clawpowers 1.0.1 → 1.1.0

package/skills/meta-skill-evolution/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: meta-skill-evolution
+description: RSI for coding methodology itself. After every 50 completed tasks, analyze outcome patterns, identify the weakest skill, surgically improve it, and commit the evolution. Agents that literally improve their own methodology over time.
+version: 1.0.0
+requires:
+  tools: [bash, git, node]
+  runtime: true
+metrics:
+  tracks: [evolutions_triggered, skills_improved, success_rate_delta, version_bumps, evolution_duration]
+  improves: [skill_selection_accuracy, weakest_skill_identification, surgical_edit_quality]
+---
+
+# Meta-Skill Evolution
+
+## When to Use
+
+Apply this skill when:
+
+- The task counter reaches a multiple of 50 (tracked in `~/.clawpowers/state/task-counter.json`)
+- A skill consistently shows < 70% success rate over the last 20 uses
+- `runtime/feedback/analyze.sh` surfaces a skill with declining trend
+- Bill explicitly requests "evolve the skills" or "improve methodology"
+- A cluster of related task failures points to a methodology gap
+
+**Skip when:**
+- Fewer than 50 total tasks have been completed (insufficient signal)
+- The runtime directory `~/.clawpowers/` doesn't exist (static mode)
+- A previous evolution cycle completed within the last 10 tasks (cooling period)
+
+**Decision tree:**
+```
+Has task counter hit a multiple of 50?
+├── No  → continue working; check counter at next task completion
+└── Yes → Run evolution cycle
+          └── Does weakest skill have < 80% success rate?
+              ├── No  → log "all skills healthy", increment counter, skip
+              └── Yes → identify weakest section → surgical edit → version bump → commit
+```
+
+## Core Methodology
+
+### Step 1: Trigger and Task Counter
+
+Every completed task increments a persistent counter. After each task:
+
+```bash
+# Increment task counter
+COUNTER_FILE=~/.clawpowers/state/task-counter.json
+CURRENT=$(cat "$COUNTER_FILE" 2>/dev/null | node -e "const d=require('/dev/stdin');console.log(d.count||0)" 2>/dev/null || echo 0)
+NEXT=$((CURRENT + 1))
+echo "{\"count\": $NEXT, \"last_updated\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" > "$COUNTER_FILE"
+
+# Check if evolution cycle is due
+if (( NEXT % 50 == 0 )); then
+  echo "Evolution cycle triggered at task $NEXT"
+  # → proceed to Step 2
+fi
+```
+
+**Recording task completion (run this after every task):**
+```bash
+bash runtime/metrics/collector.sh record \
+  --skill <active-skill-name> \
+  --outcome success|failure \
+  --duration <seconds> \
+  --notes "<brief description>"
+```
+
+### Step 2: Outcome Pattern Analysis
+
+Pull the last 50 task records and compute per-skill success rates:
+
+```bash
+# Analyze outcomes for the last 50 tasks
+METRICS_FILE=~/.clawpowers/metrics/outcomes.jsonl
+
+# Per-skill success rate (requires jq or node)
+node - <<'EOF'
+const fs = require('fs');
+const lines = fs.readFileSync(process.env.HOME + '/.clawpowers/metrics/outcomes.jsonl', 'utf8')
+  .trim().split('\n').filter(Boolean).slice(-50)
+  .map(l => JSON.parse(l));
+
+const stats = {};
+for (const rec of lines) {
+  const s = rec.skill || 'unknown';
+  if (!stats[s]) stats[s] = { success: 0, failure: 0, durations: [] };
+  stats[s][rec.outcome === 'success' ? 'success' : 'failure']++;
+  if (rec.duration) stats[s].durations.push(rec.duration);
+}
+
+const report = Object.entries(stats).map(([skill, d]) => {
+  const total = d.success + d.failure;
+  const rate = total > 0 ? (d.success / total) : null;
+  const avgDuration = d.durations.length > 0
+    ? Math.round(d.durations.reduce((a,b)=>a+b,0) / d.durations.length)
+    : null;
+  return { skill, success_rate: rate, total_tasks: total, avg_duration_s: avgDuration };
+}).sort((a, b) => (a.success_rate ?? 1) - (b.success_rate ?? 1));
+
+console.log(JSON.stringify(report, null, 2));
+EOF
+```
+
+**What to look for:**
+- Lowest `success_rate` → weakest skill candidate
+- Rising `avg_duration_s` → methodology is too slow or unclear
+- High failure count on a single skill → systemic gap, not random noise
+
+### Step 3: Identify the Weakest Skill
+
+```bash
+# Get weakest skill (lowest success rate with ≥ 3 data points)
+WEAKEST=$(node - <<'EOF'
+const fs = require('fs');
+const lines = fs.readFileSync(process.env.HOME + '/.clawpowers/metrics/outcomes.jsonl', 'utf8')
+  .trim().split('\n').filter(Boolean).slice(-50).map(l => JSON.parse(l));
+const stats = {};
+for (const rec of lines) {
+  const s = rec.skill || 'unknown';
+  if (!stats[s]) stats[s] = { success: 0, failure: 0 };
+  stats[s][rec.outcome === 'success' ? 'success' : 'failure']++;
+}
+const ranked = Object.entries(stats)
+  .filter(([_, d]) => (d.success + d.failure) >= 3)
+  .map(([skill, d]) => ({ skill, rate: d.success / (d.success + d.failure) }))
+  .sort((a, b) => a.rate - b.rate);
+console.log(ranked[0]?.skill || '');
+EOF
+)
+
+echo "Weakest skill: $WEAKEST"
+
+# Read the skill file
+SKILL_FILE="skills/$WEAKEST/SKILL.md"
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "Skill file not found: $SKILL_FILE — skipping evolution"
+  exit 0
+fi
+```
+
+### Step 4: Diagnose the Specific Weakness
+
+Before editing, analyze *why* the skill is failing. Read the failure notes:
+
+```bash
+# Extract failure notes for the weakest skill
+node - <<EOF
+const fs = require('fs');
+const skill = '$WEAKEST';
+const lines = fs.readFileSync(process.env.HOME + '/.clawpowers/metrics/outcomes.jsonl', 'utf8')
+  .trim().split('\n').filter(Boolean).slice(-50)
+  .map(l => JSON.parse(l))
+  .filter(r => r.skill === skill && r.outcome === 'failure' && r.notes);
+lines.forEach(r => console.log(r.timestamp, '|', r.notes));
+EOF
+```
+
+**Diagnosis patterns:**
+
+| Failure note pattern | Likely weak section | Fix strategy |
+|---------------------|-------------------|-------------|
+| "step X was unclear" | Core Methodology step X | Add concrete example, remove ambiguity |
+| "forgot to check Y" | Anti-Patterns table | Add the missed check as an explicit anti-pattern |
+| "didn't know when to apply" | When to Use decision tree | Sharpen the decision tree with new branch |
+| "ClawPowers commands failed" | ClawPowers Enhancement | Fix command syntax or add error handling |
+| "took too long on Z" | Core Methodology step Z | Add shortcut or restructure step ordering |
+
+### Step 5: Surgical Edit (Not Wholesale Replacement)
+
+**Critical rule:** Edit specific sections, not the entire file. Wholesale rewrites lose working methodology.
+
+```bash
+# Read the current skill version
+CURRENT_VERSION=$(grep '^version:' "$SKILL_FILE" | head -1 | awk '{print $2}' | tr -d '"')
+MAJOR=$(echo $CURRENT_VERSION | cut -d. -f1)
+MINOR=$(echo $CURRENT_VERSION | cut -d. -f2)
+PATCH=$(echo $CURRENT_VERSION | cut -d. -f3)
+NEW_VERSION="$MAJOR.$MINOR.$((PATCH + 1))"
+
+echo "Evolving $WEAKEST from v$CURRENT_VERSION → v$NEW_VERSION"
+```
+
+**Surgical edit guidelines:**
+- If the "When to Use" decision tree is wrong → edit only that block
+- If a Core Methodology step is incomplete → add one concrete example under that step
+- If an Anti-Pattern is missing → append one row to the table
+- If ClawPowers commands are broken → fix only the broken command block
+- Never touch sections that aren't implicated in the failures
+- Max lines changed per evolution cycle: 30 (forces focus)
+
+**Apply the edit and bump version:**
+```bash
+# After making the targeted edit in SKILL_FILE:
+sed -i "s/^version: $CURRENT_VERSION/version: $NEW_VERSION/" "$SKILL_FILE"
+```
+
+### Step 6: Commit the Evolution
+
+```bash
+# Stage and commit
+git add "$SKILL_FILE"
+git commit -m "skill-evolution: $WEAKEST v$CURRENT_VERSION → v$NEW_VERSION
+
+Triggered at task $TASK_COUNT. Success rate was $RATE%.
+Section edited: $SECTION_EDITED
+Root cause: $ROOT_CAUSE
+
+[meta-skill-evolution]"
+
+# Copy evolved skill to ~/.clawpowers/skills/ if exists
+MANAGED_SKILLS_DIR=~/.clawpowers/skills
+if [[ -d "$MANAGED_SKILLS_DIR" ]]; then
+  mkdir -p "$MANAGED_SKILLS_DIR/$WEAKEST"
+  cp "$SKILL_FILE" "$MANAGED_SKILLS_DIR/$WEAKEST/SKILL.md"
+fi
+```
+
+### Step 7: Log Evolution History
+
+Every evolution is appended to a persistent log:
+
+```bash
+EVOLUTION_LOG=~/.clawpowers/feedback/evolution-log.jsonl
+mkdir -p "$(dirname $EVOLUTION_LOG)"
+
+cat >> "$EVOLUTION_LOG" <<EOF
+{"timestamp":"$(date -u +%Y-%m-%dT%H:%M:%SZ)","task_count":$TASK_COUNT,"skill":"$WEAKEST","version_from":"$CURRENT_VERSION","version_to":"$NEW_VERSION","success_rate_before":$RATE,"section_edited":"$SECTION_EDITED","root_cause":"$ROOT_CAUSE","commit":"$(git rev-parse --short HEAD)"}
+EOF
+```
+
+**Review evolution history:**
+```bash
+# See all past evolutions
+cat ~/.clawpowers/feedback/evolution-log.jsonl | node -e "
+const lines = require('fs').readFileSync('/dev/stdin','utf8').trim().split('\n').map(JSON.parse);
+lines.forEach(e => console.log(e.timestamp.slice(0,10), e.skill, e.version_from, '→', e.version_to, 'rate:', (e.success_rate_before*100).toFixed(0)+'%'));
+"
+
+# Check if an evolution helped (compare rate before vs after)
+# Re-run outcome analysis after 10 more tasks to measure improvement
+```
+
+### Step 8: Validate the Evolution
+
+After 10 more tasks using the evolved skill, check if the success rate improved:
+
+```bash
+# Post-evolution check (run after 10+ tasks)
+NEW_RATE=$(node -e "
+const fs = require('fs');
+const lines = fs.readFileSync(process.env.HOME + '/.clawpowers/metrics/outcomes.jsonl','utf8')
+  .trim().split('\n').filter(Boolean).slice(-10)
+  .map(l => JSON.parse(l))
+  .filter(r => r.skill === '$WEAKEST');
+const success = lines.filter(r => r.outcome === 'success').length;
+console.log((success/lines.length).toFixed(2));
+")
+echo "Post-evolution success rate for $WEAKEST: $NEW_RATE"
+
+# If rate dropped: revert the evolution
+if node -e "process.exit(parseFloat('$NEW_RATE') < parseFloat('$RATE') ? 1 : 0)"; then
+  echo "Evolution improved the skill. Rate: $RATE → $NEW_RATE"
+else
+  echo "WARNING: Evolution did not help. Consider reverting."
+  git revert HEAD --no-edit
+fi
+```
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Full evolution pipeline:**
+
+```bash
+# Store evolution state for resumability
+bash runtime/persistence/store.sh set "meta-evolution:current:task_count" "$TASK_COUNT"
+bash runtime/persistence/store.sh set "meta-evolution:current:weakest_skill" "$WEAKEST"
+bash runtime/persistence/store.sh set "meta-evolution:current:phase" "diagnosis|editing|committed|validated"
+
+# Record the evolution outcome
+bash runtime/metrics/collector.sh record \
+  --skill meta-skill-evolution \
+  --outcome success \
+  --duration "$DURATION" \
+  --notes "$WEAKEST v$CURRENT_VERSION→v$NEW_VERSION rate:$RATE→$NEW_RATE"
+```
+
+**Analyze evolution effectiveness over time:**
+
+```bash
+bash runtime/feedback/analyze.sh --filter meta-skill-evolution
+# Shows: how many evolutions triggered, average rate improvement per evolution,
+# which skills have been evolved most, correlation between evolution and task success
+```
+
+**Track cumulative improvement:**
+```bash
+# Evolution impact report
+cat ~/.clawpowers/feedback/evolution-log.jsonl | node -e "
+const lines = require('fs').readFileSync('/dev/stdin','utf8').trim().split('\n').map(JSON.parse);
+const bySkill = {};
+lines.forEach(e => {
+  if (!bySkill[e.skill]) bySkill[e.skill] = [];
+  bySkill[e.skill].push(e);
+});
+Object.entries(bySkill).forEach(([skill, evos]) => {
+  console.log(skill + ': ' + evos.length + ' evolutions, versions: ' + evos.map(e=>e.version_to).join(', '));
+});
+"
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| Rewrite the whole skill | Destroys working methodology, no signal on what improved | Surgical edits only — max 30 lines changed |
+| Evolve based on < 3 data points | Statistical noise triggers false evolution | Require ≥ 3 uses before a skill is eligible |
+| Evolve on a cooling period | Too-frequent changes create instability | Enforce 10-task cooldown between evolutions |
+| Skip the validation step | Bad evolutions compound over time | Always measure rate before vs after |
+| Edit non-implicated sections | Changes unrelated things, pollutes signal | Only edit sections linked to failure notes |
+| Forget to bump version | Can't track evolution history | Version bump is mandatory before commit |
+| No evolution log entry | History is lost; can't audit what improved | Always append to evolution-log.jsonl |
+| Evolve the meta-skill-evolution skill first | Circular improvement without baseline | Evolve leaf skills first; evolve this skill only after 5+ other evolutions |

package/skills/self-healing-code/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: self-healing-code
+description: On test failure, automatically capture the failure, run hypothesis-driven debugging, generate ≥2 candidate patches, apply and measure each, auto-commit the winner or escalate with full context. Max 3 iteration cycles with coverage guard.
+version: 1.0.0
+requires:
+  tools: [bash, git]
+  runtime: true
+metrics:
+  tracks: [healing_attempts, auto_commits, escalations, patches_generated, coverage_delta, cycles_used]
+  improves: [patch_quality, hypothesis_accuracy, escalation_context_completeness]
+---
+
+# Self-Healing Code
+
+## When to Use
+
+Apply this skill when:
+
+- A CI run or local test suite produces a failure
+- A previously green test suite goes red after a code change
+- An automated pipeline fails and needs remediation without human intervention
+- Bill runs tests and the output contains `FAILED`, `ERROR`, or non-zero exit code
+
+**Skip when:**
+- Tests fail because of a missing environment variable or missing external service (that's a configuration issue, not a code defect)
+- The failure is a flaky test known to fail intermittently — check `~/.clawpowers/state/known-flaky.json` first
+- A previous healing cycle for this exact error is already in progress (check `~/.clawpowers/state/healing-lock.json`)
+
+**Decision tree:**
+```
+Did the test suite produce a failure?
+├── No  → no action
+└── Yes → Is this a known flaky test?
+          ├── Yes → skip, add flaky annotation, report
+          └── No  → Is a healing cycle already running for this error?
+                    ├── Yes → wait for completion or check lock age
+                    └── No  → self-healing-code ← YOU ARE HERE
+```
+
+## Core Methodology
+
+### Guardrails (enforce before any healing action)
+
+```bash
+# Max cycles — never exceed 3 healing iterations per error
+MAX_CYCLES=3
+HEALING_STATE=~/.clawpowers/state/healing-$(echo "$ERROR_SIG" | md5).json
+CURRENT_CYCLE=$(cat "$HEALING_STATE" 2>/dev/null | node -e "const d=require('/dev/stdin');console.log(d.cycle||0)" 2>/dev/null || echo 0)
+
+if (( CURRENT_CYCLE >= MAX_CYCLES )); then
+  echo "Max cycles ($MAX_CYCLES) reached. Escalating."
+  # → go to Step 6: Escalation
+fi
+
+# Coverage guard — baseline before any patch
+COVERAGE_BASELINE=$(bash runtime/persistence/store.sh get "coverage:baseline:$PROJECT" 2>/dev/null || echo "0")
+```
+
+### Step 1: Capture the Failure
+
+Collect everything needed to understand and reproduce the failure:
+
+```bash
+# Run tests and capture full output
+TEST_OUTPUT=$(bash -c "$TEST_CMD 2>&1") || true
+EXIT_CODE=$?
+
+# Extract structured fields
+TEST_NAME=$(echo "$TEST_OUTPUT" | grep -E "^(FAILED|FAIL|Error in)" | head -1)
+ERROR_MSG=$(echo "$TEST_OUTPUT" | grep -A5 "AssertionError\|Error:\|Exception:" | head -10)
+STACK_TRACE=$(echo "$TEST_OUTPUT" | grep -A20 "Traceback\|at [A-Za-z]" | head -30)
+
+# Diff from last green commit
+LAST_GREEN=$(bash runtime/persistence/store.sh get "last-green:$PROJECT" 2>/dev/null || git log --oneline | grep -i "green\|pass\|ci:" | head -1 | awk '{print $1}')
+DIFF_FROM_GREEN=""
+if [[ -n "$LAST_GREEN" ]]; then
+  DIFF_FROM_GREEN=$(git diff "$LAST_GREEN" HEAD -- . 2>/dev/null | head -200)
+fi
+
+# Error signature hash (for dedup and state tracking)
+ERROR_SIG=$(echo "${TEST_NAME}${ERROR_MSG}" | md5)
+
+# Log the capture
+CAPTURE_RECORD=~/.clawpowers/state/healing-$ERROR_SIG-capture.json
+cat > "$CAPTURE_RECORD" <<EOF
+{
+  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "test_name": $(echo "$TEST_NAME" | node -e "process.stdin.on('data',d=>console.log(JSON.stringify(d.toString().trim())))"),
+  "error_msg": $(echo "$ERROR_MSG" | node -e "process.stdin.on('data',d=>console.log(JSON.stringify(d.toString().trim())))"),
+  "exit_code": $EXIT_CODE,
+  "last_green_commit": "$LAST_GREEN",
+  "error_signature": "$ERROR_SIG"
+}
+EOF
+```
+
+**Capture checklist:**
+- [ ] Test name (exact test identifier)
+- [ ] Full error message (not truncated)
+- [ ] Stack trace (full, not just last frame)
+- [ ] Diff from last green commit
+- [ ] Environment snapshot (language version, key deps)
+
+### Step 2: Hypothesis Tree (Systematic Debugging Integration)
+
+Apply the `systematic-debugging` methodology to form ranked hypotheses. This is not optional — random patches without hypotheses produce random results.
+
+```bash
+# Check persistent hypothesis memory first (see systematic-debugging enhancement)
+KNOWN_HYP=$(bash runtime/persistence/store.sh get "debug:hypothesis:$ERROR_SIG" 2>/dev/null)
+if [[ -n "$KNOWN_HYP" ]]; then
+  echo "Known error pattern found. Starting with previously successful hypothesis."
+  echo "$KNOWN_HYP"
+fi
+```
+
+**Hypothesis template for common failure patterns:**
+
+| Failure pattern | Likely hypothesis | Experiment |
+|----------------|------------------|-----------|
+| `AttributeError: 'NoneType' has no attribute X` | Null not guarded in refactored path | Add null check before access |
+| `AssertionError: expected X, got Y` | Logic changed in upstream function | Bisect to find commit, inspect callers |
+| `ConnectionRefusedError` | Service not started or port changed | Check env config, not a code fix |
+| `KeyError: 'field_name'` | Schema changed, consumer not updated | Find all consumers of that key |
+| `TypeError: expected str, got int` | Type coercion removed | Restore coercion or fix caller |
+
+Form 2-4 specific hypotheses before generating patches.
+
+### Step 3: Generate Candidate Patches (Minimum 2)
+
+For each top hypothesis, generate a candidate patch. Generate patches **before** applying any:
+
+```bash
+# Stash current state for rollback safety
+git stash push -m "self-healing-pre-patch-$ERROR_SIG-$(date +%s)"
+STASH_REF=$(git stash list | head -1 | awk '{print $1}' | tr -d ':')
+
+# Generate patch candidates (store as files, don't apply yet)
+mkdir -p ~/.clawpowers/state/patches/$ERROR_SIG
+```
+
+**Patch generation principles:**
+- **Patch A:** Minimal fix — smallest change that addresses the hypothesis (prefer this)
+- **Patch B:** Alternative approach — different mechanism, same outcome
+- **Patch C (if needed):** Defensive fix — add guards to prevent the class of error
+
+**Example (Python null guard):**
+```python
+# Patch A — minimal: add None check at the failure site
+# Before:
+result = user.profile.settings["theme"]
+# After:
+result = user.profile.settings.get("theme", "default") if user.profile else "default"
+
+# Patch B — alternative: fix upstream to guarantee non-null
+# Before:
+def get_user(user_id):
+    return db.query(User).filter_by(id=user_id).first()  # can return None
+# After:
+def get_user(user_id):
+    user = db.query(User).filter_by(id=user_id).first()
+    if user is None:
+        raise UserNotFoundError(f"User {user_id} not found")
+    return user
+```
+
+Write each patch to a file:
+```bash
+# Write patches to staging area
+cat > ~/.clawpowers/state/patches/$ERROR_SIG/patch-a.diff <<'EOF'
+[patch content here]
+EOF
+
+# Capture reasoning for each patch
+echo '{"patch":"a","hypothesis":"null not guarded","mechanism":"add get() with default","confidence":"high"}' \
+  > ~/.clawpowers/state/patches/$ERROR_SIG/patch-a-meta.json
+```
+
+### Step 4: Apply, Test, Measure
+
+Apply patches in order, testing each. Stop at the first winner.
+
+```bash
+# Measure baseline coverage before any patch
+COVERAGE_BEFORE=$(bash -c "$COVERAGE_CMD 2>&1" | grep -E "TOTAL.*[0-9]+%" | grep -oE "[0-9]+%" | tail -1)
+
+for PATCH in a b c; do
+  PATCH_FILE=~/.clawpowers/state/patches/$ERROR_SIG/patch-$PATCH.diff
+  [[ -f "$PATCH_FILE" ]] || continue
+
+  echo "=== Applying patch $PATCH ==="
+
+  # Restore clean state from stash before each patch
+  git stash pop 2>/dev/null || true
+  git stash push -m "self-healing-between-patches-$ERROR_SIG" 2>/dev/null || true
+  git checkout -- . 2>/dev/null || true
+
+  # Apply the patch
+  git apply "$PATCH_FILE" 2>/dev/null || patch -p1 < "$PATCH_FILE" 2>/dev/null
+
+  # Run full test suite
+  TEST_RESULT=$(bash -c "$TEST_CMD 2>&1")
+  TEST_EXIT=$?
+
+  # Measure coverage after patch
+  COVERAGE_AFTER=$(bash -c "$COVERAGE_CMD 2>&1" | grep -E "TOTAL.*[0-9]+%" | grep -oE "[0-9]+%" | tail -1)
+
+  # Coverage guard: never reduce
+  COVERAGE_OK=true
+  if [[ -n "$COVERAGE_BEFORE" && -n "$COVERAGE_AFTER" ]]; then
+    BEFORE_NUM=$(echo "$COVERAGE_BEFORE" | tr -d '%')
+    AFTER_NUM=$(echo "$COVERAGE_AFTER" | tr -d '%')
+    if (( AFTER_NUM < BEFORE_NUM )); then
+      COVERAGE_OK=false
+      echo "Coverage dropped: $COVERAGE_BEFORE → $COVERAGE_AFTER. Patch $PATCH rejected."
+    fi
+  fi
+
+  if [[ $TEST_EXIT -eq 0 && "$COVERAGE_OK" == "true" ]]; then
+    echo "Patch $PATCH PASSED all tests. Coverage: $COVERAGE_BEFORE → $COVERAGE_AFTER"
+    WINNING_PATCH=$PATCH
+    break
+  else
+    echo "Patch $PATCH FAILED. Exit: $TEST_EXIT. Coverage OK: $COVERAGE_OK"
+  fi
+done
+```
+
+### Step 5: Auto-Commit the Winner
+
+If a patch passes all tests and maintains coverage:
+
+```bash
+if [[ -n "$WINNING_PATCH" ]]; then
+  # Commit with full context
+  git add -A
+  git commit -m "fix: self-healing patch for ${TEST_NAME}
+
+Error signature: $ERROR_SIG
+Patch applied: $WINNING_PATCH
+Hypothesis: $(cat ~/.clawpowers/state/patches/$ERROR_SIG/patch-$WINNING_PATCH-meta.json | node -e "const d=require('/dev/stdin');process.stdin.pipe(d.hypothesis)")
+Coverage: $COVERAGE_BEFORE → $COVERAGE_AFTER
+Cycles used: $((CURRENT_CYCLE + 1))/$MAX_CYCLES
+
+[self-healing-code]"
+
+  # Store last-green reference
+  bash runtime/persistence/store.sh set "last-green:$PROJECT" "$(git rev-parse HEAD)"
+
+  # Record success
+  bash runtime/metrics/collector.sh record \
+    --skill self-healing-code \
+    --outcome success \
+    --notes "patch-$WINNING_PATCH won, coverage $COVERAGE_BEFORE→$COVERAGE_AFTER, cycle $((CURRENT_CYCLE+1))/$MAX_CYCLES"
+
+  # Clean up healing state
+  rm -rf ~/.clawpowers/state/patches/$ERROR_SIG
+  rm -f ~/.clawpowers/state/healing-$ERROR_SIG*.json
+fi
+```
+
+### Step 6: Rollback Protocol
+
+If no patch wins after all candidates are tried:
+
+```bash
+if [[ -z "$WINNING_PATCH" ]]; then
+  # Restore to pre-healing state
+  git checkout -- .
+  git stash drop 2>/dev/null || true
+  echo "All patches failed. State restored to pre-healing baseline."
+
+  # Increment cycle counter
+  NEW_CYCLE=$((CURRENT_CYCLE + 1))
+  echo "{\"cycle\": $NEW_CYCLE, \"error_sig\": \"$ERROR_SIG\"}" > "$HEALING_STATE"
+
+  if (( NEW_CYCLE < MAX_CYCLES )); then
+    echo "Cycle $NEW_CYCLE/$MAX_CYCLES complete. Forming new hypotheses."
+    # → Loop back to Step 2 with refined hypotheses
+  else
+    # → Escalate
+    echo "Max cycles reached. Escalating with full context."
+  fi
+fi
+```
+
+### Step 7: Escalation Package
+
+When all cycles are exhausted, escalate with enough context that a human can immediately begin debugging:
+
+```markdown
+## Self-Healing Escalation Report
+
+**Error:** [test_name]
+**Error signature:** [hash]
+**Cycles attempted:** 3/3
+**Time spent:** [duration]
+
+### Failure Details
+[Full test output — not truncated]
+
+### Patches Attempted
+1. Patch A — [hypothesis] — [outcome]
+2. Patch B — [hypothesis] — [outcome]
+3. Patch C — [hypothesis] — [outcome]
+
+### Diff from Last Green
+[git diff output]
+
+### Recommended Next Step
+[Best remaining hypothesis with suggested experiment]
+
+### Relevant Files
+[files touched by failing test]
+```
+
+```bash
+# Record escalation
+bash runtime/metrics/collector.sh record \
+  --skill self-healing-code \
+  --outcome failure \
+  --notes "escalated: $MAX_CYCLES cycles, $PATCHES_TRIED patches, test: $TEST_NAME"
+```
+
+## ClawPowers Enhancement
+
+When `~/.clawpowers/` runtime is initialized:
+
+**Healing state persistence (resumable across sessions):**
+
+```bash
+# Save healing progress
+bash runtime/persistence/store.sh set "healing:$ERROR_SIG:cycle" "$CURRENT_CYCLE"
+bash runtime/persistence/store.sh set "healing:$ERROR_SIG:stash" "$STASH_REF"
+bash runtime/persistence/store.sh set "healing:$ERROR_SIG:patches_tried" "$PATCHES_TRIED"
+
+# Resume an interrupted healing session
+ERROR_SIG="<hash>"
+CYCLE=$(bash runtime/persistence/store.sh get "healing:$ERROR_SIG:cycle")
+STASH=$(bash runtime/persistence/store.sh get "healing:$ERROR_SIG:stash")
+echo "Resuming healing cycle $CYCLE for error $ERROR_SIG"
+```
+
+**Regression detection:**
+```bash
+# After auto-commit, verify no regressions in related tests
+RELATED_TESTS=$(git diff HEAD~1 HEAD --name-only | xargs grep -l "def test_" 2>/dev/null | head -10)
+bash -c "$TEST_CMD $RELATED_TESTS 2>&1"
+```
+
+**Pattern learning (feeds systematic-debugging):**
+```bash
+# After successful heal, store the winning pattern
+bash runtime/persistence/store.sh set "debug:hypothesis:$ERROR_SIG" \
+  "$(cat ~/.clawpowers/state/patches/$ERROR_SIG/patch-$WINNING_PATCH-meta.json)"
+```
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|-------------|-------------|-----------------|
+| Apply patches without stashing first | No rollback path if all patches fail | Always stash before first patch |
+| Skip hypothesis formation | Random patches waste all 3 cycles | Form ranked hypotheses before any patch |
+| Generate only 1 patch | Single point of failure | Always generate ≥ 2 patches before applying |
+| Skip coverage check | Patches that delete tests always "pass" | Coverage guard is non-negotiable |
+| Apply patches sequentially without reset | Patches contaminate each other | Reset to clean state between each patch |
+| Commit without full test suite pass | Partial fixes break other tests | Run full suite, not just the failing test |
+| Exceed 3 cycles | Spiraling into a rabbit hole | Hard limit at 3; escalate cleanly |
+| Escalate without full context | Human must re-investigate from scratch | Escalation package must include all evidence |