README
¶
diffrat
Capture the why behind code changes, store it in git-adjacent records, and make it queryable by humans and agents ("why is this code the way it is?").
The invariant: on an enforced branch, every changed line carries
rationale — an answer, an exemption, or an explicit debt record. A
pre-push hook gates on it; diffrat show answers from it later.
Install
go install github.com/cameron-mcateer/diff-rationale/cmd/diffrat@latest
The only runtime dependency is git. Prebuilt binaries for Linux, macOS, and Windows are on the releases page.
The VS Code extension (diffrat-<version>.vsix) is attached to each
release;
install it with Extensions: Install from VSIX… or
code --install-extension diffrat-<version>.vsix.
Try it
cd <your-repo>
diffrat init # writes .rationale/ schema+config (commit those),
# mints the epoch, installs this clone's pre-push hook
# ...make a change, commit it...
diffrat check # shows what still needs rationale
diffrat interview # answer; records land on refs/rationale/records
diffrat show path.go:42 # ask why later
On any other clone: diffrat install for the hook, diffrat sync for the
store — records live on their own ref, which the CLI moves itself, so
nothing comes down on git clone.
Or stage the rationale without a prompt — the path an in-session agent takes while it is still making the change:
diffrat add src/cache.go:41-58,L15-33 \
-m motivation "why this change" -m alternatives "what was rejected" \
--author "Agent Name <agent@example.com>"
# ...`add` prints the lines still uncovered; repeat until none...
git commit -am "..."
diffrat mint # refuses unless every changed line is covered
Working with a coding agent
agents.md is a drop-in brief for LLM coding agents: paste it
into your agent instructions and the agent stages rationale for its own
changes with diffrat add as it works, then diffrat mint after the
commit.
Documentation
The full manual is in docs/ — workflow guides (adopting, the daily loop, feature branches, backfilling history, hotfix debt, enforcement) and one reference page per command. Every example there is real, generated output from the released binary.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
diffrat
command
Command diffrat captures the "why" behind code changes via interviews at push time and makes the resulting records queryable.
|
Command diffrat captures the "why" behind code changes via interviews at push time and makes the resulting records queryable. |
|
internal
|
|
|
coverage
Package coverage owns the invariant (design §1): coverage over changed lines, two-sided (added lines on head, deleted lines on base), computed with pinned diff settings.
|
Package coverage owns the invariant (design §1): coverage over changed lines, two-sided (added lines on head, deleted lines on base), computed with pinned diff settings. |
|
fsck
Package fsck is the store verification pass (design §9, window-manifest-format.md §7): it validates the records ref against git's chain rather than the store maintaining any chain of its own.
|
Package fsck is the store verification pass (design §9, window-manifest-format.md §7): it validates the records ref against git's chain rather than the store maintaining any chain of its own. |
|
gc
Package gc selects abandoned pre-mint capture state for deletion (design §6, journal-ref GC).
|
Package gc selects abandoned pre-mint capture state for deletion (design §6, journal-ref GC). |
|
gitx
Package gitx is the git facade (design §14, Implementation engine): all git access in the codebase routes through this package, implemented as git plumbing via child processes.
|
Package gitx is the git facade (design §14, Implementation engine): all git access in the codebase routes through this package, implemented as git plumbing via child processes. |
|
interview
Package interview is the channel-agnostic engine (design §2, §5): a stateless function of (diff, prior answers) → next question | completed answers.
|
Package interview is the channel-agnostic engine (design §2, §5): a stateless function of (diff, prior answers) → next question | completed answers. |
|
journal
Package journal is the mutable per-branch working state during a change's lifetime (design §6): which changed lines of the current net diff are covered by which answers.
|
Package journal is the mutable per-branch working state during a change's lifetime (design §6): which changed lines of the current net diff are covered by which answers. |
|
manifest
Package manifest defines the per-window frozen fact (window-manifest-format.md): what changed in one landing window, enumerated as units, as observed by the mint that wrote it.
|
Package manifest defines the per-window frozen fact (window-manifest-format.md): what changed in one landing window, enumerated as units, as observed by the mint that wrote it. |
|
mint
Package mint turns a merged journal into immutable records (design §6): run exactly once per landing on an enforced branch, when SHAs stabilize.
|
Package mint turns a merged journal into immutable records (design §6): run exactly once per landing on an enforced branch, when SHAs stabilize. |
|
pending
Package pending holds records written toward a window that has not been minted yet (§7): mutable, local, resettable dev state under .git/rationale/pending/, deliberately not a ref — refsync never sees it and enforcement never reads it.
|
Package pending holds records written toward a window that has not been minted yet (§7): mutable, local, resettable dev state under .git/rationale/pending/, deliberately not a ref — refsync never sees it and enforcement never reads it. |
|
query
Package query is the read path (design §11): scope overlap as the primary join, with line-range history traversal (git log -L) as the join primitive.
|
Package query is the read path (design §11): scope overlap as the primary join, with line-range history traversal (git log -L) as the join primitive. |
|
record
Package record defines the envelope schema (design §3) and record serialization.
|
Package record defines the envelope schema (design §3) and record serialization. |
|
refsync
Package refsync moves the tool's own refs — refs/rationale/records and refs/rationale/journal/* — between this clone and the remote (design §6, §9).
|
Package refsync moves the tool's own refs — refs/rationale/records and refs/rationale/journal/* — between this clone and the remote (design §6, §9). |
|
teamschema
Package teamschema reads the team-owned files under .rationale/ (design §3, §14): schema.yaml (payload field taxonomy + question templates, pinned per-record by blob SHA) and config.yaml (enforcement ladder, enforced branches, exemption patterns, journal GC, plugin commands).
|
Package teamschema reads the team-owned files under .rationale/ (design §3, §14): schema.yaml (payload field taxonomy + question templates, pinned per-record by blob SHA) and config.yaml (enforcement ladder, enforced branches, exemption patterns, journal GC, plugin commands). |
|
units
Package units computes the floor partition (design §5, design §5): one base..head diff's changed-line runs as one-sided, line-granular units.
|
Package units computes the floor partition (design §5, design §5): one base..head diff's changed-line runs as one-sided, line-granular units. |
|
pkg
|
|
|
api
Package api defines rationale's stable machine-readable surface: the --json wire format of the CLI, which is the one supported integration contract — external tools consume the serialized envelope (design §14).
|
Package api defines rationale's stable machine-readable surface: the --json wire format of the CLI, which is the one supported integration contract — external tools consume the serialized envelope (design §14). |
|
rationale
Package rationale is the facade the CLI's read commands render over: it returns the pkg/api types that --json serializes, so the wire contract is built in exactly one place.
|
Package rationale is the facade the CLI's read commands render over: it returns the pkg/api types that --json serializes, so the wire contract is built in exactly one place. |
Click to show internal directories.
Click to hide internal directories.