agentic-flow-kit 0.5.0 → 0.6.0

package/src/render.mjs

@@ -22,9 +22,13 @@ export function renderContent(text, vars) {
   return String(text || '').replace(PH_RE, (m, key) => (Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : m));
 }
 
-export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
+// renderTree：模板树渲染。opts.protectOwned=true 时（init --force 路径，2026-09-27 p2-batch1），
+// rel 命中 protectSet 且目标已存在 → 跳过覆盖并计入 protected 清单（owned「永不触碰」两态模型
+// 在 --force 路径的对齐；此前 force 覆盖一切同名文件曾实测静默丢用户自定义内容）
+export function renderTree(srcRoot, targetRoot, vars, { force = false, protectSet = null } = {}) {
   const written = [];   // { rel, sha256 }
   const skipped = [];   // rel（已存在，保守跳过）
+  const protectedSkipped = []; // rel（--force 下 owned 保护跳过）
   const warnings = [];  // 未知占位符等
   const dirs = [];
 
@@ -45,10 +49,17 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
         skipped.push(rel);
         continue;
       }
+      if (protectSet && protectSet.has(rel) && fs.existsSync(target)) {
+        protectedSkipped.push(rel);
+        continue;
+      }
       const raw = fs.readFileSync(abs);
       let out = raw;
       if (raw.length < 512 * 1024 && !raw.includes(0)) {
-        const replaced = renderContent(raw.toString('utf8'), vars);
+        // 文本面 LF 归一（2026-09-27 closing-coverage）：模板盘面 CRLF（autocrlf 检出 / 编辑器写入）与
+        // LF 克隆渲染出同一字节、同一 sha——fresh sha、装户落盘、kit.json 台账三方跨环境稳定；
+        // sync/doctor/source-sync-check 的读取侧归一（shaText）与本处写盘归一同口径闭合
+        const replaced = renderContent(raw.toString('utf8').replace(/\r\n/g, '\n'), vars);
         if (replaced.includes('{{')) {
           for (const m of replaced.matchAll(/\{\{([A-Z][A-Z0-9_]*)\}\}/g)) {
             if (!Object.prototype.hasOwnProperty.call(vars, m[1])) warnings.push(`${rel}: 未知占位符 {{${m[1]}}}（原样保留）`);
@@ -56,12 +67,61 @@ export function renderTree(srcRoot, targetRoot, vars, { force = false } = {}) {
         }
         out = Buffer.from(replaced, 'utf8');
       }
-      fs.writeFileSync(target, out);
+      fs.writeFileSync(target, out, { mode: rel.startsWith('.githooks/') ? 0o755 : 0o644 }); // 钩子带执行位（init-p1-batch P1-1：POSIX 装户 git 对不可执行钩子静默跳过）
       written.push({ rel: rel.split(path.sep).join('/'), sha256: sha256(out) });
     }
   })(srcRoot);
 
-  return { written, skipped, warnings, dirs };
+  return { written, skipped, protectedSkipped, warnings, dirs };
+}
+
+// renderPkgText：目标侧脚本执行防线的比对基准（2026-09-27 init-p1-batch P1-3）——读包源模板
+// （templates/_agents/<rel 去掉 .agents/ 前缀>）→ LF 归一 → {{VAR}} 渲染（脚本面无占位符时即原文）。
+// 返回 null = 包源无该模板或非文本面（无从校验，调用方按不可信处理）。
+export function renderPkgText(pkgRoot, rel, vars) {
+  if (!rel.startsWith('.agents/')) return null;
+  const tmpl = path.join(pkgRoot, 'templates', '_agents', rel.slice('.agents/'.length));
+  try {
+    const raw = fs.readFileSync(tmpl);
+    if (raw.length >= 512 * 1024 || raw.includes(0)) return null;
+    return renderContent(raw.toString('utf8').replace(/\r\n/g, '\n'), vars);
+  } catch {
+    return null;
+  }
+}
+
+// scriptTrusted：目标侧脚本是否与包源渲染值一致（LF 归一双侧 sha 比对，与 closing-coverage 六处口径同族）。
+// 返回 {ok, note}——ok=false 时 note 给出原因（预置/被改动/包源无模板/不可读），调用方跳过执行并显式提示。
+export function scriptTrusted({ pkgRoot, target, rel, vars }) {
+  const expected = renderPkgText(pkgRoot, rel, vars);
+  if (expected === null) return { ok: false, note: `包源无 ${rel} 模板，无法校验` };
+  const expSha = sha256(Buffer.from(expected, 'utf8'));
+  let actual;
+  try {
+    actual = fs.readFileSync(path.join(target, rel), 'utf8').replace(/\r\n/g, '\n');
+  } catch {
+    return { ok: false, note: `${rel} 不可读` };
+  }
+  if (sha256(Buffer.from(actual, 'utf8')) === expSha) return { ok: true, note: '' };
+  return { ok: false, note: `目标侧 ${rel} 与包源渲染值不符（预置或被改动）` };
+}
+
+// listTree(srcRoot)：只枚举模板树的目标相对路径（rel），不落盘、不算 sha——供 doctor 台账覆盖率检查复用。
+// 与 renderTree 完全同一套 relOf 映射（顶层 _ 前缀目录转点目录）与 .agents/cache 排除，避免两处映射漂移。
+export function listTree(srcRoot) {
+  const out = [];
+  (function walk(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relOf(abs, srcRoot) === '.agents/cache') continue;
+        walk(abs);
+        continue;
+      }
+      out.push(relOf(abs, srcRoot).split(path.sep).join('/'));
+    }
+  })(srcRoot);
+  return out;
 }
 
 export { sha256 };

package/src/run-tests.mjs

@@ -12,6 +12,9 @@ const nodeSuites = [
   'src/sync.test.mjs',
   'src/init.test.mjs',
   'src/pack.test.mjs',
+  // 宿主门禁模块回归（2026-09-27 host-gates-p1：dotnet-ca BRE 豁免/fail-closed + trae 强推 token 化）
+  'src/gate-dotnet-ca.test.mjs',
+  'src/trae-hooks.test.mjs',
   ...fs.readdirSync(path.join(ROOT, 'templates/_agents/scripts'))
     .filter((f) => f.endsWith('.test.mjs'))
     .sort()

package/src/sync-hosts.mjs

@@ -24,11 +24,12 @@ function splitFm(text) {
   return { fm: `---\n${m[1]}---\n`, body: m[2] };
 }
 
-// bodySha：剥离 frontmatter 后的正文段 sha256（缺失返 null）
+// bodySha：剥离 frontmatter 后的正文段 sha256（缺失返 null）；正文 LF 归一（2026-09-27 closing-coverage：
+// CRLF/LF 盘面同值——权威源与薄适配行尾不一致不再误报漂移，与 doctor §6.7 同口径）
 function bodySha(p) {
   try {
     const { body } = splitFm(fs.readFileSync(p, 'utf8'));
-    return sha256(Buffer.from(body, 'utf8'));
+    return sha256(Buffer.from(body.replace(/\r\n/g, '\n'), 'utf8'));
   } catch {
     return null;
   }

package/src/sync.mjs

@@ -3,12 +3,15 @@
 //       每次持续报告直至 --force 或本地对齐新版——防跳过一次后下次升级被静默覆盖，2026-09-24 语义修正）；
 //       生成器目标（INDEX.md / wiki 看板）→ 不比对，收尾重跑生成器走锚点重写。
 // 附带：包内新增 managed 文件 → 安装；包内已删 → 仅报告不删盘、出台账；managed 缺失 → 恢复。
+// 台账外文件收养（2026-09-26 managed-ledger-adopt）：盘上存在但台账无该 rel 的 managed 类文件，
+//       若内容恰好等于新版渲染 sha（diskSha === fresh.sha）则收养登记——判据与台账内「改动恰好等于新版」
+//       分支同源，不存在本地独有信息可被破坏；内容不等（本地真改动）仍保守跳过且台账不登记（持续报告）。
 // owned 文件永不触碰（两态模型，见 profiles.isOwned）。
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
-import { renderTree, sha256 } from './render.mjs';
+import { renderTree, sha256, scriptTrusted } from './render.mjs';
 import { HOSTS, pickStackVars, isOwned } from './profiles.mjs';
 import { doctor } from './doctor.mjs';
 
@@ -22,6 +25,19 @@ function runNode(target, script, args = []) {
   return { ok: r.status === 0, out: `${r.stdout || ''}${r.stderr || ''}` };
 }
 
+// shaText：文本件 LF 归一哈希（managed 记账与比对统一口径，2026-09-27 closing-coverage——跨 checkout
+// 字节稳定：CRLF 盘面（autocrlf 检出/Edit 工具写入）与 LF 克隆同值；renderTree 写盘本为 LF，
+// fresh sha 天然归一，故 ledger 记 fresh sha 后两侧自洽）
+const shaText = (p) => sha256(Buffer.from(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
+
+// 钩子文件落盘补执行位（init-p1-batch P1-1）：copyFileSync 不携带 mode，POSIX 装户 git 对不可执行钩子
+// 静默跳过；FAT/网络盘 chmod 不支持时降级不中断安装
+const safeChmod = (p) => { try { fs.chmodSync(p, 0o755); } catch { /* 降级 */ } };
+const copyManaged = (freshFile, disk, rel) => {
+  fs.copyFileSync(freshFile.abs, disk);
+  if (rel.startsWith('.githooks/')) safeChmod(disk);
+};
+
 export function sync(args, pkgRoot) {
   let target = process.cwd();
   let force = false;
@@ -60,7 +76,7 @@ export function sync(args, pkgRoot) {
     }
 
     const ledger = new Map((kit.managed || []).map((f) => [f.rel, f.sha256]));
-    const updated = [], skipped = [], restored = [], added = [], removed = [], newOwned = [];
+    const updated = [], skipped = [], restored = [], added = [], removed = [], newOwned = [], adopted = [];
     let unchanged = 0;
     const managedNew = [];
 
@@ -72,26 +88,29 @@ export function sync(args, pkgRoot) {
         removed.push(rel);
         continue; // 包内已删：文件留在盘上，出台账（下次不再跟踪）
       }
-      const diskSha = fs.existsSync(disk) ? sha256(fs.readFileSync(disk)) : null;
+      const diskSha = fs.existsSync(disk) ? shaText(disk) : null;
       if (diskSha === null) {
         fs.mkdirSync(path.dirname(disk), { recursive: true }); // 父目录可能整目录缺失（如 localOnly 宿主目录被清），copyfile 不建目录
-        fs.copyFileSync(freshFile.abs, disk);
+        copyManaged(freshFile, disk, rel);
         restored.push(rel);
         managedNew.push({ rel, sha256: freshFile.sha });
         continue;
       }
       if (diskSha === ledgerSha) {
-        if (freshFile.sha === ledgerSha) { unchanged++; managedNew.push({ rel, sha256: ledgerSha }); }
-        else { fs.copyFileSync(freshFile.abs, disk); updated.push(rel); managedNew.push({ rel, sha256: freshFile.sha }); }
+        if (freshFile.sha === ledgerSha) {
+          unchanged++; managedNew.push({ rel, sha256: ledgerSha });
+          if (rel.startsWith('.githooks/')) safeChmod(disk); // 存量装户 0644 死钩子升级修复（复核 P2-3）
+        }
+        else { copyManaged(freshFile, disk, rel); updated.push(rel); managedNew.push({ rel, sha256: freshFile.sha }); }
         continue;
       }
       // 本地已改
       if (freshFile.sha === diskSha) { unchanged++; managedNew.push({ rel, sha256: diskSha }); continue; } // 改动恰好等于新版
-      if (force) { fs.copyFileSync(freshFile.abs, disk); updated.push(`${rel}（--force 覆盖本地改动）`); managedNew.push({ rel, sha256: freshFile.sha }); }
+      if (force) { copyManaged(freshFile, disk, rel); updated.push(`${rel}（--force 覆盖本地改动）`); managedNew.push({ rel, sha256: freshFile.sha }); }
       else { skipped.push(rel); managedNew.push({ rel, sha256: ledgerSha }); } // 台账保持包侧基线：持续报告「本地已改」，直到 --force 或本地对齐新版
     }
 
-    // 台账外的新文件：managed 类安装；owned 类只对「盘上缺失」的起步文档报告（已装的不动不报）
+    // 台账外的新文件：managed 类安装 / 收养；owned 类只对「盘上缺失」的起步文档报告（已装的不动不报）
     for (const [rel, freshFile] of fresh) {
       if (ledger.has(rel)) continue;
       if (isOwned(rel)) {
@@ -99,9 +118,18 @@ export function sync(args, pkgRoot) {
         continue;
       }
       const disk = path.join(target, rel);
-      if (fs.existsSync(disk) && !force) { skipped.push(`${rel}（已存在未入台账）`); continue; }
+      if (fs.existsSync(disk)) {
+        // 盘上有、台账无：内容恰好等于新版 → 收养登记（与台账内「改动恰好等于新版」同判据）；
+        // 内容不等 = 本地真改动 → 默认保守跳过且不登记（下次仍报「未入台账」，不会被静默覆盖）；
+        // --force 下按既有语义覆盖并登记（与台账内文件的 --force 行为一致）
+        const diskSha = shaText(disk);
+        if (diskSha === freshFile.sha) { adopted.push(rel); managedNew.push({ rel, sha256: diskSha }); }
+        else if (force) { copyManaged(freshFile, disk, rel); added.push(rel); managedNew.push({ rel, sha256: freshFile.sha }); }
+        else skipped.push(`${rel}（已存在未入台账）`);
+        continue;
+      }
       fs.mkdirSync(path.dirname(disk), { recursive: true });
-      fs.copyFileSync(freshFile.abs, disk);
+      copyManaged(freshFile, disk, rel);
       added.push(rel);
       managedNew.push({ rel, sha256: freshFile.sha });
     }
@@ -110,24 +138,27 @@ export function sync(args, pkgRoot) {
     list('覆盖更新', updated);
     list('恢复缺失', restored);
     list('新增安装', added);
+    list('收养登记', adopted);
     list('本地已改，跳过', skipped);
     if (skipped.some((s) => !s.includes('未入台账'))) console.log('    ↑ --force 覆盖本地改动；git diff 自查差异；台账保持包侧基线，后续 sync 持续报告直至处理');
     list('包内已移除（文件保留在盘上，可手动删除）', removed);
     list('新增 owned 起步文档（项目自持，未自动安装）', newOwned);
-    if (!updated.length && !restored.length && !added.length && !removed.length && !skipped.length && !newOwned.length) {
+    if (!updated.length && !restored.length && !added.length && !adopted.length && !removed.length && !skipped.length && !newOwned.length) {
       console.log(`  已是最新（${unchanged} 份 managed 无变化）`);
     } else {
       console.log(`  无变化 ${unchanged} 份`);
     }
 
     // owned 台账按盘面自愈：owned 归项目所有，哈希只是记账不是约束——手改后无须手工刷 kit.json
-    // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）
+    // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）。
+    // sha 按 LF 归一记（与 doctor checkOwnedDrift 同口径，2026-09-27 gate-coverage：跨 checkout 字节稳定）
+    const ownedSha = (p) => sha256(Buffer.from(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
     let ownedRefreshed = 0;
     if (Array.isArray(kit.owned)) {
       kit.owned = kit.owned.map((f) => {
         const p = path.join(target, f.rel);
         if (!fs.existsSync(p)) return f;
-        const disk = sha256(fs.readFileSync(p));
+        const disk = ownedSha(p);
         if (disk === f.sha256) return f;
         ownedRefreshed++;
         return { ...f, sha256: disk };
@@ -140,14 +171,27 @@ export function sync(args, pkgRoot) {
     kit.version = pkg.version;
     fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
 
-    // 生成器目标走锚点重写（不参与 sha 比对）
-    const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
-    if (genIndex.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-workflow-index.mjs'))) {
-      console.log(genIndex.ok ? '  已重生成 workflow/INDEX.md（锚点内重写）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
+    // 生成器目标走锚点重写（不参与 sha 比对）——执行前过供应链防线（init-p1-batch P1-3）：
+    // 目标侧脚本与包源渲染值 sha 一致才执行（预置/被改动的脚本不可信，跳过并显式提示）
+    const genGuard = (rel) => {
+      const g = scriptTrusted({ pkgRoot, target, rel, vars });
+      if (!g.ok) {
+        console.log(`  ⚠️ 跳过执行 ${rel}——${g.note}（供应链防线：只执行与包源渲染值一致的目标侧脚本）`);
+        return false;
+      }
+      return true;
+    };
+    if (genGuard('.agents/scripts/gen-workflow-index.mjs')) {
+      const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
+      if (genIndex.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-workflow-index.mjs'))) {
+        console.log(genIndex.ok ? '  已重生成 workflow/INDEX.md（锚点内重写）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
+      }
     }
-    const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
-    if (genBoard.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
-      console.log(genBoard.ok ? '  已重生成 wiki 速览与看板 DATA（锚点内重写）' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+    if (genGuard('.agents/scripts/gen-wiki-board.mjs')) {
+      const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
+      if (genBoard.ok || fs.existsSync(path.join(target, '.agents/scripts/gen-wiki-board.mjs'))) {
+        console.log(genBoard.ok ? '  已重生成 wiki 速览与看板 DATA（锚点内重写）' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+      }
     }
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });

package/src/sync.test.mjs

@@ -1,6 +1,7 @@
 // sync.test.mjs — flow-kit sync 三态升级 + add-host / add-gate 行为验证。
 // 方法：迷你 fixture 包根（小模板树 + 假宿主 zcode + 假门禁 fakeg）+ 手工模拟 v1 安装态（kit.json 台账 + 盘面），
 // 子进程 driver 调真实 sync/add-host/add-gact（隔离 process.exit 与 doctor 尾部退出），断言盘面 + 台账 + stdout 标记。
+// 场景 14：台账外文件收养（2026-09-26 managed-ledger-adopt）——内容==新版才登记，本地真改动仍跳过。
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -252,5 +253,46 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S13 恢复有报告标记', out.includes('恢复缺失'), out);
 }
 
+// ============ 场景 14：台账外文件收养（2026-09-26 managed-ledger-adopt） ============
+// 盘上有 managed 类文件但台账无该条目（旧版手动双写绕过 init/sync 登记）。收养判据与台账内
+// 「改动恰好等于新版」同源：diskSha === 新版渲染 sha 才登记；内容不等（本地真改动）仍保守跳过。
+{
+  // ①盘上有、台账无、内容 == 新版 → 收养登记
+  const fx = mkFixture(), t = mkTarget(fx);
+  W(path.join(t, '.agents/scripts/chg.txt'), 'chg v2 port 777\n'); // == 新版渲染
+  // 把它从台账里剔除，伪造「盘上有但未登记」
+  const k0 = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  k0.managed = k0.managed.filter((f) => f.rel !== '.agents/scripts/chg.txt');
+  W(path.join(t, '.agents/kit.json'), `${JSON.stringify(k0, null, 2)}\n`);
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S14① 内容==新版 → 收养登记（报告标记）', out.includes('收养登记') && out.includes('chg.txt'), out);
+  const kit1 = JSON.parse(R(path.join(t, '.agents/kit.json')));
+  check('S14① 收养后入台账且 sha=盘面', (() => {
+    const e = kit1.managed.find((f) => f.rel === '.agents/scripts/chg.txt');
+    return e && e.sha256 === sha256(Buffer.from('chg v2 port 777\n'));
+  })(), JSON.stringify(kit1.managed));
+  check('S14① 收养不改盘面（内容原样）', R(path.join(t, '.agents/scripts/chg.txt')) === 'chg v2 port 777\n');
+
+  // ②盘上有、台账无、内容 != 新版 → 不收养、不覆盖、台账不登记
+  const fx2 = mkFixture(), t2 = mkTarget(fx2);
+  W(path.join(t2, '.agents/scripts/chg.txt'), 'chg LOCAL EDIT\n'); // 本地真改动
+  const k1 = JSON.parse(R(path.join(t2, '.agents/kit.json')));
+  k1.managed = k1.managed.filter((f) => f.rel !== '.agents/scripts/chg.txt');
+  W(path.join(t2, '.agents/kit.json'), `${JSON.stringify(k1, null, 2)}\n`);
+  const r2 = runCmd('sync', fx2, t2);
+  const out2 = r2.stdout + r2.stderr;
+  check('S14② 内容!=新版 → 不收养（不报收养登记）', !out2.includes('收养登记'), out2);
+  check('S14② 本地改动幸存未被覆盖', R(path.join(t2, '.agents/scripts/chg.txt')) === 'chg LOCAL EDIT\n', out2);
+  const kit2 = JSON.parse(R(path.join(t2, '.agents/kit.json')));
+  check('S14② 台账不登记（持续报告，防下次静默覆盖）', !kit2.managed.some((f) => f.rel === '.agents/scripts/chg.txt'));
+  check('S14② 报「已存在未入台账」跳过', out2.includes('已存在未入台账'), out2);
+
+  // ③盘上无、台账无 → 新增安装（既有行为不回归）
+  const fx3 = mkFixture(), t3 = mkTarget(fx3);
+  const r3 = runCmd('sync', fx3, t3);
+  check('S14③ 盘上无 → 新增安装（既有行为不回归）', (r3.stdout + r3.stderr).includes('新增安装') && R(path.join(t3, '.agents/commands/new.txt')) === 'new in v2\n');
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
 process.exit(failCount ? 1 : 0);

package/src/trae-hooks.test.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+// trae-hooks.test.mjs — trae 宿主 hook 判定回归（2026-09-27 host-gates-p1，incident 三件套「防复发验证」落点）
+// 方法：stdin JSON 注入 spawn pre-shell-check.cjs（RunCommand 形态），断言 permissionDecision。
+// 场景对位：P1-B2 强推 token 化（换序 / +refspec / --force-with-lease 放行 / -f）+ 既有 deny/ask 回归 +
+//       非 push 命令带 --force 不误拦（如 dotnet build --force）。
+// 注：127 未装分支（P2-B4）需 .githooks 脚本缺失形态，经 isCommit 路径覆盖——单独场景构造 cwd 指向
+//     无 .githooks 的临时目录跑 git commit，断言「门禁未执行」而非「未通过」。
+// 用法：node src/trae-hooks.test.mjs（npm test 随跑）
+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';
+
+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 PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HOOK = path.join(PKG_ROOT, 'modules', 'hosts', 'trae', 'hooks', 'pre-shell-check.cjs');
+
+const runHook = (command, cwd) => {
+  const payload = JSON.stringify({
+    tool_name: 'RunCommand',
+    tool_input: { command },
+    cwd: cwd || process.cwd(),
+  });
+  const r = spawnSync(process.execPath, [HOOK], { input: payload, encoding: 'utf8', timeout: 30000 });
+  let decision = 'none';
+  let reason = '';
+  try {
+    const j = JSON.parse((r.stdout || '').trim().split('\n').pop() || '{}');
+    decision = j?.hookSpecificOutput?.permissionDecision || 'none';
+    reason = j?.hookSpecificOutput?.permissionDecisionReason || '';
+  } catch { /* 无输出 = 放行 */ }
+  return { decision, reason, raw: r.stdout || '', status: r.status };
+};
+
+// ---- ① 强推 token 化（P1-B2）----
+{
+  const cases = [
+    ['git push --force', 'deny', '标准序'],
+    ['git push origin main --force', 'deny', '换序（旧代码漏拦形态）'],
+    ['git push origin +main', 'deny', '+refspec 变体'],
+    ['git push -f', 'deny', '短旗标'],
+    ['git -c x=y push origin main --force', 'deny', '全局参前缀'],
+    ['git push -vf origin main', 'deny', '组合短旗标 -vf（复核 P2-1）'],
+    ['git push origin main && dotnet build --force', 'none', '跨 && 的 --force 属他命令不误并（复核 P2-3）'],
+    ['git push origin main --force-with-lease', 'none', '--force-with-lease 精确 token 不误拦'],
+    ['git push origin main', 'none', '普通 push 放行'],
+    ['dotnet build --force', 'none', '非 push 命令带 --force 不误拦'],
+  ];
+  for (const [cmd, expect, label] of cases) {
+    const r = runHook(cmd);
+    check(`①${label}（${cmd}）→ ${expect === 'none' ? '放行' : expect}`,
+      r.decision === expect,
+      `decision=${r.decision} reason=${r.reason}`);
+  }
+}
+// ①附：换序强推的 deny 理由点名红线
+{
+  const r = runHook('git push origin main --force');
+  check('①换序强推 deny 理由点名禁强制推送', r.decision === 'deny' && /强制推送/.test(r.reason), r.reason);
+}
+
+// ---- ② 既有 deny/ask 回归（token 边界口径不动）----
+{
+  const cases = [
+    ['git reset --hard HEAD~1', 'deny'],
+    ['drop database MyDb', 'deny'],
+    // 'dotnet ef' 已从 deny 清单移除（p2-batch2：对齐 settings.json 权威清单——settings.json 无此项）
+    ['dotnet ef database update', 'none'],
+    ['git checkout main', 'ask'],
+    ['rm -rf tmp/', 'ask'],
+    ['git status', 'none'],
+    ['git commit -m "fix: 修复"', 'none'], // commit 走 .githooks 链（本仓有钩子且全绿）；deny 门本身不应拦 commit
+  ];
+  for (const [cmd, expect] of cases) {
+    const r = runHook(cmd, PKG_ROOT); // cwd=本仓：git commit 场景能找到 .githooks
+    check(`②${cmd} → ${expect === 'none' ? '不因 deny/ask 门拦' : expect}`,
+      r.decision === expect,
+      `decision=${r.decision} reason=${r.reason}`);
+  }
+}
+
+// ---- ②附 消息字样误触（p2-batch2）：带引号多词消息内含禁词 → 剥引号整段后不再误 deny/ask ----
+{
+  const cases = [
+    ['git commit -m "fix: 修 git push --force 误拦"', 'none', 'deny 词在引号消息内'],
+    ['git commit -m "docs: 补 git clean 说明"', 'none', 'ask 词在引号消息内'],
+    ['git commit -m "真正要拦的消息"', 'none', '普通消息照常'],
+  ];
+  for (const [cmd, expect, label] of cases) {
+    const r = runHook(cmd, PKG_ROOT);
+    check(`②附 ${label} → ${expect === 'none' ? '不误拦' : expect}`,
+      r.decision === expect,
+      `decision=${r.decision} reason=${r.reason}`);
+  }
+}
+
+// ---- ③ 127 未装区分（P2-B4）：无 .githooks 的 cwd 跑 git commit → 「门禁未执行」----
+{
+  const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'trae-hook-test-'));
+  const r = runHook('git commit -m "x"', empty);
+  check('③.githooks 缺失 → deny 且理由为「门禁未执行/不可达」（非违例误报）',
+    r.decision === 'deny' && /门禁未执行|不可达/.test(r.reason),
+    `decision=${r.decision} reason=${r.reason}`);
+  fs.rmSync(empty, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/AGENTS.md

@@ -27,6 +27,7 @@
 - **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
 - 项目专属门禁挂 `.agents/hooks/local-pre-commit`。
 - 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）；L1+ 入口文档 / spec / plan 随代码同一提交；确认（approved）后立即 `docs(*)` 单独提交留痕。
+- **确认门（2026-09-27 起）**：intent/spec/plan 的 approved/done 与 incident 的 fixed/closed（2026-09-28 起，open→fixed / fixed→closed 两跳、无单跳）唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`，放弃态走显式 `--to superseded|cancelled`（cancelled 自 draft/approved/open/fixed；superseded 自 approved/done/fixed/closed——四终态同样内容绑定），两形态：① 用户终端亲手运行键入「可以」（TTY，AI 会话内被拒）；② **对话委托代录**——用户在对话内明确确认后，AI 跑 `confirm-doc.mjs <path> --delegated "<用户原话>"` 逐件代录（一次一份，「逐件确认」口径——多份并录被拒），台账如实记 `source: chat-delegated` + 原话供对质，永不伪装 TTY 行（check-loop 15 指纹+台账对账拦截，与 source 无关）。
 
 ### 检索、看板与量化
 

package/templates/_agents/board/index.html

@@ -202,7 +202,8 @@ let Q = '';                // 搜索过滤关键字
 const $ = (s) => document.querySelector(s);
 const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
 // —— 精细化徽标：验收进度 / 配对断裂 ⚠ / 进行中老化 ——
-const ACTIVE_STATUSES = ['draft', 'approved', 'open'];
+// 活跃集默认值仅在 /api/board 首包前兜底；首包后由载荷 activeStatuses 覆盖（枚举单源贯通，p2-batch2）
+let ACTIVE_STATUSES = ['draft', 'approved', 'open'];
 const ageClass = (c) => {
   if (!ACTIVE_STATUSES.includes(c.status)) return '';
   const d = new Date(c.date);
@@ -273,6 +274,7 @@ async function refreshBoard() {
   }
   CARDS = data.cards;
   ROOT = data.root || ROOT;
+  if (Array.isArray(data.activeStatuses) && data.activeStatuses.length) ACTIVE_STATUSES = data.activeStatuses;
   CURRENT = CARDS.find((c) => c.file === CURRENT?.file) ?? CURRENT; // 重定位抽屉卡片，避免刷新后徽标/状态陈旧
   for (const t of Object.keys(TYPE_LABEL)) $(`#c-${t}`).textContent = `${TYPE_LABEL[t]} ${data.counts[t] ?? 0}`;
   const groups = Object.fromEntries(COLS.map((c) => [c.key, []]));
@@ -289,6 +291,21 @@ async function refreshBoard() {
   const ca = $('#c-alerts');
   ca.style.display = nAlerts ? '' : 'none';
   if (nAlerts) { ca.textContent = `⚠ 断档 ${nAlerts}`; ca.style.color = 'var(--bad)'; }
+  // hard-block 全局告警条（单源 check-loop，2026-09-27 board-kb-p1）：check-loop hard 项自动跟随
+  let loopBar = $('#loop-alerts');
+  if (!loopBar) {
+    loopBar = document.createElement('div');
+    loopBar.id = 'loop-alerts';
+    loopBar.style.cssText = 'display:none;background:var(--bad);color:#fff;padding:6px 14px;font-size:12px;line-height:1.7;white-space:pre-wrap;';
+    document.body.insertBefore(loopBar, document.body.firstChild);
+  }
+  if (data.loopHardBlocks === null) {
+    loopBar.style.display = ''; loopBar.textContent = `⚠ 闭环校验不可用（${data.loopNote || '未知原因'}）——hard-block 面暂不可见`;
+  } else if (data.loopHardBlocks.length) {
+    loopBar.style.display = ''; loopBar.textContent = `⛔ 闭环 hard-block ${data.loopHardBlocks.length} 项（单源 check-loop）：\n` + data.loopHardBlocks.join('\n');
+  } else {
+    loopBar.style.display = 'none';
+  }
   const cardHtml = (fam, extra = '') => {
     const h = fam.head;
     return `<div class="card ${ageClass(h)}${EXPANDED.has(fam.slug) || q ? ' open' : ''}" data-slug="${esc(fam.slug)}" style="border-left-color:${TYPE_COLOR[h.type]}">` +
@@ -336,10 +353,16 @@ async function loadDoc() {
   if (error) { $('#d-body').innerHTML = `<div class="none">${esc(error)}</div>`; return; }
   // 裸 .md 相对路径引用 → 可点链接（workflow 文档互引多为纯文本路径而非 md 链接语法；
   // 已有 ](path) 链接语法因前缀为 ] 不会被重复包裹）
-  const linked = text.replace(
+  let linked = text.replace(
     /(^|[\s（(【>])((?:\.\.\/|\.\/)?(?:intents|incidents|plans|specs)\/[A-Za-z0-9_\-./]+\.md)/g,
     '$1[$2]($2)'
   );
+  // XSS 防线（2026-09-27 p2-batch2）：vendored marked v12 默认放行内嵌 HTML，文档由 AI 起草
+  // （外部内容可经 prompt 注入落盘）——渲染前剥全部裸 HTML 标签，markdown 语法不受影响
+  // （已知误伤：代码块内联 HTML 与散文 `<...>` 跨度会被剥，只读预览可接受——源文件不损）。
+  // 残余面：markdown 链接 href（javascript:/data:）不经本剥离，靠 onDocLink 对 #d-body a 一律
+  // preventDefault + 非 http(s) 转 vscode://file 中和——改 onDocLink 拦截链路前先读本注释。
+  linked = linked.replace(/<[^>]*>/g, '');
   $('#d-body').innerHTML = `<div class="md">${marked.parse(linked)}</div>`;
 }
 
@@ -438,7 +461,13 @@ sse.onerror = () => { $('#sse').classList.remove('on'); $('#sse span:last-child'
 setInterval(() => refreshBoard(), 60000);
 
 // 搜索过滤：本地过滤标题/slug/文件，SSE 刷新时保持关键字
-$('#q').addEventListener('input', (e) => { Q = e.target.value; refreshBoard(); });
+// 击键去抖 400ms（复核 P2-2 rider）：/api/board 服务端有 loop TTL 缓存，去抖进一步避免连发请求排队
+let qTimer = null;
+$('#q').addEventListener('input', (e) => {
+  Q = e.target.value;
+  clearTimeout(qTimer);
+  qTimer = setTimeout(refreshBoard, 400);
+});
 
 // 首次入场：列错峰上浮一次（.boot 稍后摘除，SSE / 过滤触发的重渲染不再重播）
 $('#board').classList.add('boot');

package/templates/_agents/commands/build.md

@@ -31,7 +31,8 @@ next: .agents/commands/test.md
    - L2/L3 按 4 节填写:任务拆解(每个任务有判据) / 风险评估 / 执行顺序 / 遗留项
    - L1 默认极简两节:改动面(逐条文件+做什么) / 验证方式(一行静态门+按需 UI 实测)；仅多文件多步骤时再加任务拆解/执行顺序
    - 仍须与入口文档同名落盘
-3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件),且相邻同 quote 连跑触发 check-loop 15 并录告警(见 workflow/papercuts.md 2026-09-28)
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
 4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 
 ### 进计划模式列改动
@@ -65,9 +66,7 @@ next: .agents/commands/test.md
 
 ## 改权威源后必跑（薄适配同步防漏）
 
-- 改 `templates/_agents/commands/*.md` 或 `templates/_agents/roles/*.md` 正文后 → 跑 `node bin/flow-kit.mjs sync-hosts --diff` 看正文段漂移 → 用户拍板 → `node bin/flow-kit.mjs sync-hosts --apply` 单向同步（薄适配正文 = 权威源正文，frontmatter 不动）；详见 `.agents/commands/sync-hosts.md`
-- 改 frontmatter（薄适配特化字段如 trae `name: wf-X`）不需同步——apply 只动正文段
-- 改 trae 钩子 / 规则 / 包源其他文件不在本工具范围
+- 改 `templates/_agents/{commands,roles}/*.md` 正文后跑 `node bin/flow-kit.mjs sync-hosts --diff` → 拍板 → `--apply` 单向同步（只动正文段，frontmatter 不动）；口径与边界详见 `.agents/commands/sync-hosts.md`
 
 ## 改 doctor / check-loop 后必跑（三处口径对账）
 
@@ -79,6 +78,8 @@ next: .agents/commands/test.md
 
 - 改 `templates/_agents/*` 包源后 → 跑 `node .agents/scripts/source-sync-check.mjs --diff` 看装副本 `.agents/` 是否同步（缺失 / 孤儿 / 漂移三类差异）
 - 漂移说明包源改了装副本未跟；缺失说明新增文件 init 未执行；孤儿说明装副本独有（可能是装户配置，不删）
+- **新增 managed 类文件须经 init/sync 登记，禁手动双写绕过台账**——手工同时写 `templates/_agents/` 与 `.agents/` 会绕过台账登记，使该文件永远不被 sync 升级（`doctor` 台账覆盖率检查会拦；见 incidents/2026-09-26-managed-ledger-adopt 复盘）
+- 门禁边界（pre-commit 双源一致性）：比较工作树非暂存区——两侧改好、分两笔提交不拦（最终一致即可）；包源删除文件退化为「孤儿」只报告不拦，删包源须手动清理装副本残件（复核 P2-2 声明，2026-09-27 gate-hardening-p2-batch）
 - B-b 决策「只报告不修复」；详见 `.agents/commands/source-sync-check.md`
 
 ## 子代理调用约定

package/templates/_agents/commands/design.md

@@ -51,5 +51,6 @@ next: .agents/commands/build.md
 ## 确认后
 
 - spec 状态 draft → approved
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
 - 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 - 进 `next: .agents/commands/build.md`

package/templates/_agents/commands/maintain.md

@@ -86,6 +86,5 @@ next: .agents/commands/plan.md(若复盘需要新 intent)
 
 ## 确认后
 
-- incident 状态 → fixed(三件套全落地)
-- 防复发用例通过后 → closed
+- incident 状态 → fixed(三件套全落地)；防复发用例通过后 → closed——两跳均走确认门 `node .agents/scripts/confirm-doc.mjs <path>`（open→fixed / fixed→closed，无单跳；2026-09-28 起 check-loop 15 对账，AI 不得直改状态）
 - 若需新 intent → 进 `next: .agents/commands/plan.md`

package/templates/_agents/commands/plan.md

@@ -29,6 +29,8 @@ next: L1 → .agents/commands/build.md ；L2/L3 → .agents/commands/design.md
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认
 
+   **确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——关单编辑（勾验/回填）先于 done 确认、confirm-doc 是最后一次写入，此后修订走 superseded 或新 intent。
+
 ## 技能辅助(可选,宿主级 skills)
 
 - 需求模糊、判据写不出时:用 `grilling`/`grill-me` 拷问需求,答完回填 6 节

package/templates/_agents/commands/test.md

@@ -75,7 +75,8 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 - **关单**（日常闭环点，不依赖是否上 prod）:
   - 关单前一键过门：`node .agents/scripts/verify.mjs`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」，intent → done；同名 spec（若有）仍 approved → done
-  - 修复：防复发验证已落地，incident → closed
+**确认落态唯一入口**（2026-09-27 起）：用户在终端跑 `node .agents/scripts/confirm-doc.mjs <path>` 键入「可以」（draft→approved / approved→done；对话内明确确认后 AI 可 `--delegated "<原话>"` 代录，台账如实记 source/quote——**逐件调用 + 逐件原话**（一次一份，build.md「逐件确认」口径；多份并录被 confirm-doc 拒绝。--delegated 每次传当次实际放行的措辞，不复用同句——复用同句使台账 quote 失去分辨力，且相邻同 quote 连跑会触发并录告警））。check-loop 15 如实口径：缺记录/指纹不配对 → hard-block 拦截；伪造台账本地不可机器防，留痕供事后对质；done 内容绑定（2026-09-28 起）——**关单编辑（勾验/回填确认结果）先于 done 确认、confirm-doc 是最后一次写入**，此后修订走 superseded 或新 intent。
+  - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
   - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
   - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）
 - L1：本阶段结束，不进 deploy