flow-comet 1.6.4 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +36 -6
  3. package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
  4. package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
  5. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +29 -4
  7. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +174 -0
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +17 -95
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +136 -19
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +54 -18
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
  15. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  16. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +25 -10
  17. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +4 -2
  18. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +21 -13
  19. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +163 -0
  20. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +448 -0
  22. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +396 -27
  23. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1035 -172
  24. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +129 -98
  25. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  26. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +797 -232
  27. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +91 -22
  28. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +69 -13
  32. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +454 -135
  33. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +109 -13
  35. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
  36. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +149 -34
  37. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +79 -9
  38. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  39. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +78 -8
  40. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
  41. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +167 -3
  42. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
  43. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +287 -0
  44. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1454 -16
  45. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1205 -77
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +52 -11
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
  50. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +9 -1
  51. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
  52. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +22 -6
  53. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
  54. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +18 -5
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +4100 -0
  56. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
  57. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
  58. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +203 -4
  59. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
  60. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  61. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  62. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  63. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  64. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  65. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  66. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  67. package/.flow-comet/skills/flow-comet-execute/SKILL.md +42 -15
  68. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  69. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  70. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  71. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  72. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  73. package/.flow-comet/skills/flow-comet-plan/SKILL.md +21 -10
  74. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  75. package/.flow-comet/skills/flow-comet-review/SKILL.md +33 -18
  76. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  77. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +44 -16
  78. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  79. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  80. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  81. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  82. package/README.md +3 -3
  83. package/package.json +1 -1
  84. package/scripts/dsh-bridge.mjs +2 -2
  85. package/scripts/lib/installer-flowkit.mjs +43 -3
@@ -10,6 +10,9 @@
10
10
  import { promises as fs } from 'fs';
11
11
  import path from 'path';
12
12
  import { EVOLVE_METADATA_SECTION, EVOLVE_METADATA_FIELDS } from './state-schema.mjs';
13
+ // 二级段体的段界(同级标题 / 分隔线 / 文末)取 lib/section-body.mjs 的唯一实现:本文件不再持有
14
+ // 第二份「按标题切段体」的行扫描(同一件事两份实现必然分叉)。
15
+ import { sectionBody } from './lib/section-body.mjs';
13
16
 
14
17
  // 既有 AI 上下文文档探测清单(与 flow-kit 入场判定同源:AGENTS/CLAUDE/Cursor/Windsurf/Copilot/Cline)
15
18
  const AI_DOC_CANDIDATES = [
@@ -174,15 +177,22 @@ async function contextSections(runRoot) {
174
177
  // 无任何生产者,故已从通过判据移除(取值单形 = state-schema 的 EVOLVE_METADATA_FIELDS)。本常量
175
178
  // 只用于**提示**:既有文档带该别名时,报错文案点名它并给出应写字段,让格式问题可见且可改写。
176
179
  const EVOLVE_DEPRECATED_SUGGESTION_FIELD = '下次同步建议';
180
+ // 「已锁决策」段名:在场判定与段内判定共用本常量(两处各写一份字面量,改名时必然分叉)。
181
+ const LOCKED_DECISIONS_SECTION = '已锁决策';
182
+
177
183
  // 模板关键格式检查(flow-kit/templates/CONTEXT.md 基准——段存在时校验其内格式,确定性检查)
178
184
  const CONTEXT_FORMAT_CHECKS = [
179
185
  {
180
186
  name: '已锁决策条目日期前缀',
181
- applies: (t) => t.includes('## 已锁决策'),
187
+ applies: (t) => t.includes('## ' + LOCKED_DECISIONS_SECTION),
182
188
  // 段内列表条目须带日期 `- [20xx-xx-xx]`;占位条目([xxx] 形态/待沉淀类/模板尖括号)放行——
183
- // 新项目骨架(无历史决策)不应被格式校验拒绝(DF-5)。
189
+ // 新项目骨架(无历史决策)不应被格式校验拒绝(DF-5)。段体经 contextSectionBody 切片:段界只由
190
+ // lib/section-body.mjs 决定(围栏内的标题不结束段体),本文件不再自带第二份「按标题切段」——
191
+ // 此前这里用字符串字面量切分(`.split('## 已锁决策')` 后再 `.split('\n##')`),是一份只在本文件
192
+ // 存在、且静态锁看不见的段体切片:同一个「这一段到哪里结束」由两处决定时,围栏 / 分隔线 / 段名
193
+ // 归一的差异迟早让两处给出不同答案。
184
194
  passes: (t) => {
185
- const seg = (t.split('## 已锁决策')[1] ?? '').split('\n##')[0];
195
+ const seg = contextSectionBody(t, LOCKED_DECISIONS_SECTION) ?? '';
186
196
  const items = seg.split('\n').filter((l) => /^\s*-\s+/.test(l));
187
197
  if (items.length === 0) return true; // 空段放行
188
198
  const bare = items.filter((l) => {
@@ -206,14 +216,14 @@ const CONTEXT_FORMAT_CHECKS = [
206
216
  // 「跑过一次但字段写残」正是最需要拦的半成品(段在场却少字段,元数据双落点会静默失真)。
207
217
  // 段名与三字段名都取自 state-schema.mjs 的单一常量集(写方 evolve.mjs 同源),本处不再写字面量。
208
218
  name: EVOLVE_METADATA_SECTION + '三字段',
209
- // 三字段判定**限定在段内**(sectionBody 切片):全文 includes 会被别处的同名字段蒙混过关——
210
- // 例如 intel-scan 段有 `**scanner**` 而 evolve 段少这一个字段,全文判定照样放行。
211
- applies: (t) => sectionBody(t, '## ' + EVOLVE_METADATA_SECTION) !== null,
219
+ // 三字段判定**限定在段内**(contextSectionBody 切片,段界来自单源):全文 includes 会被别处的同名字
220
+ // 字段蒙混过关——例如 intel-scan 段有 `**scanner**` 而 evolve 段少这一个字段,全文判定照样放行。
221
+ applies: (t) => contextSectionBody(t, EVOLVE_METADATA_SECTION) !== null,
212
222
  // 通过判据是**单形**的:取值只认常量集(写方真实产出的三个字段名)。旧的协作期容差别名
213
223
  // (`下次同步建议`)没有任何生产者,已从判据中移除——容纳它就是「校验集合 ⊃ 生产集合」,
214
224
  // 写残的段会被静默放行。带旧别名的既有文档由下方 hint 给出可见的改写指引,不是静默失败。
215
225
  passes: (t) => {
216
- const segment = sectionBody(t, '## ' + EVOLVE_METADATA_SECTION) ?? '';
226
+ const segment = contextSectionBody(t, EVOLVE_METADATA_SECTION) ?? '';
217
227
  return EVOLVE_METADATA_FIELDS.every((field) => segment.includes('**' + field + '**'));
218
228
  },
219
229
  hint: '字段 ' + EVOLVE_METADATA_FIELDS.join(' / ') + ';与 intel-scan 段同构'
@@ -301,23 +311,16 @@ function headingSet(text) {
301
311
  // `## evolve 元数据`)不得算段在场——可选段的「缺席不报」语义完全依赖这一点;字段判定限定段内,
302
312
  // 否则别处的同名标签会替缺失字段蒙混过关。必填段的同名检查沿用历史 includes 写法(缺段另有
303
313
  // missingSections 兜底,报道面不变),故两条检查的在场判据措辞不同是刻意的,不是漏改。
304
- function sectionBody(body, headingName) {
314
+ // 段界(同级标题 / 分隔线 / 文末)由 lib/section-body.mjs 单点决定,本文件只表达命中方式:恰好
315
+ // 二级 + 段名归一后相等。调用方给的是**结构文本**(围栏代码块已剥离,见 validateContext),因此围栏
316
+ // 里的书写样例既不结束段体、也不被当成数据。
317
+ function contextSectionBody(structureText, headingName) {
305
318
  const wanted = normalizeSectionName(headingName);
306
- const kept = [];
307
- let inSection = false;
308
- for (const line of String(body ?? '').split('\n')) {
309
- const heading = /^(#{1,6})[ \t]+(.+?)[ \t]*$/.exec(line);
310
- if (heading) {
311
- const level = heading[1].length;
312
- if (inSection && level <= 2) break; // 到下一个同级或更高级标题即段结束
313
- if (!inSection && level === 2 && normalizeSectionName(heading[2]) === wanted) {
314
- inSection = true;
315
- continue;
316
- }
317
- }
318
- if (inSection) kept.push(line);
319
- }
320
- return inSection ? kept.join('\n') : null;
319
+ return sectionBody(
320
+ structureText,
321
+ (heading) => heading.level === 2 && normalizeSectionName(heading.text) === wanted,
322
+ { level: 2, endOnSeparator: false },
323
+ );
321
324
  }
322
325
 
323
326
  // 校验 .specs/CONTEXT.md 7 段结构 + 模板关键格式;文件缺失 = 全缺。返回
@@ -20,12 +20,17 @@
20
20
  // 只读边界:scan 零写入;apply 的写入面只有三处——项目级文档(CONTEXT.md / ARCHITECTURE.md)、
21
21
  // .specs/evolve/ 下的报告、以及 state 的 last_evolve_at(经 workflow-state.mjs 的 config set
22
22
  // 通道写入,本脚本不直写 state 文件)。扫描内容严格限定在归档设计文档的沉淀段。
23
+ //
24
+ // 另:scan 末尾输出「结构问题」段——`.specs/ARCHITECTURE.md` 在场时按模板(8 个 H2)+ §3 的
25
+ // `### ADR-<数字>` 条目形态报告结构问题;文件缺席 / 骨架不可派生时声明跳过或未校验。该段与沉淀
26
+ // 候选互不依赖,且**只读、不阻断、不写 state**(结构问题不进退出码)。
23
27
 
24
28
  import { spawnSync } from 'child_process';
25
29
  import { promises as fs } from 'fs';
26
30
  import path from 'path';
27
31
  import { fileURLToPath } from 'url';
28
32
  import { normalizeHeading } from './route-node.mjs';
33
+ import { buildSkeleton } from './lib/guard-artifact-skeleton.mjs';
29
34
  import { readProtocolFile, validateProtocolSchema } from './protocol-utils.mjs';
30
35
  import {
31
36
  writeFileAtomic,
@@ -62,6 +67,14 @@ const CONTEXT_FILE = 'CONTEXT.md';
62
67
  const ARCHITECTURE_FILE = 'ARCHITECTURE.md';
63
68
  const DOC_CONTEXT = SPECS_DIR + '/' + CONTEXT_FILE;
64
69
  const DOC_ARCHITECTURE = SPECS_DIR + '/' + ARCHITECTURE_FILE;
70
+ // 项目级工件检查的骨架键(大小写不敏感;登记表用模板基名大写)
71
+ const ARCHITECTURE_KEY = 'ARCHITECTURE';
72
+ // ADR 条目(行锚定):模板 §3 的 `### ADR-<数字> · <标题>` 形态。模板里的占位条目(`### ADR-NNN`)
73
+ // 是字段键的**形态样例**而非真 ADR,不参与条目校验。
74
+ const ADR_ENTRY = /^###[ \t]+ADR-(\d+)(?![0-9A-Za-z])/u;
75
+ const ADR_PLACEHOLDER = /^###[ \t]+ADR-(?:NNN|<)/u;
76
+ // 条目字段行 = `- **状态**:…`(半角 / 全角冒号都认)。行锚定:正文里提一句「代价」不算填了该字段。
77
+ const ADR_FIELD = /^[ \t]*[-*][ \t]+\*\*(.+?)\*\*[ \t]*[::]/u;
65
78
  const STATE_SCRIPT = 'workflow-state.mjs';
66
79
  // `## evolve 元数据` 的段名与三字段名来自 state-schema.mjs 的单一常量集(写方 = 本节 / 校验方 =
67
80
  // context-init.mjs 的格式校验同源);段侧字段序即常量序,双落点首字段与 state 的 STATE_KEY 同名。
@@ -487,9 +500,170 @@ async function printScan(plan, out = console) {
487
500
  if (plan.scanned.length > 0) {
488
501
  out.log('EVOLVE: 已扫 change 清单:' + plan.scanned.map(changeSummary).join(' · '));
489
502
  }
503
+ await printArchitectureStructure(plan.root, out);
490
504
  out.log('EVOLVE: 应用请执行 evolve.mjs apply <id> --root <根>(未应用的候选不会写入)');
491
505
  }
492
506
 
507
+ // ---------- 项目级工件:ARCHITECTURE 结构检查(只读 · 不阻断) ----------
508
+ // 依据 DESIGN-CLARIFICATIONS C19 / AC-20③:`.specs/ARCHITECTURE.md` 存在时校验模板的 8 个 H2 段
509
+ // 与 §3 下 `### ADR-<数字>` 条目的 7 个字段键(无 ADR 条目时该段可只写「暂无」,不算问题)。
510
+ // 文件缺席 → 跳过并说明;骨架不可派生(模板 / 登记表缺席)→ 未校验并说明——不内置兜底骨架,
511
+ // 但同样不得把「无法比对」静默说成「通过」。
512
+ // 只读边界:零写入、不写 state、不参与退出码——结构问题只进报告(侧命令不阻断任何流程)。
513
+ // 单一实现纪律(L-067):段形取骨架模块(模板 + 登记表);ADR 条目形态**从模板 §3 直接派生**
514
+ // (登记表未登记 ADR 条目形态,C19),字段键因此不在本文件里另写一份字面清单。
515
+ export async function collectArchitectureStructure(root) {
516
+ const display = DOC_ARCHITECTURE;
517
+ const text = await readText(path.join(root, DOC_ARCHITECTURE));
518
+ if (text === null) {
519
+ return {
520
+ display,
521
+ exists: false,
522
+ checked: false,
523
+ note: '文件不在场(可选工件,项目未采用)',
524
+ problems: [],
525
+ basis: null,
526
+ };
527
+ }
528
+ const skeleton = await buildSkeleton(ARCHITECTURE_KEY, { runRoot: root });
529
+ if (!skeleton.derived) {
530
+ return { display, exists: true, checked: false, note: skeletonGapNote(skeleton), problems: [], basis: null };
531
+ }
532
+ const templateText = skeleton.file === null
533
+ ? null
534
+ : await readText(path.resolve(root, ...skeleton.file.split('/')));
535
+ const adrFieldKeys = adrFieldKeysOfTemplate(templateText);
536
+ const problems = h2SectionProblems(skeleton, text).concat(adrEntryProblems(text.split('\n'), adrFieldKeys));
537
+ return {
538
+ display,
539
+ exists: true,
540
+ checked: true,
541
+ note: null,
542
+ problems,
543
+ basis: architectureBasis(skeleton, adrFieldKeys),
544
+ };
545
+ }
546
+
547
+ // 缺的 H2 段(段名宽容匹配委托骨架里的 headingPattern):聚合成一条问题——8 个段逐个报会把报告
548
+ // 撞成清单,读者要的是「哪几个缺」。
549
+ function h2SectionProblems(skeleton, text) {
550
+ const missing = skeleton.sections.filter((section) => !section.pattern.test(text));
551
+ if (missing.length === 0) return [];
552
+ return ['缺 H2 段 ' + missing.length + '/' + skeleton.sections.length + ':'
553
+ + missing.map((section) => section.name).join(' · ')];
554
+ }
555
+
556
+ // 报告里的「依据」行:段数与 ADR 字段键都取自实际比对用的源(骨架 / 模板),不另抄一份数字。
557
+ function architectureBasis(skeleton, adrFieldKeys) {
558
+ const sections = skeleton.sections.length + ' 个 H2 段(骨架 = `' + skeleton.file + '` + 登记表)';
559
+ return adrFieldKeys.length === 0
560
+ ? sections + ';§3 ADR 条目未校验(模板 §3 无字段样例)'
561
+ : sections + ';§3 的 `### ADR-<数字>` 条目 ' + adrFieldKeys.length + ' 个字段键(' + adrFieldKeys.join(' · ') + ')';
562
+ }
563
+
564
+ // 骨架不可派生的原因 → 人读一句(措辞与「未校验」口径一致:声明「未校验」,不冒充「通过」)
565
+ function skeletonGapNote(skeleton) {
566
+ switch (skeleton.reason) {
567
+ case 'template-missing':
568
+ return '模板缺失 · `flow-kit/templates/' + ARCHITECTURE_FILE + '`';
569
+ case 'template-undeclared':
570
+ return '登记表未声明 ARCHITECTURE 的模板路径';
571
+ case 'template-empty':
572
+ return '模板无 H2 段 · `flow-kit/templates/' + ARCHITECTURE_FILE + '`';
573
+ case 'registry-missing':
574
+ case 'registry-unreadable':
575
+ return '登记表不可读(`reference/artifact-templates.json`:' + skeleton.reason + ')';
576
+ case 'unknown-key':
577
+ return '登记表未登记 ARCHITECTURE';
578
+ default:
579
+ return '骨架不可派生(' + String(skeleton.reason) + ')';
580
+ }
581
+ }
582
+
583
+ // §3(ADR 列表)的段范围 = 标题行带 ADR 的那个 H2。段名在不同项目里可能被改写(「架构决策记录」不带
584
+ // ADR 字样),定位不到时返回 null——调用方退回全文范围;形态判据只认行锚定的 `### ADR-<数字>`,
585
+ // 正文里引用 ADR 编号不会被当成条目。
586
+ function adrSectionRange(lines) {
587
+ for (let i = 0; i < lines.length; i += 1) {
588
+ const heading = headingOf(lines[i]);
589
+ if (heading === null || heading.level !== 2) continue;
590
+ if (!/adr/iu.test(stripCr(lines[i]))) continue;
591
+ return { start: i, end: sectionEnd(lines, i, 2, lines.length) };
592
+ }
593
+ return null;
594
+ }
595
+
596
+ // 模板 §3 的 ADR 条目字段键:优先取占位条目(`### ADR-NNN`)的字段键;模板没有占位条目时取 §3 内
597
+ // 条目字段键的并集;两者都取不到 → 空列表(该项声明「未校验」,不拿空清单去判「字段齐备」)。
598
+ function adrFieldKeysOfTemplate(templateText) {
599
+ const lines = String(templateText ?? '').replace(/^\uFEFF/u, '').replace(/\r\n?/gu, '\n').split('\n');
600
+ const range = adrSectionRange(lines);
601
+ if (range === null) return [];
602
+ const entries = adrEntries(lines, range);
603
+ const placeholder = entries.find((entry) => ADR_PLACEHOLDER.test(entry.title) && entry.keys.length > 0);
604
+ return [...new Set(placeholder !== undefined ? placeholder.keys : entries.flatMap((entry) => entry.keys))];
605
+ }
606
+
607
+ // §3 条目校验:每个 `### ADR-<数字>` 条目必须在自己块内出现全部字段键(占位条目 id 为 null,不校验)。
608
+ function adrEntryProblems(lines, adrFieldKeys) {
609
+ if (adrFieldKeys.length === 0) return [];
610
+ const range = adrSectionRange(lines) ?? { start: -1, end: lines.length };
611
+ const problems = [];
612
+ for (const entry of adrEntries(lines, range)) {
613
+ if (entry.id === null) continue;
614
+ const missing = adrFieldKeys.filter((key) => !entry.keys.includes(normalizeFieldKey(key)));
615
+ if (missing.length > 0) {
616
+ problems.push('§3 ' + entry.id + ' 缺字段 ' + missing.length + '/' + adrFieldKeys.length + ':'
617
+ + missing.join(' · '));
618
+ }
619
+ }
620
+ return problems;
621
+ }
622
+
623
+ // §3 内的条目切分(**单一实现**:模板侧取字段键、工件侧校验字段都从这里来):条目 = 一个 1~3 级
624
+ // 标题开始、到下一个 1~3 级标题前的块(`####` 属于块内)。id 只对 `### ADR-<数字>` 赋值——模板里的
625
+ // `ADR-NNN` 占位条目因此只贡献字段键形态,永远不被当作真 ADR 去校验。
626
+ function adrEntries(lines, range) {
627
+ const entries = [];
628
+ let current = null;
629
+ for (let i = range.start + 1; i < range.end; i += 1) {
630
+ const line = stripCr(lines[i]);
631
+ if (/^#{1,3}[ \t]/u.test(line)) {
632
+ const adr = ADR_ENTRY.exec(line);
633
+ current = { title: line, id: adr === null ? null : 'ADR-' + adr[1], keys: [] };
634
+ entries.push(current);
635
+ continue;
636
+ }
637
+ const field = ADR_FIELD.exec(line);
638
+ if (field !== null && current !== null) current.keys.push(normalizeFieldKey(field[1]));
639
+ }
640
+ return entries;
641
+ }
642
+
643
+ function normalizeFieldKey(raw) {
644
+ return String(raw).replace(/\s+/gu, ' ').trim().toLowerCase();
645
+ }
646
+
647
+ // 「结构问题」段(AC-20③ / C19):三个分支各有独立措辞——文件缺席(跳过)/ 骨架不可派生(未校验)
648
+ // / 实际比对(0 项或逐条列出)。只读、不阻断:结构问题不进退出码,也不写 state。
649
+ async function printArchitectureStructure(root, out) {
650
+ const structure = await collectArchitectureStructure(root);
651
+ const head = 'EVOLVE: 结构问题(' + structure.display + '):';
652
+ if (!structure.exists) {
653
+ out.log(head + '跳过——' + structure.note);
654
+ return;
655
+ }
656
+ if (!structure.checked) {
657
+ out.log(head + '未校验(' + structure.note + ')');
658
+ return;
659
+ }
660
+ out.log(head + (structure.problems.length === 0
661
+ ? '0 项'
662
+ : structure.problems.length + ' 项(只读报告,不阻断)'));
663
+ for (const problem of structure.problems) out.log(' - ' + problem);
664
+ out.log('EVOLVE: 结构问题依据:' + structure.basis);
665
+ }
666
+
493
667
  // ---------- 应用 ----------
494
668
 
495
669
  function fieldLine(key, value) {
@@ -1,7 +1,7 @@
1
1
  #!/usr/bin/env node
2
2
  // flow-comet 引擎自测套件(L1 回归基线的载体)
3
3
  //
4
- // 本文件 = runner + 底部自检(收口判据)。场景数据在 scenarios/{a..m}.mjs(按机制面分组),
4
+ // 本文件 = runner + 底部自检(收口判据)。场景数据在 scenarios/{a..n}.mjs(按机制面分组),
5
5
  // 夹具 / 断言 / 文本锚判据在 lib/ 下,与 system-test 共享的工具与计数派生各有单一来源模块。
6
6
  //
7
7
  // 每个场景 = 独立临时目录(fs.mkdtemp)+ 伪造 .flow-comet/flow-comet-state.json(currentNode +
@@ -19,9 +19,7 @@ import {
19
19
  } from './lib/test-helpers.mjs';
20
20
  import {
21
21
  BUILTIN_PROTOCOL_SOURCE,
22
- REPO_ROOT,
23
22
  createdDirs,
24
- isAuthoritativeSourceRepo,
25
23
  makeTmp,
26
24
  sleepSync,
27
25
  } from './lib/test-fixtures.mjs';
@@ -29,16 +27,7 @@ import {
29
27
  scenarioProtocolPath,
30
28
  } from './lib/test-assertions.mjs';
31
29
  import {
32
- PUBLIC_CODE_RE,
33
- SCENARIO_COUNT_FILES,
34
- SCENARIO_COUNT_FILES_MAINTAINER,
35
- SYSTEM_TEST_COUNT_FILES,
36
- SYSTEM_TEST_COUNT_FILES_MAINTAINER,
37
- countSyncProblems,
38
- internalDocsProblems,
39
- maintainerFacePresent,
40
- maintainerFaceSkips,
41
- vocabularyMirrorProblems,
30
+ publicFaceSelfCheck,
42
31
  } from './lib/text-anchor-checks.mjs';
43
32
 
44
33
  import { ENTRIES as SCENARIOS_A } from './scenarios/a.mjs';
@@ -54,6 +43,7 @@ import { ENTRIES as SCENARIOS_J } from './scenarios/j.mjs';
54
43
  import { ENTRIES as SCENARIOS_K } from './scenarios/k.mjs';
55
44
  import { ENTRIES as SCENARIOS_L } from './scenarios/l.mjs';
56
45
  import { ENTRIES as SCENARIOS_M } from './scenarios/m.mjs';
46
+ import { ENTRIES as SCENARIOS_N } from './scenarios/n.mjs';
57
47
 
58
48
  let passed = 0;
59
49
  const failures = [];
@@ -72,6 +62,7 @@ const SCENARIOS = [
72
62
  ...SCENARIOS_K,
73
63
  ...SCENARIOS_L,
74
64
  ...SCENARIOS_M,
65
+ ...SCENARIOS_N,
75
66
  ];
76
67
 
77
68
  // ---------- 运行 ----------
@@ -101,89 +92,20 @@ for (const sc of SCENARIOS) {
101
92
 
102
93
  console.log('RESULT: ' + passed + '/' + SCENARIOS.length + ' scenarios passed');
103
94
 
104
- // 文档一致性自检(场景数纪律 + 公开产物零代号纪律工具化):
105
- // ① 场景数:受检清单文档须与 SCENARIOS.length 一致(全变体检查),且清单条目必须真实存在
106
- // (AC-14:缺失显式报告,不静默跳过);
107
- // ② 公开产物零代号:公开文档不得含过程代号(场景编号/修复编号/批次/缺陷编号/问题级/验证代号/验证轮次/未公开概念——历史 CHANGELOG 回归实证)。
108
- // 仅权威源检出执行;安装副本(目标项目)无 flow-comet 文档面,跳过。
109
- if (isAuthoritativeSourceRepo()) {
110
- // ①a 受检面可见化(F2 防漂移):实际受检文件数由模块级常量**推导**、不硬编码——分发组 =
111
- // SCENARIO_COUNT_FILES ∪ SYSTEM_TEST_COUNT_FILES(后者为前者子集),维护者组 =
112
- // SCENARIO_COUNT_FILES_MAINTAINER ∪ SYSTEM_TEST_COUNT_FILES_MAINTAINER(后者为前者子集);
113
- // 维护者面缺席(CI 全新检出 / worktree)时按组跳过语义只计分发面。本行是对外可复核的
114
- // 「覆盖面事实」——清单增删/口径漂移在此直接可见,不再依赖人工核对注释(F2 根因)。
115
- const distFaceCount = new Set([...SCENARIO_COUNT_FILES, ...SYSTEM_TEST_COUNT_FILES]).size;
116
- const maintainerFaceCount = maintainerFacePresent()
117
- ? new Set([...SCENARIO_COUNT_FILES_MAINTAINER, ...SYSTEM_TEST_COUNT_FILES_MAINTAINER]).size
118
- : 0;
119
- console.log('受检面: ' + (distFaceCount + maintainerFaceCount) + ' 文件(分发 ' + distFaceCount
120
- + ' + 维护者 ' + maintainerFaceCount + ')');
121
- // ① 计数一致性受检清单(分发组恒检 + 维护者组整组在场时检;判据与场景 105 共用同一实现)
122
- // SCENARIO_COUNT_FILES(_MAINTAINER) / SYSTEM_TEST_COUNT_FILES(_MAINTAINER) 为模块级常量
123
- // (见文件头定义)——场景数与系统测试集项数两套计数合并检查
124
- for (const problem of await countSyncProblems()) {
125
- failures.push({ name: '计数一致性', error: problem });
126
- console.error('FAIL: 计数一致性\n' + problem);
127
- }
128
-
129
- // ①b 维护文档机检(docs/internal 死引用 + ROADMAP 最低结构;整组缺席即跳过)
130
- for (const problem of internalDocsProblems()) {
131
- failures.push({ name: '维护文档机检', error: problem });
132
- console.error('FAIL: 维护文档机检\n' + problem);
133
- }
134
-
135
- // ①c 维护者面缺席可见化:结构性缺席(worktree / CI 全新检出)不判失败(退出码不变、不误红),
136
- // 但必须可见——逐面输出 SKIP 行(面名 + 原因 + 本检出未执行什么校验 + 回维护者主树重跑的指引)。
137
- for (const skip of maintainerFaceSkips()) {
138
- console.log('SKIP: ' + skip.face + ' — ' + skip.reason
139
- + ';本次检出未执行该面校验,请在维护者主树重跑本套件(主树 L1),勿把跳过当成已校验。');
140
- }
141
-
142
- // ② 公开文档零代号(公开产物纪律——变更日志历史编号回归的教训)
143
- const PUBLIC_DOCS = [
144
- 'README.md', 'README-zh.md', 'CONTRIBUTING.md', 'CONTRIBUTING-zh.md',
145
- 'SECURITY.md', 'SECURITY-zh.md', 'CODE_OF_CONDUCT.md', 'CODE_OF_CONDUCT-zh.md',
146
- 'CHANGELOG.md', 'CHANGELOG-zh.md',
147
- 'docs/INSTALLATION.md', 'docs/INSTALLATION-zh.md', 'docs/MECHANISM.md', 'docs/MECHANISM-zh.md',
148
- 'docs/USAGE.md', 'docs/USAGE-zh.md',
149
- 'docs/TROUBLESHOOTING.md', 'docs/TROUBLESHOOTING-zh.md', 'docs/VERSIONS.md', 'docs/VERSIONS-zh.md',
150
- '.github/PULL_REQUEST_TEMPLATE.md',
151
- '.github/ISSUE_TEMPLATE/1-bug_report.yml', '.github/ISSUE_TEMPLATE/2-feature_request.yml',
152
- '.github/ISSUE_TEMPLATE/3-question.md', '.github/ISSUE_TEMPLATE/4-task.md',
153
- ];
154
- // 词表判据 = 模块级 PUBLIC_CODE_RE(与 .githooks/internal-codes.mjs 的 BANNED 同判据,
155
- // 见其定义处的同步约定;维护文档机检场景族另有该判据的判别力/边界锚)。
156
- for (const rel of PUBLIC_DOCS) {
157
- let text;
158
- try {
159
- text = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
160
- } catch (e) {
161
- // ENOENT 同样显式报告:本清单全部为随仓库分发的文件,任何权威源检出都应存在——
162
- // 静默跳过会让"永不生效的条目"藏身(同类 AC-14 缺陷)。
163
- failures.push({ name: '公开产物零代号(' + rel + ')', error: '文件缺失: ' + e.message });
164
- console.error('FAIL: 公开产物零代号(' + rel + ')\n文件缺失: ' + e.message);
165
- continue;
166
- }
167
- const m = text.match(PUBLIC_CODE_RE);
168
- if (m) {
169
- failures.push({ name: '公开产物零代号(' + rel + ')', error: rel + ' 含过程代号: "' + m[0] + '"' });
170
- console.error('FAIL: 公开产物零代号(' + rel + ')\n' + rel + ' 含过程代号: "' + m[0] + '"');
171
- }
172
- }
173
-
174
- // ③ 词表镜像漂移:主仓私有的词表单一来源与套件内的同义镜像必须**逐字符
175
- // 等价**——两侧此前只有注释互指"同步"、零一致性判据:主仓增补模式时分发侧扫描静默落后
176
- // (新词可在公开面长期存活而套件全绿),反向则分发面误红。判据只读文件、不改任何判定语义。
177
- for (const problem of vocabularyMirrorProblems()) {
178
- failures.push({ name: '词表镜像漂移', error: problem });
179
- console.error('FAIL: 词表镜像漂移\n' + problem);
180
- }
95
+ // 文档一致性自检(场景数纪律 + 公开产物零代号纪律工具化):形态分派(权威源检出 / 包形态 / 安装
96
+ // 副本)与四条判据(计数一致性 / 维护文档机检 / 公开产物零代号 / 词表镜像)的唯一实现在
97
+ // lib/text-anchor-checks.mjs 的 publicFaceSelfCheck——本处只负责调用与打印。该判定接受任意根,
98
+ // 故它另有常驻场景锚(公开面形态分派探针),不必等到在包形态里整跑一次才知道分派对不对。
99
+ const selfCheck = await publicFaceSelfCheck();
100
+ if (selfCheck.skip !== null) {
101
+ // 该形态不含这一面:仍然显式可见——SKIP = 未校验,不是通过。
102
+ console.log(selfCheck.skip.notice);
181
103
  } else {
182
- // 安装副本形态:.githooks 是主仓私有面(随 clone 不分发)→ 该判据**不适用**。结构性缺席
183
- // 不判失败(退出码不变、不误红),但必须显式可见——未验证 ≠ 通过,不得静默跳过。
184
- console.log('SKIP/NOT-APPLICABLE: 词表镜像漂移判据(.githooks 为主仓私有面)'
185
- + ';本次检出无该私有面,未执行「词表单一来源 ↔ 套件同义镜像」的逐字符等价性比对'
186
- + '——请在主仓私有面在场处重跑本套件(主树 L1),勿把不适用当成已校验。');
104
+ for (const notice of selfCheck.notices) console.log(notice);
105
+ for (const problem of selfCheck.problems) {
106
+ failures.push(problem);
107
+ console.error('FAIL: ' + problem.name + '\n' + problem.error);
108
+ }
187
109
  }
188
110
 
189
111
  // 清理验证:自测套件自身创建的临时目录不留残留
@@ -3,15 +3,16 @@
3
3
  //
4
4
  // 报告分层:
5
5
  // · 确定性层:文件 / 结构可判项——项目上下文段与格式、经验条目编号连续性、技术债表项数、
6
- // 可选工具在场判定、版本历史统计。每项都带计数与判据;同一冻结树两次运行逐字节一致。
6
+ // 可选工具在场判定、版本历史统计、架构文档结构(`.specs/ARCHITECTURE.md`,可选工件)。
7
+ // 每项都带计数与判据;同一冻结树两次运行逐字节一致。
7
8
  // · 增补层:代码体检工具(brooks-lint)在场时,由 agent 执行其 4 维体检并把结果并入同一份
8
9
  // 报告、标注来源;脚本不执行 agent 技能,缺省保留占位而不伪造结论。
9
10
  // · 降级声明:可选外部工具不在场时显式声明原因。判据只锚「确定性层完整 + 降级声明可见」——
10
11
  // 环境缺可选工具不构成失败(这些工具是可选项,不是依赖)。
11
12
  //
12
13
  // 只读边界:
13
- // · 读:.specs/CONTEXT.md、.specs/LESSONS.md、.specs/health/*.md(基线)、git 历史、
14
- // 可选工具的在场探测(文件 / 路径判定);
14
+ // · 读:.specs/CONTEXT.md、.specs/LESSONS.md、.specs/ARCHITECTURE.md(结构检查,可选)、
15
+ // .specs/health/*.md(基线)、git 历史、可选工具的在场探测(文件 / 路径判定);
15
16
  // · 写:仅一份报告 .specs/health/<日期>-HEALTH.md;`--stdout` 时把报告正文原样打到标准输出;
16
17
  // · 标准输出另**恒**输出 `HEALTH:` 审计行(报告路径 / 日期 / 增补层在场 / 基线)——不带
17
18
  // `--stdout` 时只有审计行(报告正文不回流);
@@ -38,7 +39,7 @@ import os from 'os';
38
39
  import path from 'path';
39
40
  import { fileURLToPath } from 'url';
40
41
  import { validateContext } from './context-init.mjs';
41
- import { parseSideCommandArgs, relativeLabel } from './evolve.mjs';
42
+ import { collectArchitectureStructure, parseSideCommandArgs, relativeLabel } from './evolve.mjs';
42
43
  import { archiveDateFromName, formatLocalDate, formatLocalTimestamp } from './time-utils.mjs';
43
44
 
44
45
  const SELF_FILE = fileURLToPath(import.meta.url);
@@ -468,6 +469,26 @@ function renderGitSection(push, git) {
468
469
  push('');
469
470
  }
470
471
 
472
+ // 确定性层 6:架构文档结构(C19 / AC-20③)——只读报告,不阻断:结构问题不影响退出码,也不写状态。
473
+ // 判据实现与 evolve 的「结构问题」段**同源**(evolve.mjs 的 collectArchitectureStructure):两处各写
474
+ // 一套段形比对必然分叉(同一判据两份实现的老账)。
475
+ function renderArchitectureSection(push, architecture, selfDisplay, options) {
476
+ push('### 6 · 架构文档结构(' + architecture.display + ' · 只读)', '');
477
+ push('- 文件:`' + architecture.display + '`(' + (architecture.exists ? '在场' : '缺失') + ')');
478
+ if (!architecture.exists) {
479
+ push('- 检查:跳过——' + architecture.note);
480
+ } else if (!architecture.checked) {
481
+ push('- 检查:未校验(' + architecture.note + ')');
482
+ } else {
483
+ push('- 结构问题(' + architecture.problems.length + '):' + (architecture.problems.length === 0 ? '无' : ''));
484
+ for (const problem of architecture.problems) push(' - ' + problem);
485
+ }
486
+ push('- 判据:' + (architecture.basis
487
+ ?? '8 个 H2 段 + §3 的 `### ADR-<数字>` 条目字段键(骨架来自 flow-kit/templates/ARCHITECTURE.md)')
488
+ + ';只读报告,不阻断、不写状态');
489
+ push('- 复现命令:`node ' + selfDisplay + ' --root ' + options.rootDisplay + ' --stdout`', '');
490
+ }
491
+
471
492
  function renderSupplementSection(push, brooks) {
472
493
  push('## 增补层(代码体检工具的 4 维结果 · 可选)', '');
473
494
  push('- **在场判定**:' + (brooks.present ? '在场' : '不在场——下列探测面逐项未命中(未安装 / 未加载)'));
@@ -555,6 +576,7 @@ function renderReport(input) {
555
576
  renderDebtSection(push, input.debt);
556
577
  renderRedundancySection(push, input.redundancy, input.options, input.selfDisplay);
557
578
  renderGitSection(push, input.git);
579
+ renderArchitectureSection(push, input.architecture, input.selfDisplay, input.options);
558
580
  renderSupplementSection(push, input.brooks);
559
581
  renderDegradationSection(push, input.redundancy, input.brooks);
560
582
  renderSnapshotSection(push, input.snapshot);
@@ -627,6 +649,7 @@ async function main(argv) {
627
649
  const context = await collectContext(options.root);
628
650
  const lessons = collectLessons(lessonsText);
629
651
  const debt = collectDebt(contextText);
652
+ const architecture = await collectArchitectureStructure(options.root);
630
653
  const redundancy = await collectRedundancy(options.root);
631
654
  const git = collectGit(options.root);
632
655
  const brooks = await collectBrooks(options.root);
@@ -642,6 +665,7 @@ async function main(argv) {
642
665
  context,
643
666
  lessons,
644
667
  debt,
668
+ architecture,
645
669
  redundancy,
646
670
  git,
647
671
  brooks,