@namewta/speculo 0.3.4 → 0.5.0

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

@@ -3,27 +3,38 @@ id: specdev/grill-with-docs
 type: workflow-entry
 workflow: specdev
 name: 设计访谈（带文档）
-description: 通过一次一问的设计访谈打磨方案，同时持续维护设计日志、领域上下文和架构决策。
-keywords: [设计访谈, ADR, LOG, CONTEXT, 决策, 领域建模]
+description: 以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护设计树、日志、领域上下文和架构决策。
+keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决策, 领域建模]
 ---
 
 # 设计访谈（带文档）
 
-本 work 保留原有的 grilling 访谈与 domain-modeling 双重能力：访谈负责沿决策树逐分支达成共识，领域建模负责在决策结晶时同步维护设计轨迹、术语与架构决策。未经用户确认，不进入实现。
+不留情面地访谈用户，直到达成共识。把这件事映射为一棵**设计树（design tree）**：每个决策都会分出挂在它下面的后续决策。
 
-## 输入与权威
+按**轮次**推进这棵树。**前沿（frontier）** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier；用户的答案会重塑设计树并解除下一层问题的阻塞。
 
-开始前按需读取：
+本 work 还负责把访谈持久化：设计树保存可恢复状态，LOG 保存讨论轨迹，CONTEXT 保存当前领域真相，ADR 保存长期架构决定。持久化不构成实现授权；在用户确认共识前不进入实现。
 
-- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
-- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
-- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
-- 原始请求：`<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
-- 分诊结果：`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
-- Bug 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
-- 当前 Spec（如已存在）：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- 工件职责规则：`<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
-- 规划原则：`<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+## 输入与产物
+
+按存在情况读取：
+
+- `<Path>{roots.state}/specdev/config.json</Path>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+
+本 work 拥有：
+
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</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>`
 
 不存在的可选输入静默跳过，不把缺失文件伪装成已知事实。
 
@@ -31,99 +42,93 @@ keywords: [设计访谈, ADR, LOG, CONTEXT, 决策, 领域建模]
 
 ### 1. 启动或恢复 change
 
-创建或恢复 `<Path>{roots.state}/specdev/changes/{change}/</Path>`，其中 `{change}` 使用 `<YYYY-MM-DD>-<topic>`。
-
-首次启动时创建：
-
-- 生命周期状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`（首次创建时使用 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`）
-- 架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.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}/</Path>`。首次启动时创建 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`，并以 `<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>` 为模板创建 `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`。
 
-创建和更新格式分别遵循：
+分别使用：
 
 - `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
 - `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
 - `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
 
-恢复已有 change 时必须先读取现有三份文档，避免重复询问已经确认的问题。
+恢复时先读取四份工件，按 design tree 的节点状态恢复，避免重复询问已关闭问题。
 
-**完成标准**：change 目录、生命周期状态和三份设计文档均可读取；已知结论与未决问题已建立初始摘要。
+**完成标准**：四份工件均可读取；节点依赖无环，所有 LOG 指针存在，当前 frontier 可确定。
 
-### 2. 探索可发现事实
+### 2. 查找事实
 
-在提问前只读探索相关代码、配置、接口、schema、测试、历史 ADR 和相邻实现。将未知项分为：
+查找*事实*是 Agent 的工作，永远不是用户的。先探索相关代码、配置、接口、schema、测试、历史 ADR 和相邻实现。
 
-- 可发现事实：继续探索，不询问用户；
-- 高影响偏好或取舍：进入访谈；
-- 低影响实现细节：记录为实现者可自行决定，不升级为产品决策。
+当前沿问题需要来自环境的事实时，派遣独立探索去查找。不要阻塞等待：一次进行中的探索是一个未解决的前置条件，所以只有它下游的问题等待结果；现在就继续处理 frontier 的其余部分。不熟悉的外部技术使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-若涉及不熟悉的外部技术、第三方 API、标准或版本行为，调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`，并把研究结论的来源和置信度写入 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
+将未知项分为：
 
-### 3. 一次一问的设计访谈
+- 可发现事实：探索或研究，不询问用户；
+- 高影响决策：进入设计树；
+- 低影响实现细节：记录为实现者可自行决定，不制造决策节点。
 
-加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。每轮只处理一个会实质改变设计的问题：
+**完成标准**：每个候选问题已分类；用户只接收无法从环境发现的真实决策。
 
-1. 陈述已知事实与证据；
-2. 提出唯一关键问题；
-3. 给出 2–4 个真实选项、权衡和推荐默认值；
-4. 等待用户确认、拒绝或延后；
-5. 将结果立即追加到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
+### 3. 建立设计树
 
-不得把多个独立决策塞进同一个问题；不得为了填模板询问不会改变方案的细节；不得在用户尚未确认前执行实现。
+围绕目标、角色、范围、主要流程、状态与失败、数据与接口、兼容与迁移、安全与隐私、性能与可观测性、验证与验收建立适用节点。
 
-**完成标准**：决策树已覆盖目标、角色、范围、主要流程、状态与失败、数据与接口、兼容与迁移、安全与隐私、性能与可观测性、验证与验收等适用分支。
+每个节点包含稳定 `D-###`、标题、问题、依赖、推荐答案和状态。只有问题本身已经可以精确陈述时才创建节点；依赖尚未确定的节点可以存在，但不进入 frontier。
 
-### 4. 同步领域文档
+**完成标准**：每个高影响已知决策有且只有一个节点；每条依赖指向真实上游节点；没有默默采用的高影响假设。
 
-加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`，按固定顺序同步：
+### 4. 逐轮推进完整 frontier
 
-1. 先把所有确认、延后、拒绝和替代结论写入 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`；
-2. 再把当前仍真实的术语、不变量、示例、反例和代码映射写入 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`；
-3. 最后把满足 ADR 条件的长期架构决策写入 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。每轮原子增加 `round`，重读设计树并计算完整 frontier。按协议格式给每个问题编号并附推荐答案，然后等待用户回答。
 
-历史轨迹不得写入领域上下文；尚未确认的选项不得写成已接受 ADR；已有 ADR 被替代时必须建立 supersedes 链，不重写历史。
+用户回答后：
 
-### 5. 收敛与就绪判断
+1. 为每个回答更新对应节点；
+2. 每个节点各追加一条 LOG，不把多个决定压成一条；
+3. 根据回答增加、删除或重新连接后续节点；
+4. 重新计算 frontier，进入下一轮。
 
-访谈结束时必须能明确：
+一个答案依赖本轮仍开放问题的提问属于后续轮次。用户延后且该决定会影响外部行为、公共接口、数据、安全、兼容、迁移或验收时，保持 blocked，不把它伪装成共识。
 
-- 目标、目标用户、成功标准；
-- IN、REUSE、OUT；
-- 主要行为路径、失败行为与状态转换；
-- 公共接口、数据、不变量、兼容和迁移影响；
-- 安全、隐私、性能、可靠性和可观测性要求；
-- 验证接缝和可观察验收方式；
-- 剩余未知项及其影响。
+**完成标准**：本轮开始时的完整 frontier 每个节点都有回答、明确延后或阻塞记录；所有状态已原子写入并重读。
 
-仍存在会改变外部行为、范围、公共接口、数据、安全、兼容、迁移或验收的未决问题时，将 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 标为 `blocked` 或保持 `active`，不得伪装为 Ready。
+### 5. 同步领域模型
 
-### 6. 停止与路由
+加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG，再把已确认且当前仍真实的术语、不变量、示例、反例和代码映射同步到 CONTEXT，最后把满足 ADR 条件的长期架构决定写入 ADR。
 
-向用户汇报三份文档的新增/修改条目、已锁定决策、延后事项和风险。根据成熟度明确给出下一步：
+历史轨迹只留在 LOG；未确认选项不写成已接受 ADR；已有 ADR 被替代时建立 supersedes 链。同步文档用于记录共识生长过程，不授权产品实现。
+
+**完成标准**：LOG、CONTEXT、ADR 和 design tree 无冲突；每个提升结论都有用户回答或事实来源。
+
+### 6. 共识确认与路由
+
+frontier 为空时，向用户确认设计树的每个分支均已走过且已经达成共识。用户指出遗漏时新增节点并继续；只有明确确认后把 design tree 标为 `consensus`。
+
+随后按成熟度路由：
 
 - 通常进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
-- 外部行为已经完全明确时可进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
-- 极小、局部且已经具备批准执行契约的工作，可在用户确认后进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`；
+- 外部行为已经完全明确时进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
+- 获批的极小局部工作可进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`；
 - 路径或关键事实仍未知时进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。
 
-同步 `<Path>{roots.state}/specdev/status.json</Path>` 的 `current_work`、`work_history` 和当前 change 状态，返回三份权威工件及下一 Work 的完整路径。
-
-不得在本 work 中自动读取实现源码并开始修改代码。
+同步 workflow/change 状态，返回四份权威工件和下一 work 的完整路径。不自动执行下一 work。
 
 ## 完成标准
 
-- `<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>` 只包含满足条件的架构决策；
-- 高影响未决问题已关闭或明确标记为阻塞；
-- 状态、权威工件和下一 Work 路径已返回；
-- 下一 work 已明确，但未自动执行实现。
+- 设计树的每个适用分支都已走过，没有高影响事项被默默假定；
+- 每轮询问的是完整 frontier，依赖未关闭的问题没有提前出现；
+- 可发现事实由 Agent 查找，没有转交用户；
+- design tree 通过 schema，LOG 指针完整；
+- CONTEXT 只包含当前领域真相，ADR 只包含满足条件的架构决定；
+- frontier 为空且用户明确确认共识；
+- 状态、权威工件和下一 work 路径已返回；
+- 未执行产品实现。
 
 ## 子文件引用
 
-- 访谈协议：`<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>`
+- 质询协议：`<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`
+- 设计树模板：`<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>`
+- 领域建模：`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`
 - ADR 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
-- 领域上下文格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
-- 设计日志格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
+- CONTEXT 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
+- LOG 格式：`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`

package/template/workflows/specdev/G-grill-with-docs/design-tree-template.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "artifact": "design-tree",
+  "change": "{change}",
+  "status": "active",
+  "round": 0,
+  "nodes": []
+}
+

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

@@ -1,45 +1,26 @@
-# 设计访谈协议
+# 设计树质询协议
 
-目标是关闭会影响产品行为、架构边界、风险或验收的关键决策，不是把所有可能问题都问一遍。
+不留情面地访谈用户，直到达成共识。把这件事映射为一棵**设计树（design tree）**：每个决策都会分出挂在它下面的后续决策。
 
-## 1. 开始前先发现事实
+按**轮次**推进这棵树。**前沿（frontier）** 是所有前置条件已经确定的决策——那些你现在就能问、不必猜测还没听到的答案的问题。在一轮中问完整条前沿：给每个问题编号，并附上你的推荐答案。然后等待用户的回答，再进入下一轮。
 
-先读取代码、配置、测试、现有 Spec、ADR、CONTEXT 和 LOG。可从环境获得的事实不得转交给用户回答；只有偏好、风险承受度、业务取舍或互斥目标需要用户决策。
+每个问题按如下格式呈现：
 
-## 2. 决策树
+```
+❓ **Q1** - **<问题标题>**：<问题正文，可以是多个段落，包括多个选项>
 
-按风险和信息缺口覆盖，不机械提问：
+➡️ <你的推荐答案>
+```
 
-1. 用户问题与成功状态；
-2. 参与者、权限与主要流程；
-3. 范围边界和明确非目标；
-4. 状态、数据、不变量与失败模式；
-5. 接口、兼容、迁移和发布；
-6. 安全、隐私、性能、可观测性；
-7. 验收与验证接缝。
+每一轮用户的回答都会重塑这棵树——已确定的决策把前沿向外推，解除依赖它们的阻塞问题。重新计算前沿，然后问下一轮。一个答案依赖本轮仍在开放中的问题的提问，属于*更晚的*轮次，而不是本轮。
 
-## 3. 每轮只关闭一个关键决定
+查找*事实*是你的工作，永远不是用户的。当前沿问题需要来自环境的事实（文件系统、工具等）时，派遣一个子 agent 去查找——不要就任何你自己能查到的东西去问用户。不要阻塞等待：一次正在进行的探索是一个未解决的前置条件，所以只有它下游的问题需要等子 agent 报告——现在就把前沿的其余部分问完。*决策*是用户的——把每个决策摆到他们面前并等待。
 
-每轮格式：
+当前沿为空时，会话结束：设计树的每个分支都已走过，没有任何东西被默默假定。在用户确认我们已达成共识之前，不要对结果采取行动。
 
-1. **已知事实：** 简短说明当前共识和证据；
-2. **唯一问题：** 不使用复合问题；
-3. **可行选项：** 只列实质不同的方案；
-4. **权衡：** 对范围、体验、架构、风险和未来成本的影响；
-5. **推荐：** 明确给出默认建议及原因；
-6. **用户结论：** confirmed / deferred / rejected；
-7. **落盘：** 更新 LOG，并按需要更新 ADR 或 CONTEXT。
+## SpecDev 持久化适配
 
-## 4. 记录规则
-
-- 所有已确认或显式延后的决策写入 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`；
-- 长期架构决策追加到 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
-- 稳定领域知识追加或合并到 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`；
-- 不因追求“文档完整”而复制同一事实；工件冲突按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 裁决。
-
-## 5. 停止条件
-
-- 关键决策已关闭，足以进入 Spec；或
-- 用户明确延后，且该延后不会伪装成 Ready；或
-- 缺少外部信息，change 标 blocked；或
-- 继续提问只会产生低影响实现细节，应交给 Ticket 或实现阶段决定。
+- 设计树当前状态写入 `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`，结构遵循 `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`。
+- 每个已回答、延后或拒绝的节点追加一条 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 记录，并把 `LOG-###` 写回节点的 `log_ref`。
+- 每轮开始前原子更新 `round`，重读设计树后计算 frontier：`status=open` 且全部 `depends_on` 节点为 `answered` 的节点集合。
+- LOG、设计树及已确认的 CONTEXT/ADR 同步只用于恢复和领域建模，不构成实现授权。只有 frontier 为空且用户确认共识后才路由下游 work。

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

@@ -2,6 +2,8 @@
 
 ```markdown
 ## LOG-### — <时间> — <主题>
+- **设计树节点：** D-### / 不适用
+- **轮次与依赖：** round <n> / D-###, D-### / 无
 - **状态：** confirmed / deferred / rejected / superseded
 - **问题：** 本条只记录一个决策或未知
 - **事实与来源：** 代码、测试、用户确认或外部规范

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

@@ -9,7 +9,7 @@ keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
 
 # 实现
 
-本 work 保留原有完整实现能力：深层模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、标准轴与规范轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence 和偏差门禁，但不把实现退化为机械照单执行。
+本 work 保留原有完整实现能力：深模块设计检查、接缝和依赖分类、design-it-twice、TDD 红→绿垂直循环、标准轴与规范轴审查、项目级验证、提交和状态更新。治理升级增加 Ready、路径所有权、Evidence 和偏差门禁，但不把实现退化为机械照单执行。
 
 ## 执行模式
 
@@ -23,6 +23,8 @@ keywords: [实现, TDD, 代码审查, 模块设计, 证据, ticket]
 
 Ticket 模式适用于多 Ticket、Standard/Deep、并行、迁移或需要完整证据治理的工作。
 
+若 Goal Plan 的 Delivery Contract 选择 `native-subagent` 或 `external-web-subagent`，这是 Ticket 模式的 delegated execution 分支。Lead 在派单、恢复或验收候选交付时调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`；Worker 的局部实现仍完整遵循本 work，不由 provider 改写。
+
 ### Direct Spec 模式（保留原能力）
 
 极小、局部、单一行为且不需要独立 Ticket DAG 的工作，可以在用户明确批准后直接基于：
@@ -61,6 +63,7 @@ Ticket 模式检查：
 - Ticket 与 Spec/ADR/Goal Plan 无冲突；
 - 可写、只读、共享路径明确且无并发冲突；
 - 并行执行时，Ticket 的 worktree 记录为 `active`，`base_sha` 与派单一致；
+- delegated execution 时，派单块的 execution model、Lead、checkpoint、workspace/session locator、路径合同、修正上限和授权矩阵与当前事实一致；
 - 验证命令和 Evidence 位置可用；
 - 当前代码事实没有使核心契约失效。
 
@@ -76,10 +79,7 @@ Direct Spec 模式检查：
 
 ### 2. 设计检查
 
-加载：
-
-- `<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
-- `<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
+加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`，并严格使用其中的模块、接口、深度、接缝、适配器、杠杆和局部性术语。
 
 在写代码前检查：
 
@@ -91,7 +91,7 @@ Direct Spec 模式检查：
 - 测试应在哪个稳定接缝观察行为；
 - Ticket/Spec 已锁定的公共契约是否被保持。
 
-存在多个局部接口设计且不改变已锁定契约时，可以运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。若方案会改变外部行为、公共接口、数据、兼容、安全或范围，返回规划工件，不使用 design-it-twice 绕过决策。
+存在多个局部接口设计且不改变已锁定契约时，可以运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。若设计摩擦已经超出当前 Ticket 范围，返回 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`；若方案会改变产品行为、公共接口、数据、兼容、安全或范围，返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 或相应规划工件，不使用 design-it-twice 绕过决策。
 
 若不熟悉外部库、框架 API 或依赖能力边界，调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
@@ -159,6 +159,8 @@ Direct Spec 模式写入：
 
 Evidence 必须包含实际修改范围、命令与结果、验收逐条映射、未运行项、偏差、残余风险和提交引用。
 
+delegated execution 还必须记录 execution model、provider、派单与最终 checkpoint、workspace/session locator、候选交付核对、修正轮次和未验证声明。Lead 使用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>` 的 `operation=execute` 分支完成核对；provider 自报结果不能直接标记为 `pass`。
+
 Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使用 `blocked`，实际实现与批准契约不一致使用 `deviated`。验证无法运行或存在未批准偏差时不得标 `done`。
 
 同步：
@@ -177,12 +179,12 @@ Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使
 5. 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、commit 或 PR 引用，以及仅在用户界面交互受影响时由 Lead 执行的待办 E2E；
 6. Direct Spec 模式返回 change、状态和 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。
 
-若由 Lead 编排，遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>` 的 Evidence 返回协议。
+若由 Lead 编排，遵循 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>` 的 Evidence 返回协议；delegated execution 同时返回稳定 workspace/session locator、最终 checkpoint、修正轮次和未验证项。
 
 ## 完成标准
 
 - 执行前预检通过；
-- 设计检查保留深层模块、接缝和依赖分类能力；
+- 设计检查严格使用共享术语，并保留深模块、接缝、适配器和依赖分类能力；
 - 每个行为通过真实红→绿循环实现；
 - 定向与适用回归验证完成；
 - 双轴审查通过；
@@ -196,11 +198,11 @@ Ticket 状态依次为 `ready → in_progress → review → done`；阻塞使
 ## 子文件引用
 
 - 执行前预检：`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
-- 代码库设计术语：`<Path>{roots.workflows}/specdev/I-implement/codebase-design-glossary.md</Path>`
-- 深化与依赖策略：`<Path>{roots.workflows}/specdev/I-implement/deepening.md</Path>`
+- 代码库设计规则：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 - Design It Twice：`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
 - TDD 规则：`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`
 - TDD 示例：`<Path>{roots.workflows}/specdev/I-implement/tdd-examples.md</Path>`
 - 代码注释规则：`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
 - 双轴审查：`<Path>{roots.workflows}/specdev/I-implement/code-review-process.md</Path>`
 - Evidence 模板：`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
+- Agent 交付合同：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`

package/template/workflows/specdev/I-implement/design-it-twice.md

@@ -1,9 +1,48 @@
-# Design It Twice
+# 设计两次
 
-只在 Ticket 允许局部设计自由、且两个方案会显著影响模块深度或测试接缝时使用。
+当用户想要为选定的深化候选探索替代接口时，使用此并行子 Agent 模式。基于 "Design It Twice"（Ousterhout）— 你的第一个想法不太可能是最好的。
 
-1. 在不改代码的情况下提出两个最小接口草图。
-2. 比较调用者复杂度、信息隐藏、错误语义、迁移成本和测试策略。
-3. 选择更深、更局部、与 Ticket 契约一致的方案，并记录为局部实现决定。
+使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 中的词汇 — **module**（模块）、**interface**（接口）、**seam**（接缝）、**adapter**（适配器）、**leverage**（杠杆）。
 
-若选择会改变公共接口、数据、兼容、范围或验收，停止并升级到 Ticket/ADR，而不是自行选择。
+## 流程
+
+### 1. 界定问题空间
+
+在启动子 Agent 之前，为选定候选编写一份面向用户的问题空间说明：
+
+- 任何新接口需要满足的约束条件
+- 它将依赖的依赖项，以及它们属于哪个类别（参见 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的“依赖类别”）
+- 一个粗略的示例代码草图来使约束具体化 — 不是提案，只是让约束变得具体的一种方式
+
+将此展示给用户，然后立即进入第 2 步。用户在子 Agent 并行工作时阅读和思考。
+
+### 2. 启动子 Agent
+
+使用 Agent 工具并行启动 3+ 个子 Agent。每个子 Agent 必须为深化后的模块生成一个**截然不同的**接口。
+
+为每个子 Agent 提供一份独立的技术简报（文件路径、耦合细节、来自共享设计规则的依赖类别、接缝背后的内容）。简报独立于第 1 步中面向用户的问题空间说明。给每个 Agent 一个不同的设计约束：
+
+- Agent 1："最小化接口 — 目标 1–3 个入口点。最大化每个入口点的杠杆。"
+- Agent 2："最大化灵活性 — 支持多种用例和扩展。"
+- Agent 3："为最常见的调用方优化 — 让默认情况变得简单。"
+- Agent 4（如适用）："围绕接缝设计端口与适配器，以处理跨接缝依赖。"
+
+在简报中同时包含共享设计规则的词汇和 CONTEXT 词汇，以便每个子 Agent 能使用架构语言和项目的领域语言一致地命名事物。
+
+每个子 Agent 输出：
+
+1. 接口（类型、方法、参数 — 以及不变量、排序、错误模式）
+2. 使用示例，展示调用方如何使用它
+3. 实现在接缝背后隐藏了什么
+4. 依赖策略和适配器
+5. 权衡 — 哪里杠杆高，哪里杠杆薄
+
+### 3. 展示和比较
+
+按顺序展示各个设计，让用户能够消化每一个，然后用文字进行比较。通过 **depth**（深度，接口处的杠杆）、**locality**（局部性，变更集中的位置）和 **seam placement**（接缝位置）来对比。
+
+比较之后，给出你自己的建议：你认为哪个设计最强以及原因。如果不同设计中的元素可以很好地组合，提出一个混合方案。要有主见 — 用户想要的是一个有力的判断，而不是一个菜单。
+
+## SpecDev 门禁
+
+本模式只探索接口，不修改代码。只有 Ticket 允许局部设计自由且候选不改变已锁定契约时可由实现者选择；涉及公共接口、数据、兼容、安全、范围或验收时停止并升级到 Ticket/ADR，暴露更广架构问题时返回 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`。

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

@@ -7,6 +7,10 @@
 - **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` / 不适用
 - **基线/分支：**
 - **Worktree 引用：** 不适用 / `<workspace_ref>`
+- **执行模型/Provider：** direct / native-subagent / external-web-subagent；provider 或不适用
+- **Session/Package locator：** 不适用 / `<portable-locator>`
+- **派单/最终 Checkpoint：** `<sha-or-local-baseline>` / `<sha-or-local-baseline>`
+- **修正轮次：** 0 / `<count>`
 - **实现者：**
 - **开始/结束：**
 - **状态：** review / done / blocked / deviated
@@ -38,6 +42,8 @@
 - **失败后修复与重跑：** 无 / ...
 - **未运行检查：** 无 / 原因与风险 ...
 - **Lead E2E：** 不适用 / 待执行：场景与预期 / 通过 / 失败
+- **反向验证：** 不适用 / 受控失败信号与恢复结果
+- **外部声明：** 无 / 已核对 / `unverified`：原因
 
 ## 5. 路径所有权审计
 
@@ -66,4 +72,5 @@
 ## 8. 交付定位
 
 - **Commit / PR：**
+- **最终 Workspace/Session locator：** 不适用 / `<portable-locator>`
 - **Evidence 文件：** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`

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

@@ -8,7 +8,11 @@
 - [ ] 当前代码入口、接口和路径仍与 Ticket 假设一致。
 - [ ] writable_paths 无并发 owner 冲突。
 - [ ] 并行执行时，`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 中本 Ticket 为 `active`，`base_sha`、分支和 `workspace_ref` 与派单一致。
+- [ ] delegated execution 时，Goal Plan 只有一个 execution model 和 Lead，派单 checkpoint 与当前源码一致，workspace/session locator 可恢复。
+- [ ] delegated execution 的授权矩阵逐项覆盖 local changes、commit、push、PR、merge、deploy、migration 和生产动作；未授权动作不会执行。
+- [ ] 外部候选交付的附件 hash、修改范围和事实声明可由 Lead 独立核对。
 - [ ] 验证命令/环境可用。
+- [ ] 可静默失效的关键门禁定义了受控反向验证；普通测试不为形式追加破坏性检查。
 - [ ] Deep Ticket 的批准点已满足。
 
 ## 失效分类
@@ -18,3 +22,5 @@
 - **ticket-invalid**：范围、接口、依赖、验证或路径契约失效；停止并修 Ticket。
 - **spec-invalid**：外部行为/合同需改变；停止并修 Spec。
 - **adr-conflict**：架构决策冲突；停止并处理 ADR。
+- **checkpoint-drift**：派单基线、源码包或当前代码已经漂移；暂停并由 Lead 重放、重派或建立新 checkpoint。
+- **delivery-unverified**：候选交付、provider 声明或附件无法独立核对；保持 `unverified`，不得推进 `done`。

package/template/workflows/specdev/INDEX.md

@@ -46,6 +46,9 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
 
 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
@@ -80,12 +83,14 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
 - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
@@ -112,6 +117,7 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
 - `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
 - `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 
 ## 启动协议
 
@@ -143,7 +149,8 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 
 - change：`active | blocked | completed | archived`
 - Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
-- Investigation：`open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`
+- Investigation status：`open | closed`
+- Investigation resolution：`answered | out-of-scope | superseded | cancelled | null`
 - Planning Depth：`lite | standard | deep`
 - Worktree：`planned | active | review | integrated | removed | blocked`
 
@@ -165,15 +172,15 @@ Archive          归档历史并将经验证知识提升为当前长期知识
 - **A-archive-and-consolidate** — 归档与沉淀：双模式沉淀 Work——归档已验证完成的 change 并提升其知识，或在没有可归档 change 时以当前代码为基本事实深度访谈用户，把经验证的架构决策与领域术语提升为永久知识。
 - **D-diagnose-bugs** — 诊断 Bug：通过复现、反馈回路、可证伪假设与最小插桩定位根因，输出修复契约而不是猜测性补丁。
 - **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
-- **G-grill-with-docs** — 设计访谈（带文档）：通过一次一问的设计访谈打磨方案，同时持续维护设计日志、领域上下文和架构决策。
+- **G-grill-with-docs** — 设计访谈（带文档）：以完整 frontier 逐轮推进设计树，直到每个决策分支都已关闭并获得用户共识，同时持续维护设计树、日志、领域上下文和架构决策。
 - **I-implement** — 实现：基于 Ready Ticket 或获批的小型 Spec 执行设计检查、TDD 红绿循环、持续验证、双轴审查、证据回写和提交。
 - **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、追踪约定、领域知识布局、验证命令和并发治理。
 - **P-goal-plan** — 目标规划：在协调复杂度需要时，将 Ready Spec、Tickets、架构决策与外部约束综合为决策完备的跨 Ticket 编排计划。
-- **R-review-architecture** — 架构审查：扫描与目标相关的代码区域，识别浅模块、接缝泄漏和局部性问题，以可视化报告呈现候选方案，并通过逐项访谈转化为可执行决策。
+- **R-review-architecture** — 架构审查：从用户指定范围或 Git 热点扫描代码库的深化机会，以持久化可视化 HTML 呈现候选，并对用户选择的一个方案运行设计树访谈。
 - **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
 - **T-tickets** — 拆分 Tickets：将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。
 - **T-triage** — 请求分诊：完整摄入外部请求，判断问题类型、影响、风险、缺失信息和下一 work，不在分诊阶段过早设计或实现。
-- **W-wayfinder** — 寻路：为路径未知、跨域或超出单次上下文的工作建立共享调查地图，通过可领取的研究与决策 Ticket 关闭未知项并收敛到可执行路线。
+- **W-wayfinder** — 寻路：为超出单次会话且路径尚不可见的工作建立本地共享地图，逐个解决 research、prototype、grilling 或 task Ticket，直到目的地路线决策完备。
 
 <!-- AUTO-INDEX-END -->