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.
Files changed (61) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +17 -5
  3. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +23 -4
  5. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  6. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
  7. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +97 -3
  8. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +38 -2
  9. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  10. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +16 -3
  11. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +2 -0
  12. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +4 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +20 -11
  14. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  15. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
  16. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +297 -131
  17. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +616 -151
  18. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +96 -45
  19. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  20. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +204 -51
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +7 -9
  22. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  23. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  24. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  25. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +38 -20
  26. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +439 -134
  27. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
  29. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
  30. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +94 -39
  31. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +6 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  33. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +57 -7
  34. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
  35. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +158 -3
  36. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
  37. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +92 -17
  38. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1439 -11
  39. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
  40. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1204 -76
  41. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
  42. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +32 -1
  43. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
  44. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +5 -0
  45. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +16 -0
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +5 -0
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2041 -66
  50. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
  51. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
  52. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
  53. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  54. package/.flow-comet/skills/flow-comet-execute/SKILL.md +30 -6
  55. package/.flow-comet/skills/flow-comet-plan/SKILL.md +10 -3
  56. package/.flow-comet/skills/flow-comet-review/SKILL.md +20 -11
  57. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +33 -8
  58. package/.flow-comet/skills/flow-comet-task/SKILL.md +2 -1
  59. package/README.md +1 -1
  60. package/package.json +1 -1
  61. package/scripts/dsh-bridge.mjs +2 -2
@@ -1 +1 @@
1
- 1.6.5
1
+ 1.7.0
@@ -135,7 +135,7 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
135
135
  | 属性 | 含义(本节为口径单一来源) |
136
136
  |------|---------------------------|
137
137
  | ① 写权限 | 子代理写入目标的**放行依据**(含 gitignored 面):身份在场 ⇒ 子代理语义放行;**最小保护集**(`.flow-comet/flow-comet-state.json`、`reference/workflow-protocol.json`)在身份在场时**仍拦** |
138
- | ② 提交隔离 | 各写者只提交**自己的字面路径**(`git add -- <路径>` / `git commit -- <同一路径>`;多个写者共享同一工作区时禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`) |
138
+ | ② 提交隔离 | 各写者只提交**自己的字面路径**(`git add -- <路径>` / `git commit -m "<消息>" -- <同一路径>`,消息在 `--` 之前;多个写者共享同一工作区时禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`) |
139
139
  | ③ 验证隔离 | **同一时刻只有一个写者**(有 request 无对应 result 的在飞委托 ⇒ 不跑全量判据,待写入者收工后重跑;已作废的委托经 `workflow-handoff.mjs withdraw <task-id> --by <来源>` 撤回,留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
140
140
  | ④ 集成纪律 | 协调者按确定性规则**显式、可审计**地集成(`merge --no-ff` 优先、冲突难解时降级 cherry-pick 并记因;机械冲突与语义冲突分别处置) |
141
141
 
@@ -184,19 +184,31 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
184
184
  **节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
185
185
 
186
186
  1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
187
- 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
187
+ 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**声明「加载了哪个技能、按哪份协议工作」。**一个节点该读的协议常常不止一份**(open 是 `0-change.md` + `1-requirement.md`,review 是 `6-review.md` + `5-test.md`)——**一份命令可以给多个 `--prompt`**,`skill-load` 会把它们**全部**记进同一个标记,不是只留第一个:
188
188
 
189
189
  ```bash
190
- node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md --templates <模板基名,...>
190
+ # 单份协议(plan):本节点只有一个必需技能
191
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load plan flow-comet-task --prompt flow-kit/prompts/3-task.md --templates TASK.md
192
+
193
+ # 多份协议(open):一条命令两个 --prompt,两份都记进标记
194
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-change --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
195
+
196
+ # 同一节点有两个 guarded 必需技能(open = change + requirement):**每个必需技能各一条**——
197
+ # 一条命令只写一个技能标记,少一条就少一个技能;每条都带该节点的全部 --prompt 与模板全清单
198
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-requirement --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
191
199
  ```
192
200
 
193
- > **提示词 = 步骤权威、模板 = 段形权威,两者缺一即未完成加载**:`--prompt` 指向的 `flow-kit/prompts/<阶段>.md` 规定这一步**怎么做**(流程步骤、检查项、交接物),`--templates` 指向的 `flow-kit/templates/<DOC>.md` 规定产出**长什么样**(标题、段序、段形)。节点入口先打印 `READ PROMPT:`;**有模板的节点**再打印 `READ TEMPLATE:`(verify / archive 为零模板节点,只打印一行);**两条 READ 行都要读**。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);错路径由入口(核对已写下的声明)与出口(核对节点协议集)两侧拦下(BLOCKED),不会静默写成一条与节点无关的声明。
201
+ > **分条等价**:按协议文件分几条命令声明,与合并成一条等价——出口判据按节点汇总,只问「该读的这几份是否都被声明过」。
202
+
203
+ > **一次声明把三个面给全**:该节点该读的**全部**协议文件(多个 `--prompt`)+ 协议要求的**每个** `guarded` 必需技能各一条(一条命令只写一个技能标记)+ 模板**全清单**(`--templates`)。少任一面的命令照抄不过:出口的覆盖判据按节点汇总点名缺哪份协议文件 / 哪个必需技能,模板声明核对再点名漏写的模板。缺声明时报文给出的恢复命令就是这三面齐全的形态——照抄即可,不要自己拆成「只补缺的那一项」。
204
+
205
+ > **提示词 = 步骤权威、模板 = 段形权威,两者缺一即未完成加载**:`--prompt` 指向的 `flow-kit/prompts/<阶段>.md` 规定这一步**怎么做**(流程步骤、检查项、交接物),`--templates` 指向的 `flow-kit/templates/<DOC>.md` 规定产出**长什么样**(标题、段序、段形)。节点入口先打印 `READ PROMPT:`;**有模板的节点**再打印 `READ TEMPLATE:`(verify / archive 为零模板节点,只打印一行);**两条 READ 行都要读**。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);**入口只拦错路径**——逐份核对已写下的声明,落在节点协议面外即 BLOCKED 并点名;**缺失由出口拦**——逐份核对节点协议集,缺哪份逐项点名。两处判据分工不同:既不会静默写成一条与节点无关的声明,也不存在「有一份就过」。
194
206
 
195
207
  > **`--templates` 是内置节点的必填声明**(每个声明标记各写**全清单**,与节点映射一致):open → `CHANGE.md,REQUIREMENT.md` · design → `DESIGN.md`(前端 change 可再加 `UI-DESIGN.md`)· plan → `TASK.md` · execute / subagent-execute → `SUMMARY.md` · review → `REVIEW.md,TEST.md` · verify / archive → **零模板节点,省略该参数**(省略即空集;多写反而不一致)。声明集合由引擎校验:漏写 / 多写 / 错名在新 change 下即 BLOCK,旧 change 仅 WARN。
196
208
 
197
209
  > **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
198
210
 
199
- 节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。
211
+ 节点退出(exit)与证据记录(record)会核对声明标记。**exit 的判据是「全部覆盖」而不是「任一命中」**:该节点该读的**每一份**协议文件、以及协议里**每一个** `guarded` 必需技能,都要有声明标记——`handoff-guarded` 是子代理侧义务,由 Return Contract 负责,不在节点标记判据内;缺任一即逐项点名并给出补齐命令,新 change BLOCKED、旧 change 只 WARN(恢复命令形态与旧标记兼容口径见 `reference/entry-detail.md` 的「exit 核对声明标记」小节)。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。
200
212
 
201
213
  ## Guardrails And Evidence
202
214
 
@@ -12,7 +12,7 @@
12
12
  五要素(缺一不可):
13
13
 
14
14
  1. **`git add -- <自己字面路径>`**:逐条字面路径(取自本任务 `write_files`),禁用 `.` / `-A` / `-u` 等宽泛形态。
15
- 2. **`git commit -- <同一路径>`**:提交以 pathspec 限定范围,保证提交只含自己的文件;路径集与上一步**逐字一致**。
15
+ 2. **`git commit -m "<消息>" -- <同一路径>`**:消息(含正文尾注 `-m "Task: <id>"`)写在 `--` **之前**,pathspec 写在 `--` 之后——提交以 pathspec 限定范围,保证提交只含自己的文件;路径集与上一步**逐字一致**。消息若落到 `--` 之后(`git commit -- <路径> -m "<消息>"`),`-m` 会被当成 pathspec、提交直接失败(退出码 1)。
16
16
  3. **锁失败重试**:并发提交会撞 `index.lock` / `cannot lock ref`——**失败即重试**(临时仓真并发实测:20 提交 / 25 次锁失败全部重试成功);不得因锁失败改用宽泛命令。
17
17
  4. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:无 pathspec 的 `git add`、`git commit -a`、`git stash`、`git clean`、`git reset` 一律禁止——它们作用于整个共享工作区。
18
18
  5. **为什么**:并发写者共享**同一个索引与工作树**——宽泛命令存在**并发索引竞态**:一方 `add -A` 会把另一方的半成品纳入自己的提交(串味 / 多文件提交);`stash` / `clean` / `reset` 更会直接破坏同伴的未提交工作。
@@ -107,19 +107,38 @@ flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部
107
107
  **节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
108
108
 
109
109
  1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
110
- 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
110
+ 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**声明「加载了哪个技能、按哪份协议工作」。**一个节点该读的协议常常不止一份**(open 是 `0-change.md` + `1-requirement.md`,review 是 `6-review.md` + `5-test.md`)——**一份命令可以给多个 `--prompt`**,`skill-load` 会把它们**全部**记进同一个标记的 `protocols` 里,不是只留第一个:
111
111
 
112
112
  ```bash
113
- node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md --templates <模板基名,...>
113
+ # 单份协议(plan)
114
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load plan flow-comet-task --prompt flow-kit/prompts/3-task.md --templates TASK.md
115
+
116
+ # 多份协议(open):一条命令两个 --prompt,两份都记进标记
117
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-change --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
118
+
119
+ # 同一节点的第二个 guarded 必需技能(open = change + requirement):每个必需技能各一条,
120
+ # 每条都带该节点全部 --prompt 与模板全清单——一条命令只写一个技能标记
121
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-requirement --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
114
122
  ```
115
123
 
124
+ > **分条等价**:按协议文件分几条命令声明,与合并成一条等价——出口判据按节点汇总,只问「该读的这几份是否都被声明过」,不要求与技能一一对应。
125
+
116
126
  > **`--templates` 是内置节点的必填声明**(每个标记各写全清单):open → `CHANGE.md,REQUIREMENT.md` · design → `DESIGN.md`(前端可加 `UI-DESIGN.md`)· plan → `TASK.md` · execute / subagent-execute → `SUMMARY.md` · review → `REVIEW.md,TEST.md` · verify / archive 为零模板节点,**省略该参数**。逐节点示例命令见各节点册的「加载声明」小节。
117
127
 
118
- > **加载链的两条指针**:节点入口**先**打印 `READ PROMPT:`(指向 `flow-kit/prompts/<阶段>.md`——这一步怎么做),**再**打印 `READ TEMPLATE:`(指向 `flow-kit/templates/<DOC>.md`——产出长什么样),**有模板的节点两行都要读**;零模板节点(verify / archive)只有 `READ PROMPT:`。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);落在节点协议面外的路径会在下一次入口被拦下(BLOCKED)并给出重声明命令——重跑声明即可,不要手改标记。
128
+ > **加载链的两条指针**:节点入口**先**打印 `READ PROMPT:`(指向 `flow-kit/prompts/<阶段>.md`——这一步怎么做),**再**打印 `READ TEMPLATE:`(指向 `flow-kit/templates/<DOC>.md`——产出长什么样),**有模板的节点两行都要读**;零模板节点(verify / archive)只有 `READ PROMPT:`。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);落在节点协议面外的路径会在下一次入口被拦下(BLOCKED,逐条点名)并给出重声明命令——**入口只判「写下的每条声明对不对」,不判「该写的都写了没有」**:该节点该读却还没声明的那几份由出口的声明门逐份点名(见下方「exit 核对声明标记」)。重跑声明即可,不要手改标记。
119
129
 
120
130
  > **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
121
131
 
122
- 节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。`flow-comet-ui-design` 与协议同等级(`guarded`)且**仅前端适用**:前端 change 须先加载并 `skill-load` 声明、record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端不加载不声明(出口输出可见的 `UI-DESIGN: skipped(非前端)`);旧 change 渐进,缺件仅 WARN。前端判据是**结构级**的:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」不算标注,仍判前端。
132
+ 节点退出(exit)与证据记录(record)会核对声明标记。
133
+
134
+ **exit 核对声明标记(覆盖判据)——判据是「全部覆盖」,不是「任一命中」**。两条同时成立才算声明齐备,缺任一条即判缺声明:
135
+
136
+ - **协议文件面**:该节点该读的**每一份**协议文件都要被声明过(open 两份、review 两份,其余节点一份)。多份可以在同一个标记的 `protocols` 里(一条命令给多个 `--prompt`),也可以分散在各技能自己的标记上——判据按节点汇总,只看这些文件是否都被声明过。
137
+ - **技能面**:协议 `requiredSkillCalls` 里**每个** `guarded` 必需技能,都要有一个属于它的标记(适用性门控的绑定除外——`flow-comet-ui-design` 只在**前端** change 上要求,见下方该段判据)。**`handoff-guarded` 不在判据内**——那是子代理侧义务,由 Return Contract 的 `required-skill:` 核对负责(让协调者声明一个它没加载的技能,只会造出另一类假声明)。
138
+
139
+ **缺声明时的恢复命令形态**(BLOCKED / WARN 报文给的就是这个形态):报文按**协议派生**给出该节点**每个** `guarded` 必需技能各一条命令(`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> …`)——每条把该节点该读的**全部**协议文件都带上(多个 `--prompt`)并带 `--templates <该节点模板全清单>`,三个面一次给全,照抄即通。旧口径的 `skill-load <node> <skill> --prompt <缺的那份协议文件>` 只补缺项、漏模板清单,照抄完同一 exit 会再被覆盖门与模板门各拦一次(已废弃;报文仍逐项点名缺哪份协议文件、哪个必需技能,命令本身则给全)。同一 `<node>-<skill>` 重跑会**覆写**该标记,补齐后重试 `exit <node>`。**分级**:新 change BLOCKED(强制全部覆盖)、旧 change 只 WARN(既有 change 不因判据变严卡死)。**兼容**:判据改为全部覆盖之前写下的标记只有一个 `protocol` 单值(历史形态甚至是完整路径),照样按 basename 计入覆盖;不可解析的标记**不计入**,并在报文里列名——不静默当通过。
140
+
141
+ 声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。`flow-comet-ui-design` 与协议同等级(`guarded`)且**仅前端适用**:前端 change 须先加载并 `skill-load` 声明、record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端不加载不声明(出口输出可见的 `UI-DESIGN: skipped(非前端)`);旧 change 渐进,缺件仅 WARN。前端判据是**结构级**的:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」不算标注,仍判前端。
123
142
 
124
143
  > **侧命令**:`evolve`(架构沉淀同步)/ `health`(健康巡检)/ `context-scan`(上下文重扫)三条横向命令**不进 8 节点流程**——不路由、不 entry/exit、不写节点证据,一律由用户显式调用;触发词、命令面与落盘产物见主 `SKILL.md` 的「侧命令」小节(单一来源,本文不复述其命令表)。
125
144
 
@@ -10,6 +10,9 @@
10
10
  import { promises as fs } from 'fs';
11
11
  import path from 'path';
12
12
  import { EVOLVE_METADATA_SECTION, EVOLVE_METADATA_FIELDS } from './state-schema.mjs';
13
+ // 二级段体的段界(同级标题 / 分隔线 / 文末)取 lib/section-body.mjs 的唯一实现:本文件不再持有
14
+ // 第二份「按标题切段体」的行扫描(同一件事两份实现必然分叉)。
15
+ import { sectionBody } from './lib/section-body.mjs';
13
16
 
14
17
  // 既有 AI 上下文文档探测清单(与 flow-kit 入场判定同源:AGENTS/CLAUDE/Cursor/Windsurf/Copilot/Cline)
15
18
  const AI_DOC_CANDIDATES = [
@@ -174,15 +177,22 @@ async function contextSections(runRoot) {
174
177
  // 无任何生产者,故已从通过判据移除(取值单形 = state-schema 的 EVOLVE_METADATA_FIELDS)。本常量
175
178
  // 只用于**提示**:既有文档带该别名时,报错文案点名它并给出应写字段,让格式问题可见且可改写。
176
179
  const EVOLVE_DEPRECATED_SUGGESTION_FIELD = '下次同步建议';
180
+ // 「已锁决策」段名:在场判定与段内判定共用本常量(两处各写一份字面量,改名时必然分叉)。
181
+ const LOCKED_DECISIONS_SECTION = '已锁决策';
182
+
177
183
  // 模板关键格式检查(flow-kit/templates/CONTEXT.md 基准——段存在时校验其内格式,确定性检查)
178
184
  const CONTEXT_FORMAT_CHECKS = [
179
185
  {
180
186
  name: '已锁决策条目日期前缀',
181
- applies: (t) => t.includes('## 已锁决策'),
187
+ applies: (t) => t.includes('## ' + LOCKED_DECISIONS_SECTION),
182
188
  // 段内列表条目须带日期 `- [20xx-xx-xx]`;占位条目([xxx] 形态/待沉淀类/模板尖括号)放行——
183
- // 新项目骨架(无历史决策)不应被格式校验拒绝(DF-5)。
189
+ // 新项目骨架(无历史决策)不应被格式校验拒绝(DF-5)。段体经 contextSectionBody 切片:段界只由
190
+ // lib/section-body.mjs 决定(围栏内的标题不结束段体),本文件不再自带第二份「按标题切段」——
191
+ // 此前这里用字符串字面量切分(`.split('## 已锁决策')` 后再 `.split('\n##')`),是一份只在本文件
192
+ // 存在、且静态锁看不见的段体切片:同一个「这一段到哪里结束」由两处决定时,围栏 / 分隔线 / 段名
193
+ // 归一的差异迟早让两处给出不同答案。
184
194
  passes: (t) => {
185
- const seg = (t.split('## 已锁决策')[1] ?? '').split('\n##')[0];
195
+ const seg = contextSectionBody(t, LOCKED_DECISIONS_SECTION) ?? '';
186
196
  const items = seg.split('\n').filter((l) => /^\s*-\s+/.test(l));
187
197
  if (items.length === 0) return true; // 空段放行
188
198
  const bare = items.filter((l) => {
@@ -206,14 +216,14 @@ const CONTEXT_FORMAT_CHECKS = [
206
216
  // 「跑过一次但字段写残」正是最需要拦的半成品(段在场却少字段,元数据双落点会静默失真)。
207
217
  // 段名与三字段名都取自 state-schema.mjs 的单一常量集(写方 evolve.mjs 同源),本处不再写字面量。
208
218
  name: EVOLVE_METADATA_SECTION + '三字段',
209
- // 三字段判定**限定在段内**(sectionBody 切片):全文 includes 会被别处的同名字段蒙混过关——
210
- // 例如 intel-scan 段有 `**scanner**` 而 evolve 段少这一个字段,全文判定照样放行。
211
- applies: (t) => sectionBody(t, '## ' + EVOLVE_METADATA_SECTION) !== null,
219
+ // 三字段判定**限定在段内**(contextSectionBody 切片,段界来自单源):全文 includes 会被别处的同名字
220
+ // 字段蒙混过关——例如 intel-scan 段有 `**scanner**` 而 evolve 段少这一个字段,全文判定照样放行。
221
+ applies: (t) => contextSectionBody(t, EVOLVE_METADATA_SECTION) !== null,
212
222
  // 通过判据是**单形**的:取值只认常量集(写方真实产出的三个字段名)。旧的协作期容差别名
213
223
  // (`下次同步建议`)没有任何生产者,已从判据中移除——容纳它就是「校验集合 ⊃ 生产集合」,
214
224
  // 写残的段会被静默放行。带旧别名的既有文档由下方 hint 给出可见的改写指引,不是静默失败。
215
225
  passes: (t) => {
216
- const segment = sectionBody(t, '## ' + EVOLVE_METADATA_SECTION) ?? '';
226
+ const segment = contextSectionBody(t, EVOLVE_METADATA_SECTION) ?? '';
217
227
  return EVOLVE_METADATA_FIELDS.every((field) => segment.includes('**' + field + '**'));
218
228
  },
219
229
  hint: '字段 ' + EVOLVE_METADATA_FIELDS.join(' / ') + ';与 intel-scan 段同构'
@@ -301,23 +311,16 @@ function headingSet(text) {
301
311
  // `## evolve 元数据`)不得算段在场——可选段的「缺席不报」语义完全依赖这一点;字段判定限定段内,
302
312
  // 否则别处的同名标签会替缺失字段蒙混过关。必填段的同名检查沿用历史 includes 写法(缺段另有
303
313
  // missingSections 兜底,报道面不变),故两条检查的在场判据措辞不同是刻意的,不是漏改。
304
- function sectionBody(body, headingName) {
314
+ // 段界(同级标题 / 分隔线 / 文末)由 lib/section-body.mjs 单点决定,本文件只表达命中方式:恰好
315
+ // 二级 + 段名归一后相等。调用方给的是**结构文本**(围栏代码块已剥离,见 validateContext),因此围栏
316
+ // 里的书写样例既不结束段体、也不被当成数据。
317
+ function contextSectionBody(structureText, headingName) {
305
318
  const wanted = normalizeSectionName(headingName);
306
- const kept = [];
307
- let inSection = false;
308
- for (const line of String(body ?? '').split('\n')) {
309
- const heading = /^(#{1,6})[ \t]+(.+?)[ \t]*$/.exec(line);
310
- if (heading) {
311
- const level = heading[1].length;
312
- if (inSection && level <= 2) break; // 到下一个同级或更高级标题即段结束
313
- if (!inSection && level === 2 && normalizeSectionName(heading[2]) === wanted) {
314
- inSection = true;
315
- continue;
316
- }
317
- }
318
- if (inSection) kept.push(line);
319
- }
320
- return inSection ? kept.join('\n') : null;
319
+ return sectionBody(
320
+ structureText,
321
+ (heading) => heading.level === 2 && normalizeSectionName(heading.text) === wanted,
322
+ { level: 2, endOnSeparator: false },
323
+ );
321
324
  }
322
325
 
323
326
  // 校验 .specs/CONTEXT.md 7 段结构 + 模板关键格式;文件缺失 = 全缺。返回
@@ -19,9 +19,7 @@ import {
19
19
  } from './lib/test-helpers.mjs';
20
20
  import {
21
21
  BUILTIN_PROTOCOL_SOURCE,
22
- REPO_ROOT,
23
22
  createdDirs,
24
- isAuthoritativeSourceRepo,
25
23
  makeTmp,
26
24
  sleepSync,
27
25
  } from './lib/test-fixtures.mjs';
@@ -29,16 +27,7 @@ import {
29
27
  scenarioProtocolPath,
30
28
  } from './lib/test-assertions.mjs';
31
29
  import {
32
- PUBLIC_CODE_RE,
33
- SCENARIO_COUNT_FILES,
34
- SCENARIO_COUNT_FILES_MAINTAINER,
35
- SYSTEM_TEST_COUNT_FILES,
36
- SYSTEM_TEST_COUNT_FILES_MAINTAINER,
37
- countSyncProblems,
38
- internalDocsProblems,
39
- maintainerFacePresent,
40
- maintainerFaceSkips,
41
- vocabularyMirrorProblems,
30
+ publicFaceSelfCheck,
42
31
  } from './lib/text-anchor-checks.mjs';
43
32
 
44
33
  import { ENTRIES as SCENARIOS_A } from './scenarios/a.mjs';
@@ -103,89 +92,20 @@ for (const sc of SCENARIOS) {
103
92
 
104
93
  console.log('RESULT: ' + passed + '/' + SCENARIOS.length + ' scenarios passed');
105
94
 
106
- // 文档一致性自检(场景数纪律 + 公开产物零代号纪律工具化):
107
- // ① 场景数:受检清单文档须与 SCENARIOS.length 一致(全变体检查),且清单条目必须真实存在
108
- // (AC-14:缺失显式报告,不静默跳过);
109
- // ② 公开产物零代号:公开文档不得含过程代号(场景编号/修复编号/批次/缺陷编号/问题级/验证代号/验证轮次/未公开概念——历史 CHANGELOG 回归实证)。
110
- // 仅权威源检出执行;安装副本(目标项目)无 flow-comet 文档面,跳过。
111
- if (isAuthoritativeSourceRepo()) {
112
- // ①a 受检面可见化(F2 防漂移):实际受检文件数由模块级常量**推导**、不硬编码——分发组 =
113
- // SCENARIO_COUNT_FILES ∪ SYSTEM_TEST_COUNT_FILES(后者为前者子集),维护者组 =
114
- // SCENARIO_COUNT_FILES_MAINTAINER ∪ SYSTEM_TEST_COUNT_FILES_MAINTAINER(后者为前者子集);
115
- // 维护者面缺席(CI 全新检出 / worktree)时按组跳过语义只计分发面。本行是对外可复核的
116
- // 「覆盖面事实」——清单增删/口径漂移在此直接可见,不再依赖人工核对注释(F2 根因)。
117
- const distFaceCount = new Set([...SCENARIO_COUNT_FILES, ...SYSTEM_TEST_COUNT_FILES]).size;
118
- const maintainerFaceCount = maintainerFacePresent()
119
- ? new Set([...SCENARIO_COUNT_FILES_MAINTAINER, ...SYSTEM_TEST_COUNT_FILES_MAINTAINER]).size
120
- : 0;
121
- console.log('受检面: ' + (distFaceCount + maintainerFaceCount) + ' 文件(分发 ' + distFaceCount
122
- + ' + 维护者 ' + maintainerFaceCount + ')');
123
- // ① 计数一致性受检清单(分发组恒检 + 维护者组整组在场时检;判据与场景 105 共用同一实现)
124
- // SCENARIO_COUNT_FILES(_MAINTAINER) / SYSTEM_TEST_COUNT_FILES(_MAINTAINER) 为模块级常量
125
- // (见文件头定义)——场景数与系统测试集项数两套计数合并检查
126
- for (const problem of await countSyncProblems()) {
127
- failures.push({ name: '计数一致性', error: problem });
128
- console.error('FAIL: 计数一致性\n' + problem);
129
- }
130
-
131
- // ①b 维护文档机检(docs/internal 死引用 + ROADMAP 最低结构;整组缺席即跳过)
132
- for (const problem of internalDocsProblems()) {
133
- failures.push({ name: '维护文档机检', error: problem });
134
- console.error('FAIL: 维护文档机检\n' + problem);
135
- }
136
-
137
- // ①c 维护者面缺席可见化:结构性缺席(worktree / CI 全新检出)不判失败(退出码不变、不误红),
138
- // 但必须可见——逐面输出 SKIP 行(面名 + 原因 + 本检出未执行什么校验 + 回维护者主树重跑的指引)。
139
- for (const skip of maintainerFaceSkips()) {
140
- console.log('SKIP: ' + skip.face + ' — ' + skip.reason
141
- + ';本次检出未执行该面校验,请在维护者主树重跑本套件(主树 L1),勿把跳过当成已校验。');
142
- }
143
-
144
- // ② 公开文档零代号(公开产物纪律——变更日志历史编号回归的教训)
145
- const PUBLIC_DOCS = [
146
- 'README.md', 'README-zh.md', 'CONTRIBUTING.md', 'CONTRIBUTING-zh.md',
147
- 'SECURITY.md', 'SECURITY-zh.md', 'CODE_OF_CONDUCT.md', 'CODE_OF_CONDUCT-zh.md',
148
- 'CHANGELOG.md', 'CHANGELOG-zh.md',
149
- 'docs/INSTALLATION.md', 'docs/INSTALLATION-zh.md', 'docs/MECHANISM.md', 'docs/MECHANISM-zh.md',
150
- 'docs/USAGE.md', 'docs/USAGE-zh.md',
151
- 'docs/TROUBLESHOOTING.md', 'docs/TROUBLESHOOTING-zh.md', 'docs/VERSIONS.md', 'docs/VERSIONS-zh.md',
152
- '.github/PULL_REQUEST_TEMPLATE.md',
153
- '.github/ISSUE_TEMPLATE/1-bug_report.yml', '.github/ISSUE_TEMPLATE/2-feature_request.yml',
154
- '.github/ISSUE_TEMPLATE/3-question.md', '.github/ISSUE_TEMPLATE/4-task.md',
155
- ];
156
- // 词表判据 = 模块级 PUBLIC_CODE_RE(与 .githooks/internal-codes.mjs 的 BANNED 同判据,
157
- // 见其定义处的同步约定;维护文档机检场景族另有该判据的判别力/边界锚)。
158
- for (const rel of PUBLIC_DOCS) {
159
- let text;
160
- try {
161
- text = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
162
- } catch (e) {
163
- // ENOENT 同样显式报告:本清单全部为随仓库分发的文件,任何权威源检出都应存在——
164
- // 静默跳过会让"永不生效的条目"藏身(同类 AC-14 缺陷)。
165
- failures.push({ name: '公开产物零代号(' + rel + ')', error: '文件缺失: ' + e.message });
166
- console.error('FAIL: 公开产物零代号(' + rel + ')\n文件缺失: ' + e.message);
167
- continue;
168
- }
169
- const m = text.match(PUBLIC_CODE_RE);
170
- if (m) {
171
- failures.push({ name: '公开产物零代号(' + rel + ')', error: rel + ' 含过程代号: "' + m[0] + '"' });
172
- console.error('FAIL: 公开产物零代号(' + rel + ')\n' + rel + ' 含过程代号: "' + m[0] + '"');
173
- }
174
- }
175
-
176
- // ③ 词表镜像漂移:主仓私有的词表单一来源与套件内的同义镜像必须**逐字符
177
- // 等价**——两侧此前只有注释互指"同步"、零一致性判据:主仓增补模式时分发侧扫描静默落后
178
- // (新词可在公开面长期存活而套件全绿),反向则分发面误红。判据只读文件、不改任何判定语义。
179
- for (const problem of vocabularyMirrorProblems()) {
180
- failures.push({ name: '词表镜像漂移', error: problem });
181
- console.error('FAIL: 词表镜像漂移\n' + problem);
182
- }
95
+ // 文档一致性自检(场景数纪律 + 公开产物零代号纪律工具化):形态分派(权威源检出 / 包形态 / 安装
96
+ // 副本)与四条判据(计数一致性 / 维护文档机检 / 公开产物零代号 / 词表镜像)的唯一实现在
97
+ // lib/text-anchor-checks.mjs 的 publicFaceSelfCheck——本处只负责调用与打印。该判定接受任意根,
98
+ // 故它另有常驻场景锚(公开面形态分派探针),不必等到在包形态里整跑一次才知道分派对不对。
99
+ const selfCheck = await publicFaceSelfCheck();
100
+ if (selfCheck.skip !== null) {
101
+ // 该形态不含这一面:仍然显式可见——SKIP = 未校验,不是通过。
102
+ console.log(selfCheck.skip.notice);
183
103
  } else {
184
- // 安装副本形态:.githooks 是主仓私有面(随 clone 不分发)→ 该判据**不适用**。结构性缺席
185
- // 不判失败(退出码不变、不误红),但必须显式可见——未验证 ≠ 通过,不得静默跳过。
186
- console.log('SKIP/NOT-APPLICABLE: 词表镜像漂移判据(.githooks 为主仓私有面)'
187
- + ';本次检出无该私有面,未执行「词表单一来源 ↔ 套件同义镜像」的逐字符等价性比对'
188
- + '——请在主仓私有面在场处重跑本套件(主树 L1),勿把不适用当成已校验。');
104
+ for (const notice of selfCheck.notices) console.log(notice);
105
+ for (const problem of selfCheck.problems) {
106
+ failures.push(problem);
107
+ console.error('FAIL: ' + problem.name + '\n' + problem.error);
108
+ }
189
109
  }
190
110
 
191
111
  // 清理验证:自测套件自身创建的临时目录不留残留
@@ -10,7 +10,7 @@
10
10
  import fs from 'fs';
11
11
  import path from 'path';
12
12
  import { createHash } from 'crypto';
13
- import { assertEqual, assertExit, assertNotOut, assertOut, assertTrue, baseState, runGuard, runHandoff, runState, writeFile, writeState } from '../lib/test-helpers.mjs';
13
+ import { assertEqual, assertExit, assertNotOut, assertOut, assertTrue, baseState, installSkillTreeCopy, runGuard, runHandoff, runPrintedCommand, runState, writeFile, writeState } from '../lib/test-helpers.mjs';
14
14
  import { archiveRecordJson, multiWaveTaskContent, explainContractProblems, assertExplainFailClosed, explainReverseConstructionProblems, CHANGE_ID, readStateFile, gitInit, gitBranch, writeIntakeArtifacts, fullContract, execSummaryFixture, assertNodeLine, driveThroughDesign } from '../lib/system-fixtures.mjs';
15
15
 
16
16
  // skill-load 的模板声明(节点级,C3/AC-13 加载链):参数化的委托驱动按节点查表——夹具是真实命令
@@ -30,6 +30,30 @@ function skillLoadArgs(nodeId, skill, prompt) {
30
30
  return args;
31
31
  }
32
32
 
33
+ // 协议 requiredSkillCalls 中 enforcement='guarded' 的协调者技能(逐节点查表,与
34
+ // reference/workflow-protocol.json 同值):节点实现技能与必需技能是两个声明面——出口的覆盖判据
35
+ // 要求每份必需技能都有自己的标记,拿实现技能的标记顶替不了。handoff scope 的技能(subagent-execute
36
+ // 的 flow-comet-dev 由子代理加载)不在此表:协调者不加载它,声明它反而是假声明。
37
+ const REQUIRED_SKILL_DECLARATION = {
38
+ plan: { skill: 'flow-comet-task', prompt: 'flow-kit/prompts/3-task.md' },
39
+ execute: { skill: 'flow-comet-dev', prompt: 'flow-kit/prompts/4-dev.md' },
40
+ review: { skill: 'flow-comet-test', prompt: 'flow-kit/prompts/5-test.md' },
41
+ verify: { skill: 'flow-comet-integration', prompt: 'flow-kit/prompts/7-integration.md' },
42
+ archive: { skill: 'flow-comet-integration', prompt: 'flow-kit/prompts/7-integration.md' },
43
+ };
44
+
45
+ // 节点声明的完整形态(两个多趟驱动共用):实现技能 + 同名的 guarded 必需技能。不共用时两处驱动
46
+ // 各写一遍补声明,下一处需要补的地方又会漏。
47
+ function declareNodeDeclarations(dir, env, nodeId, skill, prompt) {
48
+ assertExit(runState(skillLoadArgs(nodeId, skill, prompt), dir, env), 0);
49
+ const required = REQUIRED_SKILL_DECLARATION[nodeId];
50
+ // 必需技能有自己的协议文件(review 的 flow-comet-test 读 5-test.md)——用实现技能的提示词补声明,
51
+ // 技能面覆盖了但协议文件面仍缺,出口照样拦
52
+ if (required && required.skill !== skill) {
53
+ assertExit(runState(skillLoadArgs(nodeId, required.skill, required.prompt), dir, env), 0);
54
+ }
55
+ }
56
+
33
57
  export const ENTRIES = [
34
58
  // ---------- A. 状态机与路由 ----------
35
59
 
@@ -134,6 +158,8 @@ export const ENTRIES = [
134
158
  run: (dir) => {
135
159
  assertExit(runState(['init', CHANGE_ID], dir), 0);
136
160
  assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
161
+ // open 该读两份协议、协议声明两个必需技能:出口覆盖判据要求全部声明,夹具两条都写下
162
+ assertExit(runState(['skill-load', 'open', 'flow-comet-requirement', '--prompt', 'flow-kit/prompts/1-requirement.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
137
163
  writeIntakeArtifacts(dir);
138
164
  assertExit(runState(['record', 'open', '{"summary":"intake complete"}'], dir), 0);
139
165
  // 真实出口:exit open --apply(未激活声明机制 → 兼容警告 + 通过)
@@ -378,6 +404,9 @@ export const ENTRIES = [
378
404
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md',
379
405
  multiWaveTaskContent({ P01: 'pending', P02: 'pending', S01: 'pending', P03: 'pending' }));
380
406
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
407
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):节点实现技能与必需技能是两个声明面,
408
+ // 出口覆盖判据要求后者也有标记。
409
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
381
410
  assertExit(runState(['record', 'plan', '{"summary":"plan done"}'], dir), 0);
382
411
  assertExit(runGuard(['entry', 'plan'], dir), 0);
383
412
  const rPlan = runGuard(['exit', 'plan', '--apply'], dir);
@@ -385,6 +414,39 @@ export const ENTRIES = [
385
414
  assertOut(rPlan, 'ALL CHECKS PASSED');
386
415
  // 首趟路由:首波双并行无前置依赖 → 直接进入委托节点
387
416
  assertOut(rPlan, 'NODE: subagent-execute');
417
+ // 委托前置门的声明命令必须照抄可执行:解析打印文本 → 真执行 → 再 request 通过。旧形态是
418
+ // 「workflow-state.mjs skill-load <node> <skill>」——裸脚本名在 shell 里 command not found,
419
+ // `<skill>` 占位在 bash 下是重定向,且不带该节点全部 --prompt / --templates / --protocol,
420
+ // 字面断言钉不住「这条命令能不能用」。同一次 request 还断言开工前 LESSONS 命中集的围栏口径:
421
+ // 围栏里的书写样例不是真条目(围栏判定与段体单源同口径),围栏外的条目照常命中。
422
+ writeFile(dir, '.specs/LESSONS.md',
423
+ '# LESSONS\n\n## 条目区\n\n~~~md\n### L-901 · [proc] 围栏内的书写样例\n- **关键词**: p01 委托边界\n~~~\n\n'
424
+ + '### L-902 · [proc] 委托边界须留痕\n- **关键词**: p01\n');
425
+ const gatedRequest = runHandoff(['request', 'P01', 'P01 委托'], dir);
426
+ assertExit(gatedRequest, 1);
427
+ assertOut(gatedRequest, 'BLOCKED: 节点 subagent-execute 缺少技能加载声明标记');
428
+ assertNotOut(gatedRequest, 'HANDOFF REQUEST');
429
+ const declarationCommand = (gatedRequest.output.match(/^\s*(node "[^"]+" skill-load [^\n]+)$/m) || [])[1];
430
+ assertTrue(typeof declarationCommand === 'string',
431
+ '委托前置门的阻塞必须给出完整可执行命令(node "<脚本路径>" skill-load …):\n' + gatedRequest.output);
432
+ // 打印命令按安装布局的执行面解析(脚本根是运行根相对形态):先把技能树复制成安装副本,
433
+ // 再真跑打印文本——执行的是打印出来的脚本路径与参数,不是 harness 自己的绝对路径。
434
+ installSkillTreeCopy(dir, path.join('.claude', 'skills'));
435
+ const replayedDeclaration = runPrintedCommand(declarationCommand, dir,
436
+ { FLOW_COMET_RUN_ROOT: dir, FLOW_COMET_PROTOCOL: '' });
437
+ assertTrue(replayedDeclaration.status === 0,
438
+ '照抄的声明命令跑不通\n 命令: ' + declarationCommand
439
+ + '\n exit ' + replayedDeclaration.status + '\n' + replayedDeclaration.output);
440
+ const declaredRequest = runHandoff(['request', 'P01', 'P01 委托'], dir);
441
+ assertExit(declaredRequest, 0);
442
+ assertOut(declaredRequest, 'HANDOFF REQUEST: P01');
443
+ assertOut(declaredRequest, 'LESSONS-HITS: 1 条');
444
+ assertOut(declaredRequest, 'L-902');
445
+ assertNotOut(declaredRequest, 'L-901');
446
+ // 这一格考的是开工前打印面(命中集 + 围栏判定)。出口侧的「逐条回应」判据按**任务写面**算命中,
447
+ // 本夹具的 L-902 只会落在 P01 的扫描段上——留着教训册就要把 A13 后续每份 SUMMARY 的措辞一并改写,
448
+ // 而那条判据另有场景逐格考(含缺回应 / 围栏内回应)。断言完成后撤掉夹具,A13 其余步骤保持原基线。
449
+ fs.rmSync(path.join(dir, '.specs', 'LESSONS.md'), { force: true });
388
450
  // 两层加载模型:执行域两节点的手动声明标记(record 前置门;一次声明后续趟次复用)
389
451
  assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir), 0);
390
452
  assertExit(runState(['skill-load', 'subagent-execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir), 0);
@@ -503,6 +565,9 @@ export const ENTRIES = [
503
565
  '<task id="X2" parallel="true" status="pending"><action>实现 X2</action><write_files>src/x2.mjs</write_files><verify>node --check src/x2.mjs</verify><depends_on>X1</depends_on></task>\n';
504
566
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + cyclic);
505
567
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
568
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):节点实现技能与必需技能是两个声明面,
569
+ // 出口覆盖判据要求后者也有标记。
570
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
506
571
  assertExit(runState(['record', 'plan', '{"summary":"plan drafted"}'], dir), 0);
507
572
  assertExit(runGuard(['entry', 'plan'], dir), 0);
508
573
  const blocked = runGuard(['exit', 'plan', '--apply'], dir);
@@ -560,7 +625,7 @@ export const ENTRIES = [
560
625
  // next 对「currentNode 无 evidence 且非固定路由后继」的委托跳转态按正常推进豁免不放行,
561
626
  // 仅断言 guard 侧 NODE;直接后继/回流态(next 可确认)才做双侧收敛断言。
562
627
  const drive = (nodeId, skill, prompt, prepare, { expectedNode, converge = true } = {}) => {
563
- assertExit(runState(skillLoadArgs(nodeId, skill, prompt), dir, env), 0);
628
+ declareNodeDeclarations(dir, env, nodeId, skill, prompt);
564
629
  prepare();
565
630
  assertExit(runGuard(['entry', nodeId], dir), 0);
566
631
  const res = runGuard(['exit', nodeId, '--apply'], dir);
@@ -625,6 +690,8 @@ export const ENTRIES = [
625
690
  }, { expectedNode: 'archive', converge: true });
626
691
  // 归档出口:两侧均 NEXT: done
627
692
  assertExit(runState(['skill-load', 'archive', 'flow-comet-archive', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
693
+ // 协议 archive.requiredSkillCalls = flow-comet-integration(guarded):出口覆盖判据要求该技能也有标记
694
+ assertExit(runState(['skill-load', 'archive', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
628
695
  writeFile(dir, '.specs/archive/2026-08-28-' + CHANGE_ID + '/KNOWN-ISSUES.md', '# 遗留问题\n\n无。\n');
629
696
  // 归档提名随证据落盘:本 change 写了 6 份任务 SUMMARY(并行 4 份 + 串行 2 份,扫描份数按
630
697
  // 同一清单对账)。提名门缺字段即拦,与本条被测的路由收敛判据无关。
@@ -657,6 +724,9 @@ export const ENTRIES = [
657
724
  const exitPlanNoApply = () => runGuard(['exit', 'plan'], dir, planEnv);
658
725
  const exitPlanApply = () => runGuard(['exit', 'plan', '--apply'], dir, planEnv);
659
726
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
727
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):节点实现技能与必需技能是两个声明面,
728
+ // 出口覆盖判据要求后者也有标记。
729
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
660
730
  assertExit(runState(['record', 'plan', '{"summary":"plan drafted"}'], dir), 0);
661
731
  assertExit(runGuard(['entry', 'plan'], dir), 0);
662
732
  const planTask = (taskBody) => writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + taskBody);
@@ -714,6 +784,18 @@ export const ENTRIES = [
714
784
  assertExit(globRecovered, 0);
715
785
  assertOut(globRecovered, 'ALL CHECKS PASSED');
716
786
  assertNotOut(globRecovered, 'BLOCKED');
787
+ // 写面判定的元素名大小写无关:`<WRITE_FILES>` 与 `<write_files>` 是同一种元素——7 字段门按
788
+ // 大小写不敏感判定在场,而「这份写面算不算有内容」的判据若只认小写,大写写法的任务就被静默
789
+ // 排除在 [P] 补集判据之外:同波同层、写面互不重叠的一对永远不被要求标 parallel(判据在场才判,
790
+ // 判据缺席就是放行)。
791
+ planTask(
792
+ '## 波次划分\n\nWave 1: U01, U02\n\n## 任务清单\n\n'
793
+ + '<task id="U01" status="pending"><action>实现 U01</action><WRITE_FILES>src/u01.mjs</WRITE_FILES><verify>node --check src/u01.mjs</verify></task>\n'
794
+ + '<task id="U02" status="pending"><action>实现 U02</action><WRITE_FILES>src/u02.mjs</WRITE_FILES><verify>node --check src/u02.mjs</verify></task>\n');
795
+ const upperCaseWriteFiles = exitPlanNoApply();
796
+ assertExit(upperCaseWriteFiles, 1);
797
+ assertOut(upperCaseWriteFiles, '同波任务可并行却未标 [P]');
798
+ assertOut(upperCaseWriteFiles, 'U01 × U02');
717
799
  // 同一文件跨任务族(负例):两个非修复任务写入同一文件、彼此无依赖路径(串行拆分同样构成
718
800
  // 「未显式排序的同文件多任务」)→ 新 change BLOCKED,消息含任务对与重叠文件 + 恢复指引。
719
801
  // 同夹具并列一对修复任务(id 带修复前缀)写同一文件且无依赖路径——该族不参与判定,
@@ -820,7 +902,7 @@ export const ENTRIES = [
820
902
  };
821
903
  // drive 收敛面全量:每个转换点(含平行跳转与趟间回流)都断言 next 可达且与 guard 出口 NODE 一致
822
904
  const drive = (nodeId, skill, prompt, prepare, { expectedNode } = {}) => {
823
- assertExit(runState(skillLoadArgs(nodeId, skill, prompt), dir, env), 0);
905
+ declareNodeDeclarations(dir, env, nodeId, skill, prompt);
824
906
  prepare();
825
907
  assertExit(runGuard(['entry', nodeId], dir), 0);
826
908
  const res = runGuard(['exit', nodeId, '--apply'], dir);
@@ -884,6 +966,8 @@ export const ENTRIES = [
884
966
  }, { expectedNode: 'archive' });
885
967
  // 归档出口:两侧均 NEXT: done
886
968
  assertExit(runState(['skill-load', 'archive', 'flow-comet-archive', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
969
+ // 协议 archive.requiredSkillCalls = flow-comet-integration(guarded):出口覆盖判据要求该技能也有标记
970
+ assertExit(runState(['skill-load', 'archive', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
887
971
  writeFile(dir, '.specs/archive/2026-08-28-' + CHANGE_ID + '/KNOWN-ISSUES.md', '# 遗留问题\n\n无。\n');
888
972
  // 归档提名随证据落盘:本 change 写了 6 份任务 SUMMARY(并行 4 份 + 串行 2 份,扫描份数按
889
973
  // 同一清单对账)。提名门缺字段即拦,与本条被测的路由收敛判据无关。
@@ -918,6 +1002,8 @@ export const ENTRIES = [
918
1002
  driveThroughDesign(dir);
919
1003
  writeTask({ S01: 'pending' });
920
1004
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
1005
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):出口覆盖判据要求该技能也有标记
1006
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
921
1007
  assertExit(runState(['record', 'plan', '{"summary":"plan complete"}'], dir, env), 0);
922
1008
  assertExit(runGuard(['entry', 'plan'], dir), 0);
923
1009
  assertExit(runGuard(['exit', 'plan', '--apply'], dir), 0);
@@ -925,6 +1011,8 @@ export const ENTRIES = [
925
1011
  writeTask({ S01: 'done' });
926
1012
  writeFile(dir, '.specs/' + CHANGE_ID + '/S01-SUMMARY.md', execSummaryFixture('S01'));
927
1013
  assertExit(runState(['skill-load', 'execute', 'flow-comet-execute', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
1014
+ // 协议 execute.requiredSkillCalls = flow-comet-dev(guarded):出口覆盖判据要求该技能也有标记
1015
+ assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
928
1016
  assertExit(runState(['record', 'execute', '{"summary":"executed","parallelTakeoverApproved":true}'], dir, env), 0);
929
1017
  assertExit(runGuard(['entry', 'execute'], dir), 0);
930
1018
  // R-1 欠账漂移态:currentNode 漂移到文件推导下一节点 review(execute 未 completed)
@@ -964,6 +1052,8 @@ export const ENTRIES = [
964
1052
  driveThroughDesign(dir);
965
1053
  writeTask({ P01: 'pending', S01: 'pending' });
966
1054
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
1055
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):出口覆盖判据要求该技能也有标记
1056
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
967
1057
  assertExit(runState(['record', 'plan', '{"summary":"plan complete"}'], dir, env), 0);
968
1058
  assertExit(runGuard(['entry', 'plan'], dir), 0);
969
1059
  assertExit(runGuard(['exit', 'plan', '--apply'], dir), 0);
@@ -1019,6 +1109,8 @@ export const ENTRIES = [
1019
1109
  driveThroughDesign(dir);
1020
1110
  writeTask({ S01: 'pending' });
1021
1111
  assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
1112
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):出口覆盖判据要求该技能也有标记
1113
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir, env), 0);
1022
1114
  assertExit(runState(['record', 'plan', '{"summary":"plan complete"}'], dir, env), 0);
1023
1115
  assertExit(runGuard(['entry', 'plan'], dir), 0);
1024
1116
  assertExit(runGuard(['exit', 'plan', '--apply'], dir), 0);
@@ -1026,6 +1118,8 @@ export const ENTRIES = [
1026
1118
  writeTask({ S01: 'done' });
1027
1119
  writeFile(dir, '.specs/' + CHANGE_ID + '/S01-SUMMARY.md', execSummaryFixture('S01'));
1028
1120
  assertExit(runState(['skill-load', 'execute', 'flow-comet-execute', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
1121
+ // 协议 execute.requiredSkillCalls = flow-comet-dev(guarded):出口覆盖判据要求该技能也有标记
1122
+ assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
1029
1123
  assertExit(runState(['record', 'execute', '{"summary":"executed"}'], dir, env), 0);
1030
1124
  assertExit(runGuard(['entry', 'execute'], dir), 0);
1031
1125
  // 执行者自切 direct(directOverride=true 但无授权审计记录——B 方案前的自切/遗留形态)