[EPAC-2296]: Record project-level bill diff surface verification

[riddim-developer-bot]

Summary

Project-level surface/design verification gate for the bill diff backend
completion work (EPAC-2296,
parent Project Bills, Votes & Committees — depth across the legislative cycle).
This is a read-only verification gate, not an implementation change: it
records the merged surface state in
docs/backend/epac-2296-surface-verification.md and files concrete remediation
for surface-quality gaps. No backend, app, or contract code is changed.

It follows the same in-repo convention as the sibling gates
(epac-2289-staging-bill-diff-coverage.md,
epac-2291/epac-2292-backend-route-verification.md), and is the surface-quality
counterpart to the backend-route gate EPAC-2292.

Verdict: PASS with remediation

All implementation siblings (EPAC-2286/2287/2288/2289/2292/2302/2307) are
Done/merged, so the gate ran. Every changed observed surface was inventoried
and scored:

Surface	Verdict
GET /api/v1/bills/{id}/diff success / 204 / 400 / 404 JSON	Pass — schema-conformant, no raw parser/debug noise
scripts/ci/backend_staging_smoke.py diff checks	Pass — 74/100 cli-scorecard ("decent"); minor banner/--quiet gaps, no issue
backend/bills-indexer run logs	Pass — structured JSON, surfaces diff/clause counts
iOS bill diff viewer (populated / no-changes / unavailable / one-version)	Pass with remediation → EPAC-2309
iOS "Compare versions" entry point	Pass — resolves post-EPAC-2307 numeric-id mapping
Linear evidence + remediation artifacts	Pass — linear-standards.md met

Remediation filed

• EPAC-2309
  (iOS, High, est. 4): the diff viewer defaults to first→last, which returns
  204 for the marquee bill C-11 even though first→middle returns 200 with
  a populated diff — so it opens on the "unavailable" state. The backend 204 is
  correct by design (can't diff a version lacking source text without violating
  the no-rewrite civic-content rule), so the fix is iOS-side: default to a
  servable pair.

Verification evidence

Observed states confirmed firsthand, not from tests alone. Live staging probes
(https://staging-api.epac.riddimsoftware.com, 2026-06-15):

• …/13608745/diff?from=…first-reading&to=…as-passed-by-the-house-of-commons → 204 (iOS default pair)
• …/13608745/diff?from=…first-reading&to=…as-amended-by-committee → 200, populated clauses
• …/13608745/diff (no params) → 400 {"error":"missing required query parameters: from, to"}
• …/13608745 → 200 (3 versions); …/C-11 → 404 {"error":"bill not found"} (confirms EPAC-2307 numeric-id boundary)
• …/ZZ-9999/diff?from=v1&to=v2 → 404 {"error":"bill not found"}

Merged state read from this worktree (top commit 04e05105, EPAC-2307), not the
stale root checkout. lookupBillID resolves both numeric id and display number,
so the diff route serves the id the iOS app now sends and the id the smoke checks
use.

Checks skipped, with reasons

• iOS Simulator run: not performed here — this PR adds only a Markdown
  verification record and changes no app code. The iOS surface was verified from
  merged source, snapshot-test coverage, the EPAC-2307 simulator evidence, and
  live API probes. The remediation EPAC-2309 carries the Simulator-screenshot AC.

Release notes

Docs-only (verification record); no user-facing change, so no Release-Note:.

Closes EPAC-2296.