stack/docs/superpowers/plans/2026-08-13-cy2027-pfs-proposed-rule-p37.md

CY2027 PFS Proposed Rule (P37) 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: Run CY2027's NPRM (CMS-1848-P, docket CMS-2026-2377, FR doc 2026-14327, pub 2026-07-16) through the pipeline P36 built, with the four deltas from the spec (PROPOSED registry, #607 rename first, multi-rule ingest, open-comment-period farm + scheduled re-farm).

Architecture / Tech Stack: identical to P36 — see docs/superpowers/plans/2026-08-12-cy2026-pfs-proposed-rule-p36.md for the detailed patterns; this plan states only what differs.

Tracker: milestone P37 (id 38) — issues #607–#616. Spec: docs/superpowers/specs/2026-08-13-cy2027-pfs-proposed-rule-design.md

Global Constraints

Same as P36's plan (branch p37-cy2027-rule off main; conventional commits refs #NNN, no Co-Authored-By trailers; 99% coverage, stdlib mocking; ruff E,F,I/88; lazy conf imports; generated workflows untouched; llm local-only; duckdb_batch for writes; never transcribe rule parameters from memory — grep the captured text with -a (HTML-wrapped, hard-wrapped lines, stray NULs) and pincite everything; transcription-then-test allowed only for FR values). Plus, learned in P36: stage only your own files (git add <paths>, never -A); retry once on commit HEAD/index races; pyproject-touching commits trigger the full-suite hook (~14 min parallel) — serialize around them.

---

Task 1: Align rvu_proposed column names (#607)

Files: Modify src/pfs/nprm.py, tests/pfs/test_nprm.py, notebooks/cy2026_pfs_proposed_rule.py (its SQL aliases). Produces: pfs.rvu_proposed columns exactly hcpcs, mod, description, status_code, work_rvu, non_fac_pe_rvu, fac_pe_rvu, mp_rvu, cms_rule_id (audit against pfs.pipe._RVU_COLUMNS and match pfs.rvu verbatim — verify with DESCRIBE pfs.rvu on the replica first).

• Update tests to the new names (they pin the schema) → run → FAIL → rename in nprm.py (target columns + DDL + normalization map) → PASS.
• Simplify the P36 notebook's join SQL (drop the alias juggling); uvx marimo check + layout tests.
• Host run uv run python dev/scripts/ingest_pfs.py --nprm --no-lake (delete-and-reload recreates the table with new names; DROP TABLE pfs.rvu_proposed first since CREATE IF NOT EXISTS won't alter columns — do it inside the same duckdb_batch), then full run with lake; verify replica + lake schema.
• Commit fix(pfs): align rvu_proposed columns with pfs.rvu (refs #607).

Task 2: Docket mapping (#608)

Files: src/rex/comments/classify.py, tests/rex/comments/test_classify.py.

• Failing test: DOCKET_RULES["CMS-2026-2377"] == "CMS-1848-P" → add the entry (comment: CY2027 PFS NPRM, verified via FR API 2026-08-13) → PASS → commit feat(comments): register CMS-2026-2377 (CY2027 PFS NPRM) (refs #608).

Task 3: Discover + capture rule text (#609) — ops

• uv run stack bib discover-pfs-rules (registers/tags the CY2027 items; note the new item key for 2026-14327 — find via store.list_items(item_type="rule") filtering document_number).
• uv run python dev/scripts/fetch_fr_attachments.py --key <KEY>; verify PDF+TXT in data/fr_downloads and attachments on the item; grep -a -c "conversion factor" data/fr_downloads/2026-14327.txt > 0.
• Record the item key in the ledger + issue comment (later tasks need it). No commit.

Task 4: NPRM addenda capture (#610)

Files: Modify dev/scripts/fetch_nprm_addenda.py (add --year selecting a per-year config dict: detail-page URL, ZIP URL, dest dir, rule item key, tag set; 2026 entry keeps current values; 2027 entry → CMS-1848-P page, data/cms/pfs_nprm/2027/, tags sup:2027_PFS_NPRM, module:pfs, file:rvu, year:2027).

• Resolve the CMS-1848-P addenda ZIP URL from https://www.cms.gov/medicare/payment/fee-schedules/physician/federal-regulation-notices/cms-1848-p (fallback: the notices index). Download, verify Addendum B columns, --register (idempotency guard already exists — parameterize it by item key), tag-scoped zotero sync.
• Commit feat(pfs): CY2027 NPRM addenda capture — fetch_nprm_addenda --year (refs #610).

Task 5: PROPOSED registry + CY2027 parameters (#611)

Files: src/pfs/rules/__init__.py, tests/pfs/test_rules.py. Produces: PROPOSED: dict[int, ProposedRule]; proposed_for(year) -> ProposedRule | None (RULES[year].proposed if year in RULES else PROPOSED.get(year)); PROPOSED[2027] populated.

• Transcribe from data/fr_downloads/2026-14327.txt (grep -a, short fragments): proposed CFs (QP/non-QP + anesthesia pair), BN adjustor, telehealth originating-site fee, published/comment-close (DATES block — this close date drives #615's schedule), FR citation from the header ([Pages …]). Record verbatim quotes + file lines + FR pages in the report.
• Structural tests first (helper resolves both paths; 2027 in PROPOSED not RULES), then exact-value tests pinning transcriptions. Docstrings follow the file's :pincite: style citing the new item key.
• Commit feat(pfs): PROPOSED registry + proposed_for — CY2027 NPRM parameters (refs #611).

Task 6: Multi-rule NPRM ingest (#612)

Files: src/pfs/nprm.py, dev/scripts/ingest_pfs.py, tests/pfs/test_nprm.py. Produces: _discover_addendum_b(tag: str); NPRM_SOURCES: list of (year, sup_tag, cms_rule_id) (2026 + 2027); load_rvu_proposed(con, *, year) resolving tag/rule/citation via NPRM_SOURCES + proposed_for(year); --nprm loads every source, one ingest_log row each, same run_id.

• Tests: two fixture partitions load side by side; reloading one rule leaves the other intact; discovery raises naming the missing tag.
• Host run (both partitions; verify SELECT cms_rule_id, count(*) FROM pfs.rvu_proposed GROUP BY 1 shows CMS-1832-P + CMS-1848-P) + replica + lake; cms.ingest_log rows for both.
• Commit feat(pfs): multi-rule NPRM ingest — CY2026+CY2027 partitions (refs #612).

Task 7: qpp PY2027 (#613)

Files: src/qpp/__init__.py, tests/qpp/test_rules.py.

• Transcribe PY2027 current-law thresholds/standards and CMS-1848-P's proposed Advanced-APM changes from 2026-14327.txt (both greps and quotes in the report; re-verify PY2026 only where restated). QPP[2027] + QppProposed(cms_rule_id="CMS-1848-P", …); unstated values → None + notes (P36 precedent).
• Structural + exact-value tests; commit feat(qpp): PY2027 registry + CMS-1848-P proposed changes (refs #613).

Task 8: Initial comment farm (#614) — ops, long-running

• uv run stack bib fetch-pfs-comments (discovers CMS-1848-P → resolves docket → pulls comments to date; rate-limited ~970/hr — with an open period expect a partial set; run detached setsid nohup, log to .state/comments/fetch-CMS-2026-2377.log, Monitor for errors).
• Then backfill-comments (export REGULATIONS_GOV_API_KEY), comments extract --docket CMS-2026-2377, extract-ocr, then stack llm index --collection comments --docket CMS-2026-2377 and --collection rules --key <2027 item key> (detached + monitored; all resumable).
• Post counts on #614. No commit.

Task 9: Post-close re-farm (#615) — scheduled, blocks milestone close

• After Task 5 lands, set the local cron reminder for close-date+1 (CronCreate) to re-run Task 8's commands verbatim; comment the exact date + commands on #615.
• On firing: re-run, post final counts, close #615, then close milestone P37.

Task 10: CY2027 notebook (#616)

Files: notebooks/cy2027_pfs_proposed_rule.py.

• Clone the P36 notebook's structure (dataviz skill first): CF walk CY2026-final → CY2027-proposed (columns labeled "final rule pending"), RVU deltas rvu_proposed[CMS-1848-P] vs CY2026 final pfs.rvu (aligned columns from Task 1), APM section from qpp PY2027 via for_payment_year(2029)/QPP[2027], provenance from cms.ingest_log. Registry-sourced values only; FR citation attached to every figure (P36 review standard); GPCI=1.0 scope note.
• marimo check + layout tests + scoped headless integration; commit feat(notebooks): CY2027 proposed-rule financial changes + APM (refs #616).

Task 11: Close-out

• Full gates; merge p37-cy2027-rule → main (Merge P37: …), push (remote is gitea).
• Close #607–#614, #616 with substantiation; #615 + milestone stay open until the post-close re-farm.
• Append ## P37 build outcomes to the spec; update ledger; keep the re-farm cron armed.