From c063912dca996813aa7dd9125a4b44ecdfb9a45a Mon Sep 17 00:00:00 2001 From: ZimingHua Date: Wed, 7 Oct 2026 22:56:01 -0400 Subject: [PATCH] Allow page lists in multi-page reference titles A reference that cites one PDF page keeps the page only in the href (#page=57). A reference that cites several pages of one source keeps a single entry: the href opens the first cited page and the quoted title ends with "#page 72-75" or "#page 29,32-33,36,41". Updates the model-development parameters reference, the rules-engineer agent, and the implementation-validator agent so they agree. Refs PolicyEngine/policyengine-us#10008 Co-Authored-By: Claude Opus 5.5 --- .../references/parameters.md | 10 ++++-- .../implementation-validator.md | 5 +-- .../agents/country-models/rules-engineer.md | 35 ++++++++++++------- 3 files changed, 33 insertions(+), 17 deletions(-) diff --git a/skills/policyengine-model-development/references/parameters.md b/skills/policyengine-model-development/references/parameters.md index dc99187..4c294fa 100644 --- a/skills/policyengine-model-development/references/parameters.md +++ b/skills/policyengine-model-development/references/parameters.md @@ -17,7 +17,7 @@ metadata: period: year # year | month | day | eternity label: Illinois TANF earned income disregard rate reference: - - title: 305 ILCS 5/4-1.6 # full section path, no page number in title + - title: 305 ILCS 5/4-1.6 # full section path; page numbers only when several pages are cited href: https://www.ilga.gov/legislation/ilcs/... # PDFs: add #page=XX here ``` @@ -36,7 +36,13 @@ Missing any of `unit` / `period` / `label` / `reference` is a validation error. `[State] [verb] ... under the [Full Program Name] program.` - **`reference`:** prefer an online statute/reg (Cornell LII, public.law, `.gov` HTML with a section anchor) over a PDF; full subsection path in the title; verify PDF `#page=XX` is the file - page, not the printed page. + page, not the printed page. One entry per source document — URLs that differ only by `#page=` + are the same source. + - **One cited page:** the page goes only in the href (`#page=57`); no page number in the title. + - **Several cited pages:** the href opens the first cited page, and the title ends with + `#page 72-75` for a consecutive run or `#page 29,32-33,36,41` for a nonconsecutive list. Quote + titles containing `#` (`title: "Program Manual, Section 4 #page 72-75"`). Never put a page list + in the href (`#page=1,3,5` is not a valid destination). ## Federal / state separation for income taxes diff --git a/targets/claude/agents/country-models/implementation-validator.md b/targets/claude/agents/country-models/implementation-validator.md index 79adff0..2cae5f2 100644 --- a/targets/claude/agents/country-models/implementation-validator.md +++ b/targets/claude/agents/country-models/implementation-validator.md @@ -161,7 +161,8 @@ Also: 5. **Reference format — CRITICAL.** - Variables (`.py`): bare URL string, or tuple of strings. NEVER a YAML-style dict. - - Parameters (`.yaml`): structured `reference:` list with `title:` + `href:`. Page numbers go in `href:` (`#page=XX`), NEVER in `title:`. + - Parameters (`.yaml`): structured `reference:` list with `title:` + `href:`, one entry per source document. One cited page goes only in `href:` (`#page=XX`), NEVER in `title:`. Several cited pages: `href:` opens the first cited page and the quoted `title:` ends with `#page 72-75` (consecutive) or `#page 29,32-33,36,41` (nonconsecutive). + - Flag page text in a one-page title, `#page=` in any title, an unquoted `#page` title, a page list in `href:` (`#page=1,3,5`), and a multi-page table split into one entry per page. 6. **Parameter formatting — SHOULD ADDRESS.** - **Description:** one sentence; ends with single period; allowed verbs only (`limits`, `provides`, `sets`, `excludes`, `deducts`, `uses`); generic placeholder (`this amount` / `this share` / `this percentage` / `this threshold`); full program name spelled out; ends with `under the [Full Program Name] program`. @@ -251,7 +252,7 @@ Path: `{RUN_ROOT}/{PREFIX}-review-code.md`. Group findings by severity. - `variables/.../{prefix}_amount.py:42` — `# TODO: implement` ### Reference format - `variables/.../{prefix}_eligible.py:10` — uses YAML dict format inside Python -- `parameters/.../income_limit.yaml:8` — page number in `title:` ("page 13"); move to `href:` as `#page=13` +- `parameters/.../income_limit.yaml:8` — one-page reference has page number in `title:` ("page 13"); move to `href:` as `#page=13` ### Duplicate variable - `variables/.../{prefix}_fpg.py` — duplicates existing `federal_poverty_guideline`; reuse instead ### Boolean toggle date alignment diff --git a/targets/claude/agents/country-models/rules-engineer.md b/targets/claude/agents/country-models/rules-engineer.md index d61663f..cc685b5 100644 --- a/targets/claude/agents/country-models/rules-engineer.md +++ b/targets/claude/agents/country-models/rules-engineer.md @@ -50,38 +50,47 @@ description: Oregon limits gross income to this amount by household size under t If any fails, rewrite from the template before saving. -## CRITICAL: Parameter Reference Format — Page Numbers in `href:`, NEVER in `title:` +## CRITICAL: Parameter Reference Format — One Page in `href:` Only; Several Pages Listed in `title:` -The `title:` field is the legal section path (statute, regulation, manual section). The `href:` field is the URL. PDF page anchors (`#page=XX`) belong at the end of the URL. +The `title:` field is the legal section path (statute, regulation, manual section). The `href:` field is the URL. PDF page anchors (`#page=XX`) belong at the end of the URL. Use one entry per source document — URLs that differ only by `#page=` are the same source. + +- **One cited page:** the page goes only in `href:` (`#page=23`); the title has no page number. +- **Several cited pages:** `href:` opens the first cited page, and the title ends with `#page 72-75` for a consecutive run or `#page 29,32-33,36,41` for a nonconsecutive list (compress runs inside a list). Quote the title, because an unquoted ` #` starts a YAML comment and silently truncates it. **✅ Correct:** ```yaml reference: - title: OAR 461-155-0030(2)(a)(B) href: https://oregon.public.law/rules/oar_461-155-0030 - - title: Oregon DHS TANF Policy Manual Section 4.3.2 + - title: Oregon DHS TANF Policy Manual Section 4.3.2 # one page href: https://oregon.gov/dhs/tanf-manual.pdf#page=23 + - title: "Oregon DHS TANF Payment Standards, Section 2 #page 41-43" # several pages + href: https://oregon.gov/dhs/tanf-payment-standards.pdf#page=41 ``` -**❌ Forbidden — page info inside `title:`:** +**❌ Forbidden:** ```yaml reference: - - title: Arkansas TEA Manual, page 13 # page belongs in href + - title: Arkansas TEA Manual, page 13 # one page belongs in href only href: https://humanservices.arkansas.gov/wp-content/uploads/TEA_MANUAL.pdf - - title: OAR 461-155-0030 (p. 5) # page belongs in href + - title: OAR 461-155-0030 (p. 5) # one page belongs in href only href: https://oregon.public.law/rules/oar_461-155-0030 + - title: Example Manual #page 4,7 # unquoted: YAML reads the title as "Example Manual" + href: https://example.gov/manual.pdf#page=4,7 # href fragment must be one page ``` -**Title rules:** include the full section path with subsections (e.g., `(2)(a)(B)`); never include `page`, `p.`, `pg`, or `#page=`. +**Title rules:** include the full section path with subsections (e.g., `(2)(a)(B)`); never include `page`, `p.`, `pg`, or `#page=`. The only page text allowed is the trailing `#page ` on a reference that cites several pages. -**href rules:** for PDFs, append `#page=XX` where XX is the **file page number** (1-indexed), not the printed page. For HTML, use section anchors if available. +**href rules:** for PDFs, append `#page=XX` where XX is the **file page number** (1-indexed), not the printed page — the first cited page when the reference cites several. Never a page list (`#page=1,3,5`). For HTML, use section anchors if available. -**Self-check before saving each parameter file** — scan every `title:` value for: -1. Digits that represent a page number (`page 13`, `p. 5`, `pg 23`) -2. The substring `#page=` (belongs in `href:` only) -3. Missing subsection path (e.g., bare `OAR 461-155` instead of `OAR 461-155-0030(2)(a)(B)`) +**Self-check before saving each parameter file** — scan every reference for: +1. Page text in the title of a one-page reference (`page 13`, `p. 5`, `pg 23`, `#page 13`) +2. The substring `#page=` in a title (belongs in `href:` only) +3. A several-page reference whose title is unquoted, lacks the trailing `#page `, or whose `href:` does not open the first listed page +4. A multi-page table split into one entry per page +5. Missing subsection path (e.g., bare `OAR 461-155` instead of `OAR 461-155-0030(2)(a)(B)`) -If any fails, move the page info to `href:`. +Fix any failure before saving. ## Load the consolidated skill first