moflo 4.12.3 → 4.12.4-rc.1

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,11 +32,42 @@ 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;
   });
 }
 

package/.claude/helpers/gate.cjs

@@ -865,12 +865,47 @@ 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();
+    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
@@ -883,12 +918,17 @@ switch (command) {
     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 };
@@ -1017,11 +1057,28 @@ 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');
     }
     process.stderr.write('Disable via moflo.yaml:\n');
     process.stderr.write('  gates:\n    verify_before_done: false\n');

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
 

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,11 +32,42 @@ 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;
   });
 }