Implement proactive preflight planning

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

@@ -1,3 +1,3 @@
 ---
 name: agents-shipgate
 description: Use when the user wants to add or run Agents Shipgate — the deterministic merge gate for AI-generated agent capability changes — on an AI agent's tool surface; review or prepare a tool-using agent for release; scan MCP, OpenAPI, OpenAI Agents SDK, Anthropic, Google ADK, LangChain/LangGraph, CrewAI, OpenAI API, Codex plugin, or n8n tool artifacts; add advisory CI; or interpret, fix, triage, suppress, or explain a Shipgate finding.
@@ -19,15 +19,15 @@
 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 agent-json` and read the stdout `agent_result_v1` object. Switch on `decision`; follow `first_next_action`, `repair`, and `human_review`.
-7. Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules, policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run `agents-shipgate preflight --workspace . --json` or pass the planned paths with `--changed-files`. If `requires_human_review` is true or `first_next_action.actor` is `human`, stop and route to a human.
+7. Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules, policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run `agents-shipgate preflight --workspace . --plan - --json` with a `PreflightPlanV1` object. Legacy `--changed-files`/`--diff` shorthands remain available. If `requires_human_review` is true or `first_next_action.actor` is `human`, stop and route to a human.
 8. For full PR verification, read `agents-shipgate-reports/agent-result.json` first, then `verifier.json` and `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` and `agents-shipgate --version`. Continue only when the installed CLI is `>=0.13.0`; if it is missing or stale, ask the user to run `pipx install agents-shipgate` followed by `pipx upgrade agents-shipgate`, or `python -m pip install -U "agents-shipgate>=0.13"` when `pipx` is unavailable.
-- Protected-surface preflight: run `agents-shipgate preflight --workspace . --json` before touching trust roots; add `--changed-files changed.txt` or `--diff pr.diff` when you have concrete planned paths.
+- Protected-surface preflight: run `agents-shipgate preflight --workspace . --plan - --json` before touching trust roots; include `changed_files[]` or `diff_text` in the plan when you have concrete planned paths.
 - Agent-native check: run `shipgate check --agent codex --workspace . --format agent-json`; read only the JSON result for continue/repair/stop routing.
 - First adoption: run `agents-shipgate detect --workspace . --json`, then follow `references/recipes.md`.
 - Agent-related PR/CI diff: run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. For local uncommitted work, omit `--base`/`--head` so the working tree is scanned. `verify` never fetches.

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

@@ -1,3 +1,3 @@
 # Agents Shipgate Recipes
 
 Use these recipes after the `agents-shipgate` skill triggers.
@@ -46,11 +46,11 @@
 plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run:
 
 ```bash
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . --json
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . --plan - --json
 ```
 
-If you already have a path list or local diff, ask preflight about it before
-editing:
+Pass a `PreflightPlanV1` object on stdin. If you already have a path list or
+local diff and need legacy shorthands, ask preflight about them before editing:
 
 ```bash
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . \
@@ -106,7 +106,7 @@
 ```bash
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate trigger \
   --workspace . --base origin/main --head HEAD --json
-AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . --json
+AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate preflight --workspace . --plan - --json
 AGENTS_SHIPGATE_AGENT_MODE=1 agents-shipgate verify \
   --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD --ci-mode advisory --format json

.cursor/rules/agents-shipgate.mdc

@@ -1,3 +1,3 @@
 ---
 description: Run Agents Shipgate as the deterministic merge gate for AI-generated agent capability changes.
 globs:
@@ -35,12 +35,15 @@
 permissions, approval policies, or release gates, run Agents Shipgate.
 Default to advisory verification while adopting the gate.
 
+Before protected edits, run preflight and read `PreflightResultV2`:
+
+  agents-shipgate preflight --workspace . --plan - --json
+
 For local agent control, run:
 
-  agents-shipgate preflight --json
   shipgate check --agent cursor --workspace . --format agent-json
 
-Read the stdout JSON only. It is `agent_result_v1`; switch on `decision`,
+Read the check stdout JSON only. It is `agent_result_v1`; switch on `decision`,
 `completion_allowed`, and `must_stop`, then follow `first_next_action`,
 `human_review`, `repair`, and `policy`. Do not infer a decision from prose.
 
@@ -53,8 +56,10 @@
 Before editing `shipgate.yaml`, Shipgate CI, AGENTS/CLAUDE/Cursor rules,
 policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex
 plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run
-`agents-shipgate preflight --json` or `agents-shipgate preflight
---changed-files changed.txt --json`. If `requires_human_review` is `true` or
+`agents-shipgate preflight --workspace . --plan - --json` with a
+`PreflightPlanV1` object. Legacy shorthands such as
+`agents-shipgate preflight --changed-files changed.txt --json` remain available.
+If `requires_human_review` is `true` or
 `first_next_action.actor` is `human`, stop and route the change to a human.
 
 For committed PR/CI verification, run `agents-shipgate verify --base

.well-known/agents-shipgate.json

@@ -77,7 +77,7 @@
     "agent_check_codex": "shipgate check --agent codex --workspace . --format agent-json",
     "agent_check_claude_code": "shipgate check --agent claude-code --workspace . --format agent-json",
     "agent_check_cursor": "shipgate check --agent cursor --workspace . --format agent-json",
-    "preflight": "agents-shipgate preflight --workspace . --config shipgate.yaml --json",
+    "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_pr": "agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json",
@@ -119,7 +119,7 @@
   },
   "capability_lock_schema_version": "0.2",
   "capability_lock_diff_schema_version": "0.3",
-  "preflight_schema_version": "0.1",
+  "preflight_schema_version": "0.2",
   "attestation_schema_version": "0.2",
   "capability_standard_version": "0.1",
   "governance_benchmark_catalog_schema_version": "0.2",
@@ -174,7 +174,7 @@
     "agent_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-result-schema.v1.json",
     "verifier": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verifier-schema.v0.1.json",
     "packet": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/packet-schema.v0.7.json",
-    "preflight": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/preflight-schema.v0.1.json",
+    "preflight": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/preflight-schema.v0.2.json",
     "capability_lock": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-schema.v0.2.json",
     "capability_lock_diff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-diff-schema.v0.3.json",
     "governance_benchmark_catalog": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/governance-benchmark-catalog-schema.v0.2.json",

AGENTS.md

@@ -1,3 +1,3 @@
 # Agents Shipgate · Agent Instructions
 
 Authoritative instructions for AI coding agents (Claude Code, Codex, Cursor, Aider) working **with** this repository or a project that uses Agents Shipgate.
@@ -92,13 +92,16 @@
 planner first:
 
 ```bash
-agents-shipgate preflight --json
+agents-shipgate preflight --workspace . --plan - --json
 agents-shipgate preflight --changed-files changed.txt --json
 agents-shipgate preflight --capability-request request.json --json
 ```
 
 If `requires_human_review` is `true` or `first_next_action.actor` is `human`,
-stop and route the change to a human. Protected surfaces include
+stop and route the change to a human. The plan form accepts `changed_files[]`,
+`diff_text`, `capability_requests[]`, `host_permission_requests[]`, and
+`context.{agent,task}`; prefer it whenever the agent can describe the planned
+change as one JSON object. Protected surfaces include
 `shipgate.yaml`, `.github/workflows/agents-shipgate.yml`,
 `AGENTS.md`/`CLAUDE.md`/Cursor rules, policy packs, baselines, waivers,
 suppressions, Codex hooks/config, Codex plugin manifests, `.mcp.json`,
@@ -199,7 +202,7 @@
 
 ```bash
 agents-shipgate detect --workspace . --json
-agents-shipgate preflight --workspace . --json
+agents-shipgate preflight --workspace . --plan - --json
 agents-shipgate init --workspace . --write --json
 agents-shipgate scan -c shipgate.yaml                    # already produces report.json
 agents-shipgate apply-patches --from agents-shipgate-reports/report.json --json

README.md

@@ -244,7 +244,7 @@ agents-shipgate verify --preview --json
 If Shipgate is relevant, run:
 agents-shipgate init --workspace . --write --ci --agent-instructions=default --json
 Before editing protected surfaces, run:
-agents-shipgate preflight --workspace . --json
+agents-shipgate preflight --workspace . --plan - --json
 For PR/reviewer evidence, run:
 agents-shipgate verify --workspace . --config shipgate.yaml \
   --base origin/main --head HEAD --ci-mode advisory --format json
@@ -505,7 +505,7 @@ Agents Shipgate is designed to be agent-friendly. If you're a coding agent (Clau
 - **`agents-shipgate install-hooks --target claude-code --write`** — deterministic Claude Code hooks: a PreToolUse trust-root guard, a cheap trigger check after `Edit|Write|MultiEdit`, and a full `verify` at `Stop`, so the gate runs even when instruction files lose attention on long sessions. See [`docs/agents/use-with-claude-code.md`](docs/agents/use-with-claude-code.md#hooks-the-deterministic-path-recommended).
 - **`agents-shipgate mcp-serve`** (`[mcp]` extra) — read-only stdio MCP server exposing `shipgate.check`, `shipgate.preflight`, `shipgate.explain`, and `shipgate.capabilities` for agents without comfortable shell access. It is static-only and not a general MCP permission broker. See [`docs/mcp-server.md`](docs/mcp-server.md).
 - **[`docs/ai-search-summary.md`](docs/ai-search-summary.md)** — human-readable summary for AI search, answer engines, and coding agents
-- **[`docs/manifest-v0.1.json`](docs/manifest-v0.1.json)** + **[`docs/report-schema.v0.26.json`](docs/report-schema.v0.26.json)** + **[`docs/preflight-schema.v0.1.json`](docs/preflight-schema.v0.1.json)** — JSON Schemas for live editor validation and agent routing (current; emitted reports carry `report_schema_version: "0.26"`, preflight emits `preflight_schema_version: "0.1"`). v0.26 adds structured evidence gaps (`release_decision.evidence_coverage.evidence_gaps[]`) plus the advisory `suggested-inventory.json` skeleton; gate behavior is unchanged. Read `release_decision.decision` for release gating, `agent_summary.first_recommended_action` for the next agent step, and `reviewer_summary.first_recommended_surface` for the human-review entry point. The per-version additive history lives in [`docs/agent-contract-current.md`](docs/agent-contract-current.md) and [`STABILITY.md`](STABILITY.md).
+- **[`docs/manifest-v0.1.json`](docs/manifest-v0.1.json)** + **[`docs/report-schema.v0.26.json`](docs/report-schema.v0.26.json)** + **[`docs/preflight-schema.v0.2.json`](docs/preflight-schema.v0.2.json)** — JSON Schemas for live editor validation and agent routing (current; emitted reports carry `report_schema_version: "0.26"`, preflight emits `preflight_schema_version: "0.2"`). v0.26 adds structured evidence gaps (`release_decision.evidence_coverage.evidence_gaps[]`) plus the advisory `suggested-inventory.json` skeleton; gate behavior is unchanged. Read `release_decision.decision` for release gating, `agent_summary.first_recommended_action` for the next agent step, and `reviewer_summary.first_recommended_surface` for the human-review entry point. The per-version additive history lives in [`docs/agent-contract-current.md`](docs/agent-contract-current.md) and [`STABILITY.md`](STABILITY.md).
 - **[`docs/capability-lock-schema.v0.2.json`](docs/capability-lock-schema.v0.2.json)** + **[`docs/capability-lock-diff-schema.v0.3.json`](docs/capability-lock-diff-schema.v0.3.json)** — stable schemas for the static capability envelope and semantic diff emitted by `agents-shipgate capability` and, in PR workflows, by `agents-shipgate verify`; non-gating and separate from `report.json`.
 - **[`docs/attestation-schema.v0.2.json`](docs/attestation-schema.v0.2.json)** — deterministic local attestation schema; v0.2 binds verifier artifacts plus capability lock/diff hashes when present.
 - **[`docs/governance-benchmark-catalog-schema.v0.2.json`](docs/governance-benchmark-catalog-schema.v0.2.json)** + **[`docs/governance-benchmark-result-schema.v0.2.json`](docs/governance-benchmark-result-schema.v0.2.json)** — stable schemas for the research benchmark catalog and deterministic result artifact.

STABILITY.md

@@ -131,13 +131,15 @@ Signal paths use dotted notation; `[]` denotes an array field.
 
 ### Preflight JSON fields (stable)
 
-`agents-shipgate preflight --json` is a proactive, static-only planning surface
-for coding agents. It does not inspect runtime tool calls, start an MCP server,
+`agents-shipgate preflight --workspace . --plan - --json` is the primary
+proactive, static-only planning surface for coding agents. Legacy shorthands
+such as `--changed-files`, `--diff`, and `--capability-request` remain
+compatible. Preflight does not inspect runtime tool calls, start an MCP server,
 or claim merge safety. `release_decision.decision` remains the only release gate.
 
-The stable top-level fields in `PreflightResultV1` are:
+The stable top-level fields in `PreflightResultV2` are:
 
-- `preflight_schema_version` — currently `"0.1"`.
+- `preflight_schema_version` — currently `"0.2"`.
 - `workspace` and `config` — resolved workspace and manifest path context.
 - `protected_surfaces[]` — canonical trust-root surfaces with `kind`, `pattern`,
   `scope_type`, `present`, and `present_paths`.
@@ -156,6 +158,14 @@ The stable top-level fields in `PreflightResultV1` are:
   `--base-preflight` is supplied.
 - `first_next_action` — routing hint for coding-agent vs human next action.
 - `notes[]` — non-gating diagnostics such as missing manifest context.
+- `signals[]` — deterministic rows with `id`, `kind`, `severity`, `actor`,
+  `subject`, `path`, `reason`, `recommendation`, and `related_command`.
+- `requires_verify`, `verification_command`, and `allowed_next_commands[]` —
+  verifier routing hints only; they are not merge verdicts.
+- `plan_summary` — deterministic counts for the supplied plan and resulting
+  signals.
+- `host_grant_drift` — optional host-grant drift payload when a host baseline
+  is present or explicitly supplied.
 
 ### JSON report fields (stable)
 

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

@@ -1,3 +1,3 @@
 ---
 name: agents-shipgate
 description: Run the deterministic merge gate when a change touches what an AI agent can do. 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", "scan my agent", "shipgate scan", "shipgate.yaml", "agents-shipgate-reports/verifier.json", "agents-shipgate-reports/report.json", "fix shipgate finding".
@@ -53,7 +53,7 @@
    `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`, run `agents-shipgate preflight --workspace . --json` or pass planned paths with `--changed-files`. If `requires_human_review` is true or `first_next_action.actor` is `human`, stop and route to a human.
+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`, run `agents-shipgate preflight --workspace . --plan - --json` with a `PreflightPlanV1` object. Legacy `--changed-files`/`--diff` shorthands remain available. If `requires_human_review` is true or `first_next_action.actor` is `human`, stop and route to a human.
 5. Before finishing an agent-related diff, run `shipgate check --agent claude-code --workspace . --format agent-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.
 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`).

adoption-kits/claude-code-skill/prompts/verify-agent-diff.md

@@ -1,3 +1,3 @@
 # Prompt · Verify an agent-related diff
 
 You are reviewing or finishing a change to a tool-using AI agent. Use Agents
@@ -36,9 +36,10 @@
    policy packs, baselines, waivers, suppressions, Codex hooks/config, Codex
    plugin manifests, `.mcp.json`, `.app.json`, or `SKILL.md`, run:
    ```bash
-   agents-shipgate preflight --workspace . --json
+   agents-shipgate preflight --workspace . --plan - --json
    ```
-   If you have changed-file or diff context, use it:
+   Pass a `PreflightPlanV1` object on stdin. If you need legacy shorthands,
+   pass changed-file or diff context directly:
    ```bash
    agents-shipgate preflight --workspace . \
      --changed-files /tmp/shipgate-changed-files.txt \