@namewta/speculo 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

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

@@ -14,6 +14,21 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 使用垂直切片（示踪弹）将计划、规格或 PRD 分解为可独立接手的 issue。
 
+### 铁律
+
+```
+没有精确到文件路径的改动清单，不算垂直切片
+```
+
+每个切片必须指名要读哪些文件、要改哪些文件、改动什么内容。笼统描述（"改一下登录"）不是切片。
+
+### 内置文档
+
+本工作流入口自带以下配套文档，在对应阶段读取：
+
+- `issues-slices.md` — 进行实际切片分解时读取；含有完整结构规范（8 段 slices.md）、独立进入时的深度搜索协议（三轮自采集）、存疑时的提问协议（决策树）
+- `../_templates/issues-slices-template.md` — 写 `slices.md` 时作为骨架填写；头部 blockquote 标注了服务工作流与产物文件名，每个 `[TODO:]` 对应结构规范中的一段
+
 ### 输入
 
 - PRD、计划、设计记录、bug 诊断结论或当前对话上下文
@@ -40,14 +55,18 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 ### 切片计划质量准则
 
-`slices.md` 不是清单，而是一份可被下游直接接手的**切片计划**。借鉴高质量 plan 的纪律：
+`slices.md` 不是清单，而是一份可被下游直接接手的**切片计划**。借鉴高质量 plan 的纪律（参考 TASK plan 的六段结构：当前现状 → 需读文件 → 需改文件 → 数据库表 → 实现要点 → 关键决策）：
 
-- **Context 先行**：先写清*为什么*、**已确认决策**（范围拍板，防下游重新扯皮）与**关键核实结论**（探索得到的事实），再展开切片。
+- **Context 先行**：先写清*为什么*、**已确认决策**（范围拍板，防下游重新扯皮）、**当前现状**（现有实现与需求的差距，精确到文件路径+行号）与**关键核实结论**（探索得到的事实），再展开切片。——映射 slices.md §0
+- **文件级精准**：每个切片须指名**需阅读的文件**（\| 文件 \| 目的 \|）和**需修改的文件**（\| 文件 \| 改动内容 \|，新增标 **新增**，重构标 **重度重构**），杜绝笼统描述。——映射 slices.md §3 切片条目
+- **数据库变更可追溯**：涉及 schema 变更时，用「涉及的数据库表」表记录每张表的变更（新建/新增字段/语义调整），DDL 注明 sql 文件和追加位置。——映射 slices.md §2.5
+- **实现要点前置**：每个切片列出关键实现要点（算法细节、并发控制、兜底策略），让执行者拿到切片就知道怎么下手。——映射 slices.md §3 切片条目
 - **存疑即问**：方案有未决分支时，按本工作流「存疑时的提问协议」用 `AskUserQuestion` 一次一问、带推荐、逐步锁定，不臆测。
 - **行号现场核对**：引用的行号/路径均为*近似*，实施时以现场代码为准；在计划内写明这一点，避免下游照搬过期行号。
 - **保留/不动同等重要**：每个切片既写「改什么」，也写「**保留/不动什么**」——告诉执行者哪些不能碰。
-- **验证分层**：删除型切片的验收须含残留扫描（grep 0 命中）；change 级验证总览走真实运行的冒烟与（如涉及）迁移测试。
+- **验证分层**：删除型切片的验收须含残留扫描（grep 0 命中）；change 级验证总览走真实运行的冒烟与（如涉及）迁移测试。——映射 slices.md §8
 - **复用优先于新造**：能复用就不新建，在切片「复用」字段与 §1 REUSE 列显式记录。
+- **关键决策收口**：跨切片的技术选型与取舍汇总到「关键决策」段，防止下游对同一问题反复争论。——映射 slices.md §5.5
 - **重型小节按需**：风险登记、退役清单、架构上下文是条件段——复杂 change 铺开，单文件小改可省。
 
 ### 独立使用
@@ -56,19 +75,9 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 **独立进入流程：**
 
-1. **change 目录**：若用户未指定 `<change>` 目录，按 `YYYY-MM-DD-<kebab-name>` 格式创建（如 `2026-06-17-refactor-auth`），初始化 `.status.json` 并更新 `dev-status.json`。
-2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log、diagnosis 等），**自行通过代码库探索采集切片所需上下文**，不要求用户先执行其他工作流：
-   - 探索项目目录结构，建立模块心智模型（`src/`、`core/`、`tests/` 等）
-   - 读取 `AGENTS.md`、`README.md`、`CONTRIBUTING.md` 了解项目规范与架构约定
-   - `git log --oneline -30` 了解近期变更趋势和相关模块
-   - 搜索相关代码区域的注释、TODO、FIXME 和现有 issue 引用
-   - 读取 `speculo/.speculo/.config/RULES.md` 和 `speculo/.speculo/.config/adr/` 了解项目决策
-3. **深度搜索**：信息仍不足时，执行以下顺序的深度探寻：
-   - 搜索项目中与用户意图关键词匹配的代码、注释和文档
-   - 追溯相关模块的 git history（`git log -p -- <path>`）
-   - 搜索 `speculo/.speculo/doc/` 和 `speculo/.speculo/archive/` 中已有的领域文档
-   - 检查现有测试文件了解模块契约和边界行为
-4. **存疑即问**：仅在代码库探索无法确定的决策分支上，按「存疑时的提问协议」使用 `AskUserQuestion` 一次一问、带推荐、逐步锁定。
+1. **change 目录**：若用户未指定 `<change>` 目录，按「缺少 change 目录时的自初始化」创建。
+2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log、diagnosis 等），按 `issues-slices.md` 的「独立进入时的深度搜索协议」（三轮：全景扫描 → 领域上下文采集 → 锁定未决分支）自行采集切片所需上下文，不要求用户先执行其他工作流。
+3. **存疑即问**：仅在代码库探索无法确定的决策分支上，按「存疑时的提问协议」使用 `AskUserQuestion` 一次一问、带推荐、逐步锁定。
 
 ### 缺少 change 目录时的自初始化
 
@@ -99,9 +108,11 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 - 模板：`../_templates/issues-slices-template.md`
 - 产物：`slices.md`
 - 完成准则：
-  - §0 战略与背景含**已确认决策**与**关键核实结论**（独立进入时自采集，有上游则继承）
-  - 每个切片都有标题、类型、依赖、覆盖来源、验收切片；删除型切片标注**保留/不动**
+  - §0 战略与背景含**已确认决策**、**当前现状**与**关键核实结论**（独立进入时自采集，有上游则继承）
+  - 每个切片都有标题、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注**保留/不动**
   - 已确认粒度、依赖和 HITL/AFK 标记
+  - 涉及 schema 变更时 §2.5 数据库表已填写
+  - §5.5 关键决策已汇总跨切片技术选型
   - §8 验证总览存在（静态 → 残留扫描 → 冒烟，按适用项）
   - `slices.md` 无残留 `[TODO:]`
 

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

@@ -49,14 +49,15 @@
 ## `slices.md` 结构规范
 
 `issues-slices-template.md` 提供模板骨架；AI 填写时按下述结构展开。`[必填]` 段每份都要，`[条件]` 段有则填、单文件小改可省。
-> 最小形态（单文件小改）：§0(简) + §1 + §3(单切片) + §5 + §8。复杂 change：全段铺开。
+> 最小形态（单文件小改）：§0(简) + §1 + §3(单切片) + §5 + §8。复杂 change：全段铺开（含 §2.5 数据库表、§5.5 关键决策、切片内文件表和实现要点）。
 
 ### 0. 战略与背景（Context）—— [必填]
 
-本段是整份切片计划的决策锚点，含四块：
+本段是整份切片计划的决策锚点，含五块：
 
 - **一句话战略**：单句概括「做什么 + 为什么 + 怎么做到（以现有系统为基底 / 新建 / 复用）」。
 - **已确认决策**：逐条列出与用户拍板的范围/取舍决策，防止下游重新扯皮。**有 `decision-log.md` 则继承其「已确认决策」段；独立进入（无上游）时在此自采集**。
+- **当前现状**：逐条列出与需求不符的现有实现、缺失的能力或待修复的问题。每条含：`文件路径:行号范围` + 当前值/行为 + 为什么不满足需求。独立进入时从代码库探索采集；有上游 PRD 或 diagnosis 则继承其发现。格式示例：`RegexConstants.PASSWORD` 为正则 `^(?=.*[a-z])...`（要求四类全含）——与需求「至少三类」不符。
 - **关键核实结论**：探索阶段确认的事实（依赖关系、唯一调用点、可删/须留边界等）。**必须显式写明「行号为近似、实施时以现场代码为准」**，避免下游照搬过期行号。
 - **预期产出**：1–2 句描述本 change 完成后的可观察结果。
 
@@ -79,6 +80,21 @@
 
 单文件修复或热点 patch 可省略本节。
 
+### 2.5. 涉及的数据库表 —— [条件]
+
+若 change 涉及数据库 schema 变更（新建表、新增字段、字段语义调整），用三列表格记录：
+
+| 表 | 变更 |
+|----|------|
+
+变更描述规则：
+- **新建**表：列出全部字段名 + 类型 + PRIMARY KEY + UNIQUE KEY + INDEX，注明建表 DDL 追加到哪个 sql 文件末尾
+- **新增**字段：`字段名 类型 DEFAULT 默认值 COMMENT '注释'`，注明 ALTER TABLE 追加到哪个 sql 文件末尾
+- **字段语义调整**：`旧字段名 → 新语义`（不变更数据库结构，仅改代码层注释/映射）
+- **无结构变更**：纯逻辑变更（如增加唯一性校验）不产生 DDL，在此注明即可
+
+> SQL 追加原则：所有 DDL 变更追加到对应 sql 文件末尾，遵循只追加不修改原则。
+
 ### 3. 切片（slices）—— [必填]
 
 每个切片是**一个从数据到 UI 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
@@ -90,9 +106,12 @@
 - **类型：** `AFK` | `HITL`
 - **阻塞于：** 切片 M（或「无」）
 - **覆盖：** PRD 章节 / US 编号 / 用户故事简述
+- **需阅读的文件：** 实现本切片前需理解的现有代码（| 文件 | 目的 | 表）；单文件小改可省略
 - **交付物：** 该切片产出的具体文件/模块/功能清单
+- **需修改的文件：** 本切片要改动的文件（| 文件 | 改动内容 | 表）；新增文件标 **新增**，重度重构标 **重度重构**
 - **保留/不动：** 本切片**不能碰**的代码/契约/数据（如冻结常量、共享依赖、邻近功能）；无则写「无」
 - **复用：** 复用哪些现有能力（模块/文件/命令）
+- **实现要点：** 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略
 - **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成；**删除型切片须含残留扫描**（如 `grep -rn "<符号>" <范围>` 应 0 命中）
 - **对齐：** PRD FR-xxx 或 issue 引用
 - **ADR 引用：** （可选）关联的工程层 ADR 编号
@@ -100,7 +119,8 @@
 
 - `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
 - `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
-- 切片改动面较宽时，可在「交付物」下用 `| 文件 | 改动 |` 表逐文件列出（新增/修改/删除/**保留**），提升信息密度。
+- **需阅读/需修改的文件表**：借鉴高质量 plan 的双表模式——读文件表让执行者知道上下文边界，改文件表让执行者知道改动面和操作类型（新增/修改/重构）。单文件小改的切片可省略读文件表。
+- **实现要点**：每个切片列出 3-7 条关键技术点，让执行者拿到切片就知道怎么下手。包含算法细节、并发控制、兼容/兜底策略等。
 
 ### 4. 横切关注点与铁律（贯穿所有切片）—— [必填]
 
@@ -155,15 +175,17 @@ change 级验证 roll-up，补足每切片「验收切片」的整体闭环（
 ## 填写引导
 
 1. 遵循 `I-to-issues.md` 的内置切片指引与「切片计划质量准则」，以及本文件的结构规范。
-2. **写 Context（§0）**：提炼一句话战略；**采集或继承已确认决策**（有 `decision-log.md` 则继承）与**关键核实结论**（写明行号为近似、现场核对）；点明预期产出。未决分支按「存疑时的提问协议」逐一锁定。
+2. **写 Context（§0）**：提炼一句话战略；**采集或继承已确认决策**（有 `decision-log.md` 则继承）；**梳理当前现状**（逐条记录与需求不符的现有实现，精确到文件路径+行号）；**记录关键核实结论**（写明行号为近似、现场核对）；点明预期产出。未决分支按「存疑时的提问协议」逐一锁定。
 3. **采集范围**：从 PRD / decision-log / diagnosis / 用户指令中提取 IN/REUSE/OUT 三列、架构上下文和 ADR 引用；不确定的标记 `[待确认]`。
-4. **切分垂直切片**：优先窄而完整、优先 AFK；每个切片必须有用户可独立验证的「验收切片」，并标注**保留/不动**；删除型切片在验收里配残留扫描。
-5. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
-6. **填条件段**：涉及删除 / 迁移 / 外部副作用时补 §6 风险与回滚、§7 退役清单；多模块时补 §2 架构上下文。
-7. **收口验证（§8）**：列出静态 / 测试 / 残留扫描 / E2E / 迁移的整体验证项。
-8. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
-9. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
-10. 迭代直到用户批准分解；未批准前不发布外部 issue。
+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。
 
 ## 边界
 
@@ -176,10 +198,12 @@ change 级验证 roll-up，补足每切片「验收切片」的整体闭环（
 ## 完成准则
 
 - `slices.md` 无残留 `[TODO:]`
-- §0 战略与背景含已确认决策与关键核实结论（独立进入时自采集，有上游则继承）
+- §0 战略与背景含已确认决策、**当前现状**与关键核实结论（独立进入时自采集，有上游则继承）
 - 存疑点已按「存疑时的提问协议」逐一与用户锁定，或显式标记 `[待确认]`
-- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、验收切片；删除型切片标注保留/不动且验收含残留扫描
+- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注保留/不动且验收含残留扫描
 - IN/REUSE/OUT 表格完整（无法确定时标 `[待确认]` 并已获用户补充）
+- 涉及 schema 变更时 §2.5 数据库表已填写（表名、变更类型、DDL 位置）
+- §5.5 关键决策已汇总跨切片技术选型与取舍
 - §8 验证总览存在（静态 / 残留扫描 / 冒烟按适用项填）
-- 适用时已填条件段（§2 架构 / §6 风险 / §7 退役）
+- 适用时已填条件段（§2 架构 / §2.5 数据库表 / §5.5 关键决策 / §6 风险 / §7 退役）
 - `.status.json` 已记录 `slice_count`、`hitl_slice_count` 和 `issue_tracker_mode`

package/template/workflows/dev/_templates/issues-slices-template.md

@@ -1,11 +1,12 @@
 > **服务工作流：** `../I-to-issues/I-to-issues.md`
 > **产物文件名：** `slices.md`
 > **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
+> **填写纪律：** 本模板遵循六段高质量 plan 纪律——当前现状 → 需读文件 → 需改文件 → 数据库表 → 实现要点 → 关键决策；标「条件段」的小节按需填写，单文件小改的最小形态为 §0(简) + §1 + §3(单切片) + §5 + §8。
 
 # 切片计划（Vertical Slices）
 
-> 本文件是一份可被下游直接接手的切片计划：以厚 Context（已确认决策 + 关键核实结论）开篇，
-> 按依赖排序的切片展开，每切片标注保留/不动，并以分层验证收口。
+> 本文件是一份可被下游直接接手的切片计划：以厚 Context（已确认决策 + 当前现状 + 关键核实结论）开篇，
+> 按依赖排序的切片展开，每切片标注需读/需改文件、实现要点与保留/不动，并以分层验证收口。
 > 每个切片有 `<phase id="...">` 标识，供 TDD 工作流直接引用。
 > 标「条件段」的小节按需填写；单文件小改的最小形态为 §0(简) + §1 + §3(单切片) + §5 + §8。
 
@@ -13,6 +14,7 @@
 
 - **一句话战略：** [TODO: 做什么 + 为什么 + 怎么做到（新建 / 复用 / 以现有系统为基底）。]
 - **已确认决策：** [TODO: 逐条列出与用户拍板的范围/取舍决策；有 decision-log.md 则继承其「已确认决策」段。]
+- **当前现状：** [TODO: 逐条列出与需求不符的现有实现——文件路径:行号 + 当前值/行为 + 为什么不满足需求；独立进入时从代码库探索采集。]
 - **关键核实结论：** [TODO: 探索确认的事实（依赖 / 唯一调用点 / 可删须留边界）。注明：行号为近似，实施时以现场代码为准。]
 - **预期产出：** [TODO: 1–2 句，本 change 完成后的可观察结果。]
 
@@ -26,6 +28,13 @@
 ## 2. 架构上下文
 [TODO: 条件段——涉及的模块与职责分工、新增模块定位、不可逾越约束；可附 ASCII 分层图与依赖方向。单文件修复可删除本节。]
 
+## 2.5. 涉及的数据库表
+[TODO: 条件段——若涉及 schema 变更，用 | 表 | 变更 | 表记录：
+- 新建表：列出全部字段 + PK + UK + INDEX，注明 DDL 追加到哪个 sql 文件末尾
+- 新增字段：字段名 类型 DEFAULT 默认值 COMMENT '注释'，注明 ALTER TABLE 追加位置
+- 字段语义调整：旧字段名 → 新语义（不变更结构）
+- 无 schema 变更则删除本节]
+
 ## 3. 切片
 
 ### 切片 1 · [切片名称]
@@ -34,9 +43,12 @@
 - **类型：** AFK | HITL
 - **阻塞于：** 无
 - **覆盖：** [TODO: PRD 章节 / US 编号 / 用户故事]
+- **需阅读的文件：** [TODO: | 文件 | 目的 |；单文件小改可省略]
 - **交付物：** [TODO: 具体文件/模块/功能；改动面宽时可用 | 文件 | 改动 | 表逐文件列出]
+- **需修改的文件：** [TODO: | 文件 | 改动内容 |；新增文件标 **新增**，重度重构标 **重度重构**]
 - **保留/不动：** [TODO: 本切片不能碰的代码/契约/数据；无则写「无」]
 - **复用：** [TODO: 复用哪些现有能力]
+- **实现要点：** [TODO: 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略]
 - **验收切片：** [TODO: 可独立执行的验证命令或步骤；删除型须含残留扫描 grep 0 命中]
 - **对齐：** [TODO: PRD FR-xxx 或 issue 引用]
 - **ADR 引用：** [TODO: 关联的 ADR 编号，可选]
@@ -47,9 +59,12 @@
 - **类型：** AFK | HITL
 - **阻塞于：** 切片 1
 - **覆盖：** [TODO]
+- **需阅读的文件：** [TODO: | 文件 | 目的 |；单文件小改可省略]
 - **交付物：** [TODO]
+- **需修改的文件：** [TODO: | 文件 | 改动内容 |]
 - **保留/不动：** [TODO]
 - **复用：** [TODO]
+- **实现要点：** [TODO]
 - **验收切片：** [TODO]
 - **对齐：** [TODO]
 - **ADR 引用：** [TODO]
@@ -67,6 +82,9 @@ P1  phase1-xxx  切片名称  依赖 P0
 ]
 ```
 
+## 5.5. 关键决策
+[TODO: 汇总影响全局或跨切片的技术选型与取舍，如方案选择（工具类 vs 正则）、字段复用/新建决策、SQL 追加规则等。防止下游对同一问题反复争论。单文件小改可删除本节。]
+
 ## 6. 风险与回滚
 [TODO: 条件段——本期涉及删除/数据迁移/外部副作用/高耦合时填：风险 / 触发条件 / 缓解 / 回滚 表；有 prd-overview.md 风险则继承细化。纯增量小改可删除本节。]