ai-spec-dev 0.14.1 → 0.24.0

package/.claude/settings.local.json

@@ -6,12 +6,7 @@
       "Bash(grep -E \"^./\\\\w+/|^./\\\\w+\\\\.ts$\")",
       "Bash(wc -l core/*.ts prompts/*.ts)",
       "Bash(ls:*)",
-      "Bash(ls \"D:\\\\Document\\\\xwechat_files\\\\wxid_01h824wams3o22_fdb0\\\\msg\\\\file\\\\2026-03\\\\ai-spec-dev-poc\\(1\\)\\(1\\)\\\\ai-spec-dev-poc\\\\dist\")",
-      "Bash(npm view:*)",
-      "Bash(ls \"D:\\\\Document\\\\xwechat_files\\\\wxid_01h824wams3o22_fdb0\\\\msg\\\\file\\\\2026-03\\\\ai-spec-dev-poc\\(1\\)\\(1\\)\\\\ai-spec-dev-poc\\\\dist/cli\")",
-      "Bash(npx tsup:*)",
-      "Bash(node node_modules/tsup/dist/cli-main.js)",
-      "Bash(npm publish:*)",
+      "Bash(ls \"D:/Document/xwechat_files/wxid_01h824wams3o22_fdb0/msg/file/2026-03/ai-spec-dev-poc\\(2\\)/ai-spec-dev-poc/dist\")",
       "Bash(npm whoami:*)"
     ]
   }

package/README.md

@@ -147,6 +147,7 @@ ai-spec init                分析代码库，生成项目宪法（.ai-spec-cons
 ai-spec init --consolidate  整合宪法：将 §9 积累教训提炼归并到 §1–§8，清理冗余（Constitution Rebase）
 ai-spec create [idea]       完整工作流：宪法 → context → spec → tasks → refine → worktree → codegen → 测试生成 → 错误修复 → review → 经验积累
 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 代码审查（架构层 + 实现层），并打印评分趋势
@@ -204,6 +205,7 @@ ai-spec create                      # 省略 idea 时交互式询问
 --skip-error-feedback               # 跳过错误反馈自动修复
 --skip-review                       # 跳过代码审查（同时跳过经验积累）
 --skip-assessment                   # 跳过 Spec 质量预评估（省一次 AI 调用）
+--force                             # 强制绕过 minSpecScore 质量门槛（score 不足时继续执行）
 
 # 模式增强
 --tdd                               # TDD 模式：在代码生成前写入真实断言测试，由 error feedback loop 驱动实现通过测试
@@ -240,9 +242,25 @@ ai-spec config --model <name>       # 设置默认 spec model
 ai-spec config --codegen <mode>     # 设置默认 codegen 模式
 ai-spec config --codegen-provider <name>  # 设置默认 codegen provider
 ai-spec config --codegen-model <name>     # 设置默认 codegen model
+ai-spec config --min-spec-score <n> # 设置 Spec 质量门槛（1-10，0 = 禁用）
 ai-spec config --reset              # 清空配置文件
 ```
 
+> **Spec 质量门槛（minSpecScore）**
+> - 设置后，`create` 在 Approval Gate 前会运行质量评估，`overallScore` 低于阈值时阻断流程
+> - **`--auto` 模式同样生效**：CI 环境中配置了门槛则强制执行，避免低质量 Spec 静默通过
+> - `--force` 可临时绕过（输出黄色警告）
+> - 未配置（默认 0）时评估仅为建议性，不阻断
+
+#### `ai-spec learn`
+
+```
+ai-spec learn "教训或决策描述"      # 直接写入宪法 §9
+ai-spec learn                       # 省略时交互式输入
+```
+
+> 适合混用其他 AI 工具（Cursor / Copilot）的团队：在任何场景发现问题或做出架构决策时，无需经过完整 review 流程，直接将知识写入宪法，下次 `create` 即生效。
+
 #### `ai-spec workspace`
 
 ```
@@ -277,12 +295,14 @@ ai-spec export --dsl <path>         # 指定 DSL 文件
 #### `ai-spec mock`
 
 ```
-ai-spec mock                        # 读取最新 DSL，生成 mock/server.js（Express 独立 Mock 服务器）
-ai-spec mock --port 3002            # 指定端口（默认 3001）
-ai-spec mock --proxy                # 同时生成前端框架 Proxy 配置片段（Vite/Next.js/webpack 自动识别）
-ai-spec mock --msw                  # 同时生成 MSW Handlers（src/mocks/handlers.ts + browser.ts）
-ai-spec mock --dsl <path>           # 指定 DSL 文件路径（默认自动寻找最新）
-ai-spec mock --workspace            # 为工作区内所有后端 repo 批量生成 Mock
+ai-spec mock                                    # 读取最新 DSL，生成 mock/server.js（Express 独立 Mock 服务器）
+ai-spec mock --port 3002                        # 指定端口（默认 3001）
+ai-spec mock --proxy                            # 同时生成前端框架 Proxy 配置片段（Vite/Next.js/webpack 自动识别）
+ai-spec mock --msw                              # 同时生成 MSW Handlers（src/mocks/handlers.ts + browser.ts）
+ai-spec mock --dsl <path>                       # 指定 DSL 文件路径（默认自动寻找最新）
+ai-spec mock --workspace                        # 为工作区内所有后端 repo 批量生成 Mock
+ai-spec mock --serve --frontend <path>          # 生成后直接启动 Mock 服务器 + 自动 patch 前端 Proxy
+ai-spec mock --restore --frontend <path>        # 撤销 Proxy patch，停止 Mock 服务器
 ```
 
 ---
@@ -640,8 +660,27 @@ ai-spec mock --port 3002 --proxy --msw
 
 # 为工作区所有后端 repo 批量生成
 ai-spec mock --workspace
+
+# ── 一键联调（推荐）──────────────────────────────────────────
+# 生成 + 启动 Mock 服务器（后台） + 自动 patch 前端 Proxy
+ai-spec mock --serve --frontend ../my-frontend
+
+# 联调结束后恢复（撤销 Proxy patch，停止 Mock 服务器）
+ai-spec mock --restore --frontend ../my-frontend
 ```
 
+**`--serve` 详解：**
+
+`--serve` 做以下三件事：
+1. 在后台启动 `node mock/server.js`（PID 记录在 `.ai-spec-mock.lock.json`）
+2. 根据前端框架自动 patch Proxy 配置：
+   - **Vite**：生成 `vite.config.ai-spec-mock.ts`（mergeConfig 方式，非破坏性），在 `package.json` 添加 `dev:mock` 脚本
+   - **CRA**：临时修改 `package.json` 的 `"proxy"` 字段（原值备份在 lock 文件）
+   - **Next.js / webpack**：打印手动配置说明
+3. 打印前端启动命令（`npm run dev:mock` 或 `npm start`）
+
+`--restore` 的逆操作：删除 `vite.config.ai-spec-mock.ts`、还原 `package.json`、发送 SIGTERM 到 Mock 服务器进程。
+
 **生成的文件：**
 
 | 文件 | 说明 |
@@ -653,6 +692,8 @@ ai-spec mock --workspace
 | `mock/proxy.webpack.comment.txt` | webpack devServer.proxy 配置片段（默认 fallback） |
 | `src/mocks/handlers.ts` | MSW 请求拦截 handlers（`--msw`） |
 | `src/mocks/browser.ts` | MSW browser worker 初始化（`--msw`） |
+| `vite.config.ai-spec-mock.ts` | 前端临时 Vite 配置（`--serve`，非破坏性，`--restore` 后删除） |
+| `.ai-spec-mock.lock.json` | Proxy patch 记录 + Mock 服务器 PID（`--restore` 后删除） |
 
 **Mock Server 特性：**
 
@@ -661,18 +702,43 @@ ai-spec mock --workspace
 - Fixture 数据从 DSL 数据模型的字段类型推断（String → `"example_xxx"`，DateTime → ISO 8601 字符串，etc.）
 - GET List 端点（描述含 "list"/"all"）自动返回分页结构 `{ data: [...], total, page, pageSize }`
 
-**联调工作流：**
+**联调工作流（手动）：**
 
 ```
 后端 repo:
   ai-spec create "用户登录功能"    # → 生成 DSL + 代码框架
-  ai-spec mock --proxy             # → 生成 mock/server.js
+  ai-spec mock                     # → 生成 mock/server.js
   node mock/server.js              # → Mock 服务器运行在 localhost:3001
 
 前端 repo:
   配置 Proxy: 将 /api 代理到 localhost:3001   （参见 mock/proxy.*.txt）
-  # 或者:
-  ai-spec mock --msw               # → 生成 MSW handlers，前端完全脱离后端运行
+```
+
+**联调工作流（一键，推荐）：**
+
+```bash
+# 后端 repo 执行（一条命令完成全部）
+cd backend-repo
+ai-spec mock --serve --frontend ../frontend-repo
+# → 自动生成 server.js，启动 Mock 服务器（后台），patch 前端 Proxy
+
+# 按提示在前端 repo 启动 Dev Server
+cd ../frontend-repo
+npm run dev:mock
+# → 打开浏览器，直接看到 Mock 数据
+
+# 联调结束
+cd ../backend-repo
+ai-spec mock --restore --frontend ../frontend-repo
+```
+
+**工作区一键联调（`ai-spec create --serve`）：**
+
+在多 Repo 工作区模式下，加 `--serve` 标志，Pipeline 完成后自动执行上述流程：
+
+```bash
+ai-spec create "用户登录功能" --serve
+# 完成后自动：生成 Mock → 启动服务器 → patch 前端 Proxy → 打印 dev 命令
 ```
 
 ---

package/RELEASE_LOG.md

@@ -2,6 +2,477 @@
 
 ---
 
+## [0.24.0] 2026-03-25 — 四项质量修复（lesson 计数、export default、impliesRegistration、依赖拓扑排序）
+
+### 修复内容
+
+**Fix #1 — Lesson count 误计**
+- 文件：`prompts/consolidate.prompt.ts`
+- 问题：`parseConstitutionStats` 中用 `line.startsWith("-")` 统计 §9 教训条数，会将多行教训的子列表项、普通破折号行都计入，导致计数虚高、过早触发 consolidate 警告。
+- 修复：改为正则 `/^-\s+.*\*\*\[\d{4}-\d{2}-\d{2}\]\*\*/` 只匹配带日期徽章的真实教训行。
+
+**Fix #2 — `export default function/class` 未捕获**
+- 文件：`core/code-generator.ts` → `extractBehavioralContract`
+- 问题：React 函数组件 (`export default function Foo()`) 和 class 组件只被当作单行 export 处理，消费者看不到函数体内的 return 结构与 props 形状。
+- 修复：在单行 export 分支之前新增完整块捕获逻辑（大括号深度计数），与 `defineStore` 捕获逻辑对称。
+
+**Fix #3 — `impliesRegistration` 对 `route`/`view`/`api` 层失效**
+- 文件：`core/code-generator.ts` → `runApiModeWithTasks`
+- 问题：`impliesRegistration` 仅依赖任务文本关键词，若 `route` 层任务描述不含 "route"/"router" 等词，则跳过路由索引更新，新路由永远不注册。
+- 修复：增加 `task.layer === "route" || "view" || "api"` 的层级直接判断，文本关键词作为额外补充。
+
+**Fix #4 — `dependencies` 字段从未使用**
+- 文件：`core/code-generator.ts` + `core/task-generator.ts`
+- 问题：同层任务始终全量并行，任务 JSON 中声明的 `dependencies` 字段完全被忽略，层内顺序依赖无法保证。
+- 修复：
+  - 新增 `topoSortLayerTasks(tasks)` 函数，将同层任务按依赖关系分拆为多个批次（batch）；同批次内仍并行，批次间顺序执行。
+  - 每批完成后立即更新 `generatedFileCache`，确保后续批次能看到前驱批次的导出。
+  - `task-generator.ts` 同步更新 `TaskLayer` 类型、`LAYER_ORDER`、`layerColors`，补齐 `view` 和 `route` 层。
+
+---
+
+## [0.23.0] 2026-03-25 — 文件名幻觉修复（`index.vue` → `TaskManagement.vue`）
+
+### 根本原因
+
+路由文件引用的是 `@/views/task-management/index.vue`，但实际文件是 `TaskManagement.vue`。
+
+**两个叠加 bug：**
+
+**Bug 1：`generatedFileCache` 不缓存 `views/` 文件**
+
+cache 的 regex 只覆盖 `src/api*/service*/stores*/composables*/`，视图组件从未被缓存。路由文件生成时，cache 里根本看不到 `TaskManagement.vue` 的存在，只能靠「约定」猜文件名。
+
+`index.vue` 是全球最常见的视图组件命名（Next.js、Nuxt、Vite 项目大量使用），模型先验概率极高 → 幻觉必然发生。
+
+**Bug 2：路由文件和视图组件在同一层（`view`）或路由在更早的层**
+
+即使扩展了 cache regex，如果路由文件和视图组件并行执行，视图的 cache 条目还是不存在。
+
+### 修复
+
+**1. 新增 `route` 层（`core/code-generator.ts`）**
+
+完整的前端六层链：
+```
+data → infra → service → api → view → route → test
+```
+
+| 层 | 前端含义 |
+|---|---|
+| `service` | `src/api/` HTTP 函数 |
+| `api` | `src/stores/` stores |
+| `view` | `src/views/` 页面组件 |
+| `route` | `src/router/routes/` 路由文件 ← 新增 |
+| `test` | 测试 |
+
+**2. `view` 文件加入 cache（路径 sentinel，`core/code-generator.ts`）**
+
+扩展 cache regex：加入 `views?/pages?/`。但不读取文件内容（SFC 300+ 行太大），而是写入固定 sentinel：
+```
+// view component — use this exact path for router imports
+```
+
+**3. `buildGeneratedFilesSection` 对 view 文件只展示路径标记**
+
+```
+// exists: src/views/task-management/TaskManagement.vue
+```
+
+路由生成 AI 看到的不是猜测，而是已知事实。
+
+**4. `tasks.prompt.ts` 四层分离规则**
+
+含具体 EXAMPLE：
+```
+TASK-003 layer:"view"   src/views/task-management/TaskManagement.vue
+TASK-004 layer:"route"  src/router/routes/taskManagement.ts  ← 此时 cache 有 TaskManagement.vue ✓
+```
+
+**5. `codegen.prompt.ts` Rule 17 补充路径规则**
+
+"// exists:" 条目中的路径是权威来源，不得替换为 `index.vue` 或其他猜测值。
+
+---
+
+## [0.22.0] 2026-03-25 — 前端三层分离（`view` 层）彻底根治 API→Store 命名幻觉
+
+### 根本原因
+
+v0.21.0 修复了「store → 页面」的命名幻觉，但遗漏了「**api 文件 → store**」这条更上游的依赖链。
+
+v0.21.0 的 `tasks.prompt.ts` 写的是：
+```
+"service" — API call files (src/api/) AND stores (src/stores/)
+```
+
+两者被分配到**同一层**（`service`），并行执行。生成 `taskStore.ts` 时，`taskManagement.ts`（exports `getTaskList`）还没写完，不在 cache 里。Store AI 只能猜 `getTasks`。
+
+**完整的前端命名幻觉依赖链：**
+```
+src/apis/taskManagement.ts  (layer: service)
+  ↓ store 需要知道这里有哪些函数
+src/stores/taskStore.ts     (layer: ???)  ← 必须在 service 之后
+  ↓ 页面需要知道这里有哪些 actions
+src/views/TaskManagement.vue (layer: ???) ← 必须在 store 之后
+```
+
+如果三者在同一层或 store 与 api 同层，幻觉必然发生。
+
+### 修复
+
+**1. 新增 `view` 层（`core/code-generator.ts`）**
+
+`LAYER_ORDER` 从 5 层扩展到 6 层：
+```
+["data", "infra", "service", "api", "view", "test"]
+```
+
+映射关系：
+| 层 | 后端含义 | 前端含义 |
+|---|---|---|
+| `service` | 业务逻辑 | API call 函数（`src/api/` 或 `src/apis/`） |
+| `api` | 路由/控制器 | Pinia/Vuex stores（`src/stores/`） |
+| `view` | （后端不用） | 页面/视图组件（`src/views/`, `src/pages/`） |
+| `test` | 测试 | 测试 |
+
+**2. `tasks.prompt.ts` 三层分离规则**
+
+明确的层级分配规则，含错误原因解释：
+```
+service → src/apis/*.ts   (HTTP 函数，如 getTaskList)
+api     → src/stores/*.ts (store 调用 service 层函数 — service 层已在 cache 里)
+view    → src/views/*.vue (页面调用 store — api 层已在 cache 里)
+```
+
+附带具体 EXAMPLE 展示正确的三 task 写法。
+
+### 效果
+
+完整的三级 cache 保障：
+```
+service 层完成 → cache 有 getTaskList ← store 生成时看得到 ✓
+api 层完成    → cache 有 fetchTasks  ← 页面生成时看得到  ✓
+```
+
+---
+
+## [0.21.0] 2026-03-25 — Store 行为契约提取修复（`fetchTasks` → `fetchTaskList` 幻觉根治）
+
+### 根本原因分析
+
+触发条件：**Pinia / Vuex / Zustand store 文件被生成后，消费该 store 的页面/组件在同一轮继续生成时，函数名出现幻觉**（如 `fetchTasks` 被猜成 `fetchTaskList`、`loadTasks`、`fetchTaskData`）。
+
+**两个叠加 bug：**
+
+**Bug 1：`extractBehavioralContract` 对 store 文件是空壳**
+
+Pinia composition API store 的典型结构：
+```typescript
+export const useTaskStore = defineStore('task', () => {
+  const tasks = ref<Task[]>([])
+  async function fetchTasks() { ... }
+  return { tasks, fetchTasks }  // ← 这里是真正的公开 API
+})
+```
+
+`extractBehavioralContract` 的 `export const ...` 规则只捕获**第一行**：
+```
+export const useTaskStore = defineStore('task', () => {
+```
+`return { tasks, fetchTasks }` 完全丢失。消费方 AI 看到的是空壳，只能靠直觉猜函数名——而 GPT/Claude 类模型的直觉会把 `fetchTasks` 猜成 `fetchTaskList`（"更完整的命名风格"）。
+
+**Bug 2：store 和页面在同一 task layer 并行执行时，cache 快照里没有 store**
+
+cache 更新逻辑是在**整层完成后**统一写入，确保下一层看到完整结果。但如果 task generator AI 把 store 和消费 store 的页面分配到同一层（如都是 `service` 层），它们并行执行，页面生成时 cache 里根本没有 store 内容。
+
+---
+
+### 修复方案
+
+**1. `extractBehavioralContract` 新增两个捕获模式（`core/code-generator.ts`）**
+
+- `export const X = defineStore(` / `createStore(` / `createSlice(` — 使用**括号深度计数器**完整捕获整个 `defineStore(...)` 调用（含 state/actions/getters 定义体）
+- `return { ... }` — 使用**大括号深度计数器**完整捕获 return 对象（Pinia composition API 的公开 API 列表），并添加注释行 `// public API (return object):` 提示 AI 这是权威命名来源
+
+**2. `buildGeneratedFilesSection` 对 store/composable 文件传全文内容（`core/code-generator.ts`）**
+
+对路径匹配 `src/stores?/` 或 `src/composables?/` 的文件，不再调用 `extractBehavioralContract`，直接传入完整文件内容。Store 文件通常 50-200 行，context 成本可接受，且整个文件就是 API 合约。
+
+```typescript
+const isStoreOrComposable = /src[\\/](stores?|composables?)[\\/]/i.test(filePath);
+lines.push(isStoreOrComposable ? content : extractBehavioralContract(content));
+```
+
+**3. 强化 Rule 17（`prompts/codegen.prompt.ts`）**
+
+补充常见幻觉模式的负例：
+```
+fetchTasks → fetchTaskList ✗  fetchTaskData ✗  fetchTaskAll ✗
+fetchTasks → getTasks ✗       loadTasks ✗      queryTasks ✗
+createTask → createTasks ✗
+```
+以及 Pinia 专项说明："// public API (return object):" 区段展示的是 EVERY available action name。
+
+**4. 前端层级顺序规则（`prompts/tasks.prompt.ts`）**
+
+新增 CRITICAL 规则：在同一功能中，**store 必须在 `service` 层，消费该 store 的页面/组件必须在 `api` 层**。打破同层并行依赖，确保页面生成时 cache 已有 store 的完整内容。
+
+---
+
+### 效果
+
+修复后 cache 区段对 Pinia composition API store 的展示从：
+```
+export const useTaskStore = defineStore('task', () => {
+```
+变为：
+```
+export const useTaskStore = defineStore('task', () => {
+  const tasks = ref([])
+  ...
+// public API (return object):
+return {
+  tasks,
+  loading,
+  fetchTasks,
+  createTask,
+  updateTaskStatus,
+}
+```
+消费方 AI 能看到 `fetchTasks` 的精确名字，无需猜测。
+
+---
+
+## [0.20.0] 2026-03-25 — 一键 Mock 联调（`--serve` / `--restore`）
+
+### 功能：Mock Server 自动启动 + 前端 Proxy 自动 patch
+
+**背景**：代码生成完成后，前端要联调需要手动三步：① 启动 Mock 服务器、② 在前端框架配置 Proxy、③ 启动前端 Dev Server。每次都要做一遍，且 Proxy 修改要记得恢复。
+
+**方案**：新增 `--serve` / `--restore` 工作流，做到一条命令完成所有操作，联调结束一条命令还原。
+
+---
+
+#### `ai-spec mock --serve --frontend <path>`
+
+在后台启动 Mock 服务器，并自动 patch 前端 Proxy：
+
+- **Vite 项目**：生成 `vite.config.ai-spec-mock.ts`（使用 `mergeConfig` 动态合并基础配置，非破坏性），在 `package.json` 添加 `"dev:mock"` 脚本 → 执行 `npm run dev:mock`
+- **CRA 项目**：临时修改 `package.json` 的 `"proxy"` 字段（原值存入 lock 文件），执行 `npm start`
+- **Next.js / webpack**：自动 patch 不适用，打印手动配置说明
+
+所有操作记录在 `<frontend-dir>/.ai-spec-mock.lock.json`（含 Mock 服务器 PID），供 `--restore` 使用。
+
+#### `ai-spec mock --restore --frontend <path>`
+
+逐一撤销 lock 文件中记录的所有操作，并向 Mock 服务器进程发送 SIGTERM。
+
+#### `ai-spec create --serve`（工作区模式）
+
+多 Repo Pipeline 完成后，自动触发：
+1. 为后端 repo 生成 Mock Assets
+2. 后台启动 Mock 服务器
+3. 为前端 repo patch Proxy
+4. 打印前端 Dev Server 启动命令
+
+```bash
+ai-spec create "用户登录" --serve
+# → [W1..W4] 后端 + 前端 Pipeline
+# → ✔ Mock 服务器启动 (PID 12345) → http://localhost:3001
+# → ✔ 前端 Proxy patched (vite)
+# → Ready! cd ../frontend && npm run dev:mock
+```
+
+---
+
+#### 实现细节
+
+**新增文件/函数（`core/mock-server-generator.ts`）：**
+
+| 函数 | 说明 |
+|---|---|
+| `applyMockProxy(frontendDir, mockPort, endpoints?)` | 检测前端框架，执行对应 patch 操作，写入 lock 文件 |
+| `restoreMockProxy(frontendDir)` | 读取 lock 文件，逐一撤销，删除 lock 文件 |
+| `startMockServerBackground(serverJsPath, port)` | `spawn` 后台 detached 进程，返回 PID |
+| `saveMockServerPid(frontendDir, pid)` | 将 PID 写入已有 lock 文件 |
+
+**`generateViteMockConfigTs`** 生成的 `vite.config.ai-spec-mock.ts` 通过动态 `import()` 加载基础配置，支持 object / function 两种导出形式：
+
+```typescript
+export default defineConfig(async (env) => {
+  const mod = await import('./vite.config');
+  const baseConfigOrFn = mod.default;
+  const baseConfig = typeof baseConfigOrFn === 'function'
+    ? await baseConfigOrFn(env)
+    : baseConfigOrFn;
+  return mergeConfig(baseConfig ?? {}, { server: { proxy: { ... } } });
+});
+```
+
+---
+
+## [0.19.0] 2026-03-25 — 错误解析重写 · 行为契约完整提取 · Auto Gate 修复
+
+### 1. 错误解析重写（`core/error-feedback.ts`）
+
+**问题**：`parseErrors` 取输出最后 80 行。TypeScript / Jest 错误的结构是"具体 file:line 错误在前，摘要在后"，`slice(-80)` 恰好丢掉了最前面真正有文件路径的错误行，只留下摘要——AI 修的是摘要里说的东西，不是实际的错误位置。2 轮结束后 branch 仍有编译错误。
+
+**修复**：扫全文，**只保留含 `file:line` 模式的行**，过滤掉所有摘要行、noise 行。遇到 20 条即停（break），确保取到的是最早出现的 20 个可操作错误，message 截断从 300 → 400 字符避免切掉关键类型信息。
+
+```
+// Before: slice(-80) — 取末尾，丢掉最前面的具体报错
+src/services/auth.ts:15:3 - error TS2345...  ← 丢失
+...
+Found 12 errors.                              ← 被"修复"的是这里
+
+// After: scan full, filter by file:line — 取有路径的行
+src/services/auth.ts:15:3 - error TS2345...  ← ✔ 捕获
+src/controllers/user.ts:42:1 - error TS2304  ← ✔ 捕获
+```
+
+### 2. 行为契约完整提取（`core/code-generator.ts`）
+
+**问题**：`extractBehavioralContract` 对 `interface` / `type` 只捕获开头一行（`export interface UserService {`），body 里的所有方法签名、字段定义全部丢失。Task B 看到的是空壳，照样幻觉方法名和参数类型。
+
+**修复**：`interface` / `type X = {` / `class` / `enum` 使用大括号深度计数器，**完整捕获多行块**直到对应的 `}`。单行的 `export function` / `export const` 保持原有行为。
+
+```typescript
+// Before: 只有一行
+export interface UserService {
+
+// After: 完整 interface body
+export interface UserService {
+  getUser(id: string): Promise<User | null>;
+  createUser(dto: CreateUserDto): Promise<User>;
+  deleteUser(id: string): Promise<void>;
+}
+export type CreateUserDto = {
+  name: string;
+  email: string;
+  role: 'admin' | 'user';
+}
+```
+
+### 3. Auto 模式 Gate 修复（`cli/index.ts`）
+
+**问题**：`if (!opts.auto && !opts.skipAssessment)` 让 `minSpecScore` 在 `--auto` 模式下完全失效。团队配置了 `minSpecScore: 7`，CI 跑 `--auto` 照样通过，没有任何警告。
+
+**修复**：`--auto` 模式下，如果 `minSpecScore > 0`，**仍然运行 assessment 并强制执行 Gate**（只跳过交互式展示 scorecard）。`--force` 仍可绕过。
+
+```
+# 配置了 minSpecScore: 7 的项目
+ai-spec create --auto  →  运行 assessment，score=5 → exit(1)，打印原因
+ai-spec create --auto --force  →  运行 assessment，score=5 → 黄色警告，继续
+ai-spec create --auto（未配置 minSpecScore）  →  跳过 assessment，行为不变
+```
+
+---
+
+## [0.18.0] 2026-03-25 — ai-spec learn · 行为契约注入 · Approval Gate 硬门槛
+
+### 1. `ai-spec learn` — 零摩擦知识注入
+
+**背景**：宪法 §9 只收录通过 `ai-spec review` 触发的教训，依赖工具覆盖率（100% 使用 ai-spec review 在实际团队几乎不可能）。混用 Cursor / Copilot 的决策和踩坑永远不会回流。
+
+**新增命令**：`ai-spec learn "<lesson>"`
+
+```bash
+ai-spec learn "所有新接口必须走 validateRequest 中间件，上次某 PR 遗漏导致生产 bug"
+ai-spec learn  # 无参数时进入交互式输入
+```
+
+- 直接 append 到 `.ai-spec-constitution.md` §9，无需 AI 调用，无需完整 review 流程
+- 自动去重（检查前 60 字符是否已存在相似条目）
+- §9 超过 8 条时提示 `--consolidate`
+
+**新增函数**（`core/knowledge-memory.ts`）：`appendDirectLesson(projectRoot, lessonText)`
+
+### 2. Generated File Cache — 行为契约注入
+
+**背景**：0.17.0 解决了函数名幻觉（名称层）。但 Task A 的 service 校验了某字段，Task B 的 API 层完全不知道这个校验存在，命名正确但逻辑前后矛盾，lint/test 不一定能抓住。
+
+**升级**（`core/code-generator.ts`）：将 `extractExportSignatures()` 替换为 `extractBehavioralContract()`：
+
+```typescript
+// Before: 只提取 export 行（名称层）
+export function createTask(dto: CreateTaskDto): Promise<Task>
+
+// After: 同时提取 throw/validation 模式（契约层）
+export function createTask(dto: CreateTaskDto): Promise<Task>
+export function updateTask(id: string, dto: UpdateTaskDto): Promise<Task>
+
+// Error contracts (throws / validation):
+  // throw new AppError('TASK_TITLE_REQUIRED', 400)
+  // throw new AppError('PROJECT_NOT_FOUND', 404)
+```
+
+后续 task 注入的 context 不仅知道"叫什么"，还知道"校验什么、会抛什么错"，有效防止跨 task 的行为契约幻觉。
+
+### 3. Approval Gate 可配置硬门槛
+
+**背景**：spec-assessor 是建议性的、不阻断的——赶时间的工程师直接 Proceed，错误检测时机太晚。
+
+**新增配置项**（`.ai-spec.json`）：`minSpecScore`（默认 0 = 禁用）
+
+```bash
+ai-spec config --min-spec-score 7  # 设置最低分 7/10
+```
+
+当 `overallScore < minSpecScore` 时：
+- 打印红色错误信息，列出失败原因和当前阈值
+- `process.exit(1)` 阻断流程
+- `--force` flag 可强制绕过（同时输出黄色警告）
+
+**设计原则**：默认关闭，不破坏现有用户工作流；团队可按需在 `.ai-spec.json` 开启，阈值完全可配置。
+
+---
+
+## [0.17.0] 2026-03-24 — 宪法全文注入 · Export 精准缓存 · 宪法长度警告
+
+### 1. 宪法全文注入（移除硬截断）
+
+**问题**：宪法在所有 prompt 中存在硬截断（`codegen`/`task-generator`/`spec-assessor`/`update` 各处分别为 1500–2000 字符），§9 最新教训恰好位于宪法末尾，最容易被截掉——工具越用越长的宪法反而越来越被忽视。
+
+**修复**（涉及 6 处）：
+- `core/code-generator.ts` — 代码生成 prompt 中的宪法注入
+- `cli/index.ts` — update 命令中的宪法注入
+- `prompts/update.prompt.ts` — update prompt 构建函数
+- `core/task-generator.ts` — task 生成 prompt
+- `core/spec-assessor.ts` — Spec 质量评估 prompt
+- `core/context-loader.ts` — 项目文件预览从 800 → 2000 字符
+
+现代模型（Claude/Gemini/Qwen3）上下文窗口充足，宪法通常 3000–8000 字符，全文注入不会造成负担，但能确保 §9 始终被 AI 读到。
+
+### 2. Generated File Cache — Export 精准提取
+
+**问题**：跨 task 一致性保障依赖 `generatedFileCache`，原实现截取每个缓存文件的前 800 字符注入后续 task prompt。对于超过 30 行的 service/api 文件，大量 export 函数名落在 800 字符之外，跨 task 函数名幻觉问题依然存在于大文件场景。
+
+**修复**（`core/code-generator.ts`）：新增 `extractExportSignatures()` 函数，从文件全文中提取**所有以 `export` 开头的声明行**，注入后续 task prompt。无论文件长度，所有导出名称完整可见；对无显式 export 的文件（CommonJS）回退到前 3000 字符。
+
+```typescript
+// Before: 取前 800 字符，大文件的 export 被截掉
+content.slice(0, 800)
+
+// After: 提取所有 export 声明行，精准且不浪费 token
+export function getUserList(...): Promise<...>
+export function createUser(...): Promise<...>
+export const updateUser = ...
+// ...全部导出，不含实现细节
+```
+
+### 3. 宪法长度警告
+
+**新增**：当宪法超过 **6,000 字符**时，`create` / `update` / workspace 各命令加载上下文后自动输出提示：
+
+```
+⚠ Constitution is long (8,432 chars). Consider running: ai-spec init --consolidate
+```
+
+设计原则：不阻断流程，纯提示性；帮助用户在宪法真正影响 AI 注意力之前主动整合，而不是等到效果已经变差才发现。
+
+---
+
 ## [0.16.0] 2026-03-24 — Spec 质量预评估 · 分层代码审查 · TDD 模式
 
 ### 1. Spec 质量预评估（`core/spec-assessor.ts`, `prompts/spec-assess.prompt.ts`）