Source comments across kgf/ and vishwakarma/ justify their design by citing these records —
"per ADR-2", "ADR-4's no-cache decision", "ADR-7's replay promise". Measured: 35 citations
across seven ADRs. Until this directory existed they pointed at nothing a reader could open (#51).
Each record states the accepted cost, not only the choice. That is the part worth reading: several of these were decided against a reviewer's recommendation, and a decision without its price is an assertion rather than a record.
| ADR | Decision | Cited in code |
|---|---|---|
| 0001 | Build the ranker fresh from JSON rather than vendoring selection/ |
1 |
| 0002 | kgf imports nothing from vishwakarma, enforced by a subprocess test |
11 |
| 0003 | Lexical (BM25) ranking, no embeddings — scoped to ranking | — |
| 0004 | No disk cache; a warm load is cheap enough | 2 |
| 0005 | The 44-phase DAG is kgf's own authored data | 6 |
| 0006 | Role is classified by kgf, never derived from the model field |
2 |
| 0007 | Run manifests give determinism and replay | 7 |
| 0008 | Outbound HTTP for granted tools only, both sandbox flags default False | — |
| 0009 | The MCP surface is kgf's own, not a Claude Code registration | 5 |
Decisions made while hardening the tool, which the code now depends on just as heavily:
| ADR | Decision |
|---|---|
| 0010 | A rate limit must not spend a role's candidate chain |
| 0011 | Self-heal keeps the best attempt, not the last |
| 0012 | Absent evidence is not success |
| 0013 | Lifecycle chaining is a new opt-in verb, not flags on run_task |
| 0014 | Adaptive routing seeds the starting candidate, it never reorders the chain |
rules/11-documentation-files.md §6 exempts docs/ from root-file governance, which is why these
live here rather than at the root.