trekoon 0.2.6 → 0.2.8

package/src/commands/help.ts

@@ -21,6 +21,7 @@ const ROOT_HELP = [
   "  init         Initialize repo-shared .trekoon storage and DB",
   "  quickstart   Show shared-storage bootstrap + AI execution loop",
   "  wipe         Remove repo-shared Trekoon state (requires --yes)",
+  "  board        Local board asset and browser commands",
   "  epic         Epic lifecycle commands",
   "  task         Task lifecycle commands",
   "  subtask      Subtask lifecycle commands",
@@ -83,6 +84,25 @@ const WIPE_HELP = [
   "  trekoon wipe --yes",
 ].join("\n");
 
+const BOARD_HELP = [
+  "Usage: trekoon board <open|update>",
+  "",
+  "Subcommands:",
+  "  open",
+  "      Ensure board assets are installed, start a 127.0.0.1 board server,",
+  "      and launch the browser. Machine output includes server URL, fallback URL,",
+  "      and launch metadata.",
+  "  update",
+  "      Refresh board runtime assets only. Does not start the server or open a browser.",
+  "",
+  "Environment overrides:",
+  "  TREKOON_BOARD_ASSET_ROOT  Optional asset source override for tests and local development.",
+  "",
+  "Examples:",
+  "  trekoon board open",
+  "  trekoon --json board update",
+].join("\n");
+
 const EPIC_HELP = [
   "Usage: trekoon epic <create|expand|list|show|search|replace|update|delete> [options]",
   "",
@@ -131,14 +151,20 @@ const EPIC_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon epic update --all --append <text> [--status <status>]",
+  "    trekoon epic update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Descendant cascade mode:",
+  "    trekoon epic update <epic-id> --all --status done|todo",
+  "    - cascades atomically through descendant tasks and subtasks",
+  "    - blocked descendants abort the whole update",
+  "    - cascade mode supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const TASK_HELP = [
-  "Usage: trekoon task <create|create-many|list|show|ready|next|search|replace|update|delete> [options]",
+  "Usage: trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete> [options]",
   "",
   "Create-many behavior:",
   "  trekoon task create-many --epic <epic-id> --task <spec> [--task <spec> ...]",
@@ -188,10 +214,16 @@ const TASK_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon task update --all --append <text> [--status <status>]",
+  "    trekoon task update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Descendant cascade mode:",
+  "    trekoon task update <task-id> --all --status done|todo",
+  "    - cascades atomically through descendant subtasks",
+  "    - blocked descendants abort the whole update",
+  "    - cascade mode supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const SUBTASK_HELP = [
@@ -228,10 +260,16 @@ const SUBTASK_HELP = [
   "    - --preview and --apply are mutually exclusive",
   "",
   "Update behavior:",
-  "  Bulk target flags:",
-  "    --all | --ids <csv>",
-  "  Bulk fields:",
-  "    --append <text> and/or --status <status>",
+  "  Repo-wide bulk mode:",
+  "    trekoon subtask update --all --append <text> [--status <status>]",
+  "    trekoon subtask update --ids <csv> --append <text> [--status <status>]",
+  "    - preserves existing per-row bulk behavior; not one atomic multi-row update",
+  "  Positional-id cascade syntax:",
+  "    trekoon subtask update <subtask-id> --all --status done|todo",
+  "    - accepted for contract consistency",
+  "    - behaves like a normal single-subtask status update",
+  "    - positional id + --all supports only --status done|todo",
+  "    - do not combine positional id + --all with --ids, --append, --description, or --title",
 ].join("\n");
 
 const DEP_HELP = [
@@ -376,6 +414,7 @@ const SKILLS_HELP = [
 
 const COMMAND_HELP: Record<string, string> = {
   init: INIT_HELP,
+  board: BOARD_HELP,
   quickstart: QUICKSTART_HELP,
   session: SESSION_HELP,
   wipe: WIPE_HELP,

package/src/commands/init.ts

@@ -1,5 +1,7 @@
 import { unexpectedFailureResult } from "./error-utils";
 
+import { ensureBoardInstalled } from "../board/install";
+import { BoardInstallError } from "../board/types";
 import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -80,6 +82,11 @@ export async function runInit(context: CliContext): Promise<CliResult> {
   try {
     database = openTrekoonDatabase(context.cwd);
     const diagnostics = database.diagnostics;
+    const bundledAssetRoot: string | undefined = process.env.TREKOON_BOARD_ASSET_ROOT;
+    const board = ensureBoardInstalled({
+      workingDirectory: context.cwd,
+      ...(bundledAssetRoot === undefined ? {} : { bundledAssetRoot }),
+    });
     const humanLines: string[] = [
       "Trekoon initialized.",
       `Storage mode: ${diagnostics.storageMode}`,
@@ -87,6 +94,8 @@ export async function runInit(context: CliContext): Promise<CliResult> {
       `Shared storage root: ${diagnostics.sharedStorageRoot}`,
       `Storage directory: ${database.paths.storageDir}`,
       `Database file: ${database.paths.databaseFile}`,
+      `Board assets: ${board.action}`,
+      `Board runtime root: ${board.paths.runtimeRoot}`,
       ...buildRecoverySummary(database),
     ];
 
@@ -101,6 +110,11 @@ export async function runInit(context: CliContext): Promise<CliResult> {
         sharedStorageRoot: diagnostics.sharedStorageRoot,
         storageDir: database.paths.storageDir,
         databaseFile: database.paths.databaseFile,
+        board: {
+          action: board.action,
+          paths: board.paths,
+          manifest: board.manifest,
+        },
         legacyStateDetected: diagnostics.legacyStateDetected,
         recoveryRequired: diagnostics.recoveryRequired,
         recoveryStatus: diagnostics.recoveryStatus,
@@ -120,6 +134,21 @@ export async function runInit(context: CliContext): Promise<CliResult> {
       }
     }
 
+    if (error instanceof BoardInstallError) {
+      return failResult({
+        command: "init",
+        human: error.message,
+        data: {
+          code: error.code,
+          ...error.details,
+        },
+        error: {
+          code: error.code,
+          message: error.message,
+        },
+      });
+    }
+
     return unexpectedFailureResult(error, {
       command: "init",
       human: "Unexpected init command failure",

package/src/commands/subtask.ts

@@ -33,9 +33,13 @@ function formatSubtask(subtask: SubtaskRecord): string {
 const VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_SUBTASK_LIST_LIMIT = 10;
 const DEFAULT_OPEN_SUBTASK_STATUSES = ["in_progress", "in-progress", "todo"] as const;
+const CREATE_OPTIONS = ["task", "t", "title", "description", "d", "status", "s"] as const;
+const LIST_OPTIONS = ["task", "t", "status", "s", "limit", "l", "cursor", "all", "view"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["task", "t", "subtask"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -168,6 +172,25 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} cascade mode requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} cascade mode requires status-only done/todo input`,
+    },
+  });
+}
+
 function formatSubtaskListTable(subtasks: readonly SubtaskRecord[]): string {
   return formatHumanTable(
     ["ID", "TASK", "TITLE", "STATUS"],
@@ -359,6 +382,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
 
     switch (subcommand) {
       case "create": {
+        const createUnknownOption = findUnknownOption(parsed, CREATE_OPTIONS);
+        if (createUnknownOption !== undefined) {
+          return unknownOption("subtask.create", createUnknownOption, CREATE_OPTIONS);
+        }
+
+        const unexpectedCreatePositionals = readUnexpectedPositionals(parsed, 3);
+        if (unexpectedCreatePositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.create", unexpectedCreatePositionals);
+        }
+
         const missingCreateOption =
           readMissingOptionValue(parsed.missingOptionValues, "task", "t") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
@@ -447,6 +480,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("subtask.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
@@ -731,6 +774,16 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("subtask.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("subtask.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -773,7 +826,31 @@ export async function runSubtask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && subtaskId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("subtask.update", "Subtask", {
+              id: subtaskId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const subtask = mutations.updateSubtask(subtaskId, { status });
+
+          return okResult({
+            command: "subtask.update",
+            human: `Updated subtask ${formatSubtask(subtask)}`,
+            data: { subtask },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && subtaskId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (subtaskId.length > 0) {
             return failResult({

package/src/commands/task.ts

@@ -20,19 +20,14 @@ import { unexpectedFailureResult } from "./error-utils";
 import {
   buildTaskReadiness,
   DEFAULT_OPEN_TASK_STATUSES,
-  type DependencyBlocker,
-  READY_REASON_BLOCKED,
-  READY_REASON_READY,
-  type ReadyReason,
   taskStatusPriority,
   type TaskReadinessResult,
-  type TaskReadinessSummary,
   type TaskReadyCandidate,
 } from "./task-readiness";
 
 import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
-import { type CompactBatchResultContract, type CompactTaskSpec, type SearchEntityMatch, type TaskRecord } from "../domain/types";
+import { type CompactBatchResultContract, type CompactTaskSpec, type SearchEntityMatch, type StatusCascadePlan, type TaskRecord } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -45,9 +40,14 @@ function formatTask(task: TaskRecord): string {
 const VIEW_MODES = ["table", "compact", "tree", "detail"] as const;
 const LIST_VIEW_MODES = ["table", "compact"] as const;
 const DEFAULT_TASK_LIST_LIMIT = 10;
+const CREATE_OPTIONS = ["epic", "e", "title", "t", "description", "d", "status", "s"] as const;
+const LIST_OPTIONS = ["epic", "e", "status", "s", "limit", "l", "cursor", "all", "view"] as const;
+const SHOW_OPTIONS = ["view", "all"] as const;
 const SEARCH_OPTIONS = ["fields", "preview"] as const;
 const REPLACE_OPTIONS = ["search", "replace", "fields", "preview", "apply"] as const;
 const CREATE_MANY_OPTIONS = ["epic", "e", "task"] as const;
+const UPDATE_OPTIONS = ["all", "ids", "append", "description", "d", "status", "s", "title", "t"] as const;
+const STATUS_CASCADE_UPDATE_STATUSES = ["done", "todo"] as const;
 
 function parseIdsOption(rawIds: string | undefined): string[] {
   if (rawIds === undefined) {
@@ -185,6 +185,44 @@ function appendLine(existing: string, line: string): string {
   return existing.length > 0 ? `${existing}\n${line}` : line;
 }
 
+function isStatusCascadeUpdateStatus(status: string | undefined): status is (typeof STATUS_CASCADE_UPDATE_STATUSES)[number] {
+  return status === "done" || status === "todo";
+}
+
+function buildStatusCascadeData(plan: StatusCascadePlan): Record<string, unknown> {
+  return {
+    mode: "descendants",
+    root: {
+      kind: plan.rootKind,
+      id: plan.rootId,
+    },
+    targetStatus: plan.targetStatus,
+    atomic: plan.atomic,
+    changedIds: plan.changedIds,
+    unchangedIds: plan.unchangedIds,
+    counts: plan.counts,
+  };
+}
+
+function formatStatusCascadeHuman(entityLabel: string, plan: StatusCascadePlan): string {
+  return `Cascade updated ${entityLabel} ${plan.rootId} to ${plan.targetStatus} (${plan.counts.changed} changed, ${plan.counts.unchanged} unchanged; tasks=${plan.counts.changedTasks}, subtasks=${plan.counts.changedSubtasks})`;
+}
+
+function failCascadeStatusUpdate(command: string, entityLabel: string, data: Record<string, unknown>): CliResult {
+  return failResult({
+    command,
+    human: `${entityLabel} descendant cascade requires --status done or --status todo and does not support --append, --description, or --title.`,
+    data: {
+      code: "invalid_input",
+      ...data,
+    },
+    error: {
+      code: "invalid_input",
+      message: `${entityLabel} descendant cascade requires status-only done/todo mode`,
+    },
+  });
+}
+
 function formatTaskListTable(tasks: readonly TaskRecord[]): string {
   const rows = tasks.map((task) => [task.id, task.epicId, task.title, task.status]);
   return formatHumanTable(["ID", "EPIC", "TITLE", "STATUS"], rows, { wrapColumns: [2] });
@@ -426,6 +464,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
 
     switch (subcommand) {
       case "create": {
+        const createUnknownOption = findUnknownOption(parsed, CREATE_OPTIONS);
+        if (createUnknownOption !== undefined) {
+          return unknownOption("task.create", createUnknownOption, CREATE_OPTIONS);
+        }
+
+        const unexpectedCreatePositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedCreatePositionals.length > 0) {
+          return failUnexpectedPositionals("task.create", unexpectedCreatePositionals);
+        }
+
         const missingCreateOption =
           readMissingOptionValue(parsed.missingOptionValues, "epic", "e") ??
           readMissingOptionValue(parsed.missingOptionValues, "description", "d") ??
@@ -502,6 +550,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "list": {
+        const listUnknownOption = findUnknownOption(parsed, LIST_OPTIONS);
+        if (listUnknownOption !== undefined) {
+          return unknownOption("task.list", listUnknownOption, LIST_OPTIONS);
+        }
+
+        const unexpectedListPositionals = readUnexpectedPositionals(parsed, 1);
+        if (unexpectedListPositionals.length > 0) {
+          return failUnexpectedPositionals("task.list", unexpectedListPositionals);
+        }
+
         const missingListOption =
           readMissingOptionValue(parsed.missingOptionValues, "view") ??
           readMissingOptionValue(parsed.missingOptionValues, "status", "s") ??
@@ -660,6 +718,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "show": {
+        const showUnknownOption = findUnknownOption(parsed, SHOW_OPTIONS);
+        if (showUnknownOption !== undefined) {
+          return unknownOption("task.show", showUnknownOption, SHOW_OPTIONS);
+        }
+
+        const unexpectedShowPositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedShowPositionals.length > 0) {
+          return failUnexpectedPositionals("task.show", unexpectedShowPositionals);
+        }
+
         const missingShowOption = readMissingOptionValue(parsed.missingOptionValues, "view");
         if (missingShowOption !== undefined) {
           return failMissingOptionValue("task.show", missingShowOption);
@@ -989,6 +1057,16 @@ export async function runTask(context: CliContext): Promise<CliResult> {
         });
       }
       case "update": {
+        const updateUnknownOption = findUnknownOption(parsed, UPDATE_OPTIONS);
+        if (updateUnknownOption !== undefined) {
+          return unknownOption("task.update", updateUnknownOption, UPDATE_OPTIONS);
+        }
+
+        const unexpectedUpdatePositionals = readUnexpectedPositionals(parsed, 2);
+        if (unexpectedUpdatePositionals.length > 0) {
+          return failUnexpectedPositionals("task.update", unexpectedUpdatePositionals);
+        }
+
         const missingUpdateOption =
           readMissingOptionValue(parsed.missingOptionValues, "ids") ??
           readMissingOptionValue(parsed.missingOptionValues, "append") ??
@@ -1031,7 +1109,35 @@ export async function runTask(context: CliContext): Promise<CliResult> {
           });
         }
 
-        const hasBulkTarget = updateAll || ids.length > 0;
+        const cascadeMode = updateAll && taskId.length > 0;
+        if (cascadeMode) {
+          if (title !== undefined || description !== undefined || append !== undefined || !isStatusCascadeUpdateStatus(status)) {
+            return failCascadeStatusUpdate("task.update", "Task", {
+              id: taskId,
+              status,
+              allowedStatuses: [...STATUS_CASCADE_UPDATE_STATUSES],
+              fields: {
+                title: title !== undefined,
+                description: description !== undefined,
+                append: append !== undefined,
+              },
+            });
+          }
+
+          const cascade = mutations.updateTaskStatusCascade(taskId, status);
+          const task = domain.getTaskOrThrow(taskId);
+
+          return okResult({
+            command: "task.update",
+            human: formatStatusCascadeHuman("task", cascade),
+            data: {
+              task,
+              cascade: buildStatusCascadeData(cascade),
+            },
+          });
+        }
+
+        const hasBulkTarget = (updateAll && taskId.length === 0) || ids.length > 0;
         if (hasBulkTarget) {
           if (taskId.length > 0) {
             return failResult({

package/src/domain/mutation-service.ts

@@ -18,8 +18,11 @@ import {
   type SearchField,
   type SearchNode,
   type SearchSummary,
+  type StatusCascadeBlocker,
+  type StatusCascadePlan,
   type SubtaskRecord,
   type TaskRecord,
+  DomainError,
 } from "./types";
 
 function countMatches(value: string, searchText: string): number {
@@ -187,6 +190,15 @@ export class MutationService {
     })();
   }
 
+  updateEpicStatusCascade(id: string, status: string): StatusCascadePlan {
+    return this.#db.transaction((): StatusCascadePlan => {
+      const plan = this.#domain.planStatusCascade("epic", id, status);
+      this.#assertCascadeNotBlocked(plan);
+      this.#applyStatusCascadePlan(plan);
+      return plan;
+    })();
+  }
+
   deleteEpic(id: string): void {
     this.#db.transaction((): void => {
       this.#domain.deleteEpic(id);
@@ -277,6 +289,15 @@ export class MutationService {
     })();
   }
 
+  updateTaskStatusCascade(id: string, status: string): StatusCascadePlan {
+    return this.#db.transaction((): StatusCascadePlan => {
+      const plan = this.#domain.planStatusCascade("task", id, status);
+      this.#assertCascadeNotBlocked(plan);
+      this.#applyStatusCascadePlan(plan);
+      return plan;
+    })();
+  }
+
   deleteTask(id: string): void {
     this.#db.transaction((): void => {
       this.#domain.deleteTask(id);
@@ -381,6 +402,45 @@ export class MutationService {
     })();
   }
 
+  describeError(error: unknown): string | undefined {
+    if (!(error instanceof DomainError) || error.code !== "dependency_blocked") {
+      return undefined;
+    }
+
+    const details = error.details as Record<string, unknown> | undefined;
+    const unresolvedDependencies = Array.isArray(details?.unresolvedDependencies)
+      ? details.unresolvedDependencies
+      : [];
+    if (unresolvedDependencies.length > 0) {
+      const blockers = unresolvedDependencies
+        .map((dependency) => {
+          if (!dependency || typeof dependency !== "object") {
+            return null;
+          }
+
+          const id = typeof dependency.id === "string" ? dependency.id : "unknown";
+          const kind = typeof dependency.kind === "string" ? dependency.kind : "dependency";
+          const status = typeof dependency.status === "string" ? dependency.status : "unknown";
+          return `${kind} ${id} is still ${status}`;
+        })
+        .filter((value): value is string => value !== null);
+
+      if (blockers.length > 0) {
+        return `Resolve dependencies first: ${blockers.join("; ")}.`;
+      }
+    }
+
+    const cascadeBlockers = Array.isArray(details?.blockers) ? details.blockers as StatusCascadeBlocker[] : [];
+    if (cascadeBlockers.length > 0) {
+      const blockers = cascadeBlockers.map((blocker) =>
+        `${blocker.sourceKind} ${blocker.sourceId} is blocked by ${blocker.dependsOnKind} ${blocker.dependsOnId} (${blocker.dependsOnStatus})`
+      );
+      return `Resolve dependencies first: ${blockers.join("; ")}.`;
+    }
+
+    return undefined;
+  }
+
   previewEpicReplacement(
     epicId: string,
     searchText: string,
@@ -458,6 +518,62 @@ export class MutationService {
     return this.#buildScopeReplacementResult(nodes, searchText, replacementText, fields);
   }
 
+  #assertCascadeNotBlocked(plan: StatusCascadePlan): void {
+    if (plan.blockers.length === 0) {
+      return;
+    }
+
+    throw new DomainError({
+      code: "dependency_blocked",
+      message: `${plan.rootKind} cascade cannot transition to ${plan.targetStatus} while dependencies are unresolved`,
+      details: {
+        entity: plan.rootKind,
+        id: plan.rootId,
+        status: plan.targetStatus,
+        atomic: plan.atomic,
+        changedIds: plan.changedIds,
+        unchangedIds: plan.unchangedIds,
+        blockerCount: plan.blockers.length,
+        blockers: plan.blockers,
+        blockedNodeIds: [...new Set(plan.blockers.map((blocker) => blocker.sourceId))],
+        unresolvedDependencyIds: [...new Set(plan.blockers.map((blocker) => blocker.dependsOnId))],
+      },
+    });
+  }
+
+  #applyStatusCascadePlan(plan: StatusCascadePlan): void {
+    for (const change of plan.orderedChanges) {
+      if (change.kind === "epic") {
+        const epic = this.#domain.updateEpic(change.id, { status: change.nextStatus });
+        this.#appendEntityEvent("epic", epic.id, ENTITY_OPERATIONS.epic.updated, {
+          title: epic.title,
+          description: epic.description,
+          status: epic.status,
+        });
+        continue;
+      }
+
+      if (change.kind === "task") {
+        const task = this.#domain.updateTask(change.id, { status: change.nextStatus });
+        this.#appendEntityEvent("task", task.id, ENTITY_OPERATIONS.task.updated, {
+          epic_id: task.epicId,
+          title: task.title,
+          description: task.description,
+          status: task.status,
+        });
+        continue;
+      }
+
+      const subtask = this.#domain.updateSubtask(change.id, { status: change.nextStatus });
+      this.#appendEntityEvent("subtask", subtask.id, ENTITY_OPERATIONS.subtask.updated, {
+        task_id: subtask.taskId,
+        title: subtask.title,
+        description: subtask.description,
+        status: subtask.status,
+      });
+    }
+  }
+
   #applyScopeReplacement(
     nodes: readonly SearchNode[],
     searchText: string,