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

.audit/2026-09-18-coverage-gaps.md

@@ -0,0 +1,68 @@
+# Coverage gaps — serial worklist
+
+- Date: 2026-09-18
+- Branch: `docs/clean-main`
+- Status: open worklist. Companion to `.audit/coverage/` and `tools/check_coverage.py`.
+- Rule: work one entry at a time, top to bottom. Each decision is a ruling; record it, then
+  update the matching `gap` rows in the ledger to their resolution and re-run the gate.
+
+The pilot slice (settings / auth / health) produced 12 `gap` atoms that collapse into the
+seven distinct holes below. Each is a requirement the source material carries and
+`docs/REQUIREMENTS.md` does not.
+
+## GAP-1 — test-woo failure semantics
+
+- Atoms: `tag:TEST-SPEC API-10`, `tag:OPENAPI test-woo-shape`, `prd decision-17`,
+  `tag:TEST-SPEC GC-3` (partial).
+- Hole: the PoR says `test-woo` verifies the connection and resyncs (`SETTINGS-40`), but
+  nothing defines its result shape (`ok`, `detail`), that it fails closed on missing
+  credentials or non-HTTPS, or how an auth rejection differs from an unreachable store.
+- Proposed home: `SETTINGS`.
+- Status: open.
+
+## GAP-2 — health endpoint semantics
+
+- Atoms: `tag:TEST-SPEC H-1`, `tag:TEST-SPEC INS-1`, `tag:OPENAPI health`, `issue:#6`.
+- Hole: `APP-30` names `/api/health`; nothing defines the body (`status`, `version`,
+  `woo_reachable`) or that health goes non-200 on DB/volume failure.
+- Proposed home: `APP`.
+- Status: open.
+
+## GAP-3 — PUT /settings rejects a WOO_BASE_URL write
+
+- Atoms: `tag:TEST-SPEC GC-4`, `tag:OPENAPI settings-PUT-reject`.
+- Hole: `SETTINGS-5` makes the URL env-only and read-only, but nothing requires the settings
+  API to refuse an attempt to write it.
+- Proposed home: `SETTINGS`.
+- Status: open.
+
+## GAP-4 — AES credential round-trip
+
+- Atom: `tag:TEST-SPEC AES-1` (round-trip half).
+- Hole: `SETTINGS-75` covers redaction; nothing asserts that an encrypted credential
+  decrypts back to its value.
+- Proposed home: `QUALITY` (test obligation) over `SETTINGS-20/30`.
+- Status: open.
+
+## GAP-5 — upstream HTTP errors mapped to the envelope
+
+- Atom: `tag:TEST-SPEC FUND-21`.
+- Hole: publish field errors are mapped; there is no general rule that a 401/400/404 from
+  Woo is turned into the uniform envelope rather than passed through.
+- Proposed home: `APP` (alongside `APP-35`).
+- Status: open.
+
+## GAP-6 — no app-level auth
+
+- Atom: `prd no-app-auth`.
+- Hole: no row states that the app has no login of its own and relies on network plus HTTPS.
+- Proposed home: `OPS`.
+- Status: open.
+
+## GAP-7 — httpx timeout values
+
+- Atom: `cur:CONTENT-WOO httpx-timeouts`.
+- Hole: connect 10s / read 60s exist only in the contract draft.
+- Proposed home: contract detail, not a requirement: record in `docs/contracts/` in step 3
+  and mark the ledger atom `dropped` with rationale.
+- Status: open.