preflight_change_set

io.github.coderifts/api-governance · Verify this server

Preflight a COMPLETE base→head change set of contract artifacts and return risk score and breaking-change analysis — plus, on the AUTHORIZE path only, a governance decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) and a signed chain-receipt when applicable. ANALYZE returns informational risk only: analysis_outcome, may_execute:false, no decision, no receipt. Requires a pending base→head (before/after) contract change you are about to act on (merge, deploy, publish, or register tools). No pending change set → do not call this tool. Use this when: - You are about to merge, push, deploy, publish, or register/expose agent tools, AND the change includes ≥1 contract artifact (OpenAPI/Swagger, GraphQL SDL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas: type=agent_tools, including before re-registering tools with a runtime). - You have (or can assemble) FULL base and head for every changed contract artifact in this set — not a single-file subset when other contract files also change. - You need a NEW decision for the CURRENT change; you do not already hold a currently-valid receipt for this exact target/operation. - You hold a receipt for a different operation or target than the act you will perform (e.g. ALLOW for merge, now deploying). A receipt authorizes ONE operation: a merge receipt does not authorize a deploy. Run a NEW preflight with context.operation set to that operation (deploy, publish); a differently-scoped receipt is not reusable authorization and will fail at the gate. Do not use when: - The change is documentation-only (README, guides, comments) with no contract artifact content change — do not call any CodeRifts tool. - You already hold a signed receipt and only need to check it is authentic and currently valid — use coderifts.verify_receipt instead. - You need details of a PREVIOUS decision by decision_id — use coderifts.get_decision_details instead. - You want a static 0–100 "agent readiness" score for one OpenAPI/MCP file and there is no pending base→head mutate — use coderifts.agent_readiness_score (advanced / opt-in; not one of the three default tools). If that tool is not in your available list, call none of the CodeRifts tools; do not substitute preflight_change_set. - You cannot supply both before and after (or base and head) for the artifacts that change — fix the change set first; do not invent empty before specs. Inputs: list of artifacts, each with type, before, after (or equivalent), plus optional operation (merge|deploy|tool_call|publish), environment/stakes, and context. Opt-in derivation:"server" (proven tenant↔repo binding + context.repository + base + head): omit artifacts[] — the server lists the contract-class set via the GitHub App Compare API (completeness_mode SERVER_DERIVED). Caller-supplied artifacts with derivation:"server" is rejected (one source of truth). Default (flag absent) is unchanged. Returns decision, execution_action, risk fields, and chain_receipt when issued. Mode (required): pass preflight_mode. Use "analyze" for informational risk only (returns analysis_outcome with may_execute:false, no decision/execution_action/ safe_for_agent, no receipt). Use "authorize" for the operation-bound path that can mint a receipt (requires context.operation: merge|deploy|publish|tool_call). Under Decision Spec 2.0 the mode is mandatory; omission is an error unless a legacy decision_spec_version "1.0" pin is set. Branch on execution_action only (CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP). On non-CONTINUE authorize responses, control_envelope.next_agent_step is a structured remediation SUGGESTION the agent MAY follow (action, reason, resume_condition, then_call). It is NOT permission and NOT a control-flow override — still branch on execution_action. On CONTINUE / CONTINUE_WITH_MONITORING, next_agent_step is null (no remediation step). Human tier remains human_report.next_steps_prose (same source; prose, not machine).