harness-everything 0.2.2 → 0.4.0

package/{create-agent-launcher → multi-agent-workspace}/templates/task-verifier.md

@@ -1,56 +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).
+---
+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 → multi-agent-workspace}/templates/tool-maker.md

@@ -1,33 +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.
+---
+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/multi-agent-workspace/workflows/01-init.md

@@ -0,0 +1,22 @@
+# Phase 1: Platform & Location Preferences
+
+**[State Checkpoint]**
+- Verify the `Target Directory` absolute path passed from the initial context.
+
+## [Discovery & Inquiry Phase]
+1. Target Selection: First, auto-detect the current environment and target platform (`[Discover]`).
+   - Supported target platforms and enforcement levels: see [README § Supported AI IDEs & Tools](../../README.md#supported-ai-ides--tools) (platform-specific scaffold guidance lives in `guidelines/platform-<platform>.md`, listed above). Only **Claude Code** supports hard enforcement via native lifecycle hooks (`exit 2`); all other target platforms operate via prompt-based advisory rules.
+   - If interactive inquiry tools (like `vscode_askQuestions`) are available, confirm platform and scope location (Project Level vs Global Level) with the user.
+   - If running in a non-interactive terminal or without GUI inquiry tools, proceed with the auto-detected platform and default to Project Level location.
+
+## [Validation & Research Phase]
+2. Load Guidelines: Read `guidelines/platform-<platform>.md` corresponding to the chosen platform. Treat this local file as the primary source of truth. Avoid unnecessary web searches unless platform APIs are ambiguous.
+3. Conflict Assessment: 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: If interactive inquiry tools are available, confirm Resilience Features configuration; otherwise default to standard resilience.
+5. Conflict Strategy: If existing agents are found, confirm the Conflict Resolution strategy (Safe Update by default, Backup & Overwrite, or Smart Merge).
+
+## [Record: Handoff]
+6. State Packaging: Record the selected `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy`.
+7. Handoff: Load and execute `workflows/02-analysis.md`, passing these variables alongside `Target Directory`.

package/multi-agent-workspace/workflows/02-analysis.md

@@ -0,0 +1,23 @@
+# Phase 2: Project Analysis
+
+**[State Checkpoint]**
+- Verify inheritance of `Target Directory`, `Platform`, `Location`, `Resilience Features`, and `Conflict Strategy` from Phase 1.
+
+## [Discovery Phase: Content Extraction]
+1. Discovery Guide: Read `reference.md` for guidance on repo scanning.
+2. Target Scanning: Scan `Target Directory` for `README.md`, `AGENTS.md` (or `CLAUDE.md`), and build configuration files (e.g. `package.json`, `*.sln`).
+3. Safe Extraction: Read discovered files to extract project name, tech stack, build commands, and architectural conventions. Skip missing optional files gracefully.
+4. Abstraction: Synthesize extracted signals into a concise `Context Profile` to manage context window usage.
+
+## [Elimination & Evaluation Phase]
+5. Stack Detection: Determine the tech stack based on project files (e.g. `.csproj` for C#, `package.json` for Node/TS).
+6. Scope Limiting: Check for monorepo configuration (`pnpm-workspace.yaml`, `nx.json`).
+   - For monorepos, prompt the user to specify the target package/app rather than scaffolding blindly for the entire repository.
+7. Subagent Proposal: Recommend relevant specialist roles based on detected files (e.g. Shell Expert if `.sh` scripts exist). Avoid duplicating core agent roles.
+
+## [Action Phase: User Confirmation & Gap Analysis]
+8. Selection: Present recommended Subagent options to the user (e.g. Requirement Analyzer, Backend Developer, Task Verifier, plus detected specialists).
+9. Batch Requirements Check: Check selected templates for required placeholders (e.g. `{{DB_TYPE}}`). If missing from `Context Profile`, request missing inputs in one concise inquiry.
+
+## [Record: Handoff]
+10. Handoff: Load and execute `workflows/03-generation.md`, passing the `Context Profile`, `Selected Agents`, and all Phase 1 variables.

package/multi-agent-workspace/workflows/03-generation.md

@@ -0,0 +1,25 @@
+# Phase 3: Scaffold Generation
+
+**[State Checkpoint]**
+- Verify inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and Phase 1 variables (`Platform`, `Conflict Strategy`, etc.).
+- Ensure directory context matches `Target Directory` before performing file modifications.
+
+## [Preparation Phase]
+1. Merge Strategy: Apply the `Conflict Strategy` chosen in Phase 1 without blindly overwriting existing files.
+   - If `Smart Merge` is chosen but the target agent belongs to a different platform architecture, default to `Backup & Overwrite` to avoid cross-platform configuration conflicts.
+2. Semantic Integrity: For Smart Merge, align updates with logical consistency, memory management, and verification guardrails while preserving original YAML frontmatter.
+
+## [Action Phase: Generation]
+3. Run `node multi-agent-workspace/scripts/scaffold.js --workspace <root>` with the selected source, divisions, agents, and platform.
+   - Resolve document zones through the shared resolver; preserve the provenance of explicit, inferred, and fallback paths.
+   - Migrate authored decision, domain, and architecture records only after checking every destination conflict.
+   - Keep runtime metadata, roles, state, logs, and memory indexes under the global workspace-keyed state root.
+   - Resolve the router template and indexer from the installed skill directory; render the router into the global runtime, never into the repository.
+4. If the source is unavailable, retain the explicit unavailable-catalog status and do not claim a complete roster.
+
+## [Summarize & Verification Phase]
+5. Integrity Check: Verify the global manifest, handoff, launcher, selected roles, memory index, and resolved document paths before reporting completion.
+
+## [Record: Exit]
+6. Completion: Record successful subagent scaffolding.
+7. Handoff: Load and execute `workflows/04-launcher.md`, passing the `Context Profile`, `Selected Agents`, and newly created file paths.

package/multi-agent-workspace/workflows/04-launcher.md

@@ -0,0 +1,16 @@
+# Phase 4: Launcher Bootstrapping
+
+**[State Checkpoint]**
+- Verify inheritance of `Target Directory`, `Context Profile`, `Selected Agents`, and newly created file paths from Phase 3.
+
+## [Action Phase: Entry Point Generation]
+1. Entry Point Generation: Read the installed multi-agent-workspace skill and the runtime `manifest.json`/`handoff.json`.
+2. Handoff Integration: Use the resolved decision, domain, and architecture paths plus the selected roles from the manifest when dispatching bounded briefs.
+3. Disk Write: Update the global runtime launcher and resolved router generated by `scaffold.js`; repository-local router and executable copies are not created.
+
+## [Summarize: Verification]
+4. Check: Verify the runtime launcher, handoff schema, memory index, and selected-role metadata are readable from the global runtime root.
+
+## [Record: Exit]
+5. Completion: Present a clean summary table listing generated agent files and their configured roles.
+6. UX Handoff: Provide the user with guidance on how to trigger or invoke their new agent scaffold.

package/opencode-plugin/README.md

@@ -0,0 +1,137 @@
+# Harness Enforcement Plugin for opencode
+
+Adds hard enforcement gates for Harness skills in opencode, addressing the
+limitation that skills are otherwise advisory-only on that platform.
+
+> **Evidence boundary:** the plugin is implemented against opencode's real plugin API and covered by deterministic mechanism tests. **Live opencode plugin loading remains unverified** until a real host session artifact proves the host loaded and fired these hooks. See [`../docs/platform-capabilities.md`](../docs/platform-capabilities.md).
+
+## Problem
+
+In Claude Code, Harness hooks ENFORCE rules (hard gate). In opencode, skills
+only SUGGEST rules (soft guidance). This means:
+- Under pressure, agents can bypass skills
+- Verification can be skipped
+- Circuit breaker patterns don't trigger
+
+## The plugin
+
+**File:** `index.mjs` - a single ESM module, because that is what opencode
+actually loads: a JS/TS file exporting a function that returns a hooks
+object (see https://opencode.ai/docs/plugins/). There is no manifest-to-script
+mechanism; an earlier version of this plugin assumed one (a `plugin.json`
+mapping event names to standalone scripts) and opencode never invoked it -
+see issue #37 for how that was found and fixed.
+
+It implements three enforcement mechanisms across opencode's real hooks:
+
+The module follows opencode's V1 plugin contract directly: the named
+`HarnessEnforcement` export is an async factory receiving the opencode context
+(`client`, `directory`, `project`, `worktree`, and `$`) and returning the hook
+map. Copying this one `.mjs` file into `.opencode/plugins/` is enough for
+opencode to discover and invoke it; `plugin.json` is only a repository
+inventory and is not an opencode runtime manifest. The hook callbacks use the
+V1 `(input, output)` shape, including
+`output.args` when the host supplies tool arguments only in the result object.
+
+### 1. Edit tracking (`tool.execute.after`)
+
+Fires after every `edit`, `write` or `apply_patch` tool call and marks
+verification as pending.
+
+### 2. Verification gate (`event`, on `session.idle`)
+
+opencode has no "before complete" hook to block the way Claude Code's Stop
+hook does. `session.idle` - fired when the agent's turn ends - is the closest
+analog, and it cannot be blocked (the hook has no return value that denies
+it). So when it fires with verification still pending, the plugin runs the
+available `npm test` / `npm run lint` / `npm run build` scripts right there,
+and on failure calls `client.session.prompt()` to push a synthetic follow-up
+message into the session - forcing the agent to keep working instead of
+actually stopping.
+
+### 3. Circuit breaker (`tool.execute.before` + the verification gate above)
+
+Enforces Rule of 3 on repeated verification failures (same failing command +
+truncated error, not arbitrary tool failures - `tool.execute.after` has no
+normalized success/failure field to key a signature on for tools in general):
+- 3rd failure on the same signature forces a reflection message instead of a
+  retry nudge
+- the follow-up asks for a tokenized `zoom-out-report.md` artifact with the
+  required reflection sections; the artifact is accepted through the real
+  edit hook and records `lastReflection`
+- the same signature failing again after that reflection was recorded
+  hard-locks the breaker
+- once hard-locked, `tool.execute.before` throws on any `edit`/`write`/
+  `apply_patch` call, blocking further edits until the state file is cleared
+  or a new session starts
+
+Idle handling is bounded: after a failed verification, the plugin records that
+the follow-up is pending and ignores repeated `session.idle` events until a new
+code edit arrives. If prompt delivery fails, the exact follow-up text is saved
+and retried on the next idle event without re-running verification or adding a
+new breaker failure. A reflection artifact itself does not count as a code edit.
+
+## Installation
+
+Copy `index.mjs` into opencode's plugin directory - it is self-contained, no
+sibling files required:
+
+```bash
+cp opencode-plugin/index.mjs .opencode/plugins/harness-enforcement.mjs   # project-level
+# or
+cp opencode-plugin/index.mjs ~/.config/opencode/plugins/harness-enforcement.mjs  # global
+```
+
+opencode auto-loads any file dropped in those directories at startup - no
+`opencode.json` entry needed. (`opencode.json`'s `plugin` array is for npm
+package names, not local file paths.)
+
+## Manual verification CLI
+
+**File:** `hooks/verify.js` - the same "run available npm scripts" logic as
+`index.mjs`'s verification gate, kept as a standalone command:
+
+```bash
+node opencode-plugin/hooks/verify.js
+```
+
+Run it from the workspace under test, never from the Harness repo root - from
+there it would re-enter `npm test` from inside `npm test`. It is intentionally
+a separate copy of the logic, not a shared import, so `index.mjs` stays a
+single portable file for the installation step above.
+
+`plugin.json` records this standalone helper for repository parity checks; it
+does not configure opencode. The runtime module is `index.mjs`.
+
+## State and reset contract
+
+State is persisted per workspace and session under
+`~/.agents/harness-everything/workspaces/<workspace-key>/state/sessions/<session-id>/`.
+The plugin shares this layout with Harness's CJS hooks. A new session ID gets a
+new state stream, and `session.created` clears a reused session ID. A
+`session.deleted` event removes only that session's state. The old ambiguous
+`~/.harness-state/` files are migrated into the first workspace-keyed root that
+loads the plugin; conflicting or unsupported entries remain in place for
+recovery. Session IDs such as `.` or `..` are hashed
+into safe child names, and reset only removes a path proven to remain under the
+session root.
+
+The reflection report is `zoom-out-report.md` in the session state directory.
+It must contain `## Goal`, `## Failed Attempts`, `## Verified Facts`,
+`## Diagnosis`, `## Decision`, with the first non-empty line under `## Decision`
+starting with `RESUME:` or `ESCALATE:`, and the token supplied in the
+forced-reflection prompt. `apply_patch` reflection writes are accepted when
+their patch target names the report file.
+
+## Testing
+
+`ci/mechanism-2n-opencode-plugin.test.js` imports `index.mjs` and drives its
+exported hooks directly with a mock `client`/`event` context - the same shape
+opencode's plugin loader passes in - covering the edit → idle → follow-up →
+reflection-artifact → retry → hard-lock sequence, repeated-idle idempotency,
+session isolation, reset behavior, legacy-state migration, corrupt-state
+fail-closed behavior, and patch-based reflection writes.
+
+It does not launch a real opencode process; the test remains a deterministic
+hook-sequence check against the documented and source-verified hook signatures.
+A passing test is therefore mechanism evidence, not live-host loading evidence.

package/opencode-plugin/hooks/verify.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+/**
+ * Manual verification runner CLI.
+ *
+ * opencode itself never invokes this file - the real plugin (../index.mjs)
+ * runs its own inlined copy of this logic from the session.idle event, since
+ * opencode plugins must be a single loadable module (see issue #37). This
+ * script stays as a standalone command a human (or the message a hook prints)
+ * can run directly: `node opencode-plugin/hooks/verify.js`.
+ *
+ * Run it from the workspace under test, never from the Harness repo root -
+ * from there it would re-enter `npm test` from inside `npm test`.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execSync } = require('child_process');
+let getWorkspaceRoot;
+try {
+  ({ getWorkspaceRoot } = require('../../scripts/lib/workspace'));
+} catch (err) {
+  getWorkspaceRoot = () => null;
+}
+
+// Same convention as ../index.mjs's inlined copy (and the Node-side
+// scripts/lib/workspace.js#getStateHome) - a global root keyed per real
+// workspace, not the flat `~/.harness-state` every project used to share
+// (issue #42 item #4). Keyed off process.cwd() here since this CLI is meant
+// to be run "from the workspace under test" (see header comment above).
+function getStateDir() {
+  const home = process.env.HARNESS_STATE_HOME || path.join(os.homedir(), '.agents', 'harness-everything');
+  const root = getWorkspaceRoot();
+  if (!root) return path.join(home, 'workspaces', 'unbound-workspace');
+  let real = path.resolve(root);
+  try { real = fs.realpathSync(real); } catch (e) { /* cwd always exists in practice */ }
+  const slug = path.basename(real).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'workspace';
+  const hashInput = process.platform === 'win32' ? real.toLowerCase() : real;
+  const hash = crypto.createHash('sha1').update(hashInput).digest('hex').slice(0, 12);
+  return path.join(home, 'workspaces', `${slug}-${hash}`);
+}
+
+const STATE_DIR = getStateDir();
+const STATE_FILE = path.join(STATE_DIR, 'edit-state.json');
+
+// Ensure state directory exists, migrating the pre-fix flat ~/.harness-state
+// files even when a new workspace directory was already created by another
+// hook in this process.
+function migrateLegacyFlatState(stateDir) {
+  const legacyDir = path.join(os.homedir(), '.harness-state');
+  if (!fs.existsSync(legacyDir)) return;
+  try {
+    fs.mkdirSync(stateDir, { recursive: true });
+    let conflict = false;
+    for (const entry of fs.readdirSync(legacyDir, { withFileTypes: true })) {
+      if (!entry.isFile()) {
+        conflict = true;
+        continue;
+      }
+      const src = path.join(legacyDir, entry.name);
+      const destination = path.join(stateDir, entry.name);
+      if (!fs.existsSync(destination)) fs.copyFileSync(src, destination);
+      else if (!fs.readFileSync(src).equals(fs.readFileSync(destination))) conflict = true;
+    }
+    if (!conflict) fs.rmSync(legacyDir, { recursive: true, force: true });
+  } catch (e) {
+    // Best-effort - a failed or conflicting source remains available.
+  }
+}
+
+fs.mkdirSync(STATE_DIR, { recursive: true });
+migrateLegacyFlatState(STATE_DIR);
+
+function loadState() {
+  try {
+    if (fs.existsSync(STATE_FILE)) {
+      return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+    }
+  } catch (e) {
+    // Ignore parse errors
+  }
+  return {
+    lastEditTime: null,
+    verificationPending: false,
+    editsSinceVerification: 0,
+    sessionStart: Date.now()
+  };
+}
+
+function saveState(state) {
+  fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
+}
+
+function getAvailableScripts() {
+  const pkgPath = path.join(process.cwd(), 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return [];
+  }
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.scripts || {};
+  } catch {
+    return [];
+  }
+}
+
+function runVerification(command) {
+  try {
+    execSync(command, { 
+      stdio: 'pipe',
+      timeout: 60000 // 60 second timeout
+    });
+    return { success: true, command };
+  } catch (e) {
+    return { 
+      success: false, 
+      command,
+      error: e.message.slice(0, 200)
+    };
+  }
+}
+
+function main() {
+  const state = loadState();
+  
+  // Get available scripts from package.json
+  const scripts = getAvailableScripts();
+  
+  // Verification commands to try (only if script exists)
+  const possibleCommands = [
+    { cmd: 'npm test', script: 'test' },
+    { cmd: 'npm run lint', script: 'lint' },
+    { cmd: 'npm run build', script: 'build' }
+  ];
+  
+  const commands = possibleCommands
+    .filter(c => scripts[c.script])
+    .map(c => c.cmd);
+  
+  // If no verification scripts available, check if we should skip
+  if (commands.length === 0) {
+    // No npm verification available - check if this is a non-code task
+    // Allow completion without npm verification for doc-only tasks
+    console.log(JSON.stringify({
+      hook: 'verification-runner',
+      action: 'verify',
+      allPassed: true,
+      results: [],
+      message: 'No npm verification scripts available. Skipping npm verification (non-code task assumed).',
+      skipped: true
+    }));
+    return;
+  }
+  
+  const results = [];
+  let allPassed = true;
+  
+  for (const cmd of commands) {
+    const result = runVerification(cmd);
+    results.push(result);
+    if (!result.success) {
+      allPassed = false;
+    }
+  }
+  
+  // Update state
+  state.verificationPending = !allPassed;
+  state.editsSinceVerification = allPassed ? 0 : state.editsSinceVerification;
+  state.lastVerificationTime = Date.now();
+  state.verificationResults = results;
+  
+  saveState(state);
+  
+  // Output results
+  console.log(JSON.stringify({
+    hook: 'verification-runner',
+    action: 'verify',
+    allPassed,
+    results: results.map(r => ({
+      command: r.command,
+      success: r.success
+    })),
+    message: allPassed 
+      ? 'All available verification passed. You can now complete.'
+      : 'Some verification failed. Fix issues before completing.'
+  }));
+}
+
+main();