moflo 4.9.19 → 4.9.21

package/dist/src/cli/init/claudemd-generator.js

@@ -3,60 +3,57 @@
  *
  * Generates ONLY the MoFlo section to inject into a project's CLAUDE.md.
  * This must be minimal — just enough for Claude to work with moflo.
- * All detailed docs live in .claude/guidance/shipped/moflo-core-guidance.md (copied at install).
+ * All detailed docs live in .claude/guidance/moflo-core-guidance.md on consumer projects (synced from .claude/guidance/shipped/ inside node_modules/moflo).
  *
  * Principle: we are guests in the user's CLAUDE.md. Keep it small.
  */
 const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
 const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
+// Legacy markers from earlier moflo versions — detected and replaced on re-injection.
+// Single source of truth so moflo-init.ts and bin/setup-project.mjs stay in sync.
+const LEGACY_MARKER_STARTS = [
+    '<!-- MOFLO:START -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:START -->',
+];
+const LEGACY_MARKER_ENDS = [
+    '<!-- MOFLO:END -->',
+    '<!-- MOFLO:SUBAGENT-PROTOCOL:END -->',
+];
 /**
  * The single moflo section injected into CLAUDE.md.
- * ~40 lines. Points to moflo-core-guidance.md for everything else.
+ * ~22 lines. Points to moflo-core-guidance.md for everything else.
  */
 function mofloSection() {
     return `${MARKER_START}
 ## MoFlo — AI Agent Orchestration
 
-This project uses [MoFlo](https://github.com/eric-cielo/moflo) for AI-assisted development spells.
-
 ### FIRST ACTION ON EVERY PROMPT: Search Memory
 
-MUST call \`mcp__moflo__memory_search\` BEFORE any Glob/Grep/Read/file exploration. Namespaces: \`guidance\`+\`patterns\`+\`learnings\` every prompt; \`code-map\` when navigating code; \`tests\` when looking for test inventory or coverage. When the user says "remember this": \`mcp__moflo__memory_store\` with namespace \`learnings\`.
-
-### Spell Gates (enforced automatically)
-
-- **Memory-first**: Must search memory before Glob/Grep/Read
-- **TaskCreate-first**: Must call TaskCreate before spawning Agent tool
-
-- **Task Icons**: \`TaskCreate\` MUST use ICON+[Role] format — see \`.claude/guidance/moflo-task-icons.md\`
+Your first tool call MUST be \`mcp__moflo__memory_search\` — before any Glob/Grep/Read. Search \`guidance\`, \`patterns\`, and \`learnings\` every prompt; add \`code-map\` when navigating code, \`tests\` when looking for test inventory or coverage. When the user says "remember this", call \`mcp__moflo__memory_store\` with namespace \`learnings\`.
 
-### MCP Tools (preferred over CLI)
+### Auto-enforced gates
 
-| Tool | Purpose |
-|------|---------|
-| \`mcp__moflo__memory_search\` | Semantic search across indexed knowledge |
-| \`mcp__moflo__memory_store\` | Store patterns and decisions |
+- **TaskCreate-first**: Call \`TaskCreate\` before spawning the Agent tool
+- **Task Icons**: \`TaskCreate\` entries MUST use ICON+[Role] format — see \`.claude/guidance/moflo-task-icons.md\`
 
-### CLI Fallback
+### Tools
 
-\`\`\`bash
-flo-search "[query]" --namespace guidance   # Semantic search
-flo doctor --fix                             # Health check
-\`\`\`
+Prefer MCP (\`mcp__moflo__*\` — memory, swarm, agent, task, hooks, hive-mind, neural) over the CLI. CLI binaries: \`flo\` (main), \`flo-search\` (semantic search), \`flo doctor --fix\` (heal). Full catalog: \`.claude/guidance/moflo-core-guidance.md\`.
 
 ### After upgrading MoFlo
 
-After running \`npm install moflo@*\` (or \`npm install\` that touches moflo), check \`.moflo/restart-pending.json\`. If it exists, surface the \`message\` field to the user verbatim (Claude Code can't pick up new hooks/MCP tools/launcher mid-session — they're only loaded at session-start), then delete the file.
+After \`npm install\` touches moflo, check \`.moflo/restart-pending.json\` — if present, surface its \`message\` field to the user verbatim, then delete the file. (Claude Code only loads new hooks/MCP/launcher at session start.)
 
 ### Full Reference
 
-- **Subagents protocol:** \`.claude/guidance/shipped/moflo-subagents.md\`
-- **Task + swarm coordination:** \`.claude/guidance/shipped/moflo-claude-swarm-cohesion.md\`
-- **CLI, hooks, swarm, memory, moflo.yaml:** \`.claude/guidance/shipped/moflo-core-guidance.md\`
+- Universal agent rules (memory protocol, git/PR conventions, file org, build/test): \`.claude/guidance/moflo-agent-rules.md\`
+- Subagent spawn protocol: \`.claude/guidance/moflo-subagents.md\`
+- Task + swarm coordination: \`.claude/guidance/moflo-claude-swarm-cohesion.md\`
+- CLI, hooks, swarm, memory, moflo.yaml: \`.claude/guidance/moflo-core-guidance.md\`
 ${MARKER_END}`;
 }
 // --- Public API ---
-export { MARKER_START, MARKER_END };
+export { MARKER_START, MARKER_END, LEGACY_MARKER_STARTS, LEGACY_MARKER_ENDS };
 /**
  * Generate the MoFlo section to inject into CLAUDE.md.
  * Template parameter is accepted for backward compatibility but ignored —
@@ -73,12 +70,12 @@ export function generateMinimalClaudeMd(options) {
 }
 /** Available template names for CLI wizard (kept for backward compat, all produce same output) */
 export const CLAUDE_MD_TEMPLATES = [
-    { name: 'minimal', description: 'Recommended — memory search, spell gates, MCP tools (~40 lines injected)' },
-    { name: 'standard', description: 'Same as minimal (detailed docs in .claude/guidance/shipped/moflo-core-guidance.md)' },
-    { name: 'full', description: 'Same as minimal (detailed docs in .claude/guidance/shipped/moflo-core-guidance.md)' },
-    { name: 'security', description: 'Same as minimal (detailed docs in .claude/guidance/shipped/moflo-core-guidance.md)' },
-    { name: 'performance', description: 'Same as minimal (detailed docs in .claude/guidance/shipped/moflo-core-guidance.md)' },
-    { name: 'solo', description: 'Same as minimal (detailed docs in .claude/guidance/shipped/moflo-core-guidance.md)' },
+    { name: 'minimal', description: 'Recommended — memory search, gates, tools, upgrade hint (~22 lines injected)' },
+    { name: 'standard', description: 'Same as minimal (detailed docs in .claude/guidance/moflo-core-guidance.md)' },
+    { name: 'full', description: 'Same as minimal (detailed docs in .claude/guidance/moflo-core-guidance.md)' },
+    { name: 'security', description: 'Same as minimal (detailed docs in .claude/guidance/moflo-core-guidance.md)' },
+    { name: 'performance', description: 'Same as minimal (detailed docs in .claude/guidance/moflo-core-guidance.md)' },
+    { name: 'solo', description: 'Same as minimal (detailed docs in .claude/guidance/moflo-core-guidance.md)' },
 ];
 export default generateClaudeMd;
 //# sourceMappingURL=claudemd-generator.js.map

package/dist/src/cli/init/executor.js

@@ -23,32 +23,44 @@ import { errorDetail } from '../shared/utils/error-detail.js';
 /**
  * Skills to copy based on configuration. Exported for integrity tests.
  */
+// Skills installed into a consumer's `<root>/.claude/skills/` by `flo init`.
+// Every entry must be a moflo-quality, consumer-runnable skill — verified to
+// reference moflo CLI/MCP tools (not upstream `claude-flow` / `agentic-flow`
+// cruft). New additions MUST pass the same audit, otherwise the drift-guard
+// test (skills-classification-drift.test.ts) fails. See INTERNAL_SKILLS for
+// skills that ship in the tarball but are deliberately NOT installed.
 export const SKILLS_MAP = {
     core: [
-        'swarm-orchestration',
-        'swarm-advanced',
-        'sparc-methodology',
-        'hooks-automation',
-        'pair-programming',
-        'verification-quality',
-        'stream-chain',
-        'skill-builder',
+        'eldar',
+        'guidance',
+        'flo-simplify',
         'reasoningbank-intelligence',
     ],
-    browser: ['browser'],
-    github: [
-        'github-code-review',
-        'github-multi-repo',
-        'github-project-management',
-        'github-release-management',
-        'github-workflow-automation',
+    memory: [
+        'memory-patterns',
+        'memory-optimization',
+        'vector-search',
+    ],
+    spells: [
+        'spell-builder',
+        'spell-schedule',
+        'connector-builder',
     ],
 };
+// Skills that ship in the npm tarball (under `node_modules/moflo/.claude/skills/`)
+// but are deliberately NOT copied into consumer projects by `flo init`. Strictly
+// moflo-internal dev tooling. The drift-guard test asserts every dir under
+// `.claude/skills/` is classified in either SKILLS_MAP or INTERNAL_SKILLS (plus
+// the special `flo` + `fl` install path handled in moflo-init.ts).
+export const INTERNAL_SKILLS = [
+    'publish', // moflo's own /publish workflow — not consumer-relevant
+    'reset-epic', // moflo's own epic test-data reset — would torch a consumer's repo
+];
 /**
  * Commands to copy based on configuration
  */
 const COMMANDS_MAP = {
-    core: ['claude-flow-help.md', 'claude-flow-swarm.md', 'claude-flow-memory.md', 'simplify.md'],
+    core: ['claude-flow-help.md', 'claude-flow-swarm.md', 'claude-flow-memory.md', 'flo-simplify.md'],
     analysis: [],
     automation: [],
     github: ['github'],

package/dist/src/cli/init/helpers-generator.js

@@ -207,7 +207,7 @@ var path = require('path');
 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, interactionCount: 0, sessionStart: null, lastBlockedAt: null };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} };
 
 function readState() {
   try {
@@ -278,6 +278,63 @@ var EXEMPT = ['.claude/', '.claude\\\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-sta
 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). Hint stored on workflow-state and emitted
+// once by check-before-agent at Agent-spawn time — was emitted on every prompt
+// before, costing ~40 tokens × every prompt × every consumer.
+//
+// SYNC: these regexes + classifyNamespaceHint + applyPromptStateReset are
+// duplicated verbatim in bin/gate.cjs (canonical, synced to consumer
+// .claude/helpers/gate.cjs by post-install-bootstrap). Any edit MUST be
+// applied to both — this template is the fallback for the flo-init path
+// where source helpers cannot be located, so it must keep parity.
+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/,
+];
+
+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 '';
+}
+
+function applyPromptStateReset(state, promptText) {
+  state.memorySearched = false;
+  state.memorySearchedBy = {};
+  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);
+  state.lastNamespaceHint = classifyNamespaceHint(promptText);
+  // Per-actor emission tracking — fresh window each prompt so subagents that
+  // spawn their own agents still see the hint on their first check-before-agent.
+  state.lastNamespaceHintEmittedBy = {};
+}
 var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\\s+(?:run\\s+)?(?:test|t)(?:[:\\s]|$)|\\b(?:npx|pnpx)\\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\\b|(?:^|;|&&|\\|\\|)\\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\\s|\\b(?:cargo|go|deno|dotnet|mvn)\\s+test\\b|\\bgradle\\w*\\s+test\\b/i;
 var EDIT_RESET_SKIP_BOTH_RE = /\\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^|[\\\\\\/])(CHANGELOG(?:\\.md)?|\\.env\\.example|package-lock\\.json|pnpm-lock\\.yaml|yarn\\.lock|bun\\.lockb)$/i;
 // Test files: invalidate testsRun but preserve simplifyRun (#908) — /simplify
@@ -290,6 +347,8 @@ 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 + namespace hint moved here from
+    // prompt-reminder so they emit only when Claude is about to spawn an Agent.
     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');
@@ -297,6 +356,23 @@ 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 emits the hint at most once
+      // per prompt. Subagents that spawn their own agents still see it on
+      // their first check-before-agent because their session_id is its own
+      // bucket. Falls back to a _legacy_ bucket when HOOK_SESSION_ID is
+      // missing (older Claude Code, direct CLI). The map clears on every
+      // new prompt via applyPromptStateReset.
+      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);
+      }
+    }
     break;
   }
   case 'check-before-scan': {
@@ -363,7 +439,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();
       if (!s.simplifyRun) {
         s.simplifyRun = true;
@@ -397,7 +474,7 @@ switch (command) {
     var s = readState();
     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');
@@ -422,18 +499,14 @@ switch (command) {
     break;
   }
   case 'prompt-reminder': {
+    // Full per-prompt reset (first UserPromptSubmit hook via prompt-hook.mjs).
+    // Owns interactionCount + Context warnings. TaskCreate REMINDER and
+    // namespace hint moved to check-before-agent (#931).
     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 || '';
-    s.memoryRequired = prompt.length >= 4 && !DIRECTIVE_RE.test(prompt) && (TASK_RE.test(prompt) || prompt.length > 80);
+    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.');
@@ -442,12 +515,25 @@ switch (command) {
     }
     break;
   }
+  case 'prompt-state-reset': {
+    // Defensive safety-net (second UserPromptSubmit hook). Idempotent state
+    // reset only — no interactionCount increment, no emission. Ensures the
+    // per-prompt reset still happens if prompt-hook.mjs throws (#931). Skip
+    // the disk write when prompt-reminder already wrote the byte-identical
+    // post-reset state (the normal no-exception path).
+    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 });
+    writeState({ tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, interactionCount: 0, sessionStart: new Date().toISOString(), lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {} });
     break;
   }
   default:
@@ -560,45 +646,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.';
-  }
-}
-
-var parts = [output.trim(), nsHint].filter(Boolean);
+// #931 — Namespace hint classification moved into gate.cjs (computed by
+// prompt-reminder, stored on workflow-state, emitted once by check-before-agent).
+var parts = [output.trim()].filter(Boolean);
 if (parts.length) process.stdout.write(parts.join('\\n') + '\\n');
 process.exit(0);
 `;

package/dist/src/cli/init/moflo-init.js

@@ -15,6 +15,8 @@ import { execSync } from 'child_process';
 import { locateMofloRootPath } from '../services/moflo-require.js';
 import { errorDetail } from '../shared/utils/error-detail.js';
 import { discoverGuidanceDirs, discoverSrcDirs, discoverTestDirs, detectExtensions, renderMofloYaml, } from './moflo-yaml-template.js';
+import { generateClaudeMd as generateMofloSection, MARKER_START, MARKER_END, LEGACY_MARKER_STARTS, LEGACY_MARKER_ENDS, } from './claudemd-generator.js';
+import { DEFAULT_INIT_OPTIONS } from './types.js';
 export { discoverTestDirs };
 // ============================================================================
 // Init
@@ -138,11 +140,10 @@ export async function initMoflo(options) {
     steps.push(syncScripts(projectRoot, force));
     // Step 6: .gitignore entries
     steps.push(updateGitignore(projectRoot));
-    // Step 7: .claude/guidance/moflo-bootstrap.md (subagent bootstrap protocol)
-    steps.push(syncBootstrapGuidance(projectRoot, force));
-    // Step 8: Sync ALL shipped guidance docs from moflo to project
+    // Step 7: Sync ALL shipped guidance docs from moflo to project (includes
+    // moflo-subagents.md — no separate rename to moflo-bootstrap.md, see #939)
     steps.push(...syncAllShippedGuidance(projectRoot, force));
-    // Step 9: Install global `flo` shim so bare `flo` command works without npx
+    // Step 8: Install global `flo` shim so bare `flo` command works without npx
     steps.push(installGlobalFloShim(projectRoot));
     return { steps };
 }
@@ -222,6 +223,16 @@ function generateHooks(root, force, answers) {
                     { "type": "command", "command": gateHook('check-dangerous-command'), "timeout": 2000 },
                     { "type": "command", "command": gateHook('check-before-pr'), "timeout": 2000 }
                 ]
+            },
+            {
+                // #931 — Advisory only; never blocks. TaskCreate REMINDER and the
+                // namespace hint moved here from UserPromptSubmit so they emit only
+                // when Claude is about to spawn an Agent — saves ~90 tokens × every
+                // prompt × every consumer. Routed via gate-hook.mjs so Claude Code's
+                // session_id is forwarded as HOOK_SESSION_ID, enabling per-actor
+                // single-shot emission (mirror of #879's record-memory-searched fix).
+                "matcher": "^Agent$",
+                "hooks": [{ "type": "command", "command": gateHook('check-before-agent'), "timeout": 2000 }]
             }
         ],
         "PostToolUse": [
@@ -252,12 +263,16 @@ function generateHooks(root, force, answers) {
                 "hooks": [{ "type": "command", "command": gateHook('record-skill-run'), "timeout": 2000 }]
             },
             {
+                // Anchored alternation — Claude Code anchors hook matchers (`^…$` semantics),
+                // so a bare `mcp__moflo__memory_` never matches any real MCP tool name and the
+                // hook silently no-ops (#929 regression). The explicit suffix list keeps the
+                // matcher narrow while catching every memory_* tool we ship.
                 // Use gateHook (not gate) so the wrapper forwards Claude Code's session_id as
                 // HOOK_SESSION_ID — record-memory-searched needs this to mark the per-actor map
                 // (memorySearchedBy[sid]) that check-before-read consults under #838's per-actor gating.
                 // Without it, the legacy boolean is set but the per-actor map stays empty, and the gate
                 // blocks every Read forever within the turn (issue #879).
-                "matcher": "mcp__moflo__memory_",
+                "matcher": "^mcp__moflo__memory_(search|retrieve|list|stats|store)$",
                 "hooks": [{ "type": "command", "command": gateHook('record-memory-searched'), "timeout": 3000 }]
             },
             {
@@ -272,11 +287,13 @@ function generateHooks(root, force, answers) {
                 ]
             },
             {
-                // prompt-reminder is REQUIRED to reset memorySearched/memorySearchedBy on each
-                // new prompt and reclassify memoryRequired. Without it, gate state leaks across
-                // prompts. Separate hook entry so a prompt-hook.mjs exception doesn't skip the reset.
+                // prompt-state-reset is REQUIRED to reset memorySearched/memorySearchedBy on
+                // each new prompt and reclassify memoryRequired. Without it, gate state leaks
+                // across prompts. Separate hook entry so a prompt-hook.mjs exception doesn't
+                // skip the reset. Idempotent state reset only — no emission, no
+                // interactionCount increment (#931 dedupe).
                 "hooks": [
-                    { "type": "command", "command": gateHook('prompt-reminder'), "timeout": 3000 }
+                    { "type": "command", "command": gateHook('prompt-state-reset'), "timeout": 3000 }
                 ]
             }
         ],
@@ -381,24 +398,16 @@ function generateSkill(root, force) {
 // ============================================================================
 // Step 4: CLAUDE.md MoFlo section
 // ============================================================================
-// Markers for idempotent CLAUDE.md injection — keep in sync with claudemd-generator.ts
-const MOFLO_MARKER = '<!-- MOFLO:INJECTED:START -->';
-const MOFLO_MARKER_END = '<!-- MOFLO:INJECTED:END -->';
-// Also detect legacy markers so we can replace them
-const LEGACY_MARKERS = ['<!-- MOFLO:START -->', '<!-- MOFLO:SUBAGENT-PROTOCOL:START -->'];
-const LEGACY_MARKERS_END = ['<!-- MOFLO:END -->', '<!-- MOFLO:SUBAGENT-PROTOCOL:END -->'];
-function generateClaudeMd(root, force) {
+function generateClaudeMd(root, _force) {
     const claudeMdPath = path.join(root, 'CLAUDE.md');
     let existing = '';
     if (fs.existsSync(claudeMdPath)) {
         existing = fs.readFileSync(claudeMdPath, 'utf-8');
-        // Check for current or legacy markers
-        const allStartMarkers = [MOFLO_MARKER, ...LEGACY_MARKERS];
-        const allEndMarkers = [MOFLO_MARKER_END, ...LEGACY_MARKERS_END];
+        // Strip current or legacy MoFlo block so we can re-inject the latest content.
+        const allStartMarkers = [MARKER_START, ...LEGACY_MARKER_STARTS];
+        const allEndMarkers = [MARKER_END, ...LEGACY_MARKER_ENDS];
         for (let i = 0; i < allStartMarkers.length; i++) {
             if (existing.includes(allStartMarkers[i])) {
-                // Always strip the existing section so we can re-inject the latest version.
-                // This ensures CLAUDE.md stays current when moflo updates its injected content.
                 const startIdx = existing.indexOf(allStartMarkers[i]);
                 const endIdx = existing.indexOf(allEndMarkers[i]);
                 if (endIdx > startIdx) {
@@ -407,60 +416,14 @@ function generateClaudeMd(root, force) {
             }
         }
     }
-    // Minimal injection — just enough for Claude to work with moflo.
-    // All detailed docs live in .claude/guidance/shipped/moflo-core-guidance.md.
-    const mofloSection = `
-${MOFLO_MARKER}
-## MoFlo — AI Agent Orchestration
-
-This project uses [MoFlo](https://github.com/eric-cielo/moflo) for AI-assisted development spells.
-
-### FIRST ACTION ON EVERY PROMPT: Search Memory
-
-Your first tool call for every new user prompt MUST be a memory search. Do this BEFORE Glob, Grep, Read, or any file exploration.
-
-\`\`\`
-mcp__moflo__memory_search — query: "<task description>", namespace: "guidance" or "patterns" or "learnings" or "code-map" or "tests"
-\`\`\`
-
-Search \`guidance\`, \`patterns\`, and \`learnings\` namespaces on every prompt. Search \`code-map\` when navigating the codebase, \`tests\` when looking for test inventory or coverage.
-When the user asks you to remember something: \`mcp__moflo__memory_store\` with namespace \`learnings\`.
-
-### Spell Gates (enforced automatically)
-
-- **Memory-first**: Must search memory before Glob/Grep/Read
-- **TaskCreate-first**: Must call TaskCreate before spawning Agent tool
-- **Task Icons**: \`TaskCreate\` MUST use ICON+[Role] format — see \`.claude/guidance/moflo-task-icons.md\`
-
-### MCP Tools (preferred over CLI)
-
-| Tool | Purpose |
-|------|---------|
-| \`mcp__moflo__memory_search\` | Semantic search across indexed knowledge |
-| \`mcp__moflo__memory_store\` | Store patterns and decisions |
-| \`mcp__moflo__hooks_route\` | Route task to optimal agent type |
-| \`mcp__moflo__hooks_pre-task\` | Record task start |
-| \`mcp__moflo__hooks_post-task\` | Record task completion for learning |
-
-### CLI Fallback
-
-\`\`\`bash
-flo-search "[query]" --namespace guidance   # Semantic search
-flo doctor --fix                             # Health check
-\`\`\`
-
-### Full Reference
-
-For CLI commands, hooks, agents, swarm config, memory commands, and moflo.yaml options, see:
-\`.claude/guidance/shipped/moflo-core-guidance.md\`
-${MOFLO_MARKER_END}
-`;
-    const finalContent = existing.trimEnd() + '\n' + mofloSection;
+    // Single source of truth: claudemd-generator.ts owns the section content.
+    const canonical = generateMofloSection(DEFAULT_INIT_OPTIONS);
+    const finalContent = existing.trimEnd() + '\n\n' + canonical;
     fs.writeFileSync(claudeMdPath, finalContent, 'utf-8');
     return {
         name: 'CLAUDE.md',
         status: existing ? 'updated' : 'created',
-        detail: 'MoFlo section injected (~35 lines)',
+        detail: 'MoFlo section injected (~22 lines)',
     };
 }
 // ============================================================================
@@ -561,48 +524,10 @@ function updateGitignore(root) {
     return { name: '.gitignore', status: 'updated', detail: `Added: ${toAdd.join(', ')}` };
 }
 // ============================================================================
-// Step 7: .claude/guidance/moflo-bootstrap.md
-// Copies the agent bootstrap guidance to the project so subagents can read it
-// from disk without requiring memory search.
-// ============================================================================
-function syncBootstrapGuidance(root, force) {
-    const guidanceDir = path.join(root, '.claude', 'guidance');
-    const targetFile = path.join(guidanceDir, 'moflo-bootstrap.md');
-    const candidates = [
-        path.join(root, 'node_modules', 'moflo', '.claude', 'guidance', 'shipped', 'moflo-subagents.md'),
-        // Anchor on moflo's own package root (covers dev + installed; #782).
-        ...mofloRootJoin('.claude', 'guidance', 'shipped', 'moflo-subagents.md'),
-    ];
-    const sourceFile = candidates.find(f => { try {
-        return fs.existsSync(f);
-    }
-    catch {
-        return false;
-    } });
-    if (!sourceFile) {
-        return { name: 'guidance/moflo-bootstrap.md', status: 'skipped', detail: 'Source bootstrap not found' };
-    }
-    // Check if target exists and is up to date
-    if (fs.existsSync(targetFile) && !force) {
-        if (!isStale(sourceFile, targetFile)) {
-            return { name: 'guidance/moflo-bootstrap.md', status: 'skipped', detail: 'Already up to date' };
-        }
-    }
-    // Read source and prepend header
-    const content = fs.readFileSync(sourceFile, 'utf-8');
-    const header = `<!-- AUTO-GENERATED by moflo init. Do not edit — changes will be overwritten on next init. -->\n<!-- Source: moflo/.claude/guidance/shipped/moflo-subagents.md -->\n<!-- To customize, create your own project-specific guidance in .claude/guidance/. -->\n\n`;
-    fs.mkdirSync(guidanceDir, { recursive: true });
-    fs.writeFileSync(targetFile, header + content, 'utf-8');
-    return {
-        name: 'guidance/moflo-bootstrap.md',
-        status: fs.existsSync(targetFile) ? 'updated' : 'created',
-        detail: 'Subagent bootstrap protocol'
-    };
-}
-// ============================================================================
-// Step 8: Sync ALL shipped guidance docs
+// Step 7: Sync ALL shipped guidance docs
 // Discovers all .md files in moflo/.claude/guidance/shipped/ and copies them
-// to project .claude/guidance/. Skips moflo-subagents.md (handled by Step 7).
+// to project .claude/guidance/ (including moflo-subagents.md — see #939, prior
+// versions renamed it to moflo-bootstrap.md, creating a structural duplicate).
 // ============================================================================
 function syncAllShippedGuidance(root, force) {
     const guidanceDir = path.join(root, '.claude', 'guidance');
@@ -621,8 +546,10 @@ function syncAllShippedGuidance(root, force) {
     if (!shippedDir) {
         return [{ name: 'guidance/shipped/*', status: 'skipped', detail: 'Shipped guidance directory not found' }];
     }
-    // Discover all .md files, skip moflo-subagents.md (synced separately as moflo-bootstrap.md)
-    const files = fs.readdirSync(shippedDir).filter(f => f.endsWith('.md') && f !== 'moflo-subagents.md');
+    // Discover all shipped .md files dynamically — including moflo-subagents.md
+    // (#939: prior versions renamed it to moflo-bootstrap.md as a separate step,
+    // which left two copies of the same content on consumer disk).
+    const files = fs.readdirSync(shippedDir).filter(f => f.endsWith('.md'));
     if (files.length === 0) {
         return [{ name: 'guidance/shipped/*', status: 'skipped', detail: 'No shipped guidance files found' }];
     }