From c74dd0179bcda9ce466e6e062d2fa8bf14bee049 Mon Sep 17 00:00:00 2001 From: kert Date: Sat, 14 Nov 2026 16:27:04 -0500 Subject: [PATCH] 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. --- src/cli/pfs.py | 5 +- src/pfs/curated.yaml | 158 +++++++++++++++++++++++++++++++++++++ src/pfs/families.py | 12 ++- tests/cli/test_pfs_cli.py | 25 +++--- tests/pfs/test_curated.py | 39 ++++++++- tests/pfs/test_families.py | 42 +++++++--- 6 files changed, 255 insertions(+), 26 deletions(-) diff --git a/src/cli/pfs.py b/src/cli/pfs.py index f18cccc..97f95ed 100644 --- a/src/cli/pfs.py +++ b/src/cli/pfs.py @@ -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() diff --git a/src/pfs/curated.yaml b/src/pfs/curated.yaml index 5e56e8c..b970c84 100644 --- a/src/pfs/curated.yaml +++ b/src/pfs/curated.yaml @@ -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}} diff --git a/src/pfs/families.py b/src/pfs/families.py index 5053c06..b21bc23 100644 --- a/src/pfs/families.py +++ b/src/pfs/families.py @@ -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() } diff --git a/tests/cli/test_pfs_cli.py b/tests/cli/test_pfs_cli.py index c781c04..c0a0ac0 100644 --- a/tests/cli/test_pfs_cli.py +++ b/tests/cli/test_pfs_cli.py @@ -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 diff --git a/tests/pfs/test_curated.py b/tests/pfs/test_curated.py index 252782a..1ccd4f6 100644 --- a/tests/pfs/test_curated.py +++ b/tests/pfs/test_curated.py @@ -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)) diff --git a/tests/pfs/test_families.py b/tests/pfs/test_families.py index 6ded6f7..d68707e 100644 --- a/tests/pfs/test_families.py +++ b/tests/pfs/test_families.py @@ -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(