@cleocode/playbooks 2026.6.11 → 2026.6.13

package/src/parser.ts

@@ -34,6 +34,7 @@ import type {
   PlaybookDefinition,
   PlaybookDeterministicNode,
   PlaybookEdge,
+  PlaybookEdgeCondition,
   PlaybookEnsures,
   PlaybookErrorHandler,
   PlaybookInput,
@@ -499,7 +500,114 @@ function parseEdge(raw: unknown, index: number, ids: ReadonlySet<string>): Playb
     contract = { requires, ensures };
   }
 
-  return { from: raw.from, to: raw.to, contract };
+  const when = parseEdgeCondition(raw.when, `edges[${index}].when`);
+
+  const edge: PlaybookEdge = { from: raw.from, to: raw.to, contract };
+  if (when !== undefined) edge.when = when;
+  return edge;
+}
+
+/**
+ * Recognised comparison operators on a {@link PlaybookEdgeCondition}. Exactly
+ * one MUST be present so a guarded edge is unambiguous (T11806).
+ */
+const EDGE_CONDITION_OPERATORS = ['equals', 'notEquals', 'exists', 'in', 'truthy'] as const;
+
+/**
+ * Parse the optional `when` branch guard on an edge into a validated
+ * {@link PlaybookEdgeCondition}. Returns `undefined` for an absent guard
+ * (the edge is unconditional).
+ *
+ * Validation:
+ *  - `field` MUST be a non-empty string.
+ *  - Exactly ONE comparison operator (`equals` | `notEquals` | `exists` | `in`
+ *    | `truthy`) MUST be supplied — zero is ambiguous, more than one is
+ *    contradictory, both rejected at parse time so the runtime never has to
+ *    disambiguate.
+ *  - `exists` / `truthy` MUST be boolean; `in` MUST be a non-empty array.
+ *
+ * @param raw - Raw YAML value for `edge.when`.
+ * @param field - Field path for diagnostics (e.g. `"edges[2].when"`).
+ * @returns The validated condition, or `undefined` when absent.
+ * @throws {PlaybookParseError} On any structural violation.
+ *
+ * @task T11806 — cantbook runtime branching
+ */
+function parseEdgeCondition(raw: unknown, field: string): PlaybookEdgeCondition | undefined {
+  if (raw === undefined) return undefined;
+  if (!isRecord(raw)) {
+    throw new PlaybookParseError(`${field} must be an object`, field, raw);
+  }
+  if (typeof raw.field !== 'string' || raw.field.length === 0) {
+    throw new PlaybookParseError(
+      `${field}.field must be a non-empty string`,
+      `${field}.field`,
+      raw.field,
+    );
+  }
+
+  const present = EDGE_CONDITION_OPERATORS.filter((op) => Object.hasOwn(raw, op));
+  if (present.length === 0) {
+    throw new PlaybookParseError(
+      `${field} must declare exactly one of ${EDGE_CONDITION_OPERATORS.join(' | ')}`,
+      field,
+      raw,
+    );
+  }
+  if (present.length > 1) {
+    throw new PlaybookParseError(
+      `${field} declares multiple operators (${present.join(', ')}); exactly one is allowed`,
+      field,
+      raw,
+    );
+  }
+
+  const condition: PlaybookEdgeCondition = { field: raw.field };
+  const [op] = present;
+  switch (op) {
+    case 'equals':
+      condition.equals = raw.equals;
+      break;
+    case 'notEquals':
+      condition.notEquals = raw.notEquals;
+      break;
+    case 'in':
+      if (!Array.isArray(raw.in) || raw.in.length === 0) {
+        throw new PlaybookParseError(
+          `${field}.in must be a non-empty array`,
+          `${field}.in`,
+          raw.in,
+        );
+      }
+      condition.in = [...raw.in];
+      break;
+    case 'exists':
+      if (typeof raw.exists !== 'boolean') {
+        throw new PlaybookParseError(
+          `${field}.exists must be a boolean`,
+          `${field}.exists`,
+          raw.exists,
+        );
+      }
+      condition.exists = raw.exists;
+      break;
+    case 'truthy':
+      if (typeof raw.truthy !== 'boolean') {
+        throw new PlaybookParseError(
+          `${field}.truthy must be a boolean`,
+          `${field}.truthy`,
+          raw.truthy,
+        );
+      }
+      condition.truthy = raw.truthy;
+      break;
+    default: {
+      // Exhaustiveness guard — EDGE_CONDITION_OPERATORS is the SSoT.
+      const exhaustive: never = op;
+      throw new PlaybookParseError(`${field} unknown operator ${String(exhaustive)}`, field, raw);
+    }
+  }
+  return condition;
 }
 
 function parseInputs(raw: unknown): PlaybookInput[] | undefined {

package/src/runtime.ts

@@ -44,10 +44,17 @@ import type {
   PlaybookDefinition,
   PlaybookDeterministicNode,
   PlaybookEdge,
+  PlaybookEdgeCondition,
   PlaybookNode,
   PlaybookRun,
   PlaybookRunStatus,
 } from '@cleocode/contracts';
+// T11762 ST-2: registry-driven ensures.schema resolution. The bodied accessors
+// live in `@cleocode/core` (Gate-10 contracts-purity forbids them in the
+// contracts leaf); core does NOT depend on playbooks, so this import direction
+// is cycle-free (mirrors the existing `@cleocode/core/store/schema` import in
+// `./schema.ts`).
+import { getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import {
   createPlaybookApproval,
@@ -237,6 +244,13 @@ interface EdgeIndex {
   readonly outgoing: ReadonlyMap<string, readonly string[]>;
   /** Map from node id → list of predecessor node ids in declaration order. */
   readonly incoming: ReadonlyMap<string, readonly string[]>;
+  /**
+   * Map from node id → list of outgoing {@link PlaybookEdge} objects in
+   * declaration order. Carries the optional `when` branch guard (T11806) so
+   * the runtime can route conditionally. `depends[]`-derived reverse edges
+   * are unconditional and represented here as `{ from: dep, to: node }`.
+   */
+  readonly outgoingEdges: ReadonlyMap<string, readonly PlaybookEdge[]>;
 }
 
 /**
@@ -282,13 +296,16 @@ export const E_PLAYBOOK_RESUME_BLOCKED = 'E_PLAYBOOK_RESUME_BLOCKED' as const;
 function buildEdgeIndex(def: PlaybookDefinition): EdgeIndex {
   const outgoing = new Map<string, string[]>();
   const incoming = new Map<string, string[]>();
+  const outgoingEdges = new Map<string, PlaybookEdge[]>();
   for (const n of def.nodes) {
     outgoing.set(n.id, []);
     incoming.set(n.id, []);
+    outgoingEdges.set(n.id, []);
   }
   for (const e of def.edges) {
     outgoing.get(e.from)?.push(e.to);
     incoming.get(e.to)?.push(e.from);
+    outgoingEdges.get(e.from)?.push(e);
   }
   for (const n of def.nodes) {
     if (!n.depends) continue;
@@ -299,11 +316,15 @@ function buildEdgeIndex(def: PlaybookDefinition): EdgeIndex {
       if (out && !out.includes(n.id)) out.push(n.id);
       const inc = incoming.get(n.id);
       if (inc && !inc.includes(dep)) inc.push(dep);
+      // depends-derived reverse edges are always unconditional.
+      const outE = outgoingEdges.get(dep);
+      if (outE && !outE.some((e) => e.to === n.id)) outE.push({ from: dep, to: n.id });
     }
   }
   return {
     outgoing: new Map([...outgoing].map(([k, v]) => [k, Object.freeze([...v])])),
     incoming: new Map([...incoming].map(([k, v]) => [k, Object.freeze([...v])])),
+    outgoingEdges: new Map([...outgoingEdges].map(([k, v]) => [k, Object.freeze([...v])])),
   };
 }
 
@@ -327,23 +348,136 @@ function resolveEntryNode(def: PlaybookDefinition, idx: EdgeIndex): PlaybookNode
 }
 
 /**
- * Return the single successor node id for `nodeId`, or `null` if `nodeId` is
- * terminal (no outgoing edges — the "end" state in the design contract).
+ * Evaluate a declarative {@link PlaybookEdgeCondition} against the run
+ * `context`. The predicate is pure data (no `eval`, no expression parsing) so
+ * routing stays deterministic and sandbox-safe (T11806).
+ *
+ * Exactly one operator is set on a parsed condition (the parser enforces
+ * this); each is checked in turn:
+ *  - `equals` / `notEquals` — strict `Object.is`-style equality on
+ *    `context[field]`.
+ *  - `exists` — `field` present-in / absent-from context.
+ *  - `in` — `context[field]` is one of the listed values (strict equality).
+ *  - `truthy` — JS truthiness of `context[field]`.
  *
- * Throws on fan-out (> 1 successor) because the deterministic runtime does
- * not support branching without an explicit `decide`-node contract. A
- * follow-up task can add guarded branching here — see README.
+ * A condition naming a field absent from context evaluates to `false` for
+ * value comparisons (`equals`/`in`), `true` for `notEquals` (absent ≠ value),
+ * and is handled explicitly by `exists`/`truthy`.
+ *
+ * @param condition - Parsed, validated branch guard.
+ * @param context - Current accumulated run context.
+ * @returns `true` when the edge should be traversed.
+ *
+ * @task T11806 — cantbook runtime branching
  */
-function resolveNextNodeId(nodeId: string, idx: EdgeIndex): string | null {
-  const outs = idx.outgoing.get(nodeId) ?? [];
-  if (outs.length === 0) return null;
-  if (outs.length > 1) {
+function evaluateEdgeCondition(
+  condition: PlaybookEdgeCondition,
+  context: Record<string, unknown>,
+): boolean {
+  const has = Object.hasOwn(context, condition.field);
+  const value = context[condition.field];
+
+  if (condition.exists !== undefined) {
+    return condition.exists ? has : !has;
+  }
+  if (condition.truthy !== undefined) {
+    return condition.truthy ? Boolean(value) : !value;
+  }
+  if (Object.hasOwn(condition, 'equals')) {
+    return has && Object.is(value, condition.equals);
+  }
+  if (Object.hasOwn(condition, 'notEquals')) {
+    // Absent field is, by definition, not equal to any concrete value.
+    return !has || !Object.is(value, condition.notEquals);
+  }
+  if (condition.in !== undefined) {
+    return has && condition.in.some((candidate) => Object.is(value, candidate));
+  }
+  // Parser guarantees one operator is set; unreachable in practice.
+  return false;
+}
+
+/**
+ * Resolve the next node id to traverse from `nodeId`, given the current run
+ * `context`, with support for guarded conditional branching (T11806).
+ *
+ * Routing rules (minimal, fail-closed, backward-compatible):
+ *  - **0 outgoing edges** → `null` (terminal "end" state).
+ *  - Edges are partitioned into *unconditional* (no `when`) and *guarded*
+ *    (`when` predicate satisfied against `context`).
+ *  - **>1 unconditional successor** → throw `E_PLAYBOOK_RUNTIME_INVALID`
+ *    (genuine ambiguity — author must add `when` guards). This preserves the
+ *    pre-T11806 guard for the un-guarded fan-out case.
+ *  - **Exactly 1 satisfied successor** (unconditional or guarded) → traverse
+ *    it. Linear playbooks are unchanged: their single un-guarded edge is the
+ *    sole candidate.
+ *  - **Outgoing edges exist but NONE is satisfied** → throw (fail-closed: a
+ *    branch must always have a reachable default; silently terminating would
+ *    mask an authoring bug).
+ *  - **>1 satisfied successor** → throw (ambiguous branch — predicates must be
+ *    mutually exclusive; parallel fan-out is a deferred follow-up).
+ *
+ * @param nodeId - Current node id.
+ * @param idx - Pre-computed edge index.
+ * @param context - Current accumulated run context (predicate evaluation).
+ * @returns The single successor node id, or `null` when terminal.
+ * @throws {Error} stamped {@link E_PLAYBOOK_RUNTIME_INVALID} on ambiguous or
+ *   unsatisfiable branching.
+ */
+function resolveNextNodeId(
+  nodeId: string,
+  idx: EdgeIndex,
+  context: Record<string, unknown>,
+): string | null {
+  const edges = idx.outgoingEdges.get(nodeId) ?? [];
+  if (edges.length === 0) return null;
+
+  // Fast path: a single unconditional edge (the linear, pre-T11806 shape).
+  if (edges.length === 1) {
+    const [only] = edges;
+    if (only === undefined) {
+      throw new Error(`${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has undefined successor`);
+    }
+    if (only.when !== undefined && !evaluateEdgeCondition(only.when, context)) {
+      throw new Error(
+        `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} sole successor "${only.to}" is guarded ` +
+          `by a "when" predicate that is not satisfied — branch has no reachable default`,
+      );
+    }
+    return only.to;
+  }
+
+  // Fan-out: reject >1 unconditional successor (genuine ambiguity).
+  const unconditional = edges.filter((e) => e.when === undefined);
+  if (unconditional.length > 1) {
     throw new Error(
-      `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${outs.length} successors; branching requires an approval/decide node`,
+      `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${unconditional.length} unconditional ` +
+        `successors; guarded branching requires every additional edge to carry a "when" predicate`,
     );
   }
-  // Safe: length === 1
-  const [next] = outs;
+
+  // Collect satisfied successors: unconditional edge (if any) + guarded edges
+  // whose predicate holds.
+  const satisfied: string[] = [];
+  for (const e of edges) {
+    if (e.when === undefined || evaluateEdgeCondition(e.when, context)) {
+      satisfied.push(e.to);
+    }
+  }
+
+  if (satisfied.length === 0) {
+    throw new Error(
+      `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${edges.length} successors but no ` +
+        `"when" predicate is satisfied — branch has no reachable default`,
+    );
+  }
+  if (satisfied.length > 1) {
+    throw new Error(
+      `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${satisfied.length} satisfied successors ` +
+        `(${satisfied.join(', ')}); branch predicates must be mutually exclusive`,
+    );
+  }
+  const [next] = satisfied;
   if (next === undefined) {
     throw new Error(`${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has undefined successor`);
   }
@@ -612,167 +746,6 @@ function iterationCapFor(node: PlaybookNode, runtimeDefault: number): number {
   return runtimeDefault;
 }
 
-// ---------------------------------------------------------------------------
-// RCASD/IVTR node output schema validation (T11499 AC3)
-// ---------------------------------------------------------------------------
-
-/**
- * A single task entry within a decomposition `task_tree` output.
- *
- * Agents emitting a decomposition must produce a `task_tree` key in the
- * playbook context whose value is an array of objects conforming to this shape.
- * Validating the real shape — not just key presence — prevents garbage
- * decompositions from silently entering the run queue.
- *
- * @task T11499 E7-CLOSE-LOOPS AC3
- */
-interface DecompositionTaskEntry {
-  /** Task title — required, non-empty string. */
-  title: string;
-  /** Acceptance criteria — must be present and non-empty. */
-  acceptance: string[];
-  /** Optional task ID (may be pre-assigned by the agent). */
-  id?: string;
-  /** Optional parent task ID. */
-  parentId?: string;
-  /** Optional dependency IDs. */
-  depends?: string[];
-}
-
-/**
- * Validate the `task_tree` shape emitted by a RCASD decomposition node.
- *
- * Returns a human-readable violation string when the shape is invalid, or
- * `null` when the tree is well-formed. The check is performed AFTER the node
- * output is merged into the playbook context (post-merge ensures check).
- *
- * Rules enforced (AC3 — T11499):
- *  1. `task_tree` must be a non-empty array.
- *  2. Each entry must have a non-empty string `title`.
- *  3. Each entry must have a non-empty `acceptance` array (at least one string).
- *  4. No entry may have an empty `depends` array that references a non-existent
- *     sibling (intra-tree orphan check).
- *
- * The validator is intentionally lenient on optional fields (id, parentId,
- * depends) so that agents can emit a minimal valid tree without being rejected
- * for cosmetic omissions.
- *
- * @param nodeId - Node identifier (used in error messages).
- * @param taskTree - The raw value stored at `context.task_tree`.
- * @returns Violation string or `null` (valid).
- *
- * @task T11499 E7-CLOSE-LOOPS AC3
- */
-export function validateDecompositionTaskTree(nodeId: string, taskTree: unknown): string | null {
-  if (!Array.isArray(taskTree)) {
-    return `ensures.schema[task_tree] on ${nodeId}: task_tree must be a non-empty array, got ${typeof taskTree}`;
-  }
-
-  if (taskTree.length === 0) {
-    return `ensures.schema[task_tree] on ${nodeId}: task_tree is an empty array — decomposition produced no tasks`;
-  }
-
-  const knownIds = new Set<string>();
-  for (const entry of taskTree) {
-    if (typeof (entry as DecompositionTaskEntry).id === 'string') {
-      knownIds.add((entry as DecompositionTaskEntry).id!);
-    }
-  }
-
-  for (let i = 0; i < taskTree.length; i++) {
-    const entry = taskTree[i] as DecompositionTaskEntry;
-
-    if (typeof entry !== 'object' || entry === null) {
-      return `ensures.schema[task_tree] on ${nodeId}: entry[${i}] must be an object, got ${entry === null ? 'null' : typeof entry}`;
-    }
-
-    if (typeof entry.title !== 'string' || entry.title.trim().length === 0) {
-      return `ensures.schema[task_tree] on ${nodeId}: entry[${i}].title must be a non-empty string`;
-    }
-
-    if (!Array.isArray(entry.acceptance) || entry.acceptance.length === 0) {
-      return (
-        `ensures.schema[task_tree] on ${nodeId}: entry[${i}] ("${entry.title}") ` +
-        `must have a non-empty acceptance array`
-      );
-    }
-
-    const hasValidAc = entry.acceptance.some(
-      (ac) => typeof ac === 'string' && ac.trim().length > 0,
-    );
-    if (!hasValidAc) {
-      return (
-        `ensures.schema[task_tree] on ${nodeId}: entry[${i}] ("${entry.title}") ` +
-        `acceptance array contains no non-empty strings`
-      );
-    }
-
-    // Intra-tree orphan check: if depends[] are specified, they must reference
-    // another entry in the same tree (by id). References to external tasks are
-    // allowed (they have no id in this tree), so we only flag ids that look
-    // like intra-tree references but are absent from knownIds.
-    if (Array.isArray(entry.depends) && knownIds.size > 0) {
-      for (const depId of entry.depends) {
-        // Only flag if the depId matches the T#### pattern and is not in knownIds
-        // (external task IDs that exist in the DB are valid but we can't check here).
-        if (typeof depId === 'string' && /^T\d{3,}$/.test(depId) && !knownIds.has(depId)) {
-          // Soft warn only (not a hard violation) — the dep may be a pre-existing task.
-          // We don't hard-fail here because agents may correctly depend on existing tasks.
-        }
-      }
-    }
-  }
-
-  return null; // valid
-}
-
-/**
- * Validate the `evidence` field emitted by an IVTR validation node.
- *
- * IVTR validation nodes must emit an `evidence` key whose value is either:
- *  - An object with at least one key (structured evidence map), OR
- *  - A non-empty string (free-text evidence reference).
- *
- * Empty evidence (`{}`, `''`, `[]`) is rejected so that spawned agents
- * cannot satisfy the gate by emitting an empty object.
- *
- * @param nodeId - Node identifier (used in error messages).
- * @param evidence - The raw value stored at `context.evidence`.
- * @returns Violation string or `null` (valid).
- *
- * @task T11499 E7-CLOSE-LOOPS AC3
- */
-export function validateIvtrEvidenceOutput(nodeId: string, evidence: unknown): string | null {
-  if (evidence === null || evidence === undefined) {
-    return `ensures.schema[evidence] on ${nodeId}: evidence must be present (non-null, non-undefined)`;
-  }
-
-  if (typeof evidence === 'string') {
-    if (evidence.trim().length === 0) {
-      return `ensures.schema[evidence] on ${nodeId}: evidence string must not be empty`;
-    }
-    return null; // valid non-empty string
-  }
-
-  if (Array.isArray(evidence)) {
-    if (evidence.length === 0) {
-      return `ensures.schema[evidence] on ${nodeId}: evidence array must not be empty`;
-    }
-    return null; // valid non-empty array
-  }
-
-  if (typeof evidence === 'object') {
-    const keys = Object.keys(evidence as object);
-    if (keys.length === 0) {
-      return `ensures.schema[evidence] on ${nodeId}: evidence object must have at least one key (got {})`;
-    }
-    return null; // valid non-empty object
-  }
-
-  // Numbers, booleans etc. are not valid evidence shapes.
-  return `ensures.schema[evidence] on ${nodeId}: evidence must be a string, array, or object (got ${typeof evidence})`;
-}
-
 /**
  * Core step-by-step executor shared by {@link executePlaybook} and
  * {@link resumePlaybook}. Starts at `startNodeId` and walks the graph until
@@ -918,19 +891,46 @@ async function runFromNode(args: {
         }
       }
 
-      // RCASD/IVTR output schema validation (T11499 AC3):
+      // RCASD/IVTR + generic output schema validation (T11499 AC3 · T11762 ST-2):
       // Enforce ensures.schema beyond key-presence so garbage decompositions
       // cannot silently pass the runtime contract check.
+      //
+      // De-hardcoded (T11762): the former `if (schema === 'task_tree') …
+      // else if (=== 'evidence')` block — which SILENTLY SKIPPED any other
+      // schema name — is replaced by a registry-driven lookup against the
+      // ensures-schema Zod registry (`getEnsuresSchema` in `@cleocode/core`,
+      // backed by the `@cleocode/contracts` registry DATA). An UNKNOWN schema
+      // name now FAILS CLOSED (AC2) and is routed through the SAME
+      // `contract_violation` handler below (AC3), rather than passing silently.
       if (node.ensures?.schema) {
         let schemaViolation: string | null = null;
 
-        if (node.ensures.schema === 'task_tree') {
-          schemaViolation = validateDecompositionTaskTree(node.id, context['task_tree']);
-        } else if (node.ensures.schema === 'evidence') {
-          schemaViolation = validateIvtrEvidenceOutput(node.id, context['evidence']);
+        const spec = getEnsuresSchema(node.ensures.schema);
+        if (spec === null) {
+          // FAIL-CLOSED (AC2): unknown schema names were historically skipped
+          // silently. They are now an explicit, audited contract violation.
+          schemaViolation =
+            `ensures.schema[${node.ensures.schema}] on ${node.id}: unknown schema name. ` +
+            `Registered: ${listEnsuresSchemaNames().join(', ')}`;
+        } else {
+          // Validate the post-merge context value against the registered Zod
+          // schema. The message wrapper re-applies the historical
+          // `ensures.schema[<name>] on <nodeId>: <issue>` prefix so the
+          // end-to-end violation strings stay parity-identical to the deleted
+          // bespoke validators (the Zod issue messages were crafted in ST-1 to
+          // echo the original suffixes).
+          const result = spec.schema.safeParse(context[spec.contextKey]);
+          if (!result.success) {
+            const issue = result.error.issues[0];
+            const path = issue?.path ?? [];
+            const at = path.length > 0 ? ` at ${path.join('.')}` : '';
+            schemaViolation =
+              `ensures.schema[${spec.name}] on ${node.id}: ` +
+              `${issue?.message ?? 'invalid shape'}${at}`;
+          }
         }
-        // Future schema names are silently skipped (open for extension).
 
+        // ── UNCHANGED from here (the existing contract_violation handler) ──
         if (schemaViolation !== null) {
           auditContractViolation(
             args.projectRoot,
@@ -962,7 +962,9 @@ async function runFromNode(args: {
       if (failedNodeId !== undefined) break;
 
       // Validate outgoing edge contracts (edge.contract.requires on the FROM side).
-      const nextId = resolveNextNodeId(node.id, edgeIndex);
+      // Branch routing (T11806) reads the post-merge context so guard
+      // predicates can act on this node's freshly merged output.
+      const nextId = resolveNextNodeId(node.id, edgeIndex, context);
       if (nextId !== null) {
         const edge = resolveEdge(node.id, nextId, playbook.edges);
         if (edge?.contract?.requires) {
@@ -1241,10 +1243,29 @@ export async function resumePlaybook(
       `${E_PLAYBOOK_RESUME_BLOCKED}: approval node ${approval.nodeId} not found in playbook ${options.playbook.name}`,
     );
   }
-  const successor = resolveNextNodeId(approvalNode.id, edgeIndex);
+
+  const now = options.now ?? (() => new Date());
+  const maxIterationsDefault = options.maxIterationsDefault ?? 3;
+  const approvalSecret = options.approvalSecret ?? getPlaybookSecret();
+  const context: Record<string, unknown> = { ...run.bindings };
+  const iterationCounts: Record<string, number> = { ...run.iterationCounts };
+
+  // Log the approval decision into the context so downstream nodes can act on
+  // it. Set BEFORE resolving the successor so a gate can branch on the
+  // approver's decision via a `when: { field: __lastApproval... }` edge (T11806
+  // approval/resume branch parity).
+  context['__lastApproval'] = {
+    nodeId: approval.nodeId,
+    approvalId: approval.approvalId,
+    approver: approval.approver,
+    reason: approval.reason,
+    approvedAt: approval.approvedAt,
+  };
+
+  const successor = resolveNextNodeId(approvalNode.id, edgeIndex, context);
   if (successor === null) {
     // Approval at the tail of the graph completes the run immediately.
-    const completedAt = (options.now ?? (() => new Date()))().toISOString();
+    const completedAt = now().toISOString();
     updatePlaybookRun(options.db, run.runId, {
       status: 'completed',
       currentNode: null,
@@ -1265,21 +1286,6 @@ export async function resumePlaybook(
     errorContext: null,
   });
 
-  const now = options.now ?? (() => new Date());
-  const maxIterationsDefault = options.maxIterationsDefault ?? 3;
-  const approvalSecret = options.approvalSecret ?? getPlaybookSecret();
-  const context: Record<string, unknown> = { ...run.bindings };
-  const iterationCounts: Record<string, number> = { ...run.iterationCounts };
-
-  // Log the approval decision into the context so downstream nodes can act on it.
-  context['__lastApproval'] = {
-    nodeId: approval.nodeId,
-    approvalId: approval.approvalId,
-    approver: approval.approver,
-    reason: approval.reason,
-    approvedAt: approval.approvedAt,
-  };
-
   // Persist an approval trace row for audit purposes. createPlaybookApproval
   // is distinct from createApprovalGate — the latter generates the HMAC
   // resume token, while this helper records arbitrary approval state.