moflo 4.10.26 → 4.10.28

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -117,7 +117,7 @@ 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
+  hook_block_drift: regenerate           # warn | regenerate | off (default: regenerate since #1227)
   claudemd_injection_drift: regenerate   # warn | regenerate | off
 ```
 
@@ -150,7 +150,8 @@ If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are
 | `sandbox.tier: full` | Require OS sandbox; throw at runtime if the platform tool is unavailable |
 | `sandbox.tier: denylist-only` | Keep Layer 1 denylist only; skip OS isolation even when enabled |
 | `auto_update.enabled: false` | Disable all on-session auto-sync (scripts, helpers, drift checks) |
-| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (#881) |
+| `auto_update.hook_block_drift: regenerate` | Auto-repair drift in `.claude/settings.json` hook block on session start (#881, default since #1227 — basename guard from #1180 keeps user-owned hooks safe). |
+| `auto_update.hook_block_drift: warn` | Print drift notice but leave settings.json unchanged. Opt-out from auto-regen. |
 | `auto_update.hook_block_drift: off` | Skip hook-block drift detection entirely |
 | `auto_update.claudemd_injection_drift: regenerate` | Auto-refresh the MoFlo block in `CLAUDE.md` when it drifts from the current generator (#1142, default) |
 | `auto_update.claudemd_injection_drift: warn` | Print a drift notice on session start but leave `CLAUDE.md` unchanged |

package/.claude/skills/publish/SKILL.md

@@ -229,9 +229,15 @@ Confirm the published version matches what we just built.
 
 ```bash
 npm install moflo@<new-version> --save-dev
+npm install --package-lock-only --force
+npm ci --dry-run --legacy-peer-deps
 ```
 
-This updates `package.json` and `package-lock.json` to use the newly published version as a devDependency.
+The first command updates `package.json` and `package-lock.json` to use the newly published version as a devDependency.
+
+The second command (`--package-lock-only --force`) backfills cross-platform optional-dependency entries that npm omits from the lockfile when `npm install` runs on a single host platform. Without it, transitive optional deps like the nested `@rolldown/binding-wasm32-wasi/node_modules/@emnapi/*` entries get dropped when publishing from Windows, and the resulting lockfile fails `npm ci` on Ubuntu/macOS CI legs. This produced the green-`release-smoke` → red-`ci.yml` divergence in run `26487580745` (moflo@4.10.27 install commit).
+
+The final `npm ci --dry-run --legacy-peer-deps` proves the resulting lockfile is in sync with `package.json` before we commit it. If this exits non-zero, stop and investigate — do not commit a broken lockfile.
 
 ### Step 13: Final Commit
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024-2026 ruvnet
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024-2026 ruvnet
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -120,6 +120,14 @@ To force a clean re-initialization over an existing setup:
 flo init --force
 ```
 
+#### First-run heads-up: brief CPU spike during initial indexing
+
+The **very first time** MoFlo runs in your project — typically right after `flo init` and the next session start — it builds the initial guidance, code map, and test indexes from scratch and generates 384-dim embeddings for every chunk. On a medium-sized project this takes **one to a few minutes** and you may see elevated CPU during that window. It runs in the background, so you can start working immediately; you just might hear your fans for a bit.
+
+After that first pass, indexing is **incremental and lazy** — every subsequent session start only re-processes files that actually changed since the last run, which typically finishes in under a second with no perceptible CPU activity. The big one-time cost is a deliberate trade: pay it once, then every future session opens with your project already searchable by meaning.
+
+> **Tip:** Let that initial indexing finish before running **`/healer`** (or `flo healer`). Healer's embeddings and semantic-quality checks expect the indexes to exist — if you run it mid-build it may flag warnings that resolve themselves the moment indexing completes.
+
 ### 2. Review your guidance and code settings
 
 Open `moflo.yaml` to see what init detected. The two key sections:

package/bin/session-start-launcher.mjs

@@ -812,7 +812,18 @@ let autoUpdateConfig = {
   enabled: true,
   scripts: true,
   helpers: true,
-  hookBlockDrift: 'warn',
+  // #1227 — default flipped from 'warn' → 'regenerate'. After #1180 added the
+  // basename guard in applyWholesaleRegeneration, the wholesale path stopped
+  // clobbering user-owned entries (commands not pointing at moflo helpers are
+  // grafted back into the fresh tree). The only thing left to "lose" is stale
+  // moflo entries from prior versions — exactly what consumers WANT migrated.
+  // The 'warn' default was a holdover from the pre-#1180 era when the wipe
+  // wasn't safe; that rationale no longer applies, and the launcher silently
+  // leaving legacy shapes in place was the root of #1227's surprise deletions
+  // (`flo init`'s wholesale-wipe path tripped where the launcher's safe wipe
+  // hadn't run because of the warn default). Consumers who explicitly want
+  // warn-only can still set `auto_update.hook_block_drift: warn` in moflo.yaml.
+  hookBlockDrift: 'regenerate',
   // #1142 — CLAUDE.md injection drift refresh mode (warn | regenerate | off,
   // default regenerate). Defaults to regenerate because the consumer cannot
   // refresh CLAUDE.md on their own — there is no other auto-refresh path.
@@ -826,7 +837,10 @@ 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)
+    // #881: hook-block drift detector (warn | regenerate | off; default
+    // regenerate post-#1227 — the basename guard from #1180 made wholesale
+    // regen safe for user-owned hooks, so the prior 'warn' default just left
+    // legacy shapes in place for `flo init` to wipe non-safely.)
     const driftMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+hook_block_drift:\s*(warn|regenerate|off)/);
     // #1142: CLAUDE.md injection drift detector (warn | regenerate | off; default regenerate)
     const claudemdMatch = yamlContent.match(/auto_update:\s*\n(?:\s+\w+:.*\n)*?\s+claudemd_injection_drift:\s*(warn|regenerate|off)/);

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

@@ -673,6 +673,58 @@ export async function checkMofloYamlCompliance(cwd = process.cwd()) {
         fix: 'Restart Claude Code (yaml-upgrader auto-appends) or `npx moflo init --force`',
     };
 }
+/**
+ * #1229 — standing tripwire for a silently-disabled memory_first gate.
+ *
+ * `gates.memory_first` is the only enforcement of the memory-search-first
+ * protocol. When it is `false` in moflo.yaml the protocol is off repo-wide
+ * with no per-prompt signal — and because the disabled gate is itself what
+ * surfaces the stored "never disable memory_first" learning, the situation
+ * self-conceals. Historically a daemon-spawned headless analysis worker could
+ * write this value unprompted to unblock itself (the `optimize` worker editing
+ * `moflo.yaml` to `memory_first: false  # Temporarily disabled for performance
+ * analysis`); that root cause is fixed by making those workers read-only, but
+ * this check is the loud, standing detector so the state never goes unnoticed
+ * again — whatever writes it (worker, agent, or a deliberate consumer edit).
+ *
+ * Warn rather than fail: disabling the gate is a legitimate (if rare) choice;
+ * the point is that it can never be silent. Matches only an *active* (un-
+ * commented) `memory_first: false` line and is EOL-agnostic so it behaves
+ * identically on CRLF (Windows) and LF (POSIX) checkouts.
+ *
+ * Exported with a cwd param so tests can target a temp root without touching
+ * process.cwd().
+ */
+export async function checkMemoryFirstGate(cwd = process.cwd()) {
+    const yamlPath = join(cwd, 'moflo.yaml');
+    // Absence is covered by checkMofloYamlCompliance; with no file the gate
+    // defaults to enabled, so there is nothing to warn about here.
+    if (!existsSync(yamlPath)) {
+        return { name: 'Memory-First Gate', status: 'pass', message: 'Enabled (default — no moflo.yaml override)' };
+    }
+    let content;
+    try {
+        content = readFileSync(yamlPath, 'utf-8');
+    }
+    catch (e) {
+        return { name: 'Memory-First Gate', status: 'warn', message: `Unable to read moflo.yaml: ${errorDetail(e)}` };
+    }
+    // Active value only: a line whose first non-whitespace token is
+    // `memory_first: false`. A commented `# memory_first: false` is ignored
+    // because the leading `#` defeats the `^\s*memory_first` anchor.
+    const disabled = content
+        .split(/\r?\n/)
+        .some((line) => /^\s*memory_first:\s*false\b/i.test(line));
+    if (disabled) {
+        return {
+            name: 'Memory-First Gate',
+            status: 'warn',
+            message: 'DISABLED in moflo.yaml — memory-search-first protocol is off repo-wide and silent per-prompt',
+            fix: 'Restore `gates.memory_first: true` (e.g. `git checkout -- moflo.yaml`) unless you disabled it deliberately',
+        };
+    }
+    return { name: 'Memory-First Gate', status: 'pass', message: 'Enabled' };
+}
 /**
  * #981 / #987 — surfaces the single-writer-architecture safety net.
  *

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

@@ -667,7 +667,7 @@ export async function checkHookBlockDrift() {
         name: 'Hook Block Drift',
         status: 'warn',
         message: parts.join(', '),
-        fix: 'set auto_update.hook_block_drift: regenerate in moflo.yaml, or moflo.hooks.locked: true to suppress',
+        fix: 'session-start auto-regenerates by default (#1227); next Claude Code start should heal this. If it persists, ensure `auto_update.hook_block_drift` is not set to `warn`/`off` in moflo.yaml, or set `moflo.hooks.locked: true` to suppress.',
     };
 }
 // ============================================================================

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

@@ -12,7 +12,7 @@ import { checkWritersAudit } from './doctor-checks-writers-audit.js';
 import { checkSwarmFunctional, checkHiveMindFunctional, } from './doctor-checks-swarm.js';
 import { checkMemoryAccessFunctional } from './doctor-checks-memory-access.js';
 import { checkBuildTools, checkClaudeCode, checkDiskSpace, checkGit, checkGitRepo, checkNodeVersion, checkNpmVersion, } from './doctor-checks-runtime.js';
-import { checkConfigFile, checkDaemonIdentity, checkDaemonOrphan, checkDaemonStatus, checkDaemonWriteRouting, checkMcpServers, checkMemoryDatabase, checkMemoryDbIntegrity, checkMofloYamlCompliance, checkNestedMofloIslands, checkStatusLine, checkSwarmResidue, checkTestDirs, } from './doctor-checks-config.js';
+import { checkConfigFile, checkDaemonIdentity, checkDaemonOrphan, checkDaemonStatus, checkDaemonWriteRouting, checkMcpServers, checkMemoryDatabase, checkMemoryDbIntegrity, checkMemoryFirstGate, checkMofloYamlCompliance, checkNestedMofloIslands, checkStatusLine, checkSwarmResidue, checkTestDirs, } from './doctor-checks-config.js';
 import { checkSpellEngine, checkSandboxTier } from './doctor-checks-platform.js';
 import { checkEmbeddings, checkSemanticQuality, } from './doctor-checks-memory.js';
 import { checkIntelligence } from './doctor-checks-intelligence.js';
@@ -34,6 +34,8 @@ export const allChecks = [
     checkGitRepo,
     checkConfigFile,
     checkMofloYamlCompliance,
+    // #1229 — loud tripwire for a silently-disabled memory_first gate.
+    checkMemoryFirstGate,
     checkStatusLine,
     checkDaemonStatus,
     checkDaemonVersionSkew,
@@ -97,6 +99,8 @@ export const componentMap = {
     'config': checkConfigFile,
     'yaml': checkMofloYamlCompliance,
     'moflo-yaml': checkMofloYamlCompliance,
+    'memory-first': checkMemoryFirstGate,
+    'memory-gate': checkMemoryFirstGate,
     'statusline': checkStatusLine,
     'status-line': checkStatusLine,
     'daemon': checkDaemonStatus,

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

@@ -19,6 +19,9 @@ import { generateClaudeMd as generateMofloSection } from './claudemd-generator.j
 import { applyInjectionReplacement } from '../services/claudemd-injection.js';
 import { loadShippedScripts } from './shipped-scripts.js';
 import { DEFAULT_INIT_OPTIONS } from './types.js';
+import { generateSettings } from './settings-generator.js';
+import { applyWholesaleRegeneration, computeHookBlockDrift, isHookBlockLocked, } from '../services/hook-block-hash.js';
+import { rewriteIncorrectHookWiring } from '../services/hook-wiring.js';
 export { discoverTestDirs };
 // ============================================================================
 // Init
@@ -180,176 +183,107 @@ function generateConfig(root, force, answers) {
 // ============================================================================
 // Step 2: .claude/settings.json hooks
 // ============================================================================
-function generateHooks(root, force, answers) {
+// #1227 — `flo init` was the surgical patcher that silently nuked user-owned
+// hooks (project-analysis-gate.cjs, e2e-gate.cjs) AND moflo entries in legacy
+// slots (swarm_init/hive-mind_init in PreToolUse, auto-memory-hook in SessionEnd).
+// The old generateHooks had three structural defects:
+//   (1) Its "already configured" guard scanned for the literal substring
+//       `'flo gate'` / `'moflo gate'` — modern moflo commands are
+//       `node ".../helpers/gate.cjs ..."` so the substring NEVER matched and
+//       the guard always fell through to the wipe path.
+//   (2) `existing.hooks = hooks` was a wholesale overwrite — the comment claimed
+//       "preserve existing non-MoFlo hooks" but the code did the opposite.
+//   (3) Its inlined canonical block had drifted from settings-generator.ts /
+//       hook-block-hash.ts (no swarm_init, no hive-mind_init, no Stop
+//       auto-memory-hook, SessionStart launcher timeout 3000 not 5000).
+//
+// New shape: one canonical source. For missing settings.json, write
+// generateSettings(DEFAULT_INIT_OPTIONS). For existing, run the same wholesale
+// regen the session-start launcher uses — applyWholesaleRegeneration preserves
+// user-owned entries via the #1180 basename guard AND relocates moflo entries
+// from legacy slots (SessionEnd → Stop, PreToolUse swarm_init → PostToolUse,
+// etc.). rewriteIncorrectHookWiring runs first so command-string rewrites
+// (#879 / #931) are healed before the structural pass hashes the block.
+function generateHooks(root, force, _answers) {
     const settingsPath = path.join(root, '.claude', 'settings.json');
     const settingsDir = path.dirname(settingsPath);
     if (!fs.existsSync(settingsDir)) {
         fs.mkdirSync(settingsDir, { recursive: true });
     }
-    let existing = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            existing = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-        }
-        catch { /* start fresh */ }
-        // Check if MoFlo hooks already set up
-        const settingsStr = JSON.stringify(existing);
-        const hasGateHooks = settingsStr.includes('flo gate') || settingsStr.includes('moflo gate');
-        if (hasGateHooks && !force) {
-            return { name: '.claude/settings.json', status: 'skipped', detail: 'MoFlo hooks already configured' };
+    // No settings.json yet — write the canonical default and return.
+    if (!fs.existsSync(settingsPath)) {
+        const fresh = generateSettings({ ...DEFAULT_INIT_OPTIONS, targetDir: root, force: true });
+        fs.writeFileSync(settingsPath, JSON.stringify(fresh, null, 2), 'utf-8');
+        return { name: '.claude/settings.json', status: 'created', detail: 'canonical hooks block written' };
+    }
+    let existing;
+    try {
+        existing = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        // Corrupt — rewrite from canonical (force-overwrites; user can revert).
+        const fresh = generateSettings({ ...DEFAULT_INIT_OPTIONS, targetDir: root, force: true });
+        fs.writeFileSync(settingsPath, JSON.stringify(fresh, null, 2), 'utf-8');
+        return { name: '.claude/settings.json', status: 'updated', detail: 'rewrote unparseable settings.json from canonical' };
+    }
+    // Respect the explicit opt-out — same sentinel the launcher honours.
+    if (isHookBlockLocked(existing) && !force) {
+        return { name: '.claude/settings.json', status: 'skipped', detail: 'moflo.hooks.locked=true (explicit opt-out)' };
+    }
+    // Pass 1: in-place command + matcher rewrites (#879, #929, #931, #1171,
+    // auto-meditate rebrand). These never delete anything; they fix commands
+    // that exist but point at the wrong helper/subcommand.
+    const { rewrites } = rewriteIncorrectHookWiring(existing);
+    const rewroteCommands = rewrites.reduce((n, r) => n + r.count, 0);
+    // Pass 2: structural wholesale regen. Preserves user-owned entries via the
+    // #1180 basename guard (any command not pointing at a moflo-shipped helper
+    // is grafted back in); relocates moflo entries from legacy event/matcher
+    // slots to the current canonical shape.
+    const report = computeHookBlockDrift((existing.hooks ?? {}));
+    let added = 0;
+    let removed = 0;
+    let preserved = 0;
+    if (report.drifted) {
+        const extraCount = report.extra.length;
+        const result = applyWholesaleRegeneration(existing, report);
+        added = result.added;
+        removed = result.removed;
+        // applyWholesaleRegeneration computes `removed = extra - customisations`,
+        // so `preserved` is the complement — the number of user-owned entries
+        // grafted back into the fresh tree.
+        preserved = extraCount - removed;
+    }
+    // Ensure statusLine + permissions/env/attribution scaffold is present —
+    // mirrors the existing moflo-init.ts UX but no longer overwrites user
+    // values that are already set.
+    const canonical = generateSettings({ ...DEFAULT_INIT_OPTIONS, targetDir: root, force: true });
+    const scaffoldKeys = ['statusLine', 'permissions', 'env', 'attribution'];
+    const scaffoldAdded = [];
+    for (const key of scaffoldKeys) {
+        if (existing[key] == null && canonical[key] != null) {
+            existing[key] = canonical[key];
+            scaffoldAdded.push(key);
         }
     }
-    // Build hooks config — all on by default (opinionated pit-of-success)
-    // Uses direct node invocation via helper scripts (gate.cjs, gate-hook.mjs,
-    // hook-handler.cjs) instead of `npx flo` to avoid 2-5s cold-start per hook.
-    const gateHook = (sub) => `node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate-hook.mjs" ${sub}`;
-    const gate = (sub) => `node "$CLAUDE_PROJECT_DIR/.claude/helpers/gate.cjs" ${sub}`;
-    const handler = (sub) => `node "$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs" ${sub}`;
-    const hooks = {
-        "PreToolUse": [
-            {
-                "matcher": "^(Write|Edit|MultiEdit)$",
-                "hooks": [{ "type": "command", "command": handler('post-edit'), "timeout": 5000 }]
-            },
-            {
-                "matcher": "^(Glob|Grep)$",
-                "hooks": [{ "type": "command", "command": gateHook('check-before-scan'), "timeout": 3000 }]
-            },
-            {
-                "matcher": "^Read$",
-                "hooks": [{ "type": "command", "command": gateHook('check-before-read'), "timeout": 3000 }]
-            },
-            {
-                // #1171 — widened to cover the dedicated `PowerShell` tool.
-                "matcher": "^(Bash|PowerShell)$",
-                "hooks": [
-                    { "type": "command", "command": gateHook('check-dangerous-command'), "timeout": 2000 },
-                    { "type": "command", "command": gateHook('check-before-pr'), "timeout": 2000 }
-                ]
-            },
-            {
-                // #931 — Advisory only; never blocks. TaskCreate REMINDER and the
-                // namespace hint moved here from UserPromptSubmit so they emit only
-                // when Claude is about to spawn an Agent — saves ~90 tokens × every
-                // prompt × every consumer. Routed via gate-hook.mjs so Claude Code's
-                // session_id is forwarded as HOOK_SESSION_ID, enabling per-actor
-                // single-shot emission (mirror of #879's record-memory-searched fix).
-                "matcher": "^Agent$",
-                "hooks": [{ "type": "command", "command": gateHook('check-before-agent'), "timeout": 2000 }]
-            }
-        ],
-        "PostToolUse": [
-            {
-                "matcher": "^(Write|Edit|MultiEdit)$",
-                "hooks": [
-                    { "type": "command", "command": handler('post-edit'), "timeout": 5000 },
-                    { "type": "command", "command": gateHook('reset-edit-gates'), "timeout": 2000 }
-                ]
-            },
-            {
-                "matcher": "^Agent$",
-                "hooks": [{ "type": "command", "command": handler('post-task'), "timeout": 5000 }]
-            },
-            {
-                "matcher": "^TaskCreate$",
-                "hooks": [{ "type": "command", "command": gate('record-task-created'), "timeout": 2000 }]
-            },
-            {
-                // #1171 — widened to cover the dedicated `PowerShell` tool.
-                "matcher": "^(Bash|PowerShell)$",
-                "hooks": [
-                    { "type": "command", "command": gateHook('check-bash-memory'), "timeout": 2000 },
-                    { "type": "command", "command": gateHook('record-test-run'), "timeout": 2000 }
-                ]
-            },
-            {
-                "matcher": "^Skill$",
-                "hooks": [{ "type": "command", "command": gateHook('record-skill-run'), "timeout": 2000 }]
-            },
-            {
-                // Anchored alternation — Claude Code anchors hook matchers (`^…$` semantics),
-                // so a bare `mcp__moflo__memory_` never matches any real MCP tool name and the
-                // hook silently no-ops (#929 regression). The explicit suffix list keeps the
-                // matcher narrow while catching every memory_* tool we ship.
-                // Use gateHook (not gate) so the wrapper forwards Claude Code's session_id as
-                // HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor map
-                // (memorySearchedBy[sid]) that check-before-read consults under #838's per-actor gating.
-                // Without it, the legacy boolean is set but the per-actor map stays empty, and the gate
-                // blocks every Read forever within the turn (issue #879).
-                "matcher": "^mcp__moflo__memory_(search|retrieve|list|stats|store)$",
-                "hooks": [{ "type": "command", "command": gateHook('record-memory-searched'), "timeout": 3000 }]
-            },
-            {
-                "matcher": "^mcp__moflo__memory_store$",
-                "hooks": [{ "type": "command", "command": gate('record-learnings-stored'), "timeout": 2000 }]
-            }
-        ],
-        "UserPromptSubmit": [
-            {
-                "hooks": [
-                    { "type": "command", "command": `node "$CLAUDE_PROJECT_DIR/.claude/helpers/prompt-hook.mjs"`, "timeout": 3000 }
-                ]
-            },
-            {
-                // prompt-state-reset is REQUIRED to reset memorySearched/memorySearchedBy on
-                // each new prompt and reclassify memoryRequired. Without it, gate state leaks
-                // across prompts. Separate hook entry so a prompt-hook.mjs exception doesn't
-                // skip the reset. Idempotent state reset only — no emission, no
-                // interactionCount increment (#931 dedupe).
-                "hooks": [
-                    { "type": "command", "command": gateHook('prompt-state-reset'), "timeout": 3000 }
-                ]
-            }
-        ],
-        "SubagentStart": [
-            {
-                "hooks": [{
-                        "type": "command",
-                        "command": "node \"$CLAUDE_PROJECT_DIR/.claude/helpers/subagent-start.cjs\"",
-                        "timeout": 2000
-                    }]
-            }
-        ],
-        "SessionStart": [
-            {
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": "node \"$CLAUDE_PROJECT_DIR/.claude/scripts/session-start-launcher.mjs\"",
-                        "timeout": 3000
-                    }
-                ]
-            }
-        ],
-        "Stop": [
-            {
-                "hooks": [{ "type": "command", "command": handler('session-end'), "timeout": 5000 }]
-            }
-        ],
-        "PreCompact": [
-            {
-                "hooks": [{ "type": "command", "command": gate('compact-guidance'), "timeout": 3000 }]
-            }
-        ],
-        "Notification": [
-            {
-                "hooks": [{ "type": "command", "command": handler('notification'), "timeout": 3000 }]
-            }
-        ]
-    };
-    // Merge: preserve existing non-MoFlo hooks, add MoFlo hooks
-    existing.hooks = hooks;
-    // Ensure statusLine is always present (required for dashboard display).
-    // The executor.ts / settings-generator.ts code path adds this, but
-    // moflo-init.ts uses its own generateHooks() which was missing it.
-    if (!existing.statusLine) {
-        existing.statusLine = {
-            type: 'command',
-            command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/statusline.cjs"',
-        };
+    const dirty = rewroteCommands > 0 || added > 0 || removed > 0 || scaffoldAdded.length > 0;
+    if (!dirty) {
+        return { name: '.claude/settings.json', status: 'skipped', detail: 'already at canonical reference' };
     }
     fs.writeFileSync(settingsPath, JSON.stringify(existing, null, 2), 'utf-8');
-    return { name: '.claude/settings.json', status: existing.hooks ? 'updated' : 'created', detail: '14 hooks configured (gates, lifecycle, routing, session)' };
+    // Surface deletions, preserved customisations, and rewrites so nothing is
+    // silent — direct response to #1227's "no notice was printed" complaint.
+    const parts = [];
+    if (added > 0)
+        parts.push(`+${added} canonical`);
+    if (removed > 0)
+        parts.push(`-${removed} stale moflo`);
+    if (preserved > 0)
+        parts.push(`✓${preserved} preserved`);
+    if (rewroteCommands > 0)
+        parts.push(`↻${rewroteCommands} rewrites`);
+    if (scaffoldAdded.length > 0)
+        parts.push(`+scaffold (${scaffoldAdded.join(',')})`);
+    return { name: '.claude/settings.json', status: 'updated', detail: parts.join(', ') };
 }
 // ============================================================================
 // Step 3: .claude/skills/flo/ skill (with /fl alias)

package/dist/src/cli/services/headless-worker-executor.js

@@ -46,6 +46,28 @@ const MODEL_IDS = {
     opus: 'claude-opus-4-6',
     haiku: 'claude-haiku-4-5-20251001',
 };
+/**
+ * Tool allowlist for every headless worker. These workers are READ-ONLY by
+ * design: they analyse the codebase and produce a report. Moflo persists their
+ * stdout to `.moflo/reports/<type>.<ext>` itself (see `executeInternal`), so
+ * they never need write capability to deliver their output.
+ *
+ * Restricting tools here is a GATE-INTEGRITY guarantee, not a tidy-up. The
+ * spawn previously ran `claude --print <prompt>` with no tool restriction, so
+ * a daemon-spawned worker inherited the consumer's permissions and could edit
+ * any file in their tree. The `optimize` ("Performance optimization") worker
+ * is `enabled: true` by default and runs unattended; given write access and a
+ * "analyze this codebase for performance optimizations" prompt, it reasons its
+ * way into editing `moflo.yaml` to `memory_first: false`
+ * (`# Temporarily disabled for performance analysis`) to unblock its own
+ * non-memory-first tool calls against the gate — silently disabling the
+ * memory-first protocol repo-wide and dirtying the working tree every run.
+ * Worse, the gate it disables is what surfaces the "never disable memory_first"
+ * learning, so the loop self-conceals. A read-only allowlist makes that edit
+ * physically impossible while leaving full analysis capability (Read/Glob/Grep)
+ * intact. See issue #1229.
+ */
+const HEADLESS_WORKER_ALLOWED_TOOLS = 'Read,Glob,Grep';
 /**
  * Default headless worker configurations based on ADR-020 (the
  * `audit`/`document`/`predict` entries from the original ADR were dropped
@@ -811,7 +833,7 @@ export class HeadlessWorkerExecutor extends EventEmitter {
     buildPrompt(template, context, reportPath) {
         const ioInstructions = `## Output
 
-Save the full report to \`${reportPath}\` using the Write tool. Overwrite any prior content at that path. DO NOT create any other files anywhere in the project; if you need to suggest test skeletons or code samples, include them inline in the report as fenced code blocks. Moflo persists the same output to that path after you finish, so the location is authoritative.`;
+Save the full report to \`${reportPath}\` by emitting it as your response — moflo writes your output to that path after you finish, so that location is authoritative. You are a READ-ONLY analysis worker and have no write tools: do not attempt to create or modify any file in the project, and in particular never edit \`moflo.yaml\`, anything under \`.claude/\`, or any gate/config (the memory-first gate stays on — comply with it, never disable it). Include any test skeletons or code samples inline in the report as fenced code blocks.`;
         if (!context) {
             return `${template}
 
@@ -845,8 +867,11 @@ ${ioInstructions}`;
             };
             // Set model
             env.ANTHROPIC_MODEL = MODEL_IDS[options.model];
-            // Spawn claude CLI process
-            const child = spawn('claude', ['--print', prompt], {
+            // Spawn claude CLI process. Keep `--print` first and the prompt second
+            // (callers/tests rely on argv[0]/argv[1]); the read-only allowlist is
+            // appended so these analysis workers cannot mutate the consumer's tree
+            // (e.g. disable a gate in moflo.yaml). See HEADLESS_WORKER_ALLOWED_TOOLS.
+            const child = spawn('claude', ['--print', prompt, '--allowedTools', HEADLESS_WORKER_ALLOWED_TOOLS], {
                 cwd: this.projectRoot,
                 env,
                 stdio: ['pipe', 'pipe', 'pipe'],

package/dist/src/cli/spells/commands/composite-command.js

@@ -217,13 +217,24 @@ function interpolateCommandString(command, config) {
 }
 /**
  * Run a shell command and capture output.
- * Uses platform-aware shell selection.
+ *
+ * On POSIX we deliberately use `/bin/sh` (NOT `process.env.SHELL`). The
+ * interpolation pipeline uses POSIX single-quote escaping (`shellEscapeValue`),
+ * which is safe under sh/bash but breaks under zsh: zsh's stricter globbing
+ * treats unmatched `[...]` patterns as a hard error ("zsh:1: no matches found"),
+ * whereas POSIX sh and bash leave unmatched globs literal. Honouring the user's
+ * interactive `$SHELL` made CI (Ubuntu, /bin/bash) pass while macOS/Linux dev
+ * machines on zsh silently failed every composite step containing bracket
+ * characters in interpolated values.
+ *
+ * On Windows we use ComSpec (cmd.exe) — POSIX shell quoting is meaningless
+ * there; the rest of the pipeline already special-cases Windows shell-out.
  */
 function runShellCommand(command, context) {
     const timeout = 30000;
     const shell = process.platform === 'win32'
         ? (process.env.ComSpec || 'cmd.exe')
-        : (process.env.SHELL || 'bash');
+        : '/bin/sh';
     return new Promise((resolve) => {
         const child = exec(command, { timeout, shell }, (error, stdout, stderr) => {
             context.abortSignal?.removeEventListener('abort', onAbort);

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.10.26';
+export const VERSION = '4.10.28';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.26",
+  "version": "4.10.28",
   "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",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.10.25",
+    "moflo": "^4.10.27",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"