SlabUploader/docs/STRUCTURE.md

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

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, M3, 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.