moflo 4.9.19 → 4.9.21

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: {} };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -83,6 +83,78 @@ 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/,
+];
+
+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 = {};
+}
 // 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 +275,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 +287,24 @@ 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);
+      }
+    }
     break;
   }
   case 'check-before-scan': {
@@ -277,7 +372,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 +442,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 +467,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 +485,30 @@ 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 });
+    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:

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

@@ -53,6 +53,36 @@ function findProjectRoot() {
 
 const projectRoot = findProjectRoot();
 
+// Dogfood guard (#928). When this launcher runs inside the moflo repo itself,
+// .claude/scripts/, .claude/helpers/, and .claude/guidance/ are committed git
+// files — they ARE moflo's source of truth, not destinations to be re-synced
+// from node_modules. Drift heal would silently revert any post-publish edit
+// to one of those files (e.g. story #927's gate.cjs got reverted overnight
+// because manifest.size still pointed at the previously-published version).
+// Detection is `package.json#name === "moflo"` — the project's own package.json,
+// NOT node_modules/moflo/package.json. Defaults to false on any read/parse
+// error so a corrupt package.json never silently disables drift heal in a
+// real consumer.
+//
+// Workspace caveat: findProjectRoot() walks up to the nearest package.json,
+// so in a workspace child (packages/foo/) the read sees the child package
+// (name !== "moflo") and the guard stays false. moflo isn't a workspace
+// today; if it ever becomes one, run sessions from the repo root or extend
+// this check to walk further up.
+let isMofloDogfood = false;
+try {
+  const projectPkgPath = resolve(projectRoot, 'package.json');
+  if (existsSync(projectPkgPath)) {
+    const projectPkg = JSON.parse(readFileSync(projectPkgPath, 'utf-8'));
+    isMofloDogfood = projectPkg?.name === 'moflo';
+  }
+} catch (err) {
+  // Defaults to false — safer than accidentally disabling drift heal in a
+  // real consumer. Surface the failure so a corrupt project package.json
+  // doesn't silently change launcher behavior (per feedback_no_silent_failures).
+  process.stderr.write(`[moflo] dogfood-guard package.json read failed: ${err && err.message ? err.message : String(err)}\n`);
+}
+
 // Visible mutation reporter (#716). Claude Code's SessionStart hook captures
 // stdout as `additionalContext`, so each line here surfaces to Claude — and
 // through it to the user — explaining what the launcher just changed. Keep
@@ -360,6 +390,8 @@ try {
         }
       }
     }
+    // Dogfood (#928): never drift-heal moflo's own committed copies.
+    if (isMofloDogfood) manifestDrifted = false;
 
     if (installedVersion !== cachedVersion || manifestDrifted) {
       if (installedVersion !== cachedVersion) {
@@ -444,6 +476,20 @@ try {
 
       const binDir = resolve(projectRoot, 'node_modules/moflo/bin');
 
+      // Dogfood (#928): in moflo's own repo, the destinations under
+      // .claude/scripts/, .claude/helpers/, .claude/guidance/ are committed
+      // git files — copying node_modules/moflo content over them clobbers
+      // in-flight work (the same bug that silently reverted #927 between
+      // commit and publish). Skip the sync, cleanup, and manifest write
+      // entirely; queue the version-stamp write so we don't re-enter this
+      // branch on every subsequent session. Daemon recycle still happens
+      // (the stopDaemon call earlier handled this) and 3a-pre will spawn a
+      // fresh daemon under the new code.
+      if (isMofloDogfood) {
+        pendingVersionStampWrite = { path: versionStampPath, version: installedVersion };
+        emitMutation('skipped file-sync', 'moflo dogfood — committed dogfood copies preserved');
+      } else {
+
       // ── Manifest-based auto-update ──────────────────────────────────────
       //
       // IMPORTANT: Every file moflo installs into the destination project
@@ -709,6 +755,7 @@ try {
         // queued for 3g.
         emitWarning(`manifest write failed (${errMessage(err)})`);
       }
+      } // end !isMofloDogfood file-sync branch (#928)
     }
   }
 } catch (err) {
@@ -1046,7 +1093,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');
@@ -1122,6 +1169,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

package/bin/setup-project.mjs

@@ -11,78 +11,50 @@
  *   flo-setup --check    # Check if setup is current
  *
  * What it does:
- *   1. Copies .claude/guidance/shipped/moflo-subagents.md → project's .claude/guidance/moflo-bootstrap.md
+ *   1. Copies moflo/.claude/guidance/shipped/moflo-subagents.md → project's .claude/guidance/moflo-subagents.md
  *   2. Appends a subagent protocol section to CLAUDE.md (idempotent, with markers)
  *
+ * Historical note (#939): pre-fix builds renamed the destination to
+ * moflo-bootstrap.md, but the launcher's stage-3 also synced the original name
+ * — consumers ended up with two copies of the same content. The launcher now
+ * prunes any legacy moflo-bootstrap.md on first session-start after upgrade.
+ *
  * The project can layer its own guidance files on top for
  * project-specific rules (companyId, entity templates, etc.).
+ *
+ * The CLAUDE.md content is owned by `src/cli/init/claudemd-generator.ts` (compiled to
+ * `dist/src/cli/init/claudemd-generator.js`). This script is a thin wrapper so consumers
+ * always get byte-identical output regardless of which entry point they use
+ * (`flo init` vs `flo-setup`).
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, unlinkSync } from 'node:fs';
 import { dirname, resolve, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const mofloRoot = resolve(__dirname, '..');
+import { mofloInternalURL } from './lib/moflo-resolve.mjs';
+
+// Resolve moflo's installed package root via Node module resolution so the script
+// works identically from bin/ (canonical) or from .claude/scripts/ (synced copy).
+const mofloRoot = dirname(fileURLToPath(mofloInternalURL('package.json')));
+
+// Single source of truth: claudemd-generator.ts owns the section content.
+// Use the shared mofloInternalURL helper so the script works identically when
+// invoked from bin/ (canonical) or from .claude/scripts/ (synced copy).
+const {
+  generateClaudeMd,
+  MARKER_START,
+  MARKER_END,
+  LEGACY_MARKER_STARTS,
+  LEGACY_MARKER_ENDS,
+} = await import(mofloInternalURL('dist/src/cli/init/claudemd-generator.js'));
 
 const args = process.argv.slice(2);
 const updateOnly = args.includes('--update');
 const checkOnly = args.includes('--check');
 
-// Markers for idempotent CLAUDE.md updates — keep in sync with claudemd-generator.ts
-const MARKER_START = '<!-- MOFLO:INJECTED:START -->';
-const MARKER_END = '<!-- MOFLO:INJECTED:END -->';
-// Legacy markers to detect and replace
-const LEGACY_STARTS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:START -->', '<!-- MOFLO:START -->'];
-const LEGACY_ENDS = ['<!-- MOFLO:SUBAGENT-PROTOCOL:END -->', '<!-- MOFLO:END -->'];
-
-// Minimal injection — just enough for Claude to work with moflo.
-// All detailed docs live in .claude/guidance/shipped/moflo-core-guidance.md.
-const CLAUDE_MD_SECTION = `${MARKER_START}
-## MoFlo — AI Agent Orchestration
-
-This project uses [MoFlo](https://github.com/eric-cielo/moflo) for AI-assisted development workflows.
-
-### 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\`.
-
-### Workflow 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\`
-${MARKER_END}`;
+// Canonical section content (owned by claudemd-generator.ts). Trim the trailing newline
+// that generateClaudeMd appends so the marker-replace logic below stays exact.
+const CLAUDE_MD_SECTION = generateClaudeMd({}).trimEnd();
 
 function log(msg) {
   console.log(`[flo-setup] ${msg}`);
@@ -115,16 +87,16 @@ function findProjectRoot() {
   return null;
 }
 
-function copyBootstrap(projectRoot) {
+function copySubagentsGuidance(projectRoot) {
   const shippedSource = join(mofloRoot, '.claude', 'guidance', 'shipped', 'moflo-subagents.md');
   const source = existsSync(shippedSource)
     ? shippedSource
     : join(mofloRoot, '.claude', 'guidance', 'moflo-subagents.md');
   const targetDir = join(projectRoot, '.claude', 'guidance');
-  const target = join(targetDir, 'moflo-bootstrap.md');
+  const target = join(targetDir, 'moflo-subagents.md');
 
   if (!existsSync(source)) {
-    log('❌ Source bootstrap not found in moflo package');
+    log('❌ Source subagents guidance not found in moflo package');
     return false;
   }
 
@@ -143,12 +115,12 @@ function copyBootstrap(projectRoot) {
     const existing = readFileSync(target, 'utf-8');
     const newContent = header + content;
     if (existing === newContent) {
-      log('✅ moflo-bootstrap.md is current');
+      log('✅ moflo-subagents.md is current');
       return true;
     }
-    log('📝 Updating moflo-bootstrap.md');
+    log('📝 Updating moflo-subagents.md');
   } else {
-    log('📝 Creating .claude/guidance/moflo-bootstrap.md');
+    log('📝 Creating .claude/guidance/moflo-subagents.md');
   }
 
   if (!checkOnly) {
@@ -157,6 +129,25 @@ function copyBootstrap(projectRoot) {
   return true;
 }
 
+// Best-effort cleanup of pre-#939 moflo-bootstrap.md left over from prior
+// installs. Only removes the file if it carries one of our auto-generated
+// headers — never deletes a homonymous user-authored file. Idempotent.
+function cleanupLegacyBootstrap(projectRoot) {
+  const legacy = join(projectRoot, '.claude', 'guidance', 'moflo-bootstrap.md');
+  if (!existsSync(legacy)) return;
+  try {
+    const head = readFileSync(legacy, 'utf-8').slice(0, 200);
+    const ours = head.includes('AUTO-GENERATED by moflo init') || head.includes('AUTO-GENERATED by flo-setup');
+    if (!ours) return;
+    if (!checkOnly) {
+      unlinkSync(legacy);
+      log('🧹 Removed legacy moflo-bootstrap.md (pre-#939 duplicate of moflo-subagents.md)');
+    } else {
+      log('⚠️  Legacy moflo-bootstrap.md present — will be removed on next non-check run');
+    }
+  } catch { /* non-fatal */ }
+}
+
 function updateClaudeMd(projectRoot) {
   const claudeMdPath = join(projectRoot, 'CLAUDE.md');
 
@@ -173,8 +164,8 @@ function updateClaudeMd(projectRoot) {
   const content = readFileSync(claudeMdPath, 'utf-8');
 
   // Check for current or legacy markers and replace
-  const allStarts = [MARKER_START, ...LEGACY_STARTS];
-  const allEnds = [MARKER_END, ...LEGACY_ENDS];
+  const allStarts = [MARKER_START, ...LEGACY_MARKER_STARTS];
+  const allEnds = [MARKER_END, ...LEGACY_MARKER_ENDS];
 
   for (let i = 0; i < allStarts.length; i++) {
     if (content.includes(allStarts[i])) {
@@ -235,8 +226,11 @@ function main() {
   log(`Project: ${projectRoot}`);
   console.log('');
 
-  // Step 1: Copy bootstrap file
-  const bootstrapOk = copyBootstrap(projectRoot);
+  // Step 1: Copy subagents guidance under its real name (#939 — was moflo-bootstrap.md)
+  const bootstrapOk = copySubagentsGuidance(projectRoot);
+
+  // Step 1b: Remove pre-#939 moflo-bootstrap.md if it still exists from an older install
+  cleanupLegacyBootstrap(projectRoot);
 
   // Step 2: Update CLAUDE.md (skip on --update, only refresh the file)
   const claudeOk = updateOnly ? true : updateClaudeMd(projectRoot);

package/bin/simplify-classify.cjs

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 /**
- * /simplify diff classifier — issue #908.
+ * /flo-simplify diff classifier.
  *
  * Decides which review tier the current diff warrants and returns a JSON
- * dispatch decision. The /simplify skill MUST call this first so routing is
+ * dispatch decision. The /flo-simplify skill MUST call this first so routing is
  * deterministic and unit-testable instead of a prose decision Claude makes
  * over and over per run.
  *
- * Rule (per user direction): default to single-agent Sonnet review. Only
- * escalate to a 3-agent fan-out when diff signals genuinely warrant it.
- * Opus is never selected — the existing skill already documents that.
+ * Rule: default to single-agent Sonnet review. Only escalate to a 3-agent
+ * fan-out when diff signals genuinely warrant it. Opus is never selected —
+ * the existing skill already documents that.
  *
  * Outputs JSON:
  *   {
@@ -21,7 +21,8 @@
  *   }
  *
  * Usage:
- *   node bin/simplify-classify.cjs [--base main]
+ *   node bin/simplify-classify.cjs                  # auto-detects default branch
+ *   node bin/simplify-classify.cjs --base develop   # explicit override
  *   node bin/simplify-classify.cjs --diff <unified-diff-on-stdin>
  *
  * The --diff stdin form exists so unit tests can drive the classifier
@@ -31,7 +32,7 @@
 
 const { execSync } = require('child_process');
 
-// Paths where new logic warrants the 3-agent fan-out (issue #908).
+// Paths where new logic warrants the 3-agent fan-out.
 // Mechanical edits inside these paths are still SMALL; only adding/removing
 // declarations triggers escalation.
 const SECURITY_PATHS = [
@@ -49,6 +50,25 @@ function safeExec(cmd) {
   catch { return ''; }
 }
 
+// Detect the consumer's default branch. Hardcoding 'main' silently miscalibrates
+// classification on repos that use 'master', 'develop', etc. — empty diff →
+// TRIVIAL → gate stamps clean without any real review.
+let _cachedDefaultBranch = null;
+function detectDefaultBranch() {
+  if (_cachedDefaultBranch !== null) return _cachedDefaultBranch;
+
+  // Preferred: origin/HEAD points to whatever the remote considers default.
+  const symbolic = safeExec('git symbolic-ref --short refs/remotes/origin/HEAD').trim();
+  if (symbolic.startsWith('origin/')) return (_cachedDefaultBranch = symbolic.slice('origin/'.length));
+
+  // Fallback: local init.defaultBranch (set by `git init -b <name>` or config).
+  const configured = safeExec('git config --get init.defaultBranch').trim();
+  if (configured) return (_cachedDefaultBranch = configured);
+
+  // Last resort: 'main' (most common modern default).
+  return (_cachedDefaultBranch = 'main');
+}
+
 function readDiffFromGit(base) {
   // Combined diff: committed-since-base + working-tree
   const committed = safeExec(`git diff ${base}...HEAD`);
@@ -186,14 +206,15 @@ function classifyDiff(diffText) {
   return decide(parseDiff(diffText));
 }
 
-function classifyFromGit(base = 'main') {
-  return classifyDiff(readDiffFromGit(base));
+function classifyFromGit(base) {
+  const resolved = base || detectDefaultBranch();
+  return classifyDiff(readDiffFromGit(resolved));
 }
 
 if (require.main === module) {
   const args = process.argv.slice(2);
   const baseIdx = args.indexOf('--base');
-  const base = baseIdx >= 0 ? args[baseIdx + 1] : 'main';
+  const base = baseIdx >= 0 ? args[baseIdx + 1] : detectDefaultBranch();
   const stdinDiff = args.includes('--diff') || args.includes('--stdin');
 
   let result;
@@ -211,4 +232,4 @@ if (require.main === module) {
   }
 }
 
-module.exports = { parseDiff, decide, classifyDiff, classifyFromGit };
+module.exports = { parseDiff, decide, classifyDiff, classifyFromGit, detectDefaultBranch };

package/dist/src/cli/commands/doctor-checks-deep.js

@@ -425,6 +425,10 @@ const REQUIRED_GATE_CASES = [
     'check-before-pr',
     'check-dangerous-command',
     'prompt-reminder',
+    // #931 — Defensive safety-net for the second UserPromptSubmit hook. State
+    // reset only, no emission. doctor warns if a consumer's gate.cjs is too old
+    // to handle it.
+    'prompt-state-reset',
     'session-reset',
 ];
 // Import + re-export from the self-contained hook-wiring module (single source of truth).