@namewta/speculo 0.7.1 → 0.7.2
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.
- package/README.md +2 -1
- package/package.json +1 -1
- package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md +178 -0
- package/template/canonical/canonical-specdev-goal-plan.md +386 -74
- package/template/canonical/canonical-specdev-grill-with-docs.md +178 -0
- package/template/canonical/canonical-specdev-spec.md +178 -0
- package/template/canonical/canonical-specdev-tickets.md +247 -21
- package/template/canonical/canonical-specdev-wayfinder.md +178 -0
- package/template/skills/optimize-codex-config/SKILL.md +81 -0
- package/template/skills/optimize-codex-config/references/configuration-contract.md +103 -0
- package/template/skills/optimize-codex-config/references/troubleshooting.md +79 -0
- package/template/skills/optimize-codex-config/scripts/audit-codex-config.mjs +747 -0
- package/template/workflows/specdev/I-implement/I-implement.md +11 -10
- package/template/workflows/specdev/I-implement/delegated-evidence-template.md +2 -1
- package/template/workflows/specdev/I-implement/execution-preflight.md +5 -3
- package/template/workflows/specdev/I-implement/merge-conflict-protocol.md +6 -5
- package/template/workflows/specdev/INDEX.md +5 -4
- package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +27 -18
- package/template/workflows/specdev/P-goal-plan/completion-control.md +3 -3
- package/template/workflows/specdev/P-goal-plan/delegated-execution-template.md +6 -4
- package/template/workflows/specdev/P-goal-plan/delegated-execution.md +13 -7
- package/template/workflows/specdev/P-goal-plan/goal-plan-template.md +11 -2
- package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md +7 -3
- package/template/workflows/specdev/P-goal-plan/planning-modes.md +23 -8
- package/template/workflows/specdev/P-goal-plan/workspace-execution-template.md +24 -0
- package/template/workflows/specdev/common/README.md +2 -2
- package/template/workflows/specdev/common/rules/change-completion.md +3 -2
- package/template/workflows/specdev/common/rules/path-ownership.md +2 -2
- package/template/workflows/specdev/common/schemas/change-status.schema.json +178 -0
- package/template/workflows/specdev/common/schemas/goal-plan.schema.json +10 -0
- package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +11 -11
- package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +19 -4
- package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +12 -5
- package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +4 -3
- package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md +1 -1
- package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md +2 -3
- package/template/workflows/specdev/common/tools/validate-specdev.mjs +218 -5
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版,也不按固定章节数量衡量质量。
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
协作拓扑与工作区拓扑是两个正交决定。`coordination_mode: single-session` 是默认值:主会话拥有全部项目与状态写入,只读探索可以使用辅助 Agent;只有用户明确选择时才进入 `lead-team` 并建立 Lead/Worker 交付合同。`workspace_strategy` 则根据 change/Ticket 的实际隔离需求独立确定,Agent Team 本身既不要求也不禁止 worktree。
|
|
19
19
|
|
|
20
20
|
产物写入 `specdev/changes/{change}/goal-plan.md`。
|
|
21
21
|
|
|
@@ -54,17 +54,18 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
|
|
|
54
54
|
|
|
55
55
|
## 流程
|
|
56
56
|
|
|
57
|
-
### 1.
|
|
57
|
+
### 1. 验证上游并锁定执行拓扑
|
|
58
58
|
|
|
59
59
|
加载 下方 `<planning-modes>` 标签:
|
|
60
60
|
|
|
61
61
|
1. 验证 Spec Ready、Ticket Ready、合同覆盖、DAG、路径所有权和 Deep Ticket 完整性;
|
|
62
62
|
2. 只读探索会影响调度的代码事实和项目约束;
|
|
63
63
|
3. 识别 coordination、migration、high-assurance、reference-conformance 等可组合规划模式;
|
|
64
|
-
4.
|
|
65
|
-
5.
|
|
66
|
-
6.
|
|
67
|
-
7.
|
|
64
|
+
4. 未获得用户对 Lead Team 的明确选择时固定 `coordination_mode: single-session`;只读探索 Agent 不改变该值;
|
|
65
|
+
5. 用户明确选择 Lead Team 时固定 `coordination_mode: lead-team`,再选择 `native-subagent` 或 `external-web-subagent`;
|
|
66
|
+
6. 按每个 Ticket 的可观察事实选择 current 或 worktree,并汇总为 `workspace_strategy: current | worktree | mixed`;
|
|
67
|
+
7. 只对无法发现且会改变 Gate、Wave、owner、迁移、批准点或隔离策略的问题继续提问;
|
|
68
|
+
8. 不熟悉的外部标准或依赖使用 下方 `<research>` 标签。
|
|
68
69
|
|
|
69
70
|
任何硬停止问题都必须退回拥有该决策的上游工件,不得用 Goal Plan 覆盖。
|
|
70
71
|
|
|
@@ -77,21 +78,28 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
|
|
|
77
78
|
3. 为 shared path、共享合同和集中变更指定唯一 owner;
|
|
78
79
|
4. 为行为闭环、合同稳定、迁移完成、发布就绪等关键状态定义 Gate;
|
|
79
80
|
5. 明确 expand → migrate → contract、Evidence 返回和集成规则;
|
|
80
|
-
6. 定义每个 Ticket
|
|
81
|
+
6. 定义每个 Ticket 的开始条件、执行顺序、workspace 分配、验证、Evidence 目标和失败恢复,不复制 Ticket 全文;
|
|
82
|
+
7. 只有存在允许的隔离触发条件时才规划 worktree,并固定 workspace owner、integration owner、父分支和结束动作。
|
|
81
83
|
|
|
82
84
|
**完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个计划 Ticket 都有唯一 owner、可验证开始条件、Evidence 目标和恢复路径。
|
|
83
85
|
|
|
84
|
-
### 3.
|
|
86
|
+
### 3. 按两个维度加载条件分支
|
|
85
87
|
|
|
86
|
-
|
|
88
|
+
当 `workspace_strategy` 为 `worktree` 或 `mixed` 时:
|
|
89
|
+
|
|
90
|
+
1. 加载 下方 `<workspace-execution-template>` 标签;
|
|
91
|
+
2. 为每个隔离 Ticket 记录合法触发事实、固定基线、父分支、implementation owner、integration owner、可迁移 locator 和 `integrate | retain`;
|
|
92
|
+
3. 按需以规划输入调用 下方 `<dev-worktree>` 标签,不在规划阶段创建工作区。
|
|
93
|
+
|
|
94
|
+
只有 `coordination_mode: lead-team` 时:
|
|
87
95
|
|
|
88
96
|
1. 加载 下方 `<delegated-execution>` 标签;
|
|
89
97
|
2. 以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签;
|
|
90
98
|
3. 固定唯一 Lead、native/external provider、不可变 checkpoint、可恢复 locator、逐动作授权和修正上限;
|
|
91
99
|
4. 生成里程碑 Delivery Contract 与每个 Ticket 的独立 Dispatch Packet;
|
|
92
|
-
5.
|
|
100
|
+
5. 为每个派单标记 `lead-write | worker-write | read-only`;`worker-write` 必须引用隔离 workspace 分配。
|
|
93
101
|
|
|
94
|
-
|
|
102
|
+
`single-session` 跳过委派能力,但仍可加载独立 workspace 附录;`lead-team` 在没有隔离触发条件时也不得制造 worktree。
|
|
95
103
|
|
|
96
104
|
### 4. 定义整体完成、证据与恢复
|
|
97
105
|
|
|
@@ -119,12 +127,12 @@ Spec 或 Tickets Map 不存在时,返回 “编写 Spec 阶段” 或 “拆
|
|
|
119
127
|
5. Constraints, Risk and Recovery;
|
|
120
128
|
6. Progress and Decisions。
|
|
121
129
|
|
|
122
|
-
|
|
130
|
+
当 workspace strategy 需要隔离时加入 下方 `<workspace-execution-template>` 标签;当 coordination mode 为 Lead Team 时加入 下方 `<delegated-execution-template>` 标签。两个附录互不蕴含,可单独或同时出现。Ticket 较多时在 Execution Graph 内增加速查表,不创建独立的第二套状态来源。
|
|
123
131
|
|
|
124
132
|
### 6. 同步与验证
|
|
125
133
|
|
|
126
134
|
1. 将 Wave、Gate 和 owner 投影同步到 `specdev/changes/{change}/tickets-map.md`;
|
|
127
|
-
2. 对照 下方 `<goal-plan-schema>`
|
|
135
|
+
2. 对照 下方 `<goal-plan-schema>` 标签,确认 coordination 与 workspace 两个字段成对存在且组合有效;
|
|
128
136
|
3. 运行:
|
|
129
137
|
|
|
130
138
|
```bash
|
|
@@ -134,8 +142,8 @@ node Speculo Node 校验器 \
|
|
|
134
142
|
```
|
|
135
143
|
|
|
136
144
|
4. 更新 `specdev/status.json` 与 `specdev/changes/{change}/.status.json`;
|
|
137
|
-
5. 原子写入 Goal Plan 和同步投影后重新读取,确认核心 DAG/Wave/Gate/owner
|
|
138
|
-
6.
|
|
145
|
+
5. 原子写入 Goal Plan 和同步投影后重新读取,确认核心 DAG/Wave/Gate/owner、两个执行维度和授权一致;存在 workspace 附录时核对触发条件与集成字段,存在委派附录时核对 Lead、checkpoint、locator、Delivery Contract 与 Dispatch Packet;
|
|
146
|
+
6. 向用户汇报规划模式、协作方式、workspace 分配、关键路径、Wave、Gate、shared owner、迁移策略、主要风险和 Ready 状态;Lead Team 再汇报交付通道与 Lead;
|
|
139
147
|
7. 未经用户要求,不自动进入实现。
|
|
140
148
|
|
|
141
149
|
## 决策完备标准
|
|
@@ -148,7 +156,7 @@ node Speculo Node 校验器 \
|
|
|
148
156
|
- 迁移、兼容、收缩、发布和回滚顺序;
|
|
149
157
|
- Evidence 返回、集成、偏差、暂停和批准路径。
|
|
150
158
|
|
|
151
|
-
|
|
159
|
+
每份新 Goal Plan 必须锁定 coordination mode 与 workspace strategy。Lead Team 还必须锁定 Agent 派单上下文、execution model、Lead、checkpoint、locator、修正上限和逐动作授权;single-session 不包含这些角色内容。Worktree/mixed 还必须锁定逐 Ticket 隔离触发、父分支、integration owner 与结束动作;current 不包含隔离占位。
|
|
152
160
|
|
|
153
161
|
Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局部验收 checklist 或 Spec 的完整用户故事。
|
|
154
162
|
|
|
@@ -157,8 +165,8 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
157
165
|
- `specdev/changes/{change}/goal-plan.md` 已写入且只包含适用内容;
|
|
158
166
|
- 所有计划内 Ticket Ready,DAG 无环,合同覆盖明确;
|
|
159
167
|
- Wave、Gate、owner、集成、偏差和恢复可执行;
|
|
160
|
-
-
|
|
161
|
-
-
|
|
168
|
+
- `single-session` 没有委派角色、交付合同或空占位,`lead-team` 的 Delivery Contract 与每个 Dispatch Packet 完整可恢复;
|
|
169
|
+
- current strategy 没有 worktree、Ticket branch 或逐 Ticket merge 安排;worktree/mixed 的每条分配都有实际触发事实和可恢复集成合同;
|
|
162
170
|
- Tickets Map 投影已同步;
|
|
163
171
|
- 无未批准高影响假设或硬停止问题;
|
|
164
172
|
- 结构校验无 error;纯网页环境的人工核对结果已记录;
|
|
@@ -171,6 +179,7 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
171
179
|
- 委派执行协议:下方 `<delegated-execution>` 标签,仅用户选择委派时加载
|
|
172
180
|
- 完成、证据、偏差与恢复:下方 `<completion-control>` 标签
|
|
173
181
|
- Goal Plan 核心模板:下方 `<goal-plan-template>` 标签
|
|
182
|
+
- 隔离 workspace 附录模板:下方 `<workspace-execution-template>` 标签,仅 worktree/mixed 时加载
|
|
174
183
|
- 委派附录模板:下方 `<delegated-execution-template>` 标签,仅用户选择委派时加载
|
|
175
184
|
- Agent 交付合同:下方 `<subagent-delivery>` 标签,仅用户选择委派时调用
|
|
176
185
|
|
|
@@ -214,6 +223,8 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
214
223
|
- 当前代码事实使 Ticket 的核心行为、接口或验证不可执行;
|
|
215
224
|
- 必需外部合同或参考权威不可获得;
|
|
216
225
|
- 已选择委派,但 Lead、checkpoint、可恢复 locator 或交付通道无法建立;
|
|
226
|
+
- workspace strategy 为 worktree/mixed,但任一隔离 Ticket 缺少允许的 trigger、父分支、integration owner、可恢复 locator 或结束动作;
|
|
227
|
+
- `lead-team + current` 中存在 `worker-write`,或 current workspace 出现多个项目/状态写入 owner;
|
|
217
228
|
- 用户要求的远程或生产动作没有逐动作授权。
|
|
218
229
|
|
|
219
230
|
按 下方 `<artifact-contract>` 标签 和 下方 `<deviation-control>` 标签 返回真正拥有该决策的工件。
|
|
@@ -228,16 +239,27 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
228
239
|
|
|
229
240
|
模式可以组合。仅有线性低风险 Ticket 时不应为了形式生成重型 Goal Plan。
|
|
230
241
|
|
|
231
|
-
## 4.
|
|
242
|
+
## 4. 锁定正交执行维度
|
|
243
|
+
|
|
244
|
+
规划模式描述为什么需要跨 Ticket 治理,不决定协作或工作区方式。每份新 Goal Plan 都必须分别记录:
|
|
245
|
+
|
|
246
|
+
- `coordination_mode: single-session | lead-team`;
|
|
247
|
+
- `workspace_strategy: current | worktree | mixed`。
|
|
232
248
|
|
|
233
|
-
|
|
249
|
+
`single-session` 是默认协作方式:主会话拥有全部项目和 SpecDev 状态写入,只读探索、日志分析、测试观察和审查 Agent 可以返回结论,但不得成为第二写入者。只有用户明确要求或确认严格角色分派时才能使用 `lead-team`;不得根据 Ticket 数量、并行机会或平台能力静默启用。
|
|
234
250
|
|
|
235
|
-
-
|
|
236
|
-
- **委派 Goal Plan**:启用唯一 Lead 与 `native-subagent` 或 `external-web-subagent`,并加载委派协议。
|
|
251
|
+
Workspace 按 Ticket 判断,允许触发只有:`parallel-write`、`protect-local-state`、`disposable-experiment`、`background-resume`、`provider-requirement`、`user-requested`。每个触发必须引用实测事实;Agent Team、Ticket 数量、只读并行、顺序写入或泛化的“更安全”都不是触发条件。全部 Ticket 使用当前工作区时为 `current`;全部项目写入位于隔离 workspace 时为 `worktree`;两者并存时为 `mixed`。
|
|
237
252
|
|
|
238
|
-
|
|
253
|
+
四种组合均合法,但约束不同:
|
|
239
254
|
|
|
240
|
-
|
|
255
|
+
| Coordination | Workspace | 写入约束 |
|
|
256
|
+
|---|---|---|
|
|
257
|
+
| single-session | current | 主会话唯一写入 |
|
|
258
|
+
| single-session | worktree/mixed | 主会话管理并集成隔离写入 |
|
|
259
|
+
| lead-team | current | Lead 唯一写入,Worker 只读 |
|
|
260
|
+
| lead-team | worktree/mixed | `worker-write` 每项绑定独立 workspace,Lead 默认承担 integration owner |
|
|
261
|
+
|
|
262
|
+
选择 Lead Team 后固定 Lead、provider、repository、不可变 `base_sha` 或等价基线、源码交付方式、`max_correction_rounds` 和逐动作授权。选择 worktree/mixed 后固定每项的 trigger、workspace owner、integration owner、父分支、locator、来源 checkpoint 策略和结束动作。认证秘密和机器绝对路径不得进入 Goal Plan。
|
|
241
263
|
|
|
242
264
|
## 5. 规划摘要
|
|
243
265
|
|
|
@@ -245,6 +267,8 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
245
267
|
|
|
246
268
|
```text
|
|
247
269
|
modes=<mode-list>
|
|
270
|
+
coordination_mode=single-session|lead-team
|
|
271
|
+
workspace_strategy=current|worktree|mixed
|
|
248
272
|
tickets=<count>
|
|
249
273
|
critical_path=<ticket-list>
|
|
250
274
|
parallel_capacity=<n>
|
|
@@ -255,9 +279,9 @@ hard_stops=<none-or-list>
|
|
|
255
279
|
adopted_assumptions=<low-impact-only>
|
|
256
280
|
```
|
|
257
281
|
|
|
258
|
-
|
|
282
|
+
Lead Team 额外形成 `execution_model`、`lead`、`provider`、`checkpoint`、`source_delivery`、`max_correction_rounds` 和 locator;worktree/mixed 额外形成逐 Ticket workspace allocation。两类字段分别只进入各自附录。
|
|
259
283
|
|
|
260
|
-
**完成标准**:规划 modes
|
|
284
|
+
**完成标准**:规划 modes、coordination mode 与 workspace strategy 互不代替;single-session 没有委派痕迹;current 没有隔离安排;所有条件分支的源码、交付、权限和恢复字段都有可验证值。
|
|
261
285
|
|
|
262
286
|
</planning-modes>
|
|
263
287
|
|
|
@@ -288,6 +312,8 @@ Wave 内 Ticket 必须同时满足:
|
|
|
288
312
|
|
|
289
313
|
最大并发从 `specdev/config.json` 读取。并发上限是资源约束,不是必须填满的目标;Wave 也不意味着必须使用多个 Agent。
|
|
290
314
|
|
|
315
|
+
Wave、Agent Team 和 worktree 是三个不同概念。Wave 只表达依赖上可并发;是否委派由 coordination mode 决定,是否隔离写入由 workspace strategy 决定。只读并行不需要 worktree;同一 current workspace 只能有一个项目与状态写入 owner。
|
|
316
|
+
|
|
291
317
|
## 3. Gate
|
|
292
318
|
|
|
293
319
|
Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条件。每个 Gate 必须写明业务或工程状态、开启条件、关闭证据、阻塞范围、owner/批准人和失败恢复。
|
|
@@ -318,7 +344,9 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
|
|
|
318
344
|
|
|
319
345
|
## 6. Ticket 执行、Evidence 与集成
|
|
320
346
|
|
|
321
|
-
每个计划 Ticket 必须写明开始条件、依赖 Evidence
|
|
347
|
+
每个计划 Ticket 必须写明开始条件、依赖 Evidence、项目路径合同、workspace 分配、适用 Gate、必跑验证、Evidence 目标和失败恢复。实际执行仍由 “实现阶段” 与 Ticket 拥有,不在 Goal Plan 复制局部施工步骤。
|
|
348
|
+
|
|
349
|
+
Current workspace Ticket 由该 workspace 的唯一写入 owner 顺序执行。隔离 Ticket 的创建、恢复和本地集成由 workspace addendum 与 dev-worktree Skill 管理;integration owner 是核心编排角色,不预设为 Lead。`single-session` 时通常映射为主会话,`lead-team` 时通常映射为 Lead。
|
|
322
350
|
|
|
323
351
|
每个实现者完成或阻塞时:
|
|
324
352
|
|
|
@@ -327,9 +355,9 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
|
|
|
327
355
|
3. 检查依赖、路径所有权、合同覆盖和适用 Gate;
|
|
328
356
|
4. 返回 Ticket 状态、Evidence 路径、代码引用、未验证项和恢复条件。
|
|
329
357
|
|
|
330
|
-
最后一个计划内 Implement 按 下方 `<completion-control>` 标签 汇总核心计划的 Gate 和 Evidence
|
|
358
|
+
最后一个计划内 Implement 按 下方 `<completion-control>` 标签 汇总核心计划的 Gate 和 Evidence。Lead Team 的候选交付验收由独立委派协议拥有;worktree 的 Git 集成由角色中立的 workspace 协议拥有。
|
|
331
359
|
|
|
332
|
-
**完成标准**:每个执行结果可追溯到代码状态和 Evidence
|
|
360
|
+
**完成标准**:每个执行结果可追溯到代码状态和 Evidence;single-session Goal Plan 可以在不建立角色交付合同的情况下完整恢复和完成。
|
|
333
361
|
|
|
334
362
|
</orchestration-protocol>
|
|
335
363
|
|
|
@@ -337,11 +365,11 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
|
|
|
337
365
|
|
|
338
366
|
# Goal Plan 委派执行协议
|
|
339
367
|
|
|
340
|
-
只有用户在本次 P-goal-plan
|
|
368
|
+
只有用户在本次 P-goal-plan 运行中明确选择 `coordination_mode: lead-team` 时加载。该分支启用唯一 Lead 与 native/external Worker,但不决定 workspace strategy;Agent Team 可以只做只读分工,也可以与独立 worktree 组合。
|
|
341
369
|
|
|
342
370
|
## 1. Lead 与 Delivery Contract
|
|
343
371
|
|
|
344
|
-
Lead 负责源码基线、DAG、Wave、shared owner、Gate、权限、Evidence
|
|
372
|
+
Lead 负责源码基线、DAG、Wave、shared owner、Gate、权限、Evidence 汇总和最终验收;已派发写入 Ticket 的实现由对应执行者负责,Lead 不制造双重 owner。只有 workspace addendum 将 Lead 指定为 integration owner 时,Lead 才拥有对应 Git 集成。
|
|
345
373
|
|
|
346
374
|
委派分支选择唯一 execution model:`native-subagent` 或 `external-web-subagent`。Lead 以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签 生成里程碑 Delivery Contract;Implement 阶段以 `operation=execute` 调用同一 Skill 做恢复和验收。
|
|
347
375
|
|
|
@@ -354,7 +382,13 @@ Delivery Contract 必须固定:
|
|
|
354
382
|
- local changes、commit、push、PR、merge、deploy、migration 和生产动作的逐项授权;
|
|
355
383
|
- 完成、阻塞、偏差、恢复和返回协议。
|
|
356
384
|
|
|
357
|
-
|
|
385
|
+
每个 Dispatch Packet 必须标记 mutation role:
|
|
386
|
+
|
|
387
|
+
- `read-only`:Worker 只返回调查、审查、测试观察或建议;可用于任何 workspace strategy;
|
|
388
|
+
- `lead-write`:Lead 是该 Ticket 唯一写入者,可在 current 或分配给自己的 worktree 执行;
|
|
389
|
+
- `worker-write`:Worker 拥有 Ticket 写入,必须引用 Isolated Workspace Addendum 中唯一的 branch、`workspace_ref` 和 integration owner,不得写入 current workspace。
|
|
390
|
+
|
|
391
|
+
多个 Worker 需要项目写入时,workspace 决策通常会因 `parallel-write` 触发 worktree,但触发来自写入事实而不是 Lead Team 身份。Worktree 生命周期继续由角色中立的 dev-worktree Skill 管理。
|
|
358
392
|
|
|
359
393
|
## 2. Dispatch Packet
|
|
360
394
|
|
|
@@ -365,7 +399,7 @@ Delivery Contract 必须固定:
|
|
|
365
399
|
3. 相关 Spec 合同、ADR/CONTEXT 条目、Wave、Gate 和不可协商约束;
|
|
366
400
|
4. 已完成依赖及其 Evidence;
|
|
367
401
|
5. 项目 writable/read-only/shared 路径与唯一 shared owner;
|
|
368
|
-
6.
|
|
402
|
+
6. mutation role、workspace allocation、`base_sha`、workspace/session locator 和 source package hash;
|
|
369
403
|
7. 必跑验证、基线、反向验证和明确不适用项;
|
|
370
404
|
8. 当前授权、偏差升级、修正上限、Evidence 路径和返回字段。
|
|
371
405
|
|
|
@@ -379,15 +413,15 @@ Lead 接收候选交付时:
|
|
|
379
413
|
|
|
380
414
|
1. 读取 Dispatch Packet、Ticket、Evidence、Goal Plan 和代码引用;
|
|
381
415
|
2. 检查 checkpoint、附件 hash、路径授权、依赖和敏感信息边界;
|
|
382
|
-
3.
|
|
416
|
+
3. 按 mutation role 和 workspace allocation 核对交付,在声明基线上复跑定向验证和受影响回归;
|
|
383
417
|
4. 仅当 UI 交互受影响时运行最小 E2E;
|
|
384
418
|
5. provider 声明、模拟结果和静态推断在独立证据前保持 `unverified`;
|
|
385
|
-
6.
|
|
419
|
+
6. 验证通过后接受候选交付;存在 `terminal_action=integrate` 的 workspace 时交给其 integration owner 自动本地集成,否则按 current workspace 或 retain 合同继续;
|
|
386
420
|
7. 同步 Ticket、Map、Evidence 和 Goal Plan,检查 Gate 是否可关闭。
|
|
387
421
|
|
|
388
422
|
同一验收项达到修正上限时标记 blocker,记录最后 checkpoint、错误、已通过行为、责任方和恢复条件。
|
|
389
423
|
|
|
390
|
-
**完成标准**:完整委派附录包含唯一 Lead、完整 Delivery Contract、每 Ticket Dispatch Packet
|
|
424
|
+
**完成标准**:完整委派附录包含唯一 Lead、完整 Delivery Contract、每 Ticket Dispatch Packet、mutation role 和候选交付验收协议;它不隐式创建 worktree,任何一部分缺失都不得视为 Ready。
|
|
391
425
|
|
|
392
426
|
</delegated-execution>
|
|
393
427
|
|
|
@@ -417,8 +451,8 @@ Goal Plan 用紧凑摘要表达业务目标、受众、所有 Ticket 完成后
|
|
|
417
451
|
|
|
418
452
|
最后一个 Gate 关闭后加载 下方 `<change-completion>` 标签:
|
|
419
453
|
|
|
420
|
-
-
|
|
421
|
-
-
|
|
454
|
+
- `coordination_mode: single-session` 时,由最后一个计划内 “实现阶段” 汇总并完成 change;
|
|
455
|
+
- `coordination_mode: lead-team` 时,由 Lead 在独立验收后完成 change;旧 Goal Plan 缺少该字段时,继续按完整 Delegated Execution Addendum 是否存在推导。
|
|
422
456
|
|
|
423
457
|
若 triage 的 `external_action` 为 `pending-close` 或 `close-failed`,下一 Work 为 “请求分诊阶段”,否则进入 Archive。远程动作不参与本地 Gate 判断。
|
|
424
458
|
|
|
@@ -448,7 +482,7 @@ BLOCKER id=<id> owner=<owner> needed=<decision-or-input> impact=<scope>
|
|
|
448
482
|
DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
|
|
449
483
|
```
|
|
450
484
|
|
|
451
|
-
|
|
485
|
+
Lead Team 的交付状态格式由委派协议提供,不加入 single-session Goal Plan。
|
|
452
486
|
|
|
453
487
|
**完成标准**:进度可由权威工件恢复;普通计划由最后一个 Implement 完成,委派计划由 Lead 完成;所有通过、阻塞和未验证声明均能定位到具体 Evidence 与代码事实。
|
|
454
488
|
|
|
@@ -466,6 +500,8 @@ artifact: goal-plan
|
|
|
466
500
|
change: <YYYY-MM-DD-topic>
|
|
467
501
|
status: draft
|
|
468
502
|
modes: [coordination]
|
|
503
|
+
coordination_mode: single-session
|
|
504
|
+
workspace_strategy: current
|
|
469
505
|
ready_for_execution: false
|
|
470
506
|
```
|
|
471
507
|
|
|
@@ -530,6 +566,13 @@ ready_for_execution: false
|
|
|
530
566
|
|
|
531
567
|
## 4. Execution and Integration Protocol
|
|
532
568
|
|
|
569
|
+
### Execution Topology
|
|
570
|
+
|
|
571
|
+
| 维度 | 决定 | 事实依据 |
|
|
572
|
+
|---|---|---|
|
|
573
|
+
| Coordination | single-session | 未启用严格角色分派;辅助调查只能返回只读结论 |
|
|
574
|
+
| Workspace | current | 没有并行写入或其他隔离触发条件 |
|
|
575
|
+
|
|
533
576
|
### Ticket Execution Order
|
|
534
577
|
|
|
535
578
|
| Ticket | 开始条件 | 执行 owner | 必跑验证 | Evidence | 集成条件 |
|
|
@@ -540,8 +583,8 @@ ready_for_execution: false
|
|
|
540
583
|
| 动作 | 状态 | 目标与条件 |
|
|
541
584
|
|---|---|---|
|
|
542
585
|
| Local changes | allowed / not-authorized | ... |
|
|
543
|
-
|
|
|
544
|
-
|
|
|
586
|
+
| Implementation commit | allowed / not-authorized | ... |
|
|
587
|
+
| Remote repository actions | allowed / not-authorized | ... |
|
|
545
588
|
| Deploy / Migration | allowed / not-authorized | ... |
|
|
546
589
|
| Production configuration / feature / real user data | allowed / not-authorized | ... |
|
|
547
590
|
|
|
@@ -589,6 +632,35 @@ ready_for_execution: false
|
|
|
589
632
|
|
|
590
633
|
</goal-plan-template>
|
|
591
634
|
|
|
635
|
+
<workspace-execution-template>
|
|
636
|
+
|
|
637
|
+
## Isolated Workspace Addendum
|
|
638
|
+
|
|
639
|
+
只在 `workspace_strategy: worktree` 或 `workspace_strategy: mixed` 时加入。它独立于 Agent Team:单会话和 Lead Team 都可加载本附录。
|
|
640
|
+
|
|
641
|
+
### Workspace Decision
|
|
642
|
+
|
|
643
|
+
| 字段 | 值 |
|
|
644
|
+
|---|---|
|
|
645
|
+
| Strategy | worktree / mixed |
|
|
646
|
+
| Trigger | parallel-write / protect-local-state / disposable-experiment / background-resume / provider-requirement / user-requested |
|
|
647
|
+
| Current-workspace writer | `<primary-session-or-lead>` |
|
|
648
|
+
| Integration serialization | 每次只允许一个 integration owner 修改目标父分支 |
|
|
649
|
+
|
|
650
|
+
### Per-Ticket Workspace Allocation
|
|
651
|
+
|
|
652
|
+
| Ticket | Trigger and evidence | Implementation owner | Integration owner | Provider | Base SHA | Parent branch | Branch / workspace ref | Terminal action |
|
|
653
|
+
|---|---|---|---|---|---|---|---|---|
|
|
654
|
+
| T-01 | `<allowed-trigger>: <observed-fact>` | `<owner>` | `<owner>` | git / native / external | `<immutable-sha>` | `<parent-branch>` | `<branch>` / `<portable-locator>` | integrate / retain |
|
|
655
|
+
|
|
656
|
+
### Local Integration Authorization
|
|
657
|
+
|
|
658
|
+
`terminal_action=integrate` 持久授权 integration owner 执行本 Ticket 的本地 fast-forward,或在分叉时完成 `git add`、`git merge --continue` 和一次集成专用 merge commit。普通实现提交、push、PR、远端 merge、部署、迁移以及删除 branch/worktree 不从该授权继承。
|
|
659
|
+
|
|
660
|
+
来源 checkpoint、路径审计和验证通过后才可从 `review` 进入 `integrating`。集成成功写入 result SHA 与 Evidence;失败时中止正在进行的 merge、保留来源 workspace,并记录 blocker 和恢复条件。
|
|
661
|
+
|
|
662
|
+
</workspace-execution-template>
|
|
663
|
+
|
|
592
664
|
<delegated-execution-template>
|
|
593
665
|
|
|
594
666
|
## Delegated Execution Addendum
|
|
@@ -599,11 +671,12 @@ ready_for_execution: false
|
|
|
599
671
|
|---|---|
|
|
600
672
|
| Execution model | native-subagent / external-web-subagent |
|
|
601
673
|
| Lead / Provider | `<owner>` / `<provider>` |
|
|
602
|
-
| Repository /
|
|
674
|
+
| Repository / Source baseline | `<repository-or-local>` / `<immutable-checkpoint>` |
|
|
603
675
|
| Checkpoint policy | immutable SHA / equivalent fixed baseline |
|
|
604
676
|
| Source delivery | repository-url / source-package / combination |
|
|
605
677
|
| Max concurrency / corrections | `<n>` / `3` |
|
|
606
678
|
| Review | standards + spec + Lead verification + conditional E2E |
|
|
679
|
+
| Mutation policy | read-only / lead-write / worker-write;worker-write 必须引用隔离 workspace |
|
|
607
680
|
|
|
608
681
|
### Per-Ticket Dispatch Packets
|
|
609
682
|
|
|
@@ -615,15 +688,16 @@ ready_for_execution: false
|
|
|
615
688
|
- **Authority / dependencies:** 相关合同、ADR/CONTEXT、已完成依赖 Evidence
|
|
616
689
|
- **Wave / Gate / hard constraints:**
|
|
617
690
|
- **Writable / read-only / shared owner:**
|
|
618
|
-
- **
|
|
691
|
+
- **Mutation role / workspace allocation:** read-only / lead-write / worker-write;current 或对应 isolated allocation
|
|
692
|
+
- **Baseline / workspace or session locator / package hash:**
|
|
619
693
|
- **Preflight receipt:** 在 `specdev/changes/{change}/evidence/T-01.md` 记录目标、顺序、最大风险和基线差异,不超过 10 行
|
|
620
694
|
- **Verification / baseline / reverse check:**
|
|
621
695
|
- **Authorization / deviation / correction limit:**
|
|
622
696
|
- **Return:** 状态、Evidence、locator、最终 checkpoint、commit/PR、未验证项、待 Lead E2E
|
|
623
697
|
|
|
624
|
-
### Candidate Delivery Return and Lead
|
|
698
|
+
### Candidate Delivery Return and Lead Acceptance
|
|
625
699
|
|
|
626
|
-
Worker 将 Ticket 推进到 `review` 并返回候选交付;Lead 负责独立验证、适用 E2E
|
|
700
|
+
Worker 将 Ticket 推进到 `review` 并返回候选交付;Lead 负责独立验证、适用 E2E、候选验收和 Gate 判断。Git 集成只在独立 workspace 合同指定 Lead 为 integration owner 时发生;达到修正上限时保留最后可信 checkpoint、失败命令、已通过行为和恢复条件。
|
|
627
701
|
|
|
628
702
|
</delegated-execution-template>
|
|
629
703
|
|
|
@@ -739,9 +813,9 @@ shared_paths: ["package.json"]
|
|
|
739
813
|
|
|
740
814
|
## 3. Worktree 与分支
|
|
741
815
|
|
|
742
|
-
|
|
816
|
+
Worktree 只在存在可观察隔离需求时使用:并行写入、保护当前本地状态、一次性实验、后台恢复、provider 要求或用户明确要求。只读调查和没有其他隔离事实的顺序写入默认共用当前工作区。Agent Team、Ticket 数量和泛化的“更安全”都不构成隔离理由。Worktree 防止工作区污染,路径所有权防止逻辑冲突,两者不能互相替代。
|
|
743
817
|
|
|
744
|
-
生命周期由调用方明确的 workspace owner 按 下方 `<dev-worktree>` 标签
|
|
818
|
+
生命周期由调用方明确的 workspace owner 与 integration owner 按 下方 `<dev-worktree>` 标签 管理。`single-session` 通常把两者映射为主会话;`lead-team` 可以把 integration owner 映射为 Lead,但角色选择不决定是否使用 worktree。同一 current workspace 只允许一个项目与 SpecDev 状态写入 owner;Worker 要写项目文件时必须拥有独立 workspace。编排规则位于 下方 `<orchestration-protocol>` 标签。
|
|
745
819
|
|
|
746
820
|
</path-ownership>
|
|
747
821
|
|
|
@@ -874,8 +948,9 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由
|
|
|
874
948
|
|
|
875
949
|
## 转换 Owner
|
|
876
950
|
|
|
877
|
-
- Goal Plan
|
|
878
|
-
- Goal Plan
|
|
951
|
+
- Goal Plan 为 `coordination_mode: lead-team`:Lead 在独立验收并关闭最后一个 Gate 后拥有完成转换。
|
|
952
|
+
- Goal Plan 为 `coordination_mode: single-session`,或无 Goal Plan 的 Ticket/Direct Spec 实现:最后一个计划内 Implement 在最后一项验收通过后拥有完成转换。
|
|
953
|
+
- 旧 Goal Plan 缺少 coordination 字段时,根据完整 `## Delegated Execution Addendum` 是否存在兼容推导,不要求 runtime schema 迁移。
|
|
879
954
|
- 非实现型终点:最后一个拥有最终验收工件的 Work 使用本规则完成转换。
|
|
880
955
|
|
|
881
956
|
Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`,然后重读验证。全局 `specdev/status.json` 继续只保存 active 索引,不复制完成详情。
|
|
@@ -954,28 +1029,28 @@ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`
|
|
|
954
1029
|
|
|
955
1030
|
## 适用范围
|
|
956
1031
|
|
|
957
|
-
-
|
|
958
|
-
-
|
|
959
|
-
- 调用方必须明确 workspace owner、implementation owner
|
|
960
|
-
-
|
|
1032
|
+
- 只用于具备 `parallel-write`、`protect-local-state`、`disposable-experiment`、`background-resume`、`provider-requirement` 或 `user-requested` 触发事实的 Ready Ticket/原型。
|
|
1033
|
+
- 只读调查、Agent Team 本身和没有其他隔离事实的顺序执行默认共用当前工作区。
|
|
1034
|
+
- 调用方必须明确 trigger、workspace owner、implementation owner、integration owner、固定基线、父分支、工作项 ID、持久化 owner 和允许的结束动作。
|
|
1035
|
+
- Coordination 与 workspace 正交:`single-session` 可以使用本 Skill;`lead-team` 不自动使用。Current workspace 下 Worker 只读;Worker 写入必须绑定本 Skill 创建的独立 workspace。
|
|
961
1036
|
- 平台原生 worktree 优先;不可用时使用 Git worktree。
|
|
962
1037
|
|
|
963
1038
|
## 生命周期
|
|
964
1039
|
|
|
965
1040
|
1. 创建或恢复时加载 下方 `<dev-worktree-create>` 标签。
|
|
966
|
-
2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref
|
|
967
|
-
3.
|
|
1041
|
+
2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref`、不可变 source checkpoint、commit 或 PR 引用和未验证项;Ticket worktree 从 `active` 更新为 `review`。
|
|
1042
|
+
3. `terminal_action=integrate` 时 integration owner 自动加载 下方 `<dev-worktree-finalize>` 标签;`retain` 保持 review。一次性原型只评估和清理,不合入生产分支。
|
|
968
1043
|
|
|
969
|
-
Ticket worktree 状态依次为 `planned → active → review → integrated → removed`;失败进入 `blocked`,记录写入 `specdev/changes/{change}/.status.json` 的 `worktrees
|
|
1044
|
+
Ticket worktree 状态依次为 `planned → active → review → integrating → integrated → removed`;失败进入 `blocked`,记录写入 `specdev/changes/{change}/.status.json` 的 `worktrees`。`integrating` 是带完整授权、来源和尝试证据的可恢复锁:同一父分支一次只允许一个 integration owner;fast-forward 与 merge-commit 都必须落到可复核的 `integrated/passed` 终态。原型的 branch、`workspace_ref` 和清理结果只写入 `specdev/changes/{change}/prototypes/{prototype-id}/record.md`,不伪造 Ticket worktree 记录。
|
|
970
1045
|
|
|
971
1046
|
## 边界
|
|
972
1047
|
|
|
973
|
-
-
|
|
1048
|
+
- 每个隔离 Ticket 使用独立 worktree 和分支;同一并行 Wave 固定相同 `base_sha`。每个原型使用独立 worktree 和分支。
|
|
974
1049
|
- 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
1050
|
- native/external provider 保留其可迁移 opaque locator;所有 provider 都不保存机器绝对路径、认证秘密或真实用户数据。
|
|
976
1051
|
- 项目根 `.gitignore` 的 `specdev-worktree/` 条目由 `speculo init` 单一维护;缺失时创建流程阻塞并提示重新运行 init。
|
|
977
|
-
- E2E
|
|
978
|
-
-
|
|
1052
|
+
- E2E 仅适用于用户界面交互受影响的变更,由 integration owner 在集成阶段运行。
|
|
1053
|
+
- `terminal_action=integrate` 授权本地 fast-forward,以及分叉集成所需的暂存、merge continue 和一次集成专用 merge commit;不授权普通实现提交、push、PR、远端 merge、部署、迁移或删除分支/worktree。
|
|
979
1054
|
|
|
980
1055
|
</dev-worktree>
|
|
981
1056
|
|
|
@@ -986,8 +1061,8 @@ Ticket worktree 状态依次为 `planned → active → review → integrated
|
|
|
986
1061
|
## 前置
|
|
987
1062
|
|
|
988
1063
|
- Ticket `ready: true` 且依赖完成,或原型问题与临时写入范围已锁定;项目写路径无冲突。
|
|
989
|
-
-
|
|
990
|
-
- 调用方已指定 workspace owner、implementation owner
|
|
1064
|
+
- 调用方已记录允许的 trigger 及其事实。`parallel-write` 还要求 `specdev/config.json` 中 `git.worktree_for_parallel: true`;一次性原型要求 P-prototype 已取得本次临时 worktree 授权。
|
|
1065
|
+
- 调用方已指定 workspace owner、implementation owner、integration owner、父分支、工作项 ID、持久化 owner、`integrate | retain`,并固定 `base_sha`;并行 Ticket 共用同一基线。
|
|
991
1066
|
|
|
992
1067
|
## 创建
|
|
993
1068
|
|
|
@@ -998,16 +1073,31 @@ Ticket worktree 状态依次为 `planned → active → review → integrated
|
|
|
998
1073
|
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
1074
|
6. 分支使用 `speculo/<change>/<work-item-id>`;现有分支未能匹配记录时停止。
|
|
1000
1075
|
7. 安装项目所需依赖,运行最小基线检查。E2E 不属于 implementation owner 的创建基线。
|
|
1001
|
-
8. Ticket 将记录写入 `worktrees
|
|
1076
|
+
8. Ticket 将记录写入 `worktrees`;`owner` 保持 implementation owner 的兼容含义:
|
|
1002
1077
|
|
|
1003
1078
|
```json
|
|
1004
1079
|
{
|
|
1005
1080
|
"ticket_id": "T-01",
|
|
1006
1081
|
"owner": "<implementation-owner>",
|
|
1082
|
+
"integration_owner": "<integration-owner>",
|
|
1007
1083
|
"provider": "git",
|
|
1008
1084
|
"base_sha": "<sha>",
|
|
1085
|
+
"parent_branch": "<parent-branch>",
|
|
1009
1086
|
"branch": "speculo/<change>/T-01",
|
|
1010
1087
|
"workspace_ref": "specdev-worktree/T-01",
|
|
1088
|
+
"terminal_action": "integrate",
|
|
1089
|
+
"source_checkpoint": null,
|
|
1090
|
+
"integration": {
|
|
1091
|
+
"status": "pending",
|
|
1092
|
+
"parent_before_sha": null,
|
|
1093
|
+
"source_sha": null,
|
|
1094
|
+
"result_sha": null,
|
|
1095
|
+
"method": null,
|
|
1096
|
+
"conflict_paths": [],
|
|
1097
|
+
"verification": "pending",
|
|
1098
|
+
"evidence": "specdev/changes/{change}/evidence/T-01.md",
|
|
1099
|
+
"attempts": 0
|
|
1100
|
+
},
|
|
1011
1101
|
"status": "active",
|
|
1012
1102
|
"updated_at": "<ISO-8601>"
|
|
1013
1103
|
}
|
|
@@ -1015,7 +1105,7 @@ Ticket worktree 状态依次为 `planned → active → review → integrated
|
|
|
1015
1105
|
|
|
1016
1106
|
native/external provider 将示例中的 provider 与 `workspace_ref` 换为对应可迁移 locator,不套用 Git 物理路径。原型不使用本 JSON 结构,只在 record 的 Run and Assets 中记录源码 branch/commit,并在 frontmatter 写入 `workspace_ref` 与清理状态。
|
|
1017
1107
|
|
|
1018
|
-
|
|
1108
|
+
`terminal_action=integrate` 不替代来源实现提交授权;进入 `review` 前必须把已获授权的最终 commit 写为 `source_checkpoint`。完成条件:工作区可定位、基线可用、调用方记录与实际 provider、分支和 checkpoint 一致;Git provider 的引用与工作项 ID 完全一致。失败时在调用方拥有的记录中设为 `blocked` 并保留现场。
|
|
1019
1109
|
|
|
1020
1110
|
</dev-worktree-create>
|
|
1021
1111
|
|
|
@@ -1027,10 +1117,17 @@ native/external provider 将示例中的 provider 与 `workspace_ref` 换为对
|
|
|
1027
1117
|
|
|
1028
1118
|
仅生产 Ticket 进入本段;一次性原型不得合入生产分支。
|
|
1029
1119
|
|
|
1030
|
-
1.
|
|
1031
|
-
2.
|
|
1032
|
-
3.
|
|
1033
|
-
4.
|
|
1120
|
+
1. integration owner 确认记录为 `review`、`terminal_action=integrate`,读取 implementation owner 的 Evidence,并验证实际修改未越过 writable/shared owner 合同。`source_checkpoint` 必须是不可变 commit,且与记录 branch 当前 tip 一致、从 `base_sha` 可达。
|
|
1121
|
+
2. 确认目标 checkout 正位于 `parent_branch`、index 与项目 working tree 干净,并把当前 HEAD 固定为 `parent_before_sha`。目标不干净、父分支不匹配、其他记录已在同一父分支 `integrating` 或 HEAD 在集成期间变化时停止,不覆盖用户工作。
|
|
1122
|
+
3. 将记录原子更新为 `integrating`,设置 `integration.status=running`、`parent_before_sha`、`source_sha` 并递增 `attempts`。中断恢复时先核对记录、Git `MERGE_HEAD` 和当前 HEAD,不重复开始第二次集成。
|
|
1123
|
+
4. 恢复已有 `integrating` 记录时只进入一个分支:HEAD 仍等于 `parent_before_sha` 且没有 `MERGE_HEAD` 时恢复同一次尝试;HEAD 已等于 `source_checkpoint`、没有 `MERGE_HEAD` 且 `parent_before_sha` 可达来源时,将其视为已完成但尚未落状态的 fast-forward;`MERGE_HEAD` 等于 `source_checkpoint` 时恢复未完成 merge。其他 HEAD、来源或 merge 状态漂移一律设为 `blocked`,不修改 Git 现场。
|
|
1124
|
+
5. 若 `parent_before_sha` 是 `source_checkpoint` 的祖先,先在来源 workspace 运行 Ticket 定向验证、受影响回归、项目 typecheck/lint/build 和适用最小 E2E,再从目标 checkout 执行 `git merge --ff-only <source_checkpoint>`。重读目标 HEAD、tree 和 Evidence,确认 HEAD 精确等于 `source_checkpoint` 后,记录 `method=fast-forward`、`result_sha=source_checkpoint`、空 `conflict_paths`、验证命令与结果、`verification=passed`、Evidence 和 `integration.status=passed`,再把 worktree 状态更新为 `integrated`。这是 fast-forward 的终态,不继续执行 merge-commit 步骤。
|
|
1125
|
+
6. 若双方已分叉,从干净目标 checkout 执行 `git merge --no-ff --no-commit <source_checkpoint>`。出现冲突时加载 下方 `<merge-conflict-protocol>` 标签,并将本记录作为持久授权来源;不为 `git add`、继续 merge 或集成提交重复请求确认。
|
|
1126
|
+
7. 在未提交的合并结果上运行 Ticket 定向验证、受影响回归、项目 typecheck/lint/build 和适用最小 E2E。可由既有意图机械修正的失败最多处理 3 轮;不得放宽断言、删除检查或引入未批准行为。
|
|
1127
|
+
8. 验证通过后完成一次集成专用 merge commit,重读 HEAD、parents、tree、diff 和 Evidence,确认父分支为第一 parent、`source_checkpoint` 为第二 parent,记录 `method=merge-commit`、`result_sha`、conflict paths、`verification=passed`、Evidence 与 `integration.status=passed`,再把 worktree 状态更新为 `integrated`。
|
|
1128
|
+
9. 冲突需要新产品/架构/安全/迁移决定、修改越过授权路径、验证无法通过、目标状态漂移或提交 hook 无法安全完成时,执行 `git merge --abort`(仅限本流程从干净目标开始的 merge),设置 worktree 与 integration 为 `blocked`,记录最小失败、已通过行为和恢复条件,并保留来源 worktree。
|
|
1129
|
+
|
|
1130
|
+
Fast-forward 路径的 `result_sha` 等于 `source_checkpoint`;merge-commit 路径必须保持父分支为第一 parent、来源 checkpoint 为第二 parent。任何成功结果都必须能从记录和 Evidence 复核。
|
|
1034
1131
|
|
|
1035
1132
|
## 清理
|
|
1036
1133
|
|
|
@@ -1038,10 +1135,36 @@ native/external provider 将示例中的 provider 与 `workspace_ref` 换为对
|
|
|
1038
1135
|
2. Git provider 从 project root 解析 `specdev-worktree/<work-item-id>`,重验无路径逃逸且与 `git worktree list --porcelain` 的记录一致,再从主工作树移除;native/external 通过对应 provider 管理入口移除。
|
|
1039
1136
|
3. 确认 worktree 不再注册且工作项目录不存在后删除对应分支。Ticket 将状态更新为 `removed`;原型把 `cleanup_status` 更新为 `clean`。保留项目根 `specdev-worktree/` 统一目录及 `.gitignore` 条目。
|
|
1040
1137
|
|
|
1041
|
-
PR 或暂缓集成时保留 worktree
|
|
1138
|
+
PR、`terminal_action=retain` 或暂缓集成时保留 worktree。成功集成也不自动清理。清理失败时停止;仅在用户明确要求时使用强制删除。
|
|
1042
1139
|
|
|
1043
1140
|
</dev-worktree-finalize>
|
|
1044
1141
|
|
|
1142
|
+
<merge-conflict-protocol>
|
|
1143
|
+
|
|
1144
|
+
# Merge / Rebase Conflict Protocol
|
|
1145
|
+
|
|
1146
|
+
只在 `git status` 证明仓库正处于 merge 或 rebase 冲突时加载。普通集成设计冲突继续按 deviation/upstream owner 处理。
|
|
1147
|
+
|
|
1148
|
+
## 流程
|
|
1149
|
+
|
|
1150
|
+
1. 读取 Git 状态、操作类型、冲突文件、base/ours/theirs commit、当前 Ticket/Evidence,以及是否存在匹配的 `terminal_action=integrate` worktree 记录。
|
|
1151
|
+
2. 追溯双方意图:commit message、冻结的 source、Spec、Ticket、ADR、测试和调用者。二者缺失时不凭代码表面猜测产品行为。
|
|
1152
|
+
3. 逐 conflict hunk 写出双方意图、共同约束和建议结果。只合并既有意图;需要发明新行为或改变上层合同则停止并登记 deviation。
|
|
1153
|
+
4. 在获授权可写范围内解决文本,运行受影响测试、typecheck、lint 和项目要求的验证。能从既有权威唯一推导的冲突直接处理,不把“发生冲突”本身升级为人工确认。
|
|
1154
|
+
5. 若当前 merge 来自匹配记录的本地集成,`terminal_action=integrate` 已授权 `git add`、继续 merge 和一次集成专用 commit;验证通过后直接完成,不逐动作请求确认。其他 merge/rebase 仍分别取得 Git 副作用授权;没有授权时保存分析、剩余文件和精确恢复命令。
|
|
1155
|
+
6. 需要发明新产品行为、改变 Spec/ADR、安全/迁移决定、越过路径 owner 或无法保持双方既有意图时停止;由从干净目标开始的自动集成执行 `git merge --abort`,记录 blocker 并保留来源 worktree。普通冲突现场不擅自 abort。
|
|
1156
|
+
7. 重读 Git 状态、parents 和 diff,确认无 marker、无未声明路径、双方要求及测试仍成立。
|
|
1157
|
+
|
|
1158
|
+
## 完成标准
|
|
1159
|
+
|
|
1160
|
+
- 每个 hunk 的结果可追溯到双方意图;
|
|
1161
|
+
- 新产品决定没有藏在冲突解决中;
|
|
1162
|
+
- 项目验证有命令、退出码和关键输出;
|
|
1163
|
+
- Git 副作用来自逐动作授权,或来自可核对 worktree 记录中的持久本地集成授权;
|
|
1164
|
+
- 完成或暂停状态可以从 Evidence 和 Git 状态恢复。
|
|
1165
|
+
|
|
1166
|
+
</merge-conflict-protocol>
|
|
1167
|
+
|
|
1045
1168
|
<subagent-delivery>
|
|
1046
1169
|
|
|
1047
1170
|
# SpecDev Subagent Delivery
|
|
@@ -1052,11 +1175,12 @@ PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明
|
|
|
1052
1175
|
|
|
1053
1176
|
- `operation`:`plan` 或 `execute`;
|
|
1054
1177
|
- `execution_model`:`native-subagent` 或 `external-web-subagent`;
|
|
1178
|
+
- mutation role:`read-only`、`lead-write` 或 `worker-write`,以及独立确定的 workspace allocation;
|
|
1055
1179
|
- Lead、Ticket、Goal Plan、Spec、适用 ADR/CONTEXT、Wave/Gate 和依赖 Evidence;
|
|
1056
1180
|
- 项目写、只读和 shared 路径,验证矩阵与当前源码基线;
|
|
1057
1181
|
- provider、会话或 workspace locator、源码交付方式,以及用户当前明确授权。
|
|
1058
1182
|
|
|
1059
|
-
|
|
1183
|
+
`single-session` Goal Plan 和缺失 Goal Plan 的 Ticket 直接由 “实现阶段” 执行,不调用本 Skill;只读辅助 Agent 由对应 research/review 能力管理。Lead Team 输入缺失时返回调用方补齐,不猜测 checkpoint、权限或验收结果。
|
|
1060
1184
|
|
|
1061
1185
|
## 流程
|
|
1062
1186
|
|
|
@@ -1064,7 +1188,7 @@ PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明
|
|
|
1064
1188
|
|
|
1065
1189
|
一个交付链只有一个 Lead。Lead 保留需求解释、仓库保护、Wave/Gate、shared owner、权限控制、交付集成、独立验收和最终状态同步责任。
|
|
1066
1190
|
|
|
1067
|
-
将本次请求解析为逐动作授权:local changes、commit、push、PR、merge、deploy、migration、production configuration、production feature 和 real user data。未明确授权的动作记为 `not-authorized`;项目指令、历史授权和 Agent
|
|
1191
|
+
将本次请求解析为逐动作授权:local changes、implementation commit、local worktree integration、push、PR、remote merge、deploy、migration、production configuration、production feature 和 real user data。未明确授权的动作记为 `not-authorized`;项目指令、历史授权和 Agent 建议不扩大权限。`terminal_action=integrate` 只满足对应 Ticket 的 local worktree integration,不扩展其他动作。
|
|
1068
1192
|
|
|
1069
1193
|
**完成标准**:`operation` 和 `execution_model` 唯一;Lead、授权动作、目标和条件均可判定。
|
|
1070
1194
|
|
|
@@ -1085,7 +1209,7 @@ PR 或暂缓集成时保留 worktree。清理失败时停止;仅在用户明
|
|
|
1085
1209
|
|
|
1086
1210
|
### 4. 规划或执行交付合同
|
|
1087
1211
|
|
|
1088
|
-
`operation=plan` 时,向调用方返回:里程碑级 Delivery Contract,以及每个 Ticket 的独立 Dispatch Packet
|
|
1212
|
+
`operation=plan` 时,向调用方返回:里程碑级 Delivery Contract,以及每个 Ticket 的独立 Dispatch Packet。每个派单块必须包含目标、权威输入、边界优先级、路径合同、mutation role、workspace allocation、依赖证据、基线、验证与反向验证、授权、恢复 locator、最多修正轮次和返回字段。`worker-write` 没有独立 workspace 时拒绝规划;read-only 不得返回项目或状态写入。调用方将结果写入 `specdev/changes/{change}/goal-plan.md`,不复制完整历史对话或 Ticket 全文。
|
|
1089
1213
|
|
|
1090
1214
|
`operation=execute` 时,先核对派单块与当前 Goal Plan、Ticket、基线和权限;再接收原生 Worker 或外部 provider 的候选交付,检查范围与事实声明,由 Lead 运行适用验证,并把结果写入 `specdev/changes/{change}/evidence/T-NN.md`。外部声明、截图或模拟结果在 Lead 复核前保持 `unverified`。
|
|
1091
1215
|
|
|
@@ -1119,7 +1243,7 @@ ticket_path=<full-ticket-path> evidence_path=<full-evidence-path>
|
|
|
1119
1243
|
|
|
1120
1244
|
派单块还必须给出项目 `writable_paths`、`read_only_paths`、`shared_paths`、完成的依赖 Evidence、合同 ID、验证矩阵、反向验证、权限和偏差升级方式。Agent 先核对基线与路径,再用不超过 10 行的开工回执记录目标、顺序和最大风险;回执写入 Ticket Evidence,不新增进度文件。
|
|
1121
1245
|
|
|
1122
|
-
|
|
1246
|
+
派单必须标记 mutation role。`read-only` Agent 只返回结论;`lead-write` 不把项目写入委派给 Agent;`worker-write` 必须引用已规划的独立 workspace,由其 integration owner 调用 下方 `<dev-worktree>` 标签 管理。多个并行写入 Ticket 固定同一 `base_sha`,分别使用独立分支和 `workspace_ref`;Agent 只修改获准项目路径,只把 Ticket 推进到 `review`。
|
|
1123
1247
|
|
|
1124
1248
|
## 审查与修正
|
|
1125
1249
|
|
|
@@ -1134,7 +1258,7 @@ ticket_path=<full-ticket-path> evidence_path=<full-evidence-path>
|
|
|
1134
1258
|
|
|
1135
1259
|
## 返回
|
|
1136
1260
|
|
|
1137
|
-
Agent 返回 Ticket 状态、`specdev/changes/{change}/evidence/T-NN.md`、`workspace_ref`、checkpoint、commit/PR 引用和待 Lead E2E。Lead
|
|
1261
|
+
Agent 返回 Ticket 状态、`specdev/changes/{change}/evidence/T-NN.md`、`workspace_ref`、checkpoint、commit/PR 引用和待 Lead E2E。Lead 负责候选验收、回归、Gate 判断和状态同步;只有 workspace allocation 指定时才承担 integration owner。逻辑冲突返回契约 owner,不机械选择某一侧版本。
|
|
1138
1262
|
|
|
1139
1263
|
**完成标准**:派单、工作区、路径修改、审查、修正和返回均可由 Goal Plan、Evidence 与 change 状态恢复。
|
|
1140
1264
|
|
|
@@ -1162,7 +1286,7 @@ Agent 返回 Ticket 状态、`specdev/changes/{change}/evidence/T-NN.md`、`work
|
|
|
1162
1286
|
2. 用户结果、里程碑位置、相关模块、公共契约和领域不变量;
|
|
1163
1287
|
3. allowed/read-only/shared 路径、保留行为和依赖策略;
|
|
1164
1288
|
4. 需要返回的方案、修改清单、patch/源码、测试、实际命令和风险;
|
|
1165
|
-
5.
|
|
1289
|
+
5. mutation role、workspace allocation、当前授权矩阵与逐项验收标准;
|
|
1166
1290
|
6. 未实际运行的检查必须标记 `unverified`。
|
|
1167
1291
|
|
|
1168
1292
|
公开仓库 URL 使用 `<Url>https://example.com/owner/repository</Url>` 形式并同时给出 branch 与 checkpoint。Provider 无法读取仓库、需要私有上下文或固定工作区快照时使用 source-package 分支。
|
|
@@ -1564,6 +1688,10 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1564
1688
|
"type": "string",
|
|
1565
1689
|
"minLength": 1
|
|
1566
1690
|
},
|
|
1691
|
+
"integration_owner": {
|
|
1692
|
+
"type": "string",
|
|
1693
|
+
"minLength": 1
|
|
1694
|
+
},
|
|
1567
1695
|
"provider": {
|
|
1568
1696
|
"enum": [
|
|
1569
1697
|
"native",
|
|
@@ -1575,6 +1703,10 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1575
1703
|
"type": "string",
|
|
1576
1704
|
"minLength": 1
|
|
1577
1705
|
},
|
|
1706
|
+
"parent_branch": {
|
|
1707
|
+
"type": "string",
|
|
1708
|
+
"minLength": 1
|
|
1709
|
+
},
|
|
1578
1710
|
"branch": {
|
|
1579
1711
|
"type": "string",
|
|
1580
1712
|
"minLength": 1
|
|
@@ -1584,11 +1716,76 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1584
1716
|
"minLength": 1,
|
|
1585
1717
|
"pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
|
|
1586
1718
|
},
|
|
1719
|
+
"terminal_action": {
|
|
1720
|
+
"enum": [
|
|
1721
|
+
"integrate",
|
|
1722
|
+
"retain"
|
|
1723
|
+
]
|
|
1724
|
+
},
|
|
1725
|
+
"source_checkpoint": {
|
|
1726
|
+
"type": [
|
|
1727
|
+
"string",
|
|
1728
|
+
"null"
|
|
1729
|
+
]
|
|
1730
|
+
},
|
|
1731
|
+
"integration": {
|
|
1732
|
+
"type": "object",
|
|
1733
|
+
"required": [
|
|
1734
|
+
"status",
|
|
1735
|
+
"parent_before_sha",
|
|
1736
|
+
"source_sha",
|
|
1737
|
+
"result_sha",
|
|
1738
|
+
"method",
|
|
1739
|
+
"conflict_paths",
|
|
1740
|
+
"verification",
|
|
1741
|
+
"evidence",
|
|
1742
|
+
"attempts"
|
|
1743
|
+
],
|
|
1744
|
+
"properties": {
|
|
1745
|
+
"status": {
|
|
1746
|
+
"enum": [
|
|
1747
|
+
"pending",
|
|
1748
|
+
"running",
|
|
1749
|
+
"passed",
|
|
1750
|
+
"blocked"
|
|
1751
|
+
]
|
|
1752
|
+
},
|
|
1753
|
+
"parent_before_sha": {
|
|
1754
|
+
"type": ["string", "null"]
|
|
1755
|
+
},
|
|
1756
|
+
"source_sha": {
|
|
1757
|
+
"type": ["string", "null"]
|
|
1758
|
+
},
|
|
1759
|
+
"result_sha": {
|
|
1760
|
+
"type": ["string", "null"]
|
|
1761
|
+
},
|
|
1762
|
+
"method": {
|
|
1763
|
+
"enum": [null, "fast-forward", "merge-commit"]
|
|
1764
|
+
},
|
|
1765
|
+
"conflict_paths": {
|
|
1766
|
+
"type": "array",
|
|
1767
|
+
"items": {"type": "string"}
|
|
1768
|
+
},
|
|
1769
|
+
"verification": {
|
|
1770
|
+
"enum": ["pending", "passed", "failed"]
|
|
1771
|
+
},
|
|
1772
|
+
"evidence": {
|
|
1773
|
+
"type": "string",
|
|
1774
|
+
"pattern": "^\\{roots\\.state\\}/specdev/changes/[^<]+/evidence/T-[0-9]{2,}\\.md$"
|
|
1775
|
+
},
|
|
1776
|
+
"attempts": {
|
|
1777
|
+
"type": "integer",
|
|
1778
|
+
"minimum": 0
|
|
1779
|
+
}
|
|
1780
|
+
},
|
|
1781
|
+
"additionalProperties": true
|
|
1782
|
+
},
|
|
1587
1783
|
"status": {
|
|
1588
1784
|
"enum": [
|
|
1589
1785
|
"planned",
|
|
1590
1786
|
"active",
|
|
1591
1787
|
"review",
|
|
1788
|
+
"integrating",
|
|
1592
1789
|
"integrated",
|
|
1593
1790
|
"removed",
|
|
1594
1791
|
"blocked"
|
|
@@ -1599,6 +1796,111 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1599
1796
|
"minLength": 1
|
|
1600
1797
|
}
|
|
1601
1798
|
},
|
|
1799
|
+
"dependentRequired": {
|
|
1800
|
+
"terminal_action": [
|
|
1801
|
+
"integration_owner",
|
|
1802
|
+
"parent_branch",
|
|
1803
|
+
"source_checkpoint",
|
|
1804
|
+
"integration"
|
|
1805
|
+
]
|
|
1806
|
+
},
|
|
1807
|
+
"allOf": [
|
|
1808
|
+
{
|
|
1809
|
+
"if": {
|
|
1810
|
+
"properties": {
|
|
1811
|
+
"status": {"const": "integrating"}
|
|
1812
|
+
},
|
|
1813
|
+
"required": ["status"]
|
|
1814
|
+
},
|
|
1815
|
+
"then": {
|
|
1816
|
+
"required": [
|
|
1817
|
+
"terminal_action",
|
|
1818
|
+
"integration_owner",
|
|
1819
|
+
"parent_branch",
|
|
1820
|
+
"source_checkpoint",
|
|
1821
|
+
"integration"
|
|
1822
|
+
],
|
|
1823
|
+
"properties": {
|
|
1824
|
+
"terminal_action": {"const": "integrate"}
|
|
1825
|
+
}
|
|
1826
|
+
}
|
|
1827
|
+
},
|
|
1828
|
+
{
|
|
1829
|
+
"if": {
|
|
1830
|
+
"properties": {
|
|
1831
|
+
"status": {"enum": ["integrating", "integrated"]},
|
|
1832
|
+
"terminal_action": {"const": "integrate"}
|
|
1833
|
+
},
|
|
1834
|
+
"required": ["status", "terminal_action"]
|
|
1835
|
+
},
|
|
1836
|
+
"then": {
|
|
1837
|
+
"properties": {
|
|
1838
|
+
"source_checkpoint": {"type": "string", "minLength": 1},
|
|
1839
|
+
"integration": {
|
|
1840
|
+
"properties": {
|
|
1841
|
+
"parent_before_sha": {"type": "string", "minLength": 1},
|
|
1842
|
+
"source_sha": {"type": "string", "minLength": 1},
|
|
1843
|
+
"attempts": {"type": "integer", "minimum": 1}
|
|
1844
|
+
}
|
|
1845
|
+
}
|
|
1846
|
+
}
|
|
1847
|
+
}
|
|
1848
|
+
},
|
|
1849
|
+
{
|
|
1850
|
+
"if": {
|
|
1851
|
+
"properties": {
|
|
1852
|
+
"status": {"const": "integrating"},
|
|
1853
|
+
"terminal_action": {"const": "integrate"}
|
|
1854
|
+
},
|
|
1855
|
+
"required": ["status", "terminal_action"]
|
|
1856
|
+
},
|
|
1857
|
+
"then": {
|
|
1858
|
+
"properties": {
|
|
1859
|
+
"integration": {
|
|
1860
|
+
"properties": {
|
|
1861
|
+
"status": {"const": "running"}
|
|
1862
|
+
}
|
|
1863
|
+
}
|
|
1864
|
+
}
|
|
1865
|
+
}
|
|
1866
|
+
},
|
|
1867
|
+
{
|
|
1868
|
+
"if": {
|
|
1869
|
+
"properties": {
|
|
1870
|
+
"status": {"const": "integrated"},
|
|
1871
|
+
"terminal_action": {"const": "integrate"}
|
|
1872
|
+
},
|
|
1873
|
+
"required": ["status", "terminal_action"]
|
|
1874
|
+
},
|
|
1875
|
+
"then": {
|
|
1876
|
+
"properties": {
|
|
1877
|
+
"integration": {
|
|
1878
|
+
"properties": {
|
|
1879
|
+
"status": {"const": "passed"},
|
|
1880
|
+
"result_sha": {"type": "string", "minLength": 1},
|
|
1881
|
+
"method": {"enum": ["fast-forward", "merge-commit"]},
|
|
1882
|
+
"verification": {"const": "passed"}
|
|
1883
|
+
}
|
|
1884
|
+
}
|
|
1885
|
+
}
|
|
1886
|
+
}
|
|
1887
|
+
},
|
|
1888
|
+
{
|
|
1889
|
+
"if": {
|
|
1890
|
+
"properties": {
|
|
1891
|
+
"terminal_action": {"const": "retain"}
|
|
1892
|
+
},
|
|
1893
|
+
"required": ["terminal_action"]
|
|
1894
|
+
},
|
|
1895
|
+
"then": {
|
|
1896
|
+
"properties": {
|
|
1897
|
+
"status": {
|
|
1898
|
+
"not": {"enum": ["integrating", "integrated"]}
|
|
1899
|
+
}
|
|
1900
|
+
}
|
|
1901
|
+
}
|
|
1902
|
+
}
|
|
1903
|
+
],
|
|
1602
1904
|
"additionalProperties": true
|
|
1603
1905
|
}
|
|
1604
1906
|
}
|
|
@@ -1694,8 +1996,18 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1694
1996
|
"minItems": 1,
|
|
1695
1997
|
"uniqueItems": true
|
|
1696
1998
|
},
|
|
1999
|
+
"coordination_mode": {
|
|
2000
|
+
"enum": ["single-session", "lead-team"]
|
|
2001
|
+
},
|
|
2002
|
+
"workspace_strategy": {
|
|
2003
|
+
"enum": ["current", "worktree", "mixed"]
|
|
2004
|
+
},
|
|
1697
2005
|
"ready_for_execution": {"type": "boolean"}
|
|
1698
2006
|
},
|
|
2007
|
+
"dependentRequired": {
|
|
2008
|
+
"coordination_mode": ["workspace_strategy"],
|
|
2009
|
+
"workspace_strategy": ["coordination_mode"]
|
|
2010
|
+
},
|
|
1699
2011
|
"additionalProperties": true
|
|
1700
2012
|
}
|
|
1701
2013
|
```
|