work-kit-cli 0.2.8 → 0.4.0

package/cli/src/state/helpers.ts

@@ -1,47 +1,59 @@
-import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "./schema.js";
+import { PHASE_NAMES, STEPS_BY_PHASE } from "./schema.js";
 import type { Location, PhaseName, WorkKitState } from "./schema.js";
-import { PHASE_ORDER } from "../config/phases.js";
 
 /**
- * Parse "phase/sub-stage" string into a Location object.
- * Validates that the phase is a known phase name and the sub-stage exists.
+ * Mutate a state object to flip a paused session into in-progress.
+ * Caller is responsible for persisting via writeState. Returns true
+ * when state changed, false when no transition was applicable.
+ */
+export function unpause(state: WorkKitState): boolean {
+  if (state.status !== "paused") return false;
+  state.status = "in-progress";
+  delete state.pausedAt;
+  return true;
+}
+import { PHASE_ORDER } from "../config/workflow.js";
+
+/**
+ * Parse "phase/step" string into a Location object.
+ * Validates that the phase is a known phase name and the step exists.
  */
 export function parseLocation(input: string): Location {
   const parts = input.split("/");
   if (parts.length !== 2) {
-    throw new Error(`Invalid location "${input}". Expected format: phase/sub-stage (e.g., plan/clarify)`);
+    throw new Error(`Invalid location "${input}". Expected format: phase/step (e.g., plan/clarify)`);
   }
-  const [phase, subStage] = parts;
+  const [phase, step] = parts;
   if (!PHASE_NAMES.includes(phase as PhaseName)) {
     throw new Error(`Unknown phase "${phase}". Valid phases: ${PHASE_NAMES.join(", ")}`);
   }
-  const validSubStages = SUBSTAGES_BY_PHASE[phase as PhaseName];
-  if (!validSubStages.includes(subStage)) {
-    throw new Error(`Unknown sub-stage "${subStage}" in phase "${phase}". Valid: ${validSubStages.join(", ")}`);
+  const validSteps = STEPS_BY_PHASE[phase as PhaseName];
+  if (!validSteps.includes(step)) {
+    throw new Error(`Unknown step "${step}" in phase "${phase}". Valid: ${validSteps.join(", ")}`);
   }
-  return { phase: phase as PhaseName, subStage };
+  return { phase: phase as PhaseName, step };
 }
 
 /**
- * Reset state from a target location forward: marks the target sub-stage
- * and all subsequent sub-stages/phases as pending.
+ * Reset state from a target location forward: marks the target step
+ * and all subsequent steps/phases as pending.
  */
 export function resetToLocation(state: WorkKitState, location: Location): void {
   const targetPhaseState = state.phases[location.phase];
   if (!targetPhaseState) {
     throw new Error(`Phase "${location.phase}" not found in state`);
   }
-  if (!targetPhaseState.subStages[location.subStage]) {
-    throw new Error(`Sub-stage "${location.subStage}" not found in phase "${location.phase}"`);
+  if (!targetPhaseState.steps[location.step]) {
+    throw new Error(`Step "${location.step}" not found in phase "${location.phase}"`);
   }
 
   let reset = false;
-  for (const [ss, ssState] of Object.entries(targetPhaseState.subStages)) {
-    if (ss === location.subStage) reset = true;
-    if (reset && (ssState.status === "completed" || ssState.status === "waiting")) {
-      ssState.status = "pending";
-      delete ssState.completedAt;
-      delete ssState.outcome;
+  for (const [s, sState] of Object.entries(targetPhaseState.steps)) {
+    if (s === location.step) reset = true;
+    if (reset && (sState.status === "completed" || sState.status === "waiting")) {
+      sState.status = "pending";
+      delete sState.completedAt;
+      delete sState.outcome;
     }
   }
   targetPhaseState.status = "in-progress";
@@ -53,11 +65,11 @@ export function resetToLocation(state: WorkKitState, location: Location): void {
     if (laterPhaseState.status === "completed") {
       laterPhaseState.status = "pending";
       delete laterPhaseState.completedAt;
-      for (const ssState of Object.values(laterPhaseState.subStages)) {
-        if (ssState.status === "completed") {
-          ssState.status = "pending";
-          delete ssState.completedAt;
-          delete ssState.outcome;
+      for (const sState of Object.values(laterPhaseState.steps)) {
+        if (sState.status === "completed") {
+          sState.status = "pending";
+          delete sState.completedAt;
+          delete sState.outcome;
         }
       }
     }

package/cli/src/state/schema.ts

@@ -1,61 +1,125 @@
-// ── Phase & Sub-stage Types ──────────────────────────────────────────
+// ── Phase & Step Types ──────────────────────────────────────────────
 
 export const PHASE_NAMES = ["plan", "build", "test", "review", "deploy", "wrap-up"] as const;
 export type PhaseName = (typeof PHASE_NAMES)[number];
 
-export const PLAN_SUBSTAGES = ["clarify", "investigate", "sketch", "scope", "ux-flow", "architecture", "blueprint", "audit"] as const;
-export const BUILD_SUBSTAGES = ["setup", "migration", "red", "core", "ui", "refactor", "integration", "commit"] as const;
-export const TEST_SUBSTAGES = ["verify", "e2e", "validate"] as const;
-export const REVIEW_SUBSTAGES = ["self-review", "security", "performance", "compliance", "handoff"] as const;
-export const DEPLOY_SUBSTAGES = ["merge", "monitor", "remediate"] as const;
-export const WRAPUP_SUBSTAGES = ["wrap-up"] as const;
-
-export type PlanSubStage = (typeof PLAN_SUBSTAGES)[number];
-export type BuildSubStage = (typeof BUILD_SUBSTAGES)[number];
-export type TestSubStage = (typeof TEST_SUBSTAGES)[number];
-export type ReviewSubStage = (typeof REVIEW_SUBSTAGES)[number];
-export type DeploySubStage = (typeof DEPLOY_SUBSTAGES)[number];
-export type WrapUpSubStage = (typeof WRAPUP_SUBSTAGES)[number];
-
-export type SubStageName = PlanSubStage | BuildSubStage | TestSubStage | ReviewSubStage | DeploySubStage | WrapUpSubStage;
-
-export const SUBSTAGES_BY_PHASE: Record<PhaseName, readonly string[]> = {
-  plan: PLAN_SUBSTAGES,
-  build: BUILD_SUBSTAGES,
-  test: TEST_SUBSTAGES,
-  review: REVIEW_SUBSTAGES,
-  deploy: DEPLOY_SUBSTAGES,
-  "wrap-up": WRAPUP_SUBSTAGES,
+export const PLAN_STEPS = ["clarify", "investigate", "sketch", "scope", "ux-flow", "architecture", "blueprint", "audit"] as const;
+export const BUILD_STEPS = ["setup", "migration", "red", "core", "ui", "refactor", "integration", "commit"] as const;
+export const TEST_STEPS = ["verify", "e2e", "validate"] as const;
+export const REVIEW_STEPS = ["self-review", "security", "performance", "compliance", "handoff"] as const;
+export const DEPLOY_STEPS = ["merge", "monitor", "remediate"] as const;
+export const WRAPUP_STEPS = ["summary", "knowledge"] as const;
+
+export type PlanStep = (typeof PLAN_STEPS)[number];
+export type BuildStep = (typeof BUILD_STEPS)[number];
+export type TestStep = (typeof TEST_STEPS)[number];
+export type ReviewStep = (typeof REVIEW_STEPS)[number];
+export type DeployStep = (typeof DEPLOY_STEPS)[number];
+export type WrapUpStep = (typeof WRAPUP_STEPS)[number];
+
+export type StepName = PlanStep | BuildStep | TestStep | ReviewStep | DeployStep | WrapUpStep;
+
+export const STEPS_BY_PHASE: Record<PhaseName, readonly string[]> = {
+  plan: PLAN_STEPS,
+  build: BUILD_STEPS,
+  test: TEST_STEPS,
+  review: REVIEW_STEPS,
+  deploy: DEPLOY_STEPS,
+  "wrap-up": WRAPUP_STEPS,
 };
 
-// ── Classification ───────────────────────────────────────────────────
+// ── Mode Constants ──────────────────────────────────────────────────
 
-export type Classification = "bug-fix" | "small-change" | "refactor" | "feature" | "large-feature";
+export const MODE_FULL = "full-kit" as const;
+export const MODE_AUTO = "auto-kit" as const;
 
-// ── Phase & Sub-stage State ──────────────────────────────────────────
+// ── Classification ──────────────────────────────────────────────────
+
+export const CLASSIFICATIONS = ["bug-fix", "small-change", "refactor", "feature", "large-feature"] as const;
+export type Classification = (typeof CLASSIFICATIONS)[number];
+
+export function isClassification(value: string): value is Classification {
+  return (CLASSIFICATIONS as readonly string[]).includes(value);
+}
+
+// ── Model Routing ───────────────────────────────────────────────────
+
+/**
+ * Concrete model tier a phase/step can be routed to.
+ * "inherit" is not a tier — see ModelPolicy for that.
+ */
+export const MODEL_TIERS = ["haiku", "sonnet", "opus"] as const;
+export type ModelTier = (typeof MODEL_TIERS)[number];
+
+export function isModelTier(value: string): value is ModelTier {
+  return (MODEL_TIERS as readonly string[]).includes(value);
+}
+
+/**
+ * Session-wide model policy set once at init time.
+ *
+ * - "auto"     — use work-kit's step-level routing (BY_STEP + BY_PHASE + classification)
+ * - "opus" | "sonnet" | "haiku" — force that tier for every agent, no exceptions
+ * - "inherit"  — emit no model field; let Claude Code's default pick (pre-change behavior)
+ *
+ * Per-step workspace/user JSON overrides still win over the policy.
+ */
+export const MODEL_POLICIES = ["auto", "opus", "sonnet", "haiku", "inherit"] as const;
+export type ModelPolicy = (typeof MODEL_POLICIES)[number];
+
+export function isModelPolicy(value: string): value is ModelPolicy {
+  return (MODEL_POLICIES as readonly string[]).includes(value);
+}
+
+// ── Step Outcomes ───────────────────────────────────────────────────
+
+/**
+ * Closed set of outcomes a step can report when completing.
+ * Outcomes drive loop-back routing (see config/loopback-routes.ts).
+ */
+export const STEP_OUTCOMES = [
+  "done",                // generic success
+  "ok",                  // alias for done
+  "proceed",             // explicit "no loopback, advance"
+  "approved",            // review/handoff cleared for deploy
+  "revise",              // audit / review found gaps; loop back to fix
+  "broken",              // refactor or change broke something downstream
+  "changes_requested",   // review handoff requested changes
+  "fix_needed",          // deploy merge blocked, fix required
+  "fix_and_redeploy",    // remediation requires another deploy cycle
+  "blocked",             // step cannot proceed without external input
+  "skipped",             // step intentionally skipped at runtime
+] as const;
+export type StepOutcome = (typeof STEP_OUTCOMES)[number];
+
+export function isStepOutcome(value: string): value is StepOutcome {
+  return (STEP_OUTCOMES as readonly string[]).includes(value);
+}
+
+// ── Phase & Step State ──────────────────────────────────────────────
 
 export type PhaseStatus = "pending" | "in-progress" | "completed" | "skipped";
-export type SubStageStatus = "pending" | "in-progress" | "completed" | "skipped" | "waiting";
+export type StepStatus = "pending" | "in-progress" | "completed" | "skipped" | "waiting";
 
-export interface SubStageState {
-  status: SubStageStatus;
-  outcome?: string;
+export interface StepState {
+  status: StepStatus;
+  outcome?: StepOutcome;
   startedAt?: string;
   completedAt?: string;
 }
 
 export interface PhaseState {
   status: PhaseStatus;
-  subStages: Record<string, SubStageState>;
+  steps: Record<string, StepState>;
   startedAt?: string;
   completedAt?: string;
 }
 
-// ── Loopback ─────────────────────────────────────────────────────────
+// ── Loopback ────────────────────────────────────────────────────────
 
 export interface Location {
   phase: PhaseName;
-  subStage: string;
+  step: string;
 }
 
 export interface LoopbackRecord {
@@ -65,27 +129,35 @@ export interface LoopbackRecord {
   timestamp: string;
 }
 
-// ── Workflow (auto-kit) ──────────────────────────────────────────────
+// ── Workflow (auto-kit) ─────────────────────────────────────────────
 
 export interface WorkflowStep {
   phase: PhaseName;
-  subStage: string;
+  step: string;
   included: boolean;
 }
 
-// ── Main State ───────────────────────────────────────────────────────
+// ── Work Status ─────────────────────────────────────────────────────
+
+export type WorkStatus = "in-progress" | "paused" | "completed" | "failed";
+
+// ── Main State ──────────────────────────────────────────────────────
 
 export interface WorkKitState {
-  version: 1;
+  version: 2;
   slug: string;
   branch: string;
   started: string;
-  mode: "full-kit" | "auto-kit";
+  mode: typeof MODE_FULL | typeof MODE_AUTO;
   gated?: boolean;
   classification?: Classification;
-  status: "in-progress" | "paused" | "completed" | "failed";
+  status: WorkStatus;
+  /** Session-wide model policy, set once at init. Defaults to "auto". */
+  modelPolicy?: ModelPolicy;
+  /** ISO timestamp the work was paused; cleared on resume. */
+  pausedAt?: string;
   currentPhase: PhaseName | null;
-  currentSubStage: string | null;
+  currentStep: string | null;
   phases: Record<PhaseName, PhaseState>;
   workflow?: WorkflowStep[];
   loopbacks: LoopbackRecord[];
@@ -95,20 +167,38 @@ export interface WorkKitState {
   };
 }
 
-// ── Actions (CLI → Claude) ───────────────────────────────────────────
+// ── Actions (CLI → Claude) ──────────────────────────────────────────
 
 export interface AgentSpec {
   phase: PhaseName;
-  subStage: string;
+  step: string;
   skillFile: string;
   agentPrompt: string;
-  outputFile?: string; // for parallel agents writing to separate files
+  outputFile?: string;
+  /** Resolved model tier for this agent. Omitted when policy is "inherit". */
+  model?: ModelTier;
 }
 
 export type Action =
-  | { action: "spawn_agent"; phase: PhaseName; subStage: string; skillFile: string; agentPrompt: string; onComplete: string }
+  | { action: "spawn_agent"; phase: PhaseName; step: string; skillFile: string; agentPrompt: string; onComplete: string; model?: ModelTier }
   | { action: "spawn_parallel_agents"; agents: AgentSpec[]; thenSequential?: AgentSpec; onComplete: string }
   | { action: "wait_for_user"; message: string }
   | { action: "loopback"; from: Location; to: Location; reason: string }
   | { action: "complete"; message: string }
+  | { action: "paused"; message: string }
+  | { action: "resumed"; message: string; phase: PhaseName | null; step: string | null; worktreeRoot?: string }
+  | { action: "select_session"; message: string; sessions: ResumableSessionSummary[] }
   | { action: "error"; message: string; suggestion?: string };
+
+export interface ResumableSessionSummary {
+  slug: string;
+  branch: string;
+  worktreeRoot: string;
+  status: Extract<WorkStatus, "paused" | "in-progress">;
+  pausedAt?: string;
+  currentPhase: string | null;
+  currentStep: string | null;
+  // Snapshot of how long ago tracker.json was last written, captured at
+  // CLI invocation. Lets the agent surface "closed by mistake" sessions.
+  lastUpdatedAgoMs: number;
+}

package/cli/src/state/store.ts

@@ -1,12 +1,30 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
+import { execFileSync } from "node:child_process";
 import { WorkKitState } from "./schema.js";
 
-const STATE_DIR = ".work-kit";
-const STATE_FILE = "tracker.json";
+export const STATE_DIR = ".work-kit";
+export const STATE_FILE = "tracker.json";
+export const STATE_MD_FILE = "state.md";
+export const AWAITING_INPUT_MARKER_FILE = "awaiting-input";
+export const IDLE_MARKER_FILE = "idle";
 
-// ── Worktree Discovery ───────────────────────────────────────────────
+/**
+ * Remove any "blocked on user" marker files (awaiting-input, idle).
+ *
+ * Hook-installed cleanup normally handles these (PostToolUse/Stop),
+ * but edge cases (denied permission, killed session, sentinel drift)
+ * can leave stale markers. Any forward state transition should clear
+ * them as a belt-and-suspenders safety net.
+ */
+export function clearBlockingMarkers(worktreeRoot: string): void {
+  const dir = path.join(worktreeRoot, STATE_DIR);
+  fs.rmSync(path.join(dir, AWAITING_INPUT_MARKER_FILE), { force: true });
+  fs.rmSync(path.join(dir, IDLE_MARKER_FILE), { force: true });
+}
+
+// ── Worktree Discovery ──────────────────────────────────────────────
 
 export function findWorktreeRoot(startDir?: string): string | null {
   let dir = startDir || process.cwd();
@@ -29,10 +47,10 @@ export function statePath(worktreeRoot: string): string {
 }
 
 export function stateMdPath(worktreeRoot: string): string {
-  return path.join(worktreeRoot, STATE_DIR, "state.md");
+  return path.join(worktreeRoot, STATE_DIR, STATE_MD_FILE);
 }
 
-// ── Read / Write ─────────────────────────────────────────────────────
+// ── Read / Write ────────────────────────────────────────────────────
 
 export function stateExists(worktreeRoot: string): boolean {
   return fs.existsSync(statePath(worktreeRoot));
@@ -44,11 +62,13 @@ export function readState(worktreeRoot: string): WorkKitState {
     throw new Error(`No tracker.json found at ${filePath}`);
   }
   const raw = fs.readFileSync(filePath, "utf-8");
+  let parsed: any;
   try {
-    return JSON.parse(raw) as WorkKitState;
+    parsed = JSON.parse(raw);
   } catch {
     throw new Error(`Corrupted tracker.json at ${filePath}. File contains invalid JSON.`);
   }
+  return migrateState(parsed, worktreeRoot);
 }
 
 export function writeState(worktreeRoot: string, state: WorkKitState): void {
@@ -62,7 +82,7 @@ export function writeState(worktreeRoot: string, state: WorkKitState): void {
   fs.renameSync(tmp, target);
 }
 
-// ── State.md ─────────────────────────────────────────────────────────
+// ── State.md ────────────────────────────────────────────────────────
 
 export function writeStateMd(worktreeRoot: string, content: string): void {
   const dir = stateDir(worktreeRoot);
@@ -80,3 +100,103 @@ export function readStateMd(worktreeRoot: string): string | null {
   if (!fs.existsSync(filePath)) return null;
   return fs.readFileSync(filePath, "utf-8");
 }
+
+// ── Git Helpers ─────────────────────────────────────────────────
+
+// Returns the main repo root for a given path inside a git repo, or null
+// if the path is not in a git repo. Unlike `git rev-parse --show-toplevel`,
+// this returns the *main* repo even when called from inside a worktree —
+// `git worktree list --porcelain` always lists the main repo first.
+export function gitMainRepoRoot(cwd: string): string | null {
+  try {
+    const output = execFileSync("git", ["worktree", "list", "--porcelain"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const firstLine = output.split("\n").find(l => l.startsWith("worktree "));
+    if (firstLine) return firstLine.slice("worktree ".length).trim();
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function resolveMainRepoRoot(worktreeRoot: string): string {
+  return gitMainRepoRoot(worktreeRoot) ?? worktreeRoot;
+}
+
+// Per-process cache. The HEAD SHA can drift mid-session in theory, but
+// every callsite either tags a stable artifact at session end (wrap-up)
+// or stamps an event during normal phase work — close enough for telemetry.
+const headShaCache = new Map<string, string>();
+
+/** Resolve the current HEAD commit SHA for `cwd`. Returns undefined outside a git repo. */
+export function gitHeadSha(cwd: string): string | undefined {
+  const cached = headShaCache.get(cwd);
+  if (cached !== undefined) return cached;
+  try {
+    const out = execFileSync("git", ["rev-parse", "HEAD"], {
+      cwd,
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (out) {
+      headShaCache.set(cwd, out);
+      return out;
+    }
+  } catch {
+    // ignore
+  }
+  return undefined;
+}
+
+// ── Migration ───────────────────────────────────────────────────────
+
+function migrateState(raw: any, worktreeRoot: string): WorkKitState {
+  if (raw.version === 2) return raw as WorkKitState;
+
+  // v1 → v2: rename subStage fields to step
+  if (raw.version === 1 || !raw.version) {
+    if ("currentSubStage" in raw) {
+      raw.currentStep = raw.currentSubStage;
+      delete raw.currentSubStage;
+    }
+
+    for (const phase of Object.values(raw.phases) as any[]) {
+      if (phase.subStages) {
+        phase.steps = phase.subStages;
+        delete phase.subStages;
+      }
+    }
+
+    if (raw.workflow) {
+      for (const ws of raw.workflow) {
+        if ("subStage" in ws) {
+          ws.step = ws.subStage;
+          delete ws.subStage;
+        }
+      }
+    }
+
+    if (raw.loopbacks) {
+      for (const lb of raw.loopbacks) {
+        if (lb.from?.subStage !== undefined) {
+          lb.from.step = lb.from.subStage;
+          delete lb.from.subStage;
+        }
+        if (lb.to?.subStage !== undefined) {
+          lb.to.step = lb.to.subStage;
+          delete lb.to.subStage;
+        }
+      }
+    }
+
+    raw.version = 2;
+    writeState(worktreeRoot, raw as WorkKitState);
+  }
+
+  return raw as WorkKitState;
+}

package/cli/src/state/validators.test.ts

@@ -1,27 +1,27 @@
 import { describe, it } from "node:test";
 import * as assert from "node:assert/strict";
 import { validatePhasePrerequisites } from "./validators.js";
-import type { WorkKitState, PhaseName, PhaseState, SubStageState } from "./schema.js";
-import { PHASE_NAMES, SUBSTAGES_BY_PHASE } from "./schema.js";
+import type { WorkKitState, PhaseName, PhaseState, StepState } from "./schema.js";
+import { PHASE_NAMES, STEPS_BY_PHASE } from "./schema.js";
 
 function makeState(): WorkKitState {
   const phases = {} as Record<PhaseName, PhaseState>;
   for (const phase of PHASE_NAMES) {
-    const subStages: Record<string, SubStageState> = {};
-    for (const ss of SUBSTAGES_BY_PHASE[phase]) {
-      subStages[ss] = { status: "pending" };
+    const steps: Record<string, StepState> = {};
+    for (const s of STEPS_BY_PHASE[phase]) {
+      steps[s] = { status: "pending" };
     }
-    phases[phase] = { status: "pending", subStages };
+    phases[phase] = { status: "pending", steps };
   }
   return {
-    version: 1,
+    version: 2,
     slug: "test",
     branch: "feature/test",
     started: "2026-01-01",
     mode: "full-kit",
     status: "in-progress",
     currentPhase: "plan",
-    currentSubStage: "clarify",
+    currentStep: "clarify",
     phases,
     loopbacks: [],
     metadata: { worktreeRoot: "/tmp/test", mainRepoRoot: "/tmp/test" },
@@ -31,9 +31,9 @@ function makeState(): WorkKitState {
 function completePhase(state: WorkKitState, phase: PhaseName): void {
   state.phases[phase].status = "completed";
   state.phases[phase].completedAt = "2026-01-01";
-  for (const ss of Object.values(state.phases[phase].subStages)) {
-    ss.status = "completed";
-    ss.completedAt = "2026-01-01";
+  for (const s of Object.values(state.phases[phase].steps)) {
+    s.status = "completed";
+    s.completedAt = "2026-01-01";
   }
 }
 
@@ -65,7 +65,7 @@ describe("validatePhasePrerequisites", () => {
     completePhase(state, "test");
     completePhase(state, "review");
     // handoff completed but without "approved" outcome
-    state.phases.review.subStages.handoff.outcome = "pending_review";
+    state.phases.review.steps.handoff.outcome = "blocked";
     const result = validatePhasePrerequisites(state, "deploy");
     assert.equal(result.valid, false);
   });
@@ -76,7 +76,7 @@ describe("validatePhasePrerequisites", () => {
     completePhase(state, "build");
     completePhase(state, "test");
     completePhase(state, "review");
-    state.phases.review.subStages.handoff.outcome = "approved";
+    state.phases.review.steps.handoff.outcome = "approved";
     const result = validatePhasePrerequisites(state, "deploy");
     assert.equal(result.valid, true);
   });

package/cli/src/state/validators.ts

@@ -1,5 +1,5 @@
 import { WorkKitState, PhaseName } from "./schema.js";
-import { PHASE_PREREQUISITES } from "../config/phases.js";
+import { PHASE_PREREQUISITES } from "../config/workflow.js";
 
 export interface ValidationResult {
   valid: boolean;
@@ -35,7 +35,6 @@ export function validatePhasePrerequisites(state: WorkKitState, phase: PhaseName
       };
     }
 
-    // deploy completed, skipped, or pending (never started) — all ok if review is done
     return { valid: true, message: "Prerequisites met for wrap-up" };
   }
 
@@ -49,11 +48,11 @@ export function validatePhasePrerequisites(state: WorkKitState, phase: PhaseName
         missingPrerequisite: "review",
       };
     }
-    const handoff = reviewState.subStages["handoff"];
+    const handoff = reviewState.steps["handoff"];
     if (!handoff) {
       return {
         valid: false,
-        message: `deploy requires review/handoff to exist and be approved. Handoff sub-stage not found.`,
+        message: `deploy requires review/handoff to exist and be approved. Handoff step not found.`,
         missingPrerequisite: "review",
       };
     }

package/cli/src/utils/colors.ts

@@ -17,7 +17,9 @@ export const bgCyan = (s: string) => `${code(46)}${code(30)}${s}${reset}`;
 export const bgRed = (s: string) => `${code(41)}${code(97)}${s}${reset}`;
 export const bgDim = (s: string) => `${code(100)}${code(97)}${s}${reset}`;
 export const bgMagenta = (s: string) => `${code(45)}${code(97)}${s}${reset}`;
+export const bgBlue = (s: string) => `${code(44)}${code(97)}${s}${reset}`;
 export const boldCyan = (s: string) => `${code(1)}${code(36)}${s}${reset}`;
 export const boldGreen = (s: string) => `${code(1)}${code(32)}${s}${reset}`;
 export const boldYellow = (s: string) => `${code(1)}${code(33)}${s}${reset}`;
 export const boldRed = (s: string) => `${code(1)}${code(31)}${s}${reset}`;
+export const boldMagenta = (s: string) => `${code(1)}${code(35)}${s}${reset}`;

package/cli/src/utils/fs.ts

@@ -0,0 +1,13 @@
+import * as fs from "node:fs";
+import { randomUUID } from "node:crypto";
+
+/**
+ * Crash-safe write: write to a temp file in the same directory, then rename.
+ * The rename is atomic on POSIX, so a partial file never appears at `target`.
+ * Used for any file that may be read concurrently or that must survive a crash.
+ */
+export function atomicWriteFile(target: string, content: string): void {
+  const tmp = target + "." + randomUUID().slice(0, 8) + ".tmp";
+  fs.writeFileSync(tmp, content, "utf-8");
+  fs.renameSync(tmp, target);
+}

package/cli/src/utils/json.ts

@@ -0,0 +1,20 @@
+import * as fs from "node:fs";
+
+/**
+ * Read and parse a JSON file. Returns null when the file is missing,
+ * unreadable, or contains invalid JSON. Use only when null is a meaningful
+ * "no config" answer; use direct fs/JSON for hard-required files.
+ */
+export function readJsonFile<T>(filePath: string): T | null {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}