@namewta/speculo 0.1.15 → 0.1.17

package/package.json

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

package/template/skills/speculo-write/SKILL.md

@@ -7,6 +7,8 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 
 # Speculo Write
 
+创作任何 Speculo 资产的根本美德是**可预测性**——让代理每次运行采用相同的*过程*（而非相同输出）。本 skill 自带全部 Speculo 规范（路径、frontmatter、持久化）与质量杠杆（`references/authoring-quality-levers.md`），并以身作则遵守它们。
+
 ## 何时使用
 
 当任务是新增、迁移、融合或改造 Speculo 的 `workflows/`、`skills/`、`commands/`、配套模板、引用资料或 `speculo/.speculo/` 状态骨架时使用。
@@ -37,13 +39,14 @@ description: 创建或改造 Speculo workflows、skills、commands 的原子能
 
 1. **判定资产类型** —— workflow、skill、command，或组合。规则见 `references/asset-selection-sop.md`。
 2. **读取同类资产** —— 看目标目录里现有资产的真实写法，对齐风格，不直接套用外部技能格式。
-3. **提取可复用行为** —— 从参考材料保留核心内容（触发、输入输出、铁律、边界、失败恢复、模板），只规范化路径、frontmatter、产物和渐进披露。
-4. **设计文件结构** —— 入口、别名、状态字段、产物路径和验证清单。
-5. **实施** —— 实施前确认不会覆盖用户已有改动；实施后同步索引、文档和测试。
-6. **验证** —— 旧路径和旧工具名没有回流，运行项目测试或记录无法运行原因；提交前过一遍 `references/validation-checklist.md`。
+3. **提取可复用行为** —— 从参考材料保留核心内容（触发、输入输出、铁律、边界、失败恢复、模板），只规范化路径、frontmatter、产物和渐进披露；跨资产共享的规范**引用单一事实源、不复制**。
+4. **设计文件结构** —— 入口、别名、状态字段、产物路径和验证清单；按**信息层级**（步骤 / 文件内参考 / 已披露参考）排布，保持入口阶梯顶部清晰，能下推就下推（见 `references/authoring-quality-levers.md`）。
+5. **实施** —— 实施前确认不会覆盖用户已有改动；用**主导词**锚定执行与调用，完成准则做到可检验且在重要处穷尽；实施后同步索引、文档和测试。
+6. **验证** —— 旧路径和旧工具名没有回流，运行项目测试或记录无法运行原因；对照 `references/authoring-quality-levers.md` 的失败模式与空操作测试逐句修剪；提交前过一遍 `references/validation-checklist.md`。
 
 ## 渐进披露
 
+- `references/authoring-quality-levers.md`：贯穿全程的质量理论——可预测性、主导词、信息层级、完成标准、何时拆分、修剪与失败模式；设计结构、措辞、修剪和验收时读取。
 - `references/asset-selection-sop.md`：判断应做 workflow、skill 还是 command 时读取。
 - `references/workflow-authoring-sop.md`：创建或改造 workflow、phase、template、索引和状态字段时读取。
 - `references/skill-authoring-sop.md`：创建原子 skill、迁移外部技能、拆分 references 时读取。

package/template/skills/speculo-write/references/asset-selection-sop.md

@@ -4,6 +4,8 @@
 
 把用户的“做一个能力”翻译成 Speculo 的正确资产形态：workflow、skill、command，或它们的组合。
 
+> **粒度即拆分成本**（见 `authoring-quality-levers.md`「何时拆分」）：把流程切成 workflow 的多个 phase，是为了把**后续步骤**移出视野、防过早完成（**按序列拆分**）；把能力抽成可复用 skill，是为了独立触达、值回其 `description` 常驻系统提示的负载（**按调用拆分**）。每次切割都有成本，只在物有所值时拆。
+
 ## 判定规则
 
 ### 做 Workflow

package/template/skills/speculo-write/references/authoring-quality-levers.md

@@ -0,0 +1,61 @@
+# Authoring Quality Levers
+
+把「编写出色技能」的领域模型内化到 Speculo 资产创作（workflow / skill / command）。**所有杠杆都服务一个根本美德：可预测性**——让代理每次运行采用相同的*过程*（而非相同的输出）。成本与可维护性是它的症状，不是对手。
+
+本文是质量理论的**单一事实源**：`skill-authoring-sop.md`、`workflow-authoring-sop.md`、`command-authoring-sop.md`、`validation-checklist.md` 按需引用本文，不复述其内容。
+
+## 主导词（Leading Word）
+
+一个已存在于模型预训练中的紧凑概念（如 *lesson*、*fog of war*、*tracer bullet*；Speculo 里的*切片 / 接缝 / 红绿重构 / 门控 / 深模块*），代理运行资产时用它思考。作为一个 token 反复出现（而非整句），用最少 token 锚定整个行为区域。
+
+它两次服务可预测性：在正文锚定**执行**（每次遇到该词都采取相同行为）；在 `description` 与别名里锚定**调用**（同一个词出现在提示、文档、代码里，代理更可靠地触发该资产）。
+
+- 优先用预训练已有的词；自造词不招募任何先验，要用定义 token 付费。
+- 在 `description`、phase 名、完成准则里用你*真正会用来唤起该资产*的主导词。
+- 把「在三处拼写出的三元组」「用一句话指一个想法」折叠成一个 token。
+
+## 信息层级（Information Hierarchy）
+
+内容按代理需要它的紧迫程度排成**一个阶梯**，由两次切分产生：
+
+1. **步骤**——入口里的有序操作（workflow 的 `## 阶段`、skill 的 `## 执行步骤`）。主层级。每个步骤以**完成标准**结束。
+2. **文件内参考**——入口里随手查阅的定义 / 规则 / 事实。次层级。常是合法的扁平同级集合（审查类技能每条规则平级，不是坏味道）。
+3. **已披露参考**——推到 `references/` 或 phase 文件，经**上下文指针**按需加载。
+
+不是每个资产都有步骤：可以全是步骤、全是参考、或两者兼有。保持阶梯顶部清晰，能下推就下推。
+
+**渐进披露**＝沿阶梯下移以保护层级（主要不是 token 优化）。由**分支**授权：只把*部分*运行才需要的材料推到指针后，每条路径都需要的内联。**上下文指针的措辞**（而非目标）决定代理何时、多可靠地取用——指针对必备材料触发不可靠时，先改措辞，失败才内联。
+
+**就近放置（Co-location）**：一个概念的定义、规则、注意事项放在同一标题下，而非散落——读一部分就连带看到相邻内容。与「重复」相反：重复是一个含义出现在多处，散落是一个含义被拆到多处。
+
+## 完成标准（Completion Criterion）
+
+告诉代理一个工作单元已完成的判断条件。两个属性使它成为杠杆，而不只是质量指标：
+
+- **可检验**：代理能区分完成与未完成吗？模糊的界限（「理解达到」）让代理宣布完成并滑向下一步（**过早完成**）。
+- **穷尽**：「每个修改过的模型都已纳入」强于「生成变更列表」。穷尽轴*不受步骤限制*，也约束扁平参考（「每条规则都已应用」）——这正是无步骤资产仍能驱动彻底**调研工作**的力量。
+
+最强的完成标准既可检验又穷尽。Speculo 的「`xxx.md` 无残留 `[TODO:]`」是可检验的最低线；在重要处补穷尽项。
+
+## 何时拆分
+
+每次切割都消耗成本，只在物有所值时拆：
+
+- **按序列拆分**——当一个步骤的**后续步骤**诱使代理匆忙了事（过早完成）时，把序列拆成两段、把后续步骤移出视野。这正是 Speculo 把 workflow 切成 phase、把 phase 隔离到独立文件的原因。注意反面：把序列并回一个文件，会把后续步骤暴露给当前步骤。
+- **按复用 / 调用拆分**——当一段能力会被多个入口复用，或需要独立触发时，抽成 skill。你为它的 `description`（常驻系统提示）付出代价，因此这种独立触达必须值回票价。判定细节见 `asset-selection-sop.md`。
+
+## 修剪
+
+- **单一事实来源**：每个含义只存在于唯一权威位置，改行为只需一处编辑。跨资产共享的规范放进被引用的单一文件（如 `vendor/codebase-design`、本文），引用方**不复制**。
+- **相关性**：逐行问「它是否仍影响资产行为？」——越短的资产越容易保持相关。
+- **空操作测试**：逐*句*问「相对默认行为，这句改变了什么吗？」模型默认就会做的事＝空操作，付出负载却什么都没说。果断删整句，而非修剪词语。弱主导词（代理本就 thorough 时还说 *be thorough*）是空操作——换更强的词（*relentless*），而非换技术。
+
+## 失败模式
+
+用于诊断资产问题：
+
+- **过早完成**——步骤真正完成前就收尾，注意力滑向「完成态」。先锐化完成标准（廉价、局部）；只有当它本质模糊*且*确实观察到匆忙时，才用序列拆分隐藏后续步骤（且只在真正的上下文边界——command 交接 / 子代理派发——才有效，内联的引用清不掉后续步骤）。
+- **重复**——同一含义有多个事实来源。涨维护成本与 token，并夸大该含义在阶梯上的权重。是主导词的意外逆操作（主导词有意重复一个 *token* 而非*含义*）。
+- **沉积**——陈旧层因「加安全、删有风险」而堆积，得钻过它们才找到仍有效的内容。无修剪纪律资产的默认命运。
+- **蔓延**——单纯太长（即便每行都鲜活、独特）。解药是信息层级：把参考推到指针后，按分支或序列拆分。
+- **空操作**——见上「修剪」。

package/template/skills/speculo-write/references/command-authoring-sop.md

@@ -93,4 +93,4 @@ command 产物模板内联在文件末尾。模板占位符使用 `[TODO: ...]`
 - 归档路径是否位于 `speculo/.speculo/commands/<YYYY-MM-DD>-<command>-<topic>/`
 - 被调用 skill 是否没有自选 `temp/`、系统临时目录或项目根目录作为持久化位置
 
-`speculo/.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`。
+`speculo/.speculo/commands/` 归档路径、frontmatter 最小集与写入责任见 `persistence-contract-sop.md`；`description`、完成准则与修剪的质量杠杆见 `authoring-quality-levers.md`。

package/template/skills/speculo-write/references/skill-authoring-sop.md

@@ -3,6 +3,8 @@
 本文是 Speculo 原子 skill 的编写规范，复刻通用「编写技能」流程并收敛到 Speculo 约束。
 本文已内化全部所需规范；编写 skill 时**不读仓库 `docs/`**，只读本 skill 的 `references/`。
 
+质量理论（**可预测性**、**主导词**、**信息层级**、**完成标准**、**修剪**、**失败模式**）是所有 Speculo 资产共享的单一事实源，见 `authoring-quality-levers.md`；本文只补 skill 特有的流程与约束，不复述理论。
+
 ## 流程
 
 1. **收集需求** —— 向用户确认：
@@ -60,6 +62,8 @@ description 是 **agent 决定加载哪个 skill 时唯一能看到的内容**
 - 第三人称
 - 第一句：做什么
 - 第二句：「当 [具体触发条件] 时使用」
+- 用**主导词**措辞触发条件——你真正会用来唤起该 skill 的那个词；同一个词出现在描述、文档、代码里会更可靠地触发（见 `authoring-quality-levers.md`）
+- 每个分支只写一个触发器：换名重写同一分支是**重复**，折叠它
 
 **好的例子**：
 
@@ -132,6 +136,8 @@ description: <能力 + 触发场景，第三人称>
 
 reference 文件用 kebab-case，**按任务而非来源**命名（`workflow-authoring-sop.md`，不是 `from-specforge.md`）。
 
+渐进披露的本质是保护**信息层级**、让入口阶梯顶部保持清晰（不只是省 token），由**分支**授权：只把*部分*运行才需要的材料推到指针后，每条路径都需要的内联。指针的**措辞**决定取用时机与可靠性——必备材料触发不可靠时先改措辞、失败才内联（见 `authoring-quality-levers.md`）。
+
 ## 何时添加脚本
 
 **加 `scripts/`**，当操作确定且反复执行：
@@ -199,4 +205,8 @@ skill **禁止自行选择**持久化位置，包括：
 - [ ] 没有 README / INSTALLATION / CHANGELOG 等冗余文件
 - [ ] 没有时效性信息、旧项目路径、旧工具名或绝对路径绑定
 - [ ] 术语一致、含具体示例、引用只有一层深度
+- [ ] description 与正文用**主导词**锚定调用与执行
+- [ ] 完成标准 / 审查项**可检验**，重要处**穷尽**（驱动彻底调研工作，防过早完成）
+- [ ] 逐句过**空操作测试**（删掉模型默认就会做的句子），无**重复 / 沉积 / 蔓延**
+- [ ] 跨资产共享规范引用**单一事实源**、未复制
 - [ ] 若是内置资产，CLI tests 覆盖复制该 skill

package/template/skills/speculo-write/references/validation-checklist.md

@@ -16,6 +16,16 @@
 - [ ] command frontmatter 包含 `id`、`type: command`、`name`、`description`，可选 `keywords`
 - [ ] 没有把 phases、templates、depends_on、status_extensions 写进 frontmatter
 
+## 质量杠杆检查
+
+> 适用于所有资产类型；理论见 `authoring-quality-levers.md`。
+
+- [ ] description / 入口用**主导词**锚定调用，正文用同一主导词锚定执行
+- [ ] 内容按**信息层级**排布（步骤 / 文件内参考 / 已披露参考），入口阶梯顶部清晰
+- [ ] 每个步骤 / phase 的**完成标准**可检验，重要处穷尽
+- [ ] 跨资产共享含义只有**单一事实源**，引用方未复制
+- [ ] 逐句过**空操作测试**，无**过早完成 / 重复 / 沉积 / 蔓延**诱因
+
 ## Workflow 检查
 
 - [ ] 入口正文包含 `## 阶段`

package/template/skills/speculo-write/references/workflow-authoring-sop.md

@@ -1,5 +1,7 @@
 # Workflow Authoring SOP
 
+phase 的切分、完成准则与措辞遵循 `authoring-quality-levers.md` 的质量杠杆（**按序列拆分**隐藏后续步骤防过早完成、**完成标准**可检验且穷尽、**主导词**锚定调用与执行）；本文只补 workflow 特有的结构与路径约束。
+
 ## 入口结构
 
 workflow 放在 `template/workflows/<cat>/`，`<cat>` 只能是 `dev`、`doc`、`ops`。

package/template/vendor/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# 深化（Deepening）
+
+如何在给定依赖关系的情况下，安全地深化一组浅模块。假定使用 [SKILL.md](SKILL.md) 中的术语——**module（模块）**、**interface（接口）**、**seam（接缝）**、**adapter（适配器）**。
+
+## 依赖分类
+
+在评估深化候选时，对其依赖进行分类。分类决定了深化后的模块如何跨接缝进行测试。
+
+### 1. 进程内（In-process）
+
+纯计算、内存状态、无 I/O。始终可深化——合并模块，直接通过新接口进行测试。不需要适配器。
+
+### 2. 本地可替换（Local-substitutable）
+
+具有本地测试替代方案的依赖（Postgres 用 PGLite、内存文件系统）。如果存在替代方案则可深化。深化后的模块在测试套件中运行替代方案进行测试。接缝是内部的；模块外部接口处没有端口。
+
+### 3. 远程但自有（Remote but owned）（端口与适配器）
+
+跨网络边界的自有服务（微服务、内部 API）。在接缝处定义一个**端口（port）**（接口）。深度模块拥有逻辑；传输层作为**适配器（adapter）**注入。测试使用内存适配器。生产环境使用 HTTP/gRPC/队列适配器。
+
+推荐形式：*"在接缝处定义一个端口，为生产环境实现 HTTP 适配器，为测试实现内存适配器，这样即使逻辑部署跨网络，仍位于一个深度模块中。"*
+
+### 4. 真正外部（True external）（Mock）
+
+你无法控制的第三方服务（Stripe、Twilio 等）。深化后的模块将外部依赖作为注入端口接收；测试提供 mock 适配器。
+
+## 接缝纪律
+
+- **一个适配器意味着假设的接缝。两个适配器才意味着真正的接缝。** 除非至少有两个适配器是合理的（通常是生产 + 测试），否则不要引入端口。单适配器接缝只是间接层。
+- **内部接缝 vs 外部接缝。** 深度模块可以有内部接缝（对其实现私有，由其自身测试使用）以及其接口处的外部接缝。不要因为测试使用了内部接缝就通过接口暴露它们。
+
+## 测试策略：替换，而非叠加
+
+- 一旦深化模块接口层面的测试存在，浅模块的旧单元测试就成为废料——删除它们。
+- 在深化模块的接口层面编写新测试。**接口就是测试面**。
+- 测试通过接口断言可观察的结果，而非内部状态。
+- 测试应能经受内部重构——它们描述的是行为，而非实现。如果一个测试在实现变更时必须随之改变，那它就是在测试接口背后的内容。

package/template/vendor/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# 设计两次（Design It Twice）
+
+当用户想要为选定的深化候选探索替代接口时，使用此并行子代理模式。基于"设计两次"（Ousterhout）——你的第一个想法不太可能是最好的。
+
+使用 [SKILL.md](SKILL.md) 中的术语——**module（模块）**、**interface（接口）**、**seam（接缝）**、**adapter（适配器）**、**leverage（杠杆）**。
+
+## 流程
+
+### 1. 界定问题空间
+
+在生成子代理之前，为选定候选编写面向用户的问题空间说明：
+
+- 任何新接口需要满足的约束
+- 它将依赖的依赖项，以及它们属于哪个类别（参见 [DEEPENING.md](DEEPENING.md)）
+- 一个粗略的说明性代码草图，用于将约束具体化——不是提案，只是将约束变得具体的方式
+
+将此展示给用户，然后立即进入第 2 步。用户在子代理并行工作时阅读和思考。
+
+### 2. 生成子代理
+
+使用 Agent 工具并行生成 3 个以上的子代理。每个子代理必须为深化后的模块生成一个**截然不同**的接口。
+
+为每个子代理提供一个单独的技术概要（文件路径、耦合细节、来自 [DEEPENING.md](DEEPENING.md) 的依赖类别、接缝背后的内容）。该概要独立于第 1 步中面向用户的问题空间说明。给每个代理不同的设计约束：
+
+- 代理 1："最小化接口——目标是最多 1–3 个入口点。最大化每个入口点的杠杆效应。"
+- 代理 2："最大化灵活性——支持多种用例和扩展。"
+- 代理 3："针对最常见调用方优化——让默认情况变得简单。"
+- 代理 4（如适用）："围绕端口与适配器设计跨接缝依赖。"
+
+在概要中同时包含 [SKILL.md](SKILL.md) 词汇和 CONTEXT.md 词汇，以便每个子代理在命名时与架构语言和项目的领域语言保持一致。
+
+每个子代理输出：
+
+1. 接口（类型、方法、参数——加上不变量、排序、错误模式）
+2. 使用示例，展示调用方如何使用
+3. 实现隐藏在接缝背后的内容
+4. 依赖策略和适配器（参见 [DEEPENING.md](DEEPENING.md)）
+5. 权衡——杠杆效应高的地方，薄弱的地方
+
+### 3. 展示与比较
+
+依次展示设计，以便用户逐一消化，然后用文字进行比较。通过**深度**（接口层面的杠杆效应）、**局部性**（变更集中的位置）和**接缝位置**进行对比。
+
+比较后，给出你自己的推荐：你认为哪个设计最强以及为什么。如果来自不同设计的元素可以很好地组合，提出一个混合方案。要有明确的观点——用户想要的是一个强有力的解读，而不是一份菜单。

package/template/vendor/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: 设计深层模块的共享词汇。适用于用户想要设计或改进模块接口、寻找深化机会、决定接缝位置、使代码更可测试或对 AI 更可导航，或其他技能需要深层模块词汇的场景。
+---
+
+# 代码库设计
+
+设计**深层模块**：大量行为隐藏在小型接口之后，放置在清晰的接缝处，通过该接口可测试。在任何设计或重构代码的地方使用这套语言和原则。目标是为调用者提供杠杆，为维护者提供局部性，为所有人提供可测试性。
+
+## 词汇表
+
+严格使用这些术语——不要替换为"组件"、"服务"、"API"或"边界"。一致的语言是全部要点。
+
+**模块**——任何有接口和实现的东西。刻意与规模无关：一个函数、类、包或跨层切片。*避免*：单元、组件、服务。
+
+**接口**——调用者正确使用模块必须知道的一切：类型签名，还有不变量、排序约束、错误模式、所需配置和性能特征。*避免*：API、签名（太窄——它们仅指向类型层面的表面）。
+
+**实现**——模块内部的内容，其代码体。区别于**适配器**：一个东西可以是一个小适配器带大实现（一个 Postgres 仓库）或一个大适配器带小实现（一个内存假对象）。当接缝是主题时用"适配器"；否则用"实现"。
+
+**深度**——接口处的杠杆：调用者（或测试）每学习单位接口能运用的行为量。一个模块是**深的**，当大量行为隐藏在小型接口之后；是**浅的**，当接口几乎和实现一样复杂。
+
+**接缝** *(Michael Feathers)*——一个可以在不编辑该处的情况下改变行为的地方；模块接口所在的*位置*。接缝放在哪里是其自身的设计决策，区别于接缝后面是什么。*避免*：边界（被 DDD 的有界上下文过载）。
+
+**适配器**——在接缝处满足接口的具体事物。描述*角色*（它填补哪个槽位），而非实质（里面是什么）。
+
+**杠杆**——调用者从深度中获得的东西：每学习单位接口获得更多能力。一个实现付出，在 N 个调用点和 M 个测试中获得回报。
+
+**局部性**——维护者从深度中获得的东西：变更、bug、知识和验证集中在一处，而不是分散在调用者中。一处修复，处处修复。
+
+## 深 vs 浅
+
+**深层模块** = 小接口 + 大量实现：
+
+```
+┌─────────────────────┐
+│   小型接口          │  ← 少数方法，简单参数
+├─────────────────────┤
+│                     │
+│   深层实现          │  ← 复杂逻辑隐藏
+│                     │
+└─────────────────────┘
+```
+
+**浅层模块** = 大接口 + 少量实现（应避免）：
+
+```
+┌─────────────────────────────────┐
+│       大型接口                  │  ← 许多方法，复杂参数
+├─────────────────────────────────┤
+│  薄实现                         │  ← 只是传递
+└─────────────────────────────────┘
+```
+
+设计接口时，问：
+
+- 我能减少方法数量吗？
+- 我能简化参数吗？
+- 我能隐藏更多复杂性在内部吗？
+
+## 原则
+
+- **深度是接口的属性，而非实现的属性。** 一个深层模块可以在内部由小型、可 mock、可替换的部件组成——它们只是不是接口的一部分。一个模块可以有**内部接缝**（对其实现私有，由其自己的测试使用）以及其接口处的**外部接缝**。
+- **删除测试。** 想象删除该模块。如果复杂性消失，它就是个传递。如果复杂性在 N 个调用者中重新出现，它就在赚取它的价值。
+- **接口就是测试表面。** 调用者和测试跨越同一接缝。如果你想测试到接口*之外*，模块的形状可能不对。
+- **一个适配器意味着假设的接缝。两个适配器意味着真实的接缝。** 除非某物确实在接缝处变化，否则不要引入接缝。
+
+## 为可测试性设计
+
+好的接口使测试变得自然：
+
+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. **小表面积。** 更少的方法 = 需要更少的测试。更少的参数 = 更简单的测试设置。
+
+## 关系
+
+- 一个**模块**有且仅有一个**接口**（它呈现给调用者和测试的表面）。
+- **深度**是**模块**的属性，对照其**接口**来衡量。
+- **接缝**是模块**接口**所在之处。
+- **适配器**位于**接缝**处并满足**接口**。
+- **深度**为调用者产生**杠杆**，为维护者产生**局部性**。
+
+## 拒绝的框架
+
+- **深度为实现行数与接口行数之比**（Ousterhout）：奖励填充实现。我们改用深度作为杠杆。
+- **"接口"作为 TypeScript `interface` 关键字或类的公共方法**：太窄——这里的接口包括调用者必须知道的每个事实。
+- **"边界"**：被 DDD 的有界上下文过载。说**接缝**或**接口**。
+
+## 深入探索
+
+- **给定依赖深化一个集群**——参见 [DEEPENING.md](DEEPENING.md)：依赖类别、接缝规范和替换而非分层的测试。
+- **探索替代接口**——参见 [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md)：启动并行子代理以几种截然不同的方式设计接口，然后比较深度、局部性和接缝位置。

package/template/workflows/dev/00-INDEX.md

@@ -26,6 +26,8 @@ keywords: [dev, 开发, workflow, index, 状态]
 | `dev/H` | `H-diagnose/H-diagnose.md` | hotfix / bug / 性能回退诊断，零依赖，可独立进入 |
 | `dev/R` | `R-review/R-review.md` | Spec / Engineering / Standards 三维度 diff 审查，零依赖，可独立进入 |
 | `dev/D` | `D-docs-sync/D-docs-sync.md` | 基于 git diff 同步 README、CHANGELOG、AGENTS 等对外文档 |
+| `dev/M` | `M-domain-modeling/M-domain-modeling.md` | 主动领域建模：挑战术语、压测边界，沉淀 CONTEXT 通用语言与 ADR；格式单一事实源，可嵌入其他 dev workflow，也可独立进入 |
+| `dev/A` | `A-improve-architecture/A-improve-architecture.md` | 深化机会扫描 + HTML 架构审查 + 质询，基于 `vendor/codebase-design` 词汇，零依赖，可独立进入 |
 
 ## 进入协议
 
@@ -50,8 +52,12 @@ keywords: [dev, 开发, workflow, index, 状态]
 - `review`：已有 fixed point 或用户要求审查时，从 `dev/R` 开始（零依赖，无需上游工作流产物）。
 - `finalize`：实现完成、需要完成前验证与状态收尾归档时，从 `dev/04` 开始。
 - `docs-sync`：需要基于 git 差异刷新对外文档时，从 `dev/D` 开始。
+- `domain-modeling`：需要主动澄清/锐化领域术语、维护 CONTEXT 与 ADR 时，从 `dev/M` 开始（零依赖；也被 `dev/01`、`dev/02`、`dev/04`、`dev/D`、`dev/A` 引用）。
+- `improve-architecture`：需要系统性发现并落实架构深化机会时，从 `dev/A` 开始（零依赖；建立在 `vendor/codebase-design` 词汇与 `dev/M` 领域模型之上）。
 
-> **独立入口说明：** `dev/H`、`dev/I`、`dev/R` 三个横向工作流均为零硬依赖设计。用户可直接从任一入口进入，无需预先执行 `dev/01`、`dev/02` 等主线工作流。当同 change 目录下缺少上游产物时，各工作流会自行通过代码库探索（git 考古、grep 搜索、文档扫描）采集所需上下文，仅在代码库无法确定的决策点上询问用户。
+> **独立入口说明：** `dev/H`、`dev/I`、`dev/R`、`dev/M`、`dev/A` 五个横向工作流均为零硬依赖设计。用户可直接从任一入口进入，无需预先执行 `dev/01`、`dev/02` 等主线工作流。当同 change 目录下缺少上游产物时，各工作流会自行通过代码库探索（git 考古、grep 搜索、文档扫描）采集所需上下文，仅在代码库无法确定的决策点上询问用户。
+>
+> **横向工作流的共享底座：** `dev/M`（领域模型）拥有 CONTEXT / ADR 格式的单一事实源；`dev/A`（架构深化）与 `dev/03`（TDD）共享 `vendor/codebase-design` 的设计词汇（模块 / 接口 / 接缝 / 适配器 / 深度 / 杠杆 / 局部性）。引用方一律不复制这些规范。
 
 ## 状态汇报
 

package/template/workflows/dev/01-grill-with-docs/01-grill-with-docs.md

@@ -8,7 +8,7 @@ keywords: [grill, context, adr, 术语, 决策]
 
 # Grill With Docs 工作流执行指引
 
-本工作流用于在 PRD 或实现前澄清领域语言、识别决策分支，并把已确认的上下文沉淀为当前 change 的可追踪产物。领域拷问、CONTEXT 格式和 ADR 判断规则已内置在本 workflow 目录中。
+本工作流用于在 PRD 或实现前澄清领域语言、识别决策分支，并把已确认的上下文沉淀为当前 change 的可追踪产物。**领域建模的主动纪律（挑战术语、锐化语言、压测边界）与 CONTEXT / ADR 格式由横向工作流 `../M-domain-modeling/M-domain-modeling.md` 拥有**，本工作流引用之，专注把拷问结论落到当前 change 的 `context-map.md` 与 `decision-log.md`。
 
 ## 内置指引
 
@@ -38,7 +38,7 @@ keywords: [grill, context, adr, 术语, 决策]
 
 每次只问一个问题，等待用户对当前问题的反馈后再继续。如果某个问题可以通过探索代码库来回答，就直接探索代码库。
 
-需要格式约定时读取同目录 `CONTEXT-FORMAT.md` 或 `ADR-FORMAT.md`。项目 CONTEXT 或 ADR 的创建、修改必须写入 `speculo/.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
+需要格式约定时读取 `../M-domain-modeling/CONTEXT-FORMAT.md` 或 `../M-domain-modeling/ADR-FORMAT.md`（格式单一事实源）；主动拷问的具体手法见 `../M-domain-modeling/M-domain-modeling.md`「会话期间（主动纪律）」。项目 CONTEXT 或 ADR 的创建、修改必须写入 `speculo/.speculo/.config/` 下，并符合本 workflow 的用户确认策略；未确认内容只记录到当前 change 的 `decision-log.md`。
 
 ### Worktree 隔离（条件）
 

package/template/workflows/dev/01-grill-with-docs/grill-decision.md

@@ -5,7 +5,7 @@
 - `speculo/.speculo/dev/<change>/context-map.md`
 - 用户当前方案或目标
 - 本 workflow 入口文件中的内置领域拷问指引
-- 同目录 `CONTEXT-FORMAT.md`、`ADR-FORMAT.md`
+- `../M-domain-modeling/CONTEXT-FORMAT.md`、`../M-domain-modeling/ADR-FORMAT.md`（格式单一事实源）；主动拷问手法见 `../M-domain-modeling/M-domain-modeling.md`
 
 ## 产物
 
@@ -14,7 +14,7 @@
 
 ## 填写引导
 
-1. 遵循 `01-grill-with-docs.md` 的内置指引，再按需读取同目录格式文档。
+1. 遵循 `01-grill-with-docs.md` 的内置指引，再按需读取 `../M-domain-modeling/` 的格式文档与主动拷问纪律。
 2. 每次只问一个会改变决策树的问题，并给出推荐答案。
 3. 对术语冲突、代码现实冲突和 ADR 候选直接指出。
 4. 用户确认后，把决策写入 `decision-log.md`。

package/template/workflows/dev/02-prd/02-prd.md

@@ -22,6 +22,8 @@ keywords: [prd, zoom-out, 需求, 计划]
 
 当 dev workflow 已完成足够上下文探索，需要把当前对话和代码理解沉淀成 PRD 时使用。不要重复访谈已明确的信息；综合当前对话、代码库事实、领域术语、ADR、模块候选和测试目标。
 
+PRD 综合统一使用 `speculo/.speculo/.config/context/CONTEXT.md` 的通用语言；若 PRD 引入或锐化了 CONTEXT 中尚不存在的领域术语，按横向工作流 `../M-domain-modeling/M-domain-modeling.md` 主动沉淀（用户确认后写入 `.config/context/`），不要让术语只活在 PRD 里。
+
 PRD 只写入 `speculo/.speculo/dev/<change>/prd.md`，overview 只写入 `speculo/.speculo/dev/<change>/overview.md`。不写项目根下的任意规划文档，不默认发布外部 issue。只有 tracker 已配置且用户明确要求时，才进入外部发布动作。
 
 （`<change>` 格式：`YYYY-MM-DD-<kebab-name>`）

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

@@ -8,7 +8,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 # TDD Implementation 工作流执行指引
 
-本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock、接口设计、deep module 和重构指引已内置在本 workflow 目录中。
+本工作流用于把 PRD、issue、诊断结论或用户明确任务实现为经过验证的代码变更。TDD 红绿重构、测试、mock 与重构指引内置在本 workflow 目录中；**深模块、接口、接缝、适配器的设计词汇与原则统一引用 `vendor/codebase-design`，本工作流不再复制**（见下「渐进披露」）。
 
 ## 内置指引
 
@@ -24,11 +24,17 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 
 ### 渐进披露
 
-- `tests.md`：设计测试方式时读取。
-- `mocking.md`：考虑 mock 边界时读取。
-- `deep-modules.md`：识别深模块机会时读取。
-- `interface-design.md`：设计可测试公共接口时读取。
-- `refactoring.md`：进入重构阶段时读取。
+测试与重构相关指引内置在同目录：
+
+- `tests.md`：设计测试方式（好测试 vs 坏测试）时读取。
+- `mocking.md`：考虑 mock 边界、为可 mock 性设计接口时读取。
+- `refactoring.md`：进入重构阶段、识别重构候选时读取。
+
+深模块 / 接口 / 接缝 / 适配器 / 杠杆 / 局部性的设计词汇与原则统一由 `vendor/codebase-design` 承载（**单一事实源，本工作流不复制**），按需直接引用：
+
+- `../../../vendor/codebase-design/SKILL.md`：设计深模块、判断深 vs 浅、为可测试性设计接口（接受依赖而非创建、返回结果而非副作用、小表面积）时读取——deep module 与可测试接口设计的权威来源。
+- `../../../vendor/codebase-design/DEEPENING.md`：判定依赖类别（进程内 / 本地可替换 / 端口与适配器 / mock）与「替换而非叠加」的测试策略时读取。
+- `../../../vendor/codebase-design/DESIGN-IT-TWICE.md`：需要为深化候选并行探索多个备选接口时读取。
 
 ### 消费 slices 切片契约
 

package/template/workflows/dev/03-tdd/mocking.md

@@ -1,40 +1,23 @@
-# 何时使用 Mock
+# Mock 边界与可 Mock 性
 
-只在**系统边界**处 mock：
+> **依赖类别**（进程内 / 本地可替换 / 端口与适配器 / 真正外部）与「在接缝处注入端口、生产用真实适配器、测试用内存或 mock 适配器」的判定，是设计词汇的一部分，见单一事实源 `../../../vendor/codebase-design/DEEPENING.md`。本文只覆盖**写测试时**的 mock 取舍与 SDK 风格接口。
+
+## 只在系统边界处 mock
 
 - 外部 API（支付、邮件等）
-- 数据库（有时——优先考虑测试数据库）
-- 时间/随机性
+- 数据库（有时——优先考虑测试数据库 / 本地可替换实现）
+- 时间 / 随机性
 - 文件系统（有时）
 
 不要 mock：
 
-- 你自己的类/模块
+- 你自己的类 / 模块
 - 内部协作者
 - 任何你能控制的东西
 
-## 为可 Mock 性设计
-
-在系统边界处，设计易于 mock 的接口：
-
-**1. 使用依赖注入**
-
-将外部依赖传入，而不是在内部创建：
-
-```typescript
-// 易于 mock
-function processPayment(order, paymentClient) {
-  return paymentClient.charge(order.total);
-}
-
-// 难以 mock
-function processPayment(order) {
-  const client = new StripeClient(process.env.STRIPE_KEY);
-  return client.charge(order.total);
-}
-```
+> 依赖注入（接受依赖而非内部创建）是让边界可 mock 的前提；该原则见 `../../../vendor/codebase-design/SKILL.md`「为可测试性设计」，本文不复制。
 
-**2. 优先使用 SDK 风格的接口，而非通用 fetcher**
+## 优先 SDK 风格接口，而非通用 fetcher
 
 为每个外部操作创建专用函数，而不是一个带条件逻辑的通用函数：
 

package/template/workflows/dev/03-tdd/tdd-plan.md

@@ -14,7 +14,7 @@
 ## 填写引导
 
 1. 遵循 `03-tdd.md` 的内置 TDD 指引。
-2. 按需读取同目录的接口设计、测试、mock 和 deep module 文档。
+2. 按需读取同目录 `tests.md` / `mocking.md`，以及设计词汇单一事实源 `../../../vendor/codebase-design/`（`SKILL.md` 深模块与可测试接口设计、`DEEPENING.md` 依赖类别与接缝、`DESIGN-IT-TWICE.md` 备选接口）。
 3. 与用户确认公共接口、最重要的行为和测试覆盖优先级。
 4. 拆出第一个 tracing slice，避免水平切片。
 5. 探索代码库时使用项目领域术语表，确保测试名称和接口词汇与项目语言一致，并尊重触及区域的 ADR。

package/template/workflows/dev/04-finalize/04-finalize.md

@@ -82,6 +82,7 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
   - 每条完成结论都有**本次运行**的命令与输出证据
   - 已对照来源（PRD / issue / slices / 用户任务）逐项核对需求清单
   - 无调试残留与推测性功能
+  - （如适用）实现期引入的新领域术语 / 架构决策已按 `../M-domain-modeling/M-domain-modeling.md` 沉淀到 CONTEXT / ADR（模型未漂移）；无新术语则不适用
   - `completion-verification.md` 无残留 `[TODO:]`
   - `.status.json` 的 `verification_status` 为 `verified` 或 `blocked`