moflo 4.12.4-rc.9 → 4.12.4

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

@@ -27,16 +27,31 @@ Specs and plans persist as Markdown, one directory per unit of work, under the c
 <specs_dir>/<slug>/plan.md   # the "steps" + how each criterion is verified
 ```
 
-They are indexed into memory on session start, so `mcp__moflo__memory_search` surfaces prior specs across sessions. **Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
+**Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
 
-**Where they live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init` — specs stay local and do not bloat source control, but they also do **not** appear in PRs. To make specs reviewable, point `sdd.specs_dir` at a **tracked** path and commit them:
+### Specs are NOT indexed into memory
+
+Earlier versions indexed `spec.md` / `plan.md` into the `guidance` namespace. They no longer are, and the specs directory is excluded from the guidance walk even when it sits inside a `guidance.directories` entry.
+
+A spec is pre-implementation intent for **one** unit of work, not a project rule. Once implemented it is stale-by-construction, and specs accumulate without bound — so a superseded approach kept surfacing at high similarity alongside real guidance, and the namespace degraded as the project aged. Nothing was gained in exchange: the active spec's path is already known (the `flo sdd` CLI just returned it), so **read it from disk** rather than searching for it.
+
+| To… | Use |
+|---|---|
+| Read the spec/plan you are working on | `Read` the path `flo sdd` returned |
+| Find prior specs across sessions | `flo sdd list` / `flo sdd status <slug>` |
+| Recall what an implementation actually taught you | `memory_search` namespace `learnings` |
+| Recall a past verify verdict | `memory_search` namespace `verify` |
+
+Existing spec rows are removed by the `purge-spec-chunks` migration on the next session start.
+
+**Where specs live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init`. To make specs reviewable in the PR, point `sdd.specs_dir` at a **tracked** path and commit them:
 
 | `sdd.specs_dir` | Committed? | Use when |
 |-----------------|------------|----------|
-| `.moflo/specs` (default) | No (gitignored) | You want the SDD workflow but not spec artifacts in history |
-| `docs/specs`, `.specs`, … (tracked) | Yes | You want specs reviewed in the PR alongside the code |
+| `.moflo/specs` (default) | No (gitignored) | Specs are scratch — the PR body carries the acceptance criteria. Best at high spec volume. |
+| `docs/specs`, `.specs`, … (tracked) | Yes | You want the spec diffed and reviewed alongside the code |
 
-Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it. If the path sits inside a `guidance.directories` entry, specs are indexed once (as guidance), not twice.
+Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it — the CLI to write specs there, the indexer to exclude them.
 
 Each artifact carries a `status` of `draft` or `reviewed` in its frontmatter. The constitution layer (`CLAUDE.md` + `.claude/guidance/`) is referenced by every stage — never restate its invariants inside a spec.
 

package/bin/index-guidance.mjs

@@ -47,6 +47,28 @@ const DB_PATH = memoryDbPath(projectRoot);
 // Load guidance directories from moflo.yaml, falling back to defaults
 // ============================================================================
 
+/**
+ * Absolute path to the project's SDD specs directory (default `.moflo/specs`).
+ *
+ * Validation MUST match `specsRoot()` in `src/cli/sdd/artifacts.ts` exactly, or
+ * the indexer and the CLI would disagree on where specs live: reject absolute /
+ * drive-letter / parent-escape values and fall back to the default.
+ *
+ * Cross-platform (Rule #1): split the /-written config value and re-join with
+ * `path.resolve`, never hardcode a separator.
+ */
+function resolveSpecsDir(specsDirConfig) {
+  const raw = specsDirConfig || '.moflo/specs';
+  let rel = raw.split(/[\\/]+/).filter(Boolean);
+  const escapes = rel.length === 0
+    || rel.includes('..')
+    || /^([a-zA-Z]:|~)$/.test(rel[0])
+    || raw.startsWith('/')
+    || raw.startsWith('\\');
+  if (escapes) rel = ['.moflo', 'specs'];
+  return resolve(projectRoot, ...rel);
+}
+
 function loadGuidanceDirs() {
   const dirs = [];
 
@@ -115,38 +137,34 @@ function loadGuidanceDirs() {
     dirs.push({ path: bundledSkillsDir, prefix: 'skill-bundled', fileFilter: ['SKILL.md'], kind: 'skill', absolute: true });
   }
 
-  // 6. SDD spec/plan artifacts (Epic #1269) — index <specs_dir>/<slug>/{spec,plan}.md
-  //    so prior specs/plans are searchable across sessions. kind: 'spec' keys each
-  //    file by <slug>-<spec|plan> to avoid collisions between per-slug spec.md files.
-  //    #1294 — the location is configurable (default .moflo/specs). Cross-platform
-  //    (Rule #1): split the /-written value and re-join, never hardcode a separator.
-  //    Validation MUST match specsRoot() in src/cli/sdd/artifacts.ts exactly, or
-  //    the indexer and the CLI would disagree on where specs live: reject
-  //    absolute / drive-letter / parent-escape values and fall back to the default.
-  const rawSpecs = specsDirConfig || '.moflo/specs';
-  let specsRel = rawSpecs.split(/[\\/]+/).filter(Boolean);
-  const specsEscapes = specsRel.length === 0
-    || specsRel.includes('..')
-    || /^([a-zA-Z]:|~)$/.test(specsRel[0])
-    || rawSpecs.startsWith('/')
-    || rawSpecs.startsWith('\\');
-  if (specsEscapes) specsRel = ['.moflo', 'specs'];
-  const projectSpecsDir = resolve(projectRoot, ...specsRel);
-  // Double-index guard: if specs_dir sits inside a guidance dir, the guidance
-  // scan (step 1) already indexes those .md files — skip the 'spec' entry so
-  // they aren't indexed twice under two prefixes.
-  const insideGuidance = userDirs.some(d => {
-    const gd = resolve(projectRoot, ...d.split(/[\\/]+/).filter(Boolean));
-    return projectSpecsDir === gd || projectSpecsDir.startsWith(gd + sep);
-  });
-  if (existsSync(projectSpecsDir) && !insideGuidance) {
-    dirs.push({ path: specsRel.join('/'), prefix: 'spec', fileFilter: ['spec.md', 'plan.md'], kind: 'spec' });
-  }
-
-  return dirs;
+  // 6. SDD spec/plan artifacts are NOT indexed.
+  //
+  //    They were (Epic #1269, kind: 'spec'), into this same `guidance` namespace.
+  //    That was wrong on both axes:
+  //
+  //    - Signal: a spec is PRE-implementation intent for one unit of work, not a
+  //      project rule. Once implemented it is stale-by-construction, and a
+  //      superseded approach surfacing at high similarity alongside real guidance
+  //      is worse than absent. Specs accumulate without bound, so the guidance
+  //      namespace degraded monotonically with project age.
+  //    - Value: the active spec's path is already known (the `flo sdd` CLI just
+  //      returned it) — reading it beats chunked retrieval of a doc you hold the
+  //      path to. Cross-session discovery is served by `flo sdd list`, and the
+  //      durable post-implementation signal already lands in `learnings` /
+  //      `verify`.
+  //
+  //    So the specs directory is EXCLUDED from the walk rather than merely
+  //    skipped. Exclusion (not just dropping the step-6 entry) is what makes this
+  //    correct for the config `moflo-sdd.md` recommends for reviewable specs —
+  //    a tracked `specs_dir` INSIDE a guidance dir, where the step-1 scan would
+  //    otherwise pick spec.md/plan.md up as ordinary guidance markdown and
+  //    reintroduce the pollution under a guidance prefix.
+  const specsDir = resolveSpecsDir(specsDirConfig);
+
+  return { dirs, excludeRoots: [specsDir] };
 }
 
-const GUIDANCE_DIRS = loadGuidanceDirs();
+const { dirs: GUIDANCE_DIRS, excludeRoots: EXCLUDE_ROOTS } = loadGuidanceDirs();
 
 // Chunking config - optimized for Claude's retrieval
 const MIN_CHUNK_SIZE = 50;    // Lower minimum to avoid mega-chunks
@@ -612,8 +630,15 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
       };
     });
 
+    // keyPattern is load-bearing, not belt-and-braces: `${chunkPrefix}-%` as a
+    // bare LIKE also matches every chunk of any sibling doc whose name extends
+    // this one's (indexing `flo` matches `chunk-skill-flo-simplify-0`). Those
+    // rows aren't in chunkRows, so the orphan sweep deleted the sibling's whole
+    // index whenever THIS doc changed. Anchoring on the numeric chunk suffix
+    // confines the sweep to the keys this file actually owns.
     const counts = applyIncrementalChunks(db, NAMESPACE, chunkRows, {
       keyPrefix: `${chunkPrefix}-`,
+      keyPattern: new RegExp(`^${chunkPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+$`),
     });
     if (verbose) {
       debug(`  Doc ${docKey}: inserted=${counts.inserted} updated=${counts.updated} unchanged=${counts.unchanged} removed=${counts.removed}`);
@@ -628,20 +653,28 @@ function indexFile(db, filePath, keyPrefix, options = {}) {
 /**
  * Recursively collect all .md files under a directory.
  * Skips node_modules, .git, and other non-content directories.
+ *
+ * `excludeRoots` (absolute paths) prunes whole subtrees — used to keep the SDD
+ * specs directory out of the index even when it sits inside a guidance dir.
+ * Compares resolved absolute paths, never raw strings, and matches on a
+ * `path.sep` boundary so `docs/specs` cannot also prune `docs/specs-guide`.
  */
-function walkMdFiles(dir) {
+function walkMdFiles(dir, excludeRoots = []) {
   const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', '.next', '.reports']);
   // CLAUDE.md is loaded into context by Claude automatically — skip to avoid duplicate vectors
   const SKIP_FILES = new Set(['CLAUDE.md']);
   const files = [];
 
+  const isExcluded = (p) => excludeRoots.some(root => p === root || p.startsWith(root + sep));
+
   function walk(current) {
     if (!existsSync(current)) return;
     for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const full = resolve(current, entry.name);
       if (entry.isDirectory()) {
-        if (!SKIP_DIRS.has(entry.name)) walk(resolve(current, entry.name));
+        if (!SKIP_DIRS.has(entry.name) && !isExcluded(full)) walk(full);
       } else if (entry.isFile() && entry.name.endsWith('.md') && !SKIP_FILES.has(entry.name)) {
-        files.push(resolve(current, entry.name));
+        if (!isExcluded(full)) files.push(full);
       }
     }
   }
@@ -659,7 +692,7 @@ function indexDirectory(db, dirConfig) {
     return results;
   }
 
-  const allMdFiles = walkMdFiles(dirPath);
+  const allMdFiles = walkMdFiles(dirPath, EXCLUDE_ROOTS);
   const filtered = dirConfig.fileFilter
     ? allMdFiles.filter(f => dirConfig.fileFilter.includes(basename(f)))
     : allMdFiles;
@@ -674,17 +707,6 @@ function indexDirectory(db, dirConfig) {
         extraMetadata: { kind: 'skill', skill_name: skillName },
         extraTags: ['skill', `skill-${skillName}`],
       };
-    } else if (dirConfig.kind === 'spec') {
-      // kind: 'spec' (Epic #1269) — key by <slug>-<spec|plan> so a spec.md and
-      // plan.md under the same slug, and identically-named files across slugs,
-      // never collide on the doc key.
-      const slug = basename(dirname(filePath));
-      const artifact = basename(filePath, extname(filePath)); // 'spec' | 'plan'
-      options = {
-        nameOverride: `${slug}-${artifact}`,
-        extraMetadata: { kind: 'spec', spec_slug: slug, artifact },
-        extraTags: ['spec', `spec-${slug}`, artifact],
-      };
     }
     const result = indexFile(db, filePath, dirConfig.prefix, options);
     results.push(result);
@@ -693,37 +715,77 @@ function indexDirectory(db, dirConfig) {
   return results;
 }
 
+/**
+ * Derive a chunk row's owning doc prefix from its key.
+ *
+ * Chunk keys are `${chunkPrefix}-${i}`, so stripping the FINAL `-<digits>`
+ * recovers the prefix. Only the last segment is stripped, which keeps
+ * docs whose filename itself ends in digits intact:
+ * `chunk-guidance-issue-1402-0` → `chunk-guidance-issue-1402`, not
+ * `chunk-guidance-issue`.
+ *
+ * Returns null for a key with no numeric suffix — those are not chunk rows
+ * this indexer wrote, and the caller leaves them alone rather than guessing.
+ */
+function chunkPrefixOf(key) {
+  const m = key.match(/^(.*)-\d+$/);
+  return m ? m[1] : null;
+}
+
 /**
  * Remove stale entries for files that no longer exist on disk.
- * Uses the set of docKeys seen during the current indexing run to determine
- * which entries are stale, rather than reconstructing file paths from keys
- * (which breaks for files in subdirectories).
+ *
+ * Keyed on the chunk prefixes seen during the current run, NOT on `doc-*` rows.
+ * The original implementation enumerated `key LIKE 'doc-%'` and treated any doc
+ * key absent from the run as a deleted file — but #1053 S4 retired doc rows
+ * (the chunker stopped writing them and `purge-doc-entries` deleted the rest),
+ * so on any current install that query returns zero rows and the sweep was a
+ * silent no-op. Deleting a guidance file left its chunks — embeddings and all —
+ * in the namespace permanently, with nothing downstream to detect it. Specs made
+ * that visible because they accumulate fastest, but it stranded chunks for every
+ * deleted guidance file, skill, and doc.
+ *
+ * Safety: an empty live set means the run indexed nothing (I/O error, config
+ * pointing at a missing tree). Sweeping then would wipe the namespace, so bail
+ * and leave the rows for a later healthy run to reconcile.
  */
-function cleanStaleEntries(db, currentDocKeys) {
-  const docsStmt = db.prepare(
-    `SELECT DISTINCT key FROM memory_entries WHERE namespace = ? AND key LIKE 'doc-%'`
+function cleanStaleEntries(db, currentChunkPrefixes) {
+  if (currentChunkPrefixes.size === 0) {
+    log('  Skipped: this run indexed no files (refusing to sweep on an empty live set)');
+    return 0;
+  }
+
+  const chunkStmt = db.prepare(
+    `SELECT DISTINCT key FROM memory_entries WHERE namespace = ? AND key LIKE 'chunk-%'`
   );
-  docsStmt.bind([NAMESPACE]);
-  const docs = [];
-  while (docsStmt.step()) docs.push(docsStmt.getAsObject());
-  docsStmt.free();
+  chunkStmt.bind([NAMESPACE]);
+  const chunkKeys = [];
+  while (chunkStmt.step()) chunkKeys.push(chunkStmt.getAsObject().key);
+  chunkStmt.free();
+
+  // Group stale chunk keys by prefix so the log reports one line per deleted
+  // file rather than one per chunk.
+  const stalePrefixes = new Map();
+  for (const key of chunkKeys) {
+    const prefix = chunkPrefixOf(key);
+    if (!prefix || currentChunkPrefixes.has(prefix)) continue;
+    stalePrefixes.set(prefix, (stalePrefixes.get(prefix) ?? 0) + 1);
+  }
 
   let staleCount = 0;
-
-  for (const { key } of docs) {
-    // If this doc key was seen during the current indexing run, it's not stale
-    if (currentDocKeys.has(key)) continue;
-
-    const chunkPrefix = key.replace('doc-', 'chunk-');
-    const countBefore = db.exec(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = '${NAMESPACE}'`)[0]?.values[0][0] || 0;
-    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key LIKE ?`, [NAMESPACE, `${chunkPrefix}%`]);
-    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, key]);
-    const countAfter = db.exec(`SELECT COUNT(*) as cnt FROM memory_entries WHERE namespace = '${NAMESPACE}'`)[0]?.values[0][0] || 0;
-    const removed = countBefore - countAfter;
-    if (removed > 0) {
-      log(`  Removed ${removed} stale entries for deleted file: ${key}`);
-      staleCount += removed;
+  const del = db.prepare(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`);
+  try {
+    for (const key of chunkKeys) {
+      const prefix = chunkPrefixOf(key);
+      if (!prefix || currentChunkPrefixes.has(prefix)) continue;
+      del.run([NAMESPACE, key]);
+      staleCount++;
     }
+  } finally {
+    del.free();
+  }
+  for (const [prefix, count] of stalePrefixes) {
+    log(`  Removed ${count} stale entries for deleted file: ${prefix}`);
   }
 
   // Also clean any orphaned entries not matching doc-/chunk- patterns
@@ -740,6 +802,22 @@ function cleanStaleEntries(db, currentDocKeys) {
     log(`  Removed orphan entry: ${key}`);
   }
 
+  // Legacy `doc-*` rows from a pre-#1053-S4 install that never ran the
+  // purge-doc-entries migration. Unconditional — the chunker has not written
+  // one since S4, so any survivor is stale by definition.
+  const docStmt = db.prepare(
+    `SELECT key FROM memory_entries WHERE namespace = ? AND key LIKE 'doc-%'`
+  );
+  docStmt.bind([NAMESPACE]);
+  const legacyDocs = [];
+  while (docStmt.step()) legacyDocs.push(docStmt.getAsObject().key);
+  docStmt.free();
+  for (const key of legacyDocs) {
+    db.run(`DELETE FROM memory_entries WHERE namespace = ? AND key = ?`, [NAMESPACE, key]);
+    staleCount++;
+    log(`  Removed legacy doc entry: ${key}`);
+  }
+
   return staleCount;
 }
 
@@ -760,7 +838,10 @@ let docsIndexed = 0;
 let chunksIndexed = 0;
 let unchanged = 0;
 let errors = 0;
-const currentDocKeys = new Set();
+// Chunk prefixes written by this run — the live set the stale sweep diffs
+// against. Populated from every file that indexed OR was skipped as unchanged;
+// an unchanged file is very much still on disk.
+const currentChunkPrefixes = new Set();
 
 if (specificFile) {
   // Index single file
@@ -794,7 +875,7 @@ if (specificFile) {
 
     for (const result of results) {
       if (result.status === 'indexed' || result.status === 'unchanged') {
-        currentDocKeys.add(result.docKey);
+        currentChunkPrefixes.add(result.docKey.replace(/^doc-/, 'chunk-'));
       }
       if (result.status === 'indexed') {
         log(`  ✅ ${result.docKey} (${result.chunks} chunks)`);
@@ -814,7 +895,7 @@ if (specificFile) {
 let staleRemoved = 0;
 if (!specificFile) {
   log('Cleaning stale entries for deleted files...');
-  staleRemoved = cleanStaleEntries(db, currentDocKeys);
+  staleRemoved = cleanStaleEntries(db, currentChunkPrefixes);
   if (staleRemoved === 0) {
     log('  No stale entries found');
   }

package/bin/lib/incremental-write.mjs

@@ -98,9 +98,12 @@ export function schemeTaggedContentHash(files, schemeVersion) {
  * @param {string} namespace
  * @param {string} [keyPrefix] — when set, restricts the scan to `key LIKE '<prefix>%'`.
  *   The same prefix scopes the orphan sweep in {@link applyIncrementalChunks}.
+ * @param {RegExp} [keyPattern] — optional second filter applied in JS after the
+ *   SQL `LIKE`. Required whenever one caller's `keyPrefix` can be a string
+ *   prefix of another's — see {@link applyIncrementalChunks}.
  * @returns {Map<string,string>}
  */
-export function loadExistingContent(db, namespace, keyPrefix) {
+export function loadExistingContent(db, namespace, keyPrefix, keyPattern) {
   const stmt = keyPrefix
     ? db.prepare(
         `SELECT key, content FROM memory_entries WHERE namespace = ? AND key LIKE ? AND status = 'active'`,
@@ -116,7 +119,9 @@ export function loadExistingContent(db, namespace, keyPrefix) {
   const map = new Map();
   while (stmt.step()) {
     const row = stmt.getAsObject();
-    map.set(String(row.key), String(row.content ?? ''));
+    const key = String(row.key);
+    if (keyPattern && !keyPattern.test(key)) continue;
+    map.set(key, String(row.content ?? ''));
   }
   stmt.free();
   return map;
@@ -137,12 +142,21 @@ export function loadExistingContent(db, namespace, keyPrefix) {
  *   when processing a single file's chunks at a time (e.g. index-guidance.mjs
  *   iterates files independently) — without it the sweep would delete every
  *   chunk from every OTHER file as an orphan on each call.
+ * @param {RegExp} [opts.keyPattern] — narrows `keyPrefix` beyond what SQL `LIKE`
+ *   can express. REQUIRED when one file's prefix can be a string prefix of
+ *   another's, which is exactly the case for per-file chunk keys: indexing
+ *   `flo` scopes to `chunk-skill-flo-%`, and that LIKE also matches every chunk
+ *   of `flo-simplify`. Those rows are absent from the caller's `chunks`, so the
+ *   orphan sweep deleted a sibling document's entire index — it reappeared only
+ *   on the next run, re-inserted with a NULL embedding and re-vectorised from
+ *   scratch. Passing `/^chunk-skill-flo-\d+$/` confines the sweep to the chunk
+ *   keys the caller actually owns.
  * @returns {{inserted:number, updated:number, unchanged:number, removed:number}}
  */
 export function applyIncrementalChunks(db, namespace, chunks, opts = {}) {
   const serialize = opts.serialize !== false;
   const keyPrefix = opts.keyPrefix;
-  const existing = loadExistingContent(db, namespace, keyPrefix);
+  const existing = loadExistingContent(db, namespace, keyPrefix, opts.keyPattern);
   const newKeys = new Set();
   let inserted = 0;
   let updated = 0;

package/bin/migrations/purge-spec-chunks.mjs

@@ -0,0 +1,79 @@
+/**
+ * Migration: hard-delete SDD spec/plan chunks from the `guidance` namespace.
+ *
+ * `bin/index-guidance.mjs` used to index `<specs_dir>/<slug>/{spec,plan}.md`
+ * into `guidance` alongside real project guidance (Epic #1269, `kind: 'spec'`).
+ * A spec is pre-implementation intent for one unit of work, not a project rule:
+ * once implemented it is stale-by-construction, and specs accumulate without
+ * bound, so the namespace degraded monotonically with project age. The indexer
+ * now excludes the specs directory outright.
+ *
+ * This clears what earlier versions already wrote. Two shapes existed:
+ *
+ *   1. `chunk-spec-*` keys with `metadata.kind === 'spec'` — the dedicated
+ *      step-6 path, used when `specs_dir` sat OUTSIDE every guidance directory.
+ *   2. Ordinary guidance chunks under a guidance prefix — produced when
+ *      `specs_dir` sat INSIDE a guidance dir (the config `moflo-sdd.md`
+ *      recommends for reviewable specs). These carry no spec marker at all and
+ *      are indistinguishable from real guidance by key or metadata.
+ *
+ * Only shape 1 is purged here, because it is the only one that can be
+ * identified without guessing. Shape 2 is handled by the repaired stale sweep
+ * in `bin/index-guidance.mjs`: the specs directory is now pruned from the walk,
+ * so those chunk prefixes fall out of the live set on the next index run and
+ * are swept as deleted files. Deleting them here by path-matching would risk
+ * taking real guidance with them.
+ *
+ * Idempotent: re-runs find no matching rows.
+ *
+ * @module bin/migrations/purge-spec-chunks
+ */
+
+import { existsSync } from 'fs';
+import { memoryDbPath } from '../lib/moflo-paths.mjs';
+import { openBackend } from '../lib/get-backend.mjs';
+
+export const name = 'purge-spec-chunks';
+// After purge-doc-entries (0) and strip-context-preambles (20) so this operates
+// on an already-normalised chunk table.
+export const order = 30;
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<{purged:number}>}
+ */
+export async function run(projectRoot) {
+  const dbPath = memoryDbPath(projectRoot);
+  if (!existsSync(dbPath)) return { purged: 0 };
+
+  const db = await openBackend(projectRoot, { create: false });
+
+  // Two independent markers, OR'd, because they were written by the same code
+  // path and either alone would leave rows behind on a partial index:
+  //   - key prefix `chunk-spec-` (dirConfig.prefix === 'spec')
+  //   - metadata.kind === 'spec' (survives even if the prefix ever changed)
+  // Scoped to `guidance` — the only namespace bin/index-guidance.mjs writes —
+  // so a user-stored entry elsewhere that happens to match is never touched.
+  const WHERE = `namespace = 'guidance'
+      AND (key LIKE 'chunk-spec-%' OR metadata LIKE '%"kind":"spec"%')`;
+
+  const countStmt = db.prepare(`SELECT COUNT(*) AS cnt FROM memory_entries WHERE ${WHERE}`);
+  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 ${WHERE}`);
+  const purged = db.getRowsModified?.() ?? beforeCount;
+
+  // No explicit HNSW invalidation needed: the delete moves the DB/WAL mtime,
+  // which is exactly what the `hnsw-rebuild` step gates on, so the sidecar
+  // reconciles on the next session-start indexer pass.
+  if (purged > 0) db.save();
+  db.close();
+  return { purged };
+}

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.12.4-rc.9';
+export const VERSION = '4.12.4';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.12.4-rc.9",
+  "version": "4.12.4",
   "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",
@@ -98,7 +98,7 @@
     "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",
     "glob": "^11.1.0",
-    "moflo": "^4.12.4-rc.8",
+    "moflo": "^4.12.4-rc.10",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"