agentic-flow-kit 1.8.1 → 1.8.2

package/templates/_agents/scripts/rule-budget.test.mjs

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// rule-budget.test.mjs — 常驻面预算黑盒套件（2026-10-15 减重手段② 自源仓回灌随附：#count 条目数指令）
+// 夹具：os.tmpdir 下临时目录（非 git 环境——脚本 git rev-parse 失败留在 fixture 目录，
+// 字节口径回退工作区文件；与真实仓「索引/HEAD」口径的差异不影响指令语义判定）。
+// 覆盖：字节超限/未超、#count 超限/压线、旧格式行不受 #count 影响、缺预算表 exit 0、
+//       --staged 无 git（staged 空）时 #count 门跳过。
+// 运行：node templates/_agents/scripts/rule-budget.test.mjs
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT = path.join(path.dirname(fileURLToPath(import.meta.url)), 'rule-budget.mjs');
+
+let pass = 0;
+let fail = 0;
+const check = (desc, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${desc}`); }
+  else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
+};
+
+function makeFixture({ budgets, dirs = {}, files = {} }) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rule-budget-'));
+  if (budgets !== null) {
+    fs.mkdirSync(path.join(root, '.agents'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.agents', 'rule-budgets.txt'), budgets, 'utf8');
+  }
+  for (const [dir, names] of Object.entries(dirs)) {
+    fs.mkdirSync(path.join(root, dir), { recursive: true });
+    for (const n of names) fs.writeFileSync(path.join(root, dir, n), 'x\n', 'utf8');
+  }
+  for (const [f, content] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, f)), { recursive: true });
+    fs.writeFileSync(path.join(root, f), content, 'utf8');
+  }
+  return root;
+}
+
+const run = (cwd, mode = '--all') => {
+  const r = spawnSync(process.execPath, [SCRIPT, mode], { cwd, encoding: 'utf8' });
+  return { code: r.status, out: String(r.stdout || '') };
+};
+
+let root;
+
+// ---- T1 字节超限（旧格式语义不回归）----
+root = makeFixture({
+  budgets: 'AGENTS.md 10\n',
+  files: { 'AGENTS.md': 'x'.repeat(50) },
+});
+{
+  const r = run(root);
+  check('T1 字节超限 exit 1 + 违例行', r.code === 1 && r.out.includes('常驻面超限：AGENTS.md') && r.out.includes('> 上限 10B'), JSON.stringify(r));
+}
+
+// ---- T2 字节未超 → 0 ----
+root = makeFixture({
+  budgets: 'AGENTS.md 100\n',
+  files: { 'AGENTS.md': 'x'.repeat(50) },
+});
+check('T2 字节未超 exit 0', run(root).code === 0);
+
+// ---- T3 #count 超限 ----
+root = makeFixture({
+  budgets: '.agents/rules/ 2#count\n',
+  dirs: { '.agents/rules': ['r01-a.md', 'r02-b.md', 'r03-c.md'] },
+});
+{
+  const r = run(root);
+  check('T3 #count 超限 exit 1 + 条目数违例行 + 一进一出提示', r.code === 1 && r.out.includes('条目数') && r.out.includes('3 项 > 上限 2 项') && r.out.includes('一进一出'), JSON.stringify(r));
+}
+
+// ---- T4 #count 压线（= 上限）→ 0 ----
+root = makeFixture({
+  budgets: '.agents/rules/ 3#count\n',
+  dirs: { '.agents/rules': ['r01-a.md', 'r02-b.md', 'r03-c.md'] },
+});
+check('T4 #count 压线 exit 0', run(root).code === 0);
+
+// ---- T5 混合表：#count 行存在但未触其它字节条目 → 0（互不干扰）----
+root = makeFixture({
+  budgets: 'AGENTS.md 100\n.agents/rules/ 3#count\n',
+  files: { 'AGENTS.md': 'x'.repeat(50) },
+  dirs: { '.agents/rules': ['r01-a.md', 'r02-b.md', 'r03-c.md'] },
+});
+check('T5 混合表双通过 exit 0', run(root).code === 0);
+
+// ---- T6 缺预算表 → exit 0（fixture 沙箱不拦，既有语义）----
+root = makeFixture({ budgets: null });
+check('T6 缺预算表 exit 0', run(root).code === 0);
+
+// ---- T7 --staged 无 git（staged 空）：#count 门跳过不拦 ----
+root = makeFixture({
+  budgets: '.agents/rules/ 2#count\n',
+  dirs: { '.agents/rules': ['r01-a.md', 'r02-b.md', 'r03-c.md'] },
+});
+{
+  const r = run(root, '--staged');
+  check('T7 --staged 无 git 环境跳过 #count 门 exit 0', r.code === 0, JSON.stringify(r));
+}
+
+// ---- T8 glob 形态 #count（* 后缀）也按条数执法 ----
+root = makeFixture({
+  budgets: '.agents/commands/*.md 2#count\n',
+  dirs: { '.agents/commands': ['a.md', 'b.md', 'c.md', 'd.txt'] },
+});
+{
+  const r = run(root);
+  check('T8 glob #count 只数 *.md（3 项 > 2）exit 1', r.code === 1 && r.out.includes('3 项'), JSON.stringify(r));
+}
+
+for (const d of fs.readdirSync(os.tmpdir()).filter((f) => f.startsWith('rule-budget-'))) {
+  try { fs.rmSync(path.join(os.tmpdir(), d), { recursive: true, force: true }); } catch { /* Windows 文件锁容忍 */ }
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/verify.mjs

@@ -24,9 +24,12 @@
 //   提交——新装户由 init 生成器首跑种子该文件，缺文件对 --check 是漂移（红），不静默放行。
 // 绿凭证摘要（gen-verify-evidence.mjs）：全绿尾部自动重生成 workflow/verify-evidence.md——全绿事实与
 //   仓内摘要同刻生成，消除「本地台账已绿、committed 摘要滞后」的双真相分叉；生成失败响亮告警但不推翻绿裁决。
-// 用法：node .agents/scripts/verify.mjs [--list] [--test-cmd "<shell 命令>"] [--doc <本单 workflow 路径>]
-//   --list：按执行序打印门 id 后退出，不执行（与 --test-cmd 互斥）。
+// 用法：node .agents/scripts/verify.mjs [--list] [--test-cmd "<shell 命令>"] [--stub-gate "<命令>"] [--doc <本单 workflow 路径>]
+//   --list：按执行序打印门 id 后退出，不执行（与 --test-cmd / --stub-gate 互斥）。
 //   --test-cmd 用于测试注入，或在无根 package.json 的装户仓指定项目测试命令；
+//   --stub-gate <命令>（2026-10-16 自源仓回灌）：单门夹具但走**生产尾段**（落凭证 / 生成摘要）——
+//     与 --test-cmd 的差异是不打 testCmd 标记、尾段按生产路径执行；**必须配 CHECK_LOOP_ROOT**（夹具根），
+//     禁止在真实仓库写出可被当成关单凭证的绿行。
 //   --doc 把凭证绑到本单，如 --doc workflow/intents/<日期>-<主题>.md
 // 测试：node templates/_agents/scripts/verify.test.mjs（--test-cmd 注入假命令 + CHECK_LOOP_ROOT 注入夹具）
 import fs from 'node:fs';
@@ -59,6 +62,24 @@ const fixtureGates = (cmd) => [
 const args = process.argv.slice(2);
 const explicitTestCmd = args.includes('--test-cmd') ? args[args.indexOf('--test-cmd') + 1] : null;
 
+// --stub-gate（2026-10-16 自源仓 13f67ef7 回灌）：单门夹具但走**生产尾段**（落凭证 / 生成摘要）。
+// 与 --test-cmd 的关键差异：不打 testCmd 标记（fixture 模式绿行带 testCmd:true，生产凭证不与之混淆）。
+// **必须配 CHECK_LOOP_ROOT**——禁止在真实仓库写出可被当成关单凭证的绿行（信任边界：夹具单门不是关单凭证）。
+const stubIdx = args.indexOf('--stub-gate');
+const stubCmd = stubIdx >= 0 ? args[stubIdx + 1] : null;
+if (stubIdx >= 0 && !stubCmd) {
+  console.error('[verify] --stub-gate 需要一条命令');
+  process.exit(2);
+}
+if (stubCmd && explicitTestCmd) {
+  console.error('[verify] --stub-gate 与 --test-cmd 互斥');
+  process.exit(2);
+}
+if (stubCmd && !process.env.CHECK_LOOP_ROOT) {
+  console.error('[verify] --stub-gate 只允许配合 CHECK_LOOP_ROOT 夹具根（禁止在真实仓库落无关单凭证）');
+  process.exit(2);
+}
+
 // --doc 解析（沿 --test-cmd 同款取下一 argv 的写法；缺值报用法错误 exit 1 与 --test-cmd 对称）。
 // 归一基准 = **ROOT**（不是 cwd）——消费方两处都以仓库根为基准（check-loop 检查 8 用
 // path.relative(ROOT, intent)；confirm-doc 的 docRelOf 用 path.resolve(root, doc)）。若这里按 cwd
@@ -78,12 +99,14 @@ const docRel = docArg
 // 装户仓判定：engine-tests 门只在**当前目录**有 package.json 时才跑（npm test 亦在该目录执行）。
 // 跳过时后续不落测试绿凭证（见全绿落账段）。显式 --test-cmd 不受此判定影响。
 const hasRootPackageJson = fs.existsSync(path.join(process.cwd(), 'package.json'));
-const skipTest = explicitTestCmd === null && !hasRootPackageJson;
-const gates = explicitTestCmd ? fixtureGates(explicitTestCmd) : GATES;
+const skipTest = explicitTestCmd === null && stubCmd === null && !hasRootPackageJson;
+const gates = explicitTestCmd ? fixtureGates(explicitTestCmd)
+  : stubCmd ? [{ id: 'stub', name: '夹具单门', cmd: stubCmd, folder: '.', type: 'shell' }]
+  : GATES;
 
 if (args.includes('--list')) {
-  if (explicitTestCmd) {
-    console.error('[verify] --list 与 --test-cmd 互斥');
+  if (explicitTestCmd || stubCmd) {
+    console.error('[verify] --list 与 --test-cmd / --stub-gate 互斥');
     process.exit(1);
   }
   for (const g of gates) console.log(g.id);
@@ -104,7 +127,7 @@ const recordFailure = (step, exitInfo, note) => {
   }
 };
 
-console.log(`[verify] 🚀 开始静态门验证 (共 ${gates.length} 项)${explicitTestCmd ? '【fixture 模式】' : ''}\n`);
+console.log(`[verify] 🚀 开始静态门验证 (共 ${gates.length} 项)${explicitTestCmd ? '【fixture 模式】' : ''}${stubCmd ? '【stub 尾段】' : ''}\n`);
 
 let passedCount = 0;
 const outputs = {};
@@ -173,7 +196,8 @@ try {
 
 // 摘要事件原子化：全绿事实与仓内摘要（workflow/verify-evidence.md）同刻生成，消除「本地台账已绿、
 // committed 摘要滞后」的双真相分叉。仅生产模式（fixture 假门凭证不产 committed 摘要；测试门跳过时
-// 本就无凭证）；生成失败响亮告警但不推翻绿裁决（同落账口径）。
+// 本就无凭证）；stub 尾段按生产路径执行（摘要落在 CHECK_LOOP_ROOT 夹具根，不触真实仓）。
+// 生成失败响亮告警但不推翻绿裁决（同落账口径）。
 if (!explicitTestCmd && !skipTest) {
   const gen = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gen-verify-evidence.mjs'), '--root', ROOT], { encoding: 'utf8' });
   if (gen.status === 0) {

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

@@ -257,6 +257,35 @@ const readLedger = (root) => {
   fs.rmSync(root10, { recursive: true, force: true });
 }
 
+// ---- 场景 12：--stub-gate 走生产尾段（落凭证；2026-10-16 自源仓 13f67ef7 回灌）----
+// 单门夹具但按生产路径落绿行（不打 testCmd 标记）；必须配 CHECK_LOOP_ROOT。
+{
+  const root = mkfix();
+  fs.mkdirSync(path.join(root, 'workflow'), { recursive: true });
+  const git = (args) => spawnSync('git', args, { cwd: root, encoding: 'utf8' });
+  git(['init', '-q']);
+  git(['config', 'user.email', 't@t']);
+  git(['config', 'user.name', 't']);
+  fs.writeFileSync(path.join(root, 'README.md'), 'stub\n');
+  git(['add', '-A']);
+  git(['commit', '-qm', 'base']);
+  const r = run(['--stub-gate', `node ${mkCmd(0)}`], { env: { ...process.env, CHECK_LOOP_ROOT: root, RUN_E2E: '' } });
+  const l = readLedger(root)[0] || null;
+  check('场景 12：stub 单门 exit 0', r.status === 0, `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+  check('场景 12：落绿行（suite=npm test）且无 testCmd 标记',
+    l !== null && l.suite === 'npm test' && l.exitCode === 0 && !('testCmd' in l), JSON.stringify(l));
+  fs.rmSync(root, { recursive: true, force: true });
+}
+// 场景 12b：无 CHECK_LOOP_ROOT → exit 2，不跑门（信任边界：夹具单门不得当真实凭证）
+{
+  const env = { ...process.env, RUN_E2E: '' };
+  delete env.CHECK_LOOP_ROOT;
+  const r = run(['--stub-gate', 'node -e "process.exit(0)"'], { env });
+  check('场景 12b：--stub-gate 无 CHECK_LOOP_ROOT → exit 2 且不跑门',
+    r.status === 2 && String(r.stderr).includes('CHECK_LOOP_ROOT') && !String(r.stdout).includes('全绿'),
+    `exit=${r.status}\n${r.stdout}\n${r.stderr}`);
+}
+
 // ---- 场景 11：--list 锁定 engine cohort 七门序，不执行门 ----
 {
   const expect = ['scripts-syntax', 'engine-tests', 'workflows-check', 'rule-budget', 'effective-policy', 'check-loop', 'ledger-invariant'];

package/templates/_agents/scripts-test-exempt.txt

@@ -4,7 +4,8 @@
 # 新增引擎脚本默认必须带同名 .test.mjs（README 规范条目）；确属库件/工具才登记本文件。
 # 2026-10-09 A2 评估：verify-wiki-consistency 已移出（补测 3 场景）；wiki-search 已移出（转发壳，判定单源 kb-search.test 覆盖）。
 check-metric-claims.mjs | 经 check-loop.mjs 消费 | 由 check-loop.test.mjs 间接覆盖其调用路径
-rule-budget.mjs | 判定器（2026-10-13 自 .sh 移植 node；经 check-hygiene 检查 13 与 pre-commit 消费，Shipyard 侧同无直测） | check-loop.test.mjs 场景 28-30（含 --staged 硬拦两态）+ check-loop-rev.test.mjs 间接覆盖；src/rule-budget.test.mjs 平行实现作口径对照
+# 2026-10-16 减重手段② 随附：rule-budget.mjs 登记撤除（补同名直测黑盒套件 T1-T8——字节语义不回归 +
+# #count 条目数指令全形态；src/rule-budget.test.mjs 仍是包源预算自检门，职责不同并行保留）。
 ensure-board.mjs | 看板启动器 | 永久工具豁免（需真实端口/进程环境，自动化覆盖无性价比——2026-10-09 engine-quality-round2 A2 评估定性）
 policy.mjs | 库件 | 被 check-loop.test.mjs 直接 import 覆盖
 # 2026-10-12 needs-clarification：stage-gates.mjs 已建同名直测（stage-gates.test.mjs 15 断言），

package/templates/_githooks/pre-commit

@@ -3,7 +3,7 @@
 // 2026-10-13 门禁去 sh 化（B2，自 Shipyard.Material 参考实现回灌）：钩子体不再含 sh 逻辑——git 仍以自带
 // sh 启动本文件（钩子机制要求），但 shebang 即 node，PATH 无 sh 不再影响任何逻辑；语言单化后 CI 代理/
 // 本地行为一致。写法为 CommonJS——无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测。
-// 通用门禁序：闭环配对(增量) → 泳道完整性(增量) → wiki 台账(增量) → 索引漂移(增量) → 常驻面体积预算(增量) → 确认台账不变量(暂存触台账) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs)
+// 通用门禁序：闭环配对(增量) → 泳道完整性(增量) → wiki 台账(增量) → 索引漂移(增量) → 常驻面体积预算(增量) → 确认台账不变量(暂存触台账) → 项目门禁(local-pre-commit) → 敏感信息扫描+条件构建(commit-check.cjs；2026-10-16 起常规提交 --no-build——条件构建后移 pre-push 按推送范围执法，合并提交仍 --full 全量构建)
 // 项目专属门禁（架构红线/业务守卫等）放 .agents/hooks/local-pre-commit——sh 挂载点（add-gate 生态按行接线），
 // 存在即在本钩子内以 sh（缺则 bash）执行，返回非零即阻断提交
 // 合并提交场景由 .githooks/pre-merge-commit 原样转发到本脚本（合并时 git 调的是 pre-merge-commit，
@@ -58,7 +58,10 @@ if (branchName.startsWith('experiment/')) {
 //   检查 B「探索标记缺失」——experiment/* 分支暂存 intent 缺「阶段: exploring」→ 拦（标记零成本，
 //   advisory 免纪律不免标记——标记是加固门覆盖率的前提）。
 //   脚本缺失 fail-closed 阻断（见 gate()）。
-gate('泳道完整性（增量）', '.agents/scripts/check-lane-surface.mjs');
+//   `git merge` 自动提交由 pre-merge-commit 传入 `--merge`（此时 MERGE_HEAD 已不可靠，不能靠探测）；
+//   冲突解决后的手动 `git commit` 仍由脚本自己看 MERGE_HEAD（2026-10-16 自源仓回灌）。
+const mergeCommit = process.argv.includes('--merge');
+gate('泳道完整性（增量）', '.agents/scripts/check-lane-surface.mjs', mergeCommit ? ['--merge'] : []);
 
 // wiki 台账门禁（增量，check-wiki-ledger.mjs：暂存区触及 wiki/ 时跑 verify-wiki-consistency 三方一致性；
 // 无 wiki/ 变更即跳过。脚本缺失 fail-closed）
@@ -105,12 +108,14 @@ if (fs.existsSync('.agents/hooks/local-pre-commit')) {
 }
 
 // 合并提交 → 构建验证覆盖【完整合并树】，不做按扩展名的条件裁剪。
+// 常规提交 --no-build（2026-10-16 构建门后移 pre-push，自源仓回灌）：提交内环只跑敏感扫描，条件构建在
+// 推送时按 old..new 范围执法（.githooks/pre-push）；合并结果是没人验证过的新状态，仍全量构建。
 // 两条路径：`git merge` 自动提交由 .githooks/pre-merge-commit 显式传 `--full` 转发到本脚本；
 // 冲突解决后手动 `git commit` 由 git 直接调本脚本，此处按 MERGE_HEAD 探测补上（此时合并仍在进行）。
-let fullArgs = process.argv.slice(2);
+let fullArgs = process.argv.slice(2).filter((a) => a !== '--merge');
 if (fullArgs.length === 0) {
   const mergeHead = spawnSync('git', ['rev-parse', '-q', '--verify', 'MERGE_HEAD'], { encoding: 'utf8' });
-  if (mergeHead.status === 0) fullArgs = ['--full'];
+  fullArgs = mergeHead.status === 0 ? ['--full'] : ['--no-build'];
 }
 
 const cc = spawnSync(process.execPath, ['.agents/hooks/commit-check.cjs', ...fullArgs], { stdio: 'inherit' });

package/templates/_githooks/pre-merge-commit

@@ -8,10 +8,11 @@
 // 靠人工补跑静态门 + 全量测试才覆盖到）。
 //
 // 做法：转发到 .githooks/pre-commit（门禁清单只此一份，避免两份拷贝日后分叉），
-// 并显式传 `--full`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
+// 并显式传 `--full` 与 `--merge`——本钩子「只对 merge 触发」这一身份就是最强信号，无需再去探测
 // MERGE_HEAD（2026-09-19 实测：本时点 MERGE_HEAD 已不可靠）。`--full` 令编译验证
 // 覆盖【完整合并树】、不按扩展名的条件裁剪：合并结果是没人验证过的新状态，且其 diff
-// 相对第一父，裁剪会漏掉需要重跑的一侧。
+// 相对第一父，裁剪会漏掉需要重跑的一侧。`--merge` 令泳道检查 A 跳过（2026-10-16 自源仓回灌：
+// 同窗口 MERGE_HEAD 已不在，已关单产品路径会被误判「触达面判低」）。
 //
 // 冲突解决后手动 `git commit` 走的是 pre-commit 自身，那条路径由 pre-commit 内部的
 // MERGE_HEAD 探测覆盖（此时合并仍在进行，MERGE_HEAD 确定存在）。
@@ -24,5 +25,5 @@ if (top.status !== 0 || !top.stdout.trim()) {
   process.exit(1);
 }
 const hook = path.join(top.stdout.trim(), '.githooks', 'pre-commit');
-const r = spawnSync(process.execPath, [hook, '--full'], { stdio: 'inherit' });
+const r = spawnSync(process.execPath, [hook, '--full', '--merge'], { stdio: 'inherit' });
 process.exit(r.status === null ? 1 : r.status);

package/templates/_githooks/pre-push

@@ -1,82 +1,136 @@
-#!/bin/sh
-# Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）
-# 跑 .agents/scripts/check-loop.sh：扫 workflow/ 闭环骨架断档（2026-10-13 分道——默认只扫硬门，源仓同款）
-#   - 硬阻断（exit 1）= 配对断裂 / 回路断档 等硬门违例 → push 立即阻断
-#   - 卫生项（索引/宿主/词表/体积预算等 WARN 面）不进 push 门——要看时手跑 check-loop.mjs --hygiene
-#     （--all 两面都跑 = 分道前的裸跑全量）
-# stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
-#
-# experiment/* 泳道（2026-09-30 hybrid-governance-explore-hardening）：**目标分支**为 experiment/* 时，
-#   闭环扫描降级 advisory（报告不阻断）——快速 PoC 推送不因闭环断档被拦；转正（目标为 main）由加固门兜底。
-# 加固门（同日；2026-10-01 v09-review-defects 修正判定键）：推送**目标**为 refs/heads/main 时以
-#   --hardening 运行（无论来源分支——experiment/* 直推 main 同样覆盖），exploring 任务须先收口
-#   （intent approved/done + 同名 plan 在场 + L2/L3 另须同名 spec；判据见 check-loop.mjs 加固门段），
-#   hard 失败即阻断 push，防「未文档化的探索件」进 main。
-#
-# 机器门：本地钩子跑 check-loop.sh。装户仓的远端门是随包下发的 .github/workflows/kit-ci.yml（verify.mjs）。
-# kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 跑 npm test（lint + 全量套件）。
-# 装户仓无包源 templates/：sync-hosts 等包源命令不适用。本地钩子仍是提交时刻的机器门。
-# 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+#!/usr/bin/env node
+// Git 原生 pre-push hook（经 core.hooksPath 挂载，git push 时触发）— agentic-flow-kit 通用编排
+// 2026-10-16 node 化（自源仓 2ff869a9/13f67ef7 回灌 pre-push 面）：钩子体不再含 sh 逻辑——git 仍以自带
+// sh 启动本文件（钩子机制要求），但 shebang 即 node，PATH 无 sh 不影响任何逻辑。写法为 CommonJS——
+// 无扩展名文件 node 缺省按 CJS 解析，不依赖 ≥22.7 的 ESM 语法探测。
+// 跑 .agents/scripts/check-loop.mjs：扫 workflow/ 闭环骨架断档（默认只扫硬门）
+//   - 硬阻断（exit 1）= 配对断裂 / 回路断档 / 证据与确认链 / 发版未收口 → push 立即阻断
+//   - 卫生段（模板占位 / 引用漂移 / 宿主副本 / 索引）不在本钩子。要看时跑 --hygiene 或 --all
+// stdin 有行时，每个非删除的本地 sha 用 --rev 扫那棵树。没有行时（手跑钩子）仍无参数扫工作区。
+//
+// 构建门（2026-10-16 自 pre-commit 后移）：另跑 commit-check.cjs --range <old> <new> 按推送范围条件构建
+// （常规提交时刻只做敏感扫描——提交内环提速；构建执法集中到推送与关单）。范围匹配逻辑单源 =
+// commit-check.cjs。experiment/* 目标降级 advisory。手动运行（无 stdin 推送行）无范围事实，构建门跳过。
+//
+// experiment/* 泳道：**目标分支**为 experiment/* 时，闭环扫描与构建门降级 advisory（报告不阻断）——
+// 快速 PoC 推送不因闭环断档/构建失败被拦；转正（目标为 main）由加固门兜底。
+// 加固门（2026-10-01 v09-review-defects）：推送**目标**为 refs/heads/main 时以 --hardening 运行
+// （无论来源分支——experiment/* 直推 main 同样覆盖），exploring 任务须先收口（intent approved/done +
+// 同名 plan 在场 + L2/L3 另须同名 spec；判据见 check-loop.mjs 加固门段），hard 失败即阻断 push。
+//
+// 回路日检（2026-10-16 自源仓 13f67ef7 回灌）：退役催办与 papercut 报债此前无调度，机制空转。每个
+// 本地日在推送成功路径跑一次，advisory，失败不改退出码。摘要落 .agents/cache/loop-watch.jsonl（gitignore）。
+//
+// 机器门：本地钩子跑 check-loop.mjs。装户仓的远端门是随包下发的 .github/workflows/kit-ci.yml（verify.mjs）。
+// kit 源仓：.github/workflows/ci.yml 于 push main / 全部 PR 跑 npm test（lint + 全量套件）。
+// 不要用 `git push --no-verify` 绕开——发现 hard-block 应先修 workflow 文档再推。
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
 
-cd "$(git rev-parse --show-toplevel)" || exit 1
+const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+if (top.status !== 0 || !top.stdout.trim()) {
+  console.error('pre-push: 无法定位仓库根——推送已阻止');
+  process.exit(1);
+}
+process.chdir(top.stdout.trim());
+
+const LOOP = '.agents/scripts/check-loop.mjs';
+if (!fs.existsSync(LOOP)) {
+  console.error(`pre-push: 未找到 ${LOOP}——闭环扫描无法执行，推送已阻止（脚本随包下发；flow-kit sync 恢复后重试）`);
+  process.exit(1);
+}
+// 构建门脚本（2026-10-16 自 pre-commit 后移）：缺失 fail-closed
+const BUILD_CHECK = '.agents/hooks/commit-check.cjs';
+if (!fs.existsSync(BUILD_CHECK)) {
+  console.error(`pre-push: 未找到 ${BUILD_CHECK}——构建门无法执行，推送已阻止（脚本随包下发；git checkout -- ${BUILD_CHECK} 恢复后重试）`);
+  process.exit(1);
+}
 
-SCRIPT=".agents/scripts/check-loop.sh"
-if [ ! -f "$SCRIPT" ]; then
-  echo "pre-push: 未找到 $SCRIPT，跳过闭环扫描" >&2
-  exit 0
-fi
+const runLoop = (args = []) => spawnSync(process.execPath, [LOOP, ...args], { stdio: 'inherit' });
+// 范围参数：远端全零 sha（新分支首推）→ 全量构建语义（commit-check 认全零 old）
+const rangeArgsOf = (remoteSha, localSha) => ['--range', remoteSha && !/^0+$/.test(remoteSha) ? remoteSha : '0'.repeat(40), localSha];
 
-run_loop() {
-  if command -v sh >/dev/null 2>&1; then
-    sh "$SCRIPT" "$@"
-  else
-    bash "$SCRIPT" "$@"
-  fi
+let stdinText = '';
+try { stdinText = fs.readFileSync(0, 'utf8'); } catch { stdinText = ''; }
+
+let saw = 0;
+let rc = 0;
+for (const line of stdinText.split(/\r?\n/)) {
+  if (!line.trim()) continue;
+  const parts = line.trim().split(/\s+/);
+  if (parts.length < 4) continue;
+  const [localRef, localSha, remoteRef, remoteSha] = parts;
+  saw = 1;
+  if (/^0+$/.test(localSha)) continue; // 删除推送不扫
+  // 按目标分支分派（判定键 = remote_ref）：
+  // main → 加固门（必带 --hardening）；experiment/* → advisory（报告不阻断）；其他 → 全量扫描（硬门）
+  if (/^refs\/heads\/main$|^main$/.test(remoteRef)) {
+    const r = runLoop(['--rev', localSha, '--hardening']);
+    if (r.status !== 0 && rc === 0) rc = r.status === null ? 1 : r.status;
+    const rb = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (rb.status !== 0 && rc === 0) rc = rb.status === null ? 1 : rb.status;
+  } else if (/^refs\/heads\/experiment\/|^experiment\//.test(remoteRef)) {
+    console.error(`pre-push: experiment/* 目标分支（${remoteRef}）——闭环扫描与构建门降级 advisory，不阻断`);
+    const adv = spawnSync(process.execPath, [LOOP, '--rev', localSha], { stdio: 'inherit' });
+    if (adv.status !== 0) console.error('pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门');
+    const advB = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (advB.status !== 0) console.error('pre-push: （advisory）构建门未过已在上方列出——experiment 泳道不阻断推送');
+  } else {
+    const r = runLoop(['--rev', localSha]);
+    if (r.status !== 0 && rc === 0) rc = r.status === null ? 1 : r.status;
+    const rb = spawnSync(process.execPath, [BUILD_CHECK, ...rangeArgsOf(remoteSha, localSha)], { stdio: 'inherit' });
+    if (rb.status !== 0 && rc === 0) rc = rb.status === null ? 1 : rb.status;
+  }
 }
 
-saw=0
-rc=0
-while read -r local_ref local_sha remote_ref _remote_sha; do
-saw=1
-case "$local_sha" in
-*[!0]*) ;;
-*) continue ;;
-esac
-# 按目标分支三态分派（2026-10-01 v09-review-defects：判定键从 local_ref 改为 remote_ref——
-# 修复 experiment/*→main 直推被 advisory continue 吞掉加固门的漏口）：
-#   main            → 加固门（必带 --hardening）
-#   experiment/*    → advisory（报告不阻断）
-#   其他            → 全量扫描
-case "$remote_ref" in
-refs/heads/main|main)
-run_loop --rev "$local_sha" --hardening
-;;
-refs/heads/experiment/*|experiment/*)
-echo "pre-push: experiment/* 目标分支（$remote_ref）——闭环扫描降级 advisory，不阻断" >&2
-if command -v sh >/dev/null 2>&1; then
-sh "$SCRIPT" --rev "$local_sha" >&2 || echo "pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门" >&2
-else
-bash "$SCRIPT" --rev "$local_sha" >&2 || echo "pre-push: （advisory）闭环断档已在上方列出——experiment 泳道可推送，转正（推 main）须过加固门" >&2
-fi
-;;
-*)
-run_loop --rev "$local_sha"
-;;
-esac
-one=$?
-if [ "$one" -ne 0 ] && [ "$rc" -eq 0 ]; then
-rc=$one
-fi
-done
+if (saw === 0) {
+  const r = runLoop();
+  if (r.status !== 0) rc = r.status === null ? 1 : r.status;
+  console.error('pre-push: 手动运行无推送范围——构建门跳过（真实推送时按 old..new 范围执法）');
+}
 
-if [ "$saw" -eq 0 ]; then
-  run_loop
-  rc=$?
-fi
+if (rc !== 0) {
+  console.error('pre-push: 闭环骨架断档 / 构建未过（hard-block）未通过，push 已阻断。修 workflow 文档 / 构建错误后重推——不要用 --no-verify 绕过（本钩子是唯一机器门，无服务端兜底，见头部说明）');
+  console.error('pre-push: 若为「加固未过」= experiment 泳道件转正前须收口：intent approved/done + 同名 plan（L2/L3 另须 spec）且状态非 draft');
+  process.exit(rc);
+}
 
-if [ "$rc" -ne 0 ]; then
-  echo "pre-push: 闭环骨架断档（hard-block）未通过，push 已阻断。修 workflow 文档后重推——不要用 --no-verify 绕过（本钩子是唯一机器门，无服务端兜底，见头部说明）" >&2
-  echo "pre-push: 若为「加固未过」= experiment 泳道件转正前须收口：intent approved/done + 同名 plan（L2/L3 另须 spec）且状态非 draft" >&2
-  exit "$rc"
-fi
-exit 0
+// 回路日检（2026-10-16 自源仓 13f67ef7 回灌）：每个本地日在推送成功路径跑一次，advisory，失败不改退出码。
+try {
+  const cacheDir = '.agents/cache';
+  const stampPath = `${cacheDir}/loop-watch-stamp`;
+  const ledgerPath = `${cacheDir}/loop-watch.jsonl`;
+  const now = new Date();
+  const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  let prev = '';
+  try { prev = fs.readFileSync(stampPath, 'utf8').trim(); } catch { /* 首跑 */ }
+  if (prev !== today) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+    // 退役催办：mechanism-retire-watch（--json 产 actions）；papercut 报债：kit 复用 sensor --json 取 debt
+    const jobs = [
+      ['retire-watch', '.agents/scripts/mechanism-retire-watch.mjs'],
+      ['papercut-report', '.agents/scripts/papercut-debt-sensor.mjs'],
+    ];
+    const runs = [];
+    for (const [id, script] of jobs) {
+      if (!fs.existsSync(script)) { runs.push({ id, missing: true }); continue; }
+      const r = spawnSync(process.execPath, [script, '--json'], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+      let summary = {};
+      try { summary = JSON.parse(r.stdout || '{}'); } catch { summary = { parseError: true }; }
+      runs.push({
+        id,
+        exit: r.status,
+        actions: Array.isArray(summary.actions) ? summary.actions.length : null,
+        debt: typeof summary.debt === 'number' ? summary.debt : null,
+      });
+    }
+    fs.appendFileSync(ledgerPath, `${JSON.stringify({ ts: now.toISOString(), day: today, runs })}\n`);
+    fs.writeFileSync(stampPath, `${today}\n`);
+    const retire = runs.find((x) => x.id === 'retire-watch');
+    const paper = runs.find((x) => x.id === 'papercut-report');
+    console.error(`pre-push: （advisory）回路日检已记 ${ledgerPath}（退役动作 ${retire && retire.actions != null ? retire.actions : '?'}，papercut debt ${paper && paper.debt != null ? paper.debt : '?'}）`);
+  }
+} catch (e) {
+  console.error(`pre-push: （advisory）回路日检跳过——${e.message}`);
+}
+process.exit(0);