refactor(rag): extract evidence coverage gate

[BigSimmo]

Summary

• Pure structural extraction (X3 / Extract consolidation fixes #86): move the evidence coverage gate out of the src/lib/rag/rag.ts monolith into a new src/lib/rag/rag-coverage-gate.ts. evaluateEvidenceCoverageGate (exported) and the applyCoverageGateTelemetry helper it owns move byte-for-byte; the only edit to either body is the export keyword added to applyCoverageGateTelemetry, which now crosses a module boundary. git diff --color-moved=zebra classifies 250 of the 275 added lines as moved, and the only three non-moved removals are the two declaration lines that gained export plus one blank line.
• The responsibility is cohesive: the gate is a pure decision function over (query, results, queryClass) that returns an accept/reject verdict, a reason string, and the source-image flags, and applyCoverageGateTelemetry writes exactly those fields onto the telemetry record. Nothing else reads or writes them. Every predicate the gate calls already lives in a stable sibling (rag-evidence-gates.ts, clinical-search.ts), so the module needs no back-edge to rag.ts.
• The shared visualEvidenceUnitTypes taxonomy moved to rag-evidence-gates.ts rather than into the new module, because rag.ts's second-stage rerank (shouldUseSecondStageRerank, secondStageScore) still reads it. Keeping it in rag.ts would have forced a runtime back-edge; putting it in the coverage-gate module would have made ranking code depend on the gate. rag-evidence-gates.ts already owns the neighbouring evidence predicates, so the constant is byte-identical there and both consumers import it.
• Public export strategy: rag.ts explicitly re-exports evaluateEvidenceCoverageGate (export { evaluateEvidenceCoverageGate } from "@/lib/rag/rag-coverage-gate"). This was chosen deliberately to preserve the existing public @/lib/rag/rag API and avoid consumer churn — tests/retrieval-query-variants.test.ts keeps its current import unchanged. npm run check:knip is clean with the re-export in place, and no production consumer imports the symbol.
• Deliberate scope boundary: prepareCoverageGateResults stays in rag.ts. Despite its name it is pipeline orchestration — it calls measureSearchPhase, attachDocumentRankingMetadata, selectRankedRetrievalResults, attachPageVisualEvidence, and applySecondStageRerankIfNeeded, five runtime symbols that exist only inside rag.ts, plus the module-private SearchTiming and DocumentRankingMetadataCache types. Moving it would require either a runtime back-edge to rag.ts or dragging the hydration cluster along, and a signature change to inject those helpers was not acceptable. Its body is verified byte-identical and untouched in place.
• Ratcheted the maintainability budget for src/lib/rag/rag.ts from 5030 down to the new measured 4780, preserving the existing "keep the reclaimed budget" intent so it cannot silently drift back.

Files changed

File	Change
src/lib/rag/rag-coverage-gate.ts	New module: evaluateEvidenceCoverageGate + applyCoverageGateTelemetry (+261)
src/lib/rag/rag.ts	Cluster removed, imports pruned, re-export added (+3 / −253)
src/lib/rag/rag-evidence-gates.ts	Receives the shared visualEvidenceUnitTypes taxonomy (+11)
scripts/check-maintainability-budgets.mjs	rag.ts budget 5030 → 4780 (+3 / −1)
docs/maturity-backlog-workorders.md	X3 progress entry for this extraction (+10)
docs/codebase-index.md	RAG module table row for the two gate modules (+11 / −10, incl. Prettier realignment)

Line counts and movement evidence

• src/lib/rag/rag.ts: 5030 → 4780 lines (−250), measured with sourceLineCount from scripts/check-maintainability-budgets.mjs.
• Configured maintainability budget: 5030 → 4780. Before this change the gate reported src/lib/rag/rag.ts: 5030/5030; it now reports src/lib/rag/rag.ts: 4780/4780.
• git diff --stat: 6 files changed, 299 insertions(+), 264 deletions(-).
• git diff --numstat: 261/0 new module, 11/0 evidence-gates, 3/253 rag.ts, 3/1 budget script, 10/0 + 11/10 docs.
• Total src/lib/rag/** implementation LOC: 18119 → 18141 (+22) — the new module's 24-line import block and 4-line header comment, less the 8 import lines pruned from rag.ts. This is movement, not duplication: each moved function is defined exactly once repo-wide, and no pipeline body was copied.
• Verified against origin/main by extracting the original byte ranges (rag.ts:1864-2077, 2119-2134, 514-523) and diffing them against the new locations: all three blocks are byte-identical modulo the added export keyword. prepareCoverageGateResults (rag.ts:2079-2117 on main) is likewise byte-identical in place.

Verification

• npm run verify:pr-local

During development, use npm run verify:cheap as the faster iteration gate before the final PR-local preflight.

• npm run verify:ui when UI, routing, styling, browser behavior, reduced-motion, or forced-colors behavior changed
• npm run verify:release before release or handoff confidence claims

For retrieval, ranking, selection, chunking, source/citation rendering, or answer-contract changes, verify:pr-local runs eval:rag:offline automatically. Run the offline command directly during iteration before spending a live eval.

• npm run eval:retrieval:quality (must stay 36/36) when retrieval, ranking, selection, chunking, or scoring behavior changed — CI cannot run it (needs live keys), so run it locally and paste the summary. A metadata/governance-weighting change once buried correct docs (recall 1.0→0.76) and only this eval caught it.
• npm run eval:rag -- --limit 15 + npm run eval:quality -- --rag-only when answer generation, the synthesis prompt, or answer post-processing changed (grounded-supported must not drop; citation-failure 0)
• npm run check:production-readiness when clinical workflow, privacy, environment, Supabase, source governance, or deployment behavior changed
• npm run check:deployment-readiness when deployment startup, hosting, or rollout behavior changed

UI verification not run: no UI, routing, styling, browser, reduced-motion, or forced-colors surface is touched by this change — the diff is confined to two src/lib/rag modules, a budget script, and two docs.

Verification not run (provider-backed, deliberately withheld): npm run eval:retrieval:quality, npm run eval:rag, npm run eval:quality --rag-only, npm run check:production-readiness, and npm run check:deployment-readiness all call live OpenAI/Supabase. They were prohibited for this task and were not run. No live evaluation and no RAG canary was run, because this change is a zero-behavior-change structural extraction: the moved function bodies are byte-identical, no comparator, threshold, default, fallback, ordering rule, or await changed, and the byte-range diff against origin/main is the evidence. A reviewer who disputes that classification can refute it cheaply by re-running the byte-range comparison described above; if it is disputed, a live canary pair should be required before merge.

Gates run

Command	Exit	Decisive output
npm run workflow:rag-lab -- --write-evidence	0	Risk classes: retrieval, clinical — planner selected the offline checks; approval-gated live evals left unrun
npm run test -- tests/retrieval-query-variants.test.ts tests/rag-tail-latency.test.ts tests/rag-shared-cache.test.ts tests/rag-variant-early-exit.test.ts	0	Test Files 4 passed (4) / Tests 81 passed (81)
npm run check:maintainability-budgets	0	[maintainability] src/lib/rag/rag.ts: 4780/4780 lines / Maintainability hotspot budgets passed.
npm run check:rag:fixtures	0	Offline RAG fixture and manifest validation passed (36 golden cases, 21 suites).
npm run eval:rag:offline	0	Test Files 21 passed (21) / Tests 567 passed (567) / Offline RAG fixture and production-contract checks passed.
npm run typecheck	0	tsc --noEmit completed with no diagnostics
npm run lint	0	eslint --max-warnings 0 completed with no output
npm run check:knip	0	no unused/unlisted/unresolved/duplicate findings (one pre-existing .css configuration hint)
npm run format:check	0	All matched files use Prettier code style!
npm run verify:cheap	0	Test Files 435 passed (435) / Tests 4569 passed | 4 skipped (4573)
npm run test (full local unit suite)	0	Test Files 435 passed (435) / Tests 4569 passed | 4 skipped (4573)
npm run verify:pr-local -- --dry-run --files …	0	plan is provider-free: runtime, lock parity, format, lint, typecheck, test, build, rag fixtures
npm run verify:pr-local	0	✓ Compiled successfully in 56s, Client bundle secret surface check passed., Offline RAG fixture and manifest validation passed (36 golden cases, 21 suites).
git diff --check	0	no whitespace errors

Each provider-safety decision was made by reading the package script and the scripts it invokes first: eval:rag:offline resolves to check-rag-fixtures.mjs + test-rag-offline.mjs, both of which read local JSON fixtures and spawn Vitest with no fetch, no HTTP, and no OpenAI/Supabase/Railway reference; npm run build only reads a Supabase hostname string for the next/image allowlist and makes no network call.

Risk and rollout

• Risk: LOW for behaviour, MEDIUM for surface sensitivity. The change touches a protected RAG surface (src/lib/rag/**), so the surface is high-consequence even though the diff is a mechanical move. The residual risk is a mis-transcribed body; that is directly refuted by the byte-range comparison against origin/main and by 4569 green unit tests including the full 36-case offline golden fixture set.
• Rollback: single-commit git revert of this commit restores rag.ts and the 5030 budget exactly; there is no data migration, no cache-format change, and no persisted state involved.
• Provider or production effects: None. No OpenAI, Supabase, Railway, live database, ingestion, answer-generation, deployment, or release operation was performed. GitHub was used only to fetch origin/main, push this feature branch, and open this pull request.

Clinical Governance Preflight

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

RAG impact: no retrieval behaviour change — pure module extraction

Notes

• Confirmation of zero intentional behaviour change: no owner or document scope enforcement, admission-before-scope ordering, retrieval ordering, released-result ordering, ranking comparator or comparator-key order, evidence selection, coverage threshold or default, cache semantics, abort semantics, conservative fallback, citation verification, numeric-grounding verification, source governance rule, telemetry name, timing boundary, error propagation, rollback behaviour, clinical behaviour, or provider behaviour was intentionally changed. The gate's thresholds (0.48, 0.58, 0.6, 0.62), its reason strings, its per-query-class branch order, and its telemetry field writes all travelled verbatim.
• Remaining coupling and risk: rag.ts still owns prepareCoverageGateResults, so the gate's input preparation and the gate itself now live in different modules. That is the correct seam today — the preparation step is hydration/rerank orchestration, not gate logic — but it means a future reader must follow one import to see the full call sequence. rag-coverage-gate.ts has no back-edge to rag.ts; its only dependencies are @/lib/types, @/lib/clinical-search, @/lib/rag/rag-contracts (type-only), and @/lib/rag/rag-evidence-gates.
• Handoff: chore(deps-dev): bump prettier from 3.9.0 to 3.9.1 #98 and perf: pre-compute query phrases once per rankAnswerEvidence call #99 remain separate follow-up tasks and are untouched here. The intended later fix: add classifier offset pagination #101 extraction is src/lib/rag/rag-hydration.ts (historically around rag.ts:1505-1736 — the document-ranking-metadata cache, attachDocumentRankingMetadata, withCachedIndexQuality, attachIndexQualityMetadata, and attachPageVisualEvidence); it was deliberately excluded from this PR, and it is the extraction that would let prepareCoverageGateResults move cleanly afterwards. docs: record phase 6 re-audit #100 is also out of scope.

---

Generated by Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 29 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: df1f2c7d-2ce5-4fa5-bc82-12511a4a4145

📥 Commits

Reviewing files that changed from the base of the PR and between 1bff4c7 and d9598b7.

📒 Files selected for processing (6)

• docs/codebase-index.md
• docs/maturity-backlog-workorders.md
• scripts/check-maintainability-budgets.mjs
• src/lib/rag/rag-coverage-gate.ts
• src/lib/rag/rag-evidence-gates.ts
• src/lib/rag/rag.ts

---

_{Comment @coderabbitai help to get the list of available commands.}

[BigSimmo]

PR required went red on cdbcad6 — that is a superseded-run artifact, not a break, and it needs no fix. Recording it here because it is a red required check and auto-merge is armed.

Zero jobs failed. The aggregate's own output:

CHANGES_RESULT: success   STATIC_RESULT: success   SAFETY_RESULT: success
COVERAGE_RESULT: cancelled   BUILD_RESULT: cancelled

##[error]CANCELLED with no failing job: coverage build. Nothing here describes the diff,
so this is not a broken change — but a cancelled job verified nothing, so it cannot go
green either. Usually a newer push superseded this run (cancel-in-progress); look for a
newer 'PR required' run on the PR's current head SHA.

The Update-branch merge (d49ac0f) landed while cdbcad6's run was mid-flight, so cancel-in-progress cancelled coverage and build. Following the gate's own instruction: the newer run 30546667904 does exist on the current head d49ac0f, and the cancelled jobs are re-running there now. PR policy, PR mergeability, Change scope, Semgrep, Semgrep ingestion gate, Gitleaks and GitGuardian have already re-passed on d49ac0f.

Deliberately not pushing anything. A commit now would cancel that in-flight run the same way and race the armed auto-merge, so the fix for this red check is to let the current run finish. I re-verified the extraction survived the main merge at d49ac0f: rag.ts still 4780 lines, budget still 4780, no conflict markers, and both moved function bodies still byte-identical to their pre-merge origin/main originals.

If the run on d49ac0f goes red on a job that actually fails, that one is mine and I will fix it.

---

Generated by Claude Code