flow-comet 1.7.0 → 1.8.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 (78) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +16 -14
  3. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/decision-points.md +5 -5
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/reference/entry-detail.md +9 -9
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +4 -4
  8. package/.flow-comet/skills/flow-comet/reference/init-detection.md +1 -1
  9. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +2 -2
  10. package/.flow-comet/skills/flow-comet/reference/post-archive-handoff.md +264 -0
  11. package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -1
  12. package/.flow-comet/skills/flow-comet/reference/replan.md +1 -1
  13. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +1 -0
  14. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +270 -30
  15. package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +25 -8
  16. package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +41 -38
  17. package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +11 -9
  18. package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +2 -2
  19. package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +1 -1
  20. package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +112 -53
  21. package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +357 -3
  22. package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +24 -1
  23. package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +2 -2
  24. package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +9 -10
  25. package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +8 -8
  26. package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +4 -15
  27. package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +79 -107
  28. package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +183 -232
  29. package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +91 -14
  30. package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +20 -32
  31. package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +10 -19
  32. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +27 -17
  33. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +240 -87
  34. package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +15 -22
  35. package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +11 -4
  36. package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +192 -24
  37. package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +55 -44
  38. package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +2 -4
  39. package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +0 -3
  40. package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +191 -17
  41. package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +3 -0
  42. package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +23 -5
  43. package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +10 -11
  44. package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +40 -3
  45. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +12 -5
  46. package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +193 -111
  47. package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +314 -57
  48. package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +311 -216
  49. package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +33 -62
  50. package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +188 -91
  51. package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +94 -37
  52. package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +36 -27
  53. package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +285 -9
  54. package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +2 -6
  55. package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +5 -15
  56. package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +6 -5
  57. package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +40 -36
  58. package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +2 -2
  59. package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +346 -25
  60. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +0 -2
  61. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +41 -54
  62. package/.flow-comet/skills/flow-comet-archive/SKILL.md +33 -11
  63. package/.flow-comet/skills/flow-comet-change/SKILL.md +1 -1
  64. package/.flow-comet/skills/flow-comet-design/SKILL.md +5 -3
  65. package/.flow-comet/skills/flow-comet-dev/SKILL.md +2 -2
  66. package/.flow-comet/skills/flow-comet-execute/SKILL.md +11 -11
  67. package/.flow-comet/skills/flow-comet-integration/SKILL.md +10 -4
  68. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  69. package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
  70. package/.flow-comet/skills/flow-comet-review/SKILL.md +8 -8
  71. package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +1 -1
  72. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +14 -14
  73. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  74. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
  75. package/.flow-comet/skills/flow-comet-verify/SKILL.md +1 -1
  76. package/README.md +2 -2
  77. package/package.json +1 -1
  78. package/scripts/dsh-bridge.mjs +238 -21
@@ -20,7 +20,7 @@ import { nowTimestamp, formatLocalTimestamp, parseTimestamp } from './time-utils
20
20
  import { resolveRunRoot } from './lib/run-root.mjs';
21
21
  // 路径上下文(runRoot / specsRoot / statePath):节点视图解析要经 state-io 的运行根,与 workflow-state
22
22
  // 入口同源;初始化在下方 runRoot 解析之后。
23
- import { initStateContext, findActiveChange } from './lib/state-io.mjs';
23
+ import { initStateContext, findActiveChange, resolveChangeLocation } from './lib/state-io.mjs';
24
24
  // 技能加载声明判定(单一实现):委托前置门与 record 前置门是同一判据——归档兜底范围也归它,
25
25
  // 本文件不自持第二份扫描(两份实现在「活动目录在场是否回溯归档」「多归档目录取哪个」上会分叉)。
26
26
  import { hasNodeSkillDeclaration } from './lib/state-skillmarkers.mjs';
@@ -273,13 +273,9 @@ async function revalidateResultZeroCommit(state, taskId, handoffReq) {
273
273
  const revokedAtMs = parseTimestamp(handoffReq.revokedAt);
274
274
  const revokedAtDisplay = Number.isNaN(revokedAtMs) ? String(handoffReq.revokedAt) : formatLocalTimestamp(revokedAtMs);
275
275
  const detail = '任务 ' + taskId + ' 零提交资格 result 重验失败(' + reasonText + ')——request evidence noCommit=false, revokedAt=' + revokedAtDisplay + ', revokeReason=' + verdict.reason;
276
- if (state.newChange === true) {
277
- // 新 change 只落 request 资格撤销;此刻尚未默认 handoffResult,确保「不落 result」不是文案承诺
278
- console.error('HANDOFF ERROR: ' + detail + ';新 change 不落 result,出口校验不再豁免缺 commitHash。恢复: 修正 write_files / .gitignore 与路径形态后重新 request,或回传含合法 commitHash 的 Return Contract');
279
- return 'block';
280
- }
281
- console.error('HANDOFF WARN: ' + detail + '(旧 change 渐进,继续记录 result;出口校验不再豁免缺 commitHash)');
282
- return 'warn';
276
+ // 只落 request 资格撤销;此刻尚未默认 handoffResult,确保「不落 result」不是文案承诺
277
+ console.error('HANDOFF ERROR: ' + detail + ';不落 result,出口校验不再豁免缺 commitHash。恢复: 修正 write_files / .gitignore 与路径形态后重新 request,或回传含合法 commitHash 的 Return Contract');
278
+ return 'block';
283
279
  }
284
280
 
285
281
  async function readState() {
@@ -355,12 +351,29 @@ async function resultPreflightHint(state) {
355
351
  try {
356
352
  const changeName = await findActiveChange();
357
353
  if (changeName !== null) {
358
- const protocolRead = await readOwnershipProtocol(state);
359
- if (protocolRead.protocol !== null) {
360
- const view = await resolveNodeView({ changeName, protocol: protocolRead.protocol, state });
361
- if (view.routeNode !== null) return structuralPreflightHint(String(view.routeNode));
354
+ // 身份(findActiveChange)与位置(state-io 的唯一解析器)同源取用:视图的产物根必须与 status /
355
+ // next / record 认同一个目录,否则这里会给出与 next 不同的节点(移动后按活动路径推导即回退 open)。
356
+ // 解析不到(目录两处都没有 / 归档多候选)→ 认定为不可用,报文复用三命令的同一句原因。
357
+ const located = await resolveChangeLocation({
358
+ root: runRoot,
359
+ changeName,
360
+ createdAt: state?.createdAt,
361
+ });
362
+ if (!located.ok) {
363
+ unavailable = located.message.replace(/^BLOCKED:\s*/, '');
362
364
  } else {
363
- unavailable = '协议不可读:' + protocolRead.failure;
365
+ const protocolRead = await readOwnershipProtocol(state);
366
+ if (protocolRead.protocol !== null) {
367
+ const view = await resolveNodeView({
368
+ changeName,
369
+ protocol: protocolRead.protocol,
370
+ state,
371
+ location: located.resolution,
372
+ });
373
+ if (view.routeNode !== null) return structuralPreflightHint(String(view.routeNode));
374
+ } else {
375
+ unavailable = '协议不可读:' + protocolRead.failure;
376
+ }
364
377
  }
365
378
  } else {
366
379
  unavailable = '无活跃 change';
@@ -450,12 +463,8 @@ function reportRequestOwnership(state, taskId, taskAttrs, ownership) {
450
463
  + ' record + exit(退出后路由会自动前进),不要在未 exit 前 entry 目标节点;随后运行 workflow-state next,'
451
464
  + '按输出的 NODE 进入;若输出 execute 表示依赖未满足'
452
465
  + '(该任务当前按串行消化),待任务变为可委托(next 输出对应委托节点)后再 request';
453
- if (state.newChange === true) {
454
- console.error('BLOCKED: ' + detail + '——' + guide + ';本次请求未写入 state,也未记录 handoffRequests');
455
- process.exit(1);
456
- }
457
- console.error('WARN: ' + detail + '(旧 change 渐进不阻断,请求照常记录)——' + guide);
458
- return;
466
+ console.error('BLOCKED: ' + detail + '——' + guide + ';本次请求未写入 state,也未记录 handoffRequests');
467
+ process.exit(1);
459
468
  }
460
469
  if (ownership.verdict === 'mismatch') {
461
470
  const detail = '任务 ' + taskId + '(' + kind + ' pending)应归属节点 '
@@ -469,12 +478,8 @@ function reportRequestOwnership(state, taskId, taskAttrs, ownership) {
469
478
  + ':等当前节点 exit 后,再用 workflow-state entry ' + ownership.targetNode
470
479
  + ' 或 workflow-guard entry ' + ownership.targetNode + ')'
471
480
  + ';随后用 workflow-state next 查看当前路由并按 NODE 输出确认';
472
- if (state.newChange === true) {
473
- console.error('BLOCKED: ' + detail + '——' + guide + ';本次请求未写入 state,也未记录 handoffRequests');
474
- process.exit(1);
475
- }
476
- console.error('WARN: ' + detail + '(旧 change 渐进不阻断,请求照常记录)——' + guide);
477
- return;
481
+ console.error('BLOCKED: ' + detail + '——' + guide + ';本次请求未写入 state,也未记录 handoffRequests');
482
+ process.exit(1);
478
483
  }
479
484
  if (ownership.verdict === 'not-entered') {
480
485
  console.error('WARN: 任务 ' + taskId + ' 的归属节点 ' + ownership.targetNode
@@ -604,11 +609,8 @@ async function main() {
604
609
  const declared = await hasNodeSkillDeclaration(requestNode, state.activeChange);
605
610
  if (!declared) {
606
611
  const loadGuide = await requestSkillDeclarationGuide(requestNode, state);
607
- if (state.newChange === true) {
608
- console.error('BLOCKED: 节点 ' + requestNode + ' 缺少技能加载声明标记(.skill-loads/' + requestNode + '-*.json)——' + loadGuide);
609
- process.exit(1);
610
- }
611
- console.error('WARN: 节点 ' + requestNode + ' 缺少技能加载声明标记(.skill-loads/' + requestNode + '-*.json)——' + loadGuide + '(旧 change 渐进不阻断)');
612
+ console.error('BLOCKED: 节点 ' + requestNode + ' 缺少技能加载声明标记(.skill-loads/' + requestNode + '-*.json)——' + loadGuide);
613
+ process.exit(1);
612
614
  }
613
615
  }
614
616
  // W2-D: 可选 --write-files 记录该 task 允许写入的文件列表(含 glob),供 result 的提交文件子集校验
@@ -655,11 +657,8 @@ async function main() {
655
657
  }
656
658
  if (!taskResolved) {
657
659
  const msg = '委托任务不可解析:TASK.md 缺失、无匹配 <task id=' + taskId + '> 或任务缺 <write_files> 元素——无法判定零提交语义;修正 TASK.md 后重试';
658
- if (state.newChange === true) {
659
- console.error('BLOCKED: ' + msg);
660
- process.exit(1);
661
- }
662
- console.error('WARN: ' + msg + '(旧 change 渐进,不阻断,不记录 noCommit)');
660
+ console.error('BLOCKED: ' + msg);
661
+ process.exit(1);
663
662
  }
664
663
  // 开工前的 LESSONS 命中集(只读;与出口同一份命中算法)——放在归属门禁之前:request 不写 state,
665
664
  // 但执行者仍要看得到「当前任务要回应哪几条」(state 字节零改写由同一路径保证)。
@@ -793,13 +792,9 @@ async function main() {
793
792
  '恢复: 先照抄下面的命令记录委托(description 可省略,缺省即 pending),再重录 result:',
794
793
  ' ' + requestRecoveryCommand(taskId),
795
794
  ].join('\n');
796
- if (state.newChange === true) {
797
- console.error('BLOCKED: 任务 ' + taskId + ' 的 ' + missingRequest + ';本次 result 未写入 state');
798
- console.error(requestRecovery);
799
- process.exit(1);
800
- }
801
- console.error('HANDOFF WARN: ' + taskId + ' 的 ' + missingRequest + '(旧 change 渐进,不阻断)');
795
+ console.error('BLOCKED: 任务 ' + taskId + ' 的 ' + missingRequest + ';本次 result 未写入 state');
802
796
  console.error(requestRecovery);
797
+ process.exit(1);
803
798
  }
804
799
  // 已撤回 = 终态(撤回通道的闭合半边):撤回后的 request 不再接受 result——否则被撤回的委托
805
800
  // 可被事后「复活」,撤回语义与守卫的放行判据(同一判据)分叉。要重新委托该任务须重新 request
@@ -846,11 +841,8 @@ async function main() {
846
841
  console.error('HANDOFF WARN: ' + taskId + ' 零提交提交对象不可校验——按确认提示语义不阻断');
847
842
  } else if (committed.length > 0) {
848
843
  const msg = taskId + ' 声明零提交但提交携带 tracked 文件: ' + committed.join(', ');
849
- if (state.newChange === true) {
850
- console.error('BLOCKED: ' + msg + '——回退越界文件或改按常规任务申报 write_files');
851
- process.exit(1);
852
- }
853
- console.error('HANDOFF WARN: ' + msg + '(旧 change 渐进,不阻断)');
844
+ console.error('BLOCKED: ' + msg + '——回退越界文件或改按常规任务申报 write_files');
845
+ process.exit(1);
854
846
  } else {
855
847
  console.error('HANDOFF 零提交: ' + taskId + ' — 提交为空,校验通过');
856
848
  }
@@ -873,9 +865,8 @@ async function main() {
873
865
  const summaryExact = '.specs/' + state.activeChange + '/' + taskId + '-SUMMARY.md';
874
866
  const violations = committedFiles.filter(f => f !== summaryExact && !reqWriteFiles.some(a => matchWriteFilePattern(f, a)));
875
867
  if (violations.length > 0) {
876
- const currentState = await readState();
877
868
  // 只补事实,不改判定:快照与当前写面分叉时多给一行**可观测事实** + **条件式成因**,
878
- // 越界清单与 BLOCK/WARN 分级保持原样。措辞纪律:本判据只能证明两侧不一致,不能证明
869
+ // 越界清单与分级保持原样。措辞纪律:本判据只能证明两侧不一致,不能证明
879
870
  // 「计划是后来改的」——对真越界,让人去重新 request 会把越界文件写进允许列表,所以
880
871
  // 「回退越界文件」(上一行恢复指引)仍是首选,重新 request 只在成因确实成立时才走。
881
872
  // 出路是**重新发起委托**,命令因此独立成行(与其它「重新发起委托」路径同一装配):说明行
@@ -886,13 +877,9 @@ async function main() {
886
877
  + '若无 replan,越界文件仍不在该任务写面内,按上面的「回退越界文件」处理\n'
887
878
  + ' ' + requestRecoveryCommand(taskId)
888
879
  : null;
889
- if (currentState?.newChange === true) {
890
- console.error('BLOCKED: 提交文件超出 writeFiles 范围: ' + violations.join(', ') + '——新 change 强制委托边界;恢复: 回退越界文件或扩展 write_files');
891
- if (staleSnapshotHint) console.error(staleSnapshotHint);
892
- process.exit(1);
893
- }
894
- console.error('HANDOFF WARN: 提交文件超出 writeFiles 范围: ' + violations.join(', '));
880
+ console.error('BLOCKED: 提交文件超出 writeFiles 范围: ' + violations.join(', ') + '——提交文件须在 writeFiles 范围内;恢复: 回退越界文件或扩展 write_files');
895
881
  if (staleSnapshotHint) console.error(staleSnapshotHint);
882
+ process.exit(1);
896
883
  }
897
884
  } catch {
898
885
  console.error('HANDOFF ERROR: commitHash 无效或 git show 失败: ' + commitHash + '——协调者需确认原因(跨仓库 worktree 提交校验降级属预期,确认后继续)');
@@ -28,6 +28,8 @@ This node finalizes a completed change by extracting reusable lessons from the d
28
28
 
29
29
  ### Steps
30
30
 
31
+ > **硬规则(先于任何动作)**:进入本节点后,**先用 Skill 工具加载** `flow-comet-integration`,并**立即**运行下节 Required Skill Calls 的 `skill-load` 命令写下声明标记——**技能加载声明必须先于任何动作,尤其先于搬目录**。移动目录之后补声明 / 补记录仍可完成(引擎按状态判身份、按解析到的目录读写标记),但那只是**兼容 / 恢复路径**;规范顺序永远是**先记录、后搬目录**。
32
+
31
33
  1. **Scan SUMMARY.md files for lessons**: Read all `<task-id>-SUMMARY.md` files in `.specs/<change-id>/`. Focus on "decisions and deviations" sections. Also check any remaining `<task-id>-PROGRESS.md` "excluded solutions" sections.
32
34
 
33
35
  2. **Apply nomination criteria**: 三条判据(含「其余一律不提名」兜底)见 `flow-comet-integration` 册的「LESSONS 提名」段——该段是判据的**单一权威**,本册不复述、以该册为准。
@@ -44,19 +46,22 @@ This node finalizes a completed change by extracting reusable lessons from the d
44
46
  - Write `.specs/<change-id>/KNOWN-ISSUES.md` — each entry: issue description, why it was deferred, and where it may surface again.
45
47
  - The file moves with the change into `.specs/archive/<YYYY-MM-DD>-<change-id>/` (archived alongside the other artifacts), so the leftover issues never silently vanish after archive.
46
48
  - If there are no leftovers, still state that explicitly in the file (e.g. "无遗留问题" / "No known leftover issues").
49
+ - **本步必须在搬目录之前完成**:工件随目录一起归档,搬完再补只是恢复路径(与上方硬规则的「先记录、后搬目录」同一条顺序纪律)。
50
+
51
+ 6. **Record evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` to record archive completion——**记录是搬目录之前的最后一件证据动作**(LESSONS 提名与遗留清单都已就位);搬目录之后补记录只是兼容 / 恢复路径,不是规范顺序。
47
52
 
48
- 6. **Move change to archive**: After user confirmation:
53
+ 7. **Move change to archive**: After user confirmation——**搬目录是本节点唯一的不可逆动作,声明与记录都已就位后才执行**:
49
54
  - Move `.specs/<change-id>/` to `.specs/archive/<YYYY-MM-DD>-<change-id>/`.
50
55
  - Date format: YYYY-MM-DD of the archive date.
51
56
  - Verify the move completed successfully (source no longer exists, destination has all files).
52
57
  - **git 索引同步**:移动含 `.skill-loads/` 等隐藏目录时,用 `git mv` 逐项移动或移动后用 `git add -A .specs/` 同步索引——文件系统 `mv` 后 git 索引不同步,`git checkout` 会从树恢复残留文件(实测:归档后 checkout 恢复 9 个 .skill-loads 源路径文件)。
53
58
 
54
- 7. **Update CHANGELOG.md**: 在 `.specs/CHANGELOG.md` **顶部**按日期倒序插入新条目(倒序约定:新条目永远在最新日期行之上;文件不存在则从模板创建)。若项目既有 CHANGELOG 采用其他格式(如 `## 日期 + 列表`),**跟随项目既有格式**在顶部插入(不强制转表格——保持仓库一致性;guard 的倒序检测只针对表格格式行):
59
+ 8. **Update CHANGELOG.md**: 在 `.specs/CHANGELOG.md` **顶部**按日期倒序插入新条目(倒序约定:新条目永远在最新日期行之上;文件不存在则从模板创建)。若项目既有 CHANGELOG 采用其他格式(如 `## 日期 + 列表`),**跟随项目既有格式**在顶部插入(不强制转表格——保持仓库一致性;guard 的倒序检测只针对表格格式行):
55
60
  - 表格格式: `| YYYY-MM-DD | <change-id> | one-line summary | PR link | new L-NNN entries |`
56
61
 
57
- 8. **Update STATE.md(可选决策日志)**: 若项目维护 `STATE.md`,新决策日志条目**顶部**插入(倒序约定,**禁止文件尾追加**)。flow-comet 的活动 change 状态由 `.flow-comet/flow-comet-state.json` 管理——STATE.md 无 active change 字段,不需要也不应手动清除。
62
+ 9. **Update STATE.md(可选决策日志)**: 若项目维护 `STATE.md`,新决策日志条目**顶部**插入(倒序约定,**禁止文件尾追加**)。flow-comet 的活动 change 状态由 `.flow-comet/flow-comet-state.json` 管理——STATE.md 无 active change 字段,不需要也不应手动清除。
58
63
 
59
- 9. **Notify user of architecture sedimentation + leftover issues**: Check DESIGN.md section 9 for sedimentation suggestions. If N > 0 suggestions exist, tell user — and always explicitly enumerate the leftover issues from KNOWN-ISSUES.md in the archive notification (they must not silently disappear after archive):
64
+ 10. **Notify user of architecture sedimentation + leftover issues**: Check DESIGN.md section 9 for sedimentation suggestions. If N > 0 suggestions exist, tell user — and always explicitly enumerate the leftover issues from KNOWN-ISSUES.md in the archive notification (they must not silently disappear after archive):
60
65
  ```
61
66
  Archived to .specs/archive/<YYYY-MM-DD>-<change-id>/
62
67
  遗留问题清单(KNOWN-ISSUES.md,随工件归档): <each leftover issue, or 无>
@@ -64,16 +69,14 @@ This node finalizes a completed change by extracting reusable lessons from the d
64
69
  Recommended: run A-evolve workflow after >= 5 个带 `§9` 的归档 change,或距上次沉淀 > 60 天(阈值与入口册 `EVOLVE-DUE` 提示同口径)——批量 review 后 patch CONTEXT.md。
65
70
  ```
66
71
 
67
- 10. **Record evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` to record archive completion.
68
-
69
- 11. **Exit check**: Run exit check.
72
+ 11. **Exit check**: Run exit check——搬目录仍是 `exit` 的前置:归档目录不在场时出口的产物门会直接拦下;登记与通知的措辞也一律按归档后的位置写。
70
73
 
71
74
  ### 归档后发现缺陷(受控重入)
72
75
 
73
76
  归档已 entry 但归档移动尚未发生(`.specs/<change-id>/` 仍在原位、`status !== 'completed'`)时,review / verify / 执行阶段发现的新缺陷**不得**在归档阶段就地修完——工作归属须先受控归位回既有生命周期,再按修复回路收口。要点:
74
77
 
75
78
  - **未移动** → 受控重入:由用户显式授权后运行 `node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text>`——目标限 `execute` / `subagent-execute` / `review` / `verify` 之一;每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`,n ≥ 已用轮次 + 1);命令先自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`),再转移工作归属;缺授权、目标越界、超上限或归档移动已发生一律 BLOCKED(state 字节零改写),不会静默跳过。
76
- - **已移动 / 已合并** → 人工处置或新 change:归档移动已发生(`.specs/archive/<日期>-<change-id>/`)或 change 已 `completed` / 已合并时,受控重入不适用(不承诺把文件搬回原位);走人工处置,或把修复放进新 change / hotfix,并在遗留清单里登记指针。
79
+ - **已移动 / 已合并** → 人工处置或另开 change:归档移动已发生(`.specs/archive/<日期>-<change-id>/`)或 change 已 `completed` / 已合并时,受控重入不适用(不承诺把文件搬回原位);走人工处置,或把修复放进另一个 change / hotfix,并在遗留清单里登记指针。
77
80
  - **写权限顺序(先转移后写 TASK)**:先跑 `reenter` 完成转移(写入权限随即跟随目标节点),再在目标节点权限内追加 Fix 任务 / 修改工件;archive 阶段 hook 对 change 目录只放行 `KNOWN-ISSUES.md` 这一个精确文件(另有 `.specs/archive/`、`.specs/CHANGELOG.md`、`.specs/LESSONS.md`、`STATE.md`),**不要试图在归档阶段先写 TASK.md**。
78
81
  - **回源路径不因归档而放宽**:修复回路本身不变——回到 `execute` 生命周期时照样跑完四类出口,随后**回源节点跑出口**(`entry <源节点>` → `exit <源节点> --apply`);受控重入只改工作归属,不写任何闭合标记,也**禁止绕过**目标节点入口 / 出口与源节点出口门禁。
79
82
 
@@ -177,7 +180,7 @@ Evidence: `archive-summary` (required)
177
180
  ## Evidence Record
178
181
 
179
182
  ```bash
180
- node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summary":"Change archived to .specs/archive/<date>-<id>/, N lessons added, CHANGELOG updated"}'
183
+ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summary":"Archive evidence prepared before the move: N lessons nominated, leftover list compiled; directory move and CHANGELOG registration follow"}'
181
184
  ```
182
185
 
183
186
  ## Guardrails
@@ -185,7 +188,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summ
185
188
  | Guardrail ID | Label | Validation Type |
186
189
  |--------------|-------|-----------------|
187
190
  | `archive-evidence` | Archive directory exists, source removed | state-transition |
188
- | `changelog-updated` | CHANGELOG.md 有新条目,且表格条目按日期倒序 | 结构级(guard 强制:`CHANGELOG.md` 表格日期倒序——新 change 非倒序即 BLOCKED、旧 change WARN;未含本 change 标识只 WARN 提示补登记);条目内容与格式由 review 把关 |
191
+ | `changelog-updated` | CHANGELOG.md 有新条目,且表格条目按日期倒序 | 结构级(guard 强制:`CHANGELOG.md` 表格日期倒序——非倒序即 BLOCKED;未含本 change 标识只 WARN 提示补登记);条目内容与格式由 review 把关 |
189
192
  | `lessons-preserved` | LESSONS.md still in .specs/ (not archived) | 执行纪律(review 把关),guard 不校验 |
190
193
  | `user-confirmed` | User confirmed archive before execution | 执行纪律(review 把关),guard 不校验 |
191
194
 
@@ -195,7 +198,26 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '{"summ
195
198
  node .claude/skills/flow-comet/scripts/workflow-guard.mjs exit archive --apply
196
199
  ```
197
200
 
198
- If the script prints `NEXT: done`, summarize the workflow evidence and stop. The change is complete.
201
+ If the script prints `NEXT: done`, run the 「归档完成后的交接」 section below first, then summarize the workflow evidence and stop. The change is complete.
202
+
203
+ ### 归档完成后的交接(Known-Issue 后续处理)
204
+
205
+ **触发**:`exit archive --apply` 打印 `NEXT: done`、状态已变为 `completed` 之后才进入本段。归档在此之前已经闭合——**本段不阻断归档**:不重跑出口、不改出口判据、不改变 `entry → record → move → exit` 的顺序;用户选择稍后处理或直接跳过,归档结果同样成立。
206
+
207
+ **顺序**(逐条执行,不跳步、不调换):
208
+
209
+ 1. **读当前分支与工作区状态**——只用于向用户报告(当前分支名、未提交改动);**不做任何分支操作**:不 merge、不 checkout、不删除分支、不 push。
210
+ 2. **读归档的遗留清单**——`.specs/archive/<YYYY-MM-DD>-<change-id>/KNOWN-ISSUES.md`,逐条整体读、不是只数条数;文件写明无遗留问题时如实报告,可就此结束。
211
+ 3. **探测载体**——只读探测:是否 git 工作树、`origin` 的 host 分类、`gh` / `glab` 是否在场及认证状态、本地 roadmap 是否存在与其形式。
212
+ 4. **一次询问**——带着探测摘要与推荐,用结构化提问工具问一次(平台没有该工具时退回文本提问),问的是**载体**(范围只限载体本身);**载体只问一次**(粒度选择、是否提交、是否转入是各自独立的确认,不算追问),之后不再为载体追问第二遍。
213
+ 5. **完整展示**——把将要创建或写入的全部内容完整呈现给用户(过长可分批,但不得截断、不得用摘要代替)。
214
+ 6. **选择**——用户选定之后才进入执行;未选定不动任何远端或本地文件。
215
+ 7. **执行**——按用户选择创建 issue、写入本地 roadmap,或输出草稿与可复制命令。
216
+ 8. **报告**——逐条给出成功 / 跳过 / 失败原因与草稿位置,并说明遗留清单最终落在何处。本地写入时**另**按参考页「提交(仅本地写入)」节处理:先 `git check-ignore` 判定可达提交面,未被忽略则展示路径与当前分支、问一次是否提交(这一问同样不是对载体那一问的追问)。
217
+
218
+ **边界**:不写 `.flow-comet/flow-comet-state.json`;不修改归档的 `KNOWN-ISSUES.md`;不自动提交、不关闭 issue;本段全程不做任何分支操作。
219
+
220
+ **归档完成后要执行交接时**读 `../flow-comet/reference/post-archive-handoff.md`(触发与顺序、探测命令序列、四选项询问、载体决策表、公开草稿骨架、降级路径与操作矩阵)。
199
221
 
200
222
  ## Recovery
201
223
 
@@ -36,7 +36,7 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
36
36
 
37
37
  - **判据与强制等级(唯一权威)**:判据全文与 `guarded` 绑定、`required-skill:design.flow-comet-ui-design` 声明要求、非前端 `UI-DESIGN: skipped(非前端)` 的出口口径都在 `flow-comet-ui-design` 册的「触发与跳过」段——本节不复述,只描述怎么填段。
38
38
  - **前端项目**:按步骤 0.6 的预选结果填段(选定 / 理由 / 参考产品 / 明确排除),不要以结构形态标注「不适用」。
39
- - **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI 工具,无用户可见界面」)。**段缺席不再默认判非前端**——新 change 的「视觉调性」是标题必须在场的条件段,**缺席即拦**(open 出口的骨架校验与 design 出口的适用性门控都会拦);缺席只对旧 change 兼容(沿用旧口径判非前端,出口打印 `UI-DESIGN: skipped(旧 change 兼容)`)。
39
+ - **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI 工具,无用户可见界面」)。**段缺席不再默认判非前端**——新建 change 的「视觉调性」是标题必须在场的条件段,**缺席即拦**(open 出口的骨架校验与 design 出口的适用性门控都会拦);缺席不保留兼容侧——同一形态一个判级(段缺席一律拦,须显式标注「不适用」或填写调性)。
40
40
  - **改判走本阶段**:change 进行中要改前端 / 非前端判定,回到这里改这一个段,不在 design / execute / verify 里就地绕开判据——改段即改变了 design 出口的判据输入。
41
41
 
42
42
  ## 状态推进
@@ -114,11 +114,11 @@ The design node reads CHANGE.md and REQUIREMENT.md, then produces DESIGN.md thro
114
114
 
115
115
  | Skill | Enforcement | Reason |
116
116
  |-------|-------------|--------|
117
- | `flow-comet-ui-design` | Guarded(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——前端 change 须先 `skill-load` 建标记并在 record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端项目不加载不声明;旧 change 渐进 WARN |
117
+ | `flow-comet-ui-design` | Guarded(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——前端 change 须先 `skill-load` 建标记并在 record 载荷带 `required-skill:design.flow-comet-ui-design`(声明标记只能由执行者手动 `skill-load` 写入,引擎不代记);非前端项目不加载不声明;缺件一律拦截(同一形态一个判级) |
118
118
 
119
119
  **加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
120
120
 
121
- 1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为 **guarded 但仅前端适用**的条目——前端项目用 Skill 工具加载其已装副本后**必须**运行对应 `skill-load` 声明建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端项目不加载不声明(出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行);旧 change 保持渐进,缺件仅 WARN。
121
+ 1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为 **guarded 但仅前端适用**的条目——前端项目用 Skill 工具加载其已装副本后**必须**运行对应 `skill-load` 声明建标记,并在 record 载荷带 `required-skill:design.flow-comet-ui-design`;非前端项目不加载不声明(出口打印可见的 `UI-DESIGN: skipped(非前端)` 后放行);缺件一律拦截(同一形态一个判级)。
122
122
 
123
123
  > **前端判据(结构级 · 唯一权威 → `flow-comet-ui-design` 册的「触发与跳过」段)**:判据全文与 `guarded` 绑定的判级口径都在该册——本节不复述,判定与出口行为一律以该册为准。
124
124
  2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明)。`--templates` 声明本节点该读的产出物模板:`design` 的必填模板是 `DESIGN.md`;**前端 change 另加 `UI-DESIGN.md` 时写成 `--templates DESIGN.md,UI-DESIGN.md`**(`UI-DESIGN` 属可选声明,非前端不加):
@@ -145,6 +145,8 @@ Evidence: `design-summary` (required)
145
145
 
146
146
  ```bash
147
147
  node .claude/skills/flow-comet/scripts/workflow-state.mjs record design '{"summary":"DESIGN.md produced with tech stack, architecture alignment, ADRs, risks"}'
148
+ # frontend change: add "required-skill:design.flow-comet-ui-design" to an evidence payload, e.g.
149
+ # ... record design '{"summary":"...","completedChecks":["required-skill:design.flow-comet-ui-design"]}'
148
150
  ```
149
151
 
150
152
  ## Guardrails
@@ -153,7 +155,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record design '{"summa
153
155
  |--------------|-------|-----------------|
154
156
  | `design-artifacts` | DESIGN.md (or DESIGN-lite.md) exists with section 0 | artifact-exists |
155
157
  | `architecture-aligned` | Section 0.5 populated for brownfield | 执行纪律(review 把关),guard 不校验 |
156
- | `ui-design-artifacts` | UI-DESIGN.md exists for frontend projects | 结构级(guard 强制:前端 change 缺 `.specs/<change-id>/UI-DESIGN.md` → 新 change BLOCKED、旧 change WARN;判定依据 = `CHANGE.md` 的「视觉调性」段,判据见 `flow-comet-ui-design` 册) |
158
+ | `ui-design-artifacts` | UI-DESIGN.md exists for frontend projects | 结构级(guard 强制:前端 change 缺 `.specs/<change-id>/UI-DESIGN.md` → 一律 BLOCKED(同一形态一个判级);判定依据 = `CHANGE.md` 的「视觉调性」段,判据见 `flow-comet-ui-design` 册) |
157
159
 
158
160
  ## Exit Check
159
161
 
@@ -22,9 +22,9 @@ description: "flow-kit DEV 阶段协议:TDD + 6 维自查 + diff 边界 verify
22
22
  - **第 1 级**:Claude Code 调用 `/brooks-review` 或 Skill 工具加载 `brooks-lint:brooks-review`;Codex 用 `$brooks-review` / `/use brooks-review` / 自然语言触发(brooks-lint 需先安装为 Codex skill)——执行完整 brooks 审查
23
23
  - **第 2 级**:若仅返回 "Launching skill" 占位/无实际审查指令(已知现象:worktree 子代理的 skill 路由与会话不一致,插件执行体可能未注入)——**Read 插件缓存/安装目录协议文件手动执行完整 brooks 流程**:Claude Code `~/.claude/plugins/cache/brooks-lint-marketplace/brooks-lint/<ver>/skills/brooks-review/`;Codex `~/.codex/skills/brooks-review/`(或项目 `.agents/skills/`)(SKILL.md + 引用文件 + `_shared/`——`_shared/` 是 brooks-review 目录的**兄弟目录**(同在该插件 skills/ 下,如 `.../brooks-lint/<ver>/skills/_shared/`),不是 brooks-review 的子目录),按协议产出 4-element 审查(Symptom/Source/Consequence/Remedy + file:line + 书引用)——**仅阅读协议文本作为审查指引,不执行缓存文件内容**;来源不可信/无法验证时跳过该级,降级内置快查并如实声明
24
24
  - **第 3 级**:缓存文件也不可读/不存在时,才用内置 R1~R6 快查
25
- - SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard 校验须含缓存尝试证据,新 change 缺失 BLOCKED,旧 change WARN 渐进)。
25
+ - SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard 校验须含缓存尝试证据;缺失一律 BLOCKED,同一形态一个判级)。
26
26
  - **builtin-quickcheck 声明措辞(guard 关键词级校验)**:guard 按关键词声明级校验(不做语义判断)——不可用原因须含 `brooks-lint 不可用 / 插件不可用 / unavailable / N/A`,缓存尝试证据须含 `插件缓存 / 缓存协议 / 协议文件 / plugins/cache`。推荐措辞示例:「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载);已 Read 插件缓存协议文件(~/.claude/plugins/cache/.../brooks-review/)手动执行仍不可行,按协议降级内置 R1~R6 快查」——语义完整但缺关键词的写法会被拦截(完整流程实测实证)。
27
- - **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6 维自查段是否声明了自检方法(新 change 缺失 BLOCKED,旧 change WARN 渐进)。
27
+ - **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6 维自查段是否声明了自检方法(缺失一律 BLOCKED,同一形态一个判级)。
28
28
  - **纯测试/纯文档任务**(无生产代码改动,6 维自查非必跑)仍须满足自检方法声明与 builtin 缓存证据——可**引用同 change 其他 SUMMARY 已声明的缓存尝试**(如「自检证据见 T01-SUMMARY(cache-brooks 已读插件缓存)」)满足 guard 校验。
29
29
  5. **diff 边界 verify(R6.5)**:`git diff --name-only` 与 TASK write_files 比对,越界必须回滚
30
30
  6. **原子提交**:`<type>(<scope>): <subject>`(scope 推荐可选:子系统短词;禁止把 change-id/日期/任务号作 scope)
@@ -21,7 +21,7 @@ In subagent mode (default) this node is a coordinator: it does not write impleme
21
21
  |------|------|------|
22
22
  | `SUMMARY.md` | `## 做了什么(一段话)` / `## 改动文件` / `## verify 输出(必填)` / `## 6 维自查`(须含实质内容)/ `## 越界检查(必填)` / `## 是否触发新工作` / `## 完成判定`;首部四字段 `Change ID` / `Task ID` / `完成时间` / `AI 角色` 必填 | **条件段**:`## 数据库迁移(涉及 schema 变更必填 · 来自 4-dev 步骤 1.7 / R4.5)` / `## 破坏性变更(涉及破坏性改动必填 · 来自 4-dev 步骤 1.8 / R4.6 / B4 老项目护栏)` / `## 决策与偏离(如有)`——标题必须在场,不适用写 `N/A`;**增量段**:`## 自检方法`(整段必填,紧随 `## 越界检查` 或文末)、`## LESSONS 扫描`(整段必填,紧随 `## 自检方法`) |
23
23
 
24
- > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段(前者校验自检方法声明,后者校验开工前扫描可核对)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**:`## 自检方法` 声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一及降级证据,`## LESSONS 扫描` 声明命中条目与逐条回应;否则新 change 的 exit 会被 BLOCKED。
24
+ > **注意**:flow-kit 的 SUMMARY 模板**不含 `## 自检方法` 与 `## LESSONS 扫描` 两段**——它们是 flow-comet 登记的增量段(前者校验自检方法声明,后者校验开工前扫描可核对)。使用 `flow-kit/templates/SUMMARY.md` 填写后,**必须按上方右栏补写这两段**:`## 自检方法` 声明 brooks-review / cache-brooks / builtin-quickcheck 三值之一及降级证据,`## LESSONS 扫描` 声明命中条目与逐条回应;否则 exit 会被 BLOCKED。
25
25
 
26
26
  guard 校验见 workflow-guard.mjs 的 execute 出口门禁(必填段 + 6 维自查实质内容 + 自检方法声明三值 + LESSONS 扫描段与命中核对)与模板骨架派生(段标题 / 段序 / 首部字段 / 增量段位置);「填得好不好」由 review 把关。
27
27
 
@@ -60,7 +60,7 @@ A mismatch is not a bug but the same fact seen from three angles: the `ROUTE:` l
60
60
 
61
61
  execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pending 任务**。
62
62
 
63
- **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
63
+ **归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute`;错误节点的请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
64
64
 
65
65
  **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 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
66
66
 
@@ -72,8 +72,8 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
72
72
  - execute 遍历 TASK.md 时,遇到 `parallel="true" status="pending"` 的任务块应**跳过**
73
73
  - **全 parallel 任务时 execute 不得空退出(除非显式豁免)**:guard 的 exit 校验(evidence 前置 → 串行 pending 检测 → Output Schema 产物)会 BLOCKED——「空退出」默认不可达(实测确认)。正确路径:
74
74
  1. 正常流程下 determineNode 的 路由逻辑会**直接路由到 subagent-execute**(无需经过 execute 空退出)——协调者确认 路由逻辑生效(`NODE: subagent-execute`)后直接进入该节点
75
- 2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute 完成属越权委托——新 change BLOCKED(旧 change WARN 渐进)
76
- 3. **显式空退出豁免(新 change 可用)**:确认全 parallel 无串行可做且无法路由时,用 `record execute '{"emptyExitApproved":true}'` 显式声明后 exit 通过(跳过串行 pending 与产物校验;防规划错误仍默认 BLOCKED——豁免须显式声明;exit 输出 EMPTY-EXIT 审计提示)
75
+ 2. 若已进入 execute 且确认无串行任务可做:按正常 exit 流程处理(record execute evidence + 满足产物校验),需要豁免越俎代庖检测时用 `record execute '{"parallelTakeoverApproved":true}'` 显式声明;[P] 任务由 execute 完成属越权委托——一律 BLOCKED(同一形态一个判级)
76
+ 3. **显式空退出豁免(须显式声明)**:确认全 parallel 无串行可做且无法路由时,用 `record execute '{"emptyExitApproved":true}'` 显式声明后 exit 通过(跳过串行 pending 与产物校验;防规划错误仍默认 BLOCKED——豁免须显式声明;exit 输出 EMPTY-EXIT 审计提示)
77
77
  - determineNode 路由逻辑会优先检测依赖已满足的 parallel 任务并路由到 subagent-execute;若 determineNode 路由到了 execute,说明当前趟存在需要 execute 处理的串行任务(此时应执行而非空退出——**除非已显式声明空退出豁免** `emptyExitApproved`,见上条第 3 项)——串行消化完成后再次路由,剩余并行任务回到 subagent-execute 的下一趟(多趟循环直至无可并行 pending 且无串行残留)
78
78
 
79
79
  ### 并行安全四属性契约
@@ -84,7 +84,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
84
84
  > |---|------|------|----------|
85
85
  > | ① | **写权限** | 每个写者必须有一条被守卫认可的写入通道 | **身份分派**(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) |
86
86
  > | ② | **提交隔离** | 提交只含自己 `write_files` 的字面路径 | 提交面 pathspec 纪律五要素(见 Guidance 同名小节) |
87
- > | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 新 change BLOCKED / 旧 change WARN;全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
87
+ > | ③ | **验证隔离** | 同一时刻只有一个写者:全量判据不得与在飞写者并行 | 出口校验锚 = `handoffRequests` 有 request 无对应 `handoffResult` ⇒ 一律 BLOCKED(同一形态一个判级);全部有 result ⇒ 放行;无证据 ⇒ 零输出(**已撤回的 request 不构成在飞委托**:`workflow-handoff.mjs withdraw <task-id> --by <来源>` 在原记录上留痕 `withdrawnAt` + `withdrawnBy`,已撤回 = 终态、历史不删) |
88
88
  > | ④ | **集成纪律** | 机制选择 / 顺序 / 审计 / 冲突处置四项均有明文规则 | 集成纪律四要素(见 Guidance 同名小节) |
89
89
  >
90
90
  > **写面含 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`。
@@ -130,10 +130,10 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
130
130
 
131
131
  对 TASK.md 每个 pending 串行任务,协调者执行:
132
132
 
133
- 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 记录:缺失时新 change **BLOCKED**(state 字节零改写),并给出恢复指引「先照抄下面的命令记录委托(`description` 可省略),再重录 result」——命令形如 `node ".claude/skills/flow-comet/scripts/workflow-handoff.mjs" request T02`(设计形态,安装时脚本根按平台改写;引擎打印的就是带真实路径与任务号的那一行——脚本路径整条加引号,整行可直接执行);旧 change 只 WARN。零提交的 result 与只交自身 `<task-id>-SUMMARY.md` 的 result 两种形态同样被拦——该校验先于零提交语义与提交子集校验,那两者都从 request 取范围,因此不存在「先记 result 再补 request」的可行顺序。
133
+ 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 记录:缺失时 **BLOCKED**(state 字节零改写),并给出恢复指引「先照抄下面的命令记录委托(`description` 可省略),再重录 result」——命令形如 `node ".claude/skills/flow-comet/scripts/workflow-handoff.mjs" request T02`(设计形态,安装时脚本根按平台改写;引擎打印的就是带真实路径与任务号的那一行——脚本路径整条加引号,整行可直接执行)。零提交的 result 与只交自身 `<task-id>-SUMMARY.md` 的 result 两种形态同样被拦——该校验先于零提交语义与提交子集校验,那两者都从 request 取范围,因此不存在「先记 result 再补 request」的可行顺序。
134
134
  2. **委托子代理**:
135
- **委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request`(步骤 1)与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(新 change BLOCKED,恢复句见步骤 1)。
136
- **Delegation order (mandatory)**: a successful request first, then launch the subagent — the `workflow-handoff.mjs request` call and the subagent launch are two sequential steps; never inside one concurrent call (e.g. request plus Agent / spawn_agent in the same `Promise.all`). This is execution discipline, not a mechanism interception: the platform tool layer offers no hook point, so the engine will not queue it for you. **Two different things**: this rule is about the order of the request and the subagent launch, and nothing enforces it; "a result needs a request" is a mechanism guarantee — a result without one is refused before anything is written (a new change blocks, recovery line in step 1).
135
+ **委托顺序(硬顺序)**:先让 request 成功,再启动子代理——同一任务的 `workflow-handoff.mjs request`(步骤 1)与子代理启动是串行两步,禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all` 里同时发 request 与 Agent / spawn_agent)。这是执行纪律,不是机制拦截:平台工具层没有可挂的判定点,引擎不会替你排队。**两件事别混**:本条管的是「request 与子代理启动的先后」,它没有挂点;「`result` 需要一条 request」是机制保证——缺 request 的 result 在写盘前被拒(BLOCKED,恢复句见步骤 1)。
136
+ **Delegation order (mandatory)**: a successful request first, then launch the subagent — the `workflow-handoff.mjs request` call and the subagent launch are two sequential steps; never inside one concurrent call (e.g. request plus Agent / spawn_agent in the same `Promise.all`). This is execution discipline, not a mechanism interception: the platform tool layer offers no hook point, so the engine will not queue it for you. **Two different things**: this rule is about the order of the request and the subagent launch, and nothing enforces it; "a result needs a request" is a mechanism guarantee — a result without one is refused before anything is written (it blocks, recovery line in step 1).
137
137
  按平台通道委托 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 前值属预期(文件集一致即可,以实际提交对象为准)。
138
138
  **提交从属规则**:任务专属的 `<task-id>-SUMMARY.md`(位于 `.specs/<change-id>/`,是 flow-comet 强制产物)允许随任务提交属流程默认豁免——目标仓库的既有规定优先,若目标仓库忽略清单等既有规定拒绝其入库,被拒即为正确行为,严禁 force-add 强加越库提交;委托校验对任务摘要的豁免属于校验宽容度,不是入库指令。
139
139
  **提交面 pathspec 纪律(五要素,见 Guidance 同名小节)**:handoff prompt 必须要求子代理用 `git add -- <自己字面路径>` + `git commit -m "<消息>" -- <同一路径>`(消息在 `--` 之前)提交、锁失败重试、禁裸 `add` / `commit -a` / `stash` / `clean` / `reset`(适用条件:**多个写者共享同一工作区**;各自独立工作区内的局部 `reset` / `clean` 不在禁令内)。**集成纪律(四要素,见 Guidance 同名小节)**:协调者集成时优先 `git merge --no-ff`、降级 `cherry-pick` 记因、顺序按 `depends_on` 拓扑序 + 同层 task id 升序、冲突按机械 / 语义两类分别处置。
@@ -145,7 +145,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
145
145
  6. **下一个 pending 任务**:重复步骤 1-5。
146
146
 
147
147
  > 原 Steps 的 TDD / LESSONS / verify / 6 维自查 / 越界检查 / commit 协议**移入 handoff prompt 作为子代理的强制协议**,协调者不亲自执行。
148
- > **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence 缺失在新 change 下仍会被 W1-D 拦截,因此必须显式提供此形态而非省略字段)。
148
+ > **Return Contract 非代码任务**:纯文档 / 纯配置任务子代理回传时,`greenEvidence` 与 `redEvidence` 均允许 `{"command":"N/A (non-code task)","output":"..."}` 形态(command 字段存在即可通过 W1-D 校验;redEvidence 缺失仍会被 W1-D 拦截,因此必须显式提供此形态而非省略字段)。
149
149
  > **Return Contract 的 completedChecks 统一契约**:子代理回传的 `completedChecks` 必须包含 `required-skill:subagent-execute.flow-comet-dev`——execute(串行委托)与 subagent-execute(并行委托)的 handoff 统一记录在 subagent-execute 证据库(共用证据库语义),guard 的 W1-D 对全部委托结果统一校验该契约。取值与节点自证命名(本节点自身证据用的 `required-skill:execute.flow-comet-dev`,见 Required Skill Calls)无关。**格式要求**:`completedChecks` 必须是**字符串数组**(如 `["required-skill:subagent-execute.flow-comet-dev"]`)——对象数组(如 `[{id, status}]`)会被 guard 的严格比较判"缺"→ exit BLOCKED。示例:
150
150
  >
151
151
  > - 正确:`"completedChecks": ["required-skill:subagent-execute.flow-comet-dev"]`
@@ -174,7 +174,7 @@ This node is truly done when:
174
174
  - **Agent thought**: "I see a bug in an adjacent file, let me fix it along the way." **Actual risk**: "Fixing along the way" without a new task or CHANGE violates R7.1 (scope control). Must stop and create a new task or CHANGE.
175
175
  - **Agent thought**: "This task is taking long, let me skip the self-review." **Actual risk**: Skipping self-review defers quality issues to the review node, where they become Critical items requiring fix tasks. Better to catch early.
176
176
  - **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
177
- - **Agent thought**: "同时发 request 和启动子代理,省一个来回。" **Actual risk**: 先让 request 成功,再启动子代理——禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all`);这是执行纪律,不是机制拦截(平台层没有挂点,引擎不替你排队)。与它相邻的另一件事已是机制保证:`result` 在写盘前校验该任务有 request 记录,缺失即新 change BLOCKED 并给出补 request 的恢复句。The order is mandatory: **a successful request first, then launch the subagent**, **never inside one concurrent call**; this is **execution discipline, not a mechanism interception** — the platform tool layer has no hook point to enforce it.
177
+ - **Agent thought**: "同时发 request 和启动子代理,省一个来回。" **Actual risk**: 先让 request 成功,再启动子代理——禁止把 request 与子代理启动放进同一个并发调用(例如 `Promise.all`);这是执行纪律,不是机制拦截(平台层没有挂点,引擎不替你排队)。与它相邻的另一件事已是机制保证:`result` 在写盘前校验该任务有 request 记录,缺失即 BLOCKED 并给出补 request 的恢复句。The order is mandatory: **a successful request first, then launch the subagent**, **never inside one concurrent call**; this is **execution discipline, not a mechanism interception** — the platform tool layer has no hook point to enforce it.
178
178
 
179
179
  ## 修复回路状态机路径
180
180
 
@@ -246,7 +246,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record execute '{"summ
246
246
  | Guardrail ID | Label | Validation Type |
247
247
  |--------------|-------|-----------------|
248
248
  | `build-evidence` | At least one SUMMARY.md produced | artifact-exists |
249
- | `all-tasks-done` | All tasks in TASK.md have status="done"(pending 串行任务 → BLOCKED);done 任务须有对应 SUMMARY(新 change 强制 BLOCKED,旧 change WARN 渐进) | content-check |
249
+ | `all-tasks-done` | All tasks in TASK.md have status="done"(pending 串行任务 → BLOCKED);done 任务须有对应 SUMMARY(一律 BLOCKED,同一形态一个判级) | content-check |
250
250
  | `verify-output-real` | Every SUMMARY.md has verify output (not fabricated) | 结构级(guard 强制:`## verify 输出` 段在场且正文非空,骨架校验同批拦截);输出是否真实由 review 把关(伪造不可机检) |
251
251
  | `no-design-changes` | REQUIREMENT.md and DESIGN.md not modified | 执行纪律(review 把关),guard 不校验 |
252
252
  | `self-check-method` | Every SUMMARY.md declares `## 自检方法`(brooks-review / cache-brooks / builtin-quickcheck) | W1-B 段级校验 |
@@ -34,10 +34,16 @@ description: "flow-kit INTEGRATION 阶段协议:集成验证 + UAT + 失败诊
34
34
 
35
35
  ### 归档(archive 阶段)
36
36
 
37
- 1. `.specs/<change-id>/` → `.specs/archive/<YYYY-MM-DD>-<change-id>/`
38
- 2. `.specs/CHANGELOG.md` 顶部按日期倒序插入一行——**跟随项目既有格式**(非表格格式同样在顶部插入,不强制转表格;guard 的倒序检测只针对表格格式行)——完整协议见 `flow-comet-archive` 册
39
- 3. **不归档** `.specs/LESSONS.md`(项目级常驻)
40
- 4. DESIGN.md § 9 架构沉淀建议留待 A-evolve 批量同步
37
+ > **硬规则(先于任何动作)**:archive 节点的**技能加载声明必须先于任何动作,尤其先于搬目录**——先用 Skill 工具加载 `flow-comet-integration`,再照抄 `flow-comet-archive` 册的 `skill-load` 命令写下声明标记,之后才开始下面的步骤。移动目录之后补声明 / 补记录仍可完成(引擎按状态判身份、按解析到的目录读写标记),但那是**恢复路径**;规范顺序永远是**先记录、后搬目录**。
38
+
39
+ 1. **准备**:LESSONS 提名(本册上段)与遗留清单(`KNOWN-ISSUES.md`)就位——本步只写工件,不动目录。
40
+ 2. **记录**:`node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` 写下归档证据——**搬目录之前的最后一件证据动作**。
41
+ 3. **搬目录**:`.specs/<change-id>/` → `.specs/archive/<YYYY-MM-DD>-<change-id>/`——本流程唯一的不可逆动作,排在声明与记录之后。
42
+ 4. **登记**:`.specs/CHANGELOG.md` 顶部按日期倒序插入一行——**跟随项目既有格式**(非表格格式同样在顶部插入,不强制转表格;guard 的倒序检测只针对表格格式行)——完整协议见 `flow-comet-archive` 册;**不归档** `.specs/LESSONS.md`(项目级常驻)。
43
+ 5. **通知与出口**:向用户列出遗留清单并告知沉淀候选 → `workflow-guard.mjs exit archive --apply`(**搬目录仍是 `exit` 的前置**)。
44
+ - 出口打印 `NEXT: done` 之后的**交接**:步骤权威在 `flow-comet-archive` 册的「归档完成后的交接」段(触发时机 / 顺序 / 不阻断归档 / 不做任何分支操作),载体探测与操作矩阵见 `../flow-comet/reference/post-archive-handoff.md`;本步的 exit 顺序与出口判据不变。
45
+
46
+ DESIGN.md § 9 架构沉淀建议留待 A-evolve 批量同步。
41
47
 
42
48
  ## 产物
43
49
 
@@ -35,7 +35,7 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
35
35
 
36
36
  在波次散文一致性、依赖图(`depends_on` 无环且引用存在)、7 字段同层,plan 出口还做文件级依赖检测:
37
37
 
38
- - **写写强判**:本趟可运行的并行 pending 任务 `write_files` 有交集 → 新 change BLOCKED(消息含任务 id 对 × 重叠路径与恢复指引「补显式 depends_on 或拆为串行任务」);旧 change WARN 渐进不阻断。
38
+ - **写写强判**:本趟可运行的并行 pending 任务 `write_files` 有交集 → 一律 BLOCKED(消息含任务 id 对 × 重叠路径与恢复指引「补显式 depends_on 或拆为串行任务」;同一形态一个判级)。
39
39
  - **读写弱判**:仅对**无显式 depends_on 关联**的并行对探测一方 `read_files` 命中对方 `write_files` → WARN 提示(建议补显式 depends_on 声明),不 BLOCK;有显式关联=依赖已声明,跳过(合法拓扑零新增告警)。
40
40
  - **路径按声明实际解析**:不做扩展名白名单过滤——txt/log/无扩展名路径同等检出(链式重命名事故面闭合)。
41
41
  - **并存不干扰**:伪并行 WARN(并行任务全部仅写测试产物)与 read∩write 弱判各自独立渐进提示;委托前写写拦截保持为第二道防线。
@@ -23,21 +23,21 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
23
23
 
24
24
  首部字段 `Change ID` / `关联` 已在场时值不得为空(键集不强制)。
25
25
 
26
- guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结构、每任务 `<verify>`、**新格式任务的 7 字段在场**、以及 TASK.md 的模板骨架(段标题 / 段序 / 首部字段值非空)都由 guard 拦(新 change 缺任一 = 出口 BLOCKED;旧格式模板 / 旧 change 渐进 WARN);「填得好不好」——字段内容质量与任务粒度——由 review 把关。
26
+ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B:任务块结构、每任务 `<verify>`、**新格式任务的 7 字段在场**、以及 TASK.md 的模板骨架(段标题 / 段序 / 首部字段值非空)都由 guard 拦(缺任一 = 出口 BLOCKED;其中 7 字段一项在「旧式一字段模板形态(无 `<name>`)」下仅 WARN——分级依据是模板形态,不是 change 新旧);「填得好不好」——字段内容质量与任务粒度——由 review 把关。
27
27
 
28
28
  > **模板权威**:本节点产出工件的段形 = **上游模板 + 本仓登记的增量段**——唯一权威 = `flow-kit/templates/**`(段与正文),条件段 / 结构子段 / 增量段与指纹由 `../flow-comet/reference/artifact-templates.json` 登记;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
29
29
 
30
30
  加载顺序:先读 `READ PROMPT:`(`3-task`),再读 `READ TEMPLATE:`(`TASK`)。
31
31
 
32
- 波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——新 change 不一致 BLOCKED(旧 change WARN 渐进)。波次投影一致性:`## 波次划分` 声明的波次必须等于任务的依赖层级(判据与恢复指引见下方「波次形态约束」)——新 change 不一致 BLOCKED(旧 change WARN 渐进);判不了按成因二分——**载体缺席**(`## 波次划分` 不在 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过),**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数);任务集里的任务还必须被某条 Wave 行覆盖(修复族除外,漏写的以「未声明」点名)。
32
+ 波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——不一致 BLOCKED(同一形态一个判级)。波次投影一致性:`## 波次划分` 声明的波次必须等于任务的依赖层级(判据与恢复指引见下方「波次形态约束」)——不一致 BLOCKED(同一形态一个判级);判不了按成因二分——**载体缺席**(`## 波次划分` 不在 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过),**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id)→ 出口打印 `TASK.md 波次划分段内容不可判`,一律 BLOCKED(同一形态一个判级);任务集里的任务还必须被某条 Wave 行覆盖(修复族除外,漏写的以「未声明」点名)。
33
33
 
34
34
  ### 波次形态约束(依赖驱动多趟 · 规划期必守)
35
35
 
36
36
  **约束本体**:并行任务按依赖关系组织——每个并行任务显式声明 `depends_on`,依赖面的合法性只取决于依赖图本身:`depends_on` 无环且引用的任务都存在,依赖面即合法;波次编号另按「波次 = 依赖层级的投影」(下一条)单独校验——依赖面合法不等于波次声明合法,两条判据各自独立拦截。全并行、全串行、串→并、并→串四种基本形态与任意混排序列(如 `S→P→S`、`P→S→P`)一律放行——引擎按依赖拓扑自动分趟(每趟委托全部依赖已满足的并行任务,趟间回串行消化),混排序列由多趟路由按依赖拓扑自动分趟消化,并行任务的先后位置不受任何限制。
37
37
 
38
- **波次 = 依赖层级的投影(波次编号的判据)**:`## 波次划分` 里的波次编号不是自由排版,而是任务依赖层级的投影——① 每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);② 同波任务必须彼此没有依赖;③ 想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 新 change 出口 **BLOCKED**:明细逐条点名「任务 / 依赖 / 当前波 / 应到波」,并给两条恢复出路——把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来(要保留当前波次,就把「它为何排在后面」的依赖写成显式 `depends_on`);旧 change 只 WARN 渐进。**判不了按成因二分**:**载体缺席**(无 `## 波次划分` 段 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id——正文只写 `N/A`、Wave 行点的是不存在的 id、行首强调记号让 Wave 行不成立)→ 出口打印 `TASK.md 波次划分段内容不可判`,新 change BLOCKED / 旧 change WARN 渐进(该行进入 WARN 计数)。**覆盖义务**:TASK 里的每个非修复族任务都必须被某个 Wave 行覆盖(修复族不要求排进波次),漏写的任务在明细里以「未声明」的当前波逐条点名——没有「当前波」可挪,恢复出路是把它写进应到波的 Wave 行。`replan` 重校走同一判据、同一报文,不豁免。**与混排合法化并存**:本条只要求「波次编号与依赖层级一致」,不恢复旧的「并行块必须连续成组」形态约束——上面的串→并→串混排照旧合法,并行任务的先后位置照旧不受限制。
38
+ **波次 = 依赖层级的投影(波次编号的判据)**:`## 波次划分` 里的波次编号不是自由排版,而是任务依赖层级的投影——① 每个任务的波次 = 其依赖中最晚波次的下一波(无依赖 = 第 1 波);② 同波任务必须彼此没有依赖;③ 想让某任务晚一点跑,就写 `depends_on` 把顺序声明出来,而不是把它挪到后面的波却不声明。声明波次与依赖层级不一致(同波依赖 / 排在依赖之前 / 明明只需更早波次却排得更靠后)→ 出口 **BLOCKED**:明细逐条点名「任务 / 依赖 / 当前波 / 应到波」,并给两条恢复出路——把该任务移到第 N 波,或补 `depends_on` 把顺序声明出来(要保留当前波次,就把「它为何排在后面」的依赖写成显式 `depends_on`)。**判不了按成因二分**:**载体缺席**(无 `## 波次划分` 段 / 段名无从派生)→ 打印「未校验(无波次段)」并跳过该判据(未验证 ≠ 通过);**内容不可判**(段在场而没有一行 Wave 行能落到真实任务 id——正文只写 `N/A`、Wave 行点的是不存在的 id、行首强调记号让 Wave 行不成立)→ 出口打印 `TASK.md 波次划分段内容不可判`,一律 BLOCKED(同一形态一个判级)。**覆盖义务**:TASK 里的每个非修复族任务都必须被某个 Wave 行覆盖(修复族不要求排进波次),漏写的任务在明细里以「未声明」的当前波逐条点名——没有「当前波」可挪,恢复出路是把它写进应到波的 Wave 行。`replan` 重校走同一判据、同一报文,不豁免。**与混排合法化并存**:本条只要求「波次编号与依赖层级一致」,不恢复旧的「并行块必须连续成组」形态约束——上面的串→并→串混排照旧合法,并行任务的先后位置照旧不受限制。
39
39
 
40
- **硬性拦截(规划出口 BLOCKED,附恢复指引)**:任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见上表;新 change 缺任一即 BLOCKED,旧格式模板 / 旧 change 渐进 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)/ 波次声明与依赖层级不一致(明细与两条恢复出路见上一条)——任一项不成立即在规划出口被 BLOCKED(读写重叠仅 WARN),按提示修正后重新 exit 即可通过。任务间依赖不得成环(如 A→B→A),也不得构成不可满足的依赖链。
40
+ **硬性拦截(规划出口 BLOCKED,附恢复指引)**:任务块结构(至少一个 `<task>` 块)/ 每任务 `<verify>` 字段 / 新格式任务的 7 字段在场(集合见上表;缺任一即 BLOCKED——7 字段一项在旧式一字段模板形态下仅 WARN)/ 任务图依赖环 / 缺失依赖(`depends_on` 引用不存在的任务 id)/ 并行写写冲突(并行任务 `write_files` 重叠)/ 波次声明与依赖层级不一致(明细与两条恢复出路见上一条)——任一项不成立即在规划出口被 BLOCKED(读写重叠仅 WARN),按提示修正后重新 exit 即可通过。任务间依赖不得成环(如 A→B→A),也不得构成不可满足的依赖链。
41
41
 
42
42
  **警示**:落笔时先画依赖方向再标 [P],避免出口返工。
43
43
 
@@ -95,7 +95,7 @@ This node decomposes the technical design into atomic, executable tasks with cle
95
95
  - Flow-comet override: the permissive flow-kit upstream semantics — "no conflict ⇒ [P]" and "same layer = same wave, parallel" — are superseded by this node's rule; the vendored upstream files stay read-only and are not modified.
96
96
  - Output wave diagram: `Wave 1: T01[P], T02[P]` etc.; isolated tasks appear as serial steps.
97
97
 
98
- A declared wave that disagrees with the dependency level — a same-wave dependency, a task placed before its dependency, or a conservative placement later than needed — blocks a new change at the plan exit: every mismatch is named as task / dependencies / declared wave / expected wave, together with the two ways out (move it to wave N, or add the `depends_on` that explains the order), while an older change only warns. When the section is absent (no `## 波次划分` section, or its name cannot be derived), the exit prints "not checked (no wave section)" and skips the rule — unverified is not a pass. When the section is present but no Wave line resolves to a real task (a body that only says N/A, a line naming an unknown id, a leading emphasis mark that breaks the line), the content cannot be judged: a new change blocks there, an older change warns, and that warning is counted with the other warnings. Every task in the set must be covered by some Wave line (the fix-task family excepted); a task the section never mentions is named with "undeclared" as its current wave, and the way out is to write it into the wave it should reach. `replan` runs the same judgement with the same wording. This rule constrains the agreement between wave numbers and dependency levels only: it does not bring back the old "parallel blocks must be contiguous" shape constraint, so the mixed-sequence freedom above stands (serial → parallel → serial stays legal).
98
+ A declared wave that disagrees with the dependency level — a same-wave dependency, a task placed before its dependency, or a conservative placement later than needed — blocks at the plan exit: every mismatch is named as task / dependencies / declared wave / expected wave, together with the two ways out (move it to wave N, or add the `depends_on` that explains the order). When the section is absent (no `## 波次划分` section, or its name cannot be derived), the exit prints "not checked (no wave section)" and skips the rule — unverified is not a pass. When the section is present but no Wave line resolves to a real task (a body that only says N/A, a line naming an unknown id, a leading emphasis mark that breaks the line), the content cannot be judged: it blocks there. Every task in the set must be covered by some Wave line (the fix-task family excepted); a task the section never mentions is named with "undeclared" as its current wave, and the way out is to write it into the wave it should reach. `replan` runs the same judgement with the same wording. This rule constrains the agreement between wave numbers and dependency levels only: it does not bring back the old "parallel blocks must be contiguous" shape constraint, so the mixed-sequence freedom above stands (serial → parallel → serial stays legal).
99
99
 
100
100
  8. **LESSONS scan**: Grep `.specs/LESSONS.md` for keywords related to planned file paths or actions. If active lessons hit, declare difference or confirm still applies.
101
101
 
@@ -106,12 +106,12 @@ The full task decomposition protocol, XML template, and constraints are in:
106
106
 
107
107
  This node is truly done when:
108
108
  - `.specs/<change-id>/TASK.md` exists in XML format.
109
- - 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.
109
+ - 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 = exit BLOCKED; a task set written in the old one-field template shape degrades to WARN — that tier follows the template shape, not the age of the change), while **field content quality** is judged by review.
110
110
  - Every `verify` field is an executable command (not a description).
111
111
  - Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
112
112
  - 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).
113
113
  - Wave division diagram is clear and has no circular dependencies.
114
- - Wave numbers agree with dependency levels: each wave is one past the latest dependency wave, and tasks sharing a wave have no dependencies between them (an absent wave section is reported as "not checked", never as a pass; a section whose content cannot be judged blocks a new change and only warns on an older change).
114
+ - Wave numbers agree with dependency levels: each wave is one past the latest dependency wave, and tasks sharing a wave have no dependencies between them (an absent wave section is reported as "not checked", never as a pass; a section whose content cannot be judged blocks).
115
115
  - Task numbering is continuous.
116
116
 
117
117
  ### Red flags
@@ -171,7 +171,7 @@ node .claude/skills/flow-comet/scripts/workflow-state.mjs record plan '{"summary
171
171
  | Guardrail ID | Label | Validation Type |
172
172
  |--------------|-------|-----------------|
173
173
  | `plan-artifacts` | TASK.md exists with XML tasks | artifact-exists |
174
- | `task-fields-complete` | All tasks have 7 required fields | 结构在场(新格式任务缺任一字段 = 出口 BLOCKED;旧格式模板 / 旧 change 渐进 WARN)——**字段内容质量**由 review 把关 |
174
+ | `task-fields-complete` | All tasks have 7 required fields | 结构在场(新格式任务缺任一字段 = 出口 BLOCKED;旧式一字段模板形态的缺项仅 WARN——按模板形态分级)——**字段内容质量**由 review 把关 |
175
175
  | `write-files-safe` | No write_files in DESIGN forbidden list | 执行纪律(review 把关),guard 不校验 |
176
176
  | `has-parallel` | At least 1 [P] task (if applicable) | 执行纪律(review 把关),guard 不校验 |
177
177