Policies

Policies are YAML rules that define when a merge should be blocked based on behavioral signals. They're version-controlled alongside your code in spooled-policy.yml.

Evaluation flow

Trace → Fingerprint → Compare to baseline → Status + Score
    → Detect signals → Evaluate policy rules
    → Result: PASS (exit 0) or FAIL (exit 1)

Blocking vs. warning

Type	Exit code	Effect
fail_if (violation)	1	Blocks the merge, fails the CI check
warn_if (warning)	0	Logged in the report, does not block

Common patterns

Block all variants — strictest, no behavioral changes allowed:

block_merges: true
rules:
  - name: "No variants"
    fail_if:
      on_variant: true

Tool allowlist — require specific tools to be present:

rules:
  - name: "Compliance guardrails"
    fail_if:
      required_tools:
        tools: ["check_pii", "detect_hallucination"]
        message: "Compliance tools must be in the execution path"

Latency budget — block when latency exceeds threshold:

rules:
  - name: "Latency SLA"
    fail_if:
      latency_spike:
        threshold_percent: 25.0

Per-agent profiles — different rules for different agents:

profiles:
  default:
    block_merges: false
    rules:
      - name: "Warn only"
        warn_if:
          new_side_effects: true
  payment_agent:
    block_merges: true
    rules:
      - name: "Strict"
        fail_if:
          new_side_effects: true
          on_variant: true

Rule evaluation order

Rules are evaluated in order. If an agent_id matches a profile, that profile's rules are used exclusively. Otherwise, the default profile applies. If no profiles section exists, top-level rules apply to all agents.

See Policy Engine Reference for the complete list of supported conditions.