tyler/cyclone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
96ed8f5f64e6a18cb08d8c4261c2620522fe849e
cyclone/docs/superpowers/plans/2026-07-08-cyclone-doc-pass.md
T

16 KiB
Raw Blame History

Doc-Pass Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Reconcile CLAUDE.md, README.md, docs/ARCHITECTURE.md, docs/REQUIREMENTS.md, docs/RUNBOOK.md, and the eight .superpowers/skills/*/SKILL.md files so the prose matches the current implementation after SPs 23–41. Architecture: Pure .md edits. No code paths change; no API endpoints change; no test assertions change. One commit per file, prefixed docs(sp42): <file> …. The merge commit (merge: SP42 doc-pass into main) is the audit trail. Tech Stack: Markdown + git + grep for verification. Spec: docs/superpowers/specs/2026-07-08-cyclone-doc-pass-design.md

File structure

docs/superpowers/
  specs/2026-07-08-cyclone-doc-pass-design.md            ← new
  plans/2026-07-08-cyclone-doc-pass.md                   ← new

CLAUDE.md                                                ← edit (header + subpackage + LOC claims)
README.md                                                ← edit (lead paragraph + project layout)
docs/ARCHITECTURE.md                                     ← edit (§1, §2, §4.1, §4.3, §5.4, §6.2, §6.3, §7.4, §8.1, §11.2, §13.2)
docs/REQUIREMENTS.md                                     ← edit (§1, §2.2, §5.1, §5.2, §6.1, §6.2, §11, §12)
docs/RUNBOOK.md                                          ← edit (SP23 Docker stack → Docker stack)

.superpowers/skills/cyclone-spec/SKILL.md                ← edit (As of this writing header)
.superpowers/skills/cyclone-tests/SKILL.md               ← edit (counts + SP-N pointer)
.superpowers/skills/cyclone-store/SKILL.md               ← edit (SP21 framing + line refs + module list)
.superpowers/skills/cyclone-api-router/SKILL.md          ← edit (4 → 22 routers + line refs)
.superpowers/skills/cyclone-edi/SKILL.md                 ← edit (SP-N pointer)
.superpowers/skills/cyclone-frontend-page/SKILL.md       ← edit (counts + drawer list)
.superpowers/skills/cyclone-cli/SKILL.md                 ← edit (Seven → 15+ subcommands)
.superpowers/skills/cyclone-tail/SKILL.md                ← edit (3 → 4 streaming pages + line refs)

Task 0: branch + spec/plan

  • Branch sp42-doc-pass from main (no worktree — work in current checkout).
  • First commit on the branch: docs(spec): SP42 doc-pass design (commits the spec).
  • Second commit: docs(plan): SP42 doc-pass implementation plan (commits this plan).

Task 1: refresh CLAUDE.md

  • Update line ~7 to read "LAN-only by design — always binds to 0.0.0.0:8000 and requires login…".
  • Update line ~97 ("SP22 used, next free is SP24") to "SP numbers are used through SP41 (in-window rebill pipeline); the next free increment is SP42. A sp42-doc-pass worktree is checked out locally but not yet merged into main."
  • Update line ~121 (api.py / store.py LOC + "only large file" claim): replace the "3,548 LOC / 2,423 LOC / in flight" framing with post-SP21/SP36 reality. "The largest files now live under cyclone/api_routers/ (22 routers under SP36) and cyclone/store/ (the SP21-split facade in 16 modules). api.py is a ~377-line shell that wires the FastAPI app and mounts the routers."
  • Update line ~122 subpackage list: expand api_routers/ to 22 routers; add auth/ (SP24, 10 modules), handlers/ (SP27, 6 modules), rebill/ (SP41, 13 modules), reissue/ (SP24, 2 modules), store/ (SP21, 16 modules). Note that workflow/ is dead bytecode.
  • Update line ~128 migration count: "23 SQL migrations under migrations/ (0001_initial through 0023_visits)".
  • Drop the three phantom parse-999 / parse-ta1 / parse-277ca entries from the CLI block (lines 174–176) — they contradict the body text and were already flagged in CLAUDE.md's "Things that are easy to get wrong" section.
  • Commit: docs(sp42): CLAUDE.md — refresh SP numbers, store split, subpackage list.

Task 2: refresh README.md

  • Update lines 7–8: replace "Local-only on purpose: binds to 127.0.0.1, no auth, no internet exposure." with "LAN-only by design — always binds to 0.0.0.0:8000 and requires login (bcrypt + HttpOnly session cookie; first admin bootstrapped from CYCLONE_ADMIN_USERNAME + CYCLONE_ADMIN_PASSWORD). Reachability is controlled by the host firewall / compose port publishing, not the bind address."
  • Update the project-layout block: replace store.py with store/ (post-SP21 split); replace the api.py description with the thin-shell description; add auth/, handlers/, rebill/, reissue/, store/, submission/, api_routers/ (22 routers).
  • Update the "Sub-projects 2 through 19 are shipped" claim to "Sub-projects 2 through 41 are shipped."
  • Update the CLI example block to drop parse-999, parse-ta1, parse-277ca (which don't exist as DB-writing CLIs — see CLAUDE.md "Inbound ingestion paths" note).
  • Commit: docs(sp42): README.md — refresh auth/bind claim and project layout.

Task 3: refresh docs/ARCHITECTURE.md

  • Update §1 line ~14: replace 127.0.0.1 with 0.0.0.0 and add the reachability + auth boundary sentence.
  • Update §2 process diagram: replace api.py 3,548 LOC with api.py ~377 LOC (post-SP36 thin shell); replace the 4-router enumeration with the full 22-router list.
  • Update §4.1 package layout: add auth/, handlers/, rebill/, reissue/, store/, expand api_routers/ to 22 routers.
  • Update §4.2 module map: add the missing subpackage rows.
  • Update §4.3 SP21 framing: present-tense ("After SP21, the public API of cyclone.store is unchanged…"); add the post-split module list reference.
  • Update §5.4: replace /api/tail?since=… with the canonical three-stream endpoints and replace api.py:1357-2006 with api_routers/{claims,remittances,activity}.py.
  • Update §6.2 ERD: add claim_acks, resubmissions, visits tables.
  • Update §6.3 claim-state diagram: add partial (per REQUIREMENTS FR-6).
  • Update §7.4: replace auto:pcn_npi_charge / auto:pcn_charge with pcn-exact (SP31).
  • Update §8.1 endpoint enumeration with the canonical list (~85 routes after SPs 23–41).
  • Update §11.2: replace "SP23 product fork awaiting user decision" with "SP23 (shipped 2026-06-23 via merge: SP23 Ubuntu Docker Deployment into main)".
  • Update §13.2: replace "22 specs / 27 plans" with "42 specs / 37 plans"; add the missing SP25–SP41 spec entries.
  • Update §6.1 migration table from 12 to 23.
  • Commit: docs(sp42): ARCHITECTURE.md — refresh post-SP23–41 package map, endpoints, SP23 status.

Task 4: refresh docs/REQUIREMENTS.md

  • Update line ~49: "Sub-projects 2 through 41 are shipped."
  • Update §2.2 / §5.4 / §5.1: drop "SP23 would add" speculative framing; rewrite as past tense where SP23 shipped something.
  • Update §5.1 LOC claims (api.py 3,145 → ~377; store.py 2,172 → split into cyclone/store/).
  • Update §5.1 module list: add auth, handlers, rebill, reissue, submission subpackage rows; expand store row to its 16 modules.
  • Update §5.2 migration table: 12 → 23 with the full enumeration.
  • Update §6.1 SP table: add SP23 (Ubuntu+Docker, shipped) through SP41 (rebill pipeline, shipped) as separate rows.
  • Update §6.2 backlog: move SP23 from backlog to §6.1; remove the "SP23 candidate" row.
  • Update §11 R-1, R-3, R-11, R-12 to Closed with concrete merge-SHA evidence; update R-13 migration count to 23.
  • Update §12.1 / §12.2 spec-and-plan lists to include SP25–SP41.
  • Commit: docs(sp42): REQUIREMENTS.md — refresh SP table, close SP23 risks, add SP25–41.

Task 5: refresh docs/RUNBOOK.md

  • Update line ~120: replace "For the SP23 Docker stack, mount the MFT password as a file…" with "For the Docker stack, mount the MFT password as a file…" (SP23 is shipped; the wording should not read as conditional).
  • Audit any other "SP23 Docker stack" / "SP23 would" / "SP23 candidate" wording; rewrite as past tense where SP23 shipped the feature.
  • Commit: docs(sp42): RUNBOOK.md — drop 'SP23 Docker stack' conditional framing.

Task 6: refresh .superpowers/skills/cyclone-spec/SKILL.md

  • Update line ~16: "As of this writing: 42 specs in docs/superpowers/specs/, 37 plans in docs/superpowers/plans/, SP numbers used through SP41 (in-window rebill pipeline). The next free increment is SP42."
  • Add a one-line note about the SP25 reuse anomaly (three SP25s: sftp-polling-enablement, ack-live-tail, orphan-data-recovery).
  • Commit: docs(sp42): cyclone-spec skill — refresh SP-N framing.

Task 7: refresh .superpowers/skills/cyclone-tests/SKILL.md

  • Update line ~7–8: refresh test counts (89 backend → 178; 13 fixtures → 22; 59 frontend → 130+); replace "next is SP24" with "next is SP42".
  • Commit: docs(sp42): cyclone-tests skill — refresh counts and SP-N pointer.

Task 8: refresh .superpowers/skills/cyclone-store/SKILL.md

  • Update line ~10: replace backend/src/cyclone/store.py:882 with backend/src/cyclone/store/__init__.py:148.
  • Update line ~17: drop "single 2412-line module, SP21 in progress" framing; replace with the post-SP21 16-module enumeration + "Last merged SP: SP41; next free increment: SP42."
  • Update SP21 split module list (lines 60–70) to add the 5 missing modules: backfill.py, claim_acks.py, kpis.py, resubmissions.py, submission_dedup.py.
  • Update line ~86 (store.py:898-1107) → store/write.py.
  • Update line ~121 (api.py:1380-1401) → api_routers/{claims,remittances,activity}.py.
  • Update line ~136 (api.py:1891,2002) → api_routers/{claims,remittances,activity}.py.
  • Commit: docs(sp42): cyclone-store skill — refresh SP21 framing, line refs, module list.

Task 9: refresh .superpowers/skills/cyclone-api-router/SKILL.md

  • Update lines 14–18: replace "4 router modules" with the canonical 22-router list; replace "api.py ~3,548 LOC" with "api.py ~377 LOC (thin shell)".
  • Update lines 49–50: drop the "parse endpoints next refactor target" note (SP36 already split them).
  • Update lines 170–183 line refs (api.py:246-256 etc.) → api_routers/__init__.py.
  • Commit: docs(sp42): cyclone-api-router skill — refresh router count + line refs.

Task 10: refresh .superpowers/skills/cyclone-edi/SKILL.md

  • Update line ~13: "The next increment is SP42" (was SP22). Add a one-line note about SP32 (rendering NPI), SP35 (parse input guards), SP39 (2010BB NM109), SP40 (Edifabric gate) having touched parser/validator territory.
  • Commit: docs(sp42): cyclone-edi skill — refresh SP-N pointer.

Task 11: refresh .superpowers/skills/cyclone-frontend-page/SKILL.md

  • Update line ~11: refresh counts (11 → 12 pages, ~30 → ~53 hooks, 2 → 4 drawers); replace "next is SP22" with "next is SP42".
  • Update drawer list at lines 18–20: add ProviderDrawer/, AckDrawer/.
  • Commit: docs(sp42): cyclone-frontend-page skill — refresh counts + drawer list.

Task 12: refresh .superpowers/skills/cyclone-cli/SKILL.md

  • Update lines 8–9: replace "Seven subcommands" with the canonical 15+ subcommand list (parse-837, parse-835, validate-npi, validate-tax-id, validate-837, submit-batch, reissue-claims, resubmit-rejected-claims, resubmissions, pull-inbound, recover-ingest, ack-orphans, users, seed, backfill-rendering-npi, backfill-999-rejections, rebill-from-835, pull-inbound, plus the backup group).
  • Commit: docs(sp42): cyclone-cli skill — replace Seven-subcommands claim with full list.

Task 13: refresh .superpowers/skills/cyclone-tail/SKILL.md

  • Update lines 13–17: refresh "three streaming pages" claim — add Acks (SP25 ack-live-tail) for a total of 4.
  • Update line ~44: replace api.py:1357-2006 with api_routers/{claims,remittances,activity}.py + api_routers/{acks,ta1_acks}.py.
  • Update line ~70: replace api.py:1401,1894,2005 with the post-SP36 router files.
  • Update line ~119: replace api.py:1357-1401 with api_routers/claims.py.
  • Commit: docs(sp42): cyclone-tail skill — refresh streaming page count + line refs.

Task 14: autoreview (the merge gate)

  • Run the 14 acceptance-criteria grep checks from §6 of the spec; expect zero matches for each.
  • cd backend && .venv/bin/pytest -q — full backend suite passes (no regressions expected; this is a docs-only increment).
  • npm test — full vitest suite passes.
  • git log --oneline sp42-doc-pass shows the expected commit sequence (1× docs(spec): + 1× docs(plan): + 13× docs(sp42):).
  • git status --short shows no unexpected untracked files (note: pre-existing untracked files from the operator's working dir — july8billing/, july8billing_out/, xxxclaims.zip, verification-final.txt, scripts/serialize_july8_to_sp41.py, backend/src/cyclone/submission/bulk_ingest.py, backend/tests/fixtures/co_medicaid_837p.997, backend/tests/fixtures/subscriber_roster.csv, docs/superpowers/plans/2026-07-07-cyclone-2010bb-nm109-fix.md, docs/superpowers/plans/2026-07-07-cyclone-inwindow-rebill-pipeline.md, docs/superpowers/specs/2026-07-07-cyclone-inwindow-rebill-pipeline-design.md, .grok/ — should remain untracked).
  • No semantic rewrites of unrelated prose. Each diff should touch only the lines flagged in the SP42 audit findings.

Task 15: merge to main

  • git checkout main && git merge --no-ff --no-squash --no-rebase sp42-doc-pass -m "merge: SP42 doc-pass into main"
  • git log --oneline main -1 shows the SP42 merge commit with the expected subject.
  • git push origin main only after the operator has reviewed and approved the merge (per cyclone-spec — the merge commit is the audit trail; the operator must approve).

Verification commands (one-shot)

# Acceptance criteria §1 — no stale "next free is SP24" / "next is SP25"
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

# §2 — SP23 "awaiting user decision" / "candidate" / "product fork"
grep -rE 'awaiting user decision|SP23.*candidate|SP23.*product fork' docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null

# §3 — stale LOC claims
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

# §4 — 127.0.0.1 in bind-address context
grep -nE '127\.0\.0\.1' CLAUDE.md README.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null

# §5 — README "no auth, no internet exposure"
grep -nE 'no auth, no internet exposure' README.md

# §6 — "4 router modules" / "four router modules"
grep -rE '4 router modules|four router modules' .superpowers/skills/cyclone-api-router/SKILL.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null

# §7 — "Seven subcommands" / "7 subcommands"
grep -rE 'Seven subcommands|7 subcommands' .superpowers/skills/cyclone-cli/SKILL.md

# §8 — "single 2412-line module" / "SP21 in progress" / "SP21 in-flight"
grep -rE 'single 2412-line module|SP21.*in.progress|SP21.*in-flight' .superpowers/skills/cyclone-store/SKILL.md

# §9 — "12 SQL migrations"
grep -rE '12 SQL migrations' CLAUDE.md docs/ARCHITECTURE.md docs/REQUIREMENTS.md 2>/dev/null

# §10 / §11 — test suites
cd backend && .venv/bin/pytest -q
npm test
Reference in New Issue View Git Blame Copy Permalink