@namewta/speculo 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/README.md +11 -11
  2. package/dist/src/cli.js +36 -128
  3. package/dist/src/cli.js.map +1 -1
  4. package/dist/src/index.d.ts +2 -4
  5. package/dist/src/index.js +173 -151
  6. package/dist/src/index.js.map +1 -1
  7. package/package.json +6 -4
  8. package/template/.speculo/README.md +4 -0
  9. package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md +133 -141
  10. package/template/canonical/canonical-specdev-goal-plan.md +394 -377
  11. package/template/canonical/canonical-specdev-grill-with-docs.md +241 -178
  12. package/template/canonical/canonical-specdev-spec.md +132 -122
  13. package/template/canonical/canonical-specdev-tickets.md +176 -156
  14. package/template/canonical/canonical-specdev-wayfinder.md +106 -108
  15. package/template/commands/archive-and-consolidate.md +10 -8
  16. package/template/commands/handoff.md +2 -0
  17. package/template/commands/retro.md +3 -3
  18. package/template/commands/status.md +5 -4
  19. package/template/skills/archive-and-consolidate/SKILL.md +5 -9
  20. package/template/skills/archive-and-consolidate/assets/archive-plan-template.md +1 -1
  21. package/template/skills/archive-and-consolidate/references/archive-rules.md +4 -4
  22. package/template/skills/archive-and-consolidate/references/consolidation-rules.md +7 -8
  23. package/template/skills/archive-and-consolidate/references/knowledge-graduation.md +5 -2
  24. package/template/skills/github-npm-ops/SKILL.md +4 -2
  25. package/template/skills/github-npm-ops/references/issue-transport.md +26 -0
  26. package/template/skills/github-npm-ops/references/preflight-checklist.md +1 -1
  27. package/template/skills/github-npm-ops/scripts/issue-transport.mjs +227 -0
  28. package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +31 -145
  29. package/template/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md +4 -6
  30. package/template/workflows/specdev/C-code-review/C-code-review.md +42 -0
  31. package/template/workflows/specdev/C-code-review/code-review-template.md +42 -0
  32. package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md +45 -48
  33. package/template/workflows/specdev/D-diagnose-bugs/diagnosis-template.md +44 -40
  34. package/template/workflows/specdev/D-diagnose-bugs/feedback-loop.md +41 -0
  35. package/template/workflows/specdev/D-diagnose-bugs/hypothesis-and-instrumentation.md +32 -0
  36. package/template/workflows/specdev/D-diagnose-bugs/scripts/hitl-loop.template.sh +26 -0
  37. package/template/workflows/specdev/E-engineering-cognitive-mentor/E-engineering-cognitive-mentor.md +3 -3
  38. package/template/workflows/specdev/E-engineering-cognitive-mentor/persistence-and-resume.md +5 -20
  39. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +17 -10
  40. package/template/workflows/specdev/G-grill-with-docs/adr-format.md +31 -17
  41. package/template/workflows/specdev/G-grill-with-docs/context-format.md +9 -29
  42. package/template/workflows/specdev/G-grill-with-docs/domain-modeling-rules.md +10 -5
  43. package/template/workflows/specdev/G-grill-with-docs/stakeholder-questionnaire.md +45 -0
  44. package/template/workflows/specdev/I-implement/I-implement.md +29 -14
  45. package/template/workflows/specdev/I-implement/delegated-evidence-template.md +11 -0
  46. package/template/workflows/specdev/I-implement/evidence-template.md +24 -10
  47. package/template/workflows/specdev/I-implement/execution-preflight.md +4 -4
  48. package/template/workflows/specdev/I-implement/merge-conflict-protocol.md +20 -0
  49. package/template/workflows/specdev/I-implement/tdd-mocking.md +19 -0
  50. package/template/workflows/specdev/I-implement/tdd-rules.md +14 -12
  51. package/template/workflows/specdev/I-implement/tdd-test-design.md +25 -0
  52. package/template/workflows/specdev/I-init-setup/I-init-setup.md +12 -9
  53. package/template/workflows/specdev/I-init-setup/config-template.json +1 -1
  54. package/template/workflows/specdev/I-init-setup/domain-layout-template.md +2 -2
  55. package/template/workflows/specdev/I-init-setup/status-template.json +2 -3
  56. package/template/workflows/specdev/I-init-setup/tracking-template.md +3 -0
  57. package/template/workflows/specdev/INDEX.md +64 -26
  58. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +48 -38
  59. package/template/workflows/specdev/P-goal-plan/completion-control.md +19 -53
  60. package/template/workflows/specdev/P-goal-plan/delegated-execution-template.md +33 -0
  61. package/template/workflows/specdev/P-goal-plan/delegated-execution.md +53 -0
  62. package/template/workflows/specdev/P-goal-plan/goal-plan-template.md +9 -40
  63. package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md +16 -68
  64. package/template/workflows/specdev/P-goal-plan/planning-modes.md +20 -48
  65. package/template/workflows/specdev/P-prototype/P-prototype.md +46 -0
  66. package/template/workflows/specdev/P-prototype/logic-prototype.md +24 -0
  67. package/template/workflows/specdev/P-prototype/prototype-record-template.md +46 -0
  68. package/template/workflows/specdev/P-prototype/ui-prototype.md +21 -0
  69. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +1 -1
  70. package/template/workflows/specdev/S-spec/S-spec.md +2 -1
  71. package/template/workflows/specdev/T-tickets/T-tickets.md +3 -2
  72. package/template/workflows/specdev/T-tickets/ticket-readiness.md +1 -1
  73. package/template/workflows/specdev/T-tickets/ticket-template.md +1 -1
  74. package/template/workflows/specdev/T-tickets/tickets-map-template.md +1 -1
  75. package/template/workflows/specdev/T-triage/T-triage.md +65 -26
  76. package/template/workflows/specdev/T-triage/intake-protocol.md +32 -0
  77. package/template/workflows/specdev/T-triage/reconcile-protocol.md +34 -0
  78. package/template/workflows/specdev/T-triage/source-template.md +30 -0
  79. package/template/workflows/specdev/T-triage/triage-template.md +38 -24
  80. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +3 -1
  81. package/template/workflows/specdev/_state/status.json +2 -3
  82. package/template/workflows/specdev/common/README.md +9 -2
  83. package/template/workflows/specdev/common/rules/artifact-contract.md +20 -9
  84. package/template/workflows/specdev/common/rules/change-completion.md +33 -0
  85. package/template/workflows/specdev/common/rules/deviation-control.md +2 -2
  86. package/template/workflows/specdev/common/rules/evidence-and-verification.md +1 -1
  87. package/template/workflows/specdev/common/rules/path-ownership.md +3 -3
  88. package/template/workflows/specdev/common/schemas/change-status.schema.json +43 -0
  89. package/template/workflows/specdev/common/schemas/code-review.schema.json +22 -0
  90. package/template/workflows/specdev/common/schemas/diagnosis.schema.json +19 -0
  91. package/template/workflows/specdev/common/schemas/prototype-record.schema.json +24 -0
  92. package/template/workflows/specdev/common/schemas/source.schema.json +20 -0
  93. package/template/workflows/specdev/common/schemas/status.schema.json +20 -78
  94. package/template/workflows/specdev/common/schemas/triage.schema.json +21 -0
  95. package/template/workflows/specdev/common/skills/code-review/SKILL.md +49 -0
  96. package/template/workflows/specdev/common/skills/code-review/references/fowler-smells.md +18 -0
  97. package/template/workflows/specdev/common/skills/code-review/references/reviewer-contracts.md +13 -0
  98. package/template/workflows/specdev/common/skills/code-review/references/source-discovery.md +22 -0
  99. package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +12 -9
  100. package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +18 -13
  101. package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +8 -6
  102. package/template/workflows/specdev/common/skills/research/SKILL.md +38 -26
  103. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +3 -5
  104. package/template/workflows/specdev/common/tools/README.md +3 -0
  105. package/template/workflows/specdev/common/tools/validate-specdev.mjs +496 -30
  106. package/dist/src/migrate.d.ts +0 -38
  107. package/dist/src/migrate.js +0 -642
  108. package/dist/src/migrate.js.map +0 -1
  109. package/dist/src/skills-mirror.d.ts +0 -38
  110. package/dist/src/skills-mirror.js +0 -160
  111. package/dist/src/skills-mirror.js.map +0 -1
  112. package/template/workflows/specdev/A-archive-and-consolidate/archive-checklist.md +0 -15
  113. package/template/workflows/specdev/A-archive-and-consolidate/knowledge-promotion-rules.md +0 -32
  114. package/template/workflows/specdev/I-implement/code-review-process.md +0 -17
  115. package/template/workflows/specdev/I-implement/tdd-examples.md +0 -14
  116. package/template/workflows/specdev/I-init-setup/status-labels-template.md +0 -55
@@ -13,7 +13,9 @@
13
13
  - 若本地项目提供 Speculo Node 校验器,可运行它补充结构校验;纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对,并明确记录未运行的自动校验。
14
14
  - 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
15
15
 
16
- Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、Agent 交付、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版,也不按固定章节数量衡量质量;每个 Ticket 的独立 Dispatch Packet 是 Goal Plan 的执行入口,不是第二份 Ticket。
16
+ Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版,也不按固定章节数量衡量质量。
17
+
18
+ Lead/subagent 是可选的委派分支,不是 Goal Plan 的固有角色。每次运行都先由用户选择普通 Goal Plan 或委派 Goal Plan;普通计划不写 execution model、Lead、Provider、Delivery Contract、Dispatch Packet、Worker、会话 locator 或修正轮次,也不写“未启用”或“不适用”占位。
17
19
 
18
20
  产物写入 `specdev/changes/{change}/goal-plan.md`。
19
21
 
@@ -22,7 +24,7 @@ Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序
22
24
  满足任一条件时运行:
23
25
 
24
26
  - 多个 Ticket 可以或需要并行;
25
- - 存在 shared path、共享合同、集中 owner 或 Lead/Subagent
27
+ - 存在 shared path、共享合同或集中 owner;
26
28
  - 存在 Deep Ticket、expand-contract、数据迁移、兼容窗口或不可逆步骤;
27
29
  - 存在多个里程碑、外部审批、发布窗口、参考符合性或高事故半径;
28
30
  - Ticket DAG 虽不大,但关键路径、汇合点或恢复策略不能仅由 `specdev/changes/{change}/tickets-map.md` 安全表达;
@@ -52,20 +54,21 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
52
54
 
53
55
  ## 流程
54
56
 
55
- ### 1. 验证上游与选择规划模式
57
+ ### 1. 验证上游并确认角色分支
56
58
 
57
59
  加载 下方 `<planning-modes>` 标签:
58
60
 
59
61
  1. 验证 Spec Ready、Ticket Ready、合同覆盖、DAG、路径所有权和 Deep Ticket 完整性;
60
62
  2. 只读探索会影响调度的代码事实和项目约束;
61
63
  3. 识别 coordination、migration、high-assurance、reference-conformance 等可组合规划模式;
62
- 4. `direct`、`native-subagent`、`external-web-subagent` 中选择唯一 execution model,并固定 Lead、源码 checkpoint、上下文交付和逐动作授权;
63
- 5. 只对无法发现且会改变 Gate、Wave、owner、执行模型、迁移或批准点的问题向用户提问;
64
- 6. 不熟悉的外部标准或依赖使用 下方 `<research>` 标签。
64
+ 4. 每次向用户询问选择普通 Goal Plan 或委派 Goal Plan,不按复杂度静默启用角色委派;
65
+ 5. 用户选择委派时,再在 `native-subagent` 与 `external-web-subagent` 中选择实际交付通道;普通分支不形成或持久化执行模式;
66
+ 6. 只对无法发现且会改变 Gate、Wave、owner、迁移或批准点的问题继续提问;
67
+ 7. 不熟悉的外部标准或依赖使用 下方 `<research>` 标签。
65
68
 
66
69
  任何硬停止问题都必须退回拥有该决策的上游工件,不得用 Goal Plan 覆盖。
67
70
 
68
- ### 2. 构建跨 Ticket 执行模型
71
+ ### 2. 构建跨 Ticket 核心计划
69
72
 
70
73
  加载 下方 `<orchestration-protocol>` 标签:
71
74
 
@@ -73,13 +76,24 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
73
76
  2. 将 Ready 且项目写路径不相交的 Ticket 分配到 Wave;
74
77
  3. 为 shared path、共享合同和集中变更指定唯一 owner;
75
78
  4. 为行为闭环、合同稳定、迁移完成、发布就绪等关键状态定义 Gate;
76
- 5. 明确 expand → migrate → contract、Evidence 返回和集成规则;并行写代码时使用 下方 `<dev-worktree>` 标签;
77
- 6. `operation=plan` 调用 下方 `<subagent-delivery>` 标签,生成里程碑 Delivery Contract 和每个 Ticket 可独立投递的 Dispatch Packet;
78
- 7. 派单块只携带实现所需的权威引用、边界、基线、验证、恢复和返回字段,不复制完整历史对话或 Ticket 全文。
79
+ 5. 明确 expand → migrate → contract、Evidence 返回和集成规则;
80
+ 6. 定义每个 Ticket 的开始条件、执行顺序、验证、Evidence 目标和失败恢复,不复制 Ticket 全文。
81
+
82
+ **完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个计划 Ticket 都有唯一 owner、可验证开始条件、Evidence 目标和恢复路径。
83
+
84
+ ### 3. 按确认加载委派分支
85
+
86
+ 只有用户在本次运行选择委派 Goal Plan 时:
79
87
 
80
- **完成标准**:DAG、Wave、Gate Tickets Map 一致;每个计划 Ticket 都有唯一 owner、基线和可恢复派单块。
88
+ 1. 加载 下方 `<delegated-execution>` 标签;
89
+ 2. 以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签;
90
+ 3. 固定唯一 Lead、native/external provider、不可变 checkpoint、可恢复 locator、逐动作授权和修正上限;
91
+ 4. 生成里程碑 Delivery Contract 与每个 Ticket 的独立 Dispatch Packet;
92
+ 5. 并行写代码时按需调用 下方 `<dev-worktree>` 标签。
81
93
 
82
- ### 3. 定义整体完成、证据与恢复
94
+ 普通 Goal Plan 跳过本步骤,不加载上述委派能力,也不在最终产物中留下该分支的标题、字段或占位。
95
+
96
+ ### 4. 定义整体完成、证据与恢复
83
97
 
84
98
  加载 下方 `<completion-control>` 标签:
85
99
 
@@ -87,16 +101,16 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
87
101
  2. 定义整体 Definition of Done 和每个 Gate 的关闭证据;
88
102
  3. 固化跨 Ticket 不可协商约束;
89
103
  4. 区分不可违反约束与可由实现者调整的建议;
90
- 5. 定义实测基线、反向验证、防伪完成、偏差等级、修正上限、暂停范围、批准人和恢复动作;
104
+ 5. 定义实测基线、反向验证、防伪完成、偏差等级、暂停范围、批准人和恢复动作;
91
105
  6. 定义进度回报、Evidence 汇总、残余风险和回滚要求。
92
106
 
93
- **完成标准**:所有完成声明能映射到实际命令、代码状态、Evidence 或人工批准;没有 provider 自报即通过的门禁。
107
+ **完成标准**:所有完成声明能映射到实际命令、代码状态、Evidence 或人工批准;没有自报即通过的门禁。
94
108
 
95
- ### 4. 写入自适应 Goal Plan
109
+ ### 5. 写入自适应 Goal Plan
96
110
 
97
111
  使用 下方 `<goal-plan-template>` 标签 写入 `specdev/changes/{change}/goal-plan.md`。
98
112
 
99
- 模板包含六个职责区,但只保留适用内容:
113
+ 核心模板包含六个职责区,但只保留适用内容:
100
114
 
101
115
  1. Outcome and Authority;
102
116
  2. Execution Graph;
@@ -105,49 +119,46 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
105
119
  5. Constraints, Risk and Recovery;
106
120
  6. Progress and Decisions。
107
121
 
108
- Ticket 较多时在 Execution Graph 内增加速查表;不创建独立的第二套状态来源。
109
-
110
- Goal Plan 不受单次 `/goal` 字符上限约束。需要粘贴到外部 Agent 时,只投递对应 Ticket 的 Dispatch Packet 及其指向的权威材料。
122
+ 用户选择委派时,在第 4 节加入 下方 `<delegated-execution-template>` 标签 的完整内容;没有选择时不加入任何委派痕迹。Ticket 较多时在 Execution Graph 内增加速查表,不创建独立的第二套状态来源。
111
123
 
112
- ### 5. 同步与验证
124
+ ### 6. 同步与验证
113
125
 
114
126
  1. 将 Wave、Gate 和 owner 投影同步到 `specdev/changes/{change}/tickets-map.md`;
115
- 2. 对照 下方 `<goal-plan-schema>` 标签;
127
+ 2. 对照 下方 `<goal-plan-schema>` 标签;schema 不记录角色分支;
116
128
  3. 运行:
117
129
 
118
- > **结构校验:** 本地项目若已安装 Speculo,使用其 Node 校验器检查当前 change;
119
- > 纯网页环境逐项核对本文内联的 schema、Ready 清单和完成标准,并记录自动校验未运行。
130
+ ```bash
131
+ node Speculo Node 校验器 \
132
+ --stage goal-plan \
133
+ specdev/changes/{change}
134
+ ```
120
135
 
121
136
  4. 更新 `specdev/status.json` 与 `specdev/changes/{change}/.status.json`;
122
- 5. 原子写入 Goal Plan 和同步投影后重新读取,确认 execution model、Lead、checkpoint、授权、Wave/Gate 与派单块一致;
123
- 6. 向用户汇报规划模式、execution model、关键路径、Wave、Gate、shared owner、checkpoint、迁移策略、主要风险和 Ready 状态;
137
+ 5. 原子写入 Goal Plan 和同步投影后重新读取,确认核心 DAG/Wave/Gate/owner/授权一致;存在委派附录时额外确认 Lead、checkpoint、locator、Delivery Contract 与 Dispatch Packet 完整一致;
138
+ 6. 向用户汇报规划模式、关键路径、Wave、Gate、shared owner、迁移策略、主要风险和 Ready 状态;选择委派时再汇报交付通道与 Lead;
124
139
  7. 未经用户要求,不自动进入实现。
125
140
 
126
141
  ## 决策完备标准
127
142
 
128
- Goal Plan 必须让执行 Lead 或实现者无需重新决定:
143
+ 每份 Goal Plan 必须让实现者无需重新决定:
129
144
 
130
145
  - 跨 Ticket 先后、并发 Wave 和关键汇合点;
131
146
  - shared path 与共享合同的 owner;
132
147
  - Gate 开启、关闭和证据;
133
148
  - 迁移、兼容、收缩、发布和回滚顺序;
134
- - Agent 派单上下文、Evidence 返回和集成规则;
135
- - execution model、Lead、checkpoint、上下文交付、修正上限和逐动作授权;
136
- - 偏差等级、暂停范围和批准路径。
149
+ - Evidence 返回、集成、偏差、暂停和批准路径。
137
150
 
138
- Goal Plan 不应重复:
151
+ 委派 Goal Plan 还必须锁定 Agent 派单上下文、execution model、Lead、checkpoint、locator、修正上限和逐动作授权。普通 Goal Plan 不包含这些内容。
139
152
 
140
- - Ticket 的完整局部执行路线;
141
- - 每个 Ticket 的全部文件预测;
142
- - 每条局部验收 checklist;
143
- - Spec 中的完整用户故事和产品背景。
153
+ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局部验收 checklist 或 Spec 的完整用户故事。
144
154
 
145
155
  ## 完成标准
146
156
 
147
157
  - `specdev/changes/{change}/goal-plan.md` 已写入且只包含适用内容;
148
158
  - 所有计划内 Ticket Ready,DAG 无环,合同覆盖明确;
149
159
  - Wave、Gate、owner、集成、偏差和恢复可执行;
150
- - 每个计划 Ticket 的 Dispatch Packet 可独立定位权威输入、路径合同、验证和恢复点;
160
+ - 普通计划没有委派角色、交付合同或空占位;
161
+ - 委派计划的 Delivery Contract 与每个 Dispatch Packet 完整可恢复;
151
162
  - Tickets Map 投影已同步;
152
163
  - 无未批准高影响假设或硬停止问题;
153
164
  - 结构校验无 error;纯网页环境的人工核对结果已记录;
@@ -156,11 +167,12 @@ Goal Plan 不应重复:
156
167
  ## 子文件引用
157
168
 
158
169
  - 规划模式与输入门禁:下方 `<planning-modes>` 标签
159
- - DAG、Wave、Gate Lead 编排:下方 `<orchestration-protocol>` 标签
170
+ - DAG、Wave、Gate 与核心集成:下方 `<orchestration-protocol>` 标签
171
+ - 委派执行协议:下方 `<delegated-execution>` 标签,仅用户选择委派时加载
160
172
  - 完成、证据、偏差与恢复:下方 `<completion-control>` 标签
161
- - Goal Plan 模板:下方 `<goal-plan-template>` 标签
162
- - 并行 Ticket worktree:下方 `<dev-worktree>` 标签
163
- - Agent 交付合同:下方 `<subagent-delivery>` 标签
173
+ - Goal Plan 核心模板:下方 `<goal-plan-template>` 标签
174
+ - 委派附录模板:下方 `<delegated-execution-template>` 标签,仅用户选择委派时加载
175
+ - Agent 交付合同:下方 `<subagent-delivery>` 标签,仅用户选择委派时调用
164
176
 
165
177
  ---
166
178
 
@@ -172,7 +184,7 @@ Goal Plan 不应重复:
172
184
 
173
185
  # Goal Plan 规划模式与输入门禁
174
186
 
175
- 本文件由 “目标规划阶段” 在上游验证和模式选择时加载。
187
+ 本文件由 “目标规划阶段” 在上游验证和角色分支确认时加载。
176
188
 
177
189
  ## 1. 必需输入门禁
178
190
 
@@ -197,75 +209,45 @@ Goal Plan 不应重复:
197
209
  - 合同 uncovered 且未批准 deferred;
198
210
  - 并行候选写路径相交且无 owner 或顺序;
199
211
  - Ticket 改写了 Spec 的外部行为、范围或验收;
200
- - Ticket 与 `specdev/changes/{change}/ADR.md` 的已接受决策冲突;
212
+ - Ticket 与 `specdev/changes/{change}/ADR.md` 的已接受决定冲突;
201
213
  - Deep Ticket 缺少关键迁移或恢复信息;
202
214
  - 当前代码事实使 Ticket 的核心行为、接口或验证不可执行;
203
215
  - 必需外部合同或参考权威不可获得;
204
- - 选择 delegated execution,但 Lead、checkpoint、可恢复 locator 或交付通道无法建立;
216
+ - 已选择委派,但 Lead、checkpoint、可恢复 locator 或交付通道无法建立;
205
217
  - 用户要求的远程或生产动作没有逐动作授权。
206
218
 
207
219
  按 下方 `<artifact-contract>` 标签 和 下方 `<deviation-control>` 标签 返回真正拥有该决策的工件。
208
220
 
209
- ## 3. 可组合模式
210
-
211
- ### coordination
212
-
213
- 适用于多 Wave、扇出/汇合、shared path 或 Lead/Subagent。重点是 DAG、owner、Evidence 返回、集成和状态同步。
214
-
215
- ### migration
216
-
217
- 适用于 expand-contract、数据迁移、协议迁移或兼容窗口。重点是扩展、分批迁移、收缩条件、数据核对、监控和回滚。
218
-
219
- ### high-assurance
220
-
221
- 适用于安全、隐私、资金、数据完整性、法规或不可逆操作。重点是独立审查、人工批准、Evidence 完整性和失败恢复。
221
+ ## 3. 可组合规划模式
222
222
 
223
- ### reference-conformance
224
-
225
- 适用于外部合同、标准、官方实现或指定兼容行为。重点是来源版本、符合性矩阵和冲突裁决。
226
-
227
- ### release-coordination
228
-
229
- 适用于发布窗口、跨团队依赖、部署顺序或运营交接。重点是环境前置条件、Gate、观察期和回退。
223
+ - **coordination**:多 Wave、扇出/汇合或 shared path;重点是 DAG、owner、Evidence 返回、集成和状态同步。
224
+ - **migration**:expand-contract、数据或协议迁移;重点是扩展、分批迁移、收缩条件、数据核对、监控和回滚。
225
+ - **high-assurance**:安全、隐私、资金、数据完整性、法规或不可逆操作;重点是独立审查、人工批准、Evidence 完整性和失败恢复。
226
+ - **reference-conformance**:外部合同、标准、官方实现或指定兼容行为;重点是来源版本、符合性矩阵和冲突裁决。
227
+ - **release-coordination**:发布窗口、跨团队依赖、部署顺序或运营交接;重点是环境前置条件、Gate、观察期和回退。
230
228
 
231
229
  模式可以组合。仅有线性低风险 Ticket 时不应为了形式生成重型 Goal Plan。
232
230
 
233
- ## 4. 执行模型与交付事实
234
-
235
- 规划模式描述“为什么需要治理”,execution model 描述“每个 Ticket 怎样被执行”,两者不得混为同一枚举。每份 Goal Plan 只选一个主 execution model:
231
+ ## 4. 每次确认角色分支
236
232
 
237
- - `direct`:Lead 或当前执行者直接运行 Ticket,不创建子代理交付通道;
238
- - `native-subagent`:Lead 可直接管理隔离 Agent,写代码并行时配合 下方 `<dev-worktree>` 标签;
239
- - `external-web-subagent`:通过网页 provider 交付,输出在 Lead 独立核对前保持候选状态。
233
+ 规划模式描述为什么需要跨 Ticket 治理,不决定是否启用 Lead/subagent。每次运行 P 都向用户提供两个选择:
240
234
 
241
- 选择模型前先发现当前平台能力、项目配置和用户请求。只有用户明确指定 provider 或交付通道时才把偏好当作约束;否则优先使用能保留隔离、checkpoint Evidence 的现有原生能力。
235
+ - **普通 Goal Plan**:由实现者按核心计划推进,不创建严格角色、交付通道或派单合同;最终产物不记录一个名为 direct 的模式。
236
+ - **委派 Goal Plan**:启用唯一 Lead 与 `native-subagent` 或 `external-web-subagent`,并加载委派协议。
242
237
 
243
- 必须固定:
238
+ 不得根据 Ticket 数量、并行机会或平台能力静默启用委派。选择普通分支后,AI 自适应决定核心计划的适用细节,不把本次角色选择写入 frontmatter,也不在正文生成空章节或“不适用”说明。
244
239
 
245
- - `lead` 与不可转移责任;
246
- - provider 和稳定 workspace/session locator,direct 时为不适用;
247
- - repository/branch 与不可变 `base_sha` 或等价本地基线;
248
- - `source_delivery`:none、repository-url、source-package 或 combination;
249
- - `max_correction_rounds`,默认 3;
250
- - local changes、commit、push、PR、merge、deploy、migration、production configuration、production feature、real user data 的逐动作授权。
240
+ 选择委派后才固定:Lead、provider、repository/branch、不可变 `base_sha` 或等价基线、源码交付方式、`max_correction_rounds` 和逐动作授权。认证秘密和机器绝对路径不得进入 Goal Plan。
251
241
 
252
- GitHub checkpoint、源码包和 provider 分支由 下方 `<subagent-delivery>` 标签 按需加载。认证秘密和机器绝对路径不得进入 Goal Plan。
242
+ ## 5. 规划摘要
253
243
 
254
- ## 5. 模式摘要
255
-
256
- 写入 `specdev/changes/{change}/goal-plan.md` 前形成:
244
+ 写入前形成核心摘要:
257
245
 
258
246
  ```text
259
247
  modes=<mode-list>
260
- execution_model=<direct|native-subagent|external-web-subagent>
261
- lead=<owner>
262
- provider=<id|none>
263
248
  tickets=<count>
264
249
  critical_path=<ticket-list>
265
250
  parallel_capacity=<n>
266
- checkpoint=<sha-or-local-baseline>
267
- source_delivery=<mode>
268
- max_correction_rounds=<n>
269
251
  shared_owners=<owner-map>
270
252
  gates=<gate-list>
271
253
  authorization=<action-summary>
@@ -273,15 +255,17 @@ hard_stops=<none-or-list>
273
255
  adopted_assumptions=<low-impact-only>
274
256
  ```
275
257
 
276
- **完成标准**:可组合 modes 与唯一 execution model 分离;源码、交付、权限和恢复字段都有可验证值。
258
+ 委派分支额外形成 `execution_model`、`lead`、`provider`、`checkpoint`、`source_delivery`、`max_correction_rounds` locator;这些字段只进入委派附录。
259
+
260
+ **完成标准**:规划 modes 与角色选择互不代替;普通计划没有委派痕迹;委派计划的源码、交付、权限和恢复字段都有可验证值。
277
261
 
278
262
  </planning-modes>
279
263
 
280
264
  <orchestration-protocol>
281
265
 
282
- # Goal Plan 编排协议
266
+ # Goal Plan 核心编排协议
283
267
 
284
- 本文件定义 DAG、Wave、Gate、路径所有权、Delivery Contract、Dispatch Packet、Evidence 返回和集成规则。
268
+ 本文件定义所有 Goal Plan 都需要的 DAG、Wave、Gate、路径所有权、Evidence 返回和集成规则。它不建立 Lead/subagent 角色或 Agent 交付合同。
285
269
 
286
270
  ## 1. DAG 与关键路径
287
271
 
@@ -300,20 +284,13 @@ Wave 内 Ticket 必须同时满足:
300
284
  - 项目写路径不相交;
301
285
  - shared path 已由 owner 稳定;
302
286
  - 适用 Gate 已打开;
303
- - 基线和外部合同版本一致。
287
+ - 源码基线和外部合同版本一致。
304
288
 
305
- 最大并发从 `specdev/config.json` 读取。并发上限是资源约束,不是强制填满的目标。
289
+ 最大并发从 `specdev/config.json` 读取。并发上限是资源约束,不是必须填满的目标;Wave 也不意味着必须使用多个 Agent。
306
290
 
307
291
  ## 3. Gate
308
292
 
309
- Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条件。每个 Gate 必须写明:
310
-
311
- - 业务或工程状态;
312
- - 开启条件;
313
- - 关闭证据;
314
- - 阻塞范围;
315
- - owner 与批准人;
316
- - 失败时恢复动作。
293
+ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条件。每个 Gate 必须写明业务或工程状态、开启条件、关闭证据、阻塞范围、owner/批准人和失败恢复。
317
294
 
318
295
  常见 Gate 包括共享合同稳定、首条垂直路径通过、迁移完成、旧调用点归零、发布就绪和观察期结束。名称按项目语义自定义。
319
296
 
@@ -321,11 +298,11 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
321
298
 
322
299
  规则遵循 下方 `<path-ownership>` 标签:
323
300
 
324
- 1. 由专用 owner Ticket Lead 修改共享路径;
301
+ 1. 由专用 owner Ticket 或计划指定的唯一 owner 修改共享路径;
325
302
  2. 形成可验证稳定基线;
326
303
  3. 下游消费者在新基线上重新运行 preflight;
327
- 4. 才允许扇出并行;
328
- 5. 共享契约需要变化时暂停消费者并修订上游,不通过多个 Agent 同时修改解决。
304
+ 4. 才允许扇出或继续后续 Ticket;
305
+ 5. 共享契约需要变化时暂停消费者并修订上游,不通过多个执行者同时修改解决。
329
306
 
330
307
  ## 5. Expand-contract
331
308
 
@@ -339,11 +316,34 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
339
316
 
340
317
  收缩不得仅以“所有迁移 Ticket 已完成”为依据。
341
318
 
342
- ## 6. Lead Delivery Contract
319
+ ## 6. Ticket 执行、Evidence 与集成
320
+
321
+ 每个计划 Ticket 必须写明开始条件、依赖 Evidence、项目路径合同、适用 Gate、必跑验证、Evidence 目标和失败恢复。实际执行仍由 “实现阶段” 与 Ticket 拥有,不在 Goal Plan 复制局部施工步骤。
322
+
323
+ 每个实现者完成或阻塞时:
324
+
325
+ 1. 写入 `specdev/changes/{change}/evidence/T-NN.md`;
326
+ 2. 同步 Ticket、Tickets Map、Goal Plan 和 change 状态;
327
+ 3. 检查依赖、路径所有权、合同覆盖和适用 Gate;
328
+ 4. 返回 Ticket 状态、Evidence 路径、代码引用、未验证项和恢复条件。
329
+
330
+ 最后一个计划内 Implement 按 下方 `<completion-control>` 标签 汇总核心计划的 Gate 和 Evidence。委派分支的候选交付与 Lead 集成由独立委派协议拥有,不写入本文件。
331
+
332
+ **完成标准**:每个执行结果可追溯到代码状态和 Evidence;普通 Goal Plan 可以在不建立角色交付合同的情况下完整恢复和完成。
333
+
334
+ </orchestration-protocol>
335
+
336
+ <delegated-execution>
337
+
338
+ # Goal Plan 委派执行协议
339
+
340
+ 只有用户在本次 P-goal-plan 运行中选择委派 Goal Plan 时加载。该分支同时启用唯一 Lead 与 native/external subagent;不支持 Lead-only,也不把本协议用于普通 Goal Plan。
341
+
342
+ ## 1. Lead 与 Delivery Contract
343
343
 
344
344
  Lead 负责源码基线、DAG、Wave、shared owner、Gate、权限、Evidence 汇总和集成;已派发 Ticket 的实现由对应执行者负责,Lead 不制造双重 owner。
345
345
 
346
- Goal Plan 选择唯一 execution model:`direct`、`native-subagent` 或 `external-web-subagent`。Lead 以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签,生成里程碑级 Delivery Contract;Implement 阶段以 `operation=execute` 调用同一 Skill 做恢复和验收。
346
+ 委派分支选择唯一 execution model:`native-subagent` 或 `external-web-subagent`。Lead 以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签 生成里程碑 Delivery Contract;Implement 阶段以 `operation=execute` 调用同一 Skill 做恢复和验收。
347
347
 
348
348
  Delivery Contract 必须固定:
349
349
 
@@ -354,52 +354,42 @@ Delivery Contract 必须固定:
354
354
  - local changes、commit、push、PR、merge、deploy、migration 和生产动作的逐项授权;
355
355
  - 完成、阻塞、偏差、恢复和返回协议。
356
356
 
357
- 并行写代码且配置允许时,Lead 为每个 Ticket 调用 下方 `<dev-worktree>` 标签。所有并行 Ticket 固定同一 `base_sha`,每个 Ticket 使用独立分支和 `workspace_ref`;Lead 创建、恢复、集成和清理,Worker 只推进到 `review`。只读调查和顺序执行不为形式创建 worktree。
358
-
359
- **完成标准**:整个 Goal Plan 只有一个 execution model 和 Lead;每个高影响动作都有明确授权状态。
357
+ 并行写代码且配置允许时,Lead 为每个 Ticket 调用 下方 `<dev-worktree>` 标签。所有并行 Ticket 固定同一 `base_sha`,每个 Ticket 使用独立分支和 `workspace_ref`;Lead 创建、恢复、集成和清理,Worker 只推进到 `review`。
360
358
 
361
- ## 7. Dispatch Packet
359
+ ## 2. Dispatch Packet
362
360
 
363
- 每个计划 Ticket 都生成一个可独立投递的 Dispatch Packet。它不是 Ticket 副本,而是进入权威工件和当前基线的紧凑入口,至少包含:
361
+ 每个计划 Ticket 都生成一个可独立投递的 Dispatch Packet,至少包含:
364
362
 
365
363
  1. Ticket ID、目标、可观察完成结果和优先级冲突裁决;
366
- 2. “实现阶段” `specdev/changes/{change}/ticket/NN-<ticket-name>.md`;
364
+ 2. “实现阶段” 与具体 Ticket;
367
365
  3. 相关 Spec 合同、ADR/CONTEXT 条目、Wave、Gate 和不可协商约束;
368
- 4. 已完成依赖及其 `specdev/changes/{change}/evidence/T-NN.md`;
369
- 5. 项目 `writable_paths`、`read_only_paths`、`shared_paths` 与唯一 shared owner;
366
+ 4. 已完成依赖及其 Evidence;
367
+ 5. 项目 writable/read-only/shared 路径与唯一 shared owner;
370
368
  6. `base_sha`、branch、workspace/session locator 和 source package hash;
371
- 7. 必跑验证、基线指标、可静默失效门禁的反向验证,以及明确不适用项;
369
+ 7. 必跑验证、基线、反向验证和明确不适用项;
372
370
  8. 当前授权、偏差升级、修正上限、Evidence 路径和返回字段。
373
371
 
374
- 派单块将不可违反项写为 Hard Constraints,将低影响实现自由写为 Guidance。执行者必须先核对 checkpoint、项目指令、路径和验证命令,再在 Ticket Evidence 记录不超过 10 行的开工回执:目标、执行顺序、最大风险和发现的基线差异。事实不一致时停止受影响路径并升级,不用更详细文字掩盖失效前提。
372
+ 派单块将不可违反项写为 Hard Constraints,将低影响实现自由写为 Guidance。执行者先核对 checkpoint、项目指令、路径和验证命令,再在 Ticket Evidence 写入不超过 10 行的开工回执。事实不一致时停止受影响路径并升级。
375
373
 
376
- Agent 的最小读取顺序为 Implement work、当前 Ticket、Goal Plan 中适用的 Delivery Contract/Dispatch Packet、相关 Spec/ADR/CONTEXT、项目 Agent 指令和当前代码事实。不投递完整历史对话、全部 Ticket 或无关研究。
374
+ ## 3. 候选交付、Evidence Lead 集成
377
375
 
378
- **完成标准**:每个 Dispatch Packet 可在新上下文中定位全部权威输入、边界、基线、验证、恢复点和返回目标。
376
+ Worker 完成或阻塞时写入 Ticket Evidence,同步状态,并向 Lead 返回 Ticket ID、Evidence、workspace/session locator、最终 checkpoint、commit/PR、未验证项和条件性 Lead E2E。
379
377
 
380
- ## 8. Evidence 返回与集成
378
+ Lead 接收候选交付时:
381
379
 
382
- Agent 完成或阻塞时:
383
-
384
- 1. 写入 `specdev/changes/{change}/evidence/T-NN.md`,包含实际修改、命令与退出状态、验收映射、反向验证、修正轮次、checkpoint 和未验证项;
385
- 2. 同步 Ticket、Tickets Map、Goal Plan 和 change 状态;
386
- 3. 向 Lead 返回 Ticket ID 与状态、Evidence 完整路径、workspace/session locator、最终 checkpoint、commit/PR 引用和条件性 Lead E2E。
387
-
388
- Lead 接收原生或外部候选交付时:
389
-
390
- 1. 读取 Dispatch Packet、Ticket、Evidence、Goal Plan 和对应代码引用;
380
+ 1. 读取 Dispatch Packet、Ticket、Evidence、Goal Plan 和代码引用;
391
381
  2. 检查 checkpoint、附件 hash、路径授权、依赖和敏感信息边界;
392
- 3. 在隔离基线上应用交付,复跑定向验证和受影响回归;
393
- 4. 仅当用户界面交互受影响时,由 Lead 运行最小 E2E;
394
- 5. provider 声明、模拟结果和静态推断保持为 `unverified`,直到有独立证据;
382
+ 3. 在隔离基线上应用交付并复跑定向验证和受影响回归;
383
+ 4. 仅当 UI 交互受影响时运行最小 E2E;
384
+ 5. provider 声明、模拟结果和静态推断在独立证据前保持 `unverified`;
395
385
  6. 验证通过后集成,并按 dev-worktree Skill 更新或清理 worktree;
396
386
  7. 同步 Ticket、Map、Evidence 和 Goal Plan,检查 Gate 是否可关闭。
397
387
 
398
- 同一验收项达到修正上限时标记 blocker,记录最后 checkpoint、错误、已通过行为、责任方和恢复条件。逻辑冲突返回契约 owner 解决,不机械选择某一侧版本。
388
+ 同一验收项达到修正上限时标记 blocker,记录最后 checkpoint、错误、已通过行为、责任方和恢复条件。
399
389
 
400
- **完成标准**:每个完成声明可追溯到 Lead 核对的代码状态和 Evidence;失败也具有可恢复的最后可信 checkpoint
390
+ **完成标准**:完整委派附录包含唯一 Lead、完整 Delivery Contract、每 Ticket Dispatch Packet 和候选交付验收协议;任何一部分缺失都不得视为 Ready
401
391
 
402
- </orchestration-protocol>
392
+ </delegated-execution>
403
393
 
404
394
  <completion-control>
405
395
 
@@ -407,17 +397,7 @@ Lead 接收原生或外部候选交付时:
407
397
 
408
398
  ## 1. Outcome and Authority
409
399
 
410
- Goal Plan 用紧凑摘要表达:
411
-
412
- - 业务或用户目标;
413
- - 目标受众或运营角色;
414
- - 所有计划 Ticket 完成后的可观察终态;
415
- - 关键约束;
416
- - 明确非目标;
417
- - 权威来源和冲突规则;
418
- - 看似有主路径但违反边界、数据、兼容或证据要求的伪完成判据。
419
-
420
- 不复制 `specdev/changes/{change}/spec.md` 的完整用户故事。
400
+ Goal Plan 用紧凑摘要表达业务目标、受众、所有 Ticket 完成后的可观察终态、关键约束、非目标、权威来源、冲突规则和伪完成判据,不复制 Spec 的完整用户故事。
421
401
 
422
402
  ## 2. 整体 Definition of Done
423
403
 
@@ -425,59 +405,36 @@ Goal Plan 用紧凑摘要表达:
425
405
 
426
406
  - 所有计划内 Ticket 完成,cancelled 或 deferred 项有批准;
427
407
  - 所有 Spec 验收合同和外部符合性要求有 Evidence;
428
- - 项目类型检查、静态检查、测试、lint、构建和适用 CI 完成,测试数量、skip/todo、覆盖率或等价基线没有未经批准的退化;仅 UI 交互受影响时由 Lead 完成 E2E;
429
- - 可静默失效的关键门禁完成受控反向验证并恢复绿色;普通门禁有明确不适用结论,不为形式破坏环境;
408
+ - 项目类型检查、静态检查、测试、lint、构建、适用 CI 和受影响 E2E 完成,基线没有未经批准的退化;
409
+ - 可静默失效的关键门禁完成受控反向验证并恢复绿色;
430
410
  - 迁移、兼容、调用点清零、监控、回滚和不可逆批准完成;
431
- - 无未批准偏差和未处置高风险残余问题;
432
- - Ticket、Map、Goal Plan、Evidence、源码 checkpoint 和状态一致;
433
- - provider 或 Worker 自报结果均已由 Lead 核对,未核对项保持 `unverified`。
434
-
435
- ## 3. Gate 关闭仪式
411
+ - 无未批准偏差、未处置高风险残余问题或伪装成通过的 `unverified` 声明;
412
+ - Ticket、Map、Goal Plan、Evidence、代码事实和状态一致。
436
413
 
437
- 每个 Gate 关闭时:
414
+ ## 3. Gate 关闭与 change 完成
438
415
 
439
- 1. 汇总覆盖的 `specdev/changes/{change}/evidence/T-NN.md`;
440
- 2. 检查对应合同和参考符合性;
441
- 3. 检查共享接口、数据、兼容、迁移和调用点;
442
- 4. 运行里程碑级验证;仅 UI 交互受影响时由 Lead 运行最小 E2E;
443
- 5. 对会出现“坏了但仍绿色”的关键门禁运行受控反向验证,记录失败信号和恢复后的通过证据;
444
- 6. 审查基线退化、失败分类、偏差、残余风险和恢复能力;
445
- 7. 获取适用人工批准;
446
- 8. 同步 `specdev/changes/{change}/goal-plan.md`、`specdev/changes/{change}/tickets-map.md` 和状态工件。
416
+ 每个 Gate 关闭时汇总覆盖 Evidence,检查合同、共享接口、数据、兼容、迁移和调用点,运行里程碑验证和适用 E2E,执行必要反向验证,审查偏差/风险/恢复能力,获取适用人工批准,并同步 Goal Plan、Map 和状态。
447
417
 
448
- ## 4. 不可协商约束
418
+ 最后一个 Gate 关闭后加载 下方 `<change-completion>` 标签:
449
419
 
450
- 只记录跨多个 Ticket 且不可由实现者改变的规则,例如数据完整性、wire format 兼容、旧协议收缩条件、shared owner、安全要求、发布窗口、回滚演练和批准点。
420
+ - Goal Plan 不含 `## Delegated Execution Addendum` 时,由最后一个计划内 “实现阶段” 汇总并完成 change;
421
+ - Goal Plan 含完整委派附录时,由 Lead 在独立验收后完成 change。
451
422
 
452
- 每条约束同时说明违反后果。可由实现者沿现有惯例选择、且不改变行为或风险的事项写入 Guidance,不伪装成硬约束。
423
+ triage 的 `external_action` 为 `pending-close` 或 `close-failed`,下一 Work 为 “请求分诊阶段”,否则进入 Archive。远程动作不参与本地 Gate 判断。
453
424
 
454
- 来源必须指向:
425
+ ## 4. 不可协商约束
455
426
 
456
- - `specdev/changes/{change}/spec.md`;
457
- - `specdev/changes/{change}/ADR.md`;
458
- - 具体 `specdev/changes/{change}/ticket/NN-<ticket-name>.md`;
459
- - 外部 Url 标签;
460
- - `specdev/config.json`。
427
+ 只记录跨多个 Ticket 且不可由实现者改变的规则,例如数据完整性、wire format 兼容、旧协议收缩条件、shared owner、安全要求、发布窗口、回滚演练和批准点。每条约束说明来源和违反后果;可由实现者沿惯例选择的事项写入 Guidance。
461
428
 
462
429
  ## 5. 偏差与暂停
463
430
 
464
- 偏差等级和处理遵循 下方 `<deviation-control>` 标签。
465
-
466
- 跨 Ticket 偏差还必须明确:
467
-
468
- - 暂停哪些 Wave 或 Ticket;
469
- - 哪个 Gate 重新打开;
470
- - 哪些 Agent 需要重新基线;
471
- - 哪些 Evidence 失效;
472
- - 重新开始的条件。
473
-
474
- ## 6. 风险、修正与恢复
431
+ 偏差遵循 下方 `<deviation-control>` 标签。跨 Ticket 偏差还要说明暂停哪些 Wave/Ticket、重新打开哪个 Gate、哪些执行者需要新基线、哪些 Evidence 失效和恢复条件。
475
432
 
476
- 每个高风险项写明:触发信号、事故半径、预防措施、检测方式、恢复动作、owner 和批准点。迁移或发布计划必须给出回滚不可行时的前向恢复方案。
433
+ ## 6. 风险与恢复
477
434
 
478
- 每个 Dispatch Packet 记录 checkpoint、workspace/session locator、最近已验证 Evidence 和 `max_correction_rounds`。默认同一验收项最多修正 3 轮;达到上限后暂停当前 Ticket 和受影响 Wave,保留已通过行为,形成包含失败命令、最小错误、责任方和恢复条件的 blocker。
435
+ 每个高风险项写明触发信号、事故半径、预防、检测、恢复、owner 和批准点。迁移或发布计划必须给出回滚不可行时的前向恢复方案。
479
436
 
480
- 恢复时依次读取 `specdev/changes/{change}/goal-plan.md`、当前 Ticket、最新 Evidence 和 `specdev/changes/{change}/.status.json`。从最后已验证 checkpoint 继续,不重复询问已确认事实,也不创建额外进度或阻塞文件。
437
+ 恢复时依次读取 Goal Plan、当前 Ticket、最新 Evidence 和 change 状态,从最后已验证事实继续,不重复询问已确认事项,也不创建额外进度或阻塞文件。委派专属的 checkpoint、locator 和修正轮次由委派附录管理。
481
438
 
482
439
  ## 7. 进度与决策回报
483
440
 
@@ -487,14 +444,13 @@ Goal Plan 用紧凑摘要表达:
487
444
  WAVE_STATUS wave=<n> ready=<ids> active=<ids> done=<ids> blocked=<ids>
488
445
  GATE_STATUS gate=<name> state=open|closed evidence=<paths> risks=<summary>
489
446
  TICKET_STATUS id=<id> state=<state> evidence=<path> deviation=<none|id>
490
- DELIVERY_STATUS id=<id> model=<model> checkpoint=<sha> locator=<ref> corrections=<n> unverified=<items|none>
491
447
  BLOCKER id=<id> owner=<owner> needed=<decision-or-input> impact=<scope>
492
448
  DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
493
449
  ```
494
450
 
495
- 具体路径必须以本文约定的逻辑路径形式填写。
451
+ 委派 Goal Plan 的交付状态格式由委派协议提供,不加入普通 Goal Plan。
496
452
 
497
- **完成标准**:进度可由权威工件恢复;所有通过、阻塞和未验证声明均能定位到具体 Evidence 与源码 checkpoint。
453
+ **完成标准**:进度可由权威工件恢复;普通计划由最后一个 Implement 完成,委派计划由 Lead 完成;所有通过、阻塞和未验证声明均能定位到具体 Evidence 与代码事实。
498
454
 
499
455
  </completion-control>
500
456
 
@@ -534,7 +490,7 @@ ready_for_execution: false
534
490
  | 优先级 | 来源 | 负责内容 | 冲突处理 |
535
491
  |---|---|---|---|
536
492
  | 1 | 用户最新明确决定 | 产品取舍与批准 | 更新真正拥有该决策的工件 |
537
- | 2 | `specdev/changes/{change}/ADR.md` | 已接受架构决策 | 通过新决策替代 |
493
+ | 2 | `specdev/changes/{change}/ADR.md` | 当前 change 架构决定 | 通过新决定替代 |
538
494
  | 3 | `specdev/changes/{change}/spec.md` | 外部行为、范围与验收 | 下游不得改写 |
539
495
  | 4 | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单 Ticket 契约 | Goal Plan 只编排 |
540
496
  | 5 | 当前代码事实 | 现状与可行性 | 冲突时触发偏差 |
@@ -554,11 +510,9 @@ ready_for_execution: false
554
510
 
555
511
  ### Ticket Quick Reference
556
512
 
557
- <!-- Ticket 较多或执行者需要时添加;数据从 Ticket 与 Tickets Map 提取。 -->
558
-
559
513
  | ID | Ticket | 行为产出 | Depth/Risk | Dependencies | Wave/Gate | Owner | Evidence |
560
514
  |---|---|---|---|---|---|---|---|
561
- | T-01 | `specdev/changes/{change}/ticket/01-<name>.md` | ... | standard/medium | — | W0/G0 | lead | `specdev/changes/{change}/evidence/T-01.md` |
515
+ | T-01 | `specdev/changes/{change}/ticket/01-<name>.md` | ... | standard/medium | — | W0/G0 | `<owner>` | `specdev/changes/{change}/evidence/T-01.md` |
562
516
 
563
517
  ## 3. Gates and Completion Evidence
564
518
 
@@ -576,17 +530,10 @@ ready_for_execution: false
576
530
 
577
531
  ## 4. Execution and Integration Protocol
578
532
 
579
- ### Delivery Contract
533
+ ### Ticket Execution Order
580
534
 
581
- | 字段 | |
582
- |---|---|
583
- | Execution model | direct / native-subagent / external-web-subagent |
584
- | Lead / Provider | `<owner>` / `<provider-or-none>` |
585
- | Repository / Branch | `<repository-or-local>` / `<branch-or-n/a>` |
586
- | Checkpoint policy | immutable SHA / local baseline |
587
- | Source delivery | none / repository-url / source-package / combination |
588
- | Max concurrency / corrections | `<n>` / `3` |
589
- | Review | standards + spec + Lead verification + conditional E2E |
535
+ | Ticket | 开始条件 | 执行 owner | 必跑验证 | Evidence | 集成条件 |
536
+ |---|---|---|---|---|---|
590
537
 
591
538
  ### Authorization Matrix
592
539
 
@@ -598,31 +545,9 @@ ready_for_execution: false
598
545
  | Deploy / Migration | allowed / not-authorized | ... |
599
546
  | Production configuration / feature / real user data | allowed / not-authorized | ... |
600
547
 
601
- ### Per-Ticket Dispatch Packets
602
-
603
- #### Dispatch: T-01
604
-
605
- - **Goal / observable result:**
606
- - **Priority on conflict:** correctness > contract completeness > speed,或当前项目裁决
607
- - **Implement / Ticket:** “实现阶段”;`specdev/changes/{change}/ticket/01-<name>.md`
608
- - **Authority / dependencies:** 相关合同、ADR/CONTEXT、已完成依赖 Evidence
609
- - **Wave / Gate / hard constraints:**
610
- - **Writable / read-only / shared owner:**
611
- - **Baseline / branch / workspace or session locator / package hash:**
612
- - **Preflight receipt:** 在 `specdev/changes/{change}/evidence/T-01.md` 记录目标、顺序、最大风险和基线差异,不超过 10 行
613
- - **Verification / baseline / reverse check:**
614
- - **Authorization / deviation / correction limit:**
615
- - **Return:** 状态、Evidence、locator、最终 checkpoint、commit/PR、未验证项、待 Lead E2E
616
-
617
- 并行写代码时记录统一 `base_sha`,并为每个 Ticket 指定分支、`workspace_ref` 和 worktree owner。每个派单块可以独立投递,但不复制完整 Ticket 或历史对话。
618
-
619
- ### Ticket Execution
620
-
621
- 引用 “实现阶段” 和对应 `specdev/changes/{change}/ticket/NN-<ticket-name>.md`,不复制 Ticket 全文。
622
-
623
548
  ### Evidence Return and Integration
624
549
 
625
- Worker Ticket 推进到 `review`,返回 Ticket ID 与状态、Evidence 路径、`workspace_ref`、commit PR 引用,以及条件性 Lead E2E;Lead 负责集成、回归和 worktree 收尾。
550
+ 每个实现者按 I-implement 与对应 Ticket 执行,写入 Evidence 并同步 Ticket/Map/Goal Plan。最后一个计划内 Implement 汇总 Gate、运行适用集成验证,并按完成合同关闭 change。
626
551
 
627
552
  ## 5. Constraints, Risk and Recovery
628
553
 
@@ -646,15 +571,15 @@ Worker 将 Ticket 推进到 `review`,返回 Ticket ID 与状态、Evidence 路
646
571
 
647
572
  ### Current Status
648
573
 
649
- 记录 Wave/Gate、Ticket、checkpoint、workspace/session locator、修正轮次和未验证项;不使用主观百分比。
574
+ 记录 Wave/Gate、Ticket、最近验证证据和未验证项;不使用主观百分比。
650
575
 
651
576
  ### Pending Decisions and Blockers
652
577
 
653
- 达到修正上限时记录最后可信 checkpoint、失败命令、已通过行为、owner 和恢复条件。
578
+ 记录失败命令、已通过行为、owner 和恢复条件。
654
579
 
655
580
  ### Resume Protocol
656
581
 
657
- 恢复时读取本 Goal Plan、当前 Ticket、最新 Evidence 和 change 状态,从最后已验证 checkpoint 继续。
582
+ 恢复时读取本 Goal Plan、当前 Ticket、最新 Evidence 和 change 状态,从最后已验证事实继续。
658
583
 
659
584
  ### Reporting Format
660
585
 
@@ -664,6 +589,44 @@ Worker 将 Ticket 推进到 `review`,返回 Ticket ID 与状态、Evidence 路
664
589
 
665
590
  </goal-plan-template>
666
591
 
592
+ <delegated-execution-template>
593
+
594
+ ## Delegated Execution Addendum
595
+
596
+ ### Delivery Contract
597
+
598
+ | 字段 | 值 |
599
+ |---|---|
600
+ | Execution model | native-subagent / external-web-subagent |
601
+ | Lead / Provider | `<owner>` / `<provider>` |
602
+ | Repository / Branch | `<repository-or-local>` / `<branch>` |
603
+ | Checkpoint policy | immutable SHA / equivalent fixed baseline |
604
+ | Source delivery | repository-url / source-package / combination |
605
+ | Max concurrency / corrections | `<n>` / `3` |
606
+ | Review | standards + spec + Lead verification + conditional E2E |
607
+
608
+ ### Per-Ticket Dispatch Packets
609
+
610
+ #### Dispatch: T-01
611
+
612
+ - **Goal / observable result:**
613
+ - **Priority on conflict:** correctness > contract completeness > speed,或当前项目裁决
614
+ - **Implement / Ticket:** “实现阶段”;`specdev/changes/{change}/ticket/01-<name>.md`
615
+ - **Authority / dependencies:** 相关合同、ADR/CONTEXT、已完成依赖 Evidence
616
+ - **Wave / Gate / hard constraints:**
617
+ - **Writable / read-only / shared owner:**
618
+ - **Baseline / branch / workspace or session locator / package hash:**
619
+ - **Preflight receipt:** 在 `specdev/changes/{change}/evidence/T-01.md` 记录目标、顺序、最大风险和基线差异,不超过 10 行
620
+ - **Verification / baseline / reverse check:**
621
+ - **Authorization / deviation / correction limit:**
622
+ - **Return:** 状态、Evidence、locator、最终 checkpoint、commit/PR、未验证项、待 Lead E2E
623
+
624
+ ### Candidate Delivery Return and Lead Integration
625
+
626
+ Worker 将 Ticket 推进到 `review` 并返回候选交付;Lead 负责独立验证、适用 E2E、集成、Gate 关闭和 worktree 收尾。达到修正上限时保留最后可信 checkpoint、失败命令、已通过行为和恢复条件。
627
+
628
+ </delegated-execution-template>
629
+
667
630
  <artifact-contract>
668
631
 
669
632
  # 工件职责与权威裁决
@@ -674,33 +637,44 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
674
637
 
675
638
  | 工件 | 具体位置 | 必须决定 | 不应决定 |
676
639
  |---|---|---|---|
677
- | 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入和下一 work | 详细实现方案 |
640
+ | 来源快照 | `specdev/changes/{change}/source.md` | 原始请求、捕获时间、locator、hash 和关闭能力 | 当前产品合同或实现状态 |
641
+ | 分诊 | `specdev/changes/{change}/triage.md` | 请求类别、影响、风险、缺失输入、下一 work 和远程 reconcile 状态 | 详细实现方案或开发进度 |
678
642
  | 诊断 | `specdev/changes/{change}/diagnosis.md` | 复现、证据、根因、修复不变量和回归契约 | 未经验证的修复实现 |
679
643
  | 设计日志 | `specdev/changes/{change}/LOG.md` | 讨论轨迹、确认、延后、替代与废弃结论 | 当前架构权威摘要 |
680
644
  | 设计树 | `specdev/changes/{change}/design-tree.json` | 决策节点、依赖、当前 frontier、轮次与共识状态 | 领域真相或架构决定正文 |
681
- | 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | 当前领域术语、语义和稳定不变量 | 临时会议记录 |
682
- | 架构决策 | `specdev/changes/{change}/ADR.md` | 已接受架构决策、原因、后果和替代关系 | 尚未决定的方案集合 |
645
+ | Change 领域上下文 | `specdev/changes/{change}/CONTEXT.md` | change 已确认、供下游使用的领域术语和语义 | 永久领域知识或临时会议记录 |
646
+ | Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
683
647
  | Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
684
648
  | Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
685
649
  | Tickets Map | `specdev/changes/{change}/tickets-map.md` | 依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
686
650
  | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
687
651
  | Evidence | `specdev/changes/{change}/evidence/T-NN.md` | 实际修改、命令、结果、验收映射、偏差、风险和提交引用 | 新的产品或架构决策 |
652
+ | 代码审查 | `specdev/changes/{change}/reviews/CR-###.md` | 固定点、标准轴和规范轴 finding | 实施修复或合并两轴排名 |
653
+ | 原型记录 | `specdev/changes/{change}/prototypes/{prototype-id}/record.md` | 一个问题、分支、资产、答案、promotion 和清理 | 生产实现或多个问题的计划 |
654
+ | Stakeholder 问卷 | `specdev/changes/{change}/questionnaires/{slug}.md` | 第三方原始回答和恢复条件 | 未经转录确认的产品/架构决定 |
688
655
  | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
689
656
  | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
690
657
  | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
691
658
  | 架构审查 | `specdev/changes/{change}/architecture-review.md` 与 `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
692
659
 
660
+ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永久知识。G 和其他设计/执行 Works 只读 `specdev/context/` 与 `specdev/adr/`;只有 A 在 change 完成、实现证据验证、毕业评估和用户确认后才能写入永久 namespace。未毕业内容随归档 change 保留,不能从 change 工件消失。
661
+
693
662
  ## 2. 权威顺序
694
663
 
695
664
  同一事项冲突时按下列顺序裁决:
696
665
 
697
666
  1. 用户最新明确决定;
698
- 2. 当前已接受架构决策:`specdev/changes/{change}/ADR.md`;
699
- 3. 当前外部行为权威:`specdev/changes/{change}/spec.md`;
700
- 4. 当前 Ticket 契约:`specdev/changes/{change}/ticket/NN-<ticket-name>.md`;
701
- 5. 当前跨 Ticket 编排:`specdev/changes/{change}/goal-plan.md`;
702
- 6. 当前代码与运行事实;
703
- 7. 旧计划、旧日志和未经确认的推断。
667
+ 2. 当前 change 已接受的架构决策:`specdev/changes/{change}/ADR.md`;
668
+ 3. 永久 ADR 与领域上下文:`specdev/adr/`、`specdev/context/`;
669
+ 4. 当前外部行为权威:`specdev/changes/{change}/spec.md`;
670
+ 5. 当前 Ticket 契约:`specdev/changes/{change}/ticket/NN-<ticket-name>.md`;
671
+ 6. 当前跨 Ticket 编排:`specdev/changes/{change}/goal-plan.md`;
672
+ 7. 当前代码与运行事实;
673
+ 8. 旧计划、旧日志和未经确认的推断。
674
+
675
+ 当前 change 决定与永久知识冲突时,必须在 LOG/ADR 中显式说明替代关系;它只约束当前 change,直到 A 决定是否提升并更新永久版本。
676
+
677
+ `specdev/changes/{change}/source.md` 只对“原始输入是什么”具有权威;后续用户决定、ADR 和 Spec 可以显式演进该意图。远程来源在摄入后发生变化不会自动改写本地合同,必须重新 Triage。
704
678
 
705
679
  代码事实可以证明计划已过时,但不能静默改写用户目标或已接受契约。出现这种情况时,按 下方 `<deviation-control>` 标签 退回相应工件修订。
706
680
 
@@ -758,16 +732,16 @@ shared_paths: ["package.json"]
758
732
  1. 可能并行的 Ticket,其 `writable_paths` 不得相交。
759
733
  2. glob 与具体路径按覆盖关系判断,不得只比较字符串。
760
734
  3. 根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同文件默认视为 shared。
761
- 4. shared path 只能由 Lead 或专用 owner Ticket 修改;消费者 Ticket 只读。
735
+ 4. shared path 只能由专用 owner Ticket 或 Goal Plan 明确指定的唯一集成 owner 修改;消费者 Ticket 只读。委派 Goal Plan 可以把该 owner 指定为 Lead,但普通计划不预设角色。
762
736
  5. 需要越界时先停止,按 下方 `<deviation-control>` 标签 提出 ownership change;不得先改后报。
763
737
  6. 前置 Ticket 改变目录结构后,后续 Ticket 开始前重新解析项目路径;若授权范围语义未改变,可只更新导航路径。
764
738
  7. 不得把“最后解决合并冲突”当作所有权方案。
765
739
 
766
740
  ## 3. Worktree 与分支
767
741
 
768
- 并行写代码的 Ready Ticket 使用隔离 worktree;只读调查和顺序执行默认共用当前工作区。Worktree 防止工作区污染,路径所有权防止逻辑冲突,两者不能互相替代。
742
+ 需要并行或临时隔离项目写入时使用独立 worktree;只读调查和顺序执行默认共用当前工作区。Worktree 防止工作区污染,路径所有权防止逻辑冲突,两者不能互相替代。
769
743
 
770
- 生命周期由 Lead 按 下方 `<dev-worktree>` 标签 管理,编排规则位于 下方 `<orchestration-protocol>` 标签。
744
+ 生命周期由调用方明确的 workspace owner 按 下方 `<dev-worktree>` 标签 管理。普通 Goal Plan 由当前执行或集成 owner 负责;委派 Goal Plan 才把 workspace owner 映射为 Lead。编排规则位于 下方 `<orchestration-protocol>` 标签。
771
745
 
772
746
  </path-ownership>
773
747
 
@@ -799,7 +773,7 @@ shared_paths: ["package.json"]
799
773
  4. 可重复手动步骤、截图或查询结果;
800
774
  5. 代码阅读推断。
801
775
 
802
- E2E 仅在变更影响用户界面交互时加入验证矩阵,并且只由 Lead 在集成阶段执行。Worker 只记录场景、预期结果和待执行状态。API、CLI、后端、库或数据变更默认使用其稳定接缝,不追加 E2E。
776
+ E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由当前实现或集成 owner 运行;委派执行中 Worker 只记录场景、预期结果和待执行状态,由 Lead 在集成阶段运行。API、CLI、后端、库或数据变更默认使用其稳定接缝,不追加 E2E。
803
777
 
804
778
  低层证据不能替代明确要求的用户行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控信号或回滚演练。
805
779
 
@@ -842,7 +816,7 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵,并且只由 Lea
842
816
  ## 1. 偏差等级
843
817
 
844
818
  - **local**:只改变局部实现,不改变 Ticket 的行为、范围、公共契约、路径所有权或验证;记录到 Evidence 后可继续。
845
- - **ticket**:改变 Ticket 的执行路线、可写范围、局部契约或验收映射,但不改变 Spec;必须停止相关修改、更新 Ticket 并获得 owner Lead 批准。
819
+ - **ticket**:改变 Ticket 的执行路线、可写范围、局部契约或验收映射,但不改变 Spec;必须停止相关修改、更新 Ticket 并获得该 Ticket 或计划明确的批准 owner 同意。
846
820
  - **spec**:改变外部行为、范围、用户故事、验收合同或非功能要求;必须返回 “编写 Spec 阶段”。
847
821
  - **architecture**:改变已接受架构决策或公共架构约束;必须返回 “设计访谈能力” 并更新 `specdev/changes/{change}/ADR.md`。
848
822
  - **release**:改变迁移、兼容窗口、发布门禁、回滚或不可逆批准点;必须停止并获得明确人工批准。
@@ -877,50 +851,100 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵,并且只由 Lea
877
851
 
878
852
  - 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
879
853
  - 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
880
- - 偏差影响并发 Agent 时,Lead 必须暂停受影响 Wave,重新计算路径所有权、依赖和 Gate
854
+ - 偏差影响普通并行执行时,当前集成 owner 必须暂停受影响 Wave,重新计算路径所有权、依赖和 Gate;委派执行由 Lead 承担同一责任。
881
855
 
882
856
  </deviation-control>
883
857
 
858
+ <change-completion>
859
+
860
+ # Change Completion
861
+
862
+ 本规则是 change 从 active/blocked 转为 completed 的唯一合同,并由 Implement、Goal Plan、Triage、Status 与 Archive 共同读取。
863
+
864
+ ## 完成门
865
+
866
+ 一个 change 只有同时满足以下条件才能设置 `change_status: completed`:
867
+
868
+ 1. 所有计划内 Ticket 为 `done`,或有明确批准理由的 `cancelled`;无 Ticket 的 Direct Spec/非实现流程有等价的验收清单。
869
+ 2. 每个完成行为有 Evidence,全部 Spec 验收合同和适用 Goal Gate 可定位。
870
+ 3. 项目级验证通过;既有或环境失败已分类、接受并记录风险。
871
+ 4. 迁移、发布、监控、回滚和不可逆批准已完成或明确不适用。
872
+ 5. 没有未批准 deviation、未处置 blocker 或伪装成通过的 `unverified` 声明。
873
+ 6. Ticket、Map、Goal Plan、Evidence、源码 checkpoint 和 change 状态一致。
874
+
875
+ ## 转换 Owner
876
+
877
+ - Goal Plan 含完整 `## Delegated Execution Addendum`:Lead 在独立验收并关闭最后一个 Gate 后拥有完成转换。
878
+ - Goal Plan 不含委派附录,或无 Goal Plan 的 Ticket/Direct Spec 实现:最后一个计划内 Implement 在最后一项验收通过后拥有完成转换。
879
+ - 非实现型终点:最后一个拥有最终验收工件的 Work 使用本规则完成转换。
880
+
881
+ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`,然后重读验证。全局 `specdev/status.json` 继续只保存 active 索引,不复制完成详情。
882
+
883
+ ## 远程来源与归档
884
+
885
+ 远程动作不参与本地完成判定。完成后若 `specdev/changes/{change}/triage.md` 的 `external_action` 为 `pending-close` 或 `close-failed`,下一路线是 Triage reconcile;`closed`、`waived` 或 `not-applicable` 才允许 Archive 移动 change。归档后工件只读,不在归档目录补写远程结果。
886
+
887
+ ## 完成标准
888
+
889
+ - 完成声明可以从本地工件和实际验证重建;
890
+ - 当前 change 只有一个条件命中的转换 owner;
891
+ - 远程失败不会把 completed 改回 active;
892
+ - Archive 不接收尚未 reconcile 或 waive 的远程来源。
893
+
894
+ </change-completion>
895
+
884
896
  <research>
885
897
 
886
898
  # SpecDev Research
887
899
 
888
- ## 触发
900
+ ## 输入
901
+
902
+ - `decision`:研究要支持的一个具体决定;
903
+ - `questions`:需要回答的穷尽问题集;
904
+ - `stop_condition`:何时证据已足够;
905
+ - `caller`:D、G、S、W、R、T 或 I;
906
+ - `target_artifact`:调用方拥有且将接收结果的完整 Path。
889
907
 
890
- 当外部 API、库版本、协议、法规、产品能力或最佳实践会改变设计/实现决策,且当前材料不足时使用。
908
+ 缺少 owner 或 target 时返回阻塞,不创建 `{change}/research/` 等共享 namespace。
891
909
 
892
910
  ## 流程
893
911
 
894
- 1. 写清楚要支持的具体决策和停止条件。
895
- 2. 优先官方文档、规范、源代码、论文或维护者材料;技术问题优先一手来源。
896
- 3. 核对版本、发布日期、适用环境和已知限制。
897
- 4. 区分:来源明确事实、代码库事实、推断、建议。
898
- 5. 对关键结论至少交叉验证;来源冲突时并列呈现,不强行调和。
899
- 6. 记录摘要、证据、置信度、对 ADR/Spec/Ticket 的影响和仍未知项。
900
- 7. 长期有效且经实现验证后才可由 Archive 提升到永久 research。
912
+ 1. 固定问题、版本、环境和停止条件。
913
+ 2. 优先官方文档、规范、源代码、论文或维护者材料;技术问题使用一手来源。
914
+ 3. 核对发布日期、版本、适用环境、限制和已知冲突。
915
+ 4. 对每个会改变决定的实质声明就近给出来源;关键结论交叉验证,来源冲突时并列呈现。
916
+ 5. 区分来源事实、代码库事实、推断、建议和未知项。
917
+ 6. 返回一个 Markdown block,由 caller 原子写入 `target_artifact`;本 Skill 不自行写 state。
901
918
 
902
- ## 输出模板
919
+ ## 输出
903
920
 
904
921
  ```markdown
905
- # Research: <问题>
906
- - 决策用途:
907
- - 范围/版本:
908
- - 停止条件:
922
+ ## Research: <问题>
923
+ - Decision / target:
924
+ - Scope / version:
925
+ - Stop condition:
909
926
 
910
- ## Findings
911
927
  ### R-001
912
- - 结论:
913
- - 类型:官方事实 / 代码事实 / 推断 / 建议
914
- - 来源:
915
- - 置信度:high / medium / low
916
- - 适用限制:
917
- - 对工件影响:
918
-
919
- ## Conflicts and Unknowns
920
- ## Recommendation
928
+ - Claim:
929
+ - Type: official fact / code fact / inference / recommendation
930
+ - Source:
931
+ - Confidence:
932
+ - Limits:
933
+ - Artifact impact:
934
+
935
+ ### Conflicts and Unknowns
936
+ ### Recommendation
921
937
  ```
922
938
 
923
- 不得长篇复制受版权保护的来源;使用短引文和自己的准确摘要。
939
+ 不得长篇复制受版权保护内容。长期有效且经实现验证的结论只能由 Archive 从调用方工件提升到永久 research。
940
+
941
+ ## 完成标准
942
+
943
+ - 每个输入问题有答案或明确未知;
944
+ - 每个实质声明就近引用一手来源;
945
+ - 版本、限制、冲突和置信度已记录;
946
+ - 结果有唯一 owning artifact;
947
+ - 本 Skill 没有创建自己的 state 路径。
924
948
 
925
949
  </research>
926
950
 
@@ -930,79 +954,89 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵,并且只由 Lea
930
954
 
931
955
  ## 适用范围
932
956
 
933
- - 仅用于并行写代码且路径所有权不冲突的 Ready Ticket
957
+ - 用于并行写代码且路径所有权不冲突的 Ready Ticket,或明确要求临时隔离的一次性原型。
934
958
  - 只读调查和顺序执行默认共用当前工作区。
935
- - Lead 管理创建、集成和清理;Worker 只实现、验证并返回 Evidence。
959
+ - 调用方必须明确 workspace owner、implementation owner、固定基线、工作项 ID、持久化 owner 和允许的结束动作。
960
+ - 普通执行不建立额外角色;委派 Goal Plan 才把 workspace owner/implementation owner 分别映射为 Lead/Worker。
936
961
  - 平台原生 worktree 优先;不可用时使用 Git worktree。
937
962
 
938
963
  ## 生命周期
939
964
 
940
965
  1. 创建或恢复时加载 下方 `<dev-worktree-create>` 标签。
941
- 2. Worker 完成后将记录从 `active` 更新为 `review`,返回 Ticket 状态、Evidence 路径、`workspace_ref`、commit 或 PR 引用,以及条件性 Lead E2E。
942
- 3. Lead 集成或清理时加载 下方 `<dev-worktree-finalize>` 标签。
966
+ 2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref`、checkpoint、commit 或 PR 引用和未验证项;Ticket worktree 从 `active` 更新为 `review`。
967
+ 3. workspace owner 集成或清理时加载 下方 `<dev-worktree-finalize>` 标签;一次性原型只评估和清理,不合入生产分支。
943
968
 
944
- 状态依次为 `planned → active → review → integrated → removed`;失败进入 `blocked`。记录写入 `specdev/changes/{change}/.status.json` 的 `worktrees`。
969
+ Ticket worktree 状态依次为 `planned → active → review → integrated → removed`;失败进入 `blocked`,记录写入 `specdev/changes/{change}/.status.json` 的 `worktrees`。原型的 branch、`workspace_ref` 和清理结果只写入 `specdev/changes/{change}/prototypes/{prototype-id}/record.md`,不伪造 Ticket worktree 记录。
945
970
 
946
971
  ## 边界
947
972
 
948
- - 每个并行 Ticket 使用独立 worktree、分支和相同 `base_sha`。
949
- - 持久状态只保存 `workspace_ref`,不保存机器绝对路径。
950
- - E2E 仅由 Lead 在集成阶段执行,且仅适用于用户界面交互受影响的变更。
973
+ - 每个并行 Ticket 使用独立 worktree、分支和相同 `base_sha`;每个原型使用独立 worktree 和分支。
974
+ - Git provider 固定使用 `<project-root>/specdev-worktree/<work-item-id>/`,持久化 `workspace_ref: specdev-worktree/<work-item-id>`;`<project-root>` 由 `workspace.json#path_base: project-root` 解析。
975
+ - native/external provider 保留其可迁移 opaque locator;所有 provider 都不保存机器绝对路径、认证秘密或真实用户数据。
976
+ - 项目根 `.gitignore` 的 `specdev-worktree/` 条目由 `speculo init` 单一维护;缺失时创建流程阻塞并提示重新运行 init。
977
+ - E2E 仅适用于用户界面交互受影响的变更。普通执行由当前集成 owner 运行;委派执行由 Lead 在集成阶段运行。
951
978
  - 合并、推送、PR、删除分支或 worktree 仍需用户授权。
952
979
 
953
980
  </dev-worktree>
954
981
 
955
982
  <dev-worktree-create>
956
983
 
957
- # 创建或恢复 Ticket Worktree
984
+ # 创建或恢复工作项 Worktree
958
985
 
959
986
  ## 前置
960
987
 
961
- - Ticket `ready: true`,依赖完成,写路径无冲突。
962
- - `specdev/config.json` 中 `git.worktree_for_parallel: true`。
963
- - Lead 已固定所有并行 Ticket 共用的 `base_sha`。
988
+ - Ticket `ready: true` 且依赖完成,或原型问题与临时写入范围已锁定;项目写路径无冲突。
989
+ - 并行 Ticket 要求 `specdev/config.json` 中 `git.worktree_for_parallel: true`;一次性原型要求 P-prototype 已取得本次临时 worktree 授权。
990
+ - 调用方已指定 workspace owner、implementation owner、工作项 ID、持久化 owner,并固定 `base_sha`;并行 Ticket 共用同一基线。
964
991
 
965
992
  ## 创建
966
993
 
967
- 1. `specdev/changes/{change}/.status.json` `worktrees` 已有该 Ticket `active` `review` 记录,解析 `workspace_ref` 并验证分支、`base_sha` 和工作区状态;一致则恢复。
968
- 2. 否则优先调用平台原生 worktree 能力;不可用时从 `base_sha` 执行 `git worktree add -b <ticket-branch> <physical-path> <base-sha>`。物理路径必须位于主工作树之外。
969
- 3. 分支使用 `speculo/<change>/<ticket-id>`;现有分支或目标路径未能匹配记录时停止。
970
- 4. 安装项目所需依赖,运行最小基线检查。E2E 不属于 Worker 基线。
971
- 5. 写入 `worktrees`:
994
+ 1. Speculo 工作区声明的 `path_base: project-root` 解析 `<project-root>`。若记录的 provider `git`,要求 `workspace_ref` 精确为 `specdev-worktree/<work-item-id>`,拼接后仍位于 project root,且 `specdev-worktree/` 不是逃逸到外部的符号链接。
995
+ 2. 读取调用方拥有的持久化记录:Ticket 使用 `specdev/changes/{change}/.status.json` `worktrees`;原型使用 `specdev/changes/{change}/prototypes/{prototype-id}/record.md`。若已有可恢复记录,Git provider 必须在 `git worktree list --porcelain` 中匹配固定路径、分支与 `base_sha`;native/external 由对应 provider 解析 opaque locator。一致则恢复,任一不一致停止。
996
+ 3. 否则优先调用平台原生 worktree 能力。使用 native/external 时保存 provider 返回的可迁移 locator;不可用时进入 Git fallback。
997
+ 4. Git fallback 前确认项目根 `.gitignore` 已包含 `specdev-worktree/` 或等价根模式。缺失时停止并提示重新运行当前版本 `speculo init`,不在本 Skill 内修改 `.gitignore`。
998
+ 5. Git fallback 固定 `physical_path = <project-root>/specdev-worktree/<work-item-id>`、`workspace_ref = specdev-worktree/<work-item-id>`,从 `base_sha` 执行 `git worktree add -b <work-item-branch> <physical-path> <base-sha>`。已存在但未与同一记录和 Git 注册匹配的目标路径一律阻塞。
999
+ 6. 分支使用 `speculo/<change>/<work-item-id>`;现有分支未能匹配记录时停止。
1000
+ 7. 安装项目所需依赖,运行最小基线检查。E2E 不属于 implementation owner 的创建基线。
1001
+ 8. Ticket 将记录写入 `worktrees`:
972
1002
 
973
1003
  ```json
974
1004
  {
975
1005
  "ticket_id": "T-01",
976
- "owner": "<worker>",
977
- "provider": "native",
1006
+ "owner": "<implementation-owner>",
1007
+ "provider": "git",
978
1008
  "base_sha": "<sha>",
979
1009
  "branch": "speculo/<change>/T-01",
980
- "workspace_ref": "<provider-opaque-or-project-relative-ref>",
1010
+ "workspace_ref": "specdev-worktree/T-01",
981
1011
  "status": "active",
982
1012
  "updated_at": "<ISO-8601>"
983
1013
  }
984
1014
  ```
985
1015
 
986
- 完成条件:工作区可定位、基线可用、状态记录与实际分支一致。失败时设为 `blocked` 并保留现场。
1016
+ native/external provider 将示例中的 provider 与 `workspace_ref` 换为对应可迁移 locator,不套用 Git 物理路径。原型不使用本 JSON 结构,只在 record 的 Run and Assets 中记录源码 branch/commit,并在 frontmatter 写入 `workspace_ref` 与清理状态。
1017
+
1018
+ 完成条件:工作区可定位、基线可用、调用方记录与实际 provider、分支和 checkpoint 一致;Git provider 的引用与工作项 ID 完全一致。失败时在调用方拥有的记录中设为 `blocked` 并保留现场。
987
1019
 
988
1020
  </dev-worktree-create>
989
1021
 
990
1022
  <dev-worktree-finalize>
991
1023
 
992
- # 集成与清理 Ticket Worktree
1024
+ # 集成与清理工作项 Worktree
1025
+
1026
+ ## 集成
993
1027
 
994
- ## Lead 集成
1028
+ 仅生产 Ticket 进入本段;一次性原型不得合入生产分支。
995
1029
 
996
- 1. 确认记录为 `review`,读取 Worker Evidence,实际修改未越过路径契约。
1030
+ 1. workspace owner 确认记录为 `review`,读取 implementation owner 的 Evidence,实际修改未越过路径契约。
997
1031
  2. 在目标集成基线上应用变更并运行受影响的定向与回归验证。
998
- 3. 仅当变更影响用户界面交互时,由 Lead 运行验收所需的最小 E2E;Worker 只提供场景和预期结果。
1032
+ 3. 仅当变更影响用户界面交互时,由当前集成 owner 运行验收所需的最小 E2E;委派执行中 implementation owner 只提供场景和预期结果,Lead 负责运行。
999
1033
  4. 验证通过后将记录更新为 `integrated`;冲突或失败时设为 `blocked` 并保留 worktree。
1000
1034
 
1001
1035
  ## 清理
1002
1036
 
1003
1037
  1. 取得用户对删除 worktree 和分支的授权。
1004
- 2. 从主工作树或平台管理入口移除已集成 worktree
1005
- 3. 确认 worktree 不再注册后删除对应分支,并将状态更新为 `removed`。
1038
+ 2. Git provider 从 project root 解析 `specdev-worktree/<work-item-id>`,重验无路径逃逸且与 `git worktree list --porcelain` 的记录一致,再从主工作树移除;native/external 通过对应 provider 管理入口移除。
1039
+ 3. 确认 worktree 不再注册且工作项目录不存在后删除对应分支。Ticket 将状态更新为 `removed`;原型把 `cleanup_status` 更新为 `clean`。保留项目根 `specdev-worktree/` 统一目录及 `.gitignore` 条目。
1006
1040
 
1007
1041
  PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明确要求时使用强制删除。
1008
1042
 
@@ -1017,12 +1051,12 @@ PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明
1017
1051
  ## 输入
1018
1052
 
1019
1053
  - `operation`:`plan` 或 `execute`;
1020
- - `execution_model`:`direct`、`native-subagent` 或 `external-web-subagent`;
1054
+ - `execution_model`:`native-subagent` 或 `external-web-subagent`;
1021
1055
  - Lead、Ticket、Goal Plan、Spec、适用 ADR/CONTEXT、Wave/Gate 和依赖 Evidence;
1022
1056
  - 项目写、只读和 shared 路径,验证矩阵与当前源码基线;
1023
1057
  - provider、会话或 workspace locator、源码交付方式,以及用户当前明确授权。
1024
1058
 
1025
- 缺失 Goal Plan 的 `direct` Ticket 可以由 “实现阶段” Ticket 契约执行;其他输入缺失时返回调用方补齐,不猜测 checkpoint、权限或验收结果。
1059
+ 普通 Goal Plan 和缺失 Goal Plan 的 Ticket 直接由 “实现阶段” 执行,不调用本 Skill。委派输入缺失时返回调用方补齐,不猜测 checkpoint、权限或验收结果。
1026
1060
 
1027
1061
  ## 流程
1028
1062
 
@@ -1044,7 +1078,6 @@ PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明
1044
1078
 
1045
1079
  ### 3. 加载执行分支
1046
1080
 
1047
- - `direct`:直接使用 Ticket、Goal Plan、“实现阶段” 和 Evidence 合同,不加载 provider 规则;
1048
1081
  - `native-subagent`:加载 下方 `<subagent-delivery-native>` 标签,完成隔离派单、恢复和返回;
1049
1082
  - `external-web-subagent`:加载 下方 `<subagent-delivery-external-web>` 标签,完成能力探测、会话恢复、候选交付与修正。
1050
1083
 
@@ -1209,7 +1242,7 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1209
1242
  "execution": {
1210
1243
  "max_parallel": 3,
1211
1244
  "deep_ticket_human_approval": true,
1212
- "shared_path_owner": "lead"
1245
+ "shared_path_owner": "explicit"
1213
1246
  },
1214
1247
  "verification": {
1215
1248
  "test": null,
@@ -1292,11 +1325,10 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1292
1325
 
1293
1326
  ```json
1294
1327
  {
1295
- "schema_version": 3,
1328
+ "schema_version": 4,
1296
1329
  "workflow": "specdev",
1297
1330
  "active": [],
1298
- "work_history": [],
1299
- "completed": []
1331
+ "archived": []
1300
1332
  }
1301
1333
  ```
1302
1334
 
@@ -1307,19 +1339,18 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1307
1339
  ```json
1308
1340
  {
1309
1341
  "$schema": "https://json-schema.org/draft/2020-12/schema",
1310
- "$id": "urn:speculo:specdev:status:v3",
1342
+ "$id": "urn:speculo:specdev:status:v4",
1311
1343
  "title": "SpecDev Global Status",
1312
1344
  "type": "object",
1313
1345
  "required": [
1314
1346
  "schema_version",
1315
1347
  "workflow",
1316
1348
  "active",
1317
- "work_history",
1318
- "completed"
1349
+ "archived"
1319
1350
  ],
1320
1351
  "properties": {
1321
1352
  "schema_version": {
1322
- "const": 3
1353
+ "const": 4
1323
1354
  },
1324
1355
  "workflow": {
1325
1356
  "const": "specdev"
@@ -1331,30 +1362,27 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1331
1362
  "required": [
1332
1363
  "change",
1333
1364
  "current_work",
1334
- "works_run",
1335
- "result"
1365
+ "works_run"
1336
1366
  ],
1337
1367
  "properties": {
1338
1368
  "change": {
1339
- "type": "string"
1369
+ "type": "string",
1370
+ "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
1340
1371
  },
1341
1372
  "current_work": {
1342
1373
  "type": [
1343
1374
  "string",
1344
1375
  "null"
1345
- ]
1376
+ ],
1377
+ "pattern": "^specdev/"
1346
1378
  },
1347
1379
  "works_run": {
1348
1380
  "type": "array",
1349
1381
  "items": {
1350
- "type": "string"
1351
- }
1352
- },
1353
- "result": {
1354
- "type": [
1355
- "string",
1356
- "null"
1357
- ]
1382
+ "type": "string",
1383
+ "pattern": "^specdev/"
1384
+ },
1385
+ "uniqueItems": true
1358
1386
  },
1359
1387
  "claimed_investigations": {
1360
1388
  "type": "array",
@@ -1382,77 +1410,23 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1382
1410
  "type": "string"
1383
1411
  }
1384
1412
  },
1385
- "additionalProperties": true
1413
+ "additionalProperties": false
1386
1414
  }
1387
1415
  }
1388
1416
  },
1389
- "additionalProperties": true
1390
- }
1391
- },
1392
- "work_history": {
1393
- "type": "array",
1394
- "items": {
1395
- "type": "object",
1396
- "required": [
1397
- "change",
1398
- "work_id",
1399
- "started_at",
1400
- "completed_at",
1401
- "result"
1402
- ],
1403
- "properties": {
1404
- "change": {
1405
- "type": "string"
1406
- },
1407
- "work_id": {
1408
- "type": "string",
1409
- "pattern": "^specdev/"
1410
- },
1411
- "started_at": {
1412
- "type": "string"
1413
- },
1414
- "completed_at": {
1415
- "type": [
1416
- "string",
1417
- "null"
1418
- ]
1419
- },
1420
- "result": {
1421
- "type": [
1422
- "string",
1423
- "null"
1424
- ]
1425
- }
1426
- },
1427
- "additionalProperties": true
1417
+ "additionalProperties": false
1428
1418
  }
1429
1419
  },
1430
- "completed": {
1420
+ "archived": {
1431
1421
  "type": "array",
1432
1422
  "items": {
1433
- "type": "object",
1434
- "required": [
1435
- "change",
1436
- "archived_at",
1437
- "archive_path"
1438
- ],
1439
- "properties": {
1440
- "change": {
1441
- "type": "string"
1442
- },
1443
- "archived_at": {
1444
- "type": "string"
1445
- },
1446
- "archive_path": {
1447
- "type": "string",
1448
- "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
1449
- }
1450
- },
1451
- "additionalProperties": true
1452
- }
1423
+ "type": "string",
1424
+ "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
1425
+ },
1426
+ "uniqueItems": true
1453
1427
  }
1454
1428
  },
1455
- "additionalProperties": true
1429
+ "additionalProperties": false
1456
1430
  }
1457
1431
  ```
1458
1432
 
@@ -1630,6 +1604,49 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
1630
1604
  }
1631
1605
  },
1632
1606
  "allOf": [
1607
+ {
1608
+ "if": {
1609
+ "properties": {
1610
+ "worktrees": {
1611
+ "contains": {
1612
+ "properties": {
1613
+ "provider": {
1614
+ "const": "git"
1615
+ }
1616
+ },
1617
+ "required": [
1618
+ "provider"
1619
+ ]
1620
+ }
1621
+ }
1622
+ }
1623
+ },
1624
+ "then": {
1625
+ "properties": {
1626
+ "worktrees": {
1627
+ "items": {
1628
+ "if": {
1629
+ "properties": {
1630
+ "provider": {
1631
+ "const": "git"
1632
+ }
1633
+ },
1634
+ "required": [
1635
+ "provider"
1636
+ ]
1637
+ },
1638
+ "then": {
1639
+ "properties": {
1640
+ "workspace_ref": {
1641
+ "pattern": "^specdev-worktree/T-[0-9]{2,}$"
1642
+ }
1643
+ }
1644
+ }
1645
+ }
1646
+ }
1647
+ }
1648
+ }
1649
+ },
1633
1650
  {
1634
1651
  "if": {
1635
1652
  "properties": {