sillyspec 3.10.3 → 3.10.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sillyspec",
-  "version": "3.10.3",
+  "version": "3.10.4",
   "description": "SillySpec CLI — 流程状态机，让 AI 严格按步骤来",
   "icon": "logo.jpg",
   "homepage": "https://sillyspec.ppdmq.top/",

package/src/stages/brainstorm.js

@@ -211,6 +211,34 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
       name: '写设计文档并自审',
       prompt: `撰写 design 文档并进行 AI 自审。
 
+### design.md 必须包含的章节
+1. **背景**：为什么做、解决什么问题
+2. **设计目标**：要达成什么
+3. **非目标**：明确不做的事（防止 scope creep）
+4. **拆分判断**（如适用）：为什么这样组织变更、为什么不走批量模式
+5. **总体方案**：技术方案（分 Phase/Wave）
+6. **文件变更清单**（必填）：
+
+| 操作 | 文件路径 | 说明 |
+|---|---|---|
+| 新增 | src/xxx/NewFile.java | ... |
+| 修改 | src/xxx/ExistingFile.java | 新增 xx 方法 |
+| 删除 | src/xxx/OldFile.java | 已被 xx 替代 |
+
+7. **接口定义**：方法签名、数据结构（代码类任务必填）
+8. **数据模型**（如涉及）：表结构/字段变更
+9. **兼容策略**（brownfield 必填）：
+   - 未配置新功能时行为不变
+   - 新旧逻辑的回退路径
+   - 不改变的 API / 表结构
+10. **风险登记**：
+
+| 编号 | 风险 | 等级 | 应对策略 |
+|---|---|---|---|
+| R-01 | ... | P0/P1/P2 | ... |
+
+11. **自审**（AI 对自身设计的校验）
+
 ### 操作
 1. 确认变更目录存在：\`mkdir -p .sillyspec/changes/<变更名>\`（Windows 用 \`mkdir .sillyspec\\changes\\<变更名>\` 或 PowerShell \`New-Item -ItemType Directory -Force -Path .sillyspec/changes/<变更名>\`）
    - 变更名格式必须为 \`YYYY-MM-DD-<简短描述>\`（如 \`2026-05-13-user-auth\`）
@@ -218,11 +246,14 @@ HTML 原型文件路径（或"跳过"如果不适合）`,
 3. 自审检查：
    - 需求覆盖：是否完整覆盖 Step 6 确认的需求
    - 约束一致性：是否与 CONVENTIONS.md、ARCHITECTURE.md 一致
-   - 真实性：表名/字段名来自真实 schema 或标注"新增"
+   - 真实性：表名/字段名/类名/方法名来自真实代码或标注"新增"
    - YAGNI：是否包含不必要功能
    - 验收标准：是否具体可测试
-3. 自审发现问题 → 修改后重新检查
-4. 全部通过 → 进入下一步
+   - 非目标清晰：是否明确界定了不做的事
+   - 兼容策略（brownfield）：是否说明了回退路径
+   - 风险识别：是否识别了关键技术风险和对策
+4. 自审发现问题 → 修改后重新检查
+5. 全部通过 → 进入下一步
 
 ### 输出
 design.md 文件路径 + 自审结果
@@ -230,10 +261,7 @@ design.md 文件路径 + 自审结果
 ### 注意
 - 自审不通过不要进入下一步
 - 不确定的问题标注「⚠️ 自审存疑」`,
-      outputHint: 'design.md 路径 + 自审结果',
-      optional: false
-    },
-    {
+
       name: '用户确认并生成规范文件',
       prompt: `用户确认设计方案，生成规范文件。
 
@@ -241,12 +269,59 @@ design.md 文件路径 + 自审结果
 1. 展示 design.md 摘要给用户
 2. 请用户选择：✅ 确认 / ✏️ 修改 / ❌ 推翻重来
 3. 确认后，在 \`.sillyspec/changes/<变更名>/\` 下生成所有规范文件：
-   - **design.md**：架构决策、文件变更清单、数据模型、API 设计、代码风格参照
-   - **proposal.md**：动机、变更范围、不在范围内、成功标准
-   - **requirements.md**：功能需求、用户场景（Given/When/Then 格式）、非功能需求
+   - **design.md**：架构决策、文件变更清单、数据模型、API 设计、兼容策略、风险登记、自审
+   - **proposal.md**：动机、关键问题（为什么现有方案不够）、变更范围、不在范围内（显式清单）、成功标准（可验证条件）
+   - **requirements.md**：角色表 + FR 编号需求 + Given/When/Then 行为规格 + 非功能需求
    - **tasks.md**：任务列表（只列名称和对应文件路径，细节在 plan 阶段展开）
    - \`git add .sillyspec/\` — 暂存规范文件（不要 commit）
 
+### proposal.md 格式要求
+\`\`\`markdown
+# Proposal
+
+## 动机
+为什么做、解决什么核心问题
+
+## 关键问题
+为什么现有方案不够（展开 2-3 个具体痛点）
+
+## 变更范围
+本次做什么
+
+## 不在范围内（显式清单）
+- 不做 X
+- 不做 Y
+
+## 成功标准（可验证）
+- 旧配置默认行为不变
+- 新功能在配置后可用
+- ...
+\`\`\`
+
+### requirements.md 格式要求
+\`\`\`markdown
+# Requirements
+
+## 角色
+| 角色 | 说明 |
+|---|---|
+| 开发者 | ... |
+
+## 功能需求
+
+### FR-01: 需求名称
+Given 前提条件
+When 触发动作
+Then 期望结果
+
+（每个边界条件独立 GWT 块）
+
+## 非功能需求
+- 兼容性：...
+- 可回退：...
+- 可测试：...
+\`\`\`
+
 ### 输出
 所有规范文件路径
 
@@ -255,10 +330,9 @@ design.md 文件路径 + 自审结果
 - 禁止在确认前推进到后续阶段
 - 禁止自动 commit
 - 推翻重来回到 Step 6
-- 表名/字段名必须来自真实 schema 或标注"新增"
+- 表名/字段名/类名必须来自真实代码或标注"新增"
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
-      outputHint: '规范文件路径',
-      optional: false
+
     }
   ]
 }

package/src/stages/execute.js

@@ -274,7 +274,7 @@ ${taskSummary}
 子代理 prompt 要点：
 1. 任务目标（简短描述）
 2. 蓝图文件路径（让子代理自行读取详情）
-3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事
+3. 编码铁律：先读后写、TDD、不编造方法、只做蓝图里写的事、遵守边界处理规则、不超出 allowed_paths
 
 ### Wave 开始前
 1. 读取 design.md 的「编码铁律」章节（如果存在），严格遵守

package/src/stages/plan.js

@@ -54,10 +54,17 @@ export const fixedPrefix = [
     name: '展开任务并分组',
     prompt: `把 tasks.md 每个 checkbox 展开为任务描述，按 Wave 分组，产出 plan.md 总览。
 
-### plan.md 格式（轻量总览，PM 视角）
+### plan.md 格式（PM 视角 + 机器可解析）
 \`\`\`markdown
 # 实现计划
 
+## Spike 前置验证（如需要）
+| Spike | 验证内容 | 不通过后果 |
+|---|---|---|
+| spike-01 | ... | task-XX 推翻重设计 |
+
+> 技术不确定性高时才需要 Spike。无不确定性则跳过此节。
+
 ## Wave 1（并行，无依赖）
 - [ ] task-01: 添加用户创建接口
 - [ ] task-02: 添加角色创建接口
@@ -65,14 +72,42 @@ export const fixedPrefix = [
 ## Wave 2（依赖 Wave 1）
 - [ ] task-03: 用户创建接口联调
 
+## 任务总表
+| 编号 | 任务 | Wave | 优先级 | 估时 | 依赖 | 说明 |
+|---|---|---|---|---|---|---|
+| 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 → task-03（最长路径，决定最短交付周期）
+
 ## 全局验收标准
 - [ ] 所有单元测试通过
+- [ ] （brownfield）未配置新功能时行为不变
 \`\`\`
 
 ### 关键规则
-- plan.md 只放任务列表 + Wave 划分 + 全局验收标准，**不放实现细节**
+- plan.md 包含：Wave 分组 + 任务总表 + 依赖图 + 关键路径 + 全局验收标准，**不放实现细节**
 - 实现细节写到后续的 tasks/task-NN.md 中
 - 每个任务编号格式：task-01、task-02 ...
+- **Wave 下的 checkbox 行必须保留**（execute 阶段解析依赖 \`- [ ] task-XX:\` 格式）
+- 任务总表的优先级：P0（必须）/ P1（重要）/ P2（可选）
+- 估时参考：单个 task ≤ 8h，超过则拆分
+
+### Spike 前置验证
+当存在技术不确定性时，在 Wave 之前设计 Spike：
+- 涉及新技术栈/未经验证的集成 → 需要 Spike
+- 涉及安全隔离/性能瓶颈 → 需要 Spike
+- 纯业务逻辑/确定的技术方案 → 不需要 Spike
+- 每个 Spike 定义：验证内容 + 通过标准 + 不通过后果
 
 ### 批量模式指引
 如果 design.md 或需求中包含批量特征（关键词：批量/模板/引擎/N个相似），按以下原则规划：
@@ -87,7 +122,11 @@ export const fixedPrefix = [
 2. 读取 design.md 获取文件变更清单
 3. 逐个展开为任务描述
 4. 分析依赖关系，按 Wave 分组
-5. 保存到 \`.sillyspec/changes/<变更名>/plan.md\`
+5. 生成任务总表（含优先级、估时、依赖）
+6. 生成 Mermaid 依赖关系图
+7. 标注关键路径
+8. 评估是否需要 Spike 前置验证
+9. 保存到 \`.sillyspec/changes/<变更名>/plan.md\`
 
 ### 输出
 plan.md 总览内容`,
@@ -101,9 +140,13 @@ plan.md 总览内容`,
 ### 操作
 检查以下各项：
 - [ ] 每个 task 有编号（task-01、task-02 ...）
-- [ ] 每个 task 有 checkbox
+- [ ] 每个 task 在 Wave 下有 checkbox（\`- [ ] task-XX:\` 格式，execute 解析依赖此格式）
 - [ ] 已标注 Wave 分组和依赖关系
+- [ ] 有任务总表（含优先级、估时、依赖列）
+- [ ] 有 Mermaid 依赖关系图
+- [ ] 有关键路径标注
 - [ ] 有全局验收标准
+- [ ] （brownfield）全局验收包含兼容性条款
 - [ ] 没有实现细节（接口定义、代码示例等不应该在 plan.md 里）
 - [ ] plan.md 与 design.md 的文件变更清单一致
 
@@ -161,57 +204,89 @@ function parseTaskCount(planContent) {
  * 生成单个任务的蓝图写作 prompt
  */
 function buildTaskPrompt(taskNum, taskName, changeDir) {
-  return `编写任务蓝图 tasks/task-${String(taskNum).padStart(2, '0')}.md
+  const num = String(taskNum).padStart(2, '0')
+  return `编写任务蓝图 tasks/task-${num}.md
 
 ### 任务
 ${taskName}
 
 ### 文件路径
-\`.sillyspec/changes/<变更名>/tasks/task-${String(taskNum).padStart(2, '0')}.md\`
+\`.sillyspec/changes/<变更名>/tasks/task-${num}.md\`
 
 ### 格式要求（必须严格遵守）
 \`\`\`markdown
-# task-${String(taskNum).padStart(2, '0')}: ${taskName}
-
-## 修改文件
-- 具体文件路径列表
+---
+id: task-${num}
+title: ${taskName}
+priority: P0
+estimated_hours: N
+depends_on: []
+blocks: []
+allowed_paths:
+  - 允许修改的路径范围
+---
+
+# task-${num}: ${taskName}
+
+## 修改文件（必填）
+- 精确到文件路径，列出所有需要新增或修改的文件
 
 ## 实现要求
 1. 具体做什么，写清楚
 2. ...
 
-## 接口定义
-（代码类任务必填，写方法签名、数据结构）
+## 接口定义（代码类任务必填）
+写方法签名、数据结构、控制流伪代码。AI executor 应能照着直接编码。
+
+## 边界处理（必填）
+- null/空值行为
+- 兼容旧行为（brownfield：未配置新功能时行为不变）
+- 异常不静默吞掉（明确返回值或抛出）
+- 不修改传入参数
+- 歧义/冲突场景的处理策略
 
-## 边界处理
-- 异常场景列表
+## 非目标（本任务不做的事）
+- 明确列出边界，防止 scope creep
 
 ## 参考
 - 已有代码可参考的模式
 - 相关的 CONVENTIONS.md 条目
 
 ## TDD 步骤
-1. 写测试 ...
-2. 运行 <test-cmd> 确认失败
-3. 写代码 ...
-4. 运行 <test-cmd> 确认通过
+1. 写 XxxTest，覆盖场景 A/B/C
+2. 运行 <test-cmd> 确认测试失败
+3. 实现 Xxx
+4. 运行 <test-cmd> 确认测试通过
+5. 运行全量测试确认无回退
 （纯配置/文档类任务简化为：1. 实现 2. 验证）
 
 ## 验收标准
-- [ ] 具体可测试的验收条件
+| # | 验证步骤 | 通过标准 |
+|---|---|---|
+| AC-01 | 具体操作 | 期望结果 |
+| AC-02 | ... | ... |
 \`\`\`
 
+### frontmatter 元数据说明
+- \`priority\`: P0（必须）/ P1（重要）/ P2（可选）
+- \`estimated_hours\`: 预估工时，单个 task ≤ 8h
+- \`depends_on\`: 依赖的前序 task 编号列表
+- \`blocks\`: 被本 task 阻塞的后续 task 编号列表
+- \`allowed_paths\`: AI executor 可以修改的文件路径范围（安全边界）
+
 ### 关键规则
 - task-N.md 必须独立完整，execute 子代理只读这一个文件就能干活
 - 不要依赖其他 task-N.md 的内容
 - 接口定义写到"搬砖工照着做"的程度
+- 边界处理至少覆盖 5 条规则
+- 验收标准用表格格式，每条可点击验证，禁止"功能可演示"类笼统表述
 - 写完后保存到文件
 
 ### 操作
 1. 读取 design.md 和 plan.md 了解上下文
 2. 读取相关源文件了解现有代码
 3. 编写任务蓝图
-4. 保存到 tasks/task-${String(taskNum).padStart(2, '0')}.md
+4. 保存到 tasks/task-${num}.md
 
 ### 输出
 任务蓝图内容摘要`
@@ -238,37 +313,60 @@ export function buildCoordinatorStep(changeDir, taskNames) {
 2. 读取相关源文件了解现有代码
 3. 按以下格式编写任务蓝图并保存到 ${changeDir}/tasks/task-${num}.md：
 
+---
+id: task-${num}
+title: ${name}
+priority: P0/P1/P2
+estimated_hours: N
+depends_on: [task-XX]
+blocks: [task-XX]
+allowed_paths:
+  - ...
+---
+
 # task-${num}: ${name}
 
-## 修改文件
-- 文件路径列表
+## 修改文件（必填）
+- 精确到文件路径
 
 ## 实现要求
 1. 具体做什么
 
-## 接口定义
-（代码类任务必填）
+## 接口定义（代码类任务必填）
+方法签名、数据结构、控制流伪代码
+
+## 边界处理（必填）
+- null/空值行为
+- 兼容旧行为（brownfield：未配置新功能时行为不变）
+- 异常不静默吞掉（明确返回值或抛出）
+- 不修改传入参数
+- 歧义/冲突场景的处理策略
 
-## 边界处理
-- 异常场景
+## 非目标（本任务不做的事）
+- 明确边界，防止 scope creep
 
 ## 参考
 - 可参考的模式
 
 ## TDD 步骤
-1. 写测试 → 2. 确认失败 → 3. 写代码 → 4. 确认通过
+1. 写测试 → 2. 确认失败 → 3. 写代码 → 4. 确认通过 → 5. 回归
 
 ## 验收标准
-- [ ] 具体可测试的条件
+| # | 验证步骤 | 通过标准 |
+|---|---|---|
+| AC-01 | ... | ... |
 
 关键规则：
 - 必须独立完整，execute 子代理只读这一个文件就能干活
 - 不要依赖其他 task-N.md 的内容
 - 接口定义写到"搬砖工照着做"的程度
+- 边界处理至少 5 条
+- 验收标准用表格，禁止笼统表述
 - 写完后用 Write tool 保存到文件
 \`\`\``
   }).join('\n\n')
 
+
   return {
     name: '生成任务蓝图（子代理并行）',
     prompt: `为 plan.md 中的每个任务生成独立蓝图文件。
@@ -293,7 +391,9 @@ ${subagentPrompts}
 
 ## 验收
 - 每个 task-N.md 文件存在且非空
-- 包含所有必要章节：修改文件、实现要求、接口定义、边界处理、TDD 步骤、验收标准`,
+- 包含 YAML frontmatter（id、title、priority、depends_on、blocks、allowed_paths）
+- 包含所有必要章节：修改文件、实现要求、接口定义、边界处理（≥5条）、非目标、TDD 步骤、验收标准（表格格式）
+- 边界处理覆盖：null/空值、兼容性、异常处理、参数不可变、歧义场景`,
     outputHint: '蓝图生成结果',
     optional: false
   }

package/src/stages/propose.js

@@ -65,39 +65,61 @@ export const definition = {
       name: '生成规范文件',
       prompt: `在 \`.sillyspec/changes/<变更名>/\` 下生成四个文件。
 
+### proposal.md 格式要求
+- **动机**：为什么做、解决什么核心问题
+- **关键问题**：为什么现有方案不够（展开 2-3 个具体痛点）
+- **变更范围**：本次做什么
+- **不在范围内**（显式清单）：不做 X、不做 Y
+- **成功标准**（可验证条件）：旧配置默认行为不变、新功能配置后可用
+
+### requirements.md 格式要求
+- **角色表**：涉及的角色和说明
+- **FR 编号需求**：FR-01、FR-02 ... 每条需求用 Given/When/Then 格式
+- **每个边界条件**独立 GWT 块
+- **非功能需求**：兼容性、可回退、可测试、可扩展
+
+### design.md 格式要求
+- **架构决策** + **文件变更清单表格** + **接口定义**
+- **兼容策略**（brownfield 必填）：未配置新功能时行为不变、回退路径
+- **风险登记**表格：编号/风险/等级/应对策略
+- **自审**：需求覆盖、真实性、YAGNI、非目标
+
+### tasks.md 格式要求
+- 任务列表（只列名称，不展开步骤）
+- 每个 task 附文件路径
+
 ### 操作
-1. 生成 proposal.md：动机、变更范围、不在范围内、成功标准
-2. 生成 requirements.md：功能需求、用户场景（Given/When/Then）、非功能需求
-3. 生成 design.md：架构决策、文件变更清单、数据模型、API 设计、代码风格参照
-4. 生成 tasks.md：任务列表（只列名称，不展开步骤）
+1. 生成 proposal.md
+2. 生成 requirements.md
+3. 生成 design.md
+4. 生成 tasks.md
 
 ### 输出
 四个文件路径
 
 ### 注意
-- 表名/字段名必须来自真实 schema 或标注"新增"
+- 表名/字段名/类名必须来自真实代码或标注"新增"
 - 用户场景必须用 Given/When/Then 格式
 - tasks.md 只列任务名，细节在 plan 阶段展开`,
-      outputHint: '四个文件路径',
-      optional: false
-    },
-    {
+
       name: '自检门控',
       prompt: `自检生成的规范文件。
 
 ### 操作
 检查以下各项：
-- [ ] proposal.md 有动机、变更范围、不在范围内、成功标准
+- [ ] proposal.md 有动机、关键问题、变更范围、不在范围内、成功标准
 - [ ] design.md 有文件变更清单表格
-- [ ] requirements.md 有 Given/When/Then 用户场景
+- [ ] design.md 有兼容策略（brownfield 时）
+- [ ] design.md 有风险登记表格
+- [ ] requirements.md 有角色表
+- [ ] requirements.md 有 FR 编号和 Given/When/Then 用户场景
 - [ ] tasks.md 每个 task 有文件路径
 
 任何不通过 → 修正后重新检查。
 
 ### 输出
 自检通过/不通过`,
-      outputHint: '自检结果',
-      optional: false
+
     },
     {
       name: '展示并更新进度',

package/src/stages/verify.js

@@ -145,18 +145,48 @@ grep -rl "<关键词>" <源码目录>/ --include="*.java" --include="*.js" --inc
     },
     {
       name: '输出验证报告',
-      prompt: `生成完整验证报告。
+      prompt: `生成完整验证报告，并写入 verification.md。
 
 ### 操作
 1. 汇总以上所有检查结果
-2. 给出结论：PASS / PASS WITH NOTES / FAIL
+2. 生成 verification.md 文件，保存到 \`.sillyspec/changes/<变更名>/verification.md\`
+3. 给出结论：PASS / PASS WITH NOTES / FAIL
+
+### verification.md 格式
+\`\`\`markdown
+# 验证报告
+
+## 结论
+PASS / PASS WITH NOTES / FAIL
+
+## 任务完成度
+（逐项检查任务的结果）
+
+## 设计一致性
+（对照 design.md 的检查结果）
+
+## 探针结果
+- 未实现标记扫描：...
+- 关键词覆盖：...
+- 测试覆盖：...
+
+## 测试结果
+（测试套件执行结果）
+
+## 技术债务
+（TODO/FIXME/HACK 统计）
+
+## 代码审查
+（问题列表 + 总体评价）
+\`\`\`
 
 ### 输出
-验证报告 markdown + 下一步命令
+verification.md 路径 + 验证报告摘要 + 下一步命令
 
 ### 注意
 - PASS → 运行 \`sillyspec run archive\` 归档
-- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证`,
+- FAIL → 修复后运行 \`sillyspec run verify\` 重新验证
+- verification.md 是变更包的正式验收记录，归档后保留`,
       outputHint: '验证报告',
       optional: false
     }