flow-comet 1.6.1 → 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.
- package/.flow-comet/skills/flow-comet/INSTALLED_VERSION +1 -1
- package/.flow-comet/skills/flow-comet/SKILL.md +94 -46
- package/.flow-comet/skills/flow-comet/reference/KNOWN-ISSUES-template.md +1 -1
- package/.flow-comet/skills/flow-comet/reference/commit-discipline.md +32 -0
- package/.flow-comet/skills/flow-comet/reference/dirty-worktree.md +1 -1
- package/.flow-comet/skills/flow-comet/{GUIDANCE.md → reference/entry-detail.md} +22 -30
- package/.flow-comet/skills/flow-comet/reference/fix-loop.md +57 -0
- package/.flow-comet/skills/flow-comet/reference/platform-facts.md +58 -0
- package/.flow-comet/skills/flow-comet/reference/replan.md +23 -0
- package/.flow-comet/skills/flow-comet/reference/workflow-protocol.json +1 -1
- package/.flow-comet/skills/flow-comet/scripts/comet-check.mjs +5 -4
- package/.flow-comet/skills/flow-comet/scripts/comet-hook-guard.mjs +260 -17
- package/.flow-comet/skills/flow-comet/scripts/context-init.mjs +129 -3
- package/.flow-comet/skills/flow-comet/scripts/context-scan.mjs +396 -0
- package/.flow-comet/skills/flow-comet/scripts/evolve.mjs +778 -0
- package/.flow-comet/skills/flow-comet/scripts/guard-self-test.mjs +5432 -194
- package/.flow-comet/skills/flow-comet/scripts/health.mjs +664 -0
- package/.flow-comet/skills/flow-comet/scripts/route-node.mjs +51 -4
- package/.flow-comet/skills/flow-comet/scripts/state-schema.mjs +68 -0
- package/.flow-comet/skills/flow-comet/scripts/system-test.mjs +1479 -11
- package/.flow-comet/skills/flow-comet/scripts/time-utils.mjs +133 -0
- package/.flow-comet/skills/flow-comet/scripts/workflow-guard.mjs +197 -5
- package/.flow-comet/skills/flow-comet/scripts/workflow-handoff.mjs +115 -6
- package/.flow-comet/skills/flow-comet/scripts/workflow-state.mjs +261 -29
- package/.flow-comet/skills/flow-comet-archive/SKILL.md +10 -19
- package/.flow-comet/skills/flow-comet-change/SKILL.md +10 -1
- package/.flow-comet/skills/flow-comet-compose/SKILL.md +1 -1
- package/.flow-comet/skills/flow-comet-design/SKILL.md +8 -6
- package/.flow-comet/skills/flow-comet-evolve/SKILL.md +46 -11
- package/.flow-comet/skills/flow-comet-execute/SKILL.md +58 -16
- package/.flow-comet/skills/flow-comet-health/SKILL.md +57 -16
- package/.flow-comet/skills/flow-comet-integration/SKILL.md +8 -5
- package/.flow-comet/skills/flow-comet-open/SKILL.md +5 -1
- package/.flow-comet/skills/flow-comet-plan/GUIDANCE.md +1 -1
- package/.flow-comet/skills/flow-comet-plan/SKILL.md +8 -8
- package/.flow-comet/skills/flow-comet-review/SKILL.md +9 -12
- package/.flow-comet/skills/flow-comet-subagent-execute/SKILL.md +59 -16
- package/.flow-comet/skills/flow-comet-task/SKILL.md +3 -2
- package/.flow-comet/skills/flow-comet-ui-design/SKILL.md +29 -4
- package/.flow-comet/skills/flow-comet-verify/SKILL.md +8 -17
- package/README.md +5 -5
- package/package.json +1 -1
- package/scripts/dsh-bridge.mjs +59 -26
- package/scripts/prepare-env.mjs +165 -1
- package/.flow-comet/skills/flow-comet/reference/TEST-MATRIX.md +0 -116
- package/.flow-comet/skills/flow-comet/reference/composition-report.md +0 -65
- package/.flow-comet/skills/flow-comet/reference/dsh-platform.md +0 -184
- package/.flow-comet/skills/flow-comet/reference/resolved-skills.json +0 -661
- package/.flow-comet/skills/flow-comet/reference/skill-review.md +0 -13
- package/.flow-comet/skills/flow-comet/reference/subagents/script-author.md +0 -7
- package/.flow-comet/skills/flow-comet/reference/worktree-notes.md +0 -70
|
@@ -6,8 +6,9 @@ import os from 'os';
|
|
|
6
6
|
import path from 'path';
|
|
7
7
|
import { fileURLToPath } from 'url';
|
|
8
8
|
import { resolveProtocol, readProtocolFile, validateProtocolSchema, NODE_PROTOCOL_FILES, SKILL_PROTOCOL_FILES, inspectWorkflowPathSegments } from './protocol-utils.mjs';
|
|
9
|
-
import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, looksLikeObjectLiteral, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, toPersistedProtocolPath } from './state-schema.mjs';
|
|
10
|
-
import {
|
|
9
|
+
import { validateStateFields, verifyFailuresFor, setVerifyFailuresFor, looksLikeObjectLiteral, writeJsonAtomic, RUNTIME_DIR, RUNTIME_STATE_FILE_NAME, toPersistedProtocolPath } from './state-schema.mjs';
|
|
10
|
+
import { isValidTimestamp, daysSince, isArchivedAfterTimestamp, hasSection9, nowTimestamp, parseTimestamp, EVOLVE_STALE_DAYS, EVOLVE_DUE_NEW_ARCHIVE_CHANGES } from './time-utils.mjs';
|
|
11
|
+
import { probeProject, classify, printDetection, validateContext, printGenerationGuide, extractContextStructure, skipInit } from './context-init.mjs';
|
|
11
12
|
import { taskOpeningAttrs, taskBlocks } from './task-parsing.mjs';
|
|
12
13
|
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
14
|
|
|
@@ -34,21 +35,10 @@ async function readJson(file) {
|
|
|
34
35
|
return JSON.parse((await fs.readFile(file, 'utf8')).replace(/^/, ''));
|
|
35
36
|
}
|
|
36
37
|
|
|
37
|
-
// JSON
|
|
38
|
-
//
|
|
39
|
-
//
|
|
40
|
-
//
|
|
41
|
-
async function writeJson(file, value) {
|
|
42
|
-
await fs.mkdir(path.dirname(file), { recursive: true });
|
|
43
|
-
const temporary = file + '.tmp';
|
|
44
|
-
try {
|
|
45
|
-
await fs.writeFile(temporary, JSON.stringify(value, null, 2) + '\n', 'utf8');
|
|
46
|
-
await fs.rename(temporary, file);
|
|
47
|
-
} catch (error) {
|
|
48
|
-
try { await fs.rm(temporary, { force: true }); } catch { /* 清理失败不掩盖原始写错误 */ }
|
|
49
|
-
throw error;
|
|
50
|
-
}
|
|
51
|
-
}
|
|
38
|
+
// JSON 写盘统一走状态层单一来源的原子写(state-schema.mjs 的 writeJsonAtomic → writeFileAtomic):
|
|
39
|
+
// 先写同目录临时文件再 rename 覆盖目标——目标要么旧内容、要么新内容,不会出现被截断的半写状态;
|
|
40
|
+
// 写失败(磁盘满 / 权限 / 目标被占用)清理临时文件后抛出,调用方按 fail-closed 处理。mkdir recursive
|
|
41
|
+
// 由该实现承担(.skill-loads/ 等标记目录不存在时创建);状态下发是单写者形态(机器字段只由脚本通道写)。
|
|
52
42
|
|
|
53
43
|
async function fileExists(file) {
|
|
54
44
|
try { await fs.access(file); return true; } catch { return false; }
|
|
@@ -424,6 +414,58 @@ function printBranchLine(activeChange, branchPrefix = 'change/') {
|
|
|
424
414
|
}
|
|
425
415
|
}
|
|
426
416
|
|
|
417
|
+
// ---------- evolve 到期提示(AC-18:达阈值才输出,未达阈值零噪音) ----------
|
|
418
|
+
|
|
419
|
+
// 该时刻之后归档、且 DESIGN.md 带 §9 的 change 数。归档时刻取目录名日期前缀(flow-kit 约定
|
|
420
|
+
// archive/<YYYY-MM-DD>-<change-id>,该标签随提交固化、跨 clone 稳定);「归档于何时」与「§9 是否
|
|
421
|
+
// 在场」两个判定都走 time-utils 单一来源——不在本脚本内联第二份表达式(L-067)。
|
|
422
|
+
// 读取失败 / 非目录 / 无 DESIGN.md / 无 §9 一律不计入(不误报)。
|
|
423
|
+
async function countSection9ArchivesSince(timestamp) {
|
|
424
|
+
const archiveRoot = path.join(specsRoot, 'archive');
|
|
425
|
+
let entries = [];
|
|
426
|
+
try {
|
|
427
|
+
entries = await fs.readdir(archiveRoot, { withFileTypes: true });
|
|
428
|
+
} catch {
|
|
429
|
+
return 0;
|
|
430
|
+
}
|
|
431
|
+
let count = 0;
|
|
432
|
+
for (const entry of entries) {
|
|
433
|
+
if (!entry.isDirectory() || !isArchivedAfterTimestamp(entry.name, timestamp)) continue;
|
|
434
|
+
let design = '';
|
|
435
|
+
try {
|
|
436
|
+
design = await fs.readFile(path.join(archiveRoot, entry.name, 'DESIGN.md'), 'utf8');
|
|
437
|
+
} catch {
|
|
438
|
+
continue;
|
|
439
|
+
}
|
|
440
|
+
if (hasSection9(design)) count += 1;
|
|
441
|
+
}
|
|
442
|
+
return count;
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
// 到期提示:`last_evolve_at` 距今 > 60 天,或其后新增 ≥ 5 个带 §9 的归档 change → 输出一行;
|
|
446
|
+
// 否则**不打印任何行**(AC-18 反例锚:未达阈值零噪音)。旧 state 无该字段 = 从未跑过 evolve →
|
|
447
|
+
// 静默(本批不强制未接入 evolve 的项目补字段:无基线可判时不制造噪音)。提示行内不含花括号——
|
|
448
|
+
// status 的 JSON 块按「首个 { 到末个 }」截取(既有消费方 parseStatusJson 同形)。
|
|
449
|
+
async function printEvolveDueHint(state) {
|
|
450
|
+
const lastEvolveAt = state && typeof state.last_evolve_at === 'string' ? state.last_evolve_at : '';
|
|
451
|
+
if (!isValidTimestamp(lastEvolveAt)) return;
|
|
452
|
+
const elapsedDays = daysSince(lastEvolveAt);
|
|
453
|
+
if (Number.isNaN(elapsedDays)) return;
|
|
454
|
+
const staleByAge = elapsedDays > EVOLVE_STALE_DAYS;
|
|
455
|
+
const newArchives = await countSection9ArchivesSince(lastEvolveAt);
|
|
456
|
+
const staleByCount = newArchives >= EVOLVE_DUE_NEW_ARCHIVE_CHANGES;
|
|
457
|
+
if (!staleByAge && !staleByCount) return;
|
|
458
|
+
const reasons = [];
|
|
459
|
+
if (staleByAge) {
|
|
460
|
+
reasons.push('距今 ' + Math.floor(elapsedDays) + ' 天,超阈值 ' + EVOLVE_STALE_DAYS + ' 天');
|
|
461
|
+
}
|
|
462
|
+
if (staleByCount) {
|
|
463
|
+
reasons.push('其后新增 ' + newArchives + ' 个带 §9 的归档 change,达阈值 ' + EVOLVE_DUE_NEW_ARCHIVE_CHANGES + ' 个');
|
|
464
|
+
}
|
|
465
|
+
console.log('EVOLVE-DUE: 上次架构沉淀 ' + lastEvolveAt + '(' + reasons.join(';')
|
|
466
|
+
+ ')——建议显式调用 evolve(/flow-comet-evolve)同步 CONTEXT.md');
|
|
467
|
+
}
|
|
468
|
+
|
|
427
469
|
// C6: writeState 写入前校验已知字段类型(fail-closed:非法 → BLOCKED 拒绝写入,不修复不猜测)
|
|
428
470
|
// 未知字段允许(前向兼容);缺字段允许(readState 默认补);只校验存在字段的类型。
|
|
429
471
|
// 内置节点常量: 校验表已迁移到 state-schema.mjs(唯一来源),行为与迁移前的内联表完全一致(对第一个非法字段输出后退出)
|
|
@@ -433,7 +475,7 @@ async function writeState(state) {
|
|
|
433
475
|
console.error('BLOCKED: state 字段类型非法: ' + bad[0]);
|
|
434
476
|
process.exit(1);
|
|
435
477
|
}
|
|
436
|
-
await
|
|
478
|
+
await writeJsonAtomic(statePath, state);
|
|
437
479
|
}
|
|
438
480
|
|
|
439
481
|
// .specs/ 下必须存在名字「逐字相等」的目录条目(change 名唯一性判据)。大小写不敏感文件系统
|
|
@@ -702,6 +744,138 @@ async function runBridgeCheck() {
|
|
|
702
744
|
}
|
|
703
745
|
}
|
|
704
746
|
|
|
747
|
+
// ---------- intel-scan 双落点一致性(init 的检测侧) ----------
|
|
748
|
+
// `last_intel_scan` 是**双落点**字段:引擎 state(机器真相、schema 校验)与 `.specs/CONTEXT.md` 的
|
|
749
|
+
// `## intel-scan 元数据` 段(项目可见)。段行的改写——含改写前备份与结构校验——只有 context-scan
|
|
750
|
+
// 一条通道一份实现;init 侧因此**不写段**(在第二处复制段行改写判据必然与前者分叉),只承担两条:
|
|
751
|
+
// ① 形态对齐:state 侧取值一律经 time-utils 的 nowTimestamp()(本地时间 + 显式偏移),与
|
|
752
|
+
// context-scan 写入的形态同源;历史 `Z` 形态继续可解析(不迁移)。
|
|
753
|
+
// ② 漂移可见:写完后与段侧取值比对(口径 = **取值词元**,与段行写通道替换的那个词元同口径)——
|
|
754
|
+
// 不一致(含**同一时刻的两种形态**、段内取值不可解析)即输出可见提示并点名收敛命令;一致则
|
|
755
|
+
// 静默(不误报);带行尾说明的段行不构成差异(说明由写通道原样保留,不是取值的一部分)。
|
|
756
|
+
const INTEL_SECTION_NAME = 'intel-scan 元数据';
|
|
757
|
+
const INTEL_FIELD_NAME = 'last_intel_scan';
|
|
758
|
+
|
|
759
|
+
// 段侧取值词元的归一:`extractContextStructure` 返回的是字段行冒号后的**整行剩余文本**
|
|
760
|
+
// (取值词元 + 可选的 markdown 引号 + 可选的行尾说明),而段行的写通道 `context-scan` 按
|
|
761
|
+
// `INTEL_FIELD_LINE = (…)(\S+)([\s\S]*)` 只替换**首个取值词元**、行尾说明原样保留(首次接入的
|
|
762
|
+
// CONTEXT 生成物即「词元 + 说明」形态)。读侧因此必须取同一口径的词元再比对:按整行剩余文本比对时,
|
|
763
|
+
// 带说明的段行与 state 永不相等 ⇒ 同刻同形态也恒亮「不一致」、类别退化成「段内取值不是合法时间戳」,
|
|
764
|
+
// 提示点名的 `context-scan` 收敛承诺不可达(提示噪声化 = 没人看的行)。
|
|
765
|
+
// 空白切分与写侧正则的 `\S+` 同一字符类语义;行结构(段名 / 字段行形态)仍唯一来自
|
|
766
|
+
// extractContextStructure——本函数只做「词元 + 引号」归一,不解析段行(L-067 单一来源)。
|
|
767
|
+
function normalizeIntelFieldValue(value) {
|
|
768
|
+
return String(value).trim().split(/\s+/)[0].replace(/^`+/, '').replace(/`+$/, '').trim();
|
|
769
|
+
}
|
|
770
|
+
|
|
771
|
+
// 漂移判定(纯函数):两侧取值不一致时返回差异类别,一致(或任一侧缺席)返回 null(不误报)。
|
|
772
|
+
function intelScanDriftKind(stateValue, sectionValue) {
|
|
773
|
+
if (typeof stateValue !== 'string' || typeof sectionValue !== 'string') return null;
|
|
774
|
+
if (stateValue === sectionValue) return null;
|
|
775
|
+
const atSection = parseTimestamp(sectionValue);
|
|
776
|
+
if (Number.isNaN(atSection)) return '段内取值不是合法时间戳';
|
|
777
|
+
const atState = parseTimestamp(stateValue);
|
|
778
|
+
if (!Number.isNaN(atState) && atState === atSection) return '同刻不同形态';
|
|
779
|
+
return '刻与形态均不一致';
|
|
780
|
+
}
|
|
781
|
+
|
|
782
|
+
// 双落点比对(读盘 + 输出):段侧文档缺席 / 段或缺字段不在场 = 无可比对面 → 静默(不无中生有);
|
|
783
|
+
// 检出漂移 → 可见提示(stdout,与 INIT-* 提示同族且不阻断 init),点名两侧取值与收敛命令。
|
|
784
|
+
async function reportIntelScanDrift(contextFile, stateValue) {
|
|
785
|
+
let contextText;
|
|
786
|
+
try {
|
|
787
|
+
contextText = await fs.readFile(contextFile, 'utf8');
|
|
788
|
+
} catch {
|
|
789
|
+
return; // 段侧文档不可读 = 无可比对面
|
|
790
|
+
}
|
|
791
|
+
const fields = extractContextStructure(contextText).metadata[INTEL_SECTION_NAME];
|
|
792
|
+
if (!fields || !fields[INTEL_FIELD_NAME]) return; // 段或缺字段不在场 = 无可比对面
|
|
793
|
+
const landed = normalizeIntelFieldValue(fields[INTEL_FIELD_NAME].value);
|
|
794
|
+
const kind = intelScanDriftKind(stateValue, landed);
|
|
795
|
+
if (kind === null) return;
|
|
796
|
+
console.log('INIT-NOTICE: ' + INTEL_FIELD_NAME + ' 双落点不一致(' + kind + ')——引擎 state = '
|
|
797
|
+
+ stateValue + ';`.specs/CONTEXT.md` 的 `## ' + INTEL_SECTION_NAME + '` 段 = ' + landed
|
|
798
|
+
+ '。本命令只写 state(该段行的写通道是 context-scan);运行 context-scan 即把两处收敛为'
|
|
799
|
+
+ '同刻同形态(冲突时以 state 为准)。');
|
|
800
|
+
}
|
|
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
|
+
|
|
705
879
|
async function main() {
|
|
706
880
|
// 协议解析: 协议加载 = resolveProtocol 解析路径 + 受保护读取 + fail-closed schema 校验
|
|
707
881
|
// (读失败/校验失败直接 throw,沿用现有错误处理风格)
|
|
@@ -827,12 +1001,23 @@ async function main() {
|
|
|
827
1001
|
// 项目级上下文字段跨 change 保留(迁移旧 state;--init-context 刷新扫描时间;--init-skip 记拒绝)
|
|
828
1002
|
...(prevState?.ai_context_doc !== undefined ? { ai_context_doc: prevState.ai_context_doc } : {}),
|
|
829
1003
|
...(initSkip ? { ai_context_doc: 'none' } : {}),
|
|
830
|
-
// last_intel_scan 仅在校验通过后写入(agent 生成 → 脚本校验 7 段 →
|
|
1004
|
+
// last_intel_scan 仅在校验通过后写入(agent 生成 → 脚本校验 7 段 → 记录扫描时间);形态一律经
|
|
1005
|
+
// time-utils 的 nowTimestamp()(本地时间 + 显式偏移)——与 context-scan 的落点形态同源,不在本
|
|
1006
|
+
// 脚本内联第二份格式化。段侧**不在本命令的写面内**(该段行的改写与备份只有 context-scan 一份
|
|
1007
|
+
// 实现):两处取值不一致由 reportIntelScanDrift 检出并给出可见提示,不静默漂移。
|
|
831
1008
|
...(ctxValid === true
|
|
832
|
-
? { last_intel_scan:
|
|
833
|
-
: (prevState?.last_intel_scan !== undefined ? { last_intel_scan: prevState.last_intel_scan } : {}))
|
|
1009
|
+
? { last_intel_scan: nowTimestamp() }
|
|
1010
|
+
: (prevState?.last_intel_scan !== undefined ? { last_intel_scan: prevState.last_intel_scan } : {})),
|
|
1011
|
+
// last_evolve_at 同为**项目级**字段(evolve 的跨 change 基线,写通道 = config set)——init 换
|
|
1012
|
+
// change 必须原样保留:丢了它,增量窗口静默退化为全量扫描、到期提示从此不再触发(保留判据与
|
|
1013
|
+
// 上一行同形:字段缺席 = 从未跑过 evolve,不得凭空制造该字段——state-schema 不接受 null)
|
|
1014
|
+
...(prevState?.last_evolve_at !== undefined ? { last_evolve_at: prevState.last_evolve_at } : {})
|
|
834
1015
|
};
|
|
835
1016
|
await writeState(state);
|
|
1017
|
+
// 扫描时刻的双落点一致性(state ↔ `.specs/CONTEXT.md` 的 `## intel-scan 元数据` 段):本命令写
|
|
1018
|
+
// state 后即比对段侧取值——不一致(含同一时刻的两种形态)输出可见提示并点名收敛命令;一致或
|
|
1019
|
+
// 无可比对面则静默(不误报)。段行的写通道只有 context-scan,故此处是检测、不是第二份改写实现。
|
|
1020
|
+
await reportIntelScanDrift(path.join(specsRoot, 'CONTEXT.md'), state.last_intel_scan);
|
|
836
1021
|
// init 创建 .specs/<id>/ 目录——文件即真相从 init 起成立,findActiveChange 立即可识别
|
|
837
1022
|
//(此前 init 后 next/status 报 No active change,与 SKILL 启动协议 init → next 矛盾)
|
|
838
1023
|
const specsChangeDir = path.join(specsRoot, changeName);
|
|
@@ -874,6 +1059,8 @@ async function main() {
|
|
|
874
1059
|
const changeName = await findActiveChange();
|
|
875
1060
|
if (!changeName) {
|
|
876
1061
|
console.log(JSON.stringify({ status: 'no-change', message: 'No active change in .specs/' }, null, 2));
|
|
1062
|
+
// 到期提示属**项目级**元数据(与是否有 active change 无关):无活跃 change 时同样按阈值输出
|
|
1063
|
+
await printEvolveDueHint(await readState());
|
|
877
1064
|
return;
|
|
878
1065
|
}
|
|
879
1066
|
const state = await readState();
|
|
@@ -921,6 +1108,7 @@ async function main() {
|
|
|
921
1108
|
newChange: state.newChange === true
|
|
922
1109
|
}, null, 2));
|
|
923
1110
|
printBranchLine(changeName, state.branchPrefix ?? 'change/');
|
|
1111
|
+
await printEvolveDueHint(state);
|
|
924
1112
|
return;
|
|
925
1113
|
}
|
|
926
1114
|
|
|
@@ -1161,7 +1349,7 @@ async function main() {
|
|
|
1161
1349
|
if (promptArg !== null && !protocolUnderFlowKitPrompts(promptArg)) {
|
|
1162
1350
|
throw new Error('skill-load --prompt 路径必须位于 flow-kit/prompts/ 下(flow-kit 为 vendored 上游,协议提示只读引用): ' + promptArg);
|
|
1163
1351
|
}
|
|
1164
|
-
// 声明标记写入:.skill-loads/ 目录不存在时创建(
|
|
1352
|
+
// 声明标记写入:.skill-loads/ 目录不存在时创建(writeJsonAtomic 自带 mkdir recursive);
|
|
1165
1353
|
// 同 node-skill 重复调用覆盖(记录最新声明)
|
|
1166
1354
|
const changeName = await findActiveChange();
|
|
1167
1355
|
if (!changeName) {
|
|
@@ -1176,7 +1364,7 @@ async function main() {
|
|
|
1176
1364
|
const marker = { node: nodeId, skill: skillName, protocol: promptArg === null ? null : path.basename(promptArg), at: new Date().toISOString() };
|
|
1177
1365
|
// specsRoot 已含 .specs/,相对路径为 <change-id>/.skill-loads/<node>-<skill>.json
|
|
1178
1366
|
const markerRel = path.posix.join(changeName, '.skill-loads', nodeId + '-' + skillName + '.json');
|
|
1179
|
-
await
|
|
1367
|
+
await writeJsonAtomic(path.join(specsRoot, markerRel), marker);
|
|
1180
1368
|
console.log('SKILL-LOAD: ' + nodeId + ' ' + skillName + ' → .skill-loads/' + nodeId + '-' + skillName + '.json');
|
|
1181
1369
|
return;
|
|
1182
1370
|
}
|
|
@@ -1278,7 +1466,7 @@ async function main() {
|
|
|
1278
1466
|
// M5 标记目录解析:活动路径优先;change 已归档(活动目录不存在但归档目录存在)
|
|
1279
1467
|
// 时写归档路径——防重建已归档的活动目录(归档移动语义;与 findSkillLoadsDir 双路径一致)。
|
|
1280
1468
|
// 跳过条件:活动与归档均无 .skill-loads **且活动 change 目录已不存在**(归档移动后)
|
|
1281
|
-
// ——此时
|
|
1469
|
+
// ——此时 writeJsonAtomic 的 mkdir recursive 会把已归档的活动目录残留回来(修复前实测缺陷);
|
|
1282
1470
|
// 活动 change 目录仍存在(正常流程)时创建 .skill-loads 子目录是 M5 的正常职责,不跳过
|
|
1283
1471
|
const activeLoadsDir = path.join(specsRoot, markerChange, '.skill-loads');
|
|
1284
1472
|
let targetLoadsDir = activeLoadsDir;
|
|
@@ -1303,7 +1491,7 @@ async function main() {
|
|
|
1303
1491
|
// 1-requirement.md 而非节点首文件 0-change.md——修复前所有 skill 都写首文件,
|
|
1304
1492
|
// 标记的协议归属语义错误;exit 校验只查归属集合故能通过,但标记不可信)
|
|
1305
1493
|
const skillProtoFiles = SKILL_PROTOCOL_FILES[binding.skill] ?? [];
|
|
1306
|
-
await
|
|
1494
|
+
await writeJsonAtomic(markerFile, {
|
|
1307
1495
|
node: nodeId,
|
|
1308
1496
|
skill: binding.skill,
|
|
1309
1497
|
protocol: skillProtoFiles.length > 0 ? skillProtoFiles[0] : null,
|
|
@@ -1328,7 +1516,8 @@ async function main() {
|
|
|
1328
1516
|
}
|
|
1329
1517
|
|
|
1330
1518
|
if (command === 'config') {
|
|
1331
|
-
// E1: 配置命令——config set <key> <value>;branchMode 只读(init 自动判定),enablePrReview
|
|
1519
|
+
// E1: 配置命令——config set <key> <value>;branchMode 只读(init 自动判定),enablePrReview 手动
|
|
1520
|
+
// 开关,last_evolve_at 为 evolve 元数据时刻(形态校验 fail-closed,写通道唯一)
|
|
1332
1521
|
const sub = process.argv[3];
|
|
1333
1522
|
const key = process.argv[4];
|
|
1334
1523
|
const value = process.argv[5];
|
|
@@ -1349,7 +1538,21 @@ async function main() {
|
|
|
1349
1538
|
console.log('CONFIG: enablePrReview = ' + state.enablePrReview);
|
|
1350
1539
|
return;
|
|
1351
1540
|
}
|
|
1352
|
-
|
|
1541
|
+
// evolve 元数据时间戳(脚本不直写 state,项目级字段一律经本通道)。形态非法 → BLOCK
|
|
1542
|
+
// 且**零改写**(校验先于读 state 与写盘;writeState 侧的字段校验表是第二道闸,同一判据)。
|
|
1543
|
+
if (key === 'last_evolve_at') {
|
|
1544
|
+
if (!isValidTimestamp(value)) {
|
|
1545
|
+
console.error('BLOCKED: config set 值非法(last_evolve_at 必须为本地时间 + 显式偏移形态 '
|
|
1546
|
+
+ 'YYYY-MM-DDTHH:mm:ss±HH:mm,兼容历史 Z 形态): ' + value);
|
|
1547
|
+
process.exit(1);
|
|
1548
|
+
}
|
|
1549
|
+
const state = await readState();
|
|
1550
|
+
state.last_evolve_at = value;
|
|
1551
|
+
await writeState(state);
|
|
1552
|
+
console.log('CONFIG: last_evolve_at = ' + state.last_evolve_at);
|
|
1553
|
+
return;
|
|
1554
|
+
}
|
|
1555
|
+
console.error('BLOCKED: 未知配置键: ' + key + '(支持: enablePrReview, last_evolve_at;branchMode 由 init 自动判定)');
|
|
1353
1556
|
process.exit(1);
|
|
1354
1557
|
}
|
|
1355
1558
|
|
|
@@ -1858,7 +2061,9 @@ async function main() {
|
|
|
1858
2061
|
}
|
|
1859
2062
|
if (replanTask7Broken.length > 0) {
|
|
1860
2063
|
if (replanTask7NewFormat && state.newChange === true) {
|
|
1861
|
-
|
|
2064
|
+
// 文案的集合字符串**从判据常量派生**(不得在此再写一遍字面集合——第二处同口径表达会在
|
|
2065
|
+
// 判据演进时静默落后于实现;构造方式不改变渲染结果)。
|
|
2066
|
+
console.error('BLOCKED: TASK.md 任务缺 7 字段(' + replanTask7Required.join('/') + '): '
|
|
1862
2067
|
+ replanTask7Broken.join('; ') + ';恢复: 对照 flow-kit/templates/TASK.md 补齐每个 <task> 的缺字段后重试;replan 不做校验豁免');
|
|
1863
2068
|
process.exit(1);
|
|
1864
2069
|
}
|
|
@@ -1997,7 +2202,34 @@ async function main() {
|
|
|
1997
2202
|
return;
|
|
1998
2203
|
}
|
|
1999
2204
|
|
|
2000
|
-
|
|
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');
|
|
2001
2233
|
}
|
|
2002
2234
|
|
|
2003
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**:
|
|
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
|
-
-
|
|
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**:
|
|
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
|
|
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
|
-
|
|
78
|
+
**何时读完整规格**:要核对完整边界——命令全形与三态审计行(`REENTRY:` / `FIX-BATCH: 归位` / `RETURN:`)的区分、备份快照与 sha256 指纹、续轮授权形态与轮次记账、重复调用同一目标的空操作语义、「已移动 / 已合并」的处置面——读 `../flow-comet/reference/fix-loop.md`(**当你归档后发现缺陷、要把工作归属受控归位回既有生命周期时读它**)。
|
|
88
79
|
|
|
89
80
|
### 归档提交(R4.1 交付闭环)
|
|
90
81
|
|
|
@@ -15,7 +15,7 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
|
|
|
15
15
|
|
|
16
16
|
1. **自动生成 change-id**(kebab-case,2~4 词,检查 `.specs/<id>/` 不冲突)
|
|
17
17
|
2. **架构级变更检测**(步骤 0.4):命中 5 类信号时暂停,引导先跑 A-architect
|
|
18
|
-
3. **前端项目识别**(步骤 0.5
|
|
18
|
+
3. **前端项目识别**(步骤 0.5):关键词判定是否为前端项目;判定结果按「视觉调性段的标记约定」落盘(非前端以**结构形态**在该段标注「不适用」)
|
|
19
19
|
4. **视觉调性预选**(步骤 0.6,仅前端):9 张调性卡片 + 推荐
|
|
20
20
|
5. **结构化反问**(步骤 1):每轮最多 3 个问题
|
|
21
21
|
6. **影响面判定 + 范围排除**
|
|
@@ -26,6 +26,15 @@ description: "flow-kit CHANGE 阶段协议:反问澄清、change-id 自动生
|
|
|
26
26
|
|
|
27
27
|
- `.specs/<change-id>/CHANGE.md`
|
|
28
28
|
|
|
29
|
+
## 视觉调性段的标记约定(前端 / 非前端)
|
|
30
|
+
|
|
31
|
+
`CHANGE.md` 的 `## 视觉调性` 段(段名取自 `flow-kit/templates/CHANGE.md`)不只承载调性选择,还是下游 design 出口判定「是否前端」的**结构级判据**的输入面——它的在场状态必须与项目实情一致:
|
|
32
|
+
|
|
33
|
+
- **判据与强制等级(唯一权威)**:判据全文与 `guarded` 绑定、`required-skill:design.flow-comet-ui-design` 声明要求、非前端 `UI-DESIGN: skipped(非前端)` 的出口口径都在 `flow-comet-ui-design` 册的「触发与跳过」段——本节不复述,只描述怎么填段。
|
|
34
|
+
- **前端项目**:按步骤 0.6 的预选结果填段(选定 / 理由 / 参考产品 / 明确排除),不要以结构形态标注「不适用」。
|
|
35
|
+
- **非前端项目**:保留该段并以**结构形态**标注「不适用」(可附一句理由,例如「CLI 工具,无用户可见界面」)。段缺席同样按非前端处理,但缺席不留可读证据,故约定**显式标注**。
|
|
36
|
+
- **改判走本阶段**:change 进行中要改前端 / 非前端判定,回到这里改这一个段,不在 design / execute / verify 里就地绕开判据——改段即改变了 design 出口的判据输入。
|
|
37
|
+
|
|
29
38
|
## 状态推进
|
|
30
39
|
|
|
31
40
|
CHANGE.md 生成后,由 flow-comet 状态机(workflow-state/guard)推进节点。不需要手动维护 STATE.md。
|
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
|
@@ -107,11 +107,13 @@ The design node reads CHANGE.md and REQUIREMENT.md, then produces DESIGN.md thro
|
|
|
107
107
|
|
|
108
108
|
| Skill | Enforcement | Reason |
|
|
109
109
|
|-------|-------------|--------|
|
|
110
|
-
| `flow-comet-ui-design` |
|
|
110
|
+
| `flow-comet-ui-design` | Guarded(仅前端项目触发) | Produces UI-DESIGN.md with design tokens, anti-AI-slop check, visual north star——前端 change 须先 `skill-load` 建标记并在 record 载荷带 `required-skill:design.flow-comet-ui-design`(出口不再自动补写);非前端项目不加载不声明;旧 change 渐进 WARN |
|
|
111
111
|
|
|
112
112
|
**加载声明(阶段层 · 双步硬规则)**:本节点技能已由入口路由经 Skill 工具加载(你正在阅读的就是它);本节点 Required Skill Calls 的加载与声明同样不可跳过:
|
|
113
113
|
|
|
114
|
-
1. 本节点的同名条目已随路由加载——同名 required 条目(`flow-comet-design`)无需重复加载,仅需运行下方声明命令(只读取 SKILL.md 文件不叫加载,**不得跳过**真正的 Skill 工具注入步骤)。`flow-comet-ui-design` 为
|
|
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
|
+
|
|
116
|
+
> **前端判据(结构级 · 唯一权威 → `flow-comet-ui-design` 册的「触发与跳过」段)**:判据全文与 `guarded` 绑定的判级口径都在该册——本节不复述,判定与出口行为一律以该册为准。
|
|
115
117
|
2. 加载完成后**立即**运行声明命令(节点退出与证据记录会核对声明标记;声明如实记录加载动作,不等于产出证明):
|
|
116
118
|
|
|
117
119
|
```bash
|
|
@@ -158,6 +160,6 @@ If the script prints `SKILL: flow-comet-plan`, load that Skill next.
|
|
|
158
160
|
|
|
159
161
|
1. Re-run entry check to confirm workflow state.
|
|
160
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.
|
|
161
|
-
3. If the design doc exists but incomplete, resume from the first missing section (check 0, 0.5, 1-
|
|
163
|
+
3. If the design doc exists but incomplete, resume from the first missing section (check 0, 0.5, 1-6, 9).
|
|
162
164
|
4. If frontend project: check `.specs/<change-id>/UI-DESIGN.md` existence.
|
|
163
165
|
5. Do not repeat confirmed decisions. Resume from the first incomplete artifact.
|