Repository navigation
Derived lists ADR: never hand-maintain a list the disk can generate #1291
Description
Important
Problem — Hand-maintained lists that the disk can already generate drift silently: the agent-context skill index is belief, not registration — a skill can be renamed, moved, or added on disk while the index still names the old world, and sessions trust the index. The derived-lists rule was named in the skill-health campaign ("never hand-maintain a list the disk can generate") and is treated as doctrine in practice, but it is not yet an architectural decision of record — implementers keep re-inventing the tradeoff.
Approach — Write the ADR: derived lists are the default wherever a list is a pure function of on-disk state (skill indexes, capability surfaces, reference inventories). The ADR states the rule, the generation contract (deterministic, idempotent, generation-stamped so staleness is visible), the enforcement surface (lint refuses a hand-edit to a generated file), and the escape hatch (an explicitly-marked hand-authored list is allowed when it is genuinely not derivable — marked, rare, and lint-checked for the mark).
Scope — in: the ADR itself, the first enforcement point (the skill index), the generation stamp convention. out: migrating every existing hand-list (each migrates when its generator lands, under this decision), the vault index generation (owned by the distillation spec's index machinery).
Assumptions — The ADR lands in the decision record location the product repo uses; one ADR covers the rule class, not per-list decisions.
Acceptance Criteria
- The ADR exists, states the rule, the generation contract, the enforcement surface, and the escape hatch — decision-complete
- The skill index (the motivating case) becomes generated: same disk state → same bytes, with a generation stamp
- The lint refuses a hand-edit to a file carrying a generated marker, with the marker convention documented in the ADR
- At least one genuinely-not-derivable list is migrated or marked per the escape hatch, proving the hatch works and is rare
- The skill-health campaign's derived-lists open decision is closed by this ADR (referenced from its ledger)
Testing Decisions
The generator is a pure function with idempotence/determinism tests; the lint extension covers the marker refusal. No new suites.
Key Decisions
- Generated-by-default, hand-authored-by-exception-with-a-mark: the mark is the enforcement seam, not trust.
- Generation stamps make staleness visible (consistent with the freshness receipts and the memo-table design).
- The ADR closes the recorded open decision; supersession requires a superseding ADR, as usual.
Constraints & Invariants
- A generated file is never hand-edited; the lint is the guard.
- A hand-authored list must carry its mark, or it is a violation, not a grandfather.
Prior Art
- The skill-health campaign ledger (the rule's origin, the open decision), the pinned-staging row (the same receipt-and-ref discipline on the ops side), the distillation spec's index machinery (the vault-plane instance of the same rule), the splice fix precedent (the frozen index that was replaced by a live derivation).
Notes
Small by build, large by blast radius: it is the rule that keeps every future list honest without a new review burden. Deliberately a chore-grade decision record, not a framework.
Activity
fix(app): the never-blank stack — outlet net, panel holds, durable mi…