ai-spec-dev 0.37.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.37.0",
+  "version": "0.41.0",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,12 +27,12 @@
     "@google/generative-ai": "^0.21.0",
     "@inquirer/editor": "^5.0.10",
     "@inquirer/prompts": "^8.3.2",
+    "@rollup/rollup-darwin-arm64": "^4.60.1",
     "axios": "^1.13.6",
     "chalk": "^4.1.2",
     "commander": "^13.1.0",
     "dotenv": "^16.4.7",
     "fs-extra": "^11.3.0",
-    "inquirer": "^8.2.6",
     "openai": "^6.31.0",
     "undici": "^7.24.4"
   },

package/purpose.md

@@ -5,7 +5,7 @@
 
 > 痛点 · 架构创新 · 边界处理 · DSL 的意义 · 当前局限 · 未来方向
 >
-> 当前版本：v0.35.0 · 最后更新：2026-04-01
+> 当前版本：v0.38.0 · 最后更新：2026-04-02
 
 ***
 
@@ -19,6 +19,8 @@
    - 2.14 [两条 Pipeline 反馈环：让流水线可纠偏（v0.33.0+）](#214-两条-pipeline-反馈环让流水线可纠偏v0330)
    - 2.15 [DSL 的多出口价值：类型、Dashboard 与可观测性（v0.34.0+）](#215-dsl-的多出口价值类型dashboard-与可观测性v0340)
    - 2.16 [Pipeline 可靠性强化与 VCR 离线回放（v0.35.0+）](#216-pipeline-可靠性强化与-vcr-离线回放v0350)
+   - 2.17 [安全加固 + 测试工程化 + 质量门禁（v0.36.0–v0.37.0）](#217-安全加固--测试工程化--质量门禁v0360v0370)
+   - 2.18 [Design Options Dialogue + Pass 0 Spec Compliance + 项目索引（v0.38.0）](#218-design-options-dialogue--pass-0-spec-compliance--项目索引v0380)
 3. [DSL 层的意义](#3-dsl-层的意义)
 4. [完整功能矩阵](#4-完整功能矩阵)
 5. [边界情况与兜底机制](#5-边界情况与兜底机制)
@@ -26,7 +28,7 @@
 7. [当前局限](#7-当前局限)
 8. [未来优化方向](#8-未来优化方向)
 
-> **版本记录速览**：v0.17.0 宪法截断修复 · v0.18.0 `learn` + `minSpecScore` + 行为契约提取 · v0.19.0 错误解析重写 + Auto Gate 修复 · v0.20.0 `mock --serve` 一键联调 · v0.21.0 store 公开 API 提取修复 · v0.22.0 service/api 层分离 · v0.23.0 view/route 双层 + 文件名幻觉修复 · v0.24.0 四项质量修复（export default、impliesRegistration、依赖拓扑排序、lesson 计数）· v0.25.0 HTTP import 正则、分页提取、isToolCrash 三项修复 · v0.26.0 多仓库 review 目录、batch 容错、tasks JSON 健壮性 · **v0.27.0 可靠性三件套**（Provider retry/timeout/分类、文件快照 + `restore`、RunId 结构化日志）· **v0.28.0 3-pass review**（Pass 3 影响面评估 + 代码复杂度评估）· **v0.29.0 全量审查修复**（RunLogger 完整插桩、update 快照/日志/knowledge、Score Trend 显示影响/复杂度等级、死代码清理）· **v0.30.0 错误修复依赖图排序 + 前端 Import 多行感知解析** · **v0.31.0 Harness Engineer：Prompt Hash + Create 内联 Self-Eval** · **v0.32.0 logs / trend + DSL Coverage 细化评分** · **v0.33.0 两条 Pipeline 反馈环（DSL Gap Loop + Review→DSL Loop）** · **v0.34.0 Harness Dashboard + DSL → TypeScript 类型生成** · **v0.35.0 VCR 录制回放 + JSONL 崩溃恢复 + 熔断 + §9 知识闭环 + Approval Gate 预估**
+> **版本记录速览**：v0.17.0 宪法截断修复 · v0.18.0 `learn` + `minSpecScore` + 行为契约提取 · v0.19.0 错误解析重写 + Auto Gate 修复 · v0.20.0 `mock --serve` 一键联调 · v0.21.0 store 公开 API 提取修复 · v0.22.0 service/api 层分离 · v0.23.0 view/route 双层 + 文件名幻觉修复 · v0.24.0 四项质量修复（export default、impliesRegistration、依赖拓扑排序、lesson 计数）· v0.25.0 HTTP import 正则、分页提取、isToolCrash 三项修复 · v0.26.0 多仓库 review 目录、batch 容错、tasks JSON 健壮性 · **v0.27.0 可靠性三件套**（Provider retry/timeout/分类、文件快照 + `restore`、RunId 结构化日志）· **v0.28.0 3-pass review**（Pass 3 影响面评估 + 代码复杂度评估）· **v0.29.0 全量审查修复**（RunLogger 完整插桩、update 快照/日志/knowledge、Score Trend 显示影响/复杂度等级、死代码清理）· **v0.30.0 错误修复依赖图排序 + 前端 Import 多行感知解析** · **v0.31.0 Harness Engineer：Prompt Hash + Create 内联 Self-Eval** · **v0.32.0 logs / trend + DSL Coverage 细化评分** · **v0.33.0 两条 Pipeline 反馈环（DSL Gap Loop + Review→DSL Loop）** · **v0.34.0 Harness Dashboard + DSL → TypeScript 类型生成** · **v0.35.0 VCR 录制回放 + JSONL 崩溃恢复 + 熔断 + §9 知识闭环 + Approval Gate 预估** · **v0.36.0 Shell 注入防护 + API Key 权限时序 + DSL 唯一性校验 + 核心模块测试覆盖** · **v0.36.1 质量硬门禁（minHarnessScore + maxErrorCycles）+ Provider 错误诊断增强** · **v0.37.0 Mock/Types/VCR 测试覆盖（409 cases / 18 modules / 45%）** · **v0.38.0 Design Options Dialogue + Pass 0 Spec Compliance + 项目索引 scan + 抗幻觉 Skills + Task verificationSteps**
 
 ***
 
@@ -60,7 +62,7 @@ ai-spec 对每个痛点都有对应的架构设计，不是功能堆砌，而是
 | 流水线纠偏成本高   | 局部反馈环                 | DSL 稀疏时先补 Spec 再提取；Review 发现结构性问题时先修契约再 `update --codegen` |
 | 经验不断流失     | 知识记忆机制               | 审查 issue 自动写入宪法 §9，下次运行即生效；`init --consolidate` 定期精简  |
 | 跨 task 一致性 | Generated File Cache | 已生成的 API/store 文件内容缓存，后续 task 可见真实导出名                 |
-| 难以判断系统是否在变好 | Harness 可观测层          | `promptHash` + `harnessScore` + `logs/trend/dashboard`，把生成质量变成可比较数据 |
+| 难以判断系统是否在变好 | Harness 可观测层 + 质量门禁  | `promptHash` + `harnessScore` + `logs/trend/dashboard` + `minHarnessScore` 阈值阻断，把生成质量变成可比较、可管控的数据 |
 
 **核心定位**：ai-spec 不是代码补全工具，而是一个「AI 辅助工程流程编排器」。它的目标是让工程师用最少的时间获得一个符合项目规范、通过基本质检、可直接进入 Review 的代码分支。
 
@@ -135,8 +137,11 @@ ai-spec 对每个痛点都有对应的架构设计，不是功能堆砌，而是
 Step 1 · 加载项目上下文
   ContextLoader 扫描代码结构 / 依赖 / 路由 / schema
   ↓
+Step 1.5 · Design Options Dialogue（v0.38.0）
+  AI 提出 2-3 个架构方案，用户选择后注入 spec prompt
+  ↓
 Step 2 · Spec + Tasks 生成
-  宪法全文注入 prompt 最高优先级
+  宪法全文注入 prompt 最高优先级 + architectureDecision
   ↓
 Step 3 · 交互式润色
   Diff 预览，可多轮修改
@@ -165,7 +170,7 @@ Step 3.4 · Spec 质量评估
                       运行 test / lint / tsc
                         ↓
                       判断：全部通过？
-                        ├─ 通过 → Step 9 · 3-pass 代码审查
+                        ├─ 通过 → Step 9 · Pass 0 合规 + 3-pass 代码审查
                         │          Pass1 架构 · Pass2 实现 · Pass3 影响面/复杂度
                         ├─ 有错误，且 cycle ≤ 2
                         │    → 依赖图排序
@@ -173,13 +178,13 @@ Step 3.4 · Spec 质量评估
                         │    → 回到 test / lint / tsc
                         └─ cycle 2 仍失败
                              → ⚠️ 黄色警告，继续
-                             → Step 9 · 3-pass 代码审查
+                             → Step 9 · Pass 0 合规 + 3-pass 代码审查
                                   ↓
                                 §9 知识积累
                                 审查 issue 自动追加宪法
                                   ↓
                                 Step 10 · Harness Self-Eval
-                                DSL 覆盖 + Compile + Review → harnessScore
+                                Compliance + DSL 覆盖 + Compile + Review → harnessScore
                                 PromptHash 关联，零 AI 调用
                                   ↓
                                 ✔ Done
@@ -831,6 +836,120 @@ Approval Gate 新增基于正则的 DSL 规模预估（无 AI 调用），在用
 
 ***
 
+### 2.17 安全加固 + 测试工程化 + 质量门禁（v0.36.0–v0.37.0）
+
+v0.36.0–v0.37.0 是一组围绕**安全性、可测试性和质量可控性**的版本迭代，将 ai-spec 从「功能完备」推向「工程可信赖」。
+
+#### 安全加固（v0.36.0）
+
+两处安全修复消除了已知攻击面：
+
+- **Shell 命令注入防护**：`execSync` 拼接 shell 字符串时，AI 生成的 prompt 内容可能包含 `$`、`;`、`|` 等 shell 元字符。全部替换为 `spawnSync(cmd, [args], { shell: false })`，从根本上绕过 shell 解析
+- **API Key 存储权限时序**：`writeJson()` → `chmod(0o600)` 改为 `ensureFile()` → `chmod(0o600)` → `writeJson()`，消除写入与权限设置之间的窗口期
+
+#### DSL 校验增强（v0.36.0）
+
+- **Endpoint ID 唯一性检查**：AI 经常生成重复 ID（如两个 `EP-001`），导致下游 types-generator、mock-server 产生覆盖冲突。新增 `Set<string>` 去重
+- **Model 字段名唯一性检查**：同一 Model 内重复字段名会导致 Prisma schema 和 TypeScript interface 冲突
+- **`missing_errors` 误报修复**：从「任何 endpoint 缺 errors 就报 gap」改为「所有 endpoint 都缺时才报」
+
+#### 测试工程化（v0.36.0–v0.37.0）
+
+三个版本累计新增 **158 个测试用例**（251 → 409），覆盖模块从 9 个增加到 18 个，覆盖率从 22.5% 提升到 45%：
+
+| 版本 | 新增测试模块 | 测试数 | 累计 |
+|------|-----------|--------|------|
+| v0.36.0 | spec-generator / reviewer / code-generator | +8 tests | 259 |
+| v0.36.1 | context-loader / openapi-exporter / spec-versioning | +72 tests | 331 |
+| v0.37.0 | mock-server-generator / types-generator / vcr | +78 tests | 409 |
+
+测试策略：不追求行覆盖率指标，而是**覆盖每个模块的核心决策路径**——正则匹配边界、容错降级、类型映射、序列化/反序列化往返。
+
+#### 质量硬门禁（v0.36.1）
+
+将质量评分从「仅展示」升级为「可阻断」：
+
+- **`minHarnessScore`**：配置文件设置阈值（默认 0 = 禁用），自评分数低于阈值时 `exit(1)`，`--force` 可绕过
+- **`maxErrorCycles`**：错误反馈修复轮次从硬编码 2 改为可配置（默认 2，TDD 默认 3，范围 1-10）
+- **Provider 错误诊断增强**：401/403 提示检查 Key、429 提示等待或切换 Provider、网络错误提示代理设置、余额不足提示计费面板——从「报错退出」变为「报错 + 具体行动建议」
+
+**设计原则**：质量门禁的目的不是拦住所有低分运行（`--force` 始终可用），而是让团队能定义「什么分数以下不应该自动进入 Review」的基线——这是从个人工具走向团队流程的关键能力。
+
+***
+
+### 2.18 Design Options Dialogue + Pass 0 Spec Compliance + 项目索引（v0.38.0）
+
+v0.38.0 的主题是**决策前置 + 审查细化 + 跨项目感知**，在流水线的两端（生成前 / 生成后）分别加入新的质量控制点。
+
+#### Design Options Dialogue（Step 1.5）
+
+受 Superpowers brainstorming 启发，在 Spec 生成前新增架构方案对话：
+
+```
+Context Load → [Step 1.5] Design Options → Spec Generation → ...
+```
+
+- AI 针对需求提出 2-3 个架构方案，每个方案含 Approach / Trade-offs / Best when
+- 用户可选择 Option A/B/C、Blend（AI 融合多方案）、或 Skip（跳过直接生成）
+- 选定方案以 `architectureDecision` 注入 Spec prompt，确保 Spec 生成时已有明确的架构方向
+- `--fast` / `--auto` / `--vcr-replay` 模式自动跳过，不增加自动化流程的延迟
+
+**核心价值**：将「Spec 生成完后才发现方向不对」的问题前移到「Spec 生成前就对齐架构选型」。Approval Gate 保证了「需求理解是否正确」的检查点，Design Options 保证了「技术方案是否合理」的检查点——两者配合，覆盖了生成前的两类主要风险。
+
+#### Pass 0 Spec Compliance Check
+
+在现有 3-pass Review 前新增 Pass 0：穷举式 Spec 合规性审计。
+
+```
+Code Review: Pass 0 Compliance → Pass 1 Architecture → Pass 2 Implementation → Pass 3 Impact
+```
+
+- 从 Spec 中提取所有需求条目（endpoints / models / business rules / auth / error cases / side effects），逐条标记 ✅ / ⚠️ / ❌
+- 输出 `ComplianceScore: X/10` + Blockers 列表
+- Pass 1 去除原有「是否覆盖所有需求」条款（Pass 0 已处理），聚焦层分离 / 契约设计 / 安全姿态
+- Pass 1 prompt 注入 Pass 0 合规报告，避免重复发现
+- `harnessScore` 权重更新：compliance 0.30 · DSL coverage 0.25 · compile 0.20 · review 0.25
+
+**设计思考**：原有 Pass 1 架构审查既要检查架构合理性，又要核对需求覆盖度，两个维度混在一起导致审查深度不够。拆分后，Pass 0 做「是否做全了」的清单式审计，Pass 1 做「做得是否对」的架构评判——职责更清晰，漏检率更低。
+
+#### Task verificationSteps
+
+每个 Task 新增 `verificationSteps: string[]` 字段，要求具体可执行的验证命令 + 预期结果：
+
+```json
+{
+  "verificationSteps": [
+    "curl -X POST /api/login -d '{\"email\":\"test@example.com\",\"password\":\"123\"}' → 200 + JWT token",
+    "curl -X POST /api/login -d '{\"email\":\"bad\"}' → 400 INVALID_EMAIL"
+  ]
+}
+```
+
+规则：每条必须是可执行命令 + 可观察预期结果（禁止 "works correctly" 式模糊描述），2-5 条/task，后端必含 HTTP 检查，前端必含 UI render + state 检查。
+
+#### 项目索引 `ai-spec scan`
+
+新增跨项目感知能力：
+
+- `ai-spec scan` — 扫描根目录下所有子项目（识别 `package.json` / `go.mod` / `Cargo.toml` / `pom.xml` 等 manifest），持久化到 `.ai-spec-index.json`
+- 增量更新：新项目添加 `firstSeen`，已有项目更新 `techStack / hasConstitution / lastSeen`，目录消失标记 `missing:true`
+- Git Worktree 过滤：防止 ai-spec 生成的 worktree 被误识别为项目
+- `ai-spec init --global` 联动：读取 index 为全局宪法生成提供多项目上下文
+
+#### 抗幻觉 Skills
+
+从 ai-spec 内部实践中提炼 5 个可复用的 Claude Code slash command，供团队日常使用：
+
+| Skill | 用途 |
+|-------|------|
+| `/scan-singletons` | 扫描单例 config 文件，输出"只能修改、绝不重建"清单 |
+| `/add-lesson` | 零摩擦写入宪法 §9，含去重 + 分类 + 时间戳 |
+| `/installed-deps` | 列出所有依赖作为 codegen 白名单 |
+| `/recall-lessons` | 按相关度筛选 §9 历史教训 |
+| `/verify-imports` | 验证所有 import 路径，输出 broken imports 及修复建议 |
+
+***
+
 ## 3. DSL 层的意义
 
 DSL 是整个系统中设计投入最大的模块，也是最容易被误解为「多此一举」的部分。
@@ -890,42 +1009,45 @@ DSL 提取本身是高幻觉风险操作。ai-spec 做了几个针对性设计
 
 ## 4. 完整功能矩阵
 
-截至 v0.34.0，ai-spec 的完整能力覆盖：
+截至 v0.38.0，ai-spec 的完整能力覆盖：
 
 | 阶段             | 命令                        | 核心能力                                                                                                                                                                                                             |
 | -------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **初始化**        | `ai-spec init`            | 扫描项目 → 生成宪法 §1-§8（`--global` 生成全局宪法，`--consolidate` 整合 §9）                                                                                                                                                       |
-| **新功能**        | `ai-spec create`          | 宪法（全文注入）→ context → Spec+Tasks → **Spec 质量评估 + minSpecScore Gate** → Approval Gate → DSL → **DSL Gap Feedback** → Worktree → 逐 task codegen（**七层顺序 + 层内拓扑排序 + 行为契约缓存**）→ **TDD（`--tdd`）** → 错误反馈闭环（全文扫描，≤2 轮）→ 测试骨架 → **3-pass review** → **Review→DSL Loop** → **Harness Self-Eval** |
+| **新功能**        | `ai-spec create`          | 宪法（全文注入）→ context → **Design Options Dialogue** → Spec+Tasks → **Spec 质量评估 + minSpecScore Gate** → Approval Gate → DSL → **DSL Gap Feedback** → Worktree → 逐 task codegen（**七层顺序 + 层内拓扑排序 + 行为契约缓存**）→ **TDD（`--tdd`）** → 错误反馈闭环（全文扫描，≤`maxErrorCycles` 轮）→ 测试骨架 → **Pass 0 Spec Compliance + 3-pass review** → **Review→DSL Loop** → **Harness Self-Eval（minHarnessScore Gate）** |
 | **变更迭代**       | `ai-spec update`          | 最小化更新 Spec → 定向更新 DSL（delta 对比）→ 识别受影响文件 → 可选重新生成（**`--codegen`** **附带写前快照 + RunId 日志 + knowledge 积累，v0.29.0**）                                                                                                  |
 | **接口导出**       | `ai-spec export`          | DSL → OpenAPI 3.1.0 YAML/JSON，纯 TypeScript 实现，零外部依赖                                                                                                                                                              |
 | **前后端联调**      | `ai-spec mock`            | DSL → Express Mock Server + Proxy 配置 + MSW Handlers；`--serve` 一键后台启动服务器 + 自动 patch 前端 Proxy（Vite/CRA）；`--restore` 一键还原                                                                                           |
 | **类型产物**       | `ai-spec types`           | DSL → TypeScript 类型文件（models、endpoint request types、`API_ENDPOINTS`、component props）                                                                                                                               |
 | **知识注入**       | `ai-spec learn`           | 零摩擦向宪法 §9 注入工程教训，不调用 AI，实时去重                                                                                                                                                                                     |
-| **代码审查**       | `ai-spec review`          | git diff + Spec → AI **3-pass** 审查（架构层 + 实现层 + 影响面/复杂度）→ issue 写入宪法 §9                                                                                                                                           |
+| **代码审查**       | `ai-spec review`          | git diff + Spec → AI **Pass 0 合规审计 + 3-pass** 审查（架构层 + 实现层 + 影响面/复杂度）→ issue 写入宪法 §9                                                                                                                            |
 | **运行观测**       | `ai-spec logs` / `trend` / `dashboard` | 基于 RunLog 做单次回看、跨运行趋势分析、Prompt 版本对比、阶段耗时与错误频次可视化                                                                                                                                                |
 | **快照回滚**       | `ai-spec restore <runId>` | 按 RunId 回滚本次生成写入的所有文件（v0.27.0+）                                                                                                                                                                                  |
+| **项目索引**       | `ai-spec scan`            | 扫描根目录子项目 → 持久化 `.ai-spec-index.json` → 增量更新 → `init --global` 联动多项目上下文                                                                                                                                           |
 | **多 Repo 工作区** | workspace 模式              | 一句需求 → AI 拆分职责+UX 决策 → \[后端流水线 → DSL 契约] → \[前端流水线（注入后端契约）]；`--serve` 完成后自动启动联调环境                                                                                                                                |
 
-**单 Repo 流水线总图（v0.29.0）：**
+**单 Repo 流水线总图（v0.38.0）：**
 
 ```
 需求描述
   → 项目宪法（全文注入）+ 多语言 Context 感知 + 前端 Context 提取
-    → Spec + Tasks（合并生成）
-      → 交互式润色（Diff 预览）
-        → Spec 质量评估（minSpecScore 阈值）
-          → Approval Gate
-            → RunId 生成 + RunSnapshot 初始化（v0.27.0）
-              → DSL 提取 + 校验（抗幻觉，≤2 次 retry）
-                → Git Worktree 隔离
-                  → 逐 task 代码生成（每次写文件前先快照原内容）
-                      data → infra → service → api → view → route → test
-                      同层内：拓扑排序分 batch → batch 内并行 → 批次间串行更新缓存
-                    → 错误反馈闭环（全文扫描解析，≤2 轮，写前快照）
-                      → 测试骨架生成
-                        → AI 代码审查（3-pass：架构 + 实现 + 影响面/复杂度）
-                          → Run 结构化日志写入（v0.27.0）
-                            → 经验写入宪法 §9
+    → Design Options Dialogue（2-3 架构方案选择，v0.38.0）
+      → Spec + Tasks（合并生成，含 verificationSteps）
+        → 交互式润色（Diff 预览）
+          → Spec 质量评估（minSpecScore 阈值）
+            → Approval Gate（含 DSL 范围预估）
+              → RunId 生成 + RunSnapshot 初始化 + JSONL Shadow
+                → DSL 提取 + 校验（抗幻觉，≤2 次 retry，ID/字段唯一性）
+                  → Git Worktree 隔离
+                    → 逐 task 代码生成（每次写文件前先快照原内容）
+                        data → infra → service → api → view → route → test
+                        同层内：拓扑排序分 batch → batch 内并行 → 批次间串行更新缓存
+                      → 错误反馈闭环（全文扫描，≤maxErrorCycles 轮，无进展熔断）
+                        → 测试骨架生成
+                          → AI 代码审查（Pass 0 合规 + 3-pass：架构 + 实现 + 影响面）
+                            → Harness Self-Eval（minHarnessScore Gate）
+                              → Run 结构化日志写入（JSON + JSONL）
+                                → 经验写入宪法 §9（异步 fire-and-await）
 ```
 
 **多 Repo 工作区 + 一键联调（v0.20.0+）：**
@@ -1071,13 +1193,12 @@ DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于
 
 ### 7.5 错误修复能力有上限
 
-错误反馈循环最多运行 2 次，每次修复以文件为粒度。仍存在的限制：
+错误反馈循环以文件为粒度修复。仍存在的限制：
 
-- 修复上限固定为 2 cycle，无法动态调整
 - 同一文件内多个相互依赖的逻辑错误需要多轮才能全部消除
 - Python、Java 等语言的 import 语法暂不参与依赖排序（当前仅解析 TS/JS 相对 import）
 
-> v0.19.0 改进了错误 **解析** 质量（全文扫描 + file:line 过滤）。v0.30.0 新增 `buildRepairOrder()` 对出错文件按 import 依赖拓扑排序，被依赖文件优先修复，cascade 错误在 cycle 1 的消除率提升。2 cycle 上限和「按文件粒度串行修复」的基本策略不变。
+> v0.19.0 改进了错误 **解析** 质量（全文扫描 + file:line 过滤）。v0.30.0 新增 `buildRepairOrder()` 对出错文件按 import 依赖拓扑排序，被依赖文件优先修复，cascade 错误在 cycle 1 的消除率提升。v0.35.0 新增无进展熔断（错误数未减少时立即退出）。**v0.36.1 将修复轮次从硬编码 2 改为 `maxErrorCycles` 可配置**（默认 2，TDD 默认 3，范围 1-10）。
 
 ***
 
@@ -1097,7 +1218,7 @@ DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于
 
 ***
 
-*ai-spec v0.26.0 · Design Rationale Document · 2026-03-26*
+*ai-spec v0.38.0 · Design Rationale Document · 2026-04-02*
 
 </details>
 
@@ -1207,7 +1328,7 @@ The review stage evolved from a simpler review flow into a 3-pass process:
 
 This helps distinguish local code issues from broader system risk.
 
-### 2.13 Harness Engineer: from Prompt Hash to a quality data loop
+### 2.13 Harness Engineer: from Prompt Hash to a quality data loop (v0.31.0+)
 
 Harness Engineer is not just a label for a self-eval step. In ai-spec it is becoming an upper-layer design principle:
 
@@ -1218,6 +1339,25 @@ Harness Engineer is not just a label for a self-eval step. In ai-spec it is beco
 
 The purpose is to turn the generation system into something measurable, comparable, and continuously optimizable, rather than a black-box sequence of prompts.
 
+### 2.14 Security hardening + test engineering + quality gates (v0.36.0–v0.37.0)
+
+These releases focus on making the pipeline **trustworthy** rather than just functional:
+
+- **Security**: shell command injection eliminated via `spawnSync` (no shell parsing); API key file permissions set before writing sensitive data
+- **DSL validation**: endpoint ID uniqueness and model field name uniqueness checks prevent downstream conflicts
+- **Test engineering**: 158 new test cases across 9 modules (mock-server, types-generator, VCR, context-loader, openapi-exporter, spec-versioning, spec-generator, reviewer, code-generator), reaching 409 total / 18 modules / 45% coverage
+- **Quality gates**: `minHarnessScore` blocks low-quality runs at exit; `maxErrorCycles` makes repair loop depth configurable; provider errors now include actionable remediation suggestions
+
+### 2.15 Design Options Dialogue + Pass 0 Compliance + project index (v0.38.0)
+
+v0.38.0 adds quality control points at both ends of the pipeline:
+
+- **Design Options Dialogue** (Step 1.5): AI proposes 2-3 architecture options before spec generation. Users pick one (or blend), and the decision constrains the spec prompt. This prevents "wrong direction discovered too late."
+- **Pass 0 Spec Compliance Check**: exhaustive audit of every requirement in the Spec (endpoints, models, auth, errors, side effects) before the existing 3-pass review. Outputs `ComplianceScore` + blockers list. Pass 1 is freed to focus purely on architecture quality.
+- **Task verificationSteps**: each task now requires concrete, executable verification commands with expected outcomes — no more "works correctly" acceptance criteria.
+- **Project index (`ai-spec scan`)**: discovers sub-projects across a directory tree, persists to `.ai-spec-index.json`, and feeds multi-project context into global constitution generation.
+- **Anti-hallucination skills**: 5 reusable Claude Code slash commands extracted from ai-spec's internal practices (`/scan-singletons`, `/add-lesson`, `/installed-deps`, `/recall-lessons`, `/verify-imports`).
+
 ## 3. Why the DSL layer matters
 
 ### 3.1 Removing ambiguity between spec and code
@@ -1287,8 +1427,8 @@ Documented future work includes:
 - deeper CI/CD integration
 - stronger cross-run observability and evaluation signals
 
-The overall direction is clear: ai-spec is moving from “AI writes code for me” toward “AI-assisted delivery becomes a measurable engineering system.”
+The overall direction is clear: ai-spec is moving from “AI writes code for me” toward “AI-assisted delivery becomes a measurable, trustworthy engineering system.”
 
-*ai-spec v0.26.0 · Design Rationale Document · 2026-03-26*
+*ai-spec v0.38.0 · Design Rationale Document · 2026-04-02*
 
 </details>

package/tests/auto-consolidation.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import { maybeAutoConsolidate } from "../core/knowledge-memory";
+import { CONSTITUTION_FILE } from "../core/constitution-generator";
+
+const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+describe("maybeAutoConsolidate", () => {
+  let tmpDir: string;
+  const mockProvider = {
+    generate: vi.fn(),
+    providerName: "test",
+    modelName: "test-model",
+  };
+
+  beforeEach(async () => {
+    tmpDir = path.join(os.tmpdir(), `ac-test-${Date.now()}`);
+    await fs.ensureDir(tmpDir);
+    mockProvider.generate.mockReset();
+  });
+
+  afterEach(async () => {
+    await fs.remove(tmpDir);
+  });
+
+  it("returns false when no constitution file", async () => {
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir);
+    expect(result).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("returns false when lesson count below threshold", async () => {
+    const lessons = Array.from({ length: 5 }, (_, i) =>
+      `- 📝 **[2026-01-0${i + 1}]** Lesson ${i + 1}`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(false);
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+
+  it("triggers consolidation when lesson count meets threshold", async () => {
+    const lessons = Array.from({ length: 15 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson number ${i + 1} with detail text`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n- 📝 **[2026-04-02]** Consolidated lesson\n"
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(true);
+    expect(mockProvider.generate).toHaveBeenCalled();
+  });
+
+  it("returns false when consolidation fails", async () => {
+    const lessons = Array.from({ length: 15 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson ${i + 1} detail`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockRejectedValueOnce(new Error("API error"));
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 12 });
+    expect(result).toBe(false);
+  });
+
+  it("respects custom threshold", async () => {
+    const lessons = Array.from({ length: 4 }, (_, i) =>
+      `- 📝 **[2026-01-0${i + 1}]** Lesson ${i + 1} text`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    mockProvider.generate.mockResolvedValueOnce("# Constitution\n## 9. 积累教训\n- consolidated\n");
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir, { threshold: 3 });
+    expect(result).toBe(true);
+  });
+
+  it("uses default threshold of 12", async () => {
+    const lessons = Array.from({ length: 10 }, (_, i) =>
+      `- 📝 **[2026-01-${String(i + 1).padStart(2, "0")}]** Lesson ${i + 1}`
+    ).join("\n");
+    await fs.writeFile(
+      path.join(tmpDir, CONSTITUTION_FILE),
+      `# Constitution\n\n## 9. 积累教训 (Accumulated Lessons)\n${lessons}\n`
+    );
+
+    const result = await maybeAutoConsolidate(mockProvider, tmpDir);
+    expect(result).toBe(false); // 10 < 12 default
+    expect(mockProvider.generate).not.toHaveBeenCalled();
+  });
+});

package/tests/combined-generator.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { generateSpecWithTasks } from "../core/combined-generator";
+
+const mockProvider = {
+  generate: vi.fn(),
+  providerName: "test",
+  modelName: "test-model",
+};
+
+beforeEach(() => {
+  mockProvider.generate.mockReset();
+});
+
+describe("generateSpecWithTasks", () => {
+  it("parses spec and tasks from combined output", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      `# Feature Spec\n\nSome spec content.\n\n---TASKS_JSON---\n[{"id":"TASK-001","title":"Create model","description":"Create Order model","layer":"data","filesToTouch":["src/models/order.ts"],"acceptanceCriteria":["Model exists"],"verificationSteps":["Check file"],"dependencies":[],"priority":"high"}]`
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build order system");
+    expect(result.spec).toContain("Feature Spec");
+    expect(result.spec).not.toContain("TASKS_JSON");
+    expect(result.tasks).toHaveLength(1);
+    expect(result.tasks[0].id).toBe("TASK-001");
+    expect(result.tasks[0].layer).toBe("data");
+  });
+
+  it("returns empty tasks when separator is missing", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Feature Spec\n\nNo tasks separator here."
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build feature");
+    expect(result.spec).toContain("Feature Spec");
+    expect(result.tasks).toEqual([]);
+  });
+
+  it("returns empty tasks when JSON after separator is invalid", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "# Spec\n---TASKS_JSON---\nnot valid json"
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "Build feature");
+    expect(result.spec).toBe("# Spec");
+    expect(result.tasks).toEqual([]);
+  });
+
+  it("includes architecture decision in prompt when provided", async () => {
+    mockProvider.generate.mockResolvedValueOnce("# Spec\n---TASKS_JSON---\n[]");
+
+    await generateSpecWithTasks(mockProvider, "Build feature", undefined, "Use microservices");
+    const prompt = mockProvider.generate.mock.calls[0][0] as string;
+    expect(prompt).toContain("Architecture Decision");
+    expect(prompt).toContain("Use microservices");
+  });
+
+  it("includes context when ProjectContext is provided", async () => {
+    mockProvider.generate.mockResolvedValueOnce("# Spec\n---TASKS_JSON---\n[]");
+
+    const context = {
+      techStack: ["express", "prisma"],
+      dependencies: ["express", "prisma"],
+      apiStructure: ["src/routes/user.ts"],
+      fileStructure: ["src/index.ts"],
+    } as any;
+
+    await generateSpecWithTasks(mockProvider, "Build order feature", context);
+    const prompt = mockProvider.generate.mock.calls[0][0] as string;
+    expect(prompt).toContain("Build order feature");
+  });
+
+  it("trims spec and tasks", async () => {
+    mockProvider.generate.mockResolvedValueOnce(
+      "  \n# Spec  \n\n---TASKS_JSON---\n  [{\"id\":\"T1\",\"title\":\"t\",\"description\":\"d\",\"layer\":\"data\",\"filesToTouch\":[],\"acceptanceCriteria\":[],\"verificationSteps\":[],\"dependencies\":[],\"priority\":\"high\"}]  \n"
+    );
+
+    const result = await generateSpecWithTasks(mockProvider, "idea");
+    expect(result.spec).toBe("# Spec");
+    expect(result.tasks).toHaveLength(1);
+  });
+});