hunk AGENTS.md

hunk agent notes

purpose

• Terminal-first diff viewer for understanding coding-agent changesets.
• Product target is "modern desktop diff tool in a terminal", not a pager-style TUI.

architecture

CLI input
  -> parse runtime + config-backed view options
  -> normalize into one Changeset / DiffFile model
  -> App shell coordinates state, layout, and review navigation
  -> pane components render review UI
  -> Pierre-backed terminal renderer draws diff rows

shared review seam

Review core serves multiple surfaces: TUI today; web, API, and agent/runtime consumers later. Do not recreate semantic review behavior in a surface:

DiffFile[] -> projectReviewDocument -> ReviewDocumentV1 -> ReviewStore
ReviewIntent + caller facts -> planReviewIntent -> ReviewAction[] -> reducer -> surface projection

• Model: src/core/review/{types,document,identity}.ts owns the ordered, JSON-safe document. File order is review/sidebar order; use key (referenced as fileKey elsewhere), contentIdentity, and sourceIdentity (cached source text additionally requires sourceAttested) — not runtime IDs or indexes — across reloads/surfaces.
• Shared derivations: geometry.ts, expansion.ts, anchors.ts, stml.ts, and contentManifest.ts own ranges, gaps, source splitting, note targets/ownership, tag roles, and parity manifests. Consume them; never re-derive those facts in a renderer.
• State: state.ts is semantic state; actions.ts transitions; reducer.ts pure/no-I/O; selectors.ts shared policies; store.ts synchronous observable storage. New cross-surface operations start as intents. Callers supply mutable-note IDs/timestamps; core derives identities.
• Surfaces/publishers: useTerminalReview.ts is the TUI adapter and reviewNoteMapping.ts is terminal-only. Rows, measurement, scrolling, layout, themes, DOM mechanics, and source I/O stay local. useHunkSessionBridge.ts publishes the current terminal session export; registration.ts builds its metadata/initial snapshot and bridge.ts receives agent commands. This broker export is not a full ReviewState mirror.
• Other consumers: Web/API consumers reuse the model, derivations, state, intents, and the producer/protocol tier. Never build a parallel protocol. Keep presentation/client-local state local; host/extension commands need explicit remote capabilities. See docs/browser-review-rebuild.md for the rollout and current boundaries.
• Conformance: test/review-conformance/ has hand-authored semantic fixtures covering every registered core, terminal, producer, broker, protocol, and extension projection. Every new semantic consumer registers its real projection and runs the whole corpus. scripts/source-boundaries.test.ts keeps the seam renderer/platform-free; its Node-debt list is shrink-only and tombstone lists append-only. A repaid seam finding deletes copies, adds a file or banned-symbol tombstone and adversarial fixture, registers consumers, and updates docs/browser-review-seam-audit.md.