sillyspec 3.18.0 → 3.18.2

package/src/stages/execute.js

@@ -52,27 +52,25 @@ const fixedPrefix = [
     optional: false
   },
   {
-    name: '创建 worktree',
-    prompt: `为本次执行创建隔离的 git worktree。
+    name: '确认 worktree 路径',
+    prompt: `确认当前 worktree 状态，提取隔离路径。
 
 ### 操作
-1. 运行 \`sillyspec worktree create <change-name>\`
-2. 记录输出的 worktree 路径
-3. 后续所有子代理的 cwd 设为该 worktree 路径
-4. 如果创建失败 → 报错并停止（不要在无隔离状态下继续）
+1. 运行 \`sillyspec worktree meta <change-name>\` 读取 meta.json
+2. 从输出中提取 worktreePath、branch、mode 字段
+3. 确认 worktree 目录存在（如果是 worktree/native-worktree 模式）
 
-### 降级模式
-CLI 可能自动降级（sandbox 限制、已在 linked worktree 中）：
-- \`mode: native-worktree\` — 已在 linked worktree，直接复用
-- \`mode: in-place-fallback\` — git worktree add 失败，降级为 in-place + baseline protection
-- 这两种模式都会输出 worktree 路径和分支名，正常继续即可
+### 铁律
+- **worktree 已由 CLI 在 execute 阶段启动时自动创建，不要自行创建或跳过**
+- **后续所有子代理的 cwd 必须设为该 worktree 路径**
+- 如果 meta.json 不存在（说明创建失败），停止并报错
 
 ### 输出
-worktree 路径 + 分支名 + 模式（如果有）
+worktree 路径 + 分支名 + 模式
 
 ### 完成后执行
-sillyspec run execute --done --output "worktree 路径 + 分支名"`,
-    outputHint: 'worktree 路径 + 分支名',
+sillyspec run execute --done --output "worktree 路径 + 分支名 + 模式"`,
+    outputHint: 'worktree 路径 + 分支名 + 模式',
     optional: false
   },
   {

package/src/stages/index.js

@@ -1,5 +1,4 @@
 import { definition as brainstorm } from './brainstorm.js'
-import { definition as propose } from './propose.js'
 import { definition as plan } from './plan.js'
 import { definition as execute } from './execute.js'
 import { definition as verify } from './verify.js'
@@ -15,7 +14,6 @@ const auxiliaryFlag = { auxiliary: true }
 
 export const stageRegistry = {
   brainstorm,
-  propose,
   plan,
   execute,
   verify,

package/src/stages/plan.js

@@ -84,22 +84,25 @@ needs_human_review: true | false
 ### 操作
 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
   },
@@ -170,12 +173,17 @@ plan_level: light
 - 涉及的文件/模块清单
 
 ## Tasks
-- [ ] task-01: ...
+- [ ] task-01: ...（覆盖：FR-01, D-001@v1）
 - [ ] task-02: ...
 - [ ] task-03: ...
 
 ## 验收
 - 具体可验证的验收条目
+
+## 覆盖矩阵（如存在 decisions.md）
+| ID | 覆盖任务 | 验收证据 |
+|---|---|---|
+| D-001@v1 | task-01 | AC-01 |
 \`\`\`
 
 light 计划的约束：
@@ -184,6 +192,8 @@ light 计划的约束：
 - **禁止**泛泛风险 分析（如"需要充分测试"）
 - **禁止**放实现细节（函数签名、代码示例）
 - 来源/目标直接引用已有文档，不重新生成
+- 如果存在 decisions.md，所有当前版本 D-xxx@vN 必须在 Tasks 或覆盖矩阵中出现
+- 如果存在 P0/P1 unresolved blocker，不生成 plan.md
 - 任务列表控制在 10 条以内
 - **任务必须使用 checkbox 格式**（\`- [ ] task-XX:\`），不要用纯编号列表（\`1. 2.\`），execute 阶段依赖此格式解析任务
 
@@ -207,18 +217,18 @@ plan_level: full
 > 技术不确定性高时才需要 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 | 优先级 | 依赖 | 说明 |
-|---|---|---|---|---|---|
-| task-01 | 添加用户创建接口 | W1 | P0 | — | ... |
-| task-02 | 添加角色创建接口 | W1 | P0 | — | ... |
-| task-03 | 用户创建接口联调 | W2 | P0 | task-01,02 | ... |
+| 编号 | 任务 | Wave | 优先级 | 依赖 | 覆盖 FR/D | 说明 |
+|---|---|---|---|---|---|---|
+| 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（最长路径，决定最短交付周期）
@@ -226,6 +236,11 @@ task-01 → task-03（最长路径，决定最短交付周期）
 ## 全局验收标准
 - [ ] 所有单元测试通过
 - [ ] （brownfield）未配置新功能时行为不变
+
+## 覆盖矩阵（如存在 decisions.md）
+| ID | 覆盖任务 | 验收证据 |
+|---|---|---|
+| D-001@v1 | task-01 | AC-01 |
 \`\`\`
 
 full 计划的约束：
@@ -234,6 +249,8 @@ 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 ...
 - 任务总表的优先级：P0（必须）/ P1（重要）/ P2（可选）
@@ -290,6 +307,8 @@ plan_level + 计划内容（none 级别输出建议操作）`,
 - [ ] 任务列表清晰且无实现细节
 - [ ] 任务使用 checkbox 格式（\`- [ ] task-XX:\`），不是纯编号列表
 - [ ] 验收标准具体可验证（非笼统表述）
+- [ ] 如果存在 decisions.md，所有当前版本 D-xxx@vN 在 plan.md 中可追踪
+- [ ] 不存在 P0/P1 unresolved blocker
 - [ ] 没有 Mermaid 图、估时、风险分析
 - [ ] 没有函数签名、代码示例等实现细节
 - [ ] plan.md 与 design.md 的文件变更清单一致
@@ -302,6 +321,8 @@ plan_level + 计划内容（none 级别输出建议操作）`,
 - [ ] 有任务总表（含优先级、依赖列，**无估时列**）
 - [ ] 有关键路径标注
 - [ ] 有全局验收标准
+- [ ] 如果存在 decisions.md，任务总表或覆盖矩阵覆盖全部当前版本 D-xxx@vN
+- [ ] 不存在 P0/P1 unresolved blocker
 - [ ] （brownfield）全局验收包含兼容性条款
 - [ ] 没有实现细节（接口定义、代码示例等不应该在 plan.md 里）
 - [ ] plan.md 与 design.md 的文件变更清单一致
@@ -413,6 +434,8 @@ priority: P0
 estimated_hours: N
 depends_on: []
 blocks: []
+requirement_ids: [FR-01]
+decision_ids: [D-001@v1]
 allowed_paths:
   - 允许修改的路径范围
 ---
@@ -422,6 +445,10 @@ allowed_paths:
 ## 修改文件（必填）
 - 精确到文件路径，列出所有需要新增或修改的文件
 
+## 覆盖来源
+- Requirements: FR-xx（来自 requirements.md）
+- Decisions: D-xxx@vN（如存在 decisions.md）
+
 ## 实现要求
 1. 具体做什么，写清楚
 2. ...
@@ -463,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 可以修改的文件路径范围（安全边界）
 
 ### 关键规则
@@ -471,6 +500,7 @@ allowed_paths:
 - 接口定义写到"搬砖工照着做"的程度
 - 边界处理至少覆盖 5 条规则
 - 验收标准用表格格式，每条可点击验证，禁止"功能可演示"类笼统表述
+- 如果存在 decisions.md，不允许丢失当前版本 D-xxx@vN；无法覆盖的 D-xxx@vN 必须写入非目标或剩余风险
 - 写完后保存到文件
 
 ### 操作
@@ -518,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:
   - ...
 ---
@@ -527,6 +559,10 @@ allowed_paths:
 ## 修改文件（必填）
 - 精确到文件路径
 
+## 覆盖来源
+- Requirements: FR-xx
+- Decisions: D-xxx@vN（如存在）
+
 ## 实现要求
 1. 具体做什么
 
@@ -560,6 +596,7 @@ allowed_paths:
 - 接口定义写到"搬砖工照着做"的程度
 - 边界处理至少 5 条
 - 验收标准用表格，禁止笼统表述
+- 如果存在 decisions.md，不允许丢失当前版本 D-xxx@vN；无法覆盖的 D-xxx@vN 必须写入非目标或剩余风险
 - 写完后用 Write tool 保存到文件
 \`\`\``
   }).join('\n\n')
@@ -591,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/test/platform-artifacts.test.mjs

@@ -13,6 +13,7 @@ import { join, dirname } from 'path'
 import { existsSync, mkdirSync, rmSync, readFileSync, readdirSync, writeFileSync } from 'fs'
 import { fileURLToPath } from 'url'
 import { randomUUID } from 'crypto'
+import { tmpdir } from 'os'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const passed = []
@@ -33,11 +34,19 @@ function cleanup(dir) {
   try { rmSync(dir, { recursive: true, force: true }) } catch {}
 }
 
+function hasPathSegments(value, segments) {
+  const parts = value.split(/[\\/]+/)
+  for (let i = 0; i <= parts.length - segments.length; i++) {
+    if (segments.every((segment, offset) => parts[i + offset] === segment)) return true
+  }
+  return false
+}
+
 // ── 测试 1：saveWorkflowRun 平台模式路径正确 ──
 console.log('\n=== Test 1: saveWorkflowRun 平台模式写入路径 ===')
 {
   const { saveWorkflowRun } = await import('../src/workflow.js')
-  const tmpRoot = `/tmp/test-artifacts-${randomUUID().slice(0, 8)}`
+  const tmpRoot = join(tmpdir(), `test-artifacts-${randomUUID().slice(0, 8)}`)
   const runtimeRoot = join(tmpRoot, 'runtime')
   const scanRunId = 'scan-20260614-test-001'
 
@@ -63,8 +72,8 @@ console.log('\n=== Test 1: saveWorkflowRun 平台模式写入路径 ===')
   assert('workflow-runs 目录存在', existsSync(expectedDir))
   assert('workflow-runs 文件存在', existsSync(saved), `路径: ${saved}`)
   assert('路径在 runtime-root 下', saved.startsWith(runtimeRoot), `路径: ${saved}`)
-  assert('路径包含 scan-runs', saved.includes('scan-runs'), `路径: ${saved}`)
-  assert('路径包含 scanRunId', saved.includes(scanRunId), `路径: ${saved}`)
+  assert('路径包含 scan-runs', hasPathSegments(saved, ['scan-runs', scanRunId, 'workflow-runs']), `路径: ${saved}`)
+  assert('路径包含 scanRunId', hasPathSegments(saved, [scanRunId]), `路径: ${saved}`)
 
   // 验证 JSON 内容
   const content = JSON.parse(readFileSync(saved, 'utf8'))
@@ -81,7 +90,7 @@ console.log('\n=== Test 1: saveWorkflowRun 平台模式写入路径 ===')
 console.log('\n=== Test 2: saveWorkflowRun 本地模式写入路径 ===')
 {
   const { saveWorkflowRun } = await import('../src/workflow.js')
-  const tmpCwd = `/tmp/test-artifacts-local-${randomUUID().slice(0, 8)}`
+  const tmpCwd = join(tmpdir(), `test-artifacts-local-${randomUUID().slice(0, 8)}`)
   const sillyspecDir = join(tmpCwd, '.sillyspec', '.runtime', 'workflow-runs')
 
   const result = {
@@ -102,7 +111,7 @@ console.log('\n=== Test 2: saveWorkflowRun 本地模式写入路径 ===')
   })
 
   assert('本地模式文件存在', existsSync(saved))
-  assert('本地路径在 .sillyspec/.runtime 下', saved.includes('.sillyspec/.runtime/workflow-runs'), `路径: ${saved}`)
+  assert('本地路径在 .sillyspec/.runtime 下', hasPathSegments(saved, ['.sillyspec', '.runtime', 'workflow-runs']), `路径: ${saved}`)
 
   const content = JSON.parse(readFileSync(saved, 'utf8'))
   assert('本地 JSON status = fail', content.status === 'fail')

package/test/platform-failure-samples.test.mjs

@@ -13,6 +13,7 @@
 import { join, basename } from 'path'
 import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs'
 import { randomUUID } from 'crypto'
+import { tmpdir } from 'os'
 import { SCAN_STATUS, CHECK_SEVERITY } from '../src/constants.js'
 
 const passed = []
@@ -34,8 +35,8 @@ function cleanup(dir) {
 }
 
 function setup(name) {
-  const base = `/tmp/failure-test-${name}-${randomUUID().slice(0, 8)}`
-  const spec = `/tmp/failure-test-spec-${name}-${randomUUID().slice(0, 8)}`
+  const base = join(tmpdir(), `failure-test-${name}-${randomUUID().slice(0, 8)}`)
+  const spec = join(tmpdir(), `failure-test-spec-${name}-${randomUUID().slice(0, 8)}`)
   mkdirSync(base, { recursive: true })
   mkdirSync(spec, { recursive: true })
   writeFileSync(join(base, 'package.json'), '{}')

package/test/platform-recovery-chain.test.mjs

@@ -16,6 +16,7 @@ import { execSync } from 'child_process'
 import { fileURLToPath } from 'url'
 import { dirname } from 'path'
 import { randomUUID } from 'crypto'
+import { tmpdir } from 'os'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const binCLI = join(__dirname, '..', 'src', 'index.js')
@@ -48,9 +49,9 @@ function run(cmd, opts = {}) {
 // ── 测试 1：pointer 文件创建和内容 ──
 console.log('\n=== Test 1: pointer 文件创建 ===')
 {
-  const tmpCwd = `/tmp/recovery-test-${randomUUID().slice(0, 8)}`
-  const tmpSpec = `/tmp/recovery-test-spec-${randomUUID().slice(0, 8)}`
-  const tmpRuntime = `/tmp/recovery-test-rt-${randomUUID().slice(0, 8)}`
+  const tmpCwd = join(tmpdir(), `recovery-test-${randomUUID().slice(0, 8)}`)
+  const tmpSpec = join(tmpdir(), `recovery-test-spec-${randomUUID().slice(0, 8)}`)
+  const tmpRuntime = join(tmpdir(), `recovery-test-rt-${randomUUID().slice(0, 8)}`)
 
   try {
     mkdirSync(tmpCwd, { recursive: true })
@@ -82,9 +83,9 @@ console.log('\n=== Test 1: pointer 文件创建 ===')
 // ── 测试 2：--done 不带参数能恢复 ──
 console.log('\n=== Test 2: --done 恢复平台参数 ===')
 {
-  const tmpCwd = `/tmp/recovery-test2-${randomUUID().slice(0, 8)}`
-  const tmpSpec = `/tmp/recovery-test2-spec-${randomUUID().slice(0, 8)}`
-  const tmpRuntime = `/tmp/recovery-test2-rt-${randomUUID().slice(0, 8)}`
+  const tmpCwd = join(tmpdir(), `recovery-test2-${randomUUID().slice(0, 8)}`)
+  const tmpSpec = join(tmpdir(), `recovery-test2-spec-${randomUUID().slice(0, 8)}`)
+  const tmpRuntime = join(tmpdir(), `recovery-test2-rt-${randomUUID().slice(0, 8)}`)
   const scanRunId = `scan-${Date.now()}`
 
   try {
@@ -125,8 +126,8 @@ console.log('\n=== Test 3: manifest 路径字段 ===')
 // ── 测试 4：异常 pointer 检测 ──
 console.log('\n=== Test 4: 异常 pointer 残留检测 ===')
 {
-  const tmpCwd = `/tmp/recovery-test4-${randomUUID().slice(0, 8)}`
-  const tmpSpec = `/tmp/recovery-test4-spec-${randomUUID().slice(0, 8)}`
+  const tmpCwd = join(tmpdir(), `recovery-test4-${randomUUID().slice(0, 8)}`)
+  const tmpSpec = join(tmpdir(), `recovery-test4-spec-${randomUUID().slice(0, 8)}`)
 
   try {
     mkdirSync(tmpCwd, { recursive: true })
@@ -147,7 +148,7 @@ console.log('\n=== Test 4: 异常 pointer 残留检测 ===')
     // 模拟有效 pointer（手动修复）
     writeFileSync(pointerPath, JSON.stringify({
       specRoot: tmpSpec,
-      runtimeRoot: '/tmp/fake-rt',
+      runtimeRoot: join(tmpdir(), 'fake-rt'),
       workspaceId: 'test',
       scanRunId: 'scan-test',
       savedAt: new Date().toISOString(),

package/test/platform-recovery.test.mjs

@@ -6,6 +6,7 @@ import { join, resolve, dirname, basename } from 'path'
 import { existsSync, mkdirSync, writeFileSync, rmSync, readFileSync } from 'fs'
 import { fileURLToPath, pathToFileURL } from 'url'
 import { execSync } from 'child_process'
+import { tmpdir } from 'os'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
@@ -21,16 +22,23 @@ function assert(cond, msg) {
 
 const P = 'recover'
 function setup(name) {
-  const d = join('/tmp', `${P}-${name}`)
+  const d = join(tmpdir(), `${P}-${name}`)
   mkdirSync(d, { recursive: true })
   return d
 }
 function spec(name) {
-  const d = join('/tmp', `${P}-${name}-spec`)
+  const d = join(tmpdir(), `${P}-${name}-spec`)
   mkdirSync(d, { recursive: true })
   return d
 }
 function clean(...dirs) { for (const d of dirs) try { rmSync(d, { recursive: true, force: true }) } catch {} }
+function hasPathSegments(value, segments) {
+  const parts = value.split(/[\\/]+/)
+  for (let i = 0; i <= parts.length - segments.length; i++) {
+    if (segments.every((segment, offset) => parts[i + offset] === segment)) return true
+  }
+  return false
+}
 
 function run(cmd) {
   return execSync(cmd, { encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'] })
@@ -127,8 +135,8 @@ console.log('\n=== Test 5: specDir 缺文档 → 校验失败，路径不含 .si
   assert(!result.ok, `specDir 缺文档: ok=${result.ok}`)
   assert(result.errors.length > 0, `有 errors`)
   const errMsg = result.errors[0]
-  assert(!errMsg.includes('.sillyspec/docs'), `路径不含 .sillyspec: ${errMsg}`)
-  assert(errMsg.includes('/docs/'), `路径含 /docs/: ${errMsg}`)
+  assert(!hasPathSegments(errMsg, ['.sillyspec', 'docs']), `路径不含 .sillyspec: ${errMsg}`)
+  assert(hasPathSegments(errMsg, ['docs', proj, 'scan']), `路径含 docs/${proj}/scan: ${errMsg}`)
   clean(cwd, sd)
 }
 
@@ -149,7 +157,7 @@ console.log('\n=== Test 7: 非平台模式缺文档 → 路径含 .sillyspec ===
   const result = runValidators('scan', cwd, 'default', { projectName: proj })
   assert(!result.ok, `非平台缺文档: ok=${result.ok}`)
   const errMsg = result.errors[0]
-  assert(errMsg.includes('.sillyspec/docs'), `路径含 .sillyspec/docs/: ${errMsg}`)
+  assert(hasPathSegments(errMsg, ['.sillyspec', 'docs']), `路径含 .sillyspec/docs: ${errMsg}`)
   clean(cwd)
 }
 

package/test/platform-scan-p0.test.mjs

@@ -142,11 +142,14 @@ function assert(label, condition, detail) {
 {
   const { definition } = await import('../src/stages/quick.js')
   const step1Prompt = definition.steps[0].prompt
+  const step3Prompt = definition.steps[2].prompt
 
   assert('quick step 1 包含 ⛔ 标记', step1Prompt.includes('⛔'))
   assert('quick step 1 包含「不能跳过」', step1Prompt.includes('不能跳过'))
   assert('quick step 1 包含 quicklog 未创建 warning', step1Prompt.includes('quicklog 未创建'))
   assert('quick step 1 输出要求 quicklog 第一行', step1Prompt.includes('第一行确认'))
+  assert('quick step 3 禁止 git add -A', step3Prompt.includes('禁止使用 `git add -A`'))
+  assert('quick step 3 使用 scoped git add', step3Prompt.includes('git add -- <file...>'))
 
   // run.js 审计包含 quicklog 检查
   const runSrc = await readFile(join(__dirname, '..', 'src', 'run.js'), 'utf8')