@cleocode/playbooks 2026.6.12 → 2026.6.14

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, resolveStepBindings, 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,14 @@ 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, 
+// T1944 (M4): per-step `node.inputs` → dispatch-boundary binding resolver.
+resolveStepBindings, 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

@@ -230,6 +230,17 @@ function parseAgenticNode(raw, base, index) {
         inputs = acc;
     }
     const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
+    // T11759 (M4): per-stage LLM pin. Each is an optional non-empty string — the
+    // dispatcher resolves them through the E9 chokepoint at dispatch time. Absent
+    // fields leave resolution unchanged (additive).
+    const profile = parseOptionalNonEmptyString(raw.profile, `nodes[${index}].profile`);
+    const model = parseOptionalNonEmptyString(raw.model, `nodes[${index}].model`);
+    const provider = parseOptionalNonEmptyString(raw.provider, `nodes[${index}].provider`);
+    // T1947 (M4): per-step skill/tool allowlists. Each is an optional string[] —
+    // enforced at spawn time by composeSpawnPayload as an INTERSECTION against the
+    // Tier-0/1/2 baseline (restrict-only, never expand). Absent → no restriction.
+    const allowed_skills = parseStringArray(raw.allowed_skills, `nodes[${index}].allowed_skills`);
+    const allowed_tools = parseStringArray(raw.allowed_tools, `nodes[${index}].allowed_tools`);
     return {
         ...base,
         type: 'agentic',
@@ -238,6 +249,11 @@ function parseAgenticNode(raw, base, index) {
         role,
         inputs,
         ...(context_files !== undefined ? { context_files } : {}),
+        ...(profile !== undefined ? { profile } : {}),
+        ...(model !== undefined ? { model } : {}),
+        ...(provider !== undefined ? { provider } : {}),
+        ...(allowed_skills !== undefined ? { allowed_skills } : {}),
+        ...(allowed_tools !== undefined ? { allowed_tools } : {}),
     };
 }
 function parseDeterministicNode(raw, base, index) {
@@ -326,7 +342,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)
@@ -449,6 +545,23 @@ function parseStringArray(raw, field) {
         return v;
     });
 }
+/**
+ * Parse an optional scalar string field that, when present, MUST be a non-empty
+ * string (T11759 — the per-stage LLM pins `profile` / `model` / `provider`).
+ *
+ * @param raw - Raw YAML value.
+ * @param field - Field path for diagnostics.
+ * @returns The trimmed-as-authored string, or `undefined` when absent.
+ * @throws {PlaybookParseError} When present but not a non-empty string.
+ */
+function parseOptionalNonEmptyString(raw, field) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== 'string' || raw.length === 0) {
+        throw new PlaybookParseError(`${field} must be a non-empty string`, field, raw);
+    }
+    return raw;
+}
 /**
  * Detect cycles across the combined edge-set (explicit `edges[]` plus
  * `depends[]` back-references). Uses 3-color DFS.

package/dist/runtime.d.ts

@@ -35,7 +35,7 @@
  * @task T1261 PSYCHE E4 — contract enforcement + context boundary
  */
 import type { DatabaseSync } from 'node:sqlite';
-import type { PlaybookDefinition } from '@cleocode/contracts';
+import type { PlaybookAgenticNode, PlaybookDefinition } from '@cleocode/contracts';
 /**
  * Input payload handed to {@link AgentDispatcher.dispatch} on every
  * `agentic` node execution. All fields are read-only from the dispatcher's
@@ -52,8 +52,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[];
 }
 /**
  * Terminal output returned by {@link AgentDispatcher.dispatch}. The runtime
@@ -192,47 +253,44 @@ export declare const E_PLAYBOOK_RUNTIME_INVALID: "E_PLAYBOOK_RUNTIME_INVALID";
  */
 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).
+ * Resolve a {@link PlaybookAgenticNode}'s declared `inputs` into the per-step
+ * binding map handed to the dispatcher (T1944 · M4 cantbook done-gate).
  *
- * 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).
+ * 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.
  *
- * 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.
+ * ## Canonical resolver precedence (highest → lowest)
  *
- * @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.
+ * 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.
  *
- * 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).
+ * 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.
  *
- * Empty evidence (`{}`, `''`, `[]`) is rejected so that spawned agents
- * cannot satisfy the gate by emitting an empty object.
+ * ## Missing-key rule
  *
- * @param nodeId - Node identifier (used in error messages).
- * @param evidence - The raw value stored at `context.evidence`.
- * @returns Violation string or `null` (valid).
+ * 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.
  *
- * @task T11499 E7-CLOSE-LOOPS AC3
+ * @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 declare function validateIvtrEvidenceOutput(nodeId: string, evidence: unknown): string | null;
+export declare function resolveStepBindings(node: PlaybookAgenticNode, context: Record<string, unknown>): Record<string, unknown>;
 /**
  * Execute a playbook from its entry node until a terminal state is reached
  * (`completed`, `failed`, `exceeded_iteration_cap`, or `pending_approval`).