flow-comet 1.6.5 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +32 -18
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +2 -2
- package/.flow-comet/skills/flow-comet/reference/decision-points.md +5 -5
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +30 -11
- package/.flow-comet/skills/flow-comet/reference/fix-loop.md +4 -4
- package/.flow-comet/skills/flow-comet/reference/init-detection.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/platform-facts.md +2 -2
- package/.flow-comet/skills/flow-comet/reference/post-archive-handoff.md +264 -0
- package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/replan.md +1 -1
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +1 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +270 -30
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +122 -11
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +79 -40
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +11 -9
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
- package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +128 -56
- package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +357 -3
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +26 -1
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +6 -2
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +29 -21
- package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +4 -15
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +357 -219
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +725 -309
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +182 -54
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +224 -83
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +17 -28
- package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +61 -33
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +663 -205
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +68 -9
- package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +11 -4
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +232 -11
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +140 -74
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +8 -4
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
- package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +0 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +248 -24
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +63 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +181 -8
- package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +340 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +132 -20
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +12 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1564 -54
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1489 -38
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1466 -243
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +743 -24
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +220 -92
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +657 -21
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +41 -27
- package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +285 -9
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +7 -6
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +21 -15
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +8 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +45 -36
- package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2381 -85
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -2
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +339 -103
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +33 -11
- package/.flow-comet/skills/flow-comet-change/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +5 -3
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +37 -13
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +10 -4
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +13 -6
- package/.flow-comet/skills/flow-comet-review/SKILL.md +21 -12
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +43 -18
- package/.flow-comet/skills/flow-comet-task/SKILL.md +4 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +1 -1
- package/README.md +2 -2
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +238 -21
|
@@ -4,6 +4,9 @@
|
|
|
4
4
|
import path from 'path';
|
|
5
5
|
import { fileURLToPath } from 'url';
|
|
6
6
|
import { resolveProtocol, readProtocolFile, validateProtocolSchema } from './protocol-utils.mjs';
|
|
7
|
+
// 运行根(本次调用把哪个目录当项目根)由 lib/run-root.mjs 单源解析:与守卫族同一份事实——
|
|
8
|
+
// 各写一份 env/cwd 推导,同一个调用两侧就会给出不同答案(详见该模块头注释)。
|
|
9
|
+
import { resolveRunRoot } from './lib/run-root.mjs';
|
|
7
10
|
import { initStateContext } from './lib/state-io.mjs';
|
|
8
11
|
import { runAdvance, runInit, runNext, runRecord, runSelect, runStatus } from './lib/state-commands-flow.mjs';
|
|
9
12
|
import { runConfig, runExecutionMode, runSkillLoad, runVerifyFail } from './lib/state-commands-admin.mjs';
|
|
@@ -14,9 +17,9 @@ import { runExplain } from './lib/state-explain.mjs';
|
|
|
14
17
|
const command = process.argv[2] ?? 'status';
|
|
15
18
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
16
19
|
const packageRoot = path.resolve(__dirname, '..');
|
|
17
|
-
const runRoot =
|
|
20
|
+
const runRoot = resolveRunRoot();
|
|
18
21
|
// 路径上下文(runRoot / specsRoot / statePath)在分派前初始化一次——状态的读写与 .specs 路径
|
|
19
|
-
// 判定统一由 lib/state-io.mjs
|
|
22
|
+
// 判定统一由 lib/state-io.mjs 承担;运行根本身由 lib/run-root.mjs 单源解析。
|
|
20
23
|
initStateContext(runRoot);
|
|
21
24
|
// 协议解析: 协议路径统一由 resolveProtocol 解析——优先级:--protocol CLI 参数 → FLOW_COMET_PROTOCOL
|
|
22
25
|
// 环境变量 → 内置默认 reference/workflow-protocol.json。--protocol 为全局参数(可放在 command
|
|
@@ -28,6 +28,8 @@ This node finalizes a completed change by extracting reusable lessons from the d
|
|
|
28
28
|
|
|
29
29
|
### Steps
|
|
30
30
|
|
|
31
|
+
> **硬规则(先于任何动作)**:进入本节点后,**先用 Skill 工具加载** `flow-comet-integration`,并**立即**运行下节 Required Skill Calls 的 `skill-load` 命令写下声明标记——**技能加载声明必须先于任何动作,尤其先于搬目录**。移动目录之后补声明 / 补记录仍可完成(引擎按状态判身份、按解析到的目录读写标记),但那只是**兼容 / 恢复路径**;规范顺序永远是**先记录、后搬目录**。
|
|
32
|
+
|
|
31
33
|
1. **Scan SUMMARY.md files for lessons**: Read all `<task-id>-SUMMARY.md` files in `.specs/<change-id>/`. Focus on "decisions and deviations" sections. Also check any remaining `<task-id>-PROGRESS.md` "excluded solutions" sections.
|
|
32
34
|
|
|
33
35
|
2. **Apply nomination criteria**: 三条判据(含「其余一律不提名」兜底)见 `flow-comet-integration` 册的「LESSONS 提名」段——该段是判据的**单一权威**,本册不复述、以该册为准。
|
|
@@ -44,19 +46,22 @@ This node finalizes a completed change by extracting reusable lessons from the d
|
|
|
44
46
|
- Write `.specs/<change-id>/KNOWN-ISSUES.md` — each entry: issue description, why it was deferred, and where it may surface again.
|
|
45
47
|
- The file moves with the change into `.specs/archive/<YYYY-MM-DD>-<change-id>/` (archived alongside the other artifacts), so the leftover issues never silently vanish after archive.
|
|
46
48
|
- If there are no leftovers, still state that explicitly in the file (e.g. "无遗留问题" / "No known leftover issues").
|
|
49
|
+
- **本步必须在搬目录之前完成**:工件随目录一起归档,搬完再补只是恢复路径(与上方硬规则的「先记录、后搬目录」同一条顺序纪律)。
|
|
50
|
+
|
|
51
|
+
6. **Record evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` to record archive completion——**记录是搬目录之前的最后一件证据动作**(LESSONS 提名与遗留清单都已就位);搬目录之后补记录只是兼容 / 恢复路径,不是规范顺序。
|
|
47
52
|
|
|
48
|
-
|
|
53
|
+
7. **Move change to archive**: After user confirmation——**搬目录是本节点唯一的不可逆动作,声明与记录都已就位后才执行**:
|
|
49
54
|
- Move `.specs/<change-id>/` to `.specs/archive/<YYYY-MM-DD>-<change-id>/`.
|
|
50
55
|
- Date format: YYYY-MM-DD of the archive date.
|
|
51
56
|
- Verify the move completed successfully (source no longer exists, destination has all files).
|
|
52
57
|
- **git 索引同步**:移动含 `.skill-loads/` 等隐藏目录时,用 `git mv` 逐项移动或移动后用 `git add -A .specs/` 同步索引——文件系统 `mv` 后 git 索引不同步,`git checkout` 会从树恢复残留文件(实测:归档后 checkout 恢复 9 个 .skill-loads 源路径文件)。
|
|
53
58
|
|
|
54
|
-
|
|
59
|
+
8. **Update CHANGELOG.md**: 在 `.specs/CHANGELOG.md` **顶部**按日期倒序插入新条目(倒序约定:新条目永远在最新日期行之上;文件不存在则从模板创建)。若项目既有 CHANGELOG 采用其他格式(如 `## 日期 + 列表`),**跟随项目既有格式**在顶部插入(不强制转表格——保持仓库一致性;guard 的倒序检测只针对表格格式行):
|
|
55
60
|
- 表格格式: `| YYYY-MM-DD | <change-id> | one-line summary | PR link | new L-NNN entries |`
|
|
56
61
|
|
|
57
|
-
|
|
62
|
+
9. **Update STATE.md(可选决策日志)**: 若项目维护 `STATE.md`,新决策日志条目**顶部**插入(倒序约定,**禁止文件尾追加**)。flow-comet 的活动 change 状态由 `.flow-comet/flow-comet-state.json` 管理——STATE.md 无 active change 字段,不需要也不应手动清除。
|
|
58
63
|
|
|
59
|
-
|
|
64
|
+
10. **Notify user of architecture sedimentation + leftover issues**: Check DESIGN.md section 9 for sedimentation suggestions. If N > 0 suggestions exist, tell user — and always explicitly enumerate the leftover issues from KNOWN-ISSUES.md in the archive notification (they must not silently disappear after archive):
|
|
60
65
|
```
|
|
61
66
|
Archived to .specs/archive/<YYYY-MM-DD>-<change-id>/
|
|
62
67
|
遗留问题清单(KNOWN-ISSUES.md,随工件归档): <each leftover issue, or 无>
|
|
@@ -64,16 +69,14 @@ This node finalizes a completed change by extracting reusable lessons from the d
|
|
|
64
69
|
Recommended: run A-evolve workflow after >= 5 个带 `§9` 的归档 change,或距上次沉淀 > 60 天(阈值与入口册 `EVOLVE-DUE` 提示同口径)——批量 review 后 patch CONTEXT.md。
|
|
65
70
|
```
|
|
66
71
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
11. **Exit check**: Run exit check.
|
|
72
|
+
11. **Exit check**: Run exit check——搬目录仍是 `exit` 的前置:归档目录不在场时出口的产物门会直接拦下;登记与通知的措辞也一律按归档后的位置写。
|
|
70
73
|
|
|
71
74
|
### 归档后发现缺陷(受控重入)
|
|
72
75
|
|
|
73
76
|
归档已 entry 但归档移动尚未发生(`.specs/<change-id>/` 仍在原位、`status !== 'completed'`)时,review / verify / 执行阶段发现的新缺陷**不得**在归档阶段就地修完——工作归属须先受控归位回既有生命周期,再按修复回路收口。要点:
|
|
74
77
|
|
|
75
78
|
- **未移动** → 受控重入:由用户显式授权后运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text>`——目标限 `execute` / `subagent-execute` / `review` / `verify` 之一;每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`,n ≥ 已用轮次 + 1);命令先自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`),再转移工作归属;缺授权、目标越界、超上限或归档移动已发生一律 BLOCKED(state 字节零改写),不会静默跳过。
|
|
76
|
-
- **已移动 / 已合并** →
|
|
79
|
+
- **已移动 / 已合并** → 人工处置或另开 change:归档移动已发生(`.specs/archive/<日期>-<change-id>/`)或 change 已 `completed` / 已合并时,受控重入不适用(不承诺把文件搬回原位);走人工处置,或把修复放进另一个 change / hotfix,并在遗留清单里登记指针。
|
|
77
80
|
- **写权限顺序(先转移后写 TASK)**:先跑 `reenter` 完成转移(写入权限随即跟随目标节点),再在目标节点权限内追加 Fix 任务 / 修改工件;archive 阶段 hook 对 change 目录只放行 `KNOWN-ISSUES.md` 这一个精确文件(另有 `.specs/archive/`、`.specs/CHANGELOG.md`、`.specs/LESSONS.md`、`STATE.md`),**不要试图在归档阶段先写 TASK.md**。
|
|
78
81
|
- **回源路径不因归档而放宽**:修复回路本身不变——回到 `execute` 生命周期时照样跑完四类出口,随后**回源节点跑出口**(`entry <源节点>` → `exit <源节点> --apply`);受控重入只改工作归属,不写任何闭合标记,也**禁止绕过**目标节点入口 / 出口与源节点出口门禁。
|
|
79
82
|
|
|
@@ -177,7 +180,7 @@ Evidence: `archive-summary` (required)
|
|
|
177
180
|
## Evidence Record
|
|
178
181
|
|
|
179
182
|
```bash
|
|
180
|
-
node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summary":"
|
|
183
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summary":"Archive evidence prepared before the move: N lessons nominated, leftover list compiled; directory move and CHANGELOG registration follow"}'
|
|
181
184
|
```
|
|
182
185
|
|
|
183
186
|
## Guardrails
|
|
@@ -185,7 +188,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summ
|
|
|
185
188
|
| Guardrail ID | Label | Validation Type |
|
|
186
189
|
|--------------|-------|-----------------|
|
|
187
190
|
| `archive-evidence` | Archive directory exists, source removed | state-transition |
|
|
188
|
-
| `changelog-updated` | CHANGELOG.md 有新条目,且表格条目按日期倒序 | 结构级(guard 强制:`CHANGELOG.md`
|
|
191
|
+
| `changelog-updated` | CHANGELOG.md 有新条目,且表格条目按日期倒序 | 结构级(guard 强制:`CHANGELOG.md` 表格日期倒序——非倒序即 BLOCKED;未含本 change 标识只 WARN 提示补登记);条目内容与格式由 review 把关 |
|
|
189
192
|
| `lessons-preserved` | LESSONS.md still in .specs/ (not archived) | 执行纪律(review 把关),guard 不校验 |
|
|
190
193
|
| `user-confirmed` | User confirmed archive before execution | 执行纪律(review 把关),guard 不校验 |
|
|
191
194
|
|
|
@@ -195,7 +198,26 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summ
|
|
|
195
198
|
node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit archive --apply
|
|
196
199
|
```
|
|
197
200
|
|
|
198
|
-
If the script prints `NEXT: done`, summarize the workflow evidence and stop. The change is complete.
|
|
201
|
+
If the script prints `NEXT: done`, run the 「归档完成后的交接」 section below first, then summarize the workflow evidence and stop. The change is complete.
|
|
202
|
+
|
|
203
|
+
### 归档完成后的交接(Known-Issue 后续处理)
|
|
204
|
+
|
|
205
|
+
**触发**:`exit archive --apply` 打印 `NEXT: done`、状态已变为 `completed` 之后才进入本段。归档在此之前已经闭合——**本段不阻断归档**:不重跑出口、不改出口判据、不改变 `entry → record → move → exit` 的顺序;用户选择稍后处理或直接跳过,归档结果同样成立。
|
|
206
|
+
|
|
207
|
+
**顺序**(逐条执行,不跳步、不调换):
|
|
208
|
+
|
|
209
|
+
1. **读当前分支与工作区状态**——只用于向用户报告(当前分支名、未提交改动);**不做任何分支操作**:不 merge、不 checkout、不删除分支、不 push。
|
|
210
|
+
2. **读归档的遗留清单**——`.specs/archive/<YYYY-MM-DD>-<change-id>/KNOWN-ISSUES.md`,逐条整体读、不是只数条数;文件写明无遗留问题时如实报告,可就此结束。
|
|
211
|
+
3. **探测载体**——只读探测:是否 git 工作树、`origin` 的 host 分类、`gh` / `glab` 是否在场及认证状态、本地 roadmap 是否存在与其形式。
|
|
212
|
+
4. **一次询问**——带着探测摘要与推荐,用结构化提问工具问一次(平台没有该工具时退回文本提问),问的是**载体**(范围只限载体本身);**载体只问一次**(粒度选择、是否提交、是否转入是各自独立的确认,不算追问),之后不再为载体追问第二遍。
|
|
213
|
+
5. **完整展示**——把将要创建或写入的全部内容完整呈现给用户(过长可分批,但不得截断、不得用摘要代替)。
|
|
214
|
+
6. **选择**——用户选定之后才进入执行;未选定不动任何远端或本地文件。
|
|
215
|
+
7. **执行**——按用户选择创建 issue、写入本地 roadmap,或输出草稿与可复制命令。
|
|
216
|
+
8. **报告**——逐条给出成功 / 跳过 / 失败原因与草稿位置,并说明遗留清单最终落在何处。本地写入时**另**按参考页「提交(仅本地写入)」节处理:先 `git check-ignore` 判定可达提交面,未被忽略则展示路径与当前分支、问一次是否提交(这一问同样不是对载体那一问的追问)。
|
|
217
|
+
|
|
218
|
+
**边界**:不写 `.flow-comet/flow-comet-state.json`;不修改归档的 `KNOWN-ISSUES.md`;不自动提交、不关闭 issue;本段全程不做任何分支操作。
|
|
219
|
+
|
|
220
|
+
**归档完成后要执行交接时**读 `../flow-comet/reference/post-archive-handoff.md`(触发与顺序、探测命令序列、四选项询问、载体决策表、公开草稿骨架、降级路径与操作矩阵)。
|
|
199
221
|
|
|
200
222
|
## Recovery
|
|
201
223
|
|
|
@@ -36,7 +36,7 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
|
|
|
36
36
|
|
|
37
37
|
- **判据与强制等级(唯一权威)**:判据全文与 `guarded` 绑定、`required-skill:design.flow-comet-ui-design` 声明要求、非前端 `UI-DESIGN: skipped(非前端)` 的出口口径都在 `flow-comet-ui-design` 册的「触发与跳过」段——本节不复述,只描述怎么填段。
|
|
38
38
|
- **前端项目**:按步骤 0.6 的预选结果填段(选定 / 理由 / 参考产品 / 明确排除),不要以结构形态标注「不适用」。
|
|
39
|
-
- **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI
|
|
39
|
+
- **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI 工具,无用户可见界面」)。**段缺席不再默认判非前端**——新建 change 的「视觉调性」是标题必须在场的条件段,**缺席即拦**(open 出口的骨架校验与 design 出口的适用性门控都会拦);缺席不保留兼容侧——同一形态一个判级(段缺席一律拦,须显式标注「不适用」或填写调性)。
|
|
40
40
|
- **改判走本阶段**:change 进行中要改前端 / 非前端判定,回到这里改这一个段,不在 design / execute / verify 里就地绕开判据——改段即改变了 design 出口的判据输入。
|
|
41
41
|
|
|
42
42
|
## 状态推进
|
|
@@ -114,11 +114,11 @@ The design node reads CHANGE.md and REQUIREMENT.md, then produces DESIGN.md thro
|
|
|
114
114
|
|
|
115
115
|
| Skill | Enforcement | Reason |
|
|
116
116
|
|-------|-------------|--------|
|
|
117
|
-
| `flow-comet-ui-design` | Guarded(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——前端 change 须先 `skill-load` 建标记并在 record 载荷带 `required-skill:design.flow-comet-ui-design
|
|
117
|
+
| `flow-comet-ui-design` | Guarded(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——前端 change 须先 `skill-load` 建标记并在 record 载荷带 `required-skill:design.flow-comet-ui-design`(声明标记只能由执行者手动 `skill-load` 写入,引擎不代记);非前端项目不加载不声明;缺件一律拦截(同一形态一个判级) |
|
|
118
118
|
|
|
119
119
|
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
120
120
|
|
|
121
|
-
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为 **guarded 但仅前端适用**的条目——前端项目用 Skill 工具加载其已装副本后**必须**运行对应 `skill-load` 声明建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端项目不加载不声明(出口打印可见的 `UI-DESIGN: skipped(非前端)`
|
|
121
|
+
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为 **guarded 但仅前端适用**的条目——前端项目用 Skill 工具加载其已装副本后**必须**运行对应 `skill-load` 声明建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端项目不加载不声明(出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行);缺件一律拦截(同一形态一个判级)。
|
|
122
122
|
|
|
123
123
|
> **前端判据(结构级 · 唯一权威 → `flow-comet-ui-design` 册的「触发与跳过」段)**:判据全文与 `guarded` 绑定的判级口径都在该册——本节不复述,判定与出口行为一律以该册为准。
|
|
124
124
|
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板:`design` 的必填模板是 `DESIGN.md`;**前端 change 另加 `UI-DESIGN.md` 时写成 `--templates DESIGN.md,UI-DESIGN.md`**(`UI-DESIGN` 属可选声明,非前端不加):
|
|
@@ -145,6 +145,8 @@ Evidence: `design-summary` (required)
|
|
|
145
145
|
|
|
146
146
|
```bash
|
|
147
147
|
node .claude/skills/flow-comet/scripts/workflow-state.mjs record design '{"summary":"DESIGN.md produced with tech stack, architecture alignment, ADRs, risks"}'
|
|
148
|
+
# frontend change: add "required-skill:design.flow-comet-ui-design" to an evidence payload, e.g.
|
|
149
|
+
# ... record design '{"summary":"...","completedChecks":["required-skill:design.flow-comet-ui-design"]}'
|
|
148
150
|
```
|
|
149
151
|
|
|
150
152
|
## Guardrails
|
|
@@ -153,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record design '{"summa
|
|
|
153
155
|
|--------------|-------|-----------------|
|
|
154
156
|
| `design-artifacts` | DESIGN.md (or DESIGN-lite.md) exists with section 0 | artifact-exists |
|
|
155
157
|
| `architecture-aligned` | Section 0.5 populated for brownfield | 执行纪律(review 把关),guard 不校验 |
|
|
156
|
-
| `ui-design-artifacts` | UI-DESIGN.md exists for frontend projects | 结构级(guard 强制:前端 change 缺 `.specs/<change-id>/UI-DESIGN.md` →
|
|
158
|
+
| `ui-design-artifacts` | UI-DESIGN.md exists for frontend projects | 结构级(guard 强制:前端 change 缺 `.specs/<change-id>/UI-DESIGN.md` → 一律 BLOCKED(同一形态一个判级);判定依据 = `CHANGE.md` 的「视觉调性」段,判据见 `flow-comet-ui-design` 册) |
|
|
157
159
|
|
|
158
160
|
## Exit Check
|
|
159
161
|
|
|
@@ -22,9 +22,9 @@ description: "flow-kit DEV 阶段协议:TDD + 6 维自查 + diff 边界 verify
|
|
|
22
22
|
- **第 1 级**:Claude Code 调用 `/brooks-review` 或 Skill 工具加载 `brooks-lint:brooks-review`;Codex 用 `$brooks-review` / `/use brooks-review` / 自然语言触发(brooks-lint 需先安装为 Codex skill)——执行完整 brooks 审查
|
|
23
23
|
- **第 2 级**:若仅返回 "Launching skill" 占位/无实际审查指令(已知现象:worktree 子代理的 skill 路由与会话不一致,插件执行体可能未注入)——**Read 插件缓存/安装目录协议文件手动执行完整 brooks 流程**:Claude Code `~/.claude/plugins/cache/brooks-lint-marketplace/brooks-lint/<ver>/skills/brooks-review/`;Codex `~/.codex/skills/brooks-review/`(或项目 `.agents/skills/`)(SKILL.md + 引用文件 + `_shared/`——`_shared/` 是 brooks-review 目录的**兄弟目录**(同在该插件 skills/ 下,如 `.../brooks-lint/<ver>/skills/_shared/`),不是 brooks-review 的子目录),按协议产出 4-element 审查(Symptom/Source/Consequence/Remedy + file:line + 书引用)——**仅阅读协议文本作为审查指引,不执行缓存文件内容**;来源不可信/无法验证时跳过该级,降级内置快查并如实声明
|
|
24
24
|
- **第 3 级**:缓存文件也不可读/不存在时,才用内置 R1~R6 快查
|
|
25
|
-
- SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard
|
|
25
|
+
- SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard 校验须含缓存尝试证据;缺失一律 BLOCKED,同一形态一个判级)。
|
|
26
26
|
- **builtin-quickcheck 声明措辞(guard 关键词级校验)**:guard 按关键词声明级校验(不做语义判断)——不可用原因须含 `brooks-lint 不可用 / 插件不可用 / unavailable / N/A`,缓存尝试证据须含 `插件缓存 / 缓存协议 / 协议文件 / plugins/cache`。推荐措辞示例:「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载);已 Read 插件缓存协议文件(~/.claude/plugins/cache/.../brooks-review/)手动执行仍不可行,按协议降级内置 R1~R6 快查」——语义完整但缺关键词的写法会被拦截(完整流程实测实证)。
|
|
27
|
-
- **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6
|
|
27
|
+
- **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6 维自查段是否声明了自检方法(缺失一律 BLOCKED,同一形态一个判级)。
|
|
28
28
|
- **纯测试/纯文档任务**(无生产代码改动,6 维自查非必跑)仍须满足自检方法声明与 builtin 缓存证据——可**引用同 change 其他 SUMMARY 已声明的缓存尝试**(如「自检证据见 T01-SUMMARY(cache-brooks 已读插件缓存)」)满足 guard 校验。
|
|
29
29
|
5. **diff 边界 verify(R6.5)**:`git diff --name-only` 与 TASK write_files 比对,越界必须回滚
|
|
30
30
|
6. **原子提交**:`<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁止把 change-id/日期/任务号作 scope)
|
|
@@ -21,7 +21,7 @@ In subagent mode (default) this node is a coordinator: it does not write impleme
|
|
|
21
21
|
|------|------|------|
|
|
22
22
|
| `SUMMARY.md` | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出(必填)` / `## 6 维自查`(须含实质内容)/ `## 越界检查(必填)` / `## 是否触发新工作` / `## 完成判定`;首部四字段 `Change ID` / `Task ID` / `完成时间` / `AI 角色` 必填 | **条件段**:`## 数据库迁移(涉及 schema 变更必填 · 来自 4-dev 步骤 1.7 / R4.5)` / `## 破坏性变更(涉及破坏性改动必填 · 来自 4-dev 步骤 1.8 / R4.6 / B4 老项目护栏)` / `## 决策与偏离(如有)`——标题必须在场,不适用写 `N/A`;**增量段**:`## 自检方法`(整段必填,紧随 `## 越界检查` 或文末)、`## LESSONS 扫描`(整段必填,紧随 `## 自检方法`) |
|
|
23
23
|
|
|
24
|
-
> **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段(前者校验自检方法声明,后者校验开工前扫描可核对)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**:`## 自检方法` 声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一及降级证据,`## LESSONS 扫描`
|
|
24
|
+
> **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段(前者校验自检方法声明,后者校验开工前扫描可核对)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**:`## 自检方法` 声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一及降级证据,`## LESSONS 扫描` 声明命中条目与逐条回应;否则 exit 会被 BLOCKED。
|
|
25
25
|
|
|
26
26
|
guard 校验见 workflow-guard.mjs 的 execute 出口门禁(必填段 + 6 维自查实质内容 + 自检方法声明三值 + LESSONS 扫描段与命中核对)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 把关。
|
|
27
27
|
|
|
@@ -38,11 +38,29 @@ guard 校验见 workflow-guard.mjs 的 execute 出口门禁(必填段 + 6 维
|
|
|
38
38
|
|
|
39
39
|
执行模式由 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 输出(`executionMode` / `directOverride`)决定,切换用 `node .claude/skills/flow-comet/scripts/workflow-state.mjs execution-mode <subagent|direct>`。direct 是逃生口,必须用户显式调用才生效。
|
|
40
40
|
|
|
41
|
+
### 节点视图三字段(currentNode / stateCurrentNode / routeNode)
|
|
42
|
+
|
|
43
|
+
`status` 与 `next` 读的是同一份节点视图,但三个字段各说一件事,不能互相替代:
|
|
44
|
+
|
|
45
|
+
- **currentNode** = **产物推导**的节点(按 `.specs/<change-id>/` 的工件推导出「按文件看现在在哪」;语义逐字未变);
|
|
46
|
+
- **stateCurrentNode** = **state 文件原值**(`.flow-comet/flow-comet-state.json` 里 `currentNode` 的原样读数,由 entry / exit / advance / reenter 写入;语义逐字未变);
|
|
47
|
+
- **routeNode** = **路由视图**(经「进行中保护」/ Fix 受控归位后的节点;常规路径下等于 `next` 的 `NODE:` 行,决定你现在该推进哪个节点)。
|
|
48
|
+
|
|
49
|
+
三者不一致不是 bug,而是同一事实的三个视角:`ROUTE:` 行给出 `derived=… state=… route=…` 的对账(derived = 产物推导、state = state 原值、route = 路由视图)与下一步动作。**Fix 批次以 `FIX-BATCH` 行与 `next` 的 `NODE` 为准**——归位目标就是你要先跑出口的节点;预检与出口都跑在那个节点上,不要按 `stateCurrentNode` 或 `currentNode` 自行改道。
|
|
50
|
+
|
|
51
|
+
**Node view: the three fields (currentNode / stateCurrentNode / routeNode)** — `status` and `next` read the same node view, but the three fields say three different things and cannot substitute for each other:
|
|
52
|
+
|
|
53
|
+
- **currentNode** = artifact-derived (the node derived from the artifacts under `.specs/<change-id>/`, i.e. "where the files say we are"; semantics unchanged);
|
|
54
|
+
- **stateCurrentNode** = the raw state-file value (the `currentNode` read verbatim from `.flow-comet/flow-comet-state.json`, written by entry / exit / advance / reenter; semantics unchanged);
|
|
55
|
+
- **routeNode** = the routing view (after in-progress protection / controlled Fix-batch rollback; on the regular path it equals the `NODE:` line printed by `next` and decides which node you should advance now).
|
|
56
|
+
|
|
57
|
+
A mismatch is not a bug but the same fact seen from three angles: the `ROUTE:` line gives the `derived=… state=… route=…` reconciliation (derived = artifact derivation, state = raw state value, route = routing view) plus the next action. **For a Fix batch, trust the `FIX-BATCH` line and the `NODE` printed by `next`** — the rollback target is the node whose exit you must run first; run preflight and exit on that node instead of rerouting by `stateCurrentNode` or `currentNode`.
|
|
58
|
+
|
|
41
59
|
### 任务范围
|
|
42
60
|
|
|
43
61
|
execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pending 任务**。
|
|
44
62
|
|
|
45
|
-
**归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute
|
|
63
|
+
**归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute`;错误节点的请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
|
|
46
64
|
|
|
47
65
|
**TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须先经 review 流程追加到 `## Fix 任务` 段,再按下方「修复回路状态机路径」受控归位 execute,并由 entry execute 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
|
|
48
66
|
|
|
@@ -54,8 +72,8 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
54
72
|
- execute 遍历 TASK.md 时,遇到 `parallel="true" status="pending"` 的任务块应**跳过**
|
|
55
73
|
- **全 parallel 任务时 execute 不得空退出(除非显式豁免)**:guard 的 exit 校验(evidence 前置 → 串行 pending 检测 → Output Schema 产物)会 BLOCKED——「空退出」默认不可达(实测确认)。正确路径:
|
|
56
74
|
1. 正常流程下 determineNode 的 路由逻辑会**直接路由到 subagent-execute**(无需经过 execute 空退出)——协调者确认 路由逻辑生效(`NODE: subagent-execute`)后直接进入该节点
|
|
57
|
-
2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute
|
|
58
|
-
3.
|
|
75
|
+
2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute 完成属越权委托——一律 BLOCKED(同一形态一个判级)
|
|
76
|
+
3. **显式空退出豁免(须显式声明)**:确认全 parallel 无串行可做且无法路由时,用 `record execute '{"emptyExitApproved":true}'` 显式声明后 exit 通过(跳过串行 pending 与产物校验;防规划错误仍默认 BLOCKED——豁免须显式声明;exit 输出 EMPTY-EXIT 审计提示)
|
|
59
77
|
- determineNode 路由逻辑会优先检测依赖已满足的 parallel 任务并路由到 subagent-execute;若 determineNode 路由到了 execute,说明当前趟存在需要 execute 处理的串行任务(此时应执行而非空退出——**除非已显式声明空退出豁免** `emptyExitApproved`,见上条第 3 项)——串行消化完成后再次路由,剩余并行任务回到 subagent-execute 的下一趟(多趟循环直至无可并行 pending 且无串行残留)
|
|
60
78
|
|
|
61
79
|
### 并行安全四属性契约
|
|
@@ -66,7 +84,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
66
84
|
> |---|------|------|----------|
|
|
67
85
|
> | ① | **写权限** | 每个写者必须有一条被守卫认可的写入通道 | **身份分派**(CC / Codex 载荷含 `agent_id` ⇒ 子代理语义;dsh 桥接以环境变量 `FLOW_COMET_AGENT_DEPTH` 透传正整数身份深度,**并同时注入桥接通道标记 `FLOW_COMET_AGENT_DEPTH_SOURCE`——守卫要求标记与深度同时在场才接受该通道**)——**worktree 只是本属性的实现之一**,不是必须;**最小保护集除外**:身份在场时 `.flow-comet/flow-comet-state.json` 与 `../flow-comet/reference/workflow-protocol.json` 仍受拦(三平台一致 BLOCKED) |
|
|
68
86
|
> | ② | **提交隔离** | 提交只含自己 `write_files` 的字面路径 | 提交面 pathspec 纪律五要素(见 Guidance 同名小节) |
|
|
69
|
-
> | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒
|
|
87
|
+
> | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 一律 BLOCKED(同一形态一个判级);全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
|
|
70
88
|
> | ④ | **集成纪律** | 机制选择 / 顺序 / 审计 / 冲突处置四项均有明文规则 | 集成纪律四要素(见 Guidance 同名小节) |
|
|
71
89
|
>
|
|
72
90
|
> **写面含 gitignored 面的任务(四属性映射 · 与其他任务同一判据)**:任务 `write_files` 全为 gitignored 字面路径时,四属性的满足方式不变——① **写权限**仍走**身份通道**(载荷 `agent_id` / 环境变量身份深度 ⇒ 子代理语义放行,项目内任意路径可写(含 gitignored);gitignored 只是路径属性,不是通道差异);② **提交隔离**走既有 **`noCommit` 资格**(request 按 `.gitignore` 命中记 `noCommit:true` ⇒ 任务零提交,「提交只含自己 `write_files` 的字面路径」由**无提交**满足,不是放宽校验;资格 fail-closed:glob / `..` 越界 / 非 git 仓 / tracked 文件 / 链接逃逸一律不授予,result 时刻按同一判据重验,失败即撤销资格);③④ 与其他任务同形(同一时刻单写者 + 集成四要素)。**并行 × 零提交**因此合法:任务可标 `parallel="true"` 并被并行委派,出口校验按 request 的 `noCommit` 资格豁免缺 `commitHash`。
|
|
@@ -80,7 +98,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
80
98
|
|
|
81
99
|
要点(五要素 + 并行波次附加两条):
|
|
82
100
|
|
|
83
|
-
1. **`git add -- <自己字面路径>`** + **`git commit -- <同一路径>`**:逐条字面路径(取自本任务 `write_files
|
|
101
|
+
1. **`git add -- <自己字面路径>`** + **`git commit -m "<消息>" -- <同一路径>`**:逐条字面路径(取自本任务 `write_files`),两步路径集逐字一致——提交只含自己的文件;消息(含尾注)写在 `--` **之前**,写成 `-m` 在 `--` 之后会被当成 pathspec;禁用 `.` / `-A` / `-u` 等宽泛形态。
|
|
84
102
|
2. **锁失败重试**:并发提交撞 `index.lock` / `cannot lock ref` ⇒ **失败即重试**,不得因锁失败改用宽泛命令。
|
|
85
103
|
3. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:并发写者共享**同一个索引与工作树**——宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 更会破坏同伴的未提交工作。
|
|
86
104
|
4. **并行波次禁用 `git commit --amend`**:共享工作区下 HEAD 会被并行写者推进;确需修正必须**先断言 `git rev-parse HEAD` 等于自己刚提交的哈希**,否则一律改用**新提交追加**。
|
|
@@ -112,17 +130,22 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
112
130
|
|
|
113
131
|
对 TASK.md 每个 pending 串行任务,协调者执行:
|
|
114
132
|
|
|
115
|
-
1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request
|
|
116
|
-
2.
|
|
133
|
+
1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request(机制保证,不是经验之谈)**——`result` 在写盘前校验该任务存在 request 记录:缺失时 **BLOCKED**(state 字节零改写),并给出恢复指引「先照抄下面的命令记录委托(`description` 可省略),再重录 result」——命令形如 `node ".claude/skills/flow-comet/scripts/workflow-handoff.mjs" request T02`(设计形态,安装时脚本根按平台改写;引擎打印的就是带真实路径与任务号的那一行——脚本路径整条加引号,整行可直接执行)。零提交的 result 与只交自身 `<task-id>-SUMMARY.md` 的 result 两种形态同样被拦——该校验先于零提交语义与提交子集校验,那两者都从 request 取范围,因此不存在「先记 result 再补 request」的可行顺序。
|
|
134
|
+
2. **委托子代理**:
|
|
135
|
+
**委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request`(步骤 1)与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(BLOCKED,恢复句见步骤 1)。
|
|
136
|
+
**Delegation order (mandatory)**: a successful request first, then launch the subagent — the `workflow-handoff.mjs request` call and the subagent launch are two sequential steps; never inside one concurrent call (e.g. request plus Agent / spawn_agent in the same `Promise.all`). This is execution discipline, not a mechanism interception: the platform tool layer offers no hook point, so the engine will not queue it for you. **Two different things**: this rule is about the order of the request and the subagent launch, and nothing enforces it; "a result needs a request" is a mechanism guarantee — a result without one is refused before anything is written (it blocks, recovery line in step 1).
|
|
137
|
+
按平台通道委托 fresh-context 子代理(三平台同一身份判据,差异只在谁建树;`isolation: "worktree"` 是属性①的可选实现,非强制——见「并行安全四属性契约」)。handoff prompt 强制协议:子代理用 **Skill 工具**加载 flow-comet-dev 并按 `flow-kit/prompts/4-dev.md` 协议执行(TDD RED/GREEN/REFACTOR、LESSONS 扫描、既有抽象 grep、verify、6 维自查、越界检查、原子 commit `<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁 change-id/日期作 scope;任务号放提交正文尾注 Task: <task-id>,change-id 不入标题)),按 `flow-kit/templates/SUMMARY.md` 模板写 `.specs/<change-id>/<task-id>-SUMMARY.md`(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段),回传 Return Contract(含 commitHash + greenEvidence + completedChecks + selfReview)。**SUMMARY 自引用 hash 注**:提交内容无法包含自身 hash——若子代理 amend 提交,SUMMARY 内记录的 commitHash 为 amend 前值属预期(文件集一致即可,以实际提交对象为准)。
|
|
117
138
|
**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
118
|
-
**提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit --
|
|
139
|
+
**提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit -m "<消息>" -- <同一路径>`(消息在 `--` 之前)提交、锁失败重试、禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。**集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`、降级 `cherry-pick` 记因、顺序按 `depends_on` 拓扑序 + 同层 task id 升序、冲突按机械 / 语义两类分别处置。
|
|
119
140
|
**写前读模板(handoff prompt 固定句式)**:prompt 必须写明「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成,不得发出委托。
|
|
120
141
|
3. **记录 handoff result**:子代理回传后,运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs result <task-id> '<JSON>'` 记录(Return Contract 含 commitHash + greenEvidence + completedChecks + selfReview)。
|
|
121
|
-
4.
|
|
122
|
-
|
|
142
|
+
4. **每任务预检(`--preflight` · 只报结构问题)**:子代理回传并记下 `workflow-handoff.mjs result` 之后(direct 模式则在执行者交出 SUMMARY 之后),运行 `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit execute --preflight` —— 它只跑**结构性门禁**(本节点声明工件的存在性 / SUMMARY 关键段 / 模板保真骨架 / 入口工件骨架〔在场才查〕/ TASK 7 字段〔仅 `plan` 节点生效〕),**不跑**进展类门禁(证据、任务集签名、串行 pending、可委托并行、在飞委托、verify 命令执行),不推进状态、不写 state、也不写模板提示账本。**本家族的预检作用域** = 本节点声明工件的存在性(协议声明的 file 类产物,缺件即 BLOCK,逐项给出路径与模板指针)+ SUMMARY 关键段 + 模板保真骨架 + 入口三件(`CHANGE` / `REQUIREMENT` / `DESIGN`,存在才查);TASK 7 字段是 plan 出口的判据,对 execute 家族是 no-op,不在本步骤的范围内。**预检通过 = 结构面通过,不代表进展门禁会通过**(推进仍由完整 exit / `--apply` 决定)。价值:在「result 已记、尚未标 done」这个时点就能当场看到该任务 SUMMARY 的缺段 / 结构子段 / 条件段 / 首部字段问题——这正是本步骤存在的通道;不跑预检,这些问题会被更早的进展门禁挡下、攒到节点收尾一起爆。边界:它只报结构问题;**完整 `exit`(不带 `--apply`)仍是节点收尾的全链预演**——会先报进展类问题(串行 pending / 可委托并行 / 证据),预检不替代它。它只读、不写提示账本,因此**缺 H2 段只报类别计数**;结构子段与父段写法建议照常点名。要看被计数的那些段名,请等节点收尾的完整 `exit`(它维护提示账本),或直接按模板逐段对照。
|
|
143
|
+
**Per-task preflight (`--preflight`, structural only)**: after the subagent returns and its result is recorded (in direct mode, after the executor hands over the SUMMARY), run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit execute --preflight` — it runs only the structural gates (existence of the node's declared artifacts / SUMMARY key sections / template-fidelity skeleton / intake-artifact skeleton, checked only when present / TASK seven fields, which apply at `plan` alone) and skips the progress gates (evidence, task-set signature, serial pending, delegable parallel tasks, in-flight handoffs, real verify execution); it does not advance, does not write workflow state, and does not write the template hint ledger. **The preflight scope of this family** = the existence of the node's declared file artifacts (a missing one blocks and names each path with its template) + the SUMMARY key sections + the template-fidelity skeleton + the three intake documents (`CHANGE` / `REQUIREMENT` / `DESIGN`, checked only when present); the TASK seven fields belong to the `plan` exit and are a no-op for the execute family, so they are not part of this step. **Passing the preflight means the structural face passes; it does not mean the progress gates will pass** (advancing is still decided by the full exit / `--apply`). Value: the task's SUMMARY defects (missing section / structure subsection / conditional section / header field) surface right away at the point where the result is recorded and the task is not yet marked done — that is exactly the channel this step exists for; without it those defects are blocked by earlier progress gates and pile up at the node exit. Boundary: it reports structural problems only; the **full `exit` without `--apply` remains the node's whole-chain rehearsal** and reports progress-class problems first (serial pending / delegable parallel tasks / evidence) — preflight does not replace it. Because it is read-only and writes no hint ledger, **a missing H2 section is reported as a category count only**; a missing structural subsection, and the advice naming the parent section that should hold it, are still named. For the counted headings, wait for the node's closing full `exit` (which keeps that hint ledger) or compare the document against the template section by section.
|
|
144
|
+
5. **验收 SUMMARY,TASK.md 标 done**:确认 SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写且**模板保真**(标题 `# SUMMARY:` / 首部 4 字段 / 段序一致)、含 `## 自检方法` 与 `## LESSONS 扫描` 两个增量段(前者声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一)、verify 输出真实、6 维自查与越界检查有实质内容;通过后在 TASK.md 将任务标 `status="done"` 并加时间戳。
|
|
145
|
+
6. **下一个 pending 任务**:重复步骤 1-5。
|
|
123
146
|
|
|
124
147
|
> 原 Steps 的 TDD / LESSONS / verify / 6 维自查 / 越界检查 / commit 协议**移入 handoff prompt 作为子代理的强制协议**,协调者不亲自执行。
|
|
125
|
-
> **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence
|
|
148
|
+
> **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence 缺失仍会被 W1-D 拦截,因此必须显式提供此形态而非省略字段)。
|
|
126
149
|
> **Return Contract 的 completedChecks 统一契约**:子代理回传的 `completedChecks` 必须包含 `required-skill:subagent-execute.flow-comet-dev`——execute(串行委托)与 subagent-execute(并行委托)的 handoff 统一记录在 subagent-execute 证据库(共用证据库语义),guard 的 W1-D 对全部委托结果统一校验该契约。取值与节点自证命名(本节点自身证据用的 `required-skill:execute.flow-comet-dev`,见 Required Skill Calls)无关。**格式要求**:`completedChecks` 必须是**字符串数组**(如 `["required-skill:subagent-execute.flow-comet-dev"]`)——对象数组(如 `[{id, status}]`)会被 guard 的严格比较判"缺"→ exit BLOCKED。示例:
|
|
127
150
|
>
|
|
128
151
|
> - 正确:`"completedChecks": ["required-skill:subagent-execute.flow-comet-dev"]`
|
|
@@ -151,6 +174,7 @@ This node is truly done when:
|
|
|
151
174
|
- **Agent thought**: "I see a bug in an adjacent file, let me fix it along the way." **Actual risk**: "Fixing along the way" without a new task or CHANGE violates R7.1 (scope control). Must stop and create a new task or CHANGE.
|
|
152
175
|
- **Agent thought**: "This task is taking long, let me skip the self-review." **Actual risk**: Skipping self-review defers quality issues to the review node, where they become Critical items requiring fix tasks. Better to catch early.
|
|
153
176
|
- **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
|
|
177
|
+
- **Agent thought**: "同时发 request 和启动子代理,省一个来回。" **Actual risk**: 先让 request 成功,再启动子代理——禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all`);这是执行纪律,不是机制拦截(平台层没有挂点,引擎不替你排队)。与它相邻的另一件事已是机制保证:`result` 在写盘前校验该任务有 request 记录,缺失即 BLOCKED 并给出补 request 的恢复句。The order is mandatory: **a successful request first, then launch the subagent**, **never inside one concurrent call**; this is **execution discipline, not a mechanism interception** — the platform tool layer has no hook point to enforce it.
|
|
154
178
|
|
|
155
179
|
## 修复回路状态机路径
|
|
156
180
|
|
|
@@ -222,7 +246,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record execute '{"summ
|
|
|
222
246
|
| Guardrail ID | Label | Validation Type |
|
|
223
247
|
|--------------|-------|-----------------|
|
|
224
248
|
| `build-evidence` | At least one SUMMARY.md produced | artifact-exists |
|
|
225
|
-
| `all-tasks-done` | All tasks in TASK.md have status="done"(pending 串行任务 → BLOCKED);done 任务须有对应 SUMMARY
|
|
249
|
+
| `all-tasks-done` | All tasks in TASK.md have status="done"(pending 串行任务 → BLOCKED);done 任务须有对应 SUMMARY(一律 BLOCKED,同一形态一个判级) | content-check |
|
|
226
250
|
| `verify-output-real` | Every SUMMARY.md has verify output (not fabricated) | 结构级(guard 强制:`## verify 输出` 段在场且正文非空,骨架校验同批拦截);输出是否真实由 review 把关(伪造不可机检) |
|
|
227
251
|
| `no-design-changes` | REQUIREMENT.md and DESIGN.md not modified | 执行纪律(review 把关),guard 不校验 |
|
|
228
252
|
| `self-check-method` | Every SUMMARY.md declares `## 自检方法`(brooks-review / cache-brooks / builtin-quickcheck) | W1-B 段级校验 |
|
|
@@ -34,10 +34,16 @@ description: "flow-kit INTEGRATION 阶段协议:集成验证 + UAT + 失败诊
|
|
|
34
34
|
|
|
35
35
|
### 归档(archive 阶段)
|
|
36
36
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
37
|
+
> **硬规则(先于任何动作)**:archive 节点的**技能加载声明必须先于任何动作,尤其先于搬目录**——先用 Skill 工具加载 `flow-comet-integration`,再照抄 `flow-comet-archive` 册的 `skill-load` 命令写下声明标记,之后才开始下面的步骤。移动目录之后补声明 / 补记录仍可完成(引擎按状态判身份、按解析到的目录读写标记),但那是**恢复路径**;规范顺序永远是**先记录、后搬目录**。
|
|
38
|
+
|
|
39
|
+
1. **准备**:LESSONS 提名(本册上段)与遗留清单(`KNOWN-ISSUES.md`)就位——本步只写工件,不动目录。
|
|
40
|
+
2. **记录**:`node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` 写下归档证据——**搬目录之前的最后一件证据动作**。
|
|
41
|
+
3. **搬目录**:`.specs/<change-id>/` → `.specs/archive/<YYYY-MM-DD>-<change-id>/`——本流程唯一的不可逆动作,排在声明与记录之后。
|
|
42
|
+
4. **登记**:`.specs/CHANGELOG.md` 顶部按日期倒序插入一行——**跟随项目既有格式**(非表格格式同样在顶部插入,不强制转表格;guard 的倒序检测只针对表格格式行)——完整协议见 `flow-comet-archive` 册;**不归档** `.specs/LESSONS.md`(项目级常驻)。
|
|
43
|
+
5. **通知与出口**:向用户列出遗留清单并告知沉淀候选 → `workflow-guard.mjs exit archive --apply`(**搬目录仍是 `exit` 的前置**)。
|
|
44
|
+
- 出口打印 `NEXT: done` 之后的**交接**:步骤权威在 `flow-comet-archive` 册的「归档完成后的交接」段(触发时机 / 顺序 / 不阻断归档 / 不做任何分支操作),载体探测与操作矩阵见 `../flow-comet/reference/post-archive-handoff.md`;本步的 exit 顺序与出口判据不变。
|
|
45
|
+
|
|
46
|
+
DESIGN.md § 9 架构沉淀建议留待 A-evolve 批量同步。
|
|
41
47
|
|
|
42
48
|
## 产物
|
|
43
49
|
|
|
@@ -35,7 +35,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
35
35
|
|
|
36
36
|
在波次散文一致性、依赖图(`depends_on` 无环且引用存在)、7 字段同层,plan 出口还做文件级依赖检测:
|
|
37
37
|
|
|
38
|
-
- **写写强判**:本趟可运行的并行 pending 任务 `write_files` 有交集 →
|
|
38
|
+
- **写写强判**:本趟可运行的并行 pending 任务 `write_files` 有交集 → 一律 BLOCKED(消息含任务 id 对 × 重叠路径与恢复指引「补显式 depends_on 或拆为串行任务」;同一形态一个判级)。
|
|
39
39
|
- **读写弱判**:仅对**无显式 depends_on 关联**的并行对探测一方 `read_files` 命中对方 `write_files` → WARN 提示(建议补显式 depends_on 声明),不 BLOCK;有显式关联=依赖已声明,跳过(合法拓扑零新增告警)。
|
|
40
40
|
- **路径按声明实际解析**:不做扩展名白名单过滤——txt/log/无扩展名路径同等检出(链式重命名事故面闭合)。
|
|
41
41
|
- **并存不干扰**:伪并行 WARN(并行任务全部仅写测试产物)与 read∩write 弱判各自独立渐进提示;委托前写写拦截保持为第二道防线。
|
|
@@ -23,19 +23,21 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
|
|
|
23
23
|
|
|
24
24
|
首部字段 `Change ID` / `关联` 已在场时值不得为空(键集不强制)。
|
|
25
25
|
|
|
26
|
-
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结构、每任务 `<verify>`、**新格式任务的 7 字段在场**、以及 TASK.md 的模板骨架(段标题 / 段序 / 首部字段值非空)都由 guard
|
|
26
|
+
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结构、每任务 `<verify>`、**新格式任务的 7 字段在场**、以及 TASK.md 的模板骨架(段标题 / 段序 / 首部字段值非空)都由 guard 拦(缺任一 = 出口 BLOCKED;其中 7 字段一项在「旧式一字段模板形态(无 `<name>`)」下仅 WARN——分级依据是模板形态,不是 change 新旧);「填得好不好」——字段内容质量与任务粒度——由 review 把关。
|
|
27
27
|
|
|
28
28
|
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
29
29
|
|
|
30
30
|
加载顺序:先读 `READ PROMPT:`(`3-task`),再读 `READ TEMPLATE:`(`TASK`)。
|
|
31
31
|
|
|
32
|
-
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"`
|
|
32
|
+
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——不一致 BLOCKED(同一形态一个判级)。波次投影一致性:`## 波次划分` 声明的波次必须等于任务的依赖层级(判据与恢复指引见下方「波次形态约束」)——不一致 BLOCKED(同一形态一个判级);判不了按成因二分——**载体缺席**(`## 波次划分` 不在 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过),**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,一律 BLOCKED(同一形态一个判级);任务集里的任务还必须被某条 Wave 行覆盖(修复族除外,漏写的以「未声明」点名)。
|
|
33
33
|
|
|
34
34
|
### 波次形态约束(依赖驱动多趟 · 规划期必守)
|
|
35
35
|
|
|
36
|
-
**约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on
|
|
36
|
+
**约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on`,依赖面的合法性只取决于依赖图本身:`depends_on` 无环且引用的任务都存在,依赖面即合法;波次编号另按「波次 = 依赖层级的投影」(下一条)单独校验——依赖面合法不等于波次声明合法,两条判据各自独立拦截。全并行、全串行、串→并、并→串四种基本形态与任意混排序列(如 `S→P→S`、`P→S→P`)一律放行——引擎按依赖拓扑自动分趟(每趟委托全部依赖已满足的并行任务,趟间回串行消化),混排序列由多趟路由按依赖拓扑自动分趟消化,并行任务的先后位置不受任何限制。
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
**波次 = 依赖层级的投影(波次编号的判据)**:`## 波次划分` 里的波次编号不是自由排版,而是任务依赖层级的投影——① 每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);② 同波任务必须彼此没有依赖;③ 想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 出口 **BLOCKED**:明细逐条点名「任务 / 依赖 / 当前波 / 应到波」,并给两条恢复出路——把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来(要保留当前波次,就把「它为何排在后面」的依赖写成显式 `depends_on`)。**判不了按成因二分**:**载体缺席**(无 `## 波次划分` 段 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id——正文只写 `N/A`、Wave 行点的是不存在的 id、行首强调记号让 Wave 行不成立)→ 出口打印 `TASK.md 波次划分段内容不可判`,一律 BLOCKED(同一形态一个判级)。**覆盖义务**:TASK 里的每个非修复族任务都必须被某个 Wave 行覆盖(修复族不要求排进波次),漏写的任务在明细里以「未声明」的当前波逐条点名——没有「当前波」可挪,恢复出路是把它写进应到波的 Wave 行。`replan` 重校走同一判据、同一报文,不豁免。**与混排合法化并存**:本条只要求「波次编号与依赖层级一致」,不恢复旧的「并行块必须连续成组」形态约束——上面的串→并→串混排照旧合法,并行任务的先后位置照旧不受限制。
|
|
39
|
+
|
|
40
|
+
**硬性拦截(规划出口 BLOCKED,附恢复指引)**:任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见上表;缺任一即 BLOCKED——7 字段一项在旧式一字段模板形态下仅 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)/ 波次声明与依赖层级不一致(明细与两条恢复出路见上一条)——任一项不成立即在规划出口被 BLOCKED(读写重叠仅 WARN),按提示修正后重新 exit 即可通过。任务间依赖不得成环(如 A→B→A),也不得构成不可满足的依赖链。
|
|
39
41
|
|
|
40
42
|
**警示**:落笔时先画依赖方向再标 [P],避免出口返工。
|
|
41
43
|
|
|
@@ -87,11 +89,14 @@ This node decomposes the technical design into atomic, executable tasks with cle
|
|
|
87
89
|
- `done`: One sentence completion criteria, corresponding to an AC sub-item.
|
|
88
90
|
|
|
89
91
|
7. **Wave division**: Group tasks by dependency graph:
|
|
92
|
+
- **Waves are a projection of dependency levels**: each task's wave is one past the latest wave among its dependencies (no dependency = wave 1), and tasks in the same wave must not depend on one another; to make a task run later, declare the order with `depends_on` instead of moving it to a later wave without declaring it.
|
|
90
93
|
- Cross layer = sequential execution.
|
|
91
94
|
- Same-layer tasks may carry `parallel="true"` only when the wave genuinely contains a concurrent companion and their `write_files` do not overlap; an isolated task stays serial.
|
|
92
95
|
- Flow-comet override: the permissive flow-kit upstream semantics — "no conflict ⇒ [P]" and "same layer = same wave, parallel" — are superseded by this node's rule; the vendored upstream files stay read-only and are not modified.
|
|
93
96
|
- Output wave diagram: `Wave 1: T01[P], T02[P]` etc.; isolated tasks appear as serial steps.
|
|
94
97
|
|
|
98
|
+
A declared wave that disagrees with the dependency level — a same-wave dependency, a task placed before its dependency, or a conservative placement later than needed — blocks at the plan exit: every mismatch is named as task / dependencies / declared wave / expected wave, together with the two ways out (move it to wave N, or add the `depends_on` that explains the order). When the section is absent (no `## 波次划分` section, or its name cannot be derived), the exit prints "not checked (no wave section)" and skips the rule — unverified is not a pass. When the section is present but no Wave line resolves to a real task (a body that only says N/A, a line naming an unknown id, a leading emphasis mark that breaks the line), the content cannot be judged: it blocks there. Every task in the set must be covered by some Wave line (the fix-task family excepted); a task the section never mentions is named with "undeclared" as its current wave, and the way out is to write it into the wave it should reach. `replan` runs the same judgement with the same wording. This rule constrains the agreement between wave numbers and dependency levels only: it does not bring back the old "parallel blocks must be contiguous" shape constraint, so the mixed-sequence freedom above stands (serial → parallel → serial stays legal).
|
|
99
|
+
|
|
95
100
|
8. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to planned file paths or actions. If active lessons hit, declare difference or confirm still applies.
|
|
96
101
|
|
|
97
102
|
The full task decomposition protocol, XML template, and constraints are in:
|
|
@@ -101,11 +106,12 @@ The full task decomposition protocol, XML template, and constraints are in:
|
|
|
101
106
|
|
|
102
107
|
This node is truly done when:
|
|
103
108
|
- `.specs/<change-id>/TASK.md` exists in XML format.
|
|
104
|
-
- At least one `<task>` block exists; every task carries a `<verify>` field, and the 7-field set `name` / `read_files` / `write_files` / `action` / `verify` / `done` / `depends_on` is present (`id` is an **attribute** of the `<task>` element, not a field) — field **presence** is enforced by the guard (missing any field on a new-format task
|
|
109
|
+
- At least one `<task>` block exists; every task carries a `<verify>` field, and the 7-field set `name` / `read_files` / `write_files` / `action` / `verify` / `done` / `depends_on` is present (`id` is an **attribute** of the `<task>` element, not a field) — field **presence** is enforced by the guard (missing any field on a new-format task = exit BLOCKED; a task set written in the old one-field template shape degrades to WARN — that tier follows the template shape, not the age of the change), while **field content quality** is judged by review.
|
|
105
110
|
- Every `verify` field is an executable command (not a description).
|
|
106
111
|
- Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
|
|
107
112
|
- Every `[P]` mark has a genuine concurrent companion in its wave with non-overlapping `write_files`; isolated tasks are serial (a fully serial plan is valid when no genuine companion exists).
|
|
108
113
|
- Wave division diagram is clear and has no circular dependencies.
|
|
114
|
+
- Wave numbers agree with dependency levels: each wave is one past the latest dependency wave, and tasks sharing a wave have no dependencies between them (an absent wave section is reported as "not checked", never as a pass; a section whose content cannot be judged blocks).
|
|
109
115
|
- Task numbering is continuous.
|
|
110
116
|
|
|
111
117
|
### Red flags
|
|
@@ -114,6 +120,7 @@ This node is truly done when:
|
|
|
114
120
|
- **Agent thought**: "verify: tests should pass" is good enough. **Actual risk**: Vague verify commands cannot be executed. Must be specific: `pytest tests/test_x.py -v` not "tests should pass".
|
|
115
121
|
- **Agent thought**: "write_files can include any file the task might touch." **Actual risk**: Including DESIGN forbidden list modules in write_files bypasses R7.3 + R6.5 boundary enforcement. Strict control is mandatory.
|
|
116
122
|
- **Agent thought**: "Same layer means these tasks can all be marked [P]." **Actual risk**: A same-layer task with no concurrent companion, or with overlapping `write_files`, would be delegated as parallel in violation of this node's rule. Mark `[P]` by companion and write boundaries, never by layer alone.
|
|
123
|
+
- **Agent thought**: "This task just feels like it should run later, so I'll put it in a later wave." **Actual risk**: A wave number is the dependency level projected onto the plan — moving a task to a later wave without declaring the dependency is exactly the mismatch the exit blocks. Declare `depends_on` instead of moving the wave.
|
|
117
124
|
- **Agent thought**: "read_files and write_files are the same thing." **Actual risk**: read_files includes reuse targets and reference modules; write_files is strictly the modification boundary. They serve different purposes (B3 old-project guardrail).
|
|
118
125
|
|
|
119
126
|
## Entry Check
|
|
@@ -164,7 +171,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record plan '{"summary
|
|
|
164
171
|
| Guardrail ID | Label | Validation Type |
|
|
165
172
|
|--------------|-------|-----------------|
|
|
166
173
|
| `plan-artifacts` | TASK.md exists with XML tasks | artifact-exists |
|
|
167
|
-
| `task-fields-complete` | All tasks have 7 required fields | 结构在场(新格式任务缺任一字段 = 出口 BLOCKED
|
|
174
|
+
| `task-fields-complete` | All tasks have 7 required fields | 结构在场(新格式任务缺任一字段 = 出口 BLOCKED;旧式一字段模板形态的缺项仅 WARN——按模板形态分级)——**字段内容质量**由 review 把关 |
|
|
168
175
|
| `write-files-safe` | No write_files in DESIGN forbidden list | 执行纪律(review 把关),guard 不校验 |
|
|
169
176
|
| `has-parallel` | At least 1 [P] task (if applicable) | 执行纪律(review 把关),guard 不校验 |
|
|
170
177
|
|