moflo 4.9.20 → 4.9.22

package/bin/gate.cjs

@@ -7,7 +7,7 @@ var cp = require('child_process');
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -60,7 +60,7 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true };
+  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -71,6 +71,7 @@ function loadGateConfig() {
       if (/testing_gate:\s*false/i.test(content)) defaults.testing_gate = false;
       if (/simplify_gate:\s*false/i.test(content)) defaults.simplify_gate = false;
       if (/learnings_gate:\s*false/i.test(content)) defaults.learnings_gate = false;
+      if (/swarm_invocation_gate:\s*false/i.test(content)) defaults.swarm_invocation_gate = false;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -83,6 +84,99 @@ var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state
 var DANGEROUS = ['rm -rf /', 'format c:', 'del /s /q c:\\', ':(){:|:&};:', 'mkfs.', '> /dev/sda'];
 var DIRECTIVE_RE = /^(yes|no|yeah|yep|nope|sure|ok|okay|correct|right|exactly|perfect)\b/i;
 var TASK_RE = /\b(fix|bug|error|implement|add|create|build|write|refactor|debug|test|feature|issue|security|optimi)\b/i;
+
+// Namespace classification (#931). The hint used to be emitted on every prompt
+// by prompt-hook.mjs which cost ~40 tokens × every prompt × every consumer.
+// Now we classify here, store on workflow-state, and let check-before-agent
+// emit it once when Claude is actually about to spawn an agent.
+//
+// SYNC: these regexes + classifyNamespaceHint + applyPromptStateReset are
+// duplicated verbatim in src/cli/init/helpers-generator.ts (the embedded
+// gate.cjs fallback used by `flo init` when source helpers can't be located).
+// Any edit to either copy MUST be applied to both — there is no shared module
+// because helpers-generator emits a self-contained string template.
+var NS_LEARNINGS_RE = /\b(remember|recall|insight|lesson learned|gotcha|post.?mortem)\b|we (decid|agree|chose|said)/;
+var NS_TEST_RE = /\b(test|spec|coverage|tested|test case|test cases|tests for|spec for)\b/;
+var NS_EXPLICIT = [
+  { pattern: /\b(pattern|convention|best practice|style|coding rule)\b/, ns: 'patterns', label: 'code patterns and conventions' },
+  { pattern: /\b(code.?map|file structure|project structure|directory)\b/, ns: 'code-map', label: 'codebase navigation' },
+];
+var NS_PATTERN_RES = [/\b(template|example|similar to|how do we|how should)\b/];
+var NS_DOMAIN_RES = [
+  /\b(guidance|guide|docs|documentation|rules|how-to)\b/,
+  /\b(architecture|design|domain|tenant|migrat|schema|deploy)/,
+  /\b(rule|requirement|constraint|compliance)\b/,
+];
+var NS_NAV_RES = [
+  /\b(find|where|which file|look up|locate|endpoint|route|url|path)\b/,
+  /\b(class|function|method|component|service|entity|module)\b/,
+];
+
+// Detect whether the current prompt invoked /fl or /flo with a swarm/hive flag (#952).
+// When set, check-before-agent BLOCKS the Agent spawn until the matching MCP init
+// (mcp__moflo__swarm_init or mcp__moflo__hive-mind_init) has been recorded — the user
+// explicitly opted in to the protected coordination surface, so falling back to
+// raw Agent dispatch silently regresses headline moflo product capability.
+//
+// SYNC: duplicated verbatim in src/cli/init/helpers-generator.ts.
+function detectFlMode(promptText) {
+  var p = promptText || '';
+  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return null;
+  if (/(?:^|\s)(?:-s|--swarm)\b/.test(p)) return 'swarm';
+  if (/(?:^|\s)(?:-h|--hive)\b/.test(p)) return 'hive';
+  return null;
+}
+
+function classifyNamespaceHint(promptText) {
+  var lower = (promptText || '').toLowerCase();
+  if (NS_TEST_RE.test(lower)) return 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
+  if (NS_LEARNINGS_RE.test(lower)) return 'Memory namespace hint: use "learnings" for user-directed decisions and distilled insights.';
+  for (var i = 0; i < NS_EXPLICIT.length; i++) {
+    if (NS_EXPLICIT[i].pattern.test(lower)) return 'Memory namespace hint: use "' + NS_EXPLICIT[i].ns + '" for ' + NS_EXPLICIT[i].label + '.';
+  }
+  for (var j = 0; j < NS_DOMAIN_RES.length; j++) {
+    if (NS_DOMAIN_RES[j].test(lower)) return 'Memory namespace hint: search "guidance" and "learnings" for domain rules and project decisions.';
+  }
+  for (var k = 0; k < NS_PATTERN_RES.length; k++) {
+    if (NS_PATTERN_RES[k].test(lower)) return 'Memory namespace hint: use "patterns" for code patterns and conventions.';
+  }
+  for (var m = 0; m < NS_NAV_RES.length; m++) {
+    if (NS_NAV_RES[m].test(lower)) return 'Memory namespace hint: use "code-map" for codebase navigation.';
+  }
+  return '';
+}
+
+// Apply per-prompt state reset shared by `prompt-reminder` (full) and
+// `prompt-state-reset` (defensive safety-net, no emission). Idempotent — both
+// UserPromptSubmit hooks can run it without compounding any field. Caller
+// owns interactionCount and the user-visible REMINDER/Context emissions, so
+// this helper stays silent.
+function applyPromptStateReset(state, promptText) {
+  state.memorySearched = false;
+  // Wipe per-actor memory tracking too — a new user prompt is a fresh window
+  // for both parent AND any subagents the parent may spawn during this turn.
+  state.memorySearchedBy = {};
+  // learningsStored is session-scoped — once stored, it stays true until session reset.
+  // Resetting per-prompt caused false blocks when PR creation was on a later prompt.
+  var DIRECTIVE_MAX_LEN = 20;
+  var escaped = /^@@\s*/.test(promptText || '');
+  state.memoryRequired = !escaped && (promptText || '').length >= 4 && (TASK_RE.test(promptText || '') || (promptText || '').length > DIRECTIVE_MAX_LEN);
+  // Stash namespace hint for check-before-agent to emit when Claude actually
+  // spawns an Agent (#931). Empty string when nothing matched — overwriting
+  // any stale value from the previous prompt.
+  state.lastNamespaceHint = classifyNamespaceHint(promptText);
+  // Per-actor emission tracking — each subagent's session gets the hint at
+  // most once per prompt, but a fresh prompt resets every actor's window so
+  // subsequent agents (parent + subagents that spawn their own agents) all
+  // see the new classification on their first check-before-agent.
+  state.lastNamespaceHintEmittedBy = {};
+  // #952 — derive flMode from the user prompt, and reset the matching init
+  // flag. Each /fl invocation must call its protected MCP init; the previous
+  // prompt's swarm/hive registration does not satisfy this prompt's gate.
+  state.flMode = detectFlMode(promptText);
+  state.swarmInitialized = false;
+  state.hiveInitialized = false;
+}
 // Match npm/yarn/pnpm/bun test, npx vitest|jest|..., bare runners at command-start only,
 // and language-native test commands. The bare-runner arm is anchored so that
 // `npm install jest`, `grep -r vitest src/`, and similar don't false-positive.
@@ -203,6 +297,11 @@ switch (command) {
     // Advisory only — agent spawning is never blocked.
     // Memory-first enforcement happens at the scan/read gate layer.
     // SubagentStart hook injects guidance directive into subagent context.
+    //
+    // #931 — TaskCreate REMINDER and the namespace hint moved here from
+    // prompt-reminder. They only matter when Claude is actually about to spawn
+    // an Agent; emitting per-prompt cost ~90 tokens × every prompt × every
+    // consumer.
     var s = readState();
     if (config.task_create_first && !s.tasksCreated) {
       process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
@@ -210,6 +309,65 @@ switch (command) {
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
       process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents.\n');
     }
+    if (s.lastNamespaceHint) {
+      // Per-actor single-shot. Each session_id gets the hint at most once per
+      // prompt, but the hint itself stays available for other actors (e.g.
+      // a subagent that spawns its own agent has its own session_id and is
+      // entitled to a fresh emission). Falls back to a `_legacy_` bucket when
+      // Claude Code didn't forward a session_id (older host or direct CLI
+      // invocation), preserving the old "emit once globally" behavior. The
+      // map is wiped by applyPromptStateReset on every new prompt.
+      var sid = process.env.HOOK_SESSION_ID || '';
+      var emittedBy = s.lastNamespaceHintEmittedBy || {};
+      var bucket = sid || '_legacy_';
+      if (!emittedBy[bucket]) {
+        process.stdout.write(s.lastNamespaceHint + '\n');
+        emittedBy[bucket] = true;
+        s.lastNamespaceHintEmittedBy = emittedBy;
+        writeState(s);
+      }
+    }
+    // #952 — when /fl was invoked with -s/-h, the protected MCP init must run
+    // BEFORE any Agent spawn. Hard block: the user explicitly opted in to
+    // moflo's coordination surface, so silently dispatching `Agent` calls
+    // without `mcp__moflo__swarm_init` / `mcp__moflo__hive-mind_init` is the
+    // failure mode this gate exists to prevent (CLAUDE.md "⛔ Protected
+    // functionality — swarm + hive-mind"). Other Agent uses remain advisory.
+    if (config.swarm_invocation_gate) {
+      if (s.flMode === 'swarm' && !s.swarmInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -s/--swarm but mcp__moflo__swarm_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__swarm_init first, then mcp__moflo__agent_spawn for each role, then dispatch Agent.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "SWARM mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+      if (s.flMode === 'hive' && !s.hiveInitialized) {
+        process.stderr.write('BLOCKED: /fl was invoked with -h/--hive but mcp__moflo__hive-mind_init has not been called.\n');
+        process.stderr.write('Run mcp__moflo__hive-mind_init first, then dispatch Agent or hive-mind workers.\n');
+        process.stderr.write('See .claude/skills/fl/execution-modes.md "HIVE-MIND mode" and CLAUDE.md "⛔ Protected functionality".\n');
+        process.stderr.write('Disable via moflo.yaml: gates: swarm_invocation_gate: false\n');
+        process.exit(2);
+      }
+    }
+    break;
+  }
+  case 'record-swarm-init': {
+    // #952 — wired to mcp__moflo__swarm_init PostToolUse. Marks the gate
+    // satisfied so subsequent Agent spawns under /fl -s pass.
+    var s = readState();
+    if (!s.swarmInitialized) {
+      s.swarmInitialized = true;
+      writeState(s);
+    }
+    break;
+  }
+  case 'record-hive-init': {
+    // #952 — wired to mcp__moflo__hive-mind_init PostToolUse.
+    var s = readState();
+    if (!s.hiveInitialized) {
+      s.hiveInitialized = true;
+      writeState(s);
+    }
     break;
   }
   case 'check-before-scan': {
@@ -277,7 +435,8 @@ switch (command) {
     break;
   }
   case 'record-skill-run': {
-    if ((process.env.TOOL_INPUT_skill || '') === 'simplify') {
+    var skName = (process.env.TOOL_INPUT_skill || '');
+    if (skName === 'simplify' || skName === 'flo-simplify') {
       var s = readState();
       var changed = false;
       if (!s.simplifyRun) { s.simplifyRun = true; changed = true; }
@@ -346,7 +505,7 @@ switch (command) {
     }
     var missing = [];
     if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
-    if (config.simplify_gate && !s.simplifyRun) missing.push('/simplify has not run since the last code edit');
+    if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify has not run since the last code edit');
     if (config.learnings_gate && !s.learningsStored) missing.push('learnings have not been stored (call mcp__moflo__memory_store)');
     if (missing.length === 0) break;
     process.stderr.write('BLOCKED: gh pr create requires the following before opening a PR:\n');
@@ -371,20 +530,16 @@ switch (command) {
     break;
   }
   case 'prompt-reminder': {
+    // Full per-prompt reset. Wired as the first UserPromptSubmit hook (via
+    // prompt-hook.mjs). Owns interactionCount + Context warnings; the
+    // TaskCreate REMINDER and namespace hint moved to check-before-agent
+    // (#931) so they only fire when Claude is actually about to spawn an
+    // Agent.
     var s = readState();
-    s.memorySearched = false;
-    // Wipe per-actor memory tracking too — a new user prompt is a fresh window
-    // for both parent AND any subagents the parent may spawn during this turn.
-    s.memorySearchedBy = {};
-    // learningsStored is session-scoped — once stored, it stays true until session reset.
-    // Resetting per-prompt caused false blocks when PR creation was on a later prompt.
     var prompt = process.env.CLAUDE_USER_PROMPT || '';
-    var DIRECTIVE_MAX_LEN = 20;
-    var escaped = /^@@\s*/.test(prompt);
-    s.memoryRequired = !escaped && prompt.length >= 4 && (TASK_RE.test(prompt) || prompt.length > DIRECTIVE_MAX_LEN);
+    applyPromptStateReset(s, prompt);
     s.interactionCount = (s.interactionCount || 0) + 1;
     writeState(s);
-    if (!s.tasksCreated) console.log('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.');
     if (config.context_tracking) {
       var ic = s.interactionCount;
       if (ic > 30) console.log('Context: CRITICAL. Commit, store learnings, suggest new session.');
@@ -393,12 +548,34 @@ switch (command) {
     }
     break;
   }
+  case 'prompt-state-reset': {
+    // Defensive safety-net hook (#931 dedupe). Wired as the second
+    // UserPromptSubmit hook so an exception in prompt-hook.mjs doesn't skip
+    // the per-prompt state reset. Idempotent — applyPromptStateReset only
+    // sets fields to derived values, and we deliberately do NOT increment
+    // interactionCount or emit anything (that's prompt-reminder's job).
+    //
+    // Skip the disk write on the normal path: prompt-reminder runs first and
+    // already wrote the byte-identical post-reset state. Only writeState when
+    // the reset actually changed something (i.e., prompt-reminder was skipped
+    // because prompt-hook.mjs threw before invoking it).
+    var s = readState();
+    var prompt = process.env.CLAUDE_USER_PROMPT || '';
+    var before = JSON.stringify(s);
+    applyPromptStateReset(s, prompt);
+    if (JSON.stringify(s) !== before) writeState(s);
+    break;
+  }
   case 'compact-guidance': {
     console.log('Pre-Compact: Check CLAUDE.md for rules. Use memory search to recover context after compact.');
     break;
   }
   case 'session-reset': {
-    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null });
+    // Derive from STATE_DEFAULTS so adding a new state field requires only one
+    // edit (the defaults object) — the literal that used to live here drifted
+    // every time a field was added and is what motivated #952's audit of state
+    // shape consistency.
+    writeState(Object.assign({}, STATE_DEFAULTS, { sessionStart: new Date().toISOString() }));
     break;
   }
   default:

package/bin/lib/retired-files.mjs

@@ -0,0 +1,146 @@
+/**
+ * Retired-shipped-files prune helper (#948).
+ *
+ * Closes the gap that retired agents (#932) and retired skills (#945) leave
+ * in consumer projects: the manifest cleanup at section 3 of the launcher
+ * only knows about files moflo previously synced, but `.claude/agents/` and
+ * `.claude/skills/` were not in the manifest before #948. So files retired
+ * before #948 lands stay on disk forever — Claude Code keeps loading them as
+ * subagents on every prompt, paying the per-prompt roster tokens we just
+ * spent #932 fixing.
+ *
+ * This module reads `retired-files.json` (shipped at the moflo package
+ * root) and, for each entry, only prunes the consumer-side path when the
+ * file's sha256 matches one of `knownContentHashes` — i.e. the file matches
+ * a version moflo actually shipped, so the consumer didn't customize it.
+ * Customized files are preserved and a one-line notice is emitted so the
+ * user can act.
+ *
+ * Manifest format:
+ *
+ *   {
+ *     "version": 1,
+ *     "retired": [
+ *       {
+ *         "path": ".claude/agents/v3/performance-engineer.md",
+ *         "retiredIn": "4.9.22",
+ *         "retiredBy": "#932",
+ *         "knownContentHashes": ["sha256:abc...", "sha256:def..."]
+ *       }
+ *     ]
+ *   }
+ *
+ * @module bin/lib/retired-files
+ */
+
+import { existsSync, readFileSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { createHash } from 'crypto';
+
+/**
+ * Compute sha256 of file content. Returns null on read errors so the caller
+ * can decide what to do — we never want a transient stat/read failure to
+ * trigger a prune of a file we couldn't actually verify.
+ *
+ * @param {string} absPath
+ * @returns {string|null} `sha256:<hex>` or null
+ */
+export function fileSha256(absPath) {
+  try {
+    const buf = readFileSync(absPath);
+    return 'sha256:' + createHash('sha256').update(buf).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load + validate the retired-files manifest. Returns `{ entries: [] }` for
+ * any failure mode (missing file, invalid JSON, wrong shape) — the launcher
+ * must never block on a corrupt manifest.
+ *
+ * @param {string} manifestPath - absolute path to retired-files.json
+ * @returns {{ entries: Array<{path:string, retiredIn?:string, retiredBy?:string, knownContentHashes:string[]}> }}
+ */
+export function loadRetiredManifest(manifestPath) {
+  if (!existsSync(manifestPath)) return { entries: [] };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch { return { entries: [] }; }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.retired)) {
+    return { entries: [] };
+  }
+  // Filter out malformed entries — guards against a hand-edited file
+  // dropping the wrong shape into a launcher that runs on N consumer
+  // machines. A skipped entry never auto-prunes (safest default).
+  const entries = parsed.retired.filter((entry) =>
+    entry &&
+    typeof entry.path === 'string' &&
+    entry.path.length > 0 &&
+    Array.isArray(entry.knownContentHashes) &&
+    entry.knownContentHashes.length > 0 &&
+    entry.knownContentHashes.every((h) => typeof h === 'string' && h.startsWith('sha256:'))
+  );
+  return { entries };
+}
+
+/**
+ * Decide what to do with a consumer-side path against a retirement entry:
+ *
+ *   - 'absent'     — path doesn't exist on disk; nothing to do
+ *   - 'prune'      — file exists and content hash matches a known-shipped
+ *                    value; safe to delete (consumer didn't customize)
+ *   - 'preserve'   — file exists but content differs from every known-shipped
+ *                    hash; consumer customized, leave alone
+ *   - 'unknown'    — file exists but its hash couldn't be read (transient
+ *                    error); leave alone, retry next session
+ *
+ * @param {string} projectRoot
+ * @param {{path:string, knownContentHashes:string[]}} entry
+ * @returns {{ action: 'absent'|'prune'|'preserve'|'unknown', actualHash: string|null }}
+ */
+export function classifyRetiredFile(projectRoot, entry) {
+  const abs = resolve(projectRoot, entry.path);
+  if (!existsSync(abs)) return { action: 'absent', actualHash: null };
+  const actualHash = fileSha256(abs);
+  if (!actualHash) return { action: 'unknown', actualHash: null };
+  if (entry.knownContentHashes.includes(actualHash)) {
+    return { action: 'prune', actualHash };
+  }
+  return { action: 'preserve', actualHash };
+}
+
+/**
+ * Walk the manifest and apply prune decisions. Returns a small report so
+ * the caller can emit one summary line (the launcher pattern) instead of
+ * forcing it to track per-entry state.
+ *
+ * Failures are non-fatal — a single un-deletable file (Windows AV hold,
+ * EBUSY) must not stop pruning the rest. The caller surfaces the report.
+ *
+ * @param {string} projectRoot
+ * @param {string} manifestPath
+ * @returns {{ pruned: string[], preserved: string[], unknown: string[], failed: Array<{path:string, message:string}> }}
+ */
+export function applyRetiredPrune(projectRoot, manifestPath) {
+  const { entries } = loadRetiredManifest(manifestPath);
+  const report = { pruned: [], preserved: [], unknown: [], failed: [] };
+  for (const entry of entries) {
+    const { action } = classifyRetiredFile(projectRoot, entry);
+    if (action === 'absent') continue;
+    if (action === 'preserve') { report.preserved.push(entry.path); continue; }
+    if (action === 'unknown') { report.unknown.push(entry.path); continue; }
+    // action === 'prune'
+    try {
+      unlinkSync(resolve(projectRoot, entry.path));
+      report.pruned.push(entry.path);
+    } catch (err) {
+      report.failed.push({
+        path: entry.path,
+        message: err && err.message ? err.message : String(err),
+      });
+    }
+  }
+  return report;
+}

package/bin/prompt-hook.mjs

@@ -33,43 +33,9 @@ try {
   });
 } catch (err) { output = (err && err.stdout) || ''; }
 
-// Classify prompt for namespace hint
-var lower = userPrompt.toLowerCase();
-
-var LEARNINGS_HINTS = /\b(remember|recall|insight|lesson learned|gotcha|post.?mortem)\b|we (decid|agree|chose|said)/;
-var TEST_HINTS = /\b(test|spec|coverage|tested|test case|test cases|tests for|spec for)\b/;
-var EXPLICIT_NS = [
-  { pattern: /\b(pattern|convention|best practice|style|coding rule)\b/, ns: 'patterns', label: 'code patterns and conventions' },
-  { pattern: /\b(code.?map|file structure|project structure|directory)\b/, ns: 'code-map', label: 'codebase navigation' },
-];
-var PATTERN_HINTS = [/\b(template|example|similar to|how do we|how should)\b/];
-var DOMAIN_HINTS = [
-  /\b(guidance|guide|docs|documentation|rules|how-to)\b/,
-  /\b(architecture|design|domain|tenant|migrat|schema|deploy)/,
-  /\b(rule|requirement|constraint|compliance)\b/,
-];
-var NAV_PATTERNS = [
-  /\b(find|where|which file|look up|locate|endpoint|route|url|path)\b/,
-  /\b(class|function|method|component|service|entity|module)\b/,
-];
-
-var nsHint = '';
-if (TEST_HINTS.test(lower)) {
-  nsHint = 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
-} else if (LEARNINGS_HINTS.test(lower)) {
-  nsHint = 'Memory namespace hint: use "learnings" for user-directed decisions and distilled insights.';
-} else {
-  var found = EXPLICIT_NS.find(function(e) { return e.pattern.test(lower); });
-  if (found) {
-    nsHint = 'Memory namespace hint: use "' + found.ns + '" for ' + found.label + '.';
-  } else if (DOMAIN_HINTS.some(function(p) { return p.test(lower); })) {
-    nsHint = 'Memory namespace hint: search "guidance" and "learnings" for domain rules and project decisions.';
-  } else if (PATTERN_HINTS.some(function(p) { return p.test(lower); })) {
-    nsHint = 'Memory namespace hint: use "patterns" for code patterns and conventions.';
-  } else if (NAV_PATTERNS.some(function(p) { return p.test(lower); })) {
-    nsHint = 'Memory namespace hint: use "code-map" for codebase navigation.';
-  }
-}
+// #931 — Namespace hint classification moved into gate.cjs (computed by
+// prompt-reminder, stored on workflow-state.json, emitted once by
+// check-before-agent at Agent-spawn time). No per-prompt token leak now.
 
 // #867 — surface post-install restart notice. File is written by
 // scripts/post-install-notice.mjs and cleared by the SessionStart launcher
@@ -84,6 +50,6 @@ try {
   }
 } catch (e) { /* ENOENT or malformed — silent fast-path */ }
 
-var parts = [restartNotice, output.trim(), nsHint].filter(Boolean);
+var parts = [restartNotice, output.trim()].filter(Boolean);
 if (parts.length) process.stdout.write(parts.join('\n\n') + '\n');
 process.exit(0);

package/bin/session-start-launcher.mjs

@@ -14,6 +14,7 @@ import { fileURLToPath, pathToFileURL } from 'url';
 import { mofloDir } from './lib/moflo-paths.mjs';
 import { repairMemoryDbIfCorrupt } from './lib/db-repair.mjs';
 import { resolveMofloBin } from './lib/resolve-bin.mjs';
+import { applyRetiredPrune } from './lib/retired-files.mjs';
 
 // Headless skip (#860). The daemon's headless workers spawn `claude --print`
 // with CLAUDE_CODE_HEADLESS=true (see src/cli/services/headless-worker-
@@ -681,6 +682,56 @@ try {
         }
       }
 
+      // ── Sync .claude/agents/ + .claude/skills/ recursively (#948) ──────
+      // Pre-#948, agents and skills weren't manifest-tracked at all, so any
+      // file moflo retired (e.g. the 49 ruflo-aspirational agents in #932 or
+      // skill-builder in #945) would linger forever in consumer projects —
+      // Claude Code kept loading them on every prompt, paying the per-prompt
+      // roster tokens we just spent #932 fixing. Walking these dirs through
+      // syncFile() puts every shipped file in `currentManifest`, which lets
+      // the cleanup loop below auto-prune retired files going forward.
+      //
+      // Limitation: this only catches retirements that happen AFTER #948.
+      // For files retired BEFORE #948 (#932 + #945), see the retired-files.json
+      // hash-gated prune block further down — it ships a static list with
+      // content hashes so we only delete files the consumer didn't customize.
+      //
+      // User-authored files at custom paths (.claude/agents/custom/foo.md,
+      // .claude/skills/<custom>/SKILL.md) are NEVER passed through syncFile()
+      // because they don't exist in node_modules/moflo/, so they never enter
+      // the manifest and never get pruned — same proven safety story as
+      // scripts/helpers above.
+      async function syncDirRecursive(srcDir, destPrefix) {
+        if (!existsSync(srcDir)) return;
+        let entries;
+        try {
+          entries = readdirSync(srcDir, { recursive: true, withFileTypes: true });
+        } catch (err) {
+          emitWarning(`${destPrefix} readdir failed (${errMessage(err)})`);
+          return;
+        }
+        for (const entry of entries) {
+          if (!entry.isFile()) continue;
+          if (!entry.name.toLowerCase().endsWith('.md')) continue;
+          const parent = entry.parentPath || entry.path || srcDir;
+          const absSrc = resolve(parent, entry.name);
+          const rel = absSrc.slice(srcDir.length + 1).split(/[\\/]/).join('/');
+          const absDest = resolve(projectRoot, destPrefix, rel);
+          try { mkdirSync(dirname(absDest), { recursive: true }); } catch (err) {
+            emitWarning(`${destPrefix} subdir mkdir failed for ${rel} (${errMessage(err)})`);
+          }
+          await syncFile(absSrc, absDest, `${destPrefix}/${rel}`);
+        }
+      }
+      await syncDirRecursive(
+        resolve(projectRoot, 'node_modules/moflo/.claude/agents'),
+        '.claude/agents',
+      );
+      await syncDirRecursive(
+        resolve(projectRoot, 'node_modules/moflo/.claude/skills'),
+        '.claude/skills',
+      );
+
       // Sync all shipped guidance files from node_modules/moflo/.claude/guidance/shipped/
       const guidanceDir = resolve(projectRoot, '.claude/guidance');
       const shippedDir = resolve(projectRoot, 'node_modules/moflo/.claude/guidance/shipped');
@@ -725,6 +776,56 @@ try {
         emitMutation('cleaned up retired files', `${removedFiles} removed`);
       }
 
+      // ── Hash-gated prune of pre-#948 retirements (Mechanism B) ─────────
+      // The manifest cleanup above only knows about files moflo previously
+      // synced. Agents and skills retired BEFORE #948 (#932's 49 agents and
+      // #945's skill-builder, plus older retirements) were never in any
+      // manifest — they exist on disk in consumer projects only because
+      // earlier moflo versions shipped them via the npm tarball + flo init.
+      // `retired-files.json` is the explicit, reviewable static list that
+      // closes that gap. Each entry pairs a path with the sha256 hashes of
+      // every content version moflo previously shipped, so we only auto-
+      // prune when the consumer's file matches a known-shipped hash —
+      // customized files (different hash) get preserved with a one-line
+      // notice the user can act on.
+      try {
+        const retiredManifestPath = resolve(
+          projectRoot,
+          'node_modules/moflo/retired-files.json',
+        );
+        const report = applyRetiredPrune(projectRoot, retiredManifestPath);
+        if (report.pruned.length > 0) {
+          emitMutation(
+            'pruned retired shipped files',
+            `${plural(report.pruned.length, 'file')} matching known-shipped content removed`,
+          );
+        }
+        if (report.preserved.length > 0) {
+          // stdout (not stderr) so Claude sees this in `additionalContext`
+          // and can surface to the user — these aren't failures, just
+          // consumer-customized files we deliberately left alone.
+          const sample = report.preserved.slice(0, 5).map((p) => `  - ${p}`).join('\n');
+          const more = report.preserved.length > 5
+            ? `\n  …and ${report.preserved.length - 5} more`
+            : '';
+          try {
+            process.stdout.write(
+              `moflo: retained ${plural(report.preserved.length, 'customized retired file')} (delete manually if unwanted):\n${sample}${more}\n`,
+            );
+          } catch { /* non-fatal */ }
+        }
+        if (report.failed.length > 0) {
+          const sample = report.failed.slice(0, 3)
+            .map((f) => `  - ${f.path}: ${f.message}`).join('\n');
+          emitWarning(`${plural(report.failed.length, 'retired file')} failed to prune:\n${sample}`);
+        }
+      } catch (err) {
+        // Non-fatal — the consumer just doesn't get the prune this session.
+        // Next session retries; manifest-cleanup above still works for
+        // future retirements regardless.
+        emitWarning(`retired-files prune skipped (${errMessage(err)})`);
+      }
+
       // The daemon was already stopped above so the lock file is gone and
       // there's no live PID to recycle here. Section 4's `hooks.mjs
       // session-start` will spawn a fresh daemon under the current moflo
@@ -1093,7 +1194,7 @@ try {
 // Also prunes top-level mirrors whose source no longer exists in shipped/
 // (#839): pre-manifest-tracking mirrors never appeared in installed-files.json
 // so the section-3 manifest-diff cleanup can't reach them. The marker gate
-// protects user files and `moflo-bootstrap.md` (distinct `moflo init` marker).
+// protects user-authored files; pre-#939 moflo-bootstrap.md is handled by 3c-939.
 try {
   const guidanceDir = resolve(projectRoot, '.claude/guidance');
   const shippedDir = resolve(projectRoot, 'node_modules/moflo/.claude/guidance/shipped');
@@ -1169,6 +1270,24 @@ try {
   }
 } catch { /* non-fatal */ }
 
+// ── 3c-939. Remove pre-#939 moflo-bootstrap.md duplicate ────────────────────
+// Before #939, `flo init` Step 7 (and `flo-setup`) renamed moflo-subagents.md
+// to moflo-bootstrap.md while the launcher's stage-3 ALSO synced the original
+// name — consumers ended up with two copies of the same content on disk. The
+// rename is gone; this prunes any leftover from older installs. Marker-gated
+// so we never delete a homonymous user-authored file.
+try {
+  const legacyBootstrap = resolve(projectRoot, '.claude/guidance/moflo-bootstrap.md');
+  if (existsSync(legacyBootstrap)) {
+    const head = readFileSync(legacyBootstrap, 'utf-8').slice(0, 200);
+    const ours = head.includes('AUTO-GENERATED by moflo init') || head.includes('AUTO-GENERATED by flo-setup');
+    if (ours) {
+      unlinkSync(legacyBootstrap);
+      emitMutation('removed legacy moflo-bootstrap.md', 'duplicate of moflo-subagents.md (#939)');
+    }
+  }
+} catch { /* non-fatal */ }
+
 // ── 3d-yaml-create. Create moflo.yaml if missing (#895) ────────────────────
 // Sibling self-heal to 3d-yaml: that block APPENDS new sections to existing
 // yaml; this block CREATES the file from the canonical template when no yaml