ai-spec-dev 0.33.0 → 0.35.0

package/RELEASE_LOG.md

@@ -1,5 +1,231 @@
 # Release Log
 
+<details open>
+<summary>中文</summary>
+
+---
+
+## [Unreleased] 2026-04-01 — P1 Task 验证步骤 + P2 设计方案对话
+
+### 新增 / 增强
+
+**Feature 1 — Task verificationSteps（`core/task-generator.ts`、`prompts/tasks.prompt.ts`、`core/combined-generator.ts`）**
+
+受 Superpowers writing-plans 启发，每个 Task 新增 `verificationSteps` 字段，要求具体可执行的验证命令 + 预期结果，防止"works correctly"式模糊验收标准。
+
+- `SpecTask` 新增 `verificationSteps: string[]`，语义为"the how to verify"（区别于 `acceptanceCriteria` 的"the what"）
+- `tasksSystemPrompt` 新增 verificationSteps 规则段：每条步骤必须是具体命令 + 可观察预期结果，给出 Good/Bad 示例，要求 2-5 条/task，backend 必须含 HTTP 检查，frontend 必须含 UI render + state 检查
+- `combined-generator.ts` 的内联 tasks instruction 同步更新，包含 `verificationSteps` 字段定义
+- `printTasks` 每个 task 输出前 2 条 verificationSteps（灰色），超过 2 条显示 "+ N more"
+
+**Feature 2 — Design Options Dialogue（`core/design-dialogue.ts`、`prompts/design.prompt.ts`、`cli/commands/create.ts`）**
+
+受 Superpowers brainstorming 启发，在 Spec 生成前新增 Step 1.5：AI 提出 2-3 个架构方案供用户选择，选定方案作为约束注入 spec prompt，防止 Spec 生成完后才发现方向不对。
+
+- `prompts/design.prompt.ts` — `designOptionsSystemPrompt`：每个方案含 Approach / Trade-offs（2-3条）/ Best when，保持简短（≤2分钟阅读），附 Recommended 建议
+- `core/design-dialogue.ts` — `DesignDialogue` 类：提案展示 → 用户选择（Option A/B/C / Blend / Skip）→ Blend 模式让 AI 融合多方案；解析 AI 输出的方案标签，提取选定方案全文（最多 400 字符）注入 spec
+- `create.ts` Step 1.5：在 context load 完成后、spec gen 前运行；`--fast` / `--auto` / `--vcr-replay` 自动跳过；`architectureDecision` 传入 `generateSpecWithTasks` 和 `SpecGenerator.generateSpec`
+- `combined-generator.ts` / `spec-generator.ts` 均新增 `architectureDecision?: string` 参数，以 `=== Architecture Decision ===` 段注入 prompt
+
+---
+
+## [Unreleased] 2026-04-01 — Pass 0 Spec Compliance Check + 项目索引 + 抗幻觉 Skills
+
+### 新增 / 增强
+
+**Feature 1 — Pass 0 Spec Compliance Check（`prompts/codegen.prompt.ts`、`core/reviewer.ts`、`core/self-evaluator.ts`）**
+
+受 Superpowers 工作流启发，在现有 3-pass review 前新增专用的 Spec 合规性检查 Pass 0。
+
+- `specComplianceSystemPrompt` — 穷举式审计：从 Spec 中提取所有需求（endpoints、models、business rules、auth、error cases、side effects），逐条标 ✅ / ⚠️ / ❌，输出 `ComplianceScore: X/10` + Blockers 列表
+- `Pass 1 架构 Review` 去除原有"是否覆盖所有需求"条款，Pass 0 已处理，Pass 1 聚焦层分离 / 契约设计 / 安全姿态
+- Pass 1 prompt 注入 Pass 0 合规报告作为上下文，避免重复发现
+- `extractComplianceScore` / `extractMissingCount` 公开导出，供下游消费
+- `create.ts` 在 `stageEnd("review")` 后即时打印合规分 + 缺失需求数
+- `SelfEvalResult` 新增 `complianceScore` 字段；harnessScore 权重更新：当 compliance + review 均可用时，compliance 0.30 · dsl 0.25 · compile 0.20 · review 0.25
+- `printSelfEval` 输出新增 `Compliance: X/10` 行，低于 6 显示红色 ⚠
+- Review History 记录新增 `complianceScore` 字段
+
+**Feature 2 — 项目索引 `ai-spec scan`（`core/project-index.ts`、`cli/commands/scan.ts`）**
+
+- `core/project-index.ts` — 扫描根目录下所有子项目（识别 `package.json` / `go.mod` / `Cargo.toml` / `pom.xml` 等 manifest），持久化到 `.ai-spec-index.json`
+- 增量逻辑：新项目 → 添加 `firstSeen`；已有项目 → 更新 `techStack / hasConstitution / lastSeen`；目录消失 → 标记 `missing:true`（不删除记录）
+- Git Worktree 过滤：`.git` 为文件（非目录）时跳过，防止 ai-spec 生成的 worktree 被误识别为项目
+- `ai-spec scan` — 扫描并输出变更摘要（added / updated / unchanged / missing）
+- `ai-spec scan --list` — 不重新扫描，直接展示当前 index
+- `ai-spec init --global` 联动：优先读取 index，对每个活跃项目提取 type / techStack / constitution §1-§6 前 2000 字符，作为全局宪法生成的多项目上下文；无 index 时 fallback 并提示先 `scan`
+
+**Feature 3 — 抗幻觉 Skill 文件（`.claude/commands/`）**
+
+从 ai-spec 现有抗幻觉设计中提炼 5 个可复用 Claude Code slash command skill，供团队共享：
+
+- `/scan-singletons` — 扫描项目所有单例 config 文件（i18n / constants / routes / store-index），输出"只能修改、绝不重建"清单
+- `/add-lesson` — 将 review 发现写入宪法 §9，含去重（前 60 字符比对）+ 分类（bug/security/pattern/perf/convention）+ 时间戳
+- `/installed-deps` — 列出 `package.json` 所有依赖作为 codegen 白名单，附检测常用替代品歧义提示
+- `/recall-lessons` — 读取 §9，按与当前任务的相关度（High/Medium/Low）筛选并展示历史教训
+- `/verify-imports` — 验证文件中所有 import 路径（alias 解析 + 相对路径 + 包名白名单），输出 broken imports 及修复建议
+
+---
+
+## [Unreleased] 2026-04-01 — VCR 录制回放 + 异步 §9 + Approval Gate 增强
+
+### 新增 / 增强
+
+**Feature 1 — VCR 录制 & 零成本回放（`core/vcr.ts`、`cli/commands/vcr.ts`、`cli/commands/create.ts`）**
+
+受 Claude Code VCR token 计数测试模式启发，将所有 AI 响应录制成 JSON 快照，供离线无 API 调用地回放。
+
+- `VcrRecordingProvider` — 透明包装任意 `AIProvider`，拦截每次 `generate()` 并记录 `(index, promptPreview, callHash, response, providerName, modelName, ts, durationMs)`；`save()` 支持合并 spec + codegen 两个 recorder 并按时间戳排序
+- `VcrReplayProvider` — 按序返回预录响应，入参 prompt 被忽略；录制耗尽时抛出明确错误
+- 快照存储在 `.ai-spec-vcr/{runId}.json`，与 RunLog 使用相同 `runId`，可交叉查询
+- `ai-spec vcr list` — 列出所有录制（runId、AI 调用数、provider/model、录制日期）
+- `ai-spec vcr show <runId>` — 逐条展示每次 AI 调用的 promptPreview + callHash + 耗时
+- CLI 选项：`--vcr-record`（当次运行录制）、`--vcr-replay <runId>`（零 API 调用回放）
+- 实现 fire-and-await 模式：spec 和 codegen 两个 provider 分别包装，运行结束后统一 merge 保存
+
+**Enhancement 1 — §9 知识积累改为异步 fire-and-await（`cli/commands/create.ts`）**
+
+原来 `await accumulateReviewKnowledge(...)` 阻塞在 Loop 2 结构性反馈之前，拉长了关键路径。
+
+- 将调用改为立即启动、在 `runLogger.finish()` 前 `await`（fire-and-await 模式）
+- Loop 2 交互式结构分析不再等待 §9 写入，用户体验更流畅
+- 错误通过 `.catch()` 打印 `⚠ §9 accumulation failed: ...`，不影响主流程
+
+**Enhancement 2 — Approval Gate DSL 范围预估（`cli/commands/create.ts`）**
+
+原来 Approval Gate 只显示行数和字数，用户难以判断代码生成规模。
+
+- 新增 `estimateFromSpec(spec)` 内联逻辑（正则，无 AI 调用）：从 spec 文本统计 HTTP 端点数（`GET/POST/PUT/PATCH/DELETE /`）和数据模型数（`## Model`、`**Xxx**:`）
+- Approval Gate 增加 `Est. DSL scope : ~N endpoint(s), ~M model(s) → ~K files` 预估行
+- 让用户在点击 Proceed 前对代码生成规模有量化感知
+
+---
+
+## [Unreleased] 2026-04-01 — Pipeline 可靠性强化（二）：JSONL 崩溃恢复 + 熔断 + Token Budget
+
+### 功能增强
+
+**Enhancement 1 — RunLog JSONL Append-Only Shadow（`core/run-logger.ts`、`core/run-trend.ts`）**
+
+原有 `RunLogger.flush()` 是异步 fire-and-forget 的全量 JSON 重写，进程崩溃时当次 RunLog 全丢。
+
+- 新增 `appendJsonlLine(filePath, record)` — 用 `fs.appendFileSync` 同步追加，保证每条记录落盘后才继续执行
+- `RunLogger` 构造时立即写 `header` 行到 `{runId}.jsonl`；每个 `push()`、`stageFail()`、`setPromptHash()`、`setHarnessScore()`、`fileWritten()`、`finish()` 均追加对应类型的 JSONL 行（`header` / `entry` / `error` / `file` / `meta` / `footer`）
+- 原有 `.json` 全量文件保留不变（消费者 `trend`、`dashboard`、`logs` 无需改动）
+- 新增 `reconstructRunLogFromJsonl(path)` — 从 JSONL 行逐条重建 `RunLog`，供崩溃恢复使用
+- `loadRunLogs()` 新增孤儿 `.jsonl` 恢复路径：扫描到没有对应 `.json` 的 `.jsonl` 文件时，自动重建并纳入返回结果
+
+**Enhancement 2 — ErrorFeedback 无进展熔断（`core/error-feedback.ts`）**
+
+原有修复循环没有"进展检测"，即使每次修复后错误数未减少，仍会消耗完所有 `maxCycles`。
+
+- 新增 `prevErrorCount` 跟踪上一轮的错误数量
+- 每次 fix 后重新检查：若 `allErrors.length >= prevErrorCount`（错误数未减少），立即中止并打印 `⚠ Auto-fix made no progress` 提示，不再浪费额外 AI 调用
+- 参考：Claude Code `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3` 防止 compact 死循环的同类设计
+
+**Enhancement 3 — Command Output + File Content Token Budget（`core/error-feedback.ts`）**
+
+- 新增 `MAX_COMMAND_OUTPUT_CHARS = 50_000`（约 10K tokens）：`runCommand` 返回的 stderr/stdout 超过此限时截断，防止巨型构建输出撑满 AI context
+- 新增 `MAX_FIX_FILE_CHARS = 60_000`（约 12K tokens）：`attemptFix` 中发给 AI 的 `existingContent` 超过此限时截断并附加提示，AI 仍可通过错误行号定位问题
+- 参考：Claude Code `applyToolResultBudget(toolResult, maxTokens)` 工具输出预算设计
+
+---
+
+## [Unreleased] 2026-04-01 — Pipeline 可靠性强化：结构化 Review Findings + §9 知识闭环
+
+### 功能增强
+
+**Enhancement 1 — Loop 2 结构性发现：正则 → 结构化 JSON（`prompts/codegen.prompt.ts`、`core/dsl-feedback.ts`）**
+
+原有 `extractStructuralFindings` 用正则解析 AI 生成的 review 自然语言，格式漂移会导致静默漏报，且只覆盖硬编码的 4 种关键词。
+
+- `reviewArchitectureSystemPrompt` Pass 1 格式末尾新增 `## 🔍 结构性发现 JSON` 段，要求 AI 强制输出 `{"structuralFindings": [...]}` JSON block（即使无发现也输出空数组），category 枚举与原有一致：`auth_design` / `api_contract` / `model_design` / `layer_violation` / `other_design`
+- `extractStructuralFindings` 改为**优先解析 JSON block**：从 Pass 1 文本提取 ` ```json{...}``` `，parse `structuralFindings` 数组并做类型守卫过滤；解析失败或旧格式 review 才 fallback 到原有正则逻辑（向后兼容）
+- 结果：Loop 2 发现的问题不再受限于关键词列表，任何被 Pass 1 明确指出的设计问题都会进入反馈环
+
+**Enhancement 2 — §9 知识积累真正形成双向闭环（`prompts/spec.prompt.ts`、`core/reviewer.ts`）**
+
+原有实现的两个断层：
+1. constitution 虽然注入到 spec 生成 prompt，但 `specPrompt` 没有明确指令让 AI 去应用 §9 教训
+2. Reviewer 三 Pass 完全不读 constitution，无法检验新代码是否重蹈 §9 记录的问题
+
+修复：
+- `specPrompt` 末尾新增 CRITICAL 指令：如果 constitution 含 §9，spec 生成前必须逐条审阅教训；对直接相关的教训，在 §8 实施要点末尾追加「⚠ 基于历史教训：[简述规避方式]」
+- `reviewer.ts` 新增 `loadAccumulatedLessons(projectRoot)` — 读取 constitution 中 §9 段落（`## 9. 积累教训` 到下一 `## \d` 或 EOF）；注入到 Pass 1 arch review prompt（`=== §9 历史积累教训 ===`），让 reviewer 能交叉检验新代码是否复现已知问题，发现则写入 JSON findings 块触发 Loop 2
+
+**两个闭环现在都真正贯通：**
+```
+Review → §9 写入 constitution
+              ↓
+    下次 create spec 时 → spec 生成读取 §9 → 设计时规避
+              ↓
+    Review Pass 1 读取 §9 → 检验代码是否复现 → 若复现触发 Loop 2 修正 DSL
+```
+
+---
+
+## [Unreleased] 2026-03-31 — 文档同步：README / purpose / RELEASE_LOG
+
+### 文档更新
+
+- README 首页主流程同步到最新架构：
+  - 补入 **DSL Gap Feedback**
+  - 补入 **Review→DSL Loop**
+  - 明确 `logs` / `trend` / `dashboard` 消费 Harness Self-Eval 的 RunLog 数据
+  - 补充 DSL 的下游产物说明（`types` / `export` / `mock` / workspace 契约注入）
+- purpose 文档升级到 **v0.34.0** 口径：
+  - 版本记录速览补入 v0.32.0 / v0.33.0 / v0.34.0
+  - 新增“两条 Pipeline 反馈环”章节
+  - 新增“DSL 的多出口价值：类型、Dashboard 与可观测性”章节
+  - 完整功能矩阵扩展到 `types`、`logs`、`trend`、`dashboard`
+- purpose 的 Mermaid 流程图已切换为 **SVG 图片 + 折叠纯文本备用版**，方便在不支持 Mermaid 的文档平台中阅读
+- RELEASE_LOG 新增当前文档同步记录，保证产品叙事与代码实现保持一致
+
+---
+
+## [0.34.0] 2026-03-31 — Harness Dashboard + TypeScript 类型生成
+
+### 新增内容
+
+**Feature 1 — `ai-spec dashboard`（`core/dashboard-generator.ts`、`cli/commands/dashboard.ts`）**
+
+- 基于现有 `.ai-spec-logs/` RunLog 数据，一键生成静态 HTML Harness Dashboard
+- 包含：
+  - Overview 统计（总运行数 / 平均分 / 编译通过率）
+  - Score Trend 折线图（SVG，最近 30 次有评分运行）
+  - Prompt 版本对比表（avg / best / worst，当前版本高亮）
+  - 近 10 次运行历史（带评分条形）
+  - 阶段耗时柱状图（平均 ms，前 8 阶段）
+  - Top 5 错误频次统计
+- 零外部依赖（纯 inline CSS + SVG）
+- `--open` 选项：生成后自动打开浏览器
+
+```bash
+ai-spec dashboard              # 生成 .ai-spec/dashboard.html
+ai-spec dashboard --open       # 生成后自动在浏览器打开
+ai-spec dashboard --last 20    # 只分析最近 20 次运行
+ai-spec dashboard --output ./report.html
+```
+
+---
+
+**Feature 2 — `ai-spec types`（`core/types-generator.ts`、`cli/commands/types.ts`）**
+
+- DSL → TypeScript 类型文件，前端可直接 import，无需手写
+- 生成内容：
+  - 所有 `models` → `export interface ModelName { ... }`（含可选/必填、类型映射）
+  - 所有 `endpoints.request.body/query/params` → `export interface PostXxxRequest { ... }`
+  - `export const API_ENDPOINTS = { ... } as const`（含 method / path / auth）
+  - 前端 `components[].props` → `export interface ComponentNameProps { ... }`
+- 类型映射：`String→string`，`Int/Float→number`，`Boolean→boolean`，`DateTime→string`，`PascalCase→该 interface 引用`
+
+```bash
+ai-spec types                  # 生成 .ai-spec/<feature>.types.ts
+ai-spec types --stdout         # 打印到 stdout（适合管道）
+ai-spec types --output src/types/api.ts
+ai-spec types --no-endpoint-map   # 不生成 API_ENDPOINTS 常量
+```
+
 ---
 
 ## [0.33.0] 2026-03-30 — Pipeline 反馈环：DSL Gap Loop + Review→DSL Loop
@@ -74,6 +300,13 @@ Spec → DSL 提取
 
 ---
 
+**内部重构（2026-03-31）— CLI 命令拆分**
+
+- `cli/index.ts` 从 2533 行拆分为 42 行入口 + 13 个独立命令文件（`cli/commands/*.ts`）+ 共享工具层（`cli/utils.ts`）
+- 无任何用户可见功能变化，编译输出与重构前等价
+
+---
+
 ## [0.32.0] 2026-03-30 — Harness 数据闭环：`trend` / `logs` 命令 + DSL Coverage 细化评分
 
 ### 新增内容
@@ -2285,3 +2518,75 @@ Spec + Tasks 通过单次 AI 调用完成（`core/combined-generator.ts`），
 - `ai-spec review`：独立代码审查命令
 - 支持 `claude-code` / `api` / `plan` 三种代码生成模式
 - 项目上下文自动扫描（package.json / Prisma schema / 路由文件）
+
+</details>
+
+<details>
+<summary>English</summary>
+
+# Release Log
+
+This section provides an English companion view for the detailed Chinese changelog above. It keeps the same chronological direction while summarizing each version at a higher level for bilingual reading.
+
+## Version Summary
+
+- **Unreleased** — Synced README, purpose, and RELEASE_LOG to reflect the latest pipeline, feedback loops, SVG diagrams, and observability narrative.
+- **0.34.0** — Added a static Harness Dashboard and DSL-to-TypeScript type generation.
+- **0.33.0** — Introduced two pipeline feedback loops: DSL Gap Loop and Review→DSL Loop.
+- **0.32.0** — Closed the harness data loop with `trend`, `logs`, and more detailed DSL coverage scoring.
+- **0.31.0** — Introduced the Harness Engineer layer with `promptHash` and inline self-evaluation during `create`.
+- **0.30.0** — Improved error-fix dependency ordering and multiline import awareness for frontend context extraction.
+- **0.29.0** — Performed a broad hardening pass across RunLogger instrumentation, update snapshots, score trend output, and dead-code cleanup.
+- **0.28.0** — Upgraded review from 2-pass to 3-pass by adding impact assessment and code complexity analysis.
+- **0.27.0** — Added industrial reliability foundations: provider robustness, snapshot restore, and structured RunLog / RunId support.
+- **0.26.0** — Fixed stability issues in multi-repo review, parallel batch tolerance, and corrupted tasks JSON recovery.
+- **0.25.0** — Repaired context extraction for HTTP imports, pagination examples, and false crash detection.
+- **0.24.0** — Fixed lesson counting, `export default`, `impliesRegistration`, and dependency topological sorting issues.
+- **0.23.0** — Eliminated a filename hallucination bug by correcting `index.vue` generation toward the actual component name.
+- **0.22.0** — Strengthened frontend three-layer separation by introducing a `view` layer and fixing API→Store naming hallucinations.
+- **0.21.0** — Fixed store behavior contract extraction, including `fetchTasks` vs `fetchTaskList` hallucination issues.
+- **0.20.0** — Added one-command mock integration with `--serve` and `--restore`.
+- **0.19.0** — Rewrote error parsing, completed behavior contract extraction, and fixed Auto Gate behavior.
+- **0.18.0** — Added `ai-spec learn`, behavior contract injection, and made Approval Gate a hard gate.
+- **0.17.0** — Injected the full constitution into generation, improved export caching, and added constitution length warnings.
+- **0.16.0** — Added spec quality pre-assessment, layered code review, and TDD mode.
+- **0.15.0** — Added parallel task execution for tasks within the same dependency layer.
+- **0.14.5** — Added extraction and injection of real frontend pagination patterns.
+- **0.14.4** — Improved frontend output reliability with route index auto-registration and cross-task function-name consistency.
+- **0.14.3** — Added the welcome screen.
+- **0.14.2** — Added Java / Maven / Gradle project context awareness.
+- **0.14.1** — Fixed a critical bug where non-Node repos incorrectly generated TypeScript-oriented output.
+- **0.14.0** — Unified frontend framework detection and injected frontend context explicitly in task mode.
+- **0.13.9** — Added component reuse awareness.
+- **0.13.8** — Fixed store HTTP hallucinations and HTTP client import hallucinations.
+- **0.13.6** — Fixed layout hallucinations and route registration reliability.
+- **0.13.5** — Fixed frontend codegen hallucinations and route convention issues.
+- **0.13.4** — Fixed MiMo `max_tokens` truncation.
+- **0.13.3** — Fixed DSL validation false positives.
+- **0.13.2** — Added API key persistence.
+- **0.13.1** — Auto-skipped worktree for frontend generation and fixed related bugs.
+- **0.13.0** — Strengthened context awareness and error-feedback behavior.
+- **0.12.2** — Added PHP / Lumen backend support.
+- **0.12.1** — Restored MiMo v2 Pro support.
+- **0.12.0** — Added constitution consolidation with `ai-spec init --consolidate`.
+- **0.11.0** — Delivered three high-priority additions: incremental update, OpenAPI export, and multi-language codegen prompts.
+- **0.10.0** — Added Mock Server support and expanded multi-language backend support.
+- **0.9.0** — Fixed frontend DSL extraction, decomposition context, and codegen injection precision.
+- **0.8.0** — Enhanced frontend support and added shared global constitutions across projects.
+- **0.7.0** — Introduced Phase 4 multi-repo workspace orchestration.
+- **0.6.0** — Introduced Phase 3 test generation, error feedback, and lesson accumulation.
+- **0.5.0** — Introduced Phase 2 DSL transformation, schema handling, and validation.
+- **0.4.0** — Introduced Phase 1 industrial pipeline infrastructure.
+- **0.3.0** — Added project constitution support, task decomposition, and RTK integration.
+- **0.2.0** — Added multi-provider support and interactive model switching.
+- **0.1.0** — Initial release with Spec generation, Git worktree isolation, code generation, review, and basic project context scanning.
+
+## Evolution Themes
+
+- **Pipeline structure** — The project evolved from prompt-driven generation into a staged, restartable engineering pipeline.
+- **Project grounding** — Context extraction, constitutions, DSL, and behavior contracts reduce repository-specific hallucinations.
+- **Quality loops** — Testing, error feedback, review passes, lesson accumulation, and harness scoring create feedback channels after generation.
+- **Workspace orchestration** — Multi-repo features extend the system from single-repo coding to contract-aware cross-stack delivery.
+- **Harness observability** — `promptHash`, `harnessScore`, `logs`, `trend`, and `dashboard` turn runs into measurable engineering data.
+
+</details>