agentic-flow-kit 0.5.0 → 0.7.0

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';
@@ -16,11 +18,20 @@ 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;  // 向后兼容别名
+// **项目自持、按设计就该与包源骨架不同**的架子文件（2026-09-28 追加）：
+// `notes/runtime-env.md` 自述「记录本机/本项目的运行时差异……**本文件是骨架：项目按实际填写，
+// 不随 flow-kit 升级覆盖**」——即包源只发骨架、装户填实况，**两处本就应当不同**。
+// 但本工具此前按 `.md` 全量比对，导致装户一旦按文件自述填写，`--gate` 即 exit 1（CI 红）：
+// 实测（本仓自装）填写后 --gate 报 `漂移 1: notes/runtime-env.md`，回滚即恢复 0。
+// 这属「门禁范围与文件自述冲突」，非真漂移——故按渲染产物同类处理（排除）。
+// 判据：该文件是**项目内容**而非**引擎件**；引擎件（.mjs 脚本等）不在排除内，仍受双源门禁约束。
+const PROJECT_OWNED_FILES = new Set(['notes/runtime-env.md']);
+const TARGET_EXCLUDE = new Set([...RENDER_OUTPUT_FILES, ...PROJECT_OWNED_FILES]);  // 向后兼容别名（原为 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;
   }
@@ -47,7 +58,10 @@ function walkMd(root) {
 export function sourceSyncCheck({ pkgRoot, target }) {
   const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
   const adapterRoot = path.join(target, '.agents');
-  const pkgFiles = walkMd(authorityRoot);
+  // **两侧都要按 TARGET_EXCLUDE 过滤**（2026-09-28 修正）：只过滤装副本一侧会把排除件
+  // 变成「包源有 / 装副本无」的**缺失**（实测：加排除后 --gate 从「漂移 1」变成「缺失 1」，
+  // 仍 exit 1）。排除的语义是「不参与双源比对」，故包源侧同样滤掉。
+  const pkgFiles = walkMd(authorityRoot).filter((f) => !TARGET_EXCLUDE.has(f));
   const tgtFiles = walkMd(adapterRoot).filter((f) => !TARGET_EXCLUDE.has(f));
   const pkgSet = new Set(pkgFiles);
   const tgtSet = new Set(tgtFiles);
@@ -98,12 +112,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 +140,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);
 }

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

@@ -6,6 +6,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { sourceSyncCheck } from './source-sync-check.mjs';
 
@@ -15,7 +16,20 @@ function check(name, cond, detail = '') {
   else { failCount++; console.log('FAIL ' + name + (detail ? '——' + detail : '')); }
 }
 
-const SRC_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+// SRC_ROOT：自测试文件位置向上探测包源（templates/_agents）——包源路径（templates/_agents/scripts/）与
+// 装副本路径（.agents/scripts/）直跑都解析到仓库根；无包源（装户环境）返回 null，S5/S9 baseline 记 SKIP
+// 不算失败（2026-09-27 gate-hardening-p2-batch：旧 `../../..` 硬编码层级从装副本直跑必 FAIL）
+const findSrcRoot = () => {
+  let d = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(d, 'templates', '_agents'))) return d;
+    d = path.dirname(d);
+  }
+  return null;
+};
+const SRC_ROOT = findSrcRoot();
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'source-sync-check.mjs');
+const runGate = (args) => spawnSync(process.execPath, [SCRIPT, ...args], { encoding: 'utf8' });
 
 // ---- fixture：mini 包源 + 装副本，3 类差异各造 1 个 ----
 function mkFixture() {
@@ -87,11 +101,11 @@ function mkFixture() {
   check('S4 一致文件 cmdA.md 不在漂移', !r.drift.some((d) => d.rel === 'commands/cmdA.md'));
 }
 
-// ---- 场景 5：实际仓库扫描 baseline（包源 ≥ 30 份 / 装副本 ≥ 30 份）----
-{
-  const pkgRoot = SRC_ROOT;
-  const target = SRC_ROOT;
-  const r = sourceSyncCheck({ pkgRoot, target });
+// ---- 场景 5：实际仓库扫描 baseline（包源 ≥ 30 份 / 装副本 ≥ 30 份；装户环境无包源 → SKIP）----
+if (!SRC_ROOT) {
+  check('S5 baseline SKIP（未探测到包源 templates/_agents——装户环境直跑，不算失败）', true);
+} else {
+  const r = sourceSyncCheck({ pkgRoot: SRC_ROOT, target: SRC_ROOT });
   check('S5 实际仓库 包源 ≥ 30 份', r.pkgCount >= 30, '实际 ' + r.pkgCount);
   check('S5 实际仓库 装副本 ≥ 30 份', r.tgtCount >= 30, '实际 ' + r.tgtCount);
   // 装副本 kit.json / settings.json 不应在孤儿
@@ -138,8 +152,10 @@ function mkFixture() {
     r.orphan.length === 1 && r.orphan[0].rel === 'hooks/real-orphan.json', JSON.stringify(r.orphan));
 }
 
-// ---- 场景 9：实际仓库 hooks/commit-check.config.json 不在孤儿 ----
-{
+// ---- 场景 9：实际仓库 hooks/commit-check.config.json 不在孤儿（装户环境随 S5 一并 SKIP）----
+if (!SRC_ROOT) {
+  check('S9 baseline SKIP（装户环境，随 S5）', true);
+} else {
   const r = sourceSyncCheck({ pkgRoot: SRC_ROOT, target: SRC_ROOT });
   check('S9 实际仓库 hooks/commit-check.config.json 不在孤儿',
     !r.orphan.some((o) => o.rel === 'hooks/commit-check.config.json'), JSON.stringify(r.orphan));
@@ -152,5 +168,114 @@ function mkFixture() {
   check('S7 空目录 fixture 不崩（0/0）', r.pkgCount === 0 && r.tgtCount === 0);
 }
 
+// ---- 场景 10-12：--gate 门禁模式（2026-09-27 audit-gate-hardening，pre-commit 双源门禁用）----
+{
+  // S10 差异 fixture（缺失 1 / 漂移 1 / 孤儿 1）→ --gate exit 1（缺失/漂移阻断）
+  const { pkgRoot, target } = mkFixture();
+  const r = runGate(['--gate', '--pkg-root', pkgRoot, '--target', target]);
+  check('S10 --gate 差异 fixture（缺失+漂移）→ exit 1', r.status === 1, `exit=${r.status}\n${r.stdout || ''}${r.stderr || ''}`);
+}
+{
+  // S11 孤儿-only fixture → --gate exit 0（孤儿只报告不计失败——装户自持内容不入机器门）
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-gate-orphan-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents');
+  const tgtBase = path.join(target, '.agents');
+  fs.mkdirSync(path.join(pkgBase, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(tgtBase, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'commands', 'same.md'), '# v1\n');
+  fs.writeFileSync(path.join(tgtBase, 'commands', 'same.md'), '# v1\n');
+  fs.writeFileSync(path.join(tgtBase, 'local-only.md'), '# 装户自持\n');
+  const r = runGate(['--gate', '--pkg-root', pkgRoot, '--target', target]);
+  check('S11 --gate 孤儿-only → exit 0（孤儿不计失败）', r.status === 0, `exit=${r.status}\n${r.stdout || ''}${r.stderr || ''}`);
+}
+{
+  // S12 干净 fixture --gate → exit 0；差异 fixture --diff → 仍 exit 0（B-b「只报告不修复」默认语义不变）
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-gate-clean-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents');
+  const tgtBase = path.join(target, '.agents');
+  fs.mkdirSync(path.join(pkgBase, 'commands'), { recursive: true });
+  fs.mkdirSync(path.join(tgtBase, 'commands'), { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'commands', 'same.md'), '# v1\n');
+  fs.writeFileSync(path.join(tgtBase, 'commands', 'same.md'), '# v1\n');
+  const rClean = runGate(['--gate', '--pkg-root', pkgRoot, '--target', target]);
+  check('S12 --gate 干净 fixture → exit 0', rClean.status === 0, `exit=${rClean.status}`);
+  const { pkgRoot: dp, target: dt } = mkFixture();
+  const rDiff = runGate(['--diff', '--pkg-root', dp, '--target', dt]);
+  check('S12 --diff 差异 fixture 仍 exit 0（B-b 默认语义不变）', rDiff.status === 0, `exit=${rDiff.status}`);
+}
+
+// ---- 场景 13-14：sha LF 归一（2026-09-27 closing-coverage）——CRLF 等价不误报 / 内容差异照常抓 ----
+{
+  // S13 同内容不同行尾（包源 LF / 装副本 CRLF）→ 不报漂移
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-crlf-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents', 'commands');
+  const tgtBase = path.join(target, '.agents', 'commands');
+  fs.mkdirSync(pkgBase, { recursive: true });
+  fs.mkdirSync(tgtBase, { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'a.md'), '# 标题\n\n正文行\n- 项目\n');
+  fs.writeFileSync(path.join(tgtBase, 'a.md'), '# 标题\r\n\r\n正文行\r\n- 项目\r\n');
+  fs.writeFileSync(path.join(pkgBase, 'b.md'), '# B\n');
+  fs.writeFileSync(path.join(tgtBase, 'b.md'), '# B\n');
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S13 同内容不同行尾（LF vs CRLF）→ 0 漂移（LF 归一口径）', r.drift.length === 0, JSON.stringify(r.drift));
+}
+{
+  // S14 内容真实差异（即使行尾也不同）→ 照常报漂移（归一不掩盖内容差异）
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-crlf2-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents', 'commands');
+  const tgtBase = path.join(target, '.agents', 'commands');
+  fs.mkdirSync(pkgBase, { recursive: true });
+  fs.mkdirSync(tgtBase, { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'a.md'), '# v1\n内容甲\n');
+  fs.writeFileSync(path.join(tgtBase, 'a.md'), '# v1\r\n内容乙\r\n');
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S14 内容差异（甲 vs 乙）→ 报漂移（归一只认 CRLF 不吞内容）', r.drift.length === 1 && r.drift[0].rel === 'commands/a.md', JSON.stringify(r.drift));
+}
+
+// ---- 场景 15-16：项目自持架子文件排除（2026-09-28 runtime-env 双源冲突）----
+{
+  // S15 notes/runtime-env.md **两侧都被排除**——包源只发骨架、装户填实况，两处本就该不同。
+  // 回归：首版只过滤装副本一侧 → 排除件变成「包源有/装副本无」的**缺失**，--gate 仍 exit 1
+  // （实测：漂移 1 → 缺失 1）。故断言 missing/drift 皆为空。
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-owned-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents', 'notes');
+  const tgtBase = path.join(target, '.agents', 'notes');
+  fs.mkdirSync(pkgBase, { recursive: true });
+  fs.mkdirSync(tgtBase, { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'runtime-env.md'), '# 骨架\n> 项目按实际填写\n');
+  fs.writeFileSync(path.join(tgtBase, 'runtime-env.md'), '# 实况\n> 本机 sh 路径已接\n');
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S15 项目自持 runtime-env.md 两侧内容不同 → 既不报缺失也不报漂移（双侧排除）',
+    r.missing.length === 0 && r.drift.length === 0,
+    JSON.stringify({ missing: r.missing, drift: r.drift }));
+}
+{
+  // S16 排除**只针对该文件**——同目录其他 .md 仍受双源门禁约束（防排除范围被误放大）
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-ssc-owned2-'));
+  const pkgRoot = path.join(root, 'pkg');
+  const target = path.join(root, 'target');
+  const pkgBase = path.join(pkgRoot, 'templates', '_agents', 'notes');
+  const tgtBase = path.join(target, '.agents', 'notes');
+  fs.mkdirSync(pkgBase, { recursive: true });
+  fs.mkdirSync(tgtBase, { recursive: true });
+  fs.writeFileSync(path.join(pkgBase, 'runtime-env.md'), '# 骨架\n');
+  fs.writeFileSync(path.join(tgtBase, 'runtime-env.md'), '# 实况\n');
+  fs.writeFileSync(path.join(pkgBase, 'other.md'), '# v1\n');
+  fs.writeFileSync(path.join(tgtBase, 'other.md'), '# v2\n');
+  const r = sourceSyncCheck({ pkgRoot, target });
+  check('S16 排除不放大——同目录 other.md 内容不同仍报漂移',
+    r.drift.length === 1 && r.drift[0].rel === 'notes/other.md', JSON.stringify(r.drift));
+}
+
 console.log('\n合计: PASS ' + pass + ' / FAIL ' + failCount);
 process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/verify-wiki-consistency.mjs

@@ -31,6 +31,23 @@ const walkTree = (dir, rel = '') => {
 
 // ---- 磁盘枚举（登记口径与 gen-wiki-board.mjs 一致）----
 const isKnowledgeDoc = (f) => /\.(md|html)$/i.test(f) && !/\.visual-check\./i.test(f);
+// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：drafts-archive 含
+// .gitignore 忽略的本机文件（如 *.xlsx），计入会使生成物计数在 fresh clone 必然漂移；
+// 口径 = 排除忽略文件（git 不可用/非仓库时退化为全量计数，fixture 环境不受影响）
+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 diskFiles = new Set(); // "主题/文件名"（子目录文件名带 子目录/ 前缀）
 const diskTopics = new Set();
 const activeTree = { files: [], dirs: [] }; // 递归视图（断链守卫 / 台账登记断言用）
@@ -39,15 +56,18 @@ for (const d of fs.readdirSync(WIKI)) {
   if (!fs.statSync(p).isDirectory()) continue;
   if (d === 'drafts-archive') continue;
   diskTopics.add(d);
+  // gitignore 豁免消费（p2-batch2 复核 P1-3）：gen 侧排除 ignored 本机件，verify 须同口径——
+  // 否则「gen 恒写 N、verify 恒数 N+1」门禁死锁且自愈指引（重跑 gen）无效
+  const isIgnored = (rel) => { const k = rel.replace(/\/$/, ''); return gitIgnoredArchive.has(`${d}/${k}`) || gitIgnoredArchive.has(`${d}/${k}/`); }; // 尾斜杠归一（复核 P2-a）
   for (const f of fs.readdirSync(p)) {
-    if (fs.statSync(path.join(p, f)).isFile()) diskFiles.add(`${d}/${f}`);
+    if (fs.statSync(path.join(p, f)).isFile() && !isIgnored(f)) diskFiles.add(`${d}/${f}`);
   }
   if (d !== '数据维护') {
     for (const sub of fs.readdirSync(p)) {
       const sp = path.join(p, sub);
       if (!fs.statSync(sp).isDirectory()) continue;
       for (const f of fs.readdirSync(sp)) {
-        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f)) diskFiles.add(`${d}/${sub}/${f}`);
+        if (fs.statSync(path.join(sp, f)).isFile() && isKnowledgeDoc(f) && !isIgnored(`${sub}/${f}`)) diskFiles.add(`${d}/${sub}/${f}`);
       }
     }
   }
@@ -56,27 +76,11 @@ for (const d of fs.readdirSync(WIKI)) {
   activeTree.dirs.push(...sub.dirs);
 }
 
-// gitignore 豁免（F4，incident 2026-09-23-code-review-f3-f4-closeout）：drafts-archive 含
-// .gitignore 忽略的本机文件（如 *.xlsx），计入会使生成物计数在 fresh clone 必然漂移；
-// 口径 = 排除忽略文件（git 不可用/非仓库时退化为全量计数，fixture 环境不受影响）
-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();
-  }
-})();
+
 // drafts-archive 缺失：ENOENT 崩栈改明示失败（本脚本是门禁，协议目录被删应 exit 1 而非崩栈，2026-09-24）
 const ARCHIVE_DIR = path.join(WIKI, 'drafts-archive');
 let archiveCount = 0;
-if (fs.existsSync(ARCHIVE_DIR)) archiveCount = walkTree(ARCHIVE_DIR).files.filter((r) => !gitIgnoredArchive.has(r)).length;
+if (fs.existsSync(ARCHIVE_DIR)) archiveCount = walkTree(ARCHIVE_DIR).files.filter((r) => !gitIgnoredArchive.has(`drafts-archive/${r}`)).length; // 集合键带 drafts-archive/ 前缀（复核 P2-b）
 else problems.push('wiki/drafts-archive/ 目录缺失（wiki 协议结构，模板自带）——归档一致性无从校验');
 
 // ---- 看板 DATA 解析 ----
@@ -86,7 +90,25 @@ if (!m) {
   console.error('❌ 看板 DATA 解析失败：知识沉淀总览.html 中找不到 `const DATA = {...}`');
   process.exit(1);
 }
-const DATA = eval('(' + m[1] + ')');
+// JSON.parse（p2-batch2）：DATA 由 gen-wiki-board 经 JSON.stringify 生成、必为合法 JSON——
+// eval 换 JSON.parse 消除门禁脚本对 repo 内文件执行任意 JS 的面；解析失败即 fail-loud 门禁失败
+let DATA;
+try {
+  DATA = JSON.parse(m[1]);
+} catch (e) {
+  console.error(`❌ 看板 DATA 不是合法 JSON（应跑 gen-wiki-board.mjs 重生成）：${e.message}`);
+  process.exit(1);
+}
+// 合计行比对（p2-batch2）：合计行有生成（fail-loud 锚点）无验证——手改/陈旧此前不可见
+{
+  const totalM = fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').match(/合计：\*\*(\d+) 份\*\*知识文档，\*\*(\d+) 个主题\*\*/);
+  if (totalM) {
+    if (Number(totalM[1]) !== diskFiles.size || Number(totalM[2]) !== diskTopics.size) {
+      console.error(`❌ INDEX 合计行与磁盘不一致：合计 ${totalM[1]} 份/${totalM[2]} 主题 vs 磁盘 ${diskFiles.size} 份/${diskTopics.size} 主题——跑 gen-wiki-board.mjs 重生成`);
+      process.exit(1);
+    }
+  }
+}
 const boardFiles = new Set();
 for (const t of DATA.topics) for (const f of t.files) boardFiles.add(`${t.name}/${f.file}`);
 const boardTopics = new Set(DATA.topics.map((t) => t.name));
@@ -97,8 +119,9 @@ const indexTopicCounts = new Map(); // 速览表 topic → 文件数
 for (const line of fs.readFileSync(path.join(WIKI, 'INDEX.md'), 'utf8').split(/\r?\n/)) {
   const mm = line.match(/^\| ([^|]+) \| ([^|]+) \| wiki\/([^/]+)\/[^|]*\|$/);
   if (mm) indexFiles.add(`${mm[3].trim()}/${mm[1].trim()}`);
-  const ov = line.match(/^\| ([^|]+) \| (\d+) \|[^|]*\|$/);
-  if (ov && ov[1].trim() !== '主题') indexTopicCounts.set(ov[1].trim(), Number(ov[2]));
+  // 速览行用途列容忍转义管道（p2-batch2 复核 P2-4：gen 侧转义写入后本解析须同款，否则该主题计数核对静默跳过）
+  const ov = line.match(/^\| ([^|]+) \| (\d+) \|((?:\\.|[^|])*)\|$/);
+  if (ov && ov[1].trim() !== '主题') indexTopicCounts.set(ov[1].trim().replace(/\\\|/g, '|'), Number(ov[2]));
 }
 
 const diff = (a, b) => [...a].filter((x) => !b.has(x));

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

@@ -8,7 +8,7 @@ import http from 'node:http';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFile } from 'node:child_process';
+import { execFile, spawnSync } from 'node:child_process';
 import { ENUMS } from './workflow-enums.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
@@ -38,9 +38,10 @@ function parseDoc(text) {
   return { meta, title };
 }
 
-// ---- 验收标准 checkbox 统计：仅「## 验收标准」节内（至下一个 ## 标题），无该节返回 null ----
+// ---- 验收标准 checkbox 统计：仅「验收标准」节内（至下一个 ## 标题），无该节返回 null ----
+// 节匹配对齐 check-loop 检查 8 口径（^\s*##\s[^#]*验收标准，2026-09-27 board-kb-p1——「## 三、验收标准」类标题此前识别不到）
 function parseAcceptance(text) {
-  const h = text.match(/^## 验收标准.*$/m);
+  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);
@@ -50,6 +51,7 @@ function parseAcceptance(text) {
   const done = (section.match(/^\s*[-*] \[[xX]\]/gm) || []).length;
   return { done, total };
 }
+export { parseAcceptance };
 
 // ---- 配对断裂检测：按 slug 聚合同族（同名 intent/incident/plan/spec），异常卡附 alerts ----
 // 规则（口径对齐 check-loop.sh 的硬断档 + 状态枚举，看板为预警层、不阻断；枚举读单源 workflow-enums.txt）：
@@ -157,7 +159,12 @@ async function scanBoard() {
   }
   detectAlerts(cards);
   cards.sort((a, b) => b.date.localeCompare(a.date) || a.type.localeCompare(b.type));
-  return { root: ROOT, pid: process.pid, startedAt: STARTED_AT, counts, cards };
+  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/ 内 ----
@@ -202,13 +209,54 @@ setInterval(() => { for (const res of sseClients) { if (res.destroyed) sseClient
 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) {
-  res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8' });
+  // 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) => {
-  const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
   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');
@@ -238,6 +286,9 @@ const server = http.createServer(async (req, res) => {
     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 });
   }
 });
@@ -248,6 +299,10 @@ server.on('error', (e) => {
   process.exit(1);
 });
 
-server.listen(PORT, '127.0.0.1', () => {
-  console.log(`workflow 看板: http://127.0.0.1:${PORT}  （Ctrl+C 停止；只读 workflow/，不写任何文件）`);
-});
+// isMain 守卫（board-kb-p1）：parseLoopHardBlocks 可被测试 import（import 不 listen）
+const isMain = process.argv[1] && process.argv[1].endsWith('workflow-board-server.mjs');
+if (isMain) {
+  server.listen(PORT, '127.0.0.1', () => {
+    console.log(`workflow 看板: http://127.0.0.1:${PORT}  （Ctrl+C 停止；只读 workflow/，不写任何文件）`);
+  });
+}

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

@@ -0,0 +1,136 @@
+#!/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 } 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=L0 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);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/workflow-enums.mjs

@@ -1,6 +1,8 @@
 // workflow-enums 读取器——.agents/workflow-enums.txt 单源（2026-09-25 enum-single-source）
-// 消费方：workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs / fill-{intent,plan,spec}.mjs
-//   （check-loop.sh 为 POSIX sh，自行 sed 读取同文件，口径同本读取器的键）。
+// 消费方：check-loop.mjs / workflow-board-server.mjs / kb-search.mjs / gen-workflow-index.mjs /
+//         fill-{intent,plan,spec}.mjs（均经本读取器）。（2026-09-26 check-loop sh→node 迁移后，
+//         原先的 sh sed 消费方已退役——全部消费方统一经本读取器，无跨语言读取口径；S11 测试仍守
+//         「空格分隔 + # 注释」格式对简单工具保持可解析）
 // fail-loud 无 fallback：kit 自带该文件，缺失/坏数据属安装破损——直接抛错崩得可见，
 //   doctor §2 布局门同时把关文件存在性。禁止在任何消费方内再抄一份枚举字面量。
 import fs from 'node:fs';