/orbit

Failure Catalog

Purpose: single source of truth for classifying loop anomalies. Maps every observed evidence shape to a failure class, an anti-pattern ID (AP-*) for review/post-mortem cross-reference, a risk level, a safe-by-construction rule, and the smallest reversible recovery action. Load this when classifying live findings, running a safety review, or building a post-mortem.

Contents

1. Unified catalog (ID + class + risk + safe rule + recovery + sources)
2. High-impact Top 3
3. Severity priority
4. Retry policy by error type
5. Reporting schema
6. Contract-check mapping
7. Multiple-failure rule
8. Circuit breaker integration
9. Prevention checklist
10. Quick detection reference

Unified Catalog

Columns: ID = anti-pattern identifier (for review/post-mortem); Class = failure-class token used by the runner and reporting schema; Risk = primary hazard; Safe rule = preventive design rule; Recovery = smallest reversible action; Source = research citation (METR/NIST/etc.) when applicable.

Additional CONTRACT_MISSING signals (no AP-* mapping)

These are runtime-detected contract gaps surfaced by the audit pipeline; they share the CONTRACT_MISSING class but are not in the anti-pattern catalog.

Additional STATE_DRIFT signals

Additional VERIFY_GAP signals

Additional COMMIT_SCOPE_RISK signals

Additional TOOL_FAILURE signals

Additional semantic-stall signals (CONVERGENCE_STALL / OSCILLATION_LOOP)

Runtime-detected by the audit pipeline from .action-sig.log (per-iteration change signature written by the runner). Circuit breakers catch exit-code failures but miss these — iterations "succeed" while producing no net progress.

High-Impact Top 3

Apply first when generating new runners; these are the highest-leverage protections.

1. AP-13 REWARD_HACK — METR/NIST 2025-2026 demonstrate this across multiple models. tests/ immutability is a one-line fix with outsized safety value.
2. AP-14 Worktree Cleanup — destructive data loss reproducible per Claude Code issue #48927. Inode monitoring is cheap; the alternative is unrecoverable.
3. AP-17 BURN_RATE_ANOMALY — multiple 2026 incidents ($6k overnight, Uber-scale events). EWMA monitoring is orthogonal to existing RETRY_LIMIT and TOKEN_BUDGET.

Severity Priority

Retry Policy by Error Type

Errors are classified into two categories for retry policy:

Detection heuristics:

When a TRANSIENT error is retried 3 consecutive times with the same error signature, it is reclassified as PERMANENT and the circuit breaker is engaged (see § Circuit Breaker Integration).

Reporting Schema

ORBIT_FAILURE_REPORT:
  class: "<taxonomy class>"
  anti_pattern_id: "<AP-* if applicable>"
  severity: "P0|P1|P2"
  sub_class: "<specific signal>"
  retry_category: "TRANSIENT|PERMANENT"
  circuit_state: "CLOSED|HALF_OPEN|OPEN"
  evidence:
    - "<file:line>"
  impact: "<what breaks>"
  recommendation: "<smallest reversible action>"
  recovery_cmd: "<command>"

Contract-Check Mapping

Rules for Multiple Failure Classes

• Process the highest severity first.
• P0 always preempts P1 and P2.
• Use one handoff at a time.
• Record remaining issues as pending issues for the next audit cycle.

Circuit Breaker Integration

When the same failure signature (class + sub_class + error message hash) occurs CIRCUIT_THRESHOLD times (default 3):

Cooldown: OPEN state auto-transitions to HALF_OPEN after CIRCUIT_COOLDOWN seconds (default: 300).

Reset: manual reset via recover.sh --reset-circuit or by clearing ${LOOP_DIR}/.circuit-state.

Reporting: circuit breaker state changes are logged in the structured log (see script-template-runner.md § Structured Logging).

Prevention Checklist

Run before launching a loop:

• RETRY_LIMIT is set and <= 5
• verify.sh exists and covers all acceptance criteria
• goal.md has exactly one objective
• no stale .run-loop.lock exists
• every AC maps to a deterministic command
• ACs were written for this loop, not copied from another
• state.env has not been edited manually
• state.env and progress.md are consistent
• dirty-start-paths.nul exists when AUTOCOMMIT=true
• the DONE gate requires done.md and verify PASS/SKIP
• no manual git checkout will happen during active BRANCH_ISOLATION
• verify.sh includes a placeholder-detection step (TODO / pass / NotImplementedError)
• tests/ and verify.sh are read-only or protected by pre-commit
• git fsck and .git/ inode monitoring run at iter start under WORKTREE_ISOLATION
• scratchpad rotation policy is set; goal.md size is tracked iter-over-iter
• goal.md and AC files are sha256-pinned and read-only
• BURN_RATE_THRESHOLD, USD_PER_ITER_CAP, USD_PER_RUN_CAP are configured; auto-reload billing is disabled
• verify.sh includes architectural lint (duplication / cycles / dead code)
• decisions.md (append-only) is referenced; first post-compaction iter re-reads it
• .claude/settings*.json sha256-pinned at loop start
• tool-call argv dedup is active (last DEDUP_WINDOW calls hashed)

Live-Loop Audit Checklist

Run in AUDIT mode against a running or completed loop (vs the pre-launch Prevention Checklist above). Inspects evidence the runner produces; maps each miss to a class via the tables above.

• state.env.sha256 matches state.env (integrity) and NEXT_ITERATION agrees with the last progress.md entry
• CONTRACT_VERSION in state.env ≥ runner's contract version (else migration per operation-contract.md)
• a hard external terminator is declared (LOOP_TIMEOUT or USD_PER_RUN_CAP) — not iteration-cap only
• every AC in goal.md resolves to a verify command (oracle completeness)
• .goal.sha256 exists and still matches goal.md (no GOAL_DRIFT)
• .cost-usd (when present) sum is within USD_PER_RUN_CAP; last line within USD_PER_ITER_CAP
• .action-sig.log tail shows no CONVERGENCE_WINDOW identical lines and no A↔B oscillation
• any DONE claim has done.md + verify PASS/SKIP + placeholder-clean changed source (triple gate)
• footer NEXUS_LOOP_STATUS is one of READY/CONTINUE/DONE and parses deterministically

Quick Detection Reference

Failure Class Table

Canonical home for the failure taxonomy referenced from SKILL.md -> Failure and Learning Rules.