@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/T-tickets/tickets-map-template.md

@@ -1,70 +1,72 @@
-# Tickets Map: <工作简短名称>
+---
+schema_version: 3
+artifact: tickets-map
+change: <YYYY-MM-DD-topic>
+status: draft
+---
 
-<一段话总结所有 ticket 共同构建的内容。如果拆分依据是 spec，引用 spec.md。如果基于对话或计划，说明来源。>
+# Tickets Map: <工作名称>
 
-## 执行清单
+- **Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **Ticket 目录：** `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- **Evidence 目录：** `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- **可选 Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
 
-| 编号 | Ticket | 被阻塞于 | Gate | Contract ID | 状态 |
-|------|--------|----------|------|-------------|------|
-| 01 | [ticket-name](./ticket/01-<kebab-title>.md) | 无 | P0 | — | 未开始 |
-| 02 | [ticket-name](./ticket/02-<kebab-title>.md) | 01 | P1 | P1-03 | 未开始 |
-| 10 | [ticket-name](./ticket/10-<kebab-title>.md) | 02, 05 | P2 | — | 未开始 |
+## 1. 目标与拆分策略
 
-> **状态枚举**：未开始 / 进行中 / 已完成。所有 ticket 初始均为"未开始"。
-> **被阻塞于**列填写阻塞本 ticket 的 ticket 编号（如 `01`、`02, 05`），执行者需自行打开对应 ticket 文件查看其状态。不可仅凭此表判断——始终以对应 ticket 文件中的状态字段为准。
-> **Gate 列**：P0 = 核心基础设施（阻塞所有后续工作）/ P1 = 主要功能切片 / P2 = 增强和边界情况。由 P-goal-plan 填充，T-tickets 阶段留空或标注 `[待标注]`。
-> **Contract ID 列**：如有冻结合同/验收文档，填写本 ticket 覆盖的验收条目 ID（如 `P0-01, P1-03`）；无合同则填 `—`。由 P-goal-plan 填充。
+引用主要用户故事、验收合同和架构决策，说明所有 Ticket 共同交付的目标、切片原则、prefactor 和 expand-contract 选择。不要复制整个 Spec。
 
-## 依赖关系（门禁标注 DAG）
+## 2. 执行清单
 
-<!-- 用 ASCII DAG 展示 ticket 之间的阻塞关系和门禁边界。
-     由 T-tickets 写入基础树形结构，由 P-goal-plan 标注门禁层级（P0/P1/P2）、
-     就绪标记 [READY] 和扇出标记 [FAN-OUT: N路并行]。
+| ID | Ticket | 可观察产出 | Blocked By | Depth | Risk | Ready | Owner | Contract IDs | Wave/Gate | Status |
+|---|---|---|---|---|---|---|---|---|---|---|
+| T-01 | `<Path>{roots.state}/specdev/changes/{change}/ticket/01-<ticket-name>.md</Path>` | ... | — | standard | medium | yes | unassigned | AC-001 | — | ready |
 
-     绘制约定：
-     - 每行一个 ticket，缩进表示依赖深度
-     - → 表示依赖关系（A → B 表示 B 依赖 A）
-     - 用注释标注门禁边界：--- P0 gate ---
-     - 可立即开始的 ticket 标注 [READY]
-     - 扇出点标注 [FAN-OUT: N路并行]
+Ticket frontmatter 是状态、依赖、深度和路径访问契约的权威；本表是同步投影，不得独立修改出另一套真相。
 
-     示例格式：
-     01 [READY]  →  02 [FAN-OUT: 3路并行]
-                          ├→ 03 [P0]
-                          ├→ 04 [P1]
-                          └→ 05 [P1]
-     --- P0 gate ---
-     03  →  06 [P1]  →  07 [P2]
--->
+## 3. 依赖 DAG
 
+```text
+T-01 [READY]
+  ├─→ T-02
+  └─→ T-03
+        └─→ T-04
 ```
-01-<name>          ← 无阻塞，可立即开始
-  ├── 02-<name>    ← 阻塞于 01
-  └── 03-<name>    ← 阻塞于 01
-        └── 04-<name>  ← 阻塞于 03
-```
 
-## 并行规则
+每条边必须表示真实开始条件。标记关键汇合点、prefactor、expand、migrate、observe、contract 和集成验证点。
+
+## 4. 合同覆盖矩阵
+
+| Contract ID | 覆盖 Ticket | 验证接缝 | 状态 | 说明 |
+|---|---|---|---|---|
+| AC-001 | T-01 | ... | covered | ... |
+
+`uncovered` 必须修复；`deferred` 必须有用户批准、原因和后续归属。
 
-- 最大 **3** 个并发实现者（ticket 数 > 20 时可调至 4）
-- 并发 ticket 的 file allowlist 必须互不重叠——两两之间无可写文件交集
-- 共享文件（package.json、lockfile、合同文档、IPC 根导出、领域词汇表）仅由 Lead 修改
-- 共享文件修改后，所有并发子代理需在继续前同步
+## 5. 并行与路径所有权
 
-## 横切关注点
+- 最大并发来自 `<Path>{roots.state}/specdev/config.json</Path>`。
+- shared owner 为 Lead 或专用 Ticket。
+- 项目路径契约以 Ticket frontmatter 为准。
+- 并行写代码的 Ticket 使用独立 worktree；只读调查不需要。
 
-<!-- 跨多个 ticket 的规则与约束。仅在有实际内容时填写，无则省略整个小节。 -->
+| Ticket A | Ticket B | Writable 交集 | 真实依赖 | 处理 |
+|---|---|---|---|---|
+| T-02 | T-03 | 无 | 否 | 可并行 |
 
-- **数据安全铁律**：<冻结的常量、不可改的 wire-format、持久化格式>
-- **契约先行**：<跨 ticket 的 schema/API 变更顺序约束>
-- **行号现场核对**：所有文件路径和行号为近似，实施时以现场代码为准。
+## 6. Gate、Wave 与集成点
 
-## 阻塞关系说明
+T-tickets 可以标注候选 Wave 和行为里程碑。需要正式跨 Ticket 编排时，由 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 完成 Gate、Wave、owner、发布与恢复，并把结果投影回本 Map。
 
-<!-- 依赖图的文字说明。简单线性链可省略整个小节。对于扩展-收缩模式，解释三阶段。 -->
+## 7. 横切契约与风险
 
-<描述为何 ticket B 被 ticket A 阻塞。扩展-收缩模式：扩展阶段创建新形式 → 迁移批次逐步切换调用点 → 收缩阶段删除旧形式。>
+只记录跨多个 Ticket 的数据、安全、兼容、共享接口、迁移、发布和恢复规则。单 Ticket 规则留在具体 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`。
 
-## 风险与注意事项
+## 8. 同步规则
 
-<!-- 跨 ticket 的风险、回滚考虑。无可省略整个小节。 -->
+- Ticket 状态变化后同步执行清单；
+- Ticket ID、路径、依赖或 frontmatter 不一致时，以 Ticket 文件为权威并修复本 Map；
+- Goal Plan 存在时，Wave、Gate 和 owner 以 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 为编排权威；
+- 依赖、合同覆盖或路径所有权变化后运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`；
+- 内部工件不得使用相对 Markdown 链接。

package/template/workflows/specdev/T-triage/T-triage.md

@@ -2,75 +2,44 @@
 id: specdev/triage
 type: workflow-entry
 workflow: specdev
-name: Issue 分诊
-description: 将外部 issue 摄入并分诊为本地 change：深度理解上下文后写入 source-issue.md 与 triage.md，再推荐下一 work（G-grill / S-spec / I-implement / D-diagnose 等）。
-keywords: [分诊, triage, issue, 摄入, 变更引导, needs-triage]
+name: 请求分诊
+description: 完整摄入外部请求，判断问题类型、影响、风险、缺失信息和下一 work，不在分诊阶段过早设计或实现。
+keywords: [triage, 摄入, issue, 风险, 路由]
 ---
 
-# Issue 分诊
+# 请求分诊
 
-将外部 issue **分诊**为本地 change 引导：摄入 → 深度理解 → 写入 `source-issue.md` 与 `triage.md` → 推荐下一 work 后停止。本 work 只落本地产物；ADR / LOG / CONTEXT / spec / ticket 与 tracker 写回由其他 work 或 `common/triage` skill 负责。
-
-产物路径：`<Path>{roots.state}/specdev/changes/{change}/</Path>`（`{change}` = `<YYYY-MM-DD>-<topic>`）。
+分诊负责保存原始意图、建立 change、识别问题类型与风险，并推荐下一 work。分诊完成不等于实现 Ready。
 
 ## 流程
 
-### 1. 摄入 Issue
-
-加载 `<Path>{roots.workflows}/specdev/T-triage/intake-rules.md</Path>`。将 `#N`、URL、粘贴正文或口头描述规范化为统一结构（source、title、body、comments、来源标识）。`gh` 可用则拉取；否则请用户粘贴或补齐最小字段。
-
-**完成标准**：标题、正文、评论与来源标识齐全，或已标注 paste/manual 且最小字段已齐。
-
-### 2. 深度理解
-
-加载 `<Path>{roots.workflows}/specdev/T-triage/understanding-rules.md</Path>`。行为契约对齐 `<Path>{roots.workflows}/specdev/common/triage/AGENT-BRIEF.md</Path>`；范围外只读去重遵循 `<Path>{roots.workflows}/specdev/common/triage/OUT-OF-SCOPE.md</Path>`。
-
-读取永久 `<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>`（若有）；按领域概念探查代码库；扫描 `.out-of-scope/`；对 bug 做轻量可复现判定；归类 `bug` | `enhancement` 并列出具体信息缺口。
-
-**完成标准**：类别已判定；冗余与范围外结果已报告；验证结果或缺口已明确；足以起草行为摘要或已穷尽缺失问题。
-
-### 3. 选择 / 创建 Change
-
-读 `<Path>{roots.state}/specdev/status.json</Path>`（INDEX 启动协议）：新 issue 默认创建 `changes/<YYYY-MM-DD>-<kebab-topic>/`；仅用户声明续作时复用 active；多候选先消歧。在 `active` 数组中追加条目 `{ change, current_work: "specdev/triage", works_run: [], result: null }`；`work_history` 追加进行中记录（含 `change` 字段，缺字段时按 INDEX 补齐）。创建 change 目录后写入初始 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`（`change_status: "active"`、`created_at` 为当前时间）。
-
-**完成标准**：`{change}` 目录存在；`active` 含该 change；`current_work` 为 `"specdev/triage"`。
-
-### 4. 写入分诊产物
-
-加载 `<Path>{roots.workflows}/specdev/T-triage/artifact-templates.md</Path>`，仅写入：
-
-1. `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>` — 原文快照
-2. `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` — 分诊结论、行为契约草案、推荐 status 与 next work
-
-推荐 status 只记在 `triage.md`。标签字符串可读 `<Path>{roots.state}/specdev/.config/status-labels.md</Path>`（若有），否则用角色名。
-
-**完成标准**：两文件已落盘；含类别、推荐 status、行为契约草案与 next work；无残留 `[TODO:]`（`needs-info` 的信息缺口列表除外）。
-
-### 5. 路由推荐
-
-加载 `<Path>{roots.workflows}/specdev/T-triage/routing-rules.md</Path>`。首匹配恰好一条主推荐（可附一条备选），写入 `triage.md` 并展示 Path 与理由。
-
-**完成标准**：主推荐已展示；下游尚未启动。
-
-### 6. 停止并交接
-
-更新 `<Path>{roots.state}/specdev/status.json</Path>`：`active` 中对应条目的 `current_work = null`；`work_history` 对应条目补 `completed_at`、`result`（无 `artifacts` 字段）。汇报 change、类别、status、next work、产物路径；明确询问是否进入推荐 work。用户确认前保持代码与下游不动。
-
-**完成标准**：status 已更新；用户已收到摘要与确认问题；本 work 结束。
+1. **创建或选择 change**：使用 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
+2. **摄入原文**：完整保存到 `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`，保留来源、时间、链接和附件引用，不改写原意。
+3. **读取上下文**：按需读取 `<Path>{roots.state}/specdev/context/</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、当前 change 文档和相关代码事实。
+4. **分类**：bug、feature、refactor、investigation、operations、documentation 或混合；混合请求按主要阻塞问题路由，不强行塞入单类。
+5. **评估**：影响、紧急度、风险、事故半径、安全/数据/兼容/迁移因素和所需人工批准。
+6. **未知项分类**：可发现事实继续探索；无法发现且会改变方案的内容标为 decision-needed；低影响实现细节不阻塞。
+7. **推荐路线**：
+   - bug 且根因未知 → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.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>`；
+   - 小且完全明确、风险低 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 的 Lite Ticket，或用户批准的 Direct Spec 实现；
+   - 路径未知或调查超出单次上下文 → `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
+   - 架构质量问题 → `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`。
+8. **写入结果**：使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`，更新 `<Path>{roots.state}/specdev/status.json</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`（首次创建时使用 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`）。
+
+## 就绪门禁
+
+只有推荐为“直接实现”，且目标、范围、验证、路径和风险均明确并获用户批准时，才能设置 `ready_for_implementation: true`。其他情况必须为 `false`，并明确下一 work。
+
+## 完成标准
+
+- 原始请求未被改写或丢失；
+- 问题类型、影响、风险和未知项已区分；
+- 推荐下一 work 有明确理由；
+- 分诊没有夹带实现；
+- 状态已更新。
 
 ## 子文件引用
 
-| 文件 | 内容 | 触发条件 |
-|------|------|----------|
-| `<Path>{roots.workflows}/specdev/T-triage/intake-rules.md</Path>` | gh / 粘贴摄入、字段规范化 | 步骤 1 |
-| `<Path>{roots.workflows}/specdev/T-triage/understanding-rules.md</Path>` | 理解清单、冗余与范围外 | 步骤 2 |
-| `<Path>{roots.workflows}/specdev/T-triage/artifact-templates.md</Path>` | 两产物模板 | 步骤 4 |
-| `<Path>{roots.workflows}/specdev/T-triage/routing-rules.md</Path>` | 首匹配路由与话术 | 步骤 5 |
-| `<Path>{roots.workflows}/specdev/common/triage/AGENT-BRIEF.md</Path>` | 行为契约原则 | 步骤 2/4 起草摘要 |
-| `<Path>{roots.workflows}/specdev/common/triage/OUT-OF-SCOPE.md</Path>` | 范围外只读去重 | 步骤 2 扫描时 |
-
-## 依赖关系
-
-- **上游**：外部 issue（`gh` 或用户）；可选永久 adr/context；可选 `.out-of-scope/`
-- **下游**（确认后）：`<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`、`<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`、`<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`、`<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`
-- **并列**：`<Path>{roots.workflows}/specdev/common/triage/SKILL.md</Path>` 仍可独立做 tracker 状态机；本 work 只引用其 AGENT-BRIEF / OUT-OF-SCOPE
+- 分诊模板：`<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>`

package/template/workflows/specdev/T-triage/triage-template.md

@@ -0,0 +1,29 @@
+# Triage: <标题>
+
+- **Change：** `<change>`
+- **来源工件：** `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>` / 外部输入
+- **类型：** bug / feature / refactor / investigation / operations / documentation
+- **影响：** 用户、系统、数据或交付影响
+- **风险：** low / medium / high / critical
+- **紧急度：** immediate / scheduled / normal / unknown
+- **当前证据：** 已观察事实，不写推测
+- **相关代码/工件：** `<Path>src/example.ts</Path>` / `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` / 无
+- **缺失的可发现事实：** 无 / 可通过仓库、日志、测试或配置查明的事实
+- **需要用户决定：** 无 / 只有无法从环境推导且会改变目标、范围或风险承受度的决定
+- **推荐下一 work：** D-diagnose-bugs / G-grill-with-docs / S-spec / W-wayfinder / I-implement / R-review-architecture / A-archive-and-consolidate
+- **推荐理由：** 为什么该 work 是最小且正确的下一步
+- **ready_for_implementation：** false
+
+## 路由判定
+
+- **Bug 但根因未知：** 进入 D-diagnose-bugs。
+- **需求或设计存在关键未知：** 进入 G-grill-with-docs。
+- **意图清晰但尚无可验收 Spec：** 进入 S-spec。
+- **需要并行调查多个未知：** 进入 W-wayfinder。
+- **已具备 Ready Ticket，或满足受控 Direct Spec：** 进入 I-implement。
+- **目标是结构健康评估而非立即修复：** 进入 R-review-architecture。
+- **目标是关闭、合并或沉淀 change：** 进入 A-archive-and-consolidate。
+
+## 输出
+
+将结果写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`，并同步 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的下一阶段和阻塞状态。

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

@@ -3,203 +3,136 @@ id: specdev/wayfinder
 type: workflow-entry
 workflow: specdev
 name: 寻路
-description: 为超出单次会话容量的大块工作绘制共享地图，逐个解决调查 tickets 直到通往目标的路径清晰可见。支持研究和决策型 ticket 类型。
-keywords: [寻路, 地图, 探索, 规划, 战争迷雾, 调研]
+description: 为路径未知、跨域或超出单次上下文的工作建立共享调查地图，通过可领取的研究与决策 Ticket 关闭未知项并收敛到可执行路线。
+keywords: [wayfinder, 调查, research, decision, shared-map, 并行, 未知项]
 ---
 
 # 寻路
 
-一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到**目标**的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此 work 在变更目录中绘制路径作为一张**共享地图**，然后逐个处理其 tickets，直到路径变得清晰。
+Wayfinder 用于“尚不知道怎样安全形成 Spec 或实现路线”的场景。它保留共享地图、多会话领取、研究型 Ticket 和决策型 Ticket 的能力，但禁止把产品实现伪装成调查。
 
-目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。
+## 产物
 
-## 规划，而非执行
+- 共享地图：`<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 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其「说明」章节覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+模板：
 
-## 用名称引用
+- `<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
+- `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`
 
-每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的 「已做出的决策」 —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
+## 何时运行
 
-在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的 「已做出的决策」 中以 `- [ticket 标题] —— 答案概括` 形式索引。
+- 路径未知，无法安全写出 Ready Spec 或 Ticket；
+- 需要跨多个领域、技术栈或外部系统调查；
+- 调查量超出单个上下文，适合并行研究；
+- 存在多个相互依赖的高影响未知项；
+- 需要在若干候选方案中先获得事实证据再做决定。
 
-## 地图
+若问题只是一个可在当前上下文通过短暂只读探索回答的事实，不创建 Wayfinder Map。
 
-地图是变更目录下的单个 markdown 文件 `<Path>{roots.state}/specdev/changes/{change}/map.md</Path>`，是规范的产物。其 tickets 是地图内的 task list items（`- [ ]` 格式）。如果工作范围跨多个变更，地图位于主变更目录下。
+## 流程
 
-地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
+### 1. 定义目标与未知项
 
-**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞、领取与前沿的定义见下方「Tickets」节。
+写明最终目标、已知边界、当前不能决定的事项和“为什么这些未知项阻塞规划”。未知项分为：
 
-### 地图正文
+- **research**：答案可由代码、文档、实验或外部来源证实；
+- **decision**：事实已足够，但需要用户或架构 owner 做取舍；
+- **validation**：已有方案，需要实验验证关键可行性或风险；
+- **mapping**：需要建立调用链、数据流、依赖图或影响面。
 
-整个地图的低分辨率视图，每个会话加载一次。开放的 tickets **不**在此处列出 —— 它们直接作为地图文件中的未勾选小节存在。
+低影响实现细节不创建调查 Ticket。
 
-```markdown
-# 地图：<工作名称>
+### 2. 建立共享地图
 
-## 目的地
+使用 `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`：
 
-<到达此地图终点时的样子 —— 此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 ticket 之前以其为定位。>
+- 每个 Ticket 只关闭一个高影响未知项；
+- 写明依赖、owner、领取状态、停止条件和结果消费方；
+- 构建调查 DAG，避免多个调查重复回答同一问题；
+- 标记可并行调查和必须串行的决策点；
+- 定义整体停止条件，不以“所有可能问题都研究完”为目标。
 
-## 说明
+### 3. 领取与并行
 
-<领域；每个会话应咨询的技能；此工作的常设偏好>
+调查者开始前原子地更新 `<Path>{roots.state}/specdev/status.json</Path>` 的 `claimed_investigations`：
 
-## 已做出的决策
+- 未领取且依赖满足 → 设置 owner、session 和 claimed 时间；
+- 已领取 → 跳过并选择其他可用 Ticket；
+- 超过配置的 claim 超时且无进展 → 允许在记录原因后回收；
+- 完成或释放后从领取集合移除，并同步共享地图。
 
-<!-- 索引 —— 每个已关闭 ticket 一行：足以判断相关性，然后跳转到对应小节查看详细信息 -->
+并行调查使用独立上下文；不要复制所有调查历史，只读取共享地图、当前调查 Ticket、相关上游工件和必要代码事实。
 
-- [<已关闭 ticket 标题>](#ticket-标题) —— <答案的一句话概括>
+### 4. 执行调查
 
-## 尚未明确
+调查默认只读。允许：
 
-<!-- 参见"战争迷雾"：范围内但你尚无法做成 ticket 的迷雾；随着前沿推进而升级 -->
+- 代码搜索与静态分析；
+- 文档、规范和官方来源研究；
+- 可撤销的临时实验、最小原型或插桩；
+- 性能测量、调用点扫描、schema 对比或兼容性验证。
 
-## 超出范围
+外部研究使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-<!-- 参见"超出范围"：被裁定在目标之外的工作；已关闭，永不升级 -->
-```
+禁止：
 
-### Tickets
+- 顺手实现产品功能；
+- 提交未经审查的实验代码；
+- 将原型视为最终架构；
+- 在没有证据时把建议写成事实；
+- 无停止条件地持续研究。
 
-每个 ticket 是地图文件内的一个小节，其正文是问题，大小适配一个 100K token 的 agent 会话。Tickets 按创建顺序编号。
+### 5. 记录结果与影响
 
-```markdown
-## <编号>. <Ticket 标题>  `[<类型>]` `[<HITL|AFK>]`
+每个调查结果区分：
 
-**类型：** <research | prototype | grilling | task>
+- 官方或规范事实；
+- 当前代码事实；
+- 实验结果；
+- 推断；
+- 建议；
+- 用户或 owner 决策。
 
-**交互模式：** <HITL | AFK> —— <简要说明为何是此模式>
+写明来源、版本、置信度、适用范围、反例、仍未知项和对以下工件的影响：
 
-**状态：** < - [ ] 开放 | - [x] 已解决 >
+- `<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 的 ticket 标题列表，或"无 —— 可立即开始">
+调查完成、阻塞或释放时，同步调查 Ticket、调查 Evidence、共享地图和领取状态，并返回 investigation ID、状态及三份工件的完整路径。
 
-### 问题
+状态使用 `open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`。
 
-<此 ticket 要解决的决策或调查>
+### 6. 收敛与退出
 
-### 答案
+当剩余未知项不再阻止目标、行为、架构、风险或验证决策时停止。根据结果进入：
 
-<!-- 解决时填写 —— 答案的完整记录。以下仅在 ticket 已解决时出现：-->
+- 需要产品或架构取舍 → `<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，并明确下一调查或用户决策。
 
-<解决此 ticket 时记录的内容。对于 research：发现的摘要和链接资产。对于 prototype：原型的描述和链接。对于 grilling：访谈达成的共识。对于 task：已完成的工作和结果性事实。>
-```
+长期有效且经实现验证的研究，只有在归档时由 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 提升。
 
-每个 ticket 携带一个类型标签 —— 以下之一：`research`、`prototype`、`grilling`、`task`（参见下方 [Ticket 类型](#ticket-类型)）。
+## 完成标准
 
-**领取机制：** 一个会话通过将其名称追加到 `<Path>{roots.state}/specdev/status.json</Path>` 的当前 change 的 `active` 条目中的 `claimed_tickets` 数组来**领取**一个 ticket，在开始任何工作**之前**领取，以便并发会话跳过它。该记录*就是*领取标记：一个开放、未被领取的 ticket 是未被领取的。
-
-**阻塞关系：** 使用 ticket 标题在"被阻塞于"字段中声明依赖。这很关键，因为它使前沿在地图文件中*可视化*呈现 —— 人类无需额外工具就能看到哪些可以开始。当一个 ticket 的所有阻塞 tickets 都已勾选（已解决）时，该 ticket 是**未被阻塞的**；**前沿**是开放（未勾选）、未被阻塞、未被领取的 tickets —— 即已知的边界。
-
-**答案：** 不是正文的一部分 —— 它在解决时写入 ticket 的"答案"小节（参见[遍历地图](#遍历地图)）。解决 ticket 时创建的资产从 ticket 小节链接，而非粘贴进去。如果资产是文件，放置在 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下，从 ticket 链接。
-
-## Ticket 类型
-
-每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
-
-- **Research**（AFK）：调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 启动后台 Agent 针对一手来源调查问题，在 ticket 的答案中链接研究产出文件。当需要当前工作目录之外的知识时使用。
-- **Prototype**（HITL）：调用 `<Path>{roots.workflows}/specdev/common/prototype/SKILL.md</Path>` 制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 UI/逻辑代码。将原型链接为资产。当"它应该是什么样子"或"它应该怎样表现"是关键问题时使用。
-- **Grilling**（HITL）：通过 `<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>` 维护领域模型。默认情况 —— 当不确定类型时选此。
-- **Task**（HITL 或 AFK）：在*决策*能够做出之前必须完成的手动工作 —— 没有需要决定、原型化或研究的内容，但讨论被阻塞直到完成。注册服务以便判断其 API、开通访问权限、移动数据以便看到其形态。这是唯一一个*执行*而非决策的类型 —— 它通过为决策解除阻塞来赢得其位置，而非通过交付目标。Agent 在可能的情况下独立驱动（AFK）；否则它交给人类一份精确的清单（HITL）。当工作完成时解决；答案记录已完成的工作以及后续 tickets 依赖的任何结果性事实（凭据位置、新 URL、行数）。
-
-## 战争迷雾
-
-地图是*刻意*不完整的：不要绘制你还看不到的内容。在活跃的 tickets 之外是**战争迷雾** —— 你能感觉到即将到来但尚无法确定的决策和调查的模糊视野，因为它们依赖于尚未解决的问题。解决一个 ticket 会清除它前方的迷雾，将任何现在可以明确的内容升级为新的 tickets —— 逐个进行，直到通往目标的路径清晰且没有剩余 tickets。
-
-地图的**尚未明确**章节记录这些模糊视野：待定的问题、后续重新审视的区域。它是朝向目标*方向*的未发现前沿 —— 此处的所有内容都在范围内，只是不够清晰以做成 ticket。根据视野允许的范围，尽可能松散或完整地书写；它同时也是协作者阅读工作方向的路标。
-
-**迷雾还是 ticket？** 判断标准是你是否现在就能精确地陈述问题 —— 而不是你现在是否能回答它。
-
-- **做成 ticket 当** 问题已经清晰 —— 即使它被阻塞，你尚不能行动。你能写出明确的"问题"段落。
-- **尚未明确当** 你还无法如此精确地表述它。不要将迷雾预先切成 ticket 大小的碎片：它比 ticket 更粗糙，一个补丁可能在当前沿到达时升级为多个 tickets，或零个。
-
-**尚未明确**排除已决策的内容（「已做出的决策」）、已有的活跃 ticket 以及超出范围的内容（下一节）。
-
-## 超出范围
-
-迷雾只会向目标方向*聚集*。目标确定了范围，因此目标之外的工作是**超出范围**的 —— 它不是迷雾，也不属于**尚未明确**。它在地图上拥有自己的**超出范围**章节：你已自觉排除在*此*工作之外的工作。是范围而非清晰度让它落入此处。
-
-超出范围的工作永不升级 —— 前沿停在目标处 —— 因此只有在目标被重新划定后才会重新考虑，且以一个全新的工作而非恢复旧工作的形式出现。
-
-将某物裁定为超出范围是一个范围界定行为，而非路径上的一步。当已有的一个 ticket 被发现位于目标之外 —— 绘制地图时范围划分错误，或因某个解决方案而暴露 —— **关闭它**（勾选 checkbox），并在**超出范围**章节留下一行：概括加上为何超出范围，链接已关闭的 ticket。它不会出现在**已做出的决策**中，该节记录实际走过的路径 —— 范围边界不是路径上的一步。
-
-## 调用方式
-
-两种模式。无论哪种，**每个会话绝不解决超过一个 ticket。**
-
-### 绘制地图
-
-用户带着模糊的想法调用。
-
-1. **命名目标。** 运行一次 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 访谈会话，以确定此地图正在寻路的目标 —— spec、决策或变更。目标确定了范围，因此先确定它。使用 `<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>` 维护领域模型。
-
-   **完成标准**：目标已命名，范围边界已确定。
-
-2. **绘制前沿。** 再次质询，这次**广度优先**：在整个空间上扩展而非深入任何一条线索，揭示开放的决策和现在可以迈出的第一步。如果此过程没有浮现任何迷雾 —— 通往目标的路径已经清晰，整个旅程足够小到放入一个会话 —— 你不需要地图。停下来询问用户他们希望如何继续。
-
-   **完成标准**：前沿的开放决策和第一步已浮现；迷雾部分已识别并草拟。
-
-3. **创建地图**：写入 `<Path>{roots.state}/specdev/changes/{change}/map.md</Path>`，填写「目的地」和「说明」，「已做出的决策」 为空，迷雾草拟进**尚未明确**。
-
-   **完成标准**：地图文件已创建，目的地、说明、尚未明确、超出范围均已填写。
-
-4. **创建你现在能明确的 tickets** 作为地图文件内的小节 —— 然后在**第二遍**中连接阻塞边（tickets 需要首先有标题才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
-
-   **完成标准**：所有可明确的 tickets 已创建并连接阻塞边；迷雾已归入尚未明确。
-
-5. **停止** —— 绘制地图是一个会话的工作；不要同时解决 tickets。
-
-### 遍历地图
-
-用户带着一张地图（变更目录或 map.md 路径）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
-
-1. **加载地图** —— 低分辨率视图（目的地、说明、已做出的决策、尚未明确、超出范围），而非每个 ticket 的完整正文。
-
-   **完成标准**：地图的低分辨率视图已加载，当前状态已理解。
-
-2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket。**领取它**（规则见上方「Tickets」节）。
-
-   **完成标准**：一个前沿 ticket 已被选中并领取。
-
-3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用「说明」中指定的技能。根据 ticket 类型选择解决方式：**research** 调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>`；**grilling** 使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；**prototype** 调用 `<Path>{roots.workflows}/specdev/common/prototype/SKILL.md</Path>`；**task** 按问题描述执行。查阅 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型。
-
-   **完成标准**：ticket 的问题已解决，答案已记录。
-
-4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的「已做出的决策」中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `claimed_tickets` 中移除该 ticket（规则见上方「Tickets」节）。
-
-   **完成标准**：ticket checkbox 已勾选，「已做出的决策」已更新，领取标记已清除。
-
-5. **添加新浮现的 tickets** 作为地图文件内新的小节（先创建再连接阻塞边）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets（勾选并注明无效原因）。
-
-   **完成标准**：新浮现的 tickets 已添加，迷雾已升级或清除，超出范围的 tickets 已裁定。
-
-用户可以并行运行未被阻塞的 tickets，因此需预期其他会话会并发编辑地图文件和 status.json。
-
-### 完成
-
-当所有 tickets 已关闭（勾选）、迷雾已清空（尚未明确为空或仅剩无法继续分解的模糊项）、且通往目标的路径已清晰时，地图完成。向用户汇报：
-
-- 目的地是否已可抵达——路径上的每个步骤是否都已有明确的 ticket 或决策
-- 「已做出的决策」 中的关键结论摘要
-- 剩余的任何**尚未明确**项——它们是否阻碍行动，还是可作为实现细节处理
-- 建议的下一步行动（移交实现、开始执行、或重新划定目标）
-
-**完成标准**：前沿已清空——无开放 tickets、无残留迷雾、通往目标的路径清晰。完成汇报已向用户呈现。
-
----
+- 共享地图、调查 Ticket 和领取状态一致；
+- 每个调查只关闭一个高影响未知项；
+- 结论区分事实、实验、推断、建议和决定；
+- 来源、版本、置信度和停止条件可追踪；
+- 并行调查没有重复领取或互相覆盖；
+- 调查状态及 Ticket、Evidence、共享地图路径已返回；
+- 没有把产品实现藏在调查中；
+- 已明确下一 work 或阻塞决策。
 
 ## 子文件引用
 
-本入口为单文件 work，所有内容均已内联。以下引用供 work 内各阶段加载：
-
-| 文件 | 触发条件 |
-|------|----------|
-| `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` | 需要访谈以命名目标或解决 grilling 类型 ticket |
-| `<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.state}/specdev/changes/{change}/map.md</Path>` | 地图持久化文件 |
-
-状态追踪：
-- `<Path>{roots.state}/specdev/status.json</Path>` —— `active` 条目中的 `claimed_tickets` 数组记录当前领取的 ticket
+- 调查 Ticket 模板：`<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`
+- 共享地图模板：`<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`

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

@@ -0,0 +1,50 @@
+---
+artifact: investigation-ticket
+id: INV-01
+type: research
+status: open
+blocked_by: []
+owner: unassigned
+claimed_by: null
+claimed_at: null
+---
+
+# Investigation INV-01: <问题>
+
+- **调查文件：** `<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>`
+
+## 1. 决策用途
+
+- 要回答或决定什么：
+- 为什么阻塞规划：
+- 结果由哪个工件消费：
+
+## 2. 已知事实与假设
+
+### 已知事实
+
+### 待验证假设
+
+## 3. 调查契约
+
+- **允许的代码探索：** `<Path>project/relative/path/**</Path>`
+- **允许的实验：**
+- **禁止的产品实现：**
+- **来源优先级：**
+- **停止条件：**
+- **时间或资源边界：**
+
+## 4. 结果
+
+- **状态：** confirmed / disproved / decision-needed / unresolved / superseded
+- **结论：**
+- **证据：**
+- **置信度：** 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>`
+- **下一步：**