flow-comet 1.6.1 → 1.6.3

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 (51) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +94 -46
  3. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +22 -30
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
  8. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
  9. package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
  10. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
  11. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
  12. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +260 -17
  13. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
  14. package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
  15. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
  16. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5432 -194
  17. package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
  18. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +51 -4
  19. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +68 -0
  20. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1479 -11
  21. package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
  22. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +197 -5
  23. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +115 -6
  24. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +261 -29
  25. package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
  26. package/.flow-comet/skills/flow-comet-change/SKILL.md +10 -1
  27. package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
  28. package/.flow-comet/skills/flow-comet-design/SKILL.md +8 -6
  29. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
  30. package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
  31. package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
  32. package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
  33. package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
  34. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  35. package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
  36. package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
  37. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
  38. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  39. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +29 -4
  40. package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
  41. package/README.md +5 -5
  42. package/package.json +1 -1
  43. package/scripts/dsh-bridge.mjs +59 -26
  44. package/scripts/prepare-env.mjs +165 -1
  45. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
  46. package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
  47. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
  48. package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
  49. package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
  50. package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
  51. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
@@ -1,26 +1,61 @@
1
1
  ---
2
2
  name: flow-comet-evolve
3
- description: "Use only when explicitly invoked as /flow-comet-evolve; scan archived changes' DESIGN.md section 9, batch-review sediment candidates, patch CONTEXT.md. Not part of the 8-node flow."
3
+ description: "Use only when explicitly invoked as /flow-comet-evolve; scan archived changes' DESIGN.md section 9 through the engine command, review sediment candidates one by one, then patch CONTEXT.md with the approved ones. Not part of the 8-node flow."
4
4
  ---
5
5
 
6
6
  # flow-comet-evolve(横向命令 · 架构沉淀)
7
7
 
8
8
  ## 触发
9
9
 
10
- 用户说「同步架构 / 整理沉淀 / evolve / 同步 CONTEXT」;若 STATE.md 的 last_evolve_at 已超过 60 天,则**提示用户显式调用 `/flow-comet-evolve`**,不自动加载本 Skill(时间戳是提醒,不是与用户意图并列的触发条件——本命令只按显式调用与用户意图触发)。
10
+ 用户说「同步架构 / 整理沉淀 / evolve / 同步 CONTEXT」。本命令**只按显式调用与用户意图触发**——到期提示是提醒,不是自动加载条件。
11
11
 
12
- > **载体说明(沿用 flow-kit 约定)**:`STATE.md` 与 `last_evolve_at` 是 flow-kit 的约定(A-evolve.md 定义:GO.md 按 last_evolve_at 提示、evolve 读/写该字段)——项目需有按 flow-kit 维护的 STATE.md;flow-comet 引擎不自动创建/维护该字段,无 STATE.md 的项目触发本命令时按「无 last_evolve_at 基线」处理(扫描全部未沉淀的归档 change 并人工确认)。
12
+ **覆盖声明(上游 vendored 只读)**:上游对应物 = `flow-kit/prompts/A-evolve.md`(只读基准,不修改)。**以下上游语义不采用**:① 载体 = 仓库根 `STATE.md` 的 `last_evolve_at` / `last_evolve_promoted` → 本仓载体 = **引擎 state**(`last_evolve_at`)+ `.specs/CONTEXT.md` 的 `## evolve 元数据` 段(本仓 `docs/internal/ARCHITECTURE.md` §六明确**不吸收** STATE.md 式跨会话状态跟踪);② 已扫 change 清单写回 `STATE.md` 数组 → 本仓写进 `.specs/evolve/<日期>-EVOLVE.md` 报告,**不进 state**。**沿用上游**:只扫 `DESIGN.md` §9、逐项人工确认、禁止批量 promote、报告落 `.specs/evolve/`、60 天 / ≥5 个带沉淀段 change 的建议阈值。`## evolve 元数据` 段的**段形权威 = `flow-kit/templates/CONTEXT.md`**(`## intel-scan 元数据` 为同源先例;校验实现在 `context-init.mjs`)。本命令语义与产物形态**以本节为准**。
13
+
14
+ **到期提示(引擎输出面)**:`node .claude/skills/flow-comet/scripts/workflow-state.mjs status` 在下列任一条件成立时输出一行 `EVOLVE-DUE:`(含上次沉淀时间、命中原因与「建议显式调用 evolve」指引):`last_evolve_at` 距今 > 60 天,或该时刻之后新增 ≥ 5 个带 `§9` 的归档 change。未达阈值**不输出**(零噪音);`last_evolve_at` 缺席(从未沉淀过)同样不提示——需要时手动跑本命令即可。
15
+
16
+ ## 时间戳载体:引擎 state(不使用 STATE.md)
17
+
18
+ - **唯一真相** = `.flow-comet/flow-comet-state.json` 的 `last_evolve_at`,形态为**本地时间 + 显式偏移**(`YYYY-MM-DDTHH:mm:ss±HH:mm`;历史 `Z` 形态仍可解析,比较一律按解析后的时刻差值)
19
+ - **写入通道唯一** = `node .claude/skills/flow-comet/scripts/workflow-state.mjs config set last_evolve_at <值>`(脚本不直写 state 文件)
20
+ - **双落点**:同批更新 `.specs/CONTEXT.md` 的 `## evolve 元数据` 段(`last_evolve_at` / `scanner` / `下次建议` 三字段,对齐 `## intel-scan 元数据` 的字段语义)。两处取值必须一致,**冲突以 state 为准**
21
+ - 旧项目若在 `STATE.md` 维护过该字段:以引擎 state 为准;首次运行按「无基线」全量扫描并建立新基线
13
22
 
14
23
  ## 流程
15
24
 
16
- 1. 扫 `STATE.md` last_evolve_at 之后归档的 change
17
- 2. 只读每个 change 的 DESIGN.md § 9(禁止越界读 § 9 以外)
18
- 3. 聚合候选 → 贴给用户 review
19
- 4. 用户批准的才 patch `.specs/CONTEXT.md`(术语 / 已锁决策 / 抽象索引)
20
- 5. 更新 STATE.md last_evolve_at
25
+ ### 1. 扫描(只读,工作区零改动)
26
+
27
+ ```
28
+ node .claude/skills/flow-comet/scripts/evolve.mjs scan --root .
29
+ ```
30
+
31
+ - 扫描范围 = `last_evolve_at` **之后归档**的 change(无基线 → 全部归档 change);归档时刻取归档目录名的日期前缀(随提交固化,跨 clone / 检出稳定)
32
+ - **只读**每个 `.specs/archive/<日期>-<change-id>/DESIGN.md` 的架构沉淀段(第 9 节)——**不读该文档的其它段**,防 change 级冻结决策被错误升级为项目级
33
+ - 输出候选清单:`<归档目录名>#<序号>` + 条目 + 目标文档;并列出本次已扫的 change(含无沉淀段、无 `DESIGN.md` 的目录),扫描范围对用户完全可见
34
+ - 候选落点按沉淀子段归类:可复用抽象 / 禁动清单 → `CONTEXT.md`「既有抽象索引」;项目级技术决策 → `CONTEXT.md`「已锁决策」;依赖 → `CONTEXT.md`「技术栈」;跨模块契约 → `ARCHITECTURE.md`「跨模块契约」(该文档不在场时需先建立,否则应用会被拒绝且零改动)
35
+
36
+ ### 2. 逐项 review(用户参与,不可跳过)
37
+
38
+ 把候选清单贴给用户,**逐条**确认:接受 / 跳过(记理由)/ 编辑后接受。**严禁**一次性把整批直接写入。与 `CONTEXT.md` 现有条目重叠的冲突项必须显式提问,不允许默默接受。
39
+
40
+ ### 3. 应用(只写批准的项)
41
+
42
+ ```
43
+ node .claude/skills/flow-comet/scripts/evolve.mjs apply <候选 id> [<候选 id> ...] --root . --scanner "<执行工具>"
44
+ ```
45
+
46
+ - 只 patch 批准的条目:写入前先备份目标文档(`.specs/CONTEXT.md.bak-<日期>`),只追加不删除既有内容,条目带来源标注(`来源 @.specs/archive/<目录>/DESIGN.md`)
47
+ - 重复应用同一条目按**幂等**处理(目标段已在场则不重复写入)
48
+ - 同批写双落点时间戳(`config set` 通道 + `## evolve 元数据` 段,取值一致)
49
+ - 落 `.specs/evolve/<日期>-EVOLVE.md` 报告:扫描范围 + 已扫 change 清单 + 候选处置 + 未应用项 + 双落点取值 + 下次建议
50
+ - 输出 `EVOLVE-OK` 才算应用成功;失败输出 `BLOCKED:` 原因且不留下半成品(文档写入与 state 写入同一命令内完成,失败可幂等重跑)
51
+
52
+ ### 4. 收尾
53
+
54
+ 把报告路径与写入清单交给用户复核;**未应用的候选**保留在报告里,可凭候选 id 继续 `apply`。下次建议时间 = 约 60 天后,或新增 ≥ 5 个带沉淀内容的 change 之后。
21
55
 
22
56
  ## 边界
23
57
 
24
- - 不写业务代码
25
- - 不在本工作流改架构(需 A-architect 时提示用户)
26
- - CONTEXT.md 更新统一走本命令或 I-intel-scan,不在 change 内直接改
58
+ - 不写业务代码;写入面只有项目级文档、`.specs/evolve/` 报告与 `last_evolve_at`
59
+ - **只读沉淀段**:扫描与解析都不触碰设计文档的其它段
60
+ - 只追加 / 更新,**不删除**既有内容;发现需要改架构(决策推翻 / ADR 弃用 / 依赖规则变更)→ 停下来提示用户走架构重审
61
+ - `CONTEXT.md` 的更新统一走本命令或 `context-scan`,不在 change 内直接改
@@ -11,7 +11,7 @@ Complete the `execute` Node for `flow-comet`.
11
11
 
12
12
  Responsibility: 按 TASK.md 逐任务执行(**执行模式按 executionMode**:subagent 默认统一委托子代理、direct 逃生口主代理直写)。串行任务的 TDD + 6 维自查 + LESSONS 扫描 + diff 边界 verify 由执行者承担,无论哪种模式都必须加载 flow-comet-dev 协议。
13
13
 
14
- In subagent mode (default) this node is a coordinator: it does not write implementation code directly — it delegates the pending serial tasks to fresh-context subagents via the Agent tool (worktree isolation), each subagent applies the full dev protocol (TDD RED/GREEN/REFACTOR, LESSONS scan, existing abstraction grep, self-review, diff boundary verification, atomic commits) and returns a Return Contract. 趟次协作:并行委托节点(subagent-execute)可多次往返——每趟委托全部依赖已满足的并行任务,本节点在趟间消化串行任务,直至两者清空。The coordinator records handoff evidence, verifies each SUMMARY, and marks tasks done in TASK.md. In direct mode (escape hatch, user-confirmed) the main agent implements serial tasks directly — see 执行模型 below.
14
+ In subagent mode (default) this node is a coordinator: it does not write implementation code directly — it delegates the pending serial tasks to fresh-context subagents (all three platforms delegate under one identity-based criterion; worktree isolation is one optional implementation of attribute ①, not a requirement — see the four-attribute contract below), each subagent applies the full dev protocol (TDD RED/GREEN/REFACTOR, LESSONS scan, existing abstraction grep, self-review, diff boundary verification, atomic commits) and returns a Return Contract. 趟次协作:并行委托节点(subagent-execute)可多次往返——每趟委托全部依赖已满足的并行任务,本节点在趟间消化串行任务,直至两者清空。The coordinator records handoff evidence, verifies each SUMMARY, and marks tasks done in TASK.md. In direct mode (escape hatch, user-confirmed) the main agent implements serial tasks directly — see 执行模型 below.
15
15
 
16
16
  ## Guidance
17
17
 
@@ -29,7 +29,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
29
29
 
30
30
  ### 执行模型(按 executionMode,用户显式选择)
31
31
 
32
- - **subagent(默认)**: 统一委托子代理——协调者流程(构造 handoff → Agent worktree 委托 → 收集 Return Contract → 验收标 done)
32
+ - **subagent(默认)**: 统一委托子代理——协调者流程(构造 handoff → 按平台通道委托(三平台同一身份判据;worktree 为属性①的可选实现)→ 收集 Return Contract → 验收标 done)
33
33
  - **direct(逃生口,需用户显式切换)**: 主代理直接执行串行任务——但必须加载 flow-comet-dev 完整协议
34
34
  (TDD/6 维自查/越界检查/原子 commit),SUMMARY 必填段 + `## 自检方法` 强制(guard 校验兜底)
35
35
  - 无论哪种模式:`parallel="true"` 任务始终由 subagent-execute 并行委托,不在此节点执行。
@@ -44,7 +44,9 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
44
44
 
45
45
  **TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须先经 review 流程追加到 `## Fix 任务` 段,再按下方「修复回路状态机路径」受控归位 execute,并由 entry execute 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
46
46
 
47
- 本节点**不直接写实现代码**。所有 pending 任务统一通过 Agent 工具委托 fresh-context 子代理执行(加载 flow-comet-dev + 回传 Return Contract)。
47
+ **任务集已修订 ⇒ 出口报「签名不匹配」时的合法出口**:**不要手改状态**——跑 `workflow-state.mjs replan "<原因>" --authorized-by <来源>` 重校重签(需用户显式授权;**要判定该不该重校、或签名不匹配要处置时读 `../flow-comet/reference/replan.md`**)。
48
+
49
+ 本节点**不直接写实现代码**。所有 pending 任务统一委托 fresh-context 子代理执行(加载 flow-comet-dev + 回传 Return Contract);委托通道按平台(差异只在谁建树),见下方「并行安全四属性契约」与 `../flow-comet/reference/platform-facts.md`(三平台通道对照表)。
48
50
 
49
51
  - `parallel="true"` 的 pending 任务由 subagent-execute 节点负责并行委托
50
52
  - execute 遍历 TASK.md 时,遇到 `parallel="true" status="pending"` 的任务块应**跳过**
@@ -52,7 +54,48 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
52
54
  1. 正常流程下 determineNode 的 路由逻辑会**直接路由到 subagent-execute**(无需经过 execute 空退出)——协调者确认 路由逻辑生效(`NODE: subagent-execute`)后直接进入该节点
53
55
  2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute 完成属越权委托——新 change BLOCKED(旧 change WARN 渐进)
54
56
  3. **显式空退出豁免(新 change 可用)**:确认全 parallel 无串行可做且无法路由时,用 `record execute '{"emptyExitApproved":true}'` 显式声明后 exit 通过(跳过串行 pending 与产物校验;防规划错误仍默认 BLOCKED——豁免须显式声明;exit 输出 EMPTY-EXIT 审计提示)
55
- - determineNode 路由逻辑会优先检测依赖已满足的 parallel 任务并路由到 subagent-execute;若 determineNode 路由到了 execute,说明当前趟存在需要 execute 处理的串行任务(此时应执行而非空退出)——串行消化完成后再次路由,剩余并行任务回到 subagent-execute 的下一趟(多趟循环直至无可并行 pending 且无串行残留)
57
+ - determineNode 路由逻辑会优先检测依赖已满足的 parallel 任务并路由到 subagent-execute;若 determineNode 路由到了 execute,说明当前趟存在需要 execute 处理的串行任务(此时应执行而非空退出——**除非已显式声明空退出豁免** `emptyExitApproved`,见上条第 3 项)——串行消化完成后再次路由,剩余并行任务回到 subagent-execute 的下一趟(多趟循环直至无可并行 pending 且无串行残留)
58
+
59
+ ### 并行安全四属性契约
60
+
61
+ > **并行安全四属性契约**:契约对象是**四属性**,不是 worktree——`worktree` 只是属性①「写权限」的**实现之一**,不是契约本身;「一律 worktree」的口号已作废(本仓决策:契约对象 = 四属性,worktree 降为实现之一)。三平台在同一判据下平行对等,**唯一差异是「谁建树」**。
62
+ >
63
+ > | # | 属性 | 含义 | 满足形态 |
64
+ > |---|------|------|----------|
65
+ > | ① | **写权限** | 每个写者必须有一条被守卫认可的写入通道 | **身份分派**(CC / Codex 载荷含 `agent_id` ⇒ 子代理语义;dsh 桥接以环境变量 `FLOW_COMET_AGENT_DEPTH` 透传正整数身份深度,**并同时注入桥接通道标记 `FLOW_COMET_AGENT_DEPTH_SOURCE`——守卫要求标记与深度同时在场才接受该通道**)——**worktree 只是本属性的实现之一**,不是必须;**最小保护集除外**:身份在场时 `.flow-comet/flow-comet-state.json` 与 `../flow-comet/reference/workflow-protocol.json` 仍受拦(三平台一致 BLOCKED) |
66
+ > | ② | **提交隔离** | 提交只含自己 `write_files` 的字面路径 | 提交面 pathspec 纪律五要素(见 Guidance 同名小节) |
67
+ > | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 新 change BLOCKED / 旧 change WARN;全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
68
+ > | ④ | **集成纪律** | 机制选择 / 顺序 / 审计 / 冲突处置四项均有明文规则 | 集成纪律四要素(见 Guidance 同名小节) |
69
+ >
70
+ > **写面含 gitignored 面的任务(四属性映射 · 与其他任务同一判据)**:任务 `write_files` 全为 gitignored 字面路径时,四属性的满足方式不变——① **写权限**仍走**身份通道**(载荷 `agent_id` / 环境变量身份深度 ⇒ 子代理语义放行,项目内任意路径可写(含 gitignored);gitignored 只是路径属性,不是通道差异);② **提交隔离**走既有 **`noCommit` 资格**(request 按 `.gitignore` 命中记 `noCommit:true` ⇒ 任务零提交,「提交只含自己 `write_files` 的字面路径」由**无提交**满足,不是放宽校验;资格 fail-closed:glob / `..` 越界 / 非 git 仓 / tracked 文件 / 链接逃逸一律不授予,result 时刻按同一判据重验,失败即撤销资格);③④ 与其他任务同形(同一时刻单写者 + 集成四要素)。**并行 × 零提交**因此合法:任务可标 `parallel="true"` 并被并行委派,出口校验按 request 的 `noCommit` 资格豁免缺 `commitHash`。
71
+ > **留痕的边界(诚实声明 · 与 `directOverride` / `completedChecks` / `reentryAuthorization` 同族)**:留痕记录的是「**发生过委派**」,**不是**对执行者身份的物理证明——`handoffRequests` / `handoffResult` 只证明协调者写下过 request 与 result 两条记录,不证明写入确实由子代理完成;与 `completedChecks` 只能记录声明、`directOverride` 只能记录授权、`reentryAuthorization` 只能记录授权源同理。声明与事实不符属流程违规,验收以 transcript 可见的委派触发为准。
72
+ >
73
+ > **平台事实(三平台通道 · 判级三态 · 实测与边界)**:要判定平台能力(能否并行委派 / 谁建树 / 写通道是什么)或引用判级口径时读 `../flow-comet/reference/platform-facts.md`——三平台通道对照表、判级三态(证实 / 推翻 / 未覆盖)与该次实测的限定边界原文在该文件,本册不复述。
74
+
75
+ ### 提交面 pathspec 纪律(要点 · 带适用条件)
76
+
77
+ **适用条件(先读)**:本条纪律适用于「**多个写者共享同一工作区**」形态——并发写者同处一个工作树(CC 非 worktree 委托 / Codex 共享工作区 / dsh 进程内子代理)。**各自独立工作区(worktree 等)内的局部 `reset` / `clean` 不在禁令内**;但只要本趟存在**任一**共享工作区的写者,本条即对整个并行趟生效。
78
+
79
+ 要点(五要素 + 并行波次附加两条):
80
+
81
+ 1. **`git add -- <自己字面路径>`** + **`git commit -- <同一路径>`**:逐条字面路径(取自本任务 `write_files`),两步路径集逐字一致——提交只含自己的文件;禁用 `.` / `-A` / `-u` 等宽泛形态。
82
+ 2. **锁失败重试**:并发提交撞 `index.lock` / `cannot lock ref` ⇒ **失败即重试**,不得因锁失败改用宽泛命令。
83
+ 3. **禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`**:并发写者共享**同一个索引与工作树**——宽泛命令有**并发索引竞态**(把同伴半成品纳入自己的提交),`stash` / `clean` / `reset` 更会破坏同伴的未提交工作。
84
+ 4. **并行波次禁用 `git commit --amend`**:共享工作区下 HEAD 会被并行写者推进;确需修正必须**先断言 `git rev-parse HEAD` 等于自己刚提交的哈希**,否则一律改用**新提交追加**。
85
+ 5. **误改后的自救通道**(第 3 条「禁 `reset`」的定向例外):断言 HEAD 后 `git reset --soft <自己的父提交>`(**只用 `--soft`**),再以 **pathspec** 重建自己的提交。
86
+
87
+ > **要判定提交边界、或撞上锁 / 误改要收拾时读 `../flow-comet/reference/commit-discipline.md`**——五要素与并行波次附加两条的完整判据(含实测依据)在该文件。
88
+
89
+ ### 集成纪律(要点)
90
+
91
+ 要点(四要素):
92
+
93
+ 1. **机制选择**:优先 **`git merge --no-ff`**(保留父子关系、可审计;comet 先例:集成用 `--no-ff`、交付用 `--ff-only`);冲突难解时**降级 `git cherry-pick` 并强制记因**(审计行写明降级原因)。
94
+ 2. **顺序(确定性规则)**:先按 `depends_on` 的**拓扑序**(被依赖者先入),同一拓扑层内按 **task id 升序**——**不得依赖书写顺序** / 提交到达顺序 / 完成先后等运行期不确定量。
95
+ 3. **审计留痕**:每次集成输出一行 `INTEGRATE: <task-id> <commitHash> → <集成提交>`(降级路径记降级原因),映射(task-id → commitHash → 集成提交)记入该趟流程记录(`<task-id>-SUMMARY.md` / handoff evidence 文本字段);**判级**:审计行是**执行纪律**(review 把关),本节点不声称存在机械门禁校验它。
96
+ 4. **冲突处置(两类分别动作)**:**机械冲突**(不改用户可见行为)执行者**可自行解决** + 必须跑**合并后验证**并在审计行记因;**语义冲突**(两侧对同一行为 / 契约 / 接口给出不同语义)**必须中止集成并上抛**(记 BLOCKED + 恢复指引,由协调者 / 用户裁决)——不得由执行者自行拍板。
97
+
98
+ > **要在集成前定规则、或遇冲突 / 降级要判定时读 `../flow-comet/reference/commit-discipline.md`**——四要素的完整判据与 comet 先例在该文件。
56
99
 
57
100
  ### Prerequisites
58
101
 
@@ -61,15 +104,16 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
61
104
  - `.specs/LESSONS.md` must exist (or be created from template if missing).
62
105
  - For frontend/UI tasks: `.specs/<change-id>/UI-DESIGN.md` must exist.
63
106
  - 若当前任务的 `<task-id>-PROGRESS.md`(位于 `.specs/<change>/`;与 Recovery 段及归档期 `*-PROGRESS.md` 扫描同口径)存在,必须先读取"已排除方案"段(R1.6 反重复),确认当前计划不在排除列表中。完成后删除该文件,有用信息迁移至 SUMMARY。
64
- - 委托前按 `reference/dirty-worktree.md` 检查脏工作树(`.specs/<change-id>/` 未提交工件会触发 entry execute 的 WORKTREE WARN;verify 前为自查建议,无 guard 检查)。
107
+ - 委托前按 `../flow-comet/reference/dirty-worktree.md` 检查脏工作树(`.specs/<change-id>/` 未提交工件会触发 entry execute 的 WORKTREE WARN;verify 前为自查建议,无 guard 检查)。
65
108
 
66
109
  ### Steps(subagent 模式 · 协调者流程,统一委托子代理)
67
110
 
68
111
  对 TASK.md 每个 pending 串行任务,协调者执行:
69
112
 
70
113
  1. **读 task 块,构造 handoff request**:读 `<task>` XML 块(`action` / `read_files` / `write_files` / `verify` / `done`)。若内容有歧义,停下询问——不要猜。构造 handoff request 内容:task 全文 + DESIGN §0/§0.5 + AC + read/write_files 边界。运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs request <task-id>` 记录。**委托即记 request**——直接记录 result 而无对应 request 时,write_files 允许列表为空会被 BLOCKED(新 change 强制委托边界),补 request 后再重录 result 即可(执行者实证)。
71
- 2. **委托子代理**:用 Agent 工具(`isolation: "worktree"`)委托 fresh-context 子代理。handoff prompt 强制协议:子代理用 **Skill 工具**加载 flow-comet-dev 并按 `flow-kit/prompts/4-dev.md` 协议执行(TDD RED/GREEN/REFACTOR、LESSONS 扫描、既有抽象 grep、verify、6 维自查、越界检查、原子 commit `<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁 change-id/日期作 scope;任务号放提交正文尾注 Task: <task-id>,change-id 不入标题)),按 `flow-kit/templates/SUMMARY.md` 模板写 `.specs/<change-id>/<task-id>-SUMMARY.md`(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段),回传 Return Contract(含 commitHash + greenEvidence + completedChecks + selfReview)。**SUMMARY 自引用 hash 注**:提交内容无法包含自身 hash——若子代理 amend 提交,SUMMARY 内记录的 commitHash 为 amend 前值属预期(文件集一致即可,以实际提交对象为准)。
114
+ 2. **委托子代理**:按平台通道委托 fresh-context 子代理(三平台同一身份判据,差异只在谁建树;`isolation: "worktree"` 是属性①的可选实现,非强制——见「并行安全四属性契约」)。handoff prompt 强制协议:子代理用 **Skill 工具**加载 flow-comet-dev 并按 `flow-kit/prompts/4-dev.md` 协议执行(TDD RED/GREEN/REFACTOR、LESSONS 扫描、既有抽象 grep、verify、6 维自查、越界检查、原子 commit `<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁 change-id/日期作 scope;任务号放提交正文尾注 Task: <task-id>,change-id 不入标题)),按 `flow-kit/templates/SUMMARY.md` 模板写 `.specs/<change-id>/<task-id>-SUMMARY.md`(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段),回传 Return Contract(含 commitHash + greenEvidence + completedChecks + selfReview)。**SUMMARY 自引用 hash 注**:提交内容无法包含自身 hash——若子代理 amend 提交,SUMMARY 内记录的 commitHash 为 amend 前值属预期(文件集一致即可,以实际提交对象为准)。
72
115
  **提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
116
+ **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit -- <同一路径>` 提交、锁失败重试、禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。**集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`、降级 `cherry-pick` 记因、顺序按 `depends_on` 拓扑序 + 同层 task id 升序、冲突按机械 / 语义两类分别处置。
73
117
  3. **记录 handoff result**:子代理回传后,运行 `node .claude/skills/flow-comet/scripts/workflow-handoff.mjs result <task-id> '<JSON>'` 记录(Return Contract 含 commitHash + greenEvidence + completedChecks + selfReview)。
74
118
  4. **验收 SUMMARY,TASK.md 标 done**:确认 SUMMARY 按 `flow-kit/templates/SUMMARY.md` 填写且**模板保真**(标题 `# SUMMARY:` / 首部 4 字段 / 段序一致)、含 `## 自检方法` 段(声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一)、verify 输出真实、6 维自查与越界检查有实质内容;通过后在 TASK.md 将任务标 `status="done"` 并加时间戳。
75
119
  5. **下一个 pending 任务**:重复步骤 1-4。
@@ -107,18 +151,16 @@ This node is truly done when:
107
151
 
108
152
  ## 修复回路状态机路径
109
153
 
110
- review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
154
+ review / verify 发现缺陷后的修复**必须回到 `execute` 节点生命周期内完成**,禁止驻留源节点「顺手修完」;路径要点(`<源节点>` = review 或 verify):
111
155
 
112
- 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
113
- 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
114
- 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
115
- 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
116
- - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
117
- 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
118
- - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
119
- 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
156
+ 1. **追加 Fix 任务**:写进 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
157
+ 2. **受控归位 execute**:`workflow-state next`(或 `workflow-guard entry execute`)⇒ 引擎把当前节点受控归位为 `execute`(`currentNode=execute`)并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `status` 确认 `stateCurrentNode` 已是 `execute` 再开工,未归位不得硬开工。
158
+ 3. **执行修复 + 跑 execute 四类出口**:按节点生命周期完成全部 Fix 任务(委托 / 直写规则不变)→ `record execute` → `exit execute --apply`——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**,任一缺失即 BLOCKED 并给恢复指引;`entry execute` 刷新并锁定追加后的任务集(**归位后不得再增删任务或改任务内容**);通过后引擎在二次完成时把当前节点推回源节点。
159
+ 4. **审计行三态**:真实 Fix 回炉保留 `FIX-BATCH: 回源节点 <源节点>`;正常多趟收尾(签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`;旧 state 缺闭合 / 修复证据输出 `RETURN: …(旧 state 缺闭合/修复证据,未分类)`——分类只改审计行文本,路由与 state 写入零变化(`RETURN:` 是审计行前缀,与子代理的 Return Contract 无关)。
160
+ 5. **回源节点跑出口**:回到源节点后 `next` 应输出 `NODE: review` / `NODE: verify`(不因产物已存在而跳过),随后 `entry <源节点>` → `exit <源节点> --apply`;通过后继续正常路由(必要时进入下一轮 Fix 闭环)。
161
+ 6. **禁止绕过**:不归位、顺手改完直接跑源节点 exit 收场、或手改 `.flow-comet/flow-comet-state.json` 一律 BLOCKED——不得用跳过归位 / 出口门禁的手段替代本路径。
120
162
 
121
- **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
163
+ > **要判定该不该开修复回路、要受控归位或受控重入、核对归档侧重入边界时读 `../flow-comet/reference/fix-loop.md`**——上述 6 步的完整判据 + 受控重入完整规格(archive 源:`workflow-state.mjs reenter <target> --authorized-by <source> --reason <text>`,每次需用户显式授权、每 change 上限 3 轮、自动落 state 备份、打印 `REENTRY` 审计行)+ 归档侧边界原文在该文件。
122
164
 
123
165
  ## Entry Check
124
166
 
@@ -1,31 +1,72 @@
1
1
  ---
2
2
  name: flow-comet-health
3
- description: "Use only when explicitly invoked as /flow-comet-health; periodic codebase health check: CONTEXT consistency, LESSONS scanning, tech-debt review, redundancy scan. Not part of the 8-node flow."
3
+ description: "Use only when explicitly invoked as /flow-comet-health; periodic codebase health check driven by a deterministic collector (CONTEXT consistency, LESSONS numbering continuity, tech-debt count, redundancy tool probe, git history) plus an optional brooks-lint supplement layer with explicit degradation notes. Not part of the 8-node flow."
4
4
  ---
5
5
 
6
6
  # flow-comet-health(横向命令 · 巡检)
7
7
 
8
8
  ## 触发
9
9
 
10
- 用户说「健康检查 / health / 体检 / 技术债扫描 / 巡检」。
10
+ 用户说「健康检查 / health / 体检 / 技术债扫描 / 巡检 / 代码库健康度」。
11
11
 
12
- ## 前置依赖
12
+ **只按显式调用触发**:本命令不属于 8 节点流程,不被节点路由进入,也不在流程里自动跑(路由里的到期提示指向的是架构沉淀命令,不是本命令)。
13
13
 
14
- - 装了 brooks-lint → 优先 `/brooks-health`(4 维综合体检;Codex 用 `$brooks-health`)
15
- - 未装 brooks-lint → 用内置巡检清单降级
14
+ **覆盖声明(上游 vendored 只读)**:上游对应物 = `flow-kit/prompts/M-health.md`(只读基准,不修改)。
15
+
16
+ **沿用上游**:① 不属于任何 change、不写 `CHANGE.md` / `REQUIREMENT.md`,直接产出健康报告;② 角色边界 = 只产报告 + 改造建议清单,不直接改代码;③ 报告落点 `.specs/health/<YYYY-MM-DD>-HEALTH.md`;④ 装了 `brooks-lint` 时走其体检并把结果并入报告(本仓作为**可选增补层**并入**同一份**报告并标注来源);⑤ 冗余巡检**优先用工具**(`jscpd` / `knip` / `vulture` 等)并在报告里记明工具落点;⑥ 报告含**技术债优先级(Pain × Spread)**维度。
17
+
18
+ **以下上游语义不采用**:① 由 agent 现场巡检产出定性结论 → 本仓改为**确定性收集器**(脚本采集可复现项,每项带计数与复现命令);② 自动改写 `.specs/CONTEXT.md` 技术债段 / 自动开 change → 本仓**只读**(仅写体检报告,不改 CONTEXT、不开 change);③ 无可选工具时以主观评分填空 → 本仓**显式降级声明**,不产出替代性评分;④ 未装工具时走「现场 grep 抓样」的低精度回退 → 本仓**直接记降级原因**,不产出替代性读数。
19
+
20
+ 本命令语义与报告形态**以本节为准**。
21
+
22
+ ## 分层结构(防「绿报告」)
23
+
24
+ 一份报告三层,落在同一个文件 `.specs/health/<日期>-HEALTH.md`:
25
+
26
+ | 层 | 内容 | 产出者 |
27
+ |---|---|---|
28
+ | 确定性层 | 项目上下文一致性 · 经验条目编号连续性 · 技术债表项数 · 冗余工具在场判定 · 版本历史统计 | `health.mjs`(逐项带计数与判据) |
29
+ | 增补层 | 代码体检工具的 4 维结果(代码质量 / 架构 / 技术债 / 测试质量) | agent:工具在场时执行体检技能,结果**并入同一份报告**并标注来源 |
30
+ | 降级声明 | 可选工具不在场的原因 + 判据说明 | `health.mjs`(每份报告都有) |
31
+
32
+ 判据只锚「**确定性层完整 + 降级声明可见**」:可选工具缺席不构成失败,但**不能**用主观评分去填它的空位。
16
33
 
17
34
  ## 流程
18
35
 
19
- 1. 读 `.specs/CONTEXT.md` + `.specs/LESSONS.md` + 最近 1 份 `.specs/health/*.md`(对比基线)
20
- 2. 抽样 5 个最近改动频繁的 src/ 模块 + 5 个测试文件 + 最近 30 天 git log
21
- 3. 检查:
22
- - CONTEXT 与代码一致性(既有抽象索引是否过期)
23
- - LESSONS 是否需新增 / superseded
24
- - 技术债项(Pain × Spread 优先级)
25
- - 冗余(死代码 / 重复实现)——提示走 jscpd / knip / vulture 工具级扫描
26
- 4. 产出 `.specs/health/<date>.md` 报告 + 更新 CONTEXT 技术债段
36
+ 1. 跑确定性收集器(命令路径以安装平台为准,下同):
37
+
38
+ ```bash
39
+ node .claude/skills/flow-comet/scripts/health.mjs --root . --stdout
40
+ ```
41
+
42
+ 落盘 `.specs/health/<日期>-HEALTH.md`;`--stdout` 打印与落盘**逐字节相同**的内容,便于两次运行对照。
43
+
44
+ 2. 看报告「增补层」的在场判定:
45
+ - **在场**:执行代码体检技能(`brooks-health`),把 4 维结果填进增补层的四个槽位,并在来源标注行写明命中落点;
46
+ - **不在场**:保留降级声明,不产出替代性评分——报告以确定性层为全部内容。用户要求定性判断时另走代码审查流程,不把主观分写进这份报告。
47
+
48
+ 3. 读「与上次对比」段:与最近一份**日期不同**的历史报告逐项对读数。首份报告会显式声明「无差异可比」,不是静默省略。
49
+
50
+ 4. 把需要动手的发现整理成改造建议清单交给用户(按优先级分组)。本命令不改代码;要落地时另开 change。
51
+
52
+ ## 复现性纪律
53
+
54
+ - 报告里每个机器可判项都带计数与判据;同一冻结树连续两次运行,除报告末尾「易变行声明」列出的差异集合(生成时刻行 / 最近 30 天统计行 / 跨日时的文件名与基线选择)外**逐字节一致**。
55
+ - 出现差异集合之外的差异 → 按缺陷处理:先 `git status` 确认是否有人在此期间改了树,再查收集器判据是否引入了环境依赖。
56
+ - 报告由脚本整份重写:agent 填进增补层的内容会在下次运行时被覆盖;需要长期留档时把报告复制到项目自己的归档位置。
57
+
58
+ ## 降级纪律(可选工具)
59
+
60
+ 可选工具(代码体检工具、字面重复块 / 未用导出 / 未用依赖 / 死代码扫描器)**不在依赖面**:缺席、不可用、版本不符,一律走「显式声明原因 + 只出确定性子集」。
61
+
62
+ - 报告「降级声明」段逐项写明缺席工具与探面(扫描器:`node_modules/.bin/` 与 `PATH`;代码体检工具另含用户级缓存 / 用户技能目录与项目内三平台技能目录)。
63
+ - 工具在场但运行未完成(版本差异 / 平台包装器限制 / 超时)同样记进该段——**不静默降级**,也不让命令失败。
64
+ - 要让某个维度从「未采集」变成「有读数」,装工具后重跑本命令即可:不需要改流程,也不需要改运行状态。
27
65
 
28
- ## 边界
66
+ ## 只读边界
29
67
 
30
- - 业务代码只读;写入仅限巡检报告(`.specs/health/<date>.md`)与 CONTEXT 技术债段——不自动改业务代码
31
- - 发现的冗余/债项排入 backlog,不在本命令内修
68
+ - **读**:`.specs/CONTEXT.md`、`.specs/LESSONS.md`、`.specs/health/*.md`(基线)、版本历史、可选工具的在场探测。
69
+ - **写**:只写 `.specs/health/<日期>-HEALTH.md` 一份报告。
70
+ - **不写运行状态**:不触碰 `.flow-comet/flow-comet-state.json`,本命令不新增任何状态字段(横向命令不进 change 生命周期)。
71
+ - **不改业务代码**,也不自动改写 `.specs/CONTEXT.md` / `.specs/LESSONS.md`:发现项只进报告与建议清单——就地改写会让「巡检」变成隐式写入通道。
72
+ - **不自动开 change**:是否立项由用户决定。
@@ -20,19 +20,22 @@ description: "flow-kit INTEGRATION 阶段协议:集成验证 + UAT + 失败诊
20
20
  3. **失败诊断**:root cause → fix-plan → 回到 execute 修复 → 重跑
21
21
  - **自动重试 ≤ 3 轮**(R2.6),超限暂停等人工决策
22
22
 
23
- ### LESSONS 提名(archive 前必跑)
23
+ ### LESSONS 提名(archive 前必跑 · 判据单一权威在本册)
24
24
 
25
- 扫描本次 change 的所有 `*-SUMMARY.md` 和遗留 `*-PROGRESS.md`,按提名条件筛选:
25
+ 扫描本次 change 的所有 `*-SUMMARY.md`(重点「决策与偏差」段)与遗留 `*-PROGRESS.md`(「已排除方案」段),按提名条件逐条筛选:
26
26
  - 调试/试错耗时 > 30 分钟 → 提名
27
- - 错因不限于本任务 → 提名
27
+ - 错因不限于本任务(其他任务也会撞上)→ 提名
28
28
  - 6 个月内有合理概率被再次尝试 → 提名
29
+ - 其余一律不提名(避免污染 `.specs/LESSONS.md`)
29
30
 
30
- 追加到 `.specs/LESSONS.md`,编号续 `L-NNN`。
31
+ 提名动作:新条目编号 = 当前最大编号 + 1(续 `L-NNN`),插入 `## 条目区` 末尾(文件内升序,继续现有编号)——**禁止文件尾追加与乱序插入**;同时扫既有 active 条目,被本次结论取代 / 废弃的更新其状态。**不归档** `.specs/LESSONS.md`(项目级常驻,跨 change 累积)。
32
+
33
+ > 本段是提名判据的**单一权威**(本册同时是 verify 与 archive 两节点的 Required Skill,判据必然在上下文里);各节点册的同口径表述一律**以本册为准**——同一口径多处表达必分叉。
31
34
 
32
35
  ### 归档(archive 阶段)
33
36
 
34
37
  1. `.specs/<change-id>/` → `.specs/archive/<YYYY-MM-DD>-<change-id>/`
35
- 2. `.specs/CHANGELOG.md` 表格顶部按日期倒序插入一行
38
+ 2. `.specs/CHANGELOG.md` 顶部按日期倒序插入一行——**跟随项目既有格式**(非表格格式同样在顶部插入,不强制转表格;guard 的倒序检测只针对表格格式行)——完整协议见 `flow-comet-archive` 册
36
39
  3. **不归档** `.specs/LESSONS.md`(项目级常驻)
37
40
  4. DESIGN.md § 9 架构沉淀建议留待 A-evolve 批量同步
38
41
 
@@ -134,10 +134,14 @@ Evidence: `intake-summary` (required)
134
134
 
135
135
  ## Evidence Record
136
136
 
137
+ Record the node after the artifacts exist and before running the exit (the exit validates the evidence is present). Ask the engine for this node's commands — the printed `record` command carries the platform-correct script path, so there is no copy here to drift:
138
+
137
139
  ```bash
138
- node .claude/skills/flow-comet/scripts/workflow-state.mjs record open '{"summary":"CHANGE.md + REQUIREMENT.md generated, user confirmed"}'
140
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs explain open
139
141
  ```
140
142
 
143
+ A good `summary` names what was produced, for example `CHANGE.md + REQUIREMENT.md generated, user confirmed`.
144
+
141
145
  ## Guardrails
142
146
 
143
147
  | Guardrail ID | Label | Validation Type |
@@ -17,7 +17,7 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
17
17
 
18
18
  | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
19
19
  |------|-------------------------------|-----------------------------------|
20
- | TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 | `id` / `name` / `read_files` / `write_files` / `action` / `done` 等字段(执行纪律,review 把关) |
20
+ | TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 + 新格式任务的 7 字段在场(集合见本册 `SKILL.md`「必填段清单」表行;单一权威 = `workflow-guard.mjs` 的 `TASK7_REQUIRED` 常量,本文不复述集合) | 任务规模 / 粒度 / 字段内容质量(模板要求,guard 不拦)——**填得好不好**由 review 把关;`id` 是 `<task>` 元素的属性(不是字段:`<task id="T01" parallel="true" status="pending">`) |
21
21
 
22
22
  guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
23
23
 
@@ -19,9 +19,9 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
19
19
 
20
20
  | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
21
21
  |------|-------------------------------|-----------------------------------|
22
- | TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 | `id` / `name` / `read_files` / `write_files` / `action` / `done` 等字段(执行纪律,review 把关) |
22
+ | TASK.md | 至少一个 `<task>` 块 + 每个任务含 `<verify>` 字段 + 新格式任务的 7 字段在场(`name` / `read_files` / `write_files` / `action` / `verify` / `done` / `depends_on`) | 任务规模 / 粒度 / 字段内容质量(模板要求,guard 不拦)——**填得好不好**由 review 把关 |
23
23
 
24
- guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
24
+ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结构、每任务 `<verify>`、**新格式任务的 7 字段在场**都由 guard 拦(新 change 缺任一 = 出口 BLOCKED;旧格式模板 / 旧 change 渐进 WARN);「填得好不好」——字段内容质量与任务粒度——由 review 把关。
25
25
 
26
26
  > **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
27
27
 
@@ -31,7 +31,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
31
31
 
32
32
  **约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on`,合法性只取决于依赖图本身:`depends_on` 无环且引用的任务都存在,规划即合法。全并行、全串行、串→并、并→串四种基本形态与任意混排序列(如 `S→P→S`、`P→S→P`)一律放行——引擎按依赖拓扑自动分趟(每趟委托全部依赖已满足的并行任务,趟间回串行消化),混排序列由多趟路由按依赖拓扑自动分趟消化,并行任务的先后位置不受任何限制。
33
33
 
34
- **唯一硬性拦截:依赖环与缺失依赖**。任务间依赖不得成环(如 A→B→A),`depends_on` 也不得引用不存在的任务 id 或构成不可满足的依赖链;只有这两类依赖图缺陷会在规划出口被 BLOCKED 并附恢复指引——按提示调整涉环任务的 `depends_on` 后重新 exit 即可通过。
34
+ **硬性拦截(规划出口 BLOCKED,附恢复指引)**:任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见上表;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)——任一项不成立即在规划出口被 BLOCKED(读写重叠仅 WARN),按提示修正后重新 exit 即可通过。任务间依赖不得成环(如 A→B→A),也不得构成不可满足的依赖链。
35
35
 
36
36
  **警示**:落笔时先画依赖方向再标 [P],避免出口返工。
37
37
 
@@ -42,6 +42,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
42
42
  - **① 同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务。
43
43
  - **② [P] 只给本波确有并发同伴的任务**:`parallel="true"` 仅适用于同波确有其他可并行同伴、且 write_files 互不重叠的任务;孤立任务一律串行——「互不冲突」只是必要条件,不等于应标 `[P]`。
44
44
  - **③ [P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行**串行任务**的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口。共享工作区下以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为并行子代理的相互隔离纪律。
45
+ - **④ 四属性可满足(并行安全的契约对象)**:标 `[P]` 前确认**并行安全四属性**(① 写权限 · ② 提交隔离 · ③ 验证隔离 · ④ 集成纪律)都能满足——worktree 只是「① 写权限」的实现之一,**不是** `[P]` 的前提。四属性的**含义与三平台通道**以入口册「并行委派契约(四属性)· 三平台通道」为单一来源,本节只点名不复述(同一口径两处表达必分叉)。
45
46
 
46
47
  **上游语义显式覆盖**:flow-kit 上游(`flow-kit/prompts/3-task.md` 等 vendored 只读文件)的宽松语义——「无冲突即可标 [P]」「同层即同波并行」——以本节为准(显式覆盖;上游只读,不做修改)。
47
48
 
@@ -69,12 +70,11 @@ This node decomposes the technical design into atomic, executable tasks with cle
69
70
 
70
71
  3. **Decompose by file conflict (vertical slices)**: Split tasks by file conflict, NOT by horizontal layers. Each task should be a vertical slice (one feature through model/API/UI) not a horizontal layer (all models first, then all APIs). Target: 2-10 minutes per task in fresh context. Do not split one file across tasks; if unavoidable, declare explicit order and reason.
71
72
 
72
- 4. **Mark parallel tasks with [P]**: only tasks with a genuine concurrent companion in the same wave and non-overlapping write_files get `parallel="true"`; isolated tasks are serial; under direct mode `[P]` tasks are still delegated at subagent-execute.
73
+ 4. **Mark parallel tasks with [P]**: only tasks with a genuine concurrent companion in the same wave and non-overlapping write_files get `parallel="true"`; isolated tasks are serial; under direct mode `[P]` tasks are still delegated at subagent-execute. Each `[P]` task must also satisfy the four parallel-safety properties (write permission / commit isolation / verification isolation / integration discipline) — the contract object, with worktree as but one implementation of write permission and never a precondition; the entry SKILL's contract section is the single source for the per-platform channel facts.
73
74
 
74
75
  5. **Declare depends_on**: Each task explicitly declares which tasks it depends on.
75
76
 
76
- 6. **Populate 7 required fields per task**:
77
- - `id`: Format T01, T02, T02-1 etc. Continuous numbering.
77
+ 6. **Populate 7 required fields per task** — `name` / `read_files` / `write_files` / `action` / `verify` / `done` / `depends_on` (the exact set the plan exit gate enforces). `id` is **not** one of the seven fields: it is an attribute of the `<task>` element (`<task id="T01" parallel="true" status="pending">`) — format T01, T02, T02-1 etc., continuous numbering. `depends_on` is a field, and its element must be present (write an empty element when the task has no dependency):
78
78
  - `name`: One sentence.
79
79
  - `read_files`: Files the task is allowed to read. Must include reuse targets from DESIGN 0.5. Supports glob patterns.
80
80
  - `write_files`: Files the task is allowed to create/modify/delete. Must NOT include forbidden modules from DESIGN 0.5. Strictly controlled.
@@ -97,7 +97,7 @@ The full task decomposition protocol, XML template, and constraints are in:
97
97
 
98
98
  This node is truly done when:
99
99
  - `.specs/<change-id>/TASK.md` exists in XML format.
100
- - At least one `<task>` block exists; every task carries a `<verify>` field (the full seven-field shape — id/name/read_files/write_files/action/verify/done — is the execution discipline, review-checked; guard enforces the subset).
100
+ - At least one `<task>` block exists; every task carries a `<verify>` field, and the 7-field set `name` / `read_files` / `write_files` / `action` / `verify` / `done` / `depends_on` is present (`id` is an **attribute** of the `<task>` element, not a field) — field **presence** is enforced by the guard (missing any field on a new-format task in a new change = exit BLOCKED; old-format templates / old changes degrade to WARN), while **field content quality** is judged by review.
101
101
  - Every `verify` field is an executable command (not a description).
102
102
  - Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
103
103
  - Every `[P]` mark has a genuine concurrent companion in its wave with non-overlapping `write_files`; isolated tasks are serial (a fully serial plan is valid when no genuine companion exists).
@@ -160,7 +160,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record plan '{"summary
160
160
  | Guardrail ID | Label | Validation Type |
161
161
  |--------------|-------|-----------------|
162
162
  | `plan-artifacts` | TASK.md exists with XML tasks | artifact-exists |
163
- | `task-fields-complete` | All tasks have 7 required fields | 执行纪律(review 把关),guard 不校验 |
163
+ | `task-fields-complete` | All tasks have 7 required fields | 结构在场(新格式任务缺任一字段 = 出口 BLOCKED;旧格式模板 / 旧 change 渐进 WARN)——**字段内容质量**由 review 把关 |
164
164
  | `write-files-safe` | No write_files in DESIGN forbidden list | 执行纪律(review 把关),guard 不校验 |
165
165
  | `has-parallel` | At least 1 [P] task (if applicable) | 执行纪律(review 把关),guard 不校验 |
166
166
 
@@ -128,18 +128,15 @@ This node is truly done when:
128
128
 
129
129
  ## 修复回路状态机路径
130
130
 
131
- review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
132
-
133
- 1. **追加 Fix 任务**:在 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内追加编号修复任务(完整任务字段),**禁止文件尾追加**;任务集修订必须在 `entry` 之前完成。
134
- 2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
135
- 3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
136
- 4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
137
- - **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
138
- 5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
139
- - **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
140
- 6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
141
-
142
- **由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
131
+ review 发现 Critical / Major 后的修复必须回到 `execute` 节点生命周期内完成——**禁止驻留源节点「顺手修完」**(会被 BLOCKED)。要点:
132
+
133
+ 1. **追加 Fix 任务**:把修复任务(完整任务字段)追加到 `.specs/<change-id>/TASK.md` 的 `## Fix 任务` 段内,**禁止文件尾追加**;任务集修订须在 `entry` 之前完成。
134
+ 2. **受控归位 execute**:跑 `workflow-state next` 或 `workflow-guard entry execute` 触发受控归位(审计行 `FIX-BATCH: 归位`;`next` 同时输出 `NODE: execute`);用 `status` 确认 `stateCurrentNode` 已是 `execute` 再开工,未归位不得硬开工。
135
+ 3. **跑完 execute 四类出口**:`record execute` → `exit execute --apply`——全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致,任一缺失即 BLOCKED;通过后引擎把当前节点推回 review。
136
+ 4. **回源节点跑出口**:回到源节点后跑该节点出口门禁(`entry <源节点>` → `exit <源节点> --apply`),通过后继续 review → verify 的正常路由,必要时进入下一轮 Fix 闭环。
137
+ 5. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
138
+
139
+ **何时读完整规格**:要核对完整判据——Fix 任务与任务集签名的时序、受控归位的完整判定条件、`FIX-BATCH` / `RETURN` 审计行三态语义与回源节点的回程豁免、绕过的失败面与恢复指引——读 `../flow-comet/reference/fix-loop.md`(**当你 review 发现缺陷、要开修复回路把工作退回 execute 生命周期时读它**)。
143
140
 
144
141
  ## Entry Check
145
142