work-kit-cli 0.2.8 → 0.3.0

package/cli/src/commands/init.ts

@@ -1,8 +1,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, SUBSTAGES_BY_PHASE, WorkflowStep, Classification } from "../state/schema.js";
-import { writeState, writeStateMd, stateExists } from "../state/store.js";
-import { buildFullWorkflow, buildDefaultWorkflow, skillFilePath } from "../config/phases.js";
+import { WorkKitState, PhaseState, PhaseName, PHASE_NAMES, STEPS_BY_PHASE, WorkflowStep, Classification, MODE_FULL, MODE_AUTO } from "../state/schema.js";
+import { writeState, writeStateMd, stateExists, STATE_DIR, resolveMainRepoRoot } from "../state/store.js";
+import { buildFullWorkflow, buildDefaultWorkflow, skillFilePath } from "../config/workflow.js";
+import { BRANCH_PREFIX, CLI_BINARY } from "../config/constants.js";
+import { loadProjectConfig } from "../config/project-config.js";
 import type { Action } from "../state/schema.js";
 
 function toSlug(description: string): string {
@@ -18,23 +20,23 @@ function buildPhases(workflow?: WorkflowStep[]): Record<PhaseName, PhaseState> {
   const phases = {} as Record<PhaseName, PhaseState>;
 
   for (const phase of PHASE_NAMES) {
-    const subStages: Record<string, { status: "pending" | "skipped" }> = {};
-    const allSubStages = SUBSTAGES_BY_PHASE[phase];
+    const steps: Record<string, { status: "pending" | "skipped" }> = {};
+    const allSteps = STEPS_BY_PHASE[phase];
 
-    for (const ss of allSubStages) {
+    for (const s of allSteps) {
       if (workflow) {
-        const step = workflow.find((s) => s.phase === phase && s.subStage === ss);
-        subStages[ss] = { status: step?.included ? "pending" : "skipped" };
+        const ws = workflow.find((w) => w.phase === phase && w.step === s);
+        steps[s] = { status: ws?.included ? "pending" : "skipped" };
       } else {
-        subStages[ss] = { status: "pending" };
+        steps[s] = { status: "pending" };
       }
     }
 
-    // Check if entire phase is skipped (all sub-stages skipped)
-    const allSkipped = Object.values(subStages).every((s) => s.status === "skipped");
+    // Check if entire phase is skipped (all steps skipped)
+    const allSkipped = Object.values(steps).every((s) => s.status === "skipped");
     phases[phase] = {
       status: allSkipped ? "skipped" : "pending",
-      subStages,
+      steps,
     };
   }
 
@@ -58,7 +60,7 @@ function generateStateMd(slug: string, branch: string, mode: string, description
   }
 
   md += `**Phase:** plan
-**Sub-stage:** clarify
+**Step:** clarify
 **Status:** in-progress
 
 ## Description
@@ -67,9 +69,9 @@ ${description}
 
   if (workflow) {
     md += `\n## Workflow\n`;
-    for (const step of workflow) {
-      if (step.included) {
-        const label = `${step.phase.charAt(0).toUpperCase() + step.phase.slice(1)}: ${step.subStage.charAt(0).toUpperCase() + step.subStage.slice(1)}`;
+    for (const ws of workflow) {
+      if (ws.included) {
+        const label = `${ws.phase.charAt(0).toUpperCase() + ws.phase.slice(1)}: ${ws.step.charAt(0).toUpperCase() + ws.step.slice(1)}`;
         md += `- [ ] ${label}\n`;
       }
     }
@@ -93,7 +95,7 @@ ${description}
 
 function ensureGitignored(worktreeRoot: string): void {
   const gitignorePath = path.join(worktreeRoot, ".gitignore");
-  const entry = ".work-kit/";
+  const entry = `${STATE_DIR}/`;
 
   if (fs.existsSync(gitignorePath)) {
     const content = fs.readFileSync(gitignorePath, "utf-8");
@@ -105,14 +107,20 @@ function ensureGitignored(worktreeRoot: string): void {
 }
 
 export function initCommand(options: {
-  mode: "full" | "auto";
+  mode?: "full" | "auto";
   description: string;
   classification?: Classification;
   gated?: boolean;
   worktreeRoot?: string;
 }): Action {
-  const { mode, description, classification, gated } = options;
   const worktreeRoot = options.worktreeRoot || process.cwd();
+  const mainRepoRoot = resolveMainRepoRoot(worktreeRoot);
+  const projectConfig = loadProjectConfig(mainRepoRoot);
+
+  const mode = options.mode ?? projectConfig.defaults?.mode ?? "full";
+  const classification = options.classification ?? projectConfig.defaults?.classification;
+  const gated = options.gated ?? projectConfig.defaults?.gated ?? false;
+  const { description } = options;
 
   // Guard: don't overwrite existing state
   if (stateExists(worktreeRoot)) {
@@ -140,32 +148,32 @@ export function initCommand(options: {
   }
 
   const slug = toSlug(description);
-  const branch = `feature/${slug}`;
-  const modeLabel = mode === "full" ? "full-kit" : "auto-kit";
+  const branch = `${BRANCH_PREFIX}${slug}`;
+  const modeLabel = mode === "full" ? MODE_FULL : MODE_AUTO;
 
   // Build workflow
   let workflow: WorkflowStep[] | undefined;
   if (mode === "auto" && classification) {
-    workflow = buildDefaultWorkflow(classification);
+    workflow = buildDefaultWorkflow(classification, projectConfig.workflow);
   } else if (mode === "full") {
     workflow = buildFullWorkflow();
   }
 
-  // Find first active sub-stage
+  // Find first active step
   let firstPhase: PhaseName = "plan";
-  let firstSubStage = "clarify";
+  let firstStep = "clarify";
 
   if (workflow) {
     const first = workflow.find((s) => s.included);
     if (first) {
       firstPhase = first.phase;
-      firstSubStage = first.subStage;
+      firstStep = first.step;
     }
   }
 
   // Build state
   const state: WorkKitState = {
-    version: 1,
+    version: 2,
     slug,
     branch,
     started: new Date().toISOString(),
@@ -174,13 +182,13 @@ export function initCommand(options: {
     ...(classification && { classification }),
     status: "in-progress",
     currentPhase: firstPhase,
-    currentSubStage: firstSubStage,
+    currentStep: firstStep,
     phases: buildPhases(workflow),
     ...(mode === "auto" && workflow && { workflow }),
     loopbacks: [],
     metadata: {
       worktreeRoot,
-      mainRepoRoot: worktreeRoot, // will be set properly by caller
+      mainRepoRoot,
     },
   };
 
@@ -194,9 +202,9 @@ export function initCommand(options: {
   return {
     action: "spawn_agent",
     phase: firstPhase,
-    subStage: firstSubStage,
-    skillFile: skillFilePath(firstPhase, firstSubStage),
-    agentPrompt: `You are starting the ${firstPhase} phase. Begin with the ${firstSubStage} sub-stage. Read the skill file and follow its instructions. Write outputs to .work-kit/state.md.`,
-    onComplete: `npx work-kit-cli complete ${firstPhase}/${firstSubStage}`,
+    step: firstStep,
+    skillFile: skillFilePath(firstPhase, firstStep),
+    agentPrompt: `You are starting the ${firstPhase} phase. Begin with the ${firstStep} step. Read the skill file and follow its instructions. Write outputs to .work-kit/state.md.`,
+    onComplete: `${CLI_BINARY} complete ${firstPhase}/${firstStep}`,
   };
 }

package/cli/src/commands/loopback.ts

@@ -1,9 +1,9 @@
 import { readState, writeState, findWorktreeRoot } from "../state/store.js";
 import { parseLocation, resetToLocation } from "../state/helpers.js";
+import { countLoopbacksForRoute } from "../workflow/loopbacks.js";
+import { MAX_LOOPBACKS_PER_ROUTE } from "../config/constants.js";
 import type { Action } from "../state/schema.js";
 
-const MAX_LOOPBACKS_PER_ROUTE = 2;
-
 export function loopbackCommand(opts: {
   from: string;
   to: string;
@@ -19,23 +19,20 @@ export function loopbackCommand(opts: {
   const from = parseLocation(opts.from);
   const to = parseLocation(opts.to);
 
-  if (!state.phases[from.phase]?.subStages[from.subStage]) {
+  if (!state.phases[from.phase]?.steps[from.step]) {
     return { action: "error", message: `Invalid source: ${opts.from}` };
   }
-  if (!state.phases[to.phase]?.subStages[to.subStage]) {
+  if (!state.phases[to.phase]?.steps[to.step]) {
     return { action: "error", message: `Invalid target: ${opts.to}` };
   }
 
-  // Can't loop back to a skipped sub-stage
-  if (state.phases[to.phase].subStages[to.subStage].status === "skipped") {
+  // Can't loop back to a skipped step
+  if (state.phases[to.phase].steps[to.step].status === "skipped") {
     return { action: "error", message: `Cannot loop back to ${opts.to} — it is skipped.` };
   }
 
   // Enforce max loopback count per route
-  const sameRouteCount = state.loopbacks.filter(
-    (lb) => lb.from.phase === from.phase && lb.from.subStage === from.subStage
-      && lb.to.phase === to.phase && lb.to.subStage === to.subStage
-  ).length;
+  const sameRouteCount = countLoopbacksForRoute(state.loopbacks, from, to);
   if (sameRouteCount >= MAX_LOOPBACKS_PER_ROUTE) {
     return {
       action: "error",
@@ -52,7 +49,7 @@ export function loopbackCommand(opts: {
 
   resetToLocation(state, to);
   state.currentPhase = to.phase;
-  state.currentSubStage = to.subStage;
+  state.currentStep = to.step;
   writeState(root, state);
 
   return {

package/cli/src/commands/next.ts

@@ -1,9 +1,11 @@
-import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
-import { determineNextStep } from "../engine/transitions.js";
+import { readState, writeState, findWorktreeRoot, readStateMd, clearBlockingMarkers } from "../state/store.js";
+import { determineNextStep } from "../workflow/transitions.js";
 import { validatePhasePrerequisites } from "../state/validators.js";
 import { buildAgentPrompt } from "../context/prompt-builder.js";
-import { getParallelGroup } from "../engine/parallel.js";
-import { skillFilePath } from "../config/phases.js";
+import { getParallelGroup } from "../workflow/parallel.js";
+import { skillFilePath } from "../config/workflow.js";
+import { CLI_BINARY } from "../config/constants.js";
+
 import type { Action, PhaseName, WorkKitState } from "../state/schema.js";
 
 export function nextCommand(worktreeRoot?: string): Action {
@@ -12,6 +14,9 @@ export function nextCommand(worktreeRoot?: string): Action {
     return { action: "error", message: "No work-kit state found. Run `work-kit init` first." };
   }
 
+  // Forward state transition → clear any stale "blocked on user" markers
+  clearBlockingMarkers(root);
+
   const state = readState(root);
 
   if (state.status === "completed") {
@@ -22,17 +27,25 @@ export function nextCommand(worktreeRoot?: string): Action {
     return { action: "error", message: "Work-kit is in failed state.", suggestion: "Review the state and restart." };
   }
 
-  const step = determineNextStep(state);
+  if (state.status === "paused") {
+    return {
+      action: "error",
+      message: `Work-kit is paused (since ${state.pausedAt ?? "earlier"}).`,
+      suggestion: `Run \`${CLI_BINARY} resume\` to continue.`,
+    };
+  }
+
+  const nextStep = determineNextStep(state);
 
-  switch (step.type) {
+  switch (nextStep.type) {
     case "complete":
-      return { action: "complete", message: step.message! };
+      return { action: "complete", message: nextStep.message! };
 
     case "wait-for-user":
-      return { action: "wait_for_user", message: step.message! };
+      return { action: "wait_for_user", message: nextStep.message! };
 
     case "phase-boundary": {
-      const phase = step.phase!;
+      const phase = nextStep.phase!;
 
       const validation = validatePhasePrerequisites(state, phase);
       if (!validation.valid) {
@@ -47,78 +60,78 @@ export function nextCommand(worktreeRoot?: string): Action {
       state.phases[phase].status = "in-progress";
       state.phases[phase].startedAt = new Date().toISOString();
 
-      const subStages = Object.entries(state.phases[phase].subStages);
-      const firstActive = subStages.find(([_, ss]) => ss.status === "pending" || ss.status === "waiting");
+      const entries = Object.entries(state.phases[phase].steps);
+      const firstActive = entries.find(([_, s]) => s.status === "pending" || s.status === "waiting");
 
       if (!firstActive) {
-        return { action: "error", message: `No pending sub-stages in ${phase}` };
+        return { action: "error", message: `No pending steps in ${phase}` };
       }
 
-      const [subStage] = firstActive;
-      state.currentSubStage = subStage;
-      state.phases[phase].subStages[subStage].status = "in-progress";
-      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      const [step] = firstActive;
+      state.currentStep = step;
+      state.phases[phase].steps[step].status = "in-progress";
+      state.phases[phase].steps[step].startedAt = new Date().toISOString();
       writeState(root, state);
 
-      return buildSpawnAction(root, state, phase, subStage);
+      return buildSpawnAction(root, state, phase, step);
     }
 
-    case "sub-stage": {
-      const phase = step.phase!;
-      const subStage = step.subStage!;
+    case "step": {
+      const phase = nextStep.phase!;
+      const step = nextStep.step!;
 
       state.currentPhase = phase;
-      state.currentSubStage = subStage;
+      state.currentStep = step;
       if (state.phases[phase].status === "pending") {
         state.phases[phase].status = "in-progress";
         state.phases[phase].startedAt = new Date().toISOString();
       }
-      state.phases[phase].subStages[subStage].status = "in-progress";
-      state.phases[phase].subStages[subStage].startedAt = new Date().toISOString();
+      state.phases[phase].steps[step].status = "in-progress";
+      state.phases[phase].steps[step].startedAt = new Date().toISOString();
       writeState(root, state);
 
-      return buildSpawnAction(root, state, phase, subStage);
+      return buildSpawnAction(root, state, phase, step);
     }
 
     default:
-      return { action: "error", message: `Unknown step type: ${step.type}` };
+      return { action: "error", message: `Unknown step type: ${nextStep.type}` };
   }
 }
 
-function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, subStage: string): Action {
+function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, step: string): Action {
   // Read state.md once for all prompt builds
   const stateMd = readStateMd(root);
-  const parallelGroup = getParallelGroup(phase, subStage, state);
+  const parallelGroup = getParallelGroup(phase, step, state);
 
   if (parallelGroup) {
     const agents = parallelGroup.parallel
-      .filter((ss) => {
-        const ssState = state.phases[phase].subStages[ss];
-        return ssState && ssState.status !== "skipped" && ssState.status !== "completed";
+      .filter((s) => {
+        const sState = state.phases[phase].steps[s];
+        return sState && sState.status !== "skipped" && sState.status !== "completed";
       })
-      .map((ss) => ({
+      .map((s) => ({
         phase,
-        subStage: ss,
-        skillFile: skillFilePath(phase, ss),
-        agentPrompt: buildAgentPrompt(root, state, phase, ss, stateMd),
-        outputFile: `.work-kit/${phase}-${ss}.md`,
+        step: s,
+        skillFile: skillFilePath(phase, s),
+        agentPrompt: buildAgentPrompt(root, state, phase, s, stateMd),
+        outputFile: `.work-kit/${phase}-${s}.md`,
       }));
 
     // If all parallel members were filtered out, fall through to single agent
     if (agents.length === 0) {
       // Skip to thenSequential if it exists, otherwise nothing to do
       if (parallelGroup.thenSequential) {
-        const seqSS = parallelGroup.thenSequential;
+        const seqStep = parallelGroup.thenSequential;
         return {
           action: "spawn_agent",
           phase,
-          subStage: seqSS,
-          skillFile: skillFilePath(phase, seqSS),
-          agentPrompt: buildAgentPrompt(root, state, phase, seqSS, stateMd),
-          onComplete: `npx work-kit-cli complete ${phase}/${seqSS}`,
+          step: seqStep,
+          skillFile: skillFilePath(phase, seqStep),
+          agentPrompt: buildAgentPrompt(root, state, phase, seqStep, stateMd),
+          onComplete: `${CLI_BINARY} complete ${phase}/${seqStep}`,
         };
       }
-      return { action: "error", message: `No active sub-stages in parallel group for ${phase}` };
+      return { action: "error", message: `No active steps in parallel group for ${phase}` };
     }
 
     // If only 1 agent remains, run as single agent (no need for parallel)
@@ -127,22 +140,22 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
       return {
         action: "spawn_agent",
         phase: agent.phase,
-        subStage: agent.subStage,
+        step: agent.step,
         skillFile: agent.skillFile,
         agentPrompt: agent.agentPrompt,
-        onComplete: `npx work-kit-cli complete ${agent.phase}/${agent.subStage}`,
+        onComplete: `${CLI_BINARY} complete ${agent.phase}/${agent.step}`,
       };
     }
 
     for (const agent of agents) {
-      state.phases[phase].subStages[agent.subStage].status = "in-progress";
-      state.phases[phase].subStages[agent.subStage].startedAt = new Date().toISOString();
+      state.phases[phase].steps[agent.step].status = "in-progress";
+      state.phases[phase].steps[agent.step].startedAt = new Date().toISOString();
     }
 
     const thenSequential = parallelGroup.thenSequential
       ? {
           phase,
-          subStage: parallelGroup.thenSequential,
+          step: parallelGroup.thenSequential,
           skillFile: skillFilePath(phase, parallelGroup.thenSequential),
           agentPrompt: buildAgentPrompt(root, state, phase, parallelGroup.thenSequential, stateMd),
         }
@@ -154,19 +167,19 @@ function buildSpawnAction(root: string, state: WorkKitState, phase: PhaseName, s
       action: "spawn_parallel_agents",
       agents,
       thenSequential,
-      onComplete: `npx work-kit-cli complete ${phase}/${parallelGroup.thenSequential || parallelGroup.parallel[parallelGroup.parallel.length - 1]}`,
+      onComplete: `${CLI_BINARY} complete ${phase}/${parallelGroup.thenSequential || parallelGroup.parallel[parallelGroup.parallel.length - 1]}`,
     };
   }
 
-  const skill = skillFilePath(phase, subStage);
-  const prompt = buildAgentPrompt(root, state, phase, subStage, stateMd);
+  const skill = skillFilePath(phase, step);
+  const prompt = buildAgentPrompt(root, state, phase, step, stateMd);
 
   return {
     action: "spawn_agent",
     phase,
-    subStage,
+    step,
     skillFile: skill,
     agentPrompt: prompt,
-    onComplete: `npx work-kit-cli complete ${phase}/${subStage}`,
+    onComplete: `${CLI_BINARY} complete ${phase}/${step}`,
   };
 }

package/cli/src/commands/pause-resume.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, afterEach } from "node:test";
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { randomUUID } from "node:crypto";
+import { initCommand } from "./init.js";
+import { pauseCommand } from "./pause.js";
+import { resumeCommand } from "./resume.js";
+import { nextCommand } from "./next.js";
+import { bootstrapCommand } from "./bootstrap.js";
+import { completeCommand } from "./complete.js";
+
+function makeTmpDir(): string {
+  const dir = path.join(os.tmpdir(), `work-kit-pause-${randomUUID()}`);
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+let tmpDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  tmpDirs = [];
+});
+
+describe("pause / resume", () => {
+  it("pause flips status and records timestamp", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Pause test", worktreeRoot: tmp });
+
+    const result = pauseCommand("lunch", tmp);
+    assert.equal(result.action, "paused");
+
+    const tracker = JSON.parse(fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8"));
+    assert.equal(tracker.status, "paused");
+    assert.ok(tracker.pausedAt);
+  });
+
+  it("pause is idempotent — second pause errors", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Double pause", worktreeRoot: tmp });
+
+    pauseCommand(undefined, tmp);
+    const result = pauseCommand(undefined, tmp);
+    assert.equal(result.action, "error");
+  });
+
+  it("resume flips status back and clears pausedAt", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Resume test", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = resumeCommand(tmp);
+    assert.equal(result.action, "resumed");
+
+    const tracker = JSON.parse(fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8"));
+    assert.equal(tracker.status, "in-progress");
+    assert.equal(tracker.pausedAt, undefined);
+  });
+
+  it("resume on already in-progress is idempotent", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Already running", worktreeRoot: tmp });
+
+    const result = resumeCommand(tmp);
+    assert.equal(result.action, "resumed");
+  });
+
+  it("next refuses to advance a paused session", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Paused next", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = nextCommand(tmp);
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("paused"));
+    }
+  });
+
+  it("bootstrap --auto-resume flips paused → in-progress", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Auto resume", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = bootstrapCommand(tmp, { autoResume: true });
+    assert.equal(result.status, "in-progress");
+    assert.equal(result.resumed, true);
+  });
+
+  it("bootstrap without --auto-resume leaves paused state alone", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "No auto", worktreeRoot: tmp });
+    pauseCommand(undefined, tmp);
+
+    const result = bootstrapCommand(tmp);
+    assert.equal(result.status, "paused");
+    assert.notEqual(result.resumed, true);
+  });
+});
+
+describe("complete outcome validation", () => {
+  it("rejects invalid outcomes", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Outcome test", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", "totally-bogus", tmp);
+    assert.equal(result.action, "error");
+    if (result.action === "error") {
+      assert.ok(result.message.includes("Invalid outcome"));
+    }
+  });
+
+  it("accepts known outcomes", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "Outcome ok", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", "done", tmp);
+    assert.notEqual(result.action, "error");
+  });
+
+  it("accepts undefined outcome", () => {
+    const tmp = makeTmpDir();
+    tmpDirs.push(tmp);
+    initCommand({ mode: "full", description: "No outcome", worktreeRoot: tmp });
+
+    const result = completeCommand("plan/clarify", undefined, tmp);
+    assert.notEqual(result.action, "error");
+  });
+});

package/cli/src/commands/pause.ts

@@ -0,0 +1,34 @@
+import { readState, writeState, findWorktreeRoot } from "../state/store.js";
+import type { Action } from "../state/schema.js";
+
+export function pauseCommand(reason?: string, worktreeRoot?: string): Action {
+  const root = worktreeRoot || findWorktreeRoot();
+  if (!root) {
+    return { action: "error", message: "No work-kit state found." };
+  }
+
+  const state = readState(root);
+
+  if (state.status === "completed") {
+    return { action: "error", message: `${state.slug} is already completed; nothing to pause.` };
+  }
+  if (state.status === "paused") {
+    return { action: "error", message: `${state.slug} is already paused (since ${state.pausedAt}).` };
+  }
+  if (state.status === "failed") {
+    return { action: "error", message: `${state.slug} is in failed state; cannot pause.` };
+  }
+
+  state.status = "paused";
+  state.pausedAt = new Date().toISOString();
+  writeState(root, state);
+
+  const where = state.currentPhase
+    ? ` at ${state.currentPhase}${state.currentStep ? "/" + state.currentStep : ""}`
+    : "";
+
+  return {
+    action: "paused",
+    message: `Paused ${state.slug}${where}.${reason ? ` Reason: ${reason}` : ""} Run \`work-kit resume\` to continue.`,
+  };
+}