jschoubben
418261213c
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: THE CHANGE ALTERS ITS OWN CHECK (merge-check.sh): main's version judged it; the change's judges the pull requests after it merges; it…
mesh/delivery superseded: a newer head of the same pull request
ADR 0290 rule 9: once the import is checked record by record, hq keeps no copy. The records and efforts are removed; every link or path to them reads "ADR NNNN" or "research NNN"; a design's decisions: lists "ADR NNNN". 02-DECISIONS keeps a pointer README with the reading order's six topics, which the knowledge base reads through the records module; 01-RESEARCH keeps a pointer README. The checks drop the rules that judged records (the knowledge base holds each at propose; checks/README.md says where) and refuse a record written here again. Playbooks 01 and 02 and the skills write and read records with the knowledge base's verbs.
87 lines
4.9 KiB
Markdown
87 lines
4.9 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,
|
|
ADR 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 ──► research ──► decision ──► 03-DESIGN/01-to-be ──► built (code repo)
|
|
│ │ │
|
|
│ │ └─► 03-DESIGN/00-as-is once shipped
|
|
│ └────► abandoned (recorded, kept)
|
|
└─(small/obvious, still a decision record)──────────► 03-DESIGN directly
|
|
|
|
research and decisions: in the knowledge base (knowledge-base.reserve, propose, ask, get, holds)
|
|
|
|
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 decision record in the knowledge base. | 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, two issue folders
|
|
sharing a number or an issue report carrying a status key; a `graduated` research effort that
|
|
does not say what it became is refused by the knowledge base's `propose` (ADR 0290). 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](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, an issue's in the tracker
|
|
|
|
Design docs carry their status as YAML frontmatter (schema in playbook [02](02-graduation.md)).
|
|
Research efforts and decision records carry theirs in the knowledge base, which refuses a wrong one at
|
|
`propose` (ADR 0290). 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](03-issues.md)). There are **no central status
|
|
files** and no decision ledger. **Every decision is a record in
|
|
the knowledge base** — 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 are generated on demand by the
|
|
`hq-status` skill and never written to disk (ADR 0248); the decisions of a topic are
|
|
`knowledge-base.holds` with that topic.
|