hq/00-META/process/00-overview.md

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, 0081). 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	Research	An idea worth investigating before committing to design
02	Graduation & design change	Research concludes, or a design must change
03	Issues	Something is wrong — often with the owner unknown
04	Build handoff	A design is ready to be built
05	Constitution sync	how-we-build.md changed a rule the mesh enforces
06	Writing a module	Something that runs today must run on the mesh
07	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 refuses a to-be design that names no decision, an in-progress/implemented design that names no owning code, two issue folders sharing a number or an issue report carrying a status key, and a graduated research overview that does not say what it became. Run it with records.py, index.py and words.py before any HQ merge (sh merge-check.sh runs all four). The issue rules the check once held — located with an owner, resolved with a fix, a core issue with its replay — are refused at the write by the issue tracker's move (ADR 0275). What the checks cannot see — that code work actually started from a handoff — is held by playbooks 04 and 07: a feature branch exists because a design or an issue sent it.

Status lives in frontmatter, an issue's in the tracker

Research overviews, design docs and decision records each carry their status as YAML frontmatter (schemas in the section READMEs and playbooks). An issue's status lives in the issue tracker, which refuses a wrong status at the write, and its report here carries only the day it was opened (playbook 03). There are no central status files and no decision ledger. Every decision is a record in 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 (ADR 0248).