docs(db): record the execution traps and parallel-session coordination rules

[BigSimmo]

Summary

Makes durable the knowledge a long multi-session session accumulated but the repo did not hold: the traps this remediation programme has already hit, and the rules for running two phases concurrently.

This extends the playbook rather than adding a new coordination document, deliberately. A docs/database-remediation-coordination.md was the obvious move and I decided against it: the playbook already opens with "This playbook exists so the work can be executed across many separate chat sessions" — it is the coordination guide. A fourth file would have duplicated its phase list, refs, status and prompts, and gone stale the moment one of the two was updated alone. CLAUDE.md's argument for keeping AGENTS.md / CLAUDE.md / codebase-index.md non-overlapping is precisely the drift this would have created.

What the playbook genuinely lacked was the failure knowledge, so that is what this adds.

Traps this programme has already hit

All observed during execution; none hypothetical.

• The newest migration mentioning a match_* function often does not define it. These functions are redefined 2–16 times each across migrations, and 20260724130000_explicit_base_match_rpc_execute_grants.sql — the newest file mentioning several of them — contains zero create or replace function; it only re-asserts grants. Same shape for 20260724120000_table_facts_plpgsql_execute.sql. Verified by inspection, and it matters directly for Phase 1.2: diffing against a grants-only file would produce a meaningless result.
• Normalize before joining live functions to the manifest — otherwise all 93 report as simultaneously missing and extra. That is a join failure, not a finding. (Recorded in the forensics doc; surfaced here because a fresh session reads the playbook first.)
• Resolve ledger rows by exact title and confirm the row is still in the open table. The tracking anchor was once cited as #312, an unrelated Playwright row. Separately, a close request for #333 was queued after confirming a #333 row existed — but the match was the archived row, and the invalid request threw #333 is already archived, red-lining docs:check-links for the whole branch. The existence check was not the check that mattered.
• Node 24 is mandatory under engine-strict; a container shipping Node 20/22 fails npm ci with EBADENGINE and leaves tsx unresolvable, which fails check:runtime.
• Two tooling failures are already fixed in fix(ledger,guard): survive parallel reconciles and rewritten history #1978 — the ledger cancel-race and the guard-push base resolution. Their symptoms are named so a future session recognises them instead of re-diagnosing, and knows neither should need an override.

Running two phases at once

Phases with different targets — Phase 1.2 read-only against production, Phase 2 mutating staging — can safely run concurrently. The collision surface is the ledger, not the database:

• One ledger row per session, assigned explicitly in the prompt. Two pending mutations on one row make the inbox refuse the whole batch.
• One reconciliation at a time from a fresh base. Three ran in parallel on 2026-08-14 and collided.
• Never merge main into a PR carrying a reconciliation — it turns a complete transaction into a partial one.
• After a PR lands, verify the content on main, not the commit title (#324).

Verification

• npm run verify:pr-local

PR-local verification summary:
- completed: check:runtime, check:installed-lock-parity, format:changed, sitemap:check,
  docs:check-index, docs:check-inventory, docs:check-scripts, docs:check-links,
  check:branch-review-ledger, check:outstanding-issues, check:ledger-write-discipline
- failed: (none)
- not reached: (none)

• npm run docs:check-links → docs link check passed: 1767 repo path references resolve.
• npm run docs:check-index → coverage OK.
• npm run format run and committed.

Documentation-only scope, so the gate stayed on the focused docs route — no lint, typecheck, test or build, correctly.

Not run: verify:ui, provider-backed gates — nothing here touches UI or a provider.

RAG impact

Not required: documentation only. No file under src/lib/rag/**, no match_* RPC, no ranking, selection, eval-harness or fixture surface. The RPCs are described, not changed.

Risk and rollout

• Risk: None to runtime. One markdown file.
• Rollback: git revert the single commit.
• Provider or production effects: None.

Notes

• The factual corrections from the same review (20 missing indexes not 21, phase statuses, the open-PR pre-flight) landed separately in ci(lexicon): gate the generated lexicon report, and correct the remediation records #1979; this adds only the material that had no home.
• Companion context: test(live-drift): prove the drift routing, and close out Phase 0 #1951 closed Phase 0 including the forced-dispatch proof; fix(ledger,guard): survive parallel reconciles and rewritten history #1978 fixed the two tooling defects named above.
• Next in the programme: complete Phase 1.2 (the RPC dossier — all ten remaining functions are UNCLASSIFIED, and Phase 3's own stop rule forbids touching UNCLASSIFIED entries, so Phase 3 has zero actionable work until then), and the Phase 2 staging rehearsal, which can run concurrently against a different database.

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[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: 59 minutes

Limit details: You’ve used all 1 included review currently available under your plan. You completed 95 included PR reviews in the past 7 days; at that activity level, included reviews refill at 1 review per hour.

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: 00bdae42-6496-43ee-a2b9-9a23cc1fc537

📥 Commits

Reviewing files that changed from the base of the PR and between 78fe906 and c7c4248.

📒 Files selected for processing (1)

• docs/database-remediation-playbook.md

---

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

[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 ↗︎.