@anthropologies/claudestory 0.1.7 → 0.1.9

package/dist/index.js

@@ -9,6 +9,9 @@ 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 NOTE_STATUSES = ["active", "archived"];
+var NOTE_ID_REGEX = /^N-\d+$/;
+var NoteIdSchema = z.string().regex(NOTE_ID_REGEX, "Note ID must match N-NNN");
 var OUTPUT_FORMATS = ["json", "md"];
 var ERROR_CODES = [
   "not_found",
@@ -72,47 +75,65 @@ var IssueSchema = z3.object({
   lastModifiedBy: z3.string().nullable().optional()
 }).passthrough();
 
-// src/models/roadmap.ts
+// src/models/note.ts
 import { z as z4 } from "zod";
-var BlockerSchema = z4.object({
-  name: z4.string().min(1),
+var NoteSchema = z4.object({
+  id: NoteIdSchema,
+  title: z4.preprocess((v) => v ?? null, z4.string().nullable()),
+  content: z4.string().refine((v) => v.trim().length > 0, "Content cannot be empty"),
+  tags: z4.preprocess(
+    (v) => {
+      const raw = Array.isArray(v) ? v : [];
+      return raw.filter((t) => typeof t === "string").map((t) => t.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-|-$/g, "")).filter((t) => t.length > 0).filter((t, i, a) => a.indexOf(t) === i);
+    },
+    z4.array(z4.string())
+  ),
+  status: z4.enum(NOTE_STATUSES),
+  createdDate: DateSchema,
+  updatedDate: DateSchema
+}).passthrough();
+
+// src/models/roadmap.ts
+import { z as z5 } from "zod";
+var BlockerSchema = z5.object({
+  name: z5.string().min(1),
   // Legacy format (pre-T-082)
-  cleared: z4.boolean().optional(),
+  cleared: z5.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()
+  note: z5.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()
+var PhaseSchema = z5.object({
+  id: z5.string().min(1),
+  label: z5.string(),
+  name: z5.string(),
+  description: z5.string(),
+  summary: z5.string().optional()
 }).passthrough();
-var RoadmapSchema = z4.object({
-  title: z4.string(),
+var RoadmapSchema = z5.object({
+  title: z5.string(),
   date: DateSchema,
-  phases: z4.array(PhaseSchema),
-  blockers: z4.array(BlockerSchema)
+  phases: z5.array(PhaseSchema),
+  blockers: z5.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()
+import { z as z6 } from "zod";
+var FeaturesSchema = z6.object({
+  tickets: z6.boolean(),
+  issues: z6.boolean(),
+  handovers: z6.boolean(),
+  roadmap: z6.boolean(),
+  reviews: z6.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(),
+var ConfigSchema = z6.object({
+  version: z6.number().int().min(1),
+  schemaVersion: z6.number().int().optional(),
+  project: z6.string().min(1),
+  type: z6.string(),
+  language: z6.string(),
   features: FeaturesSchema
 }).passthrough();
 
@@ -121,6 +142,7 @@ var ProjectState = class _ProjectState {
   // --- Public raw inputs (readonly) ---
   tickets;
   issues;
+  notes;
   roadmap;
   config;
   handoverFilenames;
@@ -135,15 +157,19 @@ var ProjectState = class _ProjectState {
   reverseBlocksMap;
   ticketsByID;
   issuesByID;
+  notesByID;
   // --- Counts ---
   totalTicketCount;
   openTicketCount;
   completeTicketCount;
   openIssueCount;
   issuesBySeverity;
+  activeNoteCount;
+  archivedNoteCount;
   constructor(input) {
     this.tickets = input.tickets;
     this.issues = input.issues;
+    this.notes = input.notes;
     this.roadmap = input.roadmap;
     this.config = input.config;
     this.handoverFilenames = input.handoverFilenames;
@@ -209,6 +235,11 @@ var ProjectState = class _ProjectState {
       iByID.set(i.id, i);
     }
     this.issuesByID = iByID;
+    const nByID = /* @__PURE__ */ new Map();
+    for (const n of input.notes) {
+      nByID.set(n.id, n);
+    }
+    this.notesByID = nByID;
     this.totalTicketCount = input.tickets.length;
     this.openTicketCount = input.tickets.filter(
       (t) => t.status !== "complete"
@@ -226,6 +257,12 @@ var ProjectState = class _ProjectState {
       }
     }
     this.issuesBySeverity = bySev;
+    this.activeNoteCount = input.notes.filter(
+      (n) => n.status === "active"
+    ).length;
+    this.archivedNoteCount = input.notes.filter(
+      (n) => n.status === "archived"
+    ).length;
   }
   // --- Query Methods ---
   isUmbrella(ticket) {
@@ -272,6 +309,9 @@ var ProjectState = class _ProjectState {
   issueByID(id) {
     return this.issuesByID.get(id);
   }
+  noteByID(id) {
+    return this.notesByID.get(id);
+  }
   // --- Deletion Safety ---
   /** IDs of tickets that list `ticketId` in their blockedBy. */
   ticketsBlocking(ticketId) {
@@ -331,7 +371,8 @@ import {
   stat,
   realpath,
   lstat,
-  open
+  open,
+  mkdir
 } from "fs/promises";
 import { existsSync as existsSync2 } from "fs";
 import { join as join2, resolve, relative as relative2, extname as extname2, dirname, basename } from "path";
@@ -462,6 +503,12 @@ async function loadProject(root, options) {
     IssueSchema,
     warnings
   );
+  const notes = await loadDirectory(
+    join2(wrapDir, "notes"),
+    absRoot,
+    NoteSchema,
+    warnings
+  );
   const handoversDir = join2(wrapDir, "handovers");
   const handoverFilenames = await listHandovers(
     handoversDir,
@@ -482,6 +529,7 @@ async function loadProject(root, options) {
   const state = new ProjectState({
     tickets,
     issues,
+    notes,
     roadmap,
     config,
     handoverFilenames
@@ -620,6 +668,49 @@ async function deleteIssue(id, root) {
     await unlink(targetPath);
   });
 }
+async function writeNoteUnlocked(note, root) {
+  const parsed = NoteSchema.parse(note);
+  if (!NOTE_ID_REGEX.test(parsed.id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${parsed.id}`
+    );
+  }
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "notes", `${parsed.id}.json`);
+  await mkdir(dirname(targetPath), { recursive: true });
+  await guardPath(targetPath, wrapDir);
+  const json = serializeJSON(parsed);
+  await atomicWrite(targetPath, json);
+}
+async function writeNote(note, root) {
+  const wrapDir = resolve(root, ".story");
+  await withLock(wrapDir, async () => {
+    await writeNoteUnlocked(note, root);
+  });
+}
+async function deleteNote(id, root) {
+  if (!NOTE_ID_REGEX.test(id)) {
+    throw new ProjectLoaderError(
+      "invalid_input",
+      `Invalid note ID: ${id}`
+    );
+  }
+  const wrapDir = resolve(root, ".story");
+  const targetPath = join2(wrapDir, "notes", `${id}.json`);
+  await guardPath(targetPath, wrapDir);
+  await withLock(wrapDir, async () => {
+    try {
+      await stat(targetPath);
+    } catch {
+      throw new ProjectLoaderError(
+        "not_found",
+        `Note file not found: notes/${id}.json`
+      );
+    }
+    await unlink(targetPath);
+  });
+}
 async function withProjectLock(root, options, handler) {
   const absRoot = resolve(root);
   const wrapDir = join2(absRoot, ".story");
@@ -783,8 +874,9 @@ async function loadProjectUnlocked(absRoot) {
   const warnings = [];
   const tickets = await loadDirectory(join2(wrapDir, "tickets"), absRoot, TicketSchema, warnings);
   const issues = await loadDirectory(join2(wrapDir, "issues"), absRoot, IssueSchema, warnings);
+  const notes = await loadDirectory(join2(wrapDir, "notes"), absRoot, NoteSchema, warnings);
   const handoverFilenames = await listHandovers(join2(wrapDir, "handovers"), absRoot, warnings);
-  const state = new ProjectState({ tickets, issues, roadmap, config, handoverFilenames });
+  const state = new ProjectState({ tickets, issues, notes, roadmap, config, handoverFilenames });
   return { state, warnings };
 }
 async function loadSingletonFile(filename, wrapDir, root, schema) {
@@ -1045,6 +1137,53 @@ function nextTicket(state) {
   }
   return { kind: "empty_project" };
 }
+function nextTickets(state, count) {
+  const effectiveCount = Math.max(1, count);
+  const phases = state.roadmap.phases;
+  if (phases.length === 0 || state.leafTickets.length === 0) {
+    return { kind: "empty_project" };
+  }
+  const candidates = [];
+  const skippedBlockedPhases = [];
+  let allPhasesComplete = true;
+  for (const phase of phases) {
+    if (candidates.length >= effectiveCount) break;
+    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 unblocked = incompleteLeaves.filter((t) => !state.isBlocked(t));
+    if (unblocked.length === 0) {
+      skippedBlockedPhases.push({
+        phaseId: phase.id,
+        blockedCount: incompleteLeaves.length
+      });
+      continue;
+    }
+    const remaining = effectiveCount - candidates.length;
+    for (const ticket of unblocked.slice(0, remaining)) {
+      const impact = ticketsUnblockedBy(ticket.id, state);
+      const progress = ticket.parentTicket ? umbrellaProgress(ticket.parentTicket, state) : null;
+      candidates.push({
+        ticket,
+        unblockImpact: { ticketId: ticket.id, wouldUnblock: impact },
+        umbrellaProgress: progress
+      });
+    }
+  }
+  if (candidates.length > 0) {
+    return { kind: "found", candidates, skippedBlockedPhases };
+  }
+  if (skippedBlockedPhases.length > 0) {
+    return { kind: "all_blocked", phases: skippedBlockedPhases };
+  }
+  if (allPhasesComplete) {
+    return { kind: "all_complete" };
+  }
+  return { kind: "empty_project" };
+}
 function blockedTickets(state) {
   return state.leafTickets.filter(
     (t) => t.status !== "complete" && state.isBlocked(t)
@@ -1092,6 +1231,9 @@ function isBlockerCleared(blocker) {
   if (blocker.clearedDate != null) return true;
   return false;
 }
+function descendantLeaves(ticketId, state) {
+  return collectDescendantLeaves(ticketId, state, /* @__PURE__ */ new Set());
+}
 function collectDescendantLeaves(ticketId, state, visited) {
   if (visited.has(ticketId)) return [];
   visited.add(ticketId);
@@ -1107,39 +1249,6 @@ function collectDescendantLeaves(ticketId, state, visited) {
   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 = [];
@@ -1176,6 +1285,20 @@ function validateProject(state) {
       });
     }
   }
+  const noteIDCounts = /* @__PURE__ */ new Map();
+  for (const n of state.notes) {
+    noteIDCounts.set(n.id, (noteIDCounts.get(n.id) ?? 0) + 1);
+  }
+  for (const [id, count] of noteIDCounts) {
+    if (count > 1) {
+      findings.push({
+        level: "error",
+        code: "duplicate_note_id",
+        message: `Duplicate note 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);
@@ -1381,8 +1504,285 @@ function dfsBlocked(id, state, visited, inStack, findings) {
   visited.add(id);
 }
 
+// src/core/recommend.ts
+var SEVERITY_RANK = {
+  critical: 4,
+  high: 3,
+  medium: 2,
+  low: 1
+};
+var PHASE_DISTANCE_PENALTY = 100;
+var MAX_PHASE_PENALTY = 400;
+var CATEGORY_PRIORITY = {
+  validation_errors: 1,
+  critical_issue: 2,
+  inprogress_ticket: 3,
+  high_impact_unblock: 4,
+  near_complete_umbrella: 5,
+  phase_momentum: 6,
+  quick_win: 7,
+  open_issue: 8
+};
+function recommend(state, count) {
+  const effectiveCount = Math.max(1, Math.min(10, count));
+  const dedup = /* @__PURE__ */ new Map();
+  const phaseIndex = buildPhaseIndex(state);
+  const generators = [
+    () => generateValidationSuggestions(state),
+    () => generateCriticalIssues(state),
+    () => generateInProgressTickets(state, phaseIndex),
+    () => generateHighImpactUnblocks(state),
+    () => generateNearCompleteUmbrellas(state, phaseIndex),
+    () => generatePhaseMomentum(state),
+    () => generateQuickWins(state, phaseIndex),
+    () => generateOpenIssues(state)
+  ];
+  for (const gen of generators) {
+    for (const rec of gen()) {
+      const existing = dedup.get(rec.id);
+      if (!existing || rec.score > existing.score) {
+        dedup.set(rec.id, rec);
+      }
+    }
+  }
+  const curPhase = currentPhase(state);
+  const curPhaseIdx = curPhase ? phaseIndex.get(curPhase.id) ?? 0 : 0;
+  for (const [id, rec] of dedup) {
+    if (rec.kind !== "ticket") continue;
+    const ticket = state.ticketByID(id);
+    if (!ticket || ticket.phase == null) continue;
+    const ticketPhaseIdx = phaseIndex.get(ticket.phase);
+    if (ticketPhaseIdx === void 0) continue;
+    const phasesAhead = ticketPhaseIdx - curPhaseIdx;
+    if (phasesAhead > 0) {
+      const penalty = Math.min(phasesAhead * PHASE_DISTANCE_PENALTY, MAX_PHASE_PENALTY);
+      dedup.set(id, {
+        ...rec,
+        score: rec.score - penalty,
+        reason: rec.reason + " (future phase)"
+      });
+    }
+  }
+  const all = [...dedup.values()].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    const catDiff = CATEGORY_PRIORITY[a.category] - CATEGORY_PRIORITY[b.category];
+    if (catDiff !== 0) return catDiff;
+    return a.id.localeCompare(b.id);
+  });
+  return {
+    recommendations: all.slice(0, effectiveCount),
+    totalCandidates: all.length
+  };
+}
+function generateValidationSuggestions(state) {
+  const result = validateProject(state);
+  if (result.errorCount === 0) return [];
+  return [
+    {
+      id: "validate",
+      kind: "action",
+      title: "Run claudestory validate",
+      category: "validation_errors",
+      reason: `${result.errorCount} validation error${result.errorCount === 1 ? "" : "s"} \u2014 fix before other work`,
+      score: 1e3
+    }
+  ];
+}
+function generateCriticalIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "critical" || i.severity === "high")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "critical_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress, ensure it's being addressed` : `${capitalize(issue.severity)} severity issue \u2014 address before new features`,
+    score: 900 - Math.min(index, 99)
+  }));
+}
+function generateInProgressTickets(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "inprogress"
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "inprogress_ticket",
+    reason: "In-progress \u2014 finish what's started",
+    score: 800 - Math.min(index, 99)
+  }));
+}
+function generateHighImpactUnblocks(state) {
+  const candidates = [];
+  for (const ticket of state.leafTickets) {
+    if (ticket.status === "complete") continue;
+    if (state.isBlocked(ticket)) continue;
+    const wouldUnblock = ticketsUnblockedBy(ticket.id, state);
+    if (wouldUnblock.length >= 2) {
+      candidates.push({ ticket, unblockCount: wouldUnblock.length });
+    }
+  }
+  candidates.sort((a, b) => b.unblockCount - a.unblockCount);
+  return candidates.map(({ ticket, unblockCount }, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "high_impact_unblock",
+    reason: `Completing this unblocks ${unblockCount} other ticket${unblockCount === 1 ? "" : "s"}`,
+    score: 700 - Math.min(index, 99)
+  }));
+}
+function generateNearCompleteUmbrellas(state, phaseIndex) {
+  const candidates = [];
+  for (const umbrellaId of state.umbrellaIDs) {
+    const progress = umbrellaProgress(umbrellaId, state);
+    if (!progress) continue;
+    if (progress.total < 2) continue;
+    if (progress.status === "complete") continue;
+    const ratio = progress.complete / progress.total;
+    if (ratio < 0.8) continue;
+    const leaves = descendantLeaves(umbrellaId, state);
+    const incomplete = leaves.filter((t) => t.status !== "complete");
+    const sorted = sortByPhaseAndOrder(incomplete, phaseIndex);
+    if (sorted.length === 0) continue;
+    const umbrella = state.ticketByID(umbrellaId);
+    candidates.push({
+      umbrellaId,
+      umbrellaTitle: umbrella?.title ?? umbrellaId,
+      firstIncompleteLeaf: sorted[0],
+      complete: progress.complete,
+      total: progress.total,
+      ratio
+    });
+  }
+  candidates.sort((a, b) => b.ratio - a.ratio);
+  return candidates.map((c, index) => ({
+    id: c.firstIncompleteLeaf.id,
+    kind: "ticket",
+    title: c.firstIncompleteLeaf.title,
+    category: "near_complete_umbrella",
+    reason: `${c.complete}/${c.total} complete in umbrella ${c.umbrellaId} \u2014 close it out`,
+    score: 600 - Math.min(index, 99)
+  }));
+}
+function generatePhaseMomentum(state) {
+  const outcome = nextTicket(state);
+  if (outcome.kind !== "found") return [];
+  const ticket = outcome.ticket;
+  return [
+    {
+      id: ticket.id,
+      kind: "ticket",
+      title: ticket.title,
+      category: "phase_momentum",
+      reason: `Next in phase order (${ticket.phase ?? "none"})`,
+      score: 500
+    }
+  ];
+}
+function generateQuickWins(state, phaseIndex) {
+  const tickets = state.leafTickets.filter(
+    (t) => t.status === "open" && t.type === "chore" && !state.isBlocked(t)
+  );
+  const sorted = sortByPhaseAndOrder(tickets, phaseIndex);
+  return sorted.map((ticket, index) => ({
+    id: ticket.id,
+    kind: "ticket",
+    title: ticket.title,
+    category: "quick_win",
+    reason: "Chore \u2014 quick win",
+    score: 400 - Math.min(index, 99)
+  }));
+}
+function generateOpenIssues(state) {
+  const issues = state.issues.filter(
+    (i) => i.status !== "resolved" && (i.severity === "medium" || i.severity === "low")
+  ).sort((a, b) => {
+    const sevDiff = SEVERITY_RANK[b.severity] - SEVERITY_RANK[a.severity];
+    if (sevDiff !== 0) return sevDiff;
+    return b.discoveredDate.localeCompare(a.discoveredDate);
+  });
+  return issues.map((issue, index) => ({
+    id: issue.id,
+    kind: "issue",
+    title: issue.title,
+    category: "open_issue",
+    reason: issue.status === "inprogress" ? `${capitalize(issue.severity)} severity issue \u2014 in-progress` : `${capitalize(issue.severity)} severity issue`,
+    score: 300 - Math.min(index, 99)
+  }));
+}
+function capitalize(s) {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function buildPhaseIndex(state) {
+  const index = /* @__PURE__ */ new Map();
+  state.roadmap.phases.forEach((p, i) => index.set(p.id, i));
+  return index;
+}
+function sortByPhaseAndOrder(tickets, phaseIndex) {
+  return [...tickets].sort((a, b) => {
+    const aPhase = (a.phase != null ? phaseIndex.get(a.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    const bPhase = (b.phase != null ? phaseIndex.get(b.phase) : void 0) ?? Number.MAX_SAFE_INTEGER;
+    if (aPhase !== bPhase) return aPhase - bPhase;
+    return a.order - b.order;
+  });
+}
+
+// src/core/id-allocation.ts
+var TICKET_NUMERIC_REGEX = /^T-(\d+)[a-z]?$/;
+var ISSUE_NUMERIC_REGEX = /^ISS-(\d+)$/;
+var NOTE_NUMERIC_REGEX = /^N-(\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 nextNoteID(notes) {
+  let max = 0;
+  for (const n of notes) {
+    if (!NOTE_ID_REGEX.test(n.id)) continue;
+    const match = n.id.match(NOTE_NUMERIC_REGEX);
+    if (match?.[1]) {
+      const num = parseInt(match[1], 10);
+      if (num > max) max = num;
+    }
+  }
+  return `N-${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/init.ts
-import { mkdir, stat as stat2 } from "fs/promises";
+import { mkdir as mkdir2, stat as stat2 } from "fs/promises";
 import { join as join4, resolve as resolve3 } from "path";
 async function initProject(root, options) {
   const absRoot = resolve3(root);
@@ -1406,9 +1806,18 @@ async function initProject(root, options) {
       ".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 });
+  await mkdir2(join4(wrapDir, "tickets"), { recursive: true });
+  await mkdir2(join4(wrapDir, "issues"), { recursive: true });
+  await mkdir2(join4(wrapDir, "handovers"), { recursive: true });
+  await mkdir2(join4(wrapDir, "notes"), { recursive: true });
+  const created = [
+    ".story/config.json",
+    ".story/roadmap.json",
+    ".story/tickets/",
+    ".story/issues/",
+    ".story/handovers/",
+    ".story/notes/"
+  ];
   const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   const config = {
     version: 2,
@@ -1453,42 +1862,37 @@ async function initProject(root, options) {
   }
   return {
     root: absRoot,
-    created: [
-      ".story/config.json",
-      ".story/roadmap.json",
-      ".story/tickets/",
-      ".story/issues/",
-      ".story/handovers/"
-    ],
+    created,
     warnings
   };
 }
 
 // src/core/snapshot.ts
-import { readdir as readdir3, readFile as readFile3, mkdir as mkdir2, unlink as unlink2 } from "fs/promises";
+import { readdir as readdir3, readFile as readFile3, mkdir as mkdir3, unlink as unlink2 } from "fs/promises";
 import { existsSync as existsSync4 } from "fs";
 import { join as join5, resolve as resolve4 } from "path";
-import { z as z6 } from "zod";
-var LoadWarningSchema = z6.object({
-  type: z6.string(),
-  file: z6.string(),
-  message: z6.string()
+import { z as z7 } from "zod";
+var LoadWarningSchema = z7.object({
+  type: z7.string(),
+  file: z7.string(),
+  message: z7.string()
 });
-var SnapshotV1Schema = z6.object({
-  version: z6.literal(1),
-  createdAt: z6.string().datetime({ offset: true }),
-  project: z6.string(),
+var SnapshotV1Schema = z7.object({
+  version: z7.literal(1),
+  createdAt: z7.string().datetime({ offset: true }),
+  project: z7.string(),
   config: ConfigSchema,
   roadmap: RoadmapSchema,
-  tickets: z6.array(TicketSchema),
-  issues: z6.array(IssueSchema),
-  warnings: z6.array(LoadWarningSchema).optional()
+  tickets: z7.array(TicketSchema),
+  issues: z7.array(IssueSchema),
+  notes: z7.array(NoteSchema).optional().default([]),
+  warnings: z7.array(LoadWarningSchema).optional()
 });
 var MAX_SNAPSHOTS = 20;
 async function saveSnapshot(root, loadResult) {
   const absRoot = resolve4(root);
   const snapshotsDir = join5(absRoot, ".story", "snapshots");
-  await mkdir2(snapshotsDir, { recursive: true });
+  await mkdir3(snapshotsDir, { recursive: true });
   const { state, warnings } = loadResult;
   const now = /* @__PURE__ */ new Date();
   const filename = formatSnapshotFilename(now);
@@ -1500,6 +1904,7 @@ async function saveSnapshot(root, loadResult) {
     roadmap: state.roadmap,
     tickets: [...state.tickets],
     issues: [...state.issues],
+    notes: [...state.notes],
     ...warnings.length > 0 ? {
       warnings: warnings.map((w) => ({
         type: w.type,
@@ -1540,12 +1945,18 @@ function diffStates(snapshotState, currentState) {
   const ticketsAdded = [];
   const ticketsRemoved = [];
   const ticketsStatusChanged = [];
+  const ticketsDescriptionChanged = [];
   for (const [id, cur] of curTickets) {
     const snap = snapTickets.get(id);
     if (!snap) {
       ticketsAdded.push({ id, title: cur.title });
-    } else if (snap.status !== cur.status) {
-      ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    } else {
+      if (snap.status !== cur.status) {
+        ticketsStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+      }
+      if (snap.description !== cur.description) {
+        ticketsDescriptionChanged.push({ id, title: cur.title });
+      }
     }
   }
   for (const [id, snap] of snapTickets) {
@@ -1558,15 +1969,21 @@ function diffStates(snapshotState, currentState) {
   const issuesAdded = [];
   const issuesResolved = [];
   const issuesStatusChanged = [];
+  const issuesImpactChanged = [];
   for (const [id, cur] of curIssues) {
     const snap = snapIssues.get(id);
     if (!snap) {
       issuesAdded.push({ id, title: cur.title });
-    } else if (snap.status !== cur.status) {
-      if (cur.status === "resolved") {
-        issuesResolved.push({ id, title: cur.title });
-      } else {
-        issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+    } else {
+      if (snap.status !== cur.status) {
+        if (cur.status === "resolved") {
+          issuesResolved.push({ id, title: cur.title });
+        } else {
+          issuesStatusChanged.push({ id, title: cur.title, from: snap.status, to: cur.status });
+        }
+      }
+      if (snap.impact !== cur.impact) {
+        issuesImpactChanged.push({ id, title: cur.title });
       }
     }
   }
@@ -1615,11 +2032,37 @@ function diffStates(snapshotState, currentState) {
       phasesRemoved.push({ id, name: snapPhase.name });
     }
   }
+  const snapNotes = new Map(snapshotState.notes.map((n) => [n.id, n]));
+  const curNotes = new Map(currentState.notes.map((n) => [n.id, n]));
+  const notesAdded = [];
+  const notesRemoved = [];
+  const notesUpdated = [];
+  for (const [id, cur] of curNotes) {
+    const snap = snapNotes.get(id);
+    if (!snap) {
+      notesAdded.push({ id, title: cur.title });
+    } else {
+      const changedFields = [];
+      if (snap.title !== cur.title) changedFields.push("title");
+      if (snap.content !== cur.content) changedFields.push("content");
+      if (JSON.stringify([...snap.tags].sort()) !== JSON.stringify([...cur.tags].sort())) changedFields.push("tags");
+      if (snap.status !== cur.status) changedFields.push("status");
+      if (changedFields.length > 0) {
+        notesUpdated.push({ id, title: cur.title, changedFields });
+      }
+    }
+  }
+  for (const [id, snap] of snapNotes) {
+    if (!curNotes.has(id)) {
+      notesRemoved.push({ id, title: snap.title });
+    }
+  }
   return {
-    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged },
-    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged },
+    tickets: { added: ticketsAdded, removed: ticketsRemoved, statusChanged: ticketsStatusChanged, descriptionChanged: ticketsDescriptionChanged },
+    issues: { added: issuesAdded, resolved: issuesResolved, statusChanged: issuesStatusChanged, impactChanged: issuesImpactChanged },
     blockers: { added: blockersAdded, cleared: blockersCleared },
-    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged }
+    phases: { added: phasesAdded, removed: phasesRemoved, statusChanged: phasesStatusChanged },
+    notes: { added: notesAdded, removed: notesRemoved, updated: notesUpdated }
   };
 }
 function buildRecap(currentState, snapshotInfo) {
@@ -1644,6 +2087,7 @@ function buildRecap(currentState, snapshotInfo) {
   const snapshotState = new ProjectState({
     tickets: snapshot.tickets,
     issues: snapshot.issues,
+    notes: snapshot.notes ?? [],
     roadmap: snapshot.roadmap,
     config: snapshot.config,
     handoverFilenames: []
@@ -1742,6 +2186,8 @@ function formatStatus(state, format) {
     openTickets: state.leafTicketCount - state.completeLeafTicketCount,
     blockedTickets: state.blockedCount,
     openIssues: state.openIssueCount,
+    activeNotes: state.activeNoteCount,
+    archivedNotes: state.archivedNoteCount,
     handovers: state.handoverFilenames.length,
     phases: phases.map((p) => ({
       id: p.phase.id,
@@ -1758,6 +2204,7 @@ function formatStatus(state, format) {
     "",
     `Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete, ${state.blockedCount} blocked`,
     `Issues: ${state.openIssueCount} open`,
+    `Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`,
     `Handovers: ${state.handoverFilenames.length}`,
     "",
     "## Phases",
@@ -1982,6 +2429,7 @@ function formatInitResult(result, format) {
   if (result.warnings.length > 0) {
     lines.push("", `Warning: ${result.warnings.length} corrupt file(s) found. Run \`claudestory validate\` to inspect.`);
   }
+  lines.push("", "Tip: Run `claudestory setup-skill` to install the /story skill for Claude Code.");
   return lines.join("\n");
 }
 function formatHandoverList(filenames, format) {
@@ -2045,7 +2493,7 @@ function formatRecap(recap, state, format) {
         }
       }
       const ticketChanges = changes.tickets;
-      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0) {
+      if (ticketChanges.added.length > 0 || ticketChanges.removed.length > 0 || ticketChanges.statusChanged.length > 0 || ticketChanges.descriptionChanged.length > 0) {
         lines.push("");
         lines.push("## Tickets");
         for (const t of ticketChanges.statusChanged) {
@@ -2057,9 +2505,12 @@ function formatRecap(recap, state, format) {
         for (const t of ticketChanges.removed) {
           lines.push(`- ${t.id}: ${escapeMarkdownInline(t.title)} \u2014 **removed**`);
         }
+        for (const t of ticketChanges.descriptionChanged) {
+          lines.push(`- ${t.id}: description updated`);
+        }
       }
       const issueChanges = changes.issues;
-      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0) {
+      if (issueChanges.added.length > 0 || issueChanges.resolved.length > 0 || issueChanges.statusChanged.length > 0 || issueChanges.impactChanged.length > 0) {
         lines.push("");
         lines.push("## Issues");
         for (const i of issueChanges.resolved) {
@@ -2071,6 +2522,9 @@ function formatRecap(recap, state, format) {
         for (const i of issueChanges.added) {
           lines.push(`- ${i.id}: ${escapeMarkdownInline(i.title)} \u2014 **new**`);
         }
+        for (const i of issueChanges.impactChanged) {
+          lines.push(`- ${i.id}: impact updated`);
+        }
       }
       if (changes.blockers.added.length > 0 || changes.blockers.cleared.length > 0) {
         lines.push("");
@@ -2082,6 +2536,19 @@ function formatRecap(recap, state, format) {
           lines.push(`- ${escapeMarkdownInline(name)} \u2014 **new**`);
         }
       }
+      if (changes.notes && (changes.notes.added.length > 0 || changes.notes.removed.length > 0 || changes.notes.updated.length > 0)) {
+        lines.push("");
+        lines.push("## Notes");
+        for (const n of changes.notes.added) {
+          lines.push(`- ${n.id}: added`);
+        }
+        for (const n of changes.notes.removed) {
+          lines.push(`- ${n.id}: removed`);
+        }
+        for (const n of changes.notes.updated) {
+          lines.push(`- ${n.id}: updated (${n.changedFields.join(", ")})`);
+        }
+      }
     }
   }
   const actions = recap.suggestedActions;
@@ -2220,6 +2687,12 @@ function formatFullExport(state, format) {
           severity: i.severity,
           status: i.status
         })),
+        notes: state.notes.map((n) => ({
+          id: n.id,
+          title: n.title,
+          status: n.status,
+          tags: n.tags
+        })),
         blockers: state.roadmap.blockers.map((b) => ({
           name: b.name,
           cleared: isBlockerCleared(b),
@@ -2235,6 +2708,7 @@ function formatFullExport(state, format) {
   lines.push("");
   lines.push(`Tickets: ${state.completeLeafTicketCount}/${state.leafTicketCount} complete`);
   lines.push(`Issues: ${state.openIssueCount} open`);
+  lines.push(`Notes: ${state.activeNoteCount} active, ${state.archivedNoteCount} archived`);
   lines.push("");
   lines.push("## Phases");
   for (const p of phases) {
@@ -2261,6 +2735,16 @@ function formatFullExport(state, format) {
       lines.push(`- ${i.id} [${i.severity}]: ${escapeMarkdownInline(i.title)}${resolved}`);
     }
   }
+  const activeNotes = state.notes.filter((n) => n.status === "active");
+  if (activeNotes.length > 0) {
+    lines.push("");
+    lines.push("## Notes");
+    for (const n of activeNotes) {
+      const title = n.title ?? n.id;
+      const tagInfo = n.tags.length > 0 ? ` (${n.tags.join(", ")})` : "";
+      lines.push(`- ${n.id}: ${escapeMarkdownInline(title)}${tagInfo}`);
+    }
+  }
   const blockers = state.roadmap.blockers;
   if (blockers.length > 0) {
     lines.push("");
@@ -2273,7 +2757,7 @@ function formatFullExport(state, format) {
   return lines.join("\n");
 }
 function hasAnyChanges(diff) {
-  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0;
+  return diff.tickets.added.length > 0 || diff.tickets.removed.length > 0 || diff.tickets.statusChanged.length > 0 || diff.tickets.descriptionChanged.length > 0 || diff.issues.added.length > 0 || diff.issues.resolved.length > 0 || diff.issues.statusChanged.length > 0 || diff.issues.impactChanged.length > 0 || diff.blockers.added.length > 0 || diff.blockers.cleared.length > 0 || diff.phases.added.length > 0 || diff.phases.removed.length > 0 || diff.phases.statusChanged.length > 0 || (diff.notes?.added.length ?? 0) > 0 || (diff.notes?.removed.length ?? 0) > 0 || (diff.notes?.updated.length ?? 0) > 0;
 }
 function truncate(text, maxLen) {
   if (text.length <= maxLen) return text;
@@ -2284,6 +2768,29 @@ function formatTicketOneLiner(t, state) {
   const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
   return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
 }
+function formatRecommendations(result, format) {
+  if (format === "json") {
+    return JSON.stringify(successEnvelope(result), null, 2);
+  }
+  if (result.recommendations.length === 0) {
+    return "No recommendations \u2014 all work is complete or blocked.";
+  }
+  const lines = ["# Recommendations", ""];
+  for (let i = 0; i < result.recommendations.length; i++) {
+    const rec = result.recommendations[i];
+    lines.push(
+      `${i + 1}. **${escapeMarkdownInline(rec.id)}** (${rec.kind}) \u2014 ${escapeMarkdownInline(rec.title)}`
+    );
+    lines.push(`   _${escapeMarkdownInline(rec.reason)}_`);
+    lines.push("");
+  }
+  if (result.totalCandidates > result.recommendations.length) {
+    lines.push(
+      `Showing ${result.recommendations.length} of ${result.totalCandidates} candidates.`
+    );
+  }
+  return lines.join("\n");
+}
 export {
   BlockerSchema,
   CURRENT_SCHEMA_VERSION,
@@ -2299,6 +2806,10 @@ export {
   ISSUE_STATUSES,
   IssueIdSchema,
   IssueSchema,
+  NOTE_ID_REGEX,
+  NOTE_STATUSES,
+  NoteIdSchema,
+  NoteSchema,
   OUTPUT_FORMATS,
   PhaseSchema,
   ProjectLoaderError,
@@ -2315,7 +2826,9 @@ export {
   buildRecap,
   currentPhase,
   deleteIssue,
+  deleteNote,
   deleteTicket,
+  descendantLeaves,
   diffStates,
   discoverProjectRoot,
   errorEnvelope,
@@ -2336,6 +2849,7 @@ export {
   formatPhaseList,
   formatPhaseTickets,
   formatRecap,
+  formatRecommendations,
   formatSnapshotResult,
   formatStatus,
   formatTicket,
@@ -2349,12 +2863,15 @@ export {
   loadProject,
   mergeValidation,
   nextIssueID,
+  nextNoteID,
   nextOrder,
   nextTicket,
   nextTicketID,
+  nextTickets,
   partialEnvelope,
   phasesWithStatus,
   readHandover,
+  recommend,
   runTransaction,
   runTransactionUnlocked,
   saveSnapshot,
@@ -2368,6 +2885,8 @@ export {
   writeConfig,
   writeIssue,
   writeIssueUnlocked,
+  writeNote,
+  writeNoteUnlocked,
   writeRoadmap,
   writeRoadmapUnlocked,
   writeTicket,