self-healing-orchestrator

AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.

Self-Healing Orchestrator

STATUS — v3.7.0-rc.1. Per-spec safety gates strictly enforced.

Core Principle

Self-healing PROPOSES; the user APPLIES. A proposal goes through the same approval gate as a manual replan — there is no autonomous patch. If you find this skill applying patches without a user yes, that's a bug.

Hard constraints (per spec §22.1)

constraints[6]{rule,enforcement}:
  "ONLY F2 (local-logic) or F3 (local-design)","Refuse if classifier returns F1/F4/F5/F6 — those need different paths"
  "ONLY proposes; NEVER applies","Output is always a proposal artifact; user runs /aura-frog:heal accept <id> to apply"
  "Confidence < 0.7 → don't propose","Surface raw findings only; user decides if a fix is even reachable"
  "Counts toward replan_budget","Same node-level budget enforcement as replanner (per replan-thresholds.md)"
  "Max 1 self-heal per task","Once a task accepts a self-heal patch, no further auto-proposals for that task"
  "Session cap: 5 proposals total","Anti-fatigue + anti-loop; after 5, defer to manual /aura-frog:plan-replan"

Disable mechanisms (per spec §22.3, §31.3)

• Per-session: /aura-frog:heal disable — sets .claude/logs/.self-heal-disabled flag
• Permanent: AF_SELF_HEAL_DISABLED=true in .envrc
• Hook integration ignores any proposal when disabled

Flow (per spec §22.2)

Failure detected (F2 or F3)
    ↓
self-healing-orchestrator activated (only if budget remaining)
    ↓
Step 1: Parse error log → error class, library, line numbers
Step 2: Query context7 for known library patterns (NOT random web sources)
Step 3: Cross-reference permanent_memory.md "Gotchas discovered"
Step 4: Generate PROPOSED patch as draft (diff format, not applied)
Step 5: Score confidence: refuse if < 0.7
Step 6: Master-planner presents user prompt with diff + reasoning + confidence
Step 7: On user yes → apply as a NEW T4 task with its own approval flow
Step 8: On user no → log as `event: self_heal_declined`, increment session counter

Cross-check sources (allowlist)

allowed_sources[3]{source,why}:
  context7 MCP,"Library documentation; trusted technical reference"
  permanent_memory.md,"Project's own learned wisdom; trust:file"
  recent traces (.claude/plans/traces/),"Same-project context for the failure"

Forbidden sources: Stack Overflow, blog posts, web search results — too noisy, too easy to hallucinate from.

Output schema (proposal artifact)

proposal_id: HEAL-<TASK_ID>-<NNN>
task_id: TASK-00101
classification: F3
confidence: 0.84
reasoning: "Test fails because async/await missing on JWT issuance call. Library docs (context7) confirm the API is async. Memory (DEC-001) decided on httpOnly cookie storage (unaffected)."
patch:
  - file: src/auth/jwt.ts
    start_line: 42
    end_line: 42
    before: "const token = issueToken(claims);"
    after: "const token = await issueToken(claims);"
acceptance_test: "jest tests/auth.test.ts → tests/auth.test.ts::should_issue_token"
risks:
  - "Caller chain may need awaiting too — check src/auth/middleware.ts callers"
  - "Latency increase ~10ms (negligible)"
budget_decrement: 1
session_proposal_count: 2 of 5

The proposal lives at .claude/plans/proposals/HEAL-<TASK_ID>-<NNN>.yaml until accepted/declined.

Anti-patterns (each is a hard refusal)

• Auto-applying a high-confidence proposal — confidence is just signal; user approval is non-negotiable
• Proposing for F4/F5 — wrong scope; F4 needs Story replan, F5 needs Feature replan, both via replanner
• Pulling fixes from random web search — hallucination risk; cite only context7 + permanent_memory + traces
• Bypassing budget — same as replanner; if budget exhausted, escalate
• Emitting a proposal with confidence ≥0.7 but evidence < confidence — sanity check: if you can't cite ≥2 grounded sources, drop confidence below 0.7

Tie-Ins

• Spec: §22 (self-healing), §15.1 (F-class boundaries), §22.3 (disable), §31.3 (env vars)
• Skill: failure-classifier — sole producer of F2/F3 inputs
• Agent: master-planner — sole consumer of proposals (presents to user)
• Agent: replanner — alternative path for F4/F5 (this skill never trespasses)
• Rule: rules/workflow/replan-thresholds.md — shared budget semantics
• Rule: rules/workflow/checkpoint-discipline.md — pre-mutation snapshot before applying accepted proposals
• Command: /aura-frog:heal diagnose|status|disable|accept
• MCP: context7 — sole external knowledge source (rate-limited via mcp-call-gate)
• File: .claude/plans/proposals/HEAL-*.yaml — proposal artifacts
• File: .claude/memory/permanent_memory.md — Gotchas / Anti-patterns sections cross-referenced