jschoubben
90e4a368dc
Decisions were the one link the cycle checks skipped, and measuring found 19 of 70 records orphaned — the credential flow and the module-runtime cluster among them, which is how a stale premise about a settled decision survived in working memory. cycle.py now refuses an accepted record nothing cites; the 19 got true homes (design frontmatter, the playbook that implements 0021, META for the process records). The overview names the practice: spec-driven development with provenance. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
78 lines
4.4 KiB
Markdown
78 lines
4.4 KiB
Markdown
# Process — overview
|
|
|
|
How work moves through HQ, and who may do what. In industry terms this is **spec-driven
|
|
development, with provenance**: the decision is the why, the design doc is the spec, `code:`
|
|
names the implementation, and the lab beds are the conformance tests — and unlike the common
|
|
form, the chain itself is checked ([ADR 0080](../../02-DECISIONS/0080-the-development-cycle-is-checked.md),
|
|
[0081](../../02-DECISIONS/0081-a-decision-nothing-cites-is-not-yet-in-the-chain.md)). Every other document in this folder is a
|
|
playbook: trigger, who runs it, steps, outputs. Engineers and agents follow the same
|
|
playbooks; agents must not act outside them.
|
|
|
|
## The audiences
|
|
|
|
| Audience | Contract |
|
|
|---|---|
|
|
| **Engineers** | Read and write everything. HQ is the single source of truth for mission, research, design, decisions and issue diagnosis. |
|
|
| **Agents** | The same rights as engineers, exercised through these playbooks. |
|
|
| **Anyone else** | This repository is public and written for them, but it is not a support channel. Nothing here identifies the mesh it describes. |
|
|
|
|
## The knowledge flow
|
|
|
|
```
|
|
idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo)
|
|
│ │ │
|
|
│ │ └─► 03-DESIGN/00-as-is once shipped
|
|
│ └────► abandoned (recorded, kept)
|
|
└─(small/obvious, still recorded in 02-DECISIONS)──────────► 03-DESIGN directly
|
|
|
|
symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment
|
|
|
|
how-we-build.md ──► constitution sync ──► knowledge base ──► injected into design meetings
|
|
```
|
|
|
|
## The two design layers
|
|
|
|
`03-DESIGN` holds two layers that are never mixed:
|
|
|
|
| Layer | What it is | Changes when |
|
|
|---|---|---|
|
|
| `00-as-is/` | The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. |
|
|
| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `02-DECISIONS/`. | A decision is taken or amended. |
|
|
|
|
A to-be document that ships does not move. Its as-is counterpart is written or updated, the
|
|
to-be document's frontmatter goes to `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.
|
|
|
|
## The playbooks
|
|
|
|
| # | Playbook | Trigger |
|
|
|---|---|---|
|
|
| [01](01-research.md) | Research | An idea worth investigating before committing to design |
|
|
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
|
|
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
|
|
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
|
|
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
|
|
| [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
|
|
| [07](07-feature-branches.md) | Feature branches across repos | Work that changes code, in one repo or several at once |
|
|
|
|
## The cycle is checked
|
|
|
|
The flow above is a rule, and a rule states how it is checked:
|
|
[`00-META/checks/cycle.py`](../checks/cycle.py) refuses a to-be design that names no
|
|
decision, an `in-progress`/`implemented` design that names no owning code, an issue marked
|
|
`located`/`fixed` with no owner or `fixed`/`resolved` with no fix, and a `graduated`
|
|
research overview that does not say what it became. Run it with `records.py` and `index.py`
|
|
before any HQ merge. What the checks cannot see — that code work actually started from a
|
|
handoff — is held by playbooks [04](04-build-handoff.md) and [07](07-feature-branches.md):
|
|
a feature branch exists because a design or an issue sent it.
|
|
|
|
## Status lives in frontmatter
|
|
|
|
Research overviews, design docs, issue reports and decision records each carry their status as
|
|
YAML frontmatter (schemas in the section READMEs and playbooks). There are **no central status
|
|
files** and no decision ledger. **Every decision is a record in
|
|
[`02-DECISIONS`](../../02-DECISIONS/)** — if it is worth recording it is worth a record, and if
|
|
it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
|
|
are generated on demand by the `hq-status` skill and never written to disk.
|