feat(pfs): cite the other phase-1 code families

Each remaining phase-1 family now has members whose Federal Register paragraph names the code. A hand family that is also curated keeps its conflict phrases.
This commit is contained in:
kert
2026-11-14 16:27:04 -05:00
parent cba6cca08f
commit c74dd0179b
6 changed files with 255 additions and 26 deletions

View File

@@ -563,8 +563,11 @@ def _print_families(rows: list[Any], *, verbose: bool = False) -> None:
typer.echo(f"{key}: {' '.join(f'{r.code}({r.role})' for r in members)}")
total = len(by_key)
multi = sum(1 for members in by_key.values() if len(members) >= 2)
hand = sum(1 for key in by_key if key in HAND_FAMILIES)
# A key that is both hand and curated counts once, as curated.
curated = sum(1 for key in by_key if key in CURATED_FAMILIES)
hand = sum(
1 for key in by_key if key in HAND_FAMILIES and key not in CURATED_FAMILIES
)
cpt_named = sum(
1
for key, members in by_key.items()

View File

@@ -32,3 +32,161 @@ HOME-VISITS:
- {kind: modifier, target: B1, since: 2027, aliases: [MOD1], alias_cite: {item_key: 5ITGVDJV, p_id: 521}, cite: {item_key: JCWARTJD, p_id: 1168}}
- {kind: modifier, target: B2, since: 2027, aliases: [MOD2], alias_cite: {item_key: 5ITGVDJV, p_id: 537}, cite: {item_key: JCWARTJD, p_id: 1205}}
- {kind: prolonged-add-on, target: G0318, since: 2023, aliases: [GXXX3], alias_cite: {item_key: MZ24MX5S, p_id: 880}, cite: {item_key: PETM225D, p_id: 1694}}
# Phase-1 families after HOME-VISITS. Each cite is a Federal Register
# paragraph that names the code. 99339 and 99340 stay on HOME-VISITS.
# 99473 and 99474 are self-measured blood pressure, not this RPM/RTM set.
OFFICE-EM:
name: Office/outpatient E/M
synonyms: [office/outpatient e/m, office or other outpatient]
members:
# CY2021 final rule: the office/outpatient E/M visit codes.
- {code: '99202', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99203', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99204', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99205', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99211', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99212', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99213', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99214', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
- {code: '99215', role: base, cite: {item_key: YBM4IZUS, p_id: 1008}}
# Same rule: the Panel deleted 99201. Last fee-schedule year is 2020.
- {code: '99201', role: predecessor, until: 2020, cite: {item_key: YBM4IZUS, p_id: 709}}
G2211-B1-B2:
name: G2211 and modifiers B1/B2
synonyms: [g2211, visit complexity]
members:
# CY2021 final rule: add-on to office/outpatient E/M, placeholder GPC1X.
# Fee schedule runs through 2026.
- {code: 'G2211', role: add-on, since: 2021, until: 2026, cite: {item_key: YBM4IZUS, p_id: 421}}
links:
- {kind: modifier, target: B1, since: 2027, aliases: [MOD1], alias_cite: {item_key: 5ITGVDJV, p_id: 521}, cite: {item_key: JCWARTJD, p_id: 1168}}
- {kind: modifier, target: B2, since: 2027, aliases: [MOD2], alias_cite: {item_key: 5ITGVDJV, p_id: 537}, cite: {item_key: JCWARTJD, p_id: 1205}}
CCM:
name: Chronic Care Management
synonyms: [ccm, chronic care management]
members:
- {code: '99490', role: base, since: 2015, cite: {item_key: DE2VH9PD, p_id: 1251}}
- {code: '99491', role: base, since: 2019, cite: {item_key: 9V89NVZG, p_id: 1500}}
# CY2025 final rule names these in the chronic care management set.
# The fee schedule pays them from 2015.
- {code: '99487', role: base, since: 2015, cite: {item_key: JJ6AM5HJ, p_id: 7603}}
- {code: '99489', role: base, since: 2015, cite: {item_key: JJ6AM5HJ, p_id: 7603}}
# CY2013 final rule assigns 99488 status B beside 99487 and 99489.
# It is absent from the fee schedule from 2015 on.
- {code: '99488', role: predecessor, cite: {item_key: NV3Q43B7, p_id: 1213}}
- {code: '99437', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 2728}}
- {code: '99439', role: add-on, since: 2021, cite: {item_key: YBM4IZUS, p_id: 2369}}
- {code: 'G2058', role: predecessor, since: 2020, until: 2020, cite: {item_key: YBM4IZUS, p_id: 2369}}
PCM:
name: Principal Care Management
synonyms: [pcm, principal care management]
members:
- {code: '99424', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1111}}
- {code: '99426', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1111}}
- {code: '99425', role: add-on, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1096}}
- {code: '99427', role: add-on, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1096}}
# Same CY2022 final rule adopts 99424 and 99426 to replace these.
# Fee schedule years are 2020 and 2021.
- {code: 'G2064', role: predecessor, since: 2020, until: 2021, cite: {item_key: JE7KYBW3, p_id: 1111}}
- {code: 'G2065', role: predecessor, since: 2020, until: 2021, cite: {item_key: JE7KYBW3, p_id: 1111}}
TCM:
name: Transitional Care Management
synonyms: [tcm, transitional care management]
members:
- {code: '99495', role: base, since: 2013, cite: {item_key: NV3Q43B7, p_id: 1151}}
- {code: '99496', role: base, since: 2013, cite: {item_key: NV3Q43B7, p_id: 1151}}
APCM:
name: Advanced Primary Care Management
synonyms: [apcm, advanced primary care management]
members:
- {code: 'G0556', role: base, since: 2025, cite: {item_key: JJ6AM5HJ, p_id: 1237}}
- {code: 'G0557', role: base, since: 2025, cite: {item_key: JJ6AM5HJ, p_id: 1265}}
- {code: 'G0558', role: base, since: 2025, cite: {item_key: JJ6AM5HJ, p_id: 1314}}
CPO-HH:
name: Care plan oversight and home health certification
synonyms: [care plan oversight, home health certification]
members:
- {code: 'G0179', role: base, cite: {item_key: GD84NJ2Y, p_id: 838}}
- {code: 'G0180', role: base, cite: {item_key: GD84NJ2Y, p_id: 838}}
- {code: 'G0181', role: base, cite: {item_key: NV3Q43B7, p_id: 1114}}
- {code: 'G0182', role: base, cite: {item_key: NV3Q43B7, p_id: 1114}}
# CY2013 final rule: care plan oversight services (99339, 99340, 99374-99380).
# 99339 and 99340 are already members of HOME-VISITS.
# 99376 is inside that range and is not a fee-schedule row from 2015 on.
- {code: '99374', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99375', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99376', role: member, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99377', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99378', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99379', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
- {code: '99380', role: base, cite: {item_key: NV3Q43B7, p_id: 1176}}
BHI-COCM:
name: Behavioral health integration and CoCM
synonyms: [behavioral health integration, psychiatric collaborative care, cocm]
members:
- {code: '99484', role: base, since: 2018, cite: {item_key: 73DU6WUG, p_id: 683}}
- {code: '99492', role: base, since: 2018, cite: {item_key: 73DU6WUG, p_id: 683}}
- {code: '99493', role: base, since: 2018, cite: {item_key: 73DU6WUG, p_id: 683}}
- {code: '99494', role: base, since: 2018, cite: {item_key: 73DU6WUG, p_id: 683}}
RPM-RTM:
name: Remote physiologic and therapeutic monitoring
synonyms: [remote physiologic monitoring, remote therapeutic monitoring, rpm, rtm]
members:
- {code: '99091', role: base, cite: {item_key: 9V89NVZG, p_id: 1462}}
- {code: '99453', role: base, since: 2019, cite: {item_key: 9V89NVZG, p_id: 514}}
- {code: '99454', role: base, since: 2019, cite: {item_key: 9V89NVZG, p_id: 514}}
- {code: '99457', role: base, since: 2019, cite: {item_key: 9V89NVZG, p_id: 514}}
- {code: '99458', role: add-on, since: 2020, cite: {item_key: 7AG9CSGC, p_id: 1276}}
- {code: '98975', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1072}}
- {code: '98980', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1072}}
- {code: '98981', role: base, since: 2022, cite: {item_key: JE7KYBW3, p_id: 1072}}
# CY2027 proposed rule: the current remote therapeutic monitoring set.
# First fee-schedule year is 2022 for 98976 and 98977, 2023 for 98978,
# and 2026 for 98979, 98984, and 98985.
- {code: '98976', role: base, since: 2022, cite: {item_key: 5ITGVDJV, p_id: 467}}
- {code: '98977', role: base, since: 2022, cite: {item_key: 5ITGVDJV, p_id: 467}}
- {code: '98978', role: base, since: 2023, cite: {item_key: 5ITGVDJV, p_id: 467}}
- {code: '98979', role: base, since: 2026, cite: {item_key: 5ITGVDJV, p_id: 467}}
- {code: '98984', role: base, since: 2026, cite: {item_key: 5ITGVDJV, p_id: 467}}
- {code: '98985', role: base, since: 2026, cite: {item_key: 5ITGVDJV, p_id: 467}}
ACP:
name: Advance Care Planning
synonyms: [acp, advance care planning]
members:
- {code: '99497', role: base, since: 2015, cite: {item_key: DE2VH9PD, p_id: 1178}}
- {code: '99498', role: add-on, since: 2015, cite: {item_key: DE2VH9PD, p_id: 1178}}
PROLONGED:
name: Prolonged services
synonyms: [prolonged service, prolonged services]
members:
- {code: '99354', role: add-on, until: 2022, cite: {item_key: 8TDTH68T, p_id: 592}}
- {code: '99355', role: add-on, until: 2022, cite: {item_key: 8TDTH68T, p_id: 592}}
- {code: '99356', role: predecessor, until: 2022, cite: {item_key: PETM225D, p_id: 1532}}
- {code: '99357', role: predecessor, until: 2022, cite: {item_key: PETM225D, p_id: 1532}}
- {code: '99417', role: add-on, since: 2021, cite: {item_key: YBM4IZUS, p_id: 834}}
# Medicare bills G2212 for this service instead of 99417, starting in 2021.
- {code: 'G2212', role: add-on, since: 2021, cite: {item_key: YBM4IZUS, p_id: 840}}
- {code: '99418', role: add-on, since: 2023, cite: {item_key: PETM225D, p_id: 1532}}
- {code: 'G0316', role: add-on, since: 2023, cite: {item_key: PETM225D, p_id: 497}}
- {code: 'G0317', role: add-on, since: 2023, cite: {item_key: PETM225D, p_id: 497}}
- {code: 'G0318', role: add-on, since: 2023, cite: {item_key: PETM225D, p_id: 497}}
VIRTUAL:
name: Virtual check-ins and communication-technology services
synonyms: [virtual check-in, communication technology-based service]
members:
- {code: 'G2010', role: base, since: 2019, cite: {item_key: 9V89NVZG, p_id: 447}}
# Last fee-schedule year is 2024.
- {code: 'G2012', role: base, since: 2019, until: 2024, cite: {item_key: 9V89NVZG, p_id: 415}}
- {code: 'G2252', role: base, since: 2021, cite: {item_key: YBM4IZUS, p_id: 579}}

View File

@@ -160,8 +160,18 @@ def _curated_registry() -> dict[str, CuratedFamily]:
def _load_curated_families() -> dict[str, Family]:
# A hand family that is also curated keeps its conflict phrases
# (CCM is also cardiac contractility modulation). The yaml does not
# carry that list.
return {
k: Family(k, c.name, c.codes, c.synonyms, curated=True)
k: Family(
k,
c.name,
c.codes,
c.synonyms,
curated=True,
conflicts=HAND_FAMILIES[k].conflicts if k in HAND_FAMILIES else (),
)
for k, c in _curated_registry().items()
}

View File

@@ -262,9 +262,11 @@ class TestElements:
],
)
assert res.exit_code == 0, res.output
from pfs.families import HAND_FAMILIES
from pfs.families import CURATED_FAMILIES
expected = set(HAND_FAMILIES["CCM"].codes) | set(HAND_FAMILIES["APCM"].codes)
expected = set(CURATED_FAMILIES["CCM"].codes) | set(
CURATED_FAMILIES["APCM"].codes
)
assert set(seen) == expected
@@ -520,7 +522,7 @@ class TestFamilies:
# still print, with cpt-named at 0 (I4: read-only-tolerant path
# also applies to the write path when the CPT tables are empty).
assert (
"families: total 3, multi-code 2, cpt-named 0, hand 1, curated 1, other 1"
"families: total 14, multi-code 12, cpt-named 0, hand 0, curated 13, other 1"
in (res.output)
)
@@ -611,10 +613,8 @@ class TestFamilies:
fams = read_families(con)
ccm = {r.code: r for r in fams if r.key == "CCM"}
assert {"99490", "99439"} <= set(ccm)
assert ccm["99490"].note == (
"Evaluation and Management > Care Management Services > "
"Chronic Care Management Services"
)
# Curated membership replaces the derived row, CPT heading included.
assert ccm["99490"].note == ""
assert "families: total" in res.output
assert "cpt-named" in res.output
@@ -629,7 +629,8 @@ class TestFamilies:
assert res.exit_code == 0, res.output
fams = read_families(con)
ccm = {r.code: r for r in fams if r.key == "CCM"}
assert ccm["99490"].since == 2019
# The curated cite's year wins over the CPT edition span.
assert ccm["99490"].since == 2015
assert ccm["99490"].until is None
def test_write_tolerates_null_rvu_description(self, con):
@@ -785,7 +786,7 @@ class TestGuidance:
assert seen["family"] == "CCM"
assert seen["con"] is not None
assert seen["store"] is not None
assert set(seen["codes"]) == set(pfs_cli.HAND_FAMILIES["CCM"].codes)
assert set(seen["codes"]) == set(pfs_cli.CURATED_FAMILIES["CCM"].codes)
got = read_guidance(con, "CCM")
assert [r.code for r in got] == ["99490"]
assert con.published == [True]
@@ -926,7 +927,7 @@ class TestReaction:
assert seen["classify"] is None # no --stance-sample: no LLM at all
assert seen["n"] == 0
assert seen["name"] == pfs_cli.HAND_FAMILIES["CCM"].name
assert set(seen["codes"]) == set(pfs_cli.HAND_FAMILIES["CCM"].codes)
assert set(seen["codes"]) == set(pfs_cli.CURATED_FAMILIES["CCM"].codes)
got = read_reaction(con, "CCM")
assert [r.period for r in got] == ["CMS-2023-0121"]
assert con.published == [True]
@@ -1290,12 +1291,12 @@ class TestFamiliesCurated:
fams = read_families(con)
assert [r.key for r in fams if r.code == "99341"] == ["HOME-VISITS"]
assert len([r for r in fams if r.key == "HOME-VISITS"]) == 20
assert "curated 1" in res.output
assert "curated 13" in res.output
def test_check_passes_on_the_packaged_file(self, con):
res = runner.invoke(app, ["pfs", "families", "--check"])
assert res.exit_code == 0, res.output
assert "curated: 1 families, no problems" in res.output
assert "curated: 13 families, no problems" in res.output
def test_check_fails_and_lists_every_problem(self, con, monkeypatch, tmp_path):
import pfs.curated as cur

View File

@@ -93,7 +93,40 @@ def test_curated_rows_carry_cite():
1672,
"",
)
assert len(rows) == 20
assert len([row for row in rows if row.key == "HOME-VISITS"]) == 20
assert len(rows) > 20
def test_phase1_families_cite_the_rule_that_names_them():
fams = load_curated()
assert set(fams) >= {
"HOME-VISITS",
"OFFICE-EM",
"G2211-B1-B2",
"CCM",
"PCM",
"TCM",
"APCM",
"CPO-HH",
"BHI-COCM",
"RPM-RTM",
"ACP",
"PROLONGED",
"VIRTUAL",
}
add = next(m for m in fams["ACP"].members if m.code == "99498")
assert (add.role, add.since, add.item_key, add.p_id) == (
"add-on",
2015,
"DE2VH9PD",
1178,
)
# Already claimed by the home-visit family, so care-plan oversight does not
# repeat them.
assert "99339" in fams["HOME-VISITS"].codes
assert "99339" not in fams["CPO-HH"].codes
assert "99376" in fams["CPO-HH"].codes
assert curated_problems() == []
def test_apply_curated_claims_codes():
@@ -110,12 +143,12 @@ def test_apply_curated_claims_codes():
"E/M > Home",
),
FamilyRow(
"NEW-PATIENT", "New Patient", "99202", "base", 2015, None, "", 0, "E/M"
"NEW-PATIENT", "New Patient", "93000", "base", 2015, None, "", 0, "E/M"
),
]
rows = apply_curated(derived, load_curated())
assert [r.key for r in rows if r.code == "99341"] == ["HOME-VISITS"]
assert [r.key for r in rows if r.code == "99202"] == ["NEW-PATIENT"]
assert [r.key for r in rows if r.code == "93000"] == ["NEW-PATIENT"]
assert rows == sorted(rows, key=lambda r: (r.key, r.code))

View File

@@ -77,7 +77,21 @@ class TestRegistry:
assert family_of("00000") is None
def test_all_families_present(self):
assert set(FAMILIES) == {"ACP", "CCM", "PCM", "TCM", "APCM", "HOME-VISITS"}
assert set(FAMILIES) == {
"ACP",
"APCM",
"BHI-COCM",
"CCM",
"CPO-HH",
"G2211-B1-B2",
"HOME-VISITS",
"OFFICE-EM",
"PCM",
"PROLONGED",
"RPM-RTM",
"TCM",
"VIRTUAL",
}
class TestDetectCodes:
@@ -99,8 +113,8 @@ class TestDetectCodes:
assert d.codes == ("G0556", "G0557", "G0558")
def test_unregistered_code_stays_alone(self):
d = detect_codes("value of 99213")
assert d == Detection(codes=("99213",), families=(), explicit=("99213",))
d = detect_codes("value of 93000")
assert d == Detection(codes=("93000",), families=(), explicit=("93000",))
def test_multiple_families(self):
d = detect_codes("compare CCM and TCM")
@@ -315,8 +329,8 @@ class TestDetectDerivedFamilies:
assert d.explicit == ("G0557",)
assert d.families == ("APCM",)
assert d.codes == ("G0556", "G0557", "G0558")
assert detect_codes("value of 99213") == Detection(
codes=("99213",), families=(), explicit=("99213",)
assert detect_codes("value of 93000") == Detection(
codes=("93000",), families=(), explicit=("93000",)
)
d = detect_codes("compare CCM and TCM")
assert d.families == ("CCM", "TCM")
@@ -1460,10 +1474,12 @@ class TestLoadAndRefresh:
# the derived (superset) codes; every other hand key survives
# untouched since `refresh_from` seeds from HAND_FAMILIES
# first instead of clearing the registry outright.
assert n == len(HAND_FAMILIES) + len(mod.CURATED_FAMILIES)
assert n == len(set(HAND_FAMILIES) | set(mod.CURATED_FAMILIES))
assert set(mod.FAMILIES) >= set(HAND_FAMILIES)
assert set(mod.FAMILIES["CCM"].codes) == {"99490", "G2058"}
# Curated membership wins over the derived rows for the same key.
assert mod.FAMILIES["CCM"].codes == mod.CURATED_FAMILIES["CCM"].codes
assert mod.FAMILIES["CCM"].name == HAND_FAMILIES["CCM"].name
assert mod.FAMILIES["CCM"].conflicts == HAND_FAMILIES["CCM"].conflicts
finally:
con.close()
@@ -1558,8 +1574,14 @@ class TestLoadAndRefresh:
],
)
refresh_from(con)
# Those four hand keys are curated now, so the overlay wins and
# the hand conflict list still comes through.
for key in ("ACP", "PCM", "TCM", "APCM"):
assert mod.FAMILIES[key] == HAND_FAMILIES[key]
live = mod.FAMILIES[key]
assert live.curated
assert live.codes == mod.CURATED_FAMILIES[key].codes
assert live.synonyms == HAND_FAMILIES[key].synonyms
assert live.conflicts == HAND_FAMILIES[key].conflicts
finally:
con.close()
@@ -1613,6 +1635,7 @@ class TestLoadAndRefresh:
)
refresh_from(con)
assert mod.FAMILIES["CCM"].synonyms == HAND_FAMILIES["CCM"].synonyms
assert mod.FAMILIES["CCM"].conflicts == HAND_FAMILIES["CCM"].conflicts
finally:
con.close()
@@ -1697,7 +1720,8 @@ class TestCurated:
assert len(restore_families.FAMILIES["HOME-VISITS"].codes) == 20
assert restore_families.FAMILIES["HOME-VISITS"].curated
assert curated_family("home-visits").key == "HOME-VISITS"
assert curated_family("ACP") is None
assert curated_family("ACP") is not None
assert curated_family("NO-SUCH") is None
def test_family_of_prefers_curated_over_derived(self, restore_families):
restore_families.FAMILIES["ACUTE-X"] = Family(