Skip to content
Canonical

DR-101: initiative records are canonical; the initiatives tree is link-free documentation

DR-101: initiative records are canonical; the initiatives tree is link-free documentation

Section titled “DR-101: initiative records are canonical; the initiatives tree is link-free documentation”

Context

Section titled “Context”

Two stores both plausibly “are” an initiative: the numbered records at src/content/docs/ledgers/initiatives/<N>.md and the theme-doc tree at src/content/docs/initiatives/<tree>/. DR-078 governs only the substrate_doc key (optional, must resolve from the docs-site root) and never ruled which store is the record — the id-340 mint-vs-reuse procedure could not land while that was open (OQ-A/OQ-B). Measured in the S502 audit: 109 tree docs, only 4 named by any record’s substrate_doc; a pointer-gated access model would make 105 docs non-conforming.

Decision

Section titled “Decision”

ledgers/initiatives/<N>.md is THE canonical initiative record: the only home of task placement (## Projects → Linked tasks:), the only place placement is written, what /start-session §2c reads and /handoff Step 1c writes back. Minting an initiative = writing <max+1>.md there. initiatives/<tree>/ is published theme documentation: it carries no task links, and a tree doc needs NO substrate_doc pointer to be correctly filed — it is reached via the Starlight nav and cross-references. substrate_doc remains the optional depth pointer exactly as DR-078 rules (amended, not superseded).

Alternatives Considered

Section titled “Alternatives Considered”

Tree-canonical (records demoted to an index) — rejected: requires pointer discipline over 109 docs, condemns 96% of the directory as mis-filed, and breaks the numbered-record minting rule the ladder depends on.

Consequences

Section titled “Consequences”

Unblocks the id-340 ladder hook edits (H1–H5). A placement is always TWO edits — initiative: on the task file AND the id appended to the project’s Linked tasks: line; one without the other is the known failure mode. Owner-ruled S503 (OQ-A + OQ-B, tasks/id-340.md).