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.
Files changed (89) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +32 -18
  3. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +2 -2
  4. package/.flow-comet/skills/flow-comet/reference/decision-points.md +5 -5
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +30 -11
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +4 -4
  8. package/.flow-comet/skills/flow-comet/reference/init-detection.md +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +2 -2
  10. package/.flow-comet/skills/flow-comet/reference/post-archive-handoff.md +264 -0
  11. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -1
  12. package/.flow-comet/skills/flow-comet/reference/replan.md +1 -1
  13. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +1 -0
  14. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +270 -30
  15. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  16. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
  17. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +122 -11
  18. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +79 -40
  19. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +11 -9
  20. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  21. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +1 -1
  22. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +128 -56
  23. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +357 -3
  24. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +26 -1
  25. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +6 -2
  26. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +29 -21
  27. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +4 -15
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +357 -219
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +725 -309
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +182 -54
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +224 -83
  35. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +17 -28
  36. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +61 -33
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +663 -205
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +68 -9
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +11 -4
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +232 -11
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +140 -74
  46. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +8 -4
  47. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  48. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +0 -3
  49. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +248 -24
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +63 -3
  51. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +181 -8
  52. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +340 -0
  53. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +132 -20
  54. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +12 -5
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1564 -54
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1489 -38
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1466 -243
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +743 -24
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +220 -92
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +657 -21
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +41 -27
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +285 -9
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +7 -6
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +21 -15
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +8 -5
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +45 -36
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +2 -2
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2381 -85
  69. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -2
  70. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
  71. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +339 -103
  72. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  73. package/.flow-comet/skills/flow-comet-archive/SKILL.md +33 -11
  74. package/.flow-comet/skills/flow-comet-change/SKILL.md +1 -1
  75. package/.flow-comet/skills/flow-comet-design/SKILL.md +5 -3
  76. package/.flow-comet/skills/flow-comet-dev/SKILL.md +2 -2
  77. package/.flow-comet/skills/flow-comet-execute/SKILL.md +37 -13
  78. package/.flow-comet/skills/flow-comet-integration/SKILL.md +10 -4
  79. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  80. package/.flow-comet/skills/flow-comet-plan/SKILL.md +13 -6
  81. package/.flow-comet/skills/flow-comet-review/SKILL.md +21 -12
  82. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +1 -1
  83. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +43 -18
  84. package/.flow-comet/skills/flow-comet-task/SKILL.md +4 -2
  85. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  86. package/.flow-comet/skills/flow-comet-verify/SKILL.md +1 -1
  87. package/README.md +2 -2
  88. package/package.json +1 -1
  89. package/scripts/dsh-bridge.mjs +238 -21
@@ -21,11 +21,13 @@ This node performs a structured multi-round review of the implemented change, ch
21
21
  |------|------|------|
22
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
- 发现写在模板外的 `## 发现` 而 `### 2.2` 无条目 → 新 change BLOCKED(条目记录在非模板位置等于静默丢弃);**Major `[转待办]` 须有用户裁决记录**(同段、文末或单独段落「用户裁决:接受延期」+ 指向该条目 + `[升级]` 承接——单独段落与条目以空行分隔、位置不限),缺失新 change BLOCKED / 旧 change WARN 渐进。
24
+ 发现写在模板外的 `## 发现` 而 `### 2.2` 无条目 → 一律 BLOCKED(条目记录在非模板位置等于静默丢弃);**任何严重度的 `[转待办]` 都须有用户裁决记录**(同段、文末或单独段落「用户裁决:接受延期」+ 指向该条目 + `[升级]` 承接——单独段落与条目以空行分隔、位置不限),缺失一律 BLOCKED(同一形态一个判级);**每条判为 Minor 的发现都要在条目块内写 `判 Minor:<一句话理由>`**(判据见下方「处置标记」条),与处置标记无关——缺这行同样一律 BLOCKED(同一形态一个判级)。
25
25
 
26
26
  本出口**声明加载** `TEST.md` 并做 **5 轮完整性过程检查**(细目见 `flow-comet-test` 册);`TEST.md` 的**结构骨架校验在 verify 出口**(`flowkit.verify.v1`),不在本出口——`## 验证命令` 增量段的执行与校验同样在 verify 出口。
27
27
 
28
- guard 校验见 workflow-guard.mjs 的 review 出口门禁(发现区处置标记 / 发现位置 / Major 延期裁决 / 模板骨架)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 自身把关。
28
+ **AC 覆盖**在这里只做汇总提示:`REQUIREMENT.md` 的验收准则每条都应在 `TEST.md` 的 1.1 测试矩阵里有对应行;真缺时出口打印一行 `REVIEW WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖: AC-…`——一条汇总、不逐条刷屏、**不改变退出码**。权威判定在 verify 出口:缺覆盖 **BLOCKED**(点名编号 + 恢复句「在 TEST.md 的 1.1 测试矩阵为这些 AC 补行」;同一形态一个判级)。判不了按成因二分(与波次判据同口径):**模板缺席**(段名无从派生)→ 打印「未校验(<原因>)」且不改退出码(未验证 ≠ 通过,也不冒充通过);**内容不可判** → verify 出口打印 `AC 覆盖判据无法执行`,一律 BLOCKED(同一形态一个判级)。落在内容不可判一侧的有两种形态:承载段或段内清单读不出来(`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 自身把关。
29
31
 
30
32
  > **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
31
33
 
@@ -35,6 +37,7 @@ guard 校验见 workflow-guard.mjs 的 review 出口门禁(发现区处置标
35
37
 
36
38
  - [ ] **工件模板保真**:每份交付工件(`*-SUMMARY.md` / TASK / CHANGE / REQUIREMENT / DESIGN)的**标题 / 首部字段 / 段序**与对应模板一致——SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写并含 `## 自检方法` 段;执行者按 `flow-kit/prompts/4-dev.md` 协议交付。
37
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 出口**。
38
41
  - [ ] **Skill 工具不可用降级核验**:执行者会话具备 Skill 工具时,须见 Skill 工具加载节点 SKILL 的触发记录;不具备时(委托会话工具集无 Skill 工具),须按 Read 加载节点 SKILL + 协议,并在 Return Contract(`skillToolFallback: "<降级替代形态,如 file-read>"`)与 SUMMARY「自检方法」段显式声明——**Read 不得被声称为已注入(即未执行 Skill 工具注入,字段值必须写替代形态而非本说明)**。只回传 required-skill 标记而无降级声明 → 证据不完整,要求补声明;声明齐全的环境限制不判为代码缺陷。
39
42
 
40
43
  ### Prerequisites
@@ -75,7 +78,7 @@ guard 校验见 workflow-guard.mjs 的 review 出口门禁(发现区处置标
75
78
  3.5. **Round 2.0 — TEST.md 5-round pyramid completeness**: Before code quality, verify TEST.md:
76
79
  - All 5 rounds have clear status (no unfilled).
77
80
  - Skipped rounds have reasons.
78
- - 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: the gap blocks with the recovery line "add the rows to TEST.md's 1.1 test matrix". 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 and blocks. 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.
79
82
  - Round 2 (performance): if required, has actual/budget/baseline columns.
80
83
  - Round 3 (security): if required, has dependency/secret/SAST/OWASP records.
81
84
  - Round 4 (compatibility): if required, has browser matrix/migration/cross-version.
@@ -94,19 +97,21 @@ guard 校验见 workflow-guard.mjs 的 review 出口门禁(发现区处置标
94
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).
95
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.
96
99
 
97
- 7. **Severity grading**: Each finding gets:
100
+ 7. **Severity grading**: Each finding gets one of three grades — **Major 是默认档位**:
98
101
  - Critical (must fix: data corruption, security, AC not met)
99
- - Major (should fix: design issues, significant regression)
100
- - Minor (optional: naming, style, small refactor)
102
+ - Major (should fix: design issues, significant regression) — **默认**:拿不准就判 Major
103
+ - Minor (optional: naming, style, small refactor) — **仅当同时满足下方「Minor 的判据」全部五条**才可判;且该条目必须带一行 `判 Minor:<理由>`
101
104
 
102
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.
103
106
 
104
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:
105
108
  - `[已修]` — fixed via a fix task (linked in the entry)
106
109
  - `[升级]` — escalated to the user for a decision (accept + reason recorded)
107
- - `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time
108
- - **Major 不得由 reviewer 自行 `[转待办]`**:Major 的延期属用户决策点,reviewer 须先标 `[升级]` 等用户裁决;用户接受延期后,在同段、文末或单独段落记录「用户裁决:接受延期」并指向该条目(由 `[升级]` 承接),方可标 `[转待办]`——单独段落与发现条目以空行分隔、可位于发现区中间,位置不限(guard 按独立段落匹配,不要求位于文末)。review exit 结构校验:Major 条目标 `[转待办]` 而缺上述记录 → 新 change BLOCKED / 旧 change WARN 渐进;Minor `[转待办]` 不受影响,`[升级]` / `[已修]` 的 Major 直接放行。
109
- 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.
110
+ - `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time;**延期在任何严重度上都是用户决策点**
111
+ - **`[转待办]` 一律需用户裁决(Major 与 Minor 同一标准)**:延期不是 reviewer 能自行给出的处置。reviewer 须先标 `[升级]` 等用户裁决;用户接受延期后,在同段、文末或单独段落记录「用户裁决:接受延期」并指向该条目(由 `[升级]` 承接),方可标 `[转待办]`——单独段落与发现条目以空行分隔、可位于发现区中间,位置不限(guard 按独立段落匹配,不要求位于文末)。review exit 结构校验:条目标 `[转待办]` 而缺上述记录 → 一律 BLOCKED(同一形态一个判级);`[升级]` / `[已修]` 的条目直接放行。
112
+ - **Minor 的判据(五条全中才算 Minor,否则按 Major 处理)**:① 不改变任何行为与输出;② 不影响任何对外 / 对用户的表述(文档、报文、CHANGELOG);③ 不新增或保留第二份等价实现;④ 不削弱任何断言或测试判别力;⑤ 不涉及跨平台 / 分发形态。**不满足任一条即按 Major 处理**——举证责任在「判 Minor」的一侧,不在「判 Major」的一侧。每条判为 Minor 的发现都必须带一行判定理由,形态固定为 `判 Minor:<一句话理由,对应①~⑤>`,写在条目块内、与条目标题之间不留空行,**与处置标记无关**(`[已修]` / `[升级]` / `[转待办]` 一律要:理由落在判定当时,而不是延期时再补);缺该行 → 一律 BLOCKED(同一形态一个判级)。
113
+ - **修复回路内不得延期**:在一次修复回路里新发现的条目,只能是 `[已修]` 或 `[升级]`(交用户裁决)——即使该条目已有用户裁决的延期记录在场,也不得把修复回路新增的发现标 `[转待办]`。回路是「把本轮引入的问题收干净」的窗口,不是继续开新账的入口。
114
+ The exit guard structurally checks these markers on the findings area: a missing marker **blocks** the exit. Add markers to clear it.
110
115
 
111
116
  The full review protocol, templates, and checklists are in:
112
117
  - `flow-kit/prompts/6-review.md` (REVIEW phase)
@@ -116,7 +121,7 @@ The full review protocol, templates, and checklists are in:
116
121
 
117
122
  This node is truly done when:
118
123
  - `.specs/<change-id>/REVIEW.md` exists with all 3 mandatory rounds completed.
119
- - 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.
120
125
  - All Critical items are either fixed (fix tasks generated) or explicitly accepted with user confirmation.
121
126
  - 0 unacknowledged Critical items remain.
122
127
  - TEST.md 5-round pyramid completeness has been verified.
@@ -126,11 +131,14 @@ This node is truly done when:
126
131
 
127
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.
128
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。缺口只有一条出路:在 1.1 矩阵补行——把缺口记成发现条目不能替代补行(verify 出口按同一份矩阵判定,仍会拦);把缺口留到 verify 等于把可修的问题变成一次节点返工。
129
135
  - **Agent thought**: "I'll fix this small issue directly." **Actual risk**: Reviewer modifying code violates R3.3. Must generate fix tasks instead.
130
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.
131
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.
132
- - **Agent thought**: "I'll record this Minor and move on." **Actual risk**: Findings (especially Minor) that are recorded without a disposition marker silently disappear — the exit guard warns on missing markers; every finding must be `[已修]`, `[升级]` (user decision), or `[转待办]` (tracked for archive).
133
- - **Agent thought**: "This Major is not for this batch, I'll defer it to backlog myself." **Actual risk**: Major 延期属用户决策点——reviewer 自行 `[转待办]` 会被退出守卫拦截(新 change BLOCKED / 旧 change WARN);须先 `[升级]` 等用户裁决,用户接受延期后才可记录裁决并转待办。
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 自行 `[转待办]` 会被退出守卫拦下(一律 BLOCKED),须先 `[升级]` 等用户裁决,用户接受延期后才可记录裁决并转待办。
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**: 修复回路内新发现的条目只能 `[已修]` 或 `[升级]`——不得 `[转待办]`,即使裁决记录在场;这是纪律要求,守卫只看结构、看不出你在回路里第几轮。
134
142
 
135
143
  ## 修复回路状态机路径
136
144
 
@@ -141,6 +149,7 @@ review 发现 Critical / Major 后的修复必须回到 `execute` 节点生命
141
149
  3. **跑完 execute 四类出口**:`record execute` → `exit execute --apply`——全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致,任一缺失即 BLOCKED;通过后引擎把当前节点推回 review。
142
150
  4. **回源节点跑出口**:回到源节点后跑该节点出口门禁(`entry <源节点>` → `exit <源节点> --apply`),通过后继续 review → verify 的正常路由,必要时进入下一轮 Fix 闭环。
143
151
  5. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
152
+ 6. **回路内新发现的条目不得延期**:修复过程中(含回到 review 复检时)新发现的条目只能标 `[已修]` 或 `[升级]`(交用户裁决),**不得**标 `[转待办]`——即使已有用户裁决的延期记录在场。回路是把本轮引入的问题收干净的窗口,不是继续开新账的入口;守卫只做结构判定,这一条靠执行纪律。
144
153
 
145
154
  **何时读完整规格**:要核对完整判据——Fix 任务与任务集签名的时序、受控归位的完整判定条件、`FIX-BATCH` / `RETURN` 审计行三态语义与回源节点的回程豁免、绕过的失败面与恢复指引——读 `../flow-comet/reference/fix-loop.md`(**当你 review 发现缺陷、要开修复回路把工作退回 execute 生命周期时读它**)。
146
155
 
@@ -35,5 +35,5 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
35
35
 
36
36
  ### 委托前写写拦截(第二道锚保持)
37
37
 
38
- plan 出口已做文件级依赖检测(写写强判:新 change BLOCKED / 旧 change WARN;读写弱判:无显式 depends_on 关联对 WARN;伪并行 WARN 并存渐进)——委托前既有 write∩write 拦截**保持为第二道防线**(`BLOCKED: parallel tasks write_files 冲突`,行为与消息既有语义不变)。并行委托前仍校验本趟并行任务的 `write_files` 交集,plan 出口检测的提示/拦截不改变委托前拦截。
38
+ plan 出口已做文件级依赖检测(写写强判:一律 BLOCKED;读写弱判:无显式 depends_on 关联对 WARN;伪并行 WARN 并存)——委托前既有 write∩write 拦截**保持为第二道防线**(`BLOCKED: parallel tasks write_files 冲突`,行为与消息既有语义不变)。并行委托前仍校验本趟并行任务的 `write_files` 交集,plan 出口检测的提示/拦截不改变委托前拦截。
39
39
 
@@ -22,7 +22,7 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
22
22
  > |---|------|------|----------|
23
23
  > | ① | **写权限** | 每个写者必须有一条被守卫认可的写入通道 | **身份分派**(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) |
24
24
  > | ② | **提交隔离** | 提交只含自己 `write_files` 的字面路径 | 提交面 pathspec 纪律五要素(见 Guidance 同名小节) |
25
- > | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 新 change BLOCKED / 旧 change WARN;全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
25
+ > | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 一律 BLOCKED(同一形态一个判级);全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
26
26
  > | ④ | **集成纪律** | 机制选择 / 顺序 / 审计 / 冲突处置四项均有明文规则 | 集成纪律四要素(见 Guidance 同名小节) |
27
27
  >
28
28
  > **写面含 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`。
@@ -41,7 +41,7 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
41
41
  |------|------|------|
42
42
  | `SUMMARY.md` | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出(必填)` / `## 6 维自查`(须含实质内容)/ `## 越界检查(必填)` / `## 是否触发新工作` / `## 完成判定`;首部四字段 `Change ID` / `Task ID` / `完成时间` / `AI 角色` 必填 | **条件段**:`## 数据库迁移(涉及 schema 变更必填)` / `## 破坏性变更(涉及破坏性改动必填)` / `## 决策与偏离(如有)`——标题必须在场,不适用写 `N/A`;**增量段**:`## 自检方法`(整段必填,紧随 `## 越界检查` 或文末)、`## LESSONS 扫描`(整段必填,紧随 `## 自检方法`) |
43
43
 
44
- > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**,否则新 change 的 exit 会被 BLOCKED。
44
+ > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**,否则 exit 会被 BLOCKED。
45
45
  >
46
46
  > **无 parallel 任务时**:若路由到此节点但 TASK.md 无 `parallel="true" status="pending"` 任务(如全部任务已被 execute 串行处理),按常规流程记录证据后直接退出(entry → record → exit),不要空转等待。
47
47
 
@@ -74,7 +74,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
74
74
  五要素(缺一不可):
75
75
 
76
76
  1. **`git add -- <自己字面路径>`**:逐条字面路径(取自本任务 `write_files`),禁用 `.` / `-A` / `-u` 等宽泛形态。
77
- 2. **`git commit -- <同一路径>`**:路径集与上一步**逐字一致**——提交只含自己的文件。
77
+ 2. **`git commit -m "<消息>" -- <同一路径>`**:路径集与上一步**逐字一致**——提交只含自己的文件;消息写在 `--` **之前**(落到 `--` 之后会被当成 pathspec)。
78
78
  3. **锁失败重试**:并发提交会撞 `index.lock` / `cannot lock ref`,**失败即重试**,不得因此改用宽泛命令。
79
79
  4. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:它们作用于整个共享工作区。
80
80
  5. **为什么**:并发写者共享**同一索引与工作树**,宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 还会直接破坏同伴的未提交工作。
@@ -96,10 +96,28 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
96
96
 
97
97
  ### 受控重入打开的修复场景(archive 源)
98
98
 
99
- 缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `execute` / `review` / `verify`,再按常规委托与出口流程完成修复。命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`。要点:**每次调用都需要用户显式授权**(不得由执行者自决);每 change 上限 3 轮,达上限后凭 `--continue-round <n>`(n ≥ 已用轮次 + 1)显式续轮;重入前自动落 state 快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY:` 行与 `REASON: <text>` 行(与 `FIX-BATCH` / `RETURN` 行三态可区分)。归档移动已发生或 change 已 `completed` ⇒ 重入 BLOCKED(走人工处置或新 change,**不得静默跳过**);重入只改工作归属——不写闭合标记、不跳过本节点入口 / 出口门禁,重入后仍按本节点常规流程校验委托证据与 write_files 边界。
99
+ 缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `execute` / `review` / `verify`,再按常规委托与出口流程完成修复。命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`。要点:**每次调用都需要用户显式授权**(不得由执行者自决);每 change 上限 3 轮,达上限后凭 `--continue-round <n>`(n ≥ 已用轮次 + 1)显式续轮;重入前自动落 state 快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY:` 行与 `REASON: <text>` 行(与 `FIX-BATCH` / `RETURN` 行三态可区分)。归档移动已发生或 change 已 `completed` ⇒ 重入 BLOCKED(走人工处置或另开 change,**不得静默跳过**);重入只改工作归属——不写闭合标记、不跳过本节点入口 / 出口门禁,重入后仍按本节点常规流程校验委托证据与 write_files 边界。
100
100
 
101
101
  > **要核对授权留痕 / 轮次与续轮审计 / 备份指纹 / 归档侧重入边界时读 `../flow-comet/reference/fix-loop.md`**:受控重入的完整规格在该文件。
102
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
+
103
121
  ### Prerequisites
104
122
 
105
123
  - `.specs/<change-id>/TASK.md` must exist with at least one task marked `parallel="true"` and `status="pending"`.
@@ -119,25 +137,28 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
119
137
 
120
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).
121
139
 
122
- 2. **For each parallel task, create handoff request**: Use `workflow-handoff.mjs request <task-id>` to register the handoff. **委托即记 request**——直接记录 result 而无对应 request 时,write_files 允许列表为空会被 BLOCKED(新 change 强制委托边界),补 request 后再重录 result 即可。
140
+ 2. **For each parallel task, create handoff request**: Use `workflow-handoff.mjs request <task-id>` to register the handoff. **委托即记 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」的可行顺序。
123
141
  > 若不传 `--write-files`,脚本会自动从 TASK.md 对应 task 的 `<write_files>` 块解析(orchestrator 无需手动从 TASK.md 提取文件列表)。
124
- **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——并行 pending 任务只归属本节点,串行 pending 任务归属 `execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
142
+ **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——并行 pending 任务只归属本节点,串行 pending 任务归属 `execute`;错误节点的请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
125
143
  The handoff prompt must include:
126
144
  - The task's full XML block from TASK.md.
127
145
  - DESIGN.md sections 0 and 0.5 for context.
128
146
  - REQUIREMENT.md ACs relevant to this task.
129
147
  - Explicit instruction to **use the Skill 工具** to load `flow-comet-dev` and follow its full protocol `flow-kit/prompts/4-dev.md`(不得跳过——读取 SKILL.md 文件不叫加载,跑声明命令也不叫加载;加载 = Skill 工具把 skill 注入会话)。
130
148
  - **Skill 工具不可用时的降级口径(与上一条并排内联)**:子代理会话不具备 Skill 工具时,按 Read 加载节点 SKILL + `flow-kit/prompts/4-dev.md` 协议执行,Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`,SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入;**禁止把 Read 声称为已完成 Skill 工具注入**。
131
- - 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。
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,无豁免)。Skill 工具不可用而走降级时该条目标记仍按契约回传,但必须与 `skillToolFallback` 降级声明并排出现——只回传标记而无声明视为不实声明,orchestrator 不得记录 result。
132
150
  - The task's `read_files` and `write_files` boundaries.
133
151
  - Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
134
152
  - **写前读模板(固定句式)**:「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成。
135
- - **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
153
+ - **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
136
154
 
137
- - **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit -- <同一路径>`,锁失败重试,禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。
155
+ - **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit -m "<消息>" -- <同一路径>`(消息在 `--` 之前),锁失败重试,禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。
138
156
  - **集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`;降级 `cherry-pick` 必须记因;集成顺序按 `depends_on` 拓扑序 + 同层 task id 升序;冲突按**机械冲突 / 语义冲突**两类分别处置(后者必须中止并上抛)。
139
157
 
140
- 3. **Delegate to subagents**(三平台同一判据,差异只在谁建树): **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):
158
+ 3. **Delegate to subagents**(三平台同一判据,差异只在谁建树):
159
+ **委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request` 与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(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 (it 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):
141
162
  - Reads TASK.md for its specific task block.
142
163
  - Executes the full TDD protocol (RED/GREEN/REFACTOR). **纯文档/纯配置任务无生产代码可测时,`redEvidence` 与 `greenEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态**(guard W1-D 接受此形状;不得伪造测试输出)。
143
164
  - Greps existing abstractions (R6.4).
@@ -149,16 +170,19 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
149
170
  - Writes `<task-id>-SUMMARY.md` to `.specs/<change-id>/`.
150
171
  - Returns evidence via `workflow-handoff.mjs result <task-id>`.
151
172
 
152
- 4. **Collect evidence**: After all subagents complete, verify each returned:
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:
153
177
  - SUMMARY.md exists in `.specs/<change-id>/` and is **模板保真**(按 `flow-kit/templates/SUMMARY.md`:标题 `# SUMMARY:` / 首部 4 字段 / 段序一致,含 `## 自检方法` 段)。
154
178
  - Verify output is real (not fabricated).
155
179
  - Handoff evidence is recorded.
156
180
 
157
- 5. **Mark done**: Update TASK.md — set `status="done"` for all completed parallel tasks.
181
+ 6. **Mark done**: Update TASK.md — set `status="done"` for all completed parallel tasks.
158
182
 
159
- 6. **Record overall evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record subagent-execute '<evidence JSON>'` to record completion.
183
+ 7. **Record overall evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record subagent-execute '<evidence JSON>'` to record completion.
160
184
 
161
- 7. **Exit check**: Run exit check.
185
+ 8. **Exit check**: Run exit check.
162
186
 
163
187
  ## Return Contract(子代理必须回传)
164
188
 
@@ -180,8 +204,8 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
180
204
  ```
181
205
 
182
206
  - `status=DONE` 才视为完成;`BLOCKED` / `NEEDS_CONTEXT` 需 orchestrator 处理。
183
- - `redEvidence` / `greenEvidence` 缺任一 → 视为未执行 TDD,orchestrator 拒绝记录;**新 change 下 guard 强制 BLOCKED**(旧 change WARN 渐进)。
184
- - `completedChecks` 必须含 `required-skill:subagent-execute.flow-comet-dev`(子代理加载 implementation skill 的证明);缺任一项 → guard exit 严格 BLOCKED(W1-D,无旧 change 豁免),orchestrator 不得以旧格式/补录方式绕过。
207
+ - `redEvidence` / `greenEvidence` 缺任一 → 视为未执行 TDD,orchestrator 拒绝记录;**guard 严格强制 BLOCKED**(同一形态一个判级)。
208
+ - `completedChecks` 必须含 `required-skill:subagent-execute.flow-comet-dev`(子代理加载 implementation skill 的证明);缺任一项 → guard exit 严格 BLOCKED(W1-D,无豁免),orchestrator 不得以旧格式/补录方式绕过。
185
209
  - **Skill 工具不可用降级(如实声明)**:子代理会话不具备 Skill 工具时,按 Read 加载节点 SKILL + 协议执行并在 Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`(SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入);此时 `completedChecks` 的 `required-skill:...` 标记仍按契约保留,但必须与降级声明并排出现——只回传标记而无降级声明视为不实声明,orchestrator 不得记录 result;具备 Skill 工具时不得回传该字段。**该字段是声明、不是物理证明**:回执只能记录会话的声明,读 SKILL.md 与真实 Skill 注入在机器可读证据上不可区分(与 `directOverride` / `completedChecks` 同族的诚实边界)——声明与事实不符属流程违规,验收以 transcript 可见的 Skill 工具触发为准。
186
210
  - `riskSignals` 非 `none` 时,orchestrator 应将该任务标记为 review 节点的高优先级审查对象。
187
211
  - 子代理回传后,orchestrator 用 `workflow-handoff.mjs result <task-id> '<JSON>'` 记录;guard exit subagent-execute 会校验 commitHash + greenEvidence + completedChecks(W1-D,严格)。
@@ -201,6 +225,7 @@ This node is truly done when:
201
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.
202
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.
203
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 记录,缺失即 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.
204
229
 
205
230
  ## Entry Check
206
231
 
@@ -220,7 +245,7 @@ The subagent-execute node identifies all `parallel="true"` pending tasks in TASK
220
245
 
221
246
  **加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
222
247
 
223
- 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 协议与交付模板。
248
+ 1. **用 Skill 工具加载** `flow-comet-dev`。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-dev 指令生效的是 Skill 工具把它注入本次会话。本节点的 flow-comet-dev 为 handoff scope——协调者在此声明(声明标记只能由执行者手动 `skill-load` 写入,引擎不代记——handoff scope 同样必须手动声明),各子代理在各自会话按 `flow-kit/prompts/4-dev.md` 协议用 Skill 工具加载并执行;协调者构造 handoff prompt 时按 `flow-kit/prompts/4-dev.md` + `flow-kit/templates/SUMMARY.md` 引用子代理的 dev 协议与交付模板。
224
249
  2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板(subagent-execute → `SUMMARY.md`):
225
250
 
226
251
  ```bash
@@ -252,7 +277,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record subagent-execut
252
277
  |--------------|-------|-----------------|
253
278
  | `handoff-evidence` | Handoff evidence recorded for each task | evidence-only |
254
279
  | `parallel-only` | Only parallel="true" tasks delegated | 执行纪律(review 把关),guard 不校验 |
255
- | `boundary-safe` | No subagent exceeded write_files | 新 change 提交越界 BLOCKED(handoff 记录时校验),旧 change WARN 渐进 |
280
+ | `boundary-safe` | No subagent exceeded write_files | 提交越界 BLOCKED(handoff 记录时校验),同一形态一个判级 |
256
281
  | `summaries-exist` | SUMMARY.md exists for each delegated task | artifact-exists |
257
282
 
258
283
  ## Exit Check
@@ -21,11 +21,13 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
21
21
  - **同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务
22
22
  - **[P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行串行任务的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口;共享工作区以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为相互隔离纪律
23
23
  - **四属性可满足(并行安全契约)**:标 `[P]` 的任务须确认**并行安全四属性**(① 写权限 · ② 提交隔离 · ③ 验证隔离 · ④ 集成纪律)可满足——worktree 只是「① 写权限」的实现之一,不是前提;四属性的**含义与三平台通道**以入口册「并行委派契约(四属性)· 三平台通道」为单一来源,本册只点名不复述
24
- - 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;硬性拦截(规划出口 BLOCKED,附恢复指引):任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见第 3 条;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)——任一项不成立即被拦(读写重叠仅 WARN),修正后重新 exit 即可通过;跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
24
+ - 波次形态:依赖驱动多趟语义——每个并行任务显式声明 `depends_on`(后波依赖前波任务),引擎按依赖拓扑自动分趟消化(每趟委托全部依赖已满足的并行任务,趟间回串行),混排序列(串→并→串/并→串→并等交错形态)合法,无需压扁成单一串行段;硬性拦截(规划出口 BLOCKED,附恢复指引):任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见第 3 条;缺任一即 BLOCKED——7 字段一项在旧式一字段模板形态下仅 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)——任一项不成立即被拦(读写重叠仅 WARN),修正后重新 exit 即可通过;跳过未满足依赖先跑并行同样被拦。落笔时先画依赖方向再标 [P]。flow-kit 上游模板未载此约束,以本条为准
25
+ - **波次 = 依赖层级的投影(波次编号的判据)**:每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);同波任务必须彼此没有依赖;想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 在 plan 出口 **BLOCKED**,明细逐条点名「任务 / 依赖 / 当前波 / 应到波」并给两条恢复出路:把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来。判不了按成因二分——载体缺席(`## 波次划分` 不在 / 段名无从派生)→ 出口打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);内容不可判(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,一律 BLOCKED(同一形态一个判级)。另: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],孤立任务一律串行;flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
29
+ - **action 与 verify 同源**:`<action>` 中要落地的替换文本必须包含同任务 `<verify>` 断言的字面串;`<verify>` 需要出现的每一段字面文本都必须能在 `<action>` 的替换文本里找到。两边不一致时**先改任务书对齐**——不得让执行者按 `<verify>` 自行改写、再把偏差在 SUMMARY 里登记成例外
30
+ 4. **波次划分**:跨层顺序;同层任务只有确有并发同伴、且 write_files 互不重叠时才标 [P],孤立任务一律串行;**波次编号是依赖层级的投影**——层 = 1 + 依赖中最晚层(无依赖 = 第 1 波),写出「无依赖 / 第 N 波」的对应关系,不要用挪动波次代替依赖声明(判据与恢复指引见第 2 条同名条目);flow-kit 上游宽松语义(「无冲突即可标 [P]」「同层即同波并行」)以本节点为准(显式覆盖,vendored 只读不改)
29
31
  5. **XML 格式**:便于 AI 解析与执行
30
32
 
31
33
  ## 产物
@@ -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
- | 段缺席 | **新 change:拦**(条件段标题必须在场——缺席即 BLOCKED,须显式标注「不适用」或填写调性)· **旧 change:兼容**(沿用旧口径判非前端,出口打印 `UI-DESIGN: skipped(旧 change 兼容)`) | 新 change 先回 open 补段;旧 change 保持原行为,不追溯 |
32
+ | 段缺席 | **一律拦**(条件段标题必须在场——缺席即 BLOCKED,须显式标注「不适用」或填写调性;同一形态一个判级,不保留兼容侧) | 先回 open 补段(或按结构形态标注「不适用」)后再重试 |
33
33
 
34
34
  **「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、行尾,或下列标点之一:`,。;、,;.::!!??…—()()【】「」『』“”"'`——**只有这一组**,组外的标点如 `/`、`-` 不算边界),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
35
35
 
@@ -47,5 +47,5 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
47
47
 
48
48
  design 出口的核对口径:
49
49
 
50
- - **前端 change**:evidence 缺 `required-skill:design.flow-comet-ui-design` → 出口**不再自动补写**该条目,直接拦截(加载并声明后重试);缺 `.specs/<change-id>/UI-DESIGN.md` → 新 change **BLOCKED**,恢复两条路——补齐工件,或按结构形态在 `## 视觉调性` 段标注「不适用」改判非前端;旧 change 仅 **WARN** 渐进,不阻断。
50
+ - **前端 change**:evidence 缺 `required-skill:design.flow-comet-ui-design` → 出口不代记该条目,直接拦截(加载并声明后重试);缺 `.specs/<change-id>/UI-DESIGN.md` → **BLOCKED**(同一形态一个判级),恢复两条路——补齐工件,或按结构形态在 `## 视觉调性` 段标注「不适用」改判非前端;同一形态一个判级(BLOCKED),不再有渐进档。
51
51
  - **非前端 change**:不要求 UI-DESIGN.md,也不要求上述声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行——**显式跳过,不是静默省略**。
@@ -155,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record verify '{"summa
155
155
  | `verify-evidence` | UAT.md exists | artifact-exists |
156
156
  | `automation-passed` | All automated checks pass (real output) | 执行纪律(review 把关),guard 不校验 |
157
157
  | `retry-limit` | No more than 3 auto-retries(机器计数 verifyFailures,第 4 次 BLOCKED) | process-check |
158
- | `lessons-nominated` | LESSONS.md 条目形态与条目区合规(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 结构级(guard 强制:本出口校验 `.specs/LESSONS.md` 的条目写 `### L-NNN`、位于条目区、编号升序——新 change 违反即 BLOCKED,旧 change WARN);「是否有合格条目」由执行者把关,归档时另以 `evidence.lessonsNomination` 核对 |
158
+ | `lessons-nominated` | LESSONS.md 条目形态与条目区合规(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 结构级(guard 强制:本出口校验 `.specs/LESSONS.md` 的条目写 `### L-NNN`、位于条目区、编号升序——违反即 BLOCKED(同一形态一个判级));「是否有合格条目」由执行者把关,归档时另以 `evidence.lessonsNomination` 核对 |
159
159
 
160
160
  ## Exit Check
161
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.6.5-blue.svg" alt="Version 1.6.5" /></a>
15
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.8.0-blue.svg" alt="Version 1.8.0" /></a>
16
16
  </p>
17
17
 
18
18
  <p align="center">
@@ -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 350 SCENARIOS PASSED`
159
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 352 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.6.5",
3
+ "version": "1.8.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": [