agentic-flow-kit 1.8.7 → 2.0.0

package/templates/_agents/scripts/workflow-board-server.mjs

@@ -1,393 +0,0 @@
-#!/usr/bin/env node
-// workflow 实时看板服务：本地只读 http + SSE 文件监听，可视化 AI 执行流程（intents/incidents/plans/specs）。
-// 用法：node .agents/scripts/workflow-board-server.mjs [--port 8933]；多项目并行请用 ensure-board.mjs 拉起（自动上探可用端口）
-// 零依赖（node:http/node:fs/node:path/node:url/node:child_process）；只读 workflow/ 与 git，仅绑 127.0.0.1。
-// API：GET /（看板页） /marked.min.js（vendor） /api/board /api/doc?file=<相对路径> /api/history?file=<相对路径> /api/events（SSE）
-//       /api/runs（pipeline-run 执行器 run 卡片列表） /api/run?file=<runId>.json（单 run 事件流）
-// 实时边界：文档内容与状态随落盘实时（fs.watch→SSE 推送）；git 历史仅含已提交记录（git 语义）。
-// 执行器面板（2026-10-04 board-run-panel）：只读 .agents/cache/pipeline-runs/*.json（脚本亲写的机器事实），
-//   不读 orchestration-runs.jsonl（宿主 AI 自报态，非验证态）；纯只读观测层，不启动/推进/中止 run。
-import http from 'node:http';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { execFile, spawnSync } from 'node:child_process';
-import { ENUMS } from './workflow-enums.mjs';
-import { stageBar } from './pipeline-run.mjs';
-
-const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
-const WORKFLOW = path.join(ROOT, 'workflow');
-const BOARD_DIR = path.join(ROOT, '.agents', 'board');
-const DOC_TYPES = ['intents', 'incidents', 'plans', 'specs'];
-const PIPELINE_RUNS = path.join(ROOT, '.agents', 'cache', 'pipeline-runs');
-
-const portArg = process.argv.indexOf('--port');
-const PORT = portArg > 0 ? Number(process.argv[portArg + 1]) || 8933 : 8933;
-const STARTED_AT = Date.now(); // 随 /api/board 自报（startedAt），供 ensure-board.mjs 判定旧代码重启，不碰进程启动时间 API
-
-// ---- front matter + 标题解析（对照 _TEMPLATE.md 受限子集：每行 `键: 值`）----
-function parseDoc(text) {
-  const meta = {};
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (m) {
-    for (const line of m[1].split(/\r?\n/)) {
-      const kv = line.match(/^(\S+):\s*(.*)$/);
-      if (kv) meta[kv[1].trim()] = kv[2].trim();
-    }
-  }
-  const h1 = text.match(/^# (.+)$/m);
-  let title = h1 ? h1[1] : '';
-  // 去掉 "# INTENT — " 前缀留主题：em/en dash（任意间距）或带空格连字符——裸连字符属 kebab-case，不截断（2026-09-24）
-  const dash = title.match(/\S+\s*(?:[—–]+|\s-\s)\s*(.+)$/);
-  if (dash) title = dash[1];
-  return { meta, title };
-}
-
-// ---- 验收标准 checkbox 统计：仅「验收标准」节内（至下一个 ## 标题），无该节返回 null ----
-// 节匹配对齐 check-loop 检查 8 口径（^\s*##\s[^#]*验收标准，2026-09-27 board-kb-p1——「## 三、验收标准」类标题此前识别不到）
-function parseAcceptance(text) {
-  const h = text.match(/^\s*##\s[^#]*验收标准.*$/m);
-  if (!h) return null;
-  const rest = text.slice(h.index + h[0].length);
-  const next = rest.match(/^## /m);
-  const section = next ? rest.slice(0, next.index) : rest;
-  const total = (section.match(/^\s*[-*] \[[ xX]\]/gm) || []).length;
-  if (!total) return null;
-  const done = (section.match(/^\s*[-*] \[[xX]\]/gm) || []).length;
-  return { done, total };
-}
-export { parseAcceptance };
-
-// ---- 执行器 run 文件解析（2026-10-04 board-run-panel）----
-// 只读 pipeline-runs/ 下的 run JSON（脚本亲写的机器事实，含 gate 真实退出码）。坏 JSON / 缺字段容错返回 null，
-// 由调用方跳过——run 文件写入原子化（临时文件+rename），读瞬间可能撞上 rename 前状态，不 500。
-export function parseRunFile(text) {
-  let j;
-  try {
-    j = JSON.parse(text);
-  } catch {
-    return null;
-  }
-  if (!j || typeof j !== 'object' || typeof j.runId !== 'string' || !j.runId) return null;
-  return j;
-}
-
-// 单 run 卡片（/api/runs 载荷元素）：runId / requirement / stage / stopType / updatedAt / triage / 事件数 / 阶段条
-export function runCard(run) {
-  const events = Array.isArray(run.events) ? run.events : [];
-  return {
-    runId: run.runId,
-    requirement: run.requirement || '',
-    stage: run.stage || '',
-    stopType: run.stopType || '',
-    updatedAt: run.updatedAt || run.createdAt || '',
-    triage: run.triage || null,
-    eventCount: events.length,
-    stageBar: stageBar(run),
-  };
-}
-
-// 扫 pipeline-runs/ 全部 run → 卡片数组，按 updatedAt 倒序（无目录/空目录 → []）
-export function scanRuns() {
-  if (!fs.existsSync(PIPELINE_RUNS) || !fs.statSync(PIPELINE_RUNS).isDirectory()) return [];
-  const cards = [];
-  for (const f of fs.readdirSync(PIPELINE_RUNS)) {
-    if (!f.endsWith('.json')) continue;
-    try {
-      const run = parseRunFile(fs.readFileSync(path.join(PIPELINE_RUNS, f), 'utf8'));
-      if (run) cards.push(runCard(run));
-    } catch {
-      // 读失败（瞬时占用等）跳过，等下次推送
-    }
-  }
-  return cards.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
-}
-
-// 路径白名单：resolve 后必须仍在 pipeline-runs/ 内且 .json 后缀（export 供测试直测白名单面）
-export function safeRunPath(rel) {
-  const abs = path.resolve(PIPELINE_RUNS, rel);
-  if (!abs.startsWith(PIPELINE_RUNS + path.sep) || !abs.endsWith('.json')) return null;
-  return abs;
-}
-
-// ---- 配对断裂检测：按完整文件名（含日期）聚合同族，异常卡附 alerts ----
-// 与 check-loop 检查 1 的 basename 同一口径。slug（去掉日期）只给界面分组，不参与配对。
-// 规则（看板为预警层、不阻断；枚举读单源 workflow-enums.txt）：
-//   孤儿 spec / 孤儿 plan（无同名 intent·incident 入口）；入口 done 但 plan 未终态（看板启发式）；
-//   入口缺 plan（intent 一律要求；incident 需非 legacy 且级别 L1/L2/L3）；L2/L3 入口缺同名 spec；
-//   spec L3 确认三件缺失（确认结果 / 确认时间 / 正文独立复核行）；
-//   状态不在全量枚举内或缺失；draft 是合法起点，提示「尚未确认」
-const PLAN_TERMINAL = ENUMS['doc.status.terminal'];
-const STATUS_ALL = {
-  intents: ENUMS['doc.status.all'],
-  specs: ENUMS['doc.status.all'],
-  plans: ENUMS['doc.status.all'],
-  incidents: ENUMS['incident.status.all'],
-};
-const NO_STATUS = '（未填）';
-const L3_REVIEW = /^- 独立复核：[ \t]*[^<\s]/m; // 正文独立复核行须有实质内容（对照 check-loop 锚定）
-
-export function detectAlerts(cards) {
-  const byName = new Map();
-  for (const c of cards) {
-    if (!byName.has(c.name)) byName.set(c.name, []);
-    byName.get(c.name).push(c);
-  }
-  for (const c of cards) {
-    const fam = byName.get(c.name) || [];
-    const types = new Set(fam.map((x) => x.type));
-    const alerts = [];
-    const isEntry = c.type === 'intents' || c.type === 'incidents';
-    // legacy 复盘件免配对类告警（口径同 check-loop）；孤儿 spec / 孤儿 plan 两条仍按 spec·plan 自身判定
-    const legacyIncident = c.type === 'incidents' && c.flow === 'legacy';
-    if (!STATUS_ALL[c.type].includes(c.status))
-      alerts.push(`状态不在枚举内：须为 ${STATUS_ALL[c.type].join('/')}（现 ${c.status === NO_STATUS ? '缺失' : c.status}）`);
-    else if (c.status === 'draft')
-      alerts.push('尚未确认');
-    if (c.type === 'specs' && !types.has('intents') && !types.has('incidents'))
-      alerts.push('孤儿 spec：无同名 intent/incident 入口');
-    if (c.type === 'plans' && !types.has('intents') && !types.has('incidents'))
-      alerts.push('孤儿 plan：无同名 intent/incident 入口');
-    if (c.type === 'plans') {
-      const entry = fam.find((x) => x.type === 'intents' || x.type === 'incidents');
-      if (entry && entry.status === 'done' && !PLAN_TERMINAL.includes(c.status))
-        alerts.push(`入口已 done，本 plan 未终态（现 ${c.status}）`);
-    }
-    if (isEntry && !legacyIncident && !types.has('plans') && (c.type === 'intents' || ['L1', 'L2', 'L3'].includes(c.level)))
-      alerts.push('入口缺 plan：无同名 plan');
-    if (isEntry && !legacyIncident && ['L2', 'L3'].includes(c.level) && !types.has('specs'))
-      alerts.push(`${c.level} 入口缺同名 spec`);
-    if (c.type === 'specs' && c.level === 'L3' && c.status !== 'draft' && !ENUMS['doc.status.abandoned'].includes(c.status)) {
-      if (c.confirm !== 'approved') alerts.push(`L3 确认缺失：确认结果须为 approved（现 ${c.confirm || '缺失'}）`);
-      if (!c.confirmTime) alerts.push('L3 确认缺失：须记录确认时间');
-      if (!c.hasReview) alerts.push('L3 复核缺失：须记录新会话独立复核结论');
-    }
-    if (alerts.length) c.alerts = alerts;
-  }
-}
-
-// ---- 文档作者：单次 git log 批量取「文件 → 最早提交者」（--reverse 首次出现即创建者）----
-function gitAuthors() {
-  return new Promise((resolve) => {
-    const GIT = process.platform === 'win32' ? 'git.exe' : 'git';
-    execFile(GIT, ['-c', 'core.quotepath=off', 'log', '--reverse', '--pretty=format:%x00%an', '--name-only', '--', 'workflow'], { cwd: ROOT, maxBuffer: 8 * 1024 * 1024 }, (err, stdout) => {
-      if (err) { console.error('git log 取作者失败（卡片 author 置空）:', err.message); return resolve(new Map()); }
-      const map = new Map();
-      let author = '';
-      for (const line of stdout.toString('utf8').split(/\r?\n/)) {
-        if (line.startsWith('\0')) author = line.slice(1);
-        else if (line.trim() && !map.has(line.trim())) map.set(line.trim(), author);
-      }
-      resolve(map);
-    });
-  });
-}
-
-// ---- 看板全量数据：每次请求现扫磁盘（数据量小，无缓存即无失效 bug）----
-async function scanBoard() {
-  const authors = await gitAuthors();
-  const cards = [];
-  const counts = {};
-  for (const type of DOC_TYPES) {
-    const dir = path.join(WORKFLOW, type);
-    const files = fs.readdirSync(dir).filter((f) => f.endsWith('.md') && !f.startsWith('_TEMPLATE'));
-    counts[type] = files.length;
-    for (const f of files) {
-      let text = '';
-      try { text = fs.readFileSync(path.join(dir, f), 'utf8'); } catch { continue; } // watch 触发瞬间可能正被写，跳过等下次推送
-      const { meta, title } = parseDoc(text);
-      const accept = parseAcceptance(text);
-      const name = f.slice(0, -3);
-      cards.push({
-        type,
-        file: `${type}/${f}`,
-        name,
-        slug: name.replace(/^\d{4}-\d{2}-\d{2}-/, ''),
-        date: meta['日期'] || name.slice(0, 10),
-        status: meta['状态'] || NO_STATUS,
-        level: meta['级别'] || '',
-        title: title || name,
-        author: authors.get(`workflow/${type}/${f}`) || '',
-        ...(accept ? { accept } : {}),
-        // 告警规则用到的 frontmatter / 正文锚点（对照 check-loop：legacy 豁免、L3 确认三件）
-        ...(meta['流程'] ? { flow: meta['流程'] } : {}),
-        ...(meta['确认结果'] ? { confirm: meta['确认结果'] } : {}),
-        ...(meta['确认时间'] ? { confirmTime: meta['确认时间'] } : {}),
-        ...(L3_REVIEW.test(text) ? { hasReview: true } : {}),
-      });
-    }
-  }
-  detectAlerts(cards);
-  cards.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type));
-  const loop = loopHardBlocks(); // hard-block 全局告警（单源 check-loop；null = 校验不可用）
-  return {
-    root: ROOT, pid: process.pid, startedAt: STARTED_AT, counts, cards,
-    loopHardBlocks: loop.blocks, loopNote: loop.note || undefined,
-    activeStatuses: [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']], // 枚举单源贯通前端（p2-batch2）
-  };
-}
-
-// ---- 路径白名单：resolve 后必须仍在 workflow/ 内 ----
-function safeDocPath(rel) {
-  const abs = path.resolve(WORKFLOW, rel);
-  if (!abs.startsWith(WORKFLOW + path.sep) || !abs.endsWith('.md')) return null;
-  return abs;
-}
-
-function gitLog(rel) {
-  return new Promise((resolve) => {
-    const GIT = process.platform === 'win32' ? 'git.exe' : 'git'; // Windows spawn 不补 .exe 扩展名
-    execFile(GIT, ['log', '--follow', '--date=short', '--pretty=%H|%ad|%s', '--', rel.split('/').join(path.sep)], { cwd: WORKFLOW, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
-      if (err) { console.error('git log 失败:', rel, err.message); return resolve([]); }
-      resolve(stdout.toString('utf8').split(/\r?\n/).filter(Boolean).map((l) => {
-        const [hash, date, ...rest] = l.split('|');
-        return { hash, date, subject: rest.join('|') };
-      }));
-    });
-  });
-}
-
-// ---- SSE 广播：fs.watch 防抖 500ms（AI 写盘常连发多事件，合并为一次推送）----
-const sseClients = new Set();
-let debounceTimer = null;
-function broadcast(event) {
-  for (const res of sseClients) { if (!res.destroyed) res.write(`event: ${event}\ndata: {}\n\n`); }
-}
-// 统一监听回调：workflow/ 文档 + pipeline-runs/ 执行器 run 文件任一变化 → 500ms 防抖广播 changed
-function onWatchChange() {
-  clearTimeout(debounceTimer);
-  debounceTimer = setTimeout(() => broadcast('changed'), 500);
-}
-function watchDir(dir) {
-  try {
-    const watcher = fs.watch(dir, { recursive: true }, onWatchChange);
-    watcher.on('error', (e) => { console.error(`fs.watch 失效（${dir}），已通知前端降级轮询:`, e.message); broadcast('watchdead'); });
-  } catch (e) {
-    // 同步失败（典型：目录不存在 ENOENT）与异步 error 同口径广播 watchdead——否则前端徽标滞留「实时」而推送已死
-    console.error(`fs.watch 初始化失败（${dir}，前端将走 60s 兜底轮询）:`, e.message);
-    broadcast('watchdead');
-  }
-}
-watchDir(WORKFLOW);
-// 25s 心跳：防半开连接；顺带清理已断开的 client
-setInterval(() => { for (const res of sseClients) { if (res.destroyed) sseClients.delete(res); else res.write(': ping\n\n'); } }, 25000).unref();
-
-const MIME = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8' };
-
-function sendJson(res, code, obj) {
-  // X-Frame-Options（p2-batch2）：本地只读服务拒绝被外站 iframe 嵌套（配合 Host 校验收敛攻击面）
-  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'X-Frame-Options': 'DENY' });
-  res.end(JSON.stringify(obj));
-}
-
-// ---- hard-block 告警单源（2026-09-27 board-kb-p1）----
-// 看板不再自建与 check-loop 平行的 hard 规则（此前四类缺失：回路断档/验收未对账/确认未对账/确认内容漂移，
-// test.md「双跑断言」曾必失败）——scanBoard 时 spawn check-loop.mjs，解析其 stderr hard-block 段为全局告警数组：
-// check-loop 未来新增 hard 项看板自动跟随，口径永不分叉。输出 banner 为稳定契约（check-loop 头注释明示
-// doctor/pre-push 按输出消费），本解析由双跑断言测试兜底格式漂移。
-export function parseLoopHardBlocks(stderrText) {
-  const text = String(stderrText || '');
-  const start = text.indexOf('HARD-BLOCK:');
-  if (start === -1) return [];
-  let seg = text.slice(start);
-  const warnIdx = seg.indexOf('WARN');
-  if (warnIdx > 0) seg = seg.slice(0, warnIdx);
-  return seg.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.startsWith('- ['));
-}
-
-function loopHardBlocks() {
-  // TTL 缓存（复核 P2-2 rider）：check-loop 独跑实测 ~10.5s 且 spawnSync 阻塞事件循环——搜索击键/SSE
-  // 连发场景下每请求全跑不可用。60s 内复用上次结果（loopHardBlocks 是预警层非门禁，陈旧 60s 可接受；
-  // 前端 loopNote 均如实展示）。进程级缓存，无失效盲区风险（比照 kb 两元组口径弱化声明：预警层容忍）。
-  const NOW = Date.now();
-  if (loopCache.at && NOW - loopCache.at < 60_000) return loopCache.v;
-  const v = (() => {
-    try {
-      const r = spawnSync(process.execPath, [path.join(ROOT, '.agents', 'scripts', 'check-loop.mjs')], { cwd: ROOT, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
-      if (r.error) return { blocks: null, note: `check-loop 不可执行：${r.error.message}` };
-      return { blocks: parseLoopHardBlocks(r.stderr || ''), note: '' };
-    } catch (e) {
-      return { blocks: null, note: e.message };
-    }
-  })();
-  loopCache.at = NOW; loopCache.v = v;
-  return v;
-}
-const loopCache = { at: 0, v: null };
-
-const server = http.createServer(async (req, res) => {
-  try {
-    // Host 校验（DNS rebinding 缓解，2026-09-27 board-kb-p1）：本地只读服务只认本机 Host
-    const host = String(req.headers.host || '');
-    if (host !== `127.0.0.1:${PORT}` && host !== `localhost:${PORT}`) {
-      return sendJson(res, 403, { error: `Host 不受信任（仅接受 127.0.0.1:${PORT} / localhost:${PORT}）` });
-    }
-    const url = new URL(req.url, `http://127.0.0.1:${PORT}`); // 畸形请求行抛错 → 400（P1-3：原在 try 外，单包可杀进程）
-    if (url.pathname === '/api/events') {
-      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
-      res.write('retry: 3000\n\n');
-      sseClients.add(res);
-      req.on('close', () => sseClients.delete(res));
-      return;
-    }
-    if (url.pathname === '/api/board') return sendJson(res, 200, await scanBoard());
-
-    // 执行器面板（2026-10-04 board-run-panel）：run 卡片列表 + 单 run 事件流
-    if (url.pathname === '/api/runs') return sendJson(res, 200, { cards: scanRuns() }); // 键名 cards 对齐 intent 2026-10-04-board-run-panel 验收#1
-    if (url.pathname === '/api/run') {
-      const rel = url.searchParams.get('file') || '';
-      const abs = safeRunPath(rel);
-      if (!abs) return sendJson(res, 403, { error: '路径不在 pipeline-runs/ 白名单内' });
-      try {
-        return sendJson(res, 200, { run: parseRunFile(fs.readFileSync(abs, 'utf8')) });
-      } catch (e) {
-        if (e && e.code === 'ENOENT') return sendJson(res, 404, { error: 'run 文件不存在' });
-        console.error(`读 run 失败（${rel}）:`, e.message); // 权限/占用等如实 500 留痕，不并成 404
-        return sendJson(res, 500, { error: `读 run 失败：${e.message}` });
-      }
-    }
-
-    if (url.pathname === '/api/doc' || url.pathname === '/api/history') {
-      const rel = url.searchParams.get('file') || '';
-      const abs = safeDocPath(rel);
-      if (!abs) return sendJson(res, 403, { error: '路径不在 workflow/ 白名单内' });
-      if (url.pathname === '/api/doc') {
-        try { return sendJson(res, 200, { text: fs.readFileSync(abs, 'utf8') }); }
-        catch { return sendJson(res, 404, { error: '文件不存在' }); }
-      }
-      return sendJson(res, 200, { commits: await gitLog(rel) });
-    }
-
-    // 静态文件：/ 与 /marked.min.js，同样防穿越
-    const rel = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
-    const abs = path.resolve(BOARD_DIR, rel);
-    if (!abs.startsWith(BOARD_DIR + path.sep) || !fs.existsSync(abs) || !fs.statSync(abs).isFile()) {
-      res.writeHead(404); return res.end('not found');
-    }
-    res.writeHead(200, { 'Content-Type': MIME[path.extname(abs)] || 'application/octet-stream' });
-    fs.createReadStream(abs).pipe(res);
-  } catch (e) {
-    if (e && e.code === 'ERR_INVALID_URL') {
-      return sendJson(res, 400, { error: `请求行/URL 非法：${e.message}` }); // 畸形请求不杀进程（P1-3）；只认 URL 错误码——其余 TypeError 是服务端缺陷，如实 500（复核 P2-1）
-    }
-    sendJson(res, 500, { error: e.message });
-  }
-});
-
-// 绑定失败明确退出（EADDRINUSE 常见于直跑撞端口；ensure-board 会先探活选端口，这里兜底可读报错）
-server.on('error', (e) => {
-  console.error(`workflow 看板启动失败（端口 ${PORT}${e.code === 'EADDRINUSE' ? ' 已被占用' : ''}）：${e.code || e.message}`);
-  process.exit(1);
-});
-
-// isMain 守卫（board-kb-p1）：parseLoopHardBlocks 可被测试 import（import 不 listen）
-const isMain = process.argv[1] && process.argv[1].endsWith('workflow-board-server.mjs');
-if (isMain) {
-  // run 目录缺失（.agents/cache/ 被 gitignore，全新装机无此目录）时 fs.watch 同步抛 ENOENT 且无重试——
-  // 补建空目录启用监听（pipeline-run 首跑本会建；失败不阻启动，由 watchDir catch 兜底广播 watchdead）
-  try { fs.mkdirSync(PIPELINE_RUNS, { recursive: true }); } catch { /* 竞态/权限等交给 watchDir 降级 */ }
-  watchDir(PIPELINE_RUNS); // 执行器 run 文件监听仅在作为服务运行时启动（import 不监听，避免测试进程挂起）
-  server.listen(PORT, '127.0.0.1', () => {
-    console.log(`workflow 看板: http://127.0.0.1:${PORT}  （Ctrl+C 停止；只读 workflow/ 与 pipeline-runs/，不写任何文件；run 目录缺失时补建空目录以启用监听）`);
-  });
-}

package/templates/_agents/scripts/workflow-board-server.test.mjs

@@ -1,201 +0,0 @@
-#!/usr/bin/env node
-// workflow-board-server 的纯函数测试（2026-09-27 board-kb-p1）
-// 核心 = 「双跑断言」的机器化：test.md 要求「涉及看板告警规则时，用同批 workflow fixture 双跑 check-loop
-// 与看板 /api/board，断言 hard-block 集合被看板告警覆盖（防口径分叉）」——此前是纯手工步骤且必失败
-// （四类 hard-block 看板无对应项）。告警单源化后看板直接消费 check-loop 输出，本测试把双跑断言固化为：
-// check-loop fixture 输出 → parseLoopHardBlocks → 断言四类 hard-block 全覆盖。
-// 断言：①parseLoopHardBlocks 合成样本四类齐；②真 fixture spawn check-loop → 解析覆盖四类（双跑断言）；
-//       ③空/无 hard-block → 空数组；④parseAcceptance 节匹配与 check-loop 检查 8 同口径。
-// 用法：node .agents/scripts/workflow-board-server.test.mjs（import 不 listen——server 有 isMain 守卫）
-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 { parseLoopHardBlocks, parseAcceptance, detectAlerts, parseRunFile, runCard, safeRunPath } from './workflow-board-server.mjs';
-import { computeFingerprint } from './confirm-doc.mjs';
-
-let pass = 0;
-let fail = 0;
-const check = (desc, cond, detail = '') => {
-  if (cond) { pass++; console.log(`PASS  ${desc}`); }
-  else { fail++; console.log(`FAIL  ${desc}${detail ? `\n${detail}` : ''}`); }
-};
-
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
-
-// ---- ①合成样本：四类 hard-block 各一 → 全解析 ----
-{
-  const sample = [
-    '闭环骨架断档（check-loop.sh）— HARD-BLOCK:',
-    '',
-    '- [配对断裂] intent 缺 plan:x.md',
-    '- [回路断档] inc 选「是」但未指明 intent 文件路径',
-    '- [验收未对账] done intent 缺「## 验收标准」节(勾验无从核对):x.md',
-    '- [确认未对账] x.md 状态 done 无用户确认记录',
-    '- [确认内容漂移] x.md done 后内容与确认台账不符',
-    '',
-    'WARN（advisory,不阻断）:',
-    '',
-    '- [WARN 状态未确认] plan 必须...',
-  ].join('\n');
-  const parsed = parseLoopHardBlocks(sample);
-  check('①合成样本解析 5 行 hard-block（WARN 段不混入）', parsed.length === 5, JSON.stringify(parsed));
-  check('①四类目标 hard-block 全覆盖（回路断档/验收未对账/确认未对账/确认内容漂移）',
-    ['回路断档', '验收未对账', '确认未对账', '确认内容漂移'].every((k) => parsed.some((l) => l.includes(k))),
-    JSON.stringify(parsed));
-}
-
-// ---- ②双跑（真 fixture）：spawn check-loop → parseLoopHardBlocks 覆盖四类 ----
-// **检查 8 换锚后的前置条件（2026-09-28 check8-git-anchor）**：检查 8 的生效日锚已从文件名前缀
-// 改为「文件首次加入 git 的日期」，故「验收未对账」这条 hard 的产出**需要 git 首次加入日期可判定**；
-// 非 git 仓会走存量口径、不再产出该 hard（有意语义，见 spec）。因此本场景需为**真 git 仓**——
-// 这不是放宽断言，而是补上使原断言（四类 hard-block 全覆盖）成立的前置；**断言强度与文案均未变**。
-{
-  const T = fs.mkdtempSync(path.join(os.tmpdir(), 'board-loop-test-'));
-  for (const s of ['intents', 'specs', 'plans', 'incidents']) fs.mkdirSync(path.join(T, 'workflow', s), { recursive: true });
-  fs.mkdirSync(path.join(T, '.agents'), { recursive: true });
-  fs.writeFileSync(path.join(T, '.agents', 'workflow-enums.txt'), [
-    '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 w = (rel, c) => fs.writeFileSync(path.join(T, rel), c);
-  // 回路断档：incident 三件套选「是」但引用 intent 不存在
-  w('workflow/incidents/2026-09-27-loop.md', '---\n状态: open\n级别: L1\n发现: 2026-09-27\n模块: pipeline\n---\n# INCIDENT — loop\n\n## 复盘三件套\n\n1. 结构性修复\n - 是否需要新 intent:\n - 是 → ../intents/2026-09-12-ghost.md\n2. 防复发验证\n3. 规范条目\n');
-  // 验收未对账：done intent 无验收标准节（锚 = git 首次加入日期 → 见上）
-  w('workflow/intents/2026-09-27-acc.md', '---\n状态: done\n级别: L1\n日期: 2026-09-27\n模块: pipeline\n---\n# INTENT — acc\n');
-  // 确认未对账：done 无指纹无台账
-  w('workflow/plans/2026-09-27-cg.md', '---\n状态: done\n级别: L1\n日期: 2026-09-27\n---\n# PLAN — cg\n');
-  // 确认内容漂移：done + 台账 prev + 落盘后篡改
-  {
-    const body = '\n## 验收标准（可测试）\n- [x] 用例通过（证据:fixture）\n';
-    const pre = `---\n状态: approved\n级别: L1\n日期: 2026-09-28\n确认指纹: ${'a'.repeat(16)}\n---\n# INTENT — drift\n${body}`;
-    const fp = computeFingerprint(pre);
-    w('workflow/intents/2026-09-28-drift.md', `---\n状态: done\n级别: L1\n日期: 2026-09-28\n确认指纹: ${fp.slice(0, 16)}\n---\n# INTENT — drift\n${body}确认后篡改行\n`);
-    fs.writeFileSync(path.join(T, '.agents', 'confirmations.jsonl'),
-      JSON.stringify({ ts: '2026-09-28T02:00:00.000Z', doc: 'workflow/intents/2026-09-28-drift.md', stage: 'done', fingerprint: fp, prev: 'approved', source: 'tty' }) + '\n');
-  }
-  // 配对齐 plan（避免无关阻断干扰可读性——配对断裂也会在 hard 段，不影响四类断言）
-  w('workflow/plans/2026-09-27-loop.md', '---\n状态: draft\n级别: L1\n---\n# PLAN — loop\n');
-  w('workflow/plans/2026-09-27-acc.md', '---\n状态: draft\n级别: L1\n---\n# PLAN — acc\n');
-
-  // 真 git 仓（使检查 8 的 git 锚可判定）——本地提交，不入任何远端
-  const G = process.platform === 'win32' ? 'git.exe' : 'git';
-  spawnSync(G, ['init', '-q'], { cwd: T });
-  spawnSync(G, ['add', '-A'], { cwd: T });
-  spawnSync(G, ['-c', 'user.email=t@t', '-c', 'user.name=t', 'commit', '-qm', 'fixture'], { cwd: T });
-
-  const r = spawnSync(process.execPath, [CHECK_LOOP], { cwd: T, encoding: 'utf8', env: { ...process.env, CHECK_LOOP_ROOT: T } });
-  const parsed = parseLoopHardBlocks(r.stderr || '');
-  check('②双跑：check-loop fixture exit 1（确有 hard-block）', r.status === 1, `exit=${r.status}\n${r.stderr}`);
-  check('②双跑断言：四类 hard-block 均被看板告警解析覆盖',
-    ['回路断档', '验收未对账', '确认未对账', '确认内容漂移'].every((k) => parsed.some((l) => l.includes(k))),
-    JSON.stringify(parsed));
-  fs.rmSync(T, { recursive: true, force: true });
-}
-
-// ---- ③空/无 hard-block → 空数组 ----
-{
-  check('③纯 WARN 输出 → 空数组', parseLoopHardBlocks('check-loop.sh WARN（advisory,不阻断）:\n\n- [WARN x]\n').length === 0);
-  check('③空输入 → 空数组', parseLoopHardBlocks('').length === 0);
-  check('③exit 0 场景（仅 WARN banner）→ 空数组', parseLoopHardBlocks('check-loop.sh WARN（advisory,不阻断）:\n\n- [WARN 引用断档] x\n').length === 0);
-}
-
-// ---- ④parseAcceptance 与 check-loop 检查 8 节匹配同口径 ----
-{
-  const std = '---\n状态: done\n---\n# I\n\n## 验收标准（可测试）\n- [x] 甲（证据:e）\n- [ ] 乙\n';
-  const numbered = '---\n状态: done\n---\n# I\n\n## 三、验收标准\n- [x] 甲（证据:e）\n- [ ] 乙\n';
-  check('④标准标题解析 1/2', parseAcceptance(std)?.done === 1 && parseAcceptance(std)?.total === 2, JSON.stringify(parseAcceptance(std)));
-  check('④带序号标题（## 三、验收标准）此前识别不到、现在同口径', parseAcceptance(numbered)?.total === 2, JSON.stringify(parseAcceptance(numbered)));
-  check('④无验收节 → null', parseAcceptance('---\n状态: done\n---\n# I\n') === null);
-}
-
-// ---- ⑤XSS 剥离口径（p2-batch2；复核 P2-3 备注）----
-// 注意：strip 与 board/index.html loadDoc 的剥离正则是【同款拷贝、非同源】——改 loadDoc 正则时本场景
-// 须同步（防回归能力受限为已知取舍：抽共享模块需前端打包链路，暂不做）。
-// activeStatuses 载荷断言未入本套件（server 侧 scanBoard 非纯函数不可直调）——
-// 以 /api/board 手工探活留证（复核已实测枚举贯通 + X-Frame-Options DENY）。
-{
-  const strip = (s) => s.replace(/<[^>]*>/g, '');
-  const evil = '正常文字 <img src=x onerror=alert(1)> 更多 <script>alert(2)</script> 结束';
-  check('⑤剥标签：img/script 标签清零，正文文字保留',
-    !/<(img|script)/.test(strip(evil)) && strip(evil).includes('正常文字') && strip(evil).includes('结束'),
-    strip(evil));
-  const md = '## 标题\n\n- 列表 **粗体** `code`\n\n[链接](intents/x.md)';
-  check('⑤markdown 语法不受剥标签影响', strip(md) === md);
-}
-
-// ---- ⑥按完整文件名配对；draft 是合法起点 ----
-{
-  const has = (card, text) => (card.alerts || []).some((a) => a.includes(text));
-  const card = (over) => ({
-    type: 'intents', name: '2026-09-01-topic', slug: 'topic', status: 'approved', level: 'L1',
-    ...over,
-  });
-  const paired = card();
-  const plan = card({ type: 'plans', status: 'approved' });
-  const other = card({ name: '2026-09-02-topic', status: 'draft' });
-  detectAlerts([paired, plan, other]);
-  check('⑥同 slug 不同日期：有同名 plan 的 intent 不报缺 plan', !has(paired, '入口缺 plan'));
-  check('⑥同 slug 不同日期：没有同名 plan 的 intent 报缺 plan', has(other, '入口缺 plan'), JSON.stringify(other.alerts));
-  check('⑥draft 提示尚未确认，不报非法枚举', has(other, '尚未确认') && !has(other, '状态不在枚举内'), JSON.stringify(other.alerts));
-  const okIntent = card({ name: '2026-09-03-keep', status: 'approved' });
-  const okPlan = card({ type: 'plans', name: '2026-09-03-keep', status: 'approved' });
-  detectAlerts([okIntent, okPlan]);
-  check('⑥approved 同名配对：无非法枚举、无尚未确认、无缺 plan',
-    !has(okIntent, '状态不在枚举内') && !has(okIntent, '尚未确认') && !has(okIntent, '入口缺 plan'),
-    JSON.stringify(okIntent.alerts));
-  const doneIntent = card({ name: '2026-09-04-done', status: 'done' });
-  const draftPlan = card({ type: 'plans', name: '2026-09-04-done', status: 'draft' });
-  detectAlerts([doneIntent, draftPlan]);
-  check('⑥入口 done 而同名 plan 仍是 draft：plan 报未终态', has(draftPlan, '未终态'), JSON.stringify(draftPlan.alerts));
-  const bogus = card({ name: '2026-09-05-bad', status: 'nope' });
-  detectAlerts([bogus]);
-  check('⑥未知状态仍报不在枚举内', has(bogus, '状态不在枚举内'), JSON.stringify(bogus.alerts));
-}
-
-// ---- ⑦执行器面板纯函数（2026-10-04 board-run-panel）----
-{
-  // 真实 run 文件形态（对齐 .agents/cache/pipeline-runs/20261002-1819-runtime-env-md-c2ju.json）
-  const real = {
-    runId: '20261002-1819-runtime-env-md-c2ju',
-    requirement: '在 runtime-env.md 补记 pipeline-run 运行态',
-    stage: 'done',
-    stopType: 'done',
-    triage: { kind: 'require', level: 'L1', module: 'pipeline', topic: 'runtime-note', decidedBy: 'ai' },
-    updatedAt: '2026-10-02T10:19:22.566Z',
-    events: [
-      { t: '2026-10-02T10:19:02.680Z', type: 'run-created', requirement: 'x' },
-      { t: '2026-10-02T10:19:02.682Z', type: 'work-order', id: 1, kind: 'triage' },
-      { t: '2026-10-02T10:19:19.512Z', type: 'gate', cmd: 'git status --porcelain', exit: 0, ms: 58 },
-      { t: '2026-10-02T10:19:22.566Z', type: 'commit', sha: '37b552a', subject: 'docs(pipeline): x' },
-      { t: '2026-10-02T10:19:22.566Z', type: 'done' },
-    ],
-  };
-  check('⑦parseRunFile：真实 run JSON 解析成功', parseRunFile(JSON.stringify(real))?.runId === real.runId);
-  check('⑦parseRunFile：坏 JSON → null', parseRunFile('{oops') === null);
-  check('⑦parseRunFile：非对象/缺 runId → null', parseRunFile('"str"') === null && parseRunFile('{}') === null && parseRunFile('{"a":1}') === null);
-  const card = runCard(real);
-  check('⑦runCard：字段映射齐全', card.runId === real.runId && card.stage === 'done' && card.stopType === 'done' && card.eventCount === 5 && card.requirement === real.requirement);
-  check('⑦runCard：updatedAt 取 updatedAt', card.updatedAt === real.updatedAt);
-  // 阶段条复用 pipeline-run stageBar（done → Plan/Design/Build 全 [✓]，Test 为当前 [●]）
-  check('⑦stageBar：done run 前三个阶段 [✓] 且 Test 为当前', card.stageBar.includes('[✓Plan]') && card.stageBar.includes('[✓Design]') && card.stageBar.includes('[✓Build]') && card.stageBar.includes('[●Test]'));
-  // 空事件容错
-  const empty = runCard({ runId: 'r1', requirement: '', stage: 'triage', stopType: 'work-order', events: null });
-  check('⑦runCard：events 非数组容错为 0', empty.eventCount === 0);
-  // safeRunPath 路径穿越白名单（2026-10-04 review-fix-batch：安全相关函数此前无测试；用例只用平台无关的正向斜杠相对路径）
-  check('⑦safeRunPath：合法 runId.json 通过', typeof safeRunPath('20261002-1819-x-abcd.json') === 'string' && safeRunPath('20261002-1819-x-abcd.json').endsWith('.json'));
-  check('⑦safeRunPath：.. 穿越拒绝', safeRunPath('../../package.json') === null && safeRunPath('a/../../package.json') === null);
-  check('⑦safeRunPath：根相对路径拒绝', safeRunPath('/etc/passwd') === null);
-  check('⑦safeRunPath：非 .json 拒绝', safeRunPath('20261002-1819-x-abcd.md') === null && safeRunPath('20261002-1819-x-abcd') === null);
-}
-
-console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);