@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-i-implement/references/merge-conflict-protocol.md

@@ -0,0 +1,21 @@
+# Merge / Rebase Conflict Protocol
+
+只在 `git status` 证明仓库正处于 merge/rebase 冲突时加载。
+
+## 流程
+
+1. 读取 Git 状态、操作类型、冲突路径、base/ours/theirs SHA、Ticket/Evidence 与匹配的 candidate integration 记录。
+2. 从 commit、source、Spec、Ticket、ADR、测试和调用者追溯双方意图；信息不足时不猜产品行为。
+3. 对每个 hunk 写出双方意图、共同约束和唯一可推导结果；需要新行为或上层决定时停止并登记 deviation。
+4. 在授权路径内解决文本，运行受影响的非 E2E 检查；candidate checkout 中按 finalize 合同运行父状态检查/E2E。
+5. 匹配的 local candidate integration 授权包含 `git add`、candidate merge commit、必要的 `git merge --abort` 和 transient candidate checkout/branch 生命周期；不扩展到来源 branch/worktree cleanup 或远端动作。
+6. 需要改变 Spec/ADR、安全/迁移决定、越过 owner 或无法同时保持既有意图时，在 Lead-created candidate 中执行 `git merge --abort`，记录 blocker 并保留来源 worktree；未知普通冲突现场不擅自 abort。
+7. 重读 Git 状态、parents 与 diff，确认无 marker、无未声明路径、双方合同及验证仍成立。
+
+## 完成标准
+
+- 每个 hunk 可追溯到既有意图；
+- 新产品决定没有藏在冲突解决中；
+- 验证记录命令、运行环境、退出码和摘要；
+- Git 副作用来自明确的 candidate integration 或其他逐动作授权；
+- 完成/暂停可以从 Git、原计划/README 与 Evidence 恢复。

package/template/workflows/specdev/specdev-i-implement/references/tdd-rules.md

@@ -0,0 +1,25 @@
+# TDD 红绿规则
+
+1. 从 Ready Ticket/Spec 选择下一条最小可观察行为，并写下已确认 seam。
+2. 只为该行为编写一个会因目标能力缺失而失败的测试或验证。
+3. 运行并观察红灯；失败原因必须是目标行为缺失，而不是语法、夹具或环境错误。
+4. 只写使当前测试通过的最小生产代码，不预测后续切片。
+5. 运行定向测试并观察绿灯，记录命令与结果。
+6. 进入下一条窄垂直切片；周期性运行受影响回归。
+
+重构不属于红绿循环。全部目标行为完成并经过双轴 review 后，才进入独立修正/重构阶段，并重跑受影响 review 轴与验证。
+
+## 完成门
+
+- 每个切片有对应 red 和 green 证据；
+- 一个循环只有一个 seam、一个测试和一个最小实现；
+- 测试没有通过删除、跳过、吞错或放宽断言制造绿色；
+- review 前没有以“顺手重构”扩大切片。
+
+## 强制变异验证
+
+使用强制变异时，先保存基线 hash/diff，修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效；编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff，把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/specdev-d-diagnose-bugs/SKILL.md</Path>。
+
+## 纯说明与测试承接
+
+纯文档按 <Path>{roots.workflows}/specdev/specdev-i-implement/references/documentation-procedure.md</Path> 执行适用验证，不伪造代码红绿；prompt/tool/output 改动仍属行为。旧测试删除必须覆盖其行为、错误、兼容和回归义务，具体按 <Path>{roots.workflows}/specdev/common/rules/test-reliability.md</Path>。

package/template/workflows/specdev/specdev-i-init-setup/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: specdev-i-init-setup
+description: "发现项目事实与必要偏好；仅在明确请求时建立当前工程 docs 基线，不预造业务状态骨架。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/init-setup
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 初始化设置
+
+读取 <Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>，按 <Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path> 定位相关条目，明确项目、方法和数据根；直接使用无需 workspace 或 CLI。已有安装验证真实 roots，冲突只阻塞有关写入。普通 Work 不必先经过本入口。
+
+## 流程
+
+1. 只读探测包管理、workspace、构建/测试/类型/lint/CI、默认父分支、实际 worktree 与项目指令；定位真实入口和共享高冲突资源。未知验证命令保持未知，不凭框架名称编造。
+2. 区分可用、未安装、未配置、未授权、不适用并注明依据。复用用户语言、工具、产物数量及已有配置；只问无法从仓库得到且实际影响当前任务的偏好。探测不自动安装依赖、发布或创建虚假 change。
+3. 实际需要写入偏好或工具配置时读取 <Path>{roots.workflows}/specdev/specdev-i-init-setup/references/first-setup.md</Path>。已有真实 GitHub/验证配置继续使用其 schema，不删除未知独有字段。无需求不创建 config、tracking、domain-layout、空知识目录、全局 status 或 change status。
+4. 仅明确要求工程文档基线/全面理解代码时，直接使用 <Path>{roots.references}/writing-for-agents/references/current-facts-docs.md</Path> 的六步与覆盖表。最小 docs README/architecture 或已有负责正文导航，说明 HEAD/未提交或非 Git 范围、覆盖/未知/排除与实际验证；不改永久知识、不推进 docs-sync 基线。
+5. 回读本次实际写入，报告已确认事实、必要偏好来源、验证命令/退出码和未知。只读调用无文件；有 change 的结果写回原 README/Evidence，不登记 Work 调用镜像。
+
+## 停止与保全
+
+未知 schema、旧活动或混合协议保留原件并交显式转换，不从初始化偷偷迁移。CLI 安装元数据与 back 不归本 Work。已有知识、用户配置和历史不覆盖；只读发现不证明方法已安装或业务已验收。
+
+只有确实创建 worktree 时核对 `specdev-worktree/` 的忽略项与 owner：已安装的 CLI-managed 忽略项交 CLI 修复；直接模式按项目 owner 的真实授权维护，不能因没有 CLI 阻塞其他初始化事实发现。
+
+## 可选项目编排选择
+
+只有用户要求持久化编排偏好时，依据 <Path>{roots.references}/coordination/project-facts.schema.json</Path> 写入 <Path>{roots.state}/coordination/project.json</Path>，先读 <Path>{roots.references}/coordination/coordination-contract.md</Path>。配置缺失默认 Lead；不探测、安装或要求外部工具，选择不是授权凭证。只读调用不生成配置。

package/template/workflows/specdev/specdev-i-init-setup/assets/change-readme-template.md

@@ -0,0 +1,32 @@
+# <本次目标>
+
+Outcome: active
+
+<a id="scope"></a>
+## 目的与范围
+
+<当前单一目标、授权写集、IN/OUT、真实请求出处和约束。独立 <Path>{roots.state}/specdev/changes/{change}/spec.md</Path> 已负责规格时删除本模板 scope/acceptance/verification 并改为导航，不维护两套权威。>
+
+<a id="acceptance"></a>
+## 验收
+
+- [ ] AC-1：<可观察、可判定行为及验证方式>
+
+## 当前工作
+
+<简单任务清单与接续点；若使用无票 Goal 或独立 Ticket，则这里只导航其负责清单，不复制进度。>
+
+<a id="verification"></a>
+## 验证依据
+
+<尚未执行时如实描述缺口，不预填 passed。完成后每 AC 一个实际结果行：>
+
+| AC | Result | Evidence |
+|---|---|---|
+| AC-1 | <实际结果> | <#独立证据锚点或对象内文件 locator> |
+
+<需要校验原件摘要时可增加 SHA256 列，填写实际计算结果；非必需。真正执行后才在独立证据段记录 Method、Source、Observed、Result；有 Command 须有真实 Exit。>
+
+## 下一步
+
+<下一 owner、入口、阻塞与恢复限制；没有实际交接不建空 ownership/批准槽。>

package/template/workflows/specdev/specdev-i-init-setup/assets/config-template.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": 7,
+  "interaction_language": "zh-CN",
+  "artifact_language": "zh-CN",
+  "git": {
+    "default_branch": null
+  },
+  "execution": {
+    "max_concurrent_implementations": 3,
+    "max_integration_attempts": 3,
+    "deep_ticket_human_approval": true,
+    "shared_path_owner": "explicit"
+  },
+  "verification": {
+    "test": null,
+    "typecheck": null,
+    "lint": null,
+    "build": null
+  },
+  "planning": {
+    "default_depth": "standard",
+    "require_ready_gate": true,
+    "require_evidence": true,
+    "ui_design_default_candidates": 3,
+    "ui_design_max_candidates": 4
+  },
+  "github": {
+    "include_external_prs": false,
+    "labels": {}
+  }
+}

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

@@ -0,0 +1,29 @@
+# 领域文档布局
+
+## 按当前问题定位
+
+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>`
+
+UI 范围先按 scope/规则 ID 定位 <Path>{roots.state}/specdev/design/</Path>，再读取 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path> 固定的 baseline revision 与批准原型；不展开无关设计规则。
+
+## 职责
+
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`：当前 bounded context 的项目规范术语和 `_Avoid_` 同义词；不保存代码导航或 change 历史。
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`：当前 change 已接受、被替代或废弃的架构决策。
+- <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>：当前 change 的已批准视觉/交互合同，P 拥有；原型包只拥有源码和证据。
+- <Path>{roots.state}/specdev/design/DESIGN.md</Path>：A 网关拥有的项目设计基线；仅在批准的首次发布时创建，不预造空目录。
+- `<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 完成后，只有仍真实、跨 change 有用且有实现证据的规范术语、合格 ADR 或可复用设计规则才可由 A 提升。首次设计 approved-intent 基线在 HTML 集中确认后经 A 设计网关发布，不能宣称已实现；具体遵循 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path>。
+
+当前工程事实按主题读取 <Path>{roots.state}/docs/README.md</Path> 的负责正文导航；缺失不阻塞普通 Work，只有明确请求才建立基线。

package/template/workflows/specdev/specdev-i-init-setup/assets/tracking-template.md

@@ -0,0 +1,13 @@
+# 变更追踪约定
+
+SpecDev 只使用本地 Markdown/JSON 工件跟踪开发。远程 Issue、URL 或指定内容必须先由 Triage 冻结为 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`；远程状态、label、assignee 和 dependency 不替代本地 change、Ticket、Map、Goal Plan 或 Evidence。
+
+- 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/changes/{change}/README.md</Path> 顶层唯一 Outcome 表示整体 active/completed/cancelled；归档由实际目录位置与回执表示。
+- Ticket 文件是 Ticket 状态权威；`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 只作导航、依赖和覆盖图，不复制进度。
+- 简单任务由 README 清单负责；无票 Goal 由计划清单负责；有票由 Ticket/Evidence 负责，其他位置仅导航。
+- 完成条件：全部必需 Ticket 为 `done` 或有批准的 `cancelled`，证据齐全，无未批准 deviation，change 级验证通过。
+- 归档后的 `<Path>{roots.state}/specdev/changes/archive/{change}/</Path>` 默认只读；后续纠正通过新 change 和 supersedes 链完成。
+- 可关闭的远程来源在本地完成后由 Triage reconcile；`closed`、显式 `waived` 或 `not-applicable` 后才归档。完成后若要把 Ticket 记到 GitHub，由 T-triage publish 写入 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`；`pending`/`publish-failed` 不可归档。尚未成 Change 的记事项由 T-triage capture 写入 `<Path>{roots.state}/specdev/capture.md</Path>`（缺失合法），Issue 保持 open，不创建 change。发布计数与 inbox 计数都以对应本地账本为准，标签词表见 T-triage classification-map。远程 Issue 仍不是开发权威。

package/template/workflows/specdev/specdev-i-init-setup/references/change-record-examples.md

@@ -0,0 +1,62 @@
+# 按需 owner、验证与取消记录
+
+只在相关动作需要可回读证据时采用；不是每 Work 的默认表单。占位文本不是实际证据，也不创造批准。
+
+## 简单任务的原 owner
+
+无 Goal 时，README 可用以下段落绑定实际会话依据。复杂任务使用原 Goal/Implementation Plan 的 lead，不再复制：
+
+```markdown
+## Ownership
+
+Owner: session:actual-locator
+Evidence: #handoff
+
+<a id="handoff"></a>
+## 本次会话依据
+
+Session: session:actual-locator
+Source: 用户请求或真实交接的可回读来源
+Observed: 实际接受的目标、范围和当前负责关系
+```
+
+需要绑定 P bootstrap 时，Ownership 与原会话依据都保存 `Work: specdev/prototype`；仅此实际动作需要，不逐 Work 更新镜像。Evidence 不得指回 Ownership 自身。
+
+## 真实验证后记录
+
+```markdown
+<a id="verified-ac-1"></a>
+## AC-1 观察
+
+Method: 实际使用的验证方法
+Source: 被检验源码/工件与实际输入的 locator
+Observed: 实际输出、结果与覆盖边界
+Command: 确实执行的命令（未执行命令则省略本项）
+Exit: 0
+Result: passed
+```
+
+README verification 的 AC-1 行引用 `#verified-ac-1`；可以引用原 Evidence 的对应段。不以声明 passed 替代真实运行；提供 SHA256 时工具严格匹配原件字节，缺摘要能力不编造值。
+
+## 整体取消
+
+用户确实取消后，保留独立原请求/交接依据，再按原完成 owner 核对下面字段。实际无某项时写有理由的 none，尚未知不能写 resolved。
+
+```markdown
+<a id="cancellation"></a>
+## 取消说明
+
+Source: #actual-cancellation-request
+Scope: 实际取消范围
+Time: 2026-10-14T10:00:00+08:00
+Confirmed-By: session:actual-locator
+Undelivered: 尚未交付的需求
+Landed: 已落地代码、数据、设计与远程影响
+Writers: none: 实际核验没有活动写入者的依据
+Dependencies: none: 没有父子依赖的依据
+Checkpoints: resolved: 未集成 checkpoint/candidate 的实际处置
+External: waived: 已承诺外部动作经具体决定放弃的依据
+Next: 后续 owner、保留材料和恢复限制
+```
+
+Writers 有过实际写入者时用 `stopped: <证据 locator>`，原件须有 `Writers: stopped` 和真实 Observed；超时不是停止。Dependencies/Checkpoints/External 允许 none/resolved/transferred/waived，但都要具体依据。全部核对通过后才将唯一 Outcome 改 cancelled，不批量改票、不回滚或关闭远程。

package/template/workflows/specdev/specdev-i-init-setup/references/first-setup.md

@@ -0,0 +1,11 @@
+# 必要偏好与真实工具配置
+
+只有当前任务确需持久化偏好或工具设置时读取；不是缺少文件即补全骨架。
+
+语言、用户工具和明确产物数量复用当次请求或现有项目说明。实现并发、worktree、集成尝试上限只在原 Goal/Implementation Plan 真正启用时明确，由计划 `## Execution Policy Source` 记录实际来源；默认 current 单写入者。Lead 自己实现计入实现并发，只读协作者不设新数字上限。UI 缺省 3、配置 2–4、用户明确数量覆盖上限；一次 override 留当前设计包，不改全局偏好。
+
+现有 <Path>{roots.state}/specdev/config.json</Path> 中 GitHub labels/include_external_prs、验证/planning 等真实消费者配置，可按 <Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path> 验证和保留；只有确需该工具时才创建，必要结构参考 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/config-template.json</Path>。不把旧配置整份机械改写为 config.md；未知独有字段保留并报告。无标签只阻塞相关远程写入。
+
+任何配置更新先核对实际差异和授权，不保存秘密或凭据，不存全局自动 commit/集成/发布开关。未知验证命令为 null/未知，必须有仓库或真实用户来源。既有无效/未知 schema 不重置、不迁移；显式转换由原 owner 执行。
+
+change/ADR/context/docs/archive/design 等只在真实首次内容写入时创建；不生成 status、change status、空知识树、空批准槽或跟踪镜像。项目说明确需导航时可使用 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/tracking-template.md</Path> 与 <Path>{roots.workflows}/specdev/specdev-i-init-setup/assets/domain-layout-template.md</Path> 的相关内容，不要求输出两份配置文档。工程 docs 基线由入口的共享事实方法负责。

package/template/workflows/specdev/specdev-l-learn-change/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: specdev-l-learn-change
+description: "在开发完成后围绕当前 SpecDev change 回答问题，并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/learn-change
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# Change 学习：给零基础新生的图解
+
+激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。只解释当前 change 已验证的实现与测试事实，不作产品/架构决定或授予实现权限。
+
+## 执行
+
+1. **选择现有 change**：使用用户指定或唯一未归档 change；没有时返回缺失输入，不创建空 change。只读归档不追加学习材料。恢复依据留原学习索引与当前 README 导航；不把 completed/cancelled 重新打开为开发中。
+2. **确定主题**：使用 `$ARGUMENTS` 调用参数或用户最新问题；缺少时只询问主题。读者是刚入大学、零专业背景的新生，先确定“它是什么、为什么需要、怎样流动或被调用”三个答案。
+3. **定位事实**：按主题读取 Source、Spec、Ticket、Evidence、review、实际代码/测试与可靠来源。区分已验证事实、类比与未知；旧计划和实现冲突时明确差异，以当前代码、测试、Evidence 为实现事实，不让类比代替证据。
+4. **生成与保存**：读取 `<Path>{roots.workflows}/specdev/specdev-l-learn-change/references/lesson-format.md</Path>` 的完整格式和命名合同。先画 ASCII 全图，再按实际关系画短小结构/数据/调用/状态图；用短句解释箭头，术语先日常解释再给专业名字。验证零背景读者能复述三个答案；不能时拆图或换词，不灌长文。
+5. **追加而非覆盖**：从 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 及同目录真实图解的最大编号取下一号；先原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 新图解，再更新索引并回读。重讲同主题仍新增编号，保留旧文件、原顺序和全部历史行。产物仅为纯 Markdown/ASCII，不生成 HTML、CSS、SVG、图片或浏览器依赖，不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
+
+## 事实、理由与解释
+
+图解中明确已验证实现事实、可定位设计理由、教学类比与未知。讲解失败或恢复时引用实际契约与证据，不编造事故；旧计划与现状不同要指出差异，不把提案当事实。重新讲同主题仍追加新编号，不覆盖历史，不改 Learning workflow，也不把理解总结直接晋升永久知识。
+
+## 验收与恢复
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn-change <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+图解符合格式参考的四节、至少一个 ASCII 图和连续编号；索引指向真实新文件且主题/简介一致，箭头方向与事实相符。验证通过后回读并返回新图解和索引完整路径，必要接续留原学习载体。失败保留恢复位置与原因，不改变 change 原有开发完成状态。

package/template/workflows/specdev/specdev-p-goal-plan/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: specdev-p-goal-plan
+description: "为简单目标、单个已拆票 change 或多个 Ready change 规划、执行或恢复 Goal；只在用户要求目标计划、交付编排或已有 map 需推进时使用，不代替需求探索和 Ticket 编写。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/goal-plan
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# Goal 规划与执行
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。P 是统一 Goal 入口；G 仍是 Grill，跨 change 由本入口统一编排。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`，定位用户指定的 change 或 map，再读 README Outcome、实际存在的计划和所选模式。有票时每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据；不默认通读所有 Ticket 或永久索引。
+
+用户要求简单 Goal 且无需独立 Ticket 时，按 <Path>{roots.workflows}/specdev/specdev-p-goal-plan/assets/lightweight-goal-plan-template.md</Path> 的显式轻量形态，以原 goal-plan 清单负责进度与整体门，README 保留范围/AC/验证，README 只导航；不制造 Ticket/Map。发生真实并行、Deep 或跨 change 时切入完整模式并将迁出的清单改为导航。
+
+## 按意图选择模式与权威
+
+轻量 Goal 的 plan/run/resume/verify 直接使用轻量模板规定的原 Tasks、整体验证和接续章节；replan 只调整实际受影响清单，并保留原授权和已完成证据。不得为通过下表完整模式的 map 控制而制造 Ticket/Map；复杂程度已超出轻量限制时先明确升级。下表及票级编排规则仅用于已有独立 Ticket 或跨 change 的完整模式。
+
+| 用户意图 | 模式 | 必须按需读取 |
+|---|---|---|
+| 制定目标计划，尚未授权实现 | `plan`（默认） | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-lifecycle.md</Path>`；单 change 再读 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/single-change-plan.md</Path>`，多个 change 再读 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/multi-change-plan.md</Path>` |
+| 明确要求按计划实施 | `run` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-lifecycle.md</Path>` 与 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/map-control.md</Path>` |
+| 继续既有目标 | `resume` | 同上，先校验版本、owner、授权和未闭合事务，再恢复；不重复已完成副作用 |
+| 上游变更使计划失效 | `replan` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/replan-and-recovery.md</Path>` |
+| 整体检查与关闭 | `verify` | `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/completion-control.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` |
+
+有独立票的单 change 以 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 为用户总控入口；Ticket frontmatter 仍是单票状态、依赖、路径的权威，Goal Plan 拥有跨票 Gate、Wave 和授权引用。少量线性票不强制增加厚重计划。
+
+单 change 的 Map 结构就绪、Goal 全局执行门与逐票 DoR 分开判断。等待上游真实产物的未来票可保持 draft，并记录缺口和重审条件；独立 Ready 票仍可进入 frontier。具体门禁读取 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/planning-modes.md</Path>`。
+
+多 change 复用现有父 Implementation Map/Implementation Plan 和组合 DAG，不迁走活动状态。父 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 仅作无状态入口，模板为 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/goal-tickets-map-template.md</Path>`。父成员至少两个；只有一个 change 时使用单 change 模式。
+
+## 执行底线
+
+- 先冻结 Outcome、权威来源、用户指定的交付数量、范围、Definition of Done 和失败停止条件；按风险确定 DAG/Gate/Wave，不用文档长度替代质量。
+- 固定 `lead-directed`。完整 Goal 的 `concurrent_implementation_limit` 由 Execution Policy Source 说明，实际存在 config 时不超过其有效上限与宿主能力；只读审查没有新增数字上限。进入派单前读取 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/lead-orchestration.md</Path>`。
+- 保留原 worktree 选择：未明确时询问，默认 current 严格串行；required 才使用独立 worktree 与 candidate-merge。用户已答过不重复问。默认工具、数量、提交与集成权限均不因入口合并改变。
+- `plan` 只形成计划，缺少执行授权是计划中可见的待满足条件，不等于获准执行。运行前逐项核对真实授权；文档中的“已批准”不构成授权。
+- 当前票必须调用所绑定的真实 Skill，不能以“读过入口”替代；先读取 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。缺失必需 Skill、引用或验收证据时阻塞本票及依赖它的分支。
+- 他人 owner、资源或事务冲突仅暂停受影响的依赖闭包；继续独立已授权工作，不抢占、解锁或覆盖他人内容。正式记忆仍只走原网关。
+- 调度调用 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`；调度器不代替实现、审核或授权。长期运行指可恢复，不承诺后台或无限运行。
+
+## 证据复用与停滞恢复
+
+验证复用按 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path> 核对代码、配置、输入、Skill、环境和原输出；只使受影响证据失效。升级兼容、迁移、用户可见行为或性能测量仅在风险相关时成为 Goal Gate，不增加普遍必跑流程。
+
+保留原无进展停止：同一 blocker 没有新证据时不重复派发。新 Dispatch 必须说明输入、方法、范围、环境或责任处置的实质变化；换 Agent 或清空 attempts 不是变化。恢复仍核对原授权、owner、当前 Lead 身份 和未决副作用，不接管他人资源。
+
+## 校验与交付
+
+轻量 Goal 以 `--stage goal-plan` 验证显式 `artifact: lightweight-goal-plan`、原 README 规格和轻量章节；完成时逐项回读实际任务、README AC 证据与整体门，按 change-completion 决定 Outcome，不运行不存在的 map。完整模式从 map 运行只读控制检查（它不执行代码或授予写权限）：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --map <map-path> --repo <project-root>
+```
+
+再以 `--stage goal-plan` 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`：单 change 要求自己的 Goal Plan，合法 draft 可通过结构校验；存在任一父 Map、Plan 或父入口时校验完整父编排，残缺父工件不得回退单 change。校验通过不授予执行权限。完成时回读真实源、map、Ticket 状态和 Evidence，报告完成/阻塞/失效票、整体验收、实际交付数量、验证命令、未执行项与恢复路径。票全 done 不等于 Goal 自动完成。
+
+## 编排与执行上下文
+
+Lead 自行执行或当前阶段需要交接任务时，读取 <Path>{roots.references}/coordination/coordination-contract.md</Path>，按用户指定的 Lead、Orca、Herdr 或无头 CLI 方式操作。只读取所选工具的当前指南；不固定编程工具或模型。
+
+`lead` 上下文维护原业务状态和 Evidence；`task` 上下文只处理 Lead 指定目标和阶段，执行同一方法并返回候选、findings、检查和未验证项，不修改正式 Ticket、Map、Goal、Evidence，不递归启动 Goal 或交接其他任务。未曝光到宿主列表不影响读取真实入口。
+
+P 在已授权 run/resume 中完成当前实现、审查、验证和同范围修复后继续下一 Ready 任务，不逐票询问“继续”。只读分析或 plan 不执行。独立审查 required 时不能以 Lead 自审替代。

package/template/workflows/specdev/specdev-p-goal-plan/assets/goal-plan-template.md

@@ -0,0 +1,150 @@
+---
+schema_version: 7
+artifact: goal-plan
+change: <YYYY-MM-DD-topic>
+status: draft
+modes: []
+orchestration: lead-directed
+lead: <owner-or-session-locator>
+concurrent_implementation_limit: 3
+integration_attempt_limit: 3
+ticket_workspace_policy: current
+integration_gate: direct-parent
+ready_for_execution: false
+---
+
+# Goal Plan: <标题>
+
+- **Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **Tickets Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **Ticket 目录：** `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- **Evidence 目录：** `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+
+## 1. Outcome and Authority
+
+### Outcome
+
+### Success and False Completion
+
+### Non-goals
+
+### Authoritative Inputs
+
+| 优先级 | 来源 | 负责内容 | 冲突处理 |
+|---|---|---|---|
+| 1 | 用户最新明确决定 | 产品取舍与批准 | 更新真正拥有该决策的工件 |
+| 2 | `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 当前 change 架构决定与领域语义 | 返回 `<Path>{roots.workflows}/specdev/specdev-g-grill-with-docs/SKILL.md</Path>` 更新真正 owner |
+| 3 | `<Path>{roots.state}/specdev/adr/</Path>` 与 `<Path>{roots.state}/specdev/context/</Path>` | 已毕业的永久决定与领域知识 | 当前 change 替代时在 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 明示 |
+| 4 | `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` | 外部行为、范围与验收 | 下游不得改写 |
+| 5 | `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` | 单 Ticket 契约 | Goal Plan 只编排 |
+| 6 | `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>` 与当前代码/运行事实 | 已验证根因、现状与可行性 | 冲突时触发偏差并返回真正 owner |
+
+## 2. Execution Graph
+
+### DAG and Critical Path
+
+```text
+...
+```
+
+### Waves and Ownership
+
+| Wave | Ticket | 前置条件 | 项目写路径 | Shared owner | Gate/集成序号 |
+|---|---|---|---|---|---|
+
+### Ticket Quick Reference
+
+未来 draft 票在原 Ticket 的未决问题中记录待交付的上游产物、生产者 Ticket、所需证据和 DoR 重审条件。此表只导航原 Ticket/Evidence；状态、Ready、执行 owner 与工作区结果不复制到 Goal，不以 Goal Ready 代替逐票 Ready。
+
+| ID | Ticket | Evidence |
+|---|---|---|
+| T-01 | `<Path>{roots.state}/specdev/changes/{change}/ticket/01-<ticket-name>.md</Path>` | `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` |
+
+## 3. Gates and Completion Evidence
+
+### Overall Definition of Done
+
+### Gates
+
+| Gate | 开启条件 | 关闭证据 | 阻塞范围 | Lead/批准人 | 失败恢复 |
+|---|---|---|---|---|---|
+
+### Contract and Reference Coverage
+
+| 合同或参考要求 | 覆盖 Ticket | 验证接缝 | Evidence | 状态 |
+|---|---|---|---|---|
+
+## 4. Execution and Integration Protocol
+
+### Lead Orchestration
+
+| 项目 | 决定 | 事实依据 |
+|---|---|---|
+| Lead | `<owner-or-session-locator>` | 唯一 SpecDev 状态、Evidence 与父分支 owner |
+| Concurrent implementations | `<concurrent_implementation_limit>`，Lead 实际参与实现时计入；current 始终单 writer | 本计划 Execution Policy Source；核对实际存在的 config、依赖和平台限制 |
+| Integration attempts | `<integration_attempt_limit>` | 本计划 Execution Policy Source；核对实际存在的 config 限制 |
+| Read-only agents | 无 SpecDev 数字上限 | review/research/test-observation，不写状态 |
+| Dispatch | execution-time dynamic | provider/模型/派单按 Ticket 事实选择 |
+
+### Ticket Workspace and Integration
+
+本节拥有跨票工作区策略和集成安排。每票实际 Parent/base、workspace/branch、implementation/source commit、检查/E2E 和 parent result 只记录在原 Ticket Evidence 的 Workspace Execution Record；通过上表导航回读，不在 Goal 再维护一套结果。
+
+当 `ticket_workspace_policy: current` 时，Ticket 必须严格串行。Lead 每次只允许一个 implementation owner 写入当前 workspace；完成非 E2E 检查并形成 commit 后，Lead 在同一父分支/current workspace 运行适用集成检查和 E2E，验证通过后将该 Ticket 的 `result_sha` 记录为其 implementation commit，再开始下一个 Ticket。不得创建 source/candidate worktree。
+
+当 `ticket_workspace_policy: required` 时，Ticket 使用独立 source worktree；source worktree 不运行 E2E，Lead 在最新父分支的 candidate 状态运行集成检查和适用 E2E，通过且父 HEAD 未漂移后才推进父分支。
+
+### Authorization Matrix
+
+| 动作 | 状态 | 目标与条件 |
+|---|---|---|
+| Current workspace Ticket changes | allowed / not-authorized | 仅 current 模式；严格串行，单一 implementation writer |
+| Ticket worktree local changes | allowed / not-authorized | 仅 required 模式；限 writable/shared owner 合同 |
+| Implementation commit | allowed / not-authorized | 每 Ticket 必需；缺失则 Plan blocked |
+| Local direct-parent verification and parent update | allowed / not-authorized | 仅 current 模式；Lead 核对 Ticket commit 后继续 |
+| Local candidate integration and parent update | allowed / not-authorized | 仅 required 模式；Lead-only；缺失则 Plan blocked |
+| Push / PR / remote merge | allowed / not-authorized | 不从本计划本地授权继承 |
+| Branch/worktree cleanup | allowed / not-authorized | 成功集成不自动继承 |
+| Deploy / migration / production actions | allowed / not-authorized | 逐动作、目标和条件 |
+
+### Evidence Return
+
+任务执行者 只返回候选事实与 commit；Lead 独立核对并写 Evidence、状态和最终验收。
+
+## 5. Constraints, Risk and Recovery
+
+### Non-negotiable Constraints
+
+### Verification Integrity
+
+记录判卷接缝、基线、禁止的伪绿色方式，以及 current/direct-parent 或 source/candidate 两层验证边界。
+
+### Migration or Release Sequence
+
+### Risks, Monitoring and Recovery
+
+### Deviation Control
+
+遵循 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`。
+
+## 6. Progress and Decisions
+
+### Current Status
+
+只记录本 Goal 独有的当前 Wave/Gate、跨票验收、整体阻塞与下一步；相关 Ticket、implementation/source、candidate/result SHA 与逐票验证只导航原 Ticket/Evidence，不复制状态或结果；不使用主观百分比。
+
+### Pending Decisions and Blockers
+
+### Resume Protocol
+
+恢复时读取 Goal Plan、当前 Ticket 和原 Evidence 的 Workspace Execution Record，并核对实际 Git；从最后通过的父分支 result 或待修正 implementation/source checkpoint 继续。
+
+## Assumptions
+
+只记录低影响且可验证的假设。存在高影响假设时 `ready_for_execution` 必须为 `false`。
+
+
+## Execution Policy Source
+
+<实际项目/本次约定及可回读出处；填写已有并发和集成尝试字段的真实来源。存在 config 时核对其上限；Lead 自己实现计入，current 严格单 writer。无票轻量 Goal 只使用必要清单/验收，不预造执行记录。>

package/template/workflows/specdev/specdev-p-goal-plan/assets/lightweight-goal-plan-template.md

@@ -0,0 +1,21 @@
+---
+artifact: lightweight-goal-plan
+change: <YYYY-MM-DD-topic>
+lead: <actual-session-locator>
+---
+
+# <目标计划>
+
+范围和验收由本 change README 的 scope/acceptance/verification 负责。仅单 change、非 Deep、无真实并行、无独立 Ticket/Map/Implementation 的简单 Goal 使用本模板；用户明确要求完整工件时使用完整模板。
+
+## Tasks
+
+- [ ] <有明确产物与验收引用的一项任务>
+
+## Integration and Verification
+
+<适用集成方式、README AC/verification 导航、实际验证与未验证边界；票或清单全勾不替代整体验收。>
+
+## Next Steps
+
+<当前接续、原 Lead、真实交接或阻塞、下一安全动作。README 只导航本计划，不复制任务清单。>

package/template/workflows/specdev/specdev-p-goal-plan/references/completion-control.md

@@ -0,0 +1,47 @@
+# Goal Plan 完成、证据与恢复
+
+## 1. 整体 Definition of Done
+
+至少要求：
+
+- Spec 验收合同全部有通过 Evidence 或明确批准的 deferred；
+- current 模式的非 cancelled Ticket 都有 implementation commit、通过的 direct-parent 验证和父分支 result SHA；required 模式都有 source commit、通过的 candidate 和父分支 result SHA；
+- shared path、接口、数据、兼容、迁移、调用点与回滚合同闭合；
+- 项目定向检查、受影响回归、类型检查、lint/build 和适用 E2E 无未经批准退化；
+- README Outcome、Ticket、Map 导航、Goal Plan、Evidence 与实际 Git 状态一致；
+- 没有未集成 implementation/source checkpoint、活动 integration candidate 或未决高影响偏差。
+
+无需改动的 Ticket 必须转为 `cancelled` 并记录来源事实；不得用 Evidence-only Done 或 empty commit 关闭。
+
+## 2. 两层验证
+
+- `current-workspace`：current 模式 implementation owner 运行 Ticket 要求的检查，Lead 在同一 workspace 运行受影响集成/回归和适用 E2E；
+- `source-worktree`/`parent-candidate`：required 模式由 implementation owner 和 Lead 分别运行非 E2E 与集成/E2E 检查。
+
+Evidence 必须记录命令运行环境。required 模式任何在 source worktree 声称的 E2E pass 都无效；任务执行者 返回的测试结果在 Lead 核对前保持候选状态。
+
+## 3. Gate 关闭
+
+Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、candidate/result SHA、适用 E2E、反向验证、偏差、风险和批准。Gate 不以“完成若干 Ticket”作为唯一关闭条件。
+
+## 4. 失败与恢复
+
+- current/source 检查失败：保留当前 workspace 或 source worktree，继续当前 Ticket；
+- direct-parent/candidate 冲突或检查失败：父分支不动，integration 记 `failed`，Ticket 回到 `in_progress`/`blocked`；
+- 父 HEAD 漂移：integration 记 `stale`，从最新父分支重建并重跑；
+- E2E required 失败：父分支不动，保留失败命令、适用 checkpoint 和恢复条件；
+- 同一 blocker 反复出现、下一轮没有新证据，或 integration attempts 达到有效上限：停止自动重复，保留 workspace、checkpoint/candidate 和全部失败事实，将受影响 Ticket 标为 `blocked` 并返回有效 Lead；Lead 按 lead-orchestration 在 Evidence 写复盘决定后，才可重置该 Ticket 的 `attempts` 并以有实质变化的新 Packet 重新派发；
+- 命中当次 Dispatch Packet/候选协议的停止条件、继续修正已无合理收益或需要新产品决定：停止受影响 Wave，按 deviation control 返回契约 owner；
+- Lead 会话变化：读取 Goal Plan、Ticket、change worktree 状态与最新 Evidence，从最后不可变 checkpoint 恢复。
+
+父 P-goal-plan 的 Lead 可继续其他不受影响的 ready frontier；单个 Ticket 进入 Lead 复盘不自动终止整个父循环。
+
+## 5. Change 完成 owner
+
+Lead 是 Goal Plan change 的唯一完成 owner。没有 Goal Plan 的单 Ticket/Direct Spec 由当前 I-implement owner 按 change completion 规则完成。Archive 不补造完成证据。
+
+**完成标准**：所有通过、阻塞、取消和未验证声明均定位到权威工件、命令与 Git checkpoint；失败不会推进父分支或 Done。
+
+## 完成声明的版本
+
+关闭前核对最终实际代码/配置/构件与证据版本，说明未运行项、行为差异和残余风险。性能微基准、原型或 mock 不替代明确要求的真实路径。PR/Issue/发布分别回读原账本，远程 pending 不伪装已交付。