@namewta/speculo 0.1.20 → 0.2.0

package/template/workflows/dev/H-diagnose/diagnose-guide.md

@@ -1,144 +0,0 @@
-# 诊断
-
-针对疑难 Bug 和性能回退的纪律化诊断循环。复现 -> 最小化 -> 假设 -> 插桩 -> 修复 -> 回归测试。当用户报告 Bug、异常、失败测试或性能回退时使用。
-
-一套针对疑难 Bug 的纪律。仅在明确合理时才跳过阶段。
-
-## 独立诊断时的信息采集
-
-当本工作流独立进入（无上游 PRD、decision-log 等产物）时，在构建反馈循环之前先执行以下信息采集。不要求用户先跑其他工作流。
-
-### 1. 快速环境扫描
-
-- `git log --oneline -30` 查看近期变更，关注可能与 Bug 相关的 commit
-- `git log --oneline --all -- <相关文件路径>` 追溯问题模块的变更历史
-- 读取 `speculo/.speculo/.config/RULES.md` 了解项目规则
-- 读取相关模块的 `README.md` 或 `AGENTS.md` 了解架构约定
-
-### 2. 症状定位
-
-- 若有错误信息/堆栈：`grep -rn "<关键符号>"` 在项目中全局搜索，定位所有相关代码路径
-- 若有性能回退：搜索相关模块最近的性能敏感变更（循环、查询、缓存）
-- 若为测试失败：读取失败测试文件及其覆盖的源代码，理解预期行为
-- 搜索项目中是否已有类似的 issue、TODO、FIXME 提及该问题
-
-### 3. 相关模块深度探索
-
-- 读取问题代码路径的所有相关文件（调用链上下游）
-- 阅读现有测试了解模块契约
-- 检查 `speculo/.speculo/.config/adr/` 中与问题模块相关的架构决策
-- 搜索 `speculo/.speculo/doc/` 中已有的领域文档
-
-### 4. 信息仍不足时
-
-- 用 `AskUserQuestion` 向用户索取：复现环境、日志文件、HAR 捕获、核心转储等——但仅在代码库探索穷尽后
-- 不要因缺少上游产物而放弃或要求用户先执行 dev/01、dev/02
-
-探索代码库时，使用项目的领域术语表来建立相关模块的清晰心智模型，并查阅你所触及区域的 ADR。
-
-## 阶段 1 —— 构建反馈循环
-
-**这是整个技能的核心。** 其余都是机械操作。如果你拥有一个快速、确定性的、可由 agent 运行的通过/失败信号来检测 Bug，你就能找到原因——二分查找、假设检验和插桩都只是在消费这个信号。如果没有这样的信号，再多的代码凝视也救不了你。
-
-在这里投入不成比例的努力。**要大胆，要有创造力，绝不放弃。**
-
-### 构建方法——大致按此顺序尝试
-
-1. **失败测试** —— 在能触及 Bug 的任何接缝处编写——单元测试、集成测试、端到端测试。
-2. **Curl / HTTP 脚本** —— 对运行中的开发服务器发请求。
-3. **CLI 调用** —— 使用 fixture 输入，将 stdout 与已知正确的快照做 diff。
-4. **无头浏览器脚本**（Playwright / Puppeteer）——驱动 UI，对 DOM/控制台/网络进行断言。
-5. **重放捕获的 trace。** 将真实的网络请求/载荷/事件日志保存到磁盘；隔离地重放经过代码路径。
-6. **一次性测试工具。** 启动系统的最小子集（一个服务，mock 依赖），通过单个函数调用触发 Bug 代码路径。
-7. **属性/模糊循环。** 如果 Bug 是「有时输出错误」，运行 1000 个随机输入寻找失败模式。
-8. **二分查找工具。** 如果 Bug 出现在两个已知状态之间（commit、数据集、版本），自动化「在状态 X 启动、检查、重复」，以便用 `git bisect run` 定位。
-9. **差异循环。** 将相同输入分别通过旧版本和新版本（或两种配置），diff 输出。
-10. **HITL bash 脚本。** 最后手段。如果必须由人类点击，用同目录 `scripts/hitl-loop.template.sh` 来驱动他们，使循环仍然结构化。捕获的输出反馈给你。
-
-构建正确的反馈循环，Bug 就解决了 90%。
-
-### 在循环本身上迭代
-
-把循环当作产品来对待。一旦你有了_一个_循环，问自己：
-
-- 能更快吗？（缓存设置、跳过无关初始化、缩小测试范围。）
-- 能让信号更锐利吗？（断言具体症状，而不是「没有崩溃」。）
-- 能更确定吗？（固定时间、设定随机种子、隔离文件系统、冻结网络。）
-
-一个 30 秒的不稳定循环几乎不比没有循环好。一个 2 秒的确定性循环是调试超能力。
-
-### 非确定性 Bug
-
-目标不是干净的复现，而是**更高的复现率**。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 概率出现的 Bug 可以调试；1% 的不行——持续提高复现率直到可以调试。
-
-### 当你确实无法构建循环时
-
-停下来明确说明。列出你尝试过的内容。向用户请求：(a) 访问能复现问题的环境，(b) 捕获的产物（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 在生产环境添加临时插桩的权限。在没有循环的情况下**不要**进入假设阶段。
-
-在你拥有一个你信任的循环之前，不要进入阶段 2。
-
-## 阶段 2 —— 复现
-
-运行循环，观察 Bug 出现。
-
-确认：
-
-- [ ] 循环产生的是**用户**描述的失败模式——而不是附近碰巧的另一个失败。错误的 Bug = 错误的修复。
-- [ ] 失败在多次运行中可复现（或者，对于非确定性 Bug，以足够高的概率复现以便调试）。
-- [ ] 你已捕获了确切的症状（错误信息、错误输出、慢响应时间），以便后续阶段能验证修复确实解决了问题。
-
-在你复现 Bug 之前不要继续。
-
-## 阶段 3 —— 假设
-
-在测试任何假设之前，先产生 **3–5 个排序的假设**。单假设生成会锚定在第一个看似合理的想法上。
-
-每个假设必须是**可证伪的**：说明它做出的预测。
-
-> 格式：「如果 <X> 是原因，那么 <改变 Y> 将使 Bug 消失 / <改变 Z> 将使它更严重。」
-
-如果你无法说明预测，这个假设只是一种感觉——丢弃或锐化它。
-
-**在测试之前将排序列表展示给用户。** 他们通常拥有能即时重新排序的领域知识（「我们刚部署了 #3 的变更」），或者知道他们已经排除的假设。低成本的检查点，大幅节省时间。不要因此阻塞——如果用户不在，按你的排序继续。
-
-## 阶段 4 —— 插桩
-
-每个探针必须映射到阶段 3 中的特定预测。**每次只改变一个变量。**
-
-工具偏好：
-
-1. **调试器 / REPL 检查**（如果环境支持）。一个断点胜过十个日志。
-2. **定向日志** —— 在能区分假设的边界处打日志。
-3. 绝不「把所有东西都打日志然后 grep」。
-
-**给每个调试日志加上唯一前缀标签**，例如 `[DEBUG-a4f2]`。最后的清理变成一次 grep。未标记的日志保留；带标记的日志删除。
-
-**性能分支。** 对于性能回退，日志通常是错的。正确做法：建立基线测量（计时工具、`performance.now()`、profiler、查询计划），然后二分查找。先测量，后修复。
-
-## 阶段 5 —— 修复 + 回归测试
-
-在修复**之前**编写回归测试——但前提是在**正确的接缝**处。
-
-正确的接缝是指测试能在调用点触发**真实 Bug 模式**的地方。如果唯一可用的接缝太浅（当 Bug 需要多个调用者时只有单调用者测试，无法复制触发 Bug 的调用链的单元测试），那么在该处的回归测试只会给出虚假的信心。
-
-**如果不存在正确的接缝，这本身就是发现。** 记录下来。代码库架构正在阻止 Bug 被锁定。在下一阶段标记此问题。
-
-如果存在正确的接缝：
-
-1. 将最小化复现转化为该接缝处的失败测试。
-2. 观察它失败。
-3. 应用修复。
-4. 观察它通过。
-5. 针对原始（未最小化的）场景重新运行阶段 1 的反馈循环。
-
-## 阶段 6 —— 清理 + 事后分析
-
-在宣布完成之前必须做：
-
-- [ ] 原始复现不再复现（重新运行阶段 1 的循环）
-- [ ] 回归测试通过（或缺少接缝已记录）
-- [ ] 所有 `[DEBUG-...]` 插桩已移除（用 `grep` 搜索前缀）
-- [ ] 一次性原型已删除（或移到明确标记的调试位置）
-- [ ] 最终正确的假设已写在 commit / PR 信息中——以便下一个调试者从中学习
-
-**然后问：什么能预防这个 Bug？** 如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体信息交给横向工作流 `../A-improve-architecture/A-improve-architecture.md` 处理。在修复**之后**提出建议，而不是之前——你现在比开始时拥有更多信息。

package/template/workflows/dev/H-diagnose/diagnose-loop.md

@@ -1,41 +0,0 @@
-# Diagnose Loop Phase
-
-## 输入
-
-- 用户描述的失败现象、日志、trace、性能症状或失败测试
-- 可运行的测试、脚本、服务、CLI 或浏览器自动化
-- `H-diagnose.md` 中的内置诊断指引（含独立使用协议与自初始化步骤）
-- 同目录 `diagnose-guide.md`（含独立诊断时的信息采集协议）
-
-### 独立进入时的上下文自采集
-
-若无上游工作流产物（PRD、decision-log 等），在进入反馈循环构建前，按 `diagnose-guide.md` 的「独立诊断时的信息采集」执行以下快速自采集，**不要求用户先执行其他工作流**：
-
-1. `git log --oneline -30` + 搜索错误关键符号 → 定位相关代码区域
-2. 读取问题模块及其测试 → 理解预期行为
-3. 检查 `speculo/.speculo/.config/` 下的项目规则与 ADR → 了解约束
-4. 仅在代码库探索穷尽后，使用 `AskUserQuestion` 向用户索取无法从仓库获取的信息（复现环境、日志文件等）
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/diagnosis.md`，由 `../_templates/diagnosis-template.md` 填写
-
-## 填写引导
-
-1. 遵循 `H-diagnose.md` 的内置诊断指引，并按需读取 `diagnose-guide.md`。
-2. 先建立快速、确定、可信的反馈循环。
-3. 没有反馈循环时停止假设阶段，记录已尝试方法和需要用户提供的材料。
-4. 复现后提出 3-5 个排序假设，并把每个假设写成可证伪预测。
-5. 插桩必须映射到具体预测，并使用可清理的唯一调试标记。
-6. 性能回退先建立基线测量，再二分或假设检验；先测量，后修复。
-
-## 边界
-
-- 不在未复现或无可信反馈循环时进入修复。
-- 不把无关日志批量加入代码。
-- 不默认保留一次性调试脚本。
-
-## 完成准则
-
-- `diagnosis.md` 无残留 `[TODO:]`
-- `.status.json` 已记录 `feedback_loop` 和 `hypothesis_status`

package/template/workflows/dev/H-diagnose/scripts/hitl-loop.template.sh

@@ -1,41 +0,0 @@
-#!/usr/bin/env bash
-# 人在环路的复现循环。
-# 复制此文件，编辑下方步骤，然后运行。
-# agent 运行脚本；用户在终端中跟随提示操作。
-#
-# 用法：
-#   bash hitl-loop.template.sh
-#
-# 两个辅助函数：
-#   step "<指令>"          → 显示指令，等待 Enter
-#   capture VAR "<问题>"   → 显示问题，将回答读入 VAR
-#
-# 结束时，捕获的值以 KEY=VALUE 格式打印供 agent 解析。
-
-set -euo pipefail
-
-step() {
-  printf '\n>>> %s\n' "$1"
-  read -r -p "    [完成后按 Enter] " _
-}
-
-capture() {
-  local var="$1" question="$2" answer
-  printf '\n>>> %s\n' "$question"
-  read -r -p "    > " answer
-  printf -v "$var" '%s' "$answer"
-}
-
-# --- edit below ---------------------------------------------------------
-
-step "在浏览器中打开 http://localhost:3000 并登录。"
-
-capture ERRORED "点击「导出」按钮。是否报错了？(y/n)"
-
-capture ERROR_MSG "粘贴错误信息（或输入 'none'）："
-
-# --- edit above ---------------------------------------------------------
-
-printf '\n--- 已捕获 ---\n'
-printf 'ERRORED=%s\n' "$ERRORED"
-printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/template/workflows/dev/I-to-issues/I-to-issues.md

@@ -1,140 +0,0 @@
----
-id: dev/I-to-issues
-category: dev
-name: To Issues
-description: 将 PRD、计划或诊断结论拆成可独立接手的垂直切片 issue
-keywords: [issues, slices, vertical, AFK, HITL, 切片]
----
-
-# To Issues 工作流执行指引
-
-本工作流是 `dev/I` 入口。它既可独立执行，也可嵌入 `dev/01`、`dev/02`、`dev/03` 或 `dev/H`，用于生成垂直切片。垂直切片和 issue 发布指引已内置在本 workflow 目录中。
-
-## 内置指引
-
-使用垂直切片（示踪弹）将计划、规格或 PRD 分解为可独立接手的 issue。
-
-### 铁律
-
-```
-没有精确到文件路径的改动清单，不算垂直切片
-```
-
-每个切片必须指名要读哪些文件、要改哪些文件、改动什么内容。笼统描述（"改一下登录"）不是切片。
-
-### 内置文档
-
-本工作流入口自带以下配套文档，在对应阶段读取：
-
-- `issues-slices.md` — 进行实际切片分解时读取；含有完整结构规范（8 段 slices.md）、独立进入时的深度搜索协议（三轮自采集）、存疑时的提问协议（决策树）
-- `../_templates/issues-slices-template.md` — 写 `slices.md` 时作为骨架填写；头部 blockquote 标注了服务工作流与产物文件名，每个 `[TODO:]` 对应结构规范中的一段
-- `../../../vendor/codebase-design/SKILL.md` — 切分跨层切片、在 §2 架构上下文命名模块与接缝时引用（**设计词汇单一事实源**）：统一使用深模块设计词汇（模块 / 接口 / 接缝 / 适配器 / 深度 / 杠杆 / 局部性），不散用「组件 / 服务 / 边界」；判定某个切片是否值得引入新接缝时，应用「一个适配器 = 假设接缝，两个适配器 = 真实接缝」——不要为单一实现凭空切出接缝。
-
-### 输入
-
-- PRD、计划、设计记录、bug 诊断结论或当前对话上下文
-- 用户明确提供的 issue tracker 配置和标签词汇表（如果存在）
-- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-user-auth`）
-
-### 输出
-
-- `speculo/.speculo/dev/<change>/slices.md`
-- 垂直切片清单、依赖关系、HITL/AFK 标记和验收标准
-- 可选的外部 issue 引用
-
-（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
-
-### 垂直切片规则
-
-- 每个切片交付一条贯穿所有层（schema、API、UI、测试）的窄但完整的路径。
-- 完成的切片可独立演示或验证。
-- 优先选择多个薄切片而非少数厚切片。
-
-切片可以是 `HITL` 或 `AFK`。HITL 切片需要人类交互，例如架构决策或设计评审。AFK 切片可以在无人类交互的情况下实现和合并。尽可能优先选择 AFK 而非 HITL。
-
-默认只生成本地切片计划。只有 tracker 已配置且用户明确要求时，才发布外部 issue；发布时按依赖顺序发布，以便被阻塞字段引用真实 issue 标识符。不要关闭或修改任何父级 issue。
-
-### 切片计划质量准则
-
-`slices.md` 不是清单，而是一份可被下游直接接手的**切片计划**。借鉴高质量 plan 的纪律（参考 TASK plan 的六段结构：当前现状 → 需读文件 → 需改文件 → 数据库表 → 实现要点 → 关键决策）：
-
-- **Context 先行**：先写清*为什么*、**已确认决策**（范围拍板，防下游重新扯皮）、**当前现状**（现有实现与需求的差距，精确到文件路径+行号）与**关键核实结论**（探索得到的事实），再展开切片。——映射 slices.md §0
-- **文件级精准**：每个切片须指名**需阅读的文件**（\| 文件 \| 目的 \|）和**需修改的文件**（\| 文件 \| 改动内容 \|，新增标 **新增**，重构标 **重度重构**），杜绝笼统描述。——映射 slices.md §3 切片条目
-- **数据库变更可追溯**：涉及 schema 变更时，用「涉及的数据库表」表记录每张表的变更（新建/新增字段/语义调整），DDL 注明 sql 文件和追加位置。——映射 slices.md §2.5
-- **实现要点前置**：每个切片列出关键实现要点（算法细节、并发控制、兜底策略），让执行者拿到切片就知道怎么下手。——映射 slices.md §3 切片条目
-- **存疑即问**：方案有未决分支时，按本工作流「存疑时的提问协议」用 `AskUserQuestion` 一次一问、带推荐、逐步锁定，不臆测。
-- **行号现场核对**：引用的行号/路径均为*近似*，实施时以现场代码为准；在计划内写明这一点，避免下游照搬过期行号。
-- **保留/不动同等重要**：每个切片既写「改什么」，也写「**保留/不动什么**」——告诉执行者哪些不能碰。
-- **验证分层**：删除型切片的验收须含残留扫描（grep 0 命中）；change 级验证总览走真实运行的冒烟与（如涉及）迁移测试。——映射 slices.md §8
-- **复用优先于新造**：能复用就不新建，在切片「复用」字段与 §1 REUSE 列显式记录。
-- **关键决策收口**：跨切片的技术选型与取舍汇总到「关键决策」段，防止下游对同一问题反复争论。——映射 slices.md §5.5
-- **重型小节按需**：风险登记、退役清单、架构上下文是条件段——复杂 change 铺开，单文件小改可省。
-
-### 独立使用
-
-本工作流**零硬依赖**，无需预先执行 dev/01、dev/02 等其他工作流即可独立进入。只需用户描述任务意图 + 当前 git 仓库即可启动。
-
-**独立进入流程：**
-
-1. **change 目录**：若用户未指定 `<change>` 目录，按「缺少 change 目录时的自初始化」创建。
-2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log、diagnosis 等），按 `issues-slices.md` 的「独立进入时的深度搜索协议」（三轮：全景扫描 → 领域上下文采集 → 锁定未决分支）自行采集切片所需上下文，不要求用户先执行其他工作流。
-3. **存疑即问**：仅在代码库探索无法确定的决策分支上，按「存疑时的提问协议」使用 `AskUserQuestion` 一次一问、带推荐、逐步锁定。
-
-### 缺少 change 目录时的自初始化
-
-若当前无对应 change 目录，按以下步骤创建：
-
-1. 从用户意图提取 `<kebab-name>`（如 `refactor-auth`、`add-export-feature`）
-2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
-3. 初始化 `.status.json`：
-   ```json
-   {
-     "dev_entry": "dev/I",
-     "current_phase": "1. Slice Issues",
-     "phase_history": [],
-     "change_status": "active",
-     "embedded_guides": ["to-issues"],
-     "slice_count": 0,
-     "hitl_slice_count": 0,
-     "published_issue_refs": [],
-     "issue_tracker_mode": "local-only"
-   }
-   ```
-4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组中追加该 change 目录名
-
-## 阶段
-
-### 1. Slice Issues — 垂直切片分解
-- 规范：`issues-slices.md`
-- 模板：`../_templates/issues-slices-template.md`
-- 产物：`slices.md`
-- 完成准则：
-  - §0 战略与背景含**已确认决策**、**当前现状**与**关键核实结论**（独立进入时自采集，有上游则继承）
-  - 每个切片都有标题、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注**保留/不动**
-  - 已确认粒度、依赖和 HITL/AFK 标记
-  - 涉及 schema 变更时 §2.5 数据库表已填写
-  - §5.5 关键决策已汇总跨切片技术选型
-  - §8 验证总览存在（静态 → 残留扫描 → 冒烟，按适用项）
-  - `slices.md` 无残留 `[TODO:]`
-
-## 依赖
-
-- 硬依赖：无
-- 软依赖：无。若同 change 目录下存在其他工作流产物（如 prd.md、decision-log.md、diagnosis.md），可继承其信息加速执行；缺失时自行采集，不阻塞流程。完成后通常移交 `../03-tdd/03-tdd.md`，此为推荐后续而非必须。
-
-## 状态扩展字段
-
-本工作流需在同 change 的 `.status.json` 追加：
-
-- `dev_entry` (string) — 固定为 `dev/I`
-- `embedded_guides` (array) — 包含 `to-issues`
-- `slice_count` (number) — 切片数量
-- `hitl_slice_count` (number) — HITL 切片数量
-- `published_issue_refs` (array) — 已发布 issue 引用，默认空
-- `issue_tracker_mode` (disabled | local-only | publish-requested | published) — issue tracker 使用状态
-
-## 完成与状态更新
-
-- 默认只生成本地 `slices.md`。
-- 只有 tracker 已配置且用户明确要求时才发布外部 issue。
-- 完成后不自动完成 change；通常移交 `../03-tdd/03-tdd.md`。

package/template/workflows/dev/I-to-issues/issues-slices.md

@@ -1,211 +0,0 @@
-# Slice Issues Phase
-
-> 本阶段将 PRD、计划或诊断结论拆为**可独立验证的垂直切片**（tracing bullet），产出一份可被下游直接接手的**切片计划** `slices.md`。
-> `slices.md` 借鉴高质量 plan 的纪律——以厚 Context（已确认决策 + 关键核实结论）开篇，按依赖排序的切片展开，
-> 每切片标注保留/不动，并以分层验证收口；同时保留 HITL/AFK 标记、用户确认与 issue 发布流程。
-
-## 独立进入时的深度搜索协议
-
-当本工作流独立进入（无上游 PRD、decision-log、diagnosis 等产物）时，在执行切片分解前先按以下步骤自行采集上下文。**不要求用户先执行 dev/01、dev/02 或其他工作流。**
-
-### 第一轮：项目全景扫描
-
-1. **目录结构探索**：遍历项目顶层目录（`src/`、`core/`、`tests/`、`docs/` 等），建立模块边界心智模型
-2. **项目规范读取**：读取 `AGENTS.md`、`README.md`、`CONTRIBUTING.md`，提取架构约定、命名规范、测试策略
-3. **配置与依赖**：读取 `package.json`（或等效构建文件），了解技术栈、依赖和脚本入口
-4. **Speculo 状态读取**：读取 `speculo/.speculo/.config/RULES.md`、`speculo/.speculo/.config/adr/`、`speculo/.speculo/dev-status.json`，了解项目决策与当前活跃 change
-5. **近期变更趋势**：`git log --oneline -30` 了解近期工作方向
-
-### 第二轮：领域上下文采集
-
-6. **搜索相关代码**：按用户意图关键词在项目中 `grep -rn`，定位所有相关代码路径、注释、TODO
-7. **文档检索**：搜索 `speculo/.speculo/doc/` 和 `speculo/.speculo/archive/` 中已有的领域分析、设计文档
-8. **测试即规格**：阅读相关模块的现有测试文件——测试描述了系统契约和边界行为
-9. **git 考古**：对关键路径执行 `git log -p -- <path>` 理解模块的演进动机
-
-### 第三轮：锁定未决分支
-
-10. **已确认决策的底线**：从以上探索中能确定的事实写入 §0「已确认决策」；无法从代码/文档确定的分支标记为 `[待确认]`
-11. **提问收敛**：对标记 `[待确认]` 的决策分支，按「存疑时的提问协议」逐一锁定——但仅在代码库探索穷尽后
-
-### 采集成果写入
-
-- 探索确认的事实 → §0「关键核实结论」（注明行号近似）
-- 从代码/文档提取的约束 → §1 IN/REUSE/OUT、§2 架构约束
-- 无法从代码库确定的 → `[待确认]` 标记，按提问协议处理
-- 从 `prd-overview.md` 或现有文档继承的风险 → §6 风险与回滚
-
-## 输入
-
-- `prd.md`、`decision-log.md`、`diagnosis.md`、现有 issue 或用户计划（均为可选；缺失时按「独立进入时的深度搜索协议」自行采集）
-- 可选 issue tracker 配置和标签词汇表
-- `I-to-issues.md` 中的内置切片指引、「切片计划质量准则」与「独立使用」协议
-- 同级 change 目录下已有的 `context-map.md`、`decision-log.md`、`prd-overview.md`（若存在，用于继承领域术语、已确认决策、风险与 ADR 引用；不存在则按深度搜索协议自采集）
-
-## 产物
-
-- `speculo/.speculo/dev/<change>/slices.md`，由 `../_templates/issues-slices-template.md` 填写
-
-## `slices.md` 结构规范
-
-`issues-slices-template.md` 提供模板骨架；AI 填写时按下述结构展开。`[必填]` 段每份都要，`[条件]` 段有则填、单文件小改可省。
-> 最小形态（单文件小改）：§0(简) + §1 + §3(单切片) + §5 + §8。复杂 change：全段铺开（含 §2.5 数据库表、§5.5 关键决策、切片内文件表和实现要点）。
-
-### 0. 战略与背景（Context）—— [必填]
-
-本段是整份切片计划的决策锚点，含五块：
-
-- **一句话战略**：单句概括「做什么 + 为什么 + 怎么做到（以现有系统为基底 / 新建 / 复用）」。
-- **已确认决策**：逐条列出与用户拍板的范围/取舍决策，防止下游重新扯皮。**有 `decision-log.md` 则继承其「已确认决策」段；独立进入（无上游）时在此自采集**。
-- **当前现状**：逐条列出与需求不符的现有实现、缺失的能力或待修复的问题。每条含：`文件路径:行号范围` + 当前值/行为 + 为什么不满足需求。独立进入时从代码库探索采集；有上游 PRD 或 diagnosis 则继承其发现。格式示例：`RegexConstants.PASSWORD` 为正则 `^(?=.*[a-z])...`（要求四类全含）——与需求「至少三类」不符。
-- **关键核实结论**：探索阶段确认的事实（依赖关系、唯一调用点、可删/须留边界等）。**必须显式写明「行号为近似、实施时以现场代码为准」**，避免下游照搬过期行号。
-- **预期产出**：1–2 句描述本 change 完成后的可观察结果。
-
-### 1. 范围边界（IN / REUSE / OUT）—— [必填]
-
-三列表格，逐条列出：
-- **IN** —— 本次必造的新能力（每项可对应后续一个或多个切片）
-- **REUSE** —— 复用现有系统的能力（不改动，只收编进新地基）
-- **OUT** —— 本期不做、留给后续迭代的内容（吸收「明确不做」边界）
-
-表格来源优先从 PRD 或用户指令提取；若来源未明确，用 `[待确认]` 标记并提请用户补充。
-
-### 2. 架构上下文 —— [条件]
-
-若 change 涉及多模块或改动既有架构，本节记录：
-- 涉及的 `core/` / `src/` / `src-tauri/`（或本项目对应分层）模块及其职责分工
-- 新增模块的定位（一句话职责 + 落点目录）
-- 不可逾越约束（来自 `AGENTS.md` 或 PRD 的硬性规则）
-- 可选 ASCII 分层图，标出依赖方向（如 `src → core → src-tauri`）
-
-> **设计词汇**：描述模块、接口与接缝时统一使用 `../../../vendor/codebase-design/SKILL.md` 的词汇（模块 / 接口 / 接缝 / 适配器 / 深度），不要散用「组件 / 服务 / 边界」。某切片是否值得切出新接缝，按「一个适配器 = 假设接缝，两个适配器 = 真实接缝」判定。
-
-单文件修复或热点 patch 可省略本节。
-
-### 2.5. 涉及的数据库表 —— [条件]
-
-若 change 涉及数据库 schema 变更（新建表、新增字段、字段语义调整），用三列表格记录：
-
-| 表 | 变更 |
-|----|------|
-
-变更描述规则：
-- **新建**表：列出全部字段名 + 类型 + PRIMARY KEY + UNIQUE KEY + INDEX，注明建表 DDL 追加到哪个 sql 文件末尾
-- **新增**字段：`字段名 类型 DEFAULT 默认值 COMMENT '注释'`，注明 ALTER TABLE 追加到哪个 sql 文件末尾
-- **字段语义调整**：`旧字段名 → 新语义`（不变更数据库结构，仅改代码层注释/映射）
-- **无结构变更**：纯逻辑变更（如增加唯一性校验）不产生 DDL，在此注明即可
-
-> SQL 追加原则：所有 DDL 变更追加到对应 sql 文件末尾，遵循只追加不修改原则。
-
-### 3. 切片（slices）—— [必填]
-
-每个切片是**一个从数据到 UI 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
-
-```markdown
-### 切片 N · 切片名称
-<phase id="<phase-id>" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
-
-- **类型：** `AFK` | `HITL`
-- **阻塞于：** 切片 M（或「无」）
-- **覆盖：** PRD 章节 / US 编号 / 用户故事简述
-- **需阅读的文件：** 实现本切片前需理解的现有代码（| 文件 | 目的 | 表）；单文件小改可省略
-- **交付物：** 该切片产出的具体文件/模块/功能清单
-- **需修改的文件：** 本切片要改动的文件（| 文件 | 改动内容 | 表）；新增文件标 **新增**，重度重构标 **重度重构**
-- **保留/不动：** 本切片**不能碰**的代码/契约/数据（如冻结常量、共享依赖、邻近功能）；无则写「无」
-- **复用：** 复用哪些现有能力（模块/文件/命令）
-- **实现要点：** 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略
-- **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成；**删除型切片须含残留扫描**（如 `grep -rn "<符号>" <范围>` 应 0 命中）
-- **对齐：** PRD FR-xxx 或 issue 引用
-- **ADR 引用：** （可选）关联的工程层 ADR 编号
-```
-
-- `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
-- `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
-- **需阅读/需修改的文件表**：借鉴高质量 plan 的双表模式——读文件表让执行者知道上下文边界，改文件表让执行者知道改动面和操作类型（新增/修改/重构）。单文件小改的切片可省略读文件表。
-- **实现要点**：每个切片列出 3-7 条关键技术点，让执行者拿到切片就知道怎么下手。包含算法细节、并发控制、兼容/兜底策略等。
-
-### 4. 横切关注点与铁律（贯穿所有切片）—— [必填]
-
-列出跨切片一致的规则、约束与不可违反的铁律，如：
-- **数据安全铁律**：必须冻结的常量 / wire-format / 密文格式（改了即用户数据损坏）——显式列出，标「不动」。
-- **契约先行**：磁盘契约先改 zod + fixtures 再改解析。
-- **删缓存可重建**铁律。
-- 范围隔离规则（不 import 旧子系统等）、命名消歧规则。
-- **行号现场核对纪律**：本计划内所有行号为近似，实施时以现场代码为准。
-
-### 5. 依赖顺序速查 —— [必填]
-
-ASCII 依赖链，展示切片先后顺序：
-
-```
-P0  切片0  名称    ← 不可回退,最先
-P1  切片1  名称
-P2  切片2  名称    依赖 P0+P1
-...
-```
-
-### 6. 风险与回滚 —— [条件]
-
-本期涉及删除、数据迁移、外部副作用或高耦合改动时填写；纯增量的单文件小改可省。逐条列出风险、触发条件、缓解与回滚手段（表格形式）。**有 `prd-overview.md` 的「风险与未知点」则继承并细化**。
-
-### 7. 退役清单 —— [条件]
-
-仅当本 change **删除既有能力**时填写：用「项 / 处置 / 验证」表逐条记录被删/被迁的内容及其去向，作为兜底核对。
-
-### 8. 验证总览 —— [必填（轻）]
-
-change 级验证 roll-up，补足每切片「验收切片」的整体闭环（按适用项填，不适用标「N/A」）：
-- **静态检查**：构建 / 类型 / lint。
-- **测试**：单测 / 契约校验。
-- **残留扫描**：对删除项 grep，应 0 命中。
-- **E2E 冒烟**：真实运行应用走查关键路径。
-- **迁移测试**：若涉及持久化 / 格式 / 键名迁移，预置旧数据验证向后兼容。
-
-> **判据：** 每个切片的「验收切片」全部通过即该切片完成；§8 验证总览整体通过 = change 可进入 `dev/04` 收尾。
-
-## 存疑时的提问协议（决策树）
-
-切分切片或填 §0「已确认决策」时若有未决分支，**不要臆测**——先用代码库探索尝试确定，无法确定时再用 `AskUserQuestion` 按决策树逐一锁定；本协议产出的共识即写入 §0：
-
-1. **定位关键问题**：识别当前最影响方案正确性的那一个未决问题。
-2. **先查后问**：若答案能用本地代码 / 文档 / 配置确认，先读相关材料；搜索 `grep -rn`、`git log`、读取测试文件。能从仓库确定则不问。
-3. **一次一问**：每次只问一个问题，不打包问题组。
-4. **带推荐**：每个问题给出推荐答案并说明理由（基于已探索的代码库上下文）。
-5. **回答后收敛**：用户回答后，更新 §0「已确认决策」与剩余分支。
-6. **遍历至共识**：沿决策树继续，直到核心分支达成共识或用户叫停。
-
-## 填写引导
-
-1. 遵循 `I-to-issues.md` 的内置切片指引与「切片计划质量准则」，以及本文件的结构规范。
-2. **写 Context（§0）**：提炼一句话战略；**采集或继承已确认决策**（有 `decision-log.md` 则继承）；**梳理当前现状**（逐条记录与需求不符的现有实现，精确到文件路径+行号）；**记录关键核实结论**（写明行号为近似、现场核对）；点明预期产出。未决分支按「存疑时的提问协议」逐一锁定。
-3. **采集范围**：从 PRD / decision-log / diagnosis / 用户指令中提取 IN/REUSE/OUT 三列、架构上下文和 ADR 引用；不确定的标记 `[待确认]`。
-4. **记录数据库变更（§2.5）**：涉及 schema 变更时，用「涉及的数据库表」表记录每张表的变更（新建/新增字段/语义调整），DDL 注明 sql 文件和追加位置。
-5. **切分垂直切片（§3）**：优先窄而完整、优先 AFK；每个切片必须写明**需阅读的文件**（\| 文件 \| 目的 \|）、**需修改的文件**（\| 文件 \| 改动内容 \|，新增标 **新增**，重构标 **重度重构**）、**实现要点**（编号列表）、用户可独立验证的「验收切片」，并标注**保留/不动**；删除型切片在验收里配残留扫描。
-6. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
-7. **填条件段**：涉及删除 / 迁移 / 外部副作用时补 §6 风险与回滚、§7 退役清单；多模块时补 §2 架构上下文。
-8. **汇总关键决策（§5.5）**：将跨切片的技术选型与取舍写入「关键决策」段（方案选择、字段复用/新建决策、SQL 追加规则等），防止下游反复争论。
-9. **收口验证（§8）**：列出静态 / 测试 / 残留扫描 / E2E / 迁移的整体验证项。
-10. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
-11. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
-12. 迭代直到用户批准分解；未批准前不发布外部 issue。
-
-## 边界
-
-- 不关闭或修改父级 issue。
-- 不默认发布到外部 tracker。
-- 不写实现代码。
-- 不编造来源；PRD/ADR/issue 引用必须真实存在。
-- 不照搬过期行号：所有行号为近似，实施期以现场代码为准。
-
-## 完成准则
-
-- `slices.md` 无残留 `[TODO:]`
-- §0 战略与背景含已确认决策、**当前现状**与关键核实结论（独立进入时自采集，有上游则继承）
-- 存疑点已按「存疑时的提问协议」逐一与用户锁定，或显式标记 `[待确认]`
-- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注保留/不动且验收含残留扫描
-- IN/REUSE/OUT 表格完整（无法确定时标 `[待确认]` 并已获用户补充）
-- 涉及 schema 变更时 §2.5 数据库表已填写（表名、变更类型、DDL 位置）
-- §5.5 关键决策已汇总跨切片技术选型与取舍
-- §8 验证总览存在（静态 / 残留扫描 / 冒烟按适用项填）
-- 适用时已填条件段（§2 架构 / §2.5 数据库表 / §5.5 关键决策 / §6 风险 / §7 退役）
-- `.status.json` 已记录 `slice_count`、`hitl_slice_count` 和 `issue_tracker_mode`

package/template/workflows/dev/M-domain-modeling/ADR-FORMAT.md

@@ -1,74 +0,0 @@
-# ADR 格式
-
-本文是项目架构决策记录（ADR）格式与判据的**单一事实源**，由 `dev/M-domain-modeling` 拥有，`dev/01`、`dev/04`、`dev/A` 等工作流按需引用。
-
-默认产物写入调用方工作流的会话产物（如 `decision-log.md`、`domain-model-log.md`）；只有用户明确确认时，才按本格式创建项目 ADR。
-
-ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。`speculo/.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
-
-## 模板
-
-```md
-# {决策的简短标题}
-
-{1-3 句话：背景是什么、我们决定了什么、为什么这样决定。}
-```
-
-就这些。一个 ADR 可以只是一段话。价值在于记录「做出了某个决策」以及「为什么」——而不是填满各个章节。
-
-## 生命周期元数据
-
-默认 ADR 不需要元数据。只有当决策需要生命周期联动时，在标题下方放极简字段：
-
-```md
-# {决策的简短标题}
-
-Status: accepted
-superseded_by: null
-
-{1-3 句话：背景是什么、我们决定了什么、为什么这样决定。}
-```
-
-允许值：
-
-- `Status: proposed | accepted | deprecated | superseded`
-- `superseded_by: ADR-NNNN | null`
-
-当新 ADR 取代旧 ADR 时：
-
-- 新 ADR 正文说明取代了哪个 ADR 以及原因。
-- 旧 ADR 顶部更新为 `Status: superseded` 和 `superseded_by: ADR-NNNN`。
-- 若项目有 ADR 索引或 README，同步状态和取代链。
-- 任何 CONTEXT、AGENTS、README 或 docs 中的旧 ADR 引用都必须改为新 ADR、删除，或标记为待确认。
-
-## 可选章节
-
-只有确实能增加价值时才包含以下章节。大多数 ADR 不需要它们。
-
-- **Status** 前置元数据（见「生命周期元数据」）—— 当决策被重新审视时很有用
-- **Considered Options** —— 只有被拒绝的替代方案值得记住时才写
-- **Consequences** —— 只有非显而易见的下游影响需要指出时才写
-
-## 编号
-
-扫描 `speculo/.speculo/.config/adr/` 找到已有的最大编号，然后加一。
-
-## 何时提议创建 ADR
-
-以下三个条件必须同时满足：
-
-1. **难以逆转** —— 日后改变主意的代价不可忽略
-2. **缺少上下文会令人意外** —— 未来的读者看到代码会疑惑「他们到底为什么要这样做？」
-3. **真实权衡的结果** —— 确实存在替代方案，而你基于特定原因选择了其中一个
-
-如果一个决策很容易逆转，就跳过它——你反正会逆转它。如果它不令人意外，没人会疑惑为什么。如果没有真正的替代方案，除了「我们做了显而易见的事」之外没有什么可记录的。
-
-### 哪些情况应该写 ADR
-
-- **架构形态。** 「我们使用 monorepo。」「写模型采用事件溯源，读模型投射到 Postgres。」
-- **上下文之间的集成模式。** 「Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。」
-- **带有锁定效应的技术选型。** 数据库、消息总线、认证提供商、部署目标。不是每个库——只是那些换掉需要花一个季度的。
-- **边界和范围决策。** 「客户数据由 Customer 上下文拥有，其他上下文只通过 ID 引用。」明确的「不做」和「要做」同样有价值。
-- **刻意偏离显而易见的路径。** 「我们用原生 SQL 而非 ORM，因为 X。」任何理性读者会假设相反做法的地方。这能防止下一个工程师去「修复」某个刻意为之的设计。
-- **代码中看不见的约束。** 「因为合规要求，我们不能用 AWS。」「因为合作方 API 合约，响应时间必须在 200 ms 以内。」
-- **拒绝理由不明显的替代方案。** 如果你考虑过 GraphQL 但因为某些微妙原因选了 REST，记录下来——否则六个月后会有人再次提议 GraphQL。