agentic-flow-kit 0.7.0 → 0.8.0

package/modules/hosts/opencode/commands/{sync-hosts.md → wf-sync-hosts.md}

@@ -4,7 +4,7 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 
 # Sync-Hosts · 跨宿主适配层正文段同步
 
-> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（trae commands 加 `name: wf-X`、opencode/zcode/omp 各自原描述）。
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
 > 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
 
 ## 何时跑

package/modules/hosts/trae/commands/wf-sync-hosts.md

@@ -5,7 +5,7 @@ description: 跨宿主适配层同步（正文段 sha 比对 + 用户拍板 +
 
 # Sync-Hosts · 跨宿主适配层正文段同步
 
-> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（trae commands 加 `name: wf-X`、opencode/zcode/omp 各自原描述）。
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
 > 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
 
 ## 何时跑

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-flow-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "AI-Native 闭环工作流 + wiki 知识层脚手架——flow-kit init 一条命令为新项目装好 .agents 工作流引擎（阶段命令/角色契约/门禁钩子/kb 检索/看板/规则面预算）+ workflow 文档闭环 + wiki 知识库，装完自包含、零运行时依赖",
   "type": "module",
   "scripts": {

package/src/doctor.mjs

@@ -9,6 +9,8 @@ import { isOwned, HOSTS, pickStackVars } from './profiles.mjs';
 
 // 宿主目录映射（与 src/profiles.mjs#HOSTS 同源：装副本目录名前缀带点）
 const HOST_DIR = Object.fromEntries(Object.entries(HOSTS).map(([k, v]) => [k, v.dir]));
+// 命令层薄适配宿主：[装副本目录名, 文件名前缀]（单源 profiles.mjs#HOSTS.commandPrefix；与 sync-hosts pairsFor 同口径）
+const HOST_CMD_DIR = Object.entries(HOSTS).filter(([, v]) => v.commandPrefix).map(([k, v]) => [v.dir, v.commandPrefix]);
 
 function sh(cmd, cwd) {
   try {
@@ -209,7 +211,8 @@ export function doctor(args, pkgRoot) {
   // 6.7 跨宿主薄适配正文段漂移校验（2026-09-25 cross-host-sync，参见 workflows/intents/2026-09-25-cross-host-sync.md）
   //     装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（.zcode/.omp/.opencode/.trae）下的
   //     {agents,commands}/*.md 是薄适配。按正文段 sha 比对（B-b 语义，frontmatter 不计入漂移），
-  //     trae commands 加 wf- 前缀映射。首次引入为 WARN（沿用 wf-runtime 复盘「先 WARN 升级 FAIL」路径），
+  //     commands 层按 profiles.mjs#HOSTS.commandPrefix 前缀映射（2026-09-28 起 opencode/trae 同 wf-）。
+  //     首次引入为 WARN（沿用 wf-runtime 复盘「先 WARN 升级 FAIL」路径），
   //     待装户升级视反馈升级 FAIL。包源侧对应工具是 flow-kit sync-hosts（src/sync-hosts.mjs）。
   const adapterRes = checkAdapterDrift(target);
   if (adapterRes.skipped) {
@@ -341,7 +344,8 @@ export function checkOwnedDrift(target) {
 // 跨宿主薄适配正文段漂移校验（独立 export 供 doctor 主流程 + 单元测试共用；2026-09-25 cross-host-sync）
 // 装户侧视角：.agents/{commands,roles}/*.md 是权威源；4 宿主目录（zcode→.zcode、omp→.omp、
 // opencode→.opencode、trae→.trae）下 {agents,commands}/*.md 是薄适配。按正文段 sha 比对
-// （B-b 语义；frontmatter 不计入漂移）；trae commands 加 wf- 前缀映射。
+// （B-b 语义；frontmatter 不计入漂移）；commands 层映射走 HOSTS.commandPrefix 前缀（2026-09-28 起
+// opencode 与 trae 同为 wf- 前缀，单源见 profiles.mjs；roles 层映射全宿主无前缀）。
 // 返回：{ drift, total, skipped, note? }
 //   - skipped=true：权威源目录不存在 / 包源环境 / 无 .md 文件
 //   - drift：权威源正文段与薄适配正文段 sha 不一致的对数
@@ -373,10 +377,11 @@ export function checkAdapterDrift(target) {
       const authRel = `${sub}/${f}`;
       const authSha = bodySha(path.join(authorityRoot, authRel));
       const name = f.slice(0, -'.md'.length);
-      // 构建映射：commands/* → opencode/commands/<name>.md + trae/commands/wf-<name>.md；roles/* → 4 宿主 agents/<name>.md
+      // 构建映射：commands/* → 每个带 commandPrefix 的宿主 commands/<prefix><name>.md（单源 profiles.mjs#HOSTS）；
+      //             roles/*    → 4 宿主 agents/<name>.md（无前缀）
       const targets = [];
       if (sub === 'commands') {
-        targets.push([HOST_DIR.opencode, 'commands', `${name}.md`], [HOST_DIR.trae, 'commands', `wf-${name}.md`]);
+        for (const [dir, prefix] of HOST_CMD_DIR) targets.push([dir, 'commands', `${prefix}${name}.md`]);
       } else {
         for (const h of Object.keys(HOST_DIR)) targets.push([HOST_DIR[h], 'agents', `${name}.md`]);
       }

package/src/sync-hosts.mjs

@@ -1,8 +1,9 @@
 // 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 各自原描述），不在同步范围。
+// （commands 层 trae 侧另有 name: wf-X，opencode/zcode/omp 各自原描述），不在同步范围。
 // B-b 语义：sha 比对与 apply 只动正文段，frontmatter 双方各自维护。
+// 映射单源在 profiles.mjs#HOSTS.commandPrefix（命令层薄适配文件名前缀；2026-09-28 opencode 对齐 trae 的 wf- 前缀）。
 // 算法：diffHosts 抽为 pure function（authorityRoot + adaptersRoot 两个根）；
 //       sync-hosts CLI 在 pkgRoot 跑（包源视角）；doctor §7.x 在 target 跑（装户视角）——同源逻辑。
 import fs from 'node:fs';
@@ -41,14 +42,17 @@ function listMd(dir) {
   return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
 }
 
-// pairsFor：权威源文件 → 薄适配 rel 列表（与 sync-hosts 早版同映射；trae commands 加 wf- 前缀）
+// pairsFor：权威源文件 → 薄适配 rel 列表（映射单源见 profiles.mjs#HOSTS.commandPrefix）
+//   commands 权威源 → 带 commandPrefix 的宿主各一份（<dir>/commands/<prefix><name>.md）
+//   roles    权威源 → 全部宿主 agents 各一份
 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` });
+    for (const [h, v] of Object.entries(HOSTS)) {
+      if (v.commandPrefix) out.push({ adapterRel: `${h}/commands/${v.commandPrefix}${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` });
@@ -104,8 +108,10 @@ export function diffHosts({ authorityRoot, adaptersRoot }) {
         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)}`;
+        const prefix = HOSTS[h] && HOSTS[h].commandPrefix;
+        if (sub === 'commands' && prefix && f.startsWith(prefix)) {
+          // 命令层薄适配带宿主 commandPrefix（2026-09-28：opencode 对齐 trae 后两宿主同口径）
+          authGuess = `commands/${f.slice(prefix.length)}`;
         } else if (sub === 'agents') {
           authGuess = `roles/${f}`;
         } else {

package/src/sync-hosts.test.mjs

@@ -31,12 +31,12 @@ function mkFixture() {
     `---\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'),
+  // 薄适配：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/test.md'),
+  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`);
@@ -49,8 +49,9 @@ function mkFixture() {
     `---\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`);
-  // 孤儿薄适配：权威源无对应文件
+  // 孤儿薄适配：权威源无对应文件（两种形态——带 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;
 }
 
@@ -84,7 +85,7 @@ syncHosts(process.argv.slice(2), root);
   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 列出 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 正文对齐 = 4（1 role × 4 宿主 implementer 未改）', /正文对齐：\s*4\s*对/.test(out), out);
   check('S2 exit 0（diff 模式不阻断）', r.status === 0);
@@ -98,9 +99,9 @@ syncHosts(process.argv.slice(2), root);
   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：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/build.md')).match(/^name:/m));
+  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 内部做
@@ -136,12 +137,12 @@ syncHosts(process.argv.slice(2), root);
 // ============ 场景 6：薄适配文件不存在 → authorityMissing 列出，apply 不创建 ============
 {
   const fx = mkFixture();
-  fs.rmSync(path.join(fx, 'modules/hosts/opencode/commands/build.md'));
+  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/build.md'), out);
+  check('S6 薄适配缺失 → authorityMissing 列', /权威源声明但薄适配缺失（/.test(out) && out.includes('opencode/commands/wf-build.md'), out);
   const r2 = runSyncHosts(fx, ['--apply']);
-  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/build.md')));
+  check('S6 apply 不自动创建薄适配（仍缺失）', !fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/wf-build.md')));
 }
 
 // ============ 场景 7：--json 机器可读输出 ============
@@ -162,8 +163,10 @@ syncHosts(process.argv.slice(2), root);
   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);
   const r2 = runSyncHosts(fx, ['--apply']);
-  check('S8 apply 不删孤儿薄适配', fs.existsSync(path.join(fx, 'modules/hosts/opencode/commands/orphan.md')));
+  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')));
 }
 
 console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);

package/templates/AGENTS.md

@@ -23,7 +23,7 @@
 
 ### 门禁与提交
 
-- `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / wiki 台账 / 规则面预算 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
+- `.githooks/`（经 `core.hooksPath` 挂载，本地 clone 后执行 `git config core.hooksPath .githooks`）：pre-commit（闭环配对 / wiki 台账 / 规则面预算 / 双源一致性 / managed 台账快检 / 敏感信息扫描与条件构建）、pre-push（闭环断档扫描）、commit-msg、post-commit、pre-merge-commit。
 - **`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(*)` 单独提交留痕。

package/templates/_agents/commands/sync-hosts.md

@@ -17,7 +17,7 @@ next: .agents/commands/build.md（漂移属 build 改权威源未同步导致的
 
 # Sync-Hosts · 跨宿主适配层正文段同步
 
-> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（trae commands 加 `name: wf-X`、opencode/zcode/omp 各自原描述）。
+> 改权威源（`templates/_agents/{commands,roles}/*.md`）后薄适配（`modules/hosts/<h>/{agents,commands}/*.md`）要同步——薄适配正文 = 权威源正文，frontmatter 各自保留宿主特化（commands 层文件名 = 宿主命令名，opencode / trae 同用 `wf-` 前缀，单源见 `src/profiles.mjs#HOSTS.commandPrefix`；trae 另有 `name: wf-X`，zcode/omp 各自原描述）。
 > 装户视角：`flow-kit doctor` §7.x 跑同名检查（仅装户，包源环境跳过——包源下永远是 drift）。
 
 ## 何时跑

package/templates/_agents/scripts/check-ledger.mjs

@@ -0,0 +1,65 @@
+// check-ledger.mjs — managed 台账快检（2026-09-28 ledger-precommit-gate）：kit.json 台账 sha ↔ 盘面工作树
+// 补 pre-commit 盲区：双源门禁（source-sync-check）查 templates↔.agents 正文，两侧成对回退时静默；
+// doctor §4 查台账↔盘面但只在手动全量跑——「台账 sha 预 landing」（台账记了盘面尚不存在的内容 sha）
+// 随常规提交静默落 main，三次真实发生（0272a1c 预入 / ff3c721 还原窗口 / 537df18 闭合），本脚本在
+// 提交时刻补齐第三边。sha 口径：LF 归一 utf8（同 doctor §4 / render.mjs shaText / source-sync-check
+// 读取侧，跨 checkout 稳定；装户自包含约束决定独立实现，三处口径改动须同批）。
+// 边界：仅包源环境由 .githooks/pre-commit 触发（装户 managed 手改走 doctor §4 WARN 口径，不硬拦）；
+//       managed 删除即拦——sync 对 removed 只报不删，删件须手动同步装副本并重跑 sync 刷台账。
+// 用法：node .agents/scripts/check-ledger.mjs（cwd = 仓库根；非零出口即阻断提交）
+//       单元测试：import { ledgerDrift } from './check-ledger.mjs'
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+export function ledgerDrift(target = process.cwd()) {
+  const kitPath = path.join(target, '.agents', 'kit.json');
+  if (!fs.existsSync(kitPath)) return { skipped: true, note: '无 .agents/kit.json（非 flow-kit 安装）' };
+  let kit;
+  try {
+    kit = JSON.parse(fs.readFileSync(kitPath, 'utf8'));
+  } catch (e) {
+    return { skipped: false, fatal: `kit.json 解析失败：${e.message}`, modified: [], gone: [], total: 0, version: '?' };
+  }
+  if (!Array.isArray(kit.managed)) {
+    // fail-loud（独立复核 P2-3，2026-09-28）：JSON 合法但 managed 缺失/非数组时静默「全对齐」= 假放，
+    // 同 doctor §4 的 Array.isArray 显式判口径，台账结构坏了必须响
+    return { skipped: false, fatal: 'kit.json managed 缺失或非数组', modified: [], gone: [], total: 0, version: kit.version };
+  }
+  const modified = [];
+  const gone = [];
+  const managed = kit.managed;
+  for (const f of managed) {
+    const p = path.join(target, f.rel);
+    if (!fs.existsSync(p)) { gone.push(f.rel); continue; }
+    const h = createHash('sha256').update(fs.readFileSync(p, 'utf8').replace(/\r\n/g, '\n'), 'utf8').digest('hex'); // LF 归一，同 doctor §4
+    if (h !== f.sha256) modified.push(f.rel);
+  }
+  return { skipped: false, fatal: '', modified, gone, total: managed.length, version: kit.version };
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('check-ledger.mjs');
+if (isMain) {
+  const r = ledgerDrift();
+  console.log('▶ flow-kit check-ledger');
+  if (r.skipped) {
+    console.log('  ' + r.note + '，跳过 ✅');
+    process.exit(0);
+  }
+  console.log('  kit.json v' + r.version + '：managed ' + r.total + ' 份，台账 ↔ 盘面（工作树，LF 归一）');
+  if (r.fatal) console.error('❌ ' + r.fatal);
+  if (r.modified.length) {
+    console.error('  台账漂移（盘面 ≠ 台账 sha）' + r.modified.length + '：');
+    for (const rel of r.modified) console.error('    - ' + rel);
+  }
+  if (r.gone.length) {
+    console.error('  managed 缺失 ' + r.gone.length + '：');
+    for (const rel of r.gone) console.error('    - ' + rel);
+  }
+  if (r.fatal || r.modified.length || r.gone.length) {
+    console.error('  提交被拦：kit.json 与盘面不一致（预 landing / 手改未随动）——跑 node bin/flow-kit.mjs sync 成对后原路重试');
+    process.exit(1);
+  }
+  console.log('  全对齐 ✅');
+  process.exit(0);
+}

package/templates/_agents/scripts/check-ledger.test.mjs

@@ -0,0 +1,127 @@
+// check-ledger.test.mjs — managed 台账快检测试（2026-09-28 ledger-precommit-gate）
+// 方法：fixture 临时目录 .agents/kit.json + managed 件，调 ledgerDrift() + spawnSync CLI 出口码；
+//       真实仓库 baseline（包源环境全对齐；装户环境 SKIP 不计失败，沿 source-sync-check 先例）
+// 判据：S1 全对齐  S2 内容漂移逐份列出  S3 缺失  S4 CRLF×LF 归一不误报  S5 无 kit.json skip
+//       S6 kit.json 解析失败 fatal  S7/S8 CLI 出口码 0/1  S9 真实仓 baseline
+// 用法：node templates/_agents/scripts/check-ledger.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 } from 'node:url';
+import { createHash } from 'node:crypto';
+import { ledgerDrift } from './check-ledger.mjs';
+
+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 : '')); }
+}
+
+// LF 归一 sha（同 check-ledger.mjs / doctor §4 口径）
+const lfSha = (s) => createHash('sha256').update(s.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+
+function mkFixture(managed, entries, kitRaw) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-cl-'));
+  for (const [rel, content] of Object.entries(managed)) {
+    fs.mkdirSync(path.join(root, path.dirname(rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), content);
+  }
+  fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.agents', 'kit.json'),
+    kitRaw !== undefined ? kitRaw : JSON.stringify({ kit: 't', version: '0.0.0-test', managed: entries }));
+  return root;
+}
+
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'check-ledger.mjs');
+const runCli = (cwd) => spawnSync(process.execPath, [SCRIPT], { encoding: 'utf8', cwd });
+
+// ---- S1 全对齐 → 无漂移无缺失 ----
+{
+  const root = mkFixture({ '.agents/scripts/a.mjs': 'A v1\n' }, [{ rel: '.agents/scripts/a.mjs', sha256: lfSha('A v1\n') }]);
+  const r = ledgerDrift(root);
+  check('S1 全对齐 → modified=0 gone=0 total=1', !r.skipped && r.modified.length === 0 && r.gone.length === 0 && r.total === 1, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S2 内容漂移 → 逐份列出 rel ----
+{
+  const root = mkFixture({ '.agents/scripts/a.mjs': 'A 改了\n' }, [{ rel: '.agents/scripts/a.mjs', sha256: lfSha('A v1\n') }]);
+  const r = ledgerDrift(root);
+  check('S2 内容漂移 → modified=[a.mjs]', !r.skipped && r.modified.length === 1 && r.modified[0] === '.agents/scripts/a.mjs' && r.gone.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S3 managed 缺失 → gone ----
+{
+  const root = mkFixture({}, [{ rel: '.agents/scripts/gone.mjs', sha256: lfSha('x') }]);
+  const r = ledgerDrift(root);
+  check('S3 缺失 → gone=[gone.mjs]', !r.skipped && r.gone.length === 1 && r.gone[0] === '.agents/scripts/gone.mjs' && r.modified.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S4 CRLF 盘面 × LF 台账 → 归一不误报 ----
+{
+  const root = mkFixture({ '.agents/scripts/crlf.mjs': 'B v1\r\nline2\r\n' }, [{ rel: '.agents/scripts/crlf.mjs', sha256: lfSha('B v1\nline2\n') }]);
+  const r = ledgerDrift(root);
+  check('S4 CRLF 盘面 × LF 台账 → modified=0（归一口径）', !r.skipped && r.modified.length === 0 && r.gone.length === 0, JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S5 无 kit.json → skipped（非 flow-kit 安装兼容） ----
+{
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'fk-cl-'));
+  const r = ledgerDrift(root);
+  check('S5 无 kit.json → skipped=true', r.skipped === true && typeof r.note === 'string', JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S6 kit.json 解析失败 → fatal ----
+{
+  const root = mkFixture({}, [], '{ kit: 坏 json');
+  const r = ledgerDrift(root);
+  check('S6 解析失败 → fatal 非空', !r.skipped && typeof r.fatal === 'string' && r.fatal.includes('解析失败'), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S6b JSON 合法但 managed 缺失/非数组 → fatal（不静默全对齐；独立复核 P2-3） ----
+{
+  const root = mkFixture({}, [], JSON.stringify({ kit: 't', version: '0.0.0-test' }));
+  const r = ledgerDrift(root);
+  check('S6b managed 非数组 → fatal 非空（fail-loud）', !r.skipped && typeof r.fatal === 'string' && r.fatal.includes('managed'), JSON.stringify(r));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S7 CLI 干净 fixture → exit 0 + 全对齐 ----
+{
+  const root = mkFixture({ '.agents/scripts/a.mjs': 'A v1\n' }, [{ rel: '.agents/scripts/a.mjs', sha256: lfSha('A v1\n') }]);
+  const p = runCli(root);
+  check('S7 CLI 全对齐 → exit 0 + 「全对齐」', p.status === 0 && p.stdout.includes('全对齐'), `status=${p.status} out=${p.stdout}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S8 CLI 漂移 fixture → exit 1 + 列出 rel + sync 提示 ----
+{
+  const root = mkFixture({ '.agents/scripts/a.mjs': 'A 改了\n' }, [{ rel: '.agents/scripts/a.mjs', sha256: lfSha('A v1\n') }]);
+  const p = runCli(root);
+  check('S8 CLI 漂移 → exit 1 + rel + sync 提示', p.status === 1 && p.stderr.includes('.agents/scripts/a.mjs') && p.stderr.includes('sync'), `status=${p.status} err=${p.stderr}`);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
+// ---- S9 真实仓 baseline：包源环境台账↔盘面全对齐；装户环境 SKIP 不计失败 ----
+{
+  let srcRoot = path.dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5 && srcRoot; i++) {
+    if (fs.existsSync(path.join(srcRoot, 'templates', '_agents'))) break;
+    srcRoot = path.dirname(srcRoot);
+  }
+  if (!srcRoot || !fs.existsSync(path.join(srcRoot, 'templates', '_agents'))) {
+    console.log('SKIP S9（装户环境无包源，不计失败）');
+  } else {
+    const r = ledgerDrift(srcRoot);
+    check('S9 真实仓 baseline → 台账↔盘面全对齐', !r.skipped && r.modified.length === 0 && r.gone.length === 0, JSON.stringify({ modified: r.modified, gone: r.gone }));
+  }
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${failCount}`);
+process.exit(failCount ? 1 : 0);

package/templates/_agents/scripts/doctor.test.mjs

@@ -214,7 +214,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
       'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
     },
     adapters: {
-      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+      '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
       '.trae/commands/wf-build.md': `---\nname: wf-build\ndesc: trae\n---\n\n${CMD_BODY}`,
       '.zcode/agents/implementer.md': `---\nname: impl\ndesc: zcode\n---\n\n${ROLE_BODY}`,
       '.opencode/agents/implementer.md': `---\nname: impl\ndesc: oc\n---\n\n${ROLE_BODY}`,
@@ -249,7 +249,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
   const root = mkfixAdapter({
     pkgMarker: true,
     authority: { 'commands/build.md': `---\ndesc: x\n---\n\n${CMD_BODY}` },
-    adapters: { '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n漂移` },
+    adapters: { '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n漂移` },
   });
   const r = checkAdapterDrift(root);
   check('场景 11：包源环境（templates/ + modules/ 同时存在）→ skipped=true',
@@ -291,7 +291,7 @@ const CMD_BODY = '# Build\n\n正文 build v1\n';
       'roles/implementer.md': `---\ndesc: r\n---\n\n${ROLE_BODY}`,
     },
     adapters: {
-      '.opencode/commands/build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
+      '.opencode/commands/wf-build.md': `---\ndesc: oc\n---\n\n${CMD_BODY}`,
     },
   });
   const r = checkAdapterDrift(root);

package/templates/_githooks/pre-commit

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Git 原生 pre-commit hook（经 core.hooksPath 挂载，git 执行、不依赖 agent 客户端）— agentic-flow-kit 通用编排
-# 通用门禁序：闭环配对(增量) → wiki 台账(增量) → 常驻面体积预算(增量) → 双源一致性(增量) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
+# 通用门禁序：闭环配对(增量) → wiki 台账(增量) → 常驻面体积预算(增量) → 双源一致性(增量) → managed 台账快检(包源恒跑) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
 # 项目专属门禁（架构红线/业务守卫等）放 .agents/hooks/local-pre-commit——存在即在本钩子内执行，返回非零即阻断提交
 # 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
 # 不是 pre-commit）——门禁清单只此一份，避免两处分叉
@@ -46,6 +46,22 @@ if [ -d templates/_agents ] && [ -f .agents/scripts/source-sync-check.mjs ] \
   fi
 fi
 
+# managed 台账快检（包源环境恒跑，2026-09-28 ledger-precommit-gate；同日独立复核 P2-2 采纳）：
+# kit.json 台账 sha ↔ 盘面工作树（LF 归一，同 doctor §4 口径）——拦「台账 sha 预 landing」：台账记了
+# 盘面尚不存在的内容 sha。双源门禁对此静默（templates↔.agents 成对回退时两侧一致），doctor §4 只在
+# 手动全量跑——该故障模式三次真实发生（0272a1c 预入 / ff3c721 还原窗口 / 537df18 闭合），本块补齐
+# 提交时刻的第三边。恒跑不作暂存触发：预 landing 是仓态而非暂存态，暂存 grep 有前缀缝（如 .githooks/*
+# managed 件单边漂移不命中），毫秒级 80 份 hash 不构成开销理由。比较工作树而非暂存区（沿双源门禁
+# 口径）。装户环境（无 templates/_agents/ 包源）自然跳过——装户 managed 手改走 doctor §4 WARN 口径，
+# 不硬拦。已知边界：managed 删除即拦（sync 对 removed 只报不删，删件须手动同步装副本并重跑 sync 刷
+# 台账）。
+if [ -d templates/_agents ] && [ -f .agents/scripts/check-ledger.mjs ]; then
+  if ! node .agents/scripts/check-ledger.mjs; then
+    echo "pre-commit: managed 台账快检未通过，提交已阻止——kit.json 与盘面不一致，跑 node bin/flow-kit.mjs sync 成对后原路重试" >&2
+    exit 1
+  fi
+fi
+
 # 项目门禁挂载点：.agents/hooks/local-pre-commit（项目自建门禁/门禁模块接线处，存在即执行）
 if [ -f .agents/hooks/local-pre-commit ]; then
   run_gate "项目门禁（local-pre-commit）" .agents/hooks/local-pre-commit