Why findings need a file
Audit findings used to exist only in the chat transcript. Clear the context and they were gone: no ID to reference, no status to update, nothing that noticed a serious finding was reported and never fixed.
The ledger at blueprint/context/findings.md is the durable record. It is a plain markdown file the existing skills read and write. No script, no dependency, no new command.
Entry format
One block per finding. The header line is the machine-readable contract; the prose below it is for humans.
### F-03 [P1] open - Retained auth volumes carry the run label
**File:** ops/compose.yaml:86
**Found:** 2026-07-21 by /audit (scope: current)
**Why it matters:** Cleanup selects by label and now matches the credential volumes.
**Suggested fix:** Give retained volumes a label the cleanup selector excludes.
**Resolution:**IDs are sequential (F-01, F-02, …) and never reused or renumbered while their entries live in the ledger. When work completes, resolved entries archive under a work-item prefix, so feature 12’s F-03 becomes 12/F-03 permanently. Severity reuses the audit P0-P3 scale.
Statuses
| Status | Meaning | Blocks completion (P0/P1) |
|---|---|---|
unverified |
Suspected, no confirming evidence yet | No |
open |
Confirmed, not yet repaired | Yes |
fixed |
Repaired, not yet re-reviewed | Yes |
closed |
Repaired and re-reviewed against the new code | No |
accepted |
Not fixing, by your explicit decision with a recorded reason | No |
invalid |
Re-examination proved the finding wrong, with evidence recorded | No |
fixed blocking is the deliberate part. A repair is not done when the code changes; it is done when a review has looked at the result. A fix can introduce a worse defect than the one it removed, and the only thing that catches that is a fresh look at the repaired code.
The lifecycle
| Command | Ledger behavior |
|---|---|
audit |
Appends new findings with IDs, updates re-examined entries, and closes fixed findings after re-review. The only file audit writes. |
implement |
Repairs open findings as extra reviewed steps appended to the spec, then marks them fixed. Never closed. |
fix |
/fix F-03 between work items pulls the problem from the ledger and stamps Fixes: F-03 into the spec. |
complete |
Refuses to merge while a P0 or P1 is open or fixed. Archives resolved findings with the work item, carries unresolved ones forward. |
status / doctor |
Report counts and blocking findings, and route to the right repair command. |
autopilot |
Records its audit findings in the ledger and cannot present work as ready while a P0 or P1 blocks. |
Getting past the gate without code
A gate with no escape hatch gets disabled, so there are two recorded ways past it:
accepted- deliberately not fixing. Only you can make this call, and the reason is required text that travels into the archive.invalid- re-examination proved the finding wrong. Audit sets it after a re-review with the evidence recorded, or you call it explicitly.
Both are explicit and recorded. Neither is silent, and an agent can never waive its own findings.
Where findings end up
Completion appends resolved findings (closed, accepted, invalid) to the same history archive as the work item, under blueprint/history/. The spec, its evidence, and every issue raised against it end up in one document. Unresolved lower-severity findings stay in the live ledger with their IDs, so nothing is silently dropped.
The rule that keeps reviews honest
The ledger reports status. It never defines what a review looks at. Every audit pass reviews the code fresh and then updates the ledger with what it found. Working from the open findings as a checklist, verifying only those, is exactly how a repair-introduced defect ships unnoticed.
Older installs
Projects installed before the ledger existed need nothing. The file is user-owned and invisible to the updater; audit and complete create it on first use, and doctor reports a missing or malformed ledger as a warning, never a blocker.