moflo 4.12.4 → 4.12.6

package/.claude/helpers/pr-create-command.cjs

@@ -0,0 +1,440 @@
+'use strict';
+
+/**
+ * Does this Bash command actually invoke `gh pr create`?
+ *
+ * Issue #1410. The gates in `gate.cjs` (`check-before-pr`, `check-before-done`)
+ * used to answer this with a single regex applied to raw command text:
+ *
+ *   /(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/
+ *
+ * That was wrong in both directions at once. It MISSED shapes people routinely
+ * type — a newline-separated multi-line command, `cat body.md | gh pr create
+ * --body-file -`, `( gh pr create )` — each of which opened a PR with every gate
+ * silently skipped. And it FIRED on commands that merely quote the literal — a
+ * `git commit -m "...gh pr create..."`, a `node -e '...'` probe, a heredoc body —
+ * blocking work that has nothing to do with opening a PR.
+ *
+ * One cause, both symptoms: a regex over raw text cannot tell a command from a
+ * string that quotes one. That is why the obvious repair (widen the separator
+ * set to include newline and `|`) makes the over-match strictly worse — every
+ * heredoc body line starting with the literal would become a match.
+ *
+ * So: two passes.
+ *
+ *   1. `sanitizeShellData` blanks the regions that are data rather than command
+ *      — comments, heredoc bodies, all quote flavours, escapes — replacing them
+ *      with spaces and PRESERVING LENGTH, so nothing outside a blanked region
+ *      shifts or merges.
+ *   2. `isPrCreateCommand` searches the sanitised text for the literal, then
+ *      walks BACKWARDS from each hit to confirm it starts a command.
+ *
+ * Four traps, three of which are silent BYPASSES (the gate stops blocking with
+ * no signal at all), are handled deliberately below and are marked `TRAP` at
+ * their sites:
+ *
+ *   - `<<<` is a herestring, not a heredoc. Reading it as a heredoc opener
+ *     means the delimiter is never found, the "body" blanks the rest of the
+ *     input, and a real invocation on the next line is swallowed.
+ *   - Heredoc headers are matched with a STICKY regex, never against a
+ *     fixed-size `slice(i, i + N)` window. A window truncates a bare delimiter
+ *     longer than it, registers the truncated prefix as the delimiter, and the
+ *     real terminator line then never matches — body blanks to EOF.
+ *   - `\` + newline is a line continuation, not a separator: the words after it
+ *     are arguments, and heredoc bodies queued on that line do not start there.
+ *   - Left-context stays OUT of the regex. `(?:^|[\n;&|(){}])\s*(?:NAME=val\s+)*gh…`
+ *     is quadratic on sanitised input (long runs of spaces that `\s*` consumes,
+ *     fails on, and backtracks through at every position). Searching for the
+ *     literal first and walking back by hand is flat.
+ *
+ * Mirrored verbatim into `.claude/helpers/pr-create-command.cjs` — the dogfood
+ * parity guard enforces byte-identity. Dependency-free CommonJS, `node:`
+ * builtins only (it uses none), so it loads from either location.
+ */
+
+/**
+ * Chars that can immediately precede a command word. `<` and `>` are absent on
+ * purpose: `> out.txt gh pr create` is a redirect target followed by arguments
+ * in the shapes we care about, not a fresh command.
+ *
+ * The backtick is present — and is deliberately NOT blanked as data the way
+ * quotes are. #1410's write-up lists backticks with the quote flavours, but an
+ * UNQUOTED backtick is command substitution: blanking it would make
+ * `` `gh pr create` `` stop blocking, i.e. exactly the silent-bypass class the
+ * issue is about. Backticks inside `"…"` are still blanked with the rest of the
+ * quoted run, which is where the over-match risk actually lives.
+ */
+var SEPARATOR_CHARS = '\n;&|(){}`';
+
+/**
+ * Words that may sit between a separator and the command without changing the
+ * fact that a command follows. Kept short and literal — anything not listed
+ * (e.g. `echo`) correctly makes the walk fail, because its following words are
+ * arguments, not a command.
+ */
+var PREFIX_WORDS = ['!', 'then', 'else', 'elif', 'do', 'time', 'command', 'builtin', 'exec', 'env', 'nohup', 'xargs', 'sudo'];
+
+/** `NAME=value` prefix, e.g. `GH_TOKEN=x gh pr create`. Bounded to one word. */
+var ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=\S*$/;
+
+/**
+ * Heredoc header, matched STICKY at a known index. Alternatives, in order:
+ * `'DELIM'`, `"DELIM"`, `$'DELIM'`, bare DELIM. The quoted forms come first so
+ * a quoted delimiter is never mis-read as a bare one starting with a quote.
+ */
+var HEREDOC_RE = /<<(-?)[ \t]*(?:'([^'\n]*)'|"([^"\n]*)"|\$'([^'\n]*)'|([^\s;&|<>()'"`]+))/y;
+
+/** The invocation itself. No left-context — see the fourth trap above. */
+var PR_CREATE_RE = /gh\s+pr\s+create\b/g;
+
+/**
+ * Pre-sanitise reject: `gh` as a whole token. A bare `indexOf('gh')` is far too
+ * weak — "gh" is a common English digraph, so `highlight`, `github`, `though`,
+ * and `flight` all fall through to the full two-pass scan on a hook that runs as
+ * a fresh process on every Bash call, at both gate call sites.
+ *
+ * Safe against false negatives: `PR_CREATE_RE` requires whitespace after `gh`,
+ * and sanitising only ever replaces characters with spaces — it never turns a
+ * non-word character into a word one — so a `gh` that survives to match here
+ * cannot have had a word character in front of it in the raw text.
+ *
+ * No quantifiers, so the scan is linear with no backtracking.
+ */
+var GH_TOKEN_RE = /(?:^|[^A-Za-z0-9_])gh(?![A-Za-z0-9_])/;
+
+/** Horizontal whitespace only. `\n` is a separator and must not be skipped as blank. */
+function isBlank(ch) {
+  return ch === ' ' || ch === '\t' || ch === '\r';
+}
+
+/** A `#` opens a comment only when it begins a word. */
+function startsWord(cmd, i) {
+  if (i === 0) return true;
+  var prev = cmd.charAt(i - 1);
+  return isBlank(prev) || SEPARATOR_CHARS.indexOf(prev) !== -1;
+}
+
+/** Index of the first character of the whitespace/separator-delimited token containing `from`. */
+function tokenStartAt(s, from) {
+  var k = from;
+  while (k > 0 && !isBlank(s.charAt(k - 1)) && SEPARATOR_CHARS.indexOf(s.charAt(k - 1)) === -1) k--;
+  return k;
+}
+
+/**
+ * How deep `$(…)` inside `"…"` inside `$(…)` is followed before giving up and
+ * leaving the region blanked. Nothing real nests anywhere near this; the cap
+ * exists so a pathological input cannot recurse into a stack overflow.
+ */
+var MAX_SUBSTITUTION_DEPTH = 8;
+
+/**
+ * Replace every data region with spaces, preserving length. What remains is
+ * command text — the only thing safe to match a command against.
+ *
+ * Exported for tests: asserting on the sanitised string is how the blanking
+ * rules are pinned independently of the matcher on top of them.
+ *
+ * @param {string} cmd
+ * @param {number} [depth] internal — substitution recursion depth
+ * @returns {string} same length as `cmd`
+ */
+function sanitizeShellData(cmd, depth) {
+  var n = cmd.length;
+  var out = cmd.split('');
+  var pending = [];
+  var level = depth || 0;
+  var i = 0;
+
+  function blank(from, to) {
+    var stop = to > n ? n : to;
+    for (var k = from; k < stop; k++) out[k] = ' ';
+  }
+
+  /** Copy `raw`'s chars back into `out` at `from` — the inverse of `blank`. */
+  function restore(from, raw) {
+    for (var k = 0; k < raw.length; k++) out[from + k] = raw.charAt(k);
+  }
+
+  /** Scan a quoted run from `i` to its closing `close`, honouring `\` escapes if asked. */
+  function closingIndex(from, close, escapes) {
+    var j = from;
+    while (j < n) {
+      var ch = cmd.charAt(j);
+      if (escapes && ch === '\\') { j += 2; continue; }
+      if (ch === close) return j + 1;
+      j++;
+    }
+    return n;
+  }
+
+  /**
+   * Index of the `)` closing the `(` at `openIdx`, or -1 before `limit`.
+   * Skips quoted runs so a `)` inside a string doesn't close the substitution.
+   */
+  function matchingParen(openIdx, limit) {
+    var d = 0;
+    var k = openIdx;
+    while (k < limit) {
+      var ch = cmd.charAt(k);
+      if (ch === '\\') { k += 2; continue; }
+      if (ch === "'") { k = closingIndex(k + 1, "'", false); continue; }
+      if (ch === '"') { k = doubleQuoteEnd(k + 1); continue; }
+      if (ch === '(') d++;
+      else if (ch === ')') { d--; if (d === 0) return k; }
+      k++;
+    }
+    return -1;
+  }
+
+  /**
+   * Index just past the `"` that closes the run opened before `from`.
+   *
+   * Not `closingIndex(from, '"', true)`: quoting RESTARTS inside a command
+   * substitution, so in `"a $(cmd "b") c"` the quotes around `b` belong to the
+   * substitution and do not end the outer run. Scanning for the next unescaped
+   * `"` would cut the run short at `b`'s opening quote and leave the second half
+   * — including anything the substitution runs — mis-parsed.
+   *
+   * Mutually recursive with `matchingParen`; both only ever move forward, so the
+   * pair terminates.
+   */
+  function doubleQuoteEnd(from) {
+    var j = from;
+    while (j < n) {
+      var ch = cmd.charAt(j);
+      if (ch === '\\') { j += 2; continue; }
+      if (ch === '"') return j + 1;
+      if (ch === '$' && cmd.charAt(j + 1) === '(') {
+        var close = matchingParen(j + 1, n);
+        if (close !== -1) { j = close + 1; continue; }
+        j += 2;
+        continue;
+      }
+      if (ch === '`') {
+        var bt = cmd.indexOf('`', j + 1);
+        if (bt !== -1) { j = bt + 1; continue; }
+      }
+      j++;
+    }
+    return n;
+  }
+
+  /**
+   * A double-quoted run and an unquoted-delimiter heredoc body are data —
+   * EXCEPT for the command substitutions inside them, which the shell still
+   * runs. Blanking those wholesale would leave `echo "$(gh pr create)"` and its
+   * heredoc equivalent as silent bypasses, so restore each `$(…)` / `` `…` ``
+   * region over the already-blanked range: its delimiters (both of which the
+   * backwards walk reads as separators) plus its body, sanitised in its own
+   * right so quoting INSIDE the substitution still applies.
+   *
+   * `'…'`, `$'…'` and quoted-delimiter heredocs (`<<'EOF'`) are left blanked —
+   * the shell does not expand those, so there is nothing to restore.
+   */
+  function restoreSubstitutions(from, to) {
+    if (level >= MAX_SUBSTITUTION_DEPTH) return;
+    var k = from;
+    while (k < to) {
+      var ch = cmd.charAt(k);
+      if (ch === '\\') { k += 2; continue; }
+      var openLen = 0;
+      var close = -1;
+      if (ch === '$' && cmd.charAt(k + 1) === '(') {
+        openLen = 2;
+        close = matchingParen(k + 1, to);
+      } else if (ch === '`') {
+        openLen = 1;
+        close = cmd.indexOf('`', k + 1);
+        if (close >= to) close = -1;
+      }
+      if (close === -1) { k++; continue; }
+      restore(k, cmd.slice(k, k + openLen));
+      restore(close, cmd.charAt(close));
+      restore(k + openLen, sanitizeShellData(cmd.slice(k + openLen, close), level + 1));
+      k = close + 1;
+    }
+  }
+
+  /**
+   * Blank one heredoc body, starting at `start` (the first char of the line
+   * after the newline that ended the header's logical line).
+   *
+   * Blanks each body line's content and the terminator line's content, leaving
+   * every newline in place — so the text after the heredoc still begins after a
+   * real separator, and offsets outside the body are untouched.
+   *
+   * Returns the index to resume scanning from. An unterminated heredoc blanks to
+   * end of input, which is what the shell does with it too.
+   */
+  function blankHeredocBody(start, delim, stripTabs, expands) {
+    var pos = start;
+    while (pos < n) {
+      var eol = cmd.indexOf('\n', pos);
+      var lineEnd = eol === -1 ? n : eol;
+      var line = cmd.slice(pos, lineEnd);
+      // CRLF: the terminator is the line's content, not its line ending.
+      if (line.charAt(line.length - 1) === '\r') line = line.slice(0, -1);
+      var candidate = stripTabs ? line.replace(/^\t+/, '') : line;
+      blank(pos, lineEnd);
+      if (expands) restoreSubstitutions(pos, lineEnd);
+      if (candidate === delim) return eol === -1 ? n : eol + 1;
+      if (eol === -1) return n;
+      pos = eol + 1;
+    }
+    return n;
+  }
+
+  while (i < n) {
+    var c = cmd.charAt(i);
+
+    // TRAP: `\` + newline is a line continuation. Blanking BOTH characters keeps
+    // the logical line going, so the words after it stay arguments — otherwise
+    // `cat <<EOF \` + newline + `gh pr create` reads as a command when the shell
+    // reads it as arguments to `cat`. Any other `\x` is an escape; blanking the
+    // pair likewise stops `\;` and friends from reading as separators.
+    if (c === '\\') {
+      blank(i, i + 2);
+      i += 2;
+      continue;
+    }
+
+    if (c === '#' && startsWord(cmd, i)) {
+      var eol = cmd.indexOf('\n', i);
+      if (eol === -1) eol = n;
+      blank(i, eol);
+      i = eol;
+      continue;
+    }
+
+    if (c === '<' && cmd.charAt(i + 1) === '<') {
+      // TRAP: `<<<` is a herestring. Skip the operator — its word is handled by
+      // the ordinary quote/plain-text rules below.
+      if (cmd.charAt(i + 2) === '<') { i += 3; continue; }
+      // TRAP: sticky match at `i`, no window, no substring copy.
+      HEREDOC_RE.lastIndex = i;
+      var h = HEREDOC_RE.exec(cmd);
+      if (h) {
+        var delim = h[2] !== undefined ? h[2] : h[3] !== undefined ? h[3] : h[4] !== undefined ? h[4] : h[5];
+        // A BARE delimiter (`<<EOF`) expands `$(…)` in the body; any quoted form
+        // (`<<'EOF'`, `<<"EOF"`, `<<$'EOF'`) suppresses expansion entirely.
+        pending.push({ delim: delim, stripTabs: h[1] === '-', expands: h[5] !== undefined });
+        blank(i, i + h[0].length);
+        i += h[0].length;
+        continue;
+      }
+      // Not a header we recognise (`<< ;`, `<<` at end of input) — treat as text.
+      i += 2;
+      continue;
+    }
+
+    // `$'...'` processes `\` escapes; plain `'...'` does not.
+    if (c === '$' && cmd.charAt(i + 1) === "'") {
+      var ansiEnd = closingIndex(i + 2, "'", true);
+      blank(i, ansiEnd);
+      i = ansiEnd;
+      continue;
+    }
+
+    if (c === "'") {
+      var sqEnd = closingIndex(i + 1, "'", false);
+      blank(i, sqEnd);
+      i = sqEnd;
+      continue;
+    }
+
+    if (c === '"') {
+      var dqEnd = doubleQuoteEnd(i + 1);
+      blank(i, dqEnd);
+      // Substitutions inside the run still execute — see restoreSubstitutions.
+      restoreSubstitutions(i + 1, dqEnd - 1);
+      i = dqEnd;
+      continue;
+    }
+
+    if (c === '\n') {
+      i++;
+      // Bodies for every heredoc announced on the logical line just ended, in
+      // the order they were announced (`cat <<A <<B` reads A's body then B's).
+      while (pending.length > 0) {
+        var hd = pending.shift();
+        i = blankHeredocBody(i, hd.delim, hd.stripTabs, hd.expands);
+      }
+      continue;
+    }
+
+    i++;
+  }
+
+  return out.join('');
+}
+
+/**
+ * Does the token at `idx` in sanitised text `s` begin a command? True when what
+ * precedes it is the start of input, a separator, or a run of `NAME=value` /
+ * command-prefix words that itself bottoms out at one of those.
+ */
+function startsCommand(s, idx) {
+  // The hit must be the whole command word. `PR_CREATE_RE` carries no leading
+  // `\b`, so it can land mid-token — and the backwards walk below would then
+  // read a TRUNCATED prefix as a command prefix: `dogh pr create` yields `do`,
+  // which is in PREFIX_WORDS, and `FOO=bargh pr create` yields `FOO=bar`, which
+  // matches ASSIGNMENT_RE. Both are one unrelated token; both used to over-match.
+  //
+  // A leading `\b` would not fix it on its own — `\b` admits `=`, so the command
+  // in `FOO=gh pr create` (which is `pr`, not `gh`) would still walk back over
+  // `FOO=` and report a command start.
+  //
+  // Checking the whole token rather than just the character before it also keeps
+  // an invocation BY PATH working: `/usr/bin/gh pr create`, `./gh pr create`, and
+  // on Windows `C:/tools/gh` or `/c/tools/gh` — the forms that are valid command
+  // words for the shell the Bash tool runs.
+  //
+  // Only `/` is accepted as the separator, deliberately. A `\` is an ESCAPE here
+  // and is blanked in pass 1, so it can never reach this token; accepting it too
+  // would be unreachable code. The cost is that a backslash-escaped invocation
+  // (`C:\tools\gh`, or `\gh`) is not recognised — a miss, not an over-block, and
+  // the same miss the pre-#1410 regex had. Blanking the escape is what makes
+  // `echo a\; gh pr create` correctly NOT read as a command, which is worth more.
+  var tokenStart = tokenStartAt(s, idx);
+  var token = s.slice(tokenStart, idx + 2);
+  if (token !== 'gh' && !/\/gh$/.test(token)) return false;
+
+  var i = tokenStart;
+  for (;;) {
+    while (i > 0 && isBlank(s.charAt(i - 1))) i--;
+    if (i === 0) return true;
+    if (SEPARATOR_CHARS.indexOf(s.charAt(i - 1)) !== -1) return true;
+    var end = i;
+    i = tokenStartAt(s, i);
+    if (i === end) return false;
+    var word = s.slice(i, end);
+    if (!ASSIGNMENT_RE.test(word) && PREFIX_WORDS.indexOf(word) === -1) return false;
+  }
+}
+
+/**
+ * True when `cmd` invokes `gh pr create` as a command — not when it merely
+ * contains those words inside a string, comment, or heredoc body.
+ *
+ * @param {string} cmd raw Bash command text (Claude Code's `tool_input.command`)
+ * @returns {boolean}
+ */
+function isPrCreateCommand(cmd) {
+  // Fast reject before sanitising. These gates run on EVERY Bash call, and a
+  // large non-`gh` command would otherwise pay the full two-pass cost. `indexOf`
+  // first because it is the cheapest possible screen; the token check then
+  // discards the digraph false positives (`highlight`, `github`, `though`) that
+  // `indexOf` alone lets through.
+  if (typeof cmd !== 'string' || cmd.indexOf('gh') === -1) return false;
+  if (!GH_TOKEN_RE.test(cmd)) return false;
+  var s = sanitizeShellData(cmd);
+  PR_CREATE_RE.lastIndex = 0;
+  var m;
+  while ((m = PR_CREATE_RE.exec(s)) !== null) {
+    if (startsCommand(s, m.index)) return true;
+  }
+  return false;
+}
+
+module.exports = { isPrCreateCommand: isPrCreateCommand, sanitizeShellData: sanitizeShellData };

package/.claude/skills/eldar/SKILL.md

@@ -121,7 +121,7 @@ mcp__moflo__memory_stats — { namespace: "learnings" }
 
 Flag empty `learnings` as `info` (project hasn't accumulated decisions yet — fine for new projects). Flag empty `guidance` as `warn` (no indexed guidance means semantic search is degraded).
 
-**Legacy `doc-*` residue (#1053 S4)** — moflo retired whole-document indexing in favor of chunk-only RAG. The `purge-doc-entries` migration runs on session-start; if any `doc-*` rows linger, the migration didn't fire (ran with no DB, errored, or the install is below the migration's introduction).
+**Legacy `doc-*` residue** — moflo retired whole-document indexing in favor of chunk-only RAG. The `purge-doc-entries` migration runs on session-start; if any `doc-*` rows linger, the migration didn't fire (ran with no DB, errored, or the install is below the migration's introduction).
 
 ```
 mcp__moflo__memory_search — { query: "doc-", namespace: "guidance", threshold: 0, limit: 5 }

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

@@ -62,19 +62,19 @@ Under `--sdd` (or any run that authors or consults a spec), add these **spec-tar
 
 Worktree isolation is orthogonal to every other flag: it changes *where* the branch is created and the work happens, not *what* runs. All other arguments (mode, execution style, issue/title) apply unchanged. Ignored (with a one-line note) when `--epic-branch` is set — the epic orchestrator owns branch/worktree layout — and in `-r`/`--research` and `-t`/`--ticket` modes, which never touch a branch.
 
-## SDD & verification (Epic #1269)
+## SDD & verification
 
 Two **independent** modifiers, orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`. Verify is deliberately separable from SDD — you can get the completion gate without the spec ceremony.
 
 | Flag | Long | Effect |
 |------|------|--------|
 | `-sd` | `--sdd` | Run the full **spec → plan → (review) → implement → verify** cycle. Short is `-sd`, **not** `-s` (swarm) — follows the two-letter convention (`-wf`, `-wt`). Implies `--verify`. |
-| `-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`. |
+| `-v` | `--verify` | **Verify-before-done** — a normal run plus the `/verify` skill (the completion gate), no spec/plan front-half. **On by default** — 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` (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`.
+Defaults seed from `moflo.yaml` — `sdd.default` (built-in **off**) and `gates.verify_before_done` (built-in **on**). 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)
+## Auto-merge
 
 | Flag | Long | Effect |
 |------|------|--------|
@@ -164,7 +164,7 @@ let epicBranch = null;
 let issueNumber = null;
 let titleWords = [];
 
-// SDD / verify / merge modifiers (Epic #1269, #1294, #1285) — DO NOT resolve
+// SDD / verify / merge modifiers — 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.
@@ -230,7 +230,7 @@ if (useWorktree && (epicBranch || workflowMode !== "full")) {
 
 // SDD/verify are implementation-time modifiers. -t (ticket) and -r (research)
 // never implement, so verify is a no-op there — clear it. Verify is on by
-// default now (#1294), so only surface the "ignored" note when the user
+// default now, so only surface the "ignored" note when the user
 // EXPLICITLY passed -v/--verify — otherwise clearing the default is silent.
 // --sdd in -t writes the spec/plan INTO the ticket (see ./sdd.md); in -r ignored.
 if (workflowMode === "ticket" || workflowMode === "research") {

package/.claude/skills/fl/execution-modes.md

@@ -6,12 +6,12 @@ The SDD/verify modifiers (`-sd`/`--sdd`, `-v`/`--verify` — see `./sdd.md`) are
 
 ## SWARM mode (`-s`, `--swarm`)
 
-> **MANDATORY when `-s` is passed.** Your first Execute-phase action MUST be `mcp__moflo__swarm_init`, followed by `mcp__moflo__agent_spawn` for each role. Spawning subagents via `Agent` (or `Task`) without first registering the swarm is a violation of issue #952. The `Agent` PreToolUse gate will BLOCK the call until `swarm_init` runs. Even when you also use `Agent` for parallelism, the moflo swarm IS the registration surface — call it first. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
+> **MANDATORY when `-s` is passed.** Your first Execute-phase action MUST be `mcp__moflo__swarm_init`, followed by `mcp__moflo__agent_spawn` for each role. Spawning subagents via `Agent` (or `Task`) without first registering the swarm is a violation of the swarm-registration contract. The `Agent` PreToolUse gate will BLOCK the call until `swarm_init` runs. Even when you also use `Agent` for parallelism, the moflo swarm IS the registration surface — call it first. See CLAUDE.md "⛔ Protected functionality — swarm + hive-mind".
 
 > **`-s` is the user's request for agents.** An ambient "don't call the Agent
 > tool unless the user requested it" is satisfied by the flag — dispatch.
 > `swarm_init`/`agent_spawn` are MCP tools, so a suppressed run still registers a
-> swarm and passes the #952 gate while dispatching nobody. If you cannot spawn
+> swarm and passes the registration gate while dispatching nobody. If you cannot spawn
 > `Agent`, say so and stop.
 
 Swarm mode coordinates agents through the moflo swarm coordinator, then spawns workers via the `Agent` tool.
@@ -79,4 +79,4 @@ Single Claude execution without spawning sub-agents.
 
 ## Why these are MANDATORY
 
-Swarm and hive-mind are headline moflo product surface (CLAUDE.md "⛔ Protected functionality"). When the user explicitly opts in via `-s`/`-h`, the protected MCP surface MUST be exercised — falling back to "Claude-native parallelism" via `Agent` tool calls without coordinator registration is the failure mode that prompted issue #952. The PreToolUse gate enforces this; opt-out is `gates.swarm_invocation_gate: false` in `moflo.yaml`.
+Swarm and hive-mind are headline moflo product surface (CLAUDE.md "⛔ Protected functionality"). When the user explicitly opts in via `-s`/`-h`, the protected MCP surface MUST be exercised — falling back to "Claude-native parallelism" via `Agent` tool calls without coordinator registration is the failure mode this rule exists to prevent. The PreToolUse gate enforces this; opt-out is `gates.swarm_invocation_gate: false` in `moflo.yaml`.

package/.claude/skills/fl/phases.md

@@ -4,7 +4,7 @@ Phase-by-phase notes for the full `/flo <issue>` run. Phase 2 (Ticket) lives in
 
 ## Phase 0: Record run start (Flo Runs dashboard)
 
-Before research, open a run record so the Luminarium "Flo Runs" tab shows this run live and after the next session restart (#968), and so Phase 5.5 can price it. Skip this phase ONLY when `--epic-branch` is set — the epic orchestrator owns the parent record and the per-story spell engine writes its own row.
+Before research, open a run record so the Luminarium "Flo Runs" tab shows this run live and after the next session restart, and so Phase 5.5 can price it. Skip this phase ONLY when `--epic-branch` is set — the epic orchestrator owns the parent record and the per-story spell engine writes its own row.
 
 One command. It builds the record, derives the run id, and picks up the session id `gate.cjs` stamped on this prompt:
 
@@ -20,7 +20,7 @@ Flag the mode when it isn't a plain ticket run: `--research` (`-r`), `--new-tick
 
 `sessionId: null` means no session id was stamped (the gate has not seen a prompt yet, or you are outside Claude Code). The run still records; only its token cost will be unmeasurable.
 
-Do **not** hand-write a `memory_store` call for this. The record shape lives in `storeFloRunRecord` (`src/cli/services/daemon-dashboard.ts`) and `flo runs start` is its only caller — #1333 replaced a copy of the schema that lived here in prose, which produced exactly one record across the whole retained corpus because it depended on remembering to perform it.
+Do **not** hand-write a `memory_store` call for this. The record shape lives in `storeFloRunRecord` (`src/cli/services/daemon-dashboard.ts`) and `flo runs start` is its only caller — it replaced a copy of the schema that once lived here in prose, which produced exactly one record across the whole retained corpus because it depended on remembering to perform it.
 
 The session-start launcher retains the most recent ~200 tasklist rows, so this record outlives the session and renders in the Flo Runs tab on subsequent restarts.
 
@@ -63,7 +63,7 @@ flo memory search --query "<domain keywords>" --namespace guidance
 Or via MCP: `mcp__moflo__memory_search`.
 
 ### 1.4 Reach guidance via memory (only if memory was thin)
-If the §1.3 search above (the memory-first step named `SKILL.md` Step 0) returned fewer than three relevant results, widen the query — **still through `mcp__moflo__memory_search` (namespace `guidance`)**, not a direct `Read` of `.claude/guidance/*.md`. Guidance docs are indexed; search returns the relevant chunk, and `mcp__moflo__memory_get_neighbors` traverses adjacent context far more cheaply than reading the whole doc (this is the #1292 fix — don't bulk-read `.claude/guidance/moflo-sdd.md` et al.). Angle the query by change type:
+If the §1.3 search above (the memory-first step named `SKILL.md` Step 0) returned fewer than three relevant results, widen the query — **still through `mcp__moflo__memory_search` (namespace `guidance`)**, not a direct `Read` of `.claude/guidance/*.md`. Guidance docs are indexed; search returns the relevant chunk, and `mcp__moflo__memory_get_neighbors` traverses adjacent context far more cheaply than reading the whole doc (don't bulk-read `.claude/guidance/moflo-sdd.md` et al.). Angle the query by change type:
 - Bug → testing patterns, error handling
 - Feature → domain model, architecture
 - UI → frontend patterns, components
@@ -165,13 +165,13 @@ Closes #<issue-number>"
 ```
 
 **No attribution trailer.** Do not add `Co-Authored-By:`, `Generated with …`, or any
-other tool-attribution line to commits or PR bodies (#1398). This is the consumer's
+other tool-attribution line to commits or PR bodies. This is the consumer's
 repository and their git history is permanent — moflo does not sign their commits.
 
 ### 5.1b Verify-before-done (default; skipped only with `--no-verify`)
 **Delegate to the `/verify` skill** — `Skill({ skill: "verify" })`, passing the issue number or spec slug. That skill owns the mechanics (locate acceptance criteria → reuse Phase 4's already-green tests, no double verify → map each criterion → run only uncovered checks → record the outcome). Don't restate them here or verify in prose — *invoking* `/verify` is what records the run and satisfies the `check-before-done` gate.
 
-**When it runs:** by default (`verify_before_done` now defaults true, #1294) and always under `--sdd`; `--no-verify` skips it for one run. See `./sdd.md` for triggers and `.claude/skills/verify/SKILL.md` for how verification is performed.
+**When it runs:** by default (`verify_before_done` now defaults true) and always under `--sdd`; `--no-verify` skips it for one run. See `./sdd.md` for triggers and `.claude/skills/verify/SKILL.md` for how verification is performed.
 
 ### 5.2 Store learnings
 Before opening the PR, call `mcp__moflo__memory_store` with what was learned. The `check-before-pr` gate blocks `gh pr create` until this has run.
@@ -208,7 +208,7 @@ gh pr create --title "type(scope): description" --body "## Summary
 Closes #<issue-number>"
 ```
 
-**Under `--sdd` (#1297):** when `sdd.embed_in_pr` is true (default), append the spec+plan to the PR body so the reasoning is reviewable in the PR even when specs stay local/gitignored. Run `flo sdd embed <slug>`, read its printed output from the tool result, and paste it as literal text at the end of the PR body — do **not** use shell command substitution (`$(...)`) or heredoc/`printf`, none of which are portable (Rule #1). The robust path on every OS: write the full body (summary + embed block) to a file with the Write tool, then `gh pr create --body-file <path>`. See `./sdd.md` step 7.
+**Under `--sdd`:** when `sdd.embed_in_pr` is true (default), append the spec+plan to the PR body so the reasoning is reviewable in the PR even when specs stay local/gitignored. Run `flo sdd embed <slug>`, read its printed output from the tool result, and paste it as literal text at the end of the PR body — do **not** use shell command substitution (`$(...)`) or heredoc/`printf`, none of which are portable (Rule #1). The robust path on every OS: write the full body (summary + embed block) to a file with the Write tool, then `gh pr create --body-file <path>`. See `./sdd.md` step 7.
 
 ### 5.4 Update issue status
 ```bash
@@ -226,7 +226,7 @@ Idempotent and safe to skip when there is no back-reference. `--epic-branch` run
 
 ### 5.5 Close the run record
 
-Close the record Phase 0 opened, using the `runId` it printed. This is what snapshots the run's token cost — `finalize` reads the session transcript for the run's window and stores the rollup **in the same record**, so cost and outcome finally share a key (#1333):
+Close the record Phase 0 opened, using the `runId` it printed. This is what snapshots the run's token cost — `finalize` reads the session transcript for the run's window and stores the rollup **in the same record**, so cost and outcome finally share a key:
 
 ```bash
 flo runs finalize --run-id <runId>            # or: --status failed --error "<summary>"
@@ -236,7 +236,7 @@ Run it after the PR is open (5.3) so the rollup covers the whole run. Skipped un
 
 Snapshot rather than compute-on-read because Claude Code prunes `~/.claude/projects/**` — measured at roughly two days of history, so a cost joined at read time would be correct today and zero next week.
 
-`tokens.transcripts: 0` in the stored record means the run's cost could **not** be measured (no transcript, or no session id was stamped), which is not the same as a run that cost nothing. `success` means the run reached a terminal state without reporting an error — it is not a verification that the work was correct, and nothing here should be described as one (#1322).
+`tokens.transcripts: 0` in the stored record means the run's cost could **not** be measured (no transcript, or no session id was stamped), which is not the same as a run that cost nothing. `success` means the run reached a terminal state without reporting an error — it is not a verification that the work was correct, and nothing here should be described as one.
 
 ### 5.3b Auto-merge the PR (`mergeMode` / `merge.auto`)
 

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

@@ -1,9 +1,9 @@
 # SDD & Verification (`-sd` / `--sdd`, `-v` / `--verify`)
 
-Spec-Driven Development for `/flo` — Epic #1269. Two independent modifiers:
+Spec-Driven Development for `/flo`. Two independent modifiers:
 
 - **`-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.
+- **`-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) — `-v` is explicit, `--no-verify` opts out for one run.
 
 ⚠ **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.
 
@@ -11,13 +11,13 @@ Precedence: per-run flags and `--no-sdd` / `--no-verify` override `moflo.yaml`,
 
 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.
 
-> **Memory-first for SDD mechanics (do not bulk-read the guidance doc).** The authoritative SDD rules live in the **indexed** guidance doc `.claude/guidance/moflo-sdd.md`. Reach the slice you need via `mcp__moflo__memory_search { namespace: "guidance", query: "sdd <topic>" }` and traverse chunks with `mcp__moflo__memory_get_neighbors` — do **not** `Read` the whole `moflo-sdd.md` to find a rule (that is the anti-pattern #1292 fixes: with `-sd` enabled the operator read the entire doc instead of searching for the part it needed). **This file** (`./sdd.md`) is the skill's own companion runbook — it lives under `.claude/skills/`, is *not* indexed, and so is `Read` directly. See `SKILL.md` Step 0.
+> **Memory-first for SDD mechanics (do not bulk-read the guidance doc).** The authoritative SDD rules live in the **indexed** guidance doc `.claude/guidance/moflo-sdd.md`. Reach the slice you need via `mcp__moflo__memory_search { namespace: "guidance", query: "sdd <topic>" }` and traverse chunks with `mcp__moflo__memory_get_neighbors` — do **not** `Read` the whole `moflo-sdd.md` to find a rule (the anti-pattern: with `-sd` enabled, reading the entire doc instead of searching for the part you need). **This file** (`./sdd.md`) is the skill's own companion runbook — it lives under `.claude/skills/`, is *not* indexed, and so is `Read` directly. See `SKILL.md` Step 0.
 
 ## The `--sdd` cycle
 
-Artifacts live at `<specs_dir>/<slug>/{spec,plan}.md` — default `.moflo/specs`, which is **gitignored** (local, not committed). By default (`sdd.embed_in_pr: true`) the spec + plan are appended to the PR body, so the reasoning is **reviewable in the PR even while specs stay local**. To source-control the artifacts instead (or as well), set `moflo.yaml sdd.specs_dir` to a tracked path (e.g. `docs/specs`) and commit them (#1294). Drive them with the `flo sdd` CLI; never hand-write the paths.
+Artifacts live at `<specs_dir>/<slug>/{spec,plan}.md` — default `.moflo/specs`, which is **gitignored** (local, not committed). By default (`sdd.embed_in_pr: true`) the spec + plan are appended to the PR body, so the reasoning is **reviewable in the PR even while specs stay local**. To source-control the artifacts instead (or as well), set `moflo.yaml sdd.specs_dir` to a tracked path (e.g. `docs/specs`) and commit them. Drive them with the `flo sdd` CLI; never hand-write the paths.
 
-**The front half is enforced, not advisory (#1297).** When a run is armed for SDD (`-sd`/`--sdd` or `sdd.default`), the `check-before-implement` gate **blocks every source `Write`/`Edit`** until a spec exists for the active slug and its plan is `reviewed`. Skipping straight to implementation is not possible — do the spec→plan steps first. `flo sdd spec` stamps the active slug so the gate knows which unit this run is building. One-off escape hatch: re-run with `--no-sdd`; per-project off-switch: `gates: sdd_gate: false`.
+**The front half is enforced, not advisory.** When a run is armed for SDD (`-sd`/`--sdd` or `sdd.default`), the `check-before-implement` gate **blocks every source `Write`/`Edit`** until a spec exists for the active slug and its plan is `reviewed`. Skipping straight to implementation is not possible — do the spec→plan steps first. `flo sdd spec` stamps the active slug so the gate knows which unit this run is building. One-off escape hatch: re-run with `--no-sdd`; per-project off-switch: `gates: sdd_gate: false`.
 
 1. **Spec** — capture the *what* + acceptance criteria:
    ```bash
@@ -52,7 +52,7 @@ Artifacts live at `<specs_dir>/<slug>/{spec,plan}.md` — default `.moflo/specs`
 
 Runs at step 8 of the full-mode flow, before the PR — **by default** and always under `--sdd`; `--no-verify` skips it for one run.
 
-**Delegate to the `/verify` skill** — `Skill({ skill: "verify" })`, passing the issue number or spec slug. It owns the mechanics (single source of truth — don't restate them here): locate the acceptance criteria (plan, else ticket) → reuse the Tests-phase run (no double verify) → map each criterion to evidence → run only uncovered checks → record its own outcome to memory (`verify`, `verify:<slug-or-issue>`) → return a per-criterion PASS/FAIL. **The verdict is the point, not the invocation** (#1332). Invoking `/verify` trips `record-verify-run`, but that alone no longer opens `check-before-done` — the gate requires the recorded verdict to be `PASS`. A run returning FAIL leaves `gh pr create` blocked, which is the intended behaviour: the change did not meet its acceptance criteria. The verdict reaches the gate from the structured record `/verify` Step 5 writes to `memory_store` under `metadata.overall` (#1328), so a run that stores prose only is treated as *no verdict* and also blocks. Describing verification in prose has never satisfied the gate. A source edit after verifying invalidates both the flag and the verdict — re-run `/verify`. Full how-to: `.claude/skills/verify/SKILL.md`.
+**Delegate to the `/verify` skill** — `Skill({ skill: "verify" })`, passing the issue number or spec slug. It owns the mechanics (single source of truth — don't restate them here): locate the acceptance criteria (plan, else ticket) → reuse the Tests-phase run (no double verify) → map each criterion to evidence → run only uncovered checks → record its own outcome to memory (`verify`, `verify:<slug-or-issue>`) → return a per-criterion PASS/FAIL. **The verdict is the point, not the invocation.** Invoking `/verify` trips `record-verify-run`, but that alone no longer opens `check-before-done` — the gate requires the recorded verdict to be `PASS`. A run returning FAIL leaves `gh pr create` blocked, which is the intended behaviour: the change did not meet its acceptance criteria. The verdict reaches the gate from the structured record `/verify` Step 5 writes to `memory_store` under `metadata.overall`, so a run that stores prose only is treated as *no verdict* and also blocks. Describing verification in prose has never satisfied the gate. A source edit after verifying invalidates both the flag and the verdict — re-run `/verify`. Full how-to: `.claude/skills/verify/SKILL.md`.
 
 `/ward` and `/quicken` stay targeted audits, not the completion gate.