@anthropologies/claudestory 0.1.3 → 0.1.5

package/dist/mcp.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/mcp/index.ts
-import { realpathSync, existsSync as existsSync4 } from "fs";
-import { resolve as resolve5, join as join6, isAbsolute } from "path";
+import { realpathSync, existsSync as existsSync5 } from "fs";
+import { resolve as resolve7, join as join8, isAbsolute } from "path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -33,8 +33,8 @@ function discoverProjectRoot(startDir) {
 }
 
 // src/mcp/tools.ts
-import { z as z6 } from "zod";
-import { join as join5 } from "path";
+import { z as z7 } from "zod";
+import { join as join7 } from "path";
 
 // src/core/project-loader.ts
 import {
@@ -386,6 +386,7 @@ import { readdir, readFile } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
 import { join as join2, 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 (!existsSync2(handoversDir)) return [];
   let entries;
@@ -415,7 +416,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) {
@@ -502,6 +512,33 @@ async function loadProject(root, options) {
   });
   return { state, warnings };
 }
+async function withProjectLock(root, options, handler) {
+  const absRoot = resolve2(root);
+  const wrapDir = join3(absRoot, ".story");
+  await withLock(wrapDir, async () => {
+    await doRecoverTransaction(wrapDir);
+    const result = await loadProjectUnlocked(absRoot);
+    const config = result.state.config;
+    if (config.schemaVersion !== void 0 && config.schemaVersion > CURRENT_SCHEMA_VERSION) {
+      throw new ProjectLoaderError(
+        "version_mismatch",
+        `Config schemaVersion ${config.schemaVersion} exceeds max supported ${CURRENT_SCHEMA_VERSION}.`
+      );
+    }
+    if (options.strict) {
+      const integrityWarning = result.warnings.find(
+        (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+      );
+      if (integrityWarning) {
+        throw new ProjectLoaderError(
+          "project_corrupt",
+          `Strict mode: ${integrityWarning.file}: ${integrityWarning.message}`
+        );
+      }
+    }
+    await handler(result);
+  });
+}
 async function doRecoverTransaction(wrapDir) {
   const journalPath = join3(wrapDir, ".txn.json");
   let entries;
@@ -570,6 +607,17 @@ async function doRecoverTransaction(wrapDir) {
   } catch {
   }
 }
+async function loadProjectUnlocked(absRoot) {
+  const wrapDir = join3(absRoot, ".story");
+  const config = await loadSingletonFile("config.json", wrapDir, absRoot, ConfigSchema);
+  const roadmap = await loadSingletonFile("roadmap.json", wrapDir, absRoot, RoadmapSchema);
+  const warnings = [];
+  const tickets = await loadDirectory(join3(wrapDir, "tickets"), absRoot, TicketSchema, warnings);
+  const issues = await loadDirectory(join3(wrapDir, "issues"), absRoot, IssueSchema, warnings);
+  const handoverFilenames = await listHandovers(join3(wrapDir, "handovers"), absRoot, warnings);
+  const state = new ProjectState({ tickets, issues, roadmap, config, handoverFilenames });
+  return { state, warnings };
+}
 async function loadSingletonFile(filename, wrapDir, root, schema) {
   const filePath = join3(wrapDir, filename);
   const relPath = relative2(root, filePath);
@@ -648,6 +696,60 @@ async function loadDirectory(dirPath, root, schema, warnings) {
   }
   return results;
 }
+async function atomicWrite(targetPath, content) {
+  const tempPath = `${targetPath}.${process.pid}.tmp`;
+  try {
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, targetPath);
+  } catch (err) {
+    try {
+      await unlink(tempPath);
+    } catch {
+    }
+    throw new ProjectLoaderError(
+      "io_error",
+      `Failed to write ${basename(targetPath)}`,
+      err
+    );
+  }
+}
+async function guardPath(target, root) {
+  let resolvedRoot;
+  try {
+    resolvedRoot = await realpath(root);
+  } catch {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Cannot resolve project root: ${root}`
+    );
+  }
+  const targetDir = dirname2(target);
+  let resolvedDir;
+  try {
+    resolvedDir = await realpath(targetDir);
+  } catch {
+    resolvedDir = targetDir;
+  }
+  if (!resolvedDir.startsWith(resolvedRoot)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Path ${target} resolves outside project root`
+    );
+  }
+  if (existsSync3(target)) {
+    try {
+      const stats = await lstat(target);
+      if (stats.isSymbolicLink()) {
+        throw new ProjectLoaderError(
+          "invalid_input",
+          `Symlink target rejected: ${target}`
+        );
+      }
+    } catch (err) {
+      if (err instanceof ProjectLoaderError) throw err;
+    }
+  }
+}
 async function withLock(wrapDir, fn) {
   let release;
   try {
@@ -686,6 +788,13 @@ var CliValidationError = class extends Error {
     this.name = "CliValidationError";
   }
 };
+function todayISO() {
+  const d = /* @__PURE__ */ new Date();
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
 async function parseHandoverFilename(raw, handoversDir) {
   if (raw.includes("/") || raw.includes("\\") || raw.includes("..") || raw.includes("\0")) {
     throw new CliValidationError(
@@ -1109,6 +1218,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) + "...";
@@ -1376,6 +1763,8 @@ function handleValidate(ctx) {
 }
 
 // src/cli/commands/handover.ts
+import { mkdir } from "fs/promises";
+import { join as join4, resolve as resolve4 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
@@ -1427,6 +1816,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 = resolve4(root);
+    const handoversDir = join4(absRoot, ".story", "handovers");
+    await mkdir(handoversDir, { recursive: true });
+    const wrapDir = join4(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 = join4(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
 function handleBlockerList(ctx) {
@@ -1518,8 +1960,266 @@ function handleIssueGet(id, ctx) {
   return { output: formatIssue(issue, ctx.format) };
 }
 
+// src/core/snapshot.ts
+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 resolve5 } 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 = resolve5(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(resolve5(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/commands/recap.ts
+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/snapshot.ts
+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/commands/export.ts
+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/phase.ts
-import { join as join4, resolve as resolve4 } from "path";
+import { join as join6, resolve as resolve6 } from "path";
 function handlePhaseList(ctx) {
   return { output: formatPhaseList(ctx.state, ctx.format) };
 }
@@ -1578,7 +2278,7 @@ function formatMcpError(code, message) {
 async function runMcpReadTool(pinnedRoot, handler) {
   try {
     const { state, warnings } = await loadProject(pinnedRoot);
-    const handoversDir = join5(pinnedRoot, ".story", "handovers");
+    const handoversDir = join7(pinnedRoot, ".story", "handovers");
     const ctx = { state, warnings, root: pinnedRoot, handoversDir, format: "md" };
     const result = await handler(ctx);
     if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
@@ -1608,6 +2308,27 @@ ${text}`;
     return { content: [{ type: "text", text: formatMcpError("io_error", message) }], isError: true };
   }
 }
+async function runMcpWriteTool(pinnedRoot, handler) {
+  try {
+    const result = await handler(pinnedRoot, "md");
+    if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
+      return {
+        content: [{ type: "text", text: formatMcpError(result.errorCode, result.output) }],
+        isError: true
+      };
+    }
+    return { content: [{ type: "text", text: result.output }] };
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) {
+      return { content: [{ type: "text", text: formatMcpError(err.code, err.message) }], isError: true };
+    }
+    if (err instanceof CliValidationError) {
+      return { content: [{ type: "text", text: formatMcpError(err.code, err.message) }], isError: true };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: formatMcpError("io_error", message) }], isError: true };
+  }
+}
 function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_status", {
     description: "Project summary: phase statuses, ticket/issue counts, blockers, current phase"
@@ -1639,7 +2360,7 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_phase_tickets", {
     description: "Leaf tickets for a specific phase, sorted by order",
     inputSchema: {
-      phaseId: z6.string().describe("Phase ID (e.g. p5b, dogfood)")
+      phaseId: z7.string().describe("Phase ID (e.g. p5b, dogfood)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === args.phaseId);
@@ -1655,9 +2376,9 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_list", {
     description: "List leaf tickets with optional filters",
     inputSchema: {
-      status: z6.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
-      phase: z6.string().optional().describe("Filter by phase ID"),
-      type: z6.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
+      status: z7.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
+      phase: z7.string().optional().describe("Filter by phase ID"),
+      type: z7.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     if (args.phase) {
@@ -1678,14 +2399,14 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_get", {
     description: "Get a ticket by ID (includes umbrella tickets)",
     inputSchema: {
-      id: z6.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
+      id: z7.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleTicketGet(args.id, ctx)));
   server.registerTool("claudestory_issue_list", {
     description: "List issues with optional filters",
     inputSchema: {
-      status: z6.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
-      severity: z6.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low")
+      status: z7.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
+      severity: z7.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low")
     }
   }, (args) => runMcpReadTool(
     pinnedRoot,
@@ -1694,21 +2415,68 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_issue_get", {
     description: "Get an issue by ID",
     inputSchema: {
-      id: z6.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
+      id: z7.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleIssueGet(args.id, ctx)));
   server.registerTool("claudestory_handover_get", {
     description: "Content of a specific handover document by filename",
     inputSchema: {
-      filename: z6.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
+      filename: z7.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleHandoverGet(args.filename, ctx)));
+  server.registerTool("claudestory_recap", {
+    description: "Session diff \u2014 changes since last snapshot + suggested next actions. Shows what changed and what to work on."
+  }, () => runMcpReadTool(pinnedRoot, handleRecap));
+  server.registerTool("claudestory_snapshot", {
+    description: "Save current project state for session diffs. Creates a snapshot in .story/snapshots/."
+  }, () => runMcpWriteTool(pinnedRoot, handleSnapshot));
+  server.registerTool("claudestory_export", {
+    description: "Self-contained project document for sharing",
+    inputSchema: {
+      phase: z7.string().optional().describe("Export a single phase by ID"),
+      all: z7.boolean().optional().describe("Export entire project")
+    }
+  }, (args) => {
+    if (!args.phase && !args.all) {
+      return Promise.resolve({
+        content: [{ type: "text", text: formatMcpError("invalid_input", "Specify either phase or all") }],
+        isError: true
+      });
+    }
+    if (args.phase && args.all) {
+      return Promise.resolve({
+        content: [{ type: "text", text: formatMcpError("invalid_input", "Arguments phase and all are mutually exclusive") }],
+        isError: true
+      });
+    }
+    const mode = args.all ? "all" : "phase";
+    const phaseId = args.phase ?? null;
+    return runMcpReadTool(pinnedRoot, (ctx) => handleExport(ctx, mode, phaseId));
+  });
+  server.registerTool("claudestory_handover_create", {
+    description: "Create a handover document from markdown content",
+    inputSchema: {
+      content: z7.string().describe("Markdown content of the handover"),
+      slug: z7.string().optional().describe("Slug for filename (e.g. phase5b-wrapup). Default: session")
+    }
+  }, (args) => {
+    if (!args.content?.trim()) {
+      return Promise.resolve({
+        content: [{ type: "text", text: formatMcpError("invalid_input", "Handover content is empty") }],
+        isError: true
+      });
+    }
+    return runMcpWriteTool(
+      pinnedRoot,
+      (root) => handleHandoverCreate(args.content, args.slug ?? "session", "md", root)
+    );
+  });
 }
 
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.3";
+var version = "0.1.5";
 function pinProjectRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {
@@ -1717,7 +2485,7 @@ function pinProjectRoot() {
 `);
       process.exit(1);
     }
-    const resolved = resolve5(envRoot);
+    const resolved = resolve7(envRoot);
     let canonical;
     try {
       canonical = realpathSync(resolved);
@@ -1726,7 +2494,7 @@ function pinProjectRoot() {
 `);
       process.exit(1);
     }
-    if (!existsSync4(join6(canonical, CONFIG_PATH2))) {
+    if (!existsSync5(join8(canonical, CONFIG_PATH2))) {
       process.stderr.write(`Error: No .story/config.json at ${canonical}
 `);
       process.exit(1);