Merge branch cleanup and review workflow updates

.cursor/skills/accessibility-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews keyboard navigation support, semantic HTML tags, drawer/dia
 
 Use this skill when reviewing user interfaces to ensure compliance with a11y standards.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Keyboard & Focus Control

.cursor/skills/ai-architecture-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews RAG flows, context assembly, model routing, structured outp
 
 Use this skill when reviewing or modifying the RAG (Retrieval-Augmented Generation) pipeline, document retrieval, and LLM integrations.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Retrieval Quality & Provenance

.cursor/skills/api-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews API routes for routing contracts, input schema validation (
 
 Use this skill when reviewing or modifying API routes, endpoints, or network boundaries within this repository (primarily under `src/app/api/`).
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Request Validation

.cursor/skills/code-quality-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews code quality, naming structures, control flow patterns, abs
 
 Use this skill when auditing source files for maintainability, readability, and structural patterns.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Maintainability & Naming

.cursor/skills/design-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews layout density, theme adherence, typography, spacing, and v
 
 Use this skill when auditing UI styling, colors, layout structures, and spacing rules.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Style & Spacing Consistency

.cursor/skills/frontend-architecture-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews Next/React boundaries, state ownership, duplicated client s
 
 Use this skill when reviewing Next.js App Router structures, component boundaries, state management, and React performance.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Next.js App Router Boundaries

.cursor/skills/performance-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews model latency/cost, cache policies, duplicate query coalesc
 
 Use this skill when reviewing query bottlenecks, database RPC latencies, client bundle sizes, or API cost overhead.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Database & API Latency

.cursor/skills/release-readiness-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews build validation, linting/type-checking, target database ch
 
 Use this skill when preparing a branch for merging, pull request submission, or production deployment.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Build & Automation Checks

.cursor/skills/repo-auditor/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews module dependencies, broken imports, unused files, and stru
 
 Use this skill when auditing the workspace layout, folder structures, imports, and dependencies.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Structural Audits

.cursor/skills/security-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews credentials, token handling, JWT claims, service-role confi
 
 Use this skill when reviewing code that touches authentication, database schemas, environment variables, storage, or external API gateways.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Key Confinement & Environment Safety

.cursor/skills/supabase-postgres-best-practices/SKILL.md

@@ -25,6 +25,8 @@ Reference these guidelines when:
 - Optimizing for Postgres-specific features
 - Working with Row-Level Security (RLS)
 
+For review-only use, follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` first. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Rule Categories by Priority
 
 | Priority | Category                 | Impact      | Prefix      |

.cursor/skills/testing-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews unit/integration/E2E coverage, checks for fragile/flaky tes
 
 Use this skill when reviewing test coverage, testing harnesses, and test execution paths (Vitest + Playwright).
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Test Harness Coverage

.cursor/skills/ux-review/SKILL.md

@@ -7,6 +7,10 @@ description: Reviews the question-to-answer flow, source-review friction, eviden
 
 Use this skill when reviewing user interface flows, search input behaviors, sidebars, modal navigation, and responsiveness.
 
+## Repository Review Protocol
+
+Follow `AGENTS.md` review throttling and `docs/codex-review-protocol.md` before starting. Do not review opportunistically, do not mutate files during pure review, and update `docs/branch-review-ledger.md` after completed branch/PR reviews.
+
 ## Review Checklist
 
 ### 1. Search Composer Integration

.github/workflows/live-drift.yml

@@ -0,0 +1,59 @@
+name: Live drift check
+
+# Live Supabase drift detection is useful, but it must not slow PR iteration or
+# touch live services on every branch. Keep it scheduled/manual only.
+on:
+  workflow_dispatch:
+  schedule:
+    # Weekly, aligned with the existing Sunday off-peak CI cadence.
+    - cron: "30 18 * * 0"
+
+concurrency:
+  group: live-drift-check
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+env:
+  NEXT_PUBLIC_SUPABASE_URL: https://sjrfecxgysukkwxsowpy.supabase.co
+  SUPABASE_PROJECT_REF: sjrfecxgysukkwxsowpy
+  SUPABASE_PROJECT_NAME: Clinical KB Database
+  NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY: placeholder-ci-anon-key
+  SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}
+
+jobs:
+  live-drift:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Preflight required secrets
+        run: |
+          missing=""
+          [ -z "$SUPABASE_SERVICE_ROLE_KEY" ] && missing="$missing SUPABASE_SERVICE_ROLE_KEY"
+          if [ -n "$missing" ]; then
+            echo "::error::Live drift check cannot run - missing repo secrets:$missing"
+            exit 1
+          fi
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version-file: ".nvmrc"
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Guard Supabase project identity
+        run: npm run check:supabase-project
+
+      - name: Compare live schema drift
+        run: npm run check:drift

docs/branch-cleanup-guide.md

@@ -41,7 +41,19 @@ Before deleting anything:
    git worktree list --porcelain
    ```
 
-5. For each candidate branch, check whether it has patch content not on `main`:
+5. Filter candidates through the review ledger before inspecting branch diffs. Follow the lookup procedure in `docs/branch-review-ledger.md` and require all three fields to match before skipping:
+
+   ```powershell
+   $branch = "BRANCH_NAME"
+   $head = git rev-parse $branch
+   $escapedBranch = [regex]::Escape($branch)
+   Get-Content docs\branch-review-ledger.md |
+     Select-String -Pattern "\|\s*$escapedBranch\s*\|\s*$head\s*\|\s*branch-cleanup\s*\|"
+   ```
+
+   Skip the branch only when a ledger row matches the same branch/ref, reviewed HEAD, and `branch-cleanup` scope together. A branch-name-only match is not enough. Re-review when the HEAD changed or the user explicitly asks for a fresh pass.
+
+6. For each remaining candidate branch, check whether it has patch content not on `main`:
 
    ```powershell
    git log --format="%h %s" --right-only --cherry-pick main...BRANCH_NAME
@@ -53,9 +65,11 @@ Delete a branch only when the cherry-pick-aware log is empty, or when the branch
 ## Recommended Cleanup Order
 
 1. Fetch and inspect current branch state with the commands above.
-2. For each candidate branch, confirm patch-unique commits and file diffs against `main`.
-3. Port, commit, or explicitly reject useful patch content before deleting any branch ref.
-4. Remove detached worktrees only when clean, unneeded, and absent from active `git worktree list` output.
+2. Resolve each candidate's HEAD and skip unchanged completed reviews recorded in `docs/branch-review-ledger.md`.
+3. For each remaining candidate branch, confirm patch-unique commits and file diffs against `main`.
+4. Port, commit, or explicitly reject useful patch content before deleting any branch ref.
+5. Record completed cleanup reviews in `docs/branch-review-ledger.md`.
+6. Remove detached worktrees only when clean, unneeded, and absent from active `git worktree list` output.
 
 ## Final Verification
 

docs/branch-review-ledger.md

@@ -0,0 +1,23 @@
+# Branch Review Ledger
+
+Use this ledger to prevent repeated branch and PR reviews when the reviewed HEAD has not changed.
+
+## Lookup Procedure
+
+1. Identify the target branch or ref from the user request. If no target is named, use the current branch.
+2. Resolve the current HEAD:
+
+   ```powershell
+   git rev-parse <branch-or-ref>
+   ```
+
+3. Search this file for a row with the same branch/ref, reviewed HEAD, and review scope.
+4. If the HEAD and scope match an existing completed row, do not repeat the review. Summarize the prior outcome and ask before doing a fresh pass.
+5. If the HEAD changed, or the user explicitly requests a fresh review, review the changed scope and append a new row.
+6. For branch-cleanup passes, run this lookup before inspecting branch diffs so unchanged reviewed branches are filtered out early.
+
+## Review Records
+
+| Date       | Branch or ref  | Reviewed HEAD | Scope          | Outcome                                                       | Checks                                                                                                     |
+| ---------- | -------------- | ------------- | -------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| 2026-07-09 | example/branch | abc1234       | branch-cleanup | Example: already merged into `main`; no unique patch content. | `git log --right-only --cherry-pick main...example/branch`; `git diff --name-status main...example/branch` |