harness-everything 0.2.0

package/harness-everything/scripts/tier-router.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+
+function run(userPrompt) {
+  console.log(`[Tier Routing Pre-check]`);
+  
+  const promptLower = userPrompt.toLowerCase();
+
+  // Basic keyword heuristic (bilingual - the Human Partner often prompts in
+  // Chinese, and an English-only net silently degrades to Tier 1 for them).
+  // Deliberately NOT driven by the diff stats above: those measure what is
+  // already sitting uncommitted in the tree - usually the PREVIOUS task's
+  // leftovers - not the complexity of the task being asked for now.
+  const TIER3_KEYWORDS = ["architecture", "refactor", "rewrite the", "架構", "重構", "重寫"];
+  const TIER2_KEYWORDS = ["test", "api", "integration", "endpoint", "測試", "整合", "端點", "介面"];
+
+  let recommendedTier = "Tier 1 (Trivial)";
+  let rationale = "No structural/testing signals in the prompt.";
+
+  if (TIER3_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedTier = "Tier 3 (Macro Task)";
+    rationale = "Prompt implies system-wide or architectural change.";
+  } else if (TIER2_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedTier = "Tier 2 (Standard Task)";
+    rationale = "Prompt implies development work needing TDD validation or multi-file coordination.";
+  }
+
+  console.log(`\n=> RECOMMENDED TIER: ${recommendedTier}`);
+  console.log(`=> RATIONALE: ${rationale}`);
+
+  // Base execution loop: Tier 2/3 must run on the todo-driven-workflow
+  // checklist (Tier 1 is exempt to avoid checklist bloat on trivial edits).
+  if (!recommendedTier.startsWith("Tier 1")) {
+    console.log(`\n=> BASE EXECUTION LOOP: Load 'todo-driven-workflow' and initialize its checklist (3-7 verifiable sub-tasks) BEFORE editing any file.`);
+    console.log(`   Track exactly ONE item in-progress at a time; verify with real evidence before marking completed.`);
+  }
+
+  // Analyze and output relevant Knowledge Guides / Templates based on user prompt keywords
+  const recommendedGuides = [];
+
+  const TDD_TEST_KEYWORDS = [
+    "tdd", "test", "mock", "stub", "api", "endpoint", "integration", "debugging", "bug", "error", "fix",
+    "測試", "單測", "模組測試", "端點", "介面", "除錯", "錯誤", "修復"
+  ];
+  if (TDD_TEST_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- tdd/SKILL.md (Test-Driven Development Red-Green-Refactor loop)",
+      "- tdd/guides/mocking.md (Mocking principles & isolation)",
+      "- tdd/guides/interface-design.md (Interface and contract design)",
+      "- tdd/guides/deep-modules.md (Testing deep nested modules)",
+      "- tdd/guides/tests.md (General test architecture)",
+      "- environment-detection/SKILL.md (Detect active shell/OS & preflight syntax before running commands)",
+      "- verify-before-claim/SKILL.md (Fact-audit discipline: verify external claims and unmeasured estimates before asserting them)",
+      "- verification-loop/SKILL.md (Pre-PR verification gate: build, types, lint, tests, security scan)"
+    );
+  }
+
+  const GIT_COMMIT_KEYWORDS = [
+    "commit", "git", "save", "submodule", "pr", "pull request", "release", "quality gate", "ready to ship",
+    "提交", "版控", "合併", "分支", "發行"
+  ];
+  if (GIT_COMMIT_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- git-commit/SKILL.md (Angular-style commit convention generation)",
+      "- git-commit/guides/ANGULAR_STYLE.md (Commit conventions reference)",
+      "- git-commit/guides/COMMIT_GENERATION.md (Commit generation patterns)",
+      "- git-commit/guides/LANGUAGE_DETECTION.md (Multi-language commits)",
+      "- git-commit/guides/MAIN_REPO.md (Commits in main repositories)",
+      "- git-commit/guides/SUBMODULES.md (Submodule commit handling)",
+      "- rewrite-commits/SKILL.md (Rewrite commit history safely to Angular style)",
+      "- using-git-worktrees/SKILL.md (Git Worktrees isolation for feature work, avoids workspace pollution)",
+      "- verification-loop/SKILL.md (Pre-PR verification gate: build, types, lint, tests, security scan)"
+    );
+  }
+
+  if (promptLower.includes("doc") || promptLower.includes("readme") || promptLower.includes("文件") || promptLower.includes("說明文件")) {
+    recommendedGuides.push(
+      "- repo-docs/templates/readme-template.md (Standard README template)",
+      "- repo-docs/templates/product-readme-template.md (Product README template)",
+      "- repo-docs/templates/agents-template.md (Agent onboarding instructions template)"
+    );
+  }
+
+  const AGENT_KEYWORDS = [
+    "agent", "multi-agent", "launcher", "subagent", "sub-agent", "delegate", "orchestrate", "specialist", 
+    "workspace scaffolding", "scaffold workspace", "division of labor", "fable", "macro", "orchestrator",
+    "代理", "多代理", "啟動器", "子代理", "委派", "指派", "分工", "協調", "任務分配", "規劃"
+  ];
+  if (AGENT_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- fable-mode/SKILL.md (Macro task planning & execution orchestrator)",
+      "- fable-discipline/SKILL.md (Shadow guard preventing context bloat and managing token limits)",
+      "- build-multi-agent-system/SKILL.md (Universal Multi-Agent Workspace scaffolding & memory db)",
+      "- create-agent-launcher/SKILL.md (Sub-agent generator for specialized task delegation)",
+      "- repo-docs/templates/agents-template.md (Agent onboarding instructions template)",
+      "- grill-with-docs/SKILL.md (Decision tracking, Glossary & ADR-driven design grilling)"
+    );
+  }
+
+  const ARCH_REFACTOR_KEYWORDS = [
+    "refactor", "architecture", "structure", "couple", "seam", "adr", "design plan", "decision", "grill",
+    "重構", "架構", "結構", "解耦", "設計", "決策", "辯論", "質疑"
+  ];
+  if (ARCH_REFACTOR_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- improve-codebase-architecture/guides/DEEPENING.md (Deepening opportunities & depth rules)",
+      "- improve-codebase-architecture/guides/INTERFACE-DESIGN.md (Interface design principles)",
+      "- improve-codebase-architecture/guides/LANGUAGE.md (Language-specific patterns)",
+      "- improve-codebase-architecture/guides/HTML-REPORT.md (Mermaid dependency report generation)",
+      "- grill-with-docs/SKILL.md (Decision tracking, Glossary & ADR-driven design grilling)",
+      "- grill-me/SKILL.md (Challenger interview to stress-test your architecture plan)",
+      "- fable-mode/SKILL.md (Macro task planning & execution orchestrator)"
+    );
+  }
+
+  const ENV_KEYWORDS = [
+    "shell", "terminal", "powershell", "bash", "cmd", "env", "preflight", "command", "run",
+    "終端機", "命令", "環境", "指令", "執行"
+  ];
+  if (ENV_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- environment-detection/SKILL.md (Detect active shell/OS & preflight syntax before running commands)",
+      "- using-git-worktrees/SKILL.md (Git Worktrees isolation for feature work, avoids workspace pollution)"
+    );
+  }
+
+  const VERIFY_KEYWORDS = [
+    "verify", "fact", "audit", "estimate", "benchmark", "performance", "speed", "scale",
+    "驗證", "查證", "核對", "效能", "評測", "性能", "估計"
+  ];
+  if (VERIFY_KEYWORDS.some(k => promptLower.includes(k))) {
+    recommendedGuides.push(
+      "- verify-before-claim/SKILL.md (Fact-audit discipline: verify external claims and unmeasured estimates before asserting them)",
+      "- verification-loop/SKILL.md (Pre-PR verification gate: build, types, lint, tests, security scan)",
+      "- eval-harness/SKILL.md (AI performance evaluation metrics & anti-loop metrics)"
+    );
+  }
+
+  if (/\bskill\b|skill\.md|new skill|write a skill/.test(promptLower)) {
+    recommendedGuides.push(
+      "- skill-creator/SKILL.md (Authoring, auditing, and testing workflow for SKILL.md files, incl. dynamic skill generation)",
+      "- skill-style/SKILL.md (Terse Skill Contract format spec that skill-creator builds on)"
+    );
+  }
+
+  if (recommendedGuides.length > 0) {
+    console.log(`\n=> RECOMMENDED KNOWLEDGE GUIDES (Auto-loaded based on keywords):`);
+    recommendedGuides.forEach(guide => {
+      const match = guide.match(/^- ([^\s]+)/);
+      if (match) {
+        const guidePath = require('path').join(__dirname, '..', '..', match[1]);
+        if (!require('fs').existsSync(guidePath)) {
+          console.log(`${guide} [NOT INSTALLED - Ignore this recommendation]`);
+          return;
+        }
+      }
+      console.log(guide);
+    });
+  }
+
+  // Fact-audit nudge: broad, cheap keyword net for claims that risk being
+  // asserted from stale/wrong training memory instead of verified. False
+  // positives cost nothing here (it's a reminder, not a block) so recall
+  // matters more than precision.
+  const externalClaimTriggers = [
+    "does it support", "does support", "how does", "what's the default", "what is the default",
+    "exit code", "schema", "sdk", " api", "hook", "payload", "pricing", "rate limit",
+    "latest version", "current version", "deprecated", "breaking change", "changelog",
+    "spec", "documentation", "according to", "endpoint", "config option", "flag"
+  ];
+  const estimateTriggers = [
+    "benchmark", "performance", "how fast", "how long will", "how much memory",
+    "how many requests", "estimate", "roughly how", "big o", "complexity",
+    "will this scale", "throughput", "latency"
+  ];
+  const hitExternalClaim = externalClaimTriggers.some(kw => promptLower.includes(kw));
+  const hitEstimate = estimateTriggers.some(kw => promptLower.includes(kw));
+
+  if (hitExternalClaim || hitEstimate) {
+    console.log(`\n=> FACT-AUDIT REMINDER:`);
+    if (hitExternalClaim) {
+      console.log(`This looks like it may require a claim about an external framework/library/API/tool's current behavior.`);
+      console.log(`Verify via WebFetch/WebSearch against the authoritative source before asserting it - do not answer from training memory alone; it can be stale or confidently wrong (e.g. exit-code semantics, schema fields, defaults, pricing).`);
+    }
+    if (hitEstimate) {
+      console.log(`This looks like it may call for a performance/cost/timing number.`);
+      console.log(`Prefer an actual measurement over a reasoned estimate when the stakes justify it - an unmeasured number (including one you generate yourself) is a hypothesis, not a fact.`);
+    }
+  }
+
+  // Constraint strength must match judgment reliability: this routing is a
+  // keyword heuristic, so it is a default, not an order.
+  console.log(`\nTreat the tier above as the default route. If your own read of the task clearly disagrees, follow your read and say why in one line. An explicit instruction from the Human Partner always wins.`);
+}
+
+let userPrompt = process.argv[2] || '';
+
+if (process.argv[2]) {
+  // If a command-line argument is passed, use it and execute immediately.
+  run(userPrompt);
+} else if (process.stdin.isTTY) {
+  // Running interactively in a terminal without piped input, execute immediately.
+  run('');
+} else {
+  // Piped input or non-TTY, read from standard input.
+  let inputData = '';
+  process.stdin.on('data', chunk => { inputData += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      if (inputData.trim()) {
+        const payload = JSON.parse(inputData);
+        if (typeof payload.prompt === 'string') userPrompt = payload.prompt;
+      }
+    } catch (err) {
+      // Not valid JSON on stdin - fall back to argv (useful for direct/manual testing).
+    }
+    run(userPrompt);
+  });
+}

package/harness-everything/scripts/todo-cli.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * Harness Todo CLI
+ * A strict state machine for task management.
+ * Designed to slap the LLM with Exit Code 1 if it violates the Todo-Driven Workflow.
+ */
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getStateRoot } = require('../../hooks/scripts/lib/harness-state');
+
+// Shared across sessions (not scoped to one): todo-cli.js is invoked as a
+// plain CLI command by the agent, not a hook, so it never receives a
+// session_id to scope by.
+const harnessDir = getStateRoot(getWorkspaceRoot());
+const stateFile = path.join(harnessDir, 'todo-state.json');
+
+if (!fs.existsSync(harnessDir)) {
+  fs.mkdirSync(harnessDir, { recursive: true });
+}
+
+function loadState() {
+  if (fs.existsSync(stateFile)) {
+    return JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  }
+  return { tasks: [], activeId: null };
+}
+
+function saveState(state) {
+  // Atomic write (temp file + rename): todo-state.json is shared across the
+  // whole workspace, not scoped per session_id like the hook state files
+  // are, so parallel subagent Task bursts can genuinely call `todo-cli.js`
+  // around the same time. A plain writeFileSync lets a reader observe a
+  // truncated/partial JSON file if two writes interleave; rename is atomic
+  // at the filesystem level, so readers only ever see the old or the new
+  // file in full, never a half-written one. This doesn't resolve the
+  // separate lost-update race (last writer still wins) - that needs real
+  // cross-process locking, out of scope for what a CLI state file needs.
+  const tmpFile = `${stateFile}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2));
+  fs.renameSync(tmpFile, stateFile);
+}
+
+function printList(state) {
+  console.log('\n📋 Current Todo List:');
+  if (state.tasks.length === 0) {
+    console.log('  (Empty)');
+  }
+  state.tasks.forEach(t => {
+    const status = t.id === state.activeId ? '[IN-PROGRESS]' : (t.completed ? '[COMPLETED]' : '[NOT-STARTED]');
+    console.log(`  ${t.id}. ${status} ${t.title}`);
+  });
+  console.log('');
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command) {
+  console.error("❌ Error: Missing command. Use 'init', 'add', 'start', 'complete', or 'status'.");
+  process.exit(1);
+}
+
+const state = loadState();
+
+switch (command) {
+  case 'init':
+    state.tasks = [];
+    state.activeId = null;
+    args.slice(1).forEach((title, idx) => {
+      state.tasks.push({ id: idx + 1, title, completed: false });
+    });
+    saveState(state);
+    console.log("✅ Todo list initialized.");
+    printList(state);
+    break;
+
+  case 'add':
+    const title = args.slice(1).join(' ');
+    if (!title) {
+      console.error("❌ Error: Missing task title.");
+      process.exit(1);
+    }
+    const nextId = state.tasks.length > 0 ? Math.max(...state.tasks.map(t => t.id)) + 1 : 1;
+    state.tasks.push({ id: nextId, title, completed: false });
+    saveState(state);
+    console.log(`✅ Added task ${nextId}.`);
+    printList(state);
+    break;
+
+  case 'start':
+    const startId = parseInt(args[1], 10);
+    if (!startId) {
+      console.error("❌ Error: Missing task ID. Usage: start <id>");
+      process.exit(1);
+    }
+    if (state.activeId !== null && state.activeId !== startId) {
+      console.error(`❌ [BLOCKED] Task ${state.activeId} is already IN-PROGRESS.`);
+      console.error(`You MUST complete or un-start task ${state.activeId} before starting a new one. No multitasking.`);
+      process.exit(1);
+    }
+    const taskToStart = state.tasks.find(t => t.id === startId);
+    if (!taskToStart) {
+      console.error(`❌ Error: Task ${startId} not found.`);
+      process.exit(1);
+    }
+    if (taskToStart.completed) {
+      console.error(`❌ Error: Task ${startId} is already completed.`);
+      process.exit(1);
+    }
+    state.activeId = startId;
+    saveState(state);
+    console.log(`🚀 Started task ${startId}: ${taskToStart.title}`);
+    break;
+
+  case 'complete':
+    const compId = parseInt(args[1], 10);
+    if (!compId) {
+      console.error("❌ Error: Missing task ID. Usage: complete <id>");
+      process.exit(1);
+    }
+    if (state.activeId !== compId) {
+      console.error(`❌ [BLOCKED] Task ${compId} is NOT currently in-progress.`);
+      console.error(`You can only complete the active task. Active task is: ${state.activeId || 'None'}`);
+      process.exit(1);
+    }
+    
+    // ACTIONABLE RECOMMENDATION #1: Enforce State Transitions Programmatically
+    // Do not rely on prompt obedience for running verify-gate.js. The CLI should block the complete command
+    console.log("=== 🛡️ Executing Pre-Completion Verification Gate ===");
+    try {
+      const verifyScript = path.join(__dirname, 'verify-gate.js');
+      if (fs.existsSync(verifyScript)) {
+        require('child_process').execSync(`node "${verifyScript}"`, { stdio: 'inherit' });
+      }
+    } catch (err) {
+      console.error(`\n❌ [BLOCKED] Verification Gate Failed (Exit Code 1).`);
+      console.error(`You CANNOT complete this task. The code is broken.`);
+      console.error(`Please fix the errors shown above and try again.`);
+      process.exit(1);
+    }
+
+    const taskToComp = state.tasks.find(t => t.id === compId);
+    taskToComp.completed = true;
+    state.activeId = null;
+    saveState(state);
+    console.log(`✅ Completed task ${compId}: ${taskToComp.title}`);
+    printList(state);
+    break;
+
+  case 'status':
+    printList(state);
+    break;
+
+  default:
+    console.error(`❌ Error: Unknown command '${command}'.`);
+    process.exit(1);
+}

package/harness-everything/scripts/verify-gate.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Verification Gatekeeper
+ * Forces the AI to run this script to prove quality gates before declaring a task done.
+ */
+const { execSync } = require('child_process');
+
+console.log("=== 🛡️ Harness Verification Gate ===");
+
+try {
+  console.log("Running basic checks (simulated for now)...");
+  
+  // In a real project, this would run `npm run lint` and `npm test`
+  // We'll simulate a failure if `.verify-fail.tmp` exists just to prove the mechanism.
+  const fs = require('fs');
+  if (fs.existsSync('.verify-fail.tmp')) {
+    console.error("❌ Verification FAILED: Found broken tests or lint errors.");
+    console.error("Please fix the code and run this gate again.");
+    process.exit(1);
+  }
+  
+  console.log("✅ Lint passed.");
+  console.log("✅ Tests passed.");
+  console.log("✅ Verification SUCCESS. You may now complete the task.");
+  process.exit(0);
+
+} catch (err) {
+  console.error("❌ Verification FAILED.");
+  console.error(err.message);
+  process.exit(1);
+}

package/hooks/hooks.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node harness-everything/scripts/bootstrap.js"
+          }
+        ],
+        "description": "Bootstrap Harness Skills OS on session start",
+        "id": "harness:pre:bootstrap"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node harness-everything/scripts/tier-router.js"
+          }
+        ],
+        "description": "Auto-route user requests using tier-router",
+        "id": "harness:pre:tier-router"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|PowerShell|Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/rule-of-3.js"
+          }
+        ],
+        "description": "Rule of 3 Circuit Breaker - Prevents micro-error looping",
+        "id": "harness:pre:rule-of-3"
+      },
+      {
+        "matcher": "Grep|Glob|Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/boundary-guard.js"
+          }
+        ],
+        "description": "Physical boundary enforcement for searches and large file reads",
+        "id": "harness:pre:boundary-guard"
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/depth-guard.js"
+          }
+        ],
+        "description": "Information depth guard - Enforce impact assessment before writing code",
+        "id": "harness:pre:depth-guard"
+      },
+      {
+        "matcher": "Edit|Write|Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/context-compact.js"
+          }
+        ],
+        "description": "Strategic context compaction enforcement",
+        "id": "harness:pre:context-compact"
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/subagent-scope-guard.js"
+          }
+        ],
+        "description": "Snapshot repo state before a subagent burst starts",
+        "id": "harness:pre:subagent-scope-guard"
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/stop-gate.js"
+          }
+        ],
+        "description": "Pre-delivery gate - bounce the end of a turn once per edit batch when edits were never verified",
+        "id": "harness:stop:stop-gate"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/rule-of-3-tracker.js"
+          }
+        ],
+        "description": "Track error signatures for Rule of 3",
+        "id": "harness:post:rule-of-3-tracker"
+      },
+      {
+        "matcher": "Edit|Write|Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/state-persist.js"
+          }
+        ],
+        "description": "Save skill transition state",
+        "id": "harness:post:state-persist"
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/atomic-commit-check.js"
+          }
+        ],
+        "description": "Atomic commit enforcement",
+        "id": "harness:post:atomic-commit-check"
+      },
+      {
+        "matcher": "Bash|PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/contract-test.js"
+          }
+        ],
+        "description": "Contract testing between sub-agents",
+        "id": "harness:post:contract-test"
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node hooks/scripts/subagent-scope-guard.js"
+          }
+        ],
+        "description": "Diff the whole repo after a subagent burst finishes - catches scope creep past what the task briefed",
+        "id": "harness:post:subagent-scope-guard"
+      }
+    ]
+  }
+}

package/hooks/scripts/atomic-commit-check.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * Atomic Commit Check (PostToolUse: Edit|Write)
+ * PostToolUse can't block - the edit/write already happened. So this counts
+ * Edit/Write calls since the last commit and, once the count crosses a
+ * threshold, feeds a strong reminder back to Claude (exit 2) to commit the
+ * completed chunk before piling on more changes. Resets whenever HEAD moves.
+ * Fails open on any error - this is a nudge, never a hard stop.
+ */
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+const THRESHOLD = 6;
+const RENUDGE_EVERY = 3;
+
+function main(payload) {
+  try {
+    const root = getWorkspaceRoot();
+    const head = execSync('git rev-parse HEAD', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+
+    const stateFile = path.join(getSessionDir(root, payload && payload.session_id), 'atomic-commit-state.json');
+
+    let state = { lastHead: head, editCount: 0 };
+    if (fs.existsSync(stateFile)) {
+      try { state = JSON.parse(fs.readFileSync(stateFile, 'utf8')); } catch (e) { /* use default */ }
+    }
+
+    if (state.lastHead !== head) {
+      // A commit happened since we last checked - fresh start.
+      state.lastHead = head;
+      state.editCount = 0;
+    }
+
+    state.editCount += 1;
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2), 'utf8');
+
+    const overThreshold = state.editCount >= THRESHOLD;
+    const onNudgeBeat = overThreshold && (state.editCount - THRESHOLD) % RENUDGE_EVERY === 0;
+
+    if (onNudgeBeat) {
+      const statusRaw = execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      const changedFiles = statusRaw ? statusRaw.split('\n').length : 0;
+      console.error(`[Atomic Commit Check] ${state.editCount} Edit/Write calls since the last commit (${changedFiles} files currently changed).`);
+      console.error(`If a logically complete chunk of work is done, commit it now before continuing - large uncommitted diffs are harder to review and harder to recover from.`);
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+}
+
+let inputData = '';
+const timeout = setTimeout(() => { main(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 */ }
+  main(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  main(null);
+});