harness-everything 0.2.2 → 0.3.6

package/docs/architecture.md

@@ -1,95 +1,99 @@
-# Harness Architecture
-
-This document details the internal architecture, lifecycle, and integration touchpoints of the Harness behavior layer.
-
----
-
-## Architectural Overview
-
-Harness acts as a **system supervisor** wrapping around your AI development sessions. Instead of controlling the model's generation directly, it leverages native hook systems (like Claude Code's lifecycle hooks) and instruction files (like `.cursorrules` or `.github/copilot-instructions.md`) to inject contextual guardrails.
-
-The diagram below outlines the full lifecycle of a task under Harness:
-
-```mermaid
-flowchart TD
-    subgraph User_Session [User Session]
-        U([User Request]) --> Boot[bootstrap.js: Session Start]
-    end
-
-    subgraph OS_Kernel [Harness Engine]
-        Boot -->|Check Handoff Checkpoint| Preflight[preflight.js: Environment Audit]
-        Preflight --> Router{tier-router.js: Task Triage}
-        
-        Router -->|Tier 1: Trivial Task| T1[Direct Execution - No Plans]
-        Router -->|Tier 2: Standard Task| T2[tdd: Test-Driven Development]
-        Router -->|Tier 3: Macro Task| T3[fable-mode: Multi-Agent Spawn]
-        T2 & T3 --> TDW[todo-driven-workflow: Base Execution Checklist]
-    end
-
-    subgraph Defense_Safety [Circuit Breakers]
-        T1 & TDW --> Tools[Agent Tool Call]
-        Tools -->|PreToolUse| CG[context-compact.js: Bloat Warning]
-        Tools -->|PreToolUse| CB{rule-of-3.js: Circuit Breaker}
-        
-        CB -->|Fails 3x| ZO(zoom-out: Halt, Reflect & Fact-Check)
-        ZO -->|Fresh diagnosis: RESUME| Tools
-        CB -->|Succeeds| Done[Success / Finish]
-    end
-
-    subgraph Continuous_Learning [Continuous Learning]
-        ZO -->|Genuine human decision / 2nd trip| Human[Human Decision & Guidance]
-        Human --> SE[self-evolve: Deep Reflection]
-        Done -->|Complex Breakthrough| SE
-        SE --> RunSR[self-regression.js: CI Check]
-        RunSR -->|Pass 100%| Mem[(Long-term Memory / RULES.md)]
-        Mem -.->|Immunize| Preflight
-    end
-
-    style OS_Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
-    style Defense_Safety fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
-    style Continuous_Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
-```
-
----
-
-## Integration touchpoints
-
-Harness is designed to align with the unique capabilities of various AI IDEs and CLI tools — but those capabilities are not equivalent across platforms, and this repo does not pretend otherwise.
-
-**Self-healing:** integration touchpoints can drift — installed from one editor, opened in another. `harness-everything/scripts/self-heal.js` audits all six touchpoints below and re-runs the idempotent installer to backfill whatever is missing. On Claude Code, `bootstrap.js` performs the audit at SessionStart and reports missing touchpoints (repair is left to the model so an intentionally removed file isn't silently re-created every session); on hook-less platforms, the audit runs when `harness-everything` or `environment-detection`'s Discover phase loads. Only Claude Code has a hook system with exit-code-based blocking; every other platform below gets **advisory text only**, with the same protection level as the "Prompt-Only" column in the README's own comparison table. There is no `preflight.js` audit, no `Rule of 3` circuit breaker, and no WAL on those platforms — nothing runs the `.claude/harness-everything/state/*` runtime-state scripts unless Claude Code (or another hook-capable tool) is also driving the same repo.
-
-**Placement rule:** a platform's own native file/folder (`.claude/settings.json`, `.cursorrules`, `.cursor/skills/`, …) is never moved — it lives exactly where that platform expects it. Anything Harness itself needs that has no native home converges into one exclusively-owned subfolder per platform: `<platform-dir>/harness-everything/`. Nothing else ever creates a directory literally named `harness-everything`, which is what lets the installer add or remove it as a unit — including on uninstall — without touching anything else already in that platform's directory (another tool's files, or skills the user installed by hand).
-
-**Runtime state vs. installed skill content:** `<platform-dir>/harness-everything/` holds runtime state (pure runtime state: hook JSON, circuit-breaker counters, handoff/verification timestamps) kept apart in the `state/` subfolder. On the other hand, the actual installed skills go to each platform's native/expected skills directories (e.g., `.claude/skills/` for Claude, `.cursor/skills/` for Cursor, `.github/skills/` for Copilot, `.codex/skills/` for Codex, `.continue/skills/` for Continue, and `~/.agents/skills/` or `~/.claude/skills/` for Global scope) where they are dynamically discovered and processed. A `manifest.json` under `<platform-dir>/harness-everything/` (or global home) records exactly what the installer put where, per platform, so uninstall can match against the manifest files and perform precise cleanup without guessing. Both runtime state and skills directories are gitignored.
-
-### 1. Claude Code (hook-enforced)
-Our installer configures native lifecycle hooks inside `.claude/settings.json`, and places project-level skills inside the native `.claude/skills/` directory where Claude Code natively auto-discovers and registers them.
-*   `SessionStart`: Runs `bootstrap.js` to restore previous handoffs, check environment variables, and initialize session state.
-*   `PreToolUse`: Triggers `rule-of-3.js`, `boundary-guard.js`, `depth-guard.js`, `context-compact.js`, and `subagent-scope-guard.js` to intercept tool invocations before they run, and can actually block one (`exit(2)`) — e.g. the Rule of 3 circuit breaker.
-*   `PostToolUse`: Records tool outcomes, updates the persistent transaction log (WAL) via `state-persist.js`, tracks repeat failures, and can only add advisory context back (the tool already ran; nothing here blocks it).
-*   `Stop`: Runs `stop-gate.js` — when a turn ends with uncommitted edits that were never followed by a successful verification command (test/build/lint), it bounces the stop back once per edit batch. This is the mechanical form of `verification-loop`'s pre-delivery gate; on every other platform that gate remains advisory prose.
-
-### 2. Cursor (advisory only)
-The installer appends guidance to `.cursorrules`. Cursor has no hook/execution mechanism, so nothing in `.claude/harness-state/` gets read or written by Cursor itself, and no tool call can be blocked — the model is simply asked (in the same file, every session) to self-regulate: discover the environment before acting, stop after 3 repeated failures instead of continuing to retry, and prefer small commits.
-
-### 3. Copilot Chat (advisory only)
-Same mechanism and same limits as Cursor, via `.github/copilot-instructions.md`.
-
-### 4. Codex (advisory only)
-Same mechanism and same limits again, via `AGENTS.md` — Codex's actual custom-instruction file, read automatically at session start (`.codex/config.toml` controls CLI/sandbox behavior, not prompt content, and was never a valid target for this).
-
-### 5. Continue.dev (advisory only)
-Continue's rules system reads individual Markdown files (with YAML frontmatter — `name`, `globs`, `alwaysApply`) from a `.continue/rules/` folder rather than one shared file, so the installer writes a dedicated `.continue/rules/harness.md` with `alwaysApply: true` instead of appending into an arbitrary pre-existing file. No hook/execution mechanism, same limits as Cursor. Global scope writes to `~/.continue/rules/harness.md`.
-
-### 6. Hermes Agent (advisory only)
-[Hermes](https://hermes-agent.nousresearch.com/) (Nous Research) auto-injects project context into its system prompt from `.hermes.md`, `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` if present in the directory it's launched from (truncated at ~20k chars) — meaning a Codex or Cursor install already reaches Hermes for free. The installer still writes a dedicated `.hermes.md` for explicit coverage. No hook/execution mechanism. Project scope only: Hermes has no documented global project-instructions equivalent (its own settings live under `~/.hermes/`, which governs model/terminal/skills config, not per-project behavior text), so `--global --hermes` is a deliberate no-op rather than a guess.
-
----
-
-## Security Model & Data Locality
-
-Harness runs with a **zero-trust, fully local security model**:
-
-1. **No External APIs:** Harness does not send telemetry, code snippets, or configuration files to external servers. All processing is done locally via native Node.js scripts.
-2. **Credential Protection:** Harness never asks for or stores API keys or secrets. If any terminal command prompts for a password, Harness's rules immediately direct the model to halt and request manual entry by the human partner.
-3. **Execution Gating:** The hook scripts are written in standard CommonJS, ensuring they compile and run fast (<200ms) to prevent blocking terminal operations.
+# Harness Architecture
+
+This document details the internal architecture, lifecycle, and integration touchpoints of the Harness behavior layer.
+
+---
+
+## Architectural Overview
+
+Harness acts as a **system supervisor** wrapping around your AI development sessions. Instead of controlling the model's generation directly, it leverages native hook systems (like Claude Code's lifecycle hooks) and instruction files (like `.cursorrules` or `.github/copilot-instructions.md`) to inject contextual guardrails.
+
+At the skill layer, Harness is designed as a [mechanism-first skill mesh](mechanism-first-skill-mesh.md): each skill remains independently useful, while routers, gates, hooks, scripts, exit codes, and compact return values provide coordination at decision points.
+
+The diagram below outlines the full lifecycle of a task under Harness:
+
+```mermaid
+flowchart TD
+    subgraph User_Session [User Session]
+        U([User Request]) --> Boot[bootstrap.js: Session Start]
+    end
+
+    subgraph OS_Kernel [Harness Engine]
+        Boot -->|Check Handoff Checkpoint| Preflight[preflight.js: Environment Audit]
+        Preflight --> Router{tier-router.js: Task Triage}
+        
+        Router -->|Tier 1: Trivial Task| T1[Direct Execution - No Plans]
+        Router -->|Tier 2: Standard Task| T2[tdd: Test-Driven Development]
+        Router -->|Tier 3: Macro Task| T3[fable-mode: Multi-Agent Spawn]
+        T2 & T3 --> TDW[todo-driven-workflow: Base Execution Checklist]
+    end
+
+    subgraph Defense_Safety [Circuit Breakers]
+        T1 & TDW --> Tools[Agent Tool Call]
+        Tools -->|PreToolUse| CG[context-compact.js: Bloat Warning]
+        Tools -->|PreToolUse| CB{rule-of-3.js: Circuit Breaker}
+        
+        CB -->|Fails 3x| ZO(zoom-out: Halt, Reflect & Fact-Check)
+        ZO -->|Fresh diagnosis: RESUME| Tools
+        CB -->|Succeeds| Done[Success / Finish]
+    end
+
+    subgraph Continuous_Learning [Continuous Learning]
+        ZO -->|Genuine human decision / 2nd trip| Human[Human Decision & Guidance]
+        Human --> SE[self-evolve: Deep Reflection]
+        Done -->|Complex Breakthrough| SE
+        SE --> RunSR[self-regression.js: CI Check]
+        RunSR -->|Pass 100%| Mem[(Long-term Memory / RULES.md)]
+        Mem -.->|Immunize| Preflight
+    end
+
+    style OS_Kernel fill:#eceff1,stroke:#37474f,stroke-width:2px,color:#000000
+    style Defense_Safety fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,color:#000000
+    style Continuous_Learning fill:#e3f2fd,stroke:#1e88e5,stroke-width:2px,color:#000000
+```
+
+---
+
+## Integration touchpoints
+
+Harness is designed to align with the unique capabilities of various AI IDEs and CLI tools — but those capabilities are not equivalent across platforms, and this repo does not pretend otherwise.
+
+**Self-healing:** integration touchpoints can drift — installed from one editor, opened in another. `harness-everything/scripts/self-heal.js` audits all six touchpoints below and re-runs the idempotent installer to backfill whatever is missing. On Claude Code, `bootstrap.js` performs the audit at SessionStart and reports missing touchpoints (repair is left to the model so an intentionally removed file isn't silently re-created every session); on hook-less platforms, the audit runs when `harness-everything` or `environment-detection`'s Discover phase loads. Only Claude Code has a hook system with exit-code-based blocking; every other platform below gets **advisory text only**, with the same protection level as the "Prompt-Only" column in the README's own comparison table. There is no `preflight.js` audit, no `Rule of 3` circuit breaker, and no WAL on those platforms — nothing runs the `.claude/harness-everything/state/*` runtime-state scripts unless Claude Code (or another hook-capable tool) is also driving the same repo.
+
+**Placement rule:** a platform's own native file/folder (`.claude/settings.json`, `.cursorrules`, `.cursor/skills/`, …) is never moved — it lives exactly where that platform expects it. Anything Harness itself needs that has no native home converges into one exclusively-owned subfolder per platform: `<platform-dir>/harness-everything/`. Nothing else ever creates a directory literally named `harness-everything`, which is what lets the installer add or remove it as a unit — including on uninstall — without touching anything else already in that platform's directory (another tool's files, or skills the user installed by hand).
+
+**Runtime state vs. installed skill content:** `<platform-dir>/harness-everything/` holds runtime state (pure runtime state: hook JSON, circuit-breaker counters, handoff/verification timestamps) kept apart in the `state/` subfolder. On the other hand, the actual installed skills go to each platform's native/expected skills directories (e.g., `.claude/skills/` for Claude, `.cursor/skills/` for Cursor, `.github/skills/` for Copilot, `.codex/skills/` for Codex, `.continue/skills/` for Continue, and `~/.agents/skills/` or `~/.claude/skills/` for Global scope) where they are dynamically discovered and processed. A `manifest.json` under `<platform-dir>/harness-everything/` (or global home) records exactly what the installer put where, per platform, so uninstall can match against the manifest files and perform precise cleanup without guessing. Both runtime state and skills directories are ignored via `.git/info/exclude` (local-only; the working tree's `.gitignore` is never modified), recorded by the installer at install time and removed by the uninstaller.
+
+Claude's named Fable agents are copied to `.claude/agents/` (or `~/.claude/agents/` globally) so standalone installs expose the same agents as the plugin manifest. Agent files are tracked in the platform manifest; conflicting user-owned files are preserved and cause the model selector to report an explicit fallback.
+
+### 1. Claude Code (hook-enforced)
+Our installer configures native lifecycle hooks inside `.claude/settings.json`, and places project-level skills inside the native `.claude/skills/` directory where Claude Code natively auto-discovers and registers them.
+*   `SessionStart`: Runs `bootstrap.js` to restore previous handoffs, check environment variables, and initialize session state.
+*   `PreToolUse`: Triggers `rule-of-3.js`, `boundary-guard.js`, `depth-guard.js`, `context-compact.js`, and `subagent-scope-guard.js` to intercept tool invocations before they run, and can actually block one (`exit(2)`) — e.g. the Rule of 3 circuit breaker.
+*   `PostToolUse`: Records tool outcomes, updates the persistent transaction log (WAL) via `state-persist.js`, tracks repeat failures, and can only add advisory context back (the tool already ran; nothing here blocks it).
+*   `Stop`: Runs `stop-gate.js` — when a turn ends with uncommitted edits that were never followed by a successful verification command (test/build/lint), it bounces the stop back once per edit batch. This is the mechanical form of `verification-loop`'s pre-delivery gate; on every other platform that gate remains advisory prose.
+
+### 2. Cursor (advisory only)
+The installer appends guidance to `.cursorrules`. Cursor has no hook/execution mechanism, so nothing in `.claude/harness-everything/state/` gets read or written by Cursor itself, and no tool call can be blocked — the model is simply asked (in the same file, every session) to self-regulate: discover the environment before acting, stop after 3 repeated failures instead of continuing to retry, and prefer small commits.
+
+### 3. Copilot Chat (advisory only)
+Same mechanism and same limits as Cursor, via `.github/copilot-instructions.md`.
+
+### 4. Codex (advisory only)
+Same mechanism and same limits again, via `AGENTS.md` — Codex's actual custom-instruction file, read automatically at session start (`.codex/config.toml` controls CLI/sandbox behavior, not prompt content, and was never a valid target for this).
+
+### 5. Continue.dev (advisory only)
+Continue's rules system reads individual Markdown files (with YAML frontmatter — `name`, `globs`, `alwaysApply`) from a `.continue/rules/` folder rather than one shared file, so the installer writes a dedicated `.continue/rules/harness.md` with `alwaysApply: true` instead of appending into an arbitrary pre-existing file. No hook/execution mechanism, same limits as Cursor. Global scope writes to `~/.continue/rules/harness.md`.
+
+### 6. Hermes Agent (advisory only)
+[Hermes](https://hermes-agent.nousresearch.com/) (Nous Research) auto-injects project context into its system prompt from `.hermes.md`, `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` if present in the directory it's launched from (truncated at ~20k chars) — meaning a Codex or Cursor install already reaches Hermes for free. The installer still writes a dedicated `.hermes.md` for explicit coverage. No hook/execution mechanism. Project scope only: Hermes has no documented global project-instructions equivalent (its own settings live under `~/.hermes/`, which governs model/terminal/skills config, not per-project behavior text), so `--global --hermes` is a deliberate no-op rather than a guess.
+
+---
+
+## Security Model & Data Locality
+
+Harness runs with a **zero-trust, fully local security model**:
+
+1. **No External APIs:** Harness does not send telemetry, code snippets, or configuration files to external servers. All processing is done locally via native Node.js scripts.
+2. **Credential Protection:** Harness never asks for or stores API keys or secrets. If any terminal command prompts for a password, Harness's rules immediately direct the model to halt and request manual entry by the human partner.
+3. **Execution Gating:** The hook scripts are written in standard CommonJS, ensuring they compile and run fast (<200ms) to prevent blocking terminal operations.

package/docs/audit.md

@@ -0,0 +1,53 @@
+# Harness System Audit Log
+
+Maintainer-facing audit record. If you just want to know whether Harness works and how to verify it yourself, start at [VERIFICATION.md](../VERIFICATION.md) instead — this file records *how the scores below were obtained* and what changed between audit cycles.
+
+**Last self-audited: 2026-09-01**, by running the actual test suite and the VERIFICATION.md recipes on Windows 11 — not by reading the code and assuming it works.
+
+## The 2026-07-23 mis-measurement incident
+
+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.
+
+This incident is why VERIFICATION.md's recipes were rewritten to be Windows-safe (`node -e` stdin instead of a shell `echo` pipe), and why the §2 mechanism checks were automated as `ci/mechanism-test.js` (`npm run test:mechanism`) — copy-paste recipes that can be mis-executed are not a reliable verification substrate.
+
+## Five Core Verification Criteria (per VERIFICATION.md §5a)
+
+| Criterion | Score | Verified basis |
+|---|---|---|
+| **Skill Description Completeness** | 10/10 | All 26 current skill directories have a complete four-row Skill Contract and the required trigger sections. Four PreToolUse hooks remain internal mechanisms, not standalone skills. |
+| **Routing Accuracy** | 9/10 | The local router passes 34/34 positive prompts across all 26 skills, including the foundation and meta routes added in this audit. Waza verification is not runnable in this Windows checkout; ambiguous/metaphorical generalization remains unmeasured. |
+| **Test Coverage of All Skills** | 9.5/10 | `npm test` now includes syntax, CLI, routing matrix, positive route coverage, references, behavioral-case structure, Fable contract, and mechanism checks. Waza and live model sessions remain separate CI/on-demand evidence. |
+| **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** | 8.5/10 | Every current skill has a matching workflow document, and `ci/skill-routing-check.js` executes every positive route case against the real router. Runtime tool-call sequence conformance remains host-dependent and is not claimed. |
+
+## 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** | 9/10 | See above — deterministic checks now cover syntax, routing, skill references, release-tag catalog, install tree/version drift, behavioral-case structure, and 12 mechanism suites. Live model evaluation remains on-demand and is not represented by a local simulation. |
+| **README Completeness** | 9.5/10 | Catalog counts, layer labels, route coverage, and the local baseline now match the current 26-skill tree. |
+| **Maintainability** | 9/10 | The custom cross-session todo CLI and obsolete multi-agent compatibility stubs are absent; route coverage is now a deterministic regression gate. |
+| **Skills Design** | 9.5/10 | All 26 current skills use the same four-row Skill Contract and exact trigger-section contract; internal hooks remain intentionally non-routable. |
+| **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. |
+
+## Change log by audit cycle
+
+### 2026-09-01
+- Fable v3 integration now exposes explicit Haiku, Sonnet, and Opus entrypoints, with deterministic model selection and visible inline fallback or blocked escalation in `fable-mode/model-matrix.json` and `fable-mode/scripts/model-selector.js`.
+- The current workflow uses native host TODO tracking or Markdown checklists. The older shared TODO CLI/state-machine references below are retained only as historical audit evidence; no runtime, test, or active workflow depends on them.
+- Strict catalog audit: removed obsolete compatibility directories and stale workflow; added the missing `find-skills` workflow.
+- Corrected current documentation and runtime references to the per-session `.claude/harness-everything/state/` path, aligned README/registry layer labels, and removed unimplemented workflow claims.
+- Added `ci/skill-routing-check.js`; all 34 positive routing cases across the 26-skill catalog pass locally, and all positive eval descriptions now exactly match their skill frontmatter.
+
+### 2026-07-26
+- `verify-gate.js` is no longer a simulated stub: it now discovers the nearest `package.json` (scoped to the enclosing git repo), runs its real `lint`/`test` scripts via the detected package manager (npm/pnpm/yarn/bun), and blocks completion on any failure. The `.verify-fail.tmp` injection hook is kept for hermetic mechanism tests, and `HARNESS_SKIP_PROJECT_CHECKS=1` guards against self-recursion in projects (like this one) whose test suite itself drives the Harness runtime. When no runnable scripts exist it exits 0 but explicitly warns that no mechanical checks ran — the exit code is not evidence.
+- CI added: `.github/workflows/ci.yml` runs `npm test` on push/PR, closing the "local-gate-only" gap called out in the previous cycle.
+- README restructured to be user-facing (problem → quick start → what gets installed/uninstall → platform support); audit narrative moved to this file.
+- `harness-everything/SKILL.md`: tier-router output wording and the Skill Contract now agree (router output is the default route, overridable with a one-line reason — previously the contract said "MUST follow" while the script itself said "default, not an order"); section numbering fixed (§5 registry now precedes §6).
+
+### 2026-07-23
+- VERIFICATION.md §2's mechanism checks automated (`npm run test:mechanism`).
+- VERIFICATION.md's test recipes rewritten to be Windows-safe (`node -e` stdin instead of a shell `echo` pipe).
+- Workflow progress is recorded in the host TODO tracker or a Markdown checklist.

package/docs/mechanism-first-skill-mesh.md

@@ -0,0 +1,163 @@
+# Mechanism-First Skill Mesh
+
+Harness is not intended to be a rigid workflow engine. Its skills should remain independently useful, while still coordinating through lightweight mechanisms that help the model and the software engineer work together with less drift, fewer loops, and better evidence.
+
+The preferred shape is a **mechanism-first skill mesh**: skills are autonomous, coordination is explicit, and enforcement happens at narrow decision points through scripts, hooks, exit codes, and compact return values.
+
+---
+
+## Design Intent
+
+Harness exists to improve engineering collaboration, not to replace model judgment with a fixed state machine.
+
+Each skill should be able to answer four questions on its own:
+
+1. **When should I activate?** The trigger should be clear without requiring another skill to interpret it.
+2. **What do I protect?** The skill should describe the failure mode it prevents or the engineering habit it reinforces.
+3. **What mechanism do I expose?** When possible, the skill should provide a script, command, checklist primitive, verifier, or return-value contract that makes its guidance concrete.
+4. **What should I hand to nearby skills?** The skill may recommend a next skill, but it should not require a global handoff template to remain useful.
+
+This keeps the system composable: `tdd` can run alone, `verification-loop` can run alone, `todo-driven-workflow` can run alone, and `harness-everything` can route among them when the task benefits from orchestration.
+
+---
+
+## Why Not a Single Handoff Block?
+
+A universal handoff block makes workflow state easy to parse, but it also has costs:
+
+- It encourages every platform and model to speak in the same rigid shape, even when a natural response would be clearer.
+- It can turn skills into a centralized workflow runner instead of a federation of local engineering disciplines.
+- It can make the model optimize for satisfying the template rather than making the best next engineering move.
+- It adds prompt weight on platforms where the mechanism cannot actually enforce the block.
+
+Harness should avoid mandatory global handoff text. Local skills may still use concise reports when they need them, but the mesh should not depend on one universal response format.
+
+---
+
+## Mechanisms Over Prose
+
+LLMs are highly sensitive to tool results, command outputs, exit codes, and short structured decisions. Harness should prefer those signals over long textual handoffs.
+
+Good mechanism outputs are:
+
+- **Short:** the result should be easy for the model to keep in active attention.
+- **Actionable:** the output should name the next constraint, gate, or recommended skill.
+- **Non-authoritarian:** the mechanism should guide the model without stealing all judgment from it.
+- **Portable:** hook-capable platforms can run the mechanism automatically; hook-less platforms can call the same script explicitly.
+
+Example shape:
+
+```text
+HARNESS_DECISION
+tier: 2
+load: todo-driven-workflow, verification-loop
+gate: verify-before-final
+reason: user requested code changes
+```
+
+This is not a handoff block. It is a compact mechanical signal. The model remains free to decide how to present the work, explain trade-offs, and collaborate with the engineer.
+
+---
+
+## Skill Autonomy Contract
+
+Every skill in the mesh should remain useful when loaded directly.
+
+Recommended contract:
+
+- **Independent trigger:** the skill description should identify the problem or situation that activates it.
+- **Local workflow:** the skill should contain enough guidance to execute without reading the whole Harness ecosystem.
+- **Mechanism hook:** if a script can make the skill more reliable, expose it as an optional or required command.
+- **Neighbor links:** when another skill is commonly needed, recommend it by name and explain why.
+- **Exit discipline:** if the skill reaches a blocking state, it should say what evidence is missing or what human decision is needed.
+
+This contract keeps skills interoperable without requiring central ownership of every task path.
+
+---
+
+## Coordination Patterns
+
+Harness should coordinate skills through small, composable patterns.
+
+### Router Decision
+
+`harness-everything/scripts/tier-router.js` is the model-facing triage mechanism. It should return the smallest useful routing decision: tier, rationale, suggested skills, and any gate that should apply before editing or final delivery.
+
+### Checklist State
+
+`todo-driven-workflow` should own task decomposition state when a task is Tier 2 or Tier 3. The state should be machine-readable when possible, but the model should not be forced into a single response format.
+
+### Verification Gate
+
+`verification-loop` and `verify-gate.js` should provide the delivery check. Hook-capable platforms can run it automatically before stop; hook-less platforms can run it as an explicit pre-final command.
+
+### Recovery Gate
+
+`rule-of-3` and `zoom-out` should coordinate through failure signatures and recovery instructions. The key handoff is the observed failure signature, not a prose summary.
+
+### Skill Suggestion
+
+`self-evolve` and generated skills should feed the router through manifest metadata. The router should surface likely skills, but the model keeps final responsibility for selecting what actually applies.
+
+---
+
+## Platform Strategy
+
+Harness should use the strongest mechanism each platform provides.
+
+| Platform class | Preferred coordination style | Enforcement level |
+| --- | --- | --- |
+| Hook-capable platforms | Hooks run routers, guards, trackers, and stop gates automatically | Mechanical blocking is possible |
+| CLI/tool-capable but hook-less platforms | The model explicitly calls Harness scripts at decision points | Mechanism-guided, not automatically enforced |
+| Prompt-only platforms | Advisory instructions include command snippets and decision rules | Self-regulated by the model |
+
+The same skills should work across all three classes. The difference is whether the mechanism is invoked automatically, explicitly, or only described.
+
+---
+
+## Guidance for Hook-Less Platforms
+
+Do not recreate hooks with a rigid universal handoff template. Instead, make mechanisms easy to call.
+
+Implemented today, both wired into `bin/cli.js` and referenced by name in the advisory text each platform's installer writes (`scripts/lib/advisory-text.js`):
+
+- `npx github:dyphn1/Harness-everything next "<prompt>"`: wraps `tier-router.js`, printing the recommended tier, base execution loop, and matching knowledge guides for a prompt.
+- `npx github:dyphn1/Harness-everything verify`: wraps `verify-gate.js`, running the target project's own lint/test scripts and exiting non-zero on failure. This is the explicit, hookless stand-in for Claude Code's `stop-gate.js`.
+
+Both resolve their target scripts relative to the CLI's own package install, not the caller's cwd, so they work the same way regardless of which platform-specific directory (`.codex/skills/`, `.cursor/skills/`, `.github/skills/`, ...) a copy of the `harness-everything` skill also happens to be sitting in - a fixed relative path like `harness-everything/scripts/tier-router.js` would silently point at nothing depending on which platform installed it.
+
+Not yet implemented - still aspirational, do not reference these as if they exist until they're built:
+
+- `harness recover`: summarize repeated failure signatures and recommend `zoom-out` when needed. Blocked on hookless platforms not having anything that collects failure signatures the way `rule-of-3.js`'s `PostToolUse` hook does on Claude Code - the state to summarize doesn't exist yet.
+- `harness skills`: list installed, generated, and matching skills for the current workspace.
+
+These commands let Codex, Cursor, Copilot, Continue, and Hermes receive high-signal mechanical feedback without forcing them into a single scripted conversation shape.
+
+---
+
+## Anti-Goals
+
+Harness should not become:
+
+- A centralized DAG runner where every skill depends on one global workflow file.
+- A mandatory response-template system that suppresses useful model variation.
+- A command-only framework where skills cannot be understood by reading `SKILL.md`.
+- A hidden daemon that performs broad actions without visible evidence.
+- A platform-specific product that only works well when Claude Code hooks are available.
+
+The mesh should remain local, legible, and cooperative.
+
+---
+
+## Practical Authoring Rules
+
+When adding or revising a skill:
+
+1. Keep the skill independently executable.
+2. Add a script only when a mechanism can make the behavior more reliable than prose.
+3. Keep script output compact and stable enough for models to react to.
+4. Prefer gates at natural decision points: before editing, after repeated failure, before final delivery, and before persistence.
+5. Let the model choose wording and presentation unless the skill truly needs a specific artifact format.
+6. Document neighboring skills as recommendations, not hidden dependencies, unless the dependency is required for safety.
+
+The result should feel like an engineering co-pilot with good reflexes: autonomous where creativity matters, constrained where repeated mistakes are expensive, and explicit whenever evidence is needed.

package/docs/philosophy.md

@@ -1,45 +1,47 @@
-# Harness Philosophy
-
-Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.** 
-
-Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral runtime**—a lightweight, non-intrusive layer that guides, guards, and immunizes.
-
----
-
-## The Core Philosophy: Intervene Only When Necessary
-
-Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it destroys the model's creative problem-solving capability when tackling complex, novel engineering challenges.
-
-Harness takes the opposite approach:
-
-1. **Model Autonomy is Paramount:** The model should have full freedom to explore, choose its tools, and design its solution.
-2. **Context-Driven Guidance:** Harness injects high-context, low-friction signals (via hooks, rules, and local preflight checks) rather than forcing rigid execution paths.
-3. **Reactive Guardrails:** Harness remains completely silent and out of the way until a critical failure state is detected (e.g., repeating the same error 3 times, or context bloat reaching a dangerous threshold).
-4. **Behavior-First, Not Prompt-First:** Harness is not a collection of static templates or "magic prompts." It is a dynamic runtime that reacts to terminal outcomes, git status, and actual workspace conditions.
-
----
-
-## The 4 Pillars of AI Model Guidance
-
-To keep agents aligned and productive, Harness operates across four distinct domains:
-
-### 1. Environment Alignment (Discovery over Assumption)
-AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shells, or package managers (especially on Windows or within sandboxed shells). 
-Harness forces a **Discovery** phase immediately upon session start. By auditing the environment beforehand, the model knows exactly what commands are safe to run, preventing wasted tokens on syntax trial-and-error.
-
-### 2. Guardrails (The Circuit Breakers)
-When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly (the "infinite loop of trial-and-error"). 
-Harness implements a **Circuit Breaker** (the `Rule of 3`). If the exact same failure occurs three times, Harness halts execution and forces a "zoom out": the agent must rebuild the full picture and fact-check the assumptions behind its failed attempts before it may touch the code again. Most loops die right there, resolved by a fresh diagnosis. The human partner is asked to step in only when a genuine decision is on the table — a requirement conflict, an architecture trade-off, a destructive step — preserving both your token budget and your sanity.
-
-### 3. Context Preservation (Anti-Bloat Protection)
-As sessions grow, models often read too many large files or run commands that generate massive output, causing severe "Lost in the Middle" attention degradation. 
-Harness acts as an informational dashboard that tracks active file counts and staging queues, proactively nudging the model to commit changes, clean the terminal, or compact its context.
-
-### 4. Self-Evolution (Continuous Workspace Memory)
-When a complex issue is resolved, the model should never have to solve it again. Harness abstracts the underlying root cause and permanently saves it to local workspace rules. On subsequent sessions, the model immediately imports these lessons, preventing regression.
-
----
-
-## A Non-Intrusive Cognitive Amplifier
-
-Harness does not run a heavy daemon, send your code to third-party APIs, or lock you into a proprietary ecosystem. It runs entirely locally within your project, acting as a quiet guardian that ensures your AI sessions are efficient, secure, and successful.
+# Harness Philosophy
+
+Harness is built on a single, core belief: **AI coding models are highly capable, but they struggle with self-regulation, attention drift, and environment awareness.** 
+
+Instead of replacing the model or restricting it with heavy, opinionated frameworks that stifle creativity, Harness acts as a **behavioral runtime**—a lightweight, non-intrusive layer that guides, guards, and immunizes.
+
+---
+
+## The Core Philosophy: Intervene Only When Necessary
+
+Many AI development frameworks attempt to fully control the model's execution flow. They use rigid DAGs, forced chains, or complex state machines. While this works for trivial, repetitive tasks, it destroys the model's creative problem-solving capability when tackling complex, novel engineering challenges.
+
+Harness takes the opposite approach:
+
+1. **Model Autonomy is Paramount:** The model should have full freedom to explore, choose its tools, and design its solution.
+2. **Context-Driven Guidance:** Harness injects high-context, low-friction signals (via hooks, rules, and local preflight checks) rather than forcing rigid execution paths.
+3. **Reactive Guardrails:** Harness remains completely silent and out of the way until a critical failure state is detected (e.g., repeating the same error 3 times, or context bloat reaching a dangerous threshold).
+4. **Behavior-First, Not Prompt-First:** Harness is not a collection of static templates or "magic prompts." It is a dynamic runtime that reacts to terminal outcomes, git status, and actual workspace conditions.
+
+---
+
+## The 4 Pillars of AI Model Guidance
+
+To keep agents aligned and productive, Harness operates across four distinct domains:
+
+### 1. Environment Alignment (Discovery over Assumption)
+AI models often hallucinate terminal environments or make incorrect assumptions about the host operating system, shells, or package managers (especially on Windows or within sandboxed shells). 
+Harness forces a **Discovery** phase immediately upon session start. By auditing the environment beforehand, the model knows exactly what commands are safe to run, preventing wasted tokens on syntax trial-and-error.
+
+### 2. Guardrails (The Circuit Breakers)
+When a model gets stuck on a subtle bug or compiler error, its natural tendency is to make micro-adjustments repeatedly (the "infinite loop of trial-and-error"). 
+Harness implements a **Circuit Breaker** (the `Rule of 3`). If the exact same failure occurs three times, Harness halts execution and forces a "zoom out": the agent must rebuild the full picture and fact-check the assumptions behind its failed attempts before it may touch the code again. Most loops die right there, resolved by a fresh diagnosis. The human partner is asked to step in only when a genuine decision is on the table — a requirement conflict, an architecture trade-off, a destructive step — preserving both your token budget and your sanity.
+
+### 3. Context Preservation (Anti-Bloat Protection)
+As sessions grow, models often read too many large files or run commands that generate massive output, causing severe "Lost in the Middle" attention degradation. 
+Harness acts as an informational dashboard that tracks active file counts and staging queues, proactively nudging the model to commit changes, clean the terminal, or compact its context.
+
+### 4. Self-Evolution (Continuous Workspace Memory)
+When a complex issue is resolved, the model should never have to solve it again. Harness abstracts the underlying root cause and permanently saves it to local workspace rules. On subsequent sessions, the model immediately imports these lessons, preventing regression.
+
+---
+
+## A Non-Intrusive Cognitive Amplifier
+
+Harness does not run a heavy daemon, send your code to third-party APIs, or lock you into a proprietary ecosystem. It runs entirely locally within your project, acting as a quiet guardian that ensures your AI sessions are efficient, secure, and successful.
+
+For the skill-level coordination philosophy, see [Mechanism-First Skill Mesh](mechanism-first-skill-mesh.md). It explains why Harness prefers autonomous skills coordinated by scripts, hooks, exit codes, and compact return values over a single rigid handoff template.