@cleocode/cleo 2026.4.128 → 2026.4.130

package/dist/cli/index.js

@@ -758,6 +758,66 @@ var init_session2 = __esm({
   }
 });
 
+// packages/contracts/src/session-journal.ts
+import { z as z4 } from "zod";
+var SESSION_JOURNAL_SCHEMA_VERSION, sessionJournalDoctorSummarySchema, sessionJournalDebriefSummarySchema, sessionJournalEntrySchema;
+var init_session_journal = __esm({
+  "packages/contracts/src/session-journal.ts"() {
+    "use strict";
+    SESSION_JOURNAL_SCHEMA_VERSION = "1.0";
+    sessionJournalDoctorSummarySchema = z4.object({
+      /** `true` when zero noise patterns were detected. */
+      isClean: z4.boolean(),
+      /** Total number of noise findings across all patterns. */
+      findingsCount: z4.number().int().nonnegative(),
+      /** Pattern names that were detected (empty when isClean). */
+      patterns: z4.array(z4.string()),
+      /** Total brain entries scanned. `0` = empty or unavailable. */
+      totalScanned: z4.number().int().nonnegative()
+    });
+    sessionJournalDebriefSummarySchema = z4.object({
+      /** First 200 characters of the session end note (if provided). */
+      noteExcerpt: z4.string().max(200).optional(),
+      /** Number of tasks completed during the session. */
+      tasksCompletedCount: z4.number().int().nonnegative(),
+      /** Up to 5 task IDs (not titles) that were the focus of the session. */
+      tasksFocused: z4.array(z4.string()).max(5).optional()
+    });
+    sessionJournalEntrySchema = z4.object({
+      // Identity
+      /** Schema version for forward-compatibility. Always `'1.0'` in this release. */
+      schemaVersion: z4.literal(SESSION_JOURNAL_SCHEMA_VERSION),
+      /** ISO 8601 timestamp when the entry was written. */
+      timestamp: z4.string(),
+      /** CLEO session ID (e.g. `ses_20260424055456_ede571`). */
+      sessionId: z4.string(),
+      /** Event type that triggered this journal entry. */
+      eventType: z4.enum(["session_start", "session_end", "observation", "decision", "error"]),
+      // Session metadata (set on session_start / session_end)
+      /** Agent identifier (e.g. `cleo-prime`, `claude-code`). */
+      agentIdentifier: z4.string().optional(),
+      /** Provider adapter ID active for this session. */
+      providerId: z4.string().optional(),
+      /** Session scope string (e.g. `'global'` or `'epic:T1263'`). */
+      scope: z4.string().optional(),
+      // Session-end fields
+      /** Duration of the session in seconds (session_end only). */
+      duration: z4.number().int().nonnegative().optional(),
+      /** Task IDs (not titles) completed during the session. */
+      tasksCompleted: z4.array(z4.string()).optional(),
+      // Doctor summary (T1262 absorbed)
+      /** Compact result of `scanBrainNoise` run at session-end. */
+      doctorSummary: sessionJournalDoctorSummarySchema.optional(),
+      // Debrief summary
+      /** Compact excerpt from session debrief data. */
+      debriefSummary: sessionJournalDebriefSummarySchema.optional(),
+      // Optional hash chain
+      /** SHA-256 hex of the previous entry's raw JSON string (for integrity chain). */
+      prevEntryHash: z4.string().optional()
+    });
+  }
+});
+
 // packages/contracts/src/status-registry.ts
 var TASK_STATUS_SYMBOLS_UNICODE, TASK_STATUS_SYMBOLS_ASCII;
 var init_status_registry = __esm({
@@ -792,52 +852,52 @@ var init_status_registry = __esm({
 });
 
 // packages/contracts/src/task-evidence.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var fileEvidenceSchema, logEvidenceSchema, screenshotEvidenceSchema, testOutputEvidenceSchema, commandOutputEvidenceSchema, taskEvidenceSchema;
 var init_task_evidence = __esm({
   "packages/contracts/src/task-evidence.ts"() {
     "use strict";
-    fileEvidenceSchema = z4.object({
-      kind: z4.literal("file"),
-      sha256: z4.string().length(64),
-      timestamp: z4.string().datetime(),
-      path: z4.string().min(1),
-      mime: z4.string().optional(),
-      description: z4.string().optional()
+    fileEvidenceSchema = z5.object({
+      kind: z5.literal("file"),
+      sha256: z5.string().length(64),
+      timestamp: z5.string().datetime(),
+      path: z5.string().min(1),
+      mime: z5.string().optional(),
+      description: z5.string().optional()
     });
-    logEvidenceSchema = z4.object({
-      kind: z4.literal("log"),
-      sha256: z4.string().length(64),
-      timestamp: z4.string().datetime(),
-      source: z4.string().min(1),
-      description: z4.string().optional()
+    logEvidenceSchema = z5.object({
+      kind: z5.literal("log"),
+      sha256: z5.string().length(64),
+      timestamp: z5.string().datetime(),
+      source: z5.string().min(1),
+      description: z5.string().optional()
     });
-    screenshotEvidenceSchema = z4.object({
-      kind: z4.literal("screenshot"),
-      sha256: z4.string().length(64),
-      timestamp: z4.string().datetime(),
-      mime: z4.enum(["image/png", "image/jpeg", "image/webp"]).optional(),
-      description: z4.string().optional()
+    screenshotEvidenceSchema = z5.object({
+      kind: z5.literal("screenshot"),
+      sha256: z5.string().length(64),
+      timestamp: z5.string().datetime(),
+      mime: z5.enum(["image/png", "image/jpeg", "image/webp"]).optional(),
+      description: z5.string().optional()
     });
-    testOutputEvidenceSchema = z4.object({
-      kind: z4.literal("test-output"),
-      sha256: z4.string().length(64),
-      timestamp: z4.string().datetime(),
-      passed: z4.number().int().nonnegative(),
-      failed: z4.number().int().nonnegative(),
-      skipped: z4.number().int().nonnegative(),
-      exitCode: z4.number().int(),
-      description: z4.string().optional()
+    testOutputEvidenceSchema = z5.object({
+      kind: z5.literal("test-output"),
+      sha256: z5.string().length(64),
+      timestamp: z5.string().datetime(),
+      passed: z5.number().int().nonnegative(),
+      failed: z5.number().int().nonnegative(),
+      skipped: z5.number().int().nonnegative(),
+      exitCode: z5.number().int(),
+      description: z5.string().optional()
     });
-    commandOutputEvidenceSchema = z4.object({
-      kind: z4.literal("command-output"),
-      sha256: z4.string().length(64),
-      timestamp: z4.string().datetime(),
-      cmd: z4.string().min(1),
-      exitCode: z4.number().int(),
-      description: z4.string().optional()
+    commandOutputEvidenceSchema = z5.object({
+      kind: z5.literal("command-output"),
+      sha256: z5.string().length(64),
+      timestamp: z5.string().datetime(),
+      cmd: z5.string().min(1),
+      exitCode: z5.number().int(),
+      description: z5.string().optional()
     });
-    taskEvidenceSchema = z4.discriminatedUnion("kind", [
+    taskEvidenceSchema = z5.discriminatedUnion("kind", [
       fileEvidenceSchema,
       logEvidenceSchema,
       screenshotEvidenceSchema,
@@ -862,6 +922,7 @@ var init_src = __esm({
     init_params();
     init_peer();
     init_session2();
+    init_session_journal();
     init_status_registry();
     init_task_evidence();
   }
@@ -7669,6 +7730,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",
@@ -9129,6 +9216,11 @@ async function sessionGc(projectRoot, maxAgeDays = 1) {
         await accessor.removeSingleSession(s.id);
       }
     }
+    try {
+      const { rotateSessionJournals } = await import("@cleocode/core/sessions/session-journal.js");
+      await rotateSessionJournals(projectRoot);
+    } catch {
+    }
     return { success: true, data: { orphaned, removed } };
   } catch {
     return engineError("E_NOT_INITIALIZED", "Task database not initialized");
@@ -9782,7 +9874,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 +9883,7 @@ async function applyCantBodySubstitution(payload, cwd, ctx) {
   }
   let body;
   try {
-    body = readFileSync15(cantPath, "utf-8");
+    body = readFileSync16(cantPath, "utf-8");
   } catch (err) {
     return {
       ...empty,
@@ -11714,9 +11806,9 @@ async function systemLog(projectRoot, filters) {
 }
 async function queryAuditLogSqlite(projectRoot, filters) {
   try {
-    const { join: join22 } = await import("node:path");
+    const { join: join23 } = await import("node:path");
     const { existsSync: existsSync12 } = await import("node:fs");
-    const dbPath = join22(projectRoot, CLEO_DIR_NAME, TASKS_DB_FILENAME);
+    const dbPath = join23(projectRoot, CLEO_DIR_NAME, TASKS_DB_FILENAME);
     if (!existsSync12(dbPath)) {
       const offset = filters?.offset ?? 0;
       const limit = filters?.limit ?? 20;
@@ -24527,13 +24619,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 +24987,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) {
@@ -25212,6 +25405,8 @@ var init_state = __esm({
 });
 
 // packages/playbooks/src/runtime.ts
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname as dirname2, join as join4 } from "node:path";
 function buildEdgeIndex(def) {
   const outgoing = /* @__PURE__ */ new Map();
   const incoming = /* @__PURE__ */ new Map();
@@ -25364,6 +25559,42 @@ 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 {
+    const filePath = join4(projectRoot, ".cleo", "audit", "contract-violations.jsonl");
+    mkdirSync(dirname2(filePath), { recursive: true });
+    const entry = JSON.stringify({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      runId,
+      nodeId,
+      field,
+      key,
+      message: `contract_violation: ${field}['${key}'] check failed on node '${nodeId}'`,
+      playbookName
+    });
+    appendFileSync(filePath, `${entry}
+`, { encoding: "utf-8" });
+  } 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 +25603,7 @@ function iterationCapFor(node, runtimeDefault) {
 async function runFromNode(args) {
   const {
     db,
+    playbook,
     run,
     startNodeId,
     nodeIndex,
@@ -25397,6 +25629,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 +25681,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 +25865,8 @@ async function executePlaybook(options) {
     deterministicRunner: options.deterministicRunner,
     approvalSecret,
     maxIterationsDefault,
-    now
+    now,
+    projectRoot: options.projectRoot
   };
   return runFromNode(runArgs);
 }
@@ -25660,7 +25966,8 @@ async function resumePlaybook(options) {
     deterministicRunner: options.deterministicRunner,
     approvalSecret,
     maxIterationsDefault,
-    now
+    now,
+    projectRoot: options.projectRoot
   };
   return runFromNode(runArgs);
 }
@@ -25699,28 +26006,32 @@ __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 { dirname as dirname3, join as join5, resolve as resolvePath2 } from "node:path";
 import { fileURLToPath } from "node:url";
 function normalizeListStatus(raw) {
   if (typeof raw !== "string" || raw.length === 0) return void 0;
@@ -25748,8 +26059,8 @@ function resolvePlaybookDirs() {
   if (__playbookRuntimeOverrides.playbookBaseDirs) {
     return __playbookRuntimeOverrides.playbookBaseDirs;
   }
-  const globalDir = join4(homedir(), ".local", "share", "cleo", "playbooks");
-  const here = dirname2(fileURLToPath(import.meta.url));
+  const globalDir = join5(homedir(), ".local", "share", "cleo", "playbooks");
+  const here = dirname3(fileURLToPath(import.meta.url));
   const sourceStarter = resolvePath2(here, "..", "..", "..", "..", "playbooks", "starter");
   const bundledStarter = resolvePath2(here, "..", "..", "..", "playbooks", "starter");
   return [globalDir, sourceStarter, bundledStarter];
@@ -25758,9 +26069,9 @@ function loadPlaybookByName(name) {
   const candidates = resolvePlaybookDirs();
   const fileName = name.endsWith(".cantbook") ? name : `${name}.cantbook`;
   for (const dir of candidates) {
-    const full = join4(dir, fileName);
+    const full = join5(dir, fileName);
     if (existsSync3(full)) {
-      return { sourcePath: full, source: readFileSync5(full, "utf8") };
+      return { sourcePath: full, source: readFileSync6(full, "utf8") };
     }
   }
   return null;
@@ -25874,7 +26185,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 +26195,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 +26241,7 @@ var init_playbook = __esm({
        */
       getSupportedOperations() {
         return {
-          query: ["status", "list"],
+          query: ["status", "list", "validate"],
           mutate: ["run", "resume"]
         };
       }
@@ -25988,6 +26301,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 +26462,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,8 +26632,8 @@ 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 { join: join22 } = await import("node:path");
+    const { readFileSync: readFileSync16, readdirSync: readdirSync4, existsSync: existsSync12 } = await import("node:fs");
+    const { join: join23 } = await import("node:path");
     const workflowsDir = getCleoCantWorkflowsDir2();
     const combined = `${request} ${context ?? ""}`.toLowerCase();
     const matches = [];
@@ -26228,7 +26641,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(join23(workflowsDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -26243,12 +26656,12 @@ async function orchestrateClassify(request, context, projectRoot) {
         }
       }
     }
-    const localCantDir = join22(projectRoot, CLEO_DIR_NAME, WORKFLOWS_SUBDIR);
+    const localCantDir = join23(projectRoot, CLEO_DIR_NAME, WORKFLOWS_SUBDIR);
     if (existsSync12(localCantDir)) {
       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(join23(localCantDir, file), "utf-8");
           const teamMatch = /^team\s+(\S+):/m.exec(src);
           if (!teamMatch) continue;
           const teamName = teamMatch[1];
@@ -28226,7 +28639,7 @@ var init_pipeline2 = __esm({
 });
 
 // packages/cleo/src/dispatch/domains/sentient.ts
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 import { getProjectRoot as getProjectRoot11 } from "@cleocode/core";
 function safeParseJsonArray(json2) {
   if (!json2) return [];
@@ -28255,7 +28668,7 @@ async function incrementTier2Stat(projectRoot, field) {
   try {
     const { patchSentientState: patchSentientState2, readSentientState: readSentientState2 } = await import("@cleocode/core/sentient/state.js");
     const { SENTIENT_STATE_FILE: SENTIENT_STATE_FILE2 } = await import("@cleocode/core/sentient/daemon.js");
-    const statePath = join5(projectRoot, SENTIENT_STATE_FILE2);
+    const statePath = join6(projectRoot, SENTIENT_STATE_FILE2);
     const state = await readSentientState2(statePath);
     await patchSentientState2(statePath, {
       tier2Stats: {
@@ -28532,7 +28945,7 @@ var init_sentient = __esm({
       async runProposeTick(projectRoot, params) {
         const { safeRunProposeTick: safeRunProposeTick2 } = await import("@cleocode/core/sentient/propose-tick.js");
         const { SENTIENT_STATE_FILE: SENTIENT_STATE_FILE2 } = await import("@cleocode/core/sentient/daemon.js");
-        const statePath = join5(projectRoot, SENTIENT_STATE_FILE2);
+        const statePath = join6(projectRoot, SENTIENT_STATE_FILE2);
         const outcome = await safeRunProposeTick2({ projectRoot, statePath });
         const _ = params;
         void _;
@@ -28580,7 +28993,7 @@ var init_sentient = __esm({
       async setTier2Enabled(projectRoot, enabled) {
         const { patchSentientState: patchSentientState2 } = await import("@cleocode/core/sentient/state.js");
         const { SENTIENT_STATE_FILE: SENTIENT_STATE_FILE2 } = await import("@cleocode/core/sentient/daemon.js");
-        const statePath = join5(projectRoot, SENTIENT_STATE_FILE2);
+        const statePath = join6(projectRoot, SENTIENT_STATE_FILE2);
         const updated = await patchSentientState2(statePath, { tier2Enabled: enabled });
         return {
           success: true,
@@ -29961,7 +30374,7 @@ var init_tasks3 = __esm({
 });
 
 // packages/cleo/src/dispatch/engines/code-engine.ts
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 import { getProjectRoot as getProjectRoot15 } from "@cleocode/core";
 async function codeOutline(params) {
   const { smartOutline } = await import("@cleocode/core/internal");
@@ -29972,7 +30385,7 @@ async function codeOutline(params) {
       error: { code: "E_INVALID_INPUT", message: "file parameter required" }
     };
   const root = getProjectRoot15();
-  const absPath = filePath.startsWith("/") ? filePath : join6(root, filePath);
+  const absPath = filePath.startsWith("/") ? filePath : join7(root, filePath);
   return { success: true, data: smartOutline(absPath, root) };
 }
 async function codeSearch(params) {
@@ -30004,7 +30417,7 @@ async function codeUnfold(params) {
       error: { code: "E_INVALID_INPUT", message: "file and symbol parameters required" }
     };
   const root = getProjectRoot15();
-  const absPath = filePath.startsWith("/") ? filePath : join6(root, filePath);
+  const absPath = filePath.startsWith("/") ? filePath : join7(root, filePath);
   return { success: true, data: smartUnfold(absPath, symbol, root) };
 }
 async function codeParse(params) {
@@ -30016,7 +30429,7 @@ async function codeParse(params) {
       error: { code: "E_INVALID_INPUT", message: "file parameter required" }
     };
   const root = getProjectRoot15();
-  const absPath = filePath.startsWith("/") ? filePath : join6(root, filePath);
+  const absPath = filePath.startsWith("/") ? filePath : join7(root, filePath);
   return { success: true, data: parseFile(absPath, root) };
 }
 var init_code_engine = __esm({
@@ -31185,8 +31598,8 @@ var init_defaults = __esm({
 });
 
 // packages/cleo/src/dispatch/lib/config-loader.ts
-import { existsSync as existsSync4, readFileSync as readFileSync6 } from "fs";
-import { join as join7 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync7 } from "fs";
+import { join as join8 } from "path";
 function loadFromEnv(key) {
   const envKey = `${ENV_PREFIX}${key.toUpperCase()}`;
   return process.env[envKey];
@@ -31207,12 +31620,12 @@ function parseEnvValue(key, value) {
 }
 function loadFromFile(projectRoot) {
   const root = projectRoot || process.cwd();
-  const configPath = join7(root, CLEO_DIR_NAME, CONFIG_JSON);
+  const configPath = join8(root, CLEO_DIR_NAME, CONFIG_JSON);
   if (!existsSync4(configPath)) {
     return {};
   }
   try {
-    const content = readFileSync6(configPath, "utf-8");
+    const content = readFileSync7(configPath, "utf-8");
     const config = JSON.parse(content);
     const result = {};
     if (config.lifecycleEnforcement) {
@@ -31681,7 +32094,7 @@ __export(cli_exports, {
 import { randomUUID as randomUUID5 } from "node:crypto";
 import { existsSync as existsSync5 } from "node:fs";
 import { createRequire as createRequire2 } from "node:module";
-import { dirname as dirname3, join as join8 } from "node:path";
+import { dirname as dirname4, join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { catalog as catalog2, registerSkillLibraryFromPath } from "@cleocode/caamp";
 import { autoRecordDispatchTokenUsage, getProjectRoot as getProjectRoot17, hooks } from "@cleocode/core/internal";
@@ -31692,17 +32105,17 @@ function ensureCaampLibrary() {
     try {
       const req = createRequire2(import.meta.url);
       const skillsPkgJson = req.resolve("@cleocode/skills/package.json");
-      const candidate = dirname3(skillsPkgJson);
-      if (existsSync5(join8(candidate, "skills.json"))) {
+      const candidate = dirname4(skillsPkgJson);
+      if (existsSync5(join9(candidate, "skills.json"))) {
         skillsRoot = candidate;
       }
     } catch {
     }
     if (!skillsRoot) {
       const thisFile = fileURLToPath2(import.meta.url);
-      const packageRoot = join8(dirname3(thisFile), "..", "..", "..", "..", "..");
-      const candidate = join8(packageRoot, "packages", "skills");
-      if (existsSync5(join8(candidate, "skills.json"))) {
+      const packageRoot = join9(dirname4(thisFile), "..", "..", "..", "..", "..");
+      const candidate = join9(packageRoot, "packages", "skills");
+      if (existsSync5(join9(candidate, "skills.json"))) {
         skillsRoot = candidate;
       }
     }
@@ -31921,8 +32334,8 @@ var init_cli = __esm({
 });
 
 // packages/cleo/src/cli/index.ts
-import { readFileSync as readFileSync14 } from "node:fs";
-import { dirname as dirname9, join as join21 } from "node:path";
+import { readFileSync as readFileSync15 } from "node:fs";
+import { dirname as dirname10, join as join22 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
 import {
   detectAndRemoveLegacyGlobalFiles,
@@ -32882,7 +33295,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 +33352,7 @@ var addBatchCommand = defineCommand({
         process.exit(2);
         return;
       }
-      raw = readFileSync7(filePath, "utf-8");
+      raw = readFileSync8(filePath, "utf-8");
     }
     let tasks;
     try {
@@ -33549,13 +33962,13 @@ var registerCommand = defineCommand({
         transportConfig: {},
         isActive: true
       });
-      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync4 } = 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`);
+      const { existsSync: existsSync12, mkdirSync: mkdirSync5, writeFileSync: writeFileSync5 } = await import("node:fs");
+      const { join: join23 } = await import("node:path");
+      const cantDir = join23(CLEO_DIR_NAME, AGENTS_SUBDIR);
+      const cantPath = join23(cantDir, `${agentId}.cant`);
       let cantScaffolded = false;
       if (!existsSync12(cantPath)) {
-        mkdirSync4(cantDir, { recursive: true });
+        mkdirSync5(cantDir, { recursive: true });
         const role = classification ?? "specialist";
         const cantContent = `---
 kind: agent
@@ -33605,7 +34018,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,8 +34146,8 @@ 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 { join: join22 } = await import("node:path");
+      const { existsSync: existsSync12, readFileSync: readFileSync16 } = await import("node:fs");
+      const { join: join23 } = await import("node:path");
       await getDb3();
       const registry = new AgentRegistryAccessor(process.cwd());
       const credential = await registry.get(args.agentId);
@@ -33754,9 +34167,9 @@ var startCommand = defineCommand({
       }
       let profile = null;
       let cantValidation = null;
-      const cantPath = args.cant ?? join22(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
+      const cantPath = args.cant ?? join23(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;
@@ -34280,7 +34693,7 @@ var workCommand = defineCommand({
       const { AgentRegistryAccessor, getDb: getDb3 } = await import("@cleocode/core/internal");
       const { createRuntime } = await import("@cleocode/runtime");
       const { existsSync: existsSync12 } = await import("node:fs");
-      const { join: join22 } = await import("node:path");
+      const { join: join23 } = await import("node:path");
       const { execFile: execFile2 } = await import("node:child_process");
       const { promisify: promisify2 } = await import("node:util");
       const execFileAsync = promisify2(execFile2);
@@ -34300,7 +34713,7 @@ var workCommand = defineCommand({
       }
       await registry.update(args.agentId, { isActive: true });
       await registry.markUsed(args.agentId);
-      const cantPath = join22(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
+      const cantPath = join23(CLEO_DIR_NAME, AGENTS_SUBDIR, `${args.agentId}.cant`);
       const hasProfile = existsSync12(cantPath);
       const runtime = await createRuntime(registry, {
         agentId: args.agentId,
@@ -35151,8 +35564,8 @@ var installCommand = defineCommand({
   async run({ args }) {
     let tempDir = null;
     try {
-      const { existsSync: existsSync12, mkdirSync: mkdirSync4, statSync, readdirSync: readdirSync4, copyFileSync } = await import("node:fs");
-      const { join: join22, basename: basename2, resolve: resolve5, extname } = await import("node:path");
+      const { existsSync: existsSync12, mkdirSync: mkdirSync5, statSync, readdirSync: readdirSync4, copyFileSync } = await import("node:fs");
+      const { join: join23, basename: basename2, resolve: resolve5, extname } = await import("node:path");
       const { tmpdir } = await import("node:os");
       const resolvedPath = resolve5(args.path);
       if (!existsSync12(resolvedPath)) {
@@ -35176,8 +35589,8 @@ var installCommand = defineCommand({
         cantPath = resolvedPath;
       } else if (stat2.isFile() && ext === ".cantz") {
         const { execFileSync: execFileSync6 } = await import("node:child_process");
-        tempDir = join22(tmpdir(), `cleo-agent-install-${Date.now()}`);
-        mkdirSync4(tempDir, { recursive: true });
+        tempDir = join23(tmpdir(), `cleo-agent-install-${Date.now()}`);
+        mkdirSync5(tempDir, { recursive: true });
         try {
           execFileSync6("unzip", ["-o", "-q", resolvedPath, "-d", tempDir], {
             encoding: "utf-8",
@@ -35198,7 +35611,7 @@ var installCommand = defineCommand({
           return;
         }
         const topLevel = readdirSync4(tempDir).filter(
-          (entry) => statSync(join22(tempDir, entry)).isDirectory()
+          (entry) => statSync(join23(tempDir, entry)).isDirectory()
         );
         if (topLevel.length !== 1) {
           cliOutput(
@@ -35215,7 +35628,7 @@ var installCommand = defineCommand({
           return;
         }
         const agentName = topLevel[0];
-        const personaPath = join22(tempDir, agentName, "persona.cant");
+        const personaPath = join23(tempDir, agentName, "persona.cant");
         if (!existsSync12(personaPath)) {
           cliOutput(
             {
@@ -35230,11 +35643,11 @@ var installCommand = defineCommand({
           process.exitCode = 6;
           return;
         }
-        cantPath = join22(tempDir, `${agentName}.cant`);
+        cantPath = join23(tempDir, `${agentName}.cant`);
         copyFileSync(personaPath, cantPath);
       } else if (stat2.isDirectory()) {
         const agentName = basename2(resolvedPath);
-        const personaPath = join22(resolvedPath, "persona.cant");
+        const personaPath = join23(resolvedPath, "persona.cant");
         if (!existsSync12(personaPath)) {
           cliOutput(
             {
@@ -35249,9 +35662,9 @@ var installCommand = defineCommand({
           process.exitCode = 6;
           return;
         }
-        tempDir = join22(tmpdir(), `cleo-agent-install-${Date.now()}`);
-        mkdirSync4(tempDir, { recursive: true });
-        cantPath = join22(tempDir, `${agentName}.cant`);
+        tempDir = join23(tmpdir(), `cleo-agent-install-${Date.now()}`);
+        mkdirSync5(tempDir, { recursive: true });
+        cantPath = join23(tempDir, `${agentName}.cant`);
         copyFileSync(personaPath, cantPath);
       } else {
         cliOutput(
@@ -35379,7 +35792,7 @@ var packCommand = defineCommand({
   async run({ args }) {
     try {
       const { existsSync: existsSync12, statSync } = await import("node:fs");
-      const { resolve: resolve5, basename: basename2, dirname: dirname10 } = await import("node:path");
+      const { resolve: resolve5, basename: basename2, dirname: dirname11 } = await import("node:path");
       const { execFileSync: execFileSync6 } = await import("node:child_process");
       const resolvedDir = resolve5(args.dir);
       if (!existsSync12(resolvedDir) || !statSync(resolvedDir).isDirectory()) {
@@ -35396,8 +35809,8 @@ var packCommand = defineCommand({
         process.exitCode = 4;
         return;
       }
-      const { join: join22 } = await import("node:path");
-      const personaPath = join22(resolvedDir, "persona.cant");
+      const { join: join23 } = await import("node:path");
+      const personaPath = join23(resolvedDir, "persona.cant");
       if (!existsSync12(personaPath)) {
         cliOutput(
           {
@@ -35415,7 +35828,7 @@ var packCommand = defineCommand({
       const agentName = basename2(resolvedDir);
       const archiveName = `${agentName}.cantz`;
       const archivePath = resolve5(archiveName);
-      const parentDir = dirname10(resolvedDir);
+      const parentDir = dirname11(resolvedDir);
       try {
         execFileSync6("zip", ["-r", archivePath, agentName], {
           cwd: parentDir,
@@ -35445,7 +35858,7 @@ var packCommand = defineCommand({
           if (entry.isFile()) {
             fileCount++;
           } else if (entry.isDirectory()) {
-            countFiles(join22(dirPath, entry.name));
+            countFiles(join23(dirPath, entry.name));
           }
         }
       };
@@ -35514,8 +35927,8 @@ var createCommand = defineCommand({
   },
   async run({ args }) {
     try {
-      const { existsSync: existsSync12, mkdirSync: mkdirSync4, writeFileSync: writeFileSync4 } = await import("node:fs");
-      const { join: join22 } = await import("node:path");
+      const { existsSync: existsSync12, mkdirSync: mkdirSync5, writeFileSync: writeFileSync5 } = await import("node:fs");
+      const { join: join23 } = await import("node:path");
       const { homedir: homedir6 } = await import("node:os");
       const name = args.name;
       const role = args.role;
@@ -35575,12 +35988,12 @@ var createCommand = defineCommand({
       let targetRoot;
       if (isGlobal) {
         const home = homedir6();
-        const xdgData = process.env["XDG_DATA_HOME"] ?? join22(home, ".local", "share");
-        targetRoot = join22(xdgData, "cleo", "cant", "agents");
+        const xdgData = process.env["XDG_DATA_HOME"] ?? join23(home, ".local", "share");
+        targetRoot = join23(xdgData, "cleo", "cant", "agents");
       } else {
-        targetRoot = join22(process.cwd(), CLEO_DIR_NAME, CANT_AGENTS_SUBDIR);
+        targetRoot = join23(process.cwd(), CLEO_DIR_NAME, CANT_AGENTS_SUBDIR);
       }
-      const agentDir = join22(targetRoot, name);
+      const agentDir = join23(targetRoot, name);
       if (existsSync12(agentDir)) {
         cliOutput(
           {
@@ -35596,7 +36009,7 @@ var createCommand = defineCommand({
         process.exitCode = 6;
         return;
       }
-      mkdirSync4(agentDir, { recursive: true });
+      mkdirSync5(agentDir, { recursive: true });
       const personaContent = generatePersonaCant({
         name,
         role,
@@ -35605,29 +36018,29 @@ var createCommand = defineCommand({
         domain,
         parent
       });
-      writeFileSync4(join22(agentDir, "persona.cant"), personaContent, "utf-8");
+      writeFileSync5(join23(agentDir, "persona.cant"), personaContent, "utf-8");
       const manifest = generateManifest({ name, role, tier, domain });
-      writeFileSync4(
-        join22(agentDir, "manifest.json"),
+      writeFileSync5(
+        join23(agentDir, "manifest.json"),
         `${JSON.stringify(manifest, null, 2)}
 `,
         "utf-8"
       );
       const createdFiles = [
-        join22(agentDir, "persona.cant"),
-        join22(agentDir, "manifest.json")
+        join23(agentDir, "persona.cant"),
+        join23(agentDir, "manifest.json")
       ];
       if (team) {
         const teamConfigContent = generateTeamConfig(name, role, team);
-        writeFileSync4(join22(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
-        createdFiles.push(join22(agentDir, "team-config.cant"));
+        writeFileSync5(join23(agentDir, "team-config.cant"), teamConfigContent, "utf-8");
+        createdFiles.push(join23(agentDir, "team-config.cant"));
       }
       if (seedBrain) {
-        const expertiseDir = join22(agentDir, "expertise");
-        mkdirSync4(expertiseDir, { recursive: true });
+        const expertiseDir = join23(agentDir, "expertise");
+        mkdirSync5(expertiseDir, { recursive: true });
         const seedContent = generateMentalModelSeed(name, role, domain);
-        writeFileSync4(join22(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
-        createdFiles.push(join22(expertiseDir, "mental-model-seed.md"));
+        writeFileSync5(join23(expertiseDir, "mental-model-seed.md"), seedContent, "utf-8");
+        createdFiles.push(join23(expertiseDir, "mental-model-seed.md"));
         try {
           const { execFile: execFile2 } = await import("node:child_process");
           const { promisify: promisify2 } = await import("node:util");
@@ -35725,8 +36138,8 @@ var mintCommand = defineCommand({
   },
   async run({ args }) {
     try {
-      const { existsSync: existsSync12, readFileSync: readFileSync15, mkdirSync: mkdirSync4 } = await import("node:fs");
-      const { resolve: resolve5, join: join22 } = await import("node:path");
+      const { existsSync: existsSync12, readFileSync: readFileSync16, mkdirSync: mkdirSync5 } = await import("node:fs");
+      const { resolve: resolve5, join: join23 } = await import("node:path");
       const specPath = resolve5(args.spec);
       if (!existsSync12(specPath)) {
         const errEnv = {
@@ -35743,10 +36156,10 @@ 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 });
+      const outputDir = args["output-dir"] ? resolve5(args["output-dir"]) : join23(projectRoot, ".cleo", "cant", "agents");
+      mkdirSync5(outputDir, { recursive: true });
       if (args["dry-run"]) {
         const preview = {
           success: true,
@@ -37753,7 +38166,7 @@ var briefingCommand = defineCommand({
 // packages/cleo/src/cli/commands/bug.ts
 import { existsSync as existsSync7 } from "node:fs";
 import { appendFile as appendFile2, mkdir as mkdir2, readFile as readFile2 } from "node:fs/promises";
-import { dirname as dirname4, join as join9 } from "node:path";
+import { dirname as dirname5, join as join10 } from "node:path";
 import { getCleoDirAbsolute as getCleoDirAbsolute2, getCleoIdentity, getConfigPath, signAuditLine } from "@cleocode/core";
 init_cli();
 var SEVERITY_MAP = {
@@ -37806,8 +38219,8 @@ async function appendSignedBugSeverity(record) {
   const sig = await signAuditLine(id, canonical);
   const line = `${JSON.stringify({ ...full, _sig: sig })}
 `;
-  const auditPath = join9(getCleoDirAbsolute2(), "audit", "bug-severity.jsonl");
-  await mkdir2(dirname4(auditPath), { recursive: true });
+  const auditPath = join10(getCleoDirAbsolute2(), "audit", "bug-severity.jsonl");
+  await mkdir2(dirname5(auditPath), { recursive: true });
   await appendFile2(auditPath, line, { encoding: "utf-8" });
 }
 var bugCommand = defineCommand({
@@ -37919,8 +38332,8 @@ var cancelCommand = defineCommand({
 });
 
 // packages/cleo/src/cli/commands/cant.ts
-import { existsSync as existsSync8, mkdirSync, readFileSync as readFileSync8, writeFileSync } from "node:fs";
-import { dirname as dirname5, isAbsolute, join as join10, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync2, readFileSync as readFileSync9, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname6, isAbsolute, join as join11, resolve as resolve3 } from "node:path";
 init_renderers();
 function resolveFilePath(file) {
   return isAbsolute(file) ? file : resolve3(process.cwd(), file);
@@ -38070,7 +38483,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,
@@ -38080,9 +38493,9 @@ var cantMigrateCommand = defineCommand({
         const projectRoot = process.cwd();
         let written = 0;
         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");
+          const outputPath = isAbsolute(outputFile.path) ? outputFile.path : join11(projectRoot, outputFile.path);
+          mkdirSync2(dirname6(outputPath), { recursive: true });
+          writeFileSync2(outputPath, outputFile.content, "utf-8");
           written++;
         }
         cliOutput(
@@ -38130,7 +38543,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 +38580,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 +38749,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}`);
@@ -38679,9 +39092,9 @@ var codeCommand = defineCommand({
       async run({ args }) {
         await requireTreeSitter();
         const { smartOutline } = await import("@cleocode/core/internal");
-        const { join: join22 } = await import("node:path");
+        const { join: join23 } = await import("node:path");
         const root = process.cwd();
-        const absPath = args.file.startsWith("/") ? args.file : join22(root, args.file);
+        const absPath = args.file.startsWith("/") ? args.file : join23(root, args.file);
         const result = smartOutline(absPath, root);
         if (result.errors.length > 0 && result.symbols.length === 0) {
           console.error(`Error: ${result.errors.join(", ")}`);
@@ -38772,9 +39185,9 @@ var codeCommand = defineCommand({
       async run({ args }) {
         await requireTreeSitter();
         const { smartUnfold } = await import("@cleocode/core/internal");
-        const { join: join22 } = await import("node:path");
+        const { join: join23 } = await import("node:path");
         const root = process.cwd();
-        const absPath = args.file.startsWith("/") ? args.file : join22(root, args.file);
+        const absPath = args.file.startsWith("/") ? args.file : join23(root, args.file);
         const result = smartUnfold(absPath, args.symbol, root);
         if (!result.found) {
           console.error(`Symbol "${args.symbol}" not found in ${args.file}`);
@@ -39817,7 +40230,7 @@ var currentCommand = defineCommand({
 
 // packages/cleo/src/cli/commands/daemon.ts
 import { homedir as homedir2 } from "node:os";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 import { getGCDaemonStatus, spawnGCDaemon, stopGCDaemon } from "@cleocode/core/gc/daemon.js";
 async function showDaemonStatus(cleoDir, json2) {
   try {
@@ -39870,7 +40283,7 @@ var startCommand3 = defineCommand({
     }
   },
   async run({ args }) {
-    const cleoDir = args["cleo-dir"] ?? join11(homedir2(), ".cleo");
+    const cleoDir = args["cleo-dir"] ?? join12(homedir2(), ".cleo");
     const jsonMode = args.json ?? false;
     try {
       const status = await getGCDaemonStatus(cleoDir);
@@ -39901,7 +40314,7 @@ var startCommand3 = defineCommand({
       } else {
         process.stdout.write(`GC daemon started (PID ${pid})
 `);
-        process.stdout.write(`Logs: ${join11(cleoDir, "logs", "gc.log")}
+        process.stdout.write(`Logs: ${join12(cleoDir, "logs", "gc.log")}
 `);
       }
     } catch (err) {
@@ -39930,7 +40343,7 @@ var stopCommand3 = defineCommand({
     }
   },
   async run({ args }) {
-    const cleoDir = args["cleo-dir"] ?? join11(homedir2(), ".cleo");
+    const cleoDir = args["cleo-dir"] ?? join12(homedir2(), ".cleo");
     const jsonMode = args.json ?? false;
     try {
       const stopResult = await stopGCDaemon(cleoDir);
@@ -39976,7 +40389,7 @@ var statusCommand4 = defineCommand({
     }
   },
   async run({ args }) {
-    const cleoDir = args["cleo-dir"] ?? join11(homedir2(), ".cleo");
+    const cleoDir = args["cleo-dir"] ?? join12(homedir2(), ".cleo");
     await showDaemonStatus(cleoDir, args.json ?? false);
   }
 });
@@ -40002,7 +40415,7 @@ var daemonCommand = defineCommand({
   },
   async run({ args, cmd, rawArgs }) {
     if (isSubCommandDispatch(rawArgs, cmd.subCommands)) return;
-    const cleoDir = args["cleo-dir"] ?? join11(homedir2(), ".cleo");
+    const cleoDir = args["cleo-dir"] ?? join12(homedir2(), ".cleo");
     await showDaemonStatus(cleoDir, args.json ?? false);
   }
 });
@@ -40353,17 +40766,17 @@ 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 { dirname as dirname6, join as join12 } from "node:path";
+import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync11 } from "node:fs";
+import { dirname as dirname7, join as join13 } from "node:path";
 init_paths();
 init_renderers();
 function findProjectRoot() {
   let currentDir = process.cwd();
   while (currentDir !== "/") {
-    if (existsSync9(join12(currentDir, "package.json"))) {
+    if (existsSync9(join13(currentDir, "package.json"))) {
       return currentDir;
     }
-    const parent = dirname6(currentDir);
+    const parent = dirname7(currentDir);
     if (parent === currentDir) break;
     currentDir = parent;
   }
@@ -40376,11 +40789,11 @@ var detectDriftCommand = defineCommand({
   },
   async run() {
     const projectRoot = findProjectRoot();
-    const isCleoRepo = existsSync9(join12(projectRoot, "packages", "cleo", "src"));
-    const cleoSrcRoot = isCleoRepo ? join12(projectRoot, "packages", "cleo", "src") : join12(projectRoot, "src");
+    const isCleoRepo = existsSync9(join13(projectRoot, "packages", "cleo", "src"));
+    const cleoSrcRoot = isCleoRepo ? join13(projectRoot, "packages", "cleo", "src") : join13(projectRoot, "src");
     const safeRead = (filePath) => {
       try {
-        return readFileSync10(filePath, "utf-8");
+        return readFileSync11(filePath, "utf-8");
       } catch {
         return "";
       }
@@ -40391,7 +40804,7 @@ var detectDriftCommand = defineCommand({
         checks: [],
         recommendations: []
       };
-      const injPath = join12(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
+      const injPath = join13(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
       if (existsSync9(injPath)) {
         const content = safeRead(injPath);
         userResult.checks.push({
@@ -40443,9 +40856,9 @@ var detectDriftCommand = defineCommand({
       }
     };
     try {
-      const specPath = join12(projectRoot, "docs", "specs", "CLEO-OPERATION-CONSTITUTION.md");
-      const registryPath = join12(cleoSrcRoot, "dispatch", "registry.ts");
-      const dispatchDomainsDir = join12(cleoSrcRoot, "dispatch", "domains");
+      const specPath = join13(projectRoot, "docs", "specs", "CLEO-OPERATION-CONSTITUTION.md");
+      const registryPath = join13(cleoSrcRoot, "dispatch", "registry.ts");
+      const dispatchDomainsDir = join13(cleoSrcRoot, "dispatch", "domains");
       if (!existsSync9(specPath)) {
         addCheck("Gateway-to-spec sync", "fail", "CLEO-OPERATION-CONSTITUTION.md missing", [
           {
@@ -40514,8 +40927,8 @@ var detectDriftCommand = defineCommand({
       ]);
     }
     try {
-      const cliDir = join12(cleoSrcRoot, "cli", "commands");
-      const coreDir = isCleoRepo ? join12(projectRoot, "packages", "core", "src") : join12(projectRoot, "src", "core");
+      const cliDir = join13(cleoSrcRoot, "cli", "commands");
+      const coreDir = isCleoRepo ? join13(projectRoot, "packages", "core", "src") : join13(projectRoot, "src", "core");
       if (!existsSync9(cliDir)) {
         addCheck("CLI-to-core sync", "fail", "CLI commands directory missing", [
           {
@@ -40542,7 +40955,7 @@ var detectDriftCommand = defineCommand({
       addCheck("CLI-to-core sync", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const domainsDir = join12(cleoSrcRoot, "dispatch", "domains");
+      const domainsDir = join13(cleoSrcRoot, "dispatch", "domains");
       if (!existsSync9(domainsDir)) {
         addCheck("Domain handler coverage", "fail", "Dispatch domains directory missing", [
           {
@@ -40560,7 +40973,7 @@ var detectDriftCommand = defineCommand({
       addCheck("Domain handler coverage", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const matrixPath = join12(cleoSrcRoot, "dispatch", "lib", "capability-matrix.ts");
+      const matrixPath = join13(cleoSrcRoot, "dispatch", "lib", "capability-matrix.ts");
       if (!existsSync9(matrixPath)) {
         addCheck("Capability matrix", "fail", "Capability matrix missing", [
           {
@@ -40577,7 +40990,7 @@ var detectDriftCommand = defineCommand({
       addCheck("Capability matrix", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const schemaPath = join12(projectRoot, "src", "store", "schema.ts");
+      const schemaPath = join13(projectRoot, "src", "store", "schema.ts");
       if (!existsSync9(schemaPath)) {
         addCheck("Schema validation", "fail", "Schema definition missing", [
           {
@@ -40612,8 +41025,8 @@ var detectDriftCommand = defineCommand({
       addCheck("Schema validation", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const visionPath = join12(projectRoot, "docs", "concepts", "CLEO-VISION.md");
-      const specPath = join12(projectRoot, "docs", "specs", "CLEO-PORTABLE-PROJECT-BRAIN-SPEC.md");
+      const visionPath = join13(projectRoot, "docs", "concepts", "CLEO-VISION.md");
+      const specPath = join13(projectRoot, "docs", "specs", "CLEO-PORTABLE-PROJECT-BRAIN-SPEC.md");
       const issues = [];
       if (!existsSync9(visionPath)) {
         issues.push({
@@ -40668,7 +41081,7 @@ var detectDriftCommand = defineCommand({
       addCheck("Canonical identity", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const injectionPath = join12(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
+      const injectionPath = join13(projectRoot, CLEO_DIR_NAME, TEMPLATES_SUBDIR, CLEO_INJECTION_MD);
       if (!existsSync9(injectionPath)) {
         addCheck("Agent injection", "fail", "Agent injection template missing", [
           {
@@ -40698,7 +41111,7 @@ var detectDriftCommand = defineCommand({
       addCheck("Agent injection", "fail", `Error: ${getErrorMessage(e)}`);
     }
     try {
-      const exitCodesPath = join12(cleoSrcRoot, "dispatch", "lib", "exit-codes.ts");
+      const exitCodesPath = join13(cleoSrcRoot, "dispatch", "lib", "exit-codes.ts");
       if (!existsSync9(exitCodesPath)) {
         addCheck("Exit codes", "fail", "Exit codes definition missing", [
           {
@@ -40831,7 +41244,7 @@ var diagnosticsCommand = defineCommand({
 // packages/cleo/src/cli/commands/docs.ts
 init_src();
 import { mkdir as mkdir3, readdir, readFile as readFile3, writeFile } from "node:fs/promises";
-import { dirname as dirname7, isAbsolute as isAbsolute2, join as join13, resolve as resolve4 } from "node:path";
+import { dirname as dirname8, isAbsolute as isAbsolute2, join as join14, resolve as resolve4 } from "node:path";
 import {
   buildDocsGraph,
   CleoError as CleoError3,
@@ -40849,7 +41262,7 @@ import {
 init_cli();
 init_renderers();
 async function getScriptNames(projectRoot) {
-  const scriptsDir = join13(projectRoot, "scripts");
+  const scriptsDir = join14(projectRoot, "scripts");
   try {
     const files = await readdir(scriptsDir);
     return files.filter((f) => f.endsWith(".sh")).map((f) => f.replace(".sh", "")).sort();
@@ -40858,7 +41271,7 @@ async function getScriptNames(projectRoot) {
   }
 }
 async function getIndexedCommands(projectRoot) {
-  const indexPath = join13(projectRoot, "docs", "commands", "COMMANDS-INDEX.json");
+  const indexPath = join14(projectRoot, "docs", "commands", "COMMANDS-INDEX.json");
   const index = await readJson(indexPath);
   if (!index) return [];
   return index.commands.map((c) => c.name).sort();
@@ -40891,7 +41304,7 @@ async function runGapCheck(_projectRoot, filterId) {
     const reviewFiles = files.filter((f) => f.endsWith(".md"));
     for (const file of reviewFiles) {
       if (filterId && !file.includes(filterId)) continue;
-      const filePath = join13(reviewDir, file);
+      const filePath = join14(reviewDir, file);
       const content = await readFile3(filePath, "utf-8");
       const taskMatch = file.match(/^(T\d+)/);
       const taskId = taskMatch ? taskMatch[1] : "UNKNOWN";
@@ -41138,7 +41551,7 @@ var exportCommand4 = defineCommand({
       let writtenPath;
       if (typeof args.out === "string" && args.out.length > 0) {
         const outPath = isAbsolute2(args.out) ? args.out : resolve4(projectRoot, args.out);
-        await mkdir3(dirname7(outPath), { recursive: true });
+        await mkdir3(dirname8(outPath), { recursive: true });
         await writeFile(outPath, result.markdown, "utf8");
         writtenPath = outPath;
       }
@@ -41253,7 +41666,7 @@ var mergeCommand = defineCommand({
       });
       if (typeof args.out === "string" && args.out.length > 0) {
         const outPath = isAbsolute2(args.out) ? args.out : resolve4(projectRoot, args.out);
-        await mkdir3(dirname7(outPath), { recursive: true });
+        await mkdir3(dirname8(outPath), { recursive: true });
         await writeFile(outPath, result.merged, "utf8");
         process.stderr.write(`Wrote merged content to ${outPath}
 `);
@@ -41325,7 +41738,7 @@ var graphCommand = defineCommand({
       }
       if (typeof args.out === "string" && args.out.length > 0) {
         const outPath = isAbsolute2(args.out) ? args.out : resolve4(projectRoot, args.out);
-        await mkdir3(dirname7(outPath), { recursive: true });
+        await mkdir3(dirname8(outPath), { recursive: true });
         await writeFile(outPath, output, "utf8");
         process.stderr.write(`Wrote graph to ${outPath}
 `);
@@ -42249,7 +42662,7 @@ var findCommand2 = defineCommand({
 
 // packages/cleo/src/cli/commands/gc.ts
 import { homedir as homedir3 } from "node:os";
-import { join as join14 } from "node:path";
+import { join as join15 } from "node:path";
 import { runGC } from "@cleocode/core/gc/runner.js";
 import { readGCState } from "@cleocode/core/gc/state.js";
 function formatBytes(bytes) {
@@ -42281,7 +42694,7 @@ var runCommand2 = defineCommand({
     }
   },
   async run({ args }) {
-    const cleoDir = args["cleo-dir"] ?? join14(homedir3(), ".cleo");
+    const cleoDir = args["cleo-dir"] ?? join15(homedir3(), ".cleo");
     const dryRun = args["dry-run"];
     try {
       const gcResult = await runGC({ cleoDir, dryRun });
@@ -42336,8 +42749,8 @@ var statusCommand6 = defineCommand({
     }
   },
   async run({ args }) {
-    const cleoDir = args["cleo-dir"] ?? join14(homedir3(), ".cleo");
-    const statePath = join14(cleoDir, "gc-state.json");
+    const cleoDir = args["cleo-dir"] ?? join15(homedir3(), ".cleo");
+    const statePath = join15(cleoDir, "gc-state.json");
     try {
       const state = await readGCState(statePath);
       const result = { success: true, data: state };
@@ -42396,14 +42809,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 { dirname as dirname8, join as join15 } from "node:path";
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync12, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname9, join as join16 } 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 +42825,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 {
@@ -42556,11 +42969,11 @@ var generateChangelogCommand = defineCommand({
       const targetPlatform = args.platform;
       const dryRun = args["dry-run"] === true;
       const sourceFile = getChangelogSource();
-      const sourcePath = join15(getProjectRoot21(), sourceFile);
+      const sourcePath = join16(getProjectRoot21(), sourceFile);
       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) {
@@ -42569,9 +42982,9 @@ var generateChangelogCommand = defineCommand({
         const outputPath = platformConfig?.path ?? getDefaultOutputPath(targetPlatform);
         const content = generateForPlatform(targetPlatform, sourceContent, repoSlug, limit);
         if (!dryRun) {
-          const fullPath = join15(getProjectRoot21(), outputPath);
-          mkdirSync2(dirname8(fullPath), { recursive: true });
-          writeFileSync2(fullPath, content, "utf-8");
+          const fullPath = join16(getProjectRoot21(), outputPath);
+          mkdirSync3(dirname9(fullPath), { recursive: true });
+          writeFileSync3(fullPath, content, "utf-8");
         }
         results.push({ platform: targetPlatform, path: outputPath, written: !dryRun });
       } else {
@@ -42590,9 +43003,9 @@ var generateChangelogCommand = defineCommand({
             limit
           );
           if (!dryRun) {
-            const fullPath = join15(getProjectRoot21(), platformConfig.path);
-            mkdirSync2(dirname8(fullPath), { recursive: true });
-            writeFileSync2(fullPath, content, "utf-8");
+            const fullPath = join16(getProjectRoot21(), platformConfig.path);
+            mkdirSync3(dirname9(fullPath), { recursive: true });
+            writeFileSync3(fullPath, content, "utf-8");
           }
           results.push({
             platform: platformConfig.platform,
@@ -44000,9 +44413,9 @@ 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 mkdirSync4, 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 { join as join17 } from "node:path";
 import {
   getBrainDb as getBrainDb2,
   getBrainNativeDb as getBrainNativeDb3,
@@ -44046,7 +44459,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 {
@@ -44055,8 +44468,8 @@ 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");
+  if (!existsSync11(dir)) mkdirSync4(dir, { recursive: true });
+  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" },
@@ -45300,11 +45713,11 @@ var importCommand3 = defineCommand({
     }
   },
   async run({ args }) {
-    const sourceDir = args.from ?? join16(homedir4(), ".claude", "projects", "-mnt-projects-cleocode", "memory");
+    const sourceDir = args.from ?? join17(homedir4(), ".claude", "projects", "-mnt-projects-cleocode", "memory");
     const isDryRun = !!args["dry-run"];
     const isJson = !!args.json;
     const projectRoot = getProjectRoot22();
-    const stateFile = join16(projectRoot, CLEO_DIR_NAME, MIGRATE_MEMORY_HASHES_JSON);
+    const stateFile = join17(projectRoot, CLEO_DIR_NAME, MIGRATE_MEMORY_HASHES_JSON);
     if (!existsSync11(sourceDir)) {
       const msg = `Source directory not found: ${sourceDir}`;
       if (isJson) {
@@ -45314,7 +45727,7 @@ var importCommand3 = defineCommand({
       }
       process.exit(1);
     }
-    const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md").map((f) => join16(sourceDir, f));
+    const files = readdirSync3(sourceDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md").map((f) => join17(sourceDir, f));
     const importedHashes = isDryRun ? /* @__PURE__ */ new Set() : loadImportHashes(stateFile);
     const stats = { total: files.length, imported: 0, skipped: 0, errors: 0 };
     const importedEntries = [];
@@ -45329,7 +45742,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 +49626,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 +52853,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("-"));
@@ -54566,7 +55003,7 @@ var schemaCommand = defineCommand({
 init_src();
 import { execFile } from "node:child_process";
 import { readFile as readFile4 } from "node:fs/promises";
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 import * as readline2 from "node:readline";
 import { promisify } from "node:util";
 import {
@@ -54585,7 +55022,7 @@ var GITHUB_REPO = BUILD_CONFIG2.repository.fullName;
 async function getCurrentVersion() {
   const cleoHome = getCleoHome2();
   try {
-    const content = await readFile4(join17(cleoHome, "VERSION"), "utf-8");
+    const content = await readFile4(join18(cleoHome, "VERSION"), "utf-8");
     return (content.split("\n")[0] ?? "unknown").trim();
   } catch {
     return "unknown";
@@ -54639,7 +55076,7 @@ async function writeRuntimeVersionMetadata(mode, source, version) {
   ];
   await import("node:fs/promises").then(
     ({ writeFile: writeFile3, mkdir: mkdir5 }) => mkdir5(cleoHome, { recursive: true }).then(
-      () => writeFile3(join17(cleoHome, "VERSION"), `${lines.join("\n")}
+      () => writeFile3(join18(cleoHome, "VERSION"), `${lines.join("\n")}
 `, "utf-8")
     )
   );
@@ -55040,7 +55477,7 @@ async function runPostUpdateDiagnostics(opts) {
 }
 
 // packages/cleo/src/cli/commands/sentient.ts
-import { join as join18 } from "node:path";
+import { join as join19 } from "node:path";
 import { cwd as processCwd } from "node:process";
 import {
   getSentientDaemonStatus,
@@ -55111,7 +55548,7 @@ var startSub = defineCommand({
         return;
       }
       if (dryRun) {
-        const statePath2 = join18(projectRoot, SENTIENT_STATE_FILE);
+        const statePath2 = join19(projectRoot, SENTIENT_STATE_FILE);
         const outcome = await safeRunTick({ projectRoot, statePath: statePath2, dryRun: true });
         emitSuccess(
           { dryRun: true, outcome },
@@ -55245,7 +55682,7 @@ var tickSub = defineCommand({
     const jsonMode = args.json === true;
     const dryRun = args["dry-run"] === true;
     try {
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const outcome = await safeRunTick({ projectRoot, statePath, dryRun });
       emitSuccess(
         { outcome, dryRun },
@@ -55314,7 +55751,7 @@ var proposeAcceptSub = defineCommand({
         return;
       }
       await db.update(tasks).set({ status: "pending", updatedAt: now }).where(eq2(tasks.id, id)).run();
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const state = await readSentientState(statePath);
       await patchSentientState(statePath, {
         tier2Stats: {
@@ -55366,7 +55803,7 @@ var proposeRejectSub = defineCommand({
         return;
       }
       await db.update(tasks).set({ status: "cancelled", cancellationReason: reason, cancelledAt: now, updatedAt: now }).where(eq2(tasks.id, id)).run();
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const state = await readSentientState(statePath);
       await patchSentientState(statePath, {
         tier2Stats: {
@@ -55411,7 +55848,7 @@ var proposeRunSub = defineCommand({
     const projectRoot = resolveProjectRoot7(args.project);
     const jsonMode = args.json === true;
     try {
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const outcome = await safeRunProposeTick({ projectRoot, statePath });
       emitSuccess(
         { outcome },
@@ -55431,7 +55868,7 @@ var proposeEnableSub = defineCommand({
     const projectRoot = resolveProjectRoot7(args.project);
     const jsonMode = args.json === true;
     try {
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const updated = await patchSentientState(statePath, { tier2Enabled: true });
       emitSuccess({ tier2Enabled: updated.tier2Enabled }, jsonMode, "Tier-2 proposals enabled");
     } catch (err) {
@@ -55450,7 +55887,7 @@ var proposeDisableSub = defineCommand({
     const projectRoot = resolveProjectRoot7(args.project);
     const jsonMode = args.json === true;
     try {
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const updated = await patchSentientState(statePath, { tier2Enabled: false });
       emitSuccess({ tier2Enabled: updated.tier2Enabled }, jsonMode, "Tier-2 proposals disabled");
     } catch (err) {
@@ -55481,7 +55918,7 @@ var proposeSub = defineCommand({
     const projectRoot = resolveProjectRoot7(args.project);
     const jsonMode = args.json === true;
     try {
-      const statePath = join18(projectRoot, SENTIENT_STATE_FILE);
+      const statePath = join19(projectRoot, SENTIENT_STATE_FILE);
       const state = await readSentientState(statePath);
       emitSuccess(
         {
@@ -56364,7 +56801,7 @@ var searchCommand3 = defineCommand({
     );
   }
 });
-var validateCommand6 = defineCommand({
+var validateCommand7 = defineCommand({
   meta: { name: "validate", description: "Validate skill against protocol" },
   args: {
     "skill-name": {
@@ -56631,7 +57068,7 @@ var skillsCommand2 = defineCommand({
   subCommands: {
     list: listCommand20,
     search: searchCommand3,
-    validate: validateCommand6,
+    validate: validateCommand7,
     info: infoCommand,
     install: installCommand2,
     uninstall: uninstallCommand,
@@ -57212,10 +57649,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 +57690,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 +57790,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 +57804,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 = {
@@ -57556,7 +57993,7 @@ var tokenCommand = defineCommand({
 
 // packages/cleo/src/cli/commands/transcript.ts
 import { homedir as homedir5 } from "node:os";
-import { join as join19 } from "node:path";
+import { join as join20 } from "node:path";
 import { getProjectRoot as getProjectRoot27 } from "@cleocode/core";
 import {
   parseDurationMs,
@@ -57614,7 +58051,7 @@ var scanCommand = defineCommand({
       }
       return;
     }
-    const projectsDir = args["projects-dir"] ?? join19(homedir5(), ".claude", "projects");
+    const projectsDir = args["projects-dir"] ?? join20(homedir5(), ".claude", "projects");
     try {
       const result = await scanTranscripts(projectsDir);
       const envelope = {
@@ -57999,7 +58436,7 @@ var pruneCommand = defineCommand({
       process.exit(2);
       return;
     }
-    const projectsDir = args["projects-dir"] ?? join19(homedir5(), ".claude", "projects");
+    const projectsDir = args["projects-dir"] ?? join20(homedir5(), ".claude", "projects");
     try {
       const pruneResult = await pruneTranscripts({
         olderThanMs,
@@ -58425,7 +58862,7 @@ var verifyCommand2 = defineCommand({
 init_src();
 import { execFileSync as execFileSync5, spawn } from "node:child_process";
 import { mkdir as mkdir4, open, readFile as readFile5, rm, stat, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 import { CleoError as CleoError12, formatError as formatError14, getCleoHome as getCleoHome3 } from "@cleocode/core";
 init_renderers();
 var DEFAULT_PORT = 3456;
@@ -58433,10 +58870,10 @@ var DEFAULT_HOST = "127.0.0.1";
 function getWebPaths() {
   const cleoHome = getCleoHome3();
   return {
-    pidFile: join20(cleoHome, "web-server.pid"),
-    configFile: join20(cleoHome, "web-server.json"),
-    logDir: join20(cleoHome, "logs"),
-    logFile: join20(cleoHome, "logs", "web-server.log")
+    pidFile: join21(cleoHome, "web-server.pid"),
+    configFile: join21(cleoHome, "web-server.json"),
+    logDir: join21(cleoHome, "logs"),
+    logFile: join21(cleoHome, "logs", "web-server.log")
   };
 }
 function isProcessRunning(pid) {
@@ -58475,7 +58912,7 @@ async function startWebServer(port, host) {
     throw new CleoError12(1 /* GENERAL_ERROR */, `Server already running (PID: ${status.pid})`);
   }
   const projectRoot = process.env["CLEO_ROOT"] ?? process.cwd();
-  const studioDir = process.env["CLEO_STUDIO_DIR"] ?? join20(projectRoot, "packages", "studio", "build");
+  const studioDir = process.env["CLEO_STUDIO_DIR"] ?? join21(projectRoot, "packages", "studio", "build");
   await mkdir4(logDir, { recursive: true });
   await writeFile2(
     configFile,
@@ -58485,7 +58922,7 @@ async function startWebServer(port, host) {
       startedAt: (/* @__PURE__ */ new Date()).toISOString()
     })
   );
-  const webIndexPath = join20(studioDir, "index.js");
+  const webIndexPath = join21(studioDir, "index.js");
   try {
     await stat(webIndexPath);
   } catch {
@@ -58764,8 +59201,8 @@ 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 pkgPath = join22(dirname10(fileURLToPath3(import.meta.url)), "../../package.json");
+  const pkg = JSON.parse(readFileSync15(pkgPath, "utf-8"));
   return pkg.version;
 }
 var CLI_VERSION = getPackageVersion();