sillyspec 3.20.3 → 3.20.4

package/src/stages/archive.js

@@ -1,54 +1,160 @@
-export const definition = {
-  name: 'archive',
-  title: '归档变更',
-  description: '规范沉淀，可追溯',
-  auxiliary: true,
-  steps: [
-    {
-      name: '任务完成度检查',
-      prompt: `检查 tasks.md 中所有 checkbox 是否已勾选。
-
-### 操作
-1. 读取 \`.sillyspec/changes/<change-name>/tasks.md\`
-2. 检查所有 checkbox 是否已勾选
-3. 如有遗漏 → 询问用户是否继续归档
-
-### 输出
-完成度报告`,
-      outputHint: '完成度报告',
-      optional: false
-    },
-    {
-      name: '确认归档',
-      prompt: `展示即将归档的内容，请用户确认。
-
-### 操作
-1. 展示：变更目录名、包含的文件列表、生成总结
-2. 请用户确认是否执行归档
-3. 确认后：将 \`.sillyspec/changes/<change-name>/\` 移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
-4. 确保所有 checkbox 都已勾选
-
-### 输出
-归档确认`,
-      outputHint: '归档确认',
-      optional: false
-    },
-    {
-      name: '更新路线图和提交',
-      prompt: `更新路线图并暂存变更。
-
-### 操作
-1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
-2. \`git add .sillyspec/\` — **不要 commit**，由用户通过统一提交工具处理
-3. 更新 progress.json：
-   - 清除当前变更信息（归档后不再活跃）
-   - 如果是主变更（有 MASTER.md），标记所有阶段为 ✅，然后清除
-   - 历史记录追加时间 + 归档完成
-
-### 输出
-归档完成确认 + 累积规范统计`,
-      outputHint: '归档完成',
-      optional: false
-    }
-  ]
-}
+export const definition = {
+  name: 'archive',
+  title: '归档变更',
+  description: '规范沉淀，可追溯',
+  steps: [
+    {
+      name: '任务完成度检查',
+      prompt: `检查 plan.md 中所有任务 checkbox 是否已勾选（plan.md 是任务完成的唯一真相源）。
+
+### 操作
+1. 读取 \`.sillyspec/changes/<change-name>/plan.md\`
+2. 检查所有 \`- [x]\` checkbox 是否已勾选
+3. 如果 plan.md 不存在，回退读取 tasks.md 作为备选
+4. 如有遗漏 → **必须暂停等待用户决定**，不要自行判断"可以归档"
+   - 调用：\`sillyspec run archive --wait --reason "存在未完成任务，是否继续归档" --options "继续归档,回到execute完成剩余任务" --output "未完成任务列表"\`
+
+### 输出
+完成度报告（已勾选/总数 + 未完成任务列表）`,
+      outputHint: '完成度报告',
+      optional: false
+    },
+    {
+      name: 'extract-module-impact',
+      prompt: `按照 \`.sillyspec/workflows/archive-impact.yaml\` 中定义的 \`impact-analyzer\` 角色规则，分析本次变更影响的模块。
+
+### 操作
+1. 读取 \`.sillyspec/workflows/archive-impact.yaml\`，了解角色定义和检查规则
+2. 读取变更目录下的 proposal.md、design.md、tasks.md
+3. 运行 \`git diff --name-only HEAD~1\`（或 \`git diff --name-only --cached\`）获取真实修改文件列表
+4. 读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`
+   - **如果不存在**：提示"建议运行 scan 生成模块映射"，但继续执行。跳到步骤 7 生成只有 unmapped 部分的 module-impact.md
+5. 三重交叉验证：
+   - 声明范围：proposal.md / design.md 中的"变更范围"/"文件变更清单"
+   - 任务范围：tasks.md / plan.md 中的任务文件路径
+   - 真实变更：git diff 文件列表
+   - **以 git diff 为准**（真实 > 声明）
+6. 将 git diff 文件按 \`_module-map.yaml\` 的 paths glob 匹配到模块
+7. 生成模块影响矩阵：
+
+| 模块 | 影响类型 | 相关文件 | 更新内容摘要 | needs_review |
+|------|----------|----------|-------------|-------------|
+
+   影响类型：逻辑变更 / 数据结构变更 / 接口变更 / 调用关系变更 / 配置变更 / 新增
+   needs_review：如果影响无法完全确定，标记为 true
+
+8. 未匹配到任何模块的文件归入"未匹配文件"表格
+9. 生成 \`.sillyspec/changes/<change-name>/module-impact.md\`
+10. 完成后运行 workflow 检查：
+    \`node -e "import('./src/workflow.js').then(w => { /* 用 loadWorkflow 加载 archive-impact，用 runPostCheck 检查 */ })\``,
+      outputHint: 'module-impact.md 路径 + 影响摘要',
+      optional: false
+    },
+    {
+      name: 'sync-module-docs',
+      prompt: `根据 module-impact.md 同步更新模块索引和卡片文档。
+
+### ⚠️ 核心原则：结构化事实改 _module-map.yaml，语义解释改模块卡片
+- \`_module-map.yaml\` 是唯一的结构化索引源（paths/tags/entrypoints/depends_on/used_by/status/needs_review）
+- 模块卡片只负责语义说明（定位/契约摘要/关键逻辑/注意事项/人工备注）
+- 一个信息只维护一次，不要两边重复
+
+### 操作
+1. 读取 \`.sillyspec/changes/<change-name>/module-impact.md\`
+2. 如果没有受影响模块（只有 unmapped）→ 提示用户，跳过同步
+3. 对每个受影响模块，按影响类型分别更新：
+
+#### 更新 _module-map.yaml 的规则
+- **路径变化** → 更新对应模块的 paths
+- **依赖变化** → 更新 depends_on / used_by（同时更新反向模块的 used_by / depends_on）
+- **导出符号变化** → 更新 entrypoints / main_symbols
+- **新增模块** → 添加完整条目
+- **模块废弃** → status: deprecated
+- **不确定的影响** → needs_review: true, review_reasons 追加原因
+- 如果 _module-map.yaml 的 generated_at 已过时，更新为当前时间
+
+#### 更新模块卡片（modules/<module-id>.md）的规则
+- **契约语义变化**（新增/删除对外能力） → 更新"契约摘要"
+- **关键逻辑变化** → 更新"关键逻辑"
+- **边界变化**（模块职责扩大/缩小） → 更新"定位"
+- **注意事项变化** → 更新"注意事项"
+- **内部实现变化**（不影响对外接口） → 通常不更新卡片
+- **人工备注** → 永远保护，不覆盖
+
+#### 人工备注保护
+1. 用正则提取 \`<!-- MANUAL_NOTES_START -->\` 到 \`<!-- MANUAL_NOTES_END -->\` 之间的内容
+2. 生成新卡片后，原样回填到人工备注区域
+3. 如果标记缺失或重复 → 在 _module-map.yaml 中标记 needs_review: true
+
+#### 新建模块卡片模板
+\`\`\`markdown
+---
+schema_version: 1
+doc_type: module-card
+module_id: <module-id>
+---
+
+# <module-id>
+
+## 定位
+
+## 契约摘要
+
+## 关键逻辑
+
+## 注意事项
+
+## 人工备注
+
+<!-- MANUAL_NOTES_START -->
+
+<!-- MANUAL_NOTES_END -->
+\`\`\`
+
+4. 展示所有更新内容（diff 摘要），**必须暂停等待用户确认**
+   - 调用：\`sillyspec run archive --wait --reason "等待用户确认模块文档同步" --options "确认写入,跳过同步" --output "diff 摘要"\`
+5. **只有用户通过 --continue --answer "确认写入" 后才写入文件**
+   - 写入 _module-map.yaml 和受影响的模块卡片
+6. 用户拒绝时，不写入，但提示"module-impact.md 已保留，可稍后手动同步"
+7. 回填 module-impact.md 的"更新结果"表格，区分目标：
+   - 目标列写 "\`_module-map.yaml: <module-id>\`" 或 "\`modules/<module-id>.md\`"
+8. **同步完成后**，运行 \`sillyspec modules rebuild\` 刷新索引（如果需要），或手动更新 dependencies.md
+
+### 输出
+已更新的文件路径列表 + 用户确认状态`,
+      outputHint: '模块文档更新结果',
+      optional: false
+    },
+    {
+      name: '确认归档',
+      prompt: `确认归档内容，由 CLI 执行目录移动。
+
+### 操作
+1. 展示：变更目录名、包含的文件列表（含 module-impact.md）、生成总结
+2. 确保所有 checkbox 都已勾选
+3. 让用户确认后，用 \`--confirm\` 完成本步骤：
+   \`sillyspec run archive --done --confirm --output "确认归档"\`
+4. CLI 会创建 \`.sillyspec/changes/archive/\`，并将变更目录移动到 \`.sillyspec/changes/archive/YYYY-MM-DD-<change-name>/\`
+
+### 输出
+归档完成 + archive 目录路径`,
+      outputHint: '归档确认',
+      optional: false
+    },
+    {
+      name: '更新路线图和提交',
+      prompt: `更新路线图并暂存变更。
+
+### 操作
+1. 如果 \`.sillyspec/ROADMAP.md\` 存在，标记对应 Phase 为已完成
+2. \`git add .sillyspec/changes/\` — 暂存归档结果（不要 commit，由用户通过统一提交工具处理）
+3. \`git add .sillyspec/docs/\` — 暂存模块文档更新（如有）
+4. 确认 sillyspec.db 中该变更已不再 active（确认归档步骤由 CLI 调用 unregisterChange）
+
+### 输出
+归档完成确认 + 累积规范统计`,
+      outputHint: '归档完成',
+      optional: false
+    }
+  ]
+}

package/src/stages/brainstorm-auto.js

@@ -0,0 +1,229 @@
+/**
+ * brainstorm-auto.js — auto/full 模式使用的 brainstorm 步骤定义
+ *
+ * 与 brainstorm.js 的区别：
+ * 1. artifact-first：直接写文件，对话只输出摘要
+ * 2. 自动决策：基于 AC-001~AC-010 checklist，不频繁请示
+ * 3. next-action.json：结构化产物，驱动下游推进
+ * 4. 只有 blocking questions 才 wait 用户
+ * 5. 步骤从 ~13 步精简为 4 步
+ */
+
+export const definition = {
+  name: 'brainstorm',
+  title: '头脑风暴（自动模式）',
+  description: '探索需求、分析技术方案、识别风险 — artifact-first，自动决策优先',
+
+  steps: [
+    {
+      name: '状态检查与上下文加载',
+      prompt: `检查状态、加载项目上下文、匹配模块。
+
+### 操作
+1. 运行 \`sillyspec progress show\`，确认 currentStage 为 "brainstorm"
+2. 如果未初始化，提示先运行 sillyspec init
+3. **检查变更名称**：如果当前变更名是自动生成的（如 \`2026-06-02-new-change\`），直接重命名为有意义名称，然后运行 \`sillyspec change-rename <旧名> <新名>\`
+
+### 加载上下文
+4. 读取 CODEBASE-OVERVIEW.md + 共享规范 + 子项目上下文
+5. 加载项目信息：\`cat .sillyspec/projects/*.yaml 2>/dev/null\`
+6. 加载本地配置：\`cat .sillyspec/local.yaml 2>/dev/null\`
+7. 棕地项目：读取 scan 下的 STRUCTURE.md、CONVENTIONS.md、ARCHITECTURE.md
+8. 加载模块索引：读取 \`.sillyspec/docs/<project>/modules/_module-map.yaml\`（如存在）
+9. 查看进行中的变更：\`ls .sillyspec/changes/ | grep -v archive\`
+10. 检查同名变更或可复用模板
+
+### 模块匹配
+根据用户描述的需求关键词，匹配相关模块（用 _module-map.yaml 的 tags/aliases/paths）。
+
+### 子项目判定
+- 单项目：直接确认
+- 多项目且用户已指定：直接确认
+- 多项目且用户未指定：列出项目列表，需要用户确认
+
+### 如果有用户提供的原型/截图
+分析提取：页面结构、表单字段、交互流程、业务规则。
+
+### 输出
+状态摘要 + 项目现状理解（3-5 句）+ 涉及模块列表 + 子项目 + 原型分析（如有）
+
+### 注意
+- 以 CLI 返回为准，不要自行推断阶段
+- 不要用 mv 命令重命名变更目录，必须用 \`sillyspec change-rename\``,
+      outputHint: '状态摘要 + 上下文 + 模块匹配',
+      optional: false
+    },
+    {
+      name: '需求分析与方案设计',
+      requiresWait: true,
+      repeatableWait: true,
+      maxWaitRounds: 5,
+      waitReason: '等待用户回答需求问题',
+      waitOptions: ['回答见--answer', '信息够了，进入设计'],
+      prompt: `分析需求，必要时追问，然后设计方案。
+
+### 操作
+
+#### A. 需求评估
+1. 汇总上一步加载的上下文和用户需求
+2. 判断需求是否清晰：
+   - 目标明确、范围清楚、无歧义 → 跳过追问，直接进入方案设计
+   - 有歧义或不清楚 → 挑**一个最关键的**问题追问
+
+#### B. 追问规则（只在需要时）
+- 一次只问一个问题，不要一次性列出多个问题
+- 能从代码/文档确认的不要问用户
+- 多选题优于开放式问题
+- YAGNI — 砍掉不需要的功能
+- 2-3 轮问答就应进入方案设计
+- 优先追问影响架构/数据/接口的问题，实现细节不要问
+
+**如果需要追问：**调用 \`sillyspec run brainstorm --wait --reason "等待用户回答需求问题" --options "回答见--answer,信息够了,进入设计" --output "你的单个问题"\`
+
+#### C. 复杂度评估（追问结束后或不需要追问时）
+1. 判断是否需要拆分或走批量模式：
+   - 3+ 个可独立交付的功能模块 → 建议拆分
+   - 任务 > 10 且有重复模式 → 建议批量模式
+   - 简单 CRUD → 不拆
+2. 如果需要拆分/批量模式：暂停等用户确认
+   - 调用：\`sillyspec run brainstorm --wait --reason "等待用户确认拆分方案" --options "同意拆分,不需要拆分,走批量模式" --output "拆分方案摘要"\`
+3. 不需要拆分 → 继续
+
+#### D. 方案设计（自动决策优先）
+1. 基于需求理解和上下文，提出 1-3 种实现方案
+2. **使用自动决策 checklist（AC-001~AC-010）判断是否需要用户选择：**
+
+\`\`\`
+AC-001: 未修改公共 API
+AC-002: 未修改数据库 schema
+AC-003: 未涉及鉴权/权限
+AC-004: 未扩大 allowed_paths
+AC-005: 未引入新外部依赖
+AC-006: 未修改核心模块（workflow/daemon/session/lifecycle）
+AC-007: 已有项目约定可复用
+AC-008: 不影响向后兼容
+AC-009: 不涉及数据迁移
+AC-010: 单模块范围内可完成
+\`\`\`
+
+3. **自动决策判定：**
+   - 只有一个明显合理方案 + checklist 全部 ✅ → **自动选择，标记 AUTO_DECIDED**
+   - 有多个方案但影响不大（checklist 全部 ✅）→ **自动选推荐方案，标记 AUTO_DECIDED**
+   - 有多个方案且 checklist 有 ❌（影响架构/数据/接口/权限/兼容性）→ **只有这一种情况才暂停等用户选择**
+
+4. 如果需要用户选择方案：
+   - 调用：\`sillyspec run brainstorm --wait --reason "等待用户选择方案" --options "方案A,方案B,方案C" --output "方案对比摘要"\`
+
+#### E. Design Grill（轻量交叉审查）
+对方案做快速交叉审查：
+- 检查方案与 ARCHITECTURE.md / CONVENTIONS.md 的一致性
+- 检查是否有术语歧义、边界遗漏
+- 能自动解决的直接修正，只有需要业务判断的才问用户
+- 跳过条件：单模块、无状态流转、< 3 个文件变更
+
+### 输出
+需求理解摘要 + 复杂度评估 + 方案决策（AUTO_DECIDED 或用户选择）
+
+### 注意
+- **不要自问自答。** 不要在自己输出中模拟用户回答然后说"需求已明确"
+- checklist 判定结果必须在 decisions.md 中记录依据`,
+      outputHint: '需求理解 + 方案决策',
+      optional: false
+    },
+    {
+      name: '生成设计产物',
+      prompt: `将设计方案写入文件（artifact-first），不回显正文。
+
+### 操作
+1. 确保变更目录存在：\`mkdir -p .sillyspec/changes/<change-name>/brainstorm\`
+2. **直接将设计方案写入文件，不要先在对话中输出完整内容再写文件。**
+
+### 产物文件
+
+#### design.md（必填，写入 \`brainstorm/design.md\`）
+包含：背景、设计目标、非目标、总体方案、文件变更清单、接口定义、数据模型（如涉及）、兼容策略（brownfield）、风险登记、决策追踪。
+
+#### decisions.md（必填，写入 \`brainstorm/decisions.md\`）
+记录所有决策：
+\`\`\`markdown
+## D-001@v1: 决策短标题
+- type: architecture | boundary | compatibility | ...
+- priority: P0 | P1 | P2
+- status: AUTO_DECIDED | NEEDS_REVIEW | USER_DECIDED
+- source: user | code | docs
+- question: 被解决的问题
+- answer: 选择或结论
+- checklist: AC-001 ✅, AC-007 ✅（AUTO_DECIDED 时必须列出）
+- normalized_requirement: 可测试约束
+- impacts: [FR-01, task-01]
+- evidence: 代码/文档路径或用户回答轮次
+\`\`\`
+
+#### gaps.md（必填，写入 \`brainstorm/gaps.md\`）
+记录已识别的缺口。status=BLOCKER 的缺口会在 plan-postcheck 中触发回退。
+
+#### assumptions.md（必填，写入 \`brainstorm/assumptions.md\`）
+记录隐含假设和验证方法。
+
+#### next-action.json（必填，写入 \`brainstorm/next-action.json\`）
+\`\`\`json
+{
+  "status": "ready_for_plan" | "waiting_for_user",
+  "decision_level": "high" | "medium" | "low",
+  "has_blocking_questions": true | false,
+  "blocking_reasons": [],
+  "questions": [],
+  "auto_decisions": [
+    { "id": "D-001", "decision": "方案描述", "reason": "AC-007 ✅" }
+  ]
+}
+\`\`\`
+
+### 自审
+对 design.md 执行自审（需求覆盖、文件变更清单具体性、验收标准可测试、非目标清晰、兼容策略）。发现问题直接修改文件。
+
+### 如果有 blocking questions
+将问题写入 next-action.json.questions，在对话中输出问题列表和推荐选项，然后 --wait。
+
+### 输出（artifact-first）
+只输出摘要：
+\`\`\`
+已生成设计产物（5 个文件）：
+- brainstorm/design.md — 采用 xxx 方案，涉及 N 个文件变更
+- brainstorm/decisions.md — M 个决策，K 个 AUTO_DECIDED
+- brainstorm/gaps.md — J 个缺口，0 个 BLOCKER
+- brainstorm/assumptions.md — L 个假设
+- brainstorm/next-action.json — ready_for_plan / waiting_for_user
+\`\`\``,
+      outputHint: '产物摘要',
+      optional: false
+    },
+    {
+      name: '生成规范文件',
+      requiresWait: true,
+      waitReason: '等待用户最终确认',
+      waitOptions: ['确认', '需要修改', '推翻重来'],
+      prompt: `生成 proposal.md / requirements.md / tasks.md，让用户确认。
+
+### 操作
+1. 基于 brainstorm/ 下的设计产物，生成规范文件（直接写文件）：
+   - **proposal.md**：动机、关键问题、变更范围、不在范围内、成功标准
+   - **requirements.md**：角色表 + FR 编号需求 + Given/When/Then + 非功能需求
+   - **tasks.md**：任务列表（只列名称，细节在 plan 阶段展开）
+2. 如果 brainstorm/decisions.md 有 AUTO_DECIDED 决策，在变更根目录也写一份 decisions.md
+3. 所有规范文件头部包含 YAML frontmatter
+4. \`git add .sillyspec/\` — 暂存规范文件（不要 commit）
+
+### 输出（摘要）
+规范文件路径列表（各一句话说明）
+
+### 铁律
+- **直接写文件，不在对话中输出完整内容**
+- 暂停等待用户确认：\`sillyspec run brainstorm --wait --reason "等待用户最终确认" --options "确认,需要修改,推翻重来" --output "规范文件摘要"\`
+- 禁止自动 commit
+- 禁止在确认前推进到后续阶段`,
+      outputHint: '规范文件摘要',
+      optional: false
+    }
+  ]
+}