harness-everything 0.2.0

package/docs/workflows/todo-driven-workflow.md

@@ -0,0 +1,36 @@
+# Workflow: Todo-Driven Workflow
+
+> The fundamental execution loop. Driven entirely by terminal state machines (`todo-cli.js`).
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes the rigid state constraints. Transitioning state is blocked unless verification gates pass.
+
+```mermaid
+graph TD
+  Start([Initialize Checklist]) --> Plan["Define 3-7 Verifiable Sub-tasks"]
+  Plan --> SaveTodo["Try: node todo-cli.js init ..."]
+  
+  SaveTodo --> ChooseTask["Choose ONE pending task"]
+  ChooseTask --> MarkInProgress["Try: node todo-cli.js start <id>"]
+  
+  MarkInProgress --> CheckStart{Gate: Exit Code?}
+  CheckStart -->|Exit 1: Multitasking Blocked| ReflectStart["Reflect: Must complete previous task first"]
+  ReflectStart --> Execute
+  
+  CheckStart -->|Exit 0| Execute["Execute code changes"]
+  
+  Execute --> GatherEvidence["Try: node verify-gate.js"]
+  GatherEvidence --> VerifySuccess{Gate: Exit Code?}
+  
+  VerifySuccess -->|Exit 1: Code is broken| ReflectCode["Reflect: Read Error Log & Fix"]
+  ReflectCode --> Execute
+  
+  VerifySuccess -->|Exit 0: Code works| MarkCompleted["Try: node todo-cli.js complete <id>"]
+  
+  MarkCompleted --> CheckRemaining{All tasks completed?}
+  CheckRemaining -->|No| ChooseTask
+  CheckRemaining -->|Yes| Finish([Signal Task Completion])
+```

package/docs/workflows/using-git-worktrees.md

@@ -0,0 +1,63 @@
+# Workflow: Using Git Worktrees
+
+> Manages isolated workspace environments in parallel using native Git Worktrees, enabling developers to switch contexts safely without stashing or losing unsaved progress.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `using-git-worktrees` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Switch Context Needed]) --> CheckClean["Assess if main branch has uncommitted changes"]
+  CheckClean --> CreateWorktree["Run git worktree add to a sibling directory"]
+  CreateWorktree --> CheckoutTarget["Checkout target branch or create a hotfix branch"]
+  CheckoutTarget --> OpenWorkspace["Open the sibling directory as a separate isolated workspace"]
+  OpenWorkspace --> RunDev["Perform isolated edits, tests, and debugging"]
+  RunDev --> CommitIsolated["Commit changes in the isolated workspace"]
+  CommitIsolated --> RemoveWorktree["Prune and clean up the worktree path"]
+  RemoveWorktree --> Return([Return to original workspace with pristine unsaved state intact])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `using-git-worktrees` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Keyword: worktree / isolate / checkout| WT["using-git-worktrees / SKILL.md"]
+  WT -->|Maintains isolation before running tests in| TDDSkill["tdd / SKILL.md"]
+  WT -->|Protects terminal environment testing in| EnvSkill["environment-detection / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `using-git-worktrees` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Working on deep feature 'feat-billing' (unstaged edits)"] --> Interrupt["Urgent production hotfix required!"]
+  Interrupt --> Trigger["using-git-worktrees skill invoked"]
+  Trigger --> CreateWT["Add worktree: 'git worktree add ../hotfix-auth hotfix-branch'"]
+  CreateWT --> OpenWT["Open separate workspace editor in ../hotfix-auth"]
+  OpenWT --> FixBug["Fix auth bug & run verification test"]
+  FixBug --> CommitWT["Commit fix and push branch"]
+  CommitWT --> CloseWT["Close editor, run 'git worktree prune'"]
+  CloseWT --> Resume["Return to original billing workspace with all unsaved files exactly where they were"]
+  Resume --> Done([Context switched safely with zero stashing friction])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `using-git-worktrees` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/verification-loop.md

@@ -0,0 +1,69 @@
+# Workflow: Verification Loop
+
+> Comprehensive pre-PR quality gate executing builds, linting, type-checking, test suites, and security scans before claiming a task complete.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verification-loop` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Pre-PR Quality Check Triggered]) --> RunBuild["Execute compilation / project build"]
+  RunBuild --> CheckBuild{Build succeeded?}
+  CheckBuild -->|No| FixBuild["Debug and fix build errors"]
+  CheckBuild -->|Yes| RunTypeCheck["Execute language type-checking compiler"]
+  RunTypeCheck --> CheckTypes{Typecheck green?}
+  CheckTypes -->|No| FixTypes["Correct type-definition errors"]
+  CheckTypes -->|Yes| RunLint["Execute code linter checks"]
+  RunLint --> CheckLint{Lint clean?}
+  CheckLint -->|No| FixLint["Correct code-style and syntax errors"]
+  CheckLint -->|Yes| RunTests["Execute complete automated test suite"]
+  RunTests --> CheckTests{Tests passed?}
+  CheckTests -->|No| FixTests["Debug and correct failing tests"]
+  CheckTests -->|Yes| End([Pre-PR verification gate cleared successfully])
+  FixBuild & FixTypes & FixLint & FixTests --> RunBuild
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verification-loop` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Pre-PR checks / gate| VerLoop["verification-loop / SKILL.md"]
+  VerLoop -->|Guards finalize step in| Todo["todo-driven-workflow / SKILL.md"]
+  VerLoop -->|Requires test environment setup from| Env["environment-detection / SKILL.md"]
+  VerLoop -->|Precedes safe commit push in| GitCommit["git-commit / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verification-loop` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Feature code written; ready to claim task complete"] --> Trigger["verification-loop skill runs"]
+  Trigger --> Build["Run 'npm run build' -> Succeeded"]
+  Build --> Type["Run 'npm run typecheck' -> Found 2 type mismatches in routes.ts"]
+  Type --> FixT["Fix incorrect type casting in routes.ts"]
+  FixT --> Recheck["Re-run typecheck -> Succeeded"]
+  Recheck --> Lint["Run 'npm run lint' -> Clean"]
+  Lint --> Tests["Run 'npm run test' -> 24 tests passed"]
+  Tests --> Done([Verification loop complete; safe to open PR])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verification-loop` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/verify-before-claim.md

@@ -0,0 +1,60 @@
+# Workflow: Verify Before Claim
+
+> Fact-audit discipline requiring empirical verification of external claims, SDK configurations, defaults, and unmeasured performance estimates.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `verify-before-claim` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([Claim or Estimate Proposed]) --> IdentifyAssumptions["Isolate any claim or performance assumption"]
+  IdentifyAssumptions --> QueryAuthoritative["Execute WebSearch or read local code sources"]
+  QueryAuthoritative --> CrossVerify["Cross-verify details with authoritative documentation"]
+  CrossVerify --> RunLocalExperiment["Run quick script to empirically test the assumption"]
+  RunLocalExperiment --> CaptureResult["Log actual measured results and exit-codes"]
+  CaptureResult --> AssertFact["Assert verified fact based on objective data"]
+  AssertFact --> End([Hypothesis replaced with empirical truth])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `verify-before-claim` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  Router["harness-everything / tier-router.js"] -->|Requires fact checking or estimates| VBC["verify-before-claim / SKILL.md"]
+  VBC -->|Empirical verification helper| RunCode["mcp_provides_tool_pylanceRunCodeSnippet / run_in_terminal"]
+  VBC -->|Secures quality of decisions in| GWD["grill-with-docs / SKILL.md"]
+  VBC -->|Verifies assertions in testing suite| TDD["tdd / SKILL.md"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `verify-before-claim` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Developer assumes: 'Node.js fs.rmSync returns boolean upon success'"] --> Trigger["verify-before-claim skill triggered"]
+  Trigger --> ReadDocs["Checks Node.js documentation via WebSearch"]
+  ReadDocs --> FindTrue["Discovers fs.rmSync returns 'undefined' on success, and throws on failure"]
+  FindTrue --> TestCode["Executes quick Node snippet to confirm empirical behavior"]
+  TestCode --> UpdateCode["Refactors proposed catch-blocks to handle exceptions instead of checking booleans"]
+  UpdateCode --> Done([Potential production runtime crash prevented])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `verify-before-claim` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/docs/workflows/zoom-out.md

@@ -0,0 +1,62 @@
+# Workflow: Zoom Out
+
+> High-level reflection report generation to break out of error loops, analyze failure patterns, and backtrack to alternative paths.
+
+---
+
+## 1. Skill Behavior Workflow
+
+This section visualizes how the `zoom-out` skill executes internally, detailing the sequence of operations, state transitions, and evaluation steps.
+
+```mermaid
+graph TD
+  Start([3 Consecutive Errors Triggered]) --> Tripped{Rule of 3 Tripped?}
+  Tripped -->|No| Backtrack["Review code change and retry"]
+  Tripped -->|Yes| LockWork["Lock all file edit capabilities"]
+  LockWork --> GatherState["Analyze current working directory, file states, and errors"]
+  GatherState --> GenReport["Compile formal Reflection Report: what failed, assumptions, backtracking options"]
+  GenReport --> PresentReport["Present report to human partner and request guidance"]
+  PresentReport --> End([Workforce unlocked after human direction received])
+```
+
+---
+
+## 2. Triggering and Routing Path
+
+This diagram illustrates how the `zoom-out` skill is triggered through user requests or developer actions, and how it integrates or chains together with other companion skills in the Harness OS ecosystem to form unified workflows.
+
+```mermaid
+graph LR
+  RuleOf3["Rule of 3 Circuit Breaker"] -->|Tripped!| ZoomOut["zoom-out / SKILL.md"]
+  ZoomOut -->|Halts execution for| ActiveWork["Active workspace edits"]
+  ZoomOut -->|Asks for human direction via| AskQuestions["vscode_askQuestions"]
+  ZoomOut -->|Unlocks workspace state after| HumanReset["Human Partner Response"]
+```
+
+---
+
+## 3. Real-World Use Case Flowchart
+
+Here we model concrete real-world scenarios and use cases of the `zoom-out` skill, illustrating standard success paths, error handling, or recovery loops.
+
+```mermaid
+graph TD
+  Start["Attempting to fix Python import error; fails 3 times consecutively with same trace"] --> Trigger["Rule of 3 circuit breaker trips"]
+  Trigger --> Lock["Workspace writes locked"]
+  Trigger --> Collect["Collect error traces and diff history"]
+  Collect --> WriteReport["Create docs/reflection/zoom-out-report.md detailing the import cyclic dependency"]
+  WriteReport --> Present["Present options to human: Option A - Merge imports, Option B - Extract shared modules"]
+  Present --> UserChoice["User select: 'Option B'"]
+  UserChoice --> Unlock["Unlock workspace and execute Option B"]
+  Unlock --> Done([Error loop successfully broken and resolved])
+```
+
+---
+
+## 4. Verification Check
+
+To ensure that the `zoom-out` skill is operating in strict compliance with Harness OS design laws, verify the following:
+
+- [ ] **Physical Boundary Verification**: The skill boundaries are respected and do not leak context.
+- [ ] **State Checkpoint Verification**: The active state is established, validated, and recorded at the beginning and end of each execution branch.
+- [ ] **Cognitive Alignment**: The skill conforms to the **Think > Try > Summarize > Record** cognitive loop.

package/environment-detection/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: environment-detection
+description: Use at the very beginning of the session (Discover phase) to automatically detect and align with the operating system, terminal shell (e.g. Git Bash vs PowerShell vs Command Prompt), package managers, and development tools. Prevents blind command execution and repetitive tool-related errors.
+author: Miya Daniel | Harness Core Team
+version: 0.2.0
+---
+
+# Environment Detection & Shell Alignment
+
+## 📋 Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Session Start (Discover Phase), or before executing a complex terminal command sequence. |
+| **Expected Output** | Terminal execution of `node <this-skill-dir>/scripts/preflight.js`. Output of the detected OS and Shell. |
+| **State Mutations** | Context is updated with the correct path separator (`/` vs `\`) and environment variable syntax (`$VAR` vs `%VAR%`). |
+| **Enforcement Gate** | You MUST read the terminal output of `preflight.js`. If you use the wrong syntax (e.g. `%VAR%` in bash), the terminal will naturally Exit 1 and block your progress. |
+
+## Core Principles
+- **MUST** operate using the cognitive loop: Think > Try > Summarize > Record.
+- **[Think]**: Before running any terminal commands, check your environment. Blind execution is the primary source of agent step waste.
+- **[Try]**: Run the automated preflight check script to determine exact platform properties.
+- **[Summarize]**: Output the detected terminal, OS, and toolchains so the session context retains these bounds.
+- **[Record]**: Adopt the corresponding command syntax rules for the rest of the conversation.
+
+## Strict Workspace Boundary (僅偵測與操作當前工作區)
+- **Current Workspace Only**: 必須僅偵測與操作當前活動工作區目錄（即當前專案根目錄，亦為 `process.cwd()`）。
+- **Ignore Other Workspaces**: 即使 VS Code 內容或歷史記錄中暴露了其他工作區、暫存路徑或最近開啟的專案（例如 `d:\super.h2o.sbom`、`d:\DeveloperDocs`、`c:\Users\DanielCH.Chang\Desktop\XinputDxe_V0.0.5` 等），你也 **必須完全忽略它們**。絕對不要對這些非當前專案之路徑進行結構分析、工具檢查，更不能在其中執行任何終端機指令。
+- **Single-Workspace Execution**: 所有終端機指令、工具可用性檢查、路徑解析均必須嚴格限制在當前專案根目錄內。嚴格禁止跨越邊界操作鄰近或無關的資料夾。
+
+## [State Checkpoint]
+- Verify your environment details *before* executing commands or writing files.
+- If you just started a session, run the preflight script immediately.
+
+## [Discovery Phase: Environment Audit]
+1. Run the preflight script that lives at `scripts/preflight.js` **inside this skill's own directory** — resolve the path from wherever this SKILL.md was loaded (do not guess a hard-coded location):
+   ```bash
+   node "<this-skill-dir>/scripts/preflight.js"
+   ```
+2. Parse the output and understand:
+   - Operating System (Windows vs. macOS vs. Linux)
+   - Active Shell (Git Bash vs. PowerShell vs. Command Prompt)
+   - Available CLI Tools (node, pnpm, docker, python, etc.)
+3. **Toolchain Self-Heal (工欲善其事,必先利其器)**: The harness itself is part of the environment. Audit whether this workspace's integration touchpoints (`.claude/settings.json` hooks, `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.md`) are installed, and repair any missing ones — e.g., installed via Claude Code but now opened in Copilot:
+   ```bash
+   node "<skills-repo-root>/harness-everything/scripts/self-heal.js"
+   ```
+   The script is idempotent (it delegates to the installer, which merges hooks by id and never duplicates advisory text), so running it on an already-healthy workspace is a no-op. Skip only if the user intentionally removed a touchpoint file.
+
+## [Execution Phase: Syntax and Command Alignment]
+Choose the correct syntax matching your active shell:
+
+### 1. Git Bash on Windows (User's Preferred Terminal)
+- **Path Slashes**: Always use forward slashes `/` (e.g., `scripts/lib/utils.js`). Never use raw backslashes `\` because they act as escape characters in Bash.
+- **Env Variables**: Use `$VARIABLE_NAME` syntax. Do NOT use `%VARIABLE_NAME%` or `$env:VARIABLE_NAME`.
+- **Command Set**: Standard Unix commands are fully supported (`ls`, `rm -rf`, `mkdir -p`, `cp`, `mv`). Do NOT run CMD native commands like `dir`, `del`, or `copy`.
+- **No PowerShell syntax**: Do not run PowerShell-specific scripts or syntax.
+
+### 2. PowerShell on Windows
+- **Path Slashes**: Forward slashes `/` or backslashes `\\` are both acceptable.
+- **Env Variables**: Use `$env:VARIABLE_NAME` syntax.
+- **Command Set**: Use standard PowerShell commands or common aliases (e.g., `New-Item`, `Remove-Item`).
+
+### 3. Windows Command Prompt (CMD)
+- **Path Slashes**: Use backslashes `\` for file paths.
+- **Env Variables**: Use `%VARIABLE_NAME%` syntax.
+- **Command Set**: Use `dir`, `del`, `copy`, `mkdir`. Do NOT use `ls`, `rm`, `cp`, `mkdir -p`.
+
+## [Verification & Reflection Phase]
+3. If any shell command fails, do **not** blindly retry the exact same command. 
+4. Stop and ask yourself: "Did I use the wrong syntax for this terminal? Is this a Git Bash vs. PowerShell syntax issue?"
+5. If you fail 3 times on the same command, trigger the `zoom-out` circuit breaker.
+
+## Red Flags & Common Errors
+- ❌ **CMD commands in Git Bash**: Attempting to run `dir` or `del` when the terminal is actually running Git Bash.
+- ❌ **PowerShell commands in Bash**: Attempting to run `$env:PATH` or `.ps1` files in a Bash environment.
+- ❌ **Path escape failures**: Sending raw Windows paths like `scripts\run.js` inside a Bash terminal, which interprets `\r` as a carriage return or escapes characters.

package/environment-detection/scripts/preflight.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+function checkCmd(cmd) {
+  try {
+    if (os.platform() === 'win32') {
+      execSync(`where ${cmd}`, { stdio: 'ignore' });
+    } else {
+      execSync(`which ${cmd}`, { stdio: 'ignore' });
+    }
+    return true;
+  } catch (e) {
+    try {
+      execSync(`${cmd} --version`, { stdio: 'ignore' });
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+console.log("# [Environment Preflight Report]");
+console.log(`- **Operating System**: ${os.platform()} (${os.release()} ${os.arch()})`);
+
+// Shell Detection
+let shell = process.env.SHELL || process.env.COMSPEC || "Unknown";
+let shellName = "Unknown Shell";
+
+if (shell.toLowerCase().includes("bash")) {
+  shellName = "Git Bash / Bash";
+} else if (shell.toLowerCase().includes("powershell") || shell.toLowerCase().includes("pwsh") || process.env.PSModulePath) {
+  shellName = "PowerShell";
+} else if (shell.toLowerCase().includes("cmd.exe")) {
+  shellName = "Windows Command Prompt (CMD)";
+} else {
+  shellName = shell;
+}
+
+console.log(`- **Active Shell**: ${shellName} (Path: \`${shell}\`)`);
+console.log(`- **Terminal Program**: ${process.env.TERM_PROGRAM || "Standard Terminal"}`);
+
+// CLI Tools Check
+const tools = ['git', 'docker', 'docker-compose', 'node', 'pnpm', 'npm', 'python', 'pip'];
+const availableTools = [];
+for (const tool of tools) {
+  if (checkCmd(tool)) {
+    availableTools.push(tool);
+  }
+}
+console.log(`- **Available CLI Tools**: ${availableTools.join(', ') || 'None'}`);
+
+// Sandbox Capabilities Detection
+const hasDocker = availableTools.includes('docker');
+const hasSandboxExec = checkCmd('sandbox-exec');
+const sandboxCapabilities = [];
+if (hasSandboxExec) sandboxCapabilities.push('macOS Seatbelt (sandbox-exec)');
+if (hasDocker) sandboxCapabilities.push('Docker Containers');
+if (os.platform() === 'win32') {
+  sandboxCapabilities.push('Windows AppContainer (Native)');
+}
+console.log(`- **Sandbox Capabilities**: ${sandboxCapabilities.join(', ') || 'No isolation sandbox detected'}`);
+
+// Repo Status
+try {
+  const branch = execSync('git branch --show-current', { encoding: 'utf8' }).trim();
+  console.log(`- **Git Workspace**: Detected (Branch: \`${branch}\`)`);
+} catch (e) {
+  console.log(`- **Git Workspace**: No git repository detected in ${process.cwd()}`);
+}
+
+// Recommended Syntax Guardrails
+console.log("\n## [Syntax & Command Guardrails for this Environment]");
+if (os.platform() === 'win32') {
+  if (shellName.includes("Bash")) {
+    console.log("- **Path Handling**: ALWAYS use `/` slashes for directory paths in commands (e.g., `scripts/run.js`). Avoid raw backslashes `\\` as they act as escape chars.");
+    console.log("- **Environment Variables**: Use `$VAR` syntax. Do NOT use `%VAR%` or `$env:VAR`.");
+    console.log("- **Command Chaining**: Use `&&` for sequence, `|` for piping.");
+    console.log("- **Avoid Native Windows Commands**: Do NOT use `dir`, `copy`, or `del`. Use bash standard equivalents `ls`, `cp`, `rm`.");
+  } else if (shellName.includes("PowerShell")) {
+    console.log("- **Path Handling**: Slashes `/` or `\\` are generally acceptable.");
+    console.log("- **Environment Variables**: Use `$env:VAR` syntax.");
+    console.log("- **Command Chaining**: Use `;` or `&&` (if PowerShell 7+). Avoid bash-specific commands like `grep`, `awk`, `sed` unless explicitly piping.");
+  } else {
+    console.log("- **Path Handling**: Use `\\` for directories.");
+    console.log("- **Environment Variables**: Use `%VAR%`.");
+    console.log("- **Chaining**: Use `&`.");
+  }
+} else {
+  console.log("- **Unix Native**: Standard Bash/Zsh syntax applies. Use relative paths, pipeline chaining, and standard utilities.");
+}

package/eval-framework/behavioral-test.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Harness Behavioral Test Suite (E2E)
+ * Simulates an AI agent attempting both valid and invalid state transitions
+ * to mathematically prove the guardrails (Exit Code 1) are enforced.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getStateRoot } = require('../hooks/scripts/lib/harness-state');
+
+console.log("=== 🧪 Harness Behavioral Test Suite ===");
+
+const todoCli = 'node harness-everything/scripts/todo-cli.js';
+const stateFile = path.join(getStateRoot(getWorkspaceRoot()), 'todo-state.json');
+
+function run(cmd, expectFail = false) {
+  try {
+    const out = execSync(cmd, { stdio: 'pipe', encoding: 'utf8' });
+    if (expectFail) {
+      console.error(`❌ FAILED: Expected command to fail, but it succeeded: ${cmd}`);
+      process.exit(1);
+    }
+    return out;
+  } catch (err) {
+    if (!expectFail) {
+      console.error(`❌ FAILED: Unexpected failure: ${cmd}\n${err.stderr || err.message}`);
+      process.exit(1);
+    }
+    return err.stderr || err.stdout || err.message;
+  }
+}
+
+// 0. Setup: Clean slate - but this suite runs against the REAL
+// .claude/harness-state/ directory of whatever project invokes it (e.g. via self-regression.js on
+// a contributor's machine), so any real in-flight todo-state.json must be
+// preserved, not clobbered. Back it up now and restore it on exit
+// (success, assertion failure, or process.exit alike - 'exit' fires on all
+// of them) instead of deleting real state outright.
+const stateBackup = stateFile + '.selfregression-backup';
+const hadExistingState = fs.existsSync(stateFile);
+if (hadExistingState) fs.copyFileSync(stateFile, stateBackup);
+if (fs.existsSync(stateFile)) fs.unlinkSync(stateFile);
+if (fs.existsSync('.verify-fail.tmp')) fs.unlinkSync('.verify-fail.tmp');
+console.log("🧹 State cleaned.");
+
+process.on('exit', () => {
+  try {
+    if (hadExistingState) {
+      fs.copyFileSync(stateBackup, stateFile);
+      fs.unlinkSync(stateBackup);
+    } else if (fs.existsSync(stateFile)) {
+      fs.unlinkSync(stateFile);
+    }
+    if (fs.existsSync('.verify-fail.tmp')) fs.unlinkSync('.verify-fail.tmp');
+  } catch (e) {
+    // Best-effort - don't mask the real test outcome with a cleanup error.
+  }
+});
+
+// 1. Initialize
+console.log("\n[Test 1] Agent initializes checklist...");
+run(`${todoCli} init "Setup DB" "Create API"`);
+console.log("✅ Passed: List initialized.");
+
+// 2. Premature Completion (Skipping 'start')
+console.log("\n[Test 2] Agent hallucinates completion without starting...");
+const res2 = run(`${todoCli} complete 1`, true);
+if (!res2.includes("NOT currently in-progress")) {
+  console.error("❌ FAILED: Did not catch premature completion.");
+  process.exit(1);
+}
+console.log("✅ Passed: Blocked premature completion (Exit Code 1).");
+
+// 3. Start Task
+console.log("\n[Test 3] Agent starts task 1...");
+run(`${todoCli} start 1`);
+console.log("✅ Passed: Task 1 started.");
+
+// 4. Multitasking (Attention Loss)
+console.log("\n[Test 4] Agent loses attention and tries to start Task 2 concurrently...");
+const res4 = run(`${todoCli} start 2`, true);
+if (!res4.includes("already IN-PROGRESS")) {
+  console.error("❌ FAILED: Did not block multitasking.");
+  process.exit(1);
+}
+console.log("✅ Passed: Blocked multitasking (Exit Code 1).");
+
+// 5. Verification Failure (Compliance Theater)
+console.log("\n[Test 5] Agent writes broken code and tries to force complete...");
+fs.writeFileSync('.verify-fail.tmp', 'broken');
+const res5 = run(`${todoCli} complete 1`, true);
+if (!res5.includes("Verification Gate Failed")) {
+  console.error("❌ FAILED: Verification gate failed to block completion.");
+  process.exit(1);
+}
+console.log("✅ Passed: Gate blocked completion and slapped agent (Exit Code 1).");
+
+// 6. Successful Verification and Completion
+console.log("\n[Test 6] Agent fixes code, verification passes, completes task...");
+fs.unlinkSync('.verify-fail.tmp'); // Fix the "bug"
+run(`${todoCli} complete 1`);
+console.log("✅ Passed: Task 1 completed successfully.");
+
+console.log("\n🎉 ALL BEHAVIORAL TESTS PASSED. Guardrails are mathematically enforced.");

package/eval-framework/cases/case1.json

@@ -0,0 +1,5 @@
+{
+  "name": "Refactoring large module",
+  "prompt": "We need to refactor the entire authentication architecture",
+  "expected_tier": "Tier 3"
+}

package/eval-framework/cases/case2.json

@@ -0,0 +1,5 @@
+{
+  "name": "Small bugfix",
+  "prompt": "Fix the typo in the login screen",
+  "expected_tier": "Tier 1"
+}

package/eval-framework/cases/case3.json

@@ -0,0 +1,5 @@
+{
+  "name": "API implementation with tests",
+  "prompt": "Implement the new payment API and write integration tests",
+  "expected_tier": "Tier 2"
+}

package/eval-framework/cases/case4-zh-tier2.json

@@ -0,0 +1,5 @@
+{
+  "name": "Chinese prompt - API with tests",
+  "prompt": "幫我實作新的付款 API 並寫整合測試",
+  "expected_tier": "Tier 2"
+}

package/eval-framework/cases/case5-zh-tier3.json

@@ -0,0 +1,5 @@
+{
+  "name": "Chinese prompt - architectural refactor",
+  "prompt": "重構整個認證模組的架構",
+  "expected_tier": "Tier 3"
+}