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
@@ -11,6 +11,10 @@ import { inspectWorkflowProtectedPath } from '../protocol-utils.mjs';
11
11
  import { taskOpeningAttrs } from '../task-parsing.mjs';
12
12
  import { resolveNextNode, normalizeHeading, FIX_SECTION_TITLE_FALLBACK } from '../route-node.mjs';
13
13
  import { runRoot, fileExists, workflowRelativeSegments } from './guard-state-io.mjs';
14
+ import { SUMMARY_REQUIRED_SECTIONS, buildSkeleton } from './guard-artifact-skeleton.mjs';
15
+ // 归档目录名「是不是本 change 的」判据单源在状态族的路径上下文模块(guard → state-* 是允许的
16
+ // 单向边):本模块只消费,不在这里另写一份后缀/日期匹配。
17
+ import { isArchivedChangeDirName } from './state-io.mjs';
14
18
 
15
19
  // 新旧 change 区分——init 写入的 newChange: true = 新 change(严格,不依赖 entry——防系统性
16
20
  // 跳 entry 绕过);缺失/非 true(旧 change)= 渐进 WARN 兼容。
@@ -18,12 +22,8 @@ export function isNewChange(state) {
18
22
  return state.newChange === true;
19
23
  }
20
24
 
21
- // flow-kit SUMMARY 模板必填段(正则匹配,大小写不敏感 + 变体兼容)
22
- export const SUMMARY_REQUIRED_SECTIONS = [
23
- { regex: /##\s*verify\s*输出/i, label: '## verify 输出' },
24
- { regex: /##\s*6\s*维自查/i, label: '## 6 维自查' },
25
- { regex: /##\s*(越界检查|边界检查)/i, label: '## 越界检查' },
26
- ];
25
+ // flow-kit SUMMARY 模板必填段(正则匹配,大小写不敏感 + 变体兼容)——清单唯一来源是骨架模块,
26
+ // 此处只取用(本模块不再自持第二份段名清单)。
27
27
 
28
28
  // 校验 change 目录下每份 *-SUMMARY.md 含 SUMMARY 模板的三个必填段。用正则(大小写不敏感 +
29
29
  // 变体兼容)——避免现有 SUMMARY 格式漂移导致误 BLOCKED。
@@ -250,121 +250,152 @@ export async function workflowArtifactRoot(pathBase) {
250
250
  throw new Error('产物根 pathBase "' + pathBase + '" 不再支持——请改用 specs-root/project + 完整路径(如 project + openspec/changes/xxx.md)');
251
251
  }
252
252
 
253
- export async function missingRequiredArtifacts(protocol, node, change) {
253
+ // 声明工件的存在性判据——**唯一的枚举处**:本节点 outputSchemas 引用的 schema → artifacts 中
254
+ // required 的那些,逐条解析路径并判定在场。出口的产物门禁(missingRequiredArtifacts)与结构预检
255
+ // (guard-gates 的缺件报告)都只消费本函数;任何一处再自行遍历 outputSchemas 就是第二份实现,
256
+ // 判据演进时必然分叉(重构前就已分叉:预检只判 file 类、未声明 paths 直接跳过,出口侧两项都不是)。
257
+ //
258
+ // 返回结构数组(每条 = 一份声明的必需产物):
259
+ // { schemaId, artifact, resolvedPaths, present, kind, unspecifiedPaths }
260
+ // resolvedPaths —— 已替换 <change-id> 的声明路径;同一 artifact 的 paths 是互斥备选(任一路径
261
+ // 在场即在场,与节点完成判定同语义);
262
+ // present —— 在场判定结果(pathPatternExists 任一命中);
263
+ // kind —— 声明的产物类别(未声明为 undefined);
264
+ // unspecifiedPaths —— 声明不完整(required 但未声明 paths):没有路径可查,present 恒为 false。
265
+ //
266
+ // 两侧的差异不抹平、也不在这里偷偷归一,而是留给**调用点显式**决定(调用点各写一行并注明理由):
267
+ // ① kind:预检只判 kind 为 file(未声明按文件处置)的产物——其它 kind 的「在场」语义不是文件
268
+ // 存在性;出口不判 kind(目录类产物同样按路径存在性校验)。
269
+ // ② 未声明 paths:报成**声明不完整**而不是「缺件」的普通一例——没有路径就没有可判的存在性,也没有
270
+ // 可创建的落点,报文必须指向协议本身要修,而不是让人去做一件做不到的事。两侧都阻断、且渲染
271
+ // **同一句**(unspecifiedPathsNotice);区别只在编排:出口把它列进缺件清单,预检给它单列一段
272
+ // (不给「按上述路径创建」的指令)。
273
+ // ③ 归档产出(.specs/archive/ 下):只在预检侧延后报告,出口照常校验——那是归档做完后的判据。
274
+ // 本函数只做 ①②③ 都不涉及的那部分:枚举 + <change-id> 替换 + 在场判定。
275
+
276
+ // 「声明不完整」的同一句报文:两侧消费方都渲染这一句,措辞只此一处(不各写一份)。
277
+ export function unspecifiedPathsNotice(schemaId, artifactId) {
278
+ return '协议声明不完整:' + schemaId + '.' + artifactId
279
+ + ' 标记为 required 但未声明 paths —— 修协议(给它加一条路径),或在模板里改 required=false';
280
+ }
281
+
282
+ export async function declaredRequiredArtifacts(protocol, node, change) {
254
283
  const schemas = schemaMap(protocol);
255
- const missing = [];
284
+ const declared = [];
256
285
  for (const schemaId of node.outputSchemas ?? []) {
257
286
  const schema = schemas.get(schemaId);
258
287
  for (const artifact of schema?.artifacts ?? []) {
259
288
  if (!artifact.required) continue;
260
- const exists = (
261
- await Promise.all(
262
- (artifact.paths ?? []).map(async (artifactPath) => {
263
- // 替换 <change-id> 占位符为实际 change(如 name-format-unify)
264
- const resolvedPath = change ? artifactPath.replaceAll('<change-id>', change) : artifactPath;
265
- return pathPatternExists(await workflowArtifactRoot(artifact.pathBase), resolvedPath);
266
- }),
267
- )
268
- ).some(Boolean);
269
- if (!exists) missing.push(schemaId + '.' + artifact.id);
289
+ const declaredPaths = artifact.paths ?? [];
290
+ const unspecifiedPaths = declaredPaths.length === 0;
291
+ // <change-id> 替换:无活跃 change 时保留占位符原文(出口侧既有语义;预检侧在无 change 时更早
292
+ // 已退出,两侧因此共用这一条替换口径,不再各自写一份 replaceAll)。
293
+ const resolvedPaths = declaredPaths.map((declaredPath) => (change
294
+ ? String(declaredPath).replaceAll('<change-id>', change)
295
+ : String(declaredPath)));
296
+ // 未声明路径时不解析产物根:没有路径就没有可查的存在性,「pathBase 非法」也不该由一件无路径的
297
+ // 产物引爆。present 保持 false——声明不完整不是「在场」,两侧据此阻断(差异②)。
298
+ let present = false;
299
+ if (!unspecifiedPaths) {
300
+ const artifactRoot = await workflowArtifactRoot(artifact.pathBase);
301
+ present = (await Promise.all(
302
+ resolvedPaths.map((declaredPath) => pathPatternExists(artifactRoot, declaredPath)),
303
+ )).some(Boolean);
304
+ }
305
+ declared.push({ schemaId, artifact, resolvedPaths, present, kind: artifact.kind, unspecifiedPaths });
270
306
  }
271
307
  }
272
- return missing;
308
+ return declared;
309
+ }
310
+
311
+ // 出口侧的必需产物缺件清单(产物门禁与漂移容错的容错判据共用):取 declaredRequiredArtifacts 里
312
+ // 不在场者。本侧**不做**预检的 kind 过滤(①,见上式注释)——出口是完成判据:声明了却不在场就是
313
+ // 缺件,无论 kind 是不是 file。声明不完整者(②)同样进这份清单、同样阻断,但报的是可执行的那一句
314
+ // (指向协议),而不是一个空路径——与预检侧同一句、同一处措辞。
315
+ export async function missingRequiredArtifacts(protocol, node, change) {
316
+ return (await declaredRequiredArtifacts(protocol, node, change))
317
+ .filter((declared) => !declared.present)
318
+ .map((declared) => (declared.unspecifiedPaths
319
+ ? unspecifiedPathsNotice(declared.schemaId, declared.artifact.id)
320
+ : declared.schemaId + '.' + declared.artifact.id));
273
321
  }
274
322
 
275
- // 历史归档 change 不强制真实跑验证命令(判断 .specs/archive/ 目录)
323
+ // 历史归档 change 不强制真实跑验证命令(判断 .specs/archive/ 目录)。归档目录名按
324
+ // <日期>-<change-id> 精确形态比对(判据单源在 state-io):后缀匹配会把「名字恰好以本 change id
325
+ // 结尾」的别的 change 认作本 change 已归档,守卫于是**跳过真实跑验证命令的要求**——这是放行口,
326
+ // 不是显示问题。无日期前缀、名字逐字等于 change-id 的旧布局仍认(两处精确比对,都不做后缀)。
276
327
  export async function isArchivedChange(changeName) {
277
328
  if (!changeName) return false;
278
329
  const archiveRoot = path.join(runRoot, '.specs', 'archive');
279
330
  if (await fileExists(path.join(archiveRoot, changeName))) return true;
280
331
  const entries = await fs.readdir(archiveRoot).catch(() => []);
281
- return entries.some(e => e === changeName || e.endsWith('-' + changeName));
282
- }
283
-
284
- // 声明标记目录解析——活动路径 .specs/<change-id>/.skill-loads/ 优先;归档路径兜底(archive 节点
285
- // 「先移目录后 record/exit」顺序下 change 目录已在 .specs/archive/<前缀>-<change-id>/,标记只随
286
- // 目录移动——只查活动路径会把「标记存在」误判成「机制未激活」)。归档扫描匹配后缀 -<change-id>
287
- // (前缀可含日期等,与协议 flowkit.archive.v1 的 archive/*-<change-id> 同构)。两者皆无 → null
288
- // (声明机制从未激活,调用方按旧 change 兼容跳过)。
289
- export async function findSkillLoadsDir(root, changeName) {
290
- const activeDir = path.join(root, '.specs', changeName, '.skill-loads');
291
- if (await fileExists(activeDir)) {
292
- return { dir: activeDir, display: '.specs/' + changeName + '/.skill-loads/' };
293
- }
294
- const archiveRoot = path.join(root, '.specs', 'archive');
295
- const entries = await fs.readdir(archiveRoot).catch(() => []);
332
+ return entries.some((entry) => entry === changeName || isArchivedChangeDirName(entry, changeName));
333
+ }
334
+
335
+ // 段名校验基准从模板自动派生——骨架计算统一委托 lib/guard-artifact-skeleton.mjs(单一实现:读
336
+ // <runRoot>/flow-kit/templates/<DOC>.md + reference/artifact-templates.json,按 runRoot 缓存;段名
337
+ // 归一复用 route-node 的 normalizeHeading)。本模块只把骨架投影成既有消费方要的 { name, regex } 形态
338
+ // ——不自持模板读取,也不另写一份段名派生。模板整份缺失 → 该键的空数组(pick 据此跳过,见下)。
339
+ //
340
+ // 「模板缺席时的段名回退清单」唯一来源同样在骨架模块(段名清单单一来源):此处只转出既有导出面,不另存字面
341
+ // 清单——消费方(含 lib/guard-uidesign.mjs)的取用路径因此不变。
342
+ export { TEMPLATE_FALLBACK_SECTION_PATTERNS } from './guard-artifact-skeleton.mjs';
343
+
344
+ // 模板段名 → 宽松匹配正则:实现随段名归一移到骨架模块(单一出处),此处转出保持既有导出面。
345
+ export { headingPattern as templateSectionPattern } from './guard-artifact-skeleton.mjs';
346
+
347
+ // 命名段选取(唯一实现):候选集为空(模板整份缺席 / 该类段无从派生)⇒ TEMPLATE_SECTION_SKIP;
348
+ // 否则按关键词取首个命中的**模板段名**所派生的正则,关键词全不命中 ⇒ 调用方给的 fallback。
349
+ // H2 顶层段(pick)与登记表列举的结构子段(pickTemplateSection 的 level 3)共用这一条规则——
350
+ // 候选集来源不同,选段语义必须由同一个函数给出:同一份工件的同一段在两处被选出不同判据,就是
351
+ // 第二份实现(两个入口在同一候选集上给出同一判据,由套件场景逐态对账)。
352
+ function pickByKeywords(entries, keywords, fallback) {
353
+ if (entries.length === 0) return TEMPLATE_SECTION_SKIP;
296
354
  for (const entry of entries) {
297
- if (!entry.endsWith('-' + changeName)) continue;
298
- const candidate = path.join(archiveRoot, entry, '.skill-loads');
299
- if (await fileExists(candidate)) {
300
- return { dir: candidate, display: '.specs/archive/' + entry + '/.skill-loads/' };
301
- }
355
+ if (keywords.some((keyword) => entry.name.includes(keyword))) return entry.regex;
302
356
  }
303
- return null;
304
- }
305
-
306
- // 段名校验从模板自动派生——读 <runRoot>/flow-kit/templates/{CHANGE,REQUIREMENT,DESIGN,SUMMARY}.md
307
- // 提取全部 ^## 段名,正则化生成宽松匹配模式;模板目录/文件缺失时 fallback 内置段名。
308
- export const TEMPLATE_FALLBACK_SECTION_PATTERNS = {
309
- changeWhy: /^##\s*Why\b/im,
310
- changeVisualTone: /^##\s*视觉调性/im,
311
- requirementUserStory: /^##\s*用户故事/im,
312
- requirementAcceptance: /##\s*(验收准则|验收标准|AC|Acceptance Criteria)/i,
313
- designDecisionList: /^##\s*\d*\.?\s*决策清单/m,
314
- };
315
-
316
- let templateSectionPatternsCacheRoot = null;
317
- let templateSectionPatternsCache = null;
318
-
319
- // 模板段名 → 宽松匹配正则:编号前缀(1. / 0.5)可选 + 段名主体字面匹配 + 尾部括号内容(如 (AC))可选
320
- export function templateSectionPattern(rawName) {
321
- const name = String(rawName).trim();
322
- const body = name
323
- .replace(/[((][^))\n]*[))]\s*$/u, '') // 去尾部括号内容:Why(为什么做)→ Why
324
- .replace(/^\d+(?:\.\d+)?\.?\s*/u, '') // 去编号前缀:1. 决策清单 → 决策清单
325
- .trim();
326
- const escaped = escapeRegExp(body || name);
327
- return new RegExp(
328
- '^##\\s*(?:\\d+(?:\\.\\d+)?\\.?\\s*)?' + escaped + '\\s*(?:[((][^\\n))]*[))])?\\s*$',
329
- 'im',
330
- );
357
+ return fallback;
331
358
  }
332
359
 
333
- // 读取模板全部段名生成模式列表(模块级缓存,避免每次 exit 重复读文件);pick 按关键词选段,找不到 → fallback
334
- export async function templateSectionPatterns() {
335
- if (templateSectionPatternsCacheRoot === runRoot && templateSectionPatternsCache) {
336
- return templateSectionPatternsCache;
337
- }
338
- const templateDir = path.join(runRoot, 'flow-kit', 'templates');
360
+ // 任意模板键 + 层级的选段入口:pick 只覆盖 change / requirement / design / summary 四个 H2 键,
361
+ // 而判据落在别的模板(TEST 的「第 1 轮」段与 1.1 测试矩阵一类)上时同样需要一个「段名从模板派生、
362
+ // 模板缺席即跳过、关键词不命中即回退」的口子——否则消费方只能自己遍历段名表,那是第二份选段实现。
363
+ // level 2 = 模板 H2 顶层段(骨架 sections) level 3 = 登记表列举的结构子段(structureSubsections)
364
+ // 返回正则或 TEMPLATE_SECTION_SKIP(调用方据此打印「未校验」而不是猜测段名)。opts.runRoot 与骨架
365
+ // 同一出入口(场景 / 临时夹具可指向别的项目根)。
366
+ export async function pickTemplateSection(key, { keywords = [], fallback, level = 2, runRoot } = {}) {
367
+ const skeleton = await buildSkeleton(key, runRoot === undefined ? {} : { runRoot });
368
+ const entries = (level === 3 ? skeleton.structureSubsections ?? [] : skeleton.sections)
369
+ .map((entry) => ({ name: entry.name, regex: entry.pattern }));
370
+ return pickByKeywords(entries, keywords, fallback);
371
+ }
372
+
373
+ // 读取模板全部段名生成模式列表:键形(change / requirement / design / summary)与 tpl[key] 的
374
+ // { name, regex } 数组形态、pick 的按关键词选段语义一律保持既有——只把数据源换成骨架模块(缓存与
375
+ // 模板读取归它一处负责,本模块不再自持 runRoot 键控的第二份缓存)。opts.runRoot 与骨架同一出入口
376
+ // (缺省用运行上下文根;场景可指向夹具根)。
377
+ export async function templateSectionPatterns(opts = {}) {
339
378
  const result = { change: [], requirement: [], design: [], summary: [] };
340
- for (const [key, fileName] of Object.entries({
341
- change: 'CHANGE.md',
342
- requirement: 'REQUIREMENT.md',
343
- design: 'DESIGN.md',
344
- summary: 'SUMMARY.md',
345
- })) {
346
- const templateFile = path.join(templateDir, fileName);
347
- if (await fileExists(templateFile)) {
348
- try {
349
- const text = await fs.readFile(templateFile, 'utf8');
350
- for (const match of text.matchAll(/^##\s+(.+)$/gmu)) {
351
- const sectionName = match[1].trim();
352
- result[key].push({ name: sectionName, regex: templateSectionPattern(sectionName) });
353
- }
354
- } catch {}
355
- }
379
+ for (const key of Object.keys(result)) {
380
+ const skeleton = await buildSkeleton(key, opts);
381
+ result[key] = skeleton.sections.map((section) => ({ name: section.name, regex: section.pattern }));
356
382
  }
357
- result.pick = (key, keywords, fallback) => {
358
- for (const section of result[key] ?? []) {
359
- if (keywords.some((keyword) => section.name.includes(keyword))) return section.regex;
360
- }
361
- return fallback;
362
- };
363
- templateSectionPatternsCache = result;
364
- templateSectionPatternsCacheRoot = runRoot;
383
+ // 命名段选取:模板整份缺席(sections 为空)⇒ **跳过**,不回落段名兜底正则(C9:模板整份缺失时
384
+ // 模板派生判据全部跳过,fallback 只在「模板在场但某个具体段名缺失」时生效)。既有消费方里有闭包
385
+ // 外直接 `.test` 的调用点(「视觉调性」段读取),返回 null 会把「跳过」退化成 TypeError 崩溃——
386
+ // 未校验变成失败,同样不是 C9 的「跳过」,故返回可判别的跳过判据(见 TEMPLATE_SECTION_SKIP)。
387
+ result.pick = (key, keywords, fallback) => pickByKeywords(result[key] ?? [], keywords, fallback);
365
388
  return result;
366
389
  }
367
390
 
391
+ // 「跳过」判据的唯一形态:`.test` 恒真(消费方形态即 `pattern.test(text)` ⇒ 该段检查不生效),
392
+ // `skip` 标记让调用方与场景能区分「跳过」与「判据通过」。整份模板缺席时的跳过可见性由产出物结构
393
+ // 门禁的「未校验(模板缺失)」行承担,pick 不再重复打印(同一事实两处措辞会先漂移)。
394
+ export const TEMPLATE_SECTION_SKIP = Object.freeze({
395
+ skip: true,
396
+ test: () => true,
397
+ });
398
+
368
399
  // Fix 段标题从 <runRoot>/flow-kit/templates/TASK.md 派生(单一模板源 + 模块级缓存 + runRoot 键控):
369
400
  // 扫描模板全部 H2,用 route-node 共享 heading 归一(单一权威,含闭合 ATX)识别 Fix 段标题;无匹配
370
401
  // (模板缺失 / 读取失败 / 无 Fix 段)返回 undefined,由回程分类器的内置 fallback 常量兜底。标题只
@@ -1,7 +1,8 @@
1
- // 运行上下文 + 受保护状态 I/O(守卫模块)。
1
+ // 受保护状态 I/O(守卫模块)+ 守卫侧运行上下文。
2
2
  //
3
- // 运行上下文(runRoot / packageRoot / 协议路径绑定)是本模块的**单一来源**:各守卫模块不再各自
4
- // 从环境变量推导同一事实——两份推导会在形态变化时静默分叉。
3
+ // 运行根(runRoot)的解析由 lib/run-root.mjs 单源提供:状态命令族与守卫族共用同一份事实,本模块
4
+ // 只取用并再导出(守卫入口的导入面因此不变)。packageRoot 与协议路径绑定仍在这里——各守卫模块
5
+ // 不再各自从环境变量推导同一事实,两份推导会在形态变化时静默分叉。
5
6
  //
6
7
  // 受保护读写通道(路径段判据 → 逐段目录校验 → 快照复核 → 唯一临时名原子落盘)在写入前与落盘前
7
8
  // 都复核目标未被替换;任何一步不符即抛错(fail-closed),绝不退化为尽力而为的写。
@@ -12,6 +13,7 @@ import { constants as fsConstants, promises as fs } from 'fs';
12
13
  import path from 'path';
13
14
  import { fileURLToPath } from 'url';
14
15
  import { RUNTIME_STATE_PATH, LEGACY_RUNTIME_STATE_PATH } from '../state-schema.mjs';
16
+ import { resolveRunRoot } from './run-root.mjs';
15
17
  import {
16
18
  inspectWorkflowProtectedPath,
17
19
  readWorkflowProtectedFile,
@@ -24,9 +26,9 @@ import {
24
26
  const scriptsRoot = path.dirname(fileURLToPath(import.meta.url));
25
27
  // 技能包根:scripts/lib → scripts → skills/flow-comet(协议默认路径与包内资源以此为基准)
26
28
  export const packageRoot = path.resolve(scriptsRoot, '..', '..');
27
- export const runRoot = process.env.FLOW_COMET_RUN_ROOT
28
- ? path.resolve(process.env.FLOW_COMET_RUN_ROOT)
29
- : process.cwd();
29
+ // 运行根:唯一解析在 lib/run-root.mjs(与状态命令族同一份事实)——本模块只取用并再导出。
30
+ // 行内再写一次 env/cwd 推导,就是本次要消灭的那份分叉(守卫认变量、状态命令认 cwd)。
31
+ export const runRoot = resolveRunRoot();
30
32
 
31
33
  // 协议路径解析:显式 --protocol 全局参数(command=argv[2] 之后的剩余参数)> state.protocolPath
32
34
  // (init 持久化绑定)> FLOW_COMET_PROTOCOL 环境变量 > 内置默认。选择在入口 main() 内执行