pfs: code element model — closed typed vocabulary for the logical elements of a code descriptor #684

New Issue

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

kert commented

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

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (§Components: pfs/elements.py).

What. A pure module holding the element types (fixed) and element values (curated, closed list): actor, time, period, population, activity, modality, relation, setting, billing. Plus a deterministic descriptor parser for minutes / "each additional" / period words / code references in parentheticals.

Why the corpus says this is the right unit.

The telehealth review process is an element test: Step 1 separately payable under the PFS; Step 2 subject to §1834(m) (is the service "in whole or in part, inherently a face-to-face service"); Step 3 "Review the elements of the service as described by the HCPCS code and determine whether each of them is capable of being furnished using an interactive telecommunications system as defined in § 410.78(a)(3)" — CY2026 NPRM 2KVJ2HKX ¶394/¶396/¶398, 90 FR 32388–32389. The steps first print in the CY2024 rules (44F3F6VU, JJV3R692) and repeat every year since.
CPT 99490 as adopted for CY2015 is a stem plus enumerated required elements: ≥2 chronic conditions expected to last ≥12 months; conditions placing the patient at significant risk of death/decompensation/decline; comprehensive care plan established, implemented, revised, or monitored — DE2VH9PD ¶1244–1247, 79 FR 67716. The entire commenter dispute that year was over one period element (calendar month vs 30 days, ¶1248–1251).
G0556 (APCM, CY2025) is a stem plus ~20 elements with ++ sub-elements (consent; initiating visit; 24/7 access; continuity; alternative care delivery; comprehensive care management; electronic care plan; transitions; community coordination; asynchronous communication; population data; risk stratification; performance measurement) — JJ6AM5HJ ¶1163–1185, 89 FR 97864. G0557 is defined by reference to G0556's elements plus a population element (¶1186) — a relation value we must model.

Seed vocabulary from 99490, 99487/99489, 99491/99437, 99439, 99495/99496, 99497/99498, 99424–99427, G0556–G0558, 99441–99443 → 98008–98016, G2211, 99457/99458.

Done when the parser round-trips every seed descriptor in the FR into typed elements, with unit tests per type, and the five P48 hand families are reproducible from elements alone (see the families issue).

Spec docs/superpowers/specs/2026-09-09-code-family-longitudinal-design.md (§Components: `pfs/elements.py`). **What.** A pure module holding the element *types* (fixed) and element *values* (curated, closed list): `actor`, `time`, `period`, `population`, `activity`, `modality`, `relation`, `setting`, `billing`. Plus a deterministic descriptor parser for minutes / "each additional" / period words / code references in parentheticals. **Why the corpus says this is the right unit.** - The telehealth review process is an element test: Step 1 separately payable under the PFS; Step 2 subject to §1834(m) (is the service "in whole or in part, inherently a face-to-face service"); Step 3 "Review the elements of the service as described by the HCPCS code and determine whether each of them is capable of being furnished using an interactive telecommunications system as defined in § 410.78(a)(3)" — CY2026 NPRM `2KVJ2HKX` ¶394/¶396/¶398, [90 FR 32388–32389](https://www.federalregister.gov/citation/90-FR-32389). The steps first print in the CY2024 rules (`44F3F6VU`, `JJV3R692`) and repeat every year since. - CPT 99490 as adopted for CY2015 is a stem plus enumerated required elements: ≥2 chronic conditions expected to last ≥12 months; conditions placing the patient at significant risk of death/decompensation/decline; comprehensive care plan established, implemented, revised, or monitored — `DE2VH9PD` ¶1244–1247, [79 FR 67716](https://www.federalregister.gov/citation/79-FR-67716). The entire commenter dispute that year was over one `period` element (calendar month vs 30 days, ¶1248–1251). - G0556 (APCM, CY2025) is a stem plus ~20 elements with `++` sub-elements (consent; initiating visit; 24/7 access; continuity; alternative care delivery; comprehensive care management; electronic care plan; transitions; community coordination; asynchronous communication; population data; risk stratification; performance measurement) — `JJ6AM5HJ` ¶1163–1185, [89 FR 97864](https://www.federalregister.gov/citation/89-FR-97864). G0557 is defined *by reference* to G0556's elements plus a `population` element (¶1186) — a `relation` value we must model. **Seed vocabulary from** 99490, 99487/99489, 99491/99437, 99439, 99495/99496, 99497/99498, 99424–99427, G0556–G0558, 99441–99443 → 98008–98016, G2211, 99457/99458. **Done when** the parser round-trips every seed descriptor in the FR into typed elements, with unit tests per type, and the five P48 hand families are reproducible from elements alone (see the families issue).

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

kert added the pfs label 2026-09-09 14:30:03 +00:00

kert commented

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

Implemented on branch worktree-p49-code-family-foundation (plan docs/superpowers/plans/2026-09-09-code-family-foundation.md, Tasks 1 and 4). src/pfs/elements.py: ElementType (9 types), closed VOCAB, parse_descriptor, is_element_paragraph, slug; src/pfs/codetables.py: pfs.code_element, pfs.code_element_review, pfs.code_event, pfs.code_family with delete-then-insert writers, bulk readers.

Live run (2026-09-09, with the local model), elements per code:

code	elements	review
99490	22	4
99487 / 99489	20 / 20	2 / 0
99491 / 99437 / 99439	21 / 15 / 15	0
G2058	19	0
99424 / 99425 / 99426 / 99427	15 / 15 / 19 / 15	0 / 0 / 3 / 0
99495 / 99496	7 / 7	0
99497 / 99498	8 / 7	0
G0556 / G0557 / G0558	16 / 19 / 18	0
G0502 / G0503	14 / 14	0

Review queue: 9 lines across 3 codes (stack pfs review). Every row carries an FR anchor (item_key, p_id, page) or source='rvu'/'hcpcs' with a year.

Known gaps for the review loop: vocabulary values are seeded from the fixture families only; is_element_paragraph is a heuristic (final review fixed the FR cross-reference enumeration case). Follow-ups: #698 (--all-payable scale), new issue on long background paragraphs absorbed as a stem.

Implemented on branch `worktree-p49-code-family-foundation` (plan `docs/superpowers/plans/2026-09-09-code-family-foundation.md`, Tasks 1 and 4). `src/pfs/elements.py`: `ElementType` (9 types), closed `VOCAB`, `parse_descriptor`, `is_element_paragraph`, `slug`; `src/pfs/codetables.py`: `pfs.code_element`, `pfs.code_element_review`, `pfs.code_event`, `pfs.code_family` with delete-then-insert writers, bulk readers. **Live run (2026-09-09, with the local model), elements per code:** | code | elements | review | |---|---:|---:| | 99490 | 22 | 4 | | 99487 / 99489 | 20 / 20 | 2 / 0 | | 99491 / 99437 / 99439 | 21 / 15 / 15 | 0 | | G2058 | 19 | 0 | | 99424 / 99425 / 99426 / 99427 | 15 / 15 / 19 / 15 | 0 / 0 / 3 / 0 | | 99495 / 99496 | 7 / 7 | 0 | | 99497 / 99498 | 8 / 7 | 0 | | G0556 / G0557 / G0558 | 16 / 19 / 18 | 0 | | G0502 / G0503 | 14 / 14 | 0 | Review queue: 9 lines across 3 codes (`stack pfs review`). Every row carries an FR anchor (`item_key, p_id, page`) or `source='rvu'`/`'hcpcs'` with a year. Known gaps for the review loop: vocabulary values are seeded from the fixture families only; `is_element_paragraph` is a heuristic (final review fixed the FR cross-reference enumeration case). Follow-ups: #698 (`--all-payable` scale), new issue on long background paragraphs absorbed as a stem.

kert referenced this issue from a commit

2026-09-09 18:54:57 +00:00

fix(cli): stack pfs elements --dry-run reads the replica, never the writer (refs #684)

kert referenced this issue from a commit

2026-09-09 18:54:57 +00:00

fix(cli): stack pfs elements --family is repeatable (refs #684)

kert referenced this issue from a commit

2026-09-09 18:54:57 +00:00

docs: regenerate stack pfs CLI pages after the --family change (refs #684)

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