moflo 4.9.17 → 4.9.19

package/.claude/commands/simplify.md

@@ -34,20 +34,15 @@ Pick the smallest tier the diff genuinely fits.
 
 Critical-surface files (launcher, hooks, MCP wiring) raise the *care* of the agent prompt — sharper checklist, blast-radius framing — they do **not** automatically escalate to NORMAL. Risk-weighted ≠ headcount-weighted.
 
-## Phase 3: Route the model (skip for TRIVIAL)
+## Phase 3: Use the classifier's model (skip for TRIVIAL)
 
-Before spawning any Agent, ask the moflo router which model to use:
+The classifier returns the right model for the tier — no separate router call needed:
 
-```
-mcp__moflo__hooks_model-route — {
-  task: "Review N-line change in <files> for reuse, quality, efficiency",
-  preferCost: true
-}
-```
+- `sonnet` (default) — real logic edits, single agent or 3-agent fan-out.
+- `haiku` — mostly-relocation diffs (mechanical moves; pattern-matching beats deep reasoning).
+- `opus` — never returned. Code review is breadth-bound, not depth-bound; sonnet 3-way IS the high-effort tier.
 
-**Wording rules:** the router's complexity score is keyword-sensitive. Avoid `refactor`, `architect`, `audit`, `system`, `redesign`, `migrate` — those force opus even when scoring suggests sonnet. State LOC count, file count, and "review for reuse, quality, efficiency". Nothing more.
-
-**Hard rule for `/simplify`: opus is never correct.** Code review never needs Opus reasoning, even on critical surface. If the router returns `opus`, downgrade to `sonnet`. On router failure, default to `sonnet`. Comment trims and pure formatting → `haiku`.
+Pass the classifier's `model` field verbatim to Agent's `model` parameter. If you fell back to prose rules in Phase 2 (no classifier), default to `sonnet`.
 
 ## Phase 4: Validation pass (re-run after fixes from a prior simplify)
 
@@ -57,8 +52,11 @@ Escalate one tier (self-review → SMALL agent) only if the fix introduced a new
 
 ## Phase 5: Run the appropriate review
 
-### TRIVIAL / Validation
-Run the three category checks (reuse / quality / efficiency) yourself in one pass against the diff. Most TRIVIAL diffs are clean — confirm and exit. Budget: ~30 seconds, no Agent.
+### TRIVIAL
+Print one confirmation line (`simplify: TRIVIAL — N LOC, 1 file — stamped`) and exit. **Do not** walk the three-category check; the classifier already concluded the diff is below the review-value threshold. Budget: <5 seconds, no Agent.
+
+### Validation pass
+Run the three category checks against the post-fix diff in one pass. Most are clean — confirm and exit. Budget: ~30 seconds, no Agent.
 
 ### SMALL — one agent
 ```

package/.claude/helpers/gate.cjs

@@ -2,11 +2,12 @@
 'use strict';
 var fs = require('fs');
 var path = require('path');
+var cp = require('child_process');
 
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -93,6 +94,109 @@ var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
 var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|spec|specs|cypress|e2e|fixtures?)[\\\/]|\.(test|spec)\.[mc]?[jt]sx?$|\.fixture\.[mc]?[jt]sx?$/i;
+// Docs-only PR exemption: text/markup/image extensions that cannot change runtime behaviour.
+// If EVERY file in the PR diff matches this, skip testing/simplify/learnings gates.
+// Anchored to end-of-path so e.g. `foo.md.js` does not match. Excludes lock files / configs
+// on purpose — those are inert for edit-reset (above) but not "documentation".
+var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
+
+// Classifier-aware simplify gate skip. Returns a string reason if the gate
+// can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
+// so the gate's "trivial" definition matches the skill's exactly.
+//
+// Two paths:
+//   1. snapshot path — /simplify ran earlier on this branch. Classify the diff
+//      between simplifySnapshotSha and current HEAD/working-tree. If TRIVIAL,
+//      the prior review still covers the branch — no re-run needed.
+//   2. baseline path — no snapshot (first time). Classify the entire branch
+//      diff vs merge-base. If TRIVIAL, the whole PR is below the threshold
+//      where /simplify provides value — auto-pass without ever invoking it.
+//
+// Fail-safe: any error (no classifier, no git, no merge-base) returns null,
+// which forces /simplify to run as today.
+function classifyForGateSkip(state) {
+  var classify;
+  try {
+    classify = require('./simplify-classify.cjs').classifyDiff;
+  } catch (e) { return null; }
+  if (typeof classify !== 'function') return null;
+
+  function tryClassify(diffText, label) {
+    try {
+      var dec = classify(diffText);
+      if (dec.tier === 'TRIVIAL') {
+        var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
+      }
+    } catch (e) { /* fall through */ }
+    return null;
+  }
+
+  function gitDiff(args) {
+    try {
+      return cp.execFileSync('git', args, {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 5000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 8 * 1024 * 1024
+      });
+    } catch (e) { return null; }
+  }
+
+  // Snapshot path: classify everything since /simplify last ran.
+  if (state.simplifySnapshotSha) {
+    var snapDiff = gitDiff(['diff', state.simplifySnapshotSha + '...HEAD']);
+    var workTreeA = gitDiff(['diff', 'HEAD']) || '';
+    if (snapDiff !== null) {
+      var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
+      var hit = tryClassify(combined, 'delta since last /simplify');
+      if (hit) return hit;
+    }
+  }
+
+  // Baseline path: classify the whole branch vs merge-base.
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  for (var i = 0; i < bases.length; i++) {
+    var base;
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+    } catch (e) { continue; }
+    if (!base) continue;
+    var branchDiff = gitDiff(['diff', base + '...HEAD']);
+    var workTreeB = gitDiff(['diff', 'HEAD']) || '';
+    if (branchDiff !== null) {
+      return tryClassify(branchDiff + (workTreeB ? '\n' + workTreeB : ''), 'branch diff');
+    }
+    break;
+  }
+  return null;
+}
+
+// Get the file list changed on the current branch vs the merge-base with origin/main
+// (falling back to local main). Returns an array of repo-relative paths, or null on
+// failure — in which case callers MUST fall through to the standard gate (fail-safe).
+function getChangedFilesVsBase() {
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  var base = null;
+  for (var i = 0; i < bases.length; i++) {
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+      if (base) break;
+    } catch (e) { /* try next */ }
+  }
+  if (!base) return null;
+  try {
+    var out = cp.execFileSync('git', ['diff', '--name-only', base + '...HEAD'], {
+      cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return out.split('\n').map(function(l) { return l.trim(); }).filter(Boolean);
+  } catch (e) { return null; }
+}
 
 switch (command) {
   case 'check-before-agent': {
@@ -175,10 +279,19 @@ switch (command) {
   case 'record-skill-run': {
     if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
       var s = readState();
-      if (!s.simplifyRun) {
-        s.simplifyRun = true;
-        writeState(s);
-      }
+      var changed = false;
+      if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
+      // Snapshot HEAD so check-before-pr can classify delta-since-simplify and
+      // skip a redundant /simplify re-run when only trivial fixes followed.
+      // Non-fatal — gate falls through to current behaviour without the snapshot.
+      try {
+        var sha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+          stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
+      } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
+      if (changed) writeState(s);
     }
     break;
   }
@@ -208,7 +321,29 @@ switch (command) {
     // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
     var cmd = process.env.TOOL_INPUT_command || '';
     if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    // Docs-only exemption: if every file changed vs the merge-base is a docs/image
+    // file (no runtime-behaviour surface), skip the testing/simplify/learnings gates
+    // and surface a one-line transparency note. Falls through to the standard gate
+    // on any failure (no base, no diff, exec error) — fail-safe by design.
+    var changed = getChangedFilesVsBase();
+    if (changed && changed.length > 0 && changed.every(function(f) { return DOCS_ONLY_RE.test(f); })) {
+      process.stdout.write('Docs-only PR (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
+      break;
+    }
     var s = readState();
+    // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
+    // TRIVIAL, satisfy the simplify gate silently. Reuses the same classifier
+    // the skill uses — same "trivial" definition, no drift. Same threshold that
+    // already maps to TRIVIAL=0 agents inside /simplify, so trusting it at the
+    // gate level is the same trust profile, just one decision earlier.
+    if (config.simplify_gate && !s.simplifyRun) {
+      var skipReason = classifyForGateSkip(s);
+      if (skipReason) {
+        s.simplifyRun = true;
+        writeState(s);
+        process.stdout.write('Simplify gate auto-passed: ' + skipReason + '\n');
+      }
+    }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');

package/.claude/helpers/simplify-classify.cjs

@@ -159,7 +159,10 @@ function decide(stats) {
     reasoning.push(
       `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
     );
-    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+    // Haiku is sufficient for mechanical moves: code already existed and worked,
+    // so review reduces to copy-paste-divergence / dead-after-move pattern checks
+    // — exactly haiku's strength. ~5x cheaper than sonnet on relocation-shape diffs.
+    return { tier: 'SMALL', model: 'haiku', agentCount: 1, reasoning, stats };
   }
 
   // Escalation triggers — any one trips NORMAL (3 agents).

package/.claude/skills/simplify/SKILL.md

@@ -42,13 +42,8 @@ Tier definitions the classifier encodes (for reference, not for re-derivation):
 
 Pick the **smallest tier** the diff genuinely fits. When in doubt, escalate one step (not two).
 
-### TRIVIAL — self-review, no agent spawn
-ALL of these must hold:
-- ≤10 net LOC changed (insertions + deletions, excluding pure whitespace)
-- Single file
-- No logic changes — only comments, formatting, renames of local vars, JSDoc, or string-literal edits
-- No new imports, no new exports, no new function/class declarations
-- No removed safety checks, error handlers, or guards
+### TRIVIAL — gate stamp, no review
+The classifier already proved the diff is below the threshold where review provides value (≤10 net LOC, single file, no declaration/import/export changes, no removed guards). **Stamp the gate with one line of confirmation and exit immediately.** Do not walk the three-category check yourself — the classifier IS the review at this tier, and at the gate level the classifier-aware skip (`bin/gate.cjs:classifyForGateSkip`) often satisfies the gate without invoking this skill at all.
 
 Examples that qualify: trimming a comment, fixing a typo in a log message, renaming a private helper, reformatting a single block.
 Examples that DON'T qualify: changing an `if` condition, reordering function args, deleting a try/catch.
@@ -88,14 +83,21 @@ Do **not** escalate to NORMAL on a validation pass. If the fix is so structural
 
 ## Phase 2.7: Model selection
 
-**Use the model the classifier returned** — always `sonnet` for `/simplify`. Opus is never correct here; the classifier enforces this. No router call needed; the classifier IS the router for this skill.
+**Use the model the classifier returned.** The classifier IS the router for this skill — no separate router call needed. Possible outputs:
+
+- `sonnet` (default) — real logic changes, single agent or three-agent fan-out.
+- `haiku` — mostly-relocation diffs (mechanical moves where pattern-matching beats deep reasoning, ~5x cheaper).
+- `opus` — never. Code review is breadth-bound, not depth-bound; the three-agent fan-out at sonnet is the high-effort tier.
 
-If you fell back to prose rules in Phase 2 (no classifier available), use `sonnet` unconditionally. Pass the model verbatim to Agent's `model` parameter.
+If you fell back to prose rules in Phase 2 (no classifier available), use `sonnet` unconditionally. Pass the classifier's `model` field verbatim to Agent's `model` parameter.
 
 ## Phase 3: Run the appropriate review
 
-### TRIVIAL / Validation: self-review
-Run the same three category checks (reuse / quality / efficiency) yourself, in one pass, against the diff. Most TRIVIAL and validation diffs will be clean — the goal is to confirm, not to fan out. If you find an issue, fix it; otherwise stamp clean. Total budget: ~30 seconds, no Agent calls. No router call needed.
+### TRIVIAL: stamp and exit
+The classifier proved the diff is below the review-value threshold. Print one confirmation line (e.g. `simplify: TRIVIAL — N LOC, 1 file — stamped`) and exit. **Do not** walk the three-category check; the classifier already concluded the answer is "clean." Budget: <5 seconds, no Agent calls.
+
+### Validation pass: confirm clean
+Run the three category checks (reuse / quality / efficiency) yourself, in one pass, against the post-fix diff. Most validation passes are clean — the goal is to confirm fixes didn't introduce new concerns, not to fan out. Budget: ~30 seconds, no Agent calls.
 
 ### SMALL: one agent (model from router)
 Launch a SINGLE Agent with subagent_type `reviewer`, passing the model returned by Phase 2.7's router call. Cap the agent's tool budget by being explicit:

package/bin/gate.cjs

@@ -2,11 +2,12 @@
 'use strict';
 var fs = require('fs');
 var path = require('path');
+var cp = require('child_process');
 
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -93,6 +94,109 @@ var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
 var EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE = /(?:^|[\\\/])(__tests__|__mocks__|tests?|spec|specs|cypress|e2e|fixtures?)[\\\/]|\.(test|spec)\.[mc]?[jt]sx?$|\.fixture\.[mc]?[jt]sx?$/i;
+// Docs-only PR exemption: text/markup/image extensions that cannot change runtime behaviour.
+// If EVERY file in the PR diff matches this, skip testing/simplify/learnings gates.
+// Anchored to end-of-path so e.g. `foo.md.js` does not match. Excludes lock files / configs
+// on purpose — those are inert for edit-reset (above) but not "documentation".
+var DOCS_ONLY_RE = /\.(md|markdown|txt|rst|adoc|html?|pdf|png|jpe?g|gif|svg|webp|ico|bmp)$/i;
+
+// Classifier-aware simplify gate skip. Returns a string reason if the gate
+// can be auto-passed, or null if /simplify must run. Uses simplify-classify.cjs
+// so the gate's "trivial" definition matches the skill's exactly.
+//
+// Two paths:
+//   1. snapshot path — /simplify ran earlier on this branch. Classify the diff
+//      between simplifySnapshotSha and current HEAD/working-tree. If TRIVIAL,
+//      the prior review still covers the branch — no re-run needed.
+//   2. baseline path — no snapshot (first time). Classify the entire branch
+//      diff vs merge-base. If TRIVIAL, the whole PR is below the threshold
+//      where /simplify provides value — auto-pass without ever invoking it.
+//
+// Fail-safe: any error (no classifier, no git, no merge-base) returns null,
+// which forces /simplify to run as today.
+function classifyForGateSkip(state) {
+  var classify;
+  try {
+    classify = require('./simplify-classify.cjs').classifyDiff;
+  } catch (e) { return null; }
+  if (typeof classify !== 'function') return null;
+
+  function tryClassify(diffText, label) {
+    try {
+      var dec = classify(diffText);
+      if (dec.tier === 'TRIVIAL') {
+        var loc = (dec.stats.added || 0) + (dec.stats.deleted || 0);
+        return label + ' is TRIVIAL (' + loc + ' LOC, ' + (dec.stats.fileCount || 0) + ' file(s))';
+      }
+    } catch (e) { /* fall through */ }
+    return null;
+  }
+
+  function gitDiff(args) {
+    try {
+      return cp.execFileSync('git', args, {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 5000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 8 * 1024 * 1024
+      });
+    } catch (e) { return null; }
+  }
+
+  // Snapshot path: classify everything since /simplify last ran.
+  if (state.simplifySnapshotSha) {
+    var snapDiff = gitDiff(['diff', state.simplifySnapshotSha + '...HEAD']);
+    var workTreeA = gitDiff(['diff', 'HEAD']) || '';
+    if (snapDiff !== null) {
+      var combined = snapDiff + (workTreeA ? '\n' + workTreeA : '');
+      var hit = tryClassify(combined, 'delta since last /simplify');
+      if (hit) return hit;
+    }
+  }
+
+  // Baseline path: classify the whole branch vs merge-base.
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  for (var i = 0; i < bases.length; i++) {
+    var base;
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+    } catch (e) { continue; }
+    if (!base) continue;
+    var branchDiff = gitDiff(['diff', base + '...HEAD']);
+    var workTreeB = gitDiff(['diff', 'HEAD']) || '';
+    if (branchDiff !== null) {
+      return tryClassify(branchDiff + (workTreeB ? '\n' + workTreeB : ''), 'branch diff');
+    }
+    break;
+  }
+  return null;
+}
+
+// Get the file list changed on the current branch vs the merge-base with origin/main
+// (falling back to local main). Returns an array of repo-relative paths, or null on
+// failure — in which case callers MUST fall through to the standard gate (fail-safe).
+function getChangedFilesVsBase() {
+  var bases = ['origin/main', 'main', 'origin/master', 'master'];
+  var base = null;
+  for (var i = 0; i < bases.length; i++) {
+    try {
+      base = cp.execFileSync('git', ['merge-base', 'HEAD', bases[i]], {
+        cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+      if (base) break;
+    } catch (e) { /* try next */ }
+  }
+  if (!base) return null;
+  try {
+    var out = cp.execFileSync('git', ['diff', '--name-only', base + '...HEAD'], {
+      cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    return out.split('\n').map(function(l) { return l.trim(); }).filter(Boolean);
+  } catch (e) { return null; }
+}
 
 switch (command) {
   case 'check-before-agent': {
@@ -175,10 +279,19 @@ switch (command) {
   case 'record-skill-run': {
     if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
       var s = readState();
-      if (!s.simplifyRun) {
-        s.simplifyRun = true;
-        writeState(s);
-      }
+      var changed = false;
+      if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
+      // Snapshot HEAD so check-before-pr can classify delta-since-simplify and
+      // skip a redundant /simplify re-run when only trivial fixes followed.
+      // Non-fatal — gate falls through to current behaviour without the snapshot.
+      try {
+        var sha = cp.execFileSync('git', ['rev-parse', 'HEAD'], {
+          cwd: PROJECT_DIR, encoding: 'utf-8', timeout: 2000, windowsHide: true,
+          stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+        if (sha && s.simplifySnapshotSha !== sha) { s.simplifySnapshotSha = sha; changed = true; }
+      } catch (e) { /* no git or detached state — skip snapshot, gate still works */ }
+      if (changed) writeState(s);
     }
     break;
   }
@@ -208,7 +321,29 @@ switch (command) {
     // optional ENV=val prefix segment catches `GH_TOKEN=x gh pr create`.
     var cmd = process.env.TOOL_INPUT_command || '';
     if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    // Docs-only exemption: if every file changed vs the merge-base is a docs/image
+    // file (no runtime-behaviour surface), skip the testing/simplify/learnings gates
+    // and surface a one-line transparency note. Falls through to the standard gate
+    // on any failure (no base, no diff, exec error) — fail-safe by design.
+    var changed = getChangedFilesVsBase();
+    if (changed && changed.length > 0 && changed.every(function(f) { return DOCS_ONLY_RE.test(f); })) {
+      process.stdout.write('Docs-only PR (' + changed.length + ' file' + (changed.length === 1 ? '' : 's') + ') — skipping testing/simplify/learnings gates.\n');
+      break;
+    }
     var s = readState();
+    // Classifier-aware skip: if delta-since-snapshot or whole-branch diff is
+    // TRIVIAL, satisfy the simplify gate silently. Reuses the same classifier
+    // the skill uses — same "trivial" definition, no drift. Same threshold that
+    // already maps to TRIVIAL=0 agents inside /simplify, so trusting it at the
+    // gate level is the same trust profile, just one decision earlier.
+    if (config.simplify_gate && !s.simplifyRun) {
+      var skipReason = classifyForGateSkip(s);
+      if (skipReason) {
+        s.simplifyRun = true;
+        writeState(s);
+        process.stdout.write('Simplify gate auto-passed: ' + skipReason + '\n');
+      }
+    }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');

package/bin/simplify-classify.cjs

@@ -159,7 +159,10 @@ function decide(stats) {
     reasoning.push(
       `mostly relocation: ${stats.declAdded} decls added, ${stats.declRemoved} removed, net ${stats.netDecls >= 0 ? '+' : ''}${stats.netDecls}`,
     );
-    return { tier: 'SMALL', model: 'sonnet', agentCount: 1, reasoning, stats };
+    // Haiku is sufficient for mechanical moves: code already existed and worked,
+    // so review reduces to copy-paste-divergence / dead-after-move pattern checks
+    // — exactly haiku's strength. ~5x cheaper than sonnet on relocation-shape diffs.
+    return { tier: 'SMALL', model: 'haiku', agentCount: 1, reasoning, stats };
   }
 
   // Escalation triggers — any one trips NORMAL (3 agents).

package/dist/src/cli/commands/doctor-fixes.js

@@ -23,26 +23,72 @@ async function runFixCommand(cmd) {
     }
 }
 /**
- * Fix missing hook wiring in settings.json by patching in entries for any
- * REQUIRED_HOOK_WIRING patterns that aren't present. Delegates to shared
- * repairHookWiring() to stay DRY with the upgrade path.
+ * Fix Gate Health failures: bin/.claude-helpers gate.cjs drift AND missing
+ * settings.json hook wiring. The check has three independent failure modes
+ * and the prior fix only handled hook wiring — leaving bin/helper drift
+ * unresolved while still claiming success (the "Auto-fixed 1 issue" lie that
+ * surfaced when #920 mirrored the docs-only PR exemption into only one of
+ * the two gate.cjs files).
+ *
+ * Sync direction is decided by which source file is "ahead" of its installed
+ * counterpart in `node_modules/moflo/`:
+ *   - If only source `bin/gate.cjs` differs from installed bin → mirror bin → helper.
+ *   - If only source `.claude/helpers/gate.cjs` differs from installed helper → mirror helper → bin.
+ *   - If both are ahead with different content (genuine ambiguity) → bail
+ *     and let the caller report failure; refuse to silently pick a side.
+ *   - If `node_modules/moflo/` is missing entirely (consumer never installed,
+ *     unusual layout) → bail.
  */
 async function fixGateHealthHooks() {
-    const settingsPath = join(process.cwd(), '.claude', 'settings.json');
-    if (!existsSync(settingsPath))
-        return false;
-    try {
-        const raw = readFileSync(settingsPath, 'utf8');
-        const settings = JSON.parse(raw);
-        const { repaired } = repairHookWiring(settings);
-        if (repaired.length === 0)
-            return true; // nothing to fix
-        writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
-        return true;
+    const cwd = process.cwd();
+    let driftFixed = true; // true means "no drift to fix or drift resolved"
+    const binGate = join(cwd, 'bin', 'gate.cjs');
+    const helperGate = join(cwd, '.claude', 'helpers', 'gate.cjs');
+    const installedBin = join(cwd, 'node_modules', 'moflo', 'bin', 'gate.cjs');
+    const installedHelper = join(cwd, 'node_modules', 'moflo', '.claude', 'helpers', 'gate.cjs');
+    if (existsSync(binGate) && existsSync(helperGate)) {
+        try {
+            const binContent = readFileSync(binGate, 'utf8');
+            const helperContent = readFileSync(helperGate, 'utf8');
+            if (binContent !== helperContent) {
+                const installedBinContent = existsSync(installedBin) ? readFileSync(installedBin, 'utf8') : null;
+                const installedHelperContent = existsSync(installedHelper) ? readFileSync(installedHelper, 'utf8') : null;
+                const binAhead = installedBinContent !== null && binContent !== installedBinContent;
+                const helperAhead = installedHelperContent !== null && helperContent !== installedHelperContent;
+                if (binAhead && !helperAhead) {
+                    writeFileSync(helperGate, binContent, 'utf-8');
+                }
+                else if (helperAhead && !binAhead) {
+                    writeFileSync(binGate, helperContent, 'utf-8');
+                }
+                else {
+                    // Both ahead with different content, OR neither ahead (no install
+                    // to anchor on). Refuse to pick a side — surface the failure.
+                    driftFixed = false;
+                }
+            }
+        }
+        catch {
+            driftFixed = false;
+        }
     }
-    catch {
-        return false;
+    // Hook-wiring repair (separate failure mode that this fixer also owns).
+    const settingsPath = join(cwd, '.claude', 'settings.json');
+    let wiringFixed = true;
+    if (existsSync(settingsPath)) {
+        try {
+            const raw = readFileSync(settingsPath, 'utf8');
+            const settings = JSON.parse(raw);
+            const { repaired } = repairHookWiring(settings);
+            if (repaired.length > 0) {
+                writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+            }
+        }
+        catch {
+            wiringFixed = false;
+        }
     }
+    return driftFixed && wiringFixed;
 }
 /**
  * Execute the fix for a failed/warned health check.