moflo 4.12.3 → 4.12.4-rc.2

package/.claude/agents/core/coder.md

@@ -236,10 +236,9 @@ mcp__moflo__performance_benchmark {
   iterations: 10
 }
 
-// Analyze bottlenecks
+// Read this process's CPU / memory / heap usage
 mcp__moflo__performance_report {
-  component: "api-endpoint",
-  metrics: ["response-time", "memory-usage"]
+  format: "detailed"
 }
 ```
 

package/.claude/agents/core/researcher.md

@@ -155,10 +155,9 @@ mcp__moflo__memory_search {
 
 ### Analysis Tools
 ```javascript
-// Analyze codebase
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "code_quality"
+// Understand what a change touches and how risky it is
+mcp__moflo__analyze_diff {
+  ref: "main"
 }
 
 // Track research metrics

package/.claude/agents/core/reviewer.md

@@ -304,16 +304,14 @@ mcp__moflo__memory_retrieve {
 
 ### Code Analysis
 ```javascript
-// Analyze code quality
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "code_quality"
+// Assess the risk and shape of the change under review
+mcp__moflo__analyze_diff {
+  ref: "main"
 }
 
-// Run security scan
-mcp__moflo__github_repo_analyze {
-  repo: "current",
-  analysis_type: "security"
+// Scan the diff for prompt-injection and unsafe content
+mcp__moflo__aidefence_scan {
+  content: "<the diff or file under review>"
 }
 ```
 

package/.claude/guidance/shipped/moflo-spell-engine.md

@@ -1,6 +1,6 @@
 # Spell Engine — Definition Format & Step Types
 
-**Purpose:** How to define a spell (YAML/JSON schema, arguments, steps, variable interpolation) and a reference for the nine built-in step command types. For execution mechanics (running, dry-run, error codes, pause/resume, layering, credentials), see `.claude/guidance/moflo-spell-runner.md`.
+**Purpose:** How to define a spell (YAML/JSON schema, arguments, steps, variable interpolation) and a reference for the built-in step command types. For execution mechanics (running, dry-run, error codes, pause/resume, layering, credentials), see `.claude/guidance/moflo-spell-runner.md`.
 
 ---
 
@@ -96,16 +96,16 @@ steps:
     config:
       command: "curl -s {args.api_url}"
   - id: process
-    type: agent
+    type: bash
     config:
-      prompt: "Analyze this response: {fetch-url.stdout}"
+      command: 'claude -p "Analyze this response: {fetch-url.stdout}"'
 ```
 
 ---
 
 ## Step Command Types
 
-**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. To add new step types via JS/TS files, YAML composite steps, or `moflo-step-*` npm packages, see `.claude/guidance/moflo-spell-custom-steps.md`.
+**Fifteen built-in step types are registered automatically** (one of them, `agent`, is registered but not executable — see below). Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. To add new step types via JS/TS files, YAML composite steps, or `moflo-step-*` npm packages, see `.claude/guidance/moflo-spell-custom-steps.md`.
 
 ### bash — Run a Shell Command
 
@@ -122,18 +122,21 @@ steps:
 
 ---
 
-### agent — Spawn a Claude Subagent
+### agent — NOT EXECUTABLE
+
+**Do not use this step type.** It has never spawned a subagent — moflo has no agent spawner in the spell runner. It is still registered so existing spell YAML keeps parsing, but casting it now always fails with an explanatory error (#1334). Earlier versions returned `success: true` and a `result` string for work that never happened.
+
+**To run a Claude subagent from a spell, use a `bash` step:**
 
 ```yaml
 - id: research
-  type: agent
+  type: bash
   config:
-    agentType: "researcher"     # Required. researcher, coder, tester, etc.
-    prompt: "Find all API endpoints in {args.directory}"  # Required.
-    background: false           # Optional. Default false.
+    command: 'claude -p "Find all API endpoints in {args.directory}"'
+    timeout: 300000
 ```
 
-**Outputs:** `result` (string), `agentType` (string), `prompt` (string).
+**Outputs:** none — the step always fails. `agentType` and `prompt` are echoed in the failure for diagnosis only.
 
 ---
 

package/.claude/helpers/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/.claude/helpers/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);

package/.claude/skills/connector-builder/SKILL.md

@@ -118,13 +118,14 @@ steps:
       command: "echo 'preparing...'"
 
   - name: use-<name>
-    type: agent
+    type: <name>          # the step command registered in Step 4
     config:
-      prompt: |
-        Use the <name> connector to <action-1>.
-        Access via context.tools.execute('<name>', '<action-1>', { ... })
+      action: <action-1>
+      # ...action params
 ```
 
+**Do not reach a connector from an `agent` step.** That step type has never been executable. A connector is reached from its own step command (Step 4 above), from a composite step's `tool` action, or from a custom step command.
+
 ---
 
 ## Building a Step Command

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

@@ -182,7 +182,7 @@ git commit -m "type(scope): description
 
 Closes #<issue-number>
 
-Co-Authored-By: moflo <noreply@motailz.com>"
+Co-Authored-By: moflo <noreply@cielolimitada.com>"
 ```
 
 ### 5.1b Verify-before-done (default; skipped only with `--no-verify`)

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

@@ -52,7 +52,7 @@ Artifacts live at `<specs_dir>/<slug>/{spec,plan}.md` — default `.moflo/specs`
 
 Runs at step 8 of the full-mode flow, before the PR — **by default** and always under `--sdd`; `--no-verify` skips it for one run.
 
-**Delegate to the `/verify` skill** — `Skill({ skill: "verify" })`, passing the issue number or spec slug. It owns the mechanics (single source of truth — don't restate them here): locate the acceptance criteria (plan, else ticket) → reuse the Tests-phase run (no double verify) → map each criterion to evidence → run only uncovered checks → record its own outcome to memory (`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`.
+**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. **The verdict is the point, not the invocation** (#1332). Invoking `/verify` trips `record-verify-run`, but that alone no longer opens `check-before-done` — the gate requires the recorded verdict to be `PASS`. A run returning FAIL leaves `gh pr create` blocked, which is the intended behaviour: the change did not meet its acceptance criteria. The verdict reaches the gate from the structured record `/verify` Step 5 writes to `memory_store` under `metadata.overall` (#1328), so a run that stores prose only is treated as *no verdict* and also blocks. Describing verification in prose has never satisfied the gate. A source edit after verifying invalidates both the flag and the verdict — re-run `/verify`. Full how-to: `.claude/skills/verify/SKILL.md`.
 
 `/ward` and `/quicken` stay targeted audits, not the completion gate.
 

package/.claude/skills/spell-builder/SKILL.md

@@ -314,11 +314,12 @@ steps:
     output: audit-result
 
   - id: analyze-findings
-    type: agent
+    type: bash
     config:
-      prompt: |
-        Analyze the npm audit results and filter for severity >= {args.severity}.
-        Audit output: {scan-deps.result}
+      command: |
+        claude -p "Analyze these npm audit results and filter for severity >= {args.severity}.
+        Audit output: {scan-deps.stdout}"
+      timeout: 300000
     output: analysis
 
   - id: save-report

package/.claude/skills/spell-builder/architecture.md

@@ -136,11 +136,11 @@ steps:
     output: inbox          # ← stores output as "inbox"
 
   - id: process
-    type: agent
+    type: bash
     config:
-      prompt: |
-        Emails: {inbox.emails}            # ← references inbox output
-        Total: {inbox.totalEmails}
+      command: |
+        claude -p "Emails: {inbox.emails}   # ← references inbox output
+        Total: {inbox.totalEmails}"
 ```
 
 **Variable reference rules:**

package/.claude/skills/spell-builder/connectors/github-cli/README.md

@@ -1,31 +1,36 @@
 # `github-cli` — GitHub CLI Connector
 
-**Purpose:** Use this connector to execute GitHub CLI operations from agent steps or as the backing connector for the `github` step command. Choose this when you need programmatic access to GitHub issues, PRs, and repos.
+**Purpose:** Use this connector as the backing connector for the `github` step command, or from a custom step command. Choose this when you need programmatic access to GitHub issues, PRs, and repos.
 
 ## Usage
 
+From a spell, reach this connector through the `github` step, which delegates to it:
+
 ```yaml
-- id: list-open-bugs
-  type: agent
+- id: fetch-bug
+  type: github
   config:
-    prompt: |
-      Use the github-cli connector to find open bugs.
-      Call context.tools.execute('github-cli', 'issue-list', {
-        repo: 'my-org/backend-api',
-        labels: ['bug'],
-        state: 'open'
-      })
+    action: issue-fetch
+    issue: 42
+    fields: ["number", "title", "labels", "state"]
 ```
 
+> 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 `github` step, a composite step's `tool` action, or a custom step command.
+
 ## Actions
 
-| Action | Description |
-|--------|-------------|
-| `issue-create` | Create a new GitHub issue |
-| `issue-list` | List issues with optional filters |
-| `pr-create` | Create a pull request |
-| `pr-list` | List pull requests with optional filters |
-| `repo-view` | View repository metadata |
+Taken from `VALID_ACTIONS` in `src/cli/spells/connectors/github-cli.ts`. `issue-create`, `issue-list`, `pr-list` and `repo-view` were listed here previously but have never existed.
+
+| Action | Required params | Description |
+|--------|-----------------|-------------|
+| `issue-fetch` | `issue` | Fetch issue details as JSON (`fields` selects columns) |
+| `issue-edit` | `issue` | Edit an existing issue |
+| `pr-create` | `title` | Create a pull request |
+| `pr-merge` | `pr` or `issue` | Merge a PR (`mergeMethod`: squash \| merge \| rebase) |
+| `pr-find` | `head` or `search` | Find a PR by head branch or search query |
+| `label` | (`issue` or `pr`) + `labels` | Add/remove labels |
+| `comment` | (`issue` or `pr`) + `body` | Post a comment |
+| `repo-info` | — | View repository metadata |
 
 ## Direct Usage