docs: technical debt audit, remediation PRD, and WI-01 schema-channel decision (2026-10-28) by PetrefiedThunder · Pull Request #3699 · regengine/RegEngine

PetrefiedThunder · 2026-10-28T10:56:46Z

Summary

Adds docs/audits/TECH_DEBT_AUDIT_2026-10-28.md: sixteen debt items scored on impact, risk and effort (priority = (impact + risk) × (6 − effort)), each with evidence measured against the tree at af5beee. Five counts were corrected in a self-review pass (9f6efb3). Item 1 now carries a status.
Adds docs/plans/TECH_DEBT_REMEDIATION_PRD_2026-10-28.md: the audit turned into sixteen work items for an AI implementer, with requirements, acceptance criteria, verification commands, out-of-scope lines, rollback, the owner's standing rules, repo mechanics, sequencing, a definition of done, the decisions only the owner can make, and baselines.
Delivers the documentation half of WI-01 (the top item):
- docs/decisions/2026-10-30-schema-change-channel.md: Alembic is the only schema authority; supabase/migrations/ is frozen history; sql/prod-apply/ holds rendered revisions only; hand-applied changes require a paired idempotent revision. Appendix A inventories all 45 Supabase-CLI files and 12 prod-apply files against their Alembic counterpart (10 of 45 have one). Appendix B lists eight decisions for Christopher.
- sql/prod-apply/PRECHECK_alembic_version_reconcile.sql: read-only (BEGIN READ ONLY … ROLLBACK), one catalog signature per revision after v079 (71 rows) plus a summary of the chain position the catalog supports. Verified end to end on a scratch PostgreSQL 16 cluster.
- docs/runbooks/ALEMBIC_VERSION_RECONCILE.md: how to read the precheck, the one outcome in which the version row may be edited, and why the normal path is the existing DATABASE_ROLE_CUTOVER.md plus v079-to-head procedure, now targeting v137.
- docs/MIGRATION_CONSOLIDATION.md reduced to a pointer (it described March 2026).
- Still open for a code PR: WI-01 requirement 5, the scripts/check_schema_channels.py CI guard and tests.

Type of Change

Documentation

Test Plan

N/A (docs, config, etc.)
scripts/check_docs_links.py passes on the audit, the ADR, the runbook and the consolidation pointer. The PRD intentionally names files it instructs an agent to create.
The precheck SQL was run with psql -X -v ON_ERROR_STOP=1 against a scratch PostgreSQL 16 cluster seeded with a v079 version row and a few objects: exit 0, no errors, 71 signature rows, summary reports supported_through_revision = c1d2e3f4a5b6 and lists the hand-applied revisions beyond the gap. A grep confirms the file contains no INSERT/UPDATE/DELETE/DDL statements.

Checklist

My code follows the existing patterns in the codebase
I have not introduced hardcoded secrets or credentials
I have updated relevant documentation (if applicable)
My changes generate no new warnings or lint errors

Related Issues

None. visual-report (non-required) is red for a pre-existing reason fixed by #3666 (see comments). Jev second opinion on the reconcile decision is recorded in the ADR.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

Sixteen items scored on impact, risk and effort, with evidence measured against the tree, a Jev second opinion on the top three risks, and a four-phase remediation plan sized for one engineer beside feature work. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

vercel · 2026-10-28T10:56:52Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
regengine	Ready	Preview	Oct 28, 2026 11:37am UTC

coderabbitai · 2026-10-28T10:56:55Z

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

github-actions · 2026-10-28T11:00:59Z

PR Blocker Checklist

Head SHA: c282cdbb65afe48b13463c2c9a53bdbc3b9212d9

Status: Ready

All review threads resolved
No reviews requesting changes
No blocked review engines

Two (not three) of the preceding five commits are security fixes; 25 (not 24) modules exceed 1,000 lines; the codebase map lists 14 (not 7) experimental routers; every frontend `any` is in a test file; the admin bare import is a compat shim that raises rather than loading the wrong module. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

PetrefiedThunder · 2026-10-28T11:28:27Z

visual-report (non-required) is red on this head for a reason unrelated to this PR.

This PR changes one Markdown file under docs/audits/. The job's log on 9f6efb3 shows 164 of 364 visual tests failing with Screenshot name "…" must have a '.png' or '.webp' extension (Playwright 1.64 rejects extensionless toHaveScreenshot() names) plus two 60 s click timeouts on the preview-forms spec. The same job fails the same way on other open PRs, and the workflow is continue-on-error and report-only by design.

The fix already exists in #3666 (adds .png to every screenshot name and skips Vercel-protected previews). I am not porting it here: it touches six frontend test files that a docs-only PR has no reason to carry, and the check does not gate merge. Once #3666 lands, this job goes green on its own.

Generated by Claude Code

…plementer Turns the sixteen audit findings into sixteen work items with evidence, requirements, acceptance criteria, verification commands, out-of-scope lines and rollback. Adds the owner's standing rules (never delete, one item per PR, no production changes), the repo mechanics an agent hits (engine branch prefix, cross-engine review marker, gitignored audit names, docs link and workflow inventory gates), phase sequencing, a definition of done, the decisions only Christopher can make, and baseline measurements to compare against. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

PetrefiedThunder · 2026-10-28T12:16:35Z

Passwordless Auth E2E (Chromium) is red on f87ed2a for a reason outside this PR.

One test failed, on the attempt and on Playwright's retry: tests/e2e/authenticated-core-journeys.spec.ts:400 ("invite collaborator → email sent → accept invite → appears in member list"). The assertions passed; the finally cleanup threw:

Error: database is locked
  at cleanupInviteFixture (frontend/tests/e2e/authenticated-core-journeys.spec.ts:119:93)

cleanupInviteFixture opens the admin SQLite file with new DatabaseSync(adminSqlitePath()) (no busy timeout) and issues DELETEs while the admin backend still holds a write lock from the accept-invite request. The 22 other tests passed. The same code passed on the previous head 9f6efb3; the only change since is a Markdown file under docs/plans/.

No fix is open for this. Proposed patch (not pushed here, to keep a docs PR docs-only):

// frontend/tests/e2e/authenticated-core-journeys.spec.ts, both DatabaseSync call sites
const database = new DatabaseSync(adminSqlitePath());
database.exec('PRAGMA busy_timeout = 5000');

Re-running the failed job once to confirm.

Generated by Claude Code

PetrefiedThunder · 2026-10-28T23:47:31Z

Re-run result: Passwordless Auth E2E (Chromium) passed on the same head f87ed2a (job 122874475838), which confirms the database is locked failure above was a race in the test's SQLite cleanup, not a product or doc change. Frontend CI Status Gate, PR Gate: Frontend and CI Status Gate are now green. The only red check is visual-report (non-required), covered by #3666. Remaining gate: a non-author engine's REVIEW: PASS <engine> f87ed2adffcd698a09dbd7f78a92e966fbc5ec63.

Generated by Claude Code

…precheck and runbook Production (the Supabase project) was last observed at Alembic v079 with 71 revisions pending behind a role cutover that has been prepared but not executed since 2026-09-05, while 45 Supabase-CLI migrations and 12 prod-apply scripts kept reaching it by hand. This records the decision that the Alembic chain is the only authority, inventories every file in the two other channels against its Alembic counterpart (10 of 45 have one; 35 do not, with eight decisions listed for Christopher), and adds: - sql/prod-apply/PRECHECK_alembic_version_reconcile.sql: read-only; one catalog signature per revision after v079 (71 rows) and a summary of the chain position the catalog supports. Verified on a scratch PostgreSQL 16. - docs/runbooks/ALEMBIC_VERSION_RECONCILE.md: how to read the precheck and the one case in which the version row may be edited; otherwise the existing DATABASE_ROLE_CUTOVER and v079-to-head procedure applies. - docs/MIGRATION_CONSOLIDATION.md reduced to a pointer; it described March. - PRD WI-01 status and audit item 1 status updated; CI guard still open. Jev second opinion recorded in the ADR (run the chain 0.89; stamping to head unsafe p=0.95). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

…d files Completes WI-01 requirement 5 from the remediation PRD and the header rule in docs/decisions/2026-10-30-schema-change-channel.md. - scripts/check_schema_channels.py: every .sql under supabase/migrations/ and sql/prod-apply/ must start with `-- alembic-revision: <id>` and `-- rendered-from: alembic/versions/<file>.py (upgrade|downgrade|precheck)` naming an existing revision whose file matches. The 38 pre-decision files without a counterpart are grandfathered by name; the list only shrinks, and a stale entry fails the run. The reconcile precheck is exempt because it checks every revision rather than rendering one. - tests/scripts/test_check_schema_channels.py: 17 tests, including one that scans the real tree and one that keeps the grandfather list honest. - backend-ci.yml: run the guard in the "Alembic revision ID guard" job and add the two channel directories to the push and pull_request paths so a channel-only change still triggers it. - Add the two header lines to the 19 files that render a known revision (v092, v128 x2, v131, v134, v135, v136, v137). Comment lines only; no statement changes. - ADR, runbook, PRD WI-01 and audit item 1 updated to "delivered"; the open items are the Appendix B decisions. Verified: guard clean on the tree (58 files scanned); 17 tests pass; scripts/check_workflow_inventory.py, check_alembic_revisions.py and check_orphan_migrations.py still pass; docs link check passes. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

…ard tests Two test lines exceeded 120 characters; ruff format applied to both new files. No behaviour change; 17 tests still pass. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

graph_update was declared in PURGEABLE_TASK_TYPES and given a 120 s visibility timeout, but nothing enqueued it and TASK_HANDLERS never had a handler. Remove the type and the timeout, say so in the worker docstring and ASYNC_PROCESSES.md, and drop it from the two tests that listed it as a mapped type. No database object names it. 47 queue tests still pass. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

…st-dom majors (WI-13) copy-gate pinned Node 20 while .nvmrc says 22 and package.json engines says 22 or 24. Point it at .nvmrc. The one remaining literal pin is the Node 24 job in frontend-ci.yml, kept because authenticated-core-journeys needs the built-in node:sqlite module and its comment says so. With no workflow on Node 20, the jsdom 30 and jest-dom 7 Dependabot ignores lose their reason; removed so CI decides those upgrades. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

scripts/README.md gives every top-level file (99) and subdirectory (11) a row: status, purpose, and what invokes it. Status values are used, data, manual, one-time, retire-with-WI-12 and archive candidate. The 14 archive candidates stay in place; moving them to scripts/_archive/ is a decision for the owner by name and becomes a one-commit follow-up. scripts/check_scripts_registered.py fails when a top-level entry has no row or a row names a missing entry, so the directory cannot silently collect orphans again. Ten tests under tests/scripts/. Wired into backend-ci lint-repo-roots, which already triggers on scripts/**. Audit §1 and the PRD now record items 8, 13 and 15 as delivered. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GyhDYGPjbfDzVjRUqkvz4B

vercel Bot deployed to Preview October 28, 2026 10:58

View deployment

github-actions Bot added the docs label Oct 28, 2026

vercel Bot deployed to Preview October 28, 2026 11:06

View deployment

vercel Bot deployed to Preview October 28, 2026 11:37

View deployment

PetrefiedThunder changed the title ~~docs(audits): technical debt audit 2026-10-28~~ docs: technical debt audit and remediation PRD (2026-10-28) Oct 28, 2026

PetrefiedThunder changed the title ~~docs: technical debt audit and remediation PRD (2026-10-28)~~ docs: technical debt audit, remediation PRD, and WI-01 schema-channel decision (2026-10-28) Oct 30, 2026

PetrefiedThunder and others added 5 commits October 30, 2026 06:50

github-actions Bot added backend ci agent:infra Issues found by Bot-Infra agent database labels Oct 30, 2026

Navigation Menu

Repository navigation

docs: technical debt audit, remediation PRD, and WI-01 schema-channel decision (2026-10-28) - #3699

docs: technical debt audit, remediation PRD, and WI-01 schema-channel decision (2026-10-28)#3699
PetrefiedThunder wants to merge 9 commits into
mainfrom
claude/fervent-clarke-0aw2am

PetrefiedThunder commented Oct 28, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Oct 28, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Oct 28, 2026

Draft PR not reviewed

Uh oh!

github-actions Bot commented Oct 28, 2026 •

edited

Loading

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

PetrefiedThunder commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

Test Plan

Checklist

Related Issues

Uh oh!

vercel Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Oct 28, 2026

Draft PR not reviewed

Uh oh!

github-actions Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Blocker Checklist

Status: Ready

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

PetrefiedThunder commented Oct 28, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

PetrefiedThunder commented Oct 28, 2026 •

edited

Loading

vercel Bot commented Oct 28, 2026 •

edited

Loading

github-actions Bot commented Oct 28, 2026 •

edited

Loading