From 2c0bb28c332e152ab719c7a06642ab45c60dd296 Mon Sep 17 00:00:00 2001 From: Ziming Date: Wed, 7 Oct 2026 23:03:46 -0400 Subject: [PATCH 1/2] Document the reference page-citation convention Adds a "Parameter and variable references" section to CLAUDE.md: one reference entry per source document; a single cited page goes only in the href fragment; several cited pages keep the href on the first page and end the quoted title with "#page 72-75" or "#page 29,32-33,36,41"; never a page list in the href; variable reference tuples use a "# PDF pages" comment in the same shape. Fixes #10008 Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 24 +++++++++++++++++++ .../reference-page-citations.changed.md | 1 + 2 files changed, 25 insertions(+) create mode 100644 changelog.d/reference-page-citations.changed.md diff --git a/CLAUDE.md b/CLAUDE.md index 74711ab4b46..b4d08cadfc6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -146,6 +146,30 @@ changelog.d/medicaid-ce-exclusions.md - Verify behavior at edge cases (income just below/above thresholds, exact boundary conditions) - Consider real-world examples to validate implementation, including official calculators +## Parameter and variable references +- One `reference` entry per source document. URLs that differ only by `#page=` point at the same source. +- PDF page anchors use the file page number (1-indexed), not the printed page number. +- **One cited page:** put it only in the URL fragment (`#page=57`); keep the title free of page text. +- **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 (runs inside a list compress). Quote YAML titles that contain `#`; an unquoted ` #` starts a YAML comment and truncates the title. +- The URL fragment is one valid destination. Never write `#page=1,3,5`. +- Do not split one multi-page table into one entry per page. +- Variable `reference` tuples follow the same rules. Tuple entries have no title, so a `# PDF pages …` comment above a multi-page href lists the pages in the same shape; drop the comment when the href cites one page. + +```yaml +reference: + - title: FY2026 LIHEAP State Plan, Section 2.5 + href: https://example.gov/state-plan.pdf#page=57 + - title: "Energy Assistance Policy Manual, benefit matrix #page 72-75" + href: https://example.gov/manual.pdf#page=72 +``` + +```python +reference = ( + # PDF pages 61-62, 67, 78-81. + "https://example.gov/manual.pdf#page=61", +) +``` + ## Axiom Parity (required for policy changes) - Any PR that adds, updates or fixes policy must also leave the same provision correct in rulespec-us. Put one line in the PR body: `axiom: encoded-correct | encoded | queued | n/a: `. - Use `queued` only when the signed encoder is blocked; record the blocker in the issue. Each billed encoder run requires separate approval. A `queued` rulespec-us issue must be dispatch-ready and labelled `pe-parity`. It needs the module path and corpus citation, the verbatim law, the required outputs, and companion tests from the same external source as your YAML tests. See `CONTRIBUTING.md#axiom-parity`. diff --git a/changelog.d/reference-page-citations.changed.md b/changelog.d/reference-page-citations.changed.md new file mode 100644 index 00000000000..ad13f67981d --- /dev/null +++ b/changelog.d/reference-page-citations.changed.md @@ -0,0 +1 @@ +Document the reference page-citation convention for parameter and variable references in CLAUDE.md. From c4b79ecdcb071070dac0dfa835f2601330f96abe Mon Sep 17 00:00:00 2001 From: Ziming Date: Wed, 7 Oct 2026 23:17:29 -0400 Subject: [PATCH 2/2] Shorten the reference page-citation section Replaces the examples and longer explanations with six bullets. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b4d08cadfc6..de813eb790d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -147,28 +147,12 @@ changelog.d/medicaid-ce-exclusions.md - Consider real-world examples to validate implementation, including official calculators ## Parameter and variable references -- One `reference` entry per source document. URLs that differ only by `#page=` point at the same source. -- PDF page anchors use the file page number (1-indexed), not the printed page number. -- **One cited page:** put it only in the URL fragment (`#page=57`); keep the title free of page text. -- **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 (runs inside a list compress). Quote YAML titles that contain `#`; an unquoted ` #` starts a YAML comment and truncates the title. -- The URL fragment is one valid destination. Never write `#page=1,3,5`. -- Do not split one multi-page table into one entry per page. -- Variable `reference` tuples follow the same rules. Tuple entries have no title, so a `# PDF pages …` comment above a multi-page href lists the pages in the same shape; drop the comment when the href cites one page. - -```yaml -reference: - - title: FY2026 LIHEAP State Plan, Section 2.5 - href: https://example.gov/state-plan.pdf#page=57 - - title: "Energy Assistance Policy Manual, benefit matrix #page 72-75" - href: https://example.gov/manual.pdf#page=72 -``` - -```python -reference = ( - # PDF pages 61-62, 67, 78-81. - "https://example.gov/manual.pdf#page=61", -) -``` +- One `reference` entry per source document; URLs that differ only by `#page=` are one source. Do not split a multi-page table into per-page entries. +- PDF page numbers are file pages (1-indexed), not printed pages. +- One cited page: `#page=57` in the href only, no page in the title. +- Several cited pages: the href opens the first, and the title ends with `#page 72-75` (consecutive) or `#page 29,32-33,36,41` (nonconsecutive). Quote the title, since an unquoted ` #` starts a YAML comment. +- Never put a page list in the href (`#page=1,3,5`). +- Variable reference tuples have no title: put a `# PDF pages 61-62, 67` comment above a multi-page href. ## Axiom Parity (required for policy changes) - Any PR that adds, updates or fixes policy must also leave the same provision correct in rulespec-us. Put one line in the PR body: `axiom: encoded-correct | encoded | queued | n/a: `.