moflo 4.10.6 → 4.10.7

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

@@ -101,9 +101,17 @@ status_line:
 sandbox:
   enabled: false                  # Set to true to wrap bash steps in an OS sandbox
   tier: auto                      # auto | denylist-only | full
+
+# Auto-update on session start (refreshes consumer assets when moflo upgrades)
+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
+  claudemd_injection_drift: regenerate   # warn | regenerate | off
 ```
 
-If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
+If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
 
 ### Key Behaviors
 
@@ -128,6 +136,12 @@ If your `moflo.yaml` predates the `sandbox:` block, it is auto-appended on the n
 | `sandbox.enabled: true` | Wrap bash steps in an OS sandbox (macOS/Linux/WSL) — absolute disable when `false`, regardless of tier |
 | `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: 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 |
+| `auto_update.claudemd_injection_drift: off` | Skip CLAUDE.md injection drift detection entirely |
 
 ---
 

package/bin/session-start-launcher.mjs

@@ -640,7 +640,16 @@ 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, hookBlockDrift: 'warn' };
+let autoUpdateConfig = {
+  enabled: true,
+  scripts: true,
+  helpers: true,
+  hookBlockDrift: 'warn',
+  // #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.
+  claudemdInjectionDrift: 'regenerate',
+};
 try {
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (existsSync(mofloYaml)) {
@@ -651,10 +660,13 @@ try {
     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)/);
+    // #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)/);
     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];
+    if (claudemdMatch) autoUpdateConfig.claudemdInjectionDrift = claudemdMatch[1];
   }
 } catch (err) {
   // Defaults (all true) keep the upgrade flow alive but the user should
@@ -1414,23 +1426,185 @@ async function runHookBlockDriftCheck() {
   };
 }
 
-try {
-  if (autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off') {
-    const result = await runHookBlockDriftCheck();
-    if (result) {
+// ── 3a-vii. CLAUDE.md injection drift detection (#1142) ──────────────────
+// Refresh the consumer's `<root>/CLAUDE.md` MoFlo block when it has drifted
+// from what `claudemd-generator.ts` currently produces. The launcher's
+// stages 3/3b refresh shipped guidance files on every version change, but
+// CLAUDE.md was only rewritten by explicit `flo init` / `flo-setup` — so
+// consumers carried stale injection content (with the legacy `shipped/`
+// guidance paths, for example) for as long as they didn't re-run init.
+//
+// Modes (`auto_update.claudemd_injection_drift` in moflo.yaml):
+//   regenerate  — replace the drifted block in place (default; the consumer
+//                 has no other path to refresh CLAUDE.md)
+//   warn        — print a one-line drift summary to stdout
+//   off         — skip detection entirely
+//
+// Fast-path: `.moflo/claudemd-injection-cache.json` records the last clean
+// run. If CLAUDE.md + the generator module both still match the cached
+// mtimes, skip the readFile + dynamic import.
+async function runClaudeMdInjectionDriftCheck() {
+  const claudeMdPath = resolve(projectRoot, 'CLAUDE.md');
+  let claudeMdStat;
+  try { claudeMdStat = statSync(claudeMdPath); } catch { return null; }
+
+  // Locate the generator and the drift service. Both must be present —
+  // generator owns the canonical content, drift service owns the marker
+  // logic. Use bin/lib/moflo-resolve.mjs path resolution semantics
+  // (covers consumer node_modules + dev source tree). Two candidates each.
+  const generatorCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/init/claudemd-generator.js'),
+    resolve(projectRoot, 'dist/src/cli/init/claudemd-generator.js'),
+  ];
+  const driftCandidates = [
+    resolve(projectRoot, 'node_modules/moflo/dist/src/cli/services/claudemd-injection.js'),
+    resolve(projectRoot, 'dist/src/cli/services/claudemd-injection.js'),
+  ];
+  let generatorPath = null, generatorStat = null;
+  for (const p of generatorCandidates) {
+    try { generatorStat = statSync(p); generatorPath = p; break; } catch { /* try next */ }
+  }
+  let driftPath = null, driftStat = null;
+  for (const p of driftCandidates) {
+    try { driftStat = statSync(p); driftPath = p; break; } catch { /* try next */ }
+  }
+  if (!generatorPath || !driftPath) return null;
+
+  // Use the max mtime of the two modules so any update to either invalidates
+  // the cache. Both are co-bumped on publish so this is normally one mtime.
+  const moduleMtimeMs = Math.max(generatorStat.mtimeMs, driftStat.mtimeMs);
+
+  // Cache short-circuits any (claudeMdMtime, moduleMtime, state) triple
+  // match — not just 'in-sync'. A drifted consumer in warn mode still emits
+  // the nudge once on first detection, then stays silent until something
+  // actually changes (CLAUDE.md mtime bumps from a user edit, or moflo
+  // upgrade bumps moduleMtimeMs). Without this, every session re-does the
+  // full slow path (3 statSync + readFile + 2 dynamic imports + generator
+  // call) for non-in-sync consumers in perpetuity.
+  const cachePath = join(mofloDir(projectRoot), 'claudemd-injection-cache.json');
+  let cached = null;
+  try { cached = JSON.parse(readFileSync(cachePath, 'utf-8')); } catch { /* missing or corrupt */ }
+  if (
+    cached &&
+    cached.claudeMdMtimeMs === claudeMdStat.mtimeMs &&
+    cached.moduleMtimeMs === moduleMtimeMs &&
+    typeof cached.state === 'string'
+  ) return null;
+
+  // Try-catch around the dynamic imports handles the file disappearing
+  // between statSync and import (TOCTOU); other load errors surface as
+  // an emitWarning so a transitive dependency failure isn't invisible
+  // (mirrors the silent-catch lesson — see feedback_consumer_blast_radius).
+  let genMod = null, driftMod = null;
+  try {
+    genMod = await import(pathToFileURL(generatorPath).href);
+    driftMod = await import(pathToFileURL(driftPath).href);
+  } catch (err) {
+    emitWarning(`CLAUDE.md drift check skipped (${errMessage(err)})`);
+    return null;
+  }
+  if (typeof genMod.generateClaudeMd !== 'function') return null;
+  if (typeof driftMod.computeInjectionDrift !== 'function') return null;
+  if (typeof driftMod.applyInjectionReplacement !== 'function') return null;
+
+  const claudeMdContents = readFileSync(claudeMdPath, 'utf-8');
+  const canonical = genMod.generateClaudeMd({});
+  const report = driftMod.computeInjectionDrift(claudeMdContents, canonical);
+
+  let finalState = report.state;
+  let finalMtime = claudeMdStat.mtimeMs;
+
+  // Treat both 'drifted' and 'legacy-marker' as repairable in regenerate mode.
+  // 'no-marker' means the user removed the inject deliberately — don't re-add
+  // it on every session start; that's a re-init operation, not a drift fix.
+  // 'no-file' is unreachable here because statSync already succeeded.
+  const repairable = report.state === 'drifted' || report.state === 'legacy-marker';
+  if (repairable) {
+    const wantRegenerate = autoUpdateConfig.claudemdInjectionDrift === 'regenerate';
+    if (wantRegenerate) {
+      const result = driftMod.applyInjectionReplacement(claudeMdContents, canonical);
+      if (result.changed && typeof result.contents === 'string') {
+        writeFileSync(claudeMdPath, result.contents);
+        finalState = 'in-sync';
+        try { finalMtime = statSync(claudeMdPath).mtimeMs; } catch { /* keep prior */ }
+        emitMutation(
+          'refreshed CLAUDE.md MoFlo block',
+          `replaced ${report.state} block with current generator output`,
+        );
+      }
+    } else {
+      // warn mode — surface a one-line summary on stdout for Claude/user.
       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 */ }
+        process.stdout.write(
+          `moflo: CLAUDE.md injection ${report.state}; run \`flo doctor claudemd-drift\` or set auto_update.claudemd_injection_drift: regenerate in moflo.yaml\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
+    }
+  } else if (report.state === 'no-marker') {
+    // Distinct from the drift cases — surface once via warn channel so a
+    // user who didn't run init still sees a nudge, but never auto-mutate.
+    if (autoUpdateConfig.claudemdInjectionDrift !== 'off') {
+      try {
+        process.stdout.write(
+          `moflo: CLAUDE.md has no MoFlo injection block; run \`npx flo-setup\` to add one\n`,
+        );
+      } catch { /* broken stdout — non-fatal */ }
     }
   }
-} catch (err) {
-  emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+
+  return {
+    cachePath,
+    claudeMdMtimeMs: finalMtime,
+    moduleMtimeMs,
+    state: finalState,
+  };
+}
+
+// Run the two drift detectors (settings.json hook block + CLAUDE.md
+// injection) in parallel. Both do their own statSync → cache compare →
+// dynamic import dance; the work is independent and the file targets are
+// different, so Promise.all halves cold-path latency on every session start.
+// Cache-hit fast paths return null with no work — Promise.all is still
+// trivially correct there.
+{
+  const hookEnabled = autoUpdateConfig.enabled && autoUpdateConfig.hookBlockDrift !== 'off';
+  const claudemdEnabled = autoUpdateConfig.enabled && autoUpdateConfig.claudemdInjectionDrift !== 'off';
+  const [hookResult, claudemdResult] = await Promise.all([
+    hookEnabled
+      ? runHookBlockDriftCheck().catch((err) => {
+          emitWarning(`hook-block drift check skipped (${errMessage(err)})`);
+          return null;
+        })
+      : Promise.resolve(null),
+    claudemdEnabled
+      ? runClaudeMdInjectionDriftCheck().catch((err) => {
+          emitWarning(`CLAUDE.md injection drift check skipped (${errMessage(err)})`);
+          return null;
+        })
+      : Promise.resolve(null),
+  ]);
+
+  if (hookResult) {
+    try {
+      mkdirSync(mofloDir(projectRoot), { recursive: true });
+      writeFileSync(hookResult.cachePath, JSON.stringify({
+        settingsMtimeMs: hookResult.settingsMtimeMs,
+        moduleMtimeMs: hookResult.moduleMtimeMs,
+        consumerHash: hookResult.consumerHash,
+        referenceHash: hookResult.referenceHash,
+      }));
+    } catch { /* cache is opportunistic — non-fatal */ }
+  }
+  if (claudemdResult) {
+    try {
+      mkdirSync(mofloDir(projectRoot), { recursive: true });
+      writeFileSync(claudemdResult.cachePath, JSON.stringify({
+        claudeMdMtimeMs: claudemdResult.claudeMdMtimeMs,
+        moduleMtimeMs: claudemdResult.moduleMtimeMs,
+        state: claudemdResult.state,
+      }));
+    } catch { /* cache is opportunistic — non-fatal */ }
+  }
 }
 
 // ── 3b. Ensure shipped guidance files exist (even without version change) ──

package/bin/setup-project.mjs

@@ -37,16 +37,14 @@ import { mofloInternalURL } from './lib/moflo-resolve.mjs';
 // works identically from bin/ (canonical) or from .claude/scripts/ (synced copy).
 const mofloRoot = dirname(fileURLToPath(mofloInternalURL('package.json')));
 
-// Single source of truth: claudemd-generator.ts owns the section content.
-// Use the shared mofloInternalURL helper so the script works identically when
-// invoked from bin/ (canonical) or from .claude/scripts/ (synced copy).
-const {
-  generateClaudeMd,
-  MARKER_START,
-  MARKER_END,
-  LEGACY_MARKER_STARTS,
-  LEGACY_MARKER_ENDS,
-} = await import(mofloInternalURL('dist/src/cli/init/claudemd-generator.js'));
+// Single source of truth: claudemd-generator.ts owns the section content,
+// claudemd-injection.ts owns the marker-replace logic. Use the shared
+// mofloInternalURL helper so the script works identically when invoked
+// from bin/ (canonical) or from .claude/scripts/ (synced copy).
+const { generateClaudeMd } = await import(mofloInternalURL('dist/src/cli/init/claudemd-generator.js'));
+const { applyInjectionReplacement, computeInjectionDrift } = await import(
+  mofloInternalURL('dist/src/cli/services/claudemd-injection.js')
+);
 
 const args = process.argv.slice(2);
 const updateOnly = args.includes('--update');
@@ -150,65 +148,47 @@ function cleanupLegacyBootstrap(projectRoot) {
 
 function updateClaudeMd(projectRoot) {
   const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+  const existed = existsSync(claudeMdPath);
+  const content = existed ? readFileSync(claudeMdPath, 'utf-8') : null;
 
-  if (!existsSync(claudeMdPath)) {
-    if (checkOnly) {
-      log('⚠️  No CLAUDE.md found');
-      return false;
-    }
-    log('📝 Creating CLAUDE.md with subagent protocol section');
-    writeFileSync(claudeMdPath, `# Project Configuration\n\n${CLAUDE_MD_SECTION}\n`, 'utf-8');
-    return true;
-  }
+  // Single source of truth for the marker-replace logic lives in
+  // src/cli/services/claudemd-injection.ts. Classify state for logging,
+  // then apply (or report) the replacement.
+  const report = computeInjectionDrift(content, CLAUDE_MD_SECTION);
 
-  const content = readFileSync(claudeMdPath, 'utf-8');
-
-  // Check for current or legacy markers and replace
-  const allStarts = [MARKER_START, ...LEGACY_MARKER_STARTS];
-  const allEnds = [MARKER_END, ...LEGACY_MARKER_ENDS];
-
-  for (let i = 0; i < allStarts.length; i++) {
-    if (content.includes(allStarts[i])) {
-      const startIdx = content.indexOf(allStarts[i]);
-      const endIdx = content.indexOf(allEnds[i]);
-
-      if (endIdx > startIdx) {
-        // If current markers and content matches, we're up to date
-        if (i === 0) {
-          const existingSection = content.substring(startIdx, endIdx + allEnds[i].length);
-          if (existingSection === CLAUDE_MD_SECTION) {
-            log('✅ CLAUDE.md moflo section is current');
-            return true;
-          }
-        }
-
-        // Replace (current or legacy) with new section
-        if (!checkOnly) {
-          const updated = content.substring(0, startIdx) + CLAUDE_MD_SECTION + content.substring(endIdx + allEnds[i].length);
-          writeFileSync(claudeMdPath, updated, 'utf-8');
-          log(i === 0 ? '📝 Updated CLAUDE.md moflo section' : '📝 Replaced legacy CLAUDE.md section with minimal moflo injection');
-        } else {
-          log('⚠️  CLAUDE.md moflo section needs update');
-        }
-        return true;
-      }
-    }
+  if (report.state === 'in-sync') {
+    log('✅ CLAUDE.md moflo section is current');
+    return true;
   }
 
+  // `updateOnly` is informational — refresh the bootstrap mirror file but
+  // leave CLAUDE.md alone unless an inject already exists.
   if (updateOnly) {
-    log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
-    return false;
+    if (!existed) { log('⚠️  No CLAUDE.md found'); return false; }
+    if (report.state === 'no-marker') {
+      log('⚠️  CLAUDE.md has no moflo section (run without --update to add)');
+      return false;
+    }
+    // Existing block (current or legacy) + drift → fall through to write.
   }
 
   if (checkOnly) {
-    log('⚠️  CLAUDE.md missing subagent protocol section');
+    if (!existed) { log('⚠️  No CLAUDE.md found'); return false; }
+    if (report.state === 'no-marker') { log('⚠️  CLAUDE.md missing subagent protocol section'); return false; }
+    log('⚠️  CLAUDE.md moflo section needs update');
     return false;
   }
 
-  // Append section to end of CLAUDE.md
-  const separator = content.endsWith('\n') ? '\n' : '\n\n';
-  writeFileSync(claudeMdPath, content + separator + CLAUDE_MD_SECTION + '\n', 'utf-8');
-  log('📝 Added subagent protocol section to CLAUDE.md');
+  const result = applyInjectionReplacement(content, CLAUDE_MD_SECTION);
+  if (!result.changed) return true;
+  writeFileSync(claudeMdPath, result.contents, 'utf-8');
+
+  switch (report.state) {
+    case 'no-file':       log('📝 Creating CLAUDE.md with subagent protocol section'); break;
+    case 'no-marker':     log('📝 Added subagent protocol section to CLAUDE.md'); break;
+    case 'legacy-marker': log('📝 Replaced legacy CLAUDE.md section with minimal moflo injection'); break;
+    case 'drifted':       log('📝 Updated CLAUDE.md moflo section'); break;
+  }
   return true;
 }
 

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

@@ -670,4 +670,109 @@ export async function checkHookBlockDrift() {
         fix: 'set auto_update.hook_block_drift: regenerate in moflo.yaml, or claudeFlow.hooks.locked: true to suppress',
     };
 }
+// ============================================================================
+// 12. CLAUDE.md Injection Drift Check
+// ============================================================================
+/**
+ * Detect when the consumer's `<root>/CLAUDE.md` MoFlo-injected block has
+ * drifted from the canonical block the current `claudemd-generator` produces.
+ * Analogue of `Hook Block Drift` for CLAUDE.md content.
+ *
+ * The session-start launcher refreshes shipped guidance files on every
+ * version change, but the CLAUDE.md injection is only rewritten by explicit
+ * `flo init` / `flo-setup`. Without this check, consumers carry stale
+ * injection content (and stale guidance pointers) indefinitely.
+ *
+ * Five states map to four reportable statuses:
+ *   no-file       → warn  (run `flo init`)
+ *   no-marker     → warn  (run `flo init` / `flo-setup`)
+ *   legacy-marker → warn  (auto-fixable — replace legacy block)
+ *   in-sync       → pass
+ *   drifted       → warn  (auto-fixable — refresh block)
+ */
+export async function checkClaudeMdInjectionDrift() {
+    const projectDir = findConsumerProjectDir();
+    const claudeMdPath = join(projectDir, 'CLAUDE.md');
+    // Respect `auto_update.claudemd_injection_drift: off` for consumers who
+    // explicitly opt out (mirrors the launcher's behaviour and the Hook Block
+    // Drift check). Read the config first so the off-mode skip is cheap.
+    try {
+        const { loadMofloConfig } = await import('../config/moflo-config.js');
+        const cfg = loadMofloConfig(projectDir);
+        if (cfg.auto_update.claudemd_injection_drift === 'off') {
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'pass',
+                message: 'drift check skipped — auto_update.claudemd_injection_drift: off',
+            };
+        }
+    }
+    catch { /* config read failure — fall through to drift check */ }
+    if (!existsSync(claudeMdPath)) {
+        return {
+            name: 'CLAUDE.md Injection Drift',
+            status: 'warn',
+            message: 'CLAUDE.md not found',
+            fix: 'npx moflo init',
+        };
+    }
+    let contents;
+    try {
+        contents = readFileSync(claudeMdPath, 'utf-8');
+    }
+    catch (e) {
+        return {
+            name: 'CLAUDE.md Injection Drift',
+            status: 'warn',
+            message: `cannot read CLAUDE.md: ${errorDetail(e)}`,
+        };
+    }
+    // Dynamic-import the generator + drift detector so the dist-vs-source
+    // path resolution stays consistent with the launcher.
+    const { generateClaudeMd } = await import('../init/claudemd-generator.js');
+    const { computeInjectionDrift } = await import('../services/claudemd-injection.js');
+    // Use `{}` (not DEFAULT_INIT_OPTIONS) to match the launcher's call —
+    // the generator ignores the argument, but matching call shape removes the
+    // possibility of a future generator change diverging the two surfaces.
+    const canonical = generateClaudeMd({});
+    const report = computeInjectionDrift(contents, canonical);
+    switch (report.state) {
+        case 'in-sync':
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'pass',
+                message: 'CLAUDE.md injection block matches reference',
+            };
+        case 'no-marker':
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'warn',
+                message: 'CLAUDE.md has no MOFLO:INJECTED:START block',
+                fix: 'npx flo-setup',
+            };
+        case 'legacy-marker':
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'warn',
+                message: 'CLAUDE.md uses a legacy moflo marker pair (pre-MOFLO:INJECTED) — auto-fix replaces with current block',
+                fix: 'npx flo-setup --update',
+            };
+        case 'drifted':
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'warn',
+                message: 'CLAUDE.md injection block has drifted from reference',
+                fix: 'npx flo-setup --update',
+            };
+        case 'no-file':
+            // Defensive — `existsSync` returned true above, so this branch is
+            // unreachable in practice. Return a sane status anyway.
+            return {
+                name: 'CLAUDE.md Injection Drift',
+                status: 'warn',
+                message: 'CLAUDE.md not found',
+                fix: 'npx moflo init',
+            };
+    }
+}
 //# sourceMappingURL=doctor-checks-deep.js.map

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

@@ -255,6 +255,30 @@ export async function autoFixCheck(check) {
         'Gate Health': async () => {
             return fixGateHealthHooks();
         },
+        // Refresh the consumer's CLAUDE.md MoFlo block in place using the
+        // shared `applyInjectionReplacement` service. Idempotent: a re-run sees
+        // `state === 'in-sync'` and the autoFix dispatcher skips this entry.
+        'CLAUDE.md Injection Drift': async () => {
+            const projectRoot = findProjectRoot();
+            const claudeMdPath = join(projectRoot, 'CLAUDE.md');
+            try {
+                const { generateClaudeMd } = await import('../init/claudemd-generator.js');
+                const { applyInjectionReplacement } = await import('../services/claudemd-injection.js');
+                const canonical = generateClaudeMd({});
+                const existing = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, 'utf-8') : null;
+                const result = applyInjectionReplacement(existing, canonical);
+                if (!result.changed || !result.contents)
+                    return false;
+                // atomicWriteFileSync guards against a concurrent reader (Claude Code
+                // re-scanning CLAUDE.md mid-fix) seeing a truncated file.
+                atomicWriteFileSync(claudeMdPath, result.contents);
+                return true;
+            }
+            catch (e) {
+                output.writeln(output.warning(`  CLAUDE.md repair failed: ${errorDetail(e)}`));
+                return false;
+            }
+        },
         'Embedding hygiene': async () => {
             // The session-start launcher already runs the same migration BEFORE
             // daemon/MCP boot — that's where consumer autoheal happens. Running

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

@@ -4,7 +4,7 @@
  * Kept separate from `doctor.ts` so the orchestration file stays small and the
  * registry can be inspected/extended without re-touching command-action code.
  */
-import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkHookBlockDrift, checkMofloDbBridge, } from './doctor-checks-deep.js';
+import { checkSubagentHealth, checkSpellExecution, checkMcpToolInvocation, checkHookExecution, checkMcpSpellIntegration, checkGateHealth, checkHookBlockDrift, checkClaudeMdInjectionDrift, checkMofloDbBridge, } from './doctor-checks-deep.js';
 import { checkEmbeddingHygiene } from './doctor-embedding-hygiene.js';
 import { checkDaemonVersionSkew } from './doctor-checks-version-skew.js';
 import { checkEmbeddingCoverageTruth } from './doctor-checks-coverage-truth.js';
@@ -63,6 +63,7 @@ export const allChecks = [
     checkHookExecution,
     checkGateHealth,
     checkHookBlockDrift,
+    checkClaudeMdInjectionDrift,
     checkMofloDbBridge,
     // Issue #818 / epic #798 — coordinator-path tripwires. They share the
     // singleton coordinator with checkSubagentHealth above and assert by
@@ -127,6 +128,9 @@ export const componentMap = {
     'gate': checkGateHealth,
     'hook-drift': checkHookBlockDrift,
     'drift': checkHookBlockDrift,
+    'claudemd-drift': checkClaudeMdInjectionDrift,
+    'claudemd': checkClaudeMdInjectionDrift,
+    'injection-drift': checkClaudeMdInjectionDrift,
     'sandbox': checkSandboxTier,
     'sandbox-tier': checkSandboxTier,
     'moflodb': checkMofloDbBridge,

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

@@ -83,6 +83,7 @@ const DEFAULT_CONFIG = {
         scripts: true,
         helpers: true,
         hook_block_drift: 'warn',
+        claudemd_injection_drift: 'regenerate',
     },
     sandbox: {
         enabled: false,
@@ -212,6 +213,12 @@ function mergeConfig(raw, root) {
                     ? v
                     : DEFAULT_CONFIG.auto_update.hook_block_drift;
             })(),
+            claudemd_injection_drift: (() => {
+                const v = raw.auto_update?.claudemd_injection_drift ?? raw.autoUpdate?.claudemdInjectionDrift;
+                return v === 'regenerate' || v === 'off' || v === 'warn'
+                    ? v
+                    : DEFAULT_CONFIG.auto_update.claudemd_injection_drift;
+            })(),
         },
         sandbox: {
             enabled: raw.sandbox?.enabled ?? DEFAULT_CONFIG.sandbox.enabled,
@@ -409,6 +416,10 @@ auto_update:
                                  # warn = print drift summary on session start (default)
                                  # regenerate = auto-add missing hooks (only when no customisations)
                                  # off = skip detection entirely
+  claudemd_injection_drift: regenerate  # warn | regenerate | off
+                                 # regenerate = auto-refresh CLAUDE.md MoFlo block on drift (default)
+                                 # warn = print drift summary on session start
+                                 # off = skip detection entirely
 
 # OS-level sandbox for spell bash steps
 # Denylist always runs regardless of this setting

package/dist/src/cli/init/claudemd-generator.js

@@ -60,8 +60,12 @@ ${MARKER_END}`;
 export { MARKER_START, MARKER_END, LEGACY_MARKER_STARTS, LEGACY_MARKER_ENDS };
 /**
  * Generate the MoFlo section to inject into CLAUDE.md.
- * Template parameter is accepted for backward compatibility but ignored —
- * all templates now produce the same minimal injection.
+ *
+ * Both parameters are accepted for backward compatibility but ignored — all
+ * templates produce the same minimal injection and the options shape is no
+ * longer consulted. Optional so callers from both the dev tree (TS) and the
+ * dogfood launcher (plain JS) can invoke as `generateClaudeMd()` /
+ * `generateClaudeMd({})` interchangeably.
  */
 export function generateClaudeMd(_options, _template) {
     return mofloSection() + '\n';

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

@@ -15,7 +15,8 @@ import { execSync } from 'child_process';
 import { locateMofloRootPath } from '../services/moflo-require.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { discoverGuidanceDirs, discoverSrcDirs, discoverTestDirs, detectExtensions, renderMofloYaml, } from './moflo-yaml-template.js';
-import { generateClaudeMd as generateMofloSection, MARKER_START, MARKER_END, LEGACY_MARKER_STARTS, LEGACY_MARKER_ENDS, } from './claudemd-generator.js';
+import { generateClaudeMd as generateMofloSection } from './claudemd-generator.js';
+import { applyInjectionReplacement } from '../services/claudemd-injection.js';
 import { DEFAULT_INIT_OPTIONS } from './types.js';
 export { discoverTestDirs };
 // ============================================================================
@@ -400,29 +401,20 @@ function generateSkill(root, force) {
 // ============================================================================
 function generateClaudeMd(root, _force) {
     const claudeMdPath = path.join(root, 'CLAUDE.md');
-    let existing = '';
-    if (fs.existsSync(claudeMdPath)) {
-        existing = fs.readFileSync(claudeMdPath, 'utf-8');
-        // Strip current or legacy MoFlo block so we can re-inject the latest content.
-        const allStartMarkers = [MARKER_START, ...LEGACY_MARKER_STARTS];
-        const allEndMarkers = [MARKER_END, ...LEGACY_MARKER_ENDS];
-        for (let i = 0; i < allStartMarkers.length; i++) {
-            if (existing.includes(allStartMarkers[i])) {
-                const startIdx = existing.indexOf(allStartMarkers[i]);
-                const endIdx = existing.indexOf(allEndMarkers[i]);
-                if (endIdx > startIdx) {
-                    existing = existing.substring(0, startIdx) + existing.substring(endIdx + allEndMarkers[i].length);
-                }
-            }
-        }
-    }
-    // Single source of truth: claudemd-generator.ts owns the section content.
+    const existed = fs.existsSync(claudeMdPath);
+    const existing = existed ? fs.readFileSync(claudeMdPath, 'utf-8') : null;
+    // Single source of truth: claudemd-generator.ts owns the section content,
+    // claudemd-injection.ts owns the marker-replace logic. Replaces in place
+    // when a marker pair (current or legacy) already exists; otherwise creates
+    // a fresh CLAUDE.md or appends to a non-moflo one.
     const canonical = generateMofloSection(DEFAULT_INIT_OPTIONS);
-    const finalContent = existing.trimEnd() + '\n\n' + canonical;
-    fs.writeFileSync(claudeMdPath, finalContent, 'utf-8');
+    const result = applyInjectionReplacement(existing, canonical);
+    if (result.contents !== null && (result.changed || !existed)) {
+        fs.writeFileSync(claudeMdPath, result.contents, 'utf-8');
+    }
     return {
         name: 'CLAUDE.md',
-        status: existing ? 'updated' : 'created',
+        status: existed ? 'updated' : 'created',
         detail: 'MoFlo section injected (~22 lines)',
     };
 }

package/dist/src/cli/services/claudemd-injection.js

@@ -0,0 +1,173 @@
+/**
+ * CLAUDE.md injection drift detection + replacement (#1142).
+ *
+ * Detects when a consumer's `<root>/CLAUDE.md` carries a MoFlo-injected block
+ * whose content has drifted from what the current generator produces. Catches
+ * the case where a consumer upgrades moflo (so guidance files refresh) but the
+ * CLAUDE.md injection — only rewritten by explicit `flo init` / `flo-setup` —
+ * stays frozen at the prior version's content, sometimes pointing at paths
+ * that no longer exist (e.g. `.claude/guidance/shipped/...` before the
+ * flat-layout cleanup).
+ *
+ * IMPORTANT: This module must remain self-contained with ZERO imports from
+ * other moflo modules (mirrors the constraint on `services/hook-block-hash.ts`
+ * and `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 MoFlo block markers are duplicated from `init/claudemd-generator.ts` on
+ * purpose — the launcher cannot pull in TS dist of init/types.js at runtime,
+ * and a unit test asserts the two stay in sync.
+ */
+// ────────────────────────────────────────────────────────────────────────────
+// Marker constants — kept in sync with init/claudemd-generator.ts
+// ────────────────────────────────────────────────────────────────────────────
+export const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
+export const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
+// Legacy markers from earlier moflo versions — detected on drift checks so we
+// can offer to replace the legacy block with the current marker pair.
+export const LEGACY_MARKER_STARTS = [
+    '<!-- MOFLO:START -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:START -->',
+];
+export const LEGACY_MARKER_ENDS = [
+    '<!-- MOFLO:END -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:END -->',
+];
+// ────────────────────────────────────────────────────────────────────────────
+// Block extraction
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Locate the MoFlo-injected block in `claudeMdContents`, normalising line
+ * endings so a CRLF file matches an LF canonical block (Windows consumers
+ * regularly hit this — git autocrlf can flip the source bytes on checkout).
+ *
+ * Returns null when `contents` is null/undefined/empty, or when no marker
+ * pair is found. Includes the marker strings themselves in the extracted
+ * block, matching `MARKER_START…MARKER_END` exactly so a byte-for-byte
+ * compare against the canonical block works.
+ */
+export function extractInjectedBlock(claudeMdContents) {
+    if (!claudeMdContents)
+        return null;
+    const normalised = claudeMdContents.replace(/\r\n/g, '\n');
+    // Try the current marker pair first, then each legacy pair. markerIndex:
+    //   0  → current MARKER_START/MARKER_END
+    //   1+ → LEGACY_MARKER_STARTS[markerIndex - 1] / LEGACY_MARKER_ENDS[markerIndex - 1]
+    const starts = [MARKER_START, ...LEGACY_MARKER_STARTS];
+    const ends = [MARKER_END, ...LEGACY_MARKER_ENDS];
+    for (let i = 0; i < starts.length; i++) {
+        const startIdx = normalised.indexOf(starts[i]);
+        if (startIdx < 0)
+            continue;
+        const endIdx = normalised.indexOf(ends[i], startIdx + starts[i].length);
+        if (endIdx <= startIdx)
+            continue;
+        const endInclusive = endIdx + ends[i].length;
+        return {
+            block: normalised.substring(startIdx, endInclusive),
+            start: startIdx,
+            end: endInclusive,
+            markerIndex: i,
+        };
+    }
+    return null;
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Drift detection
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Trim `canonical` to the bytes between (and including) the current MoFlo
+ * markers. `generateClaudeMd()` appends a trailing newline that callers
+ * commonly include in the result; the in-file block does not carry that
+ * newline, so we strip trailing whitespace before comparing.
+ */
+function canonicalBlock(canonical) {
+    return canonical.replace(/\r\n/g, '\n').trimEnd();
+}
+/**
+ * Classify a consumer's CLAUDE.md against the canonical injected block.
+ *
+ * `claudeMdContents` should be the result of `readFileSync(<root>/CLAUDE.md)`
+ * or null/undefined when the file is absent. `canonical` is the output of
+ * `generateClaudeMd({})` from `init/claudemd-generator.ts`.
+ */
+export function computeInjectionDrift(claudeMdContents, canonical) {
+    if (claudeMdContents === null || claudeMdContents === undefined) {
+        return { state: 'no-file' };
+    }
+    const extracted = extractInjectedBlock(claudeMdContents);
+    if (!extracted) {
+        return { state: 'no-marker' };
+    }
+    if (extracted.markerIndex > 0) {
+        return { state: 'legacy-marker', legacyMarkerIndex: extracted.markerIndex - 1 };
+    }
+    const currentBlock = extracted.block;
+    const wantBlock = canonicalBlock(canonical);
+    if (currentBlock === wantBlock) {
+        return { state: 'in-sync' };
+    }
+    return { state: 'drifted' };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Replacement
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Apply the canonical block to `claudeMdContents`, returning the new
+ * contents and a `changed` flag indicating whether any bytes differ. The
+ * caller writes the file (or persists in-memory state) — this function does
+ * no I/O so it's safe to call from any execution context.
+ *
+ * Behavior by input state:
+ *  - `no-file` → returns `{ contents: canonical, changed: true }` so the
+ *    caller can write a fresh CLAUDE.md (e.g. `flo init` first-run).
+ *  - `no-marker` → APPENDS the canonical block to the end of the existing
+ *    contents (matches `bin/setup-project.mjs:updateClaudeMd` append path).
+ *  - `legacy-marker` → REPLACES the legacy block in-place with the canonical block.
+ *  - `in-sync` → no change.
+ *  - `drifted` → REPLACES the existing block in-place with the canonical block.
+ */
+export function applyInjectionReplacement(claudeMdContents, canonical) {
+    const want = canonicalBlock(canonical);
+    if (claudeMdContents === null || claudeMdContents === undefined) {
+        return { contents: `# Project Configuration\n\n${want}\n`, changed: true, state: 'in-sync' };
+    }
+    const extracted = extractInjectedBlock(claudeMdContents);
+    if (!extracted) {
+        // No marker — append the canonical block to the end (idempotent for
+        // future runs because the appended block will then be located on
+        // subsequent extractions).
+        const sep = claudeMdContents.endsWith('\n') ? '\n' : '\n\n';
+        const next = claudeMdContents + sep + want + '\n';
+        return { contents: next, changed: true, state: 'in-sync' };
+    }
+    // We located a marker pair (current or legacy). If content already matches
+    // the canonical block, nothing to do.
+    if (extracted.markerIndex === 0 && extracted.block === want) {
+        return { contents: claudeMdContents, changed: false, state: 'in-sync' };
+    }
+    // Operate on the line-ending-normalised view so the byte offsets we record
+    // line up with the actual replacement window. The output keeps LF endings
+    // — the launcher and setup-project both write LF.
+    const normalised = claudeMdContents.replace(/\r\n/g, '\n');
+    const next = normalised.substring(0, extracted.start) + want + normalised.substring(extracted.end);
+    return { contents: next, changed: true, state: 'in-sync' };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Human-readable status for healer + launcher output
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * Short one-line summary describing a drift state. Used by `flo doctor` and
+ * the session-start launcher when reporting status to the user.
+ */
+export function formatInjectionDriftStatus(report) {
+    switch (report.state) {
+        case 'no-file': return 'CLAUDE.md not found';
+        case 'no-marker': return 'CLAUDE.md has no moflo injection block';
+        case 'legacy-marker': return 'CLAUDE.md uses a legacy moflo marker pair';
+        case 'in-sync': return 'CLAUDE.md injection block matches reference';
+        case 'drifted': return 'CLAUDE.md injection block has drifted from reference';
+    }
+}
+//# sourceMappingURL=claudemd-injection.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.10.6';
+export const VERSION = '4.10.7';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.10.6",
+  "version": "4.10.7",
   "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.5",
+    "moflo": "^4.10.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"