flow-comet 1.6.5 → 1.8.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 (89) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +32 -18
  3. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +2 -2
  4. package/.flow-comet/skills/flow-comet/reference/decision-points.md +5 -5
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +30 -11
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +4 -4
  8. package/.flow-comet/skills/flow-comet/reference/init-detection.md +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +2 -2
  10. package/.flow-comet/skills/flow-comet/reference/post-archive-handoff.md +264 -0
  11. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -1
  12. package/.flow-comet/skills/flow-comet/reference/replan.md +1 -1
  13. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +1 -0
  14. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +270 -30
  15. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  16. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
  17. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +122 -11
  18. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +79 -40
  19. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +11 -9
  20. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  21. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +1 -1
  22. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +128 -56
  23. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +357 -3
  24. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +26 -1
  25. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +6 -2
  26. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +29 -21
  27. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +4 -15
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +357 -219
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +725 -309
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +182 -54
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +224 -83
  35. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +17 -28
  36. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +61 -33
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +663 -205
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +68 -9
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +11 -4
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +232 -11
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +140 -74
  46. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +8 -4
  47. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  48. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +0 -3
  49. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +248 -24
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +63 -3
  51. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +181 -8
  52. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +340 -0
  53. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +132 -20
  54. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +12 -5
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1564 -54
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1489 -38
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1466 -243
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +743 -24
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +220 -92
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +657 -21
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +41 -27
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +285 -9
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +7 -6
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +21 -15
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +8 -5
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +45 -36
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +2 -2
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2381 -85
  69. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -2
  70. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
  71. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +339 -103
  72. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  73. package/.flow-comet/skills/flow-comet-archive/SKILL.md +33 -11
  74. package/.flow-comet/skills/flow-comet-change/SKILL.md +1 -1
  75. package/.flow-comet/skills/flow-comet-design/SKILL.md +5 -3
  76. package/.flow-comet/skills/flow-comet-dev/SKILL.md +2 -2
  77. package/.flow-comet/skills/flow-comet-execute/SKILL.md +37 -13
  78. package/.flow-comet/skills/flow-comet-integration/SKILL.md +10 -4
  79. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  80. package/.flow-comet/skills/flow-comet-plan/SKILL.md +13 -6
  81. package/.flow-comet/skills/flow-comet-review/SKILL.md +21 -12
  82. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +1 -1
  83. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +43 -18
  84. package/.flow-comet/skills/flow-comet-task/SKILL.md +4 -2
  85. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  86. package/.flow-comet/skills/flow-comet-verify/SKILL.md +1 -1
  87. package/README.md +2 -2
  88. package/package.json +1 -1
  89. package/scripts/dsh-bridge.mjs +238 -21
@@ -1,30 +1,69 @@
1
1
  // 证据与产物门禁(守卫模块):直显授权约束、在飞委托、SUMMARY 必填段与自检方法、LESSONS 扫描段
2
2
  // 与命中核对、execute 出口、
3
- // verify 出口(真实执行验证命令并记录失败计数)、Return Contract、subagent-execute 摘要与多趟完成
3
+ // verify 出口(真实执行验证命令并记录失败计数)、AC 覆盖(verify 出口 BLOCK / review 出口汇总 WARN)、
4
+ // Return Contract、subagent-execute 摘要与多趟完成
4
5
  // 判定、required-skill / schema / 产物 存在性门禁——即「完成声明必须有证据与产物」这一族判据。
5
6
  //
6
- // 分级沿用既有语义:新 change(init 标记)强制 BLOCKED + 恢复指引,旧 change 渐进 WARN 不阻断。
7
+ // 判级:单一判级——违反即 BLOCKED + 恢复指引(新旧双轨已退役,同一形态不再有渐进 WARN 侧)。
7
8
 
8
9
  import { promises as fs } from 'fs';
9
10
  import path from 'path';
10
- import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor } from '../state-schema.mjs';
11
+ import { fileURLToPath } from 'url';
12
+ import {
13
+ validateStateFields,
14
+ verifyFailuresFor,
15
+ setVerifyFailuresFor,
16
+ } from '../state-schema.mjs';
11
17
  import { EXECUTE_FAMILY_NODE_IDS, analyzeDependencyGraph, normalizeHeading } from '../route-node.mjs';
12
18
  import { taskOpeningAttrs, taskBlocks as extractTaskBlocks } from '../task-parsing.mjs';
13
- import { runRoot, fileExists, statePath, writeJson } from './guard-state-io.mjs';
19
+ // 声明面的事实与命令装配各归一处:协议面事实(该节点该声明哪些技能、没有必需技能时退到哪个名字)
20
+ // 取 protocol-utils;条件提示词(判前端时才是必读面)取 NODE_CONDITIONAL_PROMPTS;命令文本与
21
+ // 「全部 --prompt + 模板全清单」的拼装取 state-explain 的 declarationCommands——本模块不再各拼一半。
22
+ import {
23
+ NODE_CONDITIONAL_PROMPTS,
24
+ declarationSkillFallback,
25
+ guardedDeclarationSkills,
26
+ } from '../protocol-utils.mjs';
27
+ import { runRoot, packageRoot, fileExists, statePath, writeJson, protocolPath } from './guard-state-io.mjs';
14
28
  import {
29
+ archiveDirNameNotice,
15
30
  eligibleParallelBlocks,
16
31
  inFlightHandoffRequests,
17
32
  isArchivedChange,
18
- isNewChange,
19
33
  missingAugmentationChecks,
20
34
  missingRequiredArtifacts,
21
35
  missingRequiredSchemaEvidence,
22
36
  missingRequiredSkillChecks,
37
+ recoveryActionText,
23
38
  taskDependsOn,
24
39
  verifySummaries,
25
40
  } from './guard-routing.mjs';
26
41
  import { applicabilityGatedBinding, frontendCriterion } from './guard-uidesign.mjs';
27
42
  import { buildSkeleton, headingPattern, LESSONS_SCAN_SECTION } from './guard-artifact-skeleton.mjs';
43
+ // 段界(同级标题 / 围栏 / 分隔线 / 文末)取 lib/section-body.mjs 的唯一实现:LESSONS 扫描段此前自带一份
44
+ // 同名语义的按行扫描(只认反引号围栏),波浪号围栏里的 `## ` 会把它截断。
45
+ import { sectionBody } from './section-body.mjs';
46
+ // AC 覆盖判定(纯判定模块):verify 出口的 BLOCK / review 出口的汇总 WARN 共用同一份判定与报文,
47
+ // 分级只在下方门禁函数一处表达。
48
+ import {
49
+ acCoverageReportLines,
50
+ acCoverageReview,
51
+ acCoverageSummaryLine,
52
+ acCoverageUnjudgeableLines,
53
+ } from './ac-coverage.mjs';
54
+ // LESSONS 命中集(路径词元 × 条目关键词)的单一实现:与 handoff request 的开工前打印共用,执行者
55
+ // 看到的集合必须就是出口验收的集合。
56
+ import { lessonsEntries, lessonsHits, lessonsPathTokens, taskWriteFilesById } from './lessons-hits.mjs';
57
+ // 命令文本的唯一实现(平台化脚本根 + 整条路径加引号):运行期恢复指引与 explain 的 COMMAND 行
58
+ // 同源;本模块不再自拼路径(L-067:同一推导两处表达必然分叉)。
59
+ import { declarationCommand, declarationCommands, protocolContextArgs, scriptCommand } from './state-explain.mjs';
60
+ // 声明标记目录的路径规则(活动路径优先、归档兜底)归状态族的路径上下文模块:本模块只按守卫运行根
61
+ // 取用(guard → state-* 是允许的单向边),不在此另写一份扫描。
62
+ import { findSkillLoadsDir } from './state-io.mjs';
63
+
64
+ // 本模块位于 <技能包>/scripts/lib:脚本目录由自身位置推导一次——「自己在哪」与运行根是本模块提供
65
+ // 的两个事实,平台化与引号形态本身在 state-explain。
66
+ const scriptsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
28
67
 
29
68
  // directOverride 授权约束(direct 是用户决策点,不可自决——机制约束)——execute / subagent-execute
30
69
  // 出口校验:executionMode=direct 且 directOverride=true(显式直显授权态)须存在授权审计记录
@@ -47,7 +86,7 @@ export function runDirectOverrideGate({ node, state }) {
47
86
 
48
87
  // 验证隔离「同一时刻只有一个写者」出口校验——读 state.evidence['subagent-execute'].handoffRequests:
49
88
  // 存在条目且**至少一个无对应 handoffResult** ⇒ 在飞委托(写者未收工,跑全量判据会被未提交中间态
50
- // 污染):新 change BLOCKED(含恢复指引「待写入者收工后重跑 / 已作废则撤回」)/ 旧 change WARN 渐进;
89
+ // 污染):一律 BLOCKED(含恢复指引「待写入者收工后重跑 / 已作废则撤回」);
51
90
  // 全部有对应 result ⇒ 放行;已撤回(withdrawnAt + withdrawnBy 齐备)的 request 不构成在飞委托 ⇒
52
91
  // 放行;无该证据对象 ⇒ 零输出。落点 = 出口校验流(与其余 violations / WARN 同风格,不新增独立命令
53
92
  // 面);判据经 inFlightHandoffRequests 单处求值(与 Return Contract 的 result 侧契约校验正交,不
@@ -58,12 +97,9 @@ export function runInFlightHandoffGate({ node, state }) {
58
97
  if (inFlight.length > 0) {
59
98
  const inFlightDetail = '存在在飞委托(handoffRequests 有 request 无对应 handoffResult): '
60
99
  + inFlight.join(', ') + '——验证隔离要求同一时刻只有一个写者(写者未收工)';
61
- if (isNewChange(state)) {
62
- console.error('BLOCKED: ' + inFlightDetail);
63
- console.error('恢复: 待写入者收工后重跑——子代理回传后用 workflow-handoff.mjs result <task-id> <Return Contract> 记录结果再重试 exit;若该委托已作废(零提交复验失败 / 写边界被拒后遗弃),用 workflow-handoff.mjs withdraw <task-id> --by <来源> [--reason <原因>] 撤回后再重试 exit(撤回留痕 withdrawnAt/withdrawnBy,已撤回 = 终态,历史不删)');
64
- process.exit(1);
65
- }
66
- console.error('WARN: ' + inFlightDetail + '(旧 change 渐进不阻断;待写入者收工后重跑全量判据;已作废的委托可用 workflow-handoff.mjs withdraw <task-id> --by <来源> 撤回)');
100
+ console.error('BLOCKED: ' + inFlightDetail);
101
+ console.error('恢复: 待写入者收工后重跑——子代理回传后用 workflow-handoff.mjs result <task-id> <Return Contract> 记录结果再重试 exit;若该委托已作废(零提交复验失败 / 写边界被拒后遗弃),用 workflow-handoff.mjs withdraw <task-id> --by <来源> [--reason <原因>] 撤回后再重试 exit(撤回留痕 withdrawnAt/withdrawnBy,已撤回 = 终态,历史不删)');
102
+ process.exit(1);
67
103
  }
68
104
  }
69
105
 
@@ -74,23 +110,8 @@ export function runInFlightHandoffGate({ node, state }) {
74
110
  // 登记表(reference/artifact-templates.json 的 SUMMARY.increments)——位置语义由模板保真门禁按同一
75
111
  // 条目执行,本门禁只判「在场 + 命中回应」,不写第二份位置判据(L-067)。
76
112
  //
77
- // 停用词表与命中上限单处定义(段名从骨架模块取用,不在本模块自持第二份清单)。关键词行
78
- // (`- **关键词**:`)是唯一参与命中计算的字段——无关键词行的旧条目不参与(给旧条目一个不被
79
- // 误命中的通道)。
80
- const LESSONS_HIT_LIMIT = 5;
81
- const LESSONS_PATH_STOPWORDS = new Set([
82
- // 目录布局噪音
83
- 'src', 'lib', 'libs', 'app', 'apps', 'core', 'pkg', 'packages', 'bin', 'dist', 'build', 'out',
84
- 'tmp', 'temp', 'test', 'tests', 'spec', 'specs', 'unit', 'e2e', 'fixture', 'fixtures',
85
- 'mock', 'mocks', 'docs', 'doc', 'scripts', 'script', 'assets', 'static', 'public',
86
- 'config', 'configs', 'utils', 'util', 'helpers', 'helper', 'common', 'shared', 'internal',
87
- 'modules', 'module', 'components', 'pages', 'views', 'styles', 'data', 'types', 'index',
88
- // 扩展名 / 备份后缀残片
89
- 'mjs', 'cjs', 'jsx', 'tsx', 'json', 'yaml', 'yml', 'toml', 'lock', 'bak', 'log', 'txt', 'css',
90
- ]);
91
-
92
- const LESSONS_ENTRY_HEADING = /^###\s*L-(\d+)\b/u;
93
- const LESSONS_KEYWORD_LINE = /^[-*\s]*\*\*关键词\*\*\s*[::]\s*(.+)$/u;
113
+ // 命中集算法(路径词元 → 条目关键词求交、取前 5)与 handoff request 的开工前打印**共用同一实现**
114
+ // (lib/lessons-hits.mjs):执行者看到的集合必须就是出口验收的集合,两处各算一套必然分叉。
94
115
 
95
116
  // 段名 / 必填来自登记表;登记表或模板缺席时退回段名常量并保持必填——扫描段由 AC-18 要求,不因模板
96
117
  // 派生失败而免检(「模板缺失」只让模板派生判据跳过,不让扫描声明消失)。
@@ -109,101 +130,16 @@ async function lessonsScanRule() {
109
130
  return { name: LESSONS_SCAN_SECTION, required: true, pattern: headingPattern(LESSONS_SCAN_SECTION, 2), registered: false };
110
131
  }
111
132
 
112
- // write_files 原文(键 = 任务 id)。块提取与开标签解析复用 task-parsing 的既有实现,只读元素文本。
133
+ // write_files 原文(键 = 任务 id):块提取与开标签解析在 lib/lessons-hits.mjs 的同一实现里,本处
134
+ // 只负责读 TASK.md——出口与开工前打印共用同一个提取,两侧的写面输入不会分叉。
113
135
  async function taskWriteFiles(changeDir) {
114
- const out = new Map();
115
136
  let text = '';
116
137
  try {
117
138
  text = await fs.readFile(path.join(changeDir, 'TASK.md'), 'utf8');
118
139
  } catch {
119
- return out;
120
- }
121
- for (const block of extractTaskBlocks(text)) {
122
- const attrs = taskOpeningAttrs(block);
123
- if (!attrs || !attrs.id) continue;
124
- const writeFiles = block.match(/<write_files>([\s\S]*?)<\/write_files>/i);
125
- if (writeFiles) out.set(attrs.id, writeFiles[1]);
126
- }
127
- return out;
128
- }
129
-
130
- // 路径段 → 词元:目录名与文件主干(去最后一层扩展名)按非字母数字切分,长度 ≥3、去停用词、去纯数字。
131
- // 只在「命中计算」这一侧做长度与停用词过滤——条目关键词侧原样保留,过滤口径不扩散成第二份规则。
132
- function lessonsPathTokens(writeFilesText) {
133
- const tokens = new Set();
134
- for (const raw of String(writeFilesText ?? '').split(/[\n;]+/u)) {
135
- const segments = raw.trim().replace(/\\/gu, '/').split('/').filter((s) => s !== '' && s !== '.' && s !== '..');
136
- segments.forEach((segment, index) => {
137
- const body = index === segments.length - 1 ? segment.replace(/\.[^.]*$/u, '') : segment;
138
- for (const piece of body.split(/[^0-9A-Za-z\u4e00-\u9fff]+/u)) {
139
- const token = piece.toLowerCase();
140
- if ([...token].length < 3) continue;
141
- if (/^\d+$/u.test(token)) continue;
142
- if (LESSONS_PATH_STOPWORDS.has(token)) continue;
143
- tokens.add(token);
144
- }
145
- });
146
- }
147
- return tokens;
148
- }
149
-
150
- // LESSONS 条目:`### L-NNN` 标题开启一个条目,块内 `- **关键词**:` 行的词元即命中输入;下一个 H2
151
- // 结束条目区(区外的 `###` 不参与)。围栏代码块内是书写样例(模板里的「条目格式」示例即此形态),
152
- // 按行扫描会被误当成真条目——围栏内一律跳过。无关键词行的条目不进结果集(旧条目跳过)。
153
- function lessonsEntries(lessonsText) {
154
- const entries = [];
155
- let current = null;
156
- let inFence = false;
157
- for (const line of String(lessonsText ?? '').replace(/\r\n?/gu, '\n').split('\n')) {
158
- if (/^\s*```/u.test(line)) { inFence = !inFence; continue; }
159
- if (inFence) continue;
160
- if (/^##\s/u.test(line)) { current = null; continue; }
161
- const heading = line.match(LESSONS_ENTRY_HEADING);
162
- if (heading) {
163
- current = { id: 'L-' + String(Number(heading[1])).padStart(3, '0'), tokens: [], order: entries.length };
164
- entries.push(current);
165
- continue;
166
- }
167
- if (current === null) continue;
168
- const keyword = line.match(LESSONS_KEYWORD_LINE);
169
- if (!keyword) continue;
170
- for (const piece of keyword[1].split(/[\s,,、;;/|]+/u)) {
171
- const token = piece.trim().toLowerCase();
172
- if (token !== '') current.tokens.push(token);
173
- }
174
- }
175
- return entries.filter((entry) => entry.tokens.length > 0);
176
- }
177
-
178
- // 命中计算:路径词元 × 条目关键词词元求交,共享词元多的条目优先(相关度),同分按条目出现顺序
179
- // (结果确定、可复核),取前 LESSONS_HIT_LIMIT 条。
180
- function lessonsHits(pathTokens, entries) {
181
- if (pathTokens.size === 0) return [];
182
- const scored = [];
183
- for (const entry of entries) {
184
- const shared = [...new Set(entry.tokens.filter((token) => pathTokens.has(token)))];
185
- if (shared.length === 0) continue;
186
- scored.push({ id: entry.id, shared, order: entry.order });
140
+ return new Map();
187
141
  }
188
- scored.sort((a, b) => b.shared.length - a.shared.length || a.order - b.order);
189
- return scored.slice(0, LESSONS_HIT_LIMIT);
190
- }
191
-
192
- // 段正文:命中段标题行之后、到下一个 H2 / 分隔线 / 文件尾(行锚定——正文里「引用段名」不劫持匹配)。
193
- // 围栏代码块内的 `## ` 与 `---` 是正文示例,不当作段边界。段缺席返回 null(与「段在场但正文为空」
194
- // 区分:前者是缺声明,后者由正文判据另行处理)。
195
- function lessonsScanBody(content, pattern) {
196
- const lines = String(content ?? '').replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n').split('\n');
197
- const start = lines.findIndex((line) => pattern.test(line));
198
- if (start === -1) return null;
199
- const body = [];
200
- let inFence = false;
201
- for (let i = start + 1; i < lines.length; i += 1) {
202
- if (/^\s*```/u.test(lines[i])) inFence = !inFence;
203
- if (!inFence && (/^##\s/u.test(lines[i]) || /^---\s*$/u.test(lines[i]))) break;
204
- body.push(lines[i]);
205
- }
206
- return body.join('\n');
142
+ return taskWriteFilesById(text);
207
143
  }
208
144
 
209
145
  // 编号在段内出现的判定:两侧非数字边界(L-501 不算命中 L-5012),大小写不敏感(执行者常写小写
@@ -214,9 +150,8 @@ function mentionsLessonsId(body, id) {
214
150
  return new RegExp('(^|[^0-9])' + escaped + '(?![0-9])', 'iu').test(body);
215
151
  }
216
152
 
217
- // 每份 SUMMARY 的两条判据 → 问题描述数组(分级由调用方按 isNewChange 决定:新 change BLOCKED /
218
- // 旧 change WARN——C10 无例外)。TASK.md 或 .specs/LESSONS.md 缺席时对应输入为空:段在场判据照常,
219
- // 命中计算自然为空集(无条目可命中)。
153
+ // 每份 SUMMARY 的两条判据 → 问题描述数组(命中即由调用方计入 violations → BLOCKED)。
154
+ // TASK.md 或 .specs/LESSONS.md 缺席时对应输入为空:段在场判据照常,命中计算自然为空集(无条目可命中)。
220
155
  async function lessonsScanProblems(changeDir, summaryFiles) {
221
156
  if (summaryFiles.length === 0) return [];
222
157
  const rule = await lessonsScanRule();
@@ -233,7 +168,9 @@ async function lessonsScanProblems(changeDir, summaryFiles) {
233
168
  problems.push(file + ' 无法读取(' + String(error?.message ?? error) + ')——LESSONS 扫描判据无法求值');
234
169
  continue;
235
170
  }
236
- const body = lessonsScanBody(content, rule.pattern);
171
+ // 段界由 lib/section-body.mjs 单点决定(围栏内的 `## ` / `---` 是正文示例,不结束段体)。
172
+ // 段缺席 → null(缺声明),与「段在场但正文为空」区分(后者由正文判据另行处理)。
173
+ const body = sectionBody(content, rule.pattern, { level: 2, endOnSeparator: true });
237
174
  if (body === null) {
238
175
  if (rule.required) {
239
176
  problems.push(file + ' 缺 ## ' + rule.name + ' 段(SUMMARY 增量段须声明扫描结果与命中回应'
@@ -253,6 +190,22 @@ async function lessonsScanProblems(changeDir, summaryFiles) {
253
190
  return problems;
254
191
  }
255
192
 
193
+ // SUMMARY 两段的**段头识别**(正则只表达「如何识别段」,段界交给 lib/section-body.mjs 单源):
194
+ // · 「6 维自查」允许模板标题的括注后缀(`## 6 维自查(生产代码改动必填 …)`);
195
+ // · 「自检方法」允许括号后缀——括号是说明不是段名,执行者常按模板标题原样书写。
196
+ // 行锚定(`^`)是必须的:段内正文里引用段名不是段头。
197
+ const SIX_DIM_HEADING_PATTERN = /^##\s*6\s*维自查/u;
198
+ const SELF_CHECK_METHOD_HEADING_PATTERN = /^##\s*自检方法(?:[((][^))\n]*[))])?\s*$/u;
199
+
200
+ // 段体:围栏代码块里的 `## ` / `---` 是正文示例,不结束段体;围栏外的同级标题与分隔线照常结束。
201
+ function summarySixDimBody(content) {
202
+ return sectionBody(content, SIX_DIM_HEADING_PATTERN, { level: 2, endOnSeparator: true });
203
+ }
204
+
205
+ function summarySelfCheckMethodBody(content) {
206
+ return sectionBody(content, SELF_CHECK_METHOD_HEADING_PATTERN, { level: 2, endOnSeparator: true });
207
+ }
208
+
256
209
  // execute / subagent-execute 出口校验每份 SUMMARY 含三个必填段 + 6 维自查非空 + 自检方法声明
257
210
  // (brooks-review / cache-brooks / builtin-quickcheck 三级降级路径)+ LESSONS 扫描段与命中核对
258
211
  export async function runSummarySectionsGate({ node, state }) {
@@ -264,14 +217,13 @@ export async function runSummarySectionsGate({ node, state }) {
264
217
  for (const f of summaryFiles) {
265
218
  try {
266
219
  const content = await fs.readFile(path.join(changeDir, f), 'utf8');
267
- // 段终止 lookahead 用 \n##\s(而非 \n##):###/#### 级子标题(如 "### 🟢 R1")是段内内容,
268
- // 不是段结束。段尾同样 = 段标题 / 分隔线 / 输入末尾;末尾一律写 (?![\s\S]),不得写 \Z
269
- // (JS 无 \Z——它是「字面字符 Z」,且本正则带 i 标志,连小写 z 都会命中,段被静默截断)
270
- const sixDim = content.match(/##\s*6\s*维自查[\s\S]*?(?=\n##\s|\n---|(?![\s\S]))/i);
220
+ // 段界由 lib/section-body.mjs 单点决定(围栏代码块里的 `## ` 是正文示例,不结束段体;围栏外的
221
+ // 同级标题与分隔线照常结束;`###` 级子标题如 "### 🟢 R1" 属段内内容——级别由 level 表达)。
222
+ const sixDimBody = summarySixDimBody(content);
271
223
  // 6 维自查段非空——去掉所有标题行后剩余实质内容 ≥ 10 字符。按行过滤标题(/^\s*#/)比正则
272
224
  // 替换稳健:任何标题格式(emoji 🟢/中英文/数字)都不计入内容
273
- const dimBody = sixDim ? sixDim[0].split('\n').filter(l => !/^\s*#/.test(l)).join('').trim() : '';
274
- if (sixDim && dimBody.length < 10) {
225
+ const dimBody = sixDimBody === null ? '' : sixDimBody.split('\n').filter(l => !/^\s*#/.test(l)).join('').trim();
226
+ if (sixDimBody !== null && dimBody.length < 10) {
275
227
  violations.push(f + ' 的 6 维自查段无实质内容');
276
228
  }
277
229
  // 生产代码任务必填 ## 自检方法,声明 brooks-review 或 builtin-quickcheck。格式兼容:方法名行
@@ -280,65 +232,42 @@ export async function runSummarySectionsGate({ node, state }) {
280
232
  // 段名部分,执行者常按模板标题原样书写导致旧正则不匹配落入"旧格式 WARN";括号后缀与段名等价)。
281
233
  // 分隔符用 .?(任意字符)而非 \.?(字面点):canonical 名 "brooks-review"/"builtin-quickcheck"
282
234
  // 是连字符,与既有 /brooks.?review/ 约定一致。真实项目端到端验证实证:方法名可能在段内后续行
283
- // (子代理列表写法)——段内全文搜索而非仅第一行。段内容截取到下一个段标题(\n## )或分隔线
284
- // (\n---)或文件尾(split 处理,避免 JS 无 \Z 的问题)
285
- const methodMatch = content.match(/##\s*自检方法(?:[((][^))\n]*[))])?\s*\n([\s\S]*)/i);
286
- const methodSection = methodMatch ? methodMatch[1].split(/\n##\s|\n---/)[0] : null;
287
- const method = methodSection ? /brooks.?review|cache.?brooks|builtin.?quickcheck/i.exec(methodSection) : null;
235
+ // (子代理列表写法)——段内全文搜索而非仅第一行。段界同样由单源决定(围栏内的示例标题不截断)
236
+ const methodSection = summarySelfCheckMethodBody(content);
237
+ const method = methodSection === null ? null
238
+ : /brooks.?review|cache.?brooks|builtin.?quickcheck/i.exec(methodSection);
288
239
  if (!method) {
289
- // 过渡规则:旧格式 SUMMARY 无 ## 自检方法 段——若全文已声明 brooks-review/cache-brooks/
290
- // builtin(旧模板行为),WARN 兼容不 BLOCKED;无任何自检声明才 BLOCKED
240
+ // 旧格式 SUMMARY 无 ## 自检方法 段——若全文已声明 brooks-review/cache-brooks/builtin
241
+ // (旧模板行为)按「段缺席」计入 violations(标题必须在场);无任何自检声明同样 BLOCKED。
291
242
  if (/brooks.?review|cache.?brooks|builtin.?quickcheck/i.test(content)) {
292
- if (isNewChange(state)) {
293
- violations.push(f + ' 缺 ## 自检方法 段(新 change 强制声明自检方法)');
294
- } else {
295
- console.error('BROOKS-LINT WARN: ' + f + ' 缺 ## 自检方法 段(旧格式),6 维自查已声明自检方法——兼容通过,建议补全');
296
- }
243
+ violations.push(f + ' 缺 ## 自检方法 段(须声明自检方法)');
297
244
  } else {
298
245
  violations.push(f + ' 缺 ## 自检方法 字段(必须声明 brooks-review 或 builtin-quickcheck)');
299
246
  }
300
247
  } else if (/builtin/i.test(method[0])) {
301
248
  // builtin 降级两级校验——① 必须声明不可用原因;② 必须含缓存尝试证据(已尝试 Read 插件缓存
302
249
  // 协议文件手动执行仍不可行——两级降级路径第 2 级;防「未尝试读缓存」的偷懒降级)。关键词
303
- // 声明级校验(设计边界:不做语义判断);缺失 → 新 change BLOCKED / 旧 SUMMARY WARN 渐进
250
+ // 声明级校验(设计边界:不做语义判断);缺失 → BLOCKED
304
251
  if (!/brooks-lint 不可用|插件不可用|unavailable|N\/A/i.test(content)) {
305
- if (isNewChange(state)) {
306
- console.error('BLOCKED: SUMMARY 使用 builtin-quickcheck 未声明 brooks-lint 不可用原因(新 change 强制);恢复: 在 ## 自检方法 段补原因(声明级校验——须含关键词: brooks-lint 不可用 / 插件不可用 / unavailable / N/A,如「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载)」)');
307
- process.exit(1);
308
- }
309
- console.error('BROOKS-LINT WARN: ' + f + ' 使用 builtin-quickcheck 但未声明 brooks-lint 不可用原因');
252
+ console.error('BLOCKED: SUMMARY 使用 builtin-quickcheck 未声明 brooks-lint 不可用原因;恢复: 在 ## 自检方法 段补原因(声明级校验——须含关键词: brooks-lint 不可用 / 插件不可用 / unavailable / N/A,如「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载)」)');
253
+ process.exit(1);
310
254
  } else if (!/插件缓存|缓存协议|协议文件|plugins\/cache/i.test(content)) {
311
- if (isNewChange(state)) {
312
- console.error('BLOCKED: SUMMARY 使用 builtin-quickcheck 未声明缓存尝试证据(新 change 强制先 Read 插件缓存协议文件);恢复: 在 ## 自检方法 段声明缓存尝试(须含关键词: 插件缓存 / 缓存协议 / 协议文件 / plugins/cache,如「已 Read 插件缓存协议文件(~/.claude/plugins/cache/...)手动执行仍不可行」)');
313
- process.exit(1);
314
- }
315
- console.error('BROOKS-LINT WARN: ' + f + ' 使用 builtin-quickcheck 但未声明缓存尝试证据(应先 Read 插件缓存协议文件手动执行完整 brooks 流程)');
316
- }
317
- }
318
- if (sixDim && !/brooks.?review|cache.?brooks/i.test(sixDim[0])) {
319
- if (isNewChange(state)) {
320
- console.error('BLOCKED: SUMMARY 的 6 维自查未声明使用 /brooks-review(新 change 强制声明自检方法);恢复: 在 6 维自查段声明 /brooks-review 或理由');
255
+ console.error('BLOCKED: SUMMARY 使用 builtin-quickcheck 未声明缓存尝试证据(须先 Read 插件缓存协议文件);恢复: 在 ## 自检方法 段声明缓存尝试(须含关键词: 插件缓存 / 缓存协议 / 协议文件 / plugins/cache,如「已 Read 插件缓存协议文件(~/.claude/plugins/cache/...)手动执行仍不可行」)');
321
256
  process.exit(1);
322
257
  }
323
- console.error('BROOKS-LINT WARN: ' + f + ' 的 6 维自查未声明使用 /brooks-review(可能使用了内置快查)');
258
+ }
259
+ if (sixDimBody !== null && !/brooks.?review|cache.?brooks/i.test(sixDimBody)) {
260
+ console.error('BLOCKED: SUMMARY 的 6 维自查未声明使用 /brooks-review;恢复: 在 6 维自查段声明 /brooks-review 或理由');
261
+ process.exit(1);
324
262
  }
325
263
  } catch {}
326
264
  }
327
- // LESSONS 扫描(AC-18):每份 SUMMARY 的扫描段在场 + 命中条目逐条回应。分级沿用既有语义——
328
- // 新 change BLOCKED / 旧 change WARN(C10 无例外)。
265
+ // LESSONS 扫描(AC-18):每份 SUMMARY 的扫描段在场 + 命中条目逐条回应;缺失即计入 violations。
329
266
  const lessonsProblems = await lessonsScanProblems(changeDir, summaryFiles);
330
- if (lessonsProblems.length > 0) {
331
- if (isNewChange(state)) {
332
- violations.push(...lessonsProblems);
333
- } else {
334
- for (const problem of lessonsProblems) {
335
- console.error('LESSONS SCAN WARN: ' + problem + '(旧 change 渐进,不阻断;新 change 将强制)');
336
- }
337
- }
338
- }
267
+ if (lessonsProblems.length > 0) violations.push(...lessonsProblems);
339
268
  if (violations.length > 0) {
340
269
  console.error('BLOCKED: SUMMARY 关键段校验失败: ' + violations.join('; '));
341
- if (lessonsProblems.length > 0 && isNewChange(state)) {
270
+ if (lessonsProblems.length > 0) {
342
271
  console.error('恢复: 按 flow-kit/templates/SUMMARY.md 在 ## 自检方法 之后补 ## LESSONS 扫描 段,并逐条写出命中条目编号与差异声明(无命中写「无 active 条目命中」);命中来源 = TASK.md 该任务 write_files 的路径段 × .specs/LESSONS.md 条目的关键词行');
343
272
  }
344
273
  process.exit(1);
@@ -390,23 +319,23 @@ export async function runExecuteExitGate({ protocol, node, state, emptyExitAppro
390
319
  && taskDependsOn(blockById.get(t.id) || '').every(d => doneIds.has(d)));
391
320
  if (serialRunnable.length > 0) {
392
321
  console.error('BLOCKED: execute 出口仍有串行 pending 任务: ' + serialRunnable.map(t => t.id).join(', ')
393
- + '——空退出豁免不适用于存在未完成可运行串行任务的情况(先完成该串行任务,或修正任务标记)'
394
- + ';无可执行的常规恢复动作时,可用 workflow-state.mjs advance 渡过结构性死结(逃生口:使用后本节点须重新 entry 并重做交付记录);常规缺产物/缺证据情形不适用');
322
+ + '——空退出豁免不适用于存在未完成可运行串行任务的情况(先完成该串行任务,或修正任务标记)');
323
+ // 恢复动作按目录在哪分两种说法(唯一分叉在 guard-routing 的 recoveryActionText):活动态给
324
+ // advance 逃生口;目录已搬进归档时那一步走不通(advance 的产物推导读活动路径),只给可执行的
325
+ // 那一步——把目录移回活动位置。
326
+ console.error('恢复: ' + recoveryActionText(state.activeChange,
327
+ '无可执行的常规恢复动作时,可用 workflow-state.mjs advance 渡过结构性死结(逃生口:使用后本节点须重新 entry 并重做交付记录);常规缺产物/缺证据情形不适用'));
395
328
  process.exit(1);
396
329
  }
397
330
 
398
- // done 任务 ↔ SUMMARY 完整性:done 任务 ↔ <id>-SUMMARY.md 存在(WARN 渐进不 BLOCK——防旧
399
- // change 卡死;结构级校验与 TASK 签名同源:任务完成声明须有对应产物)。新 change(enter 机制
400
- // 激活)升级为 BLOCKED——执行遗漏(声称完成但无产物)不静默进归档;旧 change 保持渐进。
331
+ // done 任务 ↔ SUMMARY 完整性:done 任务 ↔ <id>-SUMMARY.md 存在(结构级校验与 TASK 签名同源:
332
+ // 任务完成声明须有对应产物)。缺失即 BLOCKED——执行遗漏(声称完成但无产物)不静默进归档。
401
333
  const ki8ChangeDir = path.join(runRoot, '.specs', state.activeChange ?? '');
402
334
  for (const tid of tasks.filter(t => t.status === 'done').map(t => t.id)) {
403
335
  if (!(await fileExists(path.join(ki8ChangeDir, tid + '-SUMMARY.md')))) {
404
- if (isNewChange(state)) {
405
- console.error('BLOCKED: done 任务 ' + tid + ' 缺少 ' + tid + '-SUMMARY.md——execute 产物不完整(新 change 强制任务完成须有对应 SUMMARY;旧 change 渐进 WARN)');
406
- console.error('恢复: 补写 ' + tid + '-SUMMARY.md 后重试 exit;任务完成后补产物即可');
407
- process.exit(1);
408
- }
409
- console.error('WARN: done 任务 ' + tid + ' 缺少 ' + tid + '-SUMMARY.md——execute 产物不完整(任务完成须有对应 SUMMARY)');
336
+ console.error('BLOCKED: done 任务 ' + tid + ' 缺少 ' + tid + '-SUMMARY.md——execute 产物不完整(任务完成须有对应 SUMMARY)');
337
+ console.error('恢复: 补写 ' + tid + '-SUMMARY.md 后重试 exit;任务完成后补产物即可');
338
+ process.exit(1);
410
339
  }
411
340
  }
412
341
 
@@ -447,19 +376,55 @@ export async function runExecuteExitGate({ protocol, node, state, emptyExitAppro
447
376
  && (state.executionMode ?? 'subagent') !== 'direct'
448
377
  && !takeoverApproved
449
378
  && ki10ProtocolHasSubagent) {
450
- if (isNewChange(state)) {
451
- console.error('BLOCKED: TASK 有 parallel done 任务(' + ki10ParallelDone.join(', ')
452
- + ')但 subagent-execute 节点未 exit——新 change 强制 [P] 任务由 subagent-execute 节点委托');
453
- console.error('恢复: 经 subagent-execute 节点完成委托后再 exit;或说明越权委托原因');
454
- process.exit(1);
455
- }
456
- console.error('WARN: TASK 有 parallel done 任务(' + ki10ParallelDone.join(', ')
457
- + ')但 subagent-execute 节点未 exit——疑似 execute 阶段越权委托,[P] 任务应由 subagent-execute 节点委托');
379
+ console.error('BLOCKED: TASK 有 parallel done 任务(' + ki10ParallelDone.join(', ')
380
+ + ')但 subagent-execute 节点未 exit——[P] 任务须由 subagent-execute 节点委托(execute 阶段越权委托)');
381
+ console.error('恢复: 经 subagent-execute 节点完成委托后再 exit;或说明越权委托原因');
382
+ process.exit(1);
458
383
  }
459
384
  } catch {}
460
385
  return { exempt };
461
386
  }
462
387
 
388
+ // AC 覆盖出口校验(verify 出口 BLOCKED / review 出口只汇总 WARN)——判据(纯判定)在
389
+ // lib/ac-coverage.mjs,本处只负责分级与打印:同一份判定两处消费,分支纪律因此只有一处表达。
390
+ // · 判不了的两支按成因分开(与波次判据同口径,见 ac-coverage 文件头):
391
+ // ① **模板缺席**(段名无从派生)→ verify 出口打印「未校验(…)」且**不改变退出码**(判据没有
392
+ // 可判对象;未验证既不冒充通过也不冒充失败)。这是本出口唯一还会放行的「判不了」;
393
+ // ② **工件内容不可判**——**change 自己的载体文件被删**(REQUIREMENT.md / TEST.md 不在)与承载段 /
394
+ // 清单读不出(REQUIREMENT 定位不到验收准则段 / TEST.md 定位不到第 1 轮段 / 没有 AC 编号 /
395
+ // 第 1 轮整段 N/A 而没有 1.1 矩阵)同属这一支 → 不是「判过且通过」:BLOCKED——删文件、
396
+ // 删段都不能换到放行。
397
+ // · 真判过且缺覆盖:verify 出口 BLOCKED(点名缺失编号 + 「在 1.1 矩阵补行」的恢复指引)。
398
+ // · review 出口:一条汇总 WARN(列缺失编号),不阻断、不影响退出码——review 出口今天不要求
399
+ // TEST.md,权威判定在 verify 出口;两支「判不了」都不打印(不制造噪音)。
400
+ // 归档 change 与 verify 出口的既有豁免同源(历史归档不重判)。
401
+ export async function runAcCoverageGate({ node, state }) {
402
+ if (node.id !== 'verify' && node.id !== 'review') return;
403
+ if (!state.activeChange) return;
404
+ if (await isArchivedChange(state.activeChange)) return;
405
+ const coverage = await acCoverageReview(path.join(runRoot, '.specs', state.activeChange));
406
+ if (coverage.unverified !== null) {
407
+ if (node.id === 'verify') console.error(coverage.unverified.notice);
408
+ return;
409
+ }
410
+ if (coverage.unjudgeable !== null) {
411
+ if (node.id === 'review') return;
412
+ for (const line of acCoverageUnjudgeableLines({ coverage, level: 'BLOCKED' })) {
413
+ console.error(line);
414
+ }
415
+ process.exit(1);
416
+ }
417
+ if (coverage.missing.length === 0) return;
418
+ if (node.id === 'review') {
419
+ console.error(acCoverageSummaryLine({ coverage }));
420
+ return;
421
+ }
422
+ for (const line of acCoverageReportLines({ coverage, level: 'BLOCKED' })) {
423
+ console.error(line);
424
+ }
425
+ process.exit(1);
426
+ }
427
+
463
428
  // verify 出口必须真实跑命令(严格版)——历史归档 change 豁免(过渡规则)。命令来源三级:TEST.md 的
464
429
  // ## 验证命令 段 → state 的 verifyCommand → 项目探测回退。失败按 change 隔离计数(≥4 次要求用户
465
430
  // 决策)。二段式执行(受限沙箱兼容):首选管道式捕获,仅当 spawn 层被拒(EPERM)时以继承 stdio
@@ -467,6 +432,10 @@ export async function runExecuteExitGate({ protocol, node, state, emptyExitAppro
467
432
  export async function runVerifyExitGate({ protocol, node, state }) {
468
433
  if (node.id !== 'verify') return;
469
434
  if (await isArchivedChange(state.activeChange)) return;
435
+ // AC 覆盖:结构判据先于命令执行——缺覆盖时不白跑一遍验证命令;「载体缺席」(文件 / 模板根本不在)
436
+ // 只打印不判红(下面的「## 验证命令 / 产物」判据照常),「工件内容不可判」(含承载段被删掉)按
437
+ // change 新旧分级(见 runAcCoverageGate)。
438
+ await runAcCoverageGate({ node, state });
470
439
  // 越权委托兜底检测(verify 出口)——同 execute 出口的判定(TASK parallel done + completedNodes
471
440
  // 无 subagent-execute + 非 direct + 协议含 subagent-execute 节点),verify 时仍未 exit → WARN
472
441
  // 兜底(execute 出口未拦截的提示)
@@ -485,14 +454,10 @@ export async function runVerifyExitGate({ protocol, node, state }) {
485
454
  && (state.executionMode ?? 'subagent') !== 'direct'
486
455
  && !ki9TakeoverApproved
487
456
  && ki9ProtocolHasSubagent) {
488
- if (isNewChange(state)) {
489
- console.error('BLOCKED: TASK 有 parallel done 任务(' + ki9ParallelDone.join(', ')
490
- + ')但 subagent-execute 节点未 exit——新 change 强制(verify 兜底拦截)');
491
- console.error('恢复: 经 subagent-execute 节点完成委托后再 exit;或说明越权委托原因');
492
- process.exit(1);
493
- }
494
- console.error('WARN: TASK 有 parallel done 任务(' + ki9ParallelDone.join(', ')
495
- + ')但 subagent-execute 节点未 exit——疑似越权委托(execute 出口未拦截,verify 兜底提示)');
457
+ console.error('BLOCKED: TASK 有 parallel done 任务(' + ki9ParallelDone.join(', ')
458
+ + ')但 subagent-execute 节点未 exit——[P] 任务须由 subagent-execute 节点委托(verify 兜底拦截)');
459
+ console.error('恢复: 经 subagent-execute 节点完成委托后再 exit;或说明越权委托原因');
460
+ process.exit(1);
496
461
  }
497
462
  } catch {}
498
463
  const { spawnSync } = await import('child_process');
@@ -586,13 +551,9 @@ export function runReturnContractGate({ node, state }) {
586
551
  const noCommitTask = !!(taskReq && taskReq.noCommit === true);
587
552
  if (!r.commitHash && !noCommitTask) violations.push(taskId + ' 缺 commitHash');
588
553
  if (!r.greenEvidence || !r.greenEvidence.command) violations.push(taskId + ' 缺 greenEvidence');
589
- // redEvidence 缺失警告(过渡期不阻断)——新 change(enter 机制激活)升级为 BLOCKED(TDD RED 证据强制)
554
+ // redEvidence 缺失 = 违反 TDD RED 证据要求(BLOCKED)
590
555
  if (r && !r.redEvidence) {
591
- if (isNewChange(state)) {
592
- violations.push(taskId + ' 缺 redEvidence(新 change 强制 TDD RED 证据;旧 change 渐进 WARN)');
593
- } else {
594
- console.error('HANDOFF WARN: ' + taskId + ' 缺 redEvidence(可能未执行 TDD RED 阶段)');
595
- }
556
+ violations.push(taskId + ' 缺 redEvidence(须回传 TDD RED 证据)');
596
557
  }
597
558
  // completedChecks 严格校验(无旧 change 豁免)
598
559
  if (requiredChecks.length > 0) {
@@ -605,7 +566,7 @@ export function runReturnContractGate({ node, state }) {
605
566
  }
606
567
  if (violations.length > 0) {
607
568
  console.error('BLOCKED: Return Contract 校验失败: ' + violations.join('; '));
608
- console.error('恢复: 子代理回传完整契约(含缺失字段)后用 workflow-handoff.mjs result 重录——新 change 强制 TDD RED/GREEN 证据与 completedChecks;注意:若已记录 greenEvidence 而缺 redEvidence,时序防护会拦截事后补录(防掩盖缺 RED)——确认子代理真实执行过 TDD RED 且证据在对应 SUMMARY 中时,用 workflow-state.mjs record subagent-execute 合并写入真实 redEvidence(证据可溯源),或重新委托任务获取完整契约');
569
+ console.error('恢复: 子代理回传完整契约(含缺失字段)后用 workflow-handoff.mjs result 重录——本判据强制 TDD RED/GREEN 证据与 completedChecks;注意:若已记录 greenEvidence 而缺 redEvidence,时序防护会拦截事后补录(防掩盖缺 RED)——确认子代理真实执行过 TDD RED 且证据在对应 SUMMARY 中时,用 workflow-state.mjs record subagent-execute 合并写入真实 redEvidence(证据可溯源),或重新委托任务获取完整契约');
609
570
  process.exit(1);
610
571
  }
611
572
  }
@@ -623,12 +584,9 @@ export async function runSubagentSummaryGate({ node, state }) {
623
584
  const saDir = path.join(runRoot, '.specs', state.activeChange ?? '');
624
585
  for (const t of saTasks.filter(t => t.status === 'done')) {
625
586
  if (!(await fileExists(path.join(saDir, t.id + '-SUMMARY.md')))) {
626
- if (isNewChange(state)) {
627
- console.error('BLOCKED: done 任务 ' + t.id + ' 缺少 ' + t.id + '-SUMMARY.md——subagent-execute 产物不完整(新 change 强制任务完成须有对应 SUMMARY;旧 change 渐进 WARN)');
628
- console.error('恢复: 补写 ' + t.id + '-SUMMARY.md 后重试 exit;任务完成后补产物即可');
629
- process.exit(1);
630
- }
631
- console.error('WARN: done 任务 ' + t.id + ' 缺少 ' + t.id + '-SUMMARY.md——subagent-execute 产物不完整(任务完成须有对应 SUMMARY)');
587
+ console.error('BLOCKED: done 任务 ' + t.id + ' 缺少 ' + t.id + '-SUMMARY.md——subagent-execute 产物不完整(任务完成须有对应 SUMMARY)');
588
+ console.error('恢复: 补写 ' + t.id + '-SUMMARY.md' + ' 后重试 exit;任务完成后补产物即可');
589
+ process.exit(1);
632
590
  }
633
591
  }
634
592
  } catch {}
@@ -693,6 +651,144 @@ export async function runMultiPassCompletionGate({ node, state }) {
693
651
  } catch {}
694
652
  }
695
653
 
654
+ // ---------- 缺证据恢复指引的前置条件(record 自己的技能加载声明门) ----------
655
+ //
656
+ // record 除了写证据,还有一道前置门:节点技能加载声明标记(.specs/<change>/.skill-loads/<node>-*.json)
657
+ // 不在场时 BLOCKED。于是「照抄 record」在缺声明时走不通,而那道门的报文又把执行者推回 exit——恢复
658
+ // 路径被拆成两条报文里的两步。故缺声明时把前置条件与它的命令写进**同一段「恢复:」**(编排在
659
+ // evidenceRecoveryBlock),执行者按一条报文即可走完;已有声明时不加步骤。
660
+ //
661
+ // 判据与 record 前置门同形(<node>-*.json 任一在场即算已声明),但落点不同:state 命令族按状态入口
662
+ // 初始化的运行上下文解析 .specs/,守卫进程没有该上下文,只能按 runRoot 解析——目录解析(活动路径优先、
663
+ // 归档路径兜底)取状态族路径上下文模块(state-io)的同一实现 findSkillLoadsDir,不在此另写一份:本函数
664
+ // 只提供「声明在不在场」这一个判据,路径规则归它。
665
+ async function nodeSkillDeclared(nodeId, changeName) {
666
+ if (!nodeId || !changeName) return false;
667
+ const loadsDir = await findSkillLoadsDir(runRoot, changeName);
668
+ if (loadsDir === null) return false;
669
+ const prefix = nodeId + '-';
670
+ return (await fs.readdir(loadsDir.dir).catch(() => []))
671
+ .some((name) => name.startsWith(prefix) && name.endsWith('.json'));
672
+ }
673
+
674
+ // 守卫族的命令运行上下文(形状与状态命令族的 commandContext 相同):脚本目录由本模块位置推导,
675
+ // 运行根 / 包根 / 协议路径取守卫运行上下文——协议路径是本次 guard 实际解析到的那一份(含 state 绑定),
676
+ // 命令自带的协议上下文因此与本次运行一致。导出给同族门禁(guard-gates)取用:守卫侧的命令装配
677
+ // 只有这一份上下文,各模块自行推一份必然在「架构化路径 / 协议绑定」上分叉。
678
+ export function guardCommandContext() {
679
+ return { scriptsDir, runRoot, packageRoot, protocolPath };
680
+ }
681
+
682
+ // 本节点该声明哪些技能(单一实现:出口声明覆盖门的「要求覆盖」与恢复段的「照抄哪几条命令」共用
683
+ // 同一份判据):协议 requiredSkillCalls 中 enforcement==='guarded' 且**非 handoff scope** 的条目
684
+ // ——handoff scope 的技能由子代理加载,协调者不加载也无法诚实声明(与 record 侧同一口径);
685
+ // 适用性门控的绑定(design 的 ui-design)在判据不成立时不要求声明(非前端本就不加载它,「没声明」
686
+ // 不是缺陷),判据成立时与其它 guarded 技能同权。两处若各判一套,恢复段给出的命令会在下一次 exit
687
+ // 上被另一套判据点名——那正是「照抄走不通」的成因。过滤条件本身取自 protocol-utils(协议面事实)。
688
+ export async function declarationSkillNames(node, state) {
689
+ const skills = guardedDeclarationSkills(node);
690
+ if (skills.length === 0) return [];
691
+ if (!skills.some((skill) => applicabilityGatedBinding(node, skill) !== null)) return skills;
692
+ const frontend = await frontendCriterion(state?.activeChange);
693
+ return skills
694
+ .filter((skill) => applicabilityGatedBinding(node, skill) === null || frontend.applicable === true);
695
+ }
696
+
697
+ // 「怎么重新声明技能加载」的完整形态(命令文本的单一来源:缺证据恢复段的第一步、出口声明覆盖门的补齐
698
+ // 命令、门控绑定缺证据的补证据步骤三处都从这里取,与状态命令族同一装配 state-explain 的
699
+ // declarationCommands)——三面同时给全,缺一照抄后必被另一道门拦一次:
700
+ // · 该节点**全部**协议文件 → 多个 --prompt(open / review 各两份:只给首份,覆盖门会点名另一份);
701
+ // 前端 change 上还要并上该节点的条件提示词(design 的 2a-ui-design.md——入口会打印那一行,声明
702
+ // 却漏掉它,ui-design 的命令就与它该读的协议对不上);
703
+ // · 该节点的模板全清单 → --templates(零模板节点省略,省略即空集;漏了会被模板门拦下);
704
+ // · 技能按 declarationSkillNames 逐个展开——一条命令只写一个技能标记,故每个必需技能各一条。
705
+ // 没有任何 guarded 必需技能(自定义协议节点 / 只有 handoff 绑定的 subagent-execute)时退回协议面
706
+ // 已有的技能名(protocol-utils 的 declarationSkillFallback:实现技能 → 非 handoff 既有条目 → 占位符)。
707
+ //
708
+ // 返回命令条目 { skill, command }(命令文本的构造在 state-explain,本函数只决定「哪些技能」)。
709
+ function skillLoadDeclarationCommands({ node, skills, frontend }) {
710
+ return declarationCommands({ node, skills, frontend, context: guardCommandContext() });
711
+ }
712
+
713
+ export async function nodeSkillLoadCommands({ node, state }) {
714
+ const required = await declarationSkillNames(node, state);
715
+ const targets = required.length > 0 ? required : [declarationSkillFallback(node)];
716
+ const frontend = (NODE_CONDITIONAL_PROMPTS[node.id] ?? []).length > 0
717
+ && (await frontendCriterion(state?.activeChange)).applicable === true;
718
+ return skillLoadDeclarationCommands({ node, skills: targets, frontend });
719
+ }
720
+
721
+ // 单个技能的声明命令(入口 --prompt 冲突的兜底:标记声明的技能不在本节点目标集里时,仍要给一条
722
+ // 覆写该标记的命令)。与上面同一装配,不另拼一份文本。
723
+ export function guardDeclarationCommand({ node, skill, frontend = false }) {
724
+ return declarationCommand({ node, skill, frontend, context: guardCommandContext() });
725
+ }
726
+
727
+ // record 命令与「这条命令怎么执行」的说明分行给出(两处恢复段共用):命令单独成行才是可整行照抄的
728
+ // 片段——说明接在命令行尾时,整行丢给 shell 会把说明当成参数(载荷因此被拼成不合法 JSON:命令看起来
729
+ // 在场,照抄即失败)。说明行以「说明:」开头,与命令行的判别只靠行首(断言据此把两者分开)。
730
+ const RECORD_RETRY_NOTE = '说明: bash / PowerShell 可直接执行;cmd.exe 请把单引号换成双引号,'
731
+ + '并转义载荷里原有的双引号';
732
+
733
+ // 任意节点 + 任意载荷的 record 命令(命令文本的唯一装配:脚本路径平台化 + 整条加引号 + 协议上下文)。
734
+ // 缺证据恢复段、门控补证据段、归档提名的补录命令三处都从这里取——各自拼一段,就只有在其中一条上
735
+ // 补得到协议上下文/引号形态,另外两条照抄即失败。
736
+ export function nodeRecordCommand(nodeId, payload) {
737
+ return scriptCommand({
738
+ scriptsDir,
739
+ runRoot,
740
+ script: 'workflow-state.mjs',
741
+ args: ['record', nodeId, "'" + JSON.stringify(payload) + "'", ...protocolContextArgs(guardCommandContext())],
742
+ });
743
+ }
744
+
745
+ function recordRecoveryCommand(node, completedChecks = []) {
746
+ const payload = { summary: '<本节点完成摘要>' };
747
+ if (completedChecks.length > 0) payload.completedChecks = completedChecks;
748
+ return nodeRecordCommand(node.id, payload);
749
+ }
750
+
751
+ // 「补证据」恢复段(单一实现):两个门禁点打印同一段——缺 Output Schema 字段
752
+ // (runEvidenceCompletionGate)与完全没有证据对象(guard-gates 的 requireNodeEvidence)。两处说的
753
+ // 是同一件事(节点已完成、证据不在),各自拼一份必然分叉:一条带协议上下文与前置声明步骤、另一条
754
+ // 只剩 record,照抄的人在半路撞上 record 自己的声明门,还要回头去另一条报文里找第二步的命令。
755
+ //
756
+ // 形态只由「本节点技能声明在不在场」决定,与哪道门命中无关:
757
+ // · 声明已在场 → 一步:record 补证据;
758
+ // · 缺声明 → 两步,按**执行顺序**(第一步声明技能加载、第二步 record)——record 有自己的前置
759
+ // 门,照抄它之前必须先声明;步骤标注跟着各自的命令走(从上往下抄一遍就通)。
760
+ // lead 是**本门禁**对「它看到缺了什么」的点名(不同的门看到的缺项不同,恢复段的其余部分不随之分叉);
761
+ // 命令文本、参数段、尾部重试提示与步骤编排都只在这里产出(返回值 = 该段按序打印的各行)。
762
+ // 异步只为读声明标记:两个调用点都在可 await 的位置(缺证据门在出口链上,调用位随之声明 async)。
763
+ export async function evidenceRecoveryBlock({ node, state, lead = null }) {
764
+ const recordCommand = recordRecoveryCommand(node);
765
+ const leadPrefix = lead === null ? '' : lead + '——';
766
+ if (!state.activeChange || (await nodeSkillDeclared(node.id, state.activeChange))) {
767
+ return [
768
+ '恢复: ' + leadPrefix + '照抄下面的命令补齐它后重试 exit:',
769
+ ' ' + recordCommand,
770
+ ' ' + RECORD_RETRY_NOTE,
771
+ ];
772
+ }
773
+ // 第一步的命令由协议派生(nodeSkillLoadCommands):该节点全部协议文件(多个 --prompt)、每个
774
+ // guarded 必需技能各一条(含该节点的模板全清单)。三面正是出口声明覆盖门与模板门核对的东西
775
+ // ——旧形态只声明实现技能 + 首份协议、且不带模板清单时,照抄完同一 exit 仍会被拦(恢复步骤自己
776
+ // 走不通)。单声明节点(只有一个必需技能)因此仍是一条命令,不因派生多出步骤。
777
+ const declarations = await nodeSkillLoadCommands({ node, state });
778
+ const placeholder = declarations.some((entry) => entry.skill === '<skill>');
779
+ return [
780
+ '恢复: ' + leadPrefix + '本节点还缺技能加载声明(.skill-loads/' + node.id + '-*.json,'
781
+ + '新 change 下 record 会先被它拦下)'
782
+ + (lead === null ? '——按下面的顺序走完两步后重试 exit:' : ';按下面的顺序走完两步后重试 exit:'),
783
+ ' 第一步 声明本节点技能加载'
784
+ + (placeholder ? '(技能名按 entry 的 LOAD SKILL 行填,下面用 <skill> 占位):' : ':'),
785
+ ...declarations.map((entry) => ' ' + entry.command),
786
+ ' 第二步 补证据并重试 exit:',
787
+ ' ' + recordCommand,
788
+ ' ' + RECORD_RETRY_NOTE,
789
+ ];
790
+ }
791
+
696
792
  // 自动补 required-skill completedChecks——节点被完成即视为其实现 skill 已加载。分派(ui-design 门):
697
793
  // 仅「guarded 且适用性判据成立(判前端)」的登记绑定在**新 change** 上停止自动补——该绑定须真实
698
794
  // skill-load 声明,由后续 missingRequiredSkillChecks 拦截;判据不成立(非前端)、旧 change(渐进
@@ -704,7 +800,7 @@ export async function runEvidenceCompletionGate({ protocol, node, state, evidenc
704
800
  for (const binding of node.requiredSkillCalls ?? []) {
705
801
  const check = 'required-skill:' + node.id + '.' + binding.skill;
706
802
  const applicabilityGated = applicabilityGatedBinding(node, binding.skill) !== null;
707
- if (applicabilityGated && isNewChange(state) && (await frontendCriterion(state.activeChange)).applicable) continue;
803
+ if (applicabilityGated && (await frontendCriterion(state.activeChange)).applicable) continue;
708
804
  if (!checks.includes(check)) checks.push(check);
709
805
  }
710
806
  evidence.completedChecks = checks;
@@ -712,6 +808,10 @@ export async function runEvidenceCompletionGate({ protocol, node, state, evidenc
712
808
  const missingSchemaEvidence = missingRequiredSchemaEvidence(protocol, node, evidence);
713
809
  if (missingSchemaEvidence.length > 0) {
714
810
  console.error('BLOCKED: missing Output Schema evidence: ' + missingSchemaEvidence.join(', '));
811
+ // 阻塞消息给可照抄的下一步:record 只写 summary 即视为产出证据(与判据同一口径),照抄执行后同一
812
+ // exit 即可通过——不再让执行者从字段清单反推该跑什么命令。恢复段取单一实现(guard-gates 的前置
813
+ // 门打印同一段):缺声明时两步、声明在场时一步,两处同形(顺序、命令、协议上下文都同源)。
814
+ console.error((await evidenceRecoveryBlock({ node, state })).join('\n'));
715
815
  process.exit(1);
716
816
  }
717
817
  }
@@ -720,6 +820,14 @@ export async function runEvidenceCompletionGate({ protocol, node, state, evidenc
720
820
  // (全 parallel 无 SUMMARY 属预期);含串行任务的 change 豁免不生效,照常校验,不得静默放行。生效
721
821
  // 时追加被跳过项清单(EMPTY-EXIT-SKIPPED)。
722
822
  export async function runArtifactGate({ protocol, node, state, emptyExitApproved, emptyExitExempt }) {
823
+ // 归档目录名不合规(AC-6):本 change 的归档目录在盘上但名字不是 <YYYY-MM-DD>-<change-id> —— 这条
824
+ // 规则先于在场判定失败,报文给期望格式 + 实际目录名 + 可照抄的改名命令。放在缺件之前:错名目录不是
825
+ // 「某件产物不在场」,报成缺件会让人去补一件其实存在的产物(同一事实两种说法)。
826
+ const archiveNameProblems = archiveDirNameNotice(state.activeChange, node.id);
827
+ if (archiveNameProblems.length > 0) {
828
+ for (const line of archiveNameProblems) console.error(line);
829
+ process.exit(1);
830
+ }
723
831
  const checkedArtifacts = await missingRequiredArtifacts(protocol, node, state.activeChange);
724
832
  let missingArtifacts = checkedArtifacts;
725
833
  if (emptyExitApproved && emptyExitExempt) {
@@ -732,19 +840,49 @@ export async function runArtifactGate({ protocol, node, state, emptyExitApproved
732
840
  }
733
841
  }
734
842
 
735
- // required-skill / augmentation 声明门禁:适用性门控绑定缺的是「真实 skill-load 声明」(出口不再
736
- // 自动补写)——给出补齐路径(判据与该门同源:applicabilityGatedBinding 查询,不另写键表)
843
+ // 受适用性门控的绑定缺证据时的「怎么补」——两件事必须同一段给全,缺一照抄完都还会撞同一道门:
844
+ // ① 真实 skill-load 声明:命令与缺证据恢复段同源(skillLoadDeclarationCommands——每个 guarded 必需
845
+ // 技能各一条,每条带该节点全部 --prompt(前端含条件提示词)与模板全清单);
846
+ // ② 带该 required-skill 的 record:出口只对**非**门控绑定自动补写,声明了却不把这条写进证据,同
847
+ // 一个 exit 仍会点名同一条(旧报文正是这个形态:占位提示词 + 不提 record = 死循环)。
848
+ // 前端判据在此不必再问一次:这条检查还能缺,前提就是本 change 为新 change 且判前端——判据不成立或
849
+ // 旧 change 时出口会把它自动补进证据(那里没有缺口),故条件提示词按适用计入。
850
+ function requiredSkillEvidenceRecovery({ node, evidence, missingChecks }) {
851
+ // 声明目标与覆盖门同一份判据(guarded ∧ 非 handoff):一次把该技能组全声明掉,下一步的覆盖门
852
+ // 因此不会再点名任何一条。
853
+ const gated = guardedDeclarationSkills(node);
854
+ const declarations = skillLoadDeclarationCommands({
855
+ node,
856
+ skills: gated.length > 0 ? gated : [declarationSkillFallback(node)],
857
+ frontend: true,
858
+ });
859
+ // 载荷写回**完整**清单(既有 ∪ 缺的):只写缺的那条,会把另一条已成立的 gated 声明抹掉——下一次
860
+ // exit 反过来点名它(同一个死循环的镜像形态)。
861
+ const checks = Array.isArray(evidence?.completedChecks) ? [...evidence.completedChecks] : [];
862
+ for (const check of missingChecks) if (!checks.includes(check)) checks.push(check);
863
+ return [
864
+ '恢复: ' + missingChecks.join('、') + ' 不再由出口自动补写(guarded + 适用性判据成立)'
865
+ + '——按下面的顺序走完两步后重试 exit:',
866
+ ' 第一步 声明本节点技能加载:',
867
+ ...declarations.map((entry) => ' ' + entry.command),
868
+ ' 第二步 补证据(record 载荷带上 ' + missingChecks.join('、') + '):',
869
+ ' ' + recordRecoveryCommand(node, checks),
870
+ ' ' + RECORD_RETRY_NOTE,
871
+ ].join('\n');
872
+ }
873
+
874
+ // required-skill / augmentation 声明门禁:适用性门控绑定缺的是「真实 skill-load 声明 + 带上该条的
875
+ // 证据」(出口对该绑定不再自动补写)——恢复段两件事同一段给全(判据与该门同源:applicabilityGatedBinding
876
+ // 查询,不另写键表;命令装配与缺证据恢复段同源 skillLoadDeclarationCommands,不手拼半边命令)。
737
877
  export function runRequiredEvidenceGate({ node, evidence }) {
738
878
  const missingRequired = missingRequiredSkillChecks(node, evidence);
739
879
  if (missingRequired.length > 0) {
740
880
  console.error('BLOCKED: missing required Skill evidence: ' + missingRequired.join(', '));
741
- for (const binding of node.requiredSkillCalls ?? []) {
742
- const check = 'required-skill:' + node.id + '.' + binding.skill;
743
- if (missingRequired.includes(check) && applicabilityGatedBinding(node, binding.skill) !== null) {
744
- console.error('恢复: ' + check + ' 不再由出口自动补写(guarded + 适用性判据成立)——先加载 ' + binding.skill
745
- + ' 并运行 workflow-state.mjs skill-load ' + node.id + ' ' + binding.skill
746
- + ' --prompt <flow-kit/prompts/ 协议文件> 声明已加载后重试 exit');
747
- }
881
+ const gatedMissing = missingRequired.filter((check) => (node.requiredSkillCalls ?? []).some((binding) => binding
882
+ && 'required-skill:' + node.id + '.' + binding.skill === check
883
+ && applicabilityGatedBinding(node, binding.skill) !== null));
884
+ if (gatedMissing.length > 0) {
885
+ console.error(requiredSkillEvidenceRecovery({ node, evidence, missingChecks: gatedMissing }));
748
886
  }
749
887
  process.exit(1);
750
888
  }