@namewta/speculo 1.0.2 → 1.0.4

package/template/workflows/specdev/T-tickets/references/planning-procedure.md

@@ -0,0 +1,233 @@
+# 拆分 Tickets
+
+
+Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策，但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
+
+本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
+
+
+## 输入
+
+优先读取：
+
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- Bug 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 项目 Agent 指令及其声明的项目 Skill 根；
+- 项目当前代码、测试、配置、schema 和 CI 事实。
+
+若尚无 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`，只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续；否则建议先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
+
+## 流程
+
+### 1. 输入预检
+
+1. 先读取上游工件索引，按当前 Ticket 的依赖、缺口和冲突关键词定位，再回读相关工件；
+2. 检查 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的 `ready_for_tickets`；
+3. 按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 处理 Spec、ADR、用户决定与代码事实的冲突；
+4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节；
+5. 高影响未决问题没有关闭时停止，不通过更详细的 Ticket 文字伪装决策完备。
+
+**完成标准**：拆分依据、权威顺序、合同范围与未决问题已明确。
+
+### 2. 探索代码库与实现地形
+
+如果尚未探索，进行只读探索：
+
+- 找到行为入口、稳定接口、测试接缝、数据流和错误路径；
+- 查找相邻或类似实现，优先复用项目现有模式；
+- 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点；
+- 查找现有测试命令、夹具、类型检查、构建和 CI 门禁；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 使用项目领域词汇；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>` 避免重新争论已接受决策。
+
+遇到不熟悉的模块、外部依赖或第三方库时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`，再继续拆分。
+
+#### 项目 Skill 路由
+
+1. 读取项目 Agent 指令，确定项目声明的 Skill 根；至少枚举 `<Path>.agents/skills/**/SKILL.md</Path>`，存在其他项目级 Skill 根时一并枚举；
+2. 先读取候选 Skill 的 frontmatter 与入口路由；只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
+3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
+4. 使用项目根相对 Path 记录每个 Skill 的入口文件，同时记录触发 scope、读取时机和用途；不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill；
+5. 未发现适用项目 Skill 时，记录已扫描的 Skill 根和“无适用项”，不生成虚假路径；项目 Skill 清单是最低集合而非 allowlist。
+
+#### Prefactor
+
+遵循“让变更变容易，然后做容易的变更”：
+
+- 如果当前接口、依赖或接缝会使后续实现明显不安全或重复，提出前置 prefactor Ticket；
+- prefactor 必须说明它解除的具体阻碍；
+- prefactor 必须独立有价值且可验证；
+- 不为了“更干净”而创建与目标无关的重构 Ticket。
+
+**完成标准**：实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
+
+### 3. 草拟曳光弹式垂直切片
+
+加载 `<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`。每个切片应横向穿过交付该行为所需的最小层次组合，而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
+
+每个 Ticket 必须：
+
+- 交付一个可观察行为，或一个能独立解除后续阻塞的安全准备能力；
+- 完成后可以独立演示、测试或验证；
+- 适合一个全新 Agent 上下文在不中断的情况下完成；
+- 与其他 Ticket 有实质行为差异；
+- 只依赖真正阻止它开始的前置产物；
+- 自带至少一种完成证据。
+
+#### 宽重构例外
+
+字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时，按以下顺序：
+
+1. **Expand**：在旧形式旁增加新形式，保持旧调用方可工作；
+2. **Migrate batches**：按包、目录、消费者或风险分批迁移，每批独立成 Ticket；
+3. **Contract**：确认旧调用点为零后删除旧形式；
+4. 若迁移批次无法各自保持绿色，使用隔离集成分支和最终集成验证 Gate，但仍保留明确的批次与责任边界。
+
+**完成标准**：每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
+
+### 4. 判定规划深度与风险
+
+按 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>` 为每个 Ticket 标注：
+
+- `lite`：局部、可逆、沿用既有模式、无公共契约或迁移影响；
+- `standard`：大多数多文件或跨层垂直切片；
+- `deep`：公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
+
+规划深度不是优先级，也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
+
+### 5. 写成决策完备 Ticket
+
+必须按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 填写本票真实调用绑定；Map 中的读取路由不能代替调用。
+
+使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 填写：
+
+- 战略目标、可观察产出与来源追踪；
+- 当前代码事实和需求差距；
+- 已锁定决策、低影响假设和未决问题；
+- IN / REUSE / OUT；
+- 用户或调用者视角的端到端行为；
+- Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约；
+- 有序执行路线和安全落点；
+- expected、writable、read-only、shared 路径；
+- 正常、失败和回归验证矩阵；
+- 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查，以及按实际跨边界风险判定的 E2E disposition；
+- 每个实现 Ticket 的 implementation commit 与对应父分支完成条件；仅 required 模式创建独立 worktree；
+- Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点；
+- 可判定验收标准。
+
+路径所有权必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`，证据设计必须遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+
+### 6. 构建依赖 DAG、合同覆盖与并发检查
+
+1. 使用 Ticket ID 建立 `blocked_by`；
+2. 检测循环和不存在的引用；
+3. 识别根 Ticket、汇合点、扇出与收缩点；
+4. 为每个 Spec 验收合同映射至少一个 Ticket；
+5. 检查并行候选的 `writable_paths` 是否相交；
+6. 共享路径必须指定唯一 owner，通常由专门 Ticket 或明确的集成 owner 修改；
+7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
+
+使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 草拟总体 Map；写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
+
+### 7. Definition of Ready
+
+加载 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>` 逐个检查。
+
+存在以下任一情况时 `ready: false`：
+
+- 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
+- 依赖缺失或 DAG 有环；
+- 可写路径不明确或并行所有权冲突；
+- 验证方法不能执行且没有批准的替代证据；
+- Ticket 未声明 E2E required/not-required 及理由，或在 required 模式把 E2E 安排到 source worktree；
+- Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵，项目 Skill 路径不存在、不是项目根相对路径，或当前 Ticket 未被 `ALL`/自身 ID 覆盖；
+- 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口；
+- 单个新上下文无法完成；
+- Standard/Deep 缺少有序执行路线；
+- Deep 缺少迁移、兼容、监控、回滚或批准点。
+
+### 8. 与用户核对
+
+以完整编号列表展示所有 Ticket，至少包含：
+
+- 标题；
+- 可观察交付；
+- 被阻塞于；
+- Planning Depth 与触发原因；
+- 风险；
+- Ready 状态；
+- 关键未决问题；
+- 预计并行组和共享路径 owner；
+- `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
+
+核对：
+
+- 粒度是否适合单一上下文；
+- 是否出现水平切片；
+- 阻塞边是否真实；
+- 是否应合并、进一步拆分或增加 prefactor；
+- 合同是否全部覆盖；
+- 路径所有权和验证是否可信。
+
+每次修改后重新展示完整列表，直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时，可使用推荐默认值并把假设写入 Ticket，不为形式重复询问。
+
+### 9. 发布
+
+创建：
+
+- Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- Evidence 目录：`<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+按拓扑顺序写入 Ticket：
+
+```text
+<Path>{roots.state}/specdev/changes/{change}/ticket/NN-<ticket-name>.md</Path>
+```
+
+`NN` 使用两位或更多位零填充数字；Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID，而不是相对文件路径。
+
+使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 和 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 生成工件，并对照：
+
+- `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage tickets \
+  --repo <project-root> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+更新 `<Path>{roots.state}/specdev/status.json</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。
+
+## 完成标准
+
+- Ticket 目录和 Map 已写入完整 Path 标签 所指位置；
+- Spec 合同全部 covered 或有明确批准的 deferred；
+- DAG 无环、阻塞引用存在；
+- Ready Ticket 无高影响未知项；
+- 并行 Ticket 无未解决的可写冲突；
+- 每个 Ticket 可独立验证且适配单一上下文；
+- Tickets Map 已记录总体实施背景；每个 Ticket 被项目 Skill 读取矩阵覆盖，Skill 路径存在且为项目根相对路径；
+- Prefactor 与 expand-contract 使用条件正确；
+- 用户已批准拆分或明确授权自主发布；
+- 校验器无 error。
+
+## 子文件引用
+
+- 拆分规则：`<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`
+- Ticket 就绪规则：`<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>`
+- Tickets Map 模板：`<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`
+
+## 下一步
+
+满足任一情况时建议运行 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`：Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan；少量线性 Ready Ticket 可直接进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。

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

@@ -1,5 +1,9 @@
 ---
 schema_version: 3
+plan_contract_version: 1
+skill_scan: unreviewed
+skill_bindings: []
+resource_claims: []
 artifact: ticket
 change: <YYYY-MM-DD-topic>
 id: T-01
@@ -132,3 +136,15 @@ E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不
 - [ ] E2E disposition 已执行；required 模式 E2E 在 parent-candidate、current 模式在 current workspace 由 Lead 完成。
 - [ ] 未发生未批准的范围、契约或发布偏差。
 - [ ] Ticket、Tickets Map 和 Evidence 状态一致。
+
+## 11. SKILL 调用计划
+
+依据 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 填写 frontmatter 绑定；正文解释每项调用为什么属于本票、具体何时调用、输入定位、输出如何用于下一步。不是仅给出技能名称或阅读列表。没有适用项目 Skill 时写明真实扫描证据；不要保留 unreviewed。
+
+## 12. 停止、检查点与交付
+
+- **用户交付要求与数量：** 与 Map 的 requested_deliverables 对齐；不为压缩而减少。
+- **必需 Skill/引用/测试不可用：** 阻塞本票，报告缺口，不静默替换默认工具。
+- **归属与资源冲突：** 暂停本票和受影响下游，不接管他人状态；独立票由 map 继续。
+- **检查点：** 记录源版本、绑定摘要、已完成步骤、Evidence 和未闭合动作；恢复前回读。
+- **完成出口：** 全部适用验收及实际 Skill 证据通过，再将结果交回 Goal；未完成项明确列出。

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

@@ -1,5 +1,9 @@
 ---
 schema_version: 3
+plan_contract_version: 1
+plan_revision: 1
+requested_deliverables: []
+deliverable_policy: unreviewed
 artifact: tickets-map
 change: <YYYY-MM-DD-topic>
 status: draft
@@ -86,3 +90,13 @@ T-tickets 可以标注候选 Wave、E2E disposition 和行为里程碑。需要
 - 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 链接。
+
+## 9. 总控与恢复
+
+从本 Map 进入 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 的 plan/run/resume/replan/verify。先运行 `<Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path>` 的 `--map` 只读检查，再按 `<Path>{roots.workflows}/specdev/P-goal-plan/references/map-control.md</Path>` 调用 I 和真实 Skill、验收、更新状态直到完成或明确阻塞；此工具本身不执行代码。
+
+- frontmatter 中 requested_deliverables 用 JSON 对象数组记录用户明确要求的名称与正整数 count；没有额外数量要求时用空数组，并在 deliverable_policy 记录依据，不能保留 unreviewed。
+- requested_deliverables 属于用户交付合同；done 之前按实际产物核对，不从 Ticket 数量推断交付数量。
+- 变更范围或验收后递增 plan_revision 并重算受影响闭包；原完成证据保留，失效证据不得复用。
+- 共享语义资源在 Ticket resource_claims 声明（例如 API、表、迁移序列、正式记忆写集）；不把“不同文件”视为互不冲突。
+- 未闭合事务先查原网关，其他任务冲突只暂停相关部分；全部票 done 后仍需整体 Gate、数量和集成验收。

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

@@ -3,7 +3,7 @@ id: specdev/triage
 type: workflow-entry
 workflow: specdev
 name: 请求分诊
-description: 把远程 Issue、URL、文件或对话冻结为本地来源工件，完成风险分诊与路由，并在本地 change 完成后受控回写和关闭支持的远程 Issue。
+description: 需要冻结外部来源、审计摄入或对 completed change 回写来源 Issue 时使用；已清晰的本地需求不必经本入口路由。
 keywords: [triage, 摄入, import, issue, reconcile, close, 风险, 路由]
 ---
 
@@ -20,6 +20,8 @@ Triage 是 SpecDev 唯一的远程摄入与关闭边界。开发期间，`<Path>
 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
 
 
+普通本地请求直接进入适用 Work，不为了完成路由额外创建来源工件。用户明确要求来源审计时仍执行完整 intake；缺陷根因诊断仍交 D，不删除风险分诊与远程回写能力。
+
 ## 模式
 
 - **intake**：冻结输入、创建或恢复 change、分类并返回下一 Work。

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

@@ -2,135 +2,41 @@
 id: specdev/wayfinder
 type: workflow-entry
 workflow: specdev
-name: 寻路
-description: 为超出单次会话且路径尚不可见的工作建立本地共享地图，逐个解决 research、prototype、grilling 或 task Ticket，直到目的地路线决策完备。
-keywords: [wayfinder, 寻路, shared-map, research, prototype, grilling, task, 战争迷雾, 前沿]
+name: 探索大需求与 Change 边界
+description: 大需求的 change 边界或实施路线尚不可见时建立探索地图，并分别澄清各 change；已有清晰 Spec 时不触发。
+keywords: [initiative, 战争迷雾, change划分, exploration]
 ---
 
-# 寻路
+# 探索大需求与 Change 边界
 
-> 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
+> 激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`。
 
-一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
-
-目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
+W 位于 change 形成之前：Initiative → 候选 change → 各自 Grill → Spec → Tickets → 一个或多个 change 的 Goal。探索载体继续使用普通 change 目录，不增加另一套全局状态根；它不等于最终产品 change。
 
 ## 读取范围
 
-1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
-2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，按当前分支、状态和关键词定位最小相关工件。
-3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取；缺少匹配证据或 owner/gateway 时停止受影响分支。
-
-
-## 核心纪律
-
-### 规划，而非执行
-
-Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
-
-### 用名称引用
-
-每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
-
-### 每会话一个 Ticket
-
-无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 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/changes/{change}/.status.json</Path>` 的 `claimed_investigations`
-
-每次绘制或遍历前加载 `<Path>{roots.workflows}/specdev/W-wayfinder/local-tracker-contract.md</Path>`。Ticket 和地图模板：
-
-- `<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>`
-
-## Ticket 类型
-
-每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
-
-- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
-- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` 检测项目 UI、比较功能风格候选并逐步确认设计方向，把 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>` 与 comparison locator 链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
-- **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，否则给人类精确清单。
-
-Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:grilling | wayfinder:task`。
-
-## 战争迷雾与范围
-
-地图刻意不完整：不要绘制还看不到的内容。活跃 Tickets 之外是**战争迷雾**——能感觉即将到来、但依赖尚未解决问题而无法精确陈述的决策和调查。
-
-**迷雾还是 Ticket？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
-
-- 问题已经清晰时做成 Ticket，即使仍被阻塞；
-- 还无法精确表述时留在“尚未明确”，不预先切成 Ticket 大小碎片。
-
-目的地固定范围。目标之外的工作进入**超出范围**，不是战争迷雾。范围之外永不升级；只有重新命名目的地并创建新 change 时才重新考虑。越界 Ticket 关闭为 `out-of-scope`，链接进“超出范围”，不进入“已做出的决策”。
-
-## 调用模式
-
-### 绘制地图
-
-用户带着模糊想法调用：
-
-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。
-
-### 遍历地图
-
-用户带来地图，可选指定 Ticket：
-
-1. 加载地图的低分辨率视图，不加载每个 Ticket 正文。
-2. 用户指定 Ticket 时使用它；否则按本地 tracker contract 查询并选择第一个 frontier Ticket。
-3. 在任何工作前领取 Ticket。已领取时跳过并选择其他 frontier。
-4. 按需缩放：只读取当前 Ticket、相关或已关闭 Ticket 的详情，以及“说明”指定的能力。
-5. 解决当前唯一 Ticket，使用下一个未占用编号写 solution comment，原子关闭 Ticket 并释放 claim。
-6. 在地图“已做出的决策”追加名称链接和一句概括；越界则写入“超出范围”。
-7. 创建新浮现的 Tickets，第二遍连接阻塞；从“尚未明确”删除每个已升级补丁；更新或关闭被答案判定无效的 Tickets。
-
-写回前重读地图、Ticket 与 claims，预期其他会话并发编辑。
-
-**完成标准**：本会话只关闭一个 Ticket；Ticket、solution comment、claim、地图和新 frontier 一致。
-
-## 收敛与路由
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；读取共享地图、当前问题与依赖索引，只回读命中原文。低分辨率地图不缓存所有开放票正文。
 
-当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
+## 分支
 
-路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder`；Ticket、claim、comment 或地图不一致时保持 blocked。
+| 当前需要 | 按需读取 |
+|---|---|
+| 初次绘制问题空间，或划分多个 change | `<Path>{roots.workflows}/specdev/W-wayfinder/references/initiative-discovery.md</Path>` |
+| 领取并解决一个调查问题，或恢复既有地图 | `<Path>{roots.workflows}/specdev/W-wayfinder/references/map-traversal.md</Path>` 和 `<Path>{roots.workflows}/specdev/W-wayfinder/local-tracker-contract.md</Path>` |
+| 生成地图、问题与答案 | `<Path>{roots.workflows}/specdev/W-wayfinder/wayfinder-map-template.md</Path>`、`<Path>{roots.workflows}/specdev/W-wayfinder/investigation-ticket-template.md</Path>`、`<Path>{roots.workflows}/specdev/W-wayfinder/solution-comment-template.md</Path>` |
+| 选定清晰 change 交给 Goal | `<Path>{roots.workflows}/specdev/W-wayfinder/references/initiative-discovery.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；绘图会话不关闭调查票。这个限制约束 W，不限制 P 的长期 Goal 调度；不静默减少用户明确要求的交付数量。
+- 四类保持 `wayfinder:research`、`wayfinder:prototype`、`wayfinder:grilling`、`wayfinder:task`。HITL 必须真人参与，Agent 不代答；Task 仅解除调查阻塞，不偷做目的地实现。
+- `claimed_investigations` 仍由探索载体的 change 状态唯一拥有。先领取后执行；他人已领取的问题跳过，不接管；只暂停有归属冲突的部分。
+- 每个 materialized change 拥有自己的 design-tree、LOG、CONTEXT、ADR、Spec 与 tickets-map。共享探索答案通过 solution comment 引用，不复制成多个可写事实源。
+- 缺失关键决定或必需证据时保持该 change 未就绪；其他独立清晰 change 可以交接，不要求整个大需求一次揭完迷雾。
 
-- 目的地塑造每个 Ticket 并固定范围；
-- 地图是低分辨率索引，不列开放 Tickets，不复制答案详情；
-- 四类 Ticket 与 HITL/AFK 语义正确；
-- frontier 由 open、unblocked、unclaimed 事实查询；
-- 名称用于人类叙述，裸 ID 只作内部标识；
-- 战争迷雾、Ticket 与超出范围按可精确表述性和范围区分；
-- 每会话最多解决一个 Ticket，HITL 用户没有被 Agent 代答；
-- 每个关闭 Ticket 有 solution comment，资产通过链接引用；
-- claim、阻塞、地图与 Ticket 状态一致；
-- 路径清晰时返回下一 work，不把产品实现藏进寻路。
+## 校验与交接
 
-## 子文件引用
+存在多个候选 change 时，由 W 写 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>`；使用 `<Path>{roots.workflows}/specdev/W-wayfinder/references/initiative-template.json</Path>` 和 `<Path>{roots.workflows}/specdev/common/schemas/initiative.schema.json</Path>`。目标 change 只在用户接受边界后创建，不能挪用已属于其他任务的状态。
 
-- 本地 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>`
+运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder` 校验地图、claim、评论和 initiative；选定成员必须分别满足 Grill 共识、Ready Spec 和 Ready Tickets，再转交 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`。W 不把“地图完成”宣称为产品已经交付。

package/template/workflows/specdev/W-wayfinder/references/initiative-discovery.md

@@ -0,0 +1,29 @@
+# Initiative：从大需求到独立 Change
+
+## 结构与所有权
+
+探索载体是现有 change 目录；W 在其中拥有 `<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 与 wayfinder 地图/调查票。`<Path>{roots.state}/specdev/changes/{change}/initiative.json</Path>` 只记录候选边界、关系和 materialized target，不缓存子 change 的状态、Spec、设计树或票正文。
+
+候选 `id` 是稳定 kebab 标识，`target` 为 null 或实际 sibling change 名；同一个 target 不能重复，也不能指向探索载体本身或父 implementation change。其他任务的现存 change 只能在核验归属并获得明确关联授权后引用，不接管其工作。
+
+## 探索顺序
+
+1. 命名大目标、用户指定数量和排除项；按行为、领域边界、风险、接口与发布独立性广度扫描。
+2. 能描述边界的部分成为候选 change；不能描述的留在迷雾。候选至少写背景、目标、非目标和未知项，不预造实施步骤。
+3. 在探索地图建立共享调查问题；每个问题仍遵循 research/prototype/grilling/task、HITL/AFK 和每会话一个调查票的原纪律。
+4. 用户接受候选边界后，创建或明确关联 target change。共享答案以 solution comment/source 引用导入，不复制成新的永久知识。
+5. 对每个 target 调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；该 target 独立拥有 design-tree、LOG、CONTEXT、ADR。已确认共享决定可引用复用，不能要求用户机械回答同一问题。
+6. 单个 target 的关键决定清晰后分别进入 S/T；无关 target 继续探索。一个 target 的 blocker 不应阻塞其独立 sibling。
+
+## 校验与交接门禁
+
+- 候选 DAG 无环，依赖 ID 存在；目标与来源有证据，未创建 target 的候选不宣称 Ready。
+- `--stage wayfinder` 验证 initiative 结构、目标存在性与禁止自引用；它不等于子 change 已就绪。
+- 交接时对**选定** target 分别执行 `--stage grill` 与 `--stage tickets --repo <project-root>`，检查设计树 consensus、Spec `ready_for_tickets`、所有待执行票 Ready。
+- 选定范围的跨 change 依赖须同时选择或有已完成基线证据，不用未完成/已取消票虚假满足依赖。
+- 一个 target 交给 P 的单 change 分支；两个或以上 Ready target 交给 P 的多 change 分支。P 不接手剩余迷雾，也不为这些未知部分伪造计划。
+- 用户明确要求全部 change 时，报告全部候选与各自阻塞；交接已清晰部分不等于少交付其他部分或宣布整个大需求完成。
+
+## 版本与恢复
+
+变更候选边界或依赖时递增 `revision`，在探索 LOG 记录来源和替代关系。原 claim、评论编号和低分辨率地图仍是原协议；不改写其他任务，不把探索载体迁成父实现 change。两者可以关联，但职责和 owner 分开。

package/template/workflows/specdev/W-wayfinder/references/initiative-template.json

@@ -0,0 +1,8 @@
+{
+  "schema_version": 1,
+  "artifact": "initiative",
+  "change": "<YYYY-MM-DD-initiative>",
+  "revision": 1,
+  "destination": "<大需求目标>",
+  "changes": []
+}

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

@@ -0,0 +1,120 @@
+# 寻路
+
+
+一个模糊的想法出现了——太大而无法放入单个 Agent 会话，且从当前状态到**目的地**的路径尚不可见。寻路就是找到那条路，而非冲向目标。此 work 在 change state 中绘制一张**共享地图**，然后逐个处理其 Tickets，直到路径变得清晰。
+
+目的地可能是一份待移交和迭代的 Spec、一个在规划开始前需锁定的决策，或一项经说明允许在地图中完成的变更。命名目的地是第一步，它塑造每个 Ticket。
+
+
+## 核心纪律
+
+### 规划，而非执行
+
+Wayfinder 默认进行**规划**：每个 Ticket 解决一个决策，当地图完成时路径就清晰了——在某人动手之前没有任何剩余决定。想要直接动手通常说明已经到达地图边缘，是时候移交。只有地图“说明”明确覆盖此行为时，task 才能把解除阻塞的执行带入地图。
+
+### 用名称引用
+
+每张地图和每个 Ticket 都有一个名称。人类阅读的叙述和“已做出的决策”始终用名称引用；ID 和路径包裹在名称链接里，不以裸 `INV-01` 墙代替名称。
+
+### 每会话一个 Ticket
+
+无论绘制还是遍历，**每个会话绝不解决超过一个 Ticket**。绘制地图的会话不解决任何 Ticket；并行 research 的每个独立 Agent 也只负责一个 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/changes/{change}/.status.json</Path>` 的 `claimed_investigations`
+
+每次绘制或遍历前加载 `<Path>{roots.workflows}/specdev/W-wayfinder/local-tracker-contract.md</Path>`。Ticket 和地图模板：
+
+- `<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>`
+
+## Ticket 类型
+
+每个 Ticket 要么是 **HITL**，与一个代表自己发言的人类一起工作；要么是 **AFK**，由 Agent 独立驱动。HITL Ticket 只能通过实时交流解决，Agent 绝不代替人类一方发言。
+
+- **Research（AFK）**：阅读文档、第三方 API 或知识库等资源，揭示某个决策等待的事实。调用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。当需要当前工作目录之外的知识时使用。
+- **Prototype（HITL）**：调用 `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` 检测项目 UI、比较功能风格候选并逐步确认设计方向，把 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>` 与 comparison locator 链接为 solution comment 资产；`{design-id}` 使用 P 返回的 `UI-NNN`，P 不实现目的地。
+- **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，否则给人类精确清单。
+
+Ticket label 只能是 `wayfinder:research | wayfinder:prototype | wayfinder:grilling | wayfinder:task`。
+
+## 战争迷雾与范围
+
+地图刻意不完整：不要绘制还看不到的内容。活跃 Tickets 之外是**战争迷雾**——能感觉即将到来、但依赖尚未解决问题而无法精确陈述的决策和调查。
+
+**迷雾还是 Ticket？** 判断标准是现在能否精确陈述问题，而非现在能否回答：
+
+- 问题已经清晰时做成 Ticket，即使仍被阻塞；
+- 还无法精确表述时留在“尚未明确”，不预先切成 Ticket 大小碎片。
+
+目的地固定范围。目标之外的工作进入**超出范围**，不是战争迷雾。范围之外永不升级；只有重新命名目的地并创建新 change 时才重新考虑。越界 Ticket 关闭为 `out-of-scope`，链接进“超出范围”，不进入“已做出的决策”。
+
+## 调用模式
+
+### 绘制地图
+
+用户带着模糊想法调用：
+
+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。
+
+### 遍历地图
+
+用户带来地图，可选指定 Ticket：
+
+1. 加载地图的低分辨率视图，不加载每个 Ticket 正文。
+2. 用户指定 Ticket 时使用它；否则按本地 tracker contract 查询并选择第一个 frontier Ticket。
+3. 在任何工作前领取 Ticket。已领取时跳过并选择其他 frontier。
+4. 按需缩放：只读取当前 Ticket、相关或已关闭 Ticket 的详情，以及“说明”指定的能力。
+5. 解决当前唯一 Ticket，使用下一个未占用编号写 solution comment，原子关闭 Ticket 并释放 claim。
+6. 在地图“已做出的决策”追加名称链接和一句概括；越界则写入“超出范围”。
+7. 创建新浮现的 Tickets，第二遍连接阻塞；从“尚未明确”删除每个已升级补丁；更新或关闭被答案判定无效的 Tickets。
+
+写回前重读地图、Ticket 与 claims，预期其他会话并发编辑。
+
+**完成标准**：本会话只关闭一个 Ticket；Ticket、solution comment、claim、地图和新 frontier 一致。
+
+## 收敛与路由
+
+当前沿为空且“尚未明确”不再包含阻塞目的地的内容时，路径清晰：
+
+路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage wayfinder`；Ticket、claim、comment 或地图不一致时保持 blocked。
+
+- 需要产品或架构取舍：`<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 并固定范围；
+- 地图是低分辨率索引，不列开放 Tickets，不复制答案详情；
+- 四类 Ticket 与 HITL/AFK 语义正确；
+- frontier 由 open、unblocked、unclaimed 事实查询；
+- 名称用于人类叙述，裸 ID 只作内部标识；
+- 战争迷雾、Ticket 与超出范围按可精确表述性和范围区分；
+- 每会话最多解决一个 Ticket，HITL 用户没有被 Agent 代答；
+- 每个关闭 Ticket 有 solution comment，资产通过链接引用；
+- claim、阻塞、地图与 Ticket 状态一致；
+- 路径清晰时返回下一 work，不把产品实现藏进寻路。
+
+## 子文件引用
+
+- 本地 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>`