@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md

@@ -3,71 +3,104 @@ id: specdev/archive-and-consolidate
 type: workflow-entry
 workflow: specdev
 name: 归档与沉淀
-description: 将已完成变更归档至 archive/，并智能评估、提取持久化知识到 adr/、context/、research/ 知识库——与现有知识逐项比对，执行创建/更新/合并/废弃，确保知识始终最新。
-keywords: [归档, 沉淀, 知识持久化, 清理, ADR, 词汇表, 研究]
+description: 在验证完成和用户授权后归档 change，并以证据判断哪些架构决策、术语和研究应创建、合并、替代、废弃或不提升。
+keywords: [归档, consolidation, ADR, context, research, knowledge]
 ---
 
 # 归档与沉淀
 
-将 `changes/` 中已完成的变更归档至 `archive/`，同时从变更产物中提取可毕业知识，与现有 `<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>`、`<Path>{roots.state}/specdev/research/</Path>` 知识库智能比对后合并写入。**不是只增不减**——每次运行均评估现有知识是否需要更新、合并或废弃。
+归档不是把整个 change 无差别复制到永久知识库。永久知识只保存“当前仍真实、超出单个 change 仍有用、已有实现证据”的结论，同时保留历史和 supersedes 关系。
 
-产物写入 `<Path>{roots.state}/specdev/</Path>` 下的 adr/、context/、research/、archive/。默认 dry-run 模式，确认后方执行。
+## 输入
+
+- change 根：`<Path>{roots.state}/specdev/changes/{change}/</Path>`
+- change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
+- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 当前 Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- 当前 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- Evidence：`<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
 
 ## 流程
 
-### 1. 加载上下文与状态
+### 1. 完成检查
 
-读取 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 和 `<Path>{roots.state}/specdev/status.json</Path>`，枚举现有知识库全部内容：adr/ 中所有 `NNNN-slug.md`、context/ 中所有术语定义、research/ 中现有研究及 index.md。
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>`，检查 Ticket、Evidence、Spec 合同、Goal Gate、偏差、迁移、状态和用户授权。
 
-**完成标准**：所有知识库现有内容已索引；status.json 已解析；changes/ 目录已枚举。
+未完成、验证失败、存在未批准 deviation 或用户未授权时停止，不得标 completed 或 archived。
 
-### 2. 扫描已完成变更
+### 2. 冻结归档快照
 
-遍历 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组，筛选 `result: "completed"` 的 change；同时遍历 `<Path>{roots.state}/specdev/changes/</Path>`，读取每个变更的 `.status.json` 作为补充（`change_status: completed`）。收集每个已完成变更的 ADR.md、CONTEXT.md、LOG.md 及 research/ 子目录产物。
+记录：
 
-**完成标准**：每个已完成变更的元数据和知识产物已收集；无可读产物的变更已标注原因。
+- 归档时间；
+- 最终基线、提交或 PR；
+- 全局验证摘要；
+- 已知残余风险；
+- 被批准的 cancelled/deferred 条目；
+- 归档目标 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
 
-### 3. 知识评估与鉴别
+归档前不得删除设计日志、Evidence 或被替代 ADR。
 
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/discrimination-guide.md</Path>`。将步骤 2 收集的知识与步骤 1 索引的现有知识逐项比对，标注处置动作：create / update / merge / supersede / retire / skip。冲突项标记 needs-confirmation 并展示双方版本与建议。
+### 3. 评估长期知识
 
-**完成标准**：每个提取的知识项已标注处置动作和理由；冲突项已展示双方版本及推荐方案。
+加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md</Path>`，逐条评估当前 change 的架构决策、领域术语和研究结论。
 
-### 4. 生成归档计划
+每条结论执行：`create | update | merge | supersede | deprecate | skip`。无法判断当前真相时不提升，创建治理问题或新 change。
 
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-rules.md</Path>`。对每个已完成变更执行预检（名称格式、状态可解析、源存在、目标不冲突），生成 `changes/ → archive/YYYY-MM/` 移动计划，批量原子性检查。
+### 4. 提升与冲突处理
 
-**完成标准**：归档计划表已生成，每项标注 ready/blocked 及原因；整批原子性已验证。
+- 架构决策提升到 `<Path>{roots.state}/specdev/adr/</Path>`；
+- 领域术语提升到 `<Path>{roots.state}/specdev/context/</Path>`；
+- 经实现验证、长期有效的研究提升到 `<Path>{roots.state}/specdev/research/</Path>`；
+- 冲突 ADR 建立 supersedes 双向引用，不静默覆盖；
+- 历史结论保留状态和来源，不通过删除历史制造一致性。
 
-### 5. 生成知识沉淀计划
+### 5. 移动归档并更新状态
 
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-rules.md</Path>` 和 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-graduation.md</Path>`。基于步骤 3 鉴别结果，生成 adr/、context/、research/ 的创建/更新/废弃计划。
+将 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 移动到 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`。
 
-**完成标准**：三个知识库的写入计划已生成；未毕业知识标注保留在归档变更中的位置；冲突项已标注。
+更新 `<Path>{roots.state}/specdev/status.json</Path>`：从 active 移除，追加 completed/archived 记录；归档内 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>` 写入完成时间、归档路径和 promotion 摘要。
 
-### 6. 生成清理计划
+任何删除、移动或 Git 副作用均需用户授权。
 
-加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/cleanup-rules.md</Path>`。扫描现有知识库，识别陈旧、重复、格式违规内容，生成清理候选表（delete / merge / rewrite / keep / needs-confirmation）。
+### 6. 校验与汇报
 
-**完成标准**：清理候选表已生成，每项标注分类、理由和风险等级。
+运行包级和归档链接检查，确认：
 
-### 7. 呈现报告并等待确认
+- 归档路径存在；
+- 全局状态与归档状态一致；
+- 永久知识引用有效；
+- supersedes 链无断裂；
+- 无敏感信息进入永久知识。
 
-合并步骤 4-6 为统一报告。明确标注所有破坏性操作（移动、删除、覆写）。逐项展示冲突和待确认条目。**默认不修改任何文件**，等待用户逐项确认后进入执行。
+输出 promotion report：每条候选知识、执行动作、目标路径、证据和未提升原因。
 
-**完成标准**：报告已呈现；所有破坏性操作已标注；等待用户确认。
+## 禁止
 
-## 子文件引用
+- 未完成或验证失败的 change 标 completed；
+- 把临时实现细节、一次性命令或未经验证假设提升为永久知识；
+- 静默覆盖冲突 ADR；
+- 删除历史以制造一致性；
+- 在归档或永久知识中写入秘密、令牌、敏感日志或个人隐私；
+- 未经用户授权移动、删除、提交或推送。
 
-| 文件 | 触发条件 |
-|------|----------|
-| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/discrimination-guide.md</Path>` | 进入步骤 3「知识评估与鉴别」时加载——智能比对四步法、六种处置动作判定规则、冲突标注格式 |
-| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-rules.md</Path>` | 进入步骤 4「生成归档计划」时加载——预检清单、批量原子性规则、移动与验证规程 |
-| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-rules.md</Path>` | 进入步骤 5「生成知识沉淀计划」时加载——adr/context/research 三库的写入规则、合并策略、保护规则 |
-| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-graduation.md</Path>` | 进入步骤 5「生成知识沉淀计划」时加载——三文件模型毕业标准、反毕业条件、知识类型到知识库的映射 |
-| `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/cleanup-rules.md</Path>` | 进入步骤 6「生成清理计划」时加载——五种清理分类、反模式扫描规则、保护规则 |
+## 完成标准
 
-## 依赖关系
+- `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>` 全部适用项通过；
+- change 已移动到 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>`；
+- 全局和归档状态一致；
+- 长期知识已按证据处理；
+- promotion report 已向用户汇报；
+- 无未批准副作用。
+
+## 子文件引用
 
-- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 定义的 ADR/CONTEXT/LOG 三文件格式规范
-- 依赖 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 的持久化约定表
+- 归档检查：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/archive-checklist.md</Path>`
+- 知识提升规则：`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md</Path>`

package/template/workflows/specdev/A-archive-and-consolidate/archive-checklist.md

@@ -0,0 +1,15 @@
+# 归档检查
+
+本清单由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 使用。
+
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` 内计划 Ticket 均为 `done` 或有批准理由的 `cancelled`。
+- [ ] 每个 `done` Ticket 都有 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的 AC/合同已覆盖，无未批准 deviation。
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 中适用 Gate 已关闭。
+- [ ] 项目级验证通过，或已有明确接受的既有/环境失败记录。
+- [ ] 迁移、兼容、监控、回滚和不可逆操作已完成或明确移交。
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`、Ticket、Evidence 和状态一致。
+- [ ] 校验器无 error。
+- [ ] 永久知识候选均有来源、范围和实现证据。
+- [ ] 敏感值扫描通过。
+- [ ] 用户已授权归档及需要的移动、Git 或外部副作用。

package/template/workflows/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md

@@ -0,0 +1,32 @@
+# 知识提升规则
+
+本规则由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 使用，并遵循 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
+
+## 资格
+
+永久知识必须同时满足：
+
+- 当前代码或实际行为已有验证支持；
+- 超出单个 change 仍有用；
+- 有明确来源、适用范围和状态；
+- 不只是计划、假设、一次性操作记录或临时 workaround；
+- 与现有永久知识的关系已判断。
+
+## 操作
+
+- **create**：没有等价条目；
+- **update**：同一决策或术语的非语义性补充；
+- **merge**：多个条目表达同一当前真相，保留全部来源；
+- **supersede**：新决策替代旧决策，建立双向引用；
+- **deprecate**：不再推荐但仍需历史或兼容说明；
+- **skip**：临时、局部、未经验证、已过期或不具长期价值。
+
+## 目标
+
+- 架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 研究结论：`<Path>{roots.state}/specdev/research/</Path>`
+
+## 冲突
+
+无法确定哪条代表当前真相时不提升。创建治理问题或新 change，并保留冲突来源。永久知识库必须反映当前状态，同时保存历史关系，而不是把冲突藏起来。

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -2,86 +2,86 @@
 id: specdev/diagnose-bugs
 type: workflow-entry
 workflow: specdev
-name: 诊断
-description: 针对疑难 bug 建立诊断循环——构建紧凑反馈回路、复现最小化、可证伪假设排名、插桩定位根因，确认后移交 I-implement 修复。
-keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
+name: 诊断 Bug
+description: 通过复现、反馈回路、可证伪假设与最小插桩定位根因，输出修复契约而不是猜测性补丁。
+keywords: [bug, 诊断, 根因, 复现, 假设]
 ---
 
-# 诊断
+# 诊断 Bug
 
-针对疑难 bug 的诊断规程。先建立紧凑的反馈回路锚定症状，再通过可证伪假设排名定位根因，确认后移交 I-implement 执行修复。仅在明确有理由时才跳过阶段。
+诊断阶段默认只读项目代码；可以在当前 change 内创建诊断记录，并进行临时、可撤销的本地实验。未经用户授权，不提交修复、不部署、不执行不可逆操作。
 
-在开始诊断之前，读取当前变更的上下文与架构决策：
+## 输入与产物
 
-- **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
-- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-
-如果这些文件不存在，静默继续——诊断不依赖设计文档，缺失的 change 在需要记录结论时按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议创建。需要建立完整设计上下文时，运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`。
+- 原始请求：`<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
+- 分诊结果：`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 诊断产物：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 诊断模板：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>`
 
 ## 流程
 
-### 1. 加载上下文
-
-读取 `<Path>{roots.state}/specdev/status.json</Path>` 确认活跃变更。读取 CONTEXT.md 获取领域词汇表——使用其中已定义的术语。读取 ADR.md 了解已做出的架构决策——诊断过程中涉及的模块若与已有 ADR 相关，在假设中引用。
+### 1. 建立最短反馈回路
 
-**完成标准**：活跃变更已确认，领域词汇表和架构决策已加载。`{change}` 已确定。
+定义最短复现命令、输入、环境、期望、实际、复现率和观测位置。不能稳定复现时，先缩小观测范围、记录环境差异或建立最小探针，不直接修改业务逻辑。
 
-若诊断过程中遇到不熟悉的第三方库行为、API 语义、运行时特性或工具链细节，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成一手来源调查，再继续构建回路。
+### 2. 收集事实
 
-### 2. 构建反馈回路
+读取相关日志、调用链、测试、配置、版本差异、最近变更、运行环境和相邻成功路径。所有条目标注为事实、推断或用户报告；不得把日志缺失当作行为不存在。
 
-委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop-techniques.md</Path>`。构建一个紧凑的通过/失败信号——一条命令，确定性、秒级、agent 可无人值守运行。在此投入不成比例的精力：反馈回路是诊断的超能力。如果确实无法构建回路，向用户明确说明已尝试的方法并请求访问复现环境或捕获产物。
+外部依赖、版本行为或协议不清楚时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-**完成标准**：反馈回路紧凑且具备变红能力——一条命令已运行并通过/失败输出验证，确定性、秒级、agent 可运行。回路断言的是用户的确切症状，而非"运行不出错"。
+### 3. 假设排名
 
-### 3. 复现与最小化
+列出 3–7 个可证伪假设，按“证据支持度 × 解释范围 ÷ 验证成本”排序。每个假设必须说明：
 
-运行回路，确认它产生用户描述的故障模式。然后逐元素削减输入、调用者、配置和数据——每次削减后重新运行回路——只保留对故障有负载作用的部分。
+- 支持证据；
+- 预期可观察结果；
+- 反证实验；
+- 若被证伪，下一个候选是什么。
 
-**完成标准**：回路已复现用户症状。复现场景已最小化——每个剩余元素都有负载作用，移除任何一个都会使回路变绿。
+### 4. 最小实验
 
-### 4. 提出诊断计划
+一次只改变一个变量。优先使用定向测试、断言、日志、追踪、调试器、配置切换或隔离环境。插桩必须可移除，不得把诊断日志、永久重试或吞错当作修复。
 
-委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-format.md</Path>`。生成 3-5 个排名假设，每个假设必须是可证伪的——陈述其预测。将排名列表作为诊断计划呈现给用户确认。用户可能拥有立即重排名的领域知识。如果用户 AFK，按排名继续。
+### 5. 根因确认
 
-**完成标准**：3-5 个可证伪假设已排名并作为诊断计划呈现给用户。用户已确认或 AFK 下按排名继续。
+根因必须同时解释：
 
-### 5. 插桩验证
+- 触发条件；
+- 失败机制；
+- 为什么此前未被测试或监控捕获；
+- 影响范围；
+- 为什么拟议修复能阻断机制；
+- 修复可能引入的回归风险。
 
-委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/instrumentation-rules.md</Path>`。每个探测映射到诊断计划中的一个具体预测。每次只改变一个变量。使用调试器/REPL 优先于日志。所有调试日志使用 `[DEBUG-xxxx]` 唯一前缀标记。
+只能缓解症状时明确标注 workaround，不宣称根因已确认。
 
-**完成标准**：根因已通过插桩确认——某个假设的预测已验证，其他假设已排除。所有探测结果与诊断计划中的预测对应。
+### 6. 写入修复契约
 
-### 6. 移交修复
+使用 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`，包含根因、受影响范围、修复不变量、回归测试、非目标、风险和回滚。
 
-调用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行修复。移交以下信息：
+修复前回归测试应失败，修复后应通过。诊断产物不夹带未经批准的实现。
 
-- **根因描述**——哪个假设被确认，通过什么探测验证
-- **最小复现场景**——阶段 3 产出的最小化复现，可直接转为回归测试
-- **建议的修复接缝**——在哪个模块/接口处修复最合适
+### 7. 发布诊断
 
-修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试接缝，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
+同步 `<Path>{roots.state}/specdev/status.json</Path>` 的 `current_work`、`work_history` 和当前 change 状态，返回 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`、状态及下一 Work 的完整路径。
 
-**完成标准**：I-implement 已启动，根因描述、最小复现、建议修复接缝已移交。
+- 单一、局部、低风险且契约完全明确：可进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 生成 Lite/Standard Ticket，或在用户批准后由 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 使用 Direct Spec 模式；
+- 多行为、公共接口、迁移、安全或高风险：进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 或 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
+- 根因仍未知：保持 blocked，继续诊断或进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。
 
-### 7. 清理与复盘
+## 完成标准
 
-委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/cleanup-postmortem.md</Path>`。移除所有 `[DEBUG-xxxx]` 标记的插桩代码，删除一次性原型。在 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 中记录：被证实的假设、根因、修复提交。执行事后分析——什么本可以预防这个 bug？如果涉及架构变更，提出改进建议。
-
-**完成标准**：调试产物已清理（grep `[DEBUG-` 无残留），根因已记录到 LOG.md，预防建议已提出。
-
----
+- 有可重复复现，或明确说明为何暂时无法复现；
+- 根因有证据和反证过程；
+- 回归测试契约在修复前应失败；
+- 诊断产物区分根因、workaround 和残余未知；
+- 修复契约决策完备；
+- 状态、诊断路径和下一 Work 路径已返回；
+- 未在诊断阶段偷偷提交修复。
 
 ## 子文件引用
 
-| 文件 | 内容 | 触发条件 |
-|------|------|---------|
-| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop-techniques.md</Path>` | 10 种反馈回路构建技术、收紧回路、非确定性 bug 策略、无法构建回路时的升级路径、最小化协议 | 步骤 2「构建反馈回路」和步骤 3「复现与最小化」进入时 |
-| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-format.md</Path>` | 可证伪假设格式模板、排名规则、用户 Plan 呈现模板、AFK 默认行为 | 步骤 4「提出诊断计划」进入时 |
-| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/instrumentation-rules.md</Path>` | 探测映射规则、工具偏好、`[DEBUG-xxxx]` 标记约定、性能分支处理 | 步骤 5「插桩验证」进入时 |
-| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/cleanup-postmortem.md</Path>` | 清理检查清单、事后分析问题、预防建议记录格式 | 步骤 7「清理与复盘」进入时 |
-
-## 依赖关系
-
-- 依赖 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行修复——步骤 6 移交已确认的根因和最小复现
-- 依赖 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 提供领域上下文——步骤 1 加载
+- 诊断模板：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>`

package/template/workflows/specdev/D-diagnose-bugs/diagnosis-template.md

@@ -0,0 +1,64 @@
+# Diagnosis: <问题>
+
+- **Change：** `<change>`
+- **来源：** `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>` / `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- **诊断状态：** gathering / reproducing / testing-hypotheses / root-cause-confirmed / blocked
+- **诊断工件：** `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+
+## 1. 现象与影响
+
+只记录可观察现象、受影响对象、严重度和时间范围；把解释留到假设部分。
+
+## 2. 复现契约
+
+- **环境：** 版本、配置、数据前置条件
+- **输入/步骤：** 最小稳定复现路径
+- **期望：** 来自契约、测试或已确认行为
+- **实际：** 可观察输出
+- **复现率：**
+- **对照组：** 能正常工作的最接近路径
+- **相关路径：** `<Path>src/example.ts</Path>` / 无
+
+## 3. 证据时间线
+
+| 时间/阶段 | 观察 | 来源 | 可信度 |
+|---|---|---|---|
+| ... | ... | 日志、测试、代码、配置或用户报告 | high / medium / low |
+
+## 4. 假设与证伪
+
+| 排名 | 可证伪假设 | 支持证据 | 区分性实验 | 预期反证 | 结果 |
+|---|---|---|---|---|---|
+| 1 | ... | ... | ... | ... | confirmed / rejected / pending |
+
+每个实验应尽量只区分一个机制。插桩、日志或临时探针必须记录撤销方式，不能成为无主永久代码。
+
+## 5. 已确认根因
+
+- **触发条件：**
+- **失败机制：** 从输入到错误结果的因果链
+- **根因位置：** `<Path>src/example.ts</Path>`
+- **为何不是其他候选：**
+- **漏检原因：** 测试、监控、契约或流程缺口
+- **确认实验：** 能稳定使问题出现和消失的最小变化
+
+根因未确认时不得把“最可能”写成结论，也不得直接把 change 标记为实现就绪。
+
+## 6. 修复契约
+
+- **必须改变：**
+- **必须保持：** 不变量、兼容性和无关行为
+- **回归测试：** 能在旧实现失败、修复后通过的验证
+- **防复发措施：** 测试、监控、断言或治理修正
+- **OUT：** 本次明确不处理的相邻问题
+- **风险与回滚：**
+- **推荐下游：** S-spec / T-tickets / I-implement / R-review-architecture
+
+## 7. 诊断完成门禁
+
+- [ ] 复现或无法复现的边界已明确；
+- [ ] 根因由区分性证据支持；
+- [ ] 症状、触发条件与失败机制没有混为一谈；
+- [ ] 回归验证可执行；
+- [ ] 修复边界与必须保持项明确；
+- [ ] 未撤销的临时插桩为零，或已登记 owner 与后续删除条件。