@namewta/speculo 0.2.16 → 0.3.0

package/template/workflows/specdev/A-archive-and-consolidate/consolidation-rules.md

@@ -14,7 +14,7 @@
 
 ### 内容格式
 
-遵循 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` 定义的格式：
+永久库 ADR 与变更内 ADR（`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` 的 `## NNNN: 标题` 段落格式）格式不同——永久库使用独立文件与结构化字段：
 
 ```markdown
 # ADR-NNNN: {标题}
@@ -26,6 +26,8 @@
 - **后果**：{这个决策带来的影响，正面和负面}
 ```
 
+从变更内 ADR 提升时：标题取 `## NNNN: {标题}` 中的标题文本，正文扩写为上述五字段；来源 change 与原编号写入「决策上下文」。
+
 ### Supersede 处理
 
 若新 ADR 取代旧 ADR，在旧 ADR 文件**开头**添加横幅：
@@ -38,7 +40,7 @@
 
 ### 从 LOG 提升
 
-若变更的 `LOG.md` 中存在 `LOG-XXXX: accepted` 条目，其结论满足 ADR 三条件（不可逆 + 令人意外 + 真实权衡）但未正式记录为 ADR，则：
+若变更的 `LOG.md` 中存在 `LOG-XXXX: accepted` 条目，其结论满足 ADR 三条件（难以逆转 + 令人意外 + 真实权衡）但未正式记录为 ADR，则：
 
 1. 创建正式 ADR 文件
 2. 在 Context 中注明"从 `<change-name>` 的 LOG-XXXX 提升"

package/template/workflows/specdev/A-archive-and-consolidate/knowledge-graduation.md

@@ -41,7 +41,7 @@ specdev 每个变更遵循三文件模型（参见 `<Path>{roots.workflows}/spec
 
 | 来源文件 | 知识类型 | 判定特征 | 目标知识库 |
 |---------|---------|---------|-----------|
-| **ADR.md** | 架构决策 | `## NNNN: Title` 条目，满足三条件（不可逆 + 令人意外 + 真实权衡） | `<Path>{roots.state}/specdev/adr/</Path>` |
+| **ADR.md** | 架构决策 | `## NNNN: Title` 条目，满足三条件（难以逆转 + 令人意外 + 真实权衡） | `<Path>{roots.state}/specdev/adr/</Path>` |
 | **CONTEXT.md** | 领域术语 | `**术语名**：定义` + `_Avoid_` 条目，项目特有概念 | `<Path>{roots.state}/specdev/context/</Path>` |
 | **LOG.md** | 设计决策 | `LOG-XXXX: accepted` 条目，满足 ADR 三条件但未正式记录 → 提升为 ADR | `<Path>{roots.state}/specdev/adr/</Path>` |
 | **research/** | 研究产物 | 跨变更相关的研究发现（>1 变更引用或覆盖共享技术栈） | `<Path>{roots.state}/specdev/research/</Path>` |

package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md

@@ -16,7 +16,7 @@ keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
 - **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
 - **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
 
-如果这些文件不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。
+如果这些文件不存在，静默继续——诊断不依赖设计文档，缺失的 change 在需要记录结论时按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议创建。需要建立完整设计上下文时，运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`。
 
 ## 流程
 
@@ -60,7 +60,7 @@ keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
 - **最小复现场景**——阶段 3 产出的最小化复现，可直接转为回归测试
 - **建议的修复接缝**——在哪个模块/接口处修复最合适
 
-修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试缝合点，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
+修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试接缝，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
 
 **完成标准**：I-implement 已启动，根因描述、最小复现、建议修复接缝已移交。
 

package/template/workflows/specdev/D-diagnose-bugs/cleanup-postmortem.md

@@ -29,9 +29,9 @@
 
 问：什么本可以预防这个 bug？从以下维度审视：
 
-- **测试缝合点**——是否缺少合适的测试接缝？如果有好的缝合点，此 bug 是否会被更早发现？
+- **测试接缝**——是否缺少合适的测试接缝？如果有好的接缝，此 bug 是否会被更早发现？
 - **接口设计**——接口是否暴露了容易误用的契约？深度是否足够防止调用者犯错？
 - **数据边界**——是否缺少输入校验、类型约束或边界条件处理？
 - **耦合**——是否因模块间的隐藏耦合导致变更的连锁反应？
 
-如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况记录到 LOG.md 的预防建议中。在修复之后提出建议——此时比诊断开始时拥有更多信息。
+如果答案涉及架构变更（没有好的测试接缝、纠缠的调用者、隐藏的耦合），将具体情况记录到 LOG.md 的预防建议中。在修复之后提出建议——此时比诊断开始时拥有更多信息。

package/template/workflows/specdev/D-diagnose-bugs/feedback-loop-techniques.md

@@ -8,7 +8,7 @@
 
 ### 1. 失败测试
 
-在能触及 bug 的任意缝合点编写——单元测试、集成测试、端到端测试。优先选择现有的测试缝合点。观察项目中已有的测试了解如何注入测试。
+在能触及 bug 的任意接缝编写——单元测试、集成测试、端到端测试。优先选择现有的测试接缝。观察项目中已有的测试了解如何注入测试。
 
 ### 2. Curl / HTTP 脚本
 

package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md

@@ -36,11 +36,7 @@ keywords: [设计, 访谈, 领域建模, ADR, 决策记录, 词汇表, 设计轨
 
 ### 3. 捕获文档
 
-委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。对照词汇表挑战术语、精炼模糊语言、讨论具体场景、与代码交叉引用。
-
-- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 同步所有结论
-- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 精炼术语定义
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 仅追加满足三条件的架构决策（参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`）
+委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。对照词汇表挑战术语、精炼模糊语言、讨论具体场景、与代码交叉引用。三文件按 grilling-protocol 规定的顺序同步（LOG → CONTEXT → ADR）。
 
 **完成标准**：LOG.md 已同步所有结论；CONTEXT.md 已精炼术语；ADR.md 已追加满足三条件的架构决策。
 

package/template/workflows/specdev/G-grill-with-docs/adr-format.md

@@ -2,6 +2,8 @@
 
 所有架构决策记录存放在变更目录的单一 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 文件中。不使用 `docs/adr/` 目录下的编号文件，所有决策在一个文件内按二级标题分段。
 
+> 变更内格式为 `## NNNN: 标题` 段落。经 `A-archive-and-consolidate` 提升到永久库 `<Path>{roots.state}/specdev/adr/</Path>` 后，转为独立文件 `# ADR-NNNN: 标题` + 结构化字段（见 consolidation-rules）。
+
 ## 模板
 
 ```md

package/template/workflows/specdev/G-grill-with-docs/domain-modeling-rules.md

@@ -43,11 +43,7 @@
 
 ### 维护规则
 
-- 每次完成设计问答，同步更新 `LOG.md`、`CONTEXT.md` 与 `ADR.md`。
-- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
-- 日志可以记录具体交互和边界场景；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
-- 每个日志条目应关联对应的 ADR（如有）：`Related: ADR-XXXX`。
-- 状态为 `deferred` 的条目保留，以便后续恢复讨论时知道从什么问题开始。
+完整维护规则（状态、修订、关联 ADR）见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>` 模板内的「维护规则」块；本文件只规定同步时机：每次完成设计问答后立即同步，不批量延后。
 
 ## 及时更新 CONTEXT.md
 
@@ -64,7 +60,7 @@
 
 仅在以下三个条件全部满足时才向 `ADR.md` 追加一条决策记录：
 
-1. **难以逆转**——以后改变主意的成本是有意义的
+1. **难以逆转**——以后改变主意的成本是实质性的
 2. **没有上下文会令人惊讶**——未来的读者会疑惑"他们为什么这样做？"
 3. **真实权衡的结果**——存在真正的替代方案，你出于特定原因选择了一个
 
@@ -84,10 +80,4 @@
 
 ## 三文件同步规则
 
-访谈中每完成一轮设计问答，按以下顺序同步三个文件：
-
-1. **LOG.md** 先更新——立即追加日志条目，记录本次讨论的结论
-2. **CONTEXT.md** 随后更新——从日志中提取新术语或修正的术语定义
-3. **ADR.md** 最后更新——检查是否需要满足三条件追加 ADC（架构决策记录）
-
-如果 CONTEXT 或 ADR 的更新来自日志条目，在日志中补充 `Related: ADR-XXXX` 的关联标注。
+访谈中每完成一轮设计问答，按顺序同步：LOG.md → CONTEXT.md → ADR.md。完整时机与触发条件见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`「访谈中维护三文件」。

package/template/workflows/specdev/I-implement/I-implement.md

@@ -19,7 +19,7 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 - **永久 ADR** —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状：`<Path>{roots.state}/specdev/adr/</Path>`
 - **永久 CONTEXT** —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状：`<Path>{roots.state}/specdev/context/</Path>`
 
-如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
+如果当前 change 下的 CONTEXT.md 或 ADR.md 不存在，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或询问用户以建立上下文。永久 ADR 和 CONTEXT 目录可能为空——静默继续，不影响后续流程。
 
 ## 流程
 
@@ -65,8 +65,8 @@ keywords: [实现, TDD, 代码审查, 模块设计, 重构]
 
 ### 4. 提交
 
-1. 运行类型检查：`npx tsc --noEmit`
-2. 运行完整测试套件：`npx vitest run`
+1. 运行项目自身的类型/静态检查命令——从项目脚本（package.json scripts、Makefile、CI 配置等）探测，不确定时询问用户
+2. 运行项目自身的完整测试套件命令——探测方式同上
 3. 将更改提交到当前分支：`git add -A && git commit -m "<描述性提交信息>"`
 4. 更新 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下的状态文件
 

package/template/workflows/specdev/I-implement/codebase-design-glossary.md

@@ -1,6 +1,6 @@
 # 代码仓设计
 
-设计**深层模块**：通过一个小接口承载大量行为，放置在干净的缝合点处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
+设计**深层模块**：通过一个小接口承载大量行为，放置在干净的接缝处，可通过该接口进行测试。在任何设计或重构代码的地方使用这些语言和原则。目标是为调用者提供杠杆效应，为维护者提供局部性，为所有人提供可测试性。
 
 ## 术语表
 
@@ -10,13 +10,13 @@
 
 **Interface（接口）** — 调用者正确使用模块所需了解的一切：类型签名，还包括不变量、顺序约束、错误模式、必需配置和性能特征。_避免使用_：API、signature（太窄 — 它们仅指类型层面的表面）。
 
-**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论缝合点时用 "adapter"；否则用 "implementation"。
+**Implementation（实现）** — 模块内部的内容，它的代码体。区别于 **Adapter（适配器）**：一个东西可以是一个小适配器加一个大实现（Postgres 仓库），也可以是一个大适配器加一个小实现（内存假实现）。当讨论接缝时用 "adapter"；否则用 "implementation"。
 
 **Depth（深度）** — 接口处的杠杆效应：调用者（或测试）每学习一个单位的接口可以驱动的行为量。当大量行为隐藏在小接口后面时，模块是**深层的**；当接口几乎和实现一样复杂时，模块是**浅层的**。
 
-**Seam（缝合点）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。缝合点放在哪里本身就是一个设计决策，与缝合点后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
+**Seam（接缝）** _(Michael Feathers)_ — 一个可以在不编辑该位置的情况下改变行为的地方；模块接口所在的*位置*。接缝放在哪里本身就是一个设计决策，与接缝后面放什么不同。_避免使用_：boundary（与 DDD 的有界上下文重载）。
 
-**Adapter（适配器）** — 在缝合点处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
+**Adapter（适配器）** — 在接缝处满足接口的具体事物。描述的是*角色*（它填充哪个槽位），而非实质（内部是什么）。
 
 **Leverage（杠杆效应）** — 调用者从深度中获得的好处：每学习一个单位的接口获得更多的能力。一个实现为 N 个调用点和 M 个测试带来回报。
 
@@ -54,10 +54,10 @@
 
 ## 原则
 
-- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部缝合点**（对其实现私有，用于其自身测试）以及位于其接口处的**外部缝合点**。
+- **深度是接口的属性，而非实现的属性。** 一个深层模块内部可以由小型、可模拟、可替换的部分组成 — 只是它们不属于接口的一部分。一个模块可以拥有**内部接缝**（对其实现私有，用于其自身测试）以及位于其接口处的**外部接缝**。
 - **删除测试。** 想象删除这个模块。如果复杂性消失，它就是个透传层。如果复杂性在 N 个调用者中重新出现，它就在发挥价值。
-- **接口就是测试表面。** 调用者和测试穿过同一个缝合点。如果你想测试接口_之外_的内容，模块可能形状不对。
-- **一个适配器意味着假设的缝合点。两个适配器意味着真实的缝合点。** 除非有东西确实在缝合点两侧变化，否则不要引入缝合点。
+- **接口就是测试表面。** 调用者和测试穿过同一个接缝。如果你想测试接口_之外_的内容，模块可能形状不对。
+- **一个适配器意味着假设的接缝。两个适配器意味着真实的接缝。** 除非有东西确实在接缝两侧变化，否则不要引入接缝。
 
 ## 为可测试性而设计
 
@@ -105,5 +105,5 @@
 
 ## 深入阅读
 
-- **给定依赖的情况下深化一个集群** — 见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`：依赖类别、缝合点规程、以及替换而非分层的测试。
-- **探索替代接口** — 见 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和缝合点位置上进行比较。
+- **给定依赖的情况下深化一个集群** — 见 `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`：依赖类别、接缝规程、以及替换而非分层的测试。
+- **探索替代接口** — 见 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`：启动并行子 agent，以几种截然不同的方式设计接口，然后在深度、局部性和接缝位置上进行比较。

package/template/workflows/specdev/I-implement/tdd-examples.md

@@ -78,7 +78,7 @@ test("calculateTotal sums line items", () => {
 
 ---
 
-# 何时使用 Mock
+## 何时使用 Mock
 
 仅在**系统边界**处使用 Mock：
 

package/template/workflows/specdev/I-init-setup/I-init-setup.md

@@ -80,7 +80,7 @@ specdev 使用五个标准状态角色来追踪工作项的生命周期：
 | `ready-for-human` | `ready-for-human` | 需人工处理 |
 | `wontfix` | `wontfix` | 不处理 |
 
-当 `T-tickets`、`W-wayfinder` 等 work 处理工作项时，它们会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
+当 `T-triage` 分诊外部 issue 时，会将工作项移过一个状态机——需要评估、等待补充、可供 agent 领取、需人工处理、或不予处理。状态标签是这些状态在持久化文件中的字符串表示。默认每个角色的标签等于其名称，如果你的项目已有不同命名习惯，可以在此映射。
 
 确认用户是否接受默认标签，或需要覆盖为自定义字符串。将映射写入 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`。
 

package/template/workflows/specdev/I-init-setup/domain-layout.md

@@ -8,16 +8,18 @@ specdev 使用单上下文布局——整个 workflow 共享一套领域术语
 
 ```
 {state_root}/changes/<change>/
-├── CONTEXT.md                          ← 项目领域术语与概念
-├── ADR.md                              ← 本变更相关的架构决策记录
-└── LOG.md                              ← 设计决策日志（按时间顺序记录每次设计调整）
+├── CONTEXT.md    ← 领域词汇表
+├── ADR.md        ← 本变更相关的架构决策记录
+└── LOG.md        ← 设计决策日志
 ```
 
-- **CONTEXT.md** —— 定义项目特有的领域概念和术语表。各 work 在输出中引用领域概念时以本文档为准。
-- **ADR.md** —— 记录本变更范围内的架构决策（格式：`## ADR-NNNN: 标题`）。如果变更跨多个上下文，决策记录在触发该决策的变更目录下。
-- **LOG.md** —— 按时间倒序记录每次设计调整、决策变更及其原因。格式：`## YYYY-MM-DD HH:MM — 标题`，每次记录包含：**决策**（做什么）、**原因**（为什么）、**影响**（影响哪些 work/文件）。
+三个文件的权威格式由 `G-grill-with-docs` 定义，本文件不重复：
 
-> specdev 将所有领域文档限定在 `changes/<change>/` 目录内，不依赖全局文件。例如需要创建 CONTEXT.md 时，写入 `{state_root}/changes/<change>/CONTEXT.md`。
+- **CONTEXT.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`（规范术语 + `_Avoid_` 同义词列表）
+- **ADR.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`（单文件、`## NNNN: 标题` 分段）
+- **LOG.md** —— 格式见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`（`## LOG-XXXX` 编号条目、文件末尾追加）
+
+> specdev 将变更内领域文档限定在 `changes/<change>/` 目录内。经确认后的 ADR/CONTEXT 由 `A-archive-and-consolidate` 提升到永久目录 `{roots.state}/specdev/adr/` 与 `{roots.state}/specdev/context/`，始终反映项目当前现状。
 
 ## 路径解析规则
 
@@ -27,64 +29,27 @@ specdev 使用单上下文布局——整个 workflow 共享一套领域术语
 - `ADR.md` → `{state_root}/changes/<current_change>/ADR.md`
 - `LOG.md` → `{state_root}/changes/<current_change>/LOG.md`
 - `{state_root}` 由 runtime-context 解析为 `{roots.state}/specdev/`
-- `<current_change>` 由 `status.json` 的 `active` 数组确定（取第一个活跃变更）
+- `<current_change>` 按 INDEX 启动协议从 `status.json` 的 `active` 数组确定
 
 ## 在探索之前
 
 当 specdev work 需要领域上下文时，按以下顺序读取：
 
-1. **`CONTEXT.md`**（位于当前变更目录内）—— 项目领域语言，由 `G-grill-with-docs` 或 `I-implement` 在探索代码库时创建或更新
-2. **`ADR.md`**（位于当前变更目录内）—— 涉及当前变更的架构决策，由 `G-grill-with-docs` 在讨论架构时更新
-3. **`LOG.md`**（位于当前变更目录内）—— 设计决策历史，由各 work 在设计调整时追加记录
+1. **永久目录**（若存在）—— `{state_root}/context/` 与 `{state_root}/adr/`，反映项目当前现状
+2. **`CONTEXT.md`**（当前变更目录内）—— 本变更的领域语言
+3. **`ADR.md`**（当前变更目录内）—— 涉及当前变更的架构决策
+4. **`LOG.md`**（当前变更目录内）—— 设计决策历史
 
-如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`G-grill-with-docs` 和 `I-implement` 在领域知识或决策实际被确定时延迟创建它们。
+如果这些文件都不存在，静默继续。不要标记它们的缺失或预先建议创建。`G-grill-with-docs` 在领域知识或决策实际被确定时延迟创建它们。
 
 ## 使用术语表的词汇
 
-输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到术语表明确避免的同义词。如果需要的新概念尚未在术语表中，记录到 `CONTEXT.md` 并通知用户。
-
-如果 `CONTEXT.md` 不存在，在首次需要时由当前 work 创建骨架：
-
-```markdown
-# CONTEXT — <change 主题>
-
-## 领域术语
-
-| 术语 | 定义 | 别名 / 避免使用 |
-|------|------|----------------|
-| ... | ... | ... |
-
-## 边界上下文
-
-<!-- 如有多个子域，在此划分边界 -->
-```
+输出中命名领域概念时，使用 `CONTEXT.md` 中定义的术语，不偏离到 `_Avoid_` 列表明确避免的同义词。如果需要的新概念尚未在术语表中，按 context-format 的增删改操作记录到 `CONTEXT.md` 并通知用户。
 
 ## 标记 ADR 冲突
 
 如果输出与现有 ADR 矛盾，明确提出而不是默默覆盖：
 
-> _与 `<Path>{roots.state}/specdev/changes/<change>/ADR.md</Path>` 中的 ADR-NNNN 矛盾 — 但值得重新讨论，因为……_
-
-同时将冲突记录追加到 `LOG.md`：
-
-```markdown
-## YYYY-MM-DD HH:MM — ADR 冲突标记
-
-- **冲突**: 当前建议与 ADR-NNNN 矛盾
-- **原因**: <重新讨论的理由>
-- **影响**: 如采纳新方案，需更新 ADR.md 并记录迁移路径
-```
-
-## 写入 LOG.md
-
-每次设计调整或决策变更时，在 `LOG.md` 顶部追加一条记录（时间倒序）：
-
-```markdown
-## YYYY-MM-DD HH:MM — <简短标题>
-
-- **决策**: <做了什么设计决定>
-- **原因**: <为什么做这个决定>
-- **影响**: <影响哪些 work、哪些文件、哪些后续步骤>
-```
+> _与 ADR NNNN 矛盾 — 但值得重新讨论，因为……_
 
-`LOG.md` 不同于 `ADR.md`：ADR 记录的是相对稳定的架构决策，LOG 记录的是日常设计调整的过程脉络。如果某条 LOG 记录具有长期参考价值，提取为 ADR。
+同时按 log-format 在 `LOG.md` 末尾追加一条日志条目（状态 `deferred`）记录冲突内容与重新讨论的理由；如采纳新方案，按 adr-format 的修改规则更新对应 ADR 状态。

package/template/workflows/specdev/I-init-setup/status-labels.md

@@ -1,6 +1,6 @@
 # 状态标签
 
-specdev 各 work 使用五种规范的状态角色来追踪工作项的生命周期。本文件将这些角色映射到持久化文件中使用的实际标签字符串。
+specdev 的 issue 分诊（`T-triage` 及 `common/triage` skill）使用五种规范的状态角色来追踪工作项的生命周期。本文件将这些角色映射到持久化文件中使用的实际标签字符串。
 
 | 角色 | 标签 | 含义 |
 |------|------|------|
@@ -16,9 +16,8 @@ specdev 各 work 使用五种规范的状态角色来追踪工作项的生命周
 
 标签字符串写入位置取决于具体 work：
 
-- **T-tickets** —— 写入工作项文件（`tickets/NN-<slug>.md`）顶部的 `Status:` 行
-- **W-wayfinder** —— 写入 `wayfinder/map.md` 中工作项的状态标记
-- **其他 work** —— 在变更目录的相应产物文件中以 frontmatter 或元数据行形式记录
+- **T-triage** —— 写入变更目录 `triage.md` 的推荐 status 字段（参见 T-triage 步骤 4）
+- **其他 work** —— 引用这些角色时，在变更目录的相应产物文件中以元数据行形式记录
 
 ## 状态流转
 
@@ -51,4 +50,4 @@ needs-triage ──→ needs-info ──→ needs-triage ──→ ready-for-age
 | `ready-for-human` | `需人工` |
 | `wontfix` | `不处理` |
 
-确保标签字符串在实际使用位置（tickets 文件、wayfinder 地图等）保持一致。
+确保标签字符串在实际使用位置（triage.md 等产物文件）保持一致。

package/template/workflows/specdev/I-init-setup/tracking-convention.md

@@ -6,37 +6,24 @@ specdev workflow 的变更以 markdown 目录形式存储在 `{roots.state}/spec
 
 - 每个变更一个目录：`{roots.state}/specdev/changes/<YYYY-MM-DD>-<topic>/`
   - 例如：`changes/2026-07-21-add-auth-layer/`
-- 当前活跃变更通过 `{roots.state}/specdev/status.json` 的 `active` 数组追踪，每个条目为包含 `change`、`current_work`、`works_run`、`result` 等字段的对象
+- 当前活跃变更通过 `{roots.state}/specdev/status.json` 的 `active` 数组追踪，每个条目为包含 `change`、`current_work`、`works_run`、`result` 等字段的对象——完整字段定义见 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 的「状态字段」一节，此处不重复
 - 归档变更移至：`{roots.state}/specdev/archive/YYYY-MM/<change>/`
   - 例如：`archive/2026-07/2026-07-21-add-auth-layer/`
 - 变更目录内的工作产物由各 work 定义，典型结构：
   ```
   changes/<YYYY-MM-DD>-<topic>/
-  ├── CONTEXT.md      ← 领域术语与概念（由 domain-modeling 或 G-grill-with-docs 创建/更新）
-  ├── ADR.md          ← 架构决策记录（由 G-grill-with-docs 或 I-implement 创建/更新）
-  ├── LOG.md          ← 设计决策日志（按时间顺序记录每次设计调整）
-  ├── spec.md         ← 需求规格（由 S-spec 创建）
-  ├── tickets/        ← 工作项（由 T-tickets 创建）
-  │   └── NN-<slug>.md
-  └── wayfinder/      ← 路线图（由 W-wayfinder 创建）
-      └── map.md
-  ```
-- `status.json` 结构：
-  ```jsonc
-  {
-    "schema_version": 2,
-    "workflow": "specdev",
-    "active": [
-      {
-        "change": "2026-07-21-add-auth-layer",
-        "current_work": "specdev/grill-with-docs",
-        "works_run": [],
-        "result": null
-      }
-    ],
-    "work_history": [],
-    "completed": []
-  }
+  ├── .status.json    ← 本 change 的个体状态（见 INDEX.md「Per-change 状态文件」）
+  ├── CONTEXT.md      ← 领域词汇表（G-grill-with-docs 创建/更新）
+  ├── ADR.md          ← 架构决策记录（G-grill-with-docs 创建/更新）
+  ├── LOG.md          ← 设计决策日志（各 work 追加结论）
+  ├── spec.md         ← 需求规格（S-spec 创建）
+  ├── tickets-map.md  ← ticket 总体地图与执行清单（T-tickets 创建）
+  ├── ticket/         ← 独立 ticket 文件（T-tickets 创建）
+  │   └── NN-<name>.md
+  ├── map.md          ← 寻路地图（W-wayfinder 创建）
+  ├── goal-plan.md    ← 目标规划文档（P-goal-plan 创建）
+  ├── research/       ← 研究产物（common/research 维护，含 index.md）
+  └── prototype/      ← 原型产物（common/prototype 维护，含 index.md）
   ```
 
 ## 当 work 说"发布到变更目录"时
@@ -47,19 +34,19 @@ specdev workflow 的变更以 markdown 目录形式存储在 `{roots.state}/spec
 
 ## 当 work 说"获取当前变更"时
 
-读取 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组，获取当前活跃变更列表。如果存在多个活跃变更，提示用户选择目标变更。如果无活跃变更，提示用户先运行 `S-spec` 或 `I-init-setup` 创建变更。
+按 `<Path>{roots.workflows}/specdev/INDEX.md</Path>` 启动协议执行：读取 `status.json` 的 `active` 数组——用户指定则匹配对应条目；唯一活跃则直接使用；无活跃则创建新变更目录并追加条目；多个候选则由用户消歧。
 
 ## 当 work 说"归档变更"时
 
-将变更目录从 `{roots.state}/specdev/changes/<change>/` 移动到 `{roots.state}/specdev/archive/YYYY-MM/<change>/`（YYYY-MM 取变更日期中的年月），从 `status.json` 的 `active` 数组中移除对应条目，追加归档记录到 `completed` 数组。
+将变更目录从 `{roots.state}/specdev/changes/<change>/` 移动到 `{roots.state}/specdev/archive/YYYY-MM/<change>/`（YYYY-MM 取变更日期中的年月），从 `status.json` 的 `active` 数组中移除对应条目，追加归档记录到 `completed` 数组。完整归档与知识沉淀规程见 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。
 
 ## Wayfinding 操作
 
-供 `W-wayfinder` 使用。**地图**是一个文件，每个工作项有一个**子**文件。
+供 `W-wayfinder` 使用。**地图是单个文件** `{roots.state}/specdev/changes/<change>/map.md`，tickets 是地图文件内的编号小节，不是独立文件：
+
+- **状态**：checkbox 标记——`- [ ]` 开放、`- [x]` 已解决
+- **阻塞**：ticket 小节内的「被阻塞于」字段，以 ticket 标题引用
+- **领取**：将 ticket 名称追加到 `status.json` 当前 change 条目的 `claimed_tickets` 数组，完成后移除
+- **前沿**：开放、未被阻塞、未被领取的 tickets
 
-- **地图**：`{roots.state}/specdev/changes/<change>/wayfinder/map.md` —— Notes / Decisions-so-far / Fog 正文。
-- **子工单**：`{roots.state}/specdev/changes/<change>/tickets/NN-<slug>.md`，从 `01` 开始编号，正文中包含问题。`Type:` 行记录工单类型（`research` / `prototype` / `grilling` / `task`）；`Status:` 行记录 `claimed` / `resolved`。
-- **阻塞**：顶部附近的 `Blocked by: NN, NN` 行。当其列出的每个文件都处于 `resolved` 状态时，工单解除阻塞。
-- **前沿**：扫描 `tickets/` 中处于开放、未阻塞且未认领状态的文件；按编号取第一个。
-- **认领**：设置 `Status: claimed` 并在任何工作开始前保存。
-- **解决**：在 `## Answer` 标题下追加答案，设置 `Status: resolved`，然后将上下文指针（gist + 链接）追加到 `map.md` 中地图的 Decisions-so-far 中。
+完整地图结构与遍历规程见 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。

package/template/workflows/specdev/INDEX.md

@@ -27,7 +27,9 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
 | 活跃变更 | `<Path>{roots.state}/specdev/changes/</Path>` | 进行中的 change 产物（ADR、LOG、CONTEXT、spec、tickets、map 等） |
 | 永久 ADR | `<Path>{roots.state}/specdev/adr/</Path>` | changes 中经确认后的 ADR 提升至此，始终反映当前架构决策现状 |
 | 永久词汇表 | `<Path>{roots.state}/specdev/context/</Path>` | changes 中经确认后的 CONTEXT 提升至此，始终反映当前领域术语现状 |
+| 永久研究库 | `<Path>{roots.state}/specdev/research/</Path>` | changes 中长期有效的研究产物提升至此，由 A-archive-and-consolidate 维护 |
 | 变更归档 | `<Path>{roots.state}/specdev/archive/</Path>` | 已完成并归档的历史 change，按 YYYY-MM/<change>/ 组织 |
+| 全局配置 | `<Path>{roots.state}/specdev/config.json</Path>` | 交互语言、报告语言与持久化设置，由 I-init-setup 生成，各 work 启动时读取 |
 
 `.config/` 目录包含三个由 `I-init-setup` 生成的配置文件，定义 specdev 各 work 的持久化和行为约定：
 
@@ -35,7 +37,7 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
 - **`domain-layout.md`** — 领域文档布局：三文件模型（CONTEXT.md / ADR.md / LOG.md）的路径解析规则和读取顺序
 - **`status-labels.md`** — 状态标签映射：五个标准角色（`needs-triage` / `needs-info` / `ready-for-agent` / `ready-for-human` / `wontfix`）的标签字符串、状态流转图和自定义方式
 
-`status.json`、`changes/`、`archive/` 为固定骨架，由 `speculo init` 创建。`adr/` 和 `context/` 为确认后创建——当 changes 中的 ADR、CONTEXT 经确认符合当前现状后，提升到这两个目录，始终保持与项目当前状态一致。
+`status.json`、`changes/`、`archive/`、`adr/`、`context/`、`research/` 均随骨架由 `speculo init` 创建；后三者初始为空——changes 中的 ADR、CONTEXT、研究产物经确认符合当前现状后提升至此，始终保持与项目当前状态一致。
 
 ## 启动协议
 
@@ -45,6 +47,7 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
    - 唯一活跃 change → 直接使用 `active[0]`
    - 无活跃（`active` 为空数组）→ 创建 `changes/<YYYY-MM-DD>-<kebab-topic>/`，追加条目 `{ change, current_work: null, works_run: [], result: null }` 到 `active`
    - 多个候选 → 列出 `active` 中各 change，由用户消歧
+   - 例外：`T-triage` 分诊外部 issue 时默认总是创建新 change，仅用户声明续作时复用活跃条目（见 T-triage 步骤 3）
 
 ## 状态字段
 
@@ -96,6 +99,8 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
 
 ## Work 条目
 
+work id 格式为 `specdev/<work-name>`，其中 `<work-name>` 为 work 目录名去掉字母前缀（如 `G-grill-with-docs` → `specdev/grill-with-docs`）。
+
 <!-- AUTO-INDEX-START -->
 
 - **A-archive-and-consolidate** — 归档与沉淀：将已完成变更归档至 archive/，并智能评估、提取持久化知识到 adr/、context/、research/ 知识库——与现有知识逐项比对，执行创建/更新/合并/废弃，确保知识始终最新。
@@ -104,6 +109,7 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
 - **I-implement** — 实现：基于 spec 或 tickets 实现工作——以深层模块设计原则指导架构、以 TDD 红绿循环驱动编码、以双轴审查把关质量。
 - **I-init-setup** — 初始化设置：为 specdev workflow 配置变更追踪、领域文档布局、状态标签和语言偏好。首次使用其他 specdev works 前运行一次。
 - **P-goal-plan** — 目标规划：将 spec、tickets 和参考权威综合为一份目标规划文档——编排多 ticket 里程碑的约束、质量门禁和执行协议，桥接"已有 tickets"到"协调执行 20+ tickets"
+- **R-review-architecture** — 架构审查：扫描代码仓寻找深层化机会——发现浅模块、接缝泄漏和局部性缺陷，以可视化 HTML 报告呈现候选方案，逐一访谈深化。
 - **S-spec** — 编写 Spec：将当前对话综合为一份完整的 spec 文档，包含问题陈述、解决方案、用户故事、实现决策和测试决策，持久化到变更目录。
 - **T-tickets** — 拆分 Tickets：将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
 - **T-triage** — Issue 分诊：将外部 issue 摄入并分诊为本地 change：深度理解上下文后写入 source-issue.md 与 triage.md，再推荐下一 work（G-grill / S-spec / I-implement / D-diagnose 等）。

package/template/workflows/specdev/P-goal-plan/execution-sections.md

@@ -32,7 +32,7 @@ P0 门禁先开，阻塞所有 P1/P2 关闭。ticket 可以在其依赖就绪后
 - 用注释标注门禁边界：`--- P0 gate ---`
 - 可立即开始的 ticket 标注 `[READY]`
 - 扇出点标注 `[FAN-OUT: N路并行]`
-- ticket 编号使用两位零填充纯数字（`01`, `02`, …），**不含** `#`
+- ticket 编号格式见 T-tickets（两位零填充纯数字，不含 `#`）
 
 示例格式：
 ```
@@ -75,7 +75,7 @@ tickets-map.md 的「并行规则」节已由模板预设默认值（最大 3
 
    Lead 读取 issue 全文、合同/参考权威对应行、ticket 的验收标准。如果激活参考权威模式，对照参考快照中的对应交互路径。
 
-2. **派单** —— Lead 输出结构化派单行 `IMPLEMENTER_DISPATCH <n> issue=<url> gate=<P0|P1|P2> allowlist=<files> contract_ids=<...>`（`<n>` 为两位零填充纯数字编号，如 `01`，不含 `#`），然后生成实现子代理（model: fable, 唯一 name）。Lead+Subagent 模型下，加载 `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` 获取完整的编排协议——包括子代理上下文载荷结构、handoff 交接、合并冲突解决、Worktree 隔离和收尾审查的详细步骤。
+2. **派单** —— Lead 输出结构化派单行 `IMPLEMENTER_DISPATCH <n> issue=<url> gate=<P0|P1|P2> allowlist=<files> contract_ids=<...>`（`<n>` 编号格式见 T-tickets），然后生成实现子代理（使用当前可用的最强实现模型，唯一 name）。Lead+Subagent 模型下，加载 `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` 获取完整的编排协议——包括子代理上下文载荷结构、handoff 交接、合并冲突解决、Worktree 隔离和收尾审查的详细步骤。
 3. **实现** —— 子代理在 file allowlist 内实现变更，按 ticket 指定的测试矩阵运行测试；实现过程遵循 I-implement 的设计检查与 TDD 红绿循环。
 4. **双轴审查** —— 实现完成后，立即启动两个审查子代理并行运行：
    - `reviewer-standards-<n>`：代码质量、架构、测试覆盖

package/template/workflows/specdev/P-goal-plan/governance-sections.md

@@ -9,7 +9,7 @@
 全部 ticket 关闭后执行以下验收仪式：
 
 1. **合同/ADR 终审** —— 如果激活合同模式：逐行检查合同文档，确认所有行状态为 `done` 或 `deviate`（有记录理由），无 `todo` 残留；如果无合同但激活 ADR 模式：检查 ADR 偏差表条目已解决或明确记录为 `deviate`
-2. **整体验证门禁** —— 运行 `pnpm verify`（或 spec 中指定的验证命令），确认全绿
+2. **整体验证门禁** —— 运行 spec 或项目脚本声明的整体验证命令（类型检查 + 测试 + 构建的组合），确认全绿
 3. **集成回归走查** —— 完成一次端到端用户旅程脚本走查
 4. **关闭 spec issue** —— 关闭关联的 spec issue，引用 milestone done
 5. **人工 side-by-side 验证清单** —— 输出人工核对清单供用户在真机上执行最终手感验收
@@ -48,7 +48,7 @@
 3. **伪完成禁止** —— 「能力存在但手感、交互细节、边界情况、空状态文案与参考/规格不一致，视为未完成。禁止以"API 通了"为由关闭 ticket。」
 4. **Git 纪律** —— 如果使用 Lead+Subagent 模型：「仅 Lead 操作 Git（提交、合并、推送）。子代理输出 diff/patch，Lead 审查后提交。」
 5. **单一真相源** —— 「不复活废弃组件、不创建规格外的新抽象、不引入与 ADR 冲突的外部依赖。所有技术决策追溯到 ADR 或 LOG。」
-6. **沟通语言** —— 「全部代码注释、提交信息、issue 评论、进度报告使用简体中文。」
+6. **沟通语言** —— 「全部代码注释、提交信息、issue 评论、进度报告使用 {report_language}。」（生成 goal-plan 时从 `<Path>{roots.state}/specdev/config.json</Path>` 的 `defaults.report_language` 读取并填入具体语言）
 
 #### 模式特定约束
 
@@ -74,7 +74,7 @@ TICKET_DONE <n> (<k>/<N>) gate=<P0|P1|P2> contract_ids=<P0-01,P1-03> verify=<cmd
 ```
 
 字段说明：
-- `<n>` —— ticket 编号（两位零填充纯数字，如 `01`，不含 `#`）
+- `<n>` —— ticket 编号（格式见 T-tickets）
 - `(<k>/<N>)` —— 进度计数（当前第几个 / 总数）
 - `gate` —— 门禁层级
 - `contract_ids` —— 如激活合同模式，列出本 ticket 覆盖的合同条目 ID，逗号分隔；如无合同则使用 `adr_ref=<ADR-NNNN>`

package/template/workflows/specdev/P-goal-plan/lead-orchestration-protocol.md

@@ -40,7 +40,7 @@ IMPLEMENTER_DISPATCH <n>
   implement_ref: <{roots.workflows}/specdev/I-implement/I-implement.md>
 ```
 
-其中 `<n>` / `<nn>` 为两位零填充纯数字 ticket 编号（如 `01`），不含 `#`。
+其中 `<n>` / `<nn>` 为 ticket 编号（格式见 T-tickets：两位零填充纯数字，不含 `#`）。
 
 Lead 在生成子代理时将以上文件作为上下文传入，确保子代理在开始实现前已读取全部载荷。永久 ADR 和永久 CONTEXT 目录可能为空——静默继续。
 
@@ -118,14 +118,11 @@ Lead 在生成子代理时将以上文件作为上下文传入，确保子代理
 
 子代理完成实现并通过审查和门禁后：
 
-1. Lead 调用 `<Path>{roots.workflows}/specdev/common/dev-worktree/SKILL.md</Path>` Phase B
-2. Phase B 流程：验证测试通过 → 展示选项（本地合并/PR/保留/丢弃）→ 执行所选选项
-3. 默认选项为本地合并：checkout base → pull → `git merge --no-ff <change_branch>` → 在合并结果上重跑测试
-4. 合并成功后，从主仓库根目录执行：`git worktree remove <path>` → `git branch -d <branch>` → `git worktree prune`
-5. 更新 `.status.json`：`worktree_status: removed`
-6. 如果 worktree finalize 期间出现合并冲突，跳转到 §3 合并冲突解决协议
+1. Lead 调用 `<Path>{roots.workflows}/specdev/common/dev-worktree/SKILL.md</Path>` Phase B（完整命令序列见 `common/dev-worktree/references/finalize.md`）
+2. 默认选项为本地合并；合并冲突跳转到 §3
+3. 更新 `.status.json`：`worktree_status: removed`
 
-**完成标准**：每个并发子代理在独立 worktree 中工作，分支名 `speculo/specdev/<change>-<ticket-n>`；任意两个子代理的 file allowlist 无重叠；基线测试在 worktree 创建时通过；子代理完成后 worktree 已合并回 base 分支、worktree 目录和临时分支已清理；`.status.json` 反映最终状态。
+**完成标准**：每个并发子代理在独立 worktree 中工作，分支名 `speculo/specdev/<change>-<ticket-n>`；任意两个子代理的 file allowlist 无重叠；基线测试在 worktree 创建时通过；子代理完成后 worktree 已按 finalize 规程合并并清理；`.status.json` 反映最终状态。
 
 ## 5. 里程碑收尾审查与清理
 

package/template/workflows/specdev/P-goal-plan/vision-sections.md

@@ -70,7 +70,7 @@
 
 - ticket 数量从 tickets-map.md 统计
 - 合同条目从合同文档的表格行计数
-- verify 命令从 spec.md Test Decisions 提取，如无则使用 `pnpm verify`
+- verify 命令从 spec.md Test Decisions 提取，如无则从项目脚本（package.json scripts、Makefile 等）探测整体验证命令，不确定时询问用户
 - 锁定裁定数量从 §2 提取
 
 ### 草拟与确认