@alenfitz/spec-copilot 1.2.1 → 1.3.0

package/commands/spec:apply.md

@@ -21,13 +21,15 @@ description: 执行编码（逐 task 推进，每个 task 停顿等确认）
 每个 task 的执行流程：
 1. 编码实现
 2. 验证（编译/构建/运行）
-3. 展示验证证据（截取关键输出）
+3. **展示验证证据**（见下方验证证据要求）
 4. 立即 `git commit`
 5. 更新 tasks.md 该 task 状态为 ✅
 6. **🛑 停止。输出以下提示后结束回复：**
    ```
    ✅ T<n> 完成（<简述>）
    验证：<编译/测试结果>
+   功能验证：<curl 输出 / 页面行为描述>
+   已实现文件：<实际新增/修改的文件列表>
    Commit: <hash> <message>
    
    → 下一步：T<n+1>: <描述>
@@ -35,8 +37,19 @@ description: 执行编码（逐 task 推进，每个 task 停顿等确认）
    ```
 7. **等用户回复后才开始下一个 task**
 
-- 用户反馈后修改完 → 再次停下确认，不得自动进入下一 task
-- Spec-Code 偏差当场记录到 log.md（log.md 已在 /spec:propose 时从 `spec_copilot/changes/templates/log.md` 模板创建，直接编辑已有文件，不得重建）
+### 验证证据要求（铁律）
+
+> **编译通过 ≠ 功能完成。** 每个 task 必须提供与 tasks.md 验收标准匹配的证据。
+
+- **后端 task**：必须执行 tasks.md 中定义的验证命令（curl），展示实际返回的 JSON/状态码。如果 curl 返回异常，该 task 不得标记为 ✅
+- **前端 task**：必须说明页面可访问路径、核心交互是否可操作（表单有绑定、按钮有 handler、提交有反馈）。如果按钮的 handler 是空的 TODO，该 task 不得标记为 ✅
+- **文件清单对照**：完成时对比 tasks.md 计划的文件列表和实际修改的文件列表。遗漏的文件必须说明原因
+
+### Scope 偏差处理
+
+- 如果执行中发现某个计划文件无法实现或需要跳过，**立即告知用户并等待确认**，不得静默裁切
+- 偏差发生时当场记录到 log.md `Spec-Code 偏差记录`（log.md 已在 /spec:propose 时从模板创建，直接编辑已有文件，不得重建）
+- 禁止以"文件数太多"、"不属于当前 task 范围"为由裁减 spec 中已定义的功能
 
 ## 全部 task 完成后
 

package/commands/spec:review.md

@@ -11,13 +11,23 @@ description: 两阶段审查（Spec 合规 + 代码质量）
 运行 `npx @alenfitz/spec-copilot gate <变更名> review`（跨平台门禁检查）
 
 **阶段一 Spec Compliance**（附录 A）：
-逐条验证 spec 功能点是否落地。PASS 后才进入阶段二。
+
+> 🔒 **独立验证铁律**：禁止凭 apply 阶段的记忆得出结论。每个功能点/业务规则必须当场执行 `grep -rn` 或 `Read`，输出 `文件:行号` 作为证据。无证据的 ✅ 视为无效。
+
+执行步骤：
+1. 读取 spec.md §3 功能点列表，逐条执行 `grep -rn` 定位后端和前端实现
+2. 读取 spec.md §4 业务规则列表，逐条执行 `grep -rn` 定位校验逻辑
+3. 对有实现的功能点，`Read` 代码段确认非空实现（非 TODO/占位/空方法体）
+4. 统计覆盖率：`已实现/总功能点`。**低于 80% 直接判定不合规**
+5. 检查 log.md `Spec-Code 偏差记录` 是否为空 — 如果 apply 阶段声称无偏差但 review 发现缺失实现，标记为 Critical 不一致
+
+PASS 后才进入阶段二。
 
 **阶段二 Code Quality**（附录 B）：
 按 Critical / Important / Minor 三级审查。
 加载 `spec_copilot/stack-adapters/<栈>.md` §10 栈相关检查项。
 
-完成后更新 spec.md §12 审查结论。
+完成后更新 spec.md §12 审查结论（必须包含覆盖率数字）。
 
 ## 结束后
 

package/commands/spec:smoke.md

@@ -9,8 +9,12 @@ description: 冒烟验证（编译 + 核心接口测试）
 步骤：
 1. 编译/构建后端（命令见 `spec_copilot/rules/project-context.md` §8）
 2. 编译/构建前端（如有）
-3. 对 spec 中每个核心接口执行 curl 验证
-4. 如有前端页面，确认可渲染
+3. 读取 spec.md §3 功能点列表和 §6 API 契约
+4. 对 spec 中**每个 API 接口**执行 curl 验证（不仅限"核心接口"），记录状态码和响应摘要
+5. 如有前端页面，逐页面确认可渲染、核心交互可操作
+6. 统计接口冒烟覆盖率：`通过接口数/总接口数`
+
+> ⚠️ 仅验证"核心接口"是不够的。Spec 定义的每个 API 都必须 curl 验证可达。不可达的接口记录为失败项。
 
 ## 结束后
 

package/framework/AGENTS.md.template

@@ -29,6 +29,11 @@
 - **阶段跳转等确认**：每个阶段（propose/apply/smoke/review/fix/test/archive）完成后停下来，告知下一步是什么，等用户显式触发。
 - **唯一例外**：/spec:flow 全自动模式下，阶段间自动推进（但仅限 🟢/🟡 需求）。
 
+### Scope 偏差管控（铁律）
+- **禁止静默裁切**：如果某个 spec 功能点或 tasks.md 中的文件在执行时被跳过、简化或降级实现，必须**立即告知用户并等待确认**，然后记录到 log.md `Spec-Code 偏差记录`
+- **前后端均衡**：如果 spec 含前后端，tasks.md 中前端和后端 task 的数量比不得超过 1:3。前端不得仅做"骨架级"实现——表单必须有数据绑定、按钮必须有 handler、提交必须有反馈
+- **偏差即记录**：任何与 spec/tasks.md 的偏差（裁切功能、简化实现、跳过文件）都必须在发生时记录到 log.md，不得留空
+
 ## 启动检查（每次会话开始时执行）
 
 **执行 `/spec:init`** — 该命令自动完成规范加载、项目扫描、栈适配、变更检测、状态报告。这是每次会话的唯一起点。
@@ -129,24 +134,38 @@ npx @alenfitz/spec-copilot gate <变更名> <phase>
 
 核心理念：**不信报告，只信代码** — reviewer 必须读实际代码独立验证。
 
+### 🔒 独立验证铁律
+
+> **禁止凭记忆或 apply 阶段的上下文得出结论。每一条验证结果必须附带当场执行的 Grep/Read 证据。**
+> 没有 `文件:行号` 引用的验证结论视为无效。
+
+1. **逐功能点 Grep**：对 spec 每个功能点编号（如 F01、F02），必须执行 `grep -rn` 或 `Read` 在代码中定位实现，输出匹配的文件路径和行号
+2. **逐规则 Grep**：对 spec 每条业务规则编号（如 V01、V02），必须在 Service/Controller 层搜索对应的条件判断，输出匹配证据
+3. **前后端均验证**：后端有对应 API ≠ 功能已实现。必须同时验证前端是否有调用该 API 的页面/组件，且交互完整（按钮可点击、表单有绑定、提交有反馈）
+4. **空实现检测**：Grep 检查是否存在 `TODO`、`/* */` 空方法体、`Promise.resolve()` 占位。发现即标记为 ❌ 未实现
+5. **覆盖率统计**：最终输出 `已实现/总功能点` 比率。**低于 80% 直接判定不合规，不得通过**
+
 ### 审查维度
 1. **缺失实现**：spec 要求了但代码没做的
 2. **多余实现**：spec 没要求但代码多做了的（YAGNI 违规）
 3. **理解偏差**：做了但做错了方向的
 4. **业务规则落地**：spec 中的规则是否全部体现在代码中
 5. **数据变更准确性**：spec 中的表/字段变更是否准确落地
+6. **前后端一致性**：后端接口是否有前端调用方，前端交互是否完整闭环
 
 ### 具体审查清单（每次 review 逐项执行）
 
 **功能点验证（对应 spec §3）**
-- [ ] 读取 spec.md §3 功能点列表
-- [ ] 对每个功能点，Grep/Read 对应的代码路径，确认实现存在
+- [ ] 读取 spec.md §3 功能点列表，提取所有功能点编号
+- [ ] 对每个功能点，执行 `grep -rn "<关键字>"` 定位后端实现，记录 `文件:行号`
+- [ ] 对每个功能点，执行 `grep -rn "<关键字>"` 定位前端实现（组件/页面/API 调用），记录 `文件:行号`
+- [ ] 对有实现的功能点，`Read` 对应代码段，确认非空实现（非 TODO/占位）
 - [ ] 检查是否有 spec 未提及但代码中多出的接口（YAGNI 违规）
 
 **业务规则验证（对应 spec §4）**
-- [ ] 读取 spec.md §4 业务规则列表
-- [ ] 对每条规则，在 Service 层 Grep 对应的条件判断逻辑
-- [ ] 验证规则的边界条件是否在代码中体现
+- [ ] 读取 spec.md §4 业务规则列表，提取所有规则编号
+- [ ] 对每条规则，在 Service 层 `grep -rn` 对应的条件判断逻辑，记录 `文件:行号`
+- [ ] 验证规则的边界条件是否在代码中体现（Read 对应代码段确认）
 
 **数据变更验证（对应 spec §5）**
 - [ ] 读取 spec.md §5 数据变更
@@ -158,12 +177,19 @@ npx @alenfitz/spec-copilot gate <变更名> <phase>
 
 ### 输出格式
 ```
-#### 功能点逐条验证
-- ✅ 功能 1：已实现，见 `XxxService.java:L42`
-- ❌ 功能 2：未实现（缺少 XX 逻辑）
-- ⚠️ 功能 3：实现方式与 spec 描述有偏差
-
-#### 结论：✅ Spec 合规 / ❌ 不合规（附具体问题）
+#### 功能点逐条验证（N/M 通过，覆盖率 XX%）
+- ✅ F01：已实现，后端 `XxxService.java:L42`，前端 `XxxPage.vue:L15`
+- ❌ F02：后端有接口但前端未调用（缺少页面入口）
+- ❌ F03：未实现（grep 无结果）
+- ⚠️ F04：实现方式与 spec 描述有偏差（spec 要求 X，代码实际做了 Y）
+- ❌ F05：空实现（`XxxService.java:L88` 方法体为 TODO）
+
+#### 业务规则逐条验证（N/M 通过）
+- ✅ V01：已实现，见 `XxxService.java:L120` if 判断
+- ❌ V02：未找到对应校验逻辑
+
+#### 覆盖率：功能点 X/Y (Z%)，业务规则 X/Y (Z%)
+#### 结论：✅ Spec 合规（覆盖率 ≥ 80%） / ❌ 不合规（覆盖率 < 80% 或存在 Critical 偏差）
 ```
 
 ---

package/framework/VERSION

@@ -1 +1 @@
-1.6.0
+1.7.0

package/framework/changes/templates/tasks.md

@@ -30,6 +30,8 @@
   ```
 - **Git commit**：`git commit -m "[变更名] T1: <中文简述>"`
 - 状态：待完成
+- **实际验证结果**：（apply 完成时填写：curl 输出摘要 / 页面行为确认）
+- **实际文件清单**：（apply 完成时填写：与计划文件对比，标注新增/遗漏）
 
 ---
 
@@ -38,11 +40,21 @@
 
 ---
 
+## Scope 偏差跟踪
+> ⚠️ 执行中发生的任何 scope 偏差必须即时记录于此，禁止留空后补
+
+| Task | 偏差内容 | 原因 | 用户确认 |
+|------|---------|------|---------|
+| （无偏差则写"无"） | | | |
+
 ## 变更摘要
 > ⚠️ /spec:apply 全部完成后必须填写，不填不允许进入 /spec:review
 
 - **总文件数**：X 个新增，Y 个修改
+- **计划文件 vs 实际文件对比**：（列出计划但未实现的文件及原因）
 - **Spec-Plan 偏差记录**：（无偏差 / 列出偏差点及原因）
+- **功能点覆盖自查**：已实现 X/Y 功能点（列出未实现的功能点编号）
+- **前后端工作量比**：后端 X 文件，前端 Y 文件
 - **魔法值是否已提取为常量**：是 / 否（列出遗留项）
 - **注释覆盖情况**：Entity/Service/Controller 注释是否符合 coding-style.md §1
 - **遗留问题**：（下一步需处理的已知缺陷或 TODO）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alenfitz/spec-copilot",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Spec-Driven Development Framework — one package, six AI coding tools (opencode, Claude Code, Cursor, Windsurf, GitHub Copilot, Cline)",
   "keywords": [
     "ai-coding",
@@ -37,4 +37,4 @@
   "scripts": {
     "test": "node bin/cli.js --help"
   }
-}
+}