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
@@ -341,6 +341,13 @@ export function validateProtocolSchema(protocol) {
341
341
  if (node.requiredSkillCalls !== undefined && !Array.isArray(node.requiredSkillCalls)) {
342
342
  throw new Error('workflow protocol node.requiredSkillCalls must be an array');
343
343
  }
344
+ // 可选字段 templates(节点 → 产出物模板 basename 清单):缺省 = 该节点不声明模板。
345
+ // 只校验形态(非空字符串数组),集合语义由加载链按 C3/C12 判定——schema 不持有节点映射。
346
+ if (node.templates !== undefined
347
+ && (!Array.isArray(node.templates)
348
+ || node.templates.some((name) => typeof name !== 'string' || name.trim() === ''))) {
349
+ throw new Error('workflow protocol node.templates must be an array of non-empty strings');
350
+ }
344
351
  }
345
352
  if (Object.prototype.hasOwnProperty.call(protocol, 'writeWhitelist')) {
346
353
  checkWriteWhitelistShape(protocol.writeWhitelist);
@@ -397,3 +404,283 @@ export const SKILL_PROTOCOL_FILES = {
397
404
  'flow-comet-review': ['6-review.md'],
398
405
  'flow-comet-integration': ['7-integration.md'],
399
406
  };
407
+
408
+ // ---------- 产出物模板:节点级声明(加载链的单一语义来源) ----------
409
+ //
410
+ // 内置节点的产出物模板映射 = C3 的唯一权威表达处。required = 节点级必需模板;optional 表达「条件模板」
411
+ // (design 的 UI-DESIGN 仅前端 change 适用)。前端判定不在本模块:入口打印的条件行由 guard-uidesign
412
+ // 的 frontendCriterion 决定,避免在协议层写第二份前端判据。
413
+ //
414
+ // 与 reference/artifact-templates.json 的关系:登记表是「模板内容骨架」的权威(file / 段形 / 指纹),
415
+ // 本表只表达「哪个节点该声明哪些模板」(加载链面);两者用同一模板基名键相交。
416
+ export const NODE_ARTIFACT_TEMPLATES = {
417
+ open: { required: ['CHANGE', 'REQUIREMENT'] },
418
+ design: { required: ['DESIGN'], optional: ['UI-DESIGN'] },
419
+ plan: { required: ['TASK'] },
420
+ execute: { required: ['SUMMARY'] },
421
+ 'subagent-execute': { required: ['SUMMARY'] },
422
+ review: { required: ['REVIEW', 'TEST'] },
423
+ verify: { required: [] },
424
+ archive: { required: [] },
425
+ };
426
+
427
+ // 模板文件根(指针行的相对根)——模板文件本身的绝对位置由登记表的 file 字段承载,这里只拼声明名。
428
+ export const TEMPLATE_ROOT = 'flow-kit/templates';
429
+
430
+ // 模板名归一:去空白与尾随 .md(声明允许 `DESIGN` / `DESIGN.md` 两种写法);大小写保留书写者原样,
431
+ // 比较一律走 templateKeyOf 的小写键(登记表键大写,手写声明常常小写)。
432
+ export function normalizeTemplateName(value) {
433
+ return String(value ?? '').trim().replace(/\.md$/i, '');
434
+ }
435
+
436
+ export function templateKeyOf(value) {
437
+ return normalizeTemplateName(value).toLowerCase();
438
+ }
439
+
440
+ // 声明工件名 → 模板键(单一实现):「节点声明的哪份工件对应哪份模板」只在此派生,两个消费面共用——
441
+ // 结构预检(缺件报文里的模板指针)与模板保真门禁(该工件用哪份骨架校验)。两处曾各持一份等价实现,
442
+ // 副本一旦漂移,预检与收尾就会对同一份工件给出两套口径——这正是本函数存在的理由。
443
+ // 口径(以模板保真门禁的既有实现为基准,它更新):
444
+ // ① 路径归一:`\` 与 `/` 同权(与 workflowRelativeSegments 对声明路径的口径一致),只取末段——
445
+ // 调用方传整条声明路径(`<change-id>/*-SUMMARY.md`)或裸文件名都可以;
446
+ // ② 通配:取末个 `*` 之后(通配只出现在文件名前缀:`*-SUMMARY.md` → `-SUMMARY.md`);
447
+ // ③ 去首部非字母数字(`-SUMMARY` → `SUMMARY`):通配残渣不是名字的一部分;
448
+ // ④ 空基名 → null(没有可派生的名字)——调用方据此「不给模板指针 / 不校验」,不臆造键;
449
+ // ⑤ 键归一(去尾 `.md` + 小写)由 templateKeyOf 承担,不在此另写一份。
450
+ // 只回答「键」,不回答「该节点是否允许这份模板」:声明集合比对(C11)与指针格式化留在调用方——
451
+ // 两侧对未知键的处置本就不同(预检不编造指针、模板保真门禁跳过未登记工件)。
452
+ export function templateKeyFromArtifactName(value) {
453
+ const base = String(value ?? '').replaceAll('\\', '/').split('/').pop();
454
+ const tail = base.split('*').pop().replace(/^[^A-Za-z0-9]+/u, '');
455
+ return tail === '' ? null : templateKeyOf(tail);
456
+ }
457
+
458
+ // 逗号分隔的模板清单(`--templates CHANGE.md,REQUIREMENT.md`;单模板可省略逗号)→ 去重保序数组。
459
+ export function parseTemplateList(value) {
460
+ const names = [];
461
+ const seen = new Set();
462
+ for (const raw of String(value ?? '').split(',')) {
463
+ const name = normalizeTemplateName(raw);
464
+ if (name === '') continue;
465
+ const key = templateKeyOf(name);
466
+ if (seen.has(key)) continue;
467
+ seen.add(key);
468
+ names.push(name);
469
+ }
470
+ return names;
471
+ }
472
+
473
+ // --templates 原始参数收集:支持 `--templates a,b` 与 `--templates=a,b`,可重复出现(累加去重)。
474
+ // 后随参数是另一个选项(以 -- 开头)时不把它当成模板名(fail-closed 地当作「空清单」)。
475
+ // 返回 { provided, values }:provided 区分「未传该参数」与「传了空清单」——前者对内置节点是缺失声明。
476
+ export function findTemplatesArg(cliArgs) {
477
+ let provided = false;
478
+ const names = [];
479
+ const collect = (raw) => {
480
+ provided = true;
481
+ for (const name of parseTemplateList(raw)) {
482
+ if (!names.some((existing) => templateKeyOf(existing) === templateKeyOf(name))) names.push(name);
483
+ }
484
+ };
485
+ for (let index = 0; index < (cliArgs ?? []).length; index++) {
486
+ const arg = cliArgs[index];
487
+ if (arg === '--templates') {
488
+ const next = cliArgs[index + 1];
489
+ const hasValue = typeof next === 'string' && !next.startsWith('--');
490
+ collect(hasValue ? next : '');
491
+ if (hasValue) index += 1;
492
+ continue;
493
+ }
494
+ if (typeof arg === 'string' && arg.startsWith('--templates=')) {
495
+ collect(arg.slice('--templates='.length));
496
+ }
497
+ }
498
+ return { provided, values: names };
499
+ }
500
+
501
+ // 节点 → 模板声明。内置节点取引擎映射(协议副本删掉 node.templates 也不失效——内置节点不依赖协议
502
+ // 自称);自定义协议节点取协议里的 node.templates(ADR-002 特化层:未声明 = 零模板)。
503
+ export function nodeTemplateDeclaration(node) {
504
+ if (!node || typeof node !== 'object') return { source: 'none', required: [], optional: [] };
505
+ const builtin = NODE_ARTIFACT_TEMPLATES[node.id];
506
+ if (builtin) {
507
+ return { source: 'builtin', required: [...builtin.required], optional: [...(builtin.optional ?? [])] };
508
+ }
509
+ const declared = Array.isArray(node.templates)
510
+ ? node.templates.filter((name) => typeof name === 'string' && name.trim() !== '').map(normalizeTemplateName)
511
+ : [];
512
+ return declared.length > 0
513
+ ? { source: 'protocol', required: declared, optional: [] }
514
+ : { source: 'none', required: [], optional: [] };
515
+ }
516
+
517
+ // 声明集合比对(C11):required ⊆ declared ⊆ required ∪ optional。返回 { missing, extra }——两者
518
+ // 皆空即通过。extra 覆盖「多写」与「错名」(都不在允许集合里)。
519
+ export function templateDeclarationProblems(declaration, declared) {
520
+ const required = new Map(declaration.required.map((name) => [templateKeyOf(name), name]));
521
+ const allowed = new Set([
522
+ ...required.keys(),
523
+ ...(declaration.optional ?? []).map((name) => templateKeyOf(name)),
524
+ ]);
525
+ const seen = new Map((declared ?? []).map((name) => [templateKeyOf(name), name]));
526
+ const missing = [...required].filter(([key]) => !seen.has(key)).map(([, name]) => name);
527
+ const extra = [...seen].filter(([key]) => !allowed.has(key)).map(([, name]) => name);
528
+ return { missing, extra };
529
+ }
530
+
531
+ // 声明清单 → 易读形态(报文用;空清单写「零模板」——比空字符串诚实)。
532
+ export function describeTemplateList(names) {
533
+ return Array.isArray(names) && names.length > 0 ? names.join('、') : '零模板';
534
+ }
535
+
536
+ // 模板基名 → 指针路径(`DESIGN` → `flow-kit/templates/DESIGN.md`)。
537
+ export function templatePointerPath(name) {
538
+ return TEMPLATE_ROOT + '/' + normalizeTemplateName(name) + '.md';
539
+ }
540
+
541
+ // 指针行(入口与 explain 共用:同一判据一份实现,两处输出措辞一致)。
542
+ // label:内置入口用 `READ TEMPLATE`,现问通道用 `TEMPLATE`;conditional=true 时追出条件模板行。
543
+ export function templatePointerLines(declaration, options = {}) {
544
+ const label = typeof options.label === 'string' && options.label !== '' ? options.label : 'TEMPLATE';
545
+ const lines = declaration.required.map((name) => label + ': ' + templatePointerPath(name));
546
+ if (options.conditional === true) {
547
+ for (const name of declaration.optional ?? []) {
548
+ lines.push(label + '(条件模板): ' + templatePointerPath(name) + '(仅前端 change)');
549
+ }
550
+ }
551
+ return lines;
552
+ }
553
+
554
+ // ---------- 节点协议提示词:加载链的另一半 ----------
555
+ //
556
+ // 与模板并列的两条权威:提示词(flow-kit/prompts/)是**步骤权威**——这一步怎么做、交代什么;
557
+ // 模板(flow-kit/templates/)是**段形权威**——产出长什么样。两者都在 entry 打印、都由 skill-load
558
+ // 声明,缺一即未完成加载。
559
+ //
560
+ // 路径根与映射各只有一处:映射复用既有的 NODE_PROTOCOL_FILES(出口协议声明校验与 M5 自动补声明
561
+ // 共用),本段只提供指针形态与声明一致性判据,不复制映射表。
562
+
563
+ export const PROMPT_ROOT = 'flow-kit/prompts';
564
+
565
+ // 条件提示词(与条件模板同构):只对特定技能适用的协议文件——必读清单之外的协议面成员,参与声明
566
+ // 一致性判据;入口按前端判据追出(非前端不打印)。目前唯一的条件件是 design 节点的 UI-DESIGN 阶段:
567
+ // 前端 change 才加载 flow-comet-ui-design 并声明 `2a-ui-design.md`。
568
+ export const NODE_CONDITIONAL_PROMPTS = {
569
+ design: ['2a-ui-design.md'],
570
+ };
571
+
572
+ // 节点 → 上游协议提示文件(仅内置节点有 vendored 提示词)。自定义协议节点由 compose 只组合已装技能,
573
+ // 提示词路径仍由 skill-load --prompt 显式声明——不在协议里编造一份(与模板的 C12 语义同构)。
574
+ export function nodePromptFiles(node) {
575
+ if (!node || typeof node !== 'object') return [];
576
+ const files = NODE_PROTOCOL_FILES[node.id];
577
+ return Array.isArray(files) ? [...files] : [];
578
+ }
579
+
580
+ // 提示词文件 → 指针路径(`2-design.md` → `flow-kit/prompts/2-design.md`)。
581
+ export function promptPointerPath(file) {
582
+ return PROMPT_ROOT + '/' + file;
583
+ }
584
+
585
+ // 入口指针行:一行一个协议文件(open / review 这类多文件节点各一行)。零提示词节点返回空数组——
586
+ // 与零模板节点同语义(不打印,也不编造路径)。
587
+ // conditional=true 时追出条件提示词行(与 templatePointerLines 的条件行同形:同一前端判据、同一措辞
588
+ // 形态);非前端 change 上条件文件只是「不适用」,不是缺件,故不打印。
589
+ export function promptPointerLines(node, options = {}) {
590
+ const lines = nodePromptFiles(node).map((file) => 'READ PROMPT: ' + promptPointerPath(file));
591
+ if (options.conditional === true) {
592
+ for (const file of NODE_CONDITIONAL_PROMPTS[node?.id] ?? []) {
593
+ lines.push('READ PROMPT(条件提示词): ' + promptPointerPath(file) + '(仅前端 change)');
594
+ }
595
+ }
596
+ return lines;
597
+ }
598
+
599
+ // 声明一致性判据(入口侧):skill-load 声明的 --prompt 必须落在该节点的协议面内——
600
+ // 节点协议文件 ∪ 该节点的条件提示词。返回 null(通过)或 { declared, expected };expected 供报文
601
+ // 给出可照抄的路径。未声明(null / 空串)不在此判——缺失由出口「缺协议声明标记」门负责,
602
+ // 本判据只判「声明了但声明错」这一形态。
603
+ export function promptDeclarationConflict({ node, declaredProtocol } = {}) {
604
+ const nodeFiles = nodePromptFiles(node);
605
+ if (nodeFiles.length === 0) return null;
606
+ const declared = typeof declaredProtocol === 'string'
607
+ ? (declaredProtocol.replaceAll('\\', '/').split('/').filter((part) => part !== '').pop() ?? '')
608
+ : '';
609
+ if (declared === '') return null;
610
+ const expected = [...nodeFiles, ...(NODE_CONDITIONAL_PROMPTS[node?.id] ?? [])];
611
+ return expected.includes(declared) ? null : { declared, expected };
612
+ }
613
+
614
+ // ---------- 声明命令:参数面的一处装配 ----------
615
+ //
616
+ // 一次 skill-load 声明要携带的东西只有三样:哪个节点的哪个技能、该节点该读的**每一份**协议文件
617
+ // (条件提示词在适用时并入)、以及该节点的模板全清单。这条装配此前散在几处各拼一份——重跑声明的
618
+ // 指引只带首份 --prompt、公开册把占位符写进 --prompt 的值位置(bash 下 `<` 是重定向)、门禁报文
619
+ // 干脆不带 --templates(照抄即撞模板门)。故参数面只在这里拼,调用方只提供事实(节点、技能)。
620
+ //
621
+ // 命令**文本**(脚本路径 / 引号 / 协议上下文)不在这里:那是运行面的事实(平台布局、本次解析到的
622
+ // 协议),由 lib/state-explain.mjs 的 declarationCommand 一处补齐——状态命令族与守卫族取同一份。
623
+ //
624
+ // 同步面与异步面的差别只有一处输入:条件提示词(design 的 2a-ui-design.md)是否适用。守卫的
625
+ // nodeSkillLoadCommands 判得了前端,按结论并入;状态命令族与册子拿不到该结论,改为「本次声明的
626
+ // 技能自己承载哪份条件提示词就并入哪份」(ui-design → 2a)——同步面不替一个异步判据下结论。
627
+ // 零模板节点不拼 --templates(省略即空集,与 C11 的「可省略」一致)。
628
+ function declarationPromptFiles({ nodeId, skill, frontend }) {
629
+ const files = [...(NODE_PROTOCOL_FILES[nodeId] ?? [])];
630
+ const own = SKILL_PROTOCOL_FILES[skill] ?? [];
631
+ for (const file of NODE_CONDITIONAL_PROMPTS[nodeId] ?? []) {
632
+ if (frontend || own.includes(file)) files.push(file);
633
+ }
634
+ return files.filter((file, index) => files.indexOf(file) === index);
635
+ }
636
+
637
+ // 一次声明的参数面(argv 形态,`skill-load` 起头):脚本路径与协议上下文由调用方追加——它们是
638
+ // 运行面的事实(平台路径 / 本次解析到的协议),不是声明内容。
639
+ export function skillLoadDeclarationArgs({ node, skill, frontend = false } = {}) {
640
+ const args = ['skill-load', node?.id, skill];
641
+ for (const file of declarationPromptFiles({ nodeId: node?.id, skill, frontend })) {
642
+ args.push('--prompt', promptPointerPath(file));
643
+ }
644
+ const declaration = nodeTemplateDeclaration(node);
645
+ if (declaration.required.length > 0) {
646
+ args.push('--templates', declaration.required.map((name) => name + '.md').join(','));
647
+ }
648
+ return args;
649
+ }
650
+
651
+ // 该节点要求声明的技能(guarded ∧ 非 handoff)——协议面的事实,唯一实现:守卫的异步适用性判据、
652
+ // 同步出口的覆盖门与回退取值全从这里取(第二个过滤条件在各处各写一遍,就是「两份判据各自演进」
653
+ // 的起点)。
654
+ export function guardedDeclarationSkills(node) {
655
+ return (node?.requiredSkillCalls ?? [])
656
+ .filter((binding) => binding
657
+ && binding.enforcement === 'guarded'
658
+ && binding.scope !== 'handoff'
659
+ && typeof binding.skill === 'string'
660
+ && binding.skill !== '')
661
+ .map((binding) => binding.skill);
662
+ }
663
+
664
+ // 没有可展开的必需技能时,声明该写哪个技能名(**不臆造**):优先节点实现技能(它是这个节点的实现
665
+ // 者),其次该节点 requiredSkillCalls 里非 handoff 的既有条目,两者皆无才留占位符。
666
+ // 占位符是最后的诚实选择——它落在位置实参位,在 bash 下 `<skill>` 是输入重定向、照抄即失败,
667
+ // 故只有当协议面确实没有可用的技能名时才出现,且报文会说明要按 entry 的 LOAD SKILL 行填。
668
+ export function declarationSkillFallback(node) {
669
+ const implementation = node?.implementation;
670
+ const implementationSkill = implementation && typeof implementation === 'object' ? implementation.skill : null;
671
+ if (typeof implementationSkill === 'string' && implementationSkill.trim() !== '') return implementationSkill.trim();
672
+ const mainScoped = (node?.requiredSkillCalls ?? [])
673
+ .find((binding) => binding && binding.scope !== 'handoff'
674
+ && typeof binding.skill === 'string' && binding.skill !== '');
675
+ return mainScoped ? mainScoped.skill : '<skill>';
676
+ }
677
+
678
+ // 该节点本次该声明哪些技能(**同步面**的目标集):guarded 必需技能,但条件绑定(design 的 ui-design:
679
+ // 技能自身承载的协议文件就是该节点的条件提示词)不在此展开——它是否适用要读 CHANGE.md 判前端,
680
+ // 同步面不替它下结论,缺那一项时由判得了前端的出口指引补。一个都不剩时按 declarationSkillFallback 退。
681
+ export function declarationSkillTargets(node) {
682
+ const skills = guardedDeclarationSkills(node)
683
+ .filter((skill) => !(SKILL_PROTOCOL_FILES[skill] ?? [])
684
+ .some((file) => (NODE_CONDITIONAL_PROMPTS[node?.id] ?? []).includes(file)));
685
+ return skills.length > 0 ? skills : [declarationSkillFallback(node)];
686
+ }