CONTACT 01 · UNTRACKED
Merged blind
A huge diff lands, review attention is finite, and nobody can say what the change actually touched or which documented contract it crossed.
OPEN SOURCE · APACHE-2.0 · NODE >= 18
Change control for AI‑made changes.
Docs as code, kept true by a deterministic, git-native gate. Every source file has an owning doc, every exported symbol is fingerprinted, drift surfaces as a finding instead of a surprise, and the same registry hands your agent the smallest grounded context for the task. No AI on the verdict path.
The demo is a 30-second click-through on a throwaway repo. Prefer to watch it run for real: npx codument demo --live
Replay of one recorded codument session beside its live codument watch panel, covering the whole loop across three episodes. Episode one: the user asks for token rotation in plain words, the agent pulls the feature's context pack from the registry, grills with one question, writes the plan, and the plan adversary raises one grounded objection which the user adjudicates at the approval gate; autopilot implements while the watch verdict flips to at-risk, and codument review --strict blocks the commit naming the moved symbol rotateToken and its unmoved doc until the doc is updated. Episode two: capping the session TTL touches a declared security risk, so review --require-review demands an adversarial review; its finding's named test re-runs red on the gate's live re-run and the block holds until the fix turns it green. Episode three: the wallet feature wakes as a dependent, its doc is updated, and the contract-neutral auth move is acknowledged per symbol. Three commits land authored as the user and the verdict returns to clean. Every terminal line is replayed verbatim from the committed recording; the user types only chat, and every codument command is run by the agent.
MODE 01//SCAN · THE PROBLEM
Sweeping changes, zero telemetry.
Coding agents produce sweeping changes fast, and teams merge them blind. The failure mode is quiet. Nothing crashes; the ground truth just erodes.
CONTACT 02 · DRIFT
Docs go stale in silence
The code moves; the doc that described it does not. Every stale paragraph quietly misleads the next agent session and the next human reader.
CONTACT 03 · COST
Spend is invisible
Nobody can say what the work cost. Token usage vanishes into session logs instead of mapping back to the features it actually built.
SYSTEM//THREE PARTS · ONE SPINE
Three systems, wired through one registry.
codument is three parts working together. They share a single spine, so what the agent writes is exactly what the checks measure and the gates attack.
PART 01 · WORKFLOW
A delivery workflow your agent runs
grill→plan→approve→implement→verify→document→review→commit
You just chat. The installed instructions route intent to the right step.
Claude Code native · Codex portable · any AGENTS.md agent
PART 02 · CHECKS
Deterministic checks you run
- doctor
- doc coverage and lint
- review
- what a change touched, what went stale, per-symbol drift
- watch
- live verdict plus running cost
- audit
- replay committed history for drift
- report
- the same review as a shareable HTML page
- context
- the minimal grounded working set for a feature
- cost
- per-feature spend from captured tokens. Facts, not a bill.
The CLI finds and reports; your agent fixes.
PART 03 · GATES
Two independent adversarial gates
- plan adversary · contests the plan before code exists
- review adversary · attacks a fingerprint-bound bundle of the diff plus documented invariants
Neither gate is decorative: objections must be grounded, blocks must be proven.
docs/.registry.jsonThe spine. It maps every source file to the feature doc that owns it. The workflow writes it, the checks read it, the gates attack contracts projected from it, and codument context projects it back out as the minimal grounded working set your agent reads instead of the whole repo.
19CLI COMMANDS
15SKILLS
2ADVERSARIAL GATES
880+TESTS
THE LOOP//WHAT HAPPENS WHEN YOU TYPE
You type one sentence. This is the rest.
Scroll. The left window is the chat as you type it; the right pane is what codument does underneath at that exact moment.
YOUYOU TYPE
you › add token rotation to auth
Plain words in the chat you already have. No commands, no ceremony.
AGENTCONTEXT
⏺ run codument context --feature auth
The registry hands back the owning doc, its invariants with their tests, and the sources. On the packaged benchmark that is 1.7k tokens instead of 3.1k.
AGENTPLAN
plan written · docs/features/auth.md · 3 steps
Scope, steps, and acceptance criteria land in the feature doc and wait for your approval.
GATEPLAN ADVERSARY
1 grounded objection · cites docs/features/auth.md
An independent adversary contests the plan before code exists. It never blocks; you adjudicate.
YOUYOUR CALL
you › agreed, cap TTL in step 2. codument, run the plan
One chat line adjudicates the objection and approves the plan.
AGENTAUTOPILOT
step 1 · implement · verify · document
The agent works the approved steps and updates the mapped docs and registry inside the same step.
GATEREVIEW GATE
review --strict red · rotateToken in auth
A moved documented symbol with an unmoved doc blocks the commit until the doc updates or the move is acked.
AGENTCOMMIT
✓ step 1 committed · authored as you
One focused commit per step, no AI co-author. Verdict back to CLEAN. Next step.
YOU
STAGE 1 / 8
MODE 02//LOCK · PER-SYMBOL DRIFT
Lock-on is per symbol, not per file.
Each exported symbol's token stream is fingerprinted across two git refs. Local renames are canonicalized away, so a meaning-preserving refactor does not fire. When a documented symbol moves and its owning doc does not, only that feature wakes. The old whole-file cascade is dissolved.
codument review v1.0.0..HEADOUTPUT SHAPE · ABRIDGED
| SYMBOL | FP @ v1.0.0 | FP @ HEAD | STATUS |
|---|---|---|---|
| src/auth/session.ts::createSession | 8c41f2a | 8c41f2a | UNCHANGED |
| src/auth/session.ts::rotateToken | 5d92e07 | b31c9ae | ▲ MOVEDwoke docs/features/auth-session.md |
| src/auth/cookies.ts::parseCookie | 77a01bc | 77a01bc | UNCHANGED |
| src/auth/hash.ts::hashState | e30d112 | e30d112 | UNCHANGEDlocals renamed, canonicalized away |
CANONICAL, THEN COMPARED
Local renames are normalized out of the token stream before fingerprints are compared. A refactor that preserves meaning does not fire the gate.
ONLY THE OWNER WAKES
The registry knows which feature doc owns the moved symbol. That doc wakes. Every other doc in the repo stays quiet.
ACK, DO NOT PAPER
A moved symbol that changed no contract gets an acknowledgment, not a junk mirror edit written to appease a checker.
$ codument ack src/auth/session.ts::rotateToken --reason "moved intact, contract unchanged"
# acks are fingerprint-bound · they auto-invalidate the next time the symbol moves
# acks are fingerprint-bound · they auto-invalidate the next time the symbol moves
MODE 03//VERIFY · ADVERSARIAL GATES
Verify, don't trust.
Two independent adversaries sit across the workflow. Neither one trusts the author, and neither one gets to be creative: objections must be grounded, blocks must be proven.
GATE 01 · BEFORE CODE EXISTS
Plan adversary
Contests the plan while it is still cheap to be wrong. Grounded objections only: claims it can tie to the docs, the code, and the stated scope. It never blocks. The human adjudicates every objection.
ADVISORY · HUMAN ADJUDICATES
GATE 02 · AFTER THE DIFF
Review adversary
Attacks a fingerprint-bound bundle: the diff plus the documented invariants it crosses. It blocks only when a finding's named test is genuinely red on a live re-run. No red test, no block.
BLOCKS ONLY ON A LIVE RED TEST
G1LOCAL
The checks run in your repo, against your git refs. Nothing leaves the machine.
G2NO NETWORK
No calls out, nothing phoned home. Verdicts are computed from repo state alone.
G3NO AI ON THE VERDICT PATH
Models propose and fix; they never decide. A verdict is computed, not generated.
G4SAME REPO STATE, SAME OUTPUT
Determinism you can replay in CI, or on a colleague's machine, byte for byte.
HONEST LIMITS // codument reports facts and gaps. It does not certify that a change is safe.
MODE 04//COMMIT · ZERO COMMITMENT
Start with the drift you already shipped.
No gate, no config, no workflow change. Run it read-only against your existing history and quantify the doc drift your merges left behind.
STEP 01 · MAP
Maps your source files to the docs that should own them, scaffolding the registry from what already exists.
STEP 02 · REPLAY
Replays committed history through the same per-symbol drift analysis the live gate uses, ref by ref.
Nothing gated, nothing committed. The audit reads; it never writes.
WHEN YOU WANT THE FULL INSTRUMENT
# on an existing codebase, use scan instead of init
FROM THE BLOG//FIELD NOTES
Field notes on AI-assisted engineering.
LOG 03INTERNALS
Keeping AI off the verdict path
Why a safety layer for agent output has to be deterministic all the way down, and what that rules out by design.
LOG 01PRACTICE
The diff is not the deliverable
When an agent writes the code, review stops being a courtesy and starts being the product. What a reviewer actually owes the merge.
LOG 02PRACTICE
Your agent changed 14 files. Which docs went stale?
The failure mode of AI-assisted development is quiet. Nothing crashes, the tests pass, the diff merges. And somewhere in your docs, a paragraph that used to be true just stopped being true.