ai-spec-dev 0.28.1 → 0.29.0

package/README.md

@@ -463,15 +463,34 @@ ai-spec review specs/feature-1234567890.md
 ai-spec review --provider glm --model glm-5
 ```
 
-**输出结构：**
+**3-pass 输出结构：**
 
 ```
+─── Pass 1/3: Architecture review ───────────────
 ## ✅ 优点 (What's Good)
 ## ⚠️ 问题 (Issues Found)
 ## 💡 改进建议 (Suggestions)
 ## 📊 总体评价 (Overall Assessment)  Score: X/10
+
+─── Pass 2/3: Implementation review ─────────────
+## ✅ 优点 (What's Good)
+## ⚠️ 问题 (Issues Found)
+## 🔁 历史问题复现 (Recurring Issues)
+## 💡 改进建议 (Suggestions)
+## 📊 综合评分 (Final Score)  Score: X/10
+
+─── Pass 3/3: Impact & complexity assessment ────
+## 🌊 影响面评估 (Impact Assessment)
+   直接影响文件 / 间接范围 / Breaking Changes / 影响等级: 低|中|高
+## 🧮 代码复杂度评估 (Complexity Assessment)
+   认知复杂度热点 / 耦合度 / 可维护性风险 / 复杂度等级: 低|中|高
+
+─── Review Score Trend ──────────────────────────
+  2026-03-26  [████████░░] 8/10 影响:中 复杂度:低  feature-login-v1.md
 ```
 
+> Pass 3 的影响等级和复杂度等级会持久化到 `.ai-spec-reviews.json`，在历史趋势行中显示，三级颜色编码：高=红、中=黄、低=绿。
+
 > 提示：先执行 `git add .` 再运行 `ai-spec review`，确保所有变更都被纳入审查。
 
 ---
@@ -600,6 +619,11 @@ ai-spec update "修复描述文字" --skip-affected
 | `--provider <name>` | Spec 更新使用的 provider |
 | `--codegen-provider <name>` | 代码生成使用的 provider |
 
+> **`--codegen` 附带行为（v0.29.0+）**：
+> - 每次 update 自动生成独立 Run ID，运行摘要（耗时、写入文件数）在结束时打印
+> - 写每个受影响文件前先快照原始内容（`.ai-spec-backup/<runId>/`），可用 `ai-spec restore <runId>` 精确回滚
+> - 完成后自动对更新后的 Spec 运行代码审查，结论写入宪法 §9（与 `create` 的知识积累机制一致）
+
 ---
 
 ### `ai-spec export`

package/RELEASE_LOG.md

@@ -2,6 +2,64 @@
 
 ---
 
+## [0.29.0] 2026-03-27 — 全量审查修复（RunLogger 插桩、update 快照、Score Trend 升级、死代码清理）
+
+### 修复内容
+
+**Fix #1 — RunLogger 各阶段从未插桩（结构化日志实际为空）**
+- 文件：`cli/index.ts`（create 命令主流水线）
+- 问题：`core/run-logger.ts` 设计了完整的 `stageStart()`/`stageEnd()`/`stageFail()` API，但 CLI 中从未调用，生成的 `.ai-spec-logs/<runId>.json` 的 `entries[]` 数组始终为空——只有开始/结束时间戳和文件列表，丧失了每阶段耗时的核心价值。
+- 修复：在 `create` 流水线所有主要阶段添加 stage 调用，覆盖以下 8 个节点：
+
+  | Stage Key | 对应步骤 | 记录数据 |
+  |---|---|---|
+  | `context_load` | Step 1 — 加载项目上下文 | `techStack`, `repoType` |
+  | `spec_gen` | Step 2 — Spec + Tasks 生成 | `provider`, `model`, `taskCount`；失败时 `stageFail` |
+  | `spec_refine` | Step 3 — 交互式润色 | 耗时 |
+  | `spec_assess` | Step 3.4 — Spec 质量评估 | `overallScore`；gate 失败时 `stageFail` |
+  | `dsl_extract` | DSL — 结构化提取 | `endpoints`, `models` 数量；提取失败时 `stageFail` |
+  | `codegen` | Step 6 — 代码生成 | `mode`, `provider`, `model`, `filesGenerated` |
+  | `test_gen` | Step 7 — 测试骨架生成 | `filesGenerated` |
+  | `error_feedback` | Step 8 — 错误反馈闭环 | 耗时 |
+  | `review` | Step 9 — 3-pass 代码审查 | 耗时 |
+
+**Fix #2 — `update --codegen` 写文件前无快照，运行结束无日志**
+- 文件：`cli/index.ts`（update 命令）
+- 问题：`update --codegen` 直接改写受影响文件，但 `setActiveSnapshot()`/`setActiveLogger()` 只在 `create` 命令中调用，`getActiveSnapshot()?.snapshotFile()` 因返回 `null` 而静默跳过，用户无法对 update 产生的改动执行 `ai-spec restore`。
+- 修复：
+  - update 命令启动时生成独立 `updateRunId`，初始化 `RunSnapshot` 和 `RunLogger` 并注册为 active 单例
+  - 写每个受影响文件前调用 `updateSnapshot.snapshotFile(fullPath)`，现在 `ai-spec restore <updateRunId>` 对 update 生成的改动同样有效
+  - 写文件后调用 `updateLogger.fileWritten()`
+  - `update_codegen` stage 包含 `stageStart`/`stageEnd`/`stageFail`
+  - 命令结束时 `finish()` + `printSummary()` + restore 提示（与 create 对齐）
+
+**Fix #3 — `update --codegen` 结束后不积累审查知识**
+- 文件：`cli/index.ts`（update 命令）
+- 问题：`create` 流水线最后会用 `accumulateReviewKnowledge()` 把 review 结论写入宪法 §9；`update --codegen` 虽然也修改了代码，但流程结束后什么都不写。团队在 update 阶段发现的问题从来不进入知识库，宪法无法从迭代修改中学习。
+- 修复：`update --codegen` 完成文件写入后，自动对更新后的 Spec 运行一次 `reviewer.reviewCode()`，并将结果传入 `accumulateReviewKnowledge()`，复用 spec 更新阶段已创建的 `provider` 实例，无需额外配置。
+
+**Fix #4 — `reviewSystemPrompt` 旧版单体 prompt 变为死代码未清理**
+- 文件：`prompts/codegen.prompt.ts`、`core/reviewer.ts`
+- 问题：v0.28.0 升级为 3-pass 后，旧的整合式 `reviewSystemPrompt`（18 行）仍在 `codegen.prompt.ts` 中导出，并被 `reviewer.ts` import 但不在任何地方调用，造成维护混淆。
+- 修复：删除 `codegen.prompt.ts` 中的 `reviewSystemPrompt` export，同步删除 `reviewer.ts` 中的对应 import；注释由 `// ─── Two-pass review prompts` 更新为 `// ─── 3-pass review prompts`。
+
+### 功能增强
+
+**Enhancement — `printScoreTrend()` 新增影响等级 / 复杂度等级展示**
+- 文件：`core/reviewer.ts`
+- 背景：v0.28.0 审查历史 `ReviewHistoryEntry` 已增加 `impactLevel` 和 `complexityLevel` 字段并持久化，但 `printScoreTrend()` 展示趋势时从未读取这两个字段，用户看不到任何影响 / 复杂度信息。
+- 修复：每行趋势输出追加两个彩色标签，颜色编码：高=红、中=黄、低=绿。
+
+  ```
+  前（只有分数）:
+    2026-03-26  [████████░░] 8/10  feature-tasks-v1.md
+
+  后（新增等级标签）:
+    2026-03-26  [████████░░] 8/10 影响:中 复杂度:低  feature-tasks-v1.md
+  ```
+
+---
+
 ## [0.28.0] 2026-03-26 — 三 Pass 代码审查（影响面评估 + 代码复杂度评估）
 
 ### 新增内容

package/cli/index.ts

@@ -308,9 +308,11 @@ program
 
     // ── Step 1: Context ───────────────────────────────────────────────────────
     console.log(chalk.blue("[1/6] Loading project context..."));
+    runLogger.stageStart("context_load");
     const loader = new ContextLoader(currentDir);
     const context = await loader.loadProjectContext();
     const { type: detectedRepoType } = await detectRepoType(currentDir);
+    runLogger.stageEnd("context_load", { techStack: context.techStack, repoType: detectedRepoType });
     console.log(chalk.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
     console.log(chalk.gray(`  Dependencies: ${context.dependencies.length} packages`));
     console.log(chalk.gray(`  API files   : ${context.apiStructure.length} files`));
@@ -345,6 +347,7 @@ program
     let initialSpec: string;
     let initialTasks: import("../core/task-generator").SpecTask[] = [];
 
+    runLogger.stageStart("spec_gen", { provider: specProviderName, model: specModelName });
     try {
       if (opts.skipTasks) {
         // Tasks skipped: use SpecGenerator alone
@@ -363,7 +366,9 @@ program
           console.log(chalk.yellow("  ⚠ Tasks not parsed from response — will retry separately after refinement."));
         }
       }
+      runLogger.stageEnd("spec_gen", { taskCount: initialTasks.length });
     } catch (err) {
+      runLogger.stageFail("spec_gen", (err as Error).message);
       console.error(chalk.red("  ✘ Spec generation failed:"), err);
       process.exit(1);
     }
@@ -375,8 +380,10 @@ program
       finalSpec = initialSpec;
     } else {
       console.log(chalk.blue("\n[3/6] Interactive spec refinement..."));
+      runLogger.stageStart("spec_refine");
       const refiner = new SpecRefiner(specProvider);
       finalSpec = await refiner.refineLoop(initialSpec);
+      runLogger.stageEnd("spec_refine");
     }
 
     // Compute slug once — used in Approval Gate diff preview and versioned file save
@@ -393,14 +400,17 @@ program
       if (!opts.auto) {
         console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
       }
+      runLogger.stageStart("spec_assess");
       const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? undefined);
       if (assessment) {
+        runLogger.stageEnd("spec_assess", { overallScore: assessment.overallScore });
         if (!opts.auto) printSpecAssessment(assessment);
 
         if (minScore > 0 && assessment.overallScore < minScore) {
           if (opts.force) {
             console.log(chalk.yellow(`\n  ⚠ Score gate: ${assessment.overallScore}/10 < minimum ${minScore}/10 — bypassed with --force.`));
           } else {
+            runLogger.stageFail("spec_assess", `Score gate: ${assessment.overallScore} < ${minScore}`);
             console.log(chalk.red(`\n  ✘ Spec quality gate failed: overallScore ${assessment.overallScore}/10 < minimum ${minScore}/10`));
             if (!opts.auto) {
               console.log(chalk.gray(`  Address the issues above and re-run, or use --force to bypass.`));
@@ -411,8 +421,11 @@ program
             process.exit(1);
           }
         }
-      } else if (!opts.auto) {
-        console.log(chalk.gray("  (Assessment skipped — AI call failed or timed out)"));
+      } else {
+        runLogger.stageEnd("spec_assess", { skipped: true });
+        if (!opts.auto) {
+          console.log(chalk.gray("  (Assessment skipped — AI call failed or timed out)"));
+        }
       }
     }
 
@@ -485,18 +498,22 @@ program
     } else {
       console.log(chalk.blue("\n[DSL] Extracting structured DSL from spec..."));
       console.log(chalk.gray(`  Provider: ${specProviderName}/${specModelName}`));
+      runLogger.stageStart("dsl_extract");
       try {
         const isFrontend = isFrontendDeps(context.dependencies);
         if (isFrontend) console.log(chalk.gray("  Frontend project detected — using ComponentSpec extractor"));
         const dslExtractor = new DslExtractor(specProvider);
         extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
         if (extractedDsl) {
+          runLogger.stageEnd("dsl_extract", { endpoints: extractedDsl.endpoints?.length ?? 0, models: extractedDsl.models?.length ?? 0 });
           console.log(chalk.green("  ✔ DSL extracted and validated."));
         } else {
+          runLogger.stageEnd("dsl_extract", { skipped: true });
           console.log(chalk.yellow("  ⚠ DSL skipped — codegen will use Spec + Tasks only."));
         }
       } catch (err) {
         // Unexpected error (not user abort — that would have called process.exit)
+        runLogger.stageFail("dsl_extract", (err as Error).message);
         console.log(chalk.yellow(`  ⚠ DSL extraction error: ${(err as Error).message} — continuing without DSL.`));
       }
     }
@@ -581,6 +598,7 @@ program
       generatedTestFiles = await testGen.generateTdd(extractedDsl, workingDir);
     }
 
+    runLogger.stageStart("codegen", { mode: codegenMode, provider: codegenProviderName, model: codegenModelName });
     const codegen = new CodeGenerator(codegenProvider, codegenMode);
     const generatedFiles = await codegen.generateCode(specFile, workingDir, context, {
       auto: opts.auto,
@@ -588,6 +606,7 @@ program
       dslFilePath: savedDslFile ?? undefined,
       repoType: detectedRepoType,
     });
+    runLogger.stageEnd("codegen", { filesGenerated: generatedFiles.length });
 
     // ── Step 7: Test Skeleton Generation (skipped in TDD mode — tests already written) ──
     if (opts.tdd) {
@@ -598,8 +617,10 @@ program
       console.log(chalk.gray("\n[7/9] Skipping test generation (no DSL available)."));
     } else {
       console.log(chalk.blue(`\n[7/9] Test skeleton generation...`));
+      runLogger.stageStart("test_gen");
       const testGen = new TestGenerator(codegenProvider);
       generatedTestFiles = await testGen.generate(extractedDsl, workingDir);
+      runLogger.stageEnd("test_gen", { filesGenerated: generatedTestFiles.length });
     }
 
     // ── Step 8: Error Feedback Loop ───────────────────────────────────────────
@@ -611,15 +632,18 @@ program
       if (opts.tdd) {
         console.log(chalk.cyan("[8/9] TDD mode — error feedback loop driving implementation to pass tests..."));
       }
+      runLogger.stageStart("error_feedback");
       await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
         maxCycles: opts.tdd ? 3 : 2,  // TDD gets one extra cycle
       });
+      runLogger.stageEnd("error_feedback");
     }
 
     // ── Step 9: Code Review ───────────────────────────────────────────────────
     let reviewResult = "";
     if (!opts.skipReview) {
       console.log(chalk.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
+      runLogger.stageStart("review");
       const reviewer = new CodeReviewer(specProvider, currentDir);
       const savedSpec = await fs.readFile(specFile, "utf-8");
 
@@ -636,6 +660,7 @@ program
           process.chdir(originalDir);
         }
       }
+      runLogger.stageEnd("review");
 
       // Knowledge Memory: extract lessons from review and append to constitution §9
       await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
@@ -1790,6 +1815,14 @@ program
     console.log(chalk.blue("\n─── ai-spec update ─────────────────────────────"));
     console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
 
+    // ── Run tracking (snapshot + log) ─────────────────────────────────────────
+    const updateRunId = generateRunId();
+    const updateSnapshot = new RunSnapshot(currentDir, updateRunId);
+    setActiveSnapshot(updateSnapshot);
+    const updateLogger = new RunLogger(currentDir, updateRunId, { provider: providerName, model: modelName });
+    setActiveLogger(updateLogger);
+    console.log(chalk.gray(`  Run ID: ${updateRunId}`));
+
     // ── Find existing spec ────────────────────────────────────────────────────
     let specPath: string | null = opts.spec ?? null;
     if (!specPath) {
@@ -1860,6 +1893,7 @@ program
         ? `\n=== DSL Context ===\n${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3000)}\n`
         : "";
 
+      updateLogger.stageStart("update_codegen");
       for (const affected of result.affectedFiles) {
         const fullPath = path.join(currentDir, affected.file);
         let existing = "";
@@ -1883,12 +1917,34 @@ ${existing || "Create from scratch."}`;
           const raw = await codegenProvider.generate(codePrompt, _getPrompt(repoType));
           const content = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
           await fs.ensureDir(path.dirname(fullPath));
+          // Snapshot original before overwrite so `ai-spec restore` can undo
+          await updateSnapshot.snapshotFile(fullPath);
           await fs.writeFile(fullPath, content, "utf-8");
+          updateLogger.fileWritten(affected.file);
           console.log(chalk.green("✔"));
         } catch (err) {
+          updateLogger.stageFail("update_codegen", `${affected.file}: ${(err as Error).message}`);
           console.log(chalk.red(`✘ ${(err as Error).message}`));
         }
       }
+      updateLogger.stageEnd("update_codegen", { filesUpdated: result.affectedFiles.length });
+
+      // Knowledge Memory: run a lightweight review on the updated spec and accumulate lessons
+      const updatedSpecContent = await fs.readFile(result.newSpecPath, "utf-8").catch(() => "");
+      if (updatedSpecContent) {
+        const updateReviewer = new CodeReviewer(provider, currentDir);
+        const reviewResult = await updateReviewer.reviewCode(updatedSpecContent, result.newSpecPath).catch(() => "");
+        if (reviewResult && reviewResult !== "No changes") {
+          await accumulateReviewKnowledge(provider, currentDir, reviewResult);
+        }
+      }
+    }
+
+    // ── Finish run tracking ────────────────────────────────────────────────────
+    updateLogger.finish();
+    updateLogger.printSummary();
+    if (updateSnapshot.fileCount > 0) {
+      console.log(chalk.gray(`  To undo changes: ai-spec restore ${updateRunId}`));
     }
 
     // ── Hints ─────────────────────────────────────────────────────────────────

package/core/reviewer.ts

@@ -4,7 +4,6 @@ import * as path from "path";
 import * as fs from "fs-extra";
 import { AIProvider } from "./spec-generator";
 import {
-  reviewSystemPrompt,
   reviewArchitectureSystemPrompt,
   reviewImplementationSystemPrompt,
   reviewImpactComplexitySystemPrompt,
@@ -289,7 +288,13 @@ ${implReview}`;
     for (const entry of recent) {
       const bar = "█".repeat(entry.score) + "░".repeat(10 - entry.score);
       const color = entry.score >= 8 ? chalk.green : entry.score >= 6 ? chalk.yellow : chalk.red;
-      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}  ${path.basename(entry.specFile)}`);
+      const impactTag = entry.impactLevel
+        ? chalk.gray(` 影响:${entry.impactLevel === "高" ? chalk.red(entry.impactLevel) : entry.impactLevel === "中" ? chalk.yellow(entry.impactLevel) : chalk.green(entry.impactLevel)}`)
+        : "";
+      const complexityTag = entry.complexityLevel
+        ? chalk.gray(` 复杂度:${entry.complexityLevel === "高" ? chalk.red(entry.complexityLevel) : entry.complexityLevel === "中" ? chalk.yellow(entry.complexityLevel) : chalk.green(entry.complexityLevel)}`)
+        : "";
+      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}${impactTag}${complexityTag}  ${path.basename(entry.specFile)}`);
     }
     console.log(chalk.cyan("─────────────────────────────────────────────────"));
   }

package/dist/cli/index.js

@@ -42,8 +42,7 @@ __export(codegen_prompt_exports, {
   getCodeGenSystemPrompt: () => getCodeGenSystemPrompt,
   reviewArchitectureSystemPrompt: () => reviewArchitectureSystemPrompt,
   reviewImpactComplexitySystemPrompt: () => reviewImpactComplexitySystemPrompt,
-  reviewImplementationSystemPrompt: () => reviewImplementationSystemPrompt,
-  reviewSystemPrompt: () => reviewSystemPrompt
+  reviewImplementationSystemPrompt: () => reviewImplementationSystemPrompt
 });
 function getCodeGenSystemPrompt(repoType) {
   switch (repoType) {
@@ -61,7 +60,7 @@ function getCodeGenSystemPrompt(repoType) {
       return codeGenSystemPrompt;
   }
 }
-var codeGenSystemPrompt, codeGenGoSystemPrompt, codeGenPythonSystemPrompt, codeGenJavaSystemPrompt, codeGenRustSystemPrompt, codeGenPhpSystemPrompt, reviewSystemPrompt, reviewArchitectureSystemPrompt, reviewImplementationSystemPrompt, reviewImpactComplexitySystemPrompt;
+var codeGenSystemPrompt, codeGenGoSystemPrompt, codeGenPythonSystemPrompt, codeGenJavaSystemPrompt, codeGenRustSystemPrompt, codeGenPhpSystemPrompt, reviewArchitectureSystemPrompt, reviewImplementationSystemPrompt, reviewImpactComplexitySystemPrompt;
 var init_codegen_prompt = __esm({
   "prompts/codegen.prompt.ts"() {
     "use strict";
@@ -211,23 +210,6 @@ CRITICAL \u2014 File Reuse Rules:
 10. Register new routes in the EXISTING routes/api.php (or routes/web.php) \u2014 never create a parallel routes file.
 11. Add new Eloquent model methods to the EXISTING Model class \u2014 never create a parallel model file.
 12. Add new service methods to the EXISTING service class if one already covers the same resource.`;
-    reviewSystemPrompt = `You are a Senior Software Architect conducting a thorough code review. Your review should be structured, constructive, and specific.
-
-Always format your review with these exact sections:
-
-## \u2705 \u4F18\u70B9 (What's Good)
-List specific things done well.
-
-## \u26A0\uFE0F \u95EE\u9898 (Issues Found)
-List bugs, security issues, or spec deviations with line references.
-
-## \u{1F4A1} \u6539\u8FDB\u5EFA\u8BAE (Suggestions)
-Actionable improvements that would elevate code quality.
-
-## \u{1F4CA} \u603B\u4F53\u8BC4\u4EF7 (Overall Assessment)
-Score: X/10 \u2014 One-paragraph summary.
-
-Be specific. Reference actual code, not vague principles.`;
     reviewArchitectureSystemPrompt = `You are a Senior Software Architect reviewing the HIGH-LEVEL design of a code change.
 
 Focus ONLY on:
@@ -7047,7 +7029,9 @@ ${content.slice(0, 3e3)}`;
     for (const entry of recent) {
       const bar = "\u2588".repeat(entry.score) + "\u2591".repeat(10 - entry.score);
       const color = entry.score >= 8 ? import_chalk9.default.green : entry.score >= 6 ? import_chalk9.default.yellow : import_chalk9.default.red;
-      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}  ${path10.basename(entry.specFile)}`);
+      const impactTag = entry.impactLevel ? import_chalk9.default.gray(` \u5F71\u54CD:${entry.impactLevel === "\u9AD8" ? import_chalk9.default.red(entry.impactLevel) : entry.impactLevel === "\u4E2D" ? import_chalk9.default.yellow(entry.impactLevel) : import_chalk9.default.green(entry.impactLevel)}`) : "";
+      const complexityTag = entry.complexityLevel ? import_chalk9.default.gray(` \u590D\u6742\u5EA6:${entry.complexityLevel === "\u9AD8" ? import_chalk9.default.red(entry.complexityLevel) : entry.complexityLevel === "\u4E2D" ? import_chalk9.default.yellow(entry.complexityLevel) : import_chalk9.default.green(entry.complexityLevel)}`) : "";
+      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}${impactTag}${complexityTag}  ${path10.basename(entry.specFile)}`);
     }
     console.log(import_chalk9.default.cyan("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   }
@@ -10061,9 +10045,11 @@ program.command("create").description("Generate a feature spec and kick off code
   });
   setActiveLogger(runLogger);
   console.log(import_chalk19.default.blue("[1/6] Loading project context..."));
+  runLogger.stageStart("context_load");
   const loader = new ContextLoader(currentDir);
   const context = await loader.loadProjectContext();
   const { type: detectedRepoType } = await detectRepoType(currentDir);
+  runLogger.stageEnd("context_load", { techStack: context.techStack, repoType: detectedRepoType });
   console.log(import_chalk19.default.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
   console.log(import_chalk19.default.gray(`  Dependencies: ${context.dependencies.length} packages`));
   console.log(import_chalk19.default.gray(`  API files   : ${context.apiStructure.length} files`));
@@ -10094,6 +10080,7 @@ program.command("create").description("Generate a feature spec and kick off code
   const specProvider = createProvider(specProviderName, specApiKey, specModelName);
   let initialSpec;
   let initialTasks = [];
+  runLogger.stageStart("spec_gen", { provider: specProviderName, model: specModelName });
   try {
     if (opts.skipTasks) {
       const generator = new SpecGenerator(specProvider);
@@ -10110,7 +10097,9 @@ program.command("create").description("Generate a feature spec and kick off code
         console.log(import_chalk19.default.yellow("  \u26A0 Tasks not parsed from response \u2014 will retry separately after refinement."));
       }
     }
+    runLogger.stageEnd("spec_gen", { taskCount: initialTasks.length });
   } catch (err) {
+    runLogger.stageFail("spec_gen", err.message);
     console.error(import_chalk19.default.red("  \u2718 Spec generation failed:"), err);
     process.exit(1);
   }
@@ -10120,8 +10109,10 @@ program.command("create").description("Generate a feature spec and kick off code
     finalSpec = initialSpec;
   } else {
     console.log(import_chalk19.default.blue("\n[3/6] Interactive spec refinement..."));
+    runLogger.stageStart("spec_refine");
     const refiner = new SpecRefiner(specProvider);
     finalSpec = await refiner.refineLoop(initialSpec);
+    runLogger.stageEnd("spec_refine");
   }
   const featureSlug = slugify(idea);
   const minScore = config2.minSpecScore ?? 0;
@@ -10130,14 +10121,17 @@ program.command("create").description("Generate a feature spec and kick off code
     if (!opts.auto) {
       console.log(import_chalk19.default.blue("\n[3.4/6] Spec quality assessment..."));
     }
+    runLogger.stageStart("spec_assess");
     const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? void 0);
     if (assessment) {
+      runLogger.stageEnd("spec_assess", { overallScore: assessment.overallScore });
       if (!opts.auto) printSpecAssessment(assessment);
       if (minScore > 0 && assessment.overallScore < minScore) {
         if (opts.force) {
           console.log(import_chalk19.default.yellow(`
   \u26A0 Score gate: ${assessment.overallScore}/10 < minimum ${minScore}/10 \u2014 bypassed with --force.`));
         } else {
+          runLogger.stageFail("spec_assess", `Score gate: ${assessment.overallScore} < ${minScore}`);
           console.log(import_chalk19.default.red(`
   \u2718 Spec quality gate failed: overallScore ${assessment.overallScore}/10 < minimum ${minScore}/10`));
           if (!opts.auto) {
@@ -10149,8 +10143,11 @@ program.command("create").description("Generate a feature spec and kick off code
           process.exit(1);
         }
       }
-    } else if (!opts.auto) {
-      console.log(import_chalk19.default.gray("  (Assessment skipped \u2014 AI call failed or timed out)"));
+    } else {
+      runLogger.stageEnd("spec_assess", { skipped: true });
+      if (!opts.auto) {
+        console.log(import_chalk19.default.gray("  (Assessment skipped \u2014 AI call failed or timed out)"));
+      }
     }
   }
   if (!opts.auto) {
@@ -10208,17 +10205,21 @@ program.command("create").description("Generate a feature spec and kick off code
   } else {
     console.log(import_chalk19.default.blue("\n[DSL] Extracting structured DSL from spec..."));
     console.log(import_chalk19.default.gray(`  Provider: ${specProviderName}/${specModelName}`));
+    runLogger.stageStart("dsl_extract");
     try {
       const isFrontend = isFrontendDeps(context.dependencies);
       if (isFrontend) console.log(import_chalk19.default.gray("  Frontend project detected \u2014 using ComponentSpec extractor"));
       const dslExtractor = new DslExtractor(specProvider);
       extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
       if (extractedDsl) {
+        runLogger.stageEnd("dsl_extract", { endpoints: extractedDsl.endpoints?.length ?? 0, models: extractedDsl.models?.length ?? 0 });
         console.log(import_chalk19.default.green("  \u2714 DSL extracted and validated."));
       } else {
+        runLogger.stageEnd("dsl_extract", { skipped: true });
         console.log(import_chalk19.default.yellow("  \u26A0 DSL skipped \u2014 codegen will use Spec + Tasks only."));
       }
     } catch (err) {
+      runLogger.stageFail("dsl_extract", err.message);
       console.log(import_chalk19.default.yellow(`  \u26A0 DSL extraction error: ${err.message} \u2014 continuing without DSL.`));
     }
   }
@@ -10276,6 +10277,7 @@ program.command("create").description("Generate a feature spec and kick off code
     const testGen = new TestGenerator(codegenProvider);
     generatedTestFiles = await testGen.generateTdd(extractedDsl, workingDir);
   }
+  runLogger.stageStart("codegen", { mode: codegenMode, provider: codegenProviderName, model: codegenModelName });
   const codegen = new CodeGenerator(codegenProvider, codegenMode);
   const generatedFiles = await codegen.generateCode(specFile, workingDir, context, {
     auto: opts.auto,
@@ -10283,6 +10285,7 @@ program.command("create").description("Generate a feature spec and kick off code
     dslFilePath: savedDslFile ?? void 0,
     repoType: detectedRepoType
   });
+  runLogger.stageEnd("codegen", { filesGenerated: generatedFiles.length });
   if (opts.tdd) {
     console.log(import_chalk19.default.gray("\n[7/9] TDD mode \u2014 test files already written pre-implementation."));
   } else if (opts.skipTests) {
@@ -10292,8 +10295,10 @@ program.command("create").description("Generate a feature spec and kick off code
   } else {
     console.log(import_chalk19.default.blue(`
 [7/9] Test skeleton generation...`));
+    runLogger.stageStart("test_gen");
     const testGen = new TestGenerator(codegenProvider);
     generatedTestFiles = await testGen.generate(extractedDsl, workingDir);
+    runLogger.stageEnd("test_gen", { filesGenerated: generatedTestFiles.length });
   }
   if (opts.skipErrorFeedback) {
     console.log(import_chalk19.default.gray("[8/9] Skipping error feedback (--skip-error-feedback)."));
@@ -10301,14 +10306,17 @@ program.command("create").description("Generate a feature spec and kick off code
     if (opts.tdd) {
       console.log(import_chalk19.default.cyan("[8/9] TDD mode \u2014 error feedback loop driving implementation to pass tests..."));
     }
+    runLogger.stageStart("error_feedback");
     await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
       maxCycles: opts.tdd ? 3 : 2
       // TDD gets one extra cycle
     });
+    runLogger.stageEnd("error_feedback");
   }
   let reviewResult = "";
   if (!opts.skipReview) {
     console.log(import_chalk19.default.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
+    runLogger.stageStart("review");
     const reviewer = new CodeReviewer(specProvider, currentDir);
     const savedSpec = await fs24.readFile(specFile, "utf-8");
     if (codegenMode === "api" && generatedFiles.length > 0) {
@@ -10322,6 +10330,7 @@ program.command("create").description("Generate a feature spec and kick off code
         process.chdir(originalDir);
       }
     }
+    runLogger.stageEnd("review");
     await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
   }
   runLogger.finish();
@@ -11170,6 +11179,12 @@ program.command("update").description("Update an existing spec with a change req
   const provider = createProvider(providerName, apiKey, modelName);
   console.log(import_chalk19.default.blue("\n\u2500\u2500\u2500 ai-spec update \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log(import_chalk19.default.gray(`  Provider: ${providerName}/${modelName}`));
+  const updateRunId = generateRunId();
+  const updateSnapshot = new RunSnapshot(currentDir, updateRunId);
+  setActiveSnapshot(updateSnapshot);
+  const updateLogger = new RunLogger(currentDir, updateRunId, { provider: providerName, model: modelName });
+  setActiveLogger(updateLogger);
+  console.log(import_chalk19.default.gray(`  Run ID: ${updateRunId}`));
   let specPath = opts.spec ?? null;
   if (!specPath) {
     const specsDir = path23.join(currentDir, "specs");
@@ -11228,6 +11243,7 @@ ${context.constitution}
 === DSL Context ===
 ${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3e3)}
 ` : "";
+    updateLogger.stageStart("update_codegen");
     for (const affected of result.affectedFiles) {
       const fullPath = path23.join(currentDir, affected.file);
       let existing = "";
@@ -11252,12 +11268,29 @@ ${existing || "Create from scratch."}`;
         const raw = await codegenProvider.generate(codePrompt, _getPrompt(repoType));
         const content = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
         await fs24.ensureDir(path23.dirname(fullPath));
+        await updateSnapshot.snapshotFile(fullPath);
         await fs24.writeFile(fullPath, content, "utf-8");
+        updateLogger.fileWritten(affected.file);
         console.log(import_chalk19.default.green("\u2714"));
       } catch (err) {
+        updateLogger.stageFail("update_codegen", `${affected.file}: ${err.message}`);
         console.log(import_chalk19.default.red(`\u2718 ${err.message}`));
       }
     }
+    updateLogger.stageEnd("update_codegen", { filesUpdated: result.affectedFiles.length });
+    const updatedSpecContent = await fs24.readFile(result.newSpecPath, "utf-8").catch(() => "");
+    if (updatedSpecContent) {
+      const updateReviewer = new CodeReviewer(provider, currentDir);
+      const reviewResult = await updateReviewer.reviewCode(updatedSpecContent, result.newSpecPath).catch(() => "");
+      if (reviewResult && reviewResult !== "No changes") {
+        await accumulateReviewKnowledge(provider, currentDir, reviewResult);
+      }
+    }
+  }
+  updateLogger.finish();
+  updateLogger.printSummary();
+  if (updateSnapshot.fileCount > 0) {
+    console.log(import_chalk19.default.gray(`  To undo changes: ai-spec restore ${updateRunId}`));
   }
   if (!opts.codegen && result.affectedFiles.length > 0) {
     console.log(import_chalk19.default.blue("\n  Next steps:"));