@namewta/speculo 0.1.15 → 0.1.17

package/template/workflows/dev/A-improve-architecture/A-improve-architecture.md

@@ -0,0 +1,143 @@
+---
+id: dev/A-improve-architecture
+category: dev
+name: Improve Architecture
+description: 扫描代码库寻找深化机会，以可视化 HTML 报告呈现候选，再对选中方向深入质询并沉淀领域模型
+keywords: [architecture, deepening, deep-module, refactor, 架构, 深化, 接缝]
+---
+
+# Improve Architecture 工作流执行指引
+
+本工作流是 `dev/A` 入口：浮现架构摩擦、提出**深化机会**（把浅模块转化为深模块的重构），目标是可测试性与 AI 可导航性。它**建立在共享设计词汇与项目领域模型之上**：
+
+- 架构词汇与原则（模块 / 接口 / 深度 / 接缝 / 适配器 / 杠杆 / 局部性；删除测试、「接口就是测试表面」、「一个适配器 = 假设接缝，两个 = 真实接缝」）统一引用 `../../../vendor/codebase-design/SKILL.md`（及 `DEEPENING.md`）。在每条建议中**严格使用**这些术语——不要偏离到「组件 / 服务 / API / 边界」。
+- 领域语言来自 `speculo/.speculo/.config/context/CONTEXT.md`（为好接缝命名）；`speculo/.speculo/.config/adr/` 中的 ADR 记录本工作流**不应重新争议**的决策。领域模型的主动维护见 `../M-domain-modeling/M-domain-modeling.md`。
+
+## 内置指引
+
+### 何时使用
+
+当用户想系统性发现并落实架构深化机会（让代码更可测试、对 AI 更可导航）时使用。也可由 `../H-diagnose/H-diagnose.md` 在修复后转入——当 Bug 根因涉及架构（没有好接缝、纠缠调用者、隐藏耦合）时。
+
+### 输入
+
+- 当前 git 仓库与待改进的代码区域
+- `speculo/.speculo/.config/context/CONTEXT.md` 领域词汇、触及区域的 `speculo/.speculo/.config/adr/` ADR
+- 设计词汇单一事实源 `../../../vendor/codebase-design/SKILL.md`、`DEEPENING.md`、`DESIGN-IT-TWICE.md`
+- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-deepen-order-intake`）
+
+### 输出
+
+- `speculo/.speculo/dev/<change>/architecture-candidates.md` —— 结构化深化候选清单
+- `speculo/.speculo/dev/<change>/architecture-review.html` —— 可视化架构审查报告（前后对比图 + 推荐强度）
+- `speculo/.speculo/dev/<change>/architecture-design.md` —— 选中候选经质询后的接口设计与决策
+- 经用户确认后更新 `.config/context/`、`.config/adr/`（经 `../M-domain-modeling/`）
+
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
+### 核心原则（引用 codebase-design）
+
+- **删除测试**：对任何疑似浅的模块，想象删除它——复杂性会集中（好信号，值得深化）还是只是移动？
+- **深度是接口的属性**：小接口 + 大量实现；深化 = 缩小接口、把复杂性吸收进实现。
+- **接缝纪律**：一个适配器 = 假设接缝，两个 = 真实接缝；不要为单一实现凭空切接缝。
+- 完整原则、依赖类别与「替换而非叠加」测试策略见 `../../../vendor/codebase-design/SKILL.md` 与 `DEEPENING.md`，本工作流不复制。
+
+### 渐进披露
+
+- `HTML-REPORT.md`：编写 `architecture-review.html` 时读取——完整 HTML 框架、图表模式与样式指南。
+
+### 独立使用
+
+本工作流**零硬依赖**，无需预先执行其他工作流即可独立进入（`dev/A`）。只需当前 git 仓库即可启动；缺 change 目录时按下「自初始化」创建；缺 CONTEXT / ADR 时按代码现状探索，不阻塞。
+
+### 缺少 change 目录时的自初始化
+
+若当前无对应 change 目录：
+
+1. 从用户意图提取 `<kebab-name>`（如 `deepen-order-intake`）
+2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
+3. 初始化 `.status.json`：
+   ```json
+   {
+     "dev_entry": "dev/A",
+     "current_phase": "1. Scan",
+     "phase_history": [],
+     "change_status": "active",
+     "embedded_guides": ["improve-architecture"],
+     "candidate_count": 0,
+     "selected_candidate": null,
+     "report_path": null,
+     "architecture_status": "scanning"
+   }
+   ```
+4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组追加该 change 目录名
+
+## 阶段
+
+> **持久化铁律**：所有产物（含 HTML 报告）写入 `speculo/.speculo/dev/<change>/`，**禁止写入 `temp/`、系统临时目录或项目根目录**。
+
+### 1. Scan — 探索深化候选
+- 规范：本入口「核心原则」+ `../../../vendor/codebase-design/SKILL.md`、`../../../vendor/codebase-design/DEEPENING.md`
+- 模板：无（候选条目结构见下「引导」第 4 步）
+- 产物：`architecture-candidates.md`
+- 引导：
+  1. 先读 `speculo/.speculo/.config/context/CONTEXT.md` 与触及区域的 `.config/adr/`。
+  2. 用 Agent 工具（`subagent_type=Explore`）有机地遍历代码库，注意摩擦：理解一个概念要在许多小模块间跳转？模块浅（接口几乎和实现一样复杂）？纯函数仅为可测试性而提取、真 bug 藏在其调用方式里（没有局部性）？紧耦合模块在接缝处泄漏？哪些区域难以通过当前接口测试？
+  3. 对每个疑似浅模块应用**删除测试**，保留「删除会集中复杂性」的候选。
+  4. 每个候选记录：**涉及文件**、**问题**（当前摩擦）、**解决方案**（通俗语言）、**收益**（用局部性 / 杠杆 / 测试改善表述）、**依赖类别**（进程内 / 本地可替换 / 端口与适配器 / mock）、**推荐强度**（强烈 / 值得探索 / 推测性）。
+  5. 与现有 ADR 冲突的候选，仅在摩擦真实到值得重审 ADR 时保留，并在条目中显式标注（如「与 ADR-0007 矛盾——但因……值得重新讨论」）。
+- 完成准则：
+  - 候选均用 codebase-design 词汇命名（不散用「组件 / 服务 / 边界」）
+  - 每个候选含文件、问题、解决方案、收益、依赖类别、推荐强度
+  - `architecture-candidates.md` 无残留 `[TODO:]`
+
+### 2. Report — 可视化架构审查报告
+- 规范：`HTML-REPORT.md`
+- 模板：无
+- 产物：`architecture-review.html`
+- 引导：
+  1. 按 `HTML-REPORT.md` 编写**自包含** HTML（Tailwind + Mermaid 走 CDN），每个候选一张卡片含**前后对比图**，结尾「首要推荐」段。
+  2. 写入 `speculo/.speculo/dev/<change>/architecture-review.html`（**不写临时目录**），用 OS 命令打开（macOS `open <path>`、Linux `xdg-open <path>`、Windows `start <path>`），并告知用户绝对路径。
+  3. 领域用 CONTEXT 词汇、架构用 codebase-design 词汇。
+  4. 此时不提接口设计；写入并打开后，询问用户：「这些候选你想探索哪一个？」
+- 完成准则：
+  - HTML 自包含、每个候选有前后对比图与推荐强度徽章、含首要推荐段
+  - 报告写入 change 目录并已为用户打开
+  - 已请用户选择候选
+
+### 3. Grill — 质询所选候选并沉淀
+- 规范：`../../../skills/grill-me/SKILL.md`（逐问压测）+ `../M-domain-modeling/M-domain-modeling.md`（内联沉淀）
+- 模板：无
+- 产物：`architecture-design.md`；经用户确认后更新 `.config/context/`、`.config/adr/`
+- 引导：
+  1. 用 `../../../skills/grill-me/SKILL.md` 与用户走设计树：约束、依赖、深化后模块形态、接缝后面是什么、哪些测试存活。
+  2. 决策结晶时按 `../M-domain-modeling/M-domain-modeling.md` 内联沉淀：深化模块用了 CONTEXT 没有的概念 → 加术语；锐化了模糊术语 → 更新 CONTEXT；用户以关键理由否决候选 → 按 ADR 三判据决定是否记 ADR（防止未来架构审查重复建议同一件事）。
+  3. 想探索深化模块的备选接口时，按 `../../../vendor/codebase-design/DESIGN-IT-TWICE.md` 的「设计两次」并行子代理模式。
+- 完成准则：
+  - 选中候选的接口、依赖策略与适配器、存活测试已记入 `architecture-design.md`
+  - 决策结晶处的术语 / ADR 已按 `../M-domain-modeling/` 沉淀（经用户确认）
+  - `architecture-design.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 硬依赖：无（零依赖横向工作流）
+- 软依赖：无。可独立进入；也可由 `../H-diagnose/H-diagnose.md` 修复后转入。建立在 `../../../vendor/codebase-design/`（设计词汇）与 `../M-domain-modeling/`（领域模型）之上；深化的实现落地交由 `../03-tdd/03-tdd.md`。
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/A`
+- `embedded_guides` (array) — 包含 `improve-architecture`
+- `candidate_count` (number) — 深化候选数量
+- `selected_candidate` (string|null) — 用户选中的候选
+- `report_path` (string|null) — `speculo/.speculo/dev/<change>/architecture-review.html`
+- `architecture_status` (scanning | reported | grilling | designed | blocked) — 工作流状态
+
+## 完成与状态更新
+
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- 报告生成后写入 `candidate_count`、`report_path`，置 `architecture_status: reported`。
+- 用户选定并质询后写入 `selected_candidate`，置 `architecture_status: designed`。
+- 写 `.config/context/` 或 `.config/adr/` 前必须经用户确认（经 `../M-domain-modeling/`）。
+- 本工作流不自动完成 change；深化的实现交由 `../03-tdd/03-tdd.md` 落地。

package/template/workflows/dev/A-improve-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML 报告格式
+
+架构审查以单个**自包含 HTML 文件**渲染，写入 `speculo/.speculo/dev/<change>/architecture-review.html`（由入口 `A-improve-architecture.md` Phase 2 规定，**不写临时目录**）。Tailwind 和 Mermaid 均从 CDN 加载。Mermaid 可靠地处理图形状图表；手写 div 和内联 SVG 处理更具编辑性的可视化（质量图、横截面图）。两者混合使用——不要所有内容都依赖 Mermaid，否则会显得千篇一律。
+
+## 脚手架
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## 页头
+
+仓库名称、日期和紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，深色粗框 = 深层模块。没有介绍段落——直接进入候选方案。
+
+## 候选卡片
+
+图表承担主要信息量。文字稀疏、平实，使用 `../../../vendor/codebase-design/SKILL.md` 的术语表词汇，不铺陈。
+
+每个候选方案为一个 `<article>`：
+
+- **标题**——简短，命名深化操作（例如「折叠订单接收流水线」）。
+- **徽章行**——推荐强度（`Strong` = 翡翠绿，`Worth exploring` = 琥珀色，`Speculative` = 石板灰），外加一个依赖类别标签（`in-process`、`local-substitutable`、`ports & adapters`、`mock`）。
+- **文件**——等宽字体列表，`font-mono text-sm`。
+- **Before / After 图表**——核心部分。两列并排。见下方模式。
+- **问题**——一句话。痛点是什么。
+- **解决方案**——一句话。改变了什么。
+- **收益**——项目符号，每条 ≤6 个字。例如「测试只需命中一个接口」「定价逻辑不再泄漏」「删除 4 个浅层包装器」。
+- **ADR 提示**（如适用）——琥珀色背景框中的一行说明。
+
+没有解释性段落。如果图表需要一段文字才能理解，那就重绘图表。
+
+## 图表模式
+
+选择适合候选方案的模式。混合使用。不要让每张图表看起来都一样——多样性本身就是目的之一。
+
+### Mermaid 图（依赖/调用流的常用工具）
+
+当要表达「X 调用 Y 调用 Z，看看这有多乱」时，使用 Mermaid `flowchart` 或 `graph`。用 Tailwind 风格的卡片包裹它，避免显得突兀。使用 classDef 将泄漏边着色为红色，将深层模块着色为深色。时序图适合表达「Before：6 次往返；After：1 次」。
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### 手写框线箭头图（当 Mermaid 布局不理想时）
+
+模块用带有边框和标签的 `<div>` 表示。箭头用绝对定位在相对容器上的内联 SVG `<line>` 或 `<path>` 元素表示。当你希望「After」图表呈现为一个粗边框的深层模块，内部变灰时，使用这种方式——Mermaid 无法渲染出正确的视觉重量。
+
+### 横截面图（适合展示分层浅度）
+
+堆叠水平条带（`h-12 border-l-4`）来展示调用经过的层级。Before：6 个薄层，每层几乎什么都不做。After：1 个粗条带，标注了合并后的职责。
+
+### 质量图（适合展示「接口与实现一样宽」）
+
+每个模块两个矩形——一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅层）。After：接口矩形短，实现矩形高（深层）。
+
+### 调用图折叠
+
+Before：函数调用树，渲染为嵌套盒子。After：同一棵树折叠为一个盒子，内部现已内部化的调用在其中淡色显示。
+
+## 样式指南
+
+- 偏编辑风格，而非企业仪表盘风格。宽裕的留白。标题可选衬线字体（`font-serif` 与 stone/slate 配色搭配效果很好）。
+- 颜色克制：一种强调色（翡翠绿或靛蓝）加红色表示泄漏，琥珀色表示警告。
+- 图表高度保持在约 320px，以便 before/after 并排显示无需滚动。
+- 图表内模块标签使用 `text-xs uppercase tracking-wider`——它们应该呈现为示意图风格，而非 UI 风格。
+- 唯一的脚本是 Tailwind CDN 和 Mermaid ESM 导入。报告其余部分是静态的——没有应用代码，除 Mermaid 自身渲染外没有交互性。
+
+## 首选推荐部分
+
+一张较大的卡片。候选方案名称，一句说明原因的话，锚链接指向其卡片。仅此而已。
+
+## 语气
+
+平实中文，简洁——但架构名词和动词直接来自 `../../../vendor/codebase-design/SKILL.md`。简洁不是偏离术语表的借口。
+
+**精确使用：** 模块（module）、接口（interface）、实现（implementation）、深度（depth）、深（deep）、浅（shallow）、接缝（seam）、适配器（adapter）、杠杆（leverage）、局部性（locality）。
+
+**绝不替换：** 组件 / 服务 / 单元（表示 module）· API / 签名（表示 interface）· 边界（表示 seam）· 层 / 包装器（表示 module，当你的意思是 module 时）。
+
+**符合风格的表述：**
+
+- 「订单接收模块是浅的——接口几乎和实现一样复杂。」
+- 「定价逻辑在接缝处泄漏。」
+- 「深化：一个接口，一处可测。」
+- 「两个适配器证明了接缝：生产用 HTTP，测试用内存。」
+
+**收益项目符号**用术语表词汇命名收益：「局部性：bug 集中在一个模块」「杠杆：一个接口，N 个调用点」「接口缩小，实现吸收包装器」。不要写「更易维护」或「更干净的代码」——这些词不在术语表中，不应出现。
+
+不模棱两可，不开场白，不写「值得注意的是……」。如果一句话可以变成项目符号，就变成项目符号。如果一个项目符号可以删掉，就删掉。如果一个词不在 `../../../vendor/codebase-design/SKILL.md` 术语表中，在发明新词之前先找一个术语表中有的词。

package/template/workflows/dev/D-docs-sync/D-docs-sync.md

@@ -40,6 +40,8 @@ keywords: [docs-sync, changelog, readme, agents, documentation, 文档同步]
 - `changelog-contract.md`：更新 CHANGELOG 类文档时读取。
 - `state-json-schema.md`：初始化、读取或写回 docs-sync state 时读取。
 
+> **通用语言对齐**：对外文档（README / AGENTS）中的领域术语以 `speculo/.speculo/.config/context/CONTEXT.md` 为准；同步中若发现文档与 CONTEXT 术语漂移，交由 `../M-domain-modeling/M-domain-modeling.md` 沉淀，docs-sync 本身不另立或重定义领域术语。
+
 ## 阶段
 
 ### 1. State Read — 读取同步状态

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

@@ -141,4 +141,4 @@
 - [ ] 一次性原型已删除（或移到明确标记的调试位置）
 - [ ] 最终正确的假设已写在 commit / PR 信息中——以便下一个调试者从中学习
 
-**然后问：什么能预防这个 Bug？** 如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体信息交给 `/improve-codebase-architecture` 技能处理。在修复**之后**提出建议，而不是之前——你现在比开始时拥有更多信息。
+**然后问：什么能预防这个 Bug？** 如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体信息交给横向工作流 `../A-improve-architecture/A-improve-architecture.md` 处理。在修复**之后**提出建议，而不是之前——你现在比开始时拥有更多信息。

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

@@ -14,6 +14,22 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 使用垂直切片（示踪弹）将计划、规格或 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 诊断结论或当前对话上下文
@@ -40,14 +56,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 +76,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 +109,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 完成后的可观察结果。
 
@@ -77,8 +78,25 @@
 - 不可逾越约束（来自 `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 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
@@ -90,9 +108,12 @@
 - **类型：** `AFK` | `HITL`
 - **阻塞于：** 切片 M（或「无」）
 - **覆盖：** PRD 章节 / US 编号 / 用户故事简述
+- **需阅读的文件：** 实现本切片前需理解的现有代码（| 文件 | 目的 | 表）；单文件小改可省略
 - **交付物：** 该切片产出的具体文件/模块/功能清单
+- **需修改的文件：** 本切片要改动的文件（| 文件 | 改动内容 | 表）；新增文件标 **新增**，重度重构标 **重度重构**
 - **保留/不动：** 本切片**不能碰**的代码/契约/数据（如冻结常量、共享依赖、邻近功能）；无则写「无」
 - **复用：** 复用哪些现有能力（模块/文件/命令）
+- **实现要点：** 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略
 - **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成；**删除型切片须含残留扫描**（如 `grep -rn "<符号>" <范围>` 应 0 命中）
 - **对齐：** PRD FR-xxx 或 issue 引用
 - **ADR 引用：** （可选）关联的工程层 ADR 编号
@@ -100,7 +121,8 @@
 
 - `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
 - `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
-- 切片改动面较宽时，可在「交付物」下用 `| 文件 | 改动 |` 表逐文件列出（新增/修改/删除/**保留**），提升信息密度。
+- **需阅读/需修改的文件表**：借鉴高质量 plan 的双表模式——读文件表让执行者知道上下文边界，改文件表让执行者知道改动面和操作类型（新增/修改/重构）。单文件小改的切片可省略读文件表。
+- **实现要点**：每个切片列出 3-7 条关键技术点，让执行者拿到切片就知道怎么下手。包含算法细节、并发控制、兼容/兜底策略等。
 
 ### 4. 横切关注点与铁律（贯穿所有切片）—— [必填]
 
@@ -155,15 +177,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 +200,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/{01-grill-with-docs → M-domain-modeling}/ADR-FORMAT.md

@@ -1,10 +1,10 @@
 # ADR 格式
 
-本辅助文档只定义项目 ADR 的写法。默认产物仍写入 `speculo/.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建项目 ADR。
+本文是项目架构决策记录（ADR）格式与判据的**单一事实源**，由 `dev/M-domain-modeling` 拥有，`dev/01`、`dev/04`、`dev/A` 等工作流按需引用。
 
-ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。
+默认产物写入调用方工作流的会话产物（如 `decision-log.md`、`domain-model-log.md`）；只有用户明确确认时，才按本格式创建项目 ADR。
 
-`speculo/.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
+ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`0001-slug.md`、`0002-slug.md`，以此类推。`speculo/.speculo/.config/adr/` 目录由 Speculo 初始化提供；如果目标项目缺失该目录，按需创建。
 
 ## 模板
 
@@ -44,6 +44,6 @@ ADR 存放在 `speculo/.speculo/.config/adr/` 目录下，使用顺序编号：`
 - **上下文之间的集成模式。** 「Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。」
 - **带有锁定效应的技术选型。** 数据库、消息总线、认证提供商、部署目标。不是每个库——只是那些换掉需要花一个季度的。
 - **边界和范围决策。** 「客户数据由 Customer 上下文拥有，其他上下文只通过 ID 引用。」明确的「不做」和「要做」同样有价值。
-- **刻意偏离显而易见的路径。** 「我们用原生 SQL 而非 ORM，因为 X。」任何理性读者会假设相反做法的地方。这能防止下一个工程师去“修复”某个刻意为之的设计。
+- **刻意偏离显而易见的路径。** 「我们用原生 SQL 而非 ORM，因为 X。」任何理性读者会假设相反做法的地方。这能防止下一个工程师去「修复」某个刻意为之的设计。
 - **代码中看不见的约束。** 「因为合规要求，我们不能用 AWS。」「因为合作方 API 合约，响应时间必须在 200 ms 以内。」
 - **拒绝理由不明显的替代方案。** 如果你考虑过 GraphQL 但因为某些微妙原因选了 REST，记录下来——否则六个月后会有人再次提议 GraphQL。

package/template/workflows/dev/{01-grill-with-docs → M-domain-modeling}/CONTEXT-FORMAT.md

@@ -1,6 +1,8 @@
 # CONTEXT.md 格式
 
-本辅助文档只定义项目术语表的写法。默认产物仍写入 `speculo/.speculo/dev/<change>/context-map.md` 和 `speculo/.speculo/dev/<change>/decision-log.md`；只有用户明确确认时，才按本格式创建或更新 `speculo/.speculo/.config/context/CONTEXT.md` / `speculo/.speculo/.config/context/CONTEXT-MAP.md`。
+本文是项目术语表（通用语言）写法的**单一事实源**，由 `dev/M-domain-modeling` 拥有，`dev/01`、`dev/02`、`dev/04`、`dev/D`、`dev/A` 等工作流按需引用。
+
+只有用户明确确认时，才按本格式创建或更新 `speculo/.speculo/.config/context/CONTEXT.md` / `speculo/.speculo/.config/context/CONTEXT-MAP.md`；未确认的术语只记录到调用方工作流的会话产物（如 `decision-log.md`、`domain-model-log.md`）。
 
 ## 结构
 
@@ -56,7 +58,7 @@ _避免使用_：Client、buyer、account
 - **Ordering ↔ Billing**：共享 `CustomerId` 和 `Money` 类型
 ```
 
-技能会自动推断适用哪种结构：
+本工作流自动推断适用哪种结构：
 
 - 如果 `speculo/.speculo/.config/context/CONTEXT-MAP.md` 存在，读取它以查找上下文
 - 如果只有 `speculo/.speculo/.config/context/CONTEXT.md`，则为单上下文