@namewta/speculo 0.4.0 → 0.5.0

package/template/workflows/specdev/W-wayfinder/W-wayfinder.md

@@ -3,194 +3,123 @@ id: specdev/wayfinder
 type: workflow-entry
 workflow: specdev
 name: 寻路
-description: 为路径未知、跨域或超出单次上下文的工作绘制共享调查地图，用可领取的研究与决策 Ticket 逐步驱散战争迷雾，收敛到可执行路线。
-keywords: [wayfinder, 寻路, 调查, research, decision, shared-map, 战争迷雾, 前沿, 并行, 未知项]
+description: 为超出单次会话且路径尚不可见的工作建立本地共享地图，逐个解决 research、prototype、grilling 或 task Ticket，直到目的地路线决策完备。
+keywords: [wayfinder, 寻路, shared-map, research, prototype, grilling, task, 战争迷雾, 前沿]
 ---
 
 # 寻路
 
-Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它先命名**目标**，再把通往目标的路线绘制成一张**共享地图**——由一组可领取的调查 Ticket 组成，逐个关闭高影响未知项，直到路线清晰。地图刻意保持不完整：看得清的决策落成 Ticket，看不清的留在**战争迷雾**里，随每次调查完成而逐步散去。
+一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
 
-## 两条核心纪律
+目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
 
-- **规划而非执行**：本 work 产出的是**决策**，不是交付物。当你产生“顺手把它实现掉”的冲动时，通常意味着你已经走到了地图边缘——那是交接给实现 work 的信号，而不是继续动手的理由。用户可在地图笔记中显式授权把执行纳入地图，否则一律只产出决策。
-- **以名称指代**：共享地图和每个调查 Ticket 都是有标题的实体。凡是人会读到的叙述，一律用**名称**指代（如“调查：登录态跨域刷新策略”），而不是裸编号（`INV-03`）或裸路径。ID 与路径作为链接附在名称里，不单独充当称呼。一屏 `INV-03、INV-04、INV-05` 无法阅读。
+## 核心纪律
 
-## 产物
+### 规划，而非执行
 
-- 共享地图：`<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- 调查 Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
-- 单个调查 Ticket：`<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>`
-- 调查 Evidence：`<Path>{roots.state}/specdev/changes/{change}/investigation/evidence/</Path>`
-- 全局领取状态：`<Path>{roots.state}/specdev/status.json</Path>` 中当前 change 的 `claimed_investigations`
+Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
 
-模板：
+### 用名称引用
 
-- `<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
-- `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`
-
-## 何时运行
-
-- 路径未知，无法安全写出 Ready Spec 或 Ticket；
-- 需要跨多个领域、技术栈或外部系统调查；
-- 调查量超出单个上下文，适合并行研究；
-- 存在多个相互依赖的高影响未知项；
-- 需要在若干候选方案中先获得事实证据再做决定。
-
-若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。若在命名目标、绘制前沿后发现根本没有迷雾——所有决策都已清楚——则不需要地图，停下并直接告知用户下一步。
-
-## 两种调用模式
-
-Wayfinder 有两种入口，可分次进行：
-
-- **绘制地图**：用户带来一个粗略想法。命名目标 → 广度优先勾勒前沿 → 建立共享地图（写好目标与笔记，已定决策留空，迷雾写入“尚未指定”）→ 创建当前可明确表述的调查 Ticket 并二次连边补齐阻塞关系 → 并行触发 research 型 AFK 调查 → 停止。绘制本身不解决任何未知项。
-- **走完地图**：用户带来一张已存在的地图（可选带指定 Ticket）。加载低分辨率地图 → 选取并领取一个前沿 Ticket → 解决它 → 记录结论、释放领取、关闭 Ticket → 浮现新 Ticket、让已可表述的迷雾毕业、把越界工作移入范围之外。
-
-## 流程
-
-### 1. 命名目标与勾勒边界
-
-命名目标是第一动作，它塑造每一个后续 Ticket。写明：
-
-- **最终目标**：一到两行描述“终点长什么样”。
-- **已知边界**：当前确定的前提、约束与不变量。
-- **当前不能决定的事项**：以及“为什么这些未知项阻塞规划”。
-
-高影响未知项按**调查目的**分为四类：
+每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
 
-- **research**：答案可由代码、文档、实验或外部来源证实；
-- **decision**：事实已足够，但需要用户或架构 owner 做取舍；
-- **validation**：已有方案，需要实验验证关键可行性或风险；
-- **mapping**：需要建立调用链、数据流、依赖图或影响面。
+### 每会话一个 Ticket
 
-每个调查 Ticket 还需标注**执行模式**：
+无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 Ticket。
 
-- **AFK**（agent-only）：可由子代理独立完成，无需人类在环，典型是 research 与 mapping。
-- **HITL**（human-in-the-loop）：必须通过与用户的实时交流才能解决，代理不得替用户作答；典型是 decision，以及需要用户对原型或方案取舍反馈的 validation。
+## 产物与适配
 
-低影响实现细节不创建调查 Ticket，记录为实现者可自行决定。
+- 地图：`<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- 子 Tickets：`<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- solution comments：`<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
+- assignment registry：`<Path>{roots.state}/specdev/status.json</Path>` 的 `claimed_investigations`
 
-### 2. 战争迷雾与前沿
+每次绘制或遍历前加载 `<Path>{roots.workflows}/specdev/W-wayfinder/local-tracker-contract.md</Path>`。Ticket 和地图模板：
 
-地图**刻意不完整**——不去绘制你还看不见的东西。
-
-- **前沿**：地图上当前 `open`、依赖已满足（unblocked）、且尚未被领取（unclaimed）的调查 Ticket 集合。走完地图时只从前沿取 Ticket。
-- **战争迷雾**：范围内、你已隐约感到会出现、但此刻还无法精确表述的决策。它们写入共享地图的“尚未指定”区，不切成 Ticket。
-- **毕业判据**：能否**此刻精确陈述这个问题**（而非能否此刻回答它）。问题已经足够锐利就立 Ticket（即使仍被阻塞）；还说不清就留在迷雾里。不要预先把迷雾切成 Ticket 大小的碎片。
-
-每解决一个 Ticket 都会驱散前方迷雾，让新可表述的问题从“尚未指定”毕业为新 Ticket。
-
-### 3. 建立共享地图
-
-使用 `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`。地图是**索引而非仓库**：每个决策只在一处存放（对应调查 Ticket 或 Evidence），地图只给出一行摘要并链接到详情。地图包含：
-
-- **目标**：终点，一到两行。
-- **笔记**：领域、需参考的 skills、固定偏好，以及是否显式授权把执行纳入地图。
-- **调查清单**：当前所有已表述 Ticket 的索引表（含 ID、类型、执行模式、问题、依赖、领取状态、结果指针），前沿由此表投影。
-- **调查 DAG**：阻塞关系图，避免多个调查重复回答同一问题；标记可并行与必须串行的决策点。
-- **已定决策**：每关闭一个 Ticket 追加一行结论，作为“实际走过的路线”索引。
-- **尚未指定**：范围内、尚不可表述为 Ticket 的迷雾。
-- **范围之外**：见第 4 节。
-- **停止条件**：整体收敛判据，不以“所有可能问题都研究完”为目标。
-
-每个 Ticket 只关闭一个高影响未知项。
-
-### 4. 范围之外
-
-迷雾只朝目标方向聚集，目标一旦确定就固定了范围，因此超出目标的工作是**范围之外**，不是迷雾。它单独成节，列出被有意识排除的工作，写清摘要与理由。
-
-- 范围之外**永不毕业**回地图；只有在目标被重画时，作为新的 change 重新纳入。
-- 当一个已存在的 Ticket 被发现落在目标之外时，关闭它并在“范围之外”留一行摘要与原因，**不写入“已定决策”**——已定决策只记录实际走过的路线。
-
-### 5. 领取与并行
+- `<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/W-wayfinder/solution-comment-template.md</Path>`
 
-调查者开始前原子地更新 `<Path>{roots.state}/specdev/status.json</Path>` 的 `claimed_investigations`（领取即“认领”，先领取再动手）：
+## Ticket 类型
 
-- 未领取且依赖满足（属于前沿）→ 设置 owner、session 和 claimed 时间；
-- 已领取 → 跳过并选择其他前沿 Ticket；
-- 超过配置的 claim 超时且无进展 → 允许在记录原因后回收；
-- 完成或释放后从领取集合移除，并同步共享地图。
+每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
 
-并行是有约束的：
+- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
+- **Prototype（HITL）**：制作廉价、粗糙、具体的产物提高讨论保真度——大纲、粗略尝试、桩代码或 UI/逻辑原型。将原型链接为资产；当“它应是什么样”或“怎样表现”是关键问题时使用。
+- **Grilling（HITL）**：对话。调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 的 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？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
 
-外部研究使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
+- 问题已经清晰时做成 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。
 
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`；
-- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`；
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`；
-- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`。
+### 遍历地图
 
-调查完成、阻塞或释放时：
+用户带来地图，可选指定 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 一致。
 
-当剩余未知项不再阻止目标、行为、架构、风险或验证决策时停止。根据结果进入：
+## 收敛与路由
 
-- 需要产品或架构取舍 → `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
-- 外部行为已清楚 → `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
-- Spec 已 Ready 且只是实现拆分未知 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
-- Bug 根因路径已收敛 → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
-- 仍存在高影响未知项 → 保持 blocked，并明确下一调查或用户决策。
+当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
 
-长期有效且经实现验证的研究，只有在归档时由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 提升。
+- 需要产品或架构取舍：`<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+- 外部行为已清楚：`<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
+- Spec Ready、只需拆分：`<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
+- Bug 根因路线收敛：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
+- 仍有高影响未知项：保持 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 模板：`<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
-- 共享地图模板：`<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`
+- 本地 Tracker：`<Path>{roots.workflows}/specdev/W-wayfinder/local-tracker-contract.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
+- Solution comment：`<Path>{roots.workflows}/specdev/W-wayfinder/solution-comment-template.md</Path>`
+- 地图模板：`<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`
+- Ticket schema：`<Path>{roots.workflows}/specdev/common/schemas/wayfinder-ticket.schema.json</Path>`

package/template/workflows/specdev/W-wayfinder/investigation-ticket-template.md

@@ -1,61 +1,16 @@
 ---
-artifact: investigation-ticket
+artifact: wayfinder-ticket
 id: INV-01
-name: <简短问题名称，供人按名称指代>
-type: research
-mode: AFK
+name: <精确问题名称>
+parent_map: <Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>
+label: wayfinder:grilling
 status: open
 blocked_by: []
-owner: unassigned
-claimed_by: null
-claimed_at: null
+resolution: null
 ---
 
-# 调查：<问题名称>
+# <精确问题名称>
 
-> 本 Ticket 只关闭**一个**高影响未知项，产出的是决策而非交付物。想“顺手实现”时即到了地图边缘，交接而非动手。
+## 问题
 
-- **调查文件：** `<Path>{roots.state}/specdev/changes/{change}/investigation/INV-01-<name>.md</Path>`
-- **共享地图：** `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- **Evidence：** `<Path>{roots.state}/specdev/changes/{change}/investigation/evidence/INV-01.md</Path>`
-
-## 0. 分类
-
-- **Type：** research / decision / validation / mapping
-- **模式：** AFK（子代理独立完成）/ HITL（须与用户实时交流，代理不代答）
-
-## 1. 决策用途
-
-- 要回答或决定什么（一个精确问题）：
-- 为什么阻塞规划：
-- 结果由哪个工件消费：
-
-## 2. 已知事实与假设
-
-### 已知事实
-
-### 待验证假设
-
-## 3. 调查契约
-
-- **允许的代码探索：** `<Path>project/relative/path/**</Path>`
-- **允许的实验 / 原型：**（原型仅供用户反应，不作最终架构）
-- **禁止的产品实现：**
-- **来源优先级：**
-- **停止条件：**
-- **时间或资源边界：**
-
-## 4. 结果
-
-- **状态：** confirmed / disproved / decision-needed / unresolved / superseded / cancelled
-- **结论：**
-- **证据：**
-- **置信度：** high / medium / low
-- **适用范围与版本：**
-- **反例或限制：**
-- **对 Spec 的影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
-- **对 ADR 的影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
-- **对 Ticket 的影响：** 无 / `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`
-- **浮现的新迷雾 / 新 Ticket：**
-- **是否越界（移入范围之外）：** 否 / 是（理由：）
-- **下一步：**
+<此 Ticket 要解决的一个决策、调查或解除阻塞工作。>

package/template/workflows/specdev/W-wayfinder/local-tracker-contract.md

@@ -0,0 +1,36 @@
+# Wayfinder 本地 Tracker 适配
+
+最新版 Wayfinder 以 issue tracker 为物理载体。SpecDev 的默认 tracker 是 change state 内的本地 Markdown/JSON；本文件只映射物理原语，不改写 Wayfinder 的地图、Ticket、战争迷雾或遍历语义。
+
+| Tracker 原语 | 本地实现 |
+|---|---|
+| 地图 issue | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` |
+| 子 issue | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` |
+| label | Ticket frontmatter 的 `wayfinder:research|prototype|grilling|task` |
+| 阻塞关系 | Ticket frontmatter 的 `blocked_by` |
+| assignment | `<Path>{roots.state}/specdev/status.json</Path>` 当前 change 的 `claimed_investigations` |
+| solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` |
+| 关闭 issue | Ticket frontmatter 的 `status: closed` 与 `resolution` |
+
+## 查询前沿
+
+扫描当前地图的全部子 Ticket。一个 Ticket 同时满足以下条件时属于**前沿**：
+
+1. `status: open`；
+2. `blocked_by` 中的每个 Ticket 都是 `status: closed`；
+3. `claimed_investigations` 中没有相同 `id`。
+
+按文件名中的数字 ID 升序返回。地图正文不缓存开放 Ticket 列表；每次选择前沿都从 Ticket 与 claim 事实重新查询。
+
+## 原子领取
+
+开始任何工作前，重读全局状态并原子写入 `id`、`owner`、可选 `session` 和 `claimed_at`。已领取则选择下一前沿 Ticket。写回结果前再次重读；完成、释放或取消时删除 claim。
+
+Ticket 文件不重复保存 assignee，地图不重复保存 claim。全局 assignment registry 是领取的单一事实源。
+
+## 解决方案评论
+
+Ticket 正文只保存问题。答案写入下一个未占用的 solution comment 文件，资产从评论链接，不粘贴进 Ticket。关闭 Ticket 后，地图的“已做出的决策”只追加名称链接和一句概括；`out-of-scope` 不进入决策索引。
+
+**完成标准**：地图、Ticket、claim、阻塞和 solution comment 可以重建相同前沿；同一事实没有第二份可写副本。
+

package/template/workflows/specdev/W-wayfinder/solution-comment-template.md

@@ -0,0 +1,17 @@
+---
+artifact: wayfinder-solution-comment
+ticket: INV-01
+sequence: 1
+resolution: answered
+---
+
+# Solution: <Ticket 名称>
+
+- **Ticket：** `<Path>{roots.state}/specdev/changes/{change}/investigation/INV-01.md</Path>`
+- **答案：** <此 Ticket 关闭的决定或已完成的解除阻塞工作>
+- **事实与来源：**
+- **资产：** 无 / `<Path>project/relative/path</Path>` / `<Url>https://example.com</Url>`
+- **后续 Ticket 所依赖的事实：** 无 / ...
+- **新浮现的 Tickets：** 无 / <按名称列出>
+- **升级的战争迷雾：** 无 / ...
+- **对现有 Tickets 的影响：** 无 / update / close / supersede

package/template/workflows/specdev/W-wayfinder/wayfinder-map-template.md

@@ -4,79 +4,26 @@ change: <YYYY-MM-DD-topic>
 status: active
 ---
 
-# Wayfinder Map: <目标名称>
+# Wayfinder Map: <地图名称>
 
-> 本地图是**索引而非仓库**：每个决策只在一处存放，地图只给一行摘要并链接到详情。凡是人会读到的叙述，用**名称**指代 Ticket，不用裸编号。
+## 目的地
 
-- **共享地图：** `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
-- **调查目录：** `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
-- **领取状态：** `<Path>{roots.state}/specdev/status.json</Path>`
+<到达此地图终点时的样子——此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 Ticket 之前以其为定位。>
 
-## 1. 目标
+## 说明
 
-<终点长什么样，一到两行。目标是第一动作，塑造每一个 Ticket，并固定范围。>
+<领域；每个会话应咨询的 skills；此工作的常设偏好；是否明确把执行带入地图。>
 
-## 2. 笔记
+## 已做出的决策
 
-- **领域：**
-- **需参考的 skills：**
-- **固定偏好 / 约束：**
-- **执行授权：** 默认只产出决策不产出交付物；如需把执行纳入地图，在此显式写明。
+<!-- 索引——每个已关闭 Ticket 一行：足以判断相关性，然后放大链接查看 solution comment 持有的详细信息。开放 Tickets 通过本地 tracker 查询，不列在这里。 -->
 
-## 3. 调查清单（前沿由此表投影）
+- **<已关闭 Ticket 标题>：** `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/INV-01/01-solution.md</Path>` —— <答案的一句话概括>
 
-> 前沿 = `open` + 依赖已满足（unblocked）+ 尚未领取（unclaimed）的行。走完地图时只从前沿取 Ticket。
+## 尚未明确
 
-| 名称 | ID | Type | 模式 | 问题 | Blocked By | Owner/Claim | 状态 | Result |
-|---|---|---|---|---|---|---|---|---|
-| 示例：登录态跨域刷新策略 | INV-01 | research | AFK | ... | — | unassigned | open | `<Path>{roots.state}/specdev/changes/{change}/investigation/INV-01-<name>.md</Path>` |
+<!-- 范围内但尚无法精确表述为 Ticket 的战争迷雾；随着前沿推进而升级。 -->
 
-- Type：research（可证实）/ decision（需取舍）/ validation（需实验验证）/ mapping（建立调用链/影响面）。
-- 模式：AFK（子代理独立完成，典型 research/mapping）/ HITL（须与用户实时交流，代理不代答，典型 decision）。
+## 超出范围
 
-## 4. 调查 DAG
-
-```text
-INV-01
-  ├─→ INV-02
-  └─→ INV-03
-```
-
-- 标记可并行调查与必须串行的决策点，避免多个调查重复回答同一问题。
-
-## 5. 并行与领取规则
-
-- 最大并发来自 `<Path>{roots.state}/specdev/config.json</Path>`。
-- 当前领取集合以 `<Path>{roots.state}/specdev/status.json</Path>` 为权威。
-- 同一调查 Ticket 只能有一个 owner/session。
-- **research / AFK 型可并行领取**；**decision 及其他 HITL 型，单会话一次只解决一个**（research 除外），逐个解决让地图稳定生长。
-- 共享地图是状态投影，领取变更后必须同步；写回前先重读，预期并发编辑。
-
-## 6. 已定决策（实际走过的路线）
-
-> 每关闭一个 Ticket 追加一行结论索引。越界工作不写这里，移入“范围之外”。
-
-| 名称 | 结论（一行） | 置信度 | 消费工件 | 详情指针 |
-|---|---|---|---|---|
-
-## 7. 尚未指定（战争迷雾）
-
-> 范围内、已隐约感到会出现、但此刻还无法**精确表述**的决策。看得清就毕业成第 3 节的 Ticket，看不清就留在这里。不要预先切成 Ticket 大小的碎片。
-
-- ...
-
-## 8. 范围之外
-
-> 超出目标的工作。永不毕业回地图；目标被重画时作为新 change 处理。已存在 Ticket 若被发现越界，关闭后在此留一行摘要与理由。
-
-| 被排除的工作 | 理由 |
-|---|---|
-
-## 9. 停止条件
-
-- [ ] 目标已命名，并塑造了地图上的每个 Ticket。
-- [ ] 所有高影响未知项已 confirmed、disproved，或明确转为用户/owner 决策。
-- [ ] 战争迷雾中不再有阻塞目标、且已可精确表述却未立 Ticket 的问题。
-- [ ] 可以形成 Ready Spec、Ticket、诊断契约或架构决策。
-- [ ] 没有把产品实现留在调查 Ticket 中。
-- [ ] 所有 claim 已释放或转为明确 blocked。
+<!-- 被裁定在目的地之外的工作；已关闭，永不升级。 -->

package/template/workflows/specdev/common/README.md

@@ -19,6 +19,7 @@
 - 偏差控制：`<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/code-commenting-rule.md</Path>`
+- 代码库设计：`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
 
 ## 结构化工件 Schema
 
@@ -29,6 +30,8 @@
 - Ticket：`<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
 - Tickets Map：`<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
 - Goal Plan：`<Path>{roots.workflows}/specdev/common/schemas/goal-plan.schema.json</Path>`
+- 设计树：`<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
+- Wayfinder Ticket：`<Path>{roots.workflows}/specdev/common/schemas/wayfinder-ticket.schema.json</Path>`
 
 ## 工具与 Skill
 
@@ -36,6 +39,7 @@
 - 校验器说明：`<Path>{roots.workflows}/specdev/common/tools/README.md</Path>`
 - 外部技术研究 Skill：`<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`
 - 并行 Ticket worktree Skill：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
+- Agent 交付合同 Skill：`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
 
 ## 加载原则
 

package/template/workflows/specdev/common/rules/artifact-contract.md

@@ -9,6 +9,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | 分诊 | `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` | 请求类别、影响、风险、缺失输入和下一 work | 详细实现方案 |
 | 诊断 | `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
 | 设计日志 | `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
+| 设计树 | `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
 | 领域上下文 | `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 当前领域术语、语义和稳定不变量 | 临时会议记录 |
 | 架构决策 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 已接受架构决策、原因、后果和替代关系 | 尚未决定的方案集合 |
 | Spec | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
@@ -16,6 +17,10 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
 | Tickets Map | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
 | Goal Plan | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
 | Evidence | `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
+| Wayfinder 地图 | `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
+| Wayfinder Ticket | `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
+| Wayfinder solution comment | `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md</Path>` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
+| 架构审查 | `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
 
 ## 2. 权威顺序