jschoubben
53b94c51bb
Three records were left describing a mechanism a new record had moved, and a reader arrives at them by following a citation: 0066 still said a routed name is written into every container after 0148 replaced that with resolution; 0016 still read as though the lab were the test bed after 0149; and issues 109 and 135 said nothing about 0148 ending the copying that 135's own fix made comparable. Each was a citation leading to the wrong answer in a record that was not wrong about anything it decided. This is the second time in one session. The playbook rule I added last round did not stop it, so the convention is now written where the record conventions live, with the shape to use and three worked examples — and with the honest note that it is NOT machine-checked and cannot be from `extends:` alone: 102 records extend another, 87 have no back-reference, and that is correct, because extending usually means building on a context. Making it mechanical means a record declaring the relationship in frontmatter, which is a schema change and is not mine to decide. Also: designs 18 and 20 claimed `updated:` dates from before I edited them, and 117's `fixed-by` gained the commit beside the record.
03-DESIGN
The authoritative specification. Implementation is built against what is written here.
Two layers
| Folder | What it is |
|---|---|
00-as-is/ |
The mesh that exists today. Shipped behaviour, described as it is — including behaviour nobody would choose again. |
01-to-be/ |
The mesh being built toward. Every statement traceable to a record in 02-DECISIONS/. |
They are never mixed. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention.
When a to-be design ships, it does not move. Its as-is counterpart is written or updated,
the to-be document's status becomes implemented, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
Frontmatter
Every design document (not the READMEs) carries:
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: [] # owning code repo(s), from 00-META/repos.md
updated: YYYY-MM-DD # date of the last status change, not of text edits
decisions: [] # 02-DECISIONS/ records this document rests on
---
For an as-is document, status: implemented is the normal state — it describes something that
runs — and code: names where that implementation lives.
Status changes when implementation state changes, never because design text was edited. An
implemented claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is in-progress.
Cross-cutting views are generated from this frontmatter by the hq-status skill and never
written to disk.
What belongs here
Functional analysis, architectural description, and specification — prose and diagrams
only, no code. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in 02-DECISIONS/
and the research that produced it is closed.
Subfolders are encouraged where a layer grows enough to need them.