moflo 4.12.3 → 4.12.4-rc.2

package/.claude/skills/spell-builder/connectors/http/README.md

@@ -1,22 +1,29 @@
 # `http` — HTTP Requests
 
-**Purpose:** Use this connector to make HTTP requests to any URL from within agent steps. Choose this when you need to call REST APIs, fetch data, or post payloads during spell execution.
+**Purpose:** Use this connector to make HTTP requests to any URL. Choose this when you need to call REST APIs, fetch data, or post payloads during spell execution.
 
 ## Usage
 
+Unlike `playwright`/`github-cli`/`local-outlook`, this connector has **no dedicated step type**. Reach it from a composite (YAML) step's `tool` action:
+
 ```yaml
-- id: fetch-status
-  type: agent
-  config:
-    prompt: |
-      Use the http connector to check the deployment status.
-      Call context.tools.execute('http', 'request', {
-        method: 'GET',
-        url: 'https://api.myapp.com/deploy/status',
-        headers: { 'Authorization': 'Bearer {credentials.API_TOKEN}' }
-      })
+name: fetch-status
+inputs:
+  token: { type: string }
+actions:
+  - tool: http
+    action: request
+    params:
+      method: GET
+      url: "https://api.myapp.com/deploy/status"
+      headers:
+        Authorization: "Bearer ${inputs.token}"
 ```
 
+…or from a custom step command via the Direct Usage API below. See `.claude/guidance/moflo-spell-custom-steps.md`.
+
+> Earlier revisions of this file showed an `agent` step calling `context.tools.execute(...)` from a prompt. The `agent` step type has never been executable.
+
 ## Actions
 
 | Action | Parameters | Description |

package/.claude/skills/spell-builder/connectors/local-outlook/README.md

@@ -4,18 +4,19 @@
 
 ## Usage
 
+From a spell, reach this connector through the `outlook` step, which delegates to it:
+
 ```yaml
 - id: check-for-invoices
-  type: agent
+  type: outlook
   config:
-    prompt: |
-      Use the local-outlook connector to search for recent invoices.
-      Call context.tools.execute('local-outlook', 'search', {
-        query: 'invoice from:billing@vendor.com',
-        limit: 5
-      })
+    action: search
+    query: "invoice from:billing@vendor.com"
+    limit: 5
 ```
 
+> Earlier revisions of this file showed an `agent` step calling `context.tools.execute(...)` from a prompt. The `agent` step type has never been executable — use the `outlook` step, a composite step's `tool` action, or a custom step command.
+
 ## Actions
 
 | Action | Parameters | Description |

package/.claude/skills/spell-builder/connectors/playwright/README.md

@@ -1,21 +1,23 @@
 # `playwright` — Browser Automation Connector
 
-**Purpose:** Use this connector for low-level browser automation via Playwright. Choose this when you need direct browser control from agent steps, or when building browser-based connectors like `local-outlook`.
+**Purpose:** Use this connector for low-level browser automation via Playwright. Choose this when you need direct browser control from a step command, or when building browser-based connectors like `local-outlook`.
 
 ## Usage
 
+From a spell, reach this connector through the `browser` step, which delegates to it:
+
 ```yaml
 - id: take-screenshot
-  type: agent
+  type: browser
   config:
-    prompt: |
-      Use the playwright connector to screenshot the homepage.
-      Call context.tools.execute('playwright', 'navigate', {
-        url: 'https://myapp.com'
-      })
-      Then call context.tools.execute('playwright', 'screenshot', {})
+    actions:
+      - action: navigate
+        url: "https://myapp.com"
+      - action: screenshot
 ```
 
+> Earlier revisions of this file showed an `agent` step calling `context.tools.execute(...)` from a prompt. The `agent` step type has never been executable — use the `browser` step, a composite step's `tool` action, or a custom step command.
+
 ## Actions
 
 | Action | Parameters | Description |

package/.claude/skills/spell-builder/steps/agent/README.md

@@ -1,36 +1,40 @@
-# `agent` — Spawn a Claude Subagent
+# `agent` — NOT EXECUTABLE
 
-**Purpose:** Use this step to delegate a task to a Claude subagent and capture its response. Choose this over `bash` when the task requires reasoning, code generation, or research rather than a deterministic command.
+**Purpose:** Document that this step type does not work, so it is not offered when authoring a spell. It is registered but has never spawned a subagent — moflo has no agent spawner in the spell runner. Casting it always fails.
 
-## Usage
+**Do not add `agent` steps to a spell.** Previously the step returned `success: true` with `result: "Agent task prepared: <type>"`, so spells containing one completed green and downstream steps consumed that string as though it were agent output. It now fails with an explanatory error instead.
+
+The type stays registered on purpose: removing it would turn a silently-useless step into a hard parse error for any existing spell YAML that contains one.
+
+## Use this instead
+
+Run the Claude CLI from a `bash` step:
 
 ```yaml
 - id: research
-  type: agent
+  type: bash
   config:
-    agentType: researcher
-    prompt: "Find all REST API endpoints in src/ and list their HTTP methods and paths"
-    model: claude-sonnet-5
-    background: false
+    command: 'claude -p "Find all REST API endpoints in src/ and list their HTTP methods and paths"'
+    timeout: 300000
 ```
 
-## Config
+This is what moflo's own shipped spells do — see `src/cli/spells/definitions/epic-auto-merge.yaml`.
+
+**Note on cost:** a `bash` step invoking `claude -p` has no spend ceiling, which matters most for daemon-scheduled spells. Set a `timeout` and prefer `failOnError: true`.
+
+## If you are reading an older spell
+
+| Old `agent` config | Replacement |
+|---|---|
+| `prompt` | the prompt text inside `claude -p "..."` |
+| `agentType` | no equivalent — describe the role in the prompt |
+| `background` | no equivalent — the bash step waits |
 
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `prompt` | Yes | — | Task prompt for the agent |
-| `agentType` | No | `coder` | Agent specialization: `researcher`, `coder`, `tester`, `reviewer` |
-| `model` | No | system default | Model override (e.g. `claude-sonnet-5`) |
-| `systemPrompt` | No | — | Custom system prompt replacing the default |
-| `background` | No | `false` | Run without waiting for the result |
+`model` and `systemPrompt` were documented here previously but were never implemented — the step's `configSchema` only ever accepted `prompt`, `agentType`, and `background`.
 
 ## Outputs
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `result` | string | Agent response text |
-| `agentType` | string | Agent type that was used |
-| `prompt` | string | Prompt that was sent |
+None. The step always fails. `agentType` and `prompt` are echoed in the failure data for diagnosis only; there is no `result`.
 
 ## Source
 

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

@@ -14,7 +14,9 @@ Prove the current change **actually does what it was supposed to** before it shi
 
 ## 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.
+Invoking this skill (name `verify`) trips the `record-verify-run` hook, which flips the `verifyRun` state. **That alone does not open the gate** (#1332): `check-before-done` also requires the recorded verdict to be `PASS`, which reaches it from the `metadata.overall` your Step 5 store writes. So a run returning FAIL leaves `gh pr create` blocked — as it should, since the change did not meet its criteria — and a run that stores prose without `metadata` counts as *no verdict* and blocks too.
+
+**Only `/verify` satisfies it** — `/ward` and `/quicken` are targeted audits, not an end-to-end verification. A source edit *after* verifying invalidates both the flag and the verdict, so run `/verify` as the last step before the PR.
 
 ## Step 0 — Memory first
 
@@ -71,17 +73,36 @@ 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):
+Always store the result (feeds routing/learning and the SDD trail). Store it **twice over**: the prose summary in `value`, and the Step 4 table itself — unflattened — in `metadata`.
 
 ```
 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"]
+  tags: ["verify", "sdd"],
+  metadata: {
+    type: "verify-record",
+    issue: "<slug-or-issue>",
+    commit: "<sha>",
+    overall: "PASS" | "FAIL" | "UNVERIFIED",
+    verifiedAt: "<ISO-8601>",
+    criteria: [
+      { id: 1, statement: "<criterion>", verdict: "PASS" | "FAIL" | "UNVERIFIED",
+        evidence: "<test name / observed output>", freshlyExecuted: true }
+    ]
+  }
 }
 ```
 
+**Why both.** `value` is what gets embedded for semantic search, so it stays prose — a JSON blob there would degrade every future `learnings` search. `metadata` is stored verbatim and not embedded, so the structure survives without that cost. `memory_retrieve` returns the parsed `metadata` object for non-chunk entries, which is what makes the record readable rather than write-only.
+
+**`freshlyExecuted` is required on every criterion, not optional.** Step 3 deliberately permits *citing* an earlier green run instead of re-executing. That is a sound cost optimisation, but it means evidence may be a citation rather than a fresh result — set `freshlyExecuted: false` when you cited. Without that flag a later reader silently inherits stale evidence and cannot tell a re-verified criterion from a re-cited one.
+
+**Never record an exit code.** Claude Code's `tool_response` for Bash carries `stdout`/`stderr` but **no exit status**, and PostToolUse does not fire at all when a command exits non-zero (#1322). `evidence` is therefore descriptive by necessity; a field named `exitCode` would be agent-narrated fiction, which is the problem this record exists to remove.
+
+`overall` MUST agree with the Step 4 rule — PASS iff no criterion is FAIL or UNVERIFIED. Record a FAIL as a FAIL; the store is the audit trail, and a verdict that only ever reads PASS is worth nothing.
+
 ## 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.

package/bin/gate-hook.mjs

@@ -32,14 +32,79 @@ if (hookContext.tool_name) env.TOOL_NAME = hookContext.tool_name;
 if (typeof hookContext.session_id === 'string' && hookContext.session_id) {
   env.HOOK_SESSION_ID = hookContext.session_id;
 }
+// #1332: structured tool inputs are forwarded as JSON, not dropped.
+//
+// This previously forwarded ONLY string values, so any object-valued input was
+// invisible to gate.cjs. That blocked the verify-before-done gate from reading
+// `/verify`'s per-criterion verdict, which #1328 stores in memory_store's
+// `metadata` — an object. Parsing the verdict out of the prose `value` string
+// instead would re-create exactly the free-text dependency #1328 removed.
+//
+// Cross-platform (Rule #1): Windows caps a single environment variable at
+// ~32KB and the whole block at ~32K wide chars, and exceeding it fails the
+// spawn rather than truncating. Newly-forwarded values are therefore skipped
+// when oversized, not clipped — a truncated JSON blob would parse as malformed
+// on the far side and read as a corrupt record rather than an absent one.
+// `metadata` is capped at 64KB by memory_store, so a real verdict never nears
+// this. STRING values keep their previous uncapped behaviour byte-for-byte:
+// gate.cjs reads TOOL_INPUT_command, and dropping an oversized heredoc command
+// would silently stop check-dangerous-command from firing on the exact inputs
+// most worth checking.
+var MAX_STRUCTURED_LEN = 16384;
 if (hookContext.tool_input && typeof hookContext.tool_input === 'object') {
   Object.keys(hookContext.tool_input).forEach(function(key) {
-    if (typeof hookContext.tool_input[key] === 'string') {
-      env['TOOL_INPUT_' + key] = hookContext.tool_input[key];
+    var raw = hookContext.tool_input[key];
+    if (typeof raw === 'string') {
+      env['TOOL_INPUT_' + key] = raw;
+      return;
     }
+    var val;
+    if (typeof raw === 'number' || typeof raw === 'boolean') {
+      val = String(raw);
+    } else if (raw && typeof raw === 'object') {
+      try { val = JSON.stringify(raw); } catch (e) { return; }
+    } else {
+      return; // null/undefined/function — nothing meaningful to forward
+    }
+    if (val.length > MAX_STRUCTURED_LEN) return;
+    env['TOOL_INPUT_' + key] = val;
   });
 }
 
+// #1322: forward the parts of tool_response that actually exist, so a gate can
+// observe an OUTCOME rather than only the intent it was handed.
+//
+// Claude Code's PostToolUse payload carries NO exit status — probed on v2.1.220,
+// tool_response for a Bash call is {stdout, stderr, interrupted, isImage,
+// noOutputExpected}. PostToolUse also does not fire at all when the command
+// exits non-zero, so the only case a gate can still be fooled by is an exit code
+// MASKED by a pipe or `|| true`, where the response looks clean. The runner's
+// own output is the sole remaining signal; record-test-run reads it in gate.cjs.
+//
+// Tail, not head. Every test runner prints its pass/fail summary LAST, so
+// clipping the front of a long log would discard the exact lines this exists to
+// read. Bounds are deliberately tight — Windows caps the whole environment
+// block at ~32K wide chars and fails the spawn rather than truncating, and
+// TOOL_INPUT_command is already forwarded uncapped alongside these.
+var MAX_RESPONSE_STDOUT = 4096;
+var MAX_RESPONSE_STDERR = 2048;
+function tailOf(value, max) {
+  return value.length > max ? value.slice(value.length - max) : value;
+}
+if (hookContext.tool_response && typeof hookContext.tool_response === 'object') {
+  var resp = hookContext.tool_response;
+  if (typeof resp.stdout === 'string' && resp.stdout) {
+    env.TOOL_RESPONSE_stdout = tailOf(resp.stdout, MAX_RESPONSE_STDOUT);
+  }
+  if (typeof resp.stderr === 'string' && resp.stderr) {
+    env.TOOL_RESPONSE_stderr = tailOf(resp.stderr, MAX_RESPONSE_STDERR);
+  }
+  // Boolean — the string-typed forwarding above would drop it silently.
+  if (typeof resp.interrupted === 'boolean') {
+    env.TOOL_RESPONSE_interrupted = String(resp.interrupted);
+  }
+}
+
 // Run gate.cjs with the enriched environment
 var projectDir = (env.CLAUDE_PROJECT_DIR || process.cwd()).replace(/^\/([a-z])\//i, '$1:/');
 var gateScript = resolve(projectDir, '.claude/helpers/gate.cjs');

package/bin/gate.cjs

@@ -139,6 +139,14 @@ var EXEMPT = ['.claude/', '.claude\\', 'CLAUDE.md', 'MEMORY.md', 'workflow-state
 // failures and "fixes" them with allow rules — which cannot override a hook
 // block at all (#1307 finding 5). Naming the gate makes the cause self-evident.
 var GATE_ORIGIN_NOTE = 'This is a moflo hook, not a Claude Code permission rule — allow-rules cannot override it.';
+
+// #1348 — the pre-PR gates are order-dependent and each block message named only
+// its own missing gate, so a caller could satisfy them one at a time forever:
+// /flo-simplify may edit code (which resets tests and verify), and /verify must
+// not, so simplify strictly precedes verify. Both blocking gates print this.
+// /verify's Step 5 memory_store carries the verdict AND stamps learnings, which
+// is why learnings has no separate step here.
+var ORDER_HINT = 'Order that satisfies all of them: tests green -> /flo-simplify (re-run tests if it edits) -> /verify -> its memory_store verdict -> gh pr create\n';
 var GATE_DISABLE_NOTE = 'Disable per-gate via moflo.yaml: gates: memory_first: false';
 
 // #1294 Finding 3 — reads/scans of EPHEMERAL files under the OS temp dir
@@ -498,6 +506,53 @@ function applyPromptStateReset(state, promptText) {
 // and language-native test commands. The bare-runner arm is anchored so that
 // `npm install jest`, `grep -r vitest src/`, and similar don't false-positive.
 var TEST_RUNNER_RE = /(?:^|[^a-z])(?:npm|yarn|pnpm|bun)\s+(?:run\s+)?(?:test|t)(?:[:\s]|$)|\b(?:npx|pnpx)\s+(?:vitest|jest|mocha|ava|tap|jasmine|pytest)\b|(?:^|;|&&|\|\|)\s*(?:vitest|jest|pytest|mocha|jasmine|tap|ava)\s|\b(?:cargo|go|deno|dotnet|mvn)\s+test\b|\bgradle\w*\s+test\b/i;
+// #1322 — failure markers in a test runner's own OUTPUT.
+//
+// This is deliberately not an exit-code check: Claude Code's PostToolUse payload
+// carries no exit status, and PostToolUse does not fire at all when a command
+// exits non-zero — so an unmasked red suite already leaves testsRun false, by
+// accident of the hook lifecycle rather than by design. What DOES defeat the
+// gate is a masked exit (`npm test | tail -20`, `npm test || true`,
+// `npm test 2>&1 | grep -i fail`): the pipeline exits 0, PostToolUse fires with
+// a clean-looking response, and a red suite credits the gate. Output is the only
+// signal left, and it is genuinely weaker than a status — see the ticket.
+//
+// Every arm matches a SUMMARY shape a runner emits, never a bare "fail", which
+// occurs constantly in ordinary passing test names ("returns null when the
+// lookup failed"). The count arm excludes an explicit zero so jest's
+// `0 failed, 12 passed` cannot self-block.
+//
+// The count arm's trailing lookahead is what keeps a GREEN run from blocking
+// itself. Mocha's default spec reporter prints every passing test name, so
+// `npm test | tail -20` on a green suite legitimately contains lines like
+// `✓ handles 2 failed retries`. A real summary is followed by a delimiter or a
+// line end (`3 failed | 40 passed`, `1 failed, 2 passed`, `1 failing`), never by
+// more prose — so a lowercase word after the count means it is a sentence, not a
+// tally. `tests`/`test` is exempted because `2 failed tests` is a real summary.
+// Same-line whitespace only: at a line end there is nothing to disqualify.
+var TEST_FAILURE_RE = new RegExp([
+  '\\b(?!0\\b)\\d+\\s+(?:tests?\\s+)?(?:failed|failing|failures?)\\b(?![^\\S\\n]+(?!tests?\\b)[a-z])', // vitest/jest/pytest/mocha counts
+  '^\\s*(?:FAIL|FAILED)\\b',                                          // vitest + jest per-file, pytest FAILED
+  '^\\s*---\\s*FAIL:',                                                // go test
+  '\\btest result:\\s*FAILED\\b',                                     // cargo
+  '^npm ERR!',                                                        // npm wrapper around any of the above
+].join('|'), 'im');
+
+/**
+ * #1322 — why a just-fired record-test-run must NOT be credited, or null.
+ *
+ * Absent output is not evidence of failure: a quiet green `npm test > /dev/null`
+ * and a silently-masked red one are indistinguishable, and treating the pair as
+ * failures would block every consumer who redirects test output. Absent means
+ * unknown, and unknown keeps the pre-#1322 behaviour.
+ */
+function detectTestFailure() {
+  if (process.env.TOOL_RESPONSE_interrupted === 'true') return 'the run was interrupted';
+  var out = (process.env.TOOL_RESPONSE_stdout || '') + '\n' + (process.env.TOOL_RESPONSE_stderr || '');
+  if (!out.trim()) return null;
+  var hit = out.match(TEST_FAILURE_RE);
+  return hit ? 'output reports "' + hit[0].trim().slice(0, 40) + '"' : null;
+}
 // Edits to these don't change runtime behaviour, so they don't invalidate prior test/simplify runs.
 // Lock files and .gitignore are tracked but inert; package.json/*.yaml ARE source — they reset.
 var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^|[\\\/])(CHANGELOG(?:\.md)?|\.env\.example|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/i;
@@ -508,7 +563,13 @@ var EDIT_RESET_SKIP_BOTH_RE = /\.(md|markdown|txt|rst|adoc|lock|gitignore)$|(?:^
 // they shouldn't reset testsRun/simplifyRun the way a real source edit does.
 // Trailing terminator includes `.` so the single-file template form
 // `.github/PULL_REQUEST_TEMPLATE.md` matches alongside the directory form.
-var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)/i;
+// #1348 — `.moflo/` joins them. It is moflo's own gitignored state directory
+// (daemon locks, memory db, SDD spec/plan artifacts), so nothing written there
+// can appear in the branch diff, and a spec edit invalidating the test run is
+// pure noise. Scoped to the reset only — deliberately NOT added to EXEMPT,
+// which would also un-gate reads of `.moflo/specs/**`, and those are indexed
+// guidance that memory-first should still route through a search.
+var EDIT_RESET_SKIP_PATH_RE = /(?:^|[\\\/])\.github[\\\/](?:workflows|ISSUE_TEMPLATE|PULL_REQUEST_TEMPLATE)(?:[\\\/.]|$)|(?:^|[\\\/])\.moflo[\\\/]/i;
 // Test files: invalidate the testing gate (tests are stale once test code changes)
 // but NOT the simplify gate — /simplify already reviewed the production code; touching
 // a test file or fixture doesn't expose new untested surface for code review (#908).
@@ -637,8 +698,11 @@ function getChangedFilesVsBase() {
 
 switch (command) {
   case 'check-before-agent': {
-    // Advisory only — agent spawning is never blocked.
-    // Memory-first enforcement happens at the scan/read gate layer.
+    // Mostly advisory. The TaskCreate + memory reminders below go to stdout and
+    // never block — their wording must not claim otherwise (#1326). The one
+    // exception is the #952 swarm/hive check at the bottom of this case, which
+    // writes to stderr and exits 2.
+    // Memory-first enforcement otherwise happens at the scan/read gate layer.
     // SubagentStart hook injects guidance directive into subagent context.
     //
     // #931 — TaskCreate REMINDER and the namespace hint moved here from
@@ -647,7 +711,7 @@ switch (command) {
     // consumer.
     var s = readState();
     if (config.task_create_first && !s.tasksCreated) {
-      process.stdout.write('REMINDER: Use TaskCreate before spawning agents. Task tool is blocked until then.\n');
+      process.stdout.write('REMINDER: Use TaskCreate before spawning agents.\n');
     }
     if (config.memory_first && s.memoryRequired && !s.memorySearched) {
       process.stdout.write('REMINDER: Search memory (mcp__moflo__memory_search) before spawning agents. On chunk hits, traverse via mcp__moflo__memory_get_neighbors — see .claude/guidance/moflo-memory-protocol.md\n');
@@ -809,8 +873,17 @@ switch (command) {
   case 'record-test-run': {
     var cmd = process.env.TOOL_INPUT_command || '';
     if (TEST_RUNNER_RE.test(cmd)) {
+      // #1322 — a red run is evidence AGAINST the gate, so it also clears a
+      // flag an earlier green run earned. Without the reset, `npm test` (green)
+      // followed by an edit and `npm test | tail -20` (red) would leave the
+      // gate satisfied by the stale first run — the edit resets testsRun, but
+      // the masked red run would immediately set it back.
+      var failure = detectTestFailure();
       var s = readState();
-      if (!s.testsRun) {
+      if (failure) {
+        if (s.testsRun) { s.testsRun = false; writeState(s); }
+        process.stderr.write('gate: record-test-run not credited — ' + failure + '\n');
+      } else if (!s.testsRun) {
         s.testsRun = true;
         writeState(s);
       }
@@ -865,30 +938,92 @@ switch (command) {
     // 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); }
+      // #1332: invoking /verify starts a verification; it does not conclude
+      // one. Clear any prior verdict so the run in progress cannot inherit the
+      // PASS from a previous issue and satisfy check-before-done on its own.
+      if (!s.verifyRun || s.verifyOutcome) {
+        s.verifyRun = true;
+        s.verifyOutcome = null;
+        writeState(s);
+      }
     } else if (vName) {
       process.stderr.write('gate: record-verify-run no-op — TOOL_INPUT_skill="' + vName + '" is not verify\n');
     }
     break;
   }
+  case 'record-verify-outcome': {
+    // #1332. Fires PostToolUse on mcp__moflo__memory_store. `record-verify-run`
+    // above proves a verification was ATTEMPTED; this proves how it ENDED.
+    //
+    // The verdict is read from the structured record #1328 made /verify write
+    // to memory_store's `metadata` — never parsed out of the prose `value`,
+    // which is precisely the free-text dependency #1328 removed. gate-hook.mjs
+    // forwards the object as JSON (see its MAX_STRUCTURED_LEN note).
+    var mKey = process.env.TOOL_INPUT_key || '';
+    if (mKey.indexOf('verify:') !== 0) break;
+    var rawMeta = process.env.TOOL_INPUT_metadata || '';
+    if (!rawMeta) {
+      process.stderr.write('gate: record-verify-outcome — "' + mKey + '" carries no metadata; verdict not recorded\n');
+      break;
+    }
+    var parsedMeta = null;
+    try { parsedMeta = JSON.parse(rawMeta); } catch (e) { parsedMeta = null; }
+    if (!parsedMeta || typeof parsedMeta !== 'object' || parsedMeta.type !== 'verify-record') break;
+    var overall = typeof parsedMeta.overall === 'string' ? parsedMeta.overall.toUpperCase() : '';
+    if (overall !== 'PASS' && overall !== 'FAIL' && overall !== 'UNVERIFIED') {
+      process.stderr.write('gate: record-verify-outcome — unrecognised overall="' + parsedMeta.overall + '"; treating as not-passing\n');
+      overall = 'UNVERIFIED';
+    }
+    var vs = readState();
+    // #1348 — refuse a verdict for a run that is no longer live. `verifyRun`
+    // false here means a code edit fired reset-edit-gates between the /verify
+    // invocation and this store, so the verdict describes pre-edit code.
+    // Recording it anyway produced the contradictory `verifyRun:false,
+    // verifyOutcome:'PASS'` state that check-before-done's four-way message
+    // chain has no branch for — it reports "a code edit invalidated the previous
+    // verification" while a PASS sits in state, which reads as a gate bug.
+    if (!vs.verifyRun) {
+      process.stderr.write('gate: record-verify-outcome — "' + mKey + '" arrived after a code edit invalidated the run; verdict not recorded (re-run /verify)\n');
+      break;
+    }
+    vs.verifyOutcome = overall;
+    writeState(vs);
+    break;
+  }
   case 'reset-edit-gates': {
     var fp = process.env.TOOL_INPUT_file_path || '';
     // Inert files (markdown, lockfiles, CHANGELOG, .env.example) AND inert paths
     // (.github/workflows/, .github/ISSUE_TEMPLATE/, .github/PULL_REQUEST_TEMPLATE/, #1176):
     // no gate reset — editing these doesn't expose new runtime surface.
     if (fp && (EDIT_RESET_SKIP_BOTH_RE.test(fp) || EDIT_RESET_SKIP_PATH_RE.test(fp))) break;
+    // #1348 — a scratchpad write under the OS temp dir is transient tool I/O and
+    // can never reach the branch diff, but it used to reset tests + simplify +
+    // verify like any source change: a /verify run that jotted a probe cleared
+    // the /flo-simplify stamp, and the two gates invalidated each other with no
+    // ordering that satisfied both. Reuses the predicate the memory-first gate
+    // already trusts for these paths (#1294) rather than a second one.
+    // Scope: tmp-only, NOT project-root containment — so a project rooted under
+    // tmp has its own edits skipped too (pinned in the #1348 tests). Containment
+    // is the more general rule, but it fails OPEN when the root can't be
+    // resolved, and a gate that silently stops resetting is the worse failure.
+    if (isEphemeralPath(fp)) break;
     var s = readState();
     // 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;
+    // #1332: also fires when a verdict lingers without the flag, so no path
+    // can leave a recorded outcome behind after a source edit.
+    var resetVerify = s.verifyRun || !!s.verifyOutcome;
     var resetSimplify = s.simplifyRun && !isTestOnly;
     if (!resetTests && !resetSimplify && !resetVerify) break;
     var gates = [];
     if (resetTests) { s.testsRun = false; gates.push('tests'); }
-    if (resetVerify) { s.verifyRun = false; gates.push('verify'); }
+    // #1332: drop the recorded verdict with the flag. Leaving a stale PASS
+    // behind would let the next check-before-done pass on a verdict that
+    // describes pre-edit code.
+    if (resetVerify) { s.verifyRun = false; s.verifyOutcome = null; gates.push('verify'); }
     if (resetSimplify) { s.simplifyRun = false; gates.push('simplify'); }
     if (fp) {
       s.lastResetBy = { file: fp, at: new Date().toISOString(), gates: gates };
@@ -978,7 +1113,7 @@ switch (command) {
       }
     }
     var missing = [];
-    if (config.testing_gate && !s.testsRun) missing.push('tests have not run since the last code edit (run npm test, vitest, jest, pytest, or similar)');
+    if (config.testing_gate && !s.testsRun) missing.push('tests have not run green since the last code edit (run npm test, vitest, jest, pytest, or similar — a run whose output reports failures does not count, #1322)');
     if (config.simplify_gate && !s.simplifyRun) missing.push('/flo-simplify (or /distill) has not run since the last code edit');
     if (config.learnings_gate && !s.learningsStored) missing.push('learnings have not been stored (call mcp__moflo__memory_store)');
     if (missing.length === 0) break;
@@ -989,6 +1124,10 @@ switch (command) {
     if (s.lastResetBy && s.lastResetBy.file) {
       process.stderr.write('Last gate reset: ' + s.lastResetBy.file + ' (' + (s.lastResetBy.gates || []).join(', ') + ')\n');
     }
+    // #1348 — name the order, not just the missing gate. Satisfying one gate can
+    // invalidate another (/flo-simplify edits code, which resets tests + verify),
+    // so "what is missing" alone left callers rediscovering the sequence by trial.
+    process.stderr.write(ORDER_HINT);
     process.stderr.write('Disable per-gate via moflo.yaml:\n');
     process.stderr.write('  gates:\n    testing_gate: false\n    simplify_gate: false\n    learnings_gate: false\n');
     process.exit(2);
@@ -1017,12 +1156,34 @@ switch (command) {
       }
     }
     var sd = readState();
-    if (sd.verifyRun) break;
+    // #1332: gate on the OUTCOME, not on attendance. Before this, `verifyRun`
+    // alone opened the gate, so a /verify returning FAIL satisfied it exactly
+    // as a PASS did — a failing verdict is still a successful tool invocation.
+    if (sd.verifyRun && sd.verifyOutcome === 'PASS') 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) {
+    // The four states need different remedies, so name which one applies
+    // rather than emitting one message that fits none of them.
+    var invalidated = sd.lastResetBy && sd.lastResetBy.file
+      && (sd.lastResetBy.gates || []).indexOf('verify') >= 0;
+    if (!sd.verifyRun && invalidated) {
+      process.stderr.write('  - a code edit invalidated the previous verification — re-run /verify\n');
       process.stderr.write('Last gate reset: ' + sd.lastResetBy.file + ' (verify)\n');
+    } else if (!sd.verifyRun) {
+      process.stderr.write('  - the change has not been verified since the last code edit (run /verify)\n');
+    } else if (sd.verifyOutcome === 'FAIL' || sd.verifyOutcome === 'UNVERIFIED') {
+      process.stderr.write('  - /verify ran and returned ' + sd.verifyOutcome + ' — fix the failing criteria, then re-run /verify\n');
+      process.stderr.write('    (a FAIL is a real result, not a gate error; the PR is blocked because the change did not meet its acceptance criteria)\n');
+    } else {
+      // Ran, but no verdict reached the gate: /verify was invoked and never
+      // recorded a structured outcome (interrupted, or it stored prose only).
+      process.stderr.write('  - /verify ran but recorded no verdict — re-run it so it stores a structured result\n');
+      process.stderr.write('    (Step 5 of the verify skill must pass metadata.overall to memory_store)\n');
+      // #1348 — the trap this state sets: re-invoking /verify CLEARS any prior
+      // verdict by design (#1332), so the obvious recovery lands right back here
+      // unless Step 5 completes. Say so, rather than letting it be rediscovered.
+      process.stderr.write('    Re-invoking /verify clears the prior verdict, so a re-run that skips Step 5 lands here again.\n');
     }
+    process.stderr.write(ORDER_HINT);
     process.stderr.write('Disable via moflo.yaml:\n');
     process.stderr.write('  gates:\n    verify_before_done: false\n');
     process.exit(2);