flow-comet 1.6.5 → 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.
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +32 -18
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +2 -2
- package/.flow-comet/skills/flow-comet/reference/decision-points.md +5 -5
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/entry-detail.md +30 -11
- package/.flow-comet/skills/flow-comet/reference/fix-loop.md +4 -4
- package/.flow-comet/skills/flow-comet/reference/init-detection.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/platform-facts.md +2 -2
- package/.flow-comet/skills/flow-comet/reference/post-archive-handoff.md +264 -0
- package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/replan.md +1 -1
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +1 -0
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +270 -30
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +26 -23
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +14 -94
- package/.flow-comet/skills/flow-comet/scripts/items/a.mjs +122 -11
- package/.flow-comet/skills/flow-comet/scripts/items/b.mjs +79 -40
- package/.flow-comet/skills/flow-comet/scripts/items/c.mjs +11 -9
- package/.flow-comet/skills/flow-comet/scripts/items/e.mjs +52 -10
- package/.flow-comet/skills/flow-comet/scripts/items/f.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/items/h.mjs +128 -56
- package/.flow-comet/skills/flow-comet/scripts/items/k.mjs +357 -3
- package/.flow-comet/skills/flow-comet/scripts/items/l.mjs +26 -1
- package/.flow-comet/skills/flow-comet/scripts/items/m.mjs +6 -2
- package/.flow-comet/skills/flow-comet/scripts/items/n.mjs +29 -21
- package/.flow-comet/skills/flow-comet/scripts/lib/ac-coverage.mjs +317 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/fix-loop-node.mjs +4 -15
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-artifact-skeleton.mjs +47 -5
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-evidence-gates.mjs +357 -219
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-gates.mjs +725 -309
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-routing.mjs +182 -54
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-state-io.mjs +8 -6
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-template-fidelity.mjs +224 -83
- package/.flow-comet/skills/flow-comet/scripts/lib/guard-uidesign.mjs +17 -28
- package/.flow-comet/skills/flow-comet/scripts/lib/lessons-hits.mjs +160 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/run-root.mjs +21 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/section-body.mjs +92 -0
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-admin.mjs +61 -33
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-flow.mjs +663 -205
- package/.flow-comet/skills/flow-comet/scripts/lib/state-commands-recovery.mjs +68 -9
- package/.flow-comet/skills/flow-comet/scripts/lib/state-determine.mjs +11 -4
- package/.flow-comet/skills/flow-comet/scripts/lib/state-explain.mjs +92 -13
- package/.flow-comet/skills/flow-comet/scripts/lib/state-io.mjs +232 -11
- package/.flow-comet/skills/flow-comet/scripts/lib/state-skillmarkers.mjs +140 -74
- package/.flow-comet/skills/flow-comet/scripts/lib/system-fixtures.mjs +8 -4
- package/.flow-comet/skills/flow-comet/scripts/lib/task-graph.mjs +84 -31
- package/.flow-comet/skills/flow-comet/scripts/lib/test-assertions.mjs +0 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/test-fixtures.mjs +248 -24
- package/.flow-comet/skills/flow-comet/scripts/lib/test-helpers.mjs +63 -3
- package/.flow-comet/skills/flow-comet/scripts/lib/text-anchor-checks.mjs +181 -8
- package/.flow-comet/skills/flow-comet/scripts/lib/wave-projection.mjs +340 -0
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +132 -20
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +12 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/a.mjs +1564 -54
- package/.flow-comet/skills/flow-comet/scripts/scenarios/b.mjs +1489 -38
- package/.flow-comet/skills/flow-comet/scripts/scenarios/c.mjs +1466 -243
- package/.flow-comet/skills/flow-comet/scripts/scenarios/d.mjs +743 -24
- package/.flow-comet/skills/flow-comet/scripts/scenarios/e.mjs +220 -92
- package/.flow-comet/skills/flow-comet/scripts/scenarios/f.mjs +657 -21
- package/.flow-comet/skills/flow-comet/scripts/scenarios/g.mjs +41 -27
- package/.flow-comet/skills/flow-comet/scripts/scenarios/h.mjs +285 -9
- package/.flow-comet/skills/flow-comet/scripts/scenarios/i.mjs +7 -6
- package/.flow-comet/skills/flow-comet/scripts/scenarios/j.mjs +21 -15
- package/.flow-comet/skills/flow-comet/scripts/scenarios/k.mjs +8 -5
- package/.flow-comet/skills/flow-comet/scripts/scenarios/l.mjs +45 -36
- package/.flow-comet/skills/flow-comet/scripts/scenarios/m.mjs +2 -2
- package/.flow-comet/skills/flow-comet/scripts/scenarios/n.mjs +2381 -85
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +135 -2
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +143 -16
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +339 -103
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +5 -2
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +33 -11
- package/.flow-comet/skills/flow-comet-change/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +5 -3
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +37 -13
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +10 -4
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +13 -6
- package/.flow-comet/skills/flow-comet-review/SKILL.md +21 -12
- package/.flow-comet/skills/flow-comet-subagent-execute/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +43 -18
- package/.flow-comet/skills/flow-comet-task/SKILL.md +4 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +2 -2
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +1 -1
- package/README.md +2 -2
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +238 -21
|
@@ -13,6 +13,12 @@ import { validateStateFields } from '../state-schema.mjs';
|
|
|
13
13
|
import { inspectWorkflowPathSegments } from '../protocol-utils.mjs';
|
|
14
14
|
import { fileExists, inspectReentryChangeDir, readJson, readState, runRootDir, specsDir, stateFile, writeState } from './state-io.mjs';
|
|
15
15
|
import { TASK7_REQUIRED } from './task-graph.mjs';
|
|
16
|
+
// TASK.md 段形权威(P2b):replan 复用 plan 出口的同一份骨架门——骨架(模板 + 登记表)与报错片段
|
|
17
|
+
// (formatIssueParts)都从这两个模块取用,重校段不自持第二份段名清单 / 第二套措辞。
|
|
18
|
+
import { evaluateArtifact, formatIssueParts } from './guard-template-fidelity.mjs';
|
|
19
|
+
// 波次投影(波次 = 依赖层级的投影):与 plan 出口同一实现、同一报文——replan 的重校段消费它,
|
|
20
|
+
// 不另写一份判定(两处各写一份,改散文即可绕过其中一处)。
|
|
21
|
+
import { parallelGapOutcome, parallelGapReview, waveProjectionReview, waveReviewOutcome } from './wave-projection.mjs';
|
|
16
22
|
|
|
17
23
|
// reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]
|
|
18
24
|
// 受控重入(archive 源回边):archive 已 entry 且归档移动尚未发生时,用户显式授权把工作归属
|
|
@@ -265,6 +271,36 @@ export async function runReenter(protocol, argv) {
|
|
|
265
271
|
return;
|
|
266
272
|
}
|
|
267
273
|
|
|
274
|
+
// TASK 段形前置(P2b):计划重校是「已签发计划的修订」,TASK.md 的段形由模板权威裁定——plan 出口
|
|
275
|
+
// 已用同一份骨架门(evaluateArtifact + formatIssueParts)拦过缺段,重校段不豁免:执行期把承载段
|
|
276
|
+
// (`## 波次划分` 等模板必需段)删掉再改任务集,不得换到「未校验」放行口(否则「删一个段」就是
|
|
277
|
+
// 关掉波次判据的写法)。模板缺席 ⇒ 段集合无从派生,本判据整段跳过(plan 出口在同一输入下也只打印
|
|
278
|
+
// 「未校验(模板缺失)」;它对标题 / 首部字段的另判属另一层判据面,不在本判据的判据面内——重校段
|
|
279
|
+
// 要堵的是「删段再改任务集」)。同一形态下波次判据自己那行「未校验(无波次段)」照常打印,两条边界
|
|
280
|
+
// 各说各的事实。
|
|
281
|
+
// 报文与分级取用 plan 出口的同一份实现(骨架 = 模板 + 登记表;片段 = formatIssueParts),失败行
|
|
282
|
+
// 因此与 plan 出口**逐字一致**(escalate=false,两阶段口径不变);重校段的现场适配只落在恢复行:
|
|
283
|
+
// ① 缺的段名在这里点名(重校段没有提示账本可「再犯升级」,等第二次才说段名等于永远不说);
|
|
284
|
+
// ② 重试目标是本命令(人在 replan 现场,改完要重跑的是它)。分级沿用既有语义:新 change BLOCKED、
|
|
285
|
+
// 命中即 BLOCKED。
|
|
286
|
+
async function replanTaskStructureGate(state, taskContent) {
|
|
287
|
+
const taskArtifact = await evaluateArtifact('TASK', taskContent, {});
|
|
288
|
+
if (!taskArtifact.derived) return; // 模板缺席 ⇒ 段形无从派生(与 plan 出口同一支「未校验(模板缺失)」)
|
|
289
|
+
// escalate: false = 失败行只报类别计数——与 plan 出口**逐字一致**(两阶段口径是公开行为:
|
|
290
|
+
// 首次只给模板路径与类别计数)。重校段没有提示账本可「再犯升级」,段名因此放在恢复行点名,
|
|
291
|
+
// 不靠第二次失败才出现,也不与那条两阶段口径矛盾。
|
|
292
|
+
const parts = formatIssueParts(taskArtifact.issues, { escalate: false });
|
|
293
|
+
if (parts.length === 0) return;
|
|
294
|
+
const templateFile = taskArtifact.skeleton.file ?? '(登记表未登记模板路径)';
|
|
295
|
+
const failureLine = 'TASK.md 模板结构校验失败: ' + parts.join('; ') + '(模板: ' + templateFile + ')';
|
|
296
|
+
const missingSections = taskArtifact.issues.missing ?? [];
|
|
297
|
+
console.error('BLOCKED: ' + failureLine);
|
|
298
|
+
console.error('恢复: 对照 ' + templateFile + ' 修正标题 / 首部字段 / 段序,并按模板补齐缺失的 H2 与结构型 H3 标题'
|
|
299
|
+
+ (missingSections.length > 0 ? '(缺失的段: ' + missingSections.join('、') + ')' : '')
|
|
300
|
+
+ '——承载段被删掉也算缺段,删段不是跳过判据的写法;改完重试 replan(replan 不做校验豁免,状态零改写)');
|
|
301
|
+
process.exit(1);
|
|
302
|
+
}
|
|
303
|
+
|
|
268
304
|
// replan <reason> --authorized-by <source> [--continue-round <n>]
|
|
269
305
|
// 受控计划重校重签(ADR-013):计划在执行中被证明有缺陷时,唯一合规的重签入口——只在
|
|
270
306
|
// execute / subagent-execute 相位可用、停原位(不跳节点、不改 completedNodes),先把任务集
|
|
@@ -421,6 +457,27 @@ export async function runReplan(protocol, argv) {
|
|
|
421
457
|
+ ';恢复: 调整任务 depends_on——移除成环引用或改为真实存在的任务 id 后重试');
|
|
422
458
|
process.exit(1);
|
|
423
459
|
}
|
|
460
|
+
// TASK 段形前置(P2b):判据与措辞见 replanTaskStructureGate(本函数只负责顺序——结构先于内容)。
|
|
461
|
+
await replanTaskStructureGate(state, taskContent);
|
|
462
|
+
// 波次投影(波次 = 依赖层级的投影):与 plan 出口**同源**调用同一判定与同一报文构造(ADR-013:
|
|
463
|
+
// replan 绝不豁免——此处不判,改一改波次散文就能绕过 plan 出口的同一判据)。新 change 不一致
|
|
464
|
+
// (含未被 Wave 行声明的任务,明细取值「未声明」)→ BLOCK(逐条点名 + 恢复指引;本段全部先于
|
|
465
|
+
// 备份与写盘,故状态零改写)。「判不了」按成因二分——载体缺席(无段 / 段名
|
|
466
|
+
// 无从派生)打印「未校验」并跳过;内容不可判(段在场却无可对应任务)与 plan 出口同分级。
|
|
467
|
+
// 分级与措辞都由 waveReviewOutcome 一处产出(本段只派生 blocking):两处不可能各说一套,也不会
|
|
468
|
+
// 因为「分级规则只改了一处」而在另一处静默落后。
|
|
469
|
+
const waveReview = waveProjectionReview({ taskContent, blocks: taskList });
|
|
470
|
+
const waveOutcome = waveReviewOutcome(waveReview, { blocking: true });
|
|
471
|
+
for (const line of waveOutcome.lines) console.error(line);
|
|
472
|
+
if (waveOutcome.block) process.exit(1);
|
|
473
|
+
// 同波可并行却漏标 [P]:plan 出口的第二条波次面判据,重校段同样不豁免(ADR-013)——否则执行期
|
|
474
|
+
// 重签就能把「本可并行却没标」的计划换一份发出去。波次分组复用上面同一次解析(waveReview.waves)。
|
|
475
|
+
const gapOutcome = parallelGapOutcome(
|
|
476
|
+
parallelGapReview({ taskContent, blocks: taskList, waves: waveReview.waves }),
|
|
477
|
+
{ blocking: true },
|
|
478
|
+
);
|
|
479
|
+
for (const line of gapOutcome.lines) console.error(line);
|
|
480
|
+
if (gapOutcome.block) process.exit(1);
|
|
424
481
|
// 任务字段完整性(与 plan 出口同一判据):字段集从 `task-graph.mjs` 的单一权威常量取用——本模块
|
|
425
482
|
// 是执行期唯一允许修订任务集的通道,若在此另写一份字面集合,plan 出口会拒的任务集将被 replan
|
|
426
483
|
// 静默放行。新模板形态(含 <name>)且新 change → BLOCK;旧式一字段形态 / 旧 change 保持渐进
|
|
@@ -435,15 +492,14 @@ export async function runReplan(protocol, argv) {
|
|
|
435
492
|
}
|
|
436
493
|
}
|
|
437
494
|
if (replanTask7Broken.length > 0) {
|
|
438
|
-
if (replanTask7NewFormat
|
|
495
|
+
if (replanTask7NewFormat) {
|
|
439
496
|
// 文案的集合字符串**从判据常量派生**(不得在此再写一遍字面集合——第二处同口径表达会在
|
|
440
497
|
// 判据演进时静默落后于实现;构造方式不改变渲染结果)。
|
|
441
498
|
console.error('BLOCKED: TASK.md 任务缺 7 字段(' + TASK7_REQUIRED.join('/') + '): '
|
|
442
499
|
+ replanTask7Broken.join('; ') + ';恢复: 对照 flow-kit/templates/TASK.md 补齐每个 <task> 的缺字段后重试;replan 不做校验豁免');
|
|
443
500
|
process.exit(1);
|
|
444
501
|
}
|
|
445
|
-
console.error('TASK-7FIELD WARN: TASK.md ' + replanTask7Broken.join('; ')
|
|
446
|
-
+ (replanTask7NewFormat ? '(旧 change 渐进,不阻断)' : '(旧式一字段模板形态,渐进不阻断)'));
|
|
502
|
+
console.error('TASK-7FIELD WARN: TASK.md ' + replanTask7Broken.join('; ') + '(旧式一字段模板形态,渐进不阻断)');
|
|
447
503
|
}
|
|
448
504
|
// 路径边界:change 名必须是 .specs/ 下的单段真实目录(realpath 归一后仍在 .specs/ 内、
|
|
449
505
|
// 无 symlink/junction 逃逸;复用受控路径边界实现)——备份落点必须先通过该边界。
|
|
@@ -478,12 +534,9 @@ export async function runReplan(protocol, argv) {
|
|
|
478
534
|
if (crossTaskConflicts.length > 0) {
|
|
479
535
|
const crossDetail = crossTaskConflicts.map((c) => c.a + '×' + c.b + '(' + c.files.join(',') + ')').join('; ');
|
|
480
536
|
const crossGuide = ';恢复: 补显式 depends_on 或合并为一个任务后重试';
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
process.exit(1);
|
|
485
|
-
}
|
|
486
|
-
console.error('WARN: TASK.md 同文件跨任务且无依赖路径(旧 change 渐进不阻断): ' + crossDetail + crossGuide);
|
|
537
|
+
console.error('BLOCKED: TASK.md 同文件跨任务且无依赖路径: ' + crossDetail
|
|
538
|
+
+ '——replan 不做校验豁免,状态零改写' + crossGuide);
|
|
539
|
+
process.exit(1);
|
|
487
540
|
}
|
|
488
541
|
if (readWarnings.length > 0) {
|
|
489
542
|
console.error('WARN: TASK.md 并行任务 read∩write 隐式依赖嫌疑(一方读取对方写路径,建议补显式 depends_on 声明): '
|
|
@@ -573,6 +626,12 @@ export async function runReplan(protocol, argv) {
|
|
|
573
626
|
: '第 ' + round + '/' + REPLAN_ROUND_LIMIT + ' 轮';
|
|
574
627
|
console.log('REPLAN: ' + decision.node + ' 重新校验通过(授权源 ' + source + ';' + roundLabel
|
|
575
628
|
+ ';备份 ' + backupRecord + ')');
|
|
629
|
+
// 成功行的事实说明(只加一行可观察事实,REPLAN 行前缀与语义不变):重签的是 state.taskHash,
|
|
630
|
+
// 只写重校审计;TASK.md 保持执行者修订后的原文,plan 节点证据不会重记(防误以为 replan 会
|
|
631
|
+
// 重写计划工件或重跑计划阶段)。值前缀从实际签名派生,不在这里手写版本字面量。
|
|
632
|
+
const signaturePrefix = String(taskSetSignatureValue).split(':')[0] + ':';
|
|
633
|
+
console.log('TASKHASH: 已重签 state.taskHash(值前缀 ' + signaturePrefix
|
|
634
|
+
+ ')——TASK.md 内容未改写、plan 节点证据未重记(重签只覆盖任务集签名与重校审计)');
|
|
576
635
|
console.log('REASON: ' + reason);
|
|
577
636
|
return;
|
|
578
637
|
}
|
|
@@ -6,8 +6,13 @@ import { runRootDir } from './state-io.mjs';
|
|
|
6
6
|
// 判定核心在共享模块 route-node.mjs——本函数保持既有签名与返回语义,仅委托 resolveNextNode
|
|
7
7
|
// (output 与抽取前一致)。route / buildNodeCompletionFlags / pathPatternExists / nodeFlagsComplete /
|
|
8
8
|
// protocolTaskFilePath / hasSubagentNode 同为该模块的单一实现(guard 与状态机共用,杜绝双实现漂移)。
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
//
|
|
10
|
+
// changeDir(可选)= 该 change 目录相对 .specs/ 的 POSIX 路径(活动 '<id>' / 归档
|
|
11
|
+
// 'archive/<日期>-<id>',由 state-io.resolveChangeDir 解析)。目录已搬进归档时产物与任务文件都在
|
|
12
|
+
// 归档目录里——不传它会让推导看不到任何产物、回退到协议首节点(移动后报 open 的成因)。缺省 null
|
|
13
|
+
// = 既有形态(按 .specs/<changeName> 解析),旧调用零变化。
|
|
14
|
+
export async function determineNode(changeName, protocol, completedNodes = [], changeDir = null) {
|
|
15
|
+
return resolveNextNode({ runRoot: runRootDir(), changeName, protocol, completedNodes, changeDir });
|
|
11
16
|
}
|
|
12
17
|
|
|
13
18
|
// 正常推进豁免判定——exit --apply 会把 currentNode 推进到下一节点(如 open exit 后
|
|
@@ -20,7 +25,7 @@ export async function determineNode(changeName, protocol, completedNodes = []) {
|
|
|
20
25
|
// NEXT 同源),静态直接后继兜底(串行推进原语义,旧态/序列流不回归)。与回退豁免独立判断
|
|
21
26
|
// (回退 = TASK.md 有 pending 回退修复任务;本豁免 = 正常推进后继)。真乱序(currentNode
|
|
22
27
|
// 既非路由后继也非静态后继)仍维持严格 BLOCK。
|
|
23
|
-
export async function normalAdvanceExempt(state, protocol, completedNodes, currentNode, changeName) {
|
|
28
|
+
export async function normalAdvanceExempt(state, protocol, completedNodes, currentNode, changeName, changeDir = null) {
|
|
24
29
|
if (completedNodes.length === 0) return false;
|
|
25
30
|
const lastNodeId = completedNodes[completedNodes.length - 1];
|
|
26
31
|
const routeIds = route(protocol).map((node) => node.id);
|
|
@@ -42,7 +47,9 @@ export async function normalAdvanceExempt(state, protocol, completedNodes, curre
|
|
|
42
47
|
// 路由后继判定(与 guard 出口同源):currentNode === resolveNextNode(completedNodes) 即
|
|
43
48
|
// 正常推进后的下一路由目标(含平行转换与趟间回流);文件推导失败(异常态)不豁免。
|
|
44
49
|
try {
|
|
45
|
-
|
|
50
|
+
// 产物根与共享视图取同一个 changeDir:两处各按自己的根推导,「路由后继」就会与 next 的 NODE
|
|
51
|
+
// 行给出两个答案(移动后尤其明显:一处读归档、一处读已不存在的活动目录)。
|
|
52
|
+
const routingNext = await determineNode(changeName, protocol, completedNodes, changeDir);
|
|
46
53
|
if (routingNext === currentNode) return true;
|
|
47
54
|
} catch {
|
|
48
55
|
return false;
|
|
@@ -4,24 +4,100 @@
|
|
|
4
4
|
// 读写(不写 state、不改路由、不绕门禁,与 bridge-check 同为纯读通道)。节点 id 非法 →
|
|
5
5
|
// fail-closed 并列出协议内全部合法节点。
|
|
6
6
|
import path from 'path';
|
|
7
|
-
import {
|
|
7
|
+
import { fileURLToPath } from 'url';
|
|
8
|
+
import {
|
|
9
|
+
nodeTemplateDeclaration,
|
|
10
|
+
resolveProtocol,
|
|
11
|
+
skillLoadDeclarationArgs,
|
|
12
|
+
templatePointerLines,
|
|
13
|
+
} from '../protocol-utils.mjs';
|
|
14
|
+
import { toPersistedProtocolPath } from '../state-schema.mjs';
|
|
8
15
|
import { runRootDir } from './state-io.mjs';
|
|
9
16
|
|
|
17
|
+
// 协调者禁令的**同一句**(单一来源):entry(门禁族)与 next / record(状态命令族)都引用本常量——
|
|
18
|
+
// 同一纪律多个输出面逐字一致;两处各写一份必然在措辞演进时分叉。落点选在本模块是因为它**不属于
|
|
19
|
+
// 任何一族**:门禁族与状态命令族都只是取用方,常量因此不会把两族绑成一条反向依赖(一个措辞不该
|
|
20
|
+
// 让下游模块依赖整个上游门禁面)。现行架构口径(ADR-014 / 并行委派四属性契约):委托按平台的身份
|
|
21
|
+
// 通道判定,独立 worktree 只是「① 写权限」的一种实现,共享工作区同样受支持。
|
|
22
|
+
export const COORDINATOR_NOTICE = '你是协调者,不是执行者。禁止在主会话直接修改源码;按平台的身份通道委托子代理(同一身份判据,不要求隔离区);独立 worktree 只是四属性契约里「写权限」的一种实现,共享工作区同样受支持;子代理回传后仅更新 TASK.md / SUMMARY / handoff evidence。';
|
|
23
|
+
|
|
10
24
|
// 命令路径形态(平台化):权威源保持设计形态 .claude/skills/(与册子命令形态一致,安装时由
|
|
11
25
|
// prepare-env 的 pathReplacements 平台化);安装副本按脚本自定位输出运行根相对形态——.claude /
|
|
12
26
|
// .agents / .dsh 乃至将来新增的平台根同一推导覆盖,无需在此登记平台清单;落在运行根之外
|
|
13
27
|
// (用户级安装)时输出脚本自身的绝对路径。不得硬编码单一形态:pathReplacements 只处理 .md
|
|
14
28
|
// (prepare-env 的 applyPathReplacements 按扩展名过滤),脚本内的字面量在安装副本上不会被
|
|
15
|
-
// 替换——硬编码 .claude 会让 Codex / dsh
|
|
16
|
-
// scriptsDir
|
|
17
|
-
|
|
29
|
+
// 替换——硬编码 .claude 会让 Codex / dsh 单平台安装的消息输出不存在的命令路径。
|
|
30
|
+
// scriptsDir 由调用方以自定位绝对路径传入(调用方所在脚本目录);runRoot 缺省取状态上下文的运行根
|
|
31
|
+
// (state CLI 已初始化)——其它入口(守卫 / 委托脚本)没有该上下文,须显式传入自己的运行根。
|
|
32
|
+
// 本函数是这条推导的唯一实现:运行期消息与 explain 的 COMMAND 行都从这里取(L-067:同一推导
|
|
33
|
+
// 两处表达必然分叉)。
|
|
34
|
+
export function platformScriptsDir(scriptsDir, runRoot = runRootDir()) {
|
|
18
35
|
const posixDir = scriptsDir.replace(/\\/g, '/');
|
|
19
36
|
if (posixDir.includes('/.flow-comet/skills/')) return '.claude/skills/flow-comet/scripts';
|
|
20
|
-
const relative = path.relative(
|
|
37
|
+
const relative = path.relative(runRoot, scriptsDir).split(path.sep).join('/');
|
|
21
38
|
if (relative === '' || relative.startsWith('..') || path.isAbsolute(relative)) return posixDir;
|
|
22
39
|
return relative;
|
|
23
40
|
}
|
|
24
41
|
|
|
42
|
+
// 可复制命令形态(同一处实现:运行期消息与 explain 的 COMMAND 行共用):脚本根(平台化)+ 脚本名
|
|
43
|
+
// + 参数,整条脚本路径加双引号——安装根含空格时未加引号的路径会被 shell 按空格切分(只剩首段被当作
|
|
44
|
+
// 脚本),加引号后三种平台语义下都是单一参数(引号对无空格路径无害)。调用方只提供事实(脚本目录、
|
|
45
|
+
// 运行根、脚本名、参数),不得自行拼一份。
|
|
46
|
+
export function scriptCommand({ scriptsDir, runRoot, script, args = [] }) {
|
|
47
|
+
return 'node "' + platformScriptsDir(scriptsDir, runRoot) + '/' + script + '"'
|
|
48
|
+
+ (args.length > 0 ? ' ' + args.join(' ') : '');
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
// ---------- 声明命令(skill-load):状态命令族与守卫族共用的唯一装配 ----------
|
|
52
|
+
//
|
|
53
|
+
// 一条可照抄的声明命令由三段事实拼成,三段各有单一来源,本段只做组合:
|
|
54
|
+
// · 参数面(`skill-load <node> <skill> --prompt … --templates …`):由协议数据派生,见
|
|
55
|
+
// protocol-utils 的 skillLoadDeclarationArgs(该节点全部协议文件 + 模板全清单);
|
|
56
|
+
// · 脚本路径(平台化 + 整条加引号):见上面的 scriptCommand(与 record / entry 的恢复指引同源)——
|
|
57
|
+
// 只写裸脚本名的命令在 shell 里是 `command not found`,等于没给命令;
|
|
58
|
+
// · 协议上下文(`--protocol <持久化路径>`):本次运行解析到的协议**不是内置默认**时才带——内置
|
|
59
|
+
// 默认时照抄不带它也解析到同一份(加了只是噪音);自定义协议不带则照抄会解析到另一份协议
|
|
60
|
+
// (状态命令族只认 CLI → 环境变量 → 内置默认,没有 state 绑定这一来源),恢复路径断在第一步。
|
|
61
|
+
// 这三段此前被拼成两种文本(状态侧裸脚本名 / 守卫侧 scriptCommand 形态),同一件事两种文本时只有
|
|
62
|
+
// 一种能执行,故命令文本只在这里产出。
|
|
63
|
+
export function protocolContextArgs({ protocolPath, packageRoot, runRoot }) {
|
|
64
|
+
if (!protocolPath || !packageRoot) return [];
|
|
65
|
+
const builtin = path.resolve(packageRoot, 'reference', 'workflow-protocol.json');
|
|
66
|
+
if (path.resolve(protocolPath) === builtin) return [];
|
|
67
|
+
return ['--protocol', '"' + toPersistedProtocolPath(runRoot, protocolPath) + '"'];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
// 一条声明命令。context = { scriptsDir, runRoot, packageRoot, protocolPath }——运行面的事实,
|
|
71
|
+
// 由各族的运行上下文提供(状态命令族见 commandContext;守卫族按同一形状取自己的运行上下文)。
|
|
72
|
+
export function declarationCommand({ node, skill, frontend = false, context }) {
|
|
73
|
+
return scriptCommand({
|
|
74
|
+
scriptsDir: context.scriptsDir,
|
|
75
|
+
runRoot: context.runRoot,
|
|
76
|
+
script: 'workflow-state.mjs',
|
|
77
|
+
args: [
|
|
78
|
+
...skillLoadDeclarationArgs({ node, skill, frontend }),
|
|
79
|
+
...protocolContextArgs(context),
|
|
80
|
+
],
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
// 每个目标技能各一条命令(一次声明只写一个技能标记:同 node-skill 重跑是覆写,不是新增)。
|
|
85
|
+
// skills 必填:**谁决定目标集**由调用方表态——守卫族的异步面(判前端)与状态族的同步面
|
|
86
|
+
// (protocol-utils 的 declarationSkillTargets)取的不是同一套结论,一个缺省值会把两者悄悄换掉。
|
|
87
|
+
export function declarationCommands({ node, skills, frontend = false, context }) {
|
|
88
|
+
return skills.map((skill) => ({ skill, command: declarationCommand({ node, skill, frontend, context }) }));
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// 状态命令族的运行上下文:脚本目录由本模块位置推导(它在 scripts/lib 下),包根是脚本目录的上一级,
|
|
92
|
+
// 运行根取状态上下文(入口在分派前初始化),协议路径用入口同一个解析器按同一批参数解析
|
|
93
|
+
// (CLI > 环境变量 > 内置默认)——命令自带的协议上下文因此就是本次运行的那一份,而不是另取一次。
|
|
94
|
+
// 守卫族有自己的运行上下文(FLOW_COMET_RUN_ROOT + 状态绑定的协议),按同一形状自行提供,不走本函数。
|
|
95
|
+
export function commandContext({ argv = [], runRoot = runRootDir() } = {}) {
|
|
96
|
+
const scriptsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
|
|
97
|
+
const packageRoot = path.resolve(scriptsDir, '..');
|
|
98
|
+
return { scriptsDir, runRoot, packageRoot, protocolPath: resolveProtocol(packageRoot, runRoot, argv.slice(3)) };
|
|
99
|
+
}
|
|
100
|
+
|
|
25
101
|
// ① 产出物模板现问(加载链的第三环):与 entry 的 READ TEMPLATE 行同源同实现(protocol-utils
|
|
26
102
|
// 的 templatePointerLines),只换标签——两处措辞一处维护。零模板节点不打印。
|
|
27
103
|
// 条件模板行在本通道无条件列出(本通道不读状态、不判前端),并显式标注「仅前端 change」:是否
|
|
@@ -87,15 +163,18 @@ function printNodeSkillCalls(node) {
|
|
|
87
163
|
}
|
|
88
164
|
}
|
|
89
165
|
|
|
90
|
-
// ④ 三条命令(entry / exit / record,按节点 id
|
|
91
|
-
//
|
|
92
|
-
// 便跑不了——加引号后三种平台语义下都是**单一参数**(引号本身对无空格路径无害)。
|
|
166
|
+
// ④ 三条命令(entry / exit / record,按节点 id 与平台化路径形态生成)。命令文本一律由
|
|
167
|
+
// scriptCommand 产出(唯一实现,与运行期恢复 / 预检消息同形):脚本路径整条加双引号。
|
|
93
168
|
function printNodeCommands(node, scriptsDir) {
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
console.log('COMMAND
|
|
98
|
-
|
|
169
|
+
console.log('COMMAND entry: ' + scriptCommand({
|
|
170
|
+
scriptsDir, script: 'workflow-guard.mjs', args: ['entry', node.id],
|
|
171
|
+
}));
|
|
172
|
+
console.log('COMMAND exit: ' + scriptCommand({
|
|
173
|
+
scriptsDir, script: 'workflow-guard.mjs', args: ['exit', node.id, '--apply'],
|
|
174
|
+
}));
|
|
175
|
+
console.log('COMMAND record: ' + scriptCommand({
|
|
176
|
+
scriptsDir, script: 'workflow-state.mjs', args: ['record', node.id, `'{"summary":"<完成摘要>"}'`],
|
|
177
|
+
}));
|
|
99
178
|
}
|
|
100
179
|
|
|
101
180
|
// explain <node>:缺参 / 纯空白 / 拿选项当节点名(如 --help)→ 用法错误(fail-closed,不猜)
|
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
// 状态读写与 .specs 路径上下文(单一归属):状态文件解析 / 原子写落盘 / 活动 change 解析 /
|
|
2
2
|
// change 目录边界,以及各命令族共用的路径锚(runRoot · specsRoot · statePath)。
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
|
|
3
|
+
// 路径锚由入口在分派前初始化一次;运行根由唯一解析模块(run-root.mjs)给定——FLOW_COMET_RUN_ROOT
|
|
4
|
+
// 优先、否则进程 cwd。模块内不自行取 cwd:入口与模块各持一份「运行根」就是同一事实的第二处表达。
|
|
5
|
+
// 目录名与状态文件名常量来自 state-schema.mjs。
|
|
6
|
+
import { existsSync, promises as fs, readdirSync } from 'fs';
|
|
6
7
|
import path from 'path';
|
|
7
8
|
import { validateStateFields, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME } from '../state-schema.mjs';
|
|
8
9
|
import { inspectWorkflowPathSegments } from '../protocol-utils.mjs';
|
|
9
10
|
import { isSingleSegmentChangeName } from '../route-node.mjs';
|
|
11
|
+
// 归档目录名的日期前缀判据(<YYYY-MM-DD>-<change-id>)由 time-utils 单源表达:本模块只取「日期
|
|
12
|
+
// 前缀」这一事实再精确比对整名,不在路径规则里内联第二份日期正则。
|
|
13
|
+
import { archiveDateFromName } from '../time-utils.mjs';
|
|
10
14
|
|
|
11
15
|
let runtimeContext = null;
|
|
12
16
|
|
|
@@ -39,19 +43,37 @@ export async function fileExists(file) {
|
|
|
39
43
|
try { await fs.access(file); return true; } catch { return false; }
|
|
40
44
|
}
|
|
41
45
|
|
|
46
|
+
// 「在办」身份的唯一判据:state.activeChange 非空 ∧ status ≠ 'completed' ⇒ 在办(返回 change 名),
|
|
47
|
+
// 否则 null。目录在不在**不参与**(位置由 resolveChangeDir 回答)。抽成具名函数是为了让「同一身份
|
|
48
|
+
// 口径」有唯一表达:findActiveChange(读文件 + state 缺失时的恢复扫描)与 init 的覆盖闸门(手里
|
|
49
|
+
// 已有 prevState,不重读)消费的是同一条规则,而不是各写一遍表达式。
|
|
50
|
+
// 消费方注意:init 的闸门只认状态——state 文件缺席时「没有可被覆盖的旧状态」,恢复扫描出的目录
|
|
51
|
+
// 不构成阻断理由,也不该被当成留档对象。
|
|
52
|
+
export function inFlightChangeName(state) {
|
|
53
|
+
if (!state || typeof state !== 'object' || Array.isArray(state)) return null;
|
|
54
|
+
if (state.status === 'completed') return null;
|
|
55
|
+
return typeof state.activeChange === 'string' && state.activeChange !== '' ? state.activeChange : null;
|
|
56
|
+
}
|
|
57
|
+
|
|
42
58
|
export async function findActiveChange() {
|
|
43
|
-
// 1.
|
|
59
|
+
// 1. 身份只看状态(单一判定,判据 = inFlightChangeName):state 存在 ∧ activeChange 非空 ∧
|
|
60
|
+
// status ≠ 'completed' ⇒ 在办。目录在不在**不参与**身份判定——位置由 resolveChangeDir 回答:
|
|
61
|
+
// 归档搬移只是把目录换个位置,change 仍在办(移动后 status / next / record 照常报进行中)。
|
|
62
|
+
// 把身份绑在「活动目录存在」上会让移动后瞬时丢掉身份,命令层随即把在办 change 报成
|
|
63
|
+
// no-change / NEXT: done(假答案)。
|
|
44
64
|
if (await fileExists(stateFile())) {
|
|
45
65
|
const state = await readJson(stateFile());
|
|
46
|
-
|
|
47
|
-
|
|
66
|
+
const inFlight = inFlightChangeName(state);
|
|
67
|
+
if (inFlight) return inFlight;
|
|
68
|
+
// completed 检查优先于恢复扫描——归档完成态(无论 activeChange 是否残留)一律不识别为 active
|
|
69
|
+
//(防归档残留目录 / 残留字段误判)
|
|
48
70
|
if (state.status === 'completed') return null;
|
|
49
|
-
if (state.activeChange) {
|
|
50
|
-
const changeDir = path.join(specsDir(), state.activeChange);
|
|
51
|
-
if (await fileExists(changeDir)) return state.activeChange;
|
|
52
|
-
}
|
|
53
71
|
}
|
|
54
|
-
// 2.
|
|
72
|
+
// 2. .specs/ 扫描**只是 state 丢失时的恢复通道,不是第二身份来源**:它只在「无 state 文件」
|
|
73
|
+
// 与「state 无 activeChange」两种情形下运行,触发条件与上一步的分支互斥。读这段时不要把它当成
|
|
74
|
+
// 另一个身份来源——那会让同一事实出现两套判定(state 说 A、目录扫描说 B,命令各取一套)。
|
|
75
|
+
// 位置(活动 / 归档)由 resolveChangeDir 回答,不在本函数内。
|
|
76
|
+
// Scan .specs/ for directories with TASK.md (active flow-kit changes)
|
|
55
77
|
// 注: 曾尝试按 archive/ 对应归档跳过残留目录——但会误伤同名新 change(既有实证),已撤回。
|
|
56
78
|
// 「state 缺失 + 归档残留」为已知限制;归档后正常态由上文 completed 分支覆盖。
|
|
57
79
|
try {
|
|
@@ -145,3 +167,202 @@ export async function inspectReentryChangeDir(changeName) {
|
|
|
145
167
|
if (!(await hasExactSpecsEntry(changeName))) return { ok: false, reason: 'change-name-invalid' };
|
|
146
168
|
return { ok: true, changeDir };
|
|
147
169
|
}
|
|
170
|
+
|
|
171
|
+
// 归档目录名是否本 change 的归档目录:`<YYYY-MM-DD>-<change-id>` 精确形态,不做后缀匹配。
|
|
172
|
+
// 别的 change 的归档目录也可能以 `-<本 change>` 结尾(如 other-<本 change>),后缀匹配会把**别的
|
|
173
|
+
// change 的目录**认作本 change 的:声明标记门据此拿别人的声明替本 change 作证、归档提名据此数别人的
|
|
174
|
+
// SUMMARY 份数、守卫据此把本 change 判成「已归档」而跳过真实跑验证命令。日期形态取 time-utils 的单源
|
|
175
|
+
// 判定,本处只把整名与日期前缀拼回去做精确比对。
|
|
176
|
+
//
|
|
177
|
+
// 三个消费面(声明标记目录解析、守卫的「是否已归档」、归档提名的 SUMMARY 份数)都走这一条判据:
|
|
178
|
+
// 归档目录名是「哪个 change 的」这一事实只有一种说法,各写一份必然在「后缀算不算数」上分叉。
|
|
179
|
+
export function isArchivedChangeDirName(entry, changeName) {
|
|
180
|
+
if (typeof entry !== 'string' || typeof changeName !== 'string' || changeName === '') return false;
|
|
181
|
+
const archiveDate = archiveDateFromName(entry);
|
|
182
|
+
return archiveDate !== null && entry === archiveDate + '-' + changeName;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// ---------- change 目录定位(唯一实现) ----------
|
|
186
|
+
// 给定 change 名,回答「这个 change 的目录现在在哪」:活动目录 .specs/<id>/ 优先;不在就是归档目录
|
|
187
|
+
// .specs/archive/<YYYY-MM-DD>-<id>/(整名精确比对——判据单源 isArchivedChangeDirName,不写第二份
|
|
188
|
+
// 日期规则)。多候选按日期判:排除日期早于 state.createdAt 日期部分的候选、取日期最新的一份;
|
|
189
|
+
// 仍并列 / 无候选 → **不猜**,把候选交还调用方按 fail-closed 处理(status='ambiguous' | 'missing')。
|
|
190
|
+
//
|
|
191
|
+
// 身份与位置是两件事:身份只看 state(findActiveChange),本函数只回答位置。目录缺失不影响「这个
|
|
192
|
+
// change 在办」的判定,只影响命令能不能落地——所以运行命令在解析不到时必须 fail-closed 并点名两处
|
|
193
|
+
// 路径,而不是把在办 change 报成「没有在办 change」。
|
|
194
|
+
//
|
|
195
|
+
// 落点在本模块(.specs 路径上下文):这是一条 change 目录的路径规则,命令族 / 守卫族 / 委托脚本都
|
|
196
|
+
// 消费它,各写一份必然在「活动目录优先对不对」「多归档目录取哪个」上分叉(L-067)。运行根是显式
|
|
197
|
+
// 参数:各族注入自己的根(状态族 runRootDir()、守卫族 runRoot),规则不绑定任何一族的运行上下文。
|
|
198
|
+
//
|
|
199
|
+
// 返回形态(消费方按 status 分派,不解读 dir 的字符串形态):
|
|
200
|
+
// { status: 'active', dir, relative, display, archiveDate: null, candidates: [] }
|
|
201
|
+
// { status: 'archived', dir, relative, display, archiveDate, candidates }
|
|
202
|
+
// { status: 'missing', dir: null, relative: null, display: null, archiveDate: null, candidates }
|
|
203
|
+
// { status: 'ambiguous', dir: null, relative: null, display: null, archiveDate, candidates }
|
|
204
|
+
// relative = 相对 .specs/ 的 POSIX 路径('<id>' / 'archive/<日期>-<id>')——节点推导的产物根就按它
|
|
205
|
+
// 拼(见 route-node.resolveNextNode 的 changeDir 入参);display = 用户可见的 .specs/... 形态。
|
|
206
|
+
export async function resolveChangeDir({ root, changeName, createdAt = null } = {}) {
|
|
207
|
+
const specsRoot = path.join(root, '.specs');
|
|
208
|
+
const activeDir = path.join(specsRoot, changeName);
|
|
209
|
+
if (await fileExists(activeDir)) {
|
|
210
|
+
return {
|
|
211
|
+
status: 'active',
|
|
212
|
+
dir: activeDir,
|
|
213
|
+
relative: changeName,
|
|
214
|
+
display: '.specs/' + changeName,
|
|
215
|
+
archiveDate: null,
|
|
216
|
+
candidates: [],
|
|
217
|
+
};
|
|
218
|
+
}
|
|
219
|
+
const archiveRoot = path.join(specsRoot, 'archive');
|
|
220
|
+
const entries = await fs.readdir(archiveRoot).catch(() => []);
|
|
221
|
+
const candidates = [];
|
|
222
|
+
for (const entry of entries) {
|
|
223
|
+
if (!isArchivedChangeDirName(entry, changeName)) continue;
|
|
224
|
+
candidates.push({ name: entry, date: archiveDateFromName(entry) });
|
|
225
|
+
}
|
|
226
|
+
const lowerBound = archiveDateLowerBound(createdAt);
|
|
227
|
+
const eligible = lowerBound === null
|
|
228
|
+
? candidates.slice()
|
|
229
|
+
: candidates.filter((candidate) => candidate.date >= lowerBound);
|
|
230
|
+
if (eligible.length === 0) {
|
|
231
|
+
return { status: 'missing', dir: null, relative: null, display: null, archiveDate: null, candidates };
|
|
232
|
+
}
|
|
233
|
+
// 日期字典序 = 时间序(同一 YYYY-MM-DD 形态);同日期多份即并列,不按 readdir 顺序挑一份。
|
|
234
|
+
// 判据契约是「排不出唯一就停」:在 `<日期>-<id>` 精确名规则下同一日期不可能有两份(每个日期只
|
|
235
|
+
// 拼出一个名字),所以并列支正常不可达——保留它是因为「不猜」是解析器对调用方的承诺,不该是某条
|
|
236
|
+
// 命名规则的副产品(命名规则一放宽,是本支先接住,而不是 readdir 顺序先替人做决定)。
|
|
237
|
+
const newest = eligible.reduce((best, candidate) => (candidate.date > best.date ? candidate : best), eligible[0]);
|
|
238
|
+
const tied = eligible.filter((candidate) => candidate.date === newest.date);
|
|
239
|
+
if (tied.length > 1) {
|
|
240
|
+
return { status: 'ambiguous', dir: null, relative: null, display: null, archiveDate: newest.date, candidates };
|
|
241
|
+
}
|
|
242
|
+
return {
|
|
243
|
+
status: 'archived',
|
|
244
|
+
dir: path.join(archiveRoot, newest.name),
|
|
245
|
+
relative: 'archive/' + newest.name,
|
|
246
|
+
display: '.specs/archive/' + newest.name,
|
|
247
|
+
archiveDate: newest.date,
|
|
248
|
+
candidates,
|
|
249
|
+
};
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
// createdAt 的日期下界:取 state 时间戳的前 10 个字符,交给 time-utils 的归档日期判据校验(不写
|
|
253
|
+
// 第二份日期形态正则)。形态不可判 → null = 不设下界(判不了的日期不许当作「全都太早」把唯一
|
|
254
|
+
// 候选也排掉)。
|
|
255
|
+
function archiveDateLowerBound(createdAt) {
|
|
256
|
+
if (typeof createdAt !== 'string') return null;
|
|
257
|
+
return archiveDateFromName(createdAt.trim().slice(0, 10));
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
// 位置解析的命令面形态:可解析 → { ok: true, resolution };解析不到 → { ok: false, resolution,
|
|
261
|
+
// message }。退出码与打印归命令层(本模块不 process.exit),但**报文文本**落在这里——status /
|
|
262
|
+
// next / record / skill-load 必须说同一句话(成因只有「两处都没有」与「多候选判不出」两类,各写
|
|
263
|
+
// 一份措辞必然分叉)。
|
|
264
|
+
export async function resolveChangeLocation({ root, changeName, createdAt = null } = {}) {
|
|
265
|
+
const resolution = await resolveChangeDir({ root, changeName, createdAt });
|
|
266
|
+
if (resolution.status === 'active' || resolution.status === 'archived') {
|
|
267
|
+
return { ok: true, resolution };
|
|
268
|
+
}
|
|
269
|
+
return { ok: false, resolution, message: changeLocationFailureMessage(changeName, resolution) };
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
// 位置解析失败的可见报文(fail-closed 的唯一措辞):
|
|
273
|
+
// · missing:身份在办但两处目录都没有(running-orphan)——命令不得回落到「没有在办 change」;
|
|
274
|
+
// · ambiguous:同名归档多候选且日期判不出唯一一份——不许猜,列出候选请人工处置。
|
|
275
|
+
export function changeLocationFailureMessage(changeName, resolution) {
|
|
276
|
+
const activeDisplay = '.specs/' + changeName;
|
|
277
|
+
if (resolution.status === 'ambiguous') {
|
|
278
|
+
return 'BLOCKED: 归档目录多候选,无法唯一判定 ' + changeName + ' 的目录(' + resolution.archiveDate
|
|
279
|
+
+ ' 存在 ' + resolution.candidates.filter((candidate) => candidate.date === resolution.archiveDate).length
|
|
280
|
+
+ ' 份:' + resolution.candidates.map((candidate) => candidate.name).join('、')
|
|
281
|
+
+ ')——保留一份后重跑;引擎不猜';
|
|
282
|
+
}
|
|
283
|
+
const excluded = resolution.candidates.length > 0
|
|
284
|
+
? '(归档区同名候选 ' + resolution.candidates.map((candidate) => candidate.name).join('、')
|
|
285
|
+
+ ' 的日期均早于本次 change 的创建日期)'
|
|
286
|
+
: '';
|
|
287
|
+
return 'BLOCKED: change 目录缺失(' + activeDisplay + ' 与 .specs/archive/<日期>-' + changeName
|
|
288
|
+
+ ' 均不存在)' + excluded
|
|
289
|
+
+ '——身份由状态判定(该 change 仍在办),位置解析不到;恢复: 把目录移回 ' + activeDisplay
|
|
290
|
+
+ ',或按 <YYYY-MM-DD>-' + changeName + ' 命名放进 .specs/archive/ 后重跑';
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
// ---------- 恢复指引里的「目录在哪」(唯一分叉 · 状态族与门禁族共用) ----------
|
|
294
|
+
|
|
295
|
+
// 「目录已不在活动位置、而在归档里」的可见形态(恢复指引据此换一种说法):活动目录在原位 → null;
|
|
296
|
+
// 归档区里通过 isArchivedChangeDirName 的条目(同名多份取日期最新的一份)→ 该目录的 .specs/ 形态。
|
|
297
|
+
// 只回答「在不在归档、叫什么」,不参与定位写入(定位唯一实现是 resolveChangeDir,它还要套
|
|
298
|
+
// createdAt 下界与并列判定)。恢复指引只关心「活动位置空没空」,同步取值即可——出口链上有同步门禁
|
|
299
|
+
//(entry 记录门)取用同一份事实,不为一条提示改它的调用约定。
|
|
300
|
+
//
|
|
301
|
+
// 恢复动作的分叉**只有这一处实现**:活动态给 advance / select,归档态只给「把目录移回活动位置」。
|
|
302
|
+
// 四类消费方共用它——出口的转移前置 BLOCK、出口的 entry 记录门、证据门的状态漂移句、状态族的
|
|
303
|
+
// next 节点顺序门禁。此前实现落在门禁族(guard-routing),next 侧拿不到就自己拼了一句,于是同一
|
|
304
|
+
// 分叉只改了三处、漏了第四处(归档态下 next 推销走不通的 advance / select)。落点因此迁到本模块
|
|
305
|
+
// (.specs 路径上下文):状态族取用这里是允许的 state ← guard 单向边,反向 import 门禁族会把整个
|
|
306
|
+
// 守卫图拖进 workflow-state.mjs。运行根是显式参数(状态族 runRootDir()、门禁族 runRoot)——规则
|
|
307
|
+
// 不绑定任何一族的运行上下文,与 resolveChangeDir 同一形态。
|
|
308
|
+
export function archivedChangeLocationAt(root, changeName) {
|
|
309
|
+
if (!changeName) return null;
|
|
310
|
+
if (existsSync(path.join(root, '.specs', changeName))) return null;
|
|
311
|
+
let entries = [];
|
|
312
|
+
try {
|
|
313
|
+
entries = readdirSync(path.join(root, '.specs', 'archive'));
|
|
314
|
+
} catch {
|
|
315
|
+
return null;
|
|
316
|
+
}
|
|
317
|
+
// 归档日期是 YYYY-MM-DD(字典序 = 时间序),点名最新的一份(多份的真实处置是 resolveChangeDir 的
|
|
318
|
+
// 「排不出就停」,这里只给一句可执行的指引,不复制那套判定)。
|
|
319
|
+
const names = entries.filter((entry) => isArchivedChangeDirName(entry, changeName)).sort();
|
|
320
|
+
if (names.length === 0) return null;
|
|
321
|
+
return '.specs/archive/' + names[names.length - 1];
|
|
322
|
+
}
|
|
323
|
+
|
|
324
|
+
// 恢复动作那一句(与 archivedChangeLocationAt 同一分叉):活动目录在场时原样返回 activeText(调用方
|
|
325
|
+
// 给出的可行动作);目录已搬进归档时 advance / select 都走不通——select 要求活动目录在场,advance 的
|
|
326
|
+
// 产物推导读的也是活动路径,给出去就是让人去做一件做不到的事。此时只给可执行的那一步(把目录移回
|
|
327
|
+
// 活动位置),并保留「禁止手改状态机器字段」。
|
|
328
|
+
export function recoveryActionTextAt(root, changeName, activeText) {
|
|
329
|
+
const location = archivedChangeLocationAt(root, changeName);
|
|
330
|
+
if (location === null) return activeText;
|
|
331
|
+
return '本 change 的目录已移到归档位置(' + location + ')——恢复动作是把它移回活动位置 '
|
|
332
|
+
+ '.specs/' + changeName + '/ 后重跑;禁止手改 state 机器字段';
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
// 声明标记目录解析(活动路径 .specs/<change-id>/.skill-loads/ 优先;归档路径兜底):规范顺序是
|
|
336
|
+
// 「声明 → 记录 → 搬目录 → exit」——搬目录在 exit 前、记录之后;移动后补 record / 补声明仅作
|
|
337
|
+
// 兼容 / 恢复路径,标记因此仍须能在 .specs/archive/<日期>-<change-id>/.skill-loads/ 被读到。
|
|
338
|
+
// 只查活动路径会把「标记存在」误判成「机制未激活」。归档目录的**定位**(是哪一份、多候选
|
|
339
|
+
// 怎么办)走 resolveChangeDir 的唯一实现;本函数只把 .skill-loads/ 追加在解析到的目录之后。协议
|
|
340
|
+
// 声明的 archive/*-<change-id> 是产物 glob,目录名约定才是 <日期>-<change-id>(判据见
|
|
341
|
+
// isArchivedChangeDirName)。两者皆无 → null,调用方按「一项都没声明」处理。
|
|
342
|
+
//
|
|
343
|
+
// includeArchive 是这条规则唯一的形态开关,缺省 true(兜底归档)。入口侧(workflow-guard 的
|
|
344
|
+
// checkPromptDeclarations)传 false:入口核对的是**这一轮**写下的声明,归档里的声明属于归档前的
|
|
345
|
+
// 执行者——拿它替当前节点作证会把「这一轮没声明」判成「声明过」,错路径的声明因此漏过。这个差异
|
|
346
|
+
// 是有意的,所以给它一个名字,而不是让调用方另拼一份路径。
|
|
347
|
+
//
|
|
348
|
+
// 落点在本模块(.specs 路径上下文):它是一条 change 目录的定位规则,不是某一族的判定——状态命令族与
|
|
349
|
+
// 守卫族消费的是同一条规则,各写一份必然在「活动目录是否回溯归档」「多归档目录取哪个」上分叉。
|
|
350
|
+
// 运行根是显式参数:两族各注入自己的根(状态族 runRootDir()、守卫族 runRoot),规则因此不绑定任何
|
|
351
|
+
// 一族的运行上下文(守卫进程没有 initStateContext 建立的上下文)。依赖方向也由此确定:守卫侧取用本
|
|
352
|
+
// 模块是允许的 guard → state-* 单向边;反向(状态族 import 守卫族)会让状态 CLI 为一条路径规则加载
|
|
353
|
+
// 整个守卫图。
|
|
354
|
+
export async function findSkillLoadsDir(root, changeName, { includeArchive = true } = {}) {
|
|
355
|
+
const activeDir = path.join(root, '.specs', changeName, '.skill-loads');
|
|
356
|
+
if (await fileExists(activeDir)) {
|
|
357
|
+
return { dir: activeDir, display: '.specs/' + changeName + '/.skill-loads/' };
|
|
358
|
+
}
|
|
359
|
+
if (!includeArchive) return null;
|
|
360
|
+
// 归档路径 = 位置解析的结果 + .skill-loads/ —— 目录定位只有 resolveChangeDir 一份实现:标记查找、
|
|
361
|
+
// 命令写入与节点推导必须认同一个目录(否则「标记在 A、产物在 B」)。位置解析到活动目录时本函数
|
|
362
|
+
// 已在上一步返回;解析不出(缺失 / 多候选)→ null(调用方按「一项都没声明」fail-closed,不猜)。
|
|
363
|
+
const resolution = await resolveChangeDir({ root, changeName });
|
|
364
|
+
if (resolution.status !== 'archived') return null;
|
|
365
|
+
const candidate = path.join(resolution.dir, '.skill-loads');
|
|
366
|
+
if (!(await fileExists(candidate))) return null;
|
|
367
|
+
return { dir: candidate, display: resolution.display + '/.skill-loads/' };
|
|
368
|
+
}
|