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.
hatch run formathatch run type-checkhatch run linthatch run yaml-linthatch run check-bundle-importshatch run verify-modules-signature --payload-from-filesystem --enforce-version-bump(add--require-signaturewhen checking as formain; matches CI andscripts/pre-commit-verify-modules-signature.sh)hatch run contract-testhatch run smart-testhatch run testhatch run specfact code review run --enforcement changed --bug-hunt --json --out .specfact/code-review.json(always pass--bug-hunton manual runs so CrossHair uses bug-hunt timeouts; use--enforcement fullwhen 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.jsonand unresolved changed-line findings block merge unless an explicit exception is documented)
Pre-commit order
- Module signature verification via
scripts/pre-commit-verify-modules-signature.sh(.pre-commit-config.yaml;fail_fast: trueso a failing earlier hook never runs later stages). The hook adds--require-signatureon branchmain, or whenGITHUB_BASE_REFismain(PR target in Actions); otherwise it runs the baseline--payload-from-filesystem --enforce-version-bumpverifier (same formal policy as PRs targetingdev). - 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-yamlwhen staged*.yaml/*.yml,block1-bundle(always),block1-lintwhen staged*.py/*.pyi. - 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 underpackages/,registry/,scripts/,tools/,tests/, andopenspec/changes/(excludingTDD_EVIDENCE.md), thencontract-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.jsonas 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.mdor the PR description when quality gates are part of the change.
Outcome and scope review
- Apply
15-intent-and-scope.mdduring 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.