docs: make migration rollout and rollback guidance safe

[BigSimmo]

Summary

• replace the stale sole-pending-migration assumption with an exact, ordered review of 20260717120000, 20260717170000, and 20260717171000
• prevent rollback to the pre-privacy unscoped corrector and require a reviewed forward rollback migration
• block rollout of 20260717171000 until a forward migration purges unsafe title-word rows and a zero-row invariant passes
• add safe registry-cleanup rollback guidance and record both later migrations in the operator backlog
• mark the 2026-07-17 WIP remediation report as a superseded historical record

Verification

• npm run verify:pr-local
• npm run verify:ui when UI, routing, styling, browser behavior, reduced-motion, or forced-colors behavior changed
• npm run verify:release before release or handoff confidence claims
• npm run eval:retrieval:quality (must stay 36/36) when retrieval, ranking, selection, chunking, or scoring behavior changed
• npm run eval:rag -- --limit 15 + npm run eval:quality -- --rag-only when answer generation, the synthesis prompt, or answer post-processing changed
• npm run check:production-readiness when clinical workflow, privacy, environment, Supabase, source governance, or deployment behavior changed
• npm run check:deployment-readiness when deployment startup, hosting, or rollout behavior changed

Passed locally/offline:

• npm run docs:check-links — 915 repository path references resolve after syncing current main
• npm run docs:check-scripts — 299 documented npm references resolve after syncing current main
• Prettier --check on all four changed Markdown files
• static migration-order assertion: 20260714180000_patch_rag_and_corrector_scalability.sql → 20260717120000_corrector_public_titles_only.sql → 20260717170000_registry_projection_cleanup.sql → 20260717171000_public_title_corrector.sql
• static rollout-blocker assertion: the runbook requires a reviewed forward cleanup, owner_id/indexed-status invariant, disabled corrector traffic during the migration window, and no ad hoc production delete
• git diff --check

Verification not run: verify:pr-local, release, deployment, UI, live retrieval, and production-readiness gates are not proportionate to a docs-only change and could include broader/provider-backed work. Exact-head hosted required checks remain the merge gate.

Risk and rollout

• Risk: Low repository risk; documentation-only. The affected text governs a medium-risk production migration and now records a P1 rollout blocker: the historical 20260714180000 backfill can leave private/non-indexed title words that 20260717171000 does not purge.
• Rollback: Revert this PR if the documentation change itself must be withdrawn. Do not use the historical unscoped corrector definition as a database rollback, and do not remove the rollout blocker until a cleanup migration is merged and verified.
• Provider or production effects: Git branch publication and PR creation only, explicitly authorized. No Supabase/OpenAI call, database migration, deployment, credential use, or production mutation.

Clinical Governance Preflight

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

Notes

• No source, test, schema, migration, configuration, or runtime file changed.
• This PR documents operator actions only; merging it does not authorize a live migration apply.
• The actual forward cleanup migration remains a separately reviewed schema change and is intentionally not implemented in this docs-only PR.

Summary by CodeRabbit

• Documentation
  • Updated deployment guidance with required migration ordering, safety checks, rollout blockers, verification steps, and confirmation points.
  • Added safe rollback procedures and clarified restrictions around private-title handling.
  • Updated backlog status and launch-gating requirements to reflect pending cleanup work.
  • Marked the historical remediation report as superseded and redirected readers to current operational guidance.

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

📝 Walkthrough

Walkthrough

Operational documentation now specifies safer public-title corrector rollout gates, linked migration ordering, rollback procedures, backlog status, and redirects from superseded remediation guidance.

Changes

Migration rollout and operations

Layer / File(s)	Summary
Public-title corrector rollout runbook docs/deploy-corrector-public-titles.md	The runbook adds ordered migration checks, stale-row cleanup and zero-row invariants, approval-gated deployment steps, and updated rollback and drift-validation guidance.
Registry remediation and rollback procedure docs/operator-apply-performance-latency-remediation.md	The remediation guide requires linked migration ordering and documents rollback steps for registry-delete failures, projection reconciliation, and post-incident validation.
Operator reference updates docs/operator-backlog.md, docs/rag-scalability-wip-remediation-2026-07-17.md	The backlog marks the rollout pending with updated blockers, while the historical remediation report is marked superseded and redirects operators to current guidance.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• BigSimmo/Database#709: Updates the same public-title corrector deployment documentation.
• BigSimmo/Database#701: Changes the public-only corrector vocabulary and drift manifest referenced by these rollout gates.
• BigSimmo/Database#806: Adds related migrations and hardening for document_title_words and the corrector function.

Suggested reviewers: claude

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title is concise and accurately reflects the docs-only migration rollout and rollback guidance changes.
Description check	✅ Passed	The description matches the template and includes summary, verification status, risk/rollback, governance, and notes.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-migration-runbook-safety-20260718

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 66bdd28fea

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".