stack/docs/superpowers/specs/2026-08-13-cy2027-pfs-proposed-rule-design.md

# CY2027 PFS Proposed Rule (CMS-1848-P) — capture, ingestion, APM analysis

**Status:** Designed — repeat of the P36 pattern per standing directive
**Date:** 2026-08-13
**Part of:** P37 (CY2027 PFS Proposed Rule)
**Related:** P36 (#588–#597, merged 53b97b8), #607 (rvu_proposed column alignment — folded in here), spec `2026-08-12-cy2026-pfs-proposed-rule-design.md`

## Goal

Run the CY2027 PFS proposed rule (CMS-1848-P, docket CMS-2026-2377, FR doc
`2026-14327`, published 2026-07-16) through the pipeline P36 built: capture
files, ingest proposed parameters and Addendum B with provenance, farm the
comments (period is **open** — initial pull now, scheduled re-farm after
close), index the rule text for RAG, extend the QPP/Advanced-APM registry to
PY2027, and analyze financial changes in a notebook. Tracked as Gitea
milestone P37.

## Current state (verified 2026-08-13)

- CY2027 NPRM published 2026-07-16: FR `2026-14327`, CMS-1848-P, reg.gov
  docket CMS-2026-2377 (per the FR API). Not yet in bib; no comments pulled;
  comment period open (close date to be transcribed from the DATES block).
- P36 infrastructure exists and is merged: `ProposedRule` model,
  `pfs.nprm` loader + `pfs.rvu_proposed` (keyed by `cms_rule_id` —
  designed for multi-rule), `cms.ingest_log`, `qpp` registry,
  `llm.source.iter_rule_docs` + `rules` pgvector collection,
  `rex.comments.classify.DOCKET_RULES`, notebook pattern.
- **No CY2027 final rule exists**, so there is no `RULES[2027]` to hang a
  `proposed` block on — and `RuleYear` requires final fields
  (`conversion_factor` is load-bearing for `pfs.pipe`'s RVU-file
  selection). The registry needs a home for proposed-only years.
- #607 is open: `pfs.rvu_proposed` column names deviate from `pfs.rvu`
  (`modifier`/`mod`, `nonfac_pe_rvu`/`non_fac_pe_rvu`); fixing it before a
  second consumer cycle joins against the table halves the migration cost.

## Design deltas vs P36

### A. Proposed-only registry home (`pfs.rules`)
`PROPOSED: dict[int, ProposedRule]` module-level registry for years whose
final rule hasn't published, plus `proposed_for(year) -> ProposedRule | None`
returning `RULES[year].proposed` when the year exists in `RULES`, else
`PROPOSED.get(year)`. When the CY2027 final rule ships, `RULES[2027]` is
created and the entry migrates onto it (P36 shape); `proposed_for` keeps
consumers stable across that move. `RuleYear` itself is untouched — no
optional-final-fields surgery, `pfs.pipe` semantics unchanged.

### B. Column alignment first (#607)
Rename `pfs.rvu_proposed` columns to match `pfs.rvu` (`mod`,
`non_fac_pe_rvu`, `fac_pe_rvu` — audit the full set against `_RVU_COLUMNS`)
in `pfs.nprm`, the P36 notebook's SQL, and tests, then reload the table
(delete-and-reload makes this cheap). Done before any CY2027 consumer exists.

### C. Multi-rule NPRM ingest
`load_rvu_proposed` is parameterized by rule already; generalize discovery:
`_discover_addendum_b(tag)` takes the supplement tag (`sup:2027_PFS_NPRM`),
and `dev/scripts/ingest_pfs.py --nprm` loads every configured
(tag, cms_rule_id) pair — CY2026 and CY2027 partitions coexist keyed by
`cms_rule_id`, each with its own `ingest_log` row and FR citation from
`proposed_for(year)`.

### D. Open comment period
Initial farm now (`stack bib fetch-pfs-comments` discovers CMS-1848-P →
resolves CMS-2026-2377 → pulls comments to date), then backfill/extract/
index. A **post-close re-farm** (same commands — everything is resumable/
incremental) is scheduled after the DATES close date; the P37 milestone
stays open until that re-farm's counts are posted. A local cron reminder
fires the re-farm; the Gitea issue carries the close date.

### E. Everything else is a repeat
- Rule-text capture: `fetch_fr_attachments.py --key <2027 item>` after
  `discover-pfs-rules` registers/tags the item (`cms-rule:CMS-1848-P`).
- Addenda: CMS-1848-P detail page → `data/cms/pfs_nprm/2027/`; Addendum B
  attached + tagged `sup:2027_PFS_NPRM`, `module:pfs`, `file:rvu`,
  `year:2027` (fetch script gains a `--year 2027` mode instead of a clone).
- `DOCKET_RULES["CMS-2026-2377"] = "CMS-1848-P"` + regression test.
- CY2027 `ProposedRule` values transcribed from the captured text with
  pincites — never memory; comment-close date transcribed from DATES.
- `qpp`: PY2027 `QppYear` (current law) + `QppProposed` for CMS-1848-P
  changes, both-file citations; re-verify PY2026 values only where the
  CY2027 NPRM restates them.
- Rule text → `rules` collection (`stack llm index --collection rules
  --key <item>`); comments → `comments` collection scoped to the docket.
- Notebook `notebooks/cy2027_pfs_proposed_rule.py`: CY2026-final →
  CY2027-proposed CF walk (no final column — labeled "final rule pending");
  RVU deltas `rvu_proposed[CMS-1848-P]` vs CY2026 final `pfs.rvu`;
  Advanced-APM section from `qpp` PY2027; provenance section. Same
  registry-sourced/citation-per-figure rules the P36 review enforced.

## Milestones and issues

### P37: CY2027 PFS Proposed Rule — capture, ingest, APM analysis

1. `pfs: align rvu_proposed column names with pfs.rvu` — existing #607, added to P37 (delta B)
2. `comments: register CMS-2026-2377 ↔ CMS-1848-P mapping` — delta E
3. `bib: discover + capture CY2027 rule text (2026-14327) into fr_downloads + bib` — delta E
4. `pfs: capture CMS-1848-P proposed addenda (sup:2027_PFS_NPRM)` — delta E
5. `pfs: PROPOSED registry + proposed_for helper, CY2027 NPRM parameters + pincites` — delta A
6. `pfs: multi-rule NPRM ingest (CY2026 + CY2027 partitions)` — delta C
7. `qpp: PY2027 registry + CMS-1848-P proposed changes` — delta E
8. `comments: initial farm of CMS-2026-2377 (fetch/backfill/extract/index)` — delta D
9. `comments: post-close re-farm + re-index of CMS-2026-2377` — delta D (blocks milestone close; scheduled)
10. `notebooks: CY2027 proposed-rule financial changes + Advanced APM notebook` — delta E

Dependency order: 1 first (schema); 2–4 independent; 5 needs 3; 6 needs
1+4+5; 7 needs 3; 8 needs 2; 9 after close date; 10 needs 5+6+7.

## Testing

Same bars as P36: pytest 99% coverage, stdlib mocking; exact-value tests
pin transcribed CY2027 parameters; multi-rule loader tests cover both
partitions + the renamed columns; qpp structural tests extend to PY2027;
notebook through layout tests + marimo check + headless integration; RAG
spot-checks on the docket and rule-text chunks. Regression: P36 notebook
still green after the #607 rename.

## Out of scope

- CY2027 OPPS/other rules; the CY2027 *final* rule (a future milestone
  creates `RULES[2027]` and migrates the PROPOSED entry).
- Comment classification/sentiment (P30).
- Cloud LLM usage (llm stays local-only).

## P37 build outcomes (2026-08-14)

Issues #607–#616 + interstitial #620, milestone P37 (10 commits,
d726dca..a75b4c7, branch `p37-cy2027-rule` in a worktree — main checkout
was concurrently owned by #618). #615 and the milestone remain open until
the scheduled post-close re-farm.

- **CY2027 NPRM parameters** (91 FR 43842, item 5ITGVDJV, all values
  byte-verified by two agents): proposed CF 32.8409 non-QP / 33.1693 QP,
  anesthesia 20.2143/20.4165, BN 1.0053, telehealth $32.65, comment close
  **2026-09-14**. Housed in the new `PROPOSED` registry via
  `proposed_for(year)` (no RULES[2027] until the final rule). The NPRM's
  own Summary section mislabels its CY2026 baselines (verbatim carry-over
  of CY2026's *proposed* QP CF); documented in notes, resolved via the RIA.
- **Multi-rule ingest**: `pfs.rvu_proposed` now partitioned by cms_rule_id
  (CMS-1832-P 14,169 + CMS-1848-P 14,518 rows) with per-rule ingest_log
  provenance; columns aligned with `pfs.rvu` (#607) behind a durable
  schema-migration guard.
- **QPP correction (#620, adjudicated)**: P36 had mis-keyed the statutory
  threshold schedule (payment years read as performance years) —
  QPP[2023]/[2024] corrected to 50/35 (partial 40/25); QPP[2026] was
  superseded by CAA 2026 (50/35, partial 40/25, **3.1% incentive revived
  for payment year 2028**); [2025]/[2027] confirmed correct at 75/50. Both
  notebooks self-corrected (live registry reads); the P36 notebook's
  narrative and partition filters were fixed in the final-review wave
  (d3750ce). CMS's own drafting error at 414.1430(b)(2)(i)(D) documented.
- **Comment farm**: initial pull complete — **2,727 comments to date**
  (period open); extraction/indexing follow incrementally; post-close
  re-farm scheduled via host crontab 2026-09-15 03:17 →
  `dev/scripts/refarm_cms_2026_2377.sh` (cron-hardened: PATH, honest
  failure reporting), which posts final counts to #615.
- **Notebook**: `notebooks/cy2027_pfs_proposed_rule.py` — CF walk
  (final pending), RVU deltas vs CY2026 final, payment-year-labeled APM
  section incl. the CAA-2026 "not a clean sunset" story, provenance;
  headless-validated via staged worktree copy.
- **Also landed en route**: #617 (FR text normalized at capture — first
  live use: the CY2027 txt arrived clean), #618 (4 tracemalloc-verified
  sqlite leaks fixed + `error::ResourceWarning` gate), #619 filed
  (publish_replica symlink bug, workaround applied), #623 filed (docs
  tag-list drift from controller tag ops).