flow-comet 1.6.3 → 1.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +21 -3
  3. package/.flow-comet/skills/flow-comet/reference/artifact-template-overlay.md +154 -0
  4. package/.flow-comet/skills/flow-comet/reference/artifact-templates.json +387 -0
  5. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +8 -2
  6. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  7. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +11 -13
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +2 -2
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +180 -6
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +69 -18878
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +29 -5
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +1053 -0
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +830 -0
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +781 -0
  15. package/.flow-comet/skills/flow-comet/scripts/items/d.mjs +99 -0
  16. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +185 -0
  17. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +90 -0
  18. package/.flow-comet/skills/flow-comet/scripts/items/g.mjs +59 -0
  19. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +817 -0
  20. package/.flow-comet/skills/flow-comet/scripts/items/i.mjs +77 -0
  21. package/.flow-comet/skills/flow-comet/scripts/items/j.mjs +75 -0
  22. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +1427 -0
  23. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +275 -0
  24. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +618 -0
  25. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  26. package/.flow-comet/skills/flow-comet/scripts/lib/count-derivation.mjs +97 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +196 -0
  28. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +756 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1235 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +384 -0
  32. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +404 -0
  33. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +714 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +204 -0
  35. package/.flow-comet/skills/flow-comet/scripts/lib/reentry-node.mjs +237 -0
  36. package/.flow-comet/skills/flow-comet/scripts/lib/replan-node.mjs +209 -0
  37. package/.flow-comet/skills/flow-comet/scripts/lib/state-branch.mjs +49 -0
  38. package/.flow-comet/skills/flow-comet/scripts/lib/state-bridgecheck.mjs +201 -0
  39. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +179 -0
  40. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +714 -0
  41. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +578 -0
  42. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +52 -0
  43. package/.flow-comet/skills/flow-comet/scripts/lib/state-evolve-hint.mjs +55 -0
  44. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +123 -0
  45. package/.flow-comet/skills/flow-comet/scripts/lib/state-intelscan.mjs +58 -0
  46. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +147 -0
  47. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +249 -0
  48. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +1505 -0
  49. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +471 -0
  50. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +509 -0
  51. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +1248 -0
  52. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +237 -0
  53. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +2493 -0
  54. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +214 -2
  55. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +72 -1123
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +976 -0
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1233 -0
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1382 -0
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +483 -0
  60. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +1398 -0
  61. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +1466 -0
  62. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +1367 -0
  63. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +1287 -0
  64. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +1436 -0
  65. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +1384 -0
  66. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +1338 -0
  67. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +1492 -0
  68. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +971 -0
  69. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  70. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +1 -1
  71. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +59 -7559
  72. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +4 -4
  73. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +223 -2476
  74. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +5 -5
  75. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +27 -2190
  76. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  77. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  78. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  79. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  80. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  81. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  82. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  83. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  84. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  85. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  86. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  87. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  88. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  89. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  90. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  91. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  92. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  93. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  94. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  95. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  96. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  97. package/README.md +52 -69
  98. package/package.json +3 -2
  99. package/scripts/dsh-bridge.mjs +2 -2
  100. package/scripts/lib/installer-cleanup.mjs +152 -0
  101. package/scripts/lib/installer-flowkit.mjs +159 -0
  102. package/scripts/lib/installer-hooks.mjs +363 -0
  103. package/scripts/lib/installer-loader.mjs +220 -0
  104. package/scripts/lib/installer-migrate.mjs +236 -0
  105. package/scripts/lib/installer-platforms.mjs +314 -0
  106. package/scripts/prepare-env.mjs +21 -1313
@@ -110,9 +110,13 @@ flow-kit 9 阶段工作流的 workflow-kernel 实现。保留 flow-kit 的全部
110
110
  2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
111
111
 
112
112
  ```bash
113
- node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md
113
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md --templates <模板基名,...>
114
114
  ```
115
115
 
116
+ > **`--templates` 是内置节点的必填声明**(每个标记各写全清单):open → `CHANGE.md,REQUIREMENT.md` · design → `DESIGN.md`(前端可加 `UI-DESIGN.md`)· plan → `TASK.md` · execute / subagent-execute → `SUMMARY.md` · review → `REVIEW.md,TEST.md` · verify / archive 为零模板节点,**省略该参数**。逐节点示例命令见各节点册的「加载声明」小节。
117
+
118
+ > **加载链的两条指针**:节点入口**先**打印 `READ PROMPT:`(指向 `flow-kit/prompts/<阶段>.md`——这一步怎么做),**再**打印 `READ TEMPLATE:`(指向 `flow-kit/templates/<DOC>.md`——产出长什么样),**有模板的节点两行都要读**;零模板节点(verify / archive)只有 `READ PROMPT:`。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);落在节点协议面外的路径会在下一次入口被拦下(BLOCKED)并给出重声明命令——重跑声明即可,不要手改标记。
119
+
116
120
  > **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
117
121
 
118
122
  节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。`flow-comet-ui-design` 与协议同等级(`guarded`)且**仅前端适用**:前端 change 须先加载并 `skill-load` 声明、record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端不加载不声明(出口输出可见的 `UI-DESIGN: skipped(非前端)`);旧 change 渐进,缺件仅 WARN。前端判据是**结构级**的:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**——**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」不算标注,仍判前端。
@@ -168,9 +172,11 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"su
168
172
 
169
173
  All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
170
174
 
171
- > **模板权威**:工件段形以 `flow-kit/templates/**` 为唯一权威。
175
+ > **模板权威**:工件段形 = **上游模板 + 本仓登记的增量段**——`flow-kit/templates/**` 是唯一权威,增量段与条件段登记见 `reference/artifact-templates.json`。
172
176
  > **archive 定位与读法**:见主 `SKILL.md` 的「Artifact Paths」小节(单一来源——「何时可读 / 读什么 / 不读什么」的三段判据只在那一处表达,本文不复述)。
173
177
 
178
+ > **要核对某工件的条件段 / 结构子段 / 增量段登记时,先读 `reference/artifact-template-overlay.md`**(逐工件的人类可读登记册;快照与指纹以登记表 JSON 为准)。
179
+
174
180
  ### Scripts
175
181
 
176
182
  > **命令路径的平台化**:本文件命令统一为**权威源设计形态** `node .claude/skills/flow-comet/scripts/...`。安装时由 prepare-env 按平台处理——Claude Code 平台零替换(即此形态);Codex 平台自动替换为 `node .agents/skills/flow-comet/scripts/...`(技能安装于 `.agents/skills/`,Codex 自动发现)。相对引用(`reference/`、`flow-kit/`)不替换——随技能目录整体复制,相对位置不变。手动复制(方案 C)仅面向 Claude Code;Codex 请用安装器。
@@ -38,6 +38,10 @@
38
38
  "outputSchemas": [
39
39
  "flowkit.intake.v1"
40
40
  ],
41
+ "templates": [
42
+ "CHANGE",
43
+ "REQUIREMENT"
44
+ ],
41
45
  "guardrails": [
42
46
  {
43
47
  "id": "intake-artifacts",
@@ -84,6 +88,9 @@
84
88
  "outputSchemas": [
85
89
  "flowkit.design.v1"
86
90
  ],
91
+ "templates": [
92
+ "DESIGN"
93
+ ],
87
94
  "guardrails": [
88
95
  {
89
96
  "id": "design-artifacts",
@@ -123,6 +130,9 @@
123
130
  "outputSchemas": [
124
131
  "flowkit.plan.v1"
125
132
  ],
133
+ "templates": [
134
+ "TASK"
135
+ ],
126
136
  "guardrails": [
127
137
  {
128
138
  "id": "plan-artifacts",
@@ -161,6 +171,9 @@
161
171
  "outputSchemas": [
162
172
  "flowkit.execution.v1"
163
173
  ],
174
+ "templates": [
175
+ "SUMMARY"
176
+ ],
164
177
  "guardrails": [
165
178
  {
166
179
  "id": "build-evidence",
@@ -199,6 +212,9 @@
199
212
  "outputSchemas": [
200
213
  "flowkit.handoff.v1"
201
214
  ],
215
+ "templates": [
216
+ "SUMMARY"
217
+ ],
202
218
  "guardrails": [
203
219
  {
204
220
  "id": "handoff-evidence",
@@ -244,6 +260,10 @@
244
260
  "outputSchemas": [
245
261
  "flowkit.review.v1"
246
262
  ],
263
+ "templates": [
264
+ "REVIEW",
265
+ "TEST"
266
+ ],
247
267
  "guardrails": [
248
268
  {
249
269
  "id": "review-evidence",
@@ -282,6 +302,7 @@
282
302
  "outputSchemas": [
283
303
  "flowkit.verify.v1"
284
304
  ],
305
+ "templates": [],
285
306
  "guardrails": [
286
307
  {
287
308
  "id": "verify-evidence",
@@ -320,6 +341,7 @@
320
341
  "outputSchemas": [
321
342
  "flowkit.archive.v1"
322
343
  ],
344
+ "templates": [],
323
345
  "guardrails": [
324
346
  {
325
347
  "id": "archive-evidence",
@@ -53,7 +53,7 @@ function hookOk(extra) {
53
53
  }
54
54
 
55
55
  // 拦截输出:Codex 分支输出 {"decision":"block",reason} + exit 0(实测确认的 Codex deny 通道——
56
- // 2026-08-13 Codex 0.146:exit 2 / permissionDecision:"deny" 均不被 enforce,decision:"block"+exit 0 生效);
56
+ // exit 2 / permissionDecision:"deny" 均不被 enforce,decision:"block"+exit 0 生效);
57
57
  // Claude Code 分支既有文本 + exit 2。
58
58
  function hookBlock(mainLine, detailLine) {
59
59
  if (isCodex) {
@@ -378,9 +378,9 @@ async function agentWorktreeWriteStaysIsolated(targetRel) {
378
378
  // (fail-closed)。hook 拦工具不拦脚本——脚本通道天然不触发 PreToolUse,不受影响。
379
379
  // 与 M1 归档白名单收窄同型:保护机器文件不被越权手改(含 direct 模式下白名单 [''] 曾
380
380
  // 放行 state 写入的 fail-open 缺口——执行者自切 direct 越权写的物理入口)。
381
- // 大小写变体闭合(CodeRabbit 采纳):win32/darwin 文件系统大小写不敏感,`.Flow-Comet/Flow-Comet-
381
+ // 大小写变体闭合:win32/darwin 文件系统大小写不敏感,`.Flow-Comet/Flow-Comet-
382
382
  // State.json` 与机器状态文件指向同一实体——目标路径先 toLowerCase() 再与机器状态相对路径
383
- // 比较,变体同等 BLOCK(修复前精确等值比较被变体绕过 → fail-open)。其他平台
383
+ // 比较,变体同等 BLOCK(精确等值比较会被变体绕过 → fail-open)。其他平台
384
384
  // (大小写敏感文件系统)变体是不同文件,保持精确等值比较(不误拦合法路径)。
385
385
  // 取值唯一来源 = state-schema.mjs 的 RUNTIME_STATE_PATH(项目根相对的 POSIX 路径)。
386
386
  // 本文件不再硬编码该路径——命名空间/文件名变更只改 state-schema.mjs 一处。
@@ -405,7 +405,7 @@ function blockStateFileWrite(target) {
405
405
  // (消费方只问「是不是子代理」),不得下沉为 `if (platform === ...)` 之类的平台分支。
406
406
  // dsh 面按**实现位置修订**(规划期落定):桥接只把委派深度透传进环境变量,身份判定与保护集判定的
407
407
  // 整条都归本文件独占——桥接不再持有任何一份判定,两侧没有分叉的余地(归因以本节为准)。
408
- // env 面的作用域收紧(2026-10-07):CC / Codex 生成的 hook **直接**调用本文件、并不自证是 dsh——
408
+ // env 面的作用域收紧:CC / Codex 生成的 hook **直接**调用本文件、并不自证是 dsh——
409
409
  // 只看深度变量时,该变量一旦被继承进这些 hook 的进程环境(父进程导出 / 包装脚本转发),守卫就会在
410
410
  // phase / worktree / runRoot 检查**之前**走子代理路径返回,只剩最小保护集兜底。故桥接在注入深度的
411
411
  // 同时注入**通道标记** FLOW_COMET_AGENT_DEPTH_SOURCE=dsh-bridge;env 面身份**要求两者同时在场**
@@ -487,7 +487,7 @@ const protocolPath = resolveProtocol(packageRoot, runRoot, []);
487
487
  // RUNTIME_STATE_PATH);② 本次运行**实际生效**的协议文件(取值来源 = 上方 protocol-utils
488
488
  // resolveProtocol 的解析结果——本文件不另造第二份协议路径口径)。
489
489
  // 同一性判定复用 protocol-utils 既有受保护路径判据 workflowPathInside(互含 ⇒ 同一路径):
490
- // 路径归一/相对化只此一份,本文件不新增第二份路径判据(L-067)。大小写敏感性与状态文件判据
490
+ // 路径归一/相对化只此一份,本文件不新增第二份路径判据。大小写敏感性与状态文件判据
491
491
  // 同口径(共用 CASE_INSENSITIVE_FS 策略常量;win32 的 path.relative 本身已按小写比较)。
492
492
  function isSameWorkflowPath(left, right) {
493
493
  const fold = (value) => (CASE_INSENSITIVE_FS ? value.toLowerCase() : value);
@@ -503,7 +503,7 @@ function blockedProtocolFileTarget(absoluteTarget) {
503
503
  // 保护集的**物理**同一性判定(词法判定的别名闭合):8.3 短路径 / 符号链接 / junction / 硬链接
504
504
  // 是同一文件实体的不同拼写,词法比较看不见它们(身份放行下保护集是唯一防线,故须闭合)。
505
505
  // 判据复用 protocol-utils.mjs 导出的文件身份比较判据(workflowFileObjectIdentity +
506
- // workflowSameFileObject)——本文件不新增第二份文件身份判据(L-067)。
506
+ // workflowSameFileObject)——本文件不新增第二份文件身份判据。
507
507
  // 目标不存在(新建文件是常态)或 stat 失败 ⇒ 无法证明同一 ⇒ 返回 false(退回词法判定);
508
508
  // 诚实边界:物理判定只证明「此刻存在且同一」,不证明「将来仍同一」(与 TOCTOU 同族的既有限制)。
509
509
  async function isSameProtectedFileObject(targetAbsolute, protectedAbsolute) {
@@ -565,8 +565,8 @@ const WORKFLOW_PROJECT_FILE_MAX_BYTES = 2 * 1024 * 1024;
565
565
 
566
566
  // 受保护路径三判据(workflowPathInside / inspectWorkflowProtectedPath /
567
567
  // readWorkflowProtectedFile)与私有身份比较函数是 protocol-utils.mjs 的**单一来源**——
568
- // 本文件此前各持一份逐字节相同的副本,两侧注释互指「同源」;副本已删除,改为 import
569
- // (见文件头 import 列表)。改判据只需改 protocol-utils.mjs 一处。
568
+ // 本文件不另持副本(两份逐字节相同的副本必然分叉,互指「同源」的注释不是同步机制),
569
+ // 一律 import(见文件头 import 列表)——改判据只需改 protocol-utils.mjs 一处。
570
570
 
571
571
  function workflowRelativeSegments(value, label, allowWildcards = false) {
572
572
  if (typeof value !== 'string') throw new Error(label + ' must be a string');
@@ -670,7 +670,7 @@ async function readHookInput() {
670
670
  }
671
671
  }
672
672
 
673
- // 盘符根拼写归一(单一实现——只由下方写入目标解析消费,不得在别处再写一份同义归一,L-067)。
673
+ // 盘符根拼写归一(单一实现——只由下方写入目标解析消费,不得在别处再写一份同义归一)。
674
674
  // Windows 上 Git-Bash 类 shell 把 `D:\<剩余>` 写作 `/d/<剩余>`(盘符小写 + 正斜杠)。win32 的
675
675
  // 目标解析把该拼写读成「**当前盘根**下的 \d\<剩余>」而非 `D:\<剩余>`:同一文件于是被判成根外,
676
676
  // 词法相对化与物理同一性两道保护集判据同时失守(身份放行下保护集是唯一防线 ⇒ 静默放行)。
@@ -773,8 +773,6 @@ async function resolvePhaseWriteWhitelist(executionMode) {
773
773
  // archive 白名单:归档阶段仅遗留清单(KNOWN-ISSUES.md)可写入 change 目录(先写后移),
774
774
  // 其余 change 工件不可改(收窄为精确文件——放宽到整个目录会让归档阶段可改任意
775
775
  // 工件且无校验,防线变宽);<change-id> 占位符由 targetAllowed 替换为当前 change;
776
- // 目录移动由 .specs/archive/ 覆盖(2026-08-15 修复:此前仅 .specs/archive/ 导致按文档
777
- // 流程被 BLOCK;2026-08-16 收窄为精确文件)
778
776
  'archive': ['.specs/archive/', '.specs/<change-id>/KNOWN-ISSUES.md', '.specs/CHANGELOG.md', '.specs/LESSONS.md', 'STATE.md'],
779
777
  },
780
778
  declared: false,
@@ -883,7 +881,7 @@ async function main() {
883
881
 
884
882
  // ── ②【ADR-014 决策 6】runRoot 外写入的 fail-open 关断(两分支对称)──────────────────
885
883
  // file_path 解析为项目根之外时,与上方 Bash 分支**同判**:该分支对 targetRel === null 的目标
886
- // 同样落入 `allowed=false` → 拦截。修复前 file_path 分支在此静默落入后继流程(越界写无痕放过),
884
+ // 同样落入 `allowed=false` → 拦截。否则 file_path 分支会静默落入后继流程(越界写无痕放过),
887
885
  // Bash 分支却拦截 —— 同一目标因工具而异。判定条件与 Bash 分支逐条对齐(有写入语义 + currentNode
888
886
  // 在场);身份在场者已由上方 ① 短路放行,故「手工 worktree 绝对路径写入」不受本关断影响。
889
887
  if (fileTarget && !fileTarget.insideRunRoot && currentNode) {
@@ -904,7 +902,7 @@ async function main() {
904
902
  hookBlock(`BLOCKED: phase "${currentNode}" 不允许写入 "${target}"`, `允许范围: ${whitelist.join(', ')}`);
905
903
  }
906
904
  } else if (declared) {
907
- // 审查补充(2026-08-08):协议声明了 writeWhitelist 但未列出当前节点 → fail-closed 拒绝
905
+ // 协议声明了 writeWhitelist 但未列出当前节点 → fail-closed 拒绝
908
906
  // (漏声明节点不放行——防协议作者漏列导致防线出洞)
909
907
  hookBlock(`BLOCKED: phase "${currentNode}" 未在协议 writeWhitelist 中声明,默认拒绝写入 "${target}"`, `请在协议 writeWhitelist 中为节点 "${currentNode}" 声明允许的路径前缀`);
910
908
  } else {
@@ -106,7 +106,7 @@ export function classify(probe, state) {
106
106
  }
107
107
 
108
108
  // 输出提示(公开描述性文案;INIT-NEEDED 含预算说明与参数指引)
109
- // C 优化(2026-08-10):CONTEXT 已满足模板但无扫描记录(agent 生成后未重跑)→
109
+ // CONTEXT 已满足模板但无扫描记录(agent 生成后未重跑)→
110
110
  // 提示精准动作(记录扫描时间)而非误导性的"刷新"文案。
111
111
  export async function printDetection(runRoot, probe, verdict, out = console) {
112
112
  if (verdict === 'skip') return;
@@ -133,7 +133,7 @@ export async function printDetection(runRoot, probe, verdict, out = console) {
133
133
  }
134
134
 
135
135
  // CONTEXT 模板 7 段标题(校验基准——agent 生成后脚本校验结构完整性)
136
- // 2026-08-10 改进:段清单从 flow-kit/templates/CONTEXT.md 解析派生(括号前前缀),
136
+ // 段清单从 flow-kit/templates/CONTEXT.md 解析派生(括号前前缀),
137
137
  // 模板缺失/解析不到时 fallback 内置(对齐 C2 段名校验模板派生模式,消灭手抄漂移)。
138
138
  const CONTEXT_SECTIONS_FALLBACK = [
139
139
  '## 项目概要',
@@ -7,7 +7,7 @@
7
7
  // node evolve.mjs apply <候选 id> [<候选 id> ...] [--root <项目根>] [--scanner <执行工具>] [--stdout]
8
8
  // node evolve.mjs --help | -h
9
9
  //
10
- // 单一权威(L-067):「沉淀段在场」判定(hasSection9)与归档窗口判定(isArchivedAfterTimestamp)
10
+ // 单一权威:「沉淀段在场」判定(hasSection9)与归档窗口判定(isArchivedAfterTimestamp)
11
11
  // 一律 import time-utils.mjs;时间形态 / 解析 / 天差走 nowTimestamp / formatLocalDate /
12
12
  // parseTimestamp / daysSince——本模块不内联第二份时间正则,也不自行拼接时间字符串。
13
13
  // 「改写前备份」的命名族与失败处置走 state-schema.mjs 的 backupBeforeWrite(单一来源)——
@@ -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 同名。
@@ -114,15 +127,15 @@ function usage() {
114
127
 
115
128
  // ---------- 侧命令 CLI 契约(单一来源) ----------
116
129
  // 根相对 POSIX 路径标签:三条横向命令的 CLI 摘要行与工件段落都要把绝对路径显示成项目根相对形态
117
- // (跨机器可读、可直接粘回命令行)。此前 evolve 内联、context-scan 自持一份同名助手——同一显示
118
- // 决定的第二份表达;现由本模块(侧命令共享助手的既有落点)导出,三条命令同源消费。
130
+ // (跨机器可读、可直接粘回命令行)。同一显示决定不得有第二份表达(两份必然分叉)——由本模块
131
+ // (侧命令共享助手的既有落点)唯一导出,三条命令同源消费。
119
132
  export function relativeLabel(root, file) {
120
133
  return path.relative(root, file).split(path.sep).join('/');
121
134
  }
122
135
 
123
136
  // 三条横向命令(evolve / health / context-scan)共用本解析器:`--root <目录>` 与 `--root=<目录>`
124
- // 两种形态、`--stdout`、`--help`/`-h`、未知参数**各只在此处表达一次**——此前三份自写脚手架必然分叉
125
- // (一条不支持等号形、`--help` 只有一条有、错误构造三份各写一遍)。位置参数语义(evolve 的
137
+ // 两种形态、`--stdout`、`--help`/`-h`、未知参数**各只在此处表达一次**——多份自写脚手架必然分叉
138
+ // (一条不支持等号形、`--help` 只有一条有、错误构造各写一遍)。位置参数语义(evolve 的
126
139
  // scan|apply 子命令与候选 id)与命令自有取值开关由调用方声明,本解析器不认识任何业务词元。
127
140
  // 契约要点:用法错误一律 throw(各命令顶层错误处理决定前缀,退出码统一 1);`--help` 在位置参数
128
141
  // 之前短路(子命令之后写 `--help` 也只看用法);取值开关悬空与未知参数一律可见报错,不静默忽略。
@@ -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) {
@@ -498,7 +672,7 @@ function fieldLine(key, value) {
498
672
 
499
673
  // 文件末尾追加「块」:`split('\n')` 对**以换行收尾**的文档留有一个零长度哨兵元素——它不是文档里的
500
674
  // 一行,而是「最后一行终结符」的占位。直接在哨兵之后 push 会拼出一条**裸 LF 空行**:CRLF 文档里
501
- // 同一文件出现两种行尾(评审实测 `-->\r\n\n\r\n---`),且末行终结符退化成一个孤立的 `\r`。
675
+ // 同一文件出现两种行尾(实测 `-->\r\n\n\r\n---`),且末行终结符退化成一个孤立的 `\r`。
502
676
  // 追加前摘下哨兵、追加后放回 —— 整篇行尾一致,末尾换行约定不变(LF 文档同样收敛为**单空行**)。
503
677
  function appendBlock(lines, eol, blockLines) {
504
678
  const sentinel = lines.length > 0 && lines[lines.length - 1] === '' ? lines.pop() : null;