From 1afea1af177a7cac163905c65961452ecbdb78d0 Mon Sep 17 00:00:00 2001 From: Pengfei Hu Date: Sun, 28 Jun 2026 22:16:52 -0700 Subject: [PATCH 1/2] Canonicalize three-command CLI positioning --- .agents/skills/agents-shipgate/SKILL.md | 18 ++++++------- .../agents-shipgate/references/recipes.md | 14 +++++----- .claude/commands/shipgate.md | 6 ++--- .cursor/rules/agents-shipgate.mdc | 4 +-- .well-known/agents-shipgate.json | 8 +++--- README.md | 25 ++++++++++-------- STABILITY.md | 19 ++++++++------ action.yml | 2 +- .../.agents-shipgate-kit-metadata.json | 12 ++++++--- adoption-kits/claude-code-skill/SKILL.md | 8 +++--- .../prompts/add-shipgate-to-repo.md | 8 +++--- .../prompts/decide-shipgate-relevance.md | 4 +-- .../prompts/verify-agent-diff.md | 10 +++---- .../.agents-shipgate-kit-metadata.json | 6 +++-- adoption-kits/codex-skill/SKILL.md | 18 ++++++------- .../codex-skill/references/recipes.md | 14 +++++----- docs/INDEX.md | 2 +- docs/agent-contract-current.md | 12 +++++---- docs/agents/use-with-claude-code.md | 4 +-- docs/architecture.md | 2 +- docs/design-partner-reengagement.md | 2 +- docs/design-partner-verifier-pilot.md | 2 +- docs/diagnostics.md | 2 +- docs/errors.json | 2 +- docs/host-grants-inventory-schema.v0.1.json | 4 +-- docs/mcp-governance.md | 8 +++--- docs/quickstart.md | 9 ++++--- docs/target-repo-agent-snippets.md | 16 ++++++------ docs/triggers.json | 12 ++++----- .../github-actions/12-host-grant-drift.yml | 4 +-- llms-full.txt | 12 +++++---- .../skills/agents-shipgate/SKILL.md | 18 ++++++------- .../agents-shipgate/references/recipes.md | 14 +++++----- prompts/add-shipgate-to-repo.md | 8 +++--- prompts/decide-shipgate-relevance.md | 4 +-- prompts/verify-agent-diff.md | 10 +++---- scripts/generate_schemas.py | 2 +- skills/agents-shipgate/SKILL.md | 8 +++--- .../prompts/add-shipgate-to-repo.md | 8 +++--- .../prompts/decide-shipgate-relevance.md | 4 +-- .../prompts/verify-agent-diff.md | 10 +++---- src/agents_shipgate/cli/diagnostics.py | 2 +- .../agent_instructions/renderers/agents_md.py | 6 ++--- .../agent_instructions/renderers/claude_md.py | 6 ++--- .../agent_instructions/renderers/cursor.py | 4 +-- src/agents_shipgate/cli/first_look.py | 18 +++++++------ src/agents_shipgate/cli/host_audit.py | 2 +- src/agents_shipgate/cli/install_hooks.py | 4 +-- src/agents_shipgate/cli/main.py | 10 +++---- .../cli/verify/orchestrator.py | 6 ++--- src/agents_shipgate/core/codex_boundary.py | 4 +-- src/agents_shipgate/core/host_grants.py | 16 ++++++------ src/agents_shipgate/core/preflight.py | 4 +-- src/agents_shipgate/schemas/contract.py | 10 +++---- src/agents_shipgate/schemas/host_grants.py | 2 +- src/agents_shipgate/triggers.py | 10 +++---- .../claude-code-block-stop.json | 2 +- .../agent_protocol/codex-block-stop.json | 2 +- .../agent_protocol/cursor-block-stop.json | 2 +- .../github_action_removed.json | 2 +- tests/test_agent_instructions_apply.py | 6 +++-- tests/test_agent_instructions_renderers.py | 26 ++++++++++--------- tests/test_cli.py | 6 ++--- tests/test_codex_boundary_check.py | 10 +++---- tests/test_diagnostics.py | 2 +- tests/test_first_look.py | 2 +- tests/test_local_contract.py | 3 ++- tests/test_public_surface_contract.py | 26 +++++++++++-------- tests/test_schema_boundaries.py | 8 +++--- tests/test_trigger_command.py | 4 +-- tests/test_verify.py | 4 +-- 71 files changed, 295 insertions(+), 269 deletions(-) diff --git a/.agents/skills/agents-shipgate/SKILL.md b/.agents/skills/agents-shipgate/SKILL.md index 16230781..7a584ebf 100644 --- a/.agents/skills/agents-shipgate/SKILL.md +++ b/.agents/skills/agents-shipgate/SKILL.md @@ -1,6 +1,6 @@ --- name: agents-shipgate -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. +description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants. --- # Agents Shipgate @@ -15,28 +15,28 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali 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: "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. +3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "9"` 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`, plan to run `shipgate verify` before completion and route trust-root review to a human when the verifier requires it. +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 `agents-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: "8"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`. +- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "9"` 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. -- 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`. +- 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`. +- Unconfigured repo or uncertain relevance: run `agents-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 `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. +- Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision. +- Do not self-approve trust-root changes; when `agents-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`. diff --git a/.agents/skills/agents-shipgate/references/recipes.md b/.agents/skills/agents-shipgate/references/recipes.md index 9bf13480..edb8f164 100644 --- a/.agents/skills/agents-shipgate/references/recipes.md +++ b/.agents/skills/agents-shipgate/references/recipes.md @@ -1,7 +1,7 @@ # Agents Shipgate Recipes Use these recipes after the `agents-shipgate` skill triggers. The prominent -flows are `shipgate check`, `shipgate verify`, and `shipgate audit --host`. +flows are `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`. Supporting commands remain callable, but should not be the first thing an agent recommends. @@ -16,7 +16,7 @@ agents-shipgate --version agents-shipgate contract --json ``` -Require `agents-shipgate contract --json` to report `contract_version: "8"` or +Require `agents-shipgate contract --json` to report `contract_version: "9"` or newer. If it is missing or stale, ask the user to install or upgrade: ```bash @@ -24,7 +24,7 @@ pipx install agents-shipgate pipx upgrade agents-shipgate ``` -Do not report the task complete until the CLI exists and reports contract v8 or +Do not report the task complete until the CLI exists and reports contract v9 or newer. Local boundary checks emit `shipgate.codex_boundary_result/v1`; legacy `agent_result_v1` fixtures are retained only for older protocol integrations. @@ -47,7 +47,7 @@ surface, prompts, policies, permissions, Shipgate CI, or other protected release surfaces. ```bash -AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \ +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \ --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` @@ -58,7 +58,7 @@ 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 shipgate verify --preview --json +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify --preview --json ``` Read `agents-shipgate-reports/agent-handoff.json` first. Lead with @@ -87,7 +87,7 @@ For drift checks against an acknowledged baseline, use the same flow with ## Supporting Setup And Repair -If `shipgate verify --preview --json` says the repo needs configuration, the +If `agents-shipgate verify --preview --json` says the repo needs configuration, the supporting setup commands remain available: ```bash @@ -110,7 +110,7 @@ overwriting it. 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 +5. Re-run `agents-shipgate verify` and report the new merge verdict, release decision, blocker count, and review-item count. For one finding: diff --git a/.claude/commands/shipgate.md b/.claude/commands/shipgate.md index 2cd961c7..bd7e1089 100644 --- a/.claude/commands/shipgate.md +++ b/.claude/commands/shipgate.md @@ -10,7 +10,7 @@ capability changes. If the arguments include `audit`, run the host-grant audit flow. If they include `check`, run the local boundary check. Otherwise run the verifier flow. The supporting adoption and scan commands remain available, but this slash command -should lead with only the prominent flows: `shipgate check`, `shipgate verify`, +should lead with only the prominent flows: `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`. The canonical, self-contained verifier instructions live in the bundled prompt @@ -26,7 +26,7 @@ Prominent commands: ```bash AGENTS_SHIPGATE_AGENT_MODE=1 shipgate check \ --agent claude-code --workspace . --format codex-boundary-json -AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \ +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \ --workspace . --config shipgate.yaml \ --base origin/main --head HEAD \ --ci-mode advisory --format json @@ -67,7 +67,7 @@ For an ongoing PR that changes agent tools, MCP exports, OpenAPI specs, prompts, permissions, policies, CI gates, or `shipgate.yaml`, run the verifier: ```bash -shipgate verify --base origin/main --head HEAD --json +agents-shipgate verify --base origin/main --head HEAD --json ``` Read `agents-shipgate-reports/verifier.json` first and lead with `merge_verdict` diff --git a/.cursor/rules/agents-shipgate.mdc b/.cursor/rules/agents-shipgate.mdc index 2769bf67..40734b4a 100644 --- a/.cursor/rules/agents-shipgate.mdc +++ b/.cursor/rules/agents-shipgate.mdc @@ -52,9 +52,9 @@ result to a human. For local verification, run: - shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json + agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read diff --git a/.well-known/agents-shipgate.json b/.well-known/agents-shipgate.json index 536297f6..e0bb5863 100644 --- a/.well-known/agents-shipgate.json +++ b/.well-known/agents-shipgate.json @@ -76,8 +76,7 @@ "check_codex": "shipgate check --agent codex --workspace . --format codex-boundary-json", "check_claude_code": "shipgate check --agent claude-code --workspace . --format codex-boundary-json", "check_cursor": "shipgate check --agent cursor --workspace . --format codex-boundary-json", - "verify_local": "shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --json", - "verify_pr": "shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --json", + "verify_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --json", "host_audit": "shipgate audit --host --json --out agents-shipgate-reports/host-grants.json" }, "commands": { @@ -88,6 +87,7 @@ "preflight": "agents-shipgate preflight --workspace . --config shipgate.yaml --plan - --json", "preview": "agents-shipgate verify --preview --json", "install_ai_coding_workflow": "agents-shipgate init --workspace . --write --ci --agent-instructions=default --json", + "verify_local": "agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --json", "verify_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json", "agent_handoff": "agents-shipgate agent handoff --from agents-shipgate-reports/verifier.json --json", "trigger": "agents-shipgate trigger --base origin/main --head HEAD --json", @@ -99,7 +99,7 @@ "org_policy_packs": "agents-shipgate org policy-packs --config shipgate.yaml --json", "registry_summary": "agents-shipgate registry summary --registry .agents-shipgate/registry.jsonl --json", "registry_verify": "agents-shipgate registry verify --registry .agents-shipgate/registry.jsonl --json", - "host_audit": "agents-shipgate audit --host --json --out agents-shipgate-reports/host-grants.json", + "host_audit": "shipgate audit --host --json --out agents-shipgate-reports/host-grants.json", "capture_scenario": "agents-shipgate feedback capture --before verifier-before.json --after verifier-after.json --redact --out scenario.json", "governance_benchmark": "PYTHONPATH=src python scripts/run_governance_benchmark.py --catalog benchmark/agent-pr-governance/cases.yaml --json" }, @@ -126,7 +126,7 @@ "agent_handoff_schema_version": "shipgate.agent_handoff/v1", "agent_handoff_schema_path": "docs/agent-handoff-schema.v1.json", "agent_handoff_artifact": "agents-shipgate-reports/agent-handoff.json", - "contract_version": "8", + "contract_version": "9", "inputs": ["mcp", "openapi", "openai_agents_sdk", "anthropic_api", "google_adk", "langchain", "crewai", "openai_api", "codex_config", "codex_plugin", "n8n"], "outputs": ["markdown", "json", "sarif", "packet_md", "packet_json", "packet_html", "verifier_json", "verify_run_json", "agent_handoff_json", "pr_comment_md", "check_annotations_json", "capability_lock_json", "base_capability_lock_json", "capability_lock_diff_json", "capability_lock_diff_md", "feedback_json", "attestation_json", "org_evidence_bundle_json", "host_grants_json", "org_status_json", "scenario_json", "governance_benchmark_result_json"], "artifacts": { diff --git a/README.md b/README.md index ca7890a7..5e4fb8a9 100644 --- a/README.md +++ b/README.md @@ -127,7 +127,7 @@ Switch on `decision`, `completion_allowed`, `must_stop`, decision from prose. `shipgate check` is necessary but not sufficient for capability-expanding diffs: if a change adds dynamic, undeclared, or otherwise ambiguous tool capability, do not treat `decision="allow"` as merge readiness; -run `shipgate verify` and read `release_decision.decision`. +run `agents-shipgate verify` and read `release_decision.decision`. ### PR And Local Verification @@ -136,7 +136,7 @@ diff and read its merge verdict before you merge. For committed PR/CI refs, make the base ref available first because `verify` never fetches: ```bash -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json --base origin/main --head HEAD ``` @@ -144,16 +144,19 @@ For local, uncommitted work, omit `--base`/`--head` so your working-tree edits are scanned instead: ```bash -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json ``` If a repo is not configured yet, use the verify flow's preview entry point: ```bash -shipgate verify --preview --json +agents-shipgate verify --preview --json ``` +The short `shipgate verify` alias remains invokable for compatibility, but +agent-facing PR-gate guidance uses `agents-shipgate verify`. + ### Host-Grant Audit Before changing local MCP servers, Codex/Claude/Cursor permission rules, @@ -247,8 +250,8 @@ Use only the prominent Shipgate flows as first-look commands: shipgate check --agent codex --workspace . --format codex-boundary-json shipgate check --agent claude-code --workspace . --format codex-boundary-json shipgate check --agent cursor --workspace . --format codex-boundary-json -shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json +agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json shipgate audit --host --json --out agents-shipgate-reports/host-grants.json For local control, parse the `shipgate check` stdout JSON @@ -299,7 +302,7 @@ agents-shipgate init --workspace . --write --agent-instructions=agents-md,codex- Then invoke `$agents-shipgate` in a fresh thread. The plugin supplies workflows, not the scanner binary — install the CLI (`pipx install agents-shipgate && pipx upgrade agents-shipgate`) where Codex runs commands and -require contract v8 or newer. Marketplace details, kit overrides, and the beta-migration +require contract v9 or newer. Marketplace details, kit overrides, and the beta-migration steps: [`docs/agents/use-with-codex.md`](docs/agents/use-with-codex.md). **Cursor** — `init --agent-instructions=cursor` writes the auto-attach rule; @@ -327,7 +330,7 @@ evidence around them: ## Verify your repo ```bash -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` @@ -351,7 +354,7 @@ Install alternatives (your agent project does **not** need Python 3.12 — insta ```bash python -m pip install -U --pre agents-shipgate # global pip uv tool install --upgrade agents-shipgate # via uv -agents-shipgate contract --json # require contract_version >= 8 +agents-shipgate contract --json # require contract_version >= 9 ``` ## Adopt in one turn (scan helper) @@ -496,9 +499,9 @@ Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Clau - **[`llms.txt`](llms.txt)** — short index of every machine-readable surface, one fetch. - **[`llms-full.txt`](llms-full.txt)** — long-form concatenation of `AGENTS.md` + recipes + checks + concepts + autofix policy, in one document. Built by `scripts/build-llms-full.py`. - **[`.well-known/agents-shipgate.json`](.well-known/agents-shipgate.json)** — discovery metadata (tagline, install commands, schema URLs, gating signal, exit codes, trigger-catalog URL). -- **[`docs/triggers.json`](docs/triggers.json)** — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to run `shipgate verify --preview --json` or the full verifier. Schema is stable for `0.x`. +- **[`docs/triggers.json`](docs/triggers.json)** — machine-readable mirror of the AGENTS.md trigger table. Apply the rules to a PR diff to decide whether to run `agents-shipgate verify --preview --json` or the full verifier. Schema is stable for `0.x`. - **[`tools/shipgate-detect.py`](tools/shipgate-detect.py)** — zero-install, stdlib-only detector. `curl … | python3 - --workspace . --json` returns the same structural verdict as `agents-shipgate detect --json`. Pinned to the canonical CLI by [`tests/test_zero_install_detector.py`](tests/test_zero_install_detector.py). See [`docs/zero-install.md`](docs/zero-install.md). -- **`agents-shipgate contract --json`** — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions; contract v8 names `primary_commands`, the verifier, verify-run, agent-handoff, Codex boundary, attestation, registry, org evidence bundle, host-grants inventory, and legacy local-agent schema versions plus the agent read order. +- **`agents-shipgate contract --json`** — verify the installed CLI's local contract before relying on hard-coded schema or gating assumptions; contract v9 names `primary_commands`, the verifier, verify-run, agent-handoff, Codex boundary, attestation, registry, org evidence bundle, host-grants inventory, and legacy local-agent schema versions plus the agent read order. - **[`docs/agent-contract-current.md`](docs/agent-contract-current.md)** — single source of truth for the current schema versions and which JSON fields to read. Updated whenever the contract bumps; other agent-facing surfaces link here instead of restating the contract. - **[`docs/agent-native-merge-contract.md`](docs/agent-native-merge-contract.md)** — the agent-native protocol map: the eight contracts (trigger, capability change, merge verdict, repair, forbidden action, human authority, trust root, attestation) each mapped to the artifact that implements it. - **[`docs/capability-standard.md`](docs/capability-standard.md)** — stable non-gating capability lock/diff standard for external integrations and research tooling. diff --git a/STABILITY.md b/STABILITY.md index 53237a0f..6cb29ded 100644 --- a/STABILITY.md +++ b/STABILITY.md @@ -42,10 +42,12 @@ Breaking changes from the `0.x` line: New outputs include `verify_run_json`, `run_id`, `agent_controller_must_stop`, `agent_controller_stop_reason`, and `agent_controller_completion_allowed`. -- The runtime contract payload is now `contract_version: "8"`. +- The runtime contract payload is now `contract_version: "9"`. It adds `primary_commands{}` so agents can discover the three prominent - flows (`shipgate check`, `shipgate verify`, and `shipgate audit --host`) - without treating supporting/adoption commands as first-look guidance. + flows (`shipgate check`, `agents-shipgate verify`, and + `shipgate audit --host`) without treating supporting/adoption commands as + first-look guidance. `verify_local` remains in `commands{}` as a supporting + compatibility command, not a promoted primary flow. Report JSON remains `report_schema_version: "0.27"` from the current `0.13.0` line; this alpha does not redefine that frozen report schema. v0.27 includes policy-pack distribution metadata @@ -121,7 +123,7 @@ command-contract commitments yet. They remain consumers of `verify` artifacts; | `agents-shipgate registry report` | `--registry`, `--bypass`, `--json`, `--fail-on-bypass` | | `agents-shipgate registry summary` | `--registry`, `--json` | | `agents-shipgate registry verify` | `--registry`, `--json`, `--fail-on-issue` | -| `agents-shipgate audit --host` | `--workspace`, `--host`, `--json`, `--out`, `--save-baseline`, `--baseline`, `--drift`, `--fail-on-drift` | +| `shipgate audit --host` | `--workspace`, `--host`, `--json`, `--out`, `--save-baseline`, `--baseline`, `--drift`, `--fail-on-drift` | `agents-shipgate feedback export` is introduced in v0.11 for design-partner feedback loops. Its current flags are `--from`, `--redact`/`--no-redact`, @@ -218,9 +220,10 @@ Stable JSON fields: mcp-serve`. - `manual_review_signals[]` — stable report/packet fields an agent should read when surfacing human review work. -- `primary_commands{}` — the prominent flow map for local boundary checks, - local/PR verification, and host-grant audits. Values use the `shipgate` - alias and contain only `check`, `verify`, and `audit --host` entry points. +- `primary_commands{}` — the prominent flow map for local boundary checks, PR + verification, and host-grant audits. Values promote `shipgate check`, + `agents-shipgate verify`, and `shipgate audit --host`; local verify remains + available under `commands{}`. - `commands{}` — compatibility/supporting commands for local `shipgate check` control, preview, default local agent workflow install, local verify, PR verify, and contract introspection. @@ -819,7 +822,7 @@ failure, not a docs-only or no-trigger success: verify writes `verifier.json`, `head_status: "failed"`, `head_exit_code: 2`, `merge_verdict: "unknown"`, `applicability: "unknown"`, and `can_merge_without_human: false`; it writes no `report.json` and runs no head scan. The first next action directs agents to -fix the config path or run `shipgate verify --preview --json` before +fix the config path or run `agents-shipgate verify --preview --json` before initializing. The head scan writes `report.md`, `report.json`, `report.sarif`, `packet.json`, diff --git a/action.yml b/action.yml index d901d252..6369605a 100644 --- a/action.yml +++ b/action.yml @@ -423,7 +423,7 @@ runs: OUTPUT_DIR: ${{ inputs.output_dir }} run: | mkdir -p "${OUTPUT_DIR}" - agents-shipgate audit --host --workspace "." --json \ + shipgate audit --host --workspace "." --json \ --out "${OUTPUT_DIR}/host-grants.json" >/dev/null || \ echo "Agents Shipgate host audit failed; artifact skipped." >&2 diff --git a/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json b/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json index 01cbba7b..87663761 100644 --- a/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json +++ b/adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json @@ -17,7 +17,8 @@ "3b643d8fe5f88817702fae3d7bd51964d878a413e13fa1c7e1bc0007ee733744", "1d80cb6eeadf064fbb613ae3bd5b5e46ed4fd729c21b314d30537cb884e4a19e", "398e88622bf73b524f91405ffc5dbccde651c6a9cb7c2df035ab01d39a964e4f", - "9860b9246057289450b425daa212f248be8082327101f2a5e6a355a266f779c1" + "9860b9246057289450b425daa212f248be8082327101f2a5e6a355a266f779c1", + "5062b30ee84b3871c6532ce0e6c7ad41ac0203a1bd29be51ac3342e01fcd09cb" ], "prompts/add-shipgate-to-repo.md": [ "ea3c37cfbbd42c40d164abfe21d468a3a5550d5384125f94a53c947dea6b4b2a", @@ -25,7 +26,8 @@ "2c946f83247106a3cda96eaf92466df3d5af564faea040e13d586eefedf4f4a9", "2a6c5dea9919f031f64a5b8ee0c657d3cc6913c05da3a4ebaa8eb9e2f0728dc0", "347118060d1d39f709de5c024b617a2fdb8bd9659ac5a56d768e9a1aa39c0142", - "4db5c3f0a2f1c68fb726c5e5ec7439c985e373a29dfa6867f18b6e22c604be18" + "4db5c3f0a2f1c68fb726c5e5ec7439c985e373a29dfa6867f18b6e22c604be18", + "47f370db7820b665de6fcc61968c735e0dfb88715b9f666795687b73f0034dce" ], "prompts/stabilize-strict-mode.md": [ "ac9a176738ab2538d725c29ba302637bac6b287588e07d952aae352f85ab98cc", @@ -34,7 +36,8 @@ ], "prompts/verify-agent-diff.md": [ "0c939414da7900b8f03f2a743e0f6b8f4d96f409c1d5cde038e27a98318bf486", - "1d59c30ea72b1e7ba12ae0f650cf75462f62f1a8b532ab44f88c78e2242a8d17" + "1d59c30ea72b1e7ba12ae0f650cf75462f62f1a8b532ab44f88c78e2242a8d17", + "96a7eeeaf96df428575ad4758b48cdd6458c491bb067a99f73b06e6fd268c36d" ], "ci-recipes/advisory-pr-comment.yml": [ "a8aa3f577af73534cdb529fd4f5d34c08522181225a2eddee70099c5a8ef4191", @@ -44,7 +47,8 @@ "1bf8b9d91f081a246dcff14a84810ca5384f8e0987e4e7a8c0c5df56b151564c", "fbb5324440c51914a789f5ae953281437fae659e2fd163203814239ff664ce79", "6b18b2a37de79bed7f65d484c45238d3be033809fb25824a5097488894850f94", - "e12413fb49e2b66ff7046a30d35eb0b00b8d2594e8d1b481432f7922e576196c" + "e12413fb49e2b66ff7046a30d35eb0b00b8d2594e8d1b481432f7922e576196c", + "8d1540095101cd7ff3aec4ba998ced5c135cdbdb71637ad0c4e5d42fc6ec9ab7" ] }, "bootstrap_legacy_sha256": { diff --git a/adoption-kits/claude-code-skill/SKILL.md b/adoption-kits/claude-code-skill/SKILL.md index 16acee78..4c6af9e5 100644 --- a/adoption-kits/claude-code-skill/SKILL.md +++ b/adoption-kits/claude-code-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: agents-shipgate -description: Run prominent Agents Shipgate flows when a change touches what an AI agent can do: `shipgate check`, `shipgate verify`, or `shipgate audit --host`. Use after adding or modifying MCP servers or tools, tool/function definitions (@tool, @function_tool), OpenAPI specs that describe agent tools, agent prompts, permission scopes, approval or confirmation policies, agent CI workflows, or shipgate.yaml — and before creating a PR for any such change. Also use to verify agent-related PRs, fix or triage Shipgate findings, add Shipgate to CI, or interpret Shipgate verifier/report artifacts. Triggers on phrases like "add shipgate", "verify this agent PR", "merge verdict", "release readiness for my agent", "tool-use readiness", "shipgate check", "shipgate verify", "audit host grants", "shipgate.yaml", "agents-shipgate-reports/verifier.json", "agents-shipgate-reports/report.json", "fix shipgate finding". +description: Run prominent Agents Shipgate flows when a change touches what an AI agent can do: `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host`. Use after adding or modifying MCP servers or tools, tool/function definitions (@tool, @function_tool), OpenAPI specs that describe agent tools, agent prompts, permission scopes, approval or confirmation policies, agent CI workflows, or shipgate.yaml — and before creating a PR for any such change. Also use to verify agent-related PRs, fix or triage Shipgate findings, add Shipgate to CI, or interpret Shipgate verifier/report artifacts. Triggers on phrases like "add shipgate", "verify this agent PR", "merge verdict", "release readiness for my agent", "tool-use readiness", "shipgate check", "agents-shipgate verify", "audit host grants", "shipgate.yaml", "agents-shipgate-reports/verifier.json", "agents-shipgate-reports/report.json", "fix shipgate finding". --- # agents-shipgate skill @@ -53,8 +53,8 @@ Always: `fix_task`, and `capability_review.top_changes`. Then parse `agents-shipgate-reports/report.json.release_decision.decision`; it is the release gate. -4. 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. -5. Before finishing an agent-related diff, run `shipgate check --agent claude-code --workspace . --format codex-boundary-json`. For committed PR/CI verification, run `shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. `verify` never fetches. For host grants, run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`. +4. 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 `agents-shipgate verify` before completion and route trust-root review to a human when the verifier requires it. +5. Before finishing an agent-related diff, run `shipgate check --agent claude-code --workspace . --format codex-boundary-json`. For committed PR/CI verification, run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. `verify` never fetches. For host grants, run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`. 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 make those trust-root edits release-visible. 7. Confirm with the user before any command that writes files (`init --write`, `baseline save`). @@ -86,7 +86,7 @@ For non-GitHub CI (GitLab, CircleCI, Jenkins, Azure Pipelines, Buildkite, Bitbuc ## Boundaries (do not violate) -- Do not claim a finding is fixed without re-running `shipgate verify` and reporting the new merge verdict and release decision. +- Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision. - Do not silently suppress findings — `checks.ignore` requires a `reason` and the manifest validator rejects empty reasons. - Do not commit `agents-shipgate-reports/` — it's regenerated each run; add it to `.gitignore`. - Do not run `agents-shipgate baseline save` until the user has reviewed the initial findings; baselining ratchets in noise. diff --git a/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md b/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md index 9d5007a6..b2b7ee06 100644 --- a/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md +++ b/adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md @@ -5,11 +5,11 @@ You are working in a repo that may contain an AI agent — likely one of: an MCP Your job is to drive the first-adoption helper flow end-to-end in one tool-using turn, which adds the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. Ongoing -agent-related PRs should use `shipgate verify` after this adoption step. +agent-related PRs should use `agents-shipgate verify` after this adoption step. ## Your task -1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v8 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: +1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v9 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: ```bash SG="uvx agents-shipgate@1.0.0a1" # uv: ephemeral, always the pinned build # or: SG="pipx run agents-shipgate==1.0.0a1" @@ -20,8 +20,8 @@ agent-related PRs should use `shipgate verify` after this adoption step. If you would rather install onto `PATH`, pin the floor and **fail loudly when it resolves older** — a plain `pipx install agents-shipgate` is a no-op when an older build already exists — then set `SG=agents-shipgate`: ```bash python -m pip install -U --pre agents-shipgate - agents-shipgate contract --json # STOP if this reports contract_version < 8 - re-run pinned via uvx agents-shipgate@1.0.0a1 - SG=agents-shipgate # only after the line above confirms contract v8+ + agents-shipgate contract --json # STOP if this reports contract_version < 9 - re-run pinned via uvx agents-shipgate@1.0.0a1 + SG=agents-shipgate # only after the line above confirms contract v9+ ``` 2. **Sanity-check the install** before touching the user's code: diff --git a/adoption-kits/claude-code-skill/prompts/decide-shipgate-relevance.md b/adoption-kits/claude-code-skill/prompts/decide-shipgate-relevance.md index 1ba20ab9..00cf0ef2 100644 --- a/adoption-kits/claude-code-skill/prompts/decide-shipgate-relevance.md +++ b/adoption-kits/claude-code-skill/prompts/decide-shipgate-relevance.md @@ -73,8 +73,8 @@ the rules to the changed file list. zero-install** runner so a stale copy already on `PATH` can't answer — `uvx agents-shipgate@1.0.0a1 verify --preview --json` (or `pipx run agents-shipgate==1.0.0a1 ...`). Only fall back to a bare - `shipgate verify --preview --json` once `agents-shipgate --version` - confirms contract v8 or newer. Then follow + `agents-shipgate verify --preview --json` once `agents-shipgate --version` + confirms contract v9 or newer. Then follow [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md) for the first-adoption helper flow, or point the user at the GitHub Action (`ThreeMoonsLab/agents-shipgate@v1.0.0a1`) if they prefer CI. diff --git a/adoption-kits/claude-code-skill/prompts/verify-agent-diff.md b/adoption-kits/claude-code-skill/prompts/verify-agent-diff.md index 20bbcb2d..18a77ff4 100644 --- a/adoption-kits/claude-code-skill/prompts/verify-agent-diff.md +++ b/adoption-kits/claude-code-skill/prompts/verify-agent-diff.md @@ -13,7 +13,7 @@ work is complete. 2. **Use verify preview only when relevance or setup is unclear.** ```bash - shipgate verify --preview --json + agents-shipgate verify --preview --json ``` Preview is a lightweight verify entry point: no manifest required, no scan, exit 0. It tells you whether to configure Shipgate, skip, or run the full @@ -30,12 +30,12 @@ work is complete. For local uncommitted work, omit `--head` and omit `--base` so the checked-out working tree is scanned, including uncommitted edits: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json ``` For committed PR or CI verification, pass the head ref explicitly: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` `verify` never fetches. If you pass `--base` and that ref is missing, @@ -73,8 +73,8 @@ work is complete. ## What NOT to do -- Do not claim the diff is verified until `shipgate verify` has run or - `shipgate verify --preview --json` has returned a clear skip verdict. +- Do not claim the diff is verified until `agents-shipgate verify` has run or + `agents-shipgate verify --preview --json` has returned a clear skip verdict. - Do not claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or `human_review_required` unless the user explicitly accepts human review. diff --git a/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json b/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json index 329a5280..1f0524ef 100644 --- a/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json +++ b/adoption-kits/codex-skill/.agents-shipgate-kit-metadata.json @@ -12,7 +12,8 @@ "f545a945da52ba4cb67810464b0b60b1734b46a791d9c6023b5c8652d67286a8", "388e4997b09196791ff4c71aab3e83c7462a5b61e66a5cee13e76aa3cad0d89f", "b27913ffc17f1af4e0b9370ac6c353c3cfdc91c69deb5b0cd1de1b83f7581e3b", - "76c060a91d342cd02bf2c2273bcbb919a120ab063ebb32aba9cde67d6f0c2d1b" + "76c060a91d342cd02bf2c2273bcbb919a120ab063ebb32aba9cde67d6f0c2d1b", + "49c04766323dd3bec0b94f39ab236b84d0a6adc4e47bbaded70bc0f8f166f779" ], "references/recipes.md": [ "df5110bfa05eeabd9b918d8902b5c054fa547d1155be61ef6e7d7d63378bf210", @@ -24,7 +25,8 @@ "a554d3b989a65f9a64af6f2c14304e4ad94daa9e11515c21a2997dc1dd892c99", "6bf8b3a409df3cd6f94e070555d62eedf8ba3690b4cfdceae2d7a7482b90e91b", "8576dc41812871e97a5d5c213a2c9c44f9766f746d99e9bc9909ee69a4002575", - "d7779f4f2365c84727d02da770696a40490428a396e10d7a031b316f15ef849d" + "d7779f4f2365c84727d02da770696a40490428a396e10d7a031b316f15ef849d", + "64cfd980d399f24995008eeca4d196a6efd224edd01e108543ec11aeb291d085" ], "references/report-reading.md": [ "75a655059f3d45db365c744b0ff82d1c9d69c3638acacf640fd667ae87260d05", diff --git a/adoption-kits/codex-skill/SKILL.md b/adoption-kits/codex-skill/SKILL.md index 16230781..7a584ebf 100644 --- a/adoption-kits/codex-skill/SKILL.md +++ b/adoption-kits/codex-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: agents-shipgate -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. +description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants. --- # Agents Shipgate @@ -15,28 +15,28 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali 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: "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. +3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "9"` 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`, plan to run `shipgate verify` before completion and route trust-root review to a human when the verifier requires it. +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 `agents-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: "8"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`. +- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "9"` 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. -- 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`. +- 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`. +- Unconfigured repo or uncertain relevance: run `agents-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 `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. +- Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision. +- Do not self-approve trust-root changes; when `agents-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`. diff --git a/adoption-kits/codex-skill/references/recipes.md b/adoption-kits/codex-skill/references/recipes.md index 9bf13480..edb8f164 100644 --- a/adoption-kits/codex-skill/references/recipes.md +++ b/adoption-kits/codex-skill/references/recipes.md @@ -1,7 +1,7 @@ # Agents Shipgate Recipes Use these recipes after the `agents-shipgate` skill triggers. The prominent -flows are `shipgate check`, `shipgate verify`, and `shipgate audit --host`. +flows are `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`. Supporting commands remain callable, but should not be the first thing an agent recommends. @@ -16,7 +16,7 @@ agents-shipgate --version agents-shipgate contract --json ``` -Require `agents-shipgate contract --json` to report `contract_version: "8"` or +Require `agents-shipgate contract --json` to report `contract_version: "9"` or newer. If it is missing or stale, ask the user to install or upgrade: ```bash @@ -24,7 +24,7 @@ pipx install agents-shipgate pipx upgrade agents-shipgate ``` -Do not report the task complete until the CLI exists and reports contract v8 or +Do not report the task complete until the CLI exists and reports contract v9 or newer. Local boundary checks emit `shipgate.codex_boundary_result/v1`; legacy `agent_result_v1` fixtures are retained only for older protocol integrations. @@ -47,7 +47,7 @@ surface, prompts, policies, permissions, Shipgate CI, or other protected release surfaces. ```bash -AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \ +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \ --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` @@ -58,7 +58,7 @@ 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 shipgate verify --preview --json +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify --preview --json ``` Read `agents-shipgate-reports/agent-handoff.json` first. Lead with @@ -87,7 +87,7 @@ For drift checks against an acknowledged baseline, use the same flow with ## Supporting Setup And Repair -If `shipgate verify --preview --json` says the repo needs configuration, the +If `agents-shipgate verify --preview --json` says the repo needs configuration, the supporting setup commands remain available: ```bash @@ -110,7 +110,7 @@ overwriting it. 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 +5. Re-run `agents-shipgate verify` and report the new merge verdict, release decision, blocker count, and review-item count. For one finding: diff --git a/docs/INDEX.md b/docs/INDEX.md index 110bbdab..93fbd103 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -47,7 +47,7 @@ A single entry point for human readers and AI agents walking the `docs/` tree. - [`org-governance-schema.v0.1.json`](org-governance-schema.v0.1.json) — JSON Schema for `agents-shipgate org status --json`; local governance projection, not a release verdict - [`org-evidence-bundle-schema.v1.json`](org-evidence-bundle-schema.v1.json) — JSON Schema for `agents-shipgate org bundle`; compact CI/ledger ingestion artifact over verifier/report/attestation/org/host-grant evidence, not a release verdict - [`registry-schema.v0.3.json`](registry-schema.v0.3.json) — JSON Schema for `agents-shipgate registry query --json`, `registry summary --json`, `registry verify --json`, and `registry report --bypass --json` -- [`host-grants-inventory-schema.v0.1.json`](host-grants-inventory-schema.v0.1.json) — JSON Schema for `agents-shipgate audit --host --json`; versioned host MCP/permission/hook/workflow inventory +- [`host-grants-inventory-schema.v0.1.json`](host-grants-inventory-schema.v0.1.json) — JSON Schema for `shipgate audit --host --json`; versioned host MCP/permission/hook/workflow inventory - [`attestation-schema.v0.3.json`](attestation-schema.v0.3.json) — frozen v0.3 attestation reference - [`attestation-schema.v0.2.json`](attestation-schema.v0.2.json) — frozen v0.2 attestation reference - [`attestation-schema.v0.1.json`](attestation-schema.v0.1.json) — frozen v0.1 attestation reference diff --git a/docs/agent-contract-current.md b/docs/agent-contract-current.md index 77a1730c..5270dd32 100644 --- a/docs/agent-contract-current.md +++ b/docs/agent-contract-current.md @@ -10,7 +10,7 @@ Verify the installed CLI contract locally before relying on hard-coded docs: agents-shipgate contract --json ``` -Runtime contract v8 also exposes the local agent command spec: +Runtime contract v9 also exposes the local agent command spec: `primary_commands{}`, `commands{}`, `default_paths{}`, `artifacts{}`, `agent_read_order[]`, `verifier_read_order[]`, `merge_verdicts[]`, `release_decisions[]`, `do_not_auto_assert[]`, `verifier_schema_version`, @@ -21,15 +21,17 @@ Runtime contract v8 also exposes the local agent command spec: `host_grants_inventory_schema_version`, `agent_interface_operations[]`, `exit_code_policy`, `mcp_tools[]`, and the legacy `agent_result_*` fields retained for older protocol consumers. `primary_commands{}` is the prominent -entry surface and contains only `shipgate check`, `shipgate verify`, and -`shipgate audit --host` flows; `commands{}` is compatibility/supporting -metadata. +entry surface and contains only `shipgate check`, `agents-shipgate verify`, and +`shipgate audit --host` flows; `commands{}` is compatibility/supporting metadata +and retains local verify commands for older consumers. +The short `shipgate verify` alias remains invokable for compatibility, but it is +not the promoted PR-gate spelling in `primary_commands{}`. Downstream repos generated with `init --agent-instructions=default` get the minimal local copy at `.shipgate/agent-contract.json`. - Latest release: `v1.0.0a1` (see [pyproject.toml](../pyproject.toml) for the in-tree version) -- Runtime contract: `8` +- Runtime contract: `9` - Current report schema: `0.27` — [`docs/report-schema.v0.27.json`](report-schema.v0.27.json) - Current packet schema: `0.7` — [`docs/packet-schema.v0.7.json`](packet-schema.v0.7.json) - Current verifier schema: `0.1` — [`docs/verifier-schema.v0.1.json`](verifier-schema.v0.1.json) diff --git a/docs/agents/use-with-claude-code.md b/docs/agents/use-with-claude-code.md index 46b8d63c..032991b5 100644 --- a/docs/agents/use-with-claude-code.md +++ b/docs/agents/use-with-claude-code.md @@ -100,8 +100,8 @@ If `/shipgate` runs the bootstrap end-to-end, the first path is working. The first run installs `agents-shipgate` via `pipx`, generates `shipgate.yaml`, and produces `agents-shipgate-reports/report.json`. -For ongoing PRs, type `/shipgate verify`. Claude Code should read -`prompts/verify-agent-diff.md`, run: +For ongoing PRs, ask `/shipgate` to verify the PR. Claude Code should read +`prompts/verify-agent-diff.md` and run the canonical PR gate: ```bash AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \ diff --git a/docs/architecture.md b/docs/architecture.md index 80a0c2e2..bbda1a6c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -3,7 +3,7 @@ A single-page summary of the `agents-shipgate` codebase for new contributors and AI coding agents extending the project. Current as of 2026-06-08; auto-checked against `agents-shipgate contract --json`: -runtime contract `8`, report schema `v0.27`, packet schema `v0.7`. +runtime contract `9`, report schema `v0.27`, packet schema `v0.7`. For the per-field stability contract, see [`../STABILITY.md`](../STABILITY.md). For the agent-facing field index, diff --git a/docs/design-partner-reengagement.md b/docs/design-partner-reengagement.md index a33194ca..b4c8b250 100644 --- a/docs/design-partner-reengagement.md +++ b/docs/design-partner-reengagement.md @@ -33,7 +33,7 @@ No manifest, no CI change, read-only, one command: ```bash pipx install agents-shipgate -agents-shipgate audit --host +shipgate audit --host ``` One page: every MCP server, permission rule (wildcards flagged), hook, diff --git a/docs/design-partner-verifier-pilot.md b/docs/design-partner-verifier-pilot.md index a9e4b1c7..4a0180ff 100644 --- a/docs/design-partner-verifier-pilot.md +++ b/docs/design-partner-verifier-pilot.md @@ -44,7 +44,7 @@ If a partner hesitates at "bring a PR," start with the zero-config host audit instead — one read-only command, no manifest, no CI: ```bash -agents-shipgate audit --host +shipgate audit --host ``` It prints the repo's current coding-agent grants (MCP servers, permission diff --git a/docs/diagnostics.md b/docs/diagnostics.md index 33b6a175..adfa7965 100644 --- a/docs/diagnostics.md +++ b/docs/diagnostics.md @@ -67,7 +67,7 @@ diagnostics where no command should run. | ID | Severity | Fires when | | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | -| `SHIP-DIAG-MISSING-MANIFEST` | block | The manifest file does not exist on disk. Rank-1 action: `shipgate verify --workspace --preview --json`. | +| `SHIP-DIAG-MISSING-MANIFEST` | block | The manifest file does not exist on disk. Rank-1 action: `agents-shipgate verify --workspace --preview --json`. | | `SHIP-DIAG-INVALID-MANIFEST` | block | The manifest file exists but the loader rejected it (invalid YAML, schema validation failure, unsupported version). Rank-1 action: `edit `. | | `SHIP-DIAG-NO-AGENT-SURFACE` | info | `is_agent_project=false` AND `suggested_sources=[]` AND `codex_plugin_candidates=[]` AND no manifest. Catch-all negative control. | | `SHIP-DIAG-NON-AGENT-LIBRARY` | info | Python project (≥1 .py file + pyproject/requirements) with no agent framework, prompts, or tool surface. | diff --git a/docs/errors.json b/docs/errors.json index bf52740e..e5f626ab 100644 --- a/docs/errors.json +++ b/docs/errors.json @@ -21,7 +21,7 @@ "exit_code": 2, "typical_cause": "shipgate.yaml does not exist OR exists but the loader rejected it (extra key, missing required field, wrong nesting level).", "additional_fields": ["message", "next_action", "next_actions"], - "recovery_hint": "Distinguish missing vs. invalid via the diagnostic id: `SHIP-DIAG-MISSING-MANIFEST` → run `shipgate verify --workspace --preview --json`; if preview routes setup, run the emitted init command. `SHIP-DIAG-INVALID-MANIFEST` → edit the manifest at the path in the error; do NOT re-run `init` (it refuses to overwrite an existing file)." + "recovery_hint": "Distinguish missing vs. invalid via the diagnostic id: `SHIP-DIAG-MISSING-MANIFEST` → run `agents-shipgate verify --workspace --preview --json`; if preview routes setup, run the emitted init command. `SHIP-DIAG-INVALID-MANIFEST` → edit the manifest at the path in the error; do NOT re-run `init` (it refuses to overwrite an existing file)." }, { "id": "config_already_exists", diff --git a/docs/host-grants-inventory-schema.v0.1.json b/docs/host-grants-inventory-schema.v0.1.json index 30bc94c5..ded17793 100644 --- a/docs/host-grants-inventory-schema.v0.1.json +++ b/docs/host-grants-inventory-schema.v0.1.json @@ -2,7 +2,7 @@ "$defs": { "HostGrantsInventoryV1": { "additionalProperties": false, - "description": "Versioned host-grant inventory emitted by ``agents-shipgate audit --host``.", + "description": "Versioned host-grant inventory emitted by ``shipgate audit --host``.", "properties": { "codex_config_present": { "items": { @@ -211,6 +211,6 @@ "$id": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/host-grants-inventory-schema.v0.1.json", "$ref": "#/$defs/HostGrantsInventoryV1", "$schema": "https://json-schema.org/draft/2020-12/schema", - "description": "JSON Schema for agents-shipgate audit --host --json. The inventory summarizes local coding-agent host grants and does not gate releases.", + "description": "JSON Schema for shipgate audit --host --json. The inventory summarizes local coding-agent host grants and does not gate releases.", "title": "Agents Shipgate Host Grants Inventory v0.1" } diff --git a/docs/mcp-governance.md b/docs/mcp-governance.md index 609a8411..1b94b75e 100644 --- a/docs/mcp-governance.md +++ b/docs/mcp-governance.md @@ -91,13 +91,13 @@ like code: ## Zero-config audit To inventory host grants without a `shipgate.yaml` (for example, on a -repo you are evaluating), see `agents-shipgate audit --host` — it reads +repo you are evaluating), see `shipgate audit --host` — it reads the same host files and prints a one-page Markdown inventory without writing anything. For CI or fleet ingestion, emit the versioned JSON artifact: ```bash -agents-shipgate audit --host --json --out agents-shipgate-reports/host-grants.json +shipgate audit --host --json --out agents-shipgate-reports/host-grants.json ``` The payload includes `host_grants_inventory_schema_version: "0.1"` and validates @@ -115,11 +115,11 @@ same inventory: ```bash # 1. After a human reviews the current grants, record them as the # acknowledged state (writes .agents-shipgate/host-grants.json): -agents-shipgate audit --host --save-baseline +shipgate audit --host --save-baseline # 2. On a schedule (or pre-commit), compare current grants against the # acknowledged state; exit 20 on any drift: -agents-shipgate audit --host --drift --fail-on-drift +shipgate audit --host --drift --fail-on-drift ``` The baseline is content-only (no timestamps, no machine paths), so diff --git a/docs/quickstart.md b/docs/quickstart.md index 0447480b..b5738370 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -27,7 +27,7 @@ For local pre-commit work, omit `--base` and `--head` so uncommitted edits are scanned: ```bash -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json ``` @@ -35,16 +35,19 @@ For committed PR/CI refs, make the base ref available first, then pass base and head: ```bash -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json --base origin/main --head HEAD ``` If a repo is not configured yet, use the verify flow's preview entry point: ```bash -shipgate verify --preview --json +agents-shipgate verify --preview --json ``` +The short `shipgate verify` alias remains invokable for compatibility, but +agent-facing PR-gate guidance uses `agents-shipgate verify`. + Read `agents-shipgate-reports/agent-handoff.json` first and lead with `gate.merge_verdict`, `gate.can_merge_without_human`, `controller`, `next_action`, `fix_task`, and `capability_review.top_changes`. Then read diff --git a/docs/target-repo-agent-snippets.md b/docs/target-repo-agent-snippets.md index 8f6de559..51456a26 100644 --- a/docs/target-repo-agent-snippets.md +++ b/docs/target-repo-agent-snippets.md @@ -50,9 +50,9 @@ Commands: shipgate check --agent codex --workspace . --format codex-boundary-json shipgate check --agent claude-code --workspace . --format codex-boundary-json shipgate check --agent cursor --workspace . --format codex-boundary-json -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json shipgate audit --host --json --out agents-shipgate-reports/host-grants.json ``` @@ -68,7 +68,7 @@ is `repair` and `repair.safe_to_attempt=true`, make only the listed mechanical repair and rerun the command. If `human_review.required=true` or `must_stop=true`, stop and surface the JSON result to a human. -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read @@ -154,9 +154,9 @@ For agent tool-surface or release-policy changes, run: ```bash shipgate check --agent claude-code --workspace . --format codex-boundary-json -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json -shipgate verify --workspace . --config shipgate.yaml \ +agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json shipgate audit --host --json --out agents-shipgate-reports/host-grants.json ``` @@ -172,7 +172,7 @@ is `repair` and `repair.safe_to_attempt=true`, make only the listed mechanical repair and rerun the command. If `human_review.required=true` or `must_stop=true`, stop and surface the JSON result to a human. -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read @@ -253,9 +253,9 @@ result to a human. For local verification, run: - shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json + agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read diff --git a/docs/triggers.json b/docs/triggers.json index 2a707661..c55eabfb 100644 --- a/docs/triggers.json +++ b/docs/triggers.json @@ -2,10 +2,10 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "schema_version": "0.1", "name": "agents-shipgate-triggers", - "description": "Machine-readable trigger catalog for Agents Shipgate. Mirrors the AGENTS.md trigger table — a coding agent can fetch this and apply the rules to a PR diff or repo state to decide whether to run `shipgate verify --preview --json` or the full verifier. Stable for 0.x: rule IDs, predicate vocabulary, and action enum will not change in minor versions.", + "description": "Machine-readable trigger catalog for Agents Shipgate. Mirrors the AGENTS.md trigger table — a coding agent can fetch this and apply the rules to a PR diff or repo state to decide whether to run `agents-shipgate verify --preview --json` or the full verifier. Stable for 0.x: rule IDs, predicate vocabulary, and action enum will not change in minor versions.", "source_of_truth": "AGENTS.md#should-i-run-shipgate-on-this-pr", "documentation_url": "https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/AGENTS.md", - "default_command": "shipgate verify --preview --json", + "default_command": "agents-shipgate verify --preview --json", "predicate_vocabulary": { "glob": "Any changed file in the PR matches the glob (relative to repo root). Globstar `**` matches zero or more path segments; `*` matches within a segment; brace expansion is not supported.", "diff_contains": "The unified diff (added or modified lines) of this PR contains the literal string. Use only with stable token forms — decorator names, package names, function calls.", @@ -30,7 +30,7 @@ }, "action": "run_shipgate", "rationale": "MCP exports declare a tool surface; changes need a tool-use readiness check.", - "command": "shipgate verify --preview --json" + "command": "agents-shipgate verify --preview --json" }, { "id": "TRIGGER-OPENAPI-SPEC-CHANGED", @@ -47,7 +47,7 @@ }, "action": "run_shipgate", "rationale": "OpenAPI specs define HTTP-tool surfaces; scope coverage and side-effect classification depend on them.", - "command": "shipgate verify --preview --json" + "command": "agents-shipgate verify --preview --json" }, { "id": "TRIGGER-STATIC-TOOL-INVENTORY-CHANGED", @@ -93,7 +93,7 @@ }, "action": "run_shipgate", "rationale": "Codex plugin packages and marketplaces are static release surfaces; plugin metadata, skills, apps, MCP server declarations, and hooks need a readiness check.", - "command": "shipgate verify --preview --json" + "command": "agents-shipgate verify --preview --json" }, { "id": "TRIGGER-N8N-WORKFLOW-CHANGED", @@ -230,7 +230,7 @@ }, "actions": { "force_run": "Propose Shipgate unconditionally. Overrides `skip_shipgate` rules — used when the repo has explicitly opted in (e.g. existing `shipgate.yaml`) and every PR should be checked.", - "run_shipgate": "Propose `shipgate verify --preview --json` as the next step; if preview says the repo needs configuration, use supporting setup commands before the full verifier. Does NOT win over `skip_shipgate` — a docs-only PR that incidentally mentions a tool decorator stays skipped.", + "run_shipgate": "Propose `agents-shipgate verify --preview --json` as the next step; if preview says the repo needs configuration, use supporting setup commands before the full verifier. Does NOT win over `skip_shipgate` — a docs-only PR that incidentally mentions a tool decorator stays skipped.", "skip_shipgate": "Do not propose Shipgate. Beats `run_shipgate` (but loses to `force_run`). Recommend other appropriate checks for the PR.", "dry_run": "Advisory: `run_shipgate` stays false but `dry_run_recommended` is true in the evaluator output. Callers may propose a non-mutating scan; never propose `init --write` based on `dry_run` alone." }, diff --git a/examples/github-actions/12-host-grant-drift.yml b/examples/github-actions/12-host-grant-drift.yml index 9ee17b1f..64fb92d1 100644 --- a/examples/github-actions/12-host-grant-drift.yml +++ b/examples/github-actions/12-host-grant-drift.yml @@ -10,7 +10,7 @@ # # One-time setup (committed by a human after review): # -# agents-shipgate audit --host --save-baseline +# shipgate audit --host --save-baseline # git add .agents-shipgate/host-grants.json && git commit # # After reviewing a legitimate drift, re-acknowledge the new state with @@ -42,7 +42,7 @@ jobs: - name: Compare host grants against the acknowledged baseline run: | - agents-shipgate audit --host --drift --fail-on-drift + shipgate audit --host --drift --fail-on-drift # Exit 20 on drift fails the job; the step log contains the # one-page drift report with expansion signals. For machine # consumption add --json and upload the payload as an artifact. diff --git a/llms-full.txt b/llms-full.txt index 18adff66..be65a3fa 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -987,7 +987,7 @@ Verify the installed CLI contract locally before relying on hard-coded docs: agents-shipgate contract --json ``` -Runtime contract v8 also exposes the local agent command spec: +Runtime contract v9 also exposes the local agent command spec: `primary_commands{}`, `commands{}`, `default_paths{}`, `artifacts{}`, `agent_read_order[]`, `verifier_read_order[]`, `merge_verdicts[]`, `release_decisions[]`, `do_not_auto_assert[]`, `verifier_schema_version`, @@ -998,15 +998,17 @@ Runtime contract v8 also exposes the local agent command spec: `host_grants_inventory_schema_version`, `agent_interface_operations[]`, `exit_code_policy`, `mcp_tools[]`, and the legacy `agent_result_*` fields retained for older protocol consumers. `primary_commands{}` is the prominent -entry surface and contains only `shipgate check`, `shipgate verify`, and -`shipgate audit --host` flows; `commands{}` is compatibility/supporting -metadata. +entry surface and contains only `shipgate check`, `agents-shipgate verify`, and +`shipgate audit --host` flows; `commands{}` is compatibility/supporting metadata +and retains local verify commands for older consumers. +The short `shipgate verify` alias remains invokable for compatibility, but it is +not the promoted PR-gate spelling in `primary_commands{}`. Downstream repos generated with `init --agent-instructions=default` get the minimal local copy at `.shipgate/agent-contract.json`. - Latest release: `v1.0.0a1` (see [pyproject.toml](../pyproject.toml) for the in-tree version) -- Runtime contract: `8` +- Runtime contract: `9` - Current report schema: `0.27` — [`docs/report-schema.v0.27.json`](report-schema.v0.27.json) - Current packet schema: `0.7` — [`docs/packet-schema.v0.7.json`](packet-schema.v0.7.json) - Current verifier schema: `0.1` — [`docs/verifier-schema.v0.1.json`](verifier-schema.v0.1.json) diff --git a/plugins/agents-shipgate/skills/agents-shipgate/SKILL.md b/plugins/agents-shipgate/skills/agents-shipgate/SKILL.md index 16230781..7a584ebf 100644 --- a/plugins/agents-shipgate/skills/agents-shipgate/SKILL.md +++ b/plugins/agents-shipgate/skills/agents-shipgate/SKILL.md @@ -1,6 +1,6 @@ --- name: agents-shipgate -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. +description: Use when the user wants to run the prominent Agents Shipgate flows — `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host` — for AI agent capability changes, PR release readiness, or coding-agent host grants. --- # Agents Shipgate @@ -15,28 +15,28 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali 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: "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. +3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `contract_version: "9"` 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`, plan to run `shipgate verify` before completion and route trust-root review to a human when the verifier requires it. +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 `agents-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: "8"` or newer; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`. +- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `contract_version: "9"` 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. -- 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`. +- 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`. +- Unconfigured repo or uncertain relevance: run `agents-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 `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. +- Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision. +- Do not self-approve trust-root changes; when `agents-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`. diff --git a/plugins/agents-shipgate/skills/agents-shipgate/references/recipes.md b/plugins/agents-shipgate/skills/agents-shipgate/references/recipes.md index 9bf13480..edb8f164 100644 --- a/plugins/agents-shipgate/skills/agents-shipgate/references/recipes.md +++ b/plugins/agents-shipgate/skills/agents-shipgate/references/recipes.md @@ -1,7 +1,7 @@ # Agents Shipgate Recipes Use these recipes after the `agents-shipgate` skill triggers. The prominent -flows are `shipgate check`, `shipgate verify`, and `shipgate audit --host`. +flows are `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`. Supporting commands remain callable, but should not be the first thing an agent recommends. @@ -16,7 +16,7 @@ agents-shipgate --version agents-shipgate contract --json ``` -Require `agents-shipgate contract --json` to report `contract_version: "8"` or +Require `agents-shipgate contract --json` to report `contract_version: "9"` or newer. If it is missing or stale, ask the user to install or upgrade: ```bash @@ -24,7 +24,7 @@ pipx install agents-shipgate pipx upgrade agents-shipgate ``` -Do not report the task complete until the CLI exists and reports contract v8 or +Do not report the task complete until the CLI exists and reports contract v9 or newer. Local boundary checks emit `shipgate.codex_boundary_result/v1`; legacy `agent_result_v1` fixtures are retained only for older protocol integrations. @@ -47,7 +47,7 @@ surface, prompts, policies, permissions, Shipgate CI, or other protected release surfaces. ```bash -AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify \ +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \ --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` @@ -58,7 +58,7 @@ 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 shipgate verify --preview --json +AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify --preview --json ``` Read `agents-shipgate-reports/agent-handoff.json` first. Lead with @@ -87,7 +87,7 @@ For drift checks against an acknowledged baseline, use the same flow with ## Supporting Setup And Repair -If `shipgate verify --preview --json` says the repo needs configuration, the +If `agents-shipgate verify --preview --json` says the repo needs configuration, the supporting setup commands remain available: ```bash @@ -110,7 +110,7 @@ overwriting it. 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 +5. Re-run `agents-shipgate verify` and report the new merge verdict, release decision, blocker count, and review-item count. For one finding: diff --git a/prompts/add-shipgate-to-repo.md b/prompts/add-shipgate-to-repo.md index 9d5007a6..b2b7ee06 100644 --- a/prompts/add-shipgate-to-repo.md +++ b/prompts/add-shipgate-to-repo.md @@ -5,11 +5,11 @@ You are working in a repo that may contain an AI agent — likely one of: an MCP Your job is to drive the first-adoption helper flow end-to-end in one tool-using turn, which adds the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. Ongoing -agent-related PRs should use `shipgate verify` after this adoption step. +agent-related PRs should use `agents-shipgate verify` after this adoption step. ## Your task -1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v8 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: +1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v9 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: ```bash SG="uvx agents-shipgate@1.0.0a1" # uv: ephemeral, always the pinned build # or: SG="pipx run agents-shipgate==1.0.0a1" @@ -20,8 +20,8 @@ agent-related PRs should use `shipgate verify` after this adoption step. If you would rather install onto `PATH`, pin the floor and **fail loudly when it resolves older** — a plain `pipx install agents-shipgate` is a no-op when an older build already exists — then set `SG=agents-shipgate`: ```bash python -m pip install -U --pre agents-shipgate - agents-shipgate contract --json # STOP if this reports contract_version < 8 - re-run pinned via uvx agents-shipgate@1.0.0a1 - SG=agents-shipgate # only after the line above confirms contract v8+ + agents-shipgate contract --json # STOP if this reports contract_version < 9 - re-run pinned via uvx agents-shipgate@1.0.0a1 + SG=agents-shipgate # only after the line above confirms contract v9+ ``` 2. **Sanity-check the install** before touching the user's code: diff --git a/prompts/decide-shipgate-relevance.md b/prompts/decide-shipgate-relevance.md index 1ba20ab9..00cf0ef2 100644 --- a/prompts/decide-shipgate-relevance.md +++ b/prompts/decide-shipgate-relevance.md @@ -73,8 +73,8 @@ the rules to the changed file list. zero-install** runner so a stale copy already on `PATH` can't answer — `uvx agents-shipgate@1.0.0a1 verify --preview --json` (or `pipx run agents-shipgate==1.0.0a1 ...`). Only fall back to a bare - `shipgate verify --preview --json` once `agents-shipgate --version` - confirms contract v8 or newer. Then follow + `agents-shipgate verify --preview --json` once `agents-shipgate --version` + confirms contract v9 or newer. Then follow [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md) for the first-adoption helper flow, or point the user at the GitHub Action (`ThreeMoonsLab/agents-shipgate@v1.0.0a1`) if they prefer CI. diff --git a/prompts/verify-agent-diff.md b/prompts/verify-agent-diff.md index 20bbcb2d..18a77ff4 100644 --- a/prompts/verify-agent-diff.md +++ b/prompts/verify-agent-diff.md @@ -13,7 +13,7 @@ work is complete. 2. **Use verify preview only when relevance or setup is unclear.** ```bash - shipgate verify --preview --json + agents-shipgate verify --preview --json ``` Preview is a lightweight verify entry point: no manifest required, no scan, exit 0. It tells you whether to configure Shipgate, skip, or run the full @@ -30,12 +30,12 @@ work is complete. For local uncommitted work, omit `--head` and omit `--base` so the checked-out working tree is scanned, including uncommitted edits: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json ``` For committed PR or CI verification, pass the head ref explicitly: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` `verify` never fetches. If you pass `--base` and that ref is missing, @@ -73,8 +73,8 @@ work is complete. ## What NOT to do -- Do not claim the diff is verified until `shipgate verify` has run or - `shipgate verify --preview --json` has returned a clear skip verdict. +- Do not claim the diff is verified until `agents-shipgate verify` has run or + `agents-shipgate verify --preview --json` has returned a clear skip verdict. - Do not claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or `human_review_required` unless the user explicitly accepts human review. diff --git a/scripts/generate_schemas.py b/scripts/generate_schemas.py index c97da20e..9fa502c4 100644 --- a/scripts/generate_schemas.py +++ b/scripts/generate_schemas.py @@ -1601,7 +1601,7 @@ def build_host_grants_inventory_schema() -> tuple[Path, str]: schema["$schema"] = "https://json-schema.org/draft/2020-12/schema" schema["title"] = f"Agents Shipgate Host Grants Inventory v{minor}" schema["description"] = ( - "JSON Schema for agents-shipgate audit --host --json. The inventory " + "JSON Schema for shipgate audit --host --json. The inventory " "summarizes local coding-agent host grants and does not gate releases." ) target = DOCS / f"host-grants-inventory-schema.v{minor}.json" diff --git a/skills/agents-shipgate/SKILL.md b/skills/agents-shipgate/SKILL.md index 16acee78..4c6af9e5 100644 --- a/skills/agents-shipgate/SKILL.md +++ b/skills/agents-shipgate/SKILL.md @@ -1,6 +1,6 @@ --- name: agents-shipgate -description: Run prominent Agents Shipgate flows when a change touches what an AI agent can do: `shipgate check`, `shipgate verify`, or `shipgate audit --host`. Use after adding or modifying MCP servers or tools, tool/function definitions (@tool, @function_tool), OpenAPI specs that describe agent tools, agent prompts, permission scopes, approval or confirmation policies, agent CI workflows, or shipgate.yaml — and before creating a PR for any such change. Also use to verify agent-related PRs, fix or triage Shipgate findings, add Shipgate to CI, or interpret Shipgate verifier/report artifacts. Triggers on phrases like "add shipgate", "verify this agent PR", "merge verdict", "release readiness for my agent", "tool-use readiness", "shipgate check", "shipgate verify", "audit host grants", "shipgate.yaml", "agents-shipgate-reports/verifier.json", "agents-shipgate-reports/report.json", "fix shipgate finding". +description: Run prominent Agents Shipgate flows when a change touches what an AI agent can do: `shipgate check`, `agents-shipgate verify`, or `shipgate audit --host`. Use after adding or modifying MCP servers or tools, tool/function definitions (@tool, @function_tool), OpenAPI specs that describe agent tools, agent prompts, permission scopes, approval or confirmation policies, agent CI workflows, or shipgate.yaml — and before creating a PR for any such change. Also use to verify agent-related PRs, fix or triage Shipgate findings, add Shipgate to CI, or interpret Shipgate verifier/report artifacts. Triggers on phrases like "add shipgate", "verify this agent PR", "merge verdict", "release readiness for my agent", "tool-use readiness", "shipgate check", "agents-shipgate verify", "audit host grants", "shipgate.yaml", "agents-shipgate-reports/verifier.json", "agents-shipgate-reports/report.json", "fix shipgate finding". --- # agents-shipgate skill @@ -53,8 +53,8 @@ Always: `fix_task`, and `capability_review.top_changes`. Then parse `agents-shipgate-reports/report.json.release_decision.decision`; it is the release gate. -4. 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. -5. Before finishing an agent-related diff, run `shipgate check --agent claude-code --workspace . --format codex-boundary-json`. For committed PR/CI verification, run `shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. `verify` never fetches. For host grants, run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`. +4. 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 `agents-shipgate verify` before completion and route trust-root review to a human when the verifier requires it. +5. Before finishing an agent-related diff, run `shipgate check --agent claude-code --workspace . --format codex-boundary-json`. For committed PR/CI verification, run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. `verify` never fetches. For host grants, run `shipgate audit --host --json --out agents-shipgate-reports/host-grants.json`. 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 make those trust-root edits release-visible. 7. Confirm with the user before any command that writes files (`init --write`, `baseline save`). @@ -86,7 +86,7 @@ For non-GitHub CI (GitLab, CircleCI, Jenkins, Azure Pipelines, Buildkite, Bitbuc ## Boundaries (do not violate) -- Do not claim a finding is fixed without re-running `shipgate verify` and reporting the new merge verdict and release decision. +- Do not claim a finding is fixed without re-running `agents-shipgate verify` and reporting the new merge verdict and release decision. - Do not silently suppress findings — `checks.ignore` requires a `reason` and the manifest validator rejects empty reasons. - Do not commit `agents-shipgate-reports/` — it's regenerated each run; add it to `.gitignore`. - Do not run `agents-shipgate baseline save` until the user has reviewed the initial findings; baselining ratchets in noise. diff --git a/skills/agents-shipgate/prompts/add-shipgate-to-repo.md b/skills/agents-shipgate/prompts/add-shipgate-to-repo.md index 9d5007a6..b2b7ee06 100644 --- a/skills/agents-shipgate/prompts/add-shipgate-to-repo.md +++ b/skills/agents-shipgate/prompts/add-shipgate-to-repo.md @@ -5,11 +5,11 @@ You are working in a repo that may contain an AI agent — likely one of: an MCP Your job is to drive the first-adoption helper flow end-to-end in one tool-using turn, which adds the deterministic merge gate for AI-generated agent capability changes — a local-first, static Tool-Use Readiness review. Ongoing -agent-related PRs should use `shipgate verify` after this adoption step. +agent-related PRs should use `agents-shipgate verify` after this adoption step. ## Your task -1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v8 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: +1. **Install the tool - pin the version so a stale build can't shadow it.** This flow uses the current verifier, agent-handoff, primary-command, and Codex-boundary contracts and requires **contract v9 or newer**; an older copy lingering on `PATH` may lack the command or schema fields this prompt expects. Prefer a **pinned, zero-install** runner that fetches the exact version every time instead of trusting whatever is already on `PATH`. **Pin it into one variable and use that for every step below**, so no single command can fall through to a stale binary: ```bash SG="uvx agents-shipgate@1.0.0a1" # uv: ephemeral, always the pinned build # or: SG="pipx run agents-shipgate==1.0.0a1" @@ -20,8 +20,8 @@ agent-related PRs should use `shipgate verify` after this adoption step. If you would rather install onto `PATH`, pin the floor and **fail loudly when it resolves older** — a plain `pipx install agents-shipgate` is a no-op when an older build already exists — then set `SG=agents-shipgate`: ```bash python -m pip install -U --pre agents-shipgate - agents-shipgate contract --json # STOP if this reports contract_version < 8 - re-run pinned via uvx agents-shipgate@1.0.0a1 - SG=agents-shipgate # only after the line above confirms contract v8+ + agents-shipgate contract --json # STOP if this reports contract_version < 9 - re-run pinned via uvx agents-shipgate@1.0.0a1 + SG=agents-shipgate # only after the line above confirms contract v9+ ``` 2. **Sanity-check the install** before touching the user's code: diff --git a/skills/agents-shipgate/prompts/decide-shipgate-relevance.md b/skills/agents-shipgate/prompts/decide-shipgate-relevance.md index 1ba20ab9..00cf0ef2 100644 --- a/skills/agents-shipgate/prompts/decide-shipgate-relevance.md +++ b/skills/agents-shipgate/prompts/decide-shipgate-relevance.md @@ -73,8 +73,8 @@ the rules to the changed file list. zero-install** runner so a stale copy already on `PATH` can't answer — `uvx agents-shipgate@1.0.0a1 verify --preview --json` (or `pipx run agents-shipgate==1.0.0a1 ...`). Only fall back to a bare - `shipgate verify --preview --json` once `agents-shipgate --version` - confirms contract v8 or newer. Then follow + `agents-shipgate verify --preview --json` once `agents-shipgate --version` + confirms contract v9 or newer. Then follow [`prompts/add-shipgate-to-repo.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/prompts/add-shipgate-to-repo.md) for the first-adoption helper flow, or point the user at the GitHub Action (`ThreeMoonsLab/agents-shipgate@v1.0.0a1`) if they prefer CI. diff --git a/skills/agents-shipgate/prompts/verify-agent-diff.md b/skills/agents-shipgate/prompts/verify-agent-diff.md index 20bbcb2d..18a77ff4 100644 --- a/skills/agents-shipgate/prompts/verify-agent-diff.md +++ b/skills/agents-shipgate/prompts/verify-agent-diff.md @@ -13,7 +13,7 @@ work is complete. 2. **Use verify preview only when relevance or setup is unclear.** ```bash - shipgate verify --preview --json + agents-shipgate verify --preview --json ``` Preview is a lightweight verify entry point: no manifest required, no scan, exit 0. It tells you whether to configure Shipgate, skip, or run the full @@ -30,12 +30,12 @@ work is complete. For local uncommitted work, omit `--head` and omit `--base` so the checked-out working tree is scanned, including uncommitted edits: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --ci-mode advisory --format json ``` For committed PR or CI verification, pass the head ref explicitly: ```bash - shipgate verify --workspace . --config shipgate.yaml \ + agents-shipgate verify --workspace . --config shipgate.yaml \ --base origin/main --head HEAD --ci-mode advisory --format json ``` `verify` never fetches. If you pass `--base` and that ref is missing, @@ -73,8 +73,8 @@ work is complete. ## What NOT to do -- Do not claim the diff is verified until `shipgate verify` has run or - `shipgate verify --preview --json` has returned a clear skip verdict. +- Do not claim the diff is verified until `agents-shipgate verify` has run or + `agents-shipgate verify --preview --json` has returned a clear skip verdict. - Do not claim completion when `merge_verdict` is `blocked`, `insufficient_evidence`, or `human_review_required` unless the user explicitly accepts human review. diff --git a/src/agents_shipgate/cli/diagnostics.py b/src/agents_shipgate/cli/diagnostics.py index c0476151..4c515ece 100644 --- a/src/agents_shipgate/cli/diagnostics.py +++ b/src/agents_shipgate/cli/diagnostics.py @@ -71,7 +71,7 @@ def diagnose_missing_manifest(workspace: Path) -> list[Diagnostic]: next_actions=[ NextAction( kind="command", - command=f"shipgate verify --workspace {workspace_q} --preview --json", + command=f"agents-shipgate verify --workspace {workspace_q} --preview --json", why=( "Ask the verify flow whether this workspace needs " "Shipgate configuration before writing a manifest." diff --git a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py index bd6ddf1e..85a356f9 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/agents_md.py @@ -31,9 +31,9 @@ def render_block() -> str: shipgate check --agent codex --workspace . --format codex-boundary-json shipgate check --agent claude-code --workspace . --format codex-boundary-json shipgate check --agent cursor --workspace . --format codex-boundary-json -shipgate verify --workspace . --config shipgate.yaml \\ +agents-shipgate verify --workspace . --config shipgate.yaml \\ --ci-mode advisory --format json -shipgate verify --workspace . --config shipgate.yaml \\ +agents-shipgate verify --workspace . --config shipgate.yaml \\ --base origin/main --head HEAD --ci-mode advisory --format json shipgate audit --host --json --out agents-shipgate-reports/host-grants.json ``` @@ -49,7 +49,7 @@ def render_block() -> str: repair and rerun the command. If `human_review.required=true` or `must_stop=true`, stop and surface the JSON result to a human. -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read diff --git a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py index 7c26b4b7..6fdbc578 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/claude_md.py @@ -23,9 +23,9 @@ def render_block() -> str: ```bash shipgate check --agent claude-code --workspace . --format codex-boundary-json -shipgate verify --workspace . --config shipgate.yaml \\ +agents-shipgate verify --workspace . --config shipgate.yaml \\ --ci-mode advisory --format json -shipgate verify --workspace . --config shipgate.yaml \\ +agents-shipgate verify --workspace . --config shipgate.yaml \\ --base origin/main --head HEAD --ci-mode advisory --format json shipgate audit --host --json --out agents-shipgate-reports/host-grants.json ``` @@ -41,7 +41,7 @@ def render_block() -> str: repair and rerun the command. If `human_review.required=true` or `must_stop=true`, stop and surface the JSON result to a human. -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read diff --git a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py index fc3f55bd..759ef409 100644 --- a/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py +++ b/src/agents_shipgate/cli/discovery/agent_instructions/renderers/cursor.py @@ -68,9 +68,9 @@ def render_file() -> str: For local verification, run: - shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json + agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json -For committed PR/CI verification, run `shipgate verify --base +For committed PR/CI verification, run `agents-shipgate verify --base origin/main --head HEAD --json` after making the base ref available; it never fetches. Read `agents-shipgate-reports/agent-handoff.json` first for `gate.merge_verdict`, `gate.can_merge_without_human`, and `controller`; then read diff --git a/src/agents_shipgate/cli/first_look.py b/src/agents_shipgate/cli/first_look.py index 99a53cc7..faffef04 100644 --- a/src/agents_shipgate/cli/first_look.py +++ b/src/agents_shipgate/cli/first_look.py @@ -5,12 +5,14 @@ a repo classification, a host-grant summary, and the single best next command. It requires no ``shipgate.yaml`` and writes nothing. -This is a router, not a gate — the gates remain ``check`` (local diff) and -``verify`` (committed PR). It composes three existing read-only surfaces -(``detect``, the agent-native boundary ``check``, and ``audit --host``) so -it adds no new analysis and no new public command. Every step is wrapped so -a partial environment (no git, unreadable config) degrades to a shorter -summary rather than an error: a first look must never hard-fail. +This is a router, not a gate — the promoted gates remain ``shipgate check`` +(fast local agent loop), ``agents-shipgate verify`` (committed PR), and +``shipgate audit --host`` (zero-config permission inventory). It composes three +existing read-only surfaces (``detect``, the agent-native boundary ``check``, +and ``audit --host``) so it adds no new analysis and no new public command. +Every step is wrapped so a partial environment (no git, unreadable config) +degrades to a shorter summary rather than an error: a first look must never +hard-fail. """ from __future__ import annotations @@ -143,10 +145,10 @@ def _next_command(has_manifest: bool, has_agent_surface: bool, has_host: bool) - """The single highest-value next command for this repo's state.""" if has_manifest: - return "Next: `shipgate verify --base origin/main --head HEAD` to gate your PR." + return "Next: `agents-shipgate verify --base origin/main --head HEAD` to gate your PR." if has_agent_surface: return ( - "Next: `shipgate verify --preview --json` to confirm the setup path, " + "Next: `agents-shipgate verify --preview --json` to confirm the setup path, " "or `shipgate check` to check your working tree now." ) if has_host: diff --git a/src/agents_shipgate/cli/host_audit.py b/src/agents_shipgate/cli/host_audit.py index 7133de43..62591b56 100644 --- a/src/agents_shipgate/cli/host_audit.py +++ b/src/agents_shipgate/cli/host_audit.py @@ -1,4 +1,4 @@ -"""``agents-shipgate audit --host`` CLI wrapper.""" +"""``shipgate audit --host`` CLI wrapper.""" from __future__ import annotations diff --git a/src/agents_shipgate/cli/install_hooks.py b/src/agents_shipgate/cli/install_hooks.py index e195cf28..725cacf0 100644 --- a/src/agents_shipgate/cli/install_hooks.py +++ b/src/agents_shipgate/cli/install_hooks.py @@ -600,7 +600,7 @@ def _trigger(payload: dict[str, Any], root: Path, args: argparse.Namespace) -> i if (root / args.config).is_file(): command = _manual_verify_command(args, root=root) else: - command = "AGENTS_SHIPGATE_AGENT_MODE=1 shipgate verify --preview --json" + command = "AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify --preview --json" return _emit_context( "PostToolUse", ( @@ -629,7 +629,7 @@ def _verify(payload: dict[str, Any], root: Path, args: argparse.Namespace) -> in if trigger and trigger.get("should_run") and not stop_hook_active: return _emit_stop_block( "Agents Shipgate trigger matched, but no shipgate.yaml exists. " - "Before finishing, run `shipgate verify --preview --json`, " + "Before finishing, run `agents-shipgate verify --preview --json`, " "initialize the manifest if relevant, then verify." ) return 0 diff --git a/src/agents_shipgate/cli/main.py b/src/agents_shipgate/cli/main.py index 73ca437e..2277f837 100644 --- a/src/agents_shipgate/cli/main.py +++ b/src/agents_shipgate/cli/main.py @@ -60,7 +60,7 @@ )(_detect_command) app.command( "check", - help="Run the local Codex boundary check and emit codex boundary JSON.", + help="Run the fast local agent loop and emit codex boundary JSON.", )(_check_command) app.command( "preflight", @@ -126,8 +126,8 @@ app.command( "verify", help=( - "Run the canonical ongoing-PR verifier: trigger evaluation, optional " - "base scan, and one authoritative head scan." + "Run the canonical PR gate: trigger evaluation, optional base scan, " + "and one authoritative head scan." ), )(_verify_command) app.command( @@ -150,7 +150,7 @@ app.command( "audit", help=( - "Run `shipgate audit --host` for zero-config host-grant audits. " + "Run `shipgate audit --host` for a zero-config permission inventory. " "`audit --host` inventories " "coding-agent host grants (MCP servers, permission rules, hooks, " "workflow scopes) without requiring shipgate.yaml; `--save-baseline` " @@ -185,7 +185,7 @@ def _mcp_serve_command() -> None: _register_doctor.register(app) _register_baseline.register(app) # Visibility policy: root --help shows only the prominent flows: -# `shipgate check`, `shipgate verify`, and `shipgate audit --host`. +# `shipgate check`, `agents-shipgate verify`, and `shipgate audit --host`. # Supporting/compatibility commands stay fully invokable and documented # through their direct --help; hiding is presentation, not deprecation. # README fixture demos remain runnable, but are not a root-help flow. diff --git a/src/agents_shipgate/cli/verify/orchestrator.py b/src/agents_shipgate/cli/verify/orchestrator.py index 104e34f4..c0b51b0e 100644 --- a/src/agents_shipgate/cli/verify/orchestrator.py +++ b/src/agents_shipgate/cli/verify/orchestrator.py @@ -120,7 +120,7 @@ def run_verify( ) message = ( f"Shipgate config not found at {_display_path(config_path, git_root)}. " - "Correct --config, or run `shipgate verify --preview --json` before " + "Correct --config, or run `agents-shipgate verify --preview --json` before " "initializing." ) verifier = _build_verifier( @@ -145,7 +145,7 @@ def run_verify( first_next_action_override=VerifierNextAction( actor="coding_agent", kind="command", - command="shipgate verify --preview --json", + command="agents-shipgate verify --preview --json", why=( "Shipgate could not find the configured manifest; run verify " "preview, then correct --config or initialize shipgate.yaml." @@ -1409,7 +1409,7 @@ def _preview_verify_command( out: Path | None, ) -> str: parts = [ - "shipgate", + "agents-shipgate", "verify", "--workspace", str(workspace), diff --git a/src/agents_shipgate/core/codex_boundary.py b/src/agents_shipgate/core/codex_boundary.py index 5a2a99a6..ba24f336 100644 --- a/src/agents_shipgate/core/codex_boundary.py +++ b/src/agents_shipgate/core/codex_boundary.py @@ -1376,8 +1376,8 @@ def _risk_for(violations: list[AgentResultViolatedRule]) -> AgentResultRiskLevel # capability delta and owns release_decision.decision. Preview stays inside the # verify flow for unconfigured workspaces; adopted repos with undeclared # surfaces still use detect for suggested_sources. -_VERIFY_COMMAND = "shipgate verify --json" -_VERIFY_PREVIEW_COMMAND = "shipgate verify --preview --json" +_VERIFY_COMMAND = "agents-shipgate verify --json" +_VERIFY_PREVIEW_COMMAND = "agents-shipgate verify --preview --json" _DETECT_COMMAND = "shipgate detect --workspace . --json" diff --git a/src/agents_shipgate/core/host_grants.py b/src/agents_shipgate/core/host_grants.py index 1b48e69d..41aa991c 100644 --- a/src/agents_shipgate/core/host_grants.py +++ b/src/agents_shipgate/core/host_grants.py @@ -358,17 +358,17 @@ def load_host_grants_baseline(path: Path) -> dict[str, Any]: except OSError as exc: raise ValueError( f"No host-grants baseline at {path} ({exc}). Record one first: " - "agents-shipgate audit --host --save-baseline" + "shipgate audit --host --save-baseline" ) from exc except json.JSONDecodeError as exc: raise ValueError( f"Host-grants baseline {path} is not valid JSON ({exc}). " - "Re-record it: agents-shipgate audit --host --save-baseline" + "Re-record it: shipgate audit --host --save-baseline" ) from exc if not isinstance(data, dict): raise ValueError( f"Host-grants baseline {path} must be a JSON object. " - "Re-record it: agents-shipgate audit --host --save-baseline" + "Re-record it: shipgate audit --host --save-baseline" ) version = data.get("host_grants_schema_version") if version != HOST_GRANTS_SCHEMA_VERSION: @@ -381,7 +381,7 @@ def load_host_grants_baseline(path: Path) -> dict[str, Any]: if not isinstance(inventory, dict): raise ValueError( f"Host-grants baseline {path} is missing its inventory. " - "Re-record it: agents-shipgate audit --host --save-baseline" + "Re-record it: shipgate audit --host --save-baseline" ) for category, identity in _GRANT_CATEGORIES: entries = inventory.get(category, []) @@ -389,7 +389,7 @@ def load_host_grants_baseline(path: Path) -> dict[str, Any]: raise ValueError( f"Host-grants baseline {path} has a malformed {category!r} " "category (expected a list). Re-record it: " - "agents-shipgate audit --host --save-baseline" + "shipgate audit --host --save-baseline" ) expected = str if identity is None else dict for entry in entries: @@ -397,7 +397,7 @@ def load_host_grants_baseline(path: Path) -> dict[str, Any]: raise ValueError( f"Host-grants baseline {path} has a malformed entry in " f"{category!r} (expected {expected.__name__} entries). " - "Re-record it: agents-shipgate audit --host --save-baseline" + "Re-record it: shipgate audit --host --save-baseline" ) stored_sha = data.get("inventory_sha256") recomputed_sha = host_grants_sha256(normalized_host_grants(inventory)) @@ -407,7 +407,7 @@ def load_host_grants_baseline(path: Path) -> dict[str, Any]: f"stored inventory_sha256 {stored_sha!r} does not match the " f"inventory content ({recomputed_sha}). The file was hand-edited " "or corrupted. After a human reviews the current grants, " - "re-record it: agents-shipgate audit --host --save-baseline" + "re-record it: shipgate audit --host --save-baseline" ) return data @@ -591,7 +591,7 @@ def render_host_drift_markdown(payload: dict[str, Any]) -> str: lines.append("---") lines.append( "After a human reviews this drift, re-acknowledge the new state: " - "`agents-shipgate audit --host --save-baseline`. Do not re-save to " + "`shipgate audit --host --save-baseline`. Do not re-save to " "silence drift you have not reviewed." ) return "\n".join(lines) + "\n" diff --git a/src/agents_shipgate/core/preflight.py b/src/agents_shipgate/core/preflight.py index 5a0bc266..d1232a94 100644 --- a/src/agents_shipgate/core/preflight.py +++ b/src/agents_shipgate/core/preflight.py @@ -704,9 +704,9 @@ def signals_for_host_grant_drift( reason=reason, recommendation=( "Route the host-grant drift to a human. After review, " - "re-acknowledge with `agents-shipgate audit --host --save-baseline`." + "re-acknowledge with `shipgate audit --host --save-baseline`." ), - related_command="agents-shipgate audit --host --drift --fail-on-drift", + related_command="shipgate audit --host --drift --fail-on-drift", ) ] diff --git a/src/agents_shipgate/schemas/contract.py b/src/agents_shipgate/schemas/contract.py index 9460ab69..3914b9f5 100644 --- a/src/agents_shipgate/schemas/contract.py +++ b/src/agents_shipgate/schemas/contract.py @@ -33,7 +33,7 @@ from agents_shipgate.schemas.verifier import VerifierArtifact from agents_shipgate.schemas.verify_run import VERIFY_RUN_SCHEMA_VERSION -CONTRACT_VERSION: Literal["8"] = "8" +CONTRACT_VERSION: Literal["9"] = "9" GATING_SIGNAL: Literal["release_decision.decision"] = "release_decision.decision" AGENT_RESULT_SCHEMA_VERSION: Literal["agent_result_v1"] = "agent_result_v1" AGENT_RESULT_SCHEMA_PATH: Literal["docs/agent-result-schema.v1.json"] = ( @@ -173,7 +173,7 @@ "registry_summary": "agents-shipgate registry summary --registry .agents-shipgate/registry.jsonl --json", "registry_verify": "agents-shipgate registry verify --registry .agents-shipgate/registry.jsonl --json", "host_audit": ( - "agents-shipgate audit --host --json --out " + "shipgate audit --host --json --out " "agents-shipgate-reports/host-grants.json" ), "contract": "agents-shipgate contract --json", @@ -188,12 +188,8 @@ "check_cursor": ( "shipgate check --agent cursor --workspace . --format codex-boundary-json" ), - "verify_local": ( - "shipgate verify --workspace . --config shipgate.yaml " - "--ci-mode advisory --json" - ), "verify_pr": ( - "shipgate verify --workspace . --config shipgate.yaml " + "agents-shipgate verify --workspace . --config shipgate.yaml " "--base origin/main --head HEAD --ci-mode advisory --json" ), "host_audit": ( diff --git a/src/agents_shipgate/schemas/host_grants.py b/src/agents_shipgate/schemas/host_grants.py index e204bc01..aa1ccb94 100644 --- a/src/agents_shipgate/schemas/host_grants.py +++ b/src/agents_shipgate/schemas/host_grants.py @@ -47,7 +47,7 @@ class HostWorkflowGrantV1(BaseModel): class HostGrantsInventoryV1(BaseModel): - """Versioned host-grant inventory emitted by ``agents-shipgate audit --host``.""" + """Versioned host-grant inventory emitted by ``shipgate audit --host``.""" model_config = ConfigDict(extra="forbid") diff --git a/src/agents_shipgate/triggers.py b/src/agents_shipgate/triggers.py index a1cbe20b..d93b9b63 100644 --- a/src/agents_shipgate/triggers.py +++ b/src/agents_shipgate/triggers.py @@ -3,8 +3,8 @@ The catalog (``docs/triggers.json``) is the machine-readable mirror of the AGENTS.md trigger table. A coding agent that has not yet adopted Shipgate can fetch ``triggers.json`` and apply the rules against a PR diff or repo -state to decide whether to propose ``shipgate verify --preview --json`` as the next -step, without parsing prose. +state to decide whether to propose ``agents-shipgate verify --preview --json`` as +the next step, without parsing prose. This module is the canonical evaluator. It exists primarily so: @@ -152,7 +152,7 @@ def _next_action( if manifest_present: return { "kind": "command", - "command": "shipgate verify --base origin/main --head HEAD --json", + "command": "agents-shipgate verify --base origin/main --head HEAD --json", "why": ( "This change affects an agent tool or release-policy " "surface; verify whether the PR can merge." @@ -171,7 +171,7 @@ def _next_action( } if dry_run_recommended: command = ( - "shipgate verify --base origin/main --head HEAD " + "agents-shipgate verify --base origin/main --head HEAD " "--ci-mode advisory --json" if manifest_present else default_command @@ -420,7 +420,7 @@ def evaluate( manifest_present=manifest_present, matched=matched, default_command=triggers.get( - "default_command", "shipgate verify --preview --json" + "default_command", "agents-shipgate verify --preview --json" ), rationale=rationale, ) diff --git a/tests/golden/agent_protocol/claude-code-block-stop.json b/tests/golden/agent_protocol/claude-code-block-stop.json index ea0c8e9f..6e0d5fa6 100644 --- a/tests/golden/agent_protocol/claude-code-block-stop.json +++ b/tests/golden/agent_protocol/claude-code-block-stop.json @@ -124,7 +124,7 @@ "diff_tokens": [], "next_action": { "kind": "command", - "command": "shipgate verify --preview --json", + "command": "agents-shipgate verify --preview --json", "why": "This change looks agent-related; start with verify preview and adopt Shipgate if the preview routes setup." } }, diff --git a/tests/golden/agent_protocol/codex-block-stop.json b/tests/golden/agent_protocol/codex-block-stop.json index 1f12609b..cfb1050e 100644 --- a/tests/golden/agent_protocol/codex-block-stop.json +++ b/tests/golden/agent_protocol/codex-block-stop.json @@ -124,7 +124,7 @@ "diff_tokens": [], "next_action": { "kind": "command", - "command": "shipgate verify --preview --json", + "command": "agents-shipgate verify --preview --json", "why": "This change looks agent-related; start with verify preview and adopt Shipgate if the preview routes setup." } }, diff --git a/tests/golden/agent_protocol/cursor-block-stop.json b/tests/golden/agent_protocol/cursor-block-stop.json index aebda392..c3a495f5 100644 --- a/tests/golden/agent_protocol/cursor-block-stop.json +++ b/tests/golden/agent_protocol/cursor-block-stop.json @@ -124,7 +124,7 @@ "diff_tokens": [], "next_action": { "kind": "command", - "command": "shipgate verify --preview --json", + "command": "agents-shipgate verify --preview --json", "why": "This change looks agent-related; start with verify preview and adopt Shipgate if the preview routes setup." } }, diff --git a/tests/golden/codex_boundary_result/github_action_removed.json b/tests/golden/codex_boundary_result/github_action_removed.json index 0d38f639..26e78d77 100644 --- a/tests/golden/codex_boundary_result/github_action_removed.json +++ b/tests/golden/codex_boundary_result/github_action_removed.json @@ -131,7 +131,7 @@ "diff_tokens": [], "next_action": { "kind": "command", - "command": "shipgate verify --preview --json", + "command": "agents-shipgate verify --preview --json", "why": "This change looks agent-related; start with verify preview and adopt Shipgate if the preview routes setup." } }, diff --git a/tests/test_agent_instructions_apply.py b/tests/test_agent_instructions_apply.py index e1e0bd72..c5a3e096 100644 --- a/tests/test_agent_instructions_apply.py +++ b/tests/test_agent_instructions_apply.py @@ -190,8 +190,10 @@ def test_claude_command_current_file_matches_renderer() -> None: def test_local_contract_renderer_has_required_fields() -> None: payload = json.loads(render_local_contract_file()) assert payload["schema_version"] == "2" - assert payload["contract_version"] == "8" - assert payload["primary_commands"]["verify_local"].startswith("shipgate verify") + assert payload["contract_version"] == "9" + assert "verify_local" not in payload["primary_commands"] + assert payload["primary_commands"]["verify_pr"].startswith("agents-shipgate verify") + assert payload["commands"]["verify_local"].startswith("agents-shipgate verify") assert payload["primary_commands"]["host_audit"].startswith("shipgate audit --host") assert payload["agent_handoff_schema_version"] == "shipgate.agent_handoff/v1" assert payload["agent_handoff_artifact"] == "agents-shipgate-reports/agent-handoff.json" diff --git a/tests/test_agent_instructions_renderers.py b/tests/test_agent_instructions_renderers.py index ae191874..b68d7b15 100644 --- a/tests/test_agent_instructions_renderers.py +++ b/tests/test_agent_instructions_renderers.py @@ -45,16 +45,16 @@ REPO_ROOT = Path(__file__).resolve().parent.parent EXPECTED_CLAUDE_CODE_SKILL_RENDER_SHA256 = { ".claude/skills/agents-shipgate/SKILL.md": ( - "5062b30ee84b3871c6532ce0e6c7ad41ac0203a1bd29be51ac3342e01fcd09cb" + "6031a900efa636677786ceda881af0aa4630500683ee1845f4dd1439fdbe2e70" ), ".claude/skills/agents-shipgate/ci-recipes/advisory-pr-comment.yml": ( "99b2acfbd9dfc6653a6bbee268b83f1e2d4297829636eba662d9f4ad6fa35423" ), ".claude/skills/agents-shipgate/prompts/add-shipgate-to-repo.md": ( - "47f370db7820b665de6fcc61968c735e0dfb88715b9f666795687b73f0034dce" + "7a414bb492538d05b1b76c526e8672f24bcb1a824c368c643e3be0ee48b08274" ), ".claude/skills/agents-shipgate/prompts/decide-shipgate-relevance.md": ( - "8d1540095101cd7ff3aec4ba998ced5c135cdbdb71637ad0c4e5d42fc6ec9ab7" + "80771e3f3d3ae35329929ec567cc121cf1342bd27edbd50cf9f97f29cab703ef" ), ".claude/skills/agents-shipgate/prompts/explain-finding-to-user.md": ( "18031ed870b3c937a2996173820639ef441afe0a45e8171f16468826cd389829" @@ -75,12 +75,12 @@ "992122338eba26ae5d8056b9658117d718a6b477b9928c2a438dd449b5effb68" ), ".claude/skills/agents-shipgate/prompts/verify-agent-diff.md": ( - "96a7eeeaf96df428575ad4758b48cdd6458c491bb067a99f73b06e6fd268c36d" + "e72ab77443032dbbef9a7236ad0d859a291cb764e30c9eb37f8f1b037c0751b4" ), } EXPECTED_CODEX_SKILL_RENDER_SHA256 = { ".agents/skills/agents-shipgate/SKILL.md": ( - "49c04766323dd3bec0b94f39ab236b84d0a6adc4e47bbaded70bc0f8f166f779" + "8d5080cf5c4c429a6920b466fe5c3415d89fec3434760b549883ee9a458a48ac" ), ".agents/skills/agents-shipgate/agents/openai.yaml": ( "aa511e933ff663dcd1e0d2af3da2a7101206ce2bb1bb98c4dae801bb3f4e42ef" @@ -89,7 +89,7 @@ "16894ce679eb55c69213070775cb265f0775ad7ff1cd08091a5c57627950871b" ), ".agents/skills/agents-shipgate/references/recipes.md": ( - "64cfd980d399f24995008eeca4d196a6efd224edd01e108543ec11aeb291d085" + "d8b393e61aef853105a47630b9cbfd404378b6c9e1bbed6028b357b4e38fc72c" ), ".agents/skills/agents-shipgate/references/report-reading.md": ( "6d2848f3436f6e246bf553e6cf061c990888d6ff39eb82fec9a41f291b2e94fe" @@ -164,9 +164,11 @@ def test_local_contract_renderer_exposes_agent_operational_fields() -> None: payload = json.loads(render_local_contract_file()) assert payload["schema_version"] == "2" assert payload["agents_shipgate_version"] - assert payload["contract_version"] == "8" - assert payload["primary_commands"]["verify_pr"].startswith("shipgate verify") + assert payload["contract_version"] == "9" + assert payload["primary_commands"]["verify_pr"].startswith("agents-shipgate verify") assert payload["primary_commands"]["host_audit"].startswith("shipgate audit --host") + assert "verify_local" not in payload["primary_commands"] + assert payload["commands"]["verify_local"].startswith("agents-shipgate verify") assert payload["verifier_schema_version"] == "0.1" assert payload["verify_run_schema_version"] == "shipgate.verify_run/v1" assert payload["agent_handoff_schema_version"] == "shipgate.agent_handoff/v1" @@ -326,7 +328,7 @@ def test_claude_code_skill_has_required_surfaces() -> None: assert "release_decision.decision" in skill assert "AGENTS_SHIPGATE_AGENT_MODE=1" in skill assert "Do not claim a finding is fixed" in skill - assert "shipgate verify" in skill + assert "agents-shipgate verify" in skill def test_codex_skill_has_required_surfaces() -> None: @@ -340,12 +342,12 @@ def test_codex_skill_has_required_surfaces() -> None: assert "release_decision.decision" in skill assert "AGENTS_SHIPGATE_AGENT_MODE=1" in skill assert "Do not auto-assert approval" in skill - assert "shipgate verify" in skill + assert "agents-shipgate verify" in skill assert "agents-shipgate --version" in skill assert "agents-shipgate contract --json" in skill assert "install or upgrade `agents-shipgate`" in skill recipes = files[".agents/skills/agents-shipgate/references/recipes.md"] - assert 'contract_version: "8"' in recipes + assert 'contract_version: "9"' in recipes assert "shipgate.codex_boundary_result/v1" in recipes @@ -368,7 +370,7 @@ def test_claude_md_is_self_contained_no_dangling_link() -> None: dangling reference to AGENTS.md.""" out = render_claude_md() # Self-contained means it lists its own commands and report.json contract. - assert "shipgate verify --workspace . --config shipgate.yaml" in out + assert "agents-shipgate verify --workspace . --config shipgate.yaml" in out assert "shipgate audit --host" in out assert "merge_verdict" in out assert "release_decision.decision" in out diff --git a/tests/test_cli.py b/tests/test_cli.py index 3a5900e9..062c3578 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -176,7 +176,7 @@ def test_cli_missing_config_prints_next_action_hint(tmp_path, monkeypatch): assert "Config error:" in result.output # The human reader gets the same rank-1 recovery step that agent # mode emits as JSON — a cold user must not hit a dead end. - assert "next: shipgate verify" in result.output + assert "next: agents-shipgate verify" in result.output def test_cli_change_me_placeholder_error_routes_to_manifest_edit(tmp_path, monkeypatch): @@ -1158,7 +1158,7 @@ def test_missing_manifest_recovery_uses_config_workspace(tmp_path, monkeypatch): payloads = _stderr_json_lines(result.output) assert payloads, result.output rank_one = payloads[-1]["next_actions"][0] - assert "shipgate verify --workspace" in rank_one["command"] + assert "agents-shipgate verify --workspace" in rank_one["command"] # Routes recovery to the config's parent directory, not the foreign cwd. assert str(tmp_path / "repo") in rank_one["command"] assert str(foreign_cwd) not in rank_one["command"] @@ -1268,7 +1268,7 @@ def test_missing_manifest_command_quotes_workspace_with_spaces(tmp_path, monkeyp import shlex parts = shlex.split(command) - assert parts[:2] == ["shipgate", "verify"] + assert parts[:2] == ["agents-shipgate", "verify"] assert "--workspace" in parts workspace_arg = parts[parts.index("--workspace") + 1] assert workspace_arg == str(spaced) diff --git a/tests/test_codex_boundary_check.py b/tests/test_codex_boundary_check.py index 7beb1050..3f104117 100644 --- a/tests/test_codex_boundary_check.py +++ b/tests/test_codex_boundary_check.py @@ -105,7 +105,7 @@ def test_declared_tool_surface_change_warns_and_routes_to_verify(tmp_path: Path) assert payload["completion_allowed"] is True assert payload["must_stop"] is False assert payload["first_next_action"]["kind"] == "warn" - assert payload["first_next_action"]["command"].startswith("shipgate verify") + assert payload["first_next_action"]["command"].startswith("agents-shipgate verify") assert any(d["code"] == "capability_change_requires_verify" for d in payload["diagnostics"]) assert any(t["step"] == "coverage" for t in payload["trace"]) @@ -152,7 +152,7 @@ def test_check_warns_when_manifest_declares_changed_tool_source(tmp_path: Path) policy=None, ) assert result.decision == "warn" - assert result.first_next_action.command.startswith("shipgate verify") + assert result.first_next_action.command.startswith("agents-shipgate verify") def _write_manifest(tmp_path: Path, tool_sources: str) -> None: @@ -189,7 +189,7 @@ def test_check_warns_on_change_under_declared_directory_source(tmp_path: Path) - policy=None, ) assert result.decision == "warn" - assert result.first_next_action.command.startswith("shipgate verify") + assert result.first_next_action.command.startswith("agents-shipgate verify") def test_check_does_not_warn_on_broad_root_source(tmp_path: Path) -> None: @@ -288,7 +288,7 @@ def test_undeclared_surface_warns_and_routes_to_detect_when_manifest_present( assert any(d["code"] == "undeclared_capability_surface" for d in payload["diagnostics"]) assert any(t["step"] == "coverage" for t in payload["trace"]) assert payload["suggested_fixes"][0] == "shipgate detect --workspace . --json" - assert any(fix.startswith("shipgate verify") for fix in payload["suggested_fixes"]) + assert any(fix.startswith("agents-shipgate verify") for fix in payload["suggested_fixes"]) def test_mixed_declared_and_undeclared_routes_to_detect_when_manifest_present( @@ -326,7 +326,7 @@ def test_no_manifest_capability_add_via_check_warns_and_routes_to_verify_preview policy=None, ) assert result.decision == "warn" - assert result.first_next_action.command.startswith("shipgate verify --preview") + assert result.first_next_action.command.startswith("agents-shipgate verify --preview") def test_capability_add_to_undeclared_surface_warns_when_manifest_declares_other( diff --git a/tests/test_diagnostics.py b/tests/test_diagnostics.py index f365e211..35c856a9 100644 --- a/tests/test_diagnostics.py +++ b/tests/test_diagnostics.py @@ -142,7 +142,7 @@ def test_emits_missing_manifest_diagnostic(self, tmp_path: Path) -> None: assert [d.id for d in diags] == [DIAG_MISSING_MANIFEST] assert diags[0].severity == "block" assert diags[0].next_actions[0].kind == "command" - assert "shipgate verify" in diags[0].next_actions[0].command + assert "agents-shipgate verify" in diags[0].next_actions[0].command def test_command_quotes_workspace_with_spaces( self, tmp_path: Path diff --git a/tests/test_first_look.py b/tests/test_first_look.py index fae417c6..a1834e06 100644 --- a/tests/test_first_look.py +++ b/tests/test_first_look.py @@ -54,7 +54,7 @@ def test_first_look_routes_to_verify_when_manifest_present( assert result.exit_code == 0, result.output assert "shipgate.yaml present" in result.output - assert "shipgate verify" in result.output + assert "agents-shipgate verify" in result.output def test_first_look_reports_host_grants( diff --git a/tests/test_local_contract.py b/tests/test_local_contract.py index 5a9d2d27..a3d8aca6 100644 --- a/tests/test_local_contract.py +++ b/tests/test_local_contract.py @@ -55,10 +55,11 @@ def test_local_agent_contract_is_minimal_agent_operational_payload() -> None: "check_codex", "check_claude_code", "check_cursor", - "verify_local", "verify_pr", "host_audit", } + assert payload["primary_commands"]["verify_pr"].startswith("agents-shipgate verify") + assert payload["commands"]["verify_local"].startswith("agents-shipgate verify") assert payload["commands"]["install_agent_workflow"] == ( "agents-shipgate init --workspace . --write --ci --agent-instructions=default --json" ) diff --git a/tests/test_public_surface_contract.py b/tests/test_public_surface_contract.py index 42bd913b..a2e35351 100644 --- a/tests/test_public_surface_contract.py +++ b/tests/test_public_surface_contract.py @@ -1447,12 +1447,17 @@ def test_well_known_seo_geo_positioning_fields_are_pinned(): "check_codex", "check_claude_code", "check_cursor", - "verify_local", "verify_pr", "host_audit", } - assert all(command.startswith("shipgate ") for command in primary_commands.values()) + assert primary_commands["check_codex"].startswith("shipgate check ") + assert primary_commands["check_claude_code"].startswith("shipgate check ") + assert primary_commands["check_cursor"].startswith("shipgate check ") + assert primary_commands["verify_pr"].startswith("agents-shipgate verify ") + assert primary_commands["host_audit"].startswith("shipgate audit --host") + assert "verify_local" not in primary_commands assert commands.get("preview") == "agents-shipgate verify --preview --json" + assert commands.get("verify_local", "").startswith("agents-shipgate verify ") assert commands.get("install_ai_coding_workflow") == ( "agents-shipgate init --workspace . --write --ci --agent-instructions=default --json" ) @@ -1564,15 +1569,14 @@ def test_prominent_surfaces_only_promote_check_verify_and_host_audit(): **well_known["primary_commands"], **contract["primary_commands"], }.items(): - assert command.startswith("shipgate "), f"{name} should use the shipgate alias" - assert any( - command.startswith(prefix) - for prefix in ( - "shipgate check ", - "shipgate verify ", - "shipgate audit --host", - ) - ), f"{name} is not one of the prominent flows: {command}" + expected_prefixes = ( + "shipgate check ", + "agents-shipgate verify ", + "shipgate audit --host", + ) + assert any(command.startswith(prefix) for prefix in expected_prefixes), ( + f"{name} is not one of the prominent flows: {command}" + ) for forbidden_command in forbidden: assert forbidden_command not in command diff --git a/tests/test_schema_boundaries.py b/tests/test_schema_boundaries.py index 2977ad8e..dffd0dd4 100644 --- a/tests/test_schema_boundaries.py +++ b/tests/test_schema_boundaries.py @@ -275,7 +275,7 @@ def test_representative_schema_payloads_keep_wire_fields() -> None: } assert ContractPayload( - contract_version="8", + contract_version="9", cli_version="0.0.0", report_schema_version="0.27", packet_schema_version="0.7", @@ -304,7 +304,7 @@ def test_representative_schema_payloads_keep_wire_fields() -> None: agent_interface_operations=["verify_pr"], exit_code_policy={"3": "input parse or missing artifact error"}, mcp_tools=["shipgate.handoff"], - primary_commands={"verify_local": "shipgate verify --json"}, + primary_commands={"verify_pr": "agents-shipgate verify --json"}, commands={"preview": "agents-shipgate verify --preview --json"}, default_paths={"manifest": "shipgate.yaml"}, artifacts={ @@ -324,7 +324,7 @@ def test_representative_schema_payloads_keep_wire_fields() -> None: release_decisions=["passed", "blocked"], do_not_auto_assert=["approval"], ).model_dump(mode="json") == { - "contract_version": "8", + "contract_version": "9", "cli_version": "0.0.0", "report_schema_version": "0.27", "packet_schema_version": "0.7", @@ -353,7 +353,7 @@ def test_representative_schema_payloads_keep_wire_fields() -> None: "agent_interface_operations": ["verify_pr"], "exit_code_policy": {"3": "input parse or missing artifact error"}, "mcp_tools": ["shipgate.handoff"], - "primary_commands": {"verify_local": "shipgate verify --json"}, + "primary_commands": {"verify_pr": "agents-shipgate verify --json"}, "commands": {"preview": "agents-shipgate verify --preview --json"}, "default_paths": {"manifest": "shipgate.yaml"}, "artifacts": { diff --git a/tests/test_trigger_command.py b/tests/test_trigger_command.py index 3ba1c71c..6022a1e0 100644 --- a/tests/test_trigger_command.py +++ b/tests/test_trigger_command.py @@ -21,7 +21,7 @@ def _catalog(when: dict) -> dict: """A minimal one-rule catalog for predicate-isolation tests.""" return { "schema_version": "test", - "default_command": "shipgate verify --preview --json", + "default_command": "agents-shipgate verify --preview --json", "rules": [ {"id": "R", "action": "run_shipgate", "when": when, "rationale": ""} ], @@ -213,7 +213,7 @@ def test_next_action_points_at_verify_preview_when_not_adopted(): res = evaluate(paths=["tools/my_mcp.json"]) # run rule fires, no manifest assert res["should_run"] is True assert res["next_action"]["kind"] == "command" - assert res["next_action"]["command"] == "shipgate verify --preview --json" + assert res["next_action"]["command"] == "agents-shipgate verify --preview --json" def test_stop_conditions_not_evaluated_without_detect_result(): diff --git a/tests/test_verify.py b/tests/test_verify.py index 7a249252..2b83acf7 100644 --- a/tests/test_verify.py +++ b/tests/test_verify.py @@ -137,7 +137,7 @@ def test_verify_missing_config_docs_only_diff_fails_closed(tmp_path: Path) -> No assert payload["human_review"]["required"] is True assert "verify --preview --json" in payload["human_review"]["why"] assert payload["first_next_action"]["command"] == ( - "shipgate verify --preview --json" + "agents-shipgate verify --preview --json" ) assert (out_dir / "verifier.json").is_file() assert (out_dir / "verify-run.json").is_file() @@ -1352,7 +1352,7 @@ def test_verify_preview_configured_repo_preserves_exact_verify_args(tmp_path: Pa payload = json.loads(result.output) assert payload["mode"] == "preview" assert payload["first_next_action"]["command"] == ( - f"shipgate verify --workspace {repo} --config shipgate.yaml " + f"agents-shipgate verify --workspace {repo} --config shipgate.yaml " f"--base origin/main --head HEAD --out {out} --ci-mode advisory --json" ) From 23b708df3fa55a5e4c86bfa206247f9b8233e661 Mon Sep 17 00:00:00 2001 From: Pengfei Hu Date: Sun, 28 Jun 2026 22:51:32 -0700 Subject: [PATCH 2/2] Align host audit command reference --- AGENTS.md | 2 +- llms-full.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 95c78078..ca69c863 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -526,7 +526,7 @@ Newer commands (stable intent, flags may still evolve): | Command | Purpose | |---|---| -| `agents-shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. | +| `shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. | | `agents-shipgate mcp-serve` | Local read-only stdio MCP server (`[mcp]` extra) exposing `shipgate.check`, `shipgate.preflight`, `shipgate.explain`, `shipgate.capabilities`, and `shipgate.handoff`. See [`docs/mcp-server.md`](docs/mcp-server.md). | | `agents-shipgate org status` | Local organization governance projection over exception hygiene, policy-pack pins, host-grant drift, and registry readiness; `--json` available and governance violations exit `20`. | | `agents-shipgate registry` | `ingest --attestation ` / `query` / `report --bypass` — local capability-release ledger over attestations. | diff --git a/llms-full.txt b/llms-full.txt index be65a3fa..67f1ee00 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -551,7 +551,7 @@ Newer commands (stable intent, flags may still evolve): | Command | Purpose | |---|---| -| `agents-shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. | +| `shipgate audit --host` | Zero-config, read-only inventory of coding-agent host grants (MCP servers, permission rules, hooks, workflow scopes); `--json` available. Works without `shipgate.yaml`. | | `agents-shipgate mcp-serve` | Local read-only stdio MCP server (`[mcp]` extra) exposing `shipgate.check`, `shipgate.preflight`, `shipgate.explain`, `shipgate.capabilities`, and `shipgate.handoff`. See [`docs/mcp-server.md`](docs/mcp-server.md). | | `agents-shipgate org status` | Local organization governance projection over exception hygiene, policy-pack pins, host-grant drift, and registry readiness; `--json` available and governance violations exit `20`. | | `agents-shipgate registry` | `ingest --attestation ` / `query` / `report --bypass` — local capability-release ledger over attestations. |