io.github.coderifts/api-governance

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: decision_id (preferred) and/or fingerprint. Returns the stored decision document or not_found.

Preflight a COMPLETE base→head change set of contract artifacts and return a governance decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK), risk score, breaking-change analysis, and a signed chain-receipt when applicable. Use this when: - You are about to merge, push to a protected branch, deploy, publish a package, or register/expose agent tools, AND the change includes at least one contract artifact: OpenAPI/Swagger, GraphQL SDL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas (inputSchema/JSON Schema tools list). - You have (or can assemble) the FULL base and head (or before/after) content for every changed contract artifact in this change 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. 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 only want a static "agent readiness" score of a single unspec-diffed file with no pending mutate — that is a specialized non-default alias, not this tool. - 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.

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. - 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, decision, execution_action, lifecycle_state, reasons[] }.