moflo 4.9.12 → 4.9.13

package/.claude/skills/eldar/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: eldar
+description: Consult the Eldar — audit a project's moflo + Claude Code setup for portable, high-leverage gaps and guide remediation. Default mode is read-only audit with severity-ranked findings; --fix presents an interactive triage menu and walks the user through each chosen fix (healer, missing CLAUDE.md, sparse guidance, hook/MCP wiring, empty memory namespaces, stack→guidance gaps). Use when starting in a new project, when Claude feels lost or inefficient, when guidance/CLAUDE.md is sparse, or as a periodic health check.
+arguments: "[--fix]"
+---
+
+# /eldar — Consult the Eldar
+
+The Eldar audit a project's moflo + Claude Code setup for portable, high-leverage gaps. **Audit is read-only by default; `--fix` walks through remediation.** The Eldar consult the **Healer** (`flo healer`, the thematic alias for `flo doctor`), they do not replace them.
+
+**Arguments:** $ARGUMENTS
+
+## Modes
+
+| Mode | Trigger | What it does |
+|------|---------|--------------|
+| Audit | no flag (default) | Read-only scan; produces categorized findings + top-3 recommendation |
+| Fix | `--fix` | Audit, then interactive triage menu; user picks findings to address one at a time |
+
+## Step 0 — Memory First
+
+Before any file reads, run:
+
+```
+mcp__moflo__memory_search { query: "guidance rules project conventions stack", namespace: "guidance" }
+```
+
+The memory-first gate blocks reads otherwise. The search also surfaces any project-specific conventions the Eldar should weigh in their findings.
+
+## Step 1 — Run the Audit
+
+Walk the checklist below in order. Each check is a single category in the final report. Be explicit about what you find — both presence and absence. Severities: `error` (blocks productive work), `warn` (degrades quality), `info` (suggestion).
+
+### 1a. Setup Health — call the Healer
+
+```bash
+npx moflo healer --json
+```
+
+Parse the JSON output. Surface every `failed` check as `error`, every `warn` as `warn`. Do **not** invoke `flo doctor` directly — use the `healer` alias for thematic consistency.
+
+### 1b. Index Freshness
+
+Check for `.moflo/moflo.db` (existence + mtime). Query memory namespaces to confirm guidance + code-map are populated:
+
+```
+mcp__moflo__memory_stats — { namespace: "guidance" }
+mcp__moflo__memory_stats — { namespace: "code-map" }
+```
+
+Flag if `entries === 0` (warn) or db missing (error).
+
+### 1c. Version Skew
+
+```bash
+npm view moflo version    # latest published
+node -e "console.log(require('./package.json').devDependencies?.moflo || require('./package.json').dependencies?.moflo || 'not-installed')"
+```
+
+Compute minor-version delta. Warn if behind by ≥3 minors; info if behind by 1–2.
+
+### 1d. Model & Token Routing
+
+```
+mcp__moflo__hooks_model-stats — {}
+```
+
+If recent sonnet→opus escalation rate exceeds ~30%, flag as `info`: "router escalating frequently — see `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` for tuning". If stats unavailable (no history), skip silently.
+
+### 1e. CLAUDE.md
+
+Check `CLAUDE.md` (and `.claude/CLAUDE.md`) for:
+
+| Check | Threshold | Severity |
+|-------|-----------|----------|
+| Exists | required | error if missing |
+| Line count | 20–500 | warn if outside range |
+| Referenced files exist | every relative path it cites | warn per missing path |
+
+Use `Grep` over the file content for `\.claude/[a-z-]+/[a-z-]+\.md` patterns and verify each path resolves.
+
+### 1f. Guidance Content
+
+Count `.md` files under `.claude/guidance/` (recursive). Severity table:
+
+| File count | Severity |
+|------------|----------|
+| 0 | warn — "no guidance docs; Claude has nothing project-specific to follow" |
+| 1–2 | warn — "very sparse guidance" |
+| 3–10 | info |
+| 11+ | info |
+
+### 1g. Guidance Structure (only if 1f found ≥1 file)
+
+Apply the universal rules from `.claude/guidance/shipped/moflo-guidance-rules.md`. For each `.md` file, check:
+
+- Has `**Purpose:**` line right after H1
+- Has `## See Also` at end
+- Under 500 lines
+- H2 headings are specific (not "Overview", "Configuration", "Examples")
+- No hedged language in rule contexts (`should`, `might`, `consider`)
+
+Do **not** duplicate `/guidance -a`'s logic verbatim — just produce a one-line summary per file (`<file>: <N issues>`). The Eldar surface gaps; `/guidance -a` does the deep audit.
+
+### 1h. Memory Health
+
+For each of the canonical namespaces, check entry count:
+
+```
+mcp__moflo__memory_stats — { namespace: "guidance" }
+mcp__moflo__memory_stats — { namespace: "patterns" }
+mcp__moflo__memory_stats — { namespace: "learnings" }
+```
+
+Flag empty `learnings` as `info` (project hasn't accumulated decisions yet — fine for new projects). Flag empty `guidance` as `warn` (no indexed guidance means semantic search is degraded).
+
+### 1i. Hooks & MCP Wiring
+
+Read `.claude/settings.json`. Check:
+
+| Check | Severity |
+|-------|----------|
+| Session-start hook references the moflo launcher | error if missing |
+| `mcpServers.moflo` is configured | error if missing |
+| `hooks` section exists with at least pre-task/post-task entries | warn if absent |
+
+If settings.json is malformed JSON, surface as `error`.
+
+### 1j. Settings Sanity
+
+Spot-check `.claude/settings.json` for:
+
+- `permissions` block exists (info if absent — every prompt becomes a confirmation)
+- `env` block has at least the moflo entries the launcher writes
+- `statusLine` is configured (info — quality-of-life, not blocking)
+
+### 1k. Spell Inventory
+
+```bash
+npx moflo spell list
+```
+
+Flag `info` if count is 0 (no spells registered — user may not know they exist).
+
+### 1l. Subagent Fleet
+
+```
+Glob — { pattern: ".claude/agents/**/*.md" }
+```
+
+Count the result. `info` if 0 (no project-specific subagents — user is relying entirely on built-ins).
+
+### 1m. Stack → Guidance Cross-Reference (highest leverage)
+
+Detect the project's stack from manifests:
+
+| Manifest | Detected stack |
+|----------|----------------|
+| `package.json` deps | Node — inspect for React, Next, Drizzle, Prisma, Express, NestJS, Vite, etc. |
+| `pyproject.toml` / `requirements.txt` | Python — Django, FastAPI, SQLAlchemy, etc. |
+| `Cargo.toml` | Rust — axum, tokio, sqlx, etc. |
+| `go.mod` | Go — gin, sqlc, gorm, etc. |
+| `Gemfile` | Ruby — Rails, Sidekiq, etc. |
+
+For each detected technology, check whether `.claude/guidance/` mentions it (Grep for the technology name across the directory). Each `(detected stack item, no guidance match)` pair becomes one `info` finding: "uses Drizzle ORM but no DB-conventions guidance — high-leverage gap".
+
+This is the **highest-impact finding** for new adopters. Lead with it in the recommendation.
+
+### 1n. Anti-Pattern from History (best-effort, optional)
+
+If recent transcripts/commits are accessible, scan them for repeated manual work that an existing spell or agent already covers (e.g., 5+ separate `git status`/`git diff`/run-tests sequences in a session that `/simplify` would have handled). Surface as `info`: "consider /simplify for review loops". If unavailable, skip silently — never block the audit on this.
+
+## Step 2 — Render the Report
+
+Output a single table grouped by category, sorted by severity (`error` → `warn` → `info`):
+
+```
+ELDAR AUDIT — <project name>
+─────────────────────────────
+
+Category               Finding                                    Severity
+─────────────────────────────────────────────────────────────────────────
+Setup health           Healer reports 0 errors, 1 warning         warn
+Index freshness        Guidance index empty                       warn
+CLAUDE.md              File missing                               error
+Guidance content       0 docs in .claude/guidance/                warn
+Memory health          guidance namespace empty                   warn
+Stack → guidance       Drizzle ORM in deps; no DB guidance        info
+Stack → guidance       React Native; no mobile guidance           info
+Hooks & MCP wiring     all wired                                  ok
+... (etc) ...
+```
+
+Then list the **top 3 ranked recommendations** in plain English, with rationale and citation:
+
+```
+TOP 3 RECOMMENDATIONS
+─────────────────────
+
+1. Add CLAUDE.md (error)
+   Without it, Claude has no project entry point. Use the Eldar's
+   stack-aware scaffold via `/eldar --fix`.
+
+2. Add Drizzle conventions guidance (info — high leverage)
+   You use Drizzle ORM but have no DB-conventions doc. This is the
+   single highest-leverage gap for getting Claude to write idiomatic
+   queries and migrations in your codebase.
+   See: .claude/guidance/shipped/moflo-guidance-rules.md
+
+3. Run `flo healer --fix` (warn)
+   One auto-fixable warning. Run via `/eldar --fix` and select Healer.
+```
+
+End the audit with a one-line prompt: "Run `/eldar --fix` to address these interactively."
+
+## Step 3 — Fix Mode (`--fix` flag only)
+
+After the report, present a numbered triage menu:
+
+```
+TRIAGE MENU
+───────────
+[1] Add CLAUDE.md
+[2] Add Drizzle conventions guidance
+[3] Run flo healer --fix (1 warning)
+[4] Add empty .claude/guidance/ docs to memory namespaces
+
+Choose: all, none, or comma-separated numbers (e.g., 1,3): _
+```
+
+Drive each chosen finding through its sub-flow. Confirm before any write.
+
+### 3a. CLAUDE.md scaffold
+
+Ask the user 2–4 targeted questions based on detected stack:
+
+1. "What does this project do? (1-2 sentences for Claude's context)"
+2. "Primary tech stack confirmed: <detected list>. Anything missing?"
+3. "Any conventions Claude should follow (testing approach, branch model, etc.)?"
+4. "Any high-blast-radius areas Claude should be careful with?"
+
+Compose a CLAUDE.md draft incorporating their answers + standard moflo memory-first rule. **Show the draft to the user before writing.** Never auto-fill opinionated content.
+
+### 3b. Stack → guidance authoring
+
+For each chosen stack-gap finding:
+
+- Hand off to `/guidance` skill for the heavy lifting — it already enforces the universal rules.
+- Brief the user on what gap will be filled: "drafting Drizzle conventions doc covering query patterns, migrations, schema files".
+- Ask 2–4 targeted questions about *their* conventions (not generic Drizzle tips — Claude should follow how *they* use it).
+- The `/guidance` skill produces the draft and walks the user through the rules check.
+
+### 3c. Healer fixes
+
+```bash
+npx moflo healer --fix
+```
+
+Pass through the output verbatim. If the Healer reports manual-only fixes, surface them as next steps.
+
+### 3d. Hook/MCP wiring repair
+
+Suggest:
+
+```bash
+npx moflo init --upgrade
+```
+
+This is the standard wiring repair path. If the user is wary of running init, surface the specific missing keys from `.claude/settings.json` and offer to write them directly.
+
+### 3e. Empty namespaces
+
+Suggest concrete first entries based on detected stack. Example: "Your project uses Drizzle. Want me to seed `learnings` with the most common Drizzle gotchas as a starting set? You'd review each before storage."
+
+If the user declines, that's fine — empty `learnings` is a valid state for a young project.
+
+### 3f. After each fix
+
+After each chosen fix completes, ask: "Continue to next finding? (y/n)". Don't run them all in a batch — every change is high-leverage and deserves the user's attention.
+
+## Step 4 — Wrap-Up
+
+After audit (or audit + chosen fixes), end with:
+
+- **Audit-only**: One sentence — what was found, what to do next.
+- **Fix mode**: One sentence per applied fix, plus a closing line on what remains.
+
+Never leave the user without a clear next step.
+
+## Important
+
+- **Memory-first is mandatory.** Step 0 runs the search; the gate blocks reads otherwise.
+- **Call the Healer, not the Doctor.** `npx moflo healer` (alias) — never `flo doctor` — for thematic consistency.
+- **No auto-write of opinionated content.** Every guidance doc, every CLAUDE.md draft, every namespace seed gets shown to the user first.
+- **Portable only.** This skill ships to consumers via `.claude/skills/**/*.md` in the package files array. Never assume moflo source paths or moflo-internal state.
+- **No kitchen sink.** The audit checklist is locked at the categories above. New checks require a specific portable benefit and an issue to discuss them.
+- **Read-only by default.** `/eldar` (no flag) never writes. Only `--fix` writes, and only with per-finding confirmation.
+- **Hand off to specialists.** `/guidance` for guidance authoring, `flo healer --fix` for setup repair, `flo init --upgrade` for wiring. The Eldar route, they don't reimplement.
+
+## See Also
+
+- `.claude/guidance/shipped/moflo-guidance-rules.md` — Universal guidance writing rules used by `/guidance` and surfaced in 1g
+- `.claude/skills/guidance/SKILL.md` — The skill `/eldar --fix` hands off to for guidance authoring
+- `.claude/guidance/shipped/moflo-core-guidance.md` — moflo CLI / hooks / memory reference; useful when explaining wiring findings
+- `.claude/guidance/shipped/moflo-claude-swarm-cohesion.md` — Subagent + task coordination reference cited in routing findings

package/README.md

@@ -431,6 +431,18 @@ Inside your AI client, use the `/spell-builder` skill to create, edit, and valid
 /spell-builder                           # Start the spell builder
 ```
 
+### Other AI-client skills shipped with MoFlo
+
+Beyond `/flo`, `/spell-builder`, and `/eldar`, MoFlo ships a handful of focused slash-command skills that work in any consumer project once you `flo init`:
+
+| Skill | Purpose |
+|-------|---------|
+| `/guidance` | Author and audit guidance docs in `.claude/guidance/`. Default mode walks you through one doc; `/guidance -a` audits every doc against the universal guidance rules (Purpose lines, See Also, line counts, hedged language). |
+| `/simplify` | Adaptive code review on the current diff. Tier-based fan-out — trivial edits get a self-review, small diffs get one routed agent, cross-cutting refactors get three parallel agents. Routes through the moflo model router for cost-aware execution. |
+| `/spell-schedule` | Schedule a spell on the local moflo daemon (cron, interval, or one-time) without leaving the chat. For remote Anthropic-cloud agents on a schedule, use Claude Code's built-in `/schedule` instead. |
+
+Run any of them with no arguments to see full usage, or browse the source in `.claude/skills/` (each skill is a single `SKILL.md` file).
+
 ### Epics
 
 Epics are a specialized process for handling GitHub issues that contain multiple child stories. When you pass a GitHub issue to `/flo` and it's detected as an epic, MoFlo processes each child story sequentially through the full `/flo` process (research → implement → test → PR).
@@ -553,6 +565,19 @@ flo healer -c embeddings         # Check only embeddings health
 flo healer --verbose             # Verbose output
 ```
 
+#### `/eldar` — Consult the Eldar (project setup audit + wizard)
+
+Where the Healer checks your moflo install, `/eldar` audits how Claude is set up to *use* the project — guidance, CLAUDE.md, memory namespaces, hook/MCP wiring, model routing, and stack-aware guidance gaps — then walks you through fixing whichever findings you pick. Use it when starting in a new project, when Claude feels lost or inefficient, or as a periodic health check.
+
+```
+/eldar                           # Read-only audit; categorized report + top-3 ranked recommendation
+/eldar --fix                     # Audit, then interactive triage menu — pick which findings to address
+```
+
+The Eldar **consult** the Healer (they call `flo healer --json` as one of the audit checks) — they don't replace it. Categories audited include setup health, index freshness, version skew, model/token routing, CLAUDE.md size + reference integrity, guidance content + structure, memory health, hook/MCP wiring, settings sanity, spell + subagent inventory, **stack → guidance cross-reference** (detects tech from package.json/pyproject.toml/Cargo.toml/go.mod and flags every detected technology with no matching guidance doc — the highest-leverage finding for new adopters), and best-effort anti-pattern detection from history.
+
+In `--fix` mode, each chosen finding drives the appropriate sub-flow: Healer for setup repair, the `/guidance` skill for guidance authoring (wizard, never autogen), a stack-aware scaffold for missing CLAUDE.md, `flo init --upgrade` for hook/MCP wiring. Every write is confirmed before it lands.
+
 #### `flo diagnose` — Integration Tests
 
 While `healer` checks your environment, `diagnose` exercises every subsystem end-to-end: memory CRUD, embedding generation, semantic search, swarm lifecycle, hive-mind consensus, task management, hooks, config, neural patterns, and init idempotency. All test data is cleaned up after each test — nothing is left behind.

package/bin/hooks.mjs

@@ -22,7 +22,7 @@
 import { spawn } from 'child_process';
 import { existsSync, appendFileSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
 import { resolve, dirname } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
@@ -520,7 +520,7 @@ let _getDaemonLockHolder = null;
 try {
   const daemonLockPath = resolve(__dirname, '..', 'src', '@claude-flow', 'cli', 'dist', 'src', 'services', 'daemon-lock.js');
   if (existsSync(daemonLockPath)) {
-    const mod = await import('file://' + daemonLockPath.replace(/\\/g, '/'));
+    const mod = await import(pathToFileURL(daemonLockPath).href);
     _getDaemonLockHolder = mod.getDaemonLockHolder;
   }
 } catch { /* fallback below */ }

package/bin/index-guidance.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'url';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath } from './lib/moflo-paths.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
+import { createProcessManager } from './lib/process-manager.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -872,36 +873,25 @@ if (!skipEmbeddings && needsEmbeddings) {
   console.log('');
   log('Spawning embedding generation in background...');
 
-  const { spawn } = await import('child_process');
-
   const embeddingScript = resolveMofloBin(
     projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
   );
 
   if (embeddingScript) {
-    const embeddingArgs = ['--namespace', NAMESPACE];
-
-    // Create log file for background process output
-    const logDir = resolve(projectRoot, '.moflo/logs');
-    if (!existsSync(logDir)) {
-      mkdirSync(logDir, { recursive: true });
+    // Register the spawn with the shared ProcessManager (#886). Stdout/stderr
+    // route through `.swarm/background.log` (pm.spawn default) instead of the
+    // bespoke `.moflo/logs/embeddings.log` so the registry, dedup, and
+    // session-end drain stay consistent with every other tracked spawn.
+    const pm = createProcessManager(projectRoot);
+    const result = pm.spawn('node', [embeddingScript, '--namespace', NAMESPACE], `build-embeddings-${NAMESPACE}`);
+    if (result.skipped) {
+      log(`Background embedding already running (PID: ${result.pid})`);
+    } else if (result.pid) {
+      log(`Background embedding started (PID: ${result.pid})`);
+      log(`Log file: .swarm/background.log`);
+    } else {
+      log('⚠️  Failed to spawn background embedding');
     }
-    const logFile = resolve(logDir, 'embeddings.log');
-    const { openSync } = await import('fs');
-    const out = openSync(logFile, 'a');
-    const err = openSync(logFile, 'a');
-
-    // Spawn in background - don't wait for completion
-    const proc = spawn('node', [embeddingScript, ...embeddingArgs], {
-      stdio: ['ignore', out, err],
-      cwd: projectRoot,
-      detached: true,
-      windowsHide: true  // Suppress command windows on Windows
-    });
-    proc.unref();  // Allow parent to exit independently
-
-    log(`Background embedding started (PID: ${proc.pid})`);
-    log(`Log file: .moflo/logs/embeddings.log`);
   } else {
     log('⚠️  Embedding script not found, skipping embedding generation');
   }

package/bin/index-patterns.mjs

@@ -27,11 +27,11 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { resolve, dirname, relative, basename, extname } from 'path';
 import { fileURLToPath } from 'url';
-import { spawn } from 'child_process';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
+import { createProcessManager } from './lib/process-manager.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -342,20 +342,23 @@ async function main() {
   // Save hash
   writeFileSync(HASH_CACHE_PATH, currentHash, 'utf-8');
 
-  // Trigger embedding generation in background
+  // Trigger embedding generation in background. Register with the shared
+  // ProcessManager (#886) so doctor's zombie scan allowlists it and the
+  // session-end / smoke-teardown drain reaps it. Stable label dedupes against
+  // the index-all chain's later `build-embeddings` step when both run within
+  // the same lock window.
   try {
     const embeddingScript = resolveMofloBin(
       projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
     );
     if (embeddingScript) {
-      const child = spawn('node', [embeddingScript, '--namespace', NAMESPACE], {
-        cwd: projectRoot,
-        detached: true,
-        stdio: 'ignore',
-        windowsHide: true,
-      });
-      child.unref();
-      debug('Embedding generation started in background');
+      const pm = createProcessManager(projectRoot);
+      const result = pm.spawn('node', [embeddingScript, '--namespace', NAMESPACE], `build-embeddings-${NAMESPACE}`);
+      if (result.skipped) {
+        debug(`Embedding generation already running (PID: ${result.pid})`);
+      } else if (result.pid) {
+        debug(`Embedding generation started in background (PID: ${result.pid})`);
+      }
     }
   } catch { /* ignore */ }
 

package/bin/session-start-launcher.mjs

@@ -409,7 +409,7 @@ try {
         ];
         const cherryPickPath = cherryPickPaths.find((p) => existsSync(p));
         if (cherryPickPath) {
-          const mod = await import(`file://${cherryPickPath.replace(/\\/g, '/')}`);
+          const mod = await import(pathToFileURL(cherryPickPath).href);
           if (typeof mod.cherryPickLearningsFromLegacy === 'function') {
             const result = await mod.cherryPickLearningsFromLegacy({ projectRoot });
             if (result.copied > 0) {
@@ -858,7 +858,7 @@ try {
       ];
       const hwPath = hwPaths.find(p => existsSync(p));
       if (hwPath) {
-        const mod = await import(`file://${hwPath.replace(/\\/g, '/')}`);
+        const mod = await import(pathToFileURL(hwPath).href);
         if (typeof mod.rewriteIncorrectHookWiring === 'function') {
           const { rewrites } = mod.rewriteIncorrectHookWiring(settings);
           if (rewrites.length > 0) {
@@ -958,8 +958,28 @@ async function runHookBlockDriftCheck() {
 
   if (report.drifted) {
     const wantRegenerate = autoUpdateConfig.hookBlockDrift === 'regenerate';
-    const safeToRegenerate = wantRegenerate && report.extra.length === 0;
-    if (safeToRegenerate && typeof mod.applyAdditiveRegeneration === 'function') {
+    // #896: regenerate is wholesale when available — the additive variant
+    // can't drop stale extras (e.g. the `gate.cjs session-reset` SessionStart
+    // hook removed in #842), which is the very case consumers hit. Older
+    // moflo installs without `applyWholesaleRegeneration` fall back to the
+    // additive path, which still heals purely-additive drift.
+    const wholesale = wantRegenerate && typeof mod.applyWholesaleRegeneration === 'function';
+    const additiveSafe = wantRegenerate && !wholesale &&
+      report.extra.length === 0 && typeof mod.applyAdditiveRegeneration === 'function';
+    if (wholesale) {
+      const { added, removed } = mod.applyWholesaleRegeneration(settings, report);
+      if (added > 0 || removed > 0) {
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+        regenerated = true;
+        const parts = [];
+        if (added > 0) parts.push(`added ${plural(added, 'missing entry')}`);
+        if (removed > 0) parts.push(`removed ${plural(removed, 'stale entry')}`);
+        emitMutation(
+          'regenerated hook block',
+          `${parts.join(', ')} (drift ${report.consumerHash} → ${report.referenceHash})`,
+        );
+      }
+    } else if (additiveSafe) {
       const { added } = mod.applyAdditiveRegeneration(settings, report);
       if (added > 0) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
@@ -1102,6 +1122,40 @@ try {
   }
 } catch { /* non-fatal */ }
 
+// ── 3d-yaml-create. Create moflo.yaml if missing (#895) ────────────────────
+// Sibling self-heal to 3d-yaml: that block APPENDS new sections to existing
+// yaml; this block CREATES the file from the canonical template when no yaml
+// exists at all. Without it, consumers picking up new defaults via npm-install
+// (e.g. PR #894 flipped model_routing.enabled to true) have no surface to
+// see/tune them — the DEFAULT_CONFIG fallback is invisible.
+//
+// Runs BEFORE 3d-yaml so the appender has a file to work with on the same
+// session. Steady-state hot path: the existsSync check below short-circuits
+// before any module load, so consumers with an existing yaml pay one stat call.
+try {
+  if (!existsSync(resolve(projectRoot, 'moflo.yaml'))) {
+    const tplPaths = [
+      resolve(projectRoot, 'node_modules/moflo/dist/src/cli/init/moflo-yaml-template.js'),
+      resolve(projectRoot, 'dist/src/cli/init/moflo-yaml-template.js'),
+    ];
+    const tplPath = tplPaths.find((p) => existsSync(p));
+    if (tplPath) {
+      const { ensureMofloYamlExists } = await import(pathToFileURL(tplPath).href);
+      const result = ensureMofloYamlExists(projectRoot);
+      if (result?.created) {
+        emitMutation(
+          'created moflo.yaml',
+          'review defaults — model routing, sandbox, gates, hooks',
+        );
+      }
+    }
+  }
+} catch (err) {
+  // Non-fatal — DEFAULT_CONFIG fallback still gives correct behavior; user
+  // just loses the visible/tunable surface until next session retries (#854).
+  emitWarning(`moflo.yaml create skipped (${errMessage(err)})`);
+}
+
 // ── 3d-yaml. Append missing top-level sections to moflo.yaml ───────────────
 // Users must never be required to re-run `moflo init` after a version bump.
 // When moflo ships a new top-level config section (e.g. sandbox:), append it
@@ -1116,7 +1170,7 @@ try {
   const upgraderPath = upgraderPaths.find((p) => existsSync(p));
   const mofloYaml = resolve(projectRoot, 'moflo.yaml');
   if (upgraderPath && existsSync(mofloYaml)) {
-    const { ensureYamlSections } = await import(`file://${upgraderPath.replace(/\\/g, '/')}`);
+    const { ensureYamlSections } = await import(pathToFileURL(upgraderPath).href);
     const appended = ensureYamlSections(mofloYaml);
     if (Array.isArray(appended) && appended.length > 0) {
       emitMutation(
@@ -1135,7 +1189,7 @@ try {
   const localShimLib = resolve(projectRoot, 'bin/lib/install-global-shim.mjs');
   const shimPath = existsSync(shimLib) ? shimLib : existsSync(localShimLib) ? localShimLib : null;
   if (shimPath) {
-    const { installGlobalShim } = await import(`file://${shimPath.replace(/\\/g, '/')}`);
+    const { installGlobalShim } = await import(pathToFileURL(shimPath).href);
     const shimResult = installGlobalShim({ silent: true });
     if (shimResult?.installed) {
       emitMutation('installed global flo shim', 'bare `flo` now resolves to project install');
@@ -1162,7 +1216,7 @@ try {
   ];
   const migrationPath = migrationPaths.find((p) => existsSync(p));
   if (migrationPath) {
-    const mod = await import(`file://${migrationPath.replace(/\\/g, '/')}`);
+    const mod = await import(pathToFileURL(migrationPath).href);
     if (typeof mod.runEmbeddingsMigrationIfNeeded === 'function') {
       await mod.runEmbeddingsMigrationIfNeeded({
         out: process.stderr,
@@ -1198,7 +1252,7 @@ try {
   ];
   const purgePath = purgePaths.find((p) => existsSync(p));
   if (purgePath) {
-    const { purgeSoftDeletedEntries } = await import(`file://${purgePath.replace(/\\/g, '/')}`);
+    const { purgeSoftDeletedEntries } = await import(pathToFileURL(purgePath).href);
     const result = await purgeSoftDeletedEntries();
     if (result?.purged > 0) {
       emitMutation(
@@ -1230,7 +1284,7 @@ try {
   ];
   const purgePath = purgePaths.find((p) => existsSync(p));
   if (purgePath) {
-    const { purgeEphemeralNamespaces } = await import(`file://${purgePath.replace(/\\/g, '/')}`);
+    const { purgeEphemeralNamespaces } = await import(pathToFileURL(purgePath).href);
     const result = await purgeEphemeralNamespaces();
     if (result?.purged > 0) {
       emitMutation(

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

@@ -593,6 +593,20 @@ export async function checkHookBlockDrift() {
             message: 'drift check skipped — claudeFlow.hooks.locked: true',
         };
     }
+    // #896: respect `auto_update.hook_block_drift: off` — opt-out for consumers
+    // who explicitly don't want drift surfaced (mirrors the launcher's behaviour).
+    try {
+        const { loadMofloConfig } = await import('../config/moflo-config.js');
+        const cfg = loadMofloConfig(projectDir);
+        if (cfg.auto_update.hook_block_drift === 'off') {
+            return {
+                name: 'Hook Block Drift',
+                status: 'pass',
+                message: 'drift check skipped — auto_update.hook_block_drift: off',
+            };
+        }
+    }
+    catch { /* config read failure — fall through to drift check */ }
     const report = computeHookBlockDrift(settings.hooks ?? {});
     if (!report.drifted) {
         return {