moflo 4.12.0 → 4.12.1

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,6 +129,7 @@ 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'];
@@ -288,16 +302,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
@@ -981,6 +1050,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/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/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,6 +129,7 @@ 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'];
@@ -288,16 +302,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
@@ -981,6 +1050,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/dist/src/cli/commands/sdd.js

@@ -16,12 +16,14 @@
  *   flo sdd path <slug> [spec|plan]  Print the artifact path (for skill shell-out)
  *   flo sdd embed <slug>             Print spec+plan as a PR-body block (#1297)
  *   flo sdd index                    Re-index specs into memory now (also runs at session start)
+ *   flo sdd mode --args "<flo args>" Resolve sdd/verify/merge for a /flo run as JSON
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
 import { findProjectRoot } from '../services/project-root.js';
+import { loadMofloConfig } from '../config/moflo-config.js';
 import { locateMofloRootPath } from '../services/moflo-require.js';
 import { artifactPath, assertReviewed, listSpecs, newArtifact, readArtifact, slugify, specExists, validateArtifact, writeArtifact, } from '../sdd/index.js';
 import { defaultPlanBody, defaultSpecBody } from '../sdd/templates.js';
@@ -226,6 +228,119 @@ function cmdList(ctx) {
     }
     return { success: true, data: specs };
 }
+/**
+ * Resolve the effective `/flo` run modifiers from an argument string + moflo.yaml
+ * and print them as JSON. This is the FALLBACK path for the authoritative
+ * announcement that `bin/gate.cjs prompt-reminder` normally injects on every
+ * `/flo` prompt — consumers with hooks disabled (or a gate.cjs predating this
+ * change) still get a deterministic answer by shelling out to this.
+ *
+ * Exists because the `/flo` skill used to carry `let sddMode = false` as a
+ * literal beside a comment saying "seed from moflo.yaml"; the model executed the
+ * literal and `sdd.default: true` was silently ignored. Config-derived run modes
+ * must be COMPUTED, never described in prose next to a contradicting default.
+ *
+ * Precedence per key: `--no-X` > `-x`/`--X` > moflo.yaml > built-in. Built-in
+ * defaults differ deliberately: sdd is opt-in (false), verify is opt-out (true,
+ * #1294), merge is opt-in (false, #1285).
+ *
+ * SYNC: mirrors `resolveFloRun` in bin/gate.cjs (and its copy in
+ * init/helpers-generator.ts). Any precedence change MUST land in all three.
+ */
+function cmdMode(ctx) {
+    // MUST be passed as `--args=<value>`, not `--args <value>`: the flag parser
+    // only consumes a following token as a value when it does not start with `-`,
+    // so `--args "-sd 42"` would silently degrade to `args=true` and resolve every
+    // run to the bare config default. The `=` form bypasses that lookahead.
+    // parseValue may coerce a bare numeric ("42") to a number — coerce back.
+    const flagArgs = ctx.flags?.args;
+    const raw = (typeof flagArgs === 'string' || typeof flagArgs === 'number')
+        ? String(flagArgs)
+        : (ctx.args ?? []).slice(1).join(' ');
+    // Tokenize on whitespace so `-sd` is matched as a whole token — it is NOT
+    // `-s` (swarm) + `d`.
+    const tokens = raw.trim().split(/\s+/).filter(Boolean);
+    const has = (...names) => names.some((n) => tokens.includes(n));
+    const cfg = loadMofloConfig(projectRoot(ctx));
+    let workflow = 'full';
+    if (has('-wf', '--workflow'))
+        workflow = 'spell-engine';
+    else if (has('-r', '--research'))
+        workflow = 'research';
+    else if (has('-t', '--ticket'))
+        workflow = 'ticket';
+    const epicBranch = has('--epic-branch');
+    let sdd = false;
+    let sddSrc = 'default';
+    if (has('--no-sdd')) {
+        sdd = false;
+        sddSrc = 'flag';
+    }
+    else if (has('-sd', '--sdd')) {
+        sdd = true;
+        sddSrc = 'flag';
+    }
+    else if (cfg.sdd.default) {
+        sdd = true;
+        sddSrc = 'moflo.yaml sdd.default';
+    }
+    let verify;
+    let verifySrc = 'default';
+    if (has('--no-verify')) {
+        verify = false;
+        verifySrc = 'flag';
+    }
+    else if (has('-v', '--verify')) {
+        verify = true;
+        verifySrc = 'flag';
+    }
+    else if (!cfg.gates.verify_before_done) {
+        verify = false;
+        verifySrc = 'moflo.yaml gates.verify_before_done';
+    }
+    else {
+        verify = true;
+    }
+    // --sdd implies --verify: a spec/plan without an enforced verify step drifts.
+    if (sdd && !verify && verifySrc !== 'flag')
+        verify = true;
+    let merge = false;
+    let mergeSrc = 'default';
+    if (has('--no-merge')) {
+        merge = false;
+        mergeSrc = 'flag';
+    }
+    else if (has('-m', '--merge')) {
+        merge = true;
+        mergeSrc = 'flag';
+    }
+    else if (cfg.merge.auto) {
+        merge = true;
+        mergeSrc = 'moflo.yaml merge.auto';
+    }
+    // Applicability: -t/-r never implement, so verify is a no-op there; -r and -wf
+    // produce no spec artifacts (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 — a false must never carry the
+    // source of the value it no longer has. SYNC: mirrors bin/gate.cjs.
+    if (workflow === 'ticket' || workflow === 'research') {
+        if (verify)
+            verifySrc = `${workflow} mode does not implement`;
+        verify = false;
+    }
+    if (workflow === 'research' || workflow === 'spell-engine') {
+        if (sdd)
+            sddSrc = `${workflow} mode produces no spec artifacts`;
+        sdd = false;
+    }
+    if (workflow !== 'full' || epicBranch) {
+        if (merge)
+            mergeSrc = epicBranch ? '--epic-branch owns merging' : `${workflow} mode opens no PR`;
+        merge = false;
+    }
+    console.log(JSON.stringify({ workflow, sdd, verify, merge, sddSrc, verifySrc, mergeSrc }, null, 2));
+    return { success: true };
+}
 function cmdPath(ctx) {
     const root = projectRoot(ctx);
     const slug = slugify(ctx.args[1] || '');
@@ -294,7 +409,8 @@ Spec-Driven Development artifacts (.moflo/specs/<slug>/{spec,plan}.md):
   list                     List every spec slug
   path <slug> [spec|plan]  Print the artifact path
   embed <slug>             Print spec+plan as a collapsible block for the PR body
-  index                    Re-index specs into memory now`;
+  index                    Re-index specs into memory now
+  mode --args "<flo args>" Resolve sdd/verify/merge for a /flo run as JSON (moflo.yaml + flags)`;
 const sddCommand = {
     name: 'sdd',
     description: 'Spec-Driven Development artifacts (spec → plan → implement → verify)',
@@ -322,6 +438,8 @@ const sddCommand = {
                 return cmdStatus(ctx);
             case 'list':
                 return cmdList(ctx);
+            case 'mode':
+                return cmdMode(ctx);
             case 'path':
                 return cmdPath(ctx);
             case 'embed':

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

@@ -293,6 +293,18 @@ function loadSddConfig() {
   return out;
 }
 
+// #1285 — parse the top-level merge: block. Block-scoped like loadSddConfig.
+// SYNC: mirrors bin/gate.cjs loadMergeConfig.
+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;
+}
+
 // #1297 — read moflo.yaml once (both loaders parse it; gate fires on every
 // Write/Edit). SYNC: mirrors bin/gate.cjs readMofloYaml.
 function readMofloYaml() {
@@ -303,6 +315,7 @@ 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'];
@@ -388,13 +401,58 @@ function detectFlMode(promptText) {
   return null;
 }
 
-// #1297 — arm the SDD implement gate from a /flo prompt. SYNC: mirrors bin/gate.cjs.
-function detectSddMode(promptText) {
+// Resolve ALL /flo run modifiers from the prompt + moflo.yaml. Single source of
+// truth for gate arming AND the authoritative announcement below — a second
+// implementation is how sdd.default got silently ignored. Precedence per key:
+// --no-X > -x/--X > moflo.yaml > built-in (sdd opt-in, verify opt-out, merge
+// opt-in). SYNC: mirrors bin/gate.cjs resolveFloRun.
+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;
+
+  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'; }
+  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'; }
+
+  // Re-attribute anything applicability turned off — a false must never carry
+  // the source of the value it no longer has. SYNC: mirrors bin/gate.cjs.
+  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 a /flo prompt. Thin wrapper so the
+// armed decision and the announced decision can never disagree.
+function detectSddMode(promptText) {
+  return resolveFloRun(promptText).sdd;
 }
 
 // SDD specs-root resolution + artifact helpers for check-before-implement.
@@ -779,6 +837,30 @@ switch (command) {
     applyPromptStateReset(s, prompt);
     s.interactionCount = (s.interactionCount || 0) + 1;
     writeState(s);
+    // Announce the resolved /flo run modifiers. moflo.yaml was already parsed in
+    // THIS process (fresh per prompt — a git pull or mid-session yaml edit is
+    // picked up automatically, no cache to invalidate), so this costs no extra
+    // read. SYNC: mirrors bin/gate.cjs prompt-reminder.
+    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 + ']'
+      );
+      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/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.12.0';
+export const VERSION = '4.12.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.12.0",
+  "version": "4.12.1",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -95,7 +95,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.11.10-rc.10",
+    "moflo": "^4.12.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"