From 9743d35469382268e44c745a6731bf24352d744b Mon Sep 17 00:00:00 2001 From: kert Date: Fri, 13 Nov 2026 01:14:02 -0500 Subject: [PATCH] =?UTF-8?q?docs(plans):=20lex=20S1=20=E2=80=94=20the=20liv?= =?UTF-8?q?e=20app=20(shell,=20Contents,=20Dossier,=20Sources)=20on=20a=20?= =?UTF-8?q?sliced=20policy=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/superpowers/plans/2026-11-13-lex-s1.md | 905 ++++++++++++++++++++ 1 file changed, 905 insertions(+) create mode 100644 docs/superpowers/plans/2026-11-13-lex-s1.md diff --git a/docs/superpowers/plans/2026-11-13-lex-s1.md b/docs/superpowers/plans/2026-11-13-lex-s1.md new file mode 100644 index 0000000..103111d --- /dev/null +++ b/docs/superpowers/plans/2026-11-13-lex-s1.md @@ -0,0 +1,905 @@ +# lex S1: the live app (shell, Contents, Dossier, Sources) Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Replace the static lex snapshot with the live one-page app at `https://lex.fhirworx.io/`: an app shell (left rail, main tabs, evidence drawer, state in the URL), Contents, the stored HOME-VISITS dossier rendered faithfully (header, summary, timeline, valuation, payment, politics, governance, gaps, review list) and read-only Sources, all fed by a sliced, cached JSON API on the llm service, behind SSO. + +**Architecture:** +- **API.** A FastAPI router `llm.policy` mounted at `/api/policy` on the llm service. It reads `pfs.dossier` from the DuckDB replica through `pfs.dossier.read_dossier`, parses each family once per replica mtime, and serves pre-serialized slices (`header`, `timeline`, `valuation`, `payment`, `politics`, `sources`, `facts`, plus `contents` and one `fact`). Pure slice builders live in `llm.policy_slices`. Responses carry an ETag (304 on match) and `Cache-Control: no-cache`; Traefik gzips them. +- **Page.** Gitea keeps serving `infra/gitea/custom/public/assets/dossier/index.html`, generated by `dev/scripts/dossier_page/build.py` from `template.html`. It inlines the fhirworx design system (R85) and no data. Vanilla ES modules sit beside it, committed, and load with a content-hash `?v=`. +- **Routing.** Two host+path routers on `lex.` (priority 1000, the `reach-releases` pattern): `lex-api` sends `/api/policy/…` to the llm service unchanged, and `lex-assets` sends flat `/assets/dossier/.js` to Gitea. Every other lex path still rewrites to the page (`lex-page`). auth-handler's sign-in redirect keeps the requested path and query. + +**Tech Stack:** Python 3.13, uv, FastAPI + Starlette TestClient, DuckDB (replica `data/replica/aco.ro.duckdb`, read-only), bib SQLite, PyYAML, pytest (xdist); browser: vanilla ES modules, inline SVG, no bundler, no npm dependencies; node:test in `node:22-slim` (docker) for JS unit tests; Playwright 1.61.0 in `mcr.microsoft.com/playwright/python:v1.61.0-noble` for headless probes; Traefik v3.3 file provider; nginx (auth-handler). + +**Spec:** +- `docs/superpowers/specs/2026-11-12-cms-legal-epi-platform-design.md`: "The app: one page", "Tech", the S1 bullet in "Build order". +- `docs/superpowers/specs/2026-11-11-code-family-dossier-design.md`: dossier page layout and anti-goals. +- Binding rulings in `.superpowers/sdd/2026-11-11-code-family-dossier-home-visits/progress.md`: R10, R42, R76, R79, R85, R98, the "Parked (S1 …)" lines (368, 353), and the Task 13 conditions file `task-13-conditions.md` in the same directory. +- Hosting decided after the spec (R79, user 2026-11-12): the app's address is `lex.`, not `git./dossier`. The spec's Tech section still says `git./dossier` and `/dossier/api` with a strip-prefix; this plan follows R79 and R98. + +## Global Constraints + +**Repository and commits** +- Commit straight to `main` in `/home/kert/stack`. No branches, worktrees, merge commits, PRs or `git stash`. `git add` explicit file paths only. +- Before every commit run `git status --short`. If anything you did not stage is staged, stop and ask. +- Another session (Plan A, Task 15 fix rounds) has uncommitted edits in `src/llm/dossier.py`, `src/llm/evidence.py`, `src/llm/rag.py`, `src/llm/web/chat.html` and `tests/llm/test_dossier.py`. Never stage, edit, format or revert those files. A failing test in them is theirs: report it, don't fix it. +- Commit messages use a conventional prefix (`feat(lex): …`) and carry no `Co-Authored-By` or other trailer. + +**Running things** +- Live commands run from the main checkout through the env wrapper `bash -c 'cd /home/kert/stack && set -a && . ./.env && set +a && uv run --no-sync '`, written **ENV** below. Never run a write command from a worktree. +- Tests: `uv run --no-sync pytest -q -p no:cacheprovider -n auto `. Lint: `uv run --no-sync ruff format && uv run --no-sync ruff check `. CI enforces `--cov-fail-under=99`, so test every branch of new Python. +- JS tests: `docker run --rm -v /home/kert/stack:/w:ro -w /w node:22-slim sh -c 'node --test tests/lex/*.test.mjs'` (written **NODE** below). Pass means `# fail 0`. +- `$S` is your session scratchpad directory. Run `mkdir -p "$S/lex"` once. +- Tests need no network, live DuckDB, bib file or Ollama. Live tests skip without `data/replica/aco.ro.duckdb` and `data/bib.sqlite`. + +**Live surfaces** +- `infra/gitea/custom/public/assets/dossier/index.html` (served live by Gitea), `infra/traefik/dynamic/services.yml` (Traefik watches it) and `infra/oauth2-proxy/auth-handler.conf` are live. +- Before Task 12, run build.py only with `--out "$S/lex/index.html"`. Touch services.yml and auth-handler.conf only in Task 11. +- JS modules committed to `infra/gitea/custom/public/assets/dossier/` are served at once, but nothing loads them until Task 12 swaps the page. +- Docker: run compose only from `/home/kert/stack`, never `docker compose down`, and probe on the `gateway` network. + +**Content rules (anti-goals made testable)** +- R10: the page never builds a citation URL. It renders `cite.url`, or `cite.locator` when `url` is empty, exactly as the API gives them. +- AMA: no CPT descriptor text anywhere. The API serves only `pfs.dossier` content. The JS has no descriptor source. Licensed books (`cite.kind == "cpt_book"`) never get a link or a viewer link. +- Task 13 display conditions, verbatim: + - stance counts appear only with their accuracy line; + - a lower-bound negative delta renders "a cut of at least $X" (the stored `delta_text`, never reformatted); + - RUC seats once per specialty; + - every `Dossier.review` item (31 live) is listed; + - facts with a `note` render the note ("model paraphrase, unreviewed" / "model extract, unreviewed") as a flag; + - commenter names as posted (the stored `names`, unchanged in case or spelling). +- CMS's own summaries (`cms_summary`) are always labelled "CMS's summary" and are never merged with our classification (`stance_split`). +- Proposed values sit in their own hatched columns with a "proposed" pill, never blended with final. +- Design: only fhirworx tokens (R85). Charts are inline SVG ported from the snapshot. No CDN scripts. Fonts stay as fhirworx.css loads them. +- S2 write actions show as disabled controls marked `coming · S2`: Add source, Flag this, Accept/Correct/Reject, Propose a new family. No market-tier UI. +- Any network client sends an honest User-Agent (`stack-lex-linkcheck/1.0`). A 401/403/429 or bot page is recorded as "refused", never worked around. + +## Review Focus + +1. **The SSO session expires while lex is open.** The next API call is redirected to `auth.`, which `fetch` sees as an opaque redirect or an HTML login page. The app should show a "signed out, reload to sign in" panel that links to the current URL, never a blank pane or an uncaught error. Pinned in Task 5: `api.test.mjs` "opaque redirect is SignedOut" and "html body is SignedOut"; `shell.test.mjs` "signed-out panel links to the current URL". +2. **A family with no stored dossier.** Cases: a planned family (`?family=CCM`), a curated one not yet built, a derived key with a slash (`A/D-TX-PROGRAM-HOUR`, one of 916 such keys), a lower-case key. Each should get a 404 carrying the family's status and a message linking to Contents. Lower case is normalized, and a slash never causes a 400. Pinned in Task 3 (`test_no_dossier_404_with_status`, `test_slash_family_key_is_valid`, `test_lowercase_family_normalized`) and Task 5 (`shell.test.mjs` "not-found panel names the status"). +3. **The dossier is rebuilt or the replica republished while the app is open.** Slices fetched before and after would mix two builds. The server cache should reload on the replica mtime, and the client should refetch every slice when `built_at` differs. Pinned in Task 3 (`test_cache_reloads_after_replica_republish`) and Task 5 (`api.test.mjs` "mixed builds refetch"). +4. **A citation without a URL** (licensed CPT books, an unresolved reference), or one with `also` cites. It should render as a plain locator ``, never ``, and every also-cite should render too. Pinned in Task 5 (`cite.test.mjs` "no url renders a locator span", "also cites render"), Task 1 (the IOM references resolve) and Task 4 (`test_live_citations_resolve`). +5. **The replica is missing or has no `pfs.dossier` table** (fresh boot, republish in progress). The API should answer 503 or 404 JSON, never 500, and the app should show an "unavailable" panel. Pinned in Task 3 (`test_replica_missing_503`, `test_table_missing_404`) and Task 5 (`shell.test.mjs` "unavailable panel"). + +--- + +## Decisions (each one is the planner's call unless a ruling is cited) + +- **D1 URL state (planner's call).** + - The path is the view, `?family=KEY` is the only query parameter, and the fragment holds view-local state (`#code=99343&fact=F12`). Example: `/timeline?family=HOME-VISITS#code=99343`. + - Why: the login redirect keeps path and query but drops the fragment (it is never sent to the server). Family keys can contain `/`, so a family cannot be a path segment. + - R98's `/?family=KEY#dossier` and the snapshot's bare `#view` are read and rewritten with `history.replaceState`. View and family changes push history; fragment changes replace it. +- **D2 API route (planner's call).** `lex.` + `PathPrefix(/api/policy/)` → service `llm`, priority 1000, middlewares `git-sso, lex-api-compress, secure-headers`. + - No stripPrefix: the browser path and the service path are both `/api/policy/…`. + - Only that prefix is exposed: chat, search, `/pdf` and the viewer stay on `llm.`. + - This follows the `reach-releases` host+path pattern; the `lex` `$multi` entry stays as it is. +- **D3 Module route (planner's call).** `lex-assets`: `PathRegexp(^/assets/dossier/[a-z][a-z0-9-]*[.]js$)` → service `git`, with `git-sso, dossier-nocache, secure-headers`. + - Flat names only, so no literal or encoded dot-segment matches. This closes the parked lex-assets item (line 368). + - The git-host `dossier-assets` router stays as it is. + - No API path needs an exemption from `lex-page`, because the higher-priority routers take `/api/policy/` and the module names first. +- **D4 rd fix (planner's call).** auth-handler builds `rd` from `X-Forwarded-Uri`. Traefik's ForwardAuth calls nginx at `/`, so `$request_uri` is always `/`. A `map` encodes up to three `&` as `%26`, because oauth2-proxy reads `rd` as a query parameter. lex URLs never need an `&` in the query (D1). +- **D5 Page assembly (planner's call).** + - The JS modules are source files committed in the served directory. + - build.py keeps only the design-system inlining (R85) and stamps `?v=` on the entry script. It no longer reads any database. + - Imported modules revalidate through `dossier-nocache`. +- **D6 Slices and cache (planner's call).** + - Family travels as a query parameter. + - Every fact kind has one home view, and each view renders all of its home facts, with an "unplaced" list for facts no row or event claims. + - The cache is keyed by replica mtime, holds at most 16 families, and stores pre-serialized bytes. + - ETag = `"sha1(body)[:20]"`. Compression comes from Traefik's `compress` middleware on `lex-api`, not from app code. + - `load_slice()` is the in-process seam Plan A Task 16's golden test uses. +- **D7 Book registry (planner's call).** `src/pfs/book.yaml` lists the reviewed-tier families in build order. Each entry has a phase, value domains (from the spec's nine) and the planned code text, taken from the snapshot's PLANNED list. Value-domain assignments are mine, for the user to review. Tier: curated (`src/pfs/curated.yaml`) → "reviewed"; any other stored dossier → "machine". +- **D8 Tabs (planner's call).** The tabs are the snapshot's set, which the user has seen: + - `book`: Contents; + - ``: Dossier, Timeline, Valuation, Payment, Politics, Sources; + - `coming`: Grid, Evaluate, Predict, Draft, Review. + + Timeline, Valuation and Payment are the spec's dossier sections given full-width tabs. Review is live as a read-only list of `Dossier.review` with disabled actions. The other coming tabs are one-paragraph panels with disabled controls; the snapshot's sketches, built from raw tables, are dropped. +- **D9 Source status (planner's call).** Three statuses only: + - "full text on file": an FR rule with paragraph anchors, or a bib item with an attachment; + - "licensed book: paraphrased, cited by page"; + - "link only". + + "Wanted" and "paywalled" live only in CSV lists today, so they wait for S2's analyst store. Viewer links (`https://llm./ui/pdf/`) go only to non-rule items that have an attachment, never to licensed books. +- **D10 IOM links (planner's call).** The acceptance requires every fact's link. Two IOM references have no URL in the stored dossier ("100-04 ch.26" as a primary cite, "100-04 ch.12 §30.6.14.1" as an also-cite). Task 1 resolves them to the manual chapter PDF in bib and rebuilds the dossier with `--no-llm`, which needs no GPU. Licensed-book cites stay locator-only by design. +- **D11 Navbar link deferred (planner's call).** A Gitea navbar link and a Gitea homelab tile take effect only after a Gitea restart, and a broken template would take every Gitea page down. They are deferred to the next planned Gitea recreate, together with the parked `:3000` bind fix. The dashboard landing already has a lex tile. +- **D12 Roll safety (planner's call).** + - The llm image is built from `git archive HEAD` whenever image inputs carry another session's uncommitted edits, so their work never ships. + - The other services that share `COMMIT_SHA` (api, bcda, docs, mc) get their current images re-tagged to the new SHA so their tags resolve. They are not recreated. +- **D13 Verification harness (planner's call).** + - A throwaway `traefik:v3.3` on `gateway` loads a copy of the live `services.yml` with stub ForwardAuth. This is the S0b method, described in `task-s0-report.md` § "Signed-in simulation". + - A Playwright probe drives a real Chromium either through that Traefik (`--host-resolver-rules`) or, before the roll, against API slices dumped to files, with request routing that mirrors the three lex routers. + +## File map + +| File | Responsibility | Task | +|---|---|---| +| `src/pfs/guidance.py`, `src/pfs/cite.py`, `src/pfs/dossier.py` (mod) | IOM/MLN references carry their bib URL | 1 | +| `src/pfs/book.yaml`, `src/pfs/book.py` | The book's table of contents: phase, domains, planned families | 2 | +| `src/llm/policy_slices.py` | Pure slice builders (no I/O) | 2, 4 | +| `tests/llm/policy_fixture.py` | The fixture dossier every API and JS test shares | 2 | +| `tests/lex/fixtures/*.json` | API slices of the fixture (contract between API and JS; regenerated by a test) | 2, 4 | +| `src/llm/policy.py`, `src/llm/api.py` (mod) | Router, cache, errors, bib lookups, `load_slice` | 3, 4 | +| `dev/scripts/dossier_page/template.html`, `build.py` (rewrite) | App shell page and design-system inlining | 5 | +| `infra/gitea/custom/public/assets/dossier/{app,state,api,fmt,cite,shell}.js` | Boot and DOM wiring; URL state; API client; formatting; citations and drawer; rail, tabs, masthead and error panels | 5 | +| `infra/gitea/custom/public/assets/dossier/view-{contents,dossier,review,coming,timeline,valuation,payment,politics,sources}.js` | One module per view: `needs`, `render(data, state)`, optional `mount(root, data, state, nav)` | 5 (stubs), 6–10 | +| `tests/lex/*.test.mjs`, `tests/lex/test_js.py`, `tests/dev/test_dossier_page_build.py` | JS unit tests, their pytest wrapper, build test | 5–10 | +| `dev/scripts/lex_dump_api.py`, `dev/scripts/lex_probe.py`, `dev/scripts/lex_linkcheck.py` (+ `tests/dev/test_lex_*.py`) | Dump slices; headless probe; live link check | 5, 12 | +| `infra/traefik/dynamic/services.yml`, `infra/oauth2-proxy/auth-handler.conf` (mod) | lex-api and lex-assets routers; rd keeps the request URI | 11 | + +Order: Task 1 is independent. Tasks 2 → 3 → 4 build the API. Task 5 needs 4. Tasks 6–10 need 5 and may run in any order, one at a time. Task 11 needs 5. Task 12 comes last. + +--- + +### Task 1: IOM references carry their manual chapter's link + +**Files:** +- Modify: `src/pfs/guidance.py` (add `reference_url`), `src/pfs/cite.py` (`reference_cite` gains `url`), `src/pfs/dossier.py` (`_Bib.reference_url`, `_origin_facts`) +- Test: `tests/pfs/test_guidance.py`, `tests/pfs/test_cite.py`, `tests/pfs/test_dossier.py` + +**Interfaces:** +- Produces: + - `pfs.guidance.reference_url(store: Any, kind: str, locator: str) -> str`: + - `"iom"`: the locator matches `^(?P\d{3}-\d{2})\s+ch\.\s*(?P\d+[A-Z]?)`; the result is the URL of `resolve_iom(store, pub, ch)`'s item; + - `"mln"`: the URL of `resolve_mln(store, locator)`'s item; + - anything unresolved: `""`. + - `pfs.cite.reference_cite(kind, locator, *, item_key="", p_id=0, page=0, url="") -> Cite`: CFR keeps `_cfr_url(locator)`; any other kind uses `url`. + - `_Bib.reference_url(kind, locator) -> str`, cached per `(kind, locator)`. + +- [ ] **Step 1: Failing tests** + - In `tests/pfs/test_guidance.py`, using the existing `store` fixture with the chapter-12 item set to url `https://www.cms.gov/x/clm104c12.pdf` via `s.update`: + - `test_reference_url_iom_chapter`: `reference_url(s, "iom", "100-04 ch.12 §30.6.14.1") == "https://www.cms.gov/x/clm104c12.pdf"`; + - `test_reference_url_unresolved_is_empty`: `reference_url(s, "iom", "100-04 ch.5") == ""`, `reference_url(s, "iom", "chapter 12") == ""` and `reference_url(s, "statute", "x") == ""`. + - In `tests/pfs/test_cite.py`, `test_reference_cite_keeps_given_url`: `reference_cite("iom", "100-04 ch.26", url="u").url == "u"`, and a CFR locator still yields its eCFR URL. + - In `tests/pfs/test_dossier.py`, `test_origin_iom_cite_carries_manual_url`: follow the existing origin-fact fixture, add one `iom` origin row "100-04 ch.12" and the tagged manual item, and assert the fact's IOM cite (primary or also) has that URL. +- [ ] **Step 2: Run** the three files → FAIL. +- [ ] **Step 3: Implement** the three signatures. In `_origin_facts`, every `reference_cite(...)` call passes `url=bib.reference_url(cite_kind, ref)`. +- [ ] **Step 4: Run** → PASS; ruff on the touched files. +- [ ] **Step 5: Live rebuild (no GPU).** + - Record the stored dossier first: `ENV python -c "import duckdb; from pfs.dossier import read_dossier; d=read_dossier(duckdb.connect('data/replica/aco.ro.duckdb',read_only=True),'HOME-VISITS'); print(len(d.facts), d.fallbacks, d.summary[:80])"`. Expected: `546 ['CY2021 formation'] For CY2008, …`. + - Run `ENV stack pfs dossier --family HOME-VISITS --no-llm`. It should print the same fact count and a passing check. + - Run `ENV stack pfs dossier --family HOME-VISITS --no-llm --write`. + - Re-run the record command. Expected: the same count, the same fallbacks, an identical summary. + - Then run `ENV python -c` and count cites (primary and also) with an empty `url` and `kind != "cpt_book"`. Expected: `0`. + - If the fallbacks grew, the ledger replay missed: stop and report, do not re-run with the model. If the write fails on the DuckDB lock, wait and retry; never kill another writer. +- [ ] **Step 6: Commit** `git add src/pfs/guidance.py src/pfs/cite.py src/pfs/dossier.py tests/pfs/test_guidance.py tests/pfs/test_cite.py tests/pfs/test_dossier.py && git commit -m "fix(pfs): IOM and MLN references link their manual chapter (lex S1 acceptance)"` + +--- + +### Task 2: Book registry and dossier slices (pure) + +**Files:** +- Create: `src/pfs/book.yaml`, `src/pfs/book.py`, `src/llm/policy_slices.py`, `tests/llm/policy_fixture.py`, `tests/pfs/test_book.py`, `tests/llm/test_policy_slices.py`, `tests/lex/fixtures/{header,timeline,valuation,payment,politics,facts}.json` (generated) + +**Interfaces:** +- Consumes: `pfs.dossier.{Dossier, Fact, FACT_KINDS, compact, stance_accuracy_line}`, `pfs.cite.Cite`. +- Produces, in `pfs/book.py`: + - `DOMAINS` is the spec's nine domains, in its order: primary care, care management and coordination, behavioral health integration, home-based care, telehealth and virtual care, APM linkage, quality reporting, bundling and global packages, prevention. + - `@dataclass(frozen=True) BookEntry(key: str, name: str, phase: int, domains: tuple[str, ...], codes: str)`. + - `load_book(path: Path | None = None) -> dict[str, BookEntry]` keeps YAML order (= build order), normalizes keys with `normalize_key`, and raises `ValueError` naming the key on: an unknown domain, a phase outside 1–3, an empty name or a duplicate key. +- Produces, in `llm/policy_slices.py`: + - Constants: + - `API_VERSION = 1`; + - `SECTIONS = ("header", "timeline", "valuation", "payment", "politics", "sources", "facts")`; + - `ACCURACY_MARK = "Preliminary model classification"`; + - `VIEW_OF_KIND`: origin, formation and finding → "dossier"; event and link → "timeline"; round and pe → "valuation"; payment → "payment"; cms_summary, stance_split, money, seat and impact → "politics"; + - `SECTION_OF_VIEW = {"dossier": "header", "timeline": "timeline", "valuation": "valuation", "payment": "payment", "politics": "politics"}`; + - `ROUND_OPTIONAL = ("ruc_percentile", "survey_intra_min", "survey_total_min", "comparators", "surveying_societies", "requested_work_rvu", "rationale_quote", "pe_note")`. + - Every slice starts with `{"api": 1, "family", "built_at"}`. + - `fact_json(f: Fact, accuracy: str = "") -> dict`: `asdict(f)` plus `"view"`. A `stance_split` fact whose text lacks `ACCURACY_MARK` gains `"accuracy": accuracy or stance_accuracy_line(None)`. + - `code_groups(d) -> {"active": [...], "deleted": [...], "linked": [...]}`: + - latest = the max year of the final payment rows; + - active = codes in `d.codes` with a final row in latest; + - deleted = the rest of `d.codes`; + - linked = codes in payment rows that are not in `d.codes`; + - all three sorted. + - `document_key(c: Cite) -> str`: `item_key`, else `url` without the fragment, else `label`. + - `last_rule(d) -> dict | None`: among facts of kind event, round, link, cms_summary, origin or formation whose cite kind is `fr_para` or `fr_page`, take the max `(year, cite.p_id)` and return `{"year", "label", "url"}`. + - `header_slice(d, *, tier: str, book: BookEntry | None) -> dict`. Keys: + - `family`, `name`, `tier`, `phase`, `domains`, `codes`, `code_groups`, `status`, `years_active`, `summary`; + - `facts` (keyed by id): the summary's `[F#]` tags ∪ origin/formation/finding facts ∪ review fact ids; + - `governance` (excerpts), `gaps`, `review` (every item, verbatim), `fallbacks`, `stance_accuracy`, `check_passed`, `extractor`, `version`; + - `counts = {"facts", "timeline", "rounds", "payment_rows", "panels", "governance", "review", "gaps"}`. + - `timeline_slice(d)`: `events` (asdict), `facts` (every id the events reference ∪ every event/link fact), `unplaced` (sorted event/link ids no event references). + - `valuation_slice(d)`: `rounds` (asdict without `field_cites`), `columns` (the `ROUND_OPTIONAL` fields with any non-empty value, in that order), `facts` (round and pe). + - `payment_slice(d)`: + - `rows` and `utilization`; + - `years` (sorted distinct) and `code_groups`; + - `cells` maps `"{code}|{vintage}"` to a fact id, for payment facts by `codes[0]` and `values["vintage"]`; + - `unplaced` holds payment facts with no row; + - `facts`. + - `politics_slice(d)`: + - `panels` is `d.stakeholders` with `accuracy` filled: the stored value, else `d.stance_accuracy`, else `stance_accuracy_line(None)`; units and names unchanged; + - `stance_accuracy`; + - `facts` (cms_summary, stance_split, money, seat, impact). + - `facts_index(d)`: `{"facts": [{"id", "kind", "year", "view", "label", "url", "locator", "note", "also": [urls]}]}`. + - `fact_detail(d, fact_id) -> dict | None`. + +- [ ] **Step 1: The book.** `src/pfs/book.yaml` has `families:` in this order: + - HOME-VISITS (Home or Residence Services; phase 1; home-based care, primary care; codes ""); + - OFFICE-EM (Office/outpatient E/M; primary care; ""); + - G2211-B1-B2 (G2211 and modifiers B1/B2; primary care; "G2211, B1, B2"); + - CCM (Chronic care management (CCM); care management and coordination, primary care; "99490, 99491, 99487–99489, 99437, 99439, G2058"); + - PCM (Principal care management (PCM); care management and coordination; "99424–99427, G2064, G2065"); + - TCM (Transitional care management (TCM); care management and coordination, primary care; "99495–99496"); + - APCM (Advanced primary care management (APCM); primary care, care management and coordination, APM linkage; "G0556–G0558"); + - CPO-HH (Care plan oversight and home health certification; home-based care, care management and coordination; "G0179–G0182, 99339, 99340, 99374–99380"); + - BHI-COCM (Behavioral health integration and CoCM; behavioral health integration; "99484, 99492–99494"); + - RPM-RTM (Remote physiologic and therapeutic monitoring (RPM/RTM); telehealth and virtual care, care management and coordination; ""); + - ACP (Advance care planning (ACP); primary care; "99497–99498"); + - PROLONGED (Prolonged services; primary care; "99354–99357, 99417, 99418, G0316–G0318"); + - VIRTUAL (Virtual check-ins and communication-technology services; telehealth and virtual care; "G2010, G2012, G2252"). + + All are phase 1. The header comment says domains are the curator's classification. + + Tests: + - `test_book_build_order`: the keys start with `["HOME-VISITS", "OFFICE-EM"]`, `len == 13`, and `book["APCM"].domains[-1] == "APM linkage"`; + - `test_book_rejects_unknown_domain`, `test_book_rejects_bad_phase`, `test_book_rejects_duplicate_key` (tmp YAML; `pytest.raises(ValueError, match=KEY)`). +- [ ] **Step 2: The fixture dossier.** `tests/llm/policy_fixture.py: fixture_dossier(*, stance_accuracy: str = ACC) -> Dossier`, with no real CPT text. Contents: + - Identity: family HOME-VISITS, name "Home or Residence Services", codes `("99341", "99343")`, `built_at "2026-11-13T05:23:37"`, `fallbacks ["CY2021 formation"]`, `extractor "model:qwen2.5:14b+template"`, `check_passed True`. + - Summary: `"For CY2023, CMS finalized work RVUs for 99341 [F4]. 99343 was deleted for CY2023 [F3][F3]."` + - Facts, one per kind, plus extras. Item `PETM225D` is cited by F3, F4, F6 and F9 only. + - F1 origin (fr_para MZ24MX5S ¶878; also a statute cite with url); + - F2 formation (`cpt_book` item BOOK2019, url "", locator "CPT 2019 p. 20", note UNREVIEWED); + - F3 event 2023, PETM225D ¶1672; + - F4 round 2023 99341, PETM225D ¶1676; + - F5 pe, MZ24MX5S ¶877 (note UNREVIEWED_EXTRACT); + - F6 cms_summary 2023, PETM225D ¶1679; + - F7 stance_split 2023, text containing ACC; + - F8 stance_split 2018, without the mark; + - F9 link 2023 G0318, PETM225D ¶1694; + - F10 payment 99343 "CY2022 final"; + - F11 payment 99341 "CY2023 final"; + - F12 payment 99341 "CY2027 proposed"; + - F13 impact; F14 money; F15 seat; + - F16 finding (study cite, item ART1); + - F17 event 2021, referenced by no timeline event; + - F18 payment for 99999 (no row). + - Timeline: + - E1 2023 "deleted", codes `("99343",)`, facts `(F3,)`, line "99343 was deleted for CY2023 [F3]."; + - E2 2023 "valuation", codes `("99341",)`, facts `(F4,)`, stance `(F7,)`, cms `(F6,)`; + - E3 2023 "link:G0318", codes `("G0318",)`, facts `(F9,)`. + - Rounds: + - 99341 2023 final PETM225D: ruc_percentile "25th", rationale_quote "We are finalizing the RUC-recommended values."; + - 99343 2008 final 54GTKR5G: requested 2.85; + - all other optional fields empty. + - Payment rows: 99343 2022 final; 99341 2023 final; 99341 2027 proposed; G0318 2023 final. Two utilization rows. + - One stakeholder panel, accuracy `""`, roster_year 2022. Units: + - (specialty_society, CARDIOLOGY, `["American College of Cardiology"]`, `{"support": 1}`, delta_text "a cut of at least $12,106", lower bound); + - (individual_clinician, CARDIOLOGY, `["jane q. DOE"]`, `{"modify": 1}`); + - (health_system, NONE, `["ACME health LLC"]`, `{}`). + + Seats `{"CARDIOLOGY": {"ruc_permanent": 1, "ruc_rotating": 0, "cpt": 0, "holders": ["American College of Cardiology"], "item_keys": ["AAAA1111"]}}`. + - One governance excerpt (study cite, item ART1); two gaps. + - Review: F2, F5, plus one held summary (`fact_id ""`, quote, cite, response). +- [ ] **Step 3: Failing slice tests** (`tests/llm/test_policy_slices.py`): + +```python +def test_every_fact_kind_has_a_home_view(): + assert set(VIEW_OF_KIND) == set(FACT_KINDS) +def test_every_fact_is_served_by_its_home_view(d): + s = {k: build(k, d) for k in SECTION_OF_VIEW.values()} + for f in d.facts.values(): + assert f.id in s[SECTION_OF_VIEW[VIEW_OF_KIND[f.kind]]]["facts"] +def test_header_slice(d): + h = header_slice(d, tier="reviewed", book=load_book()["HOME-VISITS"]) + assert {"F1", "F2", "F3", "F4", "F5", "F16"} <= set(h["facts"]) and len(h["review"]) == 3 + assert h["counts"] == {"facts": 18, "timeline": 3, "rounds": 2, "payment_rows": 4, "panels": 1, "governance": 1, "review": 3, "gaps": 2} + assert h["code_groups"] == {"active": ["99341"], "deleted": ["99343"], "linked": ["G0318"]} + assert h["domains"] == ["home-based care", "primary care"] and h["tier"] == "reviewed" +def test_timeline_slice(d): + t = timeline_slice(d); assert set(t["facts"]) == {"F3", "F4", "F6", "F7", "F9", "F17"} and t["unplaced"] == ["F17"] +def test_valuation_slice_omits_empty_columns(d): + v = valuation_slice(d); assert v["columns"] == ["ruc_percentile", "requested_work_rvu", "rationale_quote"] + assert "field_cites" not in v["rounds"][0] and set(v["facts"]) == {"F4", "F5"} +def test_payment_slice_maps_facts_to_cells(d): + p = payment_slice(d) + assert p["cells"] == {"99343|CY2022 final": "F10", "99341|CY2023 final": "F11", "99341|CY2027 proposed": "F12"} + assert p["unplaced"] == ["F18"] and p["years"] == [2022, 2023, 2027] +def test_politics_slice_never_counts_without_accuracy(d): + p = politics_slice(d) + assert p["panels"][0]["accuracy"] == ACC + assert "accuracy" not in p["facts"]["F7"] and p["facts"]["F8"]["accuracy"] == ACC + assert [u["names"] for u in p["panels"][0]["units"]][1] == ["jane q. DOE"] + assert p["panels"][0]["units"][0]["delta_text"] == "a cut of at least $12,106" + assert politics_slice(fixture_dossier(stance_accuracy=""))["panels"][0]["accuracy"] == stance_accuracy_line(None) +def test_facts_index_and_detail(d): + idx = {e["id"]: e for e in facts_index(d)["facts"]} + assert len(idx) == 18 and idx["F2"]["url"] == "" and idx["F2"]["locator"] == "CPT 2019 p. 20" + assert fact_detail(d, "F4")["view"] == "valuation" and fact_detail(d, "F999") is None +def test_last_rule_is_latest_fr_cite(d): + assert last_rule(d)["label"] == d.facts["F9"].cite.label +def test_js_fixtures_match_api(d): # LEX_UPDATE_FIXTURES=1 rewrites tests/lex/fixtures/
.json first + for name, body in dossier_fixture_slices(d).items(): + assert json.loads((FIXTURES / f"{name}.json").read_text()) == body +``` + +- [ ] **Step 4: Run** `tests/pfs/test_book.py tests/llm/test_policy_slices.py` → FAIL. +- [ ] **Step 5: Implement** `pfs/book.py` and `llm/policy_slices.py`. Module scope imports only stdlib and pfs. Builders return plain JSON-serializable dicts; serializing is Task 3's job. +- [ ] **Step 6: Generate fixtures** `LEX_UPDATE_FIXTURES=1 uv run --no-sync pytest -q -p no:cacheprovider tests/llm/test_policy_slices.py::test_js_fixtures_match_api`. Then run both files without the variable → PASS, and check 100% coverage: `--cov=pfs.book --cov=llm.policy_slices --cov-report=term-missing`. Ruff. +- [ ] **Step 7: Commit** `git add src/pfs/book.yaml src/pfs/book.py src/llm/policy_slices.py tests/llm/policy_fixture.py tests/pfs/test_book.py tests/llm/test_policy_slices.py tests/lex/fixtures && git commit -m "feat(lex): the book registry and the dossier sliced per view (S1)"` + +--- + +### Task 3: The policy API: router, cache, errors + +**Files:** +- Create: `src/llm/policy.py`, `tests/llm/test_policy_api.py` +- Modify: `src/llm/api.py` (one `app.include_router(policy.router)`) + +**Interfaces:** +- Consumes: the Task 2 builders; `llm.evidence._replica_path/_connect/_mtime`; `pfs.dossier.read_dossier`; `pfs.curated.load_curated`; `pfs.book.load_book`; `pfs.families.{normalize_key, FAMILIES}`. +- Produces: + - `router = APIRouter(prefix="/api/policy")`. Module scope imports fastapi and stdlib only, as `llm.api` does. + - Constants: `KEY_RE = re.compile(r"^[A-Z0-9][A-Z0-9@/_.-]{0,199}$")`; `CACHE_MAX = 16`. + - `class PolicyError(Exception)` with `status: int` and `detail: dict`. + - Dependency seams: `config_dep() -> LlmConfig` (`llm.config.load()`); `bib_dep() -> Callable[[], Any]` (returns `conf.connect.bib`). + - `load_slice(cfg, family: str, section: str, *, bib: Callable[[], Any] | None = None) -> dict` and `load_fact(cfg, family, fact_id) -> dict`: the in-process API that both HTTP and tests use. + - `clear_cache() -> None`. + - `GET /api/policy/dossier/{section}?family=KEY` and `GET /api/policy/fact?family=KEY&id=F12` (`id` pattern `^F\d{1,6}$`). + - Every 200 response carries `application/json`, `ETag: ""` and `Cache-Control: no-cache`. A matching `If-None-Match` gets 304. + - Errors are `{"detail": {...}}`: + - 400 `{"message": "invalid family key", "family"}`; + - 404 `{"message": "unknown section", "sections": [...]}`; + - 404 `{"message": "No dossier is built for KEY yet.", "family", "status"}` with status `"curated"` (in curated.yaml), `"planned"` (in book.yaml), `"derived"` (in `FAMILIES`) or `"unknown"`, checked in that order; + - 404 for an unknown fact; + - 503 `{"message": "The data replica is not available."}` when the replica file is missing or `_connect` raises. + - The cache is an `OrderedDict` keyed by family, with value `(mtime, Dossier, {section: bytes})`, guarded by a `threading.Lock` and LRU-evicted past `CACHE_MAX`. A request whose mtime differs re-reads that family. Each DuckDB read uses its own `.cursor()`, closed after. + +- [ ] **Step 1: Failing tests.** + - The fixture writes `fixture_dossier()` into a tmp replica (`ensure_tables`, `write_dossier`). It sets `app.dependency_overrides[config_dep] = lambda: replace(CFG, duckdb_replica=str(path))`, where `CFG` is the `LlmConfig` literal from `tests/llm/test_dossier.py`, copied (do not import that file: it belongs to the other session). It resets `evidence._REPLICA = None` and `clear_cache()` before and after. + - Tests: + - `test_section_ok_etag_and_304`: 200, `r.json()["family"] == "HOME-VISITS"`, `r.headers["cache-control"] == "no-cache"`; the same GET with `If-None-Match: r.headers["etag"]` → 304. + - `test_lowercase_family_normalized`: `family=home-visits` → 200, family `HOME-VISITS`. + - `test_bad_family_400`: `family="a b"` and `family="../x"` → 400; a missing family → 422. + - `test_unknown_section_404`: `/dossier/nope` → 404 with `sections == list(SECTIONS)`. + - `test_no_dossier_404_with_status`: CCM → 404 `status == "planned"`; a family in curated.yaml with no row (monkeypatch `load_curated`) → `"curated"`; `ZZZ-NONE` → `"unknown"`. + - `test_slash_family_key_is_valid`: `params={"family": "A/D-TX-PROGRAM-HOUR"}` → 404 (not 400). + - `test_replica_missing_503`. + - `test_table_missing_404`: the replica file exists but has no `pfs` schema. + - `test_cache_reloads_after_replica_republish`: GET header; rewrite with `built_at "2026-11-14T00:00:00"`; `os.utime(path, (t + 5, t + 5))`; GET again → the new `built_at` and a new ETag. + - `test_cache_reads_dossier_once_per_mtime`: count `read_dossier` calls over GET header, timeline, payment → 1. + - `test_cache_bounded`: `monkeypatch.setattr(policy, "CACHE_MAX", 1)`; two families → the first is evicted (its `read_dossier` count goes up on re-request). + - `test_fact_endpoint`: F4 → 200 `view == "valuation"`; F999 → 404; `id=x` → 422. + - `test_load_slice_matches_http`. + - `test_router_mounted_on_app`: `"/api/policy/dossier/{section}" in {r.path for r in app.routes}`. +- [ ] **Step 2: Run** `tests/llm/test_policy_api.py` → FAIL. +- [ ] **Step 3: Implement** `policy.py` and the include line in `api.py`, placed directly after `app = FastAPI(...)`. Never touch the other session's files. +- [ ] **Step 4: Run** `tests/llm/test_policy_api.py tests/llm/test_policy_slices.py tests/llm/test_api.py` → PASS, with `--cov=llm.policy` at 100%. Ruff. +- [ ] **Step 5: Live, in process.** `ENV python -c "from llm import config; from llm.policy import load_slice; h=load_slice(config.load(),'HOME-VISITS','header'); print(h['counts'], h['tier'], len(h['review']))"`. Expected: `facts 546`, `reviewed`, `31`. +- [ ] **Step 6: Commit** `git add src/llm/policy.py src/llm/api.py tests/llm/test_policy_api.py && git commit -m "feat(llm): /api/policy — the dossier sliced and cached per replica, ETag/304 (lex S1)"` + +--- + +### Task 4: Contents and Sources slices; live API acceptance + +**Files:** +- Modify: `src/llm/policy_slices.py`, `src/llm/policy.py`, `tests/llm/test_policy_slices.py`, `tests/llm/test_policy_api.py` +- Create: `tests/llm/test_policy_live.py`, `tests/lex/fixtures/{sources,contents}.json` + +**Interfaces:** +- Produces in `policy_slices`: + - `@dataclass(frozen=True) SourceInfo(title: str, url: str, full_text: bool, is_rule: bool)`. + - `SOURCE_GROUPS: dict[str, str]` maps a cite kind to its group: `fr_para`/`fr_page` → "Federal Register rules"; `cfr` → "Regulations (eCFR)"; `statute` → "Statute"; `iom`/`mln` → "CMS manuals"; `rvu_file` → "RVU files"; `dataset` → "Data files"; `cpt_book` → "Books (licensed)"; `study` → "Studies"; anything else → "Other". + - `SOURCE_GROUP_ORDER` is that list of groups, in that order. + - `sources_slice(d, info: Mapping[str, SourceInfo], *, viewer_base: str) -> dict`: + - `documents`: `[{"key", "group", "title", "url", "status", "viewer_url", "cites": [{"label", "url", "locator"}], "n_facts"}]`, grouped by `document_key` over every fact's cite and also-cites plus the governance cites, sorted by group order then title; + - `counts`: `{group: n}`; + - the title is the bib title, else the first label; + - the status follows D9; + - `viewer_url = viewer_base + key` only when `full_text and not is_rule and group != "Books (licensed)"`. + - `contents_entry(d, *, tier, book) -> dict`, with keys `family`, `name`, `tier`, `phase`, `domains`, `codes_text` (`compact(d.codes)`), `status`, `years_active`, `built_at`, `check_passed`, `sections`, `gaps`, `n_review`, `last_rule` and `comment_period: None`. + - `sections = {"timeline": n_events, "valuation": n_rounds, "payment": "CY2015–CY2027" or "", "politics": n_panels, "governance": n, "sources": n_documents}`. + - `contents_slice(entries: list[dict], book: dict[str, BookEntry], curated: set[str], machine: tuple[int, int] | None) -> dict`: + - `families` is entries sorted by (phase or 9, name); + - `planned` holds every book entry without a built dossier, `{"family", "name", "phase", "domains", "codes", "status": "curated, not built" if key in curated else "planned"}`, in book order, followed by curated families that are not in the book; + - `machine = {"derived": n, "single_code": n} | None`. +- Produces in `policy`: + - `bib_info(store, keys) -> dict[str, SourceInfo]`: the `items` row; `is_rule` and `full_text` when an `fr_anchor_docs` row exists; `full_text` when there is an `attachments` row. + - `GET /api/policy/contents`, plus section `sources`. + - `viewer_base = f"https://llm.{os.environ.get('DOMAIN') or cfg.domain}/ui/pdf/"`. + - Machine counts come from `SELECT count(*), count(*) FILTER (WHERE n = 1) FROM (SELECT key, count(DISTINCT code) AS n FROM pfs.code_family GROUP BY key)`; a missing table gives `None`. +- Produces for Plan A Task 16: assert against `load_slice(cfg, "HOME-VISITS",
)`, or `TestClient(llm.api.app)` with `config_dep` overridden to the live replica. For example, `valuation` `rounds` keyed by `(code, item_key)`, `timeline` `facts` (`cms_summary` with `cite.p_id == 1679`), `payment` `rows` for 99343, and `header` `gaps` / `check_passed`. + +- [ ] **Step 1: Failing tests**: + +```python +def test_sources_slice_groups_documents(d, info): # info: PETM225D rule full_text; ART1 article with attachment; book keys + s = sources_slice(d, info, viewer_base="https://llm.fhirworx.io/ui/pdf/") + fr = next(x for x in s["documents"] if x["key"] == "PETM225D") + assert fr["group"] == "Federal Register rules" and fr["status"] == "full text on file" and fr["viewer_url"] == "" + assert len(fr["cites"]) == 4 and fr["n_facts"] == 4 # ¶1672, ¶1676, ¶1679, ¶1694 + book = next(x for x in s["documents"] if x["group"] == "Books (licensed)") + assert book["status"] == "licensed book: paraphrased, cited by page" and book["viewer_url"] == "" and book["url"] == "" + assert next(x for x in s["documents"] if x["key"] == "ART1")["viewer_url"] == "https://llm.fhirworx.io/ui/pdf/ART1" + assert [g for g in s["counts"]] == [g for g in SOURCE_GROUP_ORDER if g in s["counts"]] +def test_contents_slice(d): + c = contents_slice([contents_entry(d, tier="reviewed", book=BOOK["HOME-VISITS"])], BOOK, {"HOME-VISITS"}, (8662, 7858)) + assert [e["family"] for e in c["families"]] == ["HOME-VISITS"] and c["families"][0]["n_review"] == 3 + assert [p["family"] for p in c["planned"]][:2] == ["OFFICE-EM", "G2211-B1-B2"] and len(c["planned"]) == 12 + assert c["machine"] == {"derived": 8662, "single_code": 7858} + assert c["families"][0]["sections"]["payment"] == "CY2022–CY2027" +def test_bib_info_reads_status(): # Store(":memory:") + inserts into items, fr_anchor_docs, attachments +def test_contents_endpoint_and_machine_counts_missing_table(): # 200; machine is None without pfs.code_family +def test_sources_endpoint_uses_bib_once(): # bib factory called once across two GETs +``` + + Extend `test_js_fixtures_match_api` to cover `sources` (with the fake info) and `contents`. +- [ ] **Step 2: Live tests** (`tests/llm/test_policy_live.py`). Skip unless `data/replica/aco.ro.duckdb` and `data/bib.sqlite` exist. Use `load_slice` with `llm.config.load()` and `HOME-VISITS`. + - `test_live_every_fact_served_in_home_view`: the ids of `facts` equal `read_dossier(...).facts`, and each id is in its home section's `facts`. + - `test_live_citations_resolve`: for every primary and also cite, an empty `url` means `kind == "cpt_book"` with a non-empty `locator`. A non-empty URL starts with `https://` and has no whitespace. An `fr_para` URL ending `#p-N` has `(item_key, N)` in bib `fr_anchors`. + - `test_live_no_cpt_descriptor_text`: + - take every `pfs.rvu.description` of length ≥ 10 for the codes in the payment rows; + - normalize whitespace and casefold, then check it never occurs in any slice's JSON (all sections plus contents); + - the assertion message names codes only, never the text. + - `test_live_politics_counts_carry_accuracy`: every panel's `accuracy` contains `ACCURACY_MARK`, and every `stance_split` fact carries it in `text` or `accuracy`. + - `test_live_review_items_all_served`: `len(header["review"]) == len(d.review)`. +- [ ] **Step 3: Run** the new tests → FAIL. +- [ ] **Step 4: Implement.** +- [ ] **Step 5: Run.** + - `tests/llm/test_policy_*.py tests/pfs/test_book.py` → PASS. The live file passes on the host, after Task 1's rebuild. Run it non-parallel: `-p no:xdist`. + - Regenerate the fixtures with `LEX_UPDATE_FIXTURES=1`, then run again → PASS. + - Coverage 100% on the new modules. Ruff. +- [ ] **Step 6: Commit** `git add src/llm/policy_slices.py src/llm/policy.py tests/llm/test_policy_slices.py tests/llm/test_policy_api.py tests/llm/test_policy_live.py tests/lex/fixtures && git commit -m "feat(llm): lex contents and sources slices; live acceptance — every fact served and cited (S1)"` + +--- + +### Task 5: The app shell: page, state, API client, citations, drawer; test and probe tooling + +**Files:** +- Rewrite: `dev/scripts/dossier_page/template.html`, `dev/scripts/dossier_page/build.py` +- Create under `infra/gitea/custom/public/assets/dossier/`: `app.js`, `state.js`, `api.js`, `fmt.js`, `cite.js`, `shell.js`, and the stub views `view-{contents,dossier,review,coming,timeline,valuation,payment,politics,sources}.js` +- Create: `tests/lex/__init__.py`, `tests/lex/test_js.py`, `tests/lex/{state,api,cite,shell}.test.mjs`, `tests/dev/test_dossier_page_build.py`, `dev/scripts/lex_dump_api.py`, `dev/scripts/lex_probe.py`, `tests/dev/test_lex_probe.py` + +**Interfaces:** +- Consumes: the API (Tasks 3–4) and `tests/lex/fixtures/*.json`. +- Produces (JS, ES modules, pure unless noted): + - `state.js`: + - `VIEWS = ["contents", "dossier", "timeline", "valuation", "payment", "politics", "sources", "grid", "evaluate", "predict", "draft", "review"]`, `FAMILY_VIEWS` (all but contents); + - `parseLocation({pathname, search, hash}) -> {family, view, code, fact, canonical}` and `formatState({family, view, code, fact}) -> string`, following D1: + - the view is the first path segment if it is in VIEWS; else a legacy `#`; else `dossier` when a family is given, `contents` when not; + - a family view without a family falls back to contents; + - `code` is read from the fragment or a stray `?code=`, and `fact` from the fragment; + - the family is trimmed and upper-cased. + - `api.js`: + - errors `SignedOut`, `NotFound` (`.family`, `.status`), `Unavailable`, `Rebuilt`; + - `getJSON(path, fetchImpl = fetch)`: uses `{redirect: "manual"}`; `opaqueredirect`, status 0 or a non-JSON content type → SignedOut; 404 → NotFound; 503 → Unavailable; + - `sectionPath(section, family)` → `/api/policy/dossier/
?family=`; `CONTENTS_PATH = "/api/policy/contents"`; `factPath(family, id)`; + - `class DossierStore(family, fetchImpl)` with `load(needs: string[]) -> {contents?, header?, timeline?, …}`. It caches per section and checks every slice's `built_at` against `header.built_at`. On a mismatch it clears the cache and refetches once; if the mismatch persists it throws `Rebuilt`. `fact(id)` looks in the loaded slices, else fetches `factPath`. + - `fmt.js`: `esc`, `compact`, `money`, `n2`, `int`, `uniq`, `builtText(iso) -> "2026-11-13 05:23 UTC"`. + - `cite.js`: + - `citeHtml(cite)`: `label`, or `locator||label` when there is no URL; + - `factHtml(fact, {tag = "li"} = {})`: `data-fact`, `data-kind`, the note pill `note`, the text, the cite, the also-cites and `fact.accuracy` as ``; + - `tagged(text, facts)`: escapes the text and turns each `[F#]` into `citeHtml` with `data-ref="F#"`. A run of the same tag collapses to one. An unknown tag stays as text. + - `evidenceHtml(fact)`: drawer markup with kind, year, codes, text, note, cites and the non-empty `values` as a `dl`. + - `shell.js`: + - `tabsHtml(state)`: real links, `class="on"` plus `aria-current` on the current tab, `soon` on the coming tabs; + - `railHtml(contents, state)`: families link to `/dossier?family=KEY` and the current one gets `cur`; planned entries are not links; it ends with the machine-tier note; + - `mastHtml(state, header, contents)`: lex masthead and a health box such as "Live · HOME-VISITS dossier built 2026-11-13 05:23 UTC · citation check passed"; + - `errorHtml(err, state, href)`: SignedOut, NotFound by status, Unavailable, Rebuilt, each with a link (reload `href`, or `/contents`). + - Each `view-*.js` exports `needs: string[]` and `render(data, state) -> string`, plus an optional `mount(root, data, state, nav)` where `nav = {go(patch, {push}), openFact(id), openEvidence(html)}`. The stubs return `

This view is being built.

`. + - `app.js` (DOM): boot, `replaceState` to the canonical URL, rail plus search filter, tabs, `popstate`, the theme toggle (ported), and the drawer. + - A click on `[data-fact]` opens the drawer via `store.fact` and writes `#fact=` with replaceState. + - On load, `fact` in the URL opens the drawer. + - Loading sets `main.dataset.ready = ""`; after render it sets `main.dataset.ready = view`. + - Errors render `errorHtml` into main. +- Produces (Python): + - `build.py [--out PATH]`: + - drops all data extraction and imports only stdlib; + - keeps the fills `/*__FHIRWORX_CSS__*/`, `/*__FHIRWORX_DARK__*/`, ``, the three favicons and `/*__DOMAIN__*/` (asserted count); + - adds `/*__VERSION__*/` = `sha256` over the sorted `(name, bytes)` of the `*.js` files [:12]; + - writes atomically and prints `wrote ( bytes) v=`. + - `template.html`: + - keeps the head, the tokens and CSS, the sprite, the navbar, the masthead (with an `#status` slot) and the three-pane `.shell` (`#rail`, `#main` with `#tabs`, `#drawer`); + - removes the ``; + - keeps the theme bootstrap script; + - adds CSS for `.err`, `.acc` and `[data-ref]`, using tokens only. + - `dev/scripts/lex_dump_api.py --family KEY --out DIR`: `load_slice` for every section plus contents plus every fact, written to `DIR/contents.json`, `DIR/dossier/
.json` and `DIR/fact/.json`. + - `dev/scripts/lex_probe.py`: + - Options: `--base URL`, `--family KEY`, `--check smoke|facts`, `[--map HOST=TARGET]`, `[--fixture DIR --assets DIR --page FILE]`, `[--shots DIR]`. + - Playwright is imported inside `main()`. + - `route_target(path: str) -> tuple[str, str]` mirrors the routers: `("api", path)` for `^/api/policy/`; `("asset", name)` for `^/assets/dossier/([a-z][a-z0-9-]*[.]js)$`; `("page", "")` for anything else. + - With `--fixture`, `page.route` serves api requests from DIR (`/api/policy/dossier/?…` → `dossier/.json`, `/api/policy/fact?…&id=F1` → `fact/F1.json`, a missing file → 404 JSON), assets from `--assets` as `text/javascript`, and the page from `--page`. + - With `--map`, Chromium gets `--host-resolver-rules=MAP `. + - smoke: each view at 1440×900 and 390×844 must reach `main[data-ready=]` within 15 s, with no page errors and no console errors (failed `fonts.googleapis.com`/`fonts.gstatic.com` loads are ignored), and `document.documentElement.scrollWidth <= innerWidth`. Screenshots go to `--shots`. + - facts: for each entry of the facts index, open its view and find `[data-fact=id]`. If it contains `a.cite` or `.cite.book`, compare the `href` with `url` or the text with `locator`; otherwise click it and compare inside `#drawer`. Each also URL must appear too. + - It prints `facts N rendered N links ok N locator-only M` and exits 1 on any miss. + +- [ ] **Step 1: Failing JS tests**: + +```js +// state.test.mjs +eq(parseLocation({pathname: "/", search: "?family=HOME-VISITS", hash: "#dossier"}).canonical, "/dossier?family=HOME-VISITS"); +const s = parseLocation({pathname: "/timeline", search: "?family=home-visits", hash: "#code=99343&fact=F12"}); +deq([s.family, s.view, s.code, s.fact], ["HOME-VISITS", "timeline", "99343", "F12"]); +eq(s.canonical, "/timeline?family=HOME-VISITS#code=99343&fact=F12"); +eq(parseLocation({pathname: "/", search: "", hash: ""}).canonical, "/contents"); +eq(parseLocation({pathname: "/nonsense", search: "?family=X", hash: ""}).view, "dossier"); +eq(parseLocation({pathname: "/", search: "", hash: "#timeline"}).view, "contents"); +eq(formatState({family: "A/D-TX", view: "dossier"}), "/dossier?family=A%2FD-TX"); +eq(parseLocation({pathname: "/payment", search: "?family=HOME-VISITS&code=99350", hash: ""}).canonical, "/payment?family=HOME-VISITS#code=99350"); +// api.test.mjs: "opaque redirect is SignedOut", "html body is SignedOut", 404 → NotFound status "planned", 503 → Unavailable, +// sectionPath("timeline", "A/D") === "/api/policy/dossier/timeline?family=A%2FD", +// "mixed builds refetch": header T1 + timeline T2, refetched header T2 + timeline T2 → T2 data; persistent mismatch → Rebuilt +// cite.test.mjs: "no url renders a locator span" (no "href"), "also cites render" (2 × class="cite"), label "&" escaped, +// factHtml(F2) has data-fact="F2" + class="pill model" + "model paraphrase, unreviewed"; factHtml(F8) contains its accuracy; +// tagged("A [F4]. B [F3][F3].", facts) → 2 data-ref anchors; tagged("x [F99]", facts) contains "[F99]" +// shell.test.mjs: tabsHtml on /timeline marks it on with href "/timeline?family=HOME-VISITS"; coming tabs class soon; +// "signed-out panel links to the current URL"; "not-found panel names the status" (planned); "unavailable panel"; +// railHtml(contents fixture) links "/dossier?family=HOME-VISITS" with class cur; planned rows have no +``` + + Also write: + - `tests/lex/test_js.py::test_lex_js_unit_tests`: run `node --test tests/lex/*.test.mjs` when `node` ≥ 20 is on PATH, else skip with the reason "node ≥ 20 not on PATH; run NODE"; + - `tests/dev/test_dossier_page_build.py::test_build_writes_shell`: subprocess build.py `--out tmp/index.html`; then no `/*__` and no `