agentic-flow-kit 1.8.2 → 2.0.0

package/src/validate.mjs

@@ -1,77 +0,0 @@
-// flow-kit validate：只读校验装户盘面（2026-10-10 validate-entry；对照 OpenSpec validate 形态：
-// 只读 + 0/1 退出码 + --strict/--json）。
-// 语义：用**包内置** check-loop 引擎（templates/_agents/scripts/check-loop.mjs 的 runCheckLoop，
-// isMain 主守卫保证 import 零副作用）对目标仓 workflow/ 闭环跑全部 20 项检查——不执行装户侧
-// .agents/scripts/*（供应链面：判定引擎随包版本走、目标侧零代码执行；doctor 走另一极：scriptGuard
-// 先验后跑装户侧脚本，两命令互补不重复）。root 经 runCheckLoop({root}) 传入，spawnGit 以 cwd:ROOT
-// 落在目标仓——tracked 过滤按目标仓 HEAD 算，与 git 钩子看到的提交面一致。
-// 只读范围：check-loop 自身仅有的两处落盘都在 .agents/cache/ 运行时缓存（gate-stats 需 --gate-stats
-// 才触发、added-dates 缓存 best-effort），且该目录已 gitignore——本命令不改任何文档与台账。
-// 判定流水（2026-10-13 judgment-ledger 回灌 B4）：check-loop 真实运行会追加 .agents/judgments.jsonl，
-// validate 是探针而非门裁决点（init 装后自检同路径）——挂 CHECK_LOOP_NO_LEDGER 守卫保持只读契约。
-// 不暴露 --rev：runCheckLoop 中 rev 与 root 互斥（提交时点判定属钩子链职责，validate 只看盘面现状）。
-// 输出契约：check-loop 的 HARD-BLOCK/WARN 两段式原样走 stderr（稳定输出契约，消费者 .githooks/pre-push）；
-// stdout 只承载本命令的汇总行 / --json——机器消费者按 stdout 解析，人按 stderr 读明细。
-// 退出码：blocker → 1；--strict 下 advisory warning 同样 → 1（判据单源 validateExit，纯函数可单测）。
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-
-// 退出码判定单源（独立 export 供单元测试）：引擎 exitCode 非 0 → 1；--strict 时 warning 也红；
-// 结果缺失（引擎调用异常路径）fail-closed → 1。
-export function validateExit(result, strict) {
-  if (!result || result.exitCode !== 0) return 1;
-  if (strict && (result.warnings || []).length > 0) return 1;
-  return 0;
-}
-
-export async function validate(args, pkgRoot) {
-  let target = process.cwd();
-  let strict = false;
-  let json = false;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i]);
-    else if (args[i] === '--strict') strict = true;
-    else if (args[i] === '--json') json = true;
-    else {
-      console.error(`validate: 未知参数 ${args[i]}——用法 flow-kit validate [--strict] [--json] [--dir <目录>]`);
-      process.exit(1);
-    }
-  }
-
-  // 装户盘面前置：枚举单源（workflow-enums.txt 等）都在 .agents/ 下，无装副本则引擎无从判定——
-  // 先给指引再红，不产出「20 项全断档」的噪音墙
-  if (!fs.existsSync(path.join(target, '.agents'))) {
-    const msg = `缺 .agents/——validate 校验 flow-kit 装户盘面，先跑 npx agentic-flow-kit init`;
-    if (json) console.log(JSON.stringify({ target, strict, checkLoopExitCode: null, exitCode: 1, blockers: [msg], warnings: [] }, null, 2));
-    else console.error(`❌ validate: ${target} ${msg}`);
-    process.exit(1);
-  }
-
-  // 动态 import 包内置引擎：pkgRoot = npx 缓存 / 全局安装 / 仓内直跑三种形态下都指向包源模板
-  const engineUrl = pathToFileURL(path.join(pkgRoot, 'templates', '_agents', 'scripts', 'check-loop.mjs')).href;
-  const { runCheckLoop } = await import(engineUrl);
-  process.env.CHECK_LOOP_NO_LEDGER = '1'; // 探针不落判定流水（守卫开关见 judgment-ledger.mjs recordRun）
-  // mode:'all' 显式全量（2026-10-13 分道后裸跑=默认硬门）——validate 自述「全部 20 项检查」且 --strict
-  // 判红的是全量 warning 面，随分道保留原语义须显式声明，勿依赖缺省。
-  const result = runCheckLoop({ root: target, mode: 'all' });
-  const code = validateExit(result, strict);
-
-  if (json) {
-    console.log(JSON.stringify({
-      target,
-      strict,
-      checkLoopExitCode: result.exitCode,
-      exitCode: code,
-      blockers: result.blockers,
-      warnings: result.warnings,
-    }, null, 2));
-  } else {
-    const n = (result.blockers || []).length;
-    const w = (result.warnings || []).length;
-    if (code === 0) console.log(`✅ flow-kit validate 通过——blocker 0 / warning ${w}${w ? '（advisory 不阻断；--strict 可把 warning 判红）' : ''}`);
-    else if (result.exitCode !== 0) console.log(`❌ flow-kit validate 未通过——blocker ${n} / warning ${w}（明细见上方 HARD-BLOCK / WARN 输出）`);
-    else console.log(`❌ flow-kit validate（--strict）未通过——warning ${w} 条判红（默认退出码 0，advisory 不阻断）`);
-  }
-  process.exit(code);
-}

package/src/validate.test.mjs

@@ -1,95 +0,0 @@
-// validate.test.mjs — flow-kit validate 断言（2026-10-10 validate-entry）。
-// 两层：validateExit 纯函数直测（退出码判据单源）+ 端到端 spawn 真 CLI（bin/flow-kit.mjs validate，
-// --json 断言 stdout 可解析、退出码契约、缺 .agents/ 指引、未知参数用法错）。
-// fixture 沿 check-loop.test.mjs 同款：临时根（workflow 四目录 + .agents/ + 枚举单源内联 8 键），
-// 自包含、不依赖真实 git 与 workflow 文档。
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { validateExit } from './validate.mjs';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const CLI = path.join(ROOT, 'bin', 'flow-kit.mjs');
-
-let pass = 0, fail = 0;
-function check(name, cond, detail = '') {
-  if (cond) { pass++; console.log(`PASS ${name}`); }
-  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
-}
-
-// ---- validateExit 纯函数（判据单源）----
-check('V1 blocker → 1', validateExit({ exitCode: 1, blockers: ['x'], warnings: [] }, false) === 1);
-check('V2 干净 → 0', validateExit({ exitCode: 0, blockers: [], warnings: [] }, false) === 0);
-check('V3 warning 非 strict → 0', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, false) === 0);
-check('V4 warning + strict → 1', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, true) === 1);
-check('V5 引擎结果缺失 fail-closed → 1', validateExit(null, false) === 1 && validateExit(undefined, true) === 1);
-
-// ---- fixture（枚举单源内联，同 check-loop.test.mjs#ENUMS_FIXTURE）----
-const ENUMS_FIXTURE = [
-  'doc.status.all=draft approved done superseded cancelled',
-  'doc.status.confirmed=approved done superseded cancelled',
-  'doc.status.active=draft approved',
-  'doc.status.terminal=done superseded cancelled',
-  'doc.status.abandoned=superseded cancelled',
-  'incident.status.all=open fixed closed',
-  'incident.status.active=open',
-  'level.all=L1 L2 L3',
-].join('\n') + '\n';
-
-const mkfix = () => {
-  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-'));
-  for (const s of ['intents', 'specs', 'plans', 'incidents']) {
-    fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
-  }
-  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
-  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'), ENUMS_FIXTURE);
-  return d;
-};
-
-const runValidate = (dir, args = []) => spawnSync(process.execPath, [CLI, 'validate', '--dir', dir, ...args], {
-  cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
-});
-const stdoutOf = (r) => r.stdout || '';
-const stderrOf = (r) => r.stderr || '';
-
-// ---- 端到端：绿盘面（空四目录 + 枚举单源）----
-const green = mkfix();
-const rg = runValidate(green, ['--json']);
-let greenJson = null;
-try { greenJson = JSON.parse(stdoutOf(rg)); } catch { /* 解析失败在断言里报 */ }
-check('V6 绿盘面 exit 0', rg.status === 0, `exit=${rg.status}\n${stdoutOf(rg)}\n${stderrOf(rg).slice(0, 300)}`);
-check('V7 --json stdout 可解析且 blockers 空', !!greenJson && Array.isArray(greenJson.blockers) && greenJson.blockers.length === 0, stdoutOf(rg).slice(0, 300));
-check('V8 --json 契约字段在位', !!greenJson && greenJson.exitCode === 0 && greenJson.checkLoopExitCode === 0 && greenJson.strict === false && typeof greenJson.target === 'string', JSON.stringify(greenJson));
-// --strict 契约端到端：同一盘面 fixture 恒产出 advisory warning（装副本骨架件缺失类，绿判不受其扰），
-// 非 strict 绿（V6 已证）、strict 判红且 checkLoopExitCode 保持 0——判红来源是 strict 规则而非引擎
-const rs = runValidate(green, ['--json', '--strict']);
-let strictJson = null;
-try { strictJson = JSON.parse(stdoutOf(rs)); } catch { /* 同上 */ }
-check('V9 --strict 把 advisory warning 判红（checkLoopExitCode 仍 0）',
-  rs.status === 1 && !!strictJson && strictJson.exitCode === 1 && strictJson.checkLoopExitCode === 0 && strictJson.strict === true && strictJson.warnings.length > 0,
-  `exit=${rs.status}\n${stdoutOf(rs).slice(0, 300)}`);
-
-// ---- 端到端：红盘面（同名配对断档：intent 无同名 spec/plan → 检查 1 hard-block）----
-const red = mkfix();
-fs.writeFileSync(path.join(red, 'workflow', 'intents', '2026-01-01-solo.md'),
-  '---\nstatus: draft\nlevel: L1\n---\n# INTENT — solo\n');
-const rr = runValidate(red, ['--json']);
-let redJson = null;
-try { redJson = JSON.parse(stdoutOf(rr)); } catch { /* 同上 */ }
-check('V10 配对断档 exit 1', rr.status === 1, `exit=${rr.status}\n${stdoutOf(rr).slice(0, 300)}\n${stderrOf(rr).slice(0, 500)}`);
-check('V11 --json blockers 非空且明细走 stdout JSON', !!redJson && redJson.blockers.length > 0, stdoutOf(rr).slice(0, 300));
-
-// ---- 指引与用法错 ----
-const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-bare-'));
-const rb = runValidate(bare);
-check('V12 缺 .agents/ → exit 1 且给 init 指引', rb.status === 1 && /init/.test(stderrOf(rb)), `exit=${rb.status}\n${stderrOf(rb).slice(0, 300)}`);
-const ru = runValidate(green, ['--bogus']);
-check('V13 未知参数 → exit 1 用法行', ru.status === 1 && /用法/.test(stderrOf(ru)), `exit=${ru.status}\n${stderrOf(ru).slice(0, 300)}`);
-
-// ---- 清理 ----
-for (const d of [green, red, bare]) fs.rmSync(d, { recursive: true, force: true });
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);

package/templates/.gitattributes

@@ -1,17 +0,0 @@
-# agentic-flow-kit：钩子与 shell 脚本必须 LF（CRLF 会破坏 Git Bash/MSYS 执行）；
-# 预算表按 LF 计量（读取方 rule-budget.mjs 容 CRLF 行尾，此条为双保险）。已有自有 .gitattributes 的项目合并这几条即可。
-*.sh text eol=lf
-.githooks/* text eol=lf
-.agents/hooks/local-pre-commit text eol=lf
-*.ps1 text eol=crlf
-
-# 台账并集合并（2026-10-12 ledger-merge-driver）：确认台账是「尾部追加 + 多人/多 worktree 并行」形态，
-# 默认三方合并会把它当文本冲突，人工解的常见错法是「整取一侧」——静默丢掉另一侧的确认行，
-# 门禁事后无从发现。本 driver 把合并降级为确定性并集去重：两侧行全保留，无冲突可解。
-# 需配 driver（flow-kit init 自动配）：git config merge.jsonl-union.driver "node .agents/scripts/git-merge-jsonl.mjs %O %A %B"
-# **故意不加 text eol=lf**：给既有 .jsonl 加 text 规则会让下次提交时 git 重新规范化换行 → 台账 blob 字节变化
-#   → check-ledger-invariant 的 append-only 前缀不变量判为「台账重写」而硬拦。台账换行归一由 driver 自身负责。
-.agents/*.jsonl merge=jsonl-union
-# 分片目录（2026-10-13 ledger-shard-default）：上面的 glob 不跨目录层级，confirmations.d/ 下的分片
-# 须单列——分片已是默认写入口径，漏配则并行分支合并分片时仍走文本冲突（整取一侧 = 静默丢确认行）。
-.agents/confirmations.d/*.jsonl merge=jsonl-union

package/templates/AGENTS.md

@@ -1,57 +0,0 @@
-<!-- flow-kit:agents-skeleton -->
-# AGENTS.md — AI 工作流 + Wiki
-
-> 本文件由 agentic-flow-kit 生成：说明本仓库的 AI 工作流与 Wiki 用法。「项目适配区」由项目自行填写；工作流约定可增不可删。
-
-## AI工作流
-
-**闭环模型**：`workflow/` 是唯一真相源——intents（为什么做）→ specs（怎么设计）→ plans（怎么做）→ incidents（学到了什么）。单人 + AI 协作：AI 起草 / 实现 / 验证 / 自查，取舍与放行由用户拍板，确认在对话内一句话完成，追溯靠 git。文档协议（frontmatter 字段、状态枚举、命名规则）见 `workflow/README.md`。
-
-### 开工前必读
-
-1. **新需求 / 功能**：先立 `workflow/intents/` intent（复制 `_TEMPLATE.md`），对话内与用户确认后开工。
-2. **修复类任务**：先查 `workflow/incidents/` 同类历史；L1 以上立 incident（修复中即 intent 等价入口，L2/L3 与 spec/plan 同名配对）。
-3. **级别判断与风险泳道**（就高不就低）：L1 实现级（一份 plan 即入口）；L2 规则/契约；L3 数据与运行时结构。L1 协作道（轻确认+异步审计）；L2/L3 防御道（同步确认门：spec/plan 确认后方可动手，L3 加独立复核）。见 `.agents/commands/new-task.md`。
-
-### 阶段路由
-
-总入口 `.agents/commands/new-task.md`：Plan `.agents/commands/plan.md` → Design `.agents/commands/design.md` → Build `.agents/commands/build.md` → Test `.agents/commands/test.md` → Deploy `.agents/commands/deploy.md` → Maintain `.agents/commands/maintain.md`；`.agents/commands/review.md` 为横切评审入口。
-
-### 子智能体
-
-公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。多工作包编排（自动加载）：跑编排 / plan 执行多工作包时，读 `.agents/workflows/` 编排脚本按机制文档执行——stages 表（依赖分层 / 并行 / 重试 / gate）+ `steps/` 自定义步骤扩展点，见 `.agents/workflows/_TEMPLATE.md`。
-
-### 门禁与提交
-
-- `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / 泳道完整性 / wiki 台账 / 规则面预算 / 确认台账不变量 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
-- **CI 远端门（2026-10-07 起）**：`.github/workflows/kit-ci.yml`（owned）在 GitHub runner 复跑 `node .agents/scripts/verify.mjs`（云端兜底本地钩子）；非 GitHub 装户可删，等价门 = 同入口命令 + 服务端分支策略（人工一次性配置，机器不校验）。
-- **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
-- 项目专属门禁挂 `.agents/hooks/local-pre-commit`。装户五条硬规则（配对、验收、确认留痕、敏感信息、双源台账）与 `audit` 档见 `workflow/README.md`「硬规则」。
-- 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）。L1+ 三段式闭环链：`docs(*)` approved 留痕 → 代码 → 关单 `docs(*)`，相邻提交即同一闭环（2026-10-04 修订）。
-- **确认门（2026-09-27 起）**：intent/spec/plan 的 approved/done 与 incident 的 fixed/closed（两跳、无单跳）唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`，放弃态走显式 `--to superseded|cancelled`（合法前态见脚本提示；四终态同样内容绑定），两形态：① 用户终端亲手运行键入「可以」（TTY，AI 会话内被拒）；② **对话委托代录**——用户在对话内明确确认后，AI 跑 `confirm-doc.mjs <path> --delegated "<授权摘要>"` 逐件代录（默认一次一份，多份并录被拒），台账如实记 `source: chat-delegated`，永不伪装 TTY 行（check-loop 15 指纹+台账对账拦截，与 source 无关）；L1 协作道可 `--batch` 多份一次代录（台账 `brief:true`，15 并录告警豁免；L2/L3 仍逐份）。
-- **改动面 scope = 授权的机器事实（2026-10-09 起）**：confirm-doc 落账自动记 `scope{files,sha256}`（被确认文档 + `git status` 实测未提交改动集，机器派生、**AI 无输入面**）。分辨力由 scope + 指纹承担，`--delegated` 的摘要降级为人类可读留痕——**「每次换一句原话」纪律退役**，复用同一句摘要不再削弱任何判据。check-loop 15 校验受管行带 scope 且摘要自洽（`policyVersion ≥ 7` 起，旧版本与存量行零新增告警）。
-
-### 检索、看板与量化
-
-- 跨语料检索：`node .agents/scripts/kb-search.mjs "<词>"`（workflow 节级定位 + wiki 全文）；活跃流程读 `workflow/INDEX.md`（状态变更后 `node .agents/scripts/gen-workflow-index.mjs` 重生成）。
-- workflow 看板（可选，默认不拉起）：需要时手动跑 `node .agents/scripts/ensure-board.mjs`（跨平台，Windows/Linux/macOS 通用），端口从基端口 {{BOARD_PORT}} 起自动上探首个可用（多项目并行不冲突），链接以脚本输出为准（只读预警层，非门禁）。
-- 委派 / 自做结果留痕 `workflow/delegations.md`（聚合 `node .agents/scripts/agg-delegations.cjs`）；命令 / 技能卡壳记 `workflow/papercuts.md`，不当场顺手改。
-
-### 验证与关单
-
-验证入口 `.agents/commands/test.md`；**关单在 test**：逐条勾验入口文档「验收标准」并补证据后 intent → done，未勾验会被 check-loop 拦。上 prod 另走 `.agents/commands/deploy.md`（tag / 回滚 / 观察），不用 deploy 关单。
-
-## Wiki
-
-`wiki/` 是项目知识沉淀，按主题目录归位；原始 / 一次性文档归档 `wiki/drafts-archive/<日期-主题>/`（只读不增量）。
-
-- 人工只维护两样：**磁盘文件本身 + `wiki/INDEX.md` 速览表「用途」列**；计数 / 映射表 / 看板 DATA 均为生成区，勿手改——`node .agents/scripts/gen-wiki-board.mjs` 重生成，`node .agents/scripts/verify-wiki-consistency.mjs` 三方一致性验证（触及 `wiki/` 的提交会被 pre-commit 台账门禁校验）。
-- **沉淀与血缘（2026-10-10 起）**：关单时 `node .agents/scripts/draft-sediment.mjs workflow/<intents|incidents>/<本单>.md` 自动把高价值节抽成 `drafts-archive/` 草稿（`--dry-run` 预览；全占位拒抽）；草稿是中间态，人工归类到 `wiki/<主题>/` 后跑生成器 + 验证。沉淀关系用 frontmatter 双向链接：wiki 文件 `来源: workflow/…`、workflow 文件 `沉淀: wiki/…`（不沉淀写 `沉淀: 无`）——两向字段的存在性由 verify-wiki-consistency 与 check-loop 校验，改名 / 移动时须同步。
-- wiki 看板：`wiki/知识沉淀总览.html`。
-
-## 项目适配区（项目自填）
-
-- **构建 / 测试 / 类型检查命令**（静态门，各阶段命令引用此处口径）：构建 = {{BUILD_CMD}}；测试 = {{TEST_CMD}}；类型检查 = {{TYPECHECK_CMD}}
-- **运行时环境**（端口 / 进程 / 终端差异）：`.agents/notes/runtime-env.md`
-- **目录级规则**：如 `backend/AGENTS.md`、`frontend/AGENTS.md`（如有）——目录级约定不回填本文件
-- **权限与提交验证配置**：`.agents/settings.json`（allow / deny / ask）、`.agents/hooks/commit-check.config.json`（条件构建 / 质量检测命令与密钥白名单——质量检测只放秒级确定性检查（lint / 类型检查 / vet），测试不放提交门，关单在 test 阶段门）