docs(pfs): design code-family dossiers — complete life history with its politics

One cited account per CPT/HCPCS family: origin (concept, benefit design,
law), CPT Panel formation, RUC survey and CMS valuation decisions, every
change through all time, a full payment table, and at each step how
commenters lined up, who they were, what they cited and what they stood
to gain or lose in money and power, grounded in the RUC and
international fee-setting literature. Standing on-screen page per family
plus the same evidence in chat. Primary care and home-based care first
(proof family: home and residence visits), then bundling/value-based
overlaps, then the rest. Public sources plus the AMA books already held;
gaps stated on the page while pre-2018 dockets and pre-2002 rules
backfill in parallel.

docs/superpowers/specs/2026-11-11-code-family-dossier-design.md

@@ -0,0 +1,245 @@
+# Code-family dossiers: the complete life history of a code family, with its politics
+
+Date: 2026-11-11. Status: design, for review. Builds on
+`2026-09-09-code-family-longitudinal-design.md` (P49/P50).
+
+## Intent
+
+For any CPT/HCPCS code family, the stack can tell its whole biography as
+one cited account:
+
+1. **Origin** — the clinical concept and the benefit design or law that
+   called for a code (statute, regulation, CMS program, demonstration).
+2. **Formation** — when the code set first formed and was drafted: the
+   AMA CPT Editorial Panel action (or CMS creating a G-code), and the
+   first year it appears in the fee schedule.
+3. **Valuation** — the initial RUC survey and recommendation (survey
+   percentile, work RVU, time, comparator codes) and what CMS did with it
+   (accepted, refined, rejected — and why), plus practice-expense inputs.
+4. **Every change since** — revaluations, descriptor and guideline
+   changes, misvalued-code nominations, telehealth listing, bundling,
+   deletion, replacement — through all time.
+5. **Payment over all time** — a year-by-year table of RVUs, conversion
+   factor and national payment, proposed vs final, with utilization.
+
+At every step it shows **the politics**: how public commenters lined up
+(support / support with modifications / oppose), who they were, what
+evidence each side cited, and what each stood to gain or lose — in
+**money** (payment and specialty income shifts) and in **power** (who
+controls the code: RUC and CPT Panel seats, code sponsorship, which
+specialties bill it). The aim is to explain stances well enough to
+predict them from the stakes, and to ground the power analysis in the
+published research on the RUC (US) and on fee-setting bodies abroad.
+
+The user wants this "for everything", in this order: **primary care and
+home-based care first**, then **anything overlapping bundling or
+value-based care**, then **the obscure rest**.
+
+## Output
+
+- **A standing dossier page per family**, read on screen (not designed
+  for print). It is the canonical, browsable account.
+- **The same material in chat.** A question about a family answers from
+  the dossier's evidence, cites it, and links to the page. Chat's current
+  payment/valuation table is the starting point, made complete
+  (all years, all codes in the family, proposed vs final).
+- Everything is cited: a Federal Register paragraph (`#p-N` jump link),
+  a comment (regulations.gov id), a CMS file, a public AMA document, a
+  statute section, or a study. An unsourced statement does not appear.
+
+Dossier page layout (my call; a mockup can come before building):
+header (family, codes, status, years active) → one-paragraph summary →
+timeline (each event with date, what changed, source, and its comment
+split) → valuation panel (RUC recommendation vs CMS decision per code
+per round, comparators) → payment table (all years) → stakeholders
+panel (who supported/modified/opposed, by organization type and
+specialty, with their stakes) → governance context (relevant findings
+from the RUC and international literature) → sources.
+
+## Phase 1 scope (proof of concept, then fan out)
+
+**Proof family (my call): home and residence visits** — 99341–99350 plus
+the deleted domiciliary codes 99324–99340 and 99343 they absorbed in
+2023. The user named it, and it exercises every gap: deleted codes,
+late-1990s origin, RUC 25th-percentile recommendations
+(`PETM225D` ¶1676), commenter splits (¶1679), the G2211/B1/B2 add-on and
+the 2027 home-visit revaluation. Its dossier is the acceptance test.
+
+Then the rest of primary care and home-based care: office/outpatient
+E/M, G2211 and modifiers B1/B2, CCM (99490/99491/99487–99489/99437/
+99439/G2058), PCM (99424–99427, G2064/G2065), TCM (99495–99496), APCM
+(G0556–G0558), care plan oversight and home health certification
+(G0179–G0182, 99339/99340, 99374–99380), BHI and CoCM (99484,
+99492–99494), RPM/RTM, ACP (99497–99498), prolonged services
+(99354–99357, 99417/99418, G0316–G0318), virtual check-ins and
+communication-technology services (G2010/G2012/G2252).
+
+Phase 2: bundling and value-based-care overlaps (global surgical
+packages, MSSP/ACO and Innovation-Center-linked codes, APCM's tie to
+APM participation, care-management bundles, RHC/FQHC payment). Phase 3:
+everything else.
+
+## What exists (from the 2026-11-11 recon)
+
+Reuse, do not rebuild:
+- `pfs.code_event` (16,942 events / 6,713 codes) and `src/pfs/lineage.py`:
+  events anchored to FR paragraphs (CY2002–CY2027), RVU-file changes
+  (2016–2026), CPT Changes years; `src/llm/lineage.py` timeline block in
+  chat.
+- `fr_anchors` (200,975 paragraphs) and `pfs/reaction.py`'s
+  Comment:/Response: pairing; `pfs.code_reaction` with closed stance
+  labels support / oppose / modify / unclear (sampled for CCM only).
+- `pfs/valuation.py`, `pfs.rules.RULES` (CF 2014–2027), `pfs.rvu`
+  (2015–2027), `rvu_proposed`, work-time files, `pfs.utilization`.
+- Chunk metadata `codes` / `families` on all 1.42M comment chunks; bib
+  `code:` / `family:` tags; P35 theme tags (vocab v3) on comments.
+- `pfs.code_family` (8,489 derived families) and the five hand families.
+
+Gaps this design closes: (1) no structured RUC/CMS valuation
+extraction; (2) deleted codes have no lineage; (3) depth stops at CY2002
+rules / 2015 RVUs, no statute links; (4) primary-care family definitions
+are poor (generic keys, G2211 misgrouped, biliary codes in office E/M);
+(5) stance exists only for a CCM sample, commenter identity for 4.4% of
+comments; (6) chat caps the payment table at 2 years for multi-code
+families; (7) no governance literature in the library.
+
+## How it gets built (the parts decided)
+
+### Sources — public only for now (user decision)
+
+Federal Register PFS rules (back as far as federalregister.gov/govinfo
+publish them, then earlier rules via govinfo where available); CMS PFS
+relative-value files and public-use files for every year CMS publishes;
+CMS specialty-impact tables; regulations.gov comments; statute and
+regulation text (US Code, public laws, eCFR — `bib.cfrlink` exists);
+CMS manuals and MLN; MedPAC reports; public AMA material (CPT Editorial
+Panel summaries of actions and RUC meeting minutes/vote records where
+the AMA posts them publicly; RUC membership rosters); the open-access
+governance literature from the recon list
+(`scratchpad/recon/ruc-literature.md`, ~90 sources). Licensed books
+(*CPT Changes*, CPT codebooks, *Medicare RBRVS*) are added later when the
+user supplies them; the design must work without them and get richer
+with them.
+
+### Families
+
+A curated family registry for phase 1 (hand-checked membership,
+predecessor/successor links across renumbering and deletion, G-code
+families, the add-on and modifier relationships), layered over the
+derived families. Every code ever seen gets lineage, not only codes
+payable in the newest year.
+
+### Extraction (all local models — the llm module never calls cloud LLM APIs)
+
+- **Valuation decisions** from FR paragraphs: per code per round — RUC
+  recommended work RVU, survey percentile used, survey time, comparator
+  / crosswalk codes, CMS final value, decision (accept / refine / reject /
+  interim), CMS's stated rationale.
+- **Comment stance** per family per event: support / support with
+  modifications / oppose / unclear, with the reason and the evidence the
+  comment cites, extending `pfs.code_reaction` beyond CCM. CMS's own
+  Comment:/Response: summaries are a second, independent stance source
+  (CMS says "many commenters supported…"); both are shown, never merged
+  silently.
+- **Commenter identity**: organization, organization type (specialty
+  society, health system, vendor, payer, patient group, individual
+  clinician, individual), specialty, and form-letter campaign membership
+  (near-duplicate clustering). From regulations.gov fields first, then
+  letterhead/opening text of the comment and its attachments.
+
+### Stakes
+
+- **Money**: CMS specialty-impact tables per rule year; code-level
+  payment change × utilization, attributed to billing specialties;
+  proposed-vs-final deltas.
+- **Power**: RUC and CPT Panel seats by specialty and year (public
+  rosters), code sponsorship (who brought the code to the Panel/RUC, from
+  FR and public AMA records), share of a family's billing by specialty.
+- **Prediction**: an explainable model of stance from stakes
+  (expected stance per stakeholder given money and power at stake),
+  reported against actual stances per event, as calibration — not as a
+  black box.
+
+### Governance research
+
+Ingest the open-access items from the recon list into bib/Zotero
+(tagged, with full text where open access), mark paywalled ones on the
+wanted list. Dossiers cite specific findings where they bear on a
+family (e.g. RUC acceptance rates, survey response rates, the specialty
+seat effect on prices, international fee-setting comparisons).
+
+### Chat
+
+Family detection → dossier evidence block (timeline, valuation rounds,
+comment split, stakes) → answer cites it and links to the page. The
+payment table is complete (all years, all family codes) with proposed
+vs final marked.
+
+## Goals
+
+- The home-visit dossier is complete and correct end to end, checked
+  against the FR text and comments by hand — the acceptance test.
+- Every primary-care/home-based family in scope gets a dossier, then
+  phase 2 and 3 families.
+- Each dossier statement is cited; coverage gaps are stated on the page
+  ("rules before CY2002 not yet captured").
+
+## Non-goals
+
+- Printing or publishing dossiers outside the stack (they live behind
+  SSO like the rest).
+- Using licensed book content before the user supplies the books.
+- Cloud LLM calls.
+- Real-time updates; dossiers refresh on the nightly pipeline / on
+  demand.
+
+## Anti-goals (would make it a failure even if it works)
+
+- Unsourced or invented history (an origin story the sources don't
+  support).
+- Blurring proposed and final values, or CMS's summary of commenters with
+  our own count.
+- Editorial tone. The power analysis is shown through cited facts and
+  findings, in neutral language; the evidence carries the argument.
+- Profiling private individuals: individual commenters appear only in
+  counts and organization types, never as named profiles.
+
+## Constraints
+
+- Repo rules: main only, local-only LLMs, public data in the DR hoard
+  only (no ACO/WNOT/Wakely material), never spoof a browser UA for
+  FR/eCFR, hoard old copies of every source document.
+- GPU budget: the rig 4090 and rack 3060 are shared with tagging and
+  chat; extraction batches must be resumable.
+
+## Calls made after the builder check (mine, for review)
+
+- **How text gets onto a page.** Facts come from stored, cited rows:
+  valuation rounds, events, stances, identities, stakes, and a new
+  structured *origin* table linking each code to the statute, regulation,
+  program or demonstration behind it (extracted from FR preambles,
+  statute text and CMS program documents). The local model may write the
+  connective prose (summary paragraph, per-event "what changed" line)
+  **only from those rows**, and every sentence must carry at least one
+  row citation. A citation check rejects any sentence without one, and
+  rejects any number that differs from its cited row, before the page
+  renders. Hand-curation stays limited to family membership.
+- **Stance prediction.** Phase 1 ships an explicit rule from stakes to
+  expected stance (e.g. a payment cut to a specialty that bills the code
+  → expected oppose; new payment for a specialty's service → expected
+  support), shown beside actual stances so mismatches stand out. A
+  fitted, explainable model comes after the primary-care fan-out, once
+  many families supply stance and stakes data. The stakeholder unit is
+  **organization type × specialty**, with the named organizations listed
+  under it. Money stakes per specialty need specialty-level utilization,
+  which `pfs.utilization` lacks; the builder adds a public by-specialty
+  source (CMS Physician/Supplier Procedure Summary or the Medicare
+  Physician & Other Practitioners public-use files).
+
+## Left to the builder
+
+Storage schema for valuation rounds, stances and identities; extraction
+prompts and models (within local-only); the dossier page's framework
+(the llm service already serves the chat UI and `/search`, so a page
+there is the obvious home — builder's call); near-duplicate method for
+form letters; how far back public sources actually reach (report it).