@namewta/speculo 0.3.0 → 0.3.2

package/template/canonical/canonical-specdev-wayfinder.md

@@ -1,198 +1,768 @@
 # 寻路
 
-> **配套上传建议**：本能力跨引用「设计访谈（带文档）」的访谈协议与领域建模规程。若在网页 AI 平台使用，建议同时上传 `canonical-specdev-grill-with-docs.md`。仓库：https://github.com/NAMEWTA/Speculo
+## 网页平台运行约定
 
-一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到**目标**的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此 work 在变更目录中绘制路径作为一张**共享地图**，然后逐个处理其 tickets，直到路径变得清晰。
+本文是可独立上传的单文件能力快照，不依赖 Speculo CLI 的根别名或源目录。执行时统一采用以下逻辑布局：
 
-目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。
+- 项目根下的 `specdev/` 是状态区；全局配置与状态分别为 `specdev/config.json` 和 `specdev/status.json`。
+- 当前 change 位于 `specdev/changes/{change}/`，其中 `{change}` 使用 `YYYY-MM-DD-<kebab-topic>`。
+- 当前 change 的设计、规划和证据工件都写入该目录；永久 ADR、领域上下文和研究分别写入 `specdev/adr/`、`specdev/context/` 和 `specdev/research/`。
+- `specdev/config.json` 或 `specdev/status.json` 不存在时，分别按下方 `<config-template>` 和 `<status-template>` 标签创建；新建 change 时按下方 `<change-status-template>` 标签创建 `.status.json`。对应 schema 用于结构核对。
+- 项目代码与测试始终使用项目根相对路径；不写机器绝对路径。工件之间使用上述逻辑路径，不使用 Speculo 的运行时路径标签。
+- 如果网页平台不能直接写项目文件，则按目标文件名输出完整内容，并在答复中明确应保存的位置；不得把“无法写文件”伪装成已经持久化。
+- 若本地项目提供 Speculo Node 校验器，可运行它补充结构校验；纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对，并明确记录未运行的自动校验。
+- 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
 
-## 规划，而非执行
+Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它保留共享地图、多会话领取、研究型 Ticket 和决策型 Ticket 的能力，但禁止把产品实现伪装成调查。
 
-Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其「说明」章节覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+## 产物
 
-## 用名称引用
+- 共享地图：`specdev/changes/{change}/wayfinder-map.md`
+- 调查 Ticket 目录：`specdev/changes/{change}/investigation/`
+- 单个调查 Ticket：`specdev/changes/{change}/investigation/{investigation-id}.md`
+- 调查 Evidence：`specdev/changes/{change}/investigation/evidence/`
+- 全局领取状态：`specdev/status.json` 中当前 change 的 `claimed_investigations`
 
-每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的「已做出的决策」 —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
+模板：
 
-在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的「已做出的决策」中以 `- [ticket 标题] —— 答案概括` 形式索引。
+- 下方 `<investigation-ticket-template>` 标签
+- 下方 `<wayfinder-map-template>` 标签
 
-## 地图
+## 何时运行
 
-地图是变更目录下的单个 markdown 文件 map.md，是规范的产物。其 tickets 是地图内的 task list items（`- [ ]` 格式）。如果工作范围跨多个变更，地图位于主变更目录下。
+- 路径未知，无法安全写出 Ready Spec 或 Ticket；
+- 需要跨多个领域、技术栈或外部系统调查；
+- 调查量超出单个上下文，适合并行研究；
+- 存在多个相互依赖的高影响未知项；
+- 需要在若干候选方案中先获得事实证据再做决定。
 
-地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
+若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。
 
-**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞、领取与前沿的定义见下方「Tickets」节。
+## 流程
 
-### 地图正文
+### 1. 定义目标与未知项
 
-整个地图的低分辨率视图，每个会话加载一次。开放的 tickets **不**在此处列出 —— 它们直接作为地图文件中的未勾选小节存在。
+写明最终目标、已知边界、当前不能决定的事项和“为什么这些未知项阻塞规划”。未知项分为：
 
-```markdown
-# 地图：<工作名称>
+- **research**：答案可由代码、文档、实验或外部来源证实；
+- **decision**：事实已足够，但需要用户或架构 owner 做取舍；
+- **validation**：已有方案，需要实验验证关键可行性或风险；
+- **mapping**：需要建立调用链、数据流、依赖图或影响面。
 
-## 目的地
+低影响实现细节不创建调查 Ticket。
 
-<到达此地图终点时的样子 —— 此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 ticket 之前以其为定位。>
+### 2. 建立共享地图
 
-## 说明
+使用 下方 `<wayfinder-map-template>` 标签 写入 `specdev/changes/{change}/wayfinder-map.md`：
 
-<领域；每个会话应咨询的技能；此工作的常设偏好>
+- 每个 Ticket 只关闭一个高影响未知项；
+- 写明依赖、owner、领取状态、停止条件和结果消费方；
+- 构建调查 DAG，避免多个调查重复回答同一问题；
+- 标记可并行调查和必须串行的决策点；
+- 定义整体停止条件，不以“所有可能问题都研究完”为目标。
 
-## 已做出的决策
+### 3. 领取与并行
 
-<!-- 索引 —— 每个已关闭 ticket 一行：足以判断相关性，然后跳转到对应小节查看详细信息 -->
+调查者开始前原子地更新 `specdev/status.json` 的 `claimed_investigations`：
 
-- [<已关闭 ticket 标题>](#ticket-标题) —— <答案的一句话概括>
+- 未领取且依赖满足 → 设置 owner、session 和 claimed 时间；
+- 已领取 → 跳过并选择其他可用 Ticket；
+- 超过配置的 claim 超时且无进展 → 允许在记录原因后回收；
+- 完成或释放后从领取集合移除，并同步共享地图。
 
-## 尚未明确
+并行调查使用独立上下文；不要复制所有调查历史，只读取共享地图、当前调查 Ticket、相关上游工件和必要代码事实。
 
-<!-- 参见"战争迷雾"：范围内但你尚无法做成 ticket 的迷雾；随着前沿推进而升级 -->
+### 4. 执行调查
 
-## 超出范围
+调查默认只读。允许：
 
-<!-- 参见"超出范围"：被裁定在目标之外的工作；已关闭，永不升级 -->
-```
+- 代码搜索与静态分析；
+- 文档、规范和官方来源研究；
+- 可撤销的临时实验、最小原型或插桩；
+- 性能测量、调用点扫描、schema 对比或兼容性验证。
 
-### Tickets
+外部研究使用 下方 `<research>` 标签。
 
-每个 ticket 是地图文件内的一个小节，其正文是问题，大小适配一个 100K token 的 agent 会话。Tickets 按创建顺序编号。
+禁止：
 
-```markdown
-## <编号>. <Ticket 标题>  `[<类型>]` `[<HITL|AFK>]`
+- 顺手实现产品功能；
+- 提交未经审查的实验代码；
+- 将原型视为最终架构；
+- 在没有证据时把建议写成事实；
+- 无停止条件地持续研究。
 
-**类型：** <research | prototype | grilling | task>
+### 5. 记录结果与影响
 
-**交互模式：** <HITL | AFK> —— <简要说明为何是此模式>
+每个调查结果区分：
 
-**状态：** < - [ ] 开放 | - [x] 已解决 >
+- 官方或规范事实；
+- 当前代码事实；
+- 实验结果；
+- 推断；
+- 建议；
+- 用户或 owner 决策。
 
-**被阻塞于：** <阻塞此 ticket 的 ticket 标题列表，或"无 —— 可立即开始">
+写明来源、版本、置信度、适用范围、反例、仍未知项和对以下工件的影响：
 
-### 问题
+- `specdev/changes/{change}/spec.md`；
+- `specdev/changes/{change}/ADR.md`；
+- `specdev/changes/{change}/ticket/NN-<ticket-name>.md`；
+- `specdev/changes/{change}/diagnosis.md`。
 
-<此 ticket 要解决的决策或调查>
+调查完成、阻塞或释放时，同步调查 Ticket、调查 Evidence、共享地图和领取状态，并返回 investigation ID、状态及三份工件的完整路径。
 
-### 答案
+状态使用 `open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`。
 
-<!-- 解决时填写 —— 答案的完整记录。以下仅在 ticket 已解决时出现：-->
+### 6. 收敛与退出
 
-<解决此 ticket 时记录的内容。对于 research：发现的摘要和链接资产。对于 prototype：原型的描述和链接。对于 grilling：访谈达成的共识。对于 task：已完成的工作和结果性事实。>
-```
+当剩余未知项不再阻止目标、行为、架构、风险或验证决策时停止。根据结果进入：
 
-每个 ticket 携带一个类型标签 —— 以下之一：`research`、`prototype`、`grilling`、`task`（参见下方 [Ticket 类型](#ticket-类型)）。
+- 需要产品或架构取舍 → “设计访谈能力”；
+- 外部行为已清楚 → “编写 Spec 阶段”；
+- Spec 已 Ready 且只是实现拆分未知 → “拆分 Tickets 阶段”；
+- Bug 根因路径已收敛 → “Bug 诊断阶段”；
+- 仍存在高影响未知项 → 保持 blocked，并明确下一调查或用户决策。
 
-**领取机制：** 一个会话通过将其名称追加到 `specdev/status.json` 的当前 change 的 `active` 条目中的 `claimed_tickets` 数组来**领取**一个 ticket，在开始任何工作**之前**领取，以便并发会话跳过它。该记录*就是*领取标记：一个开放、未被领取的 ticket 是未被领取的。
+长期有效且经实现验证的研究，只有在归档时由 “归档与沉淀阶段” 提升。
 
-**阻塞关系：** 使用 ticket 标题在"被阻塞于"字段中声明依赖。这很关键，因为它使前沿在地图文件中*可视化*呈现 —— 人类无需额外工具就能看到哪些可以开始。当一个 ticket 的所有阻塞 tickets 都已勾选（已解决）时，该 ticket 是**未被阻塞的**；**前沿**是开放（未勾选）、未被阻塞、未被领取的 tickets —— 即已知的边界。
+## 完成标准
 
-**答案：** 不是正文的一部分 —— 它在解决时写入 ticket 的"答案"小节（参见[遍历地图](#遍历地图)）。解决 ticket 时创建的资产从 ticket 小节链接，而非粘贴进去。如果资产是文件，放置在变更目录下，从 ticket 链接。
+- 共享地图、调查 Ticket 和领取状态一致；
+- 每个调查只关闭一个高影响未知项；
+- 结论区分事实、实验、推断、建议和决定；
+- 来源、版本、置信度和停止条件可追踪；
+- 并行调查没有重复领取或互相覆盖；
+- 调查状态及 Ticket、Evidence、共享地图路径已返回；
+- 没有把产品实现藏在调查中；
+- 已明确下一 work 或阻塞决策。
 
-## Ticket 类型
+## 子文件引用
+
+- 调查 Ticket 模板：下方 `<investigation-ticket-template>` 标签
+- 共享地图模板：下方 `<wayfinder-map-template>` 标签
 
-每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
+---
 
-- **Research**（AFK）：调用 common/research skill 启动后台 Agent 针对一手来源调查问题，在 ticket 的答案中链接研究产出文件。当需要当前工作目录之外的知识时使用。
-- **Prototype**（HITL）：调用 common/prototype skill 制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
-- **Grilling**（HITL）：通过设计访谈（G-grill-with-docs）的访谈协议逐个问题进行对话。同时使用其领域建模规程维护领域模型。默认情况 —— 当不确定类型时选此。
-- **Task**（HITL 或 AFK）：在*决策*能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个*执行*而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。
+## 参考内容
 
-## 战争迷雾
+以下内容均已内联。主流程提到标签时，直接使用对应标签中的完整规则、模板或 schema。
 
-地图是*刻意*不完整的：不要绘制你还看不到的内容。在活跃的 tickets 之外是**战争迷雾** —— 你能感觉到即将到来但尚无法确定的决策和调查的模糊视野，因为它们依赖于尚未解决的问题。解决一个 ticket 会清除它前方的迷雾，将任何现在可以明确的内容升级为新的 tickets —— 逐个进行，直到通往目标的路径清晰且没有剩余 tickets。
+<investigation-ticket-template>
 
-地图的**尚未明确**章节记录这些模糊视野：待定的问题、后续重新审视的区域。它是朝向目标*方向*的未发现前沿 —— 此处的所有内容都在范围内，只是不够清晰以做成 ticket。根据视野允许的范围，尽可能松散或完整地书写；它同时也是协作者阅读工作方向的路标。
+## 产物 YAML 头部
 
-**迷雾还是 ticket？** 判断标准是你是否现在就能精确地陈述问题 —— 而不是你现在是否能回答它。
+生成该工件时，将以下字段写在文档开头的 YAML frontmatter 中：
 
-- **做成 ticket 当** 问题已经清晰 —— 即使它被阻塞，你尚不能行动。你能写出明确的"问题"段落。
-- **尚未明确当** 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。
+```yaml
+artifact: investigation-ticket
+id: INV-01
+type: research
+status: open
+blocked_by: []
+owner: unassigned
+claimed_by: null
+claimed_at: null
+```
 
-**尚未明确**排除已决策的内容（「已做出的决策」）、已有的活跃 ticket 以及超出范围的内容（下一节）。
+# Investigation INV-01: <问题>
 
-## 超出范围
+- **调查文件：** `specdev/changes/{change}/investigation/INV-01-<name>.md`
+- **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
+- **Evidence：** `specdev/changes/{change}/investigation/evidence/INV-01.md`
 
-迷雾只会向目标方向*聚集*。目标确定了范围，因此目标之外的工作是**超出范围**的 —— 它不是迷雾，也不属于**尚未明确**。它在地图上拥有自己的**超出范围**章节：你已自觉排除在*此*工作之外的工作。是范围而非清晰度让它落入此处。
+## 1. 决策用途
 
-超出范围的工作永不升级 —— 前沿停在目标处 —— 因此只有在目标被重新划定后才会重新考虑，且以一个全新的工作而非恢复旧工作的形式出现。
+- 要回答或决定什么：
+- 为什么阻塞规划：
+- 结果由哪个工件消费：
 
-将某物裁定为超出范围是一个范围界定行为，而非路径上的一步。当已有的一个 ticket 被发现位于目标之外 —— 绘制地图时范围划分错误，或因某个解决方案而暴露 —— **关闭它**（勾选 checkbox），并在**超出范围**章节留下一行：概括加上为何超出范围，链接已关闭的 ticket。它不会出现在**已做出的决策**中，该节记录实际走过的路径 —— 范围边界不是路径上的一步。
+## 2. 已知事实与假设
 
-## 调用方式
+### 已知事实
 
-两种模式。无论哪种，**每个会话绝不解决超过一个 ticket。**
+### 待验证假设
 
-### 绘制地图
+## 3. 调查契约
 
-用户带着模糊的想法调用。
+- **允许的代码探索：** `project/relative/path/**`
+- **允许的实验：**
+- **禁止的产品实现：**
+- **来源优先级：**
+- **停止条件：**
+- **时间或资源边界：**
 
-1. **命名目标。** 运行一次设计访谈（G-grill-with-docs）会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。使用其访谈协议进行访谈，使用其领域建模规程维护领域模型。
+## 4. 结果
 
-   **完成标准**：目标已命名，范围边界已确定。
+- **状态：** confirmed / disproved / decision-needed / unresolved / superseded
+- **结论：**
+- **证据：**
+- **置信度：** high / medium / low
+- **适用范围与版本：**
+- **反例或限制：**
+- **对 Spec 的影响：** 无 / `specdev/changes/{change}/spec.md`
+- **对 ADR 的影响：** 无 / `specdev/changes/{change}/ADR.md`
+- **对 Ticket 的影响：** 无 / `specdev/changes/{change}/ticket/NN-<ticket-name>.md`
+- **下一步：**
 
-2. **绘制前沿。** 再次质询，这次**广度优先**：在整个空间上扩展而非深入任何一条线索，揭示开放的决策和现在可以迈出的第一步。如果此过程没有浮现任何迷雾 —— 通往目标的路径已经清晰，整个旅程足够小到放入一个会话 —— 你不需要地图。停下来询问用户他们希望如何继续。
+</investigation-ticket-template>
 
-   **完成标准**：前沿的开放决策和第一步已浮现；迷雾部分已识别并草拟。
+<wayfinder-map-template>
 
-3. **创建地图**：写入变更目录下的 map.md，填写「目的地」和「说明」，「已做出的决策」为空，迷雾草拟进**尚未明确**。
+## 产物 YAML 头部
 
-   **完成标准**：地图文件已创建，目的地、说明、尚未明确、超出范围均已填写。
+生成该工件时，将以下字段写在文档开头的 YAML frontmatter 中：
 
-4. **创建你现在能明确的 tickets** 作为地图文件内的小节 —— 然后在**第二遍**中连接阻塞边（tickets 需要首先有标题才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
+```yaml
+artifact: wayfinder-map
+change: <YYYY-MM-DD-topic>
+status: active
+```
 
-   **完成标准**：所有可明确的 tickets 已创建并连接阻塞边；迷雾已归入尚未明确。
+# Wayfinder Map: <目标>
 
-5. **停止** —— 绘制地图是一个会话的工作；不要同时解决 tickets。
+- **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
+- **调查目录：** `specdev/changes/{change}/investigation/`
+- **领取状态：** `specdev/status.json`
 
-### 遍历地图
+## 1. 最终目标与当前边界
 
-用户带着一张地图（变更目录或 map.md 路径）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
+## 2. 调查清单
 
-1. **加载地图** —— 低分辨率视图（目的地、说明、已做出的决策、尚未明确、超出范围），而非每个 ticket 的完整正文。
+| ID | Type | 问题 | 为什么高影响 | Blocked By | Owner/Claim | 状态 | Result |
+|---|---|---|---|---|---|---|---|
+| INV-01 | research | ... | ... | — | unassigned | open | `specdev/changes/{change}/investigation/INV-01-<name>.md` |
 
-   **完成标准**：地图的低分辨率视图已加载，当前状态已理解。
+## 3. 调查 DAG
 
-2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。**领取它**（规则见上方「Tickets」节）。
+```text
+INV-01
+  ├─→ INV-02
+  └─→ INV-03
+```
 
-   **完成标准**：一个前沿 ticket 已被选中并领取。
+## 4. 并行与领取规则
 
-3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用「说明」中指定的技能。根据 ticket 类型选择解决方式：**research** 调用 common/research skill；**grilling** 使用设计访谈（G-grill-with-docs）；**prototype** 调用 common/prototype skill；**task** 按问题描述执行。查阅设计访谈的领域建模规程维护领域模型。
+- 最大并发来自 `specdev/config.json`。
+- 当前领取集合以 `specdev/status.json` 为权威。
+- 同一调查 Ticket 只能有一个 owner/session。
+- 共享地图是状态投影，领取变更后必须同步。
 
-   **完成标准**：ticket 的问题已解决，答案已记录。
+## 5. 决策收敛
 
-4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的「已做出的决策」中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `claimed_tickets` 中移除该 ticket（规则见上方「Tickets」节）。
+| 未知项 | 当前结论 | 置信度 | 消费工件 | 是否仍阻塞 |
+|---|---|---|---|---|
 
-   **完成标准**：ticket checkbox 已勾选，「已做出的决策」已更新，领取标记已清除。
+## 6. 停止条件
 
-5. **添加新浮现的 tickets** 作为地图文件内新的小节（先创建再连接阻塞边）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets（勾选并注明无效原因）。
+- [ ] 所有高影响未知项已 confirmed、disproved，或明确转为用户/owner 决策。
+- [ ] 可以形成 Ready Spec、Ticket、诊断契约或架构决策。
+- [ ] 没有把产品实现留在调查 Ticket 中。
+- [ ] 所有 claim 已释放或转为明确 blocked。
 
-   **完成标准**：新浮现的 tickets 已添加，迷雾已升级或清除，超出范围的 tickets 已裁定。
+</wayfinder-map-template>
 
-用户可以并行运行未被阻塞的 tickets，因此需预期其他会话会并发编辑地图文件和 status.json。
+<research>
 
-### 完成
+# SpecDev Research
 
-当所有 tickets 已关闭（勾选）、迷雾已清空（尚未明确为空或仅剩无法继续分解的模糊项）、且通往目标的路径已清晰时，地图完成。向用户汇报：
+## 触发
 
-- 目的地是否已可抵达——路径上的每个步骤是否都已有明确的 ticket 或决策
-- 「已做出的决策」中的关键结论摘要
-- 剩余的任何**尚未明确**项——它们是否阻碍行动，还是可作为实现细节处理
-- 建议的下一步行动（移交实现、开始执行、或重新划定目标）
+当外部 API、库版本、协议、法规、产品能力或最佳实践会改变设计/实现决策，且当前材料不足时使用。
 
-**完成标准**：前沿已清空——无开放 tickets、无残留迷雾、通往目标的路径清晰。完成汇报已向用户呈现。
+## 流程
 
----
+1. 写清楚要支持的具体决策和停止条件。
+2. 优先官方文档、规范、源代码、论文或维护者材料；技术问题优先一手来源。
+3. 核对版本、发布日期、适用环境和已知限制。
+4. 区分：来源明确事实、代码库事实、推断、建议。
+5. 对关键结论至少交叉验证；来源冲突时并列呈现，不强行调和。
+6. 记录摘要、证据、置信度、对 ADR/Spec/Ticket 的影响和仍未知项。
+7. 长期有效且经实现验证后才可由 Archive 提升到永久 research。
 
-## 子文件引用
+## 输出模板
 
-本入口为单文件 work，所有内容均已内联。以下引用供 work 内各阶段加载（跨 workflow，不内联——建议配套上传设计访谈 canonical 文档）：
+```markdown
+# Research: <问题>
+- 决策用途：
+- 范围/版本：
+- 停止条件：
+
+## Findings
+### R-001
+- 结论：
+- 类型：官方事实 / 代码事实 / 推断 / 建议
+- 来源：
+- 置信度：high / medium / low
+- 适用限制：
+- 对工件影响：
+
+## Conflicts and Unknowns
+## Recommendation
+```
 
-| 文件 | 触发条件 |
-|------|----------|
-| 设计访谈（G-grill-with-docs）主入口 | 需要访谈以命名目标或解决 grilling 类型 ticket |
-| 设计访谈的访谈协议（grilling-protocol） | 进入具体访谈——一次一问，决策树遍历 |
-| 设计访谈的领域建模规程（domain-modeling-rules） | 维护领域模型——术语精炼、决策记录 |
-| 变更目录下的 map.md | 地图持久化文件 |
+不得长篇复制受版权保护的来源；使用短引文和自己的准确摘要。
+
+</research>
+
+<config-template>
+
+```json
+{
+  "schema_version": 3,
+  "interaction_language": "zh-CN",
+  "artifact_language": "zh-CN",
+  "git": {
+    "auto_commit": false,
+    "default_branch": null,
+    "worktree_for_parallel": true
+  },
+  "execution": {
+    "max_parallel": 3,
+    "deep_ticket_human_approval": true,
+    "shared_path_owner": "lead"
+  },
+  "verification": {
+    "test": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null
+  },
+  "planning": {
+    "default_depth": "standard",
+    "require_ready_gate": true,
+    "require_evidence": true
+  }
+}
+```
+
+</config-template>
+
+<config-schema>
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:config:v3",
+  "title": "SpecDev Configuration",
+  "type": "object",
+  "required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
+  "properties": {
+    "schema_version": {"const": 3},
+    "interaction_language": {"type": "string", "minLength": 1},
+    "artifact_language": {"type": "string", "minLength": 1},
+    "git": {
+      "type": "object",
+      "required": ["auto_commit", "default_branch", "worktree_for_parallel"],
+      "properties": {
+        "auto_commit": {"type": "boolean"},
+        "default_branch": {"type": ["string", "null"]},
+        "worktree_for_parallel": {"type": "boolean"}
+      },
+      "additionalProperties": true
+    },
+    "execution": {
+      "type": "object",
+      "required": ["max_parallel", "deep_ticket_human_approval", "shared_path_owner"],
+      "properties": {
+        "max_parallel": {"type": "integer", "minimum": 1},
+        "deep_ticket_human_approval": {"type": "boolean"},
+        "shared_path_owner": {"type": "string", "minLength": 1}
+      },
+      "additionalProperties": true
+    },
+    "verification": {
+      "type": "object",
+      "required": ["test", "typecheck", "lint", "build"],
+      "properties": {
+        "test": {"type": ["string", "null"]},
+        "typecheck": {"type": ["string", "null"]},
+        "lint": {"type": ["string", "null"]},
+        "build": {"type": ["string", "null"]}
+      },
+      "additionalProperties": true
+    },
+    "planning": {
+      "type": "object",
+      "required": ["default_depth", "require_ready_gate", "require_evidence"],
+      "properties": {
+        "default_depth": {"enum": ["lite", "standard", "deep"]},
+        "require_ready_gate": {"type": "boolean"},
+        "require_evidence": {"type": "boolean"}
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}
+```
+
+</config-schema>
+
+<status-template>
+
+```json
+{
+  "schema_version": 3,
+  "workflow": "specdev",
+  "active": [],
+  "work_history": [],
+  "completed": []
+}
+```
+
+</status-template>
+
+<status-schema>
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:status:v3",
+  "title": "SpecDev Global Status",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "workflow",
+    "active",
+    "work_history",
+    "completed"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 3
+    },
+    "workflow": {
+      "const": "specdev"
+    },
+    "active": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "current_work",
+          "works_run",
+          "result"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "current_work": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "works_run": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "result": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "claimed_investigations": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "id",
+                "owner",
+                "claimed_at"
+              ],
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "owner": {
+                  "type": "string"
+                },
+                "session": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "claimed_at": {
+                  "type": "string"
+                }
+              },
+              "additionalProperties": true
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "work_history": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "work_id",
+          "started_at",
+          "completed_at",
+          "result"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "work_id": {
+            "type": "string",
+            "pattern": "^specdev/"
+          },
+          "started_at": {
+            "type": "string"
+          },
+          "completed_at": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "result": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "completed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "change",
+          "archived_at",
+          "archive_path"
+        ],
+        "properties": {
+          "change": {
+            "type": "string"
+          },
+          "archived_at": {
+            "type": "string"
+          },
+          "archive_path": {
+            "type": "string",
+            "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}
+```
+
+</status-schema>
+
+<change-status-template>
+
+```json
+{
+  "schema_version": 3,
+  "artifact": "change-status",
+  "change": "<YYYY-MM-DD-topic>",
+  "change_status": "active",
+  "current_work": null,
+  "created_at": "<ISO-8601>",
+  "updated_at": "<ISO-8601>",
+  "completed_at": null,
+  "archived": false,
+  "archive_path": null,
+  "blockers": [],
+  "deviations": [],
+  "worktrees": []
+}
+```
+
+</change-status-template>
+
+<change-status-schema>
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:change-status:v3",
+  "title": "SpecDev Change Status",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "change_status",
+    "current_work",
+    "created_at",
+    "updated_at",
+    "completed_at",
+    "archived",
+    "archive_path",
+    "blockers",
+    "deviations"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": 3
+    },
+    "artifact": {
+      "const": "change-status"
+    },
+    "change": {
+      "type": "string",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
+    },
+    "change_status": {
+      "enum": [
+        "active",
+        "blocked",
+        "completed",
+        "archived"
+      ]
+    },
+    "current_work": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "created_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "updated_at": {
+      "type": "string",
+      "minLength": 1
+    },
+    "completed_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "archived": {
+      "type": "boolean"
+    },
+    "archive_path": {
+      "anyOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "string",
+          "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
+        }
+      ]
+    },
+    "blockers": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "deviations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "worktrees": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "ticket_id",
+          "owner",
+          "provider",
+          "base_sha",
+          "branch",
+          "workspace_ref",
+          "status",
+          "updated_at"
+        ],
+        "properties": {
+          "ticket_id": {
+            "type": "string",
+            "pattern": "^T-[0-9]{2,}$"
+          },
+          "owner": {
+            "type": "string",
+            "minLength": 1
+          },
+          "provider": {
+            "enum": [
+              "native",
+              "git",
+              "external"
+            ]
+          },
+          "base_sha": {
+            "type": "string",
+            "minLength": 1
+          },
+          "branch": {
+            "type": "string",
+            "minLength": 1
+          },
+          "workspace_ref": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+          },
+          "status": {
+            "enum": [
+              "planned",
+              "active",
+              "review",
+              "integrated",
+              "removed",
+              "blocked"
+            ]
+          },
+          "updated_at": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "change_status": {
+            "const": "archived"
+          }
+        }
+      },
+      "then": {
+        "properties": {
+          "archived": {
+            "const": true
+          },
+          "archive_path": {
+            "type": "string",
+            "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
+          }
+        }
+      }
+    }
+  ],
+  "additionalProperties": true
+}
+```
 
-状态追踪：
-- `specdev/status.json` —— `active` 条目中的 `claimed_tickets` 数组记录当前领取的 ticket
+</change-status-schema>