@namewta/speculo 0.3.4 → 0.5.0

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

@@ -13,191 +13,120 @@
 - 若本地项目提供 Speculo Node 校验器，可运行它补充结构校验；纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对，并明确记录未运行的自动校验。
 - 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
 
-Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它先命名**目标**，再把通往目标的路线绘制成一张**共享地图**——由一组可领取的调查 Ticket 组成，逐个关闭高影响未知项，直到路线清晰。地图刻意保持不完整：看得清的决策落成 Ticket，看不清的留在**战争迷雾**里，随每次调查完成而逐步散去。
+一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
 
-## 两条核心纪律
+目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
 
-- **规划而非执行**：本 work 产出的是**决策**，不是交付物。当你产生“顺手把它实现掉”的冲动时，通常意味着你已经走到了地图边缘——那是交接给实现 work 的信号，而不是继续动手的理由。用户可在地图笔记中显式授权把执行纳入地图，否则一律只产出决策。
-- **以名称指代**：共享地图和每个调查 Ticket 都是有标题的实体。凡是人会读到的叙述，一律用**名称**指代（如“调查：登录态跨域刷新策略”），而不是裸编号（`INV-03`）或裸路径。ID 与路径作为链接附在名称里，不单独充当称呼。一屏 `INV-03、INV-04、INV-05` 无法阅读。
+## 核心纪律
 
-## 产物
+### 规划，而非执行
 
-- 共享地图：`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`
+Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
 
-模板：
+### 用名称引用
 
-- 下方 `<investigation-ticket-template>` 标签
-- 下方 `<wayfinder-map-template>` 标签
-
-## 何时运行
-
-- 路径未知，无法安全写出 Ready Spec 或 Ticket；
-- 需要跨多个领域、技术栈或外部系统调查；
-- 调查量超出单个上下文，适合并行研究；
-- 存在多个相互依赖的高影响未知项；
-- 需要在若干候选方案中先获得事实证据再做决定。
-
-若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。若在命名目标、绘制前沿后发现根本没有迷雾——所有决策都已清楚——则不需要地图，停下并直接告知用户下一步。
-
-## 两种调用模式
-
-Wayfinder 有两种入口，可分次进行：
-
-- **绘制地图**：用户带来一个粗略想法。命名目标 → 广度优先勾勒前沿 → 建立共享地图（写好目标与笔记，已定决策留空，迷雾写入“尚未指定”）→ 创建当前可明确表述的调查 Ticket 并二次连边补齐阻塞关系 → 并行触发 research 型 AFK 调查 → 停止。绘制本身不解决任何未知项。
-- **走完地图**：用户带来一张已存在的地图（可选带指定 Ticket）。加载低分辨率地图 → 选取并领取一个前沿 Ticket → 解决它 → 记录结论、释放领取、关闭 Ticket → 浮现新 Ticket、让已可表述的迷雾毕业、把越界工作移入范围之外。
-
-## 流程
-
-### 1. 命名目标与勾勒边界
-
-命名目标是第一动作，它塑造每一个后续 Ticket。写明：
-
-- **最终目标**：一到两行描述“终点长什么样”。
-- **已知边界**：当前确定的前提、约束与不变量。
-- **当前不能决定的事项**：以及“为什么这些未知项阻塞规划”。
-
-高影响未知项按**调查目的**分为四类：
-
-- **research**：答案可由代码、文档、实验或外部来源证实；
-- **decision**：事实已足够，但需要用户或架构 owner 做取舍；
-- **validation**：已有方案，需要实验验证关键可行性或风险；
-- **mapping**：需要建立调用链、数据流、依赖图或影响面。
-
-每个调查 Ticket 还需标注**执行模式**：
+每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
 
-- **AFK**（agent-only）：可由子代理独立完成，无需人类在环，典型是 research 与 mapping。
-- **HITL**（human-in-the-loop）：必须通过与用户的实时交流才能解决，代理不得替用户作答；典型是 decision，以及需要用户对原型或方案取舍反馈的 validation。
+### 每会话一个 Ticket
 
-低影响实现细节不创建调查 Ticket，记录为实现者可自行决定。
+无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 Ticket。
 
-### 2. 战争迷雾与前沿
+## 产物与适配
 
-地图**刻意不完整**——不去绘制你还看不见的东西。
+- 地图：`specdev/changes/{change}/wayfinder-map.md`
+- 子 Tickets：`specdev/changes/{change}/investigation/`
+- solution comments：`specdev/changes/{change}/investigation/comments/`
+- assignment registry：`specdev/status.json` 的 `claimed_investigations`
 
-- **前沿**：地图上当前 `open`、依赖已满足（unblocked）、且尚未被领取（unclaimed）的调查 Ticket 集合。走完地图时只从前沿取 Ticket。
-- **战争迷雾**：范围内、你已隐约感到会出现、但此刻还无法精确表述的决策。它们写入共享地图的“尚未指定”区，不切成 Ticket。
-- **毕业判据**：能否**此刻精确陈述这个问题**（而非能否此刻回答它）。问题已经足够锐利就立 Ticket（即使仍被阻塞）；还说不清就留在迷雾里。不要预先把迷雾切成 Ticket 大小的碎片。
+每次绘制或遍历前加载 下方 `<local-tracker-contract>` 标签。Ticket 和地图模板：
 
-每解决一个 Ticket 都会驱散前方迷雾，让新可表述的问题从“尚未指定”毕业为新 Ticket。
-
-### 3. 建立共享地图
-
-使用 下方 `<wayfinder-map-template>` 标签 写入 `specdev/changes/{change}/wayfinder-map.md`。地图是**索引而非仓库**：每个决策只在一处存放（对应调查 Ticket 或 Evidence），地图只给出一行摘要并链接到详情。地图包含：
-
-- **目标**：终点，一到两行。
-- **笔记**：领域、需参考的 skills、固定偏好，以及是否显式授权把执行纳入地图。
-- **调查清单**：当前所有已表述 Ticket 的索引表（含 ID、类型、执行模式、问题、依赖、领取状态、结果指针），前沿由此表投影。
-- **调查 DAG**：阻塞关系图，避免多个调查重复回答同一问题；标记可并行与必须串行的决策点。
-- **已定决策**：每关闭一个 Ticket 追加一行结论，作为“实际走过的路线”索引。
-- **尚未指定**：范围内、尚不可表述为 Ticket 的迷雾。
-- **范围之外**：见第 4 节。
-- **停止条件**：整体收敛判据，不以“所有可能问题都研究完”为目标。
-
-每个 Ticket 只关闭一个高影响未知项。
-
-### 4. 范围之外
-
-迷雾只朝目标方向聚集，目标一旦确定就固定了范围，因此超出目标的工作是**范围之外**，不是迷雾。它单独成节，列出被有意识排除的工作，写清摘要与理由。
-
-- 范围之外**永不毕业**回地图；只有在目标被重画时，作为新的 change 重新纳入。
-- 当一个已存在的 Ticket 被发现落在目标之外时，关闭它并在“范围之外”留一行摘要与原因，**不写入“已定决策”**——已定决策只记录实际走过的路线。
-
-### 5. 领取与并行
+- 下方 `<investigation-ticket-template>` 标签
+- 下方 `<wayfinder-map-template>` 标签
+- 下方 `<solution-comment-template>` 标签
 
-调查者开始前原子地更新 `specdev/status.json` 的 `claimed_investigations`（领取即“认领”，先领取再动手）：
+## Ticket 类型
 
-- 未领取且依赖满足（属于前沿）→ 设置 owner、session 和 claimed 时间；
-- 已领取 → 跳过并选择其他前沿 Ticket；
-- 超过配置的 claim 超时且无进展 → 允许在记录原因后回收；
-- 完成或释放后从领取集合移除，并同步共享地图。
+每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
-并行是有约束的：
+- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 下方 `<research>` 标签。当需要当前工作目录之外的知识时使用。
+- **Prototype（HITL）**：制作廉价、粗糙、具体的产物提高讨论保真度——大纲、粗略尝试、桩代码或 UI/逻辑原型。将原型链接为资产；当“它应是什么样”或“怎样表现”是关键问题时使用。
+- **Grilling（HITL）**：对话。调用 “设计访谈能力” 的 grilling 与 domain-modeling 能力，但本会话只关闭当前 Wayfinder Ticket。
+- **Task（HITL 或 AFK）**：在决策做出前必须完成的手动工作。它通过为决策解除阻塞赢得位置，不以交付目的地为目标。Agent 能独立驱动时使用 AFK，否则给人类精确清单。
 
-- **research / AFK 型调查可并行领取**，因为它们只读取事实、彼此独立，且不推进产品决策。并行调查使用独立上下文，只读取共享地图、当前调查 Ticket、相关上游工件和必要代码事实，不复制全部调查历史。
-- **decision 及其他 HITL 型 Ticket，单个会话一次只解决一个**。这类 Ticket 会实质改变方案走向、开启新的迷雾，逐个解决才能让地图稳定地生长；一次塞多个决策会污染前沿。因此除 research 型外，**同一会话不要在一轮里解决多个 HITL 型 Ticket**。
-- 用户可能在其他会话并行推进未阻塞的 Ticket，要预期对地图和领取状态的并发编辑，写回前先重读。
+Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:grilling | wayfinder:task`。
 
-### 6. 执行调查
+## 战争迷雾与范围
 
-调查默认只读。允许：
+地图刻意不完整：不要绘制还看不到的内容。活跃 Tickets 之外是**战争迷雾**——能感觉即将到来、但依赖尚未解决问题而无法精确陈述的决策和调查。
 
-- 代码搜索与静态分析；
-- 文档、规范和官方来源研究；
-- 可撤销的临时实验、最小原型或插桩（原型用于让用户对“看起来/表现如何”作出反应，是手段不是最终架构）；
-- 性能测量、调用点扫描、schema 对比或兼容性验证。
+**迷雾还是 Ticket？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
 
-外部研究使用 下方 `<research>` 标签。
+- 问题已经清晰时做成 Ticket，即使仍被阻塞；
+- 还无法精确表述时留在“尚未明确”，不预先切成 Ticket 大小碎片。
 
-禁止：
+目的地固定范围。目标之外的工作进入**超出范围**，不是战争迷雾。范围之外永不升级；只有重新命名目的地并创建新 change 时才重新考虑。越界 Ticket 关闭为 `out-of-scope`，链接进“超出范围”，不进入“已做出的决策”。
 
-- 顺手实现产品功能（想动手 = 到了地图边缘，交接而非继续）；
-- 提交未经审查的实验代码；
-- 将原型视为最终架构；
-- 在没有证据时把建议写成事实；
-- 代 HITL 型 Ticket 的用户作答；
-- 无停止条件地持续研究。
+## 调用模式
 
-### 7. 记录结果与影响
+### 绘制地图
 
-每个调查结果区分：
+用户带着模糊想法调用：
 
-- 官方或规范事实；
-- 当前代码事实；
-- 实验结果；
-- 推断；
-- 建议；
-- 用户或 owner 决策。
+1. **命名目的地。** 运行一轮 G 的 grilling/domain-modeling，确定正在寻路的 Spec、决策或变更。
+2. **绘制前沿。** 再次质询，这次广度优先，在整个空间展开而非深入一条线索。如果没有浮现任何迷雾，停下并询问用户如何继续，不创建地图。
+3. **创建地图。** 使用模板填写目的地和说明；“已做出的决策”为空，迷雾写入“尚未明确”。
+4. **创建现在可明确的 Tickets。** 先创建全部 Ticket，再第二遍连接 `blocked_by`，因为 ID 必须先存在。
+5. **派出 research Agent。** 每个 research Ticket 使用独立上下文和 claim，各自只解决一个 Ticket；需要 Git 分支时先取得对应授权。
+6. 停止。绘制地图是一个会话的工作，它不亲手解决任何 Ticket。
 
-写明来源、版本、置信度、适用范围、反例、仍未知项和对以下工件的影响：
+**完成标准**：目的地、地图、当前可表述 Tickets、阻塞边和战争迷雾已持久化；绘图会话没有关闭 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：
 
-1. 同步调查 Ticket、调查 Evidence、领取状态；
-2. 在共享地图的“已定决策”追加一行结论索引（越界的则移入“范围之外”）；
-3. 让新可表述的迷雾从“尚未指定”毕业为新 Ticket，并二次连边补齐阻塞关系；作废或被替代的 Ticket 及时更新或删除；
-4. 返回 investigation 名称、状态及三份工件（调查 Ticket、Evidence、共享地图）的完整路径。
+1. 加载地图的低分辨率视图，不加载每个 Ticket 正文。
+2. 用户指定 Ticket 时使用它；否则按本地 tracker contract 查询并选择第一个 frontier Ticket。
+3. 在任何工作前领取 Ticket。已领取时跳过并选择其他 frontier。
+4. 按需缩放：只读取当前 Ticket、相关或已关闭 Ticket 的详情，以及“说明”指定的能力。
+5. 解决当前唯一 Ticket，使用下一个未占用编号写 solution comment，原子关闭 Ticket 并释放 claim。
+6. 在地图“已做出的决策”追加名称链接和一句概括；越界则写入“超出范围”。
+7. 创建新浮现的 Tickets，第二遍连接阻塞；从“尚未明确”删除每个已升级补丁；更新或关闭被答案判定无效的 Tickets。
 
-状态使用 `open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`。
+写回前重读地图、Ticket 与 claims，预期其他会话并发编辑。
 
-### 8. 收敛与退出
+**完成标准**：本会话只关闭一个 Ticket；Ticket、solution comment、claim、地图和新 frontier 一致。
 
-当剩余未知项不再阻止目标、行为、架构、风险或验证决策时停止。根据结果进入：
+## 收敛与路由
 
-- 需要产品或架构取舍 → “设计访谈能力”；
-- 外部行为已清楚 → “编写 Spec 阶段”；
-- Spec 已 Ready 且只是实现拆分未知 → “拆分 Tickets 阶段”；
-- Bug 根因路径已收敛 → “Bug 诊断阶段”；
-- 仍存在高影响未知项 → 保持 blocked，并明确下一调查或用户决策。
+当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
 
-长期有效且经实现验证的研究，只有在归档时由 “归档与沉淀阶段” 提升。
+- 需要产品或架构取舍：“设计访谈能力”；
+- 外部行为已清楚：“编写 Spec 阶段”；
+- Spec Ready、只需拆分：“拆分 Tickets 阶段”；
+- Bug 根因路线收敛：“Bug 诊断阶段”；
+- 仍有高影响未知项：保持 active/blocked 并返回下一 frontier Ticket 名称。
 
 ## 完成标准
 
-- 目标已命名，并塑造了地图上的每个 Ticket；
-- 共享地图、调查 Ticket 和领取状态一致；
-- 地图作为索引，每个决策只在一处存放；
-- 每个调查只关闭一个高影响未知项；
-- 结论区分事实、实验、推断、建议和决定；
-- 来源、版本、置信度和停止条件可追踪；
-- 前沿、战争迷雾与范围之外划分清晰，迷雾按“能否精确表述”毕业；
-- 并行调查没有重复领取或互相覆盖，且未在一轮里解决多个 HITL 型 Ticket；
-- 调查状态及 Ticket、Evidence、共享地图路径已按名称返回；
-- 没有把产品实现藏在调查中；
-- 已明确下一 work 或阻塞决策。
+- 目的地塑造每个 Ticket 并固定范围；
+- 地图是低分辨率索引，不列开放 Tickets，不复制答案详情；
+- 四类 Ticket 与 HITL/AFK 语义正确；
+- frontier 由 open、unblocked、unclaimed 事实查询；
+- 名称用于人类叙述，裸 ID 只作内部标识；
+- 战争迷雾、Ticket 与超出范围按可精确表述性和范围区分；
+- 每会话最多解决一个 Ticket，HITL 用户没有被 Agent 代答；
+- 每个关闭 Ticket 有 solution comment，资产通过链接引用；
+- claim、阻塞、地图与 Ticket 状态一致；
+- 路径清晰时返回下一 work，不把产品实现藏进寻路。
 
 ## 子文件引用
 
-- 调查 Ticket 模板：下方 `<investigation-ticket-template>` 标签
-- 共享地图模板：下方 `<wayfinder-map-template>` 标签
+- 本地 Tracker：下方 `<local-tracker-contract>` 标签
+- Ticket 模板：下方 `<investigation-ticket-template>` 标签
+- Solution comment：下方 `<solution-comment-template>` 标签
+- 地图模板：下方 `<wayfinder-map-template>` 标签
+- Ticket schema：下方 `<wayfinder-ticket-schema>` 标签
 
 ---
 
@@ -212,66 +141,21 @@ Wayfinder 有两种入口，可分次进行：
 生成该工件时，将以下字段写在文档开头的 YAML frontmatter 中：
 
 ```yaml
-artifact: investigation-ticket
+artifact: wayfinder-ticket
 id: INV-01
-name: <简短问题名称，供人按名称指代>
-type: research
-mode: AFK
+name: <精确问题名称>
+parent_map: specdev/changes/{change}/wayfinder-map.md
+label: wayfinder:grilling
 status: open
 blocked_by: []
-owner: unassigned
-claimed_by: null
-claimed_at: null
+resolution: null
 ```
 
-# 调查：<问题名称>
-
-> 本 Ticket 只关闭**一个**高影响未知项，产出的是决策而非交付物。想“顺手实现”时即到了地图边缘，交接而非动手。
-
-- **调查文件：** `specdev/changes/{change}/investigation/INV-01-<name>.md`
-- **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
-- **Evidence：** `specdev/changes/{change}/investigation/evidence/INV-01.md`
-
-## 0. 分类
-
-- **Type：** research / decision / validation / mapping
-- **模式：** AFK（子代理独立完成）/ HITL（须与用户实时交流，代理不代答）
-
-## 1. 决策用途
-
-- 要回答或决定什么（一个精确问题）：
-- 为什么阻塞规划：
-- 结果由哪个工件消费：
+# <精确问题名称>
 
-## 2. 已知事实与假设
+## 问题
 
-### 已知事实
-
-### 待验证假设
-
-## 3. 调查契约
-
-- **允许的代码探索：** `project/relative/path/**`
-- **允许的实验 / 原型：**（原型仅供用户反应，不作最终架构）
-- **禁止的产品实现：**
-- **来源优先级：**
-- **停止条件：**
-- **时间或资源边界：**
-
-## 4. 结果
-
-- **状态：** confirmed / disproved / decision-needed / unresolved / superseded / cancelled
-- **结论：**
-- **证据：**
-- **置信度：** high / medium / low
-- **适用范围与版本：**
-- **反例或限制：**
-- **对 Spec 的影响：** 无 / `specdev/changes/{change}/spec.md`
-- **对 ADR 的影响：** 无 / `specdev/changes/{change}/ADR.md`
-- **对 Ticket 的影响：** 无 / `specdev/changes/{change}/ticket/NN-<ticket-name>.md`
-- **浮现的新迷雾 / 新 Ticket：**
-- **是否越界（移入范围之外）：** 否 / 是（理由：）
-- **下一步：**
+<此 Ticket 要解决的一个决策、调查或解除阻塞工作。>
 
 </investigation-ticket-template>
 
@@ -287,84 +171,97 @@ change: <YYYY-MM-DD-topic>
 status: active
 ```
 
-# Wayfinder Map: <目标名称>
+# Wayfinder Map: <地图名称>
 
-> 本地图是**索引而非仓库**：每个决策只在一处存放，地图只给一行摘要并链接到详情。凡是人会读到的叙述，用**名称**指代 Ticket，不用裸编号。
+## 目的地
 
-- **共享地图：** `specdev/changes/{change}/wayfinder-map.md`
-- **调查目录：** `specdev/changes/{change}/investigation/`
-- **领取状态：** `specdev/status.json`
+<到达此地图终点时的样子——此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 Ticket 之前以其为定位。>
 
-## 1. 目标
+## 说明
 
-<终点长什么样，一到两行。目标是第一动作，塑造每一个 Ticket，并固定范围。>
+<领域；每个会话应咨询的 skills；此工作的常设偏好；是否明确把执行带入地图。>
 
-## 2. 笔记
+## 已做出的决策
 
-- **领域：**
-- **需参考的 skills：**
-- **固定偏好 / 约束：**
-- **执行授权：** 默认只产出决策不产出交付物；如需把执行纳入地图，在此显式写明。
+<!-- 索引——每个已关闭 Ticket 一行：足以判断相关性，然后放大链接查看 solution comment 持有的详细信息。开放 Tickets 通过本地 tracker 查询，不列在这里。 -->
 
-## 3. 调查清单（前沿由此表投影）
+- **<已关闭 Ticket 标题>：** `specdev/changes/{change}/investigation/comments/INV-01/01-solution.md` —— <答案的一句话概括>
 
-> 前沿 = `open` + 依赖已满足（unblocked）+ 尚未领取（unclaimed）的行。走完地图时只从前沿取 Ticket。
+## 尚未明确
 
-| 名称 | ID | Type | 模式 | 问题 | Blocked By | Owner/Claim | 状态 | Result |
-|---|---|---|---|---|---|---|---|---|
-| 示例：登录态跨域刷新策略 | INV-01 | research | AFK | ... | — | unassigned | open | `specdev/changes/{change}/investigation/INV-01-<name>.md` |
+<!-- 范围内但尚无法精确表述为 Ticket 的战争迷雾；随着前沿推进而升级。 -->
 
-- Type：research（可证实）/ decision（需取舍）/ validation（需实验验证）/ mapping（建立调用链/影响面）。
-- 模式：AFK（子代理独立完成，典型 research/mapping）/ HITL（须与用户实时交流，代理不代答，典型 decision）。
+## 超出范围
 
-## 4. 调查 DAG
+<!-- 被裁定在目的地之外的工作；已关闭，永不升级。 -->
 
-```text
-INV-01
-  ├─→ INV-02
-  └─→ INV-03
-```
+</wayfinder-map-template>
+
+<local-tracker-contract>
 
-- 标记可并行调查与必须串行的决策点，避免多个调查重复回答同一问题。
+# Wayfinder 本地 Tracker 适配
 
-## 5. 并行与领取规则
+最新版 Wayfinder 以 issue tracker 为物理载体。SpecDev 的默认 tracker 是 change state 内的本地 Markdown/JSON；本文件只映射物理原语，不改写 Wayfinder 的地图、Ticket、战争迷雾或遍历语义。
 
-- 最大并发来自 `specdev/config.json`。
-- 当前领取集合以 `specdev/status.json` 为权威。
-- 同一调查 Ticket 只能有一个 owner/session。
-- **research / AFK 型可并行领取**；**decision 及其他 HITL 型，单会话一次只解决一个**（research 除外），逐个解决让地图稳定生长。
-- 共享地图是状态投影，领取变更后必须同步；写回前先重读，预期并发编辑。
+| Tracker 原语 | 本地实现 |
+|---|---|
+| 地图 issue | `specdev/changes/{change}/wayfinder-map.md` |
+| 子 issue | `specdev/changes/{change}/investigation/{investigation-id}.md` |
+| label | Ticket frontmatter 的 `wayfinder:research|prototype|grilling|task` |
+| 阻塞关系 | Ticket frontmatter 的 `blocked_by` |
+| assignment | `specdev/status.json` 当前 change 的 `claimed_investigations` |
+| solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` |
+| 关闭 issue | Ticket frontmatter 的 `status: closed` 与 `resolution` |
 
-## 6. 已定决策（实际走过的路线）
+## 查询前沿
 
-> 每关闭一个 Ticket 追加一行结论索引。越界工作不写这里，移入“范围之外”。
+扫描当前地图的全部子 Ticket。一个 Ticket 同时满足以下条件时属于**前沿**：
 
-| 名称 | 结论（一行） | 置信度 | 消费工件 | 详情指针 |
-|---|---|---|---|---|
+1. `status: open`；
+2. `blocked_by` 中的每个 Ticket 都是 `status: closed`；
+3. `claimed_investigations` 中没有相同 `id`。
 
-## 7. 尚未指定（战争迷雾）
+按文件名中的数字 ID 升序返回。地图正文不缓存开放 Ticket 列表；每次选择前沿都从 Ticket 与 claim 事实重新查询。
 
-> 范围内、已隐约感到会出现、但此刻还无法**精确表述**的决策。看得清就毕业成第 3 节的 Ticket，看不清就留在这里。不要预先切成 Ticket 大小的碎片。
+## 原子领取
 
-- ...
+开始任何工作前，重读全局状态并原子写入 `id`、`owner`、可选 `session` 和 `claimed_at`。已领取则选择下一前沿 Ticket。写回结果前再次重读；完成、释放或取消时删除 claim。
 
-## 8. 范围之外
+Ticket 文件不重复保存 assignee，地图不重复保存 claim。全局 assignment registry 是领取的单一事实源。
 
-> 超出目标的工作。永不毕业回地图；目标被重画时作为新 change 处理。已存在 Ticket 若被发现越界，关闭后在此留一行摘要与理由。
+## 解决方案评论
 
-| 被排除的工作 | 理由 |
-|---|---|
+Ticket 正文只保存问题。答案写入下一个未占用的 solution comment 文件，资产从评论链接，不粘贴进 Ticket。关闭 Ticket 后，地图的“已做出的决策”只追加名称链接和一句概括；`out-of-scope` 不进入决策索引。
 
-## 9. 停止条件
+**完成标准**：地图、Ticket、claim、阻塞和 solution comment 可以重建相同前沿；同一事实没有第二份可写副本。
 
-- [ ] 目标已命名，并塑造了地图上的每个 Ticket。
-- [ ] 所有高影响未知项已 confirmed、disproved，或明确转为用户/owner 决策。
-- [ ] 战争迷雾中不再有阻塞目标、且已可精确表述却未立 Ticket 的问题。
-- [ ] 可以形成 Ready Spec、Ticket、诊断契约或架构决策。
-- [ ] 没有把产品实现留在调查 Ticket 中。
-- [ ] 所有 claim 已释放或转为明确 blocked。
+</local-tracker-contract>
 
-</wayfinder-map-template>
+<solution-comment-template>
+
+## 产物 YAML 头部
+
+生成该工件时，将以下字段写在文档开头的 YAML frontmatter 中：
+
+```yaml
+artifact: wayfinder-solution-comment
+ticket: INV-01
+sequence: 1
+resolution: answered
+```
+
+# Solution: <Ticket 名称>
+
+- **Ticket：** `specdev/changes/{change}/investigation/INV-01.md`
+- **答案：** <此 Ticket 关闭的决定或已完成的解除阻塞工作>
+- **事实与来源：**
+- **资产：** 无 / `project/relative/path` / `<Url>https://example.com</Url>`
+- **后续 Ticket 所依赖的事实：** 无 / ...
+- **新浮现的 Tickets：** 无 / <按名称列出>
+- **升级的战争迷雾：** 无 / ...
+- **对现有 Tickets 的影响：** 无 / update / close / supersede
+
+</solution-comment-template>
 
 <research>
 
@@ -871,3 +768,28 @@ INV-01
 ```
 
 </change-status-schema>
+
+<wayfinder-ticket-schema>
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:wayfinder-ticket:v1",
+  "title": "SpecDev Wayfinder Ticket Frontmatter",
+  "type": "object",
+  "required": ["artifact", "id", "name", "parent_map", "label", "status", "blocked_by", "resolution"],
+  "properties": {
+    "artifact": { "const": "wayfinder-ticket" },
+    "id": { "type": "string", "pattern": "^INV-[0-9]{2,}$" },
+    "name": { "type": "string", "minLength": 1 },
+    "parent_map": { "type": "string", "minLength": 1 },
+    "label": { "enum": ["wayfinder:research", "wayfinder:prototype", "wayfinder:grilling", "wayfinder:task"] },
+    "status": { "enum": ["open", "closed"] },
+    "blocked_by": { "type": "array", "items": { "type": "string", "pattern": "^INV-[0-9]{2,}$" } },
+    "resolution": { "enum": [null, "answered", "out-of-scope", "superseded", "cancelled"] }
+  },
+  "additionalProperties": false
+}
+```
+
+</wayfinder-ticket-schema>

package/template/commands/docs-sync.md

@@ -2,7 +2,7 @@
 id: docs-sync
 type: command
 name: Docs Sync
-description: 清洁并提交工作区，以可复现 Git 区间和确认范围同步项目文档与 workflow 知识
+description: 清洁并提交工作区，以可复现 Git 区间和确认范围同步项目文档、Agent 手册与 workflow 知识
 keywords: [docs-sync, readme, changelog, agents, documentation]
 ---
 
@@ -19,8 +19,8 @@ keywords: [docs-sync, readme, changelog, agents, documentation]
 ## 执行
 
 1. 读取 `../skills/docs-sync/SKILL.md`，解析 `speculo/config.json` 与 `speculo/.speculo/workspace.json`（不存在时以默认值静默降级），获取全部已安装 workflow/state 根。
-2. 将 runtime context、报告路径、全局 state 路径与 Git 副作用责任传给 skill，按 skill 流程执行（清理工作区 → 确认范围 → 生命周期审计 → 同步文档 → 验证）。
+2. 将 runtime context、报告路径、全局 state 路径、Git 副作用责任和 `handbook_mode` 传给 skill。`handbook_mode` 默认为 `incremental`；用户明确要求、手册缺失或 manifest 拓扑变化时使用 `rebuild`。
 3. 整文件/目录删除和受保护知识仍逐次确认；skill 返回原子写入内容后，由本命令显式暂存并创建同步或 no-op commit。
 4. 重新读取 Git、state、报告与 sidecar；只有工作区干净、节点可复现且所有文件已提交时完成。
 
-完成标准：报告含输入节点、checkpoint、确认范围、生命周期动作和验证；全局 state 与每个 workflow sidecar 有效；`git status --short` 为空。
+完成标准：报告含输入节点、checkpoint、确认范围、handbook mode、生命周期动作和验证；全局 state 与每个 workflow sidecar 有效；`git status --short` 为空。

package/template/skills/docs-sync/SKILL.md

@@ -2,7 +2,7 @@
 id: docs-sync
 type: skill
 name: Docs Sync
-description: 基于可复现 Git 区间、用户确认范围和 workflow 规则，清洁工作区并全量审计同步项目文档与知识资产。
+description: 文档同步：基于可复现 Git 区间、确认范围和 workflow 规则审计项目文档，并在增量维护或重建分支中生成可预测的 AGENTS.md / CLAUDE.md 手册树。
 ---
 
 # Docs Sync
@@ -16,7 +16,8 @@ description: 基于可复现 Git 区间、用户确认范围和 workflow 规则
 1. 读取 `references/git-state-contract.md`，清理并提交可验证的既有工作区改动，解析上次基线与本次输入节点。完成标准：输入工作区干净，或已无损阻塞。
 2. 读取 `references/workflow-scope-contract.md`，发现全部已安装 workflow，并解析全局范围与每个 workflow 的确认清单。完成标准：首次运行已统一确认范围，每个 workflow 状态根都有合法 sidecar。
 3. 读取 `references/document-lifecycle-contract.md`，把输入区间和 workflow 证据映射为 `add | update | delete | merge | keep | propose-only`。完成标准：每个受影响资产已整份审计，而非只追加新段落。
-4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`。需要创建或重建多层代理手册树时改用 `../agents-md-builder/SKILL.md`。
-5. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
+4. 更新 README 时读取 `references/readme-contract.md`（同步规则）与 `references/readme-writing-guide.md`（内容写作规范）；更新 CHANGELOG 时读取 `references/changelog-contract.md`；更新代理手册时读取 `references/agents-contract.md`，由该契约选择 `incremental` 或 `rebuild` 分支。完成标准：每个命中文档只加载所属分支的规则，未发生分支泄漏。
+5. 生成或修改任何 Agent 消费的手册、入口或上下文指针时，读取 `references/agents/agent-writing.md`，逐项应用上下文指针、信息层级、完成标准、引导词和精简规则。完成标准：每个含义只有一个事实源，每个分支有可到达的指针，逐句通过相关性与无效指令检查。
+6. 验证项目和文档，按 `assets/report-template.md`、`assets/state-template.json` 与 `assets/workflow-scope-template.json` 返回原子写入内容。调用方提交显式文件列表并再次确认工作区干净。
 
 完成标准：项目文档与当前事实一致，过期和重复内容已删除或合并；报告可复现输入区间；state 与 sidecar 已提交；没有未确认的越权写入或遗留工作区改动。

package/template/skills/docs-sync/assets/report-template.md

@@ -1,6 +1,7 @@
 ---
 command: docs-sync
 mode: <bootstrap|incremental|no-op>
+handbook_mode: <incremental|rebuild>
 scope: <workspace|multi-workflow|workflow>
 workflows: []
 changes: []