Deliverable hygiene
Keep the repository shaped like the artifact a human maintainer should inherit. Optimize for a clear mental model, a small useful surface, behavior-focused tests, and complete removal of obsolete paths.
Choose a mode
Use doctrine mode while adding or changing code:
- Read enough of the repository to understand its current model.
- Keep temporary reasoning and agent state outside the deliverable.
- Apply the rules in
references/doctrine.md while editing.
- Validate that the final repository is easier to understand than the starting point.
Use recovery loop mode when the repository has accumulated residue:
- Run
bin/deliverable-hygiene <repo> to collect review candidates.
- Audit concrete violations using
references/filter-rubric.md.
- Fix high-confidence findings without widening the requested scope.
- Validate from repository evidence.
- Repeat for at most three passes, then stop
GREEN, BLOCKED, or CAPPED.
Read references/workflow.md before recovery loop mode. Use references/examples.md when a classification is unclear.
Core rules
- Treat the repository as the deliverable. Keep plans, prompts, review dumps, and loop state in disposable scratch space.
- Put recovery state under
.agent-work/deliverable-hygiene/<run-id>/ and ensure .agent-work/ is ignored.
- Prefer names, structure, and concise local comments over new documents.
- Preserve compatibility only when a public contract, persisted data, explicit requirement, or repository evidence makes it real.
- Keep tests that protect meaningful behavior. Rewrite or remove tests that freeze private structure.
- Add comments for intent, constraints, hazards, and external quirks that code cannot express.
Delegation
The portable role prompts in agents/ separate evidence gathering, editing, and validation:
agents/auditor.mdagents/fixer.mdagents/validator.md
Run the roles sequentially when independent subagents are unavailable. The fixer must verify the auditor's evidence, and the validator must inspect the repository rather than trust the fixer's summary.
Report
State the mode, categories fixed, files changed, checks run, final verdict, and any decision still blocked. Delete successful scratch before reporting.
1---2name: deliverable-hygiene3description: Keep or restore a codebase as a finished, human-readable work product by separating agent scratch from source, pruning excess documentation and tests, deleting obsolete compatibility paths, and validating that process residue does not leak into the deliverable. Use during implementation cleanup or when a repository has visibly drifted.4---56# Deliverable hygiene78Keep the repository shaped like the artifact a human maintainer should inherit. Optimize for a clear mental model, a small useful surface, behavior-focused tests, and complete removal of obsolete paths.910## Choose a mode1112Use **doctrine mode** while adding or changing code:13141. Read enough of the repository to understand its current model.152. Keep temporary reasoning and agent state outside the deliverable.163. Apply the rules in [`references/doctrine.md`](references/doctrine.md) while editing.174. Validate that the final repository is easier to understand than the starting point.1819Use **recovery loop mode** when the repository has accumulated residue:20211. Run `bin/deliverable-hygiene <repo>` to collect review candidates.222. Audit concrete violations using [`references/filter-rubric.md`](references/filter-rubric.md).233. Fix high-confidence findings without widening the requested scope.244. Validate from repository evidence.255. Repeat for at most three passes, then stop `GREEN`, `BLOCKED`, or `CAPPED`.2627Read [`references/workflow.md`](references/workflow.md) before recovery loop mode. Use [`references/examples.md`](references/examples.md) when a classification is unclear.2829## Core rules3031- Treat the repository as the deliverable. Keep plans, prompts, review dumps, and loop state in disposable scratch space.32- Put recovery state under `.agent-work/deliverable-hygiene/<run-id>/` and ensure `.agent-work/` is ignored.33- Prefer names, structure, and concise local comments over new documents.34- Preserve compatibility only when a public contract, persisted data, explicit requirement, or repository evidence makes it real.35- Keep tests that protect meaningful behavior. Rewrite or remove tests that freeze private structure.36- Add comments for intent, constraints, hazards, and external quirks that code cannot express.3738## Delegation3940The portable role prompts in `agents/` separate evidence gathering, editing, and validation:4142- [`agents/auditor.md`](agents/auditor.md)43- [`agents/fixer.md`](agents/fixer.md)44- [`agents/validator.md`](agents/validator.md)4546Run the roles sequentially when independent subagents are unavailable. The fixer must verify the auditor's evidence, and the validator must inspect the repository rather than trust the fixer's summary.4748## Report4950State the mode, categories fixed, files changed, checks run, final verdict, and any decision still blocked. Delete successful scratch before reporting.
batteryshark