@anthropologies/claudestory 0.1.0

package/dist/cli.js

@@ -0,0 +1,3792 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var init_esm_shims = __esm({
+  "node_modules/tsup/assets/esm_shims.js"() {
+    "use strict";
+  }
+});
+
+// src/core/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  CURRENT_SCHEMA_VERSION: () => CURRENT_SCHEMA_VERSION,
+  INTEGRITY_WARNING_TYPES: () => INTEGRITY_WARNING_TYPES,
+  ProjectLoaderError: () => ProjectLoaderError
+});
+var CURRENT_SCHEMA_VERSION, ProjectLoaderError, INTEGRITY_WARNING_TYPES;
+var init_errors = __esm({
+  "src/core/errors.ts"() {
+    "use strict";
+    init_esm_shims();
+    CURRENT_SCHEMA_VERSION = 1;
+    ProjectLoaderError = class extends Error {
+      constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+      }
+      name = "ProjectLoaderError";
+    };
+    INTEGRITY_WARNING_TYPES = [
+      "parse_error",
+      "schema_error",
+      "duplicate_id"
+    ];
+  }
+});
+
+// src/core/project-root-discovery.ts
+var project_root_discovery_exports = {};
+__export(project_root_discovery_exports, {
+  discoverProjectRoot: () => discoverProjectRoot
+});
+import { existsSync as existsSync3 } from "fs";
+import { resolve as resolve2, dirname as dirname2, join as join3 } from "path";
+function discoverProjectRoot(startDir) {
+  const envRoot = process.env[ENV_VAR];
+  if (envRoot) {
+    const resolved = resolve2(envRoot);
+    if (existsSync3(join3(resolved, CONFIG_PATH))) {
+      return resolved;
+    }
+    return null;
+  }
+  let current = resolve2(startDir ?? process.cwd());
+  for (; ; ) {
+    if (existsSync3(join3(current, CONFIG_PATH))) {
+      return current;
+    }
+    const parent = dirname2(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+var ENV_VAR, CONFIG_PATH;
+var init_project_root_discovery = __esm({
+  "src/core/project-root-discovery.ts"() {
+    "use strict";
+    init_esm_shims();
+    ENV_VAR = "CLAUDESTORY_PROJECT_ROOT";
+    CONFIG_PATH = ".story/config.json";
+  }
+});
+
+// src/cli/index.ts
+init_esm_shims();
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+// src/core/output-formatter.ts
+init_esm_shims();
+
+// src/core/queries.ts
+init_esm_shims();
+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 formatInitResult(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  return [`Initialized .story/ at ${escapeMarkdownInline(result.root)}`, "", ...result.created.map((f) => `  ${f}`)].join("\n");
+}
+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/run.ts
+init_esm_shims();
+import { join as join5 } from "path";
+
+// src/core/index.ts
+init_esm_shims();
+
+// src/core/project-state.ts
+init_esm_shims();
+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/project-loader.ts
+init_esm_shims();
+import {
+  readdir as readdir2,
+  readFile as readFile2,
+  writeFile,
+  rename,
+  unlink,
+  stat,
+  realpath,
+  lstat,
+  open
+} from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { join as join2, resolve, relative as relative2, extname as extname2, dirname, basename } from "path";
+import lockfile from "proper-lockfile";
+
+// src/models/ticket.ts
+init_esm_shims();
+import { z as z2 } from "zod";
+
+// src/models/types.ts
+init_esm_shims();
+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 OUTPUT_FORMATS = ["json", "md"];
+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
+init_esm_shims();
+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
+init_esm_shims();
+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
+init_esm_shims();
+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-loader.ts
+init_errors();
+
+// src/core/handover-parser.ts
+init_esm_shims();
+import { readdir, readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { join, relative, extname } from "path";
+var HANDOVER_DATE_REGEX = /^\d{4}-\d{2}-\d{2}/;
+async function listHandovers(handoversDir, root, warnings) {
+  if (!existsSync(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, join(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(join(handoversDir, filename), "utf-8");
+}
+
+// src/core/project-loader.ts
+async function loadProject(root, options) {
+  const absRoot = resolve(root);
+  const wrapDir = join2(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 (existsSync2(join2(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(
+    join2(wrapDir, "tickets"),
+    absRoot,
+    TicketSchema,
+    warnings
+  );
+  const issues = await loadDirectory(
+    join2(wrapDir, "issues"),
+    absRoot,
+    IssueSchema,
+    warnings
+  );
+  const handoversDir = join2(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 writeTicketUnlocked(ticket, root) {
+  const parsed = TicketSchema.parse(ticket);
+  if (!TICKET_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid ticket ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "tickets", `${parsed.id}.json`);
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeIssueUnlocked(issue, root) {
+  const parsed = IssueSchema.parse(issue);
+  if (!ISSUE_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid issue ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "issues", `${parsed.id}.json`);
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeRoadmapUnlocked(roadmap, root) {
+  const parsed = RoadmapSchema.parse(roadmap);
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "roadmap.json");
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeRoadmap(roadmap, root) {
+  const wrapDir = resolve(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeRoadmapUnlocked(roadmap, root);
+  });
+}
+async function writeConfig(config, root) {
+  const parsed = ConfigSchema.parse(config);
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(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 = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "tickets", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    if (!options?.force) {
+      const { state } = await loadProjectUnlocked(resolve(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 = resolve(root, ".story");
+  const targetPath = join2(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 withProjectLock(root, options, handler) {
+  const absRoot = resolve(root);
+  const wrapDir = join2(absRoot, ".story");
+  await withLock(wrapDir, async () => {
+    await doRecoverTransaction(wrapDir);
+    const result = await loadProjectUnlocked(absRoot);
+    const config = result.state.config;
+    if (config.schemaVersion !== void 0 && config.schemaVersion > CURRENT_SCHEMA_VERSION) {
+      throw new ProjectLoaderError(
+        "version_mismatch",
+        `Config schemaVersion ${config.schemaVersion} exceeds max supported ${CURRENT_SCHEMA_VERSION}.`
+      );
+    }
+    if (options.strict) {
+      const integrityWarning = result.warnings.find(
+        (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+      );
+      if (integrityWarning) {
+        throw new ProjectLoaderError(
+          "project_corrupt",
+          `Strict mode: ${integrityWarning.file}: ${integrityWarning.message}`
+        );
+      }
+    }
+    await handler(result);
+  });
+}
+async function runTransactionUnlocked(root, operations) {
+  const wrapDir = resolve(root, ".story");
+  const journalPath = join2(wrapDir, ".txn.json");
+  const entries = [];
+  let commitStarted = false;
+  try {
+    for (const op of operations) {
+      if (op.op === "write") {
+        const tempPath = `${op.target}.${process.pid}.tmp`;
+        entries.push({ op: "write", target: op.target, tempPath });
+      } else {
+        entries.push({ op: "delete", target: op.target });
+      }
+    }
+    const journal = { entries, commitStarted: false };
+    await fsyncWrite(journalPath, JSON.stringify(journal, null, 2));
+    for (const op of operations) {
+      if (op.op === "write") {
+        const tempPath = `${op.target}.${process.pid}.tmp`;
+        await fsyncWrite(tempPath, op.content);
+      }
+    }
+    journal.commitStarted = true;
+    await fsyncWrite(journalPath, JSON.stringify(journal, null, 2));
+    commitStarted = true;
+    for (const entry of entries) {
+      if (entry.op === "write" && entry.tempPath) {
+        await rename(entry.tempPath, entry.target);
+      } else if (entry.op === "delete") {
+        try {
+          await unlink(entry.target);
+        } catch {
+        }
+      }
+    }
+    await unlink(journalPath);
+  } catch (err) {
+    if (!commitStarted) {
+      for (const entry of entries) {
+        if (entry.tempPath) {
+          try {
+            await unlink(entry.tempPath);
+          } catch {
+          }
+        }
+      }
+      try {
+        await unlink(journalPath);
+      } catch {
+      }
+    }
+    if (err instanceof ProjectLoaderError) throw err;
+    throw new ProjectLoaderError("io_error", "Transaction failed", err);
+  }
+}
+async function doRecoverTransaction(wrapDir) {
+  const journalPath = join2(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 && existsSync2(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 = existsSync2(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 loadProjectUnlocked(absRoot) {
+  const wrapDir = join2(absRoot, ".story");
+  const config = await loadSingletonFile("config.json", wrapDir, absRoot, ConfigSchema);
+  const roadmap = await loadSingletonFile("roadmap.json", wrapDir, absRoot, RoadmapSchema);
+  const warnings = [];
+  const tickets = await loadDirectory(join2(wrapDir, "tickets"), absRoot, TicketSchema, warnings);
+  const issues = await loadDirectory(join2(wrapDir, "issues"), absRoot, IssueSchema, warnings);
+  const handoverFilenames = await listHandovers(join2(wrapDir, "handovers"), absRoot, warnings);
+  const state = new ProjectState({ tickets, issues, roadmap, config, handoverFilenames });
+  return { state, warnings };
+}
+async function loadSingletonFile(filename, wrapDir, root, schema) {
+  const filePath = join2(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 (!existsSync2(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 = join2(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;
+}
+function sortKeysDeep(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  const obj = value;
+  const sorted = {};
+  for (const key of Object.keys(obj).sort()) {
+    sorted[key] = sortKeysDeep(obj[key]);
+  }
+  return sorted;
+}
+function serializeJSON(obj) {
+  return JSON.stringify(sortKeysDeep(obj), null, 2) + "\n";
+}
+async function atomicWrite(targetPath, content) {
+  const tempPath = `${targetPath}.${process.pid}.tmp`;
+  try {
+    await writeFile(tempPath, content, "utf-8");
+    await rename(tempPath, targetPath);
+  } catch (err) {
+    try {
+      await unlink(tempPath);
+    } catch {
+    }
+    throw new ProjectLoaderError(
+      "io_error",
+      `Failed to write ${basename(targetPath)}`,
+      err
+    );
+  }
+}
+async function fsyncWrite(filePath, content) {
+  const fh = await open(filePath, "w");
+  try {
+    await fh.writeFile(content, "utf-8");
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+}
+async function guardPath(target, root) {
+  let resolvedRoot;
+  try {
+    resolvedRoot = await realpath(root);
+  } catch {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Cannot resolve project root: ${root}`
+    );
+  }
+  const targetDir = dirname(target);
+  let resolvedDir;
+  try {
+    resolvedDir = await realpath(targetDir);
+  } catch {
+    resolvedDir = targetDir;
+  }
+  if (!resolvedDir.startsWith(resolvedRoot)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Path ${target} resolves outside project root`
+    );
+  }
+  if (existsSync2(target)) {
+    try {
+      const stats = await lstat(target);
+      if (stats.isSymbolicLink()) {
+        throw new ProjectLoaderError(
+          "invalid_input",
+          `Symlink target rejected: ${target}`
+        );
+      }
+    } catch (err) {
+      if (err instanceof ProjectLoaderError) throw err;
+    }
+  }
+}
+async function withLock(wrapDir, fn) {
+  let release;
+  try {
+    release = await lockfile.lock(wrapDir, {
+      retries: { retries: 3, minTimeout: 100, maxTimeout: 1e3 },
+      stale: 1e4,
+      lockfilePath: join2(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/core/index.ts
+init_project_root_discovery();
+init_errors();
+
+// src/core/id-allocation.ts
+init_esm_shims();
+var TICKET_NUMERIC_REGEX = /^T-(\d+)[a-z]?$/;
+var ISSUE_NUMERIC_REGEX = /^ISS-(\d+)$/;
+function nextTicketID(tickets) {
+  let max = 0;
+  for (const t of tickets) {
+    if (!TICKET_ID_REGEX.test(t.id)) continue;
+    const match = t.id.match(TICKET_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `T-${String(max + 1).padStart(3, "0")}`;
+}
+function nextIssueID(issues) {
+  let max = 0;
+  for (const i of issues) {
+    if (!ISSUE_ID_REGEX.test(i.id)) continue;
+    const match = i.id.match(ISSUE_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `ISS-${String(max + 1).padStart(3, "0")}`;
+}
+function nextOrder(phaseId, state) {
+  const tickets = state.phaseTickets(phaseId);
+  if (tickets.length === 0) return 10;
+  return tickets[tickets.length - 1].order + 10;
+}
+
+// src/core/validation.ts
+init_esm_shims();
+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/core/init.ts
+init_esm_shims();
+import { mkdir, stat as stat2 } from "fs/promises";
+import { join as join4, resolve as resolve3 } from "path";
+init_errors();
+async function initProject(root, options) {
+  const absRoot = resolve3(root);
+  const wrapDir = join4(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 mkdir(join4(wrapDir, "tickets"), { recursive: true });
+  await mkdir(join4(wrapDir, "issues"), { recursive: true });
+  await mkdir(join4(wrapDir, "handovers"), { recursive: true });
+  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: [
+      {
+        id: "p0",
+        label: "PHASE 0",
+        name: "Setup",
+        description: "Initial project setup."
+      }
+    ],
+    blockers: []
+  };
+  await writeConfig(config, absRoot);
+  await writeRoadmap(roadmap, absRoot);
+  return {
+    root: absRoot,
+    created: [
+      ".story/config.json",
+      ".story/roadmap.json",
+      ".story/tickets/",
+      ".story/issues/",
+      ".story/handovers/"
+    ]
+  };
+}
+
+// src/cli/run.ts
+init_errors();
+
+// src/cli/helpers.ts
+init_esm_shims();
+import { resolve as resolve4, relative as relative3, extname as extname3 } from "path";
+import { lstat as lstat2 } from "fs/promises";
+var CliValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CliValidationError";
+  }
+};
+function formatZodError(err) {
+  return err.issues.map((i) => i.message).join("; ");
+}
+function parseTicketId(raw) {
+  const result = TicketIdSchema.safeParse(raw);
+  if (!result.success) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid ticket ID "${raw}": ${formatZodError(result.error)}`
+    );
+  }
+  return result.data;
+}
+function parseIssueId(raw) {
+  const result = IssueIdSchema.safeParse(raw);
+  if (!result.success) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid issue ID "${raw}": ${formatZodError(result.error)}`
+    );
+  }
+  return result.data;
+}
+function parseOutputFormat(raw) {
+  if (!OUTPUT_FORMATS.includes(raw)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Invalid output format "${raw}": must be one of ${OUTPUT_FORMATS.join(", ")}`
+    );
+  }
+  return raw;
+}
+function todayISO() {
+  const d = /* @__PURE__ */ new Date();
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+function normalizeArrayOption(arr) {
+  if (!arr) return [];
+  return arr.filter((s) => s.trim() !== "");
+}
+function addFormatOption(y) {
+  return y.option("format", {
+    type: "string",
+    default: "md",
+    choices: ["json", "md"],
+    describe: "Output format: json or md"
+  });
+}
+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 = resolve4(handoversDir);
+  const resolvedCandidate = resolve4(handoversDir, raw);
+  const rel = relative3(resolvedDir, resolvedCandidate);
+  if (!rel || rel.startsWith("..") || resolve4(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/cli/run.ts
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") {
+    process.exitCode = ExitCode.OK;
+    return;
+  }
+  process.exitCode = ExitCode.USER_ERROR;
+});
+function writeOutput(text) {
+  try {
+    process.stdout.write(text + "\n");
+  } catch (err) {
+    if (err.code === "EPIPE") {
+      process.exitCode = ExitCode.OK;
+      return;
+    }
+    throw err;
+  }
+}
+function hasIntegrityWarnings(warnings) {
+  return warnings.some(
+    (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+  );
+}
+async function runReadCommand(format, handler) {
+  try {
+    const root = discoverProjectRoot();
+    if (!root) {
+      writeOutput(
+        formatError("not_found", "No .story/ project found. Run `claudestory init` first.", format)
+      );
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    const { state, warnings } = await loadProject(root);
+    const handoversDir = join5(root, ".story", "handovers");
+    const result = await handler({ state, warnings, root, handoversDir, format });
+    writeOutput(result.output);
+    let exitCode = result.exitCode ?? ExitCode.OK;
+    if (exitCode === ExitCode.OK && hasIntegrityWarnings(warnings)) {
+      exitCode = ExitCode.PARTIAL;
+    }
+    process.exitCode = exitCode;
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) {
+      writeOutput(formatError(err.code, err.message, format));
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    if (err instanceof CliValidationError) {
+      writeOutput(formatError(err.code, err.message, format));
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    writeOutput(formatError("io_error", message, format));
+    process.exitCode = ExitCode.USER_ERROR;
+  }
+}
+async function runDeleteCommand(format, force, handler) {
+  try {
+    const root = discoverProjectRoot();
+    if (!root) {
+      writeOutput(
+        formatError("not_found", "No .story/ project found. Run `claudestory init` first.", format)
+      );
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    const { state, warnings } = await loadProject(root);
+    const handoversDir = join5(root, ".story", "handovers");
+    if (!force && hasIntegrityWarnings(warnings)) {
+      writeOutput(
+        formatError(
+          "project_corrupt",
+          "Project has integrity issues. Use --force to delete anyway.",
+          format
+        )
+      );
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    const result = await handler({ state, warnings, root, handoversDir, format, force });
+    writeOutput(result.output);
+    process.exitCode = result.exitCode ?? ExitCode.OK;
+  } catch (err) {
+    if (err instanceof ProjectLoaderError) {
+      writeOutput(formatError(err.code, err.message, format));
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    if (err instanceof CliValidationError) {
+      writeOutput(formatError(err.code, err.message, format));
+      process.exitCode = ExitCode.USER_ERROR;
+      return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    writeOutput(formatError("io_error", message, format));
+    process.exitCode = ExitCode.USER_ERROR;
+  }
+}
+
+// src/cli/register.ts
+init_esm_shims();
+
+// src/cli/commands/status.ts
+init_esm_shims();
+function handleStatus(ctx) {
+  return { output: formatStatus(ctx.state, ctx.format) };
+}
+
+// src/cli/commands/validate.ts
+init_esm_shims();
+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
+init_esm_shims();
+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
+init_esm_shims();
+function handleBlockerList(ctx) {
+  return { output: formatBlockerList(ctx.state.roadmap, ctx.format) };
+}
+async function handleBlockerAdd(args, format, root) {
+  let createdBlocker;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const activeConflict = state.roadmap.blockers.find(
+      (b) => b.name === args.name && !isBlockerCleared(b)
+    );
+    if (activeConflict) {
+      throw new CliValidationError("conflict", `Active blocker "${args.name}" already exists`);
+    }
+    const blocker = {
+      name: args.name,
+      cleared: false,
+      createdDate: todayISO(),
+      clearedDate: null,
+      note: args.note ?? null
+    };
+    const newBlockers = [...state.roadmap.blockers, blocker];
+    const newRoadmap = { ...state.roadmap, blockers: newBlockers };
+    await writeRoadmapUnlocked(newRoadmap, root);
+    createdBlocker = blocker;
+  });
+  if (!createdBlocker) throw new Error("Blocker not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdBlocker), null, 2) };
+  }
+  return { output: `Added blocker: ${createdBlocker.name}` };
+}
+async function handleBlockerClear(name, note, format, root) {
+  let clearedBlocker;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const idx = state.roadmap.blockers.findIndex(
+      (b) => b.name === name && !isBlockerCleared(b)
+    );
+    if (idx < 0) {
+      throw new CliValidationError("not_found", `No active blocker named "${name}"`);
+    }
+    const existing = state.roadmap.blockers[idx];
+    const updated = {
+      ...existing,
+      cleared: true,
+      clearedDate: todayISO()
+    };
+    if (note !== void 0) {
+      updated.note = note;
+    }
+    const newBlockers = [...state.roadmap.blockers];
+    newBlockers[idx] = updated;
+    const newRoadmap = { ...state.roadmap, blockers: newBlockers };
+    await writeRoadmapUnlocked(newRoadmap, root);
+    clearedBlocker = updated;
+  });
+  if (!clearedBlocker) throw new Error("Blocker not cleared");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(clearedBlocker), null, 2) };
+  }
+  return { output: `Cleared blocker: ${clearedBlocker.name}` };
+}
+
+// src/cli/commands/ticket.ts
+init_esm_shims();
+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) };
+}
+function validatePhase(phase, ctx) {
+  if (phase !== null && !ctx.state.roadmap.phases.some((p) => p.id === phase)) {
+    throw new CliValidationError("invalid_input", `Phase "${phase}" not found in roadmap`);
+  }
+}
+function validateBlockedBy(ids, ticketId, state) {
+  for (const bid of ids) {
+    if (bid === ticketId) {
+      throw new CliValidationError("invalid_input", `Ticket cannot block itself: ${bid}`);
+    }
+    const blocker = state.ticketByID(bid);
+    if (!blocker) {
+      throw new CliValidationError("invalid_input", `Blocked-by ticket ${bid} not found`);
+    }
+    if (state.umbrellaIDs.has(bid)) {
+      throw new CliValidationError("invalid_input", `Cannot block on umbrella ticket ${bid}. Use leaf tickets instead.`);
+    }
+  }
+}
+function validateParentTicket(parentId, ticketId, state) {
+  if (parentId === ticketId) {
+    throw new CliValidationError("invalid_input", `Ticket cannot be its own parent`);
+  }
+  if (!state.ticketByID(parentId)) {
+    throw new CliValidationError("invalid_input", `Parent ticket ${parentId} not found`);
+  }
+}
+function validatePostWriteState(candidate, state, isCreate) {
+  const existingTickets = [...state.tickets];
+  if (isCreate) {
+    existingTickets.push(candidate);
+  } else {
+    const idx = existingTickets.findIndex((t) => t.id === candidate.id);
+    if (idx >= 0) existingTickets[idx] = candidate;
+    else existingTickets.push(candidate);
+  }
+  const postState = new ProjectState({
+    tickets: existingTickets,
+    issues: [...state.issues],
+    roadmap: state.roadmap,
+    config: state.config,
+    handoverFilenames: [...state.handoverFilenames]
+  });
+  const result = validateProject(postState);
+  if (!result.valid) {
+    const errors = result.findings.filter((f) => f.level === "error");
+    const msg = errors.map((f) => f.message).join("; ");
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${msg}`);
+  }
+}
+async function handleTicketCreate(args, format, root) {
+  if (!TICKET_TYPES.includes(args.type)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown ticket type "${args.type}": must be one of ${TICKET_TYPES.join(", ")}`
+    );
+  }
+  let createdTicket;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    validatePhase(args.phase, { state });
+    if (args.blockedBy.length > 0) {
+      validateBlockedBy(args.blockedBy, "", state);
+    }
+    if (args.parentTicket) {
+      validateParentTicket(args.parentTicket, "", state);
+    }
+    const id = nextTicketID(state.tickets);
+    const order = nextOrder(args.phase, state);
+    const ticket = {
+      id,
+      title: args.title,
+      description: args.description,
+      type: args.type,
+      status: "open",
+      phase: args.phase,
+      order,
+      createdDate: todayISO(),
+      completedDate: null,
+      blockedBy: args.blockedBy,
+      parentTicket: args.parentTicket ?? void 0
+    };
+    validatePostWriteState(ticket, state, true);
+    await writeTicketUnlocked(ticket, root);
+    createdTicket = ticket;
+  });
+  if (!createdTicket) throw new Error("Ticket not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdTicket), null, 2) };
+  }
+  return { output: `Created ticket ${createdTicket.id}: ${createdTicket.title}` };
+}
+async function handleTicketUpdate(id, updates, format, root) {
+  if (updates.status && !TICKET_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown ticket status "${updates.status}": must be one of ${TICKET_STATUSES.join(", ")}`
+    );
+  }
+  let updatedTicket;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.ticketByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Ticket ${id} not found`);
+    }
+    if (updates.phase !== void 0) {
+      validatePhase(updates.phase, { state });
+    }
+    if (updates.blockedBy) {
+      validateBlockedBy(updates.blockedBy, id, state);
+    }
+    if (updates.parentTicket) {
+      validateParentTicket(updates.parentTicket, id, state);
+    }
+    const ticket = { ...existing };
+    if (updates.title !== void 0) ticket.title = updates.title;
+    if (updates.description !== void 0) ticket.description = updates.description;
+    if (updates.phase !== void 0) ticket.phase = updates.phase;
+    if (updates.order !== void 0) ticket.order = updates.order;
+    if (updates.blockedBy !== void 0) ticket.blockedBy = updates.blockedBy;
+    if (updates.parentTicket !== void 0) ticket.parentTicket = updates.parentTicket === null ? void 0 : updates.parentTicket;
+    if (updates.status !== void 0 && updates.status !== existing.status) {
+      ticket.status = updates.status;
+      if (updates.status === "complete" && existing.status !== "complete") {
+        ticket.completedDate = todayISO();
+      } else if (updates.status !== "complete" && existing.status === "complete") {
+        ticket.completedDate = null;
+      }
+    }
+    validatePostWriteState(ticket, state, false);
+    await writeTicketUnlocked(ticket, root);
+    updatedTicket = ticket;
+  });
+  if (!updatedTicket) throw new Error("Ticket not updated");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(updatedTicket), null, 2) };
+  }
+  return { output: `Updated ticket ${updatedTicket.id}: ${updatedTicket.title}` };
+}
+async function handleTicketDelete(id, force, format, root) {
+  if (force) {
+    process.stderr.write(
+      `Warning: force-deleting ${id} may leave dangling references. Run \`claudestory validate\` to check.
+`
+    );
+  }
+  await deleteTicket(id, root, { force });
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope({ id, deleted: true }), null, 2) };
+  }
+  return { output: `Deleted ticket ${id}.` };
+}
+
+// src/cli/commands/issue.ts
+init_esm_shims();
+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) };
+}
+function validateRelatedTickets(ids, state) {
+  for (const tid of ids) {
+    if (!state.ticketByID(tid)) {
+      throw new CliValidationError("invalid_input", `Related ticket ${tid} not found`);
+    }
+  }
+}
+function validatePostWriteIssueState(candidate, state, isCreate) {
+  const existingIssues = [...state.issues];
+  if (isCreate) {
+    existingIssues.push(candidate);
+  } else {
+    const idx = existingIssues.findIndex((i) => i.id === candidate.id);
+    if (idx >= 0) existingIssues[idx] = candidate;
+    else existingIssues.push(candidate);
+  }
+  const postState = new ProjectState({
+    tickets: [...state.tickets],
+    issues: existingIssues,
+    roadmap: state.roadmap,
+    config: state.config,
+    handoverFilenames: [...state.handoverFilenames]
+  });
+  const result = validateProject(postState);
+  if (!result.valid) {
+    const errors = result.findings.filter((f) => f.level === "error");
+    const msg = errors.map((f) => f.message).join("; ");
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${msg}`);
+  }
+}
+async function handleIssueCreate(args, format, root) {
+  if (!ISSUE_SEVERITIES.includes(args.severity)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue severity "${args.severity}": must be one of ${ISSUE_SEVERITIES.join(", ")}`
+    );
+  }
+  let createdIssue;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    if (args.relatedTickets.length > 0) {
+      validateRelatedTickets(args.relatedTickets, state);
+    }
+    const id = nextIssueID(state.issues);
+    const issue = {
+      id,
+      title: args.title,
+      status: "open",
+      severity: args.severity,
+      components: args.components,
+      impact: args.impact,
+      resolution: null,
+      location: args.location,
+      discoveredDate: todayISO(),
+      resolvedDate: null,
+      relatedTickets: args.relatedTickets
+    };
+    validatePostWriteIssueState(issue, state, true);
+    await writeIssueUnlocked(issue, root);
+    createdIssue = issue;
+  });
+  if (!createdIssue) throw new Error("Issue not created");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(createdIssue), null, 2) };
+  }
+  return { output: `Created issue ${createdIssue.id}: ${createdIssue.title}` };
+}
+async function handleIssueUpdate(id, updates, format, root) {
+  if (updates.status && !ISSUE_STATUSES.includes(updates.status)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue status "${updates.status}": must be one of ${ISSUE_STATUSES.join(", ")}`
+    );
+  }
+  if (updates.severity && !ISSUE_SEVERITIES.includes(updates.severity)) {
+    throw new CliValidationError(
+      "invalid_input",
+      `Unknown issue severity "${updates.severity}": must be one of ${ISSUE_SEVERITIES.join(", ")}`
+    );
+  }
+  let updatedIssue;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const existing = state.issueByID(id);
+    if (!existing) {
+      throw new CliValidationError("not_found", `Issue ${id} not found`);
+    }
+    if (updates.relatedTickets) {
+      validateRelatedTickets(updates.relatedTickets, state);
+    }
+    const issue = { ...existing };
+    if (updates.title !== void 0) issue.title = updates.title;
+    if (updates.severity !== void 0) issue.severity = updates.severity;
+    if (updates.impact !== void 0) issue.impact = updates.impact;
+    if (updates.resolution !== void 0) issue.resolution = updates.resolution;
+    if (updates.components !== void 0) issue.components = updates.components;
+    if (updates.relatedTickets !== void 0) issue.relatedTickets = updates.relatedTickets;
+    if (updates.location !== void 0) issue.location = updates.location;
+    if (updates.status !== void 0 && updates.status !== existing.status) {
+      issue.status = updates.status;
+      if (updates.status === "resolved" && existing.status !== "resolved") {
+        issue.resolvedDate = todayISO();
+      } else if (updates.status !== "resolved" && existing.status === "resolved") {
+        issue.resolvedDate = null;
+      }
+    }
+    validatePostWriteIssueState(issue, state, false);
+    await writeIssueUnlocked(issue, root);
+    updatedIssue = issue;
+  });
+  if (!updatedIssue) throw new Error("Issue not updated");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(updatedIssue), null, 2) };
+  }
+  return { output: `Updated issue ${updatedIssue.id}: ${updatedIssue.title}` };
+}
+async function handleIssueDelete(id, format, root) {
+  await deleteIssue(id, root);
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope({ id, deleted: true }), null, 2) };
+  }
+  return { output: `Deleted issue ${id}.` };
+}
+
+// src/cli/commands/phase.ts
+init_esm_shims();
+import { join as join6, resolve as resolve5 } 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) };
+}
+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) };
+}
+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
+    };
+    if (args.summary !== void 0) {
+      phase.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}` };
+}
+async function handlePhaseRename(id, updates, format, root) {
+  let updatedPhase;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const idx = state.roadmap.phases.findIndex((p) => p.id === id);
+    if (idx < 0) {
+      throw new CliValidationError("not_found", `Phase "${id}" not found`);
+    }
+    const existing = state.roadmap.phases[idx];
+    const phase = { ...existing };
+    if (updates.name !== void 0) phase.name = updates.name;
+    if (updates.label !== void 0) phase.label = updates.label;
+    if (updates.description !== void 0) phase.description = updates.description;
+    if (updates.summary !== void 0) phase.summary = updates.summary;
+    const newPhases = [...state.roadmap.phases];
+    newPhases[idx] = phase;
+    const newRoadmap = { ...state.roadmap, phases: newPhases };
+    await writeRoadmapUnlocked(newRoadmap, root);
+    updatedPhase = phase;
+  });
+  if (!updatedPhase) throw new Error("Phase not updated");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(updatedPhase), null, 2) };
+  }
+  return { output: `Updated phase ${updatedPhase.id}: ${updatedPhase.name}` };
+}
+async function handlePhaseMove(id, args, format, root) {
+  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 movedPhase;
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const idx = state.roadmap.phases.findIndex((p) => p.id === id);
+    if (idx < 0) {
+      throw new CliValidationError("not_found", `Phase "${id}" not found`);
+    }
+    const phase = state.roadmap.phases[idx];
+    const newPhases = state.roadmap.phases.filter((p) => p.id !== id);
+    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);
+    movedPhase = phase;
+  });
+  if (!movedPhase) throw new Error("Phase not moved");
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope(movedPhase), null, 2) };
+  }
+  return { output: `Moved phase ${movedPhase.id}: ${movedPhase.name}` };
+}
+async function handlePhaseDelete(id, reassign, format, root) {
+  if (reassign === id) {
+    throw new CliValidationError("invalid_input", `Cannot reassign to the phase being deleted: ${id}`);
+  }
+  await withProjectLock(root, { strict: true }, async ({ state }) => {
+    const idx = state.roadmap.phases.findIndex((p) => p.id === id);
+    if (idx < 0) {
+      throw new CliValidationError("not_found", `Phase "${id}" not found`);
+    }
+    const affectedTickets = state.tickets.filter((t) => t.phase === id);
+    const affectedIssues = state.issues.filter((i) => i.phase === id);
+    if ((affectedTickets.length > 0 || affectedIssues.length > 0) && !reassign) {
+      const parts = [];
+      if (affectedTickets.length > 0) parts.push(`${affectedTickets.length} ticket(s)`);
+      if (affectedIssues.length > 0) parts.push(`${affectedIssues.length} issue(s)`);
+      throw new CliValidationError(
+        "conflict",
+        `Cannot delete phase "${id}": ${parts.join(" and ")} reference it. Use --reassign <target-phase> to move them.`
+      );
+    }
+    if (reassign) {
+      if (!state.roadmap.phases.some((p) => p.id === reassign)) {
+        throw new CliValidationError("not_found", `Reassignment target phase "${reassign}" not found`);
+      }
+      const targetLeaves = state.phaseTickets(reassign);
+      let maxOrder = targetLeaves.length > 0 ? targetLeaves[targetLeaves.length - 1].order : 0;
+      const wrapDir = resolve5(root, ".story");
+      const operations = [];
+      const sortedTickets = [...affectedTickets].sort((a, b) => a.order - b.order);
+      for (const ticket of sortedTickets) {
+        maxOrder += 10;
+        const updated = { ...ticket, phase: reassign, order: maxOrder };
+        const parsed = TicketSchema.parse(updated);
+        const content = serializeJSON(parsed);
+        const target = join6(wrapDir, "tickets", `${parsed.id}.json`);
+        operations.push({ op: "write", target, content });
+      }
+      for (const issue of affectedIssues) {
+        const updated = { ...issue, phase: reassign };
+        const parsed = IssueSchema.parse(updated);
+        const content = serializeJSON(parsed);
+        const target = join6(wrapDir, "issues", `${parsed.id}.json`);
+        operations.push({ op: "write", target, content });
+      }
+      const newPhases = state.roadmap.phases.filter((p) => p.id !== id);
+      const newRoadmap = { ...state.roadmap, phases: newPhases };
+      const parsedRoadmap = RoadmapSchema.parse(newRoadmap);
+      const roadmapContent = serializeJSON(parsedRoadmap);
+      const roadmapTarget = join6(wrapDir, "roadmap.json");
+      operations.push({ op: "write", target: roadmapTarget, content: roadmapContent });
+      await runTransactionUnlocked(root, operations);
+    } else {
+      const newPhases = state.roadmap.phases.filter((p) => p.id !== id);
+      const newRoadmap = { ...state.roadmap, phases: newPhases };
+      await writeRoadmapUnlocked(newRoadmap, root);
+    }
+  });
+  if (format === "json") {
+    return { output: JSON.stringify(successEnvelope({ id, deleted: true }), null, 2) };
+  }
+  return { output: `Deleted phase ${id}.` };
+}
+
+// src/cli/commands/init.ts
+init_esm_shims();
+import { basename as basename2 } from "path";
+init_errors();
+init_project_root_discovery();
+function registerInitCommand(yargs2) {
+  return yargs2.command(
+    "init",
+    "Scaffold a new .story/ project",
+    (y) => addFormatOption(
+      y.option("name", {
+        type: "string",
+        describe: "Project name (defaults to current directory name)"
+      }).option("force", {
+        type: "boolean",
+        default: false,
+        describe: "Overwrite existing config and roadmap"
+      }).option("type", {
+        type: "string",
+        describe: "Project type (e.g. npm, macapp)"
+      }).option("language", {
+        type: "string",
+        describe: "Primary language"
+      })
+    ),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      try {
+        const name = argv.name ?? basename2(process.cwd());
+        if (!name) {
+          throw new CliValidationError(
+            "invalid_input",
+            "Could not derive project name from current directory. Use --name to specify."
+          );
+        }
+        const parentRoot = discoverProjectRoot();
+        if (parentRoot && parentRoot !== process.cwd()) {
+          process.stderr.write(
+            `Warning: existing .story/ project found at ${parentRoot}. Creating nested project.
+`
+          );
+        }
+        const result = await initProject(process.cwd(), {
+          name,
+          force: argv.force,
+          type: argv.type,
+          language: argv.language
+        });
+        writeOutput(formatInitResult(result, format));
+        process.exitCode = ExitCode.OK;
+      } catch (err) {
+        if (err instanceof ProjectLoaderError) {
+          writeOutput(formatError(err.code, err.message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        if (err instanceof CliValidationError) {
+          writeOutput(formatError(err.code, err.message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        writeOutput(formatError("io_error", message, format));
+        process.exitCode = ExitCode.USER_ERROR;
+      }
+    }
+  );
+}
+
+// src/cli/register.ts
+function registerStatusCommand(yargs2) {
+  return yargs2.command(
+    "status",
+    "Project summary",
+    (y) => addFormatOption(y),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      await runReadCommand(format, handleStatus);
+    }
+  );
+}
+function registerValidateCommand(yargs2) {
+  return yargs2.command(
+    "validate",
+    "Reference integrity + schema checks",
+    (y) => addFormatOption(y),
+    async (argv) => {
+      const format = parseOutputFormat(argv.format);
+      await runReadCommand(format, handleValidate);
+    }
+  );
+}
+function registerHandoverCommand(yargs2) {
+  return yargs2.command(
+    "handover",
+    "Handover operations",
+    (y) => y.command(
+      "list",
+      "List handover filenames (newest first)",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handleHandoverList);
+      }
+    ).command(
+      "latest",
+      "Content of most recent handover",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handleHandoverLatest);
+      }
+    ).command(
+      "get <filename>",
+      "Content of a specific handover",
+      (y2) => addFormatOption(
+        y2.positional("filename", {
+          type: "string",
+          demandOption: true,
+          describe: "Handover filename (e.g. 2026-03-19-session.md)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const filename = argv.filename;
+        await runReadCommand(
+          format,
+          (ctx) => handleHandoverGet(filename, ctx)
+        );
+      }
+    ).demandCommand(1, "Specify a handover subcommand: list, latest, get").strict(),
+    () => {
+    }
+  );
+}
+function registerBlockerCommand(yargs2) {
+  return yargs2.command(
+    "blocker",
+    "Blocker operations",
+    (y) => y.command(
+      "list",
+      "List all blockers",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handleBlockerList);
+      }
+    ).command(
+      "add",
+      "Add a new blocker",
+      (y2) => addFormatOption(
+        y2.option("name", {
+          type: "string",
+          demandOption: true,
+          describe: "Blocker name"
+        }).option("note", {
+          type: "string",
+          describe: "Optional note"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleBlockerAdd(
+            {
+              name: argv.name,
+              note: argv.note
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "clear",
+      "Clear (resolve) a blocker",
+      (y2) => addFormatOption(
+        y2.option("name", {
+          type: "string",
+          demandOption: true,
+          describe: "Blocker name to clear"
+        }).option("note", {
+          type: "string",
+          describe: "Optional note"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleBlockerClear(
+            argv.name,
+            argv.note,
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).demandCommand(1, "Specify a blocker subcommand: list, add, clear").strict(),
+    () => {
+    }
+  );
+}
+function registerTicketCommand(yargs2) {
+  return yargs2.command(
+    "ticket",
+    "Ticket operations",
+    (y) => y.command(
+      "list",
+      "List tickets",
+      (y2) => addFormatOption(
+        y2.option("status", {
+          type: "string",
+          describe: "Filter by status"
+        }).option("phase", {
+          type: "string",
+          describe: "Filter by phase"
+        }).option("type", {
+          type: "string",
+          describe: "Filter by type"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(
+          format,
+          (ctx) => handleTicketList(
+            {
+              status: argv.status,
+              phase: argv.phase,
+              type: argv.type
+            },
+            ctx
+          )
+        );
+      }
+    ).command(
+      "get <id>",
+      "Get ticket details",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Ticket ID (e.g. T-001)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseTicketId(argv.id);
+        await runReadCommand(format, (ctx) => handleTicketGet(id, ctx));
+      }
+    ).command(
+      "next",
+      "Suggest next ticket to work on",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handleTicketNext);
+      }
+    ).command(
+      "blocked",
+      "List blocked tickets",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handleTicketBlocked);
+      }
+    ).command(
+      "create",
+      "Create a new ticket",
+      (y2) => addFormatOption(
+        y2.option("title", {
+          type: "string",
+          demandOption: true,
+          describe: "Ticket title"
+        }).option("type", {
+          type: "string",
+          demandOption: true,
+          describe: "Ticket type"
+        }).option("phase", {
+          type: "string",
+          describe: "Phase ID"
+        }).option("description", {
+          type: "string",
+          default: "",
+          describe: "Ticket description"
+        }).option("blocked-by", {
+          type: "string",
+          array: true,
+          describe: "IDs of blocking tickets"
+        }).option("parent-ticket", {
+          type: "string",
+          describe: "Parent ticket ID (makes this a sub-ticket)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleTicketCreate(
+            {
+              title: argv.title,
+              type: argv.type,
+              phase: argv.phase === "" ? null : argv.phase ?? null,
+              description: argv.description,
+              blockedBy: normalizeArrayOption(
+                argv["blocked-by"]
+              ),
+              parentTicket: argv["parent-ticket"] === "" ? null : argv["parent-ticket"] ?? null
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "update <id>",
+      "Update a ticket",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Ticket ID (e.g. T-001)"
+        }).option("status", {
+          type: "string",
+          describe: "New status"
+        }).option("title", {
+          type: "string",
+          describe: "New title"
+        }).option("phase", {
+          type: "string",
+          describe: "New phase ID"
+        }).option("order", {
+          type: "number",
+          describe: "New sort order"
+        }).option("description", {
+          type: "string",
+          describe: "New description"
+        }).option("blocked-by", {
+          type: "string",
+          array: true,
+          describe: "IDs of blocking tickets"
+        }).option("parent-ticket", {
+          type: "string",
+          describe: "Parent ticket ID"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseTicketId(argv.id);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleTicketUpdate(
+            id,
+            {
+              status: argv.status,
+              title: argv.title,
+              phase: argv.phase === "" ? null : argv.phase,
+              order: argv.order,
+              description: argv.description,
+              blockedBy: argv["blocked-by"] ? normalizeArrayOption(argv["blocked-by"]) : void 0,
+              parentTicket: argv["parent-ticket"] === "" ? null : argv["parent-ticket"]
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "delete <id>",
+      "Delete a ticket",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Ticket ID (e.g. T-001)"
+        }).option("force", {
+          type: "boolean",
+          default: false,
+          describe: "Force delete even with integrity issues"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseTicketId(argv.id);
+        const force = argv.force;
+        await runDeleteCommand(
+          format,
+          force,
+          async (ctx) => handleTicketDelete(id, force, format, ctx.root)
+        );
+      }
+    ).demandCommand(
+      1,
+      "Specify a ticket subcommand: list, get, next, blocked, create, update, delete"
+    ).strict(),
+    () => {
+    }
+  );
+}
+function registerIssueCommand(yargs2) {
+  return yargs2.command(
+    "issue",
+    "Issue operations",
+    (y) => y.command(
+      "list",
+      "List issues",
+      (y2) => addFormatOption(
+        y2.option("status", {
+          type: "string",
+          describe: "Filter by status"
+        }).option("severity", {
+          type: "string",
+          describe: "Filter by severity"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(
+          format,
+          (ctx) => handleIssueList(
+            {
+              status: argv.status,
+              severity: argv.severity
+            },
+            ctx
+          )
+        );
+      }
+    ).command(
+      "get <id>",
+      "Get issue details",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Issue ID (e.g. ISS-001)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseIssueId(argv.id);
+        await runReadCommand(format, (ctx) => handleIssueGet(id, ctx));
+      }
+    ).command(
+      "create",
+      "Create a new issue",
+      (y2) => addFormatOption(
+        y2.option("title", {
+          type: "string",
+          demandOption: true,
+          describe: "Issue title"
+        }).option("severity", {
+          type: "string",
+          demandOption: true,
+          describe: "Issue severity"
+        }).option("impact", {
+          type: "string",
+          demandOption: true,
+          describe: "Impact description"
+        }).option("components", {
+          type: "string",
+          array: true,
+          describe: "Affected components"
+        }).option("related-tickets", {
+          type: "string",
+          array: true,
+          describe: "Related ticket IDs"
+        }).option("location", {
+          type: "string",
+          array: true,
+          describe: "File locations"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleIssueCreate(
+            {
+              title: argv.title,
+              severity: argv.severity,
+              impact: argv.impact,
+              components: normalizeArrayOption(
+                argv.components
+              ),
+              relatedTickets: normalizeArrayOption(
+                argv["related-tickets"]
+              ),
+              location: normalizeArrayOption(
+                argv.location
+              )
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "update <id>",
+      "Update an issue",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Issue ID (e.g. ISS-001)"
+        }).option("status", {
+          type: "string",
+          describe: "New status"
+        }).option("title", {
+          type: "string",
+          describe: "New title"
+        }).option("severity", {
+          type: "string",
+          describe: "New severity"
+        }).option("impact", {
+          type: "string",
+          describe: "New impact description"
+        }).option("resolution", {
+          type: "string",
+          describe: "Resolution description"
+        }).option("components", {
+          type: "string",
+          array: true,
+          describe: "Affected components"
+        }).option("related-tickets", {
+          type: "string",
+          array: true,
+          describe: "Related ticket IDs"
+        }).option("location", {
+          type: "string",
+          array: true,
+          describe: "File locations"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseIssueId(argv.id);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handleIssueUpdate(
+            id,
+            {
+              status: argv.status,
+              title: argv.title,
+              severity: argv.severity,
+              impact: argv.impact,
+              resolution: argv.resolution === "" ? null : argv.resolution,
+              components: argv.components ? normalizeArrayOption(argv.components) : void 0,
+              relatedTickets: argv["related-tickets"] ? normalizeArrayOption(argv["related-tickets"]) : void 0,
+              location: argv.location ? normalizeArrayOption(argv.location) : void 0
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "delete <id>",
+      "Delete an issue",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Issue ID (e.g. ISS-001)"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = parseIssueId(argv.id);
+        await runDeleteCommand(
+          format,
+          false,
+          async (ctx) => handleIssueDelete(id, format, ctx.root)
+        );
+      }
+    ).demandCommand(
+      1,
+      "Specify an issue subcommand: list, get, create, update, delete"
+    ).strict(),
+    () => {
+    }
+  );
+}
+function registerPhaseCommand(yargs2) {
+  return yargs2.command(
+    "phase",
+    "Phase operations",
+    (y) => y.command(
+      "list",
+      "List all phases",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handlePhaseList);
+      }
+    ).command(
+      "current",
+      "Show current phase",
+      (y2) => addFormatOption(y2),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        await runReadCommand(format, handlePhaseCurrent);
+      }
+    ).command(
+      "tickets",
+      "List tickets in a phase",
+      (y2) => addFormatOption(
+        y2.option("phase", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase ID"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const phaseId = argv.phase;
+        await runReadCommand(
+          format,
+          (ctx) => handlePhaseTickets(phaseId, ctx)
+        );
+      }
+    ).command(
+      "create",
+      "Create a new phase",
+      (y2) => addFormatOption(
+        y2.option("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase ID (lowercase alphanumeric with hyphens)"
+        }).option("name", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase name"
+        }).option("label", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase label (e.g. PHASE 5)"
+        }).option("description", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase description"
+        }).option("summary", {
+          type: "string",
+          describe: "Short summary"
+        }).option("after", {
+          type: "string",
+          describe: "Insert after this phase ID"
+        }).option("at-start", {
+          type: "boolean",
+          default: false,
+          describe: "Insert at the beginning"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handlePhaseCreate(
+            {
+              id: argv.id,
+              name: argv.name,
+              label: argv.label,
+              description: argv.description,
+              summary: argv.summary,
+              after: argv.after,
+              atStart: argv.atStart
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "rename <id>",
+      "Rename/update phase metadata",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase ID"
+        }).option("name", {
+          type: "string",
+          describe: "New name"
+        }).option("label", {
+          type: "string",
+          describe: "New label"
+        }).option("description", {
+          type: "string",
+          describe: "New description"
+        }).option("summary", {
+          type: "string",
+          describe: "New summary"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = argv.id;
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handlePhaseRename(
+            id,
+            {
+              name: argv.name,
+              label: argv.label,
+              description: argv.description,
+              summary: argv.summary
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "move <id>",
+      "Move a phase to a new position",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase ID to move"
+        }).option("after", {
+          type: "string",
+          describe: "Place after this phase ID"
+        }).option("at-start", {
+          type: "boolean",
+          default: false,
+          describe: "Move to the beginning"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = argv.id;
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handlePhaseMove(
+            id,
+            {
+              after: argv.after,
+              atStart: argv.atStart
+            },
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).command(
+      "delete <id>",
+      "Delete a phase",
+      (y2) => addFormatOption(
+        y2.positional("id", {
+          type: "string",
+          demandOption: true,
+          describe: "Phase ID to delete"
+        }).option("reassign", {
+          type: "string",
+          describe: "Move tickets/issues to this phase"
+        })
+      ),
+      async (argv) => {
+        const format = parseOutputFormat(argv.format);
+        const id = argv.id;
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        if (!root) {
+          writeOutput(
+            formatError(
+              "not_found",
+              "No .story/ project found.",
+              format
+            )
+          );
+          process.exitCode = ExitCode.USER_ERROR;
+          return;
+        }
+        try {
+          const result = await handlePhaseDelete(
+            id,
+            argv.reassign,
+            format,
+            root
+          );
+          writeOutput(result.output);
+          process.exitCode = result.exitCode ?? ExitCode.OK;
+        } catch (err) {
+          if (err instanceof CliValidationError) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const { ProjectLoaderError: ProjectLoaderError2 } = await Promise.resolve().then(() => (init_errors(), errors_exports));
+          if (err instanceof ProjectLoaderError2) {
+            writeOutput(formatError(err.code, err.message, format));
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          const message = err instanceof Error ? err.message : String(err);
+          writeOutput(formatError("io_error", message, format));
+          process.exitCode = ExitCode.USER_ERROR;
+        }
+      }
+    ).demandCommand(
+      1,
+      "Specify a phase subcommand: list, current, tickets, create, rename, move, delete"
+    ).strict(),
+    () => {
+    }
+  );
+}
+
+// src/cli/index.ts
+var version = "0.1.0";
+var HANDLED_ERROR = /* @__PURE__ */ Symbol("HANDLED_ERROR");
+var rawArgs = hideBin(process.argv);
+function sniffFormat(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--format" && args[i + 1] === "json") return "json";
+    if (args[i]?.startsWith("--format=") && args[i].slice("--format=".length) === "json") return "json";
+  }
+  return "md";
+}
+var errorFormat = sniffFormat(rawArgs);
+var cli = yargs(rawArgs).scriptName("claudestory").version(version).strict().demandCommand(1, "Specify a command. Run with --help for available commands.").help().fail((msg, err) => {
+  if (err) throw err;
+  writeOutput(formatError("invalid_input", msg ?? "Unknown error", errorFormat));
+  process.exitCode = ExitCode.USER_ERROR;
+  throw HANDLED_ERROR;
+});
+cli = registerInitCommand(cli);
+cli = registerStatusCommand(cli);
+cli = registerPhaseCommand(cli);
+cli = registerTicketCommand(cli);
+cli = registerIssueCommand(cli);
+cli = registerHandoverCommand(cli);
+cli = registerBlockerCommand(cli);
+cli = registerValidateCommand(cli);
+await cli.parseAsync().catch((err) => {
+  if (err === HANDLED_ERROR) return;
+  const message = err instanceof Error ? err.message : String(err);
+  writeOutput(formatError("io_error", message, errorFormat));
+  process.exitCode = ExitCode.USER_ERROR;
+});