From bd3324dc36a6568a0ab06d6843f88e444b528e5a Mon Sep 17 00:00:00 2001 From: Adron Hall Date: Mon, 14 Sep 2026 09:08:08 -0700 Subject: [PATCH] docs: consolidate onto one master doc, verify the auth column, archive the build log MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `work-consolidation.md` becomes THE single source of truth. Epic #66 restated its §1/§2/§3 as a second backlog and both drifted: between 2026-09-07 and 2026-09-13 seven PRs (#67-#73) shipped without either moving, leaving the doc ~330 tests and two API re-measures behind the code and six shipped issues listed as open. The duplication is now cut in one direction. The doc owns the plan (ordering, probe evidence, API shapes, the re-measure log, release path) and a new §1f work index mapping every item to its issue. Issues own execution. #66 is a pointer. Anti-drift: a PR that ships a G-item, closes a parity issue, or moves the test baseline must update the doc IN THAT PR. Added to the doc-quality checklist, the PR template, CLAUDE.md and the doc itself. A doc updated only in dedicated docs passes will always drift; one updated by the PR that invalidates it cannot. Live re-measure (232 paths / 303 operations, up from 226/294) overturned two standing conclusions, both confirmed by read-only probe rather than by reading the spec: - Session-only operations fell 45 -> 32, and 28 of the 32 are admin / architecture / Stripe routes a native client should never call. Four actually constrain us: auth/accounts, auth/switch, auth/remove-account (#60) and send-verification-email. - The Dashboard is no longer backend-blocked. Both layout routes, engagement and all five widget routes now answer 200 under Bearer, so #61 is a product decision only. The invite/share claim routes moved to sync-token too, which makes PR #70's "genuinely out of reach" note on document-invite accept stale. Controls probed the other way (auth/accounts and send-verification-email both 401) confirm the four that remain really are session-only -- which also settles the contradiction inside the unmerged fix/account-status-gating branch in EmailVerification.swift's favour. docs/api-coverage.md: the Auth column is now derived from the live spec's x-auth-type rather than hand-written -- 168 of 191 rows rewritten, retiring the ~50 reading "per OpenAPI, unverified". Bearer vs Session-only makes "not built" and "not buildable" distinguishable per row. Eleven rows carried a method or path the live spec does not serve; six were the §1c verb defects, where the matrix still documented the broken verbs the client stopped sending in PR #24 -- it was behind the code, not ahead of it. Two speculative rows were disproved and scored. Implemented/Tested were deliberately NOT re-scored: footnote 14's rule needs a per-row semantic check (builder AND DTO AND service call path), and a mechanical flip would manufacture exactly the unverified-but-confident marks that footnote exists to prevent. Queued as its own pass, with the evidence in footnote 16. Also fixed: the Decision 0003 gate command was unanchored and matched prose comments, reporting four false positives while the rule genuinely passed. Harvested from docs/parity-refresh-2026-09 before retiring it: the AI provisioning correction (AI is included in the subscription -- no user API key; an empty providers[] is a site outage, not something the user can fix) and the article_series ~4-minute 502 timing, which implicates a server-side retry loop. G15-G20 are marked shipped; they had been left unmarked since PRs #25/#30/#31. New gap found by the re-measure and filed as #81: saved list views -- five live, free-tier, Bearer-reachable operations (shared + personal views, forking, defaults) that no issue or prior sweep mentions. config is an unspecified string, so it must be probed before modelling. docs/progress.md is archived to docs/archive/ with a stub left at the original path so the read-only decision records keep resolving. The doc-quality "shipped-only rule" pointed at that file as its authority and now points at the master doc. Dead PLAN.md / ORCHESTRATION.md links (both deleted in f040954) are retired from README and the checklist. Gate: BUILD SUCCEEDED; Kit 478 / Domain 946 / Persistence 140 / App 954, all green. One App-target run reported 1 failure that did not reproduce in three re-runs on a documentation-only change; filed as #82 with the evidence, since PR #73 saw the same pattern. Refs #65, #66, #61, #39, #81, #82 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016gSWb3scYobtxLJioV1qF9 --- .claude/agents/doc-engineer.md | 2 +- .../assets/docs-quality-checklist.md | 7 +- .../assets/e2e-gate-checklist.md | 11 +- .github/pull_request_template.md | 2 +- CLAUDE.md | 15 +- README.md | 12 +- docs/api-coverage.md | 429 +++++---- docs/archive/progress.md | 810 +++++++++++++++++ docs/progress.md | 818 +----------------- docs/spikes/ai-materialize-live-shapes.md | 8 +- docs/user/feature-status.md | 2 +- work-consolidation.md | 180 +++- 12 files changed, 1288 insertions(+), 1008 deletions(-) create mode 100644 docs/archive/progress.md diff --git a/.claude/agents/doc-engineer.md b/.claude/agents/doc-engineer.md index c003c87..d42ab38 100644 --- a/.claude/agents/doc-engineer.md +++ b/.claude/agents/doc-engineer.md @@ -13,7 +13,7 @@ Documentation claims are code claims; verify them. Before reporting done you **m The gates that bite: -- **Shipped-only.** Every behavior claim is cross-checked against `docs/progress.md`; planned features are labeled "coming in a future update." +- **Shipped-only.** Every behavior claim is cross-checked against the Status snapshot and shipped scoreboard in `work-consolidation.md` (the single source of truth since 2026-09-14); planned features are labeled "coming in a future update." The old `docs/progress.md` is archived and must not be cited as current. - **Help Book ↔ `docs/user/` parity.** Regenerate `InterlinedList.helpindex` with `hiutil` after any HTML change (document the manual step if `hiutil` is unavailable — never fake the index). - **No `