@cleocode/playbooks 2026.6.11 → 2026.6.13

package/dist/index.d.ts

@@ -27,5 +27,5 @@ export { approveGate, type CreateApprovalGateInput, createApprovalGate, E_APPROV
 export { type MigratePlaybookFileResult, migratePlaybook, migratePlaybookFile, type NodeComplianceEntry, type PlaybookComplianceReport, validatePlaybookCompliance, } from './migrate-e4.js';
 export { type ParsePlaybookResult, PlaybookParseError, parsePlaybook, } from './parser.js';
 export { DEFAULT_POLICY_RULES, type EvaluatePolicyResult, evaluatePolicy, type PolicyRule, } from './policy.js';
-export { type AgentDispatcher, type AgentDispatchInput, type AgentDispatchResult, type DeterministicRunInput, type DeterministicRunner, type DeterministicRunResult, E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, type ExecutePlaybookOptions, type ExecutePlaybookResult, executePlaybook, type PlaybookTerminalStatus, type ResumePlaybookOptions, resumePlaybook, validateDecompositionTaskTree, validateIvtrEvidenceOutput, } from './runtime.js';
+export { type AgentDispatcher, type AgentDispatchInput, type AgentDispatchResult, type DeterministicRunInput, type DeterministicRunner, type DeterministicRunResult, E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, type ExecutePlaybookOptions, type ExecutePlaybookResult, executePlaybook, type PlaybookTerminalStatus, type ResumePlaybookOptions, resumePlaybook, } from './runtime.js';
 export { type CreatePlaybookApprovalInput, type CreatePlaybookRunInput, createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, type ListPlaybookRunsOptions, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/index.js

@@ -31,7 +31,12 @@ export { PlaybookParseError, parsePlaybook, } from './parser.js';
 // W4-9: HITL auto-policy evaluator
 export { DEFAULT_POLICY_RULES, evaluatePolicy, } from './policy.js';
 // W4-10 / T930: playbook runtime state machine + HITL resume
-// T11499 E7-CLOSE-LOOPS AC3: schema validators exported for testing + external use
-export { E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, executePlaybook, resumePlaybook, validateDecompositionTaskTree, validateIvtrEvidenceOutput, } from './runtime.js';
+// T11762 ST-2: the bespoke `validateDecompositionTaskTree` /
+// `validateIvtrEvidenceOutput` validators (and their barrel re-exports) were
+// deleted — their rules are now the `task_tree` / `evidence` Zod schemas in the
+// ensures-schema registry (`@cleocode/contracts` data + `@cleocode/core`
+// accessors). No cross-package consumer imported them, so dropping the
+// re-exports is safe.
+export { E_PLAYBOOK_RESUME_BLOCKED, E_PLAYBOOK_RUNTIME_INVALID, executePlaybook, resumePlaybook, } from './runtime.js';
 // W4-8: state layer CRUD for playbook_runs + playbook_approvals
 export { createPlaybookApproval, createPlaybookRun, deletePlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, listPlaybookApprovals, listPlaybookRuns, updatePlaybookApproval, updatePlaybookRun, } from './state.js';

package/dist/parser.js

@@ -326,7 +326,87 @@ function parseEdge(raw, index, ids) {
         const ensures = parseStringArray(raw.contract.ensures, `edges[${index}].contract.ensures`);
         contract = { requires, ensures };
     }
-    return { from: raw.from, to: raw.to, contract };
+    const when = parseEdgeCondition(raw.when, `edges[${index}].when`);
+    const edge = { 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'];
+/**
+ * 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, field) {
+    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 = { 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 = op;
+            throw new PlaybookParseError(`${field} unknown operator ${String(exhaustive)}`, field, raw);
+        }
+    }
+    return condition;
 }
 function parseInputs(raw) {
     if (raw === undefined)

package/dist/runtime.d.ts

@@ -191,48 +191,6 @@ export declare const E_PLAYBOOK_RUNTIME_INVALID: "E_PLAYBOOK_RUNTIME_INVALID";
  * does not resolve to an `approved` gate.
  */
 export declare const E_PLAYBOOK_RESUME_BLOCKED: "E_PLAYBOOK_RESUME_BLOCKED";
-/**
- * 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 declare function validateDecompositionTaskTree(nodeId: string, taskTree: unknown): string | null;
-/**
- * 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 declare function validateIvtrEvidenceOutput(nodeId: string, evidence: unknown): string | null;
 /**
  * Execute a playbook from its entry node until a terminal state is reached
  * (`completed`, `failed`, `exceeded_iteration_cap`, or `pending_approval`).

package/dist/runtime.js

@@ -36,6 +36,12 @@
  */
 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`).
+import { getEnsuresSchema, listEnsuresSchemaNames } from '@cleocode/core';
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import { createPlaybookApproval, createPlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, updatePlaybookRun, } from './state.js';
 /**
@@ -61,13 +67,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 +90,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 +120,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 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) {
-    const outs = idx.outgoing.get(nodeId) ?? [];
-    if (outs.length === 0)
+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`);
     }
@@ -347,119 +455,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
@@ -546,18 +541,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 +600,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 +844,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 +882,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.11",
+  "version": "2026.6.13",
   "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/core": "2026.6.11",
-    "@cleocode/contracts": "2026.6.11"
+    "@cleocode/contracts": "2026.6.13",
+    "@cleocode/core": "2026.6.13"
   },
   "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