@kata-sh/cli 0.1.0 → 0.1.2

package/src/resources/extensions/kata/guided-flow.ts

@@ -0,0 +1,976 @@
+/**
+ * Kata Guided Flow — Smart Entry Wizard
+ *
+ * One function: showSmartEntry(). Reads state from disk, shows a contextual
+ * wizard via showNextAction(), and dispatches through KATA-WORKFLOW.md.
+ * No execution state, no hooks, no tools — the LLM does the rest.
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import { showNextAction } from "../shared/next-action-ui.js";
+import { loadFile, parseRoadmap } from "./files.js";
+import { loadPrompt } from "./prompt-loader.js";
+import { deriveState } from "./state.js";
+import { startAuto } from "./auto.js";
+import { readCrashLock, clearLock, formatCrashInfo } from "./crash-recovery.js";
+import {
+  kataRoot,
+  milestonesDir,
+  resolveMilestoneFile,
+  resolveSliceFile,
+  resolveSlicePath,
+  resolveKataRootFile,
+  relKataRootFile,
+  relMilestoneFile,
+  relSliceFile,
+  relSlicePath,
+} from "./paths.js";
+import { join } from "node:path";
+import { readFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { ensureGitignore, ensurePreferences } from "./gitignore.js";
+
+// ─── Auto-start after discuss ─────────────────────────────────────────────────
+
+/** Stashed context + flag for auto-starting after discuss phase completes */
+let pendingAutoStart: {
+  ctx: ExtensionCommandContext;
+  pi: ExtensionAPI;
+  basePath: string;
+  milestoneId: string; // the milestone being discussed
+} | null = null;
+
+/** Called from agent_end to check if auto-mode should start after discuss */
+export function checkAutoStartAfterDiscuss(): boolean {
+  if (!pendingAutoStart) return false;
+
+  const { ctx, pi, basePath, milestoneId } = pendingAutoStart;
+
+  // Don't fire until the discuss phase has actually produced a context file
+  // for the milestone being discussed. agent_end fires after every LLM turn,
+  // including the initial "What do you want to build?" response — we need to
+  // wait for the full conversation to complete and the LLM to write CONTEXT.md.
+  const contextFile = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+  if (!contextFile) return false; // no context yet — keep waiting
+
+  pendingAutoStart = null;
+  startAuto(ctx, pi, basePath, false).catch(() => {});
+  return true;
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type UIContext = ExtensionContext;
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Read KATA-WORKFLOW.md and dispatch it to the LLM with a contextual note.
+ * This is the only way the wizard triggers work — everything else is the LLM's job.
+ */
+function dispatchWorkflow(
+  pi: ExtensionAPI,
+  note: string,
+  customType = "kata-run",
+): void {
+  const workflowPath =
+    process.env.KATA_WORKFLOW_PATH ??
+    join(process.env.HOME ?? "~", ".kata-cli", "KATA-WORKFLOW.md");
+  const workflow = readFileSync(workflowPath, "utf-8");
+
+  pi.sendMessage(
+    {
+      customType,
+      content: `Read the following Kata workflow protocol and execute exactly.\n\n${workflow}\n\n## Your Task\n\n${note}`,
+      display: false,
+    },
+    { triggerTurn: true },
+  );
+}
+
+/**
+ * Build the discuss-and-plan prompt for a new milestone.
+ * Used by all three "new milestone" paths (first ever, no active, all complete).
+ */
+function buildDiscussPrompt(
+  nextId: string,
+  preamble: string,
+  basePath: string,
+): string {
+  const milestoneDirAbs = join(basePath, ".kata", "milestones", nextId);
+  return loadPrompt("discuss", {
+    milestoneId: nextId,
+    preamble,
+    contextAbsPath: join(milestoneDirAbs, `${nextId}-CONTEXT.md`),
+    roadmapAbsPath: join(milestoneDirAbs, `${nextId}-ROADMAP.md`),
+  });
+}
+
+function findMilestoneIds(basePath: string): string[] {
+  const dir = milestonesDir(basePath);
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => {
+        const match = d.name.match(/^(M\d+)/);
+        return match ? match[1] : d.name;
+      })
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+// ─── Queue ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Queue future milestones via conversational intake.
+ *
+ * Safe to run while auto-mode is executing — only writes to future milestone
+ * directories (which auto-mode won't touch until it reaches them) and appends
+ * to project.md / queue.md.
+ *
+ * The flow:
+ * 1. Build context about all existing milestones (complete, active, pending)
+ * 2. Dispatch the queue prompt — LLM discusses with the user, assesses scope
+ * 3. LLM writes CONTEXT.md files for new milestones (no roadmaps — JIT)
+ * 4. Auto-mode picks them up naturally when it advances past current work
+ *
+ * Root durable artifacts use uppercase names like PROJECT.md and QUEUE.md.
+ */
+export async function showQueue(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+): Promise<void> {
+  // ── Ensure .kata/ exists ─────────────────────────────────────────────
+  const kataDir = kataRoot(basePath);
+  if (!existsSync(kataDir)) {
+    ctx.ui.notify(
+      "No Kata project found. Run /kata to start one first.",
+      "warning",
+    );
+    return;
+  }
+
+  const state = await deriveState(basePath);
+  const milestoneIds = findMilestoneIds(basePath);
+
+  if (milestoneIds.length === 0) {
+    ctx.ui.notify(
+      "No milestones exist yet. Run /kata to create the first one.",
+      "warning",
+    );
+    return;
+  }
+
+  // ── Build existing milestones context for the prompt ────────────────
+  const existingContext = await buildExistingMilestonesContext(
+    basePath,
+    milestoneIds,
+    state,
+  );
+
+  // ── Determine next milestone ID ─────────────────────────────────────
+  const maxNum = milestoneIds.reduce((max, id) => {
+    const num = parseInt(id.replace(/^M/, ""), 10);
+    return num > max ? num : max;
+  }, 0);
+  const nextId = `M${String(maxNum + 1).padStart(3, "0")}`;
+  const nextIdPlus1 = `M${String(maxNum + 2).padStart(3, "0")}`;
+
+  // ── Build preamble ──────────────────────────────────────────────────
+  const activePart = state.activeMilestone
+    ? `Currently executing: ${state.activeMilestone.id} — ${state.activeMilestone.title} (phase: ${state.phase}).`
+    : "No milestone currently active.";
+
+  const pendingCount = state.registry.filter(
+    (m) => m.status === "pending",
+  ).length;
+  const completeCount = state.registry.filter(
+    (m) => m.status === "complete",
+  ).length;
+
+  const preamble = [
+    `Queuing new work onto an existing Kata project.`,
+    activePart,
+    `${completeCount} milestone(s) complete, ${pendingCount} pending.`,
+    `Next available milestone ID: ${nextId}.`,
+  ].join(" ");
+
+  // ── Dispatch the queue prompt ───────────────────────────────────────
+  const prompt = loadPrompt("queue", {
+    preamble,
+    nextId,
+    nextIdPlus1,
+    existingMilestonesContext: existingContext,
+  });
+
+  pi.sendMessage(
+    {
+      customType: "kata-queue",
+      content: prompt,
+      display: false,
+    },
+    { triggerTurn: true },
+  );
+}
+
+/**
+ * Build a context block describing all existing milestones for the queue prompt.
+ * Gives the LLM enough information to dedup, sequence, and dependency-check.
+ */
+async function buildExistingMilestonesContext(
+  basePath: string,
+  milestoneIds: string[],
+  state: import("./types.js").kataState,
+): Promise<string> {
+  const sections: string[] = [];
+
+  // Include PROJECT.md if it exists — it has the milestone sequence and project description
+  const projectPath = resolveKataRootFile(basePath, "PROJECT");
+  if (existsSync(projectPath)) {
+    const projectContent = await loadFile(projectPath);
+    if (projectContent) {
+      sections.push(
+        `### Project Overview\nSource: \`${relKataRootFile("PROJECT")}\`\n\n${projectContent.trim()}`,
+      );
+    }
+  }
+
+  // Include DECISIONS.md if it exists — architectural decisions inform new milestone scoping
+  const decisionsPath = resolveKataRootFile(basePath, "DECISIONS");
+  if (existsSync(decisionsPath)) {
+    const decisionsContent = await loadFile(decisionsPath);
+    if (decisionsContent) {
+      sections.push(
+        `### Decisions Register\nSource: \`${relKataRootFile("DECISIONS")}\`\n\n${decisionsContent.trim()}`,
+      );
+    }
+  }
+
+  // For each milestone, include context and status
+  for (const mid of milestoneIds) {
+    const registryEntry = state.registry.find((m) => m.id === mid);
+    const status = registryEntry?.status ?? "unknown";
+    const title = registryEntry?.title ?? mid;
+
+    const parts: string[] = [];
+    parts.push(`### ${mid}: ${title}\n**Status:** ${status}`);
+
+    // Include context file — this is the primary content for understanding scope
+    const contextFile = resolveMilestoneFile(basePath, mid, "CONTEXT");
+    if (contextFile) {
+      const content = await loadFile(contextFile);
+      if (content) {
+        parts.push(`\n**Context:**\n${content.trim()}`);
+      }
+    }
+
+    // For completed milestones, include the summary if it exists
+    if (status === "complete") {
+      const summaryFile = resolveMilestoneFile(basePath, mid, "SUMMARY");
+      if (summaryFile) {
+        const content = await loadFile(summaryFile);
+        if (content) {
+          parts.push(`\n**Summary:**\n${content.trim()}`);
+        }
+      }
+    }
+
+    // For active/pending milestones, include the roadmap if it exists
+    // (shows what's planned but not yet built)
+    if (status === "active" || status === "pending") {
+      const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+      if (roadmapFile) {
+        const content = await loadFile(roadmapFile);
+        if (content) {
+          parts.push(`\n**Roadmap:**\n${content.trim()}`);
+        }
+      }
+    }
+
+    sections.push(parts.join("\n"));
+  }
+
+  // Include queue log if it exists — shows what's been queued before
+  const queuePath = resolveKataRootFile(basePath, "QUEUE");
+  if (existsSync(queuePath)) {
+    const queueContent = await loadFile(queuePath);
+    if (queueContent) {
+      sections.push(
+        `### Previous Queue Entries\nSource: \`${relKataRootFile("QUEUE")}\`\n\n${queueContent.trim()}`,
+      );
+    }
+  }
+
+  return sections.join("\n\n---\n\n");
+}
+
+// ─── Discuss Flow ─────────────────────────────────────────────────────────────
+
+/**
+ * Build a rich inlined-context prompt for discussing a specific slice.
+ * Preloads roadmap, milestone context, research, decisions, and completed
+ * slice summaries so the agent can ask grounded UX/behaviour questions
+ * without wasting a turn reading files.
+ */
+async function buildDiscussSlicePrompt(
+  mid: string,
+  sid: string,
+  sTitle: string,
+  base: string,
+): Promise<string> {
+  const inlined: string[] = [];
+
+  // Roadmap — always included so the agent sees surrounding slices
+  const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
+  const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
+  const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+  if (roadmapContent) {
+    inlined.push(
+      `### Milestone Roadmap\nSource: \`${roadmapRel}\`\n\n${roadmapContent.trim()}`,
+    );
+  }
+
+  // Milestone context — understanding the full milestone intent
+  const contextPath = resolveMilestoneFile(base, mid, "CONTEXT");
+  const contextRel = relMilestoneFile(base, mid, "CONTEXT");
+  const contextContent = contextPath ? await loadFile(contextPath) : null;
+  if (contextContent) {
+    inlined.push(
+      `### Milestone Context\nSource: \`${contextRel}\`\n\n${contextContent.trim()}`,
+    );
+  }
+
+  // Milestone research — technical grounding
+  const researchPath = resolveMilestoneFile(base, mid, "RESEARCH");
+  const researchRel = relMilestoneFile(base, mid, "RESEARCH");
+  const researchContent = researchPath ? await loadFile(researchPath) : null;
+  if (researchContent) {
+    inlined.push(
+      `### Milestone Research\nSource: \`${researchRel}\`\n\n${researchContent.trim()}`,
+    );
+  }
+
+  // Decisions — architectural context that constrains this slice
+  const decisionsPath = resolveKataRootFile(base, "DECISIONS");
+  if (existsSync(decisionsPath)) {
+    const decisionsContent = await loadFile(decisionsPath);
+    if (decisionsContent) {
+      inlined.push(
+        `### Decisions Register\nSource: \`${relKataRootFile("DECISIONS")}\`\n\n${decisionsContent.trim()}`,
+      );
+    }
+  }
+
+  // Completed slice summaries — what was already built that this slice builds on
+  if (roadmapContent) {
+    const roadmap = parseRoadmap(roadmapContent);
+    for (const s of roadmap.slices) {
+      if (!s.done || s.id === sid) continue;
+      const summaryPath = resolveSliceFile(base, mid, s.id, "SUMMARY");
+      const summaryRel = relSliceFile(base, mid, s.id, "SUMMARY");
+      const summaryContent = summaryPath ? await loadFile(summaryPath) : null;
+      if (summaryContent) {
+        inlined.push(
+          `### ${s.id} Summary (completed)\nSource: \`${summaryRel}\`\n\n${summaryContent.trim()}`,
+        );
+      }
+    }
+  }
+
+  const inlinedContext =
+    inlined.length > 0
+      ? `## Inlined Context (preloaded — do not re-read these files)\n\n${inlined.join("\n\n---\n\n")}`
+      : `## Inlined Context\n\n_(no context files found yet — go in blind and ask broad questions)_`;
+
+  const sliceDirAbsPath = join(base, ".kata", "milestones", mid, "slices", sid);
+  const contextAbsPath = join(sliceDirAbsPath, `${sid}-CONTEXT.md`);
+
+  return loadPrompt("guided-discuss-slice", {
+    milestoneId: mid,
+    sliceId: sid,
+    sliceTitle: sTitle,
+    inlinedContext,
+    sliceDirAbsPath,
+    contextAbsPath,
+    projectRoot: base,
+  });
+}
+
+/**
+ * /kata discuss — show a picker of non-done slices and run a slice interview.
+ * Loops back to the picker after each discussion so the user can chain
+ * multiple slice interviews in one session.
+ */
+export async function showDiscuss(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+): Promise<void> {
+  // Guard: no .kata/ project
+  if (!existsSync(join(basePath, ".kata"))) {
+    ctx.ui.notify(
+      "No Kata project found. Run /kata to start one first.",
+      "warning",
+    );
+    return;
+  }
+
+  const state = await deriveState(basePath);
+
+  // Guard: no active milestone
+  if (!state.activeMilestone) {
+    ctx.ui.notify(
+      "No active milestone. Run /kata to create one first.",
+      "warning",
+    );
+    return;
+  }
+
+  const mid = state.activeMilestone.id;
+  const milestoneTitle = state.activeMilestone.title;
+
+  // Guard: no roadmap yet
+  const roadmapFile = resolveMilestoneFile(basePath, mid, "ROADMAP");
+  const roadmapContent = roadmapFile ? await loadFile(roadmapFile) : null;
+  if (!roadmapContent) {
+    ctx.ui.notify(
+      "No roadmap yet for this milestone. Run /kata to plan first.",
+      "warning",
+    );
+    return;
+  }
+
+  const roadmap = parseRoadmap(roadmapContent);
+  const pendingSlices = roadmap.slices.filter((s) => !s.done);
+
+  if (pendingSlices.length === 0) {
+    ctx.ui.notify("All slices are complete — nothing to discuss.", "info");
+    return;
+  }
+
+  // Loop: show picker, dispatch discuss, repeat until "not_yet"
+  while (true) {
+    const actions = pendingSlices.map((s, i) => ({
+      id: s.id,
+      label: `${s.id}: ${s.title}`,
+      description: state.activeSlice?.id === s.id ? "active slice" : "upcoming",
+      recommended: i === 0,
+    }));
+
+    const choice = await showNextAction(ctx as any, {
+      title: "Kata — Discuss a slice",
+      summary: [
+        `${mid}: ${milestoneTitle}`,
+        "Pick a slice to interview. Context file will be written when done.",
+      ],
+      actions,
+      notYetMessage: "Run /kata discuss when ready.",
+    });
+
+    if (choice === "not_yet") return;
+
+    const chosen = pendingSlices.find((s) => s.id === choice);
+    if (!chosen) return;
+
+    const prompt = await buildDiscussSlicePrompt(
+      mid,
+      chosen.id,
+      chosen.title,
+      basePath,
+    );
+    dispatchWorkflow(pi, prompt, "kata-discuss");
+
+    // Wait for the discuss session to finish, then loop back to the picker
+    await ctx.waitForIdle();
+  }
+}
+
+// ─── Smart Entry Point ────────────────────────────────────────────────────────
+
+/**
+ * The one wizard. Reads state, shows contextual options, dispatches into the workflow doc.
+ */
+export async function showSmartEntry(
+  ctx: ExtensionCommandContext,
+  pi: ExtensionAPI,
+  basePath: string,
+): Promise<void> {
+  // ── Ensure git repo exists — Kata needs it for branch-per-slice ──────
+  try {
+    execSync("git rev-parse --git-dir", { cwd: basePath, stdio: "pipe" });
+  } catch {
+    execSync("git init", { cwd: basePath, stdio: "pipe" });
+  }
+
+  // ── Ensure .gitignore has baseline patterns ──────────────────────────
+  ensureGitignore(basePath);
+
+  // ── No Kata project OR no milestone → Create first/next milestone ────
+  if (!existsSync(join(basePath, ".kata"))) {
+    // Bootstrap .kata/ silently — the user wants a milestone, not to "init"
+    const kataDir = kataRoot(basePath);
+    mkdirSync(join(kataDir, "milestones"), { recursive: true });
+
+    // ── Create PREFERENCES.md template ────────────────────────────────
+    ensurePreferences(basePath);
+    try {
+      execSync(
+        "git add -A .kata .gitignore && git commit -m 'chore: init kata'",
+        {
+          cwd: basePath,
+          stdio: "pipe",
+        },
+      );
+    } catch {
+      // nothing to commit — that's fine
+    }
+  }
+
+  // Check for crash from previous auto-mode session
+  const crashLock = readCrashLock(basePath);
+  if (crashLock) {
+    clearLock(basePath);
+    const resume = await showNextAction(ctx as any, {
+      title: "Kata — Interrupted Session Detected",
+      summary: [formatCrashInfo(crashLock)],
+      actions: [
+        {
+          id: "resume",
+          label: "Resume with /kata auto",
+          description: "Pick up where it left off",
+          recommended: true,
+        },
+        {
+          id: "continue",
+          label: "Continue manually",
+          description: "Open the wizard as normal",
+        },
+      ],
+    });
+    if (resume === "resume") {
+      await startAuto(ctx, pi, basePath, false);
+      return;
+    }
+  }
+
+  const state = await deriveState(basePath);
+
+  if (!state.activeMilestone) {
+    // Guard: if a discuss session is already in flight, don't re-inject the prompt.
+    // Both /kata and /kata auto reach this branch when no milestone exists yet.
+    // Without this guard, every subsequent /kata call overwrites pendingAutoStart
+    // and fires another dispatchWorkflow, resetting the conversation mid-interview.
+    if (pendingAutoStart) {
+      ctx.ui.notify(
+        "Discussion already in progress — answer the question above to continue.",
+        "info",
+      );
+      return;
+    }
+
+    const milestoneIds = findMilestoneIds(basePath);
+    const nextId = `M${String(milestoneIds.length + 1).padStart(3, "0")}`;
+    const isFirst = milestoneIds.length === 0;
+
+    if (isFirst) {
+      // First ever — skip wizard, just ask directly
+      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+      dispatchWorkflow(
+        pi,
+        buildDiscussPrompt(
+          nextId,
+          `New project, milestone ${nextId}. Do NOT read or explore .kata/ — it's empty scaffolding.`,
+          basePath,
+        ),
+      );
+    } else {
+      const choice = await showNextAction(ctx as any, {
+        title: "Kata — Kata Workflow",
+        summary: ["No active milestone."],
+        actions: [
+          {
+            id: "new_milestone",
+            label: "Create next milestone",
+            description: "Define what to build next.",
+            recommended: true,
+          },
+        ],
+        notYetMessage: "Run /kata when ready.",
+      });
+
+      if (choice === "new_milestone") {
+        pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+        dispatchWorkflow(
+          pi,
+          buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath),
+        );
+      }
+    }
+    return;
+  }
+
+  const milestoneId = state.activeMilestone.id;
+  const milestoneTitle = state.activeMilestone.title;
+
+  // ── All milestones complete → New milestone ──────────────────────────
+  if (state.phase === "complete") {
+    const choice = await showNextAction(ctx as any, {
+      title: `Kata — ${milestoneId}: ${milestoneTitle}`,
+      summary: ["All milestones complete."],
+      actions: [
+        {
+          id: "new_milestone",
+          label: "Start new milestone",
+          description: "Define and plan the next milestone.",
+          recommended: true,
+        },
+        {
+          id: "status",
+          label: "View status",
+          description: "Review what was built.",
+        },
+      ],
+      notYetMessage: "Run /kata when ready.",
+    });
+
+    if (choice === "new_milestone") {
+      const milestoneIds = findMilestoneIds(basePath);
+      const nextId = `M${String(milestoneIds.length + 1).padStart(3, "0")}`;
+
+      pendingAutoStart = { ctx, pi, basePath, milestoneId: nextId };
+      dispatchWorkflow(
+        pi,
+        buildDiscussPrompt(nextId, `New milestone ${nextId}.`, basePath),
+      );
+    } else if (choice === "status") {
+      const { fireStatusViaCommand } = await import("./commands.js");
+      await fireStatusViaCommand(ctx);
+    }
+    return;
+  }
+
+  // ── No active slice ──────────────────────────────────────────────────
+  if (!state.activeSlice) {
+    const roadmapFile = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const hasRoadmap = !!(roadmapFile && (await loadFile(roadmapFile)));
+
+    if (!hasRoadmap) {
+      // No roadmap → discuss or plan
+      const contextFile = resolveMilestoneFile(
+        basePath,
+        milestoneId,
+        "CONTEXT",
+      );
+      const hasContext = !!(contextFile && (await loadFile(contextFile)));
+
+      const actions = [
+        {
+          id: "plan",
+          label: "Create roadmap",
+          description: hasContext
+            ? "Context captured. Decompose into slices with a boundary map."
+            : "Decompose the milestone into slices with a boundary map.",
+          recommended: true,
+        },
+        ...(!hasContext
+          ? [
+              {
+                id: "discuss",
+                label: "Discuss first",
+                description: "Capture decisions on gray areas before planning.",
+              },
+            ]
+          : []),
+      ];
+
+      const choice = await showNextAction(ctx as any, {
+        title: `Kata — ${milestoneId}: ${milestoneTitle}`,
+        summary: [
+          hasContext
+            ? "Context captured. Ready to create roadmap."
+            : "New milestone — no roadmap yet.",
+        ],
+        actions,
+        notYetMessage: "Run /kata when ready.",
+      });
+
+      if (choice === "plan") {
+        dispatchWorkflow(
+          pi,
+          loadPrompt("guided-plan-milestone", {
+            milestoneId,
+            milestoneTitle,
+          }),
+        );
+      } else if (choice === "discuss") {
+        dispatchWorkflow(
+          pi,
+          loadPrompt("guided-discuss-milestone", {
+            milestoneId,
+            milestoneTitle,
+          }),
+        );
+      }
+    } else {
+      // Roadmap exists — either blocked or ready for auto
+      const actions = [
+        {
+          id: "auto",
+          label: "Go auto",
+          description:
+            "Execute everything automatically until milestone complete.",
+          recommended: true,
+        },
+        {
+          id: "status",
+          label: "View status",
+          description: "See milestone progress and blockers.",
+        },
+      ];
+
+      const choice = await showNextAction(ctx as any, {
+        title: `Kata — ${milestoneId}: ${milestoneTitle}`,
+        summary: ["Roadmap exists. Ready to execute."],
+        actions,
+        notYetMessage: "Run /kata status for details.",
+      });
+
+      if (choice === "auto") {
+        await startAuto(ctx, pi, basePath, false);
+      } else if (choice === "status") {
+        const { fireStatusViaCommand } = await import("./commands.js");
+        await fireStatusViaCommand(ctx);
+      }
+    }
+    return;
+  }
+
+  const sliceId = state.activeSlice.id;
+  const sliceTitle = state.activeSlice.title;
+
+  // ── Slice needs planning ─────────────────────────────────────────────
+  if (state.phase === "planning") {
+    const contextFile = resolveSliceFile(
+      basePath,
+      milestoneId,
+      sliceId,
+      "CONTEXT",
+    );
+    const researchFile = resolveSliceFile(
+      basePath,
+      milestoneId,
+      sliceId,
+      "RESEARCH",
+    );
+    const hasContext = !!(contextFile && (await loadFile(contextFile)));
+    const hasResearch = !!(researchFile && (await loadFile(researchFile)));
+
+    const actions = [
+      {
+        id: "plan",
+        label: `Plan ${sliceId}`,
+        description: `Decompose "${sliceTitle}" into tasks with must-haves.`,
+        recommended: true,
+      },
+      ...(!hasContext
+        ? [
+            {
+              id: "discuss",
+              label: `Discuss ${sliceId} first`,
+              description: "Capture context and decisions for this slice.",
+            },
+          ]
+        : []),
+      ...(!hasResearch
+        ? [
+            {
+              id: "research",
+              label: `Research ${sliceId} first`,
+              description: "Scout codebase and relevant docs.",
+            },
+          ]
+        : []),
+      {
+        id: "status",
+        label: "View status",
+        description: "See milestone progress.",
+      },
+    ];
+
+    const summaryParts = [];
+    if (hasContext) summaryParts.push("context ✓");
+    if (hasResearch) summaryParts.push("research ✓");
+    const summaryLine =
+      summaryParts.length > 0
+        ? `${sliceId}: ${sliceTitle} (${summaryParts.join(", ")})`
+        : `${sliceId}: ${sliceTitle} — ready for planning.`;
+
+    const choice = await showNextAction(ctx as any, {
+      title: `Kata — ${milestoneId} / ${sliceId}: ${sliceTitle}`,
+      summary: [summaryLine],
+      actions,
+      notYetMessage: "Run /kata when ready.",
+    });
+
+    if (choice === "plan") {
+      dispatchWorkflow(
+        pi,
+        loadPrompt("guided-plan-slice", {
+          milestoneId,
+          sliceId,
+          sliceTitle,
+        }),
+      );
+    } else if (choice === "discuss") {
+      dispatchWorkflow(
+        pi,
+        await buildDiscussSlicePrompt(
+          milestoneId,
+          sliceId,
+          sliceTitle,
+          basePath,
+        ),
+      );
+    } else if (choice === "research") {
+      dispatchWorkflow(
+        pi,
+        loadPrompt("guided-research-slice", {
+          milestoneId,
+          sliceId,
+          sliceTitle,
+        }),
+      );
+    } else if (choice === "status") {
+      const { fireStatusViaCommand } = await import("./commands.js");
+      await fireStatusViaCommand(ctx);
+    }
+    return;
+  }
+
+  // ── All tasks done → Complete slice ──────────────────────────────────
+  if (state.phase === "summarizing") {
+    const choice = await showNextAction(ctx as any, {
+      title: `Kata — ${milestoneId} / ${sliceId}: ${sliceTitle}`,
+      summary: ["All tasks complete. Ready for slice summary."],
+      actions: [
+        {
+          id: "complete",
+          label: `Complete ${sliceId}`,
+          description:
+            "Write slice summary, UAT, mark done, and squash-merge to main.",
+          recommended: true,
+        },
+        {
+          id: "status",
+          label: "View status",
+          description: "Review tasks before completing.",
+        },
+      ],
+      notYetMessage: "Run /kata when ready.",
+    });
+
+    if (choice === "complete") {
+      dispatchWorkflow(
+        pi,
+        loadPrompt("guided-complete-slice", {
+          milestoneId,
+          sliceId,
+          sliceTitle,
+        }),
+      );
+    } else if (choice === "status") {
+      const { fireStatusViaCommand } = await import("./commands.js");
+      await fireStatusViaCommand(ctx);
+    }
+    return;
+  }
+
+  // ── Active task → Execute ────────────────────────────────────────────
+  if (state.activeTask) {
+    const taskId = state.activeTask.id;
+    const taskTitle = state.activeTask.title;
+
+    const continueFile = resolveSliceFile(
+      basePath,
+      milestoneId,
+      sliceId,
+      "CONTINUE",
+    );
+    const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
+    const hasInterrupted =
+      !!(continueFile && (await loadFile(continueFile))) ||
+      !!(sDir && (await loadFile(join(sDir, "continue.md"))));
+
+    const choice = await showNextAction(ctx as any, {
+      title: `Kata — ${milestoneId} / ${sliceId}: ${sliceTitle}`,
+      summary: [
+        hasInterrupted
+          ? `Resuming: ${taskId} — ${taskTitle}`
+          : `Next: ${taskId} — ${taskTitle}`,
+      ],
+      actions: [
+        {
+          id: "execute",
+          label: hasInterrupted ? `Resume ${taskId}` : `Execute ${taskId}`,
+          description: hasInterrupted
+            ? "Continue from where you left off."
+            : `Start working on "${taskTitle}".`,
+          recommended: true,
+        },
+        {
+          id: "auto",
+          label: "Go auto",
+          description: "Execute this and all remaining tasks automatically.",
+        },
+        {
+          id: "status",
+          label: "View status",
+          description: "See slice progress before starting.",
+        },
+      ],
+      notYetMessage: "Run /kata when ready.",
+    });
+
+    if (choice === "auto") {
+      await startAuto(ctx, pi, basePath, false);
+      return;
+    }
+
+    if (choice === "execute") {
+      if (hasInterrupted) {
+        dispatchWorkflow(
+          pi,
+          loadPrompt("guided-resume-task", {
+            milestoneId,
+            sliceId,
+          }),
+        );
+      } else {
+        dispatchWorkflow(
+          pi,
+          loadPrompt("guided-execute-task", {
+            milestoneId,
+            sliceId,
+            taskId,
+            taskTitle,
+          }),
+        );
+      }
+    } else if (choice === "status") {
+      const { fireStatusViaCommand } = await import("./commands.js");
+      await fireStatusViaCommand(ctx);
+    }
+    return;
+  }
+
+  // ── Fallback: show status ────────────────────────────────────────────
+  const { fireStatusViaCommand } = await import("./commands.js");
+  await fireStatusViaCommand(ctx);
+}