tyler/cyclone
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(plan): SP42 doc-pass implementation plan

Browse Source
This commit is contained in:
Nora
2026-07-08 23:01:55 -06:00
parent 90a2055c20
commit 4c466ca054
1 changed files with 234 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/plans/2026-07-08-cyclone-doc-pass.md
+234
View File
@@ -0,0 +1,234 @@
# 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`](../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
- [x] Branch `sp42-doc-pass` from `main` (no worktree — work in current checkout).
- [x] First commit on the branch: `docs(spec): SP42 doc-pass design` (commits the spec).
- [x] 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)
```bash
# 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
```