jschoubben
418261213c
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/delivery superseded: a newer head of the same pull request
ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy. The records and efforts are removed; every link or path to them reads "ADR NNNN" or "research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer README with the reading order's six topics, which the knowledge base reads through the records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that judged records (the knowledge base holds each at propose; checks/README.md says where) and refuse a record written here again. Playbooks 01 and 02 and the skills write and read records with the knowledge base's verbs.
52 lines
2.2 KiB
Markdown
52 lines
2.2 KiB
Markdown
# 03-DESIGN
|
|
|
|
The authoritative specification. Implementation is built against what is written here.
|
|
|
|
## Two layers
|
|
|
|
| Folder | What it is |
|
|
|---|---|
|
|
| [`00-as-is/`](00-as-is/) | **The mesh that exists today.** Shipped behaviour, described as it is — including behaviour nobody would choose again. |
|
|
| [`01-to-be/`](01-to-be/) | **The mesh being built toward.** Every statement traceable to a decision record in the knowledge base (ADR 0290). |
|
|
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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: [] # the decision records this document rests on, each "ADR NNNN"
|
|
---
|
|
```
|
|
|
|
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 the knowledge base
|
|
and the research that produced it is closed.
|
|
|
|
Subfolders are encouraged where a layer grows enough to need them.
|