@anthropologies/claudestory 0.1.2 → 0.1.4

package/dist/cli.js

@@ -484,6 +484,278 @@ function formatHandoverContent(filename, content, format) {
   }
   return content;
 }
+function formatSnapshotResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  let line = `Snapshot saved: ${result.filename} (${result.retained} retained`;
+  if (result.pruned > 0) line += `, ${result.pruned} pruned`;
+  line += ")";
+  return line;
+}
+function formatRecap(recap, state, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(recap), null, 2);
+  }
+  const lines = [];
+  if (!recap.snapshot) {
+    lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Recap`);
+    lines.push("");
+    lines.push("No snapshot found. Run `claudestory snapshot` to enable session diffs.");
+    lines.push("");
+    lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete, ${state.blockedCount} blocked`);
+    lines.push(`Issues: ${state.openIssueCount} open`);
+  } else {
+    lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Recap`);
+    lines.push("");
+    lines.push(`Since snapshot: ${recap.snapshot.createdAt}`);
+    if (recap.partial) {
+      lines.push("**Note:** Snapshot was taken from a project with integrity warnings. Diff may be incomplete.");
+    }
+    const changes = recap.changes;
+    const hasChanges = hasAnyChanges(changes);
+    if (!hasChanges) {
+      lines.push("");
+      lines.push("No changes since last snapshot.");
+    } else {
+      if (changes.phases.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Phase Transitions");
+        for (const p of changes.phases.statusChanged) {
+          lines.push(`- **${escapeMarkdownInline(p.name)}** (${p.id}): ${p.from} \u2192 ${p.to}`);
+        }
+      }
+      const ticketChanges = changes.tickets;
+      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Tickets");
+        for (const t of ticketChanges.statusChanged) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 ${t.from} \u2192 ${t.to}`);
+        }
+        for (const t of ticketChanges.added) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **new**`);
+        }
+        for (const t of ticketChanges.removed) {
+          lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **removed**`);
+        }
+      }
+      const issueChanges = changes.issues;
+      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0) {
+        lines.push("");
+        lines.push("## Issues");
+        for (const i of issueChanges.resolved) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **resolved**`);
+        }
+        for (const i of issueChanges.statusChanged) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 ${i.from} \u2192 ${i.to}`);
+        }
+        for (const i of issueChanges.added) {
+          lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **new**`);
+        }
+      }
+      if (changes.blockers.added.length > 0 || changes.blockers.cleared.length > 0) {
+        lines.push("");
+        lines.push("## Blockers");
+        for (const name of changes.blockers.cleared) {
+          lines.push(`- ${escapeMarkdownInline(name)} \u2014 **cleared**`);
+        }
+        for (const name of changes.blockers.added) {
+          lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
+        }
+      }
+    }
+  }
+  const actions = recap.suggestedActions;
+  lines.push("");
+  lines.push("## Suggested Actions");
+  if (actions.nextTicket) {
+    lines.push(`- **Next:** ${actions.nextTicket.id} \u2014 ${escapeMarkdownInline(actions.nextTicket.title)}${actions.nextTicket.phase ? ` (${actions.nextTicket.phase})` : ""}`);
+  }
+  if (actions.highSeverityIssues.length > 0) {
+    for (const i of actions.highSeverityIssues) {
+      lines.push(`- **${i.severity} issue:** ${i.id} \u2014 ${escapeMarkdownInline(i.title)}`);
+    }
+  }
+  if (actions.recentlyClearedBlockers.length > 0) {
+    lines.push(`- **Recently cleared:** ${actions.recentlyClearedBlockers.map(escapeMarkdownInline).join(", ")}`);
+  }
+  if (!actions.nextTicket && actions.highSeverityIssues.length === 0 && actions.recentlyClearedBlockers.length === 0) {
+    lines.push("- No urgent actions.");
+  }
+  return lines.join("\n");
+}
+function formatExport(state, mode, phaseId, format) {
+  if (mode === "phase" && phaseId) {
+    return formatPhaseExport(state, phaseId, format);
+  }
+  return formatFullExport(state, format);
+}
+function formatPhaseExport(state, phaseId, format) {
+  const phase = state.roadmap.phases.find((p) => p.id === phaseId);
+  if (!phase) {
+    return formatError("not_found", `Phase "${phaseId}" not found`, format);
+  }
+  const phaseStatus = state.phaseStatus(phaseId);
+  const leaves = state.phaseTickets(phaseId);
+  const umbrellaAncestors = /* @__PURE__ */ new Map();
+  for (const leaf of leaves) {
+    if (leaf.parentTicket) {
+      const parent = state.ticketByID(leaf.parentTicket);
+      if (parent && !umbrellaAncestors.has(parent.id)) {
+        umbrellaAncestors.set(parent.id, parent);
+      }
+    }
+  }
+  const crossPhaseDeps = /* @__PURE__ */ new Map();
+  for (const leaf of leaves) {
+    for (const blockerId of leaf.blockedBy) {
+      const blocker = state.ticketByID(blockerId);
+      if (blocker && blocker.phase !== phaseId && !crossPhaseDeps.has(blocker.id)) {
+        crossPhaseDeps.set(blocker.id, blocker);
+      }
+    }
+  }
+  const relatedIssues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.phase === phaseId || i.relatedTickets.some((tid) => {
+      const t = state.ticketByID(tid);
+      return t && t.phase === phaseId;
+    }))
+  );
+  const activeBlockers = state.roadmap.blockers.filter(
+    (b) => !isBlockerCleared(b)
+  );
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope({
+        phase: { id: phase.id, name: phase.name, description: phase.description, status: phaseStatus },
+        tickets: leaves.map((t) => ({ id: t.id, title: t.title, status: t.status, type: t.type, order: t.order })),
+        umbrellaAncestors: [...umbrellaAncestors.values()].map((t) => ({ id: t.id, title: t.title })),
+        crossPhaseDependencies: [...crossPhaseDeps.values()].map((t) => ({ id: t.id, title: t.title, status: t.status, phase: t.phase })),
+        issues: relatedIssues.map((i) => ({ id: i.id, title: i.title, severity: i.severity, status: i.status })),
+        blockers: activeBlockers.map((b) => ({ name: b.name, note: b.note ?? null }))
+      }),
+      null,
+      2
+    );
+  }
+  const lines = [];
+  lines.push(`# ${escapeMarkdownInline(phase.name)} (${phase.id})`);
+  lines.push("");
+  lines.push(`Status: ${phaseStatus}`);
+  if (phase.description) {
+    lines.push(`Description: ${escapeMarkdownInline(phase.description)}`);
+  }
+  if (leaves.length > 0) {
+    lines.push("");
+    lines.push("## Tickets");
+    for (const t of leaves) {
+      const indicator = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+      const parentNote = t.parentTicket && umbrellaAncestors.has(t.parentTicket) ? ` (under ${t.parentTicket})` : "";
+      lines.push(`${indicator} ${t.id}: ${escapeMarkdownInline(t.title)}${parentNote}`);
+    }
+  }
+  if (crossPhaseDeps.size > 0) {
+    lines.push("");
+    lines.push("## Cross-Phase Dependencies");
+    for (const [, dep] of crossPhaseDeps) {
+      lines.push(`- ${dep.id}: ${escapeMarkdownInline(dep.title)} [${dep.status}] (${dep.phase ?? "unphased"})`);
+    }
+  }
+  if (relatedIssues.length > 0) {
+    lines.push("");
+    lines.push("## Open Issues");
+    for (const i of relatedIssues) {
+      lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}`);
+    }
+  }
+  if (activeBlockers.length > 0) {
+    lines.push("");
+    lines.push("## Active Blockers");
+    for (const b of activeBlockers) {
+      lines.push(`- ${escapeMarkdownInline(b.name)}${b.note ? ` \u2014 ${escapeMarkdownInline(b.note)}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatFullExport(state, format) {
+  const phases = phasesWithStatus(state);
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope({
+        project: state.config.project,
+        phases: phases.map((p) => ({
+          id: p.phase.id,
+          name: p.phase.name,
+          description: p.phase.description,
+          status: p.status,
+          tickets: state.phaseTickets(p.phase.id).map((t) => ({
+            id: t.id,
+            title: t.title,
+            status: t.status,
+            type: t.type
+          }))
+        })),
+        issues: state.issues.map((i) => ({
+          id: i.id,
+          title: i.title,
+          severity: i.severity,
+          status: i.status
+        })),
+        blockers: state.roadmap.blockers.map((b) => ({
+          name: b.name,
+          cleared: isBlockerCleared(b),
+          note: b.note ?? null
+        }))
+      }),
+      null,
+      2
+    );
+  }
+  const lines = [];
+  lines.push(`# ${escapeMarkdownInline(state.config.project)} \u2014 Full Export`);
+  lines.push("");
+  lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete`);
+  lines.push(`Issues: ${state.openIssueCount} open`);
+  lines.push("");
+  lines.push("## Phases");
+  for (const p of phases) {
+    const indicator = p.status === "complete" ? "[x]" : p.status === "inprogress" ? "[~]" : "[ ]";
+    lines.push("");
+    lines.push(`### ${indicator} ${escapeMarkdownInline(p.phase.name)} (${p.phase.id})`);
+    if (p.phase.description) {
+      lines.push(escapeMarkdownInline(p.phase.description));
+    }
+    const tickets = state.phaseTickets(p.phase.id);
+    if (tickets.length > 0) {
+      lines.push("");
+      for (const t of tickets) {
+        const ti = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+        lines.push(`${ti} ${t.id}: ${escapeMarkdownInline(t.title)}`);
+      }
+    }
+  }
+  if (state.issues.length > 0) {
+    lines.push("");
+    lines.push("## Issues");
+    for (const i of state.issues) {
+      const resolved = i.status === "resolved" ? " \u2713" : "";
+      lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}${resolved}`);
+    }
+  }
+  const blockers = state.roadmap.blockers;
+  if (blockers.length > 0) {
+    lines.push("");
+    lines.push("## Blockers");
+    for (const b of blockers) {
+      const cleared = isBlockerCleared(b) ? "[x]" : "[ ]";
+      lines.push(`${cleared} ${escapeMarkdownInline(b.name)}${b.note ? ` \u2014 ${escapeMarkdownInline(b.note)}` : ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+function hasAnyChanges(diff) {
+  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0;
+}
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
   return text.slice(0, maxLen - 3) + "...";
@@ -496,7 +768,7 @@ function formatTicketOneLiner(t, state) {
 
 // src/cli/run.ts
 init_esm_shims();
-import { join as join5 } from "path";
+import { join as join6 } from "path";
 
 // src/core/index.ts
 init_esm_shims();
@@ -1709,7 +1981,7 @@ function dfsBlocked(id, state, visited, inStack, findings) {
 
 // src/core/init.ts
 init_esm_shims();
-import { mkdir, stat as stat2, readdir as readdir3, readFile as readFile3 } from "fs/promises";
+import { mkdir, stat as stat2 } from "fs/promises";
 import { join as join4, resolve as resolve3 } from "path";
 init_errors();
 async function initProject(root, options) {
@@ -1769,21 +2041,14 @@ async function initProject(root, options) {
   await writeRoadmap(roadmap, absRoot);
   const warnings = [];
   if (options.force && exists) {
-    for (const subdir of ["tickets", "issues"]) {
-      const dir = join4(wrapDir, subdir);
-      try {
-        const files = await readdir3(dir);
-        for (const f of files) {
-          if (!f.endsWith(".json")) continue;
-          try {
-            const content = await readFile3(join4(dir, f), "utf-8");
-            JSON.parse(content);
-          } catch {
-            warnings.push(`.story/${subdir}/${f}`);
-          }
+    try {
+      const { warnings: loadWarnings } = await loadProject(absRoot);
+      for (const w of loadWarnings) {
+        if (INTEGRITY_WARNING_TYPES.includes(w.type)) {
+          warnings.push(`${w.file}: ${w.message}`);
         }
-      } catch {
       }
+    } catch {
     }
   }
   return {
@@ -1799,12 +2064,241 @@ async function initProject(root, options) {
   };
 }
 
+// src/core/snapshot.ts
+init_esm_shims();
+import { readdir as readdir3, readFile as readFile3, mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { join as join5, resolve as resolve4 } from "path";
+import { z as z6 } from "zod";
+var LoadWarningSchema = z6.object({
+  type: z6.string(),
+  file: z6.string(),
+  message: z6.string()
+});
+var SnapshotV1Schema = z6.object({
+  version: z6.literal(1),
+  createdAt: z6.string().datetime({ offset: true }),
+  project: z6.string(),
+  config: ConfigSchema,
+  roadmap: RoadmapSchema,
+  tickets: z6.array(TicketSchema),
+  issues: z6.array(IssueSchema),
+  warnings: z6.array(LoadWarningSchema).optional()
+});
+var MAX_SNAPSHOTS = 20;
+async function saveSnapshot(root, loadResult) {
+  const absRoot = resolve4(root);
+  const snapshotsDir = join5(absRoot, ".story", "snapshots");
+  await mkdir2(snapshotsDir, { recursive: true });
+  const { state, warnings } = loadResult;
+  const now = /* @__PURE__ */ new Date();
+  const filename = formatSnapshotFilename(now);
+  const snapshot = {
+    version: 1,
+    createdAt: now.toISOString(),
+    project: state.config.project,
+    config: state.config,
+    roadmap: state.roadmap,
+    tickets: [...state.tickets],
+    issues: [...state.issues],
+    ...warnings.length > 0 ? {
+      warnings: warnings.map((w) => ({
+        type: w.type,
+        file: w.file,
+        message: w.message
+      }))
+    } : {}
+  };
+  const json = JSON.stringify(snapshot, null, 2) + "\n";
+  const targetPath = join5(snapshotsDir, filename);
+  const wrapDir = join5(absRoot, ".story");
+  await guardPath(targetPath, wrapDir);
+  await atomicWrite(targetPath, json);
+  const pruned = await pruneSnapshots(snapshotsDir);
+  const entries = await listSnapshotFiles(snapshotsDir);
+  return { filename, retained: entries.length, pruned };
+}
+async function loadLatestSnapshot(root) {
+  const snapshotsDir = join5(resolve4(root), ".story", "snapshots");
+  if (!existsSync4(snapshotsDir)) return null;
+  const files = await listSnapshotFiles(snapshotsDir);
+  if (files.length === 0) return null;
+  for (const filename of files) {
+    try {
+      const content = await readFile3(join5(snapshotsDir, filename), "utf-8");
+      const parsed = JSON.parse(content);
+      const snapshot = SnapshotV1Schema.parse(parsed);
+      return { snapshot, filename };
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+function diffStates(snapshotState, currentState) {
+  const snapTickets = new Map(snapshotState.tickets.map((t) => [t.id, t]));
+  const curTickets = new Map(currentState.tickets.map((t) => [t.id, t]));
+  const ticketsAdded = [];
+  const ticketsRemoved = [];
+  const ticketsStatusChanged = [];
+  for (const [id, cur] of curTickets) {
+    const snap = snapTickets.get(id);
+    if (!snap) {
+      ticketsAdded.push({ id, title: cur.title });
+    } else if (snap.status !== cur.status) {
+      ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    }
+  }
+  for (const [id, snap] of snapTickets) {
+    if (!curTickets.has(id)) {
+      ticketsRemoved.push({ id, title: snap.title });
+    }
+  }
+  const snapIssues = new Map(snapshotState.issues.map((i) => [i.id, i]));
+  const curIssues = new Map(currentState.issues.map((i) => [i.id, i]));
+  const issuesAdded = [];
+  const issuesResolved = [];
+  const issuesStatusChanged = [];
+  for (const [id, cur] of curIssues) {
+    const snap = snapIssues.get(id);
+    if (!snap) {
+      issuesAdded.push({ id, title: cur.title });
+    } else if (snap.status !== cur.status) {
+      if (cur.status === "resolved") {
+        issuesResolved.push({ id, title: cur.title });
+      } else {
+        issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+      }
+    }
+  }
+  const snapBlockers = new Map(
+    snapshotState.roadmap.blockers.map((b) => [b.name, b])
+  );
+  const curBlockers = new Map(
+    currentState.roadmap.blockers.map((b) => [b.name, b])
+  );
+  const blockersAdded = [];
+  const blockersCleared = [];
+  for (const [name, cur] of curBlockers) {
+    const snap = snapBlockers.get(name);
+    if (!snap) {
+      blockersAdded.push(name);
+    } else if (!isBlockerCleared(snap) && isBlockerCleared(cur)) {
+      blockersCleared.push(name);
+    }
+  }
+  const snapPhases = snapshotState.roadmap.phases;
+  const curPhases = currentState.roadmap.phases;
+  const snapPhaseMap = new Map(snapPhases.map((p) => [p.id, p]));
+  const curPhaseMap = new Map(curPhases.map((p) => [p.id, p]));
+  const phasesAdded = [];
+  const phasesRemoved = [];
+  const phasesStatusChanged = [];
+  for (const [id, curPhase] of curPhaseMap) {
+    const snapPhase = snapPhaseMap.get(id);
+    if (!snapPhase) {
+      phasesAdded.push({ id, name: curPhase.name });
+    } else {
+      const snapStatus = snapshotState.phaseStatus(id);
+      const curStatus = currentState.phaseStatus(id);
+      if (snapStatus !== curStatus) {
+        phasesStatusChanged.push({
+          id,
+          name: curPhase.name,
+          from: snapStatus,
+          to: curStatus
+        });
+      }
+    }
+  }
+  for (const [id, snapPhase] of snapPhaseMap) {
+    if (!curPhaseMap.has(id)) {
+      phasesRemoved.push({ id, name: snapPhase.name });
+    }
+  }
+  return {
+    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged },
+    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged },
+    blockers: { added: blockersAdded, cleared: blockersCleared },
+    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged }
+  };
+}
+function buildRecap(currentState, snapshotInfo) {
+  const next = nextTicket(currentState);
+  const nextTicketAction = next.kind === "found" ? { id: next.ticket.id, title: next.ticket.title, phase: next.ticket.phase } : null;
+  const highSeverityIssues = currentState.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "critical" || i.severity === "high")
+  ).map((i) => ({ id: i.id, title: i.title, severity: i.severity }));
+  if (!snapshotInfo) {
+    return {
+      snapshot: null,
+      changes: null,
+      suggestedActions: {
+        nextTicket: nextTicketAction,
+        highSeverityIssues,
+        recentlyClearedBlockers: []
+      },
+      partial: false
+    };
+  }
+  const { snapshot, filename } = snapshotInfo;
+  const snapshotState = new ProjectState({
+    tickets: snapshot.tickets,
+    issues: snapshot.issues,
+    roadmap: snapshot.roadmap,
+    config: snapshot.config,
+    handoverFilenames: []
+  });
+  const changes = diffStates(snapshotState, currentState);
+  const recentlyClearedBlockers = changes.blockers.cleared;
+  return {
+    snapshot: { filename, createdAt: snapshot.createdAt },
+    changes,
+    suggestedActions: {
+      nextTicket: nextTicketAction,
+      highSeverityIssues,
+      recentlyClearedBlockers
+    },
+    partial: (snapshot.warnings ?? []).length > 0
+  };
+}
+function formatSnapshotFilename(date) {
+  const y = date.getUTCFullYear();
+  const mo = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  const h = String(date.getUTCHours()).padStart(2, "0");
+  const mi = String(date.getUTCMinutes()).padStart(2, "0");
+  const s = String(date.getUTCSeconds()).padStart(2, "0");
+  const ms = String(date.getUTCMilliseconds()).padStart(3, "0");
+  return `${y}-${mo}-${d}T${h}-${mi}-${s}-${ms}.json`;
+}
+async function listSnapshotFiles(dir) {
+  try {
+    const entries = await readdir3(dir);
+    return entries.filter((f) => f.endsWith(".json") && !f.startsWith(".")).sort().reverse();
+  } catch {
+    return [];
+  }
+}
+async function pruneSnapshots(dir) {
+  const files = await listSnapshotFiles(dir);
+  if (files.length <= MAX_SNAPSHOTS) return 0;
+  const toRemove = files.slice(MAX_SNAPSHOTS);
+  for (const f of toRemove) {
+    try {
+      await unlink2(join5(dir, f));
+    } catch {
+    }
+  }
+  return toRemove.length;
+}
+
 // src/cli/run.ts
 init_errors();
 
 // src/cli/helpers.ts
 init_esm_shims();
-import { resolve as resolve4, relative as relative3, extname as extname3 } from "path";
+import { resolve as resolve5, relative as relative3, extname as extname3 } from "path";
 import { lstat as lstat2 } from "fs/promises";
 var CliValidationError = class extends Error {
   constructor(code, message) {
@@ -1877,10 +2371,10 @@ async function parseHandoverFilename(raw, handoversDir) {
       `Invalid handover filename "${raw}": must have .md extension`
     );
   }
-  const resolvedDir = resolve4(handoversDir);
-  const resolvedCandidate = resolve4(handoversDir, raw);
+  const resolvedDir = resolve5(handoversDir);
+  const resolvedCandidate = resolve5(handoversDir, raw);
   const rel = relative3(resolvedDir, resolvedCandidate);
-  if (!rel || rel.startsWith("..") || resolve4(resolvedDir, rel) !== resolvedCandidate) {
+  if (!rel || rel.startsWith("..") || resolve5(resolvedDir, rel) !== resolvedCandidate) {
     throw new CliValidationError(
       "invalid_input",
       `Invalid handover filename "${raw}": resolves outside handovers directory`
@@ -1941,7 +2435,7 @@ async function runReadCommand(format, handler) {
       return;
     }
     const { state, warnings } = await loadProject(root);
-    const handoversDir = join5(root, ".story", "handovers");
+    const handoversDir = join6(root, ".story", "handovers");
     const result = await handler({ state, warnings, root, handoversDir, format });
     writeOutput(result.output);
     let exitCode = result.exitCode ?? ExitCode.OK;
@@ -1976,7 +2470,7 @@ async function runDeleteCommand(format, force, handler) {
       return;
     }
     const { state, warnings } = await loadProject(root);
-    const handoversDir = join5(root, ".story", "handovers");
+    const handoversDir = join6(root, ".story", "handovers");
     if (!force && hasIntegrityWarnings(warnings)) {
       writeOutput(
         formatError(
@@ -2506,7 +3000,7 @@ async function handleIssueDelete(id, format, root) {
 
 // src/cli/commands/phase.ts
 init_esm_shims();
-import { join as join6, resolve as resolve5 } from "path";
+import { join as join7, resolve as resolve6 } from "path";
 var PHASE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 var PHASE_ID_MAX_LENGTH = 40;
 function validatePhaseId(id) {
@@ -2689,7 +3183,7 @@ async function handlePhaseDelete(id, reassign, format, root) {
       }
       const targetLeaves = state.phaseTickets(reassign);
       let maxOrder = targetLeaves.length > 0 ? targetLeaves[targetLeaves.length - 1].order : 0;
-      const wrapDir = resolve5(root, ".story");
+      const wrapDir = resolve6(root, ".story");
       const operations = [];
       const sortedTickets = [...affectedTickets].sort((a, b) => a.order - b.order);
       for (const ticket of sortedTickets) {
@@ -2697,21 +3191,21 @@ async function handlePhaseDelete(id, reassign, format, root) {
         const updated = { ...ticket, phase: reassign, order: maxOrder };
         const parsed = TicketSchema.parse(updated);
         const content = serializeJSON(parsed);
-        const target = join6(wrapDir, "tickets", `${parsed.id}.json`);
+        const target = join7(wrapDir, "tickets", `${parsed.id}.json`);
         operations.push({ op: "write", target, content });
       }
       for (const issue of affectedIssues) {
         const updated = { ...issue, phase: reassign };
         const parsed = IssueSchema.parse(updated);
         const content = serializeJSON(parsed);
-        const target = join6(wrapDir, "issues", `${parsed.id}.json`);
+        const target = join7(wrapDir, "issues", `${parsed.id}.json`);
         operations.push({ op: "write", target, content });
       }
       const newPhases = state.roadmap.phases.filter((p) => p.id !== id);
       const newRoadmap = { ...state.roadmap, phases: newPhases };
       const parsedRoadmap = RoadmapSchema.parse(newRoadmap);
       const roadmapContent = serializeJSON(parsedRoadmap);
-      const roadmapTarget = join6(wrapDir, "roadmap.json");
+      const roadmapTarget = join7(wrapDir, "roadmap.json");
       operations.push({ op: "write", target: roadmapTarget, content: roadmapContent });
       await runTransactionUnlocked(root, operations);
     } else {
@@ -2795,6 +3289,39 @@ function registerInitCommand(yargs2) {
   );
 }
 
+// src/cli/commands/recap.ts
+init_esm_shims();
+async function handleRecap(ctx) {
+  const snapshotInfo = await loadLatestSnapshot(ctx.root);
+  const recap = buildRecap(ctx.state, snapshotInfo);
+  return { output: formatRecap(recap, ctx.state, ctx.format) };
+}
+
+// src/cli/commands/export.ts
+init_esm_shims();
+function handleExport(ctx, mode, phaseId) {
+  if (mode === "phase") {
+    if (!phaseId) {
+      throw new CliValidationError("invalid_input", "Missing --phase value");
+    }
+    const phase = ctx.state.roadmap.phases.find((p) => p.id === phaseId);
+    if (!phase) {
+      throw new CliValidationError("not_found", `Phase "${phaseId}" not found in roadmap`);
+    }
+  }
+  return { output: formatExport(ctx.state, mode, phaseId, ctx.format) };
+}
+
+// src/cli/commands/snapshot.ts
+init_esm_shims();
+async function handleSnapshot(root, format) {
+  let result;
+  await withProjectLock(root, { strict: false }, async (loadResult) => {
+    result = await saveSnapshot(root, loadResult);
+  });
+  return { output: formatSnapshotResult(result, format) };
+}
+
 // src/cli/register.ts
 function registerStatusCommand(yargs2) {
   return yargs2.command(
@@ -3787,9 +4314,89 @@ function registerPhaseCommand(yargs2) {
     }
   );
 }
+function registerSnapshotCommand(yargs2) {
+  return yargs2.command(
+    "snapshot",
+    "Save current project state for session diffs",
+    (y) => addFormatOption(y),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+      if (!root) {
+        writeOutput(
+          formatError("not_found", "No .story/ project found.", format)
+        );
+        process.exitCode = ExitCode.USER_ERROR;
+        return;
+      }
+      try {
+        const result = await handleSnapshot(root, format);
+        writeOutput(result.output);
+        process.exitCode = result.exitCode ?? ExitCode.OK;
+      } catch (err) {
+        if (err instanceof CliValidationError) {
+          writeOutput(formatError(err.code, err.message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+        if (err instanceof ProjectLoaderError2) {
+          writeOutput(formatError(err.code, err.message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(formatError("io_error", message, format));
+        process.exitCode = ExitCode.USER_ERROR;
+      }
+    }
+  );
+}
+function registerRecapCommand(yargs2) {
+  return yargs2.command(
+    "recap",
+    "Session diff \u2014 changes since last snapshot + suggested actions",
+    (y) => addFormatOption(y),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      await runReadCommand(format, handleRecap);
+    }
+  );
+}
+function registerExportCommand(yargs2) {
+  return yargs2.command(
+    "export",
+    "Self-contained project document for sharing",
+    (y) => addFormatOption(
+      y.option("phase", {
+        type: "string",
+        describe: "Export a single phase by ID"
+      }).option("all", {
+        type: "boolean",
+        describe: "Export entire project"
+      }).conflicts("phase", "all").check((argv) => {
+        if (!argv.phase && !argv.all) {
+          throw new Error(
+            "Specify either --phase <id> or --all"
+          );
+        }
+        return true;
+      })
+    ),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      const mode = argv.all ? "all" : "phase";
+      const phaseId = argv.phase ?? null;
+      await runReadCommand(
+        format,
+        (ctx) => handleExport(ctx, mode, phaseId)
+      );
+    }
+  );
+}
 
 // src/cli/index.ts
-var version = "0.1.2";
+var version = "0.1.4";
 var HandledError = class extends Error {
   constructor() {
     super("HANDLED_ERROR");
@@ -3819,6 +4426,9 @@ cli = registerIssueCommand(cli);
 cli = registerHandoverCommand(cli);
 cli = registerBlockerCommand(cli);
 cli = registerValidateCommand(cli);
+cli = registerSnapshotCommand(cli);
+cli = registerRecapCommand(cli);
+cli = registerExportCommand(cli);
 function handleUnexpectedError(err) {
   if (err instanceof HandledError) return;
   const message = err instanceof Error ? err.message : String(err);