work-kit-cli 0.2.6 → 0.2.8

package/README.md

@@ -81,7 +81,7 @@ Phases communicate through **Final sections** in `.work-kit/state.md`. Each phas
 
 Dual state files in `.work-kit/`:
 
-- **state.json** — state machine (current phase, sub-stage, transitions, loop-back counts)
+- **tracker.json** — state machine (current phase, sub-stage, transitions, loop-back counts)
 - **state.md** — content (working notes, Final sections, accumulated context)
 
 All writes are atomic to prevent state corruption.
@@ -105,10 +105,12 @@ Any stage can route back to a previous stage. Each route is enforced with a max
 
 ```
 .work-kit-tracker/
-  2026-04-03-avatar-upload.md        # distilled summary
+  index.md                              # log of all completed work (links to summaries + archives)
   archive/
-    2026-04-03-avatar-upload.md      # full state.md copy
-  index.md                           # log of all completed work
+    avatar-upload-2026-04-03/
+      state.md                          # full phase outputs
+      tracker.json                      # full JSON tracker (phases, timing, status)
+      summary.md                        # distilled wrap-up summary
 ```
 
 ## Repo structure

package/cli/src/commands/bootstrap.test.ts

@@ -61,8 +61,8 @@ describe("bootstrapCommand", () => {
       worktreeRoot: tmp,
     });
 
-    // Backdate the state.json file to 3 hours ago
-    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    // Backdate the tracker.json file to 3 hours ago
+    const stateFile = path.join(tmp, ".work-kit", "tracker.json");
     const threeHoursAgo = new Date(Date.now() - 3 * 60 * 60 * 1000);
     fs.utimesSync(stateFile, threeHoursAgo, threeHoursAgo);
 
@@ -83,7 +83,7 @@ describe("bootstrapCommand", () => {
     });
 
     // Manually set status to completed
-    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    const stateFile = path.join(tmp, ".work-kit", "tracker.json");
     const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
     state.status = "completed";
     fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));
@@ -104,7 +104,7 @@ describe("bootstrapCommand", () => {
       worktreeRoot: tmp,
     });
 
-    const stateFile = path.join(tmp, ".work-kit", "state.json");
+    const stateFile = path.join(tmp, ".work-kit", "tracker.json");
     const state = JSON.parse(fs.readFileSync(stateFile, "utf-8"));
     state.status = "failed";
     fs.writeFileSync(stateFile, JSON.stringify(state, null, 2));

package/cli/src/commands/complete.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execFileSync } from "node:child_process";
-import { readState, writeState, findWorktreeRoot, readStateMd } from "../state/store.js";
+import { readState, writeState, findWorktreeRoot, readStateMd, statePath } from "../state/store.js";
 import { isPhaseComplete, nextSubStageInPhase } from "../engine/transitions.js";
 import { checkLoopback } from "../engine/loopbacks.js";
 import { PHASE_ORDER } from "../config/phases.js";
@@ -165,16 +165,31 @@ function archiveCompleted(worktreeRoot: string, state: WorkKitState): void {
   const date = new Date().toISOString().split("T")[0];
   const slug = state.slug;
   const wkDir = path.join(mainRoot, ".work-kit-tracker");
-  const archiveDir = path.join(wkDir, "archive");
+  const folderName = `${slug}-${date}`;
+  const archiveDir = path.join(wkDir, "archive", folderName);
 
-  // Ensure directories exist
+  // Ensure archive folder exists
   fs.mkdirSync(archiveDir, { recursive: true });
 
-  // Archive state.md
+  // Archive state.md (full phase outputs)
   const stateMd = readStateMd(worktreeRoot);
   if (stateMd) {
-    const archivePath = path.join(archiveDir, `${date}-${slug}.md`);
-    fs.writeFileSync(archivePath, stateMd, "utf-8");
+    fs.writeFileSync(path.join(archiveDir, "state.md"), stateMd, "utf-8");
+  }
+
+  // Archive tracker.json (full JSON with phases, timing, status)
+  const trackerPath = statePath(worktreeRoot);
+  if (fs.existsSync(trackerPath)) {
+    fs.copyFileSync(trackerPath, path.join(archiveDir, "tracker.json"));
+  }
+
+  // Write placeholder summary.md (wrap-up skill will overwrite with distilled summary)
+  const summaryPath = path.join(archiveDir, "summary.md");
+  if (!fs.existsSync(summaryPath)) {
+    const completedPhases = PHASE_ORDER
+      .filter(p => state.phases[p].status === "completed")
+      .join("→");
+    fs.writeFileSync(summaryPath, `---\nslug: ${slug}\nbranch: ${state.branch}\nstarted: ${state.started.split("T")[0]}\ncompleted: ${date}\nstatus: completed\n---\n\n## Summary\n\nPhases: ${completedPhases}\n\n_Pending wrap-up summary._\n`, "utf-8");
   }
 
   // Compute completed phases
@@ -182,15 +197,17 @@ function archiveCompleted(worktreeRoot: string, state: WorkKitState): void {
     .filter(p => state.phases[p].status === "completed")
     .join("→");
 
-  // Append to index.md
+  // Append to index.md with links to summary and archive folder
   const indexPath = path.join(wkDir, "index.md");
   let indexContent = "";
   if (fs.existsSync(indexPath)) {
     indexContent = fs.readFileSync(indexPath, "utf-8");
   }
   if (!indexContent.includes("| Date ")) {
-    indexContent = "| Date | Slug | PR | Status | Phases |\n| --- | --- | --- | --- | --- |\n";
+    indexContent = "| Date | Slug | PR | Status | Phases | Summary | Archive |\n| --- | --- | --- | --- | --- | --- | --- |\n";
   }
-  indexContent += `| ${date} | ${slug} | n/a | completed | ${completedPhases} |\n`;
+  const summaryLink = `[summary](archive/${folderName}/summary.md)`;
+  const archiveLink = `[archive](archive/${folderName}/)`;
+  indexContent += `| ${date} | ${slug} | n/a | completed | ${completedPhases} | ${summaryLink} | ${archiveLink} |\n`;
   fs.writeFileSync(indexPath, indexContent, "utf-8");
 }

package/cli/src/commands/doctor.ts

@@ -65,10 +65,10 @@ export function doctorCommand(worktreeRoot?: string): { ok: boolean; checks: Che
       if (state.version === 1 && state.slug && state.status) {
         checks.push({ name: "state", status: "pass", message: `Active work-kit: "${state.slug}" (${state.status})` });
       } else {
-        checks.push({ name: "state", status: "warn", message: "state.json exists but has unexpected structure" });
+        checks.push({ name: "state", status: "warn", message: "tracker.json exists but has unexpected structure" });
       }
     } catch (e: any) {
-      checks.push({ name: "state", status: "warn", message: `state.json error: ${e.message}` });
+      checks.push({ name: "state", status: "warn", message: `tracker.json error: ${e.message}` });
     }
   } else {
     checks.push({ name: "state", status: "pass", message: "No active work-kit (OK — run `work-kit init` to start)" });

package/cli/src/commands/init.test.ts

@@ -22,7 +22,7 @@ afterEach(() => {
 });
 
 describe("initCommand", () => {
-  it("creates state.json and state.md", () => {
+  it("creates tracker.json and state.md", () => {
     const tmp = makeTmpDir();
     tmpDirs.push(tmp);
 
@@ -32,11 +32,11 @@ describe("initCommand", () => {
       worktreeRoot: tmp,
     });
 
-    assert.ok(fs.existsSync(path.join(tmp, ".work-kit", "state.json")));
+    assert.ok(fs.existsSync(path.join(tmp, ".work-kit", "tracker.json")));
     assert.ok(fs.existsSync(path.join(tmp, ".work-kit", "state.md")));
 
     const state = JSON.parse(
-      fs.readFileSync(path.join(tmp, ".work-kit", "state.json"), "utf-8")
+      fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8")
     );
     assert.equal(state.slug, "add-user-login");
     assert.equal(state.status, "in-progress");
@@ -108,7 +108,7 @@ describe("initCommand", () => {
     assert.equal(result.action, "spawn_agent");
 
     const state = JSON.parse(
-      fs.readFileSync(path.join(tmp, ".work-kit", "state.json"), "utf-8")
+      fs.readFileSync(path.join(tmp, ".work-kit", "tracker.json"), "utf-8")
     );
     assert.equal(state.mode, "auto-kit");
     assert.equal(state.classification, "bug-fix");

package/cli/src/commands/init.ts

@@ -119,7 +119,7 @@ export function initCommand(options: {
     return {
       action: "error",
       message: "State already exists in this directory. Use `work-kit status` to check current state.",
-      suggestion: "To start fresh, delete .work-kit/state.json first.",
+      suggestion: "To start fresh, delete .work-kit/tracker.json first.",
     };
   }
 

package/cli/src/commands/uninstall.ts

@@ -52,9 +52,9 @@ export async function uninstallCommand(targetPath?: string): Promise<void> {
   }
 
   // Check for active state
-  const stateFile = path.join(projectDir, ".work-kit", "state.json");
-  if (fs.existsSync(stateFile)) {
-    console.error(yellow("\nWarning: Active work-kit state found (.work-kit/state.json)."));
+  const trackerFile = path.join(projectDir, ".work-kit", "tracker.json");
+  if (fs.existsSync(trackerFile)) {
+    console.error(yellow("\nWarning: Active work-kit state found (.work-kit/tracker.json)."));
     console.error(yellow("Uninstalling will not remove in-progress state files."));
   }
 

package/cli/src/observer/data.ts

@@ -18,7 +18,11 @@ export interface WorkItemView {
   currentPhaseStartedAt?: string;
   currentSubStageStatus?: string;
   currentSubStageIndex?: number;
+  currentSubStageStartedAt?: string;
   currentPhaseTotal?: number;
+  gated: boolean;
+  worktreePath: string;
+  phaseSubStages: { name: string; status: string; startedAt?: string; completedAt?: string; outcome?: string }[];
   startedAt: string;
   progress: { completed: number; total: number; percent: number };
   phases: { name: string; status: string; startedAt?: string; completedAt?: string }[];
@@ -95,7 +99,9 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
   let currentPhaseStartedAt: string | undefined;
   let currentSubStageStatus: string | undefined;
   let currentSubStageIndex: number | undefined;
+  let currentSubStageStartedAt: string | undefined;
   let currentPhaseTotal: number | undefined;
+  let phaseSubStages: WorkItemView["phaseSubStages"] = [];
 
   for (const phaseName of phaseList) {
     const phase = state.phases[phaseName];
@@ -143,7 +149,18 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
           currentSubStageIndex = idx >= 0 ? idx + 1 : undefined;
           const ss = phase.subStages[state.currentSubStage];
           currentSubStageStatus = ss?.status;
+          currentSubStageStartedAt = ss?.startedAt;
         }
+        phaseSubStages = activeKeys.map(key => {
+          const ss = phase.subStages[key];
+          return {
+            name: key,
+            status: ss.status,
+            startedAt: ss.startedAt,
+            completedAt: ss.completedAt,
+            outcome: ss.outcome,
+          };
+        });
       }
     }
   }
@@ -174,7 +191,11 @@ export function collectWorkItem(worktreeRoot: string): WorkItemView | null {
     currentPhaseStartedAt,
     currentSubStageStatus,
     currentSubStageIndex,
+    currentSubStageStartedAt,
     currentPhaseTotal,
+    gated: state.gated ?? false,
+    worktreePath: state.metadata.worktreeRoot,
+    phaseSubStages,
     startedAt: state.started,
     progress: { completed, total, percent },
     phases: phaseViews,

package/cli/src/observer/renderer.ts

@@ -1,6 +1,37 @@
-import { bold, dim, green, yellow, red, cyan, bgYellow } from "../utils/colors.js";
+import {
+  bold, dim, green, yellow, red, cyan, magenta,
+  bgYellow, bgCyan, bgRed, bgMagenta,
+  boldCyan, boldGreen,
+} from "../utils/colors.js";
 import type { DashboardData, WorkItemView, CompletedItemView } from "./data.js";
 
+// ── Spinners & Animation Frames ─────────────────────────────────────
+
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const PULSE = ["◐", "◓", "◑", "◒"];
+
+function spinner(tick: number): string {
+  return cyan(SPINNER[tick % SPINNER.length]);
+}
+
+function pulse(tick: number): string {
+  return PULSE[tick % PULSE.length];
+}
+
+// ── Mascot ──────────────────────────────────────────────────────────
+
+function mascot(tick: number, hasActive: boolean): string {
+  if (!hasActive) {
+    // Idle — sleeping wrench
+    const faces = ["⚙ zzZ", "⚙  zZ", "⚙   z"];
+    return dim(faces[tick % faces.length]);
+  }
+  // Working — animated gear
+  const gears = ["⚙", "⚙", "⚙", "⚙"];
+  const sparks = ["·", "✦", "·", "✧"];
+  return cyan(gears[tick % gears.length]) + yellow(sparks[tick % sparks.length]);
+}
+
 // ── Time Formatting ─────────────────────────────────────────────────
 
 function formatTimeAgo(dateStr: string): string {
@@ -8,10 +39,7 @@ function formatTimeAgo(dateStr: string): string {
   const then = new Date(dateStr).getTime();
   if (isNaN(then)) return "unknown";
 
-  // If only a date (no time component), show the date string as-is
-  // to avoid misleading hour-level precision
   const isDateOnly = /^\d{4}-\d{2}-\d{2}$/.test(dateStr);
-
   const diffMs = now - then;
   const minutes = Math.floor(diffMs / 60000);
   const hours = Math.floor(diffMs / 3600000);
@@ -35,14 +63,31 @@ function formatTimeAgo(dateStr: string): string {
   return `${weeks}w ago`;
 }
 
+function formatDuration(startStr: string): string {
+  const now = Date.now();
+  const start = new Date(startStr).getTime();
+  if (isNaN(start)) return "";
+  const diffMs = now - start;
+  const sec = Math.floor(diffMs / 1000);
+  if (sec < 60) return `${sec}s`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m`;
+  const hr = Math.floor(min / 60);
+  const remMin = min % 60;
+  return remMin > 0 ? `${hr}h${remMin}m` : `${hr}h`;
+}
+
 // ── Box Drawing ─────────────────────────────────────────────────────
 
 function horizontalLine(width: number): string {
   return "═".repeat(Math.max(0, width - 2));
 }
 
+function thinLine(width: number): string {
+  return "─".repeat(Math.max(0, width));
+}
+
 function padRight(text: string, width: number): string {
-  // Strip ANSI codes for length calculation
   const plainLen = stripAnsi(text).length;
   const padding = Math.max(0, width - plainLen);
   return text + " ".repeat(padding);
@@ -52,14 +97,6 @@ function stripAnsi(s: string): string {
   return s.replace(/\x1b\[[0-9;]*m/g, "");
 }
 
-function centerText(text: string, width: number): string {
-  const plainLen = stripAnsi(text).length;
-  const totalPad = Math.max(0, width - plainLen);
-  const leftPad = Math.floor(totalPad / 2);
-  const rightPad = totalPad - leftPad;
-  return " ".repeat(leftPad) + text + " ".repeat(rightPad);
-}
-
 function boxLine(content: string, innerWidth: number): string {
   return `║ ${padRight(content, innerWidth)} ║`;
 }
@@ -70,22 +107,40 @@ function emptyBoxLine(innerWidth: number): string {
 
 // ── Progress Bar ────────────────────────────────────────────────────
 
+function progressColor(percent: number): (s: string) => string {
+  if (percent >= 75) return green;
+  if (percent >= 50) return cyan;
+  if (percent >= 25) return yellow;
+  return red;
+}
+
 function renderProgressBar(
   completed: number,
   total: number,
   percent: number,
-  label: string,
-  maxBarWidth: number
+  maxBarWidth: number,
+  tick: number
 ): string {
   const barWidth = Math.max(20, Math.min(40, maxBarWidth));
   const filled = total > 0 ? Math.round((completed / total) * barWidth) : 0;
   const empty = barWidth - filled;
 
-  const filledStr = green("█".repeat(filled));
+  const colorFn = progressColor(percent);
+
+  // Animated head on the progress bar
+  let filledStr: string;
+  if (filled > 0 && filled < barWidth) {
+    const body = colorFn("█".repeat(filled - 1));
+    const head = tick % 2 === 0 ? colorFn("▓") : colorFn("█");
+    filledStr = body + head;
+  } else {
+    filledStr = colorFn("█".repeat(filled));
+  }
+
   const emptyStr = dim("░".repeat(empty));
-  const stats = `${label}  ${completed}/${total}  ${percent}%`;
+  const stats = dim(`${completed}/${total}`) + "  " + colorFn(`${percent}%`);
 
-  return `${filledStr}${emptyStr}   ${stats}`;
+  return `${filledStr}${emptyStr}  ${stats}`;
 }
 
 // ── Phase Status Indicators ─────────────────────────────────────────
@@ -93,7 +148,7 @@ function renderProgressBar(
 function phaseIndicator(status: string, tick: number = 0): string {
   switch (status) {
     case "completed": return green("✓");
-    case "in-progress": return tick % 2 === 0 ? cyan("▶") : dim("▶");
+    case "in-progress": return spinner(tick);
     case "waiting": return tick % 2 === 0 ? yellow("◉") : dim("◉");
     case "pending": return dim("·");
     case "skipped": return dim("⊘");
@@ -102,6 +157,28 @@ function phaseIndicator(status: string, tick: number = 0): string {
   }
 }
 
+function subStageIndicator(status: string, tick: number): string {
+  switch (status) {
+    case "completed": return green("●");
+    case "in-progress": return cyan(pulse(tick));
+    case "waiting": return yellow("○");
+    case "pending": return dim("○");
+    case "skipped": return dim("⊘");
+    case "failed": return red("●");
+    default: return dim("○");
+  }
+}
+
+function phaseName(name: string, status: string, tick: number): string {
+  switch (status) {
+    case "completed": return boldGreen(name);
+    case "in-progress": return tick % 2 === 0 ? boldCyan(name) : bold(cyan(name));
+    case "waiting": return bold(yellow(name));
+    case "failed": return bold(red(name));
+    default: return dim(name);
+  }
+}
+
 function statusDot(status: string): string {
   switch (status) {
     case "in-progress": return green("●");
@@ -112,82 +189,250 @@ function statusDot(status: string): string {
   }
 }
 
-// ── Render Work Item ────────────────────────────────────────────────
+// ── Badges ──────────────────────────────────────────────────────────
+
+function renderModeBadge(mode: string): string {
+  return mode === "full-kit" ? bgCyan(" Full Kit ") : bgYellow(" Auto Kit ");
+}
 
-function formatMode(mode: string, classification?: string): string {
-  const label = mode === "full-kit" ? "Full Kit" : "Auto Kit";
-  return classification ? `${label} · ${classification}` : label;
+function renderGatedBadge(): string {
+  return bgMagenta(" GATED ");
 }
 
-function renderWorkItem(item: WorkItemView, innerWidth: number, tick: number = 0): string[] {
+// ── Phase Pipeline ──────────────────────────────────────────────────
+
+function phaseDuration(p: { status: string; startedAt?: string; completedAt?: string }): string {
+  if (p.status === "completed" && p.startedAt && p.completedAt) {
+    const ms = new Date(p.completedAt).getTime() - new Date(p.startedAt).getTime();
+    const sec = Math.floor(ms / 1000);
+    if (sec < 60) return `${sec}s`;
+    const min = Math.floor(sec / 60);
+    if (min < 60) return `${min}m`;
+    const hr = Math.floor(min / 60);
+    const remMin = min % 60;
+    return remMin > 0 ? `${hr}h${remMin}m` : `${hr}h`;
+  }
+  if (p.status === "in-progress" && p.startedAt) {
+    return formatDuration(p.startedAt);
+  }
+  if (p.status === "waiting" && p.startedAt) {
+    return formatDuration(p.startedAt);
+  }
+  return "";
+}
+
+function renderPhasePipeline(
+  phases: WorkItemView["phases"],
+  tick: number
+): string[] {
+  const connector = dim(" ── ");
+  const connectorLen = 4; // " ── "
+
+  // Build top line (icons + names) and bottom line (timing, aligned)
+  const topParts: string[] = [];
+  const bottomParts: string[] = [];
+
+  for (let i = 0; i < phases.length; i++) {
+    const p = phases[i];
+    const icon = phaseIndicator(p.status, tick);
+    const name = phaseName(p.name, p.status, tick);
+    const segment = `${icon} ${name}`;
+    topParts.push(segment);
+
+    // Calculate plain width of this segment for alignment
+    const segPlainLen = stripAnsi(segment).length;
+    const dur = phaseDuration(p);
+
+    if (dur) {
+      // Color the duration based on status
+      let durStyled: string;
+      if (p.status === "completed") durStyled = dim(dur);
+      else if (p.status === "in-progress") durStyled = cyan(dur);
+      else if (p.status === "waiting") durStyled = yellow(dur);
+      else durStyled = dim(dur);
+
+      // Center the duration under the segment
+      const durPlainLen = stripAnsi(durStyled).length;
+      const pad = Math.max(0, Math.floor((segPlainLen - durPlainLen) / 2));
+      bottomParts.push(" ".repeat(pad) + durStyled + " ".repeat(Math.max(0, segPlainLen - durPlainLen - pad)));
+    } else {
+      bottomParts.push(" ".repeat(segPlainLen));
+    }
+
+    // Add connector spacing to bottom line too
+    if (i < phases.length - 1) {
+      bottomParts.push(" ".repeat(connectorLen));
+    }
+  }
+
+  const topLine = topParts.join(connector);
+  const bottomLine = bottomParts.join("");
+
+  // Only show bottom line if there's at least one duration
+  const hasAnyDuration = phases.some(p => phaseDuration(p) !== "");
+  if (hasAnyDuration) {
+    return [topLine, bottomLine];
+  }
+  return [topLine];
+}
+
+// ── Sub-Stage Detail Box ────────────────────────────────────────────
+
+function renderSubStageBox(
+  item: WorkItemView,
+  innerWidth: number,
+  tick: number
+): string[] {
+  const subs = item.phaseSubStages;
+  if (!subs || subs.length === 0 || !item.currentPhase) return [];
+
+  const lines: string[] = [];
+  const label = dim(item.currentPhase);
+  const boxInner = innerWidth - 8; // indent + border padding
+
+  // Top border with phase label
+  const labelLen = stripAnsi(label).length;
+  const topRule = dim("┌─ ") + label + dim(" " + "─".repeat(Math.max(0, boxInner - labelLen - 2)) + "┐");
+  lines.push("  " + topRule);
+
+  // Render sub-stages in rows that fit the width
+  const entries: string[] = [];
+  for (const ss of subs) {
+    const icon = subStageIndicator(ss.status, tick);
+    let nameStr: string;
+    switch (ss.status) {
+      case "completed": nameStr = green(ss.name); break;
+      case "in-progress": nameStr = boldCyan(ss.name); break;
+      case "waiting": nameStr = yellow(ss.name); break;
+      case "failed": nameStr = red(ss.name); break;
+      default: nameStr = dim(ss.name);
+    }
+    // Add duration for completed or in-progress
+    let duration = "";
+    if (ss.status === "completed" && ss.startedAt && ss.completedAt) {
+      const ms = new Date(ss.completedAt).getTime() - new Date(ss.startedAt).getTime();
+      const sec = Math.floor(ms / 1000);
+      if (sec < 60) duration = dim(` ${sec}s`);
+      else duration = dim(` ${Math.floor(sec / 60)}m`);
+    } else if (ss.status === "in-progress" && ss.startedAt) {
+      duration = dim(` ${formatDuration(ss.startedAt)}`);
+    }
+    entries.push(`${icon} ${nameStr}${duration}`);
+  }
+
+  // Flow entries into rows
+  let currentRow = "";
+  let currentRowLen = 0;
+  for (const entry of entries) {
+    const entryLen = stripAnsi(entry).length;
+    const separator = currentRowLen > 0 ? "  " : "";
+    const sepLen = currentRowLen > 0 ? 2 : 0;
+
+    if (currentRowLen + sepLen + entryLen > boxInner && currentRowLen > 0) {
+      // Wrap to new row
+      const padded = padRight(currentRow, boxInner);
+      lines.push("  " + dim("│ ") + padded + dim(" │"));
+      currentRow = entry;
+      currentRowLen = entryLen;
+    } else {
+      currentRow += separator + entry;
+      currentRowLen += sepLen + entryLen;
+    }
+  }
+  // Last row
+  if (currentRowLen > 0) {
+    const padded = padRight(currentRow, boxInner);
+    lines.push("  " + dim("│ ") + padded + dim(" │"));
+  }
+
+  // Bottom border
+  lines.push("  " + dim("└" + "─".repeat(boxInner + 2) + "┘"));
+
+  return lines;
+}
+
+// ── Render Work Item ────────────────────────────────────────────────
+
+function renderWorkItem(item: WorkItemView, innerWidth: number, tick: number): string[] {
   const lines: string[] = [];
 
-  // Line 1: slug + branch (right-aligned)
+  // Line 1: status dot + bold slug + elapsed time (right)
   const slugText = `${statusDot(item.status)} ${bold(item.slug)}`;
-  const branchText = dim(item.branch);
-  const slugPlainLen = stripAnsi(slugText).length;
-  const branchPlainLen = stripAnsi(branchText).length;
-  const gap1 = Math.max(2, innerWidth - slugPlainLen - branchPlainLen);
-  lines.push(slugText + " ".repeat(gap1) + branchText);
-
-  // Line 2: mode + timing (right-aligned)
-  const modeText = formatMode(item.mode, item.classification);
-  const pausedBadge = item.status === "paused" ? "  " + bgYellow(" PAUSED ") : "";
   const elapsed = formatTimeAgo(item.startedAt);
-  let timingRight = `Elapsed: ${elapsed}`;
-  if (item.currentPhaseStartedAt) {
-    timingRight += `  Phase: ${formatTimeAgo(item.currentPhaseStartedAt)}`;
+  const elapsedText = dim(`⏱ ${elapsed}`);
+  const slugLen = stripAnsi(slugText).length;
+  const elapsedLen = stripAnsi(elapsedText).length;
+  const gap1 = Math.max(2, innerWidth - slugLen - elapsedLen);
+  lines.push(slugText + " ".repeat(gap1) + elapsedText);
+
+  // Line 2: branch + mode badge + gated badge + classification
+  const branchText = dim("⎇ " + item.branch);
+  let badges = "  " + renderModeBadge(item.mode);
+  if (item.gated) badges += " " + renderGatedBadge();
+  if (item.status === "paused") badges += " " + bgYellow(" PAUSED ");
+  if (item.status === "failed") badges += " " + bgRed(" FAILED ");
+  if (item.classification) badges += "  " + dim(item.classification);
+  lines.push("  " + branchText + badges);
+
+  // Line 3: timing — phase elapsed + sub-stage elapsed
+  const timingParts: string[] = [];
+  if (item.currentPhase && item.currentPhaseStartedAt) {
+    timingParts.push(cyan("phase") + dim(`: ${formatDuration(item.currentPhaseStartedAt)}`));
   }
-  const timingText = dim(timingRight);
-  const modeStr = `  ${modeText}${pausedBadge}`;
-  const modePlainLen = stripAnsi(modeStr).length;
-  const timingPlainLen = stripAnsi(timingText).length;
-  const gap2 = Math.max(2, innerWidth - modePlainLen - timingPlainLen);
-  lines.push(modeStr + " ".repeat(gap2) + timingText);
-
-  // Line 3: progress bar with phase label only (no sub-stage inline)
-  const phaseLabel = item.currentPhase || "—";
-  const barMaxWidth = Math.max(20, Math.min(40, innerWidth - 30));
+  if (item.currentSubStage && item.currentSubStageStartedAt) {
+    timingParts.push(cyan("step") + dim(`: ${formatDuration(item.currentSubStageStartedAt)}`));
+  }
+  if (timingParts.length > 0) {
+    lines.push("  " + timingParts.join(dim("  │  ")));
+  }
+
+  // Line 4: progress bar with animated head
+  const barMaxWidth = Math.max(20, Math.min(40, innerWidth - 20));
   lines.push("  " + renderProgressBar(
     item.progress.completed,
     item.progress.total,
     item.progress.percent,
-    phaseLabel,
-    barMaxWidth
+    barMaxWidth,
+    tick
   ));
 
-  // Line 4: phase indicators with sub-stage shown under current phase
-  const phaseStrs = item.phases.map(p => `${p.name} ${phaseIndicator(p.status, tick)}`);
-  lines.push("  " + phaseStrs.join("  "));
+  // Line 5-6: phase pipeline with connectors, spinner, and timing row
+  const pipelineLines = renderPhasePipeline(item.phases, tick);
+  for (const pl of pipelineLines) {
+    lines.push("  " + pl);
+  }
 
-  // Line 5 (optional): current sub-stage detail under the phase line
-  if (item.currentSubStage && item.currentPhase) {
-    const isWaiting = item.currentSubStageStatus === "waiting";
-    let subLabel = `↳ ${item.currentSubStage}`;
-    if (item.currentSubStageIndex != null && item.currentPhaseTotal != null) {
-      subLabel += ` (${item.currentSubStageIndex}/${item.currentPhaseTotal})`;
-    }
-    if (isWaiting) {
-      const badge = tick % 2 === 0 ? bgYellow(" WAITING ") : dim(" WAITING ");
-      lines.push("    " + yellow(subLabel) + "  " + badge);
-    } else {
-      lines.push("    " + (tick % 2 === 0 ? cyan(subLabel) : dim(subLabel)));
+  // Line 6: sub-stage detail box (all sub-stages of current phase)
+  const subStageBox = renderSubStageBox(item, innerWidth, tick);
+  if (subStageBox.length > 0) {
+    for (const line of subStageBox) {
+      lines.push(line);
     }
   }
 
-  // Line 5 (optional): loopbacks
+  // Loopbacks
   if (item.loopbacks.count > 0) {
     const lb = item.loopbacks;
-    let loopStr = `  ${cyan("⟳")} ${lb.count} loopback${lb.count > 1 ? "s" : ""}`;
+    let loopStr = `  ${yellow("⟳")} ${lb.count} loopback${lb.count > 1 ? "s" : ""}`;
     if (lb.lastFrom && lb.lastTo) {
-      loopStr += `: ${lb.lastFrom} → ${lb.lastTo}`;
+      loopStr += dim(`: ${lb.lastFrom} → ${lb.lastTo}`);
     }
     if (lb.lastReason) {
-      loopStr += ` (${lb.lastReason})`;
+      loopStr += dim(` (${lb.lastReason})`);
     }
     lines.push(loopStr);
   }
 
+  // Worktree path
+  if (item.worktreePath) {
+    let displayPath = item.worktreePath;
+    const maxPathLen = innerWidth - 8;
+    if (displayPath.length > maxPathLen) {
+      displayPath = "…" + displayPath.slice(displayPath.length - maxPathLen + 1);
+    }
+    lines.push("  " + dim("⌂ " + displayPath));
+  }
+
   return lines;
 }
 
@@ -200,7 +445,7 @@ interface CompletedColumnWidths {
 }
 
 function computeCompletedWidths(items: CompletedItemView[]): CompletedColumnWidths {
-  let slug = 4, pr = 2, date = 4; // minimums
+  let slug = 4, pr = 2, date = 4;
   for (const item of items) {
     slug = Math.max(slug, item.slug.length);
     pr = Math.max(pr, (item.pr || "—").length);
@@ -228,26 +473,34 @@ export function renderDashboard(
   tick: number = 0
 ): string {
   const maxWidth = Math.min(width, 120);
-  const innerWidth = maxWidth - 4; // account for "║ " and " ║"
+  const innerWidth = maxWidth - 4;
 
   const allLines: string[] = [];
 
   // Top border
   allLines.push(`╔${horizontalLine(maxWidth)}╗`);
 
-  let activeCount = 0, pausedCount = 0, failedCount = 0;
+  // Header counts
+  let activeCount = 0, pausedCount = 0, failedCount = 0, waitingCount = 0;
   for (const item of data.activeItems) {
     if (item.status === "in-progress") activeCount++;
     else if (item.status === "paused") pausedCount++;
     else if (item.status === "failed") failedCount++;
+    if (item.currentSubStageStatus === "waiting") waitingCount++;
   }
+  const completedCount = data.completedItems.length;
+  const hasActive = activeCount > 0;
 
+  // Header: mascot + title + counts
   let headerRight = "";
   if (activeCount > 0) headerRight += `${green("●")} ${activeCount} active`;
+  if (waitingCount > 0) headerRight += `  ${yellow("◉")} ${waitingCount} waiting`;
   if (pausedCount > 0) headerRight += `  ${yellow("○")} ${pausedCount} paused`;
   if (failedCount > 0) headerRight += `  ${red("✗")} ${failedCount} failed`;
+  if (completedCount > 0) headerRight += `  ${green("✓")} ${completedCount} done`;
 
-  const headerLeft = bold("  WORK-KIT OBSERVER");
+  const mascotStr = mascot(tick, hasActive);
+  const headerLeft = `  ${mascotStr} ${bold("WORK-KIT OBSERVER")}`;
   const headerLeftLen = stripAnsi(headerLeft).length;
   const headerRightLen = stripAnsi(headerRight).length;
   const headerGap = Math.max(2, innerWidth - headerLeftLen - headerRightLen);
@@ -257,7 +510,7 @@ export function renderDashboard(
   allLines.push(`╠${horizontalLine(maxWidth)}╣`);
 
   if (data.activeItems.length === 0 && data.completedItems.length === 0) {
-    // Empty state
+    // Empty state with idle mascot
     allLines.push(emptyBoxLine(innerWidth));
     allLines.push(boxLine(dim("  No active work items found."), innerWidth));
     allLines.push(boxLine(dim("  Start a new work item with: work-kit init"), innerWidth));
@@ -275,6 +528,8 @@ export function renderDashboard(
         }
         if (i < data.activeItems.length - 1) {
           allLines.push(emptyBoxLine(innerWidth));
+          allLines.push(boxLine(dim("  " + thinLine(innerWidth - 4)), innerWidth));
+          allLines.push(emptyBoxLine(innerWidth));
         }
       }
 
@@ -284,7 +539,10 @@ export function renderDashboard(
     // Completed section
     if (data.completedItems.length > 0) {
       allLines.push(`╠${horizontalLine(maxWidth)}╣`);
-      allLines.push(boxLine(bold("  COMPLETED"), innerWidth));
+      allLines.push(boxLine(
+        bold("  COMPLETED") + dim(` (${data.completedItems.length})`),
+        innerWidth
+      ));
 
       const maxCompleted = 5;
       const displayed = data.completedItems.slice(0, maxCompleted);
@@ -295,7 +553,7 @@ export function renderDashboard(
       }
       if (data.completedItems.length > maxCompleted) {
         allLines.push(boxLine(
-          dim(`  ... and ${data.completedItems.length - maxCompleted} more`),
+          dim(`  … and ${data.completedItems.length - maxCompleted} more`),
           innerWidth
         ));
       }
@@ -310,6 +568,7 @@ export function renderDashboard(
   const timeStr = data.lastUpdated.toLocaleTimeString("en-US", {
     hour: "2-digit",
     minute: "2-digit",
+    second: "2-digit",
     hour12: false,
   });
   const footerRight = dim(`Updated: ${timeStr}`);
@@ -321,21 +580,18 @@ export function renderDashboard(
   // Bottom border
   allLines.push(`╚${horizontalLine(maxWidth)}╝`);
 
-  // Apply scrolling: figure out how many content lines we have vs available height
+  // Scrolling
   const totalLines = allLines.length;
   const availableHeight = height;
 
   if (totalLines <= availableHeight) {
-    // Everything fits, no scrolling needed
-    return allLines.join("\n") + "\n";
+    return allLines.join("\n") + "\n\x1b[J";
   }
 
-  // Apply scroll offset
   const maxScroll = Math.max(0, totalLines - availableHeight);
   const clampedOffset = Math.min(scrollOffset, maxScroll);
   const visibleLines = allLines.slice(clampedOffset, clampedOffset + availableHeight);
 
-  // Add scroll indicator if not showing everything
   if (clampedOffset > 0 || clampedOffset + availableHeight < totalLines) {
     const scrollPct = Math.round((clampedOffset / maxScroll) * 100);
     const indicator = dim(` [${scrollPct}% scrolled]`);
@@ -344,23 +600,23 @@ export function renderDashboard(
     }
   }
 
-  return visibleLines.join("\n") + "\n";
+  return visibleLines.join("\n") + "\n\x1b[J";
 }
 
 // ── Terminal Control ────────────────────────────────────────────────
 
 export function enterAlternateScreen(): void {
-  process.stdout.write("\x1b[?1049h"); // enter alternate screen
-  process.stdout.write("\x1b[?25l");   // hide cursor
+  process.stdout.write("\x1b[?1049h");
+  process.stdout.write("\x1b[?25l");
 }
 
 export function exitAlternateScreen(): void {
-  process.stdout.write("\x1b[?25h");   // show cursor
-  process.stdout.write("\x1b[?1049l"); // exit alternate screen
+  process.stdout.write("\x1b[?25h");
+  process.stdout.write("\x1b[?1049l");
 }
 
 export function clearAndHome(): string {
-  return "\x1b[H\x1b[2J"; // move to top-left + clear screen
+  return "\x1b[H\x1b[2J";
 }
 
 export function moveCursorHome(): string {

package/cli/src/observer/watcher.ts

@@ -35,7 +35,7 @@ export function startWatching(
       // rename (write tmp + rename), which replaces the inode and
       // breaks fs.watch on the file on Linux.
       const watcher = fs.watch(stateDir, { persistent: false }, (_event, filename) => {
-        if (filename === "state.json") {
+        if (filename === "tracker.json") {
           debouncedUpdate();
         }
       });

package/cli/src/state/store.ts

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { WorkKitState } from "./schema.js";
 
 const STATE_DIR = ".work-kit";
-const STATE_FILE = "state.json";
+const STATE_FILE = "tracker.json";
 
 // ── Worktree Discovery ───────────────────────────────────────────────
 
@@ -41,13 +41,13 @@ export function stateExists(worktreeRoot: string): boolean {
 export function readState(worktreeRoot: string): WorkKitState {
   const filePath = statePath(worktreeRoot);
   if (!fs.existsSync(filePath)) {
-    throw new Error(`No state.json found at ${filePath}`);
+    throw new Error(`No tracker.json found at ${filePath}`);
   }
   const raw = fs.readFileSync(filePath, "utf-8");
   try {
     return JSON.parse(raw) as WorkKitState;
   } catch {
-    throw new Error(`Corrupted state.json at ${filePath}. File contains invalid JSON.`);
+    throw new Error(`Corrupted tracker.json at ${filePath}. File contains invalid JSON.`);
   }
 }
 

package/cli/src/utils/colors.ts

@@ -9,4 +9,15 @@ export const green = (s: string) => `${code(32)}${s}${reset}`;
 export const yellow = (s: string) => `${code(33)}${s}${reset}`;
 export const red = (s: string) => `${code(31)}${s}${reset}`;
 export const cyan = (s: string) => `${code(36)}${s}${reset}`;
+export const blue = (s: string) => `${code(34)}${s}${reset}`;
+export const magenta = (s: string) => `${code(35)}${s}${reset}`;
+export const bgGreen = (s: string) => `${code(42)}${code(30)}${s}${reset}`;
 export const bgYellow = (s: string) => `${code(43)}${code(30)}${s}${reset}`;
+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 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}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "work-kit-cli",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Structured development workflow for Claude Code. Two modes, 6 phases, 27 sub-stages.",
   "type": "module",
   "bin": {

package/skills/wk-wrap-up/SKILL.md

@@ -12,16 +12,16 @@ allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 
 ## Instructions
 
-> **Note:** Archiving state.md and appending to `.work-kit-tracker/index.md` are handled automatically by the CLI when you run `work-kit complete` on the last sub-stage. You do NOT need to do these manually.
+> **Note:** The CLI automatically archives `state.md`, `tracker.json`, and a placeholder `summary.md` into `.work-kit-tracker/archive/<slug>-<date>/` when the last sub-stage completes. It also appends a row to `.work-kit-tracker/index.md`. Your job is to **replace the placeholder summary.md** with a real distilled summary.
 
 1. **Read the full `.work-kit/state.md`** — every phase output from Plan through the last completed phase
-2. **Synthesize the work-kit log entry** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
-3. **Write the summary file** to `.work-kit-tracker/<date>-<slug>.md` on the **main branch** (not the worktree)
+2. **Synthesize the summary** — not a copy-paste of state, but a distilled record that a future developer (or agent) would find useful
+3. **Overwrite the summary file** at `.work-kit-tracker/archive/<slug>-<date>/summary.md` on the **main branch** (not the worktree)
 4. **Ask the user** if they want the worktree and branch removed
 
-## Work-Kit Log Entry Format
+## Summary File Format
 
-Write to `.work-kit-tracker/<YYYY-MM-DD>-<slug>.md`:
+Overwrite `.work-kit-tracker/archive/<slug>-<date>/summary.md`:
 
 ```markdown
 ---
@@ -48,6 +48,17 @@ status: <completed | partial | rolled-back>
 - <what changed and why>
 ```
 
+## Archive Folder Structure
+
+The CLI creates this automatically — you only need to overwrite `summary.md`:
+
+```
+.work-kit-tracker/archive/<slug>-<date>/
+├── state.md          # full phase outputs (raw, from .work-kit/state.md)
+├── tracker.json      # full JSON tracker (phases, timing, status)
+└── summary.md        # distilled wrap-up summary (YOU write this)
+```
+
 ## What to Include vs. Exclude
 
 **Include:**