harness-everything 0.2.2 → 0.3.6

package/README.md

@@ -1,197 +1,279 @@
-# Harness (Behavior Layer for AI Coding Agents)
-
-[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-
-Harness is a lightweight, local behavior and orchestration runtime that wraps around your AI development sessions (Claude Code, Cursor, Copilot Chat, Codex, Continue.dev, Hermes Agent). It provides reactive hooks, routing boundaries, and circuit breakers designed to prevent infinite trial-and-error loops, costly over-engineering, and "lost-in-the-middle" context drift.
-
----
-
-## The Problem
-
-AI coding agents are highly capable, but they struggle with self-regulation, environment awareness, and attention limits:
-1. **The Infinite Retry Loop:** When an agent encounters a subtle compilation or test failure, its default behavior is to make micro-adjustments repeatedly (tweak and run, tweak and run) until it exhausts your token budget.
-2. **Environment Blindness:** Agents often assume standard Unix environments, hallucinating shell commands and paths when running on Windows, PowerShell, or sandboxed environments.
-3. **Lost-in-the-Middle Bloat:** As sessions grow, agents aggressively read too many large files or generate massive console logs, causing severe context degradation and reasoning hallucinations.
-
----
-
-## Why Harness?
-
-Harness acts as an automated system supervisor. It remains completely silent and out of the way, intervening only when execution boundaries are violated or failures are detected.
-
-### Comparison: Prompt vs. Skill vs. Harness
-
-| Dimension | Prompt-Only (Custom Instructions) | Skill-Only (Task Guides) | Harness (Behavior Layer) |
-|---|---|---|---|
-| **Activation** | Always loaded (wastes prompt space) | Loaded on demand (requires manual trigger) | Reacts dynamically via native lifecycle hooks |
-| **Fail-Safe** | No protection (model keeps retrying) | No protection (loops until token limit) | **Circuit Breaker:** Halts execution after 3 failures and alerts human |
-| **Context Aware** | High risk of lost-in-the-middle bloat | Manages scope manually | **Bloat Shield:** Proactively audits diff sizes and logs warning alerts |
-| **System Audit** | Blindly assumes shell syntax | Requires manual shell check | **Preflight:** Proactively detects Windows/Unix paths, shell type, and package manager |
-| **Memory** | Resets on every new chat session | Static text rules | **Continuous Persistence:** Writes Write-Ahead Logs (WAL) for session recovery and immunizes workspace rules |
-
-The "Harness" column above is Claude Code's behavior. On Cursor, Copilot, Codex, Continue.dev, and Hermes Agent — platforms with no hook/exit-code execution mechanism — Harness can only inject advisory text, which lands in the **Prompt-Only** column instead. See [Supported AI IDEs & Tools](#supported-ai-ides--tools) below.
-
-### When should I use Harness?
-* You regularly use agentic coding tools (like Claude Code, Cursor, or Copilot) on medium-to-large codebases.
-* You develop on Windows or in mixed shells (Git Bash, WSL, PowerShell) where agents frequently get shell syntax wrong.
-* You want automated test-driven development (TDD) enforcement and safety guards to save token budgets.
-
-### When should I NOT use Harness?
-* You only use chat interfaces for general questions without letting the AI run local commands or modify files.
-* Your project has no test suite, or you prefer unconstrained, free-form agent generation.
-
----
-
-## ⚡ Quick Start (Get Protected in 10s)
-
-Harness integrates directly into your workspace. There is no heavy daemon, no paid external APIs, and zero configuration required.
-
-```bash
-# Install Harness hooks and skills into your current workspace
-npx github:dyphn1/Harness-everything install
-```
-
-### Expected Behavior After Installation:
-1. **Hook Registration:** Harness registers native hooks (e.g., inside `.claude/settings.json` for Claude Code) to intercept session starts and tool use.
-2. **Preflight Audit:** At session startup, a lightweight preflight script runs, printing a diagnostic environment block that tells the agent your exact OS, active shell, and package manager.
-3. **Guard Active:** The circuit breaker and context compactors are active in the background, consuming zero overhead unless triggered.
-
----
-
-## Visualizing the Flow
-
-### Without Harness (Endless Trial-and-Error Loop)
-```mermaid
-flowchart TD
-    U([User Request]) --> A[AI Coding Agent]
-    A -->|Command/Edit| Env[Workspace Environment]
-    Env -->|Error / Failure| A
-    A -->|Tweak & Retry 1| Env
-    Env -->|Error / Failure| A
-    A -->|Tweak & Retry 2| Env
-    Env -->|Error / Failure| A
-    A -->|Tweak & Retry 3... N| Env
-    style A fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
-```
-
-### With Harness (Guarded and Routed Execution)
-```mermaid
-flowchart TD
-    U([User Request]) --> H_Router[Harness Router]
-    H_Router -->|Tier 1: Trivial| T1[Direct Edit]
-    H_Router -->|Tier 2: Standard| T2["todo-cli.js (Script State Machine)"]
-    H_Router -->|Tier 3: Macro| T3[Fable Multi-Agent Flow]
-    
-    T2 & T3 --> Exec[Execute Code / Run Commands]
-    Exec --> Gate{verify-gate.js}
-    
-    Gate -->|Exit 1: Slap in face| Exec
-    Gate -->|Exit 1 - Repeated| CB{Circuit Breaker rule-of-3.js}
-    CB -->|Fails 3x| ZO[Zoom Out: Ask Human / Reflect]
-    ZO -->|Fresh Diagnosis| Exec
-    Gate -->|Exit 0: Success| Done[todo-cli.js complete]
-    
-    Done --> SE[Self-Evolve: Update Rules]
-    style H_Router fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px,color:#000000
-    style CB fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000000
-    style ZO fill:#ffcc80,stroke:#ef6c00,stroke-width:1px,color:#000000
-    style Gate fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
-```
-
----
-
-## Core Modules & Concepts
-
-Harness operates through five core cognitive concepts:
-
-1. **Router (`tier-router.js`):** Prevents over-engineering. Triages incoming tasks into Tiers: Tier 1 (Direct Edit, no plans), Tier 2 (Standard TDD enforcement), or Tier 3 (Macro Multi-Agent planning and delegation).
-2. **Guard (`rule-of-3.js`):** The fail-safe circuit breaker. Tracks failure signatures across terminal runs. If a test or command fails 3 times with the same signature, it locks mutating tools and forces a `zoom-out` reflection: re-verify every assumption with read-only tools, write a fact-checked report, then resume on a fresh diagnosis. The human partner is pulled in only for genuine decisions — or when the same signature trips the breaker a second time. A companion `Stop` gate (`stop-gate.js`) bounces the end of a turn once per edit batch when edits were never followed by a successful verification command.
-3. **Memory (`state-persist.js`):** Session transaction logging. Stores a local Write-Ahead Log (WAL) of milestones, preventing agents from forgetting their current task state if a session limits out or restarts.
-4. **Reflection (`self-evolve`):** Long-term workspace immunization. Upon task completion, the agent reflects on the root cause of resolved issues and saves them to local workspace rules (`RULES.md`), validated by a hermetic self-regression suite.
-5. **Subagent Scope Guard (`subagent-scope-guard.js`):** Diffs the whole repo's `git status` before and after every subagent (`Task`) burst, not just the files it was briefed to touch. Catches a subagent that was told to only read/verify but edited files anyway — a real failure mode, not a hypothetical one.
-
----
-
-## Supported AI IDEs & Tools
-
-**Only Claude Code gets the hard-boundary hooks.** Every other platform below has no hook/exit-code execution mechanism, so `harness-everything` can only inject advisory text — same protection level as the "Prompt-Only" column in the comparison table above. There is no circuit breaker, no preflight audit, and no WAL on those platforms unless Claude Code (or another hook-capable tool) is also driving the same repo.
-
-| AI Agent Tool | Integration Method | Local Target Location | Enforcement |
-|---|---|---|---|
-| **Claude Code** | Native Lifecycle Hooks (`PreToolUse`, `PostToolUse`, `SessionStart`) | `.claude/settings.json` (project) / `~/.claude/settings.json` (user)<br>*.claude/skills/* (Project Skills) / *~/.claude/skills/* (Global Skills) | **Hard** — hooks can block a tool call (`exit(2)`) |
-| **Cursor** | Native Project Rules | `.cursorrules` | Advisory only |
-| **Copilot Chat** | Custom Instructions | `.github/copilot-instructions.md` | Advisory only |
-| **Codex** | Custom Instructions (`AGENTS.md`, not `.codex/config.toml` — that file controls CLI/sandbox behavior, not prompt content) | `AGENTS.md` | Advisory only |
-| **Continue.dev** | Native project rules (a dedicated Markdown file with YAML frontmatter, `alwaysApply: true`) | `.continue/rules/harness.md` (project) / `~/.continue/rules/harness.md` (user, via `--global`) | Advisory only |
-| **Hermes Agent** ([Nous Research](https://hermes-agent.nousresearch.com/)) | Auto-loaded project context file (Hermes also reads `AGENTS.md`/`CLAUDE.md`/`.cursorrules` from the same directory if present, truncated at ~20k chars) | `.hermes.md` (project only — Hermes has no documented global project-instructions equivalent, so `--global --hermes` is a documented no-op) | Advisory only |
-
----
-
-## Deeper Documentation
-
-For a deep dive into individual modules and the underlying philosophy, explore our sub-documents:
-
-*   [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
-*   [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
-*   [Harness Routing & Triage](docs/routing.md): Detailed trigger criteria for Tiers 1, 2, and 3.
-*   [Harness Reflection & Memory](docs/reflection.md): WAL session handoffs and workspace rules immunization.
-
----
-
-## Benchmarks & Testing
-
-**If you are an agent asked to verify a Harness install, start at [VERIFICATION.md](VERIFICATION.md), not here.** It gives exact commands with exact expected output — install artifact checks for every platform, mechanism-level checks (Claude Code only: pipe a simulated hook payload into `hooks/scripts/*.js` on stdin, confirm the exit code), the behavioral test prompts below, and an acceptance scorecard to fill in. Do not report "it works" from reading the code — every check there names a command to actually run.
-
-`npm test` (`self-evolve/scripts/self-regression.js`) runs four phases: static syntax check on every script, 5 bilingual tier-routing assertions, a 6-step behavioral state-machine simulation of `todo-cli.js`, and — as of 2026-07-23 — an automated re-run of every VERIFICATION.md §2 mechanism check (`eval-framework/mechanism-test.js`, `npm run test:mechanism` to run it alone): the Rule of 3 breaker's full trip → zoom-out release → repeat-trip hard-lock cycle, boundary guard, WAL state persistence, the fact-audit reminder, subagent scope guard, and the stop gate — 10 assertions against real exit codes and stderr, not just "the code looks right." Before this, those mechanism checks existed only as copy-paste recipes in VERIFICATION.md, and three independent 2026-07-23 audits mis-tested them via a Windows-Git-Bash-unsafe `echo '...' | node script.js` pipe and reported working hooks as broken — see the System Evaluation section below for how that got resolved. There is currently no CI workflow enforcing `npm test` on push/PR — it's a local gate contributors are expected to run, not yet an automated one.
-
-For a fuller vanilla-vs-Harness behavioral comparison, see [Harness Skills Benchmark SOP](BENCHMARK_SOP.md) — standardized, reproducible scenarios:
-*   **Test A:** Over-engineering defense (Tier 1 typo correction)
-*   **Test B:** Micro-error loop defense (Tier 2 bug resolution)
-*   **Test C:** Attention loss and hallucination (Tier 3 module refactoring)
-*   **Test D:** Knowledge boundary constraints (Offline hallucination prevention)
-*   **Test E:** Terminal environment and shell awareness (Windows/Unix shell detection)
-*   **Test F** (in VERIFICATION.md, not BENCHMARK_SOP.md): fact-audit discipline — does the agent verify an external-behavior claim before asserting it?
-
----
-
-## 📊 System Evaluation
-
-**Last self-audited: 2026-07-23**, by running the actual test suite and the VERIFICATION.md recipes on Windows 11 — not by reading the code and assuming it works. Seven independent AI-model audits (Gemini 3.1 Pro, Gemini 3.5 Flash, GPT/Copilot on Mistral Medium/Small, and others) ran the same week and disagreed sharply on whether core hooks even functioned. Three of them tested `rule-of-3.js`, `boundary-guard.js`, and `state-persist.js` by piping JSON through `echo '...' | node script.js` in Windows Git Bash, which mangles stdin/TTY state and produced false "broken" verdicts. Re-running the identical payloads through Node's own `child_process` stdin API (the technique VERIFICATION.md's recipes now use) showed every one of those mechanisms working exactly as documented — the scores below reflect that corrected, verified state, not the average of the seven reports.
-
-### Five Core Verification Criteria (per VERIFICATION.md §5a)
-
-| Criterion | Score | Verified basis |
-|---|---|---|
-| **Skill Description Completeness** | 8.5/10 | 23 of 27 skills/hooks have a full Skill Contract `SKILL.md` (trigger, output, state mutations, enforcement gate). Four PreToolUse hooks — `depth-guard.js`, `context-compact.js`, `atomic-commit-check.js`, `contract-test.js` — are only described in passing in `docs/architecture.md`, not as standalone contracts. Known, not yet closed. |
-| **Routing Accuracy** | 7/10 | `tier-router.js` is a deterministic, bilingual (EN/中文) keyword heuristic — zero runtime dependencies (`package.json` has none), fully offline, fully auditable. That's a deliberate trade against false positives/negatives on ambiguous or metaphorical prompts, not an oversight: swapping it for semantic/LLM-based routing would trade determinism and zero external calls for accuracy, which cuts against the project's own "mechanism over prose" design. |
-| **Test Coverage of All Skills** | 8.5/10 | `npm test` now runs 55 real assertions: 34 syntax checks, 5 routing-tier assertions, 6 behavioral state-machine steps, and — new as of this audit — 10 mechanism assertions covering every hook in VERIFICATION.md §2 (`eval-framework/mechanism-test.js`). Previously this scored 3–6/10 across every 2026-07-23 report because the mechanism layer was manual-only. Remaining gap: no CI wiring yet (`npm test` isn't enforced on push/PR), and the four undocumented hooks above also lack dedicated tests. |
-| **Configuration Balance** | 8.5/10 | Confirmed asymmetric-by-design: hard `exit(2)` blocking hooks on Claude Code, advisory-only text on the other five platforms, with `self-heal.js` auto-repairing missing integration files on every platform. No platform is either silently ignored or over-blocked. |
-| **Workflow Conformance** | 7/10 | `docs/workflows/` diagrams (TDD, git-commit, agent-launcher, architecture refactor) are accurate and the tier-router recommends the full skill chain for each, confirmed live. What's still missing is a *runtime* check that an agent's actual tool-call sequence matched the diagram — today that's compliance-by-convention, not compliance-by-mechanism. Not attempted this round; it's a larger feature, not a fix. |
-
-### Overall Scorecard
-
-| Category | Score | Notes |
-|---|---|---|
-| **Architecture** | 9/10 | Per-session state isolation, per-platform state directories, fail-open-by-default hooks — all re-verified directly against `hooks/scripts/lib/harness-state.js`. |
-| **Test Coverage** | 8.5/10 | See above — the single biggest measured improvement this cycle (manual-only → 55 automated assertions, cross-platform). |
-| **README Completeness** | 9/10 | This section included. |
-| **Maintainability** | 8.5/10 | `todo-cli.js`'s shared, cross-session state file (`todo-state.json`) now writes atomically (temp file + rename) instead of a direct `writeFileSync`, closing a real corruption window for concurrent subagent Task bursts. |
-| **Skills Design** | 8.5/10 | Consistent Skill Contract format; four hooks still pending one (see above). |
-| **Agent Compatibility** | 9/10 | Full hard-mechanism support on Claude Code; verified advisory-text fallback on the other five platforms via `docs/architecture.md` and `scripts/installer.js`. |
-| **Beginner Friendliness** | 7.5/10 | Quick Start is genuinely 10 seconds, but Tier Routing / Rule of 3 / session-scoped state are load-bearing concepts a newcomer has to absorb before the system's behavior makes sense. Not addressed this round. |
-
-**What changed this cycle:** VERIFICATION.md §2's mechanism checks are now automated (`npm run test:mechanism`), VERIFICATION.md's own test recipes were rewritten to be Windows-safe (`node -e` stdin instead of a shell `echo` pipe), and `todo-cli.js` writes its shared state file atomically. Full detail in the commit history.
-
----
-
-## 🤝 For Contributors
-
-To contribute to Harness or modify any Skill behavior, ensure you run the local self-regression suite first:
-
-```bash
-# Run full hermetic static syntax & routing simulations
-npm run self-regression
-```
-
-All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.
-
+# Harness (Behavior Layer for AI Coding Agents)
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+Harness is a lightweight, local behavior and orchestration runtime that wraps around your AI development sessions (Claude Code, Cursor, Copilot Chat, Codex, Continue.dev, Hermes Agent). It provides reactive hooks, routing boundaries, and circuit breakers designed to prevent infinite trial-and-error loops, costly over-engineering, and "lost-in-the-middle" context drift.
+
+---
+
+## The Problem
+
+AI coding agents are highly capable, but they struggle with self-regulation, environment awareness, and attention limits:
+1. **The Infinite Retry Loop:** When an agent encounters a subtle compilation or test failure, its default behavior is to make micro-adjustments repeatedly (tweak and run, tweak and run) until it exhausts your token budget.
+2. **Environment Blindness:** Agents often assume standard Unix environments, hallucinating shell commands and paths when running on Windows, PowerShell, or sandboxed environments.
+3. **Lost-in-the-Middle Bloat:** As sessions grow, agents aggressively read too many large files or generate massive console logs, causing severe context degradation and reasoning hallucinations.
+
+---
+
+## Why Harness?
+
+Harness acts as an automated system supervisor. It remains completely silent and out of the way, intervening only when execution boundaries are violated or failures are detected.
+
+### Comparison: Prompt vs. Skill vs. Harness
+
+| Dimension | Prompt-Only (Custom Instructions) | Skill-Only (Task Guides) | Harness (Behavior Layer) |
+|---|---|---|---|
+| **Activation** | Always loaded (wastes prompt space) | Loaded on demand (requires manual trigger) | Reacts dynamically via native lifecycle hooks |
+| **Fail-Safe** | No protection (model keeps retrying) | No protection (loops until token limit) | **Circuit Breaker:** Halts execution after 3 failures and alerts human |
+| **Context Aware** | High risk of lost-in-the-middle bloat | Manages scope manually | **Bloat Shield:** Proactively audits diff sizes and logs warning alerts |
+| **System Audit** | Blindly assumes shell syntax | Requires manual shell check | **Preflight:** Proactively detects Windows/Unix paths, shell type, and package manager |
+| **Memory** | Resets on every new chat session | Static text rules | **Continuous Persistence:** Writes Write-Ahead Logs (WAL) for session recovery and immunizes workspace rules |
+
+The "Harness" column above is Claude Code's behavior. On Cursor, Copilot, Codex, Continue.dev, and Hermes Agent — platforms with no hook/exit-code execution mechanism — Harness can only inject advisory text, which lands in the **Prompt-Only** column instead. See [Supported AI IDEs & Tools](#supported-ai-ides--tools) below.
+
+### When should I use Harness?
+* You regularly use agentic coding tools (like Claude Code, Cursor, or Copilot) on medium-to-large codebases.
+* You develop on Windows or in mixed shells (Git Bash, WSL, PowerShell) where agents frequently get shell syntax wrong.
+* You want automated test-driven development (TDD) enforcement and safety guards to save token budgets.
+
+### When should I NOT use Harness?
+* You only use chat interfaces for general questions without letting the AI run local commands or modify files.
+* Your project has no test suite, or you prefer unconstrained, free-form agent generation.
+
+---
+
+## ⚡ Quick Start (Get Protected in 10s)
+
+Harness integrates directly into your workspace. There is no heavy daemon, no paid external APIs, and zero configuration required.
+
+```bash
+# Option A: Claude Code plugin (marketplace manifest included)
+#   /plugin marketplace add dyphn1/Harness-everything
+#   /plugin install harness-everything
+
+# Option B: install Harness hooks and skills into your current workspace
+npx github:dyphn1/Harness-everything install
+```
+
+### Expected Behavior After Installation:
+1. **Hook Registration:** Harness registers native hooks (e.g., inside `.claude/settings.json` for Claude Code) to intercept session starts and tool use.
+2. **Preflight Audit:** At session startup, a lightweight preflight script runs, printing a diagnostic environment block that tells the agent your exact OS, active shell, and package manager.
+3. **Guard Active:** The circuit breaker and context compactors are active in the background, consuming zero overhead unless triggered.
+
+### What Gets Installed (and How to Remove It)
+
+The installer only ever writes to your workspace (or, with `--global`, your home directory) — no daemons, no registry entries, no network services. Depending on which platforms you select, it creates:
+
+| File / Directory | Purpose |
+|---|---|
+| `.claude/settings.json` (merged) + `.claude/skills/` + `.claude/agents/` | Claude Code lifecycle hooks, project skills, and named Fable agents |
+| `.cursorrules` | Cursor advisory rules |
+| `.github/copilot-instructions.md` | Copilot Chat advisory instructions |
+| `AGENTS.md` | Codex advisory instructions |
+| `.continue/rules/harness.md` | Continue.dev advisory rules |
+| `.hermes.md` | Hermes Agent advisory context |
+| `.claude/harness-everything/` (or the per-platform equivalent) | Harness state: `manifest.json`, WAL, circuit-breaker counters |
+
+The installer records the state directories in `.git/info/exclude` — a local-only git ignore file — so Harness state never lands in a commit and your working tree (including `.gitignore`) is never modified. Everything is removed with the built-in uninstaller:
+
+```bash
+npx github:dyphn1/Harness-everything uninstall            # interactive
+npx github:dyphn1/Harness-everything uninstall --local --skills -y   # non-interactive, workspace only
+npx github:dyphn1/Harness-everything uninstall --global   # also remove ~/.agents etc.
+```
+
+---
+
+## Visualizing the Flow
+
+### Without Harness (Endless Trial-and-Error Loop)
+```mermaid
+flowchart TD
+    U([User Request]) --> A[AI Coding Agent]
+    A -->|Command/Edit| Env[Workspace Environment]
+    Env -->|Error / Failure| A
+    A -->|Tweak & Retry 1| Env
+    Env -->|Error / Failure| A
+    A -->|Tweak & Retry 2| Env
+    Env -->|Error / Failure| A
+    A -->|Tweak & Retry 3... N| Env
+    style A fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
+```
+
+### With Harness (Guarded and Routed Execution)
+```mermaid
+flowchart TD
+    U([User Request]) --> H_Router[Harness Router]
+    H_Router -->|Tier 1: Trivial| T1[Direct Edit]
+    H_Router -->|Tier 2: Standard| T2["Native TODO / Markdown checklist"]
+    H_Router -->|Tier 3: Macro| T3[Fable Multi-Agent Flow]
+    
+    T2 & T3 --> Exec[Execute Code / Run Commands]
+    Exec --> Gate{verify-gate.js}
+    
+    Gate -->|Exit 1: Fix & retry| Exec
+    Gate -->|Exit 1 - Repeated| CB{Circuit Breaker rule-of-3.js}
+    CB -->|Fails 3x| ZO[Zoom Out: Ask Human / Reflect]
+    ZO -->|Fresh Diagnosis| Exec
+    Gate -->|Exit 0: Success| Done[Checklist item complete]
+    
+    Done --> SE[Self-Evolve: Update Rules]
+    style H_Router fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px,color:#000000
+    style CB fill:#fff9c4,stroke:#fbc02d,stroke-width:1px,color:#000000
+    style ZO fill:#ffcc80,stroke:#ef6c00,stroke-width:1px,color:#000000
+    style Gate fill:#ffcdd2,stroke:#c62828,stroke-width:1px,color:#000000
+```
+
+---
+
+## Core Modules & Concepts
+
+Harness operates through six core cognitive concepts:
+
+1. **Router (`tier-router.js`):** Prevents over-engineering. Triages incoming tasks into Tiers: Tier 1 (Direct Edit, no plans), Tier 2 (Standard TDD enforcement), or Tier 3 (Macro Multi-Agent planning and delegation). It also scans every installed platform's `manifest.json` for skills `self-evolve` has generated dynamically, and auto-surfaces the ones whose keyword triggers match the current prompt — so a lesson learned in one session gets suggested again without the human having to remember it exists. If nothing matches at all — including nothing already kept from the open skills ecosystem — `find-skills` checks `npx skills list` live and, if still nothing, searches `skills.sh`/`npx skills`. With explicit approval it defaults to applying the result ephemerally (a content-addressed OS-temp cache, zero footprint after the OS reclaims it) and only permanently installs via `npx skills add` when the user says they'll reuse it — neither path is cached into `manifest.json` the way `generated[]` is, since third-party content isn't lifecycle-owned by Harness.
+2. **Guard (`rule-of-3.js`):** The fail-safe circuit breaker. Tracks failure signatures across terminal runs. If a test or command fails 3 times with the same signature, it locks mutating tools and forces a `zoom-out` reflection: re-verify every assumption with read-only tools, write a fact-checked report, then resume on a fresh diagnosis. The human partner is pulled in only for genuine decisions — or when the same signature trips the breaker a second time. A companion `Stop` gate (`stop-gate.js`) bounces the end of a turn once per edit batch when edits were never followed by a successful verification command.
+3. **Memory (`state-persist.js`):** Session transaction logging. Stores a local Write-Ahead Log (WAL) of milestones, preventing agents from forgetting their current task state if a session limits out or restarts.
+4. **Reflection (`self-evolve`):** Long-term workspace immunization. Upon task completion, the agent reflects on the root cause of resolved issues, then judges whether the lesson is a simple rule or a reusable, complex pattern: simple rules are appended to local workspace rules (`RULES.md`); genuinely reusable patterns are instead packaged as a dynamic skill (via `skill-creator`'s Dynamic Skill Generation Contract) and registered in `manifest.json` so the Router picks it up in future sessions. Either path is validated by a hermetic self-regression suite before it's persisted.
+5. **Subagent Scope Guard (`subagent-scope-guard.js`):** Diffs the whole repo's `git status` before and after every subagent (`Task`) burst, not just the files it was briefed to touch. Catches a subagent that was told to only read/verify but edited files anyway — a real failure mode, not a hypothetical one.
+6. **Cognitive Laws (Agent Cognitive OS):** Six governing laws — Intent Precedence, State Handoff Awakening, Elimination & Prediction, Evidence Assertion, Adversarial Falsification, and Code-Documentation Alignment — are woven directly into the specific skill phase each one governs (e.g. Evidence Assertion inside `tdd`'s RED/GREEN/REFACTOR gates, State Handoff Awakening inside `zoom-out`'s reflection phase) rather than duplicated in one shared file. See the relevant skill's own `SKILL.md` for where a given law actually applies.
+
+---
+
+## Supported AI IDEs & Tools
+
+**Only Claude Code gets the hard-boundary hooks.** Every other platform below has no hook/exit-code execution mechanism, so `harness-everything` can only inject advisory text — same protection level as the "Prompt-Only" column in the comparison table above. There is no circuit breaker, no preflight audit, and no WAL on those platforms unless Claude Code (or another hook-capable tool) is also driving the same repo.
+
+| AI Agent Tool | Integration Method | Local Target Location | Enforcement |
+|---|---|---|---|
+| **Claude Code** | Native Lifecycle Hooks (`PreToolUse`, `PostToolUse`, `SessionStart`) | `.claude/settings.json` (project) / `~/.claude/settings.json` (user)<br>*.claude/skills/* (Project Skills) / *~/.claude/skills/* (Global Skills) | **Hard** — hooks can block a tool call (`exit(2)`) |
+| **Cursor** | Native Project Rules | `.cursorrules` | Advisory only |
+| **Copilot Chat** | Custom Instructions | `.github/copilot-instructions.md` | Advisory only |
+| **Codex** | Custom Instructions (`AGENTS.md`, not `.codex/config.toml` — that file controls CLI/sandbox behavior, not prompt content) | `AGENTS.md` | Advisory only |
+| **Continue.dev** | Native project rules (a dedicated Markdown file with YAML frontmatter, `alwaysApply: true`) | `.continue/rules/harness.md` (project) / `~/.continue/rules/harness.md` (user, via `--global`) | Advisory only |
+| **Hermes Agent** ([Nous Research](https://hermes-agent.nousresearch.com/)) | Auto-loaded project context file (Hermes also reads `AGENTS.md`/`CLAUDE.md`/`.cursorrules` from the same directory if present, truncated at ~20k chars) | `.hermes.md` (project only — Hermes has no documented global project-instructions equivalent, so `--global --hermes` is a documented no-op) | Advisory only |
+
+---
+
+## Repository Index
+
+## Multi-Agent Workspace
+
+Use the canonical `multi-agent-workspace` skill for permanent multi-agent
+infrastructure:
+
+```bash
+node multi-agent-workspace/scripts/scaffold.js --workspace . \
+  --agency-source <path-to-agency-agents> --division engineering --platform codex
+```
+
+The source is read-only input. The generated `.harness/multi-agent/` directory
+records the six zones, selected metadata, supported converter targets,
+launcher, immutable router, memory index, and structured handoff. Omit the
+source for an explicit unavailable-catalog fallback; do not treat it as a
+complete roster.
+
+This repo uses a flat layout (waza/agentskills.io convention). The table below maps each top-level directory to its role.
+
+| Directory | Category | Description |
+|---|---|---|
+| `harness-everything` | **Core Runtime** | Bootstrap, tier-router, verify-gate, self-heal |
+| `hooks` | **Core Runtime** | Claude Code lifecycle hooks (circuit breaker, scope guard, stop gate, etc.) |
+| `scripts` | **Core Runtime** | Installer, manifest, prompts, workspace utilities |
+| `bin` | **Core Runtime** | `harness` CLI entry point |
+| `ci` | **Quality Gates** | Consistency check, description collision, mechanism tests, negative controls |
+| `.github` | **CI/CD** | GitHub Actions workflows (ci.yml, release.yml, behavioral-evals.yml) |
+| `.claude-plugin` | **Distribution** | Plugin manifests for Claude Code marketplace |
+| `evals` | **Routing Evals** | 26 trigger/routing eval suites (waza format) |
+| `behavioral-evals` | **Behavioral Evals** | LLM-level discipline cases (headless agent sessions) |
+| `benchmarks` | **Benchmarks** | BENCHMARK_SOP fixtures and recorded A/B results |
+| `docs` | **Documentation** | Philosophy, architecture, routing, reflection, audit |
+| `references` | **Documentation** | Shared checklists (security, performance, definition-of-done) |
+| `multi-agent-workspace` | **Skill (Tier 3)** | Scaffold six zones, select agency specialists, and generate bounded launchers |
+| `environment-detection` | **Foundation** | Preflight: detect OS, shell, package manager |
+| `eval-harness` | **Skill (Tier 2)** | Evaluate agent outputs against rubrics |
+| `fable-discipline` | **Skill (Tier 3)** | Enforce Fable execution guardrails |
+| `fable-mode` | **Skill (Tier 3)** | Multi-agent orchestration with milestone gates |
+| `find-skills` | **Meta** | Discover and install skills from open ecosystems |
+| `git-commit` | **Skill (Tier 1)** | Conventional commit messages with verification |
+| `grill-me` | **Skill (Tier 2)** | Adversarial plan interrogation before implementation |
+| `grill-with-docs` | **Skill (Tier 3)** | Domain-model and decision alignment before design publication |
+| `improve-codebase-architecture` | **Skill (Tier 2)** | Architectural refactoring with evidence |
+| `install-cognitive-os` | **Foundation** | Install Harness cognitive OS into workspace |
+| `repo-docs` | **Skill (Tier 3)** | Generate repository documentation |
+| `rewrite-commits` | **Skill (Tier 1)** | Interactive rebase and commit history cleanup |
+| `security-review` | **Skill (Tier 2)** | OWASP/STRIDE security review |
+| `self-evolve` | **Skill (Tier 2)** | Workspace immunization via dynamic skills |
+| `skill-creator` | **Meta** | Create new skills from patterns |
+| `skill-style` | **Meta** | Skill authoring style guide |
+| `tdd` | **Skill (Tier 2)** | Test-driven development enforcement |
+| `to-spec` | **Advisory (Tier 2/3)** | Publish specs from settled conversations |
+| `to-tickets` | **Advisory (Tier 2/3)** | Decompose settled specs into tracked tickets |
+| `todo-driven-workflow` | **Foundation** | Native TODO or Markdown checklist discipline |
+| `using-git-worktrees` | **Skill (Tier 2)** | Git worktree concurrency patterns |
+| `verification-loop` | **Skill (Tier 2)** | Verify-before-complete enforcement |
+| `verify-before-claim` | **Always-on discipline** | Fact-audit before asserting claims |
+| `zoom-out` | **Circuit breaker** | Circuit-breaker reflection protocol |
+| `opencode-plugin` | **Platform Plugin** | Enforcement hooks for opencode (post-edit, pre-complete, circuit-breaker) |
+
+---
+
+## Deeper Documentation
+
+For a deep dive into individual modules and the underlying philosophy, explore our sub-documents:
+
+*   [Harness Philosophy](docs/philosophy.md): The core behavior-first, intervention-only design.
+*   [Harness Architecture](docs/architecture.md): Lifecycle hooks, security model, and data locality.
+*   [Harness Routing & Triage](docs/routing.md): Detailed trigger criteria for Tiers 1, 2, and 3.
+*   [Harness Reflection & Memory](docs/reflection.md): WAL session handoffs and workspace rules immunization.
+*   [Harness Audit Log](docs/audit.md): Dated self-audit scorecards, methodology, and per-cycle change log.
+
+Fable model selection is documented in [fable-mode/references/model-matrix.md](fable-mode/references/model-matrix.md); the explicit entrypoints are `fable-haiku`, `fable-sonnet`, and `fable-opus`.
+
+---
+
+## Benchmarks & Testing
+
+**If you are an agent asked to verify a Harness install, start at [VERIFICATION.md](VERIFICATION.md), not here.** It gives exact commands with exact expected output — install artifact checks for every platform, mechanism-level checks (Claude Code only), the behavioral test prompts below, and an acceptance scorecard to fill in. Do not report "it works" from reading the code — every check there names a command to actually run.
+
+`npm test` (`self-evolve/scripts/self-regression.js`) runs deterministic syntax, CLI, routing-matrix, positive skill-route coverage, reference, behavioral-case, Fable model-mode, and mechanism checks (`ci/mechanism-test.js`, `npm run test:mechanism` to run it alone). The suite checks real exit codes and stderr, not just "the code looks right." It runs in CI on every push and pull request (`.github/workflows/ci.yml`); live model evaluations remain explicitly on-demand.
+
+For a fuller vanilla-vs-Harness behavioral comparison, see [Harness Skills Benchmark SOP](BENCHMARK_SOP.md) — standardized, reproducible scenarios:
+*   **Test A:** Over-engineering defense (Tier 1 typo correction)
+*   **Test B:** Micro-error loop defense (Tier 2 bug resolution)
+*   **Test C:** Attention loss and hallucination (Tier 3 module refactoring)
+*   **Test D:** Knowledge boundary constraints (Offline hallucination prevention)
+*   **Test E:** Terminal environment and shell awareness (Windows/Unix shell detection)
+*   **Test F** (in VERIFICATION.md, not BENCHMARK_SOP.md): fact-audit discipline — does the agent verify an external-behavior claim before asserting it?
+
+Benchmark **results** are tracked in [benchmarks/](benchmarks/README.md) (`run.js scaffold` builds the fixture, `record` commits a schema-validated result bound to a session log). Until those cells are filled, effectiveness claims are unbacked by recorded evidence.
+
+### Behavioral evals (LLM-level, on demand)
+
+Mechanism tests prove the hooks enforce gates; only live sessions prove agents follow the disciplines. [behavioral-evals/](behavioral-evals/README.md) runs discipline cases (including pressure variants like "we ship in 5 minutes, skip checks") against headless agent sessions (`claude -p`, opencode) in throwaway workspaces: `npm run eval:behavioral`. Token-costing by design — never wired into CI.
+
+### Catalog hygiene
+
+`npm run test:consistency` keeps the distribution manifests, docs links, skill frontmatter, and routing-eval coverage in lockstep with what is actually on disk; `npm run test:references` checks every executable/deep-dive path named by `SKILL.md`; `npm run test:release` compares the skill catalog and references with `v0.3.3-beta`; and `harness verify-install` detects stale installed versions or file trees. `npm run test:collision` fails CI when two skills' descriptions overlap enough to confuse the router. The repository checks run on every push (`.github/workflows/ci.yml`).
+
+---
+
+## 📊 System Evaluation
+
+Harness audits itself on a dated cycle by running its own test suite and VERIFICATION.md recipes — never by reading the code and assuming it works. The full scorecards, methodology, and per-cycle change log live in [docs/audit.md](docs/audit.md).
+
+**Latest local baseline — 2026-09-01**: 26/26 on-disk skills, 26/26 routing-eval directories, and the local npm gates are green. Waza remains a CI-only gate in this checkout because its installer is not available as an npm package; run it on an LF-normalized export as documented by CI.
+
+Measure on an LF export, not a Windows working tree — CRLF can inflate waza's token counts and trigger false budget failures.
+
+---
+
+## 🤝 For Contributors
+
+To contribute to Harness or modify any Skill behavior, ensure you run the local self-regression suite first:
+
+```bash
+# Run full hermetic static syntax & routing simulations
+npm run self-regression
+```
+
+All script modifications must pass 100% cleanly before pushing to keep the runtime immunized against behavioral regression.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Harness, please report it responsibly.
+
+**Do not open a public issue for security vulnerabilities.**
+
+Instead, email: dyphn1@hotmail.com
+
+Include:
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+
+## Response Timeline
+
+- Acknowledgment within 48 hours
+- Fix or mitigation plan within 7 days for confirmed vulnerabilities
+
+## Scope
+
+This policy covers the Harness-everything repository and its published npm package.
+
+## Hooks and Runtime Behavior
+
+Harness installs execution hooks (circuit breaker, scope guard, stop gate) into Claude Code sessions. These hooks:
+
+- Enforce file-scope boundaries
+- Track verification state
+- Block unsafe operations
+
+If you find a bypass or unintended behavior in these mechanisms, please report it.