Review-first terminal diff viewer built for reading agent-authored changesets.
Documents a shared review seam as two ASCII data flows, then forbids re-deriving it in a renderer.
├── .changeset │ └── ├── docs │ ├── │ ├── │ ├── │ ├── │ ├── │ └── ├── packages │ └── hunk │ └── skills │ ├── hunk-extensions │ │ └── │ └── hunk-review │ └── ├── skills │ └── hunk-release │ └── ├── test │ └── ├── └──
The file, explained
Organized around one constraint: several surfaces share review semantics and none may reimplement them. Also carries a verification section that maps each kind of change to its specific test command, and a naming section defining three words.
Quoted passages are verbatim. Open one to see it in the source.
01 / Architecture as narrative
Two ASCII flows show how a diff becomes a review document and how an intent becomes a surface projection. Each stage names the module that owns it and the facts a renderer is to consume rather than recompute.
Source excerpt starting at line 49.parity manifests. Consume them; never re-derive those facts in a renderer.
02 / Ratchets
The known-violations baseline may only shrink and the tombstone lists may only grow. Paying off a violation has a defined sequence: delete the copies, add a tombstone and an adversarial fixture, register the consumers, update the audit document.
Source excerpt starting at line 104.explicit `@hunk/vcs/*` leaves. The known-violations baseline is shrink-only: fix an edge, rerun `bun run deps:baseline`, and never add to it.
03 / Verification by change type
Rendering changes take a typecheck, tests, integration, TTY smoke and one real terminal run. Interaction and scrolling changes take PTY coverage. Broker changes take the Node adapter suite. The section also states which four suites the default test command excludes.
Source excerpt starting at line 149.- `bun run test` does not include review conformance, PTY, TTY smoke, or real-Node adapter conformance under `test/session-broker-node/`. Run the dedicated command documented in
04 / House vocabulary
Header comments are written in active voice and lead with what the module does. Two phrasings are named as the ones to avoid, both of which describe the architecture's opinion of itself rather than its behavior.
Source excerpt starting at line 158.invariants. Avoid passive or self-important framing ("The one place where…", "the single source of truth for…") — name the behavior, not the architecture's opinion of itself.
05 / House vocabulary
layout for structural arrangement, geometry for aggregate spatial data, bounds for one concrete visible extent. Three definitions that settle naming for everything in that area.
06 / Generated file guards
The agent-facing skill document, the theme colors, the changelog page and the session wire fixtures are each identified as generated, with the source to edit and the command to run. One of them requires a protocol version bump and deleting the previous fixture in the same change.
Put it to work
hunk's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.
Try Modem