agentic-flow-kit 1.8.7 → 2.0.0

package/src/sync-hosts.test.mjs

@@ -1,291 +0,0 @@
-// 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 不自动创建
-// ⑦--json ⑧孤儿薄适配 ⑨非包源根拒绝（不把 .agents 当权威源）
-// 用法：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';
-import { diffHosts } from './sync-hosts.mjs';
-
-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（两宿主同为 wf- 前缀；trae 另有 name 字段）
-  W(path.join(root, 'modules/hosts/opencode/commands/wf-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/wf-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`);
-  for (const h of ['claude', 'cursor', 'codex']) {
-    for (const cmd of ['build', 'test']) {
-      const title = cmd === 'build' ? 'Build' : 'Test';
-      W(path.join(root, 'modules/hosts', h, 'commands', `wf-${cmd}.md`),
-        `---\ndescription: ${title} · ${h}\n---\n\n# ${title} · v1\n\n权威源正文 ${cmd} v1\n`);
-    }
-    W(path.join(root, 'modules/hosts', h, 'agents/implementer.md'),
-      `---\nname: implementer\ndescription: ${h}\n---\n\n# Implementer · v1\n\n权威源正文 implementer v1\n`);
-  }
-  // 孤儿薄适配：权威源无对应文件（两种形态——带 wf- 前缀与不带前缀）
-  W(path.join(root, 'modules/hosts/opencode/commands/orphan.md'), '# orphan\n');
-  W(path.join(root, 'modules/hosts/opencode/commands/wf-legacy.md'), '# legacy\n');
-  return root;
-}
-
-// ---- 子进程 driver：调真实 sync-hosts ----
-// 2026-10-07 起 sync-hosts 目标根 = --dir > cwd > pkgRoot，故测试必须用 --dir 锁定 fixture，
-// 否则会落到「跑测试时所在的仓库」（实仓 = 包源，会把断言全带偏）。
-function runSyncHosts(fixtureRoot, extra = [], opts = {}) {
-  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, '--dir', fixtureRoot, ...extra], { encoding: 'utf8', ...opts });
-}
-
-// runSyncHostsExit：与 CLI 同口径**传播退出码**（cli.mjs 会 process.exit(syncHosts(...))）。
-//   上面的 runSyncHosts driver 丢弃返回值，故退出码恒 0——不能用来断言 --strict 判红（B4）。
-function runSyncHostsExit(fixtureRoot, extra = []) {
-  const driver = path.join(fixtureRoot, 'driver-exit.mjs');
-  W(driver, `import { syncHosts } from ${JSON.stringify(pathToFileURL(path.join(SRC_ROOT, 'sync-hosts.mjs')).href)};
-const code = syncHosts(process.argv.slice(2), ${JSON.stringify(fixtureRoot)});
-process.exit(typeof code === 'number' ? code : 0);
-`);
-  return spawnSync(process.execPath, [driver, '--dir', fixtureRoot, ...extra], { encoding: 'utf8' });
-}
-
-// 不传 --dir 形态：把 cwd 设为 fixture（验「默认当前目录」解析）
-function runSyncHostsByCwd(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', cwd: fixtureRoot });
-}
-
-// ============ 场景 1：全对齐（正文段与权威源一致，frontmatter 各异）→ drift 空 ============
-{
-  const fx = mkFixture();
-  const r = runSyncHosts(fx, ['--diff']);
-  const out = r.stdout + r.stderr;
-  check('S1 全对齐：正文对齐 17 对（2 commands×5 适配 + 1 role×7 宿主）', /正文对齐：\s*17\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 权威源改了 → 正文漂移 10（build×5 + test×5）', /正文段漂移（10/.test(out), out);
-  check('S2 列出 opencode/commands/wf-build.md（opencode wf- 前缀映射）', out.includes('commands/build.md → opencode/commands/wf-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 正文对齐 = 7（1 role × 7 宿主 implementer 未改）', /正文对齐：\s*7\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：报告同步 5 份（带 commandPrefix 的宿主）', /按权威源正文覆盖薄适配正文段\s*5\s*份/.test(out), out);
-  check('S3 apply：opencode 正文已同步到 v2', R(path.join(fx, 'modules/hosts/opencode/commands/wf-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/wf-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*17\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);
-  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/wf-build.md'));
-  const r = runSyncHosts(fx, ['--diff']);
-  const out = r.stdout + r.stderr;
-  check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/wf-build.md'), out);
-  runSyncHosts(fx, ['--apply']);
-  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-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 { /* 非 JSON 输出时 parsed 保持 null */ }
-  check('S7 --json 输出可解析', parsed && typeof parsed === 'object' && Array.isArray(parsed.drift));
-  check('S7 --json 含 inSync = 17', parsed && parsed.inSync === 17, parsed ? JSON.stringify({ inSync: parsed && parsed.inSync, missing: parsed && parsed.authorityMissing }) : '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);
-  check('S8 opencode 孤儿带 wf- 前缀 → 反推权威源去掉前缀', out.includes('opencode/commands/wf-legacy.md（推测权威源：commands/legacy.md）'), out);
-  check('S8 opencode 孤儿不带前缀 → 原样反推 commands/<file>', out.includes('opencode/commands/orphan.md（推测权威源：commands/orphan.md）'), out);
-  runSyncHosts(fx, ['--apply']);
-  check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')) && fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-legacy.md')));
-}
-
-// ============ 场景 9：非包源根拒绝（.agents 不再当权威源，宿主文件保持原样）============
-{
- const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-synchosts-inst-'));
- W(path.join(root, '.agents/commands/test.md'),
- `---\ndescription: Test 阶段\n---\n\n# Test · v2\n\n权威源正文 test v2\n`);
- const hostBody = `---\ndescription: Test · opencode\n---\n\n# Test · v1\n\n旧正文 test v1\n`;
- W(path.join(root, '.opencode/commands/wf-test.md'), hostBody);
-
- const r1 = runSyncHosts(root, ['--diff']);
- const out1 = r1.stdout + r1.stderr;
- check('S9 非包源根 --diff：拒绝且点明只在包源仓运行', r1.status !== 0 && /只在包源仓运行/.test(out1), out1);
- check('S9 非包源根 --diff：不改宿主文件', R(path.join(root, '.opencode/commands/wf-test.md')) === hostBody, out1);
-
- const r2 = runSyncHostsByCwd(root, ['--apply']);
- const out2 = r2.stdout + r2.stderr;
- check('S9 cwd 为装户根 --apply：同样拒绝', r2.status !== 0 && /只在包源仓运行/.test(out2), out2);
- check('S9 cwd 为装户根 --apply：宿主文件未被改写', R(path.join(root, '.opencode/commands/wf-test.md')) === hostBody, out2);
-}
-
-{
- const pkg = path.resolve(SRC_ROOT, '..');
- const r = diffHosts({
-    authorityRoot: path.join(pkg, 'templates', '_agents'),
-    adaptersRoot: path.join(pkg, 'modules', 'hosts'),
-  });
-  const sample = r.authorityMissing.slice(0, 3).map((x) => x.adapterRel).concat(r.drift.slice(0, 3).map((x) => x.adapterRel)).join('、');
-  check('实仓薄适配无缺失无正文漂移', r.authorityMissing.length === 0 && r.drift.length === 0, `missing=${r.authorityMissing.length} drift=${r.drift.length} ${sample}`);
-}
-
-// ============ 场景 10：包源仓不扫描项目根宿主点（.zcode 等不是第二对账面）============
-{
-  const fx = mkFixture();
-  const zcodeBody = `---\nname: implementer\ndescription: zcode 本仓风格\n---\n\n# Implementer · v0\n\n旧版正文 implementer v0\n`;
-  W(path.join(fx, '.zcode/agents/implementer.md'), zcodeBody);
-  const r = runSyncHosts(fx, ['--diff']);
-  const out = r.stdout + r.stderr;
-  check('S10 对账面只有 modules/hosts', /对账面：modules\/hosts/.test(out) && !/项目根宿主点/.test(out), out.split('\n').slice(0, 6).join('\n'));
-  check('S10 项目根 .zcode 漂移不入报告', !out.includes('.zcode/agents/implementer.md'), out.slice(0, 500));
-  runSyncHosts(fx, ['--apply']);
-  check('S10 --apply 不改写项目根 .zcode', R(path.join(fx, '.zcode/agents/implementer.md')) === zcodeBody);
-}
-
-// ============ 场景 11：--strict 把漂移报告器变成机器门（B4）============
-// 背景：source-sync-check 删除后，跨宿主正文漂移只剩人工跑一次 --diff，CI 里无任何调用点——
-//   而改权威源要同步 N 份薄适配，人工 grep 易漏（本仓评审前就带着 10 份漂移）。
-//   默认 --diff 仍恒 exit 0（人工跑不因漂移失败），--strict 才判红，供 CI 当门。
-{
-  const fx = mkFixture();
-  // 先 --apply 归零：夹具出厂状态未必干净（默认就可能带孤儿/缺失），
-  // 「--strict 在无漂移时 exit 0」这句话得先有个干净盘面才成立。
-  runSyncHosts(fx, ['--apply']);
-  const clean = runSyncHostsExit(fx, ['--diff', '--strict']);
-  check('S11 无漂移 + --strict → exit 0', clean.status === 0, `status=${clean.status} ${(clean.stdout + clean.stderr).slice(0, 300)}`);
-
-  // 制造一处薄适配正文漂移
-  const anyAdapter = fs.readdirSync(path.join(fx, 'modules/hosts'), { withFileTypes: true })
-    .filter((d) => d.isDirectory()).map((d) => d.name);
-  let broke = null;
-  for (const host of anyAdapter) {
-    const cmdDir = path.join(fx, 'modules/hosts', host, 'commands');
-    if (!fs.existsSync(cmdDir)) continue;
-    const f = fs.readdirSync(cmdDir).find((x) => x.endsWith('.md'));
-    if (!f) continue;
-    const abs = path.join(cmdDir, f);
-    fs.appendFileSync(abs, '\n手改一行，权威源没有这段。\n');
-    broke = `${host}/commands/${f}`;
-    break;
-  }
-  check('S11 夹具确实制造了漂移', !!broke, '未找到可改的薄适配');
-
-  const loose = runSyncHostsExit(fx, ['--diff']);
-  check('S11 有漂移但默认 --diff 仍 exit 0（报告器语义不变）', loose.status === 0, `status=${loose.status}`);
-  check('S11 默认 --diff 仍报告漂移', (loose.stdout + loose.stderr).includes('正文段漂移'), loose.stdout.slice(0, 300));
-
-  const strict = runSyncHostsExit(fx, ['--diff', '--strict']);
-  const sout = strict.stdout + strict.stderr;
-  check('S11 有漂移 + --strict → exit 1（CI 机器门）', strict.status === 1, `status=${strict.status}`);
-  check('S11 strict 报错点名修法（sync-hosts --apply）', sout.includes('--apply') && sout.includes('strict'), sout.slice(-300));
-
-  runSyncHosts(fx, ['--apply']);
-  const after = runSyncHostsExit(fx, ['--diff', '--strict']);
-  check('S11 --apply 归零后 --strict 回到 exit 0', after.status === 0, `status=${after.status}`);
-}
-
-console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
-process.exit(failCount ? 1 : 0);

package/src/sync.mjs

@@ -1,228 +0,0 @@
-// flow-kit sync：按 .agents/kit.json 台账升级 managed 文件。
-// 三态：未改动（磁盘 sha==台账）→ 覆盖新版；本地已改 → 跳过并报告（--force 覆盖；台账保持包侧基线，
-//       每次持续报告直至 --force 或本地对齐新版——防跳过一次后下次升级被静默覆盖，2026-09-24 语义修正）；
-//       生成器目标（INDEX.md / wiki 看板）→ 不比对，生成器先于台账记账执行（2026-10-08 修 1：一次 sync
-//       自洽——生成器重写盘面后按终态记账），锚点内重写。
-// 附带：包内新增 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, scriptTrusted } from './render.mjs';
-import { HOSTS, pickStackVars, isOwned, srcTemplatePath, templateDriftOf, TEMPLATE_DRIFT_EXCLUDE } from './profiles.mjs';
-import { doctor } from './doctor.mjs';
-
-function fail(msg) {
-  console.error(`❌ ${msg}`);
-  process.exit(1);
-}
-
-function runNode(target, script, args = []) {
-  const r = spawnSync(process.execPath, [script, ...args], { cwd: target, encoding: 'utf8' });
-  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;
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--dir') target = path.resolve(args[++i] || fail('--dir 缺少值'));
-    else if (args[i] === '--force') force = true;
-    else fail(`未知选项：${args[i]}（flow-kit sync --help 看全部）`);
-  }
-
-  const kitPath = path.join(target, '.agents', 'kit.json');
-  if (!fs.existsSync(kitPath)) fail(`${target} 无 .agents/kit.json——先 flow-kit init（手动安装的旧项目无台账，不支持 sync）`);
-  let kit;
-  try {
-    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
-  } catch (e) {
-    fail(`kit.json 解析失败：${e.message}`);
-  }
-  const opt = kit.options || {};
-  const hosts = Array.isArray(opt.hosts) ? opt.hosts : [];
-  const vars = { BOARD_PORT: String(opt.boardPort || '8933'), ...pickStackVars(opt.stack) };
-
-  const pkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8'));
-  console.log(`▶ flow-kit sync → ${target}（台账版本 ${kit.version} → 包版本 ${pkg.version}）`);
-
-  // 当前包内存渲染到临时目录（只读比对源；不直接写目标——三态判定必须先于落盘）
-  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-sync-'));
-  try {
-    // rel → 渲染产物（新包视角的"应有文件"清单）
-    const fresh = new Map();
-    const t = renderTree(path.join(pkgRoot, 'templates'), tmp, vars, { force: true });
-    for (const f of t.written) fresh.set(f.rel, { sha: f.sha256, abs: path.join(tmp, f.rel) });
-    for (const h of hosts) {
-      if (!HOSTS[h]) continue; // 台账里的宿主已不在包支持列表——只按模板层同步
-      const hr = renderTree(path.join(pkgRoot, 'modules', 'hosts', h), path.join(tmp, HOSTS[h].dir), vars, { force: true });
-      for (const f of hr.written) fresh.set(`${HOSTS[h].dir}/${f.rel}`, { sha: f.sha256, abs: path.join(tmp, HOSTS[h].dir, f.rel) });
-    }
-
-    const ledger = new Map((kit.managed || []).map((f) => [f.rel, f.sha256]));
-    const updated = [], skipped = [], restored = [], added = [], removed = [], newOwned = [], adopted = [];
-    let unchanged = 0;
-    const managedNew = [];
-
-    // 台账内文件：三方比对（台账 sha / 磁盘 sha / 新渲染 sha）
-    for (const [rel, ledgerSha] of ledger) {
-      const disk = path.join(target, rel);
-      const freshFile = fresh.get(rel);
-      if (!freshFile) {
-        removed.push(rel);
-        continue; // 包内已删：文件留在盘上，出台账（下次不再跟踪）
-      }
-      const diskSha = fs.existsSync(disk) ? shaText(disk) : null;
-      if (diskSha === null) {
-        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 });
-          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) { 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 类只对「盘上缺失」的起步文档报告（已装的不动不报）
-    for (const [rel, freshFile] of fresh) {
-      if (ledger.has(rel)) continue;
-      if (isOwned(rel)) {
-        if (!fs.existsSync(path.join(target, rel))) newOwned.push(rel);
-        continue;
-      }
-      const disk = path.join(target, rel);
-      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 });
-      copyManaged(freshFile, disk, rel);
-      added.push(rel);
-      managedNew.push({ rel, sha256: freshFile.sha });
-    }
-
-    const list = (label, arr) => { if (arr.length) console.log(`  ${label}（${arr.length}）：${arr.join('、')}`); };
-    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 && !adopted.length && !removed.length && !skipped.length && !newOwned.length) {
-      console.log(`  已是最新（${unchanged} 份 managed 无变化）`);
-    } else {
-      console.log(`  无变化 ${unchanged} 份`);
-    }
-
-    // 生成器目标走锚点重写（不参与 sha 比对）——执行前过供应链防线（init-p1-batch P1-3）：
-    // 目标侧脚本与包源渲染值 sha 一致才执行（预置/被改动的脚本不可信，跳过并显式提示）。
-    // 先于台账记账执行（2026-10-08 papercuts-cleanup-batch 修 1）：生成器会重写 owned 生成目标
-    // （INDEX/看板），记账段按生成后盘面收口——一次 sync 自洽，不再出现「wiki 变更后需二次 sync 自愈」。
-    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]}`);
-      }
-    }
-    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]}`);
-      }
-    }
-
-    // owned 台账按盘面自愈：owned 归项目所有，哈希只是记账不是约束——手改后无须手工刷 kit.json
-    // （Shipyard 回流策略，2026-09-24：曾在消费仓被迫手工刷新 owned 哈希，根因收敛到此处）。
-    // sha 按 LF 归一记（与 doctor checkOwnedDrift 同口径，2026-09-27 gate-coverage：跨 checkout 字节稳定）。
-    // 位于生成器之后（2026-10-08 papercuts-cleanup-batch 修 1）：生成器重写盘面后按终态记账。
-    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 = ownedSha(p);
-        if (disk === f.sha256) return f;
-        ownedRefreshed++;
-        return { ...f, sha256: disk };
-      });
-    }
-    if (ownedRefreshed) console.log(`  owned 台账哈希按盘面刷新 ${ownedRefreshed} 份（owned 归项目所有，仅记账不约束）`);
-
-    // 模板下发感知（2026-10-06 template-downstream，advisory 恒不 hard-block）：owned 模板无下发通道，
-    // 源仓演进静默陈旧（S18/S20 装户事故根因）——三方 sha 判定见 profiles.templateDriftOf 单源。
-    // 锚「见过即刷新」：本次 sync 见到的包源 sha 记入 srcSha256（含旧账无锚首跑写锚——写锚不出账，
-    // 不追溯）；唯一出账形态 = 源已演进且盘面未跟随。GEN_TARGETS 生成器目标不期望被跟随，排除。
-    const driftList = [];
-    if (Array.isArray(kit.owned)) {
-      kit.owned = kit.owned.map((f) => {
-        if (TEMPLATE_DRIFT_EXCLUDE.has(f.rel)) return f;
-        const src = srcTemplatePath(pkgRoot, f.rel);
-        if (!src) return f; // 无包源模板对应（项目配置类）不参与
-        const srcCur = ownedSha(src);
-        const diskPath = path.join(target, f.rel);
-        const disk = fs.existsSync(diskPath) ? ownedSha(diskPath) : null;
-        if (templateDriftOf({ disk, srcRecord: f.srcSha256, srcCur }) === 'stale-drift') driftList.push(f.rel);
-        return srcCur === f.srcSha256 ? f : { ...f, srcSha256: srcCur };
-      });
-    }
-    if (driftList.length) {
-      console.log(`  ⚠️ 模板感知（advisory）：源仓 ${driftList.length} 份模板自上次同步后有演进且盘面未跟随：${driftList.join('、')}`);
-      console.log('    owned 归项目所有，不自动覆盖；如需跟随：从包源 templates/ 拷贝对应文件；有意定制可忽略（下次 sync 起静默）');
-    }
-
-    // 台账重写（生成器之后）：版本对齐当前包；removed 出册；skipped 保持包侧基线持续报告
-    kit.managed = managedNew.sort((a, b) => a.rel.localeCompare(b.rel));
-    kit.version = pkg.version;
-    fs.writeFileSync(kitPath, `${JSON.stringify(kit, null, 2)}\n`);
-  } finally {
-    fs.rmSync(tmp, { recursive: true, force: true });
-  }
-
-  console.log('▶ flow-kit doctor');
-  doctor(['--dir', target], pkgRoot);
-}