phoenix-self-heal

phoenix-self-heal — sense, snapshot, heal; the loop at the heart of Phoenix

Overview

This is the primitive every Phoenix lifecycle skill is built on, usable standalone: objectively sense whether work succeeded, keep a blessed snapshot to fall back to, and heal (bounded) when a check goes red — with recovery confirmed by an independent recheck, never by self-judgment. It gives an agent the one organ it's missing: knowing it failed, and fixing it, with evidence.

When to use

• Any code change with a runnable check (test/build/lint).
• Risky edits where you want a guaranteed rollback point.
• As the inner loop of phoenix-build, phoenix-test, and phoenix-debug.

The four tools

• phoenix_sense(check) — objective check. kind ∈ command_exit (run argv, pass iff exit==expect, default 0), file_sha256, regex_in_file. Returns {ok, signal, evidence}. No LLM, no opinion. target accepts an argv array (preferred) or a string; expect accepts an int or string.
• phoenix_snapshot(path, check) — save path as last-good only if check passes (never blesses a broken state). Returns {blessed, snap_id}.
• phoenix_heal(strategy, ctx) — rollback (restore a blessed snapshot) or retry (re-run a command ≤3×). healed=true only if ctx.recheck passes after the action. Bounded; reversible.
• phoenix_verify_trace() — audit the tamper-evident hash-chained log.

Example

{"check":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}                       # sense
{"path":"src/app.py","check":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}    # snapshot (blesses if green)
{"strategy":"rollback","ctx":{"path":"src/app.py","snap_id":"app.py.1a2b…",                    # heal
  "recheck":{"kind":"command_exit","target":["pytest","-q"],"expect":0}}}

The loop

  baseline ─► phoenix_sense ─► ok? ──no──► (not ready; create a check first)
                               │ yes
                               ▼
                       phoenix_snapshot (bless green state)
                               │
                               ▼
                          ── edit ──
                               │
                       phoenix_sense ─► ok? ──yes──► done (green, proven)
                               │ no
                               ▼
                       phoenix_heal (rollback/retry, ≤3) ─► re-sense ─► green? 
                               │ no after 3 → STOP, report what's blocking