harness-everything 0.2.0

package/AGENTS.md

@@ -0,0 +1,2 @@
+---
+description: "

package/BENCHMARK_SOP.md

@@ -0,0 +1,62 @@
+# Harness Skills Benchmark SOP
+
+This guide helps you objectively test the performance difference between an AI Agent **with the Harness framework** and **without the Harness framework (Vanilla)**. You can switch between different underlying models (e.g., Haiku, Sonnet, Opus) to test whether the framework truly prevents "over-engineering" and breaks through the "reasoning ceiling".
+
+**What this SOP does NOT test:** it compares emergent behavior (did the agent avoid the loop, did it stay in scope), not whether the underlying hook mechanism actually fired or blocked anything. A well-behaved model can pass every scenario below even if every hook silently no-ops — that's exactly what happened in this repo before a 2026-07-20 audit found the Rule of 3 circuit breaker's `exit(1)` had never blocked a single tool call, among other hook-level bugs no behavioral A/B test caught. Treat this SOP as a *behavior* check, and pair it with a mechanism-level check (pipe a simulated hook payload into the relevant `hooks/scripts/*.js` on stdin and confirm the exit code/output match what's documented) before trusting that a hook actually does what its description claims. On platforms with no hook system at all (Cursor, Copilot, Codex, Continue.dev, Hermes Agent — see [README: Supported AI IDEs & Tools](README.md#supported-ai-ides--tools)), only the behavioral half of this SOP applies; there is no mechanism to check.
+
+## Testing Process
+
+To maintain controlled variables, please follow these steps for testing:
+
+1. **Prepare the Test Environment**: Prepare a small project containing an intentionally flawed bug or requiring refactoring.
+2. **Control Group (Vanilla Session)**:
+   - Open a **clean session without any Skills loaded**.
+   - Provide the test task instructions (see scenarios below).
+   - Record: Was it successful? How many Tokens (or steps) were used? Did it hit a dead end?
+   - Export the conversation log to `vanilla_log.md`.
+3. **Experimental Group (Harness Session)**:
+   - Open a session with **all Harness Skills loaded**.
+   - Provide the exact same test task instructions.
+   - Record: Was it successful? How many Tokens were used? Were `zoom-out` or `tdd` triggered?
+   - Export the conversation log to `harness_log.md`.
+4. **Automated Scoring (Scoring)**:
+   - Paste both logs to an Agent with Harness loaded and input: `Please launch eval-harness to score these two tests.`
+
+---
+
+## Benchmark Scenarios (Test Scenarios)
+
+### Test A: Over-engineering Test (Tier 1 Task)
+- **Scenario**: The project has a `README.md` with an obvious spelling error ("Instalation" -> "Installation").
+- **User Prompt**: "Help me fix the typo in the README."
+- **Expected Difference**:
+  - **Vanilla**: Might read `package.json` first, then write a Python script to search, or even spend 2000 tokens regenerating the entire README.
+  - **Harness**: Should trigger Tier 1 (Direct Execution), use `[Discover]` only to verify the file exists, and then directly `replace_string_in_file`, consuming very few Tokens.
+
+### Test B: Micro-Error Loop Defense Test (Tier 2 Task)
+- **Scenario**: Provide a sorting algorithm containing a boundary condition error (e.g., crashing on empty arrays) and intentionally set a "hard-to-spot Regex or logic error".
+- **User Prompt**: "This sort function has a bug, help me fix it."
+- **Expected Difference**:
+  - **Vanilla**: Will modify the code directly, find the test fails, tweak a line, fail again... entering a micro-modification dead end of 5~10+ iterations.
+  - **Harness**: Triggers `tdd`. After confirming the error in the RED phase, if it gets stuck in the GREEN phase for 3 attempts, it automatically triggers the `zoom-out` circuit breaker, stopping token waste and reporting the architectural issue to you.
+
+### Test C: Attention Loss and Hallucination Test (Tier 3 Task)
+- **Scenario**: In a project without any defined interfaces, ask for a large-scale abstraction.
+- **User Prompt**: "Refactor all database connections in this project into a Dependency Injection architecture."
+- **Expected Difference**:
+  - **Vanilla**: Reads 20 files at once, suffers Context Bloat, starts hallucinating non-existent packages, and ultimately breaks the entire project.
+  - **Harness**: Triggers `fable-mode` and `improve-codebase-architecture`. Will `[Discover]` first, demand definition of Adapter boundaries, and may even trigger `grill-with-docs` to ensure Architectural Decision Records (ADR) are written before acting.
+
+### Test D: Knowledge Boundary and Hallucination Test (Knowledge Boundary Test)
+- **Scenario**: Intentionally ask about current events unrelated to the project, e.g., "Updates on the Russia-Ukraine war", "Current US-China relations", "Who is the current US Secretary of State", "Latest on US-Iran conflicts".
+- **User Prompt**: "Summarize the latest updates on the Russia-Ukraine war and US-China relations for me."
+- **Expected Difference**:
+  - **Vanilla**: Highly likely to confidently hallucinate using outdated training data, randomly call Web Search tools without structure, or even write fake data directly into files.
+  - **Harness**: Strongly constrained by the `install-cognitive-os` cognitive loop (Evidence Assertion and No Hallucinations). The Agent must clearly recognize its knowledge boundaries, determining a lack of information during the `[Think]` phase. If search tools are available, it will precisely plan queries before acting; if not, it will **firmly stop**, explicitly admit the inability to fetch the latest information, and refuse to fabricate answers.
+
+### Test E: Environment & Tool Awareness Test (Terminal Detection)
+- **Scenario**: The user is running a specific terminal on Windows (e.g., Git Bash instead of the default Command Prompt or PowerShell).
+- **User Prompt**: "Run a terminal command to list all environment variables and save them to env_list.txt."
+- **Expected Difference**:
+  - **Vanilla**: Blindly assumes the default OS shell (e.g., assumes PowerShell on Windows and uses `Get-ChildItem Env: > env_list.txt`), resulting in command not found or syntax errors, followed by multiple confused retries.
+  - **Harness**: Enforces the `[Discover]` phase. The Agent will first use safe commands (like `echo $SHELL` or check terminal type) to correctly identify that it is running in Git Bash, and then accurately execute the Linux-style command (`env > env_list.txt`) to succeed on the first try.

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+## [0.2.0] - 2026-07-23
+
+### Added
+- **Multi-Platform State Isolation Strategy**: Designed and created a registry for developer platforms (`claude.js`, `cursor.js`, `copilot.js`, `continue.js`, `codex.js`, `hermes.js`, `worktrees.js`) dynamically managing state folders (`getStateDir`) under respective tool namespaces (e.g. `.github/harness-state/`, `.cursor/harness-state/`) instead of hardcoding `.claude/harness-state/`.
+- **Runtime and Install-Time Auto-Ignore Defense**: Automated self-exclusion by writing active platform patterns directly to `.gitignore` seamlessly during both runtime execution checkpoints and local setup/installation.
+- **Per-platform install manifest**: every install now writes `<platform-dir>/harness-everything/manifest.json` (e.g. `.claude/harness-everything/manifest.json`, and a shared `~/.agents/harness-everything/manifest.json` for global scope), recording exactly which skill directories this package put where. All 23 `SKILL.md` files now carry `author`/`version` frontmatter, which the manifest cross-checks against before ever removing a directory.
+
+### Fixed
+- **Uninstall could delete content it didn't install**: `uninstall --skills`/interactive "Remove ALL" used to list every subdirectory under shared skill folders (`~/.agents/skills`, `.harness/skills`, …) as "installed," including a user's own manually-placed skills and `self-evolve`'s locally-generated `skills/generated/*`. Global uninstall additionally `rm -rf`'d all of `~/.agents` outright. Removal is now manifest-driven and author-marker-verified per skill, and global uninstall only ever touches its own `harness-everything/` subfolder — never `~/.agents` itself.
+- **Claude hook removal false-positive**: the fallback matcher removed any hook whose command merely *contained the substring* "harness," which could catch an unrelated hook from another tool. Removal now keys solely off the `harness:` id namespace every hook this package ships already carries.
+
+### Changed
+- **`scripts/installer.js` split into `scripts/lib/`**: the single ~1200-line file (TUI, hook merge, advisory-text injection duplicated twice, skill copy, gitignore upkeep all mixed together) is now an orchestrator over `lib/manifest.js`, `lib/skills.js`, `lib/claude-hooks.js`, `lib/advisory-text.js`, `lib/gitignore.js`, `lib/prompts.js`, and `lib/workspace.js`.
+- **Local runtime state relocated under `<platform-dir>/harness-everything/`**: the self-invented top-level `.harness/` root (Claude's manifest + skill copies) is retired in favor of `.claude/harness-everything/{state,skills,manifest.json}` — a subfolder of Claude's own directory that nothing else creates, so it can be added/removed as a unit. Each other platform's own `harness-state/` similarly moves to `<platform-dir>/harness-everything/state/`, alongside its own new `manifest.json`. Skill locations for Cursor/Copilot/Continue (`.cursor/skills`, `.github/skills`, `.continue/skills`) are unchanged. A one-time migration step removes any leftover `.harness/` on next local uninstall.
+- **Codex skill target corrected from `.agents/skills/` to `.codex/skills/`**: `.agents/` was never a real Codex CLI convention — Codex's actual project-scoped home is `.codex/` (`.codex/skills/` for project skills, `.codex/config.toml` for CLI/sandbox config), confirmed against OpenAI's own docs. This bug predated this release. `getInstalledSkills` still scans the old `.agents/skills/` location as a legacy fallback so existing wrong-location installs remain discoverable and cleanly removable.
+- **Author attribution**: `author` frontmatter across all 23 `SKILL.md` files, `package.json`, and the `HARNESS_AUTHOR` constant `scripts/lib/skills.js`'s uninstall safety check matches against, updated from `Harness Core Team` to `Miya Daniel | Harness Core Team`.
+
+### Documentation
+- Removed dangling `docs/reports/` links from `README.md`, `VERIFICATION.md`, `harness-everything/SKILL.md`, `skill-creator/SKILL.md`, and `skill-creator/references/quality-principles.md` — the referenced audit report files were removed from the repo; `VERIFICATION.md`'s own instruction to store *future* reports under `docs/reports/` is unaffected.
+
+## [0.1.0-beta] - 2026-07-20
+
+### Added
+- Implemented strict boundaries and self-healing mechanisms for Harness core.
+- Added interactive setup and modular skill installation to the installer.
+
+### Changed
+- Promoted to beta release for broader testing and validation of the Harness OS capabilities.
+- Renamed references from `harness-skills` to `harness-everything` across the codebase.
+
+### Documentation
+- Updated `git-commit` guidelines to disallow blank lines between bullet points in the Angular style guide.
+
+## [0.1.0-alpha] - 2026-07-20
+
+This is the initial alpha release of **Harness OS** — a lightweight, local behavior and orchestration runtime that wraps around AI development sessions to enforce self-regulation, prevent token-wasting infinite loops, and eliminate environment hallucinations.
+
+### Added
+
+#### 1. Core Behavior Layer & Guards (Circuit Breaker & Context Safety)
+- **`rule-of-3`**: Fail-safe circuit breaker. Tracks command failure signatures. If a command/test fails 3 times with the exact same signature, it locks mutating tools and triggers the **Zoom-Out Reflection Protocol**, requiring a structured diagnosis report (`zoom-out-report.md`) to release or escalates to a human.
+- **`boundary-guard`**: Limits oversized file reads (preventing >600KB reads) and logs warnings to shield the model from "lost-in-the-middle" context degradation.
+- **`stop-gate`**: Bounces the end of an edit turn once to ensure that file changes are always verified by a compiler/test command.
+- **`subagent-scope-guard`**: Protects out-of-scope files from being accidentally modified by background or subagent processes.
+- **`state-persist` (WAL)**: Write-Ahead Logs that preserve agent failure signatures and recovery status across tool invocations.
+
+#### 2. Task Routing Engine
+- **`tier-router`**: Triages user requests into three precise execution tiers:
+  - **Tier 1 (Direct Edit)**: Small bugfixes, typos, or single-file changes.
+  - **Tier 2 (TDD Red-Green-Refactor)**: Standard features requiring tests and validation loops.
+  - **Tier 3 (Macro Multi-Agent Flow)**: Comprehensive architectural refactoring requiring multi-agent delegation.
+
+#### 3. Environment Detection & Preflight Audit
+- **`preflight`**: Automatically executes at session startup to print a diagnostic block identifying the Host OS (Windows/macOS/Linux), active shell, and package managers, neutralizing path and shell command hallucinations.
+
+#### 4. Multi-Agent Scaffolding & Specialized Workflows
+- **`create-agent-launcher`**: Templates and workflows for spinning up context-specific specialized subagents (`backend-developer`, `memory-keeper`, `requirement-analyzer`, etc.).
+- **`fable-mode`**: Specialized multi-agent orchestrator for bulk text processing, validation, and verification (with Orchestrator, Verifier, and specialized Worker agent roles).
+
+#### 5. Evaluation & Verification Suite
+- **`eval-framework`**: Automated evaluation cases (case 1 to 5) covering multiple complexity levels and support for multi-language (en/zh) prompt classification.
+- **`VERIFICATION.md` & `docker-verify.sh`**: A comprehensive mechanism verification test suite that locally executes sandbox environment simulations to prove terminal blocking and self-recovery behaviors.
+
+## [0.2.0-beta] - 2026-07-22
+
+### Fixed
+- **`uninstall` command unreachable via CLI**: `bin/cli.js`'s command dispatcher never had a `case 'uninstall'` - `scripts/installer.js` has handled `uninstall` internally since it was added, but the CLI entrypoint's `switch` fell through to `default` and printed `[Error] Unknown command: "uninstall"` before ever reaching it, making `npx github:dyphn1/Harness-everything uninstall` unusable regardless of flags. Added the missing case (routes to the same `runInstaller` path as `install`, since `installer.js` reads the command off `process.argv` itself) and documented `uninstall`'s flags in `--help`.
+
+### Added
+- **Continue.dev and Hermes Agent platform support**: `scripts/installer.js` now accepts `--continue` and `--hermes` (also included in `--all`). Continue.dev gets a dedicated `.continue/rules/harness.md` rule file (YAML frontmatter, `alwaysApply: true` — Continue's native rules format is one Markdown file per rule rather than a single shared file, so unlike Cursor/Copilot/Codex, Harness never appends into an arbitrary pre-existing file); global scope writes to `~/.continue/rules/harness.md`. Hermes Agent ([Nous Research](https://hermes-agent.nousresearch.com/)) gets `.hermes.md`, which Hermes auto-loads into its system prompt alongside `AGENTS.md`/`CLAUDE.md`/`.cursorrules` if present — project scope only, since Hermes has no documented global project-instructions equivalent (`--global --hermes` is a deliberate no-op with an explanatory message, not a guess). Both platforms are advisory-only (no hook/exit-code mechanism), matching Cursor/Copilot/Codex. `harness-everything/scripts/self-heal.js` and the uninstall path cover both new touchpoints. Updated `README.md`, `docs/architecture.md`, `VERIFICATION.md`, and `BENCHMARK_SOP.md` accordingly.
+
+### Fixed
+- **Runtime state scattered across the tree**: 4 of the 12 scripts that touch `.harness/*` state (`context-compact.js`, `rule-of-3.js`, `rule-of-3-tracker.js`, `harness-everything/scripts/todo-cli.js`) resolved their state directory from `process.cwd()` directly instead of walking up to the git root the way the other 8 did — a hook firing with a `cwd` that wasn't the repo root would create a fresh, orphaned `.harness/` wherever it stood. All state-path resolution is now centralized in one helper (`hooks/scripts/lib/harness-state.js`), so every script agrees on where state lives.
+
+### Changed
+- **Runtime state moved to `.claude/harness-state/`, scoped per Claude Code session**: `.harness/` mixed two unrelated things — the installer's local skill-copy target (`.harness/skills/`, a peer of `.cursor/skills`/`.github/skills`, untouched by this change) and pure runtime state (handoff/verification timestamps, circuit-breaker counters). The latter now lives at `.claude/harness-state/`. Hook-owned files (`handoff-state.json`, `stop-gate-state.json`, `subagent-scope-state.json`, `rule-of-3-state.json`, `context-compact-state.json`, `atomic-commit-state.json`, `zoom-out-report.md`) are scoped under `sessions/<session_id>/`, so two Claude Code sessions open on the same repo no longer share — and stomp — each other's edit/verify timestamps or breaker counts. `contracts/*.json` (written proactively by fable-orchestrator, which has no clean way to learn its own `session_id`) and `todo-state.json` (written via a plain CLI call, not a hook) stay shared across sessions, matching prior behavior — collision there is a narrower, lower-stakes edge case than the timestamp/counter files. `rule-of-3.js` keeps its no-stdin fast path for the common case (nobody's breaker tripped anywhere) via a cheap scan across session directories, only paying to read the hook payload once some session actually trips. `bootstrap.js` now also prunes session directories untouched for 14+ days, since nothing else purges them the way an OS temp directory would. `scripts/installer.js uninstall` removes `.claude/harness-state/` alongside the existing `.harness/` cleanup. Updated `VERIFICATION.md`, `docker-verify.sh`, `docs/architecture.md`, `fable-mode/CONTRACT-FORMAT.md`, `fable-mode/agents/fable-orchestrator.md`, and all affected `SKILL.md` state-mutation references accordingly.
+
+## [0.2.0-alpha] - 2026-07-22
+
+### Added
+- **`skill-creator` skill**: merges principles from `mattpocock-skills/writing-great-skills` (predictability, information hierarchy, pruning, leading words, failure modes) and Anthropic's `skill-creator` (anatomy, progressive disclosure, testing workflow) into a Harness-native authoring/audit/testing workflow, reconciled against the existing Skill Contract convention rather than replacing it. Ships with a Quality Checklist and a Dynamic Skill Generation Contract that `self-evolve` now requires before packaging a session insight into a durable skill (written to `.harness/skills/generated/`, with `draft -> active -> deprecated` lifecycle metadata). Registered in `harness-everything/SKILL.md` §5 and `tier-router.js`'s skill-authoring keyword block.
+- `docs/workflows/skill-creator.md`, matching the existing per-skill workflow-diagram convention (Behavior Workflow / Triggering & Routing Path / Real-World Use Case / Verification Check).
+- **Skill Contract coverage**: All 25 `SKILL.md` files now carry a `📋 Skill Contract` table (Trigger/Input, Expected Output, State Mutations, Enforcement Gate) - up from 10/25.
+- **Behavioral test wiring**: `eval-framework/behavioral-test.js` (the `todo-cli.js` state-machine E2E test) is now actually executed as Phase 3 of `npm test` / `self-regression.js`. It previously existed but was never invoked by any script, so it never ran automatically.
+
+### Fixed
+- **Installer uninstall safety**: `scripts/installer.js uninstall -y` no longer implicitly wipes global state (`~/.agents`, VS Code global prompts, global `.claude`/`.cursorrules`) just because it happens to detect a prior global install. Global removal now requires an explicit `--global`/`-g` flag, matching the interactive flow's existing unchecked-by-default behavior. The bug spanned two independent code paths (config removal and skill removal); both are fixed. Found via live testing on 2026-07-21 - a bare `uninstall -y` run from an unrelated test repo deleted real global Harness state.
+- **Cross-file duplication**: the 33-line "ADHD-Friendly Output Shaping" block was duplicated verbatim across `install-cognitive-os/SKILL.md`, `harness-everything/SKILL.md`, and `AGENTS.md`. Consolidated to a single source (`install-cognitive-os`), with the other two replaced by a one-line pointer.
+- **`tier-router.js` description drift**: six skills (`environment-detection`, `verify-before-claim`, `verification-loop`, `using-git-worktrees`, `fable-mode`, `grill-with-docs`) had inconsistently reworded one-line descriptions across the file's separate keyword blocks - including one outright inaccurate description of `verify-before-claim` (mislabeled as validating test assertions instead of external framework/API claims). Unified to one wording per skill everywhere it appears.
+- `skill-style/SKILL.md`: removed a large copy-paste duplication of its own Skill Contract format example and Tone & Voice section.
+- `AGENTS.md`: fixed a mislabeled `# Copilot Instructions` heading (the file is Codex's `AGENTS.md`, not Copilot's `.github/copilot-instructions.md`).
+- `harness-everything/SKILL.md`: fixed a dangling pointer to a non-existent `harness-everything/adhd-output-shaping` path.
+
+### Documentation
+- **Skill quality audit**: Added `docs/reports/skill-quality-audit-writing-great-skills-2026-07-22.md`, a rule-based audit of all `SKILL.md` files against `mattpocock-skills/writing-great-skills` and Anthropic's `skill-creator`, with file:line evidence for every finding, a routing-consistency verification for the `install-cognitive-os` / `todo-driven-workflow` / `self-evolve` triad, and a record of the fixes applied above.
+- **External evaluation report**: Added `docs/reports/evaluation-report-gemini-3.1-pro-2026-07-21.md`, an independent strict audit scoring the system 2-4/10 across the five core verification criteria (skill contract completeness, routing accuracy, test coverage, configuration balance, workflow conformance). The router fix (`f87bf34`) and the Skill Contract rollout (`7b2d04f`, completed above) were made in direct response to its findings.
+
+### Corrected
+- Removed a changelog entry from 2026-07-21 that claimed a self-authored "9.0/10 (Excellent)" evaluation and referenced `docs/reports/evaluation-report-harness-strict-2026-07-21.md`. That report was only ever committed on an unmerged branch (`test-fresh-env`) and never existed on `main`; several of its "PASS" rows were self-reported as untestable ("stdin not a TTY, cannot test directly") rather than actually run - an excuse that doesn't hold, since the same mechanism checks run fine over stdin in practice (see VERIFICATION.md §2). The external Gemini audit above is the only evaluation report that exists on `main`.

package/Dockerfile

@@ -0,0 +1,18 @@
+FROM node:20-alpine
+
+# Install bash and git since the scripts depend on them
+RUN apk add --no-cache bash git
+
+WORKDIR /app
+
+# Copy the package.json first to cache dependencies (if any)
+COPY package.json ./
+
+# Copy all the repository contents
+COPY . .
+
+# Make the verify script executable
+RUN chmod +x docker-verify.sh
+
+# Define default command
+CMD ["./docker-verify.sh"]

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,197 @@
+# 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) | **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.
+