.pre-commit-hooks.yaml

# Canonical pre-commit hook manifest. pre-commit reads this file from the
# repo root when a downstream project uses
#   repos:
#     - repo: https://github.com/ThreeMoonsLab/agents-shipgate
#       rev: v0.12.0
#       hooks:
#         - id: <hook id below>
#
# Scope: the `files:` regex below covers the path leg of every trigger in
# `docs/triggers.json` that can be decided from a path alone — manifest,
# MCP/OpenAPI/Swagger exports, static tool inventories, n8n and Conductor
# workflow JSON, coding-agent host configuration/instructions, plugin package
# files, prompts/policies, AND GitHub workflow files. That claim is pinned
# exhaustively by `test_hook_regex_fixtures_cover_every_path_based_trigger`:
# a catalog rule with a `glob` leg must appear in the test's fixture table or
# in its documented exclusion set, so a new rule cannot land here uncovered.
# Matching is case-insensitive and, where the catalog glob is recursive, so is
# the clause: `prompts/`, `policies/`, `.codex-plugin/`, `.agents/plugins/`,
# `.n8n/`, nested `AGENTS.md`/`CLAUDE.md` and nested workflow directories all
# stage the same from a sub-workspace as from the repo root, and a `dir/**`
# glob also matches a tracked path named exactly `dir`.
# Diff-only triggers (`TRIGGER-FUNCTION-TOOL-DECORATOR`,
# `TRIGGER-GOOGLE-ADK-AGENT-TOOLS-CHANGED`) are not covered by the regex
# pre-gate — pre-commit's `files:` regex is purely path-based and cannot
# inspect diff contents. `TRIGGER-FRAMEWORK-VERSION-BUMP` needs a package
# token in the diff *in addition to* a changed dependency manifest, so a
# path-only regex cannot decide it either. Once the hook fires, the
# `verify` entry runs the full trigger evaluator (including diff_contains
# rules) itself; use the GitHub Action
# for coverage on commits whose paths don't match the regex at all, or
# `python -m agents_shipgate.triggers --git-diff HEAD` for a diff-aware
# local check without running verify.
- id: agents-shipgate
  name: Agents Shipgate merge-gate verify
  description: >
    Deterministic verifier for AI agent capability changes. Advisory mode —
    never blocks the commit. Runs the trigger-gated `verify` flow (base
    auto-detection, capability diff, merge verdict) rather than an
    unconditional scan. Switch to `agents-shipgate-strict` (or change the
    `entry:` to `--ci-mode strict`) to fail on critical findings locally.
  entry: agents-shipgate verify --config shipgate.yaml --ci-mode advisory --format text
  language: python
  pass_filenames: false
  always_run: false
  # pre-commit defaults to `types: [file]`, and a tracked symlink carries
  # the `symlink` tag instead of `file` — so the default filter drops it
  # before `files:` is ever evaluated. A governance surface can be a
  # symlink (a `prompts` or `policies` directory linked into a workspace,
  # a shared `AGENTS.md`), and the catalog routes those paths, so clear
  # the AND-filter and accept either tag.
  types: []
  types_or: [file, symlink]
  stages: [pre-commit, pre-push]
  files: |
    (?ix)^(
      (.*/)?shipgate\.yaml|
      .*tools.*\.json|
      .*mcp.*\.json|
      .*n8n.*\.json|
      (.*/)?\.n8n(/.*)?|
      (.*/)?conductor/.*\.json|
      (.*/)?ai/examples/.*\.json|
      (.*/)?\.codex/(config\.toml|hooks\.json|requirements\.toml)|
      (.*/)?\.claude/(settings(\.local)?\.json|commands(/.*)?)|
      (.*/)?\.cursor/(cli\.json|mcp\.json|rules(/.*)?)|
      (.*/)?\.vscode/mcp\.json|
      (.*/)?\.shipgate/agent-contract\.json|
      (.*/)?(AGENTS(\.override)?|CLAUDE)\.md|
      \.(agents|claude)/skills/.*|
      (.*/)?\.codex-plugin(/.*)?|
      (.*/)?\.agents/plugins(/.*)?|
      .*\.app\.json|
      (.*/)?SKILL\.md|
      .*openapi.*\.(yaml|yml|json)|
      .*swagger.*\.(yaml|yml|json)|
      \.agents-shipgate/.*\.json|
      (.*/)?prompts(/.*)?|
      (.*/)?policies(/.*)?|
      (.*/)?\.github/workflows/.*\.(yaml|yml)
    )$
  minimum_pre_commit_version: "3.0.0"

- id: agents-shipgate-strict
  name: Agents Shipgate merge-gate verify (strict)
  description: >
    Strict-mode verifier run; fails the hook on new critical findings.
    Pair with a baseline (`docs/baseline.md`) so accepted findings don't
    block every push.
  entry: agents-shipgate verify --config shipgate.yaml --ci-mode strict --fail-on critical --format text
  language: python
  pass_filenames: false
  always_run: false
  # pre-commit defaults to `types: [file]`, and a tracked symlink carries
  # the `symlink` tag instead of `file` — so the default filter drops it
  # before `files:` is ever evaluated. A governance surface can be a
  # symlink (a `prompts` or `policies` directory linked into a workspace,
  # a shared `AGENTS.md`), and the catalog routes those paths, so clear
  # the AND-filter and accept either tag.
  types: []
  types_or: [file, symlink]
  stages: [pre-push]
  files: |
    (?ix)^(
      (.*/)?shipgate\.yaml|
      .*tools.*\.json|
      .*mcp.*\.json|
      .*n8n.*\.json|
      (.*/)?\.n8n(/.*)?|
      (.*/)?conductor/.*\.json|
      (.*/)?ai/examples/.*\.json|
      (.*/)?\.codex/(config\.toml|hooks\.json|requirements\.toml)|
      (.*/)?\.claude/(settings(\.local)?\.json|commands(/.*)?)|
      (.*/)?\.cursor/(cli\.json|mcp\.json|rules(/.*)?)|
      (.*/)?\.vscode/mcp\.json|
      (.*/)?\.shipgate/agent-contract\.json|
      (.*/)?(AGENTS(\.override)?|CLAUDE)\.md|
      \.(agents|claude)/skills/.*|
      (.*/)?\.codex-plugin(/.*)?|
      (.*/)?\.agents/plugins(/.*)?|
      .*\.app\.json|
      (.*/)?SKILL\.md|
      .*openapi.*\.(yaml|yml|json)|
      .*swagger.*\.(yaml|yml|json)|
      \.agents-shipgate/.*\.json|
      (.*/)?prompts(/.*)?|
      (.*/)?policies(/.*)?|
      (.*/)?\.github/workflows/.*\.(yaml|yml)
    )$
  minimum_pre_commit_version: "3.0.0"

- id: agents-shipgate-validate
  name: Agents Shipgate manifest validate
  description: Validate `shipgate.yaml` without running checks.
  entry: agents-shipgate doctor --json
  language: python
  pass_filenames: false
  stages: [pre-commit]
  files: '^shipgate\.yaml$'
  minimum_pre_commit_version: "3.0.0"