@anthropologies/claudestory 0.1.3 → 0.1.5

package/dist/cli.js

@@ -484,6 +484,284 @@ function formatHandoverContent(filename, content, format) {
   }
   return content;
 }
+function formatHandoverCreateResult(filename, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ filename }), null, 2);
+  }
+  return `Created handover: ${filename}`;
+}
+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 +774,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();
@@ -847,6 +1125,7 @@ import { readdir, readFile } from "fs/promises";
 import { existsSync } from "fs";
 import { join, relative, extname } from "path";
 var HANDOVER_DATE_REGEX = /^\d{4}-\d{2}-\d{2}/;
+var HANDOVER_SEQ_REGEX = /^(\d{4}-\d{2}-\d{2})-(\d{2})-/;
 async function listHandovers(handoversDir, root, warnings) {
   if (!existsSync(handoversDir)) return [];
   let entries;
@@ -876,7 +1155,16 @@ async function listHandovers(handoversDir, root, warnings) {
       });
     }
   }
-  conforming.sort((a, b) => b.localeCompare(a));
+  conforming.sort((a, b) => {
+    const dateA = a.slice(0, 10);
+    const dateB = b.slice(0, 10);
+    if (dateA !== dateB) return dateB.localeCompare(dateA);
+    const seqA = a.match(HANDOVER_SEQ_REGEX);
+    const seqB = b.match(HANDOVER_SEQ_REGEX);
+    if (seqA && !seqB) return -1;
+    if (!seqA && seqB) return 1;
+    return b.localeCompare(a);
+  });
   return [...conforming, ...nonConforming];
 }
 async function readHandover(handoversDir, filename) {
@@ -1792,12 +2080,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) {
@@ -1870,10 +2387,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`
@@ -1934,7 +2451,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;
@@ -1969,7 +2486,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(
@@ -2023,6 +2540,8 @@ function handleValidate(ctx) {
 
 // src/cli/commands/handover.ts
 init_esm_shims();
+import { mkdir as mkdir3 } from "fs/promises";
+import { join as join7, resolve as resolve6 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
@@ -2074,6 +2593,59 @@ async function handleHandoverGet(filename, ctx) {
     };
   }
 }
+function normalizeSlug(raw) {
+  let slug = raw.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (slug.length > 60) slug = slug.slice(0, 60).replace(/-$/, "");
+  if (!slug) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Slug is empty after normalization: "${raw}"`
+    );
+  }
+  return slug;
+}
+async function handleHandoverCreate(content, slugRaw, format, root) {
+  if (!content.trim()) {
+    throw new CliValidationError("invalid_input", "Handover content is empty");
+  }
+  const slug = normalizeSlug(slugRaw);
+  const date = todayISO();
+  let filename;
+  await withProjectLock(root, { strict: false }, async () => {
+    const absRoot = resolve6(root);
+    const handoversDir = join7(absRoot, ".story", "handovers");
+    await mkdir3(handoversDir, { recursive: true });
+    const wrapDir = join7(absRoot, ".story");
+    const datePrefix = `${date}-`;
+    const seqRegex = new RegExp(`^${date}-(\\d{2})-`);
+    let maxSeq = 0;
+    const { readdirSync } = await import("fs");
+    try {
+      for (const f of readdirSync(handoversDir)) {
+        const m = f.match(seqRegex);
+        if (m) {
+          const n = parseInt(m[1], 10);
+          if (n > maxSeq) maxSeq = n;
+        }
+      }
+    } catch {
+    }
+    const nextSeq = maxSeq + 1;
+    if (nextSeq > 99) {
+      throw new CliValidationError(
+        "conflict",
+        `Too many handovers for ${date}; limit is 99 per day`
+      );
+    }
+    const candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+    const candidatePath = join7(handoversDir, candidate);
+    await parseHandoverFilename(candidate, handoversDir);
+    await guardPath(candidatePath, wrapDir);
+    await atomicWrite(candidatePath, content);
+    filename = candidate;
+  });
+  return { output: formatHandoverCreateResult(filename, format) };
+}
 
 // src/cli/commands/blocker.ts
 init_esm_shims();
@@ -2499,7 +3071,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 join8, resolve as resolve7 } from "path";
 var PHASE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 var PHASE_ID_MAX_LENGTH = 40;
 function validatePhaseId(id) {
@@ -2682,7 +3254,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 = resolve7(root, ".story");
       const operations = [];
       const sortedTickets = [...affectedTickets].sort((a, b) => a.order - b.order);
       for (const ticket of sortedTickets) {
@@ -2690,21 +3262,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 = join8(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 = join8(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 = join8(wrapDir, "roadmap.json");
       operations.push({ op: "write", target: roadmapTarget, content: roadmapContent });
       await runTransactionUnlocked(root, operations);
     } else {
@@ -2788,6 +3360,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(
@@ -2849,7 +3454,83 @@ function registerHandoverCommand(yargs2) {
           (ctx) => handleHandoverGet(filename, ctx)
         );
       }
-    ).demandCommand(1, "Specify a handover subcommand: list, latest, get").strict(),
+    ).command(
+      "create",
+      "Create a new handover document",
+      (y2) => addFormatOption(
+        y2.option("content", {
+          type: "string",
+          describe: "Handover content (markdown string)"
+        }).option("stdin", {
+          type: "boolean",
+          describe: "Read content from stdin"
+        }).option("slug", {
+          type: "string",
+          default: "session",
+          describe: "Slug for filename (e.g. phase5b-wrapup)"
+        }).conflicts("content", "stdin").check((argv) => {
+          if (!argv.content && !argv.stdin) {
+            throw new Error(
+              "Specify either --content or --stdin"
+            );
+          }
+          return true;
+        })
+      ),
+      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;
+        }
+        let content;
+        if (argv.stdin) {
+          if (process.stdin.isTTY) {
+            writeOutput(
+              formatError("invalid_input", "Cannot read from stdin: no pipe detected. Use --content instead.", format)
+            );
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const chunks = [];
+          for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+          }
+          content = Buffer.concat(chunks).toString("utf-8");
+        } else {
+          content = argv.content;
+        }
+        try {
+          const result = await handleHandoverCreate(
+            content,
+            argv.slug,
+            format,
+            root
+          );
+          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;
+        }
+      }
+    ).demandCommand(1, "Specify a handover subcommand: list, latest, get, create").strict(),
     () => {
     }
   );
@@ -3780,9 +4461,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.3";
+var version = "0.1.5";
 var HandledError = class extends Error {
   constructor() {
     super("HANDLED_ERROR");
@@ -3812,6 +4573,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);