@cleocode/playbooks 2026.4.128 → 2026.4.129

package/src/__tests__/migrate-e4.test.ts

@@ -0,0 +1,251 @@
+/**
+ * PSYCHE E4 migration tool tests.
+ *
+ * Validates the STRICT cutover compliance validator and migration function.
+ * No disk I/O; uses inline YAML strings.
+ *
+ * @task T1261 PSYCHE E4
+ */
+
+import { describe, expect, it } from 'vitest';
+import { migratePlaybook, validatePlaybookCompliance } from '../migrate-e4.js';
+
+// ---------------------------------------------------------------------------
+// Shared fixtures
+// ---------------------------------------------------------------------------
+
+const MINIMAL_COMPLIANT = `
+version: "1.0"
+name: compliant
+nodes:
+  - id: start
+    type: agentic
+    skill: ct-research-agent
+    requires:
+      from: ctx
+      fields: [input]
+    ensures:
+      schema: output_summary
+edges: []
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+`;
+
+const MINIMAL_NON_COMPLIANT = `
+version: "1.0"
+name: legacy
+nodes:
+  - id: start
+    type: agentic
+    skill: ct-research-agent
+edges: []
+`;
+
+const MINIMAL_PARTIAL = `
+version: "1.0"
+name: partial
+nodes:
+  - id: start
+    type: agentic
+    skill: ct-research-agent
+    requires:
+      fields: [input]
+edges: []
+`;
+
+// ---------------------------------------------------------------------------
+// validatePlaybookCompliance
+// ---------------------------------------------------------------------------
+
+describe('T1261-E4: validatePlaybookCompliance', () => {
+  it('returns compliant=true for a fully-wired playbook', () => {
+    const report = validatePlaybookCompliance(MINIMAL_COMPLIANT);
+    expect(report.parses).toBe(true);
+    expect(report.compliant).toBe(true);
+    expect(report.hasErrorHandlers).toBe(true);
+    expect(report.nodesMissingRequires).toBe(0);
+    expect(report.nodesMissingEnsures).toBe(0);
+  });
+
+  it('returns compliant=false when error_handlers is absent', () => {
+    const report = validatePlaybookCompliance(MINIMAL_PARTIAL);
+    expect(report.parses).toBe(true);
+    expect(report.compliant).toBe(false);
+    expect(report.hasErrorHandlers).toBe(false);
+  });
+
+  it('returns compliant=false when nodes lack requires/ensures', () => {
+    const report = validatePlaybookCompliance(MINIMAL_NON_COMPLIANT);
+    expect(report.parses).toBe(true);
+    expect(report.compliant).toBe(false);
+    expect(report.nodesMissingRequires).toBe(1);
+    expect(report.nodesMissingEnsures).toBe(1);
+  });
+
+  it('returns parses=false for invalid YAML', () => {
+    const report = validatePlaybookCompliance('version: "1.0"\n  : broken');
+    expect(report.parses).toBe(false);
+    expect(report.compliant).toBe(false);
+    expect(report.parseError).toBeDefined();
+  });
+
+  it('reports correct node breakdown', () => {
+    const report = validatePlaybookCompliance(MINIMAL_NON_COMPLIANT);
+    expect(report.nodes).toHaveLength(1);
+    expect(report.nodes[0]).toMatchObject({
+      id: 'start',
+      type: 'agentic',
+      hasRequires: false,
+      hasEnsures: false,
+    });
+  });
+
+  it('exempts approval nodes from requires/ensures check', () => {
+    const yaml = `
+version: "1.0"
+name: with-approval
+nodes:
+  - id: work
+    type: agentic
+    skill: ct-task-executor
+    requires:
+      fields: [input]
+    ensures:
+      schema: output
+  - id: gate
+    type: approval
+    prompt: "Approve release?"
+edges:
+  - from: work
+    to: gate
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+`;
+    const report = validatePlaybookCompliance(yaml);
+    expect(report.compliant).toBe(true);
+    expect(report.nodes.find((n) => n.id === 'gate')).toMatchObject({
+      type: 'approval',
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// migratePlaybook
+// ---------------------------------------------------------------------------
+
+describe('T1261-E4: migratePlaybook', () => {
+  it('adds error_handlers when absent', () => {
+    const migrated = migratePlaybook(MINIMAL_NON_COMPLIANT);
+    const report = validatePlaybookCompliance(migrated);
+    expect(report.hasErrorHandlers).toBe(true);
+  });
+
+  it('adds requires/ensures stubs to work nodes', () => {
+    const migrated = migratePlaybook(MINIMAL_NON_COMPLIANT);
+    const report = validatePlaybookCompliance(migrated);
+    expect(report.nodesMissingRequires).toBe(0);
+    expect(report.nodesMissingEnsures).toBe(0);
+    expect(report.compliant).toBe(true);
+  });
+
+  it('preserves existing error_handlers when present', () => {
+    const migrated = migratePlaybook(MINIMAL_PARTIAL);
+    // MINIMAL_PARTIAL has requires but no error_handlers/ensures
+    const report = validatePlaybookCompliance(migrated);
+    expect(report.parses).toBe(true);
+    // ensures gets added
+    expect(report.nodesMissingEnsures).toBe(0);
+  });
+
+  it('does not double-add requires/ensures when already present', () => {
+    // Migrating a compliant playbook should return parseable output
+    const migrated = migratePlaybook(MINIMAL_COMPLIANT);
+    const report = validatePlaybookCompliance(migrated);
+    expect(report.compliant).toBe(true);
+  });
+
+  it('throws PlaybookParseError on structurally invalid source', () => {
+    const invalid = `
+version: "1.0"
+name: bad
+nodes: []
+`;
+    // nodes must be non-empty per parser
+    expect(() => migratePlaybook(invalid)).toThrow();
+  });
+
+  it('does not modify approval nodes', () => {
+    const yaml = `
+version: "1.0"
+name: has-approval
+nodes:
+  - id: step
+    type: agentic
+    skill: ct-task-executor
+  - id: gate
+    type: approval
+    prompt: "Approve?"
+edges: []
+error_handlers:
+  - on: iteration_cap_exceeded
+    action: hitl_escalate
+`;
+    const migrated = migratePlaybook(yaml);
+    const report = validatePlaybookCompliance(migrated);
+    // approval node should still be exempted
+    const approvalEntry = report.nodes.find((n) => n.id === 'gate');
+    expect(approvalEntry?.type).toBe('approval');
+    expect(report.compliant).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// context_files parser support (T1261 E4 thin-agent boundary)
+// ---------------------------------------------------------------------------
+
+describe('T1261-E4: context_files parser support', () => {
+  it('parses context_files on an agentic node', async () => {
+    const { parsePlaybook } = await import('../parser.js');
+    const yaml = `
+version: "1.0"
+name: bounded
+nodes:
+  - id: worker
+    type: agentic
+    skill: ct-task-executor
+    context_files:
+      - packages/core/src/foo.ts
+      - packages/contracts/src/index.ts
+edges: []
+`;
+    const { definition } = parsePlaybook(yaml);
+    const node = definition.nodes[0];
+    expect(node.type).toBe('agentic');
+    if (node.type === 'agentic') {
+      expect(node.context_files).toEqual([
+        'packages/core/src/foo.ts',
+        'packages/contracts/src/index.ts',
+      ]);
+    }
+  });
+
+  it('context_files is optional — absent nodes have undefined', async () => {
+    const { parsePlaybook } = await import('../parser.js');
+    const yaml = `
+version: "1.0"
+name: unbounded
+nodes:
+  - id: worker
+    type: agentic
+    skill: ct-task-executor
+edges: []
+`;
+    const { definition } = parsePlaybook(yaml);
+    const node = definition.nodes[0];
+    if (node.type === 'agentic') {
+      expect(node.context_files).toBeUndefined();
+    }
+  });
+});

package/src/__tests__/starter.e2e.test.ts

@@ -110,15 +110,63 @@ function makeRecordingDispatcher(
 
 /**
  * Default "always succeed" handler that echoes the node id into the context
- * via `{<nodeId>_done: true}`. Enough for the happy-path assertions.
+ * via `{<nodeId>_done: true}`, plus enough fields to satisfy the ivtr/rcasd
+ * `requires` contracts so the E4 contract enforcement (T1261) doesn't fire.
+ *
+ * Fields added per-node follow the starter playbook schemas:
+ *   - implement → diff (validate.requires.fields includes 'diff')
+ *   - validate  → passed (test.requires.fields includes 'passed')
+ *   - research  → summary, risks (consensus.requires.fields)
+ *   - consensus → decision (architecture.requires.fields)
+ *   - architecture → patterns, adrs (specification.requires.fields)
+ *   - specification → acceptance, requirements (decomposition.requires.fields)
+ *   - version_bump → versionBumped (changelog.requires.fields)
+ *   - changelog → changelogUpdated (approval edge.contract.ensures)
  */
 function alwaysSucceed(input: AgentDispatchInput): AgentDispatchResult {
+  const extraFields: Record<string, unknown> = {};
+  switch (input.nodeId) {
+    case 'implement':
+      extraFields.diff = `diff-${input.runId}`;
+      break;
+    case 'validate':
+      extraFields.passed = true;
+      break;
+    case 'research':
+      extraFields.summary = 'research summary';
+      extraFields.risks = [];
+      break;
+    case 'consensus':
+      extraFields.decision = 'consensus decision';
+      break;
+    case 'architecture':
+      extraFields.patterns = [];
+      extraFields.adrs = [];
+      break;
+    case 'specification':
+      extraFields.acceptance = [];
+      extraFields.requirements = [];
+      break;
+    case 'version_bump':
+      extraFields.versionBumped = true;
+      break;
+    case 'changelog':
+      extraFields.changelogUpdated = true;
+      extraFields.published = false;
+      break;
+    case 'publish':
+      extraFields.published = true;
+      break;
+    default:
+      break;
+  }
   return {
     status: 'success',
     output: {
       [`${input.nodeId}_done`]: true,
       lastNode: input.nodeId,
       lastAgent: input.agentId,
+      ...extraFields,
     },
   };
 }

package/src/index.ts

@@ -23,7 +23,7 @@
  * 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: string = '2026.4.85';
+export const PLAYBOOKS_PACKAGE_VERSION: string = '2026.4.129';
 
 export {
   approveGate,
@@ -36,6 +36,15 @@ export {
   getPlaybookSecret,
   rejectGate,
 } from './approval.js';
+// PSYCHE E4 migration tool (T1261) — STRICT cutover validator + migrator
+export {
+  type MigratePlaybookFileResult,
+  migratePlaybook,
+  migratePlaybookFile,
+  type NodeComplianceEntry,
+  type PlaybookComplianceReport,
+  validatePlaybookCompliance,
+} from './migrate-e4.js';
 // W4-7: .cantbook YAML parser → PlaybookDefinition
 export {
   type ParsePlaybookResult,

package/src/migrate-e4.ts

@@ -0,0 +1,232 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Compliance report
+// ---------------------------------------------------------------------------
+
+/** 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 function validatePlaybookCompliance(source: string): PlaybookComplianceReport {
+  let parsed: ReturnType<typeof parsePlaybook>;
+  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: NodeComplianceEntry[] = 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: string): string {
+  // 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) as Record<string, unknown>;
+
+  // 1. Ensure error_handlers exists.
+  if (!Array.isArray(raw.error_handlers) || (raw.error_handlers as unknown[]).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 as Record<string, unknown>[]).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 });
+}
+
+// ---------------------------------------------------------------------------
+// File I/O helper
+// ---------------------------------------------------------------------------
+
+/** 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 function migratePlaybookFile(filePath: string, dryRun = false): MigratePlaybookFileResult {
+  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/src/parser.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 { createHash } from 'node:crypto';
@@ -332,6 +334,8 @@ function parseAgenticNode(
     inputs = acc;
   }
 
+  const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
+
   return {
     ...base,
     type: 'agentic',
@@ -339,6 +343,7 @@ function parseAgenticNode(
     agent,
     role,
     inputs,
+    ...(context_files !== undefined ? { context_files } : {}),
   };
 }