@namewta/speculo 0.2.6 → 0.2.9

package/template/workflows/specdev/P-goal-plan/vision-sections.md

@@ -0,0 +1,80 @@
+# 远景章节 §1-3 编写规程
+
+编写 goal-plan 的前三个章节——定义"做什么"和"怎么算做完"。逐节草拟，每节经用户确认后再进入下一节。不一口气抛出全部三节。
+
+## §1 — Goal
+
+### 五要素公式
+
+从 spec.md 的 Problem Statement 和 Solution 段落提取，合成一段密集声明，包含五个要素：
+
+1. **构建什么**（what）——从 spec.md Solution 的第一句提炼
+2. **不可协商的约束**（constraints）——从 ADR.md 架构决策中提取，至少一条
+3. **具体交付物**（deliverable）——ticket 数量 + issue 范围（如 "#18-#38，共 21 个 issues"）
+4. **质量标杆**（quality bar）——如果激活参考权威模式，声明与参考权威的对应关系（如"与 openhanako 手感一致"）；否则从 spec.md 的 Test Decisions 提取
+5. **反模式**（anti-pattern）——声明禁止的伪完成（如"能力存在但手感不像 X"）
+
+### 编写规则
+
+- 一段写到底，不分点、不用列表
+- 每个要素是可检查的声明，不是模糊愿望
+- 反模式必须具体到可识别——禁止"代码写完但交互细节不匹配"
+
+### 草拟与确认
+
+先输出 §1 草案，等待用户确认。确认后进入 §2。
+
+## §2 — Authoritative Inputs
+
+### 优先级表
+
+构建一张三列表格：优先级 | 文件路径 | 角色说明。行按优先级降序排列。
+
+按检测到的模式逐行添加：
+
+1. **合同行**（如激活合同模式）——优先级 1，路径指向合同文档，角色："冻结合同——含编号验收条目，先于所有其他参考"
+2. **参考权威行**（如激活参考权威模式）——优先级 2，路径指向参考快照，角色："UX 真理——冻结快照，不随上游漂移。手感比对基准"
+3. **ADR 行**——从 ADR.md 和永久 ADR 目录（`<Path>{roots.state}/specdev/adr/</Path>`）提取，每份一个行，优先级按 ADR 编号
+4. **领域文档行**——从 CONTEXT.md 提取，每份一个行，角色："领域词汇表——术语定义和弃用同义词的权威来源"
+5. **Spec/Ticket 行**——spec.md 和 tickets-map.md，优先级最低
+
+### 冲突裁决顺序
+
+从 input-validation.md 的推导结果复制，写为编号列表。
+
+### 锁定产品裁定
+
+从 ADR.md 的架构决策和 spec.md 的 Implementation Decisions 中提取不可推翻的裁定。每条裁定写为一句声明，标注来源（ADR 编号或 Issue 编号）。
+
+- 裁定必须是已做出且不可推翻的——只提取 ADR 中标记为"决定"状态的条目
+- 如果激活偏差模式，在此声明偏差编号和每条偏差的理由
+
+### 草拟与确认
+
+先输出 §2 完整草案（优先级表 + 冲突顺序 + 锁定裁定），等待用户确认。确认后进入 §3。
+
+## §3 — Definition of Done
+
+### 六道门禁骨架
+
+逐道门禁填空，每道门禁写为一条可客观验证的全部或无声明：
+
+1. **Issue 全绿**——填写 ticket 数量和仓库引用。格式：「所有 <N> 个 issues 全部关闭，每个 issue 的 checklist 全部勾选为 [x]」
+2. **合同/ADR 状态收敛**——如果激活合同模式：填写合同文档名和待验收条目数。格式：「`<合同>` 中所有 <P0|P1|P2> 条目状态非 `todo`——`done` 或 `deviate`（有记录理由）」；如果无合同：填写 ADR 编号。格式：「ADR-<NNNN> 状态保持 `accepted`，偏差表条目已解决或明确记录为 `deviate`」
+3. **验证门禁绿**——从 spec.md 的 Test Decisions 提取验证命令。格式：「`<verify_cmd>` 全绿」
+4. **架构不回退**——填写 lint 和类型检查。格式：「无架构退化——<lint rules>」
+5. **已锁裁定不松动**——引用 §2 的锁定产品裁定。格式：「§2 的 <N> 条锁定产品裁定全部满足，无静默推翻」
+6. **可追溯**——填写 commit 到 issue 的链接要求。格式：「每个关闭的 issue 包含实现 commit 引用和验证截图/日志」
+
+### 填充规则
+
+- ticket 数量从 tickets-map.md 统计
+- 合同条目从合同文档的表格行计数
+- verify 命令从 spec.md Test Decisions 提取，如无则使用 `pnpm verify`
+- 锁定裁定数量从 §2 提取
+
+### 草拟与确认
+
+输出 §3 完整草案，等待用户确认。
+
+**完成标准**：§1 目标声明五要素齐全且经用户确认；§2 优先级表、冲突裁决顺序、锁定裁定完整且经用户确认；§3 六道门禁全部填充为可客观验证的声明且经用户确认。

package/template/workflows/specdev/S-spec/S-spec.md

@@ -23,6 +23,8 @@ keywords: [spec, 规范, 需求, PRD, 用户故事]
 
 `{change}` 为当前活跃变更的目录名，格式为 `<YYYY-MM-DD>-<topic>`。如果尚未创建变更目录，先运行 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 的启动变更阶段初始化 CONTEXT.md 和 ADR.md。
 
+若代码库探索中遇到不熟悉的模块、外部依赖、第三方 SDK 或技术领域，调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 进行针对性调查——了解其设计意图、API 契约和行为特征——再基于完整理解撰写 spec。
+
 **完成标准**：代码库当前状态已理解，领域词汇表和 ADR 已纳入考量。
 
 ### 2. 草拟接缝

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

@@ -39,6 +39,8 @@ keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
 - 如果某个模块的当前结构会使后续实现变得复杂，先提出一个重构 ticket，放在功能 tickets 之前。
 - 预重构必须独立有价值——不是为了"更干净"而重构，而是为了"让后续变更更安全/更简单"。
 
+若探索中遇到不熟悉的模块、外部依赖或第三方库——其接口设计意图和行为特征尚不明确——调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成探查后再继续识别预重构机会。
+
 **完成标准**：代码库已探索，预重构机会已识别，领域词汇表和 ADR 已纳入考量。
 
 ### 3. 草拟垂直切片
@@ -170,72 +172,37 @@ keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
 
 **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
-```
+创建 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`，作为所有 ticket 的总体地图和执行看板。格式遵循权威模板 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`——加载该模板获取完整的节结构、表格列定义和填写约定。
 
-## 横切关注点
-
-<!-- 跨多个 ticket 的规则与约束。仅在有实际内容时填写，无则省略整个小节。 -->
-
-- **数据安全铁律**：<冻结的常量、不可改的 wire-format、持久化格式>
-- **契约先行**：<跨 ticket 的 schema/API 变更顺序约束>
-- **行号现场核对**：所有文件路径和行号为近似，实施时以现场代码为准。
-
-## 阻塞关系说明
-
-<!-- 依赖图的文字说明。简单线性链可省略整个小节。对于扩展-收缩模式，解释三阶段。 -->
-
-<描述为何 ticket #B 被 ticket #A 阻塞。扩展-收缩模式：扩展阶段创建新形式 → 迁移批次逐步切换调用点 → 收缩阶段删除旧形式。>
-
-## 风险与注意事项
-
-<!-- 跨 ticket 的风险、回滚考虑。无可省略整个小节。 -->
-```
+T-tickets 阶段填写的列：**编号**、**Ticket**、**被阻塞于**、**状态**（初始"未开始"）。**Gate** 和 **Contract ID** 列暂留空或标注 `[待标注]`——由后续 P-goal-plan 在标注门禁层级时填充。**依赖关系**节写入基础 ASCII 树形图（阻塞链），后续 P-goal-plan 在此基础上叠加门禁边界（`--- P0 gate ---`）、就绪标记 `[READY]` 和扇出标记 `[FAN-OUT: N路并行]`。**并行规则**节按模板保留——T-tickets 阶段写入规则文本，P-goal-plan 阶段可调整并发数。
 
 **tickets-map.md 填写说明：**
 
-- **执行清单**的 Ticket 列使用指向 `./ticket/` 目录的相对链接（含 `#` 编号前缀），可在 markdown 渲染器中直接点击跳转
+- **执行清单**的 Ticket 列使用指向 `./ticket/` 目录的相对链接（含 `#` 编号前缀）
 - **编号**列使用 `#01`、`#02`、`#10` 格式（`#` + 零填充序号），代表依赖顺序
-- **被阻塞于**列填写阻塞者的编号（如 `#01`、`#02, #05`），执行者需自行查看对应 ticket 文件的状态字段确认是否已就绪
+- **被阻塞于**列填写阻塞者的编号（如 `#01`、`#02, #05`）
 - **状态**列由 T-tickets 初始化为"未开始"，后续由实现者手动更新——始终以对应 ticket 文件中的状态字段为权威来源
-- **依赖关系**用 ASCII 树形图直观展示阻塞链；纯线性链用缩进列表即可
+- **Gate** 列（P0/P1/P2）和 **Contract ID** 列由 P-goal-plan 填充；T-tickets 阶段留空或标 `[待标注]`
+- **依赖关系**用 ASCII 树形图展示阻塞链——T-tickets 写入基础结构，P-goal-plan 叠加门禁标注
 - **横切关注点**只放跨 ticket 的规则——单 ticket 的规则留在该 ticket 文件内
-- **阻塞关系说明**在依赖图非平凡时补充文字解释，特别是扩展-收缩排序的三阶段
+- **阻塞关系说明**在依赖图非平凡时补充文字解释
 
-**完成标准**：`ticket/` 目录已创建，所有 ticket 独立文件已按依赖顺序写入（命名为 `#NN-<ticket-name>.md`）；`tickets-map.md` 已写入——包含总体摘要、执行清单（编号、ticket 链接、被阻塞于、状态四列，初始均为"未开始"）、依赖关系图和横切关注点；每个 ticket 声明阻塞边（使用相对路径）、战略与背景、范围边界、交付物、保留/不动和验收标准。
+**完成标准**：`ticket/` 目录已创建，所有 ticket 独立文件已按依赖顺序写入（命名为 `#NN-<ticket-name>.md`）；`tickets-map.md` 已按 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 格式写入——包含总体摘要、六列执行清单（Gate 和 Contract ID 列为 `[待标注]`）、基础依赖关系 ASCII 树形图、并行规则和横切关注点；每个 ticket 声明阻塞边、战略与背景、范围边界、交付物、保留/不动和验收标准。
 
 ## 子文件引用
 
-本入口为单文件 work，所有内容均已内联。以下引用供其他 work 读取产物：
+| 文件 | 内容 | 触发条件 |
+|------|------|----------|
+| `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` | tickets-map.md 权威模板——执行清单六列表格、门禁标注 DAG、并行规则、横切关注点 | 进入步骤 5c「写入 tickets-map.md」时加载——T-tickets 按此模板输出基础结构，P-goal-plan 随后标注 Gate、Contract ID 和门禁 DAG |
+
+本入口为单文件 work，所有 ticket 拆分流程内容均已内联。以下引用供其他 work 读取产物：
 
-- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` —— 总体地图与执行清单（编号 | Ticket | 被阻塞于 | 状态）
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` —— 总体地图与执行清单（编号 | Ticket | 被阻塞于 | Gate | Contract ID | 状态），格式遵循 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`
 - `<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）
+
+## 下一步
+
+如果 ticket 数量超过 10 个，建议运行 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 产出目标规划文档，定义里程碑级约束、质量门禁和执行协议，为大规模协调执行做准备。

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

@@ -0,0 +1,70 @@
+# Tickets Map: <工作简短名称>
+
+<一段话总结所有 ticket 共同构建的内容。如果拆分依据是 spec，引用 spec.md。如果基于对话或计划，说明来源。>
+
+## 执行清单
+
+| 编号 | Ticket | 被阻塞于 | Gate | Contract ID | 状态 |
+|------|--------|----------|------|-------------|------|
+| #01 | [ticket-name](./ticket/#01-ticket-name.md) | 无 | P0 | — | 未开始 |
+| #02 | [ticket-name](./ticket/#02-ticket-name.md) | #01 | P1 | P1-03 | 未开始 |
+| #10 | [ticket-name](./ticket/#10-ticket-name.md) | #02, #05 | P2 | — | 未开始 |
+
+> **状态枚举**：未开始 / 进行中 / 已完成。所有 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 填充。
+
+## 依赖关系（门禁标注 DAG）
+
+<!-- 用 ASCII DAG 展示 ticket 之间的阻塞关系和门禁边界。
+     由 T-tickets 写入基础树形结构，由 P-goal-plan 标注门禁层级（P0/P1/P2）、
+     就绪标记 [READY] 和扇出标记 [FAN-OUT: N路并行]。
+
+     绘制约定：
+     - 每行一个 ticket，缩进表示依赖深度
+     - → 表示依赖关系（A → B 表示 B 依赖 A）
+     - 用注释标注门禁边界：--- P0 gate ---
+     - 可立即开始的 ticket 标注 [READY]
+     - 扇出点标注 [FAN-OUT: N路并行]
+
+     示例格式：
+     #01 [READY]  →  #02 [FAN-OUT: 3路并行]
+                          ├→ #03 [P0]
+                          ├→ #04 [P1]
+                          └→ #05 [P1]
+     --- P0 gate ---
+     #03  →  #06 [P1]  →  #07 [P2]
+-->
+
+```
+#01-<name>          ← 无阻塞，可立即开始
+  ├── #02-<name>    ← 阻塞于 #01
+  └── #03-<name>    ← 阻塞于 #01
+        └── #04-<name>  ← 阻塞于 #03
+```
+
+## 并行规则
+
+- 最大 **3** 个并发实现者（ticket 数 > 20 时可调至 4）
+- 并发 ticket 的 file allowlist 必须互不重叠——两两之间无可写文件交集
+- 共享文件（package.json、lockfile、合同文档、IPC 根导出、领域词汇表）仅由 Lead 修改
+- 共享文件修改后，所有并发子代理需在继续前同步
+
+## 横切关注点
+
+<!-- 跨多个 ticket 的规则与约束。仅在有实际内容时填写，无则省略整个小节。 -->
+
+- **数据安全铁律**：<冻结的常量、不可改的 wire-format、持久化格式>
+- **契约先行**：<跨 ticket 的 schema/API 变更顺序约束>
+- **行号现场核对**：所有文件路径和行号为近似，实施时以现场代码为准。
+
+## 阻塞关系说明
+
+<!-- 依赖图的文字说明。简单线性链可省略整个小节。对于扩展-收缩模式，解释三阶段。 -->
+
+<描述为何 ticket #B 被 ticket #A 阻塞。扩展-收缩模式：扩展阶段创建新形式 → 迁移批次逐步切换调用点 → 收缩阶段删除旧形式。>
+
+## 风险与注意事项
+
+<!-- 跨 ticket 的风险、回滚考虑。无可省略整个小节。 -->

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

@@ -103,7 +103,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
 每个 ticket 要么是 **HITL** —— 人在回路中，与一个代表自己发言的人类*一起*工作 —— 要么是 **AFK**，由 agent 独立驱动。HITL ticket 只能通过实时交流来解决；agent 绝不代替人类一方发言（一个自问自答的质询 agent 已经破坏了这一点）。
 
-- **Research**（AFK）：阅读文档、第三方 API 或知识库等本地资源。创建一个 markdown 摘要作为链接资产。当需要当前工作目录之外的知识时使用。
+- **Research**（AFK）：调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 启动后台 Agent 针对一手来源调查问题，在 ticket 的答案中链接研究产出文件。当需要当前工作目录之外的知识时使用。
 - **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、行数）。
@@ -167,7 +167,7 @@ Wayfinder 默认进行**规划**：每个 ticket 解决一个决策，当地图
 
    **完成标准**：一个前沿 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>` 维护领域模型的一致性。
+3. **解决它** —— **按需缩放**：按需拉取任何相关或已关闭 ticket 的完整正文；调用 Notes 块中指定的技能。根据 ticket 类型选择解决方式：**research** ticket 调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>`；**grilling** ticket 使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 进行访谈；**prototype** 和 **task** 按各自问题描述执行。查阅 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` 维护领域模型的一致性。
 
    **完成标准**：ticket 的问题已解决，答案已记录。
 

package/template/workflows/specdev/common/dev-worktree/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: dev-worktree
+description: 在 Speculo workflow change 内创建隔离 git worktree 进行开发，完成后验证测试并合回基础分支。当用户要求隔离开发、开始实现、或实现完成后需要合并/清理时使用。与 specdev workflow 深度集成，worktree 持久化在 change 目录下的 .worktree/ 中。
+---
+
+# Dev Worktree
+
+为当前 workflow change 创建独立 worktree，实现「隔离开发 → 验证 → 合并 → 清理」闭环。
+
+**启动时宣布：** 「正在使用 dev-worktree 技能。」
+
+## 决策树
+
+| 场景 | 入口 |
+|------|------|
+| 要开始实现 / 用户要求隔离 | **阶段 A：创建 worktree** |
+| 已在 worktree 中，开发完成 | **阶段 B：收尾合并** |
+| 已在 worktree 中，未完成 | 继续开发，不重复创建 |
+| 用户要求 PR / 暂存 / 丢弃 | 阶段 B 按对应选项执行 |
+
+---
+
+## 阶段 A：创建 Worktree
+
+详细步骤见 [references/create.md](references/create.md)。核心流程：
+
+### A0. 检测现有隔离
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+SUPER=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+```
+
+- `SUPER` 有值 → submodule 内，按普通仓库处理，不误判
+- `GIT_DIR != GIT_COMMON` 且非 submodule → 已在 worktree，跳到 A3 设置
+- `GIT_DIR == GIT_COMMON` → 主工作区，继续
+
+### A1. 命名与路径
+
+| 要素 | 值 |
+|------|-----|
+| 基础分支 | 当前分支（`git rev-parse --abbrev-ref HEAD`） |
+| change 分支 | `speculo/<workflow>/<change>` |
+| worktree 路径 | `{state-root}/<workflow>/changes/<change>/.worktree/` |
+
+分支或路径已存在 → 停止，不覆盖不复用。
+
+**前置检查：** `speculo/.speculo/` 必须被 git 跟踪——产物需随分支合并。若被忽略则降级为非 worktree 模式。
+
+### A2. 创建
+
+```bash
+git worktree add -b speculo/<workflow>/<change> {state-root}/<workflow>/changes/<change>/.worktree
+```
+
+确保 `.gitignore` 含 `.worktree/`；缺失则追加并提交。
+
+### A3. 项目设置与基线
+
+自动检测并安装依赖、运行基线测试：
+
+```bash
+[ -f package.json ] && (npm install 2>/dev/null || true)
+[ -f Cargo.toml ] && cargo build
+[ -f requirements.txt ] && pip install -r requirements.txt
+[ -f go.mod ] && go mod download
+# 跑基线测试
+```
+
+基线测试失败 → 报告并询问，未获许可不开始实现。
+
+### A4. 写回状态
+
+将 `base_branch`、`change_branch`、`worktree_path`、`worktree_status: active` 写入 change 的 `.status.json`。
+
+---
+
+## 阶段 B：收尾合并
+
+详细步骤见 [references/finalize.md](references/finalize.md)。
+
+### B1. 验证测试
+
+跑项目测试套件。失败 → 停止，禁止合并/PR。
+
+### B2. 展示选项
+
+```
+实现已完成。你想怎么做？
+
+1. 本地合并回 <base-branch>（推荐，默认）
+2. 推送并创建 Pull Request
+3. 保持现状（稍后处理）
+4. 丢弃
+
+选哪个？
+```
+
+分离 HEAD 时移除选项 1。用户未指定时默认选项 1。
+
+### B3. 执行 —— 顺序不可变
+
+**选项 1（本地合并）：**
+1. 合并到 base：`git checkout <base> && git pull && git merge --no-ff <change_branch>`
+2. 在合并结果上再跑测试
+3. 测试通过 → 从主仓库根删除 worktree：`git worktree remove <path>`
+4. 删除分支：`git branch -d <change_branch>`
+5. `git worktree prune`
+6. 更新 `.status.json`：`worktree_status: removed`
+
+**选项 2（PR）：** 推送分支、创建 PR，保留 worktree。
+**选项 3（保持）：** 不动，报告状态。
+**选项 4（丢弃）：** 确认后删除 worktree 和分支。
+
+合并冲突或测试失败 → 停止，保留现场，报告原因，不强推。
+
+---
+
+## 红线
+
+**绝不：**
+- 已在 worktree 时嵌套创建
+- 覆盖已有分支或路径
+- 测试失败时继续合并/PR
+- 合并结果未验证就删 worktree
+- 先删分支再 worktree remove（顺序：merge → remove worktree → delete branch）
+- 在 worktree 内部执行 `git worktree remove`
+- 未经确认执行破坏性操作
+- 强制推送
+
+**始终：**
+- 分支名：`speculo/<workflow>/<change>`
+- worktree 路径：change 目录下的 `.worktree/`
+- 创建后装依赖 + 基线测试
+- 收尾前验证测试
+- 合并成功后再清理
+- 清理后 `git worktree prune`

package/template/workflows/specdev/common/dev-worktree/references/create.md

@@ -0,0 +1,63 @@
+# 创建 Worktree
+
+为当前 workflow change 建立独立 worktree。由 SKILL.md 阶段 A 调用。
+
+## 前置
+
+1. git 仓库内，工作区干净或可接受
+2. `speculo/.speculo/` 被 git 跟踪（change 产物随分支合并回 base）；若被忽略则降级非 worktree 模式
+3. `.gitignore` 含 `.worktree/`；缺失则追加并提交
+
+## 检测已有隔离
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+SUPER=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+```
+
+| 条件 | 判断 |
+|------|------|
+| `SUPER` 有值 | submodule，按普通仓库 |
+| `GIT_DIR != GIT_COMMON` 且非 submodule | 已在 worktree |
+| `GIT_DIR == GIT_COMMON` | 主工作区，继续创建 |
+
+已在 worktree → 报告路径与分支，跳到设置步骤，不重复创建。
+
+## 命名
+
+| 要素 | 值 |
+|------|-----|
+| base 分支 | `git rev-parse --abbrev-ref HEAD` |
+| change 分支 | `speculo/<workflow>/<change>` |
+| worktree 路径 | `{state-root}/<workflow>/changes/<change>/.worktree/` |
+
+分支或路径已存在 → 停止报告，不覆盖、不复用。
+
+## 创建
+
+```bash
+mkdir -p {state-root}/<workflow>/changes/<change>
+git worktree add -b speculo/<workflow>/<change> {state-root}/<workflow>/changes/<change>/.worktree
+cd {state-root}/<workflow>/changes/<change>/.worktree
+```
+
+> 若平台有原生 worktree 工具（如 `EnterWorktree`）且用户要求使用：用原生工具，但目标路径对齐 change 目录下 `.worktree/` 约定。无法指定路径时注明实际路径，收尾时按真实路径清理。
+
+## 项目设置与基线
+
+```bash
+[ -f package.json ] && (npm install 2>/dev/null || true)
+[ -f Cargo.toml ] && cargo build
+[ -f requirements.txt ] && pip install -r requirements.txt
+[ -f go.mod ] && go mod download
+# 跑项目基线测试
+```
+
+基线失败 → 报告询问，未获许可不开始实现。
+
+## 返回
+
+- `base_branch`、`change_branch`、`worktree_path`（绝对路径）
+- `worktree_status: active`
+- 由调用方写入 change `.status.json`

package/template/workflows/specdev/common/dev-worktree/references/finalize.md

@@ -0,0 +1,102 @@
+# 收尾合并与清理
+
+实现完成后合并回 base、清理 worktree 与分支。由 SKILL.md 阶段 B 调用。**破坏性操作须先确认。**
+
+## 前置
+
+- 测试通过（未通过不得合并）
+- 产物已在 `change_branch` 上提交
+- 已有 `base_branch`、`change_branch`、`worktree_path`
+
+## 检测环境
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+FEATURE_BRANCH=$(git branch --show-current)
+```
+
+确定 base 分支：
+```bash
+BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null || echo "")
+```
+
+## 展示选项
+
+展示前先验测试。**命名分支：**
+
+```
+实现已完成。你想怎么做？
+
+1. 本地合并回 <base-branch>（推荐，默认）
+2. 推送并创建 Pull Request
+3. 保持现状（稍后处理）
+4. 丢弃
+
+选哪个？
+```
+
+**分离 HEAD：** 移除选项 1，仅提供 2/3/4。用户未指定时默认推荐选项 1。
+
+## 选项 1：本地合并
+
+顺序固定——**先合并验证 → 再删 worktree → 最后删分支**：
+
+```bash
+MAIN_ROOT=$(git rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+git checkout <base-branch>
+git pull   # 仅远程存在且用户未禁止时
+git merge --no-ff <change_branch>
+```
+
+合并后跑测试。**失败 → 停止，保留现场，报告原因。**
+
+测试通过后：
+
+```bash
+# 必须在主仓库根执行，不能在 worktree 内部
+git worktree remove {worktree_path}
+git worktree prune
+git branch -d <change_branch>
+```
+
+更新 `.status.json`：`worktree_status: removed`。
+
+报告：已合并到 `<base-branch>`，worktree 与分支已清理。
+
+## 选项 2：PR
+
+推送分支，创建 PR，保留 worktree。若需指定远程或目标分支，先确认。
+
+## 选项 3：保持
+
+不动 worktree 和分支。报告当前状态，以便后续继续。
+
+## 选项 4：丢弃
+
+确认后删除 worktree 和分支（不合并）：
+
+```bash
+cd "$MAIN_ROOT"
+git worktree remove {worktree_path}
+git worktree prune
+git branch -D <change_branch>
+```
+
+## 失败处理
+
+| 情况 | 处理 |
+|------|------|
+| 合并冲突 | 停止，报告冲突文件，保留 worktree/分支，不强推 |
+| worktree remove 失败 | 停止报告，不 `--force`（用户明确要求除外） |
+| 已合并不回滚 | 除非用户明确要求 |
+
+## 清理规则
+
+- **只清理约定路径下的 worktree**（change 目录下 `.worktree/`）
+- 路径不匹配 → 不删（可能由 harness 管理）
+- 永远在主仓库根执行 `git worktree remove`
+- 顺序不可颠倒：merge → remove worktree → delete branch

package/template/workflows/specdev/common/research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: research
+description: "针对高可信度一手来源调查问题，并将发现结果以 Markdown 文件持久化到变更目录的 research/ 子目录中。适用于需要研究某个主题、收集文档或 API 信息、或委托阅读工作给后台 Agent 的场景。"
+---
+
+启动一个**后台 Agent** 来进行研究，这样你可以在它阅读时继续工作。
+
+其工作内容：
+
+1. 针对**一手来源**调查问题 —— 官方文档、源代码、规范、第一方 API —— 而不是基于这些来源的二次编写材料。将每个声明追溯到拥有该声明的来源。
+2. 将发现结果写入单个 Markdown 文件，为每个声明标注来源。
+3. 将文件持久化到当前变更目录的 `research/` 子目录中，并维护同目录下的 `index.md` 索引。
+
+## 持久化约定
+
+### 产物位置
+
+研究产物写入当前 change 目录下的 `research/` 子目录：
+
+```
+<Path>{roots.state}/<workflow>/changes/{change}/research/<research_topic_name>.md</Path>
+```
+
+- `<research_topic_name>` 为 kebab-case，如 `react-19-upgrade-guide.md`、`prisma-v6-migration.md`
+- `<workflow>` 为当前 workflow 目录名（如 `specdev`）
+- `<change>` 为当前活跃变更目录名（格式 `<YYYY-MM-DD>-<topic>`，从 `<Path>{roots.state}/<workflow>/status.json</Path>` 的 `active` 数组中获取）
+
+### 维护 research/index.md
+
+在 `research/` 目录下维护一个索引文件 `<Path>{roots.state}/<workflow>/changes/{change}/research/index.md</Path>`，仅包含一张表格：
+
+| 文件 | 概述 |
+|------|------|
+| `react-19-upgrade-guide.md` | React 19 升级要点、breaking changes、迁移路径 |
+| `prisma-v6-changes.md` | Prisma v6 新增 API、废弃项、性能改进 |
+
+- 表格两列：文件（`research/` 下的相对路径）、概述（一句话概括研究主题和关键发现）
+- 每次新增 research 文件后，向表格追加一行
+- 每次修改 research 文件后，检查对应概述是否仍准确，必要时更新
+- `index.md` 除表格外无需其它内容
+
+### 去重与增量更新
+
+在开始新研究之前：
+
+1. 先读取 `<Path>{roots.state}/<workflow>/changes/{change}/research/index.md</Path>`，检查是否已有同名或高度相关的 research topic
+2. 如已存在对应 `.md` 文件，先读取其完整内容
+3. 如现有内容已满足当前需求，直接引用，无需重新研究
+4. 如现有内容不满足需求（信息过时、覆盖不全、结论有误），在原文件基础上进行增删改：
+   - **增**：补充新的发现、新增来源、追加未覆盖的子主题
+   - **删**：删除已被证伪的结论、过时的信息
+   - **改**：修正错误结论、更新版本号/API 签名
+   - 修改后同步更新 `index.md` 中对应行的概述
+5. 如需研究的是全新 topic，创建新文件并追加到 `index.md` 表格