Agent quality gates and review

For merge-quality authority, run specfact code review run --scope range --base-ref <full-base-ref> --head-ref <full-head-ref> --pr-context-file <event-derived-absolute-path> --enforcement full. A local range run without matching claimed context is range_preview; one with matching claimed context is range_candidate. Neither is pr_range until a protected consumer independently verifies and promotes the evidence.

Quality gate order

Before running quality gates in a fresh worktree, bootstrap the Hatch environment serially. Run one Hatch command first, wait for it to finish, and only then run additional gates. Parallel hatch run ... commands are allowed only after the worktree environment is known healthy; otherwise concurrent environment creation can corrupt the local .venv and leave partial pip._internal imports.

  1. hatch run format
  2. hatch run type-check
  3. hatch run lint
  4. hatch run yaml-lint
  5. hatch run check-bundle-imports
  6. hatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump (add --require-signature when checking as for main; matches CI and scripts/pre-commit-verify-modules-signature.sh)
  7. hatch run contract-test
  8. hatch run smart-test
  9. hatch run test
  10. hatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json (always pass --bug-hunt on manual runs so CrossHair uses bug-hunt timeouts; use --enforcement full when legacy blockers in reviewed files must fail the run; full-repo scope when required: add --scope full; machine-readable evidence lives at .specfact/code-review.json and unresolved changed-line findings block merge unless an explicit exception is documented)

Pre-commit order

  1. Module signature verification via scripts/pre-commit-verify-modules-signature.sh (.pre-commit-config.yaml; fail_fast: true so a failing earlier hook never runs later stages). The hook adds --require-signature on branch main, or when GITHUB_BASE_REF is main (PR target in Actions); otherwise it runs the baseline --payload-from-filesystem --enforce-version-bump verifier (same formal policy as PRs targeting dev).
  2. Block 1 — four separate hooks (each flushes pre-commit output when it exits, so you see progress between stages): pre-commit-quality-checks.sh block1-format (always), block1-yaml when staged *.yaml / *.yml, block1-bundle (always), block1-lint when staged *.py / *.pyi.
  3. Block 2 — pre-commit-quality-checks.sh block2 (skipped for “safe-only” staged paths): hatch run python scripts/pre_commit_code_review.py … on staged paths under packages/, registry/, scripts/, tools/, tests/, and openspec/changes/ (excluding TDD_EVIDENCE.md), then contract-test-status / hatch run contract-test.

Run the full pipeline manually with ./scripts/pre-commit-quality-checks.sh or … all.

An explicitly approved local ARM64 Darwin feature-worktree exception may set SPECFACT_CODE_REVIEW_DEFER_TO_CI=github-linux to defer only the capsule review to the blocking exact-head GitHub Linux customer job. Every other hook component still executes. This reports DEFERRED, never PASS; it is rejected in CI, on other platforms or protected checkouts. Record maintainer approval in change evidence and require hosted review completion before merge.

SpecFact code review JSON

  • Treat .specfact/code-review.json as mandatory evidence before an OpenSpec change is complete.
  • Re-run the review when the report is missing or stale.
  • Resolve every finding at any severity unless a rare, explicit exception is documented.
  • Record the review command and timestamps in TDD_EVIDENCE.md or the PR description when quality gates are part of the change.

Outcome and scope review

  • Apply 15-intent-and-scope.md during review: verify the agreed user workflow, trust assumptions, non-goals, and acceptance, including the justification for added infrastructure.
  • Triage recommendations against the confirmed use case; escalate material scope or threat-model changes before adopting them. Preserve applicable security and quality gates.
  • Report implementation, end-to-end execution, artifact availability, and publication separately. A green check or isolated fixture cannot establish the complete user outcome.
  • Stop repeating an unchanged failed gate after two attempts without new evidence; diagnose and report the blocker before the next bounded step. Routine verification scales to touched scope while all applicable mandatory checks remain required.

Clean-code review gate

The repository enforces the clean-code charter through specfact code review run. When agents or developers invoke the review manually (outside the pre-commit helper), include --enforcement changed --bug-hunt so changed-line regressions block and CrossHair gets the longer bug-hunt budgets documented in the code-review bundle. Use --enforcement full only when the task explicitly requires every legacy blocker in reviewed files to fail the run. Zero regressions in naming, kiss, yagni, dry, and solid are required before merge.

Module signature gate

Any change that affects signed module assets or manifests must pass the signature verification command above. If verification fails because bundle contents changed, re-sign the affected manifests and bump the module version before re-running verification.