harness-everything 0.2.2 → 0.4.0

package/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/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/verify-before-claim/SKILL.md

@@ -1,86 +1,43 @@
 ---
 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
+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:
-  type: harness-discipline
+  author: Miya Daniel
+  version: 0.4.0
 ---
 
 # Verify Before Claim
 
-## 📋 Skill Contract
+Verify external behavior and unmeasured numbers before asserting them.
+
+## 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.
+| **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. |
 
-## Procedure
+## Core Flow
 
-- 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.
+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.
 
-## SKIP — don't over-trigger
+## 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
 
-- **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.
+## 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
 
-## Why this is a skill, not just a hook
+Never claim an unverified external fact as certain, even under time pressure.
 
-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.
+Deep dive: `<this-skill-dir>/references/verification-guide.md`

package/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/zoom-out/SKILL.md

@@ -1,90 +1,42 @@
 ---
 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
+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 (Global Perspective & Circuit Breaker)
+# Zoom Out (Circuit Breaker)
 
-## 📋 Skill Contract
+Stop repeated failures, rebuild the facts, and choose a safe next step.
+
+## 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.
+| **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. |
 
-**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.
+## Circuit Breaker Flow
 
-**"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.
+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`.
 
-## 6. Escalation Format (only when genuinely needed)
-Hand the human a **decision**, not a plea:
+## USE FOR:
+- "you are stuck in a loop"
+- "the same error keeps failing"
+- "rethink your assumptions"
 
-> "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?"
+## DO NOT USE FOR:
+- Routine single-failure debugging — fix it directly
+- Greenfield planning without failures (`fable-mode`)
 
-Banned: "I have tried everything and failed, please help." That reports incapability, not a decision.
+Never retry the same approach after the third failure, even under pressure.
 
-## 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`.
+Deep dive: `<this-skill-dir>/references/circuit-breaker.md`

package/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/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>

package/build-multi-agent-system/AGENTS.md

@@ -1,50 +0,0 @@
-# build-multi-agent-system - AI Authoring Guide
-
-> This repository hosts a single, complex AI skill designed to deploy a multi-agent architecture. This document serves as a Meta-Authoring Guide, dictating how AI agents should interact with, modify, or extend this skill without breaking its core rules.
-
-## Directory Structure & Taxonomy
-
-Respect the semantic boundaries of this repository:
-
-| Directory/File | Purpose / Rules |
-|---|---|
-| `SKILL.md` | The core AI instruction file. Contains the environment audit, scaffolding rules, memory implementation, and router logic. |
-| `LICENSE` | The open-source license. Do not modify. |
-
-## How to Extend (Modifying the Skill)
-
-When asked by the user to update or extend the `build-multi-agent-system` skill, you **MUST strictly follow this procedure**:
-
-### 1. Locate and Read
-- Read the root `SKILL.md` to understand the existing execution pipeline, phase logic, and strict constraints.
-- Understand the "6 Functional Zones" and the "Bootstrap Protocol".
-
-### 2. Modify `SKILL.md`
-When updating the file, it MUST retain:
-- The YAML frontmatter block containing the `name` and `description`.
-- The `## Core Principles` section enforcing the cognitive loop (Think > Try > Summarize > Record).
-- The `## [State Checkpoint]` validating the working directory.
-- Sequential workflow phases (`[Discovery Phase...]`, `[Execution Phase...]`, `[Verification Phase]`).
-
-### 3. Provide Resources
-If adding complex features (e.g., a new fallback memory indexer script language), avoid bloating `SKILL.md`. Consider introducing an `examples/` directory to store reference code, though prefer keeping the core logic concise.
-
----
-
-## Frontmatter Schema
-
-The `SKILL.md` MUST always begin with this exact YAML structure:
-
-```yaml
----
-name: "build-multi-agent-system"
-description: >
-  Deploy a universal, self-adapting Multi-Agent Architecture into any project. It dynamically analyzes the tech stack to scaffold a token-efficient workspace with strict physical boundaries, hybrid SQLite memory, and isomorphic alignment protocols.
----
-```
-
-## Constraints & Gotchas
-
-- **Cognitive Loop Integrity**: Any new steps added to the skill must align with the Think > Try > Summarize > Record methodology.
-- **Isomorphism**: When adding tech-stack-specific scaffolding logic, do not break support for general repositories. The skill must remain polyglot.
-- **Variables**: Never use single braces `{}` for variables in prompts; use double braces `{{VARIABLE}}`. Keep instructions terse and directive.

package/build-multi-agent-system/README.md

@@ -1,63 +0,0 @@
-# build-multi-agent-system
-
-> Deploy a universal, self-adapting Multi-Agent Architecture into any project. It dynamically analyzes the tech stack to scaffold a token-efficient workspace with strict physical boundaries, hybrid SQLite memory, and isomorphic alignment protocols.
-
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-
-## Overview
-
-This skill installs the physical landing gear ("where the agent lives") for a multi-agent team inside any repository. By dynamically adapting to the project's native ecosystem, it enforces physical isolation of context and cognitive metabolism, preventing the agent team from drowning in unstructured logs. It sets up 6 distinct functional zones, a relational SQLite memory indexer, and an immutable `AGENTS.md` router to keep token burn low and mitigate hallucination.
-
----
-
-## Usage
-
-Invoke the skill in GitHub Copilot Chat (or your preferred AI agent) with a prompt like:
-
-- "Deploy a multi-agent system into this project"
-- "Install the multi-agent workspace architecture here"
-- "Set up the cognitive OS and functional zones for this repo"
-
----
-
-## How it Works (Workflow)
-
-When invoked, the skill automatically executes the following steps:
-
-1. **Environment Audit**: Analyzes the project's tech stack (e.g., `package.json`, `pyproject.toml`) and deduces required sub-agent roles, mandating a PM (Coordinator) and Challenger (Alignment Enforcer).
-2. **Structural Scaffolding**: Maps and creates the 6 Functional Zones (`[State]`, `[Logs]`, `[Decisions]`, `[Domain]`, `[Architecture]`, `[Roles]`) adapted to the project's ecosystem.
-3. **Hybrid Memory Implementation**: Generates a polyglot memory indexer script that parses YAML frontmatter/Markdown headers to build a local SQLite `memory.db` for low-token queries.
-4. **The Immutable Router**: Hardcodes an `AGENTS.md` router at the project root, defining the Bootstrap Protocol, Cognitive Metabolism, and Adaptive Alignment.
-5. **Verification**: Executes the generated memory indexer script to initialize the database and summarizes the deployed architecture to the user.
-
-*(See the `SKILL.md` file for the exact machine-readable instructions.)*
-
----
-
-## Key Rules & Constraints
-
-- **Adaptive Architecture**: The system must adapt its folder names and paths to the project's native ecosystem (e.g., `docs/`, `.agents/`) rather than forcing a rigid template.
-- **Immutable Router**: The generated `AGENTS.md` is the system's brain and is strictly protected from sub-agent modification.
-- **Non-blocking Release**: Agents must log subjective reviews asynchronously and never halt execution waiting for human input.
-
----
-
-## Resources & File Structure
-
-This skill utilizes the following structure:
-
-```text
-.
-├── SKILL.md       # Core AI instructions and workflow definition
-└── LICENSE        # Apache 2.0 License
-```
-
----
-
-## Contributing
-
-Open a PR to update the core workflow in `SKILL.md`. Ensure that the cognitive loop (Think > Try > Summarize > Record) and the 6 functional zones remain enforced.
-
-## License
-
-Apache 2.0 — see [LICENSE](LICENSE) for details.