docs(phase2): coverage gate, migration TODOs, session handoff
- add tools/check_coverage.py and .audit/coverage ledger (schema + settings pilot) - add coverage gap worklist and source-doc migration TODOs - add session handoff; redirect stale resume points in AGENTS.md, docs/README.md, reconciliation record - add rows: CAPTURE-41, CAPTURE-141, METADATA-66, PUBLISH-31, SETTINGS-51
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# Coverage ledger
|
||||
|
||||
Provenance for every requirement in `docs/REQUIREMENTS.md`. One row per source atom.
|
||||
Kept under `.audit/` on purpose, so it is not part of the `docs/` structure contract.
|
||||
|
||||
`tools/check_coverage.py` reads every `*.md` in this directory except this file.
|
||||
|
||||
## Row format
|
||||
|
||||
```
|
||||
| Source | Atom | Requirement | Disposition | PoR ID | Rationale |
|
||||
```
|
||||
|
||||
- **Source** — where the atom came from, prefixed by kind: `tag:TEST-SPEC`, `tag:OPENAPI`,
|
||||
`prd`, `cur:CREATE`, `issue:#5`, `audit:14`.
|
||||
- **Atom** — the stable key inside that source, e.g. `H-1`, `settings-PUT-reject`.
|
||||
- **Requirement** — a short restatement, enough to recognise it.
|
||||
- **Disposition** — one of the values below.
|
||||
- **PoR ID** — the `docs/REQUIREMENTS.md` ID(s), comma-separated. `—` when none.
|
||||
- **Rationale** — required for everything that is not plain `ported`.
|
||||
|
||||
## Dispositions
|
||||
|
||||
| Value | Meaning | PoR ID | Rationale |
|
||||
|---|---|---|---|
|
||||
| `ported` | fully represented by the cited row(s) | required | optional |
|
||||
| `duplicate` | same rule as another atom | optional | required |
|
||||
| `new` | PoR row with no source atom; a reconciliation decision | required | required |
|
||||
| `superseded` | replaced by a later source or decision | optional | required |
|
||||
| `deferred` | intentionally out of current scope | optional | required |
|
||||
| `dropped` | deliberately discarded | `—` | required |
|
||||
| `gap` | not represented, not deliberately dropped: an open hole | `—` | required |
|
||||
|
||||
`gap` is the finding. It is the thing this ledger exists to surface.
|
||||
|
||||
## Checks
|
||||
|
||||
Forward (always):
|
||||
|
||||
1. Every row has six well-formed columns and a known disposition.
|
||||
2. A `(Source, Atom)` pair is unique across the ledger.
|
||||
3. `ported` and `new` cite at least one defined requirement ID; every cited ID resolves.
|
||||
4. `dropped` and `gap` carry no ID and a non-empty rationale.
|
||||
5. Every non-`ported` row carries a non-empty rationale.
|
||||
|
||||
Reverse (`--strict` only, once coverage is complete):
|
||||
|
||||
6. Every ID in `docs/REQUIREMENTS.md` is claimed by at least one atom, or is `new`.
|
||||
7. No `gap` rows remain.
|
||||
|
||||
## Run
|
||||
|
||||
```
|
||||
python tools/check_coverage.py
|
||||
python tools/check_coverage.py --strict
|
||||
python tools/check_coverage.py --ledger-dir <path> # for negative tests
|
||||
```
|
||||
@@ -0,0 +1,47 @@
|
||||
# Coverage ledger — settings / auth / health (pilot)
|
||||
|
||||
Seed slice proving the method. Sources: the `pre-simplification` tag, the archived PRD,
|
||||
the current branch docs, and the Gitea issues.
|
||||
|
||||
| Source | Atom | Requirement | Disposition | PoR ID | Rationale |
|
||||
|---|---|---|---|---|---|
|
||||
| tag:TEST-SPEC | GC-1 | SLAB-UAT-* creates a Woo draft regardless of woo_create_status | ported | PUBLISH-10 | — |
|
||||
| tag:TEST-SPEC | GC-2 | duplicate SKU returns 409 with edit_sku and open_existing | ported | PUBLISH-15 | — |
|
||||
| tag:TEST-SPEC | GC-3 | test-woo returns ok with taxonomy and always resyncs on success | ported | SETTINGS-40 | — |
|
||||
| tag:TEST-SPEC | GC-4 | WOO_BASE_URL compose-only, GET read-only, PUT rejects a write with 422 | gap | — | compose-only and read-only live in SETTINGS-5; the API-level 422 rejection has no row |
|
||||
| tag:TEST-SPEC | GC-5 | FastAPI refuses to start on missing or http WOO_BASE_URL | ported | SETTINGS-10 | — |
|
||||
| tag:TEST-SPEC | W-3 | taxonomy anchor unchanged on no-op, bumps only on stored-subset hash change | ported | SETTINGS-55 | sync and rebuild live in SETTINGS-50 |
|
||||
| tag:TEST-SPEC | W-4 | test-woo always runs a taxonomy resync after a successful test | duplicate | SETTINGS-40 | same rule as GC-3 |
|
||||
| tag:TEST-SPEC | AES-1 | credential encrypt/decrypt round-trips; ciphertext never appears in GET | gap | — | redaction lives in SETTINGS-75; the round-trip assertion has no row |
|
||||
| tag:TEST-SPEC | AES-2 | missing SLAB_AES_KEY refuses startup, no plaintext fallback | ported | SETTINGS-25 | — |
|
||||
| tag:TEST-SPEC | API-10 | test-woo fails closed on missing credentials or non-HTTPS URL | gap | — | no row defines test-woo's failure behavior |
|
||||
| tag:TEST-SPEC | FUND-21 | 401/400/404 mapped to an actionable error, not raw passthrough | gap | — | publish fields are mapped by PUBLISH-20 and PUBLISH-35; the settings handshake mapping is absent |
|
||||
| tag:TEST-SPEC | H-1 | health 200 with woo_reachable false when credentials are not configured | gap | — | APP-30 names /api/health only |
|
||||
| tag:TEST-SPEC | INS-1 | health non-200 on DB or volume failure; woo_reachable false when the store is unreachable | gap | — | not represented |
|
||||
| tag:TEST-SPEC | UIE-8 | Settings screen: WP creds and test-woo, inference and test, pricing, brand/GEO, create status, read-only URL | ported | SETTINGS-5, SETTINGS-15, SETTINGS-20, SETTINGS-30, SETTINGS-35, SETTINGS-65 | screen composition itself belongs to the contract/UX docs |
|
||||
| tag:TEST-SPEC | OPS-3 | compose health, test-woo ok, create status draft at deploy | ported | QUALITY-110 | — |
|
||||
| tag:OPENAPI | health | GET /api/health returns status, version, woo_reachable | gap | — | APP-30 names the path; the body is absent |
|
||||
| tag:OPENAPI | settings-PUT-reject | PUT /settings cannot write woo_base_url, 422 | duplicate | — | same rule as GC-4 |
|
||||
| tag:OPENAPI | settings-secrets | secrets are write-only and never echoed | ported | SETTINGS-75 | — |
|
||||
| tag:OPENAPI | test-woo-shape | test-woo returns ok, detail, taxonomy_anchor, taxonomy_last_sync_at | gap | — | return shape absent |
|
||||
| tag:OPENAPI | taxonomy-GET | taxonomy GET grouped, with anchor and last_sync_at | ported | SETTINGS-50, SETTINGS-55, SETTINGS-60 | — |
|
||||
| tag:ARCHITECTURE | s5-server-secrets | Woo creds, inference key, AES key, WOO_BASE_URL are server-side only | ported | SETTINGS-5, SETTINGS-15, SETTINGS-20, SETTINGS-25, SETTINGS-30 | — |
|
||||
| tag:ARCHITECTURE | s5-client-prefs | sheet and sensitivity preferences persist in localStorage | ported | CAPTURE-145 | — |
|
||||
| tag:ARCHITECTURE | s7-taxonomy | last_sync_at, anchor, and sync triggers | ported | SETTINGS-50, SETTINGS-55, SETTINGS-60 | — |
|
||||
| tag:ARCHITECTURE | s3-woo-only-fastapi | Woo is called only by FastAPI | ported | APP-25 | — |
|
||||
| tag:DATA-MODEL | settings-table | settings.value_enc is AES-GCM; WOO_BASE_URL is not a settings row | ported | SETTINGS-5, SETTINGS-20, SETTINGS-30 | — |
|
||||
| tag:DEPLOYMENT | env-table | env carries WOO_BASE_URL, Woo credentials, inference key | ported | OPS-10, SETTINGS-5, SETTINGS-30 | — |
|
||||
| tag:DEPLOYMENT | rotate-creds | rotate Woo credentials then test-woo | duplicate | SETTINGS-40 | rotation is procedure; the verification is test-woo |
|
||||
| tag:DEPLOYMENT | aes-rekey | SLAB_AES_KEY change requires re-encrypting settings | deferred | — | deferred ruling, audit section 18 item 7 |
|
||||
| prd | decision-15 | Woo credentials are server-side only, never in the browser | ported | SETTINGS-15, SETTINGS-20 | — |
|
||||
| prd | decision-16 | inference endpoint is configurable: base URL, key, model | ported | SETTINGS-30 | — |
|
||||
| prd | decision-17 | test connection verifies text and vision support | gap | — | SETTINGS-45 covers the inference probe; the Woo side of test connection is only SETTINGS-40 |
|
||||
| prd | no-app-auth | no app-level auth; HTTPS plus trusted network | gap | — | no row states the absence of app-level auth |
|
||||
| prd | FR41 | Settings UI for inference, Woo creds, pricing, brand/GEO, prompts | ported | SETTINGS-15, SETTINGS-20, SETTINGS-30, SETTINGS-35 | prompts are post-M3, audit section 11 |
|
||||
| cur:CREATE | settings-url | WOO_BASE_URL from env, read-only; change means edit .env and recreate | ported | SETTINGS-5 | — |
|
||||
| cur:CREATE | test-inference-shape | test-inference returns ok, mode, vision_capable, detail | ported | SETTINGS-45 | — |
|
||||
| cur:CONTENT-WOO | httpx-timeouts | httpx connect 10s, read 60s | gap | — | not represented |
|
||||
| issue:#5 | app-password | app password, dedicated user, AES-GCM, browser never holds it, sole caller | ported | SETTINGS-15, SETTINGS-20, APP-25 | — |
|
||||
| issue:#11 | url-compose | WOO_BASE_URL declared in compose, not user-editable | ported | SETTINGS-5 | — |
|
||||
| issue:#14 | taxonomy-refresh | taxonomy refresh triggers and anchor | ported | SETTINGS-50, SETTINGS-55, SETTINGS-60 | — |
|
||||
| issue:#6 | instrument-health | health checks and instrumentation | gap | — | same hole as H-1 and INS-1 |
|
||||
Reference in New Issue
Block a user