moflo 4.9.10 → 4.9.12

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/.claude/skills/spell-builder/SKILL.md

@@ -356,7 +356,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **Runtime source:** `src/cli/spells/commands/` — each step is a TypeScript file registered in `index.ts`.
 
-**Adding a new step:** Create a directory under `steps/<name>/` with a `README.md`. Follow `.claude/guidance/internal/guidance-rules.md` and use existing step READMEs as templates. The step command source goes in `src/cli/spells/commands/` and is registered in `index.ts`. No changes to this SKILL.md needed.
+**Adding a new step:** Create a directory under `steps/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing step READMEs as templates. The step command source goes in `src/cli/spells/commands/` and is registered in `index.ts`. No changes to this SKILL.md needed.
 
 ### Connectors
 
@@ -371,7 +371,7 @@ Write the updated YAML back to the original file (or a new path if requested).
 
 **Runtime source:** `src/cli/spells/connectors/` — each connector is a TypeScript file registered in `index.ts`.
 
-**Adding a new connector:** Create a directory under `connectors/<name>/` with a `README.md`. Follow `.claude/guidance/internal/guidance-rules.md` and use existing connector READMEs as templates. The connector source goes in `src/cli/spells/connectors/` and is registered in `index.ts`. No changes to this SKILL.md needed.
+**Adding a new connector:** Create a directory under `connectors/<name>/` with a `README.md`. Follow `.claude/guidance/shipped/moflo-guidance-rules.md` and use existing connector READMEs as templates. The connector source goes in `src/cli/spells/connectors/` and is registered in `index.ts`. No changes to this SKILL.md needed.
 
 **When to create a new connector vs composing existing ones:** See [architecture.md](architecture.md) for the decision tree.
 

package/.claude/skills/spell-builder/architecture.md

@@ -153,7 +153,7 @@ steps:
 
 ## Documentation Rules for New Components
 
-**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/internal/guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
+**Every new step, connector, or spell MUST include a README.md.** Apply the rules in `.claude/guidance/shipped/moflo-guidance-rules.md` automatically — do not wait for the user to ask. Use existing READMEs in `steps/` and `connectors/` as templates.
 
 **Where to put the README:**
 - Steps: `.claude/skills/spell-builder/steps/<name>/README.md`

package/.claude/skills/spell-schedule/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: spell-schedule
+description: |
+  Schedule a moflo spell to run on the local machine via the moflo daemon (cron, interval, or one-time).
+  Use when the user wants to schedule, automate, or recurringly run one of THEIR spells locally —
+  e.g. "schedule the oap spell every hour", "run my audit spell every weekday at 9am", "fire X once tomorrow morning".
+  This is the LOCAL daemon path. For remote Anthropic-cloud agents, use /schedule instead.
+arguments: "[spell-name-or-alias]"
+---
+
+# /spell-schedule — Schedule a Local Spell
+
+This skill walks the user through scheduling a moflo spell on the **local** moflo daemon.
+Schedules live in moflo's memory store and are evaluated once per minute by the daemon's poll loop.
+Execution goes through the same engine path as `flo spell cast`.
+
+> Not the same as `/schedule`. `/schedule` creates **remote** Anthropic-cloud routines; this skill drives the **local** daemon scheduler.
+
+**Arguments:** `$ARGUMENTS` (optional spell name/alias to pre-select)
+
+## When to use
+
+The user says any of:
+- "schedule the X spell"
+- "run X every <interval>"
+- "fire X once at <time>"
+- "set up a recurring run for X"
+- "I want X to run every morning"
+
+If the user wants a **cloud** agent (mentions "remote", "GitHub Actions", "Anthropic cloud", or specifies a repo to clone), redirect them to `/schedule`.
+
+## Workflow
+
+### Step 1 — Verify the daemon is running
+
+```bash
+npx flo doctor 2>&1 | grep -i daemon
+```
+
+If the daemon is not running, prompt the user:
+- "The moflo daemon isn't running. Schedules only fire while the daemon is up. Start it now?"
+- If yes: `npx flo daemon start` (or instruct them to enable OS autostart for survival across reboots).
+- If they decline, warn the user that the schedule will be created but won't fire until the daemon is started.
+
+### Step 2 — Identify the target spell
+
+If `$ARGUMENTS` was provided, use it as the spell name/alias. Otherwise, list spells and let the user pick:
+
+```bash
+npx flo spell list 2>&1
+```
+
+The output is a markdown table with columns: name, alias, description, source. Both `name` and `alias` are valid for `flo spell schedule create -n <value>` — prefer the full name to avoid alias conflicts.
+
+If the user-named spell is not in the list, stop and ask. Do NOT silently create a schedule for a missing spell — it will be auto-disabled on first fire.
+
+### Step 3 — Pick the cadence
+
+Use AskUserQuestion to offer four options:
+
+| Option | When to suggest | CLI form |
+|--------|-----------------|----------|
+| **Cron** | Specific time of day, day of week, or month boundary | `--cron "<5-field cron>"` (UTC, 5 fields: minute hour day-of-month month day-of-week) |
+| **Interval** | "Every N seconds/minutes/hours/days" with no specific clock anchor | `--interval <N><s\|m\|h\|d>` (e.g., `30m`, `6h`, `1d`) |
+| **One-time** | "Run once at..." or "remind me to..." | `--at <ISO 8601 datetime>` |
+| **Embedded in spell** | The schedule should travel with the spell definition (registered every daemon start) | Edit the spell YAML to add a `schedule:` block; no CLI |
+
+#### Timezone conversion (CRITICAL)
+
+Cron expressions and `--at` timestamps are **always UTC**. The user almost always means their local time.
+
+1. **Look up the user's timezone** — derive from system. On Windows, `[System.TimeZoneInfo]::Local.Id` or read the auto-memory `currentDate` block. **Never** guess.
+2. **Convert to UTC** explicitly using PowerShell (cross-platform-safe):
+   ```powershell
+   [System.TimeZoneInfo]::ConvertTimeToUtc((Get-Date "9:00am"), [System.TimeZoneInfo]::Local)
+   ```
+3. **Echo back the conversion**: "9am America/Guatemala = 15:00 UTC, so the cron would be `0 15 * * 1-5`. Confirm?"
+4. **Re-check current time before any `--at`** — long conversations drift. Run `date -u +%Y-%m-%dT%H:%M:%SZ` (or PowerShell equivalent) before computing the absolute timestamp. If the resolved time is in the past, ask for clarification — do not silently roll forward.
+
+#### Constraints
+
+- Minimum poll interval is 1 minute (the daemon polls once per `pollIntervalMs`, default 60000). Sub-minute schedules are rejected.
+- Interval units: `s`, `m`, `h`, `d` ONLY. `--interval 1w` is rejected at load time.
+- `--at` must be a valid ISO 8601 datetime in the future.
+- Exactly one of `--cron`, `--interval`, `--at` per schedule.
+
+### Step 4 — Confirm and create
+
+Show the full plan to the user before creating:
+
+```
+Spell:    outlook-attachment-processor (alias: oap)
+Cadence:  every weekday at 9am America/Guatemala (15:00 UTC)
+Cron:     0 15 * * 1-5
+Daemon:   running ✓
+```
+
+After user confirms, run:
+
+```bash
+npx flo spell schedule create -n <spell-name> --cron "<cron>" 2>&1
+# or --interval <value>
+# or --at <iso-datetime>
+```
+
+Capture the schedule ID from output and surface it to the user along with the next computed run time.
+
+### Step 5 — Verify the wiring
+
+Tail the schedule executions for the first fire so the user can confirm the daemon actually picks it up:
+
+```bash
+npx flo spell schedule list 2>&1
+```
+
+If the user wants to wait for the first fire (interval ≤ 5m), poll `flo spell schedule list` or the daemon dashboard. Otherwise, summarize and exit:
+
+```
+Scheduled: <schedule-id>
+Next run:  <ISO datetime UTC> (<local-equivalent>)
+Cancel:    npx flo spell schedule cancel <schedule-id>
+```
+
+## Sub-actions (when not creating)
+
+If the user asks to **list** schedules:
+```bash
+npx flo spell schedule list 2>&1
+```
+
+If the user asks to **cancel** a schedule:
+1. Run `flo spell schedule list` and let them pick.
+2. `npx flo spell schedule cancel <schedule-id>`.
+3. Confirm the entry is gone from the list.
+
+If the user asks to **run now** without altering the cadence:
+- Use the dashboard's "Run now" button if available, or the daemon's `runScheduleNow` API.
+- The CLI does not currently expose this — surface that limitation if asked, and offer `flo spell cast -n <name>` as a manual alternative.
+
+## Important — gotchas
+
+- **Daemon prerequisite**: schedules only fire while the daemon is running. Tell the user this explicitly. For survival across reboots, `flo daemon install` registers the OS-level autostart service.
+- **Catch-up window** (default 1h, `scheduler.catchUpWindowMs` in `moflo.yaml`): if the daemon was offline when a run was due, runs within the window still fire on the next poll. Older missed runs are skipped with a `schedule:skipped` event.
+- **maxConcurrent** (default 2): caps the number of scheduled spells running concurrently. Same-schedule overlap is never allowed.
+- **No update CLI yet**: `flo spell schedule` exposes create/list/cancel only. To change a cadence, cancel + recreate.
+- **Spell-required sandboxing** (#878): when that ships, scheduled runs honor it just like manual casts — a missing sandbox skips the run with a `schedule:skipped` event.
+
+## Output
+
+End the session with a single-block summary:
+
+```
+Schedule Created
+────────────────
+Spell:       <name>
+Cadence:     <human-readable>
+Cron/At:     <UTC expression>
+ID:          <schedule-id>
+Next run:    <UTC + local>
+Cancel:      npx flo spell schedule cancel <id>
+Daemon:      running | needs-start
+```
+
+## Reference
+
+- Full daemon scheduler docs: https://github.com/eric-cielo/moflo/blob/main/docs/SPELLS.md#scheduling
+- Tracking issue: https://github.com/eric-cielo/moflo/issues/877

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
@@ -838,8 +846,11 @@ try {
       settingsChanges.push('added statusLine');
     }
 
-    // 3a-iv. Repair missing required hook wirings (same logic as doctor --fix
-    // and moflo upgrade — shared via hook-wiring.js to stay DRY)
+    // 3a-iv. Repair missing required hook wirings AND rewrite known-bad
+    // wirings from older moflo versions (#879 — record-memory-searched
+    // wired to gate.cjs directly skips session_id forwarding and deadlocks
+    // the per-actor gate). Both passes share hook-wiring.js so doctor --fix,
+    // upgrade-merge, and the launcher stay DRY.
     try {
       const hwPaths = [
         resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/hook-wiring.js'),
@@ -847,11 +858,21 @@ try {
       ];
       const hwPath = hwPaths.find(p => existsSync(p));
       if (hwPath) {
-        const { repairHookWiring } = await import(`file://${hwPath.replace(/\\/g, '/')}`);
-        const { repaired } = repairHookWiring(settings);
-        if (repaired.length > 0) {
-          dirty = true;
-          settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
+        const mod = await import(`file://${hwPath.replace(/\\/g, '/')}`);
+        if (typeof mod.rewriteIncorrectHookWiring === 'function') {
+          const { rewrites } = mod.rewriteIncorrectHookWiring(settings);
+          if (rewrites.length > 0) {
+            dirty = true;
+            const total = rewrites.reduce((n, r) => n + r.count, 0);
+            settingsChanges.push(`rewrote ${plural(total, 'stale hook wiring')}`);
+          }
+        }
+        if (typeof mod.repairHookWiring === 'function') {
+          const { repaired } = mod.repairHookWiring(settings);
+          if (repaired.length > 0) {
+            dirty = true;
+            settingsChanges.push(`repaired ${plural(repaired.length, 'hook wiring')}`);
+          }
         }
       }
     } catch (err) {
@@ -868,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/