flow-comet 1.6.0 → 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.
Files changed (43) hide show
  1. package/.flow-comet/skills/flow-comet/GUIDANCE.md +26 -5
  2. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  3. package/.flow-comet/skills/flow-comet/SKILL.md +51 -2
  4. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
  5. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
  6. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
  7. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
  8. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
  10. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
  11. package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
  12. package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
  13. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
  14. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5499 -596
  15. package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
  16. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
  17. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
  18. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +58 -3
  19. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1024 -11
  20. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
  21. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +285 -227
  22. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +6 -4
  23. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +515 -31
  24. package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
  25. package/.flow-comet/skills/flow-comet-change/SKILL.md +13 -1
  26. package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -2
  27. package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
  28. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
  29. package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
  30. package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
  31. package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
  32. package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
  33. package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
  34. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
  35. package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
  36. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
  37. package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
  38. package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
  39. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +28 -3
  40. package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
  41. package/README.md +45 -119
  42. package/package.json +1 -1
  43. package/scripts/dsh-bridge.mjs +2 -2
@@ -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
+ }