docs(agents): tier the always-loaded instruction surface into a core plus reference files

[BigSimmo]

Summary

• Reorganises the always-loaded AI instruction surface into a small core plus named reference files. AGENTS.md + CLAUDE.md: 92,203 → 45,138 bytes (−51.0%).
• No rule is deleted, softened, narrowed, broadened or reworded. All 662 of 662 non-blank lines of AGENTS.md survive byte-identical — machine-checked, not asserted (see Proof).
• AGENTS.md becomes the always-loaded core: the Next.js block, an index, the five irreversible-harm boundaries, and the sections a committed gate parses by exact text. Nine new files under docs/agents/ carry the rest, following the heading+pointer pattern PR f328372 established.
• Every heading stays in AGENTS.md as a pointer stub, so every external reference that names a section by heading still resolves with no edit: .claude/skills/run-pr, newtask, handoff, .claude/agents/pr-ci-fixer.md, .claude/hooks/pr-handoff-stop.sh (×4), tests/claude-code-settings.test.ts.
• CLAUDE.md keeps its orientation role; only its restatements of AGENTS.md rules become pointers, and its two deep-structure sections move verbatim into docs/codebase-index.md, which CLAUDE.md itself designates as their home.
• Repairs two guards this change would otherwise have silently weakened: docs/agents joins the workflow scope maps in ci-change-scope.mjs and productivity-core.mjs (so rule edits keep the workflow CI lane instead of dropping to docs-only), and the new files join userFacingProductSurfaces.
• Updates .claude/cloud-profile/memory/token-usage-hygiene.md, whose standing instruction "do not shrink or restructure AGENTS.md/CLAUDE.md" would otherwise push a future session to revert this.
• Records the immutable review entry for this branch under docs/branch-review-records/, bundled here rather than pushed as a separate ledger-only tip.

Why

The token bill was the smaller cost. The rules that prevent irreversible harm — merging a supabase/migrations/** PR reaches the live clinical database within seconds; the retrieval-ranking surfaces are live-validated and protected — sat in the same undifferentiated wall as the rule about how Prettier treats a per-file check. Everything was emphasised, so nothing was.

Proof that nothing was lost

Every non-blank line of the pre-change AGENTS.md and CLAUDE.md was searched for, byte-for-byte, across the post-change tree:

AGENTS.md: 662 non-blank lines | not byte-identical: 0 | absent: 0
CLAUDE.md: 183 non-blank lines | not byte-identical: 48 | absent: 48

Those 48 CLAUDE.md lines are the 13 bullets that restated AGENTS.md rules (the section's own opening line already read "Full text and rationale in AGENTS.md"), plus two lead-ins. Each is listed below with the file that carries its canonical text. This was the approved scope: CLAUDE.md is the orientation layer and should not hold a second copy of the rules.

What the core keeps, and why

Kept in AGENTS.md	Reason
# This is NOT the Next.js you know	written and re-upserted by next dev; untouched, byte for byte, still first
# Supabase project safety, # RAG ranking protection, # Railway project safety, # API and provider confirmation boundary, # Local server safety	irreversible harm — these read first now
## Bare PR publication is not readiness work + the format-before-push rule	tests/bare-pr-publication-policy.test.ts pins the heading and 9 literal sentences
# Search chrome behaviour	tests/ui-overlay-css-contract.test.ts pins the BEGIN:search-chrome-behaviour marker comment and "Hidden means zero reserve"
## Anti-conflict and CI-speed operating procedure	carries "never an explicit bare PR publication" and "auto-merge state is user-owned" / "must not disable", pinned by two tests
## Codex Cloud environment	check-codex-cloud-setup.mjs requires /^## Codex Cloud environment$/gm exactly once

Text a gate parses is code, not prose. Those sections were quarantined and left alone.

New reference files

File	Receives
docs/agents/verification-gates.md	verification principle, tier table, gate-selection rules, the gate arbiter
docs/agents/pull-request-workflow.md	open PR branch sync, Run PR, babysit budget, review coverage, PR bundling
docs/agents/upload-shortcut.md	the upload shortcut and its eight subsections
docs/agents/wiring-and-bundle-budget.md	page and button wiring, bundle budget
docs/agents/external-skill-precedence.md	external skill precedence, evidence and calibration
docs/agents/claude-hook-scripts.md	the .claude/hooks/*.sh contract
docs/agents/dead-code-deletion.md	deleting code you believe is dead
docs/agents/bug-hunter-shortcut.md	the bug-hunter shortcut
docs/agents/repository-skills-and-issues.md	repository productivity skills, /issues memory
docs/agents/codex-cloud-environment.md (existing)	the inline Codex Cloud bullets — six bullets and the intro paragraph were not present verbatim there and were appended, not assumed

Verification

npm run verify:cheap — the broad offline gate, chosen because the change is cross-cutting.

Test Files  2 failed | 945 passed (947)
     Tests  2 failed | 12050 passed | 4 skipped (12056)

The two failures are pre-existing and not caused by this change: tests/clinical-hazard-controls.test.ts and tests/rag-plan-package-parity.test.ts both need commits (883f1007…, f3d1a3cc…) that are absent from the authoring container's shallow clone (98 commits). Proven, not assumed — both fail identically in a worktree checked out at unmodified origin/main (45a3dca):

Test Files  2 failed (2)
     Tests  2 failed | 17 passed (19)

Every test and script that parses these documents passes:

Test Files  10 passed (10)
     Tests  151 passed (151)

(bare-pr-publication-policy, guard-push, ui-overlay-css-contract, migration-history-guards, setup-codex-worktree, playwright-exit-code-contract, stale-resume-instructions, database-skills, productivity-workflow, route-reachability.)

Gate-manifest OK: all 37 verify:cheap gates are enforced in CI (static-pr + mapped jobs), and the 34 static gates are documented consistently.
Database skill system valid: 35 canonical skills, 8 aliases, 67 repository SKILL.md files across 4 surfaces.
docs link check passed: 4771 repo path references resolve.
docs script-ref check passed: 1202 npm-run reference(s) resolve to real scripts.
[repo-awareness] in step with data/repo-awareness-snapshot.json (204 pages, 575 documents, 2663 reviews)
Hosted migration-role guard passed: active hosted SQL/tooling uses postgres and immutable applied history is unchanged.
[pr-policy] self-test passed / PR policy workflow guard passed.
[Codex Cloud Check] PASS: static Cloud contracts match.
CI change scope self-test passed.
All matched files use Prettier code style!

The ledger commit was verified with the smallest gate that covers an append-only record plus its regenerated index: check:ledger-write-discipline, check:branch-review-ledger, check:ledger-stamp-retention, check:repo-awareness-snapshot, docs:check-links, format:check — all passed.

• npm run verify:cheap (with npm run format committed)
• npm run check:codex-cloud — not in verify:cheap; it carries the ## Codex Cloud environment heading-count assertion
• Verification not run: npm run verify:pr-local — verify:cheap already ran lint, typecheck and the full offline unit suite on this content, and re-running would buy the same verdict twice.
• npm run verify:ui not applicable: no UI, routing, styling, reduced-motion or forced-colors behaviour changed.
• No provider-backed gate was run: no eval:*, verify:release, check:supabase-project, test:live.

Risk and rollout

• Risk: documentation reorganisation plus three path-list additions in build scripts. The failure mode worth naming is an agent following a stale pointer; mitigated by keeping every heading in AGENTS.md and by docs:check-links verifying all 4,771 path references resolve.
• Rollback: revert the two commits. No runtime, schema, or deployment surface is touched.
• Provider or production effects: None. Merging triggers the usual Railway auto-deploy of the app and worker from main, but no application runtime file changed, so it rebuilds the same application.
• RAG impact: none — no retrieval, ranking, selection, scoring, eval-harness or fixture file is touched. The # RAG ranking protection section stays in the always-loaded core, byte-identical.

Clinical Governance Preflight

scripts/pr-policy.mjs classifies this PR as clinical-risk because it touches data/repo-awareness-snapshot.json, and data/** is a clinical-decision surface. That file is the generated documentation index, regenerated by npm run snapshot:repo-awareness because the change adds files under docs/; it carries no clinical content. The classifier is deliberately conservative and cannot make that distinction, so the preflight is completed rather than worked around.

• 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

Basis for each of the above, kept out of the checklist because pr-policy matches those item strings exactly: no retrieval, answer-generation, citation, source-rendering, document, upload, ingestion, access, environment, key-handling or authorization code is touched by this diff. The Supabase target was verified — the # Supabase project safety section stays in the always-loaded core byte-identical and npm run check:migration-role passed. No clinical decision-support behaviour changed, so the deployment-classification/TGA SaMD question was checked and is not applicable: the diff is documentation plus three CI path lists (ci-change-scope.mjs, productivity-core.mjs, list-database-skills.mjs), and no application runtime file is modified.

Notes

• Branch: claude/instruction-tiering-n9vs14, off origin/main at 45a3dca.
• docs/agents/ is now registered in docs/README.md's subdirectory map, and data/repo-awareness-snapshot.json regenerated.
• docs/agents/verification-gates.md gained one new structural heading (## Gate selection) so the file does not open on a dangling bullet list. No rule text changed. This and the new # How these rules are organised index in AGENTS.md are the only prose written for this change.
• Two internal cross-references in AGENTS.md say "above"/"below" about the API-and-provider boundary. They were already one-right-one-wrong before this change; section order was deliberately preserved rather than "fixed", because correcting one would break the other and both are rule text.

Rule inventory

Every heading and every top-level rule in the pre-change files, and where its full text lives now. Generated from HEAD~1 against the post-change tree, not written from memory.

CLAUDE.md restatements that became pointers

Rule (before, in CLAUDE.md)	Canonical text now
Providers need explicit confirmation.	AGENTS.md § # API and provider confirmation boundary
This is not the Next.js you know.	AGENTS.md § # This is NOT the Next.js you know
RAG ranking surfaces are protected.	AGENTS.md § # RAG ranking protection
Supabase target is pinned.	AGENTS.md § # Supabase project safety
Check the review ledger before reviewing a branch or PR	docs/agents/codex-review-throttling.md (already linked from AGENTS.md)
Never assume localhost:3000.	AGENTS.md § # Local server safety
Evidence is never compressed.	docs/agents/external-skill-precedence.md § ## Evidence and calibration are never compressed
Button wiring.	docs/agents/wiring-and-bundle-budget.md § # Page and button wiring
No orphan routes.	docs/agents/wiring-and-bundle-budget.md § New-route checklist
Internal navigation	docs/agents/wiring-and-bundle-budget.md § Navigation
One search composer per page.	AGENTS.md § # Search chrome behaviour ("One owner")
PR bodies are parsed input.	docs/agents/external-skill-precedence.md § PR titles and descriptions are parsed input
Mockups are exempt from two gates, not all of them.	docs/agents/wiring-and-bundle-budget.md § Gates, and § # Bundle budget

- **Design tokens, not hex.** has no counterpart in the rules layer and stays in CLAUDE.md, whole.

Full rule-by-rule inventory

Every heading and every top-level rule (213 rules). A rule with no arrow went where its section went; an arrow marks an exception.

AGENTS.md

# This is NOT the Next.js you know — stays in AGENTS.md

## Dependency shortcut — stays in AGENTS.md

## Bug-hunter shortcut — full text → docs/agents/bug-hunter-shortcut.md (heading kept in AGENTS.md as a pointer)

• Invoke the bug-hunter skill first.
• Prioritize reproducible defects over code style, naming, or formatting feedback.
• Trace realistic failure paths: invalid input, empty states, retries, race/concurrency issues, stale state/cache, ne…
• For each finding, include trigger, expected behavior, actual risk, and the smallest proof (or targeted test/check) …
• If no high-confidence defect is found, explicitly state that and list the most likely residual risk area.
• Keep the hunt scoped to code touched by the user request unless the defect clearly crosses module boundaries.
• Do not make broad refactors while hunting; propose minimal fixes for confirmed issues.
• Run the smallest focused verification for each confirmed defect, then expand only if needed.

## Codex review throttling and routing — stays in AGENTS.md

# Local server safety — stays in AGENTS.md

• If the user says run, execute npm run ensure and return the printed URL.
• If the user asks for UI/frontend changes, browser QA, screenshots, mobile checks, or a local app link, run `npm run…
• Never assume localhost:3000, localhost:3001, or localhost:3002.
• Never attach to a local server unless /api/local-project-id confirms it is this project.
• Do not kill or modify other projects' local servers. If the stable project port is busy, let npm run ensure choos…
• Do not run a permanent watcher. Only start or verify the server when the current chat task needs the app or the use…

# Claude Code hook scripts — full text → docs/agents/claude-hook-scripts.md (heading kept in AGENTS.md as a pointer)

• Pin the executable bit in the index, not on disk. The primary workstation is a Windows ReFS
• Register hooks as bash "$CLAUDE_PROJECT_DIR/…", never as a bare path, so the mode is never
• Line endings are LF. .gitattributes sets * text=auto eol=lf; all hook blobs measure CR=0.
• Hooks must not be able to fail a session. Every hook here exits 0 on any parse problem and
• Set an explicit timeout. The default is 60s, which session-start.sh can exceed on a cold
• SessionStart context comes from stdout, not stderr. A hook that reports on stderr is invisible

# Codex Desktop worktree setup — stays in AGENTS.md

# Reasoning effort calibration — stays in AGENTS.md

# Process hardening phases — stays in AGENTS.md

## Bare PR publication is not readiness work — stays in AGENTS.md

• Inspect only what is necessary to avoid publishing the wrong change: the branch, base, staged/unstaged scope, and P…
• Do not run or wait for npm run format, dependency installation or linking, npm run verify:pr-local, tests, …
• If a local commit hook or a readiness-only push guard (format, drift, static, or ledger-write) is the only blocker,…
• Create the PR immediately after the push, using the repository PR template where its policy fields apply. Report th…
• Verification principle: run the smallest check capable of detecting a plausible regression introduced by the cu… → docs/agents/verification-gates.md
• Do not run a broad baseline routinely before localized work, and do not select verify:cheap merely because a chan… → docs/agents/verification-gates.md
• Do not stack focused tests, full tests, typecheck, lint, build, and browser checks unless each catches a distinct p… → docs/agents/verification-gates.md
• A fast-fail subset may precede a broader required gate only when the later gate excludes that subset for the same e… → docs/agents/verification-gates.md
• Use dry-run selectors before expensive gates when scope is uncertain. npm run verify:pr-local -- --dry-run --files… → **docs/agents/verification-gates.md`**
• CI uses the same fail-closed scope model: recognised docs and workflow/policy-only changes run focused contracts; e… → docs/agents/verification-gates.md
• Let the repository run coordinator control cross-worktree verification. It permits at most two focused Vitest/read-… → docs/agents/verification-gates.md
• Running several Claude Code sessions at once is safe only when each session works from its own worktree (newtask… → **docs/agents/verification-gates.md`
• For UI, frontend, browser, routing, styling, reduced-motion, or forced-colors behaviour changes, run npm run ensur… → **docs/agents/verification-gates.md`**
• For normal engineering pushes, run npm run format and commit the result before push. This rule does not apply…
• For explicit release confidence, use npm run verify:release once; this includes the full Playwright project set a… → docs/agents/verification-gates.md
• For clinical ingestion, answer generation, source governance, privacy, production-readiness, or environment changes… → docs/agents/verification-gates.md
• For pull requests that touch ingestion, answer generation, search/ranking, source rendering, document access, priva… → docs/agents/verification-gates.md
• Track known verification debts and staged process improvements in docs/process-hardening.md instead of relying on… → docs/agents/verification-gates.md

## Do not pay twice for the verdict GitHub is about to reach — full text → docs/agents/verification-gates.md (heading kept in AGENTS.md as a pointer)

• Fail open. Missing data, unreadable CI, an unknown change class, a git failure — every
• CI is never advised by it. CI being set disables the arbiter outright. GitHub stays
• Advisory by default. A DEFER or PROVEN verdict is a recommendation printed with
• A focused run is not full-suite evidence. A narrowed Vitest invocation records under
• A deferred gate is not a passed gate. Report it as "deferred to CI — …has caught

# Deleting code you believe is dead — full text → docs/agents/dead-code-deletion.md (heading kept in AGENTS.md as a pointer)

# Page and button wiring — full text → docs/agents/wiring-and-bundle-budget.md (heading kept in AGENTS.md as a pointer)

• Buttons. Every interactive button element must do something: an onClick, a type="submit"
• Navigation. Internal navigation uses Link, router.push, or server redirect() — never
• New-route checklist. Add the page → link it from real nav (sidebar / launcher / mode home /
• Gates. eslint-rules/require-button-wiring.mjs (in npm run lint) fails on an un-wired
• Never add a production page route without either an inbound link or a documented

# Bundle budget — full text → docs/agents/wiring-and-bundle-budget.md (heading kept in AGENTS.md as a pointer)

• production — every chunk a non-mockup route reaches, plus chunks no route manifest claims
• routes — client JavaScript referenced by / and /documents/search, the same journeys
• mockups — chunks reachable only from /mockups/**. Nobody downloads these, so this is a

# Search chrome behaviour — stays in AGENTS.md

• One owner. A page either uses the shell/dashboard composer, owns an in-flow hero composer, or owns a document-v…
• Phone edge-to-edge contract. Fixed phone composers are flush to the viewport bottom and paint their own safe-ar…
• Hidden means zero reserve. When phone search/header/footer chrome scroll-hides, the content-facing reserve is `…
• Header/footer symmetry. Top header and bottom composer hide/reveal from the same scroll signal where they share…
• Page adaptation. Standalone mode homes keep the composer in-flow in the hero on phones; submitted/search-result…
• Default in-page navigation. When adding or suggesting in-page navigation on any mode page, use the DocumentView…
• Guards. Update the reserve helper, CSS tokens, Playwright phone-scroll coverage, and static contract tests toge…

# External skill precedence — full text → docs/agents/external-skill-precedence.md (heading kept in AGENTS.md as a pointer)

• Repo contracts outrank generic rules. The Front-End Checklist skill corpus (~390 user-global
• Never regress a fixed flake to satisfy a generic rule. Known collision: generic touch-target
• Unlayered CSS is deliberate. Component classes in globals.css intentionally override
• Cite the source when applying an external rule. If a checklist rule drives a change, name the

## Evidence and calibration are never compressed — full text → docs/agents/external-skill-precedence.md (heading kept in AGENTS.md as a pointer)

• Always paste the decisive line. Report gates with real output, not a summary. Under heavy-lock
• State verified versus assumed. Calibration is not filler. Say what was actually run, what was
• Third-party fix claims stay unverified until checked. Bot or agent claims that a fix landed
• PR titles and descriptions are parsed input, not prose. .github/workflows/pr-policy.yml

# Supabase project safety — stays in AGENTS.md

• This repo targets the live Supabase project Clinical KB Database.
• MERGING TO main DEPLOYS TO PRODUCTION. The Supabase GitHub integration has **"Deploy to
• Expected project ref: sjrfecxgysukkwxsowpy.
• Older unused project ref qjgitjyhxrwxsrydablr belongs to Database; treat it as stale and do not use it.
• Hosted migrations, supabase/schema.sql, supabase/roles.sql, CI, and deployment tooling must target role `postgr…
• Bare-image storage scaffolding must discover its local schema owner at runtime and must never be reused as hosted m…
• Run npm run check:migration-role after changing Supabase SQL, migration tooling, CI replay, or disaster-recovery …
• Run npm run check:supabase-project after changing Supabase env values.
• Guard-migration contract. Any mark-applied version, supabase migration repair --status applied,

# RAG ranking protection — stays in AGENTS.md

• Flag it. Any task that will touch src/lib/rag/**, clinical-search, retrieval-selection,
• PR gate. PRs touching those surfaces fail pr-policy without an explicit RAG impact:
• Canary for behaviour. Any retrieval/ranking/ordering behaviour change requires a live
• Never insert a comparator key above the relevance score, bulk-merge the wide

# Railway project safety — stays in AGENTS.md

• This repo deploys to the live Railway project Database (5deaad0b-675a-4c13-978e-5ca2b5b877f9) in workspace `big…
• Production services Database (Next.js app tier, serves https://psychiatry.tools) and worker (ingestion) auto-…
• The older Railway project clinical-kb (4361c04f-dd3c-4ee9-9e97-49e4e5707b70) is superseded with zero active dep…
• The similarly named Supabase project Clinical KB Database is the database/auth tier, not a Railway project; see "…
• Railway CLI token auth uses RAILWAY_API_TOKEN (personal account token; see .env.example). The project-scoped `R…
• Railway deploys and mutations fall under the "API and provider confirmation boundary" below; verify target project/…

# API and provider confirmation boundary — stays in AGENTS.md

• Never run, modify, test, or otherwise interact with OpenAI, Supabase, GitHub/GitLab, hosted CI, production-like ser…
• Treat indirect API usage inside scripts, tests, release checks, PR tooling, and review automation as confirmation-r…
• Prefer local, static, mocked, or offline checks. If a recommended verification would touch a provider, report the c…
• npm run check:supabase-project, live PR/CI tooling, answer-generation checks, ingestion checks against live servi…
• Exception: the Run PR shortcut (see "## Run PR shortcut") is standing user confirmation for the specific GitHub a…

# upload shortcut — full text → docs/agents/upload-shortcut.md (heading kept in AGENTS.md as a pointer)

## Protected and base branches — full text → docs/agents/upload-shortcut.md

• If neither local temporary nor origin/temporary exists, run git switch -c temporary.
• If local temporary exists and is not checked out in another worktree, switch to it only when it is clearly safe.
• If origin/temporary exists, use it only when it is clearly the matching intended branch.
• If any temporary branch state is ambiguous, diverged, checked out elsewhere, or unsafe, stop and ask instead of o…

## Required inspection — full text → docs/agents/upload-shortcut.md

• Current branch or detached HEAD state
• git status
• Staged, unstaged, and untracked files
• Recent commits relevant to the current branch
• Remote configuration and upstream branch
• Whether the branch is ahead, behind, or diverged
• Whether the current branch appears protected/base
• Other Git worktrees, if detectable
• Available checks such as tests, lint, type check, or build scripts
• Existing branch, commit, PR, and release-flow conventions

## Safe actions allowed without further confirmation — full text → docs/agents/upload-shortcut.md

• Stage coherent completed changes that clearly belong together
• Create one or more logical commits with clear messages based on the diff
• Fast-forward pull only when there are no local commits or conflict risks
• Push the current non-protected feature branch if it has a valid upstream
• Set an upstream for the current feature branch only when the correct remote and branch name are obvious
• Leave the worktree clean by committing safe completed changes

## Actions requiring explicit confirmation — full text → docs/agents/upload-shortcut.md

• git reset --hard
• git clean -fd or other destructive cleanup
• Discarding, overwriting, or reverting uncommitted changes
• Deleting local or remote branches
• Renaming branches
• Force-pushing
• Rebasing a shared/public branch
• Resolving divergent branch history
• Merging into main, master, develop, release/*, or any protected/base branch
• Closing pull requests
• Changing GitHub default branch, branch protection, repository settings, or deployment settings
• Modifying production data or deployment configuration
• Committing secrets, credentials, tokens, private keys, or sensitive local configuration
• Updating branch references where the correct replacement branch is ambiguous

## Mixed, suspicious, or unsafe changes — full text → docs/agents/upload-shortcut.md

## Branch cleanup and reference updates — full text → docs/agents/upload-shortcut.md

## Syncing and verification — full text → docs/agents/upload-shortcut.md

## Final report — full text → docs/agents/upload-shortcut.md

## Open PR branch sync (anti-churn) — full text → docs/agents/pull-request-workflow.md (heading kept in AGENTS.md as a pointer)

• Automatic GITHUB_TOKEN branch updates are prohibited: bot-authored heads
• Local/operator dry-run: npm run sync:pr-branches. Apply with the current
• Prefer fewer long-lived open PRs; land or close queue items rather than
• Before mutating an open PR with update-branch or git merge origin/main,
• The historical review table is frozen during normal PR work. Write a new review

## Run PR shortcut — full text → docs/agents/pull-request-workflow.md (heading kept in AGENTS.md as a pointer)

• GitHub reads: pull requests, checks, workflow runs and job logs, review threads.
• Pushing ordinary commits to PR feature branches (never main or another protected branch).
• Review-thread replies and review-thread resolution.
• Re-running failed hosted CI jobs and updating a PR branch from main.
• Never merge a pull request into main or any protected branch, and never enable auto-merge; the sweep fixes and re…
• Never close a pull request, delete or rename branches, force-push, or rebase.
• Never run provider-backed gates: eval:rag, eval:quality, eval:retrieval:quality, verify:release, `check:sup…
• Respect the skip-codex-review label as a full per-PR opt-out.
• Preserve unrelated staged, unstaged, and untracked work; never commit secrets.
• Resolve branch drift only with an explicitly authenticated update-branch call or git merge origin/main; skip and …
• Before treating GitHub DIRTY/CONFLICTING as a real conflict, confirm with git merge-tree (see "## Open PR bra…

## Babysit the pull request, then stop — full text → docs/agents/pull-request-workflow.md (heading kept in AGENTS.md as a pointer)

• Read checks, workflow runs, and job logs; re-run a failed job; sync the branch from
• Fix what this change broke and push the fix. The smallest correct gate still applies to
• Look on a slow cadence — roughly five minutes between checks, and wait with
• Stop as soon as CI settles. A green run ends the babysit; so does a failure that is
• Record the npm run ledger:append row if it is still owed.
• Give the user the PR URL, a short summary, and plainly where CI stands — green, red
• Then stop. The merge, review-bot findings, and anything still unresolved are the user's
• Inside the budget — shell polling (gh pr checks|status|view|…, gh run …,
• Past the budget — all of those are denied, so the session reports and stops rather

## Automated review coverage (owner decision, 2026-08-22) — full text → docs/agents/pull-request-workflow.md (heading kept in AGENTS.md as a pointer)

• Draft PRs are skipped by CodeRabbit outright; undrafting mid-CI cancels the in-flight run.
• Do not weaken, skip, or relax any required check to compensate. Required gates carry the deterministic safety n…
• Clinical-risk and RAG-surface diffs still require their PR-body preflight sections in full (scripts/pr-policy.mjs…
• Reduce PR churn by bundling low-risk append-only paperwork with product PRs (see below).

## PR bundling (reduce one-task-one-PR churn) — full text → docs/agents/pull-request-workflow.md (heading kept in AGENTS.md as a pointer)

• Independently low-risk, checked two ways:
• Committed as its own separately revertible commit while the PR is open (one PR with multiple commits, not one s…
• Listed as its own bullet in the PR body's Summary.
• Not already mid-edit in another open PR or session (check local context / review ledger first).
• A change needing its own RAG impact: line together with one that does not.
• A change needing ## Clinical Governance Preflight together with unrelated chores.
• Anything explicitly scoped "1 PR per work order" by its own tracking doc (e.g. `docs/maturity-backlog-workorders.md…

## Anti-conflict and CI-speed operating procedure — stays in AGENTS.md

### Prevent conflicts before they start — stays in AGENTS.md

• Prefer fewer, shorter-lived PRs. Bundle independently low-risk append-only docs/ledger chores (see "## PR bundling"…
• Start from a fresh origin/main worktree/branch (newtask); do not pile new work onto a stale head that already s…
• The legacy docs/branch-review-ledger.md and docs/outstanding-issues.md are serial-only: normal PRs must not…
• Before calling GitHub DIRTY/CONFLICTING a real conflict, run git merge-tree --write-tree origin/main …. C…

### Speed CI without skipping quality — stays in AGENTS.md

• Assemble every commit for a head before the first push, or wait for the current PR CI run to settle before pushing …
• For Run PR sweeps and normal readiness pushes — never an explicit bare PR publication — run npm run format **and …
• If a PR has auto-merge armed, its auto-merge state is user-owned and automation must not disable or re-enable it. O…
• Missing CI checks are not a green pass. The PR mergeability check uses trusted pull_request_target events and r…
• Triage and repair actionable review threads early; reply before resolving (disposition marker comment).
• Babysit dormant: observe fresh CI only at meaningful stage boundaries (at most once every 5 min, ≤30 min per run). …
• For sweeps needing local repair, prepare one isolated, exact-lock worktree via `node scripts/setup-codex-worktree.m…
• Treat merge queue state as read-only. Fall back to Actions runs for exact head SHA if gh pr checks cannot read ch…
• Treat outstanding-issue IDs as display locators, not proof that work landed. Queue changes only through `npm run is…
• Keep Playwright blocking tests at zero retries; quarantine via tests/flake-ledger.json only after three reproduct…

### Operator sync (explicit only) — stays in AGENTS.md

• Leave active PRs alone unless requested. Report: npm run sync:pr-branches. Apply with confirmation and human/oper…

## Codex productivity defaults — stays in AGENTS.md

## Repository productivity skills — full text → docs/agents/repository-skills-and-issues.md (heading kept in AGENTS.md as a pointer)

• plan: plan risk-scoped verification before non-trivial changes.
• fix: diagnose and repair local verification failures with the smallest reproducer.
• clinical: assemble clinical, privacy, source, and rollback evidence.
• ui: inspect the running app across routes, breakpoints, and accessibility modes.
• rag: validate retrieval and answer changes offline first, then prepare live-eval approval gates.
• operations: turn pending operator debt into a deduplicated, approval-gated batch.
• task: manage safe start, handoff, merge proof, and cleanup transitions.

## Outstanding-work memory (/issues) — full text → docs/agents/repository-skills-and-issues.md (heading kept in AGENTS.md as a pointer)

• When the user types /issues, invoke the issues skill (.claude/skills/issues/SKILL.md): run `npm run issues:re…
• /issues add|done|update|queue … queue immutable request files under docs/outstanding-issues-inbox/. Ordinary br…
• Proactively offer to capture unresolved follow-ups, deferrals, and known risks into the ledger before session conte…
• Before acting on a queued item, check open PRs for overlapping routes or components to avoid duplicate concurrent w…
• The SessionStart hook (.claude/hooks/issues-surface.sh, wired in .claude/settings.json) auto-surfaces the rec…

## Codex GitHub review behavior — stays in AGENTS.md

## Codex Cloud environment — full text → docs/agents/codex-cloud-environment.md (heading kept in AGENTS.md as a pointer)

• Configure setup as bash scripts/setup-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh.
• Configure maintenance as `bash scripts/maintain-codex-cloud.sh && bash scripts/install-codex-cloud-command-shims.sh…
• Default to CODEX_CLOUD_ACCESS_PROFILE=offline for ordinary/RAG work; use connected only with explicit provider …
• Personal Pro split control plane: Codex Cloud for code and GitHub connector; ChatGPT web for Railway and read-only …
• Acceptance: run bash scripts/check-codex-cloud-raw-env.sh, npm run check:codex-cloud, and `npm run check:codex-…
• Do not expose provider secrets (OpenAI, Supabase, Railway, GitHub PATs) in Cloud agent shells or committed config.
• Authenticated live tests run via .github/workflows/authenticated-live-tests.yml with manual dispatch, never from …
• Branch deletion helper bash scripts/delete-codex-cloud-branch-with-pat.sh is operator-only outside Cloud.

## Cursor Cloud specific instructions (not Codex Cloud) — stays in AGENTS.md

CLAUDE.md

# PsychSift — orientation for AI assistants — stays in CLAUDE.md

## How the instruction files divide up — stays in CLAUDE.md

## Highest-consequence rules — heading stays in CLAUDE.md; every bullet became a pointer (canonical text in the table above)

• Providers need explicit confirmation. Never touch OpenAI, Supabase, GitHub/GitLab, → restatement; canonical text listed above
• This is not the Next.js you know. Next 16 has breaking changes versus most training → restatement; canonical text listed above
• RAG ranking surfaces are protected. Flag the task before editing anything under → restatement; canonical text listed above
• Supabase target is pinned. Live project Clinical KB Database, ref → restatement; canonical text listed above
• Check the review ledger before reviewing a branch or PR: → restatement; canonical text listed above
• Never assume localhost:3000. Use npm run ensure and the URL it prints. → restatement; canonical text listed above
• Evidence is never compressed. Paste the decisive line from a gate. Exit code 0 alone → restatement; canonical text listed above

## Stack and runtime — stays in CLAUDE.md

## Repository layout — full text → docs/codebase-index.md § Orientation summary (CLAUDE.md keeps a pointer)

## The two flows that matter — full text → docs/codebase-index.md § Orientation summary (CLAUDE.md keeps a pointer)

## Development workflow — stays in CLAUDE.md

## Conventions the gates enforce — heading stays in CLAUDE.md; six of seven bullets became pointers, the seventh stays whole

• Button wiring. Every button element does something — handler, submit inside a form, or → restatement; canonical text listed above
• No orphan routes. A new production page route needs an inbound link from real nav, → restatement; canonical text listed above
• Internal navigation uses Link / router.push / server redirect() — never a raw → restatement; canonical text listed above
• One search composer per page. A page uses the shell/dashboard composer, an in-flow hero → restatement; canonical text listed above
• Design tokens, not hex. eslint-rules/no-hardcoded-hex.mjs, plus type-scale, — stays in CLAUDE.md, whole
• PR bodies are parsed input. scripts/pr-policy.mjs hard-blocks merges when a → restatement; canonical text listed above
• Mockups are exempt from two gates, not all of them. src/app/mockups/** and *-mockups.tsx → restatement; canonical text listed above

## Repo-specific tooling — stays in CLAUDE.md

• Claude skills (.claude/skills/): newtask (fresh worktree off latest main),
• Review subagents (.claude/agents/): rag-retrieval-reviewer,
• Skill catalogue (.agents/skills/): npm run skills lists the canonical single-word
• Session memory: a SessionStart hook surfaces the recommended queue from

---

🤖 Generated with Claude Code

https://claude.ai/code/session_017ou4w8atP9kDKHVAXUvYPe

[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]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 26439e69-f6be-4cbf-b95d-c5434f58015d

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T05:16:16.210738Z	f0ba1e1	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_34ed20e8-d435-47cb-91d5-2dce410d1608)