moflo 4.11.5 → 4.11.7

package/.claude/guidance/shipped/moflo-memory-protocol.md

@@ -4,7 +4,7 @@
 
 ## Rule (MUST)
 
-When a search hit carries a non-null `navigation` field, you MUST traverse via `mcp__moflo__memory_get_neighbors` — NOT bulk-retrieve every hit with `memory_retrieve`. The `navigation` crumb is the chunking architecture's contract; bulk-retrieving every search hit defeats it and is a protocol violation. Use `memory_retrieve` only for a single specific key you already hold, or for non-chunk entries where `navigation` is null.
+When a search hit carries a non-null `navigation` field and you need adjacent context, prefer `memory_search` with `expand: 'neighbors'` — it inlines each chunk hit's prev/next content in the SAME call (one round-trip, no re-embedding). Otherwise traverse via `mcp__moflo__memory_get_neighbors`. NEVER bulk-retrieve every hit with `memory_retrieve` — the `navigation` crumb is the chunking architecture's contract, and bulk-retrieving defeats it (protocol violation). NEVER `Read` a chunk's `parentPath` for surrounding context when `expand`/neighbors would do — a full-doc Read costs far more tokens. Use `memory_retrieve` only for a single specific key you already hold, or for non-chunk entries where `navigation` is null.
 
 ---
 
@@ -146,7 +146,8 @@ Once you have a search hit, pick the right follow-up call by what you need next.
 | You want | Use | Why |
 |----------|-----|-----|
 | Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with `navigation` (parentDoc, prev/next, chunkTitle) |
-| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, shaped entries with full nav |
+| Adjacent context AND you're still searching | `mcp__moflo__memory_search` `{ query, expand: 'neighbors' }` | Cheapest — prev/next content inlined in the search call itself, zero extra round-trips |
+| Adjacent context for a hit you already have | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, shaped entries with full nav |
 | Same-section peers (h2/h3 family) | `memory_get_neighbors` `{ include: ['siblings'] }` or `['parent','children']` | Hierarchical traversal — cheaper than re-searching |
 | Full content of one specific chunk | `mcp__moflo__memory_retrieve` `{ key }` | For a key you already hold — never for bulk-retrieving search hits |
 | Whole source doc when truly needed | `Read` `parentPath` from any chunk's nav | Disk read is cheaper than re-indexed `doc-*` |

package/bin/generate-code-map.mjs

@@ -31,7 +31,7 @@ import { fileURLToPath } from 'url';
 import { execSync, execFileSync, spawn } from 'child_process';
 import { memoryDbPath, MOFLO_DIR, findProjectRoot } from './lib/moflo-paths.mjs';
 import { openBackend } from './lib/get-backend.mjs';
-import { applyIncrementalChunks, computeContentListHash } from './lib/incremental-write.mjs';
+import { applyIncrementalChunks, schemeTaggedContentHash } from './lib/incremental-write.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
 
 
@@ -42,6 +42,16 @@ const NAMESPACE = 'code-map';
 const DB_PATH = memoryDbPath(projectRoot);
 const HASH_CACHE_PATH = resolve(projectRoot, MOFLO_DIR, 'code-map-hash.txt');
 
+// Output-scheme version for the skip-cache (#1260). Bump whenever the emitted
+// key scheme changes (chunk kinds, batch sizes, `file:` granularity) so a
+// generator upgrade forces one rebuild + orphan sweep instead of silently
+// skipping and leaving the previous scheme's rows orphaned. This is also the
+// single source of truth for the code-map scheme now that `flo memory code-map`
+// delegates here rather than shipping a second, divergent generator.
+// v2: unified scheme — invalidates every pre-#1260 cache (bare hash or the
+// old directory-level `flo memory code-map` output) exactly once on pickup.
+const SCHEME_VERSION = 2;
+
 // Directories to exclude from indexing
 const EXCLUDE_DIRS = [
   'node_modules', 'dist', 'build', '.next', 'coverage',
@@ -786,15 +796,16 @@ async function main() {
     return;
   }
 
-  // 2. Check hash for incremental skip
-  const currentHash = computeContentListHash(files);
+  // 2. Check hash for incremental skip — scheme-versioned so a scheme change
+  // invalidates the cache and forces a rebuild + orphan sweep (#1260).
+  const currentHash = schemeTaggedContentHash(files, SCHEME_VERSION);
 
   if (statsOnly) {
     const db = await getDb();
     const count = countNamespace(db);
     db.close();
     log(`Stats: ${files.length} source files, ${count} chunks in code-map namespace`);
-    log(`File list hash: ${currentHash.slice(0, 12)}...`);
+    log(`Scheme v${SCHEME_VERSION}, file list hash: ${currentHash.slice(0, 20)}...`);
     return;
   }
 

package/bin/lib/incremental-write.mjs

@@ -65,6 +65,29 @@ export function computeContentListHash(files) {
   return hasher.digest('hex');
 }
 
+/**
+ * Scheme-versioned wrapper around {@link computeContentListHash}. Prefixes the
+ * content hash with `v<schemeVersion>:` so the indexer's skip-cache encodes the
+ * OUTPUT scheme, not just the input file list (#1260).
+ *
+ * Why this is load-bearing: the skip gate short-circuits the whole
+ * extract+write pipeline (including the orphan sweep) whenever the stored hash
+ * matches. If a generator upgrade changes the emitted key scheme (e.g. drops
+ * `file:` entries, or two entry points write divergent shapes) while the source
+ * file list is unchanged, an unversioned hash still matches → the generator
+ * skips → the previous scheme's orphaned rows persist forever. Bumping
+ * `schemeVersion` invalidates every stored cache exactly once, forcing a
+ * rebuild + orphan sweep that reconciles the namespace. Legacy bare-hash caches
+ * (no `v<n>:` prefix) also mismatch, so upgrading consumers self-heal.
+ *
+ * @param {string[]} files - absolute paths
+ * @param {number|string} schemeVersion - monotonically-bumped scheme tag
+ * @returns {string} `v<schemeVersion>:<sha256>`
+ */
+export function schemeTaggedContentHash(files, schemeVersion) {
+  return `v${schemeVersion}:${computeContentListHash(files)}`;
+}
+
 /**
  * Load `key → content` for every active row in the namespace, optionally
  * scoped to keys starting with `keyPrefix` (one doc's chunks at a time —

package/dist/src/cli/commands/memory.js

@@ -10,7 +10,7 @@ import { select, confirm, input } from '../prompt.js';
 import { callMCPTool, MCPClientError } from '../mcp-client.js';
 import { openDaemonDatabase } from '../memory/daemon-backend.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
-import { legacySwarmPath, runtimePath, memoryDbPath } from '../services/moflo-paths.js';
+import { memoryDbPath } from '../services/moflo-paths.js';
 import { resolveBridgeDbPath } from '../memory/bridge-core.js';
 import { findProjectRoot } from '../services/project-root.js';
 // Memory backends
@@ -1974,129 +1974,43 @@ const rebuildIndexCommand = {
     }
 };
 // ============================================================================
-// code-map subcommand
+// code-map subcommand — delegates to the single shipped generator (#1260)
 // ============================================================================
-const EXCLUDE_DIRS = [
-    'back-office-template', 'template', '.claude', 'node_modules',
-    'dist', 'build', '.next', 'coverage',
-];
-const DIR_DESCRIPTIONS = {
-    entities: 'MikroORM entity definitions',
-    services: 'business logic services',
-    routes: 'Fastify route handlers',
-    middleware: 'request middleware (auth, validation, tenancy)',
-    schemas: 'Zod validation schemas',
-    types: 'TypeScript type definitions',
-    utils: 'utility helpers',
-    config: 'configuration',
-    migrations: 'database migrations',
-    scripts: 'CLI scripts',
-    components: 'React components',
-    pages: 'route page components',
-    contexts: 'React context providers',
-    hooks: 'React custom hooks',
-    layout: 'app shell layout',
-    themes: 'MUI theme configuration',
-    api: 'API client layer',
-    locales: 'i18n translation files',
-    tests: 'test suites',
-    e2e: 'end-to-end tests',
-};
-const TS_PATTERNS = [
-    /^export\s+(?:default\s+)?(?:abstract\s+)?class\s+(\w+)(?:\s+extends\s+([\w.]+))?(?:\s+implements\s+([\w,\s.]+))?/,
-    /^export\s+(?:default\s+)?interface\s+(\w+)(?:\s+extends\s+([\w,\s.]+))?/,
-    /^export\s+(?:default\s+)?type\s+(\w+)\s*[=<]/,
-    /^export\s+(?:const\s+)?enum\s+(\w+)/,
-    /^export\s+(?:default\s+)?(?:async\s+)?function\s+(\w+)/,
-    /^export\s+(?:default\s+)?const\s+(\w+)\s*[=:]/,
-];
-const ENTITY_DECORATOR = /@Entity\s*\(/;
-const IFACE_MAP_BATCH = 20;
-const TYPE_INDEX_BATCH = 80;
-function detectKind(line) {
-    if (/\bclass\b/.test(line))
-        return 'class';
-    if (/\binterface\b/.test(line))
-        return 'interface';
-    if (/\btype\b/.test(line))
-        return 'type';
-    if (/\benum\b/.test(line))
-        return 'enum';
-    if (/\bfunction\b/.test(line))
-        return 'function';
-    if (/\bconst\b/.test(line))
-        return 'const';
-    return 'export';
-}
-function extractTypesFromFile(filePath, projectRoot) {
-    const fullPath = pathModule.resolve(projectRoot, filePath);
-    if (!fs.existsSync(fullPath))
-        return [];
-    let content;
-    try {
-        content = fs.readFileSync(fullPath, 'utf-8');
-    }
-    catch {
-        return [];
-    }
-    const lines = content.split(/\r?\n/);
-    const types = [];
-    const seen = new Set();
-    let isEntityNext = false;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (ENTITY_DECORATOR.test(line)) {
-            isEntityNext = true;
+/**
+ * Resolve the file-level code-map generator (`bin/generate-code-map.mjs`) for
+ * `cwd`, reusing moflo's canonical bin resolver so this dist CLI command and
+ * the batch indexer (`.claude/scripts/index-all.mjs`) spawn the exact same
+ * script — one generator, one key scheme (#1260).
+ *
+ * Cross-platform: the resolver is located via a cwd-relative path (never a
+ * file-relative `../../../../` depth — that broke #1126) and imported as a
+ * `file://` URL so Windows accepts the absolute path (Rule #1). Returns null
+ * when no copy is found (broken install / not-yet-synced worktree).
+ */
+async function resolveCodeMapGenerator(cwd) {
+    const { pathToFileURL } = await import('url');
+    const resolverCandidates = [
+        pathModule.join(cwd, 'node_modules', 'moflo', 'bin', 'lib', 'resolve-bin.mjs'),
+        pathModule.join(cwd, 'bin', 'lib', 'resolve-bin.mjs'), // dev / source tree
+    ];
+    for (const resolverPath of resolverCandidates) {
+        if (!fs.existsSync(resolverPath))
             continue;
+        try {
+            const { resolveMofloBin } = await import(pathToFileURL(resolverPath).href);
+            return (resolveMofloBin(cwd, 'flo-codemap', 'generate-code-map.mjs', {
+                includeDevFallback: true,
+            }) ?? null);
         }
-        for (const pattern of TS_PATTERNS) {
-            const m = line.match(pattern);
-            if (m && m[1] && !seen.has(m[1])) {
-                seen.add(m[1]);
-                const kind = detectKind(line);
-                const bases = (m[2] || '').trim();
-                const implements_ = (m[3] || '').trim();
-                types.push({
-                    name: m[1],
-                    kind,
-                    bases: bases || null,
-                    implements: implements_ || null,
-                    isEntity: isEntityNext,
-                    file: filePath,
-                });
-                isEntityNext = false;
-                break;
-            }
-        }
-        if (isEntityNext && !line.startsWith('@') && !line.startsWith('export') && line.length > 0) {
-            isEntityNext = false;
+        catch {
+            // Fall through to the next resolver candidate.
         }
     }
-    return types;
-}
-function getProjectName(filePath) {
-    const parts = filePath.split('/');
-    if (parts[0] === 'packages' && parts.length >= 2)
-        return `${parts[0]}/${parts[1]}`;
-    if (parts[0] === 'back-office' && parts.length >= 2)
-        return `${parts[0]}/${parts[1]}`;
-    if (parts[0] === 'customer-portal' && parts.length >= 2)
-        return `${parts[0]}/${parts[1]}`;
-    if (parts[0] === 'admin-console' && parts.length >= 2)
-        return `${parts[0]}/${parts[1]}`;
-    if (parts[0] === 'webhooks' && parts.length >= 2)
-        return `${parts[0]}/${parts[1]}`;
-    if (parts[0] === 'mobile-app')
-        return 'mobile-app';
-    if (parts[0] === 'tests')
-        return 'tests';
-    if (parts[0] === 'scripts')
-        return 'scripts';
-    return parts[0];
+    return null;
 }
 const codeMapCommand = {
     name: 'code-map',
-    description: 'Generate structural code map (project overviews, directory details, type indexes) into code-map namespace',
+    description: 'Generate the structural code map (project overviews, directory details, type + file indexes) into the code-map namespace',
     options: [
         {
             name: 'force',
@@ -2134,284 +2048,49 @@ const codeMapCommand = {
         const verbose = ctx.flags.verbose;
         const statsOnly = ctx.flags.stats;
         const skipEmbeddings = ctx.flags.noEmbeddings;
-        const NAMESPACE = 'code-map';
-        const fs = await import('fs');
-        const pathMod = await import('path');
-        const { execSync } = await import('child_process');
-        const { createHash } = await import('crypto');
         const cwd = ctx.cwd || process.cwd();
-        // Post-#1168: canonical at `.moflo/memory/code-map-hash.txt`. Legacy
-        // `.swarm/code-map-hash.txt` is read-only fallback for upgrade scenarios.
-        const hashCachePath = runtimePath('memory', 'code-map-hash.txt');
-        const legacyHashCachePath = legacySwarmPath('code-map-hash.txt');
         output.writeln();
         output.writeln(output.bold('Generating Code Map'));
         output.writeln(output.dim('─'.repeat(50)));
-        // 1. Get source files via git
-        let raw;
-        try {
-            raw = execSync(`git ls-files -- "*.ts" "*.tsx" "*.js" "*.mjs" "*.jsx"`, { cwd, encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024, windowsHide: true }).trim();
-        }
-        catch {
-            output.printError('Failed to list source files via git. Is this a git repository?');
+        // Single source of truth (#1260): delegate to the one shipped generator —
+        // the same `bin/generate-code-map.mjs` that `index-all.mjs` runs. This
+        // command previously carried a SECOND, divergent generator (directory-level
+        // scheme with no `file:` entries, a path-list-only skip hash at a different
+        // cache path, and a DELETE+reinsert write that nulled embeddings). The two
+        // fought over the `code-map` namespace and accumulated orphaned rows that
+        // neither skip-cache could reconcile. Delegating here makes divergence
+        // structurally impossible.
+        const script = await resolveCodeMapGenerator(cwd);
+        if (!script) {
+            output.printError('Could not locate the code-map generator (bin/generate-code-map.mjs). Is the moflo package installed?');
             return { success: false, exitCode: 1 };
         }
-        const files = raw ? raw.split(/\r?\n/).filter((f) => {
-            for (const ex of EXCLUDE_DIRS) {
-                if (f.startsWith(ex + '/') || f.startsWith(ex + '\\'))
-                    return false;
-            }
-            return true;
-        }) : [];
-        if (files.length === 0) {
-            output.writeln('No source files found.');
-            return { success: true };
-        }
-        output.writeln(`Found ${files.length} source files`);
-        // 2. Hash check
-        const sorted = [...files].sort();
-        const currentHash = createHash('sha256').update(sorted.join('\n')).digest('hex');
-        if (statsOnly) {
-            const { db } = await openDb(cwd);
-            const stmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = ?`);
-            stmt.bind([NAMESPACE]);
-            const count = stmt.step() ? stmt.getAsObject().cnt : 0;
-            stmt.free();
-            db.close();
-            output.writeln(`Stats: ${files.length} source files, ${count} chunks in code-map namespace`);
-            output.writeln(`File list hash: ${currentHash.slice(0, 12)}...`);
-            return { success: true };
-        }
-        // Check if unchanged — canonical first, then legacy `.swarm/` fallback.
-        const cachedReadPath = fs.existsSync(hashCachePath)
-            ? hashCachePath
-            : (fs.existsSync(legacyHashCachePath) ? legacyHashCachePath : null);
-        if (!forceRegen && cachedReadPath) {
-            const cached = fs.readFileSync(cachedReadPath, 'utf-8').trim();
-            if (cached === currentHash) {
-                const { db } = await openDb(cwd);
-                const stmt = db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = ?`);
-                stmt.bind([NAMESPACE]);
-                const count = stmt.step() ? stmt.getAsObject().cnt : 0;
-                stmt.free();
-                db.close();
-                if (count > 0) {
-                    output.writeln(output.dim(`Skipping -- file list unchanged (${count} chunks in DB)`));
-                    return { success: true };
-                }
-            }
-        }
-        // 3. Extract types
-        output.writeln('Extracting type declarations...');
-        const allTypes = [];
-        const filesByProject = {};
-        const typesByProject = {};
-        const typesByDir = {};
-        for (const file of files) {
-            const project = getProjectName(file);
-            if (!filesByProject[project])
-                filesByProject[project] = [];
-            filesByProject[project].push(file);
-            const types = extractTypesFromFile(file, cwd);
-            for (const t of types) {
-                allTypes.push(t);
-                if (!typesByProject[project])
-                    typesByProject[project] = [];
-                typesByProject[project].push(t);
-                const dir = pathModule.dirname(t.file).replace(/\\/g, '/');
-                if (!typesByDir[dir])
-                    typesByDir[dir] = [];
-                typesByDir[dir].push(t);
-            }
-        }
-        output.writeln(`Extracted ${allTypes.length} types from ${Object.keys(filesByProject).length} projects`);
-        // 4. Generate chunks
-        const allChunks = [];
-        // Project overviews
-        for (const [project, projFiles] of Object.entries(filesByProject)) {
-            const types = typesByProject[project] || [];
-            const dirMap = {};
-            for (const t of types) {
-                const rel = pathModule.relative(project, pathModule.dirname(t.file)).replace(/\\/g, '/') || '(root)';
-                if (!dirMap[rel])
-                    dirMap[rel] = [];
-                dirMap[rel].push(t.name);
-            }
-            // Detect primary language
-            let tsx = 0, ts = 0, js = 0;
-            for (const f of projFiles) {
-                const ext = pathModule.extname(f);
-                if (ext === '.tsx' || ext === '.jsx')
-                    tsx++;
-                else if (ext === '.ts')
-                    ts++;
-                else
-                    js++;
-            }
-            const lang = tsx > ts && tsx > js ? 'React/TypeScript' : ts >= js ? 'TypeScript' : 'JavaScript';
-            let content = `# ${project} [${lang}, ${projFiles.length} files, ${types.length} types]\n\n`;
-            for (const dir of Object.keys(dirMap).sort()) {
-                const names = dirMap[dir];
-                const lastDir = dir.split('/').pop() || '';
-                const desc = DIR_DESCRIPTIONS[lastDir];
-                const descStr = desc ? ` -- ${desc}` : '';
-                const shown = names.slice(0, 8).join(', ');
-                const overflow = names.length > 8 ? `, ... (+${names.length - 8} more)` : '';
-                content += `  ${dir}${descStr}: ${shown}${overflow}\n`;
-            }
-            allChunks.push({
-                key: `project:${project}`,
-                content: content.trim(),
-                metadata: { kind: 'project-overview', project, language: lang, fileCount: projFiles.length, typeCount: types.length },
-                tags: ['project', project],
-            });
-        }
-        // Directory details
-        for (const [dir, types] of Object.entries(typesByDir)) {
-            if (types.length < 2)
-                continue;
-            const lastDir = dir.split('/').pop() || '';
-            const desc = DIR_DESCRIPTIONS[lastDir];
-            let content = `# ${dir} (${types.length} types)\n`;
-            if (desc)
-                content += `${desc}\n`;
-            content += '\n';
-            const sortedTypes = [...types].sort((a, b) => a.name.localeCompare(b.name));
-            for (const t of sortedTypes) {
-                const suffix = [];
-                if (t.bases)
-                    suffix.push(`: ${t.bases}`);
-                if (t.implements)
-                    suffix.push(`: ${t.implements}`);
-                const suffixStr = suffix.length ? ` ${suffix.join(' ')}` : '';
-                const fileName = pathModule.basename(t.file);
-                content += `  ${t.name}${suffixStr} (${fileName})\n`;
-            }
-            allChunks.push({
-                key: `dir:${dir}`,
-                content: content.trim(),
-                metadata: { kind: 'directory-detail', directory: dir, typeCount: types.length },
-                tags: ['directory', dir.split('/')[0]],
-            });
-        }
-        // Interface maps
-        const interfaces = new Map();
-        for (const t of allTypes) {
-            if (t.kind === 'interface' && !interfaces.has(t.name)) {
-                interfaces.set(t.name, { defined: t.file, implementations: [] });
-            }
-        }
-        for (const t of allTypes) {
-            if (t.kind !== 'class')
-                continue;
-            const impls = t.implements ? t.implements.split(',').map((s) => s.trim()) : [];
-            const bases = t.bases ? [t.bases.trim()] : [];
-            for (const iface of [...impls, ...bases]) {
-                if (interfaces.has(iface)) {
-                    interfaces.get(iface).implementations.push({ name: t.name, project: getProjectName(t.file) });
-                }
-            }
-        }
-        const mapped = Array.from(interfaces.entries())
-            .filter(([, v]) => v.implementations.length > 0)
-            .sort(([a], [b]) => a.localeCompare(b));
-        if (mapped.length > 0) {
-            const totalBatches = Math.ceil(mapped.length / IFACE_MAP_BATCH);
-            for (let i = 0; i < mapped.length; i += IFACE_MAP_BATCH) {
-                const batch = mapped.slice(i, i + IFACE_MAP_BATCH);
-                const batchNum = Math.floor(i / IFACE_MAP_BATCH) + 1;
-                let content = `# Interface-to-Implementation Map (${batchNum}/${totalBatches})\n\n`;
-                for (const [name, info] of batch) {
-                    const implStr = info.implementations.map(impl => `${impl.name} (${impl.project})`).join(', ');
-                    content += `  ${name} -> ${implStr}\n`;
-                }
-                allChunks.push({
-                    key: `iface-map:${batchNum}`,
-                    content: content.trim(),
-                    metadata: { kind: 'interface-map', batch: batchNum, totalBatches, count: batch.length },
-                    tags: ['interface-map'],
-                });
-            }
-        }
-        // Type index
-        const sortedAllTypes = [...allTypes].sort((a, b) => a.name.localeCompare(b.name));
-        const typeIdxTotalBatches = Math.ceil(sortedAllTypes.length / TYPE_INDEX_BATCH);
-        for (let i = 0; i < sortedAllTypes.length; i += TYPE_INDEX_BATCH) {
-            const batch = sortedAllTypes.slice(i, i + TYPE_INDEX_BATCH);
-            const batchNum = Math.floor(i / TYPE_INDEX_BATCH) + 1;
-            let content = `# Type Index (batch ${batchNum}, ${batch.length} types)\n\n`;
-            for (const t of batch) {
-                const ext = pathModule.extname(t.file);
-                const lang = (ext === '.tsx' || ext === '.jsx') ? 'tsx' : ext === '.ts' ? 'ts' : ext === '.mjs' ? 'esm' : 'js';
-                content += `  ${t.name} -> ${t.file} [${lang}]\n`;
-            }
-            allChunks.push({
-                key: `type-index:${batchNum}`,
-                content: content.trim(),
-                metadata: { kind: 'type-index', batch: batchNum, totalBatches: typeIdxTotalBatches, count: batch.length },
-                tags: ['type-index'],
+        const scriptArgs = [];
+        if (forceRegen)
+            scriptArgs.push('--force');
+        if (verbose)
+            scriptArgs.push('--verbose');
+        if (statsOnly)
+            scriptArgs.push('--stats');
+        if (skipEmbeddings)
+            scriptArgs.push('--no-embeddings');
+        const { execFileSync } = await import('child_process');
+        try {
+            // process.execPath (not bare 'node') so the child uses the exact same
+            // interpreter with no PATH dependency — robust on Windows where the
+            // launching node need not be on PATH (Rule #1). execFileSync passes argv
+            // as an array, so spaces in the path (e.g. "Program Files") are safe.
+            execFileSync(process.execPath, [script, ...scriptArgs], {
+                cwd,
+                stdio: 'inherit',
+                windowsHide: true,
+                timeout: 5 * 60_000,
             });
         }
-        output.writeln(`Generated ${allChunks.length} chunks`);
-        if (verbose) {
-            const projectCount = allChunks.filter(c => c.metadata.kind === 'project-overview').length;
-            const dirCount = allChunks.filter(c => c.metadata.kind === 'directory-detail').length;
-            const ifaceCount = allChunks.filter(c => c.metadata.kind === 'interface-map').length;
-            const typeIdxCount = allChunks.filter(c => c.metadata.kind === 'type-index').length;
-            output.writeln(`  Project overviews: ${projectCount}`);
-            output.writeln(`  Directory details: ${dirCount}`);
-            output.writeln(`  Interface maps:    ${ifaceCount}`);
-            output.writeln(`  Type index:        ${typeIdxCount}`);
-        }
-        // 5. Write to DB
-        output.writeln('Writing to memory database...');
-        const { db, dbPath } = await openDb(cwd);
-        // Clear old code-map entries
-        db.run(`DELETE FROM memory_entries WHERE namespace = ?`, [NAMESPACE]);
-        for (const chunk of allChunks) {
-            batchStoreEntry(db, chunk.key, NAMESPACE, chunk.content, chunk.metadata, chunk.tags);
-        }
-        saveAndCloseDb(db, dbPath);
-        // Save hash
-        const hashDir = pathModule.dirname(hashCachePath);
-        if (!fs.existsSync(hashDir)) {
-            fs.mkdirSync(hashDir, { recursive: true });
-        }
-        fs.writeFileSync(hashCachePath, currentHash, 'utf-8');
-        output.printSuccess(`${allChunks.length} chunks written to code-map namespace`);
-        // Generate embeddings unless skipped
-        if (!skipEmbeddings) {
-            output.writeln(output.dim('Generating embeddings for code-map entries...'));
-            try {
-                const { generateEmbedding } = await import('../memory/memory-initializer.js');
-                const { db: db2, dbPath: dbPath2 } = await openDb(cwd);
-                const stmt = db2.prepare(`SELECT id, content FROM memory_entries WHERE namespace = ? AND (embedding IS NULL OR embedding = '')`);
-                stmt.bind([NAMESPACE]);
-                const entries = [];
-                while (stmt.step())
-                    entries.push(stmt.getAsObject());
-                stmt.free();
-                let embedded = 0;
-                for (const entry of entries) {
-                    try {
-                        const text = entry.content.substring(0, 1500);
-                        const { embedding, dimensions, model } = await generateEmbedding(text);
-                        db2.run(`UPDATE memory_entries SET embedding = ?, embedding_model = ?, embedding_dimensions = ?, updated_at = ? WHERE id = ?`, [JSON.stringify(embedding), model, dimensions, Date.now(), entry.id]);
-                        embedded++;
-                    }
-                    catch { /* skip */ }
-                }
-                if (embedded > 0) {
-                    saveAndCloseDb(db2, dbPath2);
-                    output.printSuccess(`Generated ${embedded} embeddings`);
-                }
-                else {
-                    db2.close();
-                }
-            }
-            catch (err) {
-                output.writeln(output.dim(`  Embedding generation skipped: ${err.message}`));
-            }
+        catch (err) {
+            const code = err.status;
+            output.printError(`Code map generation failed${typeof code === 'number' ? ` (exit ${code})` : ''}: ${errorDetail(err)}`);
+            return { success: false, exitCode: typeof code === 'number' ? code : 1 };
         }
         return { success: true };
     }

package/dist/src/cli/mcp-tools/memory-tools.js

@@ -90,6 +90,20 @@ function parseNavigation(metadataJson, mode) {
         headerLevel: meta.headerLevel,
     };
 }
+// #1262 lever #1 (dedup-by-source): collapse multiple representations of the
+// SAME underlying source to one result slot. Dogfooding showed a dense query's
+// top-8 is routinely ~40% duplicates — e.g. one file indexed in code-map as
+// `file:<path>` AND in patterns as `pattern:file:<path>`, or a test surfaced as
+// both `file:<path>` and `test-file:<path>`. Path-bearing keys reduce to their
+// path; symbol/chunk/learning keys keep their own identity (a `pattern:class:X`
+// symbol view is NOT the same source as the file, so it survives separately).
+// Operates purely on logical DB keys (always forward-slash), so platform-agnostic.
+function sourceIdOf(key) {
+    const pathMatch = key.match(/^(?:pattern:)?(?:file|test-file|dir):(.+)$/);
+    if (pathMatch)
+        return `src:${pathMatch[1]}`;
+    return key.startsWith('pattern:') ? key.slice('pattern:'.length) : key;
+}
 function shapeRetrievedEntry(entry) {
     let value = entry.content;
     try {
@@ -325,39 +339,53 @@ export const memoryTools = [
     },
     {
         name: 'memory_search',
-        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search). When a result has a non-null `navigation` crumb, you MUST traverse via `memory_get_neighbors` — bulk `memory_retrieve` per hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.',
+        description: 'Semantic vector search using HNSW index (150x-12,500x faster than keyword search). On chunk hits (non-null `navigation`) you MUST get adjacent context via chunk traversal, never a full-doc `Read`: prefer `expand: "neighbors"` in THIS call (cheapest — inlines prev/next), else `memory_get_neighbors`. Bulk `memory_retrieve` per hit is a protocol violation. See `.claude/guidance/moflo-memory-protocol.md`.',
         category: 'memory',
         inputSchema: {
             type: 'object',
             properties: {
                 query: { type: 'string', description: 'Search query (semantic similarity)' },
                 namespace: { type: 'string', description: 'Namespace to search (default: all namespaces)' },
-                limit: { type: 'number', description: 'Maximum results (default: 8)' },
+                limit: { type: 'number', description: 'Maximum results (default: 8). Multiple representations of the same source (a file indexed in both code-map and patterns, a test surfaced as both file and test-file) are collapsed to one before this cap, so every slot is a distinct source.' },
                 threshold: { type: 'number', description: 'Minimum similarity threshold 0-1 (default: 0.5)' },
+                expand: {
+                    type: 'string',
+                    enum: ['neighbors'],
+                    description: "Set to 'neighbors' to inline each chunk hit's adjacent (prev/next) chunk content in this single call. Use instead of a follow-up full-doc `Read` when you need surrounding context. Off by default to keep the envelope lean.",
+                },
             },
             required: ['query'],
         },
         handler: async (input) => {
             await ensureInitialized();
-            const { searchEntries } = await getMemoryFunctions();
+            const { searchEntries, getEntry } = await getMemoryFunctions();
             const query = input.query;
             const namespace = input.namespace || 'all';
-            // #1053 S6: tighter defaults — fewer hits, higher relevance bar.
+            // #1053 S6: injected-token bar. Each returned hit is injected verbatim,
+            // so keep the cap tight — but #1262 dedup (below) makes every one of these
+            // slots a DISTINCT source rather than 8 slots holding ~5 uniques + dupes.
             const limit = input.limit || 8;
             // Falsiness check would coerce a caller-supplied 0 to default and silently
             // filter low-similarity matches; use a typeof guard so explicit zero
             // means "no threshold" (#837).
             const threshold = typeof input.threshold === 'number' ? input.threshold : 0.5;
+            // #1262 lever #3: opt-in single-call neighbor expansion.
+            const wantExpand = input.expand === 'neighbors' || input.expand === true;
+            // #1262 lever #1: over-fetch so dedup-by-source can still return a FULL
+            // `limit` distinct sources. Local HNSW makes the extra hits free (they're
+            // just not injected); 3x headroom clears the ~40% duplication observed in
+            // dogfooding. Capped so an explicit large limit can't blow up the fetch.
+            const overscan = Math.min(limit * 3, 50);
             validateMemoryInput(undefined, undefined, query);
             try {
                 const result = await searchEntries({
                     query,
                     namespace,
-                    limit,
+                    limit: overscan,
                     threshold,
                 });
                 // Parse JSON values in results
-                const results = result.results.map(r => {
+                const mapped = result.results.map(r => {
                     let value = r.content;
                     try {
                         value = JSON.parse(r.content);
@@ -379,13 +407,67 @@ export const memoryTools = [
                         navigation,
                     };
                 });
+                // #1262 lever #1: collapse duplicate representations of the same source,
+                // keeping the highest-scoring one (results arrive score-desc), then trim
+                // to `limit`. Net effect vs. the old code: `limit` DISTINCT sources
+                // instead of `limit` slots that were often ~40% near-duplicates.
+                const seenSources = new Set();
+                const results = [];
+                for (const hit of mapped) {
+                    const id = sourceIdOf(hit.key);
+                    if (seenSources.has(id))
+                        continue;
+                    seenSources.add(id);
+                    results.push(hit);
+                    if (results.length >= limit)
+                        break;
+                }
+                // #1262 lever #3: when asked, fetch each chunk hit's prev/next content
+                // inline (one round-trip) so the model doesn't fall back to a full-doc
+                // `Read` for surrounding context. Opt-in keeps the default lean.
+                if (wantExpand) {
+                    await Promise.all(results.map(async (hit) => {
+                        const nav = hit.navigation;
+                        if (!nav)
+                            return; // non-chunk hit — nothing adjacent to fetch
+                        const targets = [
+                            { position: 'prev', key: nav.prevChunk },
+                            { position: 'next', key: nav.nextChunk },
+                        ].filter((t) => Boolean(t.key));
+                        if (targets.length === 0)
+                            return;
+                        const fetched = await Promise.all(targets.map(async (t) => {
+                            const res = await getEntry({ key: t.key, namespace: hit.namespace });
+                            if (!res.found || !res.entry)
+                                return null;
+                            const entry = res.entry;
+                            let value = entry.content;
+                            try {
+                                value = JSON.parse(entry.content);
+                            }
+                            catch { /* keep string */ }
+                            return { position: t.position, key: t.key, value };
+                        }));
+                        const neighbors = fetched.filter((n) => n !== null);
+                        if (neighbors.length > 0)
+                            hit.expanded = neighbors;
+                    }));
+                }
                 notifyMemoryGate();
+                // #1262 lever #3: steer away from full-doc `Read` toward the cheap
+                // adjacent-context path — but only when it's actionable (chunk hits
+                // present and the caller didn't already expand), so the hint itself
+                // costs no tokens on the common case.
+                const nextStep = !wantExpand && results.some(r => r.navigation)
+                    ? "Chunk hits present. For adjacent context, re-call memory_search with expand:'neighbors' (one call) rather than Read-ing parentPath — full-doc Read costs far more tokens."
+                    : undefined;
                 // #1053 S6: searchTime dropped from MCP envelope (CLI keeps it for
                 // human reading); `backend` retained — doctor reads it (#1053 epic).
                 return {
                     query,
                     results,
                     total: results.length,
+                    ...(nextStep ? { nextStep } : {}),
                     backend: BACKEND_LABEL,
                 };
             }

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.11.5",
+  "version": "4.11.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",
@@ -94,7 +94,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.11.4",
+    "moflo": "^4.11.6",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"