docs(structure): govern .planning/ and register the ops runbook

- docs/STRUCTURE.md: add a .planning/ registry (vision/roadmap/history/breakdown
  roles), broaden the roadmap role, add enforcement items 8-10.
- tools/check_requirements.py: scan .planning/ too - every .planning/**.md must be
  registered, registered files must exist, requirement rows rejected there.
- .planning/: PROJECT.md, ROADMAP.md, MILESTONES.md, and milestones/v0.5/M3/
  {roadmap.md,task_breakdown.md}. M3 breakdown holds only the tasks; decisions live
  in the contracts.
- docs/DEPLOYMENT.md: add the ops runbook (registered as ops).
This commit is contained in:
2026-09-19 10:12:32 -07:00
parent 90e862cfb0
commit 6435199f08
8 changed files with 234 additions and 7 deletions
+23 -2
View File
@@ -1,7 +1,7 @@
# Structure contract
This file defines the shape of the `docs/` system and how requirements enter it.
`tools/check_requirements.py` enforces it.
This file defines the shape of the `docs/` system and the `.planning/` tree, and how requirements
enter it. `tools/check_requirements.py` enforces it.
If the repo and this file disagree, fix one deliberately. Do not let them drift.
@@ -21,6 +21,7 @@ Every Markdown file under `docs/` is registered here. `docs/archive/**` and `doc
| `docs/capabilities/CREATE.md` | capability |
| `docs/contracts/CONTENT-WOO.md` | contract |
| `docs/UAT-PRACTICE.md` | practice |
| `docs/DEPLOYMENT.md` | ops |
| `docs/capabilities/README.md` | index |
| `docs/contracts/README.md` | index |
| `docs/contracts/WOO-API.md` | contract |
@@ -30,6 +31,18 @@ Every Markdown file under `docs/` is registered here. `docs/archive/**` and `doc
| `docs/contracts/UX.md` | contract |
| `docs/contracts/TEST-SPEC.md` | contract |
Every Markdown file under `.planning/` is registered here. `.planning/` holds planning artifacts
only and is **not** a second requirements home: `docs/REQUIREMENTS.md` and `docs/MILESTONES.md`
remain the point of record, and `.planning/` files cite requirement IDs without defining them.
| Path | Role |
|---|---|
| `.planning/PROJECT.md` | vision |
| `.planning/ROADMAP.md` | roadmap |
| `.planning/MILESTONES.md` | history |
| `.planning/milestones/v0.5/M3/roadmap.md` | roadmap |
| `.planning/milestones/v0.5/M3/task_breakdown.md` | breakdown |
Roles:
- **index** — navigation only.
@@ -40,6 +53,11 @@ Roles:
- **capability** — behavior and acceptance for one capability; cites IDs, does not define them.
- **contract** — cross-cutting interface detail; cites IDs, does not define them.
- **practice** — human walkthrough.
- **ops** — runbook for hosts, builds, and release; cites inventory and contracts, defines no requirements.
- **vision** — overall project vision and current state; cites IDs, defines none.
- **roadmap** — version or milestone objectives; cites IDs, defines none.
- **breakdown** — ordered task list for a version or milestone; cites IDs, defines none.
- **history** — historical log of shipped milestones; cites IDs, defines none.
## ID namespaces
@@ -90,6 +108,9 @@ Nothing outside `REQUIREMENTS.md` may define a requirement. Capability and contr
5. `Test` references resolve: a path given for a `shipped` requirement exists; an ID given resolves to a defined requirement; `—` is allowed.
6. Requirement rows appear only in `REQUIREMENTS.md`.
7. Every ID listed in `MILESTONES.md` exists in `REQUIREMENTS.md`.
8. Every `.planning/` Markdown file is registered above.
9. Every registered `.planning/` file exists on disk.
10. Requirement rows appear nowhere outside `REQUIREMENTS.md`, including `.planning/`.
## Phase 2 migration (complete)