Development record
The principles family is a declared record store whose entries carry typed claims, and it is read cold by statement and never by citation
Context
adr-30 fixed the record's families and their homes. The principles family under the durable record holds the distilled cross-cutting principles, first class and packed by the lifeboat, and it is the only family with no frontmatter, no identifiers and no entry among the stores the schema gate walks: its entries are prose files keyed by filename.
The cold-reading design makes the knowledge record a read object in Iteration 2. Principle statements are what a project carries forward and sit on the cold side; the citations back to the decisions they were distilled from are derivational, which is the material the read block excludes. The design therefore asks for a projection rule rather than a path rule, and for four things on each entry: what kind of claim it makes, what it is a claim about, what comparison produced it, and what evidence it rests on.
itd-181 shipped the scope-condition disposition so that later work inherits only what held, and its fidelity verdict found that nothing consumes a disposition: a falsified condition blocks nothing. A principle resting on an assumption that delivery falsified is exactly the inheritance the disposition exists to prevent, and the principles family is where the check belongs.
Decision
The principles family becomes a declared record store, keyed by its
filenames, with four frontmatter keys: claim_type in the design documents'
vocabulary (criterion, causal, context), with mechanism, the shipped intent
token for the causal kind, accepted on read as an alias for causal and
written back as causal, never refused with a rename; reference (the entity
the principle is about); comparison (what was compared to produce it); and
evidence (the records it distils and the scope-condition identities it
inherits). A key considered and declined is an explicit null; an absent key is
a claim not carried; the two are never collapsed.
Population is forward-only. An entry carrying none of the four keys is untyped and reported as such at warning severity, never as wrong; an entry carrying any of them carries all four or states the null, at blocking severity. Nothing backfills an existing entry, on the same rule the origin and production-mode keys follow.
A principle is read cold by its statement and never by its citations. The include table projects the statement to a reading and withholds the four keys and every citation, and the manifest asserts the exclusion; the projection is admitted at every position but the comparative.
A principle inherits only what held. The record lint reports a principle whose evidence names a scope condition dispositioned as falsified, reports one resting on a narrowed condition with the narrowing, and reports one resting on an undispositioned condition as untested.
The lifeboat's principles contract carries the four keys when it distils, under a new schema version of its principles payload, so a packed lifeboat's principles arrive typed.
Alternatives Considered
- Leave principles as prose and exclude them from readings. Keeps the family as it is and forfeits the Iteration 2 knowledge record. Rejected: the design schedules the extension and Step 9 has no other read object.
- Type existing entries by hand in the same change. Writing a comparison the author never stated is a backfill and the record's population rule forbids it. Rejected; the untyped count is information about the family's age.
- Mint identifiers for principles. Would make the family look like the others and cost every existing cross-reference its filename handle. Rejected: the slug is the identity, and the gate keys uniqueness on the rendered handle.
Consequences
- The schema gate walks one more store, with uniqueness keyed on the
rendered handle for a slug-keyed family, and the lifeboat's own
prn-derivation from decision identifiers is recorded as a different namespace that shares the grammar. - The include table gains a projection resolution for a labelled opening
paragraph, and the manifest's kind vocabulary gains
principle, which moves the manifest schema version. - The lifeboat principles payload moves to schema version 2, and the distiller agent's contract and changelog move with it.
Status note
Accepted by the maintainer on 2026-09-02, at the planning interview for the Iteration 2 intents, after each decision was checked against the design framework v4 and its readings companion v4 and found not to contradict them. Drafted as proposed and held there until that interview, because it changes the record's architecture and the lifeboat's contract, neither an agent's act.
Frontmatter
| id | adr-2609021016270132 |
|---|---|
| type | adr |
| status | accepted |
| date | 2026-09-02 |
.abcd/development/decisions/adrs/2609021016270132-the-principles-family-is-a-declared.md
open on GitHub ↗ · commit history ↗
References5
- adr-30Design-record information architecture — flat artefact-type foldersrelated
- adr-56An exclusion control asserts only what it can proverelated
- itd-177An intent's claims are typed and its scope conditions keep their identity across edits — the readiness gate refuses an intent that leaves a context claim unrecordedrelated
- itd-181A shipped intent's scope conditions are dispositioned by the fidelity verdict — what was assumed ex ante and what survived are recorded as different thingsrelated
- itd-2609020625405170A principle carries typed claims, its reference, its comparison and its evidence, its statement is readable cold, and it inherits only what heldrelated
mentions4
- dcn-26090200000000032026-09-02 — adr-2609021016272867, adr-2609021016275803, adr-2609021016270132 and adr-2609021016288378 are adopted (maintainer, at the same interview, each checked against the framework and the companion first). adr-2609021016272867: the comparative reading receives two body fields of one named widening run's items as the single exception to the prior-run exhaust, through a fourth closed operand naming the run; the maintainer chose the named operand over a derived selection because two widening runs coexist after the closing run, on the condition that an absent operand lists the runs the operator may choose from. adr-2609021016275803: per-run context stamps and a session-separation check that reports held-for-what-was-seen or unobserved, never clean; `scribe assemble` and `scribe ingest` with a ledger-only allow list derived from the ledger's directory list. adr-2609021016270132: the principles family is a declared record store with four typed keys, forward-only, read cold by statement and never by citation, with the inheritance check. adr-2609021016288378: in its three-surface form, because the single-section draft contradicted the design's two landings and adr-55's definition of the construal.
- dcn-26090200000000112026-09-02 — adr-56's third rule is refined, not contradicted, by the source-and-tests ruling (maintainer): a control that admits an input it cannot examine may pass it only with a per-item unscanned mark in its attestation, so the second rule (an attestation never says more than the examination) carries what the third rule carried; refusal stays the rule for an input the control claims to have examined and could not. Invariant 16 amended to say so. Every ADR is now checked against the framework v4 and the companion v4: adr-58 is superseded by adr-2609021016286571, adr-2609021016272867 is corrected to the derived run, and none of adr-55, adr-57, adr-2609021016275803, adr-2609021016270132, adr-2609021016288378 or adr-2609021016286571 contradicts either document. The two-hundred-thousand-token target is a clarification the documents do not speak to, kept as such.
- iss-54ADR frontmatter selectively gains three argument fields: related_principles (which standing principles the decision leans on), a confidence qualifier, and revisit_when — the rebuttal slot naming the conditions under which the decision no longer holds. The convention serves decision durability: an ADR that records only the choice invites re-litigation, while one that records its confidence and its expiry conditions tells a future session exactly when reopening is legitimate. Adopt the fields selectively per the 2026 template-comparison evidence rather than the full heavyweight argumentation set, which adds ceremony without proportionate recall value. Acceptance: new ADRs carry the three fields where they apply, and a revisit_when condition coming true is sufficient grounds to reopen without further debate.
- spc-2609020626042471The knowledge record becomes a read object: A principle carries typed claims, projects its statement, and inherits only what held