@anthropologies/claudestory 0.1.8 → 0.1.9

package/dist/mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/mcp/index.ts
-import { realpathSync, existsSync as existsSync5 } from "fs";
+import { realpathSync, existsSync as existsSync6 } 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";
@@ -64,7 +64,7 @@ function checkRoot(candidate) {
 }
 
 // src/mcp/tools.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 import { join as join7 } from "path";
 
 // src/core/project-loader.ts
@@ -77,7 +77,8 @@ import {
   stat,
   realpath,
   lstat,
-  open
+  open,
+  mkdir
 } from "fs/promises";
 import { existsSync as existsSync3 } from "fs";
 import { join as join3, resolve as resolve2, relative as relative2, extname as extname2, dirname as dirname2, basename } from "path";
@@ -94,6 +95,9 @@ var TICKET_STATUSES = ["open", "inprogress", "complete"];
 var TICKET_TYPES = ["task", "feature", "chore"];
 var ISSUE_STATUSES = ["open", "inprogress", "resolved"];
 var ISSUE_SEVERITIES = ["critical", "high", "medium", "low"];
+var NOTE_STATUSES = ["active", "archived"];
+var NOTE_ID_REGEX = /^N-\d+$/;
+var NoteIdSchema = z.string().regex(NOTE_ID_REGEX, "Note ID must match N-NNN");
 var DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 var DateSchema = z.string().regex(DATE_REGEX, "Date must be YYYY-MM-DD").refine(
   (val) => {
@@ -147,47 +151,65 @@ var IssueSchema = z3.object({
   lastModifiedBy: z3.string().nullable().optional()
 }).passthrough();
 
-// src/models/roadmap.ts
+// src/models/note.ts
 import { z as z4 } from "zod";
-var BlockerSchema = z4.object({
-  name: z4.string().min(1),
+var NoteSchema = z4.object({
+  id: NoteIdSchema,
+  title: z4.preprocess((v) => v ?? null, z4.string().nullable()),
+  content: z4.string().refine((v) => v.trim().length > 0, "Content cannot be empty"),
+  tags: z4.preprocess(
+    (v) => {
+      const raw = Array.isArray(v) ? v : [];
+      return raw.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "")).filter((t) => t.length > 0).filter((t, i, a) => a.indexOf(t) === i);
+    },
+    z4.array(z4.string())
+  ),
+  status: z4.enum(NOTE_STATUSES),
+  createdDate: DateSchema,
+  updatedDate: DateSchema
+}).passthrough();
+
+// src/models/roadmap.ts
+import { z as z5 } from "zod";
+var BlockerSchema = z5.object({
+  name: z5.string().min(1),
   // Legacy format (pre-T-082)
-  cleared: z4.boolean().optional(),
+  cleared: z5.boolean().optional(),
   // New date-based format (T-082 migration)
   createdDate: DateSchema.optional(),
   clearedDate: DateSchema.nullable().optional(),
   // Present in all current data but optional for future minimal blockers
-  note: z4.string().nullable().optional()
+  note: z5.string().nullable().optional()
 }).passthrough();
-var PhaseSchema = z4.object({
-  id: z4.string().min(1),
-  label: z4.string(),
-  name: z4.string(),
-  description: z4.string(),
-  summary: z4.string().optional()
+var PhaseSchema = z5.object({
+  id: z5.string().min(1),
+  label: z5.string(),
+  name: z5.string(),
+  description: z5.string(),
+  summary: z5.string().optional()
 }).passthrough();
-var RoadmapSchema = z4.object({
-  title: z4.string(),
+var RoadmapSchema = z5.object({
+  title: z5.string(),
   date: DateSchema,
-  phases: z4.array(PhaseSchema),
-  blockers: z4.array(BlockerSchema)
+  phases: z5.array(PhaseSchema),
+  blockers: z5.array(BlockerSchema)
 }).passthrough();
 
 // src/models/config.ts
-import { z as z5 } from "zod";
-var FeaturesSchema = z5.object({
-  tickets: z5.boolean(),
-  issues: z5.boolean(),
-  handovers: z5.boolean(),
-  roadmap: z5.boolean(),
-  reviews: z5.boolean()
+import { z as z6 } from "zod";
+var FeaturesSchema = z6.object({
+  tickets: z6.boolean(),
+  issues: z6.boolean(),
+  handovers: z6.boolean(),
+  roadmap: z6.boolean(),
+  reviews: z6.boolean()
 }).passthrough();
-var ConfigSchema = z5.object({
-  version: z5.number().int().min(1),
-  schemaVersion: z5.number().int().optional(),
-  project: z5.string().min(1),
-  type: z5.string(),
-  language: z5.string(),
+var ConfigSchema = z6.object({
+  version: z6.number().int().min(1),
+  schemaVersion: z6.number().int().optional(),
+  project: z6.string().min(1),
+  type: z6.string(),
+  language: z6.string(),
   features: FeaturesSchema
 }).passthrough();
 
@@ -196,6 +218,7 @@ var ProjectState = class _ProjectState {
   // --- Public raw inputs (readonly) ---
   tickets;
   issues;
+  notes;
   roadmap;
   config;
   handoverFilenames;
@@ -210,15 +233,19 @@ var ProjectState = class _ProjectState {
   reverseBlocksMap;
   ticketsByID;
   issuesByID;
+  notesByID;
   // --- Counts ---
   totalTicketCount;
   openTicketCount;
   completeTicketCount;
   openIssueCount;
   issuesBySeverity;
+  activeNoteCount;
+  archivedNoteCount;
   constructor(input) {
     this.tickets = input.tickets;
     this.issues = input.issues;
+    this.notes = input.notes;
     this.roadmap = input.roadmap;
     this.config = input.config;
     this.handoverFilenames = input.handoverFilenames;
@@ -284,6 +311,11 @@ var ProjectState = class _ProjectState {
       iByID.set(i.id, i);
     }
     this.issuesByID = iByID;
+    const nByID = /* @__PURE__ */ new Map();
+    for (const n of input.notes) {
+      nByID.set(n.id, n);
+    }
+    this.notesByID = nByID;
     this.totalTicketCount = input.tickets.length;
     this.openTicketCount = input.tickets.filter(
       (t) => t.status !== "complete"
@@ -301,6 +333,12 @@ var ProjectState = class _ProjectState {
       }
     }
     this.issuesBySeverity = bySev;
+    this.activeNoteCount = input.notes.filter(
+      (n) => n.status === "active"
+    ).length;
+    this.archivedNoteCount = input.notes.filter(
+      (n) => n.status === "archived"
+    ).length;
   }
   // --- Query Methods ---
   isUmbrella(ticket) {
@@ -347,6 +385,9 @@ var ProjectState = class _ProjectState {
   issueByID(id) {
     return this.issuesByID.get(id);
   }
+  noteByID(id) {
+    return this.notesByID.get(id);
+  }
   // --- Deletion Safety ---
   /** IDs of tickets that list `ticketId` in their blockedBy. */
   ticketsBlocking(ticketId) {
@@ -501,6 +542,12 @@ async function loadProject(root, options) {
     IssueSchema,
     warnings
   );
+  const notes = await loadDirectory(
+    join3(wrapDir, "notes"),
+    absRoot,
+    NoteSchema,
+    warnings
+  );
   const handoversDir = join3(wrapDir, "handovers");
   const handoverFilenames = await listHandovers(
     handoversDir,
@@ -521,12 +568,56 @@ async function loadProject(root, options) {
   const state = new ProjectState({
     tickets,
     issues,
+    notes,
     roadmap,
     config,
     handoverFilenames
   });
   return { state, warnings };
 }
+async function writeTicketUnlocked(ticket, root) {
+  const parsed = TicketSchema.parse(ticket);
+  if (!TICKET_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid ticket ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "tickets", `${parsed.id}.json`);
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeIssueUnlocked(issue, root) {
+  const parsed = IssueSchema.parse(issue);
+  if (!ISSUE_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid issue ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "issues", `${parsed.id}.json`);
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeNoteUnlocked(note, root) {
+  const parsed = NoteSchema.parse(note);
+  if (!NOTE_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "notes", `${parsed.id}.json`);
+  await mkdir(dirname2(targetPath), { recursive: true });
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
 async function withProjectLock(root, options, handler) {
   const absRoot = resolve2(root);
   const wrapDir = join3(absRoot, ".story");
@@ -629,8 +720,9 @@ async function loadProjectUnlocked(absRoot) {
   const warnings = [];
   const tickets = await loadDirectory(join3(wrapDir, "tickets"), absRoot, TicketSchema, warnings);
   const issues = await loadDirectory(join3(wrapDir, "issues"), absRoot, IssueSchema, warnings);
+  const notes = await loadDirectory(join3(wrapDir, "notes"), absRoot, NoteSchema, warnings);
   const handoverFilenames = await listHandovers(join3(wrapDir, "handovers"), absRoot, warnings);
-  const state = new ProjectState({ tickets, issues, roadmap, config, handoverFilenames });
+  const state = new ProjectState({ tickets, issues, notes, roadmap, config, handoverFilenames });
   return { state, warnings };
 }
 async function loadSingletonFile(filename, wrapDir, root, schema) {
@@ -711,6 +803,20 @@ async function loadDirectory(dirPath, root, schema, warnings) {
   }
   return results;
 }
+function sortKeysDeep(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  const obj = value;
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortKeysDeep(obj[key]);
+  }
+  return sorted;
+}
+function serializeJSON(obj) {
+  return JSON.stringify(sortKeysDeep(obj), null, 2) + "\n";
+}
 async function atomicWrite(targetPath, content) {
   const tempPath = `${targetPath}.${process.pid}.tmp`;
   try {
@@ -851,6 +957,19 @@ async function parseHandoverFilename(raw, handoversDir) {
   }
   return raw;
 }
+function normalizeTags(raw) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of raw) {
+    if (typeof item !== "string") continue;
+    const normalized = item.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+    if (normalized && !seen.has(normalized)) {
+      seen.add(normalized);
+      result.push(normalized);
+    }
+  }
+  return result;
+}
 
 // src/core/queries.ts
 function nextTicket(state) {
@@ -888,6 +1007,53 @@ function nextTicket(state) {
   }
   return { kind: "empty_project" };
 }
+function nextTickets(state, count) {
+  const effectiveCount = Math.max(1, count);
+  const phases = state.roadmap.phases;
+  if (phases.length === 0 || state.leafTickets.length === 0) {
+    return { kind: "empty_project" };
+  }
+  const candidates = [];
+  const skippedBlockedPhases = [];
+  let allPhasesComplete = true;
+  for (const phase of phases) {
+    if (candidates.length >= effectiveCount) break;
+    const leaves = state.phaseTickets(phase.id);
+    if (leaves.length === 0) continue;
+    const status = state.phaseStatus(phase.id);
+    if (status === "complete") continue;
+    allPhasesComplete = false;
+    const incompleteLeaves = leaves.filter((t) => t.status !== "complete");
+    const unblocked = incompleteLeaves.filter((t) => !state.isBlocked(t));
+    if (unblocked.length === 0) {
+      skippedBlockedPhases.push({
+        phaseId: phase.id,
+        blockedCount: incompleteLeaves.length
+      });
+      continue;
+    }
+    const remaining = effectiveCount - candidates.length;
+    for (const ticket of unblocked.slice(0, remaining)) {
+      const impact = ticketsUnblockedBy(ticket.id, state);
+      const progress = ticket.parentTicket ? umbrellaProgress(ticket.parentTicket, state) : null;
+      candidates.push({
+        ticket,
+        unblockImpact: { ticketId: ticket.id, wouldUnblock: impact },
+        umbrellaProgress: progress
+      });
+    }
+  }
+  if (candidates.length > 0) {
+    return { kind: "found", candidates, skippedBlockedPhases };
+  }
+  if (skippedBlockedPhases.length > 0) {
+    return { kind: "all_blocked", phases: skippedBlockedPhases };
+  }
+  if (allPhasesComplete) {
+    return { kind: "all_complete" };
+  }
+  return { kind: "empty_project" };
+}
 function blockedTickets(state) {
   return state.leafTickets.filter(
     (t) => t.status !== "complete" && state.isBlocked(t)
@@ -935,6 +1101,9 @@ function isBlockerCleared(blocker) {
   if (blocker.clearedDate != null) return true;
   return false;
 }
+function descendantLeaves(ticketId, state) {
+  return collectDescendantLeaves(ticketId, state, /* @__PURE__ */ new Set());
+}
 function collectDescendantLeaves(ticketId, state, visited) {
   if (visited.has(ticketId)) return [];
   visited.add(ticketId);
@@ -988,6 +1157,8 @@ function formatStatus(state, format) {
     openTickets: state.leafTicketCount - state.completeLeafTicketCount,
     blockedTickets: state.blockedCount,
     openIssues: state.openIssueCount,
+    activeNotes: state.activeNoteCount,
+    archivedNotes: state.archivedNoteCount,
     handovers: state.handoverFilenames.length,
     phases: phases.map((p) => ({
       id: p.phase.id,
@@ -1004,6 +1175,7 @@ function formatStatus(state, format) {
     "",
     `Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete, ${state.blockedCount} blocked`,
     `Issues: ${state.openIssueCount} open`,
+    `Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`,
     `Handovers: ${state.handoverFilenames.length}`,
     "",
     "## Phases",
@@ -1100,6 +1272,52 @@ function formatNextTicketOutcome(outcome, state, format) {
     }
   }
 }
+function formatNextTicketsOutcome(outcome, state, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(outcome), null, 2);
+  }
+  switch (outcome.kind) {
+    case "empty_project":
+      return "No phased tickets found.";
+    case "all_complete":
+      return "All phases complete.";
+    case "all_blocked": {
+      const details = outcome.phases.map((p) => `${escapeMarkdownInline(p.phaseId)} (${p.blockedCount} blocked)`).join(", ");
+      return `All incomplete tickets are blocked across ${outcome.phases.length} phase${outcome.phases.length === 1 ? "" : "s"}: ${details}`;
+    }
+    case "found": {
+      const { candidates, skippedBlockedPhases } = outcome;
+      const lines = [];
+      for (let i = 0; i < candidates.length; i++) {
+        const c = candidates[i];
+        const t = c.ticket;
+        if (i > 0) lines.push("", "---", "");
+        if (candidates.length === 1) {
+          lines.push(`# Next: ${escapeMarkdownInline(t.id)} \u2014 ${escapeMarkdownInline(t.title)}`);
+        } else {
+          lines.push(`# ${i + 1}. ${escapeMarkdownInline(t.id)} \u2014 ${escapeMarkdownInline(t.title)}`);
+        }
+        lines.push("", `Phase: ${t.phase ?? "none"} | Order: ${t.order} | Type: ${t.type}`);
+        if (c.unblockImpact.wouldUnblock.length > 0) {
+          const ids = c.unblockImpact.wouldUnblock.map((u) => u.id).join(", ");
+          lines.push(`Completing this unblocks: ${ids}`);
+        }
+        if (c.umbrellaProgress) {
+          const p = c.umbrellaProgress;
+          lines.push(`Parent progress: ${p.complete}/${p.total} complete (${p.status})`);
+        }
+        if (t.description) {
+          lines.push("", fencedBlock(t.description));
+        }
+      }
+      if (skippedBlockedPhases.length > 0) {
+        const details = skippedBlockedPhases.map((p) => `${escapeMarkdownInline(p.phaseId)} (${p.blockedCount} blocked)`).join(", ");
+        lines.push("", "---", "", `Skipped blocked phases: ${details}`);
+      }
+      return lines.join("\n");
+    }
+  }
+}
 function formatTicketList(tickets, format) {
   if (format === "json") {
     return JSON.stringify(successEnvelope(tickets), null, 2);
@@ -1214,6 +1432,50 @@ function formatBlockerList(roadmap, format) {
   }
   return lines.join("\n");
 }
+function formatNote(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  const title = note.title ?? `${note.createdDate} \u2014 ${note.id}`;
+  const statusBadge = note.status === "archived" ? " (archived)" : "";
+  const lines = [
+    `# ${escapeMarkdownInline(title)}${statusBadge}`,
+    "",
+    `Status: ${note.status}`
+  ];
+  if (note.tags.length > 0) {
+    lines.push(`Tags: ${note.tags.join(", ")}`);
+  }
+  lines.push(`Created: ${note.createdDate} | Updated: ${note.updatedDate}`);
+  lines.push("", fencedBlock(note.content));
+  return lines.join("\n");
+}
+function formatNoteList(notes, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(notes), null, 2);
+  }
+  if (notes.length === 0) return "No notes found.";
+  const lines = [];
+  for (const n of notes) {
+    const title = n.title ?? n.id;
+    const status = n.status === "archived" ? "[x]" : "[ ]";
+    const tagInfo = n.status === "archived" ? " (archived)" : n.tags.length > 0 ? ` (${n.tags.join(", ")})` : "";
+    lines.push(`${status} ${n.id}: ${escapeMarkdownInline(title)}${tagInfo}`);
+  }
+  return lines.join("\n");
+}
+function formatNoteCreateResult(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  return `Created note ${note.id}: ${note.title ?? note.id}`;
+}
+function formatNoteUpdateResult(note, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(note), null, 2);
+  }
+  return `Updated note ${note.id}: ${note.title ?? note.id}`;
+}
 function formatError(code, message, format) {
   if (format === "json") {
     return JSON.stringify(errorEnvelope(code, message), null, 2);
@@ -1281,7 +1543,7 @@ function formatRecap(recap, state, format) {
         }
       }
       const ticketChanges = changes.tickets;
-      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0) {
+      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0 || ticketChanges.descriptionChanged.length > 0) {
         lines.push("");
         lines.push("## Tickets");
         for (const t of ticketChanges.statusChanged) {
@@ -1293,9 +1555,12 @@ function formatRecap(recap, state, format) {
         for (const t of ticketChanges.removed) {
           lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **removed**`);
         }
+        for (const t of ticketChanges.descriptionChanged) {
+          lines.push(`- ${t.id}: description updated`);
+        }
       }
       const issueChanges = changes.issues;
-      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0) {
+      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0 || issueChanges.impactChanged.length > 0) {
         lines.push("");
         lines.push("## Issues");
         for (const i of issueChanges.resolved) {
@@ -1307,6 +1572,9 @@ function formatRecap(recap, state, format) {
         for (const i of issueChanges.added) {
           lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **new**`);
         }
+        for (const i of issueChanges.impactChanged) {
+          lines.push(`- ${i.id}: impact updated`);
+        }
       }
       if (changes.blockers.added.length > 0 || changes.blockers.cleared.length > 0) {
         lines.push("");
@@ -1318,6 +1586,19 @@ function formatRecap(recap, state, format) {
           lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
         }
       }
+      if (changes.notes && (changes.notes.added.length > 0 || changes.notes.removed.length > 0 || changes.notes.updated.length > 0)) {
+        lines.push("");
+        lines.push("## Notes");
+        for (const n of changes.notes.added) {
+          lines.push(`- ${n.id}: added`);
+        }
+        for (const n of changes.notes.removed) {
+          lines.push(`- ${n.id}: removed`);
+        }
+        for (const n of changes.notes.updated) {
+          lines.push(`- ${n.id}: updated (${n.changedFields.join(", ")})`);
+        }
+      }
     }
   }
   const actions = recap.suggestedActions;
@@ -1456,6 +1737,12 @@ function formatFullExport(state, format) {
           severity: i.severity,
           status: i.status
         })),
+        notes: state.notes.map((n) => ({
+          id: n.id,
+          title: n.title,
+          status: n.status,
+          tags: n.tags
+        })),
         blockers: state.roadmap.blockers.map((b) => ({
           name: b.name,
           cleared: isBlockerCleared(b),
@@ -1471,6 +1758,7 @@ function formatFullExport(state, format) {
   lines.push("");
   lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete`);
   lines.push(`Issues: ${state.openIssueCount} open`);
+  lines.push(`Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`);
   lines.push("");
   lines.push("## Phases");
   for (const p of phases) {
@@ -1497,6 +1785,16 @@ function formatFullExport(state, format) {
       lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}${resolved}`);
     }
   }
+  const activeNotes = state.notes.filter((n) => n.status === "active");
+  if (activeNotes.length > 0) {
+    lines.push("");
+    lines.push("## Notes");
+    for (const n of activeNotes) {
+      const title = n.title ?? n.id;
+      const tagInfo = n.tags.length > 0 ? ` (${n.tags.join(", ")})` : "";
+      lines.push(`- ${n.id}: ${escapeMarkdownInline(title)}${tagInfo}`);
+    }
+  }
   const blockers = state.roadmap.blockers;
   if (blockers.length > 0) {
     lines.push("");
@@ -1509,7 +1807,7 @@ function formatFullExport(state, format) {
   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;
+  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.tickets.descriptionChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.issues.impactChanged.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 || (diff.notes?.added.length ?? 0) > 0 || (diff.notes?.removed.length ?? 0) > 0 || (diff.notes?.updated.length ?? 0) > 0;
 }
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
@@ -1520,6 +1818,29 @@ function formatTicketOneLiner(t, state) {
   const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
   return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
 }
+function formatRecommendations(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  if (result.recommendations.length === 0) {
+    return "No recommendations \u2014 all work is complete or blocked.";
+  }
+  const lines = ["# Recommendations", ""];
+  for (let i = 0; i < result.recommendations.length; i++) {
+    const rec = result.recommendations[i];
+    lines.push(
+      `${i + 1}. **${escapeMarkdownInline(rec.id)}** (${rec.kind}) \u2014 ${escapeMarkdownInline(rec.title)}`
+    );
+    lines.push(`   _${escapeMarkdownInline(rec.reason)}_`);
+    lines.push("");
+  }
+  if (result.totalCandidates > result.recommendations.length) {
+    lines.push(
+      `Showing ${result.recommendations.length} of ${result.totalCandidates} candidates.`
+    );
+  }
+  return lines.join("\n");
+}
 
 // src/cli/commands/status.ts
 function handleStatus(ctx) {
@@ -1562,6 +1883,20 @@ function validateProject(state) {
       });
     }
   }
+  const noteIDCounts = /* @__PURE__ */ new Map();
+  for (const n of state.notes) {
+    noteIDCounts.set(n.id, (noteIDCounts.get(n.id) ?? 0) + 1);
+  }
+  for (const [id, count] of noteIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_note_id",
+        message: `Duplicate note ID: ${id} appears ${count} times.`,
+        entity: id
+      });
+    }
+  }
   const phaseIDCounts = /* @__PURE__ */ new Map();
   for (const p of state.roadmap.phases) {
     phaseIDCounts.set(p.id, (phaseIDCounts.get(p.id) ?? 0) + 1);
@@ -1778,12 +2113,13 @@ function handleValidate(ctx) {
 }
 
 // src/cli/commands/handover.ts
-import { mkdir } from "fs/promises";
+import { existsSync as existsSync4 } from "fs";
+import { mkdir as mkdir2 } from "fs/promises";
 import { join as join4, resolve as resolve4 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
-async function handleHandoverLatest(ctx) {
+async function handleHandoverLatest(ctx, count = 1) {
   if (ctx.state.handoverFilenames.length === 0) {
     return {
       output: formatError("not_found", "No handovers found", ctx.format),
@@ -1791,25 +2127,38 @@ async function handleHandoverLatest(ctx) {
       errorCode: "not_found"
     };
   }
-  const filename = ctx.state.handoverFilenames[0];
-  await parseHandoverFilename(filename, ctx.handoversDir);
-  try {
-    const content = await readHandover(ctx.handoversDir, filename);
-    return { output: formatHandoverContent(filename, content, ctx.format) };
-  } catch (err) {
-    if (err.code === "ENOENT") {
+  const filenames = ctx.state.handoverFilenames.slice(0, count);
+  const parts = [];
+  for (const filename of filenames) {
+    await parseHandoverFilename(filename, ctx.handoversDir);
+    try {
+      const content = await readHandover(ctx.handoversDir, filename);
+      parts.push(formatHandoverContent(filename, content, ctx.format));
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        if (count > 1) continue;
+        return {
+          output: formatError("not_found", `Handover file not found: ${filename}`, ctx.format),
+          exitCode: ExitCode.USER_ERROR,
+          errorCode: "not_found"
+        };
+      }
       return {
-        output: formatError("not_found", `Handover file not found: ${filename}`, ctx.format),
+        output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
         exitCode: ExitCode.USER_ERROR,
-        errorCode: "not_found"
+        errorCode: "io_error"
       };
     }
+  }
+  if (parts.length === 0) {
     return {
-      output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
+      output: formatError("not_found", "No handovers found", ctx.format),
       exitCode: ExitCode.USER_ERROR,
-      errorCode: "io_error"
+      errorCode: "not_found"
     };
   }
+  const separator = ctx.format === "json" ? "\n" : "\n\n---\n\n";
+  return { output: parts.join(separator) };
 }
 async function handleHandoverGet(filename, ctx) {
   await parseHandoverFilename(filename, ctx.handoversDir);
@@ -1852,7 +2201,7 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
   await withProjectLock(root, { strict: false }, async () => {
     const absRoot = resolve4(root);
     const handoversDir = join4(absRoot, ".story", "handovers");
-    await mkdir(handoversDir, { recursive: true });
+    await mkdir2(handoversDir, { recursive: true });
     const wrapDir = join4(absRoot, ".story");
     const datePrefix = `${date}-`;
     const seqRegex = new RegExp(`^${date}-(\\d{2})-`);
@@ -1868,15 +2217,26 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
       }
     } catch {
     }
-    const nextSeq = maxSeq + 1;
+    let 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);
+    let candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+    let candidatePath = join4(handoversDir, candidate);
+    while (existsSync4(candidatePath)) {
+      nextSeq++;
+      if (nextSeq > 99) {
+        throw new CliValidationError(
+          "conflict",
+          `Too many handovers for ${date}; limit is 99 per day`
+        );
+      }
+      candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
+      candidatePath = join4(handoversDir, candidate);
+    }
     await parseHandoverFilename(candidate, handoversDir);
     await guardPath(candidatePath, wrapDir);
     await atomicWrite(candidatePath, content);
@@ -1890,6 +2250,52 @@ function handleBlockerList(ctx) {
   return { output: formatBlockerList(ctx.state.roadmap, ctx.format) };
 }
 
+// src/core/id-allocation.ts
+var TICKET_NUMERIC_REGEX = /^T-(\d+)[a-z]?$/;
+var ISSUE_NUMERIC_REGEX = /^ISS-(\d+)$/;
+var NOTE_NUMERIC_REGEX = /^N-(\d+)$/;
+function nextTicketID(tickets) {
+  let max = 0;
+  for (const t of tickets) {
+    if (!TICKET_ID_REGEX.test(t.id)) continue;
+    const match = t.id.match(TICKET_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `T-${String(max + 1).padStart(3, "0")}`;
+}
+function nextIssueID(issues) {
+  let max = 0;
+  for (const i of issues) {
+    if (!ISSUE_ID_REGEX.test(i.id)) continue;
+    const match = i.id.match(ISSUE_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `ISS-${String(max + 1).padStart(3, "0")}`;
+}
+function nextNoteID(notes) {
+  let max = 0;
+  for (const n of notes) {
+    if (!NOTE_ID_REGEX.test(n.id)) continue;
+    const match = n.id.match(NOTE_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `N-${String(max + 1).padStart(3, "0")}`;
+}
+function nextOrder(phaseId, state) {
+  const tickets = state.phaseTickets(phaseId);
+  if (tickets.length === 0) return 10;
+  return tickets[tickets.length - 1].order + 10;
+}
+
 // src/cli/commands/ticket.ts
 function handleTicketList(filters, ctx) {
   let tickets = [...ctx.state.leafTickets];
@@ -1927,18 +2333,159 @@ function handleTicketGet(id, ctx) {
   }
   return { output: formatTicket(ticket, ctx.state, ctx.format) };
 }
-function handleTicketNext(ctx) {
-  const outcome = nextTicket(ctx.state);
+function handleTicketNext(ctx, count = 1) {
+  if (count <= 1) {
+    const outcome2 = nextTicket(ctx.state);
+    const exitCode2 = outcome2.kind === "found" ? ExitCode.OK : ExitCode.USER_ERROR;
+    return { output: formatNextTicketOutcome(outcome2, ctx.state, ctx.format), exitCode: exitCode2 };
+  }
+  const outcome = nextTickets(ctx.state, count);
   const exitCode = outcome.kind === "found" ? ExitCode.OK : ExitCode.USER_ERROR;
-  return {
-    output: formatNextTicketOutcome(outcome, ctx.state, ctx.format),
-    exitCode
-  };
+  return { output: formatNextTicketsOutcome(outcome, ctx.state, ctx.format), exitCode };
 }
 function handleTicketBlocked(ctx) {
   const blocked = blockedTickets(ctx.state);
   return { output: formatBlockedTickets(blocked, ctx.state, ctx.format) };
 }
+function validatePhase(phase, ctx) {
+  if (phase !== null && !ctx.state.roadmap.phases.some((p) => p.id === phase)) {
+    throw new CliValidationError("invalid_input", `Phase "${phase}" not found in roadmap`);
+  }
+}
+function validateBlockedBy(ids, ticketId, state) {
+  for (const bid of ids) {
+    if (bid === ticketId) {
+      throw new CliValidationError("invalid_input", `Ticket cannot block itself: ${bid}`);
+    }
+    const blocker = state.ticketByID(bid);
+    if (!blocker) {
+      throw new CliValidationError("invalid_input", `Blocked-by ticket ${bid} not found`);
+    }
+    if (state.umbrellaIDs.has(bid)) {
+      throw new CliValidationError("invalid_input", `Cannot block on umbrella ticket ${bid}. Use leaf tickets instead.`);
+    }
+  }
+}
+function validateParentTicket(parentId, ticketId, state) {
+  if (parentId === ticketId) {
+    throw new CliValidationError("invalid_input", `Ticket cannot be its own parent`);
+  }
+  if (!state.ticketByID(parentId)) {
+    throw new CliValidationError("invalid_input", `Parent ticket ${parentId} not found`);
+  }
+}
+function validatePostWriteState(candidate, state, isCreate) {
+  const existingTickets = [...state.tickets];
+  if (isCreate) {
+    existingTickets.push(candidate);
+  } else {
+    const idx = existingTickets.findIndex((t) => t.id === candidate.id);
+    if (idx >= 0) existingTickets[idx] = candidate;
+    else existingTickets.push(candidate);
+  }
+  const postState = new ProjectState({
+    tickets: existingTickets,
+    issues: [...state.issues],
+    notes: [...state.notes],
+    roadmap: state.roadmap,
+    config: state.config,
+    handoverFilenames: [...state.handoverFilenames]
+  });
+  const result = validateProject(postState);
+  if (!result.valid) {
+    const errors = result.findings.filter((f) => f.level === "error");
+    const msg = errors.map((f) => f.message).join("; ");
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${msg}`);
+  }
+}
+async function handleTicketCreate(args, format, root) {
+  if (!TICKET_TYPES.includes(args.type)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown ticket type "${args.type}": must be one of ${TICKET_TYPES.join(", ")}`
+    );
+  }
+  let createdTicket;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    validatePhase(args.phase, { state });
+    if (args.blockedBy.length > 0) {
+      validateBlockedBy(args.blockedBy, "", state);
+    }
+    if (args.parentTicket) {
+      validateParentTicket(args.parentTicket, "", state);
+    }
+    const id = nextTicketID(state.tickets);
+    const order = nextOrder(args.phase, state);
+    const ticket = {
+      id,
+      title: args.title,
+      description: args.description,
+      type: args.type,
+      status: "open",
+      phase: args.phase,
+      order,
+      createdDate: todayISO(),
+      completedDate: null,
+      blockedBy: args.blockedBy,
+      parentTicket: args.parentTicket ?? void 0
+    };
+    validatePostWriteState(ticket, state, true);
+    await writeTicketUnlocked(ticket, root);
+    createdTicket = ticket;
+  });
+  if (!createdTicket) throw new Error("Ticket not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdTicket), null, 2) };
+  }
+  return { output: `Created ticket ${createdTicket.id}: ${createdTicket.title}` };
+}
+async function handleTicketUpdate(id, updates, format, root) {
+  if (updates.status && !TICKET_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown ticket status "${updates.status}": must be one of ${TICKET_STATUSES.join(", ")}`
+    );
+  }
+  let updatedTicket;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.ticketByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Ticket ${id} not found`);
+    }
+    if (updates.phase !== void 0) {
+      validatePhase(updates.phase, { state });
+    }
+    if (updates.blockedBy) {
+      validateBlockedBy(updates.blockedBy, id, state);
+    }
+    if (updates.parentTicket) {
+      validateParentTicket(updates.parentTicket, id, state);
+    }
+    const ticket = { ...existing };
+    if (updates.title !== void 0) ticket.title = updates.title;
+    if (updates.description !== void 0) ticket.description = updates.description;
+    if (updates.phase !== void 0) ticket.phase = updates.phase;
+    if (updates.order !== void 0) ticket.order = updates.order;
+    if (updates.blockedBy !== void 0) ticket.blockedBy = updates.blockedBy;
+    if (updates.parentTicket !== void 0) ticket.parentTicket = updates.parentTicket === null ? void 0 : updates.parentTicket;
+    if (updates.status !== void 0 && updates.status !== existing.status) {
+      ticket.status = updates.status;
+      if (updates.status === "complete" && existing.status !== "complete") {
+        ticket.completedDate = todayISO();
+      } else if (updates.status !== "complete" && existing.status === "complete") {
+        ticket.completedDate = null;
+      }
+    }
+    validatePostWriteState(ticket, state, false);
+    await writeTicketUnlocked(ticket, root);
+    updatedTicket = ticket;
+  });
+  if (!updatedTicket) throw new Error("Ticket not updated");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(updatedTicket), null, 2) };
+  }
+  return { output: `Updated ticket ${updatedTicket.id}: ${updatedTicket.title}` };
+}
 
 // src/cli/commands/issue.ts
 function handleIssueList(filters, ctx) {
@@ -1961,6 +2508,9 @@ function handleIssueList(filters, ctx) {
     }
     issues = issues.filter((i) => i.severity === filters.severity);
   }
+  if (filters.component) {
+    issues = issues.filter((i) => i.components.includes(filters.component));
+  }
   return { output: formatIssueList(issues, ctx.format) };
 }
 function handleIssueGet(id, ctx) {
@@ -1974,32 +2524,149 @@ function handleIssueGet(id, ctx) {
   }
   return { output: formatIssue(issue, ctx.format) };
 }
+function validateRelatedTickets(ids, state) {
+  for (const tid of ids) {
+    if (!state.ticketByID(tid)) {
+      throw new CliValidationError("invalid_input", `Related ticket ${tid} not found`);
+    }
+  }
+}
+function validatePostWriteIssueState(candidate, state, isCreate) {
+  const existingIssues = [...state.issues];
+  if (isCreate) {
+    existingIssues.push(candidate);
+  } else {
+    const idx = existingIssues.findIndex((i) => i.id === candidate.id);
+    if (idx >= 0) existingIssues[idx] = candidate;
+    else existingIssues.push(candidate);
+  }
+  const postState = new ProjectState({
+    tickets: [...state.tickets],
+    issues: existingIssues,
+    notes: [...state.notes],
+    roadmap: state.roadmap,
+    config: state.config,
+    handoverFilenames: [...state.handoverFilenames]
+  });
+  const result = validateProject(postState);
+  if (!result.valid) {
+    const errors = result.findings.filter((f) => f.level === "error");
+    const msg = errors.map((f) => f.message).join("; ");
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${msg}`);
+  }
+}
+async function handleIssueCreate(args, format, root) {
+  if (!ISSUE_SEVERITIES.includes(args.severity)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue severity "${args.severity}": must be one of ${ISSUE_SEVERITIES.join(", ")}`
+    );
+  }
+  let createdIssue;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    if (args.relatedTickets.length > 0) {
+      validateRelatedTickets(args.relatedTickets, state);
+    }
+    const id = nextIssueID(state.issues);
+    const issue = {
+      id,
+      title: args.title,
+      status: "open",
+      severity: args.severity,
+      components: args.components,
+      impact: args.impact,
+      resolution: null,
+      location: args.location,
+      discoveredDate: todayISO(),
+      resolvedDate: null,
+      relatedTickets: args.relatedTickets,
+      phase: args.phase ?? null
+    };
+    validatePostWriteIssueState(issue, state, true);
+    await writeIssueUnlocked(issue, root);
+    createdIssue = issue;
+  });
+  if (!createdIssue) throw new Error("Issue not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdIssue), null, 2) };
+  }
+  return { output: `Created issue ${createdIssue.id}: ${createdIssue.title}` };
+}
+async function handleIssueUpdate(id, updates, format, root) {
+  if (updates.status && !ISSUE_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue status "${updates.status}": must be one of ${ISSUE_STATUSES.join(", ")}`
+    );
+  }
+  if (updates.severity && !ISSUE_SEVERITIES.includes(updates.severity)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue severity "${updates.severity}": must be one of ${ISSUE_SEVERITIES.join(", ")}`
+    );
+  }
+  let updatedIssue;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.issueByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Issue ${id} not found`);
+    }
+    if (updates.relatedTickets) {
+      validateRelatedTickets(updates.relatedTickets, state);
+    }
+    const issue = { ...existing };
+    if (updates.title !== void 0) issue.title = updates.title;
+    if (updates.severity !== void 0) issue.severity = updates.severity;
+    if (updates.impact !== void 0) issue.impact = updates.impact;
+    if (updates.resolution !== void 0) issue.resolution = updates.resolution;
+    if (updates.components !== void 0) issue.components = updates.components;
+    if (updates.relatedTickets !== void 0) issue.relatedTickets = updates.relatedTickets;
+    if (updates.location !== void 0) issue.location = updates.location;
+    if (updates.status !== void 0 && updates.status !== existing.status) {
+      issue.status = updates.status;
+      if (updates.status === "resolved" && existing.status !== "resolved") {
+        issue.resolvedDate = todayISO();
+      } else if (updates.status !== "resolved" && existing.status === "resolved") {
+        issue.resolvedDate = null;
+      }
+    }
+    validatePostWriteIssueState(issue, state, false);
+    await writeIssueUnlocked(issue, root);
+    updatedIssue = issue;
+  });
+  if (!updatedIssue) throw new Error("Issue not updated");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(updatedIssue), null, 2) };
+  }
+  return { output: `Updated issue ${updatedIssue.id}: ${updatedIssue.title}` };
+}
 
 // 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 { readdir as readdir3, readFile as readFile3, mkdir as mkdir3, unlink as unlink2 } from "fs/promises";
+import { existsSync as existsSync5 } 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()
+import { z as z7 } from "zod";
+var LoadWarningSchema = z7.object({
+  type: z7.string(),
+  file: z7.string(),
+  message: z7.string()
 });
-var SnapshotV1Schema = z6.object({
-  version: z6.literal(1),
-  createdAt: z6.string().datetime({ offset: true }),
-  project: z6.string(),
+var SnapshotV1Schema = z7.object({
+  version: z7.literal(1),
+  createdAt: z7.string().datetime({ offset: true }),
+  project: z7.string(),
   config: ConfigSchema,
   roadmap: RoadmapSchema,
-  tickets: z6.array(TicketSchema),
-  issues: z6.array(IssueSchema),
-  warnings: z6.array(LoadWarningSchema).optional()
+  tickets: z7.array(TicketSchema),
+  issues: z7.array(IssueSchema),
+  notes: z7.array(NoteSchema).optional().default([]),
+  warnings: z7.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 });
+  await mkdir3(snapshotsDir, { recursive: true });
   const { state, warnings } = loadResult;
   const now = /* @__PURE__ */ new Date();
   const filename = formatSnapshotFilename(now);
@@ -2011,6 +2678,7 @@ async function saveSnapshot(root, loadResult) {
     roadmap: state.roadmap,
     tickets: [...state.tickets],
     issues: [...state.issues],
+    notes: [...state.notes],
     ...warnings.length > 0 ? {
       warnings: warnings.map((w) => ({
         type: w.type,
@@ -2030,7 +2698,7 @@ async function saveSnapshot(root, loadResult) {
 }
 async function loadLatestSnapshot(root) {
   const snapshotsDir = join5(resolve5(root), ".story", "snapshots");
-  if (!existsSync4(snapshotsDir)) return null;
+  if (!existsSync5(snapshotsDir)) return null;
   const files = await listSnapshotFiles(snapshotsDir);
   if (files.length === 0) return null;
   for (const filename of files) {
@@ -2051,12 +2719,18 @@ function diffStates(snapshotState, currentState) {
   const ticketsAdded = [];
   const ticketsRemoved = [];
   const ticketsStatusChanged = [];
+  const ticketsDescriptionChanged = [];
   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 });
+    } else {
+      if (snap.status !== cur.status) {
+        ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+      }
+      if (snap.description !== cur.description) {
+        ticketsDescriptionChanged.push({ id, title: cur.title });
+      }
     }
   }
   for (const [id, snap] of snapTickets) {
@@ -2069,15 +2743,21 @@ function diffStates(snapshotState, currentState) {
   const issuesAdded = [];
   const issuesResolved = [];
   const issuesStatusChanged = [];
+  const issuesImpactChanged = [];
   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 });
+    } 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 });
+        }
+      }
+      if (snap.impact !== cur.impact) {
+        issuesImpactChanged.push({ id, title: cur.title });
       }
     }
   }
@@ -2126,11 +2806,37 @@ function diffStates(snapshotState, currentState) {
       phasesRemoved.push({ id, name: snapPhase.name });
     }
   }
+  const snapNotes = new Map(snapshotState.notes.map((n) => [n.id, n]));
+  const curNotes = new Map(currentState.notes.map((n) => [n.id, n]));
+  const notesAdded = [];
+  const notesRemoved = [];
+  const notesUpdated = [];
+  for (const [id, cur] of curNotes) {
+    const snap = snapNotes.get(id);
+    if (!snap) {
+      notesAdded.push({ id, title: cur.title });
+    } else {
+      const changedFields = [];
+      if (snap.title !== cur.title) changedFields.push("title");
+      if (snap.content !== cur.content) changedFields.push("content");
+      if (JSON.stringify([...snap.tags].sort()) !== JSON.stringify([...cur.tags].sort())) changedFields.push("tags");
+      if (snap.status !== cur.status) changedFields.push("status");
+      if (changedFields.length > 0) {
+        notesUpdated.push({ id, title: cur.title, changedFields });
+      }
+    }
+  }
+  for (const [id, snap] of snapNotes) {
+    if (!curNotes.has(id)) {
+      notesRemoved.push({ id, title: snap.title });
+    }
+  }
   return {
-    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged },
-    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged },
+    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged, descriptionChanged: ticketsDescriptionChanged },
+    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged, impactChanged: issuesImpactChanged },
     blockers: { added: blockersAdded, cleared: blockersCleared },
-    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged }
+    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged },
+    notes: { added: notesAdded, removed: notesRemoved, updated: notesUpdated }
   };
 }
 function buildRecap(currentState, snapshotInfo) {
@@ -2155,6 +2861,7 @@ function buildRecap(currentState, snapshotInfo) {
   const snapshotState = new ProjectState({
     tickets: snapshot.tickets,
     issues: snapshot.issues,
+    notes: snapshot.notes ?? [],
     roadmap: snapshot.roadmap,
     config: snapshot.config,
     handoverFilenames: []
@@ -2210,12 +2917,358 @@ async function handleRecap(ctx) {
   return { output: formatRecap(recap, ctx.state, ctx.format) };
 }
 
+// src/cli/commands/note.ts
+function handleNoteList(filters, ctx) {
+  let notes = [...ctx.state.notes];
+  if (filters.status) {
+    if (!NOTE_STATUSES.includes(filters.status)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown note status "${filters.status}": must be one of ${NOTE_STATUSES.join(", ")}`
+      );
+    }
+    notes = notes.filter((n) => n.status === filters.status);
+  }
+  if (filters.tag) {
+    const normalized = normalizeTags([filters.tag]);
+    if (normalized.length === 0) {
+      notes = [];
+    } else {
+      const tag = normalized[0];
+      notes = notes.filter((n) => n.tags.includes(tag));
+    }
+  }
+  notes.sort((a, b) => {
+    const dateCmp = b.updatedDate.localeCompare(a.updatedDate);
+    if (dateCmp !== 0) return dateCmp;
+    return a.id.localeCompare(b.id);
+  });
+  return { output: formatNoteList(notes, ctx.format) };
+}
+function handleNoteGet(id, ctx) {
+  const note = ctx.state.noteByID(id);
+  if (!note) {
+    return {
+      output: formatError("not_found", `Note ${id} not found`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "not_found"
+    };
+  }
+  return { output: formatNote(note, ctx.format) };
+}
+async function handleNoteCreate(args, format, root) {
+  if (!args.content.trim()) {
+    throw new CliValidationError("invalid_input", "Note content cannot be empty");
+  }
+  let createdNote;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const id = nextNoteID(state.notes);
+    const today = todayISO();
+    const tags = args.tags ? normalizeTags(args.tags) : [];
+    const note = {
+      id,
+      title: args.title && args.title.trim() !== "" ? args.title : null,
+      content: args.content,
+      tags,
+      status: "active",
+      createdDate: today,
+      updatedDate: today
+    };
+    await writeNoteUnlocked(note, root);
+    createdNote = note;
+  });
+  if (!createdNote) throw new Error("Note not created");
+  return { output: formatNoteCreateResult(createdNote, format) };
+}
+async function handleNoteUpdate(id, updates, format, root) {
+  if (updates.content !== void 0 && !updates.content.trim()) {
+    throw new CliValidationError("invalid_input", "Note content cannot be empty");
+  }
+  if (updates.status && !NOTE_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown note status "${updates.status}": must be one of ${NOTE_STATUSES.join(", ")}`
+    );
+  }
+  let updatedNote;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.noteByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Note ${id} not found`);
+    }
+    const note = { ...existing };
+    if (updates.content !== void 0) {
+      note.content = updates.content;
+    }
+    if (updates.title !== void 0) {
+      const trimmed = updates.title?.trim();
+      note.title = !trimmed ? null : updates.title;
+    }
+    if (updates.clearTags) {
+      note.tags = [];
+    } else if (updates.tags !== void 0) {
+      note.tags = normalizeTags(updates.tags);
+    }
+    if (updates.status !== void 0) {
+      note.status = updates.status;
+    }
+    note.updatedDate = todayISO();
+    await writeNoteUnlocked(note, root);
+    updatedNote = note;
+  });
+  if (!updatedNote) throw new Error("Note not updated");
+  return { output: formatNoteUpdateResult(updatedNote, format) };
+}
+
+// src/core/recommend.ts
+var SEVERITY_RANK = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1
+};
+var PHASE_DISTANCE_PENALTY = 100;
+var MAX_PHASE_PENALTY = 400;
+var CATEGORY_PRIORITY = {
+  validation_errors: 1,
+  critical_issue: 2,
+  inprogress_ticket: 3,
+  high_impact_unblock: 4,
+  near_complete_umbrella: 5,
+  phase_momentum: 6,
+  quick_win: 7,
+  open_issue: 8
+};
+function recommend(state, count) {
+  const effectiveCount = Math.max(1, Math.min(10, count));
+  const dedup = /* @__PURE__ */ new Map();
+  const phaseIndex = buildPhaseIndex(state);
+  const generators = [
+    () => generateValidationSuggestions(state),
+    () => generateCriticalIssues(state),
+    () => generateInProgressTickets(state, phaseIndex),
+    () => generateHighImpactUnblocks(state),
+    () => generateNearCompleteUmbrellas(state, phaseIndex),
+    () => generatePhaseMomentum(state),
+    () => generateQuickWins(state, phaseIndex),
+    () => generateOpenIssues(state)
+  ];
+  for (const gen of generators) {
+    for (const rec of gen()) {
+      const existing = dedup.get(rec.id);
+      if (!existing || rec.score > existing.score) {
+        dedup.set(rec.id, rec);
+      }
+    }
+  }
+  const curPhase = currentPhase(state);
+  const curPhaseIdx = curPhase ? phaseIndex.get(curPhase.id) ?? 0 : 0;
+  for (const [id, rec] of dedup) {
+    if (rec.kind !== "ticket") continue;
+    const ticket = state.ticketByID(id);
+    if (!ticket || ticket.phase == null) continue;
+    const ticketPhaseIdx = phaseIndex.get(ticket.phase);
+    if (ticketPhaseIdx === void 0) continue;
+    const phasesAhead = ticketPhaseIdx - curPhaseIdx;
+    if (phasesAhead > 0) {
+      const penalty = Math.min(phasesAhead * PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY);
+      dedup.set(id, {
+        ...rec,
+        score: rec.score - penalty,
+        reason: rec.reason + " (future phase)"
+      });
+    }
+  }
+  const all = [...dedup.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const catDiff = CATEGORY_PRIORITY[a.category] - CATEGORY_PRIORITY[b.category];
+    if (catDiff !== 0) return catDiff;
+    return a.id.localeCompare(b.id);
+  });
+  return {
+    recommendations: all.slice(0, effectiveCount),
+    totalCandidates: all.length
+  };
+}
+function generateValidationSuggestions(state) {
+  const result = validateProject(state);
+  if (result.errorCount === 0) return [];
+  return [
+    {
+      id: "validate",
+      kind: "action",
+      title: "Run claudestory validate",
+      category: "validation_errors",
+      reason: `${result.errorCount} validation error${result.errorCount === 1 ? "" : "s"} \u2014 fix before other work`,
+      score: 1e3
+    }
+  ];
+}
+function generateCriticalIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "critical" || i.severity === "high")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "critical_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress, ensure it's being addressed` : `${capitalize(issue.severity)} severity issue \u2014 address before new features`,
+    score: 900 - Math.min(index, 99)
+  }));
+}
+function generateInProgressTickets(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "inprogress"
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "inprogress_ticket",
+    reason: "In-progress \u2014 finish what's started",
+    score: 800 - Math.min(index, 99)
+  }));
+}
+function generateHighImpactUnblocks(state) {
+  const candidates = [];
+  for (const ticket of state.leafTickets) {
+    if (ticket.status === "complete") continue;
+    if (state.isBlocked(ticket)) continue;
+    const wouldUnblock = ticketsUnblockedBy(ticket.id, state);
+    if (wouldUnblock.length >= 2) {
+      candidates.push({ ticket, unblockCount: wouldUnblock.length });
+    }
+  }
+  candidates.sort((a, b) => b.unblockCount - a.unblockCount);
+  return candidates.map(({ ticket, unblockCount }, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "high_impact_unblock",
+    reason: `Completing this unblocks ${unblockCount} other ticket${unblockCount === 1 ? "" : "s"}`,
+    score: 700 - Math.min(index, 99)
+  }));
+}
+function generateNearCompleteUmbrellas(state, phaseIndex) {
+  const candidates = [];
+  for (const umbrellaId of state.umbrellaIDs) {
+    const progress = umbrellaProgress(umbrellaId, state);
+    if (!progress) continue;
+    if (progress.total < 2) continue;
+    if (progress.status === "complete") continue;
+    const ratio = progress.complete / progress.total;
+    if (ratio < 0.8) continue;
+    const leaves = descendantLeaves(umbrellaId, state);
+    const incomplete = leaves.filter((t) => t.status !== "complete");
+    const sorted = sortByPhaseAndOrder(incomplete, phaseIndex);
+    if (sorted.length === 0) continue;
+    const umbrella = state.ticketByID(umbrellaId);
+    candidates.push({
+      umbrellaId,
+      umbrellaTitle: umbrella?.title ?? umbrellaId,
+      firstIncompleteLeaf: sorted[0],
+      complete: progress.complete,
+      total: progress.total,
+      ratio
+    });
+  }
+  candidates.sort((a, b) => b.ratio - a.ratio);
+  return candidates.map((c, index) => ({
+    id: c.firstIncompleteLeaf.id,
+    kind: "ticket",
+    title: c.firstIncompleteLeaf.title,
+    category: "near_complete_umbrella",
+    reason: `${c.complete}/${c.total} complete in umbrella ${c.umbrellaId} \u2014 close it out`,
+    score: 600 - Math.min(index, 99)
+  }));
+}
+function generatePhaseMomentum(state) {
+  const outcome = nextTicket(state);
+  if (outcome.kind !== "found") return [];
+  const ticket = outcome.ticket;
+  return [
+    {
+      id: ticket.id,
+      kind: "ticket",
+      title: ticket.title,
+      category: "phase_momentum",
+      reason: `Next in phase order (${ticket.phase ?? "none"})`,
+      score: 500
+    }
+  ];
+}
+function generateQuickWins(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "open" && t.type === "chore" && !state.isBlocked(t)
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "quick_win",
+    reason: "Chore \u2014 quick win",
+    score: 400 - Math.min(index, 99)
+  }));
+}
+function generateOpenIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "medium" || i.severity === "low")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "open_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress` : `${capitalize(issue.severity)} severity issue`,
+    score: 300 - Math.min(index, 99)
+  }));
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function buildPhaseIndex(state) {
+  const index = /* @__PURE__ */ new Map();
+  state.roadmap.phases.forEach((p, i) => index.set(p.id, i));
+  return index;
+}
+function sortByPhaseAndOrder(tickets, phaseIndex) {
+  return [...tickets].sort((a, b) => {
+    const aPhase = (a.phase != null ? phaseIndex.get(a.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    const bPhase = (b.phase != null ? phaseIndex.get(b.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    if (aPhase !== bPhase) return aPhase - bPhase;
+    return a.order - b.order;
+  });
+}
+
+// src/cli/commands/recommend.ts
+function handleRecommend(ctx, count) {
+  const result = recommend(ctx.state, count);
+  return { output: formatRecommendations(result, ctx.format) };
+}
+
 // src/cli/commands/snapshot.ts
-async function handleSnapshot(root, format) {
+async function handleSnapshot(root, format, options) {
   let result;
   await withProjectLock(root, { strict: false }, async (loadResult) => {
     result = await saveSnapshot(root, loadResult);
   });
+  if (!result) {
+    throw new Error("snapshot: withProjectLock completed without setting result");
+  }
+  if (options?.quiet) {
+    return { output: "" };
+  }
   return { output: formatSnapshotResult(result, format) };
 }
 
@@ -2355,8 +3408,14 @@ function registerAllTools(server, pinnedRoot) {
     description: "First non-complete phase with its description"
   }, () => runMcpReadTool(pinnedRoot, handlePhaseCurrent));
   server.registerTool("claudestory_ticket_next", {
-    description: "Highest-priority unblocked ticket with unblock impact and umbrella progress"
-  }, () => runMcpReadTool(pinnedRoot, handleTicketNext));
+    description: "Highest-priority unblocked ticket(s) with unblock impact and umbrella progress",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of candidates to return (default: 1)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleTicketNext(ctx, args.count ?? 1)
+  ));
   server.registerTool("claudestory_ticket_blocked", {
     description: "All blocked tickets with their blocking dependencies"
   }, () => runMcpReadTool(pinnedRoot, handleTicketBlocked));
@@ -2364,8 +3423,14 @@ function registerAllTools(server, pinnedRoot) {
     description: "List handover filenames (newest first)"
   }, () => runMcpReadTool(pinnedRoot, handleHandoverList));
   server.registerTool("claudestory_handover_latest", {
-    description: "Content of the most recent handover document"
-  }, () => runMcpReadTool(pinnedRoot, handleHandoverLatest));
+    description: "Content of the most recent handover document(s)",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of recent handovers to return (default: 1)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleHandoverLatest(ctx, args.count ?? 1)
+  ));
   server.registerTool("claudestory_blocker_list", {
     description: "All roadmap blockers with dates and status"
   }, () => runMcpReadTool(pinnedRoot, handleBlockerList));
@@ -2375,7 +3440,7 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_phase_tickets", {
     description: "Leaf tickets for a specific phase, sorted by order",
     inputSchema: {
-      phaseId: z7.string().describe("Phase ID (e.g. p5b, dogfood)")
+      phaseId: z8.string().describe("Phase ID (e.g. p5b, dogfood)")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === args.phaseId);
@@ -2391,9 +3456,9 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_list", {
     description: "List leaf tickets with optional filters",
     inputSchema: {
-      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")
+      status: z8.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
+      phase: z8.string().optional().describe("Filter by phase ID"),
+      type: z8.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
     }
   }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
     if (args.phase) {
@@ -2414,42 +3479,52 @@ function registerAllTools(server, pinnedRoot) {
   server.registerTool("claudestory_ticket_get", {
     description: "Get a ticket by ID (includes umbrella tickets)",
     inputSchema: {
-      id: z7.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
+      id: z8.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: 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")
+      status: z8.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
+      severity: z8.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low"),
+      component: z8.string().optional().describe("Filter by component name")
     }
   }, (args) => runMcpReadTool(
     pinnedRoot,
-    (ctx) => handleIssueList({ status: args.status, severity: args.severity }, ctx)
+    (ctx) => handleIssueList({ status: args.status, severity: args.severity, component: args.component }, ctx)
   ));
   server.registerTool("claudestory_issue_get", {
     description: "Get an issue by ID",
     inputSchema: {
-      id: z7.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
+      id: z8.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: z7.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
+      filename: z8.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_recommend", {
+    description: "Context-aware ranked work suggestions mixing tickets and issues",
+    inputSchema: {
+      count: z8.number().int().min(1).max(10).optional().describe("Number of recommendations (default: 5)")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleRecommend(ctx, args.count ?? 5)
+  ));
   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")
+      phase: z8.string().optional().describe("Export a single phase by ID"),
+      all: z8.boolean().optional().describe("Export entire project")
     }
   }, (args) => {
     if (!args.phase && !args.all) {
@@ -2471,8 +3546,8 @@ function registerAllTools(server, pinnedRoot) {
   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")
+      content: z8.string().describe("Markdown content of the handover"),
+      slug: z8.string().optional().describe("Slug for filename (e.g. phase5b-wrapup). Default: session")
     }
   }, (args) => {
     if (!args.content?.trim()) {
@@ -2486,12 +3561,183 @@ function registerAllTools(server, pinnedRoot) {
       (root) => handleHandoverCreate(args.content, args.slug ?? "session", "md", root)
     );
   });
+  server.registerTool("claudestory_ticket_create", {
+    description: "Create a new ticket",
+    inputSchema: {
+      title: z8.string().describe("Ticket title"),
+      type: z8.enum(TICKET_TYPES).describe("Ticket type: task, feature, chore"),
+      phase: z8.string().optional().describe("Phase ID"),
+      description: z8.string().optional().describe("Ticket description"),
+      blockedBy: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("IDs of blocking tickets"),
+      parentTicket: z8.string().regex(TICKET_ID_REGEX).optional().describe("Parent ticket ID (makes this a sub-ticket)")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleTicketCreate(
+      {
+        title: args.title,
+        type: args.type,
+        phase: args.phase ?? null,
+        description: args.description ?? "",
+        blockedBy: args.blockedBy ?? [],
+        parentTicket: args.parentTicket ?? null
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_ticket_update", {
+    description: "Update an existing ticket",
+    inputSchema: {
+      id: z8.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001)"),
+      status: z8.enum(TICKET_STATUSES).optional().describe("New status: open, inprogress, complete"),
+      title: z8.string().optional().describe("New title"),
+      order: z8.number().optional().describe("New sort order"),
+      description: z8.string().optional().describe("New description"),
+      phase: z8.string().nullable().optional().describe("New phase ID (null to clear)"),
+      parentTicket: z8.string().regex(TICKET_ID_REGEX).nullable().optional().describe("Parent ticket ID (null to clear)"),
+      blockedBy: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("IDs of blocking tickets")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleTicketUpdate(
+      args.id,
+      {
+        status: args.status,
+        title: args.title,
+        order: args.order,
+        description: args.description,
+        phase: args.phase,
+        parentTicket: args.parentTicket,
+        blockedBy: args.blockedBy
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_issue_create", {
+    description: "Create a new issue",
+    inputSchema: {
+      title: z8.string().describe("Issue title"),
+      severity: z8.enum(ISSUE_SEVERITIES).describe("Issue severity: critical, high, medium, low"),
+      impact: z8.string().describe("Impact description"),
+      components: z8.array(z8.string()).optional().describe("Affected components"),
+      relatedTickets: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("Related ticket IDs"),
+      location: z8.array(z8.string()).optional().describe("File locations"),
+      phase: z8.string().optional().describe("Phase ID")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleIssueCreate(
+      {
+        title: args.title,
+        severity: args.severity,
+        impact: args.impact,
+        components: args.components ?? [],
+        relatedTickets: args.relatedTickets ?? [],
+        location: args.location ?? [],
+        phase: args.phase
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_issue_update", {
+    description: "Update an existing issue",
+    inputSchema: {
+      id: z8.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)"),
+      status: z8.enum(ISSUE_STATUSES).optional().describe("New status: open, inprogress, resolved"),
+      title: z8.string().optional().describe("New title"),
+      severity: z8.enum(ISSUE_SEVERITIES).optional().describe("New severity"),
+      impact: z8.string().optional().describe("New impact description"),
+      resolution: z8.string().nullable().optional().describe("Resolution description (null to clear)"),
+      components: z8.array(z8.string()).optional().describe("Affected components"),
+      relatedTickets: z8.array(z8.string().regex(TICKET_ID_REGEX)).optional().describe("Related ticket IDs"),
+      location: z8.array(z8.string()).optional().describe("File locations")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleIssueUpdate(
+      args.id,
+      {
+        status: args.status,
+        title: args.title,
+        severity: args.severity,
+        impact: args.impact,
+        resolution: args.resolution,
+        components: args.components,
+        relatedTickets: args.relatedTickets,
+        location: args.location
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_note_list", {
+    description: "List notes with optional status/tag filters",
+    inputSchema: {
+      status: z8.enum(NOTE_STATUSES).optional().describe("Filter by status: active, archived"),
+      tag: z8.string().optional().describe("Filter by tag")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleNoteList({ status: args.status, tag: args.tag }, ctx)
+  ));
+  server.registerTool("claudestory_note_get", {
+    description: "Get a note by ID",
+    inputSchema: {
+      id: z8.string().regex(NOTE_ID_REGEX).describe("Note ID (e.g. N-001)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleNoteGet(args.id, ctx)));
+  server.registerTool("claudestory_note_create", {
+    description: "Create a new note",
+    inputSchema: {
+      content: z8.string().describe("Note content"),
+      title: z8.string().optional().describe("Note title"),
+      tags: z8.array(z8.string()).optional().describe("Tags for the note")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleNoteCreate(
+      {
+        content: args.content,
+        title: args.title ?? null,
+        tags: args.tags ?? []
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_note_update", {
+    description: "Update an existing note",
+    inputSchema: {
+      id: z8.string().regex(NOTE_ID_REGEX).describe("Note ID (e.g. N-001)"),
+      content: z8.string().optional().describe("New content"),
+      title: z8.string().nullable().optional().describe("New title (null to clear)"),
+      tags: z8.array(z8.string()).optional().describe("New tags (replaces existing)"),
+      status: z8.enum(NOTE_STATUSES).optional().describe("New status: active, archived")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleNoteUpdate(
+      args.id,
+      {
+        content: args.content,
+        title: args.title,
+        tags: args.tags,
+        clearTags: args.tags !== void 0 && args.tags.length === 0,
+        status: args.status
+      },
+      format,
+      root
+    )
+  ));
 }
 
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.8";
+var version = "0.1.9";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {
@@ -2503,7 +3749,7 @@ function tryDiscoverRoot() {
     const resolved = resolve7(envRoot);
     try {
       const canonical = realpathSync(resolved);
-      if (existsSync5(join8(canonical, CONFIG_PATH2))) {
+      if (existsSync6(join8(canonical, CONFIG_PATH2))) {
         return canonical;
       }
       process.stderr.write(`Warning: No .story/config.json at ${canonical}