@cleocode/playbooks 2026.6.12 → 2026.6.14

package/src/runtime.ts

@@ -44,10 +44,21 @@ import type {
   PlaybookDefinition,
   PlaybookDeterministicNode,
   PlaybookEdge,
+  PlaybookEdgeCondition,
   PlaybookNode,
   PlaybookRun,
   PlaybookRunStatus,
+  SubstitutionContext,
 } 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`).
+// 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,
@@ -77,8 +88,69 @@ export interface AgentDispatchInput {
   taskId: string;
   /** Snapshot of the accumulated bindings at dispatch time. */
   context: Record<string, unknown>;
+  /**
+   * Per-step resolved bindings for this node (T1944 · M4 cantbook done-gate).
+   *
+   * Additive field. Built by {@link resolveStepBindings} from
+   * {@link PlaybookAgenticNode.inputs} — each declared input is a mustache
+   * `{{path}}` template resolved against the accumulated run `context` (via the
+   * canonical T1238 {@link DefaultVariableResolver}), then layered ON TOP of
+   * that context so a step input SHADOWS a same-named context key.
+   *
+   * The runtime always populates this when dispatching an agentic node (it is a
+   * shallow copy of `context` when the node declares no `inputs`). It is typed
+   * optional only to keep the change strictly additive for any out-of-tree
+   * dispatcher that constructs an {@link AgentDispatchInput} directly.
+   *
+   * Resolver precedence (highest → lowest):
+   * `step bindings ⊳ playbook bindings (run context) ⊳ session ⊳ project-context ⊳ env ⊳ default`.
+   */
+  bindings?: Record<string, unknown>;
   /** 1-based iteration counter for this specific node (retry-aware). */
   iteration: number;
+  /**
+   * Name of the running playbook (`.cantbook`) — the first segment of the
+   * cantbook node identity `cantbook:<playbook>#<nodeId>` (T11759 · M4).
+   *
+   * Additive. The runtime always populates it for agentic nodes; the dispatcher
+   * uses it (with {@link nodeId}) to resolve a declared per-stage LLM profile
+   * through the E9 chokepoint. Optional only so an out-of-tree dispatcher that
+   * constructs an {@link AgentDispatchInput} directly remains source-compatible.
+   */
+  playbookName?: string;
+  /**
+   * The node's declared per-stage LLM pin (T11759 · M4) — lifted verbatim from
+   * {@link PlaybookAgenticNode.profile} / `.model` / `.provider`.
+   *
+   * Additive + all-optional. When any field is set the dispatcher resolves the
+   * stage's LLM through `resolveLLMForSystem` keyed by the cantbook node
+   * identity, honoring the profile pin; when all are unset resolution is
+   * unchanged. The runtime NEVER acts on these itself — it only forwards them.
+   */
+  profile?: string;
+  /** Inline model-id pin forwarded from {@link PlaybookAgenticNode.model} (T11759). */
+  model?: string;
+  /** Inline provider pin forwarded from {@link PlaybookAgenticNode.provider} (T11759). */
+  provider?: string;
+  /**
+   * Per-step skill allowlist lifted verbatim from
+   * {@link PlaybookAgenticNode.allowed_skills} (T1947 · M4).
+   *
+   * Additive + optional. When present the dispatcher passes it to
+   * `composeSpawnPayload`, which intersects it with the resolved agent's skill
+   * baseline (Tier-0/1/2) — the allowlist can only RESTRICT, never expand. When
+   * absent the spawn carries its full baseline skill set. The runtime NEVER acts
+   * on this itself — it only forwards it.
+   */
+  allowedSkills?: string[];
+  /**
+   * Per-step tool allowlist lifted verbatim from
+   * {@link PlaybookAgenticNode.allowed_tools} (T1947 · M4).
+   *
+   * Same restrict-only intersection semantics as {@link allowedSkills}, applied
+   * to the spawn's tool baseline.
+   */
+  allowedTools?: string[];
 }
 
 /**
@@ -237,6 +309,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 +361,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 +381,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 +413,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]`.
+ *
+ * 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: 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).
  *
- * 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.
+ * @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): string | null {
-  const outs = idx.outgoing.get(nodeId) ?? [];
-  if (outs.length === 0) return null;
-  if (outs.length > 1) {
+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 ${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: 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 ${outs.length} successors; branching requires an approval/decide node`,
+      `${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has ${satisfied.length} satisfied successors ` +
+        `(${satisfied.join(', ')}); branch predicates must be mutually exclusive`,
     );
   }
-  // Safe: length === 1
-  const [next] = outs;
+  const [next] = satisfied;
   if (next === undefined) {
     throw new Error(`${E_PLAYBOOK_RUNTIME_INVALID}: node ${nodeId} has undefined successor`);
   }
@@ -366,6 +565,75 @@ function resolveNode(nodeId: string, idx: NodeIndex): PlaybookNode {
 // 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: PlaybookAgenticNode,
+  context: Record<string, unknown>,
+): Record<string, unknown> {
+  // 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: SubstitutionContext = {
+    projectContext: context,
+    env: process.env,
+  };
+
+  const resolvedInputs: Record<string, unknown> = {};
+  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 /
@@ -377,6 +645,7 @@ async function executeAgenticNode(
   context: Record<string, unknown>,
   iteration: number,
   dispatcher: AgentDispatcher,
+  playbookName: string,
 ): Promise<NodeOutcome> {
   const agentId = node.agent ?? node.skill;
   if (agentId === undefined) {
@@ -389,6 +658,10 @@ async function executeAgenticNode(
   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,
@@ -396,7 +669,20 @@ async function executeAgenticNode(
       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 };
@@ -612,167 +898,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
@@ -873,7 +998,14 @@ async function runFromNode(args: {
 
     let outcome: NodeOutcome;
     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,
@@ -918,19 +1050,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 +1121,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 +1402,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 +1445,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.