flow-comet 1.6.0 → 1.6.1
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/GUIDANCE.md +22 -3
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +20 -1
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +3 -3
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +15 -15
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +19 -11
- package/.flow-comet/skills/flow-comet/reference/recovery.md +1 -7
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +21 -3
- package/.flow-comet/skills/flow-comet/scripts/contract-check.mjs +41 -31
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +2513 -295
- package/.flow-comet/skills/flow-comet/scripts/protocol-utils.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +459 -11
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +3 -3
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +422 -10
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +140 -226
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +1 -1
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +362 -4
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-change/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-design/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-dev/SKILL.md +3 -1
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +6 -4
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-open/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +17 -6
- package/.flow-comet/skills/flow-comet-requirement/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-review/SKILL.md +7 -5
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +12 -9
- package/.flow-comet/skills/flow-comet-task/SKILL.md +7 -3
- package/.flow-comet/skills/flow-comet-test/SKILL.md +2 -0
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +7 -5
- package/README.md +45 -119
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +2 -2
|
@@ -9,7 +9,7 @@ import { resolveProtocol, readProtocolFile, validateProtocolSchema, NODE_PROTOCO
|
|
|
9
9
|
import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, looksLikeObjectLiteral, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, toPersistedProtocolPath } from './state-schema.mjs';
|
|
10
10
|
import { probeProject, classify, printDetection, validateContext, printGenerationGuide, skipInit } from './context-init.mjs';
|
|
11
11
|
import { taskOpeningAttrs, taskBlocks } from './task-parsing.mjs';
|
|
12
|
-
import { route, resolveNextNode, hasSubagentNode, protocolTaskFilePath, resolveFixRollbackDecision, resolveFixRollbackState, applyFixRollbackRound, resolveFixReturnNode, resolveReentryDecision, isSingleSegmentChangeName, REENTRY_ROUND_LIMIT, REENTRY_TARGET_NODE_IDS, EXECUTE_FAMILY_NODE_IDS } from './route-node.mjs';
|
|
12
|
+
import { route, resolveNextNode, hasSubagentNode, protocolTaskFilePath, resolveFixRollbackDecision, resolveFixRollbackState, applyFixRollbackRound, resolveFixReturnNode, resolveReentryDecision, resolveReplanDecision, analyzeDependencyGraph, findParallelWriteConflicts, isSingleSegmentChangeName, REENTRY_ROUND_LIMIT, REENTRY_TARGET_NODE_IDS, REPLAN_ROUND_LIMIT, EXECUTE_FAMILY_NODE_IDS } from './route-node.mjs';
|
|
13
13
|
|
|
14
14
|
const command = process.argv[2] ?? 'status';
|
|
15
15
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
@@ -426,7 +426,7 @@ function printBranchLine(activeChange, branchPrefix = 'change/') {
|
|
|
426
426
|
|
|
427
427
|
// C6: writeState 写入前校验已知字段类型(fail-closed:非法 → BLOCKED 拒绝写入,不修复不猜测)
|
|
428
428
|
// 未知字段允许(前向兼容);缺字段允许(readState 默认补);只校验存在字段的类型。
|
|
429
|
-
// 内置节点常量: 校验表已迁移到 state-schema.mjs
|
|
429
|
+
// 内置节点常量: 校验表已迁移到 state-schema.mjs(唯一来源),行为与迁移前的内联表完全一致(对第一个非法字段输出后退出)
|
|
430
430
|
async function writeState(state) {
|
|
431
431
|
const bad = validateStateFields(state);
|
|
432
432
|
if (bad.length) {
|
|
@@ -878,12 +878,39 @@ async function main() {
|
|
|
878
878
|
}
|
|
879
879
|
const state = await readState();
|
|
880
880
|
const detectedNode = await determineNode(changeName, protocol, state.completedNodes);
|
|
881
|
+
// 派生视图(ADR-013 决策 11;2026-09-28 PR 审查采纳改为事件为准):被强制推进的节点以
|
|
882
|
+
// state.history 中本 change 的 advance-forced 事件为唯一判据——按 change 过滤(兼容旧事件
|
|
883
|
+
// 无 change 字段),取 e.node 集合后与 completedNodes 求交。旧「completedNodes 含而 evidence
|
|
884
|
+
// 不含」推断会漏报两类真实反例:① record 后被 advance;② replan/reenter 写授权留痕
|
|
885
|
+
// (evidence.<node>.replanAuthorization)后被 advance。state.history === undefined 的旧 state
|
|
886
|
+
// 无事件可依(advance 当时无痕)→ 回退本「缺 evidence」判据。
|
|
887
|
+
const completedArr = Array.isArray(state.completedNodes) ? state.completedNodes : [];
|
|
888
|
+
let forcedNodes;
|
|
889
|
+
if (state.history === undefined) {
|
|
890
|
+
const evidenceMap = state.evidence && typeof state.evidence === 'object' && !Array.isArray(state.evidence)
|
|
891
|
+
? state.evidence
|
|
892
|
+
: {};
|
|
893
|
+
forcedNodes = completedArr.filter((id) => {
|
|
894
|
+
const record = evidenceMap[id];
|
|
895
|
+
return !(record && typeof record === 'object' && !Array.isArray(record));
|
|
896
|
+
});
|
|
897
|
+
} else {
|
|
898
|
+
const forcedSet = new Set(
|
|
899
|
+
(Array.isArray(state.history) ? state.history : [])
|
|
900
|
+
.filter((e) => e
|
|
901
|
+
&& e.event === 'advance-forced'
|
|
902
|
+
&& (typeof e.change !== 'string' || e.change === changeName))
|
|
903
|
+
.map((e) => e.node)
|
|
904
|
+
);
|
|
905
|
+
forcedNodes = completedArr.filter((id) => forcedSet.has(id));
|
|
906
|
+
}
|
|
881
907
|
console.log(JSON.stringify({
|
|
882
908
|
status: 'running',
|
|
883
909
|
change: changeName,
|
|
884
910
|
currentNode: detectedNode,
|
|
885
911
|
stateCurrentNode: state.currentNode,
|
|
886
912
|
completedNodes: state.completedNodes,
|
|
913
|
+
forcedNodes,
|
|
887
914
|
executionMode: state.executionMode ?? 'subagent',
|
|
888
915
|
directOverride: state.directOverride ?? false,
|
|
889
916
|
branchMode: isInsideWorkTree(),
|
|
@@ -1139,7 +1166,7 @@ async function main() {
|
|
|
1139
1166
|
const changeName = await findActiveChange();
|
|
1140
1167
|
if (!changeName) {
|
|
1141
1168
|
// 归档后场景:change 目录已移入 .specs/archive/(无活跃 change)——skill-load 不可用,
|
|
1142
|
-
// 但 record 的声明自动化(M5)
|
|
1169
|
+
// 但 record 的声明自动化(M5)仍可写归档路径标记——消息如实引导(真实运行实证反馈)
|
|
1143
1170
|
throw new Error('skill-load requires an active change(先运行 init <change-id>;若该 change 已归档,声明标记由 record 自动补写——M5 会写入归档路径的 .skill-loads/)');
|
|
1144
1171
|
}
|
|
1145
1172
|
// 标记 protocol 字段 = --prompt 参数的 basename(如 0-change.md)——与 guard exit
|
|
@@ -1375,14 +1402,35 @@ async function main() {
|
|
|
1375
1402
|
console.log('No active change. Use select first.');
|
|
1376
1403
|
return;
|
|
1377
1404
|
}
|
|
1405
|
+
// 被强制推进的节点 = 推进前的 currentNode:exit 门禁未跑(无出口证据),这正是留痕与
|
|
1406
|
+
// 可见性的依据(ADR-013 决策 10/11)。advance 的推进语义保持不变,但每次使用都必须写
|
|
1407
|
+
// 审计事件并在输出显式列出被跳过的出口门禁。
|
|
1408
|
+
const forcedNode = state.currentNode;
|
|
1409
|
+
const forcedNodeId = typeof forcedNode === 'string' && forcedNode !== '' ? forcedNode : null;
|
|
1378
1410
|
if (!state.completedNodes.includes(state.currentNode)) {
|
|
1379
1411
|
state.completedNodes.push(state.currentNode);
|
|
1380
1412
|
}
|
|
1381
1413
|
// Use determineNode to get the actual next node (reads TASK.md)
|
|
1382
1414
|
const detected = await determineNode(state.activeChange, protocol, state.completedNodes);
|
|
1383
1415
|
state.currentNode = detected;
|
|
1416
|
+
if (forcedNodeId !== null) {
|
|
1417
|
+
// append-only 审计事件:change 供跨 change 检索,skipped 标识被跳过的出口门禁
|
|
1418
|
+
// (exit:<node>),reason 固定 'advance'(本 CLI 无其它原因面)。
|
|
1419
|
+
const existingHistory = Array.isArray(state.history) ? state.history : [];
|
|
1420
|
+
state.history = existingHistory.concat([{
|
|
1421
|
+
event: 'advance-forced',
|
|
1422
|
+
change: state.activeChange,
|
|
1423
|
+
node: forcedNode,
|
|
1424
|
+
skipped: ['exit:' + forcedNode],
|
|
1425
|
+
reason: 'advance',
|
|
1426
|
+
at: new Date().toISOString(),
|
|
1427
|
+
}]);
|
|
1428
|
+
}
|
|
1384
1429
|
await writeState(state);
|
|
1385
1430
|
console.log('Advanced to: ' + state.currentNode);
|
|
1431
|
+
if (forcedNodeId !== null) {
|
|
1432
|
+
console.log('ADVANCE-AUDIT: 跳过 ' + forcedNodeId + ' 的 exit 门禁;该节点无出口证据');
|
|
1433
|
+
}
|
|
1386
1434
|
return;
|
|
1387
1435
|
}
|
|
1388
1436
|
|
|
@@ -1639,7 +1687,317 @@ async function main() {
|
|
|
1639
1687
|
return;
|
|
1640
1688
|
}
|
|
1641
1689
|
|
|
1642
|
-
|
|
1690
|
+
if (command === 'replan') {
|
|
1691
|
+
// 受控计划重校重签(ADR-013):计划在执行中被证明有缺陷时,唯一合规的重签入口——只在
|
|
1692
|
+
// execute / subagent-execute 相位可用、停原位(不跳节点、不改 completedNodes),先把任务集
|
|
1693
|
+
// 重新校验(依赖图 + 任务字段,绝不豁免)再重录 state.taskHash。命令形态:
|
|
1694
|
+
// replan <reason> --authorized-by <source> [--continue-round <n>]。
|
|
1695
|
+
// 编排顺序与 reenter 同构:参数防护 → 读 state → 单一权威判定(相位/change → 授权 →
|
|
1696
|
+
// 上限与续轮 → 幂等空操作)→ 重校 → 备份(sha256)→ 重签 → 双写留痕 → REPLAN/REASON 行;
|
|
1697
|
+
// 全部判定集中在 route-node.mjs 纯函数族,BLOCK 与空操作路径一律在写盘前返回(字节零改写)。
|
|
1698
|
+
const replanUsage = '用法: workflow-state.mjs replan <reason> --authorized-by <source> [--continue-round <n>]';
|
|
1699
|
+
const replanReason = process.argv[3];
|
|
1700
|
+
if (typeof replanReason !== 'string' || replanReason.trim() === '' || replanReason.startsWith('--')) {
|
|
1701
|
+
console.error('BLOCKED: replan 缺少原因(位置参数 <reason> 必填且非空)。' + replanUsage);
|
|
1702
|
+
process.exit(1);
|
|
1703
|
+
}
|
|
1704
|
+
const reason = replanReason.trim();
|
|
1705
|
+
let authorizedBy = null;
|
|
1706
|
+
let continuationRound = null;
|
|
1707
|
+
const replanArgs = process.argv.slice(4);
|
|
1708
|
+
for (let index = 0; index < replanArgs.length; index += 1) {
|
|
1709
|
+
const arg = replanArgs[index];
|
|
1710
|
+
// 支持 --name value 与 --name=value 两种形态;--protocol 为全局参数(协议路径已由
|
|
1711
|
+
// resolveProtocol 统一解析),命令面只做占位透传。
|
|
1712
|
+
let key = arg;
|
|
1713
|
+
let value = null;
|
|
1714
|
+
if (typeof arg === 'string' && arg.startsWith('--')) {
|
|
1715
|
+
const eq = arg.indexOf('=');
|
|
1716
|
+
if (eq > 0) {
|
|
1717
|
+
key = arg.slice(0, eq);
|
|
1718
|
+
value = arg.slice(eq + 1);
|
|
1719
|
+
}
|
|
1720
|
+
}
|
|
1721
|
+
if (key === '--protocol') {
|
|
1722
|
+
if (value === null) index += 1;
|
|
1723
|
+
continue;
|
|
1724
|
+
}
|
|
1725
|
+
if (key === '--continue-round') {
|
|
1726
|
+
// 续轮授权只在达到轮次上限后生效:命令面收正整数,形态合法性与「是否已到上限」由
|
|
1727
|
+
// 单一权威综合判定裁决(本处只做数值形态防护,fail-closed,先于任何读盘)。
|
|
1728
|
+
let consumedNext = false;
|
|
1729
|
+
if (value === null) {
|
|
1730
|
+
value = replanArgs[index + 1];
|
|
1731
|
+
consumedNext = true;
|
|
1732
|
+
}
|
|
1733
|
+
const parsedRound = typeof value === 'string' && value.trim() !== '' && !value.startsWith('--')
|
|
1734
|
+
? Number(value.trim())
|
|
1735
|
+
: Number.NaN;
|
|
1736
|
+
if (!Number.isInteger(parsedRound) || parsedRound <= 0) {
|
|
1737
|
+
console.error('BLOCKED: replan --continue-round 需要正整数取值,实际 ' + JSON.stringify(value) + '。' + replanUsage);
|
|
1738
|
+
process.exit(1);
|
|
1739
|
+
}
|
|
1740
|
+
continuationRound = parsedRound;
|
|
1741
|
+
if (consumedNext) index += 1;
|
|
1742
|
+
continue;
|
|
1743
|
+
}
|
|
1744
|
+
if (key === '--authorized-by') {
|
|
1745
|
+
let consumedNext = false;
|
|
1746
|
+
if (value === null) {
|
|
1747
|
+
value = replanArgs[index + 1];
|
|
1748
|
+
consumedNext = true;
|
|
1749
|
+
}
|
|
1750
|
+
// 缺值 / 空值 / 纯空白 / 取下个选项名当值 → 一律用法错误(fail-closed,先于任何读盘)
|
|
1751
|
+
if (typeof value !== 'string' || value.trim() === '' || value.startsWith('--')) {
|
|
1752
|
+
console.error('BLOCKED: replan --authorized-by 需要非空取值。' + replanUsage);
|
|
1753
|
+
process.exit(1);
|
|
1754
|
+
}
|
|
1755
|
+
authorizedBy = value.trim();
|
|
1756
|
+
if (consumedNext) index += 1;
|
|
1757
|
+
continue;
|
|
1758
|
+
}
|
|
1759
|
+
console.error('BLOCKED: replan 未知参数 ' + JSON.stringify(arg) + '。' + replanUsage);
|
|
1760
|
+
process.exit(1);
|
|
1761
|
+
}
|
|
1762
|
+
if (authorizedBy === null) {
|
|
1763
|
+
console.error('BLOCKED: replan 需要显式授权 --authorized-by <source>(授权不可自决)。' + replanUsage);
|
|
1764
|
+
process.exit(1);
|
|
1765
|
+
}
|
|
1766
|
+
const state = await readState();
|
|
1767
|
+
const badFields = validateStateFields(state);
|
|
1768
|
+
if (badFields.length > 0) {
|
|
1769
|
+
// history 存在但非数组等类型损坏在此 fail-closed:不得由本命令静默清空覆盖审计历史。
|
|
1770
|
+
console.error('BLOCKED: state 字段类型非法: ' + badFields[0]);
|
|
1771
|
+
process.exit(1);
|
|
1772
|
+
}
|
|
1773
|
+
// 原始 state(未经 readState 兼容默认值叠加):备份取文件原始字节,落盘只写「原始键集 +
|
|
1774
|
+
// 本次实际改动的字段」——兼容默认值不得随重校回写(与受控重入同纪律)。
|
|
1775
|
+
const rawState = (await fileExists(statePath)) ? await readJson(statePath) : null;
|
|
1776
|
+
const changeName = typeof state.activeChange === 'string' ? state.activeChange : '';
|
|
1777
|
+
// 任务内容读取(fail-closed):不可读 / 为空 → 交由综合判定返回 task-content-missing
|
|
1778
|
+
// block(缺 TASK.md 时不得以「空任务集签名」判幂等空操作放行,L-079)。
|
|
1779
|
+
let taskContent = null;
|
|
1780
|
+
try {
|
|
1781
|
+
taskContent = await fs.readFile(protocolTaskFilePath(protocol, changeName, specsRoot), 'utf8');
|
|
1782
|
+
} catch { taskContent = null; }
|
|
1783
|
+
// 授权形态的 round / at 由引擎派生(命令面只承载授权来源、原因与上限后的续轮轮次):普通
|
|
1784
|
+
// 轮次以合法占位值过形态门;落盘轮次一律取综合判定返回的 round(由本 change 历史事件派生),
|
|
1785
|
+
// 不在此内联第二份轮次推导。
|
|
1786
|
+
const authorizedAt = new Date().toISOString();
|
|
1787
|
+
const decision = resolveReplanDecision({
|
|
1788
|
+
protocol,
|
|
1789
|
+
state,
|
|
1790
|
+
authorization: { round: 1, at: authorizedAt, source: authorizedBy, reason, node: state.currentNode },
|
|
1791
|
+
continuationRound,
|
|
1792
|
+
taskContent,
|
|
1793
|
+
});
|
|
1794
|
+
if (!decision.ok) {
|
|
1795
|
+
if (decision.reason === 'round-limit-reached') {
|
|
1796
|
+
console.error('BLOCKED: 本 change 计划重校已达上限(' + decision.used + '/' + decision.limit
|
|
1797
|
+
+ ' 轮)。需要人工裁决:继续(显式授权后在同一命令加 --continue-round <n>,n 为不小于第 '
|
|
1798
|
+
+ (decision.used + 1) + ' 轮的正整数,须与 --authorized-by / <reason> 同次传入)/ 停止(保持现状,不再重校)。');
|
|
1799
|
+
process.exit(1);
|
|
1800
|
+
}
|
|
1801
|
+
const replanGuidance = {
|
|
1802
|
+
'no-active-change': '当前没有活跃 change(activeChange 缺失或为空)——先 select <change-id>',
|
|
1803
|
+
'change-name-invalid': 'change 名非法 ' + JSON.stringify(changeName)
|
|
1804
|
+
+ '——必须是 .specs/ 下的单段目录名(拒绝路径分隔符、. / .. 与保留目录 archive)',
|
|
1805
|
+
'phase-not-allowed': 'replan 只在 execute / subagent-execute 相位可用(当前节点 '
|
|
1806
|
+
+ JSON.stringify(state.currentNode) + ')——其余相位请走既有推进 / 受控重入通道',
|
|
1807
|
+
'continuation-not-required': '--continue-round 只在达到轮次上限后需要(当前 ' + decision.used + '/'
|
|
1808
|
+
+ decision.limit + ' 轮)——上限前请直接以 --authorized-by / <reason> 发起',
|
|
1809
|
+
'task-content-missing': '任务内容缺失或不可读(.specs/<change>/TASK.md 不存在 / 为空)——按 fail-closed 拒绝重签',
|
|
1810
|
+
}[decision.reason] || ('授权形态不合法(' + decision.reason + ')——需要用户显式传入 --authorized-by <source>');
|
|
1811
|
+
console.error('BLOCKED: ' + replanGuidance);
|
|
1812
|
+
process.exit(1);
|
|
1813
|
+
}
|
|
1814
|
+
if (decision.action === 'noop') {
|
|
1815
|
+
console.log('REPLAN: 空操作——state.taskHash 已与当前 TASK.md 同签(' + decision.node
|
|
1816
|
+
+ '),无需重校;未备份、未计数、未写事件、未改写 state。');
|
|
1817
|
+
return;
|
|
1818
|
+
}
|
|
1819
|
+
if (decision.action !== 'apply') {
|
|
1820
|
+
console.error('BLOCKED: replan 判定返回未知动作 ' + JSON.stringify(decision.action) + '——按 fail-closed 拒绝。');
|
|
1821
|
+
process.exit(1);
|
|
1822
|
+
}
|
|
1823
|
+
// 重校(ADR-013 决策 3:replan 绝不做校验豁免):任务块 / <verify> / 任务图(依赖环与
|
|
1824
|
+
// 缺失依赖——analyzeDependencyGraph 单一实现,与 plan 出口同源)/ 7 字段完整性。任一失败
|
|
1825
|
+
// → BLOCK,状态零改写(本段全部先于备份与写盘)。
|
|
1826
|
+
const taskList = taskBlocks(taskContent);
|
|
1827
|
+
if (taskList.length === 0) {
|
|
1828
|
+
console.error('BLOCKED: TASK.md 无 <task> 块——replan 不做校验豁免,拒绝重签(状态零改写)。');
|
|
1829
|
+
process.exit(1);
|
|
1830
|
+
}
|
|
1831
|
+
const missingVerify = taskList.filter((block) => !/<verify>/.test(block));
|
|
1832
|
+
if (missingVerify.length > 0) {
|
|
1833
|
+
console.error('BLOCKED: TASK.md 中 ' + missingVerify.length
|
|
1834
|
+
+ ' 个 task 缺 <verify> 字段——replan 不做校验豁免,拒绝重签(状态零改写)。');
|
|
1835
|
+
process.exit(1);
|
|
1836
|
+
}
|
|
1837
|
+
const depGraph = analyzeDependencyGraph(taskList);
|
|
1838
|
+
if (depGraph.cyclic || depGraph.missing.length > 0) {
|
|
1839
|
+
const detail = depGraph.cyclic
|
|
1840
|
+
? '依赖环(拓扑排序无解,涉及任务: ' + depGraph.cycleIds.join(', ') + ')'
|
|
1841
|
+
: '依赖不存在的任务: ' + depGraph.missing.map((m) => m.id + '→' + m.dep).join(', ');
|
|
1842
|
+
console.error('BLOCKED: TASK.md ' + detail
|
|
1843
|
+
+ '——依赖图不可满足(任务的依赖链必须存在且无环);replan 不做校验豁免,拒绝重签(状态零改写)'
|
|
1844
|
+
+ ';恢复: 调整任务 depends_on——移除成环引用或改为真实存在的任务 id 后重试');
|
|
1845
|
+
process.exit(1);
|
|
1846
|
+
}
|
|
1847
|
+
// 任务字段完整性(与 plan 出口同一判据):新模板形态(含 <name>)且新 change → BLOCK;
|
|
1848
|
+
// 旧式一字段形态 / 旧 change 保持渐进 WARN(不放大既有语义)。
|
|
1849
|
+
const replanTask7Required = ['name', 'read_files', 'write_files', 'action', 'verify', 'done', 'depends_on'];
|
|
1850
|
+
const replanTask7NewFormat = taskList.some((block) => /<name\b/i.test(block));
|
|
1851
|
+
const replanTask7Broken = [];
|
|
1852
|
+
for (const block of taskList) {
|
|
1853
|
+
const missing = replanTask7Required.filter((field) => !new RegExp('</?' + field + '\\b', 'i').test(block));
|
|
1854
|
+
if (missing.length > 0) {
|
|
1855
|
+
const idAttr = (taskOpeningAttrs(block) || {}).id || '?';
|
|
1856
|
+
replanTask7Broken.push((idAttr !== '?' ? idAttr + ' ' : '') + '缺 ' + missing.join('/'));
|
|
1857
|
+
}
|
|
1858
|
+
}
|
|
1859
|
+
if (replanTask7Broken.length > 0) {
|
|
1860
|
+
if (replanTask7NewFormat && state.newChange === true) {
|
|
1861
|
+
console.error('BLOCKED: TASK.md 任务缺 7 字段(name/read_files/write_files/action/verify/done/depends_on): '
|
|
1862
|
+
+ replanTask7Broken.join('; ') + ';恢复: 对照 flow-kit/templates/TASK.md 补齐每个 <task> 的缺字段后重试;replan 不做校验豁免');
|
|
1863
|
+
process.exit(1);
|
|
1864
|
+
}
|
|
1865
|
+
console.error('TASK-7FIELD WARN: TASK.md ' + replanTask7Broken.join('; ')
|
|
1866
|
+
+ (replanTask7NewFormat ? '(旧 change 渐进,不阻断)' : '(旧式一字段模板形态,渐进不阻断)'));
|
|
1867
|
+
}
|
|
1868
|
+
// 路径边界:change 名必须是 .specs/ 下的单段真实目录(realpath 归一后仍在 .specs/ 内、
|
|
1869
|
+
// 无 symlink/junction 逃逸;复用受控路径边界实现)——备份落点必须先通过该边界。
|
|
1870
|
+
const changeBoundary = await inspectReentryChangeDir(changeName);
|
|
1871
|
+
if (!changeBoundary.ok) {
|
|
1872
|
+
const boundaryMessages = {
|
|
1873
|
+
'no-active-change': '当前没有活跃 change(activeChange 缺失或为空)——先 select <change-id>',
|
|
1874
|
+
'change-name-invalid': 'change 名非法 ' + JSON.stringify(changeName)
|
|
1875
|
+
+ '——必须是 .specs/ 下的单段目录名(拒绝路径分隔符、. / .. 与保留目录 archive)',
|
|
1876
|
+
'change-dir-missing': '.specs/' + (changeName || '<未知>') + '/ 目录不存在——重校备份必须具备真实 change 目录落点',
|
|
1877
|
+
'change-dir-escape': 'change 目录路径越界或跨越符号链接 / junction(' + changeBoundary.detail
|
|
1878
|
+
+ ')——受控重校与备份只允许落在 .specs/<change-id>/ 真实目录内',
|
|
1879
|
+
};
|
|
1880
|
+
console.error('BLOCKED: ' + (boundaryMessages[changeBoundary.reason] || ('change 目录边界异常(' + changeBoundary.reason + ')')));
|
|
1881
|
+
process.exit(1);
|
|
1882
|
+
}
|
|
1883
|
+
const changeDir = changeBoundary.changeDir;
|
|
1884
|
+
// 并行写冲突校验(2026-09-28 PR 审查采纳):replan 不做校验豁免——重校后的任务集若含
|
|
1885
|
+
// 本趟可运行(依赖已满足)的并行任务且 write_files 重叠,与 plan 出口使用同一实现
|
|
1886
|
+
// (route-node.findParallelWriteConflicts 单一来源)在此 BLOCK;必须早于备份与任何写盘,
|
|
1887
|
+
// BLOCK 路径 state 字节零改写。read∩write 弱判与 plan 出口同风格——仅 WARN 不阻断。
|
|
1888
|
+
// 同文件跨任务且无依赖路径(第三族)同样在此消费:与 plan 出口同判据、同分级(新 change
|
|
1889
|
+
// BLOCKED / 旧 change WARN),消息同族(任务对 `a×b(files)` + 恢复指引「补显式 depends_on 或
|
|
1890
|
+
// 合并为一个任务」)——replan 是执行期唯一合法的任务集修订通道,不得成为该形态的豁免口。
|
|
1891
|
+
const { writeConflicts, crossTaskConflicts, readWarnings } = await findParallelWriteConflicts(path.join(runRoot, '.specs', changeName));
|
|
1892
|
+
if (writeConflicts.length > 0) {
|
|
1893
|
+
console.error('BLOCKED: replan 检测到并行写冲突('
|
|
1894
|
+
+ writeConflicts.map((c) => c.a + '↔' + c.b + ': ' + c.files.join(',')).join('; ')
|
|
1895
|
+
+ ')——replan 不做校验豁免,状态零改写;恢复: 调整 write_files 消除重叠后重试');
|
|
1896
|
+
process.exit(1);
|
|
1897
|
+
}
|
|
1898
|
+
if (crossTaskConflicts.length > 0) {
|
|
1899
|
+
const crossDetail = crossTaskConflicts.map((c) => c.a + '×' + c.b + '(' + c.files.join(',') + ')').join('; ');
|
|
1900
|
+
const crossGuide = ';恢复: 补显式 depends_on 或合并为一个任务后重试';
|
|
1901
|
+
if (state.newChange === true) {
|
|
1902
|
+
console.error('BLOCKED: TASK.md 同文件跨任务且无依赖路径: ' + crossDetail
|
|
1903
|
+
+ '——replan 不做校验豁免,状态零改写' + crossGuide);
|
|
1904
|
+
process.exit(1);
|
|
1905
|
+
}
|
|
1906
|
+
console.error('WARN: TASK.md 同文件跨任务且无依赖路径(旧 change 渐进不阻断): ' + crossDetail + crossGuide);
|
|
1907
|
+
}
|
|
1908
|
+
if (readWarnings.length > 0) {
|
|
1909
|
+
console.error('WARN: TASK.md 并行任务 read∩write 隐式依赖嫌疑(一方读取对方写路径,建议补显式 depends_on 声明): '
|
|
1910
|
+
+ readWarnings.map((c) => c.a + '×' + c.b + '(' + c.files.join(',') + ')').join('; '));
|
|
1911
|
+
}
|
|
1912
|
+
const round = decision.round;
|
|
1913
|
+
const source = decision.authorization.source;
|
|
1914
|
+
const at = decision.authorization.at;
|
|
1915
|
+
const continuationAuthorized = decision.continuationAuthorized === true;
|
|
1916
|
+
const taskSetSignatureValue = decision.taskSetSignature;
|
|
1917
|
+
if (typeof taskSetSignatureValue !== 'string' || taskSetSignatureValue === '') {
|
|
1918
|
+
console.error('BLOCKED: replan 未能派生当前任务集签名——按 fail-closed 拒绝(状态零改写)。');
|
|
1919
|
+
process.exit(1);
|
|
1920
|
+
}
|
|
1921
|
+
// 备份:重签前 state 全量快照(文件原始字节,UTF-8 BOM 按可解析形态落盘);文件名
|
|
1922
|
+
// <UTC ISO 净化>-pre-replan.json;审计指纹 = 备份文件字节的 sha256(可核验)。
|
|
1923
|
+
const backupDir = path.join(changeDir, 'replan-backups');
|
|
1924
|
+
const backupFile = at.replace(/:/g, '-') + '-pre-replan.json';
|
|
1925
|
+
const backupPath = path.join(backupDir, backupFile);
|
|
1926
|
+
const backupRecord = path.relative(runRoot, backupPath).split(path.sep).join('/');
|
|
1927
|
+
const snapshotBytes = Buffer.from((await fs.readFile(statePath, 'utf8')).replace(/^\uFEFF/, ''), 'utf8');
|
|
1928
|
+
const fingerprint = createHash('sha256').update(snapshotBytes).digest('hex');
|
|
1929
|
+
const existingHistory = Array.isArray(rawState?.history) ? rawState.history : [];
|
|
1930
|
+
let backupWritten = false;
|
|
1931
|
+
try {
|
|
1932
|
+
if (!rawState || typeof rawState !== 'object' || Array.isArray(rawState)) {
|
|
1933
|
+
throw new Error('state 文件缺失或形态非法,无法重校重签');
|
|
1934
|
+
}
|
|
1935
|
+
// 备份写入路径的物理包含性复核(单一权威路径段扫描):备份目录与备份文件逐段
|
|
1936
|
+
// lstat + realpath——任何 symlink/junction 逃出 .specs/ 一律拒绝,不写任何字节。
|
|
1937
|
+
await fs.mkdir(backupDir, { recursive: true });
|
|
1938
|
+
await inspectWorkflowPathSegments(specsRoot, backupDir, 'replan backup dir', 'directory');
|
|
1939
|
+
await fs.writeFile(backupPath, snapshotBytes);
|
|
1940
|
+
backupWritten = true;
|
|
1941
|
+
await inspectWorkflowPathSegments(specsRoot, backupPath, 'replan backup file', 'file');
|
|
1942
|
+
// 双写留痕(ADR-013 决策 8):① evidence.<node>.replanAuthorization(节点级授权 + 备份
|
|
1943
|
+
// 指纹);② history 追加 replan-applied(跨 change 审计检索)。落盘形态 = 原始 state
|
|
1944
|
+
// 键集 + 本次实际改动的三处(taskHash / evidence / history),其余字段逐项不变。
|
|
1945
|
+
const existingEvidence = rawState.evidence && typeof rawState.evidence === 'object' && !Array.isArray(rawState.evidence)
|
|
1946
|
+
? rawState.evidence
|
|
1947
|
+
: {};
|
|
1948
|
+
const nodeEvidence = existingEvidence[decision.node]
|
|
1949
|
+
&& typeof existingEvidence[decision.node] === 'object'
|
|
1950
|
+
&& !Array.isArray(existingEvidence[decision.node])
|
|
1951
|
+
? existingEvidence[decision.node]
|
|
1952
|
+
: {};
|
|
1953
|
+
const authorizationRecord = {
|
|
1954
|
+
round,
|
|
1955
|
+
at,
|
|
1956
|
+
source,
|
|
1957
|
+
reason,
|
|
1958
|
+
backup: backupRecord,
|
|
1959
|
+
fingerprint,
|
|
1960
|
+
...(continuationAuthorized ? { continuationAuthorized: true } : {}),
|
|
1961
|
+
};
|
|
1962
|
+
const persisted = { ...rawState };
|
|
1963
|
+
persisted.taskHash = taskSetSignatureValue;
|
|
1964
|
+
persisted.evidence = {
|
|
1965
|
+
...existingEvidence,
|
|
1966
|
+
[decision.node]: { ...nodeEvidence, replanAuthorization: authorizationRecord },
|
|
1967
|
+
};
|
|
1968
|
+
persisted.history = existingHistory.concat([{
|
|
1969
|
+
event: 'replan-applied',
|
|
1970
|
+
change: changeName,
|
|
1971
|
+
node: decision.node,
|
|
1972
|
+
round,
|
|
1973
|
+
reason,
|
|
1974
|
+
authorizedBy: source,
|
|
1975
|
+
taskSetSignature: taskSetSignatureValue,
|
|
1976
|
+
backup: backupRecord,
|
|
1977
|
+
fingerprint,
|
|
1978
|
+
at,
|
|
1979
|
+
...(continuationAuthorized ? { continuationAuthorized: true } : {}),
|
|
1980
|
+
}]);
|
|
1981
|
+
const persistedBad = validateStateFields(persisted);
|
|
1982
|
+
if (persistedBad.length > 0) throw new Error('state 字段类型非法: ' + persistedBad[0]);
|
|
1983
|
+
await writeState(persisted);
|
|
1984
|
+
} catch (error) {
|
|
1985
|
+
// 写盘失败:回滚本次调用创建的孤儿备份(state 由原子写保证不被截断),原始错误照常上抛。
|
|
1986
|
+
if (backupWritten) {
|
|
1987
|
+
try { await fs.rm(backupPath, { force: true }); } catch { /* 清理失败不掩盖原始错误 */ }
|
|
1988
|
+
}
|
|
1989
|
+
throw error;
|
|
1990
|
+
}
|
|
1991
|
+
const roundLabel = continuationAuthorized
|
|
1992
|
+
? '第 ' + round + ' 轮(显式授权续轮,上限 ' + REPLAN_ROUND_LIMIT + ')'
|
|
1993
|
+
: '第 ' + round + '/' + REPLAN_ROUND_LIMIT + ' 轮';
|
|
1994
|
+
console.log('REPLAN: ' + decision.node + ' 重新校验通过(授权源 ' + source + ';' + roundLabel
|
|
1995
|
+
+ ';备份 ' + backupRecord + ')');
|
|
1996
|
+
console.log('REASON: ' + reason);
|
|
1997
|
+
return;
|
|
1998
|
+
}
|
|
1999
|
+
|
|
2000
|
+
throw new Error('Unknown command: ' + command + '. Use: init, status, next, select, record, verify-fail, advance, execution-mode, config, skill-load, bridge-check, reenter, replan');
|
|
1643
2001
|
}
|
|
1644
2002
|
|
|
1645
2003
|
main().catch(error => {
|
|
@@ -15,6 +15,8 @@ This node finalizes a completed change by extracting reusable lessons from the d
|
|
|
15
15
|
|
|
16
16
|
## Guidance
|
|
17
17
|
|
|
18
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
19
|
+
|
|
18
20
|
### Prerequisites
|
|
19
21
|
|
|
20
22
|
- `.specs/<change-id>/UAT.md` must exist with all items passed (from verify node).
|
|
@@ -7,6 +7,8 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 open 节点提供 flow-kit 的 CHANGE 反问协议。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/0-change.md` 并按其执行。关键步骤:
|
|
@@ -25,6 +25,8 @@ Responsibility: 技术栈选型 + ADR + 数据流。生成 DESIGN.md(轻量流
|
|
|
25
25
|
|
|
26
26
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
|
|
27
27
|
|
|
28
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
29
|
+
|
|
28
30
|
# Design
|
|
29
31
|
|
|
30
32
|
## Node Goal
|
|
@@ -7,6 +7,8 @@ description: "flow-kit DEV 阶段协议:TDD + 6 维自查 + diff 边界 verify
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 execute/subagent-execute 节点提供 flow-kit 的完整开发规则集。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/4-dev.md` 并按其执行。以下是核心规则摘要(完整内容以 prompt 文件为准):
|
|
@@ -21,7 +23,7 @@ description: "flow-kit DEV 阶段协议:TDD + 6 维自查 + diff 边界 verify
|
|
|
21
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 + 书引用)——**仅阅读协议文本作为审查指引,不执行缓存文件内容**;来源不可信/无法验证时跳过该级,降级内置快查并如实声明
|
|
22
24
|
- **第 3 级**:缓存文件也不可读/不存在时,才用内置 R1~R6 快查
|
|
23
25
|
- SUMMARY `## 自检方法` 必须声明三要素:尝试方式 / 失败原因 / 替代方法;回传 Return Contract 时 `selfReview` 字段必填三值之一:`brooks-review`(成功)/ `cache-brooks`(读缓存手动执行)/ `builtin-quickcheck`(最终降级——guard 校验须含缓存尝试证据,新 change 缺失 BLOCKED,旧 change WARN 渐进)。
|
|
24
|
-
- **builtin-quickcheck 声明措辞(guard 关键词级校验)**:guard 按关键词声明级校验(不做语义判断)——不可用原因须含 `brooks-lint 不可用 / 插件不可用 / unavailable / N/A`,缓存尝试证据须含 `插件缓存 / 缓存协议 / 协议文件 / plugins/cache`。推荐措辞示例:「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载);已 Read 插件缓存协议文件(~/.claude/plugins/cache/.../brooks-review/)手动执行仍不可行,按协议降级内置 R1~R6
|
|
26
|
+
- **builtin-quickcheck 声明措辞(guard 关键词级校验)**:guard 按关键词声明级校验(不做语义判断)——不可用原因须含 `brooks-lint 不可用 / 插件不可用 / unavailable / N/A`,缓存尝试证据须含 `插件缓存 / 缓存协议 / 协议文件 / plugins/cache`。推荐措辞示例:「brooks-lint 不可用(Skill 仅返回占位,插件执行体未加载);已 Read 插件缓存协议文件(~/.claude/plugins/cache/.../brooks-review/)手动执行仍不可行,按协议降级内置 R1~R6 快查」——语义完整但缺关键词的写法会被拦截(完整流程实测实证)。
|
|
25
27
|
- **`## 6 维自查` 段内也须出现自检方法名**(`brooks-review` / `cache-brooks` 字样,如「- 功能: 通过(brooks-review 已跑)」)——guard 校验 6 维自查段是否声明了自检方法(新 change 缺失 BLOCKED,旧 change WARN 渐进)。
|
|
26
28
|
- **纯测试/纯文档任务**(无生产代码改动,6 维自查非必跑)仍须满足自检方法声明与 builtin 缓存证据——可**引用同 change 其他 SUMMARY 已声明的缓存尝试**(如「自检证据见 T01-SUMMARY(cache-brooks 已读插件缓存)」)满足 guard 校验。
|
|
27
29
|
5. **diff 边界 verify(R6.5)**:`git diff --name-only` 与 TASK write_files 比对,越界必须回滚
|
|
@@ -25,6 +25,8 @@ In subagent mode (default) this node is a coordinator: it does not write impleme
|
|
|
25
25
|
|
|
26
26
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
27
27
|
|
|
28
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
29
|
+
|
|
28
30
|
### 执行模型(按 executionMode,用户显式选择)
|
|
29
31
|
|
|
30
32
|
- **subagent(默认)**: 统一委托子代理——协调者流程(构造 handoff → Agent worktree 委托 → 收集 Return Contract → 验收标 done)
|
|
@@ -40,7 +42,7 @@ execute 节点**只处理 `parallel="false"`(或未标注 parallel)的 pendi
|
|
|
40
42
|
|
|
41
43
|
**归属纪律**:request 会校验任务的并行属性与原始 `currentNode`——串行 pending 任务只归属本节点,并行 pending 任务归属 `subagent-execute`;错误节点的新 change 请求会被 BLOCK,并按输出运行 `workflow-state next` 与 `entry <目标节点>` 恢复后再重试。
|
|
42
44
|
|
|
43
|
-
**TASK 签名校验(C3,execute 期间)**:entry execute 时记录任务集签名(行尾规范化 + 标记属性剥离);exit 时比对——execute 期间 TASK.md **只允许改开标签的标记属性**(`status` done/pending;时间戳如需记录写在开标签属性如 `completed_at`——签名剥离白名单允许;**禁止写入 action/其他 task 内容**),增删任务/改 action/改边界/改其他内容会在 exit 被 BLOCKED(签名不匹配)。回退修复任务(review/verify 发现缺陷追加)须先经 review 流程追加到 `## Fix 任务`
|
|
45
|
+
**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 刷新签名(端到端验证实证:直接注入任务会被签名拦截)。
|
|
44
46
|
|
|
45
47
|
本节点**不直接写实现代码**。所有 pending 任务统一通过 Agent 工具委托 fresh-context 子代理执行(加载 flow-comet-dev + 回传 Return Contract)。
|
|
46
48
|
|
|
@@ -103,7 +105,7 @@ This node is truly done when:
|
|
|
103
105
|
- **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.
|
|
104
106
|
- **Agent thought**: "这个 parallel 任务小,我顺手在主会话做了。" **Actual risk**: 违反并行委托设计——subagent-execute 节点被静默跳过,丢失并行隔离与 write_files 冲突防护;且 execute 出口的 all-tasks-done 校验会 BLOCKED(parallel 无 handoffResult)。parallel="true" 任务只能由 subagent-execute 委托。
|
|
105
107
|
|
|
106
|
-
##
|
|
108
|
+
## 修复回路状态机路径
|
|
107
109
|
|
|
108
110
|
review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周期内完成,禁止驻留源节点「顺手修完」;引擎按以下路径强制闭环(`<源节点>` 为 review 或 verify):
|
|
109
111
|
|
|
@@ -111,10 +113,10 @@ review / verify 发现缺陷后的修复必须回到 `execute` 节点生命周
|
|
|
111
113
|
2. **受控归位 execute**:运行 `workflow-state next`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs next`),或运行 `workflow-guard entry execute`(完整命令:`node .claude/skills/flow-comet/scripts/workflow-guard.mjs entry execute`)。处于 Fix 回退态(源节点驻留 + 存在 pending Fix 任务 + 当前路由判定为 execute)时,引擎把当前节点受控归位为 `execute`(`currentNode=execute`),并输出 `FIX-BATCH` 审计行(`next` 同时输出 `NODE: execute`);用 `workflow-state.mjs status` 确认 `stateCurrentNode` 已是 `execute` 再开工;若未归位,先按 `next` / `status` 的输出核对任务状态与路由,不要未经归位硬开工。
|
|
112
114
|
3. **执行修复**:按 execute 节点生命周期完成全部 Fix 任务(委托/直写规则不变);`entry execute` 刷新任务集签名,锁定追加后的任务集——归位后不得再增删任务或修改任务内容。
|
|
113
115
|
4. **跑 execute 四类出口**:`record execute` → `exit execute --apply`。四类出口门禁真实执行——**全任务 done / 逐任务 SUMMARY 完备 / 6 维自查 + 自检方法声明 / 任务集签名一致**;任一缺失即 BLOCKED 并给出恢复指引。通过后,引擎在 Fix 二次完成时把当前节点推回源节点(review 或 verify)。
|
|
114
|
-
- **guard exit 回源审计行语义(Fix vs RETURN
|
|
116
|
+
- **guard exit 回源审计行语义(Fix vs RETURN)**:真实修复回路二次完成保留 `FIX-BATCH: 回源节点 <源节点>`(真实 Fix 回炉的机器锚);正常多趟收尾(任务集签名全等且无 Fix 标记)输出中性 `RETURN: 回源节点 <源节点>`(非 Fix 回修);旧 state 缺闭合/修复证据(无签名事件且无 Fix 标记)输出 `RETURN: 回源节点 <源节点>(旧 state 缺闭合/修复证据,未分类)`,不冒充 Fix、不 BLOCK;上述分类只改审计行文本,路由与 state 写入零变化。此处 `RETURN:` 仅指审计行前缀,与子代理 handoff 的 Return Contract 无关。
|
|
115
117
|
5. **回源节点跑出口**:回到源节点后运行 `next`,Fix 回程豁免生效时应输出 `NODE: review` 或 `NODE: verify`(不会因源节点产物已存在而跳过);若仍输出后续节点,说明回程条件未满足,先核对状态机归属与任务状态,不要继续推进。随后执行 `entry <源节点>` → `exit <源节点> --apply` 跑源节点出口门禁(即 entry/exit 源节点);通过后继续正常路由(review → verify;verify → archive),必要时进入下一轮 Fix 闭环。
|
|
116
118
|
- **`next` 回程审计行语义**:回程豁免行始终输出中性 `RETURN: 回程源节点 <源节点>`(源节点产物在场且未出口;保留源节点跑出口),不再输出 FIX-BATCH;受控归位行的 `FIX-BATCH: 归位 <execute 家族>` 保留(真实 Fix 回退行),两者不得混同。
|
|
117
|
-
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED
|
|
119
|
+
6. **禁止绕过**:驻留源节点不归位、顺手改完后直接跑源节点 exit 收场会被 BLOCKED(存在未归位/未跑出口的修复回路),必须按上述路径恢复;不得用跳过归位或出口门禁的手段(含手动改写 `.flow-comet/flow-comet-state.json`)替代本路径。
|
|
118
120
|
|
|
119
121
|
**由受控重入打开的场景(archive 源)**:缺陷在归档后才暴露、且归档移动尚未发生时,可先由用户显式授权把工作归属退回 `execute` / `subagent-execute` / `review` / `verify` 之一,再按本节路径回到 execute 生命周期完成修复。重入命令:`node .claude/skills/flow-comet/scripts/workflow-state.mjs reenter <target> --authorized-by <source> --reason <text> [--continue-round <n>]`——每次调用都需要用户显式授权,每 change 上限 3 轮(达上限后凭显式续轮授权 `--continue-round <n>`(n ≥ 已用轮次 + 1)可继续并计入下一轮);重入前自动落 state 备份快照(`.specs/<change-id>/.reentry-backups/`);成功打印 `REENTRY: archive → <target>(授权源 <source>;第 n/3 轮;备份 <file>)` 与 `REASON: <text>` 行(续轮审计行为 `第 n 轮(显式授权续轮,上限 3)`),与 Fix 回炉的 `FIX-BATCH` 行、正常多趟收尾的 `RETURN` 行三态可区分。归档移动已发生或 change 已 `completed` 时重入 BLOCKED,须走人工处置或新 change,不得静默跳过。重入只改工作归属,不写任何闭合标记,也不跳过目标节点入口 / 出口与源节点出口门禁;重复调用同一目标为空操作(输出 `REENTRY: 空操作——…`,不备份、不计数、不改写 state)。
|
|
120
122
|
|
|
@@ -7,6 +7,8 @@ description: "flow-kit INTEGRATION 阶段协议:集成验证 + UAT + 失败诊
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 verify 和 archive 节点提供 flow-kit 的集成验证和归档流程。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/7-integration.md` 并按其执行。
|
|
@@ -24,6 +24,8 @@ Responsibility: CHANGE 反问 + REQUIREMENT 需求分析。生成 CHANGE.md 和
|
|
|
24
24
|
|
|
25
25
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / templateSectionPatterns;「填得好不好」由 review 把关。
|
|
26
26
|
|
|
27
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
28
|
+
|
|
27
29
|
# Open
|
|
28
30
|
|
|
29
31
|
## Node Goal
|
|
@@ -23,6 +23,8 @@ Responsibility: 拆原子任务(XML 格式)+ 波次划分。生成 TASK.md
|
|
|
23
23
|
|
|
24
24
|
guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好不好」由 review 把关。
|
|
25
25
|
|
|
26
|
+
> **模板权威**:本节点产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
27
|
+
|
|
26
28
|
波次散文一致性:`## 波次划分` 中标记为并行([P])的任务必须与 XML 任务 `parallel="true"` 一致——新 change 不一致 BLOCKED(旧 change WARN 渐进)。
|
|
27
29
|
|
|
28
30
|
### 波次形态约束(依赖驱动多趟 · 规划期必守)
|
|
@@ -35,6 +37,14 @@ guard 校验见 workflow-guard.mjs NODE_TRANSITION_GATES / W1-B;「填得好
|
|
|
35
37
|
|
|
36
38
|
**理由**:引擎委托节点为多趟访问设计——按依赖分趟循环消化,序列形态自由度交给依赖声明表达。flow-kit 上游模板未载此约束,以本条为准。
|
|
37
39
|
|
|
40
|
+
### 规划期任务边界与 [P] 语义
|
|
41
|
+
|
|
42
|
+
- **① 同一文件 ⇒ 同一任务**:一个文件只能有一个任务 owner;必须拆分时,在波次划分中显式排序并写明拆分理由与依赖方向,不得把同一文件的两处改动拆成无依赖的两个任务。
|
|
43
|
+
- **② [P] 只给本波确有并发同伴的任务**:`parallel="true"` 仅适用于同波确有其他可并行同伴、且 write_files 互不重叠的任务;孤立任务一律串行——「互不冲突」只是必要条件,不等于应标 `[P]`。
|
|
44
|
+
- **③ [P] × direct 模式**:`[P]` 任务只在 `subagent-execute` 节点委托消化;direct 模式只放行**串行任务**的主代理直写,`parallel="true"` 任务在 direct 下仍必须委托——direct 不是并行任务的逃生口。共享工作区下以 `write_files` 互斥 + 提交时点(提交前 diff 边界)作为并行子代理的相互隔离纪律。
|
|
45
|
+
|
|
46
|
+
**上游语义显式覆盖**:flow-kit 上游(`flow-kit/prompts/3-task.md` 等 vendored 只读文件)的宽松语义——「无冲突即可标 [P]」「同层即同波并行」——以本节为准(显式覆盖;上游只读,不做修改)。
|
|
47
|
+
|
|
38
48
|
# Plan
|
|
39
49
|
|
|
40
50
|
## Node Goal
|
|
@@ -57,9 +67,9 @@ This node decomposes the technical design into atomic, executable tasks with cle
|
|
|
57
67
|
|
|
58
68
|
2. **Read DESIGN.md sections 0 and 0.5**: Understand the tech stack (for verify commands) and the architecture alignment (for file boundaries — touched modules, reuse targets, forbidden list).
|
|
59
69
|
|
|
60
|
-
3. **Decompose by file conflict (vertical slices)**: Split tasks by file conflict, NOT by horizontal layers. Each task should be a vertical slice (one feature through model/API/UI) not a horizontal layer (all models first, then all APIs). Target: 2-10 minutes per task in fresh context.
|
|
70
|
+
3. **Decompose by file conflict (vertical slices)**: Split tasks by file conflict, NOT by horizontal layers. Each task should be a vertical slice (one feature through model/API/UI) not a horizontal layer (all models first, then all APIs). Target: 2-10 minutes per task in fresh context. Do not split one file across tasks; if unavoidable, declare explicit order and reason.
|
|
61
71
|
|
|
62
|
-
4. **Mark parallel tasks with [P]**:
|
|
72
|
+
4. **Mark parallel tasks with [P]**: only tasks with a genuine concurrent companion in the same wave and non-overlapping write_files get `parallel="true"`; isolated tasks are serial; under direct mode `[P]` tasks are still delegated at subagent-execute.
|
|
63
73
|
|
|
64
74
|
5. **Declare depends_on**: Each task explicitly declares which tasks it depends on.
|
|
65
75
|
|
|
@@ -73,9 +83,10 @@ This node decomposes the technical design into atomic, executable tasks with cle
|
|
|
73
83
|
- `done`: One sentence completion criteria, corresponding to an AC sub-item.
|
|
74
84
|
|
|
75
85
|
7. **Wave division**: Group tasks by dependency graph:
|
|
76
|
-
- Same layer = same wave (parallel execution).
|
|
77
86
|
- Cross layer = sequential execution.
|
|
78
|
-
-
|
|
87
|
+
- Same-layer tasks may carry `parallel="true"` only when the wave genuinely contains a concurrent companion and their `write_files` do not overlap; an isolated task stays serial.
|
|
88
|
+
- 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.
|
|
89
|
+
- Output wave diagram: `Wave 1: T01[P], T02[P]` etc.; isolated tasks appear as serial steps.
|
|
79
90
|
|
|
80
91
|
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.
|
|
81
92
|
|
|
@@ -89,7 +100,7 @@ This node is truly done when:
|
|
|
89
100
|
- At least one `<task>` block exists; every task carries a `<verify>` field (the full seven-field shape — id/name/read_files/write_files/action/verify/done — is the execution discipline, review-checked; guard enforces the subset).
|
|
90
101
|
- Every `verify` field is an executable command (not a description).
|
|
91
102
|
- Every `write_files` is strictly within DESIGN.md touched + new modules range (not in forbidden list).
|
|
92
|
-
-
|
|
103
|
+
- 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).
|
|
93
104
|
- Wave division diagram is clear and has no circular dependencies.
|
|
94
105
|
- Task numbering is continuous.
|
|
95
106
|
|
|
@@ -98,7 +109,7 @@ This node is truly done when:
|
|
|
98
109
|
- **Agent thought**: "Split by layer first — models, then services, then endpoints." **Actual risk**: Horizontal layering creates artificial dependencies and blocks parallel execution. Always slice vertically by file conflict.
|
|
99
110
|
- **Agent thought**: "verify: tests should pass" is good enough. **Actual risk**: Vague verify commands cannot be executed. Must be specific: `pytest tests/test_x.py -v` not "tests should pass".
|
|
100
111
|
- **Agent thought**: "write_files can include any file the task might touch." **Actual risk**: Including DESIGN forbidden list modules in write_files bypasses R7.3 + R6.5 boundary enforcement. Strict control is mandatory.
|
|
101
|
-
- **Agent thought**: "
|
|
112
|
+
- **Agent thought**: "Same layer means these tasks can all be marked [P]." **Actual risk**: A same-layer task with no concurrent companion, or with overlapping `write_files`, would be delegated as parallel in violation of this node's rule. Mark `[P]` by companion and write boundaries, never by layer alone.
|
|
102
113
|
- **Agent thought**: "read_files and write_files are the same thing." **Actual risk**: read_files includes reuse targets and reference modules; write_files is strictly the modification boundary. They serve different purposes (B3 old-project guardrail).
|
|
103
114
|
|
|
104
115
|
## Entry Check
|
|
@@ -7,6 +7,8 @@ description: "flow-kit REQUIREMENT 阶段协议:AC(Given/When/Then)+ v1·v
|
|
|
7
7
|
|
|
8
8
|
本 Skill 为 flow-comet 的 open 节点提供 flow-kit 的 REQUIREMENT 需求分析。
|
|
9
9
|
|
|
10
|
+
> **模板权威**:本技能产出工件的段形唯一权威 = `flow-kit/templates/**`;`.specs/archive/**` 是历史证据、**不是模板来源**——不得以「上一轮就是这么写的」对齐段形。
|
|
11
|
+
|
|
10
12
|
## 加载
|
|
11
13
|
|
|
12
14
|
读取 `flow-kit/prompts/1-requirement.md` 并按其执行。关键步骤:
|