jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
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 `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/`](../02-DECISIONS/)
|
|
and the research that produced it is closed.
|
|
|
|
Subfolders are encouraged where a layer grows enough to need them.
|