perf(scripts): enforce deterministic local verification

[FelixTJDietrich]

Description

Small changes should get useful feedback in seconds, without making the pre-push gate less trustworthy. This PR establishes three commands with deliberately different promises:

When	Command	What a pass means
While editing	bun run check:affected	Static and policy checks for every selected area passed
Before pushing	bun run check	The complete local quality gate passed
Before review	bun run verify	Every mandatory CI check that can run locally without services, images, or credentials passed

Why this is worth merging

The previous affected commands took up to four minutes because they embedded broad test suites. That made the “fast” path too slow for an edit–check loop, while there was no single command for the broader credential-free CI inventory.

This change makes the boundaries explicit and measured:

• affected webapp, server, agent, and docs checks now complete in about 1–12 seconds on the documented machine;
• check remains the read-only pre-push contract and still includes agent tests;
• verify adds webapp unit and Storybook browser tests, server unit/architecture tests, webapp and Storybook production builds, generated-route validation, and the docs build;
• shared configuration, generated contracts, repository tooling, hooks, and unknown paths fail closed to check rather than guessing;
• scoped output never claims the complete gate passed.

The selector considers committed, staged, unstaged, untracked, deleted, and renamed paths. A real temporary Git repository test covers that discovery path, including the Git environment exported by hooks. Table-driven tests cover ordinary workspaces, shared/configuration inputs, generated artifacts, and cross-workspace changes.

Deliberate CI-only boundaries

verify excludes checks that need live services, end-to-end environments, image builds, mutation infrastructure, release security, or hosted credentials. Those remain clearly documented CI responsibilities. The webapp build verifier restores the generated route file before exiting, so all three normal verification commands are read-only.

The contributor guide records the measured warm budgets, peak practical memory, and planted-failure detection times. AGENTS.md, CONTRIBUTING.md, package scripts, and hook messages now describe the same contribution path.

Fixes #1549

How to test

Completed locally on the final tree:

• bun run format
• bun run check
• bun run verify — passed in 8 min 27 s before the final Storybook-build parity leg was added
• bun run verify:storybook-build
• bun test scripts/check-affected.test.ts — 9 tests passed
• affected commands run twice for first/warm timings
• invalid source planted in each scoped tree; every selected command failed within 0.8–3.0 s
• the selector test run with hook-style GIT_DIR and GIT_WORK_TREE variables to verify repository isolation

Smoke test:

1. Run bun run check:affected on this branch. Because it changes root tooling, it must expand to bun run check and report that the complete local quality gate passed.
2. Run HEPHAESTUS_SKIP_PRE_PUSH=1 sh .husky/pre-push. It must report the bypass and corrective command without claiming success.
3. Run bun run check:affected --unknown. It must reject the unsupported argument.

Checklist

• No changeset is required: this changes contributor tooling and documentation, not shipped application, server, or Docker behavior.
• No operator action or migration is required.
• The branch is rebased onto current main.

[coderabbitai]

Warning

Review limit reached

Next included review available in 3 minutes.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 989ddc9c-2aac-4975-b224-ed65db1047fa

📥 Commits

Reviewing files that changed from the base of the PR and between 73cca0d and ddfb102.

📒 Files selected for processing (11)

• .github/PULL_REQUEST_TEMPLATE.md
• .husky/pre-push
• AGENTS.md
• CONTRIBUTING.md
• docs/contributor/local-development.mdx
• docs/contributor/local-verification.mdx
• docs/sidebars.contributor.ts
• package.json
• scripts/check-affected.test.ts
• scripts/check-affected.ts
• scripts/verify-webapp-build.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[github-actions]

📚 Documentation Preview

Preview has been removed (PR closed)

[github-actions]

🧩 Storybook Preview

Preview has been removed (PR closed)