pfs: code lineage table — creation, adoption, replacement, deletion, status change, revaluation events with FR anchors #686

New Issue

kert · 2026-09-09T14:30:04Z

kert commented

2026-09-09 14:30:04 +00:00

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (pfs/lineage.py).

What. pfs.code_event(code, year, kind, from_codes, to_codes, item_key, p_id, page, source) built from two independent sources that must agree or be flagged unanchored: (a) pfs.rvu/rvu_proposed diffs per code per year — appears, disappears, status change, descriptor change, |ΔRVU| > 10 %; (b) fr_anchors paragraphs whose codes metadata contains the code and whose text matches an event pattern (creat/finaliz, replace, delet, crosswalk, bundled, telehealth services list).

Fixture lineages, all already in the corpus.

event	evidence
CMS G-code → CPT 99490 (CY2015)	`DE2VH9PD` ¶1249–1251, 79 FR 67716: "we will adopt CPT code 99490 … effective January 1, 2015 instead of the G code"
G2058 (RVU file 2020 only) → CPT 99439 (2021–)	`YBM4IZUS` ¶1578, 85 FR 84639: "descriptor identical to G2058", temporary crosswalk; ¶686 (TCM concurrency), ¶2369
G2064/G2065 (2020–21) → 99424/99426 (2022–), knock-on into RHC/FQHC G0511 rate	`JE7KYBW3` ¶1100/¶1111, 86 FR 65118; `MZ24MX5S` ¶1305
99441–99443 deleted by CPT, last in RVU file 2024, → 98008–98016	`XFGGRBDH`/`JJ6AM5HJ` ¶489/¶765, 89 FR 61652
status transitions	`pfs.rvu`: 99487/99489 B→A, 99497/99498 I→A, 99091 B→A, G2211 B→A
APCM created (CY2025)	`JJ6AM5HJ` ¶1163–1187, 89 FR 97864

99490 alone is discussed in 27 distinct rule documents (CY2015 final → CY2027 proposed) and 284 rule chunks already carry codes ∋ 99490, so the FR side has the coverage; the RVU side starts at 2015 (files before that are a gap to note, not to fill here).

Done when the six fixture lineages are emitted with correct kinds and anchors, the cross-check flags a deliberately removed paragraph as unanchored, and stack pfs lineage --code X prints the timeline with FR jump links (P40).

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (`pfs/lineage.py`). **What.** `pfs.code_event(code, year, kind, from_codes, to_codes, item_key, p_id, page, source)` built from two independent sources that must agree or be flagged `unanchored`: (a) `pfs.rvu`/`rvu_proposed` diffs per code per year — appears, disappears, status change, descriptor change, |ΔRVU| > 10 %; (b) `fr_anchors` paragraphs whose `codes` metadata contains the code and whose text matches an event pattern (creat/finaliz, replace, delet, crosswalk, bundled, telehealth services list). **Fixture lineages, all already in the corpus.** | event | evidence | |---|---| | CMS G-code → CPT 99490 (CY2015) | `DE2VH9PD` ¶1249–1251, [79 FR 67716](https://www.federalregister.gov/citation/79-FR-67716): "we will adopt CPT code 99490 … effective January 1, 2015 instead of the G code" | | G2058 (RVU file 2020 only) → CPT 99439 (2021–) | `YBM4IZUS` ¶1578, [85 FR 84639](https://www.federalregister.gov/citation/85-FR-84639): "descriptor identical to G2058", temporary crosswalk; ¶686 (TCM concurrency), ¶2369 | | G2064/G2065 (2020–21) → 99424/99426 (2022–), knock-on into RHC/FQHC G0511 rate | `JE7KYBW3` ¶1100/¶1111, [86 FR 65118](https://www.federalregister.gov/citation/86-FR-65118); `MZ24MX5S` ¶1305 | | 99441–99443 deleted by CPT, last in RVU file 2024, → 98008–98016 | `XFGGRBDH`/`JJ6AM5HJ` ¶489/¶765, [89 FR 61652](https://www.federalregister.gov/citation/89-FR-61652) | | status transitions | `pfs.rvu`: 99487/99489 B→A, 99497/99498 I→A, 99091 B→A, G2211 B→A | | APCM created (CY2025) | `JJ6AM5HJ` ¶1163–1187, [89 FR 97864](https://www.federalregister.gov/citation/89-FR-97864) | 99490 alone is discussed in 27 distinct rule documents (CY2015 final → CY2027 proposed) and 284 rule chunks already carry `codes ∋ 99490`, so the FR side has the coverage; the RVU side starts at 2015 (files before that are a gap to note, not to fill here). **Done when** the six fixture lineages are emitted with correct kinds and anchors, the cross-check flags a deliberately removed paragraph as `unanchored`, and `stack pfs lineage --code X` prints the timeline with FR jump links (P40).

kert added this to the P49: Code families as first-class objects — element model, lineage anchors, longitudinal chat milestone 2026-09-09 14:30:04 +00:00

kert added the pfs bib labels 2026-09-09 14:30:04 +00:00

kert commented

2026-09-09 18:24:12 +00:00

Implemented on branch worktree-p49-code-family-foundation (Tasks 6–7): src/pfs/lineage.py — rvu_events (appeared / disappeared / status_change / descriptor_change / revalued from pfs.rvu base-row diffs) and fr_events (created / adopted_cpt / replaces / replaced_by / deleted / crosswalk / bundled / telehealth_list from fr_anchors paragraphs naming the code), merged by lineage() with the ±1-rule-year cross-check that marks RVU events anchored. Directional replaces/replaced_by (no other code may sit between subject and trigger), created no longer fires on "value established for", same-block range prefilter (99441-99443, G0008-G0010) expands ranges, FR page citations stripped before matching. CLI: stack pfs lineage --code X [--write] (read-only without --write).

Live run, seven fixture codes: 156 events written, 0 unanchored.

code	events
99490	35
G2058	17
99439	21
G2064	17
99424	32
99441	30
G0556	4

Fixture checks: 99490 2015 adopted_cpt DE2VH9PD ¶1251 ✓; G2058 2020 appeared, 2021 replaced_by → 99439 (YBM4IZUS ¶686; the brief's ¶1578 anchors 99439's reciprocal replaces G2058), 2021 disappeared ✓; G2064 2022 replaced_by → 99424 (JE7KYBW3 ¶1100/¶1111) ✓; 99441 2025 deleted + bundled + telehealth_list (XFGGRBDH ¶489) and 2025 disappeared ✓; G0556 2025 created (JJ6AM5HJ) + appeared ✓.

Known limitation to design around in the chat (#691): FR events are dated by the rule year of the paragraph that mentions them, not the effective year — retrospective recaps yield extra created/replaced_by rows in later years (e.g. G2058 created in 2021–2023 from paragraphs recounting its CY2020 creation). The chat should present the earliest anchored event as the origin and later ones as mentions.

Implemented on branch `worktree-p49-code-family-foundation` (Tasks 6–7): `src/pfs/lineage.py` — `rvu_events` (appeared / disappeared / status_change / descriptor_change / revalued from `pfs.rvu` base-row diffs) and `fr_events` (created / adopted_cpt / replaces / replaced_by / deleted / crosswalk / bundled / telehealth_list from `fr_anchors` paragraphs naming the code), merged by `lineage()` with the ±1-rule-year cross-check that marks RVU events `anchored`. Directional `replaces`/`replaced_by` (no other code may sit between subject and trigger), `created` no longer fires on "value established for", same-block range prefilter (`99441-99443`, `G0008-G0010`) expands ranges, FR page citations stripped before matching. CLI: `stack pfs lineage --code X [--write]` (read-only without `--write`). **Live run, seven fixture codes:** 156 events written, **0 unanchored**. | code | events | |---|---:| | 99490 | 35 | | G2058 | 17 | | 99439 | 21 | | G2064 | 17 | | 99424 | 32 | | 99441 | 30 | | G0556 | 4 | Fixture checks: 99490 `2015 adopted_cpt` DE2VH9PD ¶1251 ✓; G2058 `2020 appeared`, `2021 replaced_by → 99439` (YBM4IZUS ¶686; the brief's ¶1578 anchors 99439's reciprocal `replaces G2058`), `2021 disappeared` ✓; G2064 `2022 replaced_by → 99424` (JE7KYBW3 ¶1100/¶1111) ✓; 99441 `2025 deleted` + `bundled` + `telehealth_list` (XFGGRBDH ¶489) and `2025 disappeared` ✓; G0556 `2025 created` (JJ6AM5HJ) + `appeared` ✓. **Known limitation to design around in the chat (#691):** FR events are dated by the *rule year of the paragraph that mentions them*, not the effective year — retrospective recaps yield extra `created`/`replaced_by` rows in later years (e.g. G2058 `created` in 2021–2023 from paragraphs recounting its CY2020 creation). The chat should present the earliest anchored event as the origin and later ones as mentions.

kert referenced this issue

2026-09-09 18:24:14 +00:00

pfs: derive code families from elements and CMS's own "code family" language; hand registry becomes the fixture #687

kert referenced this issue

2026-09-09 18:55:18 +00:00

P49 slice 1: code families as first-class objects — element model, lineage anchors, derived families, stack pfs CLI (refs #684 #685 #686 #687) #701