@cleocode/playbooks 2026.4.128 → 2026.4.129

package/dist/index.d.ts

@@ -24,6 +24,7 @@
  */
 export declare const PLAYBOOKS_PACKAGE_VERSION: string;
 export { approveGate, type CreateApprovalGateInput, createApprovalGate, E_APPROVAL_ALREADY_DECIDED, E_APPROVAL_NOT_FOUND, generateResumeToken, getPendingApprovals, getPlaybookSecret, rejectGate, } from './approval.js';
+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, } from './runtime.js';

package/dist/index.js

@@ -22,8 +22,10 @@
  * Consumers can use this to assert dependency alignment at runtime
  * (e.g. ensuring the `@cleocode/playbooks` runtime matches CLEO core).
  */
-export const PLAYBOOKS_PACKAGE_VERSION = '2026.4.85';
+export const PLAYBOOKS_PACKAGE_VERSION = '2026.4.129';
 export { approveGate, createApprovalGate, E_APPROVAL_ALREADY_DECIDED, E_APPROVAL_NOT_FOUND, generateResumeToken, getPendingApprovals, getPlaybookSecret, rejectGate, } from './approval.js';
+// PSYCHE E4 migration tool (T1261) — STRICT cutover validator + migrator
+export { migratePlaybook, migratePlaybookFile, validatePlaybookCompliance, } from './migrate-e4.js';
 // W4-7: .cantbook YAML parser → PlaybookDefinition
 export { PlaybookParseError, parsePlaybook, } from './parser.js';
 // W4-9: HITL auto-policy evaluator

package/dist/migrate-e4.d.ts

@@ -0,0 +1,103 @@
+/**
+ * PSYCHE E4 STRICT cutover migration tool for `.cantbook` files.
+ *
+ * Per Council mandate (T1261 ADR-055 STRICT cutover): all `.cantbook` files
+ * MUST comply with the E4 DSL contract before the v2026.4.129 ship. This
+ * module provides:
+ *
+ * 1. {@link validatePlaybookCompliance} — pure validator, returns compliance
+ *    report without modifying files.
+ * 2. {@link migratePlaybook} — enriches a `.cantbook` source string with
+ *    minimal E4-compatible scaffolding (adds skeleton error_handlers if
+ *    absent, adds requires/ensures stubs to nodes without them).
+ * 3. {@link migratePlaybookFile} — reads, migrates, and optionally writes a
+ *    `.cantbook` file in place. Dry-run mode returns the migrated source
+ *    without writing.
+ *
+ * STRICT cutover policy (no opt-in flag):
+ * - All existing `.cantbook` files MUST be validated/migrated at E4 ship.
+ * - The starter playbooks (rcasd, ivtr, release) ship with full E4 DSL and
+ *   pass validation without modification.
+ * - User-authored playbooks MUST run this tool before using the E4 runtime.
+ *
+ * @task T1261 PSYCHE E4 — STRICT cutover migration
+ */
+/** Per-node compliance entry. */
+export interface NodeComplianceEntry {
+    /** Node id. */
+    id: string;
+    /** Node type. */
+    type: string;
+    /** Whether the node has a `requires` block. */
+    hasRequires: boolean;
+    /** Whether the node has an `ensures` block. */
+    hasEnsures: boolean;
+}
+/**
+ * Result of {@link validatePlaybookCompliance}. Reports which E4 DSL
+ * features are present and which are missing.
+ */
+export interface PlaybookComplianceReport {
+    /** Whether the file parses successfully (pre-condition). */
+    parses: boolean;
+    /** Parse error message when `parses === false`. */
+    parseError?: string;
+    /** Whether the file has at least one `error_handlers` entry. */
+    hasErrorHandlers: boolean;
+    /** Number of agentic nodes missing `requires` (first predecessor context). */
+    nodesMissingRequires: number;
+    /** Number of nodes missing `ensures` (output guarantee). */
+    nodesMissingEnsures: number;
+    /** Per-node breakdown. */
+    nodes: NodeComplianceEntry[];
+    /** `true` when all E4 requirements are satisfied. */
+    compliant: boolean;
+}
+/**
+ * Validate a `.cantbook` source string for E4 DSL compliance without
+ * modifying it.
+ *
+ * @param source - Raw `.cantbook` YAML text.
+ * @returns A compliance report. Callers should check `compliant` before
+ *          running the playbook.
+ */
+export declare function validatePlaybookCompliance(source: string): PlaybookComplianceReport;
+/**
+ * Apply PSYCHE E4 STRICT cutover scaffolding to a `.cantbook` source string.
+ *
+ * Conservative strategy: adds skeleton DSL where absent; never removes or
+ * modifies existing DSL. Callers should review the migrated output before
+ * writing to disk.
+ *
+ * Migrations applied:
+ * - Adds a default `error_handlers` block if absent (iteration_cap_exceeded
+ *   → hitl_escalate + contract_violation → inject_hint).
+ * - Adds a stub `requires: {}` to work nodes (non-approval) that lack it.
+ * - Adds a stub `ensures: {}` to work nodes that lack it.
+ *
+ * @param source - Raw `.cantbook` YAML text.
+ * @returns The migrated YAML source string.
+ * @throws {PlaybookParseError} when the source cannot be parsed.
+ */
+export declare function migratePlaybook(source: string): string;
+/** Result of {@link migratePlaybookFile}. */
+export interface MigratePlaybookFileResult {
+    /** Path that was processed. */
+    filePath: string;
+    /** Pre-migration compliance report. */
+    before: PlaybookComplianceReport;
+    /** Post-migration compliance report (same as `before` in dry-run mode). */
+    after: PlaybookComplianceReport;
+    /** Whether the file was written (false in dry-run mode). */
+    written: boolean;
+    /** Migrated YAML source (always set, even in dry-run mode). */
+    migratedSource: string;
+}
+/**
+ * Read, validate, migrate, and optionally write a `.cantbook` file.
+ *
+ * @param filePath - Absolute path to the `.cantbook` file.
+ * @param dryRun - When `true`, return the migrated source without writing.
+ * @returns Migration result including before/after compliance reports.
+ */
+export declare function migratePlaybookFile(filePath: string, dryRun?: boolean): MigratePlaybookFileResult;

package/dist/migrate-e4.js

@@ -0,0 +1,163 @@
+/**
+ * PSYCHE E4 STRICT cutover migration tool for `.cantbook` files.
+ *
+ * Per Council mandate (T1261 ADR-055 STRICT cutover): all `.cantbook` files
+ * MUST comply with the E4 DSL contract before the v2026.4.129 ship. This
+ * module provides:
+ *
+ * 1. {@link validatePlaybookCompliance} — pure validator, returns compliance
+ *    report without modifying files.
+ * 2. {@link migratePlaybook} — enriches a `.cantbook` source string with
+ *    minimal E4-compatible scaffolding (adds skeleton error_handlers if
+ *    absent, adds requires/ensures stubs to nodes without them).
+ * 3. {@link migratePlaybookFile} — reads, migrates, and optionally writes a
+ *    `.cantbook` file in place. Dry-run mode returns the migrated source
+ *    without writing.
+ *
+ * STRICT cutover policy (no opt-in flag):
+ * - All existing `.cantbook` files MUST be validated/migrated at E4 ship.
+ * - The starter playbooks (rcasd, ivtr, release) ship with full E4 DSL and
+ *   pass validation without modification.
+ * - User-authored playbooks MUST run this tool before using the E4 runtime.
+ *
+ * @task T1261 PSYCHE E4 — STRICT cutover migration
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dump as yamlDump, load as yamlLoad } from 'js-yaml';
+import { PlaybookParseError, parsePlaybook } from './parser.js';
+/**
+ * Validate a `.cantbook` source string for E4 DSL compliance without
+ * modifying it.
+ *
+ * @param source - Raw `.cantbook` YAML text.
+ * @returns A compliance report. Callers should check `compliant` before
+ *          running the playbook.
+ */
+export function validatePlaybookCompliance(source) {
+    let parsed;
+    try {
+        parsed = parsePlaybook(source);
+    }
+    catch (err) {
+        return {
+            parses: false,
+            parseError: err instanceof PlaybookParseError ? err.message : String(err),
+            hasErrorHandlers: false,
+            nodesMissingRequires: 0,
+            nodesMissingEnsures: 0,
+            nodes: [],
+            compliant: false,
+        };
+    }
+    const { definition } = parsed;
+    const hasErrorHandlers = (definition.error_handlers?.length ?? 0) > 0;
+    const nodeEntries = definition.nodes.map((n) => ({
+        id: n.id,
+        type: n.type,
+        hasRequires: n.requires !== undefined,
+        hasEnsures: n.ensures !== undefined,
+    }));
+    // Agentic + deterministic nodes should have requires/ensures; approval
+    // nodes are exempt (they are gate-only, not data-producing).
+    const workNodes = nodeEntries.filter((e) => e.type !== 'approval');
+    const nodesMissingRequires = workNodes.filter((e) => !e.hasRequires).length;
+    const nodesMissingEnsures = workNodes.filter((e) => !e.hasEnsures).length;
+    const compliant = hasErrorHandlers && nodesMissingRequires === 0 && nodesMissingEnsures === 0;
+    return {
+        parses: true,
+        hasErrorHandlers,
+        nodesMissingRequires,
+        nodesMissingEnsures,
+        nodes: nodeEntries,
+        compliant,
+    };
+}
+// ---------------------------------------------------------------------------
+// Migration
+// ---------------------------------------------------------------------------
+/**
+ * Apply PSYCHE E4 STRICT cutover scaffolding to a `.cantbook` source string.
+ *
+ * Conservative strategy: adds skeleton DSL where absent; never removes or
+ * modifies existing DSL. Callers should review the migrated output before
+ * writing to disk.
+ *
+ * Migrations applied:
+ * - Adds a default `error_handlers` block if absent (iteration_cap_exceeded
+ *   → hitl_escalate + contract_violation → inject_hint).
+ * - Adds a stub `requires: {}` to work nodes (non-approval) that lack it.
+ * - Adds a stub `ensures: {}` to work nodes that lack it.
+ *
+ * @param source - Raw `.cantbook` YAML text.
+ * @returns The migrated YAML source string.
+ * @throws {PlaybookParseError} when the source cannot be parsed.
+ */
+export function migratePlaybook(source) {
+    // Parse first to validate structural correctness.
+    parsePlaybook(source);
+    // Work on the raw YAML object so we preserve ordering and comments where
+    // possible (js-yaml dump always re-serialises, but it's the safest
+    // approach for a migration tool).
+    const raw = yamlLoad(source);
+    // 1. Ensure error_handlers exists.
+    if (!Array.isArray(raw.error_handlers) || raw.error_handlers.length === 0) {
+        raw.error_handlers = [
+            {
+                on: 'iteration_cap_exceeded',
+                action: 'hitl_escalate',
+                message: 'Stage exhausted retries — escalate to human for direction.',
+            },
+            {
+                on: 'contract_violation',
+                action: 'inject_hint',
+                message: 'Contract violated at stage boundary — check requires/ensures fields.',
+            },
+        ];
+    }
+    // 2. Add requires/ensures stubs to work nodes.
+    if (Array.isArray(raw.nodes)) {
+        raw.nodes = raw.nodes.map((node) => {
+            if (node.type === 'approval')
+                return node; // approval nodes exempt
+            const patched = { ...node };
+            if (!patched.requires)
+                patched.requires = {};
+            if (!patched.ensures)
+                patched.ensures = {};
+            return patched;
+        });
+    }
+    return yamlDump(raw, { lineWidth: 100, noRefs: true });
+}
+/**
+ * Read, validate, migrate, and optionally write a `.cantbook` file.
+ *
+ * @param filePath - Absolute path to the `.cantbook` file.
+ * @param dryRun - When `true`, return the migrated source without writing.
+ * @returns Migration result including before/after compliance reports.
+ */
+export function migratePlaybookFile(filePath, dryRun = false) {
+    const source = readFileSync(filePath, 'utf8');
+    const before = validatePlaybookCompliance(source);
+    if (!before.parses) {
+        return {
+            filePath,
+            before,
+            after: before,
+            written: false,
+            migratedSource: source,
+        };
+    }
+    const migratedSource = migratePlaybook(source);
+    const after = validatePlaybookCompliance(migratedSource);
+    if (!dryRun && !before.compliant) {
+        writeFileSync(filePath, migratedSource, 'utf8');
+    }
+    return {
+        filePath,
+        before,
+        after,
+        written: !dryRun && !before.compliant,
+        migratedSource,
+    };
+}

package/dist/parser.d.ts

@@ -17,12 +17,14 @@
  *   - every edge.from + edge.to MUST reference a known node id
  *   - nodes form a DAG when combined with edges (no cycles)
  *   - agentic nodes MUST have skill OR agent (at least one)
+ *   - agentic nodes MAY have context_files (thin-agent boundary, T1261 E4)
  *   - deterministic nodes MUST have command + args
  *   - approval nodes MUST have prompt
  *   - depends[] entries MUST be valid node ids
  *   - iteration_cap (max_iterations) MUST be 0..10 (hard limit)
  *
  * @task T889 / T904 / W4-7
+ * @task T1261 PSYCHE E4 — context_files thin-agent boundary
  */
 import type { PlaybookDefinition } from '@cleocode/contracts';
 /**

package/dist/parser.js

@@ -17,12 +17,14 @@
  *   - every edge.from + edge.to MUST reference a known node id
  *   - nodes form a DAG when combined with edges (no cycles)
  *   - agentic nodes MUST have skill OR agent (at least one)
+ *   - agentic nodes MAY have context_files (thin-agent boundary, T1261 E4)
  *   - deterministic nodes MUST have command + args
  *   - approval nodes MUST have prompt
  *   - depends[] entries MUST be valid node ids
  *   - iteration_cap (max_iterations) MUST be 0..10 (hard limit)
  *
  * @task T889 / T904 / W4-7
+ * @task T1261 PSYCHE E4 — context_files thin-agent boundary
  */
 import { createHash } from 'node:crypto';
 import { load as yamlLoad } from 'js-yaml';
@@ -227,6 +229,7 @@ function parseAgenticNode(raw, base, index) {
         }
         inputs = acc;
     }
+    const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
     return {
         ...base,
         type: 'agentic',
@@ -234,6 +237,7 @@ function parseAgenticNode(raw, base, index) {
         agent,
         role,
         inputs,
+        ...(context_files !== undefined ? { context_files } : {}),
     };
 }
 function parseDeterministicNode(raw, base, index) {

package/dist/runtime.d.ts

@@ -26,8 +26,13 @@
  *    written with the HMAC-signed resume token, and the returned
  *    {@link ExecutePlaybookResult.approvalToken} is what the human reviewer
  *    must present via `resumePlaybook` to continue.
+ * 5. Contract enforcement (T1261 PSYCHE E4) — requires/ensures DSL validated
+ *    at every node boundary. Violations are appended to
+ *    `.cleo/audit/contract-violations.jsonl` and trigger the `contract_violation`
+ *    error_handler (inject_hint | hitl_escalate | abort).
  *
  * @task T930 — Playbook Runtime State Machine
+ * @task T1261 PSYCHE E4 — contract enforcement + context boundary
  */
 import type { DatabaseSync } from 'node:sqlite';
 import type { PlaybookDefinition } from '@cleocode/contracts';
@@ -131,12 +136,13 @@ export interface ExecutePlaybookOptions {
     sessionId?: string;
     /** Injectable clock for deterministic tests (defaults to `() => new Date()`). */
     now?: () => Date;
+    /**
+     * Project root for contract-violation audit writes (T1261 PSYCHE E4).
+     * When absent, contract violations are still enforced but not appended to
+     * `.cleo/audit/contract-violations.jsonl`.
+     */
+    projectRoot?: string;
 }
-/**
- * Options accepted by {@link resumePlaybook}. The runtime validates that the
- * supplied approval token resolves to an `approved` {@link PlaybookApproval}
- * row before continuing execution.
- */
 export interface ResumePlaybookOptions {
     db: DatabaseSync;
     playbook: PlaybookDefinition;
@@ -147,7 +153,12 @@ export interface ResumePlaybookOptions {
     approvalSecret?: string;
     maxIterationsDefault?: number;
     now?: () => Date;
+    /**
+     * Project root for contract-violation audit writes (T1261 PSYCHE E4).
+     */
+    projectRoot?: string;
 }
+/**
 /**
  * Terminal status values reported by the runtime.
  */

package/dist/runtime.js

@@ -26,8 +26,13 @@
  *    written with the HMAC-signed resume token, and the returned
  *    {@link ExecutePlaybookResult.approvalToken} is what the human reviewer
  *    must present via `resumePlaybook` to continue.
+ * 5. Contract enforcement (T1261 PSYCHE E4) — requires/ensures DSL validated
+ *    at every node boundary. Violations are appended to
+ *    `.cleo/audit/contract-violations.jsonl` and trigger the `contract_violation`
+ *    error_handler (inject_hint | hitl_escalate | abort).
  *
  * @task T930 — Playbook Runtime State Machine
+ * @task T1261 PSYCHE E4 — contract enforcement + context boundary
  */
 import { createApprovalGate, getPlaybookSecret } from './approval.js';
 import { createPlaybookApproval, createPlaybookRun, getPlaybookApprovalByToken, getPlaybookRun, updatePlaybookRun, } from './state.js';
@@ -257,6 +262,75 @@ function executeApprovalNode(node, runId, context, db, secret) {
 // ---------------------------------------------------------------------------
 // Main execution loop
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Contract enforcement helpers (T1261 PSYCHE E4)
+// ---------------------------------------------------------------------------
+/**
+ * Check that all required fields from a predecessor node are present in the
+ * current execution context.
+ *
+ * @param fields - List of keys that must be in `context`.
+ * @param from - Optional predecessor node id for error message context.
+ * @param context - Current accumulated run context.
+ * @returns `null` if all fields are present; a human-readable violation
+ *          description otherwise.
+ */
+function checkRequires(fields, from, context) {
+    for (const key of fields) {
+        if (!(key in context)) {
+            const source = from !== undefined ? ` (from node '${from}')` : '';
+            return `requires.fields['${key}']${source} not present in context`;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the first outgoing edge from `fromId` to `toId` in the playbook edge
+ * list. Returns `undefined` when no explicit edge exists.
+ */
+function resolveEdge(fromId, toId, edges) {
+    return edges.find((e) => e.from === fromId && e.to === toId);
+}
+/**
+ * Best-effort contract violation audit write. Non-fatal: errors are swallowed
+ * so a broken filesystem never blocks playbook execution.
+ *
+ * Writes to `<projectRoot>/.cleo/audit/contract-violations.jsonl` following
+ * the ADR-039 pattern.
+ */
+function auditContractViolation(projectRoot, runId, nodeId, field, key, playbookName) {
+    if (!projectRoot)
+        return;
+    try {
+        // Lazy-import to avoid a hard dep on @cleocode/core from @cleocode/playbooks.
+        // The audit is best-effort; we swallow any dynamic import failure.
+        void import('@cleocode/core').then(({ appendContractViolation }) => {
+            appendContractViolation(projectRoot, {
+                runId,
+                nodeId,
+                field,
+                key,
+                message: `contract_violation: ${field}['${key}'] check failed on node '${nodeId}'`,
+                playbookName,
+            });
+        });
+    }
+    catch {
+        // non-fatal
+    }
+}
+/**
+ * Map a `contract_violation` trigger to the registered error handler action.
+ *
+ * @returns `'inject_hint'` | `'hitl_escalate'` | `'abort'` based on the
+ *          first matching handler, or `null` when no handler is registered.
+ */
+function handleContractErrorHandler(playbook, trigger, _message) {
+    if (!playbook.error_handlers)
+        return null;
+    const handler = playbook.error_handlers.find((h) => h.on === trigger);
+    return handler?.action ?? null;
+}
 /**
  * Determine the effective iteration cap for a node. Falls back to the
  * runtime default (3) when `on_failure.max_iterations` is unset. The parser
@@ -282,7 +356,7 @@ function iterationCapFor(node, runtimeDefault) {
  * @internal
  */
 async function runFromNode(args) {
-    const { db, run, startNodeId, nodeIndex, edgeIndex, context, iterationCounts, dispatcher, deterministicRunner, approvalSecret, maxIterationsDefault, now, } = args;
+    const { db, playbook, run, startNodeId, nodeIndex, edgeIndex, context, iterationCounts, dispatcher, deterministicRunner, approvalSecret, maxIterationsDefault, now, } = args;
     let currentId = startNodeId;
     let lastError;
     let failedNodeId;
@@ -298,6 +372,31 @@ async function runFromNode(args) {
             currentNode: node.id,
             iterationCounts: { ...iterationCounts },
         });
+        // Contract enforcement (T1261 E4): validate node.requires BEFORE dispatch.
+        // On violation, trigger contract_violation error handler or fail the node.
+        if (node.requires?.fields) {
+            const violation = checkRequires(node.requires.fields, node.requires.from, context);
+            if (violation !== null) {
+                const contractFailure = `contract_violation: ${violation}`;
+                auditContractViolation(args.projectRoot, run.runId, node.id, 'requires', violation, playbook.name);
+                const handled = handleContractErrorHandler(playbook, 'contract_violation', contractFailure);
+                if (handled === 'abort') {
+                    failedNodeId = node.id;
+                    lastError = contractFailure;
+                    break;
+                }
+                if (handled !== null) {
+                    context['__lastError'] = contractFailure;
+                    context['__lastFailedNode'] = node.id;
+                    context['__contractViolation'] = violation;
+                    if (handled === 'hitl_escalate') {
+                        exceededNodeId = node.id;
+                        break;
+                    }
+                    // inject_hint: continue to dispatch with the hint in context
+                }
+            }
+        }
         let outcome;
         if (node.type === 'agentic') {
             outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher);
@@ -318,7 +417,40 @@ async function runFromNode(args) {
             // Merge outputs into context and persist.
             Object.assign(context, outcome.output);
             updatePlaybookRun(db, run.runId, { bindings: { ...context } });
-            currentId = resolveNextNodeId(node.id, edgeIndex);
+            // Contract enforcement (T1261 E4): validate node.ensures AFTER merge.
+            if (node.ensures?.outputFiles) {
+                for (const key of node.ensures.outputFiles) {
+                    if (!(key in context)) {
+                        const violation = `ensures.outputFiles[${key}] not present in context after ${node.id}`;
+                        auditContractViolation(args.projectRoot, run.runId, node.id, 'ensures', key, playbook.name);
+                        handleContractErrorHandler(playbook, 'contract_violation', violation);
+                        context['__ensuresViolation'] = violation;
+                    }
+                }
+            }
+            // Validate outgoing edge contracts (edge.contract.requires on the FROM side).
+            const nextId = resolveNextNodeId(node.id, edgeIndex);
+            if (nextId !== null) {
+                const edge = resolveEdge(node.id, nextId, playbook.edges);
+                if (edge?.contract?.requires) {
+                    for (const key of edge.contract.requires) {
+                        if (!(key in context)) {
+                            const violation = `edge.contract.requires[${key}] missing when crossing ${node.id} → ${nextId}`;
+                            auditContractViolation(args.projectRoot, run.runId, node.id, 'requires', key, playbook.name);
+                            const handled = handleContractErrorHandler(playbook, 'contract_violation', violation);
+                            if (handled === 'abort') {
+                                failedNodeId = node.id;
+                                lastError = violation;
+                                break;
+                            }
+                            context['__contractViolation'] = violation;
+                        }
+                    }
+                    if (failedNodeId !== undefined)
+                        break;
+                }
+            }
+            currentId = nextId;
             continue;
         }
         if (outcome.kind === 'awaiting_approval') {
@@ -488,6 +620,7 @@ export async function executePlaybook(options) {
         approvalSecret,
         maxIterationsDefault,
         now,
+        projectRoot: options.projectRoot,
     };
     return runFromNode(runArgs);
 }
@@ -596,6 +729,7 @@ export async function resumePlaybook(options) {
         approvalSecret,
         maxIterationsDefault,
         now,
+        projectRoot: options.projectRoot,
     };
     return runFromNode(runArgs);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/playbooks",
-  "version": "2026.4.128",
+  "version": "2026.4.129",
   "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-beta.22-ec7b61d",
     "js-yaml": "^4.1.0",
-    "@cleocode/contracts": "2026.4.128",
-    "@cleocode/core": "2026.4.128"
+    "@cleocode/contracts": "2026.4.129",
+    "@cleocode/core": "2026.4.129"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",