@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/I-init-setup/domain-layout-template.md

@@ -0,0 +1,23 @@
+# 领域文档布局
+
+## 读取顺序
+
+1. 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+2. 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+3. 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+4. 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+5. 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+6. 当前 Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+7. 当前 Goal Plan：`<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+8. 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+
+## 职责
+
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`：当前术语、不变量、概念关系和代码映射。
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`：当前 change 已接受、被替代或废弃的架构决策。
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`：设计讨论轨迹，不作为当前架构的最终权威。
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`：用户问题、外部行为、范围与验收合同。
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`：单个垂直切片的执行契约。
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`：跨 Ticket 的门禁、调度和治理。
+
+change 完成后，只有仍真实、长期有效且有实现证据的知识才能提升到永久目录。

package/template/workflows/specdev/I-init-setup/status-labels-template.md

@@ -0,0 +1,55 @@
+# 状态标签映射
+
+本文件把 SpecDev 的标准角色映射到外部 Issue/项目管理系统的具体标签。标准角色保持稳定；具体标签字符串可以按项目调整。
+
+## 1. 标准角色
+
+| 标准角色 | 默认标签 | 使用条件 | 退出条件 |
+|---|---|---|---|
+| needs-triage | needs-triage | 外部请求尚未完成分类、影响和路由 | `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 已完成 |
+| needs-info | needs-info | 缺少必须由用户或外部系统提供的信息 | 决策或输入已写入权威工件 |
+| ready-for-agent | ready-for-agent | 当前工件满足 Ready 门禁，可由 Agent 自主继续 | Agent 领取、出现 blocker/deviation 或完成 |
+| ready-for-human | ready-for-human | 等待产品、架构、安全、发布或不可逆操作批准 | 指定批准人记录决定 |
+| wontfix | wontfix | 用户或 owner 明确决定不处理 | 通常为终态；恢复需新决定 |
+
+标签是外部系统投影，不替代 `<Path>{roots.state}/specdev/status.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 或 Ticket frontmatter。
+
+## 2. 推荐流转
+
+```text
+needs-triage
+   ├─→ needs-info ──→ needs-triage
+   ├─→ ready-for-human ──→ ready-for-agent
+   ├─→ ready-for-agent ──→ in-progress / review / completed
+   └─→ wontfix
+```
+
+外部系统没有 `in-progress`、`review` 或 `completed` 标签时，可以不映射；SpecDev 内部状态仍由状态工件维护。
+
+## 3. 内部状态投影
+
+| SpecDev 状态或条件 | 推荐标准角色 |
+|---|---|
+| 新摄入、尚未分诊 | needs-triage |
+| `blocked` 且缺少用户输入 | needs-info |
+| Ready Ticket 或获批 Direct Spec | ready-for-agent |
+| Deep Ticket 批准点、release deviation、不可逆操作 | ready-for-human |
+| 明确取消且不再处理 | wontfix |
+
+不得仅因添加 `ready-for-agent` 标签就绕过 Spec、Ticket、Goal Plan 或验证门禁。
+
+## 4. 自定义规则
+
+1. 可以修改“默认标签”字符串，但不得改变五个标准角色的语义。
+2. 一个具体标签不得同时映射到多个互斥角色。
+3. 项目没有对应外部系统时，保留本文件作为语义字典，不强制创建标签。
+4. 标签不存在时先报告，不自动创建、重命名或删除外部标签，除非用户授权。
+5. 外部标签与内部状态冲突时，以 SpecDev 权威工件为准，修正投影并记录原因。
+6. 自定义结果应记录来源、系统名称、更新时间和维护 owner。
+
+## 5. 项目映射
+
+- **外部系统：** 无 / GitHub / GitLab / Jira / 其他
+- **映射更新时间：**
+- **维护 owner：**
+- **自定义映射：** 无 / ...

package/template/workflows/specdev/I-init-setup/status-template.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 3,
+  "workflow": "specdev",
+  "active": [],
+  "work_history": [],
+  "completed": []
+}

package/template/workflows/specdev/I-init-setup/tracking-template.md

@@ -0,0 +1,10 @@
+# 变更追踪约定
+
+- change 根：`<Path>{roots.state}/specdev/changes/</Path>`。
+- 单个 change：`<Path>{roots.state}/specdev/changes/{change}/</Path>`，其中 `{change}` 使用 `<YYYY-MM-DD>-<kebab-topic>`。
+- 一个 change 表示一个可独立说明、实现、验证和归档的目标。
+- `<Path>{roots.state}/specdev/status.json</Path>` 维护全局活动索引；`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 维护单个 change 生命周期。
+- Ticket 文件是 Ticket 状态权威；`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 是同步投影。
+- 工件状态应在同一次操作中同步，避免入口状态、Ticket 状态与 Map 状态漂移。
+- 完成条件：全部必需 Ticket 为 `done` 或有批准的 `cancelled`，证据齐全，无未批准 deviation，change 级验证通过。
+- 归档后的 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/</Path>` 默认只读；后续纠正通过新 change 和 supersedes 链完成。

package/template/workflows/specdev/INDEX.md

@@ -3,116 +3,199 @@ id: specdev
 type: workflow
 workflow: specdev
 name: SpecDev Workflow
-description: 软件研发全流程——从初始化设置、设计访谈（带 ADR/LOG/CONTEXT）、spec 编写、ticket 拆分、寻路到 TDD 实现与双轴审查
-keywords: [specdev, 软件研发, 设计, spec, tickets, 寻路, TDD, 实现, 审查]
+description: 从请求摄入、诊断、设计、规格、决策完备 Ticket、跨 Ticket 编排，到证据驱动实现、架构审查与知识归档的完整研发治理工作流。
+keywords: [specdev, 规格驱动开发, decision-complete, ticket, goal-plan, TDD, 证据, 治理]
 ---
 
 # SpecDev Workflow
 
-本文件是 `specdev` 的唯一入口——包含运行时根、持久化约定、启动协议、状态字段、路径分配、副作用边界以及 work 条目索引。
+SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责清晰的工件链。目标不是让文档尽可能长，而是让每一层拥有明确权威，并让后续模型无需重新决定前一层已经锁定的事项。
 
 ## 运行时根
 
-- **workflow 根**（`{roots.workflows}`）解析为 `<Path>{roots.workflows}/specdev/</Path>`，指向 work 入口和子文件所在目录
-- **state 根**（`{roots.state}`）解析为 `<Path>{roots.state}/specdev/</Path>`，指向持久化状态和变更产物所在目录
+- 工作流根：`<Path>{roots.workflows}/specdev/</Path>`
+- 状态根：`<Path>{roots.state}/specdev/</Path>`
+
+任何具体文件或目录引用必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。禁止内部相对链接、裸文件名和机器绝对路径。
+
+## 工件链
+
+```text
+外部请求、Issue 或对话
+        ↓
+Triage / Diagnose / Grill / Wayfinder / Architecture Review
+        ↓
+Spec             外部行为、范围、验收合同与关键约束
+        ↓
+Ticket           单一垂直切片的决策完备微计划
+        ↓
+Tickets Map      DAG、合同覆盖、Ready 与并行投影
+        ↓
+Goal Plan        仅在需要时编排跨 Ticket Gate、Wave、owner 与恢复
+        ↓
+Implement        在既定契约内设计、TDD、审查、验证和交接
+        ↓
+Evidence         实际修改、命令、结果、偏差和残余风险
+        ↓
+Archive          归档历史并将经验证知识提升为当前长期知识
+```
+
+核心状态工件：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
 
 ## 持久化约定
 
-在 state 根下维护以下结构：
+`speculo init` 创建固定状态骨架：
+
+- 全局状态：`<Path>{roots.state}/specdev/status.json</Path>`
+- 活跃 change：`<Path>{roots.state}/specdev/changes/</Path>`
+- 历史归档：`<Path>{roots.state}/specdev/archive/</Path>`
+
+初始化设置 work 首次运行时生成：
+
+- 全局配置：`<Path>{roots.state}/specdev/config.json</Path>`
+- 追踪规则：`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
+- 领域布局：`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
+- 状态标签：`<Path>{roots.state}/specdev/.config/status-labels.md</Path>`
+
+经 change 产物确认后按需创建：
+
+- 永久 ADR：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 永久研究：`<Path>{roots.state}/specdev/research/</Path>`
+
+单个 change 可以包含：
+
+- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+## 全局治理原则
+
+1. **先发现、后询问**：仓库、配置、schema、测试和文档能回答的事实先探索；只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
+2. **规划深度随风险增长**：Lite、Standard、Deep 由复杂度和事故半径决定，不由文档长度决定。
+3. **Ticket 是微型计划**：每个 Ready Ticket 决策完备，但不展开逐行代码。
+4. **Goal Plan 按需出现**：只在跨 Ticket 编排复杂度需要时生成，不以固定章节数量作为质量标准。
+5. **证据优先**：每个验收合同、Ticket 和 Gate 都必须有可重复验证与 Evidence。
+6. **路径所有权**：并发实现者只能修改授权项目路径；shared path 有唯一 owner。
+7. **偏差显式化**：计划与事实冲突时停止、记录、修订，不静默扩大范围或改写契约。
+8. **状态单一来源**：Ticket frontmatter 是单 Ticket 状态权威；Map 和 Goal Plan 是投影与编排。
+9. **知识以当前真相为目标**：归档保留历史，永久知识只保留仍真实且经实现验证的结论。
+10. **恢复依赖权威工件**：跨 Work 或 Agent 边界时同步 `current_work` 与 `work_history`，返回下一 Work 和权威工件的完整路径。
+
+共享规则：
+
+- `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
+- `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
 
-| 名称 | 路径 | 说明 |
-|------|------|------|
-| 状态索引 | `<Path>{roots.state}/specdev/status.json</Path>` | workflow 全局状态 |
-| 工作流配置 | `<Path>{roots.state}/specdev/.config/</Path>` | 变更追踪、领域文档布局、状态标签映射等配置约定 |
-| 活跃变更 | `<Path>{roots.state}/specdev/changes/</Path>` | 进行中的 change 产物（ADR、LOG、CONTEXT、spec、tickets、map 等） |
-| 永久 ADR | `<Path>{roots.state}/specdev/adr/</Path>` | changes 中经确认后的 ADR 提升至此，始终反映当前架构决策现状 |
-| 永久词汇表 | `<Path>{roots.state}/specdev/context/</Path>` | changes 中经确认后的 CONTEXT 提升至此，始终反映当前领域术语现状 |
-| 永久研究库 | `<Path>{roots.state}/specdev/research/</Path>` | changes 中长期有效的研究产物提升至此，由 A-archive-and-consolidate 维护 |
-| 变更归档 | `<Path>{roots.state}/specdev/archive/</Path>` | 已完成并归档的历史 change，按 YYYY-MM/<change>/ 组织 |
-| 全局配置 | `<Path>{roots.state}/specdev/config.json</Path>` | 交互语言、报告语言与持久化设置，由 I-init-setup 生成，各 work 启动时读取 |
+## 启动协议
 
-`.config/` 目录包含三个由 `I-init-setup` 生成的配置文件，定义 specdev 各 work 的持久化和行为约定：
+1. 解析 workflow 和 state roots。
+2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`；不存在时运行 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。
+3. 读取 `<Path>{roots.state}/specdev/status.json</Path>`：用户指定 change 优先；唯一活跃 change 直接使用；无活跃时创建；多个候选时请求消歧。
+4. 在 `<Path>{roots.state}/specdev/status.json</Path>` 写入 work 开始记录，并更新当前 change 的 `current_work`。
+5. 只加载当前步骤需要的 work 子文件和共享规则。
+6. 完成后写入产物、运行适用校验、更新状态和 `works_run`。
 
-- **`tracking.md`** — 变更追踪约定：变更目录的命名规范（`<YYYY-MM-DD>-<topic>`）、目录结构、`status.json` 机制、归档规则
-- **`domain-layout.md`** — 领域文档布局：三文件模型（CONTEXT.md / ADR.md / LOG.md）的路径解析规则和读取顺序
-- **`status-labels.md`** — 状态标签映射：五个标准角色（`needs-triage` / `needs-info` / `ready-for-agent` / `ready-for-human` / `wontfix`）的标签字符串、状态流转图和自定义方式
+## 状态字段
 
-`status.json`、`changes/`、`archive/`、`adr/`、`context/`、`research/` 均随骨架由 `speculo init` 创建；后三者初始为空——changes 中的 ADR、CONTEXT、研究产物经确认符合当前现状后提升至此，始终保持与项目当前状态一致。
+`<Path>{roots.state}/specdev/status.json</Path>` 使用 schema v3：
 
-## 启动协议
+- `schema_version`（数字）：状态 schema 版本，固定为 `3`。
+- `workflow`（字符串）：workflow 标识，固定为 `"specdev"`。
+- `active`（对象数组）：当前活跃 change；每项包含：
+  - `change`（字符串）：change 目录名，格式 `"YYYY-MM-DD-<kebab-topic>"`。
+  - `current_work`（字符串或 null）：当前 work id，如 `"specdev/implement"`；无运行中 work 时为 null。
+  - `works_run`（字符串数组）：已运行的 work id。
+  - `result`（字符串或 null）：整体结果；进行中为 null，结束时记录 `"completed"`、`"blocked"` 或 `"cancelled"`。
+  - `claimed_investigations`（对象数组，可选）：并行调查领取记录；每项包含 `id`、`owner`、可选 `session` 和 `claimed_at`。
+- `work_history`（对象数组）：work 调用记录；每项包含 `change`、`work_id`、`started_at`、`completed_at` 和 `result`。
+- `completed`（对象数组）：已归档 change；每项包含 `change`、`archived_at` 和 `archive_path`。
 
-1. **解析运行时** — 解析 workspace 配置和 workflow/state roots。已解析时复用。
-2. **选择 change** — 读取 `<Path>{roots.state}/specdev/status.json</Path>`：
-   - 用户指定 → 在 `active` 数组中查找匹配 `change` 字段的条目
-   - 唯一活跃 change → 直接使用 `active[0]`
-   - 无活跃（`active` 为空数组）→ 创建 `changes/<YYYY-MM-DD>-<kebab-topic>/`，追加条目 `{ change, current_work: null, works_run: [], result: null }` 到 `active`
-   - 多个候选 → 列出 `active` 中各 change，由用户消歧
-   - 例外：`T-triage` 分诊外部 issue 时默认总是创建新 change，仅用户声明续作时复用活跃条目（见 T-triage 步骤 3）
+`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `worktrees` 保存 Ticket 级 `base_sha`、分支、可迁移 `workspace_ref` 和生命周期状态。
 
-## 状态字段
+领域状态枚举：
 
-`<Path>{roots.state}/specdev/status.json</Path>` 包含以下字段：
-
-- **`schema_version`**（数字）— 状态 schema 版本号，当前为 2
-- **`workflow`**（字符串）— workflow 标识，固定为 `"specdev"`
-- **`active`**（对象数组）— 当前活跃 change 的状态条目，每个条目包含：
-  - `change` — change 目录名，格式 `"YYYY-MM-DD-<topic>"`
-  - `current_work` — 该 change 当前正在执行的 work id，如 `"specdev/grill-with-docs"`。无正在执行的 work 时为 null
-  - `works_run` — 该 change 已执行过的 work id 列表
-  - `result` — 该 change 的整体结果：null（进行中）或 `"completed"`（全部 work 已完成）
-  - `claimed_tickets` —（可选，W-wayfinder 使用）当前被领取的 ticket 名称列表，用于并发会话跳过
-- **`work_history`**（对象数组）— work 调用记录，每条包含：
-  - `change` — 所属 change 目录名
-  - `work_id` — work 标识
-  - `started_at` — 开始时间（ISO 8601）
-  - `completed_at` — 完成时间（ISO 8601），未完成时为 null
-  - `result` — 完成结果，如 `"completed"`、`"aborted"`
-- **`completed`**（对象数组）— 已归档 change 记录，每条包含：
-  - `change` — change 目录名
-  - `path` — 归档前 change 目录的相对路径
-  - `archived_at` — 归档时间（ISO 8601）
-  - `archive_path` — 归档目标路径的相对路径
-
-### Per-change 状态文件
-
-每个 change 目录内维护 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`，追踪该 change 的个体状态：
-
-- **`change_status`**（字符串）— change 生命周期状态：`"active"`（进行中）、`"completed"`（全部 work 完成）、`"archived"`（已归档）
-- **`created_at`**（ISO 8601 字符串）— change 创建时间
-- **`completed_at`**（ISO 8601 字符串或 null）— change 完成时间，进行中时为 null
-- **`archived`**（布尔值）— 是否已归档，默认 false
-- **`archive_path`**（字符串或 null）— 归档目标路径的相对路径，未归档时为 null
-
-创建 change 时由首个 work（如 `T-triage` 步骤 3 或 `G-grill-with-docs` 步骤 1）写入初始 `.status.json`，`change_status` 初始为 `"active"`。change 内所有 work 完成后，由最后一个 work 更新 `change_status` 为 `"completed"`。归档时由 `A-archive-and-consolidate` 更新为 `"archived"`。
+- change：`active | blocked | completed | archived`
+- Ticket：`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
+- Investigation：`open | claimed | confirmed | disproved | decision-needed | unresolved | superseded | cancelled`
+- Planning Depth：`lite | standard | deep`
+- Worktree：`planned | active | review | integrated | removed | blocked`
 
 ## 路径分配
 
-1. 产物写入当前 change 目录（`<Path>{roots.state}/specdev/changes/{change}/</Path>`）
-2. 领域文档（ADR.md、LOG.md、CONTEXT.md）由 `G-grill-with-docs` 维护
-3. Spec、tickets、map 等产物由对应 work 写入当前 change 目录
-4. 项目代码、测试写入项目相对路径，验证指针记录到 change
-5. 所有引用使用 `<Path>{roots.workflows}/specdev/...</Path>` 或 `<Path>{roots.state}/specdev/...</Path>` 格式，不引用外部
+1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
+2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
+3. 项目代码、测试和用户要求的项目文档写入项目路径；Evidence 仅保存项目相对指针。
+4. 长期知识先在 change 内形成，经确认后提升到对应永久 namespace。
 
 ## 副作用边界
 
-确认前不得执行：提交代码、合并/删除 worktree、发布/部署。结果记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。敏感值不得写入。
+未经用户明确授权不得提交、推送、合并、删除分支或 worktree、部署、发布、移动归档或执行不可逆迁移。只读探索、生成 change 工件和已授权验证可以进行。敏感值不得写入 `<Path>{roots.state}/specdev/</Path>`。
 
 ## Work 条目
 
-work id 格式为 `specdev/<work-name>`，其中 `<work-name>` 为 work 目录名去掉字母前缀（如 `G-grill-with-docs` → `specdev/grill-with-docs`）。
-
 <!-- 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"
-- **R-review-architecture** — 架构审查：扫描代码仓寻找深层化机会——发现浅模块、接缝泄漏和局部性缺陷，以可视化 HTML 报告呈现候选方案，逐一访谈深化。
-- **S-spec** — 编写 Spec：将当前对话综合为一份完整的 spec 文档，包含问题陈述、解决方案、用户故事、实现决策和测试决策，持久化到变更目录。
-- **T-tickets** — 拆分 Tickets：将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
-- **T-triage** — Issue 分诊：将外部 issue 摄入并分诊为本地 change：深度理解上下文后写入 source-issue.md 与 triage.md，再推荐下一 work（G-grill / S-spec / I-implement / D-diagnose 等）。
-- **W-wayfinder** — 寻路：为超出单次会话容量的大块工作绘制共享地图，逐个解决调查 tickets 直到通往目标的路径清晰可见。支持研究和决策型 ticket 类型。
+- **A-archive-and-consolidate** — 归档与沉淀：在验证完成和用户授权后归档 change，并以证据判断哪些架构决策、术语和研究应创建、合并、替代、废弃或不提升。
+- **D-diagnose-bugs** — 诊断 Bug：通过复现、反馈回路、可证伪假设与最小插桩定位根因，输出修复契约而不是猜测性补丁。
+- **E-engineering-cognitive-mentor** — 工程认知导师：面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
+- **G-grill-with-docs** — 设计访谈（带文档）：通过一次一问的设计访谈打磨方案，同时持续维护设计日志、领域上下文和架构决策。
+- **I-implement** — 实现：基于 Ready Ticket 或获批的小型 Spec 执行设计检查、TDD 红绿循环、持续验证、双轴审查、证据回写和提交。
+- **I-init-setup** — 初始化设置：初始化 SpecDev 的语言、配置、全局状态、追踪约定、领域知识布局、验证命令和并发治理。
+- **P-goal-plan** — 目标规划：在协调复杂度需要时，将 Ready Spec、Tickets、架构决策与外部约束综合为决策完备的跨 Ticket 编排计划。
+- **R-review-architecture** — 架构审查：扫描与目标相关的代码区域，识别浅模块、接缝泄漏和局部性问题，以可视化报告呈现候选方案，并通过逐项访谈转化为可执行决策。
+- **S-spec** — 编写 Spec：综合已知事实、设计决定、诊断与代码现状，产出以外部行为和验收合同为权威的 Ready Spec。
+- **T-tickets** — 拆分 Tickets：将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。
+- **T-triage** — 请求分诊：完整摄入外部请求，判断问题类型、影响、风险、缺失信息和下一 work，不在分诊阶段过早设计或实现。
+- **W-wayfinder** — 寻路：为路径未知、跨域或超出单次上下文的工作建立共享调查地图，通过可领取的研究与决策 Ticket 关闭未知项并收敛到可执行路线。
 
 <!-- AUTO-INDEX-END -->
+
+## Common 目录
+
+- 总览：`<Path>{roots.workflows}/specdev/common/README.md</Path>`
+- Rules：`<Path>{roots.workflows}/specdev/common/rules/</Path>`
+- Schemas：`<Path>{roots.workflows}/specdev/common/schemas/</Path>`
+- Tools：`<Path>{roots.workflows}/specdev/common/tools/</Path>`
+- Skills：`<Path>{roots.workflows}/specdev/common/skills/</Path>`
+
+## 自动校验
+
+校验一个 change：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+校验工作流包：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
+```

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

@@ -3,82 +3,146 @@ id: specdev/goal-plan
 type: workflow-entry
 workflow: specdev
 name: 目标规划
-description: 将 spec、tickets 和参考权威综合为一份目标规划文档——编排多 ticket 里程碑的约束、质量门禁和执行协议，桥接"已有 tickets"到"协调执行 20+ tickets"
-keywords: [目标规划, 编排, 里程碑, 门禁, Lead, Subagent, 合同, 参考权威]
+description: 在协调复杂度需要时，将 Ready Spec、Tickets、架构决策与外部约束综合为决策完备的跨 Ticket 编排计划。
+keywords: [目标规划, 编排, DAG, Gate, Wave, Lead, Subagent, 迁移, 证据]
 ---
 
 # 目标规划
 
-组合 work——将 spec、tickets、参考权威和领域上下文综合为一份完整的 goal-plan.md 文档，定义多 ticket 里程碑的约束条件、质量门禁、调度顺序和执行协议。
+Goal Plan 只解决单个 Ticket 无法独立决定的事情：跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版，也不按固定章节数量衡量质量。
 
-产物统一写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。
+产物写入 `<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>` 产出上游产物。
+- 多个 Ticket 可以或需要并行；
+- 存在 shared path、共享合同、集中 owner 或 Lead/Subagent；
+- 存在 Deep Ticket、expand-contract、数据迁移、兼容窗口或不可逆步骤；
+- 存在多个里程碑、外部审批、发布窗口、参考符合性或高事故半径；
+- Ticket DAG 虽不大，但关键路径、汇合点或恢复策略不能仅由 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 安全表达；
+- 用户明确要求正式跨 Ticket Plan。
+
+少量、线性、低风险且路径不冲突的 Ready Tickets 可以跳过本 work，直接由 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 按 Tickets Map 执行。
+
+## 输入
+
+必须读取：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- `<Path>{roots.state}/specdev/config.json</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>`
+- `<Path>{roots.state}/specdev/adr/</Path>`
+- `<Path>{roots.state}/specdev/context/</Path>`
+- 用户提供的合同、标准、参考实现、环境限制、发布窗口与批准策略。
+
+Spec 或 Tickets Map 不存在时，返回 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 或 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`，不得在 Goal Plan 中临时补造上游工件。
 
 ## 流程
 
-### 1. 收集输入与检测模式
+### 1. 验证上游与选择规划模式
 
-读取所有上游产物，检测适用的编排模式。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/input-validation.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/P-goal-plan/planning-modes.md</Path>`：
 
-若上游产物（spec、tickets-map、ADR）引用了不熟悉的外部依赖、技术栈或第三方服务，先调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 了解其能力边界、约束条件和集成方式，再推导编排模式和执行协议。
+1. 验证 Spec Ready、Ticket Ready、合同覆盖、DAG、路径所有权和 Deep Ticket 完整性；
+2. 只读探索会影响调度的代码事实和项目约束；
+3. 识别 coordination、migration、high-assurance、reference-conformance 等可组合模式；
+4. 只对无法发现且会改变 Gate、Wave、owner、迁移或批准点的问题向用户提问；
+5. 不熟悉的外部标准或依赖使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
 
-**完成标准**：上游产物已加载；编排模式已识别（合同模式、参考权威模式、偏差模式、执行模式），输出为模式检测摘要。
+任何硬停止问题都必须退回拥有该决策的上游工件，不得用 Goal Plan 覆盖。
 
-### 2. 编写远景章节（§1-3）
+### 2. 构建跨 Ticket 执行模型
 
-编写 Goal、Authoritative Inputs、Definition of Done 三个远景章节。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/vision-sections.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`：
 
-**完成标准**：§1 目标声明、§2 权威输入优先级表与冲突裁决顺序、§3 六道门禁 DoD 已草拟并经用户确认。
+1. 从 Ticket frontmatter 构建 DAG 和关键路径；
+2. 将 Ready 且项目写路径不相交的 Ticket 分配到 Wave；
+3. 为 shared path、共享合同和集中变更指定唯一 owner；
+4. 为行为闭环、合同稳定、迁移完成、发布就绪等关键状态定义 Gate；
+5. 明确 expand → migrate → contract、Evidence 返回和集成规则；并行写代码时使用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`；
+6. 将每个 Ticket 需要的执行上下文压缩成派单载荷，不复制整个历史对话。
 
-### 3. 编写执行章节（§4-5）
+### 3. 定义整体完成、证据与恢复
 
-编写 Ticket DAG 与调度顺序、单 ticket 执行协议。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/execution-sections.md</Path>`。
+加载 `<Path>{roots.workflows}/specdev/P-goal-plan/completion-control.md</Path>`：
 
-**完成标准**：§4 DAG 图（ASCII art）、并发规则、门禁次序、编号对照表已草拟；§5 八步执行协议（含双轴审查、Lead 纪律、回写规则）已定制并经用户确认。
+1. 将整体目标、非目标和权威来源压缩为一个可审查摘要；
+2. 定义整体 Definition of Done 和每个 Gate 的关闭证据；
+3. 固化跨 Ticket 不可协商约束；
+4. 定义偏差等级、暂停范围、批准人和恢复动作；
+5. 定义进度回报、Evidence 汇总、残余风险和回滚要求。
 
-### 4. 编写治理章节（§6-8）
+### 4. 写入自适应 Goal Plan
 
-编写里程碑级验收、硬约束、进度回报格式。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/governance-sections.md</Path>`。
+使用 `<Path>{roots.workflows}/specdev/P-goal-plan/goal-plan-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。
 
-**完成标准**：§6 五项里程碑验收步骤、§7 非协商硬约束、§8 结构化进度回报格式已草拟并经用户确认。
+模板包含六个职责区，但只保留适用内容：
 
-### 5. 可选——添加 Ticket 速查表（§9）
+1. Outcome and Authority；
+2. Execution Graph；
+3. Gates and Completion Evidence；
+4. Execution and Integration Protocol；
+5. Constraints, Risk and Recovery；
+6. Progress and Decisions。
 
-如果 ticket 数量超过 10 个或用户要求，追加 Ticket 一览速查表。委托给 `<Path>{roots.workflows}/specdev/P-goal-plan/quick-reference-table.md</Path>`。
+Ticket 较多时在 Execution Graph 内增加速查表；不创建独立的第二套状态来源。
 
-**完成标准**：§9 速查表已添加或已确认跳过。
+### 5. 同步与验证
 
-### 6. 写入产物与停止
+1. 将 Wave、Gate 和 owner 投影同步到 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`；
+2. 对照 `<Path>{roots.workflows}/specdev/common/schemas/goal-plan.schema.json</Path>`；
+3. 运行：
 
-将完整 goal-plan.md 写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。更新 `<Path>{roots.state}/specdev/status.json</Path>`：在 `work_history` 中追加条目（含 `change`、`work_id`、`started_at`、`completed_at`、`result`），在 `active` 中更新当前 change 条目的 `works_run` 列表。
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
 
-向用户汇报产物摘要（ticket 数量、门禁层级、合同/参考权威引用、关键约束），明确询问进入实现阶段（`<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`）或需要进一步修订。
+4. 更新 `<Path>{roots.state}/specdev/status.json</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`；
+5. 向用户汇报模式、关键路径、Wave、Gate、shared owner、迁移策略、主要风险和 Ready 状态；
+6. 未经用户要求，不自动进入实现。
 
-**完成标准**：goal-plan.md 已写入变更目录，九章节齐全无残留 `[TODO:]`；status.json 已更新；摘要已汇报给用户。
+## 决策完备标准
 
-## 子文件引用
+Goal Plan 必须让执行 Lead 或实现者无需重新决定：
+
+- 跨 Ticket 先后、并发 Wave 和关键汇合点；
+- shared path 与共享合同的 owner；
+- Gate 开启、关闭和证据；
+- 迁移、兼容、收缩、发布和回滚顺序；
+- Agent 派单上下文、Evidence 返回和集成规则；
+- 偏差等级、暂停范围和批准路径。
 
-本入口及以下子文件按需加载：
+Goal Plan 不应重复：
 
-| 文件 | 内容 | 触发条件 |
-|------|------|----------|
-| `<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 提取行数据的规则 |
+- Ticket 的完整局部执行路线；
+- 每个 Ticket 的全部文件预测；
+- 每条局部验收 checklist；
+- Spec 中的完整用户故事和产品背景。
 
-## 依赖关系
+## 完成标准
+
+- `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 已写入且只包含适用内容；
+- 所有计划内 Ticket Ready，DAG 无环，合同覆盖明确；
+- Wave、Gate、owner、集成、偏差和恢复可执行；
+- Tickets Map 投影已同步；
+- 无未批准高影响假设或硬停止问题；
+- `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 无 error；
+- 用户收到摘要和下一步选择。
+
+## 子文件引用
 
-- **上游输入**：依赖 `<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>` 在实现阶段读取，作为里程碑级约束和门禁次序的权威来源。
+- 规划模式与输入门禁：`<Path>{roots.workflows}/specdev/P-goal-plan/planning-modes.md</Path>`
+- DAG、Wave、Gate 与 Lead 编排：`<Path>{roots.workflows}/specdev/P-goal-plan/orchestration-protocol.md</Path>`
+- 完成、证据、偏差与恢复：`<Path>{roots.workflows}/specdev/P-goal-plan/completion-control.md</Path>`
+- Goal Plan 模板：`<Path>{roots.workflows}/specdev/P-goal-plan/goal-plan-template.md</Path>`
+- 并行 Ticket worktree：`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`