moflo 4.9.9 → 4.9.10

package/.claude/helpers/prompt-hook.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { execFileSync } from 'child_process';
+import { readFileSync } from 'fs';
 import { resolve } from 'path';
 
 // Read stdin JSON from Claude Code
@@ -70,6 +71,19 @@ if (TEST_HINTS.test(lower)) {
   }
 }
 
-var parts = [output.trim(), nsHint].filter(Boolean);
-if (parts.length) process.stdout.write(parts.join('\n') + '\n');
+// #867 — surface post-install restart notice. File is written by
+// scripts/post-install-notice.mjs and cleared by the SessionStart launcher
+// once the running moflo matches the file's version, so the file's
+// existence at prompt-time is itself the "still needs restart" signal.
+var restartNotice = '';
+try {
+  var pendingPath = resolve(projectDir, '.moflo', 'restart-pending.json');
+  var pending = JSON.parse(readFileSync(pendingPath, 'utf-8'));
+  if (pending && typeof pending.message === 'string' && pending.message.length > 0) {
+    restartNotice = pending.message;
+  }
+} catch (e) { /* ENOENT or malformed — silent fast-path */ }
+
+var parts = [restartNotice, output.trim(), nsHint].filter(Boolean);
+if (parts.length) process.stdout.write(parts.join('\n\n') + '\n');
 process.exit(0);

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

@@ -0,0 +1,82 @@
+---
+name: simplify
+description: Review changed code for reuse, quality, and efficiency, then fix any issues found. Sizes review effort to the diff — trivial edits get a self-review, substantial edits get parallel agents.
+---
+
+# /simplify — Adaptive Code Review
+
+Review changed code for reuse opportunities, quality issues, and efficiency improvements. **Effort scales with diff size** — a 5-line comment trim doesn't get the same treatment as a 500-line refactor.
+
+## Phase 1: Identify changes
+
+Run `git diff HEAD` (working tree) and `git diff main...HEAD` (committed) to get the full set of changes since the branch diverged. If on `main` with uncommitted changes, just `git diff HEAD`.
+
+Treat the union of staged + unstaged + committed-since-base as the diff to review.
+
+## Phase 2: Classify the diff
+
+Pick the **smallest tier** the diff genuinely fits. When in doubt, escalate.
+
+### TRIVIAL — self-review, no agent spawn
+ALL of these must hold:
+- ≤10 net LOC changed (insertions + deletions, excluding pure whitespace)
+- Single file
+- No logic changes — only comments, formatting, renames of local vars, JSDoc, or string-literal edits
+- No new imports, no new exports, no new function/class declarations
+- No removed safety checks, error handlers, or guards
+
+Examples that qualify: trimming a comment, fixing a typo in a log message, renaming a private helper, reformatting a single block.
+Examples that DON'T qualify: changing an `if` condition, reordering function args, deleting a try/catch.
+
+### SMALL — single agent, all three categories
+ALL of these must hold:
+- ≤50 net LOC changed
+- ≤2 files
+- No structural changes (no new modules, no API additions/removals, no contract changes)
+
+Examples that qualify: extracting a constant, inlining a one-liner, swapping a `for` for a `forEach`, adding one early-return.
+
+### NORMAL — three parallel agents (the original flow)
+Anything that doesn't fit TRIVIAL or SMALL. Includes any diff that:
+- Spans 3+ files
+- Adds/removes/renames a public API
+- Changes control flow in a non-trivial way
+- Introduces or removes a dependency
+- Touches `bin/`, hooks, MCP tool handlers, or anything called out in `CLAUDE.md` as critical surface
+
+When CLAUDE.md flags a file as critical surface (SessionStart, launcher, hooks, MCP coordinator wiring, swarm/hive-mind), **always escalate to NORMAL** regardless of LOC count. Risk-weighted, not size-weighted.
+
+## Phase 3: Run the appropriate review
+
+### TRIVIAL: self-review
+Run the same three category checks (reuse / quality / efficiency) yourself, in one pass, against the diff. Most TRIVIAL diffs will be clean — the goal is to confirm, not to fan out. If you find an issue, fix it; otherwise stamp clean. Total budget: ~30 seconds, no Agent calls.
+
+### SMALL: one agent
+Launch a SINGLE Agent with subagent_type `reviewer` covering all three categories in one prompt. Pass the diff inline. Budget: ~1 minute.
+
+```
+Agent — subagent_type: "reviewer", prompt: "Review this diff for reuse, quality, and efficiency. <diff inline>. Flag specific issues with file:line; skip generic advice. Under 200 words."
+```
+
+### NORMAL: three parallel agents (original flow)
+Launch three agents in a single message — Reuse, Quality, Efficiency — passing the full diff to each. Use the original flow's category checklists.
+
+**Reuse**: existing helpers/utilities that should be used instead; duplicated patterns; new functions that re-implement something already in the codebase.
+
+**Quality**: redundant state, parameter sprawl, copy-paste with variation, leaky abstractions, stringly-typed code, nested conditionals 3+ levels, unnecessary comments (WHAT-explanations, task references).
+
+**Efficiency**: unnecessary work, missed concurrency, hot-path bloat, recurring no-op updates, TOCTOU existence checks, unbounded structures, over-broad reads.
+
+## Phase 4: Fix or skip
+
+Aggregate findings. Fix each one directly. False positives or not-worth-fixing — note and skip without arguing. If TRIVIAL self-review found nothing, just confirm clean and exit.
+
+If fixes were made, re-run tests to confirm nothing broke. If tests fail after a fix, revert it.
+
+## Phase 5: Stamp the gate
+
+Whatever tier ran, the gate (`check-before-pr`) registers /simplify as having executed. The skill is satisfied.
+
+## Briefly summarize
+
+End with one or two sentences: which tier, what was fixed (or "clean — no changes"). No headers, no bullets unless needed.

package/bin/generate-code-map.mjs

@@ -32,6 +32,7 @@ import { execSync, execFileSync, spawn } from 'child_process';
 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 { resolveMofloBin } from './lib/resolve-bin.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -914,11 +915,9 @@ async function main() {
 }
 
 async function runEmbeddings() {
-  const embedCandidates = [
-    resolve(dirname(fileURLToPath(import.meta.url)), 'build-embeddings.mjs'),
-    resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-  ];
-  const embedScript = embedCandidates.find(p => existsSync(p));
+  const embedScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
   if (!embedScript) return;
 
   log('Generating embeddings for code-map...');

package/bin/hooks.mjs

@@ -25,6 +25,7 @@ import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createProcessManager } from './lib/process-manager.mjs';
 import { shouldDaemonAutoStart } from './lib/daemon-config.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -449,21 +450,10 @@ function spawnWindowless(cmd, args, description) {
   return result;
 }
 
-// Resolve a moflo npm bin script, falling back to local .claude/scripts/ copy
+// Resolve a moflo bin script via the shared helper (bin/lib/resolve-bin.mjs).
+// Bin-first ordering — see #866 / #869.
 function resolveBinOrLocal(binName, localScript) {
-  // 1. npm bin from moflo package (always up to date with published version)
-  const mofloScript = resolve(projectRoot, 'node_modules/moflo/bin', localScript);
-  if (existsSync(mofloScript)) return mofloScript;
-
-  // 2. npm bin from .bin (symlinked by npm install)
-  const npmBin = resolve(projectRoot, 'node_modules/.bin', binName);
-  if (existsSync(npmBin)) return npmBin;
-
-  // 3. Local .claude/scripts/ copy (may be stale but better than nothing)
-  const localPath = resolve(projectRoot, '.claude/scripts', localScript);
-  if (existsSync(localPath)) return localPath;
-
-  return null;
+  return resolveMofloBin(projectRoot, binName, localScript);
 }
 
 // Run the guidance indexer in background (non-blocking - used for session start and file changes)

package/bin/index-all.mjs

@@ -25,6 +25,7 @@ import {
   saveStepFingerprint,
   cleanupLegacyFingerprint,
 } from './lib/index-fingerprint.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 // Cap fastembed/ONNX thread count when spawning the heavy steps. Without
 // this, ONNX defaults to one thread per CPU core (22+ on a modern dev box),
@@ -61,16 +62,7 @@ function log(msg) {
 }
 
 function resolveBin(binName, localScript) {
-  const mofloScript = resolve(projectRoot, 'node_modules/moflo/bin', localScript);
-  if (existsSync(mofloScript)) return mofloScript;
-  const npmBin = resolve(projectRoot, 'node_modules/.bin', binName);
-  if (existsSync(npmBin)) return npmBin;
-  const localPath = resolve(projectRoot, '.claude/scripts', localScript);
-  if (existsSync(localPath)) return localPath;
-  // Also check bin/ directory (for development use)
-  const binPath = resolve(projectRoot, 'bin', localScript);
-  if (existsSync(binPath)) return binPath;
-  return null;
+  return resolveMofloBin(projectRoot, binName, localScript, { includeDevFallback: true });
 }
 
 function getLocalCliPath() {

package/bin/index-guidance.mjs

@@ -27,6 +27,7 @@ import { resolve, relative, dirname, basename, extname } from 'path';
 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';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 
@@ -873,14 +874,11 @@ if (!skipEmbeddings && needsEmbeddings) {
 
   const { spawn } = await import('child_process');
 
-  // Look for build-embeddings script in multiple locations:
-  // 1. Shipped with moflo (node_modules/moflo/bin/)
-  // 2. Project-local (.claude/scripts/)
-  const mofloScript = resolve(__dirname, 'build-embeddings.mjs');
-  const projectLocalScript = resolve(projectRoot, '.claude/scripts/build-embeddings.mjs');
-  const embeddingScript = existsSync(mofloScript) ? mofloScript : projectLocalScript;
+  const embeddingScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
 
-  if (existsSync(embeddingScript)) {
+  if (embeddingScript) {
     const embeddingArgs = ['--namespace', NAMESPACE];
 
     // Create log file for background process output

package/bin/index-patterns.mjs

@@ -28,10 +28,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from
 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';
-const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -75,6 +75,9 @@ function ensureDbDir() {
 
 async function getDb() {
   ensureDbDir();
+  // Lazy: hash-cache-match and no-source-files early-exits in main() never
+  // reach this, and the sql.js wasm cold-load is ~400ms otherwise wasted.
+  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
   const SQL = await initSqlJs();
   let db;
   if (existsSync(DB_PATH)) {
@@ -341,14 +344,9 @@ async function main() {
 
   // Trigger embedding generation in background
   try {
-    // Check __dirname first (works in both dev bin/ and consumer .claude/scripts/),
-    // then fall back to node_modules/moflo/bin/ for consumer projects
-    const candidates = [
-      resolve(__dirname, 'build-embeddings.mjs'),
-      resolve(projectRoot, 'node_modules/moflo/bin/build-embeddings.mjs'),
-      resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-    ];
-    const embeddingScript = candidates.find(p => existsSync(p));
+    const embeddingScript = resolveMofloBin(
+      projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+    );
     if (embeddingScript) {
       const child = spawn('node', [embeddingScript, '--namespace', NAMESPACE], {
         cwd: projectRoot,

package/bin/index-tests.mjs

@@ -28,6 +28,7 @@ import { fileURLToPath } from 'url';
 import { execSync, execFileSync, spawn } from 'child_process';
 import { mofloResolveURL } from './lib/moflo-resolve.mjs';
 import { memoryDbPath, MOFLO_DIR } from './lib/moflo-paths.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
 const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
 
@@ -687,11 +688,9 @@ async function main() {
 }
 
 async function runEmbeddings() {
-  const embedCandidates = [
-    resolve(dirname(fileURLToPath(import.meta.url)), 'build-embeddings.mjs'),
-    resolve(projectRoot, '.claude/scripts/build-embeddings.mjs'),
-  ];
-  const embedScript = embedCandidates.find(p => existsSync(p));
+  const embedScript = resolveMofloBin(
+    projectRoot, 'flo-embeddings', 'build-embeddings.mjs', { includeDevFallback: true },
+  );
   if (!embedScript) return;
 
   log('Generating embeddings for tests...');

package/bin/lib/resolve-bin.mjs

@@ -0,0 +1,62 @@
+/**
+ * Shared moflo bin-script path resolver.
+ *
+ * Resolves a moflo bin script in a consumer project, preferring the
+ * npm-installed copy over the .claude/scripts/ mirror so the spawned process
+ * matches the installed package version.
+ *
+ * Resolution order (intentional — see #866):
+ *   1. <projectRoot>/node_modules/moflo/bin/<localScript>  — published, atomic
+ *   2. <projectRoot>/node_modules/.bin/<binName>           — npm-managed alias (only if binName given)
+ *   3. <projectRoot>/.claude/scripts/<localScript>         — derived sync, can lag a session
+ *   4. <projectRoot>/bin/<localScript>                     — DEV ONLY, opt-in via includeDevFallback
+ *
+ * Why bin-first matters: the .claude/scripts/ mirror is updated by a sync
+ * step that races the launcher's section-3 file copies during the very
+ * upgrade session, so a still-stale mirror can spawn pre-upgrade argv into
+ * a post-upgrade chain (#866). The npm package copy is updated atomically
+ * by `npm install moflo`, so spawning from there guarantees the running
+ * script matches the installed package.
+ *
+ * Cross-platform: paths are joined via `node:path.resolve`, which normalises
+ * separators on Windows + POSIX. Callers compute `projectRoot` themselves
+ * (typically via findProjectRoot()) so this helper has no implicit cwd.
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+
+/**
+ * @param {string} projectRoot     Consumer's project root (caller-computed).
+ * @param {string|null} binName    npm bin alias (e.g. 'flo-index'), or null/undefined when no alias exists.
+ * @param {string} localScript     Script filename (e.g. 'index-guidance.mjs').
+ * @param {{ includeDevFallback?: boolean }} [opts]
+ *   includeDevFallback: also probe `<projectRoot>/bin/<localScript>` for source-tree dev.
+ * @returns {string|null}          Resolved absolute path, or null when no candidate exists.
+ */
+export function resolveMofloBin(projectRoot, binName, localScript, opts = {}) {
+  for (const candidate of mofloBinCandidates(projectRoot, binName, localScript, opts)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Pure-function variant — returns the candidate list in resolution order
+ * without touching the filesystem. Used by the source-invariant test that
+ * pins the bin-first ordering, and by callers that want to log what was
+ * probed when nothing resolved.
+ */
+export function mofloBinCandidates(projectRoot, binName, localScript, opts = {}) {
+  const candidates = [
+    resolve(projectRoot, 'node_modules', 'moflo', 'bin', localScript),
+  ];
+  if (binName) {
+    candidates.push(resolve(projectRoot, 'node_modules', '.bin', binName));
+  }
+  candidates.push(resolve(projectRoot, '.claude', 'scripts', localScript));
+  if (opts.includeDevFallback) {
+    candidates.push(resolve(projectRoot, 'bin', localScript));
+  }
+  return candidates;
+}

package/bin/session-start-launcher.mjs

@@ -13,6 +13,7 @@ import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
+import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 // Headless skip (#860). The daemon's headless workers spawn `claude --print`
 // with CLAUDE_CODE_HEADLESS=true (see src/cli/services/headless-worker-
@@ -1125,19 +1126,15 @@ if (mutationCount > 0) {
 // ── 4. Spawn background tasks ───────────────────────────────────────────────
 
 // hooks.mjs session-start (daemon, indexer, pretrain, HNSW, neural patterns).
-// Prefer the npm-bin copy over the `.claude/scripts/` mirror (#866). The mirror
-// is a derived sync that races the launcher's section-3 file copies during the
-// very upgrade session — spawning the still-stale `.claude/scripts/hooks.mjs`
-// then chaining `__dirname/index-all.mjs` produces an orphan running pre-
-// upgrade argv (e.g. `rebuild-index --force` after #859 had already dropped
-// it). The bin/ copy is updated atomically by `npm install moflo` (single-
-// step), so spawning from there guarantees the running hook code matches the
-// installed package. Falls back to the mirror only when the package copy is
-// unresolvable (development / symlinked installs).
-const hooksPkg = resolve(projectRoot, 'node_modules/moflo/bin/hooks.mjs');
-const hooksMirror = resolve(projectRoot, '.claude/scripts/hooks.mjs');
-const hooksScript = existsSync(hooksPkg) ? hooksPkg : hooksMirror;
-if (existsSync(hooksScript)) {
+// Bin-first ordering via resolveMofloBin — prefers the npm-package copy over
+// the `.claude/scripts/` mirror (#866). The mirror is a derived sync that
+// races the launcher's section-3 file copies during the very upgrade session;
+// spawning the still-stale mirror produces an orphan running pre-upgrade argv
+// (e.g. `rebuild-index --force` after #859 had already dropped it). The pkg
+// copy is updated atomically by `npm install moflo`, so spawning from there
+// guarantees the running hook code matches the installed package.
+const hooksScript = resolveMofloBin(projectRoot, null, 'hooks.mjs');
+if (hooksScript) {
   fireAndForget('node', [hooksScript, 'session-start'], 'hooks session-start');
 }
 
@@ -1152,10 +1149,8 @@ if (existsSync(hooksScript)) {
 // Run synchronously (capture stdout) so each completed migration surfaces
 // through emitMutation — Claude's session-start hook captures launcher
 // stdout and that's the only channel that reaches the user.
-const runMigrationsPkg = resolve(projectRoot, 'node_modules/moflo/bin/run-migrations.mjs');
-const runMigrationsMirror = resolve(projectRoot, '.claude/scripts/run-migrations.mjs');
-const runMigrations = existsSync(runMigrationsPkg) ? runMigrationsPkg : runMigrationsMirror;
-if (existsSync(runMigrations)) {
+const runMigrations = resolveMofloBin(projectRoot, null, 'run-migrations.mjs');
+if (runMigrations) {
   runMigrationsAndAnnounce(runMigrations);
 }
 

package/dist/src/cli/version.js

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

package/package.json

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