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:
+23
-2
@@ -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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user