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
@@ -21,6 +21,7 @@ import os from 'os';
21
21
  import { execFileSync, spawnSync } from 'child_process';
22
22
  import { fileURLToPath } from 'url';
23
23
  import { assertExit, assertOut, copyTreePortable, runGuard, runState, writeFile, writeState } from './test-helpers.mjs';
24
+ import { NODE_ARTIFACT_TEMPLATES } from '../protocol-utils.mjs';
24
25
 
25
26
  // 路径推导基准:技能包 scripts/ 目录(与套件入口同基准)
26
27
  export const SCRIPTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -48,9 +49,16 @@ export function gitBranch(root) {
48
49
  }
49
50
 
50
51
 
51
- // open 阶段工件(CHANGE 含 Why;REQUIREMENT 含 用户故事 + 验收准则——通过出口校验的完整形态)
52
- export function writeIntakeArtifacts(root, changeId = CHANGE_ID) {
53
- writeFile(root, '.specs/' + changeId + '/CHANGE.md', '# CHANGE\n\n- **Change ID**: ' + changeId + '\n\n## Why(为什么做)\n\n变更目标。\n');
52
+ // open 阶段工件(CHANGE 含 Why;REQUIREMENT 含 用户故事 + 验收准则——通过出口校验的完整形态)。
53
+ // 「视觉调性」是 CHANGE 模板的条件段且新 change 要求在场:夹具按其结构形态标注「不适用」
54
+ //(独立行 + 理由),使前端判据稳定地判为非前端——不写这段会让 ui-design 门对新 change 报「段缺席」。
55
+ // visualTone 覆盖该段正文:需要判为「前端」的夹具(或需要构造段内自然句子负例的夹具)**改这一段**,
56
+ // 不要另追加第二个「视觉调性」段——同名段重复时判据取首段,追加对首段没有影响。
57
+ export const DEFAULT_VISUAL_TONE = '不适用(夹具:后端任务,无用户可见界面)。';
58
+
59
+ export function writeIntakeArtifacts(root, changeId = CHANGE_ID, { visualTone = DEFAULT_VISUAL_TONE } = {}) {
60
+ writeFile(root, '.specs/' + changeId + '/CHANGE.md', '# CHANGE\n\n- **Change ID**: ' + changeId
61
+ + '\n\n## Why(为什么做)\n\n变更目标。\n\n## 视觉调性\n\n' + visualTone + '\n');
54
62
  writeFile(root, '.specs/' + changeId + '/REQUIREMENT.md', '# REQUIREMENT\n\n- **Change ID**: ' + changeId + '\n\n## 用户故事(User Story)\n\n用户需求。\n\n## 验收准则(AC)\n\n- 通过标准\n');
55
63
  }
56
64
 
@@ -72,6 +80,20 @@ export function fullContract(commitHash, taskId) {
72
80
  // 仓库本地验证工具执行(仅主仓存在、不随克隆分发;副本上文件缺失自动跳过):
73
81
  // 返回 { status, output }(spawnSync 原始结果 output 是数组,统一拼接成字符串供断言)
74
82
 
83
+ // archive 记录的证据 JSON:含归档提名三要素(扫描份数 / 提名编号 / 无提名理由)。新 change 的 archive
84
+ // 出口会核对 evidence.lessonsNomination——夹具只写 summary 会被提名门拦下,掩盖各条目真正被测的
85
+ // 归档/路由判据。summaryIds = 该夹具已写入的 `*-SUMMARY.md` 任务号(扫描份数按此对账,不另抄数字)。
86
+ export function archiveRecordJson(summary, summaryIds = []) {
87
+ return JSON.stringify({
88
+ summary,
89
+ lessonsNomination: {
90
+ scanned: summaryIds.length,
91
+ nominated: [],
92
+ reasonIfNone: '夹具:本 change 无沉淀候选入库',
93
+ },
94
+ });
95
+ }
96
+
75
97
  // 多趟链路 SUMMARY 夹具(SUMMARY 模板保真全量满足:标题首行 # SUMMARY: + 首部 4 字段 +
76
98
  // 段序 做了什么→改动文件→verify 输出→6 维自查→越界检查→自检方法;6 维声明 brooks-review)
77
99
  export function execSummaryFixture(taskId) {
@@ -117,6 +139,10 @@ export function execSummaryFixture(taskId) {
117
139
  '',
118
140
  'brooks-review',
119
141
  '',
142
+ '## LESSONS 扫描',
143
+ '',
144
+ '无 active 条目命中(夹具:本任务 write_files 与 .specs/LESSONS.md 关键词行无交集)。',
145
+ '',
120
146
  ].join('\n');
121
147
  }
122
148
 
@@ -219,7 +245,10 @@ export function writeFixBatchFixture(dir, { kind, fixStatus, newChange = true, p
219
245
  export function completeFixTaskAndRecord(dir, env) {
220
246
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', fixBatchTaskText('done'));
221
247
  writeFile(dir, '.specs/' + CHANGE_ID + '/T-FIX-01-SUMMARY.md', execSummaryFixture('T-FIX-01'));
222
- assertExit(runState(['skill-load', 'execute', 'flow-comet-execute', '--prompt', 'flow-kit/prompts/4-dev.md'], dir, env), 0);
248
+ assertExit(runState(['skill-load', 'execute', 'flow-comet-execute', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
249
+ // 协议 execute.requiredSkillCalls = flow-comet-dev(guarded):出口覆盖判据要求该技能也有标记——
250
+ // 只声明实现技能 flow-comet-execute 时覆盖缺口会被拦下(节点实现技能与必需技能是两个声明面)。
251
+ assertExit(runState(['skill-load', 'execute', 'flow-comet-dev', '--prompt', 'flow-kit/prompts/4-dev.md', '--templates', 'SUMMARY.md'], dir, env), 0);
223
252
  const rec = runState(['record', 'execute', '{"summary":"fix batch executed","parallelTakeoverApproved":true}'], dir, env);
224
253
  assertExit(rec, 0);
225
254
  assertOut(rec, 'EVIDENCE: execute');
@@ -285,7 +314,7 @@ function parseExplainSkillLine(value) {
285
314
  function parseExplainOutput(output) {
286
315
  const parsed = {
287
316
  attributes: {}, schemas: [], artifacts: [], evidence: [], guardrails: [], guardrailsNone: false,
288
- skills: [], skillsNone: false, commands: [],
317
+ skills: [], skillsNone: false, templates: [], commands: [],
289
318
  };
290
319
  let schemaIndex = -1;
291
320
  for (const rawLine of String(output).split(/\r?\n/)) {
@@ -313,6 +342,8 @@ function parseExplainOutput(output) {
313
342
  } else if (line.startsWith('REQUIRED-SKILL: ')) {
314
343
  if (value === '(none)') parsed.skillsNone = true;
315
344
  else parsed.skills.push(parseExplainSkillLine(value));
345
+ } else if (/^TEMPLATE(?:(条件模板))?: /.test(line)) {
346
+ parsed.templates.push(line);
316
347
  } else if (line.startsWith('COMMAND ')) parsed.commands.push(line);
317
348
  else throw new Error('explain 输出含未识别的行形态: ' + line);
318
349
  }
@@ -390,7 +421,22 @@ function explainGuardrailAndSkillProblems(node, parsed) {
390
421
  return problems;
391
422
  }
392
423
 
393
- // ⑤ 三条命令:节点 id 与 --apply 形态 + 脚本根形态(三条同根、指向技能包 scripts 目录)+ 脚本
424
+ // ⑤ 模板指针行:内置节点取引擎 C3 映射、自定义协议节点取 node.templates,零模板节点不打印。
425
+ // 期望值在这里**独立构造**(不调 explain 侧的格式化函数):措辞、路径根或 .md 后缀的漂移
426
+ // 才能被这条锥抓到。
427
+ function explainTemplateProblems(node, parsed) {
428
+ const builtin = NODE_ARTIFACT_TEMPLATES[node.id];
429
+ const required = builtin ? builtin.required : (node.templates ?? []);
430
+ const optional = builtin ? (builtin.optional ?? []) : [];
431
+ const expected = [];
432
+ for (const name of required) expected.push('TEMPLATE: flow-kit/templates/' + name + '.md');
433
+ for (const name of optional) expected.push('TEMPLATE(条件模板): flow-kit/templates/' + name + '.md(仅前端 change)');
434
+ if (JSON.stringify(parsed.templates) === JSON.stringify(expected)) return [];
435
+ return ['节点 ' + node.id + ' 的 TEMPLATE 行与节点模板声明不一致: 输出 '
436
+ + JSON.stringify(parsed.templates) + ' / 期望 ' + JSON.stringify(expected)];
437
+ }
438
+
439
+ // ⑥ 三条命令:节点 id 与 --apply 形态 + 脚本根形态(三条同根、指向技能包 scripts 目录)+ 脚本
394
440
  // 路径整体带双引号(含空格的安装根下不被 shell 分词——引号是契约形态的一部分,缺引号即红)。
395
441
  function explainCommandProblems(node, parsed) {
396
442
  const commandPatterns = [
@@ -427,7 +473,7 @@ function explainCommandProblems(node, parsed) {
427
473
  return problems;
428
474
  }
429
475
 
430
- // 逐字段对账(单一实现:真实判据与反向构造探针共用):四类字段 + 三条命令。
476
+ // 逐字段对账(单一实现:真实判据与反向构造探针共用):五类字段 + 三条命令。
431
477
  export function explainContractProblems(protocol, explainOutputs) {
432
478
  const problems = [];
433
479
  const schemaById = new Map((protocol.outputSchemas ?? []).map((schema) => [schema.id, schema]));
@@ -451,6 +497,7 @@ export function explainContractProblems(protocol, explainOutputs) {
451
497
  node.disabled === true ? 'true(该节点在当前协议中被停用)' : null, 'DISABLED');
452
498
  problems.push(...explainSchemaProblems(node, parsed, schemaById));
453
499
  problems.push(...explainGuardrailAndSkillProblems(node, parsed));
500
+ problems.push(...explainTemplateProblems(node, parsed));
454
501
  problems.push(...explainCommandProblems(node, parsed));
455
502
  }
456
503
  return problems;
@@ -544,6 +591,26 @@ export function explainReverseConstructionProblems(dir, protocolDecl, explainOut
544
591
  }
545
592
  }
546
593
  }
594
+ // ⑤ 模板指针行的另一面(不需重跑):真实输出去掉首条 TEMPLATE 行 ⇒ 逐节点必报 TEMPLATE 不一致。
595
+ // 没有这一侧,把模板行从实现里拿掉也能全绿(对账恒真空过)。
596
+ const strippedTemplates = new Map();
597
+ for (const [nodeId, output] of explainOutputs) {
598
+ const lines = String(output).split(/\r?\n/);
599
+ const index = lines.findIndex((line) => line.startsWith('TEMPLATE: '));
600
+ if (index < 0) continue;
601
+ strippedTemplates.set(nodeId, [...lines.slice(0, index), ...lines.slice(index + 1)].join('\n'));
602
+ }
603
+ if (strippedTemplates.size === 0) {
604
+ problems.push('反向构造前提不成立:没有任何节点的 explain 输出含 TEMPLATE: 行(模板指针判据无从判别)');
605
+ } else {
606
+ const templateProblems = explainContractProblems(protocolDecl, new Map([...explainOutputs, ...strippedTemplates]));
607
+ for (const nodeId of strippedTemplates.keys()) {
608
+ if (!templateProblems.some((problem) => problem.includes('节点 ' + nodeId + ' 的')
609
+ && problem.includes('TEMPLATE 行'))) {
610
+ problems.push('反向构造判别力缺失(去掉节点 ' + nodeId + ' 的 TEMPLATE 行未被判不一致)');
611
+ }
612
+ }
613
+ }
547
614
  return problems;
548
615
  }
549
616
 
@@ -570,12 +637,15 @@ export function multiWaveTaskContent(statusMap) {
570
637
  // 新 change 两层加载模型下逐节点 skill-load → record → entry → exit --apply 全程驱动。
571
638
  export function driveThroughDesign(dir) {
572
639
  assertExit(runState(['init', CHANGE_ID], dir), 0);
573
- assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md'], dir), 0);
640
+ assertExit(runState(['skill-load', 'open', 'flow-comet-change', '--prompt', 'flow-kit/prompts/0-change.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
641
+ // open 该读两份协议、协议声明两个必需技能(flow-comet-change / flow-comet-requirement):出口的
642
+ // 覆盖判据要求全部声明——只声明一份时连 design 都推进不到(声明门先拦),前奏形同虚设。
643
+ assertExit(runState(['skill-load', 'open', 'flow-comet-requirement', '--prompt', 'flow-kit/prompts/1-requirement.md', '--templates', 'CHANGE.md,REQUIREMENT.md'], dir), 0);
574
644
  writeIntakeArtifacts(dir);
575
645
  assertExit(runState(['record', 'open', '{"summary":"intake complete"}'], dir), 0);
576
646
  assertExit(runGuard(['entry', 'open'], dir), 0);
577
647
  assertExit(runGuard(['exit', 'open', '--apply'], dir), 0);
578
- assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md'], dir), 0);
648
+ assertExit(runState(['skill-load', 'design', 'flow-comet-design', '--prompt', 'flow-kit/prompts/2-design.md', '--templates', 'DESIGN.md'], dir), 0);
579
649
  writeFile(dir, '.specs/' + CHANGE_ID + '/DESIGN.md',
580
650
  '# DESIGN\n\n- **Change ID**: ' + CHANGE_ID + '\n\n## 0. 技术栈选定\n\nNode.js(ESM)\n\n## 决策清单\n\n- [ ] 循环路由\n');
581
651
  assertExit(runState(['record', 'design', '{"summary":"design done"}'], dir), 0);
@@ -1,14 +1,23 @@
1
1
  // task-graph.mjs — 任务与协议图的底层共享判定(单一权威实现)
2
2
  // 承载:① 协议节点顺序 / 启用 / 任务文件路径(route · protocolNodeEnabled · protocolTaskFilePath ·
3
- // EXECUTE_FAMILY_NODE_IDS);② 任务依赖解析与依赖图(taskDependencyEligibility · analyzeDependencyGraph);
3
+ // EXECUTE_FAMILY_NODE_IDS);② 任务依赖解析与依赖图(taskDependencyEligibility · analyzeDependencyGraph ·
4
+ // taskWaveLevels 依赖层级);
4
5
  // ③ 并行写冲突检测三族(findParallelWriteConflicts 及其构件);④ 任务集签名与版本语义 ·
5
6
  // history 事件归属 · change 名形态 · 修复任务族文本谓词;⑤ 任务块 7 字段集合(TASK7_REQUIRED)。
6
7
  // 纯判定:只读 TASK.md 文本、协议对象与 state.history,无 console 输出、无 process.exit、无 state 写入。
7
- // 依赖方向:本模块不 import 其他 lib 模块(lib 层最底层)——入口与兄弟模块单向依赖本模块。
8
+ // 依赖方向:只依赖叶子模块(lessons-hits 的条目边界、section-body 的段界)——入口与兄弟模块单向
9
+ // 依赖本模块,不出现反向边。
8
10
  import { promises as fs } from 'fs';
9
11
  import path from 'path';
10
12
  import { createHash } from 'crypto';
11
13
  import { taskBlocks, taskOpeningAttrs } from '../task-parsing.mjs';
14
+ // 写面元素(`<write_files>`…`</write_files>`,元素名大小写无关)与条目边界(剥注释 → 行切 → 分号
15
+ // 容错切 → trim → 滤空)都取 lib/lessons-hits.mjs 的唯一实现:本模块只剩「路径归一」这一层自己的
16
+ // 语义(见 normalizeTaskPath),不自带第二份元素提取或切分。
17
+ import { taskWriteFilesById, writeFilesEntries } from './lessons-hits.mjs';
18
+ // 段界(同级标题 / 围栏 / 分隔线 / 文末)取 lib/section-body.mjs 的唯一实现:修复段的段体此前自带一份
19
+ // 「按行找下一个 `## `」的扫描,围栏代码块里的 `## ` 会把段体截断。
20
+ import { sectionBody } from './section-body.mjs';
12
21
 
13
22
  // 任务块 7 字段集合(单一权威):plan 出口的 TASK 完整性门禁与执行期 `replan` 的重签判据共用本常量。
14
23
  // `replan` 是执行期唯一允许修订任务集的通道,两侧判据必须同源——任何一侧另写一份字面集合,都会在
@@ -162,24 +171,22 @@ export function normalizeHeading(raw) {
162
171
  }
163
172
 
164
173
  // 修复段正文切片:首个同级(##)标题命中 → 返回标题行之后、下一个同级标题(或 EOF)之前的正文;
165
- // 无命中标题 → null。只认二级标题(### 不闭合本段);CRLF / LF 归一后按行定位。
174
+ // 无命中标题 → null。只认二级标题(### 不闭合本段)。段界(含围栏同步)由 lib/section-body.mjs
175
+ // 单点决定,这里只表达自己的差异——标题按共享归一后比较(「Fix 任务(来自 REVIEW / INTEGRATION)」
176
+ // 「## Fix 任务 ##」等写法命中同一段),且**不以分隔线结束**(修复段内允许 `---` 分节,历史语义)。
166
177
  function fixSectionBody(taskContent, fixSectionTitle) {
167
- const lines = String(taskContent ?? '').replace(/\r\n?/g, '\n').split('\n');
168
178
  const wanted = normalizeHeading(fixSectionTitle);
169
179
  if (wanted === '') return null;
170
- let start = -1;
171
- for (let i = 0; i < lines.length; i += 1) {
172
- const m = lines[i].match(/^##\s+(.+?)\s*$/);
173
- if (!m) continue;
174
- const heading = normalizeHeading(m[1]);
175
- if (heading === wanted || heading.startsWith(wanted)) { start = i; break; }
176
- }
177
- if (start < 0) return null;
178
- let end = lines.length;
179
- for (let i = start + 1; i < lines.length; i += 1) {
180
- if (/^##\s/.test(lines[i])) { end = i; break; }
181
- }
182
- return lines.slice(start + 1, end).join('\n');
180
+ return sectionBody(
181
+ taskContent,
182
+ (heading) => {
183
+ // 只认二级标题起段(### 不闭合本段,也不在这里起段——历史语义)
184
+ if (heading.level !== 2) return false;
185
+ const normalized = normalizeHeading(heading.text);
186
+ return normalized === wanted || normalized.startsWith(wanted);
187
+ },
188
+ { level: 2, endOnSeparator: false },
189
+ );
183
190
  }
184
191
 
185
192
  // 修复任务族 id 前缀(唯一谓词的 id 边界,全模块只此一处定义):含尾连字符——形似编号(前缀
@@ -260,6 +267,40 @@ export function analyzeDependencyGraph(blocks) {
260
267
  return { ids, depsById, missing, cyclic, cycleIds };
261
268
  }
262
269
 
270
+ // ---------- 依赖层级(波次投影的层级求值 · 单一权威) ----------
271
+ // 层级定义:level(task) = 1 + max(level(dep)),无依赖 = 1(依赖链的最大深度)。「波次 = 依赖层级
272
+ // 的投影」这一判据(plan 出口 / replan 重校,两处同源调用)消费本函数,不在判据侧自算——层级是
273
+ // 同一份依赖数据的第二次求值,两处各算一遍必然分叉。
274
+ // 输入 = <task> 块数组(与 analyzeDependencyGraph 同源解析),输出 Map<id, level>。
275
+ // 依赖解析复用 analyzeDependencyGraph 的 depsById(依赖文本解析单一权威,不另起第二份正则);
276
+ // 引用不存在的依赖不计入层级(其合法性由依赖图判据负责),环上的任务不产出层级(本函数只求层级,
277
+ // 不承担合法性判定——依赖环 / 缺失依赖由 analyzeDependencyGraph 的消费方先行拦截)。
278
+ export function taskWaveLevels(blocks) {
279
+ const { ids, depsById } = analyzeDependencyGraph(blocks);
280
+ const levels = new Map();
281
+ const resolving = new Set();
282
+ const resolveLevel = (id) => {
283
+ const known = levels.get(id);
284
+ if (known !== undefined) return known;
285
+ if (resolving.has(id)) return null; // 环:该链无解,本 id 不产出层级
286
+ resolving.add(id);
287
+ let deepest = 0;
288
+ let solvable = true;
289
+ for (const dep of depsById.get(id) ?? []) {
290
+ if (!ids.has(dep)) continue;
291
+ const depLevel = resolveLevel(dep);
292
+ if (depLevel === null) { solvable = false; break; }
293
+ if (depLevel > deepest) deepest = depLevel;
294
+ }
295
+ resolving.delete(id);
296
+ if (!solvable) return null;
297
+ levels.set(id, deepest + 1);
298
+ return deepest + 1;
299
+ };
300
+ for (const id of ids) resolveLevel(id);
301
+ return levels;
302
+ }
303
+
263
304
  // ---------- 并行文件依赖检测(单源:plan 出口门禁与 replan 重校共用) ----------
264
305
  // 解析 TASK.md 的任务 read/write_files 声明,分三族返回:
265
306
  // ① writeConflicts(写写强判):本趟可运行的 parallel=pending 任务间 write∩write 非空——同波次
@@ -317,14 +358,14 @@ function normalizeTaskPath(raw) {
317
358
  return out.join('/');
318
359
  }
319
360
 
320
- // 路径解析与既有自动解析同源:剥 HTML 注释 → 换行切分 → 分号二次切分 → trim → 滤空 → 归一。
361
+ // 路径解析:入参是**已提取的**写面元素原文(元素提取与条目边界都取 lib/lessons-hits.mjs 的唯一实现
362
+ // ——taskWriteFilesById + writeFilesEntries;与 handoff 的提交子集校验、plan 出口的伪并行启发式
363
+ // 同一份:同一份写面在三处被切成不同条目集、或在元素名的大小写上分叉时,「谁越界」「哪一对并行
364
+ // 任务重叠」会互相矛盾)。本函数只在条目之上叠加本模块自己的归一(normalizeTaskPath)。
321
365
  // 按声明实际内容解析,不做扩展名白名单过滤——txt/log/无扩展名路径同等检出(链式重命名的 .txt
322
366
  // 事故面闭合)。族①②③共用本实现,不另起第二份。
323
367
  function parsePaths(matchText) {
324
- return String(matchText ?? '')
325
- .replace(/<!--[\s\S]*?-->/g, '')
326
- .trim().split(/\s*\n\s*/).map((l) => l.trim()).filter(Boolean)
327
- .flatMap((l) => l.split(';')).map((l) => l.trim()).filter(Boolean)
368
+ return writeFilesEntries(matchText)
328
369
  .map(normalizeTaskPath)
329
370
  .filter((p) => p !== null && p !== '');
330
371
  }
@@ -374,11 +415,18 @@ export function collectPathOverlaps(leftPaths, rightPaths) {
374
415
  }
375
416
 
376
417
  // 第三族(同文件跨任务且无依赖路径)计算——本模块具名纯函数:输入任务块 / 依赖图 / 既有族去重键,
377
- // 输出冲突对数组({ a, b, files });无 fs / console / process.exit,不改任何入参。
418
+ // 输出 { conflicts, isOverlappingPair }——conflicts 是冲突对明细({ a, b, files },报告面用),
419
+ // isOverlappingPair 是**任务对键集合上的成员判定**(谓词)。任务对键的形态只在 taskPairKey 表达一次:
420
+ // 消费方(wave-projection 的 [P] 判据)要的是「这一对是否写面重叠」,拿到的因此是判定而不是键形态——
421
+ // 两端各算一次键时,形态一旦漂移(换分隔符 / 换定序)键就不相等,补集会静默失效(写面重叠的一对被
422
+ // 当成「本可并行」)。无 fs / console / process.exit,不改任何入参。
378
423
  // taskContent 与 allBlocks 须同源(taskContent = 产出 allBlocks 的 TASK.md 文本)——修复任务族
379
424
  // 谓词需要全文以定位修复段(段标题取该谓词的缺省回退常量,与 fixTaskClassifier 的缺省一致)。
380
425
  export function collectCrossTaskConflicts({ taskContent = '', allBlocks = [], depsById = new Map(), excludedPairKeys = new Set() } = {}) {
381
426
  const isFixTask = fixTaskClassifier(taskContent);
427
+ // 写面元素(键 = 任务 id)取 lib/lessons-hits.mjs 的唯一提取:元素名大小写无关与 7 字段门的在场
428
+ // 判定同口径——大小写敏感的副本会让混合写法的任务在这里判「没有写面」,从而整对掉出本族。
429
+ const writeFaces = taskWriteFilesById(taskContent);
382
430
  const reachCache = new Map();
383
431
  const reachableFrom = (id) => {
384
432
  if (!reachCache.has(id)) reachCache.set(id, reachableTaskIds(depsById, id));
@@ -388,9 +436,9 @@ export function collectCrossTaskConflicts({ taskContent = '', allBlocks = [], de
388
436
  for (const block of allBlocks) {
389
437
  const attrs = taskOpeningAttrs(block);
390
438
  if (!attrs || !attrs.id || attrs.status === 'done' || isFixTask(block)) continue;
391
- const wf = block.match(/<write_files>([\s\S]*?)<\/write_files>/);
392
- if (!wf) continue;
393
- const writes = new Set(parsePaths(wf[1]));
439
+ const element = writeFaces.get(attrs.id);
440
+ if (element === undefined) continue;
441
+ const writes = new Set(parsePaths(element));
394
442
  if (writes.size === 0) continue;
395
443
  participants.push({ id: attrs.id, writes });
396
444
  }
@@ -405,7 +453,8 @@ export function collectCrossTaskConflicts({ taskContent = '', allBlocks = [], de
405
453
  conflicts.push({ a: participants[i].id, b: participants[j].id, files: overlap });
406
454
  }
407
455
  }
408
- return conflicts;
456
+ const pairKeys = new Set(conflicts.map((conflict) => taskPairKey(conflict.a, conflict.b)));
457
+ return { conflicts, isOverlappingPair: (a, b) => pairKeys.has(taskPairKey(a, b)) };
409
458
  }
410
459
 
411
460
  export async function findParallelWriteConflicts(changeDir) {
@@ -413,6 +462,9 @@ export async function findParallelWriteConflicts(changeDir) {
413
462
  let text;
414
463
  try { text = await fs.readFile(taskFile, 'utf8'); } catch { return { writeConflicts: [], readWarnings: [], crossTaskConflicts: [] }; }
415
464
  const allBlocks = taskBlocks(text);
465
+ // 写面元素(键 = 任务 id)取 lib/lessons-hits.mjs 的唯一提取(元素名大小写无关):大小写敏感的副本
466
+ // 会让混合写法的任务在这里判「没有写面」,同波并行写同一路径的竞态因此漏拦。
467
+ const writeFaces = taskWriteFilesById(text);
416
468
  // 依赖资格收窄:仅统计「本趟可运行」的并行任务——deps ⊆ doneIds;等待后续趟次的并行任务
417
469
  // (依赖未满足)与已交付任务不参与同趟冲突判定,使 A→B 同写路径的跨趟合法计划不再被首趟误拦
418
470
  // (与路由谓词同一口径)。依赖文本解析与资格判定一律走 taskDependencyEligibility——本函数不再
@@ -430,13 +482,13 @@ export async function findParallelWriteConflicts(changeDir) {
430
482
  for (const b of blocks) {
431
483
  const a = taskOpeningAttrs(b);
432
484
  if (!a || !a.id) continue;
433
- const wf = b.match(/<write_files>([\s\S]*?)<\/write_files>/);
485
+ const element = writeFaces.get(a.id);
434
486
  const rf = b.match(/<read_files>([\s\S]*?)<\/read_files>/);
435
- if (!wf && !rf) continue;
487
+ if (element === undefined && !rf) continue;
436
488
  perTask.push({
437
489
  id: a.id,
438
490
  deps: new Set(taskDependencyEligibility(b).deps),
439
- writes: new Set(parsePaths(wf && wf[1])),
491
+ writes: new Set(parsePaths(element)),
440
492
  reads: new Set(parsePaths(rf && rf[1])),
441
493
  });
442
494
  }
@@ -461,11 +513,12 @@ export async function findParallelWriteConflicts(changeDir) {
461
513
  // 全在该纯函数内,此处不内联第二份。
462
514
  const writePairKeys = new Set(writeConflicts.map((c) => taskPairKey(c.a, c.b)));
463
515
  const { depsById } = analyzeDependencyGraph(allBlocks);
516
+ // 只取说明面(明细):键集合与判定留在纯函数里,本函数不另算一份键。
464
517
  const crossTaskConflicts = collectCrossTaskConflicts({
465
518
  taskContent: text,
466
519
  allBlocks,
467
520
  depsById,
468
521
  excludedPairKeys: writePairKeys,
469
- });
522
+ }).conflicts;
470
523
  return { writeConflicts, readWarnings, crossTaskConflicts };
471
524
  }
@@ -24,6 +24,11 @@ import {
24
24
  writeFile,
25
25
  makeTmp as sharedMakeTmp,
26
26
  } from './test-helpers.mjs';
27
+ import {
28
+ declarationSkillTargets,
29
+ guardedDeclarationSkills,
30
+ nodePromptFiles,
31
+ } from '../protocol-utils.mjs';
27
32
 
28
33
  // 本模块位于 `<技能包>/scripts/lib/` ⇒ 脚本目录是它的上一级;技能树内所有兄弟脚本路径
29
34
  // (GUARD / STATE / HOOK / HANDOFF / 侧命令 / 内置协议副本)一律由它拼接,调用面不再各拼一遍。
@@ -45,15 +50,52 @@ export const REPO_ROOT = path.resolve(SCRIPTS_DIR, '..', '..', '..', '..');
45
50
  // 其 .flow-comet/ 只是运行时目录,无 skills/flow-comet/SKILL.md)——与安装器自身判定同判据
46
51
  // (prepare-env.mjs 的 gitignore 纳管跳过分支)。
47
52
  export const AUTHORITATIVE_SOURCE_ANCHOR = path.join(REPO_ROOT, '.flow-comet', 'skills', 'flow-comet', 'SKILL.md');
48
- export function isAuthoritativeSourceRepo() {
49
- return fs.existsSync(AUTHORITATIVE_SOURCE_ANCHOR);
50
- }
51
53
  // 权威源仓库脚本位于仓库根 scripts/prepare-env.mjs;安装副本无此脚本,场景跳过
52
54
  export const PREPARE_ENV = path.join(REPO_ROOT, 'scripts', 'prepare-env.mjs');
53
55
  // 内置协议源文件(packageRoot/reference/):场景复制到 <tmpdir>/reference/ 内(protected-path 要求 runRoot 内)
54
56
  export const BUILTIN_PROTOCOL_SOURCE = path.join(SCRIPTS_DIR, '..', 'reference', 'workflow-protocol.json');
55
57
  export const CHANGE_ID = 'ch';
56
58
 
59
+ // 节点声明标记夹具(唯一构造处):按协议派生「该节点该声明哪些技能」「该节点该读哪些协议文件」,
60
+ // 为每个必需技能写一条 `<node>-<skill>.json` 标记——每条的 protocols 都覆盖该节点**全部**协议文件,
61
+ // 等价于一次带多个 `--prompt` 的真实 skill-load(真实流程里协调者声明、record 自动补写,夹具直接
62
+ // 写 state 时这两步都不发生,必须由夹具补上同一份事实)。
63
+ //
64
+ // 与被测判据同源(protocol-utils 的 declarationSkillTargets / guardedDeclarationSkills / nodePromptFiles),
65
+ // 不手抄清单:协议面演进时夹具跟着变,不会退化成「夹具写死一份旧清单」。
66
+ //
67
+ // 适用边界(契约,负例不得走这里):
68
+ // · 只写**本节点**的必需标记:其它节点的标记不写——「跨节点标记不算数」仍由显式负例判;
69
+ // · 条件绑定的技能(design 的 flow-comet-ui-design)默认不写(非前端 change 本就不要求声明它);
70
+ // 前端夹具传 `frontend: true`,与其它 guarded 技能同权;
71
+ // · 不写多余标记:不进额外技能、不写额外协议文件清单——「多声明也不顶替缺项」仍由显式负例判;
72
+ // · 声明门自身的负例(目录整体缺席 / 缺某个技能 / 旧单值标记)一律显式删目录或显式写标记,
73
+ // 不走本 helper——否则负例被 helper 补齐后就测不到那道门了。
74
+ export function writeNodeDeclarationMarkers(dir, nodeId, { changeId = CHANGE_ID, frontend = false, skills = null } = {}) {
75
+ const protocol = JSON.parse(fs.readFileSync(SKILL_PROTOCOL_FILE, 'utf8'));
76
+ const node = (protocol.nodes ?? []).find((item) => item && item.id === nodeId);
77
+ if (node === undefined) throw new Error('夹具构造失败:协议里没有节点 ' + nodeId);
78
+ // 目标集与出口覆盖门的取用面同源:`declarationSkillTargets` = guarded 必需技能(条件绑定不在
79
+ // 同步面展开),一个都不剩时退到该节点的实现技能——subagent-execute 这类「技能全划给子代理」
80
+ // 的节点,出口仍要求声明 4-dev.md,声明就挂在实现技能名下(与恢复段打印的命令同一个技能名)。
81
+ // 前端夹具(design 的 ui-design 判据成立)把条件绑定的技能一并声明。
82
+ const targets = skills ?? (frontend
83
+ ? guardedDeclarationSkills(node)
84
+ : declarationSkillTargets(node));
85
+ const files = nodePromptFiles(node);
86
+ for (const skill of targets) {
87
+ writeFile(dir, '.specs/' + changeId + '/.skill-loads/' + nodeId + '-' + skill + '.json',
88
+ JSON.stringify({
89
+ node: nodeId,
90
+ skill,
91
+ protocol: files[0] ?? null,
92
+ protocols: files,
93
+ at: '2026-08-01T00:00:00.000Z',
94
+ }, null, 2) + '\n');
95
+ }
96
+ return targets;
97
+ }
98
+
57
99
  // 组件技能树布局感知(单一来源):本 suite 恒位于 <skillsRoot>/flow-comet/scripts/,
58
100
  // 组件技能(flow-comet-execute / flow-comet-review / flow-comet-verify 等)是 <skillsRoot>
59
101
  // 下的同级目录。权威源 checkout → <root>/.flow-comet/skills/;安装副本 → <目标>/.claude|
@@ -129,7 +171,8 @@ export function runPrepareEnv(args, root, envOverrides = {}) {
129
171
  }
130
172
 
131
173
  // 跑 workflow-state.mjs 的 bridge-check 只读子命令(T05 实现——六判定态健康/文件缺失/
132
- // 未挂载/版本偏斜/重复注册/不适用)。runRoot = cwd = 项目根;协议副本须在 runRoot 内
174
+ // 未挂载/版本偏斜/重复注册/不适用)。运行根由唯一解析模块(run-root.mjs)给定:
175
+ // FLOW_COMET_RUN_ROOT 优先(夹具把该变量与 cwd 一并设为 root);协议副本须在 runRoot 内
133
176
  // (protected-path)——指向运行器已复制到 <root>/reference/ 的内置协议副本
134
177
  // (FLOW_COMET_PROTOCOL env 优先级高于默认,见 protocol-utils resolveProtocol)。
135
178
  export function runBridgeCheck(root, dshHome) {
@@ -405,10 +448,12 @@ export function composeState(overrides = {}) {
405
448
 
406
449
  // 完整 SUMMARY:六段齐全(## verify 输出 / ## 6 维自查 / ## 越界检查 / ## 做了什么 / ## 改动文件 / ## 自检方法)
407
450
  // 6 维自查默认含实质内容且声明 brooks-review;method='' 表示去掉 ## 自检方法 段(旧格式场景)
451
+ // 结构子段与增量段按模板骨架补齐(`### 已知接受 + 理由` / `### 已知小问题` / `## LESSONS 扫描`):
452
+ // 这些 H3/增量段已成为新 change 的必填结构,夹具缺它们会被结构门当成工件缺陷而不是被测行为。
408
453
  export function summaryContent(options = {}) {
409
454
  const sixDim = options.sixDim !== undefined
410
455
  ? options.sixDim
411
- : '## 6 维自查\n\n- 功能: 通过(brooks-review 已跑)\n- 性能: 无影响\n- 安全: 无影响\n- 兼容: 通过\n- 可观测: 通过\n- 可维护: 通过';
456
+ : '## 6 维自查\n\n- 功能: 通过(brooks-review 已跑)\n- 性能: 无影响\n- 安全: 无影响\n- 兼容: 通过\n- 可观测: 通过\n- 可维护: 通过\n\n### 已知接受 + 理由\n\n- 无(夹具)。\n\n### 已知小问题\n\n- 无(夹具)。';
412
457
  const method = options.method !== undefined ? options.method : '## 自检方法\n\nbrooks-review';
413
458
  return [
414
459
  '# T01-SUMMARY',
@@ -435,12 +480,18 @@ export function summaryContent(options = {}) {
435
480
  '',
436
481
  method,
437
482
  '',
483
+ '## LESSONS 扫描',
484
+ '',
485
+ '无 active 条目命中(夹具)。',
486
+ '',
438
487
  ].join('\n');
439
488
  }
440
489
 
441
490
  // 新 change 模板保真 SUMMARY(M1 严格形态:# SUMMARY: 标题 + 首部 4 字段 + 段序保真——
442
491
  // directOverride 授权约束场景(213~216)用:新 change 出口强制模板保真,旧 summaryContent
443
492
  // 无 # SUMMARY: 标题会被 M1 BLOCKED,不能用于正例/恢复场景)
493
+ // 结构子段(### 已知接受 + 理由 / ### 已知小问题)与增量段(## 自检方法 / ## LESSONS 扫描)按模板
494
+ // 骨架补齐——新 change 缺它们属工件缺陷,不应让夹具自身触发结构门。
444
495
  export function strictSummary(taskId) {
445
496
  return [
446
497
  '# SUMMARY: ' + taskId + ' - 实现 ' + taskId,
@@ -477,6 +528,14 @@ export function strictSummary(taskId) {
477
528
  '- 可观测: 通过',
478
529
  '- 可维护: 通过',
479
530
  '',
531
+ '### 已知接受 + 理由',
532
+ '',
533
+ '- 无(夹具)。',
534
+ '',
535
+ '### 已知小问题',
536
+ '',
537
+ '- 无(夹具)。',
538
+ '',
480
539
  '## 数据库迁移',
481
540
  '',
482
541
  'N/A:本任务无 schema 变更(条件段按模板占位)。',
@@ -505,6 +564,10 @@ export function strictSummary(taskId) {
505
564
  '',
506
565
  'brooks-review',
507
566
  '',
567
+ '## LESSONS 扫描',
568
+ '',
569
+ '无 active 条目命中(夹具)。',
570
+ '',
508
571
  ].join('\n');
509
572
  }
510
573
 
@@ -648,9 +711,13 @@ export const CROSS_TASK_FIX_SECTION_PAIR =
648
711
 
649
712
  // 波次分组场景公共路径:注入 TASK.md → entry plan(记录 enteredNodes,新 change 强制先 entry;
650
713
  // 旧 change 亦先 entry 避免 ENTER WARN 干扰断言)→ exit plan。返回 exit plan 结果。
714
+ // 新 change 的声明标记在这里补齐:真实流程里协调者 entry 时会 skill-load、record 会补写标记,
715
+ // 夹具直接写 state 时这两步都不发生——不补就会被「缺协议声明标记」先拦下,被测的波次判据根本
716
+ // 轮不到说话。声明门自身的负例不走本入口(它们直接 runGuard,且显式删目录/缺标记)。
651
717
  export function runPlanExit(dir, taskContent) {
652
718
  writeFile(dir, '.specs/' + CHANGE_ID + '/TASK.md', '# TASK\n\n## 任务清单\n\n' + taskContent);
653
719
  assertExit(runGuard(['entry', 'plan'], dir), 0);
720
+ writeNodeDeclarationMarkers(dir, 'plan');
654
721
  return runGuard(['exit', 'plan'], dir);
655
722
  }
656
723
 
@@ -733,8 +800,8 @@ export function writeMigratedProjectArtifacts(proj, changeId = MIGRATION_CHANGE)
733
800
  writeFile(proj, '.specs/' + changeId + '/REQUIREMENT.md', '# REQUIREMENT\n\n- **Change ID**: ' + changeId + '\n\n## 用户故事(User Story)\n\nx\n\n## 验收准则(AC)\n\n- y\n');
734
801
  }
735
802
 
736
- // 跑安装副本内的脚本(cwd = 目标项目根——runRoot = process.cwd()):迁移后链路在
737
- // 真实安装形态(而非权威源脚本)上验证
803
+ // 跑安装副本内的脚本(cwd = 目标项目根,FLOW_COMET_RUN_ROOT 设为同一个根):运行根由唯一
804
+ // 解析模块(run-root.mjs)给定(变量优先)——迁移后链路在真实安装形态(而非权威源脚本)上验证
738
805
  export function runInstalled(proj, platformRoot, scriptName, args) {
739
806
  const script = path.join(proj, platformRoot, 'skills', 'flow-comet', 'scripts', scriptName);
740
807
  const res = spawnSync(process.execPath, [script, ...args], {
@@ -918,9 +985,12 @@ export function engineConsumersOf(name, scriptsDir = SCRIPTS_DIR) {
918
985
 
919
986
  // 从具名 import 列表里摘掉一个名字(反向构造用;名前 / 名后 / 唯一项三种位置都覆盖):
920
987
  // 摘掉后消费方仍引用该符号 ⇒ 「未从单源取用」必报。位置感知是必须的——只处理「名字后带逗号」
921
- // 的写法在名字位于列表末位时会静默不改,探针遂退化为恒绿(无判别力)。
988
+ // 的写法在名字位于列表末位时会静默不改;只剩一个名字的列表(`import { NAME } from …`)更没有逗号可
989
+ // 依,整句不动。两种形态下探针都退化为恒绿 / 报「前提失效」,锁的判别力无从证明(L-151)。
922
990
  export function dropNamedImport(text, name) {
923
991
  return String(text)
992
+ // 唯一项:列表里只有这一个名字(单行 / 多行同形;摘完保留 `import {}` 这层语句结构,变异只动名字)。
993
+ .replace(new RegExp('(import\\s*\\{)\\s*\\b' + name + '\\b\\s*(\\})'), '$1$2')
924
994
  .replace(new RegExp('(import\\s*\\{[^}]*?)\\b' + name + '\\b\\s*,\\s*'), '$1')
925
995
  .replace(new RegExp('(import\\s*\\{[^}]*?)\\s*,\\s*\\b' + name + '\\b'), '$1');
926
996
  }
@@ -93,9 +93,9 @@ export function writeState(root, state) {
93
93
  }
94
94
 
95
95
  // ---------- 受控命令(runRoot = 夹具根) ----------
96
- // 约定:spawn 时 cwd = 夹具根(workflow-state / workflow-handoff 的 runRoot 取进程 cwd),
97
- // 并注入 FLOW_COMET_RUN_ROOT 环境变量;同时捕获 stdout + stderr(WARN/BLOCKED 走 stderr,
98
- // 成功退出时只取 stdout 会让 WARN 断言误报)与 exit code,统一返回
96
+ // 约定:spawn 时 cwd = 夹具根,并注入 FLOW_COMET_RUN_ROOT 环境变量——状态命令的运行根由唯一
97
+ // 解析模块取该变量优先、否则进程 cwd,故运行根 = 夹具根;同时捕获 stdout + stderr(WARN/BLOCKED
98
+ // 走 stderr,成功退出时只取 stdout 会让 WARN 断言误报)与 exit code,统一返回
99
99
  // `{ status, output }`(output 为 stdout+stderr 拼接的字符串)。
100
100
  // 统一超时(毫秒):真实命令在冷启动 / 慢文件系统上耗时波动,60s 是两套件既有取值。
101
101
  const COMMAND_TIMEOUT_MS = 60000;
@@ -223,6 +223,63 @@ export function copyTreePortable(src, dst) {
223
223
  }
224
224
  }
225
225
 
226
+ // ---------- 打印出来的命令:解析 → argv → 真实执行 ----------
227
+ //
228
+ // 运行期消息打印的命令是**给执行者照抄的文本**,判据就得真的照着它跑:只断言字面串、再用 harness
229
+ // 的绝对脚本路径去执行,等于从未执行过打印出来的那条文本(形似全绿)。这一组是那条链路的单一
230
+ // 来源:按安装布局复制技能树 → 把打印命令按 shell 语义切成 argv → 真实执行打印文本。两组场景
231
+ //(委托链路 / 声明恢复)都从这里取用——各存一份时,同一条命令会在两组的判据里各自演化,而任一侧
232
+ // 漂移都不会让另一侧变红。
233
+
234
+ // 把套件自身技能树按安装布局复制进夹具(与安装器装出的副本同构):副本自身运行时推导出的是
235
+ // **运行根相对**的脚本目录,打印的命令因此可在夹具内解析——执行的是打印文本,不是 harness 的
236
+ // 绝对脚本路径。installDirRel 是该布局在运行根下的相对目录(夹具构造,不是断言对象)。
237
+ export function installSkillTreeCopy(root, installDirRel) {
238
+ const skillCopy = path.join(root, installDirRel, 'flow-comet');
239
+ copyTreePortable(path.join(SCRIPTS_DIR, '..'), skillCopy);
240
+ return skillCopy;
241
+ }
242
+
243
+ // 打印命令 → argv:按 shell 分词语义处理双引号与单引号(引号内空白不切分,引号本身不进入参数)。
244
+ // 该解析器对「整条路径未加引号」有判别力——缺引号时含空格的路径会被切成多个参数。
245
+ export function splitPrintedCommand(command) {
246
+ const argv = [];
247
+ let current = '';
248
+ let quote = null;
249
+ let started = false;
250
+ for (const ch of command) {
251
+ if (quote) {
252
+ if (ch === quote) { quote = null; continue; }
253
+ current += ch;
254
+ continue;
255
+ }
256
+ if (ch === '"' || ch === "'") { quote = ch; started = true; continue; }
257
+ if (/\s/.test(ch)) {
258
+ if (started) { argv.push(current); current = ''; started = false; }
259
+ continue;
260
+ }
261
+ current += ch;
262
+ started = true;
263
+ }
264
+ if (quote) throw new Error('打印命令的引号未闭合: ' + command);
265
+ if (started) argv.push(current);
266
+ return argv;
267
+ }
268
+
269
+ // 真实执行打印出来的那条命令:解释器名 `node` 换成本进程的 node 可执行文件(PATH 解析不是本锚点
270
+ // 的断言对象,脚本路径与参数才是),其余一律照打印文本解析。
271
+ export function runPrintedCommand(command, root, envOverrides = {}) {
272
+ const argv = splitPrintedCommand(command);
273
+ const interpreter = /^node(\.exe)?$/i.test(argv[0]) ? process.execPath : argv[0];
274
+ const res = spawnSync(interpreter, argv.slice(1), {
275
+ cwd: root,
276
+ env: { ...process.env, ...envOverrides },
277
+ encoding: 'utf8',
278
+ timeout: 60000,
279
+ });
280
+ return { status: res.status ?? 1, output: String(res.stdout || '') + String(res.stderr || '') };
281
+ }
282
+
226
283
  // 最小合法 state(夹具起点):字段与状态校验器的类型要求同形;node 为当前节点。
227
284
  export function baseState(node) {
228
285
  return {