@anthropologies/claudestory 0.1.0

package/dist/index.js

@@ -0,0 +1,1812 @@
+// src/models/ticket.ts
+import { z as z2 } from "zod";
+
+// src/models/types.ts
+import { z } from "zod";
+var TICKET_ID_REGEX = /^T-\d+[a-z]?$/;
+var ISSUE_ID_REGEX = /^ISS-\d+$/;
+var TICKET_STATUSES = ["open", "inprogress", "complete"];
+var TICKET_TYPES = ["task", "feature", "chore"];
+var ISSUE_STATUSES = ["open", "inprogress", "resolved"];
+var ISSUE_SEVERITIES = ["critical", "high", "medium", "low"];
+var OUTPUT_FORMATS = ["json", "md"];
+var ERROR_CODES = [
+  "not_found",
+  "validation_failed",
+  "io_error",
+  "project_corrupt",
+  "invalid_input",
+  "conflict",
+  "version_mismatch"
+];
+var DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+var DateSchema = z.string().regex(DATE_REGEX, "Date must be YYYY-MM-DD").refine(
+  (val) => {
+    const d = /* @__PURE__ */ new Date(val + "T00:00:00Z");
+    return !isNaN(d.getTime()) && d.toISOString().startsWith(val);
+  },
+  { message: "Invalid calendar date" }
+);
+var TicketIdSchema = z.string().regex(TICKET_ID_REGEX, "Ticket ID must match T-NNN or T-NNNx");
+var IssueIdSchema = z.string().regex(ISSUE_ID_REGEX, "Issue ID must match ISS-NNN");
+
+// src/models/ticket.ts
+var TicketSchema = z2.object({
+  id: TicketIdSchema,
+  title: z2.string().min(1),
+  description: z2.string(),
+  type: z2.enum(TICKET_TYPES),
+  status: z2.enum(TICKET_STATUSES),
+  phase: z2.string().nullable(),
+  order: z2.number().int(),
+  createdDate: DateSchema,
+  completedDate: DateSchema.nullable(),
+  blockedBy: z2.array(TicketIdSchema),
+  parentTicket: TicketIdSchema.nullable().optional(),
+  // Attribution fields — unused in v1, baked in to avoid future migration
+  createdBy: z2.string().nullable().optional(),
+  assignedTo: z2.string().nullable().optional(),
+  lastModifiedBy: z2.string().nullable().optional()
+}).passthrough();
+
+// src/models/issue.ts
+import { z as z3 } from "zod";
+var IssueSchema = z3.object({
+  id: IssueIdSchema,
+  title: z3.string().min(1),
+  status: z3.enum(ISSUE_STATUSES),
+  severity: z3.enum(ISSUE_SEVERITIES),
+  components: z3.array(z3.string()),
+  impact: z3.string(),
+  resolution: z3.string().nullable(),
+  location: z3.array(z3.string()),
+  discoveredDate: DateSchema,
+  resolvedDate: DateSchema.nullable(),
+  relatedTickets: z3.array(TicketIdSchema),
+  // Optional fields — older issues may omit these
+  order: z3.number().int().optional(),
+  phase: z3.string().nullable().optional(),
+  // Attribution fields — unused in v1
+  createdBy: z3.string().nullable().optional(),
+  assignedTo: z3.string().nullable().optional(),
+  lastModifiedBy: z3.string().nullable().optional()
+}).passthrough();
+
+// src/models/roadmap.ts
+import { z as z4 } from "zod";
+var BlockerSchema = z4.object({
+  name: z4.string().min(1),
+  // Legacy format (pre-T-082)
+  cleared: z4.boolean().optional(),
+  // New date-based format (T-082 migration)
+  createdDate: DateSchema.optional(),
+  clearedDate: DateSchema.nullable().optional(),
+  // Present in all current data but optional for future minimal blockers
+  note: z4.string().nullable().optional()
+}).passthrough();
+var PhaseSchema = z4.object({
+  id: z4.string().min(1),
+  label: z4.string(),
+  name: z4.string(),
+  description: z4.string(),
+  summary: z4.string().optional()
+}).passthrough();
+var RoadmapSchema = z4.object({
+  title: z4.string(),
+  date: DateSchema,
+  phases: z4.array(PhaseSchema),
+  blockers: z4.array(BlockerSchema)
+}).passthrough();
+
+// src/models/config.ts
+import { z as z5 } from "zod";
+var FeaturesSchema = z5.object({
+  tickets: z5.boolean(),
+  issues: z5.boolean(),
+  handovers: z5.boolean(),
+  roadmap: z5.boolean(),
+  reviews: z5.boolean()
+}).passthrough();
+var ConfigSchema = z5.object({
+  version: z5.number().int().min(1),
+  schemaVersion: z5.number().int().optional(),
+  project: z5.string().min(1),
+  type: z5.string(),
+  language: z5.string(),
+  features: FeaturesSchema
+}).passthrough();
+
+// src/core/project-state.ts
+var ProjectState = class _ProjectState {
+  // --- Public raw inputs (readonly) ---
+  tickets;
+  issues;
+  roadmap;
+  config;
+  handoverFilenames;
+  // --- Derived (public readonly) ---
+  umbrellaIDs;
+  leafTickets;
+  // --- Derived (private) ---
+  leafTicketsByPhase;
+  childrenByParent;
+  reverseBlocksMap;
+  ticketsByID;
+  issuesByID;
+  // --- Counts ---
+  totalTicketCount;
+  openTicketCount;
+  completeTicketCount;
+  openIssueCount;
+  issuesBySeverity;
+  constructor(input) {
+    this.tickets = input.tickets;
+    this.issues = input.issues;
+    this.roadmap = input.roadmap;
+    this.config = input.config;
+    this.handoverFilenames = input.handoverFilenames;
+    const parentIDs = /* @__PURE__ */ new Set();
+    for (const t of input.tickets) {
+      if (t.parentTicket != null) {
+        parentIDs.add(t.parentTicket);
+      }
+    }
+    this.umbrellaIDs = parentIDs;
+    this.leafTickets = input.tickets.filter((t) => !parentIDs.has(t.id));
+    const byPhase = /* @__PURE__ */ new Map();
+    for (const t of this.leafTickets) {
+      const phase = t.phase;
+      const arr = byPhase.get(phase);
+      if (arr) {
+        arr.push(t);
+      } else {
+        byPhase.set(phase, [t]);
+      }
+    }
+    for (const [, arr] of byPhase) {
+      arr.sort((a, b) => a.order - b.order);
+    }
+    this.leafTicketsByPhase = byPhase;
+    const children = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      if (t.parentTicket != null) {
+        const arr = children.get(t.parentTicket);
+        if (arr) {
+          arr.push(t);
+        } else {
+          children.set(t.parentTicket, [t]);
+        }
+      }
+    }
+    this.childrenByParent = children;
+    const reverseBlocks = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      for (const blockerID of t.blockedBy) {
+        const arr = reverseBlocks.get(blockerID);
+        if (arr) {
+          arr.push(t);
+        } else {
+          reverseBlocks.set(blockerID, [t]);
+        }
+      }
+    }
+    this.reverseBlocksMap = reverseBlocks;
+    const tByID = /* @__PURE__ */ new Map();
+    for (const t of input.tickets) {
+      if (!tByID.has(t.id)) {
+        tByID.set(t.id, t);
+      }
+    }
+    this.ticketsByID = tByID;
+    const iByID = /* @__PURE__ */ new Map();
+    for (const i of input.issues) {
+      iByID.set(i.id, i);
+    }
+    this.issuesByID = iByID;
+    this.totalTicketCount = input.tickets.length;
+    this.openTicketCount = input.tickets.filter(
+      (t) => t.status !== "complete"
+    ).length;
+    this.completeTicketCount = input.tickets.filter(
+      (t) => t.status === "complete"
+    ).length;
+    this.openIssueCount = input.issues.filter(
+      (i) => i.status === "open"
+    ).length;
+    const bySev = /* @__PURE__ */ new Map();
+    for (const i of input.issues) {
+      if (i.status === "open") {
+        bySev.set(i.severity, (bySev.get(i.severity) ?? 0) + 1);
+      }
+    }
+    this.issuesBySeverity = bySev;
+  }
+  // --- Query Methods ---
+  isUmbrella(ticket) {
+    return this.umbrellaIDs.has(ticket.id);
+  }
+  phaseTickets(phaseId) {
+    return this.leafTicketsByPhase.get(phaseId) ?? [];
+  }
+  /** Phase status derived from leaf tickets only. Umbrella stored status is ignored. */
+  phaseStatus(phaseId) {
+    const leaves = this.phaseTickets(phaseId);
+    return _ProjectState.aggregateStatus(leaves);
+  }
+  umbrellaChildren(ticketId) {
+    return this.childrenByParent.get(ticketId) ?? [];
+  }
+  /** Umbrella status derived from descendant leaf tickets (recursive traversal). */
+  umbrellaStatus(ticketId) {
+    const visited = /* @__PURE__ */ new Set();
+    const leaves = this.descendantLeaves(ticketId, visited);
+    return _ProjectState.aggregateStatus(leaves);
+  }
+  reverseBlocks(ticketId) {
+    return this.reverseBlocksMap.get(ticketId) ?? [];
+  }
+  /**
+   * A ticket is blocked if any blockedBy reference points to a non-complete ticket.
+   * Unknown blocker IDs treated as blocked (conservative — unknown dependency = assume not cleared).
+   */
+  isBlocked(ticket) {
+    if (ticket.blockedBy.length === 0) return false;
+    return ticket.blockedBy.some((blockerID) => {
+      const blocker = this.ticketsByID.get(blockerID);
+      if (!blocker) return true;
+      return blocker.status !== "complete";
+    });
+  }
+  get blockedCount() {
+    return this.tickets.filter((t) => this.isBlocked(t)).length;
+  }
+  ticketByID(id) {
+    return this.ticketsByID.get(id);
+  }
+  issueByID(id) {
+    return this.issuesByID.get(id);
+  }
+  // --- Deletion Safety ---
+  /** IDs of tickets that list `ticketId` in their blockedBy. */
+  ticketsBlocking(ticketId) {
+    return (this.reverseBlocksMap.get(ticketId) ?? []).map((t) => t.id);
+  }
+  /** IDs of tickets that have `ticketId` as their parentTicket. */
+  childrenOf(ticketId) {
+    return (this.childrenByParent.get(ticketId) ?? []).map((t) => t.id);
+  }
+  /** IDs of issues that reference `ticketId` in relatedTickets. */
+  issuesReferencing(ticketId) {
+    return this.issues.filter((i) => i.relatedTickets.includes(ticketId)).map((i) => i.id);
+  }
+  // --- Private ---
+  /**
+   * Recursively collects all descendant leaf tickets of an umbrella.
+   * Uses a visited set to guard against cycles in malformed data.
+   */
+  descendantLeaves(ticketId, visited) {
+    if (visited.has(ticketId)) return [];
+    visited.add(ticketId);
+    const directChildren = this.childrenByParent.get(ticketId) ?? [];
+    const leaves = [];
+    for (const child of directChildren) {
+      if (this.umbrellaIDs.has(child.id)) {
+        leaves.push(...this.descendantLeaves(child.id, visited));
+      } else {
+        leaves.push(child);
+      }
+    }
+    return leaves;
+  }
+  /**
+   * Shared aggregation logic for phase and umbrella status.
+   * - all complete → complete
+   * - any inprogress OR any complete (but not all) → inprogress
+   * - else → notstarted (nothing started)
+   */
+  static aggregateStatus(tickets) {
+    if (tickets.length === 0) return "notstarted";
+    const allComplete = tickets.every((t) => t.status === "complete");
+    if (allComplete) return "complete";
+    const anyProgress = tickets.some((t) => t.status === "inprogress");
+    const anyComplete = tickets.some((t) => t.status === "complete");
+    if (anyProgress || anyComplete) return "inprogress";
+    return "notstarted";
+  }
+};
+
+// src/core/project-loader.ts
+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/core/errors.ts
+var CURRENT_SCHEMA_VERSION = 1;
+var ProjectLoaderError = class extends Error {
+  constructor(code, message, cause) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+  name = "ProjectLoaderError";
+};
+var INTEGRITY_WARNING_TYPES = [
+  "parse_error",
+  "schema_error",
+  "duplicate_id"
+];
+
+// src/core/handover-parser.ts
+import { readdir, readFile } from "fs/promises";
+import { existsSync } 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");
+}
+function extractHandoverDate(filename) {
+  const match = filename.match(HANDOVER_DATE_REGEX);
+  return match ? match[0] : null;
+}
+
+// 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 writeTicket(ticket, root) {
+  const wrapDir = resolve(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeTicketUnlocked(ticket, root);
+  });
+}
+async function writeIssueUnlocked(issue, root) {
+  const parsed = IssueSchema.parse(issue);
+  if (!ISSUE_ID_REGEX.test(parsed.id)) {
+    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 writeIssue(issue, root) {
+  const wrapDir = resolve(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeIssueUnlocked(issue, root);
+  });
+}
+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 runTransaction(root, operations) {
+  const wrapDir = resolve(root, ".story");
+  await withLock(wrapDir, async () => {
+    await runTransactionUnlocked(root, operations);
+  });
+}
+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/project-root-discovery.ts
+import { existsSync as existsSync3 } from "fs";
+import { resolve as resolve2, dirname as dirname2, join as join3 } from "path";
+var ENV_VAR = "CLAUDESTORY_PROJECT_ROOT";
+var CONFIG_PATH = ".story/config.json";
+function discoverProjectRoot(startDir) {
+  const envRoot = process.env[ENV_VAR];
+  if (envRoot) {
+    const resolved = 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;
+}
+
+// src/core/queries.ts
+function nextTicket(state) {
+  const phases = state.roadmap.phases;
+  if (phases.length === 0 || state.leafTickets.length === 0) {
+    return { kind: "empty_project" };
+  }
+  let allPhasesComplete = true;
+  for (const phase of phases) {
+    const leaves = state.phaseTickets(phase.id);
+    if (leaves.length === 0) continue;
+    const status = state.phaseStatus(phase.id);
+    if (status === "complete") continue;
+    allPhasesComplete = false;
+    const incompleteLeaves = leaves.filter((t) => t.status !== "complete");
+    const candidate = incompleteLeaves.find((t) => !state.isBlocked(t));
+    if (candidate) {
+      const impact = ticketsUnblockedBy(candidate.id, state);
+      const progress = candidate.parentTicket ? umbrellaProgress(candidate.parentTicket, state) : null;
+      return {
+        kind: "found",
+        ticket: candidate,
+        unblockImpact: { ticketId: candidate.id, wouldUnblock: impact },
+        umbrellaProgress: progress
+      };
+    }
+    return {
+      kind: "all_blocked",
+      phaseId: phase.id,
+      blockedCount: incompleteLeaves.length
+    };
+  }
+  if (allPhasesComplete) {
+    return { kind: "all_complete" };
+  }
+  return { kind: "empty_project" };
+}
+function blockedTickets(state) {
+  return state.leafTickets.filter(
+    (t) => t.status !== "complete" && state.isBlocked(t)
+  );
+}
+function ticketsUnblockedBy(ticketId, state) {
+  const blocked = state.reverseBlocks(ticketId);
+  return blocked.filter((t) => {
+    if (t.status === "complete") return false;
+    return t.blockedBy.every((bid) => {
+      if (bid === ticketId) return true;
+      const blocker = state.ticketByID(bid);
+      if (!blocker) return false;
+      return blocker.status === "complete";
+    });
+  });
+}
+function umbrellaProgress(ticketId, state) {
+  if (!state.umbrellaIDs.has(ticketId)) return null;
+  const leaves = collectDescendantLeaves(ticketId, state, /* @__PURE__ */ new Set());
+  const complete = leaves.filter((t) => t.status === "complete").length;
+  return {
+    total: leaves.length,
+    complete,
+    status: state.umbrellaStatus(ticketId)
+  };
+}
+function currentPhase(state) {
+  for (const phase of state.roadmap.phases) {
+    const leaves = state.phaseTickets(phase.id);
+    if (leaves.length === 0) continue;
+    if (state.phaseStatus(phase.id) !== "complete") return phase;
+  }
+  return null;
+}
+function phasesWithStatus(state) {
+  return state.roadmap.phases.map((phase) => ({
+    phase,
+    status: state.phaseStatus(phase.id),
+    leafCount: state.phaseTickets(phase.id).length
+  }));
+}
+function isBlockerCleared(blocker) {
+  if (blocker.cleared === true) return true;
+  if (blocker.clearedDate != null) return true;
+  return false;
+}
+function collectDescendantLeaves(ticketId, state, visited) {
+  if (visited.has(ticketId)) return [];
+  visited.add(ticketId);
+  const children = state.umbrellaChildren(ticketId);
+  const leaves = [];
+  for (const child of children) {
+    if (state.umbrellaIDs.has(child.id)) {
+      leaves.push(...collectDescendantLeaves(child.id, state, visited));
+    } else {
+      leaves.push(child);
+    }
+  }
+  return leaves;
+}
+
+// src/core/id-allocation.ts
+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
+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
+import { mkdir, stat as stat2 } from "fs/promises";
+import { join as join4, resolve as resolve3 } from "path";
+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/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 partialEnvelope(data, warnings) {
+  return {
+    version: 1,
+    data,
+    warnings: warnings.map((w) => ({
+      type: w.type,
+      file: w.file,
+      message: w.message
+    })),
+    partial: true
+  };
+}
+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}`;
+}
+export {
+  BlockerSchema,
+  CURRENT_SCHEMA_VERSION,
+  ConfigSchema,
+  DATE_REGEX,
+  DateSchema,
+  ERROR_CODES,
+  ExitCode,
+  FeaturesSchema,
+  INTEGRITY_WARNING_TYPES,
+  ISSUE_ID_REGEX,
+  ISSUE_SEVERITIES,
+  ISSUE_STATUSES,
+  IssueIdSchema,
+  IssueSchema,
+  OUTPUT_FORMATS,
+  PhaseSchema,
+  ProjectLoaderError,
+  ProjectState,
+  RoadmapSchema,
+  TICKET_ID_REGEX,
+  TICKET_STATUSES,
+  TICKET_TYPES,
+  TicketIdSchema,
+  TicketSchema,
+  blockedTickets,
+  currentPhase,
+  deleteIssue,
+  deleteTicket,
+  discoverProjectRoot,
+  errorEnvelope,
+  escapeMarkdownInline,
+  extractHandoverDate,
+  fencedBlock,
+  formatBlockedTickets,
+  formatBlockerList,
+  formatError,
+  formatHandoverContent,
+  formatHandoverList,
+  formatInitResult,
+  formatIssue,
+  formatIssueList,
+  formatNextTicketOutcome,
+  formatPhaseList,
+  formatPhaseTickets,
+  formatStatus,
+  formatTicket,
+  formatTicketList,
+  formatValidation,
+  initProject,
+  isBlockerCleared,
+  listHandovers,
+  loadProject,
+  mergeValidation,
+  nextIssueID,
+  nextOrder,
+  nextTicket,
+  nextTicketID,
+  partialEnvelope,
+  phasesWithStatus,
+  readHandover,
+  runTransaction,
+  runTransactionUnlocked,
+  serializeJSON,
+  sortKeysDeep,
+  successEnvelope,
+  ticketsUnblockedBy,
+  umbrellaProgress,
+  validateProject,
+  withProjectLock,
+  writeConfig,
+  writeIssue,
+  writeIssueUnlocked,
+  writeRoadmap,
+  writeRoadmapUnlocked,
+  writeTicket,
+  writeTicketUnlocked
+};