flow-comet 1.5.1 → 1.6.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.
@@ -38,7 +38,9 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
38
38
 
39
39
  execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pending 任务**。
40
40
 
41
- **TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须经 review 流程追加后重新 entry execute 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
41
+ **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
42
+
43
+ **TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须先经 review 流程追加到 `## Fix 任务` 段,再按下方「Fix 批次状态机路径」受控归位 execute,并由 entry execute 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
42
44
 
43
45
  本节点**不直接写实现代码**。所有 pending 任务统一通过 Agent 工具委托 fresh-context 子代理执行(加载 flow-comet-dev + 回传 Return Contract)。
44
46
 
@@ -77,6 +79,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
77
79
  > - 正确:`"completedChecks": ["required-skill:subagent-execute.flow-comet-dev"]`
78
80
  > - 错误:`"completedChecks": ["required-skill:execute.flow-comet-dev"]` —— 按 execute 域命名会被 W1-D 拦截(exit BLOCKED),子代理必须回传统一契约值
79
81
  > - 错误:`"completedChecks": [{"id": "required-skill:subagent-execute.flow-comet-dev", "status": "done"}]` —— 对象数组会被严格比较判"缺"(必须为字符串数组)
82
+ > **Return Contract 的 skillToolFallback 声明**:子代理会话不具备 Skill 工具时,必须并排回传 `skillToolFallback` 声明降级替代形态(如 `file-read`)——该字段是**声明、不是物理证明**(回执只能记录声明,读 SKILL.md 与真实 Skill 注入在机器可读证据上不可区分);只有 `required-skill` 标记而无降级声明视为不实声明,orchestrator 不得记录 result;具备 Skill 工具时不得回传该字段。
80
83
 
81
84
  The full dev protocol, templates, and constraints are in:
82
85
  - `flow-kit/prompts/4-dev.md` (DEV phase) — handoff prompt 的子代理强制协议(不再以“参照前一产物”转述——子代理必须显式按此协议执行并加载 flow-comet-dev)
@@ -100,6 +103,21 @@ This node is truly done when:
100
103
  - **Agent thought**: "This task is taking long, let me skip the self-review." **Actual risk**: Skipping self-review defers quality issues to the review node, where they become Critical items requiring fix tasks. Better to catch early.
101
104
  - **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
102
105
 
106
+ ## Fix 批次状态机路径
107
+
108
+ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
109
+
110
+ 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
111
+ 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
112
+ 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
113
+ 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
114
+ - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复批次二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
115
+ 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
116
+ - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
117
+ 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的 Fix 批次),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
118
+
119
+ **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`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: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
120
+
103
121
  ## Entry Check
104
122
 
105
123
  ```bash
@@ -19,7 +19,7 @@ This node performs a structured multi-round review of the implemented change, ch
19
19
 
20
20
  | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
21
21
  |------|-------------------------------|-----------------------------------|
22
- | REVIEW.md | 文件 ≥ 100 字节;发现区条目处置标记(`[已修]` / `[升级]` / `[转待办]`——新 change 缺失 BLOCKED,旧 change WARN 渐进) | `## Critical` / `## 发现` / `## 结论` 等段(结构要求,guard 不拦段名) |
22
+ | REVIEW.md | 文件 ≥ 100 字节;发现区条目处置标记(`[已修]` / `[升级]` / `[转待办]`——新 change 缺失 BLOCKED,旧 change WARN 渐进);**Major `[转待办]` 须有用户裁决记录**(同段、文末或单独段落「用户裁决:接受延期」+ 指向该条目 + `[升级]` 承接——单独段落与条目以空行分隔、位置不限)——缺失新 change BLOCKED / 旧 change WARN 渐进 | `## Critical` / `## 发现` / `## 结论` 等段(结构要求,guard 不拦段名) |
23
23
 
24
24
  guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
25
25
 
@@ -27,6 +27,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
27
27
 
28
28
  - [ ] **工件模板保真**:每份交付工件(`*-SUMMARY.md` / TASK / CHANGE / REQUIREMENT / DESIGN)的**标题 / 首部字段 / 段序**与对应模板一致——SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写并含 `## 自检方法` 段;执行者按 `flow-kit/prompts/4-dev.md` 协议交付。
29
29
  - [ ] **Skill 工具触发可见**:检查执行者交付的 transcript,**逐节点可见本节点 skill 用 Skill 工具加载**的触发记录——声明标记在 ≠ 已加载;只看到 `skill-load` 声明命令、看不到 Skill 工具触发 → 反馈并要求补证/重做。
30
+ - [ ] **Skill 工具不可用降级核验**:执行者会话具备 Skill 工具时,须见 Skill 工具加载节点 SKILL 的触发记录;不具备时(委托会话工具集无 Skill 工具),须按 Read 加载节点 SKILL + 协议,并在 Return Contract(`skillToolFallback: "<降级替代形态,如 file-read>"`)与 SUMMARY「自检方法」段显式声明——**Read 不得被声称为已注入(即未执行 Skill 工具注入,字段值必须写替代形态而非本说明)**。只回传 required-skill 标记而无降级声明 → 证据不完整,要求补声明;声明齐全的环境限制不判为代码缺陷。
30
31
 
31
32
  ### Prerequisites
32
33
 
@@ -90,12 +91,13 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
90
91
  - Major (should fix: design issues, significant regression)
91
92
  - Minor (optional: naming, style, small refactor)
92
93
 
93
- 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 trigger return to execute node.
94
+ 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「Fix 批次状态机路径」section below: home back to execute and run its four exit gates before review can be closed.
94
95
 
95
96
  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:
96
97
  - `[已修]` — fixed via a fix task (linked in the entry)
97
98
  - `[升级]` — escalated to the user for a decision (accept + reason recorded)
98
99
  - `[转待办]` — deferred to `.specs/<change-id>/KNOWN-ISSUES.md` at archive time
100
+ - **Major 不得由 reviewer 自行 `[转待办]`**:Major 的延期属用户决策点,reviewer 须先标 `[升级]` 等用户裁决;用户接受延期后,在同段、文末或单独段落记录「用户裁决:接受延期」并指向该条目(由 `[升级]` 承接),方可标 `[转待办]`——单独段落与发现条目以空行分隔、可位于发现区中间,位置不限(guard 按独立段落匹配,不要求位于文末)。review exit 结构校验:Major 条目标 `[转待办]` 而缺上述记录 → 新 change BLOCKED / 旧 change WARN 渐进;Minor `[转待办]` 不受影响,`[升级]` / `[已修]` 的 Major 直接放行。
99
101
  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.
100
102
 
101
103
  The full review protocol, templates, and checklists are in:
@@ -120,6 +122,22 @@ This node is truly done when:
120
122
  - **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.
121
123
  - **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.
122
124
  - **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).
125
+ - **Agent thought**: "This Major is not for this batch, I'll defer it to backlog myself." **Actual risk**: Major 延期属用户决策点——reviewer 自行 `[转待办]` 会被退出守卫拦截(新 change BLOCKED / 旧 change WARN);须先 `[升级]` 等用户裁决,用户接受延期后才可记录裁决并转待办。
126
+
127
+ ## Fix 批次状态机路径
128
+
129
+ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
130
+
131
+ 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
132
+ 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
133
+ 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
134
+ 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
135
+ - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复批次二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
136
+ 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
137
+ - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
138
+ 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的 Fix 批次),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
139
+
140
+ **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`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: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
123
141
 
124
142
  ## Entry Check
125
143
 
@@ -200,5 +218,5 @@ If the script prints `SKILL: flow-comet-verify`, load that Skill next.
200
218
  2. Read `.specs/<change-id>/REVIEW.md` — if exists with all rounds completed and Critical resolved, review is done.
201
219
  3. If REVIEW.md exists but incomplete, check which rounds are missing and resume from there.
202
220
  4. If Critical items were found but fix tasks not yet generated, generate them now.
203
- 5. If fix tasks were generated but not executed, return to execute node.
221
+ 5. If fix tasks were generated but not executed, follow the「Fix 批次状态机路径」section below to home back to execute and run its four exit gates; return here only after execute exit passes, then run review's own exit.
204
222
  6. Do not repeat completed review rounds.
@@ -15,7 +15,7 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
15
15
 
16
16
  职责分工(趟次协作):本节点负责**并行委托**(`parallel="true"` 且依赖已满足的任务,同一趟内同时发出)——委托节点可多次往返:每趟委托当时全部依赖已满足的并行任务,趟间由 execute 节点串行消化,直至不存在依赖已满足的可并行 pending 且无串行残留。execute 节点负责**串行委托**(非 parallel 任务,一次一个)。两者共用同一委托证据库(handoff 记录在 subagent-execute evidence)。序列形态不是本节点的关注点:全并行、全串行、串→并、并→串及任意混排均合法(合法性只取决于 `depends_on` 无环且引用存在;依赖环与缺失依赖已在 plan 出口拦截并附恢复指引),到达本节点的任务序列由多趟路由按依赖拓扑自动分趟消化。
17
17
 
18
- > **Codex 平台委托方式(2026-08-13 调研修正 + 实测)**:Codex CLI 无 `--worktree` 一键 flag(openai/codex#12862 跟踪中),但 git worktree 是标准支持方式(Codex App 内置 worktree;子代理运行时自动创建 worktree 隔离)——本节点委托与 Claude Code 的 worktree 隔离语义对齐:协调者对每个 parallel 任务 `git worktree add <worktree路径> -b <分支>` → 在 worktree 内 `codex exec` 委托(fresh-context,prompt 内联任务块 + AC + 强制加载 flow-comet-dev 与回传 Return Contract,`</dev/null>` 防 stdin 卡住)→ 子代理回报 commitHash 后校验存在性 + 任务完成回收(`git worktree remove`)。
18
+ > **Codex 平台委托方式(2026-08-13 调研修正 + 实测)**:Codex 当前 = **串行交付**;并行委托待机制支持——不使用并行委托,任务逐个走 `execute` 节点交付,直到守卫也能识别手工 `git worktree`(属机制变更,超出本节点范围,见下方「出路」段)。
19
19
  > **沙箱要求(实测 2026-08-13)**:worktree 的 `.git` 是主仓共享——`workspace-write`/`git-write-access` 沙箱均被 Codex 硬拦截(index.lock / objects / COMMIT_EDITMSG Permission denied);子代理必须用 `sandbox_mode="danger-full-access"` 才能完成 git 提交(worktree 隔离已限定写范围,full-access 仅用于让 git 提交可行)。**信任边界**:`danger-full-access` 是宿主级信任边界(不隔离凭据/网络访问)——仅委托可信子代理,并移除委托环境中的不必要凭据。
20
20
  > **hook 会话 root 继承(实测 2026-08-15;2026-09-12 修订)**:Codex worktree 子代理的会话 root 仍是主仓库,hook 以主仓库状态判定——`execute`/`subagent-execute` 阶段协调者白名单 `.specs/` 会拦截子代理在 worktree 内写源码。**两平台的判据不同,覆盖范围也不同**:CC 的守卫按路径前缀识别隔离区(写入落在 `.claude/worktrees/**` 内即放行,`file_path` 与 Bash 命令两条判定路径同语义);Codex 靠手工 `git worktree add <任意路径>` 建隔离区,那些路径不在该前缀下,**不被放行覆盖,写入会被协调者白名单拦截**。
21
21
  > **出路(受支持路径,二选一)**:① **CC 平台**——用 `Agent` 工具的 `isolation: "worktree"` 委托(守卫已覆盖该区,见步骤 3);② **Codex 平台**——**串行执行**:不使用并行委托,任务逐个走 `execute` 节点交付,直到守卫也能识别手工 worktree(属机制变更,超出本节点范围)。
@@ -51,6 +51,10 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
51
51
 
52
52
  主会话是协调者,不是执行者。禁止在主会话直接修改源码或执行实现。源码只能通过 `Agent` 工具以 `isolation: "worktree"` 委托子代理完成。子代理派发失败时,主会话**不得接管实现**——记录当前任务为 BLOCKED 并走 Recovery。协调者只允许更新:TASK.md(标记 done)、`<task>-SUMMARY.md`、handoff evidence(workflow-handoff.mjs result)。
53
53
 
54
+ ### 受控重入打开的修复场景(archive 源)
55
+
56
+ 缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回本节点或 `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: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过本节点入口 / 出口门禁;重入后并行任务的委托证据、write_files 边界与 Return Contract 校验与常规流程完全一致;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
57
+
54
58
  ### Prerequisites
55
59
 
56
60
  - `.specs/<change-id>/TASK.md` must exist with at least one task marked `parallel="true"` and `status="pending"`.
@@ -64,6 +68,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
64
68
  - ① `git status --short`:change 工件(`.specs/<change-id>/`)**必须已 commit**——未 commit 时 worktree 子代理看不到工件(harness 从已提交 HEAD 创建 worktree)
65
69
  - ② `git log --oneline -1`:确认 HEAD 位置(change 分支)
66
70
  - ③ 委托 prompt **必须内联任务块全文 + 相关 AC**(worktree 基线可能不是 change 分支——harness 行为不可控,内联是唯一可靠路径)
71
+ - ④ **子代理会话 Skill 工具可用性(委托前探测)**:委托 prompt 必须要求子代理开工前确认本会话是否具备 Skill 工具——具备时用 Skill 工具加载 `flow-comet-dev`;不可用时按 Read 加载节点 SKILL + `flow-kit/prompts/4-dev.md` 协议执行,并在 Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`(SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入)。**禁止把 Read 声称为已注入**;委托 prompt 未写明该口径 = 委托前检查未完成,不得发出委托
67
72
  - **Red Flag**:worktree 工件不可见/基线不确定时**禁止继续委托**——先 commit 或内联上下文
68
73
  - 委托后:子代理回报 commitHash 后校验存在性(`git cat-file -e <commitHash>`,workflow-handoff result 已有 W2-D git show 校验兜底)
69
74
 
@@ -71,12 +76,14 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
71
76
 
72
77
  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 即可。
73
78
  > 若不传 `--write-files`,脚本会自动从 TASK.md 对应 task 的 `<write_files>` 块解析(orchestrator 无需手动从 TASK.md 提取文件列表)。
79
+ **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——并行 pending 任务只归属本节点,串行 pending 任务归属 `execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
74
80
  The handoff prompt must include:
75
81
  - The task's full XML block from TASK.md.
76
82
  - DESIGN.md sections 0 and 0.5 for context.
77
83
  - REQUIREMENT.md ACs relevant to this task.
78
84
  - 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 注入会话)。
79
- - 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 豁免)。
85
+ - **Skill 工具不可用时的降级口径(与上一条并排内联)**:子代理会话不具备 Skill 工具时,按 Read 加载节点 SKILL + `flow-kit/prompts/4-dev.md` 协议执行,Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`,SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入;**禁止把 Read 声称为已完成 Skill 工具注入**。
86
+ - 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。
80
87
  - The task's `read_files` and `write_files` boundaries.
81
88
  - Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
82
89
  - **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
@@ -118,13 +125,15 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
118
125
  "redEvidence": { "command": "<RED 失败测试命令>", "output": "<真实失败输出片段>" },
119
126
  "greenEvidence": { "command": "<GREEN 通过测试命令>", "output": "<真实通过输出片段>" },
120
127
  "riskSignals": ["cross-module | security | concurrency | migration | public-api | 200+lines | none"],
121
- "concerns": "<可选:未解决的疑虑>"
128
+ "concerns": "<可选:未解决的疑虑>",
129
+ "skillToolFallback": "<仅 Skill 工具不可用时回传:降级替代形态(如 file-read),未执行 Skill 工具注入>"
122
130
  }
123
131
  ```
124
132
 
125
133
  - `status=DONE` 才视为完成;`BLOCKED` / `NEEDS_CONTEXT` 需 orchestrator 处理。
126
134
  - `redEvidence` / `greenEvidence` 缺任一 → 视为未执行 TDD,orchestrator 拒绝记录;**新 change 下 guard 强制 BLOCKED**(旧 change WARN 渐进)。
127
135
  - `completedChecks` 必须含 `required-skill:subagent-execute.flow-comet-dev`(子代理加载 implementation skill 的证明);缺任一项 → guard exit 严格 BLOCKED(W1-D,无旧 change 豁免),orchestrator 不得以旧格式/补录方式绕过。
136
+ - **Skill 工具不可用降级(如实声明)**:子代理会话不具备 Skill 工具时,按 Read 加载节点 SKILL + 协议执行并在 Return Contract 回传 `"skillToolFallback": "<降级替代形态,如 file-read>"`(SUMMARY「自检方法」段同步声明该替代形态并注明未执行 Skill 工具注入);此时 `completedChecks` 的 `required-skill:...` 标记仍按契约保留,但必须与降级声明并排出现——只回传标记而无降级声明视为不实声明,orchestrator 不得记录 result;具备 Skill 工具时不得回传该字段。**该字段是声明、不是物理证明**:回执只能记录会话的声明,读 SKILL.md 与真实 Skill 注入在机器可读证据上不可区分(与 `directOverride` / `completedChecks` 同族的诚实边界)——声明与事实不符属流程违规,验收以 transcript 可见的 Skill 工具触发为准。
128
137
  - `riskSignals` 非 `none` 时,orchestrator 应将该任务标记为 review 节点的高优先级审查对象。
129
138
  - 子代理回传后,orchestrator 用 `workflow-handoff.mjs result <task-id> '<JSON>'` 记录;guard exit subagent-execute 会校验 commitHash + greenEvidence + completedChecks(W1-D,严格)。
130
139
 
@@ -49,9 +49,9 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
49
49
 
50
50
  3. **Failure diagnosis**: For any failure (automated test or UAT):
51
51
  - Switch to "Diagnose sub-role" — identify root cause, not symptom.
52
- - Produce fix-plan: append to TASK.md as numbered fix tasks with full 7 fields and verify command.
53
- - Return to execute node for fix execution.
54
- - Re-run verification after fix.
52
+ - Produce fix-plan: append to TASK.md 的 `## Fix 任务` 段 as numbered fix tasks with full 7 fields and verify command — 禁止文件尾追加.
53
+ - Follow the「Fix 批次状态机路径」section below: home back to execute, run its four exit gates, then return to verify.
54
+ - Re-run verification after fix, then run verify's own exit gates.
55
55
 
56
56
  4. **Auto-retry limit (R2.6)**: verify 失败自动重试 ≤ 3 次(机器计数 verifyFailures);第 4 次失败必须暂停问用户「继续修 / 停止」。Do not auto-retry beyond 3 times.
57
57
 
@@ -83,6 +83,21 @@ This node is truly done when:
83
83
  - **Agent thought**: "Auto-retry 4th time, maybe it'll work now." **Actual risk**: On the 4th failure (R2.6 violation), the problem is likely systematic, not transient. Must pause and ask the user「继续修 / 停止」.
84
84
  - **Agent thought**: "Fix the failure directly, no need for a fix task." **Actual risk**: Bypassing the fix-task -> execute -> re-verify cycle means the fix is not properly tracked or tested. Must go through the proper loop.
85
85
 
86
+ ## Fix 批次状态机路径
87
+
88
+ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
89
+
90
+ 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
91
+ 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
92
+ 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
93
+ 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
94
+ - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复批次二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
95
+ 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
96
+ - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
97
+ 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的 Fix 批次),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
98
+
99
+ **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`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: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
100
+
86
101
  ## Entry Check
87
102
 
88
103
  ```bash
@@ -159,6 +174,6 @@ If the script prints `SKILL: flow-comet-archive`, load that Skill next.
159
174
  2. Read `.specs/<change-id>/UAT.md` — check which items have results.
160
175
  3. If UAT.md exists with all items passing, verification is done.
161
176
  4. If UAT.md has failures, check if fix tasks were generated in TASK.md.
162
- 5. If fix tasks exist but not executed, return to execute node.
177
+ 5. If fix tasks exist but have not gone through the execute lifecycle, follow the「Fix 批次状态机路径」section below: home back to execute, run its four exit gates, then return to verify and run verify's exit gates.
163
178
  6. Count previous auto-retries (from UAT.md / machine-counted verifyFailures) to enforce R2.6 limit.
164
179
  7. Resume from the first incomplete verification step.
package/README.md CHANGED
@@ -28,7 +28,11 @@
28
28
  <p align="center">
29
29
  <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>
30
30
  <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" /></a>
31
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.5.1-blue.svg" alt="Version" /></a>
31
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.0-blue.svg" alt="Version" /></a>
32
+ </p>
33
+
34
+ <p align="center">
35
+ <em>The <code>comet</code> badge links to the Comet project — flow-comet itself no longer reads any Comet files (see ADR-009).</em>
32
36
  </p>
33
37
 
34
38
  ---
@@ -243,7 +247,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
243
247
 
244
248
  1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
245
249
  2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
246
- 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 243 SCENARIOS PASSED`
250
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 267 SCENARIOS PASSED`
247
251
  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)
248
252
 
249
253
  CI enforces the repository conventions automatically on every PR and push (regression, PR discipline, version consistency, 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.5.1",
3
+ "version": "1.6.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": [
@@ -28,7 +28,7 @@
28
28
  // 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
29
29
  // ESM 模块导出 { name, apply },ctx 由 dsh 注入。
30
30
  //
31
- // BRIDGE_VERSION: 1.5.1
31
+ // BRIDGE_VERSION: 1.6.0
32
32
 
33
33
  import { spawn } from 'node:child_process';
34
34
  import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -40,7 +40,7 @@ import path from 'node:path';
40
40
  // 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
41
41
  // bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
42
42
  export const name = 'dsh-flow-comet-bridge';
43
- export const version = '1.5.1';
43
+ export const version = '1.6.0';
44
44
 
45
45
  // guard 在项目内的相对路径常量(随 skill 包分发)。
46
46
  const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';