ai-spec-dev 0.25.0 → 0.29.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run:*)",
+      "Bash(python3 -c \":*)",
+      "Bash(grep -E \"^./\\\\w+/|^./\\\\w+\\\\.ts$\")",
+      "Bash(wc -l core/*.ts prompts/*.ts)"
+    ]
+  }
+}

package/README.md

@@ -2,12 +2,9 @@
 
 > AI 驱动的功能开发编排工具 — 从一句话需求到可运行代码的完整流水线，支持单 Repo 及多 Repo 跨端联动
 
-[![Version](https://img.shields.io/badge/version-0.25.0-blue)](https://github.com/hzhongzhong/ai-spec)
-[![Author](https://img.shields.io/badge/author-hzhongzhong-green)](https://github.com/hzhongzhong)
-
 **单 Repo 模式：**
 ```
-需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 2-pass 代码审查 → 经验积累(宪法§9)
+需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 3-pass 代码审查 → 经验积累(宪法§9)
 ```
 
 **多 Repo 模式（工作区）：**
@@ -94,9 +91,16 @@ ai-spec create "给用户模块增加登录功能"
         [cycle 2/2] Running tests: npm test
         ✔ Tests passed.
         ✔ All checks passed after 2 cycle(s).
-[9/9]   Automated code review (file-based)...
+[9/9]   Automated code review (3-pass: architecture + implementation + impact/complexity)...
+        Pass 1/3: Architecture review...
+        Pass 2/3: Implementation review...
+        Pass 3/3: Impact & complexity assessment...
+        🌊 影响等级: 中  🧮 复杂度等级: 低
 ─── Knowledge Memory ─────────────────────────────
         ✔ 2 lesson(s) appended to constitution (§9).
+  Run ID: 20260326-143022-ab3f in 94.3s · 8 files written
+  Log   : .ai-spec-logs/20260326-143022-ab3f.json
+  To undo changes: ai-spec restore 20260326-143022-ab3f
 ```
 
 ---
@@ -153,7 +157,8 @@ ai-spec update [change]     增量更新：修改现有 Spec → 重提取 DSL
 ai-spec learn [lesson]      零摩擦知识注入：直接将工程决策或教训写入宪法 §9（无需运行 review）
 ai-spec export              DSL → OpenAPI 3.1.0 YAML/JSON（可导入 Postman / Swagger UI / openapi-generator）
 ai-spec mock                从 DSL 生成 Mock Server / 前端 Proxy 配置 / MSW Handlers（联调利器）
-ai-spec review [file]       对当前 git diff 运行 2-pass AI 代码审查（架构层 + 实现层），并打印评分趋势
+ai-spec review [file]       对当前 git diff 运行 3-pass AI 代码审查（架构层 + 实现层 + 影响面/复杂度），并打印评分趋势
+ai-spec restore <runId>     回滚指定 run 修改的所有文件至原始状态（配合 Run ID 使用）
 ai-spec model               交互式切换 AI provider / model，写入 .ai-spec.json
 ai-spec config              查看 / 修改 / 重置项目级配置
 ai-spec workspace init      初始化多 Repo 工作区（生成 .ai-spec-workspace.json）
@@ -458,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`，确保所有变更都被纳入审查。
 
 ---
@@ -595,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,166 @@
 
 ---
 
+## [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 代码审查（影响面评估 + 代码复杂度评估）
+
+### 新增内容
+
+**Feature — Review Pass 3：影响面评估 + 代码复杂度评估**
+- 文件：`prompts/codegen.prompt.ts`（新增 `reviewImpactComplexitySystemPrompt`）、`core/reviewer.ts`（两 Pass 升级为三 Pass）
+- 原有两 Pass 不变；新增第三 Pass 专注于两个前两 Pass 刻意跳过的维度：
+
+  **影响面评估 (Impact Assessment)**
+  - 直接影响文件列表
+  - 间接影响范围（哪些模块/消费方/下游服务受影响）
+  - 破坏性变更检测（接口签名变更、Schema 变更、配置变更、导出重命名）
+  - 影响等级：低 / 中 / 高（附理由）
+
+  **代码复杂度评估 (Complexity Assessment)**
+  - 认知复杂度热点（最难理解的 1-3 个函数，说明为什么复杂）
+  - 耦合度分析（依赖注入 vs 硬编码、循环依赖风险）
+  - 可维护性风险（魔法数字、业务逻辑藏在生命周期钩子里、隐式时序耦合）
+  - 复杂度等级：低 / 中 / 高（附理由）
+
+- `ReviewHistoryEntry` 新增 `impactLevel` 和 `complexityLevel` 字段，历史记录持久化到 `.ai-spec-reviews.json`
+- CLI banner 更新为 `3-pass: architecture + implementation + impact/complexity`
+
+---
+
+## [0.27.0] 2026-03-26 — 三项工业化底座（Provider 可靠性、文件快照回滚、RunId 结构化日志）
+
+### 新增内容
+
+**Feature #1 — Provider 统一可靠性封装**
+- 新文件：`core/provider-utils.ts`
+- 新增 `withReliability(fn, opts)` 包装器，覆盖所有 provider 的 `generate()` 调用（Gemini、Claude、OpenAI-compatible、MiMo）
+- 能力：超时（默认 90s）+ 自动重试（2 次，退避 2s/6s）+ 结构化错误分类（`auth` / `rate_limit` / `timeout` / `network` / `provider`）
+- Auth 错误（401/403）不重试，避免无效消耗；限流（429）和网络抖动均自动重试并打印黄色警告
+
+**Feature #2 — 文件写入快照与一键回滚**
+- 新文件：`core/run-snapshot.ts`
+- 每次 `create` 运行前，自动备份将被覆盖的文件到 `.ai-spec-backup/<runId>/`
+- 新增命令：`ai-spec restore <runId>`，将本次运行修改的所有文件恢复到原始状态
+- 涵盖 codegen 写入（`code-generator.ts`）和错误修复写入（`error-feedback.ts`）两个落盘点
+- 纯新建文件不备份（无需恢复）；同一文件多次写入只备份一次（保留原始版本）
+
+**Feature #3 — RunId + 结构化执行日志**
+- 新文件：`core/run-logger.ts`
+- 每次运行生成唯一 RunId（格式：`YYYYMMDD-HHMMSS-xxxx`），打印在 banner 下方
+- 执行阶段、写入文件、错误信息实时写入 `.ai-spec-logs/<runId>.json`
+- 运行结束时打印摘要：RunId + 耗时 + 写入文件数 + 错误数 + 日志路径
+- 有文件被修改时自动提示：`To undo changes: ai-spec restore <runId>`
+
+---
+
+## [0.26.0] 2026-03-26 — 三项稳定性修复（多仓库 review、并行 batch 容错、tasks JSON 损坏）
+
+### 修复内容
+
+**Fix #1 — 多仓库模式代码审查 git diff 为空**
+- 文件：`cli/index.ts` → `runSingleRepoPipelineInWorkspace`
+- 问题：`reviewer.reviewCode()` 内部调用 `execSync("git diff")`，运行在 `process.cwd()`（CLI 启动目录）而非当前 repo 的 `workingDir`（可能是 worktree 路径），导致 diff 为空或错误，审查结果没有意义。
+- 修复：在 `reviewCode` 调用前后加 `process.chdir(workingDir)` / `process.chdir(originalDir)`，与单仓库模式保持一致。
+
+**Fix #2 — 并行 batch 单任务抛异常导致整层崩溃**
+- 文件：`core/code-generator.ts` → `runApiModeWithTasks` batch 执行循环
+- 问题：`Promise.all(batchResultPromises)` 中任意一个 `executeTask` 抛出未捕获异常（磁盘满、mkdir 失败、provider 超时），整个 `Promise.all` 立即 reject，该层剩余所有任务都被丢弃，没有任何降级处理。
+- 修复：每个 `executeTask` 调用后追加 `.catch((err) => ...)` 返回失败结果对象，确保单任务失败只影响自身，不中断同批次其他任务。
+
+**Fix #3 — `loadTasksForSpec` 遇到损坏的 JSON 文件直接崩溃**
+- 文件：`core/task-generator.ts` → `loadTasksForSpec`
+- 问题：如果上次运行中途中断导致 `*-tasks.json` 是不完整的 JSON，`fs.readJson()` 抛出 parse 错误，没有任何 try-catch 包裹，用户看到的是裸 JS 异常而非友好提示。
+- 修复：加 try-catch，catch 块打印"Tasks file corrupt，请重新运行 `ai-spec tasks`"并返回 `null`（触发重新生成），不再崩溃。
+
+---
+
+## [0.25.0] 2026-03-26 — 三项上下文提取修复（HTTP import、分页示例、工具崩溃误判）
+
+### 修复内容
+
+**Fix #1 — HTTP import 幻觉防护失效**
+- 文件：`core/frontend-context-loader.ts` → `httpImportRegex`
+- 问题：旧正则只匹配 `axios`、`ky`、`@/` 开头的路径。使用 `import request from '@/utils/request'` 等自定义封装的项目（极其常见）提取结果为 `undefined`，AI 会自由发挥 import 路径。
+- 修复：扩展匹配范围：
+  - 所有项目别名：`@/`、`~/`、`#/`、`@@/`
+  - 包含 http/request/fetch/client/api 关键词的相对路径
+  - 完整 HTTP 库列表：axios、ky、ky-universal、undici、node-fetch、cross-fetch、got、superagent、alova、openapi-fetch
+  - 排除 `import type` 语句（它们不是运行时 import）
+
+**Fix #2 — 分页示例提取正则永远不匹配**
+- 文件：`core/frontend-context-loader.ts` → 分页提取块
+- 问题：
+  1. 接口正则用 `[^}]*` 匹配接口体，遇到嵌套对象 `{ field: { ... } }` 立即截断
+  2. 函数正则用 `\n\}` 匹配闭合括号，但缩进的 `  }` 永远不匹配
+  3. 只处理 `export function`，遗漏了现代代码中更常见的 `export const x = () =>` 写法
+- 修复：完全重写为**逐行 + 括号深度计数器**的两步提取法：
+  - Step 1：找到带分页字段（pageIndex/pageSize/page/…）的接口，用深度计数捕获完整块（支持嵌套对象）
+  - Step 2：找到引用该接口的导出函数（同时支持 `export function` 和 `export const = () =>`），同样用深度计数捕获函数体
+
+**Fix #3 — `isToolCrash` 把用户代码错误当工具崩溃**
+- 文件：`core/error-feedback.ts`
+- 问题：旧判断条件是"输出包含 ReferenceError/TypeError 且包含 node_modules"。TypeScript 的自动修复测试运行时，测试框架的 stack trace 中也会包含 node_modules，导致用户自己代码里的 ReferenceError 被误判为工具崩溃跳过。
+- 修复：改为精确判断：必须同时满足（1）存在未捕获 JS 错误，且（2）stack trace 中有 `at … node_modules/…` 帧——即错误起源于工具二进制本身，而不仅仅是"输出中某处出现了 node_modules"。
+
+---
+
 ## [0.24.0] 2026-03-25 — 四项质量修复（lesson 计数、export default、impliesRegistration、依赖拓扑排序）
 
 ### 修复内容

package/cli/index.ts

@@ -72,6 +72,8 @@ import {
 } from "../core/mock-server-generator";
 import { SpecUpdater } from "../core/spec-updater";
 import { exportOpenApi } from "../core/openapi-exporter";
+import { generateRunId, RunLogger, setActiveLogger } from "../core/run-logger";
+import { RunSnapshot, setActiveSnapshot } from "../core/run-snapshot";
 
 // ─── Config File ──────────────────────────────────────────────────────────────
 
@@ -293,11 +295,24 @@ program
       codegenModel: codegenModelName,
     });
 
+    // ── Run tracking ──────────────────────────────────────────────────────────────
+    const runId = generateRunId();
+    console.log(chalk.gray(`  Run ID: ${runId}`));
+    const runSnapshot = new RunSnapshot(currentDir, runId);
+    setActiveSnapshot(runSnapshot);
+    const runLogger = new RunLogger(currentDir, runId, {
+      provider: specProviderName,
+      model: specModelName,
+    });
+    setActiveLogger(runLogger);
+
     // ── 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`));
@@ -332,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
@@ -350,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);
     }
@@ -362,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
@@ -380,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.`));
@@ -398,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)"));
+        }
       }
     }
 
@@ -472,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.`));
       }
     }
@@ -568,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,
@@ -575,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) {
@@ -585,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 ───────────────────────────────────────────
@@ -598,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 (2-pass: architecture + implementation)..."));
+      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");
 
@@ -623,12 +660,14 @@ program
           process.chdir(originalDir);
         }
       }
+      runLogger.stageEnd("review");
 
       // Knowledge Memory: extract lessons from review and append to constitution §9
       await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
     }
 
     // ── Done ──────────────────────────────────────────────────────────────────
+    runLogger.finish();
     console.log(chalk.bold.green("\n✔ All done!"));
     console.log(chalk.gray(`  Spec        : ${specFile}`));
     if (savedDslFile) console.log(chalk.gray(`  DSL         : ${savedDslFile}`));
@@ -639,6 +678,10 @@ program
     if (workingDir !== currentDir) {
       console.log(chalk.gray(`  Run \`cd ${workingDir}\` to enter the worktree.`));
     }
+    runLogger.printSummary();
+    if (runSnapshot.fileCount > 0) {
+      console.log(chalk.gray(`  To undo changes: ai-spec restore ${runId}`));
+    }
   });
 
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -1252,7 +1295,16 @@ async function runSingleRepoPipelineInWorkspace(opts: {
     console.log(chalk.blue(`  [${repoName}] Running code review...`));
     try {
       const reviewer = new CodeReviewer(specProvider);
-      const reviewResult = await reviewer.reviewCode(finalSpec);
+      // git diff must run in the repo's working directory (may be a worktree),
+      // not in wherever the CLI was invoked from.
+      const originalDir = process.cwd();
+      let reviewResult: string;
+      try {
+        process.chdir(workingDir);
+        reviewResult = await reviewer.reviewCode(finalSpec);
+      } finally {
+        process.chdir(originalDir);
+      }
       await accumulateReviewKnowledge(specProvider, repoAbsPath, reviewResult);
       console.log(chalk.green(`    Code review complete.`));
     } catch (err) {
@@ -1763,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) {
@@ -1833,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 = "";
@@ -1856,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 ─────────────────────────────────────────────────────────────────
@@ -2127,6 +2210,27 @@ program
     }
   });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: restore
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("restore")
+  .description("Restore files modified by a previous run")
+  .argument("<runId>", "Run ID shown at the end of a create / generate run")
+  .action(async (runId: string) => {
+    const currentDir = process.cwd();
+    const snapshot = new RunSnapshot(currentDir, runId);
+    console.log(chalk.blue(`Restoring run: ${runId}...`));
+    const restored = await snapshot.restore();
+    if (restored.length === 0) {
+      console.log(chalk.yellow("  No backup found for this run ID."));
+    } else {
+      restored.forEach((f) => console.log(chalk.green(`  ✔ restored: ${f}`)));
+      console.log(chalk.bold.green(`\n✔ ${restored.length} file(s) restored.`));
+    }
+  });
+
 // Show welcome screen when invoked with no arguments
 if (process.argv.length <= 2) {
   (async () => {

package/core/code-generator.ts

@@ -8,6 +8,8 @@ import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecTask, loadTasksForSpec, updateTaskStatus } from "./task-generator";
 import { loadDslForSpec, buildDslContextSection } from "./dsl-extractor";
 import { loadFrontendContext, buildFrontendContextSection } from "./frontend-context-loader";
+import { getActiveSnapshot } from "./run-snapshot";
+import { getActiveLogger } from "./run-logger";
 
 // ─── Shared Config Helper ───────────────────────────────────────────────────
 
@@ -720,7 +722,15 @@ Output ONLY a valid JSON array:
 
       for (const batch of taskBatches) {
         const batchIsParallel = batch.length > 1;
-        const batchResultPromises = batch.map((task) => executeTask(task, batchIsParallel));
+        // Wrap each task in .catch() so a single unexpected failure (disk full,
+        // provider timeout, mkdir error) degrades gracefully instead of rejecting
+        // the entire Promise.all and aborting all sibling tasks in the batch.
+        const batchResultPromises = batch.map((task) =>
+          executeTask(task, batchIsParallel).catch((err): TaskResult => {
+            console.log(chalk.yellow(`  ⚠ ${task.id} threw unexpectedly: ${(err as Error).message}`));
+            return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false };
+          })
+        );
         const batchResults = await Promise.all(batchResultPromises);
         layerResults.push(...batchResults);
         // Update cache after each batch so the next batch sees the exports.
@@ -838,8 +848,10 @@ ${existingContent || "Output only the complete file content."}`;
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
+        await getActiveSnapshot()?.snapshotFile(fullPath);
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, fileContent, "utf-8");
+        getActiveLogger()?.fileWritten(item.file);
         console.log(`${prefix}${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)} ${chalk.green("✔")}`);
         successCount++;
         writtenFiles.push(item.file);

package/core/error-feedback.ts

@@ -6,6 +6,7 @@ import { AIProvider } from "./spec-generator";
 import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecDSL } from "./dsl-types";
 import { buildDslContextSection } from "./dsl-extractor";
+import { getActiveSnapshot } from "./run-snapshot";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -242,6 +243,7 @@ Output ONLY the complete fixed file content. No markdown fences, no explanations
     try {
       const raw = await provider.generate(prompt, getCodeGenSystemPrompt());
       const fixed = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
+      await getActiveSnapshot()?.snapshotFile(fullPath);
       await fs.writeFile(fullPath, fixed, "utf-8");
       results.push({ fixed: true, file, explanation: `Fixed ${fileErrors.length} error(s)` });
       console.log(chalk.green(`  ✔ Auto-fixed: ${file}`));
@@ -300,13 +302,22 @@ export async function runErrorFeedback(
       console.log(chalk.gray(`\n  [cycle ${cycle}/${maxCycles}] Type-check: ${buildCmd}`));
       const buildResult = runCommand(buildCmd, workingDir);
       if (!buildResult.success) {
-        // Detect tool crash (ReferenceError / TypeError inside node_modules) —
-        // this means the type-check tool itself is broken (e.g. vue-tsc version
-        // incompatibility), NOT a user code error. Skip silently instead of
-        // feeding garbage into the auto-fix loop.
-        const isToolCrash =
-          /ReferenceError:|TypeError:|SyntaxError:/.test(buildResult.output) &&
-          buildResult.output.includes("node_modules");
+        // Detect tool crash — the type-check binary itself threw an unhandled
+        // exception (e.g. vue-tsc / tsc version incompatibility).
+        //
+        // Two conditions must BOTH be true:
+        //   1. The output contains an uncaught JS error (ReferenceError, TypeError, …)
+        //   2. The stack trace has at least one frame inside node_modules,
+        //      meaning the crash originated in the tool binary, not user code.
+        //
+        // TypeScript compilation errors from user code are formatted as
+        //   "src/foo.ts:10:5 - error TS2345: …"
+        // and do NOT produce "at …" stack frames, so they are never misclassified.
+        const hasUncaughtError = /ReferenceError:|TypeError:|SyntaxError:/.test(buildResult.output);
+        const hasToolStackFrame = buildResult.output
+          .split("\n")
+          .some((l) => l.trim().startsWith("at ") && l.includes("node_modules"));
+        const isToolCrash = hasUncaughtError && hasToolStackFrame;
         if (isToolCrash) {
           console.log(chalk.yellow(`  ⚠ Type-check tool crashed (possible version incompatibility). Skipping.`));
           console.log(chalk.gray(`    Tip: run \`${buildCmd}\` manually to investigate.`));