moflo 4.9.11 → 4.9.12

package/.claude/commands/simplify.md

@@ -1,55 +1,103 @@
 ---
-description: Review changed code for reuse, quality, and efficiency, then fix any issues found.
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Sizes review effort to the diff and routes the cheapest model that fits.
 ---
 
-# /simplify — Gate-Compliant Code Review
+# /simplify — Adaptive Gate-Compliant Code Review
 
-Review all changed files for reuse opportunities, code quality, and efficiency improvements.
+Review changed code for reuse, quality, and efficiency. **Effort scales with diff size; model is routed for cost.** A 5-line comment trim does not get 3 Opus agents.
 
-**This command overrides any built-in simplify skill.** Follow these steps exactly.
+## Phase 0: Gate prerequisites
 
-## Prerequisites (MANDATORY — do these FIRST)
+These satisfy the memory-first and task-create-first gates. Always do them before any Agent spawn.
 
-1. **Memory search**: Search for relevant patterns before reviewing
-```
-mcp__moflo__memory_search — query: "code quality patterns", namespace: "patterns"
-```
+1. **Memory search** — `mcp__moflo__memory_search — query: "code quality patterns", namespace: "patterns"`
+2. **Task create** — `TaskCreate — subject: "🔍 [Reviewer] Simplify changed code"`
 
-2. **Create task**: Track the simplification work
-```
-TaskCreate — subject: "🔍 [Reviewer] Simplify changed code", description: "Review changed files for reuse, quality, and efficiency"
+## Phase 1: Identify the diff
+
+```bash
+git diff HEAD          # working tree
+git diff main...HEAD   # committed since branch base
 ```
 
-## Execution
+Treat the union as the diff. Note whether `/simplify` already ran on this branch in this session — if so, you are in a **validation pass** (Phase 4 below).
 
-After prerequisites are satisfied, get the list of changed files:
+## Phase 2: Classify the diff
 
-```bash
-git diff --name-only HEAD~1
-```
+Pick the smallest tier the diff genuinely fits.
 
-Then launch 3 reviewer agents **in parallel** (single message, multiple Agent tool calls).
+| Tier | Trigger | Action |
+|------|---------|--------|
+| **TRIVIAL** | ≤10 net LOC, single file, comments/formatting/local renames only | Self-review, zero agents |
+| **SMALL** | ≤200 net LOC, ≤2 files, no API/dependency change | **One agent** (default for most diffs, including critical surface) |
+| **NORMAL** | ≥3 files, OR >200 LOC, OR public API change, OR new/removed dependency, OR cross-cutting refactor | Three parallel agents |
 
-**CRITICAL**: Each agent prompt below includes a mandatory memory search step. This is required because subagents must satisfy the memory-first gate independently before using Glob, Grep, or Read tools. Do NOT remove the memory search from agent prompts.
+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)
+
+Before spawning any Agent, ask the moflo router which model to use:
 
-### Agent 1: Reuse Reviewer
 ```
-Agent — name: "reuse-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code reuse patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for code reuse opportunities. Look for: duplicated logic that could use existing utilities, patterns already solved elsewhere in the codebase, opportunities to extract shared helpers. Files: $CHANGED_FILES"
+mcp__moflo__hooks_model-route — {
+  task: "Review N-line change in <files> for reuse, quality, efficiency",
+  preferCost: true
+}
 ```
 
-### Agent 2: Quality Reviewer
+**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`.
+
+## Phase 4: Validation pass (re-run after fixes from a prior simplify)
+
+If `/simplify` already ran on this branch in this session AND the only edits since are fixes the prior pass surfaced, **default to TRIVIAL self-review** regardless of LOC count. The fan-out happened; the fix is small relative to the already-reviewed diff.
+
+Escalate one tier (self-review → SMALL agent) only if the fix introduced a new file, a new exported symbol, a new dependency, or a control-flow change not covered by the original findings. Never escalate a validation pass to NORMAL.
+
+## 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.
+
+### SMALL — one agent
 ```
-Agent — name: "quality-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code quality patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for code quality issues. Look for: unclear naming, overly complex logic, missing error handling at system boundaries, potential bugs, consistency with existing patterns. Files: $CHANGED_FILES"
+Agent — {
+  subagent_type: "reviewer",
+  model: "<sonnet (or haiku for trivial-formatting tier from router)>",
+  prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'code review patterns' and namespace 'patterns' to satisfy the memory-first gate. THEN review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues as file:line + 1-line description. Max 5 file reads. Under 200 words. Skip cosmetic style. Don't suggest cross-cutting refactors of code outside this diff."
+}
 ```
 
-### Agent 3: Efficiency Reviewer
+For critical-surface files, prepend a 1-line risk note (e.g., "This is `bin/session-start-launcher.mjs` — runs in every consumer's session-start hot path; cross-platform + blast-radius matter."). One careful agent, not three.
+
+### NORMAL — three parallel agents
+Launch three agents in a single message, each at the routed model (typically sonnet). Each agent gets the SMALL-tier tool-budget cap.
+
+- **Agent 1 (Reuse):** existing helpers/utilities that should be used; duplicated patterns; functions re-implementing something already in the codebase.
+- **Agent 2 (Quality):** redundant state, parameter sprawl, copy-paste with variation, leaky abstractions, stringly-typed code, nested conditionals 3+ levels, unnecessary comments.
+- **Agent 3 (Efficiency):** unnecessary work, missed concurrency, hot-path bloat, recurring no-op updates, TOCTOU existence checks, unbounded structures, over-broad reads.
+
+Each agent prompt must start with `FIRST ACTION: mcp__moflo__memory_search ... namespace: "patterns"` — subagents must satisfy the memory-first gate independently before Glob/Grep/Read.
+
+## Phase 6: Fix or skip
+
+Aggregate findings. Fix each issue directly that's worth fixing. False positives or out-of-scope: note and skip without arguing.
+
+If fixes were made, re-run tests to confirm nothing broke. If tests fail after a fix, revert it.
+
+After fixes: the next `/simplify` invocation is a **validation pass** (Phase 4). Bundle related fixes into one batch so a single validation pass covers them — don't re-fan-out for cosmetic micro-corrections.
+
+## Phase 7: Optional — record routing outcome
+
+If you spawned an agent, feed back the outcome so the router learns:
+
 ```
-Agent — name: "efficiency-reviewer", run_in_background: true, subagent_type: "reviewer", prompt: "FIRST ACTION: Run mcp__moflo__memory_search with query 'performance optimization patterns' and namespace 'patterns'. You MUST do this before any Glob, Grep, or Read calls. THEN review these changed files for efficiency improvements. Look for: unnecessary allocations, O(n^2) where O(n) is possible, redundant operations, opportunities to batch or cache. Files: $CHANGED_FILES"
+mcp__moflo__hooks_model-outcome — { task: "...", model: "<chosen>", outcome: "success" | "failure" | "escalated" }
 ```
 
-## Post-Review
+`escalated` only when a real miss happened that a higher tier would have caught — never used to retroactively justify opus.
+
+## Briefly summarize
 
-1. Collect findings from all 3 reviewers
-2. Apply fixes that preserve ALL existing functionality — no behavior changes
-3. If fixes were made, re-run tests to confirm nothing broke
-4. If tests fail after fixes, revert the simplification changes
+End with one or two sentences: which tier ran, which model, what was fixed (or "clean — no changes"). No headers, no bullets.

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

@@ -5,7 +5,7 @@ description: Review changed code for reuse, quality, and efficiency, then fix an
 
 # /simplify — Adaptive Code Review
 
-Review changed code for reuse opportunities, quality issues, and efficiency improvements. **Effort scales with diff size** — a 5-line comment trim doesn't get the same treatment as a 500-line refactor.
+Review changed code for reuse opportunities, quality issues, and efficiency improvements. **Effort scales with diff size and reuses prior context** — a 5-line comment trim doesn't get the same treatment as a 500-line refactor, and a re-run after fixing pass-1 findings doesn't re-pay for a fresh fan-out.
 
 ## Phase 1: Identify changes
 
@@ -13,9 +13,11 @@ Run `git diff HEAD` (working tree) and `git diff main...HEAD` (committed) to get
 
 Treat the union of staged + unstaged + committed-since-base as the diff to review.
 
+Also note: was `/simplify` already run on this branch in this session? If yes, you're in a **validation pass** (Phase 2.5 below) — most of the heavy lifting is done.
+
 ## Phase 2: Classify the diff
 
-Pick the **smallest tier** the diff genuinely fits. When in doubt, escalate.
+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:
@@ -28,38 +30,103 @@ ALL of these must hold:
 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.
 
-### SMALL — single agent, all three categories
+### SMALL — single agent, all three categories (DEFAULT for most diffs)
 ALL of these must hold:
-- ≤50 net LOC changed
+- ≤200 net LOC changed
 - ≤2 files
 - No structural changes (no new modules, no API additions/removals, no contract changes)
 
-Examples that qualify: extracting a constant, inlining a one-liner, swapping a `for` for a `forEach`, adding one early-return.
+This is the default tier for **most real diffs**, including changes to critical surface (launcher, hooks, MCP wiring). Critical surface raises the *care* of the agent prompt (sharper checklist, blast-radius framing), not the *number* of agents.
+
+Examples that qualify: extracting a constant, inlining a one-liner, swapping a `for` for a `forEach`, adding one early-return, refactoring a single function within a file, adding a cache fast-path inside an existing block.
 
-### NORMAL — three parallel agents (the original flow)
-Anything that doesn't fit TRIVIAL or SMALL. Includes any diff that:
-- Spans 3+ files
+### NORMAL — three parallel agents
+Reserved for **genuinely cross-cutting** changes. ANY of these triggers NORMAL:
+- 3+ files changed
+- >200 net LOC changed
 - Adds/removes/renames a public API
-- Changes control flow in a non-trivial way
 - Introduces or removes a dependency
-- Touches `bin/`, hooks, MCP tool handlers, or anything called out in `CLAUDE.md` as critical surface
+- Cross-cutting refactor (touches the same pattern in multiple modules)
+
+Three agents exist to cover orthogonal axes (Reuse / Quality / Efficiency) when the change is broad enough that one agent's tool-call budget can't survey it all. For single-file edits, one focused agent always covers all three axes — three is duplication, not coverage.
+
+## Phase 2.5: Validation pass (re-run after fixes)
+
+If `/simplify` already ran on this branch in this session AND the only edits since are fixes driven by the prior pass's findings, default to **self-review tier** regardless of LOC count. The fan-out already happened; the fix is small relative to the diff that was already reviewed.
+
+Escalate one tier (self-review → SMALL agent) only if the fix introduced any of:
+- A new file
+- A new exported symbol
+- A new dependency or import from a previously-untouched module
+- A change to control flow not covered in the original findings
+
+Do **not** escalate to NORMAL on a validation pass. If the fix is so structural that NORMAL is warranted, treat it as a fresh diff and start over from Phase 1.
+
+## Phase 2.7: Route the model (before any Agent spawn)
+
+For every tier that spawns an Agent (SMALL / NORMAL — TRIVIAL self-review skips this), call the moflo router to pick the cheapest model that fits the task **before** invoking Agent:
+
+```
+mcp__moflo__hooks_model-route — {
+  task: "<diff summary — see wording rules below>",
+  preferCost: true
+}
+```
+
+### Wording the task description
+
+The router's complexity score is keyword-sensitive. Words like `refactor`, `architect`, `audit`, `system`, `redesign`, `migrate` flip a high-complexity flag and force opus *even when scoring suggests sonnet*. For `/simplify` you are **always doing code review**, never genuine architecture, so frame the task accordingly:
+
+- ✅ Good: `"Review 110-line single-file change in bin/session-start-launcher.mjs for reuse, quality, efficiency."`
+- ❌ Bad: `"Review refactor that adds mtime-cache fast-path and architects new caching layer."`
 
-When CLAUDE.md flags a file as critical surface (SessionStart, launcher, hooks, MCP coordinator wiring, swarm/hive-mind), **always escalate to NORMAL** regardless of LOC count. Risk-weighted, not size-weighted.
+Drop the trigger words. State LOC count, file count, and "review for reuse, quality, efficiency". That's enough signal.
+
+### Applying the result
+
+The router returns `{ model: 'haiku' | 'sonnet' | 'opus', complexity, reasoning, alternatives, ... }`.
+
+**Hard rule for `/simplify`: opus is never correct.** Code review does not require Opus-tier reasoning even on critical surface. If the router returns `opus`:
+
+1. Look at `alternatives` — if `sonnet` scores higher than the selected model's confidence, downgrade to sonnet.
+2. Otherwise, downgrade to sonnet anyway (treat opus as "router was uncertain — pick the safer middle").
+
+Pass the final model verbatim to the Agent's `model` parameter (Agent accepts `'haiku' | 'sonnet' | 'opus'`). On router failure (MCP call errors), default to `'sonnet'`.
+
+In practice: comment trims and pure formatting → haiku; everything else for `/simplify` → sonnet.
+
+### Feed back the outcome
+
+After the agent completes, record the outcome so the router learns:
+
+```
+mcp__moflo__hooks_model-outcome — { task: "<same wording as route call>", model: "<chosen>", outcome: "success" | "failure" | "escalated" }
+```
+
+`escalated` = the agent missed something a higher-tier pass would have caught. That signal teaches the router to bias similar tasks upward next time. Don't fake `escalated` to retroactively justify opus — only record it when a *real* miss happened.
 
 ## Phase 3: Run the appropriate review
 
-### TRIVIAL: self-review
-Run the same three category checks (reuse / quality / efficiency) yourself, in one pass, against the diff. Most TRIVIAL 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.
+### 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.
 
-### SMALL: one agent
-Launch a SINGLE Agent with subagent_type `reviewer` covering all three categories in one prompt. Pass the diff inline. Budget: ~1 minute.
+### 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:
 
 ```
-Agent — subagent_type: "reviewer", prompt: "Review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues with file:line; skip generic advice. Under 200 words."
+Agent — {
+  subagent_type: "reviewer",
+  model: "<from router, typically 'sonnet'>",
+  prompt: "Review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues as file:line + 1-line description. Max 5 file reads. Under 200 words. Skip cosmetic style. Don't suggest cross-cutting refactors of code outside this diff."
+}
 ```
 
-### NORMAL: three parallel agents (original flow)
-Launch three agents in a single message — Reuse, Quality, Efficiency — passing the full diff to each. Use the original flow's category checklists.
+For critical-surface files, prepend a 1-line risk note to the prompt (e.g., "This is `bin/session-start-launcher.mjs` — runs in every consumer's session-start hot path; cross-platform + blast-radius matter."). One careful agent, not three.
+
+Budget: ~1 minute.
+
+### NORMAL: three parallel agents (model from router, applied to all)
+Launch three agents in a single message — Reuse, Quality, Efficiency — passing the full diff and the same routed `model` to each. Each agent gets the same tool-budget cap as SMALL.
 
 **Reuse**: existing helpers/utilities that should be used instead; duplicated patterns; new functions that re-implement something already in the codebase.
 
@@ -69,14 +136,16 @@ Launch three agents in a single message — Reuse, Quality, Efficiency — passi
 
 ## Phase 4: Fix or skip
 
-Aggregate findings. Fix each one directly. False positives or not-worth-fixing — note and skip without arguing. If TRIVIAL self-review found nothing, just confirm clean and exit.
+Aggregate findings. Fix each one directly. False positives or not-worth-fixing — note and skip without arguing. If self-review found nothing, just confirm clean and exit.
 
 If fixes were made, re-run tests to confirm nothing broke. If tests fail after a fix, revert it.
 
+After fixes: the next `/simplify` invocation is a **validation pass** (Phase 2.5). Do not re-fan-out unless the fix added genuinely new concerns — bundle related fixes into one batch so a single validation pass covers them.
+
 ## Phase 5: Stamp the gate
 
-Whatever tier ran, the gate (`check-before-pr`) registers /simplify as having executed. The skill is satisfied.
+Whatever tier ran, the gate (`check-before-pr`) registers /simplify as having executed. The skill is satisfied. Self-review counts.
 
 ## Briefly summarize
 
-End with one or two sentences: which tier, what was fixed (or "clean — no changes"). No headers, no bullets unless needed.
+End with one or two sentences: which tier ran, what was fixed (or "clean — no changes"). No headers, no bullets unless needed.

package/bin/session-start-launcher.mjs

@@ -10,7 +10,7 @@
 import { spawn, execFileSync } from 'child_process';
 import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync, readdirSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname, join } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
@@ -218,11 +218,17 @@ try {
   // own errors if the DB is still broken.
 }
 
-// ── 0d. Clear post-install restart notice when version is current (#867) ───
+// ── 0d. Silently clear post-install restart notice when version is current (#867, #887) ─
 // scripts/post-install-notice.mjs drops `.moflo/restart-pending.json` on every
 // `npm install moflo`. The UserPromptSubmit hook surfaces it on every prompt
 // until cleared, so this session only sees the message between install and
 // the FIRST restart that actually picks up the new bits.
+//
+// Cleanup is silent (#887): the user already saw + acted on the restart prompt
+// — surfacing a "cleared notice" line on the very next session reads like an
+// error in additionalContext and inflates mutationCount, which would also fire
+// the closing "starting background tasks" framing. Both are noise on a
+// successful post-restart session.
 try {
   const pendingPath = join(mofloDir(projectRoot), 'restart-pending.json');
   const pkgPath = resolve(projectRoot, 'node_modules/moflo/package.json');
@@ -231,7 +237,6 @@ try {
   if (pending && typeof pending.version === 'string' && pending.version === installedVersion) {
     unlinkSync(pendingPath);
     try { unlinkSync(join(mofloDir(projectRoot), 'last-install-banner.json')); } catch { /* tracker may not exist */ }
-    emitMutation('cleared post-install restart notice', `${installedVersion} now running`);
   }
 } catch { /* file missing or malformed — silent fast-path */ }
 
@@ -304,7 +309,7 @@ try {
 // Controlled by `auto_update.enabled` in moflo.yaml (default: true).
 // When moflo is upgraded (npm install), scripts and helpers may be stale.
 // Detect version change and sync from source before running hooks.
-let autoUpdateConfig = { enabled: true, scripts: true, helpers: true };
+let autoUpdateConfig = { enabled: true, scripts: true, helpers: true, hookBlockDrift: 'warn' };
 try {
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (existsSync(mofloYaml)) {
@@ -313,9 +318,12 @@ try {
     const enabledMatch = yamlContent.match(/auto_update:\s*\n\s+enabled:\s*(true|false)/);
     const scriptsMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+scripts:\s*(true|false)/);
     const helpersMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+helpers:\s*(true|false)/);
+    // #881: hook-block drift detector (warn | regenerate | off; default warn)
+    const driftMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+hook_block_drift:\s*(warn|regenerate|off)/);
     if (enabledMatch) autoUpdateConfig.enabled = enabledMatch[1] === 'true';
     if (scriptsMatch) autoUpdateConfig.scripts = scriptsMatch[1] === 'true';
     if (helpersMatch) autoUpdateConfig.helpers = helpersMatch[1] === 'true';
+    if (driftMatch) autoUpdateConfig.hookBlockDrift = driftMatch[1];
   }
 } catch (err) {
   // Defaults (all true) keep the upgrade flow alive but the user should
@@ -881,6 +889,138 @@ try {
   emitWarning(`settings.json migration failed (${errMessage(err)})`);
 }
 
+// ── 3a-vi. Hook-block drift detection (#881) ───────────────────────────────
+// Hash the consumer's settings.json hook block against the reference block
+// `generateHooksConfig()` would produce for this moflo version. Catches
+// drift the per-bug `repairHookWiring` / `rewriteIncorrectHookWiring` rules
+// don't cover (future hook events, partial migrations, hand-edited commands).
+// Runs every session under `auto_update.enabled`, not only on version change.
+//
+// Modes (`auto_update.hook_block_drift` in moflo.yaml):
+//   warn        — print a one-line summary + diff to stdout (default)
+//   regenerate  — additively add missing hooks; falls back to warn when the
+//                 consumer has extra (custom) hooks, to avoid clobbering
+//   off         — skip entirely
+//
+// Also respects a `claudeFlow.hooks.locked: true` sentinel in settings.json
+// — if set, the user has explicitly opted out of drift surfacing.
+// Fast-path: `.moflo/hook-drift-cache.json` records the last clean run. If
+// settings.json + the dist module both still match the cached mtimes and the
+// cached check was clean (consumerHash === referenceHash), skip readFile +
+// JSON.parse + dynamic import entirely. This block runs every session; the
+// cache makes it ~free in the steady state.
+//
+// Returns the values to persist on the slow path, or null when skipped
+// (cache hit, no settings.json, no dist module, locked, etc.). Pulled out
+// to keep the guard chain flat — the original inline form was 9 levels deep.
+async function runHookBlockDriftCheck() {
+  const settingsPath = resolve(projectRoot, '.claude', 'settings.json');
+  let settingsStat;
+  try { settingsStat = statSync(settingsPath); } catch { return null; }
+
+  // statSync each candidate doubles as existence check + provides the mtime
+  // we need for the cache key, avoiding the existsSync→import TOCTOU pattern.
+  const hbhCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/hook-block-hash.js'),
+    resolve(projectRoot, 'dist/src/cli/services/hook-block-hash.js'),
+  ];
+  let hbhPath = null;
+  let hbhStat = null;
+  for (const p of hbhCandidates) {
+    try { hbhStat = statSync(p); hbhPath = p; break; } catch { /* try next */ }
+  }
+  if (!hbhPath) return null;
+
+  // Fast-path requires consumerHash === referenceHash (a previously *clean*
+  // run). A drifted-but-cached state still needs to re-emit the warning each
+  // session, so we always re-do the work in that case.
+  const cachePath = join(mofloDir(projectRoot), 'hook-drift-cache.json');
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cachePath, 'utf-8')); } catch { /* missing or corrupt */ }
+  if (
+    cached &&
+    cached.settingsMtimeMs === settingsStat.mtimeMs &&
+    cached.moduleMtimeMs === hbhStat.mtimeMs &&
+    cached.consumerHash === cached.referenceHash
+  ) return null;
+
+  // Try-catch around the dynamic import handles the file disappearing
+  // between statSync and import (TOCTOU); module-load errors fall through.
+  let mod = null;
+  try { mod = await import(pathToFileURL(hbhPath).href); } catch { /* TOCTOU or load error — skip */ return null; }
+  if (typeof mod.computeHookBlockDrift !== 'function') return null;
+
+  const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  if (typeof mod.isHookBlockLocked === 'function' && mod.isHookBlockLocked(settings)) return null;
+
+  const report = mod.computeHookBlockDrift(settings.hooks || {});
+  let regenerated = false;
+
+  if (report.drifted) {
+    const wantRegenerate = autoUpdateConfig.hookBlockDrift === 'regenerate';
+    const safeToRegenerate = wantRegenerate && report.extra.length === 0;
+    if (safeToRegenerate && typeof mod.applyAdditiveRegeneration === 'function') {
+      const { added } = mod.applyAdditiveRegeneration(settings, report);
+      if (added > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        regenerated = true;
+        emitMutation(
+          'regenerated hook block',
+          `added ${plural(added, 'missing hook entry')} (drift ${report.consumerHash} → ${report.referenceHash})`,
+        );
+      }
+    } else {
+      const parts = [];
+      if (report.missing.length > 0) parts.push(plural(report.missing.length, 'missing entry'));
+      if (report.extra.length > 0) parts.push(`${plural(report.extra.length, 'custom hook')} preserved`);
+      const reason = parts.join(', ') || 'reordered';
+      // stdout (not stderr) so Claude sees this in `additionalContext` and
+      // surfaces it to the user — not a mutation since we didn't change anything.
+      try {
+        process.stdout.write(
+          `moflo: hook block drift (${reason}); run \`flo doctor hook-drift\` or set auto_update.hook_block_drift: regenerate in moflo.yaml\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
+    }
+  }
+
+  // Regeneration mutated settings.json — re-stat for the fresh mtime so next
+  // session's fast-path matches; otherwise reuse the stat we already have.
+  let finalSettingsMtime = settingsStat.mtimeMs;
+  if (regenerated) {
+    try { finalSettingsMtime = statSync(settingsPath).mtimeMs; } catch { /* keep prior */ }
+  }
+  // After successful regeneration consumerHash matches referenceHash by construction.
+  const finalConsumerHash = regenerated ? report.referenceHash : report.consumerHash;
+
+  return {
+    cachePath,
+    settingsMtimeMs: finalSettingsMtime,
+    moduleMtimeMs: hbhStat.mtimeMs,
+    consumerHash: finalConsumerHash,
+    referenceHash: report.referenceHash,
+  };
+}
+
+try {
+  if (autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off') {
+    const result = await runHookBlockDriftCheck();
+    if (result) {
+      try {
+        mkdirSync(mofloDir(projectRoot), { recursive: true });
+        writeFileSync(result.cachePath, JSON.stringify({
+          settingsMtimeMs: result.settingsMtimeMs,
+          moduleMtimeMs: result.moduleMtimeMs,
+          consumerHash: result.consumerHash,
+          referenceHash: result.referenceHash,
+        }));
+      } catch { /* cache is opportunistic — non-fatal */ }
+    }
+  }
+} catch (err) {
+  emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+}
+
 // ── 3b. Ensure shipped guidance files exist (even without version change) ──
 // Subagents need these files on disk for direct reads without memory search.
 // Also prunes top-level mirrors whose source no longer exists in shipped/

package/dist/src/cli/commands/doctor-checks-deep.js

@@ -552,4 +552,66 @@ export async function checkGateHealth() {
         message: `${caseCount} gate cases, ${hookCount} hook bindings, state file OK`,
     };
 }
+/**
+ * Hash-based hook-block drift check (#881). Complements `checkGateHealth`'s
+ * required-pattern probe by detecting drift in *any* direction — missing
+ * events, modified commands, future hook events not yet covered by
+ * `REQUIRED_HOOK_WIRING`. Uses the self-contained `hook-block-hash` module so
+ * the same logic runs in `flo doctor`, the launcher, and unit tests.
+ *
+ * Reports `pass` when no drift, `warn` with a count summary when drift exists.
+ * Never `fail` — drift is informational; the user (or `regenerate` mode) is
+ * responsible for deciding what to do.
+ */
+export async function checkHookBlockDrift() {
+    const projectDir = findConsumerProjectDir();
+    const settingsPath = join(projectDir, '.claude', 'settings.json');
+    if (!existsSync(settingsPath)) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'warn',
+            message: '.claude/settings.json not found',
+            fix: 'npx moflo init',
+        };
+    }
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    }
+    catch (e) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'warn',
+            message: `cannot parse .claude/settings.json: ${errorDetail(e)}`,
+        };
+    }
+    const { computeHookBlockDrift, isHookBlockLocked } = await import('../services/hook-block-hash.js');
+    if (isHookBlockLocked(settings)) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'pass',
+            message: 'drift check skipped — claudeFlow.hooks.locked: true',
+        };
+    }
+    const report = computeHookBlockDrift(settings.hooks ?? {});
+    if (!report.drifted) {
+        return {
+            name: 'Hook Block Drift',
+            status: 'pass',
+            message: `hook block matches reference (${report.consumerHash})`,
+        };
+    }
+    const parts = [];
+    parts.push(`drift ${report.consumerHash} vs ${report.referenceHash}`);
+    if (report.missing.length > 0)
+        parts.push(`${report.missing.length} missing`);
+    if (report.extra.length > 0)
+        parts.push(`${report.extra.length} custom`);
+    return {
+        name: 'Hook Block Drift',
+        status: 'warn',
+        message: parts.join(', '),
+        fix: 'set auto_update.hook_block_drift: regenerate in moflo.yaml, or claudeFlow.hooks.locked: true to suppress',
+    };
+}
 //# sourceMappingURL=doctor-checks-deep.js.map

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

@@ -12,7 +12,7 @@ import { execSync, exec } from 'child_process';
 import { promisify } from 'util';
 import os from 'os';
 import { getDaemonLockHolder, releaseDaemonLock, isDaemonProcess } from '../services/daemon-lock.js';
-import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkMofloDbBridge, getMofloRoot, } from './doctor-checks-deep.js';
+import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkHookBlockDrift, checkMofloDbBridge, getMofloRoot, } from './doctor-checks-deep.js';
 import { checkEmbeddingHygiene } from './doctor-embedding-hygiene.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
@@ -1548,6 +1548,7 @@ export const doctorCommand = {
             checkMcpSpellIntegration,
             checkHookExecution,
             checkGateHealth,
+            checkHookBlockDrift,
             checkMofloDbBridge,
             // Issue #818 / epic #798 — coordinator-path tripwires. They share the
             // singleton coordinator with checkSubagentHealth above and assert by
@@ -1595,6 +1596,8 @@ export const doctorCommand = {
             'hooks': checkHookExecution,
             'gates': checkGateHealth,
             'gate': checkGateHealth,
+            'hook-drift': checkHookBlockDrift,
+            'drift': checkHookBlockDrift,
             'sandbox': checkSandboxTier,
             'sandbox-tier': checkSandboxTier,
             'moflodb': checkMofloDbBridge,

package/dist/src/cli/config/moflo-config.js

@@ -59,11 +59,11 @@ const DEFAULT_CONFIG = {
     models: {
         default: 'opus',
         research: 'sonnet',
-        review: 'opus',
+        review: 'sonnet',
         test: 'sonnet',
     },
     model_routing: {
-        enabled: false,
+        enabled: true,
         confidence_threshold: 0.85,
         cost_optimization: true,
         circuit_breaker: true,
@@ -82,6 +82,7 @@ const DEFAULT_CONFIG = {
         enabled: true,
         scripts: true,
         helpers: true,
+        hook_block_drift: 'warn',
     },
     sandbox: {
         enabled: false,
@@ -205,6 +206,12 @@ function mergeConfig(raw, root) {
             enabled: raw.auto_update?.enabled ?? raw.autoUpdate?.enabled ?? DEFAULT_CONFIG.auto_update.enabled,
             scripts: raw.auto_update?.scripts ?? raw.autoUpdate?.scripts ?? DEFAULT_CONFIG.auto_update.scripts,
             helpers: raw.auto_update?.helpers ?? raw.autoUpdate?.helpers ?? DEFAULT_CONFIG.auto_update.helpers,
+            hook_block_drift: (() => {
+                const v = raw.auto_update?.hook_block_drift ?? raw.autoUpdate?.hookBlockDrift;
+                return v === 'regenerate' || v === 'off' || v === 'warn'
+                    ? v
+                    : DEFAULT_CONFIG.auto_update.hook_block_drift;
+            })(),
         },
         sandbox: {
             enabled: raw.sandbox?.enabled ?? DEFAULT_CONFIG.sandbox.enabled,
@@ -385,7 +392,7 @@ models:
 # When enabled, overrides the static model preferences above
 # by analyzing task complexity and routing to the cheapest capable model.
 model_routing:
-  enabled: false                   # Set to true to enable dynamic routing
+  enabled: true                    # Set to false to pin to the static models above
   confidence_threshold: 0.85       # Min confidence before escalating to a more capable model
   cost_optimization: true          # Prefer cheaper models when confidence is high
   circuit_breaker: true            # Penalize models that fail repeatedly
@@ -398,6 +405,10 @@ auto_update:
   enabled: true                  # Master toggle for version-change auto-sync
   scripts: true                  # Sync .claude/scripts/ from moflo bin/
   helpers: true                  # Sync .claude/helpers/ from moflo source
+  hook_block_drift: warn         # warn | regenerate | off
+                                 # warn = print drift summary on session start (default)
+                                 # regenerate = auto-add missing hooks (only when no customisations)
+                                 # off = skip detection entirely
 
 # OS-level sandbox for spell bash steps
 # Denylist always runs regardless of this setting

package/dist/src/cli/init/moflo-init.js

@@ -382,17 +382,19 @@ status_line:
   show_mcp: true
 
 # Model preferences (haiku, sonnet, opus)
+# These are static fallbacks. When model_routing.enabled is true (default),
+# the dynamic router takes precedence based on task complexity.
 models:
-  default: opus        # Model for general tasks
+  default: opus        # Model for general tasks (kept high for unknowns)
   research: sonnet     # Model for research/exploration agents
-  review: opus         # Model for code review agents
+  review: sonnet       # Code review never needs opus reasoning
   test: sonnet         # Model for test-writing agents
 
 # Intelligent model routing (auto-selects haiku/sonnet/opus per task)
 # When enabled, overrides the static model preferences above
 # by analyzing task complexity and routing to the cheapest capable model.
 model_routing:
-  enabled: false                   # Set to true to enable dynamic routing
+  enabled: true                    # Set to false to pin to the static models above
   confidence_threshold: 0.85       # Min confidence before escalating to a more capable model
   cost_optimization: true          # Prefer cheaper models when confidence is high
   circuit_breaker: true            # Penalize models that fail repeatedly

package/dist/src/cli/services/hook-block-hash.js

@@ -0,0 +1,320 @@
+/**
+ * Settings.json hook-block drift detection (#881).
+ *
+ * Hashes the consumer's `.claude/settings.json` `hooks` block and the
+ * reference hook block that `generateHooksConfig()` would produce for the
+ * current moflo version.  When the hashes differ, the session-start launcher
+ * surfaces the diff (or, in `regenerate` mode, adds purely-additive missing
+ * hooks).  This is the broader complement to the per-bug `repairHookWiring`
+ * and `rewriteIncorrectHookWiring` rules — it catches drift in any direction,
+ * including future hook events we haven't shipped yet.
+ *
+ * IMPORTANT: This module must remain self-contained with ZERO imports from
+ * other moflo modules (mirrors the constraint on `services/hook-wiring.ts`).
+ * It is dynamically imported at runtime by `bin/session-start-launcher.mjs`
+ * in consumer projects, where transitive dependencies may not resolve.
+ *
+ * The reference hook block is duplicated from `init/settings-generator.ts`
+ * on purpose — the launcher cannot pull in `init/types.js` at runtime, and a
+ * unit test (`hook-block-hash.test.ts`) asserts the two stay in sync.
+ */
+import { createHash } from 'crypto';
+export const DRIFT_MODES = ['warn', 'regenerate', 'off'];
+// ────────────────────────────────────────────────────────────────────────────
+// Reference hook block — kept in sync with init/settings-generator.ts
+// ────────────────────────────────────────────────────────────────────────────
+const HELPERS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/helpers';
+const SCRIPTS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/scripts';
+/** Build a `node "<helper> <subcommand>"` hook entry. */
+const helperHook = (helper, sub, timeout) => ({
+    type: 'command',
+    command: `node "${HELPERS_PREFIX}/${helper}"${sub ? ` ${sub}` : ''}`,
+    timeout,
+});
+/** Build a `node "<scripts/file>"` hook entry (no subcommand). */
+const scriptHook = (file, timeout) => ({
+    type: 'command',
+    command: `node "${SCRIPTS_PREFIX}/${file}"`,
+    timeout,
+});
+const gateHook = (sub, timeout) => helperHook('gate-hook.mjs', sub, timeout);
+const gateCjs = (sub, timeout) => helperHook('gate.cjs', sub, timeout);
+const handler = (sub, timeout) => helperHook('hook-handler.cjs', sub, timeout);
+const autoMemory = (sub, timeout) => helperHook('auto-memory-hook.mjs', sub, timeout);
+/**
+ * Build the reference hook block — the canonical block `generateHooksConfig()`
+ * produces with all hook flags enabled (the default for `flo init`).
+ *
+ * If you change `generateHooksConfig()` in `init/settings-generator.ts`, also
+ * change this function — and the unit test `getReferenceHookBlock matches
+ * generateHooksConfig` will fail until the two agree.
+ */
+export function getReferenceHookBlock() {
+    return {
+        PreToolUse: [
+            { matcher: '^(Write|Edit|MultiEdit)$', hooks: [handler('post-edit', 5000)] },
+            { matcher: '^(Glob|Grep)$', hooks: [gateHook('check-before-scan', 3000)] },
+            { matcher: '^Read$', hooks: [gateHook('check-before-read', 3000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-dangerous-command', 2000), gateHook('check-before-pr', 2000)],
+            },
+        ],
+        PostToolUse: [
+            {
+                matcher: '^(Write|Edit|MultiEdit)$',
+                hooks: [handler('post-edit', 5000), gateHook('reset-edit-gates', 2000)],
+            },
+            { matcher: '^Agent$', hooks: [handler('post-task', 5000)] },
+            { matcher: '^TaskCreate$', hooks: [gateCjs('record-task-created', 2000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-bash-memory', 2000), gateHook('record-test-run', 2000)],
+            },
+            { matcher: '^Skill$', hooks: [gateHook('record-skill-run', 2000)] },
+            { matcher: 'mcp__moflo__memory_', hooks: [gateHook('record-memory-searched', 3000)] },
+            { matcher: '^TaskUpdate$', hooks: [gateCjs('check-task-transition', 2000)] },
+            { matcher: '^mcp__moflo__memory_store$', hooks: [gateCjs('record-learnings-stored', 2000)] },
+        ],
+        UserPromptSubmit: [
+            { hooks: [helperHook('prompt-hook.mjs', '', 3000)] },
+            { hooks: [gateHook('prompt-reminder', 3000)] },
+        ],
+        SubagentStart: [
+            { hooks: [helperHook('subagent-start.cjs', '', 2000)] },
+        ],
+        SessionStart: [
+            {
+                hooks: [scriptHook('session-start-launcher.mjs', 3000), autoMemory('import', 8000)],
+            },
+        ],
+        Stop: [
+            { hooks: [handler('session-end', 5000), autoMemory('sync', 10000)] },
+        ],
+        PreCompact: [
+            { hooks: [gateCjs('compact-guidance', 3000)] },
+        ],
+        Notification: [
+            { hooks: [handler('notification', 3000)] },
+        ],
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Normalisation + hashing
+// ────────────────────────────────────────────────────────────────────────────
+function normaliseHookEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.command !== 'string')
+        return null;
+    return {
+        type: typeof r.type === 'string' ? r.type : 'command',
+        command: r.command.replace(/\s+/g, ' ').trim(),
+        timeout: typeof r.timeout === 'number' && isFinite(r.timeout) ? r.timeout : 0,
+    };
+}
+function normaliseHookBlock(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const hooksIn = Array.isArray(r.hooks) ? r.hooks : [];
+    const hooks = hooksIn.map(normaliseHookEntry).filter((h) => h !== null);
+    if (hooks.length === 0)
+        return null;
+    hooks.sort((a, b) => a.command.localeCompare(b.command));
+    const out = { hooks };
+    if (typeof r.matcher === 'string' && r.matcher.length > 0)
+        out.matcher = r.matcher;
+    return out;
+}
+/**
+ * Produce a stable, sorted view of a hook tree suitable for hashing or diffing.
+ * Drops unknown keys, coerces missing fields to defaults, and sorts events,
+ * matchers, and commands so semantically-equal trees compare equal.
+ */
+export function normaliseHooks(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const events = raw;
+    const out = {};
+    const eventNames = Object.keys(events).sort();
+    for (const event of eventNames) {
+        const arr = events[event];
+        if (!Array.isArray(arr))
+            continue;
+        const blocks = arr
+            .map(normaliseHookBlock)
+            .filter((b) => b !== null);
+        if (blocks.length === 0)
+            continue;
+        blocks.sort((a, b) => {
+            const am = a.matcher ?? '';
+            const bm = b.matcher ?? '';
+            if (am !== bm)
+                return am.localeCompare(bm);
+            return (a.hooks[0]?.command ?? '').localeCompare(b.hooks[0]?.command ?? '');
+        });
+        out[event] = blocks;
+    }
+    return out;
+}
+function hashNormalised(tree) {
+    return createHash('sha256').update(JSON.stringify(tree)).digest('hex').slice(0, 16);
+}
+/**
+ * Hash a hook tree.  Stable across runs (deterministic normalisation), and
+ * insensitive to key order, whitespace inside commands, or matcher block
+ * grouping.  Returns a 16-char hex prefix of sha256 — long enough to make
+ * collisions a non-concern for the small space of valid hook trees while
+ * staying readable in launcher output.
+ */
+export function computeHookBlockHash(raw) {
+    return hashNormalised(normaliseHooks(raw));
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Diff
+// ────────────────────────────────────────────────────────────────────────────
+function entryKey(event, matcher, command) {
+    return `${event} ${matcher} ${command}`;
+}
+function flatten(tree) {
+    const out = new Map();
+    for (const event of Object.keys(tree)) {
+        for (const block of tree[event]) {
+            const matcher = block.matcher ?? '';
+            for (const hook of block.hooks) {
+                const entry = { event, matcher, command: hook.command };
+                out.set(entryKey(event, matcher, hook.command), entry);
+            }
+        }
+    }
+    return out;
+}
+let cachedReference = null;
+function getCachedReference() {
+    if (!cachedReference) {
+        const tree = getReferenceHookBlock();
+        const normalised = normaliseHooks(tree);
+        cachedReference = { tree, normalised, hash: hashNormalised(normalised), flat: flatten(normalised) };
+    }
+    return cachedReference;
+}
+/**
+ * Compare a consumer hook block against the reference and report what's
+ * missing / extra.  Pass an explicit `referenceHooks` to test against a
+ * frozen reference (used by tests); omit it to use the current moflo
+ * reference from `getReferenceHookBlock()` (memoised — built once per process).
+ */
+export function computeHookBlockDrift(consumerHooks, referenceHooks) {
+    const consumerNormalised = normaliseHooks(consumerHooks);
+    const consumerHash = hashNormalised(consumerNormalised);
+    const consumerFlat = flatten(consumerNormalised);
+    let referenceHash;
+    let referenceFlat;
+    if (referenceHooks === undefined) {
+        const ref = getCachedReference();
+        referenceHash = ref.hash;
+        referenceFlat = ref.flat;
+    }
+    else {
+        const refNormalised = normaliseHooks(referenceHooks);
+        referenceHash = hashNormalised(refNormalised);
+        referenceFlat = flatten(refNormalised);
+    }
+    const missing = [];
+    for (const [k, v] of referenceFlat) {
+        if (!consumerFlat.has(k))
+            missing.push(v);
+    }
+    const extra = [];
+    for (const [k, v] of consumerFlat) {
+        if (!referenceFlat.has(k))
+            extra.push(v);
+    }
+    return {
+        consumerHash,
+        referenceHash,
+        drifted: consumerHash !== referenceHash,
+        missing,
+        extra,
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Settings.json helpers — shared between launcher + doctor
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * True when the user has set `claudeFlow.hooks.locked: true` in their
+ * settings.json — a sentinel that suppresses drift surfacing entirely.
+ */
+export function isHookBlockLocked(settings) {
+    const root = settings;
+    const cf = root?.claudeFlow;
+    const hooks = cf?.hooks;
+    return hooks?.locked === true;
+}
+/**
+ * Additively repair drift: for every entry in `report.missing`, locate the
+ * corresponding hook in the reference block and graft it into the consumer's
+ * settings.  Only safe when `report.extra.length === 0` — otherwise the
+ * caller should fall back to `warn` mode to avoid clobbering customisations.
+ *
+ * Mutates `settings` in place; caller is responsible for writing the file.
+ */
+export function applyAdditiveRegeneration(settings, report) {
+    if (report.missing.length === 0)
+        return { settings, added: 0 };
+    const ref = getCachedReference().tree;
+    const hooks = (settings.hooks ?? {});
+    let added = 0;
+    for (const miss of report.missing) {
+        const arr = Array.isArray(hooks[miss.event]) ? hooks[miss.event] : [];
+        let block = arr.find(b => (b?.matcher ?? '') === miss.matcher);
+        if (!block) {
+            block = { hooks: [] };
+            if (miss.matcher)
+                block.matcher = miss.matcher;
+            arr.push(block);
+        }
+        if (!Array.isArray(block.hooks))
+            block.hooks = [];
+        const refArr = ref[miss.event] ?? [];
+        const refBlock = refArr.find(b => (b?.matcher ?? '') === miss.matcher);
+        const refHook = refBlock?.hooks.find(h => h.command === miss.command);
+        if (refHook && !block.hooks.some(h => h?.command === miss.command)) {
+            block.hooks.push(refHook);
+            added++;
+        }
+        hooks[miss.event] = arr;
+    }
+    if (added > 0)
+        settings.hooks = hooks;
+    return { settings, added };
+}
+/**
+ * Format a drift report for human-readable output (multi-line, no colour).
+ * Used by `flo doctor` and the session-start launcher's stdout summary.
+ */
+export function formatDriftReport(report) {
+    if (!report.drifted) {
+        return `hook block matches reference (${report.consumerHash})`;
+    }
+    const lines = [];
+    lines.push(`hook block drift detected (consumer ${report.consumerHash} vs reference ${report.referenceHash})`);
+    if (report.missing.length > 0) {
+        lines.push(`  ${report.missing.length} missing:`);
+        for (const m of report.missing) {
+            const m2 = m.matcher ? ` ${m.matcher}` : '';
+            lines.push(`    - ${m.event}${m2}: ${m.command}`);
+        }
+    }
+    if (report.extra.length > 0) {
+        lines.push(`  ${report.extra.length} extra (likely customisations):`);
+        for (const e of report.extra) {
+            const m2 = e.matcher ? ` ${e.matcher}` : '';
+            lines.push(`    + ${e.event}${m2}: ${e.command}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=hook-block-hash.js.map

package/dist/src/cli/services/index.js

@@ -15,6 +15,8 @@ export { AgentRouter, getAgentRouter, routeTask, AGENT_CAPABILITIES, } from './a
 export { startDashboard, createDashboardMemoryAccessor, DEFAULT_DASHBOARD_PORT, } from './daemon-dashboard.js';
 // Hook Wiring (shared between doctor, upgrade, and session-start)
 export { repairHookWiring, HOOK_ENTRY_MAP, REQUIRED_HOOK_WIRING, } from './hook-wiring.js';
+// Hook Block Drift Detection (#881 — hash-based reconciliation)
+export { computeHookBlockHash, computeHookBlockDrift, formatDriftReport, getReferenceHookBlock, normaliseHooks, isHookBlockLocked, applyAdditiveRegeneration, DRIFT_MODES, } from './hook-block-hash.js';
 // Subagent Bootstrap Directive (single-source for SubagentStart + agent_spawn surfaces)
 export { SUBAGENT_BOOTSTRAP_DIRECTIVE } from './subagent-bootstrap.js';
 //# sourceMappingURL=index.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.11';
+export const VERSION = '4.9.12';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.11",
+  "version": "4.9.12",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -81,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.10",
+    "moflo": "^4.9.11",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"