@anthropologies/claudestory 0.1.10 → 0.1.11

package/dist/mcp.js

@@ -2,7 +2,8 @@
 
 // src/mcp/index.ts
 import { realpathSync, existsSync as existsSync6 } from "fs";
-import { resolve as resolve7, join as join8, isAbsolute } from "path";
+import { resolve as resolve8, join as join9, isAbsolute } from "path";
+import { z as z9 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
@@ -155,15 +156,9 @@ var IssueSchema = z3.object({
 import { z as z4 } from "zod";
 var NoteSchema = z4.object({
   id: NoteIdSchema,
-  title: z4.preprocess((v) => v ?? null, z4.string().nullable()),
+  title: 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())
-  ),
+  tags: z4.array(z4.string()),
   status: z4.enum(NOTE_STATUSES),
   createdDate: DateSchema,
   updatedDate: DateSchema
@@ -589,6 +584,12 @@ async function writeTicketUnlocked(ticket, root) {
   const json = serializeJSON(parsed);
   await atomicWrite(targetPath, json);
 }
+async function writeTicket(ticket, root) {
+  const wrapDir = resolve2(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeTicketUnlocked(ticket, root);
+  });
+}
 async function writeIssueUnlocked(issue, root) {
   const parsed = IssueSchema.parse(issue);
   if (!ISSUE_ID_REGEX.test(parsed.id)) {
@@ -603,6 +604,104 @@ async function writeIssueUnlocked(issue, root) {
   const json = serializeJSON(parsed);
   await atomicWrite(targetPath, json);
 }
+async function writeIssue(issue, root) {
+  const wrapDir = resolve2(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeIssueUnlocked(issue, root);
+  });
+}
+async function writeRoadmapUnlocked(roadmap, root) {
+  const parsed = RoadmapSchema.parse(roadmap);
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "roadmap.json");
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeRoadmap(roadmap, root) {
+  const wrapDir = resolve2(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeRoadmapUnlocked(roadmap, root);
+  });
+}
+async function writeConfig(config, root) {
+  const parsed = ConfigSchema.parse(config);
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "config.json");
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await withLock(wrapDir, async () => {
+    await atomicWrite(targetPath, json);
+  });
+}
+async function deleteTicket(id, root, options) {
+  if (!TICKET_ID_REGEX.test(id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid ticket ID: ${id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "tickets", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    if (!options?.force) {
+      const { state } = await loadProjectUnlocked(resolve2(root));
+      const blocking = state.ticketsBlocking(id);
+      if (blocking.length > 0) {
+        throw new ProjectLoaderError(
+          "conflict",
+          `Cannot delete ${id}: referenced in blockedBy by ${blocking.join(", ")}`
+        );
+      }
+      const children = state.childrenOf(id);
+      if (children.length > 0) {
+        throw new ProjectLoaderError(
+          "conflict",
+          `Cannot delete ${id}: has child tickets ${children.join(", ")}`
+        );
+      }
+      const refs = state.issuesReferencing(id);
+      if (refs.length > 0) {
+        throw new ProjectLoaderError(
+          "conflict",
+          `Cannot delete ${id}: referenced by issues ${refs.join(", ")}`
+        );
+      }
+    }
+    try {
+      await stat(targetPath);
+    } catch {
+      throw new ProjectLoaderError(
+        "not_found",
+        `Ticket file not found: tickets/${id}.json`
+      );
+    }
+    await unlink(targetPath);
+  });
+}
+async function deleteIssue(id, root) {
+  if (!ISSUE_ID_REGEX.test(id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid issue ID: ${id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "issues", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    try {
+      await stat(targetPath);
+    } catch {
+      throw new ProjectLoaderError(
+        "not_found",
+        `Issue file not found: issues/${id}.json`
+      );
+    }
+    await unlink(targetPath);
+  });
+}
 async function writeNoteUnlocked(note, root) {
   const parsed = NoteSchema.parse(note);
   if (!NOTE_ID_REGEX.test(parsed.id)) {
@@ -618,6 +717,34 @@ async function writeNoteUnlocked(note, root) {
   const json = serializeJSON(parsed);
   await atomicWrite(targetPath, json);
 }
+async function writeNote(note, root) {
+  const wrapDir = resolve2(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeNoteUnlocked(note, root);
+  });
+}
+async function deleteNote(id, root) {
+  if (!NOTE_ID_REGEX.test(id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${id}`
+    );
+  }
+  const wrapDir = resolve2(root, ".story");
+  const targetPath = join3(wrapDir, "notes", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    try {
+      await stat(targetPath);
+    } catch {
+      throw new ProjectLoaderError(
+        "not_found",
+        `Note file not found: notes/${id}.json`
+      );
+    }
+    await unlink(targetPath);
+  });
+}
 async function withProjectLock(root, options, handler) {
   const absRoot = resolve2(root);
   const wrapDir = join3(absRoot, ".story");
@@ -1586,6 +1713,16 @@ function formatRecap(recap, state, format) {
           lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
         }
       }
+      if (changes.handovers && (changes.handovers.added.length > 0 || changes.handovers.removed.length > 0)) {
+        lines.push("");
+        lines.push("## Handovers");
+        for (const h of changes.handovers.added) {
+          lines.push(`- ${h} \u2014 **new**`);
+        }
+        for (const h of changes.handovers.removed) {
+          lines.push(`- ${h} \u2014 removed`);
+        }
+      }
       if (changes.notes && (changes.notes.added.length > 0 || changes.notes.removed.length > 0 || changes.notes.updated.length > 0)) {
         lines.push("");
         lines.push("## Notes");
@@ -1807,7 +1944,35 @@ 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.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;
+  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 || (diff.handovers?.added.length ?? 0) > 0 || (diff.handovers?.removed.length ?? 0) > 0;
+}
+function formatSelftestResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  const lines = ["# Self-test Report", ""];
+  const entities = ["ticket", "issue", "note"];
+  for (const entity of entities) {
+    const checks = result.results.filter((r) => r.entity === entity);
+    if (checks.length === 0) continue;
+    lines.push(`## ${entity.charAt(0).toUpperCase() + entity.slice(1)}`);
+    for (const check of checks) {
+      const mark = check.passed ? "[x]" : "[ ]";
+      const suffix = check.passed ? "" : ` \u2014 ${check.detail}`;
+      lines.push(`- ${mark} ${check.step}${suffix}`);
+    }
+    lines.push("");
+  }
+  if (result.cleanupErrors.length > 0) {
+    lines.push("## Cleanup Warnings");
+    lines.push("");
+    for (const err of result.cleanupErrors) {
+      lines.push(`- ${err}`);
+    }
+    lines.push("");
+  }
+  lines.push(`Result: ${result.passed}/${result.total} passed`);
+  return lines.join("\n");
 }
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
@@ -2446,6 +2611,12 @@ async function handleTicketUpdate(id, updates, format, root) {
       `Unknown ticket status "${updates.status}": must be one of ${TICKET_STATUSES.join(", ")}`
     );
   }
+  if (updates.type !== void 0 && !TICKET_TYPES.includes(updates.type)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown ticket type "${updates.type}": must be one of ${TICKET_TYPES.join(", ")}`
+    );
+  }
   let updatedTicket;
   await withProjectLock(root, { strict: true }, async ({ state }) => {
     const existing = state.ticketByID(id);
@@ -2461,21 +2632,26 @@ async function handleTicketUpdate(id, updates, format, root) {
     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;
+    const statusChanges = {};
     if (updates.status !== void 0 && updates.status !== existing.status) {
-      ticket.status = updates.status;
+      statusChanges.status = updates.status;
       if (updates.status === "complete" && existing.status !== "complete") {
-        ticket.completedDate = todayISO();
+        statusChanges.completedDate = todayISO();
       } else if (updates.status !== "complete" && existing.status === "complete") {
-        ticket.completedDate = null;
+        statusChanges.completedDate = null;
       }
     }
+    const ticket = {
+      ...existing,
+      ...updates.title !== void 0 && { title: updates.title },
+      ...updates.type !== void 0 && { type: updates.type },
+      ...updates.description !== void 0 && { description: updates.description },
+      ...updates.phase !== void 0 && { phase: updates.phase },
+      ...updates.order !== void 0 && { order: updates.order },
+      ...updates.blockedBy !== void 0 && { blockedBy: updates.blockedBy },
+      ...updates.parentTicket !== void 0 && { parentTicket: updates.parentTicket },
+      ...statusChanges
+    };
     validatePostWriteState(ticket, state, false);
     await writeTicketUnlocked(ticket, root);
     updatedTicket = ticket;
@@ -2564,6 +2740,9 @@ async function handleIssueCreate(args, format, root) {
   }
   let createdIssue;
   await withProjectLock(root, { strict: true }, async ({ state }) => {
+    if (args.phase && !state.roadmap.phases.some((p) => p.id === args.phase)) {
+      throw new CliValidationError("invalid_input", `Phase "${args.phase}" not found in roadmap`);
+    }
     if (args.relatedTickets.length > 0) {
       validateRelatedTickets(args.relatedTickets, state);
     }
@@ -2611,25 +2790,36 @@ async function handleIssueUpdate(id, updates, format, root) {
     if (!existing) {
       throw new CliValidationError("not_found", `Issue ${id} not found`);
     }
+    if (updates.phase !== void 0 && updates.phase !== null) {
+      if (!state.roadmap.phases.some((p) => p.id === updates.phase)) {
+        throw new CliValidationError("invalid_input", `Phase "${updates.phase}" not found in roadmap`);
+      }
+    }
     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;
+    const statusChanges = {};
     if (updates.status !== void 0 && updates.status !== existing.status) {
-      issue.status = updates.status;
+      statusChanges.status = updates.status;
       if (updates.status === "resolved" && existing.status !== "resolved") {
-        issue.resolvedDate = todayISO();
+        statusChanges.resolvedDate = todayISO();
       } else if (updates.status !== "resolved" && existing.status === "resolved") {
-        issue.resolvedDate = null;
+        statusChanges.resolvedDate = null;
       }
     }
+    const issue = {
+      ...existing,
+      ...updates.title !== void 0 && { title: updates.title },
+      ...updates.severity !== void 0 && { severity: updates.severity },
+      ...updates.impact !== void 0 && { impact: updates.impact },
+      ...updates.resolution !== void 0 && { resolution: updates.resolution },
+      ...updates.components !== void 0 && { components: updates.components },
+      ...updates.relatedTickets !== void 0 && { relatedTickets: updates.relatedTickets },
+      ...updates.location !== void 0 && { location: updates.location },
+      ...updates.order !== void 0 && { order: updates.order },
+      ...updates.phase !== void 0 && { phase: updates.phase },
+      ...statusChanges
+    };
     validatePostWriteIssueState(issue, state, false);
     await writeIssueUnlocked(issue, root);
     updatedIssue = issue;
@@ -2660,6 +2850,7 @@ var SnapshotV1Schema = z7.object({
   tickets: z7.array(TicketSchema),
   issues: z7.array(IssueSchema),
   notes: z7.array(NoteSchema).optional().default([]),
+  handoverFilenames: z7.array(z7.string()).optional().default([]),
   warnings: z7.array(LoadWarningSchema).optional()
 });
 var MAX_SNAPSHOTS = 20;
@@ -2679,6 +2870,7 @@ async function saveSnapshot(root, loadResult) {
     tickets: [...state.tickets],
     issues: [...state.issues],
     notes: [...state.notes],
+    handoverFilenames: [...state.handoverFilenames],
     ...warnings.length > 0 ? {
       warnings: warnings.map((w) => ({
         type: w.type,
@@ -2831,12 +3023,23 @@ function diffStates(snapshotState, currentState) {
       notesRemoved.push({ id, title: snap.title });
     }
   }
+  const snapHandovers = new Set(snapshotState.handoverFilenames);
+  const curHandovers = new Set(currentState.handoverFilenames);
+  const handoversAdded = [];
+  const handoversRemoved = [];
+  for (const h of curHandovers) {
+    if (!snapHandovers.has(h)) handoversAdded.push(h);
+  }
+  for (const h of snapHandovers) {
+    if (!curHandovers.has(h)) handoversRemoved.push(h);
+  }
   return {
     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 },
-    notes: { added: notesAdded, removed: notesRemoved, updated: notesUpdated }
+    notes: { added: notesAdded, removed: notesRemoved, updated: notesUpdated },
+    handovers: { added: handoversAdded, removed: handoversRemoved }
   };
 }
 function buildRecap(currentState, snapshotInfo) {
@@ -2864,7 +3067,7 @@ function buildRecap(currentState, snapshotInfo) {
     notes: snapshot.notes ?? [],
     roadmap: snapshot.roadmap,
     config: snapshot.config,
-    handoverFilenames: []
+    handoverFilenames: snapshot.handoverFilenames ?? []
   });
   const changes = diffStates(snapshotState, currentState);
   const recentlyClearedBlockers = changes.blockers.cleared;
@@ -2996,23 +3199,22 @@ async function handleNoteUpdate(id, updates, format, root) {
     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;
-    }
+    const tagsUpdate = {};
     if (updates.clearTags) {
-      note.tags = [];
+      tagsUpdate.tags = [];
     } else if (updates.tags !== void 0) {
-      note.tags = normalizeTags(updates.tags);
-    }
-    if (updates.status !== void 0) {
-      note.status = updates.status;
+      tagsUpdate.tags = normalizeTags(updates.tags);
     }
-    note.updatedDate = todayISO();
+    const note = {
+      ...existing,
+      ...updates.content !== void 0 && { content: updates.content },
+      ...updates.title !== void 0 && {
+        title: !updates.title?.trim() ? null : updates.title
+      },
+      ...tagsUpdate,
+      ...updates.status !== void 0 && { status: updates.status },
+      updatedDate: todayISO()
+    };
     await writeNoteUnlocked(note, root);
     updatedNote = note;
   });
@@ -3286,8 +3488,258 @@ function handleExport(ctx, mode, phaseId) {
   return { output: formatExport(ctx.state, mode, phaseId, ctx.format) };
 }
 
+// src/cli/commands/selftest.ts
+async function handleSelftest(root, format, failAfter) {
+  const results = [];
+  const createdIds = [];
+  const cleanupErrors = [];
+  function record(entity, step, passed2, detail) {
+    results.push({ entity, step, passed: passed2, detail });
+    if (failAfter !== void 0 && results.filter((r) => r.passed).length >= failAfter) {
+      throw new Error(`failAfter(${failAfter}): induced failure for testing`);
+    }
+  }
+  try {
+    let ticketId;
+    try {
+      const { state } = await loadProject(root);
+      ticketId = nextTicketID(state.tickets);
+      const today = todayISO();
+      const ticket = {
+        id: ticketId,
+        title: "selftest ticket",
+        type: "chore",
+        status: "open",
+        phase: null,
+        order: 0,
+        description: "Integration smoke test \u2014 will be deleted.",
+        createdDate: today,
+        completedDate: null,
+        blockedBy: [],
+        parentTicket: null
+      };
+      await writeTicket(ticket, root);
+      createdIds.push({ type: "ticket", id: ticketId });
+      record("ticket", "create", true, `Created ${ticketId}`);
+    } catch (err) {
+      record("ticket", "create", false, errMsg(err));
+    }
+    if (ticketId) {
+      try {
+        const { state } = await loadProject(root);
+        const found = state.ticketByID(ticketId);
+        if (!found) throw new Error(`${ticketId} not found after create`);
+        record("ticket", "get", true, `Found ${ticketId}`);
+      } catch (err) {
+        record("ticket", "get", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const existing = state.ticketByID(ticketId);
+        if (!existing) throw new Error(`${ticketId} not found for update`);
+        const updated = { ...existing, status: "inprogress" };
+        await writeTicket(updated, root);
+        record("ticket", "update", true, `Updated ${ticketId} status \u2192 inprogress`);
+      } catch (err) {
+        record("ticket", "update", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.ticketByID(ticketId);
+        if (!found) throw new Error(`${ticketId} not found for verify`);
+        if (found.status !== "inprogress") throw new Error(`Expected inprogress, got ${found.status}`);
+        record("ticket", "verify update", true, `Verified ${ticketId} status = inprogress`);
+      } catch (err) {
+        record("ticket", "verify update", false, errMsg(err));
+      }
+      try {
+        await deleteTicket(ticketId, root, { force: true });
+        createdIds.splice(createdIds.findIndex((c) => c.id === ticketId), 1);
+        record("ticket", "delete", true, `Deleted ${ticketId}`);
+      } catch (err) {
+        record("ticket", "delete", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.ticketByID(ticketId);
+        if (found) throw new Error(`${ticketId} still exists after delete`);
+        record("ticket", "verify delete", true, `Confirmed ${ticketId} absent`);
+      } catch (err) {
+        record("ticket", "verify delete", false, errMsg(err));
+      }
+    }
+    let issueId;
+    try {
+      const { state } = await loadProject(root);
+      issueId = nextIssueID(state.issues);
+      const today = todayISO();
+      const issue = {
+        id: issueId,
+        title: "selftest issue",
+        status: "open",
+        severity: "low",
+        components: [],
+        impact: "Integration smoke test \u2014 will be deleted.",
+        resolution: null,
+        location: [],
+        discoveredDate: today,
+        resolvedDate: null,
+        relatedTickets: [],
+        order: 0,
+        phase: null
+      };
+      await writeIssue(issue, root);
+      createdIds.push({ type: "issue", id: issueId });
+      record("issue", "create", true, `Created ${issueId}`);
+    } catch (err) {
+      record("issue", "create", false, errMsg(err));
+    }
+    if (issueId) {
+      try {
+        const { state } = await loadProject(root);
+        const found = state.issueByID(issueId);
+        if (!found) throw new Error(`${issueId} not found after create`);
+        record("issue", "get", true, `Found ${issueId}`);
+      } catch (err) {
+        record("issue", "get", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const existing = state.issueByID(issueId);
+        if (!existing) throw new Error(`${issueId} not found for update`);
+        const updated = { ...existing, status: "inprogress" };
+        await writeIssue(updated, root);
+        record("issue", "update", true, `Updated ${issueId} status \u2192 inprogress`);
+      } catch (err) {
+        record("issue", "update", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.issueByID(issueId);
+        if (!found) throw new Error(`${issueId} not found for verify`);
+        if (found.status !== "inprogress") throw new Error(`Expected inprogress, got ${found.status}`);
+        record("issue", "verify update", true, `Verified ${issueId} status = inprogress`);
+      } catch (err) {
+        record("issue", "verify update", false, errMsg(err));
+      }
+      try {
+        await deleteIssue(issueId, root);
+        createdIds.splice(createdIds.findIndex((c) => c.id === issueId), 1);
+        record("issue", "delete", true, `Deleted ${issueId}`);
+      } catch (err) {
+        record("issue", "delete", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.issueByID(issueId);
+        if (found) throw new Error(`${issueId} still exists after delete`);
+        record("issue", "verify delete", true, `Confirmed ${issueId} absent`);
+      } catch (err) {
+        record("issue", "verify delete", false, errMsg(err));
+      }
+    }
+    let noteId;
+    try {
+      const { state } = await loadProject(root);
+      noteId = nextNoteID(state.notes);
+      const today = todayISO();
+      const note = {
+        id: noteId,
+        title: "selftest note",
+        content: "Integration smoke test \u2014 will be deleted.",
+        tags: [],
+        status: "active",
+        createdDate: today,
+        updatedDate: today
+      };
+      await writeNote(note, root);
+      createdIds.push({ type: "note", id: noteId });
+      record("note", "create", true, `Created ${noteId}`);
+    } catch (err) {
+      record("note", "create", false, errMsg(err));
+    }
+    if (noteId) {
+      try {
+        const { state } = await loadProject(root);
+        const found = state.noteByID(noteId);
+        if (!found) throw new Error(`${noteId} not found after create`);
+        record("note", "get", true, `Found ${noteId}`);
+      } catch (err) {
+        record("note", "get", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const existing = state.noteByID(noteId);
+        if (!existing) throw new Error(`${noteId} not found for update`);
+        const updated = { ...existing, status: "archived", updatedDate: todayISO() };
+        await writeNote(updated, root);
+        record("note", "update", true, `Updated ${noteId} status \u2192 archived`);
+      } catch (err) {
+        record("note", "update", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.noteByID(noteId);
+        if (!found) throw new Error(`${noteId} not found for verify`);
+        if (found.status !== "archived") throw new Error(`Expected archived, got ${found.status}`);
+        record("note", "verify update", true, `Verified ${noteId} status = archived`);
+      } catch (err) {
+        record("note", "verify update", false, errMsg(err));
+      }
+      try {
+        await deleteNote(noteId, root);
+        createdIds.splice(createdIds.findIndex((c) => c.id === noteId), 1);
+        record("note", "delete", true, `Deleted ${noteId}`);
+      } catch (err) {
+        record("note", "delete", false, errMsg(err));
+      }
+      try {
+        const { state } = await loadProject(root);
+        const found = state.noteByID(noteId);
+        if (found) throw new Error(`${noteId} still exists after delete`);
+        record("note", "verify delete", true, `Confirmed ${noteId} absent`);
+      } catch (err) {
+        record("note", "verify delete", false, errMsg(err));
+      }
+    }
+  } finally {
+    for (const { type, id } of createdIds.reverse()) {
+      try {
+        if (type === "ticket") await deleteTicket(id, root, { force: true });
+        else if (type === "issue") await deleteIssue(id, root);
+        else await deleteNote(id, root);
+      } catch (err) {
+        cleanupErrors.push(`Failed to delete ${type} ${id}: ${errMsg(err)}`);
+      }
+    }
+  }
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+  const result = {
+    passed,
+    failed,
+    total: results.length,
+    results,
+    cleanupErrors
+  };
+  return { output: formatSelftestResult(result, format) };
+}
+function errMsg(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // src/cli/commands/phase.ts
 import { join as join6, resolve as resolve6 } from "path";
+var PHASE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+var PHASE_ID_MAX_LENGTH = 40;
+function validatePhaseId(id) {
+  if (id.length > PHASE_ID_MAX_LENGTH) {
+    throw new CliValidationError("invalid_input", `Phase ID "${id}" exceeds ${PHASE_ID_MAX_LENGTH} characters`);
+  }
+  if (!PHASE_ID_REGEX.test(id)) {
+    throw new CliValidationError("invalid_input", `Phase ID "${id}" must be lowercase alphanumeric with hyphens (e.g. "my-phase")`);
+  }
+}
 function handlePhaseList(ctx) {
   return { output: formatPhaseList(ctx.state, ctx.format) };
 }
@@ -3333,6 +3785,46 @@ function handlePhaseTickets(phaseId, ctx) {
   }
   return { output: formatPhaseTickets(phaseId, ctx.state, ctx.format) };
 }
+async function handlePhaseCreate(args, format, root) {
+  validatePhaseId(args.id);
+  if (args.atStart && args.after) {
+    throw new CliValidationError("invalid_input", "Cannot use both --after and --at-start");
+  }
+  if (!args.atStart && !args.after) {
+    throw new CliValidationError("invalid_input", "Must specify either --after <phase-id> or --at-start");
+  }
+  let createdPhase;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    if (state.roadmap.phases.some((p) => p.id === args.id)) {
+      throw new CliValidationError("conflict", `Phase "${args.id}" already exists`);
+    }
+    const phase = {
+      id: args.id,
+      label: args.label,
+      name: args.name,
+      description: args.description,
+      ...args.summary !== void 0 && { summary: args.summary }
+    };
+    const newPhases = [...state.roadmap.phases];
+    if (args.atStart) {
+      newPhases.unshift(phase);
+    } else {
+      const afterIdx = newPhases.findIndex((p) => p.id === args.after);
+      if (afterIdx < 0) {
+        throw new CliValidationError("not_found", `Phase "${args.after}" not found`);
+      }
+      newPhases.splice(afterIdx + 1, 0, phase);
+    }
+    const newRoadmap = { ...state.roadmap, phases: newPhases };
+    await writeRoadmapUnlocked(newRoadmap, root);
+    createdPhase = phase;
+  });
+  if (!createdPhase) throw new Error("Phase not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdPhase), null, 2) };
+  }
+  return { output: `Created phase ${createdPhase.id}: ${createdPhase.name}` };
+}
 
 // src/mcp/tools.ts
 var INFRASTRUCTURE_ERROR_CODES = [
@@ -3592,7 +4084,8 @@ function registerAllTools(server, pinnedRoot) {
       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"),
+      type: z8.enum(TICKET_TYPES).optional().describe("New type: task, feature, chore"),
+      order: z8.number().int().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)"),
@@ -3605,6 +4098,7 @@ function registerAllTools(server, pinnedRoot) {
       {
         status: args.status,
         title: args.title,
+        type: args.type,
         order: args.order,
         description: args.description,
         phase: args.phase,
@@ -3653,7 +4147,9 @@ function registerAllTools(server, pinnedRoot) {
       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")
+      location: z8.array(z8.string()).optional().describe("File locations"),
+      order: z8.number().int().optional().describe("New sort order"),
+      phase: z8.string().nullable().optional().describe("New phase ID (null to clear)")
     }
   }, (args) => runMcpWriteTool(
     pinnedRoot,
@@ -3667,7 +4163,9 @@ function registerAllTools(server, pinnedRoot) {
         resolution: args.resolution,
         components: args.components,
         relatedTickets: args.relatedTickets,
-        location: args.location
+        location: args.location,
+        order: args.order,
+        phase: args.phase
       },
       format,
       root
@@ -3732,6 +4230,125 @@ function registerAllTools(server, pinnedRoot) {
       root
     )
   ));
+  server.registerTool("claudestory_phase_create", {
+    description: "Create a new phase in the roadmap. Exactly one of after or atStart is required for positioning.",
+    inputSchema: {
+      id: z8.string().describe("Phase ID \u2014 lowercase alphanumeric with hyphens (e.g. 'my-phase')"),
+      name: z8.string().describe("Phase display name"),
+      label: z8.string().describe("Phase label (e.g. 'PHASE 1')"),
+      description: z8.string().describe("Phase description"),
+      summary: z8.string().optional().describe("One-line summary for compact display"),
+      after: z8.string().optional().describe("Insert after this phase ID"),
+      atStart: z8.boolean().optional().describe("Insert at beginning of roadmap")
+    }
+  }, (args) => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handlePhaseCreate(
+      {
+        id: args.id,
+        name: args.name,
+        label: args.label,
+        description: args.description,
+        summary: args.summary,
+        after: args.after,
+        atStart: args.atStart ?? false
+      },
+      format,
+      root
+    )
+  ));
+  server.registerTool("claudestory_selftest", {
+    description: "Integration smoke test \u2014 creates, updates, and deletes test entities to verify the full pipeline"
+  }, () => runMcpWriteTool(
+    pinnedRoot,
+    (root, format) => handleSelftest(root, format)
+  ));
+}
+
+// src/core/init.ts
+import { mkdir as mkdir4, stat as stat2 } from "fs/promises";
+import { join as join8, resolve as resolve7 } from "path";
+async function initProject(root, options) {
+  const absRoot = resolve7(root);
+  const wrapDir = join8(absRoot, ".story");
+  let exists = false;
+  try {
+    const s = await stat2(wrapDir);
+    if (s.isDirectory()) exists = true;
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw new ProjectLoaderError(
+        "io_error",
+        `Cannot check .story/ directory: ${err.message}`,
+        err
+      );
+    }
+  }
+  if (exists && !options.force) {
+    throw new ProjectLoaderError(
+      "conflict",
+      ".story/ already exists. Use --force to overwrite config and roadmap."
+    );
+  }
+  await mkdir4(join8(wrapDir, "tickets"), { recursive: true });
+  await mkdir4(join8(wrapDir, "issues"), { recursive: true });
+  await mkdir4(join8(wrapDir, "handovers"), { recursive: true });
+  await mkdir4(join8(wrapDir, "notes"), { recursive: true });
+  const created = [
+    ".story/config.json",
+    ".story/roadmap.json",
+    ".story/tickets/",
+    ".story/issues/",
+    ".story/handovers/",
+    ".story/notes/"
+  ];
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const config = {
+    version: 2,
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    project: options.name,
+    type: options.type ?? "generic",
+    language: options.language ?? "unknown",
+    features: {
+      tickets: true,
+      issues: true,
+      handovers: true,
+      roadmap: true,
+      reviews: true
+    }
+  };
+  const roadmap = {
+    title: options.name,
+    date: today,
+    phases: options.phases ?? [
+      {
+        id: "p0",
+        label: "PHASE 0",
+        name: "Setup",
+        description: "Initial project setup."
+      }
+    ],
+    blockers: []
+  };
+  await writeConfig(config, absRoot);
+  await writeRoadmap(roadmap, absRoot);
+  const warnings = [];
+  if (options.force && exists) {
+    try {
+      const { warnings: loadWarnings } = await loadProject(absRoot);
+      for (const w of loadWarnings) {
+        if (INTEGRITY_WARNING_TYPES.includes(w.type)) {
+          warnings.push(`${w.file}: ${w.message}`);
+        }
+      }
+    } catch {
+    }
+  }
+  return {
+    root: absRoot,
+    created,
+    warnings
+  };
 }
 
 // src/mcp/index.ts
@@ -3746,10 +4363,10 @@ function tryDiscoverRoot() {
 `);
       return null;
     }
-    const resolved = resolve7(envRoot);
+    const resolved = resolve8(envRoot);
     try {
       const canonical = realpathSync(resolved);
-      if (existsSync6(join8(canonical, CONFIG_PATH2))) {
+      if (existsSync6(join9(canonical, CONFIG_PATH2))) {
         return canonical;
       }
       process.stderr.write(`Warning: No .story/config.json at ${canonical}
@@ -3767,12 +4384,68 @@ function tryDiscoverRoot() {
     return null;
   }
 }
+function registerDegradedTools(server) {
+  const degradedStatus = server.registerTool("claudestory_status", {
+    description: "Project summary \u2014 returns guidance if no .story/ project found"
+  }, () => Promise.resolve({
+    content: [{ type: "text", text: "No .story/ project found. Use claudestory_init to create one, or navigate to a directory with .story/." }],
+    isError: true
+  }));
+  const degradedInit = server.registerTool("claudestory_init", {
+    description: "Initialize a new .story/ project in the current directory",
+    inputSchema: {
+      name: z9.string().describe("Project name"),
+      type: z9.string().optional().describe("Project type (e.g. npm, macapp, cargo, generic)"),
+      language: z9.string().optional().describe("Primary language (e.g. typescript, swift, rust)")
+    }
+  }, async (args) => {
+    let result;
+    try {
+      const projectRoot = realpathSync(process.cwd());
+      result = await initProject(projectRoot, {
+        name: args.name,
+        type: args.type,
+        language: args.language,
+        phases: []
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return { content: [{ type: "text", text: `[init_error] ${msg}` }], isError: true };
+    }
+    try {
+      degradedStatus.remove();
+      degradedInit.remove();
+      registerAllTools(server, result.root);
+    } catch (swapErr) {
+      process.stderr.write(`claudestory: tool-swap failed after init: ${swapErr instanceof Error ? swapErr.message : String(swapErr)}
+`);
+      try {
+        registerDegradedTools(server);
+      } catch {
+      }
+      return { content: [{ type: "text", text: `Initialized .story/ project "${args.name}" at ${result.root}
+
+Warning: tool registration failed. Restart the MCP server for full tool access.` }] };
+    }
+    process.stderr.write(`claudestory: initialized at ${result.root}
+`);
+    const lines = [
+      `Initialized .story/ project "${args.name}" at ${result.root}`,
+      `Created: ${result.created.join(", ")}`
+    ];
+    if (result.warnings.length > 0) {
+      lines.push(`Warnings: ${result.warnings.join("; ")}`);
+    }
+    lines.push("", "All claudestory tools are now available. Use claudestory_phase_create to add phases and claudestory_ticket_create to add tickets.");
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  });
+}
 async function main() {
   const root = tryDiscoverRoot();
   const server = new McpServer(
     { name: "claudestory", version },
     {
-      instructions: root ? "Start with claudestory_status for a project overview, then claudestory_ticket_next for the highest-priority work, then claudestory_handover_latest for session context." : "No .story/ project found in the current directory. Navigate to a project with a .story/ directory, or set CLAUDESTORY_PROJECT_ROOT."
+      instructions: root ? "Start with claudestory_status for a project overview, then claudestory_ticket_next for the highest-priority work, then claudestory_handover_latest for session context." : "No .story/ project found. Use claudestory_init to initialize a new project, or navigate to a directory with .story/."
     }
   );
   if (root) {
@@ -3780,13 +4453,8 @@ async function main() {
     process.stderr.write(`claudestory MCP server running (root: ${root})
 `);
   } else {
-    server.registerTool("claudestory_status", {
-      description: "Project summary \u2014 returns error if no .story/ project found"
-    }, () => Promise.resolve({
-      content: [{ type: "text", text: "No .story/ project found. Navigate to a directory containing .story/ or set CLAUDESTORY_PROJECT_ROOT." }],
-      isError: true
-    }));
-    process.stderr.write("claudestory MCP server running (no project found \u2014 tools will report errors)\n");
+    registerDegradedTools(server);
+    process.stderr.write("claudestory MCP server running (no project \u2014 claudestory_init available)\n");
   }
   const transport = new StdioServerTransport();
   await server.connect(transport);