Development record
2026-08-03 — iss-42 (v0.5.0 item D): CONTEXT.md's sharp-edges list gains a detector rather than only a correction, because the correction alone would have been the third one. The stale trust caveat (still calling iss-35's brief-vs-surface reconciliation "the open cross-check" months after `surface_coverage` shipped and iss-122 pinned the Direction-A crosscheck) is an instance of a class: the orientation doc grounds a live claim in a record, the record reaches a terminal state, and nothing in the workflow asks anyone to go back. `context_citation_currency` is that missing requirement made mechanical — it resolves every `iss-N`/`itd-N`/`spc-N`/`adr-N` handle in the "Live constraints / sharp edges" section against its store and blocks a citation to a terminal bucket (or, for the flat ADR store, a declared supersession or retired status). Deliberately narrow on two axes: ONE section of ONE document, because a terminal-state citation is legitimate in an evidence trail, a supersession chain, and a dated plan — history is supposed to name closed records; and terminal-state only, because a dangling handle is `record_schema`'s question and a second weaker implementation of an answered check is worse than none. Rejected: a git-diff-shaped handoff rule ("a change to a cited record must touch CONTEXT.md in the same commit"), which the ledger entry's wording suggests but which gates the wrong thing — it fires on commits that need no orientation change and stays silent on the case that actually bit us, a record moved in one branch and the caveat left standing in another. The state-based check has no such blind spot: whenever the citation is stale, the gate is red, regardless of which commit made it so. Alongside: `research/` stops contradicting its own README (five dated notes move into `notes/`, where ~25 peers already sit, with every citation followed — the itd-88 fidelity evidence trail, two DECISIONS.md evidence paths, `.abcd/rules.json`, and a plan link), the development record map's routing row names `research/`'s real children (`notes/` + `prompting/`, not the phantom `spikes/`), and two banned_tokens entries make both stalenesses non-silent on reintroduction. The dated plan and the ratified ADR that also mention `spikes/` are left untouched: they are chronological snapshots and a ratified decision, not living indexes, and rewriting them to match today would falsify the record — `development/README.md` alone is corrected because it alone claims to be current.
2026-08-03 — iss-42 (v0.5.0 item D): CONTEXT.md's sharp-edges list gains a detector rather than only a correction, because the correction alone would have been the third one. The stale trust caveat (still calling iss-35's brief-vs-surface reconciliation "the open cross-check" months after surface_coverage shipped and iss-122 pinned the Direction-A crosscheck) is an instance of a class: the orientation doc grounds a live claim in a record, the record reaches a terminal state, and nothing in the workflow asks anyone to go back. context_citation_currency is that missing requirement made mechanical — it resolves every iss-N/itd-N/spc-N/adr-N handle in the "Live constraints / sharp edges" section against its store and blocks a citation to a terminal bucket (or, for the flat ADR store, a declared supersession or retired status). Deliberately narrow on two axes: ONE section of ONE document, because a terminal-state citation is legitimate in an evidence trail, a supersession chain, and a dated plan — history is supposed to name closed records; and terminal-state only, because a dangling handle is record_schema's question and a second weaker implementation of an answered check is worse than none. Rejected: a git-diff-shaped handoff rule ("a change to a cited record must touch CONTEXT.md in the same commit"), which the ledger entry's wording suggests but which gates the wrong thing — it fires on commits that need no orientation change and stays silent on the case that actually bit us, a record moved in one branch and the caveat left standing in another. The state-based check has no such blind spot: whenever the citation is stale, the gate is red, regardless of which commit made it so. Alongside: research/ stops contradicting its own README (five dated notes move into notes/, where ~25 peers already sit, with every citation followed — the itd-88 fidelity evidence trail, two DECISIONS.md evidence paths, .abcd/rules.json, and a plan link), the development record map's routing row names research/'s real children (notes/ + prompting/, not the phantom spikes/), and two banned_tokens entries make both stalenesses non-silent on reintroduction. The dated plan and the ratified ADR that also mention spikes/ are left untouched: they are chronological snapshots and a ratified decision, not living indexes, and rewriting them to match today would falsify the record — development/README.md alone is corrected because it alone claims to be current.
Frontmatter
| id | dcn-2608030000000001 |
|---|---|
| type | decision |
| date | 2026-08-03 |
.abcd/work/decisions/dcn-2608030000000001-iss-42-v0-5-0-item-d-context-md-s.md
open on GitHub ↗ · commit history ↗
mentions4
- iss-35brief-vs-shipped-surface reconciliation: 05-internals/08-skills.md claims abcd ships zero user-facing skills and six top-level commands while 04-surfaces/README.md itself tables nine and /abcd:consult and /abcd:ingest are shipped; the shipped skills violate the brief criterion that any artefact mutation is a command, not a skill; the skills/ layout described (abcd-ahoy, commit-attribution, secrets-and-pii) is fictional vs the real consult/ and ingest/; the implemented, user-reachable abcd docs lint and abcd history verbs have no home in 04-surfaces at all; the operator-internal paragraph contradicts the commands/ directory that exists. Detector (per spec-moves-with-the-surface): a record-lint cross-check that every entry under commands/ and skills/ resolves to a brief surface row, and every brief surface row resolves to a shipped or explicitly staged surface. Acceptance corpus: each falsified claim above — the check fails on all of them today. Fix amends the criterion or the surface in one change, never silently.
- iss-42record orientation currency: CONTEXT.md is stale on the record trust caveat — its single most important orientation fact; phase-shift updates are not a required handoff step so the staleness recurs structurally; record README routing claims point at moved locations; research/ contradicts its own naming convention. Detector: a handoff checklist rule (a phase shift or trust-caveat change requires a CONTEXT.md update in the same change) plus banlist coverage for the moved routing targets. Acceptance corpus: the four instances above.
- iss-122The iss35 crosscheck's scope and depth are unpinned, so the gate is not reproducible: v0.3.0's receipt records zero findings four days ago while a full-depth run (17 brief docs, both directions, 22 checkers) returns 102 discrepancies, and the receipt's own promptHash field is the literal 'no-pinned-prompt' admission. The maintainer choosing briefDocs per run means two honest runs of the same gate can disagree by two orders of magnitude; the gate needs a pinned input manifest and depth so a PROMOTE means the same thing every release.
- itd-88Know What a Repo Can and Cannot Tell You — Before You Trust the Lifeboat