Review-first terminal diff viewer built for reading agent-authored changesets.
Hunk has one central constraint: every interface shares the same review model, and renderers may not rebuild it themselves. The file also maps changes to test commands and defines three project terms.
├── ├── · symlink → AGENTS.md ├── .changeset │ └── ├── docs │ ├── │ ├── │ ├── │ ├── │ ├── │ └── ├── packages │ └── hunk │ └── skills │ ├── hunk-extensions │ │ └── │ └── hunk-review │ └── ├── skills │ └── hunk-release │ └── ├── test │ └── ├── └──
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, while tombstone lists may only grow. Removing a violation requires deleting copies, adding a tombstone and adversarial fixture, registering consumers, and updating the audit.
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 need type, integration, TTY, and real-terminal checks. Interaction work needs PTY coverage; broker work needs the Node adapter suite. The guide also names four suites excluded by default.
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
Four generated outputs list their source and rebuild command. Updating a session fixture also requires a protocol version bump and deletion of the previous fixture.
These instructions explain how to work in hunk. Modem shows your agents what customers said, who is affected, and what changed.
