harness-everything 0.2.2 → 0.4.0

package/plugins/harness-everything/skills/todo-driven-workflow/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: todo-driven-workflow
+description: "Enforce a deliberate step-by-step execution loop for complex multi-step or multi-file tasks (Tier 2/3), one sub-task in-progress at a time. USE FOR: \"track a complex multi-step task as todos\", \"work through a multi-file refactor step by step\". DO NOT USE FOR: \"trivial single-file edits\", \"quick questions without implementation\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Todo-Driven Workflow
+
+Single-task milestones prevent context drift in Tier 2/3 work.
+
+## USE FOR:
+- Track multi-step, multi-file development tasks
+- Enforce exactly one active milestone
+
+## DO NOT USE FOR:
+- Trivial single-file edits
+- Parallel sub-agent state without worktree isolation (`using-git-worktrees`)
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Tier 2/3 task with a high-level description. |
+| **Expected Output** | Native TODO state or a Markdown checklist with verifiable milestones. |
+| **State Mutations** | Host-native TODO state or `<workspace>/tasks/todo.md` / `<workspace>/.github/harness-everything/todo.md`. |
+| **Enforcement Gate** | Exactly one milestone is `in-progress`; verify before marking it complete. |
+
+## Execution Loop: Think > Try > Summarize > Record
+
+1. [Think] State the goal and split it into 3-7 checkable milestones.
+2. [Record] Initialize the native host tracker before edits; if unavailable, create a Markdown checklist.
+3. Start exactly one milestone, execute only its scope, and run its named check.
+4. Mark it complete only after evidence passes; then start the next milestone.
+5. Record blockers in the checklist and escalate after the applicable circuit-breaker threshold.
+
+Native TODO tools take priority. Markdown is portable fallback; this skill
+does not depend on a repository CLI state machine.
+
+Deep dive: <this-skill-dir>/references/execution-guide.md

package/plugins/harness-everything/skills/todo-driven-workflow/references/execution-guide.md

@@ -0,0 +1,27 @@
+# Execution Guide (Deep Dive)
+
+## Tracker selection
+
+```mermaid
+flowchart TD
+  Start[Task needs milestones] --> Native{Native TODO tracker available?}
+  Native -->|Yes| Host[Use the host tracker]
+  Native -->|No| Markdown[Create tasks/todo.md or .github/harness-everything/todo.md]
+  Host --> One[Keep exactly one item in-progress]
+  Markdown --> One
+  One --> Check[Run the named verification command]
+  Check --> Record[Record evidence and mark the item complete]
+```
+
+## Rules
+
+1. Define 3-7 verifiable milestones before changing files.
+2. Prefer the host's native TODO tool and preserve its status history.
+3. If no native tracker exists, use a Markdown checklist in the repository or platform project-instructions area.
+4. Each item names its output, pass condition, and verification command.
+5. Keep one item `in-progress`; complete it from evidence before starting another.
+6. When parallel agents are active, isolate their writes with `using-git-worktrees` and merge only after scope review.
+
+The former repository TODO CLI is intentionally not a fallback. This keeps
+tracking native to the host or transparent in Markdown and avoids shared
+cross-session state collisions.

package/plugins/harness-everything/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: using-git-worktrees
+description: Use when starting feature work needing isolation or before implementation plans - ensures an isolated workspace via native tools or git worktree fallback
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Using Git Worktrees
+
+Use native tools first; git fallback.
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Isolation-needing feature work; pre-plan setup. |
+| **Expected Output** | Isolated workspace plus clean test baseline. |
+| **State Mutations** | Creates `.worktrees/<branch>`; updates `.gitignore` if needed. |
+| **Enforcement Gate** | Detect existing isolation first; seamless sandbox fallback. |
+
+## Workflow
+
+**Step 0 — Detect existing isolation** (adapt per `environment-detection`):
+```bash
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git branch --show-current
+git rev-parse --show-superproject-working-tree
+```
+Dirs differ and no superproject → already isolated; skip to Step 2; never nest. Superproject → submodule (normal repo). Else honor declared preference or ask consent; declined → in place.
+
+**Step 1 — Create**: native tool (`EnterWorktree`, `/worktree`, `--worktree`) first — raw git creates phantom state. Else verify ignored via `git check-ignore -q .worktrees || git check-ignore -q worktrees`; unignored → add to .gitignore and commit. Then `git worktree add "$path" -b "$BRANCH_NAME"` at declared preference, existing `.worktrees/`/`worktrees/`, or default `.worktrees/`. Sandbox denial → work in place.
+
+**Step 2 — Setup**: npm/cargo/pip/poetry/go.
+
+**Step 3 — Baseline**: run tests (`npm test`/`cargo test`/`pytest`/`go test ./...`); failures → report, ask.
+
+Deep dive: <this-skill-dir>/references/workflow-details.md
+
+## USE FOR:
+- feature work needing isolation
+- pre-implementation-plan setup
+- native vs manual `git worktree add`
+
+## DO NOT USE FOR:
+- nesting inside an existing worktree
+- branch/merge workflows

package/plugins/harness-everything/skills/using-git-worktrees/references/workflow-details.md

@@ -0,0 +1,108 @@
+# Using Git Worktrees — Full Workflow Reference
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Need Workspace Isolation] --> CheckIso{1. Already in Worktree?}
+
+    CheckIso -- Yes (GIT_DIR != GIT_COMMON) --> Setup[3. Run Project Setup & Dependencies]
+    CheckIso -- No (Normal Repo) --> CheckNative{2. Native Worktree Tool Available?}
+
+    CheckNative -- Yes --> RunNative[Use Native Worktree Tool] --> Setup
+    CheckNative -- No --> RunGit[Try git worktree add .worktrees/branch]
+
+    RunGit -- Success --> Setup
+    RunGit -- Fails / Denied --> WorkInPlace[Fallback: Work in Place in Current Directory] --> Setup
+
+    Setup --> RunBaseline[4. Verify Clean Test Baseline]
+    RunBaseline --> Done[Isolated Workspace Ready]
+```
+
+## Step 0 detail
+
+**Submodule guard:** `git-dir` differs from `git-common-dir` inside git submodules as well. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```bash
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree
+```
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
+
+> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
+
+Honor any existing declared preference without asking. If the user declines consent, work in place and skip to project setup.
+
+## Step 1a detail — native tools
+
+The user has asked for an isolated workspace. Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to setup.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only use the git fallback if you have no native worktree tool available.
+
+## Step 1b detail — directory selection priority
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+2. **Check for an existing project-local worktree directory:** Check if `.worktrees/` or `worktrees/` exists using cross-platform file system tools (`read_file` / `list_dir` or native shell test commands). If found, use it. If both exist, `.worktrees` wins.
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+### Safety verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```bash
+git check-ignore -q .worktrees || git check-ignore -q worktrees
+```
+
+**If NOT ignored:** Add to .gitignore, commit the change, then proceed.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+### Create the worktree
+
+```bash
+# Determine path based on chosen location
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
+
+## Step 2 detail — project setup
+
+Auto-detect and run appropriate setup:
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## Step 3 detail — baseline report
+
+If tests fail: report failures, ask whether to proceed or investigate. If tests pass:
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```

package/plugins/harness-everything/skills/verification-loop/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: verification-loop
+description: "Run objective verification gates (build, types, lint, tests, security scan) before claiming work done. USE FOR: \"run the full verification loop\", \"verify this is done before delivery\". DO NOT USE FOR: \"design discussions with no completed work\", \"planning without code changes\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Verification Loop
+
+Run objective quality gates before claiming a change is ready.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Completed implementation or change awaiting delivery. |
+| **Expected Output** | Evidence-backed verification report and delivery decision. |
+| **State Mutations** | Fills a report from `<this-skill-dir>/templates/verification-report.template.md`. |
+| **Enforcement Gate** | Build, type, lint, test, security, and diff gates all pass. |
+
+## USE FOR:
+
+- Verify a feature or change before delivery
+- Run quality gates before a PR
+
+## DO NOT USE FOR:
+
+- Fixing failures without re-running the loop
+- Writing new features or tests (use `tdd`)
+
+## Workflow
+
+Never claim completion until every applicable gate passes. On failure, fix the cause
+and rerun from the first affected gate.
+
+1. Build: `npm run build`.
+2. Types: `npx tsc --noEmit` or `pyright .`.
+3. Lint: `npm run lint` or `ruff check .`.
+4. Tests and coverage: `npm run test -- --coverage`.
+5. Security scan: secrets and stray logs.
+6. Diff review: `git diff --stat` and unintended-change checks.
+7. Fill `<this-skill-dir>/templates/verification-report.template.md` with evidence.
+
+Deep dive: `<this-skill-dir>/references/verification-phases.md`

package/plugins/harness-everything/skills/verification-loop/references/verification-phases.md

@@ -0,0 +1,116 @@
+# Verification Phases (Deep Dive)
+
+## Decision Flow
+
+```mermaid
+flowchart TD
+    Start[Trigger: Pre-Delivery / PR Verification] --> Build[1. Phase 1: Build Verification]
+    Build --> Type[2. Phase 2: Type Check]
+    Type --> Lint[3. Phase 3: Lint Check]
+    Lint --> Test[4. Phase 4: Test Suite Execution]
+    Test --> Security[5. Phase 5: Security & Secret Scan]
+    Security --> Diff[6. Phase 6: Diff Review]
+    
+    Diff --> CheckScript{7. Is verify-gate.js / Template Available?}
+    
+    CheckScript -- Yes --> RunScript[Run harness-everything/scripts/verify-gate.js / Fill verification-report.template.md]
+    CheckScript -- No --> DirectReport[Output Verification Report Inline in Response]
+    
+    RunScript --> ReportResult{All Verification Gates Passed?}
+    DirectReport --> ReportResult
+    
+    ReportResult -- Exit 0 / All Green --> Deliver[Task Ready for Delivery / PR]
+    ReportResult -- Failures Detected --> Fix[Fix Issues in Code & Re-verify] --> Build
+```
+
+Adapt commands according to the project's ecosystem and active environment (`environment-detection`). Run commands directly without non-portable POSIX pipe assumptions (avoid raw `head`, `tail`, `grep`, `2>/dev/null` piping on Windows).
+
+## Phase 1: Build Verification
+
+```bash
+# Check if project builds (JS/TS example)
+npm run build
+# OR
+pnpm build
+```
+
+If build fails, STOP and fix before continuing.
+
+## Phase 2: Type Check
+
+```bash
+# TypeScript projects
+npx tsc --noEmit
+
+# Python projects
+pyright .
+```
+
+Report all type errors. Fix critical ones before continuing.
+
+## Phase 3: Lint Check
+
+```bash
+# JavaScript/TypeScript
+npm run lint
+
+# Python
+ruff check .
+```
+
+## Phase 4: Test Suite
+
+```bash
+# Run tests with coverage
+npm run test -- --coverage
+
+# Check coverage threshold
+# Target: 80% minimum
+```
+
+Report:
+- Total tests: X
+- Passed: X
+- Failed: X
+- Coverage: X%
+
+## Phase 5: Security & Code Hygiene Scan
+
+Use native IDE search tools (`grep_search` / `file_search`) or cross-platform scripts rather than raw terminal `grep` pipes:
+- Check for hardcoded API keys / secrets (`sk-`, `api_key`).
+- Check for leftover debug log statements (`console.log`, `print`).
+
+## 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, fill in `verification-loop/templates/verification-report.template.md` with the actual results and present it.
+
+## 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/plugins/harness-everything/skills/verification-loop/templates/verification-report.template.md

@@ -0,0 +1,15 @@
+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. ...

package/plugins/harness-everything/skills/verify-before-claim/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: verify-before-claim
+description: "Verify external framework/API claims and unmeasured perf/cost estimates against an authoritative source before asserting them. Use when stating how an external framework, SDK, CLI, or API behaves, or quoting numbers not produced by a real run; output is a cited claim, a real measurement, or a labeled estimate."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Verify Before Claim
+
+Verify external behavior and unmeasured numbers before asserting them.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | External behavior, version/config/exit-code claim, or unmeasured number. |
+| **Expected Output** | Official citation, real measurement, or explicitly labeled estimate. |
+| **State Mutations** | None; evidence is returned with the claim. |
+| **Enforcement Gate** | Official source or real measurement; unresolved claims stay inconclusive. |
+
+## Core Flow
+
+1. For this repository, read the local source and report observed facts.
+2. For external behavior, use official documentation first and cite it.
+3. For numbers, run a real measurement or label the result an estimate.
+4. Report contradictions or missing evidence as inconclusive.
+
+## USE FOR:
+- Stating how an external framework, SDK, CLI tool, or API behaves
+- Quoting performance, cost, latency, or timing numbers
+- Answering "does X support Y" or version-specific questions
+- Citing defaults, exit codes, config flags, pricing, or rate limits
+
+## DO NOT USE FOR:
+- Claims about this repository's own code (read the actual source)
+- Facts the user supplied directly in this conversation
+- Generic CS/engineering knowledge (e.g. Big-O) that can't go stale
+
+Never claim an unverified external fact as certain, even under time pressure.
+
+Deep dive: `<this-skill-dir>/references/verification-guide.md`

package/plugins/harness-everything/skills/verify-before-claim/references/verification-guide.md

@@ -0,0 +1,73 @@
+# Verification Guide — details moved from SKILL.md
+
+## 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.
+
+## Decision matrix (reference)
+
+```mermaid
+flowchart TD
+    Start[About to Assert External API / Framework Behavior or Perf Number] --> CheckScope{1. Claim Scope Check}
+    
+    CheckScope -- Internal Repo Code --> ReadCode[Read Local Source Code -> State Facts]
+    CheckScope -- External Framework / API / Number --> CheckNet{2. Web Fetch / Search / Measurement Available?}
+    
+    CheckNet -- Yes --> FetchDocs[WebFetch Official Docs / Measure Real Execution]
+    FetchDocs --> CiteDocs[Quote Authoritative Source / State Measured Data]
+    
+    CheckNet -- No / Offline --> EstimateFallback[Explicitly Label Response as Unverified Estimate]
+    
+    ReadCode --> Done[Verified Output]
+    CiteDocs --> Done
+    EstimateFallback --> Done
+```

package/plugins/harness-everything/skills/zoom-out/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: zoom-out
+description: "Reflect-first circuit breaker - after 3 failures, stop edits, rebuild the full picture with read-only tools, write a fact-check report, then resume or escalate. USE FOR: \"you are stuck in a loop\", \"the same error keeps failing\", \"rethink your assumptions\". DO NOT USE FOR: \"routine single-failure debugging\", \"greenfield planning without failures\"."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.4.0
+---
+
+# Zoom Out (Circuit Breaker)
+
+Stop repeated failures, rebuild the facts, and choose a safe next step.
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Three same-signature failures or an explicit loop/rethink request. |
+| **Expected Output** | Fact-checked report ending in `RESUME` or `ESCALATE`. |
+| **State Mutations** | Writes the session `zoom-out-report.md`; reset may clear breaker state. |
+| **Enforcement Gate** | `<skills-repo-root>/hooks/scripts/rule-of-3.js` plus a valid report; reset only after the second cycle. |
+
+## Circuit Breaker Flow
+
+1. After three same-signature failures, stop edits and do not ask the user yet.
+2. Use read-only tools to restate the goal and check files, configuration, and logs.
+3. Fill `<this-skill-dir>/templates/zoom-out-report.template.md` and end with `RESUME` or `ESCALATE`.
+4. Resume only on an untried path; escalate genuine user decisions with options.
+5. Clear a repeated breaker cycle with `npm run harness:reset`; record the insight with `self-evolve`.
+
+## USE FOR:
+- "you are stuck in a loop"
+- "the same error keeps failing"
+- "rethink your assumptions"
+
+## DO NOT USE FOR:
+- Routine single-failure debugging — fix it directly
+- Greenfield planning without failures (`fable-mode`)
+
+Never retry the same approach after the third failure, even under pressure.
+
+Deep dive: `<this-skill-dir>/references/circuit-breaker.md`

package/plugins/harness-everything/skills/zoom-out/references/circuit-breaker.md

@@ -0,0 +1,66 @@
+# Zoom Out — Circuit Breaker (Full Detail)
+
+## Process & Circuit Breaker Resolution Flow
+
+Follow the decision matrix below when hitting a circuit breaker:
+
+```mermaid
+flowchart TD
+    Start[Trigger: 3 Consecutive Failures / Goal Drift] --> CeaseFire[1. Phase 1: Cease Fire - Stop Code Edits Immediately]
+    CeaseFire --> Rebuild[2. Phase 2: Rebuild Full Picture using Read-Only Tools]
+    Rebuild --> CheckPath{3. Resolve Reflection Report Path}
+
+    CheckPath -- Session Path Provided --> WriteSession[Copy template to Session zoom-out-report.md]
+    CheckPath -- Template / Path Unavailable --> WritePlatform[Write to .github/harness-everything/zoom-out-report.md or Inline]
+
+    WriteSession --> DecisionGate{4. Phase 4: Decision Gate}
+    WritePlatform --> DecisionGate
+
+    DecisionGate -- Clear Untried Path Identified --> Resume[RESUME: Execute Fresh Diagnosis in TDD / Fable]
+    DecisionGate -- Requirement Conflict / Access Gap --> Escalate[ESCALATE: Present 2-3 Options + Recommendation to Human]
+
+    Resume --> Resolved{5. Problem Cracking Succeeds?}
+    Resolved -- Yes --> SelfEvolve[Call self-evolve to Persist Insight]
+    Resolved -- No (3 More Failures) --> Escalate
+```
+
+## 1. Triggers
+- **Rule of 3 (Repeated Failures)**: Attempting to fix the same error or test failure 3 times without progress.
+- **Divergence**: Fixing one bug repeatedly introduces new secondary errors.
+- **Goal Drift**: Execution strays far from the initial task objective.
+- **User Instruction**: The user requests a step back ("zoom out", "step back", "stop and think").
+
+## 2. Phase 1 — Cease Fire
+- Pause code editing attempts immediately.
+- Refrain from guessing quick fixes without checking underlying facts first.
+
+## 3. Phase 2 — Rebuild Full Picture (Reflect & Fact-Check)
+Use read-only tools (Read / Grep / Glob) to gather fresh evidence:
+1. **Restate Goal**: Review original objectives from task/todo context.
+2. **Examine Failed Attempts**: Identify the underlying belief behind each failed fix.
+3. **Fact-Check Assumptions**: Verify files, configuration, logs, and docs directly.
+4. **Elevate Perspective**: Check for layer mismatches, API contract misunderstandings, or conflicting requirements.
+5. **Form Fresh Diagnosis**: Synthesize a comprehensive explanation that accounts for all observed evidence.
+
+## 4. Phase 3 — Write Reflection Report
+Copy `zoom-out/templates/zoom-out-report.template.md` to the `zoom-out-report.md` path given in the Rule of 3 message and fill it in section by section.
+
+A complete report automatically releases the circuit breaker on hook-enabled systems.
+
+## 5. Phase 4 — Decision Gate: Resume or Escalate
+
+- **RESUME**: Selected when the fresh diagnosis identifies a clear, untried path within existing authority.
+- **ESCALATE**: Reserved for true decision points belonging to the user (conflicting requirements, destructive migration, missing credentials/access, or repeated breaker trips).
+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`.

package/plugins/harness-everything/skills/zoom-out/templates/zoom-out-report.template.md

@@ -0,0 +1,20 @@
+## Goal
+<original task goal>
+
+## Failed Attempts
+<attempt → underlying assumption → observed outcome>
+**Failure Category:** <syntax|environment|test|timeout|permission|dependency|unknown>
+
+## Verified Facts
+<facts re-checked in Phase 2 with file paths>
+**Files Checked:** <list at least 3 related files you actually read>
+**Error Message Verified:** <copy the exact error message from the last failure>
+
+## Diagnosis
+<comprehensive explanation of root cause>
+**Root Cause Type:** <Is this a syntax error, logic error, environment issue, or missing dependency?>
+
+## Decision
+RESUME: <new approach that addresses the root cause>   — or —   ESCALATE: <decision needed from user>
+
+**Why this approach will work:** <explain how it addresses the specific root cause identified>