agentic-flow-kit 0.6.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.6.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/profiles.mjs

@@ -6,10 +6,14 @@
 // 配置的项目自动跳过，不 fail-closed 误拦。none = 不配置（项目日后自填）。
 export const HOSTS = {
   zcode: { dir: '.zcode', localOnly: true },
-  opencode: { dir: '.opencode', localOnly: false },
-  trae: { dir: '.trae', localOnly: false },
+  opencode: { dir: '.opencode', localOnly: false, commandPrefix: 'wf-' },
+  trae: { dir: '.trae', localOnly: false, commandPrefix: 'wf-' },
   omp: { dir: '.omp', localOnly: true },
 };
+// commandPrefix = 该宿主的命令层薄适配文件名（= 宿主命令名）统一前缀，2026-09-28 opencode-cmd-wf-prefix
+// 与 trae 对齐后单源：命令名不再裸占宿主顶层命名空间（撞宿主内置/第三方命令无从规避）；缺该字段的宿主
+// 表示只有角色层适配、不参与 commands 权威源映射（zcode/omp）。sync-hosts（包源侧）与 doctor §7.x
+// （装户侧）两份实现均从本表派生，新增命令层宿主只改这一处。
 
 const ESLINT_CONFIGS = [
   'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs',
@@ -78,10 +82,23 @@ export function pickStackVars(stackKey) {
 
 // 两态文件模型的归属判定：managed（随包升级）之外皆 owned（项目内容，sync 永不覆盖）
 // local-pre-commit 是项目门禁挂载点——一旦接线即含项目内容，按 owned 起步（旧台账里若在 managed，改动后 sync 也会保守跳过）
+// metric-claims.txt 是**项目自持的指标登记表**（2026-09-28 metric-claim-gate 复核 P2 更正）：装户按
+// 设计要在其中新增自有指标，若按 managed 记账则 sync 每次都报「本地已改、升级时需合并」，且将来包侧
+// 新增内置指标**永远下不来**（台账停在包侧基线）。故归 owned——随包附带一份起步内容，此后归项目。
+// metric-derivers.cjs 是**项目自持的取数器模块**（2026-09-28 adopter-derivers）：它正是上面那份登记表的
+// 扩展点——装户在此实现自有指标的取数逻辑。**必须与 metric-claims.txt 同归 owned**：若落 managed，
+// 装户一用该功能就会让 sync 永久报「本地已改」、doctor WARN，并因供应链防线使 check-loop 跳过执行
+// （门禁静默停摆）——那正是本单要修的缺陷本身（同名 incident 有实测链路）。
+// **后缀为 .cjs 而非 .mjs**（2026-09-28 跨版本实测修正）：首版用 .mjs + require(esm)，实测在
+// Node 18.20 / 20.18 / 22.11 全部 ERR_REQUIRE_ESM（只有 ≥20.19/≥22.12 可用），而本仓 engines
+// 写 >=18.0.0、CI 跑 18/22 → 装户在 CI 目标版本上根本用不了。改 .cjs 后 createRequire 同步载入
+// 全线可用。旧 .mjs 路径同样登记为 owned（免装户残留旧文件时落 managed 重演缺陷）。
 export function isOwned(rel) {
   return rel === 'AGENTS.md' || rel === '.gitattributes' || rel.startsWith('workflow/') || rel.startsWith('wiki/')
     || rel.startsWith('.agents/notes/')
     || rel === '.agents/workflow-modules.txt' || rel === '.agents/rule-budgets.txt'
+    || rel === '.agents/metric-claims.txt' || rel === '.agents/metric-derivers.cjs'
+    || rel === '.agents/metric-derivers.mjs'
     || rel === '.agents/hooks/local-pre-commit';
 }
 

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/metric-claims.txt

@@ -0,0 +1,81 @@
+# 量化断言「指标签名」单源登记表（check-loop 检查 16 共读）
+#
+# 背景（2026-09-28 claim-exceeds-fix）：结论文档里跨文档引用的量化值若各自手写，
+# 极易在事实变更后不同步——本仓已实证：同一指标在一处改了、另一处没改，
+# 而「五处文件同步」这句话本身无人核对（该单真正被门禁抓住的方式，是事后人工复核）。
+# 本表把「哪个指标、当前取值多少」收敛为单源，供 check-loop 检查 16 对账。
+#
+# 用法：活跃态文档（draft/approved/open）引用某个已登记指标时，按**签名形态**书写，
+# 检查 16 会实时取数比对。签名形态：\{\{指标名\}\}（双花括号包裹指标名，小写点分）。
+#   例（下面是「讲语法」，故加反斜杠转义；**写真断言时不加反斜杠**）：
+#     本仓台账共 \{\{ledger.lines\}\} 行，其中无 batch 字段 \{\{ledger.linesWithoutBatch\}\} 行。
+# 写作时**不要手写数字**——写完跑 check-loop，工具会把实时值填进提示里供你替换。
+# 转义按「逐个出现」生效：同一行里 \{\{x\}\} 是示意、\{\{y\}\} 是真断言时，只豁免前者。
+# （本例的指标名曾写成 ledger.total / ledger.noBatch 两个**并不存在**的名字——本表不被
+#   检查 16 扫描（它是 .txt 非 .md），故这类笔误不会被自动抓到，只能靠复核。已据实更正。）
+#
+# 为什么用显式签名而非全文数字扫描（据实说明，非偷懒）：
+#   本仓活跃文档中「N 行 / N 条 / N 份」类表述有 49 处（实测：活跃态 21 份文档逐行计），绝大多数是**历史叙述**
+#   （描述某次提交当时的规模，天然不会随当前事实变化）。全文扫描会对这些正确的
+#   历史叙述产生大量假阳性——而 check-loop.mjs 已把「无判定依据的行不产出不可
+#   消除噪声」立为红线（沿 2026-09-27 audit-gate-hardening P3 教训：噪声淹没真漏点）。
+#   故本检查**只校验显式声明的签名**：假阳性恒为 0，代价是覆盖面依赖作者登记。
+#
+# 格式：每行 `<指标名> = <取数表达式>`；`#` 开头为注释；空行忽略。
+# 取数表达式（闭集，全部本地确定性、零网络）：
+#   ledger.lines          台账 .agents/confirmations.jsonl 的非空行数
+#   ledger.linesWithoutBatch   台账中不含 "batch" 字段的行数（schema 演进前历史行）
+#   ledger.linesWithBatch      台账中含 "batch" 字段的行数
+#   docs.count.<sub>      workflow/<sub> 下文档份数——**与文档扫描同口径**：以数字开头的
+#                         .md、排除 _TEMPLATE.md、且仓库模式下只计 HEAD 已跟踪件
+#                         （故并行会话的未跟踪新档不计入）；sub ∈ intents/specs/plans/incidents
+#   docs.count.all        上述四类合计
+# ── 新增指标（2026-09-28 adopter-derivers 起）────────────────────────────────
+# 分两层取数，**内置优先**：
+#   ① 引擎内置 8 个指标（下表）——装户零配置即用，不需要做任何事。
+#   ② 项目自有指标——写 `.agents/metric-derivers.cjs`（**owned**，sync 永不覆盖），
+#      用 CommonJS 导出 `derivers` 对象（指标名 → 取数函数），并在此表加同名一行。
+#      **后缀必须是 `.cjs`、写法必须是 CommonJS**（`module.exports`）。
+#      为什么不用 `.mjs`：引擎用 `require()` 同步载入，而 `require(esm)` 仅在
+#      Node ≥20.19 / ≥22.12 可用——**实测 Node 18.20 / 20.18 / 22.11 全部
+#      ERR_REQUIRE_ESM**，而本仓 engines 声明 `>=18.0.0`。故 `.cjs` 是唯一
+#      全版本可用的形态（同步、零版本依赖）。
+#      旧的 `.mjs` 路径已弃用：若残留在盘上，检查 16 会**明确提示迁移**。
+#
+# 示例 `.agents/metric-derivers.cjs`：
+#     module.exports = {
+#       derivers: {
+#         'my.migrations': (ctx) => ctx.glob('backend/migrations/*.sql').length,
+#         'my.apiCount':   (ctx) => ctx.countFiles('src/api', (f) => f.endsWith('.controller.ts')),
+#       },
+#     };
+# ctx 提供（同步，免你重复造轮子；其余请自行 `require('node:fs')`）：
+#     ctx.root                    仓库根绝对路径
+#     ctx.read(rel)               读文本文件（LF 归一），不存在返回 ''
+#     ctx.glob(pattern)           极简 glob（* / **），返回相对路径数组
+#     ctx.countFiles(dir, pred)   递归计数（可传谓词）
+#
+# 三条硬约定（违反即 fail-loud）：
+#   1. **必须是同步函数**（返回 number，不得 async/Promise）——本检查零网络、要求本地确定性
+#   2. 必须**确定性**：不得依赖网络、不得依赖当前时间
+#   3. 返回值须为**有限数字**（Number.isFinite）
+#
+# 失败语义（**绝不静默降级**）：模块语法错 / 抛异常 / 未导出 derivers / 返回值非法
+#   → 一律出 `[WARN 装户取数器载入失败]` 或 `[WARN 指标取数失败]`，**不会**退化成
+#   「只用内置指标」——否则你会误以为「忘了登记」而查不到真因。
+# 指标名与内置同名时：**内置优先**，你的定义被忽略（会出 advisory 明示）。
+#
+# 注：本检查**不设取数超时**——请让取数器保持轻量（秒级）。死循环会拖慢门禁。
+# 另：装户模块的「取数器」在引擎侧（check-loop.mjs，managed）；本表与 derivers.cjs 同归 owned。
+#
+# 注意：不登记 advisory 总数类指标——它由 check-loop 自身产出（检查 16 是其一部分），
+# 自引用会让「报告本身改变被报告的数」，产生不可稳定对账的循环。
+
+ledger.lines = ledger.lines
+ledger.linesWithoutBatch = ledger.linesWithoutBatch
+ledger.linesWithBatch = ledger.linesWithBatch
+docs.count.intents = docs.count.intents
+docs.count.specs = docs.count.specs
+docs.count.plans = docs.count.plans
+docs.count.incidents = docs.count.incidents
+docs.count.all = docs.count.all

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);