moflo 4.11.10-rc.2 → 4.11.10-rc.4

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

@@ -1,33 +1,42 @@
 # 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`, editing `.moflo/specs/`, or turning on `sdd.default` / `gates.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, opt-in modifiers on `/flo` — orthogonal to execution mode (`-n`/`-s`/`-h`) and `--worktree`. Verify is separable from SDD by design.
+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`. |
-| Well-scoped work, but you want "prove it works before done" enforced | `-v` / `--verify` | Normal run plus the verify-before-done gate; no spec/plan front-half. |
-| Small, obvious change | (none) | Standard `/flo` run. |
+| 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. Use `--no-sdd` / `--no-verify` to opt a single run out of a `moflo.yaml` default.
+`--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 reviewable Markdown, one directory per unit of work:
+Specs and plans persist as Markdown, one directory per unit of work, under the configured specs directory (default `.moflo/specs`):
 
 ```
-.moflo/specs/<slug>/spec.md   # the "what" + acceptance criteria
-.moflo/specs/<slug>/plan.md   # the "steps" + how each criterion is verified
+<specs_dir>/<slug>/spec.md   # the "what" + acceptance criteria
+<specs_dir>/<slug>/plan.md   # the "steps" + how each criterion is verified
 ```
 
-They are git-tracked in consumer repos (so they are reviewable) and 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 `.moflo/specs/...` path in a skill step (cross-platform, Rule #1: the CLI builds every path with `path.join`).
+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.
 
@@ -52,21 +61,21 @@ The two review checkpoints are the point: **a spec must be reviewed before its p
 
 When enforced, `gh pr create` is blocked until the change has been verified end-to-end since the last code edit.
 
-- **Enforcement is opt-in.** Off by default; enable with `gates.verify_before_done: true` (or per-run `-v`). Existing installs see zero change on upgrade.
-- **Satisfy it by running the native `/verify` skill** — it exercises the change against the plan's (or ticket's) acceptance criteria. Store the outcome to memory (`namespace: learnings, key: verify:<slug>`) so it feeds routing/learning.
+- **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.
 
 ---
 
 ## Configuration Defaults
 
-Both defaults are off; turn either on to make it the project standard, then override per run.
+`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: false   # true → require /verify before `gh pr create` unless --no-verify
+  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.

package/.claude/helpers/gate.cjs

@@ -60,10 +60,11 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  // Note: verify_before_done defaults to FALSE (opt-in) — the only gate that
-  // ships off, so existing consumers see zero behavior change on upgrade
-  // (Story #1274, Epic #1269). Every other gate is opt-out (default true).
-  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: false };
+  // 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 };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -75,8 +76,8 @@ function loadGateConfig() {
       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-in: enable only when explicitly set true.
-      if (/verify_before_done:\s*true/i.test(content)) defaults.verify_before_done = true;
+      // 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;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -763,12 +764,13 @@ switch (command) {
     process.exit(2);
   }
   case 'check-before-done': {
-    // Story #1274 (Epic #1269). Verify-before-done: block `gh pr create` until
-    // the change has been verified end-to-end (native /verify skill) against the
-    // plan's acceptance criteria. OFF by default — only enforced when the
-    // consumer opts in via moflo.yaml `gates: verify_before_done: true`, so
-    // existing installs see zero change on upgrade. Same trigger + no-source
-    // exemption as check-before-pr, so the two gates compose on one command.
+    // 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;

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

@@ -49,10 +49,10 @@ Two **independent** modifiers, orthogonal to execution mode (`-n`/`-s`/`-h`) and
 | 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 only** — a normal run plus the completion gate, no spec/plan front-half. |
-| `--no-sdd`, `--no-verify` | | Opt a single run out when a `moflo.yaml` default turned it on. |
+| `-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` and `gates.verify_before_done` — so a project can make either the default; per-run flags override. `--sdd` implies `--verify` (a spec/plan without an enforced verify step drifts). In `-t`/`-r` modes (no implementation) `--verify` is a no-op — emit the one-line ignored note; `--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` (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`.
 
 ## Auto-merge (#1285)
 
@@ -115,13 +115,14 @@ let epicBranch = null;
 let issueNumber = null;
 let titleWords = [];
 
-// SDD/verify modifiers (Epic #1269). 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 (absent ⇒ false):
-//   sddMode    ← `sdd.default: true`
-//   verifyMode ← `gates.verify_before_done: true`
+// 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 = false;       // -v  / --verify (verify-before-done only)
+let verifyMode = true;        // -v / --verify (on by default; --no-verify opts out)
+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).
@@ -167,7 +168,7 @@ for (let i = 0; i < args.length; i++) {
   // (swarm) + `d`; the swarm case above only matches the exact string "-s".
   else if (arg === "-sd" || arg === "--sdd")    { sddMode = true; verifyMode = true; }
   else if (arg === "--no-sdd")                  sddMode = false;
-  else if (arg === "-v" || arg === "--verify")  verifyMode = true;
+  else if (arg === "-v" || arg === "--verify")  { verifyMode = true; verifyExplicit = true; }
   else if (arg === "--no-verify")               verifyMode = false;
   // Auto-merge modifier. `-m` is free (`-h` is hive, `-s` is swarm) — no collision.
   else if (arg === "-m" || arg === "--merge")   mergeMode = true;
@@ -187,10 +188,12 @@ 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 — note and clear it. --sdd in
-// -t writes the spec/plan INTO the ticket (see ./sdd.md); in -r it's ignored.
-if (verifyMode && (workflowMode === "ticket" || workflowMode === "research")) {
-  console.log("Note: --verify ignored — " + workflowMode + " mode does not implement.");
+// 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
+// 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") {
+  if (verifyExplicit) console.log("Note: --verify ignored — " + workflowMode + " mode does not implement.");
   verifyMode = false;
 }
 if (sddMode && workflowMode === "research") {
@@ -225,7 +228,7 @@ Full mode runs end-to-end without further prompts.
 5. Create branch, implement, write tests — `./phases.md` Phases 3–4
 6. Run `/flo-simplify` on changed code; rerun tests if it edits — `./phases.md` Phase 4.5
 7. Commit — `./phases.md` Phase 5.1
-8. **If `verifyMode`** (always on under `sddMode`): verify the change end-to-end with `/verify` against the plan's acceptance criteria, and store the outcome to memory — `./sdd.md`. This satisfies the verify-before-done gate.
+8. **Verify — default, unless `--no-verify`** (`verifyMode`, always on under `sddMode`): delegate to the `/verify` skill — `Skill({ skill: "verify" })`. It checks the change against the acceptance criteria, reusing Phase 4's tests (no double verify) and recording its own outcome; invoking it satisfies the verify-before-done gate. Mechanics live in `.claude/skills/verify/SKILL.md`; trigger/flow in `./phases.md` Phase 5.1b.
 9. Store learnings via `mcp__moflo__memory_store` — `./phases.md` Phase 5.2
 10. Open PR, update issue status — `./phases.md` Phases 5.3–5.4
 11. **If `mergeMode`:** await the PR's merge preconditions and merge it (native `--auto` preferred, else poll-then-merge) — `./phases.md` Phase 5.3b

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

@@ -183,8 +183,10 @@ Closes #<issue-number>
 Co-Authored-By: moflo <noreply@motailz.com>"
 ```
 
-### 5.1b Verify-before-done (when `verifyMode` / `--sdd` / `gates.verify_before_done`)
-Run the native `/verify` skill to exercise the change end-to-end against the plan's (or ticket's) acceptance criteria, and store the outcome to memory. Under `--sdd` this always runs; independently, `-v`/`--verify` or `moflo.yaml gates.verify_before_done: true` triggers it. The `check-before-done` gate blocks `gh pr create` until a `/verify` run is recorded (a source edit invalidates a prior verification). Full mechanics: `./sdd.md`.
+### 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.
 
 ### 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.

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

@@ -2,16 +2,16 @@
 
 Spec-Driven Development for `/flo` — Epic #1269. Two independent modifiers:
 
-- **`-sd` / `--sdd`** — run the full **spec → plan → (review) → implement → verify** cycle. Implies `--verify`.
-- **`-v` / `--verify`** — verify-before-done only: a normal run plus the completion gate, no spec/plan front-half.
+- **`-sd` / `--sdd`** — run the full **spec → plan → (review) → implement → verify** cycle. Opt-in (`sdd.default` defaults false). 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`, `gates.verify_before_done`); 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.
+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.
 
 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.
 
 ## The `--sdd` cycle
 
-Artifacts live at `.moflo/specs/<slug>/{spec,plan}.md` (git-tracked in consumer repos → reviewable). 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 in PRs). Set `moflo.yaml sdd.specs_dir` to a tracked path (e.g. `docs/specs`) to make them reviewable (#1294). Drive them with the `flo sdd` CLI; never hand-write the paths.
 
 1. **Spec** — capture the *what* + acceptance criteria:
    ```bash
@@ -38,14 +38,9 @@ Specs/plans are indexed into memory on session start, so `mcp__moflo__memory_sea
 
 ## The `--verify` step (verify-before-done)
 
-Runs at step 8 of the full-mode flow, before the PR:
+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.
 
-1. Run the native **`/verify`** skill to exercise the change end-to-end. Under `--sdd`, verify against the plan's acceptance criteria; without a plan, verify against the ticket's Acceptance Criteria.
-2. Store the outcome to memory so it feeds routing/learning:
-   ```
-   mcp__moflo__memory_store { namespace: "learnings", key: "verify:<slug-or-issue>", value: "<what was verified, pass/fail>" }
-   ```
-3. The `/verify` run trips `record-verify-run`, satisfying the `check-before-done` gate — `gh pr create` unblocks. When `gates.verify_before_done: true`, this gate is enforced for every run whether or not `-v` was passed; `-v` makes the skill *do* the verification so the gate passes cleanly. A source edit after verifying invalidates it — re-run `/verify`.
+**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 (`learnings`, `verify:<slug-or-issue>`) → return a per-criterion PASS/FAIL. *Invoking* it is the point — it trips `record-verify-run` and satisfies the `check-before-done` gate (describing verification in prose does not). A source edit after verifying invalidates it — re-run `/verify`. Full how-to: `.claude/skills/verify/SKILL.md`.
 
 `/ward` and `/quicken` stay targeted audits, not the completion gate.
 

package/.claude/skills/verify/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: verify
+description: Verify-before-done — exercise the current change end-to-end against its acceptance criteria (the SDD plan's, or the ticket's) and report a per-criterion PASS/FAIL verdict, then record the outcome to memory. This is the concrete action that satisfies moflo's verify-before-done gate (`gates.verify_before_done` / `/flo -v` / `/flo -sd`). Use before `gh pr create` when the change must be proven to work, not just tested in passing. Verifies only — it does not fix; on FAIL it reports the gaps and stops.
+arguments: "[issue-number | spec-slug]  (defaults to the current branch's issue/spec)"
+---
+
+# /verify — Verify Before Done
+
+Prove the current change **actually does what it was supposed to** before it ships. `/verify` is the end-to-end completion check for moflo's SDD cycle: it takes the change's **acceptance criteria**, exercises the change against each one with concrete evidence, and returns a per-criterion verdict. It is the action that makes the [verify-before-done gate](../../guidance/moflo-sdd.md) mean something — running it is what unblocks `gh pr create` when `gates.verify_before_done` is on.
+
+**Arguments:** $ARGUMENTS
+
+`/verify` **verifies, it does not fix.** If a criterion fails, it reports the gap and stops — the caller (you, or the `/flo` flow) decides what to do. This separation is deliberate: a checker that also patches can rationalise its way to green.
+
+## What satisfies the gate
+
+Invoking this skill (name `verify`) trips the `record-verify-run` hook, which flips the `verifyRun` state the `check-before-done` gate reads. **Only `/verify` satisfies it** — `/ward` and `/quicken` are targeted audits, not an end-to-end verification. A source edit *after* verifying invalidates the result (the edit gate resets `verifyRun`), so run `/verify` as the last step before the PR.
+
+## Step 0 — Memory first
+
+Search memory before reading files, same as any task (satisfies `memory_first`, surfaces prior verify runs for this area):
+
+```
+mcp__moflo__memory_search { query: "verify <feature keywords>", namespace: "learnings" }
+```
+
+## Step 1 — Locate the acceptance criteria
+
+Resolve the criteria to check against, in priority order — **stop at the first that exists**:
+
+| Source | How to find it | When |
+|--------|----------------|------|
+| SDD **plan** | `flo sdd list` → the slug for this branch → read its `plan.md` "Acceptance Criteria" | `--sdd` runs |
+| SDD **spec** | same slug → `spec.md` "Acceptance Criteria" | spec authored, no plan criteria |
+| **Ticket** | `gh issue view <n>` → the `## Acceptance Criteria` section | plain `-v` run, no spec |
+| **Inferred** | derive 2–4 checkable criteria from the diff + PR intent, and say so | nothing above exists |
+
+Never hand-write the spec path — get it from `flo sdd` (Rule #1: the CLI builds every path with `path.join`). If an explicit `<issue-number | spec-slug>` argument was passed, use it directly.
+
+## Step 2 — Map each criterion to a concrete check
+
+For every acceptance criterion, pick the **cheapest evidence that actually proves it**:
+
+| Criterion shape | Verification action |
+|-----------------|---------------------|
+| Logic / behavior / bug-fix | A passing test that **specifically** exercises it — reuse the suite run already done this session (see below); run only a missing/targeted test |
+| Build / types / packaging | The project's build or typecheck command — reuse if already run since the last edit |
+| Integration / e2e | The project's e2e or integration runner |
+| User-facing / UI / CLI output | Run the real thing — use `/run` to launch the app/CLI and observe the actual output (a screenshot or captured stdout is the evidence) |
+| Config / docs / non-code | Inspect the artifact directly and confirm it says what the criterion requires |
+
+**Reuse fresh evidence — do not re-run what this session already ran.** This is the key to avoiding a **double verify**. If the tests/build already ran green this session with no source edit since — which is exactly the case when `/flo` invokes `/verify` right after its Tests phase — that run **is** the evidence: cite it, don't execute it again. `/verify`'s job is the *mapping* (which criterion is proven by which existing result) and *gap-finding* (criteria no check covers), **not** re-running the suite. Only execute a check whose evidence doesn't already exist this session.
+
+**Discover the commands from the project — never assume.** When you *do* need to run something (a criterion nothing covered yet), read `package.json` scripts / `Makefile` / language toolchain and use what the repo already uses (`npm/yarn/pnpm test`, `vitest`, `jest`, `pytest`, `cargo test`, `go test`, …). Cross-platform (Rule #1): invoke the project's own scripts, don't shell out to `bash`-only constructs.
+
+## Step 3 — Execute the gaps and gather evidence
+
+Run **only the checks whose evidence doesn't already exist** this session; for everything else, cite the run that already happened. Capture, per criterion, the **specific** evidence: the passing test name, the build exit, the observed output. "The suite passed" is not evidence for a criterion unless a test actually exercises *that* criterion — if none does, that is a **gap**, not a pass (consider `/ward` to fill it, in a separate step). The distinction from a plain test run is the whole point: tests prove the code works; `/verify` proves the change did **what the ticket asked**.
+
+## Step 4 — Verdict
+
+Emit a per-criterion table. **PASS only when every criterion has affirmative evidence.** Any criterion with no covering check is `UNVERIFIED`, which counts as **not passing**.
+
+```
+| # | Acceptance criterion | Evidence | Verdict |
+|---|----------------------|----------|---------|
+| 1 | <criterion>          | <test/output/observation> | ✅ PASS / ❌ FAIL / ⚠️ UNVERIFIED |
+```
+
+Overall verdict is PASS iff no row is FAIL or UNVERIFIED.
+
+## Step 5 — Record the outcome to memory
+
+Always store the result (feeds routing/learning and the SDD trail):
+
+```
+mcp__moflo__memory_store {
+  namespace: "learnings",
+  key: "verify:<slug-or-issue>",
+  value: "<overall PASS/FAIL> — per-criterion: <criterion → evidence → verdict>; commit <sha>",
+  tags: ["verify", "sdd"]
+}
+```
+
+## Step 6 — Report
+
+One concise summary: overall verdict, the per-criterion table, and — on FAIL/UNVERIFIED — exactly which criteria are unproven and what evidence is missing. Do **not** open the PR or edit code from here; hand the verdict back to the caller.
+
+## See Also
+
+- `.claude/guidance/moflo-sdd.md` — the SDD cycle and the verify-before-done gate this skill satisfies
+- `.claude/skills/fl/sdd.md` — how `/flo` invokes `/verify` at the verify step
+- `.claude/skills/ward/SKILL.md` — fills coverage gaps `/verify` surfaces (audit, not a completion gate)
+- `.claude/skills/run/SKILL.md` — launch the real app/CLI for user-facing criteria

package/README.md

@@ -76,7 +76,7 @@ MoFlo makes deliberate choices so you don't have to:
 | **Learned Routing** | Routes tasks to the right agent type. Learns from outcomes — gets better over time. |
 | **Spell Engine** | Define multi-step automations as YAML — shell commands, agent spawns, conditionals, loops, memory ops. [Full documentation →](docs/SPELLS.md) |
 | **`/flo` Skill** | Execute GitHub issues through a full process: research → enhance → implement → test → simplify → PR. (Also available as `/fl`.) |
-| **Spec-Driven Development** | `/flo -sd` runs a spec → plan → implement → verify cycle with reviewable, memory-indexed artifacts; `/flo -v` enforces verify-before-done on its own. Both opt-in. [Details →](#spec-driven-development-sdd) |
+| **Spec-Driven Development** | `/flo -sd` runs a spec → plan → implement → verify cycle with memory-indexed artifacts (local by default; set `sdd.specs_dir` to a tracked path to review them in PRs). The spec/plan ceremony is opt-in; verify-before-done runs by **default** (opt out with `--no-verify`). [Details →](#spec-driven-development-sdd) |
 | **Context Tracking** | Monitors context window usage (FRESH → MODERATE → DEPLETED → CRITICAL) and advises accordingly. |
 | **Cross-Platform** | Works on macOS, Linux, and Windows. |
 
@@ -293,7 +293,7 @@ MoFlo installs Claude Code hooks that run on every tool call. Together, these ga
 | **TaskCreate-first** | Claude must call TaskCreate before spawning sub-agents via the Task tool | Before every Task (agent spawn) call | Ensures every piece of delegated work is tracked. Prevents runaway agent proliferation where Claude spawns agents without a clear plan. |
 | **Context tracking** | Tracks conversation length and warns about context depletion | On every user prompt (UserPromptSubmit hook) | As conversations grow, AI quality degrades. MoFlo tracks interaction count and assigns a bracket (FRESH → MODERATE → DEPLETED → CRITICAL), advising Claude to checkpoint progress or start a fresh session before quality drops. |
 | **Routing** | Analyzes each prompt and recommends the optimal agent type and model tier | On every user prompt (UserPromptSubmit hook) | Saves cost by suggesting haiku for simple tasks, sonnet for moderate ones, opus for complex reasoning — without you having to think about model selection. |
-| **Verify-before-done** *(opt-in)* | Claude must verify the change end-to-end (native `/verify`) before `gh pr create` | Before `gh pr create`, only when `gates.verify_before_done: true` | Enforces "prove it works before done." Off by default, so it never surprises an existing install. Pairs with the [Spec-Driven Development](#spec-driven-development-sdd) cycle, which gives verification its acceptance criteria. |
+| **Verify-before-done** *(on by default)* | Claude must verify the change end-to-end (the `/verify` skill) before `gh pr create` | Before `gh pr create` (docs-only diffs exempt) | Enforces "prove it works before done." On by default since #1294 (`/flo` delegates to `/verify` and reuses its test run — no double verify). Opt out with `verify_before_done: false` or `--no-verify`. Pairs with the [Spec-Driven Development](#spec-driven-development-sdd) cycle, which gives verification its acceptance criteria. |
 
 ### Smart classification
 
@@ -322,7 +322,7 @@ gates:
   memory_first: true          # Set to false to disable memory-first enforcement
   task_create_first: true     # Set to false to disable TaskCreate enforcement
   context_tracking: true      # Set to false to disable context bracket warnings
-  verify_before_done: false   # Set to true to require /verify before `gh pr create`
+  verify_before_done: true    # On by default (#1294); set false to skip /verify before `gh pr create`
 ```
 
 You can also disable individual hooks in `.claude/settings.json` by removing the corresponding hook entries.
@@ -344,24 +344,29 @@ Inside Claude Code, the `/flo` (or `/fl`) slash command drives GitHub issue exec
 /flo -m <issue>               # Auto-merge the PR once required checks pass
 ```
 
-Flags compose: e.g. `/flo -sd -m <issue>` runs the SDD cycle and auto-merges. Each opt-in modifier has a `--no-*` form (`--no-sdd`, `--no-verify`, `--no-merge`) to override a `moflo.yaml` default for a single run. For full options and details, type `/flo` with no arguments — Claude Code will display the complete skill documentation. Also available as `/fl`.
+Flags compose: e.g. `/flo -sd -m <issue>` runs the SDD cycle and auto-merges. Each modifier has a `--no-*` form (`--no-sdd`, `--no-verify`, `--no-merge`) to override a `moflo.yaml` default for a single run — including `--no-verify`, since verify-before-done is on by default. For full options and details, type `/flo` with no arguments — Claude Code will display the complete skill documentation. Also available as `/fl`.
 
 ### Spec-Driven Development (SDD)
 
-`/flo` can run the full **spec → plan → (review) → implement → verify** cycle — the 2026 agentic-coding pattern — with two independent, opt-in modifiers:
+`/flo` can run the full **spec → plan → (review) → implement → verify** cycle — the 2026 agentic-coding pattern — with two independent modifiers (the spec/plan front-half is opt-in; the verify back-half is on by default):
 
-- **`-sd` / `--sdd`** — author a **spec** (the *what* + acceptance criteria) and a **plan** (the *steps*), with a review checkpoint between each stage, before implementing. Artifacts persist as reviewable Markdown at `.moflo/specs/<slug>/{spec,plan}.md` and are indexed into memory, so prior specs are searchable across sessions. Implies `--verify`.
-- **`-v` / `--verify`** — the verify half on its own: a normal run plus the [verify-before-done gate](#the-gate-system). Separable from SDD so you can enforce "prove it works" without the spec ceremony.
+- **`-sd` / `--sdd`** *(opt-in)* — author a **spec** (the *what* + acceptance criteria) and a **plan** (the *steps*), with a review checkpoint between each stage, before implementing. Artifacts persist as Markdown at `<specs_dir>/<slug>/{spec,plan}.md` (default `.moflo/specs`) and are indexed into memory, so prior specs are searchable across sessions. Implies `--verify`.
+- **`-v` / `--verify`** *(on by default)* — the verify half: a normal run plus the [verify-before-done gate](#the-gate-system). It runs the **`/verify`** skill, which exercises the change end-to-end against its acceptance criteria and reports a per-criterion PASS/FAIL, reusing the run's own tests (no double verify). Runs by default; `--no-verify` skips it. Separable from SDD, so you get "prove it works" without the spec ceremony.
 
 Both compose with execution mode (`-n`/`-s`/`-h`) and `--worktree`, and default from `moflo.yaml`:
 
 ```yaml
 sdd:
   default: false              # true → every /flo run uses the SDD cycle unless --no-sdd
+  specs_dir: .moflo/specs     # where spec/plan artifacts are written (see below)
 gates:
-  verify_before_done: false   # true → require /verify before `gh pr create` unless --no-verify
+  verify_before_done: true    # on by default (#1294); false → skip /verify unless -v. Per-run: --no-verify
 ```
 
+On upgrade, consumers with no `verify_before_done` key start enforcing verify-before-done; an explicit value is preserved. Docs-only diffs are exempt, so a pure-docs PR is never blocked.
+
+**Where specs live — and making them reviewable.** By default spec/plan artifacts are written under `.moflo/specs`, which `flo init` gitignores — so they stay **local and never bloat source control**. If you want specs to appear in PRs and be reviewed like any other file, point `sdd.specs_dir` at a **tracked** path (e.g. `docs/specs` or `.specs`) and commit them normally; no gitignore surgery required. The path is written with `/` and resolved cross-platform. If you set it to a directory already covered by `guidance.directories`, moflo indexes the specs once (as guidance) rather than twice.
+
 `--sdd` implies `--verify` (a spec/plan without an enforced verify step drifts). Manage artifacts directly with `flo sdd` (`spec`, `plan`, `review`, `check`, `list`), and start from a fuzzy idea with **`/commune`**, which can hand its synthesized spec straight into the SDD spine. Wiring status is reported by **`/healer`** (and `/eldar`).
 
 ### Auto-merge
@@ -907,7 +912,7 @@ gates:
   memory_first: true                 # Must search memory before file exploration
   task_create_first: true            # Must TaskCreate before Agent tool
   context_tracking: true             # Track context window depletion
-  verify_before_done: false          # Require /verify before `gh pr create` (unless --no-verify)
+  verify_before_done: true           # On by default (#1294); /verify before `gh pr create` (unless --no-verify). false to disable
 
 sdd:
   default: false                     # true → every /flo run uses the spec→plan→implement→verify cycle unless --no-sdd

package/bin/gate.cjs

@@ -60,10 +60,11 @@ function writeState(s) {
 
 // Load moflo.yaml gate config (defaults: all enabled)
 function loadGateConfig() {
-  // Note: verify_before_done defaults to FALSE (opt-in) — the only gate that
-  // ships off, so existing consumers see zero behavior change on upgrade
-  // (Story #1274, Epic #1269). Every other gate is opt-out (default true).
-  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: false };
+  // 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 };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -75,8 +76,8 @@ function loadGateConfig() {
       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-in: enable only when explicitly set true.
-      if (/verify_before_done:\s*true/i.test(content)) defaults.verify_before_done = true;
+      // 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;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -763,12 +764,13 @@ switch (command) {
     process.exit(2);
   }
   case 'check-before-done': {
-    // Story #1274 (Epic #1269). Verify-before-done: block `gh pr create` until
-    // the change has been verified end-to-end (native /verify skill) against the
-    // plan's acceptance criteria. OFF by default — only enforced when the
-    // consumer opts in via moflo.yaml `gates: verify_before_done: true`, so
-    // existing installs see zero change on upgrade. Same trigger + no-source
-    // exemption as check-before-pr, so the two gates compose on one command.
+    // 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;

package/bin/index-guidance.mjs

@@ -23,7 +23,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync, statSync, mkdirSync, writeFileSync } from 'fs';
-import { resolve, relative, dirname, basename, extname } from 'path';
+import { resolve, relative, dirname, basename, extname, sep } from 'path';
 import { fileURLToPath } from 'url';
 import { memoryDbPath, findProjectRoot } from './lib/moflo-paths.mjs';
 import { openBackend } from './lib/get-backend.mjs';
@@ -51,12 +51,25 @@ function loadGuidanceDirs() {
 
   // 1. Read moflo.yaml / moflo.config.json for user-configured directories
   let configDirs = null;
+  // #1294 — configurable SDD spec/plan location (default .moflo/specs). Parsed
+  // here alongside the guidance dirs so step 6 can honor it and skip a
+  // double-index when it sits inside a guidance dir.
+  let specsDirConfig = null;
   const yamlPath = resolve(projectRoot, 'moflo.yaml');
   const jsonPath = resolve(projectRoot, 'moflo.config.json');
 
   if (existsSync(yamlPath)) {
     try {
       const content = readFileSync(yamlPath, 'utf-8');
+      // sdd.specs_dir (snake_case or camelCase, quoted or bare). Two-step:
+      // isolate the top-level `sdd:` block (up to the next column-0 key, blank
+      // lines included — a naive contiguous-line regex would break on natural
+      // whitespace between keys, #1294 review), then find specs_dir within it.
+      const sddBlock = content.match(/(?:^|\n)[ \t]*sdd:[ \t]*\n([\s\S]*?)(?=\n\S|$)/);
+      if (sddBlock) {
+        const m = sddBlock[1].match(/(?:^|\n)[ \t]+specs_?[dD]ir:[ \t]*["']?([^"'\n#]+)/);
+        if (m && m[1].trim()) specsDirConfig = m[1].trim();
+      }
       // Simple YAML array extraction — avoids needing js-yaml at runtime
       // Matches:  guidance:\n    directories:\n      - .claude/guidance\n      - docs/guides
       const guidanceBlock = content.match(/guidance:\s*\n\s+directories:\s*\n((?:\s+-\s+.+\n?)+)/);
@@ -73,6 +86,8 @@ function loadGuidanceDirs() {
       if (raw.guidance?.directories && Array.isArray(raw.guidance.directories)) {
         configDirs = raw.guidance.directories;
       }
+      const sd = raw.sdd?.specs_dir ?? raw.sdd?.specsDir;
+      if (typeof sd === 'string' && sd.trim()) specsDirConfig = sd.trim();
     } catch { /* ignore parse errors */ }
   }
 
@@ -133,12 +148,32 @@ function loadGuidanceDirs() {
     dirs.push({ path: bundledSkillsDir, prefix: 'skill-bundled', fileFilter: ['SKILL.md'], kind: 'skill', absolute: true });
   }
 
-  // 6. SDD spec/plan artifacts (Epic #1269) — index .moflo/specs/<slug>/{spec,plan}.md
+  // 6. SDD spec/plan artifacts (Epic #1269) — index <specs_dir>/<slug>/{spec,plan}.md
   //    so prior specs/plans are searchable across sessions. kind: 'spec' keys each
   //    file by <slug>-<spec|plan> to avoid collisions between per-slug spec.md files.
-  const projectSpecsDir = resolve(projectRoot, '.moflo/specs');
-  if (existsSync(projectSpecsDir)) {
-    dirs.push({ path: '.moflo/specs', prefix: 'spec', fileFilter: ['spec.md', 'plan.md'], kind: 'spec' });
+  //    #1294 — the location is configurable (default .moflo/specs). Cross-platform
+  //    (Rule #1): split the /-written value and re-join, never hardcode a separator.
+  //    Validation MUST match specsRoot() in src/cli/sdd/artifacts.ts exactly, or
+  //    the indexer and the CLI would disagree on where specs live: reject
+  //    absolute / drive-letter / parent-escape values and fall back to the default.
+  const rawSpecs = specsDirConfig || '.moflo/specs';
+  let specsRel = rawSpecs.split(/[\\/]+/).filter(Boolean);
+  const specsEscapes = specsRel.length === 0
+    || specsRel.includes('..')
+    || /^([a-zA-Z]:|~)$/.test(specsRel[0])
+    || rawSpecs.startsWith('/')
+    || rawSpecs.startsWith('\\');
+  if (specsEscapes) specsRel = ['.moflo', 'specs'];
+  const projectSpecsDir = resolve(projectRoot, ...specsRel);
+  // Double-index guard: if specs_dir sits inside a guidance dir, the guidance
+  // scan (step 1) already indexes those .md files — skip the 'spec' entry so
+  // they aren't indexed twice under two prefixes.
+  const insideGuidance = userDirs.some(d => {
+    const gd = resolve(projectRoot, ...d.split(/[\\/]+/).filter(Boolean));
+    return projectSpecsDir === gd || projectSpecsDir.startsWith(gd + sep);
+  });
+  if (existsSync(projectSpecsDir) && !insideGuidance) {
+    dirs.push({ path: specsRel.join('/'), prefix: 'spec', fileFilter: ['spec.md', 'plan.md'], kind: 'spec' });
   }
 
   return dirs;

package/bin/lib/yaml-upgrader.mjs

@@ -11,6 +11,8 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { dirname } from 'path';
+import { hasMigrationRun, markMigrationDone } from './migrations.mjs';
 
 /**
  * Registry of top-level config sections that moflo ships with default blocks.
@@ -93,6 +95,70 @@ export const RENAMED_SECTIONS = [
   { from: 'auto_reflect', to: 'auto_meditate' },
 ];
 
+/**
+ * Registry of one-time in-place VALUE migrations — for when the polarity of a
+ * shipped default changes and we want existing users carried onto the new
+ * default. Unlike a rename or an appended block, these rewrite an existing
+ * value line, so each entry is scoped to a narrowly-matched, AUTO-GENERATED
+ * default and never a value the user deliberately hand-set. Each is idempotent:
+ * once applied, the line no longer matches its own `match`.
+ */
+export const VALUE_MIGRATIONS = [
+  {
+    // #1294 — verify-before-done flipped to default-ON. `flo init` briefly (from
+    // Epic #1269 until #1294) wrote `verify_before_done: false` into the template,
+    // so a project created in that window is pinned OFF and would silently skip
+    // verification on upgrade. Flip that auto-written default to true. We match it
+    // by its generated "opt-in" comment: a hand-typed bare `false` (no such
+    // comment) is a deliberate opt-out and is LEFT UNTOUCHED. Erring toward more
+    // verification is safe (a spurious extra gate is a mild `--no-verify` away);
+    // dropping verification silently is the dangerous direction.
+    id: 'verify_before_done-default-on-1294',
+    // Cross-platform (Rule #1, checklist #4): match line CONTENT only with
+    // [^\r\n] and do NOT anchor on `$` — so on a CRLF `moflo.yaml` the trailing
+    // \r\n is left intact by the replace and we never mix line endings.
+    match: /^([ \t]*)verify_before_done:[ \t]*false\b[^\r\n]*\bopt-in\b[^\r\n]*/m,
+    replace: (_m, indent) =>
+      `${indent}verify_before_done: true    # Epic #1269/#1294: on by default; opt out with false or per-run --no-verify`,
+  },
+];
+
+/**
+ * Apply registered one-time VALUE migrations to the yaml file in place.
+ *
+ * **Runs each migration at most once, ever** — gated on the `.moflo/migrations.json`
+ * ledger (`hasMigrationRun`/`markMigrationDone`). This is the load-bearing
+ * guarantee: after the first attempt the id is recorded permanently, so if the
+ * user later flips the value back (e.g. turns verify off again), a future upgrade
+ * will **not** silently re-apply the migration and overwrite their choice. The
+ * ledger is marked whether or not the line actually matched, so a project that
+ * was already on the new value — or that had a deliberate hand-set value we chose
+ * not to touch — is likewise never reconsidered.
+ *
+ * Returns the ids that actually rewrote a line (empty if nothing changed).
+ */
+export function applyValueMigrations(yamlPath, registry = VALUE_MIGRATIONS) {
+  if (!existsSync(yamlPath)) return [];
+  const projectRoot = dirname(yamlPath);
+  let text = readFileSync(yamlPath, 'utf-8');
+  let changed = false;
+  const applied = [];
+  for (const mig of registry) {
+    if (hasMigrationRun(projectRoot, mig.id)) continue; // already attempted once — never again
+    const flipped = mig.match.test(text);
+    if (flipped) {
+      text = text.replace(mig.match, mig.replace);
+      changed = true;
+      applied.push(mig.id);
+    }
+    // Record the attempt regardless of whether it matched, so this migration is
+    // considered exactly once for this project and can't fire on a later opt-out.
+    markMigrationDone(projectRoot, mig.id, { flipped });
+  }
+  if (changed) writeFileSync(yamlPath, text, 'utf-8');
+  return applied;
+}
+
 /**
  * Rename any registered top-level sections present under their OLD key to the
  * NEW key, in place. Only the top-level key line is rewritten; the block body
@@ -136,7 +202,10 @@ export function missingSections(yamlText, registry = REQUIRED_SECTIONS) {
  * Append any missing registered sections to the yaml file at `yamlPath`.
  *
  * - Idempotent: sections already present are left alone.
- * - Non-destructive: user values are never read, parsed, or rewritten.
+ * - Appended values are never re-touched once present. The only in-place edits
+ *   are the registered key renames (RENAMED_SECTIONS) and one-time value
+ *   migrations (VALUE_MIGRATIONS), each narrowly scoped so a user's deliberate
+ *   settings are preserved.
  * - Returns the list of section keys that were appended (empty if no change).
  */
 export function ensureYamlSections(yamlPath, registry = REQUIRED_SECTIONS) {
@@ -147,6 +216,10 @@ export function ensureYamlSections(yamlPath, registry = REQUIRED_SECTIONS) {
   // not re-appended as a fresh default block alongside the stale old one.
   renameYamlSections(yamlPath);
 
+  // One-time value migrations (e.g. #1294 verify-before-done default flip). Also
+  // in place, also idempotent; scoped to auto-written defaults, never user values.
+  applyValueMigrations(yamlPath);
+
   const original = readFileSync(yamlPath, 'utf-8');
   const toAppend = registry.filter((entry) => !hasTopLevelSection(original, entry.key));
   if (toAppend.length === 0) return [];

package/dist/src/cli/config/moflo-config.js

@@ -35,7 +35,7 @@ const DEFAULT_CONFIG = {
         memory_first: true,
         task_create_first: true,
         context_tracking: true,
-        verify_before_done: false,
+        verify_before_done: true,
     },
     auto_index: {
         guidance: true,
@@ -104,6 +104,7 @@ const DEFAULT_CONFIG = {
     },
     sdd: {
         default: false,
+        specs_dir: '.moflo/specs',
     },
     merge: {
         auto: false,
@@ -321,6 +322,13 @@ function mergeConfig(raw, root) {
         },
         sdd: {
             default: raw.sdd?.default ?? DEFAULT_CONFIG.sdd.default,
+            // Accept snake_case (`specs_dir`) or camelCase (`specsDir`). A blank/empty
+            // value falls back to the default so a consumer can't accidentally point
+            // specs at the project root with `specs_dir: ""`.
+            specs_dir: (typeof (raw.sdd?.specs_dir ?? raw.sdd?.specsDir) === 'string'
+                && (raw.sdd?.specs_dir ?? raw.sdd?.specsDir).trim())
+                ? (raw.sdd?.specs_dir ?? raw.sdd?.specsDir).trim()
+                : DEFAULT_CONFIG.sdd.specs_dir,
         },
         merge: {
             auto: raw.merge?.auto ?? DEFAULT_CONFIG.merge.auto,
@@ -460,7 +468,7 @@ gates:
   memory_first: true          # Search memory before Glob/Grep
   task_create_first: true     # TaskCreate before Agent tool
   context_tracking: true      # Track context bracket (FRESH/MODERATE/DEPLETED/CRITICAL)
-  verify_before_done: false   # Epic #1269: require /verify before 'gh pr create' (opt-in)
+  verify_before_done: true    # Epic #1269/#1294: run /verify before 'gh pr create'. On by default; opt out with false or per-run --no-verify
 
 # Auto-index on session start
 auto_index:
@@ -564,6 +572,9 @@ epic:
 # Spec-Driven Development (Epic #1269)
 sdd:
   default: false                 # true = every /flo run uses spec->plan->implement->verify unless --no-sdd
+  specs_dir: .moflo/specs        # where flo sdd writes spec/plan artifacts. Default is local + gitignored
+                                 # (no source-control bloat). Set a tracked path (e.g. docs/specs) to make
+                                 # specs reviewable in PRs. Written with / — resolved cross-platform (#1294).
 
 # Auto-merge the PR at the end of a full /flo run once preconditions are met (#1285).
 # Opt-in; default false. Override per-run with --merge / --no-merge.

package/dist/src/cli/init/executor.js

@@ -47,6 +47,7 @@ export const SKILLS_MAP = {
         'perf-audit', // alias for quicken (pointer skill); installed alongside it
         'ward', // ad-hoc test-gap audit (replaced the always-on `testgaps` daemon worker)
         'test-gaps', // alias for ward (pointer skill); installed alongside it
+        'verify', // SDD verify-before-done: exercises the change against acceptance criteria (#1294)
     ],
     memory: [
         'memory-patterns',

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

@@ -255,7 +255,7 @@ 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, verify_before_done: false };
+  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 };
   try {
     var yamlPath = path.join(PROJECT_DIR, 'moflo.yaml');
     if (fs.existsSync(yamlPath)) {
@@ -267,7 +267,8 @@ function loadGateConfig() {
       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;
-      if (/verify_before_done:\\s*true/i.test(content)) defaults.verify_before_done = true;
+      // Opt-out: on by default (#1294); disable only when explicitly set false.
+      if (/verify_before_done:\\s*false/i.test(content)) defaults.verify_before_done = false;
     }
   } catch (e) { /* use defaults */ }
   return defaults;
@@ -618,9 +619,9 @@ switch (command) {
     process.exit(2);
   }
   case 'check-before-done': {
-    // Story #1274 (Epic #1269) — verify-before-done. OFF unless the consumer
-    // opts in via moflo.yaml gates.verify_before_done: true, so existing installs
-    // see zero change. Same 'gh pr create' trigger as check-before-pr. This
+    // Story #1274 (Epic #1269) + #1294 — verify-before-done. ON by default
+    // (#1294); disable via moflo.yaml gates.verify_before_done: false or per-run
+    // --no-verify. Same 'gh pr create' trigger as check-before-pr. This
     // template variant intentionally omits the no-source (docs-only) exemption to
     // stay consistent with THIS file's simpler check-before-pr; the full exemption
     // lives in the source bin/gate.cjs that the launcher syncs over this fallback.

package/dist/src/cli/init/moflo-yaml-template.js

@@ -206,7 +206,7 @@ gates:
   memory_first: ${gates}
   task_create_first: ${gates}
   context_tracking: ${gates}
-  verify_before_done: false   # Epic #1269: require /verify before 'gh pr create' (opt-in; independent of the toggle above)
+  verify_before_done: true    # Epic #1269/#1294: run /verify before 'gh pr create'. On by default; opt out with false or per-run --no-verify
 
 # Auto-index on session start
 auto_index:

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

@@ -250,9 +250,9 @@ function generateHooksConfig(config) {
                 hooks: [
                     { type: 'command', command: gateHookCmd('check-dangerous-command'), timeout: 2000 },
                     { type: 'command', command: gateHookCmd('check-before-pr'), timeout: 2000 },
-                    // Story #1274 (Epic #1269) — verify-before-done. Inert unless the
-                    // consumer sets `gates: verify_before_done: true`; gates `gh pr create`
-                    // the same as check-before-pr, so both live on this Bash/PowerShell block.
+                    // Story #1274 (Epic #1269) + #1294 — verify-before-done. On by default
+                    // (#1294); disable with `gates: verify_before_done: false`. Gates
+                    // `gh pr create` like check-before-pr, so both live on this Bash/PowerShell block.
                     { type: 'command', command: gateHookCmd('check-before-done'), timeout: 2000 },
                     // #1132 — moved from PostToolUse so process.exit(2) actually blocks
                     // read-like shell commands that bypass the Read/Glob/Grep gates.

package/dist/src/cli/sdd/artifacts.js

@@ -20,13 +20,34 @@
  */
 import { join } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync, } from 'node:fs';
+import { loadMofloConfig } from '../config/moflo-config.js';
 export const SDD_STATUSES = ['draft', 'reviewed'];
 // ============================================================================
 // Paths — all via path.join (Rule #1)
 // ============================================================================
-/** Root directory holding every spec slug: `<projectRoot>/.moflo/specs`. */
+/**
+ * Root directory holding every spec slug. Defaults to `<projectRoot>/.moflo/specs`
+ * but is configurable via `moflo.yaml` `sdd.specs_dir` (#1294) — point it at a
+ * tracked path (e.g. `docs/specs`) to make specs reviewable in PRs.
+ *
+ * Cross-platform (Rule #1): the configured value is a `/`-written relative path;
+ * we split on either separator and `path.join` each segment, so a Windows repo
+ * with `docs/specs` in yaml still resolves correctly and no separator is ever
+ * hardcoded. An absolute or `..`-escaping value falls back to the default.
+ */
 export function specsRoot(projectRoot) {
-    return join(projectRoot, '.moflo', 'specs');
+    const configured = loadMofloConfig(projectRoot).sdd.specs_dir;
+    const segments = configured.split(/[\\/]+/).filter(Boolean);
+    // Reject absolute paths and parent-directory escapes — specs live under the
+    // project root. Fall back to the default rather than resolving outside it.
+    const escapes = segments.length === 0
+        || segments.includes('..')
+        || /^([a-zA-Z]:|~)$/.test(segments[0])
+        || configured.startsWith('/')
+        || configured.startsWith('\\');
+    if (escapes)
+        return join(projectRoot, '.moflo', 'specs');
+    return join(projectRoot, ...segments);
 }
 /** Per-unit directory: `<projectRoot>/.moflo/specs/<slug>`. */
 export function specDir(projectRoot, slug) {

package/dist/src/cli/services/daemon-dashboard.js

@@ -1347,6 +1347,7 @@ const DASHBOARD_HTML = `<!DOCTYPE html>
       const cards =
         '<div class="grid">' +
         '<div class="stat-card"><div class="label">Total Sessions</div><div class="value">' + fmtCount(cs.totalSessions) + '</div></div>' +
+        '<div class="stat-card"><div class="label">Total Tokens</div><div class="value">' + fmtCount(lifeTotal) + '</div></div>' +
         '<div class="stat-card"><div class="label">Subagent Tokens</div><div class="value">' + fmtCount(subTotal) + '</div></div>' +
         '<div class="stat-card"><div class="label">Sessions w/ Errors</div><div class="value">' + fmtCount(cs.errorSessions) + '</div></div>' +
         '<div class="stat-card"><div class="label">Median Duration</div><div class="value">' + fmtDuration(cs.sessionDurationMs.median) + '</div></div>' +

package/dist/src/cli/services/hook-wiring.js

@@ -18,9 +18,9 @@ export const REQUIRED_HOOK_WIRING = [
     { event: 'PreToolUse', pattern: 'check-before-read' },
     { event: 'PreToolUse', pattern: 'check-dangerous-command' },
     { event: 'PreToolUse', pattern: 'check-before-pr' },
-    // Story #1274 (Epic #1269) — verify-before-done gate on `gh pr create`. Wired
-    // for every consumer so opting in via `gates: verify_before_done: true` takes
-    // effect without a re-init; inert (breaks immediately) while the toggle is off.
+    // Story #1274 (Epic #1269) + #1294 — verify-before-done gate on `gh pr create`.
+    // Wired for every consumer; on by default (#1294) so a default /flo run does the
+    // acceptance check. Disable with `gates: verify_before_done: false`.
     { event: 'PreToolUse', pattern: 'check-before-done' },
     // #931 — TaskCreate REMINDER + namespace hint emit only at Agent spawn now,
     // not on every prompt. Saves ~90 tokens × every prompt × every consumer.

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.11.10-rc.2';
+export const VERSION = '4.11.10-rc.4';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.11.10-rc.2",
+  "version": "4.11.10-rc.4",
   "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.1",
+    "moflo": "^4.11.10-rc.3",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"