@anthropologies/claudestory 0.1.0

package/dist/mcp.js

@@ -0,0 +1,1755 @@
+#!/usr/bin/env node
+
+// src/mcp/index.ts
+import { realpathSync, existsSync as existsSync4 } from "fs";
+import { resolve as resolve5, join as join6, isAbsolute } from "path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/core/project-root-discovery.ts
+import { existsSync } from "fs";
+import { resolve, dirname, join } from "path";
+var ENV_VAR = "CLAUDESTORY_PROJECT_ROOT";
+var CONFIG_PATH = ".story/config.json";
+function discoverProjectRoot(startDir) {
+  const envRoot = process.env[ENV_VAR];
+  if (envRoot) {
+    const resolved = resolve(envRoot);
+    if (existsSync(join(resolved, CONFIG_PATH))) {
+      return resolved;
+    }
+    return null;
+  }
+  let current = resolve(startDir ?? process.cwd());
+  for (; ; ) {
+    if (existsSync(join(current, CONFIG_PATH))) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+// src/mcp/tools.ts
+import { z as z6 } from "zod";
+import { join as join5 } from "path";
+
+// src/core/project-loader.ts
+import {
+  readdir as readdir2,
+  readFile as readFile2,
+  writeFile,
+  rename,
+  unlink,
+  stat,
+  realpath,
+  lstat,
+  open
+} 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";
+import lockfile from "proper-lockfile";
+
+// src/models/ticket.ts
+import { z as z2 } from "zod";
+
+// src/models/types.ts
+import { z } from "zod";
+var TICKET_ID_REGEX = /^T-\d+[a-z]?$/;
+var ISSUE_ID_REGEX = /^ISS-\d+$/;
+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 DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+var DateSchema = z.string().regex(DATE_REGEX, "Date must be YYYY-MM-DD").refine(
+  (val) => {
+    const d = /* @__PURE__ */ new Date(val + "T00:00:00Z");
+    return !isNaN(d.getTime()) && d.toISOString().startsWith(val);
+  },
+  { message: "Invalid calendar date" }
+);
+var TicketIdSchema = z.string().regex(TICKET_ID_REGEX, "Ticket ID must match T-NNN or T-NNNx");
+var IssueIdSchema = z.string().regex(ISSUE_ID_REGEX, "Issue ID must match ISS-NNN");
+
+// src/models/ticket.ts
+var TicketSchema = z2.object({
+  id: TicketIdSchema,
+  title: z2.string().min(1),
+  description: z2.string(),
+  type: z2.enum(TICKET_TYPES),
+  status: z2.enum(TICKET_STATUSES),
+  phase: z2.string().nullable(),
+  order: z2.number().int(),
+  createdDate: DateSchema,
+  completedDate: DateSchema.nullable(),
+  blockedBy: z2.array(TicketIdSchema),
+  parentTicket: TicketIdSchema.nullable().optional(),
+  // Attribution fields — unused in v1, baked in to avoid future migration
+  createdBy: z2.string().nullable().optional(),
+  assignedTo: z2.string().nullable().optional(),
+  lastModifiedBy: z2.string().nullable().optional()
+}).passthrough();
+
+// src/models/issue.ts
+import { z as z3 } from "zod";
+var IssueSchema = z3.object({
+  id: IssueIdSchema,
+  title: z3.string().min(1),
+  status: z3.enum(ISSUE_STATUSES),
+  severity: z3.enum(ISSUE_SEVERITIES),
+  components: z3.array(z3.string()),
+  impact: z3.string(),
+  resolution: z3.string().nullable(),
+  location: z3.array(z3.string()),
+  discoveredDate: DateSchema,
+  resolvedDate: DateSchema.nullable(),
+  relatedTickets: z3.array(TicketIdSchema),
+  // Optional fields — older issues may omit these
+  order: z3.number().int().optional(),
+  phase: z3.string().nullable().optional(),
+  // Attribution fields — unused in v1
+  createdBy: z3.string().nullable().optional(),
+  assignedTo: z3.string().nullable().optional(),
+  lastModifiedBy: z3.string().nullable().optional()
+}).passthrough();
+
+// src/models/roadmap.ts
+import { z as z4 } from "zod";
+var BlockerSchema = z4.object({
+  name: z4.string().min(1),
+  // Legacy format (pre-T-082)
+  cleared: z4.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()
+}).passthrough();
+var PhaseSchema = z4.object({
+  id: z4.string().min(1),
+  label: z4.string(),
+  name: z4.string(),
+  description: z4.string(),
+  summary: z4.string().optional()
+}).passthrough();
+var RoadmapSchema = z4.object({
+  title: z4.string(),
+  date: DateSchema,
+  phases: z4.array(PhaseSchema),
+  blockers: z4.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()
+}).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(),
+  features: FeaturesSchema
+}).passthrough();
+
+// src/core/project-state.ts
+var ProjectState = class _ProjectState {
+  // --- Public raw inputs (readonly) ---
+  tickets;
+  issues;
+  roadmap;
+  config;
+  handoverFilenames;
+  // --- Derived (public readonly) ---
+  umbrellaIDs;
+  leafTickets;
+  // --- Derived (private) ---
+  leafTicketsByPhase;
+  childrenByParent;
+  reverseBlocksMap;
+  ticketsByID;
+  issuesByID;
+  // --- Counts ---
+  totalTicketCount;
+  openTicketCount;
+  completeTicketCount;
+  openIssueCount;
+  issuesBySeverity;
+  constructor(input) {
+    this.tickets = input.tickets;
+    this.issues = input.issues;
+    this.roadmap = input.roadmap;
+    this.config = input.config;
+    this.handoverFilenames = input.handoverFilenames;
+    const parentIDs = /* @__PURE__ */ new Set();
+    for (const t of input.tickets) {
+      if (t.parentTicket != null) {
+        parentIDs.add(t.parentTicket);
+      }
+    }
+    this.umbrellaIDs = parentIDs;
+    this.leafTickets = input.tickets.filter((t) => !parentIDs.has(t.id));
+    const byPhase = /* @__PURE__ */ new Map();
+    for (const t of this.leafTickets) {
+      const phase = t.phase;
+      const arr = byPhase.get(phase);
+      if (arr) {
+        arr.push(t);
+      } else {
+        byPhase.set(phase, [t]);
+      }
+    }
+    for (const [, arr] of byPhase) {
+      arr.sort((a, b) => a.order - b.order);
+    }
+    this.leafTicketsByPhase = byPhase;
+    const children = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      if (t.parentTicket != null) {
+        const arr = children.get(t.parentTicket);
+        if (arr) {
+          arr.push(t);
+        } else {
+          children.set(t.parentTicket, [t]);
+        }
+      }
+    }
+    this.childrenByParent = children;
+    const reverseBlocks = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      for (const blockerID of t.blockedBy) {
+        const arr = reverseBlocks.get(blockerID);
+        if (arr) {
+          arr.push(t);
+        } else {
+          reverseBlocks.set(blockerID, [t]);
+        }
+      }
+    }
+    this.reverseBlocksMap = reverseBlocks;
+    const tByID = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      if (!tByID.has(t.id)) {
+        tByID.set(t.id, t);
+      }
+    }
+    this.ticketsByID = tByID;
+    const iByID = /* @__PURE__ */ new Map();
+    for (const i of input.issues) {
+      iByID.set(i.id, i);
+    }
+    this.issuesByID = iByID;
+    this.totalTicketCount = input.tickets.length;
+    this.openTicketCount = input.tickets.filter(
+      (t) => t.status !== "complete"
+    ).length;
+    this.completeTicketCount = input.tickets.filter(
+      (t) => t.status === "complete"
+    ).length;
+    this.openIssueCount = input.issues.filter(
+      (i) => i.status === "open"
+    ).length;
+    const bySev = /* @__PURE__ */ new Map();
+    for (const i of input.issues) {
+      if (i.status === "open") {
+        bySev.set(i.severity, (bySev.get(i.severity) ?? 0) + 1);
+      }
+    }
+    this.issuesBySeverity = bySev;
+  }
+  // --- Query Methods ---
+  isUmbrella(ticket) {
+    return this.umbrellaIDs.has(ticket.id);
+  }
+  phaseTickets(phaseId) {
+    return this.leafTicketsByPhase.get(phaseId) ?? [];
+  }
+  /** Phase status derived from leaf tickets only. Umbrella stored status is ignored. */
+  phaseStatus(phaseId) {
+    const leaves = this.phaseTickets(phaseId);
+    return _ProjectState.aggregateStatus(leaves);
+  }
+  umbrellaChildren(ticketId) {
+    return this.childrenByParent.get(ticketId) ?? [];
+  }
+  /** Umbrella status derived from descendant leaf tickets (recursive traversal). */
+  umbrellaStatus(ticketId) {
+    const visited = /* @__PURE__ */ new Set();
+    const leaves = this.descendantLeaves(ticketId, visited);
+    return _ProjectState.aggregateStatus(leaves);
+  }
+  reverseBlocks(ticketId) {
+    return this.reverseBlocksMap.get(ticketId) ?? [];
+  }
+  /**
+   * A ticket is blocked if any blockedBy reference points to a non-complete ticket.
+   * Unknown blocker IDs treated as blocked (conservative — unknown dependency = assume not cleared).
+   */
+  isBlocked(ticket) {
+    if (ticket.blockedBy.length === 0) return false;
+    return ticket.blockedBy.some((blockerID) => {
+      const blocker = this.ticketsByID.get(blockerID);
+      if (!blocker) return true;
+      return blocker.status !== "complete";
+    });
+  }
+  get blockedCount() {
+    return this.tickets.filter((t) => this.isBlocked(t)).length;
+  }
+  ticketByID(id) {
+    return this.ticketsByID.get(id);
+  }
+  issueByID(id) {
+    return this.issuesByID.get(id);
+  }
+  // --- Deletion Safety ---
+  /** IDs of tickets that list `ticketId` in their blockedBy. */
+  ticketsBlocking(ticketId) {
+    return (this.reverseBlocksMap.get(ticketId) ?? []).map((t) => t.id);
+  }
+  /** IDs of tickets that have `ticketId` as their parentTicket. */
+  childrenOf(ticketId) {
+    return (this.childrenByParent.get(ticketId) ?? []).map((t) => t.id);
+  }
+  /** IDs of issues that reference `ticketId` in relatedTickets. */
+  issuesReferencing(ticketId) {
+    return this.issues.filter((i) => i.relatedTickets.includes(ticketId)).map((i) => i.id);
+  }
+  // --- Private ---
+  /**
+   * Recursively collects all descendant leaf tickets of an umbrella.
+   * Uses a visited set to guard against cycles in malformed data.
+   */
+  descendantLeaves(ticketId, visited) {
+    if (visited.has(ticketId)) return [];
+    visited.add(ticketId);
+    const directChildren = this.childrenByParent.get(ticketId) ?? [];
+    const leaves = [];
+    for (const child of directChildren) {
+      if (this.umbrellaIDs.has(child.id)) {
+        leaves.push(...this.descendantLeaves(child.id, visited));
+      } else {
+        leaves.push(child);
+      }
+    }
+    return leaves;
+  }
+  /**
+   * Shared aggregation logic for phase and umbrella status.
+   * - all complete → complete
+   * - any inprogress OR any complete (but not all) → inprogress
+   * - else → notstarted (nothing started)
+   */
+  static aggregateStatus(tickets) {
+    if (tickets.length === 0) return "notstarted";
+    const allComplete = tickets.every((t) => t.status === "complete");
+    if (allComplete) return "complete";
+    const anyProgress = tickets.some((t) => t.status === "inprogress");
+    const anyComplete = tickets.some((t) => t.status === "complete");
+    if (anyProgress || anyComplete) return "inprogress";
+    return "notstarted";
+  }
+};
+
+// src/core/errors.ts
+var CURRENT_SCHEMA_VERSION = 1;
+var ProjectLoaderError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+  name = "ProjectLoaderError";
+};
+var INTEGRITY_WARNING_TYPES = [
+  "parse_error",
+  "schema_error",
+  "duplicate_id"
+];
+
+// src/core/handover-parser.ts
+import { readdir, readFile } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join as join2, relative, extname } from "path";
+var HANDOVER_DATE_REGEX = /^\d{4}-\d{2}-\d{2}/;
+async function listHandovers(handoversDir, root, warnings) {
+  if (!existsSync2(handoversDir)) return [];
+  let entries;
+  try {
+    entries = await readdir(handoversDir);
+  } catch (err) {
+    warnings.push({
+      file: relative(root, handoversDir),
+      message: `Cannot enumerate handovers: ${err instanceof Error ? err.message : String(err)}`,
+      type: "parse_error"
+    });
+    return [];
+  }
+  const conforming = [];
+  const nonConforming = [];
+  for (const entry of entries.sort()) {
+    if (entry.startsWith(".")) continue;
+    if (extname(entry) !== ".md") continue;
+    if (HANDOVER_DATE_REGEX.test(entry)) {
+      conforming.push(entry);
+    } else {
+      nonConforming.push(entry);
+      warnings.push({
+        file: relative(root, join2(handoversDir, entry)),
+        message: "Handover filename does not start with YYYY-MM-DD date prefix.",
+        type: "naming_convention"
+      });
+    }
+  }
+  conforming.sort((a, b) => b.localeCompare(a));
+  return [...conforming, ...nonConforming];
+}
+async function readHandover(handoversDir, filename) {
+  return readFile(join2(handoversDir, filename), "utf-8");
+}
+
+// src/core/project-loader.ts
+async function loadProject(root, options) {
+  const absRoot = resolve2(root);
+  const wrapDir = join3(absRoot, ".story");
+  try {
+    const wrapStat = await stat(wrapDir);
+    if (!wrapStat.isDirectory()) {
+      throw new ProjectLoaderError(
+        "not_found",
+        "Missing .story/ directory."
+      );
+    }
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) throw err;
+    throw new ProjectLoaderError(
+      "not_found",
+      "Missing .story/ directory."
+    );
+  }
+  if (existsSync3(join3(wrapDir, ".txn.json"))) {
+    await withLock(wrapDir, () => doRecoverTransaction(wrapDir));
+  }
+  const config = await loadSingletonFile(
+    "config.json",
+    wrapDir,
+    absRoot,
+    ConfigSchema
+  );
+  const maxVersion = options?.maxSchemaVersion ?? CURRENT_SCHEMA_VERSION;
+  if (config.schemaVersion !== void 0 && config.schemaVersion > maxVersion) {
+    throw new ProjectLoaderError(
+      "version_mismatch",
+      `Config schemaVersion ${config.schemaVersion} exceeds max supported ${maxVersion}.`
+    );
+  }
+  const roadmap = await loadSingletonFile(
+    "roadmap.json",
+    wrapDir,
+    absRoot,
+    RoadmapSchema
+  );
+  const warnings = [];
+  const tickets = await loadDirectory(
+    join3(wrapDir, "tickets"),
+    absRoot,
+    TicketSchema,
+    warnings
+  );
+  const issues = await loadDirectory(
+    join3(wrapDir, "issues"),
+    absRoot,
+    IssueSchema,
+    warnings
+  );
+  const handoversDir = join3(wrapDir, "handovers");
+  const handoverFilenames = await listHandovers(
+    handoversDir,
+    absRoot,
+    warnings
+  );
+  if (options?.strict) {
+    const integrityWarning = warnings.find(
+      (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+    );
+    if (integrityWarning) {
+      throw new ProjectLoaderError(
+        "project_corrupt",
+        `Strict mode: ${integrityWarning.file}: ${integrityWarning.message}`
+      );
+    }
+  }
+  const state = new ProjectState({
+    tickets,
+    issues,
+    roadmap,
+    config,
+    handoverFilenames
+  });
+  return { state, warnings };
+}
+async function doRecoverTransaction(wrapDir) {
+  const journalPath = join3(wrapDir, ".txn.json");
+  let entries;
+  let commitStarted = false;
+  try {
+    const raw = await readFile2(journalPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) {
+      entries = parsed;
+      commitStarted = true;
+    } else if (parsed != null && typeof parsed === "object" && Array.isArray(parsed.entries) && typeof parsed.commitStarted === "boolean") {
+      const journal = parsed;
+      entries = journal.entries;
+      commitStarted = journal.commitStarted;
+    } else {
+      try {
+        await unlink(journalPath);
+      } catch {
+      }
+      return;
+    }
+  } catch {
+    try {
+      await unlink(journalPath);
+    } catch {
+    }
+    return;
+  }
+  if (!commitStarted) {
+    for (const entry of entries) {
+      if (entry.op === "write" && entry.tempPath && existsSync3(entry.tempPath)) {
+        try {
+          await unlink(entry.tempPath);
+        } catch {
+        }
+      }
+    }
+    try {
+      await unlink(journalPath);
+    } catch {
+    }
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.op === "write" && entry.tempPath) {
+      const tempExists = existsSync3(entry.tempPath);
+      if (tempExists) {
+        try {
+          await rename(entry.tempPath, entry.target);
+        } catch {
+        }
+        try {
+          await unlink(entry.tempPath);
+        } catch {
+        }
+      }
+    } else if (entry.op === "delete") {
+      try {
+        await unlink(entry.target);
+      } catch {
+      }
+    }
+  }
+  try {
+    await unlink(journalPath);
+  } catch {
+  }
+}
+async function loadSingletonFile(filename, wrapDir, root, schema) {
+  const filePath = join3(wrapDir, filename);
+  const relPath = relative2(root, filePath);
+  let raw;
+  try {
+    raw = await readFile2(filePath, "utf-8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new ProjectLoaderError("not_found", `File not found: ${relPath}`);
+    }
+    throw new ProjectLoaderError(
+      "io_error",
+      `Cannot read file: ${relPath}`,
+      err
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new ProjectLoaderError(
+      "validation_failed",
+      `Invalid JSON in ${relPath}`,
+      err
+    );
+  }
+  const result = schema.safeParse(parsed);
+  if (!result.success) {
+    throw new ProjectLoaderError(
+      "validation_failed",
+      `Validation failed for ${relPath}: ${result.error.issues.map((i) => i.message).join("; ")}`,
+      result.error
+    );
+  }
+  return result.data;
+}
+async function loadDirectory(dirPath, root, schema, warnings) {
+  if (!existsSync3(dirPath)) return [];
+  let entries;
+  try {
+    entries = await readdir2(dirPath);
+  } catch (err) {
+    throw new ProjectLoaderError(
+      "io_error",
+      `Cannot enumerate ${relative2(root, dirPath)}`,
+      err
+    );
+  }
+  entries.sort();
+  const results = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    if (extname2(entry) !== ".json") continue;
+    const filePath = join3(dirPath, entry);
+    const relPath = relative2(root, filePath);
+    try {
+      const raw = await readFile2(filePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      const result = schema.safeParse(parsed);
+      if (!result.success) {
+        warnings.push({
+          file: relPath,
+          message: result.error.issues.map((i) => i.message).join("; "),
+          type: "schema_error"
+        });
+        continue;
+      }
+      results.push(result.data);
+    } catch (err) {
+      warnings.push({
+        file: relPath,
+        message: err instanceof Error ? err.message : String(err),
+        type: "parse_error"
+      });
+    }
+  }
+  return results;
+}
+async function withLock(wrapDir, fn) {
+  let release;
+  try {
+    release = await lockfile.lock(wrapDir, {
+      retries: { retries: 3, minTimeout: 100, maxTimeout: 1e3 },
+      stale: 1e4,
+      lockfilePath: join3(wrapDir, ".lock")
+    });
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) throw err;
+    throw new ProjectLoaderError(
+      "io_error",
+      `Lock acquisition failed for ${wrapDir}`,
+      err
+    );
+  }
+  try {
+    return await fn();
+  } finally {
+    if (release) {
+      try {
+        await release();
+      } catch {
+      }
+    }
+  }
+}
+
+// src/cli/helpers.ts
+import { resolve as resolve3, relative as relative3, extname as extname3 } from "path";
+import { lstat as lstat2 } from "fs/promises";
+var CliValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CliValidationError";
+  }
+};
+async function parseHandoverFilename(raw, handoversDir) {
+  if (raw.includes("/") || raw.includes("\\") || raw.includes("..") || raw.includes("\0")) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid handover filename "${raw}": contains path traversal characters`
+    );
+  }
+  if (extname3(raw) !== ".md") {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid handover filename "${raw}": must have .md extension`
+    );
+  }
+  const resolvedDir = resolve3(handoversDir);
+  const resolvedCandidate = resolve3(handoversDir, raw);
+  const rel = relative3(resolvedDir, resolvedCandidate);
+  if (!rel || rel.startsWith("..") || resolve3(resolvedDir, rel) !== resolvedCandidate) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid handover filename "${raw}": resolves outside handovers directory`
+    );
+  }
+  try {
+    const stats = await lstat2(resolvedCandidate);
+    if (stats.isSymbolicLink()) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Invalid handover filename "${raw}": symlinks not allowed`
+      );
+    }
+  } catch (err) {
+    if (err instanceof CliValidationError) throw err;
+    if (err.code !== "ENOENT") {
+      throw new CliValidationError(
+        "io_error",
+        `Cannot check handover file "${raw}": ${err.message}`
+      );
+    }
+  }
+  return raw;
+}
+
+// src/core/queries.ts
+function nextTicket(state) {
+  const phases = state.roadmap.phases;
+  if (phases.length === 0 || state.leafTickets.length === 0) {
+    return { kind: "empty_project" };
+  }
+  let allPhasesComplete = true;
+  for (const phase of phases) {
+    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 candidate = incompleteLeaves.find((t) => !state.isBlocked(t));
+    if (candidate) {
+      const impact = ticketsUnblockedBy(candidate.id, state);
+      const progress = candidate.parentTicket ? umbrellaProgress(candidate.parentTicket, state) : null;
+      return {
+        kind: "found",
+        ticket: candidate,
+        unblockImpact: { ticketId: candidate.id, wouldUnblock: impact },
+        umbrellaProgress: progress
+      };
+    }
+    return {
+      kind: "all_blocked",
+      phaseId: phase.id,
+      blockedCount: incompleteLeaves.length
+    };
+  }
+  if (allPhasesComplete) {
+    return { kind: "all_complete" };
+  }
+  return { kind: "empty_project" };
+}
+function blockedTickets(state) {
+  return state.leafTickets.filter(
+    (t) => t.status !== "complete" && state.isBlocked(t)
+  );
+}
+function ticketsUnblockedBy(ticketId, state) {
+  const blocked = state.reverseBlocks(ticketId);
+  return blocked.filter((t) => {
+    if (t.status === "complete") return false;
+    return t.blockedBy.every((bid) => {
+      if (bid === ticketId) return true;
+      const blocker = state.ticketByID(bid);
+      if (!blocker) return false;
+      return blocker.status === "complete";
+    });
+  });
+}
+function umbrellaProgress(ticketId, state) {
+  if (!state.umbrellaIDs.has(ticketId)) return null;
+  const leaves = collectDescendantLeaves(ticketId, state, /* @__PURE__ */ new Set());
+  const complete = leaves.filter((t) => t.status === "complete").length;
+  return {
+    total: leaves.length,
+    complete,
+    status: state.umbrellaStatus(ticketId)
+  };
+}
+function currentPhase(state) {
+  for (const phase of state.roadmap.phases) {
+    const leaves = state.phaseTickets(phase.id);
+    if (leaves.length === 0) continue;
+    if (state.phaseStatus(phase.id) !== "complete") return phase;
+  }
+  return null;
+}
+function phasesWithStatus(state) {
+  return state.roadmap.phases.map((phase) => ({
+    phase,
+    status: state.phaseStatus(phase.id),
+    leafCount: state.phaseTickets(phase.id).length
+  }));
+}
+function isBlockerCleared(blocker) {
+  if (blocker.cleared === true) return true;
+  if (blocker.clearedDate != null) return true;
+  return false;
+}
+function collectDescendantLeaves(ticketId, state, visited) {
+  if (visited.has(ticketId)) return [];
+  visited.add(ticketId);
+  const children = state.umbrellaChildren(ticketId);
+  const leaves = [];
+  for (const child of children) {
+    if (state.umbrellaIDs.has(child.id)) {
+      leaves.push(...collectDescendantLeaves(child.id, state, visited));
+    } else {
+      leaves.push(child);
+    }
+  }
+  return leaves;
+}
+
+// src/core/output-formatter.ts
+var ExitCode = {
+  OK: 0,
+  USER_ERROR: 1,
+  VALIDATION_ERROR: 2,
+  PARTIAL: 3
+};
+function successEnvelope(data) {
+  return { version: 1, data };
+}
+function errorEnvelope(code, message) {
+  return { version: 1, error: { code, message } };
+}
+function escapeMarkdownInline(text) {
+  return text.replace(/\\/g, "\\\\").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/([`*_~\[\]()|])/g, "\\$1").replace(/(^|\n)([#\-+*])/g, "$1\\$2").replace(/(^|\n)(\d+)\./g, "$1$2\\.");
+}
+function fencedBlock(content, lang) {
+  let maxTicks = 2;
+  const matches = content.match(/`+/g);
+  if (matches) {
+    for (const m of matches) {
+      if (m.length > maxTicks) maxTicks = m.length;
+    }
+  }
+  const fence = "`".repeat(maxTicks + 1);
+  return `${fence}${lang ?? ""}
+${content}
+${fence}`;
+}
+function formatStatus(state, format) {
+  const phases = phasesWithStatus(state);
+  const data = {
+    project: state.config.project,
+    totalTickets: state.totalTicketCount,
+    completeTickets: state.completeTicketCount,
+    openTickets: state.openTicketCount,
+    blockedTickets: state.blockedCount,
+    openIssues: state.openIssueCount,
+    handovers: state.handoverFilenames.length,
+    phases: phases.map((p) => ({
+      id: p.phase.id,
+      name: p.phase.name,
+      status: p.status,
+      leafCount: p.leafCount
+    }))
+  };
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(data), null, 2);
+  }
+  const lines = [
+    `# ${escapeMarkdownInline(state.config.project)}`,
+    "",
+    `Tickets: ${state.completeTicketCount}/${state.totalTicketCount} complete, ${state.blockedCount} blocked`,
+    `Issues: ${state.openIssueCount} open`,
+    `Handovers: ${state.handoverFilenames.length}`,
+    "",
+    "## Phases",
+    ""
+  ];
+  for (const p of phases) {
+    const indicator = p.status === "complete" ? "[x]" : p.status === "inprogress" ? "[~]" : "[ ]";
+    const summary = p.phase.summary ?? truncate(p.phase.description, 80);
+    lines.push(`${indicator} **${escapeMarkdownInline(p.phase.name)}** (${p.leafCount} tickets) \u2014 ${escapeMarkdownInline(summary)}`);
+  }
+  return lines.join("\n");
+}
+function formatPhaseList(state, format) {
+  const phases = phasesWithStatus(state);
+  const data = phases.map((p) => ({
+    id: p.phase.id,
+    label: p.phase.label,
+    name: p.phase.name,
+    description: p.phase.summary ?? p.phase.description,
+    status: p.status,
+    leafCount: p.leafCount
+  }));
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(data), null, 2);
+  }
+  const lines = [];
+  for (const p of data) {
+    const indicator = p.status === "complete" ? "[x]" : p.status === "inprogress" ? "[~]" : "[ ]";
+    lines.push(`${indicator} **${escapeMarkdownInline(p.name)}** (${p.id}) \u2014 ${p.leafCount} tickets \u2014 ${escapeMarkdownInline(truncate(p.description, 80))}`);
+  }
+  return lines.join("\n");
+}
+function formatPhaseTickets(phaseId, state, format) {
+  const tickets = state.phaseTickets(phaseId);
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(tickets), null, 2);
+  }
+  if (tickets.length === 0) return "No tickets in this phase.";
+  return tickets.map((t) => formatTicketOneLiner(t, state)).join("\n");
+}
+function formatTicket(ticket, state, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(ticket), null, 2);
+  }
+  const blocked = state.isBlocked(ticket) ? " [BLOCKED]" : "";
+  const lines = [
+    `# ${escapeMarkdownInline(ticket.id)}: ${escapeMarkdownInline(ticket.title)}${blocked}`,
+    "",
+    `Status: ${ticket.status} | Type: ${ticket.type} | Phase: ${ticket.phase ?? "none"} | Order: ${ticket.order}`,
+    `Created: ${ticket.createdDate}${ticket.completedDate ? ` | Completed: ${ticket.completedDate}` : ""}`
+  ];
+  if (ticket.blockedBy.length > 0) {
+    lines.push(`Blocked by: ${ticket.blockedBy.join(", ")}`);
+  }
+  if (ticket.parentTicket) {
+    lines.push(`Parent: ${ticket.parentTicket}`);
+  }
+  if (ticket.description) {
+    lines.push("", "## Description", "", fencedBlock(ticket.description));
+  }
+  return lines.join("\n");
+}
+function formatNextTicketOutcome(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": {
+      return `All ${outcome.blockedCount} incomplete tickets in phase "${escapeMarkdownInline(outcome.phaseId)}" are blocked.`;
+    }
+    case "found": {
+      const t = outcome.ticket;
+      const lines = [
+        `# Next: ${escapeMarkdownInline(t.id)} \u2014 ${escapeMarkdownInline(t.title)}`,
+        "",
+        `Phase: ${t.phase ?? "none"} | Order: ${t.order} | Type: ${t.type}`
+      ];
+      if (outcome.unblockImpact.wouldUnblock.length > 0) {
+        const ids = outcome.unblockImpact.wouldUnblock.map((u) => u.id).join(", ");
+        lines.push(`Completing this unblocks: ${ids}`);
+      }
+      if (outcome.umbrellaProgress) {
+        const p = outcome.umbrellaProgress;
+        lines.push(`Parent progress: ${p.complete}/${p.total} complete (${p.status})`);
+      }
+      if (t.description) {
+        lines.push("", fencedBlock(t.description));
+      }
+      return lines.join("\n");
+    }
+  }
+}
+function formatTicketList(tickets, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(tickets), null, 2);
+  }
+  if (tickets.length === 0) return "No tickets found.";
+  const lines = [];
+  for (const t of tickets) {
+    const status = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+    lines.push(`${status} ${t.id}: ${escapeMarkdownInline(t.title)} (${t.phase ?? "none"})`);
+  }
+  return lines.join("\n");
+}
+function formatIssue(issue, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(issue), null, 2);
+  }
+  const lines = [
+    `# ${escapeMarkdownInline(issue.id)}: ${escapeMarkdownInline(issue.title)}`,
+    "",
+    `Status: ${issue.status} | Severity: ${issue.severity}`,
+    `Components: ${issue.components.join(", ") || "none"}`,
+    `Discovered: ${issue.discoveredDate}${issue.resolvedDate ? ` | Resolved: ${issue.resolvedDate}` : ""}`
+  ];
+  if (issue.relatedTickets.length > 0) {
+    lines.push(`Related: ${issue.relatedTickets.join(", ")}`);
+  }
+  lines.push("", "## Impact", "", fencedBlock(issue.impact));
+  if (issue.resolution) {
+    lines.push("", "## Resolution", "", fencedBlock(issue.resolution));
+  }
+  return lines.join("\n");
+}
+function formatIssueList(issues, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(issues), null, 2);
+  }
+  if (issues.length === 0) return "No issues found.";
+  const lines = [];
+  for (const i of issues) {
+    const status = i.status === "resolved" ? "[x]" : "[ ]";
+    lines.push(`${status} ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}`);
+  }
+  return lines.join("\n");
+}
+function formatBlockedTickets(tickets, state, format) {
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope(
+        tickets.map((t) => ({
+          ...t,
+          blockers: t.blockedBy.map((bid) => ({
+            id: bid,
+            status: state.ticketByID(bid)?.status ?? "unknown"
+          }))
+        }))
+      ),
+      null,
+      2
+    );
+  }
+  if (tickets.length === 0) return "No blocked tickets.";
+  const lines = [];
+  for (const t of tickets) {
+    const blockerInfo = t.blockedBy.map((bid) => {
+      const b = state.ticketByID(bid);
+      return b ? `${bid} (${b.status})` : `${bid} (unknown)`;
+    }).join(", ");
+    lines.push(`${t.id}: ${escapeMarkdownInline(t.title)} \u2014 blocked by: ${blockerInfo}`);
+  }
+  return lines.join("\n");
+}
+function formatValidation(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  const lines = [
+    result.valid ? "Validation passed." : "Validation failed.",
+    `Errors: ${result.errorCount} | Warnings: ${result.warningCount} | Info: ${result.infoCount}`
+  ];
+  if (result.findings.length > 0) {
+    lines.push("");
+    for (const f of result.findings) {
+      const prefix = f.level === "error" ? "ERROR" : f.level === "warning" ? "WARN" : "INFO";
+      const entity = f.entity ? `[${escapeMarkdownInline(f.entity)}] ` : "";
+      lines.push(`${prefix}: ${entity}${escapeMarkdownInline(f.message)}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatBlockerList(roadmap, format) {
+  if (format === "json") {
+    return JSON.stringify(
+      successEnvelope(
+        roadmap.blockers.map((b) => ({
+          name: b.name,
+          cleared: isBlockerCleared(b),
+          note: b.note ?? null,
+          createdDate: b.createdDate ?? null,
+          clearedDate: b.clearedDate ?? null
+        }))
+      ),
+      null,
+      2
+    );
+  }
+  if (roadmap.blockers.length === 0) return "No blockers.";
+  const lines = [];
+  for (const b of roadmap.blockers) {
+    const status = isBlockerCleared(b) ? "[x]" : "[ ]";
+    const note = b.note ? ` \u2014 ${escapeMarkdownInline(b.note)}` : "";
+    lines.push(`${status} ${escapeMarkdownInline(b.name)}${note}`);
+  }
+  return lines.join("\n");
+}
+function formatError(code, message, format) {
+  if (format === "json") {
+    return JSON.stringify(errorEnvelope(code, message), null, 2);
+  }
+  return `Error [${code}]: ${escapeMarkdownInline(message)}`;
+}
+function formatHandoverList(filenames, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(filenames), null, 2);
+  }
+  if (filenames.length === 0) return "No handovers found.";
+  return filenames.join("\n");
+}
+function formatHandoverContent(filename, content, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope({ filename, content }), null, 2);
+  }
+  return content;
+}
+function truncate(text, maxLen) {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + "...";
+}
+function formatTicketOneLiner(t, state) {
+  const status = t.status === "complete" ? "[x]" : t.status === "inprogress" ? "[~]" : "[ ]";
+  const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
+  return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
+}
+
+// src/cli/commands/status.ts
+function handleStatus(ctx) {
+  return { output: formatStatus(ctx.state, ctx.format) };
+}
+
+// src/core/validation.ts
+function validateProject(state) {
+  const findings = [];
+  const phaseIDs = new Set(state.roadmap.phases.map((p) => p.id));
+  const ticketIDs = /* @__PURE__ */ new Set();
+  const issueIDs = /* @__PURE__ */ new Set();
+  const ticketIDCounts = /* @__PURE__ */ new Map();
+  for (const t of state.tickets) {
+    ticketIDCounts.set(t.id, (ticketIDCounts.get(t.id) ?? 0) + 1);
+    ticketIDs.add(t.id);
+  }
+  for (const [id, count] of ticketIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_ticket_id",
+        message: `Duplicate ticket ID: ${id} appears ${count} times.`,
+        entity: id
+      });
+    }
+  }
+  const issueIDCounts = /* @__PURE__ */ new Map();
+  for (const i of state.issues) {
+    issueIDCounts.set(i.id, (issueIDCounts.get(i.id) ?? 0) + 1);
+    issueIDs.add(i.id);
+  }
+  for (const [id, count] of issueIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_issue_id",
+        message: `Duplicate issue 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);
+  }
+  for (const [id, count] of phaseIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_phase_id",
+        message: `Duplicate phase ID: ${id} appears ${count} times.`,
+        entity: id
+      });
+    }
+  }
+  for (const t of state.tickets) {
+    if (t.phase !== null && !phaseIDs.has(t.phase)) {
+      findings.push({
+        level: "error",
+        code: "invalid_phase_ref",
+        message: `Ticket ${t.id} references unknown phase "${t.phase}".`,
+        entity: t.id
+      });
+    }
+    for (const bid of t.blockedBy) {
+      if (bid === t.id) {
+        findings.push({
+          level: "error",
+          code: "self_ref_blocked_by",
+          message: `Ticket ${t.id} references itself in blockedBy.`,
+          entity: t.id
+        });
+      } else if (!ticketIDs.has(bid)) {
+        findings.push({
+          level: "error",
+          code: "invalid_blocked_by_ref",
+          message: `Ticket ${t.id} blockedBy references nonexistent ticket ${bid}.`,
+          entity: t.id
+        });
+      } else if (state.umbrellaIDs.has(bid)) {
+        findings.push({
+          level: "error",
+          code: "blocked_by_umbrella",
+          message: `Ticket ${t.id} blockedBy references umbrella ticket ${bid}. Use leaf tickets instead.`,
+          entity: t.id
+        });
+      }
+    }
+    if (t.parentTicket != null) {
+      if (t.parentTicket === t.id) {
+        findings.push({
+          level: "error",
+          code: "self_ref_parent",
+          message: `Ticket ${t.id} references itself as parentTicket.`,
+          entity: t.id
+        });
+      } else if (!ticketIDs.has(t.parentTicket)) {
+        findings.push({
+          level: "error",
+          code: "invalid_parent_ref",
+          message: `Ticket ${t.id} parentTicket references nonexistent ticket ${t.parentTicket}.`,
+          entity: t.id
+        });
+      }
+    }
+  }
+  detectParentCycles(state, findings);
+  detectBlockedByCycles(state, findings);
+  for (const i of state.issues) {
+    for (const tref of i.relatedTickets) {
+      if (!ticketIDs.has(tref)) {
+        findings.push({
+          level: "error",
+          code: "invalid_related_ticket_ref",
+          message: `Issue ${i.id} relatedTickets references nonexistent ticket ${tref}.`,
+          entity: i.id
+        });
+      }
+    }
+    if (i.phase != null && !phaseIDs.has(i.phase)) {
+      findings.push({
+        level: "error",
+        code: "invalid_phase_ref",
+        message: `Issue ${i.id} references unknown phase "${i.phase}".`,
+        entity: i.id
+      });
+    }
+    if (i.relatedTickets.length === 0 && i.status === "open") {
+      findings.push({
+        level: "warning",
+        code: "orphan_issue",
+        message: `Issue ${i.id} is open with no related tickets.`,
+        entity: i.id
+      });
+    }
+  }
+  const orderByPhase = /* @__PURE__ */ new Map();
+  for (const t of state.leafTickets) {
+    const phase = t.phase;
+    if (!orderByPhase.has(phase)) orderByPhase.set(phase, /* @__PURE__ */ new Map());
+    const orders = orderByPhase.get(phase);
+    if (!orders.has(t.order)) orders.set(t.order, []);
+    orders.get(t.order).push(t.id);
+  }
+  for (const [phase, orders] of orderByPhase) {
+    for (const [order, ids] of orders) {
+      if (ids.length > 1) {
+        findings.push({
+          level: "info",
+          code: "duplicate_order",
+          message: `Phase "${phase ?? "null"}": tickets ${ids.join(", ")} share order ${order}.`,
+          entity: null
+        });
+      }
+    }
+  }
+  const errorCount = findings.filter((f) => f.level === "error").length;
+  const warningCount = findings.filter((f) => f.level === "warning").length;
+  const infoCount = findings.filter((f) => f.level === "info").length;
+  return {
+    valid: errorCount === 0,
+    errorCount,
+    warningCount,
+    infoCount,
+    findings
+  };
+}
+function mergeValidation(result, loaderWarnings) {
+  if (loaderWarnings.length === 0) return result;
+  const extra = loaderWarnings.map((w) => ({
+    level: w.type === "naming_convention" ? "info" : "error",
+    code: `loader_${w.type}`,
+    message: `${w.file}: ${w.message}`,
+    entity: null
+  }));
+  const allFindings = [...result.findings, ...extra];
+  const errorCount = allFindings.filter((f) => f.level === "error").length;
+  const warningCount = allFindings.filter((f) => f.level === "warning").length;
+  const infoCount = allFindings.filter((f) => f.level === "info").length;
+  return {
+    valid: errorCount === 0,
+    errorCount,
+    warningCount,
+    infoCount,
+    findings: allFindings
+  };
+}
+function detectParentCycles(state, findings) {
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  for (const t of state.tickets) {
+    if (t.parentTicket == null || visited.has(t.id)) continue;
+    dfsParent(t.id, state, visited, inStack, findings);
+  }
+}
+function dfsParent(id, state, visited, inStack, findings) {
+  if (inStack.has(id)) {
+    findings.push({
+      level: "error",
+      code: "parent_cycle",
+      message: `Cycle detected in parentTicket chain involving ${id}.`,
+      entity: id
+    });
+    return;
+  }
+  if (visited.has(id)) return;
+  inStack.add(id);
+  const ticket = state.ticketByID(id);
+  if (ticket?.parentTicket && ticket.parentTicket !== id) {
+    dfsParent(ticket.parentTicket, state, visited, inStack, findings);
+  }
+  inStack.delete(id);
+  visited.add(id);
+}
+function detectBlockedByCycles(state, findings) {
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  for (const t of state.tickets) {
+    if (t.blockedBy.length === 0 || visited.has(t.id)) continue;
+    dfsBlocked(t.id, state, visited, inStack, findings);
+  }
+}
+function dfsBlocked(id, state, visited, inStack, findings) {
+  if (inStack.has(id)) {
+    findings.push({
+      level: "error",
+      code: "blocked_by_cycle",
+      message: `Cycle detected in blockedBy chain involving ${id}.`,
+      entity: id
+    });
+    return;
+  }
+  if (visited.has(id)) return;
+  inStack.add(id);
+  const ticket = state.ticketByID(id);
+  if (ticket) {
+    for (const bid of ticket.blockedBy) {
+      if (bid !== id) {
+        dfsBlocked(bid, state, visited, inStack, findings);
+      }
+    }
+  }
+  inStack.delete(id);
+  visited.add(id);
+}
+
+// src/cli/commands/validate.ts
+function handleValidate(ctx) {
+  const baseResult = validateProject(ctx.state);
+  const merged = mergeValidation(baseResult, ctx.warnings);
+  return {
+    output: formatValidation(merged, ctx.format),
+    exitCode: merged.valid ? ExitCode.OK : ExitCode.VALIDATION_ERROR
+  };
+}
+
+// src/cli/commands/handover.ts
+function handleHandoverList(ctx) {
+  return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
+}
+async function handleHandoverLatest(ctx) {
+  if (ctx.state.handoverFilenames.length === 0) {
+    return {
+      output: formatError("not_found", "No handovers found", ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      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") {
+      return {
+        output: formatError("not_found", `Handover file not found: ${filename}`, ctx.format),
+        exitCode: ExitCode.USER_ERROR,
+        errorCode: "not_found"
+      };
+    }
+    return {
+      output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "io_error"
+    };
+  }
+}
+async function handleHandoverGet(filename, ctx) {
+  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") {
+      return {
+        output: formatError("not_found", `Handover not found: ${filename}`, ctx.format),
+        exitCode: ExitCode.USER_ERROR,
+        errorCode: "not_found"
+      };
+    }
+    return {
+      output: formatError("io_error", `Cannot read handover: ${err.message}`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "io_error"
+    };
+  }
+}
+
+// src/cli/commands/blocker.ts
+function handleBlockerList(ctx) {
+  return { output: formatBlockerList(ctx.state.roadmap, ctx.format) };
+}
+
+// src/cli/commands/ticket.ts
+function handleTicketList(filters, ctx) {
+  let tickets = [...ctx.state.leafTickets];
+  if (filters.status) {
+    if (!TICKET_STATUSES.includes(filters.status)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown ticket status "${filters.status}": must be one of ${TICKET_STATUSES.join(", ")}`
+      );
+    }
+    tickets = tickets.filter((t) => t.status === filters.status);
+  }
+  if (filters.phase) {
+    tickets = tickets.filter((t) => t.phase === filters.phase);
+  }
+  if (filters.type) {
+    if (!TICKET_TYPES.includes(filters.type)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown ticket type "${filters.type}": must be one of ${TICKET_TYPES.join(", ")}`
+      );
+    }
+    tickets = tickets.filter((t) => t.type === filters.type);
+  }
+  return { output: formatTicketList(tickets, ctx.format) };
+}
+function handleTicketGet(id, ctx) {
+  const ticket = ctx.state.ticketByID(id);
+  if (!ticket) {
+    return {
+      output: formatError("not_found", `Ticket ${id} not found`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "not_found"
+    };
+  }
+  return { output: formatTicket(ticket, ctx.state, ctx.format) };
+}
+function handleTicketNext(ctx) {
+  const outcome = nextTicket(ctx.state);
+  const exitCode = outcome.kind === "found" ? ExitCode.OK : ExitCode.USER_ERROR;
+  return {
+    output: formatNextTicketOutcome(outcome, ctx.state, ctx.format),
+    exitCode
+  };
+}
+function handleTicketBlocked(ctx) {
+  const blocked = blockedTickets(ctx.state);
+  return { output: formatBlockedTickets(blocked, ctx.state, ctx.format) };
+}
+
+// src/cli/commands/issue.ts
+function handleIssueList(filters, ctx) {
+  let issues = [...ctx.state.issues];
+  if (filters.status) {
+    if (!ISSUE_STATUSES.includes(filters.status)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown issue status "${filters.status}": must be one of ${ISSUE_STATUSES.join(", ")}`
+      );
+    }
+    issues = issues.filter((i) => i.status === filters.status);
+  }
+  if (filters.severity) {
+    if (!ISSUE_SEVERITIES.includes(filters.severity)) {
+      throw new CliValidationError(
+        "invalid_input",
+        `Unknown issue severity "${filters.severity}": must be one of ${ISSUE_SEVERITIES.join(", ")}`
+      );
+    }
+    issues = issues.filter((i) => i.severity === filters.severity);
+  }
+  return { output: formatIssueList(issues, ctx.format) };
+}
+function handleIssueGet(id, ctx) {
+  const issue = ctx.state.issueByID(id);
+  if (!issue) {
+    return {
+      output: formatError("not_found", `Issue ${id} not found`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "not_found"
+    };
+  }
+  return { output: formatIssue(issue, ctx.format) };
+}
+
+// src/cli/commands/phase.ts
+import { join as join4, resolve as resolve4 } from "path";
+function handlePhaseList(ctx) {
+  return { output: formatPhaseList(ctx.state, ctx.format) };
+}
+function handlePhaseCurrent(ctx) {
+  const phase = currentPhase(ctx.state);
+  if (phase) {
+    if (ctx.format === "json") {
+      return { output: JSON.stringify(successEnvelope(phase), null, 2) };
+    }
+    const summary = phase.summary ?? phase.description;
+    return { output: `${phase.name} (${phase.id}) \u2014 ${summary}` };
+  }
+  const hasLeavesInAnyPhase = ctx.state.roadmap.phases.some(
+    (p) => ctx.state.phaseTickets(p.id).length > 0
+  );
+  if (!hasLeavesInAnyPhase) {
+    if (ctx.format === "json") {
+      return {
+        output: JSON.stringify(successEnvelope({ current: null, reason: "no_phases" }), null, 2),
+        exitCode: ExitCode.USER_ERROR
+      };
+    }
+    return {
+      output: "No phases with tickets defined.",
+      exitCode: ExitCode.USER_ERROR
+    };
+  }
+  if (ctx.format === "json") {
+    return {
+      output: JSON.stringify(successEnvelope({ current: null, reason: "all_complete" }), null, 2)
+    };
+  }
+  return { output: "All phases complete." };
+}
+function handlePhaseTickets(phaseId, ctx) {
+  const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === phaseId);
+  if (!phaseExists) {
+    return {
+      output: formatError("not_found", `Phase "${phaseId}" not found`, ctx.format),
+      exitCode: ExitCode.USER_ERROR,
+      errorCode: "not_found"
+    };
+  }
+  return { output: formatPhaseTickets(phaseId, ctx.state, ctx.format) };
+}
+
+// src/mcp/tools.ts
+var INFRASTRUCTURE_ERROR_CODES = [
+  "io_error",
+  "project_corrupt",
+  "version_mismatch"
+];
+function formatMcpError(code, message) {
+  return `[${code}] ${message}`;
+}
+async function runMcpReadTool(pinnedRoot, handler) {
+  try {
+    const { state, warnings } = await loadProject(pinnedRoot);
+    const handoversDir = join5(pinnedRoot, ".story", "handovers");
+    const ctx = { state, warnings, root: pinnedRoot, handoversDir, format: "md" };
+    const result = await handler(ctx);
+    if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
+      return {
+        content: [{ type: "text", text: formatMcpError(result.errorCode, result.output) }],
+        isError: true
+      };
+    }
+    let text = result.output;
+    const integrityWarnings = warnings.filter(
+      (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+    );
+    if (integrityWarnings.length > 0) {
+      text = `Warning: ${integrityWarnings.length} item(s) skipped due to data integrity issues. Run claudestory_validate for details.
+
+${text}`;
+    }
+    return { content: [{ type: "text", text }] };
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) {
+      return { content: [{ type: "text", text: formatMcpError(err.code, err.message) }], isError: true };
+    }
+    if (err instanceof CliValidationError) {
+      return { content: [{ type: "text", text: formatMcpError(err.code, err.message) }], isError: true };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: formatMcpError("io_error", message) }], isError: true };
+  }
+}
+function registerAllTools(server, pinnedRoot) {
+  server.registerTool("claudestory_status", {
+    description: "Project summary: phase statuses, ticket/issue counts, blockers, current phase"
+  }, () => runMcpReadTool(pinnedRoot, handleStatus));
+  server.registerTool("claudestory_phase_list", {
+    description: "All phases with derived status (complete/inprogress/notstarted)"
+  }, () => runMcpReadTool(pinnedRoot, handlePhaseList));
+  server.registerTool("claudestory_phase_current", {
+    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));
+  server.registerTool("claudestory_ticket_blocked", {
+    description: "All blocked tickets with their blocking dependencies"
+  }, () => runMcpReadTool(pinnedRoot, handleTicketBlocked));
+  server.registerTool("claudestory_handover_list", {
+    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));
+  server.registerTool("claudestory_blocker_list", {
+    description: "All roadmap blockers with dates and status"
+  }, () => runMcpReadTool(pinnedRoot, handleBlockerList));
+  server.registerTool("claudestory_validate", {
+    description: "Reference integrity + schema checks on all .story/ files"
+  }, () => runMcpReadTool(pinnedRoot, handleValidate));
+  server.registerTool("claudestory_phase_tickets", {
+    description: "Leaf tickets for a specific phase, sorted by order",
+    inputSchema: {
+      phaseId: z6.string().describe("Phase ID (e.g. p5b, dogfood)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
+    const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === args.phaseId);
+    if (!phaseExists) {
+      return {
+        output: `Phase "${args.phaseId}" not found in roadmap.`,
+        exitCode: 1,
+        errorCode: "not_found"
+      };
+    }
+    return handlePhaseTickets(args.phaseId, ctx);
+  }));
+  server.registerTool("claudestory_ticket_list", {
+    description: "List leaf tickets with optional filters",
+    inputSchema: {
+      status: z6.enum(TICKET_STATUSES).optional().describe("Filter by status: open, inprogress, complete"),
+      phase: z6.string().optional().describe("Filter by phase ID"),
+      type: z6.enum(TICKET_TYPES).optional().describe("Filter by type: task, feature, chore")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => {
+    if (args.phase) {
+      const phaseExists = ctx.state.roadmap.phases.some((p) => p.id === args.phase);
+      if (!phaseExists) {
+        return {
+          output: `Phase "${args.phase}" not found in roadmap.`,
+          exitCode: 1,
+          errorCode: "not_found"
+        };
+      }
+    }
+    return handleTicketList(
+      { status: args.status, phase: args.phase, type: args.type },
+      ctx
+    );
+  }));
+  server.registerTool("claudestory_ticket_get", {
+    description: "Get a ticket by ID (includes umbrella tickets)",
+    inputSchema: {
+      id: z6.string().regex(TICKET_ID_REGEX).describe("Ticket ID (e.g. T-001, T-079b)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleTicketGet(args.id, ctx)));
+  server.registerTool("claudestory_issue_list", {
+    description: "List issues with optional filters",
+    inputSchema: {
+      status: z6.enum(ISSUE_STATUSES).optional().describe("Filter by status: open, inprogress, resolved"),
+      severity: z6.enum(ISSUE_SEVERITIES).optional().describe("Filter by severity: critical, high, medium, low")
+    }
+  }, (args) => runMcpReadTool(
+    pinnedRoot,
+    (ctx) => handleIssueList({ status: args.status, severity: args.severity }, ctx)
+  ));
+  server.registerTool("claudestory_issue_get", {
+    description: "Get an issue by ID",
+    inputSchema: {
+      id: z6.string().regex(ISSUE_ID_REGEX).describe("Issue ID (e.g. ISS-001)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleIssueGet(args.id, ctx)));
+  server.registerTool("claudestory_handover_get", {
+    description: "Content of a specific handover document by filename",
+    inputSchema: {
+      filename: z6.string().describe("Handover filename (e.g. 2026-03-20-session.md)")
+    }
+  }, (args) => runMcpReadTool(pinnedRoot, (ctx) => handleHandoverGet(args.filename, ctx)));
+}
+
+// src/mcp/index.ts
+var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
+var CONFIG_PATH2 = ".story/config.json";
+var version = "0.1.0";
+function pinProjectRoot() {
+  const envRoot = process.env[ENV_VAR2];
+  if (envRoot) {
+    if (!isAbsolute(envRoot)) {
+      process.stderr.write(`Error: ${ENV_VAR2} must be an absolute path, got: ${envRoot}
+`);
+      process.exit(1);
+    }
+    const resolved = resolve5(envRoot);
+    let canonical;
+    try {
+      canonical = realpathSync(resolved);
+    } catch {
+      process.stderr.write(`Error: ${ENV_VAR2} path does not exist: ${resolved}
+`);
+      process.exit(1);
+    }
+    if (!existsSync4(join6(canonical, CONFIG_PATH2))) {
+      process.stderr.write(`Error: No .story/config.json at ${canonical}
+`);
+      process.exit(1);
+    }
+    return canonical;
+  }
+  const root = discoverProjectRoot();
+  if (!root) {
+    process.stderr.write("Error: No .story/ project found. Set CLAUDESTORY_PROJECT_ROOT or run from a project directory.\n");
+    process.exit(1);
+  }
+  return realpathSync(root);
+}
+async function main() {
+  const root = pinProjectRoot();
+  const server = new McpServer(
+    { name: "claudestory", version },
+    {
+      instructions: "Start with claudestory_status for a project overview, then claudestory_ticket_next for the highest-priority work, then claudestory_handover_latest for session context."
+    }
+  );
+  registerAllTools(server, root);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`claudestory MCP server running (root: ${root})
+`);
+}
+main().catch((err) => {
+  process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});