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
@@ -103,18 +103,26 @@ function customProtocol() {
103
103
  };
104
104
  }
105
105
 
106
- // 含 requiredSkillCalls 的变体:brainstorm 带 main scope 绑定(协调者加载 → 需 skill-load 声明标记)
107
- function customProtocolWithSkillCall() {
106
+ // 协议变体(绑定面三态;`enforcement` 是出口覆盖判据的单一开关):
107
+ // · base —— 无 requiredSkillCalls:节点没有声明义务;
108
+ // · skill —— main scope 绑定、未登记等级:声明照旧由出口代记(required-skill 条目自动补写);
109
+ // · guarded —— main scope 绑定 + enforcement='guarded':该技能必须自己有一条声明标记。
110
+ function customProtocolVariant(variant) {
108
111
  const p = customProtocol();
109
- p.nodes[0].requiredSkillCalls = [{ skill: 'flow-comet-brainstorm', scope: 'main' }];
112
+ if (variant === 'skill') {
113
+ p.nodes[0].requiredSkillCalls = [{ skill: 'flow-comet-brainstorm', scope: 'main' }];
114
+ } else if (variant === 'guarded') {
115
+ p.nodes[0].requiredSkillCalls = [{ skill: 'flow-comet-brainstorm', scope: 'main', enforcement: 'guarded' }];
116
+ } else if (variant !== 'base') {
117
+ throw new Error('未知协议变体: ' + variant);
118
+ }
110
119
  return p;
111
120
  }
112
121
 
113
- // 写入自定义协议文件,返回绝对路径
114
- function writeCustomProtocol(dir, withSkillCall = false) {
115
- const proto = withSkillCall ? customProtocolWithSkillCall() : customProtocol();
116
- const file = path.join(dir, withSkillCall ? 'custom-protocol-skill.json' : 'custom-protocol.json');
117
- fs.writeFileSync(file, JSON.stringify(proto, null, 2) + '\n', 'utf8');
122
+ // 写入自定义协议文件(变体见上),返回绝对路径
123
+ function writeCustomProtocol(dir, variant = 'base') {
124
+ const file = path.join(dir, variant === 'base' ? 'custom-protocol.json' : 'custom-protocol-' + variant + '.json');
125
+ fs.writeFileSync(file, JSON.stringify(customProtocolVariant(variant), null, 2) + '\n', 'utf8');
118
126
  return file;
119
127
  }
120
128
 
@@ -148,9 +156,9 @@ export const ENTRIES = [
148
156
  },
149
157
 
150
158
  {
151
- name: 'E2 自定义协议:声明机制与出口全链路(含技能绑定)',
159
+ name: 'E2 自定义协议:声明机制与出口全链路(含技能绑定与 guarded 覆盖)',
152
160
  run: (dir) => {
153
- const custom = writeCustomProtocol(dir, true);
161
+ const custom = writeCustomProtocol(dir, 'skill');
154
162
  assertExit(runState(['init', 'cp-skill', '--protocol', custom], dir), 0);
155
163
  const env = { FLOW_COMET_PROTOCOL: custom };
156
164
  // 自定义节点 skill-load 声明(协议节点集合动态校验)
@@ -179,6 +187,40 @@ export const ENTRIES = [
179
187
  const envLoad = runGuard(['exit', 'bogus'], dir, env);
180
188
  assertExit(envLoad, 1);
181
189
  assertOut(envLoad, 'Unknown workflow Node');
190
+
191
+ // guarded 变体的出口覆盖判据(自定义协议路径):协议把绑定登记为 enforcement='guarded' 时,
192
+ // 出口要求该技能**各自**有声明标记——同节点上已声明的另一个技能不构成覆盖(record 只校验载荷里
193
+ // 出现的 required-skill 条目,覆盖判据要的是「每个 guarded 绑定各有一条标记」)。
194
+ // 对照:同一夹具换成未登记等级的绑定(skill 变体)时零该技能声明照样放行——等级是唯一开关。
195
+ const guardedProtocol = writeCustomProtocol(dir, 'guarded');
196
+ const guardedEnv = { FLOW_COMET_PROTOCOL: guardedProtocol };
197
+ assertExit(runState(['init', 'cp-guard', '--protocol', guardedProtocol], dir), 0);
198
+ assertExit(runState(['skill-load', 'brainstorm', 'flow-comet-tdd'], dir, guardedEnv), 0);
199
+ assertExit(runState(['record', 'brainstorm', '{"summary":"brainstorm done"}'], dir, guardedEnv), 0);
200
+ writeFile(dir, '.specs/cp-guard/notes.md', '# notes\n');
201
+ assertExit(runGuard(['entry', 'brainstorm'], dir, guardedEnv), 0);
202
+ const uncovered = runGuard(['exit', 'brainstorm'], dir, guardedEnv);
203
+ assertExit(uncovered, 1);
204
+ assertOut(uncovered, '缺协议声明标记');
205
+ assertOut(uncovered, '缺必需技能声明: flow-comet-brainstorm');
206
+ // 补上该绑定自己的标记 → 同一出口放行
207
+ assertExit(runState(['skill-load', 'brainstorm', 'flow-comet-brainstorm'], dir, guardedEnv), 0);
208
+ const covered = runGuard(['exit', 'brainstorm', '--apply'], dir, guardedEnv);
209
+ assertExit(covered, 0);
210
+ assertOut(covered, 'ALL CHECKS PASSED');
211
+ assertNotOut(covered, '缺协议声明标记');
212
+ // 对照:未登记等级的同一绑定 → 只声明别的技能也放行(覆盖判据不在这条路径上生效)
213
+ const plainProtocol = writeCustomProtocol(dir, 'skill');
214
+ const plainEnv = { FLOW_COMET_PROTOCOL: plainProtocol };
215
+ assertExit(runState(['init', 'cp-plain', '--protocol', plainProtocol], dir), 0);
216
+ assertExit(runState(['skill-load', 'brainstorm', 'flow-comet-tdd'], dir, plainEnv), 0);
217
+ assertExit(runState(['record', 'brainstorm', '{"summary":"brainstorm done"}'], dir, plainEnv), 0);
218
+ writeFile(dir, '.specs/cp-plain/notes.md', '# notes\n');
219
+ assertExit(runGuard(['entry', 'brainstorm'], dir, plainEnv), 0);
220
+ const ungated = runGuard(['exit', 'brainstorm'], dir, plainEnv);
221
+ assertExit(ungated, 0);
222
+ assertOut(ungated, 'ALL CHECKS PASSED');
223
+ assertNotOut(ungated, '缺协议声明标记');
182
224
  },
183
225
  },
184
226
 
@@ -8,7 +8,7 @@ import path from 'path';
8
8
  import { execFileSync, spawnSync } from 'child_process';
9
9
  import { createHash } from 'crypto';
10
10
  import { assertExit, assertNotOut, assertOut, runGuard, runHandoff, runState, writeFile, writeState } from '../lib/test-helpers.mjs';
11
- import { CHANGE_ID, assertNodeLine, assertNotNodeLine, completeFixTaskAndRecord, driveThroughDesign, execSummaryFixture, fixBatchReviewDoc, fixBatchTaskText, fullContract, parseStatusOutput, readStateBytes, readStateFile, writeIntakeArtifacts } from '../lib/system-fixtures.mjs';
11
+ import { archiveRecordJson, CHANGE_ID, assertNodeLine, assertNotNodeLine, completeFixTaskAndRecord, driveThroughDesign, execSummaryFixture, fixBatchReviewDoc, fixBatchTaskText, fullContract, parseStatusOutput, readStateBytes, readStateFile, writeIntakeArtifacts } from '../lib/system-fixtures.mjs';
12
12
 
13
13
  // 同夹具的「段内大写 Z 早于方法名」变体(真实机检标记形态):6 维自查段体首行是含大写 Z 的机检
14
14
  // 标记说明,方法声明行在其后。段尾判定若把大写 Z 当串尾(惰性段体在段内首个 Z 处提前收尾),
@@ -107,13 +107,15 @@ function replanTaskText(options = {}) {
107
107
  function seedExecuteEntryState(dir, taskText) {
108
108
  driveThroughDesign(dir);
109
109
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', taskText);
110
- assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md'], dir), 0);
110
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-plan', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
111
+ // 协议 plan.requiredSkillCalls = flow-comet-task(guarded):出口覆盖判据要求该技能也有标记
112
+ assertExit(runState(['skill-load', 'plan', 'flow-comet-task', '--prompt', 'flow-kit/prompts/3-task.md', '--templates', 'TASK.md'], dir), 0);
111
113
  assertExit(runState(['record', 'plan', '{"summary":"plan done"}'], dir), 0);
112
114
  assertExit(runGuard(['entry', 'plan'], dir), 0);
113
115
  const planExit = runGuard(['exit', 'plan', '--apply'], dir);
114
116
  assertExit(planExit, 0);
115
117
  assertNodeLine(planExit, 'execute');
116
- assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md'], dir), 0);
118
+ assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir), 0);
117
119
  assertExit(runState(['record', 'execute', '{"summary":"implementation recorded"}'], dir), 0);
118
120
  assertExit(runGuard(['entry', 'execute'], dir), 0);
119
121
  }
@@ -146,18 +148,27 @@ export const ENTRIES = [
146
148
  assertExit(runState(['init', CHANGE_ID], dir), 0);
147
149
  assertExit(runState(['skill-load', 'verify', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir), 0);
148
150
  writeFile(dir, '.specs/' + CHANGE_ID + '/UAT.md', '# UAT\n\n通过\n');
151
+ // verify 出口先跑 AC 覆盖判据(新 change):夹具给出可判的最小一对——准则清单 + 1.1 矩阵行
152
+ // (矩阵行写在围栏外;围栏里的编号只是书写样例,不计覆盖)。本项被测的是验证命令的真实执行,
153
+ // 不是 AC 覆盖,故这里只补输入面、不动任何断言。
154
+ writeFile(dir, '.specs/' + CHANGE_ID + '/REQUIREMENT.md',
155
+ '# REQUIREMENT\n\n- **Change ID**: ' + CHANGE_ID
156
+ + '\n\n## 用户故事\n\n- US-1:作为执行者,我想让验证命令真的被执行。'
157
+ + '\n\n## 验收准则(AC)\n\n- **AC-1**: Given 夹具前置 When 夹具动作 Then 夹具结果\n');
158
+ const acCoverageBlock = '## 第 1 轮 · 功能测试\n\n### 1.1 测试矩阵(AC → 用例)\n\n'
159
+ + '| AC | 类型 | 用例文件 / UAT | 状态 |\n|---|---|---|---|\n| AC-1 | unit | baseline.js | ✅ |\n\n';
149
160
  assertExit(runState(['record', 'verify', '{"summary":"verified"}'], dir), 0);
150
161
  const st = readStateFile(dir);
151
162
  st.currentNode = 'verify';
152
163
  writeState(dir, st);
153
164
  // ① 快速命令 → 出口通过
154
- writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令\n\n```bash\nnode -e "1"\n```\n');
165
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n' + acCoverageBlock + '## 验证命令\n\n```bash\nnode -e "1"\n```\n');
155
166
  assertExit(runGuard(['entry', 'verify'], dir), 0);
156
167
  const pass = runGuard(['exit', 'verify'], dir);
157
168
  assertExit(pass, 0);
158
169
  assertOut(pass, 'ALL CHECKS PASSED');
159
170
  // ② 缺省超时(未设 env)保持大值:耗时命令通过
160
- writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n## 验证命令\n\n```bash\nnode -e "setTimeout(()=>{}, 1500)"\n```\n');
171
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n' + acCoverageBlock + '## 验证命令\n\n```bash\nnode -e "setTimeout(()=>{}, 1500)"\n```\n');
161
172
  const defaultTimeout = runGuard(['exit', 'verify'], dir);
162
173
  assertExit(defaultTimeout, 0);
163
174
  assertOut(defaultTimeout, 'ALL CHECKS PASSED');
@@ -175,7 +186,7 @@ export const ENTRIES = [
175
186
  throw new Error('exit verify 失败计数未按 change 写入: ' + JSON.stringify(stTimed.verifyFailuresByChange));
176
187
  }
177
188
  // ④ 无验证命令 → 拦截(严格版要求)
178
- writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n无验证命令段。\n');
189
+ writeFile(dir, '.specs/' + CHANGE_ID + '/TEST.md', '# TEST\n\n' + acCoverageBlock + '无验证命令段。\n');
179
190
  const noCmd = runGuard(['exit', 'verify'], dir);
180
191
  assertExit(noCmd, 1);
181
192
  assertOut(noCmd, 'BLOCKED: TEST.md 需声明 ## 验证命令 段');
@@ -191,7 +202,8 @@ export const ENTRIES = [
191
202
  const st0 = readStateFile(dir);
192
203
  st0.currentNode = 'archive';
193
204
  writeState(dir, st0);
194
- assertExit(runState(['record', 'archive', '{"summary":"archived"}'], dir), 0);
205
+ // 归档提名随证据落盘(该 change 无任务 SUMMARY → 扫描 0 份,理由写明无候选入库)
206
+ assertExit(runState(['record', 'archive', archiveRecordJson('archived')], dir), 0);
195
207
  // ① 未移动(无归档目录)→ 出口拦截(缺归档产物)
196
208
  assertExit(runGuard(['entry', 'archive'], dir), 0);
197
209
  const blocked = runGuard(['exit', 'archive'], dir);
@@ -229,13 +241,14 @@ export const ENTRIES = [
229
241
  // 遗留清单(协议 required 产物——随目录移动进归档)
230
242
  writeFile(dir, '.specs/arch-mk/KNOWN-ISSUES.md', '# KNOWN-ISSUES\n\n无遗留问题\n');
231
243
  // 归档前声明标记(open + archive 节点)
232
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
244
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
233
245
  assertExit(runState(['skill-load', 'archive', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir), 0);
234
246
  // 节点推进到归档(模拟前序节点出口已完成的状态)
235
247
  const st0 = readStateFile(dir);
236
248
  st0.currentNode = 'archive';
237
249
  writeState(dir, st0);
238
- assertExit(runState(['record', 'archive', '{"summary":"archived"}'], dir), 0);
250
+ // 归档提名随证据落盘(该 change 无任务 SUMMARY → 扫描 0 份,理由写明无候选入库)
251
+ assertExit(runState(['record', 'archive', archiveRecordJson('archived')], dir), 0);
239
252
  // 移动(标记随目录进入归档路径)
240
253
  fs.mkdirSync(path.join(dir, '.specs', 'archive'), { recursive: true });
241
254
  fs.renameSync(path.join(dir, '.specs', 'arch-mk'), path.join(dir, '.specs', 'archive', '2026-08-11-arch-mk'));
@@ -260,7 +273,7 @@ export const ENTRIES = [
260
273
  writeFile(dir, 'flow-kit/prompts/0-change.md', '# 阶段 0 · CHANGE\n\n## 角色\n\n你是 Changeer。\n');
261
274
  writeFile(dir, 'flow-kit/prompts/7-integration.md', '# 阶段 7 · INTEGRATION\n\n## 角色\n\n你是 Integrationer。\n');
262
275
  // 手动 skill-load(活动路径标记,随目录移动进归档)
263
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
276
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
264
277
  assertExit(runState(['skill-load', 'archive', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir), 0);
265
278
  // 推进到 archive
266
279
  const st0 = readStateFile(dir);
@@ -590,6 +603,8 @@ export const ENTRIES = [
590
603
  }
591
604
  // 源节点(verify)出口真实重跑:验证命令落盘副作用 + 推进 archive
592
605
  assertExit(runState(['skill-load', 'verify', 'flow-comet-verify', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
606
+ // 协议 verify.requiredSkillCalls = flow-comet-integration(guarded):同一份协议文件、另一个技能面
607
+ assertExit(runState(['skill-load', 'verify', 'flow-comet-integration', '--prompt', 'flow-kit/prompts/7-integration.md'], dir, env), 0);
593
608
  assertExit(runState(['record', 'verify', '{"summary":"回源复验完成"}'], dir, env), 0);
594
609
  assertExit(runGuard(['entry', 'verify'], dir, env), 0);
595
610
  const verifyExit = runGuard(['exit', 'verify', '--apply'], dir, env);
@@ -209,8 +209,10 @@ const RAW_ENTRIES = [
209
209
  run: (dir) => {
210
210
  gitInit(dir);
211
211
  assertExit(runState(['init', CHANGE_ID, '--init-skip'], dir), 0);
212
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
213
- assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md'], dir), 0);
212
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
213
+ // open 该读两份协议、协议声明两个必需技能:出口覆盖判据要求全部声明,夹具两条都写下
214
+ assertExit(runState(['skill-load', 'open', 'flow-comet-requirement', '--prompt', 'flow-kit/prompts/1-requirement.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
215
+ assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md', '--templates', 'DESIGN.md'], dir), 0);
214
216
  writeIntakeArtifacts(dir);
215
217
  // ① entry open 记录进入标记
216
218
  assertExit(runGuard(['entry', 'open'], dir), 0);
@@ -354,15 +354,22 @@ export const ENTRIES = [
354
354
  name: 'M4 ui-design 门真实链路:entry design → 缺件 BLOCK → 补件·声明 → exit --apply 放行',
355
355
  run: (dir) => {
356
356
  assertExit(runState(['init', CHANGE_ID], dir), 0);
357
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
358
- writeIntakeArtifacts(dir);
359
- fs.appendFileSync(path.join(dir, '.specs', CHANGE_ID, 'CHANGE.md'),
360
- '\n## 视觉调性(Visual Tone)\n\n现代、克制的工具型界面。\n');
357
+ // 夹具根的模板:适用性判据的「视觉调性」段名从 CHANGE 模板派生——模板缺席时门按 C9 显式
358
+ // 「未校验(模板缺失)」跳过(降级路径由 TA-21 覆盖),本项要测的是门本身,故模板必须在场。
359
+ // 段形只登记本项工件实际写出的段:模板是段形权威,多写一段就会让出口先被结构门拦下,
360
+ // 测不到 ui-design 门(CHANGE 见 writeIntakeArtifacts,DESIGN 见下方夹具)。
361
+ writeFile(dir, 'flow-kit/templates/CHANGE.md', '# CHANGE 模板(夹具)\n\n## Why(为什么做)\n\n## 视觉调性(前端项目必填)\n');
362
+ writeFile(dir, 'flow-kit/templates/DESIGN.md', '# DESIGN 模板(夹具)\n\n## 0. 技术栈选定\n\n## 1. 决策清单\n');
363
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
364
+ // open 该读两份协议、协议声明两个必需技能:出口覆盖判据要求全部声明,夹具两条都写下
365
+ assertExit(runState(['skill-load', 'open', 'flow-comet-requirement', '--prompt', 'flow-kit/prompts/1-requirement.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
366
+ // 前端判据要的是「视觉调性段在场且未标不适用」:intake 夹具直接写实质调性(不追加同名段)。
367
+ writeIntakeArtifacts(dir, CHANGE_ID, { visualTone: '现代、克制的工具型界面。' });
361
368
  assertExit(runState(['record', 'open', '{"summary":"intake complete"}'], dir), 0);
362
369
  assertExit(runGuard(['entry', 'open'], dir), 0);
363
370
  assertExit(runGuard(['exit', 'open', '--apply'], dir), 0);
364
371
 
365
- assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md'], dir), 0);
372
+ assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md', '--templates', 'DESIGN.md'], dir), 0);
366
373
  writeFile(dir, '.specs/' + CHANGE_ID + '/DESIGN.md',
367
374
  '# DESIGN\n\n- **Change ID**: ' + CHANGE_ID + '\n\n## 0. 技术栈选定\n\nNode.js(ESM)\n\n## 决策清单\n\n- [ ] 循环路由\n');
368
375
  assertExit(runState(['record', 'design', '{"summary":"design done"}'], dir), 0);
@@ -375,13 +382,14 @@ export const ENTRIES = [
375
382
  assertOut(blocked, '恢复: 补 .specs/' + CHANGE_ID + '/UI-DESIGN.md');
376
383
 
377
384
  // 恢复:补工件 + 真实 skill-load 声明(出口不再自动补写该绑定)→ 出口放行并落状态
385
+ // 工件形态按模板:标题 = `# UI Design: <项目名>`(登记表 titleForm),不是「# UI-DESIGN」。
378
386
  writeFile(dir, '.specs/' + CHANGE_ID + '/UI-DESIGN.md',
379
- '# UI-DESIGN\n\n## 1. 设计 token\n\n- 主色 `oklch(0.6 0.1 250)`\n');
387
+ '# UI Design: 夹具项目\n\n## 1. 设计 token\n\n- 主色 `oklch(0.6 0.1 250)`\n');
380
388
  const undeclared = runGuard(['exit', 'design'], dir);
381
389
  assertExit(undeclared, 1);
382
390
  assertOut(undeclared, 'required-skill:design.flow-comet-ui-design');
383
391
  assertOut(undeclared, '不再由出口自动补写');
384
- assertExit(runState(['skill-load', 'design', 'flow-comet-ui-design', '--prompt', 'flow-kit/prompts/2a-ui-design.md'], dir), 0);
392
+ assertExit(runState(['skill-load', 'design', 'flow-comet-ui-design', '--prompt', 'flow-kit/prompts/2a-ui-design.md', '--templates', 'DESIGN.md'], dir), 0);
385
393
  assertExit(runState(['record', 'design',
386
394
  '{"summary":"design done with ui-design","completedChecks":["required-skill:design.flow-comet-design","required-skill:design.flow-comet-ui-design"]}'], dir), 0);
387
395
  const passed = runGuard(['exit', 'design', '--apply'], dir);
@@ -393,16 +401,16 @@ export const ENTRIES = [
393
401
  // ① fail-open 反向控制:段内自然句子「不适用于暗色主题…」不是结构形态 → 仍判前端、缺件 BLOCKED;
394
402
  // ② 结构形态(`适用性` 标签的字段值位)→ 可见跳过 + 命中片段回显,且不要求工件与该声明。
395
403
  const nfChange = CHANGE_ID + '-nf';
396
- const nfChangeFile = path.join(dir, '.specs', nfChange, 'CHANGE.md');
397
404
  assertExit(runState(['init', nfChange, '--init-skip'], dir), 0);
398
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
399
- writeIntakeArtifacts(dir, nfChange);
400
- fs.appendFileSync(nfChangeFile,
401
- '\n## 视觉调性(Visual Tone)\n\n不适用于暗色主题,本 change 仅覆盖浅色分支。\n');
405
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
406
+ // 第二个 change 的 open 同样要覆盖两份协议与两个必需技能(出口覆盖判据按节点核对)
407
+ assertExit(runState(['skill-load', 'open', 'flow-comet-requirement', '--prompt', 'flow-kit/prompts/1-requirement.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
408
+ // 段内自然句子(非结构形态)→ 前端判据不认,仍判前端;写在同一段里,不追加同名段。
409
+ writeIntakeArtifacts(dir, nfChange, { visualTone: '不适用于暗色主题,本 change 仅覆盖浅色分支。' });
402
410
  assertExit(runState(['record', 'open', '{"summary":"intake complete"}'], dir), 0);
403
411
  assertExit(runGuard(['entry', 'open'], dir), 0);
404
412
  assertExit(runGuard(['exit', 'open', '--apply'], dir), 0);
405
- assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md'], dir), 0);
413
+ assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md', '--templates', 'DESIGN.md'], dir), 0);
406
414
  writeFile(dir, '.specs/' + nfChange + '/DESIGN.md',
407
415
  '# DESIGN\n\n- **Change ID**: ' + nfChange + '\n\n## 0. 技术栈选定\n\nNode.js(ESM)\n\n## 决策清单\n\n- [ ] 循环路由\n');
408
416
  assertExit(runState(['record', 'design', '{"summary":"design done"}'], dir), 0);
@@ -0,0 +1,163 @@
1
+ // items/n.mjs — 条目分区:N 组条目(加载链声明集合比对 / 安装器降级口径的 L2 真实命令)
2
+ //
3
+ // 数据层约定:同 items/a.mjs 头注(只承载 ENTRIES;夹具从 lib/system-fixtures.mjs 取;组文件之间零 import)。
4
+ //
5
+ // 组界:本组承接「模板权威」批次的加载链与降级面——它们此前只有 L1 场景或只有获取点断言:
6
+ // · 加载链的**声明集合比对**(多写 / 漏写 / 错名 / 允许集内的可选项)走真实 skill-load / record 命令;
7
+ // · 安装器在「同名目录已存在 / 上游克隆已就位」两种真实目录形态下的**降级结论**(含不出现通知的反向)。
8
+
9
+ import fs from 'fs';
10
+ import path from 'path';
11
+ import { spawnSync } from 'child_process';
12
+ import { assertExit, assertNotOut, assertOut, assertTrue, installSkillTreeCopy, runPrintedCommand, runState, writeState } from '../lib/test-helpers.mjs';
13
+ import { CHANGE_ID, SCRIPTS_DIR, applyDistributionSurface, readStateFile } from '../lib/system-fixtures.mjs';
14
+
15
+ const DESIGN_SKILL_ARGS = ['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md'];
16
+
17
+ const RAW_ENTRIES = [
18
+ // ---------- N. 加载链:模板声明集合比对 ----------
19
+
20
+ // 声明集合判据 = required ⊆ declared ⊆ required ∪ optional(design 的 required=DESIGN、optional=UI-DESIGN)。
21
+ // 四个负例分别打「多写(允许集外)」「漏写(空清单)」「错名(拼错)」「缺声明(整项没写)」,
22
+ // 旧 change 同形只 WARN——新 change 的 fail-closed 与旧 change 的渐进放行必须在同一条命令上分开。
23
+ {
24
+ name: 'N1 加载链声明集合:多写/漏写/错名/缺声明对 BLOCKED,允许集内可选项放行,旧 change 同形 WARN',
25
+ run: (dir) => {
26
+ assertExit(runState(['init', CHANGE_ID, '--init-skip'], dir), 0);
27
+
28
+ // ① 允许集内正例:DESIGN(required)+ UI-DESIGN(optional)→ 通过并落标记
29
+ const optionalDeclared = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGN.md,UI-DESIGN.md'], dir);
30
+ assertExit(optionalDeclared, 0);
31
+ assertOut(optionalDeclared, 'SKILL-LOAD: design flow-comet-design');
32
+ const markerPath = path.join(dir, '.specs', CHANGE_ID, '.skill-loads', 'design-flow-comet-design.json');
33
+ const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
34
+ if (!Array.isArray(marker.templates) || marker.templates.join(',') !== 'DESIGN,UI-DESIGN') {
35
+ throw new Error('声明标记应如实记录声明的模板清单(去掉 .md 后缀),实际: ' + JSON.stringify(marker.templates));
36
+ }
37
+
38
+ // ② 多写:允许集外的模板(TASK)→ BLOCKED,并回显「怎么重新声明」的可执行命令(模板与提示词
39
+ // 同一次声明:命令必须带 --prompt,否则照抄重跑会把同一标记的 protocol 覆写成 null)
40
+ const extra = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGN.md,TASK.md'], dir);
41
+ assertExit(extra, 1);
42
+ assertOut(extra, 'BLOCKED');
43
+ assertOut(extra, '多写/错名: TASK');
44
+ assertOut(extra, '映射要求: DESIGN');
45
+ // 命令形态与守卫侧的派生同形(同一装配):脚本路径 + 该节点全部 --prompt + 模板全清单 + 协议
46
+ // 上下文,四个面一次给全;且**照抄能跑通**——解析打印文本 → 真执行,标记的 protocol 必须仍在,
47
+ // 否则下一次 exit 会被「缺协议声明标记」拦下(恢复步骤自己弄坏协议声明)。
48
+ assertNotOut(extra, '--prompt <');
49
+ const declareLine = (extra.output.match(/^\s*(node "[^"]+" skill-load design [^\n]+)$/m) || [])[1];
50
+ assertTrue(typeof declareLine === 'string',
51
+ 'BLOCKED 报文应给出可照抄的重新声明命令(node "<脚本路径>" skill-load …):\n' + extra.output);
52
+ for (const fragment of [
53
+ '--prompt flow-kit/prompts/2-design.md',
54
+ '--templates DESIGN.md',
55
+ '--protocol "reference/workflow-protocol.json"',
56
+ ]) {
57
+ assertTrue(declareLine.includes(fragment),
58
+ '重新声明命令缺 ' + fragment + '(命令与判据不是同一份形态): ' + declareLine);
59
+ }
60
+ // 真跑一遍:打印的是权威源设计形态(.claude/skills/…),按安装布局把技能树复制进夹具才可解析。
61
+ installSkillTreeCopy(dir, path.join('.claude', 'skills'));
62
+ const replayed = runPrintedCommand(declareLine, dir, { FLOW_COMET_RUN_ROOT: dir, FLOW_COMET_PROTOCOL: '' });
63
+ assertTrue(replayed.status === 0,
64
+ '照抄的重新声明命令跑不通\n 命令: ' + declareLine + '\n exit ' + replayed.status + '\n' + replayed.output);
65
+ const redeclaredMarker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
66
+ assertTrue(redeclaredMarker.protocol === '2-design.md',
67
+ '照抄重新声明命令后 protocol 不应变成 null,实际: ' + JSON.stringify(redeclaredMarker.protocol));
68
+
69
+ // ③ 漏写:显式空清单(--templates=)→ BLOCKED 且点名漏掉的必填项
70
+ const missing = runState([...DESIGN_SKILL_ARGS, '--templates='], dir);
71
+ assertExit(missing, 1);
72
+ assertOut(missing, 'BLOCKED');
73
+ assertOut(missing, '漏写: DESIGN');
74
+
75
+ // ④ 错名:拼错(DESIGNS)→ 同时报漏写与错名(错名不是「多写」的另一种说法,两条都要出声)
76
+ const typo = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGNS.md'], dir);
77
+ assertExit(typo, 1);
78
+ assertOut(typo, '漏写: DESIGN');
79
+ assertOut(typo, '多写/错名: DESIGNS');
80
+
81
+ // ⑤ 缺声明:整项不写 --templates → 新 change 同样 BLOCKED(「没写」不等于「零模板」)
82
+ const undeclared = runState(DESIGN_SKILL_ARGS, dir);
83
+ assertExit(undeclared, 1);
84
+ assertOut(undeclared, '模板声明缺失');
85
+
86
+ // ⑥ 旧 change 同形:同一条「多写」声明只 WARN 且照常落标记(渐进兼容——旧项目不可能一夜补齐)
87
+ const legacyState = readStateFile(dir);
88
+ delete legacyState.newChange;
89
+ writeState(dir, legacyState);
90
+ const legacy = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGN.md,TASK.md'], dir);
91
+ assertExit(legacy, 0);
92
+ assertOut(legacy, 'WARN');
93
+ assertNotOut(legacy, 'BLOCKED');
94
+ const legacyMarker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
95
+ if (legacyMarker.at === undefined || legacyMarker.templates.join(',') !== 'DESIGN,TASK') {
96
+ throw new Error('旧 change 的 WARN 路径应照常写标记(记录真实声明),实际: ' + JSON.stringify(legacyMarker));
97
+ }
98
+ },
99
+ },
100
+
101
+ // ---------- N. 安装器:flow-kit 降级结论 ----------
102
+
103
+ // 降级口径 = 「未校验(模板缺失)」:获取点给命令、进程结尾给结论(影响 / 原因 / 修复)。
104
+ // 两条真实目录形态都必须跑:同名非克隆目录(跳过,不改动)与上游克隆已就位(不挂通知)——
105
+ // 只断言前者会让「无条件打印通知」的实现照样通过。
106
+ {
107
+ name: 'N2 安装器降级口径:同名目录在已跳过时结尾给影响/原因/修复,上游克隆就位时不出现通知',
108
+ surface: '安装器源码(scripts/prepare-env.mjs)与 flow-kit 获取链路仅权威源侧在场',
109
+ run: (dir) => {
110
+ const repoRoot = path.resolve(SCRIPTS_DIR, '..', '..', '..', '..');
111
+ const installer = path.join(repoRoot, 'scripts', 'prepare-env.mjs');
112
+ if (!fs.existsSync(installer)) throw new Error('缺少 prepare-env.mjs');
113
+ const runInstall = (target) => {
114
+ const res = spawnSync(process.execPath, [installer, '--target', target, '--platform', 'claude-code'], {
115
+ cwd: repoRoot, encoding: 'utf8', timeout: 180000,
116
+ });
117
+ return { status: res.status, output: String(res.stdout ?? '') + String(res.stderr ?? '') };
118
+ };
119
+
120
+ // ① 降级态:目标目录预置同名 flow-kit 目录(非上游克隆)→ 跳过 + 手动指引 + 结尾三行结论
121
+ const degradedTarget = path.join(dir, 'n2-degraded');
122
+ fs.mkdirSync(path.join(degradedTarget, 'flow-kit'), { recursive: true });
123
+ const degraded = runInstall(degradedTarget);
124
+ assertExit(degraded, 0); // 降级不改变退出码:安装器其余职责照常完成
125
+ assertOut(degraded, '目录存在但非上游克隆,已跳过');
126
+ assertOut(degraded, '未校验(模板缺失)');
127
+ assertOut(degraded, '影响: 各节点出口输出');
128
+ assertOut(degraded, '原因: flow-kit/templates 未就位');
129
+ // 修复行不许把「重跑」当成对已存在目录的修复——目录在但归属无法确认时,重跑会落回同一条
130
+ // 跳过分支;须先移走/处理该目录或按手动步骤补齐,再重跑。
131
+ assertOut(degraded, '修复: 先移走或处理现有 flow-kit/ 目录');
132
+ assertOut(degraded, '按上方手动获取指引补齐,再重跑本安装器');
133
+ assertNotOut(degraded, '修复: 网络可用时重跑本安装器');
134
+ assertOut(degraded, '手动获取指引: git clone');
135
+ // 非破坏:预置目录原样保留(安装器绝不改动已有目录)
136
+ if (!fs.existsSync(path.join(degradedTarget, 'flow-kit'))) {
137
+ throw new Error('安装器不应删除已存在的 flow-kit 目录');
138
+ }
139
+
140
+ // ② 反向:上游克隆就位(origin 指向上游)→ 走「只读比对」分支,不挂降级通知
141
+ const upstreamTarget = path.join(dir, 'n2-upstream');
142
+ const cloneDir = path.join(upstreamTarget, 'flow-kit');
143
+ fs.mkdirSync(cloneDir, { recursive: true });
144
+ const git = (args) => spawnSync('git', ['-C', cloneDir, ...args], { encoding: 'utf8', timeout: 60000 });
145
+ if (spawnSync('git', ['init', '-q', cloneDir], { encoding: 'utf8' }).status !== 0) {
146
+ throw new Error('夹具构造失败:git init 未成功');
147
+ }
148
+ if (git(['remote', 'add', 'origin', 'https://github.com/rihebty/flow-kit.git']).status !== 0) {
149
+ throw new Error('夹具构造失败:git remote add 未成功');
150
+ }
151
+ if (git(['-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'snapshot']).status !== 0) {
152
+ throw new Error('夹具构造失败:git commit 未成功');
153
+ }
154
+ const clean = runInstall(upstreamTarget);
155
+ assertExit(clean, 0);
156
+ assertOut(clean, '已有 flow-kit(HEAD=');
157
+ assertNotOut(clean, '未校验(模板缺失)');
158
+ assertNotOut(clean, '非上游克隆');
159
+ },
160
+ },
161
+ ];
162
+
163
+ export const ENTRIES = RAW_ENTRIES.map(applyDistributionSurface);