Guard · Pre-PR preflight

Pre-PR preflight

Catch the failure before the PR opens. A subset of CI, run on your laptop: node --check and eslint on the changed .mjs files, the tests the diff touches, every brain-drift gate, the twin gate, the parity checks and the PR-record check. The guarantee runs one way: a red preflight means the PR fails CI; a green one does not mean the PR passes.

Start here if you want to know what is exposed in a repo and whether it will ship broken: Security. This page covers the pre-push gauntlet that runs from the same repo.

See it in motion

Where to find it

  • Skill: .claude/skills/preview-check/SKILL.md
  • Invoke: /preview-check in Claude Code
  • Script: node scripts/preflight.mjs (the pre-push gate, npm run preflight)
  • Drift gates: bash scripts/brain-drift/run-all.sh

What it does for you

Runs the cheap gates CI would.node --check on every .mjs in the diff plus server.mjs; eslint on the changed .mjs; node --test on every modified test file; the website typecheck when the diff touches website/; every brain-drift gate (api-vs-routes, config-vs-env, tests-vs-files, surface-drift and the rest that run-all.sh names); the parity checks; the PR-record check; the twin gate, which fails if a generated .claude/brain/*.html is tracked or a bespoke twin did not move with its .md; a conflict-marker scan; inline-script syntax in every public/*.html. Not run here, because each needs a clean install or a boot: website-build, website-lint, cold-start, demo-replay, dependency-audit, and the website test suite unless REPOOPS_PREFLIGHT_WEBSITE_TEST=1 is set.
The skill adds the checks the script cannot run.The server boot smoke test, the dashboard render, environment and config sanity (.env.example and config.md in step, secrets through ${env:VAR}), the past-failure replays from errors.md, the PR-body sections, and branch sanity. Any live check that writes to a running dashboard boots an isolated instance with npm run start:verify, never the operator's real one.
Grows a new check every time a new failure lands.The rule in the skill: every new entry in errors.md produces either a new check there or a new brain-drift, twin-drift or CI gate. New CI failure, fix the bug, add the check, so the next agent catches it locally first.

Configure

The skill is markdown: open it and edit. Add a check: write a line, list the script that runs it, and (if the script doesn't exist yet) write it under scripts/brain-drift/ following the existing pattern. Most drift gates are Node scripts now; the older ones are bash. run-all.sh runs each gate in order under a per-gate timeout and stops at the first failure, naming the gate that failed.

Use it well

Make preview-check the default last step before git push. When it fails, fix the root cause; don't suppress the check. When a CI failure lands that preview-check didn't catch, add the missing check to the skill in the same fix PR. One preflight runs at a time across every worktree of the repo; a second one waits for the first rather than proceeding unlocked.

Read more

Last updated