flow-comet 1.6.3 → 1.6.5

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 (106) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +21 -3
  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/entry-detail.md +8 -2
  6. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  7. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +180 -6
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +69 -18878
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +29 -5
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1053 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
  15. package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
  16. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
  17. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
  18. package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
  19. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +817 -0
  20. package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
  21. package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
  22. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
  23. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
  24. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +618 -0
  25. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  26. package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +756 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1235 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +384 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +714 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +204 -0
  35. package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
  36. package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +179 -0
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +714 -0
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +123 -0
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
  46. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
  47. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +249 -0
  48. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1505 -0
  49. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
  51. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1248 -0
  52. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
  53. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2493 -0
  54. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +214 -2
  55. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +976 -0
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1398 -0
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1367 -0
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1492 -0
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
  69. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  70. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
  71. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +59 -7559
  72. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
  73. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +223 -2476
  74. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
  75. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
  76. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  77. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  78. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  79. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  80. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  81. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  82. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  83. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  84. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  85. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  86. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  87. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  88. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  89. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  90. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  91. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  92. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  93. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  94. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  95. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  96. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  97. package/README.md +52 -69
  98. package/package.json +3 -2
  99. package/scripts/dsh-bridge.mjs +2 -2
  100. package/scripts/lib/installer-cleanup.mjs +152 -0
  101. package/scripts/lib/installer-flowkit.mjs +159 -0
  102. package/scripts/lib/installer-hooks.mjs +363 -0
  103. package/scripts/lib/installer-loader.mjs +220 -0
  104. package/scripts/lib/installer-migrate.mjs +236 -0
  105. package/scripts/lib/installer-platforms.mjs +314 -0
  106. package/scripts/prepare-env.mjs +21 -1313
@@ -0,0 +1,154 @@
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, 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
+ assertOut(extra, 'workflow-state.mjs skill-load design flow-comet-design --templates DESIGN.md --prompt flow-kit/prompts/2-design.md');
46
+ assertNotOut(extra, '--prompt <');
47
+ const declareLine = extra.output.split(/\r?\n/).find((line) => line.includes('workflow-state.mjs skill-load design')) ?? '';
48
+ assertTrue(declareLine !== '', 'BLOCKED 报文应给出可照抄的重新声明命令');
49
+ // 照抄报文里的命令重跑(只取命令词元:报文尾部是中文说明,不是参数)——标记的 protocol 必须
50
+ // 仍在,否则下一次 exit 会被「缺协议声明标记」拦下(恢复步骤自己弄坏协议声明)。
51
+ const printedArgs = declareLine.slice(declareLine.indexOf('workflow-state.mjs')).split(/\s+/u)
52
+ .filter((token) => token !== '' && !/[\u4e00-\u9fff]/u.test(token))
53
+ .slice(1);
54
+ const redeclared = runState(printedArgs, dir);
55
+ assertExit(redeclared, 0);
56
+ const redeclaredMarker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
57
+ assertTrue(redeclaredMarker.protocol === '2-design.md',
58
+ '照抄重新声明命令后 protocol 不应变成 null,实际: ' + JSON.stringify(redeclaredMarker.protocol));
59
+
60
+ // ③ 漏写:显式空清单(--templates=)→ BLOCKED 且点名漏掉的必填项
61
+ const missing = runState([...DESIGN_SKILL_ARGS, '--templates='], dir);
62
+ assertExit(missing, 1);
63
+ assertOut(missing, 'BLOCKED');
64
+ assertOut(missing, '漏写: DESIGN');
65
+
66
+ // ④ 错名:拼错(DESIGNS)→ 同时报漏写与错名(错名不是「多写」的另一种说法,两条都要出声)
67
+ const typo = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGNS.md'], dir);
68
+ assertExit(typo, 1);
69
+ assertOut(typo, '漏写: DESIGN');
70
+ assertOut(typo, '多写/错名: DESIGNS');
71
+
72
+ // ⑤ 缺声明:整项不写 --templates → 新 change 同样 BLOCKED(「没写」不等于「零模板」)
73
+ const undeclared = runState(DESIGN_SKILL_ARGS, dir);
74
+ assertExit(undeclared, 1);
75
+ assertOut(undeclared, '模板声明缺失');
76
+
77
+ // ⑥ 旧 change 同形:同一条「多写」声明只 WARN 且照常落标记(渐进兼容——旧项目不可能一夜补齐)
78
+ const legacyState = readStateFile(dir);
79
+ delete legacyState.newChange;
80
+ writeState(dir, legacyState);
81
+ const legacy = runState([...DESIGN_SKILL_ARGS, '--templates', 'DESIGN.md,TASK.md'], dir);
82
+ assertExit(legacy, 0);
83
+ assertOut(legacy, 'WARN');
84
+ assertNotOut(legacy, 'BLOCKED');
85
+ const legacyMarker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
86
+ if (legacyMarker.at === undefined || legacyMarker.templates.join(',') !== 'DESIGN,TASK') {
87
+ throw new Error('旧 change 的 WARN 路径应照常写标记(记录真实声明),实际: ' + JSON.stringify(legacyMarker));
88
+ }
89
+ },
90
+ },
91
+
92
+ // ---------- N. 安装器:flow-kit 降级结论 ----------
93
+
94
+ // 降级口径 = 「未校验(模板缺失)」:获取点给命令、进程结尾给结论(影响 / 原因 / 修复)。
95
+ // 两条真实目录形态都必须跑:同名非克隆目录(跳过,不改动)与上游克隆已就位(不挂通知)——
96
+ // 只断言前者会让「无条件打印通知」的实现照样通过。
97
+ {
98
+ name: 'N2 安装器降级口径:同名目录在已跳过时结尾给影响/原因/修复,上游克隆就位时不出现通知',
99
+ surface: '安装器源码(scripts/prepare-env.mjs)与 flow-kit 获取链路仅权威源侧在场',
100
+ run: (dir) => {
101
+ const repoRoot = path.resolve(SCRIPTS_DIR, '..', '..', '..', '..');
102
+ const installer = path.join(repoRoot, 'scripts', 'prepare-env.mjs');
103
+ if (!fs.existsSync(installer)) throw new Error('缺少 prepare-env.mjs');
104
+ const runInstall = (target) => {
105
+ const res = spawnSync(process.execPath, [installer, '--target', target, '--platform', 'claude-code'], {
106
+ cwd: repoRoot, encoding: 'utf8', timeout: 180000,
107
+ });
108
+ return { status: res.status, output: String(res.stdout ?? '') + String(res.stderr ?? '') };
109
+ };
110
+
111
+ // ① 降级态:目标目录预置同名 flow-kit 目录(非上游克隆)→ 跳过 + 手动指引 + 结尾三行结论
112
+ const degradedTarget = path.join(dir, 'n2-degraded');
113
+ fs.mkdirSync(path.join(degradedTarget, 'flow-kit'), { recursive: true });
114
+ const degraded = runInstall(degradedTarget);
115
+ assertExit(degraded, 0); // 降级不改变退出码:安装器其余职责照常完成
116
+ assertOut(degraded, '目录存在但非上游克隆,已跳过');
117
+ assertOut(degraded, '未校验(模板缺失)');
118
+ assertOut(degraded, '影响: 各节点出口输出');
119
+ assertOut(degraded, '原因: flow-kit/templates 未就位');
120
+ // 修复行不许把「重跑」当成对已存在目录的修复——目录在但归属无法确认时,重跑会落回同一条
121
+ // 跳过分支;须先移走/处理该目录或按手动步骤补齐,再重跑。
122
+ assertOut(degraded, '修复: 先移走或处理现有 flow-kit/ 目录');
123
+ assertOut(degraded, '按上方手动获取指引补齐,再重跑本安装器');
124
+ assertNotOut(degraded, '修复: 网络可用时重跑本安装器');
125
+ assertOut(degraded, '手动获取指引: git clone');
126
+ // 非破坏:预置目录原样保留(安装器绝不改动已有目录)
127
+ if (!fs.existsSync(path.join(degradedTarget, 'flow-kit'))) {
128
+ throw new Error('安装器不应删除已存在的 flow-kit 目录');
129
+ }
130
+
131
+ // ② 反向:上游克隆就位(origin 指向上游)→ 走「只读比对」分支,不挂降级通知
132
+ const upstreamTarget = path.join(dir, 'n2-upstream');
133
+ const cloneDir = path.join(upstreamTarget, 'flow-kit');
134
+ fs.mkdirSync(cloneDir, { recursive: true });
135
+ const git = (args) => spawnSync('git', ['-C', cloneDir, ...args], { encoding: 'utf8', timeout: 60000 });
136
+ if (spawnSync('git', ['init', '-q', cloneDir], { encoding: 'utf8' }).status !== 0) {
137
+ throw new Error('夹具构造失败:git init 未成功');
138
+ }
139
+ if (git(['remote', 'add', 'origin', 'https://github.com/rihebty/flow-kit.git']).status !== 0) {
140
+ throw new Error('夹具构造失败:git remote add 未成功');
141
+ }
142
+ if (git(['-c', 'user.name=t', '-c', 'user.email=t@t', 'commit', '-q', '--allow-empty', '-m', 'snapshot']).status !== 0) {
143
+ throw new Error('夹具构造失败:git commit 未成功');
144
+ }
145
+ const clean = runInstall(upstreamTarget);
146
+ assertExit(clean, 0);
147
+ assertOut(clean, '已有 flow-kit(HEAD=');
148
+ assertNotOut(clean, '未校验(模板缺失)');
149
+ assertNotOut(clean, '非上游克隆');
150
+ },
151
+ },
152
+ ];
153
+
154
+ export const ENTRIES = RAW_ENTRIES.map(applyDistributionSurface);
@@ -0,0 +1,97 @@
1
+ // count-derivation.mjs — 计数派生的单一来源:场景数与系统测试集项数的**唯一取数通道**
2
+ //
3
+ // 定位:套件底部自检、本地文档健康工具对「场景数 / 项数」的核对,一律经本模块取数。任何消费方
4
+ // 都不得再自持正则或虚拟机求值——同一计数出现第二份实现必然漂移(改了一处、另一处照旧通过)。
5
+ //
6
+ // 输入约定(组文件形态):
7
+ // · 场景 —— scripts/scenarios/*.mjs,每个文件 `export const ENTRIES = [...]`,元素是场景对象
8
+ // (含 name 与 run);
9
+ // · 条目 —— scripts/items/*.mjs,同约定,元素是测试项对象(含 name 与 run)。
10
+ // 聚合口径 = 目录内全部 .mjs 组文件的 ENTRIES.length 之和:读代码求长度,不读文本、不手抄数字。
11
+ // 目录缺席或空目录 ⇒ fail-closed:抛 code === 'COUNT_SOURCE_MISSING' 的错误并指向缺失的组文件
12
+ // 目录,不静默计 0、也不回落到套件入口的文本解析。
13
+ //
14
+ // 阶段无关性:派生值是「组文件清单 + 每份文件的条目数」的函数,与流程阶段(开发态 / 发布态 /
15
+ // 归档态)无关——组文件不随阶段搬移或改写,故不存在只在某一阶段成立的形态假设;缺口在任何阶段
16
+ // 都以同一形态(缺哪个目录就报哪个目录)暴露出来。
17
+ //
18
+ // 两个导出均为 async:组文件用动态 import 载入(载入即求值,故不静态 import 数据层)。组文件目录
19
+ // 缺失或为空抛 code === 'COUNT_SOURCE_MISSING' 的错误(err.path = 该目录),调用方据此显式报告,
20
+ // 不静默计 0。
21
+ // 可选参数 scriptsDir 是**测试接缝**(默认取本模块所在技能树的 scripts/ 目录,权威源与各平台
22
+ // 安装副本同一相对形态,不假定仓库根布局)——夹具可在临时目录里构造组文件来验证派生确实在
23
+ // 「读」,而不是硬编码。
24
+
25
+ import fs from 'node:fs';
26
+ import path from 'node:path';
27
+ import { fileURLToPath, pathToFileURL } from 'node:url';
28
+
29
+ const LIB_DIR = path.dirname(fileURLToPath(import.meta.url));
30
+ const DEFAULT_SCRIPTS_DIR = path.resolve(LIB_DIR, '..');
31
+
32
+ // 组文件目录(数据层)
33
+ const SCENARIOS_DIR = 'scenarios';
34
+ const ITEMS_DIR = 'items';
35
+
36
+ function missingSource(name, file) {
37
+ const err = new Error('计数派生源不存在: ' + name + '(' + file + ')');
38
+ err.code = 'COUNT_SOURCE_MISSING';
39
+ err.path = file;
40
+ return err;
41
+ }
42
+
43
+ // 组文件枚举:目录缺席 / 空目录 → null(调用方据此 fail-closed 并指向该目录);子目录与非 .mjs
44
+ // 不参与。
45
+ function listGroupFiles(scriptsDir, groupDir) {
46
+ const dir = path.join(scriptsDir, groupDir);
47
+ let entries;
48
+ try {
49
+ entries = fs.readdirSync(dir, { withFileTypes: true });
50
+ } catch (e) {
51
+ if (e.code === 'ENOENT' || e.code === 'ENOTDIR') return null;
52
+ throw e;
53
+ }
54
+ const files = entries
55
+ .filter((e) => e.isFile() && e.name.endsWith('.mjs'))
56
+ .map((e) => path.join(dir, e.name))
57
+ .sort();
58
+ return files.length === 0 ? null : files;
59
+ }
60
+
61
+ function labelOf(scriptsDir, file) {
62
+ return path.relative(scriptsDir, file).split(path.sep).join('/');
63
+ }
64
+
65
+ // 聚合:逐文件动态 import,累计 ENTRIES.length。任一组文件不合约定即抛出(fail-closed——
66
+ // 数据层出现一个不是组文件的模块,或组文件导出为空,都是必须当场暴露的错误,不静默计数)。
67
+ async function countGroupEntries(files, scriptsDir) {
68
+ let total = 0;
69
+ for (const file of files) {
70
+ const label = labelOf(scriptsDir, file);
71
+ const mod = await import(pathToFileURL(file).href);
72
+ if (!Array.isArray(mod.ENTRIES)) throw new Error(label + ' 未导出 ENTRIES 数组(组文件约定)');
73
+ if (mod.ENTRIES.length === 0) throw new Error(label + ' 的 ENTRIES 为空数组(组文件约定)');
74
+ for (const entry of mod.ENTRIES) {
75
+ if (!entry || typeof entry.name !== 'string' || entry.name === '') {
76
+ throw new Error(label + ' 的 ENTRIES 含缺 name 字段的元素(组文件约定)');
77
+ }
78
+ }
79
+ total += mod.ENTRIES.length;
80
+ }
81
+ return total;
82
+ }
83
+
84
+ // ---------- 对外导出 ----------
85
+
86
+ // 组文件目录缺失 / 为空 ⇒ 抛 COUNT_SOURCE_MISSING(err.path = 缺失的目录),交调用方显式报告。
87
+ export async function scenarioCount(scriptsDir = DEFAULT_SCRIPTS_DIR) {
88
+ const files = listGroupFiles(scriptsDir, SCENARIOS_DIR);
89
+ if (!files) throw missingSource(SCENARIOS_DIR + ' 组文件目录', path.join(scriptsDir, SCENARIOS_DIR));
90
+ return countGroupEntries(files, scriptsDir);
91
+ }
92
+
93
+ export async function systemItemCount(scriptsDir = DEFAULT_SCRIPTS_DIR) {
94
+ const files = listGroupFiles(scriptsDir, ITEMS_DIR);
95
+ if (!files) throw missingSource(ITEMS_DIR + ' 组文件目录', path.join(scriptsDir, ITEMS_DIR));
96
+ return countGroupEntries(files, scriptsDir);
97
+ }
@@ -0,0 +1,196 @@
1
+ // fix-loop-node.mjs — Fix 族判定与受控归位(单一权威实现)
2
+ // 承载:execute 家族之后首个未完成节点 / TASK.md 读取 / Fix 回因分类 / 受控归位轮次计数与审计文案 /
3
+ // Fix 回程节点推导。判定本身只读 TASK.md 与 state 证据(history · evidence),无 console 输出、
4
+ // 无 process.exit;唯一允许写 state 的是轮次计数 helper——它只被受控归位入口在目标命中后调用,
5
+ // 轮次字段的读写经 state-schema 单一来源。
6
+ // 「TASK.md + 路由」组合成的归位决策(resolveFixRollbackDecision)落在入口:它需要路由核心
7
+ // resolveNextNode,而路由核心留在入口(入口 → lib 单向依赖,不反向)。
8
+ // 依赖方向:本模块只依赖 task-graph.mjs 与既有共享模块。
9
+ import { promises as fs } from 'fs';
10
+ import path from 'path';
11
+ import { taskBlocks, taskOpeningAttrs } from '../task-parsing.mjs';
12
+ import { fixRoundsFor, setFixRoundsFor } from '../state-schema.mjs';
13
+ import {
14
+ route,
15
+ protocolTaskFilePath,
16
+ EXECUTE_FAMILY_NODE_IDS,
17
+ historyEventBelongsToChange,
18
+ parseTaskSetSignature,
19
+ taskSetSignature,
20
+ fixTaskClassifier,
21
+ fixTaskMarker,
22
+ } from './task-graph.mjs';
23
+
24
+ // execute 家族之后第一个未完成节点:按协议 route 顺序跳过全部 execute 家族节点,返回其后首个不在
25
+ // completedNodes 中的节点 id;协议无 execute 家族或后置节点全部完成 → null。
26
+ // 这里只做通用推导(内置协议 = review → verify → archive);是否可作为 Fix 回程源由调用方
27
+ // (归位决策 / 出口推进)再用 review / verify 收窄(只覆盖内置源节点)。
28
+ export function firstIncompletePostExecNode({ protocol, completedNodes = [] }) {
29
+ let sawExecuteFamily = false;
30
+ for (const node of route(protocol)) {
31
+ if (EXECUTE_FAMILY_NODE_IDS.has(node.id)) {
32
+ sawExecuteFamily = true;
33
+ continue;
34
+ }
35
+ if (sawExecuteFamily && !completedNodes.includes(node.id)) return node.id;
36
+ }
37
+ return null;
38
+ }
39
+
40
+ // 协议任务文件内容读取(taskFile 语义唯一来源):不存在 / 不可读 → null;调用方各自按
41
+ // fail-closed 语义处理(回退判定 → false,回程推导 → null),不把访问类故障当成空任务集。
42
+ export async function readProtocolTaskContent(protocol, changeName, specsRoot) {
43
+ try {
44
+ return await fs.readFile(protocolTaskFilePath(protocol, changeName, specsRoot), 'utf8');
45
+ } catch {
46
+ return null;
47
+ }
48
+ }
49
+
50
+ // 「未闭合 execute 生命周期」信号派生:取 history 中最后一次 exit-applied execute 家族事件
51
+ // 记录的 { signature, algo, node };无家族出口事件 / 该事件无签名字段(旧 state)→ null(调用方按
52
+ // 旧 change 渐进放行)。只认最新一次家族出口——更早的签名被后续闭合覆盖。
53
+ // change 归属过滤经 historyEventBelongsToChange(单一权威)。算法版本:事件可带 signatureAlgo
54
+ // (新写形态),缺省按签名值解析出的版本(legacy 裸 hex = v1);声明版本与值版本不一致的畸形事件
55
+ // → null(fail-closed,不参与闭合判定)。
56
+ export function latestExecuteExitEvent(history, changeName) {
57
+ if (!Array.isArray(history)) return null;
58
+ for (let i = history.length - 1; i >= 0; i -= 1) {
59
+ const event = history[i];
60
+ if (!event || event.event !== 'exit-applied' || !EXECUTE_FAMILY_NODE_IDS.has(event.node)) continue;
61
+ if (!historyEventBelongsToChange(event, changeName)) continue;
62
+ if (typeof event.taskSetSignature !== 'string' || event.taskSetSignature === '') return null;
63
+ const parsed = parseTaskSetSignature(event.taskSetSignature);
64
+ if (parsed === null) return null;
65
+ if (typeof event.signatureAlgo === 'string' && event.signatureAlgo !== '' && event.signatureAlgo !== parsed.algo) return null;
66
+ return { signature: event.taskSetSignature, algo: parsed.algo, digest: parsed.digest, node: event.node };
67
+ }
68
+ return null;
69
+ }
70
+
71
+ // ---------- Fix 回因分类(共享纯函数 · 单一权威 · 展示层派生) ----------
72
+ // 出口回程分支在写本次 exit-applied 事件之前调用本分类器:只用既有字段派生证据(history 的
73
+ // execute 家族出口签名 + TASK 内容结构标记),零新增 state 字段 / 事件类型。判据:
74
+ // divergence = 历史任一 execute 家族 exit-applied 事件记录的 taskSetSignature ≠ 当前任务集签名;
75
+ // marker = 模板派生的修复段内含 <task> 块,或全文任一任务 id 命中修复族前缀(唯一谓词
76
+ // fixTaskClassifier / 其 id 边界常量 FIX_TASK_ID_PREFIX);
77
+ // divergence ∨ marker → 'fix';有签名且不发散 → 'normal';无签名且无标记 → 'unknown'
78
+ // (旧 state 证据不足:中性输出、不 BLOCK,由调用方渲染)。
79
+ // 修复段标题由调用方传入(从 flow-kit/templates/TASK.md 的 H2 派生);缺失 / 空串回退内置常量
80
+ // (task-graph 的 FIX_SECTION_TITLE_FALLBACK)。签名事件全量参与、不做「只看最新」短路——多波次
81
+ // 场景最新签名已被闭合写成当前签名,只看最新会漏判 fix。
82
+ // 回因分类唯一入口。签名:classifyFixReturnCause({ history, changeName, taskContent, fixSectionTitle })
83
+ // → 'fix' | 'normal' | 'unknown'。纯函数:无 fs / console / process.exit,不改既有路由判定语义。
84
+ // 算法版本:只让与当前任务集签名同版本的历史事件参与「signatureKnown / divergence」判定;跨版本
85
+ // 事件跳过(不可比),避免引擎升级后把正常多趟误判成 Fix。
86
+ export function classifyFixReturnCause({ history, changeName, taskContent, fixSectionTitle } = {}) {
87
+ const current = parseTaskSetSignature(taskSetSignature(taskContent));
88
+ let signatureKnown = false;
89
+ let divergence = false;
90
+ if (Array.isArray(history)) {
91
+ for (const event of history) {
92
+ if (!event || event.event !== 'exit-applied' || !EXECUTE_FAMILY_NODE_IDS.has(event.node)) continue;
93
+ if (!historyEventBelongsToChange(event, changeName)) continue;
94
+ if (typeof event.taskSetSignature !== 'string' || event.taskSetSignature === '') continue;
95
+ const recorded = parseTaskSetSignature(event.taskSetSignature);
96
+ if (recorded === null) continue;
97
+ if (typeof event.signatureAlgo === 'string' && event.signatureAlgo !== '' && event.signatureAlgo !== recorded.algo) continue;
98
+ if (current === null || recorded.algo !== current.algo) continue;
99
+ signatureKnown = true;
100
+ if (recorded.digest !== current.digest) divergence = true;
101
+ }
102
+ }
103
+ if (divergence || fixTaskMarker(taskContent, fixSectionTitle)) return 'fix';
104
+ return signatureKnown ? 'normal' : 'unknown';
105
+ }
106
+
107
+ // ---------- Fix 受控归位轮次(单一权威 · 唯一写点) ----------
108
+ // 仅受控归位入口在目标命中后调用本 helper,且只对决策 kind='pending' 计数;done-but-unclosed、
109
+ // 回因分类、verify 命令失败都不经此,也不得在调用方另行累加。
110
+ // 阈值语义:从第 4 轮起,新 change 返回 blocked(调用方必须先于任何 state 写盘退出,不得写入
111
+ // currentNode);旧 change 返回 warn 后照常归位。用户显式授权记录为
112
+ // state.evidence[源节点].fixRoundOverride = { round, at, source },覆盖到该轮即放行(不新增第二个顶层字段)。
113
+ // 完整授权形态:round 为正整数、at/source 均为非空字符串;任一缺失/类型非法/空串(含纯空白)
114
+ // 一律视为未授权 fail-closed——第 4 轮继续 BLOCK,调用方不写 currentNode、state 字节零改写。
115
+ // 审计行后缀由本 helper 统一给出,调用方禁止各自拼装。
116
+
117
+ function readFixRoundOverride(state, sourceNode) {
118
+ if (typeof sourceNode !== 'string' || sourceNode === '') return null;
119
+ const sourceEvidence = state && state.evidence && typeof state.evidence === 'object' && !Array.isArray(state.evidence)
120
+ ? state.evidence[sourceNode]
121
+ : null;
122
+ const override = sourceEvidence && typeof sourceEvidence === 'object' && !Array.isArray(sourceEvidence)
123
+ ? sourceEvidence.fixRoundOverride
124
+ : null;
125
+ if (!override || typeof override !== 'object' || Array.isArray(override)) return null;
126
+ if (typeof override.round !== 'number' || !Number.isInteger(override.round) || override.round <= 0) return null;
127
+ if (typeof override.at !== 'string' || override.at.trim() === '') return null;
128
+ if (typeof override.source !== 'string' || override.source.trim() === '') return null;
129
+ return { round: override.round };
130
+ }
131
+
132
+ const FIX_ROLLBACK_ROUND_LIMIT = 3;
133
+
134
+ const EMPTY_FIX_ROLLBACK_ROUND = Object.freeze({
135
+ counted: false,
136
+ blocked: false,
137
+ warn: false,
138
+ round: null,
139
+ overrideUsed: false,
140
+ auditSuffix: '',
141
+ blockedMessage: null,
142
+ warnMessage: null,
143
+ });
144
+
145
+ function fixRoundAuditSuffix(round) {
146
+ return '(第 ' + round + '/' + FIX_ROLLBACK_ROUND_LIMIT + ' 轮)';
147
+ }
148
+
149
+ function fixRoundBlockedMessage(sourceNode, round) {
150
+ return [
151
+ 'BLOCKED: Fix 批次受控归位已达 ' + FIX_ROLLBACK_ROUND_LIMIT + ' 轮上限,第 ' + round + ' 轮需用户决策(继续修/停止)——源节点 ' + sourceNode + '。',
152
+ '恢复: 继续修 → 由用户显式授权后在 state.evidence.' + sourceNode + '.fixRoundOverride 记录 {"round":' + round + ',"at":"<时间>","source":"<授权来源>"} 再重试;停止 → 结束 Fix 批次并按流程处理(禁止手改 state 机器字段)。',
153
+ ].join('\n');
154
+ }
155
+
156
+ export function applyFixRollbackRound({ state, sourceNode, decision }) {
157
+ if (!state || !decision) return EMPTY_FIX_ROLLBACK_ROUND;
158
+ if (decision.kind !== 'pending') return EMPTY_FIX_ROLLBACK_ROUND;
159
+ const round = fixRoundsFor(state) + 1;
160
+ const auditSuffix = fixRoundAuditSuffix(round);
161
+ if (round <= FIX_ROLLBACK_ROUND_LIMIT) {
162
+ setFixRoundsFor(state, round);
163
+ return { ...EMPTY_FIX_ROLLBACK_ROUND, counted: true, round, auditSuffix };
164
+ }
165
+ const override = readFixRoundOverride(state, sourceNode);
166
+ if (override !== null && override.round >= round) {
167
+ setFixRoundsFor(state, round);
168
+ return { ...EMPTY_FIX_ROLLBACK_ROUND, counted: true, round, overrideUsed: true, auditSuffix };
169
+ }
170
+ if (state.newChange === true) {
171
+ return { ...EMPTY_FIX_ROLLBACK_ROUND, blocked: true, round, auditSuffix, blockedMessage: fixRoundBlockedMessage(sourceNode, round) };
172
+ }
173
+ setFixRoundsFor(state, round);
174
+ return {
175
+ ...EMPTY_FIX_ROLLBACK_ROUND,
176
+ counted: true,
177
+ warn: true,
178
+ round,
179
+ auditSuffix,
180
+ warnMessage: 'FIX-BATCH WARN: Fix 批次受控归位已达 ' + FIX_ROLLBACK_ROUND_LIMIT + ' 轮上限,第 ' + round + ' 轮在旧 change 上渐进放行(建议用户显式授权并在 evidence 记录 fixRoundOverride)。',
181
+ };
182
+ }
183
+
184
+ // Fix 回程节点推导(共享基础):TASK.md 存在、至少一个任务块且全部 status="done" 时,
185
+ // 取 firstIncompletePostExecNode;仅当其 ∈ {review, verify}(内置回程源)才返回,否则 null。
186
+ // 仍有 pending / 零任务块 / TASK.md 缺失 → null(fail-closed)。「execute 本次 exit 前已在
187
+ // completedNodes」的二次完成条件由出口推进点判定,本函数只做 TASK + 路由推导。
188
+ export async function resolveFixReturnNode({ runRoot, changeName, protocol, completedNodes = [] }) {
189
+ const taskContent = await readProtocolTaskContent(protocol, changeName, path.join(runRoot, '.specs'));
190
+ if (taskContent === null) return null;
191
+ const attrsList = taskBlocks(taskContent).map(taskOpeningAttrs).filter(Boolean);
192
+ if (attrsList.length === 0) return null;
193
+ if (!attrsList.every((attrs) => attrs.status === 'done')) return null;
194
+ const node = firstIncompletePostExecNode({ protocol, completedNodes });
195
+ return node === 'review' || node === 'verify' ? node : null;
196
+ }