Source: qa/xref-r4-QA1.md
# QA1 Audit: Round 4 Citation Fragment Repair & Advisory Case Adjudication
- **Auditor:** QA1 (`gemini-3.8-flash-high`)
- **Date:** 2026-11-10
- **Task Specs:**
- [`neov2/specs/qa1_xref4.md`](file:///home/mma/repos/neochart/neov2/specs/qa1_xref4.md)
- [`neov2/qa/xref-r4-QA1-request.md`](file:///home/mma/repos/neochart/neov2/qa/xref-r4-QA1-request.md)
- **Commits Audited:**
- [`3b17d4a`](https://github.com/lmctlhq/neochart/commit/3b17d4a86a0b5ab1e4c3905d9fb76060af55216b): *Preserve subsection links when checking local target files*
- [`2e4aa7c`](https://github.com/lmctlhq/neochart/commit/2e4aa7c039b06dbeb184de7d0386797bcce42edf): *Keep the rebuild gate strict while recording restored fragment links*
- **Primary Deliverables & Evidence Inspected:**
- [`neov2/xref/out/r3/REBUILD_PLAN.md`](file:///home/mma/repos/neochart/neov2/xref/out/r3/REBUILD_PLAN.md)
- [`neochartdocroot/authoring/build_site.py`](file:///home/mma/repos/neochart/neochartdocroot/authoring/build_site.py#L812-L828)
- [`neov2/xref/scratch_reemit.py`](file:///home/mma/repos/neochart/neov2/xref/scratch_reemit.py#L65-L165)
- [`neov2/xref/out/r4/qa1_80_manifest.json`](file:///home/mma/repos/neochart/neov2/xref/out/r4/qa1_80_manifest.json)
- [`neov2/xref/out/r4/qa1_80_evidence.json`](file:///home/mma/repos/neochart/neov2/xref/out/r4/qa1_80_evidence.json)
- [`neov2/xref/out/r4/qa1_80_changes.diff`](file:///home/mma/repos/neochart/neov2/xref/out/r4/qa1_80_changes.diff)
- [`neov2/xref/out/r4/fragment_target_observation.json`](file:///home/mma/repos/neochart/neov2/xref/out/r4/fragment_target_observation.json)
- [`neov2/xref/out/r4/reported_fragment_case_manifest.json`](file:///home/mma/repos/neochart/neov2/xref/out/r4/reported_fragment_case_manifest.json)
- [`neov2/xref/out/r4/reported_fragment_case_changes.diff`](file:///home/mma/repos/neochart/neov2/xref/out/r4/reported_fragment_case_changes.diff)
---
## Executive Summary & Track Verdicts
| Verification Track | Requirement | Independent QA1 Finding | Verdict |
|---|---|---|:---:|
| **(1) Fragment Fix** | Confirm URL fragment preservation in `build_site.py:target_href()` | `target_href()` now splits URL via `partition("#")`, tests file existence on base page, computes relative href, and appends `#fragment`. 18 statutory fragment links that were previously dropped now survive in QA1's 80-case set. Main test suite passes (**203 passed, 7 skipped**); fixture tests pass (**30 passed**). | **PASS** |
| **(2) 80-Case Scratch Re-emit** | Re-run QA1's exact 80-case manifest from Round 3 into scratch | Bounded run executed in 13.05s against `/tmp/neov2-r4-qa1-test`. Out of 80 pages: **10 changed**, **23 anchors added**, **0 anchors removed**, **0 text diffs**, **0 non-anchor diffs** (`only_anchor_additions: True`). Tree gate passed cleanly on both annotated and baseline outputs. | **PASS** |
| **(3) Corruption & Missing-Page Gates** | Injected 1-char mutation & missing page rejected by gate | Injected 1-char mutation into `us/410/0001_01`: gate immediately failed with `ValueError: non-additive page diff... only_anchor_additions: False`. Deleted page: gate immediately failed with `ValueError: {'missing': [...], 'missing_count': 1}`. | **PASS** |
| **(4) Opt-In Default** | Confirm `NEO_RESEARCH_MENTIONS` remains off by default | Default environment has variable unset. `parse_case()` omits `research_mentions`. Renderer does not consume annotations. Zero impact on HTML markup or link generation. | **PASS** |
| **(5) Advisory Case Adjudication** | Analyze `/f3d/559/0274-01` (*Severns*): data issue vs code issue & operator action | **Finding: DATA ISSUE** (not code). The code and gate behave correctly: changing `href` from `.../index.html` to `.../index.html#C` is a retarget (1 removed, 1 added) and must be blocked. The underlying data issue is that `citation_index.json` maps to `#C`, but the section 924 HTML DOM lacks an `id="C"` or `name="C"` anchor. Operator action specified. | **PASS** (Adjudicated) |
| **Overall** | **Final Audit Verdict** | **Code fix and preservation gates verified. Candidate full rebuild remains appropriately BLOCKED until operator resolves data mismatch.** | **PASS** |
> [!IMPORTANT]
> **Rebuild Status:** The code changes in `3b17d4a` and `2e4aa7c` fully resolve the fragment-dropping issue identified in Round 3 without regressing the strict additive preservation gate. However, a full-corpus candidate rebuild must remain **BLOCKED** as documented in `REBUILD_PLAN.md` until the operator addresses the statutory fragment/DOM mismatch exemplified by `/f3d/559/0274-01`. Under no circumstances should the rebuild gate be relaxed or bypassed.
---
## Track (1): Fragment Fix Verification in `build_site.py:target_href()`
### 1. Code Review of the Fix (`3b17d4a`)
In [`neochartdocroot/authoring/build_site.py`](file:///home/mma/repos/neochart/neochartdocroot/authoring/build_site.py#L814-L828), `target_href()` was previously testing filesystem existence using the unparsed target string:
```python
# PREVIOUS BUGGY LOGIC:
target_path = Path(local_cites["docroot"]) / target_url
if not target_path.resolve(strict=False).is_file():
return ""
```
Because statutory citations in `citation_index.json` contain URL fragments (e.g. `index.html#C` or `index.html#5`), `target_path.is_file()` looked for a literal file named `index.html#C` on the filesystem, evaluated to `False`, and suppressed the valid link.
In commit `3b17d4a`, this was corrected to:
```python
# CORRECTED LOGIC:
page_url, separator, fragment = target_url.partition("#")
# A fragment is a browser destination within a page, not a filesystem name.
# Fragment-only references must still point to an existing current page.
page_target = page_url or (local_cites.get("current_url", "") if separator else "")
if not page_target:
return ""
target_path = Path(local_cites["docroot"]) / page_target
if not target_path.resolve(strict=False).is_file():
return ""
href = relative_href(Path(local_cites["page_dir"]), target_path) if page_url else ""
return href + (separator + fragment if separator else "")
```
### 2. Test Suite Execution
In an isolated worktree (`/tmp/neochart-qa1-xref4`), the authoring and xref test suites were executed using the pinned environment (`/tmp/neov2-astra-venv/bin/pytest`):
```bash
/tmp/neov2-astra-venv/bin/pytest neochartdocroot/authoring neov2/xref
======================== 203 passed, 7 skipped in 0.57s ========================
```
The 5 fixture-dependent tests from `neochartdocroot` were re-verified:
```bash
cd neochartdocroot && /tmp/neov2-astra-venv/bin/pytest authoring/test_headings.py authoring/test_homepage_cards.py
============================== 30 passed in 7.02s ==============================
```
### 3. Regression Coverage for `target_href`
Commit `3b17d4a` added comprehensive unit tests in `neochartdocroot/authoring/test_eyecite_extract.py`:
- `test_target_href_checks_page_before_preserving_fragment`:
- `catalog/law/index.html#C` -> `../law/index.html#C`
- `catalog/law/index.html` -> `../law/index.html`
- URL-encoded fragments: `catalog/law/index.html#C%20D` -> `../law/index.html#C%20D`
- Same-page target: `catalog/case/index.html#C` -> `index.html#C`
- Fragment-only: `#C` -> `#C`
- Unfragmented current page: `catalog/case/index.html` -> `""` (suppressed self-link)
- Empty string: `""` -> `""`
- `test_target_href_rejects_missing_page_even_with_fragment_named_file`:
- Tests a file literally named `missing.html#C` on disk; correctly rejected because `missing.html` does not exist.
All tests passed cleanly.
---
## Track (2): Scratch Re-emit on QA1's Pinned 80 Cases
### 1. Execution & Performance
QA1 re-ran the exact 80-case manifest from Round 3 ([`neov2/xref/out/r4/qa1_80_manifest.json`](file:///home/mma/repos/neochart/neov2/xref/out/r4/qa1_80_manifest.json)) into a fresh scratch directory `/tmp/neov2-r4-qa1-test`:
```bash
/tmp/neov2-astra-venv/bin/python neov2/xref/scratch_reemit.py \
--sample 80 \
--sample-manifest neov2/xref/out/r4/qa1_80_manifest.json \
--scratch /tmp/neov2-r4-qa1-test
```
**Run Timings:**
- Total elapsed time: **13.05 seconds**
- Annotation extraction time: **4.46 seconds**
- Two-pass rendering time: **0.68 seconds**
- Throughput: ~6.1 cases/sec overall; ~17.9 cases/sec annotation pass; ~117 cases/sec rendering pass.
### 2. Quantitative Verification Results
Comparing current stored corpus pages against the scratch re-emitted annotated pages:
| Metric | Measured Value | Expected (Gate Constraint) | Status |
|---|---:|---:|:---:|
| Total Pages Sampled | 80 | 80 | MATCH |
| Pages Changed | 10 | 10 | MATCH |
| Anchors Added | 23 | 23 | MATCH |
| Anchors Removed | 0 | 0 | MATCH |
| Text Differences | 0 | 0 | MATCH |
| Non-Anchor Byte Differences | 0 | 0 | MATCH |
| `only_anchor_additions` | **True** | **True** | **PASS** |
The candidate tree gate was run directly via Python against `/tmp/neov2-r4-qa1-test/annotated`:
```python
verify_candidate_tree(CORPUS, Path('/tmp/neov2-r4-qa1-test/annotated'), addresses)
# Result: {'pages_checked': 80, 'pages_changed': 10, 'anchors_added': 23, 'anchors_removed': 0, 'text_differences': 0, 'non_anchor_byte_differences': 0, 'only_anchor_additions': True}
```
Baseline rendering (`/tmp/neov2-r4-qa1-test/baseline`) was also verified against stored pages: identical results (23 added anchors, 0 removed, 0 text diffs).
### 3. Survival of Fragment Links
In Round 3, only 1 anchor addition was observed across QA1's 80 cases (a non-fragment link). With the fix in `3b17d4a`, **22 additional links survive**, bringing the total to 23.
Of these 23 added anchors, **18 are statutory links with fragments** that were formerly dropped:
1. `catalog/cases/us/volume_410/0001_01/index.html` (*United States v. Florida East Coast R. Co.*):
- `26 U.S.C. § 172(e)` -> `../../../../federal/title_26/section_172/title26_sec172_422e1b12086e/172_net_operating_loss_deduction_0001/index.html#(e)`
2. `catalog/cases/f2d/volume_349/0168_01/index.html` (*United States v. Gardner*):
- `18 U.S.C. § 2113(c)` -> `../../../../federal/title_18/section_2113/title18_sec2113_a40590a5d2eb/2113_bank_robbery_and_incidental_crimes_0001/index.html#c`
3. `catalog/cases/f3d/volume_339/0477_01/index.html` (*First Capital Asset Mgmt. v. Brickellbush*):
- `18 U.S.C. § 1962(c)` (x2) -> `../../../../federal/title_18/section_1962/title18_sec1962_6ee5108bcfc5/1962_prohibited_activities_0001/index.html#c`
4. `catalog/cases/f3d/volume_376/0114_01/index.html` (*La Resolana Architects v. Clay Realtors*):
- `17 U.S.C. § 411(a)` -> `../../../../federal/title_17/section_411/title17_sec411_c09e3a62886a/411_registration_and_civil_infringement_actions_0001/index.html#a`
5. `catalog/cases/f3d/volume_390/0370_01/index.html` (*Barstad v. Murray County*):
- `42 U.S.C. § 1985(3)` -> `../../../../federal/title_42/section_1985/title42_sec1985_e5b0cb5038ec/1985_conspiracy_to_interfere_with_civil_rights_0001/index.html#3`
6. `catalog/cases/f3d/volume_474/0364_01/index.html` (*Williams v. Mohawk Industries*):
- `18 U.S.C. § 1962(c)` (x2) -> `../../../../federal/title_18/section_1962/title18_sec1962_6ee5108bcfc5/1962_prohibited_activities_0001/index.html#c`
7. `catalog/cases/f3d/volume_493/0078_01/index.html` (*United States v. Gomez*):
- `21 U.S.C. § 856(a)` -> `../../../../federal/title_21/section_856/title21_sec856_f62eec4c979d/856_maintaining_drug_involved_premises_0001/index.html#a`
- `18 U.S.C. § 2518(5)` -> `../../../../federal/title_18/section_2518/title18_sec2518_eb3d5db0dafc/2518_procedure_for_interception_of_wire_oral_or_electronic_co_0001/index.html#5`
8. `catalog/cases/f3d/volume_544/1140_01/index.html` (*United States v. Carter*):
- `18 U.S.C. § 3582(c)(2)` (x2) -> `../../../../federal/title_18/section_3582/title18_sec3582_a0572b84cf22/3582_imposition_of_a_sentence_of_imprisonment_0001/index.html#c_2`
- `18 U.S.C. § 2518(5)` (x3) -> `../../../../federal/title_18/section_2518/title18_sec2518_eb3d5db0dafc/2518_procedure_for_interception_of_wire_oral_or_electronic_co_0001/index.html#5`
9. `catalog/cases/f3d/volume_553/0742_01/index.html` (*Palmer v. Hendricks*):
- `28 U.S.C. § 2254(a)` (x2) -> `../../../../federal/title_28/section_2254/title28_sec2254_aee3e6592dd8/2254_state_custody_remedies_in_federal_courts_0001/index.html#a`
All fragment destinations in the emitted HTML match the exact keys defined in `citation_index.json`.
---
## Track (3): Rebuild Gate Injection Tests
To ensure the operator plan's tree gate (`scratch_reemit.py:verify_candidate_tree`) remains rigorous and fail-safe, two negative failure injections were tested against the scratch tree `/tmp/neov2-r4-qa1-test/annotated`:
### 1. Injected 1-Character Text Mutation
QA1 mutated a single character of text in the rendered SCOTUS opinion `catalog/cases/us/volume_410/0001_01/index.html` (`court` -> `count`):
```python
p = Path('/tmp/neov2-r4-qa1-test/annotated/catalog/cases/us/volume_410/0001_01/index.html')
orig = p.read_text()
p.write_text(orig.replace('court', 'count', 1))
verify_candidate_tree(CORPUS, p.parents[4], addresses)
```
**Gate Output:**
```text
ValueError: non-additive page diff in catalog/cases/us/volume_410/0001_01/index.html: {
'text_equal': False,
'non_anchor_bytes_equal': False,
'anchors_added': 1,
'anchors_removed': 0,
'only_anchor_additions': False
}
```
The tree gate immediately aborted with `ValueError`. The file was restored, and the gate returned to clean passing status.
### 2. Injected Missing Page
QA1 unlinked `catalog/cases/us/volume_410/0001_01/index.html` from the candidate tree:
```python
p.unlink()
verify_candidate_tree(CORPUS, p.parents[4], addresses)
```
**Gate Output:**
```text
ValueError: {
'missing': ['catalog/cases/us/volume_410/0001_01/index.html'],
'missing_count': 1,
'unexpected': [],
'unexpected_count': 0
}
```
The tree gate immediately aborted with `ValueError`. The file was restored, and the gate returned to clean passing status.
---
## Track (4): Opt-In Default Flag Verification
QA1 verified the opt-in flag configuration in [`neochartdocroot/authoring/parse_docs.py:477`](file:///home/mma/repos/neochart/neochartdocroot/authoring/parse_docs.py#L477):
```python
include_research = os.environ.get("NEO_RESEARCH_MENTIONS") == "1"
```
- In default runs, `NEO_RESEARCH_MENTIONS` is unset/empty; `include_research` is `False`.
- `parse_case()` omits the `research_mentions` field entirely from the parsed document dictionary.
- The card-building logic in `emit_pages.py:build_card()` does not read or consume `research_mentions`.
- No cached records are invalidated or backfilled.
- Annotation extraction has **zero impact** on HTML output bytes or links during normal site builds.
---
## Track (5): Forensic Analysis of Advisory Blocked Case `/f3d/559/0274-01`
### 1. Case Details & Observed Behavior
- **Case:** *United States v. Severns*, 559 F.3d 274 (5th Cir. 2009).
- **File:** `catalog/cases/f3d/volume_559/0274_01/index.html`.
- **Target Citation:** `18 U.S.C. § 924(c)`.
- **Original Stored Link:**
`<a class="xref" href="../../../../federal/title_18/section_924/title18_sec924_42978da3a939/924_penalties_a_1_except_as_otherwise_provided_in_this_subse_0001/index.html">18 U.S.C. § 924(c)</a>`
- **Re-rendered Link with Fragment Fix:**
`<a class="xref" href="../../../../federal/title_18/section_924/title18_sec924_42978da3a939/924_penalties_a_1_except_as_otherwise_provided_in_this_subse_0001/index.html#C">18 U.S.C. § 924(c)</a>`
When evaluated by the preservation gate:
- Old anchor `(href='.../index.html', text='18 U.S.C. § 924(c)')` is absent from the candidate -> **1 anchor removed**.
- New anchor `(href='.../index.html#C', text='18 U.S.C. § 924(c)')` is present in the candidate -> **1 anchor added**.
- Because `anchors_removed == 1`, `only_anchor_additions` evaluates to `False`. The gate strictly halts with exit code 2.
### 2. Target DOM Inspection
QA1 inspected the target HTML document:
`catalog/federal/title_18/section_924/title18_sec924_42978da3a939/924_penalties_a_1_except_as_otherwise_provided_in_this_subse_0001/index.html` (SHA256: `72d4edb8313df6f1691dae105d70d49489c00c5ba4150be1b1f6842b314b277b`).
- The only HTML anchor or element `id` in the entire page is `<section id="cited-by">`.
- There is **no element with `id="C"` or `id="c"`**, and **no `<a name="C">` or `<a name="c">`** anywhere in the document.
- Consequently, pointing the user's browser to `.../index.html#C` creates a dangling fragment link that merely lands at the top of the section page without scrolling to subsection (c).
### 3. Root Cause: Data Issue vs Code Issue
QA1 definitively adjudicates this as a **DATA ISSUE**, not a code issue:
1. **The Code is Correct:**
- `build_site.py:target_href()` behaves as an HTML linker should: it resolves the file target on disk and appends the fragment specified by the index.
- `scratch_reemit.py:verify_candidate_tree()` behaves as a preservation gate must: it prevents silent link destination changes (retargets) across previously generated pages. Retargeting an existing link is not an additive change; it removes an old link destination.
2. **The Data is Inconsistent:**
- `citation_index.json` contains an entry mapping `'18 U.S.C. § 924(C)'` to `.../index.html#C`.
- But the static law page emitter that generated `section_924/.../index.html` never produced DOM element anchors for statutory subsections.
- Concurrently, the case page `/f3d/559/0274-01` was originally generated under an earlier regime where fragments were either not in the index or stripped by `target_href()`. Re-running it today produces a retarget from the base section URL to the `#C` URL.
### 4. Operator Directives & Action Plan
The operator must **NOT** weaken `verify_candidate_tree()` to ignore retargets or allow arbitrary anchor mutations.
Before authorizing any full candidate rebuild, the operator must execute one of the following two data-reconciliation paths:
#### Option A: Source Data Reconciliation (Recommended)
1. Audit statutory section pages generated in `catalog/federal/` against `citation_index.json`.
2. Update the statutory page compiler to emit subsection anchor IDs (e.g. `<div id="c" class="subsection">`) for 18 U.S.C. § 924 and related sections.
3. If subsection anchors cannot be added to the statutory DOM, clean `citation_index.json` to map subsection citations to the base section page without a dangling `#fragment`.
4. With either change, previously emitted base-page links remain identical or transition smoothly to valid DOM destinations.
#### Option B: Scoped Operator Retarget Waiver / Migration Policy (Alternative)
1. If the operator accepts that statutory links should point to subsection fragments in anticipation of future statutory anchor generation:
- Do **NOT** disable the gate globally.
- Implement an explicit, bounded whitelist for approved retarget migrations:
e.g., allow `(old_href, new_href)` transitions strictly matching `new_href == old_href + "#" + fragment`.
- Verify every whitelisted transition against a known migration manifest before execution.
**Rebuild Status:** Until the operator selects and executes one of these reconciliation options, the full candidate rebuild must remain **BLOCKED**.
---
## Conclusion & Sign-Off
- **Round 4 Code Fix (`3b17d4a`, `2e4aa7c`):** **PASS**
- **Tree Gate Preservation & Rejection:** **PASS**
- **Opt-In Default Flag:** **PASS**
- **Operator Full Rebuild Gate:** **REBUILD BLOCKED** (Appropriately held pending operator data reconciliation)
QA1 certifies that commits `3b17d4a` and `2e4aa7c` are correct, strict, and safe to merge to master. The full candidate rebuild is safely protected by the gate.