sillyspec 3.17.15 → 3.18.1

package/src/stages/plan.js

@@ -10,6 +10,60 @@ export const definition = {
 
 // 固定前缀步骤
 export const fixedPrefix = [
+  {
+    name: '复杂度分类',
+    prompt: `在生成计划之前，先判定本次需求的复杂度等级（plan_level）。
+
+### 操作
+1. 读取 tasks.md 和 design.md，了解需求范围
+2. 按「分级规则」判定 plan_level
+
+### 分级规则
+判定 plan_level 为 none 时，需**同时满足**以下所有条件：
+- 涉及文件 ≤ 2 个
+- 不跨模块（改动集中在单个模块内）
+- 无 schema / DB / manifest / local.yaml 变更
+- 无状态机 / workflow 状态流转变更
+- 无 source_root / spec_root / runtime_root 路径隔离规则变更
+- 无 validator / postcheck / agent 调度行为变更
+- 需求明确，无设计歧义
+
+判定为 light（满足任一即升为 light）：
+- 涉及 3-5 个文件
+- 涉及 prompt 行为变更
+- 涉及 validator / postcheck 逻辑
+- 涉及路径规则变更（但范围可控）
+- 涉及 schema/DB/状态机变更，但影响面可控
+- 需要明确验收标准来防止范围漂移
+
+判定为 full（满足任一即升为 full）：
+- 预计 8 个以上 task
+- 跨 3 个以上模块
+- 涉及 CLI + 平台 + DB 联动
+- 涉及 agent 调度 / worktree / isolation 逻辑
+- 涉及复杂状态恢复（checkpoint / resume）
+- 需要并行 sub-agent 执行
+- 需要人工审查设计方向
+- 涉及 worktree / baseline / sandbox 等基础设施
+
+### 输出格式
+在输出开头，以如下格式输出分类结果：
+
+\`\`\`
+plan_level: none | light | full
+reason: <一句话说明判定理由>
+estimated_files: <N>
+cross_module: true | false
+has_schema_change: true | false
+has_state_machine_change: true | false
+needs_parallel_execution: true | false
+needs_human_review: true | false
+\`\`\`
+
+分类完成后，继续进入下一步。`,
+    outputHint: '复杂度分类结果',
+    optional: false
+  },
   {
     name: '状态检查',
     prompt: `检查当前状态，确认可以执行 plan。
@@ -30,22 +84,25 @@ export const fixedPrefix = [
 ### 操作
 1. 读取 CODEBASE-OVERVIEW.md + 各子项目上下文
 2. 读取 proposal.md、design.md、requirements.md、tasks.md
-3. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
-4. 读取 local.yaml 获取构建/测试命令
+3. 如果存在 decisions.md，必须读取并提取所有当前版本 D-xxx@vN 决策 ID
+   - 如果发现 priority=P0/P1 且 status=unresolved/blocking 的决策，停止生成计划，要求先回到 brainstorm 的 Design Grill 修正
+   - 如果发现 superseded 决策，只引用最新版本，不引用旧版本
+4. 读取 CONVENTIONS.md、ARCHITECTURE.md、STACK.md
+5. 读取 local.yaml 获取构建/测试命令
 
 ### 模块文档加载
-5. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-6. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
-7. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
-8. 将模块文档作为制定计划的上下文，确保计划符合模块当前设计
-9. **利用模块依赖关系辅助分析**：
+6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+7. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
+8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+9. 将模块文档作为制定计划的上下文，确保计划符合模块当前设计
+10. **利用模块依赖关系辅助分析**：
    - 用 depends_on 判断哪些模块会被间接影响
    - 用 used_by 判断变更会不会影响下游模块
    - 将依赖关系纳入 Wave 分组决策（依赖同一模块的任务尽量同 Wave）
    - 如果变更涉及多个有依赖关系的模块，在 plan.md 的任务总表中标注模块依赖
 
 ### 输出
-已加载的文件清单（含模块文档 + 模块依赖关系摘要）`,
+已加载的文件清单（含 decisions.md 当前版本/未决项状态、模块文档 + 模块依赖关系摘要）`,
     outputHint: '文件清单',
     optional: false
   },
@@ -62,11 +119,94 @@ export const fixedPrefix = [
     optional: false
   },
   {
-    name: '展开任务并分组',
-    prompt: `把 tasks.md 每个 checkbox 展开为任务描述，按 Wave 分组，产出 plan.md 总览。
+    name: '按复杂度生成分级计划',
+    prompt: `根据「复杂度分类」步骤的 plan_level 结果，按对应级别生成计划。
+
+### 操作
+1. 读取上一步输出的 plan_level 分类结果
+2. 读取 tasks.md 和 design.md 了解需求范围
+3. 按 plan_level 选择对应模板输出
+
+---
 
-### plan.md 格式（PM 视角 + 机器可解析）
+#### plan_level = none
+生成最小 plan.md（占位文件，保持流程兼容），不生成完整蓝图。格式：
 \`\`\`markdown
+---
+plan_level: none
+---
+
+# 计划跳过
+
+## 原因
+<一句话说明判定理由>
+
+## 建议直接 execute
+直接进入 execute 阶段完成下列最小任务。
+
+## Tasks
+- [ ] task-01: 按用户需求完成小范围明确修改
+
+## 验收
+- 修改范围符合用户需求
+- 不引入额外无关变更
+- 必要测试或检查通过
+\`\`\`
+**注意：** 所有 plan_level 都必须包含 \`- [ ] task-XX:\` 格式的 checkbox 任务，execute 阶段依赖此格式解析任务。
+
+---
+
+#### plan_level = light
+生成轻量 plan.md，保存到变更目录。只包含以下四部分：
+
+\`\`\`markdown
+---
+plan_level: light
+---
+
+# 轻量计划：<需求简述>
+
+## 来源
+直接引用 brainstorm 结论或用户原始需求，不重新扩写。
+
+## 范围
+- 涉及的文件/模块清单
+
+## Tasks
+- [ ] task-01: ...（覆盖：FR-01, D-001@v1）
+- [ ] task-02: ...
+- [ ] task-03: ...
+
+## 验收
+- 具体可验证的验收条目
+
+## 覆盖矩阵（如存在 decisions.md）
+| ID | 覆盖任务 | 验收证据 |
+|---|---|---|
+| D-001@v1 | task-01 | AC-01 |
+\`\`\`
+
+light 计划的约束：
+- **禁止**生成 Mermaid 图
+- **禁止**估时
+- **禁止**泛泛风险 分析（如"需要充分测试"）
+- **禁止**放实现细节（函数签名、代码示例）
+- 来源/目标直接引用已有文档，不重新生成
+- 如果存在 decisions.md，所有当前版本 D-xxx@vN 必须在 Tasks 或覆盖矩阵中出现
+- 如果存在 P0/P1 unresolved blocker，不生成 plan.md
+- 任务列表控制在 10 条以内
+- **任务必须使用 checkbox 格式**（\`- [ ] task-XX:\`），不要用纯编号列表（\`1. 2.\`），execute 阶段依赖此格式解析任务
+
+---
+
+#### plan_level = full
+生成完整 plan.md，保存到变更目录。格式如下：
+
+\`\`\`markdown
+---
+plan_level: full
+---
+
 # 实现计划
 
 ## Spike 前置验证（如需要）
@@ -77,25 +217,18 @@ export const fixedPrefix = [
 > 技术不确定性高时才需要 Spike。无不确定性则跳过此节。
 
 ## Wave 1（并行，无依赖）
-- [ ] task-01: 添加用户创建接口
-- [ ] task-02: 添加角色创建接口
+- [ ] task-01: 添加用户创建接口（覆盖：FR-01, D-001@v1）
+- [ ] task-02: 添加角色创建接口（覆盖：FR-02）
 
 ## Wave 2（依赖 Wave 1）
 - [ ] task-03: 用户创建接口联调
 
 ## 任务总表
-| 编号 | 任务 | Wave | 优先级 | 估时 | 依赖 | 说明 |
+| 编号 | 任务 | Wave | 优先级 | 依赖 | 覆盖 FR/D | 说明 |
 |---|---|---|---|---|---|---|
-| task-01 | 添加用户创建接口 | W1 | P0 | 4h | — | ... |
-| task-02 | 添加角色创建接口 | W1 | P0 | 3h | — | ... |
-| task-03 | 用户创建接口联调 | W2 | P0 | 4h | task-01,02 | ... |
-
-## 依赖关系图
-\`\`\`mermaid
-graph LR
-  task-01 --> task-03
-  task-02 --> task-03
-\`\`\`
+| task-01 | 添加用户创建接口 | W1 | P0 | — | FR-01, D-001@v1 | ... |
+| task-02 | 添加角色创建接口 | W1 | P0 | — | FR-02 | ... |
+| task-03 | 用户创建接口联调 | W2 | P0 | task-01,02 | FR-03 | ... |
 
 ## 关键路径
 task-01 → task-03（最长路径，决定最短交付周期）
@@ -103,66 +236,102 @@ task-01 → task-03（最长路径，决定最短交付周期）
 ## 全局验收标准
 - [ ] 所有单元测试通过
 - [ ] （brownfield）未配置新功能时行为不变
+
+## 覆盖矩阵（如存在 decisions.md）
+| ID | 覆盖任务 | 验收证据 |
+|---|---|---|
+| D-001@v1 | task-01 | AC-01 |
 \`\`\`
 
-### 关键规则
-- plan.md 包含：Wave 分组 + 任务总表 + 依赖图 + 关键路径 + 全局验收标准，**不放实现细节**
+full 计划的约束：
+- **禁止**估时（任务总表不含估时列）
+- **禁止**泛泛风险分析（"需要充分测试"类废话转为具体验收条目）
+- Mermaid 依赖关系图**仅当依赖关系非平凡时生成**（线性依赖或全并行时不生成）
+- **Wave 下的 checkbox 行必须保留**（execute 阶段解析依赖 \`- [ ] task-XX:\` 格式）
+- plan.md 包含 Wave 分组 + 任务总表 + 关键路径 + 全局验收标准，**不放实现细节**
+- 如果存在 decisions.md，plan.md 必须包含当前版本 D-xxx@vN/FR-xxx 覆盖矩阵
+- 如果存在 P0/P1 unresolved blocker，不生成 plan.md，输出阻塞清单
 - 实现细节写到后续的 tasks/task-NN.md 中
 - 每个任务编号格式：task-01、task-02 ...
-- **Wave 下的 checkbox 行必须保留**（execute 阶段解析依赖 \`- [ ] task-XX:\` 格式）
 - 任务总表的优先级：P0（必须）/ P1（重要）/ P2（可选）
-- 估时参考：单个 task ≤ 8h，超过则拆分
+- 总任务数控制在 15 个以内
 
-### Spike 前置验证
+### Spike 前置验证（仅 full）
 当存在技术不确定性时，在 Wave 之前设计 Spike：
 - 涉及新技术栈/未经验证的集成 → 需要 Spike
 - 涉及安全隔离/性能瓶颈 → 需要 Spike
 - 纯业务逻辑/确定的技术方案 → 不需要 Spike
 - 每个 Spike 定义：验证内容 + 通过标准 + 不通过后果
 
-### 批量模式指引
+### 批量模式指引（仅 full）
 如果 design.md 或需求中包含批量特征（关键词：批量/模板/引擎/N个相似），按以下原则规划：
-❌ 不要列出每个实例作为独立任务
-❌ 不要在文档中嵌入数据
-✅ 设计通用架构，Wave 1 聚焦架构
-✅ 数据转换用脚本完成，单独一个 Wave
-✅ 总任务数控制在 10 个以内
+- ❌ 不要列出每个实例作为独立任务
+- ❌ 不要在文档中嵌入数据
+- ✅ 设计通用架构，Wave 1 聚焦架构
+- ✅ 数据转换用脚本完成，单独一个 Wave
+- ✅ 总任务数控制在 10 个以内
 
-### 操作
+---
+
+### 通用操作（所有级别）
 1. 读取 tasks.md 获取任务列表
 2. 读取 design.md 获取文件变更清单
-3. 逐个展开为任务描述
-4. 分析依赖关系，按 Wave 分组
-5. 生成任务总表（含优先级、估时、依赖）
-6. 生成 Mermaid 依赖关系图
-7. 标注关键路径
-8. 评估是否需要 Spike 前置验证
-9. 保存到变更目录下的 plan.md（路径格式：\`.sillyspec/changes/<change-name>/plan.md\`，其中 <change-name> 是变更目录名，直接使用，不加子目录。正确路径示例：\`.sillyspec/changes/2026-05-28-agent-log-streaming/plan.md\`）
+3. 读取上一步的 plan_level 分类结果
+4. 按对应级别模板生成内容
+5. 保存到变更目录下的 plan.md（路径格式：\`.sillyspec/changes/<change-name>/plan.md\`，其中 <change-name> 是变更目录名，直接使用，不加子目录。正确路径示例：\`.sillyspec/changes/2026-05-28-agent-log-streaming/plan.md\`）
+**plan_level 为 none 时生成最小 plan.md（占位），不生成完整蓝图。**
 
 ### 输出
-plan.md 总览内容`,
-    outputHint: 'plan.md 总览',
+plan_level + 计划内容（none 级别输出建议操作）`,
+    outputHint: '计划内容',
     optional: false
   },
   {
     name: '自检总览',
-    prompt: `自检 plan.md 总览质量。
+    prompt: `根据 plan_level 检查对应的计划质量。
 
 ### 操作
-检查以下各项：
+读取上一步的 plan_level 分类结果，按级别执行对应的自检：
+
+#### plan_level = none
+- [ ] plan.md 文件存在且包含 plan_level: none
+- [ ] 给出了可操作的修改建议（2-5 条）
+- [ ] 不含 Wave、Mermaid、估时、任务总表、依赖关系等完整蓝图内容
+- [ ] 建议了直接 execute
+- [ ] 包含至少一个 \`- [ ] task-XX:\` 格式的 checkbox 任务（execute 解析依赖此格式）
+
+#### plan_level = light
+- [ ] 输出明确标注 plan_level: light
+- [ ] 有来源、范围、任务列表、验收标准四个部分
+- [ ] 来源直接引用已有文档，未重新扩写
+- [ ] 任务列表清晰且无实现细节
+- [ ] 任务使用 checkbox 格式（\`- [ ] task-XX:\`），不是纯编号列表
+- [ ] 验收标准具体可验证（非笼统表述）
+- [ ] 如果存在 decisions.md，所有当前版本 D-xxx@vN 在 plan.md 中可追踪
+- [ ] 不存在 P0/P1 unresolved blocker
+- [ ] 没有 Mermaid 图、估时、风险分析
+- [ ] 没有函数签名、代码示例等实现细节
+- [ ] plan.md 与 design.md 的文件变更清单一致
+- [ ] 包含至少一个 \`- [ ] task-XX:\` 格式的 checkbox 任务（execute 解析依赖此格式）
+
+#### plan_level = full
 - [ ] 每个 task 有编号（task-01、task-02 ...）
 - [ ] 每个 task 在 Wave 下有 checkbox（\`- [ ] task-XX:\` 格式，execute 解析依赖此格式）
 - [ ] 已标注 Wave 分组和依赖关系
-- [ ] 有任务总表（含优先级、估时、依赖列）
-- [ ] 有 Mermaid 依赖关系图
+- [ ] 有任务总表（含优先级、依赖列，**无估时列**）
 - [ ] 有关键路径标注
 - [ ] 有全局验收标准
+- [ ] 如果存在 decisions.md，任务总表或覆盖矩阵覆盖全部当前版本 D-xxx@vN
+- [ ] 不存在 P0/P1 unresolved blocker
 - [ ] （brownfield）全局验收包含兼容性条款
 - [ ] 没有实现细节（接口定义、代码示例等不应该在 plan.md 里）
 - [ ] plan.md 与 design.md 的文件变更清单一致
+- [ ] 如果有 Mermaid 图，依赖关系确实非平凡（非线性/非全并行）
+- [ ] 没有泛泛风险分析（如"需要充分测试"）
 
 ### 输出
-自检通过/不通过`,
+自检通过/不通过（附 plan_level）`,
+    outputHint: '自检结果',
     outputHint: '自检结果',
     optional: false
   }
@@ -265,6 +434,8 @@ priority: P0
 estimated_hours: N
 depends_on: []
 blocks: []
+requirement_ids: [FR-01]
+decision_ids: [D-001@v1]
 allowed_paths:
   - 允许修改的路径范围
 ---
@@ -274,6 +445,10 @@ allowed_paths:
 ## 修改文件（必填）
 - 精确到文件路径，列出所有需要新增或修改的文件
 
+## 覆盖来源
+- Requirements: FR-xx（来自 requirements.md）
+- Decisions: D-xxx@vN（如存在 decisions.md）
+
 ## 实现要求
 1. 具体做什么，写清楚
 2. ...
@@ -315,6 +490,8 @@ allowed_paths:
 - \`estimated_hours\`: 预估工时，单个 task ≤ 8h
 - \`depends_on\`: 依赖的前序 task 编号列表
 - \`blocks\`: 被本 task 阻塞的后续 task 编号列表
+- \`requirement_ids\`: 本任务覆盖的 FR-xxx 列表
+- \`decision_ids\`: 本任务覆盖的当前版本 D-xxx@vN 列表；无 decisions.md 时可为空数组
 - \`allowed_paths\`: AI executor 可以修改的文件路径范围（安全边界）
 
 ### 关键规则
@@ -323,6 +500,7 @@ allowed_paths:
 - 接口定义写到"搬砖工照着做"的程度
 - 边界处理至少覆盖 5 条规则
 - 验收标准用表格格式，每条可点击验证，禁止"功能可演示"类笼统表述
+- 如果存在 decisions.md，不允许丢失当前版本 D-xxx@vN；无法覆盖的 D-xxx@vN 必须写入非目标或剩余风险
 - 写完后保存到文件
 
 ### 操作
@@ -370,6 +548,8 @@ priority: P0/P1/P2
 estimated_hours: N
 depends_on: [task-XX]
 blocks: [task-XX]
+requirement_ids: [FR-XX]
+decision_ids: [D-XXX@vN]
 allowed_paths:
   - ...
 ---
@@ -379,6 +559,10 @@ allowed_paths:
 ## 修改文件（必填）
 - 精确到文件路径
 
+## 覆盖来源
+- Requirements: FR-xx
+- Decisions: D-xxx@vN（如存在）
+
 ## 实现要求
 1. 具体做什么
 
@@ -412,6 +596,7 @@ allowed_paths:
 - 接口定义写到"搬砖工照着做"的程度
 - 边界处理至少 5 条
 - 验收标准用表格，禁止笼统表述
+- 如果存在 decisions.md，不允许丢失当前版本 D-xxx@vN；无法覆盖的 D-xxx@vN 必须写入非目标或剩余风险
 - 写完后用 Write tool 保存到文件
 \`\`\``
   }).join('\n\n')
@@ -443,8 +628,8 @@ ${subagentPrompts}
 
 ## 验收
 - 每个 task-N.md 文件存在且非空
-- 包含 YAML frontmatter（id、title、priority、depends_on、blocks、allowed_paths）
-- 包含所有必要章节：修改文件、实现要求、接口定义、边界处理（≥5条）、非目标、TDD 步骤、验收标准（表格格式）
+- 包含 YAML frontmatter（id、title、priority、depends_on、blocks、requirement_ids、decision_ids、allowed_paths）
+- 包含所有必要章节：修改文件、覆盖来源、实现要求、接口定义、边界处理（≥5条）、非目标、TDD 步骤、验收标准（表格格式）
 - 边界处理覆盖：null/空值、兼容性、异常处理、参数不可变、歧义场景`
 
   return {

package/src/stages/propose.js

@@ -1,3 +1,8 @@
+/**
+ * @deprecated propose 阶段已移除入口（2026-06-14）。
+ * brainstorm 现在拥有四件套（design/proposal/requirements/tasks）的生成职责。
+ * 本文件保留以备未来需要恢复，但未注册到 stageRegistry。
+ */
 export const definition = {
   name: 'propose',
   title: '方案设计',
@@ -87,10 +92,29 @@ export const definition = {
 - **非功能需求**：兼容性、可回退、可测试、可扩展
 
 ### design.md 格式要求
-- **架构决策** + **文件变更清单表格** + **接口定义**
-- **兼容策略**（brownfield 必填）：未配置新功能时行为不变、回退路径
-- **风险登记**表格：编号/风险/等级/应对策略
-- **自审**：需求覆盖、真实性、YAGNI、非目标
+
+**必须包含的章节：**
+1. **背景**：为什么做、解决什么问题
+2. **设计目标**：要达成什么
+3. **非目标**：明确不做的事（防止 scope creep）
+4. **总体方案**：技术方案（分 Phase/Wave）
+5. **文件变更清单**（必填）：
+
+| 操作 | 文件路径 | 说明 |
+|---|---|---|
+| 新增 | src/xxx/NewFile.java | ... |
+| 修改 | src/xxx/ExistingFile.java | 新增 xx 方法 |
+
+6. **接口定义**：方法签名、数据结构（代码类任务必填）
+7. **数据模型**（如涉及）：表结构/字段变更
+8. **兼容策略**（brownfield 必填）：未配置新功能时行为不变、新旧逻辑的回退路径
+9. **风险登记**：
+
+| 编号 | 风险 | 等级 | 应对策略 |
+|---|---|---|---|
+| R-01 | ... | P0/P1/P2 | ... |
+
+10. **自审**：需求覆盖、约束一致性、真实性、YAGNI、验收标准、非目标清晰、兼容策略、风险识别
 
 ### tasks.md 格式要求
 - 任务列表（只列名称，不展开步骤）
@@ -119,9 +143,11 @@ export const definition = {
 ### 操作
 检查以下各项：
 - [ ] proposal.md 有动机、关键问题、变更范围、不在范围内、成功标准
+- [ ] design.md 有背景、设计目标、非目标
 - [ ] design.md 有文件变更清单表格
 - [ ] design.md 有兼容策略（brownfield 时）
 - [ ] design.md 有风险登记表格
+- [ ] design.md 有自审
 - [ ] requirements.md 有角色表
 - [ ] requirements.md 有 FR 编号和 Given/When/Then 用户场景
 - [ ] tasks.md 每个 task 有文件路径

package/src/stages/quick.js

@@ -72,24 +72,27 @@ quicklog 已创建（必须放在输出的第一行确认）+ 任务理解 + 上
       prompt: `Git 暂存并更新任务记录。
 
 ### 操作
-1. \`git add -A\` — 暂存改动文件（不要 commit，由用户通过统一提交工具处理）
-2. 更新 Step 1 创建的记录：
+1. 查看 \`git status --porcelain\`，确认只包含本次 quick 相关文件
+2. 使用 \`git add -- <file...>\` 暂存本次 quick 实际修改的文件（不要 commit，由用户通过统一提交工具处理）
+   - 禁止使用 \`git add -A\`
+   - 不要暂存 quick 开始前就已存在的无关改动
+3. 更新 Step 1 创建的记录：
    - 无 \`--change\`：找到对应 ql-ID 的条目，将「状态：进行中」改为「状态：已完成」，补充实际改动文件和结果摘要
    - 有 \`--change\`：勾选 tasks.md 中对应的 task checkbox
-3. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
-4. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
-5. 任务比预期复杂 → 建议用完整流程
+4. QUICKLOG 轮转：超过 500 行则重命名为 \`QUICKLOG-<USER>-YYYY-MM-DD.md\`（日期取最后一条记录的日期）。新文件从空开始，ql-ID 需扫描同目录所有 QUICKLOG 文件中当天最大序号 +1
+5. 如果发现项目特有的坑，追加到 \`.sillyspec/knowledge/uncategorized.md\`
+6. 任务比预期复杂 → 建议用完整流程
 
 ### 模块文档同步
-6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-7. 对比本次修改的文件（\`git diff --name-only\`）与模块映射
-8. 如果命中模块 → 直接同步模块文档：
+7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+8. 对比本次修改的文件（\`git diff --name-only HEAD\`）与模块映射
+9. 如果命中模块 → 直接同步模块文档：
    - 读取对应的 \`.sillyspec/docs/<project>/modules/<module>.md\`（如不存在则新建）
    - 根据本次改动内容更新模块文档（正文描述当前状态，底部变更索引追加本次 ql-ID）
    - 变更索引格式：\`- ql-YYYYMMDD-NNN-XXXX | <一句话描述>\`
    - 写入模块文档
-   - 将更新的模块文件加入 \`git add\`
-9. 未命中任何模块 → 跳过，不做额外操作
+   - 使用 \`git add -- <module-doc>\` 暂存更新的模块文件
+10. 未命中任何模块 → 跳过，不做额外操作
 
 ### 输出
 暂存确认 + 记录路径 + 模块文档同步结果（如有）`,

package/src/stages/scan.js

@@ -122,6 +122,18 @@ export const definition = {
    对每个项目分别执行（将 \`<project>\` 替换为实际项目名）
 4. 如果检查报告有失败项，按报告中的角色和文件重试失败的部分
 
+### 覆盖保护
+- 生成每份 scan 文档时，frontmatter 必须包含：
+  \`\`\`yaml
+  ---
+  source_commit: <git-head-short>
+  updated_at: <now-iso-datetime>
+  generator: sillyspec-scan
+  ---
+  \`\`\`
+- 覆盖已有 scan 文档前先读取旧 frontmatter；如果旧文档的 \`source_commit\` 与当前 HEAD 不一致，或旧文档 \`updated_at\` 晚于本次 scan 开始时间，不要覆盖。
+- 如果用户明确传入 \`--force-rescan\`，允许覆盖，但仍需写入新的 \`source_commit\` 和 \`updated_at\`。
+
 ### 子代理上下文注入
 启动每个子代理前，将以下信息拼入子代理 prompt：
 - 项目名（直接用实际项目名）

package/src/stages/verify.js

@@ -53,20 +53,23 @@ export const definition = {
       prompt: `加载规范文件并确认。
 
 ### 操作
-1. 读取 proposal.md、design.md、tasks.md、requirements.md
-2. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
-3. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）
-4. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
-5. 标注每个文件的存在/不存在状态
+1. 读取 proposal.md、design.md、tasks.md、requirements.md、plan.md
+2. 如果存在 decisions.md，必须读取并提取所有当前版本 D-xxx@vN 决策 ID
+   - 如果存在 P0/P1 unresolved/blocking 决策，验证结论不能为 PASS
+   - 如果发现 superseded 决策被下游引用，标记为 ⚠️ stale decision reference
+3. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
+4. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`（构建命令、测试命令、lint 命令等）
+5. 加载代码规范：\`cat .sillyspec/docs/<project>/scan/CONVENTIONS.md 2>/dev/null\`
+6. 标注每个文件的存在/不存在状态
 
 ### 模块文档加载
-6. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
-7. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
-8. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
-9. **检查模块索引可信度**：如果相关模块的 needs_review 为 true，提示"该模块索引可能不可信，需要回看模块卡片或源码"
+7. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（不存在则跳过以下步骤）
+8. 根据 design.md 的文件变更清单匹配 _module-map.yaml 中的模块
+9. 读取匹配到的 \`.sillyspec/docs/<project>/modules/<module>.md\`
+10. **检查模块索引可信度**：如果相关模块的 needs_review 为 true，提示"该模块索引可能不可信，需要回看模块卡片或源码"
 
 ### 输出
-文件加载确认清单（含模块文档 + 索引可信度）`,
+文件加载确认清单（含 decisions.md 当前版本/未决项状态、模块文档 + 索引可信度）`,
       outputHint: '文件确认清单',
       optional: false
     },
@@ -123,9 +126,17 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 2. 对每个 task，检查对应模块目录下是否存在测试文件（*test*、*spec*、*Test*、*Spec*）
 3. 没有测试文件的 task 标记为 ⚠️ 缺少测试
 
+**探针 4：决策追踪覆盖探针（如存在 decisions.md）**
+1. 从 decisions.md 提取所有当前版本 D-xxx@vN
+2. 检查 requirements.md 是否引用每个 D-xxx@vN，并映射到 FR-xxx
+3. 检查 plan.md 或 tasks/task-NN.md 是否引用每个 FR-xxx/D-xxx@vN
+4. 检查本步骤收集的实现证据是否能回指到对应 D-xxx@vN/FR-xxx
+5. 任意 D-xxx@vN 无下游覆盖时标记为 ⚠️ 决策未闭环
+6. 任意 P0/P1 unresolved/blocking 决策标记为 FAIL blocker
+
 ### 探针结果处理
-- 将三个探针的结果汇总为「探针报告」
-- 如果探针发现问题（未实现标记、关键词缺失、测试缺失），在最终验证报告中明确标注
+- 将四个探针的结果汇总为「探针报告」
+- 如果探针发现问题（未实现标记、关键词缺失、测试缺失、决策未闭环），在最终验证报告中明确标注
 - 探针发现的问题不等同于验证失败，但必须在报告中列出
 
 ### 设计一致性检查
@@ -136,9 +147,10 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
 4. API 设计是否符合
 5. **Reverse Sync 检查**：如果发现实现合理但 design.md 未覆盖，先更新 design.md 补充遗漏
 6. **模块文档一致性检查**：如果在"加载规范并锚定"步骤中加载了模块文档，检查实现是否符合模块文档描述的当前设计（特别关注接口签名、数据流、依赖关系）。不符合时标记 ⚠️（不阻断，模块文档可能未及时更新）
+7. **决策链路检查**：如果存在 decisions.md，输出 D-xxx@vN → FR-xxx → task-xx → evidence 的追踪矩阵；缺失项必须列为风险
 
 ### 输出
-探针报告 + 设计一致性检查结果 + 模块文档一致性检查结果`,
+探针报告 + 设计一致性检查结果 + 模块文档一致性检查结果 + 决策追踪矩阵（如有）`,
       outputHint: '设计一致性报告',
       optional: false
     },
@@ -210,6 +222,12 @@ PASS / PASS WITH NOTES / FAIL
 - 未实现标记扫描：...
 - 关键词覆盖：...
 - 测试覆盖：...
+- 决策追踪覆盖：...
+
+## 决策追踪矩阵（如存在 decisions.md）
+| 决策 ID | FR | Task | Evidence | 状态 |
+|---|---|---|---|---|
+| D-001@v1 | FR-01 | task-01 | test/file/path | PASS/PARTIAL/MISSING |
 
 ## 测试结果
 （测试套件执行结果）

package/src/workflow.js

@@ -12,6 +12,7 @@
 import { readFileSync, existsSync, readdirSync, writeFileSync, mkdirSync } from 'fs'
 import { join, resolve, basename } from 'path'
 import jsYaml from 'js-yaml'
+import { WORKFLOW_STATUS } from './constants.js'
 
 // ─── Workflow 加载 ───