@namewta/speculo 0.2.2 → 0.2.6

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

@@ -0,0 +1,241 @@
+---
+id: specdev/tickets
+type: workflow-entry
+workflow: specdev
+name: 拆分 Tickets
+description: 将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
+keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
+---
+
+# 拆分 Tickets
+
+将 plan、spec 或对话拆分为一组 **tickets** —— 曳光弹式垂直切片，每个 ticket 声明**阻塞**它的那些 tickets。
+
+## 流程
+
+### 1. 收集上下文
+
+基于对话上下文中已有的内容进行工作。如果用户将某个引用（spec 路径或其他标识）作为参数传入，拉取它并读取其完整内容。
+
+主要输入来源：
+- 如果已有 spec，读取 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` —— 这是 ticket 拆分的首要依据。
+- 读取 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 了解本 change 的架构决策——ticket 不应与已做出的决策冲突。
+- 读取 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 了解本 change 的领域词汇表。
+- 读取 `<Path>{roots.state}/specdev/adr/</Path>` —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状。
+- 读取 `<Path>{roots.state}/specdev/context/</Path>` —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状。
+
+如果尚未有 spec，可以基于对话中的计划或待办列表进行拆分，但优先建议用户先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 产出 spec 以获得更精确的拆分。
+
+**完成标准**：上下文（spec、对话、代码库）已收集，所有必要输入源已读取。
+
+### 2. 探索代码库
+
+如果尚未探索代码库，进行探索以了解代码的当前状态。Ticket 标题和描述应使用项目的领域词汇表，并尊重所涉及区域的 ADR。
+
+寻找预重构（prefactor）的机会，使实现更简单。"让变更变容易，然后做容易的变更。"
+
+具体做法：
+- 识别即将被修改的模块——它们的接口是否清晰？依赖是否合理？
+- 如果某个模块的当前结构会使后续实现变得复杂，先提出一个重构 ticket，放在功能 tickets 之前。
+- 预重构必须独立有价值——不是为了"更干净"而重构，而是为了"让后续变更更安全/更简单"。
+
+**完成标准**：代码库已探索，预重构机会已识别，领域词汇表和 ADR 已纳入考量。
+
+### 3. 草拟垂直切片
+
+将工作拆分为**曳光弹** tickets。每个切片横向切穿每一层（schema、API、UI、测试），是一条窄但**完整**的路径——是垂直切片，不是某一层的水平切片。
+
+垂直切片规则：
+- 一个完成的切片可以独立演示或验证——用户可以感知到它交付的行为
+- 每个切片的大小适配单个全新上下文窗口——一个 agent 会话可以在不间断的情况下完成它
+- 任何预重构应最先完成——它们解除后续 tickets 的阻塞
+
+为每个 ticket 标注其**阻塞边** —— 即必须在它开始之前完成的其他 tickets。没有阻塞边的 ticket 可以立即开始。
+
+**宽重构是垂直切片的例外。** **宽重构**是指一个机械性变更 —— 重命名字段、修改共享符号的类型 —— 其**影响范围**辐射整个代码库，因此单次编辑会破坏数千个调用点，任何垂直切片都无法以绿色状态落地。不要强行将其塞入曳光弹；应将其排序为**扩展-收缩**序列：
+
+1. **扩展**：在旧形式旁边添加新形式，使一切不中断。旧代码仍然工作，新代码可用但尚未被调用。
+2. **分批迁移调用点**：按影响范围分批（按包、按目录），每批是一个由扩展阶段阻塞的独立 ticket。保持 CI 逐批绿色，因为旧形式仍然存在。
+3. **收缩**：当没有调用方残留时删除旧形式，由一个由所有迁移批次阻塞的 ticket 负责。
+
+当连批次本身都无法独立保持绿色时，保持排序不变，但让它们共享一个集成分支，所有批次共同阻塞一个最终的集成验证 ticket —— 绿色仅在该处得到承诺。
+
+**完成标准**：曳光弹式垂直切片已草拟，每个 ticket 的阻塞边已标注。
+
+### 4. 与用户核对
+
+以编号列表形式呈现提议的拆分方案。对于每个 ticket，展示：
+
+- **标题**：简短的描述性名称
+- **被阻塞于**：必须首先完成的其他 tickets（如有），或"无 —— 可立即开始"
+- **它交付什么**：此 ticket 使哪些端到端行为可用，从用户视角描述
+
+询问用户：
+
+- 粒度是否合适？（太粗 —— 一个 ticket 内塞了太多决策，难以在一个会话内完成；太细 —— ticket 之间没有实质性行为差异）
+- 阻塞边是否正确 —— 每个 ticket 是否只依赖于真正阻碍它的 tickets？是否有不必要的阻塞关系？
+- 是否有 tickets 应合并或进一步拆分？
+
+迭代直到用户批准拆分方案。每次修改后重新展示完整列表。
+
+**完成标准**：用户已确认粒度、阻塞边与合并/拆分方案。批准后，tickets 将写入 `ticket/` 目录（一个 ticket 一个独立文件，命名为 `#NN-<name>.md`），并生成 `tickets-map.md` 作为总体地图和执行清单。
+
+### 5. 发布
+
+将已批准的 tickets 写入变更目录，**每个 ticket 一个独立文件**，并生成总体地图文件。按以下三步执行：
+
+**5a. 创建 ticket 目录**
+
+创建 `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` 目录。
+
+**5b. 写入单个 ticket 文件**
+
+按依赖顺序（无阻塞者在前，被阻塞者在后），为每个 ticket 创建独立文件 `<Path>{roots.state}/specdev/changes/{change}/ticket/#NN-<ticket-name>.md</Path>`。`#NN` 为 ticket 编号（`#01`, `#02`, ..., `#10`, ...），代表执行顺序。
+
+每个 ticket 文件按以下模板填写：
+
+```markdown
+# Ticket #NN: <标题>
+
+- **被阻塞于：** `./ticket/#NN-<name>.md`, `./ticket/#NN-<name>.md`（相对路径，或多个用逗号分隔。无阻塞则写"无 —— 可立即开始"。查看被引用 ticket 文件中的状态字段自行判断是否已就绪）
+- **状态：** 未开始
+
+<!-- 如需了解整体上下文、所有 ticket 的依赖关系全景或横切关注点，请查看 `../tickets-map.md`。 -->
+
+## 战略与背景
+
+<!-- [必填] 本 ticket 的战略上下文。改编自 issues-slices.md §0。 -->
+
+- **本 ticket 战略**：一句话——本 ticket 做什么 + 为什么 + 以什么为基础（新建/复用现有模块）
+- **与该 ticket 相关的已确认决策**：逐条列出与本 ticket 范围相关的已拍板决策（从 ADR、spec 或对话中提取），防止实现时重新扯皮
+- **与该 ticket 相关的当前现状**：逐条列出与本 ticket 相关的、与需求不符的现有代码/行为。格式：`文件路径:行号范围` + 当前行为 + 为何不满足需求。行号为近似值，实施时以现场代码为准
+- **该 ticket 的预期产出**：完成后可观察到的行为变化
+
+## 范围边界
+
+| IN（本 ticket 构建） | REUSE（复用现有，不改动） | OUT（本 ticket 明确不做） |
+|---------------------|-------------------------|-------------------------|
+| ...                 | ...                     | ...                     |
+
+## 要构建什么
+
+<从用户视角描述此 ticket 交付的端到端行为。用户能做什么、看到什么变化。不是逐层实现清单。一到三段。>
+
+## 交付物
+
+<!-- 本 ticket 产出的文件/模块/功能。新增文件标 **新增**，重度重构标 **重构**。 -->
+
+- **新增** path/to/new.ts —— 描述
+- 修改 path/to/existing.ts —— 改动内容
+
+## 需阅读的文件
+
+<!-- 可选：仅当 ticket 涉及非显而易见的代码区域时填写。简单 ticket 可省略整个小节。 -->
+
+| 文件 | 目的 |
+|------|------|
+| path | 为何需要阅读 |
+
+## 保留/不动
+
+<!-- 本 ticket 绝对不能碰的代码、契约或数据。无则写"无"。 -->
+
+## 实现要点
+
+<!-- 可选：3-7 条关键技术决策。简单 ticket 可省略整个小节。 -->
+
+1. 关键技术点
+2. 关键技术点
+
+## 验收标准
+
+- [ ] 可验证的验收条件
+- [ ] 可验证的验收条件
+```
+
+**模板填写说明：**
+
+- **被阻塞于**使用指向 `./ticket/` 目录的相对路径（如 `./ticket/#01-auth.md`），多个用逗号分隔。执行者应自行打开被引用的 ticket 文件查看其状态字段，判断阻塞是否已解除
+- **状态**初始固定为"未开始"；实现者开始工作时改为"进行中"，完成后改为"已完成"
+- **战略与背景**是必填段——为执行者提供该 ticket 的决策锚点和当前现状。从 spec、ADR、对话中提取，不确定的标记 `[待确认]`
+- **范围边界**是必填段——明确本 ticket 的 IN/REUSE/OUT 三列，防止范围蔓延。OUT 列吸收"明确不做"的内容
+- **交付物**列出本 ticket 产出的具体文件——新增标 **新增**，修改不标，重构标 **重构**。让执行者明确知道要动哪些文件
+- **需阅读的文件**仅在涉及非显而易见的代码区域时填写——告诉执行者上下文边界
+- **保留/不动**是本 ticket 的安全边界——显式列出不能碰的代码/契约/数据。无则写"无"
+- **实现要点**仅在 ticket 涉及有意义的架构决策时填写（3-7 条）。简单 ticket 省略
+- **验收标准**使用 `- [ ]` checklist 格式，每条具体、可独立验证。优先写可执行命令，其次写手动检查步骤
+- 描述统一使用深层模块设计词汇：模块/接口/接缝/适配器，而非组件/服务/边界
+
+避免在 ticket 文件中写入绝对路径或行号承诺 —— 它们会很快过时。例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+
+**5c. 写入 tickets-map.md**
+
+创建 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`，作为所有 ticket 的总体地图和执行看板。
+
+```markdown
+# Tickets Map: <工作简短名称>
+
+<一段话总结所有 ticket 共同构建的内容。如果拆分依据是 spec，引用 spec.md。如果基于对话或计划，说明来源。>
+
+## 执行清单
+
+| 编号 | Ticket | 被阻塞于 | 状态 |
+|------|--------|----------|------|
+| #01 | [ticket-name](./ticket/#01-ticket-name.md) | 无 | 未开始 |
+| #02 | [ticket-name](./ticket/#02-ticket-name.md) | #01 | 未开始 |
+| #10 | [ticket-name](./ticket/#10-ticket-name.md) | #02, #05 | 未开始 |
+
+> 状态枚举：未开始 / 进行中 / 已完成。所有 ticket 发布时初始状态为"未开始"，随实现进度手动更新。
+> **被阻塞于**列填写阻塞本 ticket 的 ticket 编号（如 `#01`、`#02, #05`），执行者需自行打开对应 ticket 文件查看其状态。不可仅凭此表判断——始终以对应 ticket 文件中的状态字段为准。
+
+## 依赖关系
+
+<!-- 用 ASCII 树形图展示 ticket 之间的阻塞关系。 -->
+
+```
+#01-<name>          ← 无阻塞，可立即开始
+  ├── #02-<name>    ← 阻塞于 #01
+  └── #03-<name>    ← 阻塞于 #01
+        └── #04-<name>  ← 阻塞于 #03
+```
+
+## 横切关注点
+
+<!-- 跨多个 ticket 的规则与约束。仅在有实际内容时填写，无则省略整个小节。 -->
+
+- **数据安全铁律**：<冻结的常量、不可改的 wire-format、持久化格式>
+- **契约先行**：<跨 ticket 的 schema/API 变更顺序约束>
+- **行号现场核对**：所有文件路径和行号为近似，实施时以现场代码为准。
+
+## 阻塞关系说明
+
+<!-- 依赖图的文字说明。简单线性链可省略整个小节。对于扩展-收缩模式，解释三阶段。 -->
+
+<描述为何 ticket #B 被 ticket #A 阻塞。扩展-收缩模式：扩展阶段创建新形式 → 迁移批次逐步切换调用点 → 收缩阶段删除旧形式。>
+
+## 风险与注意事项
+
+<!-- 跨 ticket 的风险、回滚考虑。无可省略整个小节。 -->
+```
+
+**tickets-map.md 填写说明：**
+
+- **执行清单**的 Ticket 列使用指向 `./ticket/` 目录的相对链接（含 `#` 编号前缀），可在 markdown 渲染器中直接点击跳转
+- **编号**列使用 `#01`、`#02`、`#10` 格式（`#` + 零填充序号），代表依赖顺序
+- **被阻塞于**列填写阻塞者的编号（如 `#01`、`#02, #05`），执行者需自行查看对应 ticket 文件的状态字段确认是否已就绪
+- **状态**列由 T-tickets 初始化为"未开始"，后续由实现者手动更新——始终以对应 ticket 文件中的状态字段为权威来源
+- **依赖关系**用 ASCII 树形图直观展示阻塞链；纯线性链用缩进列表即可
+- **横切关注点**只放跨 ticket 的规则——单 ticket 的规则留在该 ticket 文件内
+- **阻塞关系说明**在依赖图非平凡时补充文字解释，特别是扩展-收缩排序的三阶段
+
+**完成标准**：`ticket/` 目录已创建，所有 ticket 独立文件已按依赖顺序写入（命名为 `#NN-<ticket-name>.md`）；`tickets-map.md` 已写入——包含总体摘要、执行清单（编号、ticket 链接、被阻塞于、状态四列，初始均为"未开始"）、依赖关系图和横切关注点；每个 ticket 声明阻塞边（使用相对路径）、战略与背景、范围边界、交付物、保留/不动和验收标准。
+
+## 子文件引用
+
+本入口为单文件 work，所有内容均已内联。以下引用供其他 work 读取产物：
+
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` —— 总体地图与执行清单（编号 | Ticket | 被阻塞于 | 状态）
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` —— 独立 ticket 文件目录，每个文件命名为 `#NN-<ticket-name>.md`（`#NN` = `#01`, `#02`, ..., `#10`, ...）
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` —— 上游 spec（拆分依据）
+- `<Path>{roots.state}/specdev/adr/</Path>` —— 永久架构决策目录（已确认并提升的 ADR）
+- `<Path>{roots.state}/specdev/context/</Path>` —— 永久领域词汇表目录（已确认并提升的 CONTEXT）

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

@@ -0,0 +1,209 @@
+---
+id: specdev/wayfinder
+type: workflow-entry
+workflow: specdev
+name: 寻路
+description: 为超出单次会话容量的大块工作绘制共享地图，逐个解决调查 tickets 直到通往目标的路径清晰可见。支持研究和决策型 ticket 类型。
+keywords: [寻路, 地图, 探索, 规划, 战争迷雾, 调研]
+---
+
+# 寻路
+
+一个模糊的想法出现了 —— 太大而无法放入单个 agent 会话，且笼罩在迷雾中：从当前状态到**目标**的路径尚不可见。寻路（Wayfinding）就是找到那条路，而非冲向目标。此 work 在变更目录中绘制路径作为一张**共享地图**，然后逐个处理其 tickets，直到路径变得清晰。
+
+目标因工作而异，命名目标是绘制地图的第一步 —— 它塑造每个 ticket。目标可能是一份待移交和迭代的 spec、一个在规划开始前需锁定的决策、或是一个原地完成的变更（如数据结构迁移）。地图是领域无关的 —— 工程工作、课程内容，任何符合此形态的内容都可以。
+
+## 规划，而非执行
+
+Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图完成时路径就清晰了 —— 在某人动手做事之前没有任何剩余的决策。想要直接动手做事的冲动通常就是信号，表明你已经到达地图的边缘，是时候移交了。一项工作可以通过其 **Notes** 覆盖此行为 —— 将执行带入地图本身 —— 但如果没有明确说明，产出决策，而非可交付成果。
+
+## 用名称引用
+
+每张地图和每个 ticket 都有其**名称** —— 即其标题或标识。在人类阅读的所有内容中 —— 叙述、地图的 Decisions-so-far —— 使用名称引用它，绝不使用裸 ID、编号或 slug。一堵 `#42, #43, #44` 的墙是难以阅读的；名称可以一目了然。引用标记不会消失 —— 名称包裹着其引用 —— 但它们在名称*内部*，绝不是名称的替代品。
+
+在本地 markdown 地图中，使用 Markdown 链接 `[ticket 标题](#ticket-标题)` 进行引用。已解决的 tickets 在地图的 Decisions-so-far 中以 `- [ticket 标题] —— 答案概括` 形式索引。
+
+## 地图
+
+地图是变更目录下的单个 markdown 文件 `<Path>{roots.state}/specdev/changes/{change}/map.md</Path>`，是规范的产物。其 tickets 是地图内的 task list items（`- [ ]` 格式）。如果工作范围跨多个变更，地图位于主变更目录下。
+
+地图是一个**索引**，而非存储。它列出已做出的决策并指向持有其详细信息的 tickets；一个决策只存在于一个地方 —— 其 ticket —— 因此地图从不重述，仅概括并链接。
+
+**地图物理结构：** 地图文件本身是 markdown 文件。Tickets 是地图文件内的编号 task list items，而非外部 issues。每个 ticket 拥有一个独立的 markdown 小节，包含标题、类型标签、问题和答案。状态通过 checkbox 标记追踪（`- [ ]` 开放，`- [x]` 已解决）。阻塞关系通过"被阻塞于"字段声明，以 ticket 标题引用。
+
+**前沿查询：** 前沿上的 tickets 是指：checkbox 未勾选（开放）、其"被阻塞于"中列出的所有 tickets 均已勾选（无阻塞）、且尚未被领取的 tickets。Agent 通过阅读地图文件本身即可识别前沿。
+
+**领取机制：** 当一个 agent 会话开始处理某个 ticket 时，它应在 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组中记录当前处理的 ticket 名称，以便并发会话跳过它。处理完成后从 `active` 中移除。`active` 中存在记录即为领取标记。
+
+### 地图正文
+
+整个地图的低分辨率视图，每个会话加载一次。开放的 tickets **不**在此处列出 —— 它们直接作为地图文件中的未勾选小节存在。
+
+```markdown
+# 地图：<工作名称>
+
+## 目的地
+
+<到达此地图终点时的样子 —— 此工作正在寻路的 spec、决策或变更。一到两行；每个会话在挑选 ticket 之前以其为定位。>
+
+## 说明
+
+<领域；每个会话应咨询的技能；此工作的常设偏好>
+
+## 已做出的决策
+
+<!-- 索引 —— 每个已关闭 ticket 一行：足以判断相关性，然后跳转到对应小节查看详细信息 -->
+
+- [<已关闭 ticket 标题>](#ticket-标题) —— <答案的一句话概括>
+
+## 尚未明确
+
+<!-- 参见"战争迷雾"：范围内但你尚无法做成 ticket 的迷雾；随着前沿推进而升级 -->
+
+## 超出范围
+
+<!-- 参见"超出范围"：被裁定在目标之外的工作；已关闭，永不升级 -->
+```
+
+### Tickets
+
+每个 ticket 是地图文件内的一个小节，其正文是问题，大小适配一个 100K token 的 agent 会话。Tickets 按创建顺序编号。
+
+```markdown
+## <编号>. <Ticket 标题>  `[<类型>]` `[<HITL|AFK>]`
+
+**类型：** <research | prototype | grilling | task>
+
+**交互模式：** <HITL | AFK> —— <简要说明为何是此模式>
+
+**状态：** < - [ ] 开放 | - [x] 已解决 >
+
+**被阻塞于：** <阻塞此 ticket 的 ticket 标题列表，或"无 —— 可立即开始">
+
+### 问题
+
+<此 ticket 要解决的决策或调查>
+
+### 答案
+
+<!-- 解决时填写 —— 答案的完整记录。以下仅在 ticket 已解决时出现：-->
+
+<解决此 ticket 时记录的内容。对于 research：发现的摘要和链接资产。对于 prototype：原型的描述和链接。对于 grilling：访谈达成的共识。对于 task：已完成的工作和结果性事实。>
+```
+
+每个 ticket 携带一个类型标签 —— 以下之一：`research`、`prototype`、`grilling`、`task`（参见下方 [Ticket 类型](#ticket-类型)）。
+
+**领取机制：** 一个会话通过将其名称写入 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组来**领取**一个 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）：阅读文档、第三方 API 或知识库等本地资源。创建一个 markdown 摘要作为链接资产。当需要当前工作目录之外的知识时使用。
+- **Prototype**（HITL）：通过制作一个廉价、粗糙、具体的产物来提高讨论的保真度 —— 大纲、粗略尝试、桩代码、或 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，或零个。
+
+**尚未明确**排除已决策的内容（Decisions-so-far）、已有的活跃 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>`，填写 Destination 和 Notes，Decisions-so-far 为空，迷雾草拟进**尚未明确**。
+
+   **完成标准**：地图文件已创建，Destination、Notes、尚未明确、超出范围均已填写。
+
+4. **创建你现在能明确的 tickets** 作为地图文件内的小节 —— 然后在**第二遍**中连接阻塞边（tickets 需要首先有标题才能相互引用）。连接关系将它们排序为前沿和被阻塞；你尚无法明确的都在迷雾中 —— **尚未明确**章节。
+
+   **完成标准**：所有可明确的 tickets 已创建并连接阻塞边；迷雾已归入尚未明确。
+
+5. **停止** —— 绘制地图是一个会话的工作；不要同时解决 tickets。
+
+### 遍历地图
+
+用户带着一张地图（变更目录或 map.md 路径）调用。Ticket 是**可选的** —— 不提供时，你选择下一个决策，而非用户。
+
+1. **加载地图** —— 低分辨率视图（Destination、Notes、Decisions-so-far、尚未明确、超出范围），而非每个 ticket 的完整正文。
+
+   **完成标准**：地图的低分辨率视图已加载，当前状态已理解。
+
+2. **选择 ticket。** 如果用户指定了一个，使用它。否则按顺序选择第一个前沿 ticket（开放、未被阻塞、未被领取）。**领取它**：在任何工作之前将 ticket 名称写入 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组。
+
+   **完成标准**：一个前沿 ticket 已被选中并领取。
+
+3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 Notes 块中指定的技能。如有疑问，使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 进行访谈。查阅 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型的一致性。
+
+   **完成标准**：ticket 的问题已解决，答案已记录。
+
+4. **记录解决方案：** 在 ticket 的"答案"小节中填写答案，将 checkbox 从 `- [ ]` 改为 `- [x]`，在地图的 Decisions-so-far 中**追加一条上下文指针**：`- [ticket 标题] —— 答案的一句话概括`。从 `<Path>{roots.state}/specdev/status.json</Path>` 的 `active` 数组中移除该 ticket。
+
+   **完成标准**：ticket checkbox 已勾选，Decisions-so-far 已更新，active 数组已清理。
+
+5. **添加新浮现的 tickets** 作为地图文件内新的小节（先创建再连接阻塞边）；升级答案使任何变得可明确的迷雾，从**尚未明确**中清除每个已升级的补丁，使其仅以其新 ticket 的形式存在。如果答案揭示某个 ticket —— 这个或其他 —— 位于目标之外，**将其裁定为超出范围**而非在路径上解决它。如果该决策使地图的其他部分无效，更新或删除这些 tickets（勾选并注明无效原因）。
+
+   **完成标准**：新浮现的 tickets 已添加，迷雾已升级或清除，超出范围的 tickets 已裁定。
+
+用户可以并行运行未被阻塞的 tickets，因此需预期其他会话会并发编辑地图文件和 status.json。
+
+### 完成
+
+当所有 tickets 已关闭（勾选）、迷雾已清空（尚未明确为空或仅剩无法继续分解的模糊项）、且通往目标的路径已清晰时，地图完成。向用户汇报：
+
+- 目的地是否已可抵达——路径上的每个步骤是否都已有明确的 ticket 或决策
+- Decisions-so-far 中的关键结论摘要
+- 剩余的任何**尚未明确**项——它们是否阻碍行动，还是可作为实现细节处理
+- 建议的下一步行动（移交实现、开始执行、或重新划定目标）
+
+**完成标准**：前沿已清空——无开放 tickets、无残留迷雾、通往目标的路径清晰。完成汇报已向用户呈现。
+
+---
+
+## 子文件引用
+
+本入口为单文件 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` 数组记录当前领取的 ticket

package/template/workflows/{matt-pocock → specdev}/_state/status.json

@@ -1,5 +1,5 @@
 {
   "schema_version": 1,
-  "workflow": "matt-pocock",
+  "workflow": "specdev",
   "active": []
 }

package/template/commands/finalize.md

@@ -1,37 +0,0 @@
----
-id: finalize
-type: command
-name: Finalize
-description: 对任意 workflow change 执行完成门禁、状态收尾与安全归档，也可批量归档已完成 change
-keywords: [finalize, verify, complete, archive, 收尾]
----
-
-# Finalize 命令
-
-## 报告
-
-统一写入：`speculo/.speculo/commands/finalize/<YYYY-MM-DD>-<scope>-<topic>[-NN].md`。
-
-报告必须记录 `mode`、选中的 workflow/change、验证证据、状态变化、源路径、目标路径、用户确认和最终结果。
-
-## 模式
-
-### finalize-active
-
-1. 读取 `../skills/runtime-context/SKILL.md` 和 `../skills/change-lifecycle/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级）和 workflow 的固定 `changes/archive` 根。
-2. 选择一个 active change，执行新鲜验证、需求核对和 worktree 预检；缺证据即 blocked。
-3. 展示验证证据、状态变化、归档目标和报告路径，等待用户明确确认。
-4. 确认后将 change 置为 completed，再移动到 archive，更新 `status.json#active`，复查目标和索引。
-
-### archive-completed
-
-1. 选择 workflow 或 `multi-workflow` 范围，扫描所有 completed change；不重新验证，也不接受 active/broken change。
-2. 读取 `change-lifecycle` 的归档安全规则，生成逐项源/目标/冲突清单。
-3. 先展示批量计划并等待用户确认；冲突、malformed 或缺状态任一存在即停止整批动作。
-4. 确认后逐项移动、更新 `change_status: archived` 和各 workflow 索引；失败时报告已完成/未完成清单。
-
-## 完成标准
-
-- 报告文件位于 command 专属目录且 scope 可从文件名判断。
-- 所有状态、目录和索引变更均已重新读取验证。
-- 未确认或 blocked 时没有移动、删除或宣称完成。

package/template/commands/knowledge-prune.md

@@ -1,20 +0,0 @@
----
-id: knowledge-prune
-type: command
-name: Knowledge Prune
-description: dry-run 审计指定 workflow 声明的知识 namespace，生成可删除、合并或改写的候选清单
-keywords: [knowledge, prune, rules, lessons, context, adr]
----
-
-# Knowledge Prune 命令
-
-## 报告
-
-写入 `speculo/.speculo/commands/knowledge-prune/<YYYY-MM-DD>-<workflow>-<topic>[-NN].md`。报告记录扫描 namespace、证据、候选分组、风险和确认结果。
-
-## 执行
-
-1. 读取 `../skills/runtime-context/SKILL.md`，解析 `speculo/config.json`（不存在时以默认值静默降级），选择 workflow 并解析其 `PERSISTENCE.md` 声明的 knowledge/policy namespace。
-2. 读取 `../skills/knowledge-prune/SKILL.md`，默认执行 dry-run，生成 `delete | merge | rewrite | keep | needs-confirmation` 清单。
-3. 将报告写入 command 专属目录；无用户确认时不删除、重命名或改写任何 namespace。
-4. 用户确认后再次执行路径包含检查，逐项操作并复查 git、引用和报告结果。

package/template/skills/change-lifecycle/SKILL.md

@@ -1,25 +0,0 @@
----
-id: change-lifecycle
-type: skill
-name: Change Lifecycle
-description: 验证、完成和归档任意 Speculo workflow change，返回可确认的状态与目录移动计划。
----
-
-# Change Lifecycle
-
-## 输入
-
-- `runtime-context` 返回的 workflow、state、changes、archive 和可选 change 根。
-- `mode: finalize-active | archive-completed`。
-- 当前 route/phase 完成准则、change 状态与可选 worktree 状态。
-
-## 流程
-
-1. `finalize-active` 按 `references/completion-gate.md` 收集新鲜证据；任一关键结论缺证据即返回 blocked。
-2. 两种模式均按 `references/finalize-archive.md` 验证名称、状态、索引和目标冲突。
-3. 返回状态修改、移动、索引更新和可选 worktree 清理计划，等待调用方取得用户确认。
-4. 调用方执行后重新读取源、目标、change 状态和 workflow 索引；存在部分完成即返回 blocked。
-
-完成标准：返回 `verified | blocked | archived` 中唯一裁决及完整证据；本 skill 未自行持久化或执行未确认的破坏性动作。
-
-报告模板见 `assets/completion-verification-template.md` 与 `assets/completion-summary-template.md`。

package/template/skills/change-lifecycle/assets/completion-summary-template.md

@@ -1,25 +0,0 @@
-> **服务命令：** `../../../commands/finalize.md`
-> **产物文件名：** `completion-summary.md`
-> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
-
-# Completion Summary
-
-## 交付边界
-
-[TODO: 本 change 交付了什么、不含什么。]
-
-## 关键变更
-
-[TODO: 用 3-6 条概括主要变更。]
-
-## 验证证据
-
-[TODO: 指向 `completion-verification.md` 的关键结论与命令证据。]
-
-## 遗留事项
-
-[TODO: 已知遗留、后续建议或转交的工作；无则写"无"。]
-
-## 归档记录
-
-[TODO: 归档时间、源路径 → `speculo/.speculo/<workflow>/archive/<YYYY-MM>/<change>/`、用户确认记录。]

package/template/skills/change-lifecycle/assets/completion-verification-template.md

@@ -1,29 +0,0 @@
-> **服务命令：** `../../../commands/finalize.md`
-> **产物文件名：** `completion-verification.md`
-> **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
-
-# Completion Verification
-
-## 已运行命令（含证据）
-
-[TODO: 逐条记录本次运行的验证命令、退出码、通过/失败计数；无证据不得声称通过。]
-
-## 未运行命令
-
-[TODO: 列出相关但未运行的命令及原因；对应结论不得声称通过。]
-
-## 需求逐项核对
-
-[TODO: 重读来源，逐项列出需求 + satisfied/missing/partial + 来源引用。]
-
-## 回归证据（如适用）
-
-[TODO: 记录红-绿循环验证；无 bug 修复可写 N/A。]
-
-## 调试残留检查
-
-[TODO: 临时日志、DEBUG 标记、一次性脚本、推测性功能的清理结果。]
-
-## 验证结论
-
-[TODO: verified 或 blocked；blocked 时写明实际状态与缺口。]

package/template/skills/change-lifecycle/references/completion-gate.md

@@ -1,19 +0,0 @@
-# Completion Verification
-
-本门控只服务 `finalize-active`。没有本次运行的新鲜证据时返回 blocked。
-
-## 输入与产物
-
-- 输入：当前 change 产物、route/phase 完成准则、需求来源、VCS diff 和项目验证命令。
-- 产物：当前 change 下的 `completion-verification.md`，使用 `../assets/completion-verification-template.md`。
-
-## 门控
-
-1. 运行相关测试、类型检查、lint 和构建，逐条记录命令、退出码与通过/失败计数。
-2. 重读 PRD、issue、spec 或用户任务，逐项标记 `satisfied | missing | partial` 并引用来源。
-3. Bug 修复确认回归测试经过红、绿、回退修复再红、恢复再绿；无法证明时记录缺口。
-4. 子代理参与时以 VCS diff 和实际文件为证据，不使用代理自报结论。
-5. 搜索调试日志、一次性脚本、DEBUG 标记和未启用功能，清理或记录阻塞。
-6. 全部关键项有证据时写 `verification_status: verified`，否则写 `blocked` 并停止归档。
-
-完成标准：需求清单与每项结论均有新鲜证据，产物无 `[TODO:]`，change 状态已记录验证命令、需求清单和裁决。