flow-comet 1.6.4 → 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 (64) 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/evolve.mjs +174 -0
  8. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +3 -1
  9. package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
  10. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +41 -18
  11. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +16 -16
  12. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
  13. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +9 -7
  14. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +2 -2
  15. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +17 -13
  16. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  17. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  18. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +206 -3
  19. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +458 -60
  20. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +38 -58
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +642 -230
  22. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +85 -14
  23. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +43 -5
  24. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +15 -1
  25. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +18 -1
  26. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +60 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +73 -9
  28. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +21 -1
  29. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +9 -0
  30. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +212 -0
  31. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +15 -5
  32. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +4 -4
  33. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +20 -10
  34. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +4 -1
  35. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +6 -6
  36. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +13 -5
  37. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  38. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
  39. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +74 -2
  40. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  41. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  42. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  43. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  44. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  45. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  46. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  47. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  48. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  49. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  50. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  51. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  52. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  53. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  54. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  55. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  56. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  57. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  58. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  59. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  60. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  61. package/README.md +3 -3
  62. package/package.json +1 -1
  63. package/scripts/dsh-bridge.mjs +2 -2
  64. package/scripts/lib/installer-flowkit.mjs +43 -3
@@ -25,6 +25,11 @@ import { taskOpeningAttrs, taskBlocks as extractTaskBlocks } from '../task-parsi
25
25
  import { runRoot, fileExists, writeJson } from './guard-state-io.mjs';
26
26
  import {
27
27
  TEMPLATE_FALLBACK_SECTION_PATTERNS,
28
+ buildSkeleton,
29
+ headingPattern,
30
+ } from './guard-artifact-skeleton.mjs';
31
+ import { frontendCriterion } from './guard-uidesign.mjs';
32
+ import {
28
33
  evidenceFor,
29
34
  findSkillLoadsDir,
30
35
  hasEvidenceField,
@@ -57,20 +62,55 @@ function markerProtocolBasename(value) {
57
62
  return String(value).replaceAll('\\', '/').split('/').pop() || null;
58
63
  }
59
64
 
60
- // REVIEW.md 发现区条目解析——"## 发现" 段下的发现项 = 列表项("- **" 无序 / "1. **" 有序,
61
- // 两种列表形态同口径解析);"无" 条目("- 无" / "无(...)")表示该级别无发现,豁免。条目块包含
62
- // 其后的非空续行(同一段落),直到空行 / 下一条目 / 下一个标题。严重度只取该条目自身的标题/行首
63
- // ——所属 "### Major" 分区,或标题(加粗部分)内带 [Major] 标签(真实 REVIEW 常用扁平有序列表 +
64
- // 条目内级别标签的写法);条目正文引用他条的 [Major] 字样不改变本条严重度。
65
- // 返回 { title, lines, isMajor, ordinal }。
65
+ // REVIEW.md 发现区解析——发现的合法位置是模板位置 `### 2.2 …详细发现`(REVIEW 模板的结构子段);
66
+ // 旧形态 `## 发现` 段(历史 REVIEW 的写法)继续按同一套条目口径解析,供旧 change 渐进处置与迁移
67
+ // 提示。发现项有两种合法书写形态:① 列表项("- **" 无序 / "1. **" 有序,两种列表形态同口径解析);
68
+ // ② 模板范例形态(flow-kit/templates/REVIEW.md 2.2 的书写样例 `### 🔴 R<x> · <名字>:<结论>` +
69
+ // 粗体字段行)——模板位置下以严重度 token 起头的 H3 同样是发现,标题行即条目自身的第一行(处置
70
+ // 标记按该行判定)。不以严重度 token 起头的 H3(如 `### Major`)仍是严重度分区。旧 `## 发现` 段
71
+ // 保持列表项口径(历史写法,避免把分区标题误判成发现)。"无"条目("- 无" / "无(...)")表示该
72
+ // 级别无发现,豁免。条目块包含其后的非空续行,直到空行 / 下一条目 / 下一个标题。严重度只取该条目
73
+ // 自身的标题/行首——所属 "### Major" 分区,或标题(加粗部分 / H3 严重度 token)内带级别信息;
74
+ // 条目正文引用他条的 [Major] 字样不改变本条严重度。返回 { title, scope, lines, isMajor, ordinal }。
66
75
  const REVIEW_FINDING_ITEM_RE = /^\s*(?:[-*+]|\d+[.)])\s*\*\*(.+?)\*\*/;
76
+ const REVIEW_SEVERITY_TOKEN_RE = /^(?:🔴|🟡|🟢|\[\s*(?:critical|major|minor)\s*\])\s*/iu;
67
77
  const REVIEW_DISPOSITION_RE = /\[已修\]|\[升级\]|\[转待办\]/;
68
78
  const REVIEW_MAJOR_LABEL_RE = /\[\s*Major\s*\]/i;
69
79
  const REVIEW_ADJUDICATION_RE = /用户裁决\s*[::]\s*接受延期/;
80
+ // 旧形态段的「空段」形态:占位词与「无」条目不构成内容(迁移提示只在旧段真有内容时给)。
81
+ const REVIEW_FINDINGS_PLACEHOLDER_RE =
82
+ /^(?:[-*+]\s*)?(?:\*\*)?(?:无|不适用|未涉及|无变更|N\/A|—|(无)|\(无\))(?:\*\*)?[。.;;,,]?$/iu;
83
+
84
+ // 发现区作用域基准从 REVIEW 骨架派生(模板 `### 2.2 6 维诊断 · 详细发现(4 要素…)` → 结构子段
85
+ // 「详细发现」)——段名归一是骨架模块的单一实现,此处不另写段名正则。模板缺席 → primary=null,
86
+ // 模板位置判据整体跳过(模板派生判据不臆造;旧形态解析与处置校验照常)。同一父段的其它
87
+ // 结构子段(2.0 / 2.1 / 2.3)在模板位置作用域内结束该子段;段内其它 H3(如 brooks 输出的
88
+ // `### 🔴 R1 …` 分区)是严重度分区,不结束作用域。
89
+ async function reviewFindingScope() {
90
+ const skeleton = await buildSkeleton('REVIEW');
91
+ const subsections = skeleton.derived ? skeleton.structureSubsections : [];
92
+ const primary = subsections.find((entry) => entry.norm.includes('详细发现')) ?? null;
93
+ return {
94
+ primary: primary === null ? null : primary.pattern,
95
+ siblings: primary === null
96
+ ? []
97
+ : subsections
98
+ .filter((entry) => entry !== primary && entry.parentNorm === primary.parentNorm)
99
+ .map((entry) => entry.pattern),
100
+ };
101
+ }
102
+
103
+ // H3 条目形态的严重度从标题前缀的严重度 token 派生(模板范例的 🔴/🟡/🟢;另接受文字标签形态的
104
+ // [Critical]/[Major]/[Minor])——Major 延期裁决门禁对 H3 条目与列表项同口径。
105
+ function reviewSubheadingIsMajor(heading) {
106
+ const token = (String(heading).match(REVIEW_SEVERITY_TOKEN_RE) ?? [])[0] ?? '';
107
+ if (/🔴|🟡/u.test(token) || /critical|major/iu.test(token)) return true;
108
+ return REVIEW_MAJOR_LABEL_RE.test(heading);
109
+ }
70
110
 
71
- function reviewFindingsItems(text) {
111
+ function reviewFindingsItems(text, scope = { primary: null, siblings: [] }) {
72
112
  const items = [];
73
- let inFindings = false;
113
+ let mode = 'none'; // 'none' | 'legacy'(旧 ## 发现)| 'primary'(模板位置 2.2)
74
114
  let severity = '';
75
115
  let current = null;
76
116
  const pushCurrent = () => { if (current) { items.push(current); current = null; } };
@@ -78,23 +118,51 @@ function reviewFindingsItems(text) {
78
118
  const h2 = line.match(/^##\s+(.+?)\s*$/);
79
119
  if (h2) {
80
120
  pushCurrent();
81
- inFindings = /^发现/.test(h2[1]);
82
121
  severity = '';
122
+ mode = /^发现/.test(h2[1].trim()) ? 'legacy' : 'none';
83
123
  continue;
84
124
  }
85
- if (!inFindings) continue;
86
125
  const h3 = line.match(/^###\s+(.+?)\s*$/);
87
126
  if (h3) {
88
127
  pushCurrent();
128
+ if (mode === 'primary') {
129
+ // 兄弟结构子段结束模板位置作用域;其余三级标题只是严重度分区
130
+ if ((scope.siblings ?? []).some((pattern) => pattern.test(line))) {
131
+ mode = 'none';
132
+ severity = '';
133
+ continue;
134
+ }
135
+ // 模板范例形态:严重度 token 起头的 H3 = 发现条目(标题行即条目自身第一行,处置标记
136
+ // 与列表项同口径按该行判定),续行是粗体字段 / 正文,直到空行或下一个标题。
137
+ const heading = h3[1].trim();
138
+ if (REVIEW_SEVERITY_TOKEN_RE.test(heading)) {
139
+ current = {
140
+ title: heading.replace(REVIEW_SEVERITY_TOKEN_RE, '').trim() || heading,
141
+ scope: 'primary',
142
+ lines: [line],
143
+ isMajor: reviewSubheadingIsMajor(heading),
144
+ };
145
+ continue;
146
+ }
147
+ severity = heading;
148
+ continue;
149
+ }
150
+ if (mode === 'none' && scope.primary !== null && scope.primary.test(line)) {
151
+ mode = 'primary';
152
+ severity = '';
153
+ continue;
154
+ }
89
155
  severity = h3[1].trim();
90
156
  continue;
91
157
  }
158
+ if (mode === 'none') continue;
92
159
  const m = line.match(REVIEW_FINDING_ITEM_RE);
93
160
  if (m) {
94
161
  pushCurrent();
95
162
  const title = m[1].trim();
96
163
  current = {
97
164
  title,
165
+ scope: mode,
98
166
  lines: [line],
99
167
  isMajor: /^major\b/i.test(severity) || REVIEW_MAJOR_LABEL_RE.test(title),
100
168
  };
@@ -110,11 +178,30 @@ function reviewFindingsItems(text) {
110
178
  return items;
111
179
  }
112
180
 
181
+ // 旧形态 `## 发现` 段是否有实质内容(占位词 / 子标题 / 空行不计):写在旧段而模板位置无条目时
182
+ // 触发迁移提示——只在旧段真有内容时给,避免空段或只写「无」的旧 REVIEW 被误报。
183
+ function reviewLegacyFindingsHasContent(text) {
184
+ let inLegacy = false;
185
+ for (const line of String(text).split(/\r?\n/)) {
186
+ const h2 = line.match(/^##\s+(.+?)\s*$/);
187
+ if (h2) {
188
+ inLegacy = /^发现/.test(h2[1].trim());
189
+ continue;
190
+ }
191
+ if (!inLegacy) continue;
192
+ if (/^#{3,6}\s+/.test(line)) continue;
193
+ const trimmed = line.trim();
194
+ if (trimmed === '' || REVIEW_FINDINGS_PLACEHOLDER_RE.test(trimmed)) continue;
195
+ return true;
196
+ }
197
+ return false;
198
+ }
199
+
113
200
  // 发现区条目处置标记存在性:返回缺处置状态标记([已修]/[升级]/[转待办])的条目标题列表——结构级
114
201
  // 校验(不做语义判断:标记存在即视为已处置)。发现项(含 Minor;无序与有序条目同口径,均不得
115
202
  // "记录后无声消失")的处置标记以该条目自身标题/行首为准——正文引用他条标记不参与判定。
116
- function reviewFindingsMissingDisposition(text) {
117
- return reviewFindingsItems(text)
203
+ function reviewFindingsMissingDisposition(text, scope = { primary: null, siblings: [] }) {
204
+ return reviewFindingsItems(text, scope)
118
205
  .filter((item) => !/^无/.test(item.title)) // "无" 条目豁免
119
206
  // 四要素字段行豁免:REVIEW 发现条目的 Symptom/Source/Consequence/Remedy 是 brooks 审查输出
120
207
  // 格式的字段行(带 ** 加粗),不是发现条目本身——不豁免会误判为"发现项缺处置标记"(执行者按
@@ -142,9 +229,9 @@ function reviewAdjudicationPointsTo(record, item) {
142
229
  // 处置)。Minor 不参与;Major [升级]/[已修] 直接放行。条目自身的处置标记([转待办])只认该条目标题
143
230
  // /行首(无序与有序同口径),正文续行引用他条标记不触发本门禁;[升级] 承接可出现在条目自身块或
144
231
  // 用户裁决记录中(承接非本条处置)。
145
- function reviewDeferredMajorProblems(text) {
232
+ function reviewDeferredMajorProblems(text, scope = { primary: null, siblings: [] }) {
146
233
  const textValue = String(text);
147
- const items = reviewFindingsItems(textValue);
234
+ const items = reviewFindingsItems(textValue, scope);
148
235
  const paragraphs = textValue.split(/\n\s*\n/).map((p) => p.trim()).filter(Boolean);
149
236
  const problems = [];
150
237
  for (const item of items) {
@@ -392,63 +479,355 @@ export async function runArchiveBranchMergeGate({ node, state }) {
392
479
  // 特化校验按节点 id 绑定(ADR-002 分层):内置节点 id 触发 flow-kit 契约校验;自定义协议节点不
393
480
  // 误触发(通用层防线对其生效)。
394
481
  // 追加位置结构检测(全部 WARN 不 BLOCK)——防 CONTEXT/LESSONS/STATE/CHANGELOG 文件尾追加破坏
395
- // 插入位置纪律。
482
+ // 插入位置纪律;open 出口另做 CONTEXT 模板段校验(项目级工件不受 C3 节点映射约束,也不要求
483
+ // skill-load 声明模板——C17)。
484
+ // 条件子段(C21):`自定义 hooks(前端)` 只在前端 change 要求;其余子段无条件要求(未发现的写
485
+ // 「未发现」)。前端判定沿用 CHANGE.md「视觉调性」段的既有判据(单一实现)。
486
+ const CONTEXT_FRONTEND_ONLY_SUBSECTION = '自定义 hooks';
487
+
488
+ // CONTEXT 模板段问题清单:段集合取自骨架(模板 = 内容权威),段标题按段名归一匹配(忽略编号 /
489
+ // 括号后缀 / 大小写,AC-9);父段缺席时不再列其子段(父段已单独报出,避免同一事实重复计数)。
490
+ // 模板缺席(derived=false)→ 返回 null:模板派生判据整体跳过,由调用方输出显式「未校验(模板缺失)」
491
+ // ——不退回任何内置段名副本。
492
+ async function contextTemplateProblems(state, content) {
493
+ const skeleton = await buildSkeleton('CONTEXT');
494
+ if (!skeleton.derived) return null;
495
+ const problems = [];
496
+ for (const section of skeleton.sections) {
497
+ if (!section.pattern.test(content)) problems.push('缺段「## ' + section.name + '」');
498
+ }
499
+ const frontend = await frontendCriterion(state.activeChange);
500
+ for (const sub of skeleton.structureSubsections) {
501
+ if (!frontend.applicable && sub.name.includes(CONTEXT_FRONTEND_ONLY_SUBSECTION)) continue;
502
+ const parent = skeleton.sections.find((section) => section.name === sub.parent);
503
+ if (parent && !parent.pattern.test(content)) continue;
504
+ if (!sub.pattern.test(content)) problems.push('缺子段「### ' + sub.name + '」');
505
+ }
506
+ return problems;
507
+ }
508
+
396
509
  export async function runContextAppendGate({ node, state }) {
397
510
  if (node.id !== 'open' || !state.activeChange) return;
398
511
  const contextFile = path.join(runRoot, '.specs', 'CONTEXT.md');
399
- try {
400
- const content = await fs.readFile(contextFile, 'utf8');
401
- const m = content.match(/^## (术语|已锁决策|决策|术语表)[((][^\n]*(?:追加|update)[^\n]*$/im);
402
- if (m) {
512
+ if (!(await fileExists(contextFile))) return; // 项目级工件可缺席:文件存在才查
513
+ let content = null;
514
+ try { content = await fs.readFile(contextFile, 'utf8'); } catch { content = null; }
515
+ if (content === null) return;
516
+ const m = content.match(/^## (术语|已锁决策|决策|术语表)[((][^\n]*(?:追加|update)[^\n]*$/im);
517
+ if (m) {
518
+ if (isNewChange(state)) {
519
+ console.error('BLOCKED: CONTEXT.md 检测到孤立追加段(新 change 强制插入既有结构段);恢复: 把内容移入术语表/已锁决策段');
520
+ process.exit(1);
521
+ }
522
+ console.error('WARN: CONTEXT.md 检测到孤立追加段(术语/决策应插入既有结构段):' + m[0].replace(/^##\s*/, '').trim());
523
+ }
524
+ const problems = await contextTemplateProblems(state, content);
525
+ if (problems === null) {
526
+ // 模板缺席:段形校验跳过但显式声明(未验证 ≠ 通过),修复指引给出取模板的途径
527
+ console.error('CONTEXT 未校验(模板缺失)——flow-kit/templates/CONTEXT.md 不在项目根,段形校验跳过'
528
+ + '(修复: 按安装指引获取 flow-kit 模板后重试)');
529
+ return;
530
+ }
531
+ if (problems.length === 0) return;
532
+ if (isNewChange(state)) {
533
+ console.error('BLOCKED: CONTEXT.md 有 ' + problems.length + ' 处与模板段形不符(新 change 强制项目上下文按模板段形书写):');
534
+ for (const problem of problems) console.error(' - ' + problem);
535
+ console.error('恢复: 按 flow-kit/templates/CONTEXT.md 补齐段标题(未发现的写「未发现」;前端子段按条件段裁剪)后重试 exit open');
536
+ process.exit(1);
537
+ }
538
+ console.error('WARN: CONTEXT.md 有 ' + problems.length + ' 处与模板段形不符(旧 change 渐进不阻断): '
539
+ + problems.join('、'));
540
+ }
541
+
542
+ // LESSONS.md 结构检测(每条判据的作用面逐个交代):
543
+ // ① 旧形态 `## L-NNN`(条目写成二级标题)——open / verify / archive 三处出口都拦(AC-17),新
544
+ // change BLOCKED 并逐行给「文件:行号 → 改法」,旧 change WARN 渐进;
545
+ // ② 条目区外条目(条目区锚点用段名归一,容忍模板标题的括号后缀,如 `## 条目区(夹具)`)与
546
+ // ③ 同段内编号递增——两条保持既有作用面(verify / archive),不随 ① 扩到 open;
547
+ // ④ `### L-NNN` 条目的字段键(C20)——键集合从 LESSONS 模板「条目格式」段的书写样例派生;新 change
548
+ // 的新条目缺任一键 BLOCKED,旧条目(迁移形态 / 首发指向别的 change)与旧 change 只 WARN;
549
+ // ⑤ archive 出口核对 evidence.lessonsNomination:扫描份数 = 该 change 内 SUMMARY 份数、提名编号在
550
+ // LESSONS 中真实存在、无提名时理由非空——归档提名留痕且可核对。
551
+ const LESSONS_LEGACY_ENTRY_RE = /^##\s+(L-\d+)\b/u;
552
+ const LESSONS_ENTRY_ZONE_NAMES = ['条目区', '活跃条目', '已解决条目'];
553
+ // `### L-NNN` 条目块(后接非数字/非字母,避免吞掉更长编号)。模板条目形态 = `### L-NNN · [tag] 标题`
554
+ // (「条目格式」段给出的书写样例);迁移形态(`### L-NNN:` 冒号标题)与裸标题(`### L-NNN`)等
555
+ // 历史写法一律按旧条目处置(不足字段只 WARN)——新条目的判定因此只看「模板标题形态 + 字段键」。
556
+ const LESSONS_ENTRY_HEADING_RE = /^###\s*(L-\d+)(?![\dA-Za-z])/u;
557
+ const LESSONS_TEMPLATE_HEADING_RE = /^###\s*L-\d+\s*·/u;
558
+ // 字段键行:`- **<键>**: <值>`(条目正文里的粗体小标题不带列表符,不会命中)。
559
+ const LESSONS_FIELD_LINE_RE = /^[-*]\s*\*\*(.+?)\*\*\s*[::]\s*(.*)$/u;
560
+
561
+ // 旧形态条目行(行号 1 基):迁移指引逐行可执行,执行者不必自己数行号。
562
+ function lessonsLegacyEntries(content) {
563
+ const hits = [];
564
+ String(content).split(/\r?\n/).forEach((line, index) => {
565
+ const matched = line.match(LESSONS_LEGACY_ENTRY_RE);
566
+ if (matched) hits.push({ line: index + 1, id: matched[1] });
567
+ });
568
+ return hits;
569
+ }
570
+
571
+ // 该 change 的 SUMMARY 份数(C6:先看活动目录,目录已移入归档时看 `.specs/archive/*-<change>/`;
572
+ // 两处都不存在 → null = 归档产物缺失——不可核对的份数不当作 0)。
573
+ async function changeSummaryCount(changeName) {
574
+ const activeDir = path.join(runRoot, '.specs', changeName);
575
+ let dir = null;
576
+ if (await fileExists(activeDir)) {
577
+ dir = activeDir;
578
+ } else {
579
+ const archiveRoot = path.join(runRoot, '.specs', 'archive');
580
+ const entries = await fs.readdir(archiveRoot).catch(() => []);
581
+ const archived = entries.find((entry) => entry.endsWith('-' + changeName));
582
+ if (archived) dir = path.join(archiveRoot, archived);
583
+ }
584
+ if (dir === null) return null;
585
+ const files = await fs.readdir(dir).catch(() => []);
586
+ return files.filter((name) => name.endsWith('-SUMMARY.md')).length;
587
+ }
588
+
589
+ // LESSONS 里已登记的条目编号(旧形态与迁移后的新形态都算「编号存在」——形态由 ① 单独校验,
590
+ // 存在性只判编号是否真实登记)。
591
+ async function lessonsEntryNumbers() {
592
+ const lessonsFile = path.join(runRoot, '.specs', 'LESSONS.md');
593
+ let content;
594
+ try { content = await fs.readFile(lessonsFile, 'utf8'); } catch { return new Set(); }
595
+ const numbers = new Set();
596
+ for (const matched of String(content).matchAll(/^#{2,3}\s*L-(\d+)/gm)) numbers.add(parseInt(matched[1], 10));
597
+ return numbers;
598
+ }
599
+
600
+ // 归档提名核对(结构级):evidence.lessonsNomination = { scanned, nominated[], reasonIfNone }。
601
+ async function lessonsNominationProblems(state) {
602
+ const nomination = evidenceFor(state, 'archive')?.lessonsNomination;
603
+ if (!nomination || typeof nomination !== 'object' || Array.isArray(nomination)) {
604
+ return ['缺 evidence.lessonsNomination(应记录 { scanned, nominated[], reasonIfNone })'];
605
+ }
606
+ const problems = [];
607
+ const actual = await changeSummaryCount(state.activeChange);
608
+ if (actual === null) {
609
+ problems.push('该 change 的工件目录缺失(.specs/<change>/ 与 .specs/archive/*-<change>/ 都不存在),无从核对扫描份数');
610
+ } else if (nomination.scanned !== actual) {
611
+ problems.push('扫描份数 ' + JSON.stringify(nomination.scanned ?? null)
612
+ + ' ≠ 该 change 内 *-SUMMARY.md 份数 ' + actual);
613
+ }
614
+ if (!Array.isArray(nomination.nominated)) {
615
+ problems.push('lessonsNomination.nominated 须为数组(无提名写 [])');
616
+ } else if (nomination.nominated.length === 0) {
617
+ if (!(typeof nomination.reasonIfNone === 'string' && nomination.reasonIfNone.trim() !== '')) {
618
+ problems.push('无提名时 lessonsNomination.reasonIfNone 不能为空(写明本轮为何没有条目入库)');
619
+ }
620
+ } else {
621
+ const known = await lessonsEntryNumbers();
622
+ for (const id of nomination.nominated) {
623
+ const matched = typeof id === 'string' ? id.match(/^L-(\d+)$/iu) : null;
624
+ if (matched === null) {
625
+ problems.push('提名编号格式非法: ' + JSON.stringify(id) + '(应为 L-NNN)');
626
+ } else if (!known.has(parseInt(matched[1], 10))) {
627
+ problems.push('提名编号在 LESSONS.md 中不存在: ' + id);
628
+ }
629
+ }
630
+ }
631
+ return problems;
632
+ }
633
+
634
+ // ① 旧形态条目(`## L-NNN`):open / verify / archive 三处出口都拦(AC-17)——报文逐行给「文件:
635
+ // 行号 → 改法」,迁移口径 = 改级 + 移入条目区 + 按编号排序。新 change BLOCKED / 旧 change WARN。
636
+ function checkLessonsEntryForm({ content, node, state }) {
637
+ const legacyEntries = lessonsLegacyEntries(content);
638
+ if (legacyEntries.length === 0) return;
639
+ if (isNewChange(state)) {
640
+ console.error('BLOCKED: LESSONS.md 有 ' + legacyEntries.length + ' 条旧形态条目(## L-NNN)——新 change 强制条目写成三级标题并置于条目区:');
641
+ for (const entry of legacyEntries) {
642
+ console.error(' - .specs/LESSONS.md:' + entry.line + ' → 改成 "### ' + entry.id + '"(并移入 ## 条目区,按编号升序)');
643
+ }
644
+ console.error('恢复: 逐行按上述改法迁移(改级 + 移入条目区 + 按编号排序)后重试 exit ' + node.id);
645
+ process.exit(1);
646
+ }
647
+ console.error('WARN: LESSONS.md 有 ' + legacyEntries.length + ' 条旧形态条目(应为 ### L-NNN 并置于条目区;旧 change 渐进不阻断): '
648
+ + legacyEntries.map((entry) => '.specs/LESSONS.md:' + entry.line + ' → ### ' + entry.id).join('、'));
649
+ }
650
+
651
+ // ② 条目区外条目 + ③ 同段内编号递增:既有结构判据保持原作用面(verify / archive)——open 出口只
652
+ // 新增 ① 的旧形态迁移判据,不顺手把这两条扩张到 open(判据作用面按 AC 逐个交代)。
653
+ function checkLessonsZoneAndOrder({ content, state }) {
654
+ // 条目区锚点(段名归一:条目区 / 活跃条目 / 已解决条目,容忍括号后缀)——取最早条目段
655
+ const zoneIndex = (() => {
656
+ const hits = LESSONS_ENTRY_ZONE_NAMES
657
+ .map((name) => content.search(headingPattern(name, 2)))
658
+ .filter((index) => index !== -1);
659
+ return hits.length ? Math.min(...hits) : -1;
660
+ })();
661
+ const headings = [...content.matchAll(/^###\s*L-(\d+)/gm)];
662
+ if (zoneIndex !== -1) {
663
+ const outside = headings.some(h => h.index < zoneIndex);
664
+ if (outside) {
403
665
  if (isNewChange(state)) {
404
- console.error('BLOCKED: CONTEXT.md 检测到孤立追加段(新 change 强制插入既有结构段);恢复: 把内容移入术语表/已锁决策段');
666
+ console.error('BLOCKED: LESSONS.md 有条目在条目区外(新 change 强制条目插入条目区);恢复: 移入条目区');
405
667
  process.exit(1);
406
668
  }
407
- console.error('WARN: CONTEXT.md 检测到孤立追加段(术语/决策应插入既有结构段):' + m[0].replace(/^##\s*/, '').trim());
669
+ // 诊断信息附带 zoneIndex/条目位置——偶发 WARN 排查时可直接定位(文件时序/编码差异兜底)
670
+ console.error('WARN: LESSONS.md 有条目在条目区外(zoneIndex=' + zoneIndex + ', 条目数=' + headings.length + ', 区外条目: ' + headings.filter(h => h.index < zoneIndex).map(h => 'L-' + h[1]).join(',') + ')');
408
671
  }
409
- } catch {}
672
+ }
673
+ const nums = headings.map(h => parseInt(h[1], 10));
674
+ // 分段检测:按 ## 标题分段,仅同段内比较编号递增(多段 LESSONS 如「活跃条目/已解决条目」编号体系可独立)
675
+ const sectionStarts = [...content.matchAll(/^##\s+.*$/gm)].map(m => m.index);
676
+ for (let i = 1; i < nums.length; i++) {
677
+ const sameSection = !sectionStarts.some(s => s > headings[i - 1].index && s < headings[i].index);
678
+ if (sameSection && nums[i] <= nums[i - 1]) {
679
+ if (isNewChange(state)) {
680
+ console.error('BLOCKED: LESSONS.md 条目编号乱序(新 change 强制按编号插入条目区);恢复: 按 L-NNN 顺序插入');
681
+ process.exit(1);
682
+ }
683
+ console.error('WARN: LESSONS.md 条目编号乱序(L-' + String(nums[i]).padStart(3, '0') + ' 应按序插入条目区)');
684
+ break;
685
+ }
686
+ }
687
+ }
688
+
689
+ // ④ 条目字段键(C20):键集合从 LESSONS 模板「条目格式」段的书写样例派生(不写字面第二份清单)。
690
+ // 模板缺席 / 无「条目格式」段 / 样例无字段行 → null——调用方显式声明「未校验(模板缺失)」,不臆造。
691
+ async function lessonsEntryFieldKeys() {
692
+ const skeleton = await buildSkeleton('LESSONS');
693
+ if (!skeleton.derived) return null;
694
+ const formatSection = skeleton.sections.find((section) => section.norm.includes('条目格式'));
695
+ if (!formatSection) return null;
696
+ // 模板按 runRoot 解析:登记表的 file 是项目根相对路径,而 guard 可能在与项目根不同的 cwd
697
+ // 被调起(运行上下文由 FLOW_COMET_RUN_ROOT 给定)。按 cwd 读会在模板在场时也判「模板缺失」,
698
+ // 字段键无从派生 → C20 静默退化为「未校验」。
699
+ let text;
700
+ try { text = await fs.readFile(path.join(runRoot, skeleton.file), 'utf8'); } catch { return null; }
701
+ const keys = [];
702
+ let inSection = false;
703
+ let inFence = false;
704
+ for (const line of String(text).replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n').split('\n')) {
705
+ if (!inSection) {
706
+ if (formatSection.pattern.test(line)) inSection = true;
707
+ continue;
708
+ }
709
+ if (/^##\s+/u.test(line)) break;
710
+ if (/^\s*```/u.test(line)) { inFence = !inFence; continue; }
711
+ if (!inFence) continue;
712
+ const matched = line.match(LESSONS_FIELD_LINE_RE);
713
+ if (matched) keys.push(matched[1].trim());
714
+ }
715
+ return keys.length > 0 ? keys : null;
716
+ }
717
+
718
+ // `### L-NNN` 条目块:标题行 + 其后各行,直到下一个 H2/H3 标题;围栏内的书写样例不算条目
719
+ // (模板的条目格式样例就是 fenced 形态)——与 LESSONS 关键词扫描的围栏口径一致。
720
+ function lessonsEntryBlocks(content) {
721
+ const blocks = [];
722
+ let current = null;
723
+ let inFence = false;
724
+ String(content).replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n').split('\n').forEach((line, index) => {
725
+ if (/^\s*```/u.test(line)) {
726
+ inFence = !inFence;
727
+ if (current) current.lines.push(line);
728
+ return;
729
+ }
730
+ if (inFence) {
731
+ if (current) current.lines.push(line);
732
+ return;
733
+ }
734
+ if (/^#{2,3}\s/u.test(line)) {
735
+ const matched = line.match(LESSONS_ENTRY_HEADING_RE);
736
+ current = matched === null ? null : { id: matched[1], line: index + 1, heading: line, lines: [line] };
737
+ if (current) blocks.push(current);
738
+ return;
739
+ }
740
+ if (current) current.lines.push(line);
741
+ });
742
+ return blocks;
743
+ }
744
+
745
+ // 旧条目判定(结构级,不做语义判断):非模板标题形态(迁移冒号形态 / 裸标题等历史写法,含 T11
746
+ // 迁移保留原标题形态的条目)或「首发」键指向别的 change。其余缺字段条目按「新条目」处置——
747
+ // 新条目只有标题与正文(无任何字段键)时同样落在 BLOCK 分支(M-5 的失效模式)。
748
+ function lessonsEntryIsOld(block, originKey, state) {
749
+ if (!LESSONS_TEMPLATE_HEADING_RE.test(block.heading)) return true;
750
+ if (originKey === null) return false;
751
+ for (const line of block.lines.slice(1)) {
752
+ const matched = line.match(LESSONS_FIELD_LINE_RE);
753
+ if (matched && matched[1].trim() === originKey) {
754
+ const origin = matched[2].trim();
755
+ return origin !== '' && !origin.includes(state.activeChange);
756
+ }
757
+ }
758
+ return false;
759
+ }
760
+
761
+ // ④ 字段键存在性(C20):新 change 的新条目缺任一键 → BLOCKED;旧条目 / 旧 change → WARN 渐进。
762
+ function checkLessonsEntryFields({ content, node, state, keys }) {
763
+ const originKey = keys.find((key) => key.includes('首发')) ?? null;
764
+ const blocked = [];
765
+ const warned = [];
766
+ for (const block of lessonsEntryBlocks(content)) {
767
+ const present = new Map();
768
+ for (const line of block.lines.slice(1)) {
769
+ const matched = line.match(LESSONS_FIELD_LINE_RE);
770
+ if (matched && !present.has(matched[1].trim())) present.set(matched[1].trim(), matched[2].trim());
771
+ }
772
+ const missing = keys.filter((key) => !present.has(key));
773
+ if (missing.length === 0) continue;
774
+ (lessonsEntryIsOld(block, originKey, state) ? warned : blocked)
775
+ .push({ id: block.id, line: block.line, missing });
776
+ }
777
+ const describe = (entry) => '.specs/LESSONS.md:' + entry.line + ' ' + entry.id
778
+ + '(缺 ' + entry.missing.join('/') + ')';
779
+ if (warned.length > 0) {
780
+ console.error('LESSONS WARN: LESSONS.md 有 ' + warned.length + ' 条旧条目缺字段键(迁移/既有条目渐进不阻断): '
781
+ + warned.map(describe).join('、'));
782
+ }
783
+ if (blocked.length === 0) return;
784
+ const guide = '恢复: 按 flow-kit/templates/LESSONS.md「条目格式」段补全字段键(' + keys.join(' / ')
785
+ + ';正文块不强制)后重试 exit ' + node.id;
786
+ if (!isNewChange(state)) {
787
+ console.error('LESSONS WARN: LESSONS.md 有 ' + blocked.length + ' 条条目缺字段键(旧 change 渐进不阻断): '
788
+ + blocked.map(describe).join('、') + ';' + guide);
789
+ return;
790
+ }
791
+ console.error('BLOCKED: LESSONS.md 有 ' + blocked.length + ' 条新条目缺字段键(新 change 强制新条目按模板条目格式书写):');
792
+ for (const entry of blocked) console.error(' - ' + describe(entry));
793
+ console.error(guide);
794
+ process.exit(1);
795
+ }
796
+
797
+ // ⑤ archive 出口的归档提名核对(对账 SUMMARY 份数 / 提名编号存在性 / 无提名理由)——归档提名
798
+ // 留痕且可核对。新 change BLOCKED / 旧 change WARN(C10)。
799
+ async function checkLessonsNomination({ state }) {
800
+ const problems = await lessonsNominationProblems(state);
801
+ if (problems.length === 0) return;
802
+ if (isNewChange(state)) {
803
+ console.error('BLOCKED: archive 出口的 evidence.lessonsNomination 不成立(' + problems.length + ' 项):');
804
+ for (const problem of problems) console.error(' - ' + problem);
805
+ console.error('恢复: workflow-state.mjs record archive \'{"summary":"<归档摘要>","lessonsNomination":'
806
+ + '{"scanned":<该 change 内 SUMMARY 份数>,"nominated":["L-NNN"],"reasonIfNone":"<无提名时的理由>"}}\' 补齐后重试 exit archive');
807
+ process.exit(1);
808
+ }
809
+ console.error('NOMINATION WARN: evidence.lessonsNomination 不成立(旧 change 渐进不阻断): ' + problems.join(';'));
410
810
  }
411
811
 
412
- // LESSONS.md 结构检测(verify / archive 出口):条目区外条目 + 同段内编号递增
413
812
  export async function runLessonsZoneGate({ node, state }) {
414
- if ((node.id !== 'verify' && node.id !== 'archive') || !state.activeChange) return;
813
+ if (!['open', 'verify', 'archive'].includes(node.id) || !state.activeChange) return;
415
814
  const lessonsFile = path.join(runRoot, '.specs', 'LESSONS.md');
416
- try {
417
- const content = await fs.readFile(lessonsFile, 'utf8');
418
- // 条目区锚点兼容:## 条目区(模板)/ ## 活跃条目 + ## 已解决条目(实际项目结构)——取最早条目段
419
- const zoneIndex = (() => {
420
- const hits = ['条目区', '活跃条目', '已解决条目']
421
- .map(s => content.search(new RegExp('^##\\s*' + s + '\\s*$', 'm')))
422
- .filter(i => i !== -1);
423
- return hits.length ? Math.min(...hits) : -1;
424
- })();
425
- const headings = [...content.matchAll(/^###\s*L-(\d+)/gm)];
426
- if (zoneIndex !== -1) {
427
- const outside = headings.some(h => h.index < zoneIndex);
428
- if (outside) {
429
- if (isNewChange(state)) {
430
- console.error('BLOCKED: LESSONS.md 有条目在条目区外(新 change 强制条目插入条目区);恢复: 移入条目区');
431
- process.exit(1);
432
- }
433
- // 诊断信息附带 zoneIndex/条目位置——偶发 WARN 排查时可直接定位(文件时序/编码差异兜底)
434
- console.error('WARN: LESSONS.md 有条目在条目区外(zoneIndex=' + zoneIndex + ', 条目数=' + headings.length + ', 区外条目: ' + headings.filter(h => h.index < zoneIndex).map(h => 'L-' + h[1]).join(',') + ')');
435
- }
436
- }
437
- const nums = headings.map(h => parseInt(h[1], 10));
438
- // 分段检测:按 ## 标题分段,仅同段内比较编号递增(多段 LESSONS 如「活跃条目/已解决条目」编号体系可独立)
439
- const sectionStarts = [...content.matchAll(/^##\s+.*$/gm)].map(m => m.index);
440
- for (let i = 1; i < nums.length; i++) {
441
- const sameSection = !sectionStarts.some(s => s > headings[i - 1].index && s < headings[i].index);
442
- if (sameSection && nums[i] <= nums[i - 1]) {
443
- if (isNewChange(state)) {
444
- console.error('BLOCKED: LESSONS.md 条目编号乱序(新 change 强制按编号插入条目区);恢复: 按 L-NNN 顺序插入');
445
- process.exit(1);
446
- }
447
- console.error('WARN: LESSONS.md 条目编号乱序(L-' + String(nums[i]).padStart(3, '0') + ' 应按序插入条目区)');
448
- break;
815
+ let content = null;
816
+ try { content = await fs.readFile(lessonsFile, 'utf8'); } catch { content = null; }
817
+ if (content !== null) {
818
+ checkLessonsEntryForm({ content, node, state });
819
+ if (node.id !== 'open') {
820
+ checkLessonsZoneAndOrder({ content, state });
821
+ const fieldKeys = await lessonsEntryFieldKeys();
822
+ if (fieldKeys === null) {
823
+ console.error('LESSONS 条目字段 未校验(模板缺失)——flow-kit/templates/LESSONS.md 或其「条目格式」样例缺席,'
824
+ + '字段键无法派生(修复: 按安装指引获取 flow-kit 模板后重试)');
825
+ } else {
826
+ checkLessonsEntryFields({ content, node, state, keys: fieldKeys });
449
827
  }
450
828
  }
451
- } catch {}
829
+ }
830
+ if (node.id === 'archive') await checkLessonsNomination({ state });
452
831
  }
453
832
 
454
833
  // STATE.md / CHANGELOG.md 倒序检测(archive 出口):决策日志与表格条目应顶部插入(新→旧)
@@ -752,7 +1131,26 @@ export async function runReviewExitGate({ node, state }) {
752
1131
  // [转待办](归档时进 KNOWN-ISSUES)。结构级校验,WARN 渐进不 BLOCK:旧 REVIEW 未按新格式写标记
753
1132
  // 只警告不阻断(防旧 REVIEW 卡死),执行者补标记后可消除。
754
1133
  const reviewText = await fs.readFile(reviewFile, 'utf8');
755
- const missingDisposition = reviewFindingsMissingDisposition(reviewText);
1134
+ // 发现位置(模板 2.2):发现写在旧 `## 发现` 而模板位置 `### 2.2 …详细发现` 下无条目——旧段不被
1135
+ // 任何出口消费,等于「记录后静默丢弃」。新 change BLOCKED + 逐条迁移指引;旧 change WARN 渐进。
1136
+ // 模板缺席(primary=null)时不判位置:模板派生判据不臆造(C9),旧形态解析与处置校验照常。
1137
+ const scope = await reviewFindingScope();
1138
+ const findings = reviewFindingsItems(reviewText, scope);
1139
+ const misplacedFindings = scope.primary !== null
1140
+ && !findings.some((item) => item.scope === 'primary')
1141
+ && reviewLegacyFindingsHasContent(reviewText);
1142
+ if (misplacedFindings) {
1143
+ const templateFile = (await buildSkeleton('REVIEW')).file ?? 'flow-kit/templates/REVIEW.md';
1144
+ if (isNewChange(state)) {
1145
+ console.error('BLOCKED: REVIEW.md 的发现写在模板外的段「## 发现」,而模板位置(第二轮下的 2.2 详细发现)无条目——新 change 强制写在模板位置');
1146
+ console.error('恢复: 把「## 发现」下的条目逐条移入「### 2.2 …详细发现」段内(模板: ' + templateFile
1147
+ + '),删除旧段后重试 exit review');
1148
+ process.exit(1);
1149
+ }
1150
+ console.error('REVIEW WARN: REVIEW.md 的发现写在模板外的段「## 发现」,模板位置 2.2 详细发现 无条目'
1151
+ + '——迁移到 2.2 后本警告消除(旧 change 渐进不阻断;模板: ' + templateFile + ')');
1152
+ }
1153
+ const missingDisposition = reviewFindingsMissingDisposition(reviewText, scope);
756
1154
  if (missingDisposition.length > 0) {
757
1155
  if (isNewChange(state)) {
758
1156
  console.error('BLOCKED: REVIEW.md 发现区 ' + missingDisposition.length + ' 项条目缺处置状态标记([已修]/[升级]/[转待办])——新 change 强制每项发现须有处置');
@@ -767,7 +1165,7 @@ export async function runReviewExitGate({ node, state }) {
767
1165
  // 条目标 [转待办] 时须同时存在用户裁决记录(同段或文末含「用户裁决:接受延期」且指向该条目,
768
1166
  // 并由 [升级] 承接);缺失 → 新 change BLOCKED / 旧 change WARN 渐进。Minor 不受影响;
769
1167
  // Major [升级]/[已修] 直接放行。
770
- const deferredMajor = reviewDeferredMajorProblems(reviewText);
1168
+ const deferredMajor = reviewDeferredMajorProblems(reviewText, scope);
771
1169
  if (deferredMajor.length > 0) {
772
1170
  const guide = ';恢复: 先把 Major 改为 [升级] 交用户裁决;用户接受延期后在同段或文末记录「用户裁决:接受延期」并指向该条目(由 [升级] 承接)';
773
1171
  if (isNewChange(state)) {