\\n\\nPreview Branches by Supabase.\\nLearn more about [Supabase Branching ↗︎](https://supabase.com/docs/guides/platform/branching).\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"\\n\\n\\n[![Review Change Stack](https://storage.googleapis.com/coderabbit_public_assets/review-stack-in-coderabbit-ui.svg)](https://app.coderabbit.ai/change-stack/BigSimmo/Database/pull/1909?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)\\n\\n\\n\\n\\n> [!WARNING]\\n> ## Review limit reached\\n> \\n> You’ve reached a temporary PR review limit under our [Fair Usage Limits Policy](https://docs.coderabbit.ai/management/plans#fair-usage-limits-policy).
\\n> Your recent review volume is higher than typical usage, so adaptive limits are currently applied.\\n> \\n> **Next review available in:** **10 minutes**\\n> \\n> Your organization has reached its usage spending cap. Adjust your spending cap in the [billing tab](https://app.coderabbit.ai/settings/billing?tab=usage&orgId=420f13a9-28c9-4ad8-9f2e-1fd2cf273b7c).\\n> \\n>

\\n>

How can I continue?

\\n> \\n> 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.\\n> \\n> 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.\\n> \\n>

\\n> \\n> \\n>

\\n>

How do review limits work?

\\n> \\n> CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.\\n> \\n> 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.\\n> \\n> Please refer [docs](https://docs.coderabbit.ai/management/plans#rate-limits) for additional details.\\n> \\n>

\\n> \\n>

\\n>

Review details

\\n> \\n>

\\n>

⚙️ Run configuration

\\n> \\n> **Configuration used**: Path: .coderabbit.yaml\\n> \\n> **Review profile**: CHILL\\n> \\n> **Plan**: Pro\\n> \\n> **Run ID**: `c47e8e3a-800e-4c04-86f6-afac5094050d`\\n> \\n>

\\n> \\n>

\\n>

📥 Commits

\\n> \\n> Reviewing files that changed from the base of the PR and between a6ca363264d6e8680117e3629abc3469fd0b582f and 8f837e4191892d830fddef68e5d78daa22cefe1f.\\n> \\n>

\\n> \\n>

\\n>

📒 Files selected for processing (11)

\\n> \\n> * `.env.example`\\n> * `docs/branch-review-records/6a5bd9d5cba90563645f1d0ccdbae85ce69990ed735f5494573242f14c7abdc9.record.md`\\n> * `docs/outstanding-issues-inbox/75df9b82-7ecc-4aa2-bdac-653da976fe53.json`\\n> * `docs/outstanding-issues-inbox/e1506952-64c6-472f-9da4-812f8d69b483.json`\\n> * `src/lib/answer-client-payload.ts`\\n> * `src/lib/answer-preview.ts`\\n> * `src/lib/answer-progress-public.ts`\\n> * `src/lib/answer-stream-contract.ts`\\n> * `src/lib/env.ts`\\n> * `src/lib/rag/rag.ts`\\n> * `tests/answer-incremental-delivery.test.ts`\\n> \\n>

\\n> \\n>

\\n\\n\\n\\n\\n\\n

\\n

✨ Finishing Touches

\\n\\n

\\n

📝 Generate docstrings

\\n\\n- [ ] Create stacked PR\\n- [ ] Commit on current branch\\n\\n

\\n

🧪 Generate unit tests (beta)

\\n\\n- [ ] Create PR with unit tests\\n- [ ] Commit unit tests in branch `claude/rag-incremental-delivery-lpw15e`\\n\\n

\\n\\n

\\n\\n\\n\\n\\n---\\n\\n\\n\\n\\n_{Comment `@coderabbitai help` to get the list of available commands.}\\n\\n\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Build previews from the authoritative final source set**\\n\\nWhen the flag is enabled and generation falls back—or an extractive path narrows its evidence—this snapshots every `answerInputResults` source before `selectModelContextResults` or `validatedExtractiveResults` determines the final sources. For example, the existing per-document crowding cap can reduce a nine-source preview to four fallback sources, leaving five preview identities absent from the authoritative `final` payload. This violates the preview/final subset contract and forces a reconciling client to discard the preview, or risks briefly displaying evidence the final response removed; delay emission until the authoritative source selection is known or restrict it to sources guaranteed to remain in every final path.\\n\\nAGENTS.md reference: [AGENTS.md:L957-L965](https://github.com/BigSimmo/Database/blob/387a403a4bf802208420f6847771ada24e1e3eb1/AGENTS.md#L957-L965)\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"src/lib/rag/rag.ts\",\"side\":\"RIGHT\",\"line\":2802}{\"type\":\"pull_request_comment\",\"body\":\"**_{_{![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)}} Track verified-unit sequences at the stream boundary**\\n\\nWhen multiple verified units are emitted in one response—such as Phase 2 sections or an accidental duplicate callback—this always invokes `isDeliverableVerifiedUnit` with its default `lastSequence = null`. Consequently, the same sequence-0 preview is accepted repeatedly and out-of-order section sequences also cross the public SSE boundary, despite the declared strictly increasing contract. Keep the last accepted sequence in the per-stream `sendProgress` state and pass it into validation before forwarding each unit.\\n\\nAGENTS.md reference: [AGENTS.md:L957-L965](https://github.com/BigSimmo/Database/blob/387a403a4bf802208420f6847771ada24e1e3eb1/AGENTS.md#L957-L965)\\n\\nUseful? React with 👍 / 👎.\",\"path\":\"src/lib/answer-progress-public.ts\",\"side\":\"RIGHT\",\"line\":96}{\"type\":\"pull_request_comment\",\"body\":\"\\n### 💡 Codex Review\\n\\nHere are some automated review suggestions for this pull request.\\n\\n**Reviewed commit:** `387a403a4b`\\n \\n\\n

ℹ️ About Codex in GitHub

\\n
\\n\\n[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you\\n- Open a pull request for review\\n- Mark a draft as ready\\n- Comment \\\"@codex review\\\".\\n\\nIf Codex has suggestions, it will comment; otherwise it will react with 👍.\\n\\n\\n\\n\\nCodex can also answer questions or update the PR. Try commenting \\\"@codex address that feedback\\\".\\n \\n

\",\"path\":null,\"side\":null,\"line\":null}{\"type\":\"pull_request_comment\",\"body\":\"\\n\\n\\n\\n\\n\\n\\n\\n@codex resolve actionable Codex review findings for this pull request and current head using the repository instructions. This is the pull request's single automatic repair pass: do not perform a fresh review, create new standalone findings, or request another review. Work only the existing unresolved Codex threads on the current head. The only repository destination is BigSimmo/Database, and the only branch destination is the pull request head branch claude/rag-incremental-delivery-lpw15e at starting commit 31c984af8dc834769d9a69c79a9ea53a71abccb7; never publish fixes to a detached or synthetic work branch and never create a stacked pull request. Use the authenticated GitHub connector to commit each approved fix to BigSimmo/Database:claude/rag-incremental-delivery-lpw15e, then verify that the pull request head contains the published commit before reporting success. Always fix P0 and P1 findings. For P2 and lower findings, fix only clear, scoped, low-risk issues; otherwise disposition them with a concise reason. For a fixed thread, reply with as the first line and as the second line. For a no-code disposition, use followed by . These result markers authorize the workflow to close that exact thread only after it verifies a fixed commit is the pull request head; a local-only commit is not a fix. If publication or verification fails, do not use either result marker, do not claim success, and leave the thread open with the blocker. If human input or new authorization is required, do the same. Finish only after every actionable thread is fixed or dispositioned and closed, or explicitly left open for a human decision. Do not update the branch from main, address unrelated reviews, broaden scope, or create more than one scoped fix commit. Do not use external APIs, paid services, credentials, dependency changes, or broad refactors unless explicitly authorized. Add targeted tests where behavior changes and run the narrowest relevant validation.\",\"path\":null,\"side\":null,\"line\":null}","text_elements",[],{"_609":1989,"_588":589,"_611":595},{"_612":1990,"_614":-5,"_45":-5,"_616":1991,"_618":-5,"_100":369,"_96":620},[1992],{"_621":595},{"_49":1985,"_96":644},{"_609":1994,"_588":589,"_611":595},{"_612":1995,"_614":-5,"_45":-5,"_616":1996,"_618":-5,"_100":369,"_96":620},[1997,1998],{"_621":595},{"_49":2000,"_96":644},{"_49":1999,"_96":644},"\n /workspace/Database\n bash\n 2026-08-13\n Etc/UTC\n /workspace/Database\n","# AGENTS.md instructions for /workspace/Database\n\n\n\n\n# This is NOT the Next.js you know\n\nThis version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.\n\nThis block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.\n\n\n\n\n\n## Dependency shortcut\n\nWhen the user types exactly `dependency` as the entire task message, after trimming surrounding whitespace, treat it as a shortcut for safe dependency maintenance. This is a Codex chat shortcut, not an app feature, script, automation, or CI workflow.\n\nGoal:\nUpdate direct project dependencies to the newest stable compatible versions, regenerate the existing lockfile, identify source/config/test code that relies on old dependency behavior, make the smallest safe compatibility changes, and verify the result. Do not rewrite the project, switch package managers, discard user work, commit, push, deploy, or run destructive cleanup without explicit confirmation.\n\nStart with read-only inspection:\n\n- Check branch, upstream, worktrees, recent relevant history, and `git status`.\n- If on `main`, `master`, `develop`, `release/*`, or another protected/base branch, create/switch to `codex/dependency-maintenance` before editing, if safe.\n- Inspect manifests, lockfiles, package-manager config, runtime/toolchain files, workspace layout, CI config, scripts, and documented checks.\n- Detect repo-local install/dev/test/build/watch/server processes that could race dependency updates.\n- Preserve all existing staged, unstaged, and untracked user work.\n\nPackage-manager rules:\n\n- Use the package manager already used by the repo: npm, pnpm, yarn, bun, pip, poetry, uv, cargo, go, bundler, gradle, maven, dotnet, or equivalent.\n- Do not switch package managers or create a new lockfile type.\n- Respect engines, runtime versions, lockfiles, workspaces, wrappers, and repo conventions.\n- In monorepos or polyglot repos, update each ecosystem through its native workspace-aware workflow.\n\nDependency update rules:\n\n- Identify outdated direct production and development dependencies.\n- Compare both manifest ranges and locked/installed versions against latest stable compatible releases.\n- Treat “outdated packages found” exit codes as normal where applicable.\n- Avoid prerelease, alpha, beta, canary, rc, next, nightly, and experimental versions unless the stable channel points there and explain why.\n- Do not use force or legacy flags that bypass peer, engine, resolver, or lockfile integrity checks unless explicitly approved.\n- Do not run forced audit fixes or broad destructive codemods.\n- If latest is incompatible, use the newest compatible version and document why.\n- Group risky updates coherently, such as framework plus plugins, test runner plus coverage, lint core plus plugins, or runtime plus adapter packages.\n\nCompatibility audit:\n\n- For every major update and every core framework/runtime/build/test/lint/UI/database update, inspect release notes, migration guides, peer ranges, engines, and changelogs when available.\n- Search source, tests, scripts, config, and CI for imports, APIs, CLI flags, config keys, environment variables, plugin names, generated types, or file paths tied to changed dependencies.\n- If old dependency behavior is used, make the smallest safe migration that preserves behavior.\n- If migration is large, risky, architectural, or product-affecting, stop after discovery and provide a concrete fix plan with affected files, package versions, sequence, and verification commands.\n- Add or adjust focused tests only when needed to prove migrated behavior.\n\nGenerated and sensitive files:\n\n- Do not intentionally keep dependency directories, build outputs, caches, logs, local state, test artifacts, browser artifacts, `.env*`, secrets, keys, tokens, credentials, or machine-local config.\n- Manifest and existing lockfile changes are allowed.\n\nVerification:\n\n- Run a cheap baseline first when useful to distinguish pre-existing failures.\n- After updates, run install/dependency validation, then relevant lint, type check, tests, build, smoke/UI/a11y, codegen, integration checks, or equivalent.\n- For frontend/browser-facing changes, run browser/UI verification when framework, bundler, router, styling, test runner, or browser automation changed.\n- If a check fails, fix dependency-related breakage and rerun the smallest failing check before broader checks.\n- Run non-mutating audit/vulnerability checks when available.\n- Confirm no repo-owned dev server, watcher, or temporary process was left running unless requested.\n\nFinal response for `dependency` must include:\n\n- Branch and worktree state.\n- Package manager, runtime, manifests, and lockfiles detected.\n- Outdated dependencies found.\n- Dependencies updated, old version -> new version.\n- Dependencies not updated and why.\n- Files changed.\n- Compatibility migrations and old APIs found/fixed.\n- Checks run and results.\n- Checks not run and why.\n- Audit/vulnerability summary.\n- Generated/untracked files left behind.\n- Branch movement, external repo changes, or process cleanup observed.\n- Risks or follow-up work.\n- Confirmation that no commit or push was made unless explicitly requested.\n\nAfter setup:\n\n- Verify root `AGENTS.md` contains exactly one `## Dependency shortcut` section.\n- Show the final diff for `AGENTS.md`.\n- Summarize what changed.\n- Confirm no dependency update, install, test, build, audit, commit, or push was performed.\n\n\n\n\n\n## Bug-hunter shortcut\n\nWhen the user types exactly `bug-hunter` as the entire task message, after trimming surrounding whitespace, treat it as a shortcut for targeted defect discovery.\n\nExecution rules:\n\n- Invoke the `bug-hunter` skill first.\n- Prioritize reproducible defects over code style, naming, or formatting feedback.\n- Trace realistic failure paths: invalid input, empty states, retries, race/concurrency issues, stale state/cache, network/auth failures, permissions, and boundary values.\n- For each finding, include trigger, expected behavior, actual risk, and the smallest proof (or targeted test/check) that would catch it.\n- If no high-confidence defect is found, explicitly state that and list the most likely residual risk area.\n\nScope and safety:\n\n- Keep the hunt scoped to code touched by the user request unless the defect clearly crosses module boundaries.\n- Do not make broad refactors while hunting; propose minimal fixes for confirmed issues.\n- Run the smallest focused verification for each confirmed defect, then expand only if needed.\n\n\n\n\n\n## Codex review throttling and routing\n\nDo not review branches opportunistically. Review the current changed diff, PR, or branch only when the user explicitly asks for review/audit/hunter/cleanup/upload work, when CI/check failures are the task, or when the current change touches high-risk areas that require a targeted review before handoff.\n\nUse `docs/codex-review-protocol.md` as the shared review protocol for every repo-local review skill, branch/PR review, audit, bug hunt, release-readiness check, and PR/CI review.\n\nBefore reviewing a branch or PR:\n\n- Run `npm run ledger:lookup -- --scope \"\"`. It resolves the HEAD, matches the abbreviated SHAs older records used, and prints an explicit verdict. Do not read `docs/branch-review-ledger.md` by eye — live + archive rows are many, and eyeballing is how repeat reviews slipped through. `ledger:lookup` reads archives under `docs/archive/branch-review-ledger-*.md` too.\n- On `ALREADY REVIEWED`, summarize the prior ledger outcome and skip the repeat review unless the user explicitly requests a fresh pass.\n- On `NOT REVIEWED at this HEAD`, review only the changed scope and append a record after the review.\n\nBefore reviewing multiple branches:\n\n- Build a short branch inventory first: branch, upstream, ahead/behind, last commit, and merged status.\n- Skip branches already merged into `main`.\n- Skip unchanged branches already recorded in `docs/branch-review-ledger.md`.\n- Do not re-review every branch after ordinary coding tasks.\n- If a repeated request targets unchanged reviewed branches, summarize the prior result and ask before doing another full pass.\n\nReview routing:\n\n- `diff-review`: Use for explicit review of the current diff, PR, or named branch. Findings first, ordered by severity, with file/line evidence.\n- `bug-hunter`: Use only for the exact `bug-hunter` shortcut or an explicit defect-hunt request. Prioritize reproducible bugs and smallest proof.\n- `repo-auditor`: Use for explicit repo-wide audit/refactor/dead-code/import/dependency-structure requests. Treat outputs as triage, not automatic delete lists.\n- `release-readiness`: Use for explicit release, merge, PR readiness, or handoff confidence requests. Do not run provider-backed gates without confirmation.\n- `branch-cleanup`: Use only when the prompt explicitly asks for branch cleanup/hygiene or branch deletion candidates. Apply `docs/branch-cleanup-guide.md` and the review ledger before inspecting branch diffs.\n- `pr-ci-fix`: Confirmation-required for this repo. GitHub/GitLab API calls, PR comments, CI reruns, commits, and pushes require explicit user approval and must respect the upload/handoff rules. Exception: an explicit `Run PR` sweep carries this approval (see \"## Run PR shortcut\").\n\nWhen a branch or PR review completes, record it with `npm run ledger:append -- --ref --head --scope --outcome --checks `. It creates one content-addressed immutable record file, so concurrent reviews never edit a shared Markdown hunk. Never hand-write a record: hand-written rows produced the mojibake, wrong-width, and duplicate records that the 2026-07-28 hygiene pass had to repair, and `see PR head` or abbreviated HEADs make the throttle unreliable. The legacy Markdown table is frozen for normal PRs; append a correction or superseding record (`--supersede`) instead. `npm run check:branch-review-ledger` validates all sources, while `check:ledger-write-discipline` rejects a legacy-table row change before it becomes a GitHub conflict.\n\nBabysit / Run PR ledger policy: do not push a tip whose sole delta is a babysit review record (that marks every other open PR behind). One Run PR record per PR per sweep; on a later sweep of the same PR, pass `--supersede` rather than stacking another \"main sync\" record.\n\n\n\n\n\n# Local server safety\n\n- If the user says `run`, execute `npm run ensure` and return the printed URL.\n- If the user asks for UI/frontend changes, browser QA, screenshots, mobile checks, or a local app link, run `npm run ensure` before opening or testing the app, even if the user did not say `run`.\n- Never assume `localhost:3000`, `localhost:3001`, or `localhost:3002`.\n- Never attach to a local server unless `/api/local-project-id` confirms it is this project.\n- Do not kill or modify other projects' local servers. If the stable project port is busy, let `npm run ensure` choose the next safe project URL.\n- Do not run a permanent watcher. Only start or verify the server when the current chat task needs the app or the user asks to run it.\n\n\n\n\n\n# Codex Desktop worktree setup\n\n- The Windows Codex Desktop environment setup command is `node scripts/setup-codex-worktree.mjs`.\n It must work before `node_modules` exists, validate Node 24/npm 11, reuse only a complete\n byte-identical local installation, and otherwise run the locked npm install.\n- Never configure Windows Desktop worktrees to run `bash scripts/setup-codex-cloud.sh`. That script\n is Linux/Cloud-only; Windows launches it through WSL outside the worktree and cannot provision the\n repository.\n- `.codex/environments/environment.toml` is autogenerated and ignored. Change the Database\n environment through Codex settings, then verify the effective command with the generated file and\n `node scripts/setup-codex-worktree.mjs --dry-run`.\n\n\n\n\n\n# Reasoning effort calibration\n\nReasoning effort is a budget in the same way verification is a budget, and it is misspent the same\nway — by defaulting to the maximum instead of matching the spend to the risk. **Scale effort to how\nexpensive the mistake is to undo (irreversibility × branching factor), never to the phase label.**\n\"Plan high, build lower\" is a good default, not a rule; it is wrong often enough that it must be\nchosen deliberately rather than assumed.\n\n**Why it is a good default.** Planning errors compound and implementation errors stay local: a wrong\napproach throws away the build, a wrong identifier is one edit. A plan is also a few thousand output\ntokens against a build's many long turns, so effort is cheapest exactly where it has the most leverage.\n\n**The mechanism that makes it work — do not skip this part.** A lower-effort build only succeeds\nagainst a plan concrete enough to execute: named files, named symbols, ordered steps, and the gate\nthat will prove it. Downgrading the build against a vague plan does not save effort, it relocates the\nthinking into the expensive phase. If the plan cannot name those things, the build is not eligible for\nthe downgrade.\n\n| Situation | Plan | Build |\n| ---------------------------------------------------------------------------------------------- | ----------- | ----------- |\n| Architecture, Supabase migrations/RLS, RAG ranking surfaces, auth/privacy, ingestion contracts | xhigh | high |\n| Ordinary feature or UI work with a clear shape | high | medium–high |\n| Mechanical and fully specified — ledger append, docs edit, rename (not dependency maintenance) | low or skip | medium |\n| Debugging an unknown failure | low | high |\n\n**Where the default inverts and the build needs more than the plan.** These are plan-light and\nexecution-heavy; treating them as plan-heavy spends the budget in the wrong place:\n\n- **Debugging.** The plan is \"find why X fails.\" The real reasoning is hypothesis-forming over local\n runtime, logs, and repro state during the build — hosted providers still need explicit confirmation.\n- **Constraint-dense implementation.** A one-sentence plan whose edit must simultaneously satisfy\n button wiring, design tokens, the one-composer rule, unlayered CSS, and the tap-target and\n phone-chrome contracts. Holding all of it at once is the hard part, not deciding what to do.\n- **Areas where training data is stale.** Next 16 is the standing case. Effort does not repair a wrong\n prior — reading `node_modules/next/dist/docs/` does. Raising effort instead of reading is itself the\n failure mode.\n\n**Constrain xhigh planning output, not just its effort.** Extra-high planning over-produces:\nalternatives, contingency branches, and surveys that are never used, paid for twice — once generating\nand once reading. Ask for the chosen approach, the files, and the gate, not a survey.\n\n**State the split before non-trivial planning work.** One line before starting: plan effort, build\neffort, and the risk that justifies them. It is cheap, it makes a wrong allocation visible while it is\nstill free to change, and it stops the blanket default from being applied silently.\n\n\n\n\n\n# Process hardening phases\n\n- **Verification principle:** run the smallest check capable of detecting a plausible regression introduced by the current diff. Before starting a check, identify the failure class it covers, whether a successful check already covered that class, whether a cheaper focused check offers comparable detection, and whether the incremental confidence justifies the runtime, resource use, and repository-lock contention. If there is no plausible changed failure path, do not run the check.\n\n| Tier | Use when | Default evidence |\n| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| 0 — No test command | Explanation, planning, prompt writing, read-only inspection, or no repository change | No test, build, server, or baseline command |\n| 1 — Static/focused | Documentation, comments, metadata, or narrow non-behavioural configuration | Relevant format, docs, syntax, generated-file, or diff check only |\n| 2 — Focused behavioural | A localized helper, component, contract, or test change | Directly affected unit/DOM/contract test; add typecheck only when the edit can affect compilation or a type contract |\n| 3 — Domain gate | Shared UI/routing, dependencies, security, privacy, RAG, clinical output, production configuration, or another cross-cutting domain | The smallest applicable repository/domain selector, focused journey, or contract gate |\n| 4 — Broad handoff | The diff crosses multiple subsystems, cannot be bounded reliably, or the task explicitly requires PR/release confidence | One appropriate broad gate, selected rather than stacked by default |\n\n- Do not run a broad baseline routinely before localized work, and do not select `verify:cheap` merely because a change is described as “non-trivial.” Use `npm run verify:cheap` once when cross-module risk warrants a broad offline gate. Use `npm run verify:pr-local` when a change is ready for PR handoff: it now classifies the changed paths, runs focused documentation/workflow contracts for recognised low-risk scopes, and fails closed to lint, typecheck, the full unit suite, RAG fixture validation, and relevant build/domain gates for executable or unknown scope. If the diff has not changed, do not run `verify:cheap` first merely to repeat the same coverage.\n- Do not stack focused tests, full tests, typecheck, lint, build, and browser checks unless each catches a distinct plausible regression. Do not rerun an unchanged successful gate. A deliberately skipped low-yield broad gate is not automatically verification debt; report the skipped check and its risk-based reason concisely.\n- A fast-fail subset may precede a broader required gate only when the later gate excludes that subset for the same event; retain a fail-safe full path whenever the subset is skipped. Likewise, do not pre-run a build, install, or server setup that the selected wrapper performs itself. Guard these disjoint/fallback rules with workflow contract tests so a later edit cannot silently restore duplicate work or create a coverage hole.\n- Use dry-run selectors before expensive gates when scope is uncertain. `npm run verify:pr-local -- --dry-run --files ` inspects PR-local selection without running commands. The broader `--extended` plan is dry-run only unless explicit approval is reflected by `ALLOW_EXTENDED_PR_LOCAL=true`.\n- CI uses the same fail-closed scope model: recognised docs and workflow/policy-only changes run focused contracts; executable product/test/config, dependency, database, container, RAG, security-sensitive, mixed, or unknown paths retain the applicable heavy jobs. Do not broaden a path trigger or restore an always-on heavy job without evidence that the focused route misses a realistic failure class. Scheduled drift/release checks and the always-reporting `PR required` aggregate remain safety backstops.\n- Let the repository run coordinator control cross-worktree verification. It permits at most two focused Vitest/read-only typecheck leases from different worktrees; full Vitest, coverage, lint, build, Playwright, and live-provider tests remain exclusive. Do not install while a repository test, build, lint, typecheck, or server command is active. Avoid aggressive short-interval polling, and do not repeat an unchanged full gate after it passes.\n- For UI, frontend, browser, routing, styling, reduced-motion, or forced-colors behaviour changes, run `npm run ensure` before browser work and prove the changed owner or journey first. Use `npm run verify:ui` when shared UI foundations changed or PR/handoff policy requires the complete Chromium gate, not as an automatic addition after focused proof. For phone-chrome changes, run `npm run verify:phone-chrome` first: it checks installed-lock parity, selects the affected browser/PWA owners and exact journeys, and adds `verify:ui` last only when shared chrome foundations make the broad gate necessary. Inspect uncertain scope with `-- --dry-run`. Chromium evidence does not close physical Safari or installed-PWA acceptance gaps.\n- **Run `npm run format` and commit the result before every push.** Formatting is in neither `npm run test`, `npm run typecheck`, nor `npm run lint`, so the ordinary loop can report green while the changed-file CI check or exact-commit pre-push guard fails. Three CI failures on 2026-07-30 came from exactly this (two of them on `ci/circleci: verify`, since removed from the repo by PR #1412). Two traps beyond simply running it:\n - **Formatting without committing does nothing for the push.** A push sends commits, not your working tree, so formatting after committing leaves the unformatted blob on the branch. Amend or add a follow-up commit.\n - **A per-file check is not the repository-wide check.** `prettier --check ` on the source file you edited passes while a doc or ledger edit in the same push fails; that was the missed file twice out of three.\n\n `.githooks/pre-push` carries the guard, and since 2026-07-30 it checks the pushed commit where CI checks it: `guard-push.mjs` puts the pushed SHA in a temporary `git worktree` with an exact-lock `node_modules` linked in and runs Prettier there, so neither the working tree's contents nor its prettier config can vouch for the commit, and a dynamic `prettier.config.*` still loads. An isolated worktree without local dependencies may reuse Prettier only from a registered worktree with a byte-identical lockfile and matching installed Prettier version; if none exists, the guard blocks with the explicit `npm ci --include=dev` remediation instead of skipping formatting. A push that changes prettier policy (`.prettierrc*`, `.prettierignore`, `.editorconfig`, or a `package.json` carrying a `prettier` field) escalates to a whole-tree `prettier --check .`, because a policy change alters the verdict for files the push never touched. But `core.hooksPath` is set by this checkout's `npm install`, so an agent pushing from its own environment bypasses the hook entirely and only CI catches the break — which is why the rule above is still a rule.\n\n- For explicit release confidence, use `npm run verify:release` once; this includes the full Playwright project set and retains all provider-approval requirements. Ordinary local completion or PR handoff does not by itself authorize or require this release gate.\n- For clinical ingestion, answer generation, source governance, privacy, production-readiness, or environment changes, run the smallest relevant domain check plus `npm run check:production-readiness`.\n- For pull requests that touch ingestion, answer generation, search/ranking, source rendering, document access, privacy, production env, or clinical output, complete the clinical governance preflight in `.github/pull_request_template.md`.\n- Track known verification debts and staged process improvements in `docs/process-hardening.md` instead of relying on chat-only memory.\n\n\n\n\n\n# Page and button wiring\n\nInteractive controls and routes follow conventions the codebase already holds to. Before adding\nor moving a button, link, or route, read `docs/wiring-conventions.md`. A control that advertises an\naction must perform one; a page that ships must be reachable.\n\n- **Buttons.** Every interactive `