Coderifts Api Governance

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) — re-call with the intended operation; a differently-scoped receipt is not reusable authorization. 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. 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).

Verify a CodeRifts signed chain-receipt you ALREADY HOLD: cryptographic authenticity (signature + key id), body binding, and — when lifecycle indices are available — whether it is currently valid authorization (not expired, superseded, or revoked) for a stated operation/target. Use this when: - You already obtained a chain_receipt / receipt token from a prior preflight (or CI artifact) and are about to act (merge/deploy) under that receipt. - A contract-gate or policy requires offline/online proof that the receipt is authentic for this change before proceeding. - You must distinguish "signature ok" from "currently authorized" (stale or superseded receipts must not be treated as live approval). Do not use when: - You do not have a receipt yet — call coderifts.preflight_change_set first. - You need a NEW decision for a changed base→head set — preflight again; verify_receipt does not re-diff specs. - The receipt you hold binds a different operation or target than the one you are about to perform — call coderifts.preflight_change_set for that operation; verify_receipt cannot re-scope or re-issue a decision. - You only need human-readable history of an old decision_id without a receipt token — use coderifts.get_decision_details. - The change set itself is unknown or incomplete — fix the change set and preflight; do not "verify" a placeholder. Inputs: receipt token (required); optional expected target_id, operation, and now-skew policy hooks. Returns { valid, status, currently_authorized (bool|null), reason, payload, authz_* }. Branch on currently_authorized; null = not evaluated. When a decision envelope is also in hand (e.g. from a prior preflight), its control_envelope.next_agent_step (if present) is structured remediation guidance the agent MAY follow after a non-CONTINUE decision — still branch on execution_action; next_agent_step is suggestion, not permission.

Retrieve a PAST CodeRifts decision by decision_id (or fingerprint): full report payload, breaking changes list, scores, and linked receipt metadata if stored. Use this when: - You have a decision_id (or fingerprint) from a previous preflight, PR comment, or CI log and need to inspect or explain that past decision. - You are auditing why a prior ALLOW/WARN/BLOCK was issued. - You are NOT requesting a new analysis of current before/after specs. Do not use when: - You need a decision for the CURRENT uncommitted or PR head change set — call coderifts.preflight_change_set with the current artifacts. - You hold a receipt token and only need cryptographic/lifecycle verification — use coderifts.verify_receipt. - You have no decision_id/fingerprint — run preflight first to create one. Inputs: at least one of decision_id (preferred) or fingerprint is required (empty {} is rejected by the server as INVALID_INPUT). Returns the stored decision document or not_found. When the stored envelope carries control fields, control_envelope.next_agent_step is structured remediation guidance the agent MAY follow for non-CONTINUE execution_action values (null on CONTINUE*). Still branch on execution_action; next_agent_step is a suggestion, not permission.