@namewta/speculo 0.2.16 → 0.3.0

package/template/workflows/specdev/R-review-architecture/R-review-architecture.md

@@ -0,0 +1,77 @@
+---
+id: specdev/review-architecture
+type: workflow-entry
+workflow: specdev
+name: 架构审查
+description: 扫描代码仓寻找深层化机会——发现浅模块、接缝泄漏和局部性缺陷，以可视化 HTML 报告呈现候选方案，逐一访谈深化。
+keywords: [架构审查, 深化, 模块设计, 接缝, 重构, 可视化]
+---
+
+# 架构审查
+
+主动扫描代码仓发现架构摩擦，将其转化为可操作的深化方案——融合有机探索、可视化报告和访谈打磨。每一步引用内部子文件，不依赖外部 skill。
+
+在开始之前，读取当前变更的上下文与架构决策：
+
+- **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- **永久 ADR** —— 已确认并提升的架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- **永久 CONTEXT** —— 已确认并提升的领域词汇表：`<Path>{roots.state}/specdev/context/</Path>`
+
+如果当前 change 尚不存在或其下无 CONTEXT.md、ADR.md，静默继续——架构审查常是新变更的起点，change 的创建在步骤 4 用户选定候选后进行。
+
+## 流程
+
+### 1. 建立基准
+
+读取 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 建立架构评估词汇——module、interface、depth、seam、adapter、leverage、locality 八个术语及其原则。读取 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` 建立依赖分类（进程内/本地可替换/远程但自有/真正外部依赖）和接缝纪律基准。
+
+**完成标准**：架构术语、删除测试、接缝纪律和依赖分类已加载；CONTEXT.md 领域术语和 ADR.md 已有决策已理解。
+
+### 2. 探索摩擦
+
+委托给 `<Path>{roots.workflows}/specdev/R-review-architecture/exploration-guide.md</Path>`。使用 Explore 子 Agent 有机遍历代码仓——不遵循僵化启发式，注意你在何处遇到摩擦：哪些模块是浅层的？哪些接缝存在泄漏？哪里缺乏局部性？哪些部分未经测试或难以测试？对每个可疑点应用删除测试。
+
+探索中若发现候选方案与已有 ADR 矛盾，仅当摩擦足够真实、值得重新审视 ADR 时才标注——在报告中以警告框清晰标记。
+
+**完成标准**：代码仓已遍历，每个摩擦点已记录涉及文件、摩擦类型和删除测试结果。
+
+### 3. 生成可视化报告
+
+委托给 `<Path>{roots.workflows}/specdev/R-review-architecture/html-report-template.md</Path>`。将探索发现渲染为自包含 HTML 文件，写入 OS 临时目录（`$TMPDIR` 或 `/tmp`），自动在浏览器中打开。每候选一张卡片：涉及文件、问题、方案、收益、before/after 图表、推荐强度（Strong / Worth exploring / Speculative）。报告结尾附最佳推荐。
+
+此时不提出接口。报告打开后询问用户："你想探索其中哪一个？"
+
+**完成标准**：HTML 报告已写入临时目录并已在浏览器中打开；用户已看到候选方案并做出选择。
+
+### 4. 访谈深化循环
+
+用户选择候选后，先绑定变更：按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议复用当前活跃 change 或创建新 change（topic 取自候选名）；新建时参照 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 步骤 1 初始化 `.status.json` 与三文件。
+
+随后委托 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 执行一次一问访谈——沿设计树推进：约束、依赖、深化模块的形状、接缝背后的内容、存留的测试。
+
+访谈中按 grilling-protocol 与 domain-modeling-rules 维护三文件（LOG → CONTEXT → ADR）。
+
+如需探索替代接口，启动 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。
+
+用户以负载性理由拒绝候选时，提供 ADR 记录："要我将其记录为 ADR 吗？这样未来的架构审查不会重新建议它。"访谈共识达成后，移交 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行实现。
+
+**完成标准**：change 已绑定（复用或新建）；访谈共识已达成；LOG.md/CONTEXT.md/ADR.md 已同步；用户已确认进入实现或记录 ADR 排除候选。
+
+---
+
+## 子文件引用
+
+| 文件 | 内容 | 触发条件 |
+|------|------|---------|
+| `<Path>{roots.workflows}/specdev/R-review-architecture/exploration-guide.md</Path>` | 摩擦信号清单、删除测试应用规则、接缝评估标准、ADR 冲突检测规则 | 步骤 2「探索摩擦」进入时加载 |
+| `<Path>{roots.workflows}/specdev/R-review-architecture/html-report-template.md</Path>` | HTML 脚手架、6 种图表模式、样式指南、报告语言占位符 | 步骤 3「生成可视化报告」进入时加载 |
+
+## 依赖关系
+
+- 依赖 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 提供架构术语——步骤 1 加载
+- 依赖 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>` 提供依赖分类和接缝纪律——步骤 1 加载
+- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 执行访谈——步骤 4 委托
+- 依赖 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护三文件——步骤 4 委托
+- 依赖 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>` 探索替代接口——步骤 4 按需启动
+- 依赖 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行实现——步骤 4 共识后移交

package/template/workflows/specdev/R-review-architecture/exploration-guide.md

@@ -0,0 +1,103 @@
+# 探索指南
+
+有机遍历代码仓以发现架构摩擦，将每个摩擦点转化为可操作的深化候选。使用 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 中的术语——module、interface、depth、seam、adapter、leverage、locality——一致地描述每个发现。
+
+## 探索方式
+
+使用 Agent 工具的 `subagent_type=Explore` 遍历代码仓。不遵循僵化启发式——有机地探索，注意你在何处遇到摩擦。目标是发现将浅模块转化为深模块的机会。
+
+## 摩擦信号
+
+探索时注意以下信号，每个信号指向一个潜在的深化候选：
+
+### 浅模块
+
+模块的接口几乎和实现一样复杂——大量方法、复杂参数，但内部仅是透传或简单委托。
+
+识别方法：
+- 模块的方法数量接近或超过其内部逻辑行数
+- 调用者需要理解多个方法才能完成一件事
+- 模块仅仅是另一个模块的重命名包装
+
+### 接缝泄漏
+
+两个模块的接口边界存在泄漏——一方的实现细节暴露给另一方。
+
+识别方法：
+- 调用者需要了解被调用模块的内部数据结构
+- 修改一个模块的实现需要同步修改调用者
+- 错误处理分散在调用链的多个层级
+
+### 局部性缺陷
+
+理解一个概念需要跨多个小模块反复跳跃——相关代码分散而非集中。
+
+识别方法：
+- 修改一个行为需要编辑 3 个以上文件
+- 纯函数仅为可测试性提取，但真正的 bug 隐藏在调用方式中（无局部性）
+- 同一领域的验证逻辑散布在多处
+
+### 不可测试代码
+
+模块难以通过其公共接口测试，或根本未经测试。
+
+识别方法：
+- 模块在构造时创建依赖而非接收依赖
+- 模块产生副作用而不返回结果
+- 测试文件不存在，或测试绕过接口直接操纵内部状态
+
+### 单一适配器接缝
+
+接口只有一个适配器——仅为了"以后可能替换"而引入的接缝。
+
+识别方法：
+- 接口只有一个实现类，且无测试替身
+- 接口的存在理由是"解耦"，但依赖方向并未改变
+- 接口的方法签名与唯一实现完全一致
+
+## 删除测试
+
+对每个可疑模块应用删除测试：
+
+1. 想象删除此模块
+2. 如果复杂性消失——它只是透传层 → **浅模块，候选合并**
+3. 如果复杂性在 N 个调用者中重新出现——它在发挥价值 → **保留，或深化其接口**
+
+删除测试的核心洞察：一个模块的价值不在于它做了什么，而在于如果它不存在会发生什么。
+
+## 接缝评估
+
+对每个候选评估其接缝质量：
+
+- **接缝位置**：接口放在哪里？调用者和实现之间的边界是否干净？
+- **适配器证明**：是否存在至少两个适配器（生产 + 测试）来证明接缝是真实的？一个适配器意味着假设性接缝。
+- **依赖类别**：接缝处的依赖属于哪个类别？参见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`——进程内、本地可替换、远程但自有、真正外部依赖。类别决定了深化后的测试策略。
+
+## ADR 冲突检测
+
+探索中对照已有 ADR 检查每个候选：
+
+1. 读取 `<Path>{roots.state}/specdev/adr/</Path>` 下所有 ADR 文件
+2. 读取 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 中的本变更决策
+3. 如果候选方案与已有 ADR 矛盾：
+   - **摩擦真实且值得重新审视** → 在候选卡片中以警告框标注（例如："与 ADR-0007 矛盾——但值得重新审视因为……"）
+   - **ADR 理由仍然成立** → 不提出该候选——不要列出 ADR 禁止的所有理论重构
+4. 仅在探索结束后统一评估，不要在探索过程中逐条争论 ADR
+
+## 候选记录格式
+
+每个候选在内部记录以下信息，供步骤 3 生成报告使用：
+
+- **涉及文件**（路径列表）
+- **摩擦类型**（浅模块 / 接缝泄漏 / 局部性缺陷 / 不可测试 / 单一适配器）
+- **问题描述**（一句）
+- **解决方向**（一句——深化模块、合并浅包装、重划接缝、引入适配器）
+- **依赖类别**（进程内 / 本地可替换 / 远程但自有 / 真正外部依赖）
+- **删除测试结果**（"复杂度集中"或"复杂度转移"）
+- **推荐强度**（Strong / Worth exploring / Speculative）
+- **ADR 冲突**（如有——引用 ADR 编号和重新审视的理由）
+
+推荐强度判断：
+- **Strong**：删除测试通过（复杂度会集中），接缝有两个以上适配器，依赖为进程内或本地可替换
+- **Worth exploring**：删除测试通过但依赖为远程或外部，或接缝仅有一个适配器
+- **Speculative**：删除测试结果不明确，或预期的深度提升较小

package/template/workflows/specdev/R-review-architecture/html-report-template.md

@@ -0,0 +1,124 @@
+# HTML 报告模板
+
+架构审查渲染为单个自包含 HTML 文件，写入操作系统临时目录。Tailwind 和 Mermaid 均来自 CDN。Mermaid 处理图形状图表（调用图、依赖关系、序列）；手工构建的 div 和 inline SVG 处理编辑性可视化（质量图、横截面、坍缩动画）。混合使用两者——不要所有图表都用 Mermaid，多样性本身就是目的。
+
+`{{config.defaults.report_language}}` 占位符由运行时解析为 `speculo/config.json` 的 `defaults.report_language` 字段值；若配置文件不存在则默认为 `"en"`。
+
+## 脚手架
+
+```html
+<!doctype html>
+<html lang="{{config.defaults.report_language}}">
+  <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>
+      .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>
+```
+
+## 页头
+
+仓库名称、日期，以及紧凑图例：实线框 = 模块，虚线 = 接缝，红色箭头 = 泄漏，粗黑框 = 深模块。无介绍段落——直接进入候选列表。
+
+## 候选卡片
+
+每个候选渲染为一个 `<article>` 元素。图表承担主要分量——文字稀疏、平实，使用 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 中的术语，不刻意修饰。
+
+卡片结构：
+
+- **标题** — 简短命名深化方案（如"合并 Order 接收管线"）
+- **徽章行** — 推荐强度（`Strong` = 翠绿、`Worth exploring` = 琥珀、`Speculative` = 石板灰）+ 依赖类别标签（`进程内`、`本地可替换`、`端口与适配器`、`mock`）
+- **文件** — 等宽字体列表，`font-mono text-sm`
+- **Before / After 图表** — 核心。两列并排，见下方图表模式
+- **Problem** — 一句。当前架构的摩擦是什么
+- **Solution** — 一句。改变什么
+- **Wins** — 要点，每项 ≤6 词。用术语表命名收益："局部性：bug 集中在一个模块"、"杠杆：一个接口，N 个调用点"、"接口缩小；实现吸收包装器"
+- **ADR 标注**（如适用）— 一行，琥珀色调框中
+
+不要写"更易维护"或"更清晰的代码"——这些术语不在 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>` 术语表中。如果图表需要一段文字才能理解，重新画图。
+
+## 图表模式
+
+选择适合候选的模式。混合使用。不要让每个图表看起来都一样。
+
+### Mermaid 图表（依赖/调用流）
+
+当重点是"X 调用 Y 调用 Z，看这多混乱"时使用 `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>` 表示。箭头用绝对定位在相对容器上的 inline SVG `<line>` 或 `<path>` 表示。当希望"after"图表呈现为一个粗边深模块、内部灰显时使用——Mermaid 不会以合适的视觉权重渲染这种效果。
+
+### 横截面图（分层浅度）
+
+堆叠水平条（`h-12 border-l-4`）展示调用经过的各层。Before：6 个薄层各做极少。After：一个厚条标注合并后的职责。
+
+### 质量图（接口与实现一样宽）
+
+每个模块两个矩形——一个表示接口表面积，一个表示实现。Before：接口矩形几乎和实现矩形一样高（浅）。After：接口矩形短，实现矩形高（深）。
+
+### 调用图坍缩
+
+Before：嵌套框呈现的函数调用树。After：同一棵树坍缩成一个框，内部调用在其内部以淡化形式显示。
+
+### 模块关系图（接缝对比）
+
+Before：模块 A 和 B 紧耦合，虚线穿越表示接缝泄漏。After：一个深模块包裹 A 和 B 的内部，干净接口对外暴露。使用 inline SVG 绘制两个并列场景。
+
+## 样式指导
+
+- 偏向编辑风格而非企业仪表盘。宽松留白。标题可选用衬线字体（`font-serif` 与 stone/slate 搭配）
+- 色彩克制：一种强调色（翠绿或靛蓝）+ 红色用于泄漏 + 琥珀用于警告
+- 图表高度约 320px，使 before/after 并排舒适放置无需滚动
+- 模块标签用 `text-xs uppercase tracking-wider`——应读作示意图而非 UI
+- 唯一脚本是 Tailwind CDN 和 Mermaid ESM import——其余全部静态，无应用代码
+
+## 最佳推荐
+
+一张更大的卡片。候选名称，一句说明为什么，指向其卡片的锚链接。
+
+## 语气
+
+平实、简洁——架构名词和动词直接来自 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md`。简洁不是偏离的借口。
+
+**完全使用：** module、interface、implementation、depth、deep、shallow、seam、adapter、leverage、locality。
+
+**绝不替代：** component、service、unit（代替 module）· API、signature（代替 interface）· boundary（代替 seam）· layer、wrapper（代替 module 当实际指 module 时）。
+
+**符合风格的表达：**
+- "Order 接收模块是浅层的——接口几乎与实现匹配。"
+- "Pricing 跨越接缝泄漏。"
+- "深化：一个接口，一个测试点。"
+- "两个适配器证明接缝：生产用 HTTP，测试用内存。"
+
+不模糊其词，不说"值得注意的是……"。如果一句话可以变成要点，就变成要点。如果一个要点可以删除，就删除它。如果一个术语不在 `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md` 术语表中，在发明新术语之前先用术语表中已有的。

package/template/workflows/specdev/T-tickets/T-tickets.md

@@ -106,11 +106,11 @@ keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
 
 ## 战略与背景
 
-<!-- [必填] 本 ticket 的战略上下文。改编自 issues-slices.md §0。 -->
+<!-- [必填] 本 ticket 的战略上下文。 -->
 
 - **本 ticket 战略**：一句话——本 ticket 做什么 + 为什么 + 以什么为基础（新建/复用现有模块）
 - **与该 ticket 相关的已确认决策**：逐条列出与本 ticket 范围相关的已拍板决策（从 ADR、spec 或对话中提取），防止实现时重新扯皮
-- **与该 ticket 相关的当前现状**：逐条列出与本 ticket 相关的、与需求不符的现有代码/行为。格式：`文件路径:行号范围` + 当前行为 + 为何不满足需求。行号为近似值，实施时以现场代码为准
+- **与该 ticket 相关的当前现状**：逐条列出与本 ticket 相关的、与需求不符的现有代码/行为。格式：文件路径 + 当前行为 + 为何不满足需求。可附近似行号作定位提示，不作承诺——实施时以现场代码为准
 - **该 ticket 的预期产出**：完成后可观察到的行为变化
 
 ## 范围边界
@@ -168,7 +168,7 @@ keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
 - **验收标准**使用 `- [ ]` checklist 格式，每条具体、可独立验证。优先写可执行命令，其次写手动检查步骤
 - 描述统一使用深层模块设计词汇：模块/接口/接缝/适配器，而非组件/服务/边界
 
-避免在 ticket 文件中写入绝对路径或行号承诺 —— 它们会很快过时。例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+避免在 ticket 文件中写入绝对路径；行号仅作近似定位提示，不作承诺。例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
 
 **5c. 写入 tickets-map.md**
 
@@ -187,7 +187,7 @@ T-tickets 阶段填写的列：**编号**、**Ticket**、**被阻塞于**、**
 - **横切关注点**只放跨 ticket 的规则——单 ticket 的规则留在该 ticket 文件内
 - **阻塞关系说明**在依赖图非平凡时补充文字解释
 
-**完成标准**：`ticket/` 目录已创建，所有 ticket 独立文件已按依赖顺序写入（命名为 `NN-<ticket-name>.md`）；`tickets-map.md` 已按 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 格式写入——包含总体摘要、六列执行清单（Gate 和 Contract ID 列为 `[待标注]`）、基础依赖关系 ASCII 树形图、并行规则和横切关注点；每个 ticket 声明阻塞边、战略与背景、范围边界、交付物、保留/不动和验收标准。
+**完成标准**：`ticket/` 目录与全部 `NN-<ticket-name>.md` 已按依赖顺序写入；`tickets-map.md` 已按模板落盘（Gate / Contract ID 为 `[待标注]`）；每个 ticket 含阻塞边、战略与背景、范围边界、交付物、保留/不动与验收标准。
 
 ## 子文件引用
 

package/template/workflows/specdev/W-wayfinder/W-wayfinder.md

@@ -15,13 +15,13 @@ keywords: [寻路, 地图, 探索, 规划, 战争迷雾, 调研]
 
 ## 规划，而非执行
 
-Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其 **Notes** 覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其「说明」章节覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
 
 ## 用名称引用
 
-每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的 Decisions-so-far —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
+每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的 「已做出的决策」 —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
 
-在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的 Decisions-so-far 中以 `- [ticket 标题] —— 答案概括` 形式索引。
+在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的 「已做出的决策」 中以 `- [ticket 标题] —— 答案概括` 形式索引。
 
 ## 地图
 
@@ -29,11 +29,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
 
-**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞关系通过"被阻塞于"字段声明，以 ticket 标题引用。
-
-**前沿查询：** 前沿上的 tickets 是指：checkbox 未勾选（开放）、其"被阻塞于"中列出的所有 tickets 均已勾选（无阻塞）、且尚未被领取的 tickets。Agent 通过阅读地图文件本身即可识别前沿。
-
-**领取机制：** 当一个 agent 会话开始处理某个 ticket 时，它应在 `<Path>{roots.state}/specdev/status.json</Path>` 的当前 change 的 `active` 条目中，将 ticket 名称追加到 `claimed_tickets` 数组，以便并发会话跳过它。处理完成后从 `claimed_tickets` 中移除。`claimed_tickets` 中存在记录即为领取标记。
+**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞、领取与前沿的定义见下方「Tickets」节。
 
 ### 地图正文
 
@@ -104,7 +100,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
 
 - **Research**（AFK）：调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 启动后台 Agent 针对一手来源调查问题，在 ticket 的答案中链接研究产出文件。当需要当前工作目录之外的知识时使用。
-- **Prototype**（HITL）：通过制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
+- **Prototype**（HITL）：调用 `<Path>{roots.workflows}/specdev/common/prototype/SKILL.md</Path>` 制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
 - **Grilling**（HITL）：通过 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` 访谈协议逐个问题进行对话。同时使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型。默认情况 —— 当不确定类型时选此。
 - **Task**（HITL 或 AFK）：在*决策*能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个*执行*而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。
 
@@ -119,7 +115,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 - **做成 ticket 当** 问题已经清晰 —— 即使它被阻塞，你尚不能行动。你能写出明确的"问题"段落。
 - **尚未明确当** 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。
 
-**尚未明确**排除已决策的内容（Decisions-so-far）、已有的活跃 ticket 以及超出范围的内容（下一节）。
+**尚未明确**排除已决策的内容（「已做出的决策」）、已有的活跃 ticket 以及超出范围的内容（下一节）。
 
 ## 超出范围
 
@@ -145,9 +141,9 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
    **完成标准**：前沿的开放决策和第一步已浮现；迷雾部分已识别并草拟。
 
-3. **创建地图**：写入 `<Path>{roots.state}/specdev/changes/{change}/map.md</Path>`，填写 Destination 和 Notes，Decisions-so-far 为空，迷雾草拟进**尚未明确**。
+3. **创建地图**：写入 `<Path>{roots.state}/specdev/changes/{change}/map.md</Path>`，填写「目的地」和「说明」，「已做出的决策」 为空，迷雾草拟进**尚未明确**。
 
-   **完成标准**：地图文件已创建，Destination、Notes、尚未明确、超出范围均已填写。
+   **完成标准**：地图文件已创建，目的地、说明、尚未明确、超出范围均已填写。
 
 4. **创建你现在能明确的 tickets** 作为地图文件内的小节 —— 然后在**第二遍**中连接阻塞边（tickets 需要首先有标题才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
 
@@ -159,21 +155,21 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 用户带着一张地图（变更目录或 map.md 路径）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
 
-1. **加载地图** —— 低分辨率视图（Destination、Notes、Decisions-so-far、尚未明确、超出范围），而非每个 ticket 的完整正文。
+1. **加载地图** —— 低分辨率视图（目的地、说明、已做出的决策、尚未明确、超出范围），而非每个 ticket 的完整正文。
 
    **完成标准**：地图的低分辨率视图已加载，当前状态已理解。
 
-2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket（开放、未被阻塞、未被领取）。**领取它**：在任何工作之前将 ticket 名称追加到 `<Path>{roots.state}/specdev/status.json</Path>` 的当前 change 的 `active` 条目中的 `claimed_tickets` 数组。
+2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。**领取它**（规则见上方「Tickets」节）。
 
    **完成标准**：一个前沿 ticket 已被选中并领取。
 
-3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 Notes 块中指定的技能。根据 ticket 类型选择解决方式：**research** ticket 调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>`；**grilling** ticket 使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 进行访谈；**prototype** 和 **task** 按各自问题描述执行。查阅 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型的一致性。
+3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用「说明」中指定的技能。根据 ticket 类型选择解决方式：**research** 调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>`；**grilling** 使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；**prototype** 调用 `<Path>{roots.workflows}/specdev/common/prototype/SKILL.md</Path>`；**task** 按问题描述执行。查阅 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型。
 
    **完成标准**：ticket 的问题已解决，答案已记录。
 
-4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的 Decisions-so-far 中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `<Path>{roots.state}/specdev/status.json</Path>` 的当前 change 的 `active` 条目中的 `claimed_tickets` 数组中移除该 ticket。
+4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的「已做出的决策」中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `claimed_tickets` 中移除该 ticket（规则见上方「Tickets」节）。
 
-   **完成标准**：ticket checkbox 已勾选，Decisions-so-far 已更新，active 数组已清理。
+   **完成标准**：ticket checkbox 已勾选，「已做出的决策」已更新，领取标记已清除。
 
 5. **添加新浮现的 tickets** 作为地图文件内新的小节（先创建再连接阻塞边）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets（勾选并注明无效原因）。
 
@@ -186,7 +182,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 当所有 tickets 已关闭（勾选）、迷雾已清空（尚未明确为空或仅剩无法继续分解的模糊项）、且通往目标的路径已清晰时，地图完成。向用户汇报：
 
 - 目的地是否已可抵达——路径上的每个步骤是否都已有明确的 ticket 或决策
-- Decisions-so-far 中的关键结论摘要
+- 「已做出的决策」 中的关键结论摘要
 - 剩余的任何**尚未明确**项——它们是否阻碍行动，还是可作为实现细节处理
 - 建议的下一步行动（移交实现、开始执行、或重新划定目标）
 

package/template/workflows/specdev/common/dev-worktree/SKILL.md

@@ -18,121 +18,31 @@ description: 在 Speculo workflow change 内创建隔离 git worktree 进行开
 | 已在 worktree 中，未完成 | 继续开发，不重复创建 |
 | 用户要求 PR / 暂存 / 丢弃 | 阶段 B 按对应选项执行 |
 
----
-
 ## 阶段 A：创建 Worktree
 
-详细步骤见 [references/create.md](references/create.md)。核心流程：
-
-### A0. 检测现有隔离
-
-```bash
-GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
-GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
-SUPER=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
-```
-
-- `SUPER` 有值 → submodule 内，按普通仓库处理，不误判
-- `GIT_DIR != GIT_COMMON` 且非 submodule → 已在 worktree，跳到 A3 设置
-- `GIT_DIR == GIT_COMMON` → 主工作区，继续
-
-### A1. 命名与路径
-
-| 要素 | 值 |
-|------|-----|
-| 基础分支 | 当前分支（`git rev-parse --abbrev-ref HEAD`） |
-| change 分支 | `speculo/<workflow>/<change>` |
-| worktree 路径 | `{state-root}/<workflow>/changes/<change>/.worktree/` |
-
-分支或路径已存在 → 停止，不覆盖不复用。
-
-**前置检查：** `speculo/.speculo/` 必须被 git 跟踪——产物需随分支合并。若被忽略则降级为非 worktree 模式。
-
-### A2. 创建
-
-```bash
-git worktree add -b speculo/<workflow>/<change> {state-root}/<workflow>/changes/<change>/.worktree
-```
-
-确保 `.gitignore` 含 `.worktree/`；缺失则追加并提交。
-
-### A3. 项目设置与基线
-
-自动检测并安装依赖、运行基线测试：
-
-```bash
-[ -f package.json ] && (npm install 2>/dev/null || true)
-[ -f Cargo.toml ] && cargo build
-[ -f requirements.txt ] && pip install -r requirements.txt
-[ -f go.mod ] && go mod download
-# 跑基线测试
-```
+完整步骤见 [references/create.md](references/create.md)。概览：
 
-基线测试失败 → 报告并询问，未获许可不开始实现。
+1. **检测现有隔离** — 已在 worktree 则跳过创建；submodule 内按普通仓库处理
+2. **命名** — 分支 `speculo/<workflow>/<change>`；路径 `{state-root}/<workflow>/changes/<change>/.worktree/`；已存在则停止
+3. **创建** — `git worktree add -b …`；确保 `.gitignore` 含 `.worktree/`
+4. **基线** — 安装依赖并跑基线测试；失败则报告并询问
+5. **写回** — 将 `base_branch` / `change_branch` / `worktree_path` / `worktree_status: active` 写入 change 的 `.status.json`
 
-### A4. 写回状态
-
-将 `base_branch`、`change_branch`、`worktree_path`、`worktree_status: active` 写入 change 的 `.status.json`。
-
----
+**前置：** `speculo/.speculo/` 必须被 git 跟踪；若被忽略则降级为非 worktree 模式。
 
 ## 阶段 B：收尾合并
 
-详细步骤见 [references/finalize.md](references/finalize.md)。
-
-### B1. 验证测试
-
-跑项目测试套件。失败 → 停止，禁止合并/PR。
-
-### B2. 展示选项
-
-```
-实现已完成。你想怎么做？
-
-1. 本地合并回 <base-branch>（推荐，默认）
-2. 推送并创建 Pull Request
-3. 保持现状（稍后处理）
-4. 丢弃
+完整步骤见 [references/finalize.md](references/finalize.md)。概览：
 
-选哪个？
-```
+1. **验证测试** — 失败则停止，禁止合并/PR
+2. **展示选项** — 本地合并（默认）/ 创建 PR / 保持 / 丢弃
+3. **执行** — 本地合并顺序：checkout base → pull → `merge --no-ff` → 重跑测试 → `worktree remove` → `branch -d` → `prune` → 更新 `.status.json`
 
-分离 HEAD 时移除选项 1。用户未指定时默认选项 1。
-
-### B3. 执行 —— 顺序不可变
-
-**选项 1（本地合并）：**
-1. 合并到 base：`git checkout <base> && git pull && git merge --no-ff <change_branch>`
-2. 在合并结果上再跑测试
-3. 测试通过 → 从主仓库根删除 worktree：`git worktree remove <path>`
-4. 删除分支：`git branch -d <change_branch>`
-5. `git worktree prune`
-6. 更新 `.status.json`：`worktree_status: removed`
-
-**选项 2（PR）：** 推送分支、创建 PR，保留 worktree。
-**选项 3（保持）：** 不动，报告状态。
-**选项 4（丢弃）：** 确认后删除 worktree 和分支。
-
-合并冲突或测试失败 → 停止，保留现场，报告原因，不强推。
-
----
+合并冲突或测试失败 → 停止，保留现场。冲突解决见 `<Path>{roots.workflows}/specdev/common/resolving-merge-conflicts/SKILL.md</Path>`。
 
 ## 红线
 
-**绝不：**
-- 已在 worktree 时嵌套创建
-- 覆盖已有分支或路径
-- 测试失败时继续合并/PR
-- 合并结果未验证就删 worktree
-- 先删分支再 worktree remove（顺序：merge → remove worktree → delete branch）
-- 在 worktree 内部执行 `git worktree remove`
-- 未经确认执行破坏性操作
-- 强制推送
-
-**始终：**
-- 分支名：`speculo/<workflow>/<change>`
-- worktree 路径：change 目录下的 `.worktree/`
-- 创建后装依赖 + 基线测试
-- 收尾前验证测试
-- 合并成功后再清理
-- 清理后 `git worktree prune`
+- 已在 worktree 时不嵌套创建；不覆盖已有分支或路径
+- 测试失败时不合并/不发 PR；合并结果未验证不删 worktree
+- 清理顺序固定：merge → remove worktree → delete branch；在 worktree 内部不执行 `git worktree remove`
+- 破坏性操作须先确认；不强制推送

package/template/workflows/specdev/common/handoff/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: handoff
+description: "将一段对话或子代理会话压缩为一份交接文档，供另一个 agent 接手继续工作。适用于 Lead 压缩子代理实现上下文、会话移交、或任何需要把上下文浓缩为可持久化摘要的场景。"
+---
+
+# Handoff — 交接文档
+
+将当前对话（或指定的子代理会话）压缩为一份交接文档，使新的 agent 无需读取完整转录即可继续工作。
+
+## 内容要求
+
+交接文档包含以下部分：
+
+- **做了什么** —— 实现或完成的工作摘要
+- **关键决策** —— 做出的决策及理由；与 spec/plan 的任何偏差及原因
+- **验证状态** —— 测试结果摘要、已运行的检查
+- **产物引用** —— 相关 spec、ADR、commit、diff 的路径或 URL
+- **建议 skills** —— 建议接手 agent 调用的 skills 列表
+
+不重复已被其他产物（spec、方案、ADR、issue、commit、diff）覆盖的内容，改用路径或 URL 引用它们。
+
+清除任何敏感信息，如 API 密钥、密码或个人身份信息。
+
+如果调用方传入了对下一个会话重点的描述，据此定制文档内容。
+
+## 产物位置
+
+产物位置由调用方指定：
+
+- Lead 编排场景（子代理交接）：写入操作系统临时目录，关键信息由调用方回写到对应 ticket 文件（参见 `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` §2.2）
+- 调用方未指定时：写入 `<Path>{roots.state}/specdev/changes/{change}/handoff/<YYYY-MM-DD>-<topic>.md</Path>`
+
+## 路径引用规范
+
+文档中所有文件/文件夹引用使用**项目根目录**的相对路径。
+
+- ✅ `src/modules/auth/`
+- ✅ `speculo/.speculo/specdev/changes/<YYYY-MM-DD>-<topic>/spec.md`
+- ❌ `../../specdev/changes/...` — 相对于交接文档自身，脱离目录后不可定位
+- ❌ `auth` — 裸名，无法判断是目录/文件/子模块
+
+例外：skills 名称属于逻辑标识而非文件路径，不适用此规则。

package/template/workflows/specdev/common/triage/OUT-OF-SCOPE.md

@@ -20,7 +20,7 @@
 
 文件应以轻松、可读的风格编写 — 更像一份简短的设计文档，而非数据库条目。使用段落、代码示例和实例让理由清晰并对初次遇到它的人有用。
 
-```markdown
+````markdown
 # Dark Mode
 
 此项目不支持深色模式或面向用户的主题化。
@@ -50,7 +50,7 @@ interface ThemeConfig {
 - #42 — "添加深色模式支持"
 - #87 — "用于无障碍的夜间主题"
 - #134 — "深色主题选项"
-```
+````
 
 ### 文件命名