agentic-flow-kit 0.5.0 → 0.6.0

package/templates/_agents/scripts/doctor.test.mjs

@@ -5,6 +5,8 @@
 //   ② 手改装副本（盘面 sha 变） → drift=1 gone=[] total=1
 //   ③ owned 文件缺失 → drift=0 gone=[rel] total=1
 //   ④ kit.json 无 owned 字段 → skipped=true total=0
+// 另测 checkAdapterDrift(target)（场景 5-14）与 checkLedgerCoverage(target, pkgRoot)（场景 15-18，
+//   2026-09-26 managed-ledger-adopt：补「盘上有、台账无」一侧）。
 // 用法：node .agents/scripts/doctor.test.mjs（在仓库根执行，需 src/doctor.mjs 存在——dogfooding 模式）
 import fs from 'node:fs';
 import os from 'node:os';
@@ -20,7 +22,7 @@ if (!fs.existsSync(SRC)) {
   console.error(`doctor.test.mjs：未找到 ${SRC}——仅在包源仓库（dogfooding）跑 npm test 时调用`);
   process.exit(1);
 }
-const { checkOwnedDrift, checkAdapterDrift } = await import(pathToFileURL(SRC).href);
+const { checkOwnedDrift, checkAdapterDrift, checkLedgerCoverage } = await import(pathToFileURL(SRC).href);
 
 let pass = 0;
 let fail = 0;
@@ -294,5 +296,76 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 15：盘上（包源）有 managed 类文件但台账无 → 差集非空（本 incident 的目标形态）----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-'));
+  const pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-pkg-'));
+  // 包源模板树：一份 managed 类（.agents/scripts/a.mjs）+ 一份 owned 类（workflow/README.md，须被排除）
+  const w = (p, c) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, c); };
+  w(path.join(pkg, 'templates/_agents/scripts/a.mjs'), '// a\n');
+  w(path.join(pkg, 'templates/_agents/commands/b.md'), '// b\n');
+  w(path.join(pkg, 'templates/workflow/README.md'), '// owned\n');
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({
+    kit: 'agentic-flow-kit', version: '0.5.0', options: { hosts: [], stack: 'none', boardPort: '8933' },
+    managed: [], owned: [],
+  }, null, 2));
+  const r = checkLedgerCoverage(root, pkg);
+  check('场景 15：盘上有 managed 类文件台账无 → 差集含两者',
+    r.skipped === false && r.missing.includes('.agents/scripts/a.mjs') && r.missing.includes('.agents/commands/b.md') && r.missing.length === 2,
+    JSON.stringify(r));
+  check('场景 15：owned 类（workflow/）不入差集',
+    !r.missing.some((m) => m.startsWith('workflow/')), JSON.stringify(r.missing));
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(pkg, { recursive: true, force: true });
+}
+
+// ---- 场景 16：台账登记齐全 → 差集空 ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-'));
+  const pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-pkg-'));
+  const w = (p, c) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, c); };
+  w(path.join(pkg, 'templates/_agents/scripts/a.mjs'), '// a\n');
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({
+    kit: 'agentic-flow-kit', version: '0.5.0', options: { hosts: [], stack: 'none', boardPort: '8933' },
+    managed: [{ rel: '.agents/scripts/a.mjs', sha256: 'x' }], owned: [],
+  }, null, 2));
+  const r = checkLedgerCoverage(root, pkg);
+  check('场景 16：登记齐全 → missing=[] skipped=false',
+    r.skipped === false && r.missing.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(pkg, { recursive: true, force: true });
+}
+
+// ---- 场景 17：无包源 templates/（装户环境）→ skipped ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-'));
+  const pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-pkg-')); // 空包根，无 templates/
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'), JSON.stringify({
+    kit: 'agentic-flow-kit', version: '0.5.0', options: { hosts: [], stack: 'none', boardPort: '8933' },
+    managed: [], owned: [],
+  }, null, 2));
+  const r = checkLedgerCoverage(root, pkg);
+  check('场景 17：无包源模板 → skipped=true missing=[]',
+    r.skipped === true && r.missing.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(pkg, { recursive: true, force: true });
+}
+
+// ---- 场景 18：无 kit.json → skipped ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-'));
+  const pkg = fs.mkdtempSync(path.join(os.tmpdir(), 'doctor-cov-pkg-'));
+  fs.mkdirSync(path.join(pkg, 'templates/_agents/scripts'), { recursive: true });
+  fs.writeFileSync(path.join(pkg, 'templates/_agents/scripts/a.mjs'), '// a\n');
+  const r = checkLedgerCoverage(root, pkg);
+  check('场景 18：无 kit.json → skipped=true missing=[]',
+    r.skipped === true && r.missing.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+  fs.rmSync(pkg, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

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

@@ -16,7 +16,12 @@ 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]; // 前端 + 服务端：任一更新都算「旧代码」
+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;
 
 // ---- 参数与基端口 ----
@@ -83,6 +88,7 @@ function staleCode(startedAt) {
 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) {
@@ -145,11 +151,32 @@ async function main() {
   }
   if (skipped.length) console.log(`board: 基端口段他人进程已跳过：${skipped.join('；')}`);
 
-  startServer(port);
+  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;

package/templates/_agents/scripts/gate-checklist.mjs

@@ -60,6 +60,7 @@ const PAIRS = [
   { doctor: '2', cl: null, note: '目录布局——装户体检独有' },
   { doctor: '3', cl: null, note: 'git 仓库与钩子——装户体检独有' },
   { doctor: '4', cl: null, note: 'kit.json managed 台账——装户体检独有' },
+  { doctor: '4.5', cl: null, note: '台账覆盖率——装户体检独有（盘上有 managed 类文件未登记，2026-09-26 managed-ledger-adopt）' },
   { doctor: '6.5', cl: null, note: 'delegations 台账结构——装户体检独有' },
   { doctor: '6.6', cl: null, note: 'owned 漂移——装户体检独有' },
   { doctor: '6.7', cl: null, note: '跨宿主薄适配——装户体检独有' },
@@ -78,6 +79,7 @@ const PAIRS = [
   { doctor: '7', cl: '12', note: '经 §7 整体运行覆盖' },
   { doctor: '7', cl: '13', note: '经 §7 整体运行覆盖' },
   { doctor: '7', cl: '14', note: '经 §7 整体运行覆盖' },
+  { doctor: '7', cl: '15', note: '经 §7 整体运行覆盖' },
 ];
 
 // gateChecklist：按登记表对照两侧检查项（pure function；pairs 可注入供测试）

package/templates/_agents/scripts/gate-checklist.test.mjs

@@ -167,11 +167,11 @@ if (hasReal) {
     JSON.stringify({ broken: r.broken, unregistered: r.unregistered }));
 }
 
-// ---- S11 真实仓库计数：doctor ≥ 12 节 / check-loop ≥ 14 项 ----
+// ---- S11 真实仓库计数：doctor ≥ 12 节 / check-loop ≥ 15 项 ----
 if (hasReal) {
   const r = gateChecklist({ doctorSrc: realDoctor(), checkLoopSrc: realCl() });
-  check('S11 真实仓库 doctor ≥ 12 节且 check-loop ≥ 14 项（baseline）',
-    r.doctorCount >= 12 && r.checkLoopCount >= 14,
+  check('S11 真实仓库 doctor ≥ 12 节且 check-loop ≥ 15 项（baseline）',
+    r.doctorCount >= 12 && r.checkLoopCount >= 15,
     `doctor ${r.doctorCount} / check-loop ${r.checkLoopCount}`);
 }
 

package/templates/_agents/scripts/gen-wiki-board.mjs

@@ -44,20 +44,40 @@ const BOARD_P = path.join(WIKI, '知识沉淀总览.html');
 //   主题目录顶层：全量文件登记（现状不变）；
 //   直属子目录：仅登记 md/html 知识文档（排除 *.visual-check.* 工具产物；.json/.png 不计入）；
 //   数据维护主题例外——其子目录（schema变更/<批次>/ 等）走 README.md 台账，不参与登记。
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout；p2-batch2 扩面到全 wiki/——
+// 活跃主题目录内的本机文件（如 *.xlsx）同样会造成生成物计数在 fresh clone 漂移）：
+// 排除 .gitignore 忽略的本机文件，git 不可用时退化为全量计数
+const gitIgnoredArchive = (() => {
+  try {
+    const out = execSync('git -c core.quotepath=false status --ignored=matching --porcelain -uall -- wiki',
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const prefix = 'wiki/';
+    return new Set(out.split(/\r?\n/)
+      .filter((l) => l.startsWith('!! '))
+      .map((l) => l.slice(3).trim().replace(/\/$/, ''))
+      .filter((p) => p.startsWith(prefix))
+      .map((p) => p.slice(prefix.length)));
+  } catch {
+    return new Set();
+  }
+})();
 const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
 const diskTopics = new Map(); // name -> [{ name: '文件名或 子目录/文件名', dir: 'wiki/主题[/子目录]/' }]
 for (const d of fs.readdirSync(WIKI)) {
   const p = path.join(WIKI, d);
   if (!fs.statSync(p).isDirectory() || d === 'drafts-archive') continue;
+  // gitignore 豁免消费（p2-batch2 扩面落点）：gitIgnoredArchive 集合现为全 wiki/ 的忽略件相对路径——
+  // 活跃区 entries 构建处按「主题/文件」与「主题/子目录/文件」过滤（复核 P1-2：扩面集合此前无消费点=死代码）
+  const isIgnored = (rel) => { const k = rel.endsWith('/') ? rel.slice(0, -1) : rel; return gitIgnoredArchive.has(`${d}/${k}`) || gitIgnoredArchive.has(`${d}/${k}/`); }; // 尾斜杠归一（复核 P2-a；endsWith 替代正则——此文件转义层过于嘈杂）
   const entries = fs.readdirSync(p)
-    .filter((f) => fs.statSync(path.join(p, f)).isFile())
+    .filter((f) => fs.statSync(path.join(p, f)).isFile() && !isIgnored(f))
     .map((f) => ({ name: f, dir: `wiki/${d}/` }));
   if (d !== '数据维护') {
     for (const sub of fs.readdirSync(p)) {
       const sp = path.join(p, sub);
-      if (!fs.statSync(sp).isDirectory()) continue;
+      if (!fs.statSync(sp).isDirectory() || isIgnored(`${sub}/`)) continue;
       for (const f of fs.readdirSync(sp)) {
-        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f)) {
+        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f) && !isIgnored(`${sub}/${f}`)) {
           entries.push({ name: `${sub}/${f}`, dir: `wiki/${d}/${sub}/` });
         }
       }
@@ -66,29 +86,15 @@ for (const d of fs.readdirSync(WIKI)) {
   entries.sort((a, b) => a.name.localeCompare(b.name, 'zh'));
   diskTopics.set(d, entries);
 }
-// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：与 verify-wiki-consistency.mjs 同口径——
-// 排除 .gitignore 忽略的本机文件（如 *.xlsx），防止生成物计数在 fresh clone 漂移；git 不可用时退化为全量计数
-const gitIgnoredArchive = (() => {
-  try {
-    const out = execSync('git -c core.quotepath=false status --ignored=matching --porcelain -uall -- wiki/drafts-archive',
-      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
-    const prefix = 'wiki/drafts-archive/';
-    return new Set(out.split(/\r?\n/)
-      .filter((l) => l.startsWith('!! '))
-      .map((l) => l.slice(3).trim().replace(/\/$/, ''))
-      .filter((p) => p.startsWith(prefix))
-      .map((p) => p.slice(prefix.length)));
-  } catch {
-    return new Set();
-  }
-})();
+
 const archiveCount = (() => {
   let n = 0;
   const walk = (dir, rel = '') => {
     for (const e of fs.readdirSync(dir)) {
       const p = path.join(dir, e);
-      const r = rel ? `${rel}/${e}` : e;
-      if (fs.statSync(p).isDirectory()) walk(p, r);
+      // 集合键带 drafts-archive/ 前缀（扫描面扩全 wiki/ 后），walk rel 须拼前缀比对（复核 P2-b）
+      const r = rel ? `drafts-archive/${rel}/${e}` : `drafts-archive/${e}`;
+      if (fs.statSync(p).isDirectory()) walk(p, rel ? `${rel}/${e}` : e);
       else if (!gitIgnoredArchive.has(r)) n++;
     }
   };
@@ -100,11 +106,19 @@ const archiveCount = (() => {
 // ---- 读 INDEX 现速览表：主题顺序 + 用途列（人工，不覆盖）----
 // 切行须容忍 CRLF：按 '\n' 切会在行尾留 '\r'，速览表行锚定正则（\|$）整表失配 →
 // 「用途」列（唯一人工维护位）被静默重置为 <待补>（papercut 2026-09-17；fixture 见 gen-wiki-board.test.mjs 场景 1）
+// 用途列管道转义（p2-batch2）：生成侧对单元格 `|` → `\|`（行内码 \`|\`），解析侧容忍转义——
+// 否则含管道的用途描述会切坏表格行、下次生成该行解析失配走「新主题追加」把人工文本静默重置
+const BS = String.fromCharCode(92); // 反斜杠字符（转义写法在此文件里反复出错，用 charCode 表达）
+const PIPE_CH = '|';
+const escCell = (s) => String(s).split(PIPE_CH).join(BS + PIPE_CH);
+const unescCell = (s) => String(s).split(BS + PIPE_CH).join(PIPE_CH);
 const indexText = fs.readFileSync(INDEX_P, 'utf8');
 const overview = []; // {name, usage}
+// 解析正则（p2-batch2）：用途列允许转义管道 \|--`(?:\\.|[^|])*` 吃掉「转义字符+任一字符」或普通字符，
+// 裸管道才是列分隔。unescCell 还原人工原文。
 for (const line of indexText.split(/\r?\n/)) {
-  const m = line.match(/^\| ([^|]+) \| (\d+) \|([^|]*)\|$/);
-  if (m && m[1].trim() !== '主题') overview.push({ name: m[1].trim(), usage: m[3].trim() });
+  const m = line.match(/^\| ([^|]+) \| (\d+) \|((?:\\.|[^|])*)\|$/);
+  if (m && m[1].trim() !== '主题') overview.push({ name: m[1].trim(), usage: unescCell(m[3].trim()) });
 }
 // 主题顺序 = 速览表现顺序在前，磁盘新主题按中文排序追加
 const ordered = [...overview.filter((o) => diskTopics.has(o.name))];
@@ -116,7 +130,7 @@ const totalFiles = [...diskTopics.values()].reduce((n, f) => n + f.length, 0);
 
 // ---- 生成 INDEX 三段 ----
 const eol = indexText.includes('\r\n') ? '\r\n' : '\n';
-const overviewRows = ordered.map((o) => `| ${o.name} | ${diskTopics.get(o.name).length} | ${o.usage} |`);
+const overviewRows = ordered.map((o) => `| ${o.name} | ${diskTopics.get(o.name).length} | ${escCell(o.usage)} |`);
 const mappingSection = ordered.map((o) => {
   const rows = diskTopics.get(o.name).map((e) => `| ${e.name} | ${o.name} | ${e.dir} |`);
   return [`### ${o.name}（${diskTopics.get(o.name).length}）`, '', '| 文件名 | 主题 | 归属目录 |', '|---|---|---|', ...rows].join(eol);

package/templates/_agents/scripts/gen-wiki-board.test.mjs

@@ -150,6 +150,24 @@ const runGen = (root) => spawnSync(process.execPath, [GEN], { cwd: root, encodin
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 6：用途列含管道符 → 转义保 round-trip（p2-batch2：含管道的用途描述曾切坏表格行、
+//      下次生成把人工文本静默重置为 <待补>）----
+{
+  const root = mkfix('\n');
+  const BS = String.fromCharCode(92); // 反斜杠字符（JS 字符串 '\|' 中 \| 就是裸管道无转义语义——须显式拼）
+  const USAGE_WITH_PIPE = '用于 A' + BS + '|B 两类（含竖线）'; // 转义形态输入（反斜杠+管道）
+  const idx = path.join(root, 'wiki', 'INDEX.md');
+  fs.writeFileSync(idx, fs.readFileSync(idx, 'utf8').replace(USAGE_COL, USAGE_WITH_PIPE), 'utf8');
+  const r1 = runGen(root);
+  const out1 = fs.readFileSync(idx, 'utf8');
+  check('场景 6：含转义管道用途生成 exit 0 且原样保留', r1.status === 0 && out1.includes(USAGE_WITH_PIPE), `exit=${r1.status}\n${out1.split('\n').slice(0, 8).join('\n')}`);
+  const r2 = runGen(root);
+  const out2 = fs.readFileSync(idx, 'utf8');
+  check('场景 6：二次生成用途文本保持（round-trip 不重置为 <待补>）',
+    r2.status === 0 && out2.includes(USAGE_WITH_PIPE) && !out2.includes('<待补'), out2.split('\n').slice(0, 8).join('\n'));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -4,11 +4,15 @@
 // 目的：把「语料膨胀 + 常驻面体积」变成可观测趋势——每月（或按需）跑一次，往 workflow/metrics.md 追加/更新一行。
 // 口径：文档 = 磁盘（对照 gen-workflow-index / 看板，排除 _TEMPLATE.md）；常驻面 = `.agents/rule-budgets.txt`
 //   各条实测（单源，含预算上限），括号内给「预算占用峰值项」。
+//   字节口径声明（p2-batch2）：本脚本用工作区 statSync 字节（CRLF 检出态会偏高），rule-budget.sh 用
+//   索引 LF 归一字节——趋势观测可对比，但与门禁判定数值存在系统性差异，勿互相替用。
 // 不做 --check / 不挂门禁：快照是历史记录——任何文档改动都会让「当前值」漂移，拿它做漂移校验只会常红；
 //   规则面的机器约束由 pre-commit 的 rule-budget.sh 负责，本脚本只负责「看见趋势」。
 // 测试：node .agents/scripts/gen-workflow-metrics.test.mjs（fixture 回归，须全绿）
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadEnums } from './workflow-enums.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
 
@@ -39,7 +43,10 @@ const WORKFLOW = 'workflow';
 const METRICS_P = path.join(WORKFLOW, 'metrics.md');
 const BUDGETS = path.join('.agents', 'rule-budgets.txt');
 const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
-const ACTIVE_STATUS = ['draft', 'approved', 'open'];
+// 活跃口径单源（board-kb-p1：枚举字面量硬编码退役——workflow-enums.txt 是唯一源）；
+// 枚举路径锚定脚本位置（fixture 测试 cwd 在临时目录，按 cwd 解析会 ENOENT）
+const ENUMS = loadEnums(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '.agents', 'workflow-enums.txt'));
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-metrics.mjs 整段重写，手工说明写在本行之前 -->';
 const END = '<!-- GENERATED:END -->';
 
@@ -51,6 +58,7 @@ function scanDocs() {
   let files = 0;
   let bytes = 0;
   let active = 0;
+  let invalid = 0;
   let withModule = 0;
   for (const type of DOC_TYPES) {
     let n = 0;
@@ -72,6 +80,7 @@ function scanDocs() {
         }
       }
       if (ACTIVE_STATUS.includes(status)) active++;
+      else if (!status || ![...ENUMS['doc.status.all'], ...ENUMS['incident.status.all']].includes(status)) invalid++; // 状态缺失/非法单列（board-kb-p1：不再吞进终态桶）
       if (mod) withModule++;
       n++;
       b += fs.statSync(p).size;
@@ -80,7 +89,7 @@ function scanDocs() {
     files += n;
     bytes += b;
   }
-  return { perType, files, bytes, active, terminal: files - active, withModule };
+  return { perType, files, bytes, active, terminal: files - active - invalid, invalid, withModule };
 }
 
 // ---- 常驻面：按预算表逐条实测（<glob|dir/> <上限>）----
@@ -146,7 +155,7 @@ const row = `| ${month} | ${docs.files}（活跃 ${docs.active} / 终态 ${docs.
 
 // ---- 明细（stdout，不落表）：类型分布 + 逐条预算占用 ----
 console.log(`📅 ${month} 快照`);
-console.log(`  文档：${docs.files} 篇 / ${kb(docs.bytes)}（活跃 ${docs.active} / 终态 ${docs.terminal}）；模块已填 ${docs.withModule}/${docs.files}`);
+console.log(`  文档：${docs.files} 篇 / ${kb(docs.bytes)}（活跃 ${docs.active} / 终态 ${docs.terminal}${docs.invalid ? ` / 状态缺失或非法 ${docs.invalid}` : ''}）；模块已填 ${docs.withModule}/${docs.files}`);
 for (const [t, v] of Object.entries(docs.perType)) console.log(`    ${t.padEnd(10)} ${String(v.n).padStart(3)} 篇 / ${kb(v.b)}`);
 console.log(`  索引：workflow/INDEX.md ${kb(idxBytes)}（活跃 ${Number.isNaN(idxActive) ? '—' : idxActive} 行）`);
 for (const e of surf.entries) console.log(`    ${e.label.padEnd(44)} ${String(e.max).padStart(6)} / ${String(e.lim).padStart(6)} B（${e.pct.toFixed(1)}%）`);

package/templates/_agents/scripts/kb-search.mjs

@@ -31,6 +31,7 @@ const USAGE = `用法: node .agents/scripts/kb-search.mjs [选项] <词1> [词2
   -n <N>                         每语料展示文件数上限，默认 10；0 = 不限
   --include-generated            wiki：纳入默认跳过的 json/csv、*.visual-check.* 与 >180KB bulk 文件（走纯扫，不吃缓存）
   --no-cache                     禁用结构缓存，全量扫（与缓存热路径输出逐字节一致）
+  --cache <文件>                 结构缓存文件路径覆盖（默认 .agents/cache/kb-index.json；测试注入用）
   --rebuild                      忽略现有缓存重建后回写
   --help                         打印本说明
 
@@ -47,6 +48,7 @@ let limit = 10;
 let limitRaw = '10';
 let includeGenerated = false;
 let noCache = false;
+let cacheFileOverride = ''; // --cache <文件>（board-kb-p1）：测试注入式缓存路径，不再直跑清真实开发缓存
 let rebuild = false;
 const words = [];
 for (let i = 0; i < args.length; i++) {
@@ -59,11 +61,16 @@ for (let i = 0; i < args.length; i++) {
   else if (a === '-n') { limitRaw = args[++i] ?? ''; limit = Number(limitRaw); }
   else if (a === '--include-generated') includeGenerated = true;
   else if (a === '--no-cache') noCache = true;
+  else if (a === '--cache') cacheFileOverride = args[++i] ?? '';
   else if (a === '--rebuild') rebuild = true;
   else if (a === '--help' || a === '-h') { console.log(USAGE); process.exit(0); }
   else words.push(a);
 }
 if (!words.length) { console.error(USAGE); process.exit(1); }
+// 空 query 校验（board-kb-p1）：空字符串词 includes('') 恒真 → 全量命中噪声（实测 109 文件命中）——参数错误
+const qWords = words.map((w) => w.trim()).filter(Boolean);
+if (!qWords.length) { console.error(`检索词不能为空（纯空白/空串）\n\n${USAGE}`); process.exit(1); }
+words.length = 0; words.push(...qWords); // 原位替换，下游 searchWorkflow/searchWiki 传参不变
 if (!Number.isFinite(limit) || limit < 0) { console.error(`-n 须为非负整数（现 ${limitRaw}）\n\n${USAGE}`); process.exit(1); }
 if (!scope) scope = topicFilter ? 'wiki' : 'all';
 if (!['workflow', 'wiki', 'all'].includes(scope)) { console.error(`--scope 须为 workflow|wiki|all（现 ${scope}）\n\n${USAGE}`); process.exit(1); }
@@ -137,12 +144,23 @@ function matchWords(lines, words) {
 // ---- 结构缓存：可检索子集预提取，[mtimeMs,size] 两元组逐文件失效，指纹变即整份作废 ----
 // 键 = <检索根 cwd>::<相对路径>（多语料根共存一文件，fixture 临时目录天然隔离）；读写任何异常静默回退全扫。
 const CACHE_DIR = path.join(SCRIPT_DIR, '..', 'cache');
-const CACHE_FILE = path.join(CACHE_DIR, 'kb-index.json');
+const CACHE_FILE = cacheFileOverride || path.join(CACHE_DIR, 'kb-index.json');
 const ROOT_NS = `${path.resolve('.')}::`;
+// WIKI_EXTS：wiki 语料扩展面（含 --include-generated 分支）——上移至 CFG_FP 之前（board-kb-p1 起纳入指纹派生）
+const WIKI_EXTS = includeGenerated ? /\.(md|sql|html|csv|json|txt)$/i : /\.(md|sql|html|txt)$/i;
+
+// 行序列化/复活（缓存 schema 的定义者——board-kb-p1 起纳入 CFG_FP 指纹：schema 演进即整份缓存作废）
+const serializeLines = (lines, kind) => lines.map((x) => (kind === 'wf' ? [x.ln, x.section, x.line] : [x.ln, x.line]));
+const reviveLines = (lines, kind) => lines.map((a) => (kind === 'wf' ? { ln: a[0], section: a[1], line: a[2] } : { ln: a[0], line: a[1] }));
+
+// linesShapeOk：缓存条目 lines 形状校验（board-kb-p1）——JSON 合法但 schema 坏（lines 非数组 / 元素非数组）
+// 一律视同 miss 走 build 重建（头注释「任何读写异常静默回退」契约恢复；此前直接 .map 抛 TypeError exit 1）
+const linesShapeOk = (lines) => Array.isArray(lines) && (lines.length === 0 || lines.every(Array.isArray));
+
 const CFG_FP = createHash('sha256').update(JSON.stringify({
   v: 1, WF_SECTIONS, ACTIVE_STATUS, WIKI_MAX_KB, excl: [...WIKI_EXCLUDE],
-  exts: ['md', 'sql', 'html', 'txt', 'gen:csv|json'],
-  fns: [parseDoc.toString(), workflowLines.toString(), matchWords.toString()],
+  exts: WIKI_EXTS.source, // schema 派生（board-kb-p1：手抄摘要曾致扩展面演进不触发指纹失效；RegExp.source 跨 includeGenerated 分支稳定）
+  fns: [parseDoc.toString(), workflowLines.toString(), matchWords.toString(), serializeLines.toString(), reviveLines.toString()],
 })).digest('hex').slice(0, 16);
 const cacheUsable = !noCache && !includeGenerated;
 let cache = null;
@@ -155,9 +173,6 @@ if (cacheUsable) {
   if (rebuild) cache = {};
 }
 
-const serializeLines = (lines, kind) => lines.map((x) => (kind === 'wf' ? [x.ln, x.section, x.line] : [x.ln, x.line]));
-const reviveLines = (lines, kind) => lines.map((a) => (kind === 'wf' ? { ln: a[0], section: a[1], line: a[2] } : { ln: a[0], line: a[1] }));
-
 // 取一个源文件的缓存条目；miss 时 build()（读全文提取可检索子集）并登记回写。返回 {st, meta?, title?, lines}
 function cachedEntry(relPath, kind, build) {
   const abs = path.resolve(relPath);
@@ -170,7 +185,7 @@ function cachedEntry(relPath, kind, build) {
   const st = fs.statSync(abs);
   const sig = [st.mtimeMs, st.size];
   const e = cache[key];
-  if (e && e.kind === kind && Array.isArray(e.st) && e.st[0] === sig[0] && e.st[1] === sig[1]) {
+  if (e && e.kind === kind && Array.isArray(e.st) && e.st[0] === sig[0] && e.st[1] === sig[1] && linesShapeOk(e.lines)) {
     touched.add(key);
     return { st: e.st, meta: e.meta, title: e.title, lines: reviveLines(e.lines, kind) };
   }
@@ -236,7 +251,6 @@ function searchWorkflow(words) {
 }
 
 // ---- wiki 检索（口径同 2026-09-21 降噪版 wiki-search）----
-const WIKI_EXTS = includeGenerated ? /\.(md|sql|html|csv|json|txt)$/i : /\.(md|sql|html|txt)$/i;
 const walkWiki = (dir, rel) => {
   const out = [];
   for (const e of fs.readdirSync(dir)) {

package/templates/_agents/scripts/kb-search.test.mjs

@@ -14,8 +14,10 @@ import { fileURLToPath } from 'node:url';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const KB = path.join(SCRIPT_DIR, 'kb-search.mjs');
-const CACHE_FILE = path.join(SCRIPT_DIR, '..', 'cache', 'kb-index.json');
+// 注入式缓存（board-kb-p1）：--cache 指向 fixture 内路径——测试不再触碰真实 .agents/cache/kb-index.json
+// （旧 CACHE_FILE 直跑会清空真实开发缓存并遗留孤儿条目，审查 P2-2）
 const USAGE = '用法：node .agents/scripts/kb-search.test.mjs';
+const rootCache = (root) => path.join(root, 'kb-cache.json');
 
 let pass = 0;
 let fail = 0;
@@ -46,7 +48,7 @@ const mkfix = () => {
   return root;
 };
 
-const run = (root, args) => spawnSync(process.execPath, [KB, ...args], { cwd: root, encoding: 'utf8' });
+const run = (root, args) => spawnSync(process.execPath, [KB, '--cache', rootCache(root), ...args], { cwd: root, encoding: 'utf8' });
 const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l.replace('📄 ', ''));
 
 // ---- 场景 1：主路径——AND 语义 / 节限定 / 输出字段 / 活跃优先 ----
@@ -97,7 +99,7 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
   const cold = run(root, ['编码模板']);                                   // 该临时根 ns 无条目 → cold
   const warm = run(root, ['编码模板']);                                   // 全命中缓存
   const nocache = run(root, ['--no-cache', '编码模板']);
-  check('场景 4：cold/warm exit 0 且 warm 确有缓存回写', cold.status === 0 && warm.status === 0 && fs.existsSync(CACHE_FILE), `cold=${cold.status} warm=${warm.status}`);
+  check('场景 4：cold/warm exit 0 且 warm 确有缓存回写', cold.status === 0 && warm.status === 0 && fs.existsSync(rootCache(root)), `cold=${cold.status} warm=${warm.status}`);
   check('场景 4：cold ≡ warm（逐字节）', cold.stdout === warm.stdout, `cold:\n${cold.stdout}\nwarm:\n${warm.stdout}`);
   check('场景 4：cold ≡ --no-cache（逐字节）', cold.stdout === nocache.stdout, `cold:\n${cold.stdout}\nnocache:\n${nocache.stdout}`);
   check('场景 4：双侧均有命中（workflow 3 + wiki 1）', files(cold.stdout).length === 3 && /wiki\/测试主题/.test(cold.stdout), cold.stdout);
@@ -121,14 +123,14 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
 {
   const root = mkfix();
   run(root, ['编码模板']); // 建缓存
-  const j = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  const j = JSON.parse(fs.readFileSync(rootCache(root), 'utf8'));
   const fpBefore = j.fp;
   j.fp = 'ffffffffffffffff';
-  fs.writeFileSync(CACHE_FILE, JSON.stringify(j), 'utf8');
+  fs.writeFileSync(rootCache(root), JSON.stringify(j), 'utf8');
   const after = run(root, ['编码模板']);
   const scan = run(root, ['--no-cache', '编码模板']);
   check('场景 6：指纹不符 → 输出仍与纯扫逐字节一致', after.status === 0 && after.stdout === scan.stdout, `after:\n${after.stdout}\nscan:\n${scan.stdout}`);
-  const j2 = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf8'));
+  const j2 = JSON.parse(fs.readFileSync(rootCache(root), 'utf8'));
   check('场景 6：回写恢复正确指纹', j2.fp === fpBefore && j2.fp !== 'ffffffffffffffff', `fp=${j2.fp}`);
   fs.rmSync(root, { recursive: true, force: true });
 }
@@ -136,8 +138,8 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
 // ---- 场景 7：缓存损坏 → 静默回退全扫（不报错、输出与 --no-cache 一致） ----
 {
   const root = mkfix();
-  fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
-  fs.writeFileSync(CACHE_FILE, 'not-json{{{', 'utf8');
+  fs.mkdirSync(path.dirname(rootCache(root)), { recursive: true });
+  fs.writeFileSync(rootCache(root), 'not-json{{{', 'utf8');
   const r = run(root, ['编码模板']);
   const scan = run(root, ['--no-cache', '编码模板']);
   check('场景 7：损坏缓存 exit 0（stderr 无泄漏）', r.status === 0 && !r.stderr, `exit=${r.status}\n${r.stderr}`);
@@ -145,6 +147,34 @@ const files = (out) => (out.match(/^📄 (workflow\/\S+)/gm) || []).map((l) => l
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- 场景 8：结构损坏（JSON 合法但 lines 非数组 / 元素非数组）→ 静默回退（board-kb-p1 P1-1）----
+//     此前 reviveLines 直接 .map 抛 TypeError exit 1，违背「任何读写异常静默回退」声明契约
+{
+  for (const [tag, lines] of [['lines-字符串', 'corrupted'], ['lines-元素非数组', ['not-array']]]) {
+    const root = mkfix();
+    run(root, ['编码模板']); // 建缓存
+    const j = JSON.parse(fs.readFileSync(rootCache(root), 'utf8'));
+    const key = Object.keys(j.files).find((k) => k.endsWith('2026-09-01-aaa.md'));
+    j.files[key].lines = lines;
+    fs.writeFileSync(rootCache(root), JSON.stringify(j), 'utf8');
+    const r = run(root, ['编码模板']);
+    const scan = run(root, ['--no-cache', '编码模板']);
+    check(`场景 8：结构损坏（${tag}）exit 0 静默回退`, r.status === 0 && !r.stderr, `exit=${r.status}\n${r.stderr}`);
+    check(`场景 8：结构损坏（${tag}）输出与纯扫一致`, r.stdout === scan.stdout, `r:\n${r.stdout}\nscan:\n${scan.stdout}`);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+// ---- 场景 9：空 query（空串 / 纯空白）→ 参数错误 exit 1（board-kb-p1：includes('') 恒真曾全量命中）----
+{
+  const root = mkfix();
+  const r1 = run(root, ['']);
+  const r2 = run(root, ['  ', ' ']);
+  check('场景 9：空串 query exit 1', r1.status === 1 && /检索词不能为空/.test(r1.stderr), `exit=${r1.status}\n${r1.stderr}`);
+  check('场景 9：纯空白 query exit 1', r2.status === 1 && /检索词不能为空/.test(r2.stderr), `exit=${r2.status}\n${r2.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log(`\n${USAGE}`);

package/templates/_agents/scripts/source-sync-check.mjs

@@ -5,8 +5,10 @@
 //       排除装副本独有文件：kit.json / settings.json / hooks/commit-check.config.json（init 渲染产物，不属双源）
 // 用法：node .agents/scripts/source-sync-check.mjs --diff
 //       node .agents/scripts/source-sync-check.mjs --json
+//       node .agents/scripts/source-sync-check.mjs --gate（门禁模式：缺失/漂移 exit 1，孤儿只报告不计失败
+//             ——pre-commit 双源一致性门禁用，2026-09-27 audit-gate-hardening；--diff/--json 仍恒 exit 0）
 //       node .agents/scripts/source-sync-check.mjs --pkg-root <path> --target <path>
-// 零依赖；B-b 决策「只报告不修复」
+// 零依赖；B-b 决策「只报告不修复」（--gate 只加 exit 码裁决，不改默认行为）
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -20,7 +22,8 @@ const TARGET_EXCLUDE = RENDER_OUTPUT_FILES;  // 向后兼容别名
 
 function sha256(p) {
   try {
-    return createHash('sha256').update(fs.readFileSync(p)).digest('hex');
+    // LF 归一（2026-09-27 closing-coverage）：CRLF 盘面与 LF 克隆同值，行尾不一致不误报缺失/漂移/孤儿外差异
+    return createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex');
   } catch {
     return null;
   }
@@ -98,12 +101,13 @@ function printDiff(result) {
 
 const isMain = process.argv[1] && process.argv[1].endsWith('source-sync-check.mjs');
 if (isMain) {
-  let jsonMode = false, diffMode = false;
+  let jsonMode = false, diffMode = false, gateMode = false;
   let pkgRoot = null, target = null;
   for (let i = 0; i < process.argv.length - 2; i++) {
     const a = process.argv[2 + i];
     if (a === '--json') jsonMode = true;
     else if (a === '--diff') diffMode = true;
+    else if (a === '--gate') gateMode = true;
     else if (a === '--pkg-root') pkgRoot = process.argv[2 + i + 1];
     else if (a === '--target') target = process.argv[2 + i + 1];
   }
@@ -125,6 +129,16 @@ if (isMain) {
   } else {
     printDiff(result);
   }
+  if (gateMode) {
+    // 门禁模式（pre-commit 双源一致性用）：缺失/漂移非零阻断——正是「包源改了装副本没跟」的故障模式
+    // （doctor §4 台账 sha 对此静默：盘面=台账即 PASS；§4.5 只抓未登记）。孤儿只报告不计失败：
+    // 孤儿 = 装副本独有（装户自持内容如本地 skills），删留由人拍板，不入机器门。
+    if (result.missing.length || result.drift.length) {
+      console.error('❌ 双源不一致（缺失 ' + result.missing.length + ' / 漂移 ' + result.drift.length + '）——包源与装副本须同提交成对（双源纪律）；跑 node bin/flow-kit.mjs sync 后原路重试（孤儿只报告不计失败）');
+      process.exit(1);
+    }
+    process.exit(0);
+  }
   // diff/json 模式总 exit 0；差异存在不视作错误（人类阅读用；B-b 决策「只报告不修复」）
   process.exit(0);
 }