@cleocode/playbooks 2026.6.12 → 2026.6.14

package/dist/runtime.js

@@ -36,6 +36,15 @@
  */
 import { appendFileSync, mkdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+// 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`).
+// T1944 (M4): `defaultVariableResolver` is the canonical T1238 mustache engine,
+// re-used here (DRY) to resolve `PlaybookAgenticNode.inputs` `{{path}}`
+// templates at the dispatch boundary rather than re-implementing substitution.
+import { defaultVariableResolver, getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import { createPlaybookApproval, createPlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, updatePlaybookRun, } from './state.js';
 /**
@@ -61,13 +70,16 @@ export const E_PLAYBOOK_RESUME_BLOCKED = 'E_PLAYBOOK_RESUME_BLOCKED';
 function buildEdgeIndex(def) {
     const outgoing = new Map();
     const incoming = new Map();
+    const outgoingEdges = new Map();
     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)
@@ -81,11 +93,16 @@ function buildEdgeIndex(def) {
             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])])),
     };
 }
 /**
@@ -106,22 +123,116 @@ function resolveEntryNode(def, idx) {
     throw new Error(`${E_PLAYBOOK_RUNTIME_INVALID}: no entry node (every node has a predecessor) in ${def.name}`);
 }
 /**
- * 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).
  *
- * 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.
+ * 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]`.
+ *
+ * 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, idx) {
-    const outs = idx.outgoing.get(nodeId) ?? [];
-    if (outs.length === 0)
+function evaluateEdgeCondition(condition, context) {
+    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, idx, context) {
+    const edges = idx.outgoingEdges.get(nodeId) ?? [];
+    if (edges.length === 0)
         return null;
-    if (outs.length > 1) {
-        throw new Error(`${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${outs.length} successors; branching requires an approval/decide node`);
+    // 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 ${unconditional.length} unconditional ` +
+            `successors; guarded branching requires every additional edge to carry a "when" predicate`);
+    }
+    // Collect satisfied successors: unconditional edge (if any) + guarded edges
+    // whose predicate holds.
+    const satisfied = [];
+    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`);
     }
-    // Safe: length === 1
-    const [next] = outs;
+    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`);
     }
@@ -141,12 +252,74 @@ function resolveNode(nodeId, idx) {
 // ---------------------------------------------------------------------------
 // Per-node execution
 // ---------------------------------------------------------------------------
+/**
+ * Resolve a {@link PlaybookAgenticNode}'s declared `inputs` into the per-step
+ * binding map handed to the dispatcher (T1944 · M4 cantbook done-gate).
+ *
+ * Each `inputs` value is a mustache `{{path}}` template. Templates are resolved
+ * against the accumulated run `context` using the canonical T1238
+ * {@link DefaultVariableResolver} (no second substitution engine — DRY) and the
+ * resolved key/value pairs are then layered ON TOP of the run context. The
+ * result is the dispatch-time binding map.
+ *
+ * ## Canonical resolver precedence (highest → lowest)
+ *
+ * 1. **step bindings** — the resolved `node.inputs` themselves. They are merged
+ *    LAST over the run context, so a step input always SHADOWS a same-named
+ *    context key (AC3 / AC6).
+ * 2. **playbook bindings** — the accumulated run `context` (seeded from the
+ *    playbook's declared inputs + every prior node's merged output).
+ * 3. **session / project-context / env / default** — supplied to the underlying
+ *    {@link DefaultVariableResolver} via the {@link SubstitutionContext} below.
+ *
+ * The run `context` is exposed to the resolver through BOTH the `projectContext`
+ * tier (which supports dot-notation, so `{{inputs.epicId}}` and `{{context.foo}}`
+ * resolve into nested objects) and `process.env` (the `env` tier). The
+ * resolver runs in lenient mode.
+ *
+ * ## Missing-key rule
+ *
+ * Lenient. When a `{{path}}` template references a value that resolves through
+ * NO tier, the literal placeholder text is left intact in the bound value (e.g.
+ * `{{missing}}` stays `"{{missing}}"`). This mirrors the canonical T1238
+ * lenient posture — a missing input never aborts the dispatch; the agent
+ * receives the literal placeholder and can fail loudly downstream if required.
+ *
+ * @param node - The agentic node whose `inputs` are resolved.
+ * @param context - The accumulated run bindings at dispatch time.
+ * @returns A new binding map = `{ ...context, ...resolvedStepInputs }`. When the
+ *   node declares no `inputs`, this is a shallow copy of `context`.
+ */
+export function resolveStepBindings(node, context) {
+    // No declared inputs — bindings are just a snapshot of the run context.
+    if (node.inputs === undefined || Object.keys(node.inputs).length === 0) {
+        return { ...context };
+    }
+    // Expose the run context to the canonical resolver. `projectContext` is the
+    // dot-notation-capable tier, so `{{inputs.epicId}}` / `{{context.foo.bar}}`
+    // walk into nested objects; flat keys (`{{epicId}}`) resolve via a
+    // single-segment walk on the same tier.
+    const substitutionContext = {
+        projectContext: context,
+        env: process.env,
+    };
+    const resolvedInputs = {};
+    for (const [key, template] of Object.entries(node.inputs)) {
+        // Lenient resolve — missing placeholders are left literal (see TSDoc).
+        const result = defaultVariableResolver.resolve(template, substitutionContext, {
+            strict: false,
+        });
+        resolvedInputs[key] = result.text;
+    }
+    // Step bindings shadow the run context for same-named keys (AC3 / AC6).
+    return { ...context, ...resolvedInputs };
+}
 /**
  * Execute a single `agentic` node via the injected {@link AgentDispatcher}.
  * The dispatcher receives the current context and must return a success /
  * failure envelope — any thrown exception is normalized into a failure.
  */
-async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
+async function executeAgenticNode(node, runId, context, iteration, dispatcher, playbookName) {
     const agentId = node.agent ?? node.skill;
     if (agentId === undefined) {
         // Parser guarantees at-least-one, but narrow defensively.
@@ -157,6 +330,9 @@ async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
     }
     const taskIdRaw = context['taskId'];
     const taskId = typeof taskIdRaw === 'string' && taskIdRaw.length > 0 ? taskIdRaw : runId;
+    // T1944 (M4): resolve `node.inputs` `{{path}}` templates against the run
+    // context and layer them on top so step inputs shadow context (AC1/AC2/AC3).
+    const bindings = resolveStepBindings(node, context);
     try {
         const result = await dispatcher.dispatch({
             runId,
@@ -164,7 +340,20 @@ async function executeAgenticNode(node, runId, context, iteration, dispatcher) {
             agentId,
             taskId,
             context: { ...context },
+            bindings,
             iteration,
+            // T11759 (M4): forward the playbook name + the node's per-stage LLM pin so
+            // the dispatcher can resolve a declared `profile:` through the E9
+            // chokepoint. All-additive; omitted when the node declares no pin.
+            playbookName,
+            ...(node.profile !== undefined ? { profile: node.profile } : {}),
+            ...(node.model !== undefined ? { model: node.model } : {}),
+            ...(node.provider !== undefined ? { provider: node.provider } : {}),
+            // T1947 (M4): forward the per-step skill/tool allowlists so the dispatcher
+            // can intersect them against the Tier-0/1/2 baseline at spawn time. Omitted
+            // when the node declares no allowlist (additive — baseline unchanged).
+            ...(node.allowed_skills !== undefined ? { allowedSkills: node.allowed_skills } : {}),
+            ...(node.allowed_tools !== undefined ? { allowedTools: node.allowed_tools } : {}),
         });
         if (result.status === 'success') {
             return { kind: 'success', output: result.output };
@@ -347,119 +536,6 @@ function iterationCapFor(node, runtimeDefault) {
         return cap;
     return runtimeDefault;
 }
-/**
- * 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, taskTree) {
-    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();
-    for (const entry of taskTree) {
-        if (typeof entry.id === 'string') {
-            knownIds.add(entry.id);
-        }
-    }
-    for (let i = 0; i < taskTree.length; i++) {
-        const entry = taskTree[i];
-        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, evidence) {
-    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);
-        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
@@ -517,7 +593,7 @@ async function runFromNode(args) {
         }
         let outcome;
         if (node.type === 'agentic') {
-            outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher);
+            outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher, playbook.name);
         }
         else if (node.type === 'deterministic') {
             outcome = await executeDeterministicNode(node, run.runId, context, attempt, dispatcher, deterministicRunner);
@@ -546,18 +622,45 @@ 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 = null;
-                if (node.ensures.schema === 'task_tree') {
-                    schemaViolation = validateDecompositionTaskTree(node.id, context['task_tree']);
+                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 if (node.ensures.schema === 'evidence') {
-                    schemaViolation = validateIvtrEvidenceOutput(node.id, context['evidence']);
+                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, run.runId, node.id, 'ensures', node.ensures.schema, playbook.name);
                     const handled = handleContractErrorHandler(playbook, 'contract_violation', schemaViolation);
@@ -578,7 +681,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) {
@@ -820,10 +925,26 @@ export async function resumePlaybook(options) {
     if (approvalNode === undefined || approvalNode.type !== 'approval') {
         throw new Error(`${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 = { ...run.bindings };
+    const iterationCounts = { ...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,
@@ -842,19 +963,6 @@ export async function resumePlaybook(options) {
         currentNode: successor,
         errorContext: null,
     });
-    const now = options.now ?? (() => new Date());
-    const maxIterationsDefault = options.maxIterationsDefault ?? 3;
-    const approvalSecret = options.approvalSecret ?? getPlaybookSecret();
-    const context = { ...run.bindings };
-    const iterationCounts = { ...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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/playbooks",
-  "version": "2026.6.12",
+  "version": "2026.6.14",
   "description": "Playbook DSL + runtime for CLEO — T889 Orchestration Coherence v3",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,8 +19,8 @@
   "dependencies": {
     "drizzle-orm": "1.0.0-rc.3",
     "js-yaml": "^4.1.0",
-    "@cleocode/contracts": "2026.6.12",
-    "@cleocode/core": "2026.6.12"
+    "@cleocode/contracts": "2026.6.14",
+    "@cleocode/core": "2026.6.14"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/__tests__/fixtures/conditional-branch.cantbook

@@ -0,0 +1,50 @@
+version: "1.0"
+name: conditional-branch
+description: >
+  T11806 branching fixture — a single classify node fans out to two mutually
+  exclusive successors via `when` guards. When context.needsResearch is true the
+  run routes through branch-A (deep-research); otherwise it routes through
+  branch-B (skip-research). Both branches converge on a final ship node so the
+  run always reaches a single terminal state.
+
+inputs:
+  - name: taskId
+    required: true
+    description: Task id being executed.
+
+nodes:
+  - id: classify
+    type: agentic
+    skill: ct-research-agent
+    description: Classify whether the task needs research; emits needsResearch.
+
+  - id: deep-research
+    type: agentic
+    skill: ct-research-agent
+    description: Branch-A — taken when needsResearch is true.
+
+  - id: skip-research
+    type: agentic
+    skill: ct-task-executor
+    description: Branch-B — taken when needsResearch is not true.
+
+  - id: ship
+    type: agentic
+    skill: ct-task-executor
+    description: Converge — runs after whichever branch was taken.
+
+edges:
+  - from: classify
+    to: deep-research
+    when:
+      field: needsResearch
+      equals: true
+  - from: classify
+    to: skip-research
+    when:
+      field: needsResearch
+      notEquals: true
+  - from: deep-research
+    to: ship
+  - from: skip-research
+    to: ship

package/src/__tests__/fixtures/pi-skill-only.cantbook

@@ -0,0 +1,26 @@
+version: "1.0"
+name: pi-skill-only
+description: >
+  T11945 (M4) deterministic e2e fixture — a single skill-only agentic node. The
+  node names a real `ct-*` skill so the production dispatcher's
+  `runSkillNodeOrSpawn` takes the IN-PROCESS skill path (findSkill resolves it)
+  and, when a Pi runner is injected, routes the node THROUGH the PiAgentAdapter.
+  No `requires`/`ensures` contracts so schema enforcement never interferes with
+  the dispatch-path assertion. With no LLM credential resolvable in CI the Pi
+  loop terminates with the cleo-owned no-credential failure — proving the call
+  reached the Pi streamFn (the E9 chokepoint), not a live round-trip.
+
+inputs:
+  - name: taskId
+    required: true
+    description: Task id being executed (seeds the run context).
+
+nodes:
+  - id: execute
+    type: agentic
+    skill: ct-task-executor
+    description: >
+      Single skill-only node — routes in-process through the SkillExecutorAdapter,
+      and through the PiAgentAdapter when the Pi runner is wired (T11945).
+
+edges: []