flow-comet 1.6.2 → 1.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
  2. package/.flow-comet/skills/flow-comet/SKILL.md +64 -46
  3. package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
  4. package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
  5. package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
  6. package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +18 -28
  7. package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
  8. package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
  9. package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
  10. package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
  11. package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +260 -17
  12. package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +2714 -161
  13. package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +51 -4
  14. package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +13 -0
  15. package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +877 -10
  16. package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +52 -4
  17. package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +111 -4
  18. package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +108 -2
  19. package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
  20. package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -3
  21. package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
  22. package/.flow-comet/skills/flow-comet-design/SKILL.md +6 -6
  23. package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
  24. package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
  25. package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
  26. package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
  27. package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
  28. package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
  29. package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
  30. package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
  31. package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +3 -3
  32. package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
  33. package/README.md +4 -4
  34. package/package.json +1 -1
  35. package/scripts/dsh-bridge.mjs +59 -26
  36. package/scripts/prepare-env.mjs +165 -1
  37. package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
  38. package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
  39. package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
  40. package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
  41. package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
  42. package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
  43. package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
@@ -2,7 +2,7 @@
2
2
  import { constants as fsConstants, promises as fs } from 'fs';
3
3
  import path from 'path';
4
4
  import { fileURLToPath } from 'url';
5
- import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, RUNTIME_STATE_PATH, LEGACY_RUNTIME_STATE_PATH, resolveProtocolPathWithState, hasProtocolCliArg } from './state-schema.mjs';
5
+ import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, RUNTIME_STATE_PATH, LEGACY_RUNTIME_STATE_PATH, resolveProtocolPathWithState, hasProtocolCliArg, handoffRequestWithdrawn } from './state-schema.mjs';
6
6
  import { readProtocolFile, validateProtocolSchema, NODE_PROTOCOL_FILES, workflowPathInside, inspectWorkflowProtectedPath, readWorkflowProtectedFile, workflowFileObjectIdentity, workflowSameFileObject, workflowSameFileStat } from './protocol-utils.mjs';
7
7
  import { taskOpeningAttrs, taskBlocks as extractTaskBlocks } from './task-parsing.mjs';
8
8
  import { resolveNextNode, resolveFixRollbackDecision, resolveFixRollbackState, applyFixRollbackRound, resolveFixReturnNode, EXECUTE_FAMILY_NODE_IDS, TASK_SET_SIGNATURE_ALGO, taskSetSignature, parseTaskSetSignature, sameTaskSetSignature, taskSetSignatureVersionSkew, classifyFixReturnCause, normalizeHeading, FIX_SECTION_TITLE_FALLBACK, analyzeDependencyGraph, findParallelWriteConflicts } from './route-node.mjs';
@@ -645,6 +645,26 @@ function hasNonEmptyHandoffResult(evidence) {
645
645
  );
646
646
  }
647
647
 
648
+ // AC-8 在飞委托判定(验证隔离「同一时刻只有一个写者」)——handoffRequests 中存在条目而
649
+ // handoffResult 无对应记录 = 写者未收工的既有可判形态。判据单处求值(出口校验唯一消费方)。
650
+ // 三态收敛:无 evidence['subagent-execute'] / 无 handoffRequests 条目 ⇒ 返回空数组(调用方零输出,
651
+ // 不制造噪音);全部有对应 result ⇒ 同样空数组(放行)。锚定既有字段,零新增 state 顶层字段。
652
+ // 已撤回的 request 不构成在飞委托(2026-10-07 补撤回通道):零提交复验失败 / 写边界被拒之后
653
+ // request 可能留在「有 request 无 result」态而命令面无从撤回——`workflow-handoff.mjs withdraw`
654
+ // 在原地落留痕(withdrawnAt + withdrawnBy,历史不删),守卫据此放行出口。判据复用
655
+ // state-schema.mjs 的单一实现(撤回留痕两字段齐备才算撤回),本文件不另写一份。
656
+ function inFlightHandoffRequests(evidence) {
657
+ const requests = evidence && typeof evidence === 'object' ? evidence.handoffRequests : null;
658
+ if (!requests || typeof requests !== 'object' || Array.isArray(requests)) return [];
659
+ const results = evidence.handoffResult && typeof evidence.handoffResult === 'object' && !Array.isArray(evidence.handoffResult)
660
+ ? evidence.handoffResult
661
+ : {};
662
+ return Object.keys(requests).filter((taskId) => {
663
+ if (handoffRequestWithdrawn(requests[taskId])) return false;
664
+ return results[taskId] === undefined || results[taskId] === null;
665
+ });
666
+ }
667
+
648
668
  function schemaMap(protocol) {
649
669
  return new Map((protocol.outputSchemas ?? []).map((schema) => [schema.id, schema]));
650
670
  }
@@ -1642,7 +1662,11 @@ async function main() {
1642
1662
  // 波次散文一致性检测: 波次散文一致性检测(WARN 渐进)——## 波次划分 的 Wave 行任务带 [P] 标记
1643
1663
  // (并行语义)但 XML 任务无 parallel="true" → WARN(散文与机器路由依据不一致,以任务
1644
1664
  // 标记为准)。容错:无并行语义的 Wave 行不参与比对;解析不到波次段跳过(不误报)。
1645
- const waveSection = content.match(/##\s*波次划分\s*\n([\s\S]*?)(?=\n##\s|\n---|\Z)/);
1665
+ // 段尾判定 = 下一个段标题(\n## )或分隔线(\n---)或**输入末尾**。JS 正则没有 \Z:
1666
+ // \Z 是「未知转义 ⇒ 字面字符 Z」,惰性匹配一遇段内大写 Z 就提前收尾,段被静默截断
1667
+ // (含 ZERO- 一类机检标记的 TASK 会整段漏检)。串尾一律用 (?![\s\S]) 真断言——
1668
+ // 它只是「此处之后已无任何字符」,不受行首/行尾标志影响,与「多行模式下的 $」语义无歧义。
1669
+ const waveSection = content.match(/##\s*波次划分\s*\n([\s\S]*?)(?=\n##\s|\n---|(?![\s\S]))/);
1646
1670
  if (waveSection) {
1647
1671
  const proseParallelIds = [];
1648
1672
  for (const line of waveSection[1].split('\n')) {
@@ -1804,6 +1828,26 @@ async function main() {
1804
1828
  }
1805
1829
  }
1806
1830
  }
1831
+ // W1-E: 验证隔离「同一时刻只有一个写者」出口校验(AC-8 · 判级决策见 ADR-014)——读
1832
+ // state.evidence['subagent-execute'].handoffRequests:存在条目且**至少一个无对应 handoffResult**
1833
+ // ⇒ 在飞委托(写者未收工,跑全量判据会被未提交中间态污染):新 change BLOCKED(含恢复指引
1834
+ // 「待写入者收工后重跑 / 已作废则撤回」)/ 旧 change WARN 渐进;全部有对应 result ⇒ 放行;
1835
+ // 已撤回(withdrawnAt + withdrawnBy 齐备)的 request 不构成在飞委托 ⇒ 放行;无该证据对象 ⇒ 零输出。
1836
+ // 落点 = 出口校验流(与其余 violations / WARN 同风格,不新增独立命令面);判据经
1837
+ // inFlightHandoffRequests 单处求值(与 W1-D 的 result 侧契约校验正交,不重复判定)。
1838
+ if (EXECUTE_FAMILY_NODE_IDS.has(node.id)) {
1839
+ const inFlight = inFlightHandoffRequests(state.evidence?.['subagent-execute']);
1840
+ if (inFlight.length > 0) {
1841
+ const inFlightDetail = '存在在飞委托(handoffRequests 有 request 无对应 handoffResult): '
1842
+ + inFlight.join(', ') + '——验证隔离要求同一时刻只有一个写者(写者未收工)';
1843
+ if (isNewChange(state)) {
1844
+ console.error('BLOCKED: ' + inFlightDetail);
1845
+ console.error('恢复: 待写入者收工后重跑——子代理回传后用 workflow-handoff.mjs result <task-id> <Return Contract> 记录结果再重试 exit;若该委托已作废(零提交复验失败 / 写边界被拒后遗弃),用 workflow-handoff.mjs withdraw <task-id> --by <来源> [--reason <原因>] 撤回后再重试 exit(撤回留痕 withdrawnAt/withdrawnBy,已撤回 = 终态,历史不删)');
1846
+ process.exit(1);
1847
+ }
1848
+ console.error('WARN: ' + inFlightDetail + '(旧 change 渐进不阻断;待写入者收工后重跑全量判据;已作废的委托可用 workflow-handoff.mjs withdraw <task-id> --by <来源> 撤回)');
1849
+ }
1850
+ }
1807
1851
  // W1-B: execute / subagent-execute 出口校验每份 SUMMARY 含三个必填段 + 6 维自查非空 + 自检方法
1808
1852
  if (EXECUTE_FAMILY_NODE_IDS.has(node.id)) {
1809
1853
  const changeDir = path.join(runRoot, '.specs', state.activeChange ?? '');
@@ -1814,7 +1858,9 @@ async function main() {
1814
1858
  try {
1815
1859
  const content = await fs.readFile(path.join(changeDir, f), 'utf8');
1816
1860
  // 段终止 lookahead 用 \n##\s(而非 \n##):###/#### 级子标题(如 "### 🟢 R1")是段内内容,不是段结束
1817
- const sixDim = content.match(/##\s*6\s*维自查[\s\S]*?(?=\n##\s|\n---|\Z)/i);
1861
+ // 段尾同样 = 段标题 / 分隔线 / 输入末尾;末尾一律写 (?![\s\S]),不得写 \Z
1862
+ // (JS 无 \Z——它是「字面字符 Z」,且本正则带 i 标志,连小写 z 都会命中,段被静默截断)
1863
+ const sixDim = content.match(/##\s*6\s*维自查[\s\S]*?(?=\n##\s|\n---|(?![\s\S]))/i);
1818
1864
  // C1: 6 维自查段非空——去掉所有标题行后剩余实质内容 ≥ 10 字符
1819
1865
  // 按行过滤标题(/^\s*#/)比正则替换稳健:任何标题格式(emoji 🟢/中英文/数字)都不计入内容
1820
1866
  const dimBody = sixDim ? sixDim[0].split('\n').filter(l => !/^\s*#/.test(l)).join('').trim() : '';
@@ -2364,7 +2410,9 @@ async function main() {
2364
2410
  if (broken.length > 0) {
2365
2411
  if (planNewFormat) {
2366
2412
  if (isNewChange(state)) {
2367
- console.error('BLOCKED: TASK.md 任务缺 7 字段(name/read_files/write_files/action/verify/done/depends_on): ' + broken.join('; '));
2413
+ // 文案的集合字符串**从判据常量派生**(不得在此再写一遍字面集合——第二处同口径表达会在
2414
+ // 判据演进时静默落后于实现;构造方式不改变渲染结果)。
2415
+ console.error('BLOCKED: TASK.md 任务缺 7 字段(' + TASK7_REQUIRED.join('/') + '): ' + broken.join('; '));
2368
2416
  console.error('恢复: 对照 flow-kit/templates/TASK.md 补齐每个 <task> 的缺字段后重试 exit;新 change 强制任务块结构完整');
2369
2417
  process.exit(1);
2370
2418
  }
@@ -3,7 +3,7 @@ import { execFileSync } from 'child_process';
3
3
  import { promises as fs } from 'fs';
4
4
  import path from 'path';
5
5
  import { fileURLToPath } from 'url';
6
- import { validateStateFields, looksLikeObjectLiteral, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, resolveProtocolPathWithState } from './state-schema.mjs';
6
+ import { validateStateFields, looksLikeObjectLiteral, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, resolveProtocolPathWithState, handoffRequestWithdrawn } from './state-schema.mjs';
7
7
  import { EXECUTE_FAMILY_NODE_IDS, protocolNodeEnabled, resolveDelegationTarget, taskDependencyEligibility } from './route-node.mjs';
8
8
  import {
9
9
  readProtocolFile,
@@ -11,12 +11,16 @@ import {
11
11
  inspectWorkflowPathSegments,
12
12
  } from './protocol-utils.mjs';
13
13
  import { taskAttrsById, taskBlocks, taskOpeningAttrs } from './task-parsing.mjs';
14
+ // 时间形态单一权威(新增写入路径一律走本模块,禁自行拼接):撤回留痕的时刻生成走 nowTimestamp,
15
+ // 人可见回显走 formatLocalTimestamp(本地时间 + 显式偏移),解析走 parseTimestamp。
16
+ import { nowTimestamp, formatLocalTimestamp, parseTimestamp } from './time-utils.mjs';
14
17
 
15
18
  // workflow-handoff.mjs: Record subagent handoff evidence
16
19
  // evidence 统一记录在 subagent-execute 名下作为委托证据库——execute(串行委托)与 subagent-execute(并行委托)共用。不改成节点参数,保持最小改动。
17
20
  // Usage:
18
21
  // node workflow-handoff.mjs request <task-id> <description> [--write-files <files...>] -- record handoff request (W2-D: optional writeFiles allow-list)
19
22
  // node workflow-handoff.mjs result <task-id> <result-or-JSON> -- record handoff result (W1-D: JSON Return Contract; W2-D: commitHash subset check; : completedChecks 规范化; redEvidence 时间顺序校验)
23
+ // node workflow-handoff.mjs withdraw <task-id> --by <source> [--reason <text>] -- 撤回被遗弃的 request(前置:目标无 handoffResult——已收工者拒绝撤回;留痕:withdrawnAt + withdrawnBy;已撤回 = 终态)
20
24
  // node workflow-handoff.mjs status -- show all handoff evidence
21
25
 
22
26
  // 归属门禁读取协议用:与其它脚本同源(packageRoot 默认协议;env 可覆盖),不消费 request 参数。
@@ -234,7 +238,12 @@ async function revalidateResultZeroCommit(state, taskId, handoffReq) {
234
238
  // 避免 WARN 声称已撤销而 state 仍是旧值。
235
239
  await writeState(state);
236
240
  const reasonText = ZERO_COMMIT_REVOKE_REASON_TEXT[verdict.reason] || verdict.reason;
237
- const detail = '任务 ' + taskId + ' 零提交资格 result 重验失败(' + reasonText + ')——request evidence noCommit=false, revokedAt=' + handoffReq.revokedAt + ', revokeReason=' + verdict.reason;
241
+ // 人可见时间戳一律本地时间 + 显式偏移(时间纪律):revokedAt 是既有的机器字段(历史 Z 形态,
242
+ // 同族迁移窗口内保持原样),但把它原样拼进这条给人看的消息即违反人可见口径——此处按标准形态
243
+ // 回显;历史值不可解析时回显原值(可见降级,不静默改写、不谎称已格式化)。
244
+ const revokedAtMs = parseTimestamp(handoffReq.revokedAt);
245
+ const revokedAtDisplay = Number.isNaN(revokedAtMs) ? String(handoffReq.revokedAt) : formatLocalTimestamp(revokedAtMs);
246
+ const detail = '任务 ' + taskId + ' 零提交资格 result 重验失败(' + reasonText + ')——request evidence noCommit=false, revokedAt=' + revokedAtDisplay + ', revokeReason=' + verdict.reason;
238
247
  if (state.newChange === true) {
239
248
  // 新 change 只落 request 资格撤销;此刻尚未默认 handoffResult,确保「不落 result」不是文案承诺
240
249
  console.error('HANDOFF ERROR: ' + detail + ';新 change 不落 result,出口校验不再豁免缺 commitHash。恢复: 修正 write_files / .gitignore 与路径形态后重新 request,或回传含合法 commitHash 的 Return Contract');
@@ -496,10 +505,24 @@ async function main() {
496
505
  // 记 noCommit:true;不具资格 → 不记 noCommit、不阻断原流程(保持既有完整提交子集校验)。
497
506
  const literalIgnoredEligible = taskResolved && writeFiles.length > 0
498
507
  && (await classifyWriteFilesProvablyIgnored(writeFiles)).eligible;
508
+ // 撤回后再委托:新 request 覆盖当前态,但**不静默删除**撤回历史——已撤回记录的留痕转入
509
+ // previousWithdrawals 数组(加法式保留,可审计「撤回 → 重新委托」的顺序)。
510
+ const priorRecord = state.evidence['subagent-execute'].handoffRequests[taskId];
511
+ const priorWithdrawals = priorRecord && Array.isArray(priorRecord.previousWithdrawals)
512
+ ? priorRecord.previousWithdrawals
513
+ : [];
514
+ const carriedWithdrawals = handoffRequestWithdrawn(priorRecord)
515
+ ? [...priorWithdrawals, {
516
+ withdrawnAt: priorRecord.withdrawnAt,
517
+ withdrawnBy: priorRecord.withdrawnBy,
518
+ ...(priorRecord.withdrawReason ? { withdrawReason: priorRecord.withdrawReason } : {}),
519
+ }]
520
+ : priorWithdrawals;
499
521
  state.evidence['subagent-execute'].handoffRequests[taskId] = {
500
522
  description, requestedAt: new Date().toISOString(),
501
523
  ...(writeFiles.length ? { writeFiles } : {}),
502
- ...(zeroEligible || literalIgnoredEligible ? { noCommit: true } : {})
524
+ ...(zeroEligible || literalIgnoredEligible ? { noCommit: true } : {}),
525
+ ...(carriedWithdrawals.length ? { previousWithdrawals: carriedWithdrawals } : {})
503
526
  };
504
527
  await writeState(state);
505
528
  if (literalIgnoredEligible) {
@@ -551,6 +574,16 @@ async function main() {
551
574
  state.evidence['subagent-execute'] = state.evidence['subagent-execute'] || {};
552
575
  const handoffReq = state.evidence['subagent-execute'].handoffRequests?.[taskId];
553
576
  const hasRequest = !!handoffReq && typeof handoffReq === 'object';
577
+ // 已撤回 = 终态(撤回通道的闭合半边):撤回后的 request 不再接受 result——否则被撤回的委托
578
+ // 可被事后「复活」,撤回语义与守卫的放行判据(同一判据)分叉。要重新委托该任务须重新 request
579
+ // (新 request 记录会覆盖该 taskId 的当前态,撤回留痕以「撤回后重新委托」的顺序可审计)。
580
+ if (handoffRequestWithdrawn(handoffReq)) {
581
+ console.error('BLOCKED: 任务 ' + taskId + ' 的委托已撤回(终态)——不再接受 result'
582
+ + '(withdrawnAt=' + handoffReq.withdrawnAt + ', withdrawnBy=' + handoffReq.withdrawnBy + ')'
583
+ + ';恢复: 若该任务仍需执行,重新发起 workflow-handoff.mjs request ' + taskId
584
+ + ' <description> 后再回传结果');
585
+ process.exit(1);
586
+ }
554
587
  // m-13:result 重验在默认 handoffResult 之前——新 change 失败路径只落 request.noCommit=false,
555
588
  // 不落下空 handoffResult 充当 result 载体;重验通过/旧 change 之后才初始化结果容器。
556
589
  if (await revalidateResultZeroCommit(state, taskId, handoffReq) === 'block') process.exit(1);
@@ -680,6 +713,80 @@ async function main() {
680
713
  return;
681
714
  }
682
715
 
716
+ if (action === 'withdraw') {
717
+ // 撤回通道(受支持的出口解卡路径):零提交复验失败 / 写边界被拒之后,request 可能留在
718
+ // 「有 request 无 result」态而命令面无从撤回——守卫的出口校验据此永久卡住。本动作在原记录上
719
+ // **加法式**落留痕(withdrawnAt 时间戳 + withdrawnBy 来源,可选 withdrawReason),**不删除**
720
+ // 任何历史字段(description / requestedAt / writeFiles / noCommit 原样保留);守卫按同一判据
721
+ // (state-schema.handoffRequestWithdrawn)把已撤回的 request 排除在在飞委托之外。
722
+ // 已撤回 = **终态**:重复撤回被拒(不改写既有留痕),已撤回的 request 也不再接受 result。
723
+ // 适用面自洽(前置拒绝):可撤回的只有**在飞且被遗弃**的 request——已在册 handoffResult 的
724
+ // 委托(已收工)不在其列:对已收工的委托落撤回落痕,只会在同一 taskId 上造出「result 与
725
+ // withdrawnAt/withdrawnBy 并存」的组合态,而没有任何判据消费它(守卫的在飞判据只读 request
726
+ // 侧,越俎代庖检测只读 result 侧)。判据与守卫的在飞判据**互补**(同一把尺子,不另立一份):
727
+ // 无对应 result = 未收工 = 可撤回;显式 null 占位与「键缺失」同读为未收工(守卫在飞判据按
728
+ // undefined / null,越俎代庖检测按 falsy),故不阻断撤回——不给「出口拦 + 撤回拒」留下
729
+ // 无出口的死角。本拒绝**不删改**任何既有记录(request / result 一律原样),恢复指引见下方报文。
730
+ const taskId = process.argv[3];
731
+ const withdrawArgs = process.argv.slice(4);
732
+ let withdrawnBy = null;
733
+ let withdrawReason = null;
734
+ for (let i = 0; i < withdrawArgs.length; i++) {
735
+ const arg = withdrawArgs[i];
736
+ if (arg === '--by') { withdrawnBy = withdrawArgs[i + 1]; i += 1; continue; }
737
+ if (typeof arg === 'string' && arg.startsWith('--by=')) { withdrawnBy = arg.slice('--by='.length); continue; }
738
+ if (arg === '--reason') { withdrawReason = withdrawArgs[i + 1]; i += 1; continue; }
739
+ if (typeof arg === 'string' && arg.startsWith('--reason=')) { withdrawReason = arg.slice('--reason='.length); continue; }
740
+ }
741
+ if (!taskId) {
742
+ console.error('Usage: workflow-handoff.mjs withdraw <task-id> --by <source> [--reason <text>]');
743
+ process.exit(1);
744
+ }
745
+ if (typeof withdrawnBy !== 'string' || withdrawnBy.trim() === '') {
746
+ console.error('Usage: workflow-handoff.mjs withdraw <task-id> --by <source> [--reason <text>]——撤回须留痕来源(--by 不可缺省)');
747
+ process.exit(1);
748
+ }
749
+ const handoff = state.evidence?.['subagent-execute'];
750
+ const target = handoff && typeof handoff === 'object' && handoff.handoffRequests && typeof handoff.handoffRequests === 'object'
751
+ ? handoff.handoffRequests[taskId]
752
+ : null;
753
+ if (!target || typeof target !== 'object') {
754
+ console.error('HANDOFF ERROR: 任务 ' + taskId + ' 无对应 request 记录——无可撤回的委托(撤回只作用于已记录的 request,不新建记录)');
755
+ process.exit(1);
756
+ }
757
+ if (handoffRequestWithdrawn(target)) {
758
+ console.error('HANDOFF ERROR: 任务 ' + taskId + ' 的委托已撤回(终态)——不得重复撤回、不得改写既有撤回留痕'
759
+ + '(withdrawnAt=' + target.withdrawnAt + ', withdrawnBy=' + target.withdrawnBy + ')');
760
+ process.exit(1);
761
+ }
762
+ // 前置拒绝(适用面自洽):目标已收工(handoffResult 在场且非空占位)⇒ 拒绝撤回,报文写清
763
+ // 「为什么拒」与恢复指引。**不删改**任何既有记录:本路径在 writeState 之前退出,state 字节零改写。
764
+ const deliveredResult = handoff && typeof handoff === 'object' && handoff.handoffResult
765
+ && typeof handoff.handoffResult === 'object' && !Array.isArray(handoff.handoffResult)
766
+ ? handoff.handoffResult[taskId]
767
+ : undefined;
768
+ if (deliveredResult !== undefined && deliveredResult !== null) {
769
+ console.error('HANDOFF ERROR: 任务 ' + taskId + ' 的委托已收工(handoffResult 在场)——撤回只适用于被遗弃的'
770
+ + ' request(零提交复验失败 / 写边界被拒之后遗弃的在飞 request),已收工的委托无须撤回:其 result 已在册;'
771
+ + '恢复: 如需更正该任务的结果,走既有通道重新发起 workflow-handoff.mjs request ' + taskId
772
+ + ' <description> 后回传新的 result(新记录覆盖该任务的当前态,历史记录不删除)');
773
+ process.exit(1);
774
+ }
775
+ // 新写入路径统一走时间单一权威(本地时间 + 显式偏移):不在此自行拼接时刻字面。
776
+ target.withdrawnAt = nowTimestamp();
777
+ target.withdrawnBy = withdrawnBy.trim();
778
+ if (typeof withdrawReason === 'string' && withdrawReason.trim() !== '') {
779
+ target.withdrawReason = withdrawReason.trim();
780
+ }
781
+ await writeState(state);
782
+ console.error('HANDOFF 撤回留痕: ' + taskId + ' — withdrawnAt=' + target.withdrawnAt
783
+ + ', withdrawnBy=' + target.withdrawnBy
784
+ + (target.withdrawReason ? ', withdrawReason=' + target.withdrawReason : '')
785
+ + '(原 request 字段原样保留;已撤回 = 终态,守卫不再将其计为在飞委托)');
786
+ console.log('HANDOFF WITHDRAW: ' + taskId);
787
+ return;
788
+ }
789
+
683
790
  if (action === 'status') {
684
791
  const handoff = state.evidence?.['subagent-execute'] || {};
685
792
  console.log(JSON.stringify({
@@ -690,7 +797,7 @@ async function main() {
690
797
  return;
691
798
  }
692
799
 
693
- console.error('Unknown action: ' + action + '. Use: request, result, status');
800
+ console.error('Unknown action: ' + action + '. Use: request, result, withdraw, status');
694
801
  process.exit(1);
695
802
  }
696
803
 
@@ -799,6 +799,83 @@ async function reportIntelScanDrift(contextFile, stateValue) {
799
799
  + '同刻同形态(冲突时以 state 为准)。');
800
800
  }
801
801
 
802
+ // ---------- explain(节点现问:只读派生自协议 JSON) ----------
803
+
804
+ // 命令路径形态(平台化):权威源保持设计形态 .claude/skills/(与册子命令形态一致,安装时由
805
+ // prepare-env 的 pathReplacements 平台化);安装副本按脚本自定位输出运行根相对形态——.claude /
806
+ // .agents / .dsh 乃至将来新增的平台根同一推导覆盖,无需在此登记平台清单;落在运行根之外
807
+ // (用户级安装)时输出脚本自身的绝对路径。不得硬编码单一形态:pathReplacements 只处理 .md
808
+ // (prepare-env 的 applyPathReplacements 按扩展名过滤),脚本内的字面量在安装副本上不会被
809
+ // 替换——硬编码 .claude 会让 Codex / dsh 单平台安装的 explain 输出不存在的命令路径。
810
+ function platformScriptsDir() {
811
+ const posixDir = __dirname.replace(/\\/g, '/');
812
+ if (posixDir.includes('/.flow-comet/skills/')) return '.claude/skills/flow-comet/scripts';
813
+ const relative = path.relative(runRoot, __dirname).split(path.sep).join('/');
814
+ if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) return posixDir;
815
+ return relative;
816
+ }
817
+
818
+ // ① 该节点的 outputSchema 名与产物路径(含 evidence id)。产物根语义与状态机 / guard 的节点完成
819
+ // 判定一致:'specs-root' → .specs/;'project' / 缺省 → 项目根。悬空 schema 引用如实标注、不编造
820
+ // 产物(自定义协议允许悬空引用,route-node 的产物推导同样容忍)。
821
+ function printNodeArtifacts(protocol, node) {
822
+ const schemaById = new Map((protocol.outputSchemas ?? []).map((schema) => [schema.id, schema]));
823
+ const schemaIds = node.outputSchemas ?? [];
824
+ if (schemaIds.length === 0) console.log('OUTPUT-SCHEMA: (none)');
825
+ for (const schemaId of schemaIds) {
826
+ const schema = schemaById.get(schemaId);
827
+ console.log('OUTPUT-SCHEMA: ' + schemaId + (schema && schema.description ? ' — ' + schema.description : ''));
828
+ if (!schema) {
829
+ console.log(' ARTIFACT: (none)——协议 outputSchemas[] 未声明该 schema,无法派生产物路径');
830
+ continue;
831
+ }
832
+ for (const artifact of schema.artifacts ?? []) {
833
+ // 同一 artifact 的 paths 为互斥备选(命中任一即产物存在,与节点完成判定同语义)
834
+ const artifactRoot = artifact.pathBase === 'specs-root' ? '.specs/' : '';
835
+ const paths = (artifact.paths ?? []).map((declaredPath) => artifactRoot + String(declaredPath));
836
+ console.log(' ARTIFACT: ' + (artifact.id ?? '(unnamed)')
837
+ + (artifact.kind ? ' [' + artifact.kind + ']' : '')
838
+ + (artifact.required === false ? ' optional' : ' required')
839
+ + ' → ' + (paths.length > 0 ? paths.join(' | ') : '(未声明路径)'));
840
+ }
841
+ const evidenceIds = (schema.evidence ?? []).map((evidence) => evidence.id
842
+ + (evidence.required === false ? ' (optional)' : ' (required)'));
843
+ console.log(' EVIDENCE: ' + (evidenceIds.length > 0 ? evidenceIds.join(' | ') : '(none)'));
844
+ }
845
+ }
846
+
847
+ // ② guardrails 表(id / label / validation)
848
+ function printNodeGuardrails(node) {
849
+ const guardrails = node.guardrails ?? [];
850
+ if (guardrails.length === 0) console.log('GUARDRAIL: (none)');
851
+ for (const guardrail of guardrails) {
852
+ console.log('GUARDRAIL: ' + (guardrail.id ?? '(unnamed)') + ' | ' + (guardrail.label ?? '-')
853
+ + ' | ' + (guardrail.validation ?? '-'));
854
+ }
855
+ }
856
+
857
+ // ③ requiredSkillCalls(skill / scope / enforcement / reason)
858
+ function printNodeSkillCalls(node) {
859
+ const calls = node.requiredSkillCalls ?? [];
860
+ if (calls.length === 0) console.log('REQUIRED-SKILL: (none)');
861
+ for (const call of calls) {
862
+ console.log('REQUIRED-SKILL: ' + (call.skill ?? '(unnamed)')
863
+ + ' | scope=' + (call.scope ?? '-') + ' | enforcement=' + (call.enforcement ?? '-')
864
+ + ' | reason=' + (call.reason ?? '-'));
865
+ }
866
+ }
867
+
868
+ // ④ 三条命令(entry / exit / record,按节点 id 与平台化路径形态生成)。脚本路径整体加双引号:
869
+ // 安装根含空格时未加引号的路径会被 shell 按空格切分(只剩路径首段被当作脚本),打印出来的命令
870
+ // 便跑不了——加引号后三种平台语义下都是**单一参数**(引号本身对无空格路径无害)。
871
+ function printNodeCommands(node) {
872
+ const scriptsDir = platformScriptsDir();
873
+ console.log('COMMAND entry: node "' + scriptsDir + '/workflow-guard.mjs" entry ' + node.id);
874
+ console.log('COMMAND exit: node "' + scriptsDir + '/workflow-guard.mjs" exit ' + node.id + ' --apply');
875
+ console.log('COMMAND record: node "' + scriptsDir + '/workflow-state.mjs" record ' + node.id
876
+ + " '{\"summary\":\"<完成摘要>\"}'");
877
+ }
878
+
802
879
  async function main() {
803
880
  // 协议解析: 协议加载 = resolveProtocol 解析路径 + 受保护读取 + fail-closed schema 校验
804
881
  // (读失败/校验失败直接 throw,沿用现有错误处理风格)
@@ -1984,7 +2061,9 @@ async function main() {
1984
2061
  }
1985
2062
  if (replanTask7Broken.length > 0) {
1986
2063
  if (replanTask7NewFormat && state.newChange === true) {
1987
- console.error('BLOCKED: TASK.md 任务缺 7 字段(name/read_files/write_files/action/verify/done/depends_on): '
2064
+ // 文案的集合字符串**从判据常量派生**(不得在此再写一遍字面集合——第二处同口径表达会在
2065
+ // 判据演进时静默落后于实现;构造方式不改变渲染结果)。
2066
+ console.error('BLOCKED: TASK.md 任务缺 7 字段(' + replanTask7Required.join('/') + '): '
1988
2067
  + replanTask7Broken.join('; ') + ';恢复: 对照 flow-kit/templates/TASK.md 补齐每个 <task> 的缺字段后重试;replan 不做校验豁免');
1989
2068
  process.exit(1);
1990
2069
  }
@@ -2123,7 +2202,34 @@ async function main() {
2123
2202
  return;
2124
2203
  }
2125
2204
 
2126
- throw new Error('Unknown command: ' + command + '. Use: init, status, next, select, record, verify-fail, advance, execution-mode, config, skill-load, bridge-check, reenter, replan');
2205
+ if (command === 'explain') {
2206
+ // 只读派生(ADR-015 附条):「某节点产出什么 / 门禁是什么 / 要加载什么 / 跑哪三条命令」此前
2207
+ // 只在册子里手抄,本命令把它暴露为节点现问通道。数据全部取自协议 JSON 的 nodes[] 与
2208
+ // outputSchemas[]——零新事实源、零状态读写(不写 state、不改路由、不绕门禁,与 bridge-check
2209
+ // 同为纯读通道)。节点 id 非法 → fail-closed 并列出协议内全部合法节点。
2210
+ const explainNodeId = process.argv[3];
2211
+ const legalNodeIds = (protocol.nodes ?? []).map((node) => node.id);
2212
+ // 缺参 / 纯空白 / 拿选项当节点名(如 --help)→ 用法错误(fail-closed,不猜)
2213
+ if (typeof explainNodeId !== 'string' || explainNodeId.trim() === '' || explainNodeId.startsWith('--')) {
2214
+ throw new Error('explain requires a <node> id. 用法: workflow-state.mjs explain <node>'
2215
+ + '(合法节点: ' + legalNodeIds.join('/') + ')');
2216
+ }
2217
+ const explainNode = (protocol.nodes ?? []).find((node) => node.id === explainNodeId);
2218
+ if (!explainNode) {
2219
+ throw new Error('explain node 非法: ' + explainNodeId + '(协议节点: ' + legalNodeIds.join('/') + ')');
2220
+ }
2221
+ console.log('NODE: ' + explainNode.id);
2222
+ if (explainNode.label) console.log('LABEL: ' + explainNode.label);
2223
+ if (explainNode.kind) console.log('KIND: ' + explainNode.kind);
2224
+ if (explainNode.disabled === true) console.log('DISABLED: true(该节点在当前协议中被停用)');
2225
+ printNodeArtifacts(protocol, explainNode);
2226
+ printNodeGuardrails(explainNode);
2227
+ printNodeSkillCalls(explainNode);
2228
+ printNodeCommands(explainNode);
2229
+ return;
2230
+ }
2231
+
2232
+ throw new Error('Unknown command: ' + command + '. Use: init, status, next, select, record, verify-fail, advance, execution-mode, config, skill-load, bridge-check, reenter, replan, explain');
2127
2233
  }
2128
2234
 
2129
2235
  main().catch(error => {
@@ -28,22 +28,17 @@ This node finalizes a completed change by extracting reusable lessons from the d
28
28
 
29
29
  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.
30
30
 
31
- 2. **Apply nomination criteria**: For each potential lesson:
32
- - Debugging/trial-and-error took > 30 minutes -> nominate.
33
- - Error is not task-specific, other tasks would hit it too -> nominate.
34
- - Reasonable probability of retry within 6 months -> nominate.
35
- - Otherwise do not nominate (avoid pollution of LESSONS.md).
31
+ 2. **Apply nomination criteria**: 三条判据(含「其余一律不提名」兜底)见 `flow-comet-integration` 册的「LESSONS 提名」段——该段是判据的**单一权威**,本册不复述、以该册为准。
36
32
 
37
33
  3. **Add qualifying lessons to LESSONS.md**: For each nominated lesson:
38
- - Assign next `L-NNN` number (continuing from existing).
39
34
  - Fill required fields: label, keywords, applicable tech stack, status (active).
40
- - Save to `.specs/LESSONS.md` — 新条目编号 = 当前最大编号 + 1,插入 `## 条目区` 末尾(文件内升序,继续现有编号),**禁止文件尾追加与乱序插入**。
41
- - **Do NOT archive LESSONS.md** — it is a project-level permanent file that accumulates across changes.
35
+ - 写回 `.specs/LESSONS.md`;编号、插入位置与「不随 change 归档」的判定**以 `flow-comet-integration` 册「LESSONS 提名」段为准**(本册不复述)。
42
36
 
43
- 4. **Check existing lessons for superseded/deprecated**: Scan existing active lessons in `.specs/LESSONS.md`. If this change's lessons or outcomes supersede or deprecate existing entries, update their status accordingly.
37
+ 4. **Check existing lessons for superseded/deprecated**: 扫描 `.specs/LESSONS.md` 的 active 条目,被本次结论取代 / 废弃的更新其状态——判定口径以 `flow-comet-integration` 册「LESSONS 提名」段为准(本册不复述)。
44
38
 
45
39
  5. **Compile the leftover issues list (problem-handling principle)**: Before the move, collect everything that remains open or known-limited in this change:
46
40
  - REVIEW.md findings marked `[转待办]` (deferred — recorded but not fixed) plus any known limitations captured during the change.
41
+ - **需要模板时**读 `../flow-comet/reference/KNOWN-ISSUES-template.md`(当你归档时要编遗留清单、需要模板时读它)——含「遗留清单」段骨架与「使用说明」(模板本身是分发产物:零过程代号;归档实例不受此限)。
47
42
  - Write `.specs/<change-id>/KNOWN-ISSUES.md` — each entry: issue description, why it was deferred, and where it may surface again.
48
43
  - 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.
49
44
  - If there are no leftovers, still state that explicitly in the file (e.g. "无遗留问题" / "No known leftover issues").
@@ -64,7 +59,7 @@ This node finalizes a completed change by extracting reusable lessons from the d
64
59
  Archived to .specs/archive/<YYYY-MM-DD>-<change-id>/
65
60
  遗留问题清单(KNOWN-ISSUES.md,随工件归档): <each leftover issue, or 无>
66
61
  This change's DESIGN section 9 has N architecture sedimentation candidates, deferred for batch sync.
67
- Recommended: run A-evolve workflow after >= 5 changes or 60 days to batch-review and patch CONTEXT.md.
62
+ Recommended: run A-evolve workflow after >= 5 个带 `§9` 的归档 change,或距上次沉淀 > 60 天(阈值与入口册 `EVOLVE-DUE` 提示同口径)——批量 review 后 patch CONTEXT.md。
68
63
  ```
69
64
 
70
65
  10. **Record evidence**: Run `node .claude/skills/flow-comet/scripts/workflow-state.mjs record archive '<evidence JSON>'` to record archive completion.
@@ -73,18 +68,14 @@ This node finalizes a completed change by extracting reusable lessons from the d
73
68
 
74
69
  ### 归档后发现缺陷(受控重入)
75
70
 
76
- 归档已 entry 但归档移动尚未发生(`.specs/<change-id>/` 仍在原位、`status !== 'completed'`)时,review / verify / 执行阶段发现的新缺陷按下列边界处置:
71
+ 归档已 entry 但归档移动尚未发生(`.specs/<change-id>/` 仍在原位、`status !== 'completed'`)时,review / verify / 执行阶段发现的新缺陷**不得**在归档阶段就地修完——工作归属须先受控归位回既有生命周期,再按修复回路收口。要点:
77
72
 
78
- - **未移动** → 受控重入:由用户显式授权后运行
79
-
80
- ```bash
81
- node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]
82
- ```
83
-
84
- 目标限 `execute` / `subagent-execute` / `review` / `verify` 之一;每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);命令先自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`),再转移工作归属,并打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`)。缺授权、目标越界、超上限或归档移动已发生一律 BLOCKED(state 字节零改写),不会静默跳过。
73
+ - **未移动** → 受控重入:由用户显式授权后运行 `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 字节零改写),不会静默跳过。
85
74
  - **已移动 / 已合并** → 人工处置或新 change:归档移动已发生(`.specs/archive/<日期>-<change-id>/`)或 change 已 `completed` / 已合并时,受控重入不适用(不承诺把文件搬回原位);走人工处置,或把修复放进新 change / hotfix,并在遗留清单里登记指针。
75
+ - **写权限顺序(先转移后写 TASK)**:先跑 `reenter` 完成转移(写入权限随即跟随目标节点),再在目标节点权限内追加 Fix 任务 / 修改工件;archive 阶段 hook 对 change 目录只放行 `KNOWN-ISSUES.md` 这一个精确文件(另有 `.specs/archive/`、`.specs/CHANGELOG.md`、`.specs/LESSONS.md`、`STATE.md`),**不要试图在归档阶段先写 TASK.md**。
76
+ - **回源路径不因归档而放宽**:修复回路本身不变——回到 `execute` 生命周期时照样跑完四类出口,随后**回源节点跑出口**(`entry <源节点>` → `exit <源节点> --apply`);受控重入只改工作归属,不写任何闭合标记,也**禁止绕过**目标节点入口 / 出口与源节点出口门禁。
86
77
 
87
- **写权限顺序(先转移后写 TASK)**:archive 阶段 hook 对 change 目录只放行 `KNOWN-ISSUES.md` 这一个精确文件(另有 `.specs/archive/`、`.specs/CHANGELOG.md`、`.specs/LESSONS.md`、`STATE.md`),TASK.md 的修复任务写入不在放行面内。顺序固定为:先跑 `reenter` 完成转移(写入权限随即跟随目标节点),再在目标节点权限内追加 Fix 任务 / 修改工件——不要试图在 archive 阶段先写 TASK.md。若重入成功后追加任务失败,用 `next` / `status` 核对归属;重复调用同一目标为空操作(不备份、不计数、不改写 state)。
78
+ **何时读完整规格**:要核对完整边界——命令全形与三态审计行(`REENTRY:` / `FIX-BATCH: 归位` / `RETURN:`)的区分、备份快照与 sha256 指纹、续轮授权形态与轮次记账、重复调用同一目标的空操作语义、「已移动 / 已合并」的处置面——读 `../flow-comet/reference/fix-loop.md`(**当你归档后发现缺陷、要把工作归属受控归位回既有生命周期时读它**)。
88
79
 
89
80
  ### 归档提交(R4.1 交付闭环)
90
81
 
@@ -28,12 +28,11 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
28
28
 
29
29
  ## 视觉调性段的标记约定(前端 / 非前端)
30
30
 
31
- `CHANGE.md` 的 `## 视觉调性` 段(段名取自 `flow-kit/templates/CHANGE.md`)不只承载调性选择,还是下游 design 出口判定「是否前端」的**结构级判据**——它的在场状态必须与项目实情一致:
31
+ `CHANGE.md` 的 `## 视觉调性` 段(段名取自 `flow-kit/templates/CHANGE.md`)不只承载调性选择,还是下游 design 出口判定「是否前端」的**结构级判据**的输入面——它的在场状态必须与项目实情一致:
32
32
 
33
- - **结构形态**(判据口径,与引擎的 design 出口适用性门控一致;本节只描述契约,两者不一致时以引擎的输出行为为准):`不适用` 标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(例如句子里写「不适用于暗色主题」)不算标注,仍判前端。
33
+ - **判据与强制等级(唯一权威)**:判据全文与 `guarded` 绑定、`required-skill:design.flow-comet-ui-design` 声明要求、非前端 `UI-DESIGN: skipped(非前端)` 的出口口径都在 `flow-comet-ui-design` 册的「触发与跳过」段——本节不复述,只描述怎么填段。
34
34
  - **前端项目**:按步骤 0.6 的预选结果填段(选定 / 理由 / 参考产品 / 明确排除),不要以结构形态标注「不适用」。
35
35
  - **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI 工具,无用户可见界面」)。段缺席同样按非前端处理,但缺席不留可读证据,故约定**显式标注**。
36
- - **判据与强制等级**(下游据此分派):`flow-comet-ui-design` 在 design 节点的绑定等级为 `guarded`——段在场且无结构形态标记 ⇒ 判前端 ⇒ design 出口要求 `.specs/<change-id>/UI-DESIGN.md` 在场,并要求 `required-skill:design.flow-comet-ui-design` 真实声明(先加载、再声明);段缺席或有结构形态标记 ⇒ 判非前端 ⇒ 出口打印 `UI-DESIGN: skipped(非前端)` 与命中片段后放行,不要求 UI-DESIGN.md。
37
36
  - **改判走本阶段**:change 进行中要改前端 / 非前端判定,回到这里改这一个段,不在 design / execute / verify 里就地绕开判据——改段即改变了 design 出口的判据输入。
38
37
 
39
38
  ## 状态推进
@@ -15,7 +15,7 @@ description: "Use only when explicitly invoked as /flow-comet-compose. Not part
15
15
  - **guard 校验**:`workflow-guard.mjs` 按节点 guardrail(artifact-exists / evidence-only / state-transition)做阶段门禁
16
16
  - **hook 拦截**:`comet-hook-guard.mjs` 按 writeWhitelist 做写入边界守卫
17
17
 
18
- **内置 8 节点协议不可被取代**:`reference/workflow-protocol.json`(open→design→plan→execute→subagent-execute→review→verify→archive)永远是默认工作流;自定义协议只在用户显式指定时加载(见「与内置协议的关系」)。
18
+ **内置 8 节点协议不可被取代**:`../flow-comet/reference/workflow-protocol.json`(open→design→plan→execute→subagent-execute→review→verify→archive)永远是默认工作流;自定义协议只在用户显式指定时加载(见「与内置协议的关系」)。
19
19
 
20
20
  ## 交互流程(逐步)
21
21
 
@@ -58,11 +58,11 @@ This node transforms requirements into an actionable technical design. It produc
58
58
 
59
59
  5. **Data flow / architecture diagram (section 2)**: ASCII or Mermaid diagram showing data/event flow, key state machines, boundaries.
60
60
 
61
- 6. **ADR (section 3)**: For any decision that could be reversed later, write ADR to `.specs/adr/<NNN>-<title>.md` with Context / Decision / Consequences structure.
61
+ 6. **ADR (section 4)**: For any decision that could be reversed later, write ADR to `.specs/adr/<NNN>-<title>.md` with Context / Decision / Consequences structure.
62
62
 
63
- 7. **Risk assessment (section 4)**: At least 3 risks (implementation / launch / long-term debt), each with mitigation.
63
+ 7. **Risk assessment (section 5)**: At least 3 risks (implementation / launch / long-term debt), each with mitigation.
64
64
 
65
- 8. **Out of scope (section 5)**: Explicitly list what this design does NOT solve but will need future attention.
65
+ 8. **Out of scope (section 6)**: Explicitly list what this design does NOT solve but will need future attention.
66
66
 
67
67
  9. **Architecture sedimentation suggestions (section 9)**: If this change introduces project-level reusable value (new abstractions, tech decisions, cross-module contracts, dependency changes, forbidden-list updates), fill section 9. Otherwise write "No architecture sedimentation suggestions for this change."
68
68
 
@@ -111,9 +111,9 @@ The design node reads CHANGE.md and REQUIREMENT.md, then produces DESIGN.md thro
111
111
 
112
112
  **加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
113
113
 
114
- 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。
114
+ 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。
115
115
 
116
- > **前端判据(结构级 · 与引擎同口径)**:`CHANGE.md` 的「视觉调性」段在场,且段内的「不适用」标记成**结构形态**时才判非前端——标记**独立行**、居**行首**(可带列表符号 / 引用 / 加粗),或写在适用性类标签(`适用性` / `适用范围` / `是否前端` / `视觉调性` / `前端` / `界面` / `适用`)的**字段值位**;标记之后须成**词形边界**(紧跟空白、标点或行尾),命中即回显**命中片段**。段内其它位置顺带提到「不适用」(如「不适用于暗色主题」)不算标注,仍判前端、仍要求 UI-DESIGN.md 与 `guarded` 声明。
116
+ > **前端判据(结构级 · 唯一权威 → `flow-comet-ui-design` 册的「触发与跳过」段)**:判据全文与 `guarded` 绑定的判级口径都在该册——本节不复述,判定与出口行为一律以该册为准。
117
117
  2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
118
118
 
119
119
  ```bash
@@ -160,6 +160,6 @@ If the script prints `SKILL: flow-comet-plan`, load that Skill next.
160
160
 
161
161
  1. Re-run entry check to confirm workflow state.
162
162
  2. Read `.specs/<change-id>/DESIGN.md` — 轻量流程允许 `.specs/<change-id>/DESIGN-lite.md`(guard 同口径:DESIGN.md 优先、DESIGN-lite 兜底)——if exists with section 0 populated and user confirmed, design phase is done.
163
- 3. If the design doc exists but incomplete, resume from the first missing section (check 0, 0.5, 1-5, 9).
163
+ 3. If the design doc exists but incomplete, resume from the first missing section (check 0, 0.5, 1-6, 9).
164
164
  4. If frontend project: check `.specs/<change-id>/UI-DESIGN.md` existence.
165
165
  5. Do not repeat confirmed decisions. Resume from the first incomplete artifact.