Make primary Shipgate flows prominent

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

@@ -1,6 +1,6 @@
 ---
 name: agents-shipgate
-description: Use when the user wants to add or run Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes — on an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
+description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants.
 ---
 
 # Agents Shipgate
@@ -13,33 +13,30 @@
 
 ## Workflow
 
-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`.
+1. For local checks, verifier runs, host audits, and supporting recovery commands, 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. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "7"` or newer: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
+3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "8"` or newer: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
 4. Set `AGENTS_SHIPGATE_AGENT_MODE=1` before running Shipgate commands so errors include structured `next_action` JSON.
 5. Default first-time CI to advisory mode. Do not enable release-blocking CI or save a baseline until a human has reviewed current findings.
 6. For local agent control, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and read the stdout `shipgate.codex_boundary_result/v1` object. Switch on `decision`; follow `first_next_action`, `repair`, and `human_review`.
-7. Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules, policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run `agents-shipgate preflight --workspace . --plan - --json` with a `PreflightPlanV1` object. Legacy `--changed-files`/`--diff` shorthands remain available. If `requires_human_review` is true or `first_next_action.actor` is `human`, stop and route to a human.
+7. Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules, policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, plan to run `shipgate verify` before completion and route trust-root review to a human when the verifier requires it.
 8. For full PR verification, read `agents-shipgate-reports/agent-handoff.json` first, then `verifier.json` for detailed controller state, then `verify-run.json` for reproducibility metadata, then `report.json` for reviewer detail; `report.json.release_decision.decision` remains the release gate.
 9. Auto-apply only high-confidence safe patches. Do not auto-assert approval, confirmation, idempotency, broad-scope, prohibited-action, or runtime-trace evidence.
 10. Ensure `.gitignore` covers `agents-shipgate-reports/` before committing.
 
 ## Fast Paths
 
-- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "7"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
-- Protected-surface preflight: run `agents-shipgate preflight --workspace . --plan - --json` before touching trust roots; include `changed_files[]` or `diff_text` in the plan when you have concrete planned paths.
+- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "8"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
 - Agent-native check: run `shipgate check --agent codex --workspace . --format codex-boundary-json`; read only the JSON result for continue/repair/stop routing.
-- First adoption: run `agents-shipgate detect --workspace . --json`, then follow `references/recipes.md`.
-- Agent-related PR/CI diff: run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. For local uncommitted work, omit `--base`/`--head` so the working tree is scanned. `verify` never fetches.
-- Existing manifest / ongoing PR: run `agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --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`.
-- Triage heuristic findings: run `agents-shipgate findings --from agents-shipgate-reports/report.json --provenance-kind keyword_heuristic,regex_heuristic --json`.
+- Agent-related PR/CI diff: run `shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. For local uncommitted work, omit `--base`/`--head` so the working tree is scanned. `verify` never fetches.
+- Existing manifest / ongoing PR: run `shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`.
+- Unconfigured repo or uncertain relevance: run `shipgate verify --preview --json`.
+- Host grants: run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`.
 
 ## Boundaries
 
-- Do not claim a finding is fixed without re-running `agents-shipgate scan` and reporting the new decision/counts.
-- Do not continue with protected-surface edits when preflight returns `requires_human_review=true`; coding agents must not self-approve trust-root changes.
+- Do not claim a finding is fixed without re-running `shipgate verify` and reporting the new merge verdict and release decision.
+- Do not self-approve trust-root changes; when `shipgate verify` returns human review required, surface it to a human.
 - Before finishing an agent-related diff, run `shipgate check --agent codex --workspace . --format codex-boundary-json` and follow `shipgate.codex_boundary_result/v1`.
 - 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`.

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

@@ -1,199 +1,123 @@
 # Agents Shipgate Recipes
 
-Use these recipes after the `agents-shipgate` skill triggers.
+Use these recipes after the `agents-shipgate` skill triggers. The prominent
+flows are `shipgate check`, `shipgate verify`, and `shipgate audit --host`.
+Supporting commands remain callable, but should not be the first thing an agent
+recommends.
 
 ## CLI Preflight
 
-The Codex plugin supplies the workflow instructions, not the scanner binary.
-Before running `agents-shipgate` commands, confirm the CLI is installed and new
-enough for the `verify` workflow:
+The Codex plugin supplies workflow instructions, not the scanner binary.
+Before running Shipgate commands, confirm the CLI is installed and new enough:
 
 ```bash
 command -v agents-shipgate
 agents-shipgate --version
 agents-shipgate contract --json
 ```
 
-Require `agents-shipgate contract --json` to report `contract_version: "7"` or
-newer. If the command is missing or the contract is older, ask the user to
-install or upgrade the CLI and rerun the task:
+Require `agents-shipgate contract --json` to report `contract_version: "8"` or
+newer. If it is missing or stale, ask the user to install or upgrade:
 
 ```bash
 pipx install agents-shipgate
-pipx upgrade agents-shipgate  # plain install is a no-op over a stale build
+pipx upgrade agents-shipgate
 ```
 
-After installation, run `agents-shipgate --version` and
-`agents-shipgate contract --json` again. Do not continue to `detect`, `init`,
-`scan`, or `verify` until the CLI exists and reports contract v7 or newer.
+Do not report the task complete until the CLI exists and reports contract v8 or
+newer. Local boundary checks emit `shipgate.codex_boundary_result/v1`; legacy
+`agent_result_v1` fixtures are retained only for older protocol integrations.
 
-A missing or stale binary is a `decision="block"` install action in the
-agent-native protocol, not a reason to proceed unverified. Until
-`agents-shipgate contract --json` confirms contract v7 or newer, do not report
-the task complete: surface the install/upgrade action and stop. Local boundary
-checks emit `shipgate.codex_boundary_result/v1`; legacy `agent_result_v1`
-fixtures are retained only for older protocol integrations.
+## Local Agent Check
 
-## Protected Surface Preflight
+Run the boundary check before reporting an agent-related local diff complete:
 
-Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules,
-policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex
-plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run:
+```bash
+AGENTS_SHIPGATE_AGENT_MODE=1 shipgate check \
+  --agent codex --workspace . --format codex-boundary-json
+```
+
+Read only stdout JSON. Switch on `decision`, `completion_allowed`,
+`must_stop`, `first_next_action`, `human_review`, `repair`, and `policy`.
+
+## Verify A 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 preflight --workspace . --plan - --json
+AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \
+  --workspace . --config shipgate.yaml \
+  --base origin/main --head HEAD --ci-mode advisory --format json
 ```
 
-Pass a `PreflightPlanV1` object on stdin. If you already have a path list or
-local diff and need legacy shorthands, ask preflight about them before editing:
+For local uncommitted work, omit `--head` and `--base` so `verify` scans the
+checked-out working tree, including uncommitted edits. In committed PR or CI
+contexts, make the base ref available first because `verify` never fetches. If
+the repo is not configured or relevance is unclear, run:
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . \
-  --changed-files changed.txt --json
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . \
-  --diff pr.diff --json
+AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify --preview --json
 ```
 
-If `requires_human_review` is true or `first_next_action.actor` is `human`,
-stop and route the change to a human. Preflight is a routing surface only;
-`release_decision.decision` remains the gate.
+Read `agents-shipgate-reports/agent-handoff.json` first. Lead with
+`gate.merge_verdict`, then inspect `next_action`, `controller`,
+`fix_task.safe_to_attempt`, and `capability_review.top_changes[]`. Then read
+`verifier.json`, `verify-run.json`, and `report.json`; the release gate remains
+`report.json.release_decision.decision`.
+
+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-*` findings route those trust-root
+changes to human review.
 
-## Decide Relevance
+## Audit Host Grants
 
-Run:
+Run host audit when the task touches MCP servers, permission rules, hooks,
+workflow scopes, or coding-agent host configuration:
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate detect --workspace . --json
+AGENTS_SHIPGATE_AGENT_MODE=1 shipgate audit --host --json \
+  --out agents-shipgate-reports/host-grants.json
 ```
 
-Proceed when any of these are true:
-
-- `is_agent_project: true`
-- `suggested_sources` is non-empty
-- `codex_plugin_candidates` is non-empty
-- `shipgate.yaml` already exists
-- the user explicitly asked for a Shipgate scan or Tool-Use Readiness gate
+For drift checks against an acknowledged baseline, use the same flow with
+`--drift` and optionally `--fail-on-drift`.
 
-Stop only when all signals are absent and the user did not explicitly request Shipgate.
+## Supporting Setup And Repair
 
-## Bootstrap A Repo
-
-Run:
+If `shipgate verify --preview --json` says the repo needs configuration, the
+supporting setup commands remain available:
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate detect --workspace . --json
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate contract --json
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate init --workspace . --write --ci --json
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate scan -c shipgate.yaml --suggest-patches --format json
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate apply-patches \
   --from agents-shipgate-reports/report.json \
   --confidence high --apply
 ```
 
-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 preflight --workspace . --plan - --json
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
-  --workspace . --config shipgate.yaml \
-  --base origin/main --head HEAD --ci-mode advisory --format json
-```
-
-For local uncommitted work, omit `--head` and omit `--base` so `verify` scans
-the checked-out working tree, including uncommitted edits. In committed PR or
-CI contexts, make the base ref available first because `verify` never fetches.
-If you pass a missing `--base`, `verify` exits 2 with an unknown merge verdict.
-
-Read `agents-shipgate-reports/agent-handoff.json` first. Lead with
-`gate.merge_verdict`, then inspect `capability_review.top_changes[]`,
-`next_action`, `controller`, and `fix_task.safe_to_attempt`. Then read
-`agents-shipgate-reports/verifier.json` for detailed controller context and
-`agents-shipgate-reports/report.json`; `release_decision.decision` remains the
-gate. `capability_review.top_changes[]` and `verifier_summary` are
-supporting/provisional composition summaries: their verdict-like values mirror
-`release_decision.decision`, and they add 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`.
+If `init` reports placeholders, replace `CHANGE_ME` values from repo context
+before verification. If `shipgate.yaml` already exists, edit it rather than
+overwriting it.
 
-Do not switch to release-blocking behavior in the same task. Strict promotion requires human review, suppressions with reasons, and optionally a saved baseline.
-
-## Fix Top Finding
+## Fix Or Explain Findings
 
 1. Read `agents-shipgate-reports/report.json`.
 2. Pick the first blocker, then highest-severity review item.
-3. If `findings[].agent_action == "auto_apply"` and a high-confidence patch exists, apply it with `apply-patches --confidence high --apply`.
-4. For policy/evidence gaps, propose the exact human decision needed. Do not fabricate approval, confirmation, idempotency, broad-scope, prohibited-action, or runtime-trace evidence.
-5. Re-run scan and report the new `release_decision.decision`, blocker count, and review item count.
-
-## Recommend Fixes
-
-Group active findings by action:
+3. Auto-apply only high-confidence safe patches.
+4. For policy/evidence gaps, propose the exact human decision needed. Do not
+   fabricate approval, confirmation, idempotency, broad-scope,
+   prohibited-action, or runtime-trace evidence.
+5. Re-run `shipgate verify` and report the new merge verdict, release
+   decision, blocker count, and review-item count.
 
-- `auto_apply`: safe mechanical patches.
-- `propose_patch_for_review`: show patch, leave final decision to user.
-- `escalate_to_human`: policy/evidence decision.
-- `suppress_with_reason`: only when the user confirms the finding is intentionally accepted.
-- `informational`: summarize, no gate action.
-
-## Explain A Finding
-
-Run:
+For one finding:
 
 ```bash
 agents-shipgate explain-finding <fingerprint> \
   --from agents-shipgate-reports/report.json --json
 ```
 
-Use the returned deterministic `explanation` for PR comments or chat replies. Keep it to 3-5 sentences and include the tool name, release risk, and next action.
-
-## Triage False Positives
-
-Prefer fixing the manifest or policy evidence over suppression. Suppress only with a specific reason:
-
-```yaml
-checks:
-  ignore:
-    - check_id: SHIP-CHECK-ID
-      tool: tool.name
-      reason: specific accepted-risk rationale
-```
-
-## Promote Advisory To Strict
-
-Only after humans review advisory output:
-
-```bash
-agents-shipgate baseline save -c shipgate.yaml --out .agents-shipgate/baseline.json
-agents-shipgate scan -c shipgate.yaml \
-  --baseline .agents-shipgate/baseline.json \
-  --ci-mode strict --fail-on critical,high
-```
-
-The promoted gate should fail only on new findings above the selected threshold.
-
-## Upgrade Shipgate
-
-Update the GitHub Action tag and `shipgate_version` together. Re-run:
-
-```bash
-agents-shipgate contract --json
-agents-shipgate scan -c shipgate.yaml --suggest-patches --format json
-```
-
-If schema or decision fields changed, use `docs/agent-contract-current.md` from the installed version or upstream repo.
+Suppressions require a specific non-empty reason and explicit user approval.