harness-everything 0.2.0

package/hooks/scripts/lib/platforms/copilot.js

@@ -0,0 +1,41 @@
+const path = require('path');
+const fs = require('fs');
+
+// Copilot's own skills location (.github/skills/) is unchanged - it already
+// has an established home. Only bookkeeping that never had a home (runtime
+// state, install manifest) converges into .github/harness-everything/.
+module.exports = {
+  name: 'copilot',
+  label: 'GitHub Copilot',
+  getHarnessDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.github', 'harness-everything');
+  },
+  getStateDir(workspaceRoot) {
+    return path.join(this.getHarnessDir(workspaceRoot), 'state');
+  },
+  getSkillsDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.github', 'skills');
+  },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = ['.github/harness-everything/'];
+    if (fs.existsSync(path.join(workspaceRoot, '.github', 'skills'))) {
+      patterns.push('.github/skills/');
+    }
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (pattern === '.github/harness-everything/') {
+      return trimmedLine === '.github/' ||
+             trimmedLine === '.github' ||
+             trimmedLine === '.github/harness-everything' ||
+             trimmedLine === '.github/harness-everything/';
+    }
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) {
+      return false; // Handled via global userPromptsDir check
+    }
+    return fs.existsSync(path.join(workspaceRoot, '.github', 'copilot-instructions.md'));
+  }
+};

package/hooks/scripts/lib/platforms/cursor.js

@@ -0,0 +1,41 @@
+const path = require('path');
+const fs = require('fs');
+
+// Cursor's own skills location (.cursor/skills/) is unchanged - it already
+// has an established home. Only bookkeeping that never had a home (runtime
+// state, install manifest) converges into .cursor/harness-everything/.
+module.exports = {
+  name: 'cursor',
+  label: 'Cursor',
+  getHarnessDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.cursor', 'harness-everything');
+  },
+  getStateDir(workspaceRoot) {
+    return path.join(this.getHarnessDir(workspaceRoot), 'state');
+  },
+  getSkillsDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.cursor', 'skills');
+  },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = ['.cursor/harness-everything/'];
+    if (fs.existsSync(path.join(workspaceRoot, '.cursor', 'skills'))) {
+      patterns.push('.cursor/skills/');
+    }
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (pattern === '.cursor/harness-everything/') {
+      return trimmedLine === '.cursor/' ||
+             trimmedLine === '.cursor' ||
+             trimmedLine === '.cursor/harness-everything' ||
+             trimmedLine === '.cursor/harness-everything/';
+    }
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) {
+      return fs.existsSync(path.join(userHome, '.cursorrules'));
+    }
+    return fs.existsSync(path.join(workspaceRoot, '.cursorrules'));
+  }
+};

package/hooks/scripts/lib/platforms/hermes.js

@@ -0,0 +1,32 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  name: 'hermes',
+  label: 'Hermes Agent',
+  getStateDir(workspaceRoot) {
+    return path.join(workspaceRoot, '.hermes', 'harness-state');
+  },
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = [];
+    if (fs.existsSync(path.join(workspaceRoot, '.hermes', 'harness-state'))) {
+      patterns.push('.hermes/harness-state/');
+    }
+    return patterns;
+  },
+  isMatch(pattern, trimmedLine) {
+    if (pattern === '.hermes/harness-state/') {
+      return trimmedLine === '.hermes/' || 
+             trimmedLine === '.hermes' || 
+             trimmedLine === '.hermes/harness-state' ||
+             trimmedLine === '.hermes/harness-state/';
+    }
+    return trimmedLine === pattern || trimmedLine === pattern.slice(0, -1);
+  },
+  isInstalled(workspaceRoot, userHome, isGlobal) {
+    if (isGlobal) {
+      return false;
+    }
+    return fs.existsSync(path.join(workspaceRoot, '.hermes.md'));
+  }
+};

package/hooks/scripts/lib/platforms/index.js

@@ -0,0 +1,17 @@
+const claude = require('./claude');
+const cursor = require('./cursor');
+const copilot = require('./copilot');
+const codex = require('./codex');
+const _continue = require('./continue');
+const hermes = require('./hermes');
+const worktrees = require('./worktrees');
+
+module.exports = [
+  claude,
+  cursor,
+  copilot,
+  codex,
+  _continue,
+  hermes,
+  worktrees
+];

package/hooks/scripts/lib/platforms/worktrees.js

@@ -0,0 +1,20 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = {
+  name: 'worktrees',
+  label: 'Git Worktrees',
+  getIgnorePatterns(workspaceRoot) {
+    const patterns = [];
+    if (fs.existsSync(path.join(workspaceRoot, '.worktrees'))) {
+      patterns.push('.worktrees/');
+    }
+    if (fs.existsSync(path.join(workspaceRoot, 'worktrees'))) {
+      patterns.push('worktrees/');
+    }
+    return patterns;
+  },
+  isInstalled() {
+    return false; // Not a standalone platform hook/settings installer
+  }
+};

package/hooks/scripts/reset-circuit-breaker.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// Manual escape hatch for the Rule of 3 circuit breaker. Run this directly
+// in your own terminal (not through the agent — Bash is blocked while the
+// breaker is tripped) to clear it without waiting for a new session.
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, readCurrentSession } = require('./lib/harness-state');
+
+// This is run directly by the human, not through the agent, so there's no
+// hook payload to read a session_id from - resolve "the session that's
+// currently blocked" via the pointer bootstrap.js wrote at its last
+// SessionStart.
+const root = getWorkspaceRoot();
+const harnessDir = getSessionDir(root, readCurrentSession(root));
+const stateFile = path.join(harnessDir, 'rule-of-3-state.json');
+const reportFile = path.join(harnessDir, 'zoom-out-report.md');
+
+if (fs.existsSync(stateFile)) {
+  fs.unlinkSync(stateFile);
+  console.log('Rule of 3 circuit breaker cleared.');
+} else {
+  console.log('Rule of 3 circuit breaker is not currently tripped.');
+}
+
+// A human reset is a full clear: the stale reflection report belongs to the
+// loop that was just abandoned.
+if (fs.existsSync(reportFile)) {
+  fs.unlinkSync(reportFile);
+  console.log('Stale zoom-out report removed.');
+}

package/hooks/scripts/rule-of-3-tracker.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+// PostToolUse hooks in Claude Code typically receive the tool output via stdin
+let inputData = '';
+
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    // Claude Code's documented PostToolUse payload nests tool output under
+    // tool_response rather than at the top level, and does not guarantee a
+    // numeric exit code field. Treating a missing/unknown exit code as a
+    // failure (the old `exitCode !== 0` check) flags every successful call
+    // as an error. Only count a call as a failure when we have positive
+    // evidence of one.
+    const toolResponse = payload.tool_response || {};
+    const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+    const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+    const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
+    const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+
+    const explicitFailure = exitCode !== undefined && exitCode !== 0;
+    const explicitSuccess = exitCode === 0;
+    const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+    // Without an exit code, bare stderr is not enough evidence: plenty of
+    // tools chat on stderr while succeeding (git, npm warnings, progress
+    // bars), and three identical warnings must not trip the breaker. Require
+    // the text to actually look like a failure.
+    const looksLikeError = /\b(error|fail|failed|failure|exception|fatal|panic|traceback|denied|refused|cannot|unable)\b/i.test(stderr);
+    const isFailure = explicitFailure || (exitCode === undefined && stderrSignal && looksLikeError);
+    const errorText = (stderrSignal ? stderr : stdout) || '';
+
+    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), payload.session_id), 'rule-of-3-state.json');
+
+    let state = { count: 0, lastHash: null, zoomOutResolved: false, zoomOutCycles: 0, lastFailureAt: 0 };
+    if (fs.existsSync(stateFile)) {
+      state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    }
+
+    if (isFailure && errorText) {
+      // Hash the tail of the error to identify identical loops. Normalize
+      // first: timestamps, line numbers, addresses and counters vary between
+      // otherwise-identical failures, and an ever-changing hash would hide a
+      // genuine loop from the breaker.
+      const normalized = errorText.slice(-400)
+        .toLowerCase()
+        .replace(/0x[0-9a-f]+/g, '#')
+        .replace(/\d+/g, '#')
+        .replace(/\s+/g, ' ')
+        .trim();
+      const hash = crypto.createHash('md5').update(normalized.slice(-200)).digest('hex');
+
+      if (state.lastHash === hash) {
+        state.count += 1;
+      } else {
+        state.count = 1;
+        state.lastHash = hash;
+        // New signature = new problem: the zoom-out cycle budget starts over.
+        state.zoomOutCycles = 0;
+      }
+      // Any fresh failure re-arms the breaker. Without this, a signature that
+      // failed again after a success (or after a zoom-out release) would keep
+      // zoomOutResolved=true and the breaker could never trip on it again.
+      state.zoomOutResolved = false;
+      // rule-of-3.js only honors a zoom-out report written AFTER this moment,
+      // so a stale report can't unlock a later trip.
+      state.lastFailureAt = Date.now();
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    } else if (explicitSuccess) {
+      // Only reset on a *confirmed* zero exit code, not merely "not a failure".
+      if (state.count > 0 || state.zoomOutCycles > 0) {
+        state.count = 0;
+        state.zoomOutResolved = true;
+        state.zoomOutCycles = 0;
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+    
+  } catch (err) {
+    // silently fail
+  }
+  process.exit(0);
+});

package/hooks/scripts/rule-of-3.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// Rule of 3 circuit breaker (PreToolUse: Bash|PowerShell|Edit|Write).
+//
+// Tripping the breaker forces REFLECTION, not surrender. The most common
+// agent failure mode is drilling deeper on one unverified assumption, so the
+// breaker locks mutating tools and demands a zoom-out fact-check first
+// (read-only tools stay available). A valid reflection report - written to
+// the session's zoom-out-report.md (path given in the block message below) -
+// releases the breaker again. Only a SECOND trip on the same failure
+// signature - proof that reflection alone couldn't crack it - hard-locks the
+// session until the Human Partner decides.
+//
+// State is scoped per Claude Code session_id (see lib/harness-state.js) so
+// two sessions open on the same repo never share a trip count. The common
+// case - nobody's breaker tripped anywhere - never has to read stdin to find
+// that out; only once some session IS tripped do we pay to read the payload
+// and check whether it's this one.
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir, listSessionDirs } = require('./lib/harness-state');
+
+const REQUIRED_SECTIONS = [
+  '## Goal',
+  '## Failed Attempts',
+  '## Verified Facts',
+  '## Diagnosis',
+  '## Decision'
+];
+
+function readState(stateFile) {
+  if (!fs.existsSync(stateFile)) return null;
+  try { return JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (err) { return null; }
+}
+
+function isTripped(state) {
+  return !!state && state.count >= 3 && !state.zoomOutResolved;
+}
+
+function anySessionTripped(root) {
+  return listSessionDirs(root).some(dir => isTripped(readState(path.join(dir, 'rule-of-3-state.json'))));
+}
+
+// The one mutation allowed while tripped: writing the reflection report.
+function isReportWrite(payload, reportFile) {
+  if (!payload) return false;
+  if (payload.tool_name !== 'Write' && payload.tool_name !== 'Edit') return false;
+  const target = payload.tool_input && payload.tool_input.file_path;
+  if (!target) return false;
+  return path.resolve(target).toLowerCase() === path.resolve(reportFile).toLowerCase();
+}
+
+// A report only counts if it was written AFTER the failure that tripped the
+// breaker (a stale report from an earlier loop can't unlock a new one), has
+// every required section, and actually committed to a RESUME/ESCALATE call.
+function reportIsValid(state, reportFile) {
+  if (!fs.existsSync(reportFile)) return false;
+  if (fs.statSync(reportFile).mtimeMs < (state.lastFailureAt || 0)) return false;
+  const text = fs.readFileSync(reportFile, 'utf8');
+  if (!REQUIRED_SECTIONS.every(h => text.includes(h))) return false;
+  return /\b(RESUME|ESCALATE)\b/.test(text);
+}
+
+function blockForReflection(state, reportFile) {
+  console.error(`[CRITICAL] RULE OF 3 CIRCUIT BREAKER TRIGGERED!`);
+  console.error(`The same failure signature has now occurred 3 times.`);
+  console.error(`Error Signature: ${state.lastHash}`);
+  console.error(`\nMutating tools (Bash/PowerShell/Edit/Write) are locked - not because you`);
+  console.error(`must wait for a human, but because you must stop drilling and rebuild the`);
+  console.error(`full picture first. Do NOT ask the Human Partner yet.`);
+  console.error(`\nACTION REQUIRED (reflect first):`);
+  console.error(`1. CEASE FIRE. No new fix attempts, no variations of the last one.`);
+  console.error(`2. Load the 'zoom-out' skill and follow its Reflect & Fact-Check protocol.`);
+  console.error(`3. Using READ-ONLY tools (Read/Grep/Glob - still available), re-verify the`);
+  console.error(`   assumption behind each failed attempt against the actual code/logs/docs.`);
+  console.error(`4. Write your findings to '${reportFile}' (the ONLY write`);
+  console.error(`   allowed right now) with sections: ## Goal, ## Failed Attempts,`);
+  console.error(`   ## Verified Facts, ## Diagnosis, ## Decision (ending RESUME: or ESCALATE:).`);
+  console.error(`\nA valid report releases this breaker automatically. Escalate to the Human`);
+  console.error(`Partner ONLY if your Decision concludes a genuinely human call is needed`);
+  console.error(`(requirement conflict, architecture trade-off, destructive action, missing`);
+  console.error(`access) - and then present options with a recommendation, not apologies.`);
+  // For PreToolUse, only exit code 2 actually blocks the tool call.
+  // Exit 1 is a non-blocking error and Claude Code proceeds anyway.
+  process.exit(2);
+}
+
+function blockForHumanDecision(state) {
+  console.error(`[CRITICAL] RULE OF 3 CIRCUIT BREAKER TRIGGERED! (repeat trip - hard lock)`);
+  console.error(`Error Signature: ${state.lastHash}`);
+  console.error(`\nYou already completed a zoom-out reflection for this same failure signature`);
+  console.error(`and the fresh diagnosis failed too. This is now past reflect-and-retry:`);
+  console.error(`STOP and hand the decision to your Human Partner.`);
+  console.error(`\nPresent a DECISION REQUEST, not a plea: the goal, the verified facts, every`);
+  console.error(`path already falsified (including the post-reflection diagnosis), 2-3`);
+  console.error(`concrete options with trade-offs, and your recommendation.`);
+  console.error(`\nThis lock persists until the Human Partner clears it by running`);
+  console.error(`"npm run harness:reset" in their own terminal, or by starting a new`);
+  console.error(`session / running /clear (which resets it automatically on SessionStart).`);
+  process.exit(2);
+}
+
+function main(payload) {
+  try {
+    const root = getWorkspaceRoot();
+    const sessionDir = getSessionDir(root, payload && payload.session_id);
+    const stateFile = path.join(sessionDir, 'rule-of-3-state.json');
+    const reportFile = path.join(sessionDir, 'zoom-out-report.md');
+
+    const state = readState(stateFile);
+    if (!isTripped(state)) {
+      process.exit(0);
+    }
+
+    if (isReportWrite(payload, reportFile)) {
+      process.exit(0);
+    }
+
+    if (reportIsValid(state, reportFile)) {
+      state.count = 0;
+      state.zoomOutResolved = true;
+      state.zoomOutCycles = (state.zoomOutCycles || 0) + 1;
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      console.log(
+        `[Rule of 3] Zoom-out report accepted - breaker released. Follow your ` +
+        `report's Decision: RESUME means one fresh run at the NEW diagnosis; ` +
+        `ESCALATE means present the decision request and WAIT for the Human ` +
+        `Partner before mutating anything. If this same signature trips the ` +
+        `breaker again, it hard-locks for a human decision.`
+      );
+      process.exit(0);
+    }
+
+    if ((state.zoomOutCycles || 0) >= 1) {
+      blockForHumanDecision(state);
+    }
+    blockForReflection(state, reportFile);
+  } catch (err) {
+    // Fail open if state tracking breaks
+    process.exit(0);
+  }
+}
+
+// Fast path: skip stdin entirely unless some session's breaker is actually
+// tripped (also keeps manual terminal runs instant).
+let tripped = false;
+try {
+  tripped = anySessionTripped(getWorkspaceRoot());
+} catch (err) {
+  tripped = false; // fail open
+}
+
+if (!tripped) {
+  process.exit(0);
+}
+
+if (process.stdin.isTTY) {
+  // Manual run in a terminal - no payload is coming.
+  main(null);
+} else {
+  let raw = '';
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    let payload = null;
+    try { payload = JSON.parse(raw); } catch (err) { /* no payload */ }
+    main(payload);
+  };
+  // Claude Code closes stdin right after writing the payload; the timer is a
+  // safety net so an odd caller that never closes stdin can't hang the hook.
+  const timer = setTimeout(finish, 300);
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => { clearTimeout(timer); finish(); });
+  process.stdin.on('error', () => { clearTimeout(timer); finish(); });
+}

package/hooks/scripts/state-persist.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+// Commands that count as "verification ran" for the Stop gate
+// (hooks/scripts/stop-gate.js). Recall over precision: under-blocking the
+// gate is the correct failure direction, so a broad net is fine.
+const VERIFY_COMMAND_RE = /\b(test|spec|jest|vitest|mocha|pytest|rspec|phpunit|tsc|eslint|lint|build|compile|verify|check)\b/i;
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  processState(null);
+}, 200);
+
+process.stdin.on('data', chunk => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  try {
+    const payload = JSON.parse(inputData.trim());
+    processState(payload);
+  } catch (err) {
+    processState(null);
+  }
+});
+
+function processState(payload) {
+  try {
+    const sessionId = payload && payload.session_id;
+    const stateFile = path.join(getSessionDir(getWorkspaceRoot(), sessionId), 'handoff-state.json');
+
+    // Merge into the existing state rather than replacing it, so the
+    // failure/idle status and the Stop-gate milestones can coexist.
+    let state = { status: 'idle', timestamp: new Date().toISOString() };
+    if (fs.existsSync(stateFile)) {
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (e) { /* keep default */ }
+    }
+
+    if (payload) {
+      // Claude Code nests tool output under tool_response, not at the top
+      // level, and uses tool_name rather than tool. A numeric exit code
+      // also isn't guaranteed to be present at all - only trust it when
+      // it's actually a number; fall back to a stderr signal otherwise.
+      const toolResponse = payload.tool_response || {};
+      const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+      const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+      const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? payload.exitCode;
+      const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+      const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+      const isFailed = (exitCode !== undefined && exitCode !== 0) || (exitCode === undefined && stderrSignal);
+      const toolName = payload.tool_name || payload.tool || 'command';
+
+      if (isFailed) {
+        // Truncate output to avoid state bloat
+        let output = (stderrSignal ? stderr : stdout) || payload.output || '';
+        if (output.length > 500) {
+          output = '...' + output.slice(-500);
+        }
+
+        state.status = 'failed';
+        state.timestamp = new Date().toISOString();
+        state.tool = toolName;
+        state.exitCode = exitCode;
+        state.errorSummary = output.trim();
+      } else if (exitCode === 0 && state.status === 'failed') {
+        // Clear failed state or mark as idle/resolved
+        state.lastResolved = { tool: state.tool, timestamp: state.timestamp };
+        state.status = 'idle';
+        state.timestamp = new Date().toISOString();
+        delete state.exitCode;
+        delete state.errorSummary;
+      }
+
+      // Milestones for the Stop gate: when did the last mutation happen, and
+      // has any verification-ish command succeeded since.
+      if (toolName === 'Edit' || toolName === 'Write') {
+        state.lastEditAt = Date.now();
+      } else if ((toolName === 'Bash' || toolName === 'PowerShell') && !isFailed) {
+        const command = (payload.tool_input && payload.tool_input.command) || '';
+        if (VERIFY_COMMAND_RE.test(command)) {
+          state.lastVerifyAt = Date.now();
+        }
+      }
+
+      fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+    } else {
+      // No standard input payload, or invalid JSON. Just maintain a heartbeat timestamp
+      if (!fs.existsSync(stateFile)) {
+        fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+      }
+    }
+  } catch (err) {
+    // Fail silently in hooks
+  }
+  process.exit(0);
+}

package/hooks/scripts/stop-gate.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Stop Gate (Stop hook - Claude Code only)
+ * The pre-delivery gate (verification-loop) was prose-only, and prose decays
+ * as context grows. This makes the one check that matters mechanical: ending
+ * the turn with edits that were never followed by a successful
+ * verification-ish command (test/build/lint - tracked by state-persist.js)
+ * while uncommitted changes sit in the tree gets bounced back ONCE per edit
+ * batch. Objective facts only; fails open on any error.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function decide(payload) {
+  try {
+    // Loop guard: if this stop already resulted from a Stop-hook block,
+    // always let it through - one bounce is the contract, never a cage.
+    if (payload && payload.stop_hook_active) {
+      process.exit(0);
+    }
+
+    const root = getWorkspaceRoot();
+    const sessionDir = getSessionDir(root, payload && payload.session_id);
+    const handoffFile = path.join(sessionDir, 'handoff-state.json');
+    const gateFile = path.join(sessionDir, 'stop-gate-state.json');
+
+    if (!fs.existsSync(handoffFile)) process.exit(0);
+    const handoff = JSON.parse(fs.readFileSync(handoffFile, 'utf8'));
+    const lastEditAt = handoff.lastEditAt || 0;
+    const lastVerifyAt = handoff.lastVerifyAt || 0;
+
+    // No edits this session, or verification already ran after the last edit.
+    if (!lastEditAt || lastVerifyAt >= lastEditAt) process.exit(0);
+
+    // One bounce per edit batch: if we already blocked for this exact edit
+    // timestamp, the model either verified (which moves lastVerifyAt) or
+    // explicitly chose not to - don't nag twice for the same batch.
+    let gate = {};
+    if (fs.existsSync(gateFile)) {
+      try { gate = JSON.parse(fs.readFileSync(gateFile, 'utf8')); } catch (e) { /* ignore */ }
+    }
+    if (gate.blockedForEditAt === lastEditAt) process.exit(0);
+
+    // Only relevant when unverified work is actually sitting in the tree.
+    const dirty = execSync('git status --porcelain', {
+      cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    if (!dirty) process.exit(0);
+
+    fs.writeFileSync(gateFile, JSON.stringify({ blockedForEditAt: lastEditAt }, null, 2), 'utf8');
+
+    console.error(`[Stop Gate] Turn is ending with uncommitted edits and no successful verification command (test/build/lint) since the last edit.`);
+    console.error(`Before delivering: run the relevant check from 'verification-loop' - even a single targeted test beats none.`);
+    console.error(`If verification is genuinely not applicable (docs-only change, analysis-only turn, the Human Partner told you to stop), state that explicitly in your reply and stop again.`);
+    console.error(`This gate bounces at most once per edit batch.`);
+    process.exit(2);
+  } catch (err) {
+    // Fail open - a broken gate must never trap the session.
+    process.exit(0);
+  }
+}
+
+let inputData = '';
+const timeout = setTimeout(() => {
+  decide(null);
+}, 200);
+
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  decide(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  decide(null);
+});