moflo 4.9.36 → 4.9.37

package/.claude/guidance/shipped/moflo-agent-rules.md

@@ -24,6 +24,18 @@
 
 **Search `tests` when looking for test coverage** of a function, module, or behavior — it indexes the test tree separately so you can pinpoint specs without grepping the whole repo.
 
+### Traverse Chunks, Don't Bulk-Retrieve
+
+Search returns chunked guidance with a compact `navigation` crumb (`parentDoc`, `prevChunk`, `nextChunk`, `chunkTitle`). Use it:
+
+| Want | Use |
+|------|-----|
+| Adjacent / sibling / hierarchical context | `mcp__moflo__memory_get_neighbors` |
+| Full content of one chunk | `mcp__moflo__memory_retrieve` (returns full nav for further traversal) |
+| Whole source doc | `Read` `parentPath` from any chunk's nav |
+
+Full protocol: `.claude/guidance/moflo-memory-protocol.md`. Don't retrieve every search hit blindly.
+
 ### Tool Selection (MCP-first)
 
 | Tool | Purpose |

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

@@ -0,0 +1,30 @@
+# MoFlo Memory Protocol — Search, Traverse, Retrieve
+
+**Purpose:** How to use moflo's chunked memory effectively. Search returns navigable chunks — traverse the chunk graph, do not bulk-retrieve every hit.
+
+---
+
+## Decision Table
+
+| You want | Use | Why |
+|----------|-----|-----|
+| Find an entry-point | `mcp__moflo__memory_search` | Returns chunk hits with compact `navigation` (parentDoc, prev/next, chunkTitle) |
+| Adjacent context (1 chunk over) | `mcp__moflo__memory_get_neighbors` `{ key, include: ['prev','next'] }` | One round-trip, returns 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 chunk | `mcp__moflo__memory_retrieve` `{ key }` | Returns full nav object for further traversal |
+| Whole source doc when truly needed | `Read` `parentPath` from any chunk's nav | Disk read is cheaper than re-indexed `doc-*` |
+
+## Anti-Patterns
+
+| Don't | Do instead |
+|-------|-----------|
+| Retrieve every search hit blindly | Read the search snippet + `navigation`; retrieve or traverse only the chunks you need |
+| Open the source file when a chunk would do | Stay in the chunk graph; `Read` `parentPath` only for the rare full-doc case |
+| Search again for a key you already have | `memory_retrieve` or `memory_get_neighbors` directly |
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — namespaces, query examples, MCP-first tool selection
+- `.claude/guidance/moflo-memory-strategy.md` — How chunking, embeddings, and the RAG index work

package/.claude/guidance/shipped/moflo-subagents.md

@@ -18,6 +18,10 @@ CLI fallback when MCP is unavailable: `npx flo memory search --query "..." --nam
 
 The full namespace reference, query examples by domain, and tool catalog live in `.claude/guidance/moflo-agent-rules.md` § Memory-First Protocol — read that next.
 
+### Traverse, don't bulk-retrieve
+
+Search hits carry a compact `navigation` crumb. For adjacent/sibling/hierarchical context, call `mcp__moflo__memory_get_neighbors` (one round-trip) instead of retrieving every hit. Full protocol: `.claude/guidance/moflo-memory-protocol.md`.
+
 ---
 
 ## Step 2: Apply Universal Agent Rules

package/.claude/helpers/gate.cjs

@@ -307,7 +307,7 @@ switch (command) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
     }
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
-      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
+      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     }
     if (s.lastNamespaceHint) {
       // Per-actor single-shot. Each session_id gets the hint at most once per
@@ -376,7 +376,7 @@ switch (command) {
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -386,7 +386,7 @@ switch (command) {
     var fp = process.env.TOOL_INPUT_file_path || '';
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'record-task-created': {

package/.claude/helpers/subagent-bootstrap.json

@@ -1,3 +1,3 @@
 {
-  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol."
+  "directive": "MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When search returns chunk hits, traverse via mcp__moflo__memory_get_neighbors before retrieving — see `.claude/guidance/moflo-memory-protocol.md`."
 }

package/.claude/helpers/subagent-start.cjs

@@ -22,7 +22,7 @@ const path = require('path');
 // Defense-in-depth copy of the canonical directive in subagent-bootstrap.json.
 // Kept as a single-line literal so the parity test in tests/bin/subagent-start.test.ts
 // can verify it matches the JSON via plain substring containment.
-const FALLBACK_DIRECTIVE = 'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol.';
+const FALLBACK_DIRECTIVE = 'MANDATORY FIRST ACTION: Your very first tool call MUST be mcp__moflo__memory_search (any query, any namespace). The memory-first gate WILL BLOCK all Glob, Grep, and Read calls until you do this. After memory search, follow `.claude/guidance/moflo-subagents.md` protocol. When search returns chunk hits, traverse via mcp__moflo__memory_get_neighbors before retrieving — see `.claude/guidance/moflo-memory-protocol.md`.';
 
 function loadDirective() {
   const jsonPath = path.join(__dirname, 'subagent-bootstrap.json');

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

@@ -121,6 +121,14 @@ 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).
 
+**Legacy `doc-*` residue (#1053 S4)** — moflo retired whole-document indexing in favor of chunk-only RAG. The `purge-doc-entries` migration runs on session-start; if any `doc-*` rows linger, the migration didn't fire (ran with no DB, errored, or the install is below the migration's introduction).
+
+```
+mcp__moflo__memory_search — { query: "doc-", namespace: "guidance", threshold: 0, limit: 5 }
+```
+
+If any returned `key` starts with `doc-`, flag `info`: "legacy doc-* rows present — `purge-doc-entries` migration did not run; fixable via `flo healer --fix` or manual `node node_modules/moflo/bin/run-migrations.mjs`".
+
 ### 1i. Hooks & MCP Wiring
 
 Read `.claude/settings.json`. Check:

package/bin/gate.cjs

@@ -307,7 +307,7 @@ switch (command) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
     }
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
-      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
+      process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     }
     if (s.lastNamespaceHint) {
       // Per-actor single-shot. Each session_id gets the hint at most once per
@@ -376,7 +376,7 @@ switch (command) {
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -386,7 +386,7 @@ switch (command) {
     var fp = process.env.TOOL_INPUT_file_path || '';
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search.\n');
+    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
     process.exit(2);
   }
   case 'record-task-created': {

package/bin/index-guidance.mjs

@@ -272,6 +272,22 @@ function getEntryHash(db, key) {
   return null;
 }
 
+// #1053 S4: doc-* entries retired. Doc-level skip check now reads
+// docContentHash off chunk-0 (every chunk carries it).
+function getDocHashFromChunkZero(db, chunkPrefix) {
+  const stmt = db.prepare('SELECT metadata FROM memory_entries WHERE key = ? AND namespace = ?');
+  stmt.bind([`${chunkPrefix}-0`, NAMESPACE]);
+  const entry = stmt.step() ? stmt.getAsObject() : null;
+  stmt.free();
+  if (entry?.metadata) {
+    try {
+      const meta = JSON.parse(entry.metadata);
+      return meta.docContentHash;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
 /**
  * Extract overlapping context from adjacent text
  * @param {string} text - The text to extract from
@@ -536,9 +552,10 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const content = readFileSync(filePath, 'utf-8');
     const contentHash = hashContent(content);
 
-    // Check if content changed (skip if same hash unless --force)
+    // Check if content changed (skip if same hash unless --force).
+    // #1053 S4: doc-* retired — read docContentHash off chunk-0 instead.
     if (!force) {
-      const existingHash = getEntryHash(db, docKey);
+      const existingHash = getDocHashFromChunkZero(db, chunkPrefix);
       if (existingHash === contentHash) {
         return { docKey, status: 'unchanged', chunks: 0 };
       }
@@ -547,25 +564,19 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const stats = statSync(filePath);
     const relativePath = '/' + relative(projectRoot, filePath).replace(/\\/g, '/');
 
-    // Delete old chunks for this file before re-indexing
+    // Delete old chunks for this file before re-indexing.
+    // #1053 S4: also delete any legacy doc-* row (one-time cleanup if a
+    // pre-S4 install left one behind for this prefix).
     deleteByPrefix(db, chunkPrefix);
+    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, docKey]);
 
-    // 1. Store full document
-    const docMetadata = {
-      ...extraMetadata,
-      type: 'document',
-      filePath: relativePath,
-      fileSize: stats.size,
-      lastModified: stats.mtime.toISOString(),
-      contentHash,
-      indexedAt: new Date().toISOString(),
-      ragVersion: '2.0',  // Mark as full RAG indexed
-    };
-
-    storeEntry(db, docKey, content, docMetadata, [keyPrefix, 'document', ...extraTags]);
-    debug(`Stored document: ${docKey}`);
+    // #1053 S4: Chunker no longer writes doc-* entries. Audit found zero
+    // production readers — they duplicated chunk semantic territory and
+    // ate ~13% of search slots without unique signal. parentDoc on chunks
+    // remains as an identifier/grouping label; callers needing the source
+    // file Read parentPath, per shipped/moflo-memory-protocol.md.
 
-    // 2. Chunk and store semantic pieces with full RAG linking
+    // Chunk and store semantic pieces with full RAG linking
     const chunks = chunkMarkdown(content, fileName);
 
     if (chunks.length === 0) {
@@ -576,14 +587,6 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
     const hierarchy = buildHierarchy(chunks, chunkPrefix);
     const siblings = chunks.map((_, i) => `${chunkPrefix}-${i}`);
 
-    // Update document with children references
-    const docChildrenMeta = {
-      ...docMetadata,
-      children: siblings,
-      chunkCount: chunks.length,
-    };
-    storeEntry(db, docKey, content, docChildrenMeta, [keyPrefix, 'document', ...extraTags]);
-
     for (let i = 0; i < chunks.length; i++) {
       const chunk = chunks[i];
       const chunkKey = `${chunkPrefix}-${i}`;
@@ -592,13 +595,11 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
       const prevChunk = i > 0 ? `${chunkPrefix}-${i - 1}` : null;
       const nextChunk = i < chunks.length - 1 ? `${chunkPrefix}-${i + 1}` : null;
 
-      // Extract overlapping context from adjacent chunks
-      const contextBefore = i > 0
-        ? extractOverlapContext(chunks[i - 1].content, overlapPercent, 'end')
-        : null;
-      const contextAfter = i < chunks.length - 1
-        ? extractOverlapContext(chunks[i + 1].content, overlapPercent, 'start')
-        : null;
+      // #1053 S5: dropped extractOverlapContext + preamble wrapping. The
+      // preambles were a workaround for missing traversal — once memory_get_neighbors
+      // is wired (S2), prevChunk/nextChunk metadata + a real call is the
+      // alternative path. Saved ~25-30% bloat per chunk on disk and in
+      // embeddings.
 
       // Get hierarchical relationships
       const hierInfo = hierarchy[chunkKey];
@@ -608,9 +609,13 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
         type: 'chunk',
         ragVersion: '2.0',
 
-        // Document relationship
+        // Document relationship — parentDoc is an identifier/grouping label
+        // only after #1053 S4; the actual source doc is at parentPath.
+        // docContentHash is the file-level hash, used by the skip-if-unchanged
+        // check (the chunker reads it off chunk-0 to decide whether to re-index).
         parentDoc: docKey,
         parentPath: relativePath,
+        docContentHash: contentHash,
 
         // Sequential navigation (forward/backward links)
         chunkIndex: i,
@@ -632,30 +637,14 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
         isPart: chunk.isPart || false,
         partNum: chunk.partNum || null,
 
-        // Overlapping context for continuity
-        contextOverlapPercent: overlapPercent,
-        hasContextBefore: !!contextBefore,
-        hasContextAfter: !!contextAfter,
-
         // Content metadata
         contentLength: chunk.content.length,
         contentHash: hashContent(chunk.content),
         indexedAt: new Date().toISOString(),
       };
 
-      // Build searchable content with title context
-      // Include overlap context for better retrieval
-      let searchableContent = `# ${chunk.title}\n\n`;
-
-      if (contextBefore) {
-        searchableContent += `[Context from previous section:]\n${contextBefore}\n\n---\n\n`;
-      }
-
-      searchableContent += chunk.content;
-
-      if (contextAfter) {
-        searchableContent += `\n\n---\n\n[Context from next section:]\n${contextAfter}`;
-      }
+      // #1053 S5: title heading + chunk body. No prev/next preamble.
+      const searchableContent = `# ${chunk.title}\n\n${chunk.content}`;
 
       // Store chunk with full metadata
       storeEntry(

package/bin/migrations/purge-doc-entries.mjs

@@ -0,0 +1,53 @@
+/**
+ * Migration: hard-delete every legacy `doc-*` whole-document entry from the
+ * guidance namespace. The chunker no longer writes these (#1053 S4) — audit
+ * found zero production readers, they duplicated chunk semantic territory,
+ * and they ate ~13% of search slots on every query without unique signal.
+ *
+ * Idempotent: re-runs are no-ops because there will be no `doc-*` rows left.
+ *
+ * @module bin/migrations/purge-doc-entries
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { memoryDbPath } from '../lib/moflo-paths.mjs';
+
+export const name = 'purge-doc-entries';
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{purged:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { purged: 0 };
+
+  // Lazy-load sql.js — keeps the manifest-stamped no-op path off the WASM
+  // init cost (~30ms cold).
+  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+  const SQL = await initSqlJs();
+  const db = new SQL.Database(readFileSync(dbPath));
+
+  // Scope: every namespace, since both `flo memory index-guidance` and
+  // `bin/index-guidance.mjs` historically wrote doc-* across whatever
+  // namespace the entry was scoped to (default for guidance: `guidance`).
+  // Conservative — match the prefix only, never sweep user-stored keys
+  // that happen to start with "doc".
+  const countStmt = db.prepare(`SELECT COUNT(*) AS cnt FROM memory_entries WHERE key LIKE 'doc-%'`);
+  countStmt.step();
+  const beforeCount = Number(countStmt.getAsObject().cnt ?? 0);
+  countStmt.free();
+
+  if (beforeCount === 0) {
+    db.close();
+    return { purged: 0 };
+  }
+
+  db.run(`DELETE FROM memory_entries WHERE key LIKE 'doc-%'`);
+  const purged = db.getRowsModified?.() ?? beforeCount;
+
+  if (purged > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  db.close();
+  return { purged };
+}

package/bin/migrations/strip-context-preambles.mjs

@@ -0,0 +1,97 @@
+/**
+ * Migration: strip the legacy `[Context from previous section:]` /
+ * `[Context from next section:]` preamble blocks from every existing chunk
+ * (#1053 S5). The chunker no longer writes them — they were a workaround for
+ * missing traversal, and once memory_get_neighbors is wired (S2),
+ * prevChunk/nextChunk metadata + a real call is the alternative path.
+ *
+ * For every chunk whose content carries a preamble marker:
+ *   1. Strip the preamble block(s) in place
+ *   2. NULL the embedding column so build-embeddings regenerates it from the
+ *      cleaned content on the next indexer pass
+ *
+ * Idempotent: chunks already in the new shape (no preamble markers) are
+ * untouched.
+ *
+ * @module bin/migrations/strip-context-preambles
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { mofloResolveURL } from '../lib/moflo-resolve.mjs';
+import { memoryDbPath } from '../lib/moflo-paths.mjs';
+
+export const name = 'strip-context-preambles';
+// Run after purge-doc-entries (which itself has order=0 default). Explicit
+// ordering keeps this independent of fs sort order.
+export const order = 20;
+
+// Validated against real chunks; the back-to-back `---` runs that earlier
+// drafts mishandled are absorbed by the trailing `(?:---\n\n)*` / leading
+// `(?:\n\n---)+` greediness.
+const PREV_PREAMBLE = /\[Context from previous section:\][\s\S]*?\n\n---\n\n(?:---\n\n)*/g;
+const NEXT_PREAMBLE = /(?:\n\n---)+\n\n\[Context from next section:\][\s\S]*$/g;
+
+function strip(content) {
+  // Reset lastIndex defensively — global regex state can leak across calls
+  // when reused on a hot path.
+  PREV_PREAMBLE.lastIndex = 0;
+  NEXT_PREAMBLE.lastIndex = 0;
+  return content.replace(PREV_PREAMBLE, '').replace(NEXT_PREAMBLE, '');
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{stripped:number, untouched:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { stripped: 0, untouched: 0 };
+
+  const initSqlJs = (await import(mofloResolveURL('sql.js'))).default;
+  const SQL = await initSqlJs();
+  const db = new SQL.Database(readFileSync(dbPath));
+
+  // Only chunks can carry the preamble — the chunker is the only writer of
+  // those markers. Filter on key prefix to keep the LIKE selective; manual
+  // memory entries containing the literal string are extremely unlikely and
+  // the strip is a no-op for them anyway.
+  const stmt = db.prepare(
+    `SELECT id, content FROM memory_entries WHERE key LIKE 'chunk-%' AND status = 'active'`,
+  );
+  const rows = [];
+  while (stmt.step()) rows.push(stmt.getAsObject());
+  stmt.free();
+
+  if (rows.length === 0) {
+    db.close();
+    return { stripped: 0, untouched: 0 };
+  }
+
+  let stripped = 0;
+  let untouched = 0;
+  const update = db.prepare(`UPDATE memory_entries SET content = ?, embedding = NULL WHERE id = ?`);
+  try {
+    for (const row of rows) {
+      const original = String(row.content || '');
+      // Cheap prefix-check to avoid running the regex on chunks that have no
+      // preamble — covers the common idempotent re-run case in O(1).
+      if (!original.includes('[Context from previous section:]') && !original.includes('[Context from next section:]')) {
+        untouched++;
+        continue;
+      }
+      const cleaned = strip(original);
+      if (cleaned === original) {
+        untouched++;
+        continue;
+      }
+      update.run([cleaned, row.id]);
+      stripped++;
+    }
+  } finally {
+    update.free();
+  }
+
+  if (stripped > 0) writeFileSync(dbPath, Buffer.from(db.export()));
+  db.close();
+  return { stripped, untouched };
+}

package/bin/semantic-search.mjs

@@ -164,6 +164,7 @@ async function semanticSearch(queryText, options = {}) {
         preview: entry.content.substring(0, 150).replace(/\n/g, ' '),
         type: metadata.type || 'unknown',
         parentDoc: metadata.parentDoc || null,
+        parentPath: metadata.parentPath || null,
         chunkTitle: metadata.chunkTitle || null,
       });
     } catch (err) {
@@ -262,7 +263,9 @@ async function main() {
     console.log(`  Key: ${top.key}`);
     console.log(`  Score: ${top.score.toFixed(4)}`);
     if (top.chunkTitle) console.log(`  Section: ${top.chunkTitle}`);
-    if (top.parentDoc) console.log(`  Parent: ${top.parentDoc}`);
+    // #1053 S4: doc-* retired — parentPath is the actionable source location.
+    if (top.parentPath) console.log(`  Parent: ${top.parentPath}`);
+    else if (top.parentDoc) console.log(`  Parent: ${top.parentDoc}`);
     console.log(`  Preview: ${top.preview}...`);
   } catch (err) {
     console.error(`[semantic-search] Error: ${err.message}`);

package/bin/session-start-launcher.mjs

@@ -1605,6 +1605,8 @@ function runMigrationsAndAnnounce(runnerPath) {
   const labels = {
     'knowledge-to-learnings': 'consolidated knowledge → learnings',
     'knowledge-purge': 'removed legacy knowledge namespace rows',
+    'purge-doc-entries': 'pruned legacy doc-* rows (chunk-only RAG, #1053)',
+    'strip-context-preambles': 'stripped chunk preambles; embeddings will rebuild on next index pass (#1053)',
   };
 
   for (const line of raw.split('\n')) {