Add verifier guidance and Claude hooks

.agents/skills/agents-shipgate/SKILL.md

@@ -13,7 +13,7 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali
 
 ## Workflow
 
-1. For relevance decisions, bootstrap, scanning, CI setup, finding fixes, false-positive triage, strict-mode promotion, or version upgrades, read `references/recipes.md`.
+1. For relevance decisions, bootstrap, verifier runs, scanning, CI setup, finding fixes, false-positive triage, strict-mode promotion, or version upgrades, read `references/recipes.md`.
 2. For reading `report.json`, summarizing release decisions, or deciding what may be auto-applied, read `references/report-reading.md`.
 3. Set `AGENTS_SHIPGATE_AGENT_MODE=1` before running Shipgate commands so errors include structured `next_action` JSON.
 4. Default first-time CI to advisory mode. Do not enable release-blocking CI or save a baseline until a human has reviewed current findings.
@@ -24,6 +24,7 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali
 ## Fast Paths
 
 - First adoption: run `agents-shipgate detect --workspace . --json`, then follow `references/recipes.md`.
+- Local agent-related diff: run `agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`. Add `--base origin/main --head HEAD` only for committed PR/CI verification after making the base ref available.
 - Existing manifest: run `agents-shipgate scan -c shipgate.yaml --suggest-patches --format json`.
 - First GitHub CI: copy `assets/advisory-pr-comment.yml` to `.github/workflows/agents-shipgate.yml`.
 - Explain one finding: run `agents-shipgate explain-finding <fingerprint> --from agents-shipgate-reports/report.json --json`.
@@ -32,6 +33,8 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali
 ## Boundaries
 
 - Do not claim a finding is fixed without re-running `agents-shipgate scan` and reporting the new decision/counts.
+- Before finishing an agent-related diff in a repo with `shipgate.yaml`, run `agents-shipgate verify` or report the exact `agents-shipgate trigger` skip verdict.
+- Do not bypass the verifier by suppressing findings, lowering severity, expanding baselines or waivers, removing Shipgate CI, or weakening agent instructions; verify-mode `SHIP-VERIFY-*` checks make those trust-root edits release-visible.
 - Do not silently suppress findings. Suppressions require a non-empty `reason`.
 - Do not commit generated reports.
 - Do not edit the upstream `agents-shipgate` check implementation unless the user is working in the Agents Shipgate repo itself.

.agents/skills/agents-shipgate/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Agents Shipgate"
   short_description: "Run Tool-Use Readiness release gates"
-  default_prompt: "Use $agents-shipgate to add a Tool-Use Readiness release gate to this agent repo."
+  default_prompt: "Use $agents-shipgate to add or verify a Tool-Use Readiness release gate for this agent repo."
 
 policy:
   allow_implicit_invocation: true

.agents/skills/agents-shipgate/references/recipes.md

@@ -36,6 +36,37 @@ AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate apply-patches \
 
 If `init` reports placeholders, replace `CHANGE_ME` values from repo context before scanning. If `shipgate.yaml` already exists, edit it rather than overwriting it.
 
+## Verify An Agent-Related Diff
+
+Use this before finishing a PR or local change that touches an agent tool
+surface, prompts, policies, permissions, Shipgate CI, or other protected
+release surfaces.
+
+```bash
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate trigger \
+  --workspace . --base origin/main --head HEAD --json
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
+  --workspace . --config shipgate.yaml \
+  --ci-mode advisory --format json
+```
+
+For local pre-commit work, omit `--head` and omit `--base` unless the base ref
+exists locally so `verify` scans the checked-out working tree, including
+uncommitted edits. In committed PR or CI contexts, add
+`--base origin/main --head HEAD` after making the base ref available. If you
+pass a missing `--base`, `verify` exits 2 with an unknown merge verdict.
+
+Read `agents-shipgate-reports/report.json` first. Use
+`release_decision.decision` as the gate. Use `verifier_summary` only as a
+composition summary: its `verdict` mirrors `release_decision.decision` and it
+adds counts for protected-surface touches, policy weakening, human
+acknowledgement, and top reason codes.
+
+Do not bypass the verifier. Do not suppress findings, lower severity, expand
+baselines or waivers, remove Shipgate CI, or weaken agent instructions to make
+the run pass. Verify-mode `SHIP-VERIFY-*` findings route those trust-root
+changes to human review.
+
 ## First-Time CI
 
 Use advisory mode only. Copy `assets/advisory-pr-comment.yml` to `.github/workflows/agents-shipgate.yml`.

.agents/skills/agents-shipgate/references/report-reading.md

@@ -8,7 +8,25 @@ Always read `agents-shipgate-reports/report.json`. Do not scrape Markdown.
 2. `release_decision.blockers[]`: items blocking release.
 3. `release_decision.review_items[]`: accepted debt or human-review items.
 4. `agent_summary`: one-fetch summary with `headline`, counts, safe patches, human-review needs, and `first_recommended_action`.
-5. `findings[]`: detailed evidence, source, severity, and remediation.
+5. `verifier_summary`: one-fetch verifier composition for PR controllers. Its `verdict` mirrors `release_decision.decision`; use it for protected-surface, policy-weakening, human-ack, and reason-code rollups, never as a second gate.
+6. `findings[]`: detailed evidence, source, severity, and remediation.
+
+## Verifier Summary
+
+When `report_schema_version` is `0.22` or newer, read
+`verifier_summary` after `release_decision`:
+
+- `verdict`: exact mirror of `release_decision.decision`.
+- `protected_surface_touched`: true when verify-mode `SHIP-VERIFY-*`
+  findings show a trust-root edit.
+- `policy_weakened`: true when the normalized policy surface moved toward
+  less review, less blocking, or less evidence.
+- `human_ack_required` / `human_ack_satisfied`: declared human-acknowledgement
+  state; a coding agent must not synthesize acknowledgement.
+- `top_reason_codes[]`: ranked reason-code counts for concise summaries.
+
+This block is a deterministic projection. It cannot introduce a blocker that
+is not already present in `findings[]` and `release_decision`.
 
 ## Per-Finding Action
 

.claude/commands/shipgate.md

@@ -1,28 +1,51 @@
 ---
-description: Bootstrap agents-shipgate as a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces
+description: Bootstrap or verify agents-shipgate as a local-first, static Tool-Use Readiness release gate for AI agent tool surfaces
 ---
 
-Run the agents-shipgate bootstrap flow on the current repo: install the CLI,
+Arguments: `$ARGUMENTS`
+
+If the arguments include `verify`, run the ongoing-PR verifier flow. Otherwise
+run the agents-shipgate bootstrap flow on the current repo: install the CLI,
 add a local-first, static Tool-Use Readiness release gate for AI agent tool
 surfaces, generate `shipgate.yaml`, fill in placeholders, run a scan, and
 surface the top findings from the JSON report.
 
-The canonical, self-contained instructions live in `prompts/add-shipgate-to-repo.md`. Read that file first and follow it verbatim. Try these paths in order; use the first that exists:
+The canonical, self-contained instructions live in the bundled prompt files.
+For bootstrap, read `prompts/add-shipgate-to-repo.md`. For verifier runs, read
+`prompts/verify-agent-diff.md`. Try these paths in order; use the first that
+exists:
+
+1. `.claude/skills/agents-shipgate/prompts/<recipe>.md` — bundled with the `agents-shipgate` skill if installed in this project.
+2. `prompts/<recipe>.md` — present when this repo is a clone of `agents-shipgate` itself.
+3. `https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/prompts/<recipe>.md` — last-resort fetch.
+
+Verifier command:
+
+```bash
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
+  --workspace . --config shipgate.yaml \
+  --ci-mode advisory --format json
+```
 
-1. `.claude/skills/agents-shipgate/prompts/add-shipgate-to-repo.md` — bundled with the `agents-shipgate` skill if installed in this project.
-2. `prompts/add-shipgate-to-repo.md` — present when this repo is a clone of `agents-shipgate` itself.
-3. `https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/prompts/add-shipgate-to-repo.md` — last-resort fetch.
+Add `--base origin/main --head HEAD` only when verifying a committed PR/CI ref
+after making the base ref available. For local pre-commit work, omit both so
+uncommitted edits are scanned.
 
 Required behavior (do not skip):
 
 1. Set `AGENTS_SHIPGATE_AGENT_MODE=1` for every CLI call so errors emit a `next_action` JSON line on stderr.
 2. Run `agents-shipgate contract --json` when available and use it to verify the installed CLI's schema versions and gating signal.
 3. Confirm with the user before running `agents-shipgate init --workspace . --write` (it writes `shipgate.yaml` to the workspace).
 4. Parse `agents-shipgate-reports/report.json` directly — do not scrape the markdown. **For release gating, read `release_decision.decision` first** (`"blocked" | "review_required" | "insufficient_evidence" | "passed"`; baseline-aware, v0.8+; `insufficient_evidence` added v0.14) along with `release_decision.{reason, blockers, review_items, fail_policy.would_fail_ci}`. Other stable fields: `findings[].{check_id, severity, tool_name, recommendation}`. For reviewer triage by source reliability, run `agents-shipgate findings --from agents-shipgate-reports/report.json --provenance-kind keyword_heuristic,regex_heuristic --json`; `findings[].provenance_kind` is not a gate input. `summary.{critical_count, high_count, medium_count, status}` is legacy and baseline-blind — kept for v0.7 callers, do not lead with it. The Release Evidence Packet is at `agents-shipgate-reports/packet.{md,json,html}`. Full contract: [`docs/agent-contract-current.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md).
-5. Add `agents-shipgate-reports/` to `.gitignore` if it is not already.
-6. Do **not** run `agents-shipgate baseline save` in this flow — baselining is a separate decision.
+5. For verifier runs, parse `agents-shipgate-reports/verifier.json` only for trigger/base orchestration status. The release gate remains `agents-shipgate-reports/report.json.release_decision.decision`.
+6. Do **not** bypass the verifier by suppressing findings, lowering severity, expanding baselines or waivers, removing Shipgate CI, or weakening agent instructions. Verify-mode `SHIP-VERIFY-*` checks route those trust-root edits to human review.
+7. Add `agents-shipgate-reports/` to `.gitignore` if it is not already.
+8. Do **not** run `agents-shipgate baseline save` in this flow — baselining is a separate decision.
 
-Report back: `release_decision.decision` and `reason`, blocker / review-item counts, top 3 active findings by severity, the packet path (`agents-shipgate-reports/packet.md`), and one suggested next step.
+Report back: `release_decision.decision` and `reason`, `merge_verdict`,
+`can_merge_without_human`, blocker / review-item counts, top 3 active findings
+by severity, `verifier_summary` trust-root flags when present, capability
+change highlights, and one suggested next step.
 
 ## Ongoing PRs
 

.cursor/rules/agents-shipgate.mdc

@@ -35,12 +35,29 @@ When a change affects agent tools, MCP exports, OpenAPI specs, prompts,
 permissions, approval policies, or release gates, run Agents Shipgate.
 Default to advisory scans while adopting the gate.
 
+For an existing `shipgate.yaml`, prefer the ongoing-PR verifier before
+finishing:
+
+  agents-shipgate verify --workspace . --config shipgate.yaml \
+      --ci-mode advisory --format json
+
+Omit `--base` and `--head` for local pre-commit work so uncommitted edits are
+scanned; add `--base origin/main --head HEAD` only for committed PR/CI
+verification after making the base ref available.
+
 Use `agents-shipgate-reports/report.json` as the source of truth. Prefer
 `release_decision.decision` over legacy severity/status summaries.
+Use `agents-shipgate-reports/verifier.json` only for trigger/base orchestration
+status, not as a second verdict.
 
 Apply only high-confidence safe patches. Do not invent approval, confirmation,
 or idempotency evidence.
 
+Do not bypass the verifier by suppressing findings, lowering severity,
+expanding baselines or waivers, removing Shipgate CI, or weakening agent
+instructions. Verify-mode `SHIP-VERIFY-*` checks make those trust-root edits
+release-visible.
+
 For one-fetch counts and a deterministic next step, read
 `report.json.agent_summary` (v0.12+): verdict, blocker_count,
 review_item_count, auto_appliable_patches, needs_human_review,

STABILITY.md

@@ -372,9 +372,9 @@ tests on every CI run, not by convention:
     only. **Plus** one `importlib.resources.files('agents_shipgate')`
     call to resolve the bundled trigger catalog.
   - **`cli/verify/git.py`** — one shared `subprocess.run` helper invokes
-    local `git rev-parse`, `git diff`, and `git archive` for verify
-    base/head orchestration. It never fetches, uses fixed argv, captures
-    output, and never executes user code.
+    local `git rev-parse`, `git diff`, `git ls-files`, and `git archive`
+    for verify base/head and working-tree orchestration. It never fetches,
+    uses fixed argv, captures output, and never executes user code.
   - **`fixtures.py`** — one `importlib.resources.files('agents_shipgate')`
     call to resolve the bundled fixture directory.
   - **`cli/discovery/agent_instructions/adoption_kit.py`** — one

adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json

@@ -3,12 +3,14 @@
   "target": "claude-code-skill",
   "prior_render_sha256": {
     "SKILL.md": [
-      "139b5e00b916448cf2de4752221c66296a7e546865b1efdf93f98d8bb5cb3019"
+      "139b5e00b916448cf2de4752221c66296a7e546865b1efdf93f98d8bb5cb3019",
+      "5ab92f77352ea31ad03c28e1d596b20ada24fa4176a5e0b0b38990e4a00fb5bb"
     ]
   },
   "bootstrap_legacy_sha256": {
     "SKILL.md": [
-      "b17c53d9905f46b196be38e98cf71e53da6779e3a4f426ecff14f2b0f238aba9"
+      "b17c53d9905f46b196be38e98cf71e53da6779e3a4f426ecff14f2b0f238aba9",
+      "cd33a7c1d2efe003c54c5c2a270ccde7230349e19e9241dba87cb4bbd5f8ceea"
     ],
     "prompts/add-shipgate-to-repo.md": [
       "1ea69b1d3d418080c76540fff3b20044f70ed6787418eb5e4d3d39e036b34014"
@@ -34,6 +36,9 @@
     "prompts/upgrade-shipgate-version.md": [
       "992122338eba26ae5d8056b9658117d718a6b477b9928c2a438dd449b5effb68"
     ],
+    "prompts/verify-agent-diff.md": [
+      "5e4e98af540c91da8e243570d3ee411c929f3099727805f990ea0aca3245ff37"
+    ],
     "ci-recipes/advisory-pr-comment.yml": [
       "c3756c86f52cf00a594b3fe38179b66e0f07dc8c52b98b9e76f4a15939901c77"
     ]

adoption-kits/claude-code-skill/SKILL.md

@@ -33,6 +33,7 @@ Pick the matching task and follow the linked recipe verbatim. Recipes are bundle
 |---|---|
 | Decide whether Shipgate should run at all (apply `docs/triggers.json` against the PR) | [`prompts/decide-shipgate-relevance.md`](prompts/decide-shipgate-relevance.md) |
 | Bootstrap a repo (install, init, scan, report) | [`prompts/add-shipgate-to-repo.md`](prompts/add-shipgate-to-repo.md) |
+| Verify an agent-related PR or local diff before finishing | [`prompts/verify-agent-diff.md`](prompts/verify-agent-diff.md) |
 | Add Shipgate to CI for the first time (advisory, PR comment) | See "First-time CI setup" below; copy [`ci-recipes/advisory-pr-comment.yml`](ci-recipes/advisory-pr-comment.yml) |
 | Fix the highest-severity finding | [`prompts/fix-top-finding.md`](prompts/fix-top-finding.md) |
 | Recommend fixes across all active findings | [`prompts/recommend-fixes.md`](prompts/recommend-fixes.md) |
@@ -45,7 +46,9 @@ Always:
 
 1. Set `AGENTS_SHIPGATE_AGENT_MODE=1` so errors emit a `next_action` JSON line on stderr.
 2. Parse `agents-shipgate-reports/report.json` (stable contract), not the markdown.
-3. Confirm with the user before any command that writes files (`init --write`, `baseline save`).
+3. Before finishing an agent-related local diff in a repo with `shipgate.yaml`, run `agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`, or report the exact `agents-shipgate trigger` skip verdict. Add `--base origin/main --head HEAD` only for committed PR/CI verification after making the base ref available.
+4. Do not bypass the verifier by suppressing findings, lowering severity, expanding baselines or waivers, removing Shipgate CI, or weakening agent instructions; verify-mode `SHIP-VERIFY-*` checks make those trust-root edits release-visible.
+5. Confirm with the user before any command that writes files (`init --write`, `baseline save`).
 
 ## First-time CI setup (advisory)
 
@@ -77,6 +80,8 @@ For non-GitHub CI (GitLab, CircleCI, Jenkins, Azure Pipelines, Buildkite, Bitbuc
 - Do not run `agents-shipgate baseline save` until the user has reviewed the initial findings; baselining ratchets in noise.
 - Do not enable strict CI as the first CI step. Always start advisory.
 - Do not modify checks in `agents-shipgate`'s own source — that's upstream repo work.
+- Do not weaken Shipgate trust roots to make a verifier run pass. Policy, baseline,
+  waiver, CI, trigger-catalog, and agent-instruction changes require human review.
 
 ## If something errors out