agentic-flow-kit 1.8.7 → 2.0.0

package/templates/engine/.agents/scripts/dream-run.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+// dream-run — 离线梦境最小审计（2026-11-11，对照 Anthropic《The components of agent memory》）
+// 定位：可手动/定时触发的只读审计编排器。不发明新判定，只编排现有脚本完成「离线梦境」
+//   职能：修剪陈旧(A) / 拓扑修复(B) / Judge 对账(C) / 错类候选(D) / 记忆负债(E) /
+//   冷数据候选(E2)，末尾追加 AI Judge 阶段(F)：抽取活跃 workflow 文档 + git 历史 + 确认/验证台账证据，
+//   生成抽样审计简报（tmp/dream-judge-brief-<date>.md），交由主智能体在下个会话委托
+//   independent-reviewer 角色核验——脚本只做采样与证据收集，判断由 AI 执行。
+//
+// 用法：
+//   node .agents/scripts/dream-run.mjs                     # dry-run：只读审计 + AI 抽样简报
+//   node .agents/scripts/dream-run.mjs --execute           # 执行安全修复（仅归档 + 重生成索引）
+//   node .agents/scripts/dream-run.mjs --report <path>     # 自定义报告路径（默认 tmp/dream-report-<date>.md）
+//   node .agents/scripts/dream-run.mjs --judge-count <N>   # AI 抽样文档数（默认 3，0 = 跳过）
+//   node .agents/scripts/dream-run.mjs --no-judge          # 跳过 AI Judge 阶段
+//
+// 安全边界：
+//   - 默认 dry-run 零写操作；--execute 只做「终态件归档 + 索引重生成」，不改写任何文档内容
+//   - 不自动 commit / push（根 AGENTS.md 禁令）；报告落 tmp/（gitignore）
+//   - 错类合并、指纹异常等需判断项只出候选，由主智能体/用户处置
+// 单源口径：全部阶段复用现有脚本，无新台账、新规则、新常驻成本；所有 spawn 带 windowsHide
+//   （Windows 无控制台父进程派生控制台子进程会闪窗，见 runtime-env.md §6.4）。
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = process.env.CHECK_LOOP_ROOT || path.resolve(SCRIPT_DIR, '..', '..');
+const TMP_DIR = path.join(ROOT, 'tmp');
+
+// ---------- 参数解析 ----------
+const args = process.argv.slice(2);
+const EXECUTE = args.includes('--execute');
+const NO_JUDGE = args.includes('--no-judge');
+const reportIdx = args.indexOf('--report');
+const REPORT_PATH = reportIdx >= 0 && args[reportIdx + 1]
+  ? path.resolve(ROOT, args[reportIdx + 1])
+  : path.join(TMP_DIR, `dream-report-${today()}.md`);
+const judgeIdx = args.indexOf('--judge-count');
+const JUDGE_COUNT = judgeIdx >= 0 ? Number.parseInt(args[judgeIdx + 1], 10) : 3;
+if (Number.isNaN(JUDGE_COUNT) || JUDGE_COUNT < 0) {
+  console.error('--judge-count 须为非负整数');
+  process.exit(2);
+}
+
+// ---------- 工具 ----------
+function today() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function run(relScript, scriptArgs = [], opts = {}) {
+  const r = spawnSync('node', [relScript, ...scriptArgs], {
+    encoding: 'utf8',
+    cwd: ROOT,
+    windowsHide: true,
+    ...opts,
+  });
+  if (r.error) return { ok: false, out: '', err: r.error.message, status: -1 };
+  return { ok: r.status === 0, out: (r.stdout || '') + (r.stderr || ''), status: r.status };
+}
+
+function git(args, opts = {}) {
+  const r = spawnSync('git', args, { encoding: 'utf8', cwd: ROOT, windowsHide: true, ...opts });
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), err: (r.stderr || '').trim() };
+}
+
+const lines = [];
+const add = (s = '') => lines.push(s);
+const section = (t) => { lines.push(`\n## ${t}\n`); };
+
+// 非终态即活跃：intents/specs/plans 终态 = done/superseded/cancelled；incidents 终态 = closed
+const TERMINAL = new Set(['done', 'superseded', 'cancelled', 'closed']);
+const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
+
+// ---------- 阶段 A：终态件归档 ----------
+section('A. 终态件归档（archive-sweep --window 21）');
+const sweep = run(path.join('.agents', 'scripts', 'archive-sweep.mjs'),
+  ['--window', '21', ...(EXECUTE ? ['--execute'] : [])]);
+add(sweep.ok ? sweep.out.trim() : `⚠ archive-sweep 失败: ${sweep.err || sweep.out}`);
+
+// ---------- 阶段 B：索引漂移 ----------
+section('B. 索引漂移（--execute 时重生成）');
+for (const [name, gen] of [
+  ['workflow-index', '.agents/scripts/gen-workflow-index.mjs'],
+  ['engine-map', '.agents/scripts/gen-engine-map.mjs'],
+]) {
+  const check = run(gen, ['--check']);
+  if (check.ok) {
+    add(`- ${name}: 一致`);
+  } else {
+    add(`- ${name}: 漂移\n  ${check.out.split('\n').filter(Boolean).slice(0, 10).join('\n  ')}`);
+    if (EXECUTE) {
+      const regen = run(gen, []);
+      add(regen.ok ? '  → 已重生成' : `  → 重生成失败: ${regen.err || regen.out}`);
+    } else {
+      add('  → 待重生成（--execute）');
+    }
+  }
+}
+const wiki = run('.agents/scripts/verify-wiki-consistency.mjs', []);
+add(wiki.ok ? '- wiki: 三方一致' : `- wiki: 不一致\n  ${wiki.out.split('\n').filter(Boolean).slice(0, 10).join('\n  ')}`);
+
+// ---------- 阶段 C：全量对账（只报告） ----------
+section('C. 全量对账（CHECK_LOOP_FULL=1，hard 6 段）');
+const loop = run('.agents/scripts/check-loop.mjs', [], { env: { ...process.env, CHECK_LOOP_FULL: '1' } });
+if (loop.ok) {
+  add('- check-loop: 全绿');
+} else {
+  add(`- check-loop: 退出码 ${loop.status}（有阻断/告警）`);
+  const blk = loop.out.split('\n').filter((l) => /BLOCK|block/i.test(l)).slice(0, 15);
+  if (blk.length) add(`  BLOCK 摘要:\n  ${blk.join('\n  ')}`);
+  add('  明细: node .agents/scripts/check-loop.mjs（或 tmp/check-loop-warn.log）');
+}
+
+// ---------- 阶段 D：错类候选（只报告，沿用 papercut-fix §0 阈值 ≥3 次） ----------
+section('D. 错类候选（agg-judgments --retire-candidates）');
+const cand = run('.agents/scripts/agg-judgments.mjs', ['--retire-candidates']);
+add(cand.ok ? cand.out.trim() : `⚠ 候选统计失败: ${cand.err || cand.out}`);
+
+// ---------- 阶段 E：常驻面预算（只报告） ----------
+section('E. 常驻面预算（rule-budget --all）');
+const budget = run('.agents/scripts/rule-budget.mjs', ['--all']);
+add(budget.ok ? '- 预算: OK' : `- 预算超限:\n  ${budget.out.split('\n').filter(Boolean).slice(0, 10).join('\n  ')}`);
+
+// ---------- 阶段 E2：冷数据候选（只报告，agg-kb-usage --stale-days 90） ----------
+section('E2. 冷数据候选（agg-kb-usage --stale-days 90）');
+const cold = run('.agents/scripts/agg-kb-usage.mjs', ['--stale-days', '90']);
+add(cold.ok ? cold.out.trim() : `⚠ 冷数据统计失败: ${cold.err || cold.out}`);
+
+// ---------- 阶段 F：AI Judge 抽样简报 ----------
+let judgeBriefPath = '';
+if (!NO_JUDGE && JUDGE_COUNT > 0) {
+  section('F. AI Judge 抽样审计');
+  judgeBriefPath = path.join(TMP_DIR, `dream-judge-brief-${today()}.md`);
+  const sample = collectJudgeSamples(JUDGE_COUNT);
+  if (sample.docs.length === 0) {
+    add('- 无活跃 workflow 文档，跳过抽样');
+  } else {
+    writeJudgeBrief(judgeBriefPath, sample);
+    add(`- 已抽取 ${sample.docs.length} 份活跃文档，证据简报: ${path.relative(ROOT, judgeBriefPath)}`);
+    add('- 下一步: 主智能体读取简报，按末尾模板委托 independent-reviewer 核验');
+  }
+}
+
+// ---------- 报告落盘 ----------
+fs.mkdirSync(TMP_DIR, { recursive: true });
+const header = `# 离线梦境审计报告 ${today()}\n> 生成: node .agents/scripts/dream-run.mjs${EXECUTE ? ' --execute' : ''}（默认 dry-run）\n`;
+fs.writeFileSync(REPORT_PATH, header + lines.join('\n') + '\n', 'utf8');
+console.log(`报告已写入 ${path.relative(ROOT, REPORT_PATH)}`);
+if (judgeBriefPath && fs.existsSync(judgeBriefPath)) {
+  console.log(`AI Judge 简报已写入 ${path.relative(ROOT, judgeBriefPath)}`);
+}
+
+// ---------- 阶段 F 辅助：采样与证据收集 ----------
+
+function collectJudgeSamples(maxCount) {
+  const docs = [];
+  for (const type of DOC_TYPES) {
+    const dir = path.join(ROOT, 'workflow', type);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!f.endsWith('.md') || f.startsWith('_')) continue;
+      const p = path.join(dir, f);
+      const raw = fs.readFileSync(p, 'utf8');
+      const fm = parseFrontmatter(raw);
+      if (!fm) continue;
+      const status = fm['状态'] || '';
+      if (TERMINAL.has(status)) continue;
+      docs.push({
+        type,
+        file: f,
+        path: p,
+        status,
+        date: fm['日期'] || fm['发现'] || '',
+        module: fm['模块'] || '',
+        level: fm['级别'] || '',
+        title: (raw.match(/^#\s+(.+)$/m) || [])[1] || f,
+        body: raw,
+      });
+    }
+  }
+  // 老活优先（最可能沉淀过期/错误笔记）
+  docs.sort((a, b) => (a.date || '9999').localeCompare(b.date || '9999'));
+  return { docs: docs.slice(0, maxCount) };
+}
+
+function parseFrontmatter(raw) {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const fm = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    const i = line.indexOf(':');
+    if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+  }
+  return fm;
+}
+
+function extractSections(raw) {
+  const KEYS = ['背景', '目标', '非目标', '根因', '为什么没拦住', '复盘三件套', '复盘', '验收标准', '影响面'];
+  const out = [];
+  const bodyLines = raw.split(/\r?\n/);
+  for (let i = 0; i < bodyLines.length; i++) {
+    const m = bodyLines[i].match(/^##{1,3}\s+(.+)$/);
+    if (!m) continue;
+    const h = m[1].trim();
+    if (!KEYS.some((k) => h.includes(k))) continue;
+    const block = [];
+    for (let j = i + 1; j < bodyLines.length; j++) {
+      if (/^##{1,3}\s+/.test(bodyLines[j])) break;
+      block.push(bodyLines[j]);
+    }
+    const text = block.join('\n').trim();
+    if (text) out.push(`### ${h}\n${text}`);
+  }
+  return out;
+}
+
+function gatherEvidence(doc) {
+  const ev = [];
+  // L1 transcripts：git 历史
+  const log = git(['log', '--oneline', '-8', '--', doc.path]);
+  if (log.ok && log.out) ev.push(`### git 历史（近 8 条）\n${log.out}`);
+
+  // 确认台账（分片优先 + 主台账按文档基名检索）
+  const base = path.basename(doc.path, '.md');
+  let conf = '';
+  const shard = path.join(ROOT, '.agents', 'confirmations.d', `${base}.jsonl`);
+  if (fs.existsSync(shard)) conf += fs.readFileSync(shard, 'utf8');
+  const main = path.join(ROOT, '.agents', 'confirmations.jsonl');
+  if (fs.existsSync(main)) {
+    conf += fs.readFileSync(main, 'utf8').split(/\r?\n/).filter((l) => l.includes(base)).join('\n');
+  }
+  const confRows = conf.split(/\r?\n/).filter(Boolean);
+  if (confRows.length) ev.push(`### 确认台账\n${confRows.slice(0, 6).join('\n')}`);
+
+  // 验证流水（同名检索，可能有）
+  const verif = path.join(ROOT, '.agents', 'verifications.jsonl');
+  if (fs.existsSync(verif)) {
+    const rows = fs.readFileSync(verif, 'utf8').split(/\r?\n/).filter((l) => l.includes(base));
+    if (rows.length) ev.push(`### 验证流水（同名命中 ${rows.length} 行，示 3）\n${rows.slice(0, 3).join('\n')}`);
+  }
+  return ev;
+}
+
+function writeJudgeBrief(briefPath, sample) {
+  const parts = [];
+  parts.push(`# AI Judge 抽样审计简报 ${today()}`);
+  parts.push('');
+  parts.push('> 由 dream-run.mjs 阶段 F 生成：抽样活跃 workflow 文档 + 原始证据（git 历史 / 确认台账 / 验证流水）。');
+  parts.push('> 判断由主智能体委托 independent-reviewer 角色执行，本简报只做采样与证据收集。');
+  parts.push('');
+  sample.docs.forEach((doc, i) => {
+    parts.push('---');
+    parts.push('');
+    parts.push(`## 样本 ${i + 1}: ${doc.title}`);
+    parts.push('');
+    parts.push(`- 路径: workflow/${doc.type}/${doc.file}`);
+    parts.push(`- 状态: ${doc.status} ｜ 级别: ${doc.level || '-'} ｜ 日期: ${doc.date || '-'} ｜ 模块: ${doc.module || '-'}`);
+    const secs = extractSections(doc.body);
+    if (secs.length) parts.push('', secs.join('\n\n'));
+    const ev = gatherEvidence(doc);
+    if (ev.length) parts.push('', ev.join('\n\n'));
+  });
+  parts.push('');
+  parts.push('---');
+  parts.push('');
+  parts.push('## Judge 委托模板');
+  parts.push('');
+  parts.push('以下内容供主智能体复制给 independent-reviewer：');
+  parts.push('```text');
+  parts.push(`任务：核验以下 ${sample.docs.length} 份活跃 workflow 文档的声明是否被证据支持。`);
+  parts.push('范围：本简报中的全部样本。');
+  parts.push('方法：');
+  parts.push('1. 逐份读文档正文（workflow/<type>/<file> 原始文件）；');
+  parts.push('2. 对照 git 历史、确认台账（.agents/confirmations.d/ 与 confirmations.jsonl）、验证流水（verifications.jsonl）；');
+  parts.push('3. 重点核验「验收标准」勾验声明、incident 的根因与复盘陈述、plan 的验证计划引用；');
+  parts.push('4. 输出：每份文档给出 BLOCK（证据不支持/矛盾）/ WARN（证据缺失或过期）/ OK，附 file:line 与证据指针。');
+  parts.push('约束：只读不改；不确定写「数据不足」，禁止编造证据。');
+  parts.push('```');
+  fs.mkdirSync(path.dirname(briefPath), { recursive: true });
+  fs.writeFileSync(briefPath, parts.join('\n') + '\n', 'utf8');
+}

package/templates/engine/.agents/scripts/ensure-board.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// ensure-board.mjs — workflow 看板按需手动拉起（默认不自动开启；只起不关：OS 重启即天然回收，无需 stop/status）
+// 跨平台单入口（零依赖，Windows/Linux/macOS 同一脚本，取代旧 ensure-board.ps1）：
+//   端口语义（2026-10-22 board-slot-strict，与前端/端到端同式）：基端口 = --port 显式（绝对值，不吃槽位偏移）
+//   > 配置基线（init 询问值，存于 engine.json）> 8933，再按 SHIPYARD_SLOT 偏移 slot×10（缺省 0 = 8933）；
+//   strict——只绑槽位端口（不漂移）：活的本项目看板 → 复用（代码文件晚于服务端 startedAt = 旧代码自动 kill 重启）；
+//   他人进程（其他项目看板 / 非看板服务）不动手不 kill，直接失败退出并提示（旧上探窗口 10 会漂进相邻槽位服务口）。
+//   端口解析单源 board-port.mjs（本文件 import；槽位派生仍单源 scripts/verify/e2e/ports.mjs，端口字面量不落脚本）。
+// 身份与陈旧判定全部来自 /api/board 自报（pid/startedAt）——不碰 OS 专属的端口属主 / 进程启动时间 API。
+// 用法：node .agents/scripts/ensure-board.mjs [--port 8933] [--no-open]（多 worktree 并行设 SHIPYARD_SLOT=<n>）
+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';
+import { resolveBoardPort } from './board-port.mjs';
+
+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'), // 前端运行时依赖（同盲区）
+  path.join(SCRIPT_DIR, 'dev-tour-model.mjs'),   // server import 即加载（dev-tour 模型）
+]; // 任一更新都算「旧代码」
+const WINDOW = 1; // strict（2026-10-22 board-slot-strict）：只试槽位端口一口；旧上探窗口 10 会漂进相邻槽位服务口（如 8942=槽位1 API）
+
+// ---- 参数与基端口 ----
+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));
+
+const BASE_PORT = resolveBoardPort({ explicit: portArg, root: ROOT }); // 基端口解析单源 board-port.mjs（含显式端口绝对值不吃槽位偏移语义）
+
+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 不进连接池，无残留句柄
+// 超时 25s（board-slot-strict 实测踩坑×2）：**旧版服务端**（去阻塞改造前）的 /api/board 在请求路径
+// 同步跑 check-loop（全量门实测 17.4s）——闲置后首包阻塞整个事件循环，探测窗口必须盖过旧版最坏冷启动
+// 才能把自己人认出来（15s 实测仍不够）。新版服务端 /api/board 恒即时返回，25s 仅为旧版兼容余量。
+function httpProbe(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/api/board', headers: { Connection: 'close' }, timeout: 25000 }, (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} 被他人进程占用（strict 不漂移不 kill）：${skipped.join('；')}；换 SHIPYARD_SLOT 槽位或 --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 主路径；
+  //   2026-10-22 board-slot-strict 再实测：闲置后冷跑 check-loop spawnSync 阻塞事件循环可达 ~17s
+  //   （全量门实测 check-loop 17.4s），15s 窗口仍会误报「未能确认为本项目」——扩至 25s）：
+  //   ① 子进程已退出（EADDRINUSE 自杀）→ 端口确被抢占，如实报告；
+  //   ② 25s 内轮询 probeBoard 直到自报 pid === 自家 pid（长超时容忍冷启动）；
+  //   ③ 轮询超时仍不一致 → 如实报告未确认为本项目（不误称他人抢占）。
+  const deadline = Date.now() + 25000;
+  let mine = null;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      console.log(`board: 端口 ${port} 在启动窗口被他人进程抢占（本项目进程已退出 exitCode=${child.exitCode}）——本轮未拉起本项目看板，重跑 ensure-board 即可（strict：不自动换端口）`);
+      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/engine/.agents/scripts/failure-attribution.mjs

@@ -0,0 +1,11 @@
+// failure-attribution.mjs — 门禁失败归因（env / flaky / real）
+// 目的：红单必须可信。共享 dev 库死锁、缺依赖/缺二进制是环境假红；把它们与真回归分开，
+//   AI 才不会在假红上反复重跑或开始考虑 --no-verify（红线）。归因只标注，不改裁决。
+// 口径：env 优先（缺件/网络/依赖），其次 flaky（已知并发/锁/句柄争用签名），否则 real。
+// 诚实边界：签名匹配是启发式——归因写进失败行供人复核，不自动降档（降档须 owner 裁决 + 复评日）。
+export function classifyFailure(text) {
+  const s = String(text || '');
+  if (/NU1100|ECONNREFUSED|ENOTFOUND|EAI_AGAIN|Cannot find module|MODULE_NOT_FOUND|not recognized as an internal|command not found|ENOENT[^\n]*node_modules|gitleaks.*(?:not found|未安装)|eslint.*(?:not found|未安装)/i.test(s)) return 'env';
+  if (/Msg 1205|deadlock|死锁|Execution Timeout|syscall: rm|resource temporarily unavailable|EAGAIN/i.test(s)) return 'flaky';
+  return 'real';
+}

package/templates/engine/.agents/scripts/fill-intent.mjs

@@ -0,0 +1,60 @@
+// fill-intent：起草 intent 草稿（背景与问题/历史教训防复发/目标/非目标/约束/影响面/触达红线/验收标准 8 节正文 + 确认与复核 共 9 节）
+// 读 workflow/intents/_TEMPLATE.md 的节标题 → 输出符合 frontmatter 受限子集（5 字段）的草稿到指定文件
+// 用法：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';
+
+const TODAY = new Date().toISOString().slice(0, 10);
+const LEVELS = ENUMS['level.all']; // 级别词表单源（.agents/config/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` 命中结果；按改动文件找同类用 `--files <路径,...>`（词元 OR）\n- 避坑指南：<针对历史根因，本次如何预防/规避>' },
+  { title: '目标', hint: '- <可验证的目标>' },
+  { title: '非目标（L1 微改动无实质内容可删本节，不硬填）', hint: '- <明确不做的，防止范围蔓延>' },
+  { title: '约束（L1 微改动无实质内容可删本节，不硬填）', hint: '- <复用什么、不许动什么>' },
+  { title: '影响面', hint: '- 模块：<词表之一，见 .agents/config/workflow-modules.txt>\n- 数据库：无 / <表名>（涉及 schema 变更 $\rightarrow$ L3；无 schema 的运行时 / 管线结构面亦为 L3，判据见 .agents/commands/new-task.md §1 风险定级）\n- 前端页面：<路由或组件，无则删本行>' },
+  { title: '触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 或 Quick-Plan 中说明）', hint: '- [ ] <按本项目 AGENTS.md 红线逐行补；无则删本行>\n- [ ] 规则 / 契约变更（编码权威 / 共享契约 / 接口签名 / 既有参数语义 / 全局口径）$\rightarrow$ 级别至少 L2\n- [ ] schema / 迁移 SQL / DI 链 / 认证与中间件管线 $\rightarrow$ 级别 L3\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。' },
+];
+
+export function renderIntent({ topic, module, level, notes, date = TODAY }) {
+  if (!LEVELS.includes(level)) throw new Error('level 不在枚举 ' + LEVELS.join('|') + '：' + level);
+  const fm = '---\n状态: draft\n级别: ' + 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；check-loop 只扫 frontmatter 取机器字段，正文不再写状态/级别行 -->\n\n';
+  for (const { title, hint } of SECTIONS) {
+    body += '## ' + title + '\n\n' + hint + '\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);
+  const { body } = renderIntent(a);
+  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;