Agent quality gates and review

Quality gate order

  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 --bug-hunt --json --out .specfact/code-review.json (always pass --bug-hunt on manual runs so CrossHair uses bug-hunt timeouts; full-repo scope when required: add --scope full; machine-readable evidence lives at .specfact/code-review.json and unresolved 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.

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.

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 --bug-hunt so the contract runner gives CrossHair the longer bug-hunt budgets documented in the code-review bundle. 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.