@titan-design/brain 0.6.1 → 0.7.0

package/dist/cli.js

@@ -11,7 +11,7 @@ import {
   saveConfig,
   withBrain,
   withDb
-} from "./chunk-HNC656YT.js";
+} from "./chunk-IESQY2UZ.js";
 import {
   createEmbedder,
   getEmbedderInfo
@@ -20,7 +20,7 @@ import {
   computeFacets,
   search,
   searchMemories
-} from "./chunk-KSJZ7CMP.js";
+} from "./chunk-4GDSQB2E.js";
 import {
   VALID_CORE_NOTE_TYPES,
   VALID_INBOX_SOURCES,
@@ -39,7 +39,7 @@ import {
   processInbox,
   slugify,
   traverseGraph
-} from "./chunk-AJKFX2TM.js";
+} from "./chunk-LLAHWRO4.js";
 import {
   INDEXABLE_EXTENSIONS,
   scanForChanges
@@ -53,7 +53,7 @@ import {
 
 // src/cli.ts
 import { createRequire } from "module";
-import { Command as Command46 } from "@commander-js/extra-typings";
+import { Command as Command49 } from "@commander-js/extra-typings";
 
 // src/commands/init.ts
 import { Command } from "@commander-js/extra-typings";
@@ -1317,7 +1317,8 @@ var TYPE_DIRS = {
   pattern: "patterns",
   meeting: "logs",
   "session-log": "logs",
-  guide: "guides"
+  guide: "guides",
+  workflow: "workflows"
 };
 function resolveOutputPath(notesDir, tier, type, id) {
   if (tier === "fast") {
@@ -1395,7 +1396,7 @@ function validateEnum(value, valid, label) {
 }
 var addCommand = new Command5("add").description("Create a new note from file or stdin").argument("[file]", "Input file path").option("--title <title>", "Note title").option(
   "--type <type>",
-  "Note type (note, decision, pattern, research, meeting, session-log, guide)"
+  "Note type (note, decision, pattern, research, meeting, session-log, guide, workflow)"
 ).option("--tier <tier>", "Note tier (slow, fast)").option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "One-line summary for search excerpts").option("--confidence <level>", "Confidence level (high, medium, low, speculative)").option("--status <status>", "Note status (current, outdated, deprecated, draft)").option("--category <cat>", "Category label").option("--related <ids>", "Comma-separated related note IDs").option("--review-interval <interval>", "Review interval (e.g. 90d, 30d, 180d)").option("--created <date>", "Created date (YYYY-MM-DD), defaults to today").option("--url <url>", "Fetch URL and create note from extracted content").action(async (file, opts, cmd) => {
   if (opts.type && !VALID_CORE_NOTE_TYPES.includes(opts.type)) {
     process.stderr.write(
@@ -2370,8 +2371,8 @@ import { join as join5 } from "path";
 function writeQueueFile(brainDir, context, registry) {
   const queueDir = join5(brainDir, "import-queue");
   mkdirSync5(queueDir, { recursive: true });
-  const basename7 = context.sourcePath.split("/").pop()?.replace(/\.[^.]+$/, "") ?? "unknown";
-  const slug = slugify(basename7);
+  const basename8 = context.sourcePath.split("/").pop()?.replace(/\.[^.]+$/, "") ?? "unknown";
+  const slug = slugify(basename8);
   const queuePath = join5(queueDir, `${slug}.md`);
   const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const lines2 = [];
@@ -2476,15 +2477,19 @@ async function runExtractionPipeline(content, filePath, registry, embedder, db,
     const lineCount = content.split("\n").length;
     const ext = filePath.split(".").pop()?.toLowerCase() ?? "txt";
     const format = detectFormat2(ext);
-    const queueResult = writeQueueFile(config.notesDir, {
-      sourcePath: filePath,
-      format,
-      lineCount,
-      tier1Items: tier1.items,
-      tier2Items,
-      lowConfidenceRegions: [],
-      remainderContent: tier2Remainder
-    }, registry);
+    const queueResult = writeQueueFile(
+      config.notesDir,
+      {
+        sourcePath: filePath,
+        format,
+        lineCount,
+        tier1Items: tier1.items,
+        tier2Items,
+        lowConfidenceRegions: [],
+        remainderContent: tier2Remainder
+      },
+      registry
+    );
     result.queuedFiles.push({ path: queueResult.queuePath, reason: queueResult.reason });
   }
   const handlers = registry.getContentHandlers();
@@ -3640,14 +3645,14 @@ async function runAllChecks(db, embedderBackend, ollamaUrl, ollamaModel, notesDi
     checkStaleNotes(db)
   ];
   if (notesDir) {
-    const { readdirSync: readdirSync5, statSync: statSync5 } = await import("fs");
-    const { join: join21 } = await import("path");
+    const { readdirSync: readdirSync7, statSync: statSync5 } = await import("fs");
+    const { join: join23 } = await import("path");
     const { INDEXABLE_EXTENSIONS: INDEXABLE_EXTENSIONS2 } = await import("./file-scanner-LBBH5I44.js");
     const diskFiles = /* @__PURE__ */ new Set();
     try {
-      const entries = readdirSync5(notesDir, { recursive: true });
+      const entries = readdirSync7(notesDir, { recursive: true });
       for (const entry of entries) {
-        const full = join21(notesDir, entry);
+        const full = join23(notesDir, entry);
         try {
           if (statSync5(full).isFile()) {
             const ext = full.slice(full.lastIndexOf(".")).toLowerCase();
@@ -3746,11 +3751,11 @@ var doctorCommand = new Command21("doctor").description("Check system health and
       }
       const fsCheck = report.checks.find((c) => c.name === "Filesystem sync");
       if (fsCheck?.status === "warning" && fsCheck.message.includes("orphaned")) {
-        const { existsSync: existsSync22 } = await import("fs");
+        const { existsSync: existsSync26 } = await import("fs");
         const dbFiles = db.getAllFiles();
         let cleaned = 0;
         for (const [path] of dbFiles) {
-          if (!existsSync22(path)) {
+          if (!existsSync26(path)) {
             db.deleteFile(path);
             cleaned++;
           }
@@ -3983,18 +3988,34 @@ notesCommand.command("list").description("List all notes").option("--module <nam
 });
 
 // src/modules/pm/index.ts
-import { Command as Command44 } from "@commander-js/extra-typings";
+import { Command as Command43 } from "@commander-js/extra-typings";
 
 // src/modules/pm/commands/project.ts
 import { Command as Command26 } from "@commander-js/extra-typings";
 import { existsSync as existsSync13, readFileSync as readFileSync13 } from "fs";
 
-// src/modules/pm/errors.ts
+// src/errors.ts
 function ok(data) {
   return { ok: true, data };
 }
 function fail(code, message, details) {
-  return { ok: false, error: pmError(code, message, details) };
+  const error = {
+    error: true,
+    code,
+    message
+  };
+  if (details !== void 0) {
+    error.details = details;
+  }
+  return { ok: false, error };
+}
+
+// src/modules/pm/errors.ts
+function ok2(data) {
+  return ok(data);
+}
+function fail2(code, message, details) {
+  return fail(code, message, details);
 }
 function pmError(code, message, details) {
   const err = { error: true, code, message };
@@ -4060,13 +4081,13 @@ function nextWorkstreamNumber(db, prefix) {
 function resolveWorkstreamFilter(input) {
   const asInt = Number(input);
   if (Number.isInteger(asInt) && asInt > 0) {
-    return ok(asInt);
+    return ok2(asInt);
   }
   const parsed = parseDisplayId(input);
   if (parsed && parsed.workstream !== void 0 && parsed.task === void 0) {
-    return ok(parsed.workstream);
+    return ok2(parsed.workstream);
   }
-  return fail(
+  return fail2(
     "INVALID_INPUT",
     `Invalid workstream filter "${input}". Use a number (6) or display ID (PREFIX-NN). Run "brain pm workstream list" to see options.`
   );
@@ -4091,7 +4112,7 @@ var PM_ACTIVE_PROJECT_KEY = "pm_active_project";
 function resolveDisplayId(db, displayId) {
   const noteIds = db.getModuleNoteIds({ module: "pm" });
   if (noteIds.length === 0) {
-    return fail("NOT_FOUND", `No PM notes found. Run "brain pm list" to check projects.`);
+    return fail2("NOT_FOUND", `No PM notes found. Run "brain pm list" to check projects.`);
   }
   const notes = db.getNotesByIds(noteIds);
   const knownPrefixes = /* @__PURE__ */ new Set();
@@ -4099,7 +4120,7 @@ function resolveDisplayId(db, displayId) {
     if (!note.metadata) continue;
     const meta = JSON.parse(note.metadata);
     if (meta.display_id === displayId) {
-      return ok(note.id);
+      return ok2(note.id);
     }
     if (typeof meta.prefix === "string") {
       knownPrefixes.add(meta.prefix);
@@ -4107,7 +4128,7 @@ function resolveDisplayId(db, displayId) {
   }
   const prefixList = [...knownPrefixes].sort().join(", ");
   const hint = prefixList ? ` Known projects: ${prefixList}. Run "brain pm list" to see all projects.` : ' Run "brain pm list" to check available projects.';
-  return fail("NOT_FOUND", `No PM note found with display ID "${displayId}".${hint}`);
+  return fail2("NOT_FOUND", `No PM note found with display ID "${displayId}".${hint}`);
 }
 function getProjectNotes(db, prefix) {
   const noteIds = db.getModuleNoteIds({ module: "pm" });
@@ -4140,35 +4161,35 @@ function resolveProject(db, explicit) {
           const m = JSON.parse(p.metadata);
           return m.prefix;
         });
-        return fail(
+        return fail2(
           "NOT_FOUND",
           `Project "${upper}" not found. Available projects: ${available.sort().join(", ")}.`
         );
       }
-      return fail("NOT_FOUND", `Project "${upper}" not found. No projects exist yet.`);
+      return fail2("NOT_FOUND", `Project "${upper}" not found. No projects exist yet.`);
     }
-    return ok(upper);
+    return ok2(upper);
   }
   const active = getActiveProject(db);
-  if (active) return ok(active);
+  if (active) return ok2(active);
   const projects = getPmNotes(db, "project");
   if (projects.length === 1) {
     const meta = JSON.parse(projects[0].metadata);
     const prefix = meta.prefix;
     setActiveProject(db, prefix);
-    return ok(prefix);
+    return ok2(prefix);
   }
   if (projects.length > 1) {
     const prefixes = projects.map((p) => {
       const m = JSON.parse(p.metadata);
       return m.prefix;
     });
-    return fail(
+    return fail2(
       "INVALID_INPUT",
       `Multiple projects found: ${prefixes.join(", ")}. Use --project <prefix> or "brain pm use <prefix>".`
     );
   }
-  return fail("INVALID_INPUT", 'No projects found. Run "brain pm onboard <name>" to create one.');
+  return fail2("INVALID_INPUT", 'No projects found. Run "brain pm onboard <name>" to create one.');
 }
 function resolveProjectOrAll(db, explicit) {
   if (explicit) {
@@ -4176,15 +4197,15 @@ function resolveProjectOrAll(db, explicit) {
     return result;
   }
   const active = getActiveProject(db);
-  if (active) return ok(active);
+  if (active) return ok2(active);
   const projects = getPmNotes(db, "project");
   if (projects.length === 1) {
     const meta = JSON.parse(projects[0].metadata);
     const prefix = meta.prefix;
     setActiveProject(db, prefix);
-    return ok(prefix);
+    return ok2(prefix);
   }
-  return ok(null);
+  return ok2(null);
 }
 function getAllProjectPrefixes(db) {
   const projects = getPmNotes(db, "project");
@@ -4241,19 +4262,28 @@ function buildProjectMarkdown(input) {
   if (input.wipLimit !== void 0) {
     lines2.push(`wip_limit: ${input.wipLimit}`);
   }
+  if (input.path) lines2.push(`path: "${input.path}"`);
+  if (input.remote) lines2.push(`remote: "${input.remote}"`);
+  if (input.defaultBranch) lines2.push(`default_branch: "${input.defaultBranch}"`);
+  if (input.reviewThreshold !== void 0) lines2.push(`review_threshold: ${input.reviewThreshold}`);
+  if (input.packageName) lines2.push(`package_name: "${input.packageName}"`);
+  if (input.packageManager) lines2.push(`package_manager: "${input.packageManager}"`);
+  if (input.commands) lines2.push(`commands: '${JSON.stringify(input.commands)}'`);
+  if (input.branchPrefix) lines2.push(`branch_prefix: '${JSON.stringify(input.branchPrefix)}'`);
+  if (input.notes) lines2.push(`notes: '${JSON.stringify(input.notes)}'`);
   lines2.push(`created: ${now}`, `modified: ${now}`, "---", "", `# ${input.name}`, "");
   return lines2.join("\n");
 }
 async function createProject(db, config, embedder, input) {
   if (!validatePrefix(input.prefix)) {
-    return fail(
+    return fail2(
       "INVALID_INPUT",
       `Invalid prefix "${input.prefix}": must be 2-5 uppercase alphanumeric characters`
     );
   }
   const existing = getPmNotes(db, "project", { prefix: input.prefix });
   if (existing.length > 0) {
-    return fail("PROJECT_EXISTS", `Project with prefix "${input.prefix}" already exists`);
+    return fail2("PROJECT_EXISTS", `Project with prefix "${input.prefix}" already exists`);
   }
   const filePath = projectFilePath(config, input.prefix);
   const dir = dirname3(filePath);
@@ -4269,18 +4299,48 @@ async function createProject(db, config, embedder, input) {
     prefix: input.prefix,
     status: "active",
     phase: input.phase,
-    wip_limit: input.wipLimit
+    wip_limit: input.wipLimit,
+    path: input.path,
+    remote: input.remote,
+    default_branch: input.defaultBranch,
+    review_threshold: input.reviewThreshold,
+    package_name: input.packageName,
+    package_manager: input.packageManager,
+    commands: input.commands,
+    branch_prefix: input.branchPrefix,
+    notes: input.notes
   };
-  return ok(metadata);
+  return ok2(metadata);
 }
 function projectMetaFromRecord(meta) {
+  const parseJsonField = (val) => {
+    if (!val) return void 0;
+    if (typeof val === "object") return val;
+    if (typeof val === "string") {
+      try {
+        return JSON.parse(val);
+      } catch {
+        return void 0;
+      }
+    }
+    return void 0;
+  };
   return {
     title: meta.title ?? void 0,
     display_id: meta.display_id,
     prefix: meta.prefix,
     status: meta.status,
     phase: meta.phase,
-    wip_limit: meta.wip_limit
+    wip_limit: meta.wip_limit,
+    path: meta.path,
+    remote: meta.remote,
+    default_branch: meta.default_branch,
+    review_threshold: meta.review_threshold,
+    package_name: meta.package_name,
+    package_manager: meta.package_manager,
+    commands: parseJsonField(meta.commands),
+    branch_prefix: parseJsonField(meta.branch_prefix),
+    notes: parseJsonField(meta.notes)
   };
 }
 function listProjects(db) {
@@ -4289,7 +4349,7 @@ function listProjects(db) {
     const meta = JSON.parse(note.metadata);
     return projectMetaFromRecord(meta);
   });
-  return ok(projects);
+  return ok2(projects);
 }
 function availableProjectsList(db) {
   const notes = getPmNotes(db, "project");
@@ -4303,20 +4363,20 @@ function availableProjectsList(db) {
 function getProject(db, prefix) {
   const notes = getPmNotes(db, "project", { prefix });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
+    return fail2("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
   }
   const meta = JSON.parse(notes[0].metadata);
-  return ok(projectMetaFromRecord(meta));
+  return ok2(projectMetaFromRecord(meta));
 }
 async function updateProject(db, config, embedder, prefix, updates) {
   const notes = getPmNotes(db, "project", { prefix });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
+    return fail2("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
   }
   const note = notes[0];
   const filePath = note.filePath;
   if (!existsSync7(filePath)) {
-    return fail("NOT_FOUND", `Project file not found at "${filePath}"`);
+    return fail2("NOT_FOUND", `Project file not found at "${filePath}"`);
   }
   const content = readFileSync8(filePath, "utf-8");
   let updated = content;
@@ -4329,6 +4389,41 @@ async function updateProject(db, config, embedder, prefix, updates) {
   if (updates.wip_limit !== void 0) {
     updated = replaceFrontmatterField(updated, "wip_limit", String(updates.wip_limit));
   }
+  if (updates.path !== void 0) {
+    updated = replaceFrontmatterField(updated, "path", `"${updates.path}"`);
+  }
+  if (updates.remote !== void 0) {
+    updated = replaceFrontmatterField(updated, "remote", `"${updates.remote}"`);
+  }
+  if (updates.default_branch !== void 0) {
+    updated = replaceFrontmatterField(updated, "default_branch", `"${updates.default_branch}"`);
+  }
+  if (updates.review_threshold !== void 0) {
+    updated = replaceFrontmatterField(
+      updated,
+      "review_threshold",
+      String(updates.review_threshold)
+    );
+  }
+  if (updates.package_name !== void 0) {
+    updated = replaceFrontmatterField(updated, "package_name", `"${updates.package_name}"`);
+  }
+  if (updates.package_manager !== void 0) {
+    updated = replaceFrontmatterField(updated, "package_manager", `"${updates.package_manager}"`);
+  }
+  if (updates.commands !== void 0) {
+    updated = replaceFrontmatterField(updated, "commands", `'${JSON.stringify(updates.commands)}'`);
+  }
+  if (updates.branch_prefix !== void 0) {
+    updated = replaceFrontmatterField(
+      updated,
+      "branch_prefix",
+      `'${JSON.stringify(updates.branch_prefix)}'`
+    );
+  }
+  if (updates.notes !== void 0) {
+    updated = replaceFrontmatterField(updated, "notes", `'${JSON.stringify(updates.notes)}'`);
+  }
   const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   updated = replaceFrontmatterField(updated, "modified", now);
   writeFileSync7(filePath, updated, "utf-8");
@@ -4336,17 +4431,17 @@ async function updateProject(db, config, embedder, prefix, updates) {
   const noteId = await indexSingleFile(db, embedder, filePath, updated, hash, Date.now());
   const refreshedNote = db.getNoteById(noteId);
   const meta = JSON.parse(refreshedNote.metadata);
-  return ok(projectMetaFromRecord(meta));
+  return ok2(projectMetaFromRecord(meta));
 }
 async function deleteProject(db, config, prefix, force) {
   const notes = getPmNotes(db, "project", { prefix });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
+    return fail2("NOT_FOUND", `Project "${prefix}" not found.${availableProjectsList(db)}`);
   }
   const projectNotes = getProjectNotes(db, prefix);
   const nonProjectNotes = projectNotes.filter((n) => n.id !== notes[0].id);
   if (nonProjectNotes.length > 0 && !force) {
-    return fail(
+    return fail2(
       "HAS_DEPENDENTS",
       `Project "${prefix}" has ${nonProjectNotes.length} dependent note(s). Use force to delete.`,
       { count: nonProjectNotes.length }
@@ -4370,7 +4465,7 @@ async function deleteProject(db, config, prefix, force) {
   if (existsSync7(projectDir)) {
     rmSync2(projectDir, { recursive: true, force: true });
   }
-  return ok(void 0);
+  return ok2(void 0);
 }
 function replaceFrontmatterField(content, field, value) {
   const endOfFrontmatter = content.indexOf("\n---", 4);
@@ -4378,7 +4473,8 @@ function replaceFrontmatterField(content, field, value) {
   const frontmatter = content.slice(0, endOfFrontmatter);
   const rest = content.slice(endOfFrontmatter);
   const fieldRegex = new RegExp(`^${field}:.*$`, "m");
-  const quoted = value.includes(" ") ? `"${value}"` : value;
+  const isAlreadyQuoted = value.startsWith("'") && value.endsWith("'") || value.startsWith('"') && value.endsWith('"');
+  const quoted = isAlreadyQuoted ? value : value.includes(" ") ? `"${value}"` : value;
   if (fieldRegex.test(frontmatter)) {
     return frontmatter.replace(fieldRegex, `${field}: ${quoted}`) + rest;
   }
@@ -4393,23 +4489,24 @@ import { join as join12, dirname as dirname6 } from "path";
 
 // src/modules/pm/engine/state-machine.ts
 var TRANSITIONS = {
-  pending: ["claimed", "blocked", "cancelled"],
+  pending: ["claimed", "blocked", "cancelled", "pruned"],
   claimed: ["in-progress", "pending", "cancelled"],
   "in-progress": ["done", "blocked", "cancelled", "pending"],
   done: [],
-  blocked: ["pending", "cancelled"],
-  cancelled: []
+  blocked: ["pending", "cancelled", "pruned"],
+  cancelled: [],
+  pruned: []
 };
 var DEFAULT_STALE_MS = 7 * 24 * 60 * 60 * 1e3;
 function validateTransition(from, to) {
   const allowed = TRANSITIONS[from];
   if (allowed.includes(to)) {
-    return ok(void 0);
+    return ok2(void 0);
   }
   const validList = allowed.length > 0 ? allowed.join(", ") : "none (terminal state)";
   const hint = buildTransitionHint(from, to);
   const message = `Cannot transition from '${from}' to '${to}'. Valid: ${validList}.${hint}`;
-  return fail("INVALID_TRANSITION", message, { from, to });
+  return fail2("INVALID_TRANSITION", message, { from, to });
 }
 function buildTransitionHint(from, to) {
   if (from === "pending" && to === "done") {
@@ -4423,6 +4520,7 @@ function buildTransitionHint(from, to) {
 function computeVirtualState(input) {
   const states = [];
   const { status, dependenciesComplete, hasDependencies, claimedAt, dueDate } = input;
+  if (status === "pruned") return states;
   if (status === "pending") {
     if (!hasDependencies || dependenciesComplete) {
       states.push("+READY", "+ELIGIBLE");
@@ -4441,7 +4539,7 @@ function computeVirtualState(input) {
       states.push("+STALE");
     }
   }
-  if (dueDate && !["done", "cancelled"].includes(status)) {
+  if (dueDate && !["done", "cancelled", "pruned"].includes(status)) {
     const now = input.now ?? /* @__PURE__ */ new Date();
     const due = /* @__PURE__ */ new Date(dueDate + "T23:59:59");
     if (due < now) {
@@ -4519,7 +4617,10 @@ function computeEligible(db, prefix) {
   for (const t of tasks) {
     if (t.status !== "pending") continue;
     const deps = graph.get(t.displayId) ?? [];
-    const allDepsDone = deps.every((dep) => statusByDisplay.get(dep) === "done");
+    const allDepsDone = deps.every((dep) => {
+      const s = statusByDisplay.get(dep);
+      return s === "done" || s === "pruned";
+    });
     if (allDepsDone) {
       eligible.push(t.displayId);
     }
@@ -4531,7 +4632,7 @@ function detectCycles(graph) {
   const visited = /* @__PURE__ */ new Set();
   const inStack = /* @__PURE__ */ new Set();
   const path = [];
-  function dfs(node) {
+  function dfs2(node) {
     if (inStack.has(node)) {
       const cycleStart = path.indexOf(node);
       cycles.push(path.slice(cycleStart).concat(node));
@@ -4542,20 +4643,22 @@ function detectCycles(graph) {
     inStack.add(node);
     path.push(node);
     for (const neighbor of graph.get(node) ?? []) {
-      dfs(neighbor);
+      dfs2(neighbor);
     }
     path.pop();
     inStack.delete(node);
   }
   for (const node of graph.keys()) {
-    dfs(node);
+    dfs2(node);
   }
   return cycles;
 }
 function computeWaves(db, prefix) {
   const tasks = getProjectTasks(db, prefix);
   const graph = buildDependencyGraph(db, prefix);
-  const activeTasks = tasks.filter((t) => t.status !== "done" && t.status !== "cancelled");
+  const activeTasks = tasks.filter(
+    (t) => t.status !== "done" && t.status !== "cancelled" && t.status !== "pruned"
+  );
   const activeIds = new Set(activeTasks.map((t) => t.displayId));
   const statusByDisplay = /* @__PURE__ */ new Map();
   for (const t of tasks) {
@@ -4748,7 +4851,7 @@ function computeHash(task, deps, decisions, prompt) {
 function assembleContext(db, taskDisplayId, options) {
   const taskNotes = getPmNotes(db, "task", { display_id: taskDisplayId });
   if (taskNotes.length === 0) {
-    return fail("NOT_FOUND", `Task "${taskDisplayId}" not found`);
+    return fail2("NOT_FOUND", `Task "${taskDisplayId}" not found`);
   }
   const taskNote = taskNotes[0];
   const task = JSON.parse(taskNote.metadata);
@@ -4759,7 +4862,7 @@ function assembleContext(db, taskDisplayId, options) {
   const decisions = findImpactingDecisions(db, taskDisplayId, task.project);
   const prompt = findPromptContent(db, taskDisplayId, task.project);
   const contextHash = computeHash(task, dependencies, decisions, prompt);
-  return ok({
+  return ok2({
     task,
     body,
     workstream,
@@ -4845,7 +4948,7 @@ async function assembleDispatch(db, embedder, config, taskDisplayId, options) {
   const wsDescription = ctx.workstream ? findWorkstreamDescription(db, ctx.task.project, ctx.task.workstream) : "";
   const allTasksResult = listTasks(db, ctx.task.project);
   const downstreamDependents = allTasksResult.ok ? allTasksResult.data.filter((t) => t.depends_on?.includes(taskDisplayId)).map((t) => ({ displayId: t.display_id, title: t.title ?? t.display_id })) : [];
-  return ok({
+  return ok2({
     ...ctx,
     peerTasks,
     workstreamDescription: wsDescription,
@@ -4861,7 +4964,7 @@ function findWorkstreamDescription(db, project, workstreamNum) {
 function assembleProjectContext(db, prefix) {
   const projectNotes = getPmNotes(db, "project", { prefix });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${prefix}" not found`);
+    return fail2("NOT_FOUND", `Project "${prefix}" not found`);
   }
   const projectNote = projectNotes[0];
   const meta = JSON.parse(projectNote.metadata);
@@ -4883,14 +4986,14 @@ function assembleProjectContext(db, prefix) {
     });
   }
   const allTasks = listTasks(db, prefix, { priority: "critical" });
-  const criticalTasks = (allTasks.ok ? allTasks.data : []).filter((t) => t.status !== "done" && t.status !== "cancelled").map(({ virtualStates: _vs, ...rest }) => rest);
+  const criticalTasks = (allTasks.ok ? allTasks.data : []).filter((t) => t.status !== "done" && t.status !== "cancelled" && t.status !== "pruned").map(({ virtualStates: _vs, ...rest }) => rest);
   const allProjectTasks = listTasks(db, prefix);
   const dist = {};
   for (const t of allProjectTasks.ok ? allProjectTasks.data : []) {
     dist[t.status] = (dist[t.status] ?? 0) + 1;
   }
   const decisions = findProjectDecisions(db, prefix);
-  return ok({
+  return ok2({
     project: {
       prefix,
       name: meta.title ?? meta.name ?? prefix,
@@ -4907,7 +5010,7 @@ function assembleProjectContext(db, prefix) {
 async function assembleWorkstreamContext(db, wsDisplayId, embedder, config) {
   const wsNotes = getPmNotes(db, "workstream", { display_id: wsDisplayId });
   if (wsNotes.length === 0) {
-    return fail("NOT_FOUND", `Workstream "${wsDisplayId}" not found`);
+    return fail2("NOT_FOUND", `Workstream "${wsDisplayId}" not found`);
   }
   const wsNote = wsNotes[0];
   const wsMeta = JSON.parse(wsNote.metadata);
@@ -4953,7 +5056,7 @@ async function assembleWorkstreamContext(db, wsDisplayId, embedder, config) {
       }
     }
   }
-  return ok({
+  return ok2({
     workstream: {
       displayId: wsDisplayId,
       title: wsMeta.title ?? wsNote.title,
@@ -5069,7 +5172,7 @@ function workstreamMetaFromRecord(meta, description) {
 async function createWorkstream(db, config, embedder, input) {
   const projectNotes = getPmNotes(db, "project", { prefix: input.project });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${input.project}" not found`);
+    return fail2("NOT_FOUND", `Project "${input.project}" not found`);
   }
   const number = nextWorkstreamNumber(db, input.project);
   const displayId = formatDisplayId(input.project, number);
@@ -5094,7 +5197,7 @@ async function createWorkstream(db, config, embedder, input) {
     number,
     status: "active"
   };
-  return ok(metadata);
+  return ok2(metadata);
 }
 function listWorkstreams(db, prefix) {
   const notes = getPmNotes(db, "workstream", { project: prefix });
@@ -5103,26 +5206,26 @@ function listWorkstreams(db, prefix) {
     const description = extractDescription(note.filePath);
     return workstreamMetaFromRecord(meta, description);
   });
-  return ok(workstreams);
+  return ok2(workstreams);
 }
 function getWorkstream(db, displayId) {
   const notes = getPmNotes(db, "workstream", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Workstream "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Workstream "${displayId}" not found`);
   }
   const meta = JSON.parse(notes[0].metadata);
   const description = extractDescription(notes[0].filePath);
-  return ok(workstreamMetaFromRecord(meta, description));
+  return ok2(workstreamMetaFromRecord(meta, description));
 }
 async function updateWorkstream(db, config, embedder, displayId, updates) {
   const notes = getPmNotes(db, "workstream", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Workstream "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Workstream "${displayId}" not found`);
   }
   const note = notes[0];
   const filePath = note.filePath;
   if (!existsSync9(filePath)) {
-    return fail("NOT_FOUND", `Workstream file not found at "${filePath}"`);
+    return fail2("NOT_FOUND", `Workstream file not found at "${filePath}"`);
   }
   const content = readFileSync10(filePath, "utf-8");
   let updated = content;
@@ -5136,23 +5239,23 @@ async function updateWorkstream(db, config, embedder, displayId, updates) {
   const noteId = await indexSingleFile(db, embedder, filePath, updated, hash, Date.now());
   const refreshedNote = db.getNoteById(noteId);
   const meta = JSON.parse(refreshedNote.metadata);
-  return ok(workstreamMetaFromRecord(meta));
+  return ok2(workstreamMetaFromRecord(meta));
 }
 async function deleteWorkstream(db, config, displayId, force) {
   const notes = getPmNotes(db, "workstream", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Workstream "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Workstream "${displayId}" not found`);
   }
   const parsed = parseDisplayId(displayId);
   if (!parsed || parsed.workstream === void 0) {
-    return fail("INVALID_INPUT", `Invalid workstream display ID "${displayId}"`);
+    return fail2("INVALID_INPUT", `Invalid workstream display ID "${displayId}"`);
   }
   const taskNotes = getPmNotes(db, "task", {
     project: parsed.prefix,
     workstream: parsed.workstream
   });
   if (taskNotes.length > 0 && !force) {
-    return fail(
+    return fail2(
       "HAS_DEPENDENTS",
       `Workstream "${displayId}" has ${taskNotes.length} task(s). Use force to delete.`,
       { count: taskNotes.length }
@@ -5171,7 +5274,7 @@ async function deleteWorkstream(db, config, displayId, force) {
   if (existsSync9(wsNote.filePath)) {
     unlinkSync3(wsNote.filePath);
   }
-  return ok(void 0);
+  return ok2(void 0);
 }
 
 // src/modules/pm/engine/activity.ts
@@ -5367,15 +5470,15 @@ function mergeDependsOn(db, noteId, frontmatterDeps) {
 async function createTask(db, config, embedder, input) {
   const projectNotes = getPmNotes(db, "project", { prefix: input.project });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${input.project}" not found`);
+    return fail2("NOT_FOUND", `Project "${input.project}" not found`);
   }
   const wsDisplayId = formatDisplayId(input.project, input.workstream);
   const wsNotes = getPmNotes(db, "workstream", { display_id: wsDisplayId });
   if (wsNotes.length === 0) {
-    return fail("NOT_FOUND", `Workstream "${wsDisplayId}" not found`);
+    return fail2("NOT_FOUND", `Workstream "${wsDisplayId}" not found`);
   }
   if (!input.description?.trim()) {
-    return fail(
+    return fail2(
       "INVALID_INPUT",
       "Task description is required \u2014 tasks without body content are invisible to search"
     );
@@ -5385,7 +5488,7 @@ async function createTask(db, config, embedder, input) {
     for (const depDisplayId of input.dependsOn) {
       const resolved = resolveDisplayId(db, depDisplayId);
       if (!resolved.ok) {
-        return fail("NOT_FOUND", `Dependency "${depDisplayId}" not found`);
+        return fail2("NOT_FOUND", `Dependency "${depDisplayId}" not found`);
       }
       resolvedDepIds.push({ displayId: depDisplayId, noteId: resolved.data });
     }
@@ -5445,7 +5548,7 @@ async function createTask(db, config, embedder, input) {
     acceptance_criteria: input.acceptanceCriteria,
     references: input.references
   };
-  return ok(metadata);
+  return ok2(metadata);
 }
 function listTasks(db, prefix, filters, listMode = "default") {
   const VIRTUAL_STATE_FILTERS = {
@@ -5545,7 +5648,7 @@ function listTasks(db, prefix, filters, listMode = "default") {
     );
   }
   const cleaned = tasks.map(({ _body, ...rest }) => rest);
-  return ok(cleaned);
+  return ok2(cleaned);
 }
 function didYouMeanTask(db, displayId) {
   const parsed = parseDisplayId(displayId);
@@ -5565,7 +5668,7 @@ function getTask(db, displayId) {
   if (notes.length === 0) {
     const suggestion = didYouMeanTask(db, displayId);
     const hint = suggestion ? ` Did you mean "${suggestion}"?` : "";
-    return fail("NOT_FOUND", `Task "${displayId}" not found.${hint}`);
+    return fail2("NOT_FOUND", `Task "${displayId}" not found.${hint}`);
   }
   const taskNote = notes[0];
   const meta = JSON.parse(taskNote.metadata);
@@ -5580,19 +5683,19 @@ function getTask(db, displayId) {
     claimedAt: taskMeta.claimed_at,
     dueDate: taskMeta.due_date
   });
-  return ok({ ...taskMeta, virtualStates });
+  return ok2({ ...taskMeta, virtualStates });
 }
 async function updateTaskStatus(db, config, embedder, displayId, newStatus) {
   const notes = getPmNotes(db, "task", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Task "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Task "${displayId}" not found`);
   }
   const note = notes[0];
   const meta = JSON.parse(note.metadata);
   const currentStatus = meta.status;
   const transitionResult = validateTransition(currentStatus, newStatus);
   if (!transitionResult.ok) {
-    return fail(
+    return fail2(
       "INVALID_TRANSITION",
       transitionResult.error.message,
       transitionResult.error.details
@@ -5600,7 +5703,7 @@ async function updateTaskStatus(db, config, embedder, displayId, newStatus) {
   }
   const filePath = note.filePath;
   if (!existsSync11(filePath)) {
-    return fail("NOT_FOUND", `Task file not found at "${filePath}"`);
+    return fail2("NOT_FOUND", `Task file not found at "${filePath}"`);
   }
   let content = readFileSync11(filePath, "utf-8");
   content = replaceFrontmatterField3(content, "status", newStatus);
@@ -5631,17 +5734,17 @@ async function updateTaskStatus(db, config, embedder, displayId, newStatus) {
       newlyEligible
     });
   }
-  return ok(taskMetaFromRecord(refreshedMeta));
+  return ok2(taskMetaFromRecord(refreshedMeta));
 }
 async function updateTask(db, config, embedder, displayId, updates) {
   const notes = getPmNotes(db, "task", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Task "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Task "${displayId}" not found`);
   }
   const note = notes[0];
   const filePath = note.filePath;
   if (!existsSync11(filePath)) {
-    return fail("NOT_FOUND", `Task file not found at "${filePath}"`);
+    return fail2("NOT_FOUND", `Task file not found at "${filePath}"`);
   }
   let content = readFileSync11(filePath, "utf-8");
   if (updates.mode !== void 0) {
@@ -5666,19 +5769,19 @@ async function updateTask(db, config, embedder, displayId, updates) {
   const noteId = await indexSingleFile(db, embedder, filePath, content, hash, Date.now());
   const refreshedNote = db.getNoteById(noteId);
   const refreshedMeta = JSON.parse(refreshedNote.metadata);
-  return ok(taskMetaFromRecord(refreshedMeta));
+  return ok2(taskMetaFromRecord(refreshedMeta));
 }
 async function deleteTask(db, config, displayId, force) {
   const notes = getPmNotes(db, "task", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Task "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Task "${displayId}" not found`);
   }
   const taskNote = notes[0];
   if (!force) {
     const incomingRelations = db.getRelationsTo(taskNote.id);
     const dependents = incomingRelations.filter((r) => r.type === "depends_on");
     if (dependents.length > 0) {
-      return fail(
+      return fail2(
         "HAS_DEPENDENTS",
         `Task "${displayId}" has ${dependents.length} dependent task(s). Use force to delete.`,
         { count: dependents.length }
@@ -5694,7 +5797,7 @@ async function deleteTask(db, config, displayId, force) {
   if (contentDir && existsSync11(contentDir)) {
     rmSync3(contentDir, { recursive: true, force: true });
   }
-  return ok(void 0);
+  return ok2(void 0);
 }
 
 // src/modules/pm/commands/activity.ts
@@ -5703,14 +5806,14 @@ import { existsSync as existsSync12, readFileSync as readFileSync12, unlinkSync
 import { join as join13 } from "path";
 function projectDeleteWithActivity(db, config, prefix, opts) {
   if (!opts.confirm) {
-    return fail(
+    return fail2(
       "INVALID_INPUT",
       "Deletion requires --confirm. This will delete the project and all associated notes."
     );
   }
   const projectNotes = getPmNotes(db, "project", { prefix });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${prefix}" not found.`);
+    return fail2("NOT_FOUND", `Project "${prefix}" not found.`);
   }
   const allProjectNotes = getProjectNotes(db, prefix);
   const activityNotes = getPmNotes(db, "activity", { project: prefix });
@@ -5748,7 +5851,7 @@ function projectDeleteWithActivity(db, config, prefix, opts) {
   if (existsSync12(projectDir)) {
     rmSync4(projectDir, { recursive: true, force: true });
   }
-  return ok({
+  return ok2({
     deletedCount: deletedIds.length,
     untrackedCount,
     deletedIds
@@ -6471,9 +6574,9 @@ function generateClaim() {
 }
 function validateClaimToken(expected, provided) {
   if (expected === provided) {
-    return ok(void 0);
+    return ok2(void 0);
   }
-  return fail("INVALID_CLAIM_TOKEN", "Claim token does not match", {
+  return fail2("INVALID_CLAIM_TOKEN", "Claim token does not match", {
     expected,
     provided
   });
@@ -6585,7 +6688,10 @@ function createTaskCommands() {
       if (prefixes.length === 0) {
         process.stderr.write(
           formatError(
-            pmError("INVALID_INPUT", 'No projects found. Run "brain pm onboard <name>" to create one.'),
+            pmError(
+              "INVALID_INPUT",
+              'No projects found. Run "brain pm onboard <name>" to create one.'
+            ),
             !!opts.json
           ) + "\n"
         );
@@ -6808,27 +6914,80 @@ function createTaskCommands() {
   });
   cmd.command("done").description('Mark task as done (low-level \u2014 use "brain pm complete" for full impact tracking)').argument("<id>", "Task display ID").option("--token <token>", "Claim token for verification").option("--json", "Output JSON").action(async (id, opts) => {
     await withBrain(async (svc) => {
-      const redirectMsg = checkNamespaceMismatch(id.toUpperCase(), "task");
+      const displayId = id.toUpperCase();
+      const redirectMsg = checkNamespaceMismatch(displayId, "task");
       if (redirectMsg) {
         process.stderr.write(`Error: ${redirectMsg}
 `);
         process.exitCode = 1;
         return;
       }
+      const taskResult = getTask(svc.db, displayId);
+      if (!taskResult.ok) {
+        process.stderr.write(formatError(taskResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
       if (opts.token) {
-        const taskResult = getTask(svc.db, id.toUpperCase());
-        if (taskResult.ok && taskResult.data.claim_token && taskResult.data.claim_token !== opts.token) {
+        if (taskResult.data.claim_token && taskResult.data.claim_token !== opts.token) {
           process.stderr.write(
             `Warning: Token mismatch (expected ${taskResult.data.claim_token}, got ${opts.token})
 `
           );
         }
       }
+      const currentStatus = taskResult.data.status;
+      if (currentStatus === "pending") {
+        process.stderr.write(`Auto-claiming ${displayId}...
+`);
+        const claim = generateClaim();
+        const claimResult = await updateTaskMetadataFields(
+          svc.db,
+          svc.config,
+          svc.embedder,
+          displayId,
+          { status: "claimed", claim_token: claim.token, claimed_at: claim.claimedAt }
+        );
+        if (!claimResult.ok) {
+          process.stderr.write(formatError(claimResult.error, !!opts.json) + "\n");
+          process.exitCode = 1;
+          return;
+        }
+        process.stderr.write(`Auto-starting ${displayId}...
+`);
+        const startResult = await updateTaskStatus(
+          svc.db,
+          svc.config,
+          svc.embedder,
+          displayId,
+          "in-progress"
+        );
+        if (!startResult.ok) {
+          process.stderr.write(formatError(startResult.error, !!opts.json) + "\n");
+          process.exitCode = 1;
+          return;
+        }
+      } else if (currentStatus === "claimed") {
+        process.stderr.write(`Auto-starting ${displayId}...
+`);
+        const startResult = await updateTaskStatus(
+          svc.db,
+          svc.config,
+          svc.embedder,
+          displayId,
+          "in-progress"
+        );
+        if (!startResult.ok) {
+          process.stderr.write(formatError(startResult.error, !!opts.json) + "\n");
+          process.exitCode = 1;
+          return;
+        }
+      }
       const result = await updateTaskStatus(
         svc.db,
         svc.config,
         svc.embedder,
-        id.toUpperCase(),
+        displayId,
         "done"
       );
       if (!result.ok) {
@@ -7089,12 +7248,12 @@ ${field}: ${quoted}` + rest;
 async function updateTaskMetadataFields(db, config, embedder, displayId, fields) {
   const notes = getPmNotes(db, "task", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Task "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Task "${displayId}" not found`);
   }
   const note = notes[0];
   const filePath = note.filePath;
   if (!existsSync14(filePath)) {
-    return fail("NOT_FOUND", `Task file not found at "${filePath}"`);
+    return fail2("NOT_FOUND", `Task file not found at "${filePath}"`);
   }
   let content = readFileSync14(filePath, "utf-8");
   for (const [key, value] of Object.entries(fields)) {
@@ -7199,18 +7358,18 @@ ${field}: ${quoted}` + rest;
 async function createDecision(db, config, embedder, input) {
   const projectNotes = getPmNotes(db, "project", { prefix: input.project });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${input.project}" not found`);
+    return fail2("NOT_FOUND", `Project "${input.project}" not found`);
   }
   const sourceResolved = resolveDisplayId(db, input.sourceTask);
   if (!sourceResolved.ok) {
-    return fail("NOT_FOUND", `Source task "${input.sourceTask}" not found`);
+    return fail2("NOT_FOUND", `Source task "${input.sourceTask}" not found`);
   }
   const resolvedImpacts = [];
   if (input.impacts && input.impacts.length > 0) {
     for (const impactId of input.impacts) {
       const resolved = resolveDisplayId(db, impactId);
       if (!resolved.ok) {
-        return fail("NOT_FOUND", `Impact target "${impactId}" not found`);
+        return fail2("NOT_FOUND", `Impact target "${impactId}" not found`);
       }
       resolvedImpacts.push({ displayId: impactId, noteId: resolved.data });
     }
@@ -7241,7 +7400,7 @@ async function createDecision(db, config, embedder, input) {
     source_task: input.sourceTask,
     impacts: input.impacts
   };
-  return ok(metadata);
+  return ok2(metadata);
 }
 function listDecisions(db, prefix, filters) {
   const filterObj = { project: prefix };
@@ -7252,12 +7411,12 @@ function listDecisions(db, prefix, filters) {
     const meta = JSON.parse(note.metadata);
     return decisionMetaFromRecord(meta);
   });
-  return ok(decisions);
+  return ok2(decisions);
 }
 function getDecision(db, displayId) {
   const notes = getPmNotes(db, "decision", { display_id: displayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `Decision "${displayId}" not found`);
+    return fail2("NOT_FOUND", `Decision "${displayId}" not found`);
   }
   const note = notes[0];
   const meta = JSON.parse(note.metadata);
@@ -7272,17 +7431,17 @@ function getDecision(db, displayId) {
       content = headingEnd !== -1 ? body.slice(headingEnd + 1).trim() : "";
     }
   }
-  return ok({ ...decisionMeta, content });
+  return ok2({ ...decisionMeta, content });
 }
 async function supersedeDecision(db, config, embedder, oldDisplayId, newInput) {
   const oldNotes = getPmNotes(db, "decision", { display_id: oldDisplayId });
   if (oldNotes.length === 0) {
-    return fail("NOT_FOUND", `Decision "${oldDisplayId}" not found`);
+    return fail2("NOT_FOUND", `Decision "${oldDisplayId}" not found`);
   }
   const oldNote = oldNotes[0];
   const oldFilePath = oldNote.filePath;
   if (!existsSync15(oldFilePath)) {
-    return fail("NOT_FOUND", `Decision file not found at "${oldFilePath}"`);
+    return fail2("NOT_FOUND", `Decision file not found at "${oldFilePath}"`);
   }
   let oldContent = readFileSync15(oldFilePath, "utf-8");
   oldContent = replaceFrontmatterField5(oldContent, "status", "superseded");
@@ -7313,7 +7472,7 @@ async function supersedeDecision(db, config, embedder, oldDisplayId, newInput) {
     ];
     db.upsertRelations(newResolved.data, supersedesRelation);
   }
-  return ok({ old: oldDecision, new: newResult.data });
+  return ok2({ old: oldDecision, new: newResult.data });
 }
 
 // src/modules/pm/data/prompt-ops.ts
@@ -7421,11 +7580,11 @@ async function supersedeCurrentPrompt(db, embedder, taskDisplayId, project) {
 async function writePrompt(db, config, embedder, input) {
   const projectNotes = getPmNotes(db, "project", { prefix: input.project });
   if (projectNotes.length === 0) {
-    return fail("NOT_FOUND", `Project "${input.project}" not found`);
+    return fail2("NOT_FOUND", `Project "${input.project}" not found`);
   }
   const taskResolved = resolveDisplayId(db, input.task);
   if (!taskResolved.ok) {
-    return fail("NOT_FOUND", `Task "${input.task}" not found`);
+    return fail2("NOT_FOUND", `Task "${input.task}" not found`);
   }
   await supersedeCurrentPrompt(db, embedder, input.task, input.project);
   const version = currentVersionForTask(db, input.task, input.project) + 1;
@@ -7448,12 +7607,12 @@ async function writePrompt(db, config, embedder, input) {
     prompt_status: status,
     version
   };
-  return ok(metadata);
+  return ok2(metadata);
 }
 function getPrompt(db, taskDisplayId, version) {
   const notes = getPmNotes(db, "prompt", { task: taskDisplayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `No prompts found for task "${taskDisplayId}"`);
+    return fail2("NOT_FOUND", `No prompts found for task "${taskDisplayId}"`);
   }
   let target = notes[0];
   let targetMeta = JSON.parse(target.metadata);
@@ -7463,7 +7622,7 @@ function getPrompt(db, taskDisplayId, version) {
       return m.version === version;
     });
     if (!match) {
-      return fail("NOT_FOUND", `Prompt version ${version} not found for task "${taskDisplayId}"`);
+      return fail2("NOT_FOUND", `Prompt version ${version} not found for task "${taskDisplayId}"`);
     }
     target = match;
     targetMeta = JSON.parse(match.metadata);
@@ -7488,7 +7647,7 @@ function getPrompt(db, taskDisplayId, version) {
       content = headingEnd !== -1 ? body.slice(headingEnd + 1).trim() : "";
     }
   }
-  return ok({ ...promptMetaFromRecord(targetMeta), content });
+  return ok2({ ...promptMetaFromRecord(targetMeta), content });
 }
 function listPrompts(db, prefix, filters) {
   const filterObj = { project: prefix };
@@ -7499,19 +7658,19 @@ function listPrompts(db, prefix, filters) {
     const meta = JSON.parse(note.metadata);
     return promptMetaFromRecord(meta);
   });
-  return ok(prompts);
+  return ok2(prompts);
 }
 function getPromptHistory(db, taskDisplayId) {
   const notes = getPmNotes(db, "prompt", { task: taskDisplayId });
   if (notes.length === 0) {
-    return fail("NOT_FOUND", `No prompts found for task "${taskDisplayId}"`);
+    return fail2("NOT_FOUND", `No prompts found for task "${taskDisplayId}"`);
   }
   const prompts = notes.map((note) => {
     const meta = JSON.parse(note.metadata);
     return promptMetaFromRecord(meta);
   });
   prompts.sort((a, b) => (a.version ?? 0) - (b.version ?? 0));
-  return ok(prompts);
+  return ok2(prompts);
 }
 function getIndexedAt(db, filePath) {
   const file = db.getFile(filePath);
@@ -7520,7 +7679,7 @@ function getIndexedAt(db, filePath) {
 function detectStalePrompts(db, prefix) {
   const currentPrompts = getPmNotes(db, "prompt", { project: prefix, prompt_status: "current" });
   if (currentPrompts.length === 0) {
-    return ok([]);
+    return ok2([]);
   }
   const decisionNotes = getPmNotes(db, "decision", { project: prefix });
   const stale = [];
@@ -7533,13 +7692,13 @@ function detectStalePrompts(db, prefix) {
       const impacts = decMeta.impacts;
       if (!impacts || !impacts.includes(taskDisplayId)) continue;
       const decIndexedAt = getIndexedAt(db, decNote.filePath);
-      if (decIndexedAt > promptIndexedAt) {
+      if (decIndexedAt >= promptIndexedAt) {
         stale.push(promptMetaFromRecord(promptMeta));
         break;
       }
     }
   }
-  return ok(stale);
+  return ok2(stale);
 }
 
 // src/modules/pm/engine/consistency.ts
@@ -7618,7 +7777,10 @@ function findBlockedWithoutCause(db, prefix) {
       });
       continue;
     }
-    const allDone = deps.every((d) => statusMap.get(d) === "done");
+    const allDone = deps.every((d) => {
+      const s = statusMap.get(d);
+      return s === "done" || s === "pruned";
+    });
     if (allDone) {
       results.push({
         id: meta.display_id,
@@ -7643,17 +7805,18 @@ function findCancelledDependencies(db, prefix) {
   for (const task of tasks) {
     const meta = JSON.parse(task.metadata);
     const status = meta.status;
-    if (status === "done" || status === "cancelled") continue;
+    if (status === "done" || status === "cancelled" || status === "pruned") continue;
     const deps = getDependencyDisplayIds(db, task.id);
     if (deps.length === 0) continue;
     for (const dep of deps) {
-      if (statusMap.get(dep) === "cancelled") {
+      const depStatus = statusMap.get(dep);
+      if (depStatus === "cancelled" || depStatus === "pruned") {
         results.push({
           task: meta.display_id,
           taskTitle: task.title ?? meta.display_id,
           dependsOn: dep,
-          dependsOnStatus: "cancelled",
-          reason: `Depends on cancelled task ${dep}`
+          dependsOnStatus: depStatus,
+          reason: `Depends on ${depStatus} task ${dep}`
         });
       }
     }
@@ -7925,13 +8088,13 @@ function resolveWorkstreamByName(db, prefix, input) {
   if (idResult.ok) return idResult;
   const wsResult = listWorkstreams(db, prefix);
   if (!wsResult.ok)
-    return fail("NOT_FOUND", `Could not list workstreams: ${wsResult.error.message}`);
+    return fail2("NOT_FOUND", `Could not list workstreams: ${wsResult.error.message}`);
   const lower = input.toLowerCase();
   for (const ws of wsResult.data) {
     const name = ws.title?.replace(/^Workstream\s+/i, "") ?? "";
-    if (name.toLowerCase().includes(lower)) return ok(ws.number);
+    if (name.toLowerCase().includes(lower)) return ok2(ws.number);
   }
-  return fail(
+  return fail2(
     "INVALID_INPUT",
     `No workstream matching "${input}". Use a number, display ID, or name. Run "brain pm workstream list" to see options.`
   );
@@ -7972,7 +8135,11 @@ function createOrchestrationCommands() {
         if (!singlePrefix) {
           process.stderr.write(
             formatError(
-              { error: true, code: "INVALID_INPUT", message: "--workstream requires --project when multiple projects exist" },
+              {
+                error: true,
+                code: "INVALID_INPUT",
+                message: "--workstream requires --project when multiple projects exist"
+              },
               !!opts.json
             ) + "\n"
           );
@@ -9195,7 +9362,7 @@ function buildCaptureMarkdown(captureId, input) {
 }
 async function createCapture(db, config, embedder, input) {
   if (!input.content || input.content.trim().length === 0) {
-    return fail("INVALID_INPUT", "Capture content cannot be empty");
+    return fail2("INVALID_INPUT", "Capture content cannot be empty");
   }
   const captureId = `capture-${randomUUID6().slice(0, 12)}`;
   const filePath = captureFilePath(config, captureId);
@@ -9215,7 +9382,7 @@ async function createCapture(db, config, embedder, input) {
     processed: false,
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  return ok(record);
+  return ok2(record);
 }
 function listCaptures(db, filters) {
   const filterObj = {};
@@ -9236,19 +9403,19 @@ function listCaptures(db, filters) {
       createdAt: note.createdAt ?? ""
     };
   });
-  return ok(captures);
+  return ok2(captures);
 }
 async function processCapture(db, config, embedder, captureNoteId, asTask) {
   const note = db.getNoteById(captureNoteId);
   if (!note) {
-    return fail("NOT_FOUND", `Capture "${captureNoteId}" not found`);
+    return fail2("NOT_FOUND", `Capture "${captureNoteId}" not found`);
   }
   if (note.type !== "capture" || note.module !== "pm") {
-    return fail("INVALID_INPUT", `Note "${captureNoteId}" is not a PM capture`);
+    return fail2("INVALID_INPUT", `Note "${captureNoteId}" is not a PM capture`);
   }
   const meta = JSON.parse(note.metadata);
   if (meta.processed === true || meta.processed === "true") {
-    return fail("INVALID_INPUT", `Capture "${captureNoteId}" has already been processed`);
+    return fail2("INVALID_INPUT", `Capture "${captureNoteId}" has already been processed`);
   }
   const taskResult = await createTask(db, config, embedder, asTask);
   if (!taskResult.ok) {
@@ -9257,7 +9424,7 @@ async function processCapture(db, config, embedder, captureNoteId, asTask) {
   const updatedMeta = { ...meta, processed: true };
   const updatedNote = { ...note, metadata: JSON.stringify(updatedMeta) };
   db.upsertNote(updatedNote);
-  return ok(taskResult.data);
+  return ok2(taskResult.data);
 }
 
 // src/modules/pm/commands/capture.ts
@@ -9590,32 +9757,32 @@ import { readFileSync as readFileSync17 } from "fs";
 import { Command as Command36 } from "@commander-js/extra-typings";
 function validateImportDef(data) {
   if (!data || typeof data !== "object") {
-    return fail("INVALID_INPUT", "Import data must be a JSON object");
+    return fail2("INVALID_INPUT", "Import data must be a JSON object");
   }
   const obj = data;
   if (typeof obj.name !== "string" || obj.name.trim().length === 0) {
-    return fail("INVALID_INPUT", 'Import data must have a non-empty "name" field');
+    return fail2("INVALID_INPUT", 'Import data must have a non-empty "name" field');
   }
   if (typeof obj.prefix !== "string" || obj.prefix.trim().length === 0) {
-    return fail("INVALID_INPUT", 'Import data must have a non-empty "prefix" field');
+    return fail2("INVALID_INPUT", 'Import data must have a non-empty "prefix" field');
   }
   if (obj.workstreams !== void 0 && !Array.isArray(obj.workstreams)) {
-    return fail("INVALID_INPUT", '"workstreams" must be an array');
+    return fail2("INVALID_INPUT", '"workstreams" must be an array');
   }
   const workstreams = obj.workstreams ?? [];
   for (let i = 0; i < workstreams.length; i++) {
     const ws = workstreams[i];
     if (typeof ws.name !== "string" || ws.name.trim().length === 0) {
-      return fail("INVALID_INPUT", `Workstream at index ${i} must have a non-empty "name" field`);
+      return fail2("INVALID_INPUT", `Workstream at index ${i} must have a non-empty "name" field`);
     }
     if (ws.tasks !== void 0 && !Array.isArray(ws.tasks)) {
-      return fail("INVALID_INPUT", `Workstream "${ws.name}" tasks must be an array`);
+      return fail2("INVALID_INPUT", `Workstream "${ws.name}" tasks must be an array`);
     }
     const tasks = ws.tasks ?? [];
     for (let j = 0; j < tasks.length; j++) {
       const t = tasks[j];
       if (typeof t.name !== "string" || t.name.trim().length === 0) {
-        return fail(
+        return fail2(
           "INVALID_INPUT",
           `Task at index ${j} in workstream "${ws.name}" must have a non-empty "name"`
         );
@@ -9737,7 +9904,7 @@ function createImportCommand() {
         rawData = JSON.parse(content);
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        const error = fail(
+        const error = fail2(
           "INVALID_INPUT",
           `Failed to read/parse "${opts.fromJson}": ${message}`
         );
@@ -10195,10 +10362,8 @@ function createOrchestrateCommands() {
             `Tasks: ${done.length} done, ${inProgress.length} in-progress, ${pending.length} pending, ${blocked.length} blocked (${allTasks.length} total)
 `
           );
-          process.stdout.write(
-            `Worktrees: ${worktreeInfo.used}/${worktreeInfo.max} in use
-`
-          );
+          process.stdout.write(`Worktrees: ${worktreeInfo.used}/${worktreeInfo.max} in use
+`);
           if (worktreeInfo.allocations.length > 0) {
             for (const a of worktreeInfo.allocations) {
               process.stdout.write(`  ${a.taskId}: ${a.path}
@@ -10212,18 +10377,8 @@ function createOrchestrateCommands() {
   return cmd;
 }
 
-// src/modules/pm/commands/install-hooks.ts
-import { Command as Command38 } from "@commander-js/extra-typings";
-var DEPRECATION_MESSAGE = 'DEPRECATED: "brain pm install-hooks" has been replaced by "ao hook install".\nInstall ao-cli and run: ao hook install\nTo remove existing hooks: ao hook remove\n';
-function createInstallHooksCommand() {
-  return new Command38("install-hooks").description('[DEPRECATED] Use "ao hook install" instead').option("--remove", "Remove installed hooks and skill").option("--dry-run", "Preview changes without writing files").action(() => {
-    process.stderr.write(DEPRECATION_MESSAGE);
-    process.exitCode = 1;
-  });
-}
-
 // src/modules/pm/commands/setup.ts
-import { Command as Command39 } from "@commander-js/extra-typings";
+import { Command as Command38 } from "@commander-js/extra-typings";
 async function validateDatabase() {
   try {
     await withBrain(() => {
@@ -10320,7 +10475,7 @@ function formatText(dbCheck, demo) {
   return lines2.join("\n");
 }
 function createSetupCommand() {
-  return new Command39("setup").description('[DEPRECATED] Use "ao hook install" for hooks. Use --demo for demo project only.').option("--demo", "Create a demo project").option("--json", "Output JSON status").option("--dry-run", "Show what would be done").action(async (opts) => {
+  return new Command38("setup").description('[DEPRECATED] Use "ao hook install" for hooks. Use --demo for demo project only.').option("--demo", "Create a demo project").option("--json", "Output JSON status").option("--dry-run", "Show what would be done").action(async (opts) => {
     if (opts.dryRun) {
       const items = [];
       if (opts.demo) items.push("Demo project with 2 workstreams and 4 tasks");
@@ -10343,7 +10498,9 @@ function createSetupCommand() {
       process.stdout.write(
         JSON.stringify(
           {
-            checks: [{ label: "Database accessible", passed: dbCheck.passed, error: dbCheck.error }],
+            checks: [
+              { label: "Database accessible", passed: dbCheck.passed, error: dbCheck.error }
+            ],
             demo: { success: demo.success, error: demo.error },
             success: !hasFailure
           },
@@ -10358,7 +10515,7 @@ function createSetupCommand() {
 }
 
 // src/modules/pm/commands/check.ts
-import { Command as Command40 } from "@commander-js/extra-typings";
+import { Command as Command39 } from "@commander-js/extra-typings";
 function resolvePrefix(explicit, active) {
   if (explicit) return explicit.toUpperCase();
   return active ?? void 0;
@@ -10444,7 +10601,7 @@ function formatCheckReport(report) {
   }
 }
 function createCheckCommand() {
-  return new Command40("check").description("Run consistency checks on a PM project").option("--project <prefix>", "Project prefix (uses active project if omitted)").option("--deep", "Include semantic analysis and source document clustering").option("--deps", "Check dependency graph for cycles").option("--json", "Output JSON").action(async (opts) => {
+  return new Command39("check").description("Run consistency checks on a PM project").option("--project <prefix>", "Project prefix (uses active project if omitted)").option("--deep", "Include semantic analysis and source document clustering").option("--deps", "Check dependency graph for cycles").option("--json", "Output JSON").action(async (opts) => {
     await withBrain(async (svc) => {
       const prefix = resolvePrefix(opts.project, getActiveProject(svc.db));
       if (!prefix) {
@@ -10487,7 +10644,7 @@ function createCheckCommand() {
 }
 
 // src/modules/pm/commands/onboard.ts
-import { Command as Command41 } from "@commander-js/extra-typings";
+import { Command as Command40 } from "@commander-js/extra-typings";
 import { createHash as createHash13 } from "crypto";
 import { readFileSync as readFileSync19, writeFileSync as writeFileSync16, mkdirSync as mkdirSync16, existsSync as existsSync21, unlinkSync as unlinkSync6 } from "fs";
 import { join as join20, dirname as dirname11, basename as basename6 } from "path";
@@ -10831,7 +10988,7 @@ async function runOnboard(db, config, embedder, opts) {
   const now = () => (/* @__PURE__ */ new Date()).toISOString();
   const existing = getPmNotes(db, "project", { prefix: opts.prefix });
   if (existing.length > 0 && !opts.reset) {
-    return fail(
+    return fail2(
       "PROJECT_EXISTS",
       `Project "${opts.prefix}" already exists. Use --reset to re-onboard.`
     );
@@ -10841,7 +10998,7 @@ async function runOnboard(db, config, embedder, opts) {
     const projMeta = JSON.parse(projNote.metadata ?? "{}");
     const projTitle = (projMeta.title ?? "").replace(/^Project\s+/i, "");
     if (projTitle.toLowerCase() === opts.projectName.toLowerCase() && projMeta.prefix !== opts.prefix) {
-      return fail(
+      return fail2(
         "PROJECT_EXISTS",
         `A project named "${opts.projectName}" already exists as ${projMeta.prefix}. Use --prefix ${projMeta.prefix} --reset to re-onboard, or brain pm use ${projMeta.prefix}.`
       );
@@ -11038,7 +11195,7 @@ async function runOnboard(db, config, embedder, opts) {
   writeFileSync16(manifestPath, manifestMd, "utf-8");
   const manifestHash = createHash13("sha256").update(manifestMd).digest("hex");
   await indexSingleFile(db, embedder, manifestPath, manifestMd, manifestHash, Date.now());
-  return ok(manifest);
+  return ok2(manifest);
 }
 function syncProjectHierarchyEdges(db, prefix) {
   const projectNotes = getPmNotes(db, "project", { prefix });
@@ -11110,7 +11267,7 @@ function buildManifestNote(manifest, slug, projectName) {
   return lines2.join("\n");
 }
 function createOnboardCommand() {
-  const cmd = new Command41("onboard");
+  const cmd = new Command40("onboard");
   cmd.description("Set up a PM project from a codebase").argument("<project-name>", "Project name").option(
     "--prefix <prefix>",
     "Project prefix (2-5 uppercase chars, derived from name if omitted)"
@@ -11158,7 +11315,7 @@ function createOnboardCommand() {
 }
 
 // src/modules/pm/commands/relate.ts
-import { Command as Command42 } from "@commander-js/extra-typings";
+import { Command as Command41 } from "@commander-js/extra-typings";
 async function relateAction(db, source, target, opts) {
   const relType = opts.type ?? "related";
   const sourceNote = db.getNoteById(source);
@@ -11188,7 +11345,7 @@ async function relateAction(db, source, target, opts) {
   return { ok: true, message: `Created ${relType} relation: ${source} -> ${target}` };
 }
 function createRelateCommand() {
-  return new Command42("relate").description("Create or remove a relation between two notes").argument("<source>", "Source note ID or display ID").argument("<target>", "Target note ID or display ID").option("--type <type>", "Relation type (related, depends_on, derived-from, parent)", "related").option("--remove", "Remove the relation instead of creating it").option("--json", "Output JSON").action(async (source, target, opts) => {
+  return new Command41("relate").description("Create or remove a relation between two notes").argument("<source>", "Source note ID or display ID").argument("<target>", "Target note ID or display ID").option("--type <type>", "Relation type (related, depends_on, derived-from, parent)", "related").option("--remove", "Remove the relation instead of creating it").option("--json", "Output JSON").action(async (source, target, opts) => {
     await withDb(async ({ db }) => {
       const result = await relateAction(db, source, target, opts);
       if (opts.json) {
@@ -11204,7 +11361,7 @@ function createRelateCommand() {
 }
 
 // src/modules/pm/commands/review.ts
-import { Command as Command43 } from "@commander-js/extra-typings";
+import { Command as Command42 } from "@commander-js/extra-typings";
 
 // src/modules/pm/data/review-ops.ts
 function extractPrNumber(url) {
@@ -11222,11 +11379,28 @@ function findReviewWorkstream(db, project) {
   }
   return { found: false };
 }
+var AUTO_COMPLETE_TRANSITIONS = {
+  pending: ["claimed", "in-progress", "done"],
+  claimed: ["in-progress", "done"],
+  "in-progress": ["done"]
+};
+async function autoCompleteSourceTask(db, config, embedder, displayId, currentStatus) {
+  const steps = AUTO_COMPLETE_TRANSITIONS[currentStatus];
+  if (!steps) return false;
+  for (const targetStatus of steps) {
+    const result = await updateTaskStatus(db, config, embedder, displayId, targetStatus);
+    if (!result.ok) return false;
+  }
+  return true;
+}
 async function createReviewTask(db, config, embedder, input) {
+  if (input.risk !== void 0 && (!Number.isInteger(input.risk) || input.risk < 1 || input.risk > 5)) {
+    return fail2("INVALID_INPUT", `Risk must be an integer between 1 and 5, got ${input.risk}`);
+  }
   const sourceDisplayId = input.sourceTaskId.toUpperCase();
   const sourceNotes = getPmNotes(db, "task", { display_id: sourceDisplayId });
   if (sourceNotes.length === 0) {
-    return fail("NOT_FOUND", `Source task "${sourceDisplayId}" not found`);
+    return fail2("NOT_FOUND", `Source task "${sourceDisplayId}" not found`);
   }
   const sourceMeta = JSON.parse(sourceNotes[0].metadata);
   const project = sourceMeta.project;
@@ -11244,7 +11418,7 @@ async function createReviewTask(db, config, embedder, input) {
       description: "Pull request review tasks requiring human approval"
     });
     if (!wsResult.ok) {
-      return fail(wsResult.error.code, wsResult.error.message, wsResult.error.details);
+      return fail2(wsResult.error.code, wsResult.error.message, wsResult.error.details);
     }
     reviewWsNumber = wsResult.data.number;
   }
@@ -11259,6 +11433,9 @@ async function createReviewTask(db, config, embedder, input) {
   if (input.agentId) {
     descriptionLines.push(`- **Agent:** ${input.agentId}`);
   }
+  if (input.risk !== void 0) {
+    descriptionLines.push(`- **Risk:** ${input.risk}/5`);
+  }
   descriptionLines.push("", "Review and merge the pull request to unblock downstream work.");
   const taskResult = await createTask(db, config, embedder, {
     project,
@@ -11271,7 +11448,7 @@ async function createReviewTask(db, config, embedder, input) {
     description: descriptionLines.join("\n")
   });
   if (!taskResult.ok) {
-    return fail(taskResult.error.code, taskResult.error.message, taskResult.error.details);
+    return fail2(taskResult.error.code, taskResult.error.message, taskResult.error.details);
   }
   const reviewDisplayId = taskResult.data.display_id;
   const rewiredDeps = [];
@@ -11312,32 +11489,65 @@ async function createReviewTask(db, config, embedder, input) {
     project
   });
   const captureNoteId = captureResult.ok ? captureResult.data.noteId : "";
-  return ok({
+  let sourceAutoCompleted = false;
+  if (input.autoComplete !== false) {
+    const sourceStatus = sourceMeta.status ?? "pending";
+    if (sourceStatus !== "done") {
+      try {
+        sourceAutoCompleted = await autoCompleteSourceTask(
+          db,
+          config,
+          embedder,
+          sourceDisplayId,
+          sourceStatus
+        );
+      } catch {
+      }
+    }
+  }
+  let riskAdvisory;
+  if (input.risk !== void 0) {
+    riskAdvisory = input.risk >= 4 ? `Advisory: risk ${input.risk} \u2014 human review recommended` : `Advisory: risk ${input.risk} \u2014 agent review may be sufficient`;
+  }
+  return ok2({
     reviewTaskId: reviewDisplayId,
     reviewTaskMeta: taskResult.data,
     rewiredDeps,
-    captureNoteId
+    captureNoteId,
+    riskAdvisory,
+    sourceAutoCompleted
   });
 }
 
 // src/modules/pm/commands/review.ts
 function createReviewCommands() {
-  const cmd = new Command43("review").description("PR review lifecycle commands");
-  cmd.command("create").description("Create a review task for a PR").argument("<task-id>", "Source task display ID (e.g. SDK-02.01)").requiredOption("--pr <url>", "Pull request URL").requiredOption("--branch <branch>", "Branch name").option("--agent <id>", "Agent ID that created the PR").option("--no-rewire", "Skip dependency rewiring").option("--json", "Output JSON").action(async (taskId, opts) => {
+  const cmd = new Command42("review").description("PR review lifecycle commands");
+  cmd.command("create").description("Create a review task for a PR").argument("<task-id>", "Source task display ID (e.g. SDK-02.01)").requiredOption("--pr <url>", "Pull request URL").requiredOption("--branch <branch>", "Branch name").option("--agent <id>", "Agent ID that created the PR").option("--no-rewire", "Skip dependency rewiring").option("--no-auto-complete", "Skip auto-completing the source task").option("--risk <number>", "Risk score (1-5) for review routing advisory").option("--json", "Output JSON").action(async (taskId, opts) => {
     await withBrain(async (svc) => {
+      let risk;
+      if (opts.risk !== void 0) {
+        risk = Number(opts.risk);
+        if (!Number.isInteger(risk) || risk < 1 || risk > 5) {
+          process.stderr.write("Error: --risk must be an integer between 1 and 5\n");
+          process.exitCode = 1;
+          return;
+        }
+      }
       const result = await createReviewTask(svc.db, svc.config, svc.embedder, {
         sourceTaskId: taskId,
         prUrl: opts.pr,
         branch: opts.branch,
         agentId: opts.agent,
-        rewireDeps: opts.rewire
+        rewireDeps: opts.rewire,
+        autoComplete: opts.autoComplete,
+        risk
       });
       if (!result.ok) {
         process.stderr.write(formatError(result.error, !!opts.json) + "\n");
         process.exitCode = 1;
         return;
       }
-      const { reviewTaskId, reviewTaskMeta, rewiredDeps } = result.data;
+      const { reviewTaskId, reviewTaskMeta, rewiredDeps, sourceAutoCompleted } = result.data;
       if (opts.json) {
         process.stdout.write(
           JSON.stringify(
@@ -11345,7 +11555,9 @@ function createReviewCommands() {
               reviewTaskId,
               reviewTask: reviewTaskMeta,
               rewiredDeps,
-              captureNoteId: result.data.captureNoteId
+              captureNoteId: result.data.captureNoteId,
+              riskAdvisory: result.data.riskAdvisory,
+              sourceAutoCompleted
             },
             null,
             2
@@ -11358,8 +11570,20 @@ function createReviewCommands() {
           `  ${reviewTaskMeta.title} [${reviewTaskMeta.priority}] (${reviewTaskMeta.mode})
 `
         );
+        if (sourceAutoCompleted) {
+          process.stdout.write(`  Auto-completed source task ${taskId.toUpperCase()}
+`);
+        } else if (!opts.autoComplete) {
+        } else {
+          process.stdout.write(`  Source task ${taskId.toUpperCase()} already done
+`);
+        }
         if (rewiredDeps.length > 0) {
           process.stdout.write(`  Rewired deps: ${rewiredDeps.join(", ")}
+`);
+        }
+        if (result.data.riskAdvisory) {
+          process.stdout.write(`  ${result.data.riskAdvisory}
 `);
         }
       }
@@ -11443,7 +11667,6 @@ var PmContentHandler = class {
   setConfig(config) {
     this.config = config;
   }
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   canHandle(noteType, _content) {
     return noteType === "task";
   }
@@ -11452,11 +11675,7 @@ var PmContentHandler = class {
     if (!this.config) {
       throw new Error("PmContentHandler requires config \u2014 call setConfig() before materialize()");
     }
-    const { prefix, workstream } = await ensureProjectAndWorkstream(
-      db,
-      this.config,
-      embedder
-    );
+    const { prefix, workstream } = await ensureProjectAndWorkstream(db, this.config, embedder);
     const noteIds = [];
     for (const item of items) {
       const name = item.fields.name || item.title || "Imported task";
@@ -11564,7 +11783,7 @@ var pmModule = {
           number: { type: "number", description: "Task number within workstream" },
           status: {
             type: "string",
-            enum: ["pending", "claimed", "in-progress", "done", "blocked", "cancelled"],
+            enum: ["pending", "claimed", "in-progress", "done", "blocked", "cancelled", "pruned"],
             description: "Task status"
           },
           mode: {
@@ -11759,7 +11978,6 @@ var pmModule = {
     pmCmd.addCommand(createAuditCommands());
     pmCmd.addCommand(createImportCommand());
     pmCmd.addCommand(createOrchestrateCommands());
-    pmCmd.addCommand(createInstallHooksCommand());
     pmCmd.addCommand(createSetupCommand());
     pmCmd.addCommand(createCheckCommand());
     pmCmd.addCommand(createOnboardCommand());
@@ -11769,10 +11987,10 @@ var pmModule = {
     pmCmd.on("command:*", async (operands) => {
       const unknown = operands[0];
       if (!unknown) return;
-      const { resolveUnknownCommand } = await import("./command-resolution-MO7LSFOT.js");
+      const { resolveUnknownCommand } = await import("./command-resolution-EJ6LTC2Z.js");
       let resolution;
       try {
-        const { withBrain: withBrain2 } = await import("./brain-service-4ETWBOIO.js");
+        const { withBrain: withBrain2 } = await import("./brain-service-TYFNTBT6.js");
         resolution = await withBrain2(async (svc) => {
           return resolveUnknownCommand(unknown, svc.db, svc.embedder);
         });
@@ -11783,7 +12001,7 @@ var pmModule = {
 `);
       process.exitCode = 1;
     });
-    const showCmd = new Command44("show").description("Show details for any PM entity (task, workstream, or project)").argument("<id>", "Display ID (e.g., VOLT, VOLT-01, VOLT-01.03)").option("--json", "Output JSON").option("--format <format>", "Output format").action(async (id, opts) => {
+    const showCmd = new Command43("show").description("Show details for any PM entity (task, workstream, or project)").argument("<id>", "Display ID (e.g., VOLT, VOLT-01, VOLT-01.03)").option("--json", "Output JSON").option("--format <format>", "Output format").action(async (id, opts) => {
       if (opts.format === "json") opts.json = true;
       const entityType = detectEntityType2(id);
       const args = ["node", "brain-pm", entityType, "show", id];
@@ -11791,7 +12009,7 @@ var pmModule = {
       await pmCmd.parseAsync(args, { from: "node" });
     });
     pmCmd.addCommand(showCmd);
-    const claimCmd = new Command44("claim").description("Claim a task").argument("<id>", "Task display ID (e.g., VOLT-01.03)").option("--start", "Start working immediately after claiming").option("--json", "Output JSON").option("--format <format>", "Output format").action(async (id, opts) => {
+    const claimCmd = new Command43("claim").description("Claim a task").argument("<id>", "Task display ID (e.g., VOLT-01.03)").option("--start", "Start working immediately after claiming").option("--json", "Output JSON").option("--format <format>", "Output format").action(async (id, opts) => {
       if (opts.format === "json") opts.json = true;
       const args = ["node", "brain-pm", "task", "claim", id];
       if (opts.start) args.push("--start");
@@ -11813,7 +12031,7 @@ var pmModule = {
       "release",
       "complete"
     ]);
-    const tasksAlias = new Command44("tasks").description('Task management (alias for "task")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
+    const tasksAlias = new Command43("tasks").description('Task management (alias for "task")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
       const idx = process.argv.indexOf("tasks");
       const tail = process.argv.slice(idx + 1);
       const hasSubcommand = tail.length > 0 && taskSubcommands.has(tail[0]);
@@ -11835,7 +12053,7 @@ var pmModule = {
     });
     pmCmd.addCommand(tasksAlias);
     const wsSubcommands = /* @__PURE__ */ new Set(["list", "show", "add"]);
-    const workstreamsAlias = new Command44("workstreams").description('Workstream management (alias for "workstream")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
+    const workstreamsAlias = new Command43("workstreams").description('Workstream management (alias for "workstream")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
       const idx = process.argv.indexOf("workstreams");
       const tail = process.argv.slice(idx + 1);
       const hasSubcommand = tail.length > 0 && wsSubcommands.has(tail[0]);
@@ -11846,7 +12064,7 @@ var pmModule = {
     });
     pmCmd.addCommand(workstreamsAlias);
     const projectSubcommands = /* @__PURE__ */ new Set(["list", "show", "add"]);
-    const projectsAlias = new Command44("projects").description('Project management (alias for "project")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
+    const projectsAlias = new Command43("projects").description('Project management (alias for "project")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
       const idx = process.argv.indexOf("projects");
       const tail = process.argv.slice(idx + 1);
       const hasSubcommand = tail.length > 0 && projectSubcommands.has(tail[0]);
@@ -11856,7 +12074,7 @@ var pmModule = {
       });
     });
     pmCmd.addCommand(projectsAlias);
-    const lsAlias = new Command44("ls").description('List projects (alias for "list")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
+    const lsAlias = new Command43("ls").description('List projects (alias for "list")').helpOption(false).allowUnknownOption().allowExcessArguments(true).action(async () => {
       const idx = process.argv.indexOf("ls");
       const tail = process.argv.slice(idx + 1);
       await pmCmd.parseAsync(["node", "brain-pm", "list", ...tail], { from: "node" });
@@ -11866,9 +12084,2040 @@ var pmModule = {
   }
 };
 
-// src/commands/instances.ts
-import { Command as Command45 } from "@commander-js/extra-typings";
-var listSubcommand = new Command45("list").description("List all known brain instances").option("--json", "output as JSON").option("--prune", "remove stale entries (paths that no longer exist)").action((opts) => {
+// src/modules/workflow/commands/workflow.ts
+import { Command as Command44 } from "@commander-js/extra-typings";
+
+// src/modules/workflow/data/workflow-ops.ts
+import { readFileSync as readFileSync20, existsSync as existsSync22 } from "fs";
+
+// src/modules/workflow/engine/dag.ts
+function ok3(data) {
+  return { ok: true, data };
+}
+function fail3(code, message, details) {
+  const err = { error: true, code, message };
+  if (details !== void 0) {
+    err.details = details;
+  }
+  return { ok: false, error: err };
+}
+function getPredecessors(stepId, edges) {
+  return edges.filter((e) => e.to === stepId).map((e) => e.from);
+}
+function validateDag(definition) {
+  const { steps, edges } = definition;
+  if (steps.length === 0) {
+    return fail3("INVALID_DEFINITION", "Workflow must have at least one step");
+  }
+  const stepIds = new Set(steps.map((s) => s.id));
+  for (const edge of edges) {
+    if (!stepIds.has(edge.from)) {
+      return fail3("INVALID_DEFINITION", `Edge references non-existent source step: ${edge.from}`);
+    }
+    if (!stepIds.has(edge.to)) {
+      return fail3("INVALID_DEFINITION", `Edge references non-existent target step: ${edge.to}`);
+    }
+  }
+  const cycleResult = detectCycle(steps, edges);
+  if (cycleResult) {
+    return fail3("CYCLE_DETECTED", `Cycle detected: ${cycleResult.join(" -> ")}`, {
+      cycle: cycleResult
+    });
+  }
+  const unconditionalEdges = edges.filter((e) => !e.condition);
+  const hasIncoming = new Set(unconditionalEdges.map((e) => e.to));
+  const entryNodes = steps.filter((s) => !hasIncoming.has(s.id));
+  if (entryNodes.length === 0) {
+    return fail3("INVALID_DEFINITION", "DAG must have at least one entry node");
+  }
+  const hasOutgoing = new Set(unconditionalEdges.map((e) => e.from));
+  const terminalNodes = steps.filter((s) => !hasOutgoing.has(s.id));
+  if (terminalNodes.length === 0) {
+    return fail3("INVALID_DEFINITION", "DAG must have at least one terminal node");
+  }
+  return ok3(void 0);
+}
+function detectCycle(steps, edges) {
+  const adj = /* @__PURE__ */ new Map();
+  for (const s of steps) {
+    adj.set(s.id, []);
+  }
+  for (const e of edges) {
+    if (!e.condition) {
+      adj.get(e.from)?.push(e.to);
+    }
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  const path = [];
+  for (const s of steps) {
+    const cycle = dfs(s.id, adj, visited, inStack, path);
+    if (cycle) return cycle;
+  }
+  return null;
+}
+function dfs(node, adj, visited, inStack, path) {
+  if (inStack.has(node)) {
+    const cycleStart = path.indexOf(node);
+    return path.slice(cycleStart).concat(node);
+  }
+  if (visited.has(node)) return null;
+  visited.add(node);
+  inStack.add(node);
+  path.push(node);
+  for (const neighbor of adj.get(node) ?? []) {
+    const cycle = dfs(neighbor, adj, visited, inStack, path);
+    if (cycle) return cycle;
+  }
+  path.pop();
+  inStack.delete(node);
+  return null;
+}
+function topologicalSort(steps, edges) {
+  const inDegree = /* @__PURE__ */ new Map();
+  const adj = /* @__PURE__ */ new Map();
+  for (const s of steps) {
+    inDegree.set(s.id, 0);
+    adj.set(s.id, []);
+  }
+  for (const e of edges) {
+    if (!e.condition) {
+      adj.get(e.from)?.push(e.to);
+      inDegree.set(e.to, (inDegree.get(e.to) ?? 0) + 1);
+    }
+  }
+  const queue = [];
+  for (const [id, deg] of inDegree) {
+    if (deg === 0) queue.push(id);
+  }
+  const sorted = [];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    sorted.push(node);
+    for (const neighbor of adj.get(node) ?? []) {
+      const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+      inDegree.set(neighbor, newDeg);
+      if (newDeg === 0) queue.push(neighbor);
+    }
+  }
+  if (sorted.length !== steps.length) {
+    return fail3("CYCLE_DETECTED", "Graph contains a cycle");
+  }
+  return ok3(sorted);
+}
+function getUnreachableSteps(completedSteps, edges, allSteps) {
+  const completed = new Set(completedSteps);
+  const reachable = new Set(completedSteps);
+  const stepObjs = allSteps.map((id) => ({ id, name: id }));
+  const sortResult = topologicalSort(stepObjs, edges);
+  const order = sortResult.ok ? sortResult.data : allSteps;
+  for (const stepId of order) {
+    if (reachable.has(stepId)) continue;
+    const preds = getPredecessors(stepId, edges);
+    if (preds.length === 0) continue;
+    const hasCompletedPred = preds.some((p) => completed.has(p));
+    if (hasCompletedPred) {
+      reachable.add(stepId);
+      continue;
+    }
+    const reachablePreds = preds.filter((p) => reachable.has(p));
+    if (reachablePreds.length >= 2) {
+      reachable.add(stepId);
+    }
+  }
+  return allSteps.filter((s) => !reachable.has(s));
+}
+
+// src/modules/workflow/data/queries.ts
+function getWorkflowDefinition(db, workflowId) {
+  const noteIds = db.getModuleNoteIds({ module: "workflow", type: "workflow" });
+  if (noteIds.length === 0) {
+    return fail("NOT_FOUND", `No workflow notes found.`);
+  }
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id !== workflowId) continue;
+    const chunk = db.getFirstChunkForNote(note.id);
+    if (!chunk) {
+      return fail("NOT_FOUND", `Workflow "${workflowId}" has no content to parse.`);
+    }
+    let definition;
+    try {
+      const jsonMatch = chunk.content.match(/({[\s\S]*})/);
+      const jsonStr = jsonMatch ? jsonMatch[1] : chunk.content;
+      definition = JSON.parse(jsonStr);
+    } catch {
+      return fail("INVALID_INPUT", `Workflow "${workflowId}" body is not valid JSON.`);
+    }
+    return ok({
+      note,
+      definition,
+      metadata: meta
+    });
+  }
+  return fail("NOT_FOUND", `Workflow "${workflowId}" not found.`);
+}
+function listWorkflows(db, filters) {
+  const noteIds = db.getModuleNoteIds({ module: "workflow", type: "workflow" });
+  if (noteIds.length === 0) {
+    return ok([]);
+  }
+  const notes = db.getNotesByIds(noteIds);
+  const results = [];
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (filters?.project && meta.project !== filters.project) continue;
+    if (filters?.status && meta.registration_status !== filters.status) continue;
+    results.push(meta);
+  }
+  return ok(results);
+}
+function getInstanceByDisplayId(db, displayId) {
+  const noteIds = db.getModuleNoteIds({ module: "pm", type: "task" });
+  if (noteIds.length === 0) {
+    return fail("NOT_FOUND", `No task notes found.`);
+  }
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id !== displayId) continue;
+    if (!meta.workflow_id) {
+      return fail("NOT_FOUND", `Task "${displayId}" is not a workflow instance.`);
+    }
+    return ok({
+      note,
+      metadata: {
+        workflow_id: meta.workflow_id,
+        workflow_version: meta.workflow_version ?? 1,
+        instance_status: meta.instance_status ?? "placeholder",
+        context: meta.context ?? {}
+      }
+    });
+  }
+  return fail("NOT_FOUND", `Task "${displayId}" not found.`);
+}
+function getInstanceStepStates(db, instanceDisplayId) {
+  const instanceResult = getInstanceByDisplayId(db, instanceDisplayId);
+  if (!instanceResult.ok) return instanceResult;
+  const instanceNote = instanceResult.data.note;
+  const relations = db.getRelationsFrom(instanceNote.id);
+  const expandsToRelations = relations.filter((r) => r.type === "expands-to");
+  if (expandsToRelations.length === 0) {
+    return ok({
+      steps: [],
+      progress: { total: 0, done: 0, pruned: 0, active: 0, pending: 0 }
+    });
+  }
+  const childIds = expandsToRelations.map((r) => r.targetId);
+  const childNotes = db.getNotesByIds(childIds);
+  const steps = [];
+  let done = 0;
+  let pruned = 0;
+  let active = 0;
+  let pending = 0;
+  for (const [, childNote] of childNotes) {
+    if (!childNote.metadata) continue;
+    const meta = JSON.parse(childNote.metadata);
+    const status = meta.status ?? "pending";
+    const stepId = meta.step_id ?? "";
+    const taskDisplayId = meta.display_id ?? "";
+    steps.push({ stepId, taskDisplayId, status });
+    switch (status) {
+      case "done":
+        done++;
+        break;
+      case "pruned":
+      case "cancelled":
+        pruned++;
+        break;
+      case "claimed":
+      case "in-progress":
+        active++;
+        break;
+      default:
+        pending++;
+        break;
+    }
+  }
+  return ok({
+    steps,
+    progress: { total: steps.length, done, pruned, active, pending }
+  });
+}
+
+// src/modules/workflow/data/workflow-ops.ts
+function extractNoteBody(filePath) {
+  if (!existsSync22(filePath)) return "";
+  const content = readFileSync20(filePath, "utf-8");
+  const fmEnd = content.indexOf("\n---", 4);
+  if (fmEnd === -1) return "";
+  let body = content.slice(fmEnd + 4).trim();
+  if (body.startsWith("#")) {
+    const headingEnd = body.indexOf("\n");
+    if (headingEnd === -1) return "";
+    body = body.slice(headingEnd + 1).trim();
+  }
+  return body;
+}
+async function registerWorkflow(db, _config, _embedder, noteId) {
+  const note = db.getNoteById(noteId);
+  if (!note) {
+    return fail("NOT_FOUND", `Note "${noteId}" not found`);
+  }
+  if (note.type !== "workflow") {
+    return fail(
+      "INVALID_NOTE_TYPE",
+      `Note "${noteId}" is type "${note.type}", expected "workflow"`
+    );
+  }
+  const body = extractNoteBody(note.filePath);
+  let definition;
+  try {
+    definition = JSON.parse(body);
+  } catch {
+    return fail("PARSE_ERROR", `Failed to parse workflow definition as JSON`);
+  }
+  const dagResult = validateDag(definition);
+  if (!dagResult.ok) {
+    const code = dagResult.error.code;
+    return fail(code, dagResult.error.message, dagResult.error.details);
+  }
+  const existingMeta = note.metadata ? JSON.parse(note.metadata) : {};
+  const currentVersion = existingMeta.registration_status === "registered" ? existingMeta.version ?? 0 : 0;
+  const newVersion = currentVersion + 1;
+  const updatedMeta = {
+    ...existingMeta,
+    registration_status: "registered",
+    version: newVersion,
+    step_count: definition.steps.length,
+    edge_count: definition.edges.length,
+    name: definition.name,
+    display_id: existingMeta.display_id ?? noteId
+  };
+  const updatedNote = { ...note, metadata: JSON.stringify(updatedMeta) };
+  db.upsertNote(updatedNote);
+  const workflowMeta = {
+    display_id: updatedMeta.display_id ?? noteId,
+    name: definition.name,
+    version: newVersion,
+    registration_status: "registered",
+    step_count: definition.steps.length,
+    edge_count: definition.edges.length
+  };
+  return ok(workflowMeta);
+}
+async function instantiateWorkflow(db, config, embedder, workflowId, project, context, options) {
+  const defResult = getWorkflowDefinition(db, workflowId);
+  if (!defResult.ok) {
+    return fail("NOT_FOUND", defResult.error.message);
+  }
+  const { definition, metadata: wfMeta, note: defNote } = defResult.data;
+  if (definition.parameters) {
+    for (const param of definition.parameters) {
+      if (param.required && !(param.name in context)) {
+        return fail("MISSING_PARAMETER", `Required parameter "${param.name}" not provided`);
+      }
+    }
+  }
+  const taskResult = await createTask(db, config, embedder, {
+    project,
+    workstream: 1,
+    name: `[${definition.name}] instance`,
+    description: `Workflow instance of ${workflowId}`,
+    category: "implementation",
+    priority: "medium"
+  });
+  if (!taskResult.ok) {
+    return fail("NOT_FOUND", taskResult.error.message);
+  }
+  const taskDisplayId = taskResult.data.display_id;
+  const taskNoteIds = db.getModuleNoteIds({ module: "pm", type: "task" });
+  const taskNotes = db.getNotesByIds(taskNoteIds);
+  let taskNoteId;
+  for (const [, note] of taskNotes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id === taskDisplayId) {
+      taskNoteId = note.id;
+      const updatedMeta = {
+        ...meta,
+        workflow_id: workflowId,
+        workflow_version: wfMeta.version,
+        instance_status: "placeholder",
+        context
+      };
+      db.upsertNote({ ...note, metadata: JSON.stringify(updatedMeta) });
+      break;
+    }
+  }
+  if (taskNoteId) {
+    const relations = [{ sourceId: taskNoteId, targetId: defNote.id, type: "instance-of" }];
+    if (options?.iterationOf) {
+      const prevInstanceResult = getInstanceByDisplayId(db, options.iterationOf);
+      if (prevInstanceResult.ok) {
+        relations.push({
+          sourceId: taskNoteId,
+          targetId: prevInstanceResult.data.note.id,
+          type: "iteration-of"
+        });
+      }
+    }
+    db.upsertRelations(taskNoteId, relations);
+  }
+  return ok({
+    display_id: taskDisplayId,
+    workflow_id: workflowId,
+    workflow_version: wfMeta.version,
+    instance_status: "placeholder",
+    context
+  });
+}
+async function expandWorkflow(db, config, embedder, instanceDisplayId) {
+  const instanceResult = getInstanceByDisplayId(db, instanceDisplayId);
+  if (!instanceResult.ok) {
+    return fail("NOT_FOUND", instanceResult.error.message);
+  }
+  const { note: instanceNote, metadata: instanceMeta } = instanceResult.data;
+  if (instanceMeta.instance_status === "expanded" || instanceMeta.instance_status === "executing" || instanceMeta.instance_status === "completed" || instanceMeta.instance_status === "collapsed") {
+    return fail("ALREADY_EXPANDED", `Instance "${instanceDisplayId}" is already expanded`);
+  }
+  const relations = db.getRelationsFrom(instanceNote.id);
+  const instanceOfRel = relations.find((r) => r.type === "instance-of");
+  if (!instanceOfRel) {
+    return fail("DEFINITION_NOT_FOUND", `No instance-of relation found for "${instanceDisplayId}"`);
+  }
+  const defNote = db.getNoteById(instanceOfRel.targetId);
+  if (!defNote) {
+    return fail("DEFINITION_NOT_FOUND", `Workflow definition note not found`);
+  }
+  const chunk = db.getFirstChunkForNote(defNote.id);
+  if (!chunk) {
+    return fail("DEFINITION_NOT_FOUND", `Workflow definition has no content`);
+  }
+  let definition;
+  try {
+    const jsonMatch = chunk.content.match(/({[\s\S]*})/);
+    definition = JSON.parse(jsonMatch ? jsonMatch[1] : chunk.content);
+  } catch {
+    return fail("DEFINITION_NOT_FOUND", `Failed to parse workflow definition`);
+  }
+  const sortResult = topologicalSort(definition.steps, definition.edges);
+  if (!sortResult.ok) {
+    return fail("DEFINITION_NOT_FOUND", `Failed to sort workflow steps`);
+  }
+  const topoOrder = sortResult.data;
+  const stepToTaskNoteId = /* @__PURE__ */ new Map();
+  const stepToDisplayId = /* @__PURE__ */ new Map();
+  const instanceParsedMeta = JSON.parse(instanceNote.metadata);
+  const instanceProject = instanceParsedMeta.project ?? "TST";
+  const instanceWorkstream = instanceParsedMeta.workstream ?? 1;
+  for (const stepId of topoOrder) {
+    const stepDef = definition.steps.find((s) => s.id === stepId);
+    const stepName = stepDef?.name ?? stepId;
+    const taskResult = await createTask(db, config, embedder, {
+      project: instanceProject,
+      workstream: instanceWorkstream,
+      name: `[${definition.name}] ${stepName}`,
+      description: `Step "${stepId}" of workflow ${instanceDisplayId}`,
+      category: stepDef?.category ?? "implementation",
+      priority: stepDef?.priority ?? "medium"
+    });
+    if (!taskResult.ok) continue;
+    const childDisplayId = taskResult.data.display_id;
+    stepToDisplayId.set(stepId, childDisplayId);
+    const matchingNotes = getPmNotes(db, "task", { display_id: childDisplayId });
+    if (matchingNotes.length > 0) {
+      const childNote = matchingNotes[0];
+      const meta = childNote.metadata ? JSON.parse(childNote.metadata) : {};
+      const updatedChildMeta = { ...meta, step_id: stepId };
+      db.upsertNote({ ...childNote, metadata: JSON.stringify(updatedChildMeta) });
+      stepToTaskNoteId.set(stepId, childNote.id);
+    }
+  }
+  const existingInstanceRelations = db.getRelationsFrom(instanceNote.id);
+  const instanceRelations = [...existingInstanceRelations];
+  for (const [, childNoteId] of stepToTaskNoteId) {
+    instanceRelations.push({
+      sourceId: instanceNote.id,
+      targetId: childNoteId,
+      type: "expands-to"
+    });
+  }
+  db.upsertRelations(instanceNote.id, instanceRelations);
+  const unconditionalEdges = definition.edges.filter((e) => !e.condition);
+  const edgesBySource = /* @__PURE__ */ new Map();
+  let edgeCount = 0;
+  for (const edge of unconditionalEdges) {
+    const fromNoteId = stepToTaskNoteId.get(edge.from);
+    const toNoteId = stepToTaskNoteId.get(edge.to);
+    if (fromNoteId && toNoteId) {
+      if (!edgesBySource.has(toNoteId)) {
+        edgesBySource.set(toNoteId, []);
+      }
+      edgesBySource.get(toNoteId).push({
+        sourceId: toNoteId,
+        targetId: fromNoteId,
+        type: "depends_on"
+      });
+      edgeCount++;
+    }
+  }
+  for (const [sourceNoteId, rels] of edgesBySource) {
+    const existing = db.getRelationsFrom(sourceNoteId);
+    db.upsertRelations(sourceNoteId, [...existing, ...rels]);
+  }
+  const currentMeta = JSON.parse(instanceNote.metadata);
+  const expandedMeta = { ...currentMeta, instance_status: "expanded" };
+  db.upsertNote({ ...instanceNote, metadata: JSON.stringify(expandedMeta) });
+  return ok({ tasksCreated: stepToTaskNoteId.size, edges: edgeCount });
+}
+function getWorkflowStatus(db, instanceDisplayId) {
+  const instanceResult = getInstanceByDisplayId(db, instanceDisplayId);
+  if (!instanceResult.ok) {
+    return fail("NOT_FOUND", instanceResult.error.message);
+  }
+  const stepsResult = getInstanceStepStates(db, instanceDisplayId);
+  if (!stepsResult.ok) {
+    return fail("NOT_FOUND", stepsResult.error.message);
+  }
+  const { steps } = stepsResult.data;
+  const defResult = getWorkflowDefinition(db, instanceResult.data.metadata.workflow_id);
+  if (defResult.ok) {
+    const { definition } = defResult.data;
+    const sortResult = topologicalSort(definition.steps, definition.edges);
+    if (sortResult.ok) {
+      const orderIndex = new Map(sortResult.data.map((id, i) => [id, i]));
+      steps.sort((a, b) => {
+        const ai = orderIndex.get(a.stepId) ?? Infinity;
+        const bi = orderIndex.get(b.stepId) ?? Infinity;
+        return ai - bi;
+      });
+    }
+  }
+  return ok({
+    instance: instanceResult.data.metadata,
+    steps,
+    progress: stepsResult.data.progress
+  });
+}
+async function collapseWorkflow(db, config, embedder, instanceDisplayId) {
+  const instanceResult = getInstanceByDisplayId(db, instanceDisplayId);
+  if (!instanceResult.ok) {
+    return fail("NOT_FOUND", instanceResult.error.message);
+  }
+  const { note: instanceNote, metadata: instanceMeta } = instanceResult.data;
+  if (instanceMeta.instance_status === "placeholder") {
+    return fail("NOT_EXPANDED", `Instance "${instanceDisplayId}" has not been expanded`);
+  }
+  const stepsResult = getInstanceStepStates(db, instanceDisplayId);
+  if (!stepsResult.ok) {
+    return fail("NOT_FOUND", stepsResult.error.message);
+  }
+  const { steps } = stepsResult.data;
+  const incomplete = steps.filter(
+    (s) => s.status !== "done" && s.status !== "pruned" && s.status !== "cancelled"
+  );
+  if (incomplete.length > 0) {
+    return fail("INCOMPLETE_WORKFLOW", `${incomplete.length} tasks are not done/pruned`, {
+      incomplete: incomplete.map((s) => s.taskDisplayId)
+    });
+  }
+  let tasksArchived = 0;
+  const relations = db.getRelationsFrom(instanceNote.id);
+  const expandsToRelations = relations.filter((r) => r.type === "expands-to");
+  const childIds = expandsToRelations.map((r) => r.targetId);
+  const childNotes = db.getNotesByIds(childIds);
+  for (const [, childNote] of childNotes) {
+    if (!childNote.metadata) continue;
+    const meta = JSON.parse(childNote.metadata);
+    if (meta.status !== "done") {
+      const updatedMeta = { ...meta, status: "done" };
+      db.upsertNote({ ...childNote, metadata: JSON.stringify(updatedMeta) });
+    }
+    tasksArchived++;
+  }
+  const currentMeta = JSON.parse(instanceNote.metadata);
+  const collapsedMeta = { ...currentMeta, instance_status: "collapsed" };
+  db.upsertNote({ ...instanceNote, metadata: JSON.stringify(collapsedMeta) });
+  const summaryNoteId = `${instanceDisplayId}-summary`;
+  return ok({ summaryNoteId, tasksArchived });
+}
+
+// src/modules/workflow/engine/templates.ts
+import { readFileSync as readFileSync21, existsSync as existsSync23, readdirSync as readdirSync5 } from "fs";
+import { join as join21, basename as basename7 } from "path";
+function findTemplatesDir() {
+  const sourceDir = join21(import.meta.dirname, "..", "templates");
+  if (existsSync23(sourceDir) && existsSync23(join21(sourceDir, "implementation-compact.md"))) {
+    return sourceDir;
+  }
+  const bundledDir = join21(import.meta.dirname, "templates");
+  if (existsSync23(bundledDir) && existsSync23(join21(bundledDir, "implementation-compact.md"))) {
+    return bundledDir;
+  }
+  return sourceDir;
+}
+var TEMPLATES_DIR = findTemplatesDir();
+function resolveTemplate(templateName) {
+  const normalized = templateName.endsWith(".md") ? templateName : `${templateName}.md`;
+  const filePath = join21(TEMPLATES_DIR, normalized);
+  if (!existsSync23(filePath)) {
+    const available = listTemplateNames();
+    return fail(
+      "NOT_FOUND",
+      `Template "${templateName}" not found. Available: ${available.join(", ")}`
+    );
+  }
+  const content = readFileSync21(filePath, "utf-8");
+  const variables = extractVariables(content);
+  const name = basename7(normalized, ".md");
+  return ok({ name, content, variables });
+}
+function listTemplateNames() {
+  if (!existsSync23(TEMPLATES_DIR)) return [];
+  return readdirSync5(TEMPLATES_DIR).filter((f) => f.endsWith(".md")).map((f) => basename7(f, ".md")).sort();
+}
+function extractVariables(content) {
+  const matches = content.matchAll(/\{\{(\w+)\}\}/g);
+  const vars = /* @__PURE__ */ new Set();
+  for (const m of matches) {
+    vars.add(m[1]);
+  }
+  return [...vars].sort();
+}
+function renderTemplate(templateName, params) {
+  const resolved = resolveTemplate(templateName);
+  if (!resolved.ok) return resolved;
+  let rendered = resolved.data.content;
+  for (const [key, value] of Object.entries(params)) {
+    rendered = rendered.replaceAll(`{{${key}}}`, value);
+  }
+  return ok(rendered);
+}
+
+// src/modules/workflow/engine/dispatch.ts
+var CATEGORY_TO_PREFIX = {
+  implementation: "feature",
+  feature: "feature",
+  testing: "feature",
+  documentation: "feature",
+  design: "feature",
+  configuration: "feature",
+  migration: "feature",
+  bug: "bug",
+  fix: "bug",
+  refactor: "refactor",
+  infrastructure: "infrastructure",
+  research: "feature",
+  review: "feature"
+};
+function slugify2(text) {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60);
+}
+function buildBranchName(category, title, branchPrefix) {
+  const prefixKey = CATEGORY_TO_PREFIX[category] ?? "feature";
+  const prefix = branchPrefix?.[prefixKey] ?? defaultBranchPrefix(prefixKey);
+  const slug = slugify2(title);
+  return `${prefix}/${slug}`;
+}
+function defaultBranchPrefix(key) {
+  const defaults = {
+    feature: "feat",
+    bug: "fix",
+    refactor: "refactor",
+    infrastructure: "infra"
+  };
+  return defaults[key];
+}
+function resolveStepMode(db, taskId) {
+  const taskNotes = getPmNotes(db, "task", { display_id: taskId });
+  if (taskNotes.length === 0) return void 0;
+  const taskNote = taskNotes[0];
+  if (!taskNote.metadata) return void 0;
+  const taskMeta = JSON.parse(taskNote.metadata);
+  const stepId = taskMeta.step_id;
+  if (!stepId) return void 0;
+  const incomingRelations = db.getRelationsTo(taskNote.id);
+  const expandsToRel = incomingRelations.find((r) => r.type === "expands-to");
+  if (!expandsToRel) return void 0;
+  const instanceNote = db.getNoteById(expandsToRel.sourceId);
+  if (!instanceNote?.metadata) return void 0;
+  const instanceMeta = JSON.parse(instanceNote.metadata);
+  const workflowId = instanceMeta.workflow_id;
+  if (!workflowId) return void 0;
+  const defResult = getWorkflowDefinition(db, workflowId);
+  if (!defResult.ok) return void 0;
+  const step = defResult.data.definition.steps.find((s) => s.id === stepId);
+  return step?.mode;
+}
+function injectWorkflowContext(db, taskId, vars) {
+  const taskNotes = getPmNotes(db, "task", { display_id: taskId });
+  if (taskNotes.length === 0) return;
+  const taskNote = taskNotes[0];
+  if (!taskNote.metadata) return;
+  const taskMeta = JSON.parse(taskNote.metadata);
+  const stepId = taskMeta.step_id;
+  if (stepId) {
+    vars.STEP_ID = stepId;
+  }
+  const incomingRelations = db.getRelationsTo(taskNote.id);
+  const expandsToRel = incomingRelations.find((r) => r.type === "expands-to");
+  if (!expandsToRel) return;
+  const instanceNote = db.getNoteById(expandsToRel.sourceId);
+  if (!instanceNote?.metadata) return;
+  const instanceMeta = JSON.parse(instanceNote.metadata);
+  const instanceDisplayId = instanceMeta.display_id;
+  const workflowId = instanceMeta.workflow_id;
+  const context = instanceMeta.context;
+  if (instanceDisplayId) {
+    vars.INSTANCE_ID = instanceDisplayId;
+  }
+  if (workflowId) {
+    vars.WORKFLOW_ID = workflowId;
+    const defResult = getWorkflowDefinition(db, workflowId);
+    if (defResult.ok) {
+      vars.WORKFLOW_NAME = defResult.data.definition.name;
+    }
+  }
+  if (context) {
+    for (const [key, value] of Object.entries(context)) {
+      vars[key] = value;
+      const upperKey = key.toUpperCase();
+      if (!(upperKey in vars)) {
+        vars[upperKey] = value;
+      }
+    }
+  }
+}
+async function dispatchTemplate(db, config, embedder, taskId, templateName, opts = {}) {
+  const prefix = taskId.split("-")[0];
+  const taskResult = getTask(db, taskId);
+  if (!taskResult.ok) {
+    return fail(taskResult.error.code, taskResult.error.message, taskResult.error.details);
+  }
+  const task = taskResult.data;
+  const projectResult = getProject(db, prefix);
+  const vars = {};
+  vars.TASK_ID = taskId;
+  vars.BRAIN_TASK_ID = taskId;
+  vars.PROJECT_PREFIX = prefix;
+  if (projectResult.ok) {
+    const p = projectResult.data;
+    vars.REPO_PATH = p.path ?? "";
+    vars.BUILD_CMD = p.commands?.build ?? "N/A";
+    vars.TEST_CMD = p.commands?.test ?? "N/A";
+    vars.TYPECHECK_CMD = p.commands?.typecheck ?? "N/A";
+    vars.LINT_CMD = p.commands?.lint ?? "N/A";
+    vars.BASE_BRANCH = p.default_branch ?? "main";
+    vars.REVIEW_THRESHOLD = String(p.review_threshold ?? 5);
+    vars.BRANCH_NAME = opts.branch ?? buildBranchName(task.category, task.title ?? taskId, p.branch_prefix);
+  } else {
+    vars.REPO_PATH = "";
+    vars.BUILD_CMD = "N/A";
+    vars.TEST_CMD = "N/A";
+    vars.TYPECHECK_CMD = "N/A";
+    vars.LINT_CMD = "N/A";
+    vars.BASE_BRANCH = "main";
+    vars.REVIEW_THRESHOLD = "5";
+    vars.BRANCH_NAME = opts.branch ?? buildBranchName(task.category, task.title ?? taskId);
+  }
+  vars.WORKTREE_PATH = opts.worktree ?? "";
+  const taskNotes = getPmNotes(db, "task", { display_id: taskId });
+  if (taskNotes.length > 0) {
+    const body = readTaskBody(taskNotes[0]);
+    vars.IMPLEMENTATION_INSTRUCTIONS = body;
+    vars.TASK_DESCRIPTION = body;
+  }
+  if (task.claim_token) {
+    vars.CLAIM_TOKEN = task.claim_token;
+  }
+  if (opts.claim && !opts.dryRun) {
+    const claimResult = await updateTaskStatus(db, config, embedder, taskId, "claimed");
+    if (!claimResult.ok) {
+      return fail(claimResult.error.code, claimResult.error.message, claimResult.error.details);
+    }
+    const claim = generateClaim();
+    vars.CLAIM_TOKEN = claim.token;
+  }
+  injectWorkflowContext(db, taskId, vars);
+  const stepMode = resolveStepMode(db, taskId);
+  const rendered = renderTemplate(templateName, vars);
+  if (!rendered.ok) return rendered;
+  const unfilledMatches = rendered.data.matchAll(/\{\{(\w+)\}\}/g);
+  const unfilled = [...new Set([...unfilledMatches].map((m) => m[1]))].sort();
+  return ok({
+    rendered: rendered.data,
+    template: templateName,
+    taskId,
+    variables: vars,
+    unfilled,
+    mode: stepMode
+  });
+}
+
+// src/modules/workflow/commands/workflow.ts
+function formatWorkflowLine(wf) {
+  return `${wf.display_id} - ${wf.name} v${wf.version} [${wf.registration_status}]`;
+}
+function formatError2(error, json) {
+  if (json) {
+    return JSON.stringify({ error: true, code: error.code, message: error.message });
+  }
+  return `Error [${error.code}]: ${error.message}`;
+}
+function createWorkflowCommand() {
+  const cmd = new Command44("workflow").description("Workflow definition management");
+  cmd.command("register").description("Register a workflow definition").argument("<note-id>", "Note ID of the workflow to register").option("--json", "Output JSON").action(async (noteId, opts) => {
+    await withBrain(async (svc) => {
+      const result = await registerWorkflow(svc.db, svc.config, svc.embedder, noteId);
+      if (!result.ok) {
+        process.stderr.write(formatError2(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const meta = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(meta, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Registered workflow: ${meta.name}
+`);
+        process.stdout.write(`  Version: ${meta.version}
+`);
+        process.stdout.write(`  Steps: ${meta.step_count}
+`);
+        process.stdout.write(`  Edges: ${meta.edge_count}
+`);
+      }
+    });
+  });
+  cmd.command("list").description("List registered workflows").option("--project <prefix>", "Filter by project prefix").option("--status <status>", "Filter by registration status").option("--json", "Output JSON").action(async (opts) => {
+    await withBrain(async (svc) => {
+      const filters = {};
+      if (opts.project) filters.project = opts.project;
+      if (opts.status) filters.status = opts.status;
+      const result = listWorkflows(svc.db, filters);
+      if (!result.ok) {
+        process.stderr.write(formatError2(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const workflows = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(workflows, null, 2) + "\n");
+      } else if (workflows.length === 0) {
+        process.stdout.write("No workflows found.\n");
+      } else {
+        for (const wf of workflows) {
+          process.stdout.write(formatWorkflowLine(wf) + "\n");
+        }
+      }
+    });
+  });
+  cmd.command("show").description("Show workflow definition details").argument("<workflow-id>", "Workflow display ID").option("--json", "Output JSON").action(async (workflowId, opts) => {
+    await withBrain(async (svc) => {
+      const result = getWorkflowDefinition(svc.db, workflowId);
+      if (!result.ok) {
+        process.stderr.write(formatError2(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const { definition, metadata } = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify({ metadata, definition }, null, 2) + "\n");
+      } else {
+        process.stdout.write(`${metadata.display_id} - ${metadata.name}
+`);
+        process.stdout.write(`  Version: ${metadata.version}
+`);
+        process.stdout.write(`  Steps: ${metadata.step_count}
+`);
+        process.stdout.write(`  Edges: ${metadata.edge_count}
+`);
+        if (definition.steps.length > 0) {
+          process.stdout.write("\nSteps:\n");
+          for (const step of definition.steps) {
+            const mode = step.mode ? ` (${step.mode})` : "";
+            process.stdout.write(`  ${step.id} - ${step.name}${mode}
+`);
+          }
+        }
+      }
+    });
+  });
+  cmd.command("status").description("Show workflow instance status").argument("<instance-id>", "Instance display ID").option("--history", "Show execution history").option("--json", "Output JSON").action(async (instanceId, opts) => {
+    await withBrain(async (svc) => {
+      const result = getWorkflowStatus(svc.db, instanceId);
+      if (!result.ok) {
+        process.stderr.write(formatError2(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const { instance: metadata, steps, progress } = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify({ metadata, steps, progress }, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Instance: ${instanceId}
+`);
+        process.stdout.write(
+          `  Workflow: ${metadata.workflow_id} v${metadata.workflow_version}
+`
+        );
+        process.stdout.write(`  Status: ${metadata.instance_status}
+`);
+        process.stdout.write(
+          `  Progress: ${progress.done}/${progress.total} done, ${progress.active} active, ${progress.pending} pending, ${progress.pruned} pruned
+`
+        );
+        if (steps.length > 0) {
+          process.stdout.write("\nSteps:\n");
+          for (const step of steps) {
+            process.stdout.write(`  ${step.stepId} (${step.taskDisplayId}) - ${step.status}
+`);
+          }
+        }
+        if (opts.history) {
+          process.stdout.write("\nHistory not yet available.\n");
+        }
+      }
+    });
+  });
+  cmd.command("dispatch").description("Fill a dispatch template with task and project metadata").argument("<task-id>", "Brain PM task display ID (e.g., SDK-02.03)").argument("<template>", "Template name (e.g., implementation-compact)").option("--branch <name>", "Override auto-generated branch name").option("--worktree <path>", "Set worktree path").option("--dry-run", "Show filled template without claiming the task").option("--claim", "Auto-claim the task before dispatch").option("--json", "Output JSON with template and metadata").action(async (taskId, templateName, opts) => {
+    await withBrain(async (svc) => {
+      const result = await dispatchTemplate(
+        svc.db,
+        svc.config,
+        svc.embedder,
+        taskId.toUpperCase(),
+        templateName,
+        {
+          branch: opts.branch,
+          worktree: opts.worktree,
+          dryRun: opts.dryRun,
+          claim: opts.claim
+        }
+      );
+      if (!result.ok) {
+        process.stderr.write(formatError2(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else {
+        if (result.data.mode === "assisted") {
+          process.stdout.write("## Assisted Step \u2014 Coordinator Instructions\n\n");
+          process.stdout.write(
+            "This step requires interactive coordination. Use this prompt in your current session.\n"
+          );
+          process.stdout.write("Do NOT dispatch this to an autonomous agent.\n\n");
+          process.stdout.write("---\n\n");
+        }
+        process.stdout.write(result.data.rendered + "\n");
+      }
+    });
+  });
+  cmd.command("gate").description("Set gate status for a workflow step").argument("<instance-id>", "Instance display ID").argument("<step-id>", "Step ID within the workflow").argument("<action>", "Gate action: pass").option("--json", "Output JSON").action(async (instanceId, stepId, action, opts) => {
+    if (action !== "pass") {
+      const msg = `Unknown gate action "${action}". Supported: pass`;
+      process.stderr.write(
+        formatError2({ code: "INVALID_ACTION", message: msg }, !!opts.json) + "\n"
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await withBrain(async (svc) => {
+      const stepsResult = getInstanceStepStates(svc.db, instanceId);
+      if (!stepsResult.ok) {
+        process.stderr.write(formatError2(stepsResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const step = stepsResult.data.steps.find((s) => s.stepId === stepId);
+      if (!step) {
+        const msg = `Step "${stepId}" not found in instance "${instanceId}"`;
+        process.stderr.write(
+          formatError2({ code: "NOT_FOUND", message: msg }, !!opts.json) + "\n"
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const taskNotes = svc.db.getModuleNoteIds({ module: "pm", type: "task" });
+      const notes = svc.db.getNotesByIds(taskNotes);
+      let updated = false;
+      for (const [, note] of notes) {
+        if (!note.metadata) continue;
+        const meta = JSON.parse(note.metadata);
+        if (meta.display_id !== step.taskDisplayId) continue;
+        const newMeta = { ...meta, gate_status: "passed" };
+        svc.db.upsertNote({ ...note, metadata: JSON.stringify(newMeta) });
+        updated = true;
+        break;
+      }
+      if (!updated) {
+        const msg = `Could not update gate for task "${step.taskDisplayId}"`;
+        process.stderr.write(
+          formatError2({ code: "UPDATE_FAILED", message: msg }, !!opts.json) + "\n"
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify(
+            { instance_id: instanceId, step_id: stepId, gate_status: "passed" },
+            null,
+            2
+          ) + "\n"
+        );
+      } else {
+        process.stdout.write(`Gate passed for step "${stepId}" (${step.taskDisplayId})
+`);
+      }
+    });
+  });
+  return cmd;
+}
+
+// src/modules/workflow/commands/resource.ts
+import { Command as Command45 } from "@commander-js/extra-typings";
+
+// src/modules/workflow/engine/fast-path.ts
+import {
+  existsSync as existsSync24,
+  mkdirSync as mkdirSync17,
+  readFileSync as readFileSync22,
+  readdirSync as readdirSync6,
+  renameSync as renameSync2,
+  unlinkSync as unlinkSync7,
+  writeFileSync as writeFileSync17
+} from "fs";
+import { createHash as createHash14, randomUUID as randomUUID8 } from "crypto";
+import { join as join22 } from "path";
+function sidecarDir(config) {
+  return join22(config.notesDir, "modules", "workflow", "resources");
+}
+function sidecarPath(config, displayId) {
+  return join22(sidecarDir(config), `${displayId}.json`);
+}
+function toFastPathResource(resource) {
+  return {
+    id: resource.display_id,
+    type: resource.resource_type,
+    project: resource.project,
+    status: resource.status,
+    data: resource.data,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function buildResourceMarkdown(resource) {
+  const now = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const id = resource.display_id.toLowerCase() + "-resource";
+  const dataJson = JSON.stringify(resource.data);
+  const lines2 = [
+    "---",
+    `id: ${id}`,
+    `title: "Resource ${resource.display_id}"`,
+    "type: resource",
+    "tier: fast",
+    "module: workflow",
+    `display_id: ${resource.display_id}`,
+    `resource_type: ${resource.resource_type}`,
+    `project: ${resource.project}`,
+    `status: ${resource.status}`,
+    `data: '${dataJson}'`,
+    `created: ${now}`,
+    `modified: ${now}`,
+    "---",
+    "",
+    `# Resource ${resource.display_id}`,
+    "",
+    `Type: ${resource.resource_type}`,
+    `Project: ${resource.project}`,
+    ""
+  ];
+  return lines2.join("\n");
+}
+function writeSidecarAtomic(config, resource) {
+  const dir = sidecarDir(config);
+  if (!existsSync24(dir)) {
+    mkdirSync17(dir, { recursive: true });
+  }
+  const tmpPath = join22(dir, `.${resource.id}-${randomUUID8().slice(0, 8)}.tmp`);
+  const finalPath = sidecarPath(config, resource.id);
+  writeFileSync17(tmpPath, JSON.stringify(resource, null, 2), "utf-8");
+  renameSync2(tmpPath, finalPath);
+}
+async function writeResource(db, config, embedder, resource) {
+  const fastPathData = toFastPathResource(resource);
+  try {
+    writeSidecarAtomic(config, fastPathData);
+  } catch {
+    return fail("SIDECAR_WRITE_FAILED", `Failed to write sidecar for ${resource.display_id}`);
+  }
+  try {
+    const markdown = buildResourceMarkdown(resource);
+    const noteDir = join22(config.notesDir, "modules", "workflow");
+    if (!existsSync24(noteDir)) {
+      mkdirSync17(noteDir, { recursive: true });
+    }
+    const filePath = join22(noteDir, `${resource.display_id}.md`);
+    writeFileSync17(filePath, markdown, "utf-8");
+    const hash = createHash14("sha256").update(markdown).digest("hex");
+    await indexSingleFile(db, embedder, filePath, markdown, hash, Date.now());
+  } catch {
+    const sc = sidecarPath(config, resource.display_id);
+    if (existsSync24(sc)) {
+      unlinkSync7(sc);
+    }
+    return fail("DB_WRITE_FAILED", `Failed to index resource note for ${resource.display_id}`);
+  }
+  return ok(fastPathData);
+}
+async function updateResourceSidecar(db, config, embedder, resourceId, updates) {
+  const existing = readResourceFastPath(config.notesDir, resourceId);
+  if (!existing) {
+    return fail("NOT_FOUND", `Resource "${resourceId}" not found`);
+  }
+  const updated = {
+    ...existing,
+    type: updates.resource_type ?? existing.type,
+    project: updates.project ?? existing.project,
+    status: updates.status ?? existing.status,
+    data: updates.data ?? existing.data,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  try {
+    writeSidecarAtomic(config, updated);
+  } catch {
+    return fail("SIDECAR_WRITE_FAILED", `Failed to update sidecar for ${resourceId}`);
+  }
+  return ok(updated);
+}
+function readResourceFastPath(notesDir, displayId) {
+  const filePath = join22(notesDir, "modules", "workflow", "resources", `${displayId}.json`);
+  if (!existsSync24(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync22(filePath, "utf-8"));
+  } catch {
+    process.stderr.write(`fast-path: corrupt JSON in ${filePath}
+`);
+    return null;
+  }
+}
+
+// src/modules/workflow/data/resource-ops.ts
+async function createResource(db, config, embedder, resource) {
+  return writeResource(db, config, embedder, resource);
+}
+function listResources(db, filters) {
+  const noteIds = db.getModuleNoteIds({ module: "workflow", type: "resource" });
+  const notes = db.getNotesByIds(noteIds);
+  const resources = [];
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (filters?.type && meta.resource_type !== filters.type) continue;
+    if (filters?.project && meta.project !== filters.project) continue;
+    if (filters?.status && meta.status !== filters.status) continue;
+    resources.push({
+      id: meta.display_id,
+      type: meta.resource_type,
+      project: meta.project,
+      status: meta.status,
+      data: typeof meta.data === "string" ? JSON.parse(meta.data) : meta.data ?? {},
+      updatedAt: note.modifiedAt ?? note.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return ok(resources);
+}
+function getResource(db, resourceId) {
+  const noteIds = db.getModuleNoteIds({ module: "workflow", type: "resource" });
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id !== resourceId) continue;
+    return ok({
+      id: meta.display_id,
+      type: meta.resource_type,
+      project: meta.project,
+      status: meta.status,
+      data: typeof meta.data === "string" ? JSON.parse(meta.data) : meta.data ?? {},
+      updatedAt: note.modifiedAt ?? note.createdAt ?? (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  return fail("NOT_FOUND", `Resource "${resourceId}" not found`);
+}
+async function releaseResource(db, config, embedder, resourceId) {
+  return updateResourceSidecar(db, config, embedder, resourceId, { status: "released" });
+}
+
+// src/modules/workflow/commands/resource.ts
+function parseDataPairs(raw) {
+  const result = {};
+  for (const pair of raw.split(",")) {
+    const eqIdx = pair.indexOf("=");
+    if (eqIdx === -1) continue;
+    const key = pair.slice(0, eqIdx).trim();
+    const val = pair.slice(eqIdx + 1).trim();
+    result[key] = val;
+  }
+  return result;
+}
+function createResourceCommand() {
+  const cmd = new Command45("resource").description("Workflow resource management");
+  cmd.command("add").description("Add a resource to a workflow").requiredOption("--type <type>", "Resource type (worktree|branch|ownership|wip-slot)").requiredOption("--project <prefix>", "Project prefix").option("--data <pairs>", "Comma-separated key=val data pairs").option("--id <id>", "Custom display ID").option("--json", "Output JSON").action(async (opts) => {
+    await withBrain(async (svc) => {
+      const displayId = opts.id ?? `RES-${Date.now().toString(36).toUpperCase()}`;
+      const resource = {
+        display_id: displayId,
+        resource_type: opts.type,
+        project: opts.project,
+        status: "active",
+        data: opts.data ? parseDataPairs(opts.data) : {}
+      };
+      const result = await createResource(svc.db, svc.config, svc.embedder, resource);
+      if (!result.ok) {
+        process.stderr.write(`Error: ${result.error.message}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Created resource ${result.data.id} (${result.data.type})
+`);
+      }
+    });
+  });
+  cmd.command("list").description("List workflow resources").option("--type <type>", "Filter by resource type").option("--project <prefix>", "Filter by project").option("--json", "Output JSON").action(async (opts) => {
+    await withBrain(async (svc) => {
+      const result = listResources(svc.db, {
+        type: opts.type,
+        project: opts.project
+      });
+      if (!result.ok) {
+        process.stderr.write(`Error: ${result.error.message}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else if (result.data.length === 0) {
+        process.stdout.write("No resources found.\n");
+      } else {
+        for (const r of result.data) {
+          process.stdout.write(`${r.id}  ${r.type}  ${r.project}  ${r.status}
+`);
+        }
+      }
+    });
+  });
+  cmd.command("show").description("Show resource details").argument("<id>", "Resource display ID").option("--json", "Output JSON").action(async (id, opts) => {
+    await withBrain(async (svc) => {
+      const result = getResource(svc.db, id);
+      if (!result.ok) {
+        process.stderr.write(`Error: ${result.error.message}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else {
+        const r = result.data;
+        process.stdout.write(`ID:      ${r.id}
+`);
+        process.stdout.write(`Type:    ${r.type}
+`);
+        process.stdout.write(`Project: ${r.project}
+`);
+        process.stdout.write(`Status:  ${r.status}
+`);
+        process.stdout.write(`Data:    ${JSON.stringify(r.data)}
+`);
+        process.stdout.write(`Updated: ${r.updatedAt}
+`);
+      }
+    });
+  });
+  cmd.command("release").description("Release a workflow resource").argument("<id>", "Resource display ID").option("--json", "Output JSON").action(async (id, opts) => {
+    await withBrain(async (svc) => {
+      const result = await releaseResource(svc.db, svc.config, svc.embedder, id);
+      if (!result.ok) {
+        process.stderr.write(`Error: ${result.error.message}
+`);
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Released resource ${result.data.id}
+`);
+      }
+    });
+  });
+  return cmd;
+}
+
+// src/modules/workflow/commands/lifecycle.ts
+import { Command as Command46 } from "@commander-js/extra-typings";
+
+// src/modules/workflow/engine/gates.ts
+import { existsSync as existsSync25 } from "fs";
+import { execSync as execSync4 } from "child_process";
+var DEFAULT_TIMEOUT_MS = 3e4;
+async function evaluateTaskComplete(gate, db) {
+  const noteIds = db.getModuleNoteIds({ module: "pm", type: "task" });
+  if (noteIds.length === 0) return false;
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id === gate.target && meta.status === "done") {
+      return true;
+    }
+  }
+  return false;
+}
+function evaluateCliPass(gate) {
+  const command = gate.command ?? gate.target ?? "true";
+  const timeout = gate.timeout ?? DEFAULT_TIMEOUT_MS;
+  try {
+    execSync4(command, { timeout, stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function evaluateGate(gate, db, _config, taskMetadata) {
+  switch (gate.type) {
+    case "task-complete": {
+      const passed = await evaluateTaskComplete(gate, db);
+      return { gate, passed, reason: passed ? void 0 : `Task "${gate.target}" not done` };
+    }
+    case "file-exists": {
+      const passed = gate.target ? existsSync25(gate.target) : false;
+      return { gate, passed, reason: passed ? void 0 : `File "${gate.target}" not found` };
+    }
+    case "cli-pass": {
+      const passed = evaluateCliPass(gate);
+      return { gate, passed, reason: passed ? void 0 : `Command failed` };
+    }
+    case "human-approval":
+      return { gate, passed: false, reason: "Human approval required" };
+    case "approval": {
+      const passed = taskMetadata?.gate_status === "passed";
+      return {
+        gate,
+        passed,
+        reason: passed ? void 0 : "Approval gate not yet passed"
+      };
+    }
+    case "iteration": {
+      const max = gate.maxIterations ?? Infinity;
+      const count = taskMetadata?.iteration_count ?? 0;
+      const passed = count < max;
+      return {
+        gate,
+        passed,
+        reason: passed ? void 0 : `Iteration limit reached (${count}/${max})`
+      };
+    }
+    case "custom": {
+      const passed = evaluateCliPass(gate);
+      return { gate, passed, reason: passed ? void 0 : `Custom command failed` };
+    }
+  }
+}
+async function evaluateGates(gates, db, config, taskMetadata) {
+  if (gates.length === 0) {
+    return { allPassed: true, results: [] };
+  }
+  const results = [];
+  for (const gate of gates) {
+    const result = await evaluateGate(gate, db, config, taskMetadata);
+    results.push(result);
+  }
+  const allPassed = results.every((r) => r.passed);
+  return { allPassed, results };
+}
+
+// src/modules/workflow/engine/lifecycle.ts
+async function advanceWorkflow(db, config, instanceDisplayId) {
+  const instanceResult = getInstanceByDisplayId(db, instanceDisplayId);
+  if (!instanceResult.ok) return instanceResult;
+  const { note: instanceNote } = instanceResult.data;
+  const stepsResult = getInstanceStepStates(db, instanceDisplayId);
+  if (!stepsResult.ok) return stepsResult;
+  const { steps } = stepsResult.data;
+  if (steps.length === 0) {
+    return ok({ advanced: [], pruned: [], warnings: [], completed: true });
+  }
+  const definition = resolveDefinition(db, instanceNote);
+  if (!definition) {
+    return fail("DEFINITION_NOT_FOUND", "Could not resolve workflow definition");
+  }
+  const statusMap = new Map(steps.map((s) => [s.stepId, s.status]));
+  const taskDisplayIdMap = new Map(steps.map((s) => [s.stepId, s.taskDisplayId]));
+  const allStepIds = steps.map((s) => s.stepId);
+  const readySteps = buildReadySet(allStepIds, steps, definition);
+  const advanced = await findAdvancedSteps(
+    allStepIds,
+    statusMap,
+    taskDisplayIdMap,
+    definition,
+    readySteps,
+    db,
+    config
+  );
+  const { pruned, warnings } = pruneUnreachableSteps(
+    db,
+    allStepIds,
+    statusMap,
+    taskDisplayIdMap,
+    definition,
+    readySteps,
+    advanced
+  );
+  const prunedSet = new Set(pruned);
+  const completed = allStepIds.every((stepId) => {
+    const status = statusMap.get(stepId);
+    if (status === "pruned" || status === "cancelled" || prunedSet.has(stepId)) return true;
+    return readySteps.has(stepId);
+  });
+  if (completed) {
+    updateInstanceStatus(db, instanceNote.id, "completed");
+  }
+  return ok({ advanced, pruned, warnings, completed });
+}
+function buildReadySet(allStepIds, steps, definition) {
+  const ready = /* @__PURE__ */ new Set();
+  for (const s of steps) {
+    if (s.status === "done") {
+      ready.add(s.stepId);
+    }
+  }
+  const unconditionalEdges = definition.edges.filter((e) => !e.condition);
+  for (const stepId of allStepIds) {
+    const preds = getPredecessors(stepId, unconditionalEdges);
+    if (preds.length === 0) {
+      ready.add(stepId);
+    }
+  }
+  return ready;
+}
+async function findAdvancedSteps(allStepIds, statusMap, taskDisplayIdMap, definition, readySteps, db, config) {
+  const advanced = [];
+  const unconditional = definition.edges.filter((e) => !e.condition);
+  for (const stepId of allStepIds) {
+    const status = statusMap.get(stepId);
+    if (status === "done" || status === "pruned" || status === "cancelled") continue;
+    const preds = getPredecessors(stepId, unconditional);
+    if (preds.length === 0) continue;
+    const allPredsReady = preds.every((p) => readySteps.has(p));
+    if (!allPredsReady) continue;
+    const stepDef = definition.steps.find((s) => s.id === stepId);
+    const gates = stepDef?.gates ?? [];
+    if (gates.length > 0) {
+      const taskMeta = lookupTaskMetadata(db, taskDisplayIdMap.get(stepId));
+      const gateResult = await evaluateGates(gates, db, config, taskMeta);
+      if (!gateResult.allPassed) continue;
+    }
+    advanced.push(stepId);
+  }
+  return advanced;
+}
+function pruneUnreachableSteps(db, allStepIds, statusMap, taskDisplayIdMap, definition, readySteps, advanced) {
+  const pruned = [];
+  const warnings = [];
+  const unreachable = getUnreachableSteps([...readySteps], definition.edges, allStepIds);
+  const conditionalTargets = new Set(definition.edges.filter((e) => e.condition).map((e) => e.to));
+  for (const stepId of allStepIds) {
+    if (unreachable.includes(stepId)) continue;
+    if (!conditionalTargets.has(stepId)) continue;
+    const status = statusMap.get(stepId);
+    if (status === "done" || status === "pruned" || status === "cancelled") continue;
+    const incoming = definition.edges.filter((e) => e.to === stepId);
+    const allConditional = incoming.every((e) => e.condition);
+    if (!allConditional) continue;
+    const allSourcesReady = incoming.every((e) => readySteps.has(e.from));
+    if (allSourcesReady && !advanced.includes(stepId)) {
+      unreachable.push(stepId);
+    }
+  }
+  for (const stepId of unreachable) {
+    const status = statusMap.get(stepId);
+    const displayId = taskDisplayIdMap.get(stepId);
+    if (status === "pending" || status === "blocked") {
+      pruneTask(db, displayId);
+      pruned.push(stepId);
+    } else if (status === "claimed" || status === "in-progress") {
+      warnings.push(`Step "${stepId}" (${displayId}) should be pruned but is ${status}`);
+    }
+  }
+  return { pruned, warnings };
+}
+function lookupTaskMetadata(db, taskDisplayId) {
+  if (!taskDisplayId) return void 0;
+  const noteIds = db.getModuleNoteIds({ module: "pm", type: "task" });
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id === taskDisplayId) return meta;
+  }
+  return void 0;
+}
+function resolveDefinition(db, instanceNote) {
+  const relations = db.getRelationsFrom(instanceNote.id);
+  const instanceOfRel = relations.find((r) => r.type === "instance-of");
+  if (!instanceOfRel) return null;
+  const defNote = db.getNoteById(instanceOfRel.targetId);
+  if (!defNote) return null;
+  const chunk = db.getFirstChunkForNote(defNote.id);
+  if (!chunk) return null;
+  try {
+    const jsonMatch = chunk.content.match(/({[\s\S]*})/);
+    return JSON.parse(jsonMatch ? jsonMatch[1] : chunk.content);
+  } catch {
+    return null;
+  }
+}
+function pruneTask(db, targetDisplayId) {
+  const noteIds = db.getModuleNoteIds({ module: "pm", type: "task" });
+  const notes = db.getNotesByIds(noteIds);
+  for (const [, note] of notes) {
+    if (!note.metadata) continue;
+    const meta = JSON.parse(note.metadata);
+    if (meta.display_id === targetDisplayId) {
+      const updated = { ...meta, status: "pruned" };
+      db.upsertNote({ ...note, metadata: JSON.stringify(updated) });
+      break;
+    }
+  }
+}
+function updateInstanceStatus(db, noteId, status) {
+  const note = db.getNoteById(noteId);
+  if (!note?.metadata) return;
+  const meta = JSON.parse(note.metadata);
+  const updated = { ...meta, instance_status: status };
+  db.upsertNote({ ...note, metadata: JSON.stringify(updated) });
+}
+
+// src/modules/workflow/commands/lifecycle.ts
+function formatError3(error, json) {
+  if (json) {
+    return JSON.stringify({ error: true, code: error.code, message: error.message });
+  }
+  return `Error [${error.code}]: ${error.message}`;
+}
+function parseContextPairs(pairs) {
+  const context = {};
+  for (const pair of pairs) {
+    const eqIndex = pair.indexOf("=");
+    if (eqIndex === -1) {
+      throw new Error(`Invalid context pair: "${pair}" (expected key=value)`);
+    }
+    context[pair.slice(0, eqIndex)] = pair.slice(eqIndex + 1);
+  }
+  return context;
+}
+function createLifecycleCommands() {
+  const add = new Command46("add").description("Add a workflow instance").argument("<workflow-id>", "Workflow definition ID to instantiate").requiredOption("--project <prefix>", "Project prefix for the instance").option("--context <key=value...>", "Context key=value pairs", []).option("--json", "Output JSON").action(async (workflowId, opts) => {
+    let context;
+    try {
+      context = parseContextPairs(opts.context);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      if (opts.json) {
+        process.stderr.write(
+          JSON.stringify({ error: true, code: "INVALID_CONTEXT", message: msg }) + "\n"
+        );
+      } else {
+        process.stderr.write(`Error [INVALID_CONTEXT]: ${msg}
+`);
+      }
+      process.exitCode = 1;
+      return;
+    }
+    await withBrain(async (svc) => {
+      const result = await instantiateWorkflow(
+        svc.db,
+        svc.config,
+        svc.embedder,
+        workflowId,
+        opts.project,
+        context
+      );
+      if (!result.ok) {
+        process.stderr.write(formatError3(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const data = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Created workflow instance ${data.display_id}
+`);
+        process.stdout.write(`  Workflow: ${data.workflow_id} v${data.workflow_version}
+`);
+        process.stdout.write(`  Status: ${data.instance_status}
+`);
+      }
+    });
+  });
+  const expand = new Command46("expand").description("Expand a workflow instance into tasks").argument("<instance-id>", "Instance display ID to expand").option("--json", "Output JSON").action(async (instanceId, opts) => {
+    await withBrain(async (svc) => {
+      const result = await expandWorkflow(svc.db, svc.config, svc.embedder, instanceId);
+      if (!result.ok) {
+        process.stderr.write(formatError3(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const data = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+      } else {
+        process.stdout.write(
+          `Expanded: ${data.tasksCreated} tasks created, ${data.edges} edges
+`
+        );
+      }
+    });
+  });
+  const advance = new Command46("advance").description("Advance a workflow to the next step").argument("<instance-id>", "Instance display ID to advance").option("--json", "Output JSON").action(async (instanceId, opts) => {
+    await withBrain(async (svc) => {
+      const result = await advanceWorkflow(svc.db, svc.config, instanceId);
+      if (!result.ok) {
+        process.stderr.write(formatError3(result.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const data = result.data;
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+      } else {
+        const advancedStr = data.advanced.length > 0 ? data.advanced.join(", ") : "(none)";
+        const prunedStr = data.pruned.length > 0 ? data.pruned.join(", ") : "(none)";
+        process.stdout.write(`Advanced: ${advancedStr}
+`);
+        process.stdout.write(`Pruned: ${prunedStr}
+`);
+        if (data.warnings.length > 0) {
+          process.stdout.write(`Warnings: ${data.warnings.join("; ")}
+`);
+        }
+        process.stdout.write(`Completed: ${data.completed}
+`);
+      }
+    });
+  });
+  const next = new Command46("next").description("Advance a workflow and dispatch the next step(s)").argument("<instance-id>", "Instance display ID to advance").option("--json", "Output JSON").action(async (instanceId, opts) => {
+    await withBrain(async (svc) => {
+      const advResult = await advanceWorkflow(svc.db, svc.config, instanceId);
+      if (!advResult.ok) {
+        process.stderr.write(formatError3(advResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const { advanced, pruned, warnings, completed } = advResult.data;
+      const stepsResult = getInstanceStepStates(svc.db, instanceId);
+      const stepToTask = /* @__PURE__ */ new Map();
+      if (stepsResult.ok) {
+        for (const step of stepsResult.data.steps) {
+          stepToTask.set(step.stepId, step.taskDisplayId);
+        }
+      }
+      const instanceResult = getInstanceByDisplayId(svc.db, instanceId);
+      const stepDefs = /* @__PURE__ */ new Map();
+      if (instanceResult.ok) {
+        const workflowId = instanceResult.data.metadata.workflow_id;
+        const defResult = getWorkflowDefinition(svc.db, workflowId);
+        if (defResult.ok) {
+          for (const step of defResult.data.definition.steps) {
+            stepDefs.set(step.id, { template: step.template, mode: step.mode });
+          }
+        }
+      }
+      const dispatched = [];
+      const dispatchErrors = [];
+      for (const stepId of advanced) {
+        const taskId = stepToTask.get(stepId);
+        if (!taskId) continue;
+        const stepDef = stepDefs.get(stepId);
+        const templateName = stepDef?.template;
+        if (!templateName) continue;
+        const isAssisted = stepDef?.mode === "assisted";
+        const dispatchResult = await dispatchTemplate(
+          svc.db,
+          svc.config,
+          svc.embedder,
+          taskId,
+          templateName,
+          { claim: !isAssisted }
+        );
+        if (!dispatchResult.ok) {
+          dispatchErrors.push({
+            stepId,
+            error: dispatchResult.error.message
+          });
+          continue;
+        }
+        dispatched.push({ stepId, taskId, template: templateName });
+      }
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              advanced,
+              pruned,
+              warnings,
+              completed,
+              dispatched,
+              errors: dispatchErrors
+            },
+            null,
+            2
+          ) + "\n"
+        );
+      } else {
+        const advancedStr = advanced.length > 0 ? advanced.join(", ") : "(none)";
+        const prunedStr = pruned.length > 0 ? pruned.join(", ") : "(none)";
+        process.stdout.write(`Advanced: ${advancedStr}
+`);
+        process.stdout.write(`Pruned: ${prunedStr}
+`);
+        if (warnings.length > 0) {
+          process.stdout.write(`Warnings: ${warnings.join("; ")}
+`);
+        }
+        if (completed) {
+          process.stdout.write(`Workflow completed.
+`);
+        }
+        if (dispatched.length > 0) {
+          process.stdout.write(`
+Dispatched steps:
+`);
+          for (const d of dispatched) {
+            process.stdout.write(`  ${d.stepId} \u2192 ${d.taskId} (${d.template})
+`);
+          }
+        }
+        if (dispatchErrors.length > 0) {
+          process.stdout.write(`
+Dispatch errors:
+`);
+          for (const e of dispatchErrors) {
+            process.stdout.write(`  ${e.stepId}: ${e.error}
+`);
+          }
+        }
+        if (dispatched.length > 0) {
+          const firstTask = dispatched[0];
+          const rendered = await dispatchTemplate(
+            svc.db,
+            svc.config,
+            svc.embedder,
+            firstTask.taskId,
+            firstTask.template,
+            { dryRun: true }
+          );
+          if (rendered.ok) {
+            if (rendered.data.mode === "assisted") {
+              process.stdout.write(`
+## Assisted Step \u2014 Coordinator Instructions
+
+`);
+              process.stdout.write(
+                "This step requires interactive coordination. Use this prompt in your current session.\n"
+              );
+              process.stdout.write("Do NOT dispatch this to an autonomous agent.\n\n");
+              process.stdout.write("---\n\n");
+            } else {
+              process.stdout.write(`
+--- Dispatch prompt (${firstTask.stepId}) ---
+`);
+            }
+            process.stdout.write(rendered.data.rendered + "\n");
+          }
+        }
+      }
+    });
+  });
+  const run = new Command46("run").description("Instantiate, expand, and dispatch the first step(s) of a workflow").argument("<definition-id>", "Workflow definition ID to run").requiredOption("--project <prefix>", "Project prefix for the instance").option("--param <key=value...>", "Parameter key=value pairs", []).option("--template <name>", "Override dispatch template for first step(s)").option("--json", "Output JSON").action(async (definitionId, opts) => {
+    let params;
+    try {
+      params = parseContextPairs(opts.param);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(
+        formatError3({ code: "INVALID_PARAM", message: msg }, !!opts.json) + "\n"
+      );
+      process.exitCode = 1;
+      return;
+    }
+    await withBrain(async (svc) => {
+      const instResult = await instantiateWorkflow(
+        svc.db,
+        svc.config,
+        svc.embedder,
+        definitionId,
+        opts.project,
+        params
+      );
+      if (!instResult.ok) {
+        process.stderr.write(formatError3(instResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const instanceId = instResult.data.display_id;
+      const expandResult = await expandWorkflow(svc.db, svc.config, svc.embedder, instanceId);
+      if (!expandResult.ok) {
+        process.stderr.write(formatError3(expandResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const defResult = getWorkflowDefinition(svc.db, definitionId);
+      if (!defResult.ok) {
+        process.stderr.write(formatError3(defResult.error, !!opts.json) + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      const { definition } = defResult.data;
+      const unconditionalEdges = definition.edges.filter((e) => !e.condition);
+      const hasIncoming = new Set(unconditionalEdges.map((e) => e.to));
+      const entrySteps = definition.steps.filter((s) => !hasIncoming.has(s.id));
+      const stepsResult = getInstanceStepStates(svc.db, instanceId);
+      const stepToTask = /* @__PURE__ */ new Map();
+      if (stepsResult.ok) {
+        for (const step of stepsResult.data.steps) {
+          stepToTask.set(step.stepId, step.taskDisplayId);
+        }
+      }
+      const dispatched = [];
+      const dispatchErrors = [];
+      for (const step of entrySteps) {
+        const taskId = stepToTask.get(step.id);
+        if (!taskId) continue;
+        const templateName = opts.template ?? step.template;
+        if (!templateName) {
+          dispatchErrors.push({
+            stepId: step.id,
+            error: `No template specified (use --template or define template in step)`
+          });
+          continue;
+        }
+        const isAssisted = step.mode === "assisted";
+        const dispatchResult = await dispatchTemplate(
+          svc.db,
+          svc.config,
+          svc.embedder,
+          taskId,
+          templateName,
+          { claim: !isAssisted }
+        );
+        if (!dispatchResult.ok) {
+          dispatchErrors.push({
+            stepId: step.id,
+            error: dispatchResult.error.message
+          });
+          continue;
+        }
+        dispatched.push({ stepId: step.id, taskId, template: templateName });
+      }
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              instance_id: instanceId,
+              workflow_id: instResult.data.workflow_id,
+              workflow_version: instResult.data.workflow_version,
+              tasks_created: expandResult.data.tasksCreated,
+              edges: expandResult.data.edges,
+              dispatched,
+              errors: dispatchErrors
+            },
+            null,
+            2
+          ) + "\n"
+        );
+      } else {
+        process.stdout.write(`Instance: ${instanceId}
+`);
+        process.stdout.write(
+          `  Workflow: ${instResult.data.workflow_id} v${instResult.data.workflow_version}
+`
+        );
+        process.stdout.write(
+          `  Expanded: ${expandResult.data.tasksCreated} tasks, ${expandResult.data.edges} edges
+`
+        );
+        if (dispatched.length > 0) {
+          process.stdout.write(`
+Dispatched steps:
+`);
+          for (const d of dispatched) {
+            process.stdout.write(`  ${d.stepId} \u2192 ${d.taskId} (${d.template})
+`);
+          }
+        }
+        if (dispatchErrors.length > 0) {
+          process.stdout.write(`
+Dispatch errors:
+`);
+          for (const e of dispatchErrors) {
+            process.stdout.write(`  ${e.stepId}: ${e.error}
+`);
+          }
+        }
+        if (dispatched.length > 0) {
+          const firstTask = dispatched[0];
+          const rendered = await dispatchTemplate(
+            svc.db,
+            svc.config,
+            svc.embedder,
+            firstTask.taskId,
+            firstTask.template,
+            { dryRun: true }
+          );
+          if (rendered.ok) {
+            if (rendered.data.mode === "assisted") {
+              process.stdout.write(`
+## Assisted Step \u2014 Coordinator Instructions
+
+`);
+              process.stdout.write(
+                "This step requires interactive coordination. Use this prompt in your current session.\n"
+              );
+              process.stdout.write("Do NOT dispatch this to an autonomous agent.\n\n");
+              process.stdout.write("---\n\n");
+            } else {
+              process.stdout.write(`
+--- Dispatch prompt (${firstTask.stepId}) ---
+`);
+            }
+            process.stdout.write(rendered.data.rendered + "\n");
+          }
+        }
+      }
+    });
+  });
+  return [add, expand, advance, next, run];
+}
+
+// src/modules/workflow/commands/collapse.ts
+import { Command as Command47 } from "@commander-js/extra-typings";
+function createCollapseCommand() {
+  const cmd = new Command47("collapse").description("Collapse a completed workflow instance").argument("<instance-id>", "Workflow instance display ID").option("--json", "Output JSON").action(async (instanceId, opts) => {
+    await withBrain(async (svc) => {
+      const result = await collapseWorkflow(svc.db, svc.config, svc.embedder, instanceId);
+      if (!result.ok) {
+        const msg = opts.json ? JSON.stringify(result.error, null, 2) : `Error: ${result.error.message}`;
+        process.stderr.write(msg + "\n");
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result.data, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Collapsed workflow instance
+`);
+        process.stdout.write(`  Summary: ${result.data.summaryNoteId}
+`);
+        process.stdout.write(`  Tasks archived: ${result.data.tasksArchived}
+`);
+      }
+    });
+  });
+  return cmd;
+}
+
+// src/modules/workflow/index.ts
+var workflowModule = {
+  name: "workflow",
+  version: "1.0.0",
+  description: "Workflow definition, instantiation, and lifecycle management",
+  register(ctx) {
+    ctx.registerNoteType({
+      name: "workflow",
+      description: "Workflow definition with steps and edges",
+      tier: "slow",
+      schema: {
+        type: "object",
+        properties: {
+          display_id: { type: "string", description: "Display identifier" },
+          name: { type: "string", description: "Workflow name" },
+          version: { type: "number", description: "Workflow version number" },
+          registration_status: {
+            type: "string",
+            enum: ["registered", "draft", "archived"],
+            description: "Registration status"
+          },
+          step_count: { type: "number", description: "Number of steps in the workflow" },
+          edge_count: { type: "number", description: "Number of edges in the workflow" }
+        },
+        required: ["name", "version", "registration_status"]
+      }
+    });
+    ctx.registerNoteType({
+      name: "resource",
+      description: "Resource bound to a workflow instance",
+      tier: "fast",
+      schema: {
+        type: "object",
+        properties: {
+          display_id: { type: "string", description: "Display identifier" },
+          resource_type: { type: "string", description: "Type of resource" },
+          project: { type: "string", description: "Associated project prefix" },
+          status: {
+            type: "string",
+            enum: ["active", "released", "expired"],
+            description: "Resource status"
+          },
+          data: { type: "string", description: "Resource data payload" }
+        },
+        required: ["resource_type", "status"]
+      }
+    });
+    ctx.registerRelationType({
+      name: "instance-of",
+      description: "Workflow instance is an instance of a workflow definition"
+    });
+    ctx.registerRelationType({
+      name: "expands-to",
+      description: "Workflow step expands to sub-steps"
+    });
+    ctx.registerRelationType({
+      name: "iteration-of",
+      description: "Workflow instance is an iteration of a previous instance"
+    });
+    ctx.registerExtractionStrategy({ shouldExtract: () => false });
+    ctx.registerFilter({ visibility: "private" });
+    const wfCmd = createWorkflowCommand();
+    wfCmd.addCommand(createResourceCommand());
+    for (const cmd of createLifecycleCommands()) {
+      wfCmd.addCommand(cmd);
+    }
+    wfCmd.addCommand(createCollapseCommand());
+    ctx.registerCommand(wfCmd);
+  }
+};
+
+// src/commands/instances.ts
+import { Command as Command48 } from "@commander-js/extra-typings";
+var listSubcommand = new Command48("list").description("List all known brain instances").option("--json", "output as JSON").option("--prune", "remove stale entries (paths that no longer exist)").action((opts) => {
   const globalDir = GLOBAL_BRAIN_DIR;
   if (opts.prune) {
     const pruned = pruneStaleInstances(globalDir);
@@ -11901,10 +14150,10 @@ Local instances (${instances.length}):
     }
   }
 });
-var instancesCommand = new Command45("instances").description("Manage brain instances").addCommand(listSubcommand);
+var instancesCommand = new Command48("instances").description("Manage brain instances").addCommand(listSubcommand);
 
 // src/cli.ts
-var program = new Command46().name("brain").description("Developer second brain with hybrid RAG search").version(createRequire(import.meta.url)("../package.json").version).option("--global", "Force use of global brain instance").option("--instance <path>", "Use specific brain instance at path");
+var program = new Command49().name("brain").description("Developer second brain with hybrid RAG search").version(createRequire(import.meta.url)("../package.json").version).option("--global", "Force use of global brain instance").option("--instance <path>", "Use specific brain instance at path");
 program.addCommand(initCommand);
 program.addCommand(indexCommand);
 program.addCommand(searchCommand);
@@ -11931,7 +14180,7 @@ program.addCommand(resetCommand);
 program.addCommand(notesCommand);
 program.addCommand(instancesCommand);
 async function main() {
-  const { registry } = await loadModules({ modules: [pmModule] });
+  const { registry } = await loadModules({ modules: [pmModule, workflowModule] });
   for (const { command } of registry.getCommands()) {
     program.addCommand(command);
   }