agentic-flow-kit 0.4.0 → 0.6.0

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-index.mjs

@@ -10,6 +10,7 @@
 // 生成区：INDEX.md 的 GENERATED:BEGIN/END 锚点注释之间整段重写，锚点外内容原样保留。
 import fs from 'node:fs';
 import path from 'node:path';
+import { ENUMS } from './workflow-enums.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-index.mjs [--dry-run] [--check] [--help]
 
@@ -32,14 +33,15 @@ const WORKFLOW = 'workflow';
 const INDEX_P = path.join(WORKFLOW, 'INDEX.md');
 const DOC_TYPES = ['intents', 'specs', 'plans', 'incidents'];
 const TYPE_LABEL = { intents: 'INTENT', specs: 'SPEC', plans: 'PLAN', incidents: 'INCIDENT' };
-const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 其余（done/fixed/closed/superseded/cancelled）折叠进档案计数
+// 活跃口径 = 单源 doc.status.active ∪ incident.status.active；其余状态折叠进档案计数
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 
 const BEGIN = '<!-- GENERATED:BEGIN — gen-workflow-index.mjs 整段重写，手工说明写在本行之前 -->';
 const END = '<!-- GENERATED:END -->';
 const HEADER = `# workflow 索引 — 活跃层与档案（生成物，勿手改）
 
 > 生成器 \`node .agents/scripts/gen-workflow-index.mjs\`（状态变更 / 新建文档后重跑；\`--check\` 校验漂移，check-loop 会告警）。
-> 活跃 = draft / approved / open（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
+> 活跃 = ${ACTIVE_STATUS.join(' / ')}（在跑）；其余状态折叠进档案计数，检索用 \`node .agents/scripts/kb-search.mjs "<词>"\`（默认含全部状态、活跃优先排序）。
 > 模块词表见 \`.agents/workflow-modules.txt\`。
 `;
 

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

@@ -16,6 +16,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { ENUMS } from './workflow-enums.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const MODULES_FILE = path.join(SCRIPT_DIR, '..', 'workflow-modules.txt');
@@ -30,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                         打印本说明
 
@@ -46,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++) {
@@ -58,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); }
@@ -78,7 +86,8 @@ if (moduleFilter && !MODULES.includes(moduleFilter)) {
   process.exit(1);
 }
 
-const ACTIVE_STATUS = ['draft', 'approved', 'open']; // 与 workflow/INDEX.md 活跃口径一致（fixed 归档案，默认也可命中）
+// 活跃口径 = 单源 doc.status.active ∪ incident.status.active（与 workflow/INDEX.md 活跃层一致，fixed 归档案默认也可命中）
+const ACTIVE_STATUS = [...ENUMS['doc.status.active'], ...ENUMS['incident.status.active']];
 const WF_SECTIONS = ['背景', '目标', '根因', '复盘三件套', '验收标准', '影响面'];
 const WIKI_EXCLUDE = new Set(['INDEX.md', '知识沉淀总览.html']);
 const WIKI_MAX_KB = 180;
@@ -135,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;
@@ -153,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);
@@ -168,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) };
   }
@@ -234,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

@@ -0,0 +1,145 @@
+// flow-kit source-sync-check：装户面同步一致性检查（包源 templates/_agents/ vs 装副本 .agents/）
+// 目的：包源改了 templates/_agents/ 但 .agents/ 装副本没刷新——这种"真空地带"sync.mjs 不扫、doctor.mjs §6.6 不扫
+//       本工具扫 templates/_agents/ 下所有 .md / .mjs / .json / .txt（排除 cache/）vs .agents/ 对应路径
+//       输出三类差异：缺失（包源有装副本无）/ 孤儿（包源无装副本有）/ 漂移（两者都有 sha 不一致）
+//       排除装副本独有文件：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 决策「只报告不修复」（--gate 只加 exit 码裁决，不改默认行为）
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+function fail(msg) { console.error('❌ ' + msg); process.exit(1); }
+
+const VALID_EXTS = new Set(['.md', '.mjs', '.json', '.txt']);
+// 装副本独有文件（init 渲染产物，不属双源结构）
+const RENDER_OUTPUT_FILES = new Set(['kit.json', 'settings.json', 'hooks/commit-check.config.json']);
+const TARGET_EXCLUDE = RENDER_OUTPUT_FILES;  // 向后兼容别名
+
+function sha256(p) {
+  try {
+    // 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;
+  }
+}
+
+// walkMd：递归扫目录，列出所有 validExt 文件（排除 cache/）
+function walkMd(root) {
+  const out = [];
+  function walk(dir, relBase) {
+    if (!fs.existsSync(dir)) return;
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const rel = relBase ? relBase + '/' + e.name : e.name;
+      const abs = path.join(dir, e.name);
+      // 排除 cache/ 目录（与 sync.mjs 既有约定一致）
+      if (rel === 'cache' || rel.startsWith('cache/')) continue;
+      if (e.isDirectory()) walk(abs, rel);
+      else if (VALID_EXTS.has(path.extname(e.name))) out.push(rel);
+    }
+  }
+  walk(root, '');
+  return out;
+}
+
+export function sourceSyncCheck({ pkgRoot, target }) {
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adapterRoot = path.join(target, '.agents');
+  const pkgFiles = walkMd(authorityRoot);
+  const tgtFiles = walkMd(adapterRoot).filter((f) => !TARGET_EXCLUDE.has(f));
+  const pkgSet = new Set(pkgFiles);
+  const tgtSet = new Set(tgtFiles);
+  const missing = []; // 包源有 / 装副本无
+  const orphan = [];  // 包源无 / 装副本有
+  const drift = [];   // 两者都有但 sha 不一致
+  for (const f of pkgFiles) {
+    if (!tgtSet.has(f)) { missing.push({ rel: f }); continue; }
+    const pkgSha = sha256(path.join(authorityRoot, f));
+    const tgtSha = sha256(path.join(adapterRoot, f));
+    if (pkgSha !== null && tgtSha !== null && pkgSha !== tgtSha) {
+      drift.push({ rel: f, pkgSha, tgtSha });
+    }
+  }
+  for (const f of tgtFiles) {
+    if (!pkgSet.has(f)) orphan.push({ rel: f });
+  }
+  return {
+    pkgRoot, target,
+    pkgCount: pkgFiles.length,
+    tgtCount: tgtFiles.length,
+    missing: missing.sort((a, b) => a.rel.localeCompare(b.rel)),
+    orphan: orphan.sort((a, b) => a.rel.localeCompare(b.rel)),
+    drift: drift.sort((a, b) => a.rel.localeCompare(b.rel)),
+  };
+}
+
+function printDiff(result) {
+  console.log('▶ flow-kit source-sync-check --diff');
+  console.log('  包源 (templates/_agents/) ' + result.pkgCount + ' 份  |  装副本 (.agents/) ' + result.tgtCount + ' 份');
+  if (!result.missing.length && !result.orphan.length && !result.drift.length) {
+    console.log('  无差异 ✅');
+    return;
+  }
+  if (result.missing.length) {
+    console.log('  缺失（包源有 / 装副本无）' + result.missing.length + '：');
+    for (const m of result.missing) console.log('    - ' + m.rel);
+  }
+  if (result.orphan.length) {
+    console.log('  孤儿（包源无 / 装副本有）' + result.orphan.length + '：');
+    for (const o of result.orphan) console.log('    - ' + o.rel);
+  }
+  if (result.drift.length) {
+    console.log('  漂移（包源装副本都有但 sha 不一致）' + result.drift.length + '：');
+    for (const d of result.drift) console.log('    - ' + d.rel + '  pkg=' + d.pkgSha.slice(0, 8) + '…  tgt=' + d.tgtSha.slice(0, 8) + '…');
+  }
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('source-sync-check.mjs');
+if (isMain) {
+  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];
+  }
+  if (!pkgRoot) pkgRoot = process.cwd();
+  if (!target) target = process.cwd();
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adapterRoot = path.join(target, '.agents');
+  if (!fs.existsSync(authorityRoot)) fail('找不到包源：' + authorityRoot);
+  if (!fs.existsSync(adapterRoot)) fail('找不到装副本：' + adapterRoot);
+  const result = sourceSyncCheck({ pkgRoot, target });
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({
+      pkgCount: result.pkgCount,
+      tgtCount: result.tgtCount,
+      missing: result.missing.map((m) => m.rel),
+      orphan: result.orphan.map((o) => o.rel),
+      drift: result.drift.map((d) => ({ rel: d.rel, pkgSha: d.pkgSha.slice(0, 8), tgtSha: d.tgtSha.slice(0, 8) })),
+    }, null, 2) + '\n');
+  } 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);
+}
+export default sourceSyncCheck;