agentic-flow-kit 0.4.0 → 0.6.0

package/src/sync-hosts.test.mjs

@@ -0,0 +1,170 @@
+// sync-hosts.test.mjs — flow-kit sync-hosts B-b 语义四场景（2026-09-25）
+// 方法：迷你 fixture 包根（权威源 templates/_agents + 薄适配 modules/hosts/<h>/{agents,commands}/
+//       与权威源正文段一致，frontmatter 各异）+ 子进程 driver 调真实 sync-hosts（隔离 process.exit）
+// 判据：①全对齐 → inSync=28, drift 空  ②权威源改 → drift 列  ③apply → 正文一致，frontmatter 各自保留
+//       ④薄适配 frontmatter 手改 → 不进 drift  ⑤薄适配正文手改 → drift 列，apply 覆盖
+//       ⑥薄适配缺失 → authorityMissing 列；apply 不自动创建
+// 用法：node src/sync-hosts.test.mjs
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SRC_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)));
+
+let pass = 0, failCount = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { failCount++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+const W = (p, content) => { fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, content); };
+const R = (p) => fs.readFileSync(p, 'utf8');
+
+// ---- fixture 包根：权威源 + 4 宿主薄适配（正文段与权威源一致，frontmatter 各异） ----
+function mkFixture() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-'));
+  // 权威源（2 commands + 1 role，简化测试体量；权威源也带 frontmatter 保证 body 段含前导空行，与薄适配对齐）
+  W(path.join(root, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'templates/_agents/roles/implementer.md'),
+    `---\ndescription: Implementer 角色契约\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 薄适配：commands 权威源 → opencode + trae（trae 加 wf- 前缀 + name）
+  W(path.join(root, 'modules/hosts/opencode/commands/build.md'),
+    `---\ndescription: Build · opencode 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: Build · trae 风格\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/commands/test.md'),
+    `---\ndescription: Test · opencode 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  W(path.join(root, 'modules/hosts/trae/commands/wf-test.md'),
+    `---\nname: wf-test\ndescription: Test · trae 风格\n---\n\n# Test · v1\n\n权威源正文 test v1\n`);
+  // roles 权威源 → 4 宿主 agents（omp/zcode 中文风格 + trae name）
+  W(path.join(root, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: 在已批准工作包内实现\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/omp/agents/implementer.md'),
+    `---\nname: implementer\ndescription: omp 本机风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/opencode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: opencode 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  W(path.join(root, 'modules/hosts/trae/agents/implementer.md'),
+    `---\nname: implementer\ndescription: trae 英文风格\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
+  // 孤儿薄适配：权威源无对应文件
+  W(path.join(root, 'modules/hosts/opencode/commands/orphan.md'), '# orphan\n');
+  return root;
+}
+
+// ---- 子进程 driver：调真实 sync-hosts ----
+function runSyncHosts(fixtureRoot, extra = []) {
+  const driver = path.join(fixtureRoot, 'driver.mjs');
+  W(driver, `import { syncHosts } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync-hosts.mjs')).href)};
+const root = ${JSON.stringify(fixtureRoot)};
+syncHosts(process.argv.slice(2), root);
+`);
+  return spawnSync(process.execPath, [driver, ...extra], { encoding: 'utf8' });
+}
+
+// ============ 场景 1：全对齐（正文段与权威源一致，frontmatter 各异）→ drift 空 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S1 全对齐：正文对齐 8 对（2 commands×2 适配 + 1 role×4 宿主）', /正文对齐：\s*8\s*对/.test(out), out);
+  check('S1 全对齐：报告无漂移', /无漂移/.test(out), out);
+  check('S1 全对齐：exit 0', r.status === 0, `status=${r.status}`);
+}
+
+// ============ 场景 2：权威源改了正文，薄适配未跟 → drift 列 4 处（build→opencode+trae, test→opencode+trae）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  W(path.join(fx, 'templates/_agents/commands/test.md'),
+    `---\ndescription: Test 阶段\nstage: Test\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S2 权威源改了 → 正文漂移 4（build×2 + test×2）', /正文段漂移（4/.test(out), out);
+  check('S2 列出 opencode/commands/build.md', out.includes('commands/build.md → opencode/commands/build.md'), out);
+  check('S2 列出 trae/commands/wf-build.md（trae wf- 前缀映射）', out.includes('commands/build.md → trae/commands/wf-build.md'), out);
+  check('S2 正文对齐 = 4（1 role × 4 宿主 implementer 未改）', /正文对齐：\s*4\s*对/.test(out), out);
+  check('S2 exit 0（diff 模式不阻断）', r.status === 0);
+}
+
+// ============ 场景 3：apply 后正文段 sha 一致，frontmatter 各自保留 ============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'templates/_agents/commands/build.md'),
+    `---\ndescription: Build 阶段\nstage: Build\n---\n\n# Build · v2\n\n权威源正文 build v2\n`);
+  const r = runSyncHosts(fx, ['--apply']);
+  const out = r.stdout + r.stderr;
+  check('S3 apply：报告同步 2 份（opencode + trae）', /按权威源正文覆盖薄适配正文段\s*2\s*份/.test(out), out);
+  check('S3 apply：opencode 正文已同步到 v2', R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：trae 正文已同步到 v2', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：opencode frontmatter 保留（仍无 name 字段）', !R(path.join(fx, 'modules/hosts/opencode/commands/build.md')).match(/^name:/m));
+  check('S3 apply：trae frontmatter 保留（仍含 name: wf-build）', R(path.join(fx, 'modules/hosts/trae/commands/wf-build.md')).match(/^name:\s*wf-build/m) !== null);
+  check('S3 apply：权威源不动', R(path.join(fx, 'templates/_agents/commands/build.md')).includes('权威源正文 build v2'));
+  check('S3 apply：再次 diff 应显示对齐 8', true); // 二次扫描由 sync-hosts 内部做
+}
+
+// ============ 场景 4：薄适配 frontmatter 手改 → 不进 drift（正文段比对不受影响）============
+{
+  const fx = mkFixture();
+  // trae frontmatter description 改成"自定义"——正文段未动
+  W(path.join(fx, 'modules/hosts/trae/commands/wf-build.md'),
+    `---\nname: wf-build\ndescription: trae 自定义描述\n---\n\n# Build · v1\n\n权威源正文 build v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S4 frontmatter 差异不计正文段漂移', /正文对齐：\s*8\s*对/.test(out) && /无漂移/.test(out), out);
+}
+
+// ============ 场景 5：薄适配正文手改 → drift 列出，apply 覆盖（不污染权威源）============
+{
+  const fx = mkFixture();
+  W(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'),
+    `---\nname: implementer\ndescription: zcode 风格\n---\n\n# Implementer · v1\n\n薄适配手改 implementer v1\n`);
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S5 薄适配正文手改 → 正文段漂移 1', /正文段漂移（1/.test(out), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S5 apply 后：薄适配正文回到权威源（含「权威源正文 implementer v1」）', /权威源正文 implementer v1/.test(R(path.join(fx, 'modules/hosts/zcode/agents/implementer.md'))));
+  check('S5 apply 不污染权威源（权威源仍 v1）', !R(path.join(fx, 'templates/_agents/roles/implementer.md')).includes('薄适配手改'));
+  // apply 后再 diff 一次，diff 应显示"无漂移"
+  const r3 = runSyncHosts(fx, ['--diff']);
+  check('S5 apply 后再 diff 应无漂移', /无漂移/.test(r3.stdout + r3.stderr), r3.stdout + r3.stderr);
+}
+
+// ============ 场景 6：薄适配文件不存在 → authorityMissing 列出，apply 不创建 ============
+{
+  const fx = mkFixture();
+  fs.rmSync(path.join(fx, 'modules/hosts/opencode/commands/build.md'));
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/build.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/build.md')));
+}
+
+// ============ 场景 7：--json 机器可读输出 ============
+{
+  const fx = mkFixture();
+  const r = runSyncHosts(fx, ['--json']);
+  const out = r.stdout + r.stderr;
+  let parsed = null;
+  try { parsed = JSON.parse(out); } catch {}
+  check('S7 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.drift));
+  check('S7 --json 含 inSync = 8', parsed && parsed.inSync === 8, parsed ? JSON.stringify(parsed) : 'null');
+}
+
+// ============ 场景 8：孤儿薄适配（权威源无对应文件）→ adapterOrphans 列，apply 不删 ============
+{
+  const fx = mkFixture();
+  // orphan.md 已在 mkFixture 写入
+  const r = runSyncHosts(fx, ['--diff']);
+  const out = r.stdout + r.stderr;
+  check('S8 孤儿薄适配 → adapterOrphans 列', /孤儿薄适配（/.test(out) && out.includes('opencode/commands/orphan.md'), out);
+  const r2 = runSyncHosts(fx, ['--apply']);
+  check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')));
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

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,25 +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.copyFileSync(freshFile.abs, disk);
+        fs.mkdirSync(path.dirname(disk), { recursive: true }); // 父目录可能整目录缺失（如 localOnly 宿主目录被清），copyfile 不建目录
+        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)) {
@@ -98,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 });
     }
@@ -109,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 };
@@ -139,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';
@@ -242,5 +243,56 @@ else if (cmd === 'add-gate') addGate(rest, root);
   check('S12 有刷新报告', out.includes('owned 台账哈希按盘面刷新 1 份'), out);
 }
 
+// ============ 场景 13：managed 连同父目录整目录缺失 → 恢复并重建父目录（恢复分支 mkdir，2026-09-25） ============
+{
+  const fx = mkFixture(), t = mkTarget(fx);
+  fs.rmSync(path.join(t, '.zcode'), { recursive: true, force: true });
+  const r = runCmd('sync', fx, t);
+  const out = r.stdout + r.stderr;
+  check('S13 整目录缺失的 managed 被恢复（父目录重建）', R(path.join(t, '.zcode/h.txt')) === 'host v2 777\n', out);
+  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

@@ -19,7 +19,7 @@
 
 ### 子智能体
 
-公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。
+公共角色契约在 `.agents/roles/`（`implementer` / `independent-reviewer` / `ui-verifier`），各宿主经薄适配层（`.opencode/agents/`、`.trae/agents/`、`.zcode/agents/` 等）注册，宿主不支持子智能体时按命令 frontmatter 的 `fallback` 执行。子智能体不跨用户确认门、不替用户批准、不自行提交。多工作包编排（自动加载）：跑编排 / plan 执行多工作包时，读 `.agents/workflows/` 编排脚本按机制文档执行——stages 表（依赖分层 / 并行 / 重试 / gate）+ `steps/` 自定义步骤扩展点，见 `.agents/workflows/_TEMPLATE.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');