@namewta/speculo 0.4.0 → 0.5.0

package/template/skills/docs-sync/references/agents/agent-writing.md

@@ -0,0 +1,75 @@
+# Agent 文档写作
+
+任何由 agent 消费的文档的撰写参考——一份 skill、一个 `AGENTS.md` / `CLAUDE.md`、一份通过指针到达的文档。包装形式不同，撰写之道相同：同样的杠杆让每一份文档都可预测——agent 每次都走相同的*流程*，而不是产出相同的输出。
+
+## 上下文指针
+
+**上下文指针（context pointer）** 是 agent 上下文中持有的一条引用，它指明某份上下文之外的资料，并编码了到达它的条件。一份 skill 的 description 是指针；`AGENTS.md` 中一行指向某文档的引用，也是同一个东西。决定 agent 何时——以及多可靠地——到达该资料的，是指针的*措辞*，而不是它的目标。一个措辞薄弱的指针指向一份必读资料，就是一个变异 bug：先打磨措辞；只有打磨失败时，才把资料内联进来。
+
+指针承担两项工作——说明资料是什么，并列出应触发到达它的**分支**（branch 是文档处理的某个不同情况，因此不同运行会走不同的路径）。一个始终加载的指针，每个字都要在每一轮对话中付出成本，所以它比正文更需要被毫不留情地精简：
+
+- **前置引导词**——触发工作是在指针上完成的。
+- **每个分支一个触发器。** 只是给同一分支换了个说法的同义词，等于把同一个分支写了两遍；把它们合并，只保留真正不同的分支。
+- **删掉正文已经承载的身份信息。**
+
+## 两种负载
+
+你添加的每份文档和每个指针，都要花掉两种预算之一：
+
+- **上下文负载（context load）**——始终加载的资料对 agent 窗口的代价：`AGENTS.md` 里的一行、一份 skill 描述、任何每轮对话都待在上下文里的东西，无论是否触发，都在消耗 token 和注意力。
+- **认知负载（cognitive load）**——对人类的代价：存在哪些文档、何时该去取哪一份。人类就是索引。这不是需要最小化的成本——它是人类主动性的价格；在人类判断重要的地方花它，在无关紧要的地方拿掉它。
+
+只通过指针到达的资料，免去了上下文负载，代价是指针自身的那一行；完全没有指针的资料，则完全压在认知负载上。
+
+## 信息层级
+
+一份文档由两种内容类型构成——**步骤**（agent 执行的有序操作）和**参考**（按需查阅的定义、规则、事实）——两者自由混合：全是步骤（一份菜谱）、全是参考（一次 review 的规则、本技能），或两者兼有。核心决策是每一块内容在**信息层级**上所处的位置，这是一把按 agent 需要资料的即时程度排序的梯子：
+
+1. **文件内步骤**——第一层级：agent 做什么，按顺序。
+2. **文件内参考**——按需查阅。它常常是一个合理扁平的并列集合（一次 review 的全部规则在同一条横档上）——这没什么不好，不是坏味道。
+3. **外置参考（disclosed reference）**——推到独立文件里，通过上下文指针到达，只在指针触发时加载。从同一文件夹的兄弟文件，一直到住在任何地方、任何文档都能指向的完全外部参考。
+
+推得太少，顶层会臃肿；推得太多，你会把 agent 真正需要的资料藏起来。这个张力就是全部决策所在。
+
+**渐进式披露（progressive disclosure）** 是沿梯子向下的移动——从主文件中移出、放到指针后面——让顶层保持可读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：每个分支都要用到的内容内联保留，只有部分分支会碰到的内容推到指针后面。当一份文档有步骤时，本应披露的文件内参考会埋没这些步骤，让"照做"变成抛硬币——这不只是可读性杠杆，而是变异杠杆。
+
+**就近放置（co-location）** 是文件内部的伴侣：梯子决定一块内容*下探多深*，就近放置决定它落到那里后*旁边放着什么*。把一个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样读到一部分时，相邻部分也随之而来。判断标准：文档读起来应该像专门写给 agent 的文档——归组的内容如此，散落的内容则不然。（它与重复不同：重复是在两个地方重述同一层含义；散落是把一层含义打碎到多处。）
+
+**臃肿（sprawl）** 是这里的失败模式：一份文档单纯地太长，即使每一行都是活的、独一无二的。注意力在过剩内容中变薄，而每一行额外的内容都是又多一条需要保持相关的东西。解药就是那把梯子：把参考披露到指针后面，并按分支或序列拆分，让每条路径只携带它需要的东西。
+
+## 步骤与完成标准
+
+每个步骤都以一个**完成标准（completion criterion）** 收尾——告诉 agent 工作已完成的条件。两个属性使它成为杠杆：
+
+- **清晰度**——agent 能否区分"完成"与"未完成"？一个模糊的边界（"已达成理解"）会招致**提前完成（premature completion）**：在步骤真正完成之前就结束它，注意力滑向*看起来完成了*。仍可见的后续步骤——**完成后的步骤（post-completion steps）**——提供拉力；标准的清晰度是阻力。按顺序防御：**先磨利边界**（局部且廉价）；只有当边界不可约地模糊*且*你观察到赶工行为时，才通过拆分序列隐藏后续步骤——而隐藏只在真正的上下文边界处有效（一次交接或一个 subagent 派遣；内联调用会让后续步骤留在上下文中，什么也清不掉）。
+- **要求强度（demand）**——它要求多少。"每个修改过的模型都被说明"逼出彻底的工作，而"生成一份变更清单"不会。要求强度驱动**苦功（legwork）**——agent 在工作内部做的挖掘，它藏在措辞里而不是写成独立步骤——并且它不绑定步骤："每条规则都适用"绑定一整个扁平的参考集合，正如"每个步骤都完成"绑定一条序列，这正是一份纯参考文档仍然带着穷尽性门槛的方式。
+
+最强的标准既可核查又穷尽。
+
+## 何时拆分
+
+把一份文档拆成两份，要花掉两种负载之一，所以只有在切口值得时才拆：
+
+- **按序列拆分**——拆分一段步骤序列，此时完成后的步骤会诱使 agent 赶工眼前的步骤。让它们不可见，会驱动当前任务上更多的苦功。当心反向情况：合并序列会让每个步骤都暴露在后续步骤面前，招致提前完成。
+
+## 引导词
+
+**引导词（leading word）** 是一个早已存在于模型预训练中的紧凑概念，agent 在运行文档时用它思考（_lesson_、_fog of war_、_tracer bullets_）。以 token 形式重复、永不用句子重述，它累积出一个分布式的定义，并以最少的 token 锚定一整个行为区域——通过征用模型已有的先验。自己造词也行，只要定义清楚，但一个生造的词征用不到任何先验——你在定义 token 上付出的，正是预训练词免费给予的；先用已有的词。
+
+它双重锚定。在正文里是*执行*：每次该词出现，agent 都伸手取同样的行为；在扁平参考内部，它把注意力聚焦到要找的一类事物上。在指针里是*调用*：当同一个词同时存在于你的 prompts、你的文档和你的代码库时，agent 会把这份共享语言与资料联系起来，更可靠地到达它。
+
+寻找用引导词重构的机会。一个在三个地方展开的三件套、一个花一句话指向同一个概念的指针——每一处都是渴望塌缩成单个 token 的段落：
+
+- "fast, deterministic, low-overhead" → _tight_（一个 _tight_ 循环）。
+- "a loop you believe in" → _red_——一个模糊的闸门变成二元的可观察状态（遇到 bug 循环变 _red_，或不变）。
+
+你赢两次：更少的 token，以及一个更锋利的钩子让 agent 挂上它的思考。假设每份文档都携带着引导词可以退役的重述——去把它们找出来。
+
+**否定式表述（negation）** 是这个杠杆旁边的失败模式：用禁止来引导，会把被禁止的行为拖进上下文，让它变得*更容易*被激活，而不是更难。_不要想大象_，然后脑子里就全是大象；否定是一个脆弱的修饰符，会被强激活的概念碾过去，于是禁令有一半读起来像是在指示去做那件事。用**肯定式**提示——陈述目标行为（"写一行注释"），让被禁止的行为永远不被说出来。只有当你实在无法用肯定句式表达时，一条禁令才配占有一席之地；即使如此，也要配上肯定的目标，让注意力落在"做什么"上。
+
+## 精简
+
+- 让每个含义都有**单一事实来源（single source of truth）**：一个权威的位置，这样改变行为就是改一处。**重复（duplication）**——同一含义出现在多个地方——耗费维护成本和 token，并把一个含义在梯子上的显著性抬到超过它实际等级的高度。（它是引导词的意外反面：引导词是有意重复一个 token，从来不是重复含义。）
+- **环境（environment）** 也是事实来源——`package.json` 脚本、配置文件、目录布局、`--help` 输出——而重述环境的文档就是一份**缓存（cache）**：一次查询的副本，只有当查询本身昂贵时才值得负担这份负载。只缓存 agent 无法通过查找得到的东西：不成文的约定、选择背后的原因、任何配置文件都不会招认的坑。把"一个文件一条命令"式的查找留给环境，在那里它们不会过期。
+- 逐行检查**相关性（relevance）**：它是否仍然与文档所做的事有关？一行内容失去相关性，要么因为从未作用于任务（纯叙述，或一个本应披露的分支），要么因为行为或世界变化而过期。更短的文档更容易保持相关。没有精简纪律，默认的归宿是**沉积（sediment）**：一层层过期的内容沉淀下来——因为添加感觉安全、删除感觉冒险——直到你必须钻穿它们才能找到仍然活着的东西。
+- 逐句猎杀**无效指令（no-ops）**：一句模型本来就默认遵守的指令，花了负载却没说出任何东西。判断标准——它是否改变了相对默认的行为？——是模型相对的，不是读者相对的：两个人争论一句无效指令，争论的是默认是什么，而且要靠运行文档来裁决，不是靠辩论。当一句指令不合格时，删除整句，而不是从里面删词。这个判断标准也给引导词打分：一个弱到打不过默认的词（在 agent 已经够"be thorough"的地方写*要彻底*）就是无效指令，修法是换一个更强的词（*毫不留情*），而不是换一种技巧。

package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/claude-redirect.md

@@ -10,7 +10,7 @@
 Speculo agent handbook: see [AGENTS.md](./AGENTS.md).
 ```
 
-此格式与 `../../docs-sync/references/agents-contract.md` 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是入口指针。
+此格式与 [`../agents-contract.md`](../agents-contract.md) 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是入口指针。
 
 ## 设计缘由
 

package/template/skills/docs-sync/references/agents-contract.md

@@ -1,6 +1,28 @@
 # AI 代理手册同步契约
 
-本契约用于差量维护已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。创建或重建多层手册树时调用 `../../agents-md-builder/SKILL.md`，不要在 docs-sync 中复制其扫描和模板逻辑。
+本契约用于差量维护或重建已确认范围内的 `AGENTS.md`、`CLAUDE.md` 和工具专属入口。调用方传入 `handbook_mode=incremental|rebuild`；默认使用 `incremental`，仅在用户显式要求、手册缺失或 manifest 拓扑变化时进入 `rebuild`。
+
+## 分支路由
+
+### Incremental
+
+读取当前手册、Git 输入区间和直接事实源，逐段执行下方内容优先级、生命周期和验证规则。不重新分类未受影响目录，也不加载重建模板。
+
+**完成标准**：所有被 Git 区间或当前事实命中的手册均已整份审计，未命中手册保持不变。
+
+### Rebuild
+
+按顺序读取：
+
+1. `agents/manifest-discovery.md`，发现 manifest、忽略目录、父子树和孤立手册；
+2. `agents/role-classification.md`，为每个目录判定唯一角色；
+3. `agents/evidence-collection.md`，为每个输出结论收集真实文件证据；
+4. `agents/content-contract.md`、`agents/writing-style.md` 和对应 `agents/templates/*`，自底向上生成 AGENTS.md；
+5. `agents/claude-redirect.md`，生成或修复同层 CLAUDE.md。
+
+展示创建、更新和删除候选；整文件删除或把多行 CLAUDE.md 改成重定向前取得明确确认。
+
+**完成标准**：扫描范围内每个合法目录恰好一个 AGENTS.md，每个 AGENTS.md 有唯一 CLAUDE.md 重定向，父子 routing 完整，所有处置均有证据和确认状态。
 
 ## 内容优先级
 

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`。