Development record

Design-record information architecture — flat artefact-type folders

adracceptedadr-30

Context

The design record is the durable spec the build works from. It needs one canonical home per concept, or facts drift across duplicated locations and cross-references rot. A record that groups by a second axis (input vs process, durable vs working) inside its own tree double-classifies every artefact and forces a "where does this go?" judgement on every write.

The working tree already separates concerns on the durability axis: the durable record in .abcd/development/, shared working notes in .abcd/work/, and local-only ephemera in .abcd/.work.local/. A second such split inside development/ would be redundant.

Decision

The design record under .abcd/development/ is organised as flat folders by artefact type, one canonical home per concept, with a README.md map:

brief/ — the living canvas (what abcd IS) plus the bounded-context glossary/.
intents/ — press-release intents, directory-as-status (ADR-3): disciplines/ drafts/ planned/ shipped/ superseded/.
principles/ — distilled cross-cutting design principles.
decisions/ — ADRs (MADR), one canonical home, plus notes/.
roadmap/ — sequencing: phases/ + rfcs/.
plans/ — dated design/implementation plans.
research/ — investigations: notes/ + spikes/.

Two numbering schemes, by artefact nature:

ADRs use sequential NNNN (0007-title.md) — a stable, order-free cross-reference handle that never moves.
Plans, research notes, and the Tier-2 DECISIONS.md log are date-prefixed (YYYY-MM-DD-topic.md) — they are chronological artefacts read newest-first.

Issues are not a record folder: a design-significant issue graduates into intents/ or principles/; trivia lives in local .work.local/ handover notes.

User-facing documentation is separate, under docs/, organised by Diátaxis (tutorials / how-to / reference / explanation), one type per page. The CLI reference under docs/reference/cli/ is generated from the command tree and not hand-edited. The design record does not live in docs/; docs/ does not carry design rationale.

Alternatives Considered

An input/process (or durable/working) meta-grouping inside development/. Rejected: it double-classifies against the development/ ↔ work/ ↔ .work.local/ tiering that already carries that axis, and makes filing ambiguous.
Keep the inherited nesting (intents under roadmap/, a deep foundation/terminology/ tree, design notes under research/adr/, a research/phase/0/ tier). Rejected: it overloads "phase" against roadmap/phases/, buries top-level artefacts, and gives ADRs no single home.
Date-prefix ADRs too. Rejected: an ADR's value is a stable handle other documents link to; a date prefix makes the handle chronological and unstable.

Consequences

Every artefact has exactly one home; cross-references target stable paths.
ADRs keep a permanent NNNN identity even as the record is reorganised; the brief stays current-state (ADR-5) with history in git.
The four Diátaxis directories give user docs a home distinct from the record, so a page is either a learning/task/reference/understanding artefact or a design record — never a mix.

Frontmatter

id	adr-30
type	adr
status	accepted
date	2026-07-06

.abcd/development/decisions/adrs/0030-record-information-architecture.md
open on GitHub ↗ · commit history ↗

References2

adr-3Directory location is the source of truth for lifecycle staterelated
adr-5Brief is the current state; no version label, no archive directoryrelated

Referenced by6

adr-32The issue ledger is working-tier data, not authored recordrelated
adr-41Documents and ledgers never leave the user tier; a public citation requires both gatesrelated
adr-47abcdev.app is rendered from this repository alonerelated
adr-51An intent can declare its mechanism claim and its scope conditionsrelated
adr-2609021016270132The principles family is a declared record store whose entries carry typed claims, and it is read cold by statement and never by citationrelated
adr-2609231028044006Shape claims in the brief's surface chapters are derived, never hand-authoredrelated

mentions21

adr-2609151138420062The decisions log is a folder of minted records, not one appended file
dcn-26080300000000022026-08-03 — iss-42, CORRECTION to the entry immediately above and three fixes from a fresh adversarial correctness review. (1) That entry claimed two banned_tokens entries made both stalenesses "non-silent on reintroduction". The `phantom-research-spikes` half did not: its pattern was the literal string `research/spikes`, which never occurs in the prose it was meant to catch — the record map spells the row as two separate backtick spans (`notes/` ... `spikes/`), so restoring the exact original stale line left record-lint at zero blockers. The claim was written from reading the pattern instead of reproducing the defect, which is the failure the detector-first rule exists to prevent, and the lesson is that a ban's acceptance test is the original line, not the pattern's plausibility. The fix is not a wider regex: ADR-30 and the dated go-rebuild plan carry the same prose shape legitimately, and no pattern separates the living index from the two historical records without an escape they must not be edited to carry. So the row is GATED instead, per iss-38's "delete or gate, never correct and leave hand-kept" — an `index_drift` region over the row holds it to `research/`'s actual subdirectories, which catches every spelling of a phantom child AND a real child the row omits, and fails closed if the region is deleted. (2) `abcd ideate record` wrote its dated verdict record to `research/` root, making the shipped binary the standing producer of the very convention violation this item cleared out of that directory by hand; `ResearchRelDir` now points at `research/notes/`. spc-18's rationale ("killed ideas are research outcomes, and the research directory is where a future session looks") argues for the research area, not its root, and a verdict record is by spc-18's own words a dated research note — so `notes/` is where the record's convention already put it. The CLI surface test asserted the path through the constant, so it would have followed the constant anywhere; it now asserts the literal directory. (3) The rewritten trust caveat over-claimed `surface_coverage`: the rule reads `commands_dir` and `skills_dir` only, while the crosscheck manifest's Direction B enumerates five surface kinds, so the agent, hook, and CLI-verb surfaces are periodic-pass-only. A caveat whose entire job is saying how much is machine-enforced must not overstate it — the same phantom-enforcement class iss-40 flagged — and the wording now names the two surfaces the structural check actually covers.
dcn-26082000000000012026-08-20 — bughunt round 2 (branch bughunt-a/round-2): captured iss-331..iss-343 and fixed (ids 339-343 re-minted from an initial 326-330 after main concurrently took those numbers in the v0.6.1 cut)
dcn-26082000000000022026-08-20 — bughunt round 2 (branch bughunt-b/round-2): captured the round-2 records (iss-346..iss-357, with the two colliding ids re-minted as iss-358/iss-359), fixed
dcn-26082000000000082026-08-20 — Bug-hunt round 3 (hunt B), branch bughunt-b/round-3. Baseline
dcn-26082100000000012026-08-21 — Bug-hunt round 4, branch bughunt-b/round-4. Baseline (make preflight
dcn-26082200000000042026-08-22 — The abcdev.app website enters the record: adr-47 (rendered from
decompose-before-filingDecompose Before Filing
iss-9glossary output path is inconsistent: Phase 3 writes to foundation/terminology while the record uses brief/glossary and ADR-30 names that the glossary home.
iss-332.abcd/development/README.md conventions line says issues graduate into intents/ or principles/ rather than a ledger, but the repo runs on a committed issue ledger at .abcd/work/issues/ (adr-32); the map of the durable record denies the store it governs, in the file iss-42 ruled must be current
iss-333brief/05-internals/03-configuration.md's Plugin-internal development namespace tree draws the pre-adr-30 layout: roadmap/intents/{drafts,planned,shipped}, research/adr/, research/phase/, and specs/ under .abcd/ — the record's only map of its own namespace routes a reader to four paths that do not exist; the blocker moved-intents-path rule is defeated only by the ASCII art splitting the string
iss-352three current-state records cite ADRs at development/research/adr/, a path that does not exist and a layout adr-30 explicitly rejected; all three are backticked code spans links_resolve never checks
iss-353research/notes/README.md prescribes topic-kind note naming while adr-30 and development/README.md ratify date-prefixed naming and the record-lint successor plus ideate both emit dated notes; the notes README is the outlier and 29 of 41 notes are dated
iss-391research notes README routes phase-scoped research to research/phase/N/ and names research/adr/ as a sibling — both layouts adr-30 rejected and the gated research-children index denies — and its Related display texts sit one level short of their hrefs
iss-2608211146222734The retired pre-adr-30 path literal 'roadmap/intents' — a record-lint blocker token (moved-intents-path: 'intents live at intents/') — survived in AGENTS.md and .abcd/README.md, the two canonical where-things-live maps, both outside record-lint's roots (.abcd/development) so the armed token is structurally blind to them. Read in context beside the real nested path decisions/adrs, the slash reads as a path separator, i.e. the banned pre-adr-30 layout. A 2026-07-06 review already adjudicated both sites stale (fix #6). CLAUDE.md is a symlink to AGENTS.md, so the line is injected into every agent session and risks an agent propagating the banned path into development/ where it is a live blocker. Live instance of open iss-279's detector gap (banned_tokens cannot reach AGENTS.md/CONTRIBUTING.md).
iss-2609020626111484ADR owed: the principles family becomes a declared record store with typed frontmatter, a record-architecture decision on the pattern of adr-30, and the lifeboat principles contract moves with it
iss-2610262033559124The intent chapter makes the grill glossary-aware once a terminology/ directory exists; the glossary's home is .abcd/development/brief/glossary/.
itd-84An Intent Is Decomposed Before It Is Filed, And A Reversal Is Only Ever Flagged
itd-140The Generic/Specific Boundary of the Site Generator Is a Gate, Not a Hope
itd-2609020625405170A principle carries typed claims, its reference, its comparison and its evidence, its statement is readable cold, and it inherits only what held
spc-2609020626042471The knowledge record becomes a read object: A principle carries typed claims, projects its statement, and inherits only what held