flow-comet 1.6.4 → 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 (64) 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/evolve.mjs +174 -0
  8. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +3 -1
  9. package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
  10. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +41 -18
  11. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +16 -16
  12. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
  13. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +9 -7
  14. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +2 -2
  15. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +17 -13
  16. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +154 -0
  17. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +406 -0
  18. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +206 -3
  19. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +458 -60
  20. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +38 -58
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +642 -230
  22. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +85 -14
  23. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +43 -5
  24. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +15 -1
  25. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +18 -1
  26. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +60 -0
  27. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +73 -9
  28. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +21 -1
  29. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +9 -0
  30. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +212 -0
  31. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +15 -5
  32. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +4 -4
  33. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +20 -10
  34. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +4 -1
  35. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +6 -6
  36. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +13 -5
  37. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2125 -0
  38. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
  39. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +74 -2
  40. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  41. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  42. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  43. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  44. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  45. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  46. package/.flow-comet/skills/flow-comet-execute/SKILL.md +13 -10
  47. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  48. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  49. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  50. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  51. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  52. package/.flow-comet/skills/flow-comet-plan/SKILL.md +11 -7
  53. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  54. package/.flow-comet/skills/flow-comet-review/SKILL.md +15 -9
  55. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  56. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +11 -8
  57. package/.flow-comet/skills/flow-comet-task/SKILL.md +1 -1
  58. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  59. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  60. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  61. package/README.md +3 -3
  62. package/package.json +1 -1
  63. package/scripts/dsh-bridge.mjs +2 -2
  64. package/scripts/lib/installer-flowkit.mjs +43 -3
@@ -17,9 +17,19 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
17
17
 
18
18
  ### 必填段清单(结构+存在级)
19
19
 
20
- | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
21
- |------|-------------------------------|-----------------------------------|
22
- | SUMMARY.md | `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 自检方法` | `## 做了什么` / `## 改动文件` 等(执行纪律,review 把关) |
20
+ 段形唯一权威 = `flow-kit/templates/SUMMARY.md` + 登记表 `../flow-comet/reference/artifact-templates.json`(模板缺席时出口输出「未校验(模板缺失)」)。
21
+
22
+ | 文件 | 无条件段(缺席 = BLOCKED) | 条件段与增量段(在场才校验 / 位置按登记表) |
23
+ |------|---------------------------|-------------------------------------------|
24
+ | SUMMARY.md | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 是否触发新工作` / `## 完成判定` | 条件段:`## 数据库迁移`(涉 schema 变更)/ `## 破坏性变更` / `## 决策与偏离`——标题必须在场,不涉及时写「不适用」;增量段:`## 自检方法`(紧随 `## 越界检查` 或位于骨架段之后,须声明自检方法名)与 `## LESSONS 扫描`(紧随自检方法之后或文末,逐条回应命中的 `L-NNN`),两者均必填 |
25
+
26
+ 声明本次读到的模板:
27
+
28
+ ```bash
29
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-subagent-execute --prompt flow-kit/prompts/4-dev.md --templates SUMMARY.md
30
+ ```
31
+
32
+ 加载顺序:先 `READ PROMPT:`(步骤权威),有模板的节点再 `READ TEMPLATE:`(段形权威);design 前端另有一行条件提示词 `2a-ui-design`。
23
33
 
24
34
  guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
25
35
 
@@ -37,19 +37,21 @@ Responsibility: 委托 [P] 并行任务给子代理,要求加载 flow-comet-de
37
37
 
38
38
  ### 必填段清单(结构+存在级)
39
39
 
40
- | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
41
- |------|-------------------------------|-----------------------------------|
42
- | SUMMARY.md | `## verify 输出` / `## 6 维自查`(须含实质内容)/ `## 越界检查` / `## 自检方法` | `## 做了什么` / `## 改动文件` 等(执行纪律,review 把关) |
40
+ | 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
41
+ |------|------|------|
42
+ | `SUMMARY.md` | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出(必填)` / `## 6 维自查`(须含实质内容)/ `## 越界检查(必填)` / `## 是否触发新工作` / `## 完成判定`;首部四字段 `Change ID` / `Task ID` / `完成时间` / `AI 角色` 必填 | **条件段**:`## 数据库迁移(涉及 schema 变更必填)` / `## 破坏性变更(涉及破坏性改动必填)` / `## 决策与偏离(如有)`——标题必须在场,不适用写 `N/A`;**增量段**:`## 自检方法`(整段必填,紧随 `## 越界检查` 或文末)、`## LESSONS 扫描`(整段必填,紧随 `## 自检方法`) |
43
43
 
44
- > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 段**——该段是 flow-comet 的强制增量(guard 校验自检方法声明)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方必填段清单补写 `## 自检方法` 段**,否则新 change 的 exit 会被 BLOCKED。
44
+ > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**,否则新 change 的 exit 会被 BLOCKED。
45
45
  >
46
46
  > **无 parallel 任务时**:若路由到此节点但 TASK.md 无 `parallel="true" status="pending"` 任务(如全部任务已被 execute 串行处理),按常规流程记录证据后直接退出(entry → record → exit),不要空转等待。
47
47
 
48
48
  加载声明(阶段层 · 双步硬规则)见下文 Required Skill Calls 节。
49
49
 
50
- guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
50
+ guard 校验见 workflow-guard.mjs 的委托出口门禁(必填段 + 6 维自查实质内容 + 自检方法声明三值 + LESSONS 扫描段与命中核对)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 把关。
51
51
 
52
- > **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
52
+ > **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
53
+
54
+ 加载顺序:先读 `READ PROMPT:`(`4-dev`),再读 `READ TEMPLATE:`(`SUMMARY`)。
53
55
 
54
56
  # Subagent Execute
55
57
 
@@ -129,6 +131,7 @@ Division of labor (pass-based collaboration): this node handles parallel delegat
129
131
  - Explicit requirement to return `completedChecks` in the Return Contract containing `required-skill:subagent-execute.flow-comet-dev`(证明已加载 implementation skill;guard W1-D 严格校验,缺失 → exit BLOCKED,无旧 change 豁免)。Skill 工具不可用而走降级时该条目标记仍按契约回传,但必须与 `skillToolFallback` 降级声明并排出现——只回传标记而无声明视为不实声明,orchestrator 不得记录 result。
130
132
  - The task's `read_files` and `write_files` boundaries.
131
133
  - Instruction to produce `<task-id>-SUMMARY.md` in `.specs/<change-id>/` following the `flow-kit/templates/SUMMARY.md` template(标题/首部/段序保真,另补 flow-comet 增量 `## 自检方法` 段)。
134
+ - **写前读模板(固定句式)**:「开工前先读 <本任务产出物的模板路径>,按其标题 / 首部 / 段序填写,并按本仓登记补写增量段」——模板路径逐任务给出(本节点默认 `flow-kit/templates/SUMMARY.md`);只写「按模板填写」视为委托前检查未完成。
132
135
  - **提交边界警告**:提交**只含该任务 write_files 范围内的文件**(含测试文件)——不得包含 TASK.md 与其他协调者维护的 .specs 工件(新 change 提交越界 BLOCKED;实测子代理提交含 TASK.md 被 W2-D 拦截)。**提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
133
136
 
134
137
  - **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:子代理必须用 `git add -- <自己字面路径>` + `git commit -- <同一路径>`,锁失败重试,禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。
@@ -218,10 +221,10 @@ The subagent-execute node identifies all `parallel="true"` pending tasks in TASK
218
221
  **加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
219
222
 
220
223
  1. **用 Skill 工具加载** `flow-comet-dev`。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让 flow-comet-dev 指令生效的是 Skill 工具把它注入本次会话。本节点的 flow-comet-dev 为 handoff scope——协调者在此声明(声明标记的自动补写不覆盖 handoff scope,必须手动声明),各子代理在各自会话按 `flow-kit/prompts/4-dev.md` 协议用 Skill 工具加载并执行;协调者构造 handoff prompt 时按 `flow-kit/prompts/4-dev.md` + `flow-kit/templates/SUMMARY.md` 引用子代理的 dev 协议与交付模板。
221
- 2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
224
+ 2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板(subagent-execute → `SUMMARY.md`):
222
225
 
223
226
  ```bash
224
- node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-dev --prompt flow-kit/prompts/4-dev.md
227
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load subagent-execute flow-comet-dev --prompt flow-kit/prompts/4-dev.md --templates SUMMARY.md
225
228
  ```
226
229
 
227
230
  > **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。
@@ -7,7 +7,7 @@ description: "flow-kit TASK 阶段协议:拆原子任务(XML 格式)、rea
7
7
 
8
8
  本 Skill 为 flow-comet 的 plan 节点提供 flow-kit 的 TASK 拆解流程。
9
9
 
10
- > **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
10
+ > **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
11
11
 
12
12
  ## 加载
13
13
 
@@ -7,12 +7,16 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
7
7
 
8
8
  本 Skill 为 flow-comet 的 review 节点提供 flow-kit 的 5 轮测试金字塔。
9
9
 
10
- > **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
10
+ > **模板权威**:本技能产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
11
11
 
12
12
  ## 加载
13
13
 
14
14
  读取 `flow-kit/prompts/5-test.md` 并按其执行。
15
15
 
16
+ ## 上游段表不采用(覆盖声明)
17
+
18
+ `flow-kit/prompts/5-test.md` 把「本次测试范围声明」写成职责小节里的一个 H2,且其 H3 编号与模板错位(例:1.3 覆盖率与边界、1.4 测试质量自检、2.2 前端性能、4.2 数据迁移、5.2 指标与追踪、5.3 告警与健康检查)——**这组 H3 编号不采用**:H2 / H3 的段名与段序一律以 `flow-kit/templates/TEST.md` 为准(`第 2 轮` ~ `第 5 轮` 是标题必须在场的条件段,不适用写 `N/A`)。
19
+
16
20
  ### 5 轮测试金字塔
17
21
 
18
22
  | 轮次 | 内容 | 适用性 |
@@ -40,4 +44,4 @@ description: "flow-kit TEST 阶段协议:5 轮测试金字塔(功能/性能/
40
44
 
41
45
  ## 使用范围
42
46
 
43
- TEST.md 的完整性由 review 节点第 2 轮检查。brooks-lint 已装时用 `/brooks-test`(Codex 用 `$brooks-test`),未装时用内置清单。
47
+ TEST.md 的**结构在场**由 **verify 出口**按登记表骨架校验(5 轮 H2 与结构子段,条件轮写 `N/A` 放行);**5 轮内容质量**由 review 节点第 2 轮检查(`### 2.0 TEST.md 5 轮金字塔完整性` 小节)。brooks-lint 已装时用 `/brooks-test`(Codex 用 `$brooks-test`),未装时用内置清单。
@@ -29,7 +29,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
29
29
  |---|---|---|
30
30
  | 段在场,段内出现**结构形态**的「不适用」标记 | 非前端 change | **显式跳过**:不加载、不产出;design 出口打印 `UI-DESIGN: skipped(非前端)` 与命中片段后放行 |
31
31
  | 段在场,无**结构形态**的「不适用」标记 | 前端 change | 必须加载本技能并产出 `.specs/<change-id>/UI-DESIGN.md` |
32
- | 段缺席 | 非前端 change | 同上按非前端处理——但缺席不留可读证据,故约定保留段并以结构形态标注「不适用」(见 `flow-comet-change` 的标记约定) |
32
+ | 段缺席 | **新 change:拦**(条件段标题必须在场——缺席即 BLOCKED,须显式标注「不适用」或填写调性)· **旧 change:兼容**(沿用旧口径判非前端,出口打印 `UI-DESIGN: skipped(旧 change 兼容)`) | 新 change 先回 open 补段;旧 change 保持原行为,不追溯 |
33
33
 
34
34
  **「结构形态」的三种任一**(与引擎判据同口径):标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、行尾,或下列标点之一:`,。;、,;.::!!??…—()()【】「」『』“”"'`——**只有这一组**,组外的标点如 `/`、`-` 不算边界),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
35
35
 
@@ -42,7 +42,7 @@ description: "flow-kit 2a UI-DESIGN 阶段协议:美学方向 + design tokens
42
42
  `design` 节点对本技能的绑定等级 = **guarded**(见 `../flow-comet/reference/workflow-protocol.json` 的 `requiredSkillCalls`)。前端 change 的完整动作是**先加载、再声明、后干活**:
43
43
 
44
44
  1. 用 Skill 工具加载本技能(只读取 SKILL.md 文件不叫加载);
45
- 2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md`;
45
+ 2. 立即声明已加载:`node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md --templates DESIGN.md`(`--templates` 声明 design 节点的产出物模板;前端要一并声明 UI-DESIGN 时写 `--templates DESIGN.md,UI-DESIGN.md`);
46
46
  3. 把 `required-skill:design.flow-comet-ui-design` 记进 design 节点的 evidence(`record` / handoff 载荷)。
47
47
 
48
48
  design 出口的核对口径:
@@ -17,16 +17,18 @@ This node performs the final integration verification: running all automated tes
17
17
 
18
18
  ### 必填段清单(结构+存在级)
19
19
 
20
- | 文件 | guard 强制段(缺失 = BLOCKED) | 其余模板段(模板要求,guard 不拦) |
21
- |------|-------------------------------|-----------------------------------|
22
- | TEST.md | `## 验证命令`(exit verify 真实执行) | `## 测试矩阵` 等段(5 轮金字塔,review 把关) |
23
- | UAT.md | `## 验收结果` | 其余(执行纪律,review 把关) |
20
+ | 文件(模板 = `flow-kit/templates/<DOC>.md`) | 左栏 · 无条件段(模板 H2,缺席 / 空正文 = BLOCKED) | 右栏 · 条件段(**标题必须在场**,正文可写 `N/A`)/ 增量段(按登记位置) |
21
+ |------|------|------|
22
+ | `TEST.md` | `## 验证命令`(本仓登记的**增量段**,必填,位置不限但标题后必须紧跟代码块)——exit verify 真实执行其中的命令并计数失败 | `TEST.md` 的 5 轮 H2 与结构子段**在本出口**按登记表骨架校验(`flowkit.verify.v1` 的 artifacts 含 TEST.md;UAT 未登记 → 跳过)。verify 的**模板声明**为空集,但结构校验来自节点 `outputSchemas`,不来自模板声明 |
23
+ | `UAT.md` | **仅存在性**——guard 只查 `.specs/<change-id>/UAT.md` 在场(UAT 无上游模板,不校验段名与段序) | `## 验收结果` 等段:格式与内容由 UAT 执行与 review 把关,guard 不判段名 |
24
24
 
25
- > **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet 的强制增量(exit verify 会真实执行其中的命令并计数失败)。使用 `flow-kit/templates/TEST.md` 填写后,**必须按上方必填段清单补写 `## 验证命令` 段**,否则 exit verify 会被 BLOCKED。**排版约束**:`## 验证命令` 标题后必须**紧跟**代码块(` ``` `),标题与代码块之间**不得插入任何说明行**(如 blockquote 说明——guard 正则要求标题后直接是代码块);段名可带括号后缀。UAT.md 同理:flow-kit 无独立 UAT 模板(UAT 脚本格式见 5-test.md 1.2 节),产出时按上方必填段清单写 `## 验收结果` 段。
25
+ > **注意**:flow-kit 的 TEST 模板**不含 `## 验证命令` 段**——该段是 flow-comet 登记的增量段(exit verify 会真实执行其中的命令并计数失败)。使用 `flow-kit/templates/TEST.md` 填写后,**必须按上方右栏补写 `## 验证命令` 段**,否则 exit verify 会被 BLOCKED。**排版约束**:`## 验证命令` 标题后必须**紧跟**代码块(` ``` `),标题与代码块之间**不得插入任何说明行**(如 blockquote 说明——guard 正则要求标题后直接是代码块);段名可带括号后缀。UAT.md 同理:flow-kit 无独立 UAT 模板(UAT 脚本格式见 5-test.md 1.2 节),本出口只查文件在场——`## 验收结果` 段按惯例填写,格式由 UAT 执行与 review 把关。
26
26
 
27
- guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
27
+ guard 校验见 workflow-guard.mjs 的 verify 出口门禁(`## 验证命令` 增量段真实执行 + 失败计数 + LESSONS 条目形态与条目区);UAT.md 只查存在性,「填得好不好」由 review 与 UAT 执行把关。
28
28
 
29
- > **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
29
+ > **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
30
+
31
+ 本节点零模板:只有 `READ PROMPT:`(`7-integration`),没有 `READ TEMPLATE:`。
30
32
 
31
33
  ### Prerequisites
32
34
 
@@ -120,6 +122,8 @@ Load `flow-comet-integration` during this Node and record completed check `requi
120
122
  node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load verify flow-comet-integration --prompt flow-kit/prompts/7-integration.md
121
123
  ```
122
124
 
125
+ > **零模板节点省略 `--templates`**:verify 的产出物模板映射为空(UAT.md 无上游模板;TEST.md 的结构校验在 verify 出口(本节点),review 只做 5 轮完整性过程检查),命令**不带** `--templates`——省略即视为空集,与节点映射一致并通过;不要「为保险」补一个模板名(多写会与映射不一致而被拦)。
126
+
123
127
  > **跑 skill-load 声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做。
124
128
 
125
129
  ## Augmentations
@@ -151,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record verify '{"summa
151
155
  | `verify-evidence` | UAT.md exists | artifact-exists |
152
156
  | `automation-passed` | All automated checks pass (real output) | 执行纪律(review 把关),guard 不校验 |
153
157
  | `retry-limit` | No more than 3 auto-retries(机器计数 verifyFailures,第 4 次 BLOCKED) | process-check |
154
- | `lessons-nominated` | LESSONS.md updated with new entries(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 执行纪律(review 把关),guard 不校验 |
158
+ | `lessons-nominated` | LESSONS.md 条目形态与条目区合规(完成提名扫描;仅当有合格条目时更新——无合格条目不强制新增,避免噪音条目) | 结构级(guard 强制:本出口校验 `.specs/LESSONS.md` 的条目写 `### L-NNN`、位于条目区、编号升序——新 change 违反即 BLOCKED,旧 change WARN);「是否有合格条目」由执行者把关,归档时另以 `evidence.lessonsNomination` 核对 |
155
159
 
156
160
  ## Exit Check
157
161
 
package/README.md CHANGED
@@ -12,7 +12,7 @@
12
12
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=flat" alt="License: MIT" /></a>
13
13
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js_%E2%89%A518-339933?style=flat&logo=node.js&logoColor=white" alt="Node.js 18+" /></a>
14
14
  <a href="https://github.com/baobaolaodie/flow-comet/actions"><img src="https://img.shields.io/github/actions/workflow/status/baobaolaodie/flow-comet/ci.yml?style=flat" alt="CI status" /></a>
15
- <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.4-blue.svg" alt="Version 1.6.4" /></a>
15
+ <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-1.6.5-blue.svg" alt="Version 1.6.5" /></a>
16
16
  </p>
17
17
 
18
18
  <p align="center">
@@ -118,7 +118,7 @@ Driving a node by hand, the artifacts each node produces, and the two command su
118
118
 
119
119
  | Project | What it is, and how it works | Relationship to flow-comet |
120
120
  |---|---|---|
121
- | **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer and inherits its artifacts and rules; the projects below reached flow-comet through it. |
121
+ | **flow-kit** | Pure-Markdown methodology pack: 9-stage process, `.specs/` templates, R1–R8 rules, no runtime. You load the stage prompts by hand; state travels through `.md` artifacts. An install pins a specific commit. | **Dependency — the base, and the aggregation point.** flow-comet is its automation layer: templates, rules and artifact shapes are inherited from upstream, and this repository only adds the increment sections upstream does not define; the template is the sole authority on shape, and documents without an upstream template (`UAT`, the archive's leftovers list) are checked for existence only. The projects below reached flow-comet through it. |
122
122
  | **OpenSpec** (Fission-AI) | Spec-driven development framework: a lightweight spec layer before coding. One `proposal` / `specs` / `design` / `tasks` set per change under `openspec/`; the default profile runs propose → apply → sync → archive. | **Aggregated through flow-kit** (idea source). Standalone it stays lighter: no state machine, no gates. |
123
123
  | **Superpowers** (obra) | Agentic skills framework plus a full development methodology, installed per harness across Claude Code, Codex, Cursor, Gemini CLI and more. Skills trigger by context and are enforced by instructions. | **Aggregated through flow-kit** (idea source, partial overlap). Discipline lives in skill text and relies on model compliance; flow-comet machine-checks the same discipline. |
124
124
  | **comet** (rpamis) | Resumable long-running task workflow and skill platform: a five-stage state machine, stage guards, hook write-interception. `/comet` routes from config and defaults to its Native branch. | **Early mechanism reference, now decoupled.** The hook-injection shape and script-owned state came from here; the naming was decoupled and state does not interoperate. Only its Classic branch carries the OpenSpec + Superpowers lineage. |
@@ -156,7 +156,7 @@ Full guide in [CONTRIBUTING.md](CONTRIBUTING.md) — branch model (`feature →
156
156
 
157
157
  1. Branch from `dev`: `git checkout dev && git checkout -b feat/<description>`
158
158
  2. Edit skills/scripts under `.flow-comet/skills/` (authoritative source); TDD with RED scenario first
159
- 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 325 SCENARIOS PASSED`
159
+ 3. Run regression: `node .flow-comet/skills/flow-comet/scripts/guard-self-test.mjs` → `ALL 350 SCENARIOS PASSED`
160
160
  4. Open a PR into `dev` (squash — one change-level commit); release PR `dev → main` (merge — dev's change-level commits enter main, and dev stops leading after each release)
161
161
 
162
162
  CI enforces the repository conventions automatically on every PR and push: regression, installer reproducibility, workflow and bilingual-mirror quality, PR discipline, version consistency, and dead links. Local hooks (commit/push message checks) install with `node scripts/install-commit-hook.mjs` — see [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "flow-comet",
3
- "version": "1.6.4",
3
+ "version": "1.6.5",
4
4
  "description": "An automated execution engine that turns AI coding discipline into a verifiable state machine for the flow-kit 9-stage workflow, built for Claude Code, Codex, and DeepSeek Harness.",
5
5
  "type": "module",
6
6
  "files": [
@@ -38,7 +38,7 @@
38
38
  // 纯 ESM、零第三方依赖,仅使用 Node.js 内置模块。dsh 官方插件形态:
39
39
  // ESM 模块导出 { name, apply },ctx 由 dsh 注入。
40
40
  //
41
- // BRIDGE_VERSION: 1.6.4
41
+ // BRIDGE_VERSION: 1.6.5
42
42
 
43
43
  import { spawn } from 'node:child_process';
44
44
  import { existsSync, readFileSync, realpathSync } from 'node:fs';
@@ -50,7 +50,7 @@ import path from 'node:path';
50
50
  // 值语义 = 当前发布版本(随发布同步更新,与技能包 INSTALLED_VERSION 同值——
51
51
  // bridge-check 的版本一致性检查据此判定 loader 与项目副本同版)。
52
52
  export const name = 'dsh-flow-comet-bridge';
53
- export const version = '1.6.4';
53
+ export const version = '1.6.5';
54
54
 
55
55
  // guard 在项目内的相对路径常量(随 skill 包分发)。
56
56
  const HOOK_GUARD_REL = '.dsh/skills/flow-comet/scripts/comet-hook-guard.mjs';
@@ -5,6 +5,8 @@
5
5
  * 归属不可确认即跳过并给手动指引;clone / checkout 的失败**不抛错**——外网故障不得绑架安装器
6
6
  * 的其余职责(技能树、规则、hook 注入照常完成,进程照常 exit 0)。把这条链路独立成模块,是为
7
7
  * 了让「什么情况下会改动用户目录」只有一个落点可审——答案必须是「只有目标不存在时」。
8
+ * 降级态的统一口径是「未校验(模板缺失)」:获取点给怎么补(命令),进程结尾单独明示后果与
9
+ * 修复方法(两处分工见 FLOW_KIT_DEGRADED_NOTICE 上方的说明)。
8
10
  *
9
11
  * 依赖方向:本模块是叶子(只用 node 内置模块与 git 命令)。
10
12
  */
@@ -28,12 +30,47 @@ function gitErrorFirstLine(err) {
28
30
  return String(err && err.message ? err.message : err).split('\n')[0].trim();
29
31
  }
30
32
 
31
- /** 手动获取指引(clone/checkout 失败或目录非上游克隆时打印——含上游 URL 与目标路径;不抛错) */
33
+ /**
34
+ * 手动获取指引(clone/checkout 失败或目录非上游克隆时打印——含上游 URL 与目标路径;不抛错):
35
+ * 这里只负责「怎么补」,用户可见的结论(影响 / 原因 / 修复方法)留到进程结尾单独明示——
36
+ * 获取段在平台摘要之前执行,结论留在这一段里会被后面的平台清单与摘要顶出视野。
37
+ */
32
38
  function printFlowKitManualGuide(target) {
33
39
  const flowKitDir = path.join(target, 'flow-kit');
34
40
  console.warn(`[flow-comet] 手动获取指引: git clone ${FLOW_KIT_UPSTREAM_URL} "${flowKitDir}"`);
35
41
  console.warn(`[flow-comet] 然后锁定快照: git -C "${flowKitDir}" checkout --detach ${FLOW_KIT_LOCKED_COMMIT.slice(0, FLOW_KIT_SHORT_SHA_LEN)}`);
36
- console.warn('[flow-comet] 未获取 flow-kit 时技能协议引用悬空、guard 段名基准退化为内置 fallback——其余安装职责不受影响。');
42
+ console.warn('[flow-comet] 后果: 模板校验将不可用——各节点出口输出「未校验(模板缺失)」而不比对模板段形;技能册的模板引用同时悬空。其余安装职责不受影响。');
43
+ }
44
+
45
+ /**
46
+ * 安装结尾的降级结论(未校验(模板缺失)):影响 / 原因 / 修复方法三行,挂在进程结尾打印。
47
+ * 与获取点的手动指引分工:那里给命令(现在就能照做),这里给结论(安装结束时的状态与后果)。
48
+ * 只有真的拿不到模板时才挂(获取成功、HEAD 只读失败但目录在场都不挂——模板仍在磁盘上,
49
+ * 结构校验照常可用)。调用契约:只由 prepare-env CLI 进程调用——结尾提示挂在 process 'exit'
50
+ * 上,若将来被库内导入复用,提示会跟着宿主进程退出一起打印(不可断言、会污染输出)。
51
+ * 修复行的措辞约束:`flow-kit/` 已存在但归属无法确认时,重跑会落回同一条跳过分支(安装器绝不
52
+ * 改动已有目录)——所以「重跑」只在移走/处理该目录或按手动步骤补齐之后才是修复,不能单说重跑。
53
+ */
54
+ const FLOW_KIT_DEGRADED_NOTICE = [
55
+ '[flow-comet] 提醒: 本次安装未获取 flow-kit 模板——产出物不会做模板校验。',
56
+ '[flow-comet] 影响: 各节点出口输出「未校验(模板缺失)」而不拦缺段 / 乱序 / 空段(结构校验不可用)。',
57
+ '[flow-comet] 原因: flow-kit/templates 未就位(自动获取失败,或同名目录归属无法确认已跳过——安装器绝不改动已有目录)。',
58
+ '[flow-comet] 修复: 先移走或处理现有 flow-kit/ 目录,或按上方手动获取指引补齐,再重跑本安装器。',
59
+ ].join('\n') + '\n';
60
+
61
+ let flowKitDegradedNoticeScheduled = false;
62
+
63
+ /** 挂一次结尾结论(重复调用幂等;退出阶段只能用同步写——console 在 exit 阶段不保证刷出) */
64
+ function scheduleFlowKitDegradedNotice() {
65
+ if (flowKitDegradedNoticeScheduled) return;
66
+ flowKitDegradedNoticeScheduled = true;
67
+ process.once('exit', () => {
68
+ try {
69
+ fs.writeSync(2, FLOW_KIT_DEGRADED_NOTICE);
70
+ } catch {
71
+ // 结尾提示是尽力而为:写不出去也不得改变退出码(exit 0 / 非破坏契约的底线)
72
+ }
73
+ });
37
74
  }
38
75
 
39
76
  /**
@@ -60,7 +97,8 @@ function flowKitOriginStatus(flowKitDir) {
60
97
  * 路径 2 已存在且 .git 存在且 origin 匹配上游 → 只读 rev-parse HEAD 并输出与锁定点差异影响,绝不改动;
61
98
  * 路径 3 已存在但不满足归属判定 → 摘要"非上游克隆,已跳过"+ 手动指引,不改动;
62
99
  * 路径 4 clone/checkout 任一失败 → 警告 + 手动获取指引,**不抛错**(D5——外网故障不得绑架安装器
63
- * 其余职责,进程照常 exit 0);各平台 purge 清单永不包含 flow-kit(D6,见 PLATFORMS 表头注释)。
100
+ * 其余职责,进程照常 exit 0);3、4 两条降级路径都在安装结尾补一句「未校验(模板缺失)」
101
+ * 的影响 / 原因 / 修复方法;各平台 purge 清单永不包含 flow-kit(D6,见 PLATFORMS 表头注释)。
64
102
  */
65
103
  export function ensureFlowKit(target) {
66
104
  const flowKitDir = path.join(target, 'flow-kit');
@@ -81,6 +119,7 @@ export function ensureFlowKit(target) {
81
119
  // 路径 4:clone/checkout 任一失败 → WARN + 手动指引,不抛错
82
120
  console.warn(`[flow-comet] 警告: flow-kit 自动获取失败(${gitErrorFirstLine(err)})`);
83
121
  printFlowKitManualGuide(target);
122
+ scheduleFlowKitDegradedNotice();
84
123
  }
85
124
  return;
86
125
  }
@@ -94,6 +133,7 @@ export function ensureFlowKit(target) {
94
133
  }
95
134
  console.log('[flow-comet] 目录存在但非上游克隆,已跳过');
96
135
  printFlowKitManualGuide(target);
136
+ scheduleFlowKitDegradedNotice();
97
137
  return;
98
138
  }
99
139
  // 路径 2:上游克隆 → 只读检测并输出差异影响(D4——绝不 fetch/checkout 改动用户克隆)