# Structure contract

This file defines the shape of the `docs/` system 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/CAPTURE.md` | capability |
| `docs/PHOTOS.md` | capability |
| `docs/CREATE.md` | capability |
| `docs/CONTENT-WOO.md` | contract |
| `docs/UAT-PRACTICE.md` | practice |
| `docs/capabilities/README.md` | index |
| `docs/contracts/README.md` | index |

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.

## 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-1 | Statement of one testable requirement | shipped | frontend/src/measure/measure.test.ts |
```

- `Scope` is `shipped`, `M3`, or `later`.
- `Test` is a repo-relative path to the test that proves the requirement. Required for `shipped` and `M3`; use `—` for `later`.

## 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` paths for `shipped | M3` requirements exist on disk.
6. Requirement rows appear only in `REQUIREMENTS.md`.
7. Every ID listed in `MILESTONES.md` exists in `REQUIREMENTS.md`.

## Planned (Phase 2)

- Migrate capability docs to `docs/capabilities/` and contracts to `docs/contracts/`.
- Populate `REQUIREMENTS.md` from the `pre-simplification` tag and the current docs.
- Enforce branch-neutral language in trunk docs.
- Wire this check into CI.

## Migration plan (Phase 2)

| Current | Canonical home |
|---|---|
| `docs/CAPTURE.md` | `docs/capabilities/CAPTURE.md` |
| `docs/PHOTOS.md` | `docs/capabilities/PHOTOS.md` |
| `docs/CREATE.md` | `docs/capabilities/CREATE.md` |
| `docs/CONTENT-WOO.md` | `docs/contracts/CONTENT-WOO.md` |
| tag `OPENAPI.md` | `docs/contracts/API.md` |
| tag `DATA-MODEL.md` | `docs/contracts/DATA-MODEL.md` |
| tag `UX.md` | `docs/contracts/UX.md` |
| tag `PROMPTS.md` | `docs/contracts/PROMPTS.md` |
| tag `TEST-SPEC.md` | `docs/contracts/TEST-SPEC.md` |