@namewta/speculo 0.2.7 → 0.2.9

package/template/workflows/specdev/INDEX.md

@@ -77,10 +77,12 @@ keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现,
 
 <!-- AUTO-INDEX-START -->
 
+- **A-archive-and-consolidate** — 归档与沉淀：将已完成变更归档至 archive/，智能评估变更产物与现有 adr/、context/、research/ 知识库的差异，执行创建/更新/合并/废弃，审计清理陈旧内容，确保知识始终最新。
 - **D-diagnose-bugs** — 诊断：针对疑难 bug 建立诊断循环——构建紧凑反馈回路、复现最小化、可证伪假设排名、插桩定位根因，确认后移交 I-implement 修复。
 - **G-grill-with-docs** — 设计访谈（带文档）：无情访谈打磨设计，同时持续产出 ADR.md、LOG.md 和 CONTEXT.md 三个领域文档。在设计讨论中捕获术语定义、记录架构决策、保存完整设计轨迹。
 - **I-implement** — 实现：基于 spec 或 tickets 实现工作——以深层模块设计原则指导架构、以 TDD 红绿循环驱动编码、以双轴审查把关质量。
 - **I-init-setup** — 初始化设置：为 specdev workflow 配置变更追踪、领域文档布局、状态标签和语言偏好。首次使用其他 specdev works 前运行一次。
+- **P-goal-plan** — 目标规划：将 spec、tickets 和参考权威综合为一份目标规划文档——编排多 ticket 里程碑的约束、质量门禁和执行协议，桥接"已有 tickets"到"协调执行 20+ tickets"。
 - **S-spec** — 编写 Spec：将当前对话综合为一份完整的 spec 文档，包含问题陈述、解决方案、用户故事、实现决策和测试决策，持久化到变更目录。
 - **T-tickets** — 拆分 Tickets：将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
 - **W-wayfinder** — 寻路：为超出单次会话容量的大块工作绘制共享地图，逐个解决调查 tickets 直到通往目标的路径清晰可见。支持研究和决策型 ticket 类型。

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

@@ -0,0 +1,84 @@
+---
+id: specdev/goal-plan
+type: workflow-entry
+workflow: specdev
+name: 目标规划
+description: 将 spec、tickets 和参考权威综合为一份目标规划文档——编排多 ticket 里程碑的约束、质量门禁和执行协议，桥接"已有 tickets"到"协调执行 20+ tickets"
+keywords: [目标规划, 编排, 里程碑, 门禁, Lead, Subagent, 合同, 参考权威]
+---
+
+# 目标规划
+
+组合 work——将 spec、tickets、参考权威和领域上下文综合为一份完整的 goal-plan.md 文档，定义多 ticket 里程碑的约束条件、质量门禁、调度顺序和执行协议。
+
+产物统一写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。
+
+在开始规划之前，读取变更的上下文与上游产物：
+
+- **spec.md** —— 当前变更的规格：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **tickets-map.md** —— ticket 依赖图与执行清单（格式遵循 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`）：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- **CONTEXT.md** —— 领域词汇表：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- **LOG.md** —— 设计决策日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+
+如果 spec.md 或 tickets-map.md 不存在，先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 和 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 产出上游产物。
+
+## 流程
+
+### 1. 收集输入与检测模式
+
+读取所有上游产物，检测适用的编排模式。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/input-validation.md</Path>`。
+
+若上游产物（spec、tickets-map、ADR）引用了不熟悉的外部依赖、技术栈或第三方服务，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 了解其能力边界、约束条件和集成方式，再推导编排模式和执行协议。
+
+**完成标准**：上游产物已加载；编排模式已识别（合同模式、参考权威模式、偏差模式、执行模式），输出为模式检测摘要。
+
+### 2. 编写远景章节（§1-3）
+
+编写 Goal、Authoritative Inputs、Definition of Done 三个远景章节。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/vision-sections.md</Path>`。
+
+**完成标准**：§1 目标声明、§2 权威输入优先级表与冲突裁决顺序、§3 六道门禁 DoD 已草拟并经用户确认。
+
+### 3. 编写执行章节（§4-5）
+
+编写 Ticket DAG 与调度顺序、单 ticket 执行协议。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/execution-sections.md</Path>`。
+
+**完成标准**：§4 DAG 图（ASCII art）、并发规则、门禁次序、编号对照表已草拟；§5 八步执行协议（含双轴审查、Lead 纪律、回写规则）已定制并经用户确认。
+
+### 4. 编写治理章节（§6-8）
+
+编写里程碑级验收、硬约束、进度回报格式。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/governance-sections.md</Path>`。
+
+**完成标准**：§6 五项里程碑验收步骤、§7 非协商硬约束、§8 结构化进度回报格式已草拟并经用户确认。
+
+### 5. 可选——添加 Ticket 速查表（§9）
+
+如果 ticket 数量超过 10 个或用户要求，追加 Ticket 一览速查表。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/quick-reference-table.md</Path>`。
+
+**完成标准**：§9 速查表已添加或已确认跳过。
+
+### 6. 写入产物与停止
+
+将完整 goal-plan.md 写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。更新 `<Path>{roots.state}/specdev/status.json</Path>` 记录 work 完成状态与产物路径。
+
+向用户汇报产物摘要（ticket 数量、门禁层级、合同/参考权威引用、关键约束），明确询问进入实现阶段（`<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`）或需要进一步修订。
+
+**完成标准**：goal-plan.md 已写入变更目录，九章节齐全无残留 `[TODO:]`；status.json 已更新；摘要已汇报给用户。
+
+## 子文件引用
+
+本入口及以下子文件按需加载：
+
+| 文件 | 内容 | 触发条件 |
+|------|------|----------|
+| `<Path>{roots.workflows}/specdev/P-goal-plan/input-validation.md</Path>` | 输入验证与模式检测 | 进入步骤 1「收集输入与检测模式」时加载——包含必需输入检查清单、五题模式检测、冲突裁决顺序推导、模式检测摘要输出格式 |
+| `<Path>{roots.workflows}/specdev/P-goal-plan/vision-sections.md</Path>` | 远景章节 §1-3 编写规程 | 进入步骤 2「编写远景章节」时加载——包含 Goal 五要素公式、权威输入优先级表与冲突裁决、六道门禁 DoD 骨架填充规则 |
+| `<Path>{roots.workflows}/specdev/P-goal-plan/execution-sections.md</Path>` | 执行章节 §4-5 编写规程 | 进入步骤 3「编写执行章节」时加载——包含 DAG 构造规则、ASCII 图约定、并发控制、八步执行协议模板 |
+| `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` | Lead 编排协议——派单上下文、handoff 交接、合并冲突、Worktree 隔离、收尾审查 | 经由 `<Path>{roots.workflows}/specdev/P-goal-plan/execution-sections.md</Path>` 在 Lead+Subagent 模型 §5 步骤 2「派单」时加载——覆盖从派单到里程碑收尾的完整 Lead 协调生命周期 |
+| `<Path>{roots.workflows}/specdev/P-goal-plan/governance-sections.md</Path>` | 治理章节 §6-8 编写规程 | 进入步骤 4「编写治理章节」时加载——包含里程碑验收仪式、硬约束推导、进度回报格式模板 |
+| `<Path>{roots.workflows}/specdev/P-goal-plan/quick-reference-table.md</Path>` | 速查表 §9 编写规程 | ticket 数量 ≥ 10 或用户显式要求时加载——包含五列表格模板与从 tickets-map 提取行数据的规则 |
+
+## 依赖关系
+
+- **上游输入**：依赖 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 产出的 spec.md 和 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 产出的 tickets-map.md；强烈建议已有 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` 产出的 ADR.md、CONTEXT.md、LOG.md。
+- **下游消费**：产物 goal-plan.md 被 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 在实现阶段读取，作为里程碑级约束和门禁次序的权威来源。

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

@@ -0,0 +1,103 @@
+# 执行章节 §4-5 编写规程
+
+编写 goal-plan 的 Ticket DAG 和单 ticket 执行协议。这两个章节是 goal-plan 的核心工程内容，决定"按什么顺序做"和"每个怎么做"。
+
+## §4 — Ticket DAG and Scheduling Order
+
+tickets-map.md 的格式遵循权威模板 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`——执行清单为六列表格（编号 | Ticket | 被阻塞于 | Gate | Contract ID | 状态），依赖关系节支持门禁标注 DAG。
+
+### DAG 构造
+
+从 tickets-map.md 读取并丰富依赖图：
+
+1. **读取 tickets-map.md** —— 读取执行清单表的 `被阻塞于` 列和基础 ASCII 依赖树
+2. **构建邻接表** —— ticket A 阻塞 ticket B = A → B 的有向边
+3. **检测循环** —— 如果有循环依赖，报告并停止，让用户先修复 tickets
+4. **标注门禁层级** —— 结合合同或 spec 的优先级（P0/P1/P2）给每个 ticket 分配 gate 层级，将 Gate 标注**回写**到 tickets-map.md 执行清单表的 Gate 列：
+   - P0 = 阻塞所有后续工作的核心基础设施
+   - P1 = 主要功能切片
+   - P2 = 增强和边界情况
+5. **填写 Contract ID** —— 如激活合同模式，将每个 ticket 覆盖的验收条目 ID 回写到 tickets-map.md 执行清单表的 Contract ID 列
+
+### 门禁次序
+
+P0 门禁先开，阻塞所有 P1/P2 关闭。ticket 可以在其依赖就绪后开始，不依赖门禁——但门禁关闭（和里程碑推进）严格遵循 P0→P1→P2 顺序。
+
+### ASCII 图绘制
+
+在 tickets-map.md 的「依赖关系」节中，将 T-tickets 写入的基础 ASCII 树形图**丰富**为门禁标注 DAG。遵循以下约定：
+
+- 每行一个 ticket，缩进表示依赖深度
+- `→` 表示依赖关系（A → B 表示 B 依赖 A）
+- 用注释标注门禁边界：`--- P0 gate ---`
+- 可立即开始的 ticket 标注 `[READY]`
+- 扇出点标注 `[FAN-OUT: N路并行]`
+
+示例格式：
+```
+#4 [READY]  →  #5 [FAN-OUT: 3路并行]
+                     ├→ #6 [P0]
+                     ├→ #7 [P1]
+                     └→ #8 [P1]
+--- P0 gate ---
+#6  →  #9 [P1]  →  #10 [P2]
+```
+
+将丰富后的 DAG 回写到 tickets-map.md 的「依赖关系」节，替换 T-tickets 写入的基础版本。
+
+### 并行规则
+
+tickets-map.md 的「并行规则」节已由模板预设默认值（最大 3 并发、allowlist 不重叠、共享文件仅 Lead 修改）。P-goal-plan 根据实际 ticket 数量调整并发数（> 20 时可调至 4），并在 goal-plan.md §4 中引用 tickets-map.md 的并行规则（避免重复）。
+
+### 草拟与确认
+
+输出 DAG 图、门禁次序声明、并行规则。等待用户确认后，将门禁标注和 Contract ID 回写到 tickets-map.md，将完整 DAG 和门禁次序写入 goal-plan.md §4。
+
+## §5 — Per-Ticket Execution Protocol
+
+### 协议定制
+
+根据 input-validation.md 检测到的执行模型选择协议骨架：
+
+#### Lead+Subagent 模型（完整八步）
+
+1. **读取** —— Lead 读取 issue 全文、合同/参考权威对应行、ticket 的验收标准。如果激活参考权威模式，对照参考快照中的对应交互路径。
+2. **派单** —— Lead 输出结构化派单行 `IMPLEMENTER_DISPATCH #<n> issue=<url> gate=<P0|P1|P2> allowlist=<files> contract_ids=<...>`，然后生成实现子代理（model: fable, 唯一 name）。Lead+Subagent 模型下，加载 `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` 获取完整的编排协议——包括子代理上下文载荷结构、handoff 交接、合并冲突解决、Worktree 隔离和收尾审查的详细步骤。
+3. **实现** —— 子代理在 file allowlist 内实现变更，按 ticket 指定的测试矩阵运行测试。
+4. **双轴审查** —— 实现完成后，立即启动两个审查子代理并行运行：
+   - `reviewer-standards-<n>`：代码质量、架构、测试覆盖
+   - `reviewer-spec-<n>`：spec 合规、验收标准
+   - 任一返回 REQUEST_CHANGES 则启动修复子代理
+5. **门禁** —— 类型检查、测试、lint 全部通过。
+6. **回写** —— 如果激活合同模式：更新合同条目状态为 `done` 或 `deviate`；如激活 ADR 模式：检查 ADR 状态无需变更。偏差条目如有则由 Lead 同步偏差表。
+7. **关闭 issue** —— 附上验证证据（测试输出、commit SHA、如适用附截图）。
+8. **Lead 纪律** —— Lead 自身不得实现代码。如果 Lead 发现自己在写实现代码，输出 `DELEGATION_VIOLATION` 并重新派单。子代理不得操作 Git——只由 Lead 提交。
+
+#### 简化模型（精简协议）
+
+1. **读取** — 读 ticket、spec 对应 User Story、验收标准。
+2. **实现** — 在 ticket 声明的范围内实现变更。
+3. **审查** — 单审查者检查代码质量和 spec 合规。
+4. **门禁** — 类型检查、测试通过。
+5. **关闭** — 提交并关闭 issue。
+
+### 草拟规则
+
+- 协议步骤中的具体路径（合同路径、参考快照路径）从 input-validation 的检测结果填入
+- 测试矩阵从 tickets 或 spec 的 Test Decisions 提取
+- 双轴审查的派单模板写为可复制的文本块
+- Lead 纪律写为不可协商的约束
+
+### 草拟与确认
+
+输出 §5 完整协议文本。等待用户确认后进入治理章节。
+
+**完成标准**：§4 DAG 图无循环、门禁标注正确、对照表完整且经用户确认；§5 执行协议八步/精简流程已定制填入具体路径、测试矩阵和双轴审查模板，经用户确认。
+
+## 子文件引用
+
+本文件按需加载以下子文件：
+
+| 文件 | 内容 | 触发条件 |
+|------|------|----------|
+| `<Path>{roots.workflows}/specdev/P-goal-plan/lead-orchestration-protocol.md</Path>` | Lead 编排协议——派单上下文载荷、handoff 交接、合并冲突解决、Worktree 隔离的创建与收尾、里程碑收尾审查 | 使用 Lead+Subagent 模型时，在 §5 步骤 2「派单」加载，覆盖从派单到收尾的完整执行生命周期 |

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

@@ -0,0 +1,103 @@
+# 治理章节 §6-8 编写规程
+
+编写 goal-plan 的里程碑验收、硬约束和进度回报格式。这三个章节定义"怎么验收"和"怎么追踪"。
+
+## §6 — Milestone-Level Acceptance
+
+### 五项仪式步骤
+
+全部 ticket 关闭后执行以下验收仪式：
+
+1. **合同/ADR 终审** —— 如果激活合同模式：逐行检查合同文档，确认所有行状态为 `done` 或 `deviate`（有记录理由），无 `todo` 残留；如果无合同但激活 ADR 模式：检查 ADR 偏差表条目已解决或明确记录为 `deviate`
+2. **整体验证门禁** —— 运行 `pnpm verify`（或 spec 中指定的验证命令），确认全绿
+3. **集成回归走查** —— 完成一次端到端用户旅程脚本走查
+4. **关闭 spec issue** —— 关闭关联的 spec issue，引用 milestone done
+5. **人工 side-by-side 验证清单** —— 输出人工核对清单供用户在真机上执行最终手感验收
+
+### 集成回归走查脚本构造
+
+从 spec.md 的 User Stories 和 ticket 的验收标准推导端到端用户旅程：
+
+- 提取每个 User Story 的关键交互步骤
+- 按用户使用顺序串联（不按 ticket 编号）
+- 每个步骤写为具体的操作指令（命名具体的按钮、输入、期望行为）
+- 覆盖主路径和至少一条备选路径
+
+格式：编号列表，每一步包含"操作 → 期望"。
+
+### 人工 side-by-side 清单构造
+
+- 按门禁层级（P0/P1/P2）分组
+- 如果激活参考权威模式：每项包含参考权威对比步骤（"对照 X 中的 Y——行为是否一致？"）
+- 结尾注明："自动化不替代最终手感环节"
+
+### 草拟与确认
+
+输出 §6 完整草案（五项步骤 + 回归走查脚本 + side-by-side 清单分组）。等待用户确认后进入 §7。
+
+## §7 — Hard Constraints
+
+### 约束推导
+
+从模式检测和 ADR 推导所有非协商约束。每条约束写为一句声明 + 违反后果。
+
+#### 通用约束（所有 goal-plan 包含）
+
+1. **合同/规格冻结** —— 如激活合同模式：「合同一旦冻结不得修改。如需修改，先修改合同再继续实现。违反即返工。」；否则：「spec 的 User Stories 和 Implementation Decisions 为权威。超出 spec 的范围变更需先更新 spec。」
+2. **领域不变量优先** —— 「架构决策中声明的领域不变量先于实现便利。违反即返工。」
+3. **伪完成禁止** —— 「能力存在但手感、交互细节、边界情况、空状态文案与参考/规格不一致，视为未完成。禁止以"API 通了"为由关闭 ticket。」
+4. **Git 纪律** —— 如果使用 Lead+Subagent 模型：「仅 Lead 操作 Git（提交、合并、推送）。子代理输出 diff/patch，Lead 审查后提交。」
+5. **单一真相源** —— 「不复活废弃组件、不创建规格外的新抽象、不引入与 ADR 冲突的外部依赖。所有技术决策追溯到 ADR 或 LOG。」
+6. **沟通语言** —— 「全部代码注释、提交信息、issue 评论、进度报告使用简体中文。」
+
+#### 模式特定约束
+
+- **合同模式**：「合同条目状态回写必须在 ticket 关闭前完成。先回写合同，再关闭 issue。」
+- **参考权威模式**：「任何与参考权威的行为差异必须追溯到一个偏差条目（DEV-NN）。无条目偏差视为缺陷。」
+- **Lead+Subagent 模式**：「Lead 不得实现代码。发现 Lead 写实现代码时输出 DELEGATION_VIOLATION 并重新派单。子代理不得提交——只输出 patch。」
+- **偏差模式**：「偏差条目（DEV-NN）关闭条件是：要么通过实现消除偏差，要么在偏差表中记录为 deviate 并附理由。」
+
+### 草拟与确认
+
+输出 §7 完整约束列表。等待用户确认后进入 §8。
+
+## §8 — Progress Reporting Format
+
+### 模板定制
+
+根据执行模型和合同模式定制进度回报格式：
+
+#### TICKET_DONE 格式（Lead+Subagent 模型）
+
+```
+TICKET_DONE #<n> (<k>/<N>) gate=<P0|P1|P2> contract_ids=<P0-01,P1-03> verify=<cmd:result> commit=<sha>
+```
+
+字段说明：
+- `#<n>` —— ticket 编号
+- `(<k>/<N>)` —— 进度计数（当前第几个 / 总数）
+- `gate` —— 门禁层级
+- `contract_ids` —— 如激活合同模式，列出本 ticket 覆盖的合同条目 ID，逗号分隔；如无合同则使用 `adr_ref=<ADR-NNNN>`
+- `verify` —— 验证命令及结果（PASS/FAIL）
+- `commit` —— 提交 SHA
+
+#### MILESTONE_DONE 格式
+
+所有 ticket 关闭后输出：
+
+```
+MILESTONE_DONE issues_closed=<N>/<N> contract_todo=0 verify=GREEN
+```
+
+如果无合同模式：将 `contract_todo=0` 替换为 `adr_deviate_resolved_or_recorded=YES`。
+
+#### 格式变体
+
+- **切面跟踪**（ticket 数 > 15 时推荐）：在 TICKET_DONE 中增加 `slice=<ADR|DATA|SHELL|WORK|...>` 字段，按切面分组追踪进度
+- **简化模型**：使用简化格式 `TICKET_DONE #<n> verify=<cmd:result>`
+
+### 草拟与确认
+
+输出 §8 格式定义，包含一个填写示例。等待用户确认。
+
+**完成标准**：§6 五项验收步骤完整、回归走查脚本覆盖主路径和一条备选路径、side-by-side 清单按门禁分组；§7 约束条条为一句声明+后果、模式特定约束已根据检测结果定制；§8 模板字段已填入本里程碑的具体值（N、合同路径、验证命令），经用户确认。

package/template/workflows/specdev/P-goal-plan/input-validation.md

@@ -0,0 +1,94 @@
+# 输入验证与模式检测
+
+在开始编写 goal-plan 任何章节之前，验证上游输入完整性并检测适用的编排模式。模式检测在第一步完成，后续所有章节根据检测结果适配内容。
+
+## 1. 必需输入检查
+
+逐项检查以下输入是否存在，缺失时按规则处理：
+
+| 输入 | 路径 | 缺失处理 |
+|------|------|----------|
+| spec.md | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | **中止**——引导用户先运行 `S-spec`，无 spec 无法定义目标 |
+| tickets-map.md | `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` | **中止**——引导用户先运行 `T-tickets`，无 tickets 无法构建 DAG |
+| ADR.md | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 继续但记录——约束推导将缺少架构锚点 |
+| CONTEXT.md | `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 继续但记录——术语将草拟而非引用 |
+| LOG.md | `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` | 继续但记录——设计轨迹不可追溯 |
+
+如果 spec.md 和 tickets-map.md 均存在，继续下一步。任何必需项缺失且用户拒绝先运行上游 work，则中止。
+
+## 2. 模式检测
+
+对以下五个问题逐一回答，每个"是"激活对应的编排模式：
+
+### Q1：是否存在冻结合同/验收文档？
+
+在 spec.md 和 ADR.md 中搜索合同/验收文档引用。合同是包含编号验收条目（P0-01、P1-01 等）及状态值（`todo`/`done`/`deviate`/`n/a`）的外部文档。
+
+- **是** → 激活「冻结合同模式」：§2 权威输入优先级表增加合同行；§3 DoD 增加合同状态收敛条目；§5 执行协议包含回写合同步骤；§6 里程碑验收包含合同终审；§7 硬约束包含合同冻结
+- **否** → 使用简化模式：DoD 不含合同条目；执行协议不含回写合同；约束以 ADR 为权威
+
+### Q2：是否存在参考权威（UX 快照、既有代码库）？
+
+在 spec.md 的"解决方案"或"参考"段落中搜索对快照/代码库/产品的引用。
+
+- **是** → 激活「参考权威模式」：§2 权威输入优先级表增加参考权威行；§5 执行协议步骤 1 包含对照路径；§6 人工 side-by-side 清单增加参考权威对比列
+- **否** → 无参考权威：跳过参考对比相关内容
+
+### Q3：是否存在有意偏差（DEV-01...）？
+
+在合同文档或 ADR 中搜索偏差表（DEV-01 及更高编号）。偏差是预先批准的对参考权威的偏离。
+
+- **是** → 激活「偏差模式」：§2 权威输入增加偏差表引用；§3 DoD 增加偏差收敛条目；§5 执行协议步骤 6 包含偏差追踪
+- **否** → 无偏差追踪需求
+
+### Q4：ticket 数量在哪个范围？
+
+统计 tickets-map.md 中的 ticket 条目数：
+
+- **< 10 个** → 「轻量模式」：警告用户 goal-plan 为 10+ tickets 设计，提供两个选项：(a) 继续用简化模板（一步编写全部章节），(b) 跳过 goal-plan 直接进入 I-implement
+- **10-20 个** → 「标准模式」：启用并发控制（max 3），DAG 中等复杂度
+- **> 20 个** → 「复杂模式」：完整并发控制、严格门禁次序（P0→P1→P2）、§9 速查表强制追加
+
+### Q5：采用何种执行模型？
+
+检查用户是否有意使用 Lead+Subagent 模型。默认如果 ticket 数 ≥ 10 或有合同文档，推荐 Lead+Subagent。
+
+- **Lead+Subagent 模型** → §5 执行协议使用完整八步流程（读取→派单→实现→双轴审查→门禁→回写→关闭→纪律）；§7 硬约束包含 Lead 纪律规则；§8 进度回报使用 TICKET_DONE 格式
+- **简化模型** → §5 使用精简协议（读取→实现→审查→门禁→关闭）；不使用 TICKET_DONE 格式
+
+## 3. 冲突裁决顺序
+
+从检测到的模式推导冲突裁决顺序，默认顺序（从高到低）：
+
+1. 领域不变量（来自 ADR.md 架构决策）
+2. 冻结合同（如激活合同模式）
+3. 参考权威手感（如激活参考权威模式）
+4. spec.md 中的用户故事
+
+如果未激活合同模式，跳过第 2 项。如果未激活参考权威模式，跳过第 3 项。
+
+## 4. 输出模式检测摘要
+
+将检测结果汇总为结构化摘要，呈现给用户确认：
+
+```
+## 模式检测摘要
+
+| 检测项 | 结果 | 影响 |
+|--------|------|------|
+| 冻结合同 | 是/否 | ... |
+| 参考权威 | 是/否 | ... |
+| 有意偏差 | 是（DEV-01 至 DEV-0X）/ 否 | ... |
+| Ticket 数量 | N（轻量/标准/复杂） | ... |
+| 执行模型 | Lead+Subagent / 简化 | ... |
+| ADR 可用 | 是/否 | ... |
+| CONTEXT 可用 | 是/否 | ... |
+
+冲突裁决顺序：[推导结果]
+
+是否确认以上模式检测？如有误请纠正后继续。
+```
+
+用户确认或纠正后，进入远景章节编写。
+
+**完成标准**：五个模式检测问题均已回答；冲突裁决顺序已推导；摘要已呈现并获用户确认或纠正。

package/template/workflows/specdev/P-goal-plan/lead-orchestration-protocol.md

@@ -0,0 +1,159 @@
+# Lead 编排协议
+
+本协议扩展 §5 执行协议中的 Lead+Subagent 模型，覆盖 Lead 在子代理协调中的五个关键环节。当 Lead+Subagent 模型激活时，在 §5 步骤 2「派单」时加载，覆盖整个执行生命周期——从派单到收尾。
+
+协议覆盖：子代理派单上下文载荷、执行完成后 handoff 交接、并行执行合并冲突解决、Worktree 隔离的创建与收尾、里程碑完成时的 neat-freak 收尾审查。
+
+## 1. 子代理派单上下文
+
+### 1.1 上下文载荷结构
+
+向子代理派单时，只发送元数据行（`IMPLEMENTER_DISPATCH`）不足以保证子代理产出与规格一致的实现。Lead 必须在派单时为每个子代理组装完整的上下文载荷，包含以下内容：
+
+| 载荷项 | 来源路径 | 说明 |
+|--------|---------|------|
+| 架构决策记录 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 和 `<Path>{roots.state}/specdev/adr/</Path>` | 当前变更的架构约束和已确认的永久架构决策——子代理必须遵守的设计边界 |
+| 领域词汇表 | `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 和 `<Path>{roots.state}/specdev/context/</Path>` | 当前变更的术语定义和已确认的永久词汇表——子代理的命名和概念必须对齐，使用 `_Avoid_` 列表中的同义词即视为偏离 |
+| 目标规划文档 | `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` | 里程碑级约束、门禁次序、Definition of Done——子代理理解全局上下文和自身 ticket 在整体中的位置 |
+| ticket 文件 | `<Path>{roots.state}/specdev/changes/{change}/</Path>` 下对应 ticket | 验收标准、file allowlist、合同引用、阻塞关系——子代理的直接任务定义，包含「要构建什么」「范围边界」「保留/不动」 |
+| 合同验收条目 | 合同文档中本 ticket 覆盖的条目（如激活合同模式） | 编号验收条目及当前状态——子代理必须逐个满足的可检查条件 |
+| 实现方法参考 | `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` | 深层模块设计原则、TDD 红绿循环、双轴审查流程——子代理的实现方法论，确保所有子代理采用一致的工程质量标准 |
+
+### 1.2 派单模板
+
+Lead 向子代理发送的内容应包含以下结构化信息块，而非仅一行元数据：
+
+```
+IMPLEMENTER_DISPATCH #<n>
+  issue: <url>
+  gate: <P0|P1|P2>
+  allowlist: <files>
+  contract_ids: <...>
+
+附加上下文——子代理在开始实现前读取：
+  adr: <{roots.state}/specdev/changes/{change}/ADR.md>
+  permanent_adr: <{roots.state}/specdev/adr/>
+  context: <{roots.state}/specdev/changes/{change}/CONTEXT.md>
+  permanent_context: <{roots.state}/specdev/context/>
+  goal_plan: <{roots.state}/specdev/changes/{change}/goal-plan.md>
+  ticket_file: <{roots.state}/specdev/changes/{change}/<ticket-file>>
+  implement_ref: <{roots.workflows}/specdev/I-implement/I-implement.md>
+```
+
+Lead 在生成子代理时将以上文件作为上下文传入，确保子代理在开始实现前已读取全部载荷。永久 ADR 和永久 CONTEXT 目录可能为空——静默继续。
+
+**完成标准**：每个子代理在启动时收到完整的上下文载荷（ADR、CONTEXT、goal-plan、ticket 文件、合同条目、I-implement 参考），所有路径指向真实存在的文件；IMPLEMENTER_DISPATCH 行和附加上下文已一并传递给子代理。
+
+## 2. 子代理完成后交接
+
+### 2.1 启动 handoff 技能
+
+子代理完成 ticket 实现并通过双轴审查和门禁后（§5 步骤 3-5 完成），Lead 执行交接流程：
+
+1. Lead 调用 `<Path>{roots.workflows}/specdev/common/handoff/SKILL.md</Path>` 压缩子代理的对话上下文
+2. handoff 技能产出交接文档，包含：实现了什么、做出的关键决策、与 spec 的任何偏差及原因、测试结果摘要、建议后续 agent 调用的 skills
+3. handoff 剥离敏感信息，不重复已存在于 spec/plan/ADR/commit/diff 中的内容——改用路径或 URL 引用
+4. 交接文档保存到操作系统临时目录
+
+### 2.2 回写 ticket 文件
+
+压缩后的交接摘要回写到对应 ticket 文件，使后续 agent 可通过 ticket 文件获取实现上下文，无需读取完整子代理转录：
+
+1. Lead 从 handoff 输出中提取关键信息：commit SHA、测试结果、决策与偏差、引用的产物路径
+2. Lead 在 ticket 文件末尾追加 `## 实现交接摘要` 小节，包含以上信息
+3. 格式：
+
+```
+## 实现交接摘要
+
+- **Commit**: <sha>
+- **测试结果**: <summary>
+- **关键决策**: <decision>（如有）
+- **偏差**: <deviation + reason>（如有）
+- **产物引用**: <paths to spec/ADR/contract updated>
+- **交接文档**: <path to OS temp handoff doc>
+```
+
+**完成标准**：每个 ticket 完成后，Lead 已调用 handoff 技能压缩对话；交接摘要已回写到 ticket 文件的「实现交接摘要」小节；后续 agent 可通过 ticket 文件获取实现上下文，无需读取完整子代理转录。
+
+## 3. 合并冲突解决
+
+### 3.1 触发条件
+
+并行执行时，Lead 从多个子代理 worktree 向 base 分支合并时可能产生冲突。尽管 file allowlist 非重叠规则降低了冲突概率，共享依赖（package.json、lockfile）或配置文件仍可能在合并时冲突。Lead 从 worktree finalize（§4.2）或手动合并时检测到冲突即触发本协议。
+
+### 3.2 解决协议
+
+1. Lead 检测到合并冲突后，调用 `<Path>{roots.workflows}/specdev/common/resolving-merge-conflicts/SKILL.md</Path>`
+2. 遵循该技能的 5 步协议：
+   - **查看状态**：检查 git merge/rebase 当前状态，列出冲突文件
+   - **溯源一手来源**：阅读每个冲突的 commit 消息、检查 PR、查看原始 issue/ticket，理解每方更改的原始意图
+   - **逐块解决**：尽可能保留双方意图。不兼容时，选择与合并既定目标一致的一方，记录权衡。不发明新行为。务必解决，不执行 `--abort`
+   - **运行检查**：按类型检查、测试、格式化的顺序运行自动化检查，修复合并破坏的任何内容
+   - **完成合并**：暂存所有内容并提交。如果是 rebase，继续直到所有 commits 已 rebase
+3. 解决后，Lead 在合并结果上重跑测试，确认通过后再继续
+4. 如果解决需要修改子代理产出，Lead 将变更记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`：记录冲突的 ticket、冲突文件、做出的权衡
+
+**完成标准**：合并冲突已通过 resolving-merge-conflicts 技能的 5 步协议解决；双方意图已尽可能保留；不兼容处已选择与合并目标一致的方案并记录权衡；自动化检查全绿；合并结果测试通过；如有子代理产出修改，已记录到 LOG.md。
+
+## 4. 并行 Worktree 隔离
+
+### 4.1 为并发子代理创建隔离 Worktree
+
+当 DAG 允许 3-4 个 ticket 并行执行时，Lead 为每个并发子代理创建独立的 git worktree：
+
+1. Lead 对每个并发子代理调用 `<Path>{roots.workflows}/specdev/common/dev-worktree/SKILL.md</Path>` Phase A
+2. 每个 worktree 使用唯一分支名：`speculo/specdev/<change>-<ticket-n>`
+3. Worktree 路径：`<Path>{roots.state}/specdev/changes/{change}/.worktree-<ticket-n>/</Path>`
+4. Lead 在派单前确认：
+   - 每个子代理的 file allowlist 与其 worktree 范围对应
+   - 两两子代理的 file allowlist 无重叠（共享文件仅 Lead 修改）
+   - 每个 worktree 中基线测试通过（基线失败阻断派单）
+5. 子代理在其隔离 worktree 内工作，无法看到其他子代理的进行中工作
+6. Lead 在 `.status.json` 中记录每个 worktree 的状态：`worktree_status: active`、`ticket_ref`、`base_branch`
+
+### 4.2 子代理完成后的 Worktree 收尾
+
+子代理完成实现并通过审查和门禁后：
+
+1. Lead 调用 `<Path>{roots.workflows}/specdev/common/dev-worktree/SKILL.md</Path>` Phase B
+2. Phase B 流程：验证测试通过 → 展示选项（本地合并/PR/保留/丢弃）→ 执行所选选项
+3. 默认选项为本地合并：checkout base → pull → `git merge --no-ff <change_branch>` → 在合并结果上重跑测试
+4. 合并成功后，从主仓库根目录执行：`git worktree remove <path>` → `git branch -d <branch>` → `git worktree prune`
+5. 更新 `.status.json`：`worktree_status: removed`
+6. 如果 worktree finalize 期间出现合并冲突，跳转到 §3 合并冲突解决协议
+
+**完成标准**：每个并发子代理在独立 worktree 中工作，分支名 `speculo/specdev/<change>-<ticket-n>`；任意两个子代理的 file allowlist 无重叠；基线测试在 worktree 创建时通过；子代理完成后 worktree 已合并回 base 分支、worktree 目录和临时分支已清理；`.status.json` 反映最终状态。
+
+## 5. 里程碑收尾审查与清理
+
+### 5.1 触发 neat-freak
+
+当 Lead 判断里程碑完成——所有 ticket 关闭、全部门禁通过、§6 里程碑验收仪式完成：
+
+1. Lead 调用 `<Path>{roots.workflows}/specdev/common/neat-freak/SKILL.md</Path>` 执行知识治理收尾
+2. neat-freak 跨六个事实面进行一致性核对：
+   - **Code** — 当前分支的代码实际实现了什么
+   - **Runtime** — 用户实际获得的行为
+   - **Docs** — 人类/下游文档是否与现状一致
+   - **Rules** — Agent 约束是否单一来源、无死引用
+   - **Memory** — 快照是否准确、是否授权修改
+   - **Workspace** — 是否有未清理的会话残留
+3. 每个事实面标记状态：`verified-current`、`changed-and-verified`、`pending`、`out-of-scope`、`not-applicable`
+4. 清理候选：临时计划文档、调试脚本、过期副本（`xxx_old.*`、`xxx_backup/`、`xxx_v2.*`）、孤立 worktree 产物
+5. 清理前必须经用户确认——预授权不替代最终报告的确认
+
+### 5.2 收尾清单
+
+Lead 在输出 `MILESTONE_DONE` 前逐项确认：
+
+- [ ] 所有 ticket 的 handoff 摘要已回写到对应 ticket 文件的「实现交接摘要」小节
+- [ ] 所有 worktree 已合并且清理——`git worktree list` 无本变更残留
+- [ ] 所有临时分支已删除——仅保留 base 和已合并的 change 分支
+- [ ] neat-freak 已运行——文档、ADR、CONTEXT 与代码现状一致，六个事实面状态明确
+- [ ] `.status.json` 反映最终状态——所有 `worktree_status: removed`
+- [ ] `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 已追加里程碑完成记录（日期、ticket 数、关键决策、合并冲突及解决摘要）
+- [ ] 检查 `<Path>{roots.state}/specdev/adr/</Path>` 和 `<Path>{roots.state}/specdev/context/</Path>`——是否需要将 change 中的新 ADR 条目和术语提升到永久目录
+- [ ] 输出 `MILESTONE_DONE` 格式的完成报告
+
+**完成标准**：neat-freak 知识治理收尾已完成——六个事实面状态明确、文档与代码一致、无过期引用；所有 worktree 和临时分支已清理；ticket 交接摘要齐全且可追溯；LOG.md 已记录里程碑完成；永久 ADR 和 CONTEXT 目录已检查并提升新条目（如有）；MILESTONE_DONE 报告已输出。

package/template/workflows/specdev/P-goal-plan/quick-reference-table.md

@@ -0,0 +1,60 @@
+# 速查表 §9 编写规程
+
+可选的 Ticket 一览速查表，为 Lead 提供快速全局视图。
+
+## 触发条件
+
+满足以下任一条件时追加 §9：
+
+- ticket 数量 ≥ 10 个
+- 用户显式要求"加速查表"或"加 ticket 一览"
+
+不满足时，在 goal-plan.md 末尾添加一行说明并跳过：「§9 速查表已跳过（ticket 数量 < 10）。」
+
+## 表格模板
+
+五列表格，每行一个 ticket：
+
+| # | 切片 | 闸门 | 被阻塞于 | 端到端交付 |
+|---|------|------|----------|-----------|
+| <n> | <slice_name> | <P0\|P1\|P2> | <ticket titles> | <一句话交付描述> |
+
+### 列填充规则
+
+- **#** —— ticket 编号，与 issues 对应
+- **切片** —— 从 ticket 内容分析其所属的功能切面（如 DATA、SHELL、WORK、PLANNER、SCHEDULE、BOARDS、GATE、ADR）。一个 ticket 属于一个切面。从 ticket 标题和"要构建什么"段落推断切面名
+- **闸门** —— 从 DAG 分析中分配的 P0/P1/P2 层级
+- **被阻塞于** —— 从 tickets-map.md 的依赖边提取，用 ticket 标题（非编号）列出前置
+- **端到端交付** —— 一句话描述本 ticket 的用户可见交付物。不写技术实现细节，写用户能感知的变化
+
+### 行生成
+
+1. 从 tickets-map.md 逐行读取 ticket
+2. 对每个 ticket，读取其内容摘要（标题 + "要构建什么"首句）
+3. 推断切片名——检查标题中是否包含领域关键词（DATA→数据层、SHELL→外壳/布局、WORK→核心工作流等），默认归入 WORK
+4. 从 DAG 分析复制 gate 层级和阻塞关系
+5. 将"要构建什么"浓缩为一句话，删除技术细节（"使用 React 实现..."→"用户可以看到..."）
+6. 按 gate 层级排序（P0 在前），gate 内按 ticket 编号排序
+
+## 可选：Lead 开篇清单
+
+在速查表之后可选追加一段 Lead 在里程碑启动前需确认的检查项：
+
+```
+## Lead 开篇清单
+
+启动里程碑前确认：
+
+- [ ] 所有 issues 已在 GitHub 创建且标签正确
+- [ ] 合同/ADR 偏差表已与用户对齐
+- [ ] 参考权威快照路径可访问
+- [ ] 子代理 file allowlist 无重叠
+- [ ] 共享文件修改权仅 Lead 持有
+- [ ] 门禁次序和并发规则已向用户确认
+```
+
+## 写入
+
+将表格（和可选的开篇清单）追加到 goal-plan.md 作为 §9。如果跳过，写入跳过说明。
+
+**完成标准**：速查表已追加（或跳过说明已写入）；行数据与 tickets-map.md 一致；切片分类合理；端到端交付描述均为用户可见变化。