novox/hq
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

The numbering is the flow: decisions are 02, design is 03

Browse Source 
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.
This commit is contained in:
jschoubben
2026-08-23 18:05:11 +02:00
parent f05e4a0dce
commit c0b35652d0
72 changed files with 217 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+14 -10
View File
@@ -7,30 +7,34 @@ why. Implementation lives in `modules/`; the reasoning behind it lives here.
| Folder | Purpose |
|--------|---------|
| [`00-GENESIS`](00-GENESIS/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. |
| [`00-META`](00-META/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. |
| [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. |
| [`02-DESIGN`](02-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](02-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](02-DESIGN/01-to-be/) — the one being built toward. |
| [`adr`](adr/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. |
| [`02-DECISIONS`](02-DECISIONS/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. |
| [`03-DESIGN`](03-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](03-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](03-DESIGN/01-to-be/) — the one being built toward. |
| [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. |
| [`DECISIONS.md`](DECISIONS.md) | The ledger: every decision as it was taken, indexing the records and holding the ones too small to warrant one. |
**The numbering is the flow.** Research produces a decision; the decision authorises a design.
That is why decisions are `02` and design is `03` — a reader following the numbers walks the
process in the order it happens.
## The flow
```
idea ──► 01-RESEARCH ──► decision (adr/) ──► 02-DESIGN/01-to-be ──► built (code repo)
idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo)
│ │ │
│ │ └─► 02-DESIGN/00-as-is once shipped
│ │ └─► 03-DESIGN/00-as-is once shipped
│ └────► abandoned (recorded, kept)
└─(small/obvious, decision recorded in DECISIONS.md)────► 02-DESIGN directly
└─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
00-GENESIS/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions
00-META/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions
```
Implementation lives in the code repositories — see
[`00-GENESIS/repos.md`](00-GENESIS/repos.md). Every workflow is a playbook in
[`00-GENESIS/process/`](00-GENESIS/process/); agents operate through them and not outside them.
[`00-META/repos.md`](00-META/repos.md). Every workflow is a playbook in
[`00-META/process/`](00-META/process/); agents operate through them and not outside them.
## Rules
@@ -97,7 +101,7 @@ Answered separately, a repository of its own is the better home:
changes. Tying documents to a code branch means they merge on the code's schedule.
- **The reviewers are different.** A design argument is not reviewed the way an
implementation is, and it should not queue behind a build.
- **The scope is wider than one repository.** [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
- **The scope is wider than one repository.** [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the
monorepo entirely. Documentation that governs several repositories cannot live inside one
of them.