# 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.