docs(structure): add requirements contract, job namespaces, and enforcement gate
Phase 1 scaffold for the docs consolidation: - docs/STRUCTURE.md: artifact registry, 8 owner-job ID namespaces, routing and change rules - docs/REQUIREMENTS.md, docs/MILESTONES.md: normative schema, empty pending Phase 2 port - docs/_templates/: requirement-row, capability, contract, adr - docs/capabilities/, docs/contracts/: registered homes - tools/check_requirements.py: enforces registry, IDs, and traceability - AGENTS.md: coding paused banner + structure-contract routing rule - README.md: pointers to the structure/requirements/milestones set Additive only: no doc moves, no requirement text, no CI wiring yet.
This commit is contained in:
@@ -0,0 +1,21 @@
|
||||
# Milestones
|
||||
|
||||
A milestone is an explicit subset of requirement IDs from `docs/REQUIREMENTS.md`. No prose scope here.
|
||||
|
||||
Populated in Phase 2. Until then every milestone is empty and coding is paused.
|
||||
|
||||
## M1 — Capture (shipped)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## M2 — Photos (shipped)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## M3 — Create (paused)
|
||||
|
||||
- IDs: —
|
||||
|
||||
## Later
|
||||
|
||||
- IDs: —
|
||||
@@ -0,0 +1,58 @@
|
||||
# Requirements
|
||||
|
||||
Normative source of truth. One row per requirement. Enforced by `tools/check_requirements.py`.
|
||||
|
||||
A requirement is defined here and nowhere else. Capability and contract docs cite IDs; they do not restate them.
|
||||
|
||||
Format and rules: `docs/STRUCTURE.md`.
|
||||
Scope: `shipped` | `M3` | `later`. `Test` is required for `shipped` and `M3`; use `—` for `later`.
|
||||
|
||||
Populated in Phase 2 from the `pre-simplification` tag and the current docs.
|
||||
|
||||
## CAPTURE — ecommerce-ready capture
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## METADATA — listing attributes and copy
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## REVIEW — confirm, tweak, ready
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## PUBLISH — store submission
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## SETTINGS — configured once
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## APP — device draft and state
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## OPS — deploy and release
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
|
||||
## QUALITY — verification
|
||||
|
||||
| ID | Requirement | Scope | Test |
|
||||
|---|---|---|---|
|
||||
| — | *(none yet)* | — | — |
|
||||
@@ -0,0 +1,106 @@
|
||||
# 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` |
|
||||
Vendored
+20
@@ -0,0 +1,20 @@
|
||||
<!--
|
||||
Template: decision record. One file per decision.
|
||||
Record why a choice was made when the reason is not obvious from the code or requirements.
|
||||
-->
|
||||
# ADR-<n>: <title>
|
||||
|
||||
- Date: <yyyy-mm-dd>
|
||||
- Status: `<proposed | accepted | superseded>`
|
||||
|
||||
## Context
|
||||
|
||||
<the situation and forces>
|
||||
|
||||
## Decision
|
||||
|
||||
<what was decided>
|
||||
|
||||
## Consequences
|
||||
|
||||
<what this makes easier, harder, or impossible>
|
||||
Vendored
+17
@@ -0,0 +1,17 @@
|
||||
<!--
|
||||
Template: capability doc. Home: docs/capabilities/<NAME>.md
|
||||
Behavior and acceptance only. Cite requirement IDs; never define them.
|
||||
-->
|
||||
# <Capability>
|
||||
|
||||
Status: `<shipped | in progress | planned>`
|
||||
|
||||
Cites: `<IDs from docs/REQUIREMENTS.md>`
|
||||
|
||||
## Behavior
|
||||
|
||||
<what the capability does, in plain terms>
|
||||
|
||||
## Acceptance
|
||||
|
||||
<what must be observed for this capability to be considered done, and where the evidence lives>
|
||||
Vendored
+11
@@ -0,0 +1,11 @@
|
||||
<!--
|
||||
Template: contract doc. Home: docs/contracts/<NAME>.md
|
||||
Cross-cutting interface detail. Cite requirement IDs; never define them.
|
||||
-->
|
||||
# <Contract>
|
||||
|
||||
Cites: `<IDs from docs/REQUIREMENTS.md>`
|
||||
|
||||
## <Interface detail>
|
||||
|
||||
<schemas, endpoints, prompts, screen rules — non-normative detail that supports the cited requirements>
|
||||
Vendored
+6
@@ -0,0 +1,6 @@
|
||||
<!--
|
||||
Template: one requirement row.
|
||||
Append to the correct namespace section of docs/REQUIREMENTS.md.
|
||||
Do not define this requirement anywhere else.
|
||||
-->
|
||||
| `<PREFIX>-<n>` | <one testable statement> | `<shipped|M3|later>` | `<repo-relative test path>` or `—` |
|
||||
@@ -0,0 +1,13 @@
|
||||
# Capability docs
|
||||
|
||||
One file per capability. Behavior and acceptance only.
|
||||
|
||||
Rules (`docs/STRUCTURE.md`): a capability doc **cites** requirement IDs from `docs/REQUIREMENTS.md`; it never defines or restates them.
|
||||
|
||||
Expected files (Phase 2 migration):
|
||||
|
||||
- `CAPTURE.md` — Milestone 1 Capture
|
||||
- `PHOTOS.md` — Milestone 2 Photos
|
||||
- `CREATE.md` — Milestone 3 Create
|
||||
|
||||
Template: `docs/_templates/capability.md`.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Contract docs
|
||||
|
||||
Cross-cutting interface detail shared by capabilities.
|
||||
|
||||
Rules (`docs/STRUCTURE.md`): a contract doc **cites** requirement IDs from `docs/REQUIREMENTS.md`; it never defines or restates them.
|
||||
|
||||
Expected files (Phase 2 migration):
|
||||
|
||||
- `API.md` — FastAPI HTTP contract (from tag `OPENAPI.md`)
|
||||
- `DATA-MODEL.md` — SQLite schema and status machine (from tag `DATA-MODEL.md`)
|
||||
- `UX.md` — screens, field recovery, outcomes (from tag `UX.md`)
|
||||
- `PROMPTS.md` — Call 1 / Call 2 prompt text (from tag `PROMPTS.md`)
|
||||
- `TEST-SPEC.md` — test pyramid, vectors, dishonest proxies (from tag `TEST-SPEC.md`)
|
||||
- `CONTENT-WOO.md` — listing copy and Woo payload detail (migrated from `docs/CONTENT-WOO.md`)
|
||||
|
||||
Template: `docs/_templates/contract.md`.
|
||||
Reference in New Issue
Block a user