Sub-project 42 — Doc-Pass: Reconcile Stale Docs with SP23–SP41 Reality: Design Spec

Date: 2026-07-08 Status: Draft, awaiting user sign-off Branch: sp42-doc-pass Aesthetic direction: No new UI (docs-only increment; no code paths change).

1. Scope

Between SP23 (Ubuntu + Docker + auth + RBAC + LAN-bind product fork, merged 07a7ecb on 2026-06-23) and SP41 (in-window rebill pipeline, merged 309e6c0 on 2026-07-08), 19 increments landed on main without a corresponding documentation alignment pass. The CLAUDE.md, README.md, ARCHITECTURE.md, REQUIREMENTS.md, and the eight .superpowers/skills/*/SKILL.md files all carry stale references to:

the pre-SP21 monolithic store.py (~2,423 LOC) and pre-SP36 monolithic api.py (~3,548 LOC) — both have since been split;
127.0.0.1 as the bind address — SP23 moved the bind to 0.0.0.0 with the host firewall now controlling reachability;
the "no auth" posture — SP23 landed bcrypt + HttpOnly session cookies via cyclone.auth.*;
the SP23 product fork being "awaiting user decision" — SP23 is in main;
the "SP22 used, next is SP24" / "SP22 used, next is SP25" framing in skill files — last merged SP is SP41, next free is SP42;
the "12 SQL migrations" claim — 23 migrations are on disk (0001_initial through 0023_visits);
the "4 router modules" claim in cyclone-api-router/SKILL.md — SP36 split api.py into 22 routers under api_routers/;
the "Seven subcommands" claim in cyclone-cli/SKILL.md — SP24 / SP25 / SP27 / SP28 / SP33 / SP37 / SP38 / SP39 / SP40 / SP41 added ~12 more;
the "22 specs / 27 plans" / "17 specs / 13 plans" framing — 42 specs and 37 plans are on disk;
the "single 2412-line module" claim in cyclone-store/SKILL.md — SP21 shipped the split into 16 modules.

SP42 is a docs-only increment: every change is to *.md files. No code paths change; no API endpoints change; no test assertions change.

In scope:

CLAUDE.md — refresh the SP-N section (last merged SP, next free, file-size + subpackage claims), the migration count, and the CLI subcommand list (drop the three phantom parse-999 / parse-ta1 / parse-277ca entries that contradict the body text).
README.md — replace the "binds to 127.0.0.1, no auth, no internet exposure" lead with the SP23 posture ("always binds to 0.0.0.0, requires login, LAN-only by design"), update the project-layout block to reflect the post-SP21/SP36 split, and refresh the "Sub-projects 2 through 19 are shipped" framing.
docs/ARCHITECTURE.md — refresh the §1 / §2 / §4.1 / §4.3 / §5.4 / §6.2 / §7.4 / §8.1 / §11.2 / §13.2 blocks. SP23 is shipped (drop "awaiting user decision"). The package-layout map gets auth/, handlers/, rebill/, reissue/, store/ (the SP21 facade), and the full 22-router api_routers/. The SP21 split is present-tense. The endpoint enumeration in §8.1 gets refreshed. The §6.3 claim-state diagram gains partial (REQUIREMENTS FR-6 already lists it). The §7.4 audit strategy list gets pcn-exact (SP31) replacing the stale auto:pcn_npi_charge / auto:pcn_charge labels. The migration table goes from 12 to 23.
docs/REQUIREMENTS.md — move SP23 from §6.2 backlog to §6.1 shipped. Close R-1 (auth shipped), R-3 (Dockerfile / docker-compose shipped), R-11 (SP21 store split shipped), R-12 (SP36 api.py split shipped) with concrete evidence. Update R-13's migration count to 23. Add SP23–SP41 rows to the §6.1 SP table. Update §5.1 LOC claims and module list. Update §5.2 migration table. Update §12.1 / §12.2 spec-and-plan lists.
docs/RUNBOOK.md — replace "the SP23 Docker stack" with "the Docker stack"; keep the existing "Reissue claims (SP24)" section as-is (already correct).
.superpowers/skills/cyclone-spec/SKILL.md — refresh the "As of this writing" header line.
.superpowers/skills/cyclone-tests/SKILL.md — refresh test counts (178 backend tests, 22 fixtures, 130+ frontend test files) and the SP-N "next" pointer.
.superpowers/skills/cyclone-store/SKILL.md — drop the "single 2412-line module, SP21 in progress" framing; update line refs from store.py:882 to store/__init__.py:148; complete the SP21 module list (add backfill.py, claim_acks.py, kpis.py, resubmissions.py, submission_dedup.py); update line refs from api.py:1380-1401 / api.py:1891,2002 to the post-SP36 router files.
.superpowers/skills/cyclone-api-router/SKILL.md — replace "4 router modules" with "22 router modules"; replace the "next refactor target is the parse endpoints" note with the post-SP36 reality; update line refs in the "Mounting in api.py" example.
.superpowers/skills/cyclone-edi/SKILL.md — refresh the SP-N "next" pointer.
.superpowers/skills/cyclone-frontend-page/SKILL.md — refresh page / hook / drawer counts (12 pages, 19 hooks, 4 drawers including ProviderDrawer/ + AckDrawer/); refresh SP-N "next" pointer.
.superpowers/skills/cyclone-cli/SKILL.md — replace the "Seven subcommands" claim with the canonical 15+ subcommand list per the actual cyclone/cli.py; refresh SP-N "next" pointer.
.superpowers/skills/cyclone-tail/SKILL.md — refresh the "three streaming pages" claim (add Acks per SP25 ack-live-tail); replace api.py:1357-2006 line refs with the post-SP36 router files.

Out of scope:

Any code change. SP42 is docs-only.
Any new feature description beyond what already exists in code. The spec is a reconciliation pass, not a content pass.
Documenting SP34 (999-acceptance-restore). The branch was orphaned; SP31 supersedes the underlying race via the 2-of-3 match rule. The doc-pass must not list SP34 as shipped.
Documenting SP25's three-topic reuse as separate SPs. The historical anomaly is acknowledged in the SP42 spec but the doc pass keeps the merged-message convention (one row per merge commit).
Resolving the SP24 number collision (reissue-claims vs auth-posture alignment). The current main HEAD merge commit c9588f7 carries the subject "merge: SP24 reissue-claims into main", so SP24 is the reissue work; the 2026-06-23 docs-only auth-posture-alignment work landed as a sub-task of SP23 and is documented there.
A full rewrite of any section. The doc-pass updates only the lines that are stale; it does not restructure narrative.
The dead backend/src/cyclone/workflow/ directory. R-27 is left Open; deletion is a follow-up increment.

2. Decisions (locked during brainstorming)

Docs-only — no code paths change. Per the cyclone-spec skill convention, this is documented but enforced by reading the diff before each commit. Every commit in the SP42 branch must touch only *.md files (plus the spec/plan docs themselves).
One commit per file, prefixed docs(sp42): <file> …. Keeps the SP42 merge commit readable and lets reviewers bisect a single stale doc back to a specific commit if a future refactor pulls a doc claim back out of date.
Mechanical fixes only. Where the existing prose is correct (RUNBOOK.md §"Submitting claims (canonical — SP37)", the SP38 ack-orphans section, the SP41 §3.1 FR-RB-* block in REQUIREMENTS.md, the live-tail wire format table in CLAUDE.md), the doc-pass does not touch them. The pass targets the lines where the prose is provably inconsistent with git log + list_dir + the actual backend/src/cyclone/ inventory.
SP23 is shipped everywhere. Every "SP23 awaiting user decision" / "SP23 product fork" / "SP23 candidate" line in the docs gets rewritten as past tense. This is the single biggest correctness win and the highest-blast-radius fix.
Migration count goes from 12 to 23, every time it appears. Three docs (CLAUDE.md, ARCHITECTURE.md, REQUIREMENTS.md) all say "12" — they all become "23."
Router count goes from 4 to 22, every time it appears. cyclone-api-router/SKILL.md says "4 router modules"; ARCHITECTURE.md §2 says "4 routers"; REQUIREMENTS.md R-12 says "4 sub-routes". All three become "22."
Store split is present-tense everywhere. The "SP21 in flight" / "SP21 split is in progress" / "SP21 split is in-flight on refactor/store-split" framing in CLAUDE.md, ARCHITECTURE.md, REQUIREMENTS.md, and cyclone-store/SKILL.md all become past tense with the merge commit (4360ef7) cited as evidence.
CLI subcommand list gets the canonical 15+ enumeration in cyclone-cli/SKILL.md. The "Seven subcommands" line is replaced with the full list from cyclone/cli.py (verified against git log — users, submit-batch, reissue-claims, resubmit-rejected-claims, resubmissions, validate-837, recover-ingest, ack-orphans, seed, backfill-rendering-npi, backfill-999-rejections, pull-inbound, rebill-from-835, plus the existing parse-837, parse-835, validate-npi, validate-tax-id, and the backup group).
SP25 reuse is acknowledged in cyclone-spec/SKILL.md. The "Three SP25s (sftp-polling-enablement, ack-live-tail, orphan-data-recovery)" anomaly gets a one-line note in the skill's SP-N overview so future agents don't conflate the three SP25s with one another.
No new skill files. The exploration found that the SP23 auth work arguably warrants a cyclone-auth skill, but adding one is outside the doc-pass scope. It's flagged as a follow-up increment.

3. Threat model

The doc-pass changes no code paths and no auth gates. The threat model is unchanged from SP41 (the last shipped SP): the auth boundary is HTTP (login required, bcrypt + HttpOnly session cookie); the file-system threat is local-only and handled by SQLCipher at rest and the macOS Keychain. The doc-pass does not weaken any posture; the README.md "binds to 0.0.0.0, requires login" claim actually tightens the operator's mental model by removing the false "no auth, no internet exposure" framing that was inherited from the pre-SP23 posture.

The doc-pass is itself shipped via the same SP-N merge flow (single atomic merge, no squash, no rebase). The merge commit is the audit trail — merge: SP42 doc-pass into main.

4. Test impact

Per the cyclone-tests skill convention:

No new tests. SP42 is docs-only; nothing in the codebase is exercised differently.
Existing tests: the full pytest suite (cd backend && .venv/bin/pytest -q) plus the full vitest suite (npm test) must continue to pass — the doc-pass is a non-regression increment.
CI posture: unchanged (R-26 "no CI workflow" is left Open).
Fixtures: none added.
Frontend tests: none added.

5. Spec & plan anchors

Spec anchor (this file): docs/superpowers/specs/2026-07-08-cyclone-doc-pass-design.md
Plan anchor: docs/superpowers/plans/2026-07-08-cyclone-doc-pass.md
Source-of-truth inputs:
- git log --all --oneline --grep='merge: SP' | sed 's/.*merge: //' | awk '{print $1}' | sort -V | uniq — proves the SPs that have actually merged (5, 9-21, 23-41)
- ls docs/superpowers/specs/ | wc -l → 42; ls docs/superpowers/plans/ | wc -l → 37
- find backend/src/cyclone/migrations -name '*.sql' | wc -l → 23
- ls backend/src/cyclone/api_routers/*.py | wc -l → 21 routers + _shared.py + __init__.py
- ls backend/src/cyclone/store/*.py | wc -l → 17 modules
- find backend/src/cyclone -maxdepth 1 -type d — proves the subpackage list
- backend/src/cyclone/__main__.py:48 — proves host=os.environ.get("CYCLONE_HOST", "0.0.0.0")

6. Acceptance criteria

grep -rE 'SP22.*SP24|next free increment is SP24|next increment is SP24|next free is SP24|next is SP25' CLAUDE.md README.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md docs/RUNBOOK.md .superpowers/skills/ 2>/dev/null returns zero matches.
grep -rE 'awaiting user decision|SP23.*candidate|SP23.*product fork' docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null returns zero matches (in the SP23 context).
grep -rE 'api\.py.*3,548|3,548 LOC|store\.py.*2,423|2,423 LOC|2,172 LOC|3,145 LOC' CLAUDE.md README.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md .superpowers/skills/ 2>/dev/null returns zero matches.
grep -rE '127\.0\.0\.1' CLAUDE.md README.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null returns zero matches in the bind-address context.
grep -rE 'no auth, no internet exposure' README.md returns zero matches.
grep -rE '4 router modules|four router modules' .superpowers/skills/cyclone-api-router/SKILL.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null returns zero matches.
grep -rE 'Seven subcommands|7 subcommands' .superpowers/skills/cyclone-cli/SKILL.md returns zero matches.
grep -rE 'single 2412-line module|SP21.*in.progress|SP21.*in-flight' .superpowers/skills/cyclone-store/SKILL.md returns zero matches.
grep -rE '12 SQL migrations' CLAUDE.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null returns zero matches.
cd backend && .venv/bin/pytest -q exits 0; no regressions.
npm test exits 0; no regressions.
git log --oneline sp42-doc-pass shows one docs(spec): + one docs(plan): commit plus ~13 docs(sp42): commits (one per file touched).
After the merge to main, git log --oneline main -1 shows the SP42 merge commit with subject merge: SP42 doc-pass into main.
The single-file diff for CLAUDE.md, README.md, ARCHITECTURE.md, REQUIREMENTS.md, RUNBOOK.md, and each of the 8 skill files shows the stale lines updated and no semantic rewrites of unrelated prose.

13 KiB Raw Permalink Blame History Unescape Escape