flow-comet 1.6.4 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +36 -6
- package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
- package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +29 -4
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +174 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +17 -95
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +136 -19
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +54 -18
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +25 -10
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +4 -2
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +21 -13
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +163 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +448 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +396 -27
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1035 -172
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +129 -98
- 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 +797 -232
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +91 -22
- 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 +69 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +454 -135
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +109 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +149 -34
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +79 -9
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +78 -8
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +167 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +287 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1454 -16
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1205 -77
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +52 -11
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +9 -1
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +22 -6
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +18 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +4100 -0
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +203 -4
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +42 -15
- package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
- package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +21 -10
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-review/SKILL.md +33 -18
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +44 -16
- package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
- package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
- package/README.md +3 -3
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
- package/scripts/lib/installer-flowkit.mjs +43 -3
|
@@ -17,18 +17,27 @@ This node performs a structured multi-round review of the implemented change, ch
|
|
|
17
17
|
|
|
18
18
|
### 必填段清单(结构+存在级)
|
|
19
19
|
|
|
20
|
-
|
|
|
21
|
-
|
|
22
|
-
| REVIEW.md |
|
|
20
|
+
| 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
|
|
21
|
+
|------|------|------|
|
|
22
|
+
| `REVIEW.md` | `## 第一轮 · Spec 合规审查` / `## 第二轮 · 代码质量审查(6 维衰退风险)` / `## 总结`;结构子段 `### 2.0 TEST.md 5 轮金字塔完整性` / `### 2.1` / `### 2.2` / `### 2.3` 在父段在场时必在场;文件 ≥ 100 字节;首部字段 `Change ID` / `审查时间` / `审查者` / `总体结论` 已在场时值不得为空(键集不强制) | **条件段**:`## 第三轮 · UI 视觉审查(仅前端)` / `## 第四轮 · 补充审查(按触发条件)`——标题必须在场,不适用写 `N/A`(其结构子段 `### 4.1` / `### 4.2` 在父段适用时必在场);**增量段**:发现条目的**处置标记**(`[已修]` / `[升级]` / `[转待办]`,必填,写在 `### 2.2 6 维诊断 · 详细发现` 段内) |
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
发现写在模板外的 `## 发现` 而 `### 2.2` 无条目 → 新 change BLOCKED(条目记录在非模板位置等于静默丢弃);**任何严重度的 `[转待办]` 都须有用户裁决记录**(同段、文末或单独段落「用户裁决:接受延期」+ 指向该条目 + `[升级]` 承接——单独段落与条目以空行分隔、位置不限),缺失新 change BLOCKED / 旧 change WARN 渐进;**每条判为 Minor 的发现都要在条目块内写 `判 Minor:<一句话理由>`**(判据见下方「处置标记」条),与处置标记无关——缺这行同样新 change BLOCKED / 旧 change WARN 渐进。
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
本出口**声明加载** `TEST.md` 并做 **5 轮完整性过程检查**(细目见 `flow-comet-test` 册);`TEST.md` 的**结构骨架校验在 verify 出口**(`flowkit.verify.v1`),不在本出口——`## 验证命令` 增量段的执行与校验同样在 verify 出口。
|
|
27
|
+
|
|
28
|
+
**AC 覆盖**在这里只做汇总提示:`REQUIREMENT.md` 的验收准则每条都应在 `TEST.md` 的 1.1 测试矩阵里有对应行;真缺时出口打印一行 `REVIEW WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖: AC-…`——一条汇总、不逐条刷屏、**不改变退出码**。权威判定在 verify 出口:新 change 缺覆盖 **BLOCKED**(点名编号 + 恢复句「在 TEST.md 的 1.1 测试矩阵为这些 AC 补行」),旧 change WARN 渐进。判不了按成因二分(与波次判据同口径):**模板缺席**(段名无从派生)→ 打印「未校验(<原因>)」且不改退出码(未验证 ≠ 通过,也不冒充通过);**内容不可判** → verify 出口打印 `AC 覆盖判据无法执行`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数)。落在内容不可判一侧的有两种形态:承载段或段内清单读不出来(`REQUIREMENT.md` 的验收准则段被删掉 / `TEST.md` 的第 1 轮段被删掉 / `REQUIREMENT.md` 无 AC 编号 / 第 1 轮内无 1.1 测试矩阵段),以及 **change 自己的载体文件本身缺席**(`REQUIREMENT.md` 缺席 / `TEST.md` 缺席)——载体文件是这个 change 自己的东西,删掉它换不到「没有可判对象」。围栏代码块里的示例行也不算覆盖(矩阵段跨过围栏读段界,示例仍只是示例)。本出口对两支判不了都不打印(不制造噪音),只汇总真缺的编号。
|
|
29
|
+
|
|
30
|
+
guard 校验见 workflow-guard.mjs 的 review 出口门禁(发现区处置标记 / 发现位置 / 延期裁决(任何严重度)/ Minor 判定理由行 / 模板骨架)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 自身把关。
|
|
31
|
+
|
|
32
|
+
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
33
|
+
|
|
34
|
+
加载顺序:先读 `READ PROMPT:`(`6-review`、`5-test`),再读 `READ TEMPLATE:`(`REVIEW`、`TEST`)。
|
|
27
35
|
|
|
28
36
|
### 必查清单(review 逐项核对 · 执行者交付纪律)
|
|
29
37
|
|
|
30
38
|
- [ ] **工件模板保真**:每份交付工件(`*-SUMMARY.md` / TASK / CHANGE / REQUIREMENT / DESIGN)的**标题 / 首部字段 / 段序**与对应模板一致——SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写并含 `## 自检方法` 段;执行者按 `flow-kit/prompts/4-dev.md` 协议交付。
|
|
31
39
|
- [ ] **Skill 工具触发可见**:检查执行者交付的 transcript,**逐节点可见本节点 skill 用 Skill 工具加载**的触发记录——声明标记在 ≠ 已加载;只看到 `skill-load` 声明命令、看不到 Skill 工具触发 → 反馈并要求补证/重做。
|
|
40
|
+
- [ ] **AC 覆盖**:看到出口打印的 `REVIEW WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖` 时逐条核对缺失编号——要么在 1.1 矩阵补行(verify 出口会据此 BLOCK),要么在 REVIEW 里说明该 AC 为何无用例并按发现条目处理(处置标记 + 严重度);**不得因为 review 出口只汇总、不阻断,就把缺口留给 verify 出口**。
|
|
32
41
|
- [ ] **Skill 工具不可用降级核验**:执行者会话具备 Skill 工具时,须见 Skill 工具加载节点 SKILL 的触发记录;不具备时(委托会话工具集无 Skill 工具),须按 Read 加载节点 SKILL + 协议,并在 Return Contract(`skillToolFallback: "<降级替代形态,如 file-read>"`)与 SUMMARY「自检方法」段显式声明——**Read 不得被声称为已注入(即未执行 Skill 工具注入,字段值必须写替代形态而非本说明)**。只回传 required-skill 标记而无降级声明 → 证据不完整,要求补声明;声明齐全的环境限制不判为代码缺陷。
|
|
33
42
|
|
|
34
43
|
### Prerequisites
|
|
@@ -69,7 +78,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
69
78
|
3.5. **Round 2.0 — TEST.md 5-round pyramid completeness**: Before code quality, verify TEST.md:
|
|
70
79
|
- All 5 rounds have clear status (no unfilled).
|
|
71
80
|
- Skipped rounds have reasons.
|
|
72
|
-
- Round 1 (functional): every AC has coverage.
|
|
81
|
+
- Round 1 (functional): every AC has coverage — every acceptance criterion in `REQUIREMENT.md` reads a row in the 1.1 test matrix. When any is missing the review exit prints one summary line (`REVIEW WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖: AC-…`) and keeps its exit code, while the verify exit is the authoritative gate: a new change blocks on the gap with the recovery line "add the rows to TEST.md's 1.1 test matrix", an older change warns. When the criterion cannot be judged the causes part ways (the same convention as the wave rule): a missing template — the section names cannot be derived — prints "not checked (<reason>)" and keeps the exit code, while content that cannot be judged is not a pass: the exit reports that the AC coverage rule cannot run, blocks a new change, warns on an older change and counts that warning. Two shapes fall on that side: the carrier section or the list inside it cannot be read (the acceptance section deleted from `REQUIREMENT.md`, the round-1 section deleted from `TEST.md`, no AC ids, or no 1.1 test matrix inside the round-1 section), and a carrier document of the change itself being gone — `REQUIREMENT.md` absent or `TEST.md` absent: the document belongs to this change, so deleting it is not "nothing to judge"; a sample row inside a fenced code block counts as neither coverage nor a declared criterion either, because the matrix section steps over fences while the sample stays a sample. This exit prints neither of the two not-judged branches.
|
|
73
82
|
- Round 2 (performance): if required, has actual/budget/baseline columns.
|
|
74
83
|
- Round 3 (security): if required, has dependency/secret/SAST/OWASP records.
|
|
75
84
|
- Round 4 (compatibility): if required, has browser matrix/migration/cross-version.
|
|
@@ -88,18 +97,20 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
88
97
|
- **4.1 Tech debt assessment**: If milestone/quarterly release, run `/brooks-debt` (Codex: `$brooks-debt`). Categorize findings into Critical (fix now) / Scheduled (next 1-3 iterations) / Monitored (record only).
|
|
89
98
|
- **4.2 Cross-model spot-check**: If involves security/auth/concurrency/single function >80 lines/coverage drop: run same review with another model, record divergence.
|
|
90
99
|
|
|
91
|
-
7. **Severity grading**: Each finding gets
|
|
100
|
+
7. **Severity grading**: Each finding gets one of three grades — **Major 是默认档位**:
|
|
92
101
|
- Critical (must fix: data corruption, security, AC not met)
|
|
93
|
-
- Major (should fix: design issues, significant regression)
|
|
94
|
-
- Minor (optional: naming, style, small refactor)
|
|
102
|
+
- Major (should fix: design issues, significant regression) — **默认**:拿不准就判 Major
|
|
103
|
+
- Minor (optional: naming, style, small refactor) — **仅当同时满足下方「Minor 的判据」全部五条**才可判;且该条目必须带一行 `判 Minor:<理由>`
|
|
95
104
|
|
|
96
105
|
8. **Generate fix tasks**: For all Critical and decided-to-fix Major findings, append to `.specs/<change-id>/TASK.md` as numbered fix tasks with full 7 fields — 追加到 TASK.md 的 `## Fix 任务` 段内(**禁止文件尾追加**), then follow the「修复回路状态机路径」section below: home back to execute and run its four exit gates before review can be closed.
|
|
97
106
|
|
|
98
107
|
9. **Disposition markers (problem-handling principle)**: Every finding entry in the `## 发现` section of REVIEW.md — including Minor — must carry a **disposition marker** so findings never silently disappear after being recorded:
|
|
99
108
|
- `[已修]` — fixed via a fix task (linked in the entry)
|
|
100
109
|
- `[升级]` — escalated to the user for a decision (accept + reason recorded)
|
|
101
|
-
- `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time
|
|
102
|
-
-
|
|
110
|
+
- `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time;**延期在任何严重度上都是用户决策点**
|
|
111
|
+
- **`[转待办]` 一律需用户裁决(Major 与 Minor 同一标准)**:延期不是 reviewer 能自行给出的处置。reviewer 须先标 `[升级]` 等用户裁决;用户接受延期后,在同段、文末或单独段落记录「用户裁决:接受延期」并指向该条目(由 `[升级]` 承接),方可标 `[转待办]`——单独段落与发现条目以空行分隔、可位于发现区中间,位置不限(guard 按独立段落匹配,不要求位于文末)。review exit 结构校验:条目标 `[转待办]` 而缺上述记录 → 新 change BLOCKED / 旧 change WARN 渐进;`[升级]` / `[已修]` 的条目直接放行。
|
|
112
|
+
- **Minor 的判据(五条全中才算 Minor,否则按 Major 处理)**:① 不改变任何行为与输出;② 不影响任何对外 / 对用户的表述(文档、报文、CHANGELOG);③ 不新增或保留第二份等价实现;④ 不削弱任何断言或测试判别力;⑤ 不涉及跨平台 / 分发形态。**不满足任一条即按 Major 处理**——举证责任在「判 Minor」的一侧,不在「判 Major」的一侧。每条判为 Minor 的发现都必须带一行判定理由,形态固定为 `判 Minor:<一句话理由,对应①~⑤>`,写在条目块内、与条目标题之间不留空行,**与处置标记无关**(`[已修]` / `[升级]` / `[转待办]` 一律要:理由落在判定当时,而不是延期时再补);缺该行 → 新 change BLOCKED / 旧 change WARN 渐进。
|
|
113
|
+
- **修复回路内不得延期**:在一次修复回路里新发现的条目,只能是 `[已修]` 或 `[升级]`(交用户裁决)——即使该条目已有用户裁决的延期记录在场,也不得把修复回路新增的发现标 `[转待办]`。回路是「把本轮引入的问题收干净」的窗口,不是继续开新账的入口。
|
|
103
114
|
The exit guard structurally checks these markers on the findings area: a missing marker **blocks** the exit for a new change, and is a non-blocking warning for a legacy change (to avoid deadlocking legacy reviews). Add markers to clear it.
|
|
104
115
|
|
|
105
116
|
The full review protocol, templates, and checklists are in:
|
|
@@ -110,7 +121,7 @@ The full review protocol, templates, and checklists are in:
|
|
|
110
121
|
|
|
111
122
|
This node is truly done when:
|
|
112
123
|
- `.specs/<change-id>/REVIEW.md` exists with all 3 mandatory rounds completed.
|
|
113
|
-
- Every finding has a severity label, file:line reference, and a disposition marker (`[已修]` / `[升级]` / `[转待办]`).
|
|
124
|
+
- Every finding has a severity label, file:line reference, and a disposition marker (`[已修]` / `[升级]` / `[转待办]`); every `[转待办]` has a recorded user ruling, and every Minor carries its `判 Minor:` reason line.
|
|
114
125
|
- All Critical items are either fixed (fix tasks generated) or explicitly accepted with user confirmation.
|
|
115
126
|
- 0 unacknowledged Critical items remain.
|
|
116
127
|
- TEST.md 5-round pyramid completeness has been verified.
|
|
@@ -120,11 +131,14 @@ This node is truly done when:
|
|
|
120
131
|
|
|
121
132
|
- **Agent thought**: "Code looks good, no issues found." **Actual risk**: Concluding without file:line references means the review was superficial. Every finding must point to specific code.
|
|
122
133
|
- **Agent thought**: "TEST.md exists, that's enough." **Actual risk**: Not checking test pyramid completeness means gaps in test coverage go undetected. Must verify all 5 rounds have clear status.
|
|
134
|
+
- **Agent thought**: "The exit only warned about the missing AC coverage, so it is not my problem." **Actual risk**: 汇总不阻断是分工,不是豁免——verify 出口会就同一份缺口 BLOCKED(新 change)。缺口只有两条出路:在 1.1 矩阵补行,或把它作为发现条目按处置标记处理;把缺口留到 verify 等于把可修的问题变成一次节点返工。
|
|
123
135
|
- **Agent thought**: "I'll fix this small issue directly." **Actual risk**: Reviewer modifying code violates R3.3. Must generate fix tasks instead.
|
|
124
136
|
- **Agent thought**: "Round 3 (UI) is optional." **Actual risk**: For frontend projects with UI changes, Round 3 is mandatory. Only non-frontend projects skip it.
|
|
125
137
|
- **Agent thought**: "6-dimension review is just a checklist." **Actual risk**: Without file:line references and book citations (when using built-in path), the review lacks rigor and fixability.
|
|
126
|
-
- **Agent thought**: "I'll record this Minor and move on." **Actual risk**:
|
|
127
|
-
- **Agent thought**: "This
|
|
138
|
+
- **Agent thought**: "I'll record this Minor and move on." **Actual risk**: 不带处置标记(或判了 Minor 却写不出 `判 Minor:` 理由)的发现等于静默丢弃——退出守卫按结构拦截;每条发现都必须是 `[已修]`、`[升级]`(交用户裁决)或 `[转待办]`(延期,须先有用户裁决)。
|
|
139
|
+
- **Agent thought**: "This finding is not for this batch, I'll defer it to backlog myself." **Actual risk**: 延期在任何严重度上都是用户决策点——Major 与 Minor 一视同仁;reviewer 自行 `[转待办]` 会被退出守卫拦下(新 change BLOCKED / 旧 change WARN),须先 `[升级]` 等用户裁决,用户接受延期后才可记录裁决并转待办。
|
|
140
|
+
- **Agent thought**: "It's only naming and style, Minor is fine." **Actual risk**: Minor 的判据是五条全中而不是主观轻重——改行为、改对外表述、留第二份等价实现、削弱断言、触及跨平台面,任一条成立即按 Major 处理;宽判 Minor 正是遗留账不断增长的入口,判不准时默认 Major。
|
|
141
|
+
- **Agent thought**: "I'm in a fix loop, I'll defer this new one." **Actual risk**: 修复回路内新发现的条目只能 `[已修]` 或 `[升级]`——不得 `[转待办]`,即使裁决记录在场;这是纪律要求,守卫只看结构、看不出你在回路里第几轮。
|
|
128
142
|
|
|
129
143
|
## 修复回路状态机路径
|
|
130
144
|
|
|
@@ -135,6 +149,7 @@ review 发现 Critical / Major 后的修复必须回到 `execute` 节点生命
|
|
|
135
149
|
3. **跑完 execute 四类出口**:`record execute` → `exit execute --apply`——全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致,任一缺失即 BLOCKED;通过后引擎把当前节点推回 review。
|
|
136
150
|
4. **回源节点跑出口**:回到源节点后跑该节点出口门禁(`entry <源节点>` → `exit <源节点> --apply`),通过后继续 review → verify 的正常路由,必要时进入下一轮 Fix 闭环。
|
|
137
151
|
5. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
152
|
+
6. **回路内新发现的条目不得延期**:修复过程中(含回到 review 复检时)新发现的条目只能标 `[已修]` 或 `[升级]`(交用户裁决),**不得**标 `[转待办]`——即使已有用户裁决的延期记录在场。回路是把本轮引入的问题收干净的窗口,不是继续开新账的入口;守卫只做结构判定,这一条靠执行纪律。
|
|
138
153
|
|
|
139
154
|
**何时读完整规格**:要核对完整判据——Fix 任务与任务集签名的时序、受控归位的完整判定条件、`FIX-BATCH` / `RETURN` 审计行三态语义与回源节点的回程豁免、绕过的失败面与恢复指引——读 `../flow-comet/reference/fix-loop.md`(**当你 review 发现缺陷、要开修复回路把工作退回 execute 生命周期时读它**)。
|
|
140
155
|
|
|
@@ -164,11 +179,11 @@ Load `flow-comet-test` during this Node and record completed check `required-ski
|
|
|
164
179
|
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
165
180
|
|
|
166
181
|
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-review`)无需重复加载,仅需运行下方对应声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-test` 为本节点 Required Skill Call,每次 review **必须用 Skill 工具加载**。
|
|
167
|
-
2.
|
|
182
|
+
2. 加载完成后**立即**运行声明命令,每个协议文件对应一条(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板(review → `REVIEW.md` + `TEST.md`,两条命令各写全清单):
|
|
168
183
|
|
|
169
184
|
```bash
|
|
170
|
-
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-review --prompt flow-kit/prompts/6-review.md
|
|
171
|
-
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-test --prompt flow-kit/prompts/5-test.md
|
|
185
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-review --prompt flow-kit/prompts/6-review.md --templates REVIEW.md,TEST.md
|
|
186
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load review flow-comet-test --prompt flow-kit/prompts/5-test.md --templates REVIEW.md,TEST.md
|
|
172
187
|
```
|
|
173
188
|
|
|
174
189
|
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
@@ -201,7 +216,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record review '{"summa
|
|
|
201
216
|
| `review-evidence` | REVIEW.md exists | artifact-exists |
|
|
202
217
|
| `critical-resolved` | 0 unacknowledged Critical items | 执行纪律(review 把关),guard 不校验 |
|
|
203
218
|
| `no-code-changes` | Reviewer did not modify code files | 执行纪律(review 把关),guard 不校验 |
|
|
204
|
-
| `test-pyramid-checked` | TEST.md 5
|
|
219
|
+
| `test-pyramid-checked` | TEST.md 5 轮金字塔的结构在场(各轮 H2 标题 + 结构子段)+ REVIEW 的 `### 2.0` 完整性小节 | 结构级(`### 2.0` 子段由 REVIEW 模板骨架在本出口强制;`TEST.md` 骨架由 verify 出口按登记表校验——缺席即 BLOCKED,条件轮写 `N/A` 放行);5 轮内容质量仍由 review 自己把关 |
|
|
205
220
|
|
|
206
221
|
## Exit Check
|
|
207
222
|
|
|
@@ -17,9 +17,19 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
|
|
|
17
17
|
|
|
18
18
|
### 必填段清单(结构+存在级)
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
|
20
|
+
段形唯一权威 = `flow-kit/templates/SUMMARY.md` + 登记表 `../flow-comet/reference/artifact-templates.json`(模板缺席时出口输出「未校验(模板缺失)」)。
|
|
21
|
+
|
|
22
|
+
| 文件 | 无条件段(缺席 = BLOCKED) | 条件段与增量段(在场才校验 / 位置按登记表) |
|
|
23
|
+
|------|---------------------------|-------------------------------------------|
|
|
24
|
+
| SUMMARY.md | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 是否触发新工作` / `## 完成判定` | 条件段:`## 数据库迁移`(涉 schema 变更)/ `## 破坏性变更` / `## 决策与偏离`——标题必须在场,不涉及时写「不适用」;增量段:`## 自检方法`(紧随 `## 越界检查` 或位于骨架段之后,须声明自检方法名)与 `## LESSONS 扫描`(紧随自检方法之后或文末,逐条回应命中的 `L-NNN`),两者均必填 |
|
|
25
|
+
|
|
26
|
+
声明本次读到的模板:
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-subagent-execute --prompt flow-kit/prompts/4-dev.md --templates SUMMARY.md
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
加载顺序:先 `READ PROMPT:`(步骤权威),有模板的节点再 `READ TEMPLATE:`(段形权威);design 前端另有一行条件提示词 `2a-ui-design`。
|
|
23
33
|
|
|
24
34
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
35
|
|
|
@@ -37,19 +37,21 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
|
|
|
37
37
|
|
|
38
38
|
### 必填段清单(结构+存在级)
|
|
39
39
|
|
|
40
|
-
|
|
|
41
|
-
|
|
42
|
-
| SUMMARY.md | `## verify
|
|
40
|
+
| 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
|
|
41
|
+
|------|------|------|
|
|
42
|
+
| `SUMMARY.md` | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出(必填)` / `## 6 维自查`(须含实质内容)/ `## 越界检查(必填)` / `## 是否触发新工作` / `## 完成判定`;首部四字段 `Change ID` / `Task ID` / `完成时间` / `AI 角色` 必填 | **条件段**:`## 数据库迁移(涉及 schema 变更必填)` / `## 破坏性变更(涉及破坏性改动必填)` / `## 决策与偏离(如有)`——标题必须在场,不适用写 `N/A`;**增量段**:`## 自检方法`(整段必填,紧随 `## 越界检查` 或文末)、`## LESSONS 扫描`(整段必填,紧随 `## 自检方法`) |
|
|
43
43
|
|
|
44
|
-
> **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法`
|
|
44
|
+
> **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**,否则新 change 的 exit 会被 BLOCKED。
|
|
45
45
|
>
|
|
46
46
|
> **无 parallel 任务时**:若路由到此节点但 TASK.md 无 `parallel="true" status="pending"` 任务(如全部任务已被 execute 串行处理),按常规流程记录证据后直接退出(entry → record → exit),不要空转等待。
|
|
47
47
|
|
|
48
48
|
加载声明(阶段层 · 双步硬规则)见下文 Required Skill Calls 节。
|
|
49
49
|
|
|
50
|
-
guard 校验见 workflow-guard.mjs
|
|
50
|
+
guard 校验见 workflow-guard.mjs 的委托出口门禁(必填段 + 6 维自查实质内容 + 自检方法声明三值 + LESSONS 扫描段与命中核对)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 把关。
|
|
51
51
|
|
|
52
|
-
>
|
|
52
|
+
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
53
|
+
|
|
54
|
+
加载顺序:先读 `READ PROMPT:`(`4-dev`),再读 `READ TEMPLATE:`(`SUMMARY`)。
|
|
53
55
|
|
|
54
56
|
# Subagent Execute
|
|
55
57
|
|
|
@@ -72,7 +74,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
72
74
|
五要素(缺一不可):
|
|
73
75
|
|
|
74
76
|
1. **`git add -- <自己字面路径>`**:逐条字面路径(取自本任务 `write_files`),禁用 `.` / `-A` / `-u` 等宽泛形态。
|
|
75
|
-
2. **`git commit --
|
|
77
|
+
2. **`git commit -m "<消息>" -- <同一路径>`**:路径集与上一步**逐字一致**——提交只含自己的文件;消息写在 `--` **之前**(落到 `--` 之后会被当成 pathspec)。
|
|
76
78
|
3. **锁失败重试**:并发提交会撞 `index.lock` / `cannot lock ref`,**失败即重试**,不得因此改用宽泛命令。
|
|
77
79
|
4. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:它们作用于整个共享工作区。
|
|
78
80
|
5. **为什么**:并发写者共享**同一索引与工作树**,宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 还会直接破坏同伴的未提交工作。
|
|
@@ -98,6 +100,24 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
98
100
|
|
|
99
101
|
> **要核对授权留痕 / 轮次与续轮审计 / 备份指纹 / 归档侧重入边界时读 `../flow-comet/reference/fix-loop.md`**:受控重入的完整规格在该文件。
|
|
100
102
|
|
|
103
|
+
### 节点视图三字段(currentNode / stateCurrentNode / routeNode)
|
|
104
|
+
|
|
105
|
+
`status` 与 `next` 读的是同一份节点视图,但三个字段各说一件事,不能互相替代:
|
|
106
|
+
|
|
107
|
+
- **currentNode** = **产物推导**的节点(按 `.specs/<change-id>/` 的工件推导出「按文件看现在在哪」;语义逐字未变);
|
|
108
|
+
- **stateCurrentNode** = **state 文件原值**(`.flow-comet/flow-comet-state.json` 里 `currentNode` 的原样读数,由 entry / exit / advance / reenter 写入;语义逐字未变);
|
|
109
|
+
- **routeNode** = **路由视图**(经「进行中保护」/ Fix 受控归位后的节点;常规路径下等于 `next` 的 `NODE:` 行,决定你现在该推进哪个节点)。
|
|
110
|
+
|
|
111
|
+
三者不一致不是 bug,而是同一事实的三个视角:`ROUTE:` 行给出 `derived=… state=… route=…` 的对账(derived = 产物推导、state = state 原值、route = 路由视图)与下一步动作。**Fix 批次以 `FIX-BATCH` 行与 `next` 的 `NODE` 为准**——归位目标就是你要先跑出口的节点;预检与出口都跑在那个节点上,不要按 `stateCurrentNode` 或 `currentNode` 自行改道。
|
|
112
|
+
|
|
113
|
+
**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:
|
|
114
|
+
|
|
115
|
+
- **currentNode** = artifact-derived (the node derived from the artifacts under `.specs/<change-id>/`, i.e. "where the files say we are"; semantics unchanged);
|
|
116
|
+
- **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);
|
|
117
|
+
- **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).
|
|
118
|
+
|
|
119
|
+
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`.
|
|
120
|
+
|
|
101
121
|
### Prerequisites
|
|
102
122
|
|
|
103
123
|
- `.specs/<change-id>/TASK.md` must exist with at least one task marked `parallel="true"` and `status="pending"`.
|
|
@@ -117,7 +137,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
117
137
|
|
|
118
138
|
1. **Identify parallel tasks**: Read TASK.md and find all tasks with `parallel="true"` and `status="pending"`. Verify they are genuinely independent (no file conflicts between them — check `write_files` do not overlap).
|
|
119
139
|
|
|
120
|
-
2. **For each parallel task, create handoff request**: Use `workflow-handoff.mjs request <task-id>` to register the handoff. **委托即记 request
|
|
140
|
+
2. **For each parallel task, create handoff request**: Use `workflow-handoff.mjs request <task-id>` to register the handoff. **委托即记 request(机制保证,不是经验之谈)**——`result` 在写盘前校验该任务存在 request 记录:缺失时新 change **BLOCKED**(state 字节零改写),并给出恢复指引「先照抄下面的命令记录委托(`description` 可省略),再重录 result」——命令形如 `node ".claude/skills/flow-comet/scripts/workflow-handoff.mjs" request T02`(设计形态,安装时脚本根按平台改写;引擎打印的就是带真实路径与任务号的那一行——脚本路径整条加引号,整行可直接执行);旧 change 只 WARN。零提交的 result 与只交自身 `<task-id>-SUMMARY.md` 的 result 两种形态同样被拦——该校验先于零提交语义与提交子集校验,那两者都从 request 取范围,因此不存在「先记 result 再补 request」的可行顺序。
|
|
121
141
|
> 若不传 `--write-files`,脚本会自动从 TASK.md 对应 task 的 `<write_files>` 块解析(orchestrator 无需手动从 TASK.md 提取文件列表)。
|
|
122
142
|
**归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——并行 pending 任务只归属本节点,串行 pending 任务归属 `execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
|
|
123
143
|
The handoff prompt must include:
|
|
@@ -129,12 +149,16 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
129
149
|
- Explicit requirement to return `completedChecks` in the Return Contract containing `required-skill:subagent-execute.flow-comet-dev`(证明已加载 implementation skill;guard W1-D 严格校验,缺失 → exit BLOCKED,无旧 change 豁免)。Skill 工具不可用而走降级时该条目标记仍按契约回传,但必须与 `skillToolFallback` 降级声明并排出现——只回传标记而无声明视为不实声明,orchestrator 不得记录 result。
|
|
130
150
|
- The task's `read_files` and `write_files` boundaries.
|
|
131
151
|
- Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
|
|
152
|
+
- **写前读模板(固定句式)**:「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成。
|
|
132
153
|
- **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
133
154
|
|
|
134
|
-
- **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit --
|
|
155
|
+
- **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit -m "<消息>" -- <同一路径>`(消息在 `--` 之前),锁失败重试,禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。
|
|
135
156
|
- **集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`;降级 `cherry-pick` 必须记因;集成顺序按 `depends_on` 拓扑序 + 同层 task id 升序;冲突按**机械冲突 / 语义冲突**两类分别处置(后者必须中止并上抛)。
|
|
136
157
|
|
|
137
|
-
3. **Delegate to subagents**(三平台同一判据,差异只在谁建树):
|
|
158
|
+
3. **Delegate to subagents**(三平台同一判据,差异只在谁建树):
|
|
159
|
+
**委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request` 与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(新 change BLOCKED,恢复句见步骤 2)。
|
|
160
|
+
**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 (a new change blocks, recovery line in step 2).
|
|
161
|
+
**Claude Code 平台**:直接委托子代理——守卫按**身份判据优先于路径判据**放行(载荷含 `agent_id` ⇒ 子代理语义);`Agent` 工具的 `isolation: "worktree"` 是属性①的一种实现(**可选,非强制**,见「并行安全四属性契约」);`.claude/worktrees/**` 路径前缀通道仍为兼容通道。**dsh 平台**:直接委托平台进程内子代理——守卫按会话身份分派(身份深度为正整数 ⇒ 放行(**最小保护集除外**)、项目内任意路径可写(含 gitignored)),**无需隔离区**;同一工作区的并行子代理会看到彼此未提交中间态,靠 `write_files` 边界互斥与提交时点作相互隔离纪律(**无需隔离区 ≠ 无需边界**)。**Codex 平台**:直接委托原生子代理(`spawn_agent` 等)——守卫按身份分派放行(真机实测:载荷含 `agent_id` / `agent_type`);默认**共享工作区**,同样靠 `write_files` 边界互斥与提交时点纪律。**建树选择的适用面**:协调者显式 `git worktree add <路径>`(手工建树)**是受支持的建树选择**——在委派 prompt 里指定 `workdir`,写入由身份通道放行(原生子代理无自动建树);**以建树绕过边界**不受支持——用独立树规避协调者禁令 / 最小保护集 / `write_files` 互斥与提交时点纪律 / handoff 与 Return Contract 证据,或把 worktree 当作四属性的替代品。**不得用 File API 直写等规避通道代替**(绕过写入防线不是受支持路径)。Each subagent (all three platforms):
|
|
138
162
|
- Reads TASK.md for its specific task block.
|
|
139
163
|
- Executes the full TDD protocol (RED/GREEN/REFACTOR). **纯文档/纯配置任务无生产代码可测时,`redEvidence` 与 `greenEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态**(guard W1-D 接受此形状;不得伪造测试输出)。
|
|
140
164
|
- Greps existing abstractions (R6.4).
|
|
@@ -146,16 +170,19 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
146
170
|
- Writes `<task-id>-SUMMARY.md` to `.specs/<change-id>/`.
|
|
147
171
|
- Returns evidence via `workflow-handoff.mjs result <task-id>`.
|
|
148
172
|
|
|
149
|
-
4.
|
|
173
|
+
4. **每任务预检(`--preflight` · 只报结构问题)**:每个子代理回传、`workflow-handoff.mjs result` 记下之后立即运行 `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit subagent-execute --preflight` —— 它只跑**结构性门禁**(本节点声明工件的存在性 / SUMMARY 关键段 / 模板保真骨架 / 入口工件骨架〔在场才查〕/ TASK 7 字段〔仅 `plan` 节点生效〕),**不跑**进展类门禁(证据、任务集签名、串行 pending、可委托并行、在飞委托、verify 命令执行),不推进状态、不写 state、也不写模板提示账本。**本家族的预检作用域** = 本节点声明工件的存在性(协议声明的 file 类产物,缺件即 BLOCK,逐项给出路径与模板指针)+ SUMMARY 关键段 + 模板保真骨架 + 入口三件(`CHANGE` / `REQUIREMENT` / `DESIGN`,存在才查);TASK 7 字段是 plan 出口的判据,对 subagent-execute 家族是 no-op,不在本步骤的范围内。**预检通过 = 结构面通过,不代表进展门禁会通过**(推进仍由完整 exit / `--apply` 决定)。价值:在「result 已记、尚未标 done」这个时点就能当场看到该任务 SUMMARY 的缺段 / 结构子段 / 条件段 / 首部字段问题——这正是本步骤存在的通道;不跑预检,这些问题会被更早的进展门禁挡下(可委托并行 / 在飞委托先于模板保真),攒到节点收尾一起爆。边界:它只报结构问题;**完整 `exit`(不带 `--apply`)仍是节点收尾的全链预演**——会先报进展类问题(可委托并行 / 在飞委托 / 证据),预检不替代它。它只读、不写提示账本,因此**缺 H2 段只报类别计数**;结构子段与父段写法建议照常点名。要看被计数的那些段名,请等节点收尾的完整 `exit`(它维护提示账本),或直接按模板逐段对照。
|
|
174
|
+
**Per-task preflight (`--preflight`, structural only)**: after each subagent returns and its result is recorded, run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit subagent-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 subagent-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 (delegable parallel tasks / in-flight handoffs precede template fidelity) 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 (delegable parallel tasks / in-flight handoffs / 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.
|
|
175
|
+
|
|
176
|
+
5. **Collect evidence**: After all subagents complete, verify each returned:
|
|
150
177
|
- SUMMARY.md exists in `.specs/<change-id>/` and is **模板保真**(按 `flow-kit/templates/SUMMARY.md`:标题 `# SUMMARY:` / 首部 4 字段 / 段序一致,含 `## 自检方法` 段)。
|
|
151
178
|
- Verify output is real (not fabricated).
|
|
152
179
|
- Handoff evidence is recorded.
|
|
153
180
|
|
|
154
|
-
|
|
181
|
+
6. **Mark done**: Update TASK.md — set `status="done"` for all completed parallel tasks.
|
|
155
182
|
|
|
156
|
-
|
|
183
|
+
7. **Record overall evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record subagent-execute '<evidence JSON>'` to record completion.
|
|
157
184
|
|
|
158
|
-
|
|
185
|
+
8. **Exit check**: Run exit check.
|
|
159
186
|
|
|
160
187
|
## Return Contract(子代理必须回传)
|
|
161
188
|
|
|
@@ -198,6 +225,7 @@ This node is truly done when:
|
|
|
198
225
|
- **Agent thought**: "Subagent can figure out what to do from context." **Actual risk**: Subagent not loading `flow-comet-dev` means it skips TDD, LESSONS scan, diff boundary check, and self-review. The handoff prompt must explicitly require flow-comet-dev.
|
|
199
226
|
- **Agent thought**: "Subagent might need to touch related files for context." **Actual risk**: Subagent exceeding `write_files` boundaries creates merge conflicts with other parallel subagents. Strict boundary enforcement is mandatory.
|
|
200
227
|
- **Agent thought**: "One subagent finished, mark it done immediately." **Actual risk**: Marking tasks done before all subagents complete can cause issues if a later subagent fails and needs to reference completed work. Wait for all, then batch mark.
|
|
228
|
+
- **Agent thought**: "同时发 request 和启动子代理,省一个来回。" **Actual risk**: 先让 request 成功,再启动子代理——禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all`);这是执行纪律,不是机制拦截(平台层没有挂点,引擎不替你排队)。与它相邻的另一件事已是机制保证:`result` 在写盘前校验该任务有 request 记录,缺失即新 change 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.
|
|
201
229
|
|
|
202
230
|
## Entry Check
|
|
203
231
|
|
|
@@ -218,10 +246,10 @@ The subagent-execute node identifies all `parallel="true"` pending tasks in TASK
|
|
|
218
246
|
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
219
247
|
|
|
220
248
|
1. **用 Skill 工具加载** `flow-comet-dev`。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-dev 指令生效的是 Skill 工具把它注入本次会话。本节点的 flow-comet-dev 为 handoff scope——协调者在此声明(声明标记的自动补写不覆盖 handoff scope,必须手动声明),各子代理在各自会话按 `flow-kit/prompts/4-dev.md` 协议用 Skill 工具加载并执行;协调者构造 handoff prompt 时按 `flow-kit/prompts/4-dev.md` + `flow-kit/templates/SUMMARY.md` 引用子代理的 dev 协议与交付模板。
|
|
221
|
-
2.
|
|
249
|
+
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板(subagent-execute → `SUMMARY.md`):
|
|
222
250
|
|
|
223
251
|
```bash
|
|
224
|
-
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-dev --prompt flow-kit/prompts/4-dev.md
|
|
252
|
+
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-dev --prompt flow-kit/prompts/4-dev.md --templates SUMMARY.md
|
|
225
253
|
```
|
|
226
254
|
|
|
227
255
|
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
|
|
@@ -7,7 +7,7 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 plan 节点提供 flow-kit 的 TASK 拆解流程。
|
|
9
9
|
|
|
10
|
-
>
|
|
10
|
+
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
11
|
|
|
12
12
|
## 加载
|
|
13
13
|
|
|
@@ -22,10 +22,11 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
|
|
|
22
22
|
- **[P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行串行任务的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口;共享工作区以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为相互隔离纪律
|
|
23
23
|
- **四属性可满足(并行安全契约)**:标 `[P]` 的任务须确认**并行安全四属性**(① 写权限 · ② 提交隔离 · ③ 验证隔离 · ④ 集成纪律)可满足——worktree 只是「① 写权限」的实现之一,不是前提;四属性的**含义与三平台通道**以入口册「并行委派契约(四属性)· 三平台通道」为单一来源,本册只点名不复述
|
|
24
24
|
- 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;硬性拦截(规划出口 BLOCKED,附恢复指引):任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见第 3 条;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)——任一项不成立即被拦(读写重叠仅 WARN),修正后重新 exit 即可通过;跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
|
|
25
|
+
- **波次 = 依赖层级的投影(波次编号的判据)**:每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);同波任务必须彼此没有依赖;想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 新 change 在 plan 出口 **BLOCKED**,明细逐条点名「任务 / 依赖 / 当前波 / 应到波」并给两条恢复出路:把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来;旧 change 只 WARN。判不了按成因二分——载体缺席(`## 波次划分` 不在 / 段名无从派生)→ 出口打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);内容不可判(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数)。另:TASK 里的每个非修复族任务都必须被某个 Wave 行覆盖——修复族不要求排进波次,漏写的任务在明细里以「未声明」的当前波被点名。`replan` 重校走同一判据、同一报文。本条只要求「波次编号与依赖层级一致」,与上面的混排合法化并存——不恢复旧的「并行块必须连续成组」形态约束
|
|
25
26
|
- 依赖:`depends_on: <task-id>`
|
|
26
27
|
3. **每任务 7 字段**:name / read_files / write_files / action / verify / done / depends_on——与 plan 出口「新格式任务的 7 字段在场」判据同一集合;`id` **不是字段**,它是 `<task>` 元素的属性(`<task id="T01" parallel="true" status="pending">`);`depends_on` 元素必在(无依赖写空元素)
|
|
27
28
|
- **write_files 必须包含关联测试文件**:若任务修改组件/函数,且有关联测试直接 import 其本地导出(如 `src/**/__tests__/*.test.ts` 从组件文件 import),该测试文件**必须纳入该任务 write_files**。否则组件删除本地导出/改 import 后,关联测试会编译失败或断言失效(实测:改组件时破坏了关联测试文件)。
|
|
28
|
-
4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P]
|
|
29
|
+
4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P],孤立任务一律串行;**波次编号是依赖层级的投影**——层 = 1 + 依赖中最晚层(无依赖 = 第 1 波),写出「无依赖 / 第 N 波」的对应关系,不要用挪动波次代替依赖声明(判据与恢复指引见第 2 条同名条目);flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
|
|
29
30
|
5. **XML 格式**:便于 AI 解析与执行
|
|
30
31
|
|
|
31
32
|
## 产物
|
|
@@ -7,12 +7,16 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 review 节点提供 flow-kit 的 5 轮测试金字塔。
|
|
9
9
|
|
|
10
|
-
>
|
|
10
|
+
> **模板权威**:本技能产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
11
|
|
|
12
12
|
## 加载
|
|
13
13
|
|
|
14
14
|
读取 `flow-kit/prompts/5-test.md` 并按其执行。
|
|
15
15
|
|
|
16
|
+
## 上游段表不采用(覆盖声明)
|
|
17
|
+
|
|
18
|
+
`flow-kit/prompts/5-test.md` 把「本次测试范围声明」写成职责小节里的一个 H2,且其 H3 编号与模板错位(例:1.3 覆盖率与边界、1.4 测试质量自检、2.2 前端性能、4.2 数据迁移、5.2 指标与追踪、5.3 告警与健康检查)——**这组 H3 编号不采用**:H2 / H3 的段名与段序一律以 `flow-kit/templates/TEST.md` 为准(`第 2 轮` ~ `第 5 轮` 是标题必须在场的条件段,不适用写 `N/A`)。
|
|
19
|
+
|
|
16
20
|
### 5 轮测试金字塔
|
|
17
21
|
|
|
18
22
|
| 轮次 | 内容 | 适用性 |
|
|
@@ -40,4 +44,4 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
|
|
|
40
44
|
|
|
41
45
|
## 使用范围
|
|
42
46
|
|
|
43
|
-
TEST.md
|
|
47
|
+
TEST.md 的**结构在场**由 **verify 出口**按登记表骨架校验(5 轮 H2 与结构子段,条件轮写 `N/A` 放行);**5 轮内容质量**由 review 节点第 2 轮检查(`### 2.0 TEST.md 5 轮金字塔完整性` 小节)。brooks-lint 已装时用 `/brooks-test`(Codex 用 `$brooks-test`),未装时用内置清单。
|
|
@@ -29,7 +29,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
29
29
|
|---|---|---|
|
|
30
30
|
| 段在场,段内出现**结构形态**的「不适用」标记 | 非前端 change | **显式跳过**:不加载、不产出;design 出口打印 `UI-DESIGN: skipped(非前端)` 与命中片段后放行 |
|
|
31
31
|
| 段在场,无**结构形态**的「不适用」标记 | 前端 change | 必须加载本技能并产出 `.specs/<change-id>/UI-DESIGN.md` |
|
|
32
|
-
| 段缺席 |
|
|
32
|
+
| 段缺席 | **新 change:拦**(条件段标题必须在场——缺席即 BLOCKED,须显式标注「不适用」或填写调性)· **旧 change:兼容**(沿用旧口径判非前端,出口打印 `UI-DESIGN: skipped(旧 change 兼容)`) | 新 change 先回 open 补段;旧 change 保持原行为,不追溯 |
|
|
33
33
|
|
|
34
34
|
**「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、行尾,或下列标点之一:`,。;、,;.::!!??…—()()【】「」『』“”"'`——**只有这一组**,组外的标点如 `/`、`-` 不算边界),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
|
|
35
35
|
|
|
@@ -42,7 +42,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
|
|
|
42
42
|
`design` 节点对本技能的绑定等级 = **guarded**(见 `../flow-comet/reference/workflow-protocol.json` 的 `requiredSkillCalls`)。前端 change 的完整动作是**先加载、再声明、后干活**:
|
|
43
43
|
|
|
44
44
|
1. 用 Skill 工具加载本技能(只读取 SKILL.md 文件不叫加载);
|
|
45
|
-
2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md
|
|
45
|
+
2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md --templates DESIGN.md`(`--templates` 声明 design 节点的产出物模板;前端要一并声明 UI-DESIGN 时写 `--templates DESIGN.md,UI-DESIGN.md`);
|
|
46
46
|
3. 把 `required-skill:design.flow-comet-ui-design` 记进 design 节点的 evidence(`record` / handoff 载荷)。
|
|
47
47
|
|
|
48
48
|
design 出口的核对口径:
|
|
@@ -17,16 +17,18 @@ This node performs the final integration verification: running all automated tes
|
|
|
17
17
|
|
|
18
18
|
### 必填段清单(结构+存在级)
|
|
19
19
|
|
|
20
|
-
|
|
|
21
|
-
|
|
22
|
-
| TEST.md | `##
|
|
23
|
-
| UAT.md | `## 验收结果`
|
|
20
|
+
| 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
|
|
21
|
+
|------|------|------|
|
|
22
|
+
| `TEST.md` | `## 验证命令`(本仓登记的**增量段**,必填,位置不限但标题后必须紧跟代码块)——exit verify 真实执行其中的命令并计数失败 | `TEST.md` 的 5 轮 H2 与结构子段**在本出口**按登记表骨架校验(`flowkit.verify.v1` 的 artifacts 含 TEST.md;UAT 未登记 → 跳过)。verify 的**模板声明**为空集,但结构校验来自节点 `outputSchemas`,不来自模板声明 |
|
|
23
|
+
| `UAT.md` | **仅存在性**——guard 只查 `.specs/<change-id>/UAT.md` 在场(UAT 无上游模板,不校验段名与段序) | `## 验收结果` 等段:格式与内容由 UAT 执行与 review 把关,guard 不判段名 |
|
|
24
24
|
|
|
25
|
-
> **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet
|
|
25
|
+
> **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet 登记的增量段(exit verify 会真实执行其中的命令并计数失败)。使用 `flow-kit/templates/TEST.md` 填写后,**必须按上方右栏补写 `## 验证命令` 段**,否则 exit verify 会被 BLOCKED。**排版约束**:`## 验证命令` 标题后必须**紧跟**代码块(` ``` `),标题与代码块之间**不得插入任何说明行**(如 blockquote 说明——guard 正则要求标题后直接是代码块);段名可带括号后缀。UAT.md 同理:flow-kit 无独立 UAT 模板(UAT 脚本格式见 5-test.md 1.2 节),本出口只查文件在场——`## 验收结果` 段按惯例填写,格式由 UAT 执行与 review 把关。
|
|
26
26
|
|
|
27
|
-
guard 校验见 workflow-guard.mjs
|
|
27
|
+
guard 校验见 workflow-guard.mjs 的 verify 出口门禁(`## 验证命令` 增量段真实执行 + 失败计数 + LESSONS 条目形态与条目区);UAT.md 只查存在性,「填得好不好」由 review 与 UAT 执行把关。
|
|
28
28
|
|
|
29
|
-
>
|
|
29
|
+
> **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
30
|
+
|
|
31
|
+
本节点零模板:只有 `READ PROMPT:`(`7-integration`),没有 `READ TEMPLATE:`。
|
|
30
32
|
|
|
31
33
|
### Prerequisites
|
|
32
34
|
|
|
@@ -120,6 +122,8 @@ Load `flow-comet-integration` during this Node and record completed check `requi
|
|
|
120
122
|
node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load verify flow-comet-integration --prompt flow-kit/prompts/7-integration.md
|
|
121
123
|
```
|
|
122
124
|
|
|
125
|
+
> **零模板节点省略 `--templates`**:verify 的产出物模板映射为空(UAT.md 无上游模板;TEST.md 的结构校验在 verify 出口(本节点),review 只做 5 轮完整性过程检查),命令**不带** `--templates`——省略即视为空集,与节点映射一致并通过;不要「为保险」补一个模板名(多写会与映射不一致而被拦)。
|
|
126
|
+
|
|
123
127
|
> **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做。
|
|
124
128
|
|
|
125
129
|
## Augmentations
|
|
@@ -151,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record verify '{"summa
|
|
|
151
155
|
| `verify-evidence` | UAT.md exists | artifact-exists |
|
|
152
156
|
| `automation-passed` | All automated checks pass (real output) | 执行纪律(review 把关),guard 不校验 |
|
|
153
157
|
| `retry-limit` | No more than 3 auto-retries(机器计数 verifyFailures,第 4 次 BLOCKED) | process-check |
|
|
154
|
-
| `lessons-nominated` | LESSONS.md
|
|
158
|
+
| `lessons-nominated` | LESSONS.md 条目形态与条目区合规(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 结构级(guard 强制:本出口校验 `.specs/LESSONS.md` 的条目写 `### L-NNN`、位于条目区、编号升序——新 change 违反即 BLOCKED,旧 change WARN);「是否有合格条目」由执行者把关,归档时另以 `evidence.lessonsNomination` 核对 |
|
|
155
159
|
|
|
156
160
|
## Exit Check
|
|
157
161
|
|
package/README.md
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat" alt="License: MIT" /></a>
|
|
13
13
|
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
|
|
14
14
|
<a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI status" /></a>
|
|
15
|
-
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.
|
|
15
|
+
<a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.7.0-blue.svg" alt="Version 1.7.0" /></a>
|
|
16
16
|
</p>
|
|
17
17
|
|
|
18
18
|
<p align="center">
|
|
@@ -118,7 +118,7 @@ Driving a node by hand, the artifacts each node produces, and the two command su
|
|
|
118
118
|
|
|
119
119
|
| Project | What it is, and how it works | Relationship to flow-comet |
|
|
120
120
|
|---|---|---|
|
|
121
|
-
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer and
|
|
121
|
+
| **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer: templates, rules and artifact shapes are inherited from upstream, and this repository only adds the increment sections upstream does not define; the template is the sole authority on shape, and documents without an upstream template (`UAT`, the archive's leftovers list) are checked for existence only. The projects below reached flow-comet through it. |
|
|
122
122
|
| **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding. One `proposal` / `specs` / `design` / `tasks` set per change under `openspec/`; the default profile runs propose → apply → sync → archive. | **Aggregated through flow-kit** (idea source). Standalone it stays lighter: no state machine, no gates. |
|
|
123
123
|
| **Superpowers** (obra) | Agentic skills framework plus a full development methodology, installed per harness across Claude Code, Codex, Cursor, Gemini CLI and more. Skills trigger by context and are enforced by instructions. | **Aggregated through flow-kit** (idea source, partial overlap). Discipline lives in skill text and relies on model compliance; flow-comet machine-checks the same discipline. |
|
|
124
124
|
| **comet** (rpamis) | Resumable long-running task workflow and skill platform: a five-stage state machine, stage guards, hook write-interception. `/comet` routes from config and defaults to its Native branch. | **Early mechanism reference, now decoupled.** The hook-injection shape and script-owned state came from here; the naming was decoupled and state does not interoperate. Only its Classic branch carries the OpenSpec + Superpowers lineage. |
|
|
@@ -156,7 +156,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
|
|
|
156
156
|
|
|
157
157
|
1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
|
|
158
158
|
2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
|
|
159
|
-
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL
|
|
159
|
+
3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 350 SCENARIOS PASSED`
|
|
160
160
|
4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
|
|
161
161
|
|
|
162
162
|
CI enforces the repository conventions automatically on every PR and push: regression, installer reproducibility, workflow and bilingual-mirror quality, PR discipline, version consistency, and dead links. Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "flow-comet",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.7.0",
|
|
4
4
|
"description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
package/scripts/dsh-bridge.mjs
CHANGED
|
@@ -38,7 +38,7 @@
|
|
|
38
38
|
// 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
|
|
39
39
|
// ESM 模块导出 { name, apply },ctx 由 dsh 注入。
|
|
40
40
|
//
|
|
41
|
-
// BRIDGE_VERSION: 1.
|
|
41
|
+
// BRIDGE_VERSION: 1.7.0
|
|
42
42
|
|
|
43
43
|
import { spawn } from 'node:child_process';
|
|
44
44
|
import { existsSync, readFileSync, realpathSync } from 'node:fs';
|
|
@@ -50,7 +50,7 @@ import path from 'node:path';
|
|
|
50
50
|
// 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
|
|
51
51
|
// bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
|
|
52
52
|
export const name = 'dsh-flow-comet-bridge';
|
|
53
|
-
export const version = '1.
|
|
53
|
+
export const version = '1.7.0';
|
|
54
54
|
|
|
55
55
|
// guard 在项目内的相对路径常量(随 skill 包分发)。
|
|
56
56
|
const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
|