@mrclrchtr/supi-flow 0.10.1 → 0.11.0

package/extensions/tools/flow-tools.ts

@@ -1,9 +1,19 @@
-import { dirname, join } from "node:path";
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { type Static, Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { tndm, tndmJson } from "../cli.js";
 
+type FlowTaskListEntry = {
+  number?: number;
+  title?: string;
+  status?: string;
+  files?: string[];
+  verification?: string;
+  notes?: string;
+  detail_path?: string;
+};
+
 // ─── supi_flow_start ───────────────────────────────────────────
 
 export const supiFlowStartParams = Type.Object({
@@ -77,62 +87,31 @@ export const supiFlowPlanParams = Type.Object({
   ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
   plan_content: Type.String({
     description:
-      "Markdown plan content with tasks numbered as '**Task {N}**'.\n\n- [ ] **Task 1**: Description\n  - File: path/to/file\n  - Verification: command",
+      "Approved overview / plan markdown to store in the ticket's canonical content.md. This may contain zero tasks; task authoring happens separately in state.toml.",
   }),
-  append: Type.Optional(
-    Type.Boolean({
-      description:
-        "If true, append to existing content. If false (default), replace content entirely.",
-    }),
-  ),
 });
 
 export type FlowPlanParams = Static<typeof supiFlowPlanParams>;
 
 export async function executeFlowPlan(params: FlowPlanParams) {
-  // Create a "plan" document and get its path
-  const docResult = await tndmJson<{ path: string }>([
-    "ticket",
-    "doc",
-    "create",
-    params.ticket_id,
-    "plan",
-  ]);
-  const docPath = docResult.path;
-
-  let content = params.plan_content;
-
-  if (params.append) {
-    try {
-      const existingContent = readFileSync(docPath, "utf-8");
-      if (existingContent) {
-        content = existingContent + "\n\n" + content;
-      }
-    } catch {
-      // If reading fails, just use the new content
-    }
+  if (!params.plan_content.trim()) {
+    throw new Error("supi_flow_plan: plan_content must not be blank");
   }
 
-  // Write the plan content to the document file
-  writeFileSync(docPath, content, "utf-8");
-
-  // Sync fingerprints and update tags
-  await tndm(["ticket", "sync", params.ticket_id]);
-
-  // Replace any flow-state tag with flow:planned — remove all possible flow-state tags
-  // first, then add flow:planned, to work correctly regardless of the ticket's current
-  // flow state (brainstorm, planned, applying, or done).
   await tndm([
     "ticket",
     "update",
     params.ticket_id,
-    "--remove-tags",
-    "flow:brainstorm,flow:planned,flow:applying,flow:done",
+    "--content",
+    params.plan_content,
   ]);
+
   await tndm([
     "ticket",
     "update",
     params.ticket_id,
+    "--remove-tags",
+    "flow:brainstorm,flow:planned,flow:applying,flow:done",
     "--add-tags",
     "flow:planned",
   ]);
@@ -141,157 +120,396 @@ export async function executeFlowPlan(params: FlowPlanParams) {
     content: [
       {
         type: "text" as const,
-        text: `Plan stored in ${params.ticket_id} (${docPath}). Tags updated to flow:planned.`,
+        text: `Overview stored in content.md for ticket ${params.ticket_id}. Tags updated to flow:planned.`,
       },
     ],
-    details: { action: "flow_plan", ticketId: params.ticket_id, tags: "flow:planned", path: docPath },
+    details: {
+      action: "flow_plan",
+      ticketId: params.ticket_id,
+      tags: "flow:planned",
+      contentStored: true,
+    },
   };
 }
 
-// ─── supi_flow_complete_task ───────────────────────────────────
+// ─── supi_flow_apply ───────────────────────────────────────────
 
-export const supiFlowCompleteTaskParams = Type.Object({
+export const supiFlowApplyParams = Type.Object({
   ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
-  task_number: Type.Number({
-    description: "1-based task number to mark as complete (e.g. 1, 2, 3)",
-  }),
 });
 
-export type FlowCompleteTaskParams = Static<typeof supiFlowCompleteTaskParams>;
+export type FlowApplyParams = Static<typeof supiFlowApplyParams>;
 
-type CheckTaskResult =
-  | { kind: "unchecked"; updatedContent: string }
-  | { kind: "already_checked" }
-  | { kind: "not_found" };
+export async function executeFlowApply(params: FlowApplyParams) {
+  const ticket = await loadTicket(params.ticket_id);
+  const status = extractTicketStatus(ticket);
+  const tags = extractTicketTags(ticket);
 
-function checkTask(content: string, taskNumber: number): CheckTaskResult {
-  // Match a task line like "- [ ] **Task N:**" or "  - [ ] **Task N:**"
-  const lines = content.split("\n");
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const trimmed = line.trimStart();
+  if (status === "done" || tags.includes("flow:done")) {
+    throw new Error(`supi_flow_apply: ticket ${params.ticket_id} is already closed`);
+  }
 
-    const uncheckedMatch = trimmed.match(
-      new RegExp(`^- \\[ \\] \\*\\*Task ${taskNumber}\\*\\*:`),
+  if (!tags.includes("flow:planned") && !tags.includes("flow:applying")) {
+    throw new Error(
+      `supi_flow_apply: ticket ${params.ticket_id} must be in flow:planned or flow:applying`,
     );
-    if (uncheckedMatch) {
-      // Replace the [ ] with [x] in the trimmed version
-      const indent = line.slice(0, line.length - trimmed.length);
-      lines[i] = indent + trimmed.replace("- [ ]", "- [x]");
-      return { kind: "unchecked", updatedContent: lines.join("\n") };
-    }
-
-    const checkedMatch = trimmed.match(
-      new RegExp(`^- \\[x\\] \\*\\*Task ${taskNumber}\\*\\*:`),
+  }
+  if (
+    tags.includes("flow:applying") &&
+    status !== "in_progress" &&
+    status !== "blocked"
+  ) {
+    throw new Error(
+      `supi_flow_apply: ticket ${params.ticket_id} must have status in_progress or blocked when tagged flow:applying`,
     );
-    if (checkedMatch) {
-      return { kind: "already_checked" };
-    }
   }
-  return { kind: "not_found" };
-}
 
-export async function executeFlowCompleteTask(params: FlowCompleteTaskParams) {
-  const showResult = await tndmJson<{
-    id: string;
-    content_path?: string;
-    documents?: Array<{ name: string; path: string }>;
-  }>([
-    "ticket",
-    "show",
+  const overview = readRequiredTicketContent(
     params.ticket_id,
-  ]);
+    extractContentPath(ticket),
+    "supi_flow_apply",
+  );
+  const tasks = await loadTaskList(params.ticket_id);
 
-  const contentPath = showResult.content_path;
-  if (!contentPath) {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: `No content path found in ticket ${params.ticket_id}.`,
-        },
-      ],
-      details: { action: "flow_complete_task", ticketId: params.ticket_id, error: "No content path" },
-    };
+  if (tasks.length === 0) {
+    throw new Error(`supi_flow_apply: ticket ${params.ticket_id} has no structured tasks`);
   }
 
-  const planDocument = showResult.documents?.find((document) => document.name === "plan");
-  if (!planDocument) {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: `No plan file is registered in ticket ${params.ticket_id}.`,
-        },
-      ],
-      details: {
-        action: "flow_complete_task",
-        ticketId: params.ticket_id,
-        error: "No plan file",
+  let transitioned = false;
+  let applyStatus = status ?? "in_progress";
+
+  if (tags.includes("flow:planned")) {
+    await tndm([
+      "ticket",
+      "update",
+      params.ticket_id,
+      "--status",
+      "in_progress",
+      "--remove-tags",
+      "flow:planned",
+      "--add-tags",
+      "flow:applying",
+    ]);
+    transitioned = true;
+    applyStatus = "in_progress";
+  }
+
+  const contentPath = extractContentPath(ticket) ?? "";
+  const taskCount = tasks.length;
+  const transitionText = transitioned
+    ? `Ticket ${params.ticket_id} moved to flow:applying.`
+    : applyStatus === "blocked"
+      ? `Ticket ${params.ticket_id} is already in flow:applying and currently blocked.`
+      : `Ticket ${params.ticket_id} is already in flow:applying.`;
+
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `${transitionText} Loaded approved overview and ${taskCount} task${taskCount === 1 ? "" : "s"}.`,
       },
-    };
+    ],
+    details: {
+      action: "flow_apply",
+      ticketId: params.ticket_id,
+      transitioned,
+      status: applyStatus,
+      tags: "flow:applying",
+      contentPath,
+      overview,
+      tasks,
+    },
+  };
+}
+
+// ─── supi_flow_task ────────────────────────────────────────────
+
+export const supiFlowTaskParams = Type.Object({
+  ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
+  operation: StringEnum(["add", "edit", "remove"] as const, {
+    description: "Single-task mutation to apply",
+  }),
+  task_number: Type.Optional(
+    Type.Number({ description: "Task number for edit/remove operations" }),
+  ),
+  title: Type.Optional(
+    Type.String({ description: "Task title (required for add)" }),
+  ),
+  files: Type.Optional(
+    Type.Array(Type.String(), { description: "File paths for the task" }),
+  ),
+  clear_files: Type.Optional(
+    Type.Boolean({ description: "Clear all file paths during edit" }),
+  ),
+  verification: Type.Optional(
+    Type.String({ description: "Verification command for the task" }),
+  ),
+  clear_verification: Type.Optional(
+    Type.Boolean({ description: "Clear the verification command during edit" }),
+  ),
+  notes: Type.Optional(
+    Type.String({ description: "Extra notes for the task" }),
+  ),
+  clear_notes: Type.Optional(
+    Type.Boolean({ description: "Clear task notes during edit" }),
+  ),
+  detail: Type.Optional(
+    Type.String({ description: "Optional markdown body for the canonical task detail doc" }),
+  ),
+  clear_detail: Type.Optional(
+    Type.Boolean({ description: "Clear the linked canonical task detail doc reference during edit" }),
+  ),
+});
+
+export type FlowTaskParams = Static<typeof supiFlowTaskParams>;
+
+export async function executeFlowTask(params: FlowTaskParams) {
+  if (params.files !== undefined && params.clear_files) {
+    throw new Error("supi_flow_task: files and clear_files cannot be used together");
+  }
+  if (params.verification !== undefined && params.clear_verification) {
+    throw new Error("supi_flow_task: verification and clear_verification cannot be used together");
   }
+  if (params.notes !== undefined && params.clear_notes) {
+    throw new Error("supi_flow_task: notes and clear_notes cannot be used together");
+  }
+  if (params.detail !== undefined && params.clear_detail) {
+    throw new Error("supi_flow_task: detail and clear_detail cannot be used together");
+  }
+
+  switch (params.operation) {
+    case "add": {
+      if (params.task_number !== undefined) {
+        throw new Error("supi_flow_task: task_number is not used for add");
+      }
+      if (!params.title || !params.title.trim()) {
+        throw new Error("supi_flow_task: title is required for add");
+      }
 
-  const planPath = join(dirname(contentPath), planDocument.path);
+      const args: string[] = [
+        "ticket",
+        "task",
+        "add",
+        params.ticket_id,
+        "--title",
+        params.title,
+      ];
+      for (const file of params.files ?? []) {
+        args.push("--file", file);
+      }
+      if (params.verification && params.verification.trim()) {
+        args.push("--verification", params.verification);
+      }
+      if (params.notes && params.notes.trim()) {
+        args.push("--notes", params.notes);
+      }
 
-  let content: string;
-  try {
-    content = readFileSync(planPath, "utf-8");
-  } catch {
-    return {
-      content: [
-        {
-          type: "text" as const,
-          text: `No plan file found at ${planPath}. No tasks to complete.`,
+      const result = await tndmJson<Record<string, unknown>>(args);
+      const taskNumber = extractLatestTaskNumber(result);
+      let finalResult = result;
+
+      if (params.detail !== undefined) {
+        const detailResult = await ensureTaskDetailDoc(params.ticket_id, taskNumber);
+        writeTaskDetailDoc(detailResult.path, taskNumber, params.title, params.detail);
+        await tndm(["ticket", "sync", params.ticket_id]);
+        finalResult = await loadTicket(params.ticket_id);
+      }
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `Task ${taskNumber} added to ${params.ticket_id}.`,
+          },
+        ],
+        details: {
+          action: "flow_task",
+          operation: "add",
+          ticketId: params.ticket_id,
+          taskNumber,
+          result: finalResult,
         },
-      ],
-      details: { action: "flow_complete_task", ticketId: params.ticket_id, error: "No plan file" },
-    };
-  }
+      };
+    }
+
+    case "edit": {
+      if (params.task_number === undefined) {
+        throw new Error("supi_flow_task: task_number is required for edit");
+      }
+      if (params.title !== undefined && !params.title.trim()) {
+        throw new Error("supi_flow_task: title must not be blank when provided");
+      }
+      const hasRequestedChange =
+        params.title !== undefined ||
+        params.files !== undefined ||
+        Boolean(params.clear_files) ||
+        params.verification !== undefined ||
+        Boolean(params.clear_verification) ||
+        params.notes !== undefined ||
+        Boolean(params.clear_notes) ||
+        params.detail !== undefined ||
+        Boolean(params.clear_detail);
+      if (!hasRequestedChange) {
+        throw new Error("supi_flow_task: edit requires at least one field change");
+      }
 
-  const result = checkTask(content, params.task_number);
+      const args: string[] = [
+        "ticket",
+        "task",
+        "edit",
+        params.ticket_id,
+        String(params.task_number),
+      ];
+      if (params.title !== undefined) args.push("--title", params.title);
+      if (params.files !== undefined) {
+        if (params.files.length === 0) {
+          args.push("--clear-files");
+        } else {
+          for (const file of params.files) args.push("--file", file);
+        }
+      } else if (params.clear_files) {
+        args.push("--clear-files");
+      }
+      if (params.verification !== undefined) {
+        args.push("--verification", params.verification);
+      } else if (params.clear_verification) {
+        args.push("--verification", "");
+      }
+      if (params.notes !== undefined) {
+        args.push("--notes", params.notes);
+      } else if (params.clear_notes) {
+        args.push("--notes", "");
+      }
+
+      const hasManifestFieldChanges = args.length > 5;
+      const result = hasManifestFieldChanges
+        ? await tndmJson<Record<string, unknown>>(args)
+        : undefined;
+      let finalResult = result;
+
+      if (params.detail !== undefined) {
+        const detailResult = await ensureTaskDetailDoc(params.ticket_id, params.task_number);
+        const taskSnapshot = result ?? await loadTicket(params.ticket_id);
+        const taskTitle =
+          params.title ??
+          extractTaskTitle(taskSnapshot, params.task_number) ??
+          `Task ${params.task_number}`;
+        writeTaskDetailDoc(
+          detailResult.path,
+          params.task_number,
+          taskTitle,
+          params.detail,
+        );
+        await tndm(["ticket", "sync", params.ticket_id]);
+        finalResult = await loadTicket(params.ticket_id);
+      } else if (params.clear_detail) {
+        await tndmJson([
+          "ticket",
+          "task",
+          "detail",
+          "clear",
+          params.ticket_id,
+          String(params.task_number),
+        ]);
+        finalResult = await loadTicket(params.ticket_id);
+      }
 
-  switch (result.kind) {
-    case "unchecked":
-      writeFileSync(planPath, result.updatedContent, "utf-8");
-      await tndm(["ticket", "sync", params.ticket_id]);
       return {
         content: [
           {
             type: "text" as const,
-            text: `Task ${params.task_number} checked off in ${params.ticket_id}.`,
+            text: `Task ${params.task_number} updated in ${params.ticket_id}.`,
           },
         ],
         details: {
-          action: "flow_complete_task",
+          action: "flow_task",
+          operation: "edit",
           ticketId: params.ticket_id,
           taskNumber: params.task_number,
-          completed: true,
+          result: finalResult,
         },
       };
+    }
+
+    case "remove": {
+      if (params.task_number === undefined) {
+        throw new Error("supi_flow_task: task_number is required for remove");
+      }
+
+      const result = await tndmJson<Record<string, unknown>>([
+        "ticket",
+        "task",
+        "remove",
+        params.ticket_id,
+        String(params.task_number),
+      ]);
 
-    case "already_checked":
       return {
         content: [
           {
             type: "text" as const,
-            text: `Task ${params.task_number} is already checked off in ${params.ticket_id}.`,
+            text: `Task ${params.task_number} removed from ${params.ticket_id}.`,
           },
         ],
         details: {
-          action: "flow_complete_task",
+          action: "flow_task",
+          operation: "remove",
           ticketId: params.ticket_id,
           taskNumber: params.task_number,
-          completed: true,
-          skipped: true,
+          removed: true,
+          result,
         },
       };
+    }
+  }
+}
+
+// ─── supi_flow_complete_task ───────────────────────────────────
+
+export const supiFlowCompleteTaskParams = Type.Object({
+  ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
+  task_number: Type.Number({
+    description: "1-based task number to mark as complete (e.g. 1, 2, 3)",
+  }),
+});
+
+export type FlowCompleteTaskParams = Static<typeof supiFlowCompleteTaskParams>;
+
+export async function executeFlowCompleteTask(params: FlowCompleteTaskParams) {
+  try {
+    const result = await tndmJson<Record<string, unknown>>([
+      "ticket",
+      "task",
+      "complete",
+      params.ticket_id,
+      String(params.task_number),
+    ]);
 
-    case "not_found":
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: `Task ${params.task_number} completed in ${params.ticket_id}.`,
+        },
+      ],
+      details: {
+        action: "flow_complete_task",
+        ticketId: params.ticket_id,
+        taskNumber: params.task_number,
+        completed: true,
+        result,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Task already done returns a regular success from the CLI; only hard failure
+    // happens when the task doesn't exist
+    if (message.includes("not found")) {
       throw new Error(
-        `Task ${params.task_number} not found in ticket ${params.ticket_id}.` +
-        ` Task must exist as '- [ ] **Task N:**' or '- [x] **Task N:**'.`,
+        `Task ${params.task_number} not found in ticket ${params.ticket_id}.`,
       );
+    }
+    throw error;
   }
 }
 
@@ -299,47 +517,73 @@ export async function executeFlowCompleteTask(params: FlowCompleteTaskParams) {
 
 export const supiFlowCloseParams = Type.Object({
   ticket_id: Type.String({ description: "Ticket ID (e.g. TNDM-A1B2C3)" }),
-  verification_results: Type.Optional(
-    Type.String({
-      description:
-        "Verification results / evidence from the agent. Appended to the ticket content under ## Verification Results.",
-    }),
-  ),
+  verification_results: Type.String({
+    description:
+      "Verification results / evidence from the agent to write into archive.md before closing the ticket.",
+  }),
 });
 
 export type FlowCloseParams = Static<typeof supiFlowCloseParams>;
 
 export async function executeFlowClose(params: FlowCloseParams) {
-  let archivePath = "";
+  const verificationResults = params.verification_results?.trim() ?? "";
+  if (!verificationResults) {
+    throw new Error("supi_flow_close: verification_results is required");
+  }
 
-  if (params.verification_results) {
-    // Create/register archive.md via document registry, then write results
-    const docResult = await tndmJson<{ path: string }>([
-      "ticket",
-      "doc",
-      "create",
-      params.ticket_id,
-      "archive",
-    ]);
-    archivePath = docResult.path;
-    writeFileSync(archivePath, `# Archive\n\n${params.verification_results}\n`, "utf-8");
-    await tndm(["ticket", "sync", params.ticket_id]);
+  const ticket = await loadTicket(params.ticket_id);
+  const status = extractTicketStatus(ticket);
+  const tags = extractTicketTags(ticket);
+
+  if (status === "done" || tags.includes("flow:done")) {
+    throw new Error(`supi_flow_close: ticket ${params.ticket_id} is already closed`);
+  }
+  if (!tags.includes("flow:applying")) {
+    throw new Error(
+      `supi_flow_close: ticket ${params.ticket_id} must be in flow:applying before close`,
+    );
+  }
+  if (status !== "in_progress" && status !== "blocked") {
+    throw new Error(
+      `supi_flow_close: ticket ${params.ticket_id} must have status in_progress or blocked before close`,
+    );
   }
 
-  // Replace any flow-state tag with flow:done — remove all possible flow-state tags
-  // first, then set status and add flow:done, to work correctly regardless of the
-  // ticket's current flow state.
-  await tndm([
+  const tasks = await loadTaskList(params.ticket_id);
+  if (tasks.length === 0) {
+    throw new Error(`supi_flow_close: ticket ${params.ticket_id} has no structured tasks`);
+  }
+
+  const incompleteTasks = tasks.filter((task) => task.status !== "done");
+  if (incompleteTasks.length > 0) {
+    const taskList = incompleteTasks
+      .map((task) => `#${task.number ?? "?"}${task.title ? ` ${task.title}` : ""}`)
+      .join(", ");
+    throw new Error(
+      `supi_flow_close: ticket ${params.ticket_id} has incomplete tasks: ${taskList}`,
+    );
+  }
+
+  // Create/register archive.md via document registry, then write results
+  const docResult = await tndmJson<{ path: string }>([
     "ticket",
-    "update",
+    "doc",
+    "create",
     params.ticket_id,
-    "--remove-tags",
-    "flow:brainstorm,flow:planned,flow:applying,flow:done",
+    "archive",
   ]);
+  writeFileSync(docResult.path, `# Archive\n\n${verificationResults}\n`, "utf-8");
+  await tndm(["ticket", "sync", params.ticket_id]);
+
+  // Replace any flow-state tag with flow:done — remove all possible flow-state tags,
+  // set status, and add flow:done in one atomic call, to work correctly regardless of
+  // the ticket's current flow state.
   await tndm([
     "ticket",
     "update",
     params.ticket_id,
+    "--remove-tags",
+    "flow:brainstorm,flow:planned,flow:applying,flow:done",
     "--status",
     "done",
     "--add-tags",
@@ -361,3 +605,148 @@ export async function executeFlowClose(params: FlowCloseParams) {
     },
   };
 }
+
+function extractLatestTaskNumber(result: Record<string, unknown>): number {
+  const tasks = extractTasks(result);
+  const numbers = tasks
+    .map((task) => task.number)
+    .filter((value): value is number => typeof value === "number");
+
+  if (numbers.length === 0) {
+    throw new Error("supi_flow_task: task_add did not return a task list");
+  }
+
+  return Math.max(...numbers);
+}
+
+function extractTaskTitle(result: Record<string, unknown>, taskNumber: number): string | undefined {
+  return extractTasks(result).find((task) => task.number === taskNumber)?.title;
+}
+
+function extractTasks(result: Record<string, unknown>): FlowTaskListEntry[] {
+  const ticket = unwrapTicket(result);
+
+  if (Array.isArray(ticket.tasks)) {
+    return filterFlowTasks(ticket.tasks);
+  }
+
+  const state = ticket.state;
+  if (
+    typeof state === "object" &&
+    state !== null &&
+    Array.isArray((state as { tasks?: unknown }).tasks)
+  ) {
+    return filterFlowTasks((state as { tasks: unknown[] }).tasks);
+  }
+
+  return [];
+}
+
+function filterFlowTasks(tasks: unknown[]): FlowTaskListEntry[] {
+  return tasks.filter(
+    (task): task is FlowTaskListEntry => typeof task === "object" && task !== null,
+  );
+}
+
+function unwrapTicket(result: Record<string, unknown>): Record<string, unknown> {
+  const ticket = result.ticket;
+  if (typeof ticket === "object" && ticket !== null) {
+    return ticket as Record<string, unknown>;
+  }
+  return result;
+}
+
+function extractTicketTags(result: Record<string, unknown>): string[] {
+  const ticket = unwrapTicket(result);
+  if (!Array.isArray(ticket.tags)) {
+    return [];
+  }
+
+  return ticket.tags.filter((tag): tag is string => typeof tag === "string");
+}
+
+function extractTicketStatus(result: Record<string, unknown>): string | undefined {
+  const ticket = unwrapTicket(result);
+  return typeof ticket.status === "string" ? ticket.status : undefined;
+}
+
+function extractContentPath(result: Record<string, unknown>): string | undefined {
+  const ticket = unwrapTicket(result);
+  return typeof ticket.content_path === "string" ? ticket.content_path : undefined;
+}
+
+function readRequiredTicketContent(
+  ticketId: string,
+  contentPath: string | undefined,
+  toolName: string,
+): string {
+  if (!contentPath) {
+    throw new Error(`${toolName}: ticket ${ticketId} is missing content_path`);
+  }
+
+  let overview: string;
+  try {
+    overview = readFileSync(resolveTicketPath(contentPath), "utf-8");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${toolName}: failed to read content.md for ticket ${ticketId}: ${message}`);
+  }
+
+  if (!overview.trim()) {
+    throw new Error(`${toolName}: approved overview in content.md must not be blank`);
+  }
+
+  return overview;
+}
+
+function resolveTicketPath(ticketPath: string): string {
+  if (isAbsolute(ticketPath)) {
+    return ticketPath;
+  }
+
+  return resolve(findRepoRoot(), ticketPath);
+}
+
+function findRepoRoot(startDir = process.cwd()): string {
+  let current = resolve(startDir);
+
+  while (true) {
+    if (existsSync(join(current, ".git")) || existsSync(join(current, ".tndm"))) {
+      return current;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      throw new Error(`failed to locate repository root from ${startDir}`);
+    }
+    current = parent;
+  }
+}
+
+async function loadTicket(id: string): Promise<Record<string, unknown>> {
+  return tndmJson<Record<string, unknown>>(["ticket", "show", id]);
+}
+
+async function loadTaskList(id: string): Promise<FlowTaskListEntry[]> {
+  const tasks = await tndmJson<unknown>(["ticket", "task", "list", id]);
+  if (!Array.isArray(tasks)) {
+    throw new Error(`supi_flow: task list for ticket ${id} did not return an array`);
+  }
+  return filterFlowTasks(tasks);
+}
+
+async function ensureTaskDetailDoc(id: string, taskNumber: number): Promise<{ path: string }> {
+  return tndmJson<{ path: string }>([
+    "ticket",
+    "task",
+    "detail",
+    "ensure",
+    id,
+    String(taskNumber),
+  ]);
+}
+
+function writeTaskDetailDoc(path: string, taskNumber: number, title: string, detail: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `# Task ${taskNumber}: ${title}\n\n${detail}\n`, "utf-8");
+}