fix(gates): catch lint and type errors before push, not in CI

[BigSimmo]

Summary

• Add a pre-push static gate (lint + typecheck). Two open PRs burned full CI cycles this week on defects one local command would have caught: Ship soft Category filter (replace phone select blue highlight) #1606 on a react-hooks/set-state-in-effect lint error, Phone Choose mode sheet: review + two large YES mockups #1618 on TS2339 for mode.devOnly (a union member that lacks the property — src/lib/app-modes.ts:400 already exports the correct "devOnly" in mode guard). Neither lint nor typecheck was in the pre-push path. guard-push.mjs gains a fourth guard covering both.
• Fix the typecheck gate it depends on (ledger #210). Typecheck could not simply be added, because it was already unusable. tsconfig.json's include carries .next/types/**/*.ts and .next/dev/types/**/*.ts — gitignored build artifacts — so deleting a page leaves the stale generated validator importing a removed module. New tsconfig.typecheck.json + npm run typecheck:source answer "is the source sound?" deterministically.
• Correct a doc claim that made Add three Clinical KB guide wireframe mockups #1580 surprising. "Mockups are exempt" was being read as blanket. They are exempt from the wiring and reachability gates and nothing else — still typechecked, and their client chunks still count toward check:bundle-budget.
• Record the unmade decision behind Add three Clinical KB guide wireframe mockups #1580 as #237. The budget totals every built chunk, which contradicts ledger #013's "not an initial production bundle" position. Recorded rather than papered over; no metric was changed here.

Root cause was reproduced, not inferred. A planted .next/dev/types/validator.ts referencing a removed mockup page yields error TS2307: Cannot find module '.../mockups/deleted-mockup-route/page.js' — base config exit 2, source-only config exit 0. Red locally and green in CI (fresh checkout, no .next) is how the gate got abandoned, which is how a real type error then reached CI.

Verified against real build artifacts, not just the synthetic fixture: after npm run build, .next/types/validator.ts exists and is absent from the source config's file list. The only .next file that still enters is routes.d.ts, via next-env.d.ts; it contains zero imports (a pure string-literal route union), so it cannot produce the missing-module error. Source-only typecheck also passes with no .next present at all, so a fresh checkout is unaffected.

The new guard is scoped to the lint roots and to pushes touching TypeScript, skips loudly when node_modules is absent rather than pushing people to GUARD_PUSH_DISABLE=1 (which would lose the format and drift guards too), and is overridable with SKIP_STATIC_GUARD=1. Route-signature validation is not lost — next build still covers it in CI.

Verification

• npm run verify:pr-local — could not complete, and not because of this diff: it fails closed at its check:installed-lock-parity precondition with playwright: installed 1.62.0 does not match locked 1.62.1, a pre-existing container drift. This diff changes no dependency. The gates it selects for this scope were run directly instead:
  • npm run lint — exit 0
  • npm run typecheck — exit 0 (base config, as CI runs it)
  • npm run test — 489 files passed, 5097 passed / 4 skipped
  • npm run build — compiled successfully; Client bundle secret surface check passed.
  • npm run check:bundle-budget — 1406.9 KiB gzip; baseline 1406.4 KiB; within tolerance
  • npx prettier --check . — All matched files use Prettier code style! (repo-wide, not per-file)
  • npm run check:outstanding-issues — 235 rows (104 open, 131 archived), unique ids, next-id=238
  • npm run docs:check-scripts — 428 npm-run reference(s) resolve; docs:check-inventory current after docs:update
• Guard-specific proof: node scripts/guard-push.mjs --self-test passes; tests/guard-push.test.ts15 passed; the guard was driven directly against reconstructions of both defects and blocked each with CI-identical messages (TS2339 ... Property 'devOnly' does not exist, error Calling setState synchronously within an effect).
• Timing, so the hook is not something people disable: source typecheck is 54.7s cold / 6.9s warm incremental; lint is scoped to changed files.
• npm run verify:ui — not run: no UI, routing, styling, or browser behaviour changed.
• npm run verify:release — not run: no release or handoff confidence claimed.

Risk and rollout

• Risk: the guard blocks a legitimate push. Bounded three ways — it only runs when lint-root or TypeScript files change, it fails open with a loud note when node_modules is absent, and SKIP_STATIC_GUARD=1 overrides it. The residual gap is deliberate: it reads the working tree rather than the pushed blobs (unlike the format guard, which materialises the commit because formatting drift between tree and commit is silent and common). A lint or type error present in the commit but not the tree implies editing after committing, which the guard surfaces with a dirty-tree note. Reproducing a node_modules-linked worktree for tsc costs more than that gap.
• Rollback: revert. The guard is additive; tsconfig.typecheck.json and typecheck:source are new and unreferenced by CI, and no existing gate's behaviour changed.
• Provider or production effects: None. No dependency, schema, runtime, or deployment change; every command run was local and offline.

Notes

#210 is closed with its residual stated rather than silently: plain npm run typecheck still reads .next and so still goes red against a stale build. That is correct behaviour for a stale artifact, and CI's Build job verifies the generated types for real — clear .next if you want the full check locally.

#237 is recorded but deliberately not decided here. The budget's totalGzipBytes comes from measureChunkPaths(walkJsFiles(CHUNKS_DIR)) — every built chunk — while the manifest-scoped initialDashboardChunks set is used only for the fixture-payload assertion. Choosing between "exclude mockup chunks so the number means production weight" and "keep counting them as a deliberate hygiene ceiling" changes what the gate is for, which is a call for the repo owner. Measured context: main sits at 1406.4 KiB against a 10% tolerance, and 59 of ~105 app routes are mockups.

No Clinical Governance Preflight section: this diff touches build tooling and documentation only — no ingestion, answer generation, search/ranking, source rendering, document access, privacy, or production env. No RAG impact: line for the same reason — no file under any RAG-ranking surface is touched.

---

Generated by Claude Code

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

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:5 minutes

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: 6f625643-50d1-47ab-a798-7e9f711193df

📥 Commits

Reviewing files that changed from the base of the PR and between ce3bd2d and 6af496b.

📒 Files selected for processing (16)

• .githooks/pre-push
• AGENTS.md
• CLAUDE.md
• docs/branch-review-ledger.md
• docs/codebase-index.md
• docs/outstanding-issues.md
• docs/process-hardening.md
• docs/scripts-index.md
• package.json
• scripts/guard-push.mjs
• scripts/run-heavy.mjs
• scripts/test-cache-path.mjs
• tests/audit-remediation-tooling.test.ts
• tests/guard-push.test.ts
• tests/test-runner-safety.test.ts
• tsconfig.typecheck.json

---

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

[cursor]

Babysit update (head after Bugbot)

Addressed Devin review threads (all three resolved) and a Bugbot finding on this PR:

1. Shared lease for typecheck:source:internal + distinct per-worktree --tsBuildInfoFile; dropped pinned in-repo buildinfo from tsconfig.typecheck.json.
2. staticGuard goes through run-heavy (lint:changed:internal / lint:internal / typecheck:source:internal) with private eslint cache, short fail-open wait, eslint policy escalation, and HEAD≠tip fail-closed.
3. CLAUDE.md points at #252 (post-issues: queue fastest-wins plan and capture three follow-ups #1624 renumber); hook/docs describe the fourth guard / SKIP_STATIC_GUARD=1.
4. Bugbot fix:run-heavy fallback spawn (no npm_execpath, which is the pre-push path) now forwards effectiveForwarded so --tsBuildInfoFile is not dropped; dirty-tree success also warns.

Ledger rows for this PR’s open follow-ups are #252–#255 (next-id=256). PR #1624 is already merged.

Local proof: guard-push --self-test passed; Vitest on guard-push / audit-remediation / test-runner-safety 57 passed; outstanding-issues guard green.