flow-comet 1.6.1 → 1.6.2

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.
@@ -0,0 +1,133 @@
1
+ // time-utils.mjs: 时间形态 / 解析 / 到期阈值的单一权威(单源纪律 · L-067)
2
+ //
3
+ // 为什么单独成域:时间戳曾散落各脚本以 `new Date().toISOString()` 生成、以字符串拼接消费——
4
+ // 同一事实的多个表达在时区面必然分叉(L-096:`date` 读数在 UTC 与 +0800 间抖动,目测判时得出过
5
+ // 相反结论)。本模块是「生成 / 解析 / 阈值比较 / 归档窗口判定」的唯一实现:
6
+ // · 生成:本地时间 + 显式偏移 `YYYY-MM-DDTHH:mm:ss±HH:mm`(人读为本地时间、机器可无损解析)
7
+ // · 解析:`Date.parse` + 分量回环校验(兼容历史 `Z` 形态;`2026-02-30` 一类不可自洽形态拒绝)
8
+ // · 阈值:天差比较 + evolve 到期窗口(> 60 天,或该时刻之后新增 ≥ 5 个带 §9 的归档 change)
9
+ // 消费方(workflow-state 的 config set / status;evolve 的扫描范围与元数据写入)一律 import 本模块——
10
+ // 在其它脚本内联第二份格式化 / 解析表达式即违反单源纪律(守卫按表达式形态扫描,注释互指同源不作数)。
11
+ //
12
+ // 边界:本模块只管「时间与到期判据」,不做 I/O(不读 state、不扫目录);调用方负责取字段与遍历文件。
13
+
14
+ // 时间戳形态:秒级为最小精度,毫秒可选;时区必须是显式 `Z` 或 `±HH:mm`(`+0800` / 裸本地时间 /
15
+ // 纯日期一律非法——纯日期无法表达「时刻」,进 state 会让天差判定退化为猜测)。
16
+ const TIMESTAMP_SHAPE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(Z|([+-])(\d{2}):(\d{2}))$/;
17
+ // 归档目录名日期前缀(flow-kit 7-integration 约定:archive/<YYYY-MM-DD>-<change-id>)
18
+ const ARCHIVE_DATE_PREFIX = /^(\d{4}-\d{2}-\d{2})(?:-|$)/;
19
+ // 一天的毫秒数(天差换算与阈值比较的唯一常量,不在调用点重写这个字面量)
20
+ const MS_PER_DAY = 24 * 60 * 60 * 1000;
21
+
22
+ function pad2(value) {
23
+ return String(value).padStart(2, '0');
24
+ }
25
+
26
+ function toDate(value) {
27
+ if (value instanceof Date) return value;
28
+ if (typeof value === 'number' && Number.isFinite(value)) return new Date(value);
29
+ return new Date(NaN);
30
+ }
31
+
32
+ // 本地时间 + 显式偏移(人读为本地时间、机器可无损解析)。传入 Date 或 epoch 毫秒;非法时间一律抛出
33
+ // (fail-closed:不生成可疑时间戳)。
34
+ export function formatLocalTimestamp(value = new Date()) {
35
+ const date = toDate(value);
36
+ if (Number.isNaN(date.getTime())) throw new Error('formatLocalTimestamp: 非法时间值');
37
+ const offsetMinutes = -date.getTimezoneOffset();
38
+ const sign = offsetMinutes < 0 ? '-' : '+';
39
+ const abs = Math.abs(offsetMinutes);
40
+ return date.getFullYear() + '-' + pad2(date.getMonth() + 1) + '-' + pad2(date.getDate())
41
+ + 'T' + pad2(date.getHours()) + ':' + pad2(date.getMinutes()) + ':' + pad2(date.getSeconds())
42
+ + sign + pad2(Math.floor(abs / 60)) + ':' + pad2(abs % 60);
43
+ }
44
+
45
+ // 本地日期 `YYYY-MM-DD`(工件名 `<日期>-<KIND>.md` 与日期粒度比较用)。
46
+ export function formatLocalDate(value = new Date()) {
47
+ const date = toDate(value);
48
+ if (Number.isNaN(date.getTime())) throw new Error('formatLocalDate: 非法时间值');
49
+ return date.getFullYear() + '-' + pad2(date.getMonth() + 1) + '-' + pad2(date.getDate());
50
+ }
51
+
52
+ // 当前时刻的标准形态(新写入路径统一走本函数,不自行拼接)。
53
+ export function nowTimestamp() {
54
+ return formatLocalTimestamp(new Date());
55
+ }
56
+
57
+ // 解析为标准形态或历史 `Z` 形态 → epoch 毫秒;非法(含形态不符、日历不可自洽)→ NaN,不抛。
58
+ // 分量回环校验是判别力所在:V8 对 `2026-02-30T00:00:00Z` 会静默滚到 3 月 2 日——只查 Date.parse
59
+ // 是否 NaN 会把它当合法值写进 state,到期判定随之失真。
60
+ export function parseTimestamp(value) {
61
+ if (typeof value !== 'string') return NaN;
62
+ const text = value.trim();
63
+ const parts = TIMESTAMP_SHAPE.exec(text);
64
+ if (!parts) return NaN;
65
+ const ms = Date.parse(text);
66
+ if (Number.isNaN(ms)) return NaN;
67
+ const [, year, month, day, hour, minute, second, fraction, zone, sign, offsetHour, offsetMinute] = parts;
68
+ let offsetMinutes = 0;
69
+ if (zone !== 'Z') {
70
+ if (Number(offsetHour) > 23 || Number(offsetMinute) > 59) return NaN;
71
+ offsetMinutes = (Number(offsetHour) * 60 + Number(offsetMinute)) * (sign === '-' ? -1 : 1);
72
+ }
73
+ const millis = fraction ? Number((fraction + '00').slice(0, 3)) : 0; // `.5` / `.50` / `.500` → 500ms
74
+ // 回环:把 epoch 还原成「书写时区」的墙钟分量,逐项与字面量比对(不一致 = 日历滚动过,如 2026-02-30)
75
+ const wallClock = new Date(ms + offsetMinutes * 60000);
76
+ const written = [Number(year), Number(month) - 1, Number(day), Number(hour), Number(minute), Number(second), millis];
77
+ const restored = [wallClock.getUTCFullYear(), wallClock.getUTCMonth(), wallClock.getUTCDate(),
78
+ wallClock.getUTCHours(), wallClock.getUTCMinutes(), wallClock.getUTCSeconds(), wallClock.getUTCMilliseconds()];
79
+ return written.every((value, index) => value === restored[index]) ? ms : NaN;
80
+ }
81
+
82
+ // 形态与日历均合法 → true。state 字段校验与 config set 写通道共用本判定(fail-closed 单一来源)。
83
+ export function isValidTimestamp(value) {
84
+ return !Number.isNaN(parseTimestamp(value));
85
+ }
86
+
87
+ // 距该时刻已过多少天(小数)。reference 缺省 = 现在(epoch 毫秒或可解析时间戳)。
88
+ // 非法输入 → NaN(调用方按「不可判」处理,不得据此判到期)。
89
+ export function daysSince(timestamp, reference = Date.now()) {
90
+ const at = parseTimestamp(timestamp);
91
+ if (Number.isNaN(at)) return NaN;
92
+ const ref = reference instanceof Date ? reference.getTime() : reference;
93
+ const referenceMs = typeof ref === 'number' && Number.isFinite(ref) ? ref : parseTimestamp(ref);
94
+ if (Number.isNaN(referenceMs)) return NaN;
95
+ return (referenceMs - at) / MS_PER_DAY;
96
+ }
97
+
98
+ // 归档目录名 → 归档日期 `YYYY-MM-DD`;非约定命名或日期不可自洽 → null。
99
+ // 取目录名而非 mtime:目录名随提交固化(跨 clone / checkout 稳定),mtime 会被检出重写——
100
+ // 用 mtime 判「归档于何时」在全新检出上会把整仓历史当成新增(L-096 的「mtime 判时」用于
101
+ // 判活场景,归档窗口判据需要的是**随工件固化的时刻标签**)。
102
+ export function archiveDateFromName(dirName) {
103
+ if (typeof dirName !== 'string') return null;
104
+ const parts = ARCHIVE_DATE_PREFIX.exec(dirName.trim());
105
+ if (!parts) return null;
106
+ return isValidTimestamp(parts[1] + 'T00:00:00Z') ? parts[1] : null;
107
+ }
108
+
109
+ // 「该归档 change 在该时刻之后归档」判定:日期粒度、严格在其后(与 flow-kit A-evolve
110
+ // 「只扫该日期之后归档的 change」同源)。任一输入不可判 → false(不放行 → 不误报新)。
111
+ export function isArchivedAfterTimestamp(dirName, timestamp) {
112
+ const archiveDate = archiveDateFromName(dirName);
113
+ const at = parseTimestamp(timestamp);
114
+ if (archiveDate === null || Number.isNaN(at)) return false;
115
+ return archiveDate > formatLocalDate(new Date(at));
116
+ }
117
+
118
+ // 到期阈值(与 flow-kit A-evolve / 7-integration 的「约 60 天后,或新增 ≥ 5 个有 §9 内容的
119
+ // change 之后」同值)。两个常量是 status 到期提示与 evolve 技能文本的共同来源。
120
+ export const EVOLVE_STALE_DAYS = 60;
121
+ export const EVOLVE_DUE_NEW_ARCHIVE_CHANGES = 5;
122
+
123
+ // ---------- 到期窗口的输入面:§9 沉淀段在场判定 ----------
124
+ // 为什么在「时间」模块里:AC-18 的到期判据 = 时间阈值 + 窗口内「带 §9 的归档 change」计数——两者
125
+ // 同为**到期窗口判据**的组成部分。若 §9 在场判定在 status 提示与 evolve 扫描各写一份,两个消费面
126
+ // 会各自漂移(L-067:注释互指同源不是同步机制),故由本模块唯一表达,消费方 import。
127
+ // 上游锚 = flow-kit 7-integration 的 `grep -c '^### 9\.' DESIGN.md`;本仓归档 DESIGN.md 用
128
+ // `## 9.` 形态,故层级放宽到 2~4 并容忍 `§9` 写法。只作「有无」判定,不解析条目内容。
129
+ const SECTION9_HEADING = /^#{2,4}\s*§?\s*9\s*[.、·]/m;
130
+
131
+ export function hasSection9(text) {
132
+ return typeof text === 'string' && SECTION9_HEADING.test(text);
133
+ }
@@ -805,6 +805,7 @@ let templateSectionPatternsCache = null;
805
805
 
806
806
  const TEMPLATE_FALLBACK_SECTION_PATTERNS = {
807
807
  changeWhy: /^##\s*Why\b/im,
808
+ changeVisualTone: /^##\s*视觉调性/im,
808
809
  requirementUserStory: /^##\s*用户故事/im,
809
810
  requirementAcceptance: /##\s*(验收准则|验收标准|AC|Acceptance Criteria)/i,
810
811
  designDecisionList: /^##\s*\d*\.?\s*决策清单/m,
@@ -859,6 +860,131 @@ async function templateSectionPatterns() {
859
860
  return result;
860
861
  }
861
862
 
863
+ // ===== ui-design 适用性门控(前端判据 · 结构级,不做语义)=====
864
+ // 协议 design 节点的 ui-design 绑定为 guarded,但它「仅前端」适用 ⇒ 出口自动补 required-skill
865
+ // 声明对该绑定失效(须真实 skill-load 声明),判据不成立(非前端)时按 advisory 处理并在出口
866
+ // 输出可见跳过行(不留假绿:跳过是显式记录,非静默省略)。
867
+ // 键控(enforcement 是这道门的单一表达处):门只在「协议登记了该绑定 ∧ enforcement === 'guarded'」
868
+ // 时存在——协议副本删掉绑定或把等级调回 advisory ⇒ 门不适用(留可见「门未启用」行,不静默消失),
869
+ // 相应路径逐字回到未登记绑定的原语义。门禁侧不持有第二份键表:登记表 APPLICABILITY_GATED_BINDINGS
870
+ // 按 `<nodeId>.<skill>` 键控,工件门与出口自动补写共用下方 applicabilityGatedBinding 查询。
871
+ // 判据必须结构性可判:CHANGE.md 的「视觉调性」段在场且段内不含**结构形态**的「不适用」标记 ⇒
872
+ // 前端;段缺席 / 段内以结构形态标注 ⇒ 非前端。段名基准从 flow-kit/templates/CHANGE.md 派生
873
+ // (与 C2/M3 同源,模板缺失 → 内置骨架名),不做段名第二实现。
874
+ const UI_DESIGN_SKILL = 'flow-comet-ui-design';
875
+ const APPLICABILITY_GATED_BINDINGS = new Set(['design.' + UI_DESIGN_SKILL]);
876
+ const VISUAL_TONE_NOT_APPLICABLE = '不适用';
877
+
878
+ // 负向标记的结构约束(三种形态,共用同一词形边界)——裸子串会让「不适用于暗色主题」这类自然句子
879
+ // 关掉整道门(fail-open),故标记必须落在结构锚位且成词形边界:
880
+ // 形态 A 独立行:整行(去块引用 / 列表符 / 加粗)就是标记,可带括注理由与尾标点;
881
+ // 形态 B 行首:行以标记开头(如「不适用 —— CLI 工具,无用户可见界面。」);
882
+ // 形态 C 字段值位:`<适用性标签>: 不适用`——标签限本约定的短标签表(适用性 / 前端 / 视觉调性 …),
883
+ // 不通配任意字段名:`- 暗色主题:不适用` 这类「某子维度不适用」的字段不得关掉整道门。
884
+ // 词形边界 = 标记后为行尾 / 空白 / 标点 / 括注引号——「不适用于…」的「于」不是边界。
885
+ const TONE_MARKER_TAIL = String.raw`(?=$|[\s,。;、,;.::!!??…—()()【】「」『』“”"'])`;
886
+ const TONE_MARKER_LEAD = String.raw`^[>\s]*(?:[-*+]\s+)?(?:\*\*)?`;
887
+ const TONE_MARKER_FIELD_LABELS = '适用性|适用范围|是否前端|视觉调性|前端|界面|适用';
888
+ const TONE_MARKER_ALONE_LINE = new RegExp(TONE_MARKER_LEAD + VISUAL_TONE_NOT_APPLICABLE
889
+ + String.raw`(?:\*\*)?(?:\s*[((][^))]*[))])?[。.;;,,]?\s*$`);
890
+ const TONE_MARKER_LINE_HEAD = new RegExp(TONE_MARKER_LEAD + VISUAL_TONE_NOT_APPLICABLE
891
+ + String.raw`(?:\*\*)?` + TONE_MARKER_TAIL);
892
+ const TONE_MARKER_FIELD_VALUE = new RegExp(String.raw`(?:^|[\s|])(?:\*\*)?(?:`
893
+ + TONE_MARKER_FIELD_LABELS + String.raw`)(?:\*\*)?\s*[::]\s*(?:\*\*)?`
894
+ + VISUAL_TONE_NOT_APPLICABLE + String.raw`(?:\*\*)?` + TONE_MARKER_TAIL);
895
+
896
+ // 「视觉调性」段正文(段标题之后、下一个 H2 之前;段缺席 → null)
897
+ async function visualToneSectionBody(changeName) {
898
+ if (!changeName) return null;
899
+ let text;
900
+ try {
901
+ text = await fs.readFile(path.join(runRoot, '.specs', changeName, 'CHANGE.md'), 'utf8');
902
+ } catch {
903
+ return null;
904
+ }
905
+ const headingPattern = (await templateSectionPatterns())
906
+ .pick('change', ['视觉调性'], TEMPLATE_FALLBACK_SECTION_PATTERNS.changeVisualTone);
907
+ let body = null;
908
+ for (const line of String(text).replace(/\uFEFF/g, '').split(/\r?\n/)) {
909
+ if (/^##\s+/.test(line)) {
910
+ if (body !== null) break; // 到达下一个 H2 → 本段结束
911
+ if (headingPattern.test(line)) body = '';
912
+ continue;
913
+ }
914
+ if (body !== null) body += line + '\n';
915
+ }
916
+ return body;
917
+ }
918
+
919
+ // 段内负向标记命中(逐行判定——判据限段内):命中 → 返回命中行片段(去空白 + 超长截断),
920
+ // 未命中 → null。片段回显进出口的跳过行,跳过因此自证(不是「段内某处出现过什么字面」)。
921
+ function visualToneNotApplicableHit(body) {
922
+ for (const rawLine of String(body).split(/\r?\n/)) {
923
+ const line = rawLine.trim();
924
+ if (line === '') continue;
925
+ if (TONE_MARKER_ALONE_LINE.test(line)
926
+ || TONE_MARKER_LINE_HEAD.test(line)
927
+ || TONE_MARKER_FIELD_VALUE.test(line)) {
928
+ return line.length > 60 ? line.slice(0, 60) + '…' : line;
929
+ }
930
+ }
931
+ return null;
932
+ }
933
+
934
+ // 登记表查询(唯一键表,键形 `<nodeId>.<skill>`):该节点 + 技能是否受适用性门控
935
+ function isRegisteredApplicabilityBinding(node, skill) {
936
+ return APPLICABILITY_GATED_BINDINGS.has(node.id + '.' + skill);
937
+ }
938
+
939
+ // 适用性门控绑定的单一查询:在场 ∧ enforcement === 'guarded' ∧ 登记在表 → 协议绑定;否则 null。
940
+ // 工件门、出口自动补写与缺声明恢复指引共用本查询——enforcement 是该门的单一表达处。
941
+ function applicabilityGatedBinding(node, skill) {
942
+ if (!isRegisteredApplicabilityBinding(node, skill)) return null;
943
+ return (node.requiredSkillCalls ?? []).find((call) => call.skill === skill && call.enforcement === 'guarded') ?? null;
944
+ }
945
+
946
+ // 前端判据:{ applicable, reason }——applicable=true 表示本 change 判为前端项目
947
+ async function frontendCriterion(changeName) {
948
+ const body = await visualToneSectionBody(changeName);
949
+ if (body === null) return { applicable: false, reason: '「视觉调性」段缺席(判非前端)' };
950
+ const hit = visualToneNotApplicableHit(body);
951
+ if (hit !== null) {
952
+ return { applicable: false, reason: '「视觉调性」段标注「不适用」(判非前端;命中片段: ' + hit + ')' };
953
+ }
954
+ return { applicable: true, reason: '「视觉调性」段在场且未标注「不适用」(判前端;无结构形态标记)' };
955
+ }
956
+
957
+ // design 出口 ui-design 工件门(按协议绑定键控:登记 ∧ 等级 = guarded ∧ 判据成立)——判据成立 ⇒
958
+ // 要求 UI-DESIGN.md 在场:新 change 缺件 BLOCKED + 恢复指引,旧 change WARN 渐进不阻断(不静默
959
+ // 放行);判据不成立(非前端)⇒ 可见跳过行(含命中片段)后照常放行;协议删掉该绑定或等级非
960
+ // guarded ⇒ 门未启用(同样可见输出),行为回到未登记绑定的原语义——闸门开关由协议表达。
961
+ async function checkUiDesignArtifact(node, state) {
962
+ if (!state.activeChange || !isRegisteredApplicabilityBinding(node, UI_DESIGN_SKILL)) return;
963
+ if (!applicabilityGatedBinding(node, UI_DESIGN_SKILL)) {
964
+ const protocolState = (node.requiredSkillCalls ?? []).some((call) => call.skill === UI_DESIGN_SKILL)
965
+ ? '协议 ' + node.id + ' 绑定等级 = advisory,非 guarded'
966
+ : '协议 ' + node.id + ' 节点未登记 ' + UI_DESIGN_SKILL + ' 绑定';
967
+ console.error('UI-DESIGN: 门未启用(' + protocolState + ')');
968
+ return;
969
+ }
970
+ const frontend = await frontendCriterion(state.activeChange);
971
+ if (!frontend.applicable) {
972
+ console.error('UI-DESIGN: skipped(非前端)——' + frontend.reason + ',不要求 UI-DESIGN.md');
973
+ return;
974
+ }
975
+ const artifact = path.join(runRoot, '.specs', state.activeChange, 'UI-DESIGN.md');
976
+ if (await fileExists(artifact)) return;
977
+ const recovery = '补 .specs/' + state.activeChange + '/UI-DESIGN.md(加载 ' + UI_DESIGN_SKILL + ' 并按其协议产出 design token / 反 AI-slop 自检),'
978
+ + '或在 .specs/' + state.activeChange + '/CHANGE.md 的「视觉调性」段以结构形态标注「不适用」(非前端项目)后重试 exit design';
979
+ if (isNewChange(state)) {
980
+ console.error('BLOCKED: design 出口缺 UI-DESIGN.md——' + frontend.reason + ',前端项目须产出 UI-DESIGN.md');
981
+ console.error('恢复: ' + recovery);
982
+ process.exit(1);
983
+ }
984
+ console.error('UI-DESIGN WARN: 缺 .specs/' + state.activeChange + '/UI-DESIGN.md——' + frontend.reason + '(旧 change 渐进不阻断;新 change 将强制)');
985
+ console.error('恢复: ' + recovery);
986
+ }
987
+
862
988
  // Fix 段标题从 <runRoot>/flow-kit/templates/TASK.md 派生(单一模板源 + 模块级缓存 + runRoot 键控):
863
989
  // 扫描模板全部 H2,用 route-node 共享 heading 归一(单一权威,含闭合 ATX)识别 Fix 段标题;
864
990
  // 无匹配(模板缺失 / 读取失败 / 无 Fix 段)返回 undefined,由回程分类器的内置 fallback 常量兜底。
@@ -1490,6 +1616,8 @@ async function main() {
1490
1616
  } catch {}
1491
1617
  }
1492
1618
  }
1619
+ // design 出口 ui-design 工件门(按协议绑定键控:登记 ∧ 等级 = guarded ∧ 判据成立)——见 checkUiDesignArtifact
1620
+ await checkUiDesignArtifact(node, state);
1493
1621
  // plan exit 校验 TASK 含 task 块和 verify 字段
1494
1622
  if (node.id === 'plan' && state.activeChange) {
1495
1623
  const taskFile = path.join(runRoot, '.specs', state.activeChange, 'TASK.md');
@@ -2299,11 +2427,17 @@ async function main() {
2299
2427
  }
2300
2428
  }
2301
2429
 
2302
- // 自动补 required-skill completedChecks——节点被完成即视为其实现 skill 已加载
2430
+ // 自动补 required-skill completedChecks——节点被完成即视为其实现 skill 已加载。
2431
+ // 分派(ui-design 门):仅「guarded 且适用性判据成立(判前端)」的登记绑定在**新 change**
2432
+ // 上停止自动补——该绑定须真实 skill-load 声明,由下方 missingRequiredSkillChecks 拦截;
2433
+ // 判据不成立(非前端)、旧 change(渐进兼容——自动补写保持原语义,工件门照常 WARN)或未登记
2434
+ // 的绑定 → 逐字保持原自动补语义(其它节点/绑定不受影响)。
2303
2435
  if ((node.requiredSkillCalls ?? []).length > 0) {
2304
2436
  const checks = Array.isArray(evidence.completedChecks) ? evidence.completedChecks : [];
2305
2437
  for (const binding of node.requiredSkillCalls ?? []) {
2306
2438
  const check = 'required-skill:' + node.id + '.' + binding.skill;
2439
+ const applicabilityGated = applicabilityGatedBinding(node, binding.skill) !== null;
2440
+ if (applicabilityGated && isNewChange(state) && (await frontendCriterion(state.activeChange)).applicable) continue;
2307
2441
  if (!checks.includes(check)) checks.push(check);
2308
2442
  }
2309
2443
  evidence.completedChecks = checks;
@@ -2329,6 +2463,16 @@ async function main() {
2329
2463
  const missingRequired = missingRequiredSkillChecks(node, evidence);
2330
2464
  if (missingRequired.length > 0) {
2331
2465
  console.error('BLOCKED: missing required Skill evidence: ' + missingRequired.join(', '));
2466
+ // ui-design 门:适用性门控绑定缺的是「真实 skill-load 声明」(出口不再自动补写)——给出补齐路径
2467
+ // (判据与该门同源:applicabilityGatedBinding 查询,不在此另写键表)
2468
+ for (const binding of node.requiredSkillCalls ?? []) {
2469
+ const check = 'required-skill:' + node.id + '.' + binding.skill;
2470
+ if (missingRequired.includes(check) && applicabilityGatedBinding(node, binding.skill) !== null) {
2471
+ console.error('恢复: ' + check + ' 不再由出口自动补写(guarded + 适用性判据成立)——先加载 ' + binding.skill
2472
+ + ' 并运行 workflow-state.mjs skill-load ' + node.id + ' ' + binding.skill
2473
+ + ' --prompt <flow-kit/prompts/ 协议文件> 声明已加载后重试 exit');
2474
+ }
2475
+ }
2332
2476
  process.exit(1);
2333
2477
  }
2334
2478
  const missingAugmentations = missingAugmentationChecks(node, evidence);
@@ -3,7 +3,7 @@ import { execFileSync } from 'child_process';
3
3
  import { promises as fs } from 'fs';
4
4
  import path from 'path';
5
5
  import { fileURLToPath } from 'url';
6
- import { validateStateFields, looksLikeObjectLiteral, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, resolveProtocolPathWithState } from './state-schema.mjs';
6
+ import { validateStateFields, looksLikeObjectLiteral, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, resolveProtocolPathWithState } from './state-schema.mjs';
7
7
  import { EXECUTE_FAMILY_NODE_IDS, protocolNodeEnabled, resolveDelegationTarget, taskDependencyEligibility } from './route-node.mjs';
8
8
  import {
9
9
  readProtocolFile,
@@ -256,8 +256,10 @@ async function writeState(state) {
256
256
  console.error('BLOCKED: state 字段类型非法: ' + bad[0]);
257
257
  process.exit(1);
258
258
  }
259
- await fs.mkdir(path.dirname(statePath), { recursive: true });
260
- await fs.writeFile(statePath, JSON.stringify(state, null, 2) + '\n', 'utf8');
259
+ // 落盘形态与引擎其余 state 写入对齐:同一原子写导出(原先直写会让同一 state 文件出现
260
+ // 「脚本通道原子、handoff 非原子」两种形态——半写窗口正是该文件最不可接受的损坏面)。
261
+ // 错误语义不变:写失败照常上抛(临时文件已清理),调用方按既有 fail-closed 处理。
262
+ await writeJsonAtomic(statePath, state);
261
263
  }
262
264
 
263
265
  // ---------- request 归属门禁(只读判定) ----------
@@ -6,8 +6,9 @@ import os from 'os';
6
6
  import path from 'path';
7
7
  import { fileURLToPath } from 'url';
8
8
  import { resolveProtocol, readProtocolFile, validateProtocolSchema, NODE_PROTOCOL_FILES, SKILL_PROTOCOL_FILES, inspectWorkflowPathSegments } from './protocol-utils.mjs';
9
- import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, looksLikeObjectLiteral, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, toPersistedProtocolPath } from './state-schema.mjs';
10
- import { probeProject, classify, printDetection, validateContext, printGenerationGuide, skipInit } from './context-init.mjs';
9
+ import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, looksLikeObjectLiteral, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, toPersistedProtocolPath } from './state-schema.mjs';
10
+ import { isValidTimestamp, daysSince, isArchivedAfterTimestamp, hasSection9, nowTimestamp, parseTimestamp, EVOLVE_STALE_DAYS, EVOLVE_DUE_NEW_ARCHIVE_CHANGES } from './time-utils.mjs';
11
+ import { probeProject, classify, printDetection, validateContext, printGenerationGuide, extractContextStructure, skipInit } from './context-init.mjs';
11
12
  import { taskOpeningAttrs, taskBlocks } from './task-parsing.mjs';
12
13
  import { route, resolveNextNode, hasSubagentNode, protocolTaskFilePath, resolveFixRollbackDecision, resolveFixRollbackState, applyFixRollbackRound, resolveFixReturnNode, resolveReentryDecision, resolveReplanDecision, analyzeDependencyGraph, findParallelWriteConflicts, isSingleSegmentChangeName, REENTRY_ROUND_LIMIT, REENTRY_TARGET_NODE_IDS, REPLAN_ROUND_LIMIT, EXECUTE_FAMILY_NODE_IDS } from './route-node.mjs';
13
14
 
@@ -34,21 +35,10 @@ async function readJson(file) {
34
35
  return JSON.parse((await fs.readFile(file, 'utf8')).replace(/^/, ''));
35
36
  }
36
37
 
37
- // JSON 写盘统一走原子写:先写同目录临时文件,再 rename 覆盖目标——目标文件要么是旧内容、
38
- // 要么是新内容,不会出现被截断的半写状态。写失败(磁盘满 / 权限 / 目标被占用)时清理临时文件
39
- // 后抛出,调用方按 fail-closed 处理。状态下发是单写者形态(机器字段只由脚本通道写),
40
- // 固定临时名与目标同目录,保证 rename 不跨卷。
41
- async function writeJson(file, value) {
42
- await fs.mkdir(path.dirname(file), { recursive: true });
43
- const temporary = file + '.tmp';
44
- try {
45
- await fs.writeFile(temporary, JSON.stringify(value, null, 2) + '\n', 'utf8');
46
- await fs.rename(temporary, file);
47
- } catch (error) {
48
- try { await fs.rm(temporary, { force: true }); } catch { /* 清理失败不掩盖原始写错误 */ }
49
- throw error;
50
- }
51
- }
38
+ // JSON 写盘统一走状态层单一来源的原子写(state-schema.mjs 的 writeJsonAtomic → writeFileAtomic):
39
+ // 先写同目录临时文件再 rename 覆盖目标——目标要么旧内容、要么新内容,不会出现被截断的半写状态;
40
+ // 写失败(磁盘满 / 权限 / 目标被占用)清理临时文件后抛出,调用方按 fail-closed 处理。mkdir recursive
41
+ // 由该实现承担(.skill-loads/ 等标记目录不存在时创建);状态下发是单写者形态(机器字段只由脚本通道写)。
52
42
 
53
43
  async function fileExists(file) {
54
44
  try { await fs.access(file); return true; } catch { return false; }
@@ -424,6 +414,58 @@ function printBranchLine(activeChange, branchPrefix = 'change/') {
424
414
  }
425
415
  }
426
416
 
417
+ // ---------- evolve 到期提示(AC-18:达阈值才输出,未达阈值零噪音) ----------
418
+
419
+ // 该时刻之后归档、且 DESIGN.md 带 §9 的 change 数。归档时刻取目录名日期前缀(flow-kit 约定
420
+ // archive/<YYYY-MM-DD>-<change-id>,该标签随提交固化、跨 clone 稳定);「归档于何时」与「§9 是否
421
+ // 在场」两个判定都走 time-utils 单一来源——不在本脚本内联第二份表达式(L-067)。
422
+ // 读取失败 / 非目录 / 无 DESIGN.md / 无 §9 一律不计入(不误报)。
423
+ async function countSection9ArchivesSince(timestamp) {
424
+ const archiveRoot = path.join(specsRoot, 'archive');
425
+ let entries = [];
426
+ try {
427
+ entries = await fs.readdir(archiveRoot, { withFileTypes: true });
428
+ } catch {
429
+ return 0;
430
+ }
431
+ let count = 0;
432
+ for (const entry of entries) {
433
+ if (!entry.isDirectory() || !isArchivedAfterTimestamp(entry.name, timestamp)) continue;
434
+ let design = '';
435
+ try {
436
+ design = await fs.readFile(path.join(archiveRoot, entry.name, 'DESIGN.md'), 'utf8');
437
+ } catch {
438
+ continue;
439
+ }
440
+ if (hasSection9(design)) count += 1;
441
+ }
442
+ return count;
443
+ }
444
+
445
+ // 到期提示:`last_evolve_at` 距今 > 60 天,或其后新增 ≥ 5 个带 §9 的归档 change → 输出一行;
446
+ // 否则**不打印任何行**(AC-18 反例锚:未达阈值零噪音)。旧 state 无该字段 = 从未跑过 evolve →
447
+ // 静默(本批不强制未接入 evolve 的项目补字段:无基线可判时不制造噪音)。提示行内不含花括号——
448
+ // status 的 JSON 块按「首个 { 到末个 }」截取(既有消费方 parseStatusJson 同形)。
449
+ async function printEvolveDueHint(state) {
450
+ const lastEvolveAt = state && typeof state.last_evolve_at === 'string' ? state.last_evolve_at : '';
451
+ if (!isValidTimestamp(lastEvolveAt)) return;
452
+ const elapsedDays = daysSince(lastEvolveAt);
453
+ if (Number.isNaN(elapsedDays)) return;
454
+ const staleByAge = elapsedDays > EVOLVE_STALE_DAYS;
455
+ const newArchives = await countSection9ArchivesSince(lastEvolveAt);
456
+ const staleByCount = newArchives >= EVOLVE_DUE_NEW_ARCHIVE_CHANGES;
457
+ if (!staleByAge && !staleByCount) return;
458
+ const reasons = [];
459
+ if (staleByAge) {
460
+ reasons.push('距今 ' + Math.floor(elapsedDays) + ' 天,超阈值 ' + EVOLVE_STALE_DAYS + ' 天');
461
+ }
462
+ if (staleByCount) {
463
+ reasons.push('其后新增 ' + newArchives + ' 个带 §9 的归档 change,达阈值 ' + EVOLVE_DUE_NEW_ARCHIVE_CHANGES + ' 个');
464
+ }
465
+ console.log('EVOLVE-DUE: 上次架构沉淀 ' + lastEvolveAt + '(' + reasons.join(';')
466
+ + ')——建议显式调用 evolve(/flow-comet-evolve)同步 CONTEXT.md');
467
+ }
468
+
427
469
  // C6: writeState 写入前校验已知字段类型(fail-closed:非法 → BLOCKED 拒绝写入,不修复不猜测)
428
470
  // 未知字段允许(前向兼容);缺字段允许(readState 默认补);只校验存在字段的类型。
429
471
  // 内置节点常量: 校验表已迁移到 state-schema.mjs(唯一来源),行为与迁移前的内联表完全一致(对第一个非法字段输出后退出)
@@ -433,7 +475,7 @@ async function writeState(state) {
433
475
  console.error('BLOCKED: state 字段类型非法: ' + bad[0]);
434
476
  process.exit(1);
435
477
  }
436
- await writeJson(statePath, state);
478
+ await writeJsonAtomic(statePath, state);
437
479
  }
438
480
 
439
481
  // .specs/ 下必须存在名字「逐字相等」的目录条目(change 名唯一性判据)。大小写不敏感文件系统
@@ -702,6 +744,61 @@ async function runBridgeCheck() {
702
744
  }
703
745
  }
704
746
 
747
+ // ---------- intel-scan 双落点一致性(init 的检测侧) ----------
748
+ // `last_intel_scan` 是**双落点**字段:引擎 state(机器真相、schema 校验)与 `.specs/CONTEXT.md` 的
749
+ // `## intel-scan 元数据` 段(项目可见)。段行的改写——含改写前备份与结构校验——只有 context-scan
750
+ // 一条通道一份实现;init 侧因此**不写段**(在第二处复制段行改写判据必然与前者分叉),只承担两条:
751
+ // ① 形态对齐:state 侧取值一律经 time-utils 的 nowTimestamp()(本地时间 + 显式偏移),与
752
+ // context-scan 写入的形态同源;历史 `Z` 形态继续可解析(不迁移)。
753
+ // ② 漂移可见:写完后与段侧取值比对(口径 = **取值词元**,与段行写通道替换的那个词元同口径)——
754
+ // 不一致(含**同一时刻的两种形态**、段内取值不可解析)即输出可见提示并点名收敛命令;一致则
755
+ // 静默(不误报);带行尾说明的段行不构成差异(说明由写通道原样保留,不是取值的一部分)。
756
+ const INTEL_SECTION_NAME = 'intel-scan 元数据';
757
+ const INTEL_FIELD_NAME = 'last_intel_scan';
758
+
759
+ // 段侧取值词元的归一:`extractContextStructure` 返回的是字段行冒号后的**整行剩余文本**
760
+ // (取值词元 + 可选的 markdown 引号 + 可选的行尾说明),而段行的写通道 `context-scan` 按
761
+ // `INTEL_FIELD_LINE = (…)(\S+)([\s\S]*)` 只替换**首个取值词元**、行尾说明原样保留(首次接入的
762
+ // CONTEXT 生成物即「词元 + 说明」形态)。读侧因此必须取同一口径的词元再比对:按整行剩余文本比对时,
763
+ // 带说明的段行与 state 永不相等 ⇒ 同刻同形态也恒亮「不一致」、类别退化成「段内取值不是合法时间戳」,
764
+ // 提示点名的 `context-scan` 收敛承诺不可达(提示噪声化 = 没人看的行)。
765
+ // 空白切分与写侧正则的 `\S+` 同一字符类语义;行结构(段名 / 字段行形态)仍唯一来自
766
+ // extractContextStructure——本函数只做「词元 + 引号」归一,不解析段行(L-067 单一来源)。
767
+ function normalizeIntelFieldValue(value) {
768
+ return String(value).trim().split(/\s+/)[0].replace(/^`+/, '').replace(/`+$/, '').trim();
769
+ }
770
+
771
+ // 漂移判定(纯函数):两侧取值不一致时返回差异类别,一致(或任一侧缺席)返回 null(不误报)。
772
+ function intelScanDriftKind(stateValue, sectionValue) {
773
+ if (typeof stateValue !== 'string' || typeof sectionValue !== 'string') return null;
774
+ if (stateValue === sectionValue) return null;
775
+ const atSection = parseTimestamp(sectionValue);
776
+ if (Number.isNaN(atSection)) return '段内取值不是合法时间戳';
777
+ const atState = parseTimestamp(stateValue);
778
+ if (!Number.isNaN(atState) && atState === atSection) return '同刻不同形态';
779
+ return '刻与形态均不一致';
780
+ }
781
+
782
+ // 双落点比对(读盘 + 输出):段侧文档缺席 / 段或缺字段不在场 = 无可比对面 → 静默(不无中生有);
783
+ // 检出漂移 → 可见提示(stdout,与 INIT-* 提示同族且不阻断 init),点名两侧取值与收敛命令。
784
+ async function reportIntelScanDrift(contextFile, stateValue) {
785
+ let contextText;
786
+ try {
787
+ contextText = await fs.readFile(contextFile, 'utf8');
788
+ } catch {
789
+ return; // 段侧文档不可读 = 无可比对面
790
+ }
791
+ const fields = extractContextStructure(contextText).metadata[INTEL_SECTION_NAME];
792
+ if (!fields || !fields[INTEL_FIELD_NAME]) return; // 段或缺字段不在场 = 无可比对面
793
+ const landed = normalizeIntelFieldValue(fields[INTEL_FIELD_NAME].value);
794
+ const kind = intelScanDriftKind(stateValue, landed);
795
+ if (kind === null) return;
796
+ console.log('INIT-NOTICE: ' + INTEL_FIELD_NAME + ' 双落点不一致(' + kind + ')——引擎 state = '
797
+ + stateValue + ';`.specs/CONTEXT.md` 的 `## ' + INTEL_SECTION_NAME + '` 段 = ' + landed
798
+ + '。本命令只写 state(该段行的写通道是 context-scan);运行 context-scan 即把两处收敛为'
799
+ + '同刻同形态(冲突时以 state 为准)。');
800
+ }
801
+
705
802
  async function main() {
706
803
  // 协议解析: 协议加载 = resolveProtocol 解析路径 + 受保护读取 + fail-closed schema 校验
707
804
  // (读失败/校验失败直接 throw,沿用现有错误处理风格)
@@ -827,12 +924,23 @@ async function main() {
827
924
  // 项目级上下文字段跨 change 保留(迁移旧 state;--init-context 刷新扫描时间;--init-skip 记拒绝)
828
925
  ...(prevState?.ai_context_doc !== undefined ? { ai_context_doc: prevState.ai_context_doc } : {}),
829
926
  ...(initSkip ? { ai_context_doc: 'none' } : {}),
830
- // last_intel_scan 仅在校验通过后写入(agent 生成 → 脚本校验 7 段 → 记录扫描时间)
927
+ // last_intel_scan 仅在校验通过后写入(agent 生成 → 脚本校验 7 段 → 记录扫描时间);形态一律经
928
+ // time-utils 的 nowTimestamp()(本地时间 + 显式偏移)——与 context-scan 的落点形态同源,不在本
929
+ // 脚本内联第二份格式化。段侧**不在本命令的写面内**(该段行的改写与备份只有 context-scan 一份
930
+ // 实现):两处取值不一致由 reportIntelScanDrift 检出并给出可见提示,不静默漂移。
831
931
  ...(ctxValid === true
832
- ? { last_intel_scan: new Date().toISOString() }
833
- : (prevState?.last_intel_scan !== undefined ? { last_intel_scan: prevState.last_intel_scan } : {}))
932
+ ? { last_intel_scan: nowTimestamp() }
933
+ : (prevState?.last_intel_scan !== undefined ? { last_intel_scan: prevState.last_intel_scan } : {})),
934
+ // last_evolve_at 同为**项目级**字段(evolve 的跨 change 基线,写通道 = config set)——init 换
935
+ // change 必须原样保留:丢了它,增量窗口静默退化为全量扫描、到期提示从此不再触发(保留判据与
936
+ // 上一行同形:字段缺席 = 从未跑过 evolve,不得凭空制造该字段——state-schema 不接受 null)
937
+ ...(prevState?.last_evolve_at !== undefined ? { last_evolve_at: prevState.last_evolve_at } : {})
834
938
  };
835
939
  await writeState(state);
940
+ // 扫描时刻的双落点一致性(state ↔ `.specs/CONTEXT.md` 的 `## intel-scan 元数据` 段):本命令写
941
+ // state 后即比对段侧取值——不一致(含同一时刻的两种形态)输出可见提示并点名收敛命令;一致或
942
+ // 无可比对面则静默(不误报)。段行的写通道只有 context-scan,故此处是检测、不是第二份改写实现。
943
+ await reportIntelScanDrift(path.join(specsRoot, 'CONTEXT.md'), state.last_intel_scan);
836
944
  // init 创建 .specs/<id>/ 目录——文件即真相从 init 起成立,findActiveChange 立即可识别
837
945
  //(此前 init 后 next/status 报 No active change,与 SKILL 启动协议 init → next 矛盾)
838
946
  const specsChangeDir = path.join(specsRoot, changeName);
@@ -874,6 +982,8 @@ async function main() {
874
982
  const changeName = await findActiveChange();
875
983
  if (!changeName) {
876
984
  console.log(JSON.stringify({ status: 'no-change', message: 'No active change in .specs/' }, null, 2));
985
+ // 到期提示属**项目级**元数据(与是否有 active change 无关):无活跃 change 时同样按阈值输出
986
+ await printEvolveDueHint(await readState());
877
987
  return;
878
988
  }
879
989
  const state = await readState();
@@ -921,6 +1031,7 @@ async function main() {
921
1031
  newChange: state.newChange === true
922
1032
  }, null, 2));
923
1033
  printBranchLine(changeName, state.branchPrefix ?? 'change/');
1034
+ await printEvolveDueHint(state);
924
1035
  return;
925
1036
  }
926
1037
 
@@ -1161,7 +1272,7 @@ async function main() {
1161
1272
  if (promptArg !== null && !protocolUnderFlowKitPrompts(promptArg)) {
1162
1273
  throw new Error('skill-load --prompt 路径必须位于 flow-kit/prompts/ 下(flow-kit 为 vendored 上游,协议提示只读引用): ' + promptArg);
1163
1274
  }
1164
- // 声明标记写入:.skill-loads/ 目录不存在时创建(writeJson 自带 mkdir recursive);
1275
+ // 声明标记写入:.skill-loads/ 目录不存在时创建(writeJsonAtomic 自带 mkdir recursive);
1165
1276
  // 同 node-skill 重复调用覆盖(记录最新声明)
1166
1277
  const changeName = await findActiveChange();
1167
1278
  if (!changeName) {
@@ -1176,7 +1287,7 @@ async function main() {
1176
1287
  const marker = { node: nodeId, skill: skillName, protocol: promptArg === null ? null : path.basename(promptArg), at: new Date().toISOString() };
1177
1288
  // specsRoot 已含 .specs/,相对路径为 <change-id>/.skill-loads/<node>-<skill>.json
1178
1289
  const markerRel = path.posix.join(changeName, '.skill-loads', nodeId + '-' + skillName + '.json');
1179
- await writeJson(path.join(specsRoot, markerRel), marker);
1290
+ await writeJsonAtomic(path.join(specsRoot, markerRel), marker);
1180
1291
  console.log('SKILL-LOAD: ' + nodeId + ' ' + skillName + ' → .skill-loads/' + nodeId + '-' + skillName + '.json');
1181
1292
  return;
1182
1293
  }
@@ -1278,7 +1389,7 @@ async function main() {
1278
1389
  // M5 标记目录解析:活动路径优先;change 已归档(活动目录不存在但归档目录存在)
1279
1390
  // 时写归档路径——防重建已归档的活动目录(归档移动语义;与 findSkillLoadsDir 双路径一致)。
1280
1391
  // 跳过条件:活动与归档均无 .skill-loads **且活动 change 目录已不存在**(归档移动后)
1281
- // ——此时 writeJson 的 mkdir recursive 会把已归档的活动目录残留回来(修复前实测缺陷);
1392
+ // ——此时 writeJsonAtomic 的 mkdir recursive 会把已归档的活动目录残留回来(修复前实测缺陷);
1282
1393
  // 活动 change 目录仍存在(正常流程)时创建 .skill-loads 子目录是 M5 的正常职责,不跳过
1283
1394
  const activeLoadsDir = path.join(specsRoot, markerChange, '.skill-loads');
1284
1395
  let targetLoadsDir = activeLoadsDir;
@@ -1303,7 +1414,7 @@ async function main() {
1303
1414
  // 1-requirement.md 而非节点首文件 0-change.md——修复前所有 skill 都写首文件,
1304
1415
  // 标记的协议归属语义错误;exit 校验只查归属集合故能通过,但标记不可信)
1305
1416
  const skillProtoFiles = SKILL_PROTOCOL_FILES[binding.skill] ?? [];
1306
- await writeJson(markerFile, {
1417
+ await writeJsonAtomic(markerFile, {
1307
1418
  node: nodeId,
1308
1419
  skill: binding.skill,
1309
1420
  protocol: skillProtoFiles.length > 0 ? skillProtoFiles[0] : null,
@@ -1328,7 +1439,8 @@ async function main() {
1328
1439
  }
1329
1440
 
1330
1441
  if (command === 'config') {
1331
- // E1: 配置命令——config set <key> <value>;branchMode 只读(init 自动判定),enablePrReview 手动开关
1442
+ // E1: 配置命令——config set <key> <value>;branchMode 只读(init 自动判定),enablePrReview 手动
1443
+ // 开关,last_evolve_at 为 evolve 元数据时刻(形态校验 fail-closed,写通道唯一)
1332
1444
  const sub = process.argv[3];
1333
1445
  const key = process.argv[4];
1334
1446
  const value = process.argv[5];
@@ -1349,7 +1461,21 @@ async function main() {
1349
1461
  console.log('CONFIG: enablePrReview = ' + state.enablePrReview);
1350
1462
  return;
1351
1463
  }
1352
- console.error('BLOCKED: 未知配置键: ' + key + '(支持: enablePrReview;branchMode 由 init 自动判定)');
1464
+ // evolve 元数据时间戳(脚本不直写 state,项目级字段一律经本通道)。形态非法 → BLOCK
1465
+ // 且**零改写**(校验先于读 state 与写盘;writeState 侧的字段校验表是第二道闸,同一判据)。
1466
+ if (key === 'last_evolve_at') {
1467
+ if (!isValidTimestamp(value)) {
1468
+ console.error('BLOCKED: config set 值非法(last_evolve_at 必须为本地时间 + 显式偏移形态 '
1469
+ + 'YYYY-MM-DDTHH:mm:ss±HH:mm,兼容历史 Z 形态): ' + value);
1470
+ process.exit(1);
1471
+ }
1472
+ const state = await readState();
1473
+ state.last_evolve_at = value;
1474
+ await writeState(state);
1475
+ console.log('CONFIG: last_evolve_at = ' + state.last_evolve_at);
1476
+ return;
1477
+ }
1478
+ console.error('BLOCKED: 未知配置键: ' + key + '(支持: enablePrReview, last_evolve_at;branchMode 由 init 自动判定)');
1353
1479
  process.exit(1);
1354
1480
  }
1355
1481