@anthropologies/claudestory 0.1.34 → 0.1.36

package/dist/cli.js

@@ -1761,7 +1761,7 @@ function fencedBlock(content, lang) {
 ${content}
 ${fence}`;
 }
-function formatStatus(state, format) {
+function formatStatus(state, format, activeSessions = []) {
   const phases = phasesWithStatus(state);
   const data = {
     project: state.config.project,
@@ -1781,7 +1781,8 @@ function formatStatus(state, format) {
       name: p.phase.name,
       status: p.status,
       leafCount: p.leafCount
-    }))
+    })),
+    ...activeSessions.length > 0 ? { activeSessions } : {}
   };
   if (format === "json") {
     return JSON.stringify(successEnvelope(data), null, 2);
@@ -1803,6 +1804,15 @@ function formatStatus(state, format) {
     const summary = p.phase.summary ?? truncate(p.phase.description, 80);
     lines.push(`${indicator} **${escapeMarkdownInline(p.phase.name)}** (${p.leafCount} tickets) \u2014 ${escapeMarkdownInline(summary)}`);
   }
+  if (activeSessions.length > 0) {
+    lines.push("");
+    lines.push("## Active Sessions");
+    lines.push("");
+    for (const s of activeSessions) {
+      const ticket = s.ticketId ? `${s.ticketId}: ${escapeMarkdownInline(s.ticketTitle ?? "")}` : "no ticket";
+      lines.push(`- ${s.sessionId.slice(0, 8)}: ${s.state} -- ${ticket} (${s.mode} mode)`);
+    }
+  }
   if (state.isEmptyScaffold) {
     lines.push("");
     lines.push(EMPTY_SCAFFOLD_HEADING);
@@ -2691,15 +2701,71 @@ var init_output_formatter = __esm({
   }
 });
 
+// src/core/session-scan.ts
+import { readdirSync, readFileSync } from "fs";
+import { join as join4 } from "path";
+function scanActiveSessions(root) {
+  const sessDir = join4(root, ".story", "sessions");
+  let entries;
+  try {
+    entries = readdirSync(sessDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const statePath2 = join4(sessDir, entry.name, "state.json");
+    let raw;
+    try {
+      raw = readFileSync(statePath2, "utf-8");
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (parsed.status !== "active") continue;
+    if (parsed.state === "SESSION_END") continue;
+    const lease = parsed.lease;
+    if (lease?.expiresAt) {
+      const expires = new Date(lease.expiresAt).getTime();
+      if (!Number.isNaN(expires) && expires <= Date.now()) continue;
+    } else {
+      continue;
+    }
+    const ticket = parsed.ticket;
+    results.push({
+      sessionId: parsed.sessionId ?? entry.name,
+      state: parsed.state ?? "unknown",
+      mode: parsed.mode ?? "auto",
+      ticketId: ticket?.id ?? null,
+      ticketTitle: ticket?.title ?? null
+    });
+  }
+  return results;
+}
+var init_session_scan = __esm({
+  "src/core/session-scan.ts"() {
+    "use strict";
+    init_esm_shims();
+  }
+});
+
 // src/cli/commands/status.ts
 function handleStatus(ctx) {
-  return { output: formatStatus(ctx.state, ctx.format) };
+  const sessions = scanActiveSessions(ctx.root);
+  return { output: formatStatus(ctx.state, ctx.format, sessions) };
 }
 var init_status = __esm({
   "src/cli/commands/status.ts"() {
     "use strict";
     init_esm_shims();
     init_output_formatter();
+    init_session_scan();
   }
 });
 
@@ -2787,6 +2853,7 @@ function validateProject(state) {
       }
     }
   }
+  detectSupersedesCycles(state, findings);
   const phaseIDCounts = /* @__PURE__ */ new Map();
   for (const p of state.roadmap.phases) {
     phaseIDCounts.set(p.id, (phaseIDCounts.get(p.id) ?? 0) + 1);
@@ -2991,6 +3058,33 @@ function dfsBlocked(id, state, visited, inStack, findings) {
   inStack.delete(id);
   visited.add(id);
 }
+function detectSupersedesCycles(state, findings) {
+  const visited = /* @__PURE__ */ new Set();
+  const inStack = /* @__PURE__ */ new Set();
+  for (const l of state.lessons) {
+    if (l.supersedes == null || visited.has(l.id)) continue;
+    dfsSupersedesChain(l.id, state, visited, inStack, findings);
+  }
+}
+function dfsSupersedesChain(id, state, visited, inStack, findings) {
+  if (inStack.has(id)) {
+    findings.push({
+      level: "error",
+      code: "supersedes_cycle",
+      message: `Cycle detected in supersedes chain involving ${id}.`,
+      entity: id
+    });
+    return;
+  }
+  if (visited.has(id)) return;
+  inStack.add(id);
+  const lesson = state.lessonByID(id);
+  if (lesson?.supersedes && lesson.supersedes !== id) {
+    dfsSupersedesChain(lesson.supersedes, state, visited, inStack, findings);
+  }
+  inStack.delete(id);
+  visited.add(id);
+}
 var init_validation = __esm({
   "src/core/validation.ts"() {
     "use strict";
@@ -3027,7 +3121,7 @@ __export(handover_exports, {
 });
 import { existsSync as existsSync4 } from "fs";
 import { mkdir as mkdir2 } from "fs/promises";
-import { join as join4, resolve as resolve4 } from "path";
+import { join as join5, resolve as resolve4 } from "path";
 function handleHandoverList(ctx) {
   return { output: formatHandoverList(ctx.state.handoverFilenames, ctx.format) };
 }
@@ -3112,15 +3206,15 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
   let filename;
   await withProjectLock(root, { strict: false }, async () => {
     const absRoot = resolve4(root);
-    const handoversDir = join4(absRoot, ".story", "handovers");
+    const handoversDir = join5(absRoot, ".story", "handovers");
     await mkdir2(handoversDir, { recursive: true });
-    const wrapDir = join4(absRoot, ".story");
+    const wrapDir = join5(absRoot, ".story");
     const datePrefix = `${date}-`;
     const seqRegex = new RegExp(`^${date}-(\\d{2})-`);
     let maxSeq = 0;
-    const { readdirSync: readdirSync2 } = await import("fs");
+    const { readdirSync: readdirSync5 } = await import("fs");
     try {
-      for (const f of readdirSync2(handoversDir)) {
+      for (const f of readdirSync5(handoversDir)) {
         const m = f.match(seqRegex);
         if (m) {
           const n = parseInt(m[1], 10);
@@ -3137,7 +3231,7 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
       );
     }
     let candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
-    let candidatePath = join4(handoversDir, candidate);
+    let candidatePath = join5(handoversDir, candidate);
     while (existsSync4(candidatePath)) {
       nextSeq++;
       if (nextSeq > 99) {
@@ -3147,7 +3241,7 @@ async function handleHandoverCreate(content, slugRaw, format, root) {
         );
       }
       candidate = `${date}-${String(nextSeq).padStart(2, "0")}-${slug}.md`;
-      candidatePath = join4(handoversDir, candidate);
+      candidatePath = join5(handoversDir, candidate);
     }
     await parseHandoverFilename(candidate, handoversDir);
     await guardPath(candidatePath, wrapDir);
@@ -3382,7 +3476,20 @@ function validateParentTicket(parentId, ticketId, state) {
     throw new CliValidationError("invalid_input", `Parent ticket ${parentId} not found`);
   }
 }
+function buildErrorMultiset(findings) {
+  const counts = /* @__PURE__ */ new Map();
+  const messages = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    if (f.level !== "error") continue;
+    const key = `${f.code}|${f.entity ?? ""}|${f.message}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+    messages.set(key, f.message);
+  }
+  return { counts, messages };
+}
 function validatePostWriteState(candidate, state, isCreate) {
+  const preResult = validateProject(state);
+  const { counts: preErrors } = buildErrorMultiset(preResult.findings);
   const existingTickets = [...state.tickets];
   if (isCreate) {
     existingTickets.push(candidate);
@@ -3399,11 +3506,17 @@ function validatePostWriteState(candidate, state, isCreate) {
     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}`);
+  const postResult = validateProject(postState);
+  const { counts: postErrors, messages: postMessages } = buildErrorMultiset(postResult.findings);
+  const newErrors = [];
+  for (const [key, postCount] of postErrors) {
+    const preCount = preErrors.get(key) ?? 0;
+    if (postCount > preCount) {
+      newErrors.push(postMessages.get(key) ?? key);
+    }
+  }
+  if (newErrors.length > 0) {
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${newErrors.join("; ")}`);
   }
 }
 async function handleTicketCreate(args, format, root) {
@@ -3587,7 +3700,20 @@ function validateRelatedTickets(ids, state) {
     }
   }
 }
+function buildErrorMultiset2(findings) {
+  const counts = /* @__PURE__ */ new Map();
+  const messages = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    if (f.level !== "error") continue;
+    const key = `${f.code}|${f.entity ?? ""}|${f.message}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+    messages.set(key, f.message);
+  }
+  return { counts, messages };
+}
 function validatePostWriteIssueState(candidate, state, isCreate) {
+  const preResult = validateProject(state);
+  const { counts: preErrors } = buildErrorMultiset2(preResult.findings);
   const existingIssues = [...state.issues];
   if (isCreate) {
     existingIssues.push(candidate);
@@ -3604,11 +3730,17 @@ function validatePostWriteIssueState(candidate, state, isCreate) {
     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}`);
+  const postResult = validateProject(postState);
+  const { counts: postErrors, messages: postMessages } = buildErrorMultiset2(postResult.findings);
+  const newErrors = [];
+  for (const [key, postCount] of postErrors) {
+    const preCount = preErrors.get(key) ?? 0;
+    if (postCount > preCount) {
+      newErrors.push(postMessages.get(key) ?? key);
+    }
+  }
+  if (newErrors.length > 0) {
+    throw new CliValidationError("validation_failed", `Write would create invalid state: ${newErrors.join("; ")}`);
   }
 }
 async function handleIssueCreate(args, format, root) {
@@ -3742,11 +3874,11 @@ __export(snapshot_exports, {
 });
 import { readdir as readdir3, readFile as readFile3, mkdir as mkdir3, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync5 } from "fs";
-import { join as join5, resolve as resolve5 } from "path";
+import { join as join6, resolve as resolve5 } from "path";
 import { z as z8 } from "zod";
 async function saveSnapshot(root, loadResult) {
   const absRoot = resolve5(root);
-  const snapshotsDir = join5(absRoot, ".story", "snapshots");
+  const snapshotsDir = join6(absRoot, ".story", "snapshots");
   await mkdir3(snapshotsDir, { recursive: true });
   const { state, warnings } = loadResult;
   const now = /* @__PURE__ */ new Date();
@@ -3771,8 +3903,8 @@ async function saveSnapshot(root, loadResult) {
     } : {}
   };
   const json = JSON.stringify(snapshot, null, 2) + "\n";
-  const targetPath = join5(snapshotsDir, filename);
-  const wrapDir = join5(absRoot, ".story");
+  const targetPath = join6(snapshotsDir, filename);
+  const wrapDir = join6(absRoot, ".story");
   await guardPath(targetPath, wrapDir);
   await atomicWrite(targetPath, json);
   const pruned = await pruneSnapshots(snapshotsDir);
@@ -3780,13 +3912,13 @@ async function saveSnapshot(root, loadResult) {
   return { filename, retained: entries.length, pruned };
 }
 async function loadLatestSnapshot(root) {
-  const snapshotsDir = join5(resolve5(root), ".story", "snapshots");
+  const snapshotsDir = join6(resolve5(root), ".story", "snapshots");
   if (!existsSync5(snapshotsDir)) return null;
   const files = await listSnapshotFiles(snapshotsDir);
   if (files.length === 0) return null;
   for (const filename of files) {
     try {
-      const content = await readFile3(join5(snapshotsDir, filename), "utf-8");
+      const content = await readFile3(join6(snapshotsDir, filename), "utf-8");
       const parsed = JSON.parse(content);
       const snapshot = SnapshotV1Schema.parse(parsed);
       return { snapshot, filename };
@@ -4030,7 +4162,7 @@ async function pruneSnapshots(dir) {
   const toRemove = files.slice(MAX_SNAPSHOTS);
   for (const f of toRemove) {
     try {
-      await unlink2(join5(dir, f));
+      await unlink2(join6(dir, f));
     } catch {
     }
   }
@@ -4449,7 +4581,7 @@ var init_lesson2 = __esm({
 });
 
 // src/core/recommend.ts
-function recommend(state, count) {
+function recommend(state, count, options) {
   const effectiveCount = Math.max(1, Math.min(10, count));
   const dedup = /* @__PURE__ */ new Map();
   const phaseIndex = buildPhaseIndex(state);
@@ -4461,7 +4593,8 @@ function recommend(state, count) {
     () => generateNearCompleteUmbrellas(state, phaseIndex),
     () => generatePhaseMomentum(state),
     () => generateQuickWins(state, phaseIndex),
-    () => generateOpenIssues(state)
+    () => generateOpenIssues(state),
+    () => generateDebtTrend(state, options)
   ];
   for (const gen of generators) {
     for (const rec of gen()) {
@@ -4471,6 +4604,7 @@ function recommend(state, count) {
       }
     }
   }
+  applyHandoverBoost(state, dedup, options);
   const curPhase = currentPhase(state);
   const curPhaseIdx = curPhase ? phaseIndex.get(curPhase.id) ?? 0 : 0;
   for (const [id, rec] of dedup) {
@@ -4660,7 +4794,76 @@ function sortByPhaseAndOrder(tickets, phaseIndex) {
     return a.order - b.order;
   });
 }
-var SEVERITY_RANK, PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY, CATEGORY_PRIORITY;
+function applyHandoverBoost(state, dedup, options) {
+  if (!options?.latestHandoverContent) return;
+  const content = options.latestHandoverContent;
+  let actionableIds = extractTicketIdsFromActionableSections(content);
+  if (actionableIds.size === 0) {
+    const allIds = new Set(content.match(TICKET_ID_RE) ?? []);
+    for (const id of allIds) {
+      const ticket = state.ticketByID(id);
+      if (ticket && ticket.status !== "complete" && ticket.status !== "inprogress") {
+        actionableIds.add(id);
+      }
+    }
+  }
+  for (const id of actionableIds) {
+    const ticket = state.ticketByID(id);
+    if (!ticket || ticket.status === "complete") continue;
+    const existing = dedup.get(id);
+    if (existing) {
+      dedup.set(id, {
+        ...existing,
+        score: existing.score + HANDOVER_BOOST,
+        reason: existing.reason + " (handover context)"
+      });
+    } else {
+      dedup.set(id, {
+        id,
+        kind: "ticket",
+        title: ticket.title,
+        category: "handover_context",
+        reason: "Referenced in latest handover",
+        score: HANDOVER_BASE_SCORE
+      });
+    }
+  }
+}
+function extractTicketIdsFromActionableSections(content) {
+  const ids = /* @__PURE__ */ new Set();
+  const lines = content.split("\n");
+  let inActionable = false;
+  for (const line of lines) {
+    if (/^#+\s/.test(line)) {
+      inActionable = ACTIONABLE_HEADING_RE.test(line);
+    }
+    if (inActionable) {
+      const matches = line.match(TICKET_ID_RE);
+      if (matches) for (const m of matches) ids.add(m);
+    }
+  }
+  return ids;
+}
+function generateDebtTrend(state, options) {
+  if (options?.previousOpenIssueCount == null) return [];
+  const currentOpen = state.issues.filter((i) => i.status !== "resolved").length;
+  const previous = options.previousOpenIssueCount;
+  if (previous <= 0) return [];
+  const growth = (currentOpen - previous) / previous;
+  const absolute = currentOpen - previous;
+  if (growth > DEBT_GROWTH_THRESHOLD && absolute >= DEBT_ABSOLUTE_MINIMUM) {
+    return [{
+      id: "DEBT_TREND",
+      kind: "action",
+      title: "Issue debt growing",
+      category: "debt_trend",
+      reason: `Open issues grew from ${previous} to ${currentOpen} (+${Math.round(growth * 100)}%). Consider triaging or resolving issues before adding features.`,
+      score: DEBT_TREND_SCORE
+    }];
+  }
+  return [];
+}
+var SEVERITY_RANK, PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY, CATEGORY_PRIORITY, TICKET_ID_RE, ACTIONABLE_HEADING_RE, HANDOVER_BOOST, HANDOVER_BASE_SCORE, DEBT_TREND_SCORE, DEBT_GROWTH_THRESHOLD, DEBT_ABSOLUTE_MINIMUM;
 var init_recommend = __esm({
   "src/core/recommend.ts"() {
     "use strict";
@@ -4682,17 +4885,52 @@ var init_recommend = __esm({
       high_impact_unblock: 4,
       near_complete_umbrella: 5,
       phase_momentum: 6,
-      quick_win: 7,
-      open_issue: 8
+      debt_trend: 7,
+      quick_win: 8,
+      handover_context: 9,
+      open_issue: 10
     };
+    TICKET_ID_RE = /\bT-\d{3}[a-z]?\b/g;
+    ACTIONABLE_HEADING_RE = /^#+\s.*(next|open|remaining|todo|blocked)/im;
+    HANDOVER_BOOST = 50;
+    HANDOVER_BASE_SCORE = 350;
+    DEBT_TREND_SCORE = 450;
+    DEBT_GROWTH_THRESHOLD = 0.25;
+    DEBT_ABSOLUTE_MINIMUM = 2;
   }
 });
 
 // src/cli/commands/recommend.ts
+import { readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { join as join7 } from "path";
 function handleRecommend(ctx, count) {
-  const result = recommend(ctx.state, count);
+  const options = buildRecommendOptions(ctx);
+  const result = recommend(ctx.state, count, options);
   return { output: formatRecommendations(result, ctx.state, ctx.format) };
 }
+function buildRecommendOptions(ctx) {
+  const opts = {};
+  try {
+    const files = readdirSync2(ctx.handoversDir).filter((f) => f.endsWith(".md")).sort();
+    if (files.length > 0) {
+      opts.latestHandoverContent = readFileSync2(join7(ctx.handoversDir, files[files.length - 1]), "utf-8");
+    }
+  } catch {
+  }
+  try {
+    const snapshotsDir = join7(ctx.root, ".story", "snapshots");
+    const snapFiles = readdirSync2(snapshotsDir).filter((f) => f.endsWith(".json")).sort();
+    if (snapFiles.length > 0) {
+      const raw = readFileSync2(join7(snapshotsDir, snapFiles[snapFiles.length - 1]), "utf-8");
+      const snap = JSON.parse(raw);
+      if (snap.issues) {
+        opts.previousOpenIssueCount = snap.issues.filter((i) => i.status !== "resolved").length;
+      }
+    }
+  } catch {
+  }
+  return opts;
+}
 var init_recommend2 = __esm({
   "src/cli/commands/recommend.ts"() {
     "use strict";
@@ -5242,27 +5480,27 @@ __export(session_exports, {
 import { randomUUID } from "crypto";
 import {
   mkdirSync,
-  readdirSync,
-  readFileSync,
+  readdirSync as readdirSync3,
+  readFileSync as readFileSync3,
   writeFileSync,
   renameSync,
   unlinkSync,
   existsSync as existsSync6,
   rmSync
 } from "fs";
-import { join as join6 } from "path";
+import { join as join8 } from "path";
 import lockfile2 from "proper-lockfile";
 function sessionsRoot(root) {
-  return join6(root, ".story", SESSIONS_DIR);
+  return join8(root, ".story", SESSIONS_DIR);
 }
 function sessionDir(root, sessionId) {
-  return join6(sessionsRoot(root), sessionId);
+  return join8(sessionsRoot(root), sessionId);
 }
 function statePath(dir) {
-  return join6(dir, "state.json");
+  return join8(dir, "state.json");
 }
 function eventsPath(dir) {
-  return join6(dir, "events.log");
+  return join8(dir, "events.log");
 }
 function createSession(root, recipe, workspaceId, configOverrides) {
   const id = randomUUID();
@@ -5318,7 +5556,7 @@ function readSession(dir) {
   const path2 = statePath(dir);
   let raw;
   try {
-    raw = readFileSync(path2, "utf-8");
+    raw = readFileSync3(path2, "utf-8");
   } catch {
     return null;
   }
@@ -5361,7 +5599,7 @@ function readEvents(dir) {
   const path2 = eventsPath(dir);
   let raw;
   try {
-    raw = readFileSync(path2, "utf-8");
+    raw = readFileSync3(path2, "utf-8");
   } catch {
     return { events: [], malformedCount: 0 };
   }
@@ -5418,7 +5656,7 @@ function findActiveSessionFull(root) {
   const sessDir = sessionsRoot(root);
   let entries;
   try {
-    entries = readdirSync(sessDir, { withFileTypes: true });
+    entries = readdirSync3(sessDir, { withFileTypes: true });
   } catch {
     return null;
   }
@@ -5432,7 +5670,7 @@ function findActiveSessionFull(root) {
   let bestGuideCall = 0;
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const dir = join6(sessDir, entry.name);
+    const dir = join8(sessDir, entry.name);
     const session = readSession(dir);
     if (!session) continue;
     if (session.status !== "active") continue;
@@ -5455,7 +5693,7 @@ function findStaleSessions(root) {
   const sessDir = sessionsRoot(root);
   let entries;
   try {
-    entries = readdirSync(sessDir, { withFileTypes: true });
+    entries = readdirSync3(sessDir, { withFileTypes: true });
   } catch {
     return [];
   }
@@ -5468,7 +5706,7 @@ function findStaleSessions(root) {
   const results = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const dir = join6(sessDir, entry.name);
+    const dir = join8(sessDir, entry.name);
     const session = readSession(dir);
     if (!session) continue;
     if (session.status !== "active") continue;
@@ -5524,7 +5762,7 @@ function findResumableSession(root) {
   const sessDir = sessionsRoot(root);
   let entries;
   try {
-    entries = readdirSync(sessDir, { withFileTypes: true });
+    entries = readdirSync3(sessDir, { withFileTypes: true });
   } catch {
     return null;
   }
@@ -5539,7 +5777,7 @@ function findResumableSession(root) {
   let bestPreparedAt = 0;
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const dir = join6(sessDir, entry.name);
+    const dir = join8(sessDir, entry.name);
     const session = readSession(dir);
     if (!session) continue;
     if (session.status !== "active") continue;
@@ -5563,7 +5801,7 @@ async function withSessionLock(root, fn) {
     release = await lockfile2.lock(sessDir, {
       retries: { retries: 3, minTimeout: 100, maxTimeout: 1e3 },
       stale: 3e4,
-      lockfilePath: join6(sessDir, ".lock")
+      lockfilePath: join8(sessDir, ".lock")
     });
     return await fn();
   } finally {
@@ -5879,16 +6117,16 @@ var init_git_inspector = __esm({
 });
 
 // src/autonomous/recipes/loader.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { join as join7, dirname as dirname3 } from "path";
+import { readFileSync as readFileSync4 } from "fs";
+import { join as join9, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 function loadRecipe(recipeName) {
   if (!/^[A-Za-z0-9_-]+$/.test(recipeName)) {
     throw new Error(`Invalid recipe name: ${recipeName}`);
   }
-  const recipesDir = join7(dirname3(fileURLToPath2(import.meta.url)), "..", "recipes");
-  const path2 = join7(recipesDir, `${recipeName}.json`);
-  const raw = readFileSync2(path2, "utf-8");
+  const recipesDir = join9(dirname3(fileURLToPath2(import.meta.url)), "..", "recipes");
+  const path2 = join9(recipesDir, `${recipeName}.json`);
+  const raw = readFileSync4(path2, "utf-8");
   return JSON.parse(raw);
 }
 function resolveRecipe(recipeName, projectOverrides) {
@@ -6164,7 +6402,7 @@ var init_types2 = __esm({
 
 // src/autonomous/stages/pick-ticket.ts
 import { existsSync as existsSync7, unlinkSync as unlinkSync2 } from "fs";
-import { join as join8 } from "path";
+import { join as join10 } from "path";
 var PickTicketStage;
 var init_pick_ticket = __esm({
   "src/autonomous/stages/pick-ticket.ts"() {
@@ -6219,7 +6457,7 @@ var init_pick_ticket = __esm({
             return { action: "retry", instruction: `Ticket ${ticketId} is ${ticket.status} \u2014 pick an open ticket.` };
           }
         }
-        const planPath = join8(ctx.dir, "plan.md");
+        const planPath = join10(ctx.dir, "plan.md");
         try {
           if (existsSync7(planPath)) unlinkSync2(planPath);
         } catch {
@@ -6259,11 +6497,11 @@ ${ticket.description}` : "",
 });
 
 // src/autonomous/stages/plan.ts
-import { existsSync as existsSync8, readFileSync as readFileSync3 } from "fs";
-import { join as join9 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
+import { join as join11 } from "path";
 function readFileSafe(path2) {
   try {
-    return readFileSync3(path2, "utf-8");
+    return readFileSync5(path2, "utf-8");
   } catch {
     return "";
   }
@@ -6304,7 +6542,7 @@ var init_plan = __esm({
         };
       }
       async report(ctx, _report) {
-        const planPath = join9(ctx.dir, "plan.md");
+        const planPath = join11(ctx.dir, "plan.md");
         if (!existsSync8(planPath)) {
           return { action: "retry", instruction: `Plan file not found at ${planPath}. Write your plan there and call me again.`, reminders: ["Save plan to .story/sessions/<id>/plan.md"] };
         }
@@ -6550,7 +6788,8 @@ var init_implement = __esm({
           reminders: [
             "Follow the plan exactly. Do NOT deviate without re-planning.",
             "Do NOT ask the user for confirmation.",
-            "If you discover pre-existing bugs, failing tests not caused by your changes, or other out-of-scope problems, file them as issues using claudestory_issue_create. Do not fix them inline."
+            "If you discover pre-existing bugs, failing tests not caused by your changes, or other out-of-scope problems, file them as issues using claudestory_issue_create. Do not fix them inline.",
+            "Track which files you create or modify. Only these files should be staged at commit time."
           ],
           transitionedFrom: ctx.state.previousState ?? void 0
         };
@@ -7247,10 +7486,10 @@ var init_finalize = __esm({
             "Code review passed. Time to commit.",
             "",
             ctx.state.ticket ? `1. Update ticket ${ctx.state.ticket.id} status to "complete" in .story/` : "",
-            "2. Stage all changed files (code + .story/ changes)",
+            "2. Stage only the files you created or modified for this ticket (code + .story/ changes). Do NOT use `git add -A` or `git add .`",
             '3. Call me with completedAction: "files_staged"'
           ].filter(Boolean).join("\n"),
-          reminders: ["Stage both code changes and .story/ ticket update in the same commit."],
+          reminders: ["Stage both code changes and .story/ ticket update in the same commit. Only stage files related to this ticket."],
           transitionedFrom: ctx.state.previousState ?? void 0
         };
       }
@@ -7754,7 +7993,7 @@ Impact: ${nextIssue.impact}` : ""}` : `Fix issue ${next}.`,
 
 // src/autonomous/stages/handover.ts
 import { writeFileSync as writeFileSync2 } from "fs";
-import { join as join10 } from "path";
+import { join as join12 } from "path";
 var HandoverStage;
 var init_handover2 = __esm({
   "src/autonomous/stages/handover.ts"() {
@@ -7791,7 +8030,7 @@ var init_handover2 = __esm({
         } catch {
           handoverFailed = true;
           try {
-            const fallbackPath = join10(ctx.dir, "handover-fallback.md");
+            const fallbackPath = join12(ctx.dir, "handover-fallback.md");
             writeFileSync2(fallbackPath, content, "utf-8");
           } catch {
           }
@@ -7875,8 +8114,32 @@ var init_stages = __esm({
 });
 
 // src/autonomous/guide.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
-import { join as join11 } from "path";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync3, readdirSync as readdirSync4 } from "fs";
+import { join as join13 } from "path";
+function buildGuideRecommendOptions(root) {
+  const opts = {};
+  try {
+    const handoversDir = join13(root, ".story", "handovers");
+    const files = readdirSync4(handoversDir, "utf-8").filter((f) => f.endsWith(".md")).sort();
+    if (files.length > 0) {
+      opts.latestHandoverContent = readFileSync6(join13(handoversDir, files[files.length - 1]), "utf-8");
+    }
+  } catch {
+  }
+  try {
+    const snapshotsDir = join13(root, ".story", "snapshots");
+    const snapFiles = readdirSync4(snapshotsDir, "utf-8").filter((f) => f.endsWith(".json")).sort();
+    if (snapFiles.length > 0) {
+      const raw = readFileSync6(join13(snapshotsDir, snapFiles[snapFiles.length - 1]), "utf-8");
+      const snap = JSON.parse(raw);
+      if (snap.issues) {
+        opts.previousOpenIssueCount = snap.issues.filter((i) => i.status !== "resolved").length;
+      }
+    }
+  } catch {
+  }
+  return opts;
+}
 async function recoverPendingMutation(dir, state, root) {
   const mutation = state.pendingProjectMutation;
   if (!mutation || typeof mutation !== "object") return state;
@@ -8248,7 +8511,7 @@ Staged: ${stagedResult.data.join(", ")}`
       }
     }
     const { state: projectState, warnings } = await loadProject(root);
-    const handoversDir = join11(root, ".story", "handovers");
+    const handoversDir = join13(root, ".story", "handovers");
     const ctx = { state: projectState, warnings, root, handoversDir, format: "md" };
     let handoverText = "";
     try {
@@ -8265,7 +8528,7 @@ Staged: ${stagedResult.data.join(", ")}`
       }
     } catch {
     }
-    const rulesText = readFileSafe2(join11(root, "RULES.md"));
+    const rulesText = readFileSafe2(join13(root, "RULES.md"));
     const lessonDigest = buildLessonDigest(projectState.lessons);
     const digestParts = [
       handoverText ? `## Recent Handovers
@@ -8281,7 +8544,7 @@ ${rulesText}` : "",
     ].filter(Boolean);
     const digest = digestParts.join("\n\n---\n\n");
     try {
-      writeFileSync3(join11(dir, "context-digest.md"), digest, "utf-8");
+      writeFileSync3(join13(dir, "context-digest.md"), digest, "utf-8");
     } catch {
     }
     if (mode !== "auto" && args.ticketId) {
@@ -8300,6 +8563,18 @@ ${rulesText}` : "",
           return guideError(new Error(`Ticket ${args.ticketId} is blocked by: ${ticket.blockedBy.join(", ")}.`));
         }
       }
+      if (mode !== "review") {
+        const claimId = ticket.claimedBySession;
+        if (claimId && typeof claimId === "string" && claimId !== session.sessionId) {
+          const claimingSession = findSessionById(root, claimId);
+          if (claimingSession && claimingSession.state.status === "active" && !isLeaseExpired(claimingSession.state)) {
+            deleteSession(root, session.sessionId);
+            return guideError(new Error(
+              `Ticket ${args.ticketId} is claimed by active session ${claimId}. Wait for it to finish or stop it with "claudestory session stop ${claimId}".`
+            ));
+          }
+        }
+      }
       let entryState;
       if (mode === "review") {
         entryState = "CODE_REVIEW";
@@ -8395,7 +8670,8 @@ ${ticket.description}` : "",
     } else {
       candidatesText = "No tickets found.";
     }
-    const recResult = recommend(projectState, 5);
+    const guideRecOptions = buildGuideRecommendOptions(root);
+    const recResult = recommend(projectState, 5, guideRecOptions);
     let recsText = "";
     if (recResult.recommendations.length > 0) {
       const ticketRecs = recResult.recommendations.filter((r) => r.kind === "ticket");
@@ -8620,26 +8896,7 @@ async function handleResume(root, args) {
     ));
   }
   if (expectedHead && headResult.data.hash !== expectedHead) {
-    const recoveryMapping = {
-      PICK_TICKET: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
-      COMPLETE: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
-      HANDOVER: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
-      PLAN: { state: "PLAN", resetPlan: true, resetCode: false },
-      IMPLEMENT: { state: "PLAN", resetPlan: true, resetCode: false },
-      WRITE_TESTS: { state: "PLAN", resetPlan: true, resetCode: false },
-      // T-139: baseline stale after HEAD change
-      VERIFY: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
-      // T-131: reviewed code stale after HEAD drift
-      PLAN_REVIEW: { state: "PLAN", resetPlan: true, resetCode: true },
-      TEST: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
-      // T-128: tests invalidated by HEAD change
-      CODE_REVIEW: { state: "PLAN", resetPlan: true, resetCode: true },
-      FINALIZE: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
-      LESSON_CAPTURE: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
-      ISSUE_SWEEP: { state: "PICK_TICKET", resetPlan: false, resetCode: false }
-      // T-128: post-complete, restart sweep
-    };
-    const mapping = recoveryMapping[resumeState] ?? { state: "PICK_TICKET", resetPlan: false, resetCode: false };
+    const mapping = RECOVERY_MAPPING[resumeState] ?? { state: "PICK_TICKET", resetPlan: false, resetCode: false };
     const recoveryReviews = {
       plan: mapping.resetPlan ? [] : info.state.reviews.plan,
       code: mapping.resetCode ? [] : info.state.reviews.code
@@ -8987,12 +9244,12 @@ function guideError(err) {
 }
 function readFileSafe2(path2) {
   try {
-    return readFileSync4(path2, "utf-8");
+    return readFileSync6(path2, "utf-8");
   } catch {
     return "";
   }
 }
-var SEVERITY_MAP, workspaceLocks, MAX_AUTO_ADVANCE_DEPTH;
+var RECOVERY_MAPPING, SEVERITY_MAP, workspaceLocks, MAX_AUTO_ADVANCE_DEPTH;
 var init_guide = __esm({
   "src/autonomous/guide.ts"() {
     "use strict";
@@ -9014,6 +9271,22 @@ var init_guide = __esm({
     init_queries();
     init_recommend();
     init_handover();
+    RECOVERY_MAPPING = {
+      PICK_TICKET: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
+      COMPLETE: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
+      HANDOVER: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
+      PLAN: { state: "PLAN", resetPlan: true, resetCode: false },
+      IMPLEMENT: { state: "PLAN", resetPlan: true, resetCode: false },
+      WRITE_TESTS: { state: "PLAN", resetPlan: true, resetCode: false },
+      BUILD: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
+      VERIFY: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
+      PLAN_REVIEW: { state: "PLAN", resetPlan: true, resetCode: true },
+      TEST: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
+      CODE_REVIEW: { state: "PLAN", resetPlan: true, resetCode: true },
+      FINALIZE: { state: "IMPLEMENT", resetPlan: false, resetCode: true },
+      LESSON_CAPTURE: { state: "PICK_TICKET", resetPlan: false, resetCode: false },
+      ISSUE_SWEEP: { state: "PICK_TICKET", resetPlan: false, resetCode: false }
+    };
     SEVERITY_MAP = {
       critical: "critical",
       major: "high",
@@ -9222,8 +9495,8 @@ var init_session_report_formatter = __esm({
 });
 
 // src/cli/commands/session-report.ts
-import { readFileSync as readFileSync5, existsSync as existsSync10 } from "fs";
-import { join as join12 } from "path";
+import { readFileSync as readFileSync7, existsSync as existsSync10 } from "fs";
+import { join as join14 } from "path";
 async function handleSessionReport(sessionId, root, format = "md") {
   if (!UUID_REGEX.test(sessionId)) {
     return {
@@ -9242,7 +9515,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
       isError: true
     };
   }
-  const statePath2 = join12(dir, "state.json");
+  const statePath2 = join14(dir, "state.json");
   if (!existsSync10(statePath2)) {
     return {
       output: `Error: Session ${sessionId} corrupt \u2014 state.json missing.`,
@@ -9252,7 +9525,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
     };
   }
   try {
-    const rawJson = JSON.parse(readFileSync5(statePath2, "utf-8"));
+    const rawJson = JSON.parse(readFileSync7(statePath2, "utf-8"));
     if (rawJson && typeof rawJson === "object" && "schemaVersion" in rawJson && rawJson.schemaVersion !== CURRENT_SESSION_SCHEMA_VERSION) {
       return {
         output: `Error: Session ${sessionId} \u2014 unsupported session schema version ${rawJson.schemaVersion}.`,
@@ -9281,7 +9554,7 @@ async function handleSessionReport(sessionId, root, format = "md") {
   const events = readEvents(dir);
   let planContent = null;
   try {
-    planContent = readFileSync5(join12(dir, "plan.md"), "utf-8");
+    planContent = readFileSync7(join14(dir, "plan.md"), "utf-8");
   } catch {
   }
   let gitLog = null;
@@ -9310,7 +9583,7 @@ var init_session_report = __esm({
 });
 
 // src/cli/commands/phase.ts
-import { join as join13, resolve as resolve6 } from "path";
+import { join as join15, resolve as resolve6 } from "path";
 function validatePhaseId(id) {
   if (id.length > PHASE_ID_MAX_LENGTH) {
     throw new CliValidationError("invalid_input", `Phase ID "${id}" exceeds ${PHASE_ID_MAX_LENGTH} characters`);
@@ -9499,21 +9772,21 @@ async function handlePhaseDelete(id, reassign, format, root) {
         const updated = { ...ticket, phase: reassign, order: maxOrder };
         const parsed = TicketSchema.parse(updated);
         const content = serializeJSON(parsed);
-        const target = join13(wrapDir, "tickets", `${parsed.id}.json`);
+        const target = join15(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 = join13(wrapDir, "issues", `${parsed.id}.json`);
+        const target = join15(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 = join13(wrapDir, "roadmap.json");
+      const roadmapTarget = join15(wrapDir, "roadmap.json");
       operations.push({ op: "write", target: roadmapTarget, content: roadmapContent });
       await runTransactionUnlocked(root, operations);
     } else {
@@ -9546,14 +9819,14 @@ var init_phase = __esm({
 
 // src/mcp/tools.ts
 import { z as z10 } from "zod";
-import { join as join14 } from "path";
+import { join as join16 } from "path";
 function formatMcpError(code, message) {
   return `[${code}] ${message}`;
 }
 async function runMcpReadTool(pinnedRoot, handler) {
   try {
     const { state, warnings } = await loadProject(pinnedRoot);
-    const handoversDir = join14(pinnedRoot, ".story", "handovers");
+    const handoversDir = join16(pinnedRoot, ".story", "handovers");
     const ctx = { state, warnings, root: pinnedRoot, handoversDir, format: "md" };
     const result = await handler(ctx);
     if (result.errorCode && INFRASTRUCTURE_ERROR_CODES.includes(result.errorCode)) {
@@ -10140,10 +10413,10 @@ var init_tools = __esm({
 
 // src/core/init.ts
 import { mkdir as mkdir4, stat as stat2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
-import { join as join15, resolve as resolve7 } from "path";
+import { join as join17, resolve as resolve7 } from "path";
 async function initProject(root, options) {
   const absRoot = resolve7(root);
-  const wrapDir = join15(absRoot, ".story");
+  const wrapDir = join17(absRoot, ".story");
   let exists = false;
   try {
     const s = await stat2(wrapDir);
@@ -10163,11 +10436,11 @@ async function initProject(root, options) {
       ".story/ already exists. Use --force to overwrite config and roadmap."
     );
   }
-  await mkdir4(join15(wrapDir, "tickets"), { recursive: true });
-  await mkdir4(join15(wrapDir, "issues"), { recursive: true });
-  await mkdir4(join15(wrapDir, "handovers"), { recursive: true });
-  await mkdir4(join15(wrapDir, "notes"), { recursive: true });
-  await mkdir4(join15(wrapDir, "lessons"), { recursive: true });
+  await mkdir4(join17(wrapDir, "tickets"), { recursive: true });
+  await mkdir4(join17(wrapDir, "issues"), { recursive: true });
+  await mkdir4(join17(wrapDir, "handovers"), { recursive: true });
+  await mkdir4(join17(wrapDir, "notes"), { recursive: true });
+  await mkdir4(join17(wrapDir, "lessons"), { recursive: true });
   const created = [
     ".story/config.json",
     ".story/roadmap.json",
@@ -10207,7 +10480,7 @@ async function initProject(root, options) {
   };
   await writeConfig(config, absRoot);
   await writeRoadmap(roadmap, absRoot);
-  const gitignorePath = join15(wrapDir, ".gitignore");
+  const gitignorePath = join17(wrapDir, ".gitignore");
   await ensureGitignoreEntries(gitignorePath, STORY_GITIGNORE_ENTRIES);
   const warnings = [];
   if (options.force && exists) {
@@ -10255,7 +10528,7 @@ var init_init = __esm({
 // src/mcp/index.ts
 var mcp_exports = {};
 import { realpathSync as realpathSync2, existsSync as existsSync11 } from "fs";
-import { resolve as resolve8, join as join16, isAbsolute } from "path";
+import { resolve as resolve8, join as join18, isAbsolute } from "path";
 import { z as z11 } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -10270,7 +10543,7 @@ function tryDiscoverRoot() {
     const resolved = resolve8(envRoot);
     try {
       const canonical = realpathSync2(resolved);
-      if (existsSync11(join16(canonical, CONFIG_PATH2))) {
+      if (existsSync11(join18(canonical, CONFIG_PATH2))) {
         return canonical;
       }
       process.stderr.write(`Warning: No .story/config.json at ${canonical}
@@ -10373,7 +10646,7 @@ var init_mcp = __esm({
     init_init();
     ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "0.1.34";
+    version = "0.1.36";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -10409,7 +10682,7 @@ __export(run_exports, {
   runReadCommand: () => runReadCommand,
   writeOutput: () => writeOutput
 });
-import { join as join17 } from "path";
+import { join as join19 } from "path";
 function writeOutput(text) {
   try {
     process.stdout.write(text + "\n");
@@ -10437,7 +10710,7 @@ async function runReadCommand(format, handler) {
       return;
     }
     const { state, warnings } = await loadProject(root);
-    const handoversDir = join17(root, ".story", "handovers");
+    const handoversDir = join19(root, ".story", "handovers");
     const result = await handler({ state, warnings, root, handoversDir, format });
     writeOutput(result.output);
     let exitCode = result.exitCode ?? ExitCode.OK;
@@ -10472,7 +10745,7 @@ async function runDeleteCommand(format, force, handler) {
       return;
     }
     const { state, warnings } = await loadProject(root);
-    const handoversDir = join17(root, ".story", "handovers");
+    const handoversDir = join19(root, ".story", "handovers");
     if (!force && hasIntegrityWarnings(warnings)) {
       writeOutput(
         formatError(
@@ -10521,6 +10794,102 @@ var init_run = __esm({
   }
 });
 
+// src/cli/commands/repair.ts
+function computeRepairs(state, warnings) {
+  const integrityWarning = warnings.find(
+    (w) => INTEGRITY_WARNING_TYPES.includes(w.type)
+  );
+  if (integrityWarning) {
+    return {
+      fixes: [],
+      error: `Cannot repair: data integrity issue in ${integrityWarning.file}: ${integrityWarning.message}. Fix the corrupt file first, then retry.`,
+      tickets: [],
+      issues: []
+    };
+  }
+  const fixes = [];
+  const modifiedTickets = [];
+  const modifiedIssues = [];
+  const ticketIDs = new Set(state.tickets.map((t) => t.id));
+  const phaseIDs = new Set(state.roadmap.phases.map((p) => {
+    const id = p.id;
+    return typeof id === "object" && id !== null ? id.rawValue ?? String(id) : String(id);
+  }));
+  for (const ticket of state.tickets) {
+    let modified = false;
+    let blockedBy = [...ticket.blockedBy];
+    let parentTicket = ticket.parentTicket;
+    let phase = ticket.phase;
+    const validBlockedBy = blockedBy.filter((ref) => ticketIDs.has(ref));
+    if (validBlockedBy.length < blockedBy.length) {
+      const removed = blockedBy.filter((ref) => !ticketIDs.has(ref));
+      blockedBy = validBlockedBy;
+      modified = true;
+      fixes.push({ entity: ticket.id, field: "blockedBy", description: `Removed stale refs: ${removed.join(", ")}` });
+    }
+    if (parentTicket && !ticketIDs.has(parentTicket)) {
+      fixes.push({ entity: ticket.id, field: "parentTicket", description: `Cleared stale ref: ${parentTicket}` });
+      parentTicket = null;
+      modified = true;
+    }
+    const phaseRaw = typeof phase === "object" && phase !== null ? phase.rawValue ?? String(phase) : phase != null ? String(phase) : null;
+    if (phaseRaw && !phaseIDs.has(phaseRaw)) {
+      fixes.push({ entity: ticket.id, field: "phase", description: `Cleared stale phase: ${phaseRaw}` });
+      phase = null;
+      modified = true;
+    }
+    if (modified) {
+      modifiedTickets.push({ ...ticket, blockedBy, parentTicket, phase });
+    }
+  }
+  for (const issue of state.issues) {
+    let modified = false;
+    let relatedTickets = [...issue.relatedTickets];
+    let phase = issue.phase;
+    const validRelated = relatedTickets.filter((ref) => ticketIDs.has(ref));
+    if (validRelated.length < relatedTickets.length) {
+      const removed = relatedTickets.filter((ref) => !ticketIDs.has(ref));
+      relatedTickets = validRelated;
+      modified = true;
+      fixes.push({ entity: issue.id, field: "relatedTickets", description: `Removed stale refs: ${removed.join(", ")}` });
+    }
+    const issuePhaseRaw = typeof phase === "object" && phase !== null ? phase.rawValue ?? String(phase) : phase != null ? String(phase) : null;
+    if (issuePhaseRaw && !phaseIDs.has(issuePhaseRaw)) {
+      fixes.push({ entity: issue.id, field: "phase", description: `Cleared stale phase: ${issuePhaseRaw}` });
+      phase = null;
+      modified = true;
+    }
+    if (modified) {
+      modifiedIssues.push({ ...issue, relatedTickets, phase });
+    }
+  }
+  return { fixes, tickets: modifiedTickets, issues: modifiedIssues };
+}
+function handleRepair(ctx, dryRun) {
+  const { fixes, error } = computeRepairs(ctx.state, ctx.warnings);
+  if (error) {
+    return { output: error, errorCode: "project_corrupt" };
+  }
+  if (fixes.length === 0) {
+    return { output: "No stale references found. Project is clean." };
+  }
+  const lines = [`Found ${fixes.length} stale reference(s)${dryRun ? " (dry run)" : ""}:`, ""];
+  for (const fix of fixes) {
+    lines.push(`- ${fix.entity}.${fix.field}: ${fix.description}`);
+  }
+  if (dryRun) {
+    lines.push("", "Run without --dry-run to apply fixes.");
+  }
+  return { output: lines.join("\n") };
+}
+var init_repair = __esm({
+  "src/cli/commands/repair.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+  }
+});
+
 // src/cli/commands/init.ts
 import { basename as basename2 } from "path";
 function registerInitCommand(yargs) {
@@ -10890,7 +11259,7 @@ __export(setup_skill_exports, {
 });
 import { mkdir as mkdir5, writeFile as writeFile3, readFile as readFile5, rm, rename as rename2, unlink as unlink3 } from "fs/promises";
 import { existsSync as existsSync12 } from "fs";
-import { join as join18, dirname as dirname4 } from "path";
+import { join as join20, dirname as dirname4 } from "path";
 import { homedir } from "os";
 import { execFileSync } from "child_process";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -10899,10 +11268,10 @@ function log(msg) {
 }
 function resolveSkillSourceDir() {
   const thisDir = dirname4(fileURLToPath3(import.meta.url));
-  const bundledPath = join18(thisDir, "..", "src", "skill");
-  if (existsSync12(join18(bundledPath, "SKILL.md"))) return bundledPath;
-  const sourcePath = join18(thisDir, "..", "..", "skill");
-  if (existsSync12(join18(sourcePath, "SKILL.md"))) return sourcePath;
+  const bundledPath = join20(thisDir, "..", "src", "skill");
+  if (existsSync12(join20(bundledPath, "SKILL.md"))) return bundledPath;
+  const sourcePath = join20(thisDir, "..", "..", "skill");
+  if (existsSync12(join20(sourcePath, "SKILL.md"))) return sourcePath;
   throw new Error(
     `Cannot find bundled skill files. Checked:
   ${bundledPath}
@@ -10915,7 +11284,7 @@ function isHookWithCommand(entry, command) {
   return e.type === "command" && typeof e.command === "string" && e.command.trim() === command;
 }
 async function registerHook(hookType, hookEntry, settingsPath, matcher) {
-  const path2 = settingsPath ?? join18(homedir(), ".claude", "settings.json");
+  const path2 = settingsPath ?? join20(homedir(), ".claude", "settings.json");
   let raw = "{}";
   if (existsSync12(path2)) {
     try {
@@ -11013,7 +11382,7 @@ async function registerStopHook(settingsPath) {
   return registerHook("Stop", { type: "command", command: STOP_HOOK_COMMAND, async: true }, settingsPath);
 }
 async function removeHook(hookType, command, settingsPath) {
-  const path2 = settingsPath ?? join18(homedir(), ".claude", "settings.json");
+  const path2 = settingsPath ?? join20(homedir(), ".claude", "settings.json");
   let raw = "{}";
   if (existsSync12(path2)) {
     try {
@@ -11060,7 +11429,7 @@ async function removeHook(hookType, command, settingsPath) {
 }
 async function handleSetupSkill(options = {}) {
   const { skipHooks = false } = options;
-  const skillDir = join18(homedir(), ".claude", "skills", "story");
+  const skillDir = join20(homedir(), ".claude", "skills", "story");
   await mkdir5(skillDir, { recursive: true });
   let srcSkillDir;
   try {
@@ -11073,19 +11442,19 @@ async function handleSetupSkill(options = {}) {
     process.exitCode = 1;
     return;
   }
-  const oldPrimeDir = join18(homedir(), ".claude", "skills", "prime");
+  const oldPrimeDir = join20(homedir(), ".claude", "skills", "prime");
   if (existsSync12(oldPrimeDir)) {
     await rm(oldPrimeDir, { recursive: true, force: true });
     log("Removed old /prime skill (migrated to /story)");
   }
-  const existed = existsSync12(join18(skillDir, "SKILL.md"));
-  const skillContent = await readFile5(join18(srcSkillDir, "SKILL.md"), "utf-8");
-  await writeFile3(join18(skillDir, "SKILL.md"), skillContent, "utf-8");
+  const existed = existsSync12(join20(skillDir, "SKILL.md"));
+  const skillContent = await readFile5(join20(srcSkillDir, "SKILL.md"), "utf-8");
+  await writeFile3(join20(skillDir, "SKILL.md"), skillContent, "utf-8");
   let referenceWritten = false;
-  const refSrcPath = join18(srcSkillDir, "reference.md");
+  const refSrcPath = join20(srcSkillDir, "reference.md");
   if (existsSync12(refSrcPath)) {
     const refContent = await readFile5(refSrcPath, "utf-8");
-    await writeFile3(join18(skillDir, "reference.md"), refContent, "utf-8");
+    await writeFile3(join20(skillDir, "reference.md"), refContent, "utf-8");
     referenceWritten = true;
   }
   log(`${existed ? "Updated" : "Installed"} /story skill at ${skillDir}/`);
@@ -11199,8 +11568,8 @@ var hook_status_exports = {};
 __export(hook_status_exports, {
   handleHookStatus: () => handleHookStatus
 });
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync4, renameSync as renameSync2, unlinkSync as unlinkSync4 } from "fs";
-import { join as join19 } from "path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync4, renameSync as renameSync2, unlinkSync as unlinkSync4 } from "fs";
+import { join as join21 } from "path";
 async function readStdinSilent() {
   try {
     const chunks = [];
@@ -11250,10 +11619,10 @@ function activePayload(session) {
   };
 }
 function ensureGitignore(root) {
-  const gitignorePath = join19(root, ".story", ".gitignore");
+  const gitignorePath = join21(root, ".story", ".gitignore");
   let existing = "";
   try {
-    existing = readFileSync6(gitignorePath, "utf-8");
+    existing = readFileSync8(gitignorePath, "utf-8");
   } catch {
   }
   const lines = existing.split("\n").map((l) => l.trim());
@@ -11269,7 +11638,7 @@ function ensureGitignore(root) {
 }
 function writeStatus(root, payload) {
   ensureGitignore(root);
-  const statusPath = join19(root, ".story", "status.json");
+  const statusPath = join21(root, ".story", "status.json");
   const content = JSON.stringify(payload, null, 2) + "\n";
   atomicWriteSync(statusPath, content);
 }
@@ -11328,8 +11697,8 @@ var config_update_exports = {};
 __export(config_update_exports, {
   handleConfigSetOverrides: () => handleConfigSetOverrides
 });
-import { readFileSync as readFileSync7 } from "fs";
-import { join as join20 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
+import { join as join22 } from "path";
 async function handleConfigSetOverrides(root, format, options) {
   const { json: jsonArg, clear } = options;
   if (!clear && !jsonArg) {
@@ -11357,8 +11726,8 @@ async function handleConfigSetOverrides(root, format, options) {
   }
   let resultOverrides = null;
   await withProjectLock(root, { strict: false }, async () => {
-    const configPath = join20(root, ".story", "config.json");
-    const rawContent = readFileSync7(configPath, "utf-8");
+    const configPath = join22(root, ".story", "config.json");
+    const rawContent = readFileSync9(configPath, "utf-8");
     const raw = JSON.parse(rawContent);
     if (clear) {
       delete raw.recipeOverrides;
@@ -11605,6 +11974,7 @@ __export(register_exports, {
   registerRecapCommand: () => registerRecapCommand,
   registerRecommendCommand: () => registerRecommendCommand,
   registerReferenceCommand: () => registerReferenceCommand,
+  registerRepairCommand: () => registerRepairCommand,
   registerSelftestCommand: () => registerSelftestCommand,
   registerSessionCommand: () => registerSessionCommand,
   registerSetupSkillCommand: () => registerSetupSkillCommand,
@@ -11635,6 +12005,47 @@ function registerValidateCommand(yargs) {
     }
   );
 }
+function registerRepairCommand(yargs) {
+  return yargs.command(
+    "repair",
+    "Fix stale references in .story/ data",
+    (y) => y.option("dry-run", { type: "boolean", default: false, describe: "Show what would be fixed without writing" }),
+    async (argv) => {
+      const dryRun = argv["dry-run"];
+      if (dryRun) {
+        await runReadCommand("md", (ctx) => handleRepair(ctx, true));
+      } else {
+        const { withProjectLock: withProjectLock2, writeTicketUnlocked: writeTicketUnlocked2, writeIssueUnlocked: writeIssueUnlocked2, runTransactionUnlocked: runTransactionUnlocked2 } = await Promise.resolve().then(() => (init_project_loader(), project_loader_exports));
+        const root = (await Promise.resolve().then(() => (init_project_root_discovery(), project_root_discovery_exports))).discoverProjectRoot();
+        await withProjectLock2(root, { strict: false }, async ({ state, warnings }) => {
+          const result = computeRepairs(state, warnings);
+          if (result.error) {
+            writeOutput(result.error);
+            process.exitCode = ExitCode.USER_ERROR;
+            return;
+          }
+          if (result.fixes.length === 0) {
+            writeOutput("No stale references found. Project is clean.");
+            return;
+          }
+          await runTransactionUnlocked2(root, async () => {
+            for (const ticket of result.tickets) {
+              await writeTicketUnlocked2(ticket, root);
+            }
+            for (const issue of result.issues) {
+              await writeIssueUnlocked2(issue, root);
+            }
+          });
+          const lines = [`Fixed ${result.fixes.length} stale reference(s):`, ""];
+          for (const fix of result.fixes) {
+            lines.push(`- ${fix.entity}.${fix.field}: ${fix.description}`);
+          }
+          writeOutput(lines.join("\n"));
+        });
+      }
+    }
+  );
+}
 function registerHandoverCommand(yargs) {
   return yargs.command(
     "handover",
@@ -13606,6 +14017,7 @@ var init_register = __esm({
     init_output_formatter();
     init_status();
     init_validate();
+    init_repair();
     init_handover();
     init_blocker();
     init_ticket2();
@@ -13655,9 +14067,10 @@ async function runCli() {
     registerSetupSkillCommand: registerSetupSkillCommand2,
     registerHookStatusCommand: registerHookStatusCommand2,
     registerConfigCommand: registerConfigCommand2,
-    registerSessionCommand: registerSessionCommand2
+    registerSessionCommand: registerSessionCommand2,
+    registerRepairCommand: registerRepairCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "0.1.34";
+  const version2 = "0.1.36";
   class HandledError extends Error {
     constructor() {
       super("HANDLED_ERROR");
@@ -13689,6 +14102,7 @@ async function runCli() {
   cli = registerHandoverCommand2(cli);
   cli = registerBlockerCommand2(cli);
   cli = registerValidateCommand2(cli);
+  cli = registerRepairCommand2(cli);
   cli = registerSnapshotCommand2(cli);
   cli = registerRecapCommand2(cli);
   cli = registerExportCommand2(cli);