agentic-flow-kit 0.4.0 → 0.6.0

package/src/init.mjs

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { execSync, spawnSync } from 'node:child_process';
-import { renderTree, renderContent, sha256 } from './render.mjs';
+import { renderTree, renderContent, sha256, scriptTrusted, listTree } from './render.mjs';
 import { HOSTS, STACKS, STACK_ALIASES, settingsJson, commitCheckConfig, pickStackVars, isOwned } from './profiles.mjs';
 import { doctor } from './doctor.mjs';
 
@@ -112,7 +112,12 @@ async function interactive() {
       console.log(dim('  ⚠️ 没认出——序号或名称再来一次'));
     }
     console.log(`\n${cyan('── 3/3 · workflow 看板端口')}`);
-    const boardPort = (await p.ask(dim('  直接回车 = 8933'))) || '8933';
+    let boardPort = '';
+    for (;;) {
+      boardPort = (await p.ask(dim('  直接回车 = 8933'))) || '8933';
+      if (/^(0|[1-9]\d*)$/.test(String(boardPort)) && Number(boardPort) >= 1 && Number(boardPort) <= 65535) break;
+      console.log(dim('  ⚠️ 端口须为 1-65535 整数——再来一次'));
+    }
 
     console.log(`\n  ${bold(`宿主 ${hosts.join('、')}`)}${dim(' ｜ ')}${bold(`技术栈 ${stack}`)}${dim(' ｜ ')}${bold(`端口 ${boardPort}`)}`);
     const yes = await p.ask(dim('  确认安装到当前目录？(y/n，回车取消)'));
@@ -150,6 +155,10 @@ export async function init(args, pkgRoot) {
 
   opt.stack = normalizeStack(opt.stack);
   if (!STACKS[opt.stack]) fail(`未知技术栈：${opt.stack}（可选 dotnet | node（ts/js） | python | go | none——对应编译检查与自检验命令初值）`);
+  // 端口校验（2026-09-27 p2-batch1）：任意字符串曾直进 vars 渲染进 AGENTS.md（AI 每会话必读面）——1-65535 整数 fail-fast
+  if (!/^(0|[1-9]\d*)$/.test(String(opt.boardPort)) || Number(opt.boardPort) < 1 || Number(opt.boardPort) > 65535) {
+    fail(`--board-port 须为 1-65535 整数（现「${opt.boardPort}」）`);
+  }
   const hosts = opt.hosts.split(',').map((s) => s.trim()).filter(Boolean);
   for (const h of hosts) {
     if (!HOSTS[h]) fail(`未知宿主：${h}（可选 ${Object.keys(HOSTS).join(' | ')}）`);
@@ -167,12 +176,23 @@ export async function init(args, pkgRoot) {
   console.log(`${bold(cyan('▶ flow-kit init'))}${dim(' → ')}${target}`);
   console.log(`  宿主：${hosts.join(', ')} ｜ 技术栈：${opt.stack} ｜ 看板端口：${opt.boardPort}`);
 
-  // 1) 模板树（保守：已存在文件跳过，--force 覆盖）
-  const t = renderTree(path.join(pkgRoot, 'templates'), target, vars, { force: opt.force });
+  // 1) 模板树（保守：已存在文件跳过，--force 覆盖；p2-batch1：--force 下已存在 owned 仍跳过——
+  //    「项目自持」两态模型在重装路径的对齐，实测曾静默丢用户自定义「项目适配区」内容。
+  //    保护集 = 包源模板树内 isOwned 为真的 rel，现场枚举单源不另抄清单）
+  const protectSet = opt.force
+    ? new Set(listTree(path.join(pkgRoot, 'templates')).filter((rel) => isOwned(rel)))
+    : null;
+  const t = renderTree(path.join(pkgRoot, 'templates'), target, vars, { force: opt.force, protectSet });
+  for (const rel of t.protectedSkipped || []) {
+    console.log(`  跳过（owned 项目自持，--force 不覆盖）：${rel}——如需重置请手动删除后重跑`);
+  }
 
-  // 1.5) AGENTS.md 特例：已存在且无骨架标记 → 文末追加补齐（原内容保留）；带标记 → 保守跳过
+  // 1.5) AGENTS.md 特例：已存在且无骨架标记 → 文末追加补齐（原内容保留）；带标记 → 保守跳过。
+  //  门槛含 protectedSkipped（p2-batch1 复核 P1-2）：--force 下 owned 保护跳过也属「已存在不覆盖」，
+  //  无骨架时同样要追加（追加本就是非覆盖语义，与保护不冲突）——否则自带 AGENTS.md 的装户经
+  //  --force 重装永远拿不到工作流骨架且无感知
   let agentsMergedSha = null;
-  if (t.skipped.includes('AGENTS.md')) {
+  if (t.skipped.includes('AGENTS.md') || (t.protectedSkipped || []).includes('AGENTS.md')) {
     const agentsAbs = path.join(target, 'AGENTS.md');
     const existing = fs.readFileSync(agentsAbs, 'utf8');
     if (hasAgentsSkeleton(existing)) {
@@ -181,7 +201,8 @@ export async function init(args, pkgRoot) {
     } else {
       const incoming = renderContent(fs.readFileSync(path.join(pkgRoot, 'templates', 'AGENTS.md'), 'utf8'), vars);
       fs.writeFileSync(agentsAbs, mergeAgents(existing, incoming));
-      agentsMergedSha = sha256(fs.readFileSync(agentsAbs));
+      // LF 归一记账（init-p1-batch P1-4）：用户 CRLF 原文 + LF 追加的混合文件与 doctor §6.6 / sync ownedSha 同口径
+      agentsMergedSha = sha256(Buffer.from(fs.readFileSync(agentsAbs, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
       t.skipped = t.skipped.filter((r) => r !== 'AGENTS.md');
       console.log('  AGENTS.md 已存在但无工作流骨架——文末追加补齐（原内容保留，「项目适配区」照常自填）');
     }
@@ -192,6 +213,16 @@ export async function init(args, pkgRoot) {
   for (const h of hosts) {
     hostResults[h] = renderTree(path.join(pkgRoot, 'modules', 'hosts', h), path.join(target, HOSTS[h].dir), vars, { force: opt.force });
   }
+  // 换 --hosts 重装：旧宿主目录脱账提示（kit.json 只记新宿主，孤儿对 doctor §4.5 不可见——审查 P2-1 附带）
+  if (fs.existsSync(kitPath)) {
+    try {
+      const oldHosts = (JSON.parse(fs.readFileSync(kitPath, 'utf8')).options?.hosts) || [];
+      const removed = oldHosts.filter((h) => HOSTS[h] && !hosts.includes(h));
+      for (const h of removed) {
+        console.log(`  ⚠️ 旧宿主 ${HOSTS[h].dir}/ 不在新 --hosts 清单——其文件已脱账（成静默孤儿），如弃用请手动删除目录`);
+      }
+    } catch { /* 旧台账不可读（--force 重装修复场景），跳过提示 */ }
+  }
 
   // 3) 生成的 owned 基线配置（引擎按固定路径读取；存在则跳过，永不覆盖；技术栈命令由项目在文件内自填）
   const generated = {
@@ -231,13 +262,49 @@ export async function init(args, pkgRoot) {
     console.log('  ⚠️ 目标不是 git 仓库——钩子未挂载；git init 后手动执行：git config core.hooksPath .githooks');
   }
 
-  // 6) kit.json：managed（模板/适配层，升级可覆盖）与 owned（基线配置+起步文档，升级不动）台账
+  // 6) 生成器首跑（幂等）：workflow/INDEX.md 活跃层索引 + wiki 速览计数与看板 DATA
+  //    先于 kit.json 记账（init-p1-batch P1-2：生成器会重写 owned 起步文档，先跑后记账则 doctor §6.6 对账即绿，
+  //    fresh init 不再必现 owned FAIL / exit 1）；执行前过供应链防线（P1-3）——目标侧脚本与包源渲染值
+  //    sha 一致才执行（目标目录预置脚本不可信，「已存在保守跳过」语义下预置件会被原样保留）
+  const guardRun = (rel) => {
+    const g = scriptTrusted({ pkgRoot, target, rel, vars });
+    if (!g.ok) {
+      console.log(`  ⚠️ 跳过执行 ${rel}——${g.note}（供应链防线：只执行与包源渲染值一致的目标侧脚本）`);
+      return false;
+    }
+    return true;
+  };
+  if (guardRun('.agents/scripts/gen-workflow-index.mjs')) {
+    const genIndex = runNode(target, '.agents/scripts/gen-workflow-index.mjs');
+    console.log(genIndex.ok ? '  已生成 workflow/INDEX.md（活跃层索引）' : `  ⚠️ gen-workflow-index 失败：${genIndex.out.split('\n')[0]}`);
+  }
+  if (guardRun('.agents/scripts/gen-wiki-board.mjs')) {
+    const genBoard = runNode(target, '.agents/scripts/gen-wiki-board.mjs');
+    console.log(genBoard.ok ? '  已生成 wiki 速览计数与知识沉淀总览 DATA' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
+  }
+
+  // 7) kit.json：managed（模板/适配层，升级可覆盖）与 owned（基线配置+起步文档，升级不动）台账
+  //    owned 的生成器目标按生成后盘面重记（P1-2）；记账一律 LF 归一 sha（P1-4——render 写盘已归一，
+  //    生成器重写目标与用户合并文件两侧同口径，跨 checkout 字节稳定）
+  const shaText = (p) => sha256(Buffer.from(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
+  const GEN_TARGETS = new Set(['workflow/INDEX.md', 'wiki/INDEX.md', 'wiki/知识沉淀总览.html']); // 新增生成器目标须同步本清单
   const managed = [
     ...t.written.filter((f) => !isOwned(f.rel)),
     // 宿主文件渲染时相对宿主根，入台账须还原为项目根相对路径
     ...hosts.flatMap((h) => hostResults[h].written.map((f) => ({ ...f, rel: `${HOSTS[h].dir}/${f.rel}` }))),
   ];
-  const owned = [...t.written.filter((f) => isOwned(f.rel)), ...ownedGenerated];
+  const owned = [...t.written.filter((f) => isOwned(f.rel)), ...ownedGenerated]
+    .map((f) => (GEN_TARGETS.has(f.rel) && fs.existsSync(path.join(target, f.rel))
+      ? { ...f, sha256: shaText(path.join(target, f.rel)) }
+      : f));
+  // protectedSkipped 件按盘面 LF 归一 sha 补记（p2-batch1 复核 P2-3）：--force 重装受保护 owned
+  // 不补记会让 doctor §6.6 的漂移可见性静默消失（台账缺口对体检不可见）
+  for (const rel of t.protectedSkipped || []) {
+    if (!isOwned(rel) || !fs.existsSync(path.join(target, rel))) continue;
+    if (rel === 'AGENTS.md' && agentsMergedSha) continue; // 追加特例已记（agentsMergedSha），避免台账重复条目（复核收口 P2）
+    if (owned.some((f) => f.rel === rel)) continue;
+    owned.push({ rel, sha256: shaText(path.join(target, rel)) });
+  }
   if (agentsMergedSha) owned.push({ rel: 'AGENTS.md', sha256: agentsMergedSha });
   const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
   fs.mkdirSync(path.dirname(kitPath), { recursive: true });
@@ -251,14 +318,9 @@ export async function init(args, pkgRoot) {
   }, null, 2)}\n`);
   console.log(`  kit.json 台账：managed ${managed.length} 份 ｜ owned ${owned.length} 份（版本 ${pkg.version}）`);
 
-  // 7) 生成器首跑（幂等）：workflow/INDEX.md 活跃层索引 + wiki 速览计数与看板 DATA
-  const genIndex = runNode(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');
-  console.log(genBoard.ok ? '  已生成 wiki 速览计数与知识沉淀总览 DATA' : `  ⚠️ gen-wiki-board 失败：${genBoard.out.split('\n')[0]}`);
-
-  // 8) 自检
-  console.log('▶ flow-kit doctor');
+  // 8) 自检（kit.json 已按生成后盘面记账——doctor §6.6 应全绿，fresh init 以 exit 0 收场）
+  // 输出语义（p2-batch1 P2-4）：doctor 打印在异步端口回调里、晚于本横幅——脚本化消费方按退出码判定
+  console.log('▶ flow-kit doctor（安装产物已就位；体检 FAIL 时本命令 exit 1，产物无损——按 FAIL 项处置）');
   doctor(['--dir', target], pkgRoot);
 
   if (t.skipped.length) console.log(`  跳过（已存在，未覆盖）：${t.skipped.join('、')}`);

package/src/init.test.mjs

@@ -1,9 +1,16 @@
 #!/usr/bin/env node
-// init.mjs 交互解析纯函数测试（normalizeStack / parseChoices）——不触真实安装与 stdin
+// init.mjs 交互解析纯函数测试（normalizeStack / parseChoices）+ 装户面断言——解析层不触真实安装与 stdin；
+// 装户面节对真实 templates/ 树跑 renderTree（init/sync 同一装户路径），断言编排 runner 与 workflows 目录在装户清单内。
 // 断言：①ts/js 别名归一 node；②序号/名称/混输/全角逗号/空白分隔解析正确（去重保序）；
-//       ③非法输入返回 null（就地重问信号）；④空输入回默认（EOF/直接回车安全回退）。
+//       ③非法输入返回 null（就地重问信号）；④空输入回默认（EOF/直接回车安全回退）；⑥装户面含 runner/workflows。
 // 用法：node src/init.test.mjs
 import { normalizeStack, parseChoices, hasAgentsSkeleton, mergeAgents } from './init.mjs';
+import { renderTree, scriptTrusted, listTree } from './render.mjs';
+import { sha256 } from './render.mjs';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 let pass = 0;
 let fail = 0;
@@ -48,6 +55,81 @@ check('合并：原内容尾部空白折叠不产生连续空行',
   mergeAgents('# A\n内容\n\n\n', '<!-- m -->\n# B') === '# A\n内容\n\n<!-- m -->\n# B\n');
 check('合并：原内容为空时骨架即全文', mergeAgents('', '<!-- m -->\n# B') === '<!-- m -->\n# B\n');
 
+// ---- ⑥ 装户面：真实模板树含编排机制件（init/sync 同走 renderTree，结构保证装户必有） ----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-surface-'));
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, { BOARD_PORT: '8933' }, { force: true });
+  const rels = new Set(t.written.map((w) => w.rel));
+  check('装户面含机制文档与编排脚本示例（_TEMPLATE + 示例 .md）',
+    rels.has('.agents/workflows/_TEMPLATE.md') && rels.has('.agents/workflows/示例-并行实现评审.md'),
+    [...rels].filter((r) => r.includes('workflows')).join('、'));
+  check('装户面含 steps 扩展点示例', rels.has('.agents/workflows/steps/示例-部署验证.md'),
+    [...rels].filter((r) => r.includes('steps')).join('、'));
+  check('装户面无 orchestrate 命令残留（编排机制为目录约定，2026-09-25-wf-runtime）',
+    ![...rels].some((r) => r.includes('orchestrate')),
+    [...rels].filter((r) => r.includes('orchestrate')).join('、'));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+// ---- ⑦ 钩子执行位 + 供应链防线 + 记账归一（2026-09-27 init-p1-batch 复核条件①）----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'init-p1-'));
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const vars = { BOARD_PORT: '8933' };
+  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
+  // P1-1：renderTree 落盘执行位——win32 下 statSync().mode 无 0o111 语义（恒 0666 系），
+  // 断言「writeFileSync 带 mode 参数不炸 + POSIX 语义表达」；真值在 POSIX CI 腿验证
+  const hookStat = fs.statSync(path.join(tmp, '.githooks', 'pre-commit'));
+  const hookHasExecBit = (hookStat.mode & 0o111) !== 0;
+  check('钩子落盘执行位：writeFileSync mode=0755 不炸且 POSIX 语义下可执行位为真（win32 平台分支容忍）',
+    hookHasExecBit || process.platform === 'win32',
+    `mode=${(hookStat.mode & 0o777).toString(8)} platform=${process.platform}`);
+  // P1-3：scriptTrusted——一致放行 / 预置拒绝 / 包源无模板拒绝
+  const ok1 = scriptTrusted({ pkgRoot, target: tmp, rel: '.agents/scripts/gen-workflow-index.mjs', vars });
+  check('scriptTrusted：与包源渲染值一致 → ok', ok1.ok, ok1.note);
+  fs.writeFileSync(path.join(tmp, '.agents/scripts/gen-workflow-index.mjs'), 'require("fs").writeFileSync("MARKER","pwned")\n');
+  const bad1 = scriptTrusted({ pkgRoot, target: tmp, rel: '.agents/scripts/gen-workflow-index.mjs', vars });
+  check('scriptTrusted：预置/被改动 → 拒绝且 note 可见', !bad1.ok && bad1.note.includes('不符'), bad1.note);
+  const bad2 = scriptTrusted({ pkgRoot, target: tmp, rel: '.agents/scripts/not-in-pkg.mjs', vars });
+  check('scriptTrusted：包源无模板 → fail-closed 拒绝', !bad2.ok, bad2.note);
+  // P1-4：owned 记账 LF 归一——CRLF 盘面与 LF 内容同 sha（与 doctor §6.6 比较口径一致）
+  const crlfFile = path.join(tmp, 'crlf-owned.txt');
+  fs.writeFileSync(crlfFile, '行甲\r\n行乙\r\n');
+  const normSha = sha256(Buffer.from('行甲\n行乙\n', 'utf8'));
+  const rawSha = sha256(Buffer.from('行甲\r\n行乙\r\n', 'utf8'));
+  const readNorm = sha256(Buffer.from(fs.readFileSync(crlfFile, 'utf8').replace(/\r\n/g, '\n'), 'utf8'));
+  check('记账口径：LF 归一 sha == LF 内容 sha != 原始字节 sha（CRLF 盘面跨 checkout 稳定）',
+    readNorm === normSha && readNorm !== rawSha);
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+// ---- ⑧ --force owned 保护 + 端口校验（2026-09-27 p2-batch1）----
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'init-protect-'));
+  const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+  const vars = { BOARD_PORT: '8933' };
+  // 预置「用户已自定义」的 owned 文件（内容 != 模板渲染值）
+  const agPath = path.join(tmp, 'AGENTS.md');
+  fs.writeFileSync(agPath, '# 我的项目\n\n自定义适配区命令行，p2b1-marker-keep。\n');
+  const lpPath = path.join(tmp, '.agents', 'hooks', 'local-pre-commit');
+  fs.mkdirSync(path.dirname(lpPath), { recursive: true });
+  fs.writeFileSync(lpPath, '#!/bin/sh\nset -e\nsh .agents/hooks/check-architecture.sh  # add-gate 接线行 p2b1-marker-keep\n');
+  const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true, protectSet: new Set([...listTree(path.join(pkgRoot, 'templates')).filter((rel) => rel === 'AGENTS.md' || rel === '.agents/hooks/local-pre-commit')]) });
+  check('⑧--force owned 保护：自定义 AGENTS.md 不被覆盖（marker 保留 + protectedSkipped 记录）',
+    fs.readFileSync(agPath, 'utf8').includes('p2b1-marker-keep') && (t.protectedSkipped || []).includes('AGENTS.md'),
+    JSON.stringify({ ps: t.protectedSkipped }));
+  check('⑧--force owned 保护：local-pre-commit 接线行保留',
+    fs.readFileSync(lpPath, 'utf8').includes('p2b1-marker-keep') && (t.protectedSkipped || []).includes('.agents/hooks/local-pre-commit'),
+    JSON.stringify({ ps: t.protectedSkipped }));
+  // managed 文件不受保护（--force 照常覆盖）
+  const cmd = path.join(tmp, '.agents', 'commands', 'plan.md');
+  check('⑧managed 文件 --force 照常覆盖（不在 protectedSkipped）',
+    fs.existsSync(cmd) && !(t.protectedSkipped || []).includes('.agents/commands/plan.md'),
+    JSON.stringify({ ps: t.protectedSkipped }));
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 if (fail) {
   console.log('\n用法：node src/init.test.mjs');

package/src/pack.test.mjs

@@ -0,0 +1,24 @@
+// pack.test.mjs — npm 打包防线断言：templates/_agents/cache（运行时生成、gitignore）不得进发布包。
+// 0.4.0 实发包含测试残留 kb-index.json（incident 2026-09-24-npm-pack-cache-leak）——files 白名单列出
+// templates 后 npm-packlist 不再按根 .gitignore 排除目录内文件，须显式负向排除；prepack 兜底物理清除。
+// 此处断言配置层两道防线在位（npm 10/11 双版本 pack 行为已在 incident 实测验证）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+
+const files = pkg.files || [];
+const prepack = pkg.scripts?.prepack || '';
+check('P1 files 负向排除 cache 目录与内容', files.includes('!templates/_agents/cache') && files.includes('!templates/_agents/cache/**'), JSON.stringify(files));
+check('P2 prepack 兜底清除 cache 目录', /templates[\\/]_agents[\\/]cache/.test(prepack) && /rmSync/.test(prepack), prepack || 'scripts.prepack 缺失');
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 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

@@ -1,5 +1,6 @@
-// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs + check-loop bash 套件。
-// 顺序执行、任一非零整体失败（exit 1）；无 sh 环境（极简 Windows）跳过 bash 套件并显著提示。
+// run-tests.mjs — 全套测试入口（npm test）：CLI 单测（sync/add-host/add-gate）+ 引擎 *.test.mjs 套件。
+// 顺序执行、任一非零整体失败（exit 1）。check-loop 套件自 2026-09-26 check-loop-node 起为 node 实现
+// （check-loop.test.mjs 由下方 glob 自动发现——旧 bash 特判与「无 sh 跳过」提示随迁移退役）。
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -10,6 +11,10 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 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()
@@ -23,14 +28,5 @@ for (const rel of nodeSuites) {
   if (r.status !== 0) failed++;
 }
 
-const shSuite = 'templates/_agents/scripts/check-loop.test.sh';
-if (spawnSync('sh', ['-c', 'true']).status === 0) {
-  console.log(`\n===== ${shSuite}（bash 套件） =====`);
-  const r = spawnSync('sh', [path.join(ROOT, shSuite)], { cwd: ROOT, stdio: 'inherit' });
-  if (r.status !== 0) failed++;
-} else {
-  console.warn(`\n⚠️ 环境无 sh——跳过 ${shSuite}（装 Git Bash / 在 WSL 里补跑，勿静默当作通过）`);
-}
-
 console.log(`\n${failed ? `❌ ${failed} 个套件失败` : '✅ 全部套件通过'}`);
 process.exit(failed ? 1 : 0);

package/src/sync-hosts.mjs

@@ -0,0 +1,194 @@
+// flow-kit sync-hosts：跨宿主适配层正文段漂移检查 + 单向同步（B-b 方案，2026-09-25）
+// 目的：改权威源（templates/_agents/{commands,roles}/*.md）正文要同步到 N 份薄适配
+// （modules/hosts/<h>/{agents,commands}/*.md）的对应正文段；薄适配 frontmatter 保留宿主特化字段
+// （trae commands 加 name: wf-X、opencode/zcode/omp 各自原描述），不在同步范围。
+// B-b 语义：sha 比对与 apply 只动正文段，frontmatter 双方各自维护。
+// 算法：diffHosts 抽为 pure function（authorityRoot + adaptersRoot 两个根）；
+//       sync-hosts CLI 在 pkgRoot 跑（包源视角）；doctor §7.x 在 target 跑（装户视角）——同源逻辑。
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOSTS } from './profiles.mjs';
+import { sha256 } from './render.mjs';
+
+function fail(msg) {
+  console.error(`❌ ${msg}`);
+  process.exit(1);
+}
+
+// 剥离 frontmatter 返回 { fm, body }；无 frontmatter 时 fm = ''，body = 整文件
+// frontmatter 形如 "---\n...\n---\n"，位于文件首；其后（含分隔空行）为正文段。
+function splitFm(text) {
+  const m = String(text || '').match(/^---\r?\n([\s\S]*?\r?\n)---\r?\n?([\s\S]*)$/);
+  if (!m) return { fm: '', body: String(text || '') };
+  // fm 还原为带分隔横线的形式；body 保留首部空行
+  return { fm: `---\n${m[1]}---\n`, body: m[2] };
+}
+
+// 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.replace(/\r\n/g, '\n'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// listMd：列目录下 .md 文件（同步当前层；不递归）
+function listMd(dir) {
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+  return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+}
+
+// pairsFor：权威源文件 → 薄适配 rel 列表（与 sync-hosts 早版同映射；trae commands 加 wf- 前缀）
+function pairsFor(authRel) {
+  const out = [];
+  const norm = authRel.split(path.sep).join('/');
+  if (norm.startsWith('commands/') && norm.endsWith('.md')) {
+    const name = norm.slice('commands/'.length, -'.md'.length);
+    out.push({ adapterRel: `opencode/commands/${name}.md` });
+    out.push({ adapterRel: `trae/commands/wf-${name}.md` });
+  } else if (norm.startsWith('roles/') && norm.endsWith('.md')) {
+    const name = norm.slice('roles/'.length, -'.md'.length);
+    for (const h of Object.keys(HOSTS)) out.push({ adapterRel: `${h}/agents/${name}.md` });
+  }
+  return out;
+}
+
+// diffHosts：权威源正文段 vs 薄适配正文段的漂移分析（B-b 语义；pure function）。
+// authorityRoot：权威源根（含 commands/ + roles/）
+// adaptersRoot：薄适配根（含 <h>/{agents,commands}/）
+// 返回：{ drift, inSync, authorityMissing, adapterOrphans, note }
+//   drift       = 正文段 sha 不一致（权威源改 / 薄适配手改 都计入；不区分方向）
+//   inSync      = 正文段 sha 对齐的文件对数
+//   authorityMissing = 权威源声明但薄适配文件不存在（apply 不自动创建——薄适配须经 add-host 接管）
+//   adapterOrphans   = 薄适配存在但权威源无对应文件（apply 不删——可能是宿主特化或历史残留）
+export function diffHosts({ authorityRoot, adaptersRoot }) {
+  if (!fs.existsSync(authorityRoot)) return { drift: [], inSync: 0, authorityMissing: [], adapterOrphans: [], note: `权威源根不存在：${authorityRoot}` };
+
+  const drift = [];
+  let inSync = 0;
+  const adapterSeen = new Set();
+  const authorityMissing = [];
+
+  // 扫权威源 commands/ + roles/
+  for (const sub of ['commands', 'roles']) {
+    const subAbs = path.join(authorityRoot, sub);
+    for (const f of listMd(subAbs)) {
+      const authRel = `${sub}/${f}`;
+      const authAbs = path.join(authorityRoot, authRel);
+      const authSha = bodySha(authAbs);
+      const pairs = pairsFor(authRel);
+      if (pairs.length === 0) continue;
+      for (const { adapterRel } of pairs) {
+        adapterSeen.add(adapterRel);
+        const adapterAbs = path.join(adaptersRoot, adapterRel);
+        const adapterSha = bodySha(adapterAbs);
+        if (adapterSha === null) {
+          authorityMissing.push({ authRel, adapterRel });
+          continue;
+        }
+        if (authSha === adapterSha) { inSync++; continue; }
+        drift.push({ authRel, adapterRel, authSha, adapterSha });
+      }
+    }
+  }
+
+  // 扫薄适配找孤儿（权威源无对应文件）
+  const adapterOrphans = [];
+  for (const h of Object.keys(HOSTS)) {
+    for (const sub of ['agents', 'commands']) {
+      const subAbs = path.join(adaptersRoot, h, sub);
+      for (const f of listMd(subAbs)) {
+        const adapterRel = `${h}/${sub}/${f}`;
+        if (adapterSeen.has(adapterRel)) continue;
+        let authGuess;
+        if (h === 'trae' && sub === 'commands' && f.startsWith('wf-')) {
+          authGuess = `commands/${f.slice('wf-'.length)}`;
+        } else if (sub === 'agents') {
+          authGuess = `roles/${f}`;
+        } else {
+          authGuess = `commands/${f}`;
+        }
+        adapterOrphans.push({ adapterRel, authGuess });
+      }
+    }
+  }
+
+  return { drift, inSync, authorityMissing, adapterOrphans };
+}
+
+// printDiff：人类可读 diff 报告（B-b 语义：正文段比对 + frontmatter 双方不动）
+function printDiff(result) {
+  const { drift, inSync, authorityMissing, adapterOrphans, note } = result;
+  if (note) console.log(`ℹ️  ${note}\n`);
+  console.log(`  正文对齐：${inSync} 对`);
+  if (authorityMissing.length) {
+    console.log(`  权威源声明但薄适配缺失（${authorityMissing.length}，apply 不自动创建——薄适配须经 add-host 接管）：`);
+    for (const { authRel, adapterRel } of authorityMissing) console.log(`    - ${authRel} → ${adapterRel}`);
+  }
+  if (drift.length) {
+    console.log(`  正文段漂移（${drift.length}，权威源与薄适配正文 sha 不一致——可能是权威源改了或薄适配正文手改了；run with --apply to sync 正文段，frontmatter 不动）：`);
+    for (const { authRel, adapterRel } of drift) console.log(`    - ${authRel} → ${adapterRel}`);
+  } else if (!authorityMissing.length) {
+    console.log('  无漂移 ✅');
+  }
+  if (adapterOrphans.length) {
+    console.log(`  ⚠️  孤儿薄适配（${adapterOrphans.length}，权威源无对应文件，可能是历史残留或宿主特化；apply 不删）：`);
+    for (const { adapterRel, authGuess } of adapterOrphans) console.log(`    - ${adapterRel}（推测权威源：${authGuess}）`);
+  }
+}
+
+// applyForward：把权威源正文段同步到薄适配（保留薄适配原 frontmatter）
+// 返回：{ synced: [{adapterRel}] }
+function applyForward({ authorityRoot, adaptersRoot }, drift) {
+  const synced = [];
+  for (const { authRel, adapterRel } of drift) {
+    const authAbs = path.join(authorityRoot, authRel);
+    const adapterAbs = path.join(adaptersRoot, adapterRel);
+    const authText = fs.readFileSync(authAbs, 'utf8');
+    const adapterText = fs.readFileSync(adapterAbs, 'utf8');
+    const { body } = splitFm(authText);
+    const { fm } = splitFm(adapterText);
+    // 拼接：薄适配 frontmatter + 权威源正文段
+    fs.mkdirSync(path.dirname(adapterAbs), { recursive: true });
+    fs.writeFileSync(adapterAbs, `${fm}${body}`);
+    synced.push(adapterRel);
+  }
+  return { synced };
+}
+
+export function syncHosts(args, pkgRoot) {
+  let apply = false;
+  let json = false;
+  for (const a of args) {
+    if (a === '--diff') apply = false;
+    else if (a === '--apply') apply = true;
+    else if (a === '--json') json = true;
+    else fail(`未知选项：${a}（flow-kit sync-hosts --help）`);
+  }
+  if (!pkgRoot) fail('sync-hosts 缺少 pkgRoot（开发模式入口）');
+
+  const authorityRoot = path.join(pkgRoot, 'templates', '_agents');
+  const adaptersRoot = path.join(pkgRoot, 'modules', 'hosts');
+  const result = diffHosts({ authorityRoot, adaptersRoot });
+
+  if (apply && result.drift.length > 0) {
+    const { synced } = applyForward({ authorityRoot, adaptersRoot }, result.drift);
+    console.log(`▶ flow-kit sync-hosts --apply → ${pkgRoot}`);
+    console.log(`  按权威源正文覆盖薄适配正文段 ${synced.length} 份（薄适配 frontmatter 不动）：`);
+    for (const rel of synced) console.log(`    - ${rel}`);
+    const after = diffHosts({ authorityRoot, adaptersRoot });
+    console.log(`  同步后正文对齐：${after.inSync} 对；权威源缺失：${after.authorityMissing.length}；正文漂移：${after.drift.length}`);
+    return after.drift.length === 0 && after.authorityMissing.length === 0 ? 0 : 1;
+  }
+
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+  } else {
+    console.log(`▶ flow-kit sync-hosts --diff → ${pkgRoot}`);
+    printDiff(result);
+  }
+  return 0;
+}