@cleocode/cleo 2026.4.127 → 2026.4.129

package/dist/cli/index.js

@@ -7669,6 +7669,32 @@ var init_registry = __esm({
           }
         ]
       },
+      // ── playbook.validate (T1261 PSYCHE E4) ──────────────────────────────────
+      {
+        gateway: "query",
+        domain: "playbook",
+        operation: "validate",
+        description: "playbook.validate (query) \u2014 parse and validate a .cantbook file without executing it; exit 0 on success, exit 70 on parse error",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: [],
+        params: [
+          {
+            name: "file",
+            type: "string",
+            required: false,
+            description: "Absolute or relative path to the .cantbook file",
+            cli: { positional: true }
+          },
+          {
+            name: "name",
+            type: "string",
+            required: false,
+            description: "Playbook name (resolved through the standard search path)"
+          }
+        ]
+      },
       // ── orchestrate.{approve,reject,pending} HITL gate decisions (T935) ──────
       {
         gateway: "mutate",
@@ -9782,7 +9808,7 @@ async function applyCantBodySubstitution(payload, cwd, ctx) {
   if (!cantPath) {
     return { ...empty, reason: "resolved agent has no cantPath" };
   }
-  const [{ existsSync: existsSync12, readFileSync: readFileSync15 }, { substituteCantAgentBody }] = await Promise.all([
+  const [{ existsSync: existsSync12, readFileSync: readFileSync16 }, { substituteCantAgentBody }] = await Promise.all([
     import("node:fs"),
     import("@cleocode/core/internal")
   ]);
@@ -9791,7 +9817,7 @@ async function applyCantBodySubstitution(payload, cwd, ctx) {
   }
   let body;
   try {
-    body = readFileSync15(cantPath, "utf-8");
+    body = readFileSync16(cantPath, "utf-8");
   } catch (err) {
     return {
       ...empty,
@@ -24527,13 +24553,15 @@ function parseAgenticNode(raw, base, index) {
     }
     inputs = acc;
   }
+  const context_files = parseStringArray(raw.context_files, `nodes[${index}].context_files`);
   return {
     ...base,
     type: "agentic",
     skill,
     agent,
     role,
-    inputs
+    inputs,
+    ...context_files !== void 0 ? { context_files } : {}
   };
 }
 function parseDeterministicNode(raw, base, index) {
@@ -24893,6 +24921,105 @@ var init_parser = __esm({
   }
 });
 
+// packages/playbooks/src/migrate-e4.ts
+import { readFileSync as readFileSync5, writeFileSync } from "node:fs";
+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 !== void 0,
+    hasEnsures: n.ensures !== void 0
+  }));
+  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
+  };
+}
+function migratePlaybook(source) {
+  parsePlaybook(source);
+  const raw = load(source);
+  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 \u2014 escalate to human for direction."
+      },
+      {
+        on: "contract_violation",
+        action: "inject_hint",
+        message: "Contract violated at stage boundary \u2014 check requires/ensures fields."
+      }
+    ];
+  }
+  if (Array.isArray(raw.nodes)) {
+    raw.nodes = raw.nodes.map((node) => {
+      if (node.type === "approval") return node;
+      const patched = { ...node };
+      if (!patched.requires) patched.requires = {};
+      if (!patched.ensures) patched.ensures = {};
+      return patched;
+    });
+  }
+  return dump(raw, { lineWidth: 100, noRefs: true });
+}
+function migratePlaybookFile(filePath, dryRun = false) {
+  const source = readFileSync5(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
+  };
+}
+var init_migrate_e4 = __esm({
+  "packages/playbooks/src/migrate-e4.ts"() {
+    "use strict";
+    init_js_yaml();
+    init_parser();
+  }
+});
+
 // packages/playbooks/src/policy.ts
 function evaluatePolicy(command, rules = DEFAULT_POLICY_RULES) {
   for (const rule of rules) {
@@ -25364,6 +25491,39 @@ function executeApprovalNode(node, runId, context, db, secret) {
   });
   return { kind: "awaiting_approval", token: gate.token, approvalId: gate.approvalId };
 }
+function checkRequires(fields, from, context) {
+  for (const key of fields) {
+    if (!(key in context)) {
+      const source = from !== void 0 ? ` (from node '${from}')` : "";
+      return `requires.fields['${key}']${source} not present in context`;
+    }
+  }
+  return null;
+}
+function resolveEdge(fromId, toId, edges) {
+  return edges.find((e) => e.from === fromId && e.to === toId);
+}
+function auditContractViolation(projectRoot, runId, nodeId, field, key, playbookName) {
+  if (!projectRoot) return;
+  try {
+    void import("@cleocode/core").then(({ appendContractViolation }) => {
+      appendContractViolation(projectRoot, {
+        runId,
+        nodeId,
+        field,
+        key,
+        message: `contract_violation: ${field}['${key}'] check failed on node '${nodeId}'`,
+        playbookName
+      });
+    });
+  } catch {
+  }
+}
+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;
+}
 function iterationCapFor(node, runtimeDefault) {
   const cap = node.on_failure?.max_iterations;
   if (typeof cap === "number" && Number.isFinite(cap) && cap >= 0) return cap;
@@ -25372,6 +25532,7 @@ function iterationCapFor(node, runtimeDefault) {
 async function runFromNode(args) {
   const {
     db,
+    playbook,
     run,
     startNodeId,
     nodeIndex,
@@ -25397,6 +25558,35 @@ async function runFromNode(args) {
       currentNode: node.id,
       iterationCounts: { ...iterationCounts }
     });
+    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;
+          }
+        }
+      }
+    }
     let outcome;
     if (node.type === "agentic") {
       outcome = await executeAgenticNode(node, run.runId, context, attempt, dispatcher);
@@ -25420,7 +25610,51 @@ async function runFromNode(args) {
     if (outcome.kind === "success") {
       Object.assign(context, outcome.output);
       updatePlaybookRun(db, run.runId, { bindings: { ...context } });
-      currentId = resolveNextNodeId(node.id, edgeIndex);
+      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;
+          }
+        }
+      }
+      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} \u2192 ${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 !== void 0) break;
+        }
+      }
+      currentId = nextId;
       continue;
     }
     if (outcome.kind === "awaiting_approval") {
@@ -25560,7 +25794,8 @@ async function executePlaybook(options) {
     deterministicRunner: options.deterministicRunner,
     approvalSecret,
     maxIterationsDefault,
-    now
+    now,
+    projectRoot: options.projectRoot
   };
   return runFromNode(runArgs);
 }
@@ -25660,7 +25895,8 @@ async function resumePlaybook(options) {
     deterministicRunner: options.deterministicRunner,
     approvalSecret,
     maxIterationsDefault,
-    now
+    now,
+    projectRoot: options.projectRoot
   };
   return runFromNode(runArgs);
 }
@@ -25699,26 +25935,30 @@ __export(src_exports, {
   getPlaybookSecret: () => getPlaybookSecret,
   listPlaybookApprovals: () => listPlaybookApprovals,
   listPlaybookRuns: () => listPlaybookRuns,
+  migratePlaybook: () => migratePlaybook,
+  migratePlaybookFile: () => migratePlaybookFile,
   parsePlaybook: () => parsePlaybook,
   rejectGate: () => rejectGate,
   resumePlaybook: () => resumePlaybook,
   updatePlaybookApproval: () => updatePlaybookApproval,
-  updatePlaybookRun: () => updatePlaybookRun
+  updatePlaybookRun: () => updatePlaybookRun,
+  validatePlaybookCompliance: () => validatePlaybookCompliance
 });
 var PLAYBOOKS_PACKAGE_VERSION;
 var init_src2 = __esm({
   "packages/playbooks/src/index.ts"() {
     init_approval();
+    init_migrate_e4();
     init_parser();
     init_policy();
     init_runtime();
     init_state();
-    PLAYBOOKS_PACKAGE_VERSION = "2026.4.85";
+    PLAYBOOKS_PACKAGE_VERSION = "2026.4.129";
   }
 });
 
 // packages/cleo/src/dispatch/domains/playbook.ts
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync3, readFileSync as readFileSync6 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname as dirname2, join as join4, resolve as resolvePath2 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -25760,7 +26000,7 @@ function loadPlaybookByName(name) {
   for (const dir of candidates) {
     const full = join4(dir, fileName);
     if (existsSync3(full)) {
-      return { sourcePath: full, source: readFileSync5(full, "utf8") };
+      return { sourcePath: full, source: readFileSync6(full, "utf8") };
     }
   }
   return null;
@@ -25874,7 +26114,7 @@ var init_playbook = __esm({
     __playbookRuntimeOverrides = {};
     PlaybookHandler = class {
       /**
-       * Query gateway — `status` and `list`.
+       * Query gateway — `status`, `list`, and `validate`.
        */
       async query(operation, params) {
         const startTime = Date.now();
@@ -25884,6 +26124,8 @@ var init_playbook = __esm({
               return this.handleStatus(params, startTime);
             case "list":
               return this.handleList(params, startTime);
+            case "validate":
+              return this.handleValidate(params, startTime);
             default:
               return errorResult(
                 "query",
@@ -25928,7 +26170,7 @@ var init_playbook = __esm({
        */
       getSupportedOperations() {
         return {
-          query: ["status", "list"],
+          query: ["status", "list", "validate"],
           mutate: ["run", "resume"]
         };
       }
@@ -25988,6 +26230,104 @@ var init_playbook = __esm({
           data: envelope
         };
       }
+      /**
+       * Validate a `.cantbook` file at an absolute path or a playbook name.
+       *
+       * Accepts either:
+       *  - `file` — absolute or relative path to a `.cantbook` file on disk.
+       *  - `name` — playbook name resolved through the standard search path.
+       *
+       * Returns a LAFS envelope with `valid: true` on success, or an error
+       * envelope with `E_PLAYBOOK_PARSE` and the field/message on failure.
+       * Exit code 70 is passed through from {@link PlaybookParseError}.
+       *
+       * @task T1261 PSYCHE E4
+       */
+      async handleValidate(params, startTime) {
+        const file = params?.file;
+        const name = params?.name;
+        if (!file && !name) {
+          return errorResult(
+            "query",
+            "playbook",
+            "validate",
+            "E_INVALID_INPUT",
+            "Either file (path) or name (playbook name) is required",
+            startTime
+          );
+        }
+        let source;
+        let sourcePath;
+        if (file) {
+          const { existsSync: existsSync12, readFileSync: readFileSync16 } = await import("node:fs");
+          const { resolve: resolvePath3 } = await import("node:path");
+          const resolved = resolvePath3(file);
+          if (!existsSync12(resolved)) {
+            return errorResult(
+              "query",
+              "playbook",
+              "validate",
+              "E_NOT_FOUND",
+              `playbook file not found: ${resolved}`,
+              startTime
+            );
+          }
+          sourcePath = resolved;
+          source = readFileSync16(resolved, "utf8");
+        } else {
+          const loaded = loadPlaybookByName(name);
+          if (loaded === null) {
+            return errorResult(
+              "query",
+              "playbook",
+              "validate",
+              "E_NOT_FOUND",
+              `playbook "${name}" not found in any search path`,
+              startTime
+            );
+          }
+          sourcePath = loaded.sourcePath;
+          source = loaded.source;
+        }
+        try {
+          const { definition, sourceHash } = parsePlaybook(source);
+          return {
+            meta: dispatchMeta("query", "playbook", "validate", startTime),
+            success: true,
+            data: {
+              valid: true,
+              sourcePath,
+              sourceHash,
+              name: definition.name,
+              version: definition.version,
+              nodeCount: definition.nodes.length,
+              edgeCount: definition.edges.length,
+              hasRequires: definition.nodes.some((n) => n.requires !== void 0),
+              hasEnsures: definition.nodes.some((n) => n.ensures !== void 0),
+              hasErrorHandlers: (definition.error_handlers?.length ?? 0) > 0
+            }
+          };
+        } catch (err) {
+          if (err instanceof PlaybookParseError) {
+            return errorResult(
+              "query",
+              "playbook",
+              "validate",
+              err.code,
+              `${err.message}${err.field ? ` [field=${err.field}]` : ""}`,
+              startTime
+            );
+          }
+          return errorResult(
+            "query",
+            "playbook",
+            "validate",
+            "E_PLAYBOOK_PARSE",
+            err instanceof Error ? err.message : String(err),
+            startTime
+          );
+        }
+      }
       async handleRun(params, startTime) {
         const name = params?.name;
         if (!name) {
@@ -26051,12 +26391,14 @@ var init_playbook = __esm({
         const dispatcher = await buildDefaultDispatcher();
         let result;
         try {
+          const { getProjectRoot: getProjectRoot29 } = await import("@cleocode/core/internal");
           const opts = {
             db,
             playbook: parsed.definition,
             playbookHash: parsed.sourceHash,
             initialContext,
-            dispatcher
+            dispatcher,
+            projectRoot: getProjectRoot29()
           };
           if (__playbookRuntimeOverrides.approvalSecret !== void 0) {
             opts.approvalSecret = __playbookRuntimeOverrides.approvalSecret;
@@ -26219,7 +26561,7 @@ import {
 async function orchestrateClassify(request, context, projectRoot) {
   try {
     const { getCleoCantWorkflowsDir: getCleoCantWorkflowsDir2 } = await import("@cleocode/core/internal");
-    const { readFileSync: readFileSync15, readdirSync: readdirSync4, existsSync: existsSync12 } = await import("node:fs");
+    const { readFileSync: readFileSync16, readdirSync: readdirSync4, existsSync: existsSync12 } = await import("node:fs");
     const { join: join22 } = await import("node:path");
     const workflowsDir = getCleoCantWorkflowsDir2();
     const combined = `${request} ${context ?? ""}`.toLowerCase();
@@ -26228,7 +26570,7 @@ async function orchestrateClassify(request, context, projectRoot) {
       const files = readdirSync4(workflowsDir).filter((f) => f.endsWith(".cant"));
       for (const file of files) {
         try {
-          const src = readFileSync15(join22(workflowsDir, file), "utf-8");
+          const src = readFileSync16(join22(workflowsDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -26248,7 +26590,7 @@ async function orchestrateClassify(request, context, projectRoot) {
       const files = readdirSync4(localCantDir).filter((f) => f.endsWith(".cant"));
       for (const file of files) {
         try {
-          const src = readFileSync15(join22(localCantDir, file), "utf-8");
+          const src = readFileSync16(join22(localCantDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -31185,7 +31527,7 @@ var init_defaults = __esm({
 });
 
 // packages/cleo/src/dispatch/lib/config-loader.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
 import { join as join7 } from "path";
 function loadFromEnv(key) {
   const envKey = `${ENV_PREFIX}${key.toUpperCase()}`;
@@ -31212,7 +31554,7 @@ function loadFromFile(projectRoot) {
     return {};
   }
   try {
-    const content = readFileSync6(configPath, "utf-8");
+    const content = readFileSync7(configPath, "utf-8");
     const config = JSON.parse(content);
     const result = {};
     if (config.lifecycleEnforcement) {
@@ -31921,7 +32263,7 @@ var init_cli = __esm({
 });
 
 // packages/cleo/src/cli/index.ts
-import { readFileSync as readFileSync14 } from "node:fs";
+import { readFileSync as readFileSync15 } from "node:fs";
 import { dirname as dirname9, join as join21 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import {
@@ -32882,7 +33224,7 @@ var addCommand = defineCommand({
 });
 
 // packages/cleo/src/cli/commands/add-batch.ts
-import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
+import { existsSync as existsSync6, readFileSync as readFileSync8 } from "node:fs";
 init_cli();
 init_renderers();
 var addBatchCommand = defineCommand({
@@ -32939,7 +33281,7 @@ var addBatchCommand = defineCommand({
         process.exit(2);
         return;
       }
-      raw = readFileSync7(filePath, "utf-8");
+      raw = readFileSync8(filePath, "utf-8");
     }
     let tasks;
     try {
@@ -33549,7 +33891,7 @@ var registerCommand = defineCommand({
         transportConfig: {},
         isActive: true
       });
-      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync4 } = await import("node:fs");
+      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync5 } = await import("node:fs");
       const { join: join22 } = await import("node:path");
       const cantDir = join22(CLEO_DIR_NAME, AGENTS_SUBDIR);
       const cantPath = join22(cantDir, `${agentId}.cant`);
@@ -33605,7 +33947,7 @@ agent ${agentId}:
   enforcement:
     1: TODO \u2014 what does this agent push back on?
 `;
-        writeFileSync4(cantPath, cantContent, "utf-8");
+        writeFileSync5(cantPath, cantContent, "utf-8");
         cantScaffolded = true;
       }
       cliOutput(
@@ -33733,7 +34075,7 @@ var startCommand = defineCommand({
     try {
       const { AgentRegistryAccessor, getDb: getDb3 } = await import("@cleocode/core/internal");
       const { createRuntime } = await import("@cleocode/runtime");
-      const { existsSync: existsSync12, readFileSync: readFileSync15 } = await import("node:fs");
+      const { existsSync: existsSync12, readFileSync: readFileSync16 } = await import("node:fs");
       const { join: join22 } = await import("node:path");
       await getDb3();
       const registry = new AgentRegistryAccessor(process.cwd());
@@ -33756,7 +34098,7 @@ var startCommand = defineCommand({
       let cantValidation = null;
       const cantPath = args.cant ?? join22(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
       if (existsSync12(cantPath)) {
-        profile = readFileSync15(cantPath, "utf-8");
+        profile = readFileSync16(cantPath, "utf-8");
         try {
           const cantModule = await import("@cleocode/cant");
           const validate = "validate" in cantModule ? cantModule.validate : null;
@@ -35514,7 +35856,7 @@ var createCommand = defineCommand({
   },
   async run({ args }) {
     try {
-      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync4 } = await import("node:fs");
+      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync5 } = await import("node:fs");
       const { join: join22 } = await import("node:path");
       const { homedir: homedir6 } = await import("node:os");
       const name = args.name;
@@ -35605,9 +35947,9 @@ var createCommand = defineCommand({
         domain,
         parent
       });
-      writeFileSync4(join22(agentDir, "persona.cant"), personaContent, "utf-8");
+      writeFileSync5(join22(agentDir, "persona.cant"), personaContent, "utf-8");
       const manifest = generateManifest({ name, role, tier, domain });
-      writeFileSync4(
+      writeFileSync5(
         join22(agentDir, "manifest.json"),
         `${JSON.stringify(manifest, null, 2)}
 `,
@@ -35619,14 +35961,14 @@ var createCommand = defineCommand({
       ];
       if (team) {
         const teamConfigContent = generateTeamConfig(name, role, team);
-        writeFileSync4(join22(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
+        writeFileSync5(join22(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
         createdFiles.push(join22(agentDir, "team-config.cant"));
       }
       if (seedBrain) {
         const expertiseDir = join22(agentDir, "expertise");
         mkdirSync4(expertiseDir, { recursive: true });
         const seedContent = generateMentalModelSeed(name, role, domain);
-        writeFileSync4(join22(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
+        writeFileSync5(join22(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
         createdFiles.push(join22(expertiseDir, "mental-model-seed.md"));
         try {
           const { execFile: execFile2 } = await import("node:child_process");
@@ -35725,7 +36067,7 @@ var mintCommand = defineCommand({
   },
   async run({ args }) {
     try {
-      const { existsSync: existsSync12, readFileSync: readFileSync15, mkdirSync: mkdirSync4 } = await import("node:fs");
+      const { existsSync: existsSync12, readFileSync: readFileSync16, mkdirSync: mkdirSync4 } = await import("node:fs");
       const { resolve: resolve5, join: join22 } = await import("node:path");
       const specPath = resolve5(args.spec);
       if (!existsSync12(specPath)) {
@@ -35743,7 +36085,7 @@ var mintCommand = defineCommand({
         process.exitCode = 4;
         return;
       }
-      const specContent = readFileSync15(specPath, "utf-8");
+      const specContent = readFileSync16(specPath, "utf-8");
       const projectRoot = process.cwd();
       const outputDir = args["output-dir"] ? resolve5(args["output-dir"]) : join22(projectRoot, ".cleo", "cant", "agents");
       mkdirSync4(outputDir, { recursive: true });
@@ -37919,7 +38261,7 @@ var cancelCommand = defineCommand({
 });
 
 // packages/cleo/src/cli/commands/cant.ts
-import { existsSync as existsSync8, mkdirSync, readFileSync as readFileSync8, writeFileSync } from "node:fs";
+import { existsSync as existsSync8, mkdirSync, readFileSync as readFileSync9, writeFileSync as writeFileSync2 } from "node:fs";
 import { dirname as dirname5, isAbsolute, join as join10, resolve as resolve3 } from "node:path";
 init_renderers();
 function resolveFilePath(file) {
@@ -38070,7 +38412,7 @@ var cantMigrateCommand = defineCommand({
     if (!ensureExists(filePath, "cant.migrate")) return;
     try {
       const mod = await loadMigrateEngine();
-      const content = readFileSync8(filePath, "utf-8");
+      const content = readFileSync9(filePath, "utf-8");
       const result = mod.migrateMarkdown(content, filePath, {
         write: isWrite,
         verbose: isVerbose,
@@ -38082,7 +38424,7 @@ var cantMigrateCommand = defineCommand({
         for (const outputFile of result.outputFiles) {
           const outputPath = isAbsolute(outputFile.path) ? outputFile.path : join10(projectRoot, outputFile.path);
           mkdirSync(dirname5(outputPath), { recursive: true });
-          writeFileSync(outputPath, outputFile.content, "utf-8");
+          writeFileSync2(outputPath, outputFile.content, "utf-8");
           written++;
         }
         cliOutput(
@@ -38130,7 +38472,7 @@ var cantCommand = defineCommand({
 });
 
 // packages/cleo/src/cli/commands/chain.ts
-import { readFileSync as readFileSync9 } from "node:fs";
+import { readFileSync as readFileSync10 } from "node:fs";
 init_cli();
 var showCommand3 = defineCommand({
   meta: { name: "show", description: "Show details for a WarpChain definition" },
@@ -38167,7 +38509,7 @@ var addCommand3 = defineCommand({
     }
   },
   async run({ args }) {
-    const chainJson = JSON.parse(readFileSync9(args.file, "utf-8"));
+    const chainJson = JSON.parse(readFileSync10(args.file, "utf-8"));
     await dispatchFromCli(
       "mutate",
       "pipeline",
@@ -38336,10 +38678,10 @@ var checkChainValidateCommand = defineCommand({
     }
   },
   async run({ args }) {
-    const { readFileSync: readFileSync15 } = await import("node:fs");
+    const { readFileSync: readFileSync16 } = await import("node:fs");
     let chain;
     try {
-      chain = JSON.parse(readFileSync15(args.file, "utf8"));
+      chain = JSON.parse(readFileSync16(args.file, "utf8"));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(`Failed to read or parse chain file: ${message}`);
@@ -40353,7 +40695,7 @@ var detectCommand2 = defineCommand({
 
 // packages/cleo/src/cli/commands/detect-drift.ts
 init_src();
-import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync10 } from "node:fs";
+import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync11 } from "node:fs";
 import { dirname as dirname6, join as join12 } from "node:path";
 init_paths();
 init_renderers();
@@ -40380,7 +40722,7 @@ var detectDriftCommand = defineCommand({
     const cleoSrcRoot = isCleoRepo ? join12(projectRoot, "packages", "cleo", "src") : join12(projectRoot, "src");
     const safeRead = (filePath) => {
       try {
-        return readFileSync10(filePath, "utf-8");
+        return readFileSync11(filePath, "utf-8");
       } catch {
         return "";
       }
@@ -42396,14 +42738,14 @@ var gcCommand = defineCommand({
 // packages/cleo/src/cli/commands/generate-changelog.ts
 init_src();
 import { execFileSync as execFileSync3 } from "node:child_process";
-import { existsSync as existsSync10, mkdirSync as mkdirSync2, readFileSync as readFileSync11, writeFileSync as writeFileSync2 } from "node:fs";
+import { existsSync as existsSync10, mkdirSync as mkdirSync2, readFileSync as readFileSync12, writeFileSync as writeFileSync3 } from "node:fs";
 import { dirname as dirname8, join as join15 } from "node:path";
 import { CleoError as CleoError4, formatError as formatError6, getConfigPath as getConfigPath2, getProjectRoot as getProjectRoot21 } from "@cleocode/core";
 init_renderers();
 function getChangelogSource(cwd) {
   const configPath = getConfigPath2(cwd);
   try {
-    const config = JSON.parse(readFileSync11(configPath, "utf-8"));
+    const config = JSON.parse(readFileSync12(configPath, "utf-8"));
     return config?.release?.changelog?.source ?? "CHANGELOG.md";
   } catch {
     return "CHANGELOG.md";
@@ -42412,7 +42754,7 @@ function getChangelogSource(cwd) {
 function getEnabledPlatforms(cwd) {
   const configPath = getConfigPath2(cwd);
   try {
-    const config = JSON.parse(readFileSync11(configPath, "utf-8"));
+    const config = JSON.parse(readFileSync12(configPath, "utf-8"));
     const outputs = config?.release?.changelog?.outputs ?? [];
     return outputs.filter((o) => o.enabled);
   } catch {
@@ -42560,7 +42902,7 @@ var generateChangelogCommand = defineCommand({
       if (!existsSync10(sourcePath)) {
         throw new CleoError4(4 /* NOT_FOUND */, `Changelog source not found: ${sourcePath}`);
       }
-      const sourceContent = readFileSync11(sourcePath, "utf-8");
+      const sourceContent = readFileSync12(sourcePath, "utf-8");
       const repoSlug = getGitHubRepoSlug();
       const results = [];
       if (targetPlatform) {
@@ -42571,7 +42913,7 @@ var generateChangelogCommand = defineCommand({
         if (!dryRun) {
           const fullPath = join15(getProjectRoot21(), outputPath);
           mkdirSync2(dirname8(fullPath), { recursive: true });
-          writeFileSync2(fullPath, content, "utf-8");
+          writeFileSync3(fullPath, content, "utf-8");
         }
         results.push({ platform: targetPlatform, path: outputPath, written: !dryRun });
       } else {
@@ -42592,7 +42934,7 @@ var generateChangelogCommand = defineCommand({
           if (!dryRun) {
             const fullPath = join15(getProjectRoot21(), platformConfig.path);
             mkdirSync2(dirname8(fullPath), { recursive: true });
-            writeFileSync2(fullPath, content, "utf-8");
+            writeFileSync3(fullPath, content, "utf-8");
           }
           results.push({
             platform: platformConfig.platform,
@@ -44000,7 +44342,7 @@ var mapCommand = defineCommand({
 
 // packages/cleo/src/cli/commands/memory.ts
 import { createHash as createHash3 } from "node:crypto";
-import { existsSync as existsSync11, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync12, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync13, writeFileSync as writeFileSync4 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join16 } from "node:path";
 import {
@@ -44046,7 +44388,7 @@ ${body}`).digest("hex").slice(0, 16);
 function loadImportHashes(stateFile) {
   try {
     if (!existsSync11(stateFile)) return /* @__PURE__ */ new Set();
-    const raw = readFileSync12(stateFile, "utf-8");
+    const raw = readFileSync13(stateFile, "utf-8");
     const parsed = JSON.parse(raw);
     return new Set(parsed.hashes);
   } catch {
@@ -44056,7 +44398,7 @@ function loadImportHashes(stateFile) {
 function saveImportHashes(stateFile, hashes) {
   const dir = stateFile.slice(0, stateFile.lastIndexOf("/"));
   if (!existsSync11(dir)) mkdirSync3(dir, { recursive: true });
-  writeFileSync3(stateFile, JSON.stringify({ hashes: [...hashes] }, null, 2), "utf-8");
+  writeFileSync4(stateFile, JSON.stringify({ hashes: [...hashes] }, null, 2), "utf-8");
 }
 var storeCommand = defineCommand({
   meta: { name: "store", description: "Store a pattern or learning to BRAIN memory" },
@@ -45329,7 +45671,7 @@ var importCommand3 = defineCommand({
     for (const filePath of files) {
       const fileName = filePath.split("/").pop() ?? filePath;
       try {
-        const raw = readFileSync12(filePath, "utf-8");
+        const raw = readFileSync13(filePath, "utf-8");
         if (!raw.trim()) {
           stats.skipped++;
           skippedEntries.push({ file: fileName, reason: "empty file" });
@@ -49213,8 +49555,8 @@ var exportCommand6 = defineCommand({
         return;
       }
       if (outputFile) {
-        const { writeFileSync: writeFileSync4 } = await import("node:fs");
-        writeFileSync4(outputFile, output, "utf-8");
+        const { writeFileSync: writeFileSync5 } = await import("node:fs");
+        writeFileSync5(outputFile, output, "utf-8");
         process.stdout.write(
           `[nexus] Exported to ${outputFile} (${nodes.length} nodes, ${relations.length} edges)
 `
@@ -52440,17 +52782,41 @@ var listCommand13 = defineCommand({
     );
   }
 });
+var validateCommand6 = defineCommand({
+  meta: {
+    name: "validate",
+    description: "Parse and validate a .cantbook file \u2014 exit 0 on success, exit 70 on parse error (T1261)"
+  },
+  args: {
+    file: {
+      type: "positional",
+      description: "Path to .cantbook file OR playbook name to resolve via search path",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const isPath = args.file.includes("/") || args.file.includes("\\") || args.file.endsWith(".cantbook");
+    await dispatchFromCli(
+      "query",
+      "playbook",
+      "validate",
+      isPath ? { file: args.file } : { name: args.file },
+      { command: "playbook" }
+    );
+  }
+});
 var playbookCommand = defineCommand({
   meta: {
     name: "playbook",
-    description: "Playbook runtime operations (run, status, resume, list, create)"
+    description: "Playbook runtime operations (run, status, resume, list, create, validate)"
   },
   subCommands: {
     run: runCommand3,
     status: statusCommand10,
     resume: resumeCommand,
     list: listCommand13,
-    create: createCommand2
+    create: createCommand2,
+    validate: validateCommand6
   },
   async run({ cmd, rawArgs }) {
     const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
@@ -56364,7 +56730,7 @@ var searchCommand3 = defineCommand({
     );
   }
 });
-var validateCommand6 = defineCommand({
+var validateCommand7 = defineCommand({
   meta: { name: "validate", description: "Validate skill against protocol" },
   args: {
     "skill-name": {
@@ -56631,7 +56997,7 @@ var skillsCommand2 = defineCommand({
   subCommands: {
     list: listCommand20,
     search: searchCommand3,
-    validate: validateCommand6,
+    validate: validateCommand7,
     info: infoCommand,
     install: installCommand2,
     uninstall: uninstallCommand,
@@ -57212,10 +57578,10 @@ var reconcileCommand2 = defineCommand({
     }
   },
   async run({ args }) {
-    const { readFileSync: readFileSync15 } = await import("node:fs");
+    const { readFileSync: readFileSync16 } = await import("node:fs");
     let externalTasks;
     try {
-      externalTasks = JSON.parse(readFileSync15(args.file, "utf8"));
+      externalTasks = JSON.parse(readFileSync16(args.file, "utf8"));
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       console.error(`Failed to read or parse external tasks file: ${message}`);
@@ -57253,7 +57619,7 @@ var syncCommand5 = defineCommand({
 
 // packages/cleo/src/cli/commands/testing.ts
 init_cli();
-var validateCommand7 = defineCommand({
+var validateCommand8 = defineCommand({
   meta: { name: "validate", description: "Validate testing protocol compliance for a task" },
   args: {
     taskId: {
@@ -57353,7 +57719,7 @@ var runCommand4 = defineCommand({
 var testingCommand = defineCommand({
   meta: { name: "testing", description: "Validate testing protocol compliance" },
   subCommands: {
-    validate: validateCommand7,
+    validate: validateCommand8,
     check: checkCommand7,
     status: statusCommand12,
     coverage: coverageCommand,
@@ -57367,14 +57733,14 @@ var testingCommand = defineCommand({
 });
 
 // packages/cleo/src/cli/commands/token.ts
-import { readFileSync as readFileSync13 } from "node:fs";
+import { readFileSync as readFileSync14 } from "node:fs";
 import { measureTokenExchange, recordTokenExchange as recordTokenExchange2 } from "@cleocode/core/internal";
 init_cli();
 init_renderers();
 function readPayload(args, textKey, fileKey) {
   const text = args[textKey];
   const file = args[fileKey];
-  if (file) return readFileSync13(file, "utf-8");
+  if (file) return readFileSync14(file, "utf-8");
   return text;
 }
 var filterArgs = {
@@ -58765,7 +59131,7 @@ Or via NodeSource: https://github.com/nodesource/distributions
 }
 function getPackageVersion() {
   const pkgPath = join21(dirname9(fileURLToPath3(import.meta.url)), "../../package.json");
-  const pkg = JSON.parse(readFileSync14(pkgPath, "utf-8"));
+  const pkg = JSON.parse(readFileSync15(pkgPath, "utf-8"));
   return pkg.version;
 }
 var CLI_VERSION = getPackageVersion();