agentic-flow-kit 1.8.7 → 2.0.0

package/templates/_agents/scripts/edit-face-check.test.mjs

@@ -1,99 +0,0 @@
-// edit-face-check.test.mjs — 编辑时快检（2026-10-09 engine-quality-round2 B2）
-// 三面：纯函数（lfBytes/globToRe/budgetAdvisory）+ 端到端全绿面 + 破坏面（删阶段索引→WARN→exit 1、
-// 预算超限→exit 1）。判定零复刻：端到端经 CHECK_LOOP_ROOT 消费真 check-loop，fixture 复制脚本集。
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const SRC = path.dirname(fileURLToPath(import.meta.url));
-let pass = 0, fail = 0;
-const check = (name, cond, detail = '') => {
-  if (cond) { pass++; console.log(`PASS ${name}`); }
-  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
-};
-
-const mod = await import(pathToFileURL(path.join(SRC, 'edit-face-check.mjs')).href);
-const { lfBytes, globToRe, budgetAdvisory } = mod;
-
-// ---- ① 纯函数 ----
-check('lfBytes：CRLF 归一计 UTF-8 字节', lfBytes('a\r\nb中文') === Buffer.byteLength('a\nb中文', 'utf8'));
-check('globToRe：精确路径', globToRe('AGENTS.md').test('AGENTS.md') && !globToRe('AGENTS.md').test('x/AGENTS.md'));
-check('globToRe：段内通配', globToRe('.agents/commands/*.md').test('.agents/commands/plan.md') && !globToRe('.agents/commands/*.md').test('.agents/commands/x/plan.md'));
-check('globToRe：目录前缀', globToRe('.agents/cache/').test('.agents/cache/a/b.json'));
-
-{
-  const files = new Map([
-    ['AGENTS.md', 'x'.repeat(120)],
-    ['.agents/commands/plan.md', 'y'.repeat(50)],
-  ]);
-  const budgets = '# 注释行\nAGENTS.md 100\n.agents/commands/*.md 200\n非法行\n';
-  const r = budgetAdvisory(files, budgets);
-  check('budgetAdvisory：超限单文件报、未超限不报、非法行跳过',
-    r.length === 1 && r[0].rel === 'AGENTS.md' && r[0].limit === 100 && r[0].actual === 120, JSON.stringify(r));
-  check('budgetAdvisory：表缺失 fail-open', budgetAdvisory(files, null).length === 0);
-}
-
-// ---- ② 端到端 fixture ----
-// 夹具闭包（2026-10-12 fixture-closure-rootfix）：此前手写 SCRIPTS 枚举，漏拷 ledger-loader / ledger-prune
-// 就让 check-loop import 失败 → 门禁静默不跑 → **假绿**。改为按入口自动求传递闭包，新增依赖自动跟随。
-const { copyScriptClosure, copyAgentsFiles } = await import('./fixture-scripts.mjs');
-// 引用完整性哑文件（检查 4/6/7 的存在性判据——避免 fixture 结构性 WARN 淹没断言面）
-const REF_COMMANDS = ['new-task', 'plan', 'design', 'build', 'test', 'deploy', 'maintain', 'review'];
-const REF_ROLES = ['implementer', 'independent-reviewer', 'ui-verifier'];
-function mkFixture({ breakStageIndex, overBudget }) {
-  const fx = fs.mkdtempSync(path.join(os.tmpdir(), 'efc-'));
-  fs.mkdirSync(path.join(fx, '.agents', 'scripts'), { recursive: true });
-  copyScriptClosure(path.join(fx, '.agents', 'scripts'), ['edit-face-check.mjs', 'check-loop.mjs']);
-  copyAgentsFiles(path.join(fx, '.agents'), ['kit.json', 'workflow-modules.txt', 'workflow-enums.txt']);
-  fs.mkdirSync(path.join(fx, 'workflow', 'intents'), { recursive: true });
-  for (const d of ['specs', 'plans', 'incidents']) fs.mkdirSync(path.join(fx, 'workflow', d), { recursive: true });
-  for (const c of REF_COMMANDS) { fs.mkdirSync(path.join(fx, '.agents', 'commands'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'commands', `${c}.md`), `# ${c}\n`); }
-  for (const rname of REF_ROLES) { fs.mkdirSync(path.join(fx, '.agents', 'roles'), { recursive: true }); fs.writeFileSync(path.join(fx, '.agents', 'roles', `${rname}.md`), `# ${rname}\n`); }
-  // 常驻面 AGENTS.md：阶段索引齐全（含 review）/ 破坏面删索引（破坏只在 AGENTS.md 侧——new-task
-  //   哑文件写全索引，钉检查 7 的双向语义差异）
-  const routes = '.agents/commands/plan.md → .agents/commands/design.md → .agents/commands/build.md → .agents/commands/test.md → .agents/commands/deploy.md → .agents/commands/maintain.md';
-  const reviewLine = breakStageIndex ? '' : '\n**横切**：.agents/commands/review.md\n';
-  const body = `# AGENTS\n\n## 阶段路由\n\n**入口**：.agents/commands/new-task.md\n**指令**：${breakStageIndex ? '（已删）' : routes}${reviewLine}\n`;
-  fs.writeFileSync(path.join(fx, 'AGENTS.md'), overBudget ? body + 'x'.repeat(200) : body);
-  fs.writeFileSync(path.join(fx, '.agents', 'commands', 'new-task.md'),
-    `# new-task\n\n| Plan | ${routes} | Review |\n`);
-  fs.writeFileSync(path.join(fx, '.agents', 'rule-budgets.txt'), `AGENTS.md ${overBudget ? 100 : 100000}\n`);
-  return fx;
-}
-
-{
-  // 全绿面：空 workflow + 引用齐全 + 预算内 → hard/预算两道过（exit 0）。
-  //   注：不要求零 WARN——check-loop 全扫对极简 fixture 有结构性 advisory（引用/角色形态），明细
-  //   承载给编辑者对照；exit 语义只钉 hard 与预算两道（绝对 WARN 计数会让存量仓库恒非零）。
-  const fx = mkFixture({});
-  const driver = path.join(fx, 'driver.mjs');
-  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
-  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
-  check('E2E 全绿面：exit 0（hard/预算两道过）且 AGENTS.md 侧无索引漂移', r.status === 0 && !/AGENTS\.md 缺 .* 指令索引/.test(r.stdout || ''), `status=${r.status}\n${(r.stdout || '') + (r.stderr || '')}`.slice(0, 600));
-}
-
-{
-  // 破坏面：删阶段索引 → 检查 7 WARN 点名（明细承载编辑破坏——破坏面 vs 全绿面的差异就在输出；
-  //   hard 不误触：阶段索引是 warning 级，exit≠2）
-  const fx = mkFixture({ breakStageIndex: true });
-  const driver = path.join(fx, 'driver.mjs');
-  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
-  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
-  const out = (r.stdout || '') + (r.stderr || '');
-  check('E2E 破坏面（删阶段索引）：WARN 点名 AGENTS.md 侧索引漂移且 hard 不误触', r.status !== 2 && /AGENTS\.md 缺 plan 指令索引/.test(out), `status=${r.status}\n${out.slice(0, 600)}`);
-}
-
-{
-  // 预算超限面：AGENTS.md 超上限 → exit 1（advisory 面单独可达——workflow 全绿）
-  const fx = mkFixture({ overBudget: true });
-  const driver = path.join(fx, 'driver.mjs');
-  fs.writeFileSync(driver, `import { main } from ${JSON.stringify('file:///' + path.join(fx, '.agents', 'scripts', 'edit-face-check.mjs').replace(/\\/g, '/'))};\nprocess.exit(main(${JSON.stringify(fx)}, ${JSON.stringify(path.join(fx, '.agents', 'scripts'))}));\n`);
-  const r = spawnSync(process.execPath, [driver], { encoding: 'utf8' });
-  const out = (r.stdout || '') + (r.stderr || '');
-  check('E2E 预算超限面：exit 1 且 advisory 点名', r.status === 1 && /预算 advisory/.test(out), `status=${r.status}\n${out.slice(0, 500)}`);
-}
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/ensure-board.mjs

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-// ensure-board.mjs — workflow 看板按需手动拉起（默认不自动开启；只起不关：OS 重启即天然回收，无需 stop/status）
-// 跨平台单入口（零依赖，Windows/Linux/macOS 同一脚本，取代旧 ensure-board.ps1）：
-//   基端口（--port 显式 > kit.json boardPort > 8933）向上探测首个可用端口（窗口 10）——
-//   端口空闲 → 全新启动；探活 /api/board 比对 root：本项目看板 → 复用（代码文件晚于服务端 startedAt = 旧代码自动 kill 重启）；
-//   他人进程（其他项目看板 / 非看板服务）不动手不 kill，跳过试下一端口；全新启动成功后弹浏览器（重启/已运行不弹，SSE 自动重连）
-// 身份与陈旧判定全部来自 /api/board 自报（pid/startedAt）——不碰 OS 专属的端口属主 / 进程启动时间 API。
-// 用法：node .agents/scripts/ensure-board.mjs [--port 8933] [--no-open]
-import net from 'node:net';
-import http from 'node:http';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { spawn } from 'node:child_process';
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const ROOT = path.resolve(SCRIPT_DIR, '../..'); // 与 server 的 ROOT 同口径
-const SERVER = path.join(SCRIPT_DIR, 'workflow-board-server.mjs');
-const CODE_FILES = [
-  path.join(ROOT, '.agents', 'board', 'index.html'),
-  SERVER,
-  path.join(SCRIPT_DIR, 'workflow-enums.mjs'),   // server import 即加载（p2-batch2：枚举更新不触发重启的盲区）
-  path.join(ROOT, '.agents', 'board', 'marked.min.js'), // 前端运行时依赖（同盲区）
-]; // 任一更新都算「旧代码」
-const WINDOW = 10;
-
-// ---- 参数与基端口 ----
-const argv = process.argv;
-const flagIdx = argv.indexOf('--port');
-const eqArg = argv.find((a) => a.startsWith('--port='));
-const portArg = flagIdx > -1 ? argv[flagIdx + 1] : eqArg && eqArg.slice('--port='.length);
-const noOpen = argv.includes('--no-open');
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-let BASE_PORT;
-if (portArg && Number(portArg)) {
-  BASE_PORT = Number(portArg);
-} else {
-  // 基端口取 kit 台账（init 询问值，与命令文档 8933 同源）；无台账或解析失败回落 8933
-  try { BASE_PORT = Number(JSON.parse(fs.readFileSync(path.join(ROOT, '.agents', 'kit.json'), 'utf8')).options.boardPort) || 8933; }
-  catch { BASE_PORT = 8933; }
-}
-
-const samePath = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
-
-// ---- 探活：端口占用用 net.connect；看板身份/属主用 /api/board 自报（isBoard=含 cards 字段；ours=root 指向本项目）----
-// 不用全局 fetch：undici 连接池 keep-alive 句柄会拖住/污染退出（Windows 上强退触发 libuv 断言）
-function portBusy(port) {
-  return new Promise((resolve) => {
-    const s = net.connect({ host: '127.0.0.1', port });
-    s.setTimeout(800);
-    s.on('connect', () => { s.destroy(); resolve(true); });
-    s.on('timeout', () => { s.destroy(); resolve(true); }); // 超时从保守视作占用；localhost 上近乎不存在
-    s.on('error', () => resolve(false));
-  });
-}
-
-// /api/board 用 http.get 正规解包（server 响应为 chunked，手工拼包解析不了）；Connection: close + 默认 agent 不进连接池，无残留句柄
-function httpProbe(port) {
-  return new Promise((resolve) => {
-    const req = http.get({ host: '127.0.0.1', port, path: '/api/board', headers: { Connection: 'close' }, timeout: 2000 }, (res) => {
-      let buf = '';
-      res.on('data', (d) => { buf += d; });
-      res.on('end', () => resolve({ status: res.statusCode, json: () => { try { return JSON.parse(buf); } catch { return null; } } }));
-    });
-    req.on('timeout', () => { req.destroy(); resolve({ status: 0 }); });
-    req.on('error', () => resolve({ status: 0 }));
-  });
-}
-
-async function probeBoard(port) {
-  const none = { isBoard: false };
-  const r = await httpProbe(port);
-  if (r.status !== 200) return none;
-  const j = r.json();
-  if (!j || typeof j !== 'object' || !('cards' in j)) return none;
-  return { isBoard: true, ours: !!(j.root && samePath(path.resolve(String(j.root)), ROOT)), pid: j.pid, startedAt: j.startedAt };
-}
-
-// 陈旧判定：代码文件最新 mtime 晚于服务端启动时刻（2s 容差）= 旧代码；无 startedAt（旧版服务端）返回 null 无法判定
-function staleCode(startedAt) {
-  if (!startedAt) return null;
-  const newest = Math.max(...CODE_FILES.filter((f) => fs.existsSync(f)).map((f) => fs.statSync(f).mtimeMs));
-  return newest > startedAt + 2000;
-}
-
-// ---- 动作：kill / 拉起（detached + windowsHide，父进程退出后存活）/ 等监听 / 弹浏览器 ----
-function startServer(port) {
-  const c = spawn(process.execPath, [SERVER, '--port', String(port)], { detached: true, stdio: 'ignore', windowsHide: true });
-  c.unref();
-  return c; // 返回 child 供竞态复验比对 pid（p2-batch2）
-}
-
-async function waitListen(port) {
-  const deadline = Date.now() + 8000;
-  while (Date.now() < deadline) {
-    if (await portBusy(port)) return true;
-    await sleep(300);
-  }
-  return false;
-}
-
-// intentional-simple: 弹浏览器 best-effort 三平台分流（win: cmd start / mac: open / linux: xdg-open），失败不打扰——链接已在输出里
-function openBrowser(url) {
-  try {
-    if (process.platform === 'win32') spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
-    else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true, stdio: 'ignore' }).unref();
-  } catch { /* 浏览器拉起失败不阻断看板流程 */ }
-}
-
-// ---- 主流程（返回退出码，自然排水退出——不用 process.exit：强退在 Windows 上会触发 libuv 断言）----
-async function main() {
-  const skipped = [];
-  let action = null;
-  let port = 0;
-  let board = null;
-
-  for (let p = BASE_PORT; p < BASE_PORT + WINDOW; p++) {
-    if (!(await portBusy(p))) { port = p; action = 'fresh start'; break; }
-    const b = await probeBoard(p);
-    if (b.ours) {
-      port = p;
-      board = b;
-      const stale = staleCode(b.startedAt);
-      if (stale === true) {
-        try { process.kill(b.pid); } catch { /* 进程可能已自行退出 */ }
-        await sleep(500);
-        action = 'restarted (stale code detected)';
-      } else if (stale === null) {
-        action = 'legacy';
-      } else {
-        action = 'up-to-date';
-      }
-      break;
-    }
-    skipped.push(`端口 ${p}（pid ${b.pid ?? '未知'}）`);
-  }
-  const url = `http://127.0.0.1:${port}`;
-
-  if (!action) {
-    console.log(`board: 端口 ${BASE_PORT}..${BASE_PORT + WINDOW - 1} 均被他人进程占用（未动手不 kill）：${skipped.join('；')}；可 --port 指定其他基端口`);
-    return 1;
-  }
-  if (action === 'legacy') {
-    console.log(`board: ${url} 是本项目旧版看板（无 startedAt，无法判定代码新旧），未自动重启；如需更新请手动重启`);
-    return 0;
-  }
-  if (action === 'up-to-date') {
-    console.log(`board: already up-to-date at ${url} (pid ${board.pid ?? '未知'})`);
-    return 0;
-  }
-  if (skipped.length) console.log(`board: 基端口段他人进程已跳过：${skipped.join('；')}`);
-
-  const child = startServer(port);
-  if (!(await waitListen(port))) {
-    console.log(`board: FAILED to start on ${port}`);
-    return 1;
-  }
-  // 竞态复验（2026-09-27 p2-batch2；同日复核 P1-1 收窄）：waitListen 只见「端口有人听」——spawn 与
-  // listen 之间他人进程抢先绑定同端口时自家子进程已 EADDRINUSE 退出。复验 /api/board 自报 pid 与
-  // 自家子进程一致。判定顺序（复核实测教训：冷启动首包可达 12s，2s 硬超时会误杀 fresh start 主路径）：
-  //   ① 子进程已退出（EADDRINUSE 自杀）→ 端口确被抢占，如实报告；
-  //   ② 15s 内轮询 probeBoard 直到自报 pid === 自家 pid（长超时容忍冷启动）；
-  //   ③ 轮询超时仍不一致 → 如实报告未确认为本项目（不误称他人抢占）。
-  const deadline = Date.now() + 15000;
-  let mine = null;
-  while (Date.now() < deadline) {
-    if (child.exitCode !== null) {
-      console.log(`board: 端口 ${port} 在启动窗口被他人进程抢占（本项目进程已退出 exitCode=${child.exitCode}）——本轮未拉起本项目看板，可重跑 ensure-board 自动上探下一端口`);
-      return 1;
-    }
-    mine = await probeBoard(port);
-    if (mine.ours && mine.pid === child.pid) break;
-    await sleep(400);
-  }
-  if (!mine || !mine.ours || mine.pid !== child.pid) {
-    console.log(`board: 端口 ${port} 上的服务未能确认为本项目（pid ${child.pid}，自报 ${mine?.pid ?? '未知'}）——冷启动超时或被抢占；可重跑 ensure-board`);
-    return 1;
-  }
-  console.log(`board: ${action} -> ${url}`);
-  if (!noOpen && action === 'fresh start') openBrowser(url);
-  return 0;
-}
-
-process.exitCode = await main();

package/templates/_agents/scripts/fill-intent.mjs

@@ -1,91 +0,0 @@
-// flow-kit fill-intent：起草 intent 草稿（背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核 共 9 节）
-// 读 workflow/intents/_TEMPLATE.md 的节标题 → 输出符合 frontmatter 受限子集（7 字段，含 risk_level 风险泳道与预判路由）的草稿到指定文件
-// 用法：node .agents/scripts/fill-intent.mjs --module pipeline --level L1 --topic "test" --output /tmp/x.md
-// 零依赖；CLI 解析用最简字符串匹配；不替代 AI 起草——本工具只输出模板与提示句
-import fs from 'node:fs';
-import path from 'node:path';
-import { ENUMS } from './workflow-enums.mjs';
-import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const TODAY = new Date().toISOString().slice(0, 10);
-const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
-
-function parseArgs(argv) {
-  const out = { topic: null, module: null, level: 'L1', output: null, notes: '' };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
-    if (a === '--topic') out.topic = next();
-    else if (a === '--module') out.module = next();
-    else if (a === '--level') out.level = next();
-    else if (a === '--output') out.output = next();
-    else if (a === '--notes') out.notes = next() || '';
-  }
-  return out;
-}
-
-function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
-
-const SECTIONS = [
-  { title: '背景与问题', hint: '<为什么做；写明需求来源（工单 / 沟通记录 / 待办事项）>' },
-  { title: '历史教训/防复发', hint: '- 检索结果：`node .agents/scripts/kb-search.mjs "<关键词>" --type incidents` 命中结果\n- 避坑指南：<针对历史根因，本次如何预防/规避>' },
-  { title: '目标', hint: '- <可验证的目标>' },
-  { title: '非目标（L1 微改动无实质内容可删本节，不硬填）', hint: '- <明确不做的，防止范围蔓延>' },
-  { title: '约束（L1 微改动无实质内容可删本节，不硬填）', hint: '- <复用什么、不许动什么>' },
-  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 → L3；无 schema 的运行时 / 管线结构面亦为 L3，判据单源见 .agents/scripts/level-criteria.mjs 的 L3_SURFACES）\n- 前端页面：<路由或组件，无则删本行>' },
-  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 触及判据单源 `.agents/scripts/level-criteria.mjs` 的 `L2_SURFACES` 触达面闭集 → 级别至少 L2\n- [ ] 触及同源的 `L3_SURFACES` 结构面闭集 → 级别 L3\n\n> 两条闭集只在该单源一处定义，**逐条对照单源勾选，不要凭记忆复述**（此处曾各写一份且条目不一致，判低即错判）。\n> 触及任一红线即为 L2 / L3，必须立 ../specs/YYYY-MM-DD-<主题>.md 写明如何满足，方可起草 plan。' },
-  { title: '验收标准（可测试）', hint: '- [ ] <逐条可测试；写不出可测试判据 = 还没想清楚>\n\n> **闭环对账**：关单在 test 阶段（不依赖 deploy）。intent 置 done 前逐条勾验，每条补证据——`- [x] <判据>（证据：<commit SHA / 测试用例名 / 冒烟脚本输出>）`。\n> done 状态仍有未勾项会被 check-loop 拦截（2026-09-12 起新建 intent 为 hard-block，存量 intent 仅 warning 提示）；勾选但缺「证据：」为 hard-block。' },
-];
-
-// renderIntent：骨架渲染（纯函数）。kbHits（2026-10-09 engine-quality-round3 W2）：kb-search 命中行
-// 数组（📄 行原文）——非空时替换「历史教训/防复发」节的检索占位行为实际命中列表（历史坑强制注入，
-// 手动路由与 pipeline-run 工单同权）；空/缺省保留占位（fail-open 口径）。子进程调用在 main，本函数保持无 IO。
-// 预判（2026-10-13 自 Shipyard §25 prejudgment-ledger 回灌）：intents≡require 恒真、level 与「级别」双写
-// 同值——机器可推导字段直出（与 B6b 路由预判一致性检查对账零 WARN）；advisory 灰度，缺字段零告警。
-export function renderIntent({ topic, module, level, notes, date = TODAY, kbHits = [], kbFailNote = '' }) {
-  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
-  const fm = '---\n状态: draft\n级别: ' + level + '\n预判: kind=require level=' + level + '\nrisk_level: ' + level + '\n日期: ' + date + '\n模块: ' + module + '\n备注: ' + (notes || '<可选：附注自由文本，check-loop 不解析>') + '\n---\n';
-  let body = '# INTENT — ' + topic + '\n\n<!-- 复制本模板为 YYYY-MM-DD-<主题>.md 后填写；plans/ 下同名文件与本文件配对 -->\n<!-- frontmatter 受限子集（2026-09-13）：每行 键: 值；状态∈draft/approved/done/superseded/cancelled（严格枚举，附注写备注键）；级别∈L1/L2/L3（2026-10-13 L0 退役）；risk_level=级别（混合治理风险泳道选道：L1 协作道异步审计 / L2/L3 防御道同步确认）；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->\n\n';
-  for (const { title, hint } of SECTIONS) {
-    let section = hint;
-    if (title === '历史教训/防复发') {
-      const placeholder = '- 检索结果：`node .agents/scripts/kb-search.mjs "<关键词>" --type incidents` 命中结果';
-      if (kbHits.length) {
-      const injected = '- 检索结果（自动注入 ' + kbHits.length + ' 条，同域历史——起草前先读其根因与防复发）：\n' + kbHits.map((h) => '  - ' + h).join('\n');
-      if (section.includes(placeholder)) section = section.replace(placeholder, injected);
-      }
-      else if (kbFailNote) section = section.replace('- 检索结果：', '- 检索结果' + kbFailNote + '\n- 检索结果：'); // 复核 P2-2：不可用时留手工命令注释行
-    }
-    body += '## ' + title + '\n\n' + section + '\n\n';
-  }
-  body += '## 确认与复核\n\n- 确认日期：\n- 确认人：用户（对话内明确放行即确认）\n- 确认范围：\n- 复核：L1 不要求独立复核\n';
-  return { frontmatter: fm, body: fm + body, sections: SECTIONS.map((s) => s.title) };
-}
-
-const isMain = process.argv[1] && process.argv[1].endsWith('fill-intent.mjs');
-if (isMain) {
-  const a = parseArgs(process.argv.slice(2));
-  if (!a.topic || !a.module || !a.output) fail('必填：--topic / --module / --output；选填：--level（默认 L1）/ --notes');
-  if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
-  // 历史坑强制注入（2026-10-09 engine-quality-round3 W2）：同目录 kb-search 子进程检索同域历史
-  // （关键词 = topic ascii 段 + 模块名；--type incidents,plans——修复先例与计划同查）。fail-open：
-  // 非零/零命中/3s 超时 → kbHits 空 → 保留占位（与手动路由「AI 自觉检索」不同，此处机器保证尝试）。
-  let kbFailNote = '';
-  let kbHits = [];
-  try {
-    const words = (String(a.topic).toLowerCase().match(/[a-z0-9]{2,}/g) || []).slice(0, 2);
-    const kw = [...new Set([...words, String(a.module || '')].filter(Boolean))]; // 复核 P1-1：模块名入关键词（spec S2 口径）
-    const r = spawnSync(process.execPath, [path.join(path.dirname(fileURLToPath(import.meta.url)), 'kb-search.mjs'),
-      ...kw, '--scope', 'workflow', '--type', 'incidents,plans', '-n', '4'], { encoding: 'utf8', timeout: 3000, windowsHide: true });
-    if (r.status === 0 && r.stdout) {
-      kbHits = r.stdout.split(/\r?\n/).filter((l) => l.startsWith('📄')).slice(0, 4);
-    if (!kbHits.length) kbFailNote = '（自动检索不可用或零命中，手工跑：node .agents/scripts/kb-search.mjs "<关键词>" --type incidents）';
-    }
-  } catch { /* fail-open：检索不可用保留占位 */ }
-  const { body } = renderIntent({ ...a, kbHits, kbFailNote });
-  fs.mkdirSync(path.dirname(a.output), { recursive: true });
-  fs.writeFileSync(a.output, body);
-  console.log('✅ 已生成 intent 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / 模块 ' + a.module + '）');
-}
-export default renderIntent;

package/templates/_agents/scripts/fill-intent.test.mjs

@@ -1,113 +0,0 @@
-// fill-intent.test.mjs — fill-intent 工具测试（2026-09-25 doc-fill-tools）
-// 方法：直接 import 模块调 renderIntent 拿字符串（不写盘），断言 frontmatter 字段 + 节数 + 枚举值合法性
-// 用法：node .agents/scripts/fill-intent.test.mjs
-import { renderIntent } from './fill-intent.mjs';
-
-let pass = 0, failCount = 0;
-function check(name, cond, detail = '') {
-  if (cond) { pass++; console.log('PASS ' + name); }
-  else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
-}
-
-// ---- 场景 1：L1 必填 frontmatter 字段都在 ----
-{
-  const { body } = renderIntent({ topic: 'test', module: 'pipeline', level: 'L1' });
-  const fm = body.match(/^---([\s\S]*?)---/);
-  check('S1 frontmatter 含状态 draft', /状态:\s*draft/.test(fm[1]));
-  check('S1 frontmatter 含级别 L1', /级别:\s*L1/.test(fm[1]));
-  check('S1 frontmatter 含日期 YYYY-MM-DD', /日期:\s*\d{4}-\d{2}-\d{2}/.test(fm[1]));
-  check('S1 frontmatter 含模块 pipeline', /模块:\s*pipeline/.test(fm[1]));
-  check('S1 frontmatter 含备注', /备注:/.test(fm[1]));
-}
-
-// ---- 场景 2：L2/L3 frontmatter 同样含完整字段 ----
-{
-  for (const level of ['L2', 'L3']) {
-    const { body } = renderIntent({ topic: 't', module: 'pipeline', level });
-    const fm = body.match(/^---([\s\S]*?)---/);
-    check('S2 级别 ' + level + ' frontmatter 完整', /状态:\s*draft/.test(fm[1]) && /级别:\s*/.test(fm[1]) && /日期:/.test(fm[1]));
-  }
-}
-
-// ---- 场景 3：非法 level 抛错（枚举严格）----
-{
-  let threw = false;
-  try { renderIntent({ topic: 't', module: 'pipeline', level: 'L9' }); } catch { threw = true; }
-  check('S3 非法 level 抛错', threw);
-}
-
-// ---- 场景 4：9 节正文齐 ----
-{
-  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
-  const expectedSections = ['背景与问题', '历史教训/防复发', '目标', '非目标', '约束', '影响面', '触达红线', '验收标准', '确认与复核'];
-  for (const s of expectedSections) check('S4 含节 ## ' + s, body.includes('## ' + s));
-  check('S4 共 9 节标题', (body.match(/^##\s/gm) || []).length === 9);
-}
-
-// ---- 场景 5：备注字段透传 ----
-{
-  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1', notes: '自定义备注' });
-  check('S5 自定义备注透传', body.includes('备注: 自定义备注'));
-  const { body: body2 } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
-  check('S5 默认备注占位', body2.includes('备注: <可选：附注自由文本，check-loop 不解析>'));
-}
-
-// ---- 场景 6：日期默认今日 ----
-{
-  const today = new Date().toISOString().slice(0, 10);
-  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1' });
-  check('S6 日期默认今日 ' + today, body.includes('日期: ' + today));
-  const { body: body2 } = renderIntent({ topic: 't', module: 'pipeline', level: 'L1', date: '2026-01-15' });
-  check('S6 自定义日期透传', body2.includes('日期: 2026-01-15'));
-}
-
-// ---- 场景 7：导出函数可单元测试 ----
-{
-  check('S7 renderIntent 是函数', typeof renderIntent === 'function');
-  // 边界：缺 topic 应返回字符串（渲染时缺 topic → topic 是 undefined 字符串，不抛错——按 design 透传）
-  const r = renderIntent({ module: 'pipeline', level: 'L1' });
-  check('S7 缺 topic 仍可渲染（透传设计）', typeof r.body === 'string' && r.body.includes('INTENT — undefined'));
-}
-
-// ---- 场景 8：risk_level 风险泳道字段（混合治理，= 级别，全枚举落 frontmatter）----
-{
-  for (const level of ['L1', 'L2', 'L3']) { // L0 已退役——L0 现走 renderIntent 抛「level 不在枚举」（S8b）
-    const { body } = renderIntent({ topic: 't', module: 'pipeline', level });
-    const fm = body.match(/^---([\s\S]*?)---/)[1];
-    check('S8 risk_level=' + level + ' 写入 frontmatter', new RegExp('^risk_level:\\s*' + level + '$', 'm').test(fm));
-  }
-}
-
-// ---- 场景 8b：L0 已退役（2026-10-13 自源仓收敛系列 1 回灌）→ renderIntent fail-loud ----
-{
-  let threw = '';
-  try { renderIntent({ topic: 't', module: 'pipeline', level: 'L0' }); } catch (e) { threw = e.message; }
-  check('S8b level=L0 → 抛 level 不在枚举 L1|L2|L3', threw.includes('level 不在枚举 L1|L2|L3'), threw);
-}
-
-// ---- 场景 9：预判键 scaffold（2026-10-13 自 Shipyard §25 prejudgment-ledger 回灌）----
-// intents≡require 恒真；level 与「级别」双写同值——与路由预判一致性检查对账零 WARN（advisory 灰度）
-{
-  for (const level of ['L1', 'L2', 'L3']) { // L0 已退役——L0 现走 renderIntent 抛「level 不在枚举」（S8b）
-    const { body } = renderIntent({ topic: 't', module: 'pipeline', level });
-    const fm = body.match(/^---([\s\S]*?)---/)[1];
-    check('S9 预判=' + level + ' scaffold（kind=require level=级别）',
-      new RegExp('^预判:\\s*kind=require level=' + level + '$', 'm').test(fm));
-  }
-}
-
-
-// ---- 历史坑注入 kbHits（2026-10-09 engine-quality-round3 W2）----
-{
-  const hits = ["📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB"];
-  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: hits });
-  check('kb 注入：命中行替换占位（含自动注入计数与 📄 原文）',
-    body.includes('检索结果（自动注入 1 条') && body.includes("📄 workflow/incidents/2026-10-01-aaa.md — closed · L2 · pipeline · 3 处命中 / 1KB") && !body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
-}
-{
-  const { body } = renderIntent({ topic: 't', module: 'pipeline', level: 'L2', kbHits: [] });
-  check('kb 零命中：保留占位（fail-open 口径）', body.includes("- 检索结果：`node .agents/scripts/kb-search.mjs \"<关键词>\" --type incidents` 命中结果"), body.slice(0, 200));
-}
-
-console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
-process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/fill-plan.mjs

@@ -1,79 +0,0 @@
-// flow-kit fill-plan：起草 plan 草稿（L1 Quick-Plan 三节 / L2-L3 完整 4 节）
-// 用法：node .agents/scripts/fill-plan.mjs --level L1 --topic "test" --output /tmp/x.md [--root <仓库根>]
-// L1：改动方案 + 约束与风险 + 验证计划（Quick-Plan 必填三节）
-// L1 直达（2026-10-13 自 Shipyard 回灌）：本 plan 即入口、不另立 intent；无同名 intent/incident 时起草门
-// 放行（--level L1）。修复类仍可另立 incident。L2/L3：改动方案 + 任务拆解 + 执行顺序 + 验证计划
-// 起草门（2026-09-30 stage-gate-machine）：output 落于工作区（路径含 workflow 段）时，须同主题入口已确认，
-// 且入口级别（取入口 frontmatter，非 --level）为 L2/L3 时同名 spec 已确认；未过 → 拒绝生成（exit 2）。
-import fs from 'node:fs';
-import path from 'node:path';
-import { ENUMS } from './workflow-enums.mjs';
-import { draftGateFor, resolveWorkspace } from './stage-gates.mjs';
-
-const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/workflow-enums.txt）
-
-function parseArgs(argv) {
-  const out = { topic: null, level: 'L1', output: null, root: null };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    const next = () => { const v = argv[++i]; if (v === undefined) return null; return v; };
-    if (a === '--topic') out.topic = next();
-    else if (a === '--level') out.level = next();
-    else if (a === '--output') out.output = next();
-    else if (a === '--root') out.root = next();
-  }
-  return out;
-}
-
-function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
-
-const L1_SECTIONS = [
-  { title: '改动方案', hint: '- <文件/组件>：<做什么；判据细节直接写进条目，如「L771 message.success 改『更新成功』」>\n\n> build.md 确认的改动清单确认后回填本节落盘（对话留痕仅供当次）——改动面 + 任务勾选态 + git status = 会话重入三锚（2026-10-11 session-context）。' },
-  { title: '约束与风险', hint: '- 约束：<对照 AGENTS.md 红线，说明如何满足；不许动什么>\n- 风险：<潜在影响 / 破坏性风险>' },
-  { title: '验证计划', hint: '- 静态门：项目构建命令（+ 项目测试命令，测试项目就绪后）\n- 前端：cd frontend && npm run build（vue-tsc）\n- UI：.agents/commands/test.md（涉及页面改动必走，headless Chrome 实测）\n- L2 追加：<契约 / 规则面比对：编码结果抽样 / 接口契约断言 / 口径对账>\n- L3 追加：<含 schema 变更：备份 + 回滚 SQL 就绪后执行；仅运行时 / 管线：回退上一 release tag + 配置开关预案>' },
-];
-
-const FULL_SECTIONS = [
-  L1_SECTIONS[0],
-  { title: '任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）', hint: '- [ ] 1. <任务>\n   - 判据：<怎样算完成；尽量对应一个测试或可复现操作>\n   - 风险：低 / 中 / 高（<原因>）\n   - 留痕：（勾选时回填 commit SHA / 测试名 / 实测输出）\n- [ ] 2. <任务>\n   - 判据：…\n   - 风险：…\n   - 留痕：…\n\n> 任务即勾选态（2026-10-11 session-context）：完成一项立刻勾选并回填留痕；压缩 / 新会话续作先读本表勾选态 + git status 重建进度，禁凭记忆补勾。' },
-  { title: '执行顺序（L2/L3 必填；L1 单文件微改动删本节）', hint: '<1 → 2 → 3；标注依赖关系>' },
-  L1_SECTIONS[2],
-];
-
-export function renderPlan({ topic, level = 'L1' }) {
-  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
-  const sections = level === 'L1' ? L1_SECTIONS : FULL_SECTIONS;
-  const fm = '---\n状态: draft\n级别: ' + level + '\n模块: pipeline\n---\n';
-  const entryLine = level === 'L1'
-    ? '对应入口：本 plan（L1 不再另立 intent）。修复类另保留 ../incidents/YYYY-MM-DD-<主题>.md\n对应 spec：省略（仅 L2/L3）\n\n'
-    : '对应入口：../intents/YYYY-MM-DD-<主题>.md 或 ../incidents/YYYY-MM-DD-<主题>.md（保留实际一项）\n对应 spec：../specs/YYYY-MM-DD-<主题>.md\n\n';
-  let body = '# PLAN — ' + topic + '\n\n<!-- 与 intents/ 或 incidents/ 下同名入口文档配对；L2/L3 必须先有 ../specs/ 同名 spec 确认通过；AI 起草、用户对话内确认后开工 -->\n<!-- frontmatter 受限子集（2026-09-13）：状态∈draft/approved/done/superseded/cancelled；级别∈L1/L2/L3（2026-10-13 L0 退役）；正文不再写状态/级别行 -->\n<!-- L1 快车道 (Quick-Plan)（2026-09-30 更新）：合并 Spec 与 Plan 核心。必填三节：[改动方案, 约束与风险, 验证计划]。仅多文件多步骤时保留任务拆解/执行顺序。L1 直达（2026-10-13 自 Shipyard 回灌）：本文件即入口，不另立 intent -->\n\n' + entryLine;
-  for (const { title, hint } of sections) {
-    body += '## ' + title + '\n\n' + hint + '\n\n';
-  }
-  body += '## 确认与复核\n\n> 确认 = 用户在对话内一句话通过；确认后本 plan 状态 draft → approved 并回填本节（确认环节的机器可见态），done 只在关单出现——禁从 draft 直跳 done（2026-09-22 papercut）。\n- 确认结果：approved（YYYY-MM-DD 用户对话内确认）；done（YYYY-MM-DD 关单，随入口文档置终态）\n- 确认门记录：plan 草稿全文过目 + 改动清单确认（build.md 两道门，逐次，不合并）\n- 复核：L1 不要求独立复核\n';
-  return { frontmatter: fm, body: fm + body, sections: sections.map((s) => s.title) };
-}
-
-const isMain = process.argv[1] && process.argv[1].endsWith('fill-plan.mjs');
-if (isMain) {
-  const a = parseArgs(process.argv.slice(2));
-  if (!a.topic || !a.output) fail('必填：--topic / --output；选填：--level（默认 L1）/ --root');
-  if (!LEVELS.includes(a.level)) fail('level 必须在 ' + LEVELS.join('|') + '：' + a.level);
-  const ws = resolveWorkspace(a.output, a.root);
-  if (ws) {
-    const gate = draftGateFor('plan', ws.root, ws.base, { level: a.level });
-    if (!gate.ok) {
-      console.error('❌ 起草门未过（stage-gates）：' + gate.reason);
-      console.error('   ' + gate.hint + '——本份未生成（确认前置后重跑本命令）');
-      process.exit(2);
-    }
-  } else {
-    console.error('ℹ️  未定位到工作区（output 路径不含 workflow/ 段）——按仓外草稿处理，跳过起草门前置校验');
-  }
-  const { body } = renderPlan(a);
-  fs.mkdirSync(path.dirname(a.output), { recursive: true });
-  fs.writeFileSync(a.output, body);
-  console.log('✅ 已生成 plan 草稿：' + a.output + '（状态 draft / 级别 ' + a.level + ' / ' + (a.level === 'L1' ? 'Quick-Plan 三节（plan 即入口）' : '完整 4 节') + '）');
-}
-export default renderPlan;