@namewta/speculo 0.7.1 → 0.7.3
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/dist/src/migrations.js +604 -23
- package/dist/src/migrations.js.map +1 -1
- package/package.json +1 -1
- package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md +171 -277
- package/template/canonical/canonical-specdev-goal-plan.md +714 -833
- package/template/canonical/canonical-specdev-grill-with-docs.md +172 -278
- package/template/canonical/canonical-specdev-spec.md +199 -315
- package/template/canonical/canonical-specdev-tickets.md +405 -398
- package/template/canonical/canonical-specdev-wayfinder.md +170 -276
- package/template/skills/migrate-runtime-state/SKILL.md +6 -6
- package/template/skills/migrate-runtime-state/references/migration-contract.md +9 -3
- package/template/skills/migrate-runtime-state/scripts/migrate-runtime-state.mjs +322 -33
- 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 +97 -142
- package/template/workflows/specdev/I-implement/evidence-template.md +60 -48
- package/template/workflows/specdev/I-implement/execution-preflight.md +29 -19
- package/template/workflows/specdev/I-implement/merge-conflict-protocol.md +12 -11
- package/template/workflows/specdev/I-init-setup/I-init-setup.md +4 -5
- package/template/workflows/specdev/I-init-setup/change-status-template.json +14 -1
- package/template/workflows/specdev/I-init-setup/config-template.json +3 -5
- package/template/workflows/specdev/I-init-setup/status-template.json +1 -1
- package/template/workflows/specdev/INDEX.md +12 -8
- package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +76 -93
- package/template/workflows/specdev/P-goal-plan/completion-control.md +26 -44
- package/template/workflows/specdev/P-goal-plan/goal-plan-template.md +43 -31
- package/template/workflows/specdev/P-goal-plan/lead-orchestration.md +34 -0
- package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md +31 -42
- package/template/workflows/specdev/P-goal-plan/planning-modes.md +42 -61
- package/template/workflows/specdev/T-tickets/T-tickets.md +6 -3
- package/template/workflows/specdev/T-tickets/ticket-readiness.md +5 -3
- package/template/workflows/specdev/T-tickets/ticket-template.md +8 -1
- package/template/workflows/specdev/T-tickets/tickets-map-template.md +5 -4
- package/template/workflows/specdev/_state/status.json +1 -1
- package/template/workflows/specdev/common/README.md +2 -2
- package/template/workflows/specdev/common/rules/change-completion.md +17 -19
- package/template/workflows/specdev/common/rules/deviation-control.md +1 -1
- package/template/workflows/specdev/common/rules/evidence-and-verification.md +27 -37
- package/template/workflows/specdev/common/rules/path-ownership.md +21 -23
- package/template/workflows/specdev/common/rules/readiness-and-depth.md +1 -1
- package/template/workflows/specdev/common/schemas/change-status.schema.json +136 -195
- package/template/workflows/specdev/common/schemas/config.schema.json +9 -11
- package/template/workflows/specdev/common/schemas/goal-plan.schema.json +24 -6
- package/template/workflows/specdev/common/schemas/status.schema.json +7 -63
- package/template/workflows/specdev/common/skills/dev-worktree/SKILL.md +42 -21
- package/template/workflows/specdev/common/skills/dev-worktree/references/create.md +48 -18
- package/template/workflows/specdev/common/skills/dev-worktree/references/finalize.md +47 -12
- package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +34 -30
- package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md +10 -23
- package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md +14 -25
- package/template/workflows/specdev/common/tools/validate-specdev.mjs +507 -117
- package/template/workflows/specdev/I-implement/delegated-evidence-template.md +0 -11
- package/template/workflows/specdev/P-goal-plan/delegated-execution-template.md +0 -33
- package/template/workflows/specdev/P-goal-plan/delegated-execution.md +0 -53
|
@@ -13,9 +13,9 @@
|
|
|
13
13
|
- 若本地项目提供 Speculo Node 校验器,可运行它补充结构校验;纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对,并明确记录未运行的自动校验。
|
|
14
14
|
- 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
|
|
15
15
|
|
|
16
|
-
Goal Plan
|
|
16
|
+
Goal Plan 只拥有单个 Ticket 无法独立决定的事情:整体 Outcome、跨 Ticket 顺序与并发、共享所有权、里程碑 Gate、动态派单边界、父分支集成、迁移/发布顺序、偏差升级和恢复。Ticket 继续拥有局部实现合同。
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
每次 Goal Plan 都采用 `lead-directed`:当前主会话是唯一 Lead,负责计划、SpecDev 状态、Evidence、派单、候选验收、父分支集成和最终回复。Lead 可以根据实际依赖与平台能力动态派遣 subagent,不需要用户预选协作模式。Agent 编排与 worktree 隔离是正交关系;每个进入 I-implement 的 Ticket 都必须拥有独立 worktree,无论由 Lead 还是 implementation subagent 实现。
|
|
19
19
|
|
|
20
20
|
产物写入 `specdev/changes/{change}/goal-plan.md`。
|
|
21
21
|
|
|
@@ -25,12 +25,12 @@ Lead/subagent 是可选的委派分支,不是 Goal Plan 的固有角色。每
|
|
|
25
25
|
|
|
26
26
|
- 多个 Ticket 可以或需要并行;
|
|
27
27
|
- 存在 shared path、共享合同或集中 owner;
|
|
28
|
-
- 存在 Deep Ticket、expand-contract
|
|
29
|
-
-
|
|
30
|
-
- Ticket DAG
|
|
28
|
+
- 存在 Deep Ticket、expand-contract、迁移、兼容窗口或不可逆步骤;
|
|
29
|
+
- 存在多个 Gate、外部审批、发布窗口或高事故半径;
|
|
30
|
+
- Ticket DAG 的关键路径、汇合点或恢复策略无法由 Tickets Map 安全表达;
|
|
31
31
|
- 用户明确要求正式跨 Ticket Plan。
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
少量、线性、低风险的 Ready Tickets 可以跳过本 work,由 I-implement 逐 Ticket 建立 worktree 并执行。没有 Ticket 的获批小型 Direct Spec 不受 Ticket worktree 合同约束;一旦需要切片,先运行 T-tickets。
|
|
34
34
|
|
|
35
35
|
## 输入
|
|
36
36
|
|
|
@@ -43,89 +43,78 @@ Lead/subagent 是可选的委派分支,不是 Goal Plan 的固有角色。每
|
|
|
43
43
|
|
|
44
44
|
按存在情况读取:
|
|
45
45
|
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
46
|
+
- 当前 change 架构决策:`specdev/changes/{change}/ADR.md`
|
|
47
|
+
- 当前 change 领域上下文:`specdev/changes/{change}/CONTEXT.md`
|
|
48
|
+
- 当前 change 设计日志:`specdev/changes/{change}/LOG.md`
|
|
49
|
+
- 当前 change 诊断:`specdev/changes/{change}/diagnosis.md`
|
|
50
|
+
- 永久架构决策:`specdev/adr/`
|
|
51
|
+
- 永久领域上下文:`specdev/context/`
|
|
52
|
+
- 用户提供的合同、标准、参考实现、环境限制、发布窗口和批准策略。
|
|
52
53
|
|
|
53
|
-
Spec 或 Tickets Map
|
|
54
|
+
永久目录可以为空,静默继续。缺少 Spec 或 Tickets Map 时返回 “编写 Spec 阶段” 或 “拆分 Tickets 阶段”;当前 ADR/CONTEXT 缺失且规划依赖对应决定时返回 “设计访谈能力”,不在 Goal Plan 中补造上游权威。
|
|
54
55
|
|
|
55
56
|
## 流程
|
|
56
57
|
|
|
57
|
-
### 1.
|
|
58
|
+
### 1. 验证上游与执行边界
|
|
58
59
|
|
|
59
60
|
加载 下方 `<planning-modes>` 标签:
|
|
60
61
|
|
|
61
|
-
1. 验证 Spec
|
|
62
|
-
2.
|
|
63
|
-
3. 识别
|
|
64
|
-
4.
|
|
65
|
-
5.
|
|
66
|
-
6.
|
|
67
|
-
7. 不熟悉的外部标准或依赖使用 下方 `<research>` 标签。
|
|
62
|
+
1. 验证 Spec、Tickets、合同覆盖、DAG、路径所有权和 Deep Ticket 完整性;
|
|
63
|
+
2. 只读探索影响调度的代码与项目事实;
|
|
64
|
+
3. 识别 migration、high-assurance、reference-conformance、release-coordination 等适用模式;
|
|
65
|
+
4. 从 config 读取 `max_implementation_agents`,将实际上限写入 `implementation_agent_limit`;本计划可以降低但不得超过 `3`,Lead 不计入;
|
|
66
|
+
5. 确认实现 commit 与本地候选集成已获授权;缺一项则计划保持 blocked;
|
|
67
|
+
6. 只询问无法发现且会改变 Gate、Wave、owner、迁移、批准或验收的问题。
|
|
68
68
|
|
|
69
|
-
|
|
69
|
+
**完成标准**:所有计划内 Ticket Ready;Lead、授权、实现并发上限和父分支可判定;没有用 Goal Plan 掩盖上游缺口。
|
|
70
70
|
|
|
71
|
-
### 2.
|
|
71
|
+
### 2. 构建 Outcome、DAG、Wave 与 Gate
|
|
72
72
|
|
|
73
73
|
加载 下方 `<orchestration-protocol>` 标签:
|
|
74
74
|
|
|
75
|
-
1.
|
|
76
|
-
2.
|
|
77
|
-
3. 为 shared path
|
|
78
|
-
4.
|
|
79
|
-
5.
|
|
80
|
-
6.
|
|
75
|
+
1. 压缩 Outcome、成功/伪完成、非目标和权威来源;
|
|
76
|
+
2. 从 Ticket frontmatter 构建 DAG、关键路径、扇出与汇合点;
|
|
77
|
+
3. 为 shared path、共享合同和集中修改指定唯一 owner;
|
|
78
|
+
4. 将依赖满足且项目写路径不相交的 Ticket 分入 Wave;
|
|
79
|
+
5. 为合同稳定、垂直路径、迁移完成、发布就绪等状态定义 Gate;
|
|
80
|
+
6. 为每个 Ticket 记录开始条件、worktree、验证层级、Evidence 目标、集成顺序和失败恢复。
|
|
81
81
|
|
|
82
|
-
**完成标准**:DAG、Wave、Gate 与 Tickets Map
|
|
82
|
+
**完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个 Ticket 有唯一项目写 owner、worktree 合同和可验证集成出口。
|
|
83
83
|
|
|
84
|
-
### 3.
|
|
84
|
+
### 3. 固定 Lead 编排与动态派单合同
|
|
85
85
|
|
|
86
|
-
|
|
86
|
+
加载 下方 `<lead-orchestration>` 标签,并以 `operation=plan` 调用 下方 `<subagent-delivery>` 标签:
|
|
87
87
|
|
|
88
|
-
1.
|
|
89
|
-
2.
|
|
90
|
-
3.
|
|
91
|
-
4.
|
|
92
|
-
5.
|
|
88
|
+
1. 固定 Lead 的可恢复 owner/session locator;
|
|
89
|
+
2. 声明 implementation subagent 最多同时三个,Lead 不计入;
|
|
90
|
+
3. 不为只读 review/research/test-observation agent 写 SpecDev 数字上限;
|
|
91
|
+
4. 固定只有 Lead 写 SpecDev 工件与状态;
|
|
92
|
+
5. 定义执行期动态 Dispatch Packet、候选返回和 Lead 验收;
|
|
93
|
+
6. provider、模型和具体派单在 Ticket 开始时按事实选择,不在 Goal Plan 中预分配。
|
|
93
94
|
|
|
94
|
-
|
|
95
|
+
**完成标准**:Lead 可以在恢复后重建派单边界;任何 subagent 都不能成为第二个 SpecDev 状态写入者或父分支 integration owner。
|
|
95
96
|
|
|
96
|
-
### 4.
|
|
97
|
+
### 4. 定义完成、证据与恢复
|
|
97
98
|
|
|
98
99
|
加载 下方 `<completion-control>` 标签:
|
|
99
100
|
|
|
100
|
-
1.
|
|
101
|
-
2.
|
|
102
|
-
3.
|
|
103
|
-
4.
|
|
104
|
-
5.
|
|
105
|
-
6.
|
|
101
|
+
1. 定义整体 Definition of Done 和每个 Gate 的关闭证据;
|
|
102
|
+
2. 固化不可协商约束与允许的局部实现自由;
|
|
103
|
+
3. 为每个 Ticket 明确 source-worktree 检查与 parent-candidate 检查;
|
|
104
|
+
4. E2E 按 Ticket 实际跨边界风险标记 required 或 not-required;
|
|
105
|
+
5. 定义候选失败、父 HEAD 漂移、偏差、暂停、批准和恢复动作;
|
|
106
|
+
6. 定义 change 完成、远程 reconcile、残余风险和回滚要求。
|
|
106
107
|
|
|
107
|
-
|
|
108
|
+
**完成标准**:每个完成声明映射到不可变 commit、候选/父分支 SHA、命令、Evidence 或人工批准。
|
|
108
109
|
|
|
109
|
-
### 5.
|
|
110
|
+
### 5. 写入、同步与验证
|
|
110
111
|
|
|
111
|
-
使用 下方 `<goal-plan-template>` 标签 写入
|
|
112
|
+
使用 下方 `<goal-plan-template>` 标签 写入 Goal Plan:
|
|
112
113
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
3. Gates and Completion Evidence;
|
|
118
|
-
4. Execution and Integration Protocol;
|
|
119
|
-
5. Constraints, Risk and Recovery;
|
|
120
|
-
6. Progress and Decisions。
|
|
121
|
-
|
|
122
|
-
用户选择委派时,在第 4 节加入 下方 `<delegated-execution-template>` 标签 的完整内容;没有选择时不加入任何委派痕迹。Ticket 较多时在 Execution Graph 内增加速查表,不创建独立的第二套状态来源。
|
|
123
|
-
|
|
124
|
-
### 6. 同步与验证
|
|
125
|
-
|
|
126
|
-
1. 将 Wave、Gate 和 owner 投影同步到 `specdev/changes/{change}/tickets-map.md`;
|
|
127
|
-
2. 对照 下方 `<goal-plan-schema>` 标签;schema 不记录角色分支;
|
|
128
|
-
3. 运行:
|
|
114
|
+
1. 只保留适用 planning modes,不创建条件性 topology addendum;
|
|
115
|
+
2. 将 Wave、Gate 和 owner 投影同步到 Tickets Map;
|
|
116
|
+
3. 对照 下方 `<goal-plan-schema>` 标签;
|
|
117
|
+
4. 运行:
|
|
129
118
|
|
|
130
119
|
```bash
|
|
131
120
|
node Speculo Node 校验器 \
|
|
@@ -133,46 +122,40 @@ node Speculo Node 校验器 \
|
|
|
133
122
|
specdev/changes/{change}
|
|
134
123
|
```
|
|
135
124
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
6. 向用户汇报规划模式、关键路径、Wave、Gate、shared owner、迁移策略、主要风险和 Ready 状态;选择委派时再汇报交付通道与 Lead;
|
|
125
|
+
5. 原子更新 Goal Plan、Tickets Map、全局/current change 状态并重新读取;
|
|
126
|
+
6. 向用户报告 Outcome、关键路径、Wave/Gate、Lead、实现 agent 上限、shared owner、E2E disposition、迁移与主要风险;
|
|
139
127
|
7. 未经用户要求,不自动进入实现。
|
|
140
128
|
|
|
141
129
|
## 决策完备标准
|
|
142
130
|
|
|
143
|
-
每份 Goal Plan
|
|
131
|
+
每份 Goal Plan 必须让 Lead 无需重新决定:
|
|
144
132
|
|
|
145
|
-
-
|
|
146
|
-
-
|
|
147
|
-
-
|
|
148
|
-
-
|
|
149
|
-
-
|
|
133
|
+
- Outcome、权威来源和整体完成;
|
|
134
|
+
- 跨 Ticket 先后、Wave、Gate 和关键汇合点;
|
|
135
|
+
- shared path 与共享合同 owner;
|
|
136
|
+
- implementation subagent 上限及动态派单边界;
|
|
137
|
+
- 每 Ticket worktree、source commit、候选验证和父分支推进规则;
|
|
138
|
+
- E2E disposition、偏差、暂停、批准和恢复路径。
|
|
150
139
|
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局部验收 checklist 或 Spec 的完整用户故事。
|
|
140
|
+
Goal Plan 不复制 Ticket 的局部施工路线、全部文件预测或逐项验收清单。
|
|
154
141
|
|
|
155
142
|
## 完成标准
|
|
156
143
|
|
|
157
|
-
- `
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
- Tickets Map
|
|
163
|
-
- 无未批准高影响假设或硬停止问题;
|
|
164
|
-
- 结构校验无 error;纯网页环境的人工核对结果已记录;
|
|
165
|
-
- 用户收到摘要和下一步选择。
|
|
144
|
+
- Goal Plan schema v4 且 `ready_for_execution` 与状态一致;
|
|
145
|
+
- Lead 唯一,最多三个 implementation subagent,review/research agent 不受 SpecDev 数字限制;
|
|
146
|
+
- 每个实现 Ticket 都有 worktree、commit、candidate-merge 和 Evidence 出口;
|
|
147
|
+
- source worktree 不承担 E2E,适用 E2E 只由 Lead 在 parent-candidate 状态运行;
|
|
148
|
+
- 计划只保留当前固定 Lead 与 candidate-merge 合同,不携带条件性编排附录;
|
|
149
|
+
- validator 无 error,Tickets Map 投影同步,用户收到下一步选择。
|
|
166
150
|
|
|
167
151
|
## 子文件引用
|
|
168
152
|
|
|
169
153
|
- 规划模式与输入门禁:下方 `<planning-modes>` 标签
|
|
170
|
-
- DAG、Wave、Gate
|
|
171
|
-
-
|
|
172
|
-
-
|
|
173
|
-
- Goal Plan
|
|
174
|
-
-
|
|
175
|
-
- Agent 交付合同:下方 `<subagent-delivery>` 标签,仅用户选择委派时调用
|
|
154
|
+
- DAG、Wave、Gate 与集成队列:下方 `<orchestration-protocol>` 标签
|
|
155
|
+
- Lead 与动态派单:下方 `<lead-orchestration>` 标签
|
|
156
|
+
- 完成、证据与恢复:下方 `<completion-control>` 标签
|
|
157
|
+
- Goal Plan 模板:下方 `<goal-plan-template>` 标签
|
|
158
|
+
- Agent 交付合同:下方 `<subagent-delivery>` 标签
|
|
176
159
|
|
|
177
160
|
---
|
|
178
161
|
|
|
@@ -184,80 +167,61 @@ Goal Plan 不应重复 Ticket 的局部执行路线、全部文件预测、局
|
|
|
184
167
|
|
|
185
168
|
# Goal Plan 规划模式与输入门禁
|
|
186
169
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
## 1. 必需输入门禁
|
|
190
|
-
|
|
191
|
-
- [ ] `specdev/changes/{change}/spec.md` 设置 `ready_for_tickets: true`,或存在用户明确批准的等价权威目标。
|
|
192
|
-
- [ ] `specdev/changes/{change}/tickets-map.md` 与全部 Ticket 一致。
|
|
193
|
-
- [ ] 所有计划执行的 Ticket 设置 `ready: true`。
|
|
194
|
-
- [ ] Ticket ID、具体 `specdev/changes/{change}/ticket/NN-<ticket-name>.md` 和 Map 行一致。
|
|
195
|
-
- [ ] `blocked_by` 引用存在,DAG 无环。
|
|
196
|
-
- [ ] Spec 验收合同全部 covered,或 deferred 项有批准、原因和后续归属。
|
|
197
|
-
- [ ] 可能并行的 Ticket 项目写路径不相交,或已有 shared owner 与排序方案。
|
|
198
|
-
- [ ] Deep Ticket 具备迁移、兼容、监控、回滚、收缩条件和批准点。
|
|
199
|
-
- [ ] Ticket 与 Spec、ADR、代码事实不存在未处理冲突。
|
|
200
|
-
- [ ] 项目声明的验证命令真实存在且能观察目标行为;不可运行项有替代证据或明确 blocker。
|
|
201
|
-
- [ ] 当前源码基线、工作区状态和外部合同版本已实测,而非使用浮动的“最新”描述。
|
|
170
|
+
规划模式描述 Goal Plan 需要额外解决的工程问题,不再表示 Agent 或 workspace topology。Lead-directed、每 Ticket worktree 和 candidate-merge 是所有新 Goal Plan 的固定合同。
|
|
202
171
|
|
|
203
|
-
##
|
|
172
|
+
## 1. 输入门禁
|
|
204
173
|
|
|
205
|
-
|
|
174
|
+
开始规划前穷尽检查:
|
|
206
175
|
|
|
207
|
-
-
|
|
208
|
-
- DAG
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
-
-
|
|
212
|
-
-
|
|
213
|
-
- Deep Ticket
|
|
214
|
-
-
|
|
215
|
-
-
|
|
216
|
-
-
|
|
217
|
-
-
|
|
176
|
+
- Spec `ready_for_tickets: true`,或上游工件已等价覆盖范围、合同与验收;
|
|
177
|
+
- Tickets Map 与全部 Ticket 存在、Ready、DAG 无环;
|
|
178
|
+
- 每个验收合同被 Ticket 覆盖;
|
|
179
|
+
- writable/shared path 有唯一 owner,Wave 候选无写冲突;
|
|
180
|
+
- config schema v4,`max_implementation_agents` 为 `1..3`;
|
|
181
|
+
- 父分支可定位,implementation commit 与本地 integration 已获授权;
|
|
182
|
+
- Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
|
|
183
|
+
- Ticket 与 `specdev/changes/{change}/spec.md`、`specdev/changes/{change}/ADR.md`、`specdev/adr/`、`specdev/context/` 和当前代码事实不存在未处理冲突;
|
|
184
|
+
- 项目声明的验证命令真实存在,并能观察目标行为;不可运行项有替代证据或明确 blocker;
|
|
185
|
+
- 当前源码基线、父分支、工作区状态和现有用户改动已经实测;
|
|
186
|
+
- 外部合同、标准、参考实现或依赖版本已经固定,不使用浮动的“最新”描述。
|
|
218
187
|
|
|
219
|
-
|
|
188
|
+
缺失上游事实返回其 owner;非 v4 Goal Plan 必须按当前合同重新规划,不能只修改版本号。
|
|
220
189
|
|
|
221
|
-
##
|
|
190
|
+
## 2. 可组合模式
|
|
222
191
|
|
|
223
|
-
-
|
|
224
|
-
-
|
|
225
|
-
-
|
|
226
|
-
-
|
|
227
|
-
- **release-coordination**:发布窗口、跨团队依赖、部署顺序或运营交接;重点是环境前置条件、Gate、观察期和回退。
|
|
192
|
+
- `migration`:存在 expand-contract、数据/协议迁移、兼容窗口或收缩条件;
|
|
193
|
+
- `high-assurance`:涉及安全、隐私、资金、数据完整性、法规、关键基础设施、不可逆操作或高事故半径;
|
|
194
|
+
- `reference-conformance`:必须逐项符合外部标准、协议、设计或参考实现;
|
|
195
|
+
- `release-coordination`:存在发布窗口、跨团队依赖、外部批准、阶段部署、观察期、运营交接或远程 reconcile。
|
|
228
196
|
|
|
229
|
-
|
|
197
|
+
没有适用模式时 `modes: []`。模式只增加对应 Gate、证据和恢复,不改变 Lead、worktree 或集成基本合同。
|
|
230
198
|
|
|
231
|
-
##
|
|
199
|
+
## 3. 固定执行拓扑
|
|
232
200
|
|
|
233
|
-
|
|
201
|
+
- `orchestration: lead-directed`;
|
|
202
|
+
- `ticket_workspace_policy: required`;
|
|
203
|
+
- `integration_gate: candidate-merge`;
|
|
204
|
+
- `implementation_agent_limit` 不大于 config,也不大于 `3`;
|
|
205
|
+
- Lead 不计入 implementation subagent 数量;
|
|
206
|
+
- review/research/test-observation agent 无 SpecDev 固定数字上限,但必须保持只读且不竞争同一可变环境;
|
|
207
|
+
- provider 与派单在执行期决定,不成为 Goal Plan 的静态枚举。
|
|
234
208
|
|
|
235
|
-
|
|
236
|
-
- **委派 Goal Plan**:启用唯一 Lead 与 `native-subagent` 或 `external-web-subagent`,并加载委派协议。
|
|
209
|
+
## 4. Ready 停止条件
|
|
237
210
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
选择委派后才固定:Lead、provider、repository/branch、不可变 `base_sha` 或等价基线、源码交付方式、`max_correction_rounds` 和逐动作授权。认证秘密和机器绝对路径不得进入 Goal Plan。
|
|
241
|
-
|
|
242
|
-
## 5. 规划摘要
|
|
243
|
-
|
|
244
|
-
写入前形成核心摘要:
|
|
245
|
-
|
|
246
|
-
```text
|
|
247
|
-
modes=<mode-list>
|
|
248
|
-
tickets=<count>
|
|
249
|
-
critical_path=<ticket-list>
|
|
250
|
-
parallel_capacity=<n>
|
|
251
|
-
shared_owners=<owner-map>
|
|
252
|
-
gates=<gate-list>
|
|
253
|
-
authorization=<action-summary>
|
|
254
|
-
hard_stops=<none-or-list>
|
|
255
|
-
adopted_assumptions=<low-impact-only>
|
|
256
|
-
```
|
|
211
|
+
存在以下任一情况时 `ready_for_execution: false`:
|
|
257
212
|
|
|
258
|
-
|
|
213
|
+
- Lead locator 无法恢复;
|
|
214
|
+
- 本地 commit 或 candidate integration 未授权;
|
|
215
|
+
- Ticket 无法建立独立 worktree 或父分支不明确;
|
|
216
|
+
- shared path 没有唯一 owner;
|
|
217
|
+
- E2E 是否需要会改变验收结论但尚未确定;
|
|
218
|
+
- 项目验证命令不能执行或无法观察目标行为,且没有批准的替代证据;
|
|
219
|
+
- 当前源码/工作区基线未实测,或外部合同版本仍然浮动;
|
|
220
|
+
- Ticket 与 Spec、ADR、`specdev/adr/`、`specdev/context/` 或代码事实存在未处理冲突;
|
|
221
|
+
- 迁移、发布、不可逆动作或恢复存在高影响未知项;
|
|
222
|
+
- 实现 agent 上限超过 `3`。
|
|
259
223
|
|
|
260
|
-
|
|
224
|
+
**完成标准**:所有固定字段、适用模式、授权、Lead、父分支和阻塞均可验证;没有替代编排模型或空占位。
|
|
261
225
|
|
|
262
226
|
</planning-modes>
|
|
263
227
|
|
|
@@ -265,192 +229,144 @@ adopted_assumptions=<low-impact-only>
|
|
|
265
229
|
|
|
266
230
|
# Goal Plan 核心编排协议
|
|
267
231
|
|
|
268
|
-
|
|
232
|
+
本文件定义 DAG、Wave、Gate、路径所有权、Ticket worktree、Evidence 返回和父分支集成队列。
|
|
269
233
|
|
|
270
234
|
## 1. DAG 与关键路径
|
|
271
235
|
|
|
272
|
-
- 依赖权威来自
|
|
273
|
-
- `specdev/changes/{change}/tickets-map.md` 是投影,不是第二套依赖真相;
|
|
236
|
+
- 依赖权威来自 Ticket frontmatter 的 `blocked_by`;Tickets Map 是投影;
|
|
274
237
|
- 计算根节点、扇出、汇合点、关键路径、共享合同 owner 和最终收缩点;
|
|
275
|
-
-
|
|
276
|
-
-
|
|
238
|
+
- 依赖只表示真实开始条件,不表达偏好、Agent 交接或“最好先做”;
|
|
239
|
+
- 无法独立保持可验证状态的迁移批次必须有明确 Gate 和恢复策略。
|
|
277
240
|
|
|
278
|
-
## 2. Wave
|
|
241
|
+
## 2. Wave 与实现并发
|
|
279
242
|
|
|
280
|
-
Wave 内 Ticket
|
|
243
|
+
Wave 内 Ticket 必须 Ready、依赖 Evidence 完整、项目写路径不相交、shared owner 已稳定、适用 Gate 已打开且基线一致。
|
|
281
244
|
|
|
282
|
-
-
|
|
283
|
-
- 所有依赖已完成并有 Evidence;
|
|
284
|
-
- 项目写路径不相交;
|
|
285
|
-
- shared path 已由 owner 稳定;
|
|
286
|
-
- 适用 Gate 已打开;
|
|
287
|
-
- 源码基线和外部合同版本一致。
|
|
288
|
-
|
|
289
|
-
最大并发从 `specdev/config.json` 读取。并发上限是资源约束,不是必须填满的目标;Wave 也不意味着必须使用多个 Agent。
|
|
245
|
+
Lead 根据当前事实决定自行实现或派单。同时活跃的 implementation subagent 不得超过 Goal Plan 与 config 中较小的上限,且绝不超过三个;Lead 不计入。Wave 是可并发性,不是必须填满的目标。只读 review/research/test-observation agent 不写固定数字上限,但不得写项目或 SpecDev 状态,也不得争用同一可变测试环境。
|
|
290
246
|
|
|
291
247
|
## 3. Gate
|
|
292
248
|
|
|
293
|
-
Gate
|
|
294
|
-
|
|
295
|
-
常见 Gate 包括共享合同稳定、首条垂直路径通过、迁移完成、旧调用点归零、发布就绪和观察期结束。名称按项目语义自定义。
|
|
249
|
+
Gate 用可验证状态定义,必须写明:工程/业务状态、开启条件、关闭证据、阻塞范围、Lead/批准人和失败恢复。常见 Gate 包括共享合同稳定、首条垂直路径、迁移完成、旧调用点归零、候选合并通过、发布就绪和观察期结束。
|
|
296
250
|
|
|
297
|
-
## 4. Shared path
|
|
251
|
+
## 4. Shared path 与合同
|
|
298
252
|
|
|
299
|
-
|
|
253
|
+
遵循 下方 `<path-ownership>` 标签:
|
|
300
254
|
|
|
301
|
-
1.
|
|
302
|
-
2.
|
|
303
|
-
3.
|
|
304
|
-
4.
|
|
305
|
-
5.
|
|
255
|
+
1. 专用 owner Ticket 修改共享路径;
|
|
256
|
+
2. 在其 worktree 形成 commit 与非 E2E 证据;
|
|
257
|
+
3. 通过 Lead candidate-merge 进入父分支;
|
|
258
|
+
4. 下游 Ticket 基于新的父分支 checkpoint 创建或刷新 worktree;
|
|
259
|
+
5. 共享合同变化时暂停消费者并修订上游,不让多个执行者竞争写入。
|
|
306
260
|
|
|
307
|
-
## 5.
|
|
261
|
+
## 5. 每 Ticket worktree
|
|
308
262
|
|
|
309
|
-
|
|
263
|
+
每个进入 I-implement 的 Ticket 建立唯一 `specdev-worktree/<ticket-id>`。记录 workspace/implementation/integration owner、`base_sha`、父分支、branch、portable locator、source checkpoint、candidate/result SHA 与验证状态。Lead 自行实现时仍进入该 worktree;subagent 身份不决定是否隔离。
|
|
310
264
|
|
|
311
|
-
|
|
312
|
-
2. **migrate**:按可独立验证的影响范围分批迁移;
|
|
313
|
-
3. **observe**:扫描旧调用点、旧数据或旧协议使用量;
|
|
314
|
-
4. **contract**:收缩条件有证据后删除旧形式;
|
|
315
|
-
5. **verify**:运行兼容、数据、回归、监控和回滚检查。
|
|
265
|
+
同一 Ticket 在 candidate 验证失败后保留来源 worktree并继续修正。新的 source commit 替换当前 `source_checkpoint`,旧 commit 继续由 Git/Evidence 可追溯。成功集成不自动清理 branch/worktree。
|
|
316
266
|
|
|
317
|
-
|
|
267
|
+
## 6. 父分支集成队列
|
|
318
268
|
|
|
319
|
-
|
|
269
|
+
Lead 串行集成 Ready 候选:
|
|
320
270
|
|
|
321
|
-
|
|
271
|
+
1. 冻结最新 `parent_before_sha`;
|
|
272
|
+
2. 在 Lead-owned parent integration checkout 组合父分支与 `source_checkpoint`;
|
|
273
|
+
3. 生成可定位的 `candidate_sha`;
|
|
274
|
+
4. 在 candidate 状态运行集成检查和适用 E2E;
|
|
275
|
+
5. 重读父 HEAD;若变化,将候选标记 `stale` 并重建;
|
|
276
|
+
6. 检查通过且父 HEAD 未变时,父分支 fast-forward 到 candidate;
|
|
277
|
+
7. 重读父 HEAD/tree,写入 `result_sha` 后才允许 Ticket Done。
|
|
322
278
|
|
|
323
|
-
|
|
279
|
+
父分支是 source checkpoint 的祖先时 candidate/result 可等于 source SHA,方法为 `fast-forward`;否则 candidate 必须是独立 merge commit。候选失败时父分支保持不变,Ticket 回到 `in_progress` 或 `blocked`。
|
|
324
280
|
|
|
325
|
-
|
|
326
|
-
2. 同步 Ticket、Tickets Map、Goal Plan 和 change 状态;
|
|
327
|
-
3. 检查依赖、路径所有权、合同覆盖和适用 Gate;
|
|
328
|
-
4. 返回 Ticket 状态、Evidence 路径、代码引用、未验证项和恢复条件。
|
|
281
|
+
## 7. Expand-contract
|
|
329
282
|
|
|
330
|
-
|
|
283
|
+
标准顺序为 expand → migrate → observe → contract → verify。每批迁移独立 commit、candidate 验证和父分支集成;收缩依据旧调用/数据/协议归零证据,不依据 Ticket 数量推断。
|
|
331
284
|
|
|
332
|
-
|
|
285
|
+
**完成标准**:每个 Ticket 从父基线、source commit、candidate 到 result 都可恢复;父分支只包含已通过候选门禁的 Ticket。
|
|
333
286
|
|
|
334
287
|
</orchestration-protocol>
|
|
335
288
|
|
|
336
|
-
<
|
|
337
|
-
|
|
338
|
-
# Goal Plan 委派执行协议
|
|
289
|
+
<lead-orchestration>
|
|
339
290
|
|
|
340
|
-
|
|
291
|
+
# Lead 编排与动态派单协议
|
|
341
292
|
|
|
342
|
-
## 1. Lead
|
|
293
|
+
## 1. 唯一 Lead
|
|
343
294
|
|
|
344
|
-
Lead
|
|
295
|
+
Lead 是主会话中的唯一编排 owner,保留需求解释、DAG/Wave/Gate、路径分配、权限、SpecDev 状态、Evidence、候选验收、父分支集成和最终回复责任。恢复时以 Goal Plan 的 `lead` locator 和权威工件继续;更换会话只转移 Lead 身份,不产生第二写入者。
|
|
345
296
|
|
|
346
|
-
|
|
297
|
+
## 2. 派单类型
|
|
347
298
|
|
|
348
|
-
|
|
299
|
+
- **implementation**:写入单个 Ticket worktree 的授权项目路径,运行非 E2E 检查并返回 source commit;
|
|
300
|
+
- **review**:只读审查固定 checkpoint,返回 findings;
|
|
301
|
+
- **research**:只读收集代码或外部事实,返回来源与结论;
|
|
302
|
+
- **test-observation**:只读运行或观察已授权检查,返回命令与结果,不拥有 E2E Gate。
|
|
349
303
|
|
|
350
|
-
|
|
351
|
-
- repository、branch、不可变 checkpoint 与源码交付方式;
|
|
352
|
-
- 最大并发和默认 3 轮的 `max_correction_rounds`;
|
|
353
|
-
- 标准轴、规范轴、Lead 独立验证和条件性 E2E;
|
|
354
|
-
- local changes、commit、push、PR、merge、deploy、migration 和生产动作的逐项授权;
|
|
355
|
-
- 完成、阻塞、偏差、恢复和返回协议。
|
|
304
|
+
Lead 在 Ticket 可以独立执行、写路径不冲突、上下文足够且平台支持时派单。派单是执行期决定,不写回 Goal Plan 作为固定拓扑。
|
|
356
305
|
|
|
357
|
-
|
|
306
|
+
## 3. 并发
|
|
358
307
|
|
|
359
|
-
|
|
308
|
+
implementation subagent 同时最多三个,实际值取 Goal Plan、config 与平台能力的最小值;Lead 不计入。review/research/test-observation agent 不设置 SpecDev 数字上限,但 Lead 必须避免测试资源冲突、重复工作和上下文失控。
|
|
360
309
|
|
|
361
|
-
|
|
310
|
+
## 4. 写入边界
|
|
362
311
|
|
|
363
|
-
|
|
364
|
-
2. “实现阶段” 与具体 Ticket;
|
|
365
|
-
3. 相关 Spec 合同、ADR/CONTEXT 条目、Wave、Gate 和不可协商约束;
|
|
366
|
-
4. 已完成依赖及其 Evidence;
|
|
367
|
-
5. 项目 writable/read-only/shared 路径与唯一 shared owner;
|
|
368
|
-
6. `base_sha`、branch、workspace/session locator 和 source package hash;
|
|
369
|
-
7. 必跑验证、基线、反向验证和明确不适用项;
|
|
370
|
-
8. 当前授权、偏差升级、修正上限、Evidence 路径和返回字段。
|
|
312
|
+
implementation subagent 只写分配 worktree 中的项目路径和其 Git commit,不写 Ticket、Map、Goal Plan、Evidence、change status 或父分支。其他 subagent 全部只读。Lead 接收返回后独立核对,再写所有 SpecDev 状态。
|
|
371
313
|
|
|
372
|
-
|
|
314
|
+
## 5. 动态 Dispatch Packet
|
|
373
315
|
|
|
374
|
-
|
|
316
|
+
每次派单必须绑定 Ticket、Goal Plan、依赖 Evidence、不可变 `base_sha`、branch/workspace locator、writable/read-only/shared paths、provider、允许动作、非 E2E 验证、停止条件和返回格式。provider 或模型按当次能力与授权选择;外部 provider 需要独立的数据发送授权。
|
|
375
317
|
|
|
376
|
-
|
|
318
|
+
implementation 返回至少包含:Ticket ID、workspace locator、最终 commit、dirty 状态、修改路径、检查命令/结果、未验证项、冲突与阻塞。review/research 返回固定输入、findings、来源和未验证声明。
|
|
377
319
|
|
|
378
|
-
Lead
|
|
320
|
+
## 6. Lead 验收
|
|
379
321
|
|
|
380
|
-
|
|
381
|
-
2. 检查 checkpoint、附件 hash、路径授权、依赖和敏感信息边界;
|
|
382
|
-
3. 在隔离基线上应用交付并复跑定向验证和受影响回归;
|
|
383
|
-
4. 仅当 UI 交互受影响时运行最小 E2E;
|
|
384
|
-
5. provider 声明、模拟结果和静态推断在独立证据前保持 `unverified`;
|
|
385
|
-
6. 验证通过后集成,并按 dev-worktree Skill 更新或清理 worktree;
|
|
386
|
-
7. 同步 Ticket、Map、Evidence 和 Goal Plan,检查 Gate 是否可关闭。
|
|
322
|
+
Lead 核对基线、路径、commit、dirty 状态、项目事实与非 E2E 结果;不接受 subagent 自报的 Evidence 或 E2E pass。implementation 候选进入 dev-worktree candidate-merge;read-only 结果由 Lead 复核后写入对应权威工件。失败返回同一 Ticket worktree 修正或标记 blocked。
|
|
387
323
|
|
|
388
|
-
|
|
324
|
+
**完成标准**:每次写入只有一个 Ticket/owner/worktree;所有 SpecDev 状态由 Lead 落盘;派单和返回可从 Evidence 恢复。
|
|
389
325
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
</delegated-execution>
|
|
326
|
+
</lead-orchestration>
|
|
393
327
|
|
|
394
328
|
<completion-control>
|
|
395
329
|
|
|
396
|
-
# Goal Plan
|
|
397
|
-
|
|
398
|
-
## 1. Outcome and Authority
|
|
399
|
-
|
|
400
|
-
Goal Plan 用紧凑摘要表达业务目标、受众、所有 Ticket 完成后的可观察终态、关键约束、非目标、权威来源、冲突规则和伪完成判据,不复制 Spec 的完整用户故事。
|
|
401
|
-
|
|
402
|
-
## 2. 整体 Definition of Done
|
|
403
|
-
|
|
404
|
-
整体完成至少覆盖:
|
|
405
|
-
|
|
406
|
-
- 所有计划内 Ticket 完成,cancelled 或 deferred 项有批准;
|
|
407
|
-
- 所有 Spec 验收合同和外部符合性要求有 Evidence;
|
|
408
|
-
- 项目类型检查、静态检查、测试、lint、构建、适用 CI 和受影响 E2E 完成,基线没有未经批准的退化;
|
|
409
|
-
- 可静默失效的关键门禁完成受控反向验证并恢复绿色;
|
|
410
|
-
- 迁移、兼容、调用点清零、监控、回滚和不可逆批准完成;
|
|
411
|
-
- 无未批准偏差、未处置高风险残余问题或伪装成通过的 `unverified` 声明;
|
|
412
|
-
- Ticket、Map、Goal Plan、Evidence、代码事实和状态一致。
|
|
413
|
-
|
|
414
|
-
## 3. Gate 关闭与 change 完成
|
|
415
|
-
|
|
416
|
-
每个 Gate 关闭时汇总覆盖 Evidence,检查合同、共享接口、数据、兼容、迁移和调用点,运行里程碑验证和适用 E2E,执行必要反向验证,审查偏差/风险/恢复能力,获取适用人工批准,并同步 Goal Plan、Map 和状态。
|
|
330
|
+
# Goal Plan 完成、证据与恢复
|
|
417
331
|
|
|
418
|
-
|
|
332
|
+
## 1. 整体 Definition of Done
|
|
419
333
|
|
|
420
|
-
|
|
421
|
-
- Goal Plan 含完整委派附录时,由 Lead 在独立验收后完成 change。
|
|
334
|
+
至少要求:
|
|
422
335
|
|
|
423
|
-
|
|
336
|
+
- Spec 验收合同全部有通过 Evidence 或明确批准的 deferred;
|
|
337
|
+
- 所有非 cancelled Ticket 都有 source commit、通过的 candidate 和父分支 result SHA;
|
|
338
|
+
- shared path、接口、数据、兼容、迁移、调用点与回滚合同闭合;
|
|
339
|
+
- 项目定向检查、受影响回归、类型检查、lint/build 和适用 E2E 无未经批准退化;
|
|
340
|
+
- change 状态、Ticket、Map、Goal Plan、Evidence 与实际 Git 状态一致;
|
|
341
|
+
- 没有未集成 source checkpoint、活动 integration candidate 或未决高影响偏差。
|
|
424
342
|
|
|
425
|
-
|
|
343
|
+
无需改动的 Ticket 必须转为 `cancelled` 并记录来源事实;不得用 Evidence-only Done 或 empty commit 关闭。
|
|
426
344
|
|
|
427
|
-
|
|
345
|
+
## 2. 两层验证
|
|
428
346
|
|
|
429
|
-
|
|
347
|
+
- `source-worktree`:implementation owner 运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查;
|
|
348
|
+
- `parent-candidate`:Lead 运行受影响集成/回归和 Ticket 标记 required 的 E2E。
|
|
430
349
|
|
|
431
|
-
|
|
350
|
+
Evidence 必须记录命令运行环境。任何在 source worktree 声称的 E2E pass 都无效;subagent 返回的测试结果在 Lead 核对前保持候选状态。
|
|
432
351
|
|
|
433
|
-
##
|
|
352
|
+
## 3. Gate 关闭
|
|
434
353
|
|
|
435
|
-
|
|
354
|
+
Lead 在每个 Gate 汇总覆盖 Evidence、接口/数据/兼容状态、candidate/result SHA、适用 E2E、反向验证、偏差、风险和批准。Gate 不以“完成若干 Ticket”作为唯一关闭条件。
|
|
436
355
|
|
|
437
|
-
|
|
356
|
+
## 4. 失败与恢复
|
|
438
357
|
|
|
439
|
-
|
|
358
|
+
- source 检查失败:保留 worktree,继续当前 Ticket;
|
|
359
|
+
- candidate 冲突或检查失败:父分支不动,integration 记 `failed`,Ticket 回到 `in_progress`/`blocked`;
|
|
360
|
+
- 父 HEAD 漂移:integration 记 `stale`,从最新父分支重建并重跑;
|
|
361
|
+
- E2E required 失败:父分支不动,保留失败命令、candidate SHA 和恢复条件;
|
|
362
|
+
- 命中当次 Dispatch Packet/候选协议的停止条件、继续修正已无合理收益或需要新产品决定:停止受影响 Wave,按 deviation control 返回契约 owner;
|
|
363
|
+
- Lead 会话变化:读取 Goal Plan、Ticket、change worktree 状态与最新 Evidence,从最后不可变 checkpoint 恢复。
|
|
440
364
|
|
|
441
|
-
|
|
365
|
+
## 5. Change 完成 owner
|
|
442
366
|
|
|
443
|
-
|
|
444
|
-
WAVE_STATUS wave=<n> ready=<ids> active=<ids> done=<ids> blocked=<ids>
|
|
445
|
-
GATE_STATUS gate=<name> state=open|closed evidence=<paths> risks=<summary>
|
|
446
|
-
TICKET_STATUS id=<id> state=<state> evidence=<path> deviation=<none|id>
|
|
447
|
-
BLOCKER id=<id> owner=<owner> needed=<decision-or-input> impact=<scope>
|
|
448
|
-
DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
|
|
449
|
-
```
|
|
367
|
+
Lead 是 Goal Plan change 的唯一完成 owner。没有 Goal Plan 的单 Ticket/Direct Spec 由当前 I-implement owner 按 change completion 规则完成。Archive 不补造完成证据。
|
|
450
368
|
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
**完成标准**:进度可由权威工件恢复;普通计划由最后一个 Implement 完成,委派计划由 Lead 完成;所有通过、阻塞和未验证声明均能定位到具体 Evidence 与代码事实。
|
|
369
|
+
**完成标准**:所有通过、阻塞、取消和未验证声明均定位到权威工件、命令与 Git checkpoint;失败不会推进父分支或 Done。
|
|
454
370
|
|
|
455
371
|
</completion-control>
|
|
456
372
|
|
|
@@ -461,11 +377,16 @@ DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
|
|
|
461
377
|
生成该工件时,将以下字段写在文档开头的 YAML frontmatter 中:
|
|
462
378
|
|
|
463
379
|
```yaml
|
|
464
|
-
schema_version:
|
|
380
|
+
schema_version: 5
|
|
465
381
|
artifact: goal-plan
|
|
466
382
|
change: <YYYY-MM-DD-topic>
|
|
467
383
|
status: draft
|
|
468
|
-
modes: [
|
|
384
|
+
modes: []
|
|
385
|
+
orchestration: lead-directed
|
|
386
|
+
lead: <owner-or-session-locator>
|
|
387
|
+
implementation_agent_limit: 3
|
|
388
|
+
ticket_workspace_policy: required
|
|
389
|
+
integration_gate: candidate-merge
|
|
469
390
|
ready_for_execution: false
|
|
470
391
|
```
|
|
471
392
|
|
|
@@ -490,10 +411,11 @@ ready_for_execution: false
|
|
|
490
411
|
| 优先级 | 来源 | 负责内容 | 冲突处理 |
|
|
491
412
|
|---|---|---|---|
|
|
492
413
|
| 1 | 用户最新明确决定 | 产品取舍与批准 | 更新真正拥有该决策的工件 |
|
|
493
|
-
| 2 | `specdev/changes/{change}/ADR.md` | 当前 change
|
|
494
|
-
| 3 | `specdev/changes/{change}/
|
|
495
|
-
| 4 | `specdev/changes/{change}/
|
|
496
|
-
| 5 |
|
|
414
|
+
| 2 | `specdev/changes/{change}/ADR.md` 与 `specdev/changes/{change}/CONTEXT.md` | 当前 change 架构决定与领域语义 | 返回 “设计访谈能力” 更新真正 owner |
|
|
415
|
+
| 3 | `specdev/adr/` 与 `specdev/context/` | 已毕业的永久决定与领域知识 | 当前 change 替代时在 `specdev/changes/{change}/ADR.md` 与 `specdev/changes/{change}/LOG.md` 明示 |
|
|
416
|
+
| 4 | `specdev/changes/{change}/spec.md` | 外部行为、范围与验收 | 下游不得改写 |
|
|
417
|
+
| 5 | `specdev/changes/{change}/ticket/` | 单 Ticket 契约 | Goal Plan 只编排 |
|
|
418
|
+
| 6 | `specdev/changes/{change}/diagnosis.md` 与当前代码/运行事实 | 已验证根因、现状与可行性 | 冲突时触发偏差并返回真正 owner |
|
|
497
419
|
|
|
498
420
|
## 2. Execution Graph
|
|
499
421
|
|
|
@@ -505,14 +427,14 @@ ready_for_execution: false
|
|
|
505
427
|
|
|
506
428
|
### Waves and Ownership
|
|
507
429
|
|
|
508
|
-
| Wave | Ticket | 前置条件 | 项目写路径 | Shared owner |
|
|
430
|
+
| Wave | Ticket | 前置条件 | 项目写路径 | Shared owner | Gate/集成序号 |
|
|
509
431
|
|---|---|---|---|---|---|
|
|
510
432
|
|
|
511
433
|
### Ticket Quick Reference
|
|
512
434
|
|
|
513
|
-
| ID |
|
|
514
|
-
|
|
515
|
-
| T-01 | `specdev/
|
|
435
|
+
| ID | 可观察产出 | Dependencies | Worktree | Implementation owner | E2E disposition | Evidence |
|
|
436
|
+
|---|---|---|---|---|---|---|
|
|
437
|
+
| T-01 | ... | — | `specdev-worktree/T-01` | Lead / dynamic dispatch | required / not-required: reason | `specdev/changes/{change}/evidence/T-01.md` |
|
|
516
438
|
|
|
517
439
|
## 3. Gates and Completion Evidence
|
|
518
440
|
|
|
@@ -520,7 +442,7 @@ ready_for_execution: false
|
|
|
520
442
|
|
|
521
443
|
### Gates
|
|
522
444
|
|
|
523
|
-
| Gate | 开启条件 | 关闭证据 | 阻塞范围 |
|
|
445
|
+
| Gate | 开启条件 | 关闭证据 | 阻塞范围 | Lead/批准人 | 失败恢复 |
|
|
524
446
|
|---|---|---|---|---|---|
|
|
525
447
|
|
|
526
448
|
### Contract and Reference Coverage
|
|
@@ -530,34 +452,44 @@ ready_for_execution: false
|
|
|
530
452
|
|
|
531
453
|
## 4. Execution and Integration Protocol
|
|
532
454
|
|
|
533
|
-
###
|
|
455
|
+
### Lead Orchestration
|
|
534
456
|
|
|
535
|
-
|
|
|
536
|
-
|
|
457
|
+
| 项目 | 决定 | 事实依据 |
|
|
458
|
+
|---|---|---|
|
|
459
|
+
| Lead | `<owner-or-session-locator>` | 唯一 SpecDev 状态、Evidence 与父分支 owner |
|
|
460
|
+
| Implementation subagents | `<= 3`,Lead 不计入 | config、依赖和平台能力的最小值 |
|
|
461
|
+
| Read-only agents | 无 SpecDev 数字上限 | review/research/test-observation,不写状态 |
|
|
462
|
+
| Dispatch | execution-time dynamic | provider/模型/派单按 Ticket 事实选择 |
|
|
463
|
+
|
|
464
|
+
### Ticket Workspace and Candidate Integration
|
|
465
|
+
|
|
466
|
+
| Ticket | Parent/base | Worktree/branch | Source checks | Source commit | Candidate checks/E2E | Parent result |
|
|
467
|
+
|---|---|---|---|---|---|---|
|
|
468
|
+
|
|
469
|
+
集成按表中顺序串行进行。source worktree 不运行 E2E;Lead 在最新父分支的 candidate 状态运行集成检查和适用 E2E,通过且父 HEAD 未漂移后才推进父分支。
|
|
537
470
|
|
|
538
471
|
### Authorization Matrix
|
|
539
472
|
|
|
540
473
|
| 动作 | 状态 | 目标与条件 |
|
|
541
474
|
|---|---|---|
|
|
542
|
-
|
|
|
543
|
-
|
|
|
544
|
-
|
|
|
545
|
-
|
|
|
546
|
-
|
|
|
475
|
+
| Ticket worktree local changes | allowed / not-authorized | 限 writable/shared owner 合同 |
|
|
476
|
+
| Implementation commit | allowed / not-authorized | 每 Ticket 必需;缺失则 Plan blocked |
|
|
477
|
+
| Local candidate integration and parent update | allowed / not-authorized | Lead-only;缺失则 Plan blocked |
|
|
478
|
+
| Push / PR / remote merge | allowed / not-authorized | 不从本计划本地授权继承 |
|
|
479
|
+
| Branch/worktree cleanup | allowed / not-authorized | 成功集成不自动继承 |
|
|
480
|
+
| Deploy / migration / production actions | allowed / not-authorized | 逐动作、目标和条件 |
|
|
547
481
|
|
|
548
|
-
### Evidence Return
|
|
482
|
+
### Evidence Return
|
|
549
483
|
|
|
550
|
-
|
|
484
|
+
subagent 只返回候选事实与 commit;Lead 独立核对并写 Evidence、状态和最终验收。
|
|
551
485
|
|
|
552
486
|
## 5. Constraints, Risk and Recovery
|
|
553
487
|
|
|
554
488
|
### Non-negotiable Constraints
|
|
555
489
|
|
|
556
|
-
每条包含来源和违反后果;局部实现自由进入 Guidance。
|
|
557
|
-
|
|
558
490
|
### Verification Integrity
|
|
559
491
|
|
|
560
|
-
|
|
492
|
+
记录判卷接缝、基线、禁止的伪绿色方式,以及 source/candidate 两层验证边界。
|
|
561
493
|
|
|
562
494
|
### Migration or Release Sequence
|
|
563
495
|
|
|
@@ -571,62 +503,20 @@ ready_for_execution: false
|
|
|
571
503
|
|
|
572
504
|
### Current Status
|
|
573
505
|
|
|
574
|
-
记录 Wave/Gate、Ticket
|
|
506
|
+
记录 Wave/Gate、Ticket、source/candidate/result SHA、最近验证和未验证项;不使用主观百分比。
|
|
575
507
|
|
|
576
508
|
### Pending Decisions and Blockers
|
|
577
509
|
|
|
578
|
-
记录失败命令、已通过行为、owner 和恢复条件。
|
|
579
|
-
|
|
580
510
|
### Resume Protocol
|
|
581
511
|
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
### Reporting Format
|
|
512
|
+
恢复时读取 Goal Plan、当前 Ticket、change worktree 状态和最新 Evidence;从最后通过的父分支 result 或待修正 source checkpoint 继续。
|
|
585
513
|
|
|
586
514
|
## Assumptions
|
|
587
515
|
|
|
588
|
-
|
|
516
|
+
只记录低影响且可验证的假设。存在高影响假设时 `ready_for_execution` 必须为 `false`。
|
|
589
517
|
|
|
590
518
|
</goal-plan-template>
|
|
591
519
|
|
|
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
|
-
|
|
630
520
|
<artifact-contract>
|
|
631
521
|
|
|
632
522
|
# 工件职责与权威裁决
|
|
@@ -709,39 +599,37 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
|
|
|
709
599
|
|
|
710
600
|
# 路径所有权与并发规则
|
|
711
601
|
|
|
712
|
-
|
|
602
|
+
路径所有权是逻辑写入边界;worktree 是物理隔离边界,两者不能互相替代。
|
|
713
603
|
|
|
714
604
|
## 1. 四类路径
|
|
715
605
|
|
|
716
|
-
- `expected_changes
|
|
717
|
-
- `writable_paths
|
|
718
|
-
- `read_only_paths
|
|
719
|
-
- `shared_paths`:多个 Ticket
|
|
720
|
-
|
|
721
|
-
示例:
|
|
606
|
+
- `expected_changes`:导航预测;
|
|
607
|
+
- `writable_paths`:当前 Ticket implementation owner 可写的硬边界;
|
|
608
|
+
- `read_only_paths`:只读上下文;
|
|
609
|
+
- `shared_paths`:多个 Ticket 可能触达且必须有唯一 owner 的项目路径。
|
|
722
610
|
|
|
723
|
-
|
|
724
|
-
expected_changes: ["src/auth/session.ts"]
|
|
725
|
-
writable_paths: ["src/auth/**"]
|
|
726
|
-
read_only_paths: ["src/users/**"]
|
|
727
|
-
shared_paths: ["package.json"]
|
|
728
|
-
```
|
|
611
|
+
所有项目路径使用项目根相对路径。根依赖清单、锁文件、根导出、共享 schema、迁移索引、全局路由和跨 Ticket 合同默认视为 shared。
|
|
729
612
|
|
|
730
613
|
## 2. 所有权规则
|
|
731
614
|
|
|
732
|
-
1. 可能并行的 Ticket,其
|
|
733
|
-
2.
|
|
734
|
-
3.
|
|
735
|
-
4.
|
|
736
|
-
5.
|
|
737
|
-
6.
|
|
738
|
-
|
|
615
|
+
1. 可能并行的 Ticket,其 writable paths 不得相交;glob 按覆盖关系判断。
|
|
616
|
+
2. shared path 只由专用 owner Ticket 修改;消费者 Ticket 只读。Lead 负责集成,不以冲突解决替代 shared owner。
|
|
617
|
+
3. implementation subagent 只写其 Packet 与 Ticket 授权路径;Lead 自行实现也受同一边界约束。
|
|
618
|
+
4. review/research/test-observation agent 只读项目与 SpecDev 工件。
|
|
619
|
+
5. 越界前停止并按 deviation control 提出 ownership change;不得先改后报。
|
|
620
|
+
6. 上游 Ticket 改变目录/合同后,下游基于已集成父分支重新解析路径和 preflight。
|
|
621
|
+
|
|
622
|
+
## 3. Ticket worktree
|
|
739
623
|
|
|
740
|
-
|
|
624
|
+
每个进入 I-implement 的 Ticket 都使用唯一来源 worktree `specdev-worktree/<ticket-id>`,无论是否并行、是否派遣 subagent。Ticket 切片是隔离依据;Agent Team 不是 worktree 触发器。没有 Ticket 的获批 Direct Spec 可由 current workspace 唯一 owner 执行;只读调查不创建实现 worktree。
|
|
741
625
|
|
|
742
|
-
|
|
626
|
+
workspace/implementation owner 可以是 Lead 或动态 implementation subagent;integration owner 固定为 Lead。只有 Lead 写 SpecDev 状态、建立 parent-candidate、运行适用 E2E 并推进父分支。生命周期由 下方 `<dev-worktree>` 标签 管理。
|
|
743
627
|
|
|
744
|
-
|
|
628
|
+
## 4. 并发
|
|
629
|
+
|
|
630
|
+
implementation subagent 同时最多三个,Lead 不计入;实际上限取 Goal Plan、config 和平台能力最小值。review/research/test-observation agent 不设置 SpecDev 数字上限,但 Lead 必须避免重复工作与可变环境争用。
|
|
631
|
+
|
|
632
|
+
**完成标准**:每个项目写入映射到唯一 Ticket、owner 和来源 worktree;shared 与父分支写入 owner 唯一。
|
|
745
633
|
|
|
746
634
|
</path-ownership>
|
|
747
635
|
|
|
@@ -749,61 +637,51 @@ shared_paths: ["package.json"]
|
|
|
749
637
|
|
|
750
638
|
# 证据与验证规范
|
|
751
639
|
|
|
752
|
-
|
|
640
|
+
验证回答“怎样证明”,Evidence 记录“实际运行了什么、在哪个状态运行、结果和残余风险是什么”。
|
|
753
641
|
|
|
754
642
|
## 1. 验证矩阵
|
|
755
643
|
|
|
756
|
-
|
|
644
|
+
每行绑定行为、合同或风险,并标记环境:
|
|
757
645
|
|
|
758
|
-
| 行为或风险 |
|
|
759
|
-
|
|
760
|
-
|
|
|
761
|
-
|
|
|
762
|
-
|
|
|
646
|
+
| 行为或风险 | 接缝 | 命令/方法 | 环境 | 预期 | Evidence |
|
|
647
|
+
|---|---|---|---|---|---|
|
|
648
|
+
| 正常/失败路径 | 公共接口或稳定接缝 | 定向测试 | source-worktree | 合同成立 | Ticket Evidence |
|
|
649
|
+
| 跨模块回归 | 集成接缝 | 回归命令 | parent-candidate | 组合状态成立 | Ticket Evidence |
|
|
650
|
+
| E2E required | 真实端到端边界 | 场景步骤 | parent-candidate | 外部行为成立 | Ticket Evidence |
|
|
651
|
+
|
|
652
|
+
## 2. 两层验证
|
|
653
|
+
|
|
654
|
+
### Source-worktree
|
|
655
|
+
|
|
656
|
+
implementation owner 运行最接近目标行为的单元/组件测试、静态分析、类型、lint/build 等适用非 E2E 检查。来源实现必须在 clean worktree 形成 commit。任何 source-worktree E2E pass 声明无效。
|
|
763
657
|
|
|
764
|
-
|
|
658
|
+
### Parent-candidate
|
|
765
659
|
|
|
766
|
-
|
|
660
|
+
Lead 在最新父分支与 source commit 的 candidate 状态运行受影响集成/回归、项目父状态检查和适用 E2E。E2E 由实际跨边界风险决定,不限于 UI;not-required 必须写理由。required E2E 未运行或失败时不得推进父分支。
|
|
767
661
|
|
|
768
|
-
|
|
662
|
+
### Direct Spec
|
|
769
663
|
|
|
770
|
-
|
|
771
|
-
2. 稳定接缝上的单元测试;
|
|
772
|
-
3. 类型检查、静态分析、lint 和构建;
|
|
773
|
-
4. 可重复手动步骤、截图或查询结果;
|
|
774
|
-
5. 代码阅读推断。
|
|
664
|
+
获批 Direct Spec 不创建 Ticket worktree 或 candidate。Lead 在 current workspace 记录实施前基线,运行轻量合同要求的定向检查、适用回归与 E2E,并记录最终 checkpoint、dirty 状态、运行环境、命令、退出状态和未运行原因。E2E 仍只由 Lead 执行;不得为套用两层验证而伪造 Ticket、source/candidate/result 或父分支推进证据。
|
|
775
665
|
|
|
776
|
-
|
|
666
|
+
低层证据不能替代明确要求的外部行为证据。高风险迁移还需要 dry-run、调用点扫描、数据核对、监控或恢复演练。
|
|
777
667
|
|
|
778
|
-
|
|
668
|
+
## 3. Agent 声明
|
|
779
669
|
|
|
780
|
-
|
|
670
|
+
subagent 只返回候选命令与结果,不写 Evidence。Lead 重读 workspace/Git、必要时复跑或核对输出后落盘;外部 provider 自报、截图、模拟和推断在此之前标记 `unverified`。review/research/test-observation agent 不拥有 E2E Gate。
|
|
781
671
|
|
|
782
|
-
|
|
672
|
+
## 4. 失败分类与完整性
|
|
783
673
|
|
|
784
|
-
|
|
785
|
-
- 基线已存在的失败;
|
|
786
|
-
- 环境、权限或基础设施失败;
|
|
787
|
-
- 验证本身无效或无法观察目标行为。
|
|
674
|
+
失败分类为本 Ticket 新失败、基线既有失败、环境/权限/基础设施失败、无效验证或 candidate stale。不得通过跳过、放宽断言、吞错、删除用例或迁移验证位置制造绿色。
|
|
788
675
|
|
|
789
|
-
|
|
676
|
+
受控反向验证只用于可能静默通过的关键门禁:证明检查能在目标风险出现时失败,再恢复并重跑。普通测试不为形式执行破坏性操作。
|
|
790
677
|
|
|
791
|
-
##
|
|
678
|
+
## 5. Evidence 最低内容
|
|
792
679
|
|
|
793
|
-
|
|
680
|
+
每个 Ticket Evidence 至少包含:Lead、Dispatch/返回(若有)、base/source/candidate/result SHA、来源 worktree、实际路径、每条命令/环境/退出状态、合同映射、双轴审查、E2E disposition、未运行项、失败分类、偏差、残余风险和父分支重读结果。
|
|
794
681
|
|
|
795
|
-
|
|
796
|
-
- 实际修改的项目路径;
|
|
797
|
-
- 每条命令、退出状态和结果摘要;
|
|
798
|
-
- 每条验收合同的证据映射;
|
|
799
|
-
- 未运行项与原因;
|
|
800
|
-
- 新失败、既有失败和环境失败;
|
|
801
|
-
- 偏差及批准;
|
|
802
|
-
- 残余风险;
|
|
803
|
-
- worktree、提交或 PR 引用;
|
|
804
|
-
- 最终结论。
|
|
682
|
+
Ticket Done 必须有 source commit、通过 candidate、父分支 result 与 Lead Evidence。无法运行 required 验证、存在未批准偏差、父分支未包含 source commit 或 Evidence 不完整时不得 Done。
|
|
805
683
|
|
|
806
|
-
|
|
684
|
+
Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施前/最终 checkpoint、实际路径、定向/回归/E2E 命令及环境、验收映射、未运行项、偏差、残余风险和提交授权状态。
|
|
807
685
|
|
|
808
686
|
</evidence-and-verification>
|
|
809
687
|
|
|
@@ -851,7 +729,7 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由
|
|
|
851
729
|
|
|
852
730
|
- 未批准的 ticket、spec、architecture 或 release 偏差不得继续实现。
|
|
853
731
|
- 不得通过扩大 `writable_paths`、删除测试、降低断言或把风险改写成“已知限制”来绕过停止。
|
|
854
|
-
-
|
|
732
|
+
- 偏差影响并行执行、source checkpoint 或 candidate 集成时,Lead 必须暂停受影响 Wave,重新计算路径所有权、依赖、Gate 与父分支顺序;任何 subagent 都不能自行改写上层合同。
|
|
855
733
|
|
|
856
734
|
</deviation-control>
|
|
857
735
|
|
|
@@ -859,37 +737,35 @@ E2E 仅在变更影响用户界面交互时加入验证矩阵。普通执行由
|
|
|
859
737
|
|
|
860
738
|
# Change Completion
|
|
861
739
|
|
|
862
|
-
本规则是 change 从 active/blocked 转为 completed
|
|
740
|
+
本规则是 change 从 active/blocked 转为 completed 的唯一合同。
|
|
863
741
|
|
|
864
742
|
## 完成门
|
|
865
743
|
|
|
866
|
-
一个 change
|
|
744
|
+
一个 change 只有同时满足以下条件才能 completed:
|
|
867
745
|
|
|
868
|
-
1. 所有计划内 Ticket 为
|
|
869
|
-
2.
|
|
870
|
-
3.
|
|
871
|
-
4.
|
|
872
|
-
5.
|
|
873
|
-
6.
|
|
746
|
+
1. 所有计划内 Ticket 为 done,或因权威事实无需改动而记录为 cancelled;Direct Spec/非实现流程有等价验收。
|
|
747
|
+
2. 每个 done Ticket 有 source commit、passed candidate、父分支 result SHA,且父分支包含 source commit;worktree 生命周期为 `integrated` 或完成来源清理后的 `removed`。
|
|
748
|
+
3. 每个行为有 Lead Evidence,全部 Spec 合同与 Goal Gate 可定位。
|
|
749
|
+
4. source-worktree 非 E2E 检查、parent-candidate 集成/回归和 required E2E 已通过;not-required 有理由。
|
|
750
|
+
5. 迁移、发布、监控、恢复和不可逆批准已完成或明确不适用。
|
|
751
|
+
6. 没有未批准 deviation、blocker、unverified、活动 candidate 或未集成 source checkpoint。
|
|
752
|
+
7. Ticket、Map、Goal Plan、Evidence、change status 与实际 Git 一致。
|
|
753
|
+
|
|
754
|
+
Evidence-only Done 和 empty commit 不满足完成门。
|
|
874
755
|
|
|
875
756
|
## 转换 Owner
|
|
876
757
|
|
|
877
|
-
- Goal Plan
|
|
878
|
-
-
|
|
879
|
-
-
|
|
758
|
+
- 有 Goal Plan:其唯一 Lead 在关闭最后 Gate 后拥有转换;
|
|
759
|
+
- 无 Goal Plan 的 Ticket/Direct Spec:当前 I-implement 主会话 owner 拥有转换;
|
|
760
|
+
- 非实现型终点:最终验收工件 owner 使用本规则。
|
|
880
761
|
|
|
881
|
-
Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work
|
|
762
|
+
Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`、`completed_at`、`updated_at` 和 `current_work`,然后重读。全局 status 只维护 active/archived 索引。
|
|
882
763
|
|
|
883
764
|
## 远程来源与归档
|
|
884
765
|
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
## 完成标准
|
|
766
|
+
远程动作不参与本地完成判定。Triage 为 `pending-close`/`close-failed` 时先 reconcile;`closed`、`waived` 或 `not-applicable` 才允许 Archive。归档后工件只读。
|
|
888
767
|
|
|
889
|
-
|
|
890
|
-
- 当前 change 只有一个条件命中的转换 owner;
|
|
891
|
-
- 远程失败不会把 completed 改回 active;
|
|
892
|
-
- Archive 不接收尚未 reconcile 或 waive 的远程来源。
|
|
768
|
+
**完成标准**:完成声明可由本地工件、Git 与验证重建;只有一个 owner 命中;失败 candidate 不污染父分支。
|
|
893
769
|
|
|
894
770
|
</change-completion>
|
|
895
771
|
|
|
@@ -950,230 +826,323 @@ Owner 原子更新 `specdev/changes/{change}/.status.json` 的 `change_status`
|
|
|
950
826
|
|
|
951
827
|
<dev-worktree>
|
|
952
828
|
|
|
953
|
-
#
|
|
829
|
+
# Dev Worktree
|
|
830
|
+
|
|
831
|
+
本 Skill 由 T-tickets/P-goal-plan/I-implement 和 P-prototype 复用。`purpose=ticket` 使用完整 source → candidate → parent 状态机;`purpose=prototype` 只使用调用方批准的临时生命周期。
|
|
832
|
+
|
|
833
|
+
## 输入
|
|
954
834
|
|
|
955
|
-
|
|
835
|
+
- `operation=create | restore | finalize | remove`;
|
|
836
|
+
- `purpose=ticket | prototype`;
|
|
837
|
+
- repository、父分支、`base_sha`、branch、portable workspace locator;
|
|
838
|
+
- workspace、implementation 和 integration owner;
|
|
839
|
+
- 允许动作、路径合同、验证合同、调用方状态记录位置。
|
|
956
840
|
|
|
957
|
-
|
|
958
|
-
- 只读调查和顺序执行默认共用当前工作区。
|
|
959
|
-
- 调用方必须明确 workspace owner、implementation owner、固定基线、工作项 ID、持久化 owner 和允许的结束动作。
|
|
960
|
-
- 普通执行不建立额外角色;委派 Goal Plan 才把 workspace owner/implementation owner 分别映射为 Lead/Worker。
|
|
961
|
-
- 平台原生 worktree 优先;不可用时使用 Git worktree。
|
|
841
|
+
Ticket 还必须提供 Ready Ticket、Goal Plan(若存在)、Evidence 路径、implementation commit 与本地 candidate integration/父分支更新授权。缺失时返回 blocked,不使用 current workspace 代替。
|
|
962
842
|
|
|
963
|
-
##
|
|
843
|
+
## 1. 创建或恢复
|
|
964
844
|
|
|
965
|
-
|
|
966
|
-
2. implementation owner 完成后返回工作项状态、Evidence/record 路径、`workspace_ref`、checkpoint、commit 或 PR 引用和未验证项;Ticket worktree 从 `active` 更新为 `review`。
|
|
967
|
-
3. workspace owner 集成或清理时加载 下方 `<dev-worktree-finalize>` 标签;一次性原型只评估和清理,不合入生产分支。
|
|
845
|
+
`operation=create` 时加载 下方 `<dev-worktree-create>` 标签。Ticket 使用 `specdev-worktree/<ticket-id>`;同一 Ticket 只存在一个来源 worktree。`operation=restore` 时重读实际 Git worktree/branch/tip/dirty 状态并与调用方记录核对,漂移时停止。
|
|
968
846
|
|
|
969
|
-
|
|
847
|
+
**完成标准**:来源基线、branch、locator、owners 和实际 Git 状态一致;现有用户改动未被覆盖。
|
|
970
848
|
|
|
971
|
-
##
|
|
849
|
+
## 2. 来源实现门
|
|
972
850
|
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
851
|
+
implementation owner 只在来源 worktree 修改授权项目路径,运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查。进入 `review` 前,worktree 必须 clean,branch tip 必须是已授权的 `source_checkpoint` commit,实际 diff 必须符合路径合同。
|
|
852
|
+
|
|
853
|
+
**完成标准**:source checkpoint 不可变且可达;来源 worktree 没有 E2E pass 声明。
|
|
854
|
+
|
|
855
|
+
## 3. 候选合并与父分支推进
|
|
856
|
+
|
|
857
|
+
`operation=finalize` 仅由 Lead/integration owner 调用,并加载 下方 `<dev-worktree-finalize>` 标签。Lead 在独立 parent-candidate checkout 组合最新父分支与 source checkpoint,运行集成检查和适用 E2E,通过后才推进父分支。
|
|
858
|
+
|
|
859
|
+
本地 candidate checkout/branch 的创建、重建和回收属于已授权 local candidate integration;来源 branch/worktree 的删除仍需要独立 cleanup 授权。push、PR、remote merge、deploy、migration 和生产动作不从本 Skill 继承。
|
|
860
|
+
|
|
861
|
+
**完成标准**:Ticket `integrated` 时父 HEAD 精确等于记录的 result SHA,并包含 source checkpoint;失败或 stale 时父分支未变化。后续 `removed` 只表示来源 branch/worktree 已清理,不撤销该集成事实。
|
|
862
|
+
|
|
863
|
+
## 4. 移除
|
|
864
|
+
|
|
865
|
+
`operation=remove` 先验证 Ticket 已 `integrated` 或 prototype 已结束、目标 worktree clean、checkpoint 可恢复且删除目标精确。只有明确 cleanup 授权时删除来源 branch/worktree;强制删除需要单独确认。删除后重读 `git worktree list` 与 refs,并只把调用方生命周期状态更新为 `removed`;`base_sha`、source checkpoint、candidate/result、验证、E2E 与 Evidence 字段必须原样保留。
|
|
866
|
+
|
|
867
|
+
**完成标准**:只删除精确授权目标;失败保留现场与恢复命令。
|
|
868
|
+
|
|
869
|
+
## 固定规则
|
|
870
|
+
|
|
871
|
+
- Agent Team 不决定 worktree;Ticket 切片本身决定来源 worktree;
|
|
872
|
+
- Ticket E2E 只在 Lead-owned parent-candidate checkout 运行;
|
|
873
|
+
- 每个 Done Ticket 必须有 source commit 与父分支 result,worktree 状态为 `integrated` 或其清理后终态 `removed`;
|
|
874
|
+
- candidate 失败保留来源 worktree 修正,父分支不动;
|
|
875
|
+
- 成功集成不自动清理来源 branch/worktree。
|
|
979
876
|
|
|
980
877
|
</dev-worktree>
|
|
981
878
|
|
|
982
879
|
<dev-worktree-create>
|
|
983
880
|
|
|
984
|
-
#
|
|
881
|
+
# Create Or Restore Worktree
|
|
882
|
+
|
|
883
|
+
## Ticket 前置条件
|
|
884
|
+
|
|
885
|
+
- Ticket Ready,项目根是有效 Git repository,父分支和 `base_sha` 可解析;
|
|
886
|
+
- implementation commit 与 local candidate integration/父分支更新已授权;
|
|
887
|
+
- workspace、implementation、integration owner 唯一;integration owner 必须为 Lead;
|
|
888
|
+
- `specdev-worktree/` 已由 Speculo init 加入项目 `.gitignore`;
|
|
889
|
+
- 目标 branch/worktree 不覆盖现有用户 workspace,路径合同无冲突。
|
|
985
890
|
|
|
986
|
-
|
|
891
|
+
Prototype 只要求调用方已记录本次临时 branch/worktree 授权、问题、owner、locator 和清理策略;它不写 Ticket worktree 状态。
|
|
987
892
|
|
|
988
|
-
|
|
989
|
-
- 并行 Ticket 要求 `specdev/config.json` 中 `git.worktree_for_parallel: true`;一次性原型要求 P-prototype 已取得本次临时 worktree 授权。
|
|
990
|
-
- 调用方已指定 workspace owner、implementation owner、工作项 ID、持久化 owner,并固定 `base_sha`;并行 Ticket 共用同一基线。
|
|
893
|
+
## 创建 Ticket 来源 worktree
|
|
991
894
|
|
|
992
|
-
|
|
895
|
+
1. 重读父分支 HEAD、工作树、现有 worktrees 与 refs;父 HEAD 与计划基线不一致时由 Lead决定更新 `base_sha` 或阻塞;
|
|
896
|
+
2. 固定 branch `speculo/<change>/<ticket-id>` 与 locator `specdev-worktree/<ticket-id>`;
|
|
897
|
+
3. 确认目标 branch/path 不存在,或其实际记录精确匹配当前 Ticket;
|
|
898
|
+
4. 从 `base_sha` 创建 Git worktree,不复用其他 Ticket/原型目录;
|
|
899
|
+
5. 在来源 worktree 读取项目 Agent 指令、依赖、构建与路径合同;
|
|
900
|
+
6. 安装实际需要的依赖,运行最小非 E2E 基线;
|
|
901
|
+
7. Lead 写入 `specdev/changes/{change}/.status.json`,状态为 `active`。
|
|
993
902
|
|
|
994
|
-
|
|
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`:
|
|
903
|
+
初始记录:
|
|
1002
904
|
|
|
1003
905
|
```json
|
|
1004
906
|
{
|
|
1005
907
|
"ticket_id": "T-01",
|
|
1006
|
-
"owner": "
|
|
908
|
+
"owner": "lead",
|
|
909
|
+
"implementation_owner": "lead-or-dynamic-agent",
|
|
910
|
+
"integration_owner": "lead",
|
|
1007
911
|
"provider": "git",
|
|
1008
|
-
"base_sha": "<sha>",
|
|
912
|
+
"base_sha": "<immutable-sha>",
|
|
913
|
+
"parent_branch": "<parent-branch>",
|
|
1009
914
|
"branch": "speculo/<change>/T-01",
|
|
1010
915
|
"workspace_ref": "specdev-worktree/T-01",
|
|
916
|
+
"source_checkpoint": null,
|
|
917
|
+
"integration": {
|
|
918
|
+
"status": "pending",
|
|
919
|
+
"parent_before_sha": null,
|
|
920
|
+
"source_sha": null,
|
|
921
|
+
"candidate_sha": null,
|
|
922
|
+
"candidate_branch": null,
|
|
923
|
+
"candidate_workspace_ref": null,
|
|
924
|
+
"result_sha": null,
|
|
925
|
+
"method": null,
|
|
926
|
+
"conflict_paths": [],
|
|
927
|
+
"verification": "pending",
|
|
928
|
+
"e2e": {"required": false, "status": "not-required", "evidence": null},
|
|
929
|
+
"evidence": "specdev/changes/<change>/evidence/T-01.md",
|
|
930
|
+
"attempts": 0
|
|
931
|
+
},
|
|
1011
932
|
"status": "active",
|
|
1012
933
|
"updated_at": "<ISO-8601>"
|
|
1013
934
|
}
|
|
1014
935
|
```
|
|
1015
936
|
|
|
1016
|
-
|
|
937
|
+
`e2e.required` 与 Ticket/Goal Plan disposition 一致;required 时初始 status 为 `pending`。
|
|
938
|
+
|
|
939
|
+
## 恢复
|
|
940
|
+
|
|
941
|
+
恢复时核对 repository、branch、locator、`base_sha`、实际 HEAD、dirty 状态和 owner。状态记录与 Git 不一致、branch 被其他 worktree 占用或出现越界修改时停止;Lead 写 blocker,不重建覆盖。
|
|
1017
942
|
|
|
1018
|
-
|
|
943
|
+
进入 `review` 前必须由 implementation owner 创建最终 commit;Lead 重读 branch tip、diff 与 `git status`,把精确 SHA 写入 `source_checkpoint`。
|
|
944
|
+
|
|
945
|
+
**完成标准**:来源 worktree 可定位且唯一;基线、记录与 Git 一致;source 检查不含 E2E;失败时保留现场。
|
|
1019
946
|
|
|
1020
947
|
</dev-worktree-create>
|
|
1021
948
|
|
|
1022
949
|
<dev-worktree-finalize>
|
|
1023
950
|
|
|
1024
|
-
#
|
|
951
|
+
# Candidate Merge And Parent Integration
|
|
1025
952
|
|
|
1026
|
-
|
|
953
|
+
仅由 Lead/integration owner 对状态为 `review` 的 Ticket 调用。
|
|
1027
954
|
|
|
1028
|
-
|
|
955
|
+
## 1. 接收 source checkpoint
|
|
1029
956
|
|
|
1030
|
-
1.
|
|
1031
|
-
2.
|
|
1032
|
-
3.
|
|
1033
|
-
4.
|
|
957
|
+
1. 核对 Ticket、Goal Plan、Evidence 目标、owner 与本地 integration 授权;
|
|
958
|
+
2. 验证来源 worktree clean,branch tip 精确等于 `source_checkpoint`,commit 从 `base_sha` 可达;
|
|
959
|
+
3. 审计实际 diff 未越过 writable/shared owner 合同;
|
|
960
|
+
4. 确认 source-worktree 必跑非 E2E 检查已执行,且没有把 E2E 自报为通过;
|
|
961
|
+
5. 重读父分支 checkout clean、HEAD 与 remote/本地约定,记录 `parent_before_sha`。
|
|
1034
962
|
|
|
1035
|
-
|
|
963
|
+
失败时保持 `review`/`blocked`,不开始候选合并。
|
|
1036
964
|
|
|
1037
|
-
|
|
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` 条目。
|
|
965
|
+
## 2. 建立 parent-candidate checkout
|
|
1040
966
|
|
|
1041
|
-
|
|
967
|
+
1. 使用 branch `speculo/integration/<change>/<ticket-id>` 和 locator `specdev-worktree/.integration/<ticket-id>`,从最新 `parent_before_sha` 建立 Lead-owned integration worktree;
|
|
968
|
+
2. 如果父 SHA 是 source checkpoint 的祖先,在 candidate checkout 执行 `git merge --ff-only <source_checkpoint>`,`method=fast-forward`;
|
|
969
|
+
3. 否则执行 `git merge --no-ff --no-commit <source_checkpoint>`;
|
|
970
|
+
4. 冲突按 下方 `<merge-conflict-protocol>` 标签 处理。需要新产品决定时执行 `git merge --abort`,记录 blocker 并返回来源 worktree;
|
|
971
|
+
5. 对分叉结果创建一次 Lead-owned candidate merge commit,`method=merge-commit`;
|
|
972
|
+
6. 记录 candidate branch/locator、`candidate_sha`、`source_sha`、冲突路径与 attempts,worktree 状态改为 `integrating`、integration 状态改为 `candidate`。
|
|
1042
973
|
|
|
1043
|
-
|
|
974
|
+
重试前从最新父分支重建 candidate branch/worktree;旧 candidate SHA 保存在 Evidence。候选生命周期的重建/回收包含在 local candidate integration 授权中。
|
|
1044
975
|
|
|
1045
|
-
|
|
976
|
+
## 3. 在候选父状态验证
|
|
1046
977
|
|
|
1047
|
-
|
|
978
|
+
在 candidate checkout 运行:
|
|
1048
979
|
|
|
1049
|
-
|
|
980
|
+
- Ticket 受影响集成与回归;
|
|
981
|
+
- 项目要求的 typecheck/lint/build 或其他父状态检查;
|
|
982
|
+
- 仅当 Ticket/Goal Plan `e2e.required=true` 时运行对应 E2E。
|
|
1050
983
|
|
|
1051
|
-
|
|
984
|
+
每条命令记录运行环境 `parent-candidate`、退出码与摘要。E2E required 未运行或失败时 integration `verification=failed`、`status=failed`;父分支保持 `parent_before_sha`。可由既有合同机械修正的失败最多处理三轮;不得放宽断言、删除检查或发明行为。
|
|
985
|
+
|
|
986
|
+
## 4. 推进父分支
|
|
987
|
+
|
|
988
|
+
全部 required 检查通过后:
|
|
989
|
+
|
|
990
|
+
1. 重读父分支 HEAD;不等于 `parent_before_sha` 时将 candidate 标记 `stale`,不推进父分支并从步骤 2 重建;
|
|
991
|
+
2. 在父分支 checkout 执行 `git merge --ff-only <candidate_sha>`;候选 merge commit 本身已以父 SHA 为第一祖先,因此不再创建第二个 merge commit;
|
|
992
|
+
3. 重读父 HEAD、tree 与 ancestor 关系,确认 HEAD 精确等于 candidate SHA 且包含 source checkpoint;
|
|
993
|
+
4. 写入 `result_sha=candidate_sha`、`verification=passed`、E2E 最终状态和 Evidence;
|
|
994
|
+
5. integration/status 改为 `passed`/`integrated`,再由 Lead 标记 Ticket Done。
|
|
995
|
+
|
|
996
|
+
## 5. 失败、清理与恢复
|
|
997
|
+
|
|
998
|
+
- candidate 检查失败:父分支不动,Ticket 回 `in_progress` 或 `blocked`,来源 worktree 保留;
|
|
999
|
+
- 父 HEAD 漂移:旧 candidate 记 `stale`,完整重建并重跑;
|
|
1000
|
+
- 成功后可按 candidate integration 授权回收 transient integration worktree/branch;来源 branch/worktree 不自动清理。获得独立 cleanup 授权并清理后,只将生命周期状态改为 `removed`,完整保留已经通过的集成与 E2E 证据;
|
|
1001
|
+
- push、PR、remote merge、deploy、migration 和生产动作仍需各自授权。
|
|
1052
1002
|
|
|
1053
|
-
|
|
1054
|
-
- `execution_model`:`native-subagent` 或 `external-web-subagent`;
|
|
1055
|
-
- Lead、Ticket、Goal Plan、Spec、适用 ADR/CONTEXT、Wave/Gate 和依赖 Evidence;
|
|
1056
|
-
- 项目写、只读和 shared 路径,验证矩阵与当前源码基线;
|
|
1057
|
-
- provider、会话或 workspace locator、源码交付方式,以及用户当前明确授权。
|
|
1003
|
+
**完成标准**:passed 时父 HEAD=result/candidate SHA 且包含 source commit;failed/stale 时父 HEAD 仍为开始该轮记录的父状态或更新后的外部事实,没有本轮候选污染。
|
|
1058
1004
|
|
|
1059
|
-
|
|
1005
|
+
</dev-worktree-finalize>
|
|
1006
|
+
|
|
1007
|
+
<merge-conflict-protocol>
|
|
1008
|
+
|
|
1009
|
+
# Merge / Rebase Conflict Protocol
|
|
1010
|
+
|
|
1011
|
+
只在 `git status` 证明仓库正处于 merge/rebase 冲突时加载。
|
|
1060
1012
|
|
|
1061
1013
|
## 流程
|
|
1062
1014
|
|
|
1063
|
-
|
|
1015
|
+
1. 读取 Git 状态、操作类型、冲突路径、base/ours/theirs SHA、Ticket/Evidence 与匹配的 candidate integration 记录。
|
|
1016
|
+
2. 从 commit、source、Spec、Ticket、ADR、测试和调用者追溯双方意图;信息不足时不猜产品行为。
|
|
1017
|
+
3. 对每个 hunk 写出双方意图、共同约束和唯一可推导结果;需要新行为或上层决定时停止并登记 deviation。
|
|
1018
|
+
4. 在授权路径内解决文本,运行受影响的非 E2E 检查;candidate checkout 中按 finalize 合同运行父状态检查/E2E。
|
|
1019
|
+
5. 匹配的 local candidate integration 授权包含 `git add`、candidate merge commit、必要的 `git merge --abort` 和 transient candidate checkout/branch 生命周期;不扩展到来源 branch/worktree cleanup 或远端动作。
|
|
1020
|
+
6. 需要改变 Spec/ADR、安全/迁移决定、越过 owner 或无法同时保持既有意图时,在 Lead-created candidate 中执行 `git merge --abort`,记录 blocker 并保留来源 worktree;未知普通冲突现场不擅自 abort。
|
|
1021
|
+
7. 重读 Git 状态、parents 与 diff,确认无 marker、无未声明路径、双方合同及验证仍成立。
|
|
1064
1022
|
|
|
1065
|
-
|
|
1023
|
+
## 完成标准
|
|
1066
1024
|
|
|
1067
|
-
|
|
1025
|
+
- 每个 hunk 可追溯到既有意图;
|
|
1026
|
+
- 新产品决定没有藏在冲突解决中;
|
|
1027
|
+
- 验证记录命令、运行环境、退出码和摘要;
|
|
1028
|
+
- Git 副作用来自明确的 candidate integration 或其他逐动作授权;
|
|
1029
|
+
- 完成/暂停可以从 Git、change status 和 Evidence 恢复。
|
|
1068
1030
|
|
|
1069
|
-
|
|
1031
|
+
</merge-conflict-protocol>
|
|
1070
1032
|
|
|
1071
|
-
|
|
1033
|
+
<subagent-delivery>
|
|
1072
1034
|
|
|
1073
|
-
|
|
1035
|
+
# Subagent Delivery
|
|
1074
1036
|
|
|
1075
|
-
|
|
1037
|
+
本 Skill 被 P-goal-plan 与 I-implement 调用。它不选择是否使用 Lead 模式:Lead 是固定外层 owner;本 Skill 只保证每次动态派单可恢复、可验收且不产生第二个 SpecDev 状态写入者。
|
|
1076
1038
|
|
|
1077
|
-
|
|
1039
|
+
## 输入
|
|
1078
1040
|
|
|
1079
|
-
|
|
1041
|
+
所有调用都必须提供 `operation=plan | dispatch | accept` 与 Lead owner/session locator。其余输入按 operation 判定,不得把后续阶段事实反向要求给 `plan`:
|
|
1080
1042
|
|
|
1081
|
-
- `
|
|
1082
|
-
- `
|
|
1043
|
+
- `operation=plan`:提供允许的 `task_kind` 集合、implementation subagent 上限、Lead/SpecDev/父分支/E2E 所有权和通用授权边界;Goal Plan 此时可以尚未写入,不要求 Ticket、provider、checkpoint 或 workspace;
|
|
1044
|
+
- `operation=dispatch`:提供 `task_kind=implementation | review | research | test-observation`、已存在 Goal Plan(若有)、Ticket/固定审查目标、依赖 Evidence、适用合同、repository、不可变 checkpoint、项目 Agent 指令、workspace/session locator、provider、允许动作、路径边界、检查、停止条件与返回格式;
|
|
1045
|
+
- `operation=accept`:提供原 Dispatch Packet、subagent 返回、当前 repository/workspace、预期与实际 checkpoint,以及 Lead 可用于独立核对的 Git/命令事实。
|
|
1083
1046
|
|
|
1084
|
-
|
|
1047
|
+
`operation=dispatch` 且 `task_kind=implementation` 时,还必须提供独立 Ticket worktree、branch、`base_sha`、writable/shared owner、implementation commit 授权与 source-worktree 非 E2E 检查。缺失时返回 blocked,不推断权限或创建 current-workspace 写入者。
|
|
1085
1048
|
|
|
1086
|
-
|
|
1049
|
+
## 1. 固定 Lead 与任务类型
|
|
1087
1050
|
|
|
1088
|
-
|
|
1051
|
+
Lead 保留需求解释、DAG/Wave/Gate、shared owner、权限、SpecDev 工件、Evidence、candidate-merge、父分支和最终回复。subagent 不写 Ticket、Map、Goal Plan、Evidence、change status 或父分支。
|
|
1089
1052
|
|
|
1090
|
-
|
|
1053
|
+
- implementation 可以写唯一 Ticket worktree,并在授权时创建实现 commit;
|
|
1054
|
+
- review/research/test-observation 只读,返回 findings、来源或命令观察;
|
|
1055
|
+
- E2E Gate 永远由 Lead 拥有,不能派给 implementation 或只读 agent;Ticket E2E 在 parent-candidate 状态执行,Direct Spec E2E 在 Lead-owned current workspace 执行。
|
|
1091
1056
|
|
|
1092
|
-
|
|
1057
|
+
**完成标准**:Lead、task kind、写入边界和 E2E owner 唯一。
|
|
1093
1058
|
|
|
1094
|
-
|
|
1059
|
+
## 2. 锁定基线、provider 与授权
|
|
1095
1060
|
|
|
1096
|
-
|
|
1061
|
+
记录 repository、branch、`base_sha`/固定审查 SHA、workspace/session locator 和 provider。GitHub 是源码事实来源时加载 下方 `<subagent-delivery-github-checkpoints>` 标签;需要向外部 provider 发送附件或私有上下文时,取得发送授权后加载 下方 `<subagent-delivery-source-package>` 标签。
|
|
1097
1062
|
|
|
1098
|
-
|
|
1063
|
+
授权逐动作记录:worktree local changes、implementation commit、外部内容发送、push、PR、remote merge、deploy、migration 和 production actions。Goal Plan 的本地 commit/integration 授权不扩展到远端、清理或生产动作。
|
|
1099
1064
|
|
|
1100
|
-
|
|
1065
|
+
**完成标准**:每个可变输入绑定 checkpoint;provider 只接收已授权范围;未授权动作不可执行。
|
|
1101
1066
|
|
|
1102
|
-
|
|
1067
|
+
## 3. 生成动态 Dispatch Packet
|
|
1103
1068
|
|
|
1104
|
-
|
|
1069
|
+
`operation=plan` 时只返回通用 Lead delivery contract,不读取尚未生成的 Goal Plan,也不为 Ticket 预分配 agent/provider。
|
|
1105
1070
|
|
|
1106
|
-
|
|
1071
|
+
`operation=dispatch` 时为单次任务生成 Packet:目标、IN/OUT、已锁定决定、固定输入、workspace、writable/read-only/shared paths、允许动作、必跑检查、禁止在 source worktree 运行 E2E、停止条件和返回字段。
|
|
1107
1072
|
|
|
1108
|
-
|
|
1073
|
+
- 原生 Agent:加载 下方 `<subagent-delivery-native>` 标签;
|
|
1074
|
+
- 外部网页 Agent:加载 下方 `<subagent-delivery-external-web>` 标签。
|
|
1109
1075
|
|
|
1110
|
-
|
|
1076
|
+
implementation Packet 必须适合一个上下文独立完成;多个 implementation subagent 由 Lead 控制在 Goal Plan/config 上限内且最多三个。只读 agent 不设置 SpecDev 数字上限,但不得争用可变环境。
|
|
1111
1077
|
|
|
1112
|
-
|
|
1078
|
+
**完成标准**:Packet 可独立投递;目标、checkpoint、路径、权限、检查和返回均可判定。
|
|
1113
1079
|
|
|
1114
|
-
|
|
1115
|
-
DISPATCH ticket=<id> wave=<wave> gate=<gate>
|
|
1116
|
-
baseline=<sha> branch=<branch> workspace=<workspace-ref>
|
|
1117
|
-
ticket_path=<full-ticket-path> evidence_path=<full-evidence-path>
|
|
1118
|
-
```
|
|
1080
|
+
## 4. 接收与验收候选
|
|
1119
1081
|
|
|
1120
|
-
|
|
1082
|
+
`operation=accept` 时,Lead 核对 Packet、当前父/来源基线、实际路径、dirty 状态、commit 可达性、命令输出和未验证项。外部声明、截图、provider 自报测试和推断保持 `unverified`,直到 Lead 在本地复核。
|
|
1121
1083
|
|
|
1122
|
-
|
|
1084
|
+
implementation 返回必须包含 Ticket ID、workspace locator、最终 commit、dirty 状态、修改路径、非 E2E 检查、失败/未运行项和恢复条件。review/research/test-observation 返回固定输入、findings、来源、命令与未验证声明。Lead 把验收结果写入调用方拥有的 Evidence/状态。
|
|
1123
1085
|
|
|
1124
|
-
|
|
1086
|
+
**完成标准**:每个 pass 有 Lead 可复查事实;candidate 未被误写为 Done 或父分支结果。
|
|
1125
1087
|
|
|
1126
|
-
|
|
1088
|
+
## 5. 修正与恢复
|
|
1127
1089
|
|
|
1128
|
-
|
|
1129
|
-
- 规范轴:Spec、ADR、Ticket、Goal Plan、路径合同和验收映射;
|
|
1130
|
-
- Lead 复跑的定向验证与适用回归;
|
|
1131
|
-
- 对可能静默失效的门禁执行一次受控反向验证,并恢复绿色基线。
|
|
1090
|
+
修正继续使用同一 Ticket 与 worktree,基于最后 source checkpoint 生成新 commit。基线或父分支漂移时由 Lead 暂停派单、重算影响并更新 Packet;契约冲突返回拥有该决定的工件。Lead 可以按当次风险在 Dispatch Packet 中定义停止条件,但 SpecDev 不推断全局修正次数;继续修正已无合理收益或需要上游决定时,返回 blocked、最后可信 checkpoint、失败命令和恢复条件。
|
|
1132
1091
|
|
|
1133
|
-
|
|
1092
|
+
**完成标准**:恢复不重新决定已锁定事项;每次候选都有唯一 checkpoint 和明确 owner。
|
|
1134
1093
|
|
|
1135
|
-
|
|
1094
|
+
</subagent-delivery>
|
|
1136
1095
|
|
|
1137
|
-
|
|
1096
|
+
<subagent-delivery-native>
|
|
1138
1097
|
|
|
1139
|
-
|
|
1098
|
+
# Native Subagent
|
|
1140
1099
|
|
|
1141
|
-
|
|
1100
|
+
Lead 可以直接创建和管理隔离 Agent 时加载。
|
|
1142
1101
|
|
|
1143
|
-
|
|
1102
|
+
## 派单
|
|
1144
1103
|
|
|
1145
|
-
|
|
1104
|
+
Lead 为每个 Agent 发送一个完整 Dispatch Packet。implementation Agent 只进入指定 Ticket worktree;review/research/test-observation Agent 只读取固定输入。并行前核对 Ticket 依赖与 writable/shared path,不以“不同 Agent”代替路径隔离。
|
|
1146
1105
|
|
|
1147
|
-
|
|
1106
|
+
Packet 对 implementation 明确:
|
|
1148
1107
|
|
|
1149
|
-
|
|
1108
|
+
- Ticket、Goal Plan、依赖 Evidence 与 `base_sha`;
|
|
1109
|
+
- branch、portable `workspace_ref`、writable/read-only/shared paths;
|
|
1110
|
+
- 允许 worktree local changes 与 implementation commit;
|
|
1111
|
+
- 单元、组件、静态、类型、lint/build 等适用非 E2E 检查;
|
|
1112
|
+
- E2E 由 Lead 在 parent-candidate 状态执行;
|
|
1113
|
+
- 越界、合同冲突、基线漂移和无法提交时立即停止。
|
|
1150
1114
|
|
|
1151
|
-
|
|
1115
|
+
## 返回
|
|
1152
1116
|
|
|
1153
|
-
|
|
1117
|
+
implementation Agent 返回 Ticket ID、workspace locator、最终 commit、`git status`、修改路径、命令/结果、未运行项、冲突和恢复条件,不写 SpecDev Evidence。只读 Agent 返回固定 checkpoint、findings、来源、命令观察和未验证项。
|
|
1154
1118
|
|
|
1155
|
-
|
|
1119
|
+
Lead 重读 worktree、验证 commit 可达且 tip 一致、检查实际 diff 与路径合同,再决定接受、修正或 blocked。接受的 implementation 候选进入 dev-worktree candidate-merge;只读结论由 Lead 写入对应权威工件。
|
|
1156
1120
|
|
|
1157
|
-
|
|
1121
|
+
**完成标准**:原生 Agent 的写入与返回均绑定一个 Packet;Lead 可以独立复现其事实声明。
|
|
1158
1122
|
|
|
1159
|
-
|
|
1123
|
+
</subagent-delivery-native>
|
|
1160
1124
|
|
|
1161
|
-
|
|
1162
|
-
2. 用户结果、里程碑位置、相关模块、公共契约和领域不变量;
|
|
1163
|
-
3. allowed/read-only/shared 路径、保留行为和依赖策略;
|
|
1164
|
-
4. 需要返回的方案、修改清单、patch/源码、测试、实际命令和风险;
|
|
1165
|
-
5. 当前授权矩阵与逐项验收标准;
|
|
1166
|
-
6. 未实际运行的检查必须标记 `unverified`。
|
|
1125
|
+
<subagent-delivery-external-web>
|
|
1167
1126
|
|
|
1168
|
-
|
|
1127
|
+
# External Web Subagent
|
|
1169
1128
|
|
|
1170
|
-
|
|
1129
|
+
用户已授权目标 provider 与发送内容范围,且外部网页模型能为当前任务提供实际价值时加载。外部会话永远返回候选,不拥有本地 worktree、commit、SpecDev 状态或 E2E Gate。
|
|
1171
1130
|
|
|
1172
|
-
|
|
1131
|
+
## 能力与数据门
|
|
1173
1132
|
|
|
1174
|
-
|
|
1133
|
+
先确认 provider 能接收的文件、大小、会话恢复、输出格式和数据保留边界。需要源码包时加载 source-package reference,排除凭据、真实用户数据、运行时状态和无关代码;记录 locator、hash 与 checkpoint。能力或授权不足时改用原生/Lead 执行,不降低合同。
|
|
1175
1134
|
|
|
1176
|
-
|
|
1135
|
+
## 投递与返回
|
|
1136
|
+
|
|
1137
|
+
Packet 固定目标、范围、合同、checkpoint、路径边界、非 E2E 验证要求和停止条件。外部 provider 返回 patch/文件、修改清单、推理摘要、模拟或自报测试、未验证项和会话 locator。
|
|
1138
|
+
|
|
1139
|
+
Lead 在 Ticket worktree 中核对附件 hash、应用候选、检查 diff、依赖与锁文件、运行本地非 E2E 检查并创建 implementation commit。外部自报结果、截图或模拟保持 `unverified`;适用 E2E 仍只在 parent-candidate 状态运行。
|
|
1140
|
+
|
|
1141
|
+
## 修正与恢复
|
|
1142
|
+
|
|
1143
|
+
修正轮绑定新的源码 checkpoint 或 candidate hash,不覆盖旧附件。会话无法恢复、输出越界或 contract 冲突时停止并保留最后可信包、失败证据和恢复条件。
|
|
1144
|
+
|
|
1145
|
+
**完成标准**:发送范围有授权且可审计;本地 commit 与验收完全由 Lead 拥有;外部声明不被当作通过证据。
|
|
1177
1146
|
|
|
1178
1147
|
</subagent-delivery-external-web>
|
|
1179
1148
|
|
|
@@ -1231,16 +1200,14 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1231
1200
|
|
|
1232
1201
|
```json
|
|
1233
1202
|
{
|
|
1234
|
-
"schema_version":
|
|
1203
|
+
"schema_version": 4,
|
|
1235
1204
|
"interaction_language": "zh-CN",
|
|
1236
1205
|
"artifact_language": "zh-CN",
|
|
1237
1206
|
"git": {
|
|
1238
|
-
"
|
|
1239
|
-
"default_branch": null,
|
|
1240
|
-
"worktree_for_parallel": true
|
|
1207
|
+
"default_branch": null
|
|
1241
1208
|
},
|
|
1242
1209
|
"execution": {
|
|
1243
|
-
"
|
|
1210
|
+
"max_implementation_agents": 3,
|
|
1244
1211
|
"deep_ticket_human_approval": true,
|
|
1245
1212
|
"shared_path_owner": "explicit"
|
|
1246
1213
|
},
|
|
@@ -1265,33 +1232,31 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1265
1232
|
```json
|
|
1266
1233
|
{
|
|
1267
1234
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1268
|
-
"$id": "urn:speculo:specdev:config:
|
|
1235
|
+
"$id": "urn:speculo:specdev:config:v4",
|
|
1269
1236
|
"title": "SpecDev Configuration",
|
|
1270
1237
|
"type": "object",
|
|
1271
1238
|
"required": ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"],
|
|
1272
1239
|
"properties": {
|
|
1273
|
-
"schema_version": {"const":
|
|
1240
|
+
"schema_version": {"const": 4},
|
|
1274
1241
|
"interaction_language": {"type": "string", "minLength": 1},
|
|
1275
1242
|
"artifact_language": {"type": "string", "minLength": 1},
|
|
1276
1243
|
"git": {
|
|
1277
1244
|
"type": "object",
|
|
1278
|
-
"required": ["
|
|
1245
|
+
"required": ["default_branch"],
|
|
1279
1246
|
"properties": {
|
|
1280
|
-
"
|
|
1281
|
-
"default_branch": {"type": ["string", "null"]},
|
|
1282
|
-
"worktree_for_parallel": {"type": "boolean"}
|
|
1247
|
+
"default_branch": {"type": ["string", "null"]}
|
|
1283
1248
|
},
|
|
1284
|
-
"additionalProperties":
|
|
1249
|
+
"additionalProperties": false
|
|
1285
1250
|
},
|
|
1286
1251
|
"execution": {
|
|
1287
1252
|
"type": "object",
|
|
1288
|
-
"required": ["
|
|
1253
|
+
"required": ["max_implementation_agents", "deep_ticket_human_approval", "shared_path_owner"],
|
|
1289
1254
|
"properties": {
|
|
1290
|
-
"
|
|
1255
|
+
"max_implementation_agents": {"type": "integer", "minimum": 1, "maximum": 3},
|
|
1291
1256
|
"deep_ticket_human_approval": {"type": "boolean"},
|
|
1292
1257
|
"shared_path_owner": {"type": "string", "minLength": 1}
|
|
1293
1258
|
},
|
|
1294
|
-
"additionalProperties":
|
|
1259
|
+
"additionalProperties": false
|
|
1295
1260
|
},
|
|
1296
1261
|
"verification": {
|
|
1297
1262
|
"type": "object",
|
|
@@ -1315,7 +1280,7 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1315
1280
|
"additionalProperties": true
|
|
1316
1281
|
}
|
|
1317
1282
|
},
|
|
1318
|
-
"additionalProperties":
|
|
1283
|
+
"additionalProperties": false
|
|
1319
1284
|
}
|
|
1320
1285
|
```
|
|
1321
1286
|
|
|
@@ -1325,7 +1290,7 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1325
1290
|
|
|
1326
1291
|
```json
|
|
1327
1292
|
{
|
|
1328
|
-
"schema_version":
|
|
1293
|
+
"schema_version": 5,
|
|
1329
1294
|
"workflow": "specdev",
|
|
1330
1295
|
"active": [],
|
|
1331
1296
|
"archived": []
|
|
@@ -1339,83 +1304,27 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1339
1304
|
```json
|
|
1340
1305
|
{
|
|
1341
1306
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1342
|
-
"$id": "urn:speculo:specdev:status:
|
|
1307
|
+
"$id": "urn:speculo:specdev:status:v5",
|
|
1343
1308
|
"title": "SpecDev Global Status",
|
|
1344
1309
|
"type": "object",
|
|
1345
|
-
"required": [
|
|
1346
|
-
"schema_version",
|
|
1347
|
-
"workflow",
|
|
1348
|
-
"active",
|
|
1349
|
-
"archived"
|
|
1350
|
-
],
|
|
1310
|
+
"required": ["schema_version", "workflow", "active", "archived"],
|
|
1351
1311
|
"properties": {
|
|
1352
|
-
"schema_version": {
|
|
1353
|
-
|
|
1354
|
-
},
|
|
1355
|
-
"workflow": {
|
|
1356
|
-
"const": "specdev"
|
|
1357
|
-
},
|
|
1312
|
+
"schema_version": {"const": 5},
|
|
1313
|
+
"workflow": {"const": "specdev"},
|
|
1358
1314
|
"active": {
|
|
1359
1315
|
"type": "array",
|
|
1360
1316
|
"items": {
|
|
1361
1317
|
"type": "object",
|
|
1362
|
-
"required": [
|
|
1363
|
-
"change",
|
|
1364
|
-
"current_work",
|
|
1365
|
-
"works_run"
|
|
1366
|
-
],
|
|
1318
|
+
"required": ["change"],
|
|
1367
1319
|
"properties": {
|
|
1368
1320
|
"change": {
|
|
1369
1321
|
"type": "string",
|
|
1370
1322
|
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"
|
|
1371
|
-
},
|
|
1372
|
-
"current_work": {
|
|
1373
|
-
"type": [
|
|
1374
|
-
"string",
|
|
1375
|
-
"null"
|
|
1376
|
-
],
|
|
1377
|
-
"pattern": "^specdev/"
|
|
1378
|
-
},
|
|
1379
|
-
"works_run": {
|
|
1380
|
-
"type": "array",
|
|
1381
|
-
"items": {
|
|
1382
|
-
"type": "string",
|
|
1383
|
-
"pattern": "^specdev/"
|
|
1384
|
-
},
|
|
1385
|
-
"uniqueItems": true
|
|
1386
|
-
},
|
|
1387
|
-
"claimed_investigations": {
|
|
1388
|
-
"type": "array",
|
|
1389
|
-
"items": {
|
|
1390
|
-
"type": "object",
|
|
1391
|
-
"required": [
|
|
1392
|
-
"id",
|
|
1393
|
-
"owner",
|
|
1394
|
-
"claimed_at"
|
|
1395
|
-
],
|
|
1396
|
-
"properties": {
|
|
1397
|
-
"id": {
|
|
1398
|
-
"type": "string"
|
|
1399
|
-
},
|
|
1400
|
-
"owner": {
|
|
1401
|
-
"type": "string"
|
|
1402
|
-
},
|
|
1403
|
-
"session": {
|
|
1404
|
-
"type": [
|
|
1405
|
-
"string",
|
|
1406
|
-
"null"
|
|
1407
|
-
]
|
|
1408
|
-
},
|
|
1409
|
-
"claimed_at": {
|
|
1410
|
-
"type": "string"
|
|
1411
|
-
}
|
|
1412
|
-
},
|
|
1413
|
-
"additionalProperties": false
|
|
1414
|
-
}
|
|
1415
1323
|
}
|
|
1416
1324
|
},
|
|
1417
1325
|
"additionalProperties": false
|
|
1418
|
-
}
|
|
1326
|
+
},
|
|
1327
|
+
"uniqueItems": true
|
|
1419
1328
|
},
|
|
1420
1329
|
"archived": {
|
|
1421
1330
|
"type": "array",
|
|
@@ -1436,11 +1345,24 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1436
1345
|
|
|
1437
1346
|
```json
|
|
1438
1347
|
{
|
|
1439
|
-
"schema_version":
|
|
1348
|
+
"schema_version": 5,
|
|
1440
1349
|
"artifact": "change-status",
|
|
1441
1350
|
"change": "<YYYY-MM-DD-topic>",
|
|
1442
1351
|
"change_status": "active",
|
|
1443
1352
|
"current_work": null,
|
|
1353
|
+
"works_run": [],
|
|
1354
|
+
"claimed_investigations": [],
|
|
1355
|
+
"execution_authorization": {
|
|
1356
|
+
"implementation_commit": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Ticket source commits"},
|
|
1357
|
+
"local_candidate_integration": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Lead-owned local parent candidate integration and parent update"},
|
|
1358
|
+
"source_cleanup": {"status": "not-authorized", "source": null, "granted_at": null, "scope": "Source worktree and branch cleanup"}
|
|
1359
|
+
},
|
|
1360
|
+
"leadership": {
|
|
1361
|
+
"current": "<owner-or-session-locator>",
|
|
1362
|
+
"epoch": 1,
|
|
1363
|
+
"assigned_at": "<ISO-8601>",
|
|
1364
|
+
"history": []
|
|
1365
|
+
},
|
|
1444
1366
|
"created_at": "<ISO-8601>",
|
|
1445
1367
|
"updated_at": "<ISO-8601>",
|
|
1446
1368
|
"completed_at": null,
|
|
@@ -1459,216 +1381,157 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1459
1381
|
```json
|
|
1460
1382
|
{
|
|
1461
1383
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1462
|
-
"$id": "urn:speculo:specdev:change-status:
|
|
1384
|
+
"$id": "urn:speculo:specdev:change-status:v5",
|
|
1463
1385
|
"title": "SpecDev Change Status",
|
|
1464
1386
|
"type": "object",
|
|
1465
1387
|
"required": [
|
|
1466
|
-
"schema_version",
|
|
1467
|
-
"
|
|
1468
|
-
"
|
|
1469
|
-
"change_status",
|
|
1470
|
-
"current_work",
|
|
1471
|
-
"created_at",
|
|
1472
|
-
"updated_at",
|
|
1473
|
-
"completed_at",
|
|
1474
|
-
"archived",
|
|
1475
|
-
"archive_path",
|
|
1476
|
-
"blockers",
|
|
1477
|
-
"deviations"
|
|
1388
|
+
"schema_version", "artifact", "change", "change_status", "current_work", "works_run",
|
|
1389
|
+
"claimed_investigations", "execution_authorization", "leadership", "created_at", "updated_at",
|
|
1390
|
+
"completed_at", "archived", "archive_path", "blockers", "deviations", "worktrees"
|
|
1478
1391
|
],
|
|
1479
1392
|
"properties": {
|
|
1480
|
-
"schema_version": {
|
|
1481
|
-
|
|
1482
|
-
},
|
|
1483
|
-
"
|
|
1484
|
-
|
|
1485
|
-
},
|
|
1486
|
-
"
|
|
1487
|
-
|
|
1488
|
-
|
|
1489
|
-
},
|
|
1490
|
-
"
|
|
1491
|
-
|
|
1492
|
-
|
|
1493
|
-
|
|
1494
|
-
|
|
1495
|
-
|
|
1496
|
-
|
|
1497
|
-
|
|
1498
|
-
|
|
1499
|
-
|
|
1500
|
-
|
|
1501
|
-
|
|
1502
|
-
|
|
1503
|
-
|
|
1504
|
-
|
|
1505
|
-
|
|
1506
|
-
|
|
1507
|
-
|
|
1508
|
-
|
|
1509
|
-
"type": "string",
|
|
1510
|
-
"minLength": 1
|
|
1393
|
+
"schema_version": {"const": 5},
|
|
1394
|
+
"artifact": {"const": "change-status"},
|
|
1395
|
+
"change": {"type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$"},
|
|
1396
|
+
"change_status": {"enum": ["active", "blocked", "completed", "archived"]},
|
|
1397
|
+
"current_work": {"type": ["string", "null"], "pattern": "^specdev/"},
|
|
1398
|
+
"works_run": {"type": "array", "items": {"type": "string", "pattern": "^specdev/"}, "uniqueItems": true},
|
|
1399
|
+
"claimed_investigations": {"type": "array", "items": {"$ref": "#/$defs/claim"}},
|
|
1400
|
+
"execution_authorization": {"$ref": "#/$defs/authorization"},
|
|
1401
|
+
"leadership": {"$ref": "#/$defs/leadership"},
|
|
1402
|
+
"created_at": {"type": "string", "minLength": 1},
|
|
1403
|
+
"updated_at": {"type": "string", "minLength": 1},
|
|
1404
|
+
"completed_at": {"type": ["string", "null"]},
|
|
1405
|
+
"archived": {"type": "boolean"},
|
|
1406
|
+
"archive_path": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"}]},
|
|
1407
|
+
"blockers": {"type": "array", "items": {"type": "string"}},
|
|
1408
|
+
"deviations": {"type": "array", "items": {"type": "string"}},
|
|
1409
|
+
"worktrees": {"type": "array", "items": {"$ref": "#/$defs/worktree"}}
|
|
1410
|
+
},
|
|
1411
|
+
"$defs": {
|
|
1412
|
+
"claim": {
|
|
1413
|
+
"type": "object",
|
|
1414
|
+
"required": ["id", "owner", "session", "claimed_at"],
|
|
1415
|
+
"properties": {
|
|
1416
|
+
"id": {"type": "string", "minLength": 1},
|
|
1417
|
+
"owner": {"type": "string", "minLength": 1},
|
|
1418
|
+
"session": {"type": ["string", "null"]},
|
|
1419
|
+
"claimed_at": {"type": "string", "minLength": 1}
|
|
1420
|
+
},
|
|
1421
|
+
"additionalProperties": false
|
|
1511
1422
|
},
|
|
1512
|
-
"
|
|
1513
|
-
"type":
|
|
1514
|
-
|
|
1515
|
-
|
|
1516
|
-
|
|
1423
|
+
"authorization-entry": {
|
|
1424
|
+
"type": "object",
|
|
1425
|
+
"required": ["status", "source", "granted_at", "scope"],
|
|
1426
|
+
"properties": {
|
|
1427
|
+
"status": {"enum": ["authorized", "not-authorized", "revoked"]},
|
|
1428
|
+
"source": {"type": ["string", "null"]},
|
|
1429
|
+
"granted_at": {"type": ["string", "null"]},
|
|
1430
|
+
"scope": {"type": "string", "minLength": 1}
|
|
1431
|
+
},
|
|
1432
|
+
"allOf": [{
|
|
1433
|
+
"if": {"properties": {"status": {"const": "authorized"}}, "required": ["status"]},
|
|
1434
|
+
"then": {"properties": {"source": {"type": "string", "minLength": 1}, "granted_at": {"type": "string", "minLength": 1}}}
|
|
1435
|
+
}],
|
|
1436
|
+
"additionalProperties": false
|
|
1517
1437
|
},
|
|
1518
|
-
"
|
|
1519
|
-
"type": "
|
|
1438
|
+
"authorization": {
|
|
1439
|
+
"type": "object",
|
|
1440
|
+
"required": ["implementation_commit", "local_candidate_integration", "source_cleanup"],
|
|
1441
|
+
"properties": {
|
|
1442
|
+
"implementation_commit": {"$ref": "#/$defs/authorization-entry"},
|
|
1443
|
+
"local_candidate_integration": {"$ref": "#/$defs/authorization-entry"},
|
|
1444
|
+
"source_cleanup": {"$ref": "#/$defs/authorization-entry"}
|
|
1445
|
+
},
|
|
1446
|
+
"additionalProperties": false
|
|
1520
1447
|
},
|
|
1521
|
-
"
|
|
1522
|
-
"
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
},
|
|
1526
|
-
{
|
|
1527
|
-
|
|
1528
|
-
|
|
1529
|
-
|
|
1530
|
-
|
|
1448
|
+
"leadership-history": {
|
|
1449
|
+
"type": "object",
|
|
1450
|
+
"required": ["owner", "epoch", "assigned_at", "ended_at"],
|
|
1451
|
+
"properties": {
|
|
1452
|
+
"owner": {"type": "string", "minLength": 1},
|
|
1453
|
+
"epoch": {"type": "integer", "minimum": 1},
|
|
1454
|
+
"assigned_at": {"type": "string", "minLength": 1},
|
|
1455
|
+
"ended_at": {"type": "string", "minLength": 1}
|
|
1456
|
+
},
|
|
1457
|
+
"additionalProperties": false
|
|
1531
1458
|
},
|
|
1532
|
-
"
|
|
1533
|
-
"type": "
|
|
1534
|
-
"
|
|
1535
|
-
|
|
1536
|
-
|
|
1459
|
+
"leadership": {
|
|
1460
|
+
"type": "object",
|
|
1461
|
+
"required": ["current", "epoch", "assigned_at", "history"],
|
|
1462
|
+
"properties": {
|
|
1463
|
+
"current": {"type": "string", "minLength": 1},
|
|
1464
|
+
"epoch": {"type": "integer", "minimum": 1},
|
|
1465
|
+
"assigned_at": {"type": "string", "minLength": 1},
|
|
1466
|
+
"history": {"type": "array", "items": {"$ref": "#/$defs/leadership-history"}}
|
|
1467
|
+
},
|
|
1468
|
+
"additionalProperties": false
|
|
1537
1469
|
},
|
|
1538
|
-
"
|
|
1539
|
-
"type": "
|
|
1540
|
-
"
|
|
1541
|
-
|
|
1542
|
-
|
|
1470
|
+
"full-suite": {
|
|
1471
|
+
"type": "object",
|
|
1472
|
+
"required": ["required", "status", "reason", "evidence"],
|
|
1473
|
+
"properties": {
|
|
1474
|
+
"required": {"type": "boolean"},
|
|
1475
|
+
"status": {"enum": ["not-required", "pending", "passed", "failed"]},
|
|
1476
|
+
"reason": {"type": ["string", "null"]},
|
|
1477
|
+
"evidence": {"type": ["string", "null"]}
|
|
1478
|
+
},
|
|
1479
|
+
"allOf": [{
|
|
1480
|
+
"if": {"properties": {"required": {"const": false}}, "required": ["required"]},
|
|
1481
|
+
"then": {"properties": {"status": {"const": "not-required"}, "reason": {"type": "string", "minLength": 1}}}
|
|
1482
|
+
}],
|
|
1483
|
+
"additionalProperties": false
|
|
1543
1484
|
},
|
|
1544
|
-
"
|
|
1545
|
-
"type": "
|
|
1546
|
-
"
|
|
1547
|
-
|
|
1548
|
-
"
|
|
1549
|
-
|
|
1550
|
-
|
|
1551
|
-
|
|
1552
|
-
|
|
1553
|
-
|
|
1554
|
-
|
|
1555
|
-
|
|
1556
|
-
|
|
1557
|
-
],
|
|
1558
|
-
"
|
|
1559
|
-
|
|
1560
|
-
|
|
1561
|
-
"pattern": "^T-[0-9]{2,}$"
|
|
1562
|
-
},
|
|
1563
|
-
"owner": {
|
|
1564
|
-
"type": "string",
|
|
1565
|
-
"minLength": 1
|
|
1566
|
-
},
|
|
1567
|
-
"provider": {
|
|
1568
|
-
"enum": [
|
|
1569
|
-
"native",
|
|
1570
|
-
"git",
|
|
1571
|
-
"external"
|
|
1572
|
-
]
|
|
1573
|
-
},
|
|
1574
|
-
"base_sha": {
|
|
1575
|
-
"type": "string",
|
|
1576
|
-
"minLength": 1
|
|
1577
|
-
},
|
|
1578
|
-
"branch": {
|
|
1579
|
-
"type": "string",
|
|
1580
|
-
"minLength": 1
|
|
1581
|
-
},
|
|
1582
|
-
"workspace_ref": {
|
|
1583
|
-
"type": "string",
|
|
1584
|
-
"minLength": 1,
|
|
1585
|
-
"pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
|
|
1586
|
-
},
|
|
1587
|
-
"status": {
|
|
1588
|
-
"enum": [
|
|
1589
|
-
"planned",
|
|
1590
|
-
"active",
|
|
1591
|
-
"review",
|
|
1592
|
-
"integrated",
|
|
1593
|
-
"removed",
|
|
1594
|
-
"blocked"
|
|
1595
|
-
]
|
|
1596
|
-
},
|
|
1597
|
-
"updated_at": {
|
|
1598
|
-
"type": "string",
|
|
1599
|
-
"minLength": 1
|
|
1600
|
-
}
|
|
1601
|
-
},
|
|
1602
|
-
"additionalProperties": true
|
|
1603
|
-
}
|
|
1604
|
-
}
|
|
1605
|
-
},
|
|
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
|
-
}
|
|
1485
|
+
"worktree": {
|
|
1486
|
+
"type": "object",
|
|
1487
|
+
"required": ["ticket_id", "owner", "implementation_owner", "integration_owner", "provider", "base_sha", "parent_branch", "branch", "workspace_ref", "source_checkpoint", "integration", "status", "updated_at"],
|
|
1488
|
+
"properties": {
|
|
1489
|
+
"ticket_id": {"type": "string", "pattern": "^T-[0-9]{2,}$"},
|
|
1490
|
+
"owner": {"type": "string", "minLength": 1},
|
|
1491
|
+
"implementation_owner": {"type": "string", "minLength": 1},
|
|
1492
|
+
"integration_owner": {"type": "string", "minLength": 1},
|
|
1493
|
+
"provider": {"const": "git"},
|
|
1494
|
+
"base_sha": {"type": "string", "minLength": 1},
|
|
1495
|
+
"parent_branch": {"type": "string", "minLength": 1},
|
|
1496
|
+
"branch": {"type": "string", "minLength": 1},
|
|
1497
|
+
"workspace_ref": {"type": "string", "pattern": "^specdev-worktree/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*/T-[0-9]{2,}$"},
|
|
1498
|
+
"source_checkpoint": {"type": ["string", "null"]},
|
|
1499
|
+
"integration": {"$ref": "#/$defs/integration"},
|
|
1500
|
+
"status": {"enum": ["planned", "active", "review", "integrating", "integrated", "removed", "blocked"]},
|
|
1501
|
+
"updated_at": {"type": "string", "minLength": 1}
|
|
1623
1502
|
},
|
|
1624
|
-
"
|
|
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
|
-
}
|
|
1503
|
+
"additionalProperties": false
|
|
1649
1504
|
},
|
|
1650
|
-
{
|
|
1651
|
-
"
|
|
1652
|
-
|
|
1653
|
-
|
|
1654
|
-
|
|
1655
|
-
|
|
1656
|
-
}
|
|
1505
|
+
"integration": {
|
|
1506
|
+
"type": "object",
|
|
1507
|
+
"required": ["status", "parent_ref", "parent_before_sha", "source_sha", "candidate_sha", "candidate_tree_sha", "candidate_branch", "candidate_workspace_ref", "result_sha", "method", "conflict_paths", "verification", "full_suite", "e2e", "evidence", "attempts", "promotion_status"],
|
|
1508
|
+
"properties": {
|
|
1509
|
+
"status": {"enum": ["pending", "candidate", "passed", "failed", "stale"]},
|
|
1510
|
+
"parent_ref": {"type": ["string", "null"]},
|
|
1511
|
+
"parent_before_sha": {"type": ["string", "null"]},
|
|
1512
|
+
"source_sha": {"type": ["string", "null"]},
|
|
1513
|
+
"candidate_sha": {"type": ["string", "null"]},
|
|
1514
|
+
"candidate_tree_sha": {"type": ["string", "null"]},
|
|
1515
|
+
"candidate_branch": {"type": ["string", "null"]},
|
|
1516
|
+
"candidate_workspace_ref": {"anyOf": [{"type": "null"}, {"type": "string", "pattern": "^specdev-worktree/\\.integration/[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*/T-[0-9]{2,}$"}]},
|
|
1517
|
+
"result_sha": {"type": ["string", "null"]},
|
|
1518
|
+
"method": {"enum": [null, "fast-forward", "merge-commit"]},
|
|
1519
|
+
"conflict_paths": {"type": "array", "items": {"type": "string"}},
|
|
1520
|
+
"verification": {"enum": ["pending", "passed", "failed"]},
|
|
1521
|
+
"full_suite": {"$ref": "#/$defs/full-suite"},
|
|
1522
|
+
"e2e": {"$ref": "#/$defs/full-suite"},
|
|
1523
|
+
"evidence": {"type": "string", "pattern": "^\\{roots\\.state\\}/specdev/changes/[^<]+/evidence/T-[0-9]{2,}\\.md$"},
|
|
1524
|
+
"attempts": {"type": "integer", "minimum": 0},
|
|
1525
|
+
"promotion_status": {"enum": ["pending", "applying", "applied", "failed", "stale"]}
|
|
1657
1526
|
},
|
|
1658
|
-
"
|
|
1659
|
-
"properties": {
|
|
1660
|
-
"archived": {
|
|
1661
|
-
"const": true
|
|
1662
|
-
},
|
|
1663
|
-
"archive_path": {
|
|
1664
|
-
"type": "string",
|
|
1665
|
-
"pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"
|
|
1666
|
-
}
|
|
1667
|
-
}
|
|
1668
|
-
}
|
|
1527
|
+
"additionalProperties": false
|
|
1669
1528
|
}
|
|
1670
|
-
|
|
1671
|
-
"
|
|
1529
|
+
},
|
|
1530
|
+
"allOf": [{
|
|
1531
|
+
"if": {"properties": {"change_status": {"const": "archived"}}, "required": ["change_status"]},
|
|
1532
|
+
"then": {"properties": {"archived": {"const": true}, "archive_path": {"type": "string", "pattern": "^specdev/archive/[0-9]{4}-[0-9]{2}/.+/$"}}}
|
|
1533
|
+
}],
|
|
1534
|
+
"additionalProperties": false
|
|
1672
1535
|
}
|
|
1673
1536
|
```
|
|
1674
1537
|
|
|
@@ -1679,24 +1542,42 @@ Manifest 至少记录 repository、branch、checkpoint、工作区状态、包 l
|
|
|
1679
1542
|
```json
|
|
1680
1543
|
{
|
|
1681
1544
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
1682
|
-
"$id": "urn:speculo:specdev:goal-plan:
|
|
1545
|
+
"$id": "urn:speculo:specdev:goal-plan:v5",
|
|
1683
1546
|
"title": "SpecDev Goal Plan Frontmatter",
|
|
1684
1547
|
"type": "object",
|
|
1685
|
-
"required": [
|
|
1548
|
+
"required": [
|
|
1549
|
+
"schema_version", "artifact", "change", "status", "modes", "orchestration",
|
|
1550
|
+
"lead", "implementation_agent_limit", "ticket_workspace_policy", "integration_gate",
|
|
1551
|
+
"ready_for_execution"
|
|
1552
|
+
],
|
|
1686
1553
|
"properties": {
|
|
1687
|
-
"schema_version": {"const":
|
|
1554
|
+
"schema_version": {"const": 5},
|
|
1688
1555
|
"artifact": {"const": "goal-plan"},
|
|
1689
1556
|
"change": {"type": "string", "minLength": 1},
|
|
1690
1557
|
"status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]},
|
|
1691
1558
|
"modes": {
|
|
1692
1559
|
"type": "array",
|
|
1693
|
-
"items": {"enum": ["
|
|
1694
|
-
"minItems": 1,
|
|
1560
|
+
"items": {"enum": ["migration", "high-assurance", "reference-conformance", "release-coordination"]},
|
|
1695
1561
|
"uniqueItems": true
|
|
1696
1562
|
},
|
|
1563
|
+
"orchestration": {"const": "lead-directed"},
|
|
1564
|
+
"lead": {"type": "string", "minLength": 1},
|
|
1565
|
+
"implementation_agent_limit": {"type": "integer", "minimum": 1, "maximum": 3},
|
|
1566
|
+
"ticket_workspace_policy": {"const": "required"},
|
|
1567
|
+
"integration_gate": {"const": "candidate-merge"},
|
|
1697
1568
|
"ready_for_execution": {"type": "boolean"}
|
|
1698
1569
|
},
|
|
1699
|
-
"
|
|
1570
|
+
"allOf": [
|
|
1571
|
+
{
|
|
1572
|
+
"if": {"properties": {"status": {"enum": ["draft", "blocked", "completed"]}}, "required": ["status"]},
|
|
1573
|
+
"then": {"properties": {"ready_for_execution": {"const": false}}}
|
|
1574
|
+
},
|
|
1575
|
+
{
|
|
1576
|
+
"if": {"properties": {"status": {"enum": ["ready", "in_progress"]}}, "required": ["status"]},
|
|
1577
|
+
"then": {"properties": {"ready_for_execution": {"const": true}}}
|
|
1578
|
+
}
|
|
1579
|
+
],
|
|
1580
|
+
"additionalProperties": false
|
|
1700
1581
|
}
|
|
1701
1582
|
```
|
|
1702
1583
|
|