CodeRifts Decision Spec

Current: Decision Spec 2.0 (2026-08) · License: MIT · Schema: coderifts.com/schemas/preflight-response.v2.consumer.json · Manifest: coderifts.com/.well-known/coderifts.json

Preflight modes#

preflight_mode is required on every preflight request (analyze or authorize). A request without it returns 400 with a machine-readable error naming both modes.

Legacy pin (30 days): send decision_spec_version: "1.0" to receive the pre-v2 shape (including soft-default mode and analyze responses that still carried execution vocabulary). Sunset is 2026-09-07T00:00:00Z. After sunset, only the v2 contract remains.

Honest note (risk vs permission): Analyze responses do not carry decision, execution_action, or safe_for_agent. Risk classification is analysis_outcome (closed set: NO_BREAK_DETECTED | BREAKS_DETECTED | ANALYSIS_FAILED) plus risk/impact payload fields. That is not authorization. Permission requires the authorize path and a verified receipt: receipt present and currently_authorized and operation match and fingerprint match and allow-class execution_action. No single field alone permits proceed.

Response shapes#

ANALYZE response (informational — not permission)#

{
  "preflight_mode": "analyze",
  "decision_spec_version": "2.0",
  "analysis_outcome": "BREAKS_DETECTED",
  "authorization_effect": "NONE",
  "may_execute": false,
  "receipt_kind": "NONE",
  "risk_score": 87,
  "breaking_changes": 3,
  "patterns": ["AUTH_SCOPE_REDUCTION", "FIELD_REMOVED", "ENDPOINT_REMOVED"],
  "requires_migration": true,
  "timestamp": "2026-08-08T10:00:00Z"
}

No execution_action, no safe_for_agent, no decision, no chain_receipt. Branch on may_execute / analysis_outcome only for risk handling — never treat this body as a green light to merge, deploy, or call tools.

AUTHORIZE response (operation-bound)#

{
  "preflight_mode": "authorize",
  "decision_spec_version": "2.0",
  "receipt_kind": "operation_authorization",
  "decision": "BLOCK",
  "execution_action": "STOP",
  "safe_for_agent": false,
  "risk_score": 87,
  "breaking_changes": 3,
  "patterns": ["AUTH_SCOPE_REDUCTION", "FIELD_REMOVED"],
  "requires_migration": true,
  "operation": "merge",
  "chain_receipt": "",
  "timestamp": "2026-08-08T10:00:00Z"
}

Branch on execution_action for proceed/halt. Use decision as explanation. A downstream merge/deploy/runtime gate must verify the receipt (conjunctive checks) — possession of execution_action alone is not enough.

Field definitions by mode#

Decision values#

• BLOCK — The change violates a governance rule or exceeds the risk threshold. The requested operation must not proceed through an enforcing path. Agents: do not proceed; the API contract has changed in a way that will break tool calls or workflow steps.
• REQUIRE_APPROVAL — High-risk but does not automatically block. Human approval required before merge. Agents: pause execution and wait for human sign-off.
• WARN — Potentially risky but within policy. Not itself permission: on acting paths, proceed only with a verified receipt that is currently authorized and matches operation, fingerprint and required context.
• ALLOW — No configured blocking signal was detected under the supplied evidence. Not sufficient authorization to execute by itself; on acting paths, proceed only after the associated receipt is currently authorized and matches operation, fingerprint and required context.

safe_for_agent flag (authorize only)#

Prefer branching on execution_action for control flow; treat safe_for_agent as a dashboard/legacy signal. safe_for_agent: false is set when any of these agent-breaking patterns are detected: TOOL_CALLING_SCHEMA_DRIFT, TOOL_RESULT_SHAPE_DRIFT, AGENT_PROTOCOL_DRIFT, WORKFLOW_CHAIN_BREAK, AUTH_DELEGATION_DRIFT, SHARED_STATE_SCHEMA_DRIFT. If safe_for_agent: false, agents must not call the updated API without human review.

Pattern registry (v1.0)#

Patterns are named identifiers for categories of breaking changes, stable across spec versions.

Contract patterns#

Agent patterns#

Behavioral patterns (roadmap — requires traffic capture)#

See also: MCP Integration for the three MCP tools that speak this contract, and Portable Verification for the receipt signature format.