flow-comet 1.6.4 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +36 -6
  3. package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
  4. package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
  5. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +29 -4
  7. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +174 -0
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +17 -95
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +136 -19
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +54 -18
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
  15. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  16. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +25 -10
  17. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +4 -2
  18. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +21 -13
  19. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +163 -0
  20. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +448 -0
  22. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +396 -27
  23. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1035 -172
  24. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +129 -98
  25. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  26. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +797 -232
  27. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +91 -22
  28. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +69 -13
  32. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +454 -135
  33. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +109 -13
  35. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
  36. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +149 -34
  37. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +79 -9
  38. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  39. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +78 -8
  40. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
  41. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +167 -3
  42. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
  43. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +287 -0
  44. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1454 -16
  45. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1205 -77
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +52 -11
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
  50. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +9 -1
  51. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
  52. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +22 -6
  53. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
  54. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +18 -5
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +4100 -0
  56. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
  57. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
  58. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +203 -4
  59. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
  60. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  61. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  62. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  63. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  64. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  65. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  66. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  67. package/.flow-comet/skills/flow-comet-execute/SKILL.md +42 -15
  68. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  69. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  70. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  71. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  72. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  73. package/.flow-comet/skills/flow-comet-plan/SKILL.md +21 -10
  74. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  75. package/.flow-comet/skills/flow-comet-review/SKILL.md +33 -18
  76. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  77. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +44 -16
  78. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  79. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  80. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  81. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  82. package/README.md +3 -3
  83. package/package.json +1 -1
  84. package/scripts/dsh-bridge.mjs +2 -2
  85. package/scripts/lib/installer-flowkit.mjs +43 -3
@@ -6,9 +6,11 @@ import fs from 'fs';
6
6
  import path from 'path';
7
7
  import { execFileSync } from 'child_process';
8
8
  import {
9
+ assertEqual,
9
10
  assertExit,
10
11
  assertNotOut,
11
12
  assertOut,
13
+ assertTrue,
12
14
  baseState,
13
15
  runGuard,
14
16
  runHandoff,
@@ -24,17 +26,39 @@ import {
24
26
  TASK_P1,
25
27
  TASK_P2,
26
28
  composeState,
29
+ engineCodeText,
27
30
  engineScriptFiles,
31
+ engineScriptTexts,
28
32
  handoffFor,
29
33
  strictSummary,
30
34
  summaryContent,
31
35
  timeUtilsModule,
32
36
  writeCustomProtocol,
37
+ writeNodeDeclarationMarkers,
33
38
  } from '../lib/test-fixtures.mjs';
34
39
  import {
35
40
  assertStateBytesUnchanged,
41
+ fixBatchTaskText,
36
42
  readStateBytes,
43
+ scenarioProtocolPath,
37
44
  } from '../lib/test-assertions.mjs';
45
+ // 命令文本的唯一实现(平台化脚本根 + 整条路径加引号):期望值只能从这里取,断言运行期
46
+ // 输出与 handoff 的 PREFLIGHT 同源同形——不是「看起来都像命令」。
47
+ import { scriptCommand } from '../lib/state-explain.mjs';
48
+ // 单一来源静态锁(COORDINATOR 常量的落点与取用面):与套件其它单源锚共用同一判据实现。
49
+ import { singleSourceImportProblems } from '../lib/text-anchor-checks.mjs';
50
+
51
+ // 声明工件枚举面的静态锁数据(判据见场景 08):outputSchemas → artifacts 的枚举只许在**唯一权威**
52
+ // 处(表内第一项)出现——出口的产物门禁与结构预检都只消费它,任一侧再自行遍历就是第二份实现,
53
+ // 两份副本可以逐字相同地并存、下一次演进才分叉。其余落点逐一登记并写明它为什么不是**同一条判据**;
54
+ // 登记面与实际枚举面双向对账(新增落点必须显式登记,被收编的落点必须从表里移除),第二份副本
55
+ // 因此既无法静默长出来,也不会在判据失去判别力时(连权威处都看不见)悄无声息。
56
+ const DECLARED_ARTIFACT_ENUMERATION_SITES = [
57
+ { file: 'lib/guard-routing.mjs', why: '唯一权威 declaredRequiredArtifacts(枚举 + <change-id> 替换 + 在场判定)' },
58
+ { file: 'route-node.mjs', why: '节点完成判定(状态机的完成标志集),另一条机制,不属于本判据的消费面' },
59
+ { file: 'lib/guard-template-fidelity.mjs', why: '工件 → 模板键映射:决定校验哪份工件,不做在场判定' },
60
+ { file: 'lib/state-explain.mjs', why: 'explain 的展示面:打印声明的产物路径,不做在场判定' },
61
+ ];
38
62
 
39
63
  export const ENTRIES = [
40
64
  // 1: open exit 通过(模板段名 CHANGE "## Why(为什么做)" + REQUIREMENT "## 用户故事(User Story)" + 验收段)——带模板验证 C2 派生
@@ -54,9 +78,12 @@ export const ENTRIES = [
54
78
  },
55
79
  },
56
80
 
57
- // 2: open exit BLOCKED——CHANGE.md 缺 Why 段
81
+ // 2: open exit 模板缺席——CHANGE.md 缺 Why 段:命名段判据跳过,但跳过必须可见(C9)
82
+ // 模板整份缺席(夹具没有 flow-kit/templates/)时 pick 不再回落到命名段兜底正则 ⇒ 「缺必填段」
83
+ // 判据不生效;但「不阻断」不等于「静默通过」——产出物结构门禁必须逐工件报到「未校验(模板缺失)」,
84
+ // 跳过因此自证(L-079)。模板在场但该段名缺席时 fallback 仍生效,见 TA-21 的反向构造。
58
85
  {
59
- name: '02 open exit BLOCKED:CHANGE 缺 Why 段',
86
+ name: '02 open exit 模板缺席:CHANGE 缺 Why 段不阻断,但显式报到「未校验(模板缺失)」',
60
87
  run: (dir) => {
61
88
  const st = baseState('open');
62
89
  st.evidence.open = { summary: 'intake complete' };
@@ -64,16 +91,21 @@ export const ENTRIES = [
64
91
  writeFile(dir, '.specs/' + CHANGE_ID + '/CHANGE.md', '# CHANGE\n\n## 变更目标\n\n## 方案\n');
65
92
  writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md', '# REQUIREMENT\n\n## 用户故事\n\n## 验收准则(AC)\n');
66
93
  const res = runGuard(['exit', 'open'], dir);
67
- assertExit(res, 1);
68
- assertOut(res, 'BLOCKED');
69
- assertOut(res, 'CHANGE.md 缺必填段');
94
+ assertExit(res, 0);
95
+ assertOut(res, '未校验(模板缺失): CHANGE.md');
96
+ assertNotOut(res, '缺必填段');
97
+ assertNotOut(res, 'BLOCKED');
70
98
  },
71
99
  },
72
100
 
73
101
  // 3: open exit BLOCKED——REQUIREMENT.md 缺验收段(且无 Given 豁免)
102
+ // 判据面是模板派生的段名表,故夹具带 REQUIREMENT 模板:模板缺席时该判据按 C9 跳过(见第 2 例),
103
+ // 这里测的是「模板在场」的真实路径。
74
104
  {
75
105
  name: '03 open exit BLOCKED:REQUIREMENT 缺验收段',
76
106
  run: (dir) => {
107
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
108
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(Acceptance Criteria)\n');
77
109
  const st = baseState('open');
78
110
  st.evidence.open = { summary: 'intake complete' };
79
111
  writeState(dir, st);
@@ -102,9 +134,11 @@ export const ENTRIES = [
102
134
  },
103
135
 
104
136
  // 5: design exit BLOCKED——缺 ## 决策清单 段
137
+ // 同第 3 例:判据面是模板派生的段名表,夹具带 DESIGN 模板(模板缺席时该判据按 C9 跳过)。
105
138
  {
106
139
  name: '05 design exit BLOCKED:缺决策清单',
107
140
  run: (dir) => {
141
+ writeFile(dir, 'flow-kit/templates/DESIGN.md', '# DESIGN 模板\n\n## 0. 技术栈选型\n## 1. 技术决策清单\n');
108
142
  const st = baseState('design');
109
143
  st.evidence.design = { summary: 'design done' };
110
144
  writeState(dir, st);
@@ -116,12 +150,40 @@ export const ENTRIES = [
116
150
  },
117
151
 
118
152
  // 6: plan exit 通过(task 块 + verify 字段)
153
+ // 结构预检在 plan 节点的覆盖:七字段分支只在 plan 生效,缺字段时预检即拦且只读,字段齐时通过。
154
+ // 七字段门禁的阻断分支只对新 change 生效(旧 change 渐进 WARN),故预检这一段用新 change 夹具。
119
155
  {
120
156
  name: '06 plan exit 通过(task 块 + verify)',
121
157
  run: (dir) => {
122
158
  const st = baseState('plan');
123
159
  st.evidence.plan = { summary: 'plan done' };
124
160
  writeState(dir, st);
161
+ const newChangeState = { ...baseState('plan'), newChange: true, enteredNodes: ['plan'] };
162
+ newChangeState.evidence.plan = { summary: 'plan done' };
163
+ writeState(dir, newChangeState);
164
+ // ① 缺 write_files → 预检 BLOCKED,且 state 字节零改写
165
+ const missingFieldTask =
166
+ '<task id="T01" status="pending"><name>任务一</name><read_files>src/*</read_files>'
167
+ + '<action>实现 T01</action><verify>node --check src/t1.mjs</verify><done>AC-1</done>'
168
+ + '<depends_on></depends_on></task>\n';
169
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + missingFieldTask);
170
+ const missingBytes = readStateBytes(dir);
171
+ const missingPre = runGuard(['exit', 'plan', '--preflight'], dir);
172
+ assertExit(missingPre, 1);
173
+ assertOut(missingPre, 'BLOCKED');
174
+ assertOut(missingPre, '缺 7 字段');
175
+ assertOut(missingPre, '缺 write_files');
176
+ assertStateBytesUnchanged(dir, missingBytes, '预检的七字段门禁同样只读:不得写 state');
177
+ // ② 七字段齐 → 预检通过(只读面不越权放行推进,完整 exit 仍由原夹具证明)
178
+ const completeTask =
179
+ '<task id="T01" status="pending"><name>任务一</name><read_files>src/*</read_files>'
180
+ + '<write_files>src/t1.mjs</write_files><action>实现 T01</action>'
181
+ + '<verify>node --check src/t1.mjs</verify><done>AC-1</done><depends_on></depends_on></task>\n';
182
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + completeTask);
183
+ const completePre = runGuard(['exit', 'plan', '--preflight'], dir);
184
+ assertExit(completePre, 0);
185
+ assertOut(completePre, 'ALL CHECKS PASSED');
186
+ writeState(dir, st);
125
187
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + TASK_DONE);
126
188
  const res = runGuard(['exit', 'plan'], dir);
127
189
  assertExit(res, 0);
@@ -146,22 +208,41 @@ export const ENTRIES = [
146
208
 
147
209
  // 8: execute exit 通过(enter 记录 taskHash + SUMMARY 六段 + 6 维实质 + 自检方法 + handoff 齐 + TASK 全 done)
148
210
  {
149
- name: '08 execute exit 通过(enter 后未改 TASK,签名匹配)',
211
+ name: '08 execute exit 通过(enter 后未改 TASK,签名匹配)+ 未 exit 时 status/next 共用节点视图(含 coordinatorMode 同源与协调者行)',
150
212
  run: (dir) => {
151
213
  const st = baseState('execute');
152
214
  st.evidence.execute = { summary: 'executed' };
153
215
  writeState(dir, st);
154
216
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + TASK_DONE);
155
217
  // enter 时脚本自动记录 taskHash(写回 state)
156
- assertExit(runGuard(['entry', 'execute'], dir), 0);
218
+ const entryView = runGuard(['entry', 'execute'], dir);
219
+ assertExit(entryView, 0);
220
+ // 跨输出面锚:entry 与 next 打印的是**同一句**协调者纪律(单一来源)。入口侧先独立断言
221
+ // 口径 token 与旧句零残留;与 next 的逐字相等在下方 nextView 之后比对。
222
+ const entryCoordinatorLine = entryView.output.split('\n').find((line) => line.startsWith('COORDINATOR: '));
223
+ if (!entryCoordinatorLine) {
224
+ throw new Error('entry execute 缺 COORDINATOR 行\n实际输出:\n' + entryView.output);
225
+ }
226
+ for (const token of ['按平台的身份通道委托子代理', '同一身份判据', '不要求隔离区', '「写权限」的一种实现', '共享工作区同样受支持']) {
227
+ if (!entryCoordinatorLine.includes(token)) {
228
+ throw new Error('entry execute 的 COORDINATOR 行缺现行口径 ' + token + ':' + entryCoordinatorLine);
229
+ }
230
+ }
231
+ assertNotOut(entryView, '只能通过 Agent 工具 worktree isolation 委托子代理');
157
232
  // exit 前补 SUMMARY + handoff(不碰 TASK.md)
158
233
  writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', summaryContent());
159
234
  const st2 = JSON.parse(fs.readFileSync(path.join(dir, '.flow-comet', 'flow-comet-state.json'), 'utf8'));
160
235
  st2.evidence['subagent-execute'] = { handoffResult: handoffFor(['T01']) };
161
236
  writeState(dir, st2);
237
+ // AC-2 正向锚:裸 exit(不带 --apply)是节点收尾的全链预演——跑完整门禁但不落盘,并显式
238
+ // 提示 --apply 才推进。反向对照在场景 14(--preflight 通过路径不得打印 --apply 引导):
239
+ // 两个只读面各守一侧,preflight 只跑结构子集、裸 exit 必须真跑到「可落盘」这一步。
240
+ const bareExitBytes = readStateBytes(dir);
162
241
  const res = runGuard(['exit', 'execute'], dir);
163
242
  assertExit(res, 0);
164
243
  assertOut(res, 'ALL CHECKS PASSED');
244
+ assertOut(res, 'APPLY: rerun with --apply');
245
+ assertStateBytesUnchanged(dir, bareExitBytes, '裸 exit(不带 --apply)是全链预演:门禁全过后也不得改写 state');
165
246
  // 变体:自检方法段名带括号后缀(执行者按模板标题原样书写,如 "## 自检方法(声明 brooks-review 或 builtin-quickcheck)")
166
247
  // → 段名识别放宽后通过,无"旧格式"兼容 WARN
167
248
  writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', summaryContent({
@@ -180,6 +261,615 @@ export const ENTRIES = [
180
261
  const resVariantNeg = runGuard(['exit', 'execute'], dir);
181
262
  assertExit(resVariantNeg, 1);
182
263
  assertOut(resVariantNeg, '自检方法');
264
+
265
+ // ---------- 节点视图收敛(in-place 扩展) ----------
266
+ // 构造「execute 已 entry 未 exit、产物推导已指向其后继 review」的态:此前 status 只报
267
+ // 推导节点 review、next 的进行中保护报 execute——同一事实两处说法。收敛后 status 增
268
+ // routeNode(= next 的 NODE)与 ROUTE: 三视图对账行;next 增 WHY: 停留原因与 execute
269
+ // 家族的 PREFLIGHT: 预检提示;既有 currentNode(产物推导)/ stateCurrentNode(state
270
+ // 原值)语义逐字不变,且两条命令都不写 state。
271
+ // 说明:不新增场景条目是本仓「场景数 = 受检面计数」约束下的 in-place 扩展形态(同场景 15)。
272
+ writeFile(dir, '.specs/' + CHANGE_ID + '/CHANGE.md', '# CHANGE\n');
273
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md', '# REQUIREMENT\n');
274
+ writeFile(dir, '.specs/' + CHANGE_ID + '/DESIGN.md', '# DESIGN\n');
275
+ const viewState = JSON.parse(readStateBytes(dir));
276
+ viewState.completedNodes = ['open', 'design', 'plan'];
277
+ viewState.enteredNodes = ['open', 'design', 'plan', 'execute'];
278
+ viewState.evidence = {
279
+ ...viewState.evidence,
280
+ open: { summary: 'open complete' },
281
+ design: { summary: 'design complete' },
282
+ plan: { summary: 'plan complete' },
283
+ };
284
+ writeState(dir, viewState);
285
+ const viewBytes = readStateBytes(dir);
286
+ const statusView = runState(['status'], dir);
287
+ assertExit(statusView, 0);
288
+ const statusRouteNode = (statusView.output.match(/"routeNode":\s*"([^"]+)"/) ?? [])[1];
289
+ if (statusRouteNode !== 'execute') {
290
+ throw new Error('status.routeNode 应为进行中节点 execute(= next 的 NODE),实际: '
291
+ + JSON.stringify(statusRouteNode) + '\n实际输出:\n' + statusView.output);
292
+ }
293
+ assertOut(statusView, '"currentNode": "review"'); // 产物推导语义不变(SUMMARY 已齐 → review)
294
+ assertOut(statusView, '"stateCurrentNode": "execute"'); // state 原值语义不变
295
+ // coordinatorMode 与 routeNode 同源(One predicate)——进行中态下 routeNode=execute 而
296
+ // 产物推导是 review;旧口径(按 detectedNode 计算)会在同一响应里给出 false,即两个「当前
297
+ // 节点」口径并存。断言取其在 route 视图上的取值,锁住二者不再分叉。
298
+ assertOut(statusView, '"coordinatorMode": true');
299
+ const routeLine = statusView.output.split('\n').find((line) => line.startsWith('ROUTE: '));
300
+ if (!routeLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + statusView.output);
301
+ for (const token of ['derived=review', 'state=execute', 'route=execute', '先 exit execute']) {
302
+ if (!routeLine.includes(token)) throw new Error('ROUTE: 行缺少 ' + token + ':' + routeLine);
303
+ }
304
+ assertStateBytesUnchanged(dir, viewBytes, 'status 是只读视图(ROUTE 诊断不得写 state)');
305
+ const nextView = runState(['next'], dir);
306
+ assertExit(nextView, 0);
307
+ const nextNode = (nextView.output.match(/^NODE: (.+)$/m) ?? [])[1];
308
+ if (nextNode !== statusRouteNode) {
309
+ throw new Error('status.routeNode 与 next 的 NODE 不一致(同一事实两处说法):'
310
+ + JSON.stringify(statusRouteNode) + ' vs ' + JSON.stringify(nextNode));
311
+ }
312
+ const whyLine = nextView.output.split('\n').find((line) => line.startsWith('WHY: '));
313
+ if (!whyLine) throw new Error('next 缺少 WHY: 停留原因行\n实际输出:\n' + nextView.output);
314
+ if (!whyLine.includes('已 entry 未 exit')) {
315
+ throw new Error('WHY: 行应说明进行中原因(已 entry 未 exit):' + whyLine);
316
+ }
317
+ assertOut(nextView, 'PREFLIGHT: ');
318
+ // 平台化形态:脚本路径整条加引号,命令在引号之后接 exit <节点> --preflight(裸脚本名的旧
319
+ // 形态由下文的解析断言与反向锚共同排除)。预检节点取路由视图(= NODE 行),且必须与
320
+ // 「完整 exit(不带 --apply)才是全链预演」的说明句同行——同一个 PREFLIGHT 不再指两条命令。
321
+ assertOut(nextView, 'workflow-guard.mjs" exit execute --preflight');
322
+ assertOut(nextView, '做结构预检(只跑结构性门禁,不写 state、不推进状态)');
323
+ assertOut(nextView, '完整 exit(不带 --apply)是节点收尾的全链预演');
324
+ assertNotOut(nextView, '(不带 --apply)预检——跑完整出口门禁');
325
+ assertStateBytesUnchanged(dir, viewBytes, 'next 进行中保护不得写 state(routeNode 与 NODE 同源)');
326
+
327
+ // next 的 PREFLIGHT 行必须与 handoff result 的平台化形态同源——命令从输出解析后,
328
+ // 逐字等于脚本命令单一实现的产物(同一 scriptsDir / runRoot),而不是裸脚本名。
329
+ const preflightCommand = (nextView.output.match(/PREFLIGHT: 可运行 (node .+?) 做结构预检/) ?? [])[1];
330
+ if (!preflightCommand) {
331
+ throw new Error('next 的 PREFLIGHT 行缺可解析的平台化命令(应为 node "<脚本路径>" exit <节点> --preflight):\n'
332
+ + nextView.output);
333
+ }
334
+ const expectedPreflightCommand = scriptCommand({
335
+ scriptsDir: SCRIPTS_DIR, runRoot: dir, script: 'workflow-guard.mjs', args: ['exit', 'execute', '--preflight'],
336
+ });
337
+ if (preflightCommand !== expectedPreflightCommand) {
338
+ throw new Error('next 的 PREFLIGHT 命令未走平台化单一实现:'
339
+ + JSON.stringify(preflightCommand) + '(期望 ' + JSON.stringify(expectedPreflightCommand) + ')');
340
+ }
341
+ // 反向锚:裸脚本名形态(旧输出)不得残留——它正是「照抄到非 .claude 安装会落空」的形态。
342
+ assertNotOut(nextView, 'PREFLIGHT: 可运行 workflow-guard.mjs');
343
+ // 两个输出面同形:同一节点下 handoff result 打印的同一条命令必须逐字相同(不是各写一份)。
344
+ // handoff 侧的路由视图要解析协议(与 next 同一判定),而 runHandoff 默认不注入协议副本——
345
+ // 显式传入场景协议路径(与 runState 的默认注入同源)。
346
+ const handoffPre = runHandoff(['result', 'T01', '{"greenEvidence":{"command":"node --check src/t1.mjs"},"redEvidence":{"command":"node --check src/t1.mjs"}}'], dir, {
347
+ FLOW_COMET_PROTOCOL: scenarioProtocolPath(dir),
348
+ });
349
+ assertExit(handoffPre, 0);
350
+ const handoffPreflightCommand = (handoffPre.output.match(/PREFLIGHT: SUMMARY 结构尚未校验——可运行 (node .+?) 做结构预检/) ?? [])[1];
351
+ if (!handoffPreflightCommand) {
352
+ throw new Error('handoff result 的 PREFLIGHT 行缺可解析的平台化命令:\n' + handoffPre.output);
353
+ }
354
+ if (handoffPreflightCommand !== preflightCommand) {
355
+ throw new Error('两处 PREFLIGHT 命令形态不一致(next vs handoff result):'
356
+ + JSON.stringify(preflightCommand) + ' vs ' + JSON.stringify(handoffPreflightCommand));
357
+ }
358
+
359
+ // COORDINATOR 行按现行架构口径——三平台按身份通道委托、worktree 只是「写权限」的
360
+ // 一种实现、不要求隔离区。旧句(只能 worktree isolation)写回即红。
361
+ assertOut(nextView, 'COORDINATOR: ');
362
+ assertOut(nextView, '按平台的身份通道委托子代理');
363
+ assertOut(nextView, '同一身份判据');
364
+ assertOut(nextView, '不要求隔离区');
365
+ assertOut(nextView, '「写权限」的一种实现');
366
+ assertOut(nextView, '共享工作区同样受支持');
367
+ assertNotOut(nextView, '只能通过 Agent 工具 worktree isolation 委托子代理');
368
+ // 跨输出面:entry 与 next 的 COORDINATOR 行必须逐字相同(同一常量/同一措辞)——写回任一处
369
+ // 的旧句都会同时破坏 token 断言与这条逐字相等锚。
370
+ const nextCoordinatorLine = nextView.output.split('\n').find((line) => line.startsWith('COORDINATOR: '));
371
+ if (!nextCoordinatorLine) {
372
+ throw new Error('next 缺 COORDINATOR 行\n实际输出:\n' + nextView.output);
373
+ }
374
+ if (entryCoordinatorLine !== nextCoordinatorLine) {
375
+ throw new Error('entry 与 next 的 COORDINATOR 行不一致(同一纪律两个输出面必须逐字相同):'
376
+ + '\nentry: ' + entryCoordinatorLine + '\nnext : ' + nextCoordinatorLine);
377
+ }
378
+ // 常量落点与取用面(单一来源的静态锁):协调者禁令是**一个知识**,实现只许一处、取用面只许
379
+ // 具名 import。两处各写一份在措辞演进时必然分叉,而
380
+ // 上面的运行期相等锚只在两处恰好同值时成立——**落点错了它看不见**(两份副本可以逐字相同)。
381
+ // 故另锚这一层:① 定义面唯一且落在中立模块(状态命令族与门禁族都只是取用方);② 消费方不得
382
+ // 自带第二份定义、不得绕过单源取用。反向边(状态命令族 → 门禁族)随迁位消失——套件里直接
383
+ // 断言它没有回来:状态命令族的**代码层**不得再出现门禁模块的名字。
384
+ const engineTexts = engineScriptTexts();
385
+ const singleSourceProblems = singleSourceImportProblems({
386
+ symbol: 'COORDINATOR_NOTICE',
387
+ sourceRel: 'lib/state-explain.mjs',
388
+ texts: engineTexts,
389
+ });
390
+ if (singleSourceProblems.length > 0) {
391
+ throw new Error('协调者禁令的单一来源被破坏(' + singleSourceProblems.join('; ') + ')');
392
+ }
393
+ const flowCode = engineCodeText(engineTexts.get('lib/state-commands-flow.mjs') ?? '');
394
+ if (flowCode.includes('guard-gates')) {
395
+ throw new Error('状态命令族不得依赖门禁族(反向边):lib/state-commands-flow.mjs 的代码层仍引用 guard-gates');
396
+ }
397
+ // 声明工件的**枚举**单一来源锁(与上一条同族:守的事都落在「落点」这一层,不靠运行期相等):
398
+ // 枚举只许在 lib/guard-routing.mjs 的 declaredRequiredArtifacts 一处,出口产物门禁与结构预检
399
+ // 都只消费它。运行期断言守不住这件事——两份枚举可以逐字相同地并存,下次演进才分叉;故按
400
+ // 代码层形态对账(注释里提到 outputSchemas / artifacts 是说明,不是实现)。判据形态 = 同一
401
+ // 模块的代码层既遍历 outputSchemas、又迭代 .artifacts(两侧各自遍历正是被收掉的第二份实现)。
402
+ const declaredArtifactEnumerationSites = [...engineTexts.entries()]
403
+ .filter(([, text]) => {
404
+ const code = engineCodeText(text);
405
+ return /\boutputSchemas\b/u.test(code) && /\bof\s+[\w$.?]+\.artifacts\b/u.test(code);
406
+ })
407
+ .map(([rel]) => rel)
408
+ .sort();
409
+ const registeredEnumerationSites = DECLARED_ARTIFACT_ENUMERATION_SITES.map((site) => site.file).sort();
410
+ const unregisteredEnumerationSites = declaredArtifactEnumerationSites
411
+ .filter((rel) => !registeredEnumerationSites.includes(rel));
412
+ const vanishedEnumerationSites = registeredEnumerationSites
413
+ .filter((rel) => !declaredArtifactEnumerationSites.includes(rel));
414
+ if (unregisteredEnumerationSites.length > 0 || vanishedEnumerationSites.length > 0) {
415
+ throw new Error('声明工件的枚举面不再是单一来源(枚举只许在 lib/guard-routing.mjs 的 '
416
+ + 'declaredRequiredArtifacts 一处,出口与预检都只消费它):'
417
+ + (unregisteredEnumerationSites.length > 0
418
+ ? '\n未登记的枚举落点: ' + unregisteredEnumerationSites.join('、')
419
+ + '——若它确实是另一条机制(不是「声明工件的存在性」判据),在套件的 '
420
+ + 'DECLARED_ARTIFACT_ENUMERATION_SITES 里登记并写明理由;否则改从单一来源取用'
421
+ : '')
422
+ + (vanishedEnumerationSites.length > 0
423
+ ? '\n登记了却已不再枚举: ' + vanishedEnumerationSites.join('、')
424
+ + '——登记面与实际枚举面对不上:该文件的枚举已消失或改了形态,'
425
+ + '要么同步登记面,要么这条锁已失去判别力'
426
+ : ''));
427
+ }
428
+
429
+ // ---------- record 的节点视图同源(in-place 扩展) ----------
430
+ // 缺陷形态:runRecord 写证据后用 determineNode(产物推导)打印 NEXT/NODE,未走共享视图——
431
+ // 就在上面这个「currentNode=execute 已 entry 未 exit、产物推导已指向 review」的态里,
432
+ // record execute 报 review,而 next 报 execute、status.routeNode 报 execute:每完成一个节点
433
+ // 都会看到与两条命令相反的「下一节点」,正是本 change 要消灭的同一事实两处说法(L-067)。
434
+ // record 是**第三个**节点视图输出面,故判据取「三面同一节点」而不是各自断言节点名。
435
+ writeFile(dir, '.specs/' + CHANGE_ID + '/.skill-loads/execute-flow-comet-execute.json',
436
+ JSON.stringify({
437
+ node: 'execute',
438
+ skill: 'flow-comet-execute',
439
+ protocol: '3-execute.md',
440
+ templates: ['SUMMARY'],
441
+ at: '2026-08-01T00:00:00.000Z',
442
+ }, null, 2) + '\n');
443
+ const recordView = runState(['record', 'execute', '{"summary":"execute recorded while in progress"}'], dir);
444
+ assertExit(recordView, 0);
445
+ const recordNode = (recordView.output.match(/^NODE: (.+)$/m) ?? [])[1];
446
+ if (recordNode !== 'execute') {
447
+ throw new Error('record 处于进行中态:NODE 应为路由视图 execute(不是产物推导的 review),实际: '
448
+ + JSON.stringify(recordNode) + '\nrecord 输出:\n' + recordView.output);
449
+ }
450
+ // 正常态不受影响:非边界态的 record 照常给出节点与 NEXT: auto,边界态那句不得漏到这里。
451
+ assertOut(recordView, 'NEXT: auto');
452
+ assertNotOut(recordView, 'NEXT: blocked');
453
+ if (recordNode !== nextNode || recordNode !== statusRouteNode) {
454
+ throw new Error('record 的 NODE 与 next / status.routeNode 不同源(同一事实三处说法):'
455
+ + JSON.stringify({ record: recordNode, next: nextNode, statusRouteNode })
456
+ + '\nrecord 输出:\n' + recordView.output + '\nnext 输出:\n' + nextView.output);
457
+ }
458
+ // record 也会经 printNext 打出 COORDINATOR 行(execute 家族)——它是同一常量的第三个输出面,
459
+ // 一并锁进「逐字相等」:任一处另写一份措辞都会在这里红。
460
+ const recordCoordinatorLine = recordView.output.split('\n').find((line) => line.startsWith('COORDINATOR: '));
461
+ if (recordCoordinatorLine !== nextCoordinatorLine) {
462
+ throw new Error('record 的 COORDINATOR 行与 entry / next 不一致(同一常量、同一 printNext 实现):'
463
+ + '\nnext : ' + nextCoordinatorLine + '\nrecord: ' + recordCoordinatorLine);
464
+ }
465
+
466
+ // ---------- record 载荷必须是对象(in-place 扩展) ----------
467
+ // 形状校验只判「对象各字段的类型」(state-schema 的 evidencePayloadProblems 对非对象载荷
468
+ // 直接放行),于是载荷本身不是对象时旧实现两条路都错:null 一路走到读 `parsed.completedChecks`
469
+ // 时抛 TypeError——报文是堆栈,既不说哪一步错了、也不说载荷该长什么样;数组/字符串/数字则被
470
+ // 静默改写成 { summary: String(...) },替调用方编了一份它没说过的载荷。两类都在入口拦下:
471
+ // 非零退出、报文点名当前类型、state 字节零改写。判定放在 runRecord 入口而不是共享形状表——
472
+ // 它判的是「载荷本身是不是对象」,与「对象各字段的类型」是两件事,各自守自己边界内的事实。
473
+ const payloadBytes = readStateBytes(dir);
474
+ for (const [label, payload, typeName] of [
475
+ ['null', 'null', 'null'],
476
+ ['数组', '[1,2]', 'array'],
477
+ ['字符串', '"just a summary string"', 'string'],
478
+ ['数字', '42', 'number'],
479
+ ]) {
480
+ const badPayload = runState(['record', 'execute', payload], dir);
481
+ assertExit(badPayload, 1);
482
+ assertOut(badPayload, 'record 载荷必须是对象(当前是 ' + typeName + ')');
483
+ if (badPayload.output.includes('TypeError')) {
484
+ throw new Error(label + ' 载荷应被可读报文拒绝,不得抛 TypeError:\n' + badPayload.output);
485
+ }
486
+ assertStateBytesUnchanged(dir, payloadBytes, label + ' 载荷在写入前被拒绝(state 字节零改写)');
487
+ }
488
+
489
+ // ---------- Fix 归位态的节点视图(in-place 扩展) ----------
490
+ // 缺陷复现:currentNode=review、REVIEW.md 在场、TASK 有 pending 修复任务时,next 的
491
+ // FIX-BATCH 分支先于共享视图返回并打印 NODE: execute,status 只走共享视图——它按「进行中
492
+ // 保护」报 routeNode=review,ROUTE: 行还叫人「先 exit review」,真去 exit 会被
493
+ // 「存在未归位/未跑出口的 Fix 批次」拦下。修复后 status 只读消费同一归位决策
494
+ // (resolveFixRollbackDecision 是纯读:不写盘、不计轮次),routeNode 与指引都指向归位目标。
495
+ const fixTaskPath = '.specs/' + CHANGE_ID + '/TASK.md';
496
+ const fixState = {
497
+ activeChange: CHANGE_ID,
498
+ currentNode: 'review',
499
+ completedNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute'],
500
+ enteredNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute', 'review'],
501
+ evidence: {
502
+ open: { summary: 'open complete' },
503
+ design: { summary: 'design complete' },
504
+ plan: { summary: 'plan complete' },
505
+ execute: { summary: 'first pass executed' },
506
+ review: { summary: 'review in progress' },
507
+ },
508
+ verifyFailures: 0,
509
+ executionMode: 'subagent',
510
+ directOverride: false,
511
+ newChange: true,
512
+ };
513
+ writeFile(dir, fixTaskPath, fixBatchTaskText('pending'));
514
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REVIEW.md', '# REVIEW\n\n## 结论\n\n修复任务已追加,待归位 execute 跑完其出口。\n');
515
+ writeState(dir, fixState);
516
+ const fixBytes = readStateBytes(dir);
517
+ const fixStatus = runState(['status'], dir);
518
+ assertExit(fixStatus, 0);
519
+ assertStateBytesUnchanged(dir, fixBytes, 'Fix 归位态下 status 是只读视图(归位决策只读消费,不写盘)');
520
+ const fixRouteNode = (fixStatus.output.match(/"routeNode":\s*"([^"]+)"/) ?? [])[1];
521
+ const fixRouteLine = fixStatus.output.split('\n').find((line) => line.startsWith('ROUTE: '));
522
+ if (!fixRouteLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + fixStatus.output);
523
+ const fixNext = runState(['next'], dir);
524
+ assertExit(fixNext, 0);
525
+ assertOut(fixNext, 'FIX-BATCH: 归位 execute(源节点 review)');
526
+ const fixNextNode = (fixNext.output.match(/^NODE: (.+)$/m) ?? [])[1];
527
+ if (fixNextNode !== 'execute') {
528
+ throw new Error('Fix 归位态下 next 应打印 NODE: execute,实际: ' + JSON.stringify(fixNextNode)
529
+ + '\n实际输出:\n' + fixNext.output);
530
+ }
531
+ if (fixRouteNode !== fixNextNode) {
532
+ throw new Error('Fix 归位态下 status.routeNode 与 next 的 NODE 不一致(status 把执行者指向了会被 FIX-BATCH 拦下的节点):'
533
+ + JSON.stringify(fixRouteNode) + ' vs ' + JSON.stringify(fixNextNode)
534
+ + '\nstatus 输出:\n' + fixStatus.output + '\nnext 输出:\n' + fixNext.output);
535
+ }
536
+ if (fixRouteLine.includes('先 exit review')) {
537
+ throw new Error('Fix 归位态下 ROUTE: 不得让用户先去 exit 会被 FIX-BATCH 拦下的源节点:' + fixRouteLine);
538
+ }
539
+ for (const token of ['Fix 批次', '归位 execute']) {
540
+ if (!fixRouteLine.includes(token)) throw new Error('ROUTE: 行缺少归位指引 ' + token + ':' + fixRouteLine);
541
+ }
542
+ // 同源不只在 NODE 上:next 的 FIX-BATCH 分支也要有一行 WHY(与共享视图同一段文案实现),
543
+ // 且该行点名的节点与 status.routeNode 相同——否则两边节点相同、解释却各自一份。
544
+ const fixWhyLine = fixNext.output.split('\n').find((line) => line.startsWith('WHY: '));
545
+ if (!fixWhyLine) {
546
+ throw new Error('Fix 归位态下 next 缺少 WHY: 解释行(应与共享视图同源)\n实际输出:\n' + fixNext.output);
547
+ }
548
+ if (!fixWhyLine.includes(fixRouteNode)) {
549
+ throw new Error('WHY: 行点名的节点应与 status.routeNode 一致(' + JSON.stringify(fixRouteNode) + '):' + fixWhyLine);
550
+ }
551
+ if (!fixWhyLine.includes('Fix 批次')) {
552
+ throw new Error('WHY: 行应说明这是 Fix 批次归位(而不是产物推导/进行中保护):' + fixWhyLine);
553
+ }
554
+ // 归位写盘仍只属于 next 的 FIX-BATCH 分支(既有契约:受控归位改写 currentNode,见场景 253a);
555
+ // 视图路径本身不得写 state——归位后重跑 next 走共享视图,字节零变化。
556
+ const stateAfterRollback = JSON.parse(readStateBytes(dir));
557
+ if (stateAfterRollback.currentNode !== 'execute') {
558
+ throw new Error('Fix 归位态下 next 应把 currentNode 归位 execute,实际 '
559
+ + JSON.stringify(stateAfterRollback.currentNode));
560
+ }
561
+ const bytesAfterRollback = readStateBytes(dir);
562
+ const nextAfterRollback = runState(['next'], dir);
563
+ assertExit(nextAfterRollback, 0);
564
+ assertOut(nextAfterRollback, 'NODE: execute');
565
+ assertStateBytesUnchanged(dir, bytesAfterRollback, '归位后的共享视图路径不得改写 state');
566
+
567
+ // handoff result 侧同源(缺陷复现):Fix 归位态下 state.currentNode=review,取原值会打印
568
+ // exit review——该节点此刻正被 Fix 批次门禁拦着;路由视图是 execute。两处提示(next /
569
+ // handoff result)必须同一节点,且都带结构预检与全链预演两句。
570
+ // T02 的 result 必须对上一条 request(缺 request 的 result 在写盘前被拦)——本段只验证
571
+ // PREFLIGHT 节点同源,故补一条最小 request(noCommit:零提交请求,不引入提交子集校验噪声),
572
+ // 归位态其余字段原样保留。
573
+ writeState(dir, {
574
+ ...fixState,
575
+ evidence: {
576
+ ...fixState.evidence,
577
+ 'subagent-execute': { handoffRequests: { T02: { description: 'fix handoff', noCommit: true } } },
578
+ },
579
+ });
580
+ const fixHandoff = runHandoff(['result', 'T02',
581
+ '{"greenEvidence":{"command":"node --check src/t2.mjs"},"redEvidence":{"command":"node --check src/t2.mjs"}}'], dir, {
582
+ FLOW_COMET_PROTOCOL: scenarioProtocolPath(dir),
583
+ });
584
+ assertExit(fixHandoff, 0);
585
+ const fixHandoffCommand = (fixHandoff.output.match(/PREFLIGHT: SUMMARY 结构尚未校验——可运行 (node .+?) 做结构预检/) ?? [])[1];
586
+ if (!fixHandoffCommand) {
587
+ throw new Error('Fix 归位态下 handoff result 的 PREFLIGHT 行缺可解析命令:\n' + fixHandoff.output);
588
+ }
589
+ const expectedFixHandoffCommand = scriptCommand({
590
+ scriptsDir: SCRIPTS_DIR, runRoot: dir, script: 'workflow-guard.mjs', args: ['exit', 'execute', '--preflight'],
591
+ });
592
+ if (fixHandoffCommand !== expectedFixHandoffCommand) {
593
+ throw new Error('Fix 归位态下 handoff result 的预检节点应取路由视图 execute(不是 state.currentNode 原值 review):'
594
+ + JSON.stringify(fixHandoffCommand) + '(期望 ' + JSON.stringify(expectedFixHandoffCommand) + ')');
595
+ }
596
+
597
+ // 保护谓词的路由序号条件(反过度保护):verify 驻留但 REVIEW.md 缺失 → 产物推导回退
598
+ // review(derived 在 currentNode 之前,不是路由后继),进行中保护不得把路由钉在 verify 上;
599
+ // status 与 next 都必须报产物推导的 review,next 的漂移校正随之落盘。
600
+ writeFile(dir, fixTaskPath, fixBatchTaskText('done'));
601
+ fs.rmSync(path.join(dir, '.specs/' + CHANGE_ID, 'REVIEW.md'));
602
+ writeState(dir, {
603
+ ...fixState,
604
+ currentNode: 'verify',
605
+ completedNodes: [...fixState.completedNodes, 'review'],
606
+ enteredNodes: [...fixState.enteredNodes, 'verify'],
607
+ evidence: { ...fixState.evidence, verify: { summary: 'verify in progress' } },
608
+ });
609
+ const driftStatus = runState(['status'], dir);
610
+ assertExit(driftStatus, 0);
611
+ const driftRouteNode = (driftStatus.output.match(/"routeNode":\s*"([^"]+)"/) ?? [])[1];
612
+ if (driftRouteNode !== 'review') {
613
+ throw new Error('derived 不在 currentNode 之后时不得套用进行中保护(routeNode 应为产物推导的 review),实际: '
614
+ + JSON.stringify(driftRouteNode) + '\nstatus 输出:\n' + driftStatus.output);
615
+ }
616
+ // 另一侧取值:非进行中态 routeNode 不是 execute 家族 → coordinatorMode=false
617
+ // (与「同源」一起锁住取值域,不能只在一个方向上成立)。
618
+ assertOut(driftStatus, '"coordinatorMode": false');
619
+ const driftNext = runState(['next'], dir);
620
+ assertExit(driftNext, 0);
621
+ assertOut(driftNext, 'NODE: review');
622
+ if (JSON.parse(readStateBytes(dir)).currentNode !== 'review') {
623
+ throw new Error('非后继形态应被产物权威校正回 review,实际 state.currentNode: '
624
+ + JSON.stringify(JSON.parse(readStateBytes(dir)).currentNode) + '\nnext 输出:\n' + driftNext.output);
625
+ }
626
+
627
+ // 序号条件的边界(反过度收窄):execute 家族是同一个多趟**循环**,execute ⇄ subagent-execute
628
+ // 在 route 里的一前一后不是先后关系。波次收齐后只剩串行 pending 时(派生回到 execute 的
629
+ // 趟间回边),保护必须继续生效——否则 next 会把 currentNode 推回 execute,波次的出口再也
630
+ // 无法重跑(L-060 型死结)。
631
+ writeFile(dir, fixTaskPath, fixBatchTaskText('pending'));
632
+ writeState(dir, {
633
+ ...fixState,
634
+ currentNode: 'subagent-execute',
635
+ completedNodes: ['open', 'design', 'plan', 'execute'],
636
+ enteredNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute'],
637
+ evidence: { ...fixState.evidence, 'subagent-execute': { summary: 'wave delegated' } },
638
+ });
639
+ const waveBytes = readStateBytes(dir);
640
+ const waveStatus = runState(['status'], dir);
641
+ assertExit(waveStatus, 0);
642
+ const waveRouteNode = (waveStatus.output.match(/"routeNode":\s*"([^"]+)"/) ?? [])[1];
643
+ if (waveRouteNode !== 'subagent-execute') {
644
+ throw new Error('执行家族内的趟间回边不得套用路由序号条件(routeNode 应为进行中的 subagent-execute),实际: '
645
+ + JSON.stringify(waveRouteNode) + '\nstatus 输出:\n' + waveStatus.output);
646
+ }
647
+ const waveNext = runState(['next'], dir);
648
+ assertExit(waveNext, 0);
649
+ assertOut(waveNext, 'NODE: subagent-execute');
650
+ assertStateBytesUnchanged(dir, waveBytes, '执行家族回边仍属进行中保护:next 不得把 currentNode 推回 execute');
651
+
652
+ // 序号条件的第三枚构造(正向守护,in-place 扩展):derived 落在 currentNode **之前不止一步**。
653
+ // 既有两枚反向构造里 derived 都是 currentNode 的直接前驱(verify→review 回退 / 执行家族的趟间
654
+ // 回边),故「只豁免直接前驱、更早的一律按进行中保护」这种收窄它们照样全绿。此处让派生的
655
+ // execute 与驻留的 review 隔着一整个执行家族,且保护链条上的其余前提**全部成立**——currentNode
656
+ // 已 entry 未 exit、路由后继推导(把 currentNode 视为已完成再求值)恰等于 derivedNode——只有
657
+ // 序号条件为假:路由必须跟随产物推导回到 execute,不得被保护钉在更晚的 review 上。
658
+ writeFile(dir, fixTaskPath, fixBatchTaskText('done'));
659
+ fs.rmSync(path.join(dir, '.specs/' + CHANGE_ID, 'T01-SUMMARY.md'), { force: true });
660
+ writeState(dir, {
661
+ activeChange: CHANGE_ID,
662
+ currentNode: 'review',
663
+ completedNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute'],
664
+ enteredNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute', 'review'],
665
+ evidence: {
666
+ open: { summary: 'open complete' },
667
+ design: { summary: 'design complete' },
668
+ plan: { summary: 'plan complete' },
669
+ execute: { summary: 'executed' },
670
+ review: { summary: 'review in progress — SUMMARY 在此后被移除' },
671
+ },
672
+ verifyFailures: 0,
673
+ executionMode: 'subagent',
674
+ directOverride: false,
675
+ newChange: true,
676
+ });
677
+ const behindBytes = readStateBytes(dir);
678
+ const behindStatus = runState(['status'], dir);
679
+ assertExit(behindStatus, 0);
680
+ assertOut(behindStatus, '"currentNode": "execute"'); // 产物推导:SUMMARY 缺席 → 回到 execute
681
+ assertOut(behindStatus, '"stateCurrentNode": "review"'); // state 原值语义不变
682
+ assertOut(behindStatus, '"routeNode": "execute"'); // 路由视图跟随产物推导
683
+ assertNotOut(behindStatus, '"routeNode": "review"'); // 不得被进行中保护钉在更晚的 currentNode
684
+ const behindRouteLine = behindStatus.output.split('\n').find((line) => line.startsWith('ROUTE: '));
685
+ if (!behindRouteLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + behindStatus.output);
686
+ for (const token of ['derived=execute', 'state=review', 'route=execute']) {
687
+ if (!behindRouteLine.includes(token)) {
688
+ throw new Error('derived 早于 currentNode 时 ROUTE: 行缺少 ' + token + ':' + behindRouteLine);
689
+ }
690
+ }
691
+ if (behindRouteLine.includes('进行中')) {
692
+ throw new Error('derived 早于 currentNode 时 ROUTE: 行不得声明进行中(保护不成立):' + behindRouteLine);
693
+ }
694
+ assertStateBytesUnchanged(dir, behindBytes, 'status 是只读视图(早于 currentNode 的 derived 不改写 state)');
695
+ const behindNext = runState(['next'], dir);
696
+ assertExit(behindNext, 0);
697
+ assertOut(behindNext, 'NODE: execute');
698
+ const behindWhy = behindNext.output.split('\n').find((line) => line.startsWith('WHY: '));
699
+ if (!behindWhy) throw new Error('next 缺少 WHY: 解释行\n实际输出:\n' + behindNext.output);
700
+ if (!behindWhy.includes('产物推导')) {
701
+ throw new Error('早于 currentNode 的 derived 应报产物推导(不是进行中保护):' + behindWhy);
702
+ }
703
+ if (behindWhy.includes('进行中保护')) {
704
+ throw new Error('早于 currentNode 的 derived 不得套用进行中保护:' + behindWhy);
705
+ }
706
+ // 非进行中 → 漂移校正照常落盘:state.currentNode 回到产物推导的 execute
707
+ if (JSON.parse(readStateBytes(dir)).currentNode !== 'execute') {
708
+ throw new Error('derived 早于 currentNode 时应被产物权威校正回 execute,实际 state.currentNode: '
709
+ + JSON.stringify(JSON.parse(readStateBytes(dir)).currentNode) + '\nnext 输出:\n' + behindNext.output);
710
+ }
711
+
712
+ // ---------- 边界态:next 会 BLOCKED 时 status 不得给节点(in-place 扩展) ----------
713
+ // 缺陷复现:next 有两条**不打印 NODE**、直接 BLOCKED 的分支(Fix 受控归位第 4 轮无授权 /
714
+ // 单趟零进展),status 却照常经 resolveNodeView 给一个 routeNode——执行者按 status 行动必然
715
+ // 撞 BLOCKED,「同一状态同一答案」在这两种态上不成立。修复后 status 输出 routeNode=null 且
716
+ // ROUTE: 行写明「next 将 BLOCKED:<原因>」,与 next 的实际行为一致;判定是 state 副本上的
717
+ // 只读预演(真实字节零改写、不计轮次)。
718
+ writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', summaryContent());
719
+ writeFile(dir, fixTaskPath, fixBatchTaskText('pending'));
720
+ writeState(dir, { ...fixState, fixRoundsByChange: { [CHANGE_ID]: 3 } });
721
+ const blockedFixBytes = readStateBytes(dir);
722
+ const blockedFixStatus = runState(['status'], dir);
723
+ assertExit(blockedFixStatus, 0);
724
+ if (!/"routeNode":\s*null/.test(blockedFixStatus.output)) {
725
+ throw new Error('Fix 归位第 4 轮无授权态:next 会 BLOCKED 且不打印 NODE,status.routeNode 必须是 null,实际输出:\n'
726
+ + blockedFixStatus.output);
727
+ }
728
+ const blockedFixRouteLine = blockedFixStatus.output.split('\n').find((line) => line.startsWith('ROUTE: '));
729
+ if (!blockedFixRouteLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + blockedFixStatus.output);
730
+ for (const token of ['route=null', 'next 将 BLOCKED', 'Fix 批次受控归位已达 3 轮上限', '先按恢复指引处理']) {
731
+ if (!blockedFixRouteLine.includes(token)) {
732
+ throw new Error('边界态 ROUTE: 行缺少 ' + token + ':' + blockedFixRouteLine);
733
+ }
734
+ }
735
+ assertStateBytesUnchanged(dir, blockedFixBytes, 'status 的「next 将 BLOCKED」判定是只读预演(不得写 state)');
736
+ const blockedFixRounds = JSON.parse(readStateBytes(dir)).fixRoundsByChange?.[CHANGE_ID];
737
+ if (blockedFixRounds !== 3) {
738
+ throw new Error('status 不得计轮次(Fix 计数应保持 3),实际 ' + JSON.stringify(blockedFixRounds));
739
+ }
740
+ const blockedFixNext = runState(['next'], dir);
741
+ assertExit(blockedFixNext, 1);
742
+ assertOut(blockedFixNext, 'BLOCKED: Fix 批次受控归位已达 3 轮上限');
743
+ if (/^NODE: /m.test(blockedFixNext.output)) {
744
+ throw new Error('Fix 归位第 4 轮无授权态:next 必须 BLOCKED、不得打印 NODE\n实际输出:\n' + blockedFixNext.output);
745
+ }
746
+ assertStateBytesUnchanged(dir, blockedFixBytes, 'next 的 BLOCK 分支在任何写盘之前(state 字节零改写)');
747
+
748
+ // record 是这条事实的**第四个说法**(in-place 扩展):边界态下它的尾巴仍按旧路径打印
749
+ // NEXT: done——同一 state 上 next 已 BLOCKED、status.routeNode 已是 null,record 却说
750
+ // 「没有下一节点了」。record 走共享节点视图,边界态命中时同样不得给出下一节点(next 此刻
751
+ // 不打印 NODE),改用与 ROUTE: 行同源的一句;判定本身零写盘——轮次与 currentNode 不动,
752
+ // record 的写面仍只是它自己的证据(录证据是它的职责,不是判定副作用)。
753
+ const recordBlockedFix = runState(['record', 'execute', '{"summary":"execute recorded while the fix batch is blocked"}'], dir);
754
+ assertExit(recordBlockedFix, 0);
755
+ assertOut(recordBlockedFix, 'EVIDENCE: execute');
756
+ assertNotOut(recordBlockedFix, 'NEXT: done');
757
+ if (/^NODE: /m.test(recordBlockedFix.output)) {
758
+ throw new Error('边界态下 record 不得给出下一节点(next 此刻不打印 NODE)\n实际输出:\n' + recordBlockedFix.output);
759
+ }
760
+ assertOut(recordBlockedFix, 'NEXT: blocked(Fix 批次受控归位已达 3 轮上限');
761
+ assertOut(recordBlockedFix, '先按恢复指引处理');
762
+ const recordBlockedFixState = JSON.parse(readStateBytes(dir));
763
+ if (recordBlockedFixState.fixRoundsByChange?.[CHANGE_ID] !== 3) {
764
+ throw new Error('record 的边界态判定不得计轮次(Fix 计数应保持 3),实际: '
765
+ + JSON.stringify(recordBlockedFixState.fixRoundsByChange) + '\nrecord 输出:\n' + recordBlockedFix.output);
766
+ }
767
+ if (recordBlockedFixState.currentNode !== 'review') {
768
+ throw new Error('record 的边界态判定不得改写 currentNode(应保持 review),实际: '
769
+ + JSON.stringify(recordBlockedFixState.currentNode));
770
+ }
771
+
772
+ // 零进展态(孤儿并行任务:depends_on 指向不存在的任务 id)——同样「next BLOCKED / status 无节点」
773
+ writeFile(dir, fixTaskPath, '# TASK\n\n'
774
+ + '<task id="P01" parallel="true" status="pending"><action>实现 P01</action><write_files>src/p01.mjs</write_files><verify>node --check src/p01.mjs</verify><depends_on>NOPE</depends_on></task>\n');
775
+ writeState(dir, {
776
+ ...fixState,
777
+ currentNode: 'execute',
778
+ completedNodes: ['open', 'design', 'plan'],
779
+ enteredNodes: ['open', 'design', 'plan', 'execute'],
780
+ evidence: {
781
+ open: { summary: 'open complete' },
782
+ design: { summary: 'design complete' },
783
+ plan: { summary: 'plan complete' },
784
+ execute: { summary: 'execute in progress' },
785
+ },
786
+ });
787
+ const zeroProgressBytes = readStateBytes(dir);
788
+ const zeroProgressStatus = runState(['status'], dir);
789
+ assertExit(zeroProgressStatus, 0);
790
+ if (!/"routeNode":\s*null/.test(zeroProgressStatus.output)) {
791
+ throw new Error('零进展态:next 会 BLOCKED 且不打印 NODE,status.routeNode 必须是 null,实际输出:\n'
792
+ + zeroProgressStatus.output);
793
+ }
794
+ const zeroProgressRouteLine = zeroProgressStatus.output.split('\n').find((line) => line.startsWith('ROUTE: '));
795
+ if (!zeroProgressRouteLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + zeroProgressStatus.output);
796
+ for (const token of ['route=null', 'next 将 BLOCKED', '路由零进展', '先按恢复指引处理']) {
797
+ if (!zeroProgressRouteLine.includes(token)) {
798
+ throw new Error('零进展态 ROUTE: 行缺少 ' + token + ':' + zeroProgressRouteLine);
799
+ }
800
+ }
801
+ assertStateBytesUnchanged(dir, zeroProgressBytes, '零进展态下 status 仍是只读视图(不得写 state)');
802
+ const zeroProgressNext = runState(['next'], dir);
803
+ assertExit(zeroProgressNext, 1);
804
+ assertOut(zeroProgressNext, 'BLOCKED: 路由零进展');
805
+ if (/^NODE: /m.test(zeroProgressNext.output)) {
806
+ throw new Error('零进展态:next 必须 BLOCKED、不得打印 NODE\n实际输出:\n' + zeroProgressNext.output);
807
+ }
808
+ assertStateBytesUnchanged(dir, zeroProgressBytes, '零进展态下 next 的 BLOCK 分支不得写 state');
809
+
810
+ // 零进展态同样:record 不得把「没有下一节点」说成 NEXT: done,原因与 ROUTE: 行同源。
811
+ const recordZeroProgress = runState(['record', 'execute', '{"summary":"execute recorded while routing is stuck"}'], dir);
812
+ assertExit(recordZeroProgress, 0);
813
+ assertOut(recordZeroProgress, 'EVIDENCE: execute');
814
+ assertNotOut(recordZeroProgress, 'NEXT: done');
815
+ if (/^NODE: /m.test(recordZeroProgress.output)) {
816
+ throw new Error('零进展态下 record 不得给出下一节点(next 此刻不打印 NODE)\n实际输出:\n' + recordZeroProgress.output);
817
+ }
818
+ assertOut(recordZeroProgress, 'NEXT: blocked(路由零进展');
819
+ assertOut(recordZeroProgress, '先按恢复指引处理');
820
+
821
+ // RETURN 回程构造态(源节点未 entry、无 evidence):产物已把路由推到源节点之后 → next 保留
822
+ // 源节点跑出口。NODE 必须与 status.routeNode 同一值(旧实现直接打印 state.currentNode,status
823
+ // 报产物后继 verify——同一 state 两个答案),并给出 WHY: 说明回程原因。
824
+ writeFile(dir, fixTaskPath, fixBatchTaskText('done'));
825
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REVIEW.md',
826
+ '# REVIEW\n\n## 结论\n\n回程态构造:execute 已完成,等待 review 出口。\n');
827
+ writeState(dir, {
828
+ ...fixState,
829
+ enteredNodes: ['open', 'design', 'plan', 'execute', 'subagent-execute'],
830
+ evidence: {
831
+ open: { summary: 'open complete' },
832
+ design: { summary: 'design complete' },
833
+ plan: { summary: 'plan complete' },
834
+ execute: { summary: 'fix batch executed' },
835
+ 'subagent-execute': { summary: 'delegated' },
836
+ },
837
+ });
838
+ const returnBytes = readStateBytes(dir);
839
+ const returnStatus = runState(['status'], dir);
840
+ assertExit(returnStatus, 0);
841
+ const returnRouteNode = (returnStatus.output.match(/"routeNode":\s*"([^"]+)"/) ?? [])[1];
842
+ // 回程态的解释面同源:next 的 WHY: 说「回程源节点 review…」,ROUTE: 行也必须给出同一原因——
843
+ // 否则 derived=verify 与 route=review 并排却不说明为什么,读起来就像产物推导指向 review
844
+ // (缺这条分支时正好如此)。同一停留原因有四个输出面,少一个就分叉一个。
845
+ const returnRouteLine = returnStatus.output.split('\n').find((line) => line.startsWith('ROUTE: '));
846
+ if (!returnRouteLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + returnStatus.output);
847
+ for (const token of ['route=review', '回程', '产物在场且未出口', '保留源节点 review 跑出口']) {
848
+ if (!returnRouteLine.includes(token)) {
849
+ throw new Error('回程态 ROUTE: 行缺少 ' + token + ':' + returnRouteLine);
850
+ }
851
+ }
852
+ const returnNext = runState(['next'], dir);
853
+ assertExit(returnNext, 0);
854
+ assertOut(returnNext, 'RETURN: 回程源节点 review');
855
+ const returnNextNode = (returnNext.output.match(/^NODE: (.+)$/m) ?? [])[1];
856
+ if (returnRouteNode !== returnNextNode) {
857
+ throw new Error('RETURN 回程态下 status.routeNode 与 next 的 NODE 不一致(同一事实两处说法):'
858
+ + JSON.stringify(returnRouteNode) + ' vs ' + JSON.stringify(returnNextNode)
859
+ + '\nstatus 输出:\n' + returnStatus.output + '\nnext 输出:\n' + returnNext.output);
860
+ }
861
+ if (returnNextNode !== 'review') {
862
+ throw new Error('RETURN 回程态:源节点未出口时 next 应保留源节点 review 跑出口,实际: '
863
+ + JSON.stringify(returnNextNode) + '\nnext 输出:\n' + returnNext.output);
864
+ }
865
+ const returnWhyLine = returnNext.output.split('\n').find((line) => line.startsWith('WHY: '));
866
+ if (!returnWhyLine) throw new Error('RETURN 回程态下 next 缺少 WHY: 解释行\n实际输出:\n' + returnNext.output);
867
+ for (const token of ['回程源节点 review', '产物在场且未出口', '保留源节点跑出口']) {
868
+ if (!returnWhyLine.includes(token)) {
869
+ throw new Error('RETURN 的 WHY: 行缺少 ' + token + ':' + returnWhyLine);
870
+ }
871
+ }
872
+ assertStateBytesUnchanged(dir, returnBytes, 'RETURN 回程分支是只读放行(不得改写 state)');
183
873
  },
184
874
  },
185
875
 
@@ -270,20 +960,243 @@ export const ENTRIES = [
270
960
  },
271
961
  },
272
962
 
273
- // 14: 串行 pending 未完成 → BLOCKED
963
+ // 14: 串行 pending 未完成 → BLOCKED;in-place 扩展:结构化预检(exit --preflight)
964
+ // 缺陷形态:每任务预检被设想的时点(result 已记、尚未标 done)在完整出口链里必先撞更早的
965
+ // 进展类门禁——串行 pending 排在模板保真门之前,结构问题根本报不出来。本例用同一夹具证明:
966
+ // ① 完整 exit(不带 --apply)仍报进展类问题(对照锚),且此刻还没到结构门;
967
+ // ② --preflight 首报结构问题、不报串行 pending,且只读(state 字节零改写 + 不写提示账本);
968
+ // ③ 旧 change 只 WARN 不阻断;④ 参数防护 fail-closed(--preflight+--apply / 非 exit 命令 /
969
+ // 未知节点);⑤ 通过时提示不误导(不打印 --apply 引导),结构干净也不放行推进(完整 exit 照旧拦)。
970
+ // 同缺陷的第二形态(⑥⑦⑧,in-place 追加):空 open 节点曾因「入口三件只查在场者」一件都没查、
971
+ // 直接打印 ALL CHECKS PASSED——⑥ 要求缺件必须 BLOCK 且逐项给路径 + 模板指针;⑦ 要求缺件与结构
972
+ // 问题同轮报告(先列缺失件、再列结构问题);⑧ 要求工件齐但缺段时仍回到既有两阶段结构报文
973
+ // (首段只报类别计数)。三者都断言 state 字节零改写(预检仍只读)。
974
+ // 反向构造:把预检实现改回「跑全链」⇒ ② 的旧 change 分支落进完整出口链、被串行 pending 拦下
975
+ // (期望 exit 0 实际 1,断言红);让预检写 state ⇒ ②/⑥⑦⑧ 的字节断言红;写提示账本 ⇒ ① 的账本
976
+ // 断言红;去掉声明工件存在性判据 ⇒ ⑥ 的 BLOCK 断言红(回到打印 ALL CHECKS PASSED 的假绿)。
274
977
  {
275
- name: '14 execute exit BLOCKED:串行 pending 未完成',
978
+ name: '14 execute exit BLOCKED:串行 pending 未完成 + --preflight 结构化预检(结构先报/只读/分级/参数防护)',
276
979
  run: (dir) => {
980
+ // SUMMARY 模板(夹具自带:两种检出形态下都确定,不依赖 vendored 模板在场)。H2 段集 = 登记表
981
+ // 登记的全部 SUMMARY 段(含条件段)——坏 SUMMARY 的缺陷因此只暴露在「段形」这一层。
982
+ writeFile(dir, 'flow-kit/templates/SUMMARY.md', [
983
+ '# SUMMARY 模板',
984
+ '',
985
+ '## 做了什么(一段话)',
986
+ '## 改动文件',
987
+ '## verify 输出(必填)',
988
+ '## 6 维自查(生产代码改动必填 · 来自 4-dev 步骤 4)',
989
+ '## 数据库迁移(涉及 schema 变更必填 · 来自 4-dev 步骤 1.7 / R4.5)',
990
+ '## 越界检查(必填 · 来自 4-dev 步骤 5 / R6.5 / B3 老项目护栏)',
991
+ '## 破坏性变更(涉及破坏性改动必填 · 来自 4-dev 步骤 1.8 / R4.6 / B4 老项目护栏)',
992
+ '## 决策与偏离(如有)',
993
+ '## 是否触发新工作',
994
+ '## 完成判定',
995
+ '',
996
+ ].join('\n'));
277
997
  const st = baseState('execute');
998
+ st.newChange = true;
999
+ st.enteredNodes = ['execute'];
278
1000
  st.evidence.execute = { summary: 'executed' };
279
1001
  st.evidence['subagent-execute'] = { handoffResult: handoffFor(['P02']) };
280
1002
  writeState(dir, st);
281
1003
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' +
282
1004
  '<task id="T01" parallel="false" status="pending"><action>实现 T01</action><write_files>src/t1.mjs</write_files><verify>node --check src/t1.mjs</verify></task>\n' + TASK_P2);
1005
+ // 坏 SUMMARY:关键段齐(关键段门能过),但段形不合模板——标题缺 `# SUMMARY:`
1006
+ // 前缀、首部四字段缺席、段序偏离、缺「是否触发新工作」「完成判定」。这正是只有模板保真门
1007
+ // 才判、因而被更早的进展门挡住的结构问题。
283
1008
  writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', summaryContent());
284
- const res = runGuard(['exit', 'execute'], dir);
285
- assertExit(res, 1);
286
- assertOut(res, '串行 pending');
1009
+ const serialExit = runGuard(['exit', 'execute'], dir);
1010
+ assertExit(serialExit, 1);
1011
+ assertOut(serialExit, '串行 pending');
1012
+ assertNotOut(serialExit, '模板结构校验失败');
1013
+
1014
+ // ① 结构化预检:同一夹具下首报结构问题(不得报进展类);且只读(state 字节与账本零改写)
1015
+ const preflightBytes = readStateBytes(dir);
1016
+ const pre = runGuard(['exit', 'execute', '--preflight'], dir);
1017
+ assertExit(pre, 1);
1018
+ assertOut(pre, 'PREFLIGHT: ');
1019
+ assertOut(pre, 'T01-SUMMARY.md 模板结构校验失败');
1020
+ assertOut(pre, '(模板: flow-kit/templates/SUMMARY.md)');
1021
+ assertOut(pre, '缺段 2 项'); // 首段形态:类别计数(缺段不列段名)
1022
+ assertNotOut(pre, '缺段 2 项:');
1023
+ assertNotOut(pre, '串行 pending');
1024
+ assertNotOut(pre, 'ALL CHECKS PASSED');
1025
+ assertStateBytesUnchanged(dir, preflightBytes, '--preflight 只读:不得写 state');
1026
+ assertTrue(!fs.existsSync(path.join(dir, '.specs', CHANGE_ID, '.template-hints.json')),
1027
+ '--preflight 不得写模板提示账本(.template-hints.json)');
1028
+
1029
+ // ② 分级不变:同一坏 SUMMARY 在旧 change 只 WARN 不阻断(预检不得把旧 change 升级成 BLOCK)
1030
+ writeState(dir, { ...st, newChange: false });
1031
+ const oldChangeBytes = readStateBytes(dir);
1032
+ const oldChangePre = runGuard(['exit', 'execute', '--preflight'], dir);
1033
+ assertExit(oldChangePre, 0);
1034
+ assertOut(oldChangePre, 'TEMPLATE-STRUCTURE WARN');
1035
+ assertNotOut(oldChangePre, 'BLOCKED');
1036
+ assertStateBytesUnchanged(dir, oldChangeBytes, '旧 change 预检同样只读');
1037
+ writeState(dir, st);
1038
+ const restoredBytes = readStateBytes(dir);
1039
+
1040
+ // ③ 参数防护 fail-closed:--preflight 与 --apply 同时给 ⇒ 用法错误(只读/写盘无合法语义)
1041
+ const conflict = runGuard(['exit', 'execute', '--preflight', '--apply'], dir);
1042
+ assertExit(conflict, 1);
1043
+ assertOut(conflict, '用法错误');
1044
+ assertOut(conflict, '--apply');
1045
+ assertStateBytesUnchanged(dir, restoredBytes, '用法错误路径不得写 state');
1046
+ const wrongCommand = runGuard(['entry', 'execute', '--preflight'], dir);
1047
+ assertExit(wrongCommand, 1);
1048
+ assertOut(wrongCommand, '用法错误');
1049
+ assertOut(wrongCommand, '只能与 exit');
1050
+
1051
+ // ③b 未知参数 fail-closed:exit 的参数解析只认 --apply / --preflight 两个**已知** token——
1052
+ // 其余若静默忽略,「参数说错了但仍然跑」的两种形态就会漏过:
1053
+ // · `--bogus` 被静默忽略 ⇒ 一次看起来成功的预演(只读面被误当成通过);
1054
+ // · `--prefligh`(笔误)既不是预检、也不报错 ⇒ 静默走**完整出口链**,预检被当成全链预演。
1055
+ // 判据:未知 `--*` 一律用法错误(非零退出),且**不得**进入任何门禁链(不打印进展类报错)。
1056
+ // 正对照紧随其后(④:合法 `--preflight` 仍 exit 0 + ALL CHECKS PASSED)——同一夹具、单变量。
1057
+ const typo = runGuard(['exit', 'execute', '--prefligh'], dir);
1058
+ assertExit(typo, 1);
1059
+ assertOut(typo, '用法错误');
1060
+ assertOut(typo, '--prefligh');
1061
+ assertNotOut(typo, '串行 pending');
1062
+ assertStateBytesUnchanged(dir, restoredBytes, '笔误参数的用法错误路径不得写 state');
1063
+ const unknownPair = runGuard(['exit', 'execute', '--prefilter', '--bogus'], dir);
1064
+ assertExit(unknownPair, 1);
1065
+ assertOut(unknownPair, '用法错误');
1066
+ assertOut(unknownPair, '--prefilter');
1067
+ assertOut(unknownPair, '--bogus');
1068
+ assertNotOut(unknownPair, '串行 pending');
1069
+ assertStateBytesUnchanged(dir, restoredBytes, '未知参数的用法错误路径不得写 state');
1070
+
1071
+ // ④ 结构干净 ⇒ 预检通过,且不打印 --apply 引导(预检不落盘,那行会误导)
1072
+ writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', strictSummary('T01'));
1073
+ const okBytes = readStateBytes(dir);
1074
+ const ok = runGuard(['exit', 'execute', '--preflight'], dir);
1075
+ assertExit(ok, 0);
1076
+ assertOut(ok, 'ALL CHECKS PASSED');
1077
+ assertOut(ok, 'PREFLIGHT: structural checks only');
1078
+ assertNotOut(ok, 'APPLY: rerun with --apply');
1079
+ assertStateBytesUnchanged(dir, okBytes, '预检通过路径不得写 state');
1080
+ // 结构干净 ≠ 进展完成:串行 pending 仍在,完整 exit 照旧拦(预检不越权放行推进)
1081
+ const stillBlocked = runGuard(['exit', 'execute'], dir);
1082
+ assertExit(stillBlocked, 1);
1083
+ assertOut(stillBlocked, '串行 pending');
1084
+
1085
+ // ⑤ 未知节点照既有报错(--preflight 不得把未知节点变成静默通过)
1086
+ const unknown = runGuard(['exit', 'no-such-node', '--preflight'], dir);
1087
+ assertExit(unknown, 1);
1088
+ assertOut(unknown, 'Unknown workflow Node: no-such-node');
1089
+
1090
+ // 预检与完整出口共用同一结构报告器:父段正文留下 N/A 意图痕迹、却写不进白名单时,
1091
+ // 「该怎么写」属结构面反馈,预检必须一并带出——自持一份只读副本的实现会丢掉这一段,
1092
+ // 于是同一条结构问题在预检里只说「缺子段」、在收尾时却还给写法,两种模式的反馈不一致。
1093
+ // 夹具:6 维自查段写成「见 N/A …」(剥掉包裹后开头是实词,不算整段不适用),两条结构子段
1094
+ // 因此仍要求;该段保留 brooks-review 字样,关键段门照常通过。
1095
+ const adviceSummary = strictSummary('T01')
1096
+ .replace('- 功能: 通过(brooks-review 已跑)\n- 性能: 无影响\n- 安全: 无影响\n- 兼容: 通过\n- 可观测: 通过\n- 可维护: 通过',
1097
+ '见 N/A(六维由 brooks-review 覆盖)')
1098
+ .replace('### 已知接受 + 理由\n\n- 无(夹具)。\n\n### 已知小问题\n\n- 无(夹具)。\n\n', '');
1099
+ writeFile(dir, '.specs/' + CHANGE_ID + '/T01-SUMMARY.md', adviceSummary);
1100
+ const adviceBytes = readStateBytes(dir);
1101
+ const advice = runGuard(['exit', 'execute', '--preflight'], dir);
1102
+ assertExit(advice, 1);
1103
+ assertOut(advice, '缺结构子段 2 项');
1104
+ assertOut(advice, '若要整段不适用');
1105
+ assertOut(advice, '包裹符号本身就被接受');
1106
+ assertStateBytesUnchanged(dir, adviceBytes, '预检的写法建议路径同样只读');
1107
+
1108
+ // ⑥ 空 open 节点(本缺陷的原始形态):全新 change 的 `.specs/<id>/` 空目录、无 CHANGE.md /
1109
+ // REQUIREMENT.md。改前结构子集只查「在场者」⇒ 一件都没查、打印 ALL CHECKS PASSED(假绿)。
1110
+ // 本节点声明的 file 类工件(open: CHANGE.md + REQUIREMENT.md)是否在场是**结构事实**,不是
1111
+ // 进展判定:缺失必须 BLOCK,逐项给路径,并给一句「先创建该工件(按模板路径)」的指引。
1112
+ const openState = { ...baseState('open'), newChange: true, enteredNodes: ['open'] };
1113
+ fs.rmSync(path.join(dir, '.specs', CHANGE_ID), { recursive: true, force: true });
1114
+ writeState(dir, openState);
1115
+ const emptyOpenBytes = readStateBytes(dir);
1116
+ const emptyOpen = runGuard(['exit', 'open', '--preflight'], dir);
1117
+ assertExit(emptyOpen, 1);
1118
+ assertOut(emptyOpen, 'BLOCKED');
1119
+ assertOut(emptyOpen, '.specs/' + CHANGE_ID + '/CHANGE.md');
1120
+ assertOut(emptyOpen, '.specs/' + CHANGE_ID + '/REQUIREMENT.md');
1121
+ assertOut(emptyOpen, '模板: flow-kit/templates/CHANGE.md');
1122
+ assertNotOut(emptyOpen, 'ALL CHECKS PASSED');
1123
+ assertStateBytesUnchanged(dir, emptyOpenBytes, '缺件预检同样只读:不得写 state');
1124
+ assertTrue(!fs.existsSync(path.join(dir, '.specs', CHANGE_ID, '.template-hints.json')),
1125
+ '缺件预检不得写模板提示账本(.template-hints.json)');
1126
+
1127
+ // 上面那条模板指针(`模板: flow-kit/templates/CHANGE.md`)由「声明工件名 → 模板键」的派生得来。
1128
+ // 同一份派生只许有一个实现:结构预检(缺件报文的模板指针)与模板保真门禁(该工件用哪份骨架
1129
+ // 校验)是两个消费面,各自持有一份等价副本在口径演进时必然分叉,同一份工件就会得到两套说法。
1130
+ // 取用面由真实引用派生(不写文件名清单),静态锁因此对新增消费方同样生效——把副本写回任一
1131
+ // 消费方,本断言即红。
1132
+ const templateKeyProblems = singleSourceImportProblems({
1133
+ symbol: 'templateKeyFromArtifactName',
1134
+ sourceRel: 'protocol-utils.mjs',
1135
+ texts: engineScriptTexts(),
1136
+ });
1137
+ if (templateKeyProblems.length > 0) {
1138
+ throw new Error('模板键派生的单一来源被破坏(' + templateKeyProblems.join('; ') + ')');
1139
+ }
1140
+
1141
+ // ⑦ 缺件与结构问题同轮报告(先列缺失件,再列结构问题):CHANGE.md 在场但缺模板段、
1142
+ // REQUIREMENT.md 仍缺席 ⇒ 两类都要报——存在性不再被「在场才查」吞掉结构报告的时机。
1143
+ writeFile(dir, 'flow-kit/templates/CHANGE.md',
1144
+ '# CHANGE 模板\n\n## Why(为什么做)\n## What(做什么)\n## 影响面\n');
1145
+ writeFile(dir, '.specs/' + CHANGE_ID + '/CHANGE.md',
1146
+ '# CHANGE: 夹具\n\n## Why(为什么做)\n\n理由。\n\n## 影响面\n\n夹具。\n');
1147
+ const mixedBytes = readStateBytes(dir);
1148
+ const mixed = runGuard(['exit', 'open', '--preflight'], dir);
1149
+ assertExit(mixed, 1);
1150
+ assertOut(mixed, 'BLOCKED');
1151
+ assertOut(mixed, '.specs/' + CHANGE_ID + '/REQUIREMENT.md');
1152
+ assertOut(mixed, 'CHANGE.md 模板结构校验失败');
1153
+ assertOut(mixed, '缺段 1 项'); // 首段形态:类别计数(缺段不列段名)
1154
+ assertNotOut(mixed, '缺段 1 项:');
1155
+ assertNotOut(mixed, 'ALL CHECKS PASSED');
1156
+ assertTrue(mixed.output.indexOf('.specs/' + CHANGE_ID + '/REQUIREMENT.md')
1157
+ < mixed.output.indexOf('CHANGE.md 模板结构校验失败'),
1158
+ '同轮报告应先列缺失工件、再列结构问题\n实际输出:\n' + mixed.output);
1159
+ assertStateBytesUnchanged(dir, mixedBytes, '缺件 + 结构问题同轮的预检只读');
1160
+
1161
+ // ⑧ 工件齐但缺段(本缺陷修复后不得倒退的既有语义):补上结构完整的 REQUIREMENT.md,
1162
+ // CHANGE.md 仍缺一段 ⇒ 只剩两阶段结构报文,且首段只报类别计数、不列段名。
1163
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1164
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(AC)\n## 范围切分\n');
1165
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md', [
1166
+ '# REQUIREMENT: 夹具',
1167
+ '',
1168
+ '## 用户故事(User Story)',
1169
+ '',
1170
+ '夹具故事。',
1171
+ '',
1172
+ '## 验收准则(AC)',
1173
+ '',
1174
+ '- AC-1: 夹具。',
1175
+ '',
1176
+ '## 范围切分',
1177
+ '',
1178
+ '### v1(本次必做)',
1179
+ '',
1180
+ '- 夹具。',
1181
+ '',
1182
+ '### v2(下一轮考虑,不本次)',
1183
+ '',
1184
+ '- 无。',
1185
+ '',
1186
+ '### out(永远不做)',
1187
+ '',
1188
+ '- 无。',
1189
+ '',
1190
+ ].join('\n'));
1191
+ const structureOnlyBytes = readStateBytes(dir);
1192
+ const structureOnly = runGuard(['exit', 'open', '--preflight'], dir);
1193
+ assertExit(structureOnly, 1);
1194
+ assertOut(structureOnly, 'BLOCKED: CHANGE.md 模板结构校验失败');
1195
+ assertOut(structureOnly, '缺段 1 项');
1196
+ assertNotOut(structureOnly, '缺段 1 项:');
1197
+ assertNotOut(structureOnly, '声明工件缺失');
1198
+ assertNotOut(structureOnly, 'ALL CHECKS PASSED');
1199
+ assertStateBytesUnchanged(dir, structureOnlyBytes, '两阶段结构报文路径同样只读');
287
1200
  },
288
1201
  },
289
1202
 
@@ -351,6 +1264,9 @@ export const ENTRIES = [
351
1264
  handoffResult: handoffFor(['P01']),
352
1265
  };
353
1266
  writeState(dir, inFlight);
1267
+ // 新 change 的声明标记:真实流程里协调者声明 / record 自动补写;夹具直接写 state,须补同一份事实
1268
+ // (否则先撞声明覆盖门,被测的「在飞委托」判据根本轮不到说话)。
1269
+ writeNodeDeclarationMarkers(dir, 'subagent-execute');
354
1270
  const blocked = runGuard(['exit', 'subagent-execute'], dir);
355
1271
  assertExit(blocked, 1);
356
1272
  assertOut(blocked, '在飞委托');
@@ -392,6 +1308,7 @@ export const ENTRIES = [
392
1308
  handoffResult: handoffFor(['P01']),
393
1309
  };
394
1310
  writeState(dir, withdrawCase);
1311
+ writeNodeDeclarationMarkers(dir, 'subagent-execute');
395
1312
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n' + TASK_P1 + TASK_P2);
396
1313
  // 严格形态(newChange:true)下 done 任务须有对应 SUMMARY——补两份,使「撤回 ⇒ 出口放行」
397
1314
  // 的断言落在**唯一**阻塞点(在飞委托)上,而不是被无关门禁干扰。
@@ -413,6 +1330,13 @@ export const ENTRIES = [
413
1330
  assertOut(completedWithdraw, 'handoffResult 在场');
414
1331
  assertOut(completedWithdraw, '撤回只适用于被遗弃的 request');
415
1332
  assertOut(completedWithdraw, '恢复:');
1333
+ // ②c-0c 恢复句的可照抄性:命令是这条恢复路径唯一的可执行面,没有形态断言时退回裸脚本名 /
1334
+ // <description> 占位(占位在 bash 里是输入重定向)不会被发现。期望值取命令文本的唯一
1335
+ // 装配,不另写一份字面路径——运行期换了装配,这里随之变红。
1336
+ assertOut(completedWithdraw, scriptCommand({
1337
+ scriptsDir: SCRIPTS_DIR, runRoot: dir, script: 'workflow-handoff.mjs', args: ['request', 'P01'],
1338
+ }));
1339
+ assertNotOut(completedWithdraw, '<description>');
416
1340
  assertNotOut(completedWithdraw, 'HANDOFF WITHDRAW');
417
1341
  assertStateBytesUnchanged(dir, bytesBeforeCompletedWithdraw, '撤回已收工的委托被拒');
418
1342
  // ②c-1 真实 CLI 撤回:缺 --by 先被拒(留痕来源不可缺省)⇒ 补齐后撤回成功
@@ -465,6 +1389,11 @@ export const ENTRIES = [
465
1389
  const resultAfterWithdraw = runHandoff(['result', 'P02', '{"commitHash":"deadbee","completedChecks":[]}'], dir);
466
1390
  assertExit(resultAfterWithdraw, 1);
467
1391
  assertOut(resultAfterWithdraw, '已撤回(终态)');
1392
+ // ②c-5b 同一恢复句的形态(与 ②c-0c 同一装配):命令带真实脚本路径与任务号,无占位符。
1393
+ assertOut(resultAfterWithdraw, scriptCommand({
1394
+ scriptsDir: SCRIPTS_DIR, runRoot: dir, script: 'workflow-handoff.mjs', args: ['request', 'P02'],
1395
+ }));
1396
+ assertNotOut(resultAfterWithdraw, '<description>');
468
1397
  // ②c-6 判据要求留痕两字段齐备:抽掉 withdrawnBy(手改形态)⇒ 重新计为在飞委托 ⇒ 出口回收
469
1398
  const strippedWithdraw = JSON.parse(readStateBytes(dir));
470
1399
  delete strippedWithdraw.evidence['subagent-execute'].handoffRequests.P02.withdrawnBy;
@@ -638,10 +1567,14 @@ export const ENTRIES = [
638
1567
 
639
1568
  // 21: exit verify——LESSONS.md 条目编号乱序 → WARN 不 BLOCK;verify 命令 timeout 可配置:
640
1569
  // ① 缺省 timeout(无 env)下耗时命令通过(缺省保持大值);② env
641
- // FLOW_COMET_VERIFY_TIMEOUT_MS 覆盖生效——设小值后同耗时命令超时 BLOCK
1570
+ // FLOW_COMET_VERIFY_TIMEOUT_MS 覆盖生效——设小值后同耗时命令超时 BLOCK。同场景 in-place 扩展
1571
+ // AC 覆盖判据(verify 出口):全覆盖通过 / 漏一条点名 BLOCK / 多条全点名 / 旧 change 只 WARN /
1572
+ // 两种书写形态与编号后缀归并 / 模板段名不含关键词时回落到与入口同一份基准 / 「判不了」按成因二分
1573
+ // (载体缺席 = 文件 / 模板根本不在 → 显式未校验且不改退出码;工件内容不可判 = 承载段被删掉或清单
1574
+ // 读不出 → 新 change BLOCKED、旧 change WARN 计数)。
642
1575
  {
643
- name: '21 exit verify WARN:LESSONS.md 编号乱序 + verify timeout env 覆盖',
644
- run: (dir) => {
1576
+ name: '21 exit verify WARN:LESSONS.md 编号乱序 + verify timeout env 覆盖 + AC 覆盖(新 change BLOCK / 旧 change WARN / 判不了按成因二分)',
1577
+ run: async (dir) => {
645
1578
  const st = baseState('verify');
646
1579
  st.evidence.verify = { summary: 'verified' };
647
1580
  writeState(dir, st);
@@ -654,11 +1587,49 @@ export const ENTRIES = [
654
1587
  // 子断言:无区外条目时不得打印"条目在条目区外"WARN(误报修复——修复前
655
1588
  // console.error 在 if(outside) 之外无条件执行,每次 exit 都刷一条空 WARN)
656
1589
  assertNotOut(res, '条目在条目区外');
1590
+ // 子断言(围栏分段):两个乱序条目之间隔着**围栏示例里的** `## ` 标题——围栏里的标题不开
1591
+ // 新段,两个条目因此仍在同一段,乱序必须照样判出。旧实现按任意 `^##` 行分段:示例行把
1592
+ // 一段切成两段,「同段内递增」这条判据的同段条件不成立,乱序被静默放过(假绿)。
1593
+ writeFile(dir, '.specs/LESSONS.md', '# LESSONS\n\n## 条目区\n\n### L-002: b\n\n'
1594
+ + '```md\n## 写法样例(围栏内的标题不结束条目区)\n```\n\n### L-001: a\n');
1595
+ const resFencedOrder = runGuard(['exit', 'verify'], dir);
1596
+ assertExit(resFencedOrder, 0);
1597
+ assertOut(resFencedOrder, 'WARN: LESSONS.md 条目编号乱序');
1598
+ // 复位:后续子断言回到原夹具(两个乱序条目紧邻,判据与上面同形)
1599
+ writeFile(dir, '.specs/LESSONS.md', '# LESSONS\n\n## 条目区\n\n### L-002: b\n### L-001: a\n');
657
1600
  // 子断言:## 验证命令 段标题带括号后缀(与 ## 自检方法 段括号后缀兼容风格一致)不误 BLOCK
658
1601
  writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令(必填 · exit verify 真实执行)\n\n```bash\nnode -e "1"\n```\n');
659
1602
  const resBracket = runGuard(['exit', 'verify'], dir);
660
1603
  assertExit(resBracket, 0);
661
1604
  assertOut(resBracket, 'ALL CHECKS PASSED');
1605
+ // 子断言:归档判定按 <日期>-<本 change> 精确形态。诱饵 = 名字以 -<本 change> 结尾的别的 change
1606
+ // 归档目录:本 change 并未归档,复核命令必须真实执行(副作用文件即执行证据)。修复前后缀匹配
1607
+ // 把本 change 判成「已归档」,整个验证命令被跳过——那是放行口,不是显示问题。
1608
+ const ranByDecoy = path.join(dir, 'archive-decoy-ran.txt');
1609
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令\n\n' +
1610
+ '```bash\nnode -e "require(\'fs\').writeFileSync(\'archive-decoy-ran.txt\',\'RAN\')"\n```\n');
1611
+ writeFile(dir, '.specs/archive/2026-10-20-other-' + CHANGE_ID + '/CHANGE.md', '# CHANGE\n\n## Why\n\n诱饵。\n');
1612
+ fs.rmSync(ranByDecoy, { force: true });
1613
+ const resDecoyArchive = runGuard(['exit', 'verify'], dir);
1614
+ assertExit(resDecoyArchive, 0);
1615
+ if (!fs.existsSync(ranByDecoy)) {
1616
+ throw new Error('同后缀诱饵归档不得把本 change 判成已归档:验证命令必须真实执行(副作用文件缺失)');
1617
+ }
1618
+ // 反向构造(同一判据 + 单变量):真正的归档目录(<日期>-<本 change>)在场时豁免仍生效——命令
1619
+ // 一旦被执行就会以 3 退出。精确化不得把「归档 change 免跑验证命令」一并收紧掉。
1620
+ const ranByArchive = path.join(dir, 'archive-real-ran.txt');
1621
+ fs.rmSync(path.join(dir, '.specs', 'archive', '2026-10-20-other-' + CHANGE_ID), { recursive: true, force: true });
1622
+ writeFile(dir, '.specs/archive/2026-10-20-' + CHANGE_ID + '/CHANGE.md', '# CHANGE\n\n## Why\n\n已归档。\n');
1623
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令\n\n' +
1624
+ '```bash\nnode -e "require(\'fs\').writeFileSync(\'archive-real-ran.txt\',\'RAN\'); process.exit(3)"\n```\n');
1625
+ fs.rmSync(ranByArchive, { force: true });
1626
+ const resRealArchive = runGuard(['exit', 'verify'], dir);
1627
+ assertExit(resRealArchive, 0);
1628
+ if (fs.existsSync(ranByArchive)) {
1629
+ throw new Error('真正的归档 change 仍须豁免真实跑验证命令(反向构造:豁免被误收紧)');
1630
+ }
1631
+ // 复位:归档目录撤掉、TEST.md 回到快速通过的形态,后续 timeout 断言按原样执行
1632
+ fs.rmSync(path.join(dir, '.specs', 'archive'), { recursive: true, force: true });
662
1633
  // ① 缺省 timeout(未设 env)保持大值:1.5s 耗时命令通过(若缺省被误改小 → 超时 RED)
663
1634
  writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令\n\n```bash\nnode -e "setTimeout(()=>{}, 1500)"\n```\n');
664
1635
  const resDefault = runGuard(['exit', 'verify'], dir);
@@ -703,6 +1674,388 @@ export const ENTRIES = [
703
1674
  throw new Error('exit verify 成功不得清 Fix 归位轮次(计数隔离): '
704
1675
  + JSON.stringify(stPass.fixRoundsByChange));
705
1676
  }
1677
+ // ===== AC 覆盖(verify 出口):判据在 lib/ac-coverage.mjs(纯判定),此处只验分级与报文 =====
1678
+ // 夹具自带 REQUIREMENT / TEST 模板(段名由骨架派生);新 change BLOCKED / 旧 change WARN。
1679
+ // 反向构造:把该判据从 verify 出口链里摘掉 ⇒ ②③ 回到 exit 0(缺覆盖被静默放过),① 的
1680
+ // 「无缺覆盖输出」也失去判别力(它只证明「不误报」,负例才证明「报得出」)。
1681
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1682
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(AC)\n## 非功能性需求\n');
1683
+ writeFile(dir, 'flow-kit/templates/TEST.md', '# TEST 模板\n\n## 第 1 轮 · 功能测试\n');
1684
+ // 本块用 newChange 夹具(AC-6 要求新 change 必拦),故 LESSONS 必须回到有序形态——编号乱序的
1685
+ // 新 change 会被 LESSONS 区门禁先拦(该判据由本场景前半段覆盖,不是本块被测面)。
1686
+ writeFile(dir, '.specs/LESSONS.md', '# LESSONS\n\n## 条目区\n\n### L-001: a\n### L-002: b\n');
1687
+ const acCriteria = (ids) => ids
1688
+ .map((id) => '### ' + id + ' · 夹具准则\n\n- **Given** 夹具前置\n- **When** 夹具动作\n- **Then** 夹具结果')
1689
+ .join('\n\n');
1690
+ // acceptanceBody = 「验收准则(AC)」段的正文(两种书写形态与同行多编号都由它构造)
1691
+ const acRequirement = (acceptanceBody) => [
1692
+ '# REQUIREMENT: AC 覆盖夹具',
1693
+ '',
1694
+ '- **Change ID**: ' + CHANGE_ID,
1695
+ '- **关联**: `@.specs/' + CHANGE_ID + '/REQUIREMENT.md`',
1696
+ '',
1697
+ '## 用户故事',
1698
+ '',
1699
+ '- **US-1**:作为执行者,我想让 AC 覆盖判据有夹具。',
1700
+ '',
1701
+ '## 验收准则(AC)',
1702
+ '',
1703
+ acceptanceBody,
1704
+ '',
1705
+ '## 非功能性需求',
1706
+ '',
1707
+ '- **性能**: 无',
1708
+ '',
1709
+ ].join('\n');
1710
+ const acTest = (coveredIds) => [
1711
+ '# TEST: AC 覆盖夹具',
1712
+ '',
1713
+ '- **Change ID**: ' + CHANGE_ID,
1714
+ '- **关联**: `@.specs/' + CHANGE_ID + '/REQUIREMENT.md`',
1715
+ '- **项目类型**: CLI',
1716
+ '',
1717
+ '## 第 1 轮 · 功能测试',
1718
+ '',
1719
+ '### 1.1 测试矩阵(AC → 用例)',
1720
+ '',
1721
+ '| AC | 类型 | 用例文件 / UAT | 状态 |',
1722
+ '|---|---|---|---|',
1723
+ coveredIds.length > 0
1724
+ ? coveredIds.map((id) => '| ' + id + ' | unit | guard-self-test.mjs | ✅ |').join('\n')
1725
+ : '| — | — | 夹具无覆盖行 | — |',
1726
+ '',
1727
+ // 「第 1 轮」段的其余结构子段按登记表登记名在场(父段在场时子段必须在场——本判据不是被测面,
1728
+ // 故夹具按段形补齐,只让 1.1 的行数变化。)
1729
+ '### 1.2 UAT 脚本',
1730
+ '',
1731
+ '- 夹具:见 UAT.md。',
1732
+ '',
1733
+ '### 1.3 覆盖率',
1734
+ '',
1735
+ '- 夹具:不适用。',
1736
+ '',
1737
+ '### 1.4 边界 / 错误路径用例',
1738
+ '',
1739
+ '- 夹具:不适用。',
1740
+ '',
1741
+ '### 1.5 测试质量自检(6 维测试衰退风险)',
1742
+ '',
1743
+ '- 夹具:不适用。',
1744
+ '',
1745
+ '### 1.6 测试质量记事(backlog)',
1746
+ '',
1747
+ '- 夹具:无。',
1748
+ '',
1749
+ '## 验证命令',
1750
+ '',
1751
+ '```bash',
1752
+ 'node -e "1"',
1753
+ '```',
1754
+ '',
1755
+ ].join('\n');
1756
+ const acState = (isNew) => {
1757
+ const st = { ...baseState('verify'), evidence: { verify: { summary: 'verified' } } };
1758
+ if (isNew) {
1759
+ st.newChange = true;
1760
+ st.enteredNodes = ['verify'];
1761
+ }
1762
+ return st;
1763
+ };
1764
+ const acWrite = (acceptanceBody, coveredIds, isNew) => {
1765
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md', acRequirement(acceptanceBody));
1766
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', acTest(coveredIds));
1767
+ writeState(dir, acState(isNew));
1768
+ // 新 change 夹具补齐 verify 节点的声明标记(真实流程里由协调者 / record 写;夹具直接写 state)
1769
+ if (isNew) writeNodeDeclarationMarkers(dir, 'verify');
1770
+ };
1771
+ // 缺覆盖报文的首行(明细只在这一行,断言按它取编号清单——正文别处的编号不算点名)
1772
+ const acMissingLine = (res) => (res.output.match(/缺 AC 覆盖[^\n]*/u) ?? [''])[0];
1773
+ // WARN COUNT 汇总行读数:内容不可判那一支必须真的进入既有计数(差值断言用,形态同波次判据)
1774
+ const warnCountOf = (res) => {
1775
+ const matched = /WARN COUNT: (\d+)/u.exec(res.output);
1776
+ return matched === null ? 0 : Number(matched[1]);
1777
+ };
1778
+ // ① 全量覆盖 → 通过(判据不产生输出:缺覆盖报文与「未校验」都不出现)
1779
+ acWrite(acCriteria(['AC-1', 'AC-2']), ['AC-1', 'AC-2'], true);
1780
+ const acCovered = runGuard(['exit', 'verify'], dir);
1781
+ assertExit(acCovered, 0);
1782
+ assertOut(acCovered, 'ALL CHECKS PASSED');
1783
+ assertNotOut(acCovered, '缺 AC 覆盖');
1784
+ assertNotOut(acCovered, 'AC 覆盖判据无法执行');
1785
+ // 「判据真的判过」= AC 覆盖自己那两行一句都不出现(其它门禁的「未校验(模板缺失)」是别的事实,
1786
+ // 按 AC 判据的专有措辞断言,不拿泛化的「未校验」当判据)
1787
+ assertNotOut(acCovered, 'AC 覆盖判据跳过');
1788
+ // ② 漏一条 → verify 出口 BLOCKED:报文点名该编号 + 「在 1.1 矩阵补行」的恢复指引
1789
+ acWrite(acCriteria(['AC-1', 'AC-2', 'AC-3']), ['AC-1', 'AC-2'], true);
1790
+ const acBlocked = runGuard(['exit', 'verify'], dir);
1791
+ assertExit(acBlocked, 1);
1792
+ assertOut(acBlocked, 'BLOCKED');
1793
+ assertOut(acBlocked, '缺 AC 覆盖');
1794
+ assertTrue(acMissingLine(acBlocked).includes('AC-3'),
1795
+ '缺失清单应点名 AC-3,实际: ' + acMissingLine(acBlocked));
1796
+ assertTrue(!/AC-1|AC-2/u.test(acMissingLine(acBlocked)),
1797
+ '缺失清单不得点名已覆盖的 AC-1 / AC-2,实际: ' + acMissingLine(acBlocked));
1798
+ assertOut(acBlocked, '在 TEST.md 的 1.1 测试矩阵为这些 AC 补行');
1799
+ // ②b 补齐后通过(单变量反向构造:只有矩阵行变了)
1800
+ acWrite(acCriteria(['AC-1', 'AC-2', 'AC-3']), ['AC-1', 'AC-2', 'AC-3'], true);
1801
+ const acFixed = runGuard(['exit', 'verify'], dir);
1802
+ assertExit(acFixed, 0);
1803
+ assertNotOut(acFixed, '缺 AC 覆盖');
1804
+ // ③ 多条缺失 → 全部点名(按 REQUIREMENT 出现顺序,报告稳定可对照)
1805
+ acWrite(acCriteria(['AC-1', 'AC-2', 'AC-3', 'AC-4']), ['AC-1'], true);
1806
+ const acMulti = runGuard(['exit', 'verify'], dir);
1807
+ assertExit(acMulti, 1);
1808
+ assertTrue(acMissingLine(acMulti).includes('AC-2、AC-3、AC-4'),
1809
+ '多条缺失应全部点名(按 REQUIREMENT 顺序),实际: ' + acMissingLine(acMulti));
1810
+ // ④ 「不可判」按成因二分之一——**工件内容不可判**:REQUIREMENT 有验收准则却没有任何 AC 编号。
1811
+ // 验收段在场(载体不缺席)而清单读不出来,不是「判过且通过」:新 change BLOCKED,恢复指引是
1812
+ // 「给编号」(没有编号就没有可对账的清单,补矩阵行不是这一支的出路)。
1813
+ acWrite('- 本段只写散文、不含任何编号(构造「有验收准则却没 AC 编号」形态)。', ['AC-1'], true);
1814
+ const acNoIds = runGuard(['exit', 'verify'], dir);
1815
+ assertExit(acNoIds, 1);
1816
+ assertOut(acNoIds, 'BLOCKED: AC 覆盖判据无法执行');
1817
+ assertOut(acNoIds, '没有 AC-N 编号');
1818
+ assertOut(acNoIds, '给验收准则的每条准则编号');
1819
+ assertNotOut(acNoIds, '缺 AC 覆盖');
1820
+ assertNotOut(acNoIds, '未校验(REQUIREMENT 无 AC 编号)');
1821
+ // ④b 旧 change 同一形态只 WARN(渐进不阻断),且该行进入既有 WARN COUNT——「判不了」不再静默;
1822
+ // 计数差分(判别力):同夹具补上编号且全覆盖后该 WARN 消失,WARN COUNT 恰少 1。
1823
+ acWrite('- 本段只写散文、不含任何编号。', ['AC-1'], false);
1824
+ const acNoIdsOld = runGuard(['exit', 'verify'], dir);
1825
+ assertExit(acNoIdsOld, 0);
1826
+ assertOut(acNoIdsOld, 'WARN: AC 覆盖判据无法执行');
1827
+ assertOut(acNoIdsOld, '(旧 change 渐进不阻断)');
1828
+ assertOut(acNoIdsOld, 'ALL CHECKS PASSED');
1829
+ acWrite(acCriteria(['AC-1']), ['AC-1'], false);
1830
+ const acNoIdsOldFixed = runGuard(['exit', 'verify'], dir);
1831
+ assertExit(acNoIdsOldFixed, 0);
1832
+ assertTrue(warnCountOf(acNoIdsOld) === warnCountOf(acNoIdsOldFixed) + 1,
1833
+ '内容不可判的 WARN 未计入 WARN COUNT(未校验仍静默): 无编号='
1834
+ + warnCountOf(acNoIdsOld) + ' 补编号后=' + warnCountOf(acNoIdsOldFixed));
1835
+ // ⑤ TEST.md 缺席 → 与 REQUIREMENT 缺席同口径:**内容不可判**(载体文件被删,新 change
1836
+ // BLOCKED),不是「未校验」放行。链序同源:AC 覆盖判据排在「## 验证命令」门之前,
1837
+ // 它一旦拦下,命令门就不会在本次出口说话——「没有清单」是更靠前的那一环。
1838
+ acWrite(acCriteria(['AC-1']), ['AC-1'], true);
1839
+ fs.rmSync(path.join(dir, '.specs', CHANGE_ID, 'TEST.md'), { force: true });
1840
+ const acNoTest = runGuard(['exit', 'verify'], dir);
1841
+ assertExit(acNoTest, 1);
1842
+ assertOut(acNoTest, 'BLOCKED: AC 覆盖判据无法执行');
1843
+ assertOut(acNoTest, '没有 TEST.md');
1844
+ assertOut(acNoTest, '恢复: 补回 TEST.md');
1845
+ assertNotOut(acNoTest, '未校验(TEST.md 缺席)');
1846
+ assertNotOut(acNoTest, '缺 AC 覆盖');
1847
+ // 命令门自身另有断言(系统测试集 H6 的缺段格);此处钉的是链序:AC 判据在它之前发言。
1848
+ assertNotOut(acNoTest, 'BLOCKED: TEST.md 需声明 ## 验证命令 段');
1849
+ // ⑥ 旧 change 同输入只 WARN(渐进不阻断,退出码不变)
1850
+ acWrite(acCriteria(['AC-1', 'AC-2']), ['AC-1'], false);
1851
+ const acOldChange = runGuard(['exit', 'verify'], dir);
1852
+ assertExit(acOldChange, 0);
1853
+ assertOut(acOldChange, 'WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖');
1854
+ assertTrue(acMissingLine(acOldChange).includes('AC-2'),
1855
+ '旧 change 的 WARN 同样点名缺失编号,实际: ' + acMissingLine(acOldChange));
1856
+ assertNotOut(acOldChange, 'BLOCKED');
1857
+ assertOut(acOldChange, 'ALL CHECKS PASSED');
1858
+ // ⑦ 书写形态与编号词法:'### AC-N · 标题' 与 '- AC-N: 说明' 两种写法同样解析,同一行的多个编号
1859
+ // 全部收集;'AC-2a' 这类后缀没有自己的编号,归并到 AC-2(不因后缀漏判)。夹具里 AC-4 只在
1860
+ // REQUIREMENT 出现、矩阵无对应行 → 只有它缺。段内围栏里的 '## …' 示例不结束本段(围栏内标题
1861
+ // 若被当成段边界,段被截断 → AC-2..AC-4 读不到 → 判据静默变绿)。
1862
+ acWrite([
1863
+ '### AC-1 · 标题形态',
1864
+ '',
1865
+ '- **Given** 前置',
1866
+ '- **When** 动作',
1867
+ '- **Then** 结果',
1868
+ '',
1869
+ '```markdown',
1870
+ '## 示例:围栏内的二级标题不结束本段',
1871
+ '```',
1872
+ '',
1873
+ '- AC-2: 列表形态(与标题形态同段混排)',
1874
+ '- AC-3、AC-4: 同一行两个编号',
1875
+ ].join('\n'), ['AC-1', 'AC-2a'], true);
1876
+ const acMixed = runGuard(['exit', 'verify'], dir);
1877
+ assertExit(acMixed, 1);
1878
+ assertTrue(acMissingLine(acMixed).includes('AC-3、AC-4'),
1879
+ '混排写法 + 同行多编号应被解析(后缀归并后只剩 AC-3 / AC-4 缺),实际: ' + acMissingLine(acMixed));
1880
+ assertTrue(!/AC-1|AC-2/u.test(acMissingLine(acMixed)),
1881
+ 'AC-1(标题写法)与 AC-2a(后缀归并到 AC-2)都算已覆盖,实际: ' + acMissingLine(acMixed));
1882
+ // ⑧ 「不可判」按成因二分之二——**工件内容不可判**:第 1 轮整段写 N/A(1.1 矩阵段随之不在)而
1883
+ // AC 存在。TEST.md 在场、模板在场,缺的是清单本身 → 新 change BLOCKED,恢复指引是「补 1.1
1884
+ // 矩阵段」;旧实现把它当「未校验」放行(把一段 N/A 读成「无从判断」)。
1885
+ acWrite(acCriteria(['AC-1', 'AC-2']), ['AC-1'], true);
1886
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md',
1887
+ acTest(['AC-1']).replace(/### 1\.1[\s\S]*?(?=## 验证命令)/u, 'N/A\n\n'));
1888
+ const acRoundNa = runGuard(['exit', 'verify'], dir);
1889
+ assertExit(acRoundNa, 1);
1890
+ assertOut(acRoundNa, 'BLOCKED: AC 覆盖判据无法执行');
1891
+ assertOut(acRoundNa, '整段写 N/A 就是这一形态');
1892
+ assertOut(acRoundNa, '补 1.1 测试矩阵段');
1893
+ assertNotOut(acRoundNa, '未校验(TEST.md 无 1.1 测试矩阵段)');
1894
+ // ⑨ 「不可判」的另一半——**载体缺席**(模板整份不在):段名无从派生,判据没有可判对象 → 打印
1895
+ // 「未校验」并放行,退出码不因该判据改变(其余判据照常,此处全绿)。
1896
+ fs.rmSync(path.join(dir, 'flow-kit', 'templates', 'REQUIREMENT.md'), { force: true });
1897
+ fs.rmSync(path.join(dir, 'flow-kit', 'templates', 'TEST.md'), { force: true });
1898
+ acWrite(acCriteria(['AC-1']), ['AC-1'], true);
1899
+ const acNoTemplate = runGuard(['exit', 'verify'], dir);
1900
+ assertExit(acNoTemplate, 0);
1901
+ assertOut(acNoTemplate, '未校验(模板缺席(段名无从派生))');
1902
+ assertNotOut(acNoTemplate, 'AC 覆盖判据无法执行');
1903
+ assertOut(acNoTemplate, 'ALL CHECKS PASSED');
1904
+ // ⑩ 承载段缺席(**文件与模板都在场**,只有验收准则段被删掉)→ 内容不可判,不是「载体缺席」:
1905
+ // 「未校验」只对文件 / 模板根本不在的形态开放,作者自己能删掉的段不能换到放行口。新 change
1906
+ // BLOCKED,且恢复指引必须能照做(补回 `## 验收准则(AC)` 段并给每条 AC 编号)。
1907
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1908
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(AC)\n## 非功能性需求\n');
1909
+ writeFile(dir, 'flow-kit/templates/TEST.md', '# TEST 模板\n\n## 第 1 轮 · 功能测试\n');
1910
+ const requirementWithoutAcceptance = () => [
1911
+ '# REQUIREMENT: AC 覆盖夹具',
1912
+ '',
1913
+ '- **Change ID**: ' + CHANGE_ID,
1914
+ '',
1915
+ '## 用户故事',
1916
+ '',
1917
+ '- **US-1**:作为执行者,我想让 AC 覆盖判据有夹具。',
1918
+ '',
1919
+ '## 非功能性需求',
1920
+ '',
1921
+ '- **性能**: 无',
1922
+ '',
1923
+ ].join('\n');
1924
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md', requirementWithoutAcceptance());
1925
+ const acNoAcceptanceSection = runGuard(['exit', 'verify'], dir);
1926
+ assertExit(acNoAcceptanceSection, 1);
1927
+ assertOut(acNoAcceptanceSection, 'BLOCKED: AC 覆盖判据无法执行');
1928
+ assertOut(acNoAcceptanceSection, '定位不到验收准则段');
1929
+ assertOut(acNoAcceptanceSection, '在 REQUIREMENT.md 里补「## 验收准则(AC)」段');
1930
+ assertOut(acNoAcceptanceSection, '形如 AC-1');
1931
+ assertNotOut(acNoAcceptanceSection, '未校验(REQUIREMENT 无验收准则段)');
1932
+ assertNotOut(acNoAcceptanceSection, '缺 AC 覆盖');
1933
+ // ⑩b 旧 change 走同一份夹具只 WARN(渐进不阻断),该行仍进入既有 WARN COUNT——计数差分
1934
+ // (判别力):把承载段补回来并覆盖后 WARN 消失,计数恰少 1。
1935
+ writeState(dir, acState(false));
1936
+ const acNoAcceptanceOld = runGuard(['exit', 'verify'], dir);
1937
+ assertExit(acNoAcceptanceOld, 0);
1938
+ assertOut(acNoAcceptanceOld, 'WARN: AC 覆盖判据无法执行');
1939
+ assertOut(acNoAcceptanceOld, '(旧 change 渐进不阻断)');
1940
+ assertOut(acNoAcceptanceOld, 'ALL CHECKS PASSED');
1941
+ acWrite(acCriteria(['AC-1']), ['AC-1'], false);
1942
+ const acNoAcceptanceOldFixed = runGuard(['exit', 'verify'], dir);
1943
+ assertExit(acNoAcceptanceOldFixed, 0);
1944
+ assertTrue(warnCountOf(acNoAcceptanceOld) === warnCountOf(acNoAcceptanceOldFixed) + 1,
1945
+ '承载段缺席的 WARN 未计入 WARN COUNT(删段仍静默): 缺段=' + warnCountOf(acNoAcceptanceOld)
1946
+ + ' 补段后=' + warnCountOf(acNoAcceptanceOldFixed));
1947
+ // ⑪ **与入口同一份选段基准**(AC-4 的判别锚):把模板的验收段改名成不含关键词的标题,模板仍在场 ——
1948
+ // 选段只能回落到与 open 出口**同一份**回退基准(TEMPLATE_FALLBACK_SECTION_PATTERNS
1949
+ // 的 requirementAcceptance),于是 verify 出口按入口口径定位到工件的「## 验收准则(AC)」
1950
+ // 段、覆盖判据照常生效。模块内自写一份关键词查找时,这里会得到「未校验」放行——入口按
1951
+ // 回退正则拦、出口按关键词找不到段放行,同一事实两处两判且没有断言能抓到。
1952
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1953
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 用户可接受条件\n## 非功能性需求\n');
1954
+ acWrite(acCriteria(['AC-1', 'AC-2']), ['AC-1'], true);
1955
+ const acRenamedTemplate = runGuard(['exit', 'verify'], dir);
1956
+ assertExit(acRenamedTemplate, 1);
1957
+ assertOut(acRenamedTemplate, 'BLOCKED');
1958
+ assertOut(acRenamedTemplate, '缺 AC 覆盖');
1959
+ assertTrue(acMissingLine(acRenamedTemplate).includes('AC-2'),
1960
+ '模板段名不含关键词时应回落到与入口同一份回退基准并照常点名 AC-2,实际: '
1961
+ + acMissingLine(acRenamedTemplate));
1962
+ assertNotOut(acRenamedTemplate, 'AC 覆盖判据跳过');
1963
+ // ⑫ 选段规则只有一份实现:pickTemplateSection(新入口)与既有的 templateSectionPatterns().pick
1964
+ // 在**同一候选集**上必须给出同一个判据——三件事逐一验证:关键词命中 / 模板在场而关键词不命中
1965
+ // (回退)/ 模板整份缺席(跳过)。任一入口自带一份选段逻辑,三态里至少一态当场分叉。
1966
+ const routing = await import('../lib/guard-routing.mjs');
1967
+ const acceptanceArgs = {
1968
+ keywords: ['验收'],
1969
+ fallback: routing.TEMPLATE_FALLBACK_SECTION_PATTERNS.requirementAcceptance,
1970
+ };
1971
+ const patternShape = (pattern) => (pattern === routing.TEMPLATE_SECTION_SKIP
1972
+ ? 'SKIP'
1973
+ : String(pattern?.source) + '/' + String(pattern?.flags));
1974
+ const pickVersusEntry = async (root, label) => {
1975
+ const viaPick = patternShape((await routing.templateSectionPatterns({ runRoot: root }))
1976
+ .pick('requirement', acceptanceArgs.keywords, acceptanceArgs.fallback));
1977
+ const viaEntry = patternShape(await routing.pickTemplateSection('requirement', { ...acceptanceArgs, runRoot: root }));
1978
+ assertEqual(viaEntry, viaPick, label + ':选段入口与 pick 对同一候选集应给出同一判据');
1979
+ return viaPick;
1980
+ };
1981
+ // (a) 关键词命中(标准模板在场)
1982
+ const hitShape = await pickVersusEntry(dir, '关键词命中');
1983
+ assertTrue(hitShape !== 'SKIP', '模板在场且段名含关键词时应选出真实判据,实际: ' + hitShape);
1984
+ // (b) 回退(模板在场,段名不含关键词)
1985
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1986
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 用户可接受条件\n## 非功能性需求\n');
1987
+ const fallbackShape = await pickVersusEntry(dir, '关键词不命中→回退');
1988
+ assertTrue(fallbackShape === patternShape(acceptanceArgs.fallback),
1989
+ '模板在场而关键词不命中时应回落到与入口同一份回退基准,实际: ' + fallbackShape);
1990
+ // (c) 跳过(模板整份缺席):两个入口都必须返回**同一个**跳过判据
1991
+ const bareRoot = path.join(dir, 'bare-root');
1992
+ fs.mkdirSync(bareRoot, { recursive: true });
1993
+ const skipShape = await pickVersusEntry(bareRoot, '模板整份缺席→跳过');
1994
+ assertTrue(skipShape === 'SKIP', '模板整份缺席时两个入口都应返回同一个跳过判据,实际: ' + skipShape);
1995
+ // 复位模板段名,后续若再扩展本块仍按标准夹具
1996
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
1997
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(AC)\n## 非功能性需求\n');
1998
+ // ⑬ **载体文件被删**不是「没有可判对象」:REQUIREMENT.md / TEST.md 是这个 change 自己的
1999
+ // 载体,作者抬手就能删——把它读成「未校验、放行」正是「删文件换到关掉判据」的写法。
2000
+ // 新 change 必须拦(内容不可判那一支),旧 change 只 WARN 且该行进既有 WARN COUNT。
2001
+ // 载体缺席因此只剩模板缺席一支:模板不是这个 change 的文件,删不掉 change 里的东西来造它。
2002
+ acWrite(acCriteria(['AC-1']), ['AC-1'], true);
2003
+ fs.rmSync(path.join(dir, '.specs', CHANGE_ID, 'REQUIREMENT.md'), { force: true });
2004
+ const acNoRequirement = runGuard(['exit', 'verify'], dir);
2005
+ assertExit(acNoRequirement, 1);
2006
+ assertOut(acNoRequirement, 'BLOCKED: AC 覆盖判据无法执行');
2007
+ assertOut(acNoRequirement, '没有 REQUIREMENT.md');
2008
+ assertOut(acNoRequirement, '恢复: 补回 REQUIREMENT.md');
2009
+ assertNotOut(acNoRequirement, '未校验(REQUIREMENT 缺席)');
2010
+ assertNotOut(acNoRequirement, '缺 AC 覆盖');
2011
+ // ⑬b 旧 change 同形态:WARN 渐进 + 计数差分(补回文件后该 WARN 消失,WARN COUNT 恰少 1)
2012
+ // 模板按登记表的段名书写:AC 判据只在文件在场时读模板,模板段名与登记表不一致会**额外**
2013
+ // 产出一条 TEMPLATE-REGISTRY WARN(只在补回文件那一趟出现),差分因此被它抵消——那条 WARN
2014
+ // 不是本格被测对象,夹具把它消掉,差值才只剩 AC 那一条。
2015
+ writeFile(dir, 'flow-kit/templates/REQUIREMENT.md',
2016
+ '# REQUIREMENT 模板\n\n## 用户故事(User Story)\n## 验收准则(AC)\n## 范围切分\n'
2017
+ + '## 非功能性需求\n## 依赖与假设\n');
2018
+ writeState(dir, acState(false));
2019
+ const acNoRequirementOld = runGuard(['exit', 'verify'], dir);
2020
+ assertExit(acNoRequirementOld, 0);
2021
+ assertOut(acNoRequirementOld, 'WARN: AC 覆盖判据无法执行');
2022
+ assertOut(acNoRequirementOld, '(旧 change 渐进不阻断)');
2023
+ assertOut(acNoRequirementOld, 'ALL CHECKS PASSED');
2024
+ acWrite(acCriteria(['AC-1']), ['AC-1'], false);
2025
+ const acNoRequirementOldFixed = runGuard(['exit', 'verify'], dir);
2026
+ assertExit(acNoRequirementOldFixed, 0);
2027
+ assertTrue(warnCountOf(acNoRequirementOld) === warnCountOf(acNoRequirementOldFixed) + 1,
2028
+ '载体文件被删的 WARN 未计入 WARN COUNT(删文件仍静默): 缺文件=' + warnCountOf(acNoRequirementOld)
2029
+ + ' 补文件后=' + warnCountOf(acNoRequirementOldFixed));
2030
+ // ⑭ **围栏里的示例行不算覆盖**:1.1 矩阵段保留围栏内容(段界要跨围栏),但示例行只是书写
2031
+ // 样例——把 AC-2 / AC-3 写在围栏示例里而真实矩阵只有 AC-1 时,判据必须仍点名缺
2032
+ // AC-2、AC-3(旧实现全段扫编号,示例行把它读成「覆盖了」= 假绿)。
2033
+ acWrite(acCriteria(['AC-1', 'AC-2', 'AC-3']), ['AC-1'], true);
2034
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', acTest(['AC-1']).replace(
2035
+ '| AC-1 | unit | guard-self-test.mjs | ✅ |',
2036
+ '| AC-1 | unit | guard-self-test.mjs | ✅ |\n\n'
2037
+ + '```md\n| AC-2 | unit | 示例行(书写样例,不是覆盖) | ✅ |\n'
2038
+ + '| AC-3 | unit | 示例行(书写样例,不是覆盖) | ✅ |\n```',
2039
+ ));
2040
+ const acFencedExample = runGuard(['exit', 'verify'], dir);
2041
+ assertExit(acFencedExample, 1);
2042
+ assertTrue(acMissingLine(acFencedExample).includes('AC-2、AC-3'),
2043
+ '围栏示例行不得算作覆盖(AC-2 / AC-3 只在示例块里),实际: ' + acMissingLine(acFencedExample));
2044
+ assertOut(acFencedExample, '在 TEST.md 的 1.1 测试矩阵为这些 AC 补行');
2045
+ // ⑭b 声明侧同口径:验收段里只在围栏示例中出现编号 ≠ 声明了准则——围栏里的是示例,
2046
+ // 「有验收准则却没有任何编号」照旧属内容不可判(假绿的另一面)。
2047
+ acWrite([
2048
+ '```md',
2049
+ '### AC-1 · 示例写法(不是本 change 的准则)',
2050
+ '```',
2051
+ '',
2052
+ '- 本段只有书写样例,真实准则一条都没编号。',
2053
+ ].join('\n'), ['AC-1'], true);
2054
+ const acFencedDeclaration = runGuard(['exit', 'verify'], dir);
2055
+ assertExit(acFencedDeclaration, 1);
2056
+ assertOut(acFencedDeclaration, 'BLOCKED: AC 覆盖判据无法执行');
2057
+ assertOut(acFencedDeclaration, '没有 AC-N 编号');
2058
+ assertNotOut(acFencedDeclaration, '缺 AC 覆盖');
706
2059
  },
707
2060
  },
708
2061
 
@@ -710,7 +2063,7 @@ export const ENTRIES = [
710
2063
  // 子断言:归档缺 KNOWN-ISSUES.md(遗留清单,协议 required 产物)→ BLOCKED
711
2064
  {
712
2065
  name: '22 exit archive WARN:CHANGELOG.md 表格日期非倒序',
713
- run: (dir) => {
2066
+ run: async (dir) => {
714
2067
  const st = baseState('archive');
715
2068
  st.evidence.archive = { summary: 'archived' };
716
2069
  writeState(dir, st);
@@ -733,6 +2086,72 @@ export const ENTRIES = [
733
2086
  const resMissing = runGuard(['exit', 'archive'], dir);
734
2087
  assertExit(resMissing, 1);
735
2088
  assertOut(resMissing, 'missing Output Schema artifacts');
2089
+
2090
+ // 子断言:结构化预检的**时点分界**。归档产出(.specs/archive/<日期>-<change-id>/)是归档动作
2091
+ // 自己的产出位置——归档前连 .specs/archive/ 都不存在,把它报成缺件、还让人「先按上述路径创建」,
2092
+ // 给的是归档前不可能执行的指令(完整出口照旧要求它:那是归档动作做完后的判据,由上面的
2093
+ // resMissing 守住)。预检只报「归档执行后才会生成」,且报文里的通配符(路径判据语法)必须换成
2094
+ // 占位说明——照字面去建带 `*` 的目录同样不可执行。
2095
+ fs.rmSync(path.join(dir, '.specs/archive'), { recursive: true, force: true });
2096
+ const preflightArchive = runGuard(['exit', 'archive', '--preflight'], dir);
2097
+ assertExit(preflightArchive, 0);
2098
+ assertOut(preflightArchive, '归档执行后才会生成');
2099
+ assertOut(preflightArchive, '.specs/archive/<日期>-' + CHANGE_ID + '/KNOWN-ISSUES.md');
2100
+ assertNotOut(preflightArchive, 'BLOCKED');
2101
+ assertNotOut(preflightArchive, '先按上述路径创建缺失工件');
2102
+ const wildcardLines = preflightArchive.output.split('\n').filter((line) => line.includes('*'));
2103
+ assertTrue(wildcardLines.length === 0,
2104
+ '预检报文不得打印含通配符的路径(判据语法漏进了给人读的路径):\n' + wildcardLines.join('\n'));
2105
+ // 反过度修复锚:同一夹具下空 change 的 open 预检照旧 BLOCK——放宽只落在「归档产出」这一类路径上,
2106
+ // 其他节点声明的缺件判据一字不动。
2107
+ const preflightOpen = runGuard(['exit', 'open', '--preflight'], dir);
2108
+ assertExit(preflightOpen, 1);
2109
+ assertOut(preflightOpen, 'BLOCKED: 节点 open 的声明工件缺失');
2110
+
2111
+ // 子断言:声明不完整(required 但未声明 paths)——同一份协议,**两侧都阻断且说同一句**。
2112
+ // 这种声明的特殊处:没有路径可判存在性,也没有可创建的落点,所以报文只能是「修协议」这一条
2113
+ // 可执行的下一步;修复前两侧对同一份协议给出两种说法(预检跳过、出口永久算缺件),正是这里
2114
+ // 要钉死的东西。期望措辞从唯一出处取(guard-routing 的 unspecifiedPathsNotice),不在测试里
2115
+ // 另写一份。
2116
+ const { unspecifiedPathsNotice } = await import('../lib/guard-routing.mjs');
2117
+ const incompleteSchema = 'fixture.unspecified-paths.v1';
2118
+ const incompleteArtifact = 'no-paths';
2119
+ const builtinForIncomplete = JSON.parse(
2120
+ fs.readFileSync(path.join(SCRIPTS_DIR, '..', 'reference', 'workflow-protocol.json'), 'utf8'));
2121
+ writeFile(dir, 'reference/custom-unspecified-paths.json', JSON.stringify({
2122
+ ...builtinForIncomplete,
2123
+ nodes: builtinForIncomplete.nodes.map((node) => (node.id === 'archive'
2124
+ ? { ...node, outputSchemas: [...node.outputSchemas, incompleteSchema] }
2125
+ : node)),
2126
+ outputSchemas: [...builtinForIncomplete.outputSchemas, {
2127
+ id: incompleteSchema,
2128
+ description: '声明不完整的必需产物(required 但未声明 paths)',
2129
+ artifacts: [{ id: incompleteArtifact, kind: 'file', required: true, pathBase: 'specs-root' }],
2130
+ evidence: [],
2131
+ }],
2132
+ }, null, 2) + '\n');
2133
+ const incompleteProtocolPath = path.join(dir, 'reference', 'custom-unspecified-paths.json');
2134
+ // 归档自身的两件必需产物先补齐:单变量 = 唯一缺陷就是那件「声明不完整」的产物。
2135
+ writeFile(dir, '.specs/archive/foo-' + CHANGE_ID + '/KNOWN-ISSUES.md', '# KNOWN-ISSUES\n\n无遗留问题\n');
2136
+ const exitIncomplete = runGuard(['exit', 'archive', '--protocol', incompleteProtocolPath], dir);
2137
+ assertExit(exitIncomplete, 1);
2138
+ const preflightIncomplete = runGuard(
2139
+ ['exit', 'archive', '--preflight', '--protocol', incompleteProtocolPath], dir);
2140
+ assertExit(preflightIncomplete, 1);
2141
+ const expectedNotice = unspecifiedPathsNotice(incompleteSchema, incompleteArtifact);
2142
+ const noticeLineOf = (view) => view.output.split('\n')
2143
+ .find((line) => line.includes('协议声明不完整:')) ?? null;
2144
+ const exitNotice = noticeLineOf(exitIncomplete);
2145
+ const preflightNotice = noticeLineOf(preflightIncomplete);
2146
+ assertTrue(exitNotice !== null && exitNotice.endsWith(expectedNotice),
2147
+ '出口侧应给「声明不完整」那一句(指向修协议,而不是让人去创建一个没有路径的文件):\n'
2148
+ + String(exitNotice) + '\n期望以: ' + expectedNotice + ' 结尾');
2149
+ assertTrue(preflightNotice !== null && preflightNotice.endsWith(expectedNotice),
2150
+ '预检侧应与出口侧同一句(两侧各写一份措辞正是本次要消灭的分叉):\n'
2151
+ + String(preflightNotice) + '\n期望以: ' + expectedNotice + ' 结尾');
2152
+ // 两侧都不给做不到的指令:没有路径可建,就不许出现「按上述路径创建」。
2153
+ assertNotOut(preflightIncomplete, '先按上述路径创建缺失工件');
2154
+ assertNotOut(exitIncomplete, '按上述路径创建');
736
2155
  },
737
2156
  },
738
2157
 
@@ -786,9 +2205,28 @@ export const ENTRIES = [
786
2205
  writeFile(dir, '.specs/compose-demo/notes.md', '# notes\n');
787
2206
  writeFile(dir, '.specs/compose-demo/T01-SUMMARY.md', '# T01-SUMMARY\n');
788
2207
  writeFile(dir, '.specs/compose-demo/verdict.md', '# verdict\n');
2208
+ const viewBytes = readStateBytes(dir);
789
2209
  const res = runState(['status', '--protocol', custom], dir);
790
2210
  assertExit(res, 0);
791
2211
  assertOut(res, '"currentNode": "codereview"');
2212
+ // 当前节点 brainstorm 从未 exit(completedNodes 空、evidence 空,只是产物齐全)→ next 的节点
2213
+ // 顺序门禁会 BLOCKED 且不打印 NODE。共享视图必须报同一事实:routeNode=null,并在 ROUTE: 行
2214
+ // 写明原因——修复前这里报产物推导的 codereview,正是「status 叫人去一个 next 不会去的地方」。
2215
+ assertOut(res, '"routeNode": null');
2216
+ const routeLine = res.output.split('\n').find((line) => line.startsWith('ROUTE: '));
2217
+ if (!routeLine) throw new Error('status 缺少 ROUTE: 诊断行\n实际输出:\n' + res.output);
2218
+ for (const token of ['route=null', 'next 将 BLOCKED', '疑似未 exit 节点 brainstorm']) {
2219
+ if (!routeLine.includes(token)) {
2220
+ throw new Error('节点顺序门禁态 ROUTE: 行缺少 ' + token + ':' + routeLine);
2221
+ }
2222
+ }
2223
+ assertStateBytesUnchanged(dir, viewBytes, 'status 的「next 将 BLOCKED」判定是只读视图(不得写 state)');
2224
+ // 同一 state 下 next 的实际行为——视图给出的节点必须是 next 会打印的那个:BLOCKED、不打印 NODE。
2225
+ const nextView = runState(['next', '--protocol', custom], dir);
2226
+ assertExit(nextView, 1);
2227
+ assertOut(nextView, 'BLOCKED: 疑似未 exit 节点 brainstorm');
2228
+ assertNotOut(nextView, 'NODE: ');
2229
+ assertStateBytesUnchanged(dir, viewBytes, 'next 的顺序门禁 BLOCK 在任何写盘之前');
792
2230
  },
793
2231
  },
794
2232