flow-comet 1.6.4 → 1.7.0

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 (85) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +36 -6
  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/commit-discipline.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +29 -4
  7. package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +22 -0
  8. package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
  9. package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +174 -0
  10. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +17 -95
  11. package/.flow-comet/skills/flow-comet/scripts/health.mjs +28 -4
  12. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +136 -19
  13. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +54 -18
  14. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +6 -6
  15. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
  16. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +25 -10
  17. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +4 -2
  18. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +21 -13
  19. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +163 -0
  20. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
  21. package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +448 -0
  22. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +396 -27
  23. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +1035 -172
  24. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +129 -98
  25. package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
  26. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +797 -232
  27. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +91 -22
  28. package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
  29. package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
  30. package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
  31. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +69 -13
  32. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +454 -135
  33. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +66 -0
  34. package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +109 -13
  35. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +55 -2
  36. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +149 -34
  37. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +79 -9
  38. package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
  39. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +78 -8
  40. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +60 -3
  41. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +167 -3
  42. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +341 -0
  43. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +287 -0
  44. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1454 -16
  45. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1202 -8
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1205 -77
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +753 -5
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +52 -11
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +582 -3
  50. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +9 -1
  51. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +5 -0
  52. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +22 -6
  53. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +2 -0
  54. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +18 -5
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +4100 -0
  56. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -0
  57. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +6 -5
  58. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +203 -4
  59. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +312 -63
  60. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
  61. package/.flow-comet/skills/flow-comet-archive/SKILL.md +6 -2
  62. package/.flow-comet/skills/flow-comet-change/SKILL.md +6 -2
  63. package/.flow-comet/skills/flow-comet-design/GUIDANCE.md +13 -3
  64. package/.flow-comet/skills/flow-comet-design/SKILL.md +15 -8
  65. package/.flow-comet/skills/flow-comet-dev/SKILL.md +1 -1
  66. package/.flow-comet/skills/flow-comet-evolve/SKILL.md +1 -0
  67. package/.flow-comet/skills/flow-comet-execute/SKILL.md +42 -15
  68. package/.flow-comet/skills/flow-comet-health/SKILL.md +1 -1
  69. package/.flow-comet/skills/flow-comet-integration/SKILL.md +1 -1
  70. package/.flow-comet/skills/flow-comet-open/GUIDANCE.md +14 -4
  71. package/.flow-comet/skills/flow-comet-open/SKILL.md +11 -9
  72. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +13 -3
  73. package/.flow-comet/skills/flow-comet-plan/SKILL.md +21 -10
  74. package/.flow-comet/skills/flow-comet-requirement/SKILL.md +1 -1
  75. package/.flow-comet/skills/flow-comet-review/SKILL.md +33 -18
  76. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +13 -3
  77. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +44 -16
  78. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  79. package/.flow-comet/skills/flow-comet-test/SKILL.md +6 -2
  80. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  81. package/.flow-comet/skills/flow-comet-verify/SKILL.md +12 -8
  82. package/README.md +3 -3
  83. package/package.json +1 -1
  84. package/scripts/dsh-bridge.mjs +2 -2
  85. package/scripts/lib/installer-flowkit.mjs +43 -3
@@ -1 +1 @@
1
- 1.6.4
1
+ 1.7.0
@@ -7,6 +7,18 @@ description: "Use when the user wants the flow-comet managed workflow for flow-k
7
7
 
8
8
  # flow-comet
9
9
 
10
+ ## 协议覆盖声明(phase-gated · 上游 vendored 只读基准)
11
+
12
+ **上游只读基准**:`flow-kit/prompts/**` 与 `flow-kit/templates/**` 是随包引入的上游 vendored 基准,本仓**只读引用、不修改**;下列是本仓有意的方向修正,逐条可审计。
13
+
14
+ **不采用(逐条点名)**:① flow-kit 设计原则里的「artifact-first,不是 phase-gated(阶段可压缩、可回炉)」——本仓是 **phase-gated**:8 节点 entry/exit 门 + 节点顺序门,`currentNode` 不匹配即 BLOCKED;② 上游各 prompt 的段表只作内容指引、不作段形来源——`flow-kit/prompts/0-change.md` 的 CHANGE 自检 5 段清单、`flow-kit/prompts/2-design.md` 的 §3 / §4 编号(与模板的 3 / 4 / 5 互换)、`flow-kit/prompts/5-test.md` 的 H3 编号(与模板 H3 错位)一律不采用。
15
+
16
+ **沿用上游**:工件优先级(`.specs/<change-id>/` 是唯一进度真相,可回炉重进)与各阶段的内容协议(反问 / 决策清单 / 5 轮金字塔 / LESSONS 提名)全部沿用;段名、段序与结构子段以 `flow-kit/templates/**` 加 `reference/artifact-templates.json` 为唯一来源。
17
+
18
+ **阶段门是工件门的加强,不是替代**:工件仍是唯一真相,阶段门只把「缺工件」从「事后发现」提前到「出口拦截」——不能拿阶段门替代工件本身。
19
+
20
+ **以本节为准**:本节的 phase-gated 反转全局生效;其余覆盖项按各自小节划定适用面,节点册与技能册另有覆盖声明的,以该册声明为准。
21
+
10
22
  ## Decision Core
11
23
 
12
24
  ### 自动节点检测
@@ -123,7 +135,7 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
123
135
  | 属性 | 含义(本节为口径单一来源) |
124
136
  |------|---------------------------|
125
137
  | ① 写权限 | 子代理写入目标的**放行依据**(含 gitignored 面):身份在场 ⇒ 子代理语义放行;**最小保护集**(`.flow-comet/flow-comet-state.json`、`reference/workflow-protocol.json`)在身份在场时**仍拦** |
126
- | ② 提交隔离 | 各写者只提交**自己的字面路径**(`git add -- <路径>` / `git commit -- <同一路径>`;多个写者共享同一工作区时禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`) |
138
+ | ② 提交隔离 | 各写者只提交**自己的字面路径**(`git add -- <路径>` / `git commit -m "<消息>" -- <同一路径>`,消息在 `--` 之前;多个写者共享同一工作区时禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`) |
127
139
  | ③ 验证隔离 | **同一时刻只有一个写者**(有 request 无对应 result 的在飞委托 ⇒ 不跑全量判据,待写入者收工后重跑;已作废的委托经 `workflow-handoff.mjs withdraw <task-id> --by <来源>` 撤回,留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
128
140
  | ④ 集成纪律 | 协调者按确定性规则**显式、可审计**地集成(`merge --no-ff` 优先、冲突难解时降级 cherry-pick 并记因;机械冲突与语义冲突分别处置) |
129
141
 
@@ -167,20 +179,36 @@ node .claude/skills/flow-comet/scripts/context-scan.mjs [--root <项目根>] [--
167
179
 
168
180
  **新 change 严格模式**:`init` 创建的 change 标记为"新"(`newChange: true`)——新 change 下全部内容级检查强制 BLOCKED(处置标记/缓存证据/波次散文/越权委托/SUMMARY 完整性/进入证据等);旧 change(历史遗留,无标记)保持渐进 WARN。执行者可通过 `status` 确认当前 change 的新旧。
169
181
 
170
- > **design 行绑定的前端适用性**:`flow-comet-ui-design` 与协议一致为 `guarded`,但只对**前端 change** 适用——**触发与跳过判据的唯一权威是 `flow-comet-ui-design` 册**;结构形态按其口径压缩为:`CHANGE.md` 的「视觉调性」段在场,段内「不适用」标记须成**独立行**、居**行首**,或写在适用性类标签的**字段值位**,标记之后须成**词形边界**(命中即回显**命中片段**自证)。前端须先用 Skill 工具加载该技能 + `skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md` 建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端不加载、不声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行;旧 change 缺件仅 WARN。
182
+ > **design 行绑定的前端适用性**:`flow-comet-ui-design` 与协议一致为 `guarded`,但只对**前端 change** 适用——**触发与跳过判据的唯一权威是 `flow-comet-ui-design` 册**;结构形态按其口径压缩为:`CHANGE.md` 的「视觉调性」段在场,段内「不适用」标记须成**独立行**、居**行首**,或写在适用性类标签的**字段值位**,标记之后须成**词形边界**(命中即回显**命中片段**自证)。前端须先用 Skill 工具加载该技能 + `skill-load design flow-comet-ui-design --prompt flow-kit/prompts/2a-ui-design.md --templates DESIGN.md` 建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端不加载、不声明,出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行;旧 change 缺件仅 WARN。
171
183
 
172
184
  **节点技能两层加载模型(入口层 · 双步硬规则)**:路由到节点后,以下两步**都不可跳过**:
173
185
 
174
186
  1. **用 Skill 工具加载该节点的 Implementation 技能**(见下方 Skill Bindings 表 Implementation 列,如 execute → flow-comet-execute)。**不得跳过**——只读取 SKILL.md 文件不叫加载;真正让该 skill 的指令生效的是 Skill 工具把它注入本次会话。
175
- 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**逐条运行声明命令(open/review 等涉及多个协议文件的节点,每个协议文件对应一条声明命令):
187
+ 2. 随后按该节点 SKILL 的 Required Skill Calls,用 Skill 工具加载协议技能(与 Implementation 同名的条目已随路由加载,无需重复加载),加载完成后**立即**声明「加载了哪个技能、按哪份协议工作」。**一个节点该读的协议常常不止一份**(open 是 `0-change.md` + `1-requirement.md`,review 是 `6-review.md` + `5-test.md`)——**一份命令可以给多个 `--prompt`**,`skill-load` 会把它们**全部**记进同一个标记,不是只留第一个:
176
188
 
177
189
  ```bash
178
- node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load <node> <skill> --prompt flow-kit/prompts/<阶段>.md
190
+ # 单份协议(plan):本节点只有一个必需技能
191
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load plan flow-comet-task --prompt flow-kit/prompts/3-task.md --templates TASK.md
192
+
193
+ # 多份协议(open):一条命令两个 --prompt,两份都记进标记
194
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-change --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
195
+
196
+ # 同一节点有两个 guarded 必需技能(open = change + requirement):**每个必需技能各一条**——
197
+ # 一条命令只写一个技能标记,少一条就少一个技能;每条都带该节点的全部 --prompt 与模板全清单
198
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs skill-load open flow-comet-requirement --prompt flow-kit/prompts/0-change.md --prompt flow-kit/prompts/1-requirement.md --templates CHANGE.md,REQUIREMENT.md
179
199
  ```
180
200
 
201
+ > **分条等价**:按协议文件分几条命令声明,与合并成一条等价——出口判据按节点汇总,只问「该读的这几份是否都被声明过」。
202
+
203
+ > **一次声明把三个面给全**:该节点该读的**全部**协议文件(多个 `--prompt`)+ 协议要求的**每个** `guarded` 必需技能各一条(一条命令只写一个技能标记)+ 模板**全清单**(`--templates`)。少任一面的命令照抄不过:出口的覆盖判据按节点汇总点名缺哪份协议文件 / 哪个必需技能,模板声明核对再点名漏写的模板。缺声明时报文给出的恢复命令就是这三面齐全的形态——照抄即可,不要自己拆成「只补缺的那一项」。
204
+
205
+ > **提示词 = 步骤权威、模板 = 段形权威,两者缺一即未完成加载**:`--prompt` 指向的 `flow-kit/prompts/<阶段>.md` 规定这一步**怎么做**(流程步骤、检查项、交接物),`--templates` 指向的 `flow-kit/templates/<DOC>.md` 规定产出**长什么样**(标题、段序、段形)。节点入口先打印 `READ PROMPT:`;**有模板的节点**再打印 `READ TEMPLATE:`(verify / archive 为零模板节点,只打印一行);**两条 READ 行都要读**。design 的**前端** change 还会多打印一行 `READ PROMPT(条件提示词): …2a-ui-design.md…`(按 `frontendCriterion` 判定;非前端不打印)。`--prompt` 必须是该节点的协议文件(以入口打印的 `READ PROMPT:` 行为准);**入口只拦错路径**——逐份核对已写下的声明,落在节点协议面外即 BLOCKED 并点名;**缺失由出口拦**——逐份核对节点协议集,缺哪份逐项点名。两处判据分工不同:既不会静默写成一条与节点无关的声明,也不存在「有一份就过」。
206
+
207
+ > **`--templates` 是内置节点的必填声明**(每个声明标记各写**全清单**,与节点映射一致):open → `CHANGE.md,REQUIREMENT.md` · design → `DESIGN.md`(前端 change 可再加 `UI-DESIGN.md`)· plan → `TASK.md` · execute / subagent-execute → `SUMMARY.md` · review → `REVIEW.md,TEST.md` · verify / archive → **零模板节点,省略该参数**(省略即空集;多写反而不一致)。声明集合由引擎校验:漏写 / 多写 / 错名在新 change 下即 BLOCK,旧 change 仅 WARN。
208
+
181
209
  > **跑声明命令 ≠ 加载**:声明只把“哪次会话加载了哪个 skill、按哪份协议工作”写进状态供 exit/record 核对;真正加载只有第 1 步的 Skill 工具能做到。协议的引用示例:execute / subagent-execute 节点加载 flow-comet-dev 时用 `--prompt flow-kit/prompts/4-dev.md`(DEV 阶段协议),交付物按 `flow-kit/templates/SUMMARY.md` 模板填写并补写 `## 自检方法` 段。
182
210
 
183
- 节点退出(exit)与证据记录(record)会核对声明标记。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。
211
+ 节点退出(exit)与证据记录(record)会核对声明标记。**exit 的判据是「全部覆盖」而不是「任一命中」**:该节点该读的**每一份**协议文件、以及协议里**每一个** `guarded` 必需技能,都要有声明标记——`handoff-guarded` 是子代理侧义务,由 Return Contract 负责,不在节点标记判据内;缺任一即逐项点名并给出补齐命令,新 change BLOCKED、旧 change 只 WARN(恢复命令形态与旧标记兼容口径见 `reference/entry-detail.md` 的「exit 核对声明标记」小节)。声明如实记录执行者动作——加载了哪个 skill、按哪份协议工作——**不等于产出证明**;产出是否正确由产物结构校验与门禁把关。**技能加载前置门**:新 change 的 required 条目不再自动补写——handoff request / record 前必须已有本节点声明标记(先加载、再声明、后干活);声明标记自动补写仅对旧 change 兜底(按协议 requiredSkillCalls 代记,标记带 `auto: true`),手动声明仍推荐(如实记录加载动作与协议文件)。
184
212
 
185
213
  ## Guardrails And Evidence
186
214
 
@@ -252,9 +280,11 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record <node-id> '{"su
252
280
 
253
281
  All artifacts in `.specs/<change-id>/`. Cross-change files in `.specs/` (CONTEXT.md, LESSONS.md, CHANGELOG.md).
254
282
 
255
- > **模板权威**:工件段形以 `flow-kit/templates/**` 为唯一权威。
283
+ > **模板权威**:工件段形 = **上游模板 + 本仓登记的增量段**——`flow-kit/templates/**` 是唯一权威(段与正文),条件段 / 结构子段 / 增量段与指纹由 `reference/artifact-templates.json` 登记。
256
284
  > **archive 定位与读法**:`.specs/archive/**` 是历史证据。**何时可读**:工作区文档明确要求(如断点续传 / 决策追溯),或某 guard 硬校验的约定在模板与 LESSONS 中查不到时;**读什么**:只取结构与证据;**不读什么**:不作为格式规范或决策依据,不得以归档工件对齐段形。
257
285
 
286
+ > **要判定某一段是上游模板段还是本仓登记的增量段、或要核对某工件的条件段与结构子段登记时,先读 `reference/artifact-template-overlay.md`**(按登记表派生的人类可读册:逐工件的标题形态 / 首部字段 / 无条件段 / 条件段 / 结构子段 / 增量段与位置)。
287
+
258
288
  ### Scripts
259
289
 
260
290
  > **命令路径的平台化**:本文件命令统一为**权威源设计形态** `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 请用安装器。
@@ -0,0 +1,154 @@
1
+ # 工件模板登记册(人类可读版)
2
+
3
+ > **读者对象**:要核对「某份工件的某一段从哪来」的执行者与审查者——典型场景是段形被判缺时,确认这一段是上游模板段,还是本仓追加的增量段。
4
+ > **何时读**:要判定某段的归属、要核对条件段与结构子段的登记、或要确认某个工件的标题形态与首部字段时读它。快照口径与指纹以 `reference/artifact-templates.json` 为准——本册(下称「登记册」)是那张登记表的人类可读派生,登记表增删改后同批更新本册。
5
+
6
+ ## 一、单一来源与派生关系
7
+
8
+ | 层 | 载体 | 作用 |
9
+ |---|---|---|
10
+ | 内容权威 | `flow-kit/templates/<DOC>.md` | 段名、段序、正文原文——段集合以它为准 |
11
+ | 结构登记 | `reference/artifact-templates.json` | 模板本身推不出的三类信息:条件段、结构子段、增量段;另记首部字段 / 标题形态 / 指纹 |
12
+ | 本册 | `reference/artifact-template-overlay.md` | 上面两者的合并读法(供人读;改登记表时同批更新,发版期比对指纹) |
13
+
14
+ **合并与判定口径**(与引擎同口径,逐条对应报错类别):
15
+
16
+ - **段集合以模板为准**:登记表里多出的段(模板已删)忽略并提示;模板里多出的段(登记表未登记)按无条件段处理。
17
+ - **段名归一**:忽略编号、括号内容与大小写,核心词必须一致(`## 1. 决策清单` 与 `## 决策清单` 同键);结构子段里的同名对按括号内容区分(`Button (Primary)` 与 `Button (Secondary)` 不是一段)。
18
+ - **无条件段**:缺标题即拦;段正文不得为空。
19
+ - **条件段**:**标题必须在场**(缺席即拦);正文可写 `N/A` / `不适用` / `无` / `—` / `未涉及` / `无变更`,视为已填;与模板该段正文逐字相同判未填。
20
+ - **结构子段**:父段在场且父段正文不是整段 `N/A` 时必须在场;父段整段写 `N/A` 则子段豁免。
21
+ - **增量段**:不参与模板全序;只校验位置(紧随锚段 / 文末 / 位置不限 / 写在指定段内)。`required` 只由各自门禁消费,本层不做存在性兜底。
22
+ - **首部与标题**:标题形态按模板首行(大小写不敏感);首部只校验已在场的 `- **字段**:` 键的值非空。
23
+ - **模板缺席**:整份不校验并输出「未校验(模板缺失)」——不拿内置骨架顶替;标题形态与首部字段来自登记表,照常校验。
24
+ - **两阶段报错**:同一工件首次失败只给模板路径与类别计数,再次失败才列段名(记录在 `.specs/<change-id>/.template-hints.json`,通过后清除)。
25
+
26
+ ## 二、逐工件登记
27
+
28
+ ### ARCHITECTURE — `flow-kit/templates/ARCHITECTURE.md`
29
+
30
+ - 标题形态:`# ARCHITECTURE — 项目级系统架构(活文档)`
31
+ - 首部字段:维护者 / 首次创建 / 最近修订 / 当前 ADR 编号最大值
32
+ - 无条件段(8):`1. 系统概览` · `2. 模块清单 + 边界` · `3. ADR 列表` · `4. 跨模块契约` · `5. 扩展点` · `6. 容量 / 性能边界` · `7. 已知技术债 + 长期方向` · `8. 修订历史`
33
+ - 条件段:无
34
+ - 结构子段:`1.1 一句话定位` · `1.2 服务边界图` · `1.3 关键非功能性指标` · `2.1 模块表` · `2.2 模块依赖规则` · `4.1 公共 HTTP API` · `4.2 事件总线` · `4.3 数据库 schema` · `4.4 共享配置项`
35
+ - 增量段:无
36
+ - 附加:「ADR 列表」段内的 `### ADR-<数字>` 条目另按条目字段校验(健康巡检与架构沉淀两条侧命令共用同一判据)。
37
+
38
+ ### CHANGE — `flow-kit/templates/CHANGE.md`
39
+
40
+ - 标题形态:`# CHANGE: <一句话标题>`
41
+ - 首部字段:Change ID / 创建日期 / 路径建议 / 状态
42
+ - 无条件段(6):`Why(为什么做)` · `What(做什么)` · `影响面` · `范围排除(这次不做)` · `验收线(粗粒度,不是 AC)` · `风险与未知`
43
+ - 条件段(1):`视觉调性(前端项目必填,由 0-change 步骤 0.6 预选填入)`——标题必须在场;非前端写「不适用」的结构形态标记,缺席不再默认判非前端
44
+ - 结构子段:无
45
+ - 增量段(1):`架构层影响声明`(整段,可选,位置 = 文末 / `风险与未知` 之后)
46
+
47
+ ### CONTEXT — `flow-kit/templates/CONTEXT.md`
48
+
49
+ - 标题形态:`# CONTEXT — 项目共享上下文`
50
+ - 首部字段:无
51
+ - 无条件段(7):`项目概要` · `技术栈(团队级默认 / 已锁定)` · `域语言(术语表)` · `已锁决策` · `默认偏好` · `既有抽象索引` · `intel-scan 元数据`
52
+ - 条件段:无
53
+ - 结构子段(挂在「既有抽象索引」下):`HTTP 客户端` · `数据库访问` · `状态管理` · `工具函数` · `自定义 hooks` · `错误处理` · `Schema / 迁移` · `命名约定` · `禁动清单` · `技术债`
54
+ - 增量段:无
55
+
56
+ ### DESIGN — `flow-kit/templates/DESIGN.md`
57
+
58
+ - 标题形态:`# DESIGN: <change 标题>`
59
+ - 首部字段:Change ID / 关联 / 作者
60
+ - 无条件段(5):`0. 技术栈选定` · `1. 决策清单` · `2. 数据流 / 架构图` · `5. 风险` · `6. 不在范围`
61
+ - 条件段(4):`0.5 既有架构对齐` · `3. 关键状态机(如有)` · `4. ADR 索引` · `9. 架构沉淀建议`——标题必须在场
62
+ - 结构子段:`0.5.1 本次 change 触碰的既有模块` · `0.5.2 既有抽象沿用对照表` · `0.5.3 沿用模式 vs 引入新模式`(挂在 0.5);`9.1` ~ `9.5` 五个沉淀槽(挂在 9)
63
+ - 增量段:无
64
+ - 附加:`DESIGN-lite.md` 不是登记工件,只校验标题形态。
65
+
66
+ ### LESSONS — `flow-kit/templates/LESSONS.md`
67
+
68
+ - 标题形态:`# LESSONS — 跨任务失败知识库`
69
+ - 首部字段:无
70
+ - 无条件段(5):`标签索引` · `使用方式` · `条目格式(复制此模板新增)` · `提名条件` · `复核与剪枝`
71
+ - 条件段(1):`条目区(实际项目里把下面的示例替换成你的真实条目)`——标题必须在场
72
+ - 结构子段:`写代码前(DEV 阶段,R1.8)` · `任务完成后(INTEGRATION ARCHIVE 步骤)`(挂在「使用方式」)
73
+ - 增量段:无
74
+ - 附加:条目本身写 `### L-NNN` 并在「条目区」内按编号升序;`## L-NNN` 旧形态在 open / verify / archive 三个出口被拦。
75
+
76
+ ### PROGRESS — `flow-kit/templates/PROGRESS.md`
77
+
78
+ - 标题形态:`# PROGRESS: <T01 - 任务名>`
79
+ - 首部字段:Change ID / Task ID / 暂停时间 / 触发清窗的信号
80
+ - 无条件段(6):`已完成的子步骤` · `当前正在做(清窗那一刻的状态)` · `已排除的方案(反重复关键)` · `待确认的假设` · `临时记下的线索 / 文件位置` · `恢复指引(给下一会话的 AI)`
81
+ - 条件段:无
82
+ - 结构子段:无
83
+ - 增量段:无
84
+
85
+ ### REQUIREMENT — `flow-kit/templates/REQUIREMENT.md`
86
+
87
+ - 标题形态:`# REQUIREMENT: <change 标题>`
88
+ - 首部字段:Change ID / 关联
89
+ - 无条件段(5):`用户故事` · `验收准则(AC)` · `范围切分` · `非功能性需求` · `依赖与假设`
90
+ - 条件段:无
91
+ - 结构子段(挂在「范围切分」):`v1(本次必做)` · `v2(下一轮考虑,不本次)` · `out(永远不做)`
92
+ - 增量段:无
93
+
94
+ ### REVIEW — `flow-kit/templates/REVIEW.md`
95
+
96
+ - 标题形态:`# REVIEW: <change 标题>`
97
+ - 首部字段:Change ID / 审查时间 / 审查者 / 总体结论
98
+ - 无条件段(3):`第一轮 · Spec 合规审查` · `第二轮 · 代码质量审查(6 维衰退风险)` · `总结`
99
+ - 条件段(2):`第三轮 · UI 视觉审查`(仅前端) · `第四轮 · 补充审查(按触发条件)`——标题必须在场
100
+ - 结构子段:`2.0 TEST.md 5 轮金字塔完整性` · `2.1 6 维诊断 · 严重度统计` · `2.2 6 维诊断 · 详细发现` · `2.3 架构依赖图`;`4.1 技术债评估` · `4.2 跨模型分歧`
101
+ - 增量段(1):`处置标记`(条目级标记,必填,位置 = 写在 `2.2 6 维诊断 · 详细发现` 段内)——发现写在模板外的段而 2.2 无条目同样被拦
102
+
103
+ ### STATE — `flow-kit/templates/STATE.md`
104
+
105
+ - 标题形态:`# STATE — 跨会话项目状态`
106
+ - 首部字段:无
107
+ - 无条件段(6):`当前位置` · `阻塞与待决策` · `决策日志(最近 10 条,倒序)` · `已归档 Changes(最近 5 个,倒序)` · `横向命令状态` · `健康检查(AI 每次会话开始前自检)`
108
+ - 条件段:无
109
+ - 结构子段:无
110
+ - 增量段:无
111
+ - 说明:本仓的运行状态由引擎状态文件承载,本模板不参与节点门禁。
112
+
113
+ ### SUMMARY — `flow-kit/templates/SUMMARY.md`
114
+
115
+ - 标题形态:`# SUMMARY: <T01 - 任务名>`
116
+ - 首部字段:Change ID / Task ID / 完成时间 / AI 角色
117
+ - 无条件段(7):`做了什么(一段话)` · `改动文件` · `verify 输出(必填)` · `6 维自查` · `越界检查(必填)` · `是否触发新工作` · `完成判定`
118
+ - 条件段(3):`数据库迁移`(涉及 schema 变更必填) · `破坏性变更`(涉及破坏性改动必填) · `决策与偏离(如有)`——标题必须在场,不适用写 `N/A`
119
+ - 结构子段:`已知接受 + 理由` · `已知小问题`(挂在 6 维自查);`Schema Diff` · `迁移文件` · `执行状态` · `提醒`(挂在数据库迁移);`判定命中` · `引用图` · `反问用户结果` · `回归测试覆盖`(挂在破坏性变更)
120
+ - 增量段(2):`自检方法`(整段,必填,紧随 `越界检查` 或文末) · `LESSONS 扫描`(整段,必填,紧随 `自检方法`)——两段都只按位置校验,存在性由执行/委托出口门禁消费
121
+
122
+ ### TASK — `flow-kit/templates/TASK.md`
123
+
124
+ - 标题形态:`# TASK: <change 标题>`
125
+ - 首部字段:Change ID / 关联
126
+ - 无条件段(5):`波次划分` · `任务清单` · `状态字段说明` · `阻塞日志` · `Fix 任务(来自 REVIEW / INTEGRATION)`
127
+ - 条件段:无
128
+ - 结构子段:无(任务块的 7 字段是元素级结构,不在段层登记)
129
+ - 增量段:无
130
+ - 说明:段正文本身就可能是成品形态(空阻塞日志 / 表格说明),照抄不算未填。
131
+
132
+ ### TEST — `flow-kit/templates/TEST.md`
133
+
134
+ - 标题形态:`# TEST: <change 标题>`
135
+ - 首部字段:Change ID / 关联 / 项目类型
136
+ - 无条件段(4):`0. 本次测试范围声明(5 轮金字塔)` · `第 1 轮 · 功能测试` · `新增测试登记` · `回归保护`
137
+ - 条件段(4):`第 2 轮 · 性能测试` · `第 3 轮 · 安全测试` · `第 4 轮 · 兼容性测试` · `第 5 轮 · 可观测性验证`——标题必须在场,不适用写 `N/A`
138
+ - 结构子段:`1.1 测试矩阵` · `1.2 UAT 脚本` · `1.3 覆盖率` · `1.4 边界 / 错误路径用例` · `1.5 测试质量自检` · `1.6 测试质量记事`;`2.1` ~ `2.4`;`3.1` ~ `3.4`;`4.1` ~ `4.4`;`5.1` ~ `5.4`
139
+ - 增量段(1):`验证命令`(整段,必填,位置不限但**标题后必须紧跟代码块**)——验证出口真实执行其中第一条命令并计数失败
140
+
141
+ ### UI-DESIGN — `flow-kit/templates/UI-DESIGN.md`
142
+
143
+ - 标题形态:`# UI Design: <项目名>`
144
+ - 首部:frontmatter 顶层键 name / description / colors / typography / spacing / rounded / motion / shadow(行级解析,不引入 YAML 依赖)
145
+ - 无条件段(10):`1. 美学北极星` · `2. 4 个决策问题` · `3. 颜色系统` · `4. 字体系统` · `5. 间距 & 圆角 & 动效` · `6. 关键组件规约` · `7. Do's and Don'ts` · `8. 占位符策略` · `9. 反 AI-slop 自检结果` · `10. 触发任务`
146
+ - 可选段(1):`0. 视觉语汇对齐`(仅 brownfield 填;greenfield 可整段删除——这是模板允许删除的唯一段)
147
+ - 结构子段:`0.1` ~ `0.3`(挂在 0);`v0 确认摸路`(1);`Primary` / `Neutral` / `命名规则`(3);`层次表`(4);`Button (Primary)` / `Button (Secondary)` / `Input / Field` / `Card / Container` / `Navigation` / `Typography Hierarchy`(6);`Do` / `Don't`(7)
148
+ - 增量段:无
149
+
150
+ ## 三、维护约定
151
+
152
+ - **改模板 ⇒ 同批改登记表**:段名、段序、结构子段、增量位置任一变化都要同步 `reference/artifact-templates.json`,并在发版期比对指纹(`templateCommit` + 每模板 sha256);本册同批更新。
153
+ - **不得另写段名清单**:门禁一律从登记表 + 模板派生骨架,代码与技能册都不再抄一份段名(抄一份就必然分叉)。
154
+ - **本册不是门禁**:它没有运行时消费方——判据落在引擎与登记表;本册只回答「这一段从哪来」。