Ty
01aa4c52c3
Surface-matrix sweep of every source doc; added nine missed behaviors (METADATA-115, REVIEW-50, APP-55/60/65, SETTINGS-45 mode, Generate-text availability, defaults-off). 153 requirements, 0 coverage gaps. Migrated capabilities to docs/capabilities/ and contracts to docs/contracts/; added WOO-API, API, DATA-MODEL, PROMPTS, UX, TEST-SPEC. Populated MILESTONES; branch-neutral trunk docs; renamed umbrella term to Woo Slab Taxonomy. Archived reconciliation working records under .audit/archive/.
103 lines
5.0 KiB
Markdown
103 lines
5.0 KiB
Markdown
# Session handoff — requirements reconciliation
|
||
|
||
- Date: 2026-09-18
|
||
- Branch: `docs/clean-main`
|
||
- HEAD: `84d7681`. The last pushed tip was `1603467`.
|
||
- Working tree: clean. This session's work is committed as `84d7681`; not pushed yet.
|
||
- This file supersedes the stale "Resume here" section 0 of
|
||
`2026-09-18-reconciliation-decisions.md`.
|
||
|
||
## Read first
|
||
|
||
1. `docs/STRUCTURE.md` — structure contract, ID namespaces, the step-5 ID stride rule.
|
||
2. `docs/REQUIREMENTS.md` — the PoR. 136 requirements.
|
||
3. `.audit/2026-09-18-migration-todos.md` — deferred source-doc edits for step 3.
|
||
4. `.audit/2026-09-18-coverage-gaps.md` — the serial gap worklist (GAP-1..GAP-7).
|
||
5. `.audit/coverage/README.md` — the coverage ledger schema.
|
||
|
||
## Gates
|
||
|
||
```
|
||
python tools/check_requirements.py -> PASS, 12 docs, 8 namespaces, 136 requirements
|
||
python tools/check_coverage.py -> PASS, 40 atoms, 12 gaps, 20/136 IDs claimed
|
||
python tools/check_coverage.py --strict -> FAIL by design until coverage is complete
|
||
```
|
||
|
||
## What this session did
|
||
|
||
1. Renumbered every requirement in steps of 5 per namespace (see STRUCTURE.md). Nothing
|
||
cites IDs yet, so this was free. First IDs: `CAPTURE-5`, `METADATA-5`, etc.
|
||
2. Applied owner corrections: `PUBLISH-8` (no image cap), `METADATA-16` (template is the
|
||
fallback only), `REVIEW-8` (calculated fields are not mutable), `PUBLISH-30`
|
||
(attempt-level failure wording), `PUBLISH-35` and `PUBLISH-36/37/38` (error triage).
|
||
3. Walked `CAPTURE.md`, `PHOTOS.md`, `CREATE.md`, `CONTENT-WOO.md` section by section.
|
||
Added five rows: `CAPTURE-41`, `CAPTURE-141`, `METADATA-66`, `PUBLISH-31`,
|
||
`SETTINGS-51`.
|
||
4. Built the coverage method: `tools/check_coverage.py`, `.audit/coverage/` (schema plus a
|
||
settings/auth/health pilot ledger), and the gap worklist.
|
||
|
||
## Rulings locked this session (do not relitigate)
|
||
|
||
1. `METADATA-1`, `-2`, `-3` stay as written.
|
||
2. Audit decisions beat older specs. Title separator is the hyphen ` - `.
|
||
3. Grade is exactly 1. `fig-*` tags are optional. The Figure attribute is at least 1.
|
||
Ready set is two images; `REVIEW-5` is the PoR.
|
||
4. Tag scope is important: sync keeps only the figure and feature tag families so non-wood
|
||
Woo metadata does not pollute the workflow (`SETTINGS-51`).
|
||
5. Content-generation logging stays (`METADATA-66`), it is the trace/debug/tuning record.
|
||
6. Partial-publish orphaned media: log it, surface a manual cleanup note, no auto-delete
|
||
(`PUBLISH-31`).
|
||
7. Order of the coverage walk: current docs, then tag docs, then the archived PRD, then the
|
||
Gitea main design issues (#1–#20). TEST-SPEC is done LAST, reconciled against a finished
|
||
PoR.
|
||
|
||
## Open work
|
||
|
||
1. Continue the coverage walk doc by doc, section by section. Remaining current docs:
|
||
`PRODUCT`, `README`, `UAT-PRACTICE`. Then the tag docs, the archived PRD, the main
|
||
issues, and finally TEST-SPEC.
|
||
2. The pilot ledger `coverage/settings-auth-health.md` mixes sources. When a walked source
|
||
collides with it, split the ledger into per-source files first (this write was started
|
||
and reverted once; get explicit approval).
|
||
3. Resolve the coverage gaps in one pass, then step 3 migration
|
||
(`docs/capabilities/`, `docs/contracts/`, branch-neutral, cite IDs), then retire the
|
||
working records.
|
||
|
||
## Known gaps
|
||
|
||
1. `.audit/2026-09-18-coverage-gaps.md` has GAP-1..GAP-7, all open. GAP-1 (`test-woo`
|
||
failure semantics) and GAP-2 (health/`woo_reachable`) are the ones with the most
|
||
downstream content.
|
||
2. The coverage ledger currently reports 12 `gap` atoms from the pilot slice.
|
||
3. Still-open decisions: the `attributes` element shape on `POST /products`, and server
|
||
persistence (full CRUD vs a thinner path).
|
||
4. Discussed but unresolved: Woo credentials are stored server-side, so two phones share one
|
||
credential row and a wrong password locks both out. A "last-known-good plus auth-gated
|
||
promotion" rule was proposed; no requirement row yet.
|
||
|
||
## Process rules
|
||
|
||
1. This is planning work. Walk in plan mode (read-only); flip to build only for edits the
|
||
owner has explicitly approved.
|
||
2. No file gets created, edited, or deleted without the owner saying go for that specific
|
||
change.
|
||
3. Where a doc and the shipped code disagree, the as-built code is what the PoR documents.
|
||
4. Raw evidence for any "done": gate output, diff, or command output.
|
||
|
||
## Environment
|
||
|
||
1. Subagents `general` and `explore` are routed to the local SWIFT model
|
||
(`deepblu5090-8084/Swift-Qwen3.8-27B-Q5_K_M.gguf`) in the global config
|
||
`~/.config/opencode/opencode.jsonc`. Config loads at startup; restart after edits.
|
||
2. SWIFT is suitable for mechanical extraction only (read and list). Dispositions and
|
||
rulings stay with the owner. It never writes.
|
||
3. `.audit/docs-structure-pass.tsv` is finished history from 2026-09-09. Leave it.
|
||
|
||
## Commit
|
||
|
||
- `84d7681` — coverage gate, migration TODOs, session handoff. Working tree clean.
|
||
- Touches: `docs/REQUIREMENTS.md` (+5 rows), `docs/README.md`, `AGENTS.md`,
|
||
`.audit/2026-09-18-reconciliation-decisions.md`, and the new `.audit` files plus
|
||
`tools/check_coverage.py`.
|
||
- Not pushed to origin as of this handoff.
|