moflo 4.11.9 → 4.11.10-rc.10

package/.claude/guidance/shipped/moflo-core-guidance.md

@@ -218,6 +218,7 @@ See `.claude/guidance/moflo-memory-strategy.md` for memory-specific troubleshoot
 ## See Also
 
 - `.claude/guidance/moflo-skills-reference.md` — Slash-command skills catalog (`/flo`, `/commune`, `/meditate`, `/divine`, …) plus the automatic features (auto-meditate, session-continuity)
+- `.claude/guidance/moflo-sdd.md` — Spec-Driven Development (`/flo -sd`/`-v`, `flo sdd`, verify-before-done gate, `sdd.default` / `gates.verify_before_done`)
 - `.claude/guidance/moflo-cli-reference.md` — CLI commands, agents, hooks, hive-mind, RuVector
 - `.claude/guidance/moflo-yaml-reference.md` — `moflo.yaml` schema, environment variables, `.mcp.json` setup
 - `.claude/guidance/moflo-subagents.md` — Subagents memory-first protocol and store patterns

package/.claude/guidance/shipped/moflo-epic-processing.md

@@ -57,6 +57,7 @@ The strategy is resolved with this precedence (highest first):
 
 ## See Also
 
+- `.claude/guidance/moflo-session-continuity.md` — How `epic-state` + git reconciliation resume works vs. native Claude Code checkpoints (`/rewind`, agent-tree)
 - `src/cli/commands/epic.ts` — Epic command implementation
 - `src/cli/config/moflo-config.ts` — `MofloConfig.epic` interface and defaults
 - `.claude/skills/fl/SKILL.md` — `/flo` skill epic handling section

package/.claude/guidance/shipped/moflo-sdd.md

@@ -0,0 +1,97 @@
+# MoFlo Spec-Driven Development (SDD) & Verify-Before-Done
+
+**Purpose:** How to run and reason about the `spec → plan → implement → verify` cycle in `/flo`, the `flo sdd` artifact CLI, and the verify-before-done gate. Read this before using `-sd`/`-v`/`--no-verify`, editing `.moflo/specs/`, or tuning `sdd.default` / `gates.verify_before_done`.
+
+---
+
+## When to Use `-sd` vs `-v` vs Neither
+
+Two independent modifiers on `/flo`, orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`. The **spec/plan ceremony (`-sd`) is opt-in**; **verify-before-done (`-v`) runs by default** (#1294) — separable from SDD by design.
+
+| Situation | Flag | Effect |
+|-----------|------|--------|
+| Fuzzy or large unit of work; you want a reviewed spec/plan before code | `-sd` / `--sdd` | Full spec → plan → (review) → implement → verify. Implies `--verify`. Opt-in. |
+| A default run already verifies before done | (none) | Verify-before-done runs automatically via the `/verify` skill. |
+| Skip verification for one run | `--no-verify` | Drops the (default-on) verify step. |
+
+`--sdd` **always implies** `--verify` — a spec/plan without an enforced verify step drifts. `--no-sdd` / `--no-verify` opt a single run out; `-v` only matters to force verify back on where a project set `verify_before_done: false`.
+
+---
+
+## The Artifact Convention
+
+Specs and plans persist as Markdown, one directory per unit of work, under the configured specs directory (default `.moflo/specs`):
+
+```
+<specs_dir>/<slug>/spec.md   # the "what" + acceptance criteria
+<specs_dir>/<slug>/plan.md   # the "steps" + how each criterion is verified
+```
+
+They are indexed into memory on session start, so `mcp__moflo__memory_search` surfaces prior specs across sessions. **Always create and mutate them through the `flo sdd` CLI** — never hand-write the path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
+
+**Where they live is configurable (`sdd.specs_dir`, #1294).** The default `.moflo/specs` is **gitignored** by `flo init` — specs stay local and do not bloat source control, but they also do **not** appear in PRs. To make specs reviewable, point `sdd.specs_dir` at a **tracked** path and commit them:
+
+| `sdd.specs_dir` | Committed? | Use when |
+|-----------------|------------|----------|
+| `.moflo/specs` (default) | No (gitignored) | You want the SDD workflow but not spec artifacts in history |
+| `docs/specs`, `.specs`, … (tracked) | Yes | You want specs reviewed in the PR alongside the code |
+
+Set it once in `moflo.yaml`; the `flo sdd` CLI and the session-start indexer both honor it. If the path sits inside a `guidance.directories` entry, specs are indexed once (as guidance), not twice.
+
+Each artifact carries a `status` of `draft` or `reviewed` in its frontmatter. The constitution layer (`CLAUDE.md` + `.claude/guidance/`) is referenced by every stage — never restate its invariants inside a spec.
+
+---
+
+## Driving the Cycle with `flo sdd`
+
+The `flo sdd` CLI is the single cross-platform entry point for every SDD artifact operation — scaffold, review, gate, and status. Drive the cycle through these commands; never hand-write a `.moflo/specs/...` path in a skill step.
+
+| Command | Does |
+|---------|------|
+| `flo sdd spec "<title>"` | Scaffold `spec.md` (or show an existing one). `--from <file\|->` seeds the body. |
+| `flo sdd review <slug>` | Mark the spec reviewed — unlocks the plan. |
+| `flo sdd plan <slug>` | Scaffold `plan.md`; **requires the spec be reviewed**. |
+| `flo sdd review <slug> plan` | Mark the plan reviewed — unlocks implementation. |
+| `flo sdd check <slug> implement` | Review-checkpoint gate — exits non-zero until the plan is reviewed. |
+| `flo sdd list` / `flo sdd status <slug>` | Enumerate specs / show one unit's spec+plan status. |
+
+The two review checkpoints are the point: **a spec must be reviewed before its plan; a plan must be reviewed before implementation.** Pass `--force` only to deliberately skip a checkpoint.
+
+---
+
+## Verify-Before-Done Gate
+
+When enforced, `gh pr create` is blocked until the change has been verified end-to-end since the last code edit.
+
+- **On by default (#1294).** Enforced for every `/flo` run; disable per-project with `gates.verify_before_done: false` or per-run with `--no-verify`. On upgrade, consumers with no `verify_before_done` key start enforcing; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
+- **Satisfy it by running the `/verify` skill** — `/flo` delegates to it. It exercises the change against the plan's (or ticket's) acceptance criteria and records its own outcome to memory (`namespace: learnings, key: verify:<slug>`). It reuses the Tests-phase run rather than repeating it (no double verify).
+- **A source edit invalidates a prior verification** — re-run `/verify` after editing. `/ward` and `/quicken` are targeted audits, not the completion gate.
+
+---
+
+## SDD & Verify moflo.yaml Defaults
+
+`sdd.default` is off (opt-in); `verify_before_done` is **on** (#1294). Override per run with the flags.
+
+```yaml
+sdd:
+  default: false              # true → every /flo run uses the SDD cycle unless --no-sdd
+gates:
+  verify_before_done: true    # on by default (#1294); false → skip /verify unless -v. Per-run: --no-verify
+```
+
+Check wiring status with `/healer` (or `/eldar`) — the `SDD + Verify Wiring` check reports whether the gate cases and hooks are present and which toggles are on.
+
+---
+
+## From a Fuzzy Idea: `/commune` → Spec
+
+When the unit of work is still fuzzy, start with `/commune`. It runs a short Socratic dialogue and synthesizes a spec, then can hand that spec straight into the SDD spine (`flo sdd spec "<title>" --from -`). Rename its **Success criteria** section to **`## Acceptance Criteria`** on the way in — the SDD validator requires it. `/commune` is the pre-execution counterpart to `/meditate`.
+
+---
+
+## See Also
+
+- `.claude/skills/fl/sdd.md` — the `/flo` companion that drives `-sd`/`-v` end to end
+- `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, gates, and config hub
+- `.claude/guidance/moflo-yaml-reference.md` — full `moflo.yaml` field reference, including `sdd` and `gates`

package/.claude/guidance/shipped/moflo-session-continuity.md

@@ -0,0 +1,71 @@
+# Native Checkpoints vs. MoFlo Continuity — Who Owns Undo and Resume
+
+**Purpose:** Decide which layer owns a given "undo" or "resume" — Claude Code's native checkpoints (`/rewind`, agent-tree checkpointing) or moflo's session-continuity + epic-state — so the two coexist by layering, never by competing. Read this before wiring any resume/rollback behavior into a moflo workflow.
+
+---
+
+## Ownership Decision Table
+
+The two systems solve different problems. Never route a job to the wrong layer or build a moflo mechanism that duplicates a native one.
+
+| You want to… | Owner | Mechanism |
+|--------------|-------|-----------|
+| Undo code edits from earlier THIS session | Native | `/rewind` code checkpoints |
+| Pause/resume a multi-hour agent tree WITHIN a session | Native | Agent-tree checkpointing (beta) |
+| Pick up context ACROSS sessions ("where you left off") | MoFlo | Session-continuity digest |
+| Resume an interrupted `flo epic` from real progress | MoFlo | `epic-state` reconciled against git + the GitHub checklist |
+| Fail over to another model when a tier is unavailable | Native | `fallbackModel` — moflo's router emits the chain |
+
+**Rule:** native checkpoints govern *in-session* rollback of code and agent trees; moflo governs *cross-session* coordination and the durable learning record. They layer; they do not overlap.
+
+---
+
+## Native Checkpoints Are Runtime-Only — Never Couple MoFlo to Them
+
+Native `/rewind`, code checkpoints, and agent-tree checkpoint state live entirely inside the Claude Code runtime. There is **no stable public file or API** for them, and moflo library code (the `flo` CLI, MCP server, hooks, launcher, daemon) is never handed a reference to that state.
+
+**Never read or write native checkpoint state from moflo code.** Coupling to an undocumented runtime format violates the cross-platform rule and the consumer-blast-radius rule — it would break silently on any Claude Code update, in every consumer install. Treat native checkpoints as a black box the human drives; moflo reacts to committed results (git, GitHub), not to session snapshots.
+
+---
+
+## MoFlo Session-Continuity — The Cross-Session Digest
+
+Session-continuity is moflo's narrative bridge between sessions, distinct from native checkpoints. At session end it captures a scrubbed digest — `{goal, decisions, gitState}` — to a rotated JSON store under `.moflo/`. At session start it scores digests by branch match, changed-file overlap, and recency, then injects the best one as a **"Where you left off"** lead.
+
+**Treat the injected digest as a verifiable lead, not ground truth.** It reflects what was true when it was written — re-check the current branch, working tree, and files before acting on it. Configure via `session_continuity: {capture, inject, max_age_hours}` in `moflo.yaml`; both flags default on.
+
+---
+
+## Epic Resume Is Checkpoint-Agnostic — Git Is the Source of Truth
+
+`flo epic` records progress in the `epic-state` memory namespace, but that namespace is an **in-session cache, hard-deleted on every session start** — never rely on it as the durable resume store. The durable sources of truth are the **git epic branch + commits** and the **GitHub issue checklist** (`[ ]` vs `[x]`).
+
+On resume, `epic.ts` reconciles memory against git: it recomputes the `epic/{n}-{slug}` branch and, if the branch is missing or has no commits ahead of the base, discards the memory record and starts fresh. This makes epic resume **independent of native checkpoints** — it works identically whether or not the user used `/rewind`, because truth is re-derived from committed state, not a session snapshot. Do not add native-checkpoint detection to epic resume; it would be unverifiable noise.
+
+---
+
+## Swarm and Hive-Mind Are a Logical Layer Native Nesting Does Not Replace
+
+MoFlo's `UnifiedSwarmCoordinator` is a **logical coordination layer** — an agent registry plus MessageBus routing, consensus voting, and workload-balanced task distribution. "Spawn" registers a tracked record; it never launches a process. Hive-mind is one level deep (queen → flat worker list; workers never spawn sub-workers).
+
+Native 3-level nested subagents solve **process and context isolation for real, executing agents** — an orthogonal concern. Native nesting does not replace the registry, MessageBus, consensus, or task distribution.
+
+**Never rewire swarm/hive-mind onto native nesting.** Reducing coordinator handlers to stubs to "map onto native primitives" is exactly the disconnection the protected-functionality rule forbids, for zero functional gain. The only seam between the two — the subagent bootstrap directive — is already carried in every spawn's metadata and response. Keep every handler wired to the coordinator.
+
+---
+
+## Model Routing Emits Native `fallbackModel` Chains
+
+MoFlo's model router already tracks per-tier circuit-breaker state. Its routing result carries a `fallbackModel` chain: an ordered, circuit-breaker-aware failover list that excludes the primary, drops `inherit` and zero-score tiers, and demotes any open-circuit tier to the tail.
+
+The chain is **advisory** — surfaced to the orchestrator via `hooks_model-route` and `agent_spawn`, then applied when spawning a real subagent. MoFlo never auto-launches a model itself; the orchestrator (or the native `Task` spawn) consumes the chain and maps it onto Claude Code's native `fallbackModel`. A healthy lower tier is always tried before a failing one.
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-epic-processing.md` — Epic orchestration whose `epic-state` + git reconciliation this doc frames against native checkpoints
+- `.claude/guidance/moflo-claude-swarm-cohesion.md` — Swarm/hive coordination model the "logical layer" note protects
+- `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, swarm, memory, and config hub
+- `src/cli/movector/model-router.ts` — Router that emits the `fallbackModel` chain
+- `src/cli/commands/epic.ts` — Epic resume + git-branch reconciliation

package/.claude/helpers/gate.cjs

@@ -3,11 +3,12 @@
 var fs = require('fs');
 var path = require('path');
 var cp = require('child_process');
+var os = require('os');
 
 var PROJECT_DIR = (process.env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var STATE_FILE = path.join(PROJECT_DIR, '.claude', 'workflow-state.json');
 
-var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false };
+var STATE_DEFAULTS = { tasksCreated: false, taskCount: 0, memorySearched: false, memorySearchedBy: {}, memoryRequired: true, learningsStored: false, testsRun: false, simplifyRun: false, simplifySnapshotSha: null, verifyRun: false, verifyOutcome: null, interactionCount: 0, sessionStart: null, lastBlockedAt: null, lastNamespaceHint: '', lastNamespaceHintEmittedBy: {}, flMode: null, swarmInitialized: false, hiveInitialized: false, sddMode: false, activeSddSlug: null };
 
 // Per-actor memory-search tracking (#838). The legacy `memorySearched` boolean
 // is session-wide, so once the parent searches memory, every spawned subagent
@@ -60,27 +61,86 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true };
-  try {
-    var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
-    if (fs.existsSync(yamlPath)) {
-      var content = fs.readFileSync(yamlPath, 'utf-8');
-      if (/memory_first:\s*false/i.test(content)) defaults.memory_first = false;
-      if (/task_create_first:\s*false/i.test(content)) defaults.task_create_first = false;
-      if (/context_tracking:\s*false/i.test(content)) defaults.context_tracking = false;
-      if (/testing_gate:\s*false/i.test(content)) defaults.testing_gate = false;
-      if (/simplify_gate:\s*false/i.test(content)) defaults.simplify_gate = false;
-      if (/learnings_gate:\s*false/i.test(content)) defaults.learnings_gate = false;
-      if (/swarm_invocation_gate:\s*false/i.test(content)) defaults.swarm_invocation_gate = false;
-    }
-  } catch (e) { /* use defaults */ }
+  // verify_before_done is opt-OUT (default true), like every other gate: #1294
+  // ships a real /verify skill and has /flo delegate to it, so leaving it off by
+  // default would make the default /flo run silently skip the acceptance check.
+  // Disable per-project with `verify_before_done: false` or per-run `--no-verify`.
+  var defaults = { memory_first: true, task_create_first: true, context_tracking: true, testing_gate: true, simplify_gate: true, learnings_gate: true, swarm_invocation_gate: true, verify_before_done: true, sdd_gate: true };
+  var content = MOFLO_YAML;
+  if (content) {
+    if (/memory_first:\s*false/i.test(content)) defaults.memory_first = false;
+    if (/task_create_first:\s*false/i.test(content)) defaults.task_create_first = false;
+    if (/context_tracking:\s*false/i.test(content)) defaults.context_tracking = false;
+    if (/testing_gate:\s*false/i.test(content)) defaults.testing_gate = false;
+    if (/simplify_gate:\s*false/i.test(content)) defaults.simplify_gate = false;
+    if (/learnings_gate:\s*false/i.test(content)) defaults.learnings_gate = false;
+    if (/swarm_invocation_gate:\s*false/i.test(content)) defaults.swarm_invocation_gate = false;
+    // Opt-out: on by default; disable only when explicitly set false.
+    if (/verify_before_done:\s*false/i.test(content)) defaults.verify_before_done = false;
+    // sdd_gate is the check-before-implement backstop (#1297). Opt-out; the
+    // gate only fires when a run is actually armed for SDD (sddMode), so
+    // leaving it on costs non-SDD work nothing.
+    if (/sdd_gate:\s*false/i.test(content)) defaults.sdd_gate = false;
+  }
   return defaults;
 }
 
+// Parse the top-level `sdd:` block from moflo.yaml (#1297). Scoped to the block
+// body so we never match a `default:` key from another section (epic, merge).
+// Cross-platform: tolerates CRLF; no path separators hardcoded.
+function loadSddConfig() {
+  var out = { default: false, specsDir: '.moflo/specs' };
+  var content = MOFLO_YAML;
+  if (!content) return out;
+  var block = content.match(/^sdd:[ \t]*\r?\n((?:[ \t]+.*(?:\r?\n|$))*)/m);
+  if (!block) return out;
+  var body = block[1];
+  if (/^\s*default:\s*true\b/im.test(body)) out.default = true;
+  var sd = body.match(/^\s*specs_dir:\s*(.+?)\s*$/im);
+  if (sd) {
+    var v = sd[1].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '').trim();
+    if (v) out.specsDir = v;
+  }
+  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
+// double-stat); ENOENT/unreadable → '' → every parser falls back to defaults.
+function readMofloYaml() {
+  try { return fs.readFileSync(path.join(PROJECT_DIR, 'moflo.yaml'), 'utf-8'); }
+  catch (e) { return ''; }
+}
+var MOFLO_YAML = readMofloYaml();
+
 var config = loadGateConfig();
+var sddConf = loadSddConfig();
 var command = process.argv[2];
 
 var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state', 'node_modules', 'moflo.yaml'];
+
+// #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
+// memory-first gate. Cross-platform (Rule #1): os.tmpdir() is correct on every
+// OS; we normalize a leading `/private` on both sides so macOS's
+// /var/folders (os.tmpdir) vs /private/var/folders (realpath) symlink pair
+// still matches (CLAUDE.md #1145). Never hardcode `/tmp`.
+function stripPrivate(p) { return p.indexOf('/private/') === 0 ? p.slice('/private'.length) : p; }
+function isEphemeralPath(fp) {
+  if (!fp) return false;
+  var tmp;
+  try { tmp = path.resolve(os.tmpdir()); } catch (e) { return false; }
+  var t = stripPrivate(tmp);
+  function under(p) { var n = stripPrivate(p); return n === t || n.indexOf(t + path.sep) === 0; }
+  var resolved = path.resolve(fp);
+  if (!under(resolved)) return false;
+  // Under tmp by literal path — confirm it isn't a symlink staged in tmp that
+  // dereferences to a real project file (realpath BOTH sides, CLAUDE.md Rule #2).
+  // On ENOENT (a not-yet-created tmp file) keep the verdict — still ephemeral.
+  try { return under(fs.realpathSync(resolved)); } catch (e) { return true; }
+}
 // #1171 — DANGEROUS gained PowerShell additions to match the matcher widening
 // that now routes the dedicated `PowerShell` tool through check-dangerous-command.
 // POSIX entries still apply because PS will execute them when invoked. Substring
@@ -228,6 +288,59 @@ 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) {
+  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;
+}
+
+// Resolve the absolute specs root the same way TS specsRoot does (#1294): split
+// the /-written config value on either separator, reject absolute/`..`-escaping
+// values, and fall back to the gitignored default. Rule #1: no separator hardcoded.
+function sddSpecsRootAbs() {
+  var configured = (sddConf.specsDir || '.moflo/specs');
+  var segments = configured.split(/[\\/]+/).filter(Boolean);
+  var escapes = segments.length === 0
+    || segments.indexOf('..') >= 0
+    || /^([a-zA-Z]:|~)$/.test(segments[0])
+    || configured.charAt(0) === '/'
+    || configured.charAt(0) === '\\';
+  if (escapes) return path.join(PROJECT_DIR, '.moflo', 'specs');
+  return path.join.apply(path, [PROJECT_DIR].concat(segments));
+}
+
+// Is the edited path inside the specs dir? Editing spec.md/plan.md themselves must
+// never trip the implement gate. Compares resolved absolute paths (Rule #1: the
+// edit path may be relative or absolute; normalize both before the prefix test).
+function isInsideSpecsDir(filePath) {
+  try {
+    var root = sddSpecsRootAbs();
+    var abs = path.isAbsolute(filePath) ? filePath : path.resolve(PROJECT_DIR, filePath);
+    var rel = path.relative(root, abs);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  } catch (e) { return false; }
+}
+
+// Read plan.md frontmatter for the active slug and report whether it is reviewed.
+// Pure fs + regex (no spawn) so it stays cheap on every Write/Edit. Matches the
+// double-quoted scalar serializeArtifact emits (`status: "reviewed"`).
+function isPlanReviewed(slug) {
+  try {
+    var planPath = path.join(sddSpecsRootAbs(), slug, 'plan.md');
+    if (!fs.existsSync(planPath)) return false;
+    var content = fs.readFileSync(planPath, 'utf-8').replace(/\r\n/g, '\n');
+    var fm = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!fm) return false;
+    return /^\s*status:\s*["']?reviewed["']?\s*$/im.test(fm[1]);
+  } catch (e) { return false; }
+}
+
 function classifyNamespaceHint(promptText) {
   var lower = (promptText || '').toLowerCase();
   if (NS_TEST_RE.test(lower)) return 'Memory namespace hint: use "tests" for test inventory and coverage lookups.';
@@ -300,6 +413,10 @@ function applyPromptStateReset(state, promptText) {
   state.flMode = detectFlMode(promptText);
   state.swarmInitialized = false;
   state.hiveInitialized = false;
+  // #1297 — arm/disarm the SDD implement gate per prompt. A fresh /flo run starts
+  // with no active slug; `flo sdd spec` stamps activeSddSlug during the run.
+  state.sddMode = detectSddMode(promptText);
+  state.activeSddSlug = null;
 }
 // Match npm/yarn/pnpm/bun test, npx vitest|jest|..., bare runners at command-start only,
 // and language-native test commands. The bare-runner arm is anchored so that
@@ -525,6 +642,7 @@ switch (command) {
     var s = readState();
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     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.exit(2);
@@ -534,6 +652,9 @@ switch (command) {
     var s = readState();
     if (!s.memoryRequired || isMemorySearchedFor(s)) break;
     var fp = process.env.TOOL_INPUT_file_path || '';
+    // Ephemeral tmp/scratch reads are exempt even when they look like guidance
+    // (a temp copy is still transient tool I/O, not the indexed source).
+    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');
@@ -654,6 +775,25 @@ switch (command) {
     }
     break;
   }
+  case 'record-verify-run': {
+    // Story #1274 (Epic #1269). Fires PostToolUse on ^Skill$ when the native
+    // /verify skill runs, satisfying the verify-before-done gate. Mirrors
+    // record-skill-run's fault-tolerant shape. The verification OUTCOME (what
+    // was checked, pass/fail) is written to memory by the verify flow itself
+    // via mcp__moflo__memory_store — same division of labour as testsRun vs the
+    // test output; this recorder only tracks that verification happened.
+    var vName = (process.env.TOOL_INPUT_skill || '');
+    // Only the native /verify skill satisfies verify-before-done. /ward and
+    // /quicken are targeted audits, NOT the completion gate (see fl/sdd.md) —
+    // crediting them would let the gate pass without an end-to-end verify.
+    if (vName === 'verify') {
+      var s = readState();
+      if (!s.verifyRun) { s.verifyRun = true; writeState(s); }
+    } else if (vName) {
+      process.stderr.write('gate: record-verify-run no-op — TOOL_INPUT_skill="' + vName + '" is not verify\n');
+    }
+    break;
+  }
   case 'reset-edit-gates': {
     var fp = process.env.TOOL_INPUT_file_path || '';
     // Inert files (markdown, lockfiles, CHANGELOG, .env.example) AND inert paths
@@ -664,10 +804,14 @@ switch (command) {
     // Test-only edits invalidate testsRun but preserve simplifyRun (#908).
     var isTestOnly = fp && EDIT_RESET_SKIP_SIMPLIFY_ONLY_RE.test(fp);
     var resetTests = s.testsRun;
+    // A code edit invalidates a prior verification (Story #1274) — same as tests,
+    // including test-only edits (the criteria being verified may have moved).
+    var resetVerify = s.verifyRun;
     var resetSimplify = s.simplifyRun && !isTestOnly;
-    if (!resetTests && !resetSimplify) break;
+    if (!resetTests && !resetSimplify && !resetVerify) break;
     var gates = [];
     if (resetTests) { s.testsRun = false; gates.push('tests'); }
+    if (resetVerify) { s.verifyRun = false; gates.push('verify'); }
     if (resetSimplify) { s.simplifyRun = false; gates.push('simplify'); }
     if (fp) {
       s.lastResetBy = { file: fp, at: new Date().toISOString(), gates: gates };
@@ -675,6 +819,44 @@ switch (command) {
     writeState(s);
     break;
   }
+  case 'check-before-implement': {
+    // #1297 — the SDD front-half backstop. When a run is armed for SDD
+    // (sddMode, set from -sd/--sdd or sdd.default on a /flo run), block source
+    // Write/Edit until a spec exists and its plan is reviewed. Mirrors the
+    // memory_first gate shape. Disarmed runs (the default for non-SDD work)
+    // pass instantly. Opt out per-project with `gates: sdd_gate: false`.
+    if (!config.sdd_gate) break;
+    var si = readState();
+    if (!si.sddMode) break; // not an SDD run — no enforcement
+    var fpi = process.env.TOOL_INPUT_file_path || '';
+    if (!fpi) break;
+    // Only gate real source edits. Exempt the same inert files/paths the other
+    // gates skip, plus the spec/plan artifacts themselves.
+    if (EXEMPT.some(function (e) { return fpi.indexOf(e) >= 0; })) break;
+    if (!SOURCE_FILE_RE.test(fpi)) break;
+    if (EDIT_RESET_SKIP_PATH_RE.test(fpi)) break;
+    if (isInsideSpecsDir(fpi)) break;
+    if (!si.activeSddSlug) {
+      process.stderr.write(
+        'BLOCKED: SDD mode is on — author a spec before editing source.\n' +
+        'Run: flo sdd spec "<title>"   (then review it, and plan)\n' +
+        'This run is spec-gated (-sd / sdd.default). One-off skip: re-run with --no-sdd.\n' +
+        'Disable per-project via moflo.yaml: gates: sdd_gate: false\n'
+      );
+      process.exit(2);
+    }
+    if (!isPlanReviewed(si.activeSddSlug)) {
+      process.stderr.write(
+        'BLOCKED: SDD — the plan for "' + si.activeSddSlug + '" is not reviewed yet.\n' +
+        'Author + review the plan first:\n' +
+        '  flo sdd plan ' + si.activeSddSlug + '\n' +
+        '  flo sdd review ' + si.activeSddSlug + ' plan\n' +
+        'One-off skip: re-run with --no-sdd. Disable via moflo.yaml: gates: sdd_gate: false\n'
+      );
+      process.exit(2);
+    }
+    break;
+  }
   case 'check-before-pr': {
     // Anchored to command-start (or chained via && / || / ;) so heredoc bodies
     // and quoted strings that contain the literal "gh pr create" don't trip
@@ -734,6 +916,40 @@ switch (command) {
     process.stderr.write('  gates:\n    testing_gate: false\n    simplify_gate: false\n    learnings_gate: false\n');
     process.exit(2);
   }
+  case 'check-before-done': {
+    // Story #1274 (Epic #1269) + #1294. Verify-before-done: block `gh pr create`
+    // until the change has been verified end-to-end (the /verify skill) against
+    // the plan's acceptance criteria. ON by default (#1294) — /flo delegates to
+    // /verify, so a default run does the acceptance check; disable per-project
+    // with `gates: verify_before_done: false` or per-run `--no-verify`. Same
+    // trigger + no-source exemption as check-before-pr, so they compose on one
+    // command (docs-only diffs are exempt, so this never blocks a docs PR).
+    if (!config.verify_before_done) break;
+    var cmd = process.env.TOOL_INPUT_command || '';
+    if (!/(?:^|&&\s*|\|\|\s*|;\s*)\s*(?:[A-Z_][A-Z0-9_]*=\S+\s+)*gh\s+pr\s+create\b/.test(cmd)) break;
+    // No-source-files exemption — a docs-only / path-inert diff needs no verify.
+    var changedD = getChangedFilesVsBase();
+    if (changedD && changedD.length > 0) {
+      var hasSourceD = changedD.some(function(f) {
+        return SOURCE_FILE_RE.test(f) && !EDIT_RESET_SKIP_PATH_RE.test(f);
+      });
+      if (!hasSourceD) {
+        var reasonD = changedD.every(function(f) { return DOCS_ONLY_RE.test(f); }) ? 'Docs-only' : 'No source files in branch diff';
+        process.stdout.write(reasonD + ' (' + changedD.length + ' file' + (changedD.length === 1 ? '' : 's') + ') — skipping verify-before-done gate.\n');
+        break;
+      }
+    }
+    var sd = readState();
+    if (sd.verifyRun) break;
+    process.stderr.write('BLOCKED: gh pr create requires verification before done:\n');
+    process.stderr.write('  - the change has not been verified since the last code edit (run /verify)\n');
+    if (sd.lastResetBy && sd.lastResetBy.file && (sd.lastResetBy.gates || []).indexOf('verify') >= 0) {
+      process.stderr.write('Last gate reset: ' + sd.lastResetBy.file + ' (verify)\n');
+    }
+    process.stderr.write('Disable via moflo.yaml:\n');
+    process.stderr.write('  gates:\n    verify_before_done: false\n');
+    process.exit(2);
+  }
   case 'check-dangerous-command': {
     // #1171 follow-up — strip quoted string bodies and heredoc bodies before
     // substring-matching DANGEROUS. Without this, `git commit -m "...remove-item

package/.claude/skills/commune/SKILL.md

@@ -119,11 +119,16 @@ The whole point is to feed moflo's existing strengths, not start a parallel trac
 | Destination | When | How |
 |-------------|------|-----|
 | **`/flo` ticket** (Recommended) | The spec is a unit of work to build | Map the spec to Description / Acceptance Criteria / Suggested Test Cases, then run `/fl -t <title>` to create the GitHub issue (or `/fl <issue#>` to implement immediately). The spec's Success criteria become Acceptance Criteria; Scope+Approach become the Description. |
+| **SDD spec artifact** | The user wants the spec to drive an `/flo --sdd` run (the spec→plan→implement→verify cycle) | Pipe the synthesized markdown into the SDD spine: `flo sdd spec "<title>" --from -` (writes `.moflo/specs/<slug>/spec.md`, git-tracked + memory-indexed). Rename the spec's **Success criteria** section to **`## Acceptance Criteria`** first — the SDD validator requires it. Then `flo sdd review <slug>` when signed off, and hand to `/fl --sdd <issue#>` (or `/fl -sd <issue#>`). This is the pre-execution counterpart to `/meditate`. |
 | **Spell** | The spec describes a repeatable, automatable pipeline | Hand the spec to `/spell-builder` as the design input. |
 | **Memory** | The spec is a decision/insight to retain, not build now | `mcp__moflo__memory_store { namespace: "learnings", key: "spec:<topic>", value: <spec> }` (use `patterns` for a reusable approach). |
 | **Just the file** | The user wants the artifact only | `Write` the markdown to a path the user names, or to a repo-relative `docs/specs/<kebab-title>.md`. Never hardcode an absolute or OS-specific path (e.g. `/tmp`); build the path from the project root. |
 
-Offer to do more than one (e.g. save to memory **and** open a ticket). Default to the `/flo` ticket path when the user is unsure.
+Offer to do more than one (e.g. save to memory **and** open a ticket). Default to the `/flo` ticket path when the user is unsure. For the **SDD spec** path, always create the artifact through the `flo sdd` CLI — never hand-write the `.moflo/specs/...` path (cross-platform, Rule #1).
+
+## See Also — SDD
+
+`.claude/skills/fl/sdd.md` — how `/flo --sdd` consumes the spec artifact this skill produces and drives it through plan → implement → verify.
 
 ## Guardrails