harness-everything 0.2.1 → 0.2.2

package/verification-loop/SKILL.md

@@ -1,138 +1,138 @@
----
-name: verification-loop
-description: "A comprehensive verification system for Claude Code sessions."
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
-metadata:
-  origin: ECC
----
-
-# Verification Loop Skill
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Approaching task completion or PR creation. Input: The modified project files. |
-| **Expected Output** | Terminal logs showing successful Build, Type Check, Lint, and Test execution. |
-| **State Mutations** | None. Pure verification. |
-| **Enforcement Gate** | You MUST execute `npm run build`, `npm run lint`, and `npm run test` (or equivalent). You cannot complete the task if any of these return Exit Code 1. |
-
-A comprehensive verification system for Claude Code sessions.
-
-## When to Use
-
-Invoke this skill:
-- After completing a feature or significant code change
-- Before creating a PR
-- When you want to ensure quality gates pass
-- After refactoring
-
-## Verification Phases
-
-### Phase 1: Build Verification
-```bash
-# Check if project builds
-npm run build 2>&1 | tail -20
-# OR
-pnpm build 2>&1 | tail -20
-```
-
-If build fails, STOP and fix before continuing.
-
-### Phase 2: Type Check
-```bash
-# TypeScript projects
-npx tsc --noEmit 2>&1 | head -30
-
-# Python projects
-pyright . 2>&1 | head -30
-```
-
-Report all type errors. Fix critical ones before continuing.
-
-### Phase 3: Lint Check
-```bash
-# JavaScript/TypeScript
-npm run lint 2>&1 | head -30
-
-# Python
-ruff check . 2>&1 | head -30
-```
-
-### Phase 4: Test Suite
-```bash
-# Run tests with coverage
-npm run test -- --coverage 2>&1 | tail -50
-
-# Check coverage threshold
-# Target: 80% minimum
-```
-
-Report:
-- Total tests: X
-- Passed: X
-- Failed: X
-- Coverage: X%
-
-### Phase 5: Security Scan
-```bash
-# Check for secrets
-grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
-grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
-
-# Check for console.log
-grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
-```
-
-### Phase 6: Diff Review
-```bash
-# Show what changed
-git diff --stat
-git diff HEAD~1 --name-only
-```
-
-Review each changed file for:
-- Unintended changes
-- Missing error handling
-- Potential edge cases
-
-## Output Format
-
-After running all phases, produce a verification report:
-
-```
-VERIFICATION REPORT
-==================
-
-Build:     [PASS/FAIL]
-Types:     [PASS/FAIL] (X errors)
-Lint:      [PASS/FAIL] (X warnings)
-Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
-Security:  [PASS/FAIL] (X issues)
-Diff:      [X files changed]
-
-Overall:   [READY/NOT READY] for PR
-
-Issues to Fix:
-1. ...
-2. ...
-```
-
-## Continuous Mode
-
-For long sessions, run verification every 15 minutes or after major changes:
-
-```markdown
-Set a mental checkpoint:
-- After completing each function
-- After finishing a component
-- Before moving to next task
-
-Run: /verify
-```
-
-## Integration with Hooks
-
-This skill complements PostToolUse hooks but provides deeper verification.
-Hooks catch issues immediately; this skill provides comprehensive review.
+---
+name: verification-loop
+description: "A comprehensive verification system for Claude Code sessions."
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+metadata:
+  origin: ECC
+---
+
+# Verification Loop Skill
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Approaching task completion or PR creation. Input: The modified project files. |
+| **Expected Output** | Terminal logs showing successful Build, Type Check, Lint, and Test execution. |
+| **State Mutations** | None. Pure verification. |
+| **Enforcement Gate** | You MUST execute `npm run build`, `npm run lint`, and `npm run test` (or equivalent). You cannot complete the task if any of these return Exit Code 1. |
+
+A comprehensive verification system for Claude Code sessions.
+
+## When to Use
+
+Invoke this skill:
+- After completing a feature or significant code change
+- Before creating a PR
+- When you want to ensure quality gates pass
+- After refactoring
+
+## Verification Phases
+
+### Phase 1: Build Verification
+```bash
+# Check if project builds
+npm run build 2>&1 | tail -20
+# OR
+pnpm build 2>&1 | tail -20
+```
+
+If build fails, STOP and fix before continuing.
+
+### Phase 2: Type Check
+```bash
+# TypeScript projects
+npx tsc --noEmit 2>&1 | head -30
+
+# Python projects
+pyright . 2>&1 | head -30
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+### Phase 3: Lint Check
+```bash
+# JavaScript/TypeScript
+npm run lint 2>&1 | head -30
+
+# Python
+ruff check . 2>&1 | head -30
+```
+
+### Phase 4: Test Suite
+```bash
+# Run tests with coverage
+npm run test -- --coverage 2>&1 | tail -50
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+### Phase 5: Security Scan
+```bash
+# Check for secrets
+grep -rn "sk-" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+grep -rn "api_key" --include="*.ts" --include="*.js" . 2>/dev/null | head -10
+
+# Check for console.log
+grep -rn "console.log" --include="*.ts" --include="*.tsx" src/ 2>/dev/null | head -10
+```
+
+### Phase 6: Diff Review
+```bash
+# Show what changed
+git diff --stat
+git diff HEAD~1 --name-only
+```
+
+Review each changed file for:
+- Unintended changes
+- Missing error handling
+- Potential edge cases
+
+## Output Format
+
+After running all phases, produce a verification report:
+
+```
+VERIFICATION REPORT
+==================
+
+Build:     [PASS/FAIL]
+Types:     [PASS/FAIL] (X errors)
+Lint:      [PASS/FAIL] (X warnings)
+Tests:     [PASS/FAIL] (X/Y passed, Z% coverage)
+Security:  [PASS/FAIL] (X issues)
+Diff:      [X files changed]
+
+Overall:   [READY/NOT READY] for PR
+
+Issues to Fix:
+1. ...
+2. ...
+```
+
+## Continuous Mode
+
+For long sessions, run verification every 15 minutes or after major changes:
+
+```markdown
+Set a mental checkpoint:
+- After completing each function
+- After finishing a component
+- Before moving to next task
+
+Run: /verify
+```
+
+## Integration with Hooks
+
+This skill complements PostToolUse hooks but provides deeper verification.
+Hooks catch issues immediately; this skill provides comprehensive review.

package/verify-before-claim/SKILL.md

@@ -1,86 +1,86 @@
----
-name: verify-before-claim
-description: "Verify external framework/API claims and unmeasured perf/cost estimates against an authoritative source before asserting them, instead of answering from training memory."
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
-metadata:
-  type: harness-discipline
----
-
-# Verify Before Claim
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | About to state how an external system (framework/library/SDK/API/service) currently behaves, or about to state an unmeasured performance/cost/timing number. |
-| **Expected Output** | The claim is backed by a `WebFetch`/`WebSearch`-sourced quote from authoritative docs, or an actual measurement — never asserted from training memory alone. |
-| **State Mutations** | None — this is a discipline governing what gets asserted in the response, not a file-mutating skill. |
-| **Enforcement Gate** | An external-behavior claim without a same-session fetch/search backing it **MUST NOT** be asserted with confidence; an unmeasured number **MUST** be explicitly labeled as an estimate, not presented as fact. |
-
-Training memory goes stale and is easy to misremember with full confidence.
-This skill exists because that failure mode is real and already happened in
-this repo: an early claim that `rule-of-3.js`'s `process.exit(1)` blocked a
-Claude Code `PreToolUse` hook was wrong — the official docs say only
-`exit(2)` blocks, `exit(1)` is a non-blocking error — and it was only caught
-by actually fetching `code.claude.com/docs/en/hooks` instead of trusting the
-assumption. The circuit breaker had never blocked anything until that got
-checked.
-
-`harness-everything/scripts/tier-router.js` fires a lightweight keyword-based
-reminder for this automatically (`UserPromptSubmit`, "FACT-AUDIT REMINDER"
-block) so you don't have to be manually pushed into checking every time. This
-file is the actual discipline behind that reminder.
-
-## TRIGGER — verify before asserting, don't skip because the answer "feels obvious"
-
-Whenever either is true:
-
-1. **You are about to state how an external system currently behaves** —
-   a framework, library, SDK, CLI tool, API, or service's schema, defaults,
-   exit codes, config flags, pricing, rate limits, version-specific behavior,
-   or "does X support Y." This includes cases that feel like common
-   knowledge — exit-code conventions, hook payload shapes, and default
-   values are exactly where confident misremembering happens.
-2. **You are about to state a performance, cost, or timing number that
-   wasn't produced by an actual run in this session** — "this should take
-   ~X," "this is O(n)," "this will cost about $Y," "this should be fast
-   enough." An estimate rendered with confidence is still an estimate.
-
-## Procedure
-
-- For claim (1): `WebFetch` the tool's official documentation first. If the
-  official docs don't cover it, `WebSearch` and cite what you find. Quote the
-  relevant part back rather than paraphrasing from memory — paraphrasing
-  reintroduces the same risk you're trying to avoid.
-- For claim (2): if the stakes justify it (the number feeds a design
-  decision, a rejection/deferral, or something the user will act on),
-  actually run it — a real benchmark, a real timing, a real measurement —
-  instead of reasoning about what it "should" be. If running it isn't
-  feasible, say explicitly that the number is an unverified estimate; don't
-  present it with the same confidence as a measured fact.
-- If a fetch or search comes back inconclusive or contradicts your prior
-  assumption, say so and show the source — don't quietly reconcile it into
-  something that sounds more confident than what you actually found.
-
-## SKIP — don't over-trigger
-
-- **The claim is about this repository's own code**, not an external system.
-  Reading the actual source here already is the authoritative check; no web
-  verification needed.
-- **The user supplied the fact or number directly** in this conversation —
-  trust their firsthand statement, don't second-guess it with a search.
-- **Already verified this session** — don't re-fetch the same source
-  redundantly if it was already checked earlier in this conversation and
-  nothing suggests it changed.
-- **Generic, non-version-specific CS/engineering knowledge** (what a hash map
-  is, what Big-O notation means) — this isn't tied to any particular tool's
-  current implementation, so there's nothing to go stale.
-
-## Why this is a skill, not just a hook
-
-The `tier-router.js` reminder is a keyword net — cheap, broad, and it can
-only nudge, not judge whether a specific sentence you're about to write is
-actually an unverified claim. The judgment call is still yours: notice when
-you're about to assert something you haven't actually checked this session,
-regardless of whether a keyword happened to fire.
+---
+name: verify-before-claim
+description: "Verify external framework/API claims and unmeasured perf/cost estimates against an authoritative source before asserting them, instead of answering from training memory."
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+metadata:
+  type: harness-discipline
+---
+
+# Verify Before Claim
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | About to state how an external system (framework/library/SDK/API/service) currently behaves, or about to state an unmeasured performance/cost/timing number. |
+| **Expected Output** | The claim is backed by a `WebFetch`/`WebSearch`-sourced quote from authoritative docs, or an actual measurement — never asserted from training memory alone. |
+| **State Mutations** | None — this is a discipline governing what gets asserted in the response, not a file-mutating skill. |
+| **Enforcement Gate** | An external-behavior claim without a same-session fetch/search backing it **MUST NOT** be asserted with confidence; an unmeasured number **MUST** be explicitly labeled as an estimate, not presented as fact. |
+
+Training memory goes stale and is easy to misremember with full confidence.
+This skill exists because that failure mode is real and already happened in
+this repo: an early claim that `rule-of-3.js`'s `process.exit(1)` blocked a
+Claude Code `PreToolUse` hook was wrong — the official docs say only
+`exit(2)` blocks, `exit(1)` is a non-blocking error — and it was only caught
+by actually fetching `code.claude.com/docs/en/hooks` instead of trusting the
+assumption. The circuit breaker had never blocked anything until that got
+checked.
+
+`harness-everything/scripts/tier-router.js` fires a lightweight keyword-based
+reminder for this automatically (`UserPromptSubmit`, "FACT-AUDIT REMINDER"
+block) so you don't have to be manually pushed into checking every time. This
+file is the actual discipline behind that reminder.
+
+## TRIGGER — verify before asserting, don't skip because the answer "feels obvious"
+
+Whenever either is true:
+
+1. **You are about to state how an external system currently behaves** —
+   a framework, library, SDK, CLI tool, API, or service's schema, defaults,
+   exit codes, config flags, pricing, rate limits, version-specific behavior,
+   or "does X support Y." This includes cases that feel like common
+   knowledge — exit-code conventions, hook payload shapes, and default
+   values are exactly where confident misremembering happens.
+2. **You are about to state a performance, cost, or timing number that
+   wasn't produced by an actual run in this session** — "this should take
+   ~X," "this is O(n)," "this will cost about $Y," "this should be fast
+   enough." An estimate rendered with confidence is still an estimate.
+
+## Procedure
+
+- For claim (1): `WebFetch` the tool's official documentation first. If the
+  official docs don't cover it, `WebSearch` and cite what you find. Quote the
+  relevant part back rather than paraphrasing from memory — paraphrasing
+  reintroduces the same risk you're trying to avoid.
+- For claim (2): if the stakes justify it (the number feeds a design
+  decision, a rejection/deferral, or something the user will act on),
+  actually run it — a real benchmark, a real timing, a real measurement —
+  instead of reasoning about what it "should" be. If running it isn't
+  feasible, say explicitly that the number is an unverified estimate; don't
+  present it with the same confidence as a measured fact.
+- If a fetch or search comes back inconclusive or contradicts your prior
+  assumption, say so and show the source — don't quietly reconcile it into
+  something that sounds more confident than what you actually found.
+
+## SKIP — don't over-trigger
+
+- **The claim is about this repository's own code**, not an external system.
+  Reading the actual source here already is the authoritative check; no web
+  verification needed.
+- **The user supplied the fact or number directly** in this conversation —
+  trust their firsthand statement, don't second-guess it with a search.
+- **Already verified this session** — don't re-fetch the same source
+  redundantly if it was already checked earlier in this conversation and
+  nothing suggests it changed.
+- **Generic, non-version-specific CS/engineering knowledge** (what a hash map
+  is, what Big-O notation means) — this isn't tied to any particular tool's
+  current implementation, so there's nothing to go stale.
+
+## Why this is a skill, not just a hook
+
+The `tier-router.js` reminder is a keyword net — cheap, broad, and it can
+only nudge, not judge whether a specific sentence you're about to write is
+actually an unverified claim. The judgment call is still yours: notice when
+you're about to assert something you haven't actually checked this session,
+regardless of whether a keyword happened to fire.

package/zoom-out/SKILL.md

@@ -1,90 +1,90 @@
----
-name: zoom-out
-description: Reflect-first circuit breaker - rebuild the full picture and fact-check assumptions when stuck; escalate to the human only for genuine decisions.
-author: Miya Daniel | Harness Core Team
-version: 0.2.0
----
-
-# Zoom Out (Global Perspective & Circuit Breaker)
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Terminal script failures 3 times in a row, or getting stuck in an infinite loop. Input: Error logs. |
-| **Expected Output** | Reflection report written to disk. Terminal commands MUST STOP until the report is completed. |
-| **State Mutations** | MUST write `zoom-out-report.md` at the exact path the Rule of 3 breaker message gives you (session-scoped under `.claude/harness-state/sessions/<id>/`). |
-| **Enforcement Gate** | The `rule-of-3.js` script (if run via Hook or CLI) will block all other `Write` or `Edit` actions until that `zoom-out-report.md` exists and is formatted correctly. |
-
-This skill is the **Ultimate Circuit Breaker** in the Harness system.
-It MUST be forcefully triggered when the Agent falls into logic blind spots, invalid retries, or hits the Reasoning Ceiling.
-
-Its purpose is **NOT** to hand the problem to the human. The most common fatal flaw when stuck is failing to step back and rebuild a complete overview of the problem — three failures in a row almost always share one unverified assumption. This skill forces that step. The Human Partner is interrupted only when there is a genuine **decision** that belongs to them, never as a substitute for reflection you have not done yet.
-
-> **Platform note**: only Claude Code enforces this breaker physically (hooks lock mutating tools; a valid report releases them). On advisory-only platforms (Cursor, Copilot, Gemini CLI, Codex CLI...) nothing will stop you — the protocol is identical and **self-enforced**: stop at 3 failures, run Phases 1-4 exactly as written, and still write the report file as the reflection artifact.
-
-## 1. Triggers
-- **Rule of 3 (Micro-error looping)**: This is the most common fatal flaw of AI. If attempting to fix the same error, same test failure, or same logic fails 3 times consecutively, or if constantly making minor invalid changes in the same place (e.g., repeatedly changing variable names or adding console.log but it's still broken).
-- **Divergence Phenomenon**: Fixing one Bug leads to 2 new Bugs, and fixing those triggers even more errors.
-- **Attention Loss**: You realize you have forgotten the initial task goal, or the files being modified deviate too far from the original goal.
-- **Human Intervention**: The user explicitly instructs "zoom out", "step back and look", or "stop and think".
-
-## 2. Phase 1 — Cease Fire
-- **ABSOLUTELY PROHIBITED** from proposing any new code modification suggestions.
-- **ABSOLUTELY PROHIBITED** from saying "I understand, I will fix it using the following method..." — that sentence is the tunnel talking.
-- **Do NOT message the Human Partner yet.** "I failed 3 times" is not yet a report worth their time; reflection comes first.
-
-## 3. Phase 2 — Rebuild the Full Picture (Reflect & Fact-Check)
-Use **READ-ONLY tools** (Read / Grep / Glob) — they remain available while the breaker is locked. No guessing in this phase; only evidence.
-
-1. **Restate the original goal** — from the task / todo list, not from your memory of the current rabbit hole. Ask: does the thing I have been fighting even matter to this goal?
-2. **List each failed attempt and extract the assumption behind it.** Every fix attempt encoded a belief about the system; name each belief explicitly.
-3. **Fact-check every assumption against reality.** Open the actual file, the actual log, the actual config, the actual upstream data, the actual docs. Replace every "it should be" with "I looked, and it is".
-4. **Raise the altitude.** Is this even the right layer? Is the module doing what the architecture intends? Did upstream pass wrong data? Is this a framework limitation? Do two requirements contradict each other?
-5. **Form a fresh diagnosis** that explains **ALL** observed evidence — including why all previous attempts failed — not just the latest error message.
-
-## 4. Phase 3 — Write the Reflection Report
-Write your findings to the exact `zoom-out-report.md` path printed in the Rule of 3 block message — the ONLY write permitted while the breaker is locked. (If the file already exists from an earlier cycle, Read it first so you do not re-propose an already-falsified diagnosis.) Required sections:
-
-```markdown
-## Goal
-<the original task goal, restated from source>
-## Failed Attempts
-<attempt → the assumption it relied on → why it was wrong>
-## Verified Facts
-<only things you actually re-checked in Phase 2, each with where you looked>
-## Diagnosis
-<the fresh root-cause explanation covering all evidence>
-## Decision
-RESUME: <the new approach>   — or —   ESCALATE: <the decision the human must make>
-```
-
-A valid report automatically releases the circuit breaker. This is not paperwork — the hook checks it precisely because writing it honestly IS the reflection.
-
-## 5. Phase 4 — Decision Gate: Resume or Escalate
-
-**RESUME (the default and expected outcome)** when the fresh diagnosis yields a genuinely NEW path — a different layer, different root cause, or different approach, not a variation of the attempts that already failed — and it is within your existing authority and task scope. Self-recovery is what zoom-out is for.
-
-**ESCALATE only when the blocker is a decision that belongs to a human**, such as:
-- Requirements contradict each other, or the goal itself is ambiguous.
-- The fix requires an architecture / scope trade-off the human has not sanctioned (rewriting a module, changing a public API, dropping a requirement).
-- The path forward is destructive or irreversible (data migration, force push, deleting user data).
-- You lack access only the human can grant (credentials, environment, third-party service).
-- This is the SECOND breaker trip on the same failure signature — reflection already had its shot; the hook hard-locks and the human decides.
-
-**"I am not capable of fixing this" is NOT an escalation reason** — that conclusion is usually the tunnel still talking; zoom out further instead. **"This requires a choice only you can make"** is.
-
-## 6. Escalation Format (only when genuinely needed)
-Hand the human a **decision**, not a plea:
-
-> "Goal: [...]. I falsified paths X, Y, Z — verified facts: [...].
-> The real blocker is a [requirement conflict / architecture trade-off / destructive step / access gap], which is your call, not mine.
-> Option A: [...] (trade-off: ...). Option B: [...] (trade-off: ...).
-> I recommend A because [...]. Which direction do you choose?"
-
-Banned: "I have tried everything and failed, please help." That reports incapability, not a decision.
-
-## 7. Recovery
-- **Self-recovery path**: a valid report ending in `RESUME` releases the breaker — reload the appropriate execution mode (`tdd`, `fable-mode`) and execute the new diagnosis. If the SAME failure signature accumulates 3 more failures, the breaker hard-locks and the decision goes to the human.
-- **Human path**: after the human answers an `ESCALATE`, or clears a hard lock (`npm run harness:reset` in their own terminal, or a new session / `/clear`), continue under their direction.
-- Either way, once the problem is ultimately cracked, feed the insight to `self-evolve`.
+---
+name: zoom-out
+description: Reflect-first circuit breaker - rebuild the full picture and fact-check assumptions when stuck; escalate to the human only for genuine decisions.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Zoom Out (Global Perspective & Circuit Breaker)
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Terminal script failures 3 times in a row, or getting stuck in an infinite loop. Input: Error logs. |
+| **Expected Output** | Reflection report written to disk. Terminal commands MUST STOP until the report is completed. |
+| **State Mutations** | MUST write `zoom-out-report.md` at the exact path the Rule of 3 breaker message gives you (session-scoped under `.claude/harness-state/sessions/<id>/`). |
+| **Enforcement Gate** | The `rule-of-3.js` script (if run via Hook or CLI) will block all other `Write` or `Edit` actions until that `zoom-out-report.md` exists and is formatted correctly. |
+
+This skill is the **Ultimate Circuit Breaker** in the Harness system.
+It MUST be forcefully triggered when the Agent falls into logic blind spots, invalid retries, or hits the Reasoning Ceiling.
+
+Its purpose is **NOT** to hand the problem to the human. The most common fatal flaw when stuck is failing to step back and rebuild a complete overview of the problem — three failures in a row almost always share one unverified assumption. This skill forces that step. The Human Partner is interrupted only when there is a genuine **decision** that belongs to them, never as a substitute for reflection you have not done yet.
+
+> **Platform note**: only Claude Code enforces this breaker physically (hooks lock mutating tools; a valid report releases them). On advisory-only platforms (Cursor, Copilot, Gemini CLI, Codex CLI...) nothing will stop you — the protocol is identical and **self-enforced**: stop at 3 failures, run Phases 1-4 exactly as written, and still write the report file as the reflection artifact.
+
+## 1. Triggers
+- **Rule of 3 (Micro-error looping)**: This is the most common fatal flaw of AI. If attempting to fix the same error, same test failure, or same logic fails 3 times consecutively, or if constantly making minor invalid changes in the same place (e.g., repeatedly changing variable names or adding console.log but it's still broken).
+- **Divergence Phenomenon**: Fixing one Bug leads to 2 new Bugs, and fixing those triggers even more errors.
+- **Attention Loss**: You realize you have forgotten the initial task goal, or the files being modified deviate too far from the original goal.
+- **Human Intervention**: The user explicitly instructs "zoom out", "step back and look", or "stop and think".
+
+## 2. Phase 1 — Cease Fire
+- **ABSOLUTELY PROHIBITED** from proposing any new code modification suggestions.
+- **ABSOLUTELY PROHIBITED** from saying "I understand, I will fix it using the following method..." — that sentence is the tunnel talking.
+- **Do NOT message the Human Partner yet.** "I failed 3 times" is not yet a report worth their time; reflection comes first.
+
+## 3. Phase 2 — Rebuild the Full Picture (Reflect & Fact-Check)
+Use **READ-ONLY tools** (Read / Grep / Glob) — they remain available while the breaker is locked. No guessing in this phase; only evidence.
+
+1. **Restate the original goal** — from the task / todo list, not from your memory of the current rabbit hole. Ask: does the thing I have been fighting even matter to this goal?
+2. **List each failed attempt and extract the assumption behind it.** Every fix attempt encoded a belief about the system; name each belief explicitly.
+3. **Fact-check every assumption against reality.** Open the actual file, the actual log, the actual config, the actual upstream data, the actual docs. Replace every "it should be" with "I looked, and it is".
+4. **Raise the altitude.** Is this even the right layer? Is the module doing what the architecture intends? Did upstream pass wrong data? Is this a framework limitation? Do two requirements contradict each other?
+5. **Form a fresh diagnosis** that explains **ALL** observed evidence — including why all previous attempts failed — not just the latest error message.
+
+## 4. Phase 3 — Write the Reflection Report
+Write your findings to the exact `zoom-out-report.md` path printed in the Rule of 3 block message — the ONLY write permitted while the breaker is locked. (If the file already exists from an earlier cycle, Read it first so you do not re-propose an already-falsified diagnosis.) Required sections:
+
+```markdown
+## Goal
+<the original task goal, restated from source>
+## Failed Attempts
+<attempt → the assumption it relied on → why it was wrong>
+## Verified Facts
+<only things you actually re-checked in Phase 2, each with where you looked>
+## Diagnosis
+<the fresh root-cause explanation covering all evidence>
+## Decision
+RESUME: <the new approach>   — or —   ESCALATE: <the decision the human must make>
+```
+
+A valid report automatically releases the circuit breaker. This is not paperwork — the hook checks it precisely because writing it honestly IS the reflection.
+
+## 5. Phase 4 — Decision Gate: Resume or Escalate
+
+**RESUME (the default and expected outcome)** when the fresh diagnosis yields a genuinely NEW path — a different layer, different root cause, or different approach, not a variation of the attempts that already failed — and it is within your existing authority and task scope. Self-recovery is what zoom-out is for.
+
+**ESCALATE only when the blocker is a decision that belongs to a human**, such as:
+- Requirements contradict each other, or the goal itself is ambiguous.
+- The fix requires an architecture / scope trade-off the human has not sanctioned (rewriting a module, changing a public API, dropping a requirement).
+- The path forward is destructive or irreversible (data migration, force push, deleting user data).
+- You lack access only the human can grant (credentials, environment, third-party service).
+- This is the SECOND breaker trip on the same failure signature — reflection already had its shot; the hook hard-locks and the human decides.
+
+**"I am not capable of fixing this" is NOT an escalation reason** — that conclusion is usually the tunnel still talking; zoom out further instead. **"This requires a choice only you can make"** is.
+
+## 6. Escalation Format (only when genuinely needed)
+Hand the human a **decision**, not a plea:
+
+> "Goal: [...]. I falsified paths X, Y, Z — verified facts: [...].
+> The real blocker is a [requirement conflict / architecture trade-off / destructive step / access gap], which is your call, not mine.
+> Option A: [...] (trade-off: ...). Option B: [...] (trade-off: ...).
+> I recommend A because [...]. Which direction do you choose?"
+
+Banned: "I have tried everything and failed, please help." That reports incapability, not a decision.
+
+## 7. Recovery
+- **Self-recovery path**: a valid report ending in `RESUME` releases the breaker — reload the appropriate execution mode (`tdd`, `fable-mode`) and execute the new diagnosis. If the SAME failure signature accumulates 3 more failures, the breaker hard-locks and the decision goes to the human.
+- **Human path**: after the human answers an `ESCALATE`, or clears a hard lock (`npm run harness:reset` in their own terminal, or a new session / `/clear`), continue under their direction.
+- Either way, once the problem is ultimately cracked, feed the insight to `self-evolve`.