@namewta/speculo 0.1.15 → 0.1.17

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

@@ -0,0 +1,118 @@
+---
+id: dev/M-domain-modeling
+category: dev
+name: Domain Modeling
+description: 主动构建与精炼项目领域模型——挑战术语、压测边界，并在决策结晶当下沉淀通用语言（CONTEXT）与架构决策（ADR）
+keywords: [domain-modeling, context, adr, ubiquitous-language, 领域建模, 术语, 通用语言]
+---
+
+# Domain Modeling 工作流执行指引
+
+本工作流是 `dev/M` 入口，也是 dev 分类**领域模型的横向纪律与格式单一事实源**：在设计与讨论中*主动*构建、精炼项目领域模型，并在术语和决策结晶的当下立即沉淀。它既可独立进入（`dev/M`），也被 `dev/01`、`dev/02`、`dev/04`、`dev/D` 与 `dev/A` 在各自阶段中引用。
+
+> **主动 vs 消费**：仅仅*读取* CONTEXT 取词汇**不是**本工作流——那是任何工作流都该有的一行习惯。本工作流用于你正在*改变*模型，而不仅是消费它时。
+
+## 内置指引
+
+### 何时使用
+
+当 dev 工作流需要*改变*领域模型时使用——挑战或锐化术语、消解一词多义、记录难以逆转的架构决策、维护通用语言。典型触发：
+
+- 用户用词与现有 CONTEXT 冲突，或同一概念出现多个词
+- 讨论领域关系，需要用具体场景压测边界
+- 出现「难以逆转 + 缺上下文会令人意外 + 真实权衡」的决策，值得记成 ADR
+- 实现 / 重构 / PRD 中引入了 CONTEXT 里尚不存在的概念
+
+### 输入
+
+- 用户的计划、设计或当前讨论
+- `speculo/.speculo/.config/context/CONTEXT.md`、`speculo/.speculo/.config/context/CONTEXT-MAP.md`、`speculo/.speculo/.config/adr/` 与相关代码
+- 当前 change 目录：`speculo/.speculo/dev/<change>/`（`<change>` 必须为 `YYYY-MM-DD-<kebab-name>`，例：`2026-06-12-model-ordering`）
+
+### 输出
+
+- 会话沉淀记录：`speculo/.speculo/dev/<change>/domain-model-log.md`
+- 经用户确认后更新 `speculo/.speculo/.config/context/CONTEXT.md`（或 `CONTEXT-MAP.md`）
+- 经用户确认后在 `speculo/.speculo/.config/adr/` 新建 ADR
+- 需要用户决策的术语 / 边界问题，每次只问一个
+
+（`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）
+
+### 会话期间（主动纪律）
+
+在讨论进行中持续执行，**不要批量**——在发生的当下捕获：
+
+- **对照词汇表挑战**：用户用词与 CONTEXT 现有语言冲突时立即指出。「你的词汇表把『取消』定义为 X，但你似乎指 Y——到底是哪个？」
+- **锐化模糊语言**：用户用含混或一词多义术语时，提出一个精确的规范术语。「你说『账户』——是指 Customer 还是 User？它们是不同的东西。」
+- **用具体场景压测**：讨论领域关系时，发明探测边界的场景，迫使精确界定概念之间的边界。
+- **与代码交叉引用**：用户陈述某事如何运作时，核对代码是否一致；矛盾即指出。「你的代码取消整个 Order，但你刚说支持部分取消——哪个对？」
+- **内联沉淀**：术语一旦解决，立即按 `CONTEXT-FORMAT.md` 更新（用户确认后写 `.config/context/`）；未确认的只记到 `domain-model-log.md`。
+- **有节制地提供 ADR**：仅当「难以逆转 + 缺上下文会令人意外 + 真实权衡的结果」三条全部满足时，才按 `ADR-FORMAT.md` 提议创建 ADR；任一不满足则跳过。
+
+> `CONTEXT.md` 必须完全不含实现细节——它是词汇表，不是 spec、草稿本或实现决策仓库。
+
+### 渐进披露
+
+- `CONTEXT-FORMAT.md`：撰写或更新项目术语表（CONTEXT / CONTEXT-MAP）时读取——**通用语言格式的单一事实源**。
+- `ADR-FORMAT.md`：判断是否该写 ADR、以何种格式写时读取——**ADR 格式与判据的单一事实源**。
+
+### 独立使用
+
+本工作流**零硬依赖**，无需预先执行其他工作流即可独立进入（`dev/M`）。只需用户的领域讨论 + 当前 git 仓库即可启动；缺 change 目录时按下「自初始化」创建。
+
+### 缺少 change 目录时的自初始化
+
+若当前无对应 change 目录：
+
+1. 从用户意图提取 `<kebab-name>`（如 `model-ordering-terms`）
+2. 创建 `speculo/.speculo/dev/<YYYY-MM-DD>-<kebab-name>/`
+3. 初始化 `.status.json`：
+   ```json
+   {
+     "dev_entry": "dev/M",
+     "current_phase": "1. Model Session",
+     "phase_history": [],
+     "change_status": "active",
+     "embedded_guides": ["domain-modeling"],
+     "terms_resolved": [],
+     "adr_candidates": [],
+     "context_write_status": "none"
+   }
+   ```
+4. 在 `speculo/.speculo/dev-status.json` 的 `active` 数组追加该 change 目录名
+
+## 阶段
+
+> **惰性创建文件**——只在需要写入时才创建。`.config/context/CONTEXT.md` 与 `.config/adr/` 由 Speculo 初始化提供；若目标项目缺失，在第一个术语 / ADR 解决时按需创建。
+
+### 1. Model Session — 词汇与决策沉淀
+- 规范：本入口「会话期间（主动纪律）」+ 同目录 `CONTEXT-FORMAT.md`、`ADR-FORMAT.md`
+- 模板：`../_templates/domain-model-log-template.md`
+- 产物：`domain-model-log.md`；经用户确认后更新 `.config/context/` 与 `.config/adr/`
+- 完成准则：
+  - 每个被挑战 / 锐化的术语都有结论（已写入 CONTEXT 或记为 `[待确认]`）
+  - 每个 ADR 候选都已按三条判据裁决（提议创建，或显式跳过并记原因）
+  - 写入 `.config/context/` 或 `.config/adr/` 的内容均经用户确认
+  - `domain-model-log.md` 无残留 `[TODO:]`
+
+## 依赖
+
+- 硬依赖：无
+- 软依赖：无。可独立进入；也被 `../01-grill-with-docs/01-grill-with-docs.md`、`../02-prd/02-prd.md`、`../04-finalize/04-finalize.md`、`../D-docs-sync/D-docs-sync.md`、`../A-improve-architecture/A-improve-architecture.md` 在其阶段中引用。
+
+## 状态扩展字段
+
+本工作流需在同 change 的 `.status.json` 追加：
+
+- `dev_entry` (string) — 固定为 `dev/M`
+- `embedded_guides` (array) — 包含 `domain-modeling`
+- `terms_resolved` (array) — 本会话解决的术语及结论
+- `adr_candidates` (array) — ADR 候选及裁决（`created` | `skipped` + 原因）
+- `context_write_status` (none | logged | context-updated | adr-created) — 领域模型沉淀状态
+
+## 完成与状态更新
+
+- 进入 phase 时更新 `current_phase` 和 `phase_history`。
+- 术语 / 决策沉淀后更新 `terms_resolved`、`adr_candidates`、`context_write_status`。
+- 写 `.config/context/` 或 `.config/adr/` **前必须经用户确认**（持久化写入责任表中，这两处 AI 仅在用户确认后写入）。
+- 本工作流不自动完成 change；嵌入其他工作流时随宿主流程推进。

package/template/workflows/dev/_templates/domain-model-log-template.md

@@ -0,0 +1,20 @@
+> **服务工作流：** `../M-domain-modeling/M-domain-modeling.md`
+> **产物文件名：** `domain-model-log.md`
+> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
+
+# Domain Model Log
+
+## 术语沉淀
+[TODO: 逐条记录本会话挑战或锐化的术语。每条含：术语、结论（规范词 + 避免使用的别名）、是否已写入 `speculo/.speculo/.config/context/CONTEXT.md`（已写入 / `[待确认]`）。]
+
+## 场景压测
+[TODO: 记录用于界定边界的具体场景，以及由此确定的概念边界结论。无则写「无」。]
+
+## 代码交叉核对
+[TODO: 记录领域陈述与代码现实的核对结果（一致 / 矛盾及处置）。无则写「无」。]
+
+## ADR 候选与裁决
+[TODO: 逐条列出 ADR 候选。每条按三条判据（难以逆转 / 缺上下文会令人意外 / 真实权衡）裁决：`created`（编号 + `.config/adr/` 路径）或 `skipped`（原因）。无则写「无」。]
+
+## 待确认
+[TODO: 仍需用户决策的术语 / 边界 / 决策分支，每条一行。无则写「无」。]

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 风险则继承细化。纯增量小改可删除本节。]
 

package/template/workflows/dev/03-tdd/deep-modules.md

@@ -1,33 +0,0 @@
-# 深模块
-
-来自《A Philosophy of Software Design》：
-
-**深模块** = 小接口 + 大量实现
-
-```
-┌─────────────────────┐
-│     小接口           │  ← 方法少，参数简单
-├─────────────────────┤
-│                     │
-│                     │
-│     深层实现         │  ← 复杂逻辑被隐藏
-│                     │
-│                     │
-└─────────────────────┘
-```
-
-**浅模块** = 大接口 + 很少实现（应避免）
-
-```
-┌─────────────────────────────────┐
-│           大接口               │  ← 方法多，参数复杂
-├─────────────────────────────────┤
-│  薄实现                         │  ← 只是透传
-└─────────────────────────────────┘
-```
-
-设计接口时，问自己：
-
-- 能否减少方法数量？
-- 能否简化参数？
-- 能否把更多复杂性隐藏在里面？

package/template/workflows/dev/03-tdd/interface-design.md

@@ -1,31 +0,0 @@
-# 面向可测试性的接口设计
-
-好的接口让测试变得自然：
-
-1. **接受依赖，而不是自己创建**
-
-   ```typescript
-   // 易于测试
-   function processOrder(order, paymentGateway) {}
-
-   // 难以测试
-   function processOrder(order) {
-     const gateway = new StripeGateway();
-   }
-   ```
-
-2. **返回结果，而不是产生副作用**
-
-   ```typescript
-   // 易于测试
-   function calculateDiscount(cart): Discount {}
-
-   // 难以测试
-   function applyDiscount(cart): void {
-     cart.total -= discount;
-   }
-   ```
-
-3. **小表面积**
-   - 方法越少 = 需要的测试越少
-   - 参数越少 = 测试准备越简单