@anthropologies/claudestory 0.1.27 → 0.1.29

package/dist/cli.js

@@ -491,6 +491,15 @@ var init_project_state = __esm({
       get blockedCount() {
         return this.leafTickets.filter((t) => t.status !== "complete" && this.isBlocked(t)).length;
       }
+      /** True when the project has been initialized but not yet populated with tickets/issues/handovers. */
+      get isEmptyScaffold() {
+        return this.tickets.length === 0 && this.issues.length === 0 && this.handoverFilenames.length === 0 && this.isDefaultScaffoldPhases;
+      }
+      get isDefaultScaffoldPhases() {
+        const { phases } = this.roadmap;
+        if (phases.length === 0) return true;
+        return phases.length === 1 && phases[0].id === "p0";
+      }
       ticketByID(id) {
         return this.ticketsByID.get(id);
       }
@@ -1673,6 +1682,7 @@ var init_queries = __esm({
 // src/core/output-formatter.ts
 var output_formatter_exports = {};
 __export(output_formatter_exports, {
+  EMPTY_SCAFFOLD_HEADING: () => EMPTY_SCAFFOLD_HEADING,
   ExitCode: () => ExitCode,
   errorEnvelope: () => errorEnvelope,
   escapeMarkdownInline: () => escapeMarkdownInline,
@@ -1763,6 +1773,7 @@ function formatStatus(state, format) {
     activeLessons: state.activeLessonCount,
     deprecatedLessons: state.deprecatedLessonCount,
     handovers: state.handoverFilenames.length,
+    isEmptyScaffold: state.isEmptyScaffold,
     phases: phases.map((p) => ({
       id: p.phase.id,
       name: p.phase.name,
@@ -1790,6 +1801,13 @@ 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 (state.isEmptyScaffold) {
+    lines.push("");
+    lines.push(EMPTY_SCAFFOLD_HEADING);
+    lines.push("");
+    lines.push("This project has been initialized but has no tickets, issues, or handovers yet.");
+    lines.push("Run the /story setup flow to analyze your project and create an initial roadmap.");
+  }
   return lines.join("\n");
 }
 function formatPhaseList(state, format) {
@@ -2629,11 +2647,14 @@ function formatReference(commands, mcpTools, format) {
   lines.push("- **/story not available:** Run `claudestory setup-skill` to install the skill");
   return lines.join("\n");
 }
-function formatRecommendations(result, format) {
+function formatRecommendations(result, state, format) {
   if (format === "json") {
-    return JSON.stringify(successEnvelope(result), null, 2);
+    return JSON.stringify(successEnvelope({ ...result, isEmptyScaffold: state.isEmptyScaffold }), null, 2);
   }
   if (result.recommendations.length === 0) {
+    if (state.isEmptyScaffold) {
+      return "No recommendations yet \u2014 this project needs tickets and phases. Run the /story setup flow to get started.";
+    }
     return "No recommendations \u2014 all work is complete or blocked.";
   }
   const lines = ["# Recommendations", ""];
@@ -2652,12 +2673,13 @@ function formatRecommendations(result, format) {
   }
   return lines.join("\n");
 }
-var ExitCode;
+var EMPTY_SCAFFOLD_HEADING, ExitCode;
 var init_output_formatter = __esm({
   "src/core/output-formatter.ts"() {
     "use strict";
     init_esm_shims();
     init_queries();
+    EMPTY_SCAFFOLD_HEADING = "## Getting Started";
     ExitCode = {
       OK: 0,
       USER_ERROR: 1,
@@ -4667,7 +4689,7 @@ var init_recommend = __esm({
 // src/cli/commands/recommend.ts
 function handleRecommend(ctx, count) {
   const result = recommend(ctx.state, count);
-  return { output: formatRecommendations(result, ctx.format) };
+  return { output: formatRecommendations(result, ctx.state, ctx.format) };
 }
 var init_recommend2 = __esm({
   "src/cli/commands/recommend.ts"() {
@@ -5002,6 +5024,7 @@ var init_session_types = __esm({
       "VERIFY",
       "FINALIZE",
       "COMPACT",
+      "LESSON_CAPTURE",
       "ISSUE_SWEEP"
     ]);
     IDLE_STATES = /* @__PURE__ */ new Set([
@@ -5028,6 +5051,7 @@ var init_session_types = __esm({
       "COMPACT",
       "HANDOVER",
       "COMPLETE",
+      "LESSON_CAPTURE",
       "ISSUE_SWEEP",
       "SESSION_END"
     ];
@@ -5594,6 +5618,8 @@ var init_state_machine = __esm({
       // pass → FINALIZE, fail → IMPLEMENT, retry
       FINALIZE: ["COMPLETE"],
       COMPLETE: ["PICK_TICKET", "HANDOVER", "ISSUE_SWEEP", "SESSION_END"],
+      LESSON_CAPTURE: ["ISSUE_SWEEP", "HANDOVER", "LESSON_CAPTURE"],
+      // advance → ISSUE_SWEEP, retry self, done → HANDOVER
       ISSUE_SWEEP: ["ISSUE_SWEEP", "HANDOVER", "PICK_TICKET"],
       // retry (next issue), done → HANDOVER, loop → PICK_TICKET
       HANDOVER: ["COMPACT", "SESSION_END", "PICK_TICKET"],
@@ -5967,6 +5993,18 @@ function findFirstPostComplete(postComplete, ctx) {
   }
   return { kind: "exhausted" };
 }
+function findNextPostComplete(postComplete, currentId, ctx) {
+  const currentIndex = postComplete.indexOf(currentId);
+  const startIndex = currentIndex >= 0 ? currentIndex + 1 : 0;
+  for (let i = startIndex; i < postComplete.length; i++) {
+    const id = postComplete[i];
+    const stage = stages.get(id);
+    if (!stage) return { kind: "unregistered", id };
+    if (stage.skip?.(ctx)) continue;
+    return { kind: "found", stage };
+  }
+  return { kind: "exhausted" };
+}
 var stages;
 var init_registry = __esm({
   "src/autonomous/stages/registry.ts"() {
@@ -7403,6 +7441,74 @@ var init_complete = __esm({
   }
 });
 
+// src/autonomous/stages/lesson-capture.ts
+var LessonCaptureStage;
+var init_lesson_capture = __esm({
+  "src/autonomous/stages/lesson-capture.ts"() {
+    "use strict";
+    init_esm_shims();
+    LessonCaptureStage = class {
+      id = "LESSON_CAPTURE";
+      skip(ctx) {
+        const config = ctx.recipe.stages?.LESSON_CAPTURE;
+        return !config?.enabled;
+      }
+      async enter(ctx) {
+        const planReviews = ctx.state.reviews.plan ?? [];
+        const codeReviews = ctx.state.reviews.code ?? [];
+        const ticketsDone = ctx.state.completedTickets.length;
+        const planFindings = planReviews.reduce((sum, r) => sum + (r.findingCount ?? 0), 0);
+        const planCritical = planReviews.reduce((sum, r) => sum + (r.criticalCount ?? 0), 0);
+        const planMajor = planReviews.reduce((sum, r) => sum + (r.majorCount ?? 0), 0);
+        const codeFindings = codeReviews.reduce((sum, r) => sum + (r.findingCount ?? 0), 0);
+        const codeCritical = codeReviews.reduce((sum, r) => sum + (r.criticalCount ?? 0), 0);
+        const codeMajor = codeReviews.reduce((sum, r) => sum + (r.majorCount ?? 0), 0);
+        const totalFindings = planFindings + codeFindings;
+        if (totalFindings === 0) {
+          ctx.appendEvent("lesson_capture", { result: "no_findings", ticketsDone });
+          return { action: "advance" };
+        }
+        ctx.appendEvent("lesson_capture", {
+          result: "started",
+          ticketsDone,
+          planFindings,
+          codeFindings
+        });
+        return {
+          instruction: [
+            "# Capture Lessons from Review Findings",
+            "",
+            `This session completed ${ticketsDone} ticket(s). Review summary:`,
+            `- **Plan reviews:** ${planReviews.length} round(s), ${planCritical} critical, ${planMajor} major, ${planFindings} total findings`,
+            `- **Code reviews:** ${codeReviews.length} round(s), ${codeCritical} critical, ${codeMajor} major, ${codeFindings} total findings`,
+            "",
+            "Review these findings for recurring patterns worth capturing as lessons:",
+            "",
+            "1. Call `claudestory_lesson_list` to see existing lessons",
+            "2. For each pattern that recurred or was critical/major:",
+            "   - If it matches an existing lesson \u2192 call `claudestory_lesson_reinforce`",
+            '   - If it\'s a new pattern \u2192 call `claudestory_lesson_create` with `source: "review"`',
+            "3. Skip patterns that are one-off or already well-covered",
+            `4. Call \`claudestory_autonomous_guide\` with completedAction: "lessons_captured"`,
+            "",
+            "```json",
+            `{ "sessionId": "${ctx.state.sessionId}", "action": "report", "report": { "completedAction": "lessons_captured" } }`,
+            "```"
+          ].join("\n"),
+          reminders: [
+            "Check existing lessons first \u2014 reinforce before creating duplicates.",
+            "Only capture patterns worth remembering across sessions."
+          ]
+        };
+      }
+      async report(ctx, _report) {
+        ctx.appendEvent("lesson_capture", { result: "completed" });
+        return { action: "advance" };
+      }
+    };
+  }
+});
+
 // src/autonomous/stages/issue-sweep.ts
 var IssueSweepStage;
 var init_issue_sweep = __esm({
@@ -7611,6 +7717,7 @@ var init_stages = __esm({
     init_verify();
     init_finalize();
     init_complete();
+    init_lesson_capture();
     init_issue_sweep();
     init_handover2();
     registerStage(new PickTicketStage());
@@ -7623,6 +7730,7 @@ var init_stages = __esm({
     registerStage(new VerifyStage());
     registerStage(new FinalizeStage());
     registerStage(new CompleteStage());
+    registerStage(new LessonCaptureStage());
     registerStage(new IssueSweepStage());
     registerStage(new HandoverStage());
   }
@@ -8238,7 +8346,8 @@ async function processAdvance(ctx, currentStage, advance, depth = 0) {
       }
       if (next.kind === "exhausted") {
         const postComplete = ctx.state.resolvedPostComplete ?? ctx.recipe.postComplete;
-        const post = findFirstPostComplete(postComplete, ctx);
+        const isInPostComplete = postComplete.includes(currentStage.id);
+        const post = isInPostComplete ? findNextPostComplete(postComplete, currentStage.id, ctx) : findFirstPostComplete(postComplete, ctx);
         if (post.kind === "found") {
           assertTransition(currentStage.id, post.stage.id);
           ctx.writeState({ state: post.stage.id, previousState: currentStage.id });
@@ -8384,6 +8493,7 @@ async function handleResume(root, args) {
       // 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
     };
@@ -10129,7 +10239,7 @@ var init_mcp = __esm({
     init_init();
     ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
     CONFIG_PATH2 = ".story/config.json";
-    version = "0.1.27";
+    version = "0.1.29";
     main().catch((err) => {
       process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}
 `);
@@ -13407,7 +13517,7 @@ async function runCli() {
     registerConfigCommand: registerConfigCommand2,
     registerSessionCommand: registerSessionCommand2
   } = await Promise.resolve().then(() => (init_register(), register_exports));
-  const version2 = "0.1.27";
+  const version2 = "0.1.29";
   class HandledError extends Error {
     constructor() {
       super("HANDLED_ERROR");

package/dist/index.d.ts

@@ -561,6 +561,9 @@ declare class ProjectState {
      */
     isBlocked(ticket: Ticket): boolean;
     get blockedCount(): number;
+    /** True when the project has been initialized but not yet populated with tickets/issues/handovers. */
+    get isEmptyScaffold(): boolean;
+    private get isDefaultScaffoldPhases();
     ticketByID(id: string): Ticket | undefined;
     issueByID(id: string): Issue | undefined;
     noteByID(id: string): Note | undefined;
@@ -1722,6 +1725,8 @@ declare function buildRecap(currentState: ProjectState, snapshotInfo: {
     filename: string;
 } | null): RecapResult;
 
+/** SKILL PROTOCOL: SKILL.md Step 2b matches this literal string. Do not change without updating SKILL.md. */
+declare const EMPTY_SCAFFOLD_HEADING = "## Getting Started";
 declare const ExitCode: {
     readonly OK: 0;
     readonly USER_ERROR: 1;
@@ -1792,6 +1797,6 @@ declare function formatSnapshotResult(result: {
 }, format: OutputFormat): string;
 declare function formatRecap(recap: RecapResult, state: ProjectState, format: OutputFormat): string;
 declare function formatExport(state: ProjectState, mode: "all" | "phase", phaseId: string | null, format: OutputFormat): string;
-declare function formatRecommendations(result: RecommendResult, format: OutputFormat): string;
+declare function formatRecommendations(result: RecommendResult, state: ProjectState, format: OutputFormat): string;
 
-export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, NOTE_ID_REGEX, NOTE_STATUSES, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, type Note, NoteIdSchema, NoteSchema, type NoteStatus, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type RecommendCategory, type RecommendItemKind, type RecommendResult, type Recommendation, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteNote, deleteTicket, descendantLeaves, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverCreateResult, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatRecommendations, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextNoteID, nextOrder, nextTicket, nextTicketID, nextTickets, partialEnvelope, phasesWithStatus, readHandover, recommend, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeNote, writeNoteUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };
+export { type Blocker, BlockerSchema, CURRENT_SCHEMA_VERSION, type Config, ConfigSchema, DATE_REGEX, DateSchema, EMPTY_SCAFFOLD_HEADING, ERROR_CODES, type ErrorCode, type ErrorEnvelope, ExitCode, type ExitCodeValue, type Features, FeaturesSchema, INTEGRITY_WARNING_TYPES, ISSUE_ID_REGEX, ISSUE_SEVERITIES, ISSUE_STATUSES, type InitOptions, type InitResult, type Issue, IssueIdSchema, IssueSchema, type IssueSeverity, type IssueStatus, type LoadOptions, type LoadResult, type LoadWarning, type LoadWarningType, NOTE_ID_REGEX, NOTE_STATUSES, type NextTicketAllBlocked, type NextTicketAllComplete, type NextTicketEmpty, type NextTicketOutcome, type NextTicketResult, type Note, NoteIdSchema, NoteSchema, type NoteStatus, OUTPUT_FORMATS, type OutputFormat, type PartialEnvelope, type Phase, PhaseSchema, type PhaseStatus, type PhaseWithStatus, ProjectLoaderError, ProjectState, type RecapResult, type RecommendCategory, type RecommendItemKind, type RecommendResult, type Recommendation, type Roadmap, RoadmapSchema, type SnapshotDiff, type SnapshotV1, SnapshotV1Schema, type SuccessEnvelope, TICKET_ID_REGEX, TICKET_STATUSES, TICKET_TYPES, type Ticket, TicketIdSchema, TicketSchema, type TicketStatus, type TicketType, type UmbrellaProgress, type UnblockImpact, type ValidationFinding, type ValidationLevel, type ValidationResult, type WithProjectLockOptions, atomicWrite, blockedTickets, buildRecap, currentPhase, deleteIssue, deleteNote, deleteTicket, descendantLeaves, diffStates, discoverProjectRoot, errorEnvelope, escapeMarkdownInline, extractHandoverDate, fencedBlock, formatBlockedTickets, formatBlockerList, formatError, formatExport, formatHandoverContent, formatHandoverCreateResult, formatHandoverList, formatInitResult, formatIssue, formatIssueList, formatNextTicketOutcome, formatPhaseList, formatPhaseTickets, formatRecap, formatRecommendations, formatSnapshotResult, formatStatus, formatTicket, formatTicketList, formatValidation, guardPath, initProject, isBlockerCleared, listHandovers, loadLatestSnapshot, loadProject, mergeValidation, nextIssueID, nextNoteID, nextOrder, nextTicket, nextTicketID, nextTickets, partialEnvelope, phasesWithStatus, readHandover, recommend, runTransaction, runTransactionUnlocked, saveSnapshot, serializeJSON, sortKeysDeep, successEnvelope, ticketsUnblockedBy, umbrellaProgress, validateProject, withProjectLock, writeConfig, writeIssue, writeIssueUnlocked, writeNote, writeNoteUnlocked, writeRoadmap, writeRoadmapUnlocked, writeTicket, writeTicketUnlocked };

package/dist/index.js

@@ -326,6 +326,15 @@ var ProjectState = class _ProjectState {
   get blockedCount() {
     return this.leafTickets.filter((t) => t.status !== "complete" && this.isBlocked(t)).length;
   }
+  /** True when the project has been initialized but not yet populated with tickets/issues/handovers. */
+  get isEmptyScaffold() {
+    return this.tickets.length === 0 && this.issues.length === 0 && this.handoverFilenames.length === 0 && this.isDefaultScaffoldPhases;
+  }
+  get isDefaultScaffoldPhases() {
+    const { phases } = this.roadmap;
+    if (phases.length === 0) return true;
+    return phases.length === 1 && phases[0].id === "p0";
+  }
   ticketByID(id) {
     return this.ticketsByID.get(id);
   }
@@ -2289,6 +2298,7 @@ async function pruneSnapshots(dir) {
 }
 
 // src/core/output-formatter.ts
+var EMPTY_SCAFFOLD_HEADING = "## Getting Started";
 var ExitCode = {
   OK: 0,
   USER_ERROR: 1,
@@ -2343,6 +2353,7 @@ function formatStatus(state, format) {
     activeLessons: state.activeLessonCount,
     deprecatedLessons: state.deprecatedLessonCount,
     handovers: state.handoverFilenames.length,
+    isEmptyScaffold: state.isEmptyScaffold,
     phases: phases.map((p) => ({
       id: p.phase.id,
       name: p.phase.name,
@@ -2370,6 +2381,13 @@ 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 (state.isEmptyScaffold) {
+    lines.push("");
+    lines.push(EMPTY_SCAFFOLD_HEADING);
+    lines.push("");
+    lines.push("This project has been initialized but has no tickets, issues, or handovers yet.");
+    lines.push("Run the /story setup flow to analyze your project and create an initial roadmap.");
+  }
   return lines.join("\n");
 }
 function formatPhaseList(state, format) {
@@ -2967,11 +2985,14 @@ function formatTicketOneLiner(t, state) {
   const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
   return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
 }
-function formatRecommendations(result, format) {
+function formatRecommendations(result, state, format) {
   if (format === "json") {
-    return JSON.stringify(successEnvelope(result), null, 2);
+    return JSON.stringify(successEnvelope({ ...result, isEmptyScaffold: state.isEmptyScaffold }), null, 2);
   }
   if (result.recommendations.length === 0) {
+    if (state.isEmptyScaffold) {
+      return "No recommendations yet \u2014 this project needs tickets and phases. Run the /story setup flow to get started.";
+    }
     return "No recommendations \u2014 all work is complete or blocked.";
   }
   const lines = ["# Recommendations", ""];
@@ -2996,6 +3017,7 @@ export {
   ConfigSchema,
   DATE_REGEX,
   DateSchema,
+  EMPTY_SCAFFOLD_HEADING,
   ERROR_CODES,
   ExitCode,
   FeaturesSchema,

package/dist/mcp.js

@@ -433,6 +433,15 @@ var init_project_state = __esm({
       get blockedCount() {
         return this.leafTickets.filter((t) => t.status !== "complete" && this.isBlocked(t)).length;
       }
+      /** True when the project has been initialized but not yet populated with tickets/issues/handovers. */
+      get isEmptyScaffold() {
+        return this.tickets.length === 0 && this.issues.length === 0 && this.handoverFilenames.length === 0 && this.isDefaultScaffoldPhases;
+      }
+      get isDefaultScaffoldPhases() {
+        const { phases } = this.roadmap;
+        if (phases.length === 0) return true;
+        return phases.length === 1 && phases[0].id === "p0";
+      }
       ticketByID(id) {
         return this.ticketsByID.get(id);
       }
@@ -1563,6 +1572,7 @@ function formatStatus(state, format) {
     activeLessons: state.activeLessonCount,
     deprecatedLessons: state.deprecatedLessonCount,
     handovers: state.handoverFilenames.length,
+    isEmptyScaffold: state.isEmptyScaffold,
     phases: phases.map((p) => ({
       id: p.phase.id,
       name: p.phase.name,
@@ -1590,6 +1600,13 @@ 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 (state.isEmptyScaffold) {
+    lines.push("");
+    lines.push(EMPTY_SCAFFOLD_HEADING);
+    lines.push("");
+    lines.push("This project has been initialized but has no tickets, issues, or handovers yet.");
+    lines.push("Run the /story setup flow to analyze your project and create an initial roadmap.");
+  }
   return lines.join("\n");
 }
 function formatPhaseList(state, format) {
@@ -2356,11 +2373,14 @@ function formatTicketOneLiner(t, state) {
   const blocked = state.isBlocked(t) ? " [BLOCKED]" : "";
   return `${status} ${t.id}: ${escapeMarkdownInline(t.title)}${blocked}`;
 }
-function formatRecommendations(result, format) {
+function formatRecommendations(result, state, format) {
   if (format === "json") {
-    return JSON.stringify(successEnvelope(result), null, 2);
+    return JSON.stringify(successEnvelope({ ...result, isEmptyScaffold: state.isEmptyScaffold }), null, 2);
   }
   if (result.recommendations.length === 0) {
+    if (state.isEmptyScaffold) {
+      return "No recommendations yet \u2014 this project needs tickets and phases. Run the /story setup flow to get started.";
+    }
     return "No recommendations \u2014 all work is complete or blocked.";
   }
   const lines = ["# Recommendations", ""];
@@ -2379,12 +2399,13 @@ function formatRecommendations(result, format) {
   }
   return lines.join("\n");
 }
-var ExitCode;
+var EMPTY_SCAFFOLD_HEADING, ExitCode;
 var init_output_formatter = __esm({
   "src/core/output-formatter.ts"() {
     "use strict";
     init_esm_shims();
     init_queries();
+    EMPTY_SCAFFOLD_HEADING = "## Getting Started";
     ExitCode = {
       OK: 0,
       USER_ERROR: 1,
@@ -3472,6 +3493,7 @@ var init_session_types = __esm({
       "COMPACT",
       "HANDOVER",
       "COMPLETE",
+      "LESSON_CAPTURE",
       "ISSUE_SWEEP",
       "SESSION_END"
     ];
@@ -4883,7 +4905,7 @@ function sortByPhaseAndOrder(tickets, phaseIndex) {
 init_output_formatter();
 function handleRecommend(ctx, count) {
   const result = recommend(ctx.state, count);
-  return { output: formatRecommendations(result, ctx.format) };
+  return { output: formatRecommendations(result, ctx.state, ctx.format) };
 }
 
 // src/cli/commands/snapshot.ts
@@ -5200,6 +5222,8 @@ var TRANSITIONS = {
   // pass → FINALIZE, fail → IMPLEMENT, retry
   FINALIZE: ["COMPLETE"],
   COMPLETE: ["PICK_TICKET", "HANDOVER", "ISSUE_SWEEP", "SESSION_END"],
+  LESSON_CAPTURE: ["ISSUE_SWEEP", "HANDOVER", "LESSON_CAPTURE"],
+  // advance → ISSUE_SWEEP, retry self, done → HANDOVER
   ISSUE_SWEEP: ["ISSUE_SWEEP", "HANDOVER", "PICK_TICKET"],
   // retry (next issue), done → HANDOVER, loop → PICK_TICKET
   HANDOVER: ["COMPACT", "SESSION_END", "PICK_TICKET"],
@@ -5559,6 +5583,18 @@ function findFirstPostComplete(postComplete, ctx) {
   }
   return { kind: "exhausted" };
 }
+function findNextPostComplete(postComplete, currentId, ctx) {
+  const currentIndex = postComplete.indexOf(currentId);
+  const startIndex = currentIndex >= 0 ? currentIndex + 1 : 0;
+  for (let i = startIndex; i < postComplete.length; i++) {
+    const id = postComplete[i];
+    const stage = stages.get(id);
+    if (!stage) return { kind: "unregistered", id };
+    if (stage.skip?.(ctx)) continue;
+    return { kind: "found", stage };
+  }
+  return { kind: "exhausted" };
+}
 
 // src/autonomous/stages/types.ts
 init_esm_shims();
@@ -6915,6 +6951,68 @@ var CompleteStage = class {
   }
 };
 
+// src/autonomous/stages/lesson-capture.ts
+init_esm_shims();
+var LessonCaptureStage = class {
+  id = "LESSON_CAPTURE";
+  skip(ctx) {
+    const config = ctx.recipe.stages?.LESSON_CAPTURE;
+    return !config?.enabled;
+  }
+  async enter(ctx) {
+    const planReviews = ctx.state.reviews.plan ?? [];
+    const codeReviews = ctx.state.reviews.code ?? [];
+    const ticketsDone = ctx.state.completedTickets.length;
+    const planFindings = planReviews.reduce((sum, r) => sum + (r.findingCount ?? 0), 0);
+    const planCritical = planReviews.reduce((sum, r) => sum + (r.criticalCount ?? 0), 0);
+    const planMajor = planReviews.reduce((sum, r) => sum + (r.majorCount ?? 0), 0);
+    const codeFindings = codeReviews.reduce((sum, r) => sum + (r.findingCount ?? 0), 0);
+    const codeCritical = codeReviews.reduce((sum, r) => sum + (r.criticalCount ?? 0), 0);
+    const codeMajor = codeReviews.reduce((sum, r) => sum + (r.majorCount ?? 0), 0);
+    const totalFindings = planFindings + codeFindings;
+    if (totalFindings === 0) {
+      ctx.appendEvent("lesson_capture", { result: "no_findings", ticketsDone });
+      return { action: "advance" };
+    }
+    ctx.appendEvent("lesson_capture", {
+      result: "started",
+      ticketsDone,
+      planFindings,
+      codeFindings
+    });
+    return {
+      instruction: [
+        "# Capture Lessons from Review Findings",
+        "",
+        `This session completed ${ticketsDone} ticket(s). Review summary:`,
+        `- **Plan reviews:** ${planReviews.length} round(s), ${planCritical} critical, ${planMajor} major, ${planFindings} total findings`,
+        `- **Code reviews:** ${codeReviews.length} round(s), ${codeCritical} critical, ${codeMajor} major, ${codeFindings} total findings`,
+        "",
+        "Review these findings for recurring patterns worth capturing as lessons:",
+        "",
+        "1. Call `claudestory_lesson_list` to see existing lessons",
+        "2. For each pattern that recurred or was critical/major:",
+        "   - If it matches an existing lesson \u2192 call `claudestory_lesson_reinforce`",
+        '   - If it\'s a new pattern \u2192 call `claudestory_lesson_create` with `source: "review"`',
+        "3. Skip patterns that are one-off or already well-covered",
+        `4. Call \`claudestory_autonomous_guide\` with completedAction: "lessons_captured"`,
+        "",
+        "```json",
+        `{ "sessionId": "${ctx.state.sessionId}", "action": "report", "report": { "completedAction": "lessons_captured" } }`,
+        "```"
+      ].join("\n"),
+      reminders: [
+        "Check existing lessons first \u2014 reinforce before creating duplicates.",
+        "Only capture patterns worth remembering across sessions."
+      ]
+    };
+  }
+  async report(ctx, _report) {
+    ctx.appendEvent("lesson_capture", { result: "completed" });
+    return { action: "advance" };
+  }
+};
+
 // src/autonomous/stages/issue-sweep.ts
 init_esm_shims();
 var IssueSweepStage = class {
@@ -7105,6 +7203,7 @@ registerStage(new CodeReviewStage());
 registerStage(new VerifyStage());
 registerStage(new FinalizeStage());
 registerStage(new CompleteStage());
+registerStage(new LessonCaptureStage());
 registerStage(new IssueSweepStage());
 registerStage(new HandoverStage());
 
@@ -7728,7 +7827,8 @@ async function processAdvance(ctx, currentStage, advance, depth = 0) {
       }
       if (next.kind === "exhausted") {
         const postComplete = ctx.state.resolvedPostComplete ?? ctx.recipe.postComplete;
-        const post = findFirstPostComplete(postComplete, ctx);
+        const isInPostComplete = postComplete.includes(currentStage.id);
+        const post = isInPostComplete ? findNextPostComplete(postComplete, currentStage.id, ctx) : findFirstPostComplete(postComplete, ctx);
         if (post.kind === "found") {
           assertTransition(currentStage.id, post.stage.id);
           ctx.writeState({ state: post.stage.id, previousState: currentStage.id });
@@ -7874,6 +7974,7 @@ async function handleResume(root, args) {
       // 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
     };
@@ -9294,7 +9395,7 @@ async function ensureGitignoreEntries(gitignorePath, entries) {
 // src/mcp/index.ts
 var ENV_VAR2 = "CLAUDESTORY_PROJECT_ROOT";
 var CONFIG_PATH2 = ".story/config.json";
-var version = "0.1.27";
+var version = "0.1.29";
 function tryDiscoverRoot() {
   const envRoot = process.env[ENV_VAR2];
   if (envRoot) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropologies/claudestory",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "license": "UNLICENSED",
   "description": "Cross-session context persistence for AI coding projects. Tracks tickets, issues, roadmap, and handovers so every session builds on the last.",
   "keywords": [

package/src/skill/SKILL.md

@@ -199,6 +199,14 @@ Call these in order:
 5. **Lessons learned** — call `claudestory_lesson_digest` MCP tool
 6. **Recent commits** — run `git log --oneline -10`
 
+## Step 2b: Empty Scaffold Check
+
+After `claudestory_status` returns, check in order:
+
+1. **Integrity guard** — if the response starts with "Warning:" and contains "item(s) skipped due to data integrity issues", this is NOT an empty scaffold. Tell the user to run `claudestory validate`. Continue Step 2/3 normally.
+2. **Scaffold detection** — check BOTH: output contains "## Getting Started" AND shows `Tickets: 0/0 complete` + `Handovers: 0`. If met AND the project has code indicators (git history, package manifest, source files), route to the AI-Assisted Setup Flow (section 1b above) instead of Step 3. Skip remaining Step 2 calls and Step 3.
+3. **Empty without code** — if scaffold detected but no code indicators (truly empty directory), continue to Step 3 which will show: "Your project is set up but has no tickets yet. Would you like me to help you create your first phase and tickets?"
+
 ## Step 3: Present Summary
 
 After loading context, present a concise summary: