flow-comet 1.6.5 → 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 +17 -5
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +23 -4
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +97 -3
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +38 -2
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +16 -3
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +4 -0
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +20 -11
- 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 +47 -5
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +297 -131
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +616 -151
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +96 -45
- 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 +204 -51
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +7 -9
- 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 +38 -20
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +439 -134
- 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 +92 -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 +94 -39
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +6 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +57 -7
- 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 +158 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +92 -17
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1439 -11
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1204 -76
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +32 -1
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +5 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +16 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +5 -0
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2041 -66
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
- 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-execute/SKILL.md +30 -6
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +10 -3
- package/.flow-comet/skills/flow-comet-review/SKILL.md +20 -11
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +33 -8
- package/.flow-comet/skills/flow-comet-task/SKILL.md +2 -1
- package/README.md +1 -1
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
|
@@ -38,6 +38,24 @@ guard 校验见 workflow-guard.mjs 的 execute 出口门禁(必填段 + 6 维
|
|
|
38
38
|
|
|
39
39
|
执行模式由 `node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 输出(`executionMode` / `directOverride`)决定,切换用 `node .claude/skills/flow-comet/scripts/workflow-state.mjs execution-mode <subagent|direct>`。direct 是逃生口,必须用户显式调用才生效。
|
|
40
40
|
|
|
41
|
+
### 节点视图三字段(currentNode / stateCurrentNode / routeNode)
|
|
42
|
+
|
|
43
|
+
`status` 与 `next` 读的是同一份节点视图,但三个字段各说一件事,不能互相替代:
|
|
44
|
+
|
|
45
|
+
- **currentNode** = **产物推导**的节点(按 `.specs/<change-id>/` 的工件推导出「按文件看现在在哪」;语义逐字未变);
|
|
46
|
+
- **stateCurrentNode** = **state 文件原值**(`.flow-comet/flow-comet-state.json` 里 `currentNode` 的原样读数,由 entry / exit / advance / reenter 写入;语义逐字未变);
|
|
47
|
+
- **routeNode** = **路由视图**(经「进行中保护」/ Fix 受控归位后的节点;常规路径下等于 `next` 的 `NODE:` 行,决定你现在该推进哪个节点)。
|
|
48
|
+
|
|
49
|
+
三者不一致不是 bug,而是同一事实的三个视角:`ROUTE:` 行给出 `derived=… state=… route=…` 的对账(derived = 产物推导、state = state 原值、route = 路由视图)与下一步动作。**Fix 批次以 `FIX-BATCH` 行与 `next` 的 `NODE` 为准**——归位目标就是你要先跑出口的节点;预检与出口都跑在那个节点上,不要按 `stateCurrentNode` 或 `currentNode` 自行改道。
|
|
50
|
+
|
|
51
|
+
**Node view: the three fields (currentNode / stateCurrentNode / routeNode)** — `status` and `next` read the same node view, but the three fields say three different things and cannot substitute for each other:
|
|
52
|
+
|
|
53
|
+
- **currentNode** = artifact-derived (the node derived from the artifacts under `.specs/<change-id>/`, i.e. "where the files say we are"; semantics unchanged);
|
|
54
|
+
- **stateCurrentNode** = the raw state-file value (the `currentNode` read verbatim from `.flow-comet/flow-comet-state.json`, written by entry / exit / advance / reenter; semantics unchanged);
|
|
55
|
+
- **routeNode** = the routing view (after in-progress protection / controlled Fix-batch rollback; on the regular path it equals the `NODE:` line printed by `next` and decides which node you should advance now).
|
|
56
|
+
|
|
57
|
+
A mismatch is not a bug but the same fact seen from three angles: the `ROUTE:` line gives the `derived=… state=… route=…` reconciliation (derived = artifact derivation, state = raw state value, route = routing view) plus the next action. **For a Fix batch, trust the `FIX-BATCH` line and the `NODE` printed by `next`** — the rollback target is the node whose exit you must run first; run preflight and exit on that node instead of rerouting by `stateCurrentNode` or `currentNode`.
|
|
58
|
+
|
|
41
59
|
### 任务范围
|
|
42
60
|
|
|
43
61
|
execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pending 任务**。
|
|
@@ -80,7 +98,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
80
98
|
|
|
81
99
|
要点(五要素 + 并行波次附加两条):
|
|
82
100
|
|
|
83
|
-
1. **`git add -- <自己字面路径>`** + **`git commit -- <同一路径>`**:逐条字面路径(取自本任务 `write_files
|
|
101
|
+
1. **`git add -- <自己字面路径>`** + **`git commit -m "<消息>" -- <同一路径>`**:逐条字面路径(取自本任务 `write_files`),两步路径集逐字一致——提交只含自己的文件;消息(含尾注)写在 `--` **之前**,写成 `-m` 在 `--` 之后会被当成 pathspec;禁用 `.` / `-A` / `-u` 等宽泛形态。
|
|
84
102
|
2. **锁失败重试**:并发提交撞 `index.lock` / `cannot lock ref` ⇒ **失败即重试**,不得因锁失败改用宽泛命令。
|
|
85
103
|
3. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:并发写者共享**同一个索引与工作树**——宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 更会破坏同伴的未提交工作。
|
|
86
104
|
4. **并行波次禁用 `git commit --amend`**:共享工作区下 HEAD 会被并行写者推进;确需修正必须**先断言 `git rev-parse HEAD` 等于自己刚提交的哈希**,否则一律改用**新提交追加**。
|
|
@@ -112,14 +130,19 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
112
130
|
|
|
113
131
|
对 TASK.md 每个 pending 串行任务,协调者执行:
|
|
114
132
|
|
|
115
|
-
1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request
|
|
116
|
-
2.
|
|
133
|
+
1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request(机制保证,不是经验之谈)**——`result` 在写盘前校验该任务存在 request 记录:缺失时新 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」的可行顺序。
|
|
134
|
+
2. **委托子代理**:
|
|
135
|
+
**委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request`(步骤 1)与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(新 change BLOCKED,恢复句见步骤 1)。
|
|
136
|
+
**Delegation order (mandatory)**: a successful request first, then launch the subagent — the `workflow-handoff.mjs request` call and the subagent launch are two sequential steps; never inside one concurrent call (e.g. request plus Agent / spawn_agent in the same `Promise.all`). This is execution discipline, not a mechanism interception: the platform tool layer offers no hook point, so the engine will not queue it for you. **Two different things**: this rule is about the order of the request and the subagent launch, and nothing enforces it; "a result needs a request" is a mechanism guarantee — a result without one is refused before anything is written (a new change blocks, recovery line in step 1).
|
|
137
|
+
按平台通道委托 fresh-context 子代理(三平台同一身份判据,差异只在谁建树;`isolation: "worktree"` 是属性①的可选实现,非强制——见「并行安全四属性契约」)。handoff prompt 强制协议:子代理用 **Skill 工具**加载 flow-comet-dev 并按 `flow-kit/prompts/4-dev.md` 协议执行(TDD RED/GREEN/REFACTOR、LESSONS 扫描、既有抽象 grep、verify、6 维自查、越界检查、原子 commit `<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁 change-id/日期作 scope;任务号放提交正文尾注 Task: <task-id>,change-id 不入标题)),按 `flow-kit/templates/SUMMARY.md` 模板写 `.specs/<change-id>/<task-id>-SUMMARY.md`(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段),回传 Return Contract(含 commitHash + greenEvidence + completedChecks + selfReview)。**SUMMARY 自引用 hash 注**:提交内容无法包含自身 hash——若子代理 amend 提交,SUMMARY 内记录的 commitHash 为 amend 前值属预期(文件集一致即可,以实际提交对象为准)。
|
|
117
138
|
**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
|
|
118
|
-
**提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit --
|
|
139
|
+
**提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit -m "<消息>" -- <同一路径>`(消息在 `--` 之前)提交、锁失败重试、禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。**集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`、降级 `cherry-pick` 记因、顺序按 `depends_on` 拓扑序 + 同层 task id 升序、冲突按机械 / 语义两类分别处置。
|
|
119
140
|
**写前读模板(handoff prompt 固定句式)**:prompt 必须写明「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成,不得发出委托。
|
|
120
141
|
3. **记录 handoff result**:子代理回传后,运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs result <task-id> '<JSON>'` 记录(Return Contract 含 commitHash + greenEvidence + completedChecks + selfReview)。
|
|
121
|
-
4.
|
|
122
|
-
|
|
142
|
+
4. **每任务预检(`--preflight` · 只报结构问题)**:子代理回传并记下 `workflow-handoff.mjs result` 之后(direct 模式则在执行者交出 SUMMARY 之后),运行 `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit execute --preflight` —— 它只跑**结构性门禁**(本节点声明工件的存在性 / SUMMARY 关键段 / 模板保真骨架 / 入口工件骨架〔在场才查〕/ TASK 7 字段〔仅 `plan` 节点生效〕),**不跑**进展类门禁(证据、任务集签名、串行 pending、可委托并行、在飞委托、verify 命令执行),不推进状态、不写 state、也不写模板提示账本。**本家族的预检作用域** = 本节点声明工件的存在性(协议声明的 file 类产物,缺件即 BLOCK,逐项给出路径与模板指针)+ SUMMARY 关键段 + 模板保真骨架 + 入口三件(`CHANGE` / `REQUIREMENT` / `DESIGN`,存在才查);TASK 7 字段是 plan 出口的判据,对 execute 家族是 no-op,不在本步骤的范围内。**预检通过 = 结构面通过,不代表进展门禁会通过**(推进仍由完整 exit / `--apply` 决定)。价值:在「result 已记、尚未标 done」这个时点就能当场看到该任务 SUMMARY 的缺段 / 结构子段 / 条件段 / 首部字段问题——这正是本步骤存在的通道;不跑预检,这些问题会被更早的进展门禁挡下、攒到节点收尾一起爆。边界:它只报结构问题;**完整 `exit`(不带 `--apply`)仍是节点收尾的全链预演**——会先报进展类问题(串行 pending / 可委托并行 / 证据),预检不替代它。它只读、不写提示账本,因此**缺 H2 段只报类别计数**;结构子段与父段写法建议照常点名。要看被计数的那些段名,请等节点收尾的完整 `exit`(它维护提示账本),或直接按模板逐段对照。
|
|
143
|
+
**Per-task preflight (`--preflight`, structural only)**: after the subagent returns and its result is recorded (in direct mode, after the executor hands over the SUMMARY), run `node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit execute --preflight` — it runs only the structural gates (existence of the node's declared artifacts / SUMMARY key sections / template-fidelity skeleton / intake-artifact skeleton, checked only when present / TASK seven fields, which apply at `plan` alone) and skips the progress gates (evidence, task-set signature, serial pending, delegable parallel tasks, in-flight handoffs, real verify execution); it does not advance, does not write workflow state, and does not write the template hint ledger. **The preflight scope of this family** = the existence of the node's declared file artifacts (a missing one blocks and names each path with its template) + the SUMMARY key sections + the template-fidelity skeleton + the three intake documents (`CHANGE` / `REQUIREMENT` / `DESIGN`, checked only when present); the TASK seven fields belong to the `plan` exit and are a no-op for the execute family, so they are not part of this step. **Passing the preflight means the structural face passes; it does not mean the progress gates will pass** (advancing is still decided by the full exit / `--apply`). Value: the task's SUMMARY defects (missing section / structure subsection / conditional section / header field) surface right away at the point where the result is recorded and the task is not yet marked done — that is exactly the channel this step exists for; without it those defects are blocked by earlier progress gates and pile up at the node exit. Boundary: it reports structural problems only; the **full `exit` without `--apply` remains the node's whole-chain rehearsal** and reports progress-class problems first (serial pending / delegable parallel tasks / evidence) — preflight does not replace it. Because it is read-only and writes no hint ledger, **a missing H2 section is reported as a category count only**; a missing structural subsection, and the advice naming the parent section that should hold it, are still named. For the counted headings, wait for the node's closing full `exit` (which keeps that hint ledger) or compare the document against the template section by section.
|
|
144
|
+
5. **验收 SUMMARY,TASK.md 标 done**:确认 SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写且**模板保真**(标题 `# SUMMARY:` / 首部 4 字段 / 段序一致)、含 `## 自检方法` 与 `## LESSONS 扫描` 两个增量段(前者声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一)、verify 输出真实、6 维自查与越界检查有实质内容;通过后在 TASK.md 将任务标 `status="done"` 并加时间戳。
|
|
145
|
+
6. **下一个 pending 任务**:重复步骤 1-5。
|
|
123
146
|
|
|
124
147
|
> 原 Steps 的 TDD / LESSONS / verify / 6 维自查 / 越界检查 / commit 协议**移入 handoff prompt 作为子代理的强制协议**,协调者不亲自执行。
|
|
125
148
|
> **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence 缺失在新 change 下仍会被 W1-D 拦截,因此必须显式提供此形态而非省略字段)。
|
|
@@ -151,6 +174,7 @@ This node is truly done when:
|
|
|
151
174
|
- **Agent thought**: "I see a bug in an adjacent file, let me fix it along the way." **Actual risk**: "Fixing along the way" without a new task or CHANGE violates R7.1 (scope control). Must stop and create a new task or CHANGE.
|
|
152
175
|
- **Agent thought**: "This task is taking long, let me skip the self-review." **Actual risk**: Skipping self-review defers quality issues to the review node, where they become Critical items requiring fix tasks. Better to catch early.
|
|
153
176
|
- **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
|
|
177
|
+
- **Agent thought**: "同时发 request 和启动子代理,省一个来回。" **Actual risk**: 先让 request 成功,再启动子代理——禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all`);这是执行纪律,不是机制拦截(平台层没有挂点,引擎不替你排队)。与它相邻的另一件事已是机制保证:`result` 在写盘前校验该任务有 request 记录,缺失即新 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.
|
|
154
178
|
|
|
155
179
|
## 修复回路状态机路径
|
|
156
180
|
|
|
@@ -29,13 +29,15 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结
|
|
|
29
29
|
|
|
30
30
|
加载顺序:先读 `READ PROMPT:`(`3-task`),再读 `READ TEMPLATE:`(`TASK`)。
|
|
31
31
|
|
|
32
|
-
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——新 change 不一致 BLOCKED(旧 change WARN
|
|
32
|
+
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——新 change 不一致 BLOCKED(旧 change WARN 渐进)。波次投影一致性:`## 波次划分` 声明的波次必须等于任务的依赖层级(判据与恢复指引见下方「波次形态约束」)——新 change 不一致 BLOCKED(旧 change WARN 渐进);判不了按成因二分——**载体缺席**(`## 波次划分` 不在 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过),**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数);任务集里的任务还必须被某条 Wave 行覆盖(修复族除外,漏写的以「未声明」点名)。
|
|
33
33
|
|
|
34
34
|
### 波次形态约束(依赖驱动多趟 · 规划期必守)
|
|
35
35
|
|
|
36
|
-
**约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on
|
|
36
|
+
**约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on`,依赖面的合法性只取决于依赖图本身:`depends_on` 无环且引用的任务都存在,依赖面即合法;波次编号另按「波次 = 依赖层级的投影」(下一条)单独校验——依赖面合法不等于波次声明合法,两条判据各自独立拦截。全并行、全串行、串→并、并→串四种基本形态与任意混排序列(如 `S→P→S`、`P→S→P`)一律放行——引擎按依赖拓扑自动分趟(每趟委托全部依赖已满足的并行任务,趟间回串行消化),混排序列由多趟路由按依赖拓扑自动分趟消化,并行任务的先后位置不受任何限制。
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
**波次 = 依赖层级的投影(波次编号的判据)**:`## 波次划分` 里的波次编号不是自由排版,而是任务依赖层级的投影——① 每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);② 同波任务必须彼此没有依赖;③ 想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 新 change 出口 **BLOCKED**:明细逐条点名「任务 / 依赖 / 当前波 / 应到波」,并给两条恢复出路——把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来(要保留当前波次,就把「它为何排在后面」的依赖写成显式 `depends_on`);旧 change 只 WARN 渐进。**判不了按成因二分**:**载体缺席**(无 `## 波次划分` 段 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id——正文只写 `N/A`、Wave 行点的是不存在的 id、行首强调记号让 Wave 行不成立)→ 出口打印 `TASK.md 波次划分段内容不可判`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数)。**覆盖义务**:TASK 里的每个非修复族任务都必须被某个 Wave 行覆盖(修复族不要求排进波次),漏写的任务在明细里以「未声明」的当前波逐条点名——没有「当前波」可挪,恢复出路是把它写进应到波的 Wave 行。`replan` 重校走同一判据、同一报文,不豁免。**与混排合法化并存**:本条只要求「波次编号与依赖层级一致」,不恢复旧的「并行块必须连续成组」形态约束——上面的串→并→串混排照旧合法,并行任务的先后位置照旧不受限制。
|
|
39
|
+
|
|
40
|
+
**硬性拦截(规划出口 BLOCKED,附恢复指引)**:任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见上表;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)/ 波次声明与依赖层级不一致(明细与两条恢复出路见上一条)——任一项不成立即在规划出口被 BLOCKED(读写重叠仅 WARN),按提示修正后重新 exit 即可通过。任务间依赖不得成环(如 A→B→A),也不得构成不可满足的依赖链。
|
|
39
41
|
|
|
40
42
|
**警示**:落笔时先画依赖方向再标 [P],避免出口返工。
|
|
41
43
|
|
|
@@ -87,11 +89,14 @@ This node decomposes the technical design into atomic, executable tasks with cle
|
|
|
87
89
|
- `done`: One sentence completion criteria, corresponding to an AC sub-item.
|
|
88
90
|
|
|
89
91
|
7. **Wave division**: Group tasks by dependency graph:
|
|
92
|
+
- **Waves are a projection of dependency levels**: each task's wave is one past the latest wave among its dependencies (no dependency = wave 1), and tasks in the same wave must not depend on one another; to make a task run later, declare the order with `depends_on` instead of moving it to a later wave without declaring it.
|
|
90
93
|
- Cross layer = sequential execution.
|
|
91
94
|
- Same-layer tasks may carry `parallel="true"` only when the wave genuinely contains a concurrent companion and their `write_files` do not overlap; an isolated task stays serial.
|
|
92
95
|
- Flow-comet override: the permissive flow-kit upstream semantics — "no conflict ⇒ [P]" and "same layer = same wave, parallel" — are superseded by this node's rule; the vendored upstream files stay read-only and are not modified.
|
|
93
96
|
- Output wave diagram: `Wave 1: T01[P], T02[P]` etc.; isolated tasks appear as serial steps.
|
|
94
97
|
|
|
98
|
+
A declared wave that disagrees with the dependency level — a same-wave dependency, a task placed before its dependency, or a conservative placement later than needed — blocks a new change at the plan exit: every mismatch is named as task / dependencies / declared wave / expected wave, together with the two ways out (move it to wave N, or add the `depends_on` that explains the order), while an older change only warns. When the section is absent (no `## 波次划分` section, or its name cannot be derived), the exit prints "not checked (no wave section)" and skips the rule — unverified is not a pass. When the section is present but no Wave line resolves to a real task (a body that only says N/A, a line naming an unknown id, a leading emphasis mark that breaks the line), the content cannot be judged: a new change blocks there, an older change warns, and that warning is counted with the other warnings. Every task in the set must be covered by some Wave line (the fix-task family excepted); a task the section never mentions is named with "undeclared" as its current wave, and the way out is to write it into the wave it should reach. `replan` runs the same judgement with the same wording. This rule constrains the agreement between wave numbers and dependency levels only: it does not bring back the old "parallel blocks must be contiguous" shape constraint, so the mixed-sequence freedom above stands (serial → parallel → serial stays legal).
|
|
99
|
+
|
|
95
100
|
8. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to planned file paths or actions. If active lessons hit, declare difference or confirm still applies.
|
|
96
101
|
|
|
97
102
|
The full task decomposition protocol, XML template, and constraints are in:
|
|
@@ -106,6 +111,7 @@ This node is truly done when:
|
|
|
106
111
|
- Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
|
|
107
112
|
- Every `[P]` mark has a genuine concurrent companion in its wave with non-overlapping `write_files`; isolated tasks are serial (a fully serial plan is valid when no genuine companion exists).
|
|
108
113
|
- Wave division diagram is clear and has no circular dependencies.
|
|
114
|
+
- Wave numbers agree with dependency levels: each wave is one past the latest dependency wave, and tasks sharing a wave have no dependencies between them (an absent wave section is reported as "not checked", never as a pass; a section whose content cannot be judged blocks a new change and only warns on an older change).
|
|
109
115
|
- Task numbering is continuous.
|
|
110
116
|
|
|
111
117
|
### Red flags
|
|
@@ -114,6 +120,7 @@ This node is truly done when:
|
|
|
114
120
|
- **Agent thought**: "verify: tests should pass" is good enough. **Actual risk**: Vague verify commands cannot be executed. Must be specific: `pytest tests/test_x.py -v` not "tests should pass".
|
|
115
121
|
- **Agent thought**: "write_files can include any file the task might touch." **Actual risk**: Including DESIGN forbidden list modules in write_files bypasses R7.3 + R6.5 boundary enforcement. Strict control is mandatory.
|
|
116
122
|
- **Agent thought**: "Same layer means these tasks can all be marked [P]." **Actual risk**: A same-layer task with no concurrent companion, or with overlapping `write_files`, would be delegated as parallel in violation of this node's rule. Mark `[P]` by companion and write boundaries, never by layer alone.
|
|
123
|
+
- **Agent thought**: "This task just feels like it should run later, so I'll put it in a later wave." **Actual risk**: A wave number is the dependency level projected onto the plan — moving a task to a later wave without declaring the dependency is exactly the mismatch the exit blocks. Declare `depends_on` instead of moving the wave.
|
|
117
124
|
- **Agent thought**: "read_files and write_files are the same thing." **Actual risk**: read_files includes reuse targets and reference modules; write_files is strictly the modification boundary. They serve different purposes (B3 old-project guardrail).
|
|
118
125
|
|
|
119
126
|
## Entry Check
|
|
@@ -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
|
|
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
27
|
|
|
28
|
-
|
|
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 自身把关。
|
|
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: 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.
|
|
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,18 +97,20 @@ 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
|
-
-
|
|
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
|
+
- **修复回路内不得延期**:在一次修复回路里新发现的条目,只能是 `[已修]` 或 `[升级]`(交用户裁决)——即使该条目已有用户裁决的延期记录在场,也不得把修复回路新增的发现标 `[转待办]`。回路是「把本轮引入的问题收干净」的窗口,不是继续开新账的入口。
|
|
109
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.
|
|
110
115
|
|
|
111
116
|
The full review protocol, templates, and checklists are in:
|
|
@@ -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(新 change)。缺口只有两条出路:在 1.1 矩阵补行,或把它作为发现条目按处置标记处理;把缺口留到 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**:
|
|
133
|
-
- **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**: 修复回路内新发现的条目只能 `[已修]` 或 `[升级]`——不得 `[转待办]`,即使裁决记录在场;这是纪律要求,守卫只看结构、看不出你在回路里第几轮。
|
|
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
|
|
|
@@ -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` 还会直接破坏同伴的未提交工作。
|
|
@@ -100,6 +100,24 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
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,7 +137,7 @@ 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
|
|
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」的可行顺序。
|
|
123
141
|
> 若不传 `--write-files`,脚本会自动从 TASK.md 对应 task 的 `<write_files>` 块解析(orchestrator 无需手动从 TASK.md 提取文件列表)。
|
|
124
142
|
**归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——并行 pending 任务只归属本节点,串行 pending 任务归属 `execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
|
|
125
143
|
The handoff prompt must include:
|
|
@@ -134,10 +152,13 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
|
|
|
134
152
|
- **写前读模板(固定句式)**:「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成。
|
|
135
153
|
- **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 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 --
|
|
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**(三平台同一判据,差异只在谁建树):
|
|
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):
|
|
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.
|
|
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
|
-
|
|
181
|
+
6. **Mark done**: Update TASK.md — set `status="done"` for all completed parallel tasks.
|
|
158
182
|
|
|
159
|
-
|
|
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
|
-
|
|
185
|
+
8. **Exit check**: Run exit check.
|
|
162
186
|
|
|
163
187
|
## Return Contract(子代理必须回传)
|
|
164
188
|
|
|
@@ -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 记录,缺失即新 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.
|
|
204
229
|
|
|
205
230
|
## Entry Check
|
|
206
231
|
|
|
@@ -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
|
## 产物
|
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">
|
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';
|