flow-comet 1.6.5 → 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 (61) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +17 -5
  3. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +23 -4
  5. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  6. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
  7. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +97 -3
  8. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +38 -2
  9. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  10. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +16 -3
  11. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +2 -0
  12. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +4 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +20 -11
  14. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  15. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
  16. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +297 -131
  17. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +616 -151
  18. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +96 -45
  19. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  20. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +204 -51
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +7 -9
  22. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  23. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  24. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  25. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +38 -20
  26. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +439 -134
  27. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
  29. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
  30. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +94 -39
  31. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +6 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  33. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +57 -7
  34. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
  35. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +158 -3
  36. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
  37. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +92 -17
  38. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1439 -11
  39. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
  40. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1204 -76
  41. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
  42. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +32 -1
  43. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
  44. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +5 -0
  45. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +16 -0
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +5 -0
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2041 -66
  50. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
  51. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
  52. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
  53. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  54. package/.flow-comet/skills/flow-comet-execute/SKILL.md +30 -6
  55. package/.flow-comet/skills/flow-comet-plan/SKILL.md +10 -3
  56. package/.flow-comet/skills/flow-comet-review/SKILL.md +20 -11
  57. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +33 -8
  58. package/.flow-comet/skills/flow-comet-task/SKILL.md +2 -1
  59. package/README.md +1 -1
  60. package/package.json +1 -1
  61. package/scripts/dsh-bridge.mjs +2 -2
@@ -0,0 +1,317 @@
1
+ // ac-coverage.mjs — AC 覆盖判定(纯判定:无 console、无 process.exit、无写盘)。
2
+ //
3
+ // 语义:REQUIREMENT.md 的「验收准则」段声明本 change 的验收准则(AC-N);TEST.md 的「1.1 测试矩阵
4
+ // (AC → 用例)」段是这些准则的用例映射(测试阶段派生用例的唯一来源)。覆盖判定 = 每条 AC 编号都在
5
+ // 1.1 段文本里出现过(存在级:只保证「写了」,不保证「测得对」——后者属内容语义,由 review 的人看)。
6
+ //
7
+ // 段名不在这里写死(模板权威单链,L-067):三个段的定位全部走 guard-routing 的选段入口
8
+ // (templateSectionPatterns().pick 与同一份选段规则的另一入口 pickTemplateSection)——本模块不再自己遍历
9
+ // 骨架段名表找关键词:
10
+ // · 验收段:'requirement' 的 H2 段名里选段,与 **open 出口的验收段判据同一调用**(同一关键词、
11
+ // 同一回退清单),因此「入口说缺段 / verify 说未校验」这类两处两判不再可能发生;
12
+ // · 第 1 轮段:'TEST' 的 H2 段名里按关键词选段——它是 1.1 矩阵的**承载段**(见下方二分);
13
+ // · 1.1 矩阵段:'TEST' 的结构子段(登记名「1.1 测试矩阵(AC → 用例)」)。
14
+ // 选出来的段名统一交给**共享段标题谓词**(guard-artifact-skeleton 的 headingPredicate:级别 + 段名
15
+ // 归一后相等)判定「这一行是不是那一段」。本模块不再持行正则:标题正文本身可以以井号开头
16
+ // (`## ## 验收准则(AC)`),段形门认作在场而按整行锚定的正则判缺席——同一份工件的同一段两处两判
17
+ // (假红,恢复句还指向补段)。归一在标题文本层,井号 / 编号前缀 / 尾部括号 / 闭合 ATX / 大小写因此
18
+ // 都不是判定变量。
19
+ //
20
+ // 「判不了」按成因二分——本节是**本仓结构判据的唯一形态**(波次判据 wave-projection.mjs 与它同形,
21
+ // 第三个结构判据照抄这组字段即可,不必再选一次):
22
+ // { unverified: { reason, notice } | null, unjudgeable: { reason, explanation, recovery } | null, ... }
23
+ // 留下的理由:载荷跟着分类走(notice 可直接打印;explanation + recovery 是「解释 + 出路」两半),
24
+ // 调用方按字段出现与否分级、不必按 reason 反查第二张表;与之相对的 { judgeable, reason } 形态把
25
+ // 「能否判定」和「成因」压进一个字符串,调用方只能从取值反推分级。
26
+ // · **模板缺席**(段名无从派生)——判据没有可判对象(模板不是这个 change 的文件,作者改不动
27
+ // 它)⇒ 调用方打印「未校验」并放行,不改退出码。这是「未校验」一支**唯一**的成因;
28
+ // · **工件内容不可判**——两类形态、同一分级:① 文件与模板都在场,缺的是**承载段本身或段内
29
+ // 清单**(REQUIREMENT 在场却定位不到验收准则段;验收段在而无任何 AC-N 编号;TEST.md 在场却
30
+ // 定位不到第 1 轮段;第 1 轮段在而段内没有 1.1 矩阵段,即「整段 N/A」);② **change 自己的
31
+ // 载体文件缺席**(REQUIREMENT.md / TEST.md 不在)——这两个文件是这个 change 自己的东西,作者
32
+ // 抬手就能删,删掉它换不到「没有可判对象」。两支同属「不是判过且通过」,调用方按既有分级:
33
+ // 新 change BLOCKED / 旧 change WARN(WARN 行进入既有 WARN COUNT)。删段、删文件因此都不是
34
+ // 关掉判据的写法,出路只有「按模板把段、清单与文件补回来」。
35
+ //
36
+ // 词法:AC-<数字>,大小写不敏感;AC-1a 归并到 AC-1(后缀不参与编号),AC-01 与 AC-1 归一为同一编号;
37
+ // 同一行多个编号全部收集;编号按 REQUIREMENT 里的出现顺序(首见)去重——报告顺序因此与台账顺序
38
+ // 一致,便于逐条对照。**围栏代码块里的编号不算数**:两侧同口径——矩阵段里贴一段书写样例(表格
39
+ // 示例行)不得被读成「覆盖了」,验收段里贴的编号样例也不得被读成「声明了」;围栏内是示例,
40
+ // 围栏外才是台账。段界本身由 sectionBody 跨围栏给出(围栏内的 `## ` 不结束段体),编号扫描再
41
+ // 过一次围栏状态——两件事各管一段:前者决定读多远,后者决定读到的哪些真算数。
42
+ //
43
+ // 分级(新 change BLOCK / 旧 change WARN、review 出口只汇总)不在这里判:本模块只产出判定结果与
44
+ // 报文文本,console / exit 只在门禁层(与「纯判定 + 门禁编排」的既有分层一致)。
45
+ import { promises as fs } from 'fs';
46
+ import path from 'path';
47
+ import {
48
+ TEMPLATE_FALLBACK_SECTION_NAMES,
49
+ TEMPLATE_FALLBACK_SECTION_PATTERNS,
50
+ buildSkeleton,
51
+ headingPredicate,
52
+ } from './guard-artifact-skeleton.mjs';
53
+ import {
54
+ TEMPLATE_SECTION_SKIP,
55
+ pickTemplateSection,
56
+ templateSectionPattern,
57
+ templateSectionPatterns,
58
+ } from './guard-routing.mjs';
59
+ // 段界(同级标题 / 围栏 / 分隔线 / 文末)取 lib/section-body.mjs 的唯一实现:矩阵段里贴一段示例
60
+ // (围栏内的 `## …`)时,段被提前截断会**少读后面的 AC 编号**——那正是本判据的输入,静默少读会把
61
+ // 「没覆盖」读成「覆盖了」(假绿)。
62
+ import { isFenceLine, sectionBody } from './section-body.mjs';
63
+
64
+ // 验收段的关键词:与 open 出口的验收段判据**同一个列表**('验收')。此处刻意不把 AC / Acceptance
65
+ // 加进来——它们已由回退基准(TEMPLATE_FALLBACK_SECTION_PATTERNS.requirementAcceptance)覆盖,
66
+ // 而多加一个关键词会让入口与 verify 出口对同一份模板选出不同的段。
67
+ const ACCEPTANCE_SECTION_KEYWORDS = ['验收'];
68
+ // 第 1 轮段与 1.1 矩阵段的关键词(前者是后者的承载段,两者都从模板派生)。
69
+ const TEST_ROUND_SECTION_KEYWORDS = ['第 1 轮'];
70
+ const TEST_MATRIX_SECTION_KEYWORDS = ['测试矩阵'];
71
+ // 关键词全不命中时的回退**段名**(模板在场却把段名换成了别的说法——上游改标题措辞是常见形态)。
72
+ // 1.1 矩阵回退到登记词「测试矩阵」(编号前缀 / 尾部括号 / 闭合 ATX 由共享归一吃掉);第 1 轮段的落地
73
+ // 标题带分隔符与子标题,故把既有写法列全(尾部括号同样由归一吃掉)。
74
+ const TEST_ROUND_FALLBACK_NAMES = ['第 1 轮 · 功能测试', '第 1 轮:功能测试', '第 1 轮 功能测试', '第 1 轮'];
75
+ const TEST_MATRIX_FALLBACK_NAMES = ['测试矩阵'];
76
+ // AC 编号词法:只认 AC-<数字>;后缀(如 AC-1a 的 a)不参与编号,前导零同样归一到数字值。
77
+ const AC_TOKEN_RE = /AC-(\d+)/giu;
78
+
79
+ // 文本归一(BOM / 行尾):段定位与编号解析共用同一口径——行尾差异是检出的噪音。
80
+ function normalizeText(text) {
81
+ return String(text ?? '').replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n');
82
+ }
83
+
84
+ // 读文件:读不到(缺席 / 无权限)一律 null——「无从判断」由调用方按「未校验」处理,不在这里吞成空串
85
+ // (空串会被读成「段在场但没有编号」)。
86
+ async function readText(filePath) {
87
+ try {
88
+ return await fs.readFile(filePath, 'utf8');
89
+ } catch {
90
+ return null;
91
+ }
92
+ }
93
+
94
+ // 选中判据 → 段标题谓词。选段规则仍只在 guard-routing 一处(本模块不遍历骨架段名表挑关键词):
95
+ // 这里只把**选中的判据**还原成它背后的登记名,再交给共享归一比较(headingPredicate:级别 + 段名
96
+ // 归一后相等,与 TASK 段形门、波次门同一套)。选中的是回退判据时没有登记名可比(模板段名已不含
97
+ // 关键词),按调用方登记的回退名清单比较——两种情形都是「标题正文归一后与段名相等」,不再有「拿标题
98
+ // 行跑正则」这一支。选段入口返回 TEMPLATE_SECTION_SKIP(模板整份缺席)时原样上抛。
99
+ async function sectionMatcher(picked, { key, level, fallbackNames }) {
100
+ if (picked === TEMPLATE_SECTION_SKIP) return TEMPLATE_SECTION_SKIP;
101
+ const skeleton = await buildSkeleton(key);
102
+ const entries = level === 3 ? skeleton.structureSubsections ?? [] : skeleton.sections;
103
+ const selected = entries.find((entry) => entry.pattern.source === picked.source
104
+ && entry.pattern.flags === picked.flags);
105
+ return headingPredicate(selected === undefined ? fallbackNames : selected.name, level);
106
+ }
107
+
108
+ // 三个段的判据全部经 guard-routing 的选段入口派生(返回值可能是 TEMPLATE_SECTION_SKIP:模板整份
109
+ // 缺席 ⇒ 该段名无从派生 ⇒ 调用方按「载体缺席」打印未校验,而不是拿一个猜的段名去判)。验收段走
110
+ // templateSectionPatterns().pick——与 open 出口的验收段判据同一调用形态;TEST 的两个段走
111
+ // pickTemplateSection(pick 的键只覆盖四个 H2 模板,TEST 与结构子段不在其内,选段规则仍是同一份
112
+ // pickByKeywords)。三处的回退判据只是「落到回退」的标记(选段入口的返回契约是「正则或跳过」),
113
+ // 真正逐标题比较的是上面的回退名清单——判据与清单由同一份名字派生,不会各说一套。
114
+ async function acceptanceSectionMatcher() {
115
+ const patterns = await templateSectionPatterns();
116
+ const picked = patterns.pick(
117
+ 'requirement', ACCEPTANCE_SECTION_KEYWORDS, TEMPLATE_FALLBACK_SECTION_PATTERNS.requirementAcceptance);
118
+ return sectionMatcher(picked, {
119
+ key: 'requirement',
120
+ level: 2,
121
+ fallbackNames: TEMPLATE_FALLBACK_SECTION_NAMES.requirementAcceptance,
122
+ });
123
+ }
124
+
125
+ async function testRoundSectionMatcher() {
126
+ const picked = await pickTemplateSection('TEST', {
127
+ keywords: TEST_ROUND_SECTION_KEYWORDS,
128
+ fallback: templateSectionPattern(TEST_ROUND_FALLBACK_NAMES[0], 2),
129
+ level: 2,
130
+ });
131
+ return sectionMatcher(picked, { key: 'TEST', level: 2, fallbackNames: TEST_ROUND_FALLBACK_NAMES });
132
+ }
133
+
134
+ async function testMatrixSectionMatcher() {
135
+ const picked = await pickTemplateSection('TEST', {
136
+ keywords: TEST_MATRIX_SECTION_KEYWORDS,
137
+ fallback: templateSectionPattern(TEST_MATRIX_FALLBACK_NAMES[0], 3),
138
+ level: 3,
139
+ });
140
+ return sectionMatcher(picked, { key: 'TEST', level: 3, fallbackNames: TEST_MATRIX_FALLBACK_NAMES });
141
+ }
142
+
143
+ // 段文本 → AC 编号(规范形态 AC-<n>,按首见顺序去重)。围栏行与围栏内的行全部跳过(围栏语法取
144
+ // section-body 的 isFenceLine 单一实现):不跳过时,矩阵段里贴一段围栏示例表格就把示例里的
145
+ // 编号读成了覆盖行(假绿),验收段里贴示例则把示例读成声明。
146
+ export function parseAcIds(body) {
147
+ const ids = [];
148
+ const seen = new Set();
149
+ let inFence = false;
150
+ for (const line of normalizeText(body).split('\n')) {
151
+ if (isFenceLine(line)) {
152
+ inFence = !inFence;
153
+ continue;
154
+ }
155
+ if (inFence) continue;
156
+ for (const matched of line.matchAll(AC_TOKEN_RE)) {
157
+ const id = 'AC-' + String(Number(matched[1]));
158
+ if (seen.has(id)) continue;
159
+ seen.add(id);
160
+ ids.push(id);
161
+ }
162
+ }
163
+ return ids;
164
+ }
165
+
166
+ // 「未校验」这一支只收**模板缺席**(判据真的没有可判对象,而模板不是这个 change 的文件):其它成因
167
+ // 都是作者自己能动的东西,落进下一张表。notice 由解释派生(reason 是机器可读的短句)——两种调用方
168
+ // (verify 出口 / review 出口)打印同一份文本,同一事实两处措辞必然先漂移。
169
+ const UNVERIFIED_EXPLANATIONS = {
170
+ '模板缺席(段名无从派生)': '模板不可派生,验收段 / 1.1 矩阵段的段名无从定位',
171
+ };
172
+
173
+ // 「工件内容不可判」的成因,两类形态:① **载体文件缺席**(REQUIREMENT.md / TEST.md 不在——作者
174
+ // 自己能删的东西,删掉它换不到「没有可判对象」);② **承载段本身或段内清单读不出**(文件与模板都
175
+ // 在场)。每条成因自带**解释 + 恢复出路**(同一件事的两半写在一处:只有解释没有出路,人只能猜下一
176
+ // 步;只有出路没有解释,人不知道该改哪一环)。恢复指引必须能照做——补文件 / 补承载段 / 补编号 /
177
+ // 补矩阵段都是作者当场能落笔的动作(「把 N/A 改成通过」不是出路:没有矩阵就仍无从对账)。
178
+ // 两个载体文件缺席排在最前:文件不在时连「有没有段」都无从谈起,报文要先说要补回哪份文件;承载段
179
+ // 缺席的两支排在清单那两支之前——没有承载段就没有清单可读。
180
+ const UNJUDGEABLE_CAUSES = {
181
+ 'REQUIREMENT 缺席': {
182
+ explanation: '该 change 没有 REQUIREMENT.md——载体文件不在,验收准则无从读取(文件是这个 change'
183
+ + '自己的东西,作者能删掉它,所以这不是「没有可判对象」)',
184
+ recovery: '补回 REQUIREMENT.md(「## 验收准则(AC)」段 + 每条准则的 AC-N 编号)后重试 exit verify',
185
+ },
186
+ 'TEST.md 缺席': {
187
+ explanation: '该 change 没有 TEST.md——载体文件不在,1.1 测试矩阵无从读取(同 REQUIREMENT 缺席:'
188
+ + '作者能删掉的文件不是「没有可判对象」)',
189
+ recovery: '补回 TEST.md(「## 验证命令」段 + 「## 第 1 轮 · 功能测试」里的 1.1 测试矩阵)后重试 exit verify',
190
+ },
191
+ 'REQUIREMENT 无验收准则段': {
192
+ explanation: 'REQUIREMENT.md 在场、模板也在场,但段名(模板派生 + 回退基准)定位不到验收准则段'
193
+ + '——承载段不在,判据没有可对账的准则清单(删掉一个段不等于判据无从判断)',
194
+ recovery: '在 REQUIREMENT.md 里补「## 验收准则(AC)」段,并给每条准则编号(形如 AC-1、AC-2 …,'
195
+ + '编号写在标题或列表项里均可);补完重试 exit verify',
196
+ },
197
+ 'REQUIREMENT 无 AC 编号': {
198
+ explanation: 'REQUIREMENT.md 有验收准则段却没有 AC-N 编号——没有编号就没有可对账的清单',
199
+ recovery: '给验收准则的每条准则编号(形如 AC-1、AC-2 …,编号写在标题或列表项里均可),编号后重试 exit verify',
200
+ },
201
+ 'TEST.md 无第 1 轮段': {
202
+ explanation: 'TEST.md 在场、模板也在场,但段名定位不到 1.1 测试矩阵的承载段(第 1 轮 · 功能测试)'
203
+ + '——承载段不在,AC 与用例的映射读不出来',
204
+ recovery: '在 TEST.md 里补「## 第 1 轮 · 功能测试」段,并在其中补 1.1 测试矩阵'
205
+ + '(每条 AC 一行:| AC-N | 类型 | 用例文件 / UAT | 状态 |);补完重试 exit verify',
206
+ },
207
+ 'TEST.md 第 1 轮无 1.1 测试矩阵段': {
208
+ explanation: 'TEST.md 的第 1 轮段在场,但段内没有 1.1 测试矩阵段(整段写 N/A 就是这一形态)'
209
+ + '——AC 与用例的映射读不出来',
210
+ recovery: '在 TEST.md 的第 1 轮内补 1.1 测试矩阵段(每条 AC 一行:| AC-N | 类型 | 用例文件 / UAT | 状态 |),'
211
+ + '补完重试 exit verify;整段写 N/A 不构成测试矩阵',
212
+ },
213
+ };
214
+
215
+ // 判不了时返回的判定结果形态:两个成因字段互斥,调用方按「模板缺席 → 未校验放行」/「内容不可判 →
216
+ // 按 change 新旧分级」两支处置。
217
+ function unverifiable(reason) {
218
+ const explanation = UNVERIFIED_EXPLANATIONS[reason] ?? reason;
219
+ return {
220
+ acIds: [],
221
+ missing: [],
222
+ unverified: {
223
+ reason,
224
+ notice: '未校验(' + reason + ')——' + explanation + ';AC 覆盖判据跳过(未验证 ≠ 通过)',
225
+ },
226
+ unjudgeable: null,
227
+ };
228
+ }
229
+
230
+ // 不可判的成因与文本在同一处产出(判定结果自带解释与恢复出路):调用方只打印,不再按 reason 去查
231
+ // 第二张表——两张按同一个 key 索引的表只要有人漏改一张,报文就会一半新一半旧。
232
+ function unjudgeable(reason) {
233
+ const cause = UNJUDGEABLE_CAUSES[reason] ?? {
234
+ explanation: reason,
235
+ recovery: '按模板补齐该段后重试 exit verify',
236
+ };
237
+ return {
238
+ acIds: [],
239
+ missing: [],
240
+ unverified: null,
241
+ unjudgeable: { reason, explanation: cause.explanation, recovery: cause.recovery },
242
+ };
243
+ }
244
+
245
+ // 判定:返回 { acIds, missing, unverified, unjudgeable }。
246
+ // · acIds = REQUIREMENT 验收段内的编号(有序去重);
247
+ // · missing = 这些编号里未出现在 1.1 矩阵段文本中的(同样按 REQUIREMENT 顺序);
248
+ // · unverified / unjudgeable = 非 null 表示没判成:前者只剩「模板缺席」(放行),后者是工件
249
+ // 内容不可判——载体文件被删或承载段 / 清单读不出(按 change 新旧分级);两者都为 null 才表示
250
+ // 判据真的判过。
251
+ // 顺序固定:承载段在不在一级(段缺席 = 内容不可判,不是「无可判对象」),再判「有没有编号」,最后判
252
+ // 「矩阵能不能读」——三级「判不了」因此不会互相遮蔽,报文说的是真正卡住的那一环。
253
+ export async function acCoverageReview(changeDir) {
254
+ const requirementText = await readText(path.join(changeDir, 'REQUIREMENT.md'));
255
+ // 载体文件缺席不是「没有可判对象」(作者能删掉它)——与承载段被删同属内容不可判。
256
+ if (requirementText === null) return unjudgeable('REQUIREMENT 缺席');
257
+ const acceptanceMatcher = await acceptanceSectionMatcher();
258
+ if (acceptanceMatcher === TEMPLATE_SECTION_SKIP) return unverifiable('模板缺席(段名无从派生)');
259
+ const acceptanceBody = sectionBody(requirementText, acceptanceMatcher, { level: 2, endOnSeparator: false });
260
+ // 承载段缺席 ≠ 载体缺席:REQUIREMENT.md 与模板都在场,缺的是作者自己删掉的段——按内容不可判
261
+ // 分级(新 change BLOCKED / 旧 change WARN),删段因此不是关掉 AC 覆盖判据的写法。
262
+ if (acceptanceBody === null) return unjudgeable('REQUIREMENT 无验收准则段');
263
+ const acIds = parseAcIds(acceptanceBody);
264
+ if (acIds.length === 0) return unjudgeable('REQUIREMENT 无 AC 编号');
265
+ const testText = await readText(path.join(changeDir, 'TEST.md'));
266
+ if (testText === null) return unjudgeable('TEST.md 缺席');
267
+ const roundMatcher = await testRoundSectionMatcher();
268
+ if (roundMatcher === TEMPLATE_SECTION_SKIP) return unverifiable('模板缺席(段名无从派生)');
269
+ // 同一口径:TEST.md 与模板在场而承载段(第 1 轮)缺席 → 内容不可判(删段不得成为跳过口)。
270
+ if (sectionBody(testText, roundMatcher, { level: 2, endOnSeparator: false }) === null) {
271
+ return unjudgeable('TEST.md 无第 1 轮段');
272
+ }
273
+ const matrixMatcher = await testMatrixSectionMatcher();
274
+ if (matrixMatcher === TEMPLATE_SECTION_SKIP) return unverifiable('模板缺席(段名无从派生)');
275
+ const matrixBody = sectionBody(testText, matrixMatcher, { level: 3, endOnSeparator: false });
276
+ if (matrixBody === null) return unjudgeable('TEST.md 第 1 轮无 1.1 测试矩阵段');
277
+ const covered = new Set(parseAcIds(matrixBody));
278
+ return { acIds, missing: acIds.filter((id) => !covered.has(id)), unverified: null, unjudgeable: null };
279
+ }
280
+
281
+ // verify 出口的报文(BLOCKED / WARN 同一文本,只换分级前缀与末尾的分级说明):首行点名缺失编号,
282
+ // 第二行给可执行的恢复出路(在 1.1 矩阵补行)——两条出路只有一条(覆盖是矩阵行的事,没有第二种写法)。
283
+ export function acCoverageReportLines({ coverage, level = 'BLOCKED' }) {
284
+ const blocking = level === 'BLOCKED';
285
+ return [
286
+ (blocking ? 'BLOCKED: ' : 'WARN: ')
287
+ + 'TEST.md 的 1.1 测试矩阵缺 AC 覆盖: ' + coverage.missing.join('、')
288
+ + '——REQUIREMENT.md 的验收准则共 ' + coverage.acIds.length
289
+ + ' 条,上述编号在 1.1 矩阵里没有对应行(AC 是测试阶段派生用例的唯一来源,每条都要有行)'
290
+ + (blocking ? '' : '(旧 change 渐进不阻断)'),
291
+ '恢复: 在 TEST.md 的 1.1 测试矩阵为这些 AC 补行(每条一行:| ' + (coverage.missing[0] ?? 'AC-N')
292
+ + ' | 类型 | 用例文件 / UAT | 状态 |),补完重试 exit verify',
293
+ ];
294
+ }
295
+
296
+ // 「工件内容不可判」的报文(verify 出口 BLOCKED / 旧 change WARN 同一文本,只换分级前缀与末尾的
297
+ // 分级说明——与波次判据同形):首行点名是哪一环读不出来,第二行给能照做的恢复出路。WARN 前缀让该行
298
+ // 进入既有 WARN COUNT(「该写的没写」不再静默为「未校验」)。
299
+ export function acCoverageUnjudgeableLines({ coverage, level = 'BLOCKED' }) {
300
+ const blocking = level === 'BLOCKED';
301
+ const { explanation, recovery } = coverage.unjudgeable;
302
+ return [
303
+ (blocking ? 'BLOCKED: ' : 'WARN: ')
304
+ + 'AC 覆盖判据无法执行——' + explanation
305
+ + (blocking ? '' : '(旧 change 渐进不阻断)')
306
+ + ':判据没有可对账的清单(未验证 ≠ 通过)',
307
+ '恢复: ' + recovery,
308
+ ];
309
+ }
310
+
311
+ // review 出口的汇总:一条(不逐条刷屏)、不阻断、不改退出码——review 出口今天不要求 TEST.md,
312
+ // 这里只把「测试矩阵漏了谁」提前摆到审查者眼前;权威判定在 verify 出口。
313
+ export function acCoverageSummaryLine({ coverage }) {
314
+ return 'REVIEW WARN: TEST.md 的 1.1 测试矩阵缺 AC 覆盖: ' + coverage.missing.join('、')
315
+ + '——REQUIREMENT.md 的验收准则共 ' + coverage.acIds.length
316
+ + ' 条(verify 出口会据此 BLOCK;本出口只汇总提示,不影响退出码)';
317
+ }
@@ -101,21 +101,48 @@ function headingLines(text, level) {
101
101
  return out;
102
102
  }
103
103
 
104
- // 段名宽容匹配(单一实现):主体取 normalizeHeading 的结果,译为行锚定正则。编号前缀与尾部括号在
105
- // 正则里同样是可选的——「省编号 / 换括号措辞 / 大小写不同」命中同一段,核心词不同则不命中(AC-9)。
104
+ // 段名宽容匹配(单一实现):主体取 normalizeHeading 的结果,译为行锚定正则。编号前缀、尾部括号与
105
+ // 闭合 ATX 在正则里同样可选——「省编号 / 换括号措辞 / 大小写不同 / 尾部补 `##`」命中同一段,核心词
106
+ // 不同则不命中(AC-9)。闭合 ATX 的判定与 normalizeHeading 取同一惯例:收尾的 `#` 串前面必须有空白,
107
+ // 否则那是标题文本本身(`## 波次划分##` 的段名以 `#` 结尾,不是同一条标题)。
106
108
  // escapeRegExp 的既有契约是 glob 片段(调用方先 split('*')),故不转义 `*`;段名是字面文本,缺口在
107
109
  // 这一行显式闭合,而不是另写一份转义实现。
110
+ // 匹配只对**围栏外的标题行**有意义(围栏内的标题是正文示例):段名判据一律经 lib/section-body.mjs 的
111
+ // 围栏感知扫描取行,本正则不承担围栏语义(对着整篇文本 test 会把示例标题读成段)。
108
112
  export function headingPattern(rawName, level = 2) {
109
113
  const normalized = normalizeHeading(rawName);
110
114
  const body = normalized === '' ? String(rawName ?? '').trim() : normalized;
111
- const literal = escapeRegExp(body).replace(/\*/gu, '\\*');
112
115
  const marker = level === 3 ? '###' : '##';
113
116
  return new RegExp(
114
- '^' + marker + '\\s*(?:\\d+(?:\\.\\d+)?\\.?\\s*)?' + literal + '\\s*(?:[((][^\\n))]*[))])?\\s*$',
117
+ '^' + marker + '\\s*(?:\\d+(?:\\.\\d+)?\\.?\\s*)?' + headingLiteral(body)
118
+ + '\\s*(?:[((][^\\n))]*[))])?(?:\\s+#+)?\\s*$',
115
119
  'im',
116
120
  );
117
121
  }
118
122
 
123
+ // 段名字面量 → 正则片段:转义正则元字符(`*` 不在 escapeRegExp 的 glob 契约内,单独闭合)。段名
124
+ // 在正则里是字面文本,缺口在这一行显式闭合,而不是各消费方各写一份转义。
125
+ function headingLiteral(rawName) {
126
+ return escapeRegExp(String(rawName ?? '')).replace(/\*/gu, '\\*');
127
+ }
128
+
129
+ // 段标题谓词(同一套归一的谓词形态;lib/section-body.mjs 既接受整行正则,也接受
130
+ // `(heading) => boolean`):判定 = 级别相等 且 标题正文与段名过同一个 normalizeHeading 后相等。
131
+ // 为什么需要谓词形态:标题**正文本身**可以以井号开头(`## ## 验收准则(AC)`)——Markdown 的合法
132
+ // 写法,段形门先剥前导井号再归一(认作在场),而按整行锚定的正则把第二个井号读成段名的一部分:同一份
133
+ // 工件的同一段在两处得到相反答案,一次排版就够关掉其中一处判据(未校验 ≠ 通过)。归一在标题文本层,
134
+ // 井号因此不是判定变量。段形门(guard-template-fidelity)对同一件事用的是同一套归一(标题正文与段名
135
+ // 各过 normalizeHeading 再比);波次门与 AC 覆盖取用本谓词,两处不再各写一份比较。
136
+ // names 可给单个段名或段名清单(回退基准常是一组同义写法,见文件末尾的段名清单段)。
137
+ export function headingPredicate(names, level = 2) {
138
+ const wanted = new Set((Array.isArray(names) ? names : [names])
139
+ .map((name) => normalizeHeading(name))
140
+ .filter((name) => name !== ''));
141
+ return function registeredSectionHeading(heading) {
142
+ return Boolean(heading) && heading.level === level && wanted.has(normalizeHeading(heading.text));
143
+ };
144
+ }
145
+
119
146
  // 登记表读取(进程内一次)
120
147
  let registryCache = null;
121
148
 
@@ -385,12 +412,21 @@ export async function allSkeletons(opts = {}) {
385
412
  // SUMMARY 模板缺席时的段序兜底:登记表不可读 / 模板未安装时,SUMMARY 门禁仍判乱序与缺段。
386
413
  export const LEGACY_SUMMARY_ORDER = ['做了什么', '改动文件', 'verify 输出', '6 维自查', '越界检查', '自检方法'];
387
414
 
415
+ // 验收准则段的回退**段名**(一组同义写法):同一份字面清单派生两种投影——open 出口对着整篇工件文本
416
+ // test 下面的行正则,AC 覆盖按标题行过共享谓词比较(标题正文以井号开头时行正则判缺席,谓词认在场)。
417
+ // 行正则由名字拼出:回退基准因此只有一份清单,改一处不会让另一处静默落后。
418
+ export const TEMPLATE_FALLBACK_SECTION_NAMES = {
419
+ requirementAcceptance: ['验收准则', '验收标准', 'AC', 'Acceptance Criteria'],
420
+ };
421
+
388
422
  // 模板缺席时 open / design 出口的段名回退(键形态保持不变,消费方按既有键取用)。
389
423
  export const TEMPLATE_FALLBACK_SECTION_PATTERNS = {
390
424
  changeWhy: /^##\s*Why\b/im,
391
425
  changeVisualTone: /^##\s*视觉调性/im,
392
426
  requirementUserStory: /^##\s*用户故事/im,
393
- requirementAcceptance: /##\s*(验收准则|验收标准|AC|Acceptance Criteria)/i,
427
+ requirementAcceptance: new RegExp(
428
+ '##\\s*(' + TEMPLATE_FALLBACK_SECTION_NAMES.requirementAcceptance.map(headingLiteral).join('|') + ')',
429
+ 'i'),
394
430
  designDecisionList: /^##\s*\d*\.?\s*决策清单/m,
395
431
  };
396
432
 
@@ -404,3 +440,9 @@ export const SUMMARY_REQUIRED_SECTIONS = [
404
440
  { regex: /##\s*6\s*维自查/i, label: '## 6 维自查' },
405
441
  { regex: /##\s*(越界检查|边界检查)/i, label: '## 越界检查' },
406
442
  ];
443
+
444
+ // 波次段名(TASK 模板的 H2):与上面几份清单同一性质——模板缺席时判据仍要有一份基准名,消费方
445
+ // (lib/wave-projection.mjs)只 import,不自持字面名。宽容匹配由 headingPattern 派生,标题的编号
446
+ // 前缀 / 尾部括号 / 闭合 ATX 因此与 TASK 段形门、AC 覆盖走同一套归一:同一份工件的同一段在两处被
447
+ // 认出同一组写法。「名字与模板一致」由套件在模板在场时对账(不一致即红)——登记值不是自由变量。
448
+ export const WAVE_SECTION_NAME = '波次划分';