jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
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 record in [`02-DECISIONS/`](../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:
|
|
|
|
```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: [] # 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 `hal-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/`](../02-DECISIONS/)
|
|
and the research that produced it is closed.
|
|
|
|
Subfolders are encouraged where a layer grows enough to need them.
|