harness-everything 0.3.6 → 0.4.1

package/opencode-plugin/README.md

@@ -1,94 +1,137 @@
 # Harness Enforcement Plugin for opencode
 
-This plugin adds hard enforcement gates for Harness skills in opencode, addressing the limitation that skills are advisory-only in this platform.
+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:
+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
 
-## Solution
-
-This plugin implements three enforcement mechanisms:
-
-### 1. Post-Edit Verification Gate
-
-**File:** `hooks/post-edit.js`
-
-Records every edit and tracks verification status.
-
-### 2. Pre-Complete Verification Gate
-
-**File:** `hooks/pre-complete.js`
-
-Blocks completion until verification runs after edits.
-
-### 3. Circuit Breaker
-
-**File:** `hooks/circuit-breaker.js`
-
-Enforces Rule of 3:
-- Tracks failure signatures
-- Blocks edits after 3 failures on same signature
-- Requires reflection (zoom-out) before resuming
-
-### 4. Compliance Monitor
-
-**File:** `hooks/compliance.js`
-
-Tracks compliance metrics:
-- Verification compliance rate
-- Circuit breaker trips
-- Pressure resistance metrics
+## 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
 
-1. Copy `opencode-plugin/` to your opencode config directory
-2. Add to `opencode.json`:
+Copy `index.mjs` into opencode's plugin directory - it is self-contained, no
+sibling files required:
 
-```json
-{
-  "plugins": ["./opencode-plugin"]
-}
+```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
 ```
 
-## Configuration
-
-Edit `plugin.json` to configure:
-
-```json
-{
-  "config": {
-    "verificationRequired": true,
-    "circuitBreakerEnabled": true,
-    "maxRetries": 3,
-    "verificationCommands": ["npm test", "npm run lint", "npm run build"]
-  }
-}
-```
+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.)
 
-## Expected Impact
+## Manual verification CLI
 
-| Metric | Before | After (Expected) |
-|--------|--------|------------------|
-| Pressure pass rate | 0% | 80%+ |
-| Verification compliance | Unknown | 95%+ |
-| Circuit breaker enforcement | Advisory only | Hard gate |
+**File:** `hooks/verify.js` - the same "run available npm scripts" logic as
+`index.mjs`'s verification gate, kept as a standalone command:
 
-## Limitations
+```bash
+node opencode-plugin/hooks/verify.js
+```
 
-1. **Requires opencode plugin support** - opencode must support post-edit hooks
-2. **State files in user home** - Uses `~/.harness-state/` for persistence
-3. **No cross-session state** - Each session starts fresh (by design)
+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
 
-Run the behavioral evals to verify:
-
-```bash
-node behavioral-evals/run.js run --engine opencode
-```
+`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.
 
-Expected improvement in pressure cases.
+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

@@ -1,27 +1,77 @@
 #!/usr/bin/env node
 /**
- * Verification Runner Hook
- * 
- * Runs verification commands and updates state.
- * This hook runs available verification commands (npm test, lint, build) and:
- * 1. Detects available scripts from package.json
- * 2. Executes only available verification commands
- * 3. Updates state to reflect verification status
- * 4. Logs verification results
+ * 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 = path.join(process.env.HOME || process.env.USERPROFILE, '.harness-state');
+const STATE_DIR = getStateDir();
 const STATE_FILE = path.join(STATE_DIR, 'edit-state.json');
 
-// Ensure state directory exists
-if (!fs.existsSync(STATE_DIR)) {
-  fs.mkdirSync(STATE_DIR, { recursive: true });
+// 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)) {