harness-everything 0.2.0

package/create-agent-launcher/templates/task-verifier.md

@@ -0,0 +1,56 @@
+---
+name: "Task Verifier"
+description: "Use when: verifying if the implemented changes meet the original requirements and AI implementation document. It checks modifications without editing files and re-dispatches tasks if errors are found."
+{{TOOLS_ARRAY_DECLARATION}}
+---
+
+You are an expert Quality Assurance and Task Verifier for the **{{PROJECT_NAME}}** project. Your responsibility is to inspect the codebase after a task has been implemented to ensure it perfectly matches the requirements.
+
+## Constraints
+
+- **NO MODIFICATION**: You are a Read-Only Auditor. DO NOT use `{{EDIT_TOOL_NAME}}` to modify any source code files. If you find an issue, your job is to fail the verification, not to fix it.
+- ONLY use `{{SEARCH_TOOL_NAME}}` and `{{READ_TOOL_NAME}}` to inspect the codebase state. NEVER alter repository state.
+- DO NOT attempt to fix errors yourself.
+- **NO AGENT INVOCATION**: You CANNOT use an `agent` tool to call other agents. Output a Handover Block to request a re-dispatch instead.
+
+## Behavioral Guidelines
+
+### Strict Binary Verification
+*(from Karpathy: Goal-Driven Execution)*
+- Compare actual changes against **each goal** listed in the implementation document.
+- This is a BINARY check. Partial fulfillment is a Fail ❌.
+- DO NOT suggest alternative designs or code improvements. Your only concern is compliance with the document.
+- If a requirement is ambiguous in the document, surface that ambiguity as a Fail ❌.
+
+### Zero Tolerance for Extraneous Code
+*(from Karpathy: Surgical Changes)*
+- Inspect the codebase using your read and search tools to verify what was changed. 
+- If you find code that was NOT explicitly requested in the plan (even if it looks like a good refactor or a nice-to-have fix), you MUST fail the verification and instruct the developer to revert the extraneous changes.
+
+### Categorize the Failure
+If verification fails, you MUST categorize the root cause of the failure:
+- `Implementation_Error`: The developer wrote bugged code or didn't follow the clear plan.
+- `Requirement_Ambiguity`: The plan itself is contradictory, missing edge cases, or logically flawed.
+- `Environment_Blocker`: Code seems right, but builds/tests fail due to missing dependencies, config issues, or OS limitations.
+- `Knowledge_Gap`: Missing context about internal libraries or third-party APIs.
+
+## Approach
+
+1. **Check Requirements Document**: Read the AI implementation document in `{{AI_PLAN_PATH}}` to understand the exact scope.
+2. **Review Modifications**: Review the Handover Block provided by the Developer to get the exact list of modified files and line ranges. Use `{{READ_TOOL_NAME}}` directly on those specific files to inspect their current contents. You do not need to do a blind search unless the Developer's list is incomplete.
+3. **Verify Compliance**: Cross-check actual code logic against the requirements and documented plan. Ensure no unrequested changes were made.
+4. **Handle Discrepancies**: Pass ✅ if all requirements are met. Fail ❌ and output a Handover Block with fix instructions if not.
+
+## Output Format
+
+```
+### 🤝 Handover Block
+- **Verification Status**: `[✅ Pass | ❌ Fail]`
+- **Failure Category**: `<Implementation_Error | Requirement_Ambiguity | Environment_Blocker | Knowledge_Gap | None>`
+- **Verified Against**: `<absolute path to implementation document>`
+- **Errors / Missing Items**: `<concise list, or 'None' if Pass>`
+- **Key Learnings (if any)**: `<Identify any novel problems solved, new architectural patterns used, or critical errors overcome during this task that should be committed to long-term memory. If none, write 'None'.>`
+- **Recommended Agent**: `<Agent Name if Fail, or 'None' if Pass>`
+- **Fix Instructions**: `<specific description of what needs to be fixed if Fail, or 'None' if Pass>`
+- **Action for Orchestrator**: I have completed my verification. Please refer to your central rules to determine the next step in the workflow (e.g. re-invoke developer, invoke memory keeper, or stop).
+```

package/create-agent-launcher/templates/tool-maker.md

@@ -0,0 +1,33 @@
+---
+name: "Tool Maker"
+description: "Use when: a repetitive or error-prone task (like file parsing, data extraction, or log analysis) needs to be automated via a small script to make the AI's autonomous capabilities more reliable."
+{{TOOLS_ARRAY_DECLARATION}}
+---
+
+You are the Tool Maker Agent for the **{{PROJECT_NAME}}** project. Your job is to create small, reliable, and reusable utility scripts (e.g., Python, Node.js, bash) that help the AI system bypass limitations or handle brittle operations (like complex file reading or text processing).
+
+## Constraints
+
+- DO NOT implement core application features.
+- DO NOT modify existing application source code unless it's a dedicated utility script directory (e.g., `scripts/ai_tools/`).
+- Scripts must be self-contained and require minimal external dependencies.
+- Scripts must be designed to be run from a standard terminal (CLI).
+- Output of the scripts must be clean, parsable, and AI-friendly (e.g., JSON or clear structured text).
+
+## Approach
+
+1. **Understand the Bottleneck**: Read the context provided by the Orchestrator regarding what operation is failing or is too repetitive (e.g., "The AI keeps failing to read line ranges in large CSVs").
+2. **Design the Tool**: Choose the appropriate scripting language (usually Python or Node.js depending on the project stack). Ensure it takes clear command-line arguments.
+3. **Implement**: Write the script and save it to the project's scripts directory (e.g., `{{SCRIPTS_DIR}}/`).
+4. **Test**: Run the script using the terminal to verify it works exactly as intended and handles edge cases (like file not found).
+5. **Document**: Add a brief usage example as a comment at the top of the script so other agents know how to use it.
+
+## Output Format
+
+```
+### 🛠️ Tool Created
+- **Tool Path**: `<path to the script>`
+- **Usage Command**: `<example command to run it>`
+- **Purpose**: <Brief description of what it solves>
+- **Action for Orchestrator**: Please pass this tool information back to the agent that requested it, or proceed with the workflow.
+```

package/create-agent-launcher/workflows/01-init.md

@@ -0,0 +1,22 @@
+# Phase 1: Platform & Location Preferences
+
+**[State Checkpoint]**
+- MUST verify the `Target Directory` absolute path passed from the previous step.
+
+## [Discovery & Inquiry Phase]
+1. Target Selection: MUST use `vscode_askQuestions` to ask platform and location in one prompt.
+   - Target Platform options MUST include Copilot, Claude, Gemini, and Codex.
+   - Target Location options MUST include Project Level and Global Level.
+   - MUST NOT auto-detect the platform.
+
+## [Validation & Research Phase]
+2. Load Guidelines: MUST read `guidelines/platform-<platform>.md` corresponding to the chosen platform. MUST treat this local file as the single source of truth. DO NOT perform web research for platform APIs unless explicitly instructed or if the file contains severe logic gaps.
+3. Conflict Assessment: MUST use the loaded layout rules to check if existing agents are already present in the target location within the `Target Directory`.
+
+## [Action Phase: Conflict Resolution]
+4. Preference Gathering: MUST use `vscode_askQuestions` to ask for Resilience Features configuration.
+5. Conflict Strategy: IF existing agents are found in the previous step, MUST ask for Conflict Resolution strategy (Safe Update, Backup & Overwrite, Smart Merge).
+
+## [Record: Handoff]
+6. State Packaging: MUST explicitly record the selected `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy`.
+7. Handoff: MUST execute `workflows/02-analysis.md` and explicitly pass these variables alongside the `Target Directory`.

package/create-agent-launcher/workflows/02-analysis.md

@@ -0,0 +1,26 @@
+# Phase 2: Project Analysis
+
+**[State Checkpoint]**
+- MUST verify the inheritance of `Target Directory`, `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy` from Phase 1.
+
+## [Discovery Phase: Content Extraction]
+1. Discovery Guide: MUST read `reference.md` for the discovery guide.
+2. Target Scanning: MUST scan the `Target Directory` for `README.md`, `AGENTS.md` (or `CLAUDE.md`), and build files (e.g., `package.json`, `*.sln`).
+3. Safe Extraction: For EACH discovered file, MUST read it securely and extract project name, tech stack, build commands, and architectural rules. IF a file does not exist, MUST skip it.
+4. Abstraction: MUST synthesize the extracted data into a `Context Profile` to prevent context bloat.
+
+## [Elimination & Evaluation Phase]
+5. Stack Detection: MUST determine the exact tech stack from the gathered signals (e.g., `.csproj` implies C#).
+6. Scope Limiting: MUST check for monorepo configuration (`pnpm-workspace.yaml`, `nx.json`).
+   - IF it IS a monorepo, MUST use `vscode_askQuestions` to ask the user to specify the target package/app. MUST NOT attempt to scaffold agents for the entire monorepo universally.
+7. Subagent Proposal: MUST propose specialist agents based on detected files (e.g., `.sh` implies Shell Expert). MUST NOT propose agents that duplicate core roles.
+
+## [Action Phase: User Confirmation & Gap Analysis]
+8. Selection: MUST use `vscode_askQuestions` to present a multi-select checklist of Subagents.
+   - MUST include Core agents: Requirement Analyzer, Backend Developer, Task Verifier.
+   - MUST include detected Specialist agents in the options.
+9. Batch Requirements Check: AFTER selection, MUST quickly assess the chosen templates for required Placeholders (e.g., `{{DB_TYPE}}`). IF the `Context Profile` lacks this data, MUST explicitly ask the user in ONE batched question to fill the gaps.
+10. Wait State: MUST wait for user to complete selection and variable input before proceeding.
+
+## [Record: Handoff]
+10. Handoff: MUST execute `workflows/03-generation.md` and explicitly pass the `Context Profile`, `Selected Agents`, and ALL Phase 1 variables.

package/create-agent-launcher/workflows/03-generation.md

@@ -0,0 +1,29 @@
+# Phase 3: Scaffold Generation
+
+**[State Checkpoint]**
+- MUST verify the inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and Phase 1 variables (`Platform`, `Conflict Strategy`, etc.).
+- MUST ensure terminal is located at the `Target Directory` BEFORE file modifications.
+
+## [Preparation Phase]
+1. Merge Strategy: MUST NOT overwrite existing agents blindly. MUST apply the `Conflict Strategy` selected in Phase 1. 
+   - IF `Smart Merge` is selected BUT the target agent belongs to a different platform architecture, MUST downgrade to `Backup & Overwrite` to prevent cross-platform hallucination.
+2. Semantic Integrity: IF Smart Merge, MUST perform Semantic Refactor aligning with Logical Consistency, Long-Term Memory, Self-Adaptation, and Self-Verification. MUST preserve original YAML Frontmatter.
+
+## [Action Phase: Generation]
+3. Template Iteration: For EACH selected agent in `Selected Agents`, MUST NOT read all templates at once to prevent context dilution. MUST process them one by one:
+   - MUST read the specific template.
+   - IF `Conflict Strategy` is Smart Merge AND the target file exists, MUST read the existing file BEFORE merging to prevent hallucination.
+   - MUST inject strict Cognitive Guardrails: MUST explicitly define Role Boundaries (refusing out-of-scope tasks), mandate the use of the Shared Memory Space (`memory-keeper`), and mandate deterministic outcome verification (no hallucinating success).
+   - MUST align generation with platform-specific capabilities (e.g., VS Code LSP tooltips vs Cursor rules) and inject localized task-tracking/TODO frameworks tailored to the target platform and specific agent role (ensuring each agent and platform gets its own isolated, native TODO tracking system, e.g., mapping to `manage_todo_list` for VS Code, `.cursorrules` checklists for Cursor, or unique agent-scoped status JSONs).
+   - MUST substitute placeholders using the `Context Profile`. IF a placeholder cannot be resolved, MUST NOT guess. MUST insert a conspicuous tag (e.g., `<<TODO: MANUAL_INPUT_REQUIRED>>` or localized `// TODO:` structured comments mapping to the active platform's task-tracking schema).
+   - MUST write files securely to destination paths from `guidelines/platform-<platform>.md`.
+4. Orchestrator Gen: MUST consult `guidelines/platform-<platform>.md` for Orchestrator requirements. MUST generate separate Orchestrator Instructions or update the root system prompt IF required.
+
+## [Summarize & Verification Phase]
+5. Integrity Check: MUST verify the generated files were written correctly to the disk by reading back portions or verifying their existence. Hallucinating success is forbidden.
+
+## [Record: Exit]
+6. Completion: MUST log successful Subagent generation.
+7. Handoff: MUST execute `workflows/04-launcher.md` and pass the `Context Profile`, `Selected Agents`, and paths of the newly created files to ensure the entry point is explicitly generated in a dedicated mental phase.
+
+[Exit: Await User Instruction]**'launch agent'** or describe your feature/task."

package/create-agent-launcher/workflows/04-launcher.md

@@ -0,0 +1,20 @@
+# Phase 4: Launcher Bootstrapping
+
+**[State Checkpoint]**
+- MUST verify the inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and paths of the newly created files from Phase 3.
+- MUST ensure terminal is located at the `Target Directory`.
+
+## [Action Phase: Entry Point Generation]
+1. Entry Point Gen: MUST read `templates/agent-launcher.md`.
+2. Handoff Integration: MUST substitute placeholders using the `Context Profile`. MUST dynamically inject the paths and roles of the `Selected Agents` into the Launcher, ensuring it accurately serves as the central router for the ecosystem.
+3. Disk Write: MUST save to the skill entry point path defined in the platform guidelines securely.
+
+## [Summarize: Verification]
+4. Check: MUST verify the Launcher was written successfully.
+
+## [Record: Exit]
+5. Completion: MUST report successful scaffold generation to the user. MUST provide a summary table of ALL generated files (including Subagents and the Launcher) and their status.
+6. UX Handoff: MUST prompt the user to launch their first agent workflow with a suggested message (e.g., "Agentic workflow scaffold is ready. To launch your first agent workflow, use the launcher...").
+7. Exit: MUST terminate execution.
+
+[Exit: Await User Instruction]

package/docker-verify.sh

@@ -0,0 +1,266 @@
+#!/bin/bash
+set -e # Exit immediately if a command exits with a non-zero status
+
+echo "================================================="
+echo "   Harness OS - Comprehensive Docker Verification   "
+echo "================================================="
+
+# 1. Prepare Git Environment (Subagent Scope Guard depends on Git)
+echo -e "\n[Step 1] Initializing local Git repository for tests..."
+if [ ! -d ".git" ]; then
+  git init
+  git config --global user.email "test@test.com"
+  git config --global user.name "Test Bot"
+  git add -A
+  git commit -m "initial commit for test"
+  echo "Git repository initialized and committed."
+else
+  echo "Git repository already exists."
+fi
+
+# 2. Run Self-Regression Test Suite
+echo -e "\n[Step 2] Running Harness Self-Regression tests..."
+npm test
+
+# 3. Mechanism Checks (from VERIFICATION.md Section 2)
+echo -e "\n[Step 3] Running Mechanism Checks..."
+
+# 3a. Rule of 3 Circuit Breaker actually blocks
+# Runtime state lives under .claude/harness-state/sessions/<session_id>/;
+# invocations with no session_id (like these bare/manual calls) fall into a
+# fixed sessions/default/ bucket.
+echo -e "\n---> Running 3a: Rule of 3 Circuit Breaker"
+mkdir -p .claude/harness-state/sessions/default
+rm -f .claude/harness-state/sessions/default/zoom-out-report.md
+echo '{"count":3,"lastHash":"verify-test","zoomOutResolved":false}' > .claude/harness-state/sessions/default/rule-of-3-state.json
+
+# We expect this to exit with 2 and print CRITICAL trigger message
+set +e
+node hooks/scripts/rule-of-3.js 2>rule-of-3-err.log
+EXIT_CODE=$?
+set -e
+
+echo "Exit code: $EXIT_CODE"
+if [ "$EXIT_CODE" -ne 2 ]; then
+  echo "❌ FAIL: Rule of 3 did not exit with code 2 (got $EXIT_CODE)"
+  exit 1
+fi
+
+if ! grep -q "RULE OF 3 CIRCUIT BREAKER TRIGGERED" rule-of-3-err.log; then
+  echo "❌ FAIL: Rule of 3 error output did not contain trigger message"
+  cat rule-of-3-err.log
+  exit 1
+fi
+echo "✅ PASS: Rule of 3 blocked successfully with exit code 2 and correct message."
+
+# Reset Rule of 3
+echo "Resetting circuit breaker..."
+npm run harness:reset
+set +e
+node hooks/scripts/rule-of-3.js
+EXIT_CODE=$?
+set -e
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "❌ FAIL: Rule of 3 reset check failed (expected 0, got $EXIT_CODE)"
+  exit 1
+fi
+echo "✅ PASS: Rule of 3 reset check passed."
+
+# 3a-bis. Zoom-out reflection report releases the breaker (self-recovery path)
+echo -e "\n---> Running 3a-bis: Zoom-out report releases the breaker"
+echo '{"count":3,"lastHash":"verify-test","zoomOutResolved":false,"lastFailureAt":0,"zoomOutCycles":0}' > .claude/harness-state/sessions/default/rule-of-3-state.json
+printf '## Goal\nx\n## Failed Attempts\nx\n## Verified Facts\nx\n## Diagnosis\nx\n## Decision\nRESUME: new approach\n' > .claude/harness-state/sessions/default/zoom-out-report.md
+
+set +e
+node hooks/scripts/rule-of-3.js
+EXIT_CODE=$?
+set -e
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "❌ FAIL: Valid reflection report did not release the breaker (expected 0, got $EXIT_CODE)"
+  exit 1
+fi
+if ! node -e "const s=require('./.claude/harness-state/sessions/default/rule-of-3-state.json'); process.exit(s.count===0 && s.zoomOutResolved===true && s.zoomOutCycles===1 ? 0 : 1)"; then
+  echo "❌ FAIL: Breaker state not updated after report release"
+  cat .claude/harness-state/sessions/default/rule-of-3-state.json
+  exit 1
+fi
+echo "✅ PASS: Valid reflection report released the breaker (self-recovery)."
+
+# Second trip on the same signature must hard-lock even though a report exists
+# (the report is stale relative to lastFailureAt, and the cycle budget is spent).
+node -e "require('fs').writeFileSync('.claude/harness-state/sessions/default/rule-of-3-state.json', JSON.stringify({count:3,lastHash:'verify-test',zoomOutResolved:false,lastFailureAt:Date.now()+60000,zoomOutCycles:1}))"
+set +e
+node hooks/scripts/rule-of-3.js 2>rule-of-3-err.log
+EXIT_CODE=$?
+set -e
+if [ "$EXIT_CODE" -ne 2 ]; then
+  echo "❌ FAIL: Second trip did not hard-lock (expected 2, got $EXIT_CODE)"
+  cat rule-of-3-err.log
+  exit 1
+fi
+if ! grep -q "hard lock" rule-of-3-err.log; then
+  echo "❌ FAIL: Second-trip output did not contain hard-lock escalation message"
+  cat rule-of-3-err.log
+  exit 1
+fi
+echo "✅ PASS: Second trip on the same signature hard-locked for human decision."
+npm run harness:reset
+
+
+# 3b. Boundary Guard blocks oversized read
+echo -e "\n---> Running 3b: Boundary Guard Oversized Read"
+node -e "require('fs').writeFileSync('.verify-big.tmp','x'.repeat(600*1024))"
+
+set +e
+echo '{"tool_name":"Read","tool_input":{"file_path":".verify-big.tmp"}}' | node hooks/scripts/boundary-guard.js 2>boundary-guard-err.log
+EXIT_CODE=$?
+set -e
+
+rm -f .verify-big.tmp
+
+echo "Exit code: $EXIT_CODE"
+if [ "$EXIT_CODE" -ne 2 ]; then
+  echo "❌ FAIL: Boundary Guard did not exit with code 2 (got $EXIT_CODE)"
+  exit 1
+fi
+
+if ! grep -q "BLOCKED" boundary-guard-err.log; then
+  echo "❌ FAIL: Boundary Guard error output did not contain BLOCKED"
+  cat boundary-guard-err.log
+  exit 1
+fi
+echo "✅ PASS: Boundary Guard blocked large read successfully."
+
+
+# 3c. State persistence (WAL) records failure and handles clear
+echo -e "\n---> Running 3c: State persistence (WAL)"
+rm -f .claude/harness-state/sessions/default/handoff-state.json
+
+# Record failure
+echo '{"tool_name":"Bash","tool_response":{"stdout":"","stderr":"npm ERR! verify-test failure"}}' | node hooks/scripts/state-persist.js
+
+if [ ! -f ".claude/harness-state/sessions/default/handoff-state.json" ]; then
+  echo "❌ FAIL: handoff-state.json was not created"
+  exit 1
+fi
+
+STATUS=$(node -e "console.log(JSON.parse(require('fs').readFileSync('.claude/harness-state/sessions/default/handoff-state.json','utf8')).status)")
+if [ "$STATUS" != "failed" ]; then
+  echo "❌ FAIL: Expected status to be 'failed', got '$STATUS'"
+  exit 1
+fi
+
+# Bootstrap output verification (pipe {} explicitly - bootstrap.js reads a
+# session_id off stdin same as every other hook, and a bare invocation's
+# stdin isn't guaranteed to close on its own in a non-interactive shell)
+BOOTSTRAP_OUT=$(echo '{}' | node harness-everything/scripts/bootstrap.js)
+if ! echo "$BOOTSTRAP_OUT" | grep -q "Harness OS - Handoff Checkpoint"; then
+  echo "❌ FAIL: Bootstrap output did not show handoff checkpoint box"
+  echo "$BOOTSTRAP_OUT"
+  exit 1
+fi
+echo "✅ PASS: State persistence correctly saved failure status."
+
+# Clean run to clear WAL
+echo '{"tool_name":"Bash","tool_response":{"stdout":"ok","exitCode":0}}' | node hooks/scripts/state-persist.js
+BOOTSTRAP_OUT_CLEAN=$(echo '{}' | node harness-everything/scripts/bootstrap.js)
+if echo "$BOOTSTRAP_OUT_CLEAN" | grep -q "Harness OS - Handoff Checkpoint"; then
+  echo "❌ FAIL: Bootstrap output still showed checkpoint box after clean run"
+  exit 1
+fi
+echo "✅ PASS: State persistence correctly cleared status on successful execution."
+
+
+# 3d. Fact-audit reminder reaches agent via stdin JSON
+echo -e "\n---> Running 3d: Fact-audit reminder"
+ROUTER_OUT=$(echo '{"prompt":"what exit code does this hook use by default and is it documented"}' | node harness-everything/scripts/tier-router.js)
+
+if ! echo "$ROUTER_OUT" | grep -q "FACT-AUDIT REMINDER"; then
+  echo "❌ FAIL: tier-router did not output FACT-AUDIT REMINDER on stdin JSON"
+  echo "$ROUTER_OUT"
+  exit 1
+fi
+echo "✅ PASS: Fact-audit reminder successfully outputted."
+
+
+# 3e. Subagent scope guard catches out-of-scope change
+echo -e "\n---> Running 3e: Subagent scope guard"
+# PreToolUse
+echo '{"tool_name":"Task","hook_event_name":"PreToolUse","tool_input":{}}' | node hooks/scripts/subagent-scope-guard.js
+
+# Make unexpected modification
+echo "unexpected change" >> .verify-scope-test.tmp
+
+# PostToolUse expect exit 2
+set +e
+echo '{"tool_name":"Task","hook_event_name":"PostToolUse","tool_input":{}}' | node hooks/scripts/subagent-scope-guard.js 2>scope-guard-err.log
+EXIT_CODE=$?
+set -e
+
+rm -f .verify-scope-test.tmp
+
+echo "Exit code: $EXIT_CODE"
+if [ "$EXIT_CODE" -ne 2 ]; then
+  echo "❌ FAIL: Subagent scope guard did not block out-of-scope changes (expected exit code 2, got $EXIT_CODE)"
+  exit 1
+fi
+
+if ! grep -q "Subagent Scope Guard" scope-guard-err.log || ! grep -q ".verify-scope-test.tmp" scope-guard-err.log; then
+  echo "❌ FAIL: Scope guard did not report the unexpected changed file"
+  cat scope-guard-err.log
+  exit 1
+fi
+echo "✅ PASS: Subagent scope guard successfully blocked out-of-scope modifications."
+
+
+# 3f. Stop gate bounces an unverified-edit stop exactly once
+echo -e "\n---> Running 3f: Stop Gate"
+rm -f .claude/harness-state/sessions/default/stop-gate-state.json
+node -e "require('fs').mkdirSync('.claude/harness-state/sessions/default',{recursive:true}); require('fs').writeFileSync('.claude/harness-state/sessions/default/handoff-state.json', JSON.stringify({status:'idle',lastEditAt:Date.now(),lastVerifyAt:0}))"
+echo "dirty" > .verify-dirty.tmp
+
+set +e
+echo '{}' | node hooks/scripts/stop-gate.js 2>stop-gate-err.log
+EXIT_CODE=$?
+set -e
+echo "Exit code: $EXIT_CODE"
+if [ "$EXIT_CODE" -ne 2 ]; then
+  echo "❌ FAIL: Stop gate did not bounce an unverified-edit stop (expected 2, got $EXIT_CODE)"
+  cat stop-gate-err.log
+  exit 1
+fi
+if ! grep -q "Stop Gate" stop-gate-err.log; then
+  echo "❌ FAIL: Stop gate output did not contain its message"
+  cat stop-gate-err.log
+  exit 1
+fi
+
+# Same edit batch must not bounce twice
+set +e
+echo '{}' | node hooks/scripts/stop-gate.js
+EXIT_CODE=$?
+set -e
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "❌ FAIL: Stop gate bounced the same edit batch twice (expected 0, got $EXIT_CODE)"
+  exit 1
+fi
+
+# Loop guard: stop_hook_active always passes
+rm -f .claude/harness-state/sessions/default/stop-gate-state.json
+set +e
+echo '{"stop_hook_active":true}' | node hooks/scripts/stop-gate.js
+EXIT_CODE=$?
+set -e
+if [ "$EXIT_CODE" -ne 0 ]; then
+  echo "❌ FAIL: Stop gate blocked despite stop_hook_active (expected 0, got $EXIT_CODE)"
+  exit 1
+fi
+rm -f .verify-dirty.tmp .claude/harness-state/sessions/default/handoff-state.json .claude/harness-state/sessions/default/stop-gate-state.json
+echo "✅ PASS: Stop gate bounced once, then respected the batch and loop guards."
+
+# Clean up temporary test output logs
+rm -f rule-of-3-err.log boundary-guard-err.log scope-guard-err.log stop-gate-err.log
+
+echo -e "\n================================================="
+echo " 🎉 ALL HARNESS MECHANISM CHECKS PASSED SUCCESSFULLY!"
+echo "================================================="

package/docs/architecture.md

@@ -0,0 +1,95 @@
+# 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 two kinds of content, kept apart by subfolder. `skills/` — Claude only, since Claude has no native project-skill directory to piggyback on — is the installer's local skill-copy target (see `scripts/lib/skills.js`'s `getInstalledSkills`, which is manifest-tracked, not a blind directory scan) — real files, not cache. Every other platform's skills stay at that platform's own established location (`.cursor/skills`, `.github/skills`, `.codex/skills`, `.continue/skills`) and are never moved. `state/` is pure runtime state: hook JSON, circuit-breaker counters, handoff/verification timestamps. It's scoped per Claude Code `session_id` under `sessions/<id>/` so two sessions open on the same repo never share (and stomp) each other's edit/verify timestamps or breaker counts — invocations with no `session_id` (manual runs, tests) fall into a fixed `sessions/default/` bucket. Both are gitignored and safe to delete; `state/` regenerates itself from nothing but in-session state (losing it mid-session just clears breaker/verification history), while deleting `skills/` requires re-running the installer to restore the copied skill files. A `manifest.json` sibling at the `harness-everything/` root records exactly what the installer put where, per platform, so uninstall never has to guess.
+
+### 1. Claude Code (hook-enforced)
+Our installer configures native lifecycle hooks inside `.claude/settings.json`:
+*   `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.

package/docs/philosophy.md

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

package/docs/reflection.md

@@ -0,0 +1,34 @@
+# Harness Reflection, Memory & Self-Evolution
+
+AI models are notorious for forgetting lessons learned in previous coding sessions. When a bug is solved, if the developer opens a new terminal or launches a new AI session, the agent may encounter the same environment quirks or framework gotchas and make the exact same mistakes again.
+
+Harness solves this through its **Self-Evolution and Persistent Memory system**.
+
+---
+
+## The Transaction Log (WAL) & Session Handoff
+
+Harness maintains a lightweight transaction log (analogous to a Write-Ahead Log in databases) via `hooks/scripts/state-persist.js`.
+
+*   **Continuous Capture:** Every successful tool use or milestone is recorded in the session transaction log.
+*   **Handoff File:** A session handoff checkpoint is saved in the workspace.
+*   **Session Start Recovery:** Upon starting a new session, the `bootstrap.js` hook reads the handoff file. It automatically "wakens" the agent, restoring the previous task state, completed milestones, and pending actions. This completely eliminates "session restart amnesia."
+
+---
+
+## Long-term Memory & Workspace Rules
+
+When a complex issue—such as an environment-specific bug, a unique framework quirk, or a custom build command requirement—is successfully resolved:
+
+1.  **Deep Reflection:** Harness triggers the `self-evolve` skill, directing the model to reflect on the root cause and extract the exact pattern.
+2.  **Rule Generation:** The model abstracts the learning into a concise rule (avoiding generic prompt prose).
+3.  **RULES.md Integration:** The rule is appended or merged into local workspace rules (usually under a `RULES.md` or a customized folder).
+4.  **Self-Regression Validation:** Before any new rule is persisted, Harness executes the `self-regression.js` test suite. This ensures that the generated rules do not conflict with existing core rules and that all script syntax is 100% correct, preventing behavior decay.
+
+---
+
+## The Benefits of Self-Evolution
+
+*   **Immunization:** The workspace is permanently "immunized" against recurring bugs.
+*   **Team Alignment:** Because rules are checked into Git, every developer (and every AI agent they launch) immediately benefits from the shared, updated knowledge base.
+*   **Token Efficiency:** Rather than the user repeatedly reminding the AI about custom project structures or conventions, the agent reads them natively from the immunized RULES file.