122 lines
6.3 KiB
Markdown
122 lines
6.3 KiB
Markdown
# Structure contract
|
|
|
|
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.
|
|
|
|
## Artifact registry
|
|
|
|
Every Markdown file under `docs/` is registered here. `docs/archive/**` and `docs/_templates/**` are exempt.
|
|
|
|
| Path | Role |
|
|
|---|---|
|
|
| `docs/README.md` | index |
|
|
| `docs/PRODUCT.md` | intent |
|
|
| `docs/STRUCTURE.md` | meta |
|
|
| `docs/REQUIREMENTS.md` | requirements |
|
|
| `docs/MILESTONES.md` | scope |
|
|
| `docs/capabilities/CAPTURE.md` | capability |
|
|
| `docs/capabilities/PHOTOS.md` | capability |
|
|
| `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 |
|
|
| `docs/contracts/API.md` | contract |
|
|
| `docs/contracts/DATA-MODEL.md` | contract |
|
|
| `docs/contracts/PROMPTS.md` | contract |
|
|
| `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 |
|
|
| `.planning/milestones/v0.5/M4/goals.md` | roadmap |
|
|
| `.planning/milestones/v0.5/M4/tasks.md` | breakdown |
|
|
|
|
Roles:
|
|
|
|
- **index** — navigation only.
|
|
- **intent** — why and what; not testable requirements.
|
|
- **meta** — this contract.
|
|
- **requirements** — the only normative text.
|
|
- **scope** — milestone-to-ID mapping.
|
|
- **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
|
|
|
|
Namespaces are **owner jobs, not technology layers**. A requirement belongs to the job it serves, and each namespace owns that job's screen, rules, server behavior, and data. There is no separate API, data, or UX layer to fight over.
|
|
|
|
All requirement text lives only in `docs/REQUIREMENTS.md`. This table assigns the home and prefix.
|
|
|
|
| Prefix | The owner is... | Covers |
|
|
|---|---|---|
|
|
| `CAPTURE` | capturing ecommerce-ready pics | photo intake, pick calibration/dimension photo, BG removal, crop, axis, length/width, calculations, inventory PNG, dimension overlay, lineup |
|
|
| `METADATA` | building the listing | wood attributes and tags, title, short/deep description, via up to 2 inference calls |
|
|
| `REVIEW` | reviewing and correcting | confidence display, field gating, tweaks, per-slab price suggestion and override, ready gate |
|
|
| `PUBLISH` | submitting to the store | WooCommerce create, draft/live, duplicate SKU, cleanup |
|
|
| `SETTINGS` | configuring before the session | Woo connection, inference config, species `$/bdft` rates, brand/geo |
|
|
| `APP` | (foundation, not a job) | device draft, slab status, resume, server seams, secret handling |
|
|
| `OPS` | (foundation, not a job) | deploy, hosts, release, UAT |
|
|
| `QUALITY` | (foundation, not a job) | test obligations, vectors, anti-metrics |
|
|
|
|
Price has two homes by design: the species `$/bdft` rates are configured in `SETTINGS`; the per-slab suggestion and override live in `REVIEW`.
|
|
|
|
## Requirement format
|
|
|
|
Defined only in `docs/REQUIREMENTS.md`, as table rows:
|
|
|
|
```
|
|
| ID | Requirement | Scope | Test |
|
|
| CAPTURE-5 | Statement of one testable requirement | shipped | frontend/src/measure/measure.test.ts |
|
|
```
|
|
|
|
- `Scope` is `shipped`, a milestone scope (`M3`, `M4`, ...), or `later`.
|
|
- `Test` is a repo-relative test path, a requirement ID, or `—`. A path given for a `shipped` requirement must exist; a given ID must resolve to a defined requirement.
|
|
- IDs advance by 5 within each namespace (`5, 10, 15, ...`), resetting for each prefix. The gaps are intentional room for later insertions; never renumber to close a gap.
|
|
|
|
## How to change a requirement
|
|
|
|
- **Modify:** edit the single row in `REQUIREMENTS.md`; update `Test`; if scope changed, update `MILESTONES.md`. Do not create a doc.
|
|
- **Add:** pick the prefix and home from the namespace table; append a row; add the test. Do not create a doc.
|
|
- **New domain:** that is a structure change. Add a namespace row and a home here first, deliberately. Do not create a drive-by artifact.
|
|
|
|
Nothing outside `REQUIREMENTS.md` may define a requirement. Capability and contract docs cite IDs only.
|
|
|
|
## Enforced by `tools/check_requirements.py`
|
|
|
|
1. Every `docs/` Markdown file (except `archive/**` and `_templates/**`) is registered above.
|
|
2. Every registered file exists on disk.
|
|
3. Requirement IDs match `^[A-Z]+-\d+$`, are unique, and use a registered prefix.
|
|
4. Scope is one of `shipped | M3 | later`.
|
|
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)
|
|
|
|
Capability docs live in `docs/capabilities/` and contracts in `docs/contracts/`. The reconciliation
|
|
and migration evidence is archived under `.audit/archive/`; the coverage ledger and matrices are in
|
|
`.audit/coverage/`. Wire `check_requirements.py` into CI when a CI stage exists.
|