moflo 4.12.0 → 4.12.2

package/.claude/agents/base-template-generator.md

@@ -1,6 +1,6 @@
 ---
 name: base-template-generator
-description: Use this agent when you need to create foundational templates, boilerplate code, or starter configurations for new projects, components, or features. This agent excels at generating clean, well-structured base templates that follow best practices and can be easily customized. Examples: <example>Context: User needs to start a new React component and wants a solid foundation. user: 'I need to create a new user profile component' assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.' <commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary></example> <example>Context: User is setting up a new API endpoint and needs a template. user: 'Can you help me set up a new REST API endpoint for user management?' assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.' <commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary></example>
+description: Create foundational templates, boilerplate code, and starter configurations for new projects, components, or features. Use for scaffolding a new component, API endpoint, model, config, or test suite from scratch.
 color: orange
 ---
 
@@ -19,6 +19,26 @@ On chunk hits where `navigation` is non-null, traverse via `mcp__moflo__memory_g
 
 You are a Base Template Generator, an expert architect specializing in creating clean, well-structured foundational templates and boilerplate code. Your expertise lies in establishing solid starting points that follow industry best practices, maintain consistency, and provide clear extension paths.
 
+## When you get dispatched
+
+Worked examples of the requests that route here — these live in the body, not the
+frontmatter `description`, because the description is always-resident routing
+context while this body only loads on dispatch.
+
+<example>
+Context: User needs to start a new React component and wants a solid foundation.
+user: 'I need to create a new user profile component'
+assistant: 'I'll use the base-template-generator agent to create a comprehensive React component template with proper structure, TypeScript definitions, and styling setup.'
+<commentary>Since the user needs a foundational template for a new component, use the base-template-generator agent to create a well-structured starting point.</commentary>
+</example>
+
+<example>
+Context: User is setting up a new API endpoint and needs a template.
+user: 'Can you help me set up a new REST API endpoint for user management?'
+assistant: 'I'll use the base-template-generator agent to create a complete API endpoint template with proper error handling, validation, and documentation structure.'
+<commentary>The user needs a foundational template for an API endpoint, so use the base-template-generator agent to provide a comprehensive starting point.</commentary>
+</example>
+
 Your core responsibilities:
 - Generate comprehensive base templates for components, modules, APIs, configurations, and project structures
 - Ensure all templates follow established coding standards and best practices from the project's CLAUDE.md guidelines

package/.claude/guidance/shipped/moflo-yaml-reference.md

@@ -123,14 +123,54 @@ auto_update:
   helpers: true                          # Sync .claude/helpers/ from moflo source
   hook_block_drift: regenerate           # warn | regenerate | off (default: regenerate since #1227)
   claudemd_injection_drift: regenerate   # warn | regenerate | off
+
+# Which skill categories to install (OPTIONAL — omit to get every skill)
+skills:
+  categories: [core, memory, spells]     # core | memory | spells
 ```
 
 If your `moflo.yaml` predates the `sandbox:` or `auto_update:` blocks, they are auto-appended on the next session start — you never need to re-run `moflo init` after a version bump.
 
+### Narrowing Installed Skills with `skills.categories`
+
+**Omit the `skills:` block entirely to receive every moflo skill — that is the default and the recommended setting.** Add `skills.categories` only when you want a smaller always-resident skill listing, and expect to lose the commands in the categories you drop.
+
+Every installed skill's name and description sit in Claude's context in every session, so a project that will never author a spell can reclaim that space. The cost is real but small — the full set is roughly 2,000 tokens.
+
+| Category | Skills | Drop it when |
+|----------|--------|--------------|
+| `core` | `/fl`, `/healer`, `/verify`, `/flo-simplify`, `/eldar`, `/quicken`, `/ward`, `/divine`, `/meditate`, `/guidance`, `/commune`, `/luminarium` | Never — these are the everyday commands |
+| `memory` | `/memory-patterns`, `/vector-search`, `/memory-optimization`, `/memory-team`, `/memory-worktree` | You are not building on moflo's memory stack and have finished any team/worktree sharing setup |
+| `spells` | `/spell-builder`, `/spell-schedule`, `/connector-builder` | You do not author or schedule spells in this project |
+
+Both YAML list styles work:
+
+```yaml
+skills:
+  categories: [core, memory]
+```
+
+```yaml
+skills:
+  categories:
+    - core
+    - memory
+```
+
+**Key behaviors:**
+
+- **Omitting `skills:` means no restriction.** Every shipped skill syncs on every session start, exactly as before this option existed.
+- **`/flo` and `/fl` are never gated.** The ticket spell is the primary entry point and installs regardless of selection.
+- **An unknown category name is ignored, not fatal.** A typo narrows nothing rather than silently stripping your skills.
+- **Narrowing stops future syncing; it does not delete.** Skills already on disk stay until you remove them — moflo will not re-add them once excluded, so delete the directories under `.claude/skills/` to reclaim the context.
+- **Re-widening is instant.** Add the category back and the next session start restores its skills.
+
 ### Key Behaviors
 
 | Config | Effect |
 |--------|--------|
+| `skills.categories` omitted | Install every skill (default) |
+| `skills.categories: [core]` | Install only core skills; `memory` + `spells` stop syncing |
 | `auto_index.guidance: false` | Skip guidance indexing on session start |
 | `auto_index.code_map: false` | Skip code map generation on session start |
 | `auto_meditate.enabled: false` | Opt out of automatic session-lesson distillation (`/meditate` still works manually) |

package/.claude/helpers/gate.cjs

@@ -104,6 +104,19 @@ function loadSddConfig() {
   return out;
 }
 
+// Parse the top-level `merge:` block from moflo.yaml (#1285). Block-scoped for
+// the same reason as loadSddConfig: a bare `auto:` key can appear under other
+// sections. Cross-platform: tolerates CRLF.
+function loadMergeConfig() {
+  var out = { auto: false };
+  var content = MOFLO_YAML;
+  if (!content) return out;
+  var block = content.match(/^merge:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m);
+  if (!block) return out;
+  if (/^\s*auto:\s*true\b/im.test(block[1])) out.auto = true;
+  return out;
+}
+
 // Read moflo.yaml exactly once per gate process (#1297 review): loadGateConfig
 // and loadSddConfig both parse it, and the gate fires on every Write/Edit — a
 // second read is wasted syscalls. Single readFileSync in try/catch (no existsSync
@@ -116,10 +129,18 @@ var MOFLO_YAML = readMofloYaml();
 
 var config = loadGateConfig();
 var sddConf = loadSddConfig();
+var mergeConf = loadMergeConfig();
 var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 
+// Appended to every memory-first denial. Without it, a context audit of Claude
+// Code's denial telemetry reads moflo's gate enforcements as permission-setup
+// failures and "fixes" them with allow rules — which cannot override a hook
+// block at all (#1307 finding 5). Naming the gate makes the cause self-evident.
+var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule — allow-rules cannot override it.';
+var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
+
 // #1294 Finding 3 — reads/scans of EPHEMERAL files under the OS temp dir
 // (background-task output/transcripts, agent scratchpads) are transient tool
 // I/O and never carry indexable project knowledge, so they must not trip the
@@ -288,16 +309,71 @@ function detectFlMode(promptText) {
   return null;
 }
 
-// #1297 — arm the SDD implement gate from the user prompt. Only /fl or /flo runs
-// can arm it. Explicit -sd/--sdd wins; --no-sdd disarms; otherwise honor the
-// sdd.default config. `-sd` is a distinct token from `-s` (swarm): the `d` sits
-// on the word boundary so `-s\b` never matches `-sd`.
-function detectSddMode(promptText) {
+// Resolve the FULL set of /flo run modifiers from the prompt + moflo.yaml — the
+// single source of truth for both gate arming (#1297) and the authoritative
+// announcement emitted by prompt-reminder. Two consumers, one resolver: a second
+// implementation is exactly how `sdd.default: true` got silently ignored (the
+// skill's prompt carried `let sddMode = false` and the model executed the literal).
+//
+// Precedence per key: explicit --no-X > explicit -x/--X > moflo.yaml > built-in.
+// NOTE the differing built-in defaults: sdd is opt-IN (false), verify is opt-OUT
+// (true, #1294), merge is opt-IN (false, #1285).
+//
+// `-sd` is a distinct token from `-s` (swarm): the `d` sits on the word boundary
+// so `-s\b` never matches `-sd`.
+function resolveFloRun(promptText) {
   var p = promptText || '';
-  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return false;
-  if (/(?:^|\s)--no-sdd\b/.test(p)) return false;
-  if (/(?:^|\s)(?:-sd|--sdd)\b/.test(p)) return true;
-  return !!sddConf.default;
+  var out = { isFlo: false, workflow: 'full', sdd: false, verify: false, merge: false,
+              sddSrc: 'default', verifySrc: 'default', mergeSrc: 'default' };
+  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return out;
+  out.isFlo = true;
+
+  // Workflow mode — decides which modifiers are even applicable.
+  if (/(?:^|\s)(?:-wf|--workflow)\b/.test(p)) out.workflow = 'spell-engine';
+  else if (/(?:^|\s)(?:-r|--research)\b/.test(p)) out.workflow = 'research';
+  else if (/(?:^|\s)(?:-t|--ticket)\b/.test(p)) out.workflow = 'ticket';
+  var epicBranch = /(?:^|\s)--epic-branch\b/.test(p);
+
+  if (/(?:^|\s)--no-sdd\b/.test(p)) { out.sdd = false; out.sddSrc = 'flag'; }
+  else if (/(?:^|\s)(?:-sd|--sdd)\b/.test(p)) { out.sdd = true; out.sddSrc = 'flag'; }
+  else if (sddConf.default) { out.sdd = true; out.sddSrc = 'moflo.yaml sdd.default'; }
+
+  if (/(?:^|\s)--no-verify\b/.test(p)) { out.verify = false; out.verifySrc = 'flag'; }
+  else if (/(?:^|\s)(?:-v|--verify)\b/.test(p)) { out.verify = true; out.verifySrc = 'flag'; }
+  else if (!config.verify_before_done) { out.verify = false; out.verifySrc = 'moflo.yaml gates.verify_before_done'; }
+  else { out.verify = true; out.verifySrc = 'default'; }
+  // --sdd implies --verify: a spec/plan without an enforced verify step drifts.
+  if (out.sdd && !out.verify && out.verifySrc !== 'flag') out.verify = true;
+
+  if (/(?:^|\s)--no-merge\b/.test(p)) { out.merge = false; out.mergeSrc = 'flag'; }
+  else if (/(?:^|\s)(?:-m|--merge)\b/.test(p)) { out.merge = true; out.mergeSrc = 'flag'; }
+  else if (mergeConf.auto) { out.merge = true; out.mergeSrc = 'moflo.yaml merge.auto'; }
+
+  // Applicability: -t/-r never implement, so verify is a no-op there; -r produces
+  // no artifacts, so sdd is a no-op too (in -t the spec/plan goes INTO the ticket,
+  // so sdd stays on). Only a full non-epic-branch run opens a PR to merge.
+  // Re-attribute anything applicability turned off, so a false never carries the
+  // source of the value it no longer has. This whole change exists to stop modes
+  // being reported inaccurately — the attribution has to be honest too.
+  if (out.workflow === 'ticket' || out.workflow === 'research') {
+    if (out.verify) out.verifySrc = out.workflow + ' mode does not implement';
+    out.verify = false;
+  }
+  if (out.workflow === 'research' || out.workflow === 'spell-engine') {
+    if (out.sdd) out.sddSrc = out.workflow + ' mode produces no spec artifacts';
+    out.sdd = false;
+  }
+  if (out.workflow !== 'full' || epicBranch) {
+    if (out.merge) out.mergeSrc = epicBranch ? '--epic-branch owns merging' : out.workflow + ' mode opens no PR';
+    out.merge = false;
+  }
+  return out;
+}
+
+// #1297 — arm the SDD implement gate from the user prompt. Thin wrapper so the
+// arming decision and the announced decision can never disagree.
+function detectSddMode(promptText) {
+  return resolveFloRun(promptText).sdd;
 }
 
 // Resolve the absolute specs root the same way TS specsRoot does (#1294): split
@@ -644,7 +720,7 @@ switch (command) {
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (isEphemeralPath(process.env.TOOL_INPUT_path)) break;
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -657,7 +733,7 @@ switch (command) {
     if (isEphemeralPath(fp)) break;
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'record-task-created': {
@@ -706,11 +782,12 @@ switch (command) {
     // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
     var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
     process.stderr.write(
-      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'BLOCKED [moflo memory_first gate]: Search memory before reading files via Bash.\n' +
       'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
       (hint ? hint + '\n' : '') +
       'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
-      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+      GATE_ORIGIN_NOTE + '\n' +
+      GATE_DISABLE_NOTE + '\n'
     );
     process.exit(2);
     break;
@@ -981,6 +1058,33 @@ switch (command) {
     applyPromptStateReset(s, prompt);
     s.interactionCount = (s.interactionCount || 0) + 1;
     writeState(s);
+    // Announce the resolved /flo run modifiers. The gate already parsed
+    // moflo.yaml in THIS process (fresh per prompt — a git pull or a mid-session
+    // yaml edit is picked up automatically, no cache to invalidate), so this
+    // costs no extra read. Emitting it is what closes the loop: the skill used
+    // to carry `let sddMode = false` as a literal and the model executed it,
+    // silently ignoring `sdd.default: true`. Only fires on /fl|/flo prompts.
+    var floRun = resolveFloRun(prompt);
+    if (floRun.isFlo) {
+      console.log(
+        '[moflo] /flo run modes (AUTHORITATIVE — use verbatim; do NOT re-derive from the skill defaults): ' +
+        'sdd=' + (floRun.sdd ? 'ON' : 'off') +
+        ' verify=' + (floRun.verify ? 'ON' : 'off') +
+        ' merge=' + (floRun.merge ? 'ON' : 'off') +
+        ' [workflow=' + floRun.workflow + ']'
+      );
+      // Spell out the surprising case: a project default the user did not type.
+      if (floRun.sdd && floRun.sddSrc !== 'flag') {
+        console.log(
+          '[moflo] sdd is ON via ' + floRun.sddSrc + ' — the spec→plan→implement→verify cycle is ' +
+          'MANDATORY this run. Author the spec before editing source (the sdd_gate blocks source ' +
+          'Write/Edit until a reviewed plan exists). One-off opt out: re-run with --no-sdd.'
+        );
+      }
+      if (floRun.merge && floRun.mergeSrc !== 'flag') {
+        console.log('[moflo] merge is ON via ' + floRun.mergeSrc + ' — the PR will be auto-merged. Opt out: --no-merge.');
+      }
+    }
     if (config.context_tracking) {
       var ic = s.interactionCount;
       if (ic > 30) console.log('Context: CRITICAL. Commit, store learnings, suggest new session.');

package/.claude/skills/distill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: distill
-description: Alias for /flo-simplify. Review changed code for reuse, quality, and efficiency, then fix any issues found — effort scales to the diff size.
+description: Alias for /flo-simplify — see that skill's description.
 ---
 
 # /distill is an alias for /flo-simplify

package/.claude/skills/fl/SKILL.md

@@ -72,7 +72,7 @@ Two **independent** modifiers, orthogonal to execution mode (`-n`/`-s`/`-h`) and
 | `-v` | `--verify` | **Verify-before-done** — a normal run plus the `/verify` skill (the completion gate), no spec/plan front-half. **On by default** (#1294) — this flag only forces it back on for a project that set `gates.verify_before_done: false`. |
 | `--no-sdd`, `--no-verify` | | Opt a single run out. `--no-verify` skips the (default-on) verify step. |
 
-Defaults seed from `moflo.yaml` — `sdd.default` (default **off**) and `gates.verify_before_done` (default **on** since #1294). So the SDD spec/plan ceremony is opt-in, but **verify-before-done runs by default**; per-run flags override (`--no-verify` to skip). `--sdd` implies `--verify` (a spec/plan without an enforced verify step drifts). In `-t`/`-r` modes (no implementation) verify is a no-op — cleared silently, with the one-line ignored note only when the user explicitly passed `-v`/`--verify`; `--sdd` in `-t` writes the spec/plan **into the ticket** rather than scaffolding artifacts. Full mechanics in `./sdd.md`.
+Defaults seed from `moflo.yaml` — `sdd.default` (built-in **off**) and `gates.verify_before_done` (built-in **on** since #1294). So the SDD spec/plan ceremony is opt-in *by default*, but **a project can turn it on for every run** — never assume it is off; resolve it per the "Resolved run modes" section below. Verify-before-done runs by default; per-run flags override (`--no-verify` to skip). `--sdd` implies `--verify` (a spec/plan without an enforced verify step drifts). In `-t`/`-r` modes (no implementation) verify is a no-op — cleared silently, with the one-line ignored note only when the user explicitly passed `-v`/`--verify`; `--sdd` in `-t` writes the spec/plan **into the ticket** rather than scaffolding artifacts. Full mechanics in `./sdd.md`.
 
 ## Auto-merge (#1285)
 
@@ -124,6 +124,35 @@ Read the relevant file before executing that part of the run.
 | `./spell-engine.md` | `-wf` invocations (list, info, execute) |
 | `./sdd.md` | `-sd`/`--sdd` and `-v`/`--verify` — the spec→plan→implement→verify cycle |
 
+## Resolved run modes — read this BEFORE parsing arguments
+
+`sddMode`, `verifyMode`, and `mergeMode` are **config-derived**. Their project defaults live in `moflo.yaml` (`sdd.default`, `gates.verify_before_done`, `merge.auto`), so they cannot be known from this document — you MUST obtain them, never assume them. A run that assumes `sdd=off` on a project with `sdd.default: true` silently skips the entire spec→plan cycle, which is the exact failure this step exists to prevent.
+
+**Primary source — the injected resolution line.** moflo's `prompt-reminder` hook resolves all three from `moflo.yaml` on every `/flo` prompt (fresh process per prompt, so a `git pull` or a mid-session edit to `moflo.yaml` is picked up automatically) and emits them into your context immediately above the user's message:
+
+```
+[moflo] /flo run modes (AUTHORITATIVE — use verbatim; do NOT re-derive from the skill defaults): sdd=ON verify=ON merge=off [workflow=full]
+```
+
+Scan for that `[moflo] /flo run modes` line and assign `sddMode` / `verifyMode` / `mergeMode` from it **verbatim**. It already accounts for flags the user typed, `moflo.yaml` defaults, `--sdd` implying `--verify`, and mode applicability — do not second-guess it.
+
+**Fallback — no such line in context** (hooks disabled, or a consumer on a gate.cjs predating this). Shell out once; the CLI resolves from the same precedence rules:
+
+```bash
+flo sdd mode --args="$ARGUMENTS"
+```
+
+Use `--args=` (with the `=`), **not** `--args <value>` — a value starting with `-` would otherwise be parsed as flags and you would silently get the bare config default back.
+
+```json
+{ "workflow": "full", "sdd": true, "verify": true, "merge": false,
+  "sddSrc": "moflo.yaml sdd.default", "verifySrc": "default", "mergeSrc": "default" }
+```
+
+**Never skip both.** If the injected line is absent and the CLI call fails, say so explicitly to the user and stop rather than proceeding on a guessed mode — a wrongly-assumed `sdd=off` is invisible to the user until the PR lands without a spec.
+
+When `sdd` resolved ON from config rather than a typed flag, state that in your first message (e.g. *"SDD is on via `moflo.yaml sdd.default` — running the spec→plan→implement→verify cycle."*) so the user can `--no-sdd` out before work starts.
+
 ## Argument parsing
 
 ```javascript
@@ -135,21 +164,13 @@ let epicBranch = null;
 let issueNumber = null;
 let titleWords = [];
 
-// SDD/verify modifiers (Epic #1269, #1294). Seed from moflo.yaml BEFORE parsing
-// so a project default applies unless a per-run flag overrides it. Read the two
-// keys from moflo.yaml at the project root — NOTE the different absent-defaults:
-//   sddMode    ← `sdd.default`            (absent ⇒ false — spec/plan is opt-in)
-//   verifyMode ← `gates.verify_before_done` (absent ⇒ TRUE — verify is on by default, #1294)
-let sddMode = false;          // -sd / --sdd  (full spec→plan→implement→verify)
-let verifyMode = true;        // -v / --verify (on by default; --no-verify opts out)
+// SDD / verify / merge modifiers (Epic #1269, #1294, #1285) — DO NOT resolve
+// these here. They are config-derived, and the values below are placeholders,
+// NOT defaults. Take them from the "Resolved run modes" step above; the loop
+// below only applies what the user typed on top of that resolution.
+let sddMode, verifyMode, mergeMode;   // ← assigned from the resolution, never guessed
 let verifyExplicit = false;   // did the user actually type -v/--verify? (drives the -t/-r note only, so it doesn't fire on the default)
 
-// Auto-merge modifier (#1285). Seed from moflo.yaml BEFORE parsing, same as
-// sddMode/verifyMode: read `merge.auto` at the project root (absent ⇒ false).
-// When true, a full run awaits the PR's merge preconditions and merges it
-// (Phase 5.3b) instead of stopping at "PR opened".
-let mergeMode = false;        // -m / --merge  ← moflo.yaml merge.auto
-
 let wfName = null, wfSubcommand = null;
 let wfArgs = [], wfNamedArgs = {};
 

package/.claude/skills/fl/sdd.md

@@ -2,10 +2,12 @@
 
 Spec-Driven Development for `/flo` — Epic #1269. Two independent modifiers:
 
-- **`-sd` / `--sdd`** — run the full **spec → plan → (review) → implement → verify** cycle. Opt-in (`sdd.default` defaults false). Implies verify.
+- **`-sd` / `--sdd`** — run the full **spec → plan → (review) → implement → verify** cycle. Opt-in *by built-in default* (`sdd.default` = false), but **a project can set `sdd.default: true` and turn it on for every run**. Implies verify.
 - **`-v` / `--verify`** — verify-before-done: a normal run plus the completion gate, no spec/plan front-half. **On by default** (`gates.verify_before_done` defaults true, #1294) — `-v` is explicit, `--no-verify` opts out for one run.
 
-Defaults seed from `moflo.yaml` (`sdd.default` = false, `gates.verify_before_done` = true); per-run flags and `--no-sdd` / `--no-verify` override. Both are orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`, so `--sdd -s -wt 42` runs the SDD cycle in a swarm inside a worktree.
+⚠ **Never infer whether SDD is on from these built-in defaults.** They are project-configurable, so the effective value is only knowable at run time. Resolve it as `SKILL.md` § "Resolved run modes" describes — the `[moflo] /flo run modes` line injected into context, or `flo sdd mode --args="$ARGUMENTS"`. Assuming `sdd=off` on a project with `sdd.default: true` silently skips the whole spec/plan cycle and is invisible to the user until the PR lands without a spec.
+
+Precedence: per-run flags and `--no-sdd` / `--no-verify` override `moflo.yaml`, which overrides the built-ins. Both are orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`, so `--sdd -s -wt 42` runs the SDD cycle in a swarm inside a worktree.
 
 The artifact model, paths, and CLI live in `src/cli/sdd/` (`flo sdd …`). The constitution layer (CLAUDE.md + `.claude/guidance/`) is referenced by every stage — never restated in a spec.
 

package/.claude/skills/perf-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: perf-audit
-description: Alias for /quicken. Ad-hoc performance audit — reveals N+1 queries, needless re-renders, missing caching, memory leaks, and redundant computation in your diff (or a named path), and prescribes the fix inline.
+description: Alias for /quicken — see that skill's description.
 arguments: "[path or area | --all]"
 ---
 

package/.claude/skills/test-gaps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-gaps
-description: Alias for /ward. Ad-hoc test-gap audit — reveals untested functions, uncovered edge cases, and missing error-handling/integration tests in your diff (or a named path), and conjures ready-to-paste test skeletons inline.
+description: Alias for /ward — see that skill's description.
 arguments: "[path or area | --all]"
 ---
 

package/bin/gate.cjs

@@ -104,6 +104,19 @@ function loadSddConfig() {
   return out;
 }
 
+// Parse the top-level `merge:` block from moflo.yaml (#1285). Block-scoped for
+// the same reason as loadSddConfig: a bare `auto:` key can appear under other
+// sections. Cross-platform: tolerates CRLF.
+function loadMergeConfig() {
+  var out = { auto: false };
+  var content = MOFLO_YAML;
+  if (!content) return out;
+  var block = content.match(/^merge:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m);
+  if (!block) return out;
+  if (/^\s*auto:\s*true\b/im.test(block[1])) out.auto = true;
+  return out;
+}
+
 // Read moflo.yaml exactly once per gate process (#1297 review): loadGateConfig
 // and loadSddConfig both parse it, and the gate fires on every Write/Edit — a
 // second read is wasted syscalls. Single readFileSync in try/catch (no existsSync
@@ -116,10 +129,18 @@ var MOFLO_YAML = readMofloYaml();
 
 var config = loadGateConfig();
 var sddConf = loadSddConfig();
+var mergeConf = loadMergeConfig();
 var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
 
+// Appended to every memory-first denial. Without it, a context audit of Claude
+// Code's denial telemetry reads moflo's gate enforcements as permission-setup
+// failures and "fixes" them with allow rules — which cannot override a hook
+// block at all (#1307 finding 5). Naming the gate makes the cause self-evident.
+var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule — allow-rules cannot override it.';
+var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
+
 // #1294 Finding 3 — reads/scans of EPHEMERAL files under the OS temp dir
 // (background-task output/transcripts, agent scratchpads) are transient tool
 // I/O and never carry indexable project knowledge, so they must not trip the
@@ -288,16 +309,71 @@ function detectFlMode(promptText) {
   return null;
 }
 
-// #1297 — arm the SDD implement gate from the user prompt. Only /fl or /flo runs
-// can arm it. Explicit -sd/--sdd wins; --no-sdd disarms; otherwise honor the
-// sdd.default config. `-sd` is a distinct token from `-s` (swarm): the `d` sits
-// on the word boundary so `-s\b` never matches `-sd`.
-function detectSddMode(promptText) {
+// Resolve the FULL set of /flo run modifiers from the prompt + moflo.yaml — the
+// single source of truth for both gate arming (#1297) and the authoritative
+// announcement emitted by prompt-reminder. Two consumers, one resolver: a second
+// implementation is exactly how `sdd.default: true` got silently ignored (the
+// skill's prompt carried `let sddMode = false` and the model executed the literal).
+//
+// Precedence per key: explicit --no-X > explicit -x/--X > moflo.yaml > built-in.
+// NOTE the differing built-in defaults: sdd is opt-IN (false), verify is opt-OUT
+// (true, #1294), merge is opt-IN (false, #1285).
+//
+// `-sd` is a distinct token from `-s` (swarm): the `d` sits on the word boundary
+// so `-s\b` never matches `-sd`.
+function resolveFloRun(promptText) {
   var p = promptText || '';
-  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return false;
-  if (/(?:^|\s)--no-sdd\b/.test(p)) return false;
-  if (/(?:^|\s)(?:-sd|--sdd)\b/.test(p)) return true;
-  return !!sddConf.default;
+  var out = { isFlo: false, workflow: 'full', sdd: false, verify: false, merge: false,
+              sddSrc: 'default', verifySrc: 'default', mergeSrc: 'default' };
+  if (!/^\s*\/(?:fl|flo)\b/i.test(p)) return out;
+  out.isFlo = true;
+
+  // Workflow mode — decides which modifiers are even applicable.
+  if (/(?:^|\s)(?:-wf|--workflow)\b/.test(p)) out.workflow = 'spell-engine';
+  else if (/(?:^|\s)(?:-r|--research)\b/.test(p)) out.workflow = 'research';
+  else if (/(?:^|\s)(?:-t|--ticket)\b/.test(p)) out.workflow = 'ticket';
+  var epicBranch = /(?:^|\s)--epic-branch\b/.test(p);
+
+  if (/(?:^|\s)--no-sdd\b/.test(p)) { out.sdd = false; out.sddSrc = 'flag'; }
+  else if (/(?:^|\s)(?:-sd|--sdd)\b/.test(p)) { out.sdd = true; out.sddSrc = 'flag'; }
+  else if (sddConf.default) { out.sdd = true; out.sddSrc = 'moflo.yaml sdd.default'; }
+
+  if (/(?:^|\s)--no-verify\b/.test(p)) { out.verify = false; out.verifySrc = 'flag'; }
+  else if (/(?:^|\s)(?:-v|--verify)\b/.test(p)) { out.verify = true; out.verifySrc = 'flag'; }
+  else if (!config.verify_before_done) { out.verify = false; out.verifySrc = 'moflo.yaml gates.verify_before_done'; }
+  else { out.verify = true; out.verifySrc = 'default'; }
+  // --sdd implies --verify: a spec/plan without an enforced verify step drifts.
+  if (out.sdd && !out.verify && out.verifySrc !== 'flag') out.verify = true;
+
+  if (/(?:^|\s)--no-merge\b/.test(p)) { out.merge = false; out.mergeSrc = 'flag'; }
+  else if (/(?:^|\s)(?:-m|--merge)\b/.test(p)) { out.merge = true; out.mergeSrc = 'flag'; }
+  else if (mergeConf.auto) { out.merge = true; out.mergeSrc = 'moflo.yaml merge.auto'; }
+
+  // Applicability: -t/-r never implement, so verify is a no-op there; -r produces
+  // no artifacts, so sdd is a no-op too (in -t the spec/plan goes INTO the ticket,
+  // so sdd stays on). Only a full non-epic-branch run opens a PR to merge.
+  // Re-attribute anything applicability turned off, so a false never carries the
+  // source of the value it no longer has. This whole change exists to stop modes
+  // being reported inaccurately — the attribution has to be honest too.
+  if (out.workflow === 'ticket' || out.workflow === 'research') {
+    if (out.verify) out.verifySrc = out.workflow + ' mode does not implement';
+    out.verify = false;
+  }
+  if (out.workflow === 'research' || out.workflow === 'spell-engine') {
+    if (out.sdd) out.sddSrc = out.workflow + ' mode produces no spec artifacts';
+    out.sdd = false;
+  }
+  if (out.workflow !== 'full' || epicBranch) {
+    if (out.merge) out.mergeSrc = epicBranch ? '--epic-branch owns merging' : out.workflow + ' mode opens no PR';
+    out.merge = false;
+  }
+  return out;
+}
+
+// #1297 — arm the SDD implement gate from the user prompt. Thin wrapper so the
+// arming decision and the announced decision can never disagree.
+function detectSddMode(promptText) {
+  return resolveFloRun(promptText).sdd;
 }
 
 // Resolve the absolute specs root the same way TS specsRoot does (#1294): split
@@ -644,7 +720,7 @@ switch (command) {
     var target = (process.env.TOOL_INPUT_pattern || '') + ' ' + (process.env.TOOL_INPUT_path || '');
     if (isEphemeralPath(process.env.TOOL_INPUT_path)) break;
     if (EXEMPT.some(function(p) { return target.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before exploring files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'check-before-read': {
@@ -657,7 +733,7 @@ switch (command) {
     if (isEphemeralPath(fp)) break;
     var isGuidance = fp.indexOf('.claude/guidance/') >= 0 || fp.indexOf('.claude\\guidance\\') >= 0;
     if (!isGuidance && EXEMPT.some(function(p) { return fp.indexOf(p) >= 0; })) break;
-    process.stderr.write('BLOCKED: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
+    process.stderr.write('BLOCKED [moflo memory_first gate]: Search memory before reading files. Use mcp__moflo__memory_search. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' + GATE_ORIGIN_NOTE + '\n' + GATE_DISABLE_NOTE + '\n');
     process.exit(2);
   }
   case 'record-task-created': {
@@ -706,11 +782,12 @@ switch (command) {
     // "Memory namespace hint: ..." sentence so the BLOCK message stays uniform.
     var hint = s2.lastNamespaceHint || classifyBashNamespaceHint(cmd) || '';
     process.stderr.write(
-      'BLOCKED: Search memory before reading files via Bash.\n' +
+      'BLOCKED [moflo memory_first gate]: Search memory before reading files via Bash.\n' +
       'Example: mcp__moflo__memory_search { query: "<topic>", namespace: "<one of: guidance | code-map | patterns | learnings | tests>" }\n' +
       (hint ? hint + '\n' : '') +
       'On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n' +
-      'Disable per-gate via moflo.yaml: gates: memory_first: false\n'
+      GATE_ORIGIN_NOTE + '\n' +
+      GATE_DISABLE_NOTE + '\n'
     );
     process.exit(2);
     break;
@@ -981,6 +1058,33 @@ switch (command) {
     applyPromptStateReset(s, prompt);
     s.interactionCount = (s.interactionCount || 0) + 1;
     writeState(s);
+    // Announce the resolved /flo run modifiers. The gate already parsed
+    // moflo.yaml in THIS process (fresh per prompt — a git pull or a mid-session
+    // yaml edit is picked up automatically, no cache to invalidate), so this
+    // costs no extra read. Emitting it is what closes the loop: the skill used
+    // to carry `let sddMode = false` as a literal and the model executed it,
+    // silently ignoring `sdd.default: true`. Only fires on /fl|/flo prompts.
+    var floRun = resolveFloRun(prompt);
+    if (floRun.isFlo) {
+      console.log(
+        '[moflo] /flo run modes (AUTHORITATIVE — use verbatim; do NOT re-derive from the skill defaults): ' +
+        'sdd=' + (floRun.sdd ? 'ON' : 'off') +
+        ' verify=' + (floRun.verify ? 'ON' : 'off') +
+        ' merge=' + (floRun.merge ? 'ON' : 'off') +
+        ' [workflow=' + floRun.workflow + ']'
+      );
+      // Spell out the surprising case: a project default the user did not type.
+      if (floRun.sdd && floRun.sddSrc !== 'flag') {
+        console.log(
+          '[moflo] sdd is ON via ' + floRun.sddSrc + ' — the spec→plan→implement→verify cycle is ' +
+          'MANDATORY this run. Author the spec before editing source (the sdd_gate blocks source ' +
+          'Write/Edit until a reviewed plan exists). One-off opt out: re-run with --no-sdd.'
+        );
+      }
+      if (floRun.merge && floRun.mergeSrc !== 'flag') {
+        console.log('[moflo] merge is ON via ' + floRun.mergeSrc + ' — the PR will be auto-merged. Opt out: --no-merge.');
+      }
+    }
     if (config.context_tracking) {
       var ic = s.interactionCount;
       if (ic > 30) console.log('Context: CRITICAL. Commit, store learnings, suggest new session.');