Skip to content

feat(hook): agent-validated commit gate (agent judge → pre-commit hook → CI) #674

Closed

Description

@ajianaz

Problem

The fleet standard says to run cora review before every commit, but nothing makes an agent actually do it, and the agent-as-reviewer flow (cora.review_prepare / cora.review_finalize) leaves no trace a hook or CI can check:

  • An agent can git commit without ever reviewing; the pre-commit hook is the only net, and it is per repo, opt-in, and --no-verify bypasses it.
  • The hook installed by cora hook install runs cora review --staged --format compact without --ci, so it cannot block on findings the way the standard requires (--ci --severity major), and it hides stderr.
  • The hook template has no # cora-managed-hook sentinel, so running cora hook install twice wraps the old hook into the new one.
  • Agent review and the hook do not know about each other: a diff the agent already judged is reviewed again by the hook (a second LLM call, or a hang on a stale binary).

Proposal

Three tiers, one verifiable record:

  1. Agent (tier 0): before committing, the agent judges the staged diff with the cora-review skill. cora.review_finalize (and cora review --staged itself) records a small validation marker in <git-dir>/cora/validations/ keyed by the sha256 of the exact diff, with the verdict (should_block, issue counts, who judged).
  2. Hook (tier 1, fallback): cora hook install writes a v2 hook that first runs cora hook verify; a validated, non-blocking diff passes immediately, otherwise it runs cora review --staged --ci --severity major (LLM when a key exists, deterministic checks otherwise) with the standard exit-code handling. Sentinel added; legacy hooks are recognised and upgraded in place.
  3. CI (tier 2): the Cora Review workflow on PRs to develop must fail when a required secret is empty (a green check must not hide a degraded review).
    Plus an enforcement point for agents: cora hook claude-guard, a Claude Code PreToolUse command that denies git commit (and --no-verify) unless the staged diff is validated. Stable exit codes for cora hook verify: 0 validated, 10 validated but blocking, 11 not validated (clap errors stay 2).

Done when

  • Marker write/check with tests (match, mismatch after re-stage, blocking, missing, pruning).
  • cora hook verify, cora hook claude-guard, v2 hook template + sentinel/legacy upgrade, docs, skill text, help text.
  • End-to-end: stage a change, run the agent flow, commit passes the guard; stage another change, commit is denied; --no-verify is denied.
  • The repo's own pre-commit script and CI secret guard follow in a second PR.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions