agentic-flow-kit 1.6.0 → 1.7.15

package/src/rule-budget.test.mjs

@@ -0,0 +1,103 @@
+// rule-budget.test.mjs — 纯包源预算自检门（2026-10-11 budget-self-check）——关闭「纯包源仓不跑装户预算门」盲区。
+// 背景：常驻面预算单源 templates/_agents/rule-budgets.txt（装户命名空间），此前只在装户侧强制
+// （pre-commit --staged 硬拦 / check-loop 13 --all warning）；v1.7.1 起本仓纯包源（5ca9e8c 删装副本）、
+// 两处都不跑——bb69e19/418960a 重构净增 78B 把 .agents/commands/ 推到 65581B > 65536B，包源侧零暴露，
+// 装户首提被硬拦才发现（2026-10-11 S1 冒烟）。本套件把同一张预算表映射到包源路径核对，npm test / CI
+// 直接拦超限——模板增长不再静默入包。run-tests 盘面 glob 自动挂载本套件。
+// 口径（对照 templates/_agents/scripts/rule-budget.sh 单源，勿两处漂移）：
+//   字节 = LF 归一（工作树读入去 \r\n——等价 fsize 的 git cat-file 口径，core.autocrlf 检出形态无关）；
+//   目录合计 = 扁平 glob（直接子文件，不入子目录）；pat=首空格前 / lim=末空格后；lim 非纯数字行跳过；
+//   # 注释与空行跳过。
+// 与装户门的口径差异（诚实声明）：
+//   - AGENTS.md 是渲染模板：装户拿到的是占位符展开后的文件，渲染形态权威仍在装户门；本套件按全部
+//     STACKS 渲染取 max（BOARD_PORT 按最坏 5 位端口）做包源侧近似——单源复用 profiles/render，不复制命令表。
+//   - fail-loud 项（装户侧是 skip，包源侧是打包回归——表不随包或常驻面失踪 = 装户门整体变暗）：
+//     预算表缺失 / 解析 0 行 / 映射目标不存在 / 文件 glob 零命中。装户侧专属面（无包源对应）SKIP 并注记。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderContent } from './render.mjs';
+import { STACKS, pickStackVars } from './profiles.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const BUDGETS = path.join(ROOT, 'templates', '_agents', 'rule-budgets.txt');
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+const lfBytes = (abs) => Buffer.byteLength(fs.readFileSync(abs, 'utf8').replace(/\r\n/g, '\n'), 'utf8');
+
+// ---- 预算表（缺失即 fail-loud：装户门会整体变暗）----
+if (!fs.existsSync(BUDGETS)) {
+  console.log('FAIL R0 预算表缺失 templates/_agents/rule-budgets.txt——装户侧 pre-commit/检查13 将整体 skip');
+  process.exit(1);
+}
+const rows = [];
+for (const line of fs.readFileSync(BUDGETS, 'utf8').split('\n')) {
+  const t = line.replace(/\r/g, '');   // 表文件检出即 CRLF——显式去 \r（rule-budget.sh 同款）
+  if (!t || t.startsWith('#')) continue;
+  const i = t.indexOf(' ');
+  if (i < 0) continue;
+  const pat = t.slice(0, i);
+  const lim = t.slice(t.lastIndexOf(' ') + 1);
+  if (!/^\d+$/.test(lim)) continue;    // 非纯数字 lim 跳过（sh case 同款）
+  rows.push({ pat, lim: Number(lim) });
+}
+check('R1 预算表解析非空', rows.length > 0, `仅 ${rows.length} 行——表被清空即盲区复活`);
+
+// ---- 映射：装户命名空间 → 包源路径（新预算行若只属装户侧，在此登记映射或留 SKIP）----
+function mapToPkg(pat) {
+  if (pat === 'AGENTS.md') return 'templates/AGENTS.md';
+  if (pat.startsWith('.agents/')) return 'templates/_agents/' + pat.slice('.agents/'.length);
+  return null;
+}
+
+const REMEDY = '处置沿先例：压缩版本括号/措辞（71e0b0e、v1.7.10 三处），或在 rule-budgets.txt 注明理由调预算（512B 步进）';
+
+for (const { pat, lim } of rows) {
+  const rel = mapToPkg(pat);
+  if (!rel) { console.log(`SKIP ${pat}——装户侧专属面，无包源对应`); continue; }
+  const abs = path.join(ROOT, rel);
+  if (pat.endsWith('/')) {
+    // 目录合计：扁平直接子文件，不入子目录（sh `for f in "$pat"*` + [ -f ] 同款）
+    if (!fs.existsSync(abs)) { check(`R-dir ${pat} 目标存在`, false, `${rel} 缺失`); continue; }
+    const files = fs.readdirSync(abs, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => e.name);
+    const total = files.reduce((s, n) => s + lfBytes(path.join(abs, n)), 0);
+    check(`R-dir ${rel} 合计 ${total}B ≤ ${lim}B（${files.length} 文件）`, total <= lim, `超 ${total - lim}B。${REMEDY}`);
+  } else if (pat.includes('*')) {
+    // 文件 glob：仅支持 dir 内后缀形（*.md）——与 sh glob 展开同效
+    const dir = path.dirname(abs);
+    const base = path.basename(pat);
+    const suffix = base.slice(base.indexOf('*') + 1);
+    const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => n.endsWith(suffix)) : [];
+    if (files.length === 0) { check(`R-glob ${pat} 有命中`, false, `${dir} 下无 *${suffix}——常驻面失踪或映射失效`); continue; }
+    const sizes = files.map((n) => ({ n, b: lfBytes(path.join(dir, n)) }));
+    const over = sizes.filter((s) => s.b > lim);
+    const maxS = sizes.slice().sort((a, b) => b.b - a.b)[0];
+    check(`R-glob ${path.dirname(rel)}/${base} ${sizes.length} 份，最大 ${maxS.n} ${maxS.b}B ≤ ${lim}B`, over.length === 0,
+      `${over.map((s) => `${s.n}=${s.b}B 超 ${s.b - lim}B`).join('；')}。${REMEDY}`);
+  } else {
+    if (!fs.existsSync(abs)) { check(`R-file ${pat} 目标存在`, false, `${rel} 缺失`); continue; }
+    const b = lfBytes(abs);
+    check(`R-file ${rel} = ${b}B ≤ ${lim}B`, b <= lim, `超 ${b - lim}B。${REMEDY}`);
+  }
+}
+
+// ---- AGENTS.md 渲染近似（装户渲染形态 = 占位符展开；包源侧按全部栈取 max）----
+const agentsRow = rows.find((r) => r.pat === 'AGENTS.md');
+if (agentsRow) {
+  const tpl = fs.readFileSync(path.join(ROOT, 'templates', 'AGENTS.md'), 'utf8');
+  let worst = { stack: '-', b: 0 };
+  for (const stack of Object.keys(STACKS)) {
+    const text = renderContent(tpl, { BOARD_PORT: '99999', ...pickStackVars(stack) });
+    const b = Buffer.byteLength(text.replace(/\r\n/g, '\n'), 'utf8');
+    if (b > worst.b) worst = { stack, b };
+  }
+  check(`R-render templates/AGENTS.md 渲染 max(${worst.stack}) ${worst.b}B ≤ ${agentsRow.lim}B`, worst.b <= agentsRow.lim,
+    `超 ${worst.b - agentsRow.lim}B——渲染形态超限装户门同样会拦，先压模板正文。${REMEDY}`);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/src/run-tests.mjs

@@ -11,16 +11,17 @@ import { fileURLToPath } from 'node:url';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
+// src/ 侧按盘面枚举，不硬编码清单（2026-10-09 审查 P0-1）——此前硬编码 8 项，`src/sync-hosts.test.mjs`
+// 漏挂：npm test 不跑它，CI 也盖不住（ci.yml shipped 步骤只 glob `.agents/scripts/*.test.mjs`），
+// 而 `templates/_agents/commands/sync-hosts.md:62`「npm test 含 sync-hosts.test.mjs 8 场景」随模板
+// 下发 5 个装户宿主。检查 20 只扫 `templates/_agents/scripts/` 面，结构上抓不到 src/ 漏挂。
+// 改 glob 后：新增 src 测试文件不可能再被静默漏跑（枚举漂移由盘面兜住，不靠人记得补）。
+// 含宿主门禁模块回归（2026-09-27 host-gates-p1：dotnet-ca BRE 豁免/fail-closed + trae 强推 token 化）。
 const nodeSuites = [
-  'src/sync.test.mjs',
-  'src/init.test.mjs',
-  'src/pack.test.mjs',
-  'src/gates.test.mjs',
-  'src/fresh-init.test.mjs',
-  'src/stack-profile.test.mjs',
-  // 宿主门禁模块回归（2026-09-27 host-gates-p1：dotnet-ca BRE 豁免/fail-closed + trae 强推 token 化）
-  'src/gate-dotnet-ca.test.mjs',
-  'src/trae-hooks.test.mjs',
+  ...fs.readdirSync(path.join(ROOT, 'src'))
+    .filter((f) => f.endsWith('.test.mjs'))
+    .sort()
+    .map((f) => `src/${f}`),
   ...fs.readdirSync(path.join(ROOT, 'templates/_agents/scripts'))
     .filter((f) => f.endsWith('.test.mjs'))
     .sort()
@@ -46,4 +47,10 @@ for (const rel of nodeSuites) {
 }
 
 console.log(`\n${failed ? `❌ ${failed} 个套件失败` : '✅ 全部套件通过'}`);
+// 机器可读汇总行（2026-10-09 审查 P0-2）：verify.mjs 的凭证计数**只认这一行**。
+// 此前它 pop 通配「合计: PASS n / FAIL n」，而 45+ 套件每个都打印自己那行同形文本——
+// 取到的是字母序最后一个套件的场景数（本仓实况：workflows-check.test.mjs 的 15），
+// 于是「一行机器事实」的 passed 字段落成了错的事实。独立前缀 + 套件口径，嵌套同形行不再被误取。
+// 口径：SUITES = 本编排器实际执行的套件数（lint 不计入；lint 红照样 exit 1，凭证不落）。
+console.log(`[run-tests] 合计: SUITES ${nodeSuites.length} / FAILED ${failed}`);
 process.exit(failed ? 1 : 0);

package/src/sync-hosts.mjs

@@ -26,8 +26,10 @@ function splitFm(text) {
 }
 
 // bodySha：剥离 frontmatter 后的正文段 sha256（缺失返 null）；正文 LF 归一（2026-09-27 closing-coverage：
-// CRLF/LF 盘面同值——权威源与薄适配行尾不一致不再误报漂移，与 doctor §6.7 同口径）
-function bodySha(p) {
+// CRLF/LF 盘面同值——权威源与薄适配行尾不一致不再误报漂移）。
+// 单源 export（2026-10-11 bodysha-single-source）：doctor §6.7 checkAdapterDrift 复用——此前 doctor
+// 内联第二份实现靠注释约束同口径，收敛为单源 import 消灭漂移面。
+export function bodySha(p) {
   try {
     const { body } = splitFm(fs.readFileSync(p, 'utf8'));
     return sha256(Buffer.from(body.replace(/\r\n/g, '\n'), 'utf8'));

package/src/trae-hooks.test.mjs

@@ -39,6 +39,17 @@ const runHook = (command, cwd) => {
   return { decision, reason, raw: r.stdout || '', status: r.status };
 };
 
+// 门禁在位桩（2026-10-09 装户端内容清理后）：纯包源仓无 .githooks/——hook 第二道关卡
+// （commit/push 前置 .githooks/*）在仓内必判「门禁未执行」。①/②/②附 的 token 边界断言
+// 需要「门禁通过」语境：造临时目录放通过型桩门禁当 cwd；③ 另用空目录保留「缺失 → 门禁未执行」deny。
+const GATE_FIXTURE = fs.mkdtempSync(path.join(os.tmpdir(), 'trae-hook-gates-'));
+fs.mkdirSync(path.join(GATE_FIXTURE, '.githooks'));
+for (const name of ['pre-commit', 'pre-push']) {
+  const stub = path.join(GATE_FIXTURE, '.githooks', name);
+  fs.writeFileSync(stub, '#!/usr/bin/env bash\nexit 0\n');
+  fs.chmodSync(stub, 0o755);
+}
+
 // ---- ① 强推 token 化（P1-B2）----
 {
   const cases = [
@@ -54,7 +65,7 @@ const runHook = (command, cwd) => {
     ['dotnet build --force', 'none', '非 push 命令带 --force 不误拦'],
   ];
   for (const [cmd, expect, label] of cases) {
-    const r = runHook(cmd);
+    const r = runHook(cmd, GATE_FIXTURE);
     check(`①${label}（${cmd}）→ ${expect === 'none' ? '放行' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -79,7 +90,7 @@ const runHook = (command, cwd) => {
     ['git commit -m "fix: 修复"', 'none'], // commit 走 .githooks 链（本仓有钩子且全绿）；deny 门本身不应拦 commit
   ];
   for (const [cmd, expect] of cases) {
-    const r = runHook(cmd, PKG_ROOT); // cwd=本仓：git commit 场景能找到 .githooks
+    const r = runHook(cmd, GATE_FIXTURE); // cwd=桩门禁目录：git commit 能通过第二道关卡，只测 deny/ask 门
     check(`②${cmd} → ${expect === 'none' ? '不因 deny/ask 门拦' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -94,7 +105,7 @@ const runHook = (command, cwd) => {
     ['git commit -m "真正要拦的消息"', 'none', '普通消息照常'],
   ];
   for (const [cmd, expect, label] of cases) {
-    const r = runHook(cmd, PKG_ROOT);
+    const r = runHook(cmd, GATE_FIXTURE);
     check(`②附 ${label} → ${expect === 'none' ? '不误拦' : expect}`,
       r.decision === expect,
       `decision=${r.decision} reason=${r.reason}`);
@@ -112,4 +123,5 @@ const runHook = (command, cwd) => {
 }
 
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+fs.rmSync(GATE_FIXTURE, { recursive: true, force: true });
 process.exit(fail ? 1 : 0);

package/src/validate.mjs

@@ -0,0 +1,72 @@
+// flow-kit validate：只读校验装户盘面（2026-10-10 validate-entry；对照 OpenSpec validate 形态：
+// 只读 + 0/1 退出码 + --strict/--json）。
+// 语义：用**包内置** check-loop 引擎（templates/_agents/scripts/check-loop.mjs 的 runCheckLoop，
+// isMain 主守卫保证 import 零副作用）对目标仓 workflow/ 闭环跑全部 20 项检查——不执行装户侧
+// .agents/scripts/*（供应链面：判定引擎随包版本走、目标侧零代码执行；doctor 走另一极：scriptGuard
+// 先验后跑装户侧脚本，两命令互补不重复）。root 经 runCheckLoop({root}) 传入，spawnGit 以 cwd:ROOT
+// 落在目标仓——tracked 过滤按目标仓 HEAD 算，与 git 钩子看到的提交面一致。
+// 只读范围：check-loop 自身仅有的两处落盘都在 .agents/cache/ 运行时缓存（gate-stats 需 --gate-stats
+// 才触发、added-dates 缓存 best-effort），且该目录已 gitignore——本命令不改任何文档与台账。
+// 不暴露 --rev：runCheckLoop 中 rev 与 root 互斥（提交时点判定属钩子链职责，validate 只看盘面现状）。
+// 输出契约：check-loop 的 HARD-BLOCK/WARN 两段式原样走 stderr（稳定输出契约，消费者 .githooks/pre-push）；
+// stdout 只承载本命令的汇总行 / --json——机器消费者按 stdout 解析，人按 stderr 读明细。
+// 退出码：blocker → 1；--strict 下 advisory warning 同样 → 1（判据单源 validateExit，纯函数可单测）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+// 退出码判定单源（独立 export 供单元测试）：引擎 exitCode 非 0 → 1；--strict 时 warning 也红；
+// 结果缺失（引擎调用异常路径）fail-closed → 1。
+export function validateExit(result, strict) {
+  if (!result || result.exitCode !== 0) return 1;
+  if (strict && (result.warnings || []).length > 0) return 1;
+  return 0;
+}
+
+export async function validate(args, pkgRoot) {
+  let target = process.cwd();
+  let strict = false;
+  let json = false;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--dir') target = path.resolve(args[++i]);
+    else if (args[i] === '--strict') strict = true;
+    else if (args[i] === '--json') json = true;
+    else {
+      console.error(`validate: 未知参数 ${args[i]}——用法 flow-kit validate [--strict] [--json] [--dir <目录>]`);
+      process.exit(1);
+    }
+  }
+
+  // 装户盘面前置：枚举单源（workflow-enums.txt 等）都在 .agents/ 下，无装副本则引擎无从判定——
+  // 先给指引再红，不产出「20 项全断档」的噪音墙
+  if (!fs.existsSync(path.join(target, '.agents'))) {
+    const msg = `缺 .agents/——validate 校验 flow-kit 装户盘面，先跑 npx agentic-flow-kit init`;
+    if (json) console.log(JSON.stringify({ target, strict, checkLoopExitCode: null, exitCode: 1, blockers: [msg], warnings: [] }, null, 2));
+    else console.error(`❌ validate: ${target} ${msg}`);
+    process.exit(1);
+  }
+
+  // 动态 import 包内置引擎：pkgRoot = npx 缓存 / 全局安装 / 仓内直跑三种形态下都指向包源模板
+  const engineUrl = pathToFileURL(path.join(pkgRoot, 'templates', '_agents', 'scripts', 'check-loop.mjs')).href;
+  const { runCheckLoop } = await import(engineUrl);
+  const result = runCheckLoop({ root: target });
+  const code = validateExit(result, strict);
+
+  if (json) {
+    console.log(JSON.stringify({
+      target,
+      strict,
+      checkLoopExitCode: result.exitCode,
+      exitCode: code,
+      blockers: result.blockers,
+      warnings: result.warnings,
+    }, null, 2));
+  } else {
+    const n = (result.blockers || []).length;
+    const w = (result.warnings || []).length;
+    if (code === 0) console.log(`✅ flow-kit validate 通过——blocker 0 / warning ${w}${w ? '（advisory 不阻断；--strict 可把 warning 判红）' : ''}`);
+    else if (result.exitCode !== 0) console.log(`❌ flow-kit validate 未通过——blocker ${n} / warning ${w}（明细见上方 HARD-BLOCK / WARN 输出）`);
+    else console.log(`❌ flow-kit validate（--strict）未通过——warning ${w} 条判红（默认退出码 0，advisory 不阻断）`);
+  }
+  process.exit(code);
+}

package/src/validate.test.mjs

@@ -0,0 +1,95 @@
+// validate.test.mjs — flow-kit validate 断言（2026-10-10 validate-entry）。
+// 两层：validateExit 纯函数直测（退出码判据单源）+ 端到端 spawn 真 CLI（bin/flow-kit.mjs validate，
+// --json 断言 stdout 可解析、退出码契约、缺 .agents/ 指引、未知参数用法错）。
+// fixture 沿 check-loop.test.mjs 同款：临时根（workflow 四目录 + .agents/ + 枚举单源内联 8 键），
+// 自包含、不依赖真实 git 与 workflow 文档。
+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';
+import { validateExit } from './validate.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = path.join(ROOT, 'bin', 'flow-kit.mjs');
+
+let pass = 0, fail = 0;
+function check(name, cond, detail = '') {
+  if (cond) { pass++; console.log(`PASS ${name}`); }
+  else { fail++; console.log(`FAIL ${name}${detail ? `——${detail}` : ''}`); }
+}
+
+// ---- validateExit 纯函数（判据单源）----
+check('V1 blocker → 1', validateExit({ exitCode: 1, blockers: ['x'], warnings: [] }, false) === 1);
+check('V2 干净 → 0', validateExit({ exitCode: 0, blockers: [], warnings: [] }, false) === 0);
+check('V3 warning 非 strict → 0', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, false) === 0);
+check('V4 warning + strict → 1', validateExit({ exitCode: 0, blockers: [], warnings: ['w'] }, true) === 1);
+check('V5 引擎结果缺失 fail-closed → 1', validateExit(null, false) === 1 && validateExit(undefined, true) === 1);
+
+// ---- fixture（枚举单源内联，同 check-loop.test.mjs#ENUMS_FIXTURE）----
+const ENUMS_FIXTURE = [
+  'doc.status.all=draft approved done superseded cancelled',
+  'doc.status.confirmed=approved done superseded cancelled',
+  'doc.status.active=draft approved',
+  'doc.status.terminal=done superseded cancelled',
+  'doc.status.abandoned=superseded cancelled',
+  'incident.status.all=open fixed closed',
+  'incident.status.active=open',
+  'level.all=L0 L1 L2 L3',
+].join('\n') + '\n';
+
+const mkfix = () => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-'));
+  for (const s of ['intents', 'specs', 'plans', 'incidents']) {
+    fs.mkdirSync(path.join(d, 'workflow', s), { recursive: true });
+  }
+  fs.mkdirSync(path.join(d, '.agents'), { recursive: true });
+  fs.writeFileSync(path.join(d, '.agents', 'workflow-enums.txt'), ENUMS_FIXTURE);
+  return d;
+};
+
+const runValidate = (dir, args = []) => spawnSync(process.execPath, [CLI, 'validate', '--dir', dir, ...args], {
+  cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024,
+});
+const stdoutOf = (r) => r.stdout || '';
+const stderrOf = (r) => r.stderr || '';
+
+// ---- 端到端：绿盘面（空四目录 + 枚举单源）----
+const green = mkfix();
+const rg = runValidate(green, ['--json']);
+let greenJson = null;
+try { greenJson = JSON.parse(stdoutOf(rg)); } catch { /* 解析失败在断言里报 */ }
+check('V6 绿盘面 exit 0', rg.status === 0, `exit=${rg.status}\n${stdoutOf(rg)}\n${stderrOf(rg).slice(0, 300)}`);
+check('V7 --json stdout 可解析且 blockers 空', !!greenJson && Array.isArray(greenJson.blockers) && greenJson.blockers.length === 0, stdoutOf(rg).slice(0, 300));
+check('V8 --json 契约字段在位', !!greenJson && greenJson.exitCode === 0 && greenJson.checkLoopExitCode === 0 && greenJson.strict === false && typeof greenJson.target === 'string', JSON.stringify(greenJson));
+// --strict 契约端到端：同一盘面 fixture 恒产出 advisory warning（装副本骨架件缺失类，绿判不受其扰），
+// 非 strict 绿（V6 已证）、strict 判红且 checkLoopExitCode 保持 0——判红来源是 strict 规则而非引擎
+const rs = runValidate(green, ['--json', '--strict']);
+let strictJson = null;
+try { strictJson = JSON.parse(stdoutOf(rs)); } catch { /* 同上 */ }
+check('V9 --strict 把 advisory warning 判红（checkLoopExitCode 仍 0）',
+  rs.status === 1 && !!strictJson && strictJson.exitCode === 1 && strictJson.checkLoopExitCode === 0 && strictJson.strict === true && strictJson.warnings.length > 0,
+  `exit=${rs.status}\n${stdoutOf(rs).slice(0, 300)}`);
+
+// ---- 端到端：红盘面（同名配对断档：intent 无同名 spec/plan → 检查 1 hard-block）----
+const red = mkfix();
+fs.writeFileSync(path.join(red, 'workflow', 'intents', '2026-01-01-solo.md'),
+  '---\nstatus: draft\nlevel: L1\n---\n# INTENT — solo\n');
+const rr = runValidate(red, ['--json']);
+let redJson = null;
+try { redJson = JSON.parse(stdoutOf(rr)); } catch { /* 同上 */ }
+check('V10 配对断档 exit 1', rr.status === 1, `exit=${rr.status}\n${stdoutOf(rr).slice(0, 300)}\n${stderrOf(rr).slice(0, 500)}`);
+check('V11 --json blockers 非空且明细走 stdout JSON', !!redJson && redJson.blockers.length > 0, stdoutOf(rr).slice(0, 300));
+
+// ---- 指引与用法错 ----
+const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'flow-kit-validate-bare-'));
+const rb = runValidate(bare);
+check('V12 缺 .agents/ → exit 1 且给 init 指引', rb.status === 1 && /init/.test(stderrOf(rb)), `exit=${rb.status}\n${stderrOf(rb).slice(0, 300)}`);
+const ru = runValidate(green, ['--bogus']);
+check('V13 未知参数 → exit 1 用法行', ru.status === 1 && /用法/.test(stderrOf(ru)), `exit=${ru.status}\n${stderrOf(ru).slice(0, 300)}`);
+
+// ---- 清理 ----
+for (const d of [green, red, bare]) fs.rmSync(d, { recursive: true, force: true });
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/AGENTS.md

@@ -28,7 +28,8 @@
 - **`git commit` / `git merge` / `git push` 三处一律禁 `--no-verify`**——被拦说明产出不合规，按提示修完原路重试。
 - 项目专属门禁挂 `.agents/hooks/local-pre-commit`。装户五条硬规则（配对、验收、确认留痕、敏感信息、双源台账）与 `audit` 档见 `workflow/README.md`「硬规则」。
 - 提交遵循 Conventional Commits 中文（feat / fix / docs / style / refactor / perf）。L1+ 三段式闭环链：`docs(*)` approved 留痕 → 代码 → 关单 `docs(*)`，相邻提交即同一闭环（2026-10-04 修订）。
-- **确认门（2026-09-27 起）**：intent/spec/plan 的 approved/done 与 incident 的 fixed/closed（两跳、无单跳）唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`，放弃态走显式 `--to superseded|cancelled`（合法前态见脚本提示；四终态同样内容绑定），两形态：① 用户终端亲手运行键入「可以」（TTY，AI 会话内被拒）；② **对话委托代录**——用户在对话内明确确认后，AI 跑 `confirm-doc.mjs <path> --delegated "<用户原话>"` 逐件代录（默认一次一份，多份并录被拒），台账如实记 `source: chat-delegated` + 原话供对质，永不伪装 TTY 行（check-loop 15 指纹+台账对账拦截，与 source 无关）；L0/L1 协作道可 `--batch` 多份一次代录（台账 `brief:true`，15 并录告警豁免；L2/L3 仍逐份）。
+- **确认门（2026-09-27 起）**：intent/spec/plan 的 approved/done 与 incident 的 fixed/closed（两跳、无单跳）唯一入口 = `node .agents/scripts/confirm-doc.mjs <path>`，放弃态走显式 `--to superseded|cancelled`（合法前态见脚本提示；四终态同样内容绑定），两形态：① 用户终端亲手运行键入「可以」（TTY，AI 会话内被拒）；② **对话委托代录**——用户在对话内明确确认后，AI 跑 `confirm-doc.mjs <path> --delegated "<授权摘要>"` 逐件代录（默认一次一份，多份并录被拒），台账如实记 `source: chat-delegated`，永不伪装 TTY 行（check-loop 15 指纹+台账对账拦截，与 source 无关）；L0/L1 协作道可 `--batch` 多份一次代录（台账 `brief:true`，15 并录告警豁免；L2/L3 仍逐份）。
+- **改动面 scope = 授权的机器事实（2026-10-09 起）**：confirm-doc 落账自动记 `scope{files,sha256}`（被确认文档 + `git status` 实测未提交改动集，机器派生、**AI 无输入面**）。分辨力由 scope + 指纹承担，`--delegated` 的摘要降级为人类可读留痕——**「每次换一句原话」纪律退役**，复用同一句摘要不再削弱任何判据。check-loop 15 校验受管行带 scope 且摘要自洽（`policyVersion ≥ 7` 起，旧版本与存量行零新增告警）。
 
 ### 检索、看板与量化
 
@@ -45,6 +46,7 @@
 `wiki/` 是项目知识沉淀，按主题目录归位；原始 / 一次性文档归档 `wiki/drafts-archive/<日期-主题>/`（只读不增量）。
 
 - 人工只维护两样：**磁盘文件本身 + `wiki/INDEX.md` 速览表「用途」列**；计数 / 映射表 / 看板 DATA 均为生成区，勿手改——`node .agents/scripts/gen-wiki-board.mjs` 重生成，`node .agents/scripts/verify-wiki-consistency.mjs` 三方一致性验证（触及 `wiki/` 的提交会被 pre-commit 台账门禁校验）。
+- **沉淀与血缘（2026-10-10 起）**：关单时 `node .agents/scripts/draft-sediment.mjs workflow/<intents|incidents>/<本单>.md` 自动把高价值节抽成 `drafts-archive/` 草稿（`--dry-run` 预览；全占位拒抽）；草稿是中间态，人工归类到 `wiki/<主题>/` 后跑生成器 + 验证。沉淀关系用 frontmatter 双向链接：wiki 文件 `来源: workflow/…`、workflow 文件 `沉淀: wiki/…`（不沉淀写 `沉淀: 无`）——两向字段的存在性由 verify-wiki-consistency 与 check-loop 校验，改名 / 移动时须同步。
 - wiki 看板：`wiki/知识沉淀总览.html`。
 
 ## 项目适配区（项目自填）

package/templates/_agents/commands/build.md

@@ -27,7 +27,7 @@ next: .agents/commands/test.md
 
 起草 intent / spec / plan 任一件后，**在输出草稿全文前先给三件要点总览**（各一件：目标 / 关键取舍 /
 验收判据 diff，合计 ≤12 行）——用户一次看整体再逐件拍板，省三次盲确认的上下文切换。
-确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录、禁复用同句）。本阶段总览侧重：plan 任务拆解与两道确认门位置。
+确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录；摘要可复用——分辨力由 scope+指纹承担，2026-10-09 起）。本阶段总览侧重：plan 任务拆解与两道确认门位置。
 
 ## 1. 执行
 
@@ -38,7 +38,7 @@ next: .agents/commands/test.md
    - 复制 `workflow/plans/_TEMPLATE.md` → `workflow/plans/YYYY-MM-DD-<主题>.md`(与入口文档同名)
    - L2/L3 按 4 节填写:改动方案 / 任务拆解(每个任务有判据) / 执行顺序 / 验证计划（与 fill-plan.mjs 单源一致）
    - L1 使用 Quick-Plan 极简三节:改动方案 / 约束与风险(原 Spec 核心) / 验证计划；多文件多步骤时可补任务拆解/执行顺序
-3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件配逐件原话**:`--delegated` 每次传当次实际放行的措辞,不复用同句——复用同句使台账 quote 失去分辨力(事后对质看不出放行的是哪一件);原因与根治见 workflow/papercuts.md 2026-09-28。
+3. 停下,输出 plan 草稿全文给用户过目,一句"可以"即确认。**逐件确认**:入口文档 / spec / plan 各自的确认点不得并作一次,plan 草稿须全文过目(不接受摘要代替)。**逐件代录**:`--delegated "<授权摘要>"` 每件单独一次——摘要为人类可读留痕,复用同句不削弱判据(分辨力由落账自动记录的改动面 `scope{files,sha256}` 与文档指纹承担,2026-10-09 起)。
    **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 一次一份多份并录被拒 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 4. 确认后 → plan 状态 draft → approved,并在 plan 内补「确认与复核」节(确认结果 + 日期)。确认环节须在文档留痕:`approved` 是确认的机器可见态,`done` 只在关单出现,禁从 `draft` 直跳 `done`;确认后立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)。
 
@@ -48,7 +48,7 @@ next: .agents/commands/test.md
    - **先拉同模块历史坑**：按入口文档 `模块:` 跑 `node .agents/scripts/kb-search.mjs --scope workflow --module <token> "<关键词>"`——命中 incident 的根因 / 防复发条目列入改动自查
    - 列改动文件清单(读后改 vs 新建)
    - 列步骤(改 X 文件做 Y → 改 Z 文件做 W)
-   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（见 incidents/2026-09-25-wf-runtime 复盘）
+   - **owned 文件同步**：kit.owned 列表文件（AGENTS.md / workflow 模板等）sync 不动，须列「手动同步装副本」步骤（仅包源/dogfood 双形态仓适用；纯装户仓 owned 即项目自有文件，无此步）
    - 标注触达红线(对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）)
 6. 停下,等用户确认改动清单。
 
@@ -71,32 +71,13 @@ next: .agents/commands/test.md
 
 - 红线(架构 / 数据 / 安全等)正文与豁免见根与目录级 `AGENTS.md`(如有)——已由 pre-commit 机器门强制的部分以钩子为准，写代码前先过一遍目录级 AGENTS
 
-## 4. 改权威源后必跑（薄适配同步防漏）
-
-- 改 `templates/_agents/{commands,roles}/*.md` 正文后跑 `node bin/flow-kit.mjs sync-hosts --diff` → 拍板 → `--apply` 单向同步（只动正文段，frontmatter 不动）；口径与边界详见 `.agents/commands/sync-hosts.md`
-- 改根 `AGENTS.md`（owned 常驻面）后跑 `node .agents/scripts/edit-face-check.mjs`——工作树面快检（阶段索引/引用/预算 advisory），别等提交门才发觉砍坏（2026-10-09 B2）
-
-## 5. 改 doctor / check-loop 后必跑（三处口径对账）
-
-- 改 `src/doctor.mjs` 加新 § 检查项 → 跑 `node .agents/scripts/gate-checklist.mjs --diff` 看 doctor ↔ check-loop 对照表
-- 改 `.agents/scripts/check-loop.sh` 加新 § 检查项 → 同上
-- 任一处有而另一边无 → 工具报"缺点"，由用户拍板是否补齐（不自动同步，B-b 决策）；详见 `.agents/commands/gate-checklist.md`
-
-## 6. 改包源后必跑（装户面同步一致性）
-
-- 改 `templates/_agents/*` 包源后 → 跑 `node .agents/scripts/source-sync-check.mjs --diff` 看装副本 `.agents/` 是否同步（缺失 / 孤儿 / 漂移三类差异）
-- 漂移说明包源改了装副本未跟；缺失说明新增文件 init 未执行；孤儿说明装副本独有（可能是装户配置，不删）
-- **新增 managed 类文件须经 init/sync 登记，禁手动双写绕过台账**——手工同时写 `templates/_agents/` 与 `.agents/` 会绕过台账登记，使该文件永远不被 sync 升级（`doctor` 台账覆盖率检查会拦；见 incidents/2026-09-26-managed-ledger-adopt 复盘）
-- 门禁边界（pre-commit 双源一致性）：比较工作树非暂存区——两侧改好、分两笔提交不拦（最终一致即可）；包源删除文件退化为「孤儿」只报告不拦，删包源须手动清理装副本残件（复核 P2-2 声明，2026-09-27 gate-hardening-p2-batch）
-- B-b 决策「只报告不修复」；详见 `.agents/commands/source-sync-check.md`
-
-## 7. 子代理调用约定
+## 4. 子代理调用约定
 
 - plan 起草、风险判断、改动清单与两道确认门由主智能体负责;仅两道确认后范围明确的工作包可委派 `implementer`,公共接口 / Schema / 依赖 / 安全 / 权限 / 破坏性操作不得委派。
 - 多工作包并行 / 链式推进:编排机制(声明随 plan 草稿一并确认;确认后读 `.agents/workflows/` 按机制文档执行,`steps/` 为项目自定义步骤扩展点);详见 `.agents/workflows/_TEMPLATE.md`。
 - 子智能体返回后,主智能体须检查 diff 与授权文件范围、确认未覆盖既有修改并重跑相关验证;不支持子智能体时 `fallback: main`,验收标准不变。
 
-## 8. 确认后
+## 5. 确认后
 
 - plan 状态 → done（实现完成；intent / spec 关单在 test）
 - commit：L1+ 入口文档 / spec / plan 随代码同一提交（Conventional Commits 中文 feat/fix/refactor/perf）；docs 豁免与 bootstrap 可单独 `docs(*)`

package/templates/_agents/commands/deploy.md

@@ -49,6 +49,7 @@ next: .agents/commands/maintain.md(仅事故时)
 ## 6. 上线后观察(用户观察,Maintain 阶段接手)
 
 - 观察期:上线后 24h;由用户观察错误率 / 延迟 / 关键业务流(无监控时人工看)
+- 异常判据(观察期退出规则):项目口径填 `workflow/regression-checklist.md`——无监控时的最低判据:错误日志 / 异常告警 / 关键业务流失败**任一出现即触发 §5 回滚预案,不等 24h**;无异常满 24h 方可闭环
 - 闭环宣告:用户确认无异常后才算闭环;AI 不得自行宣告
 - 异常回落:超阈值 → 生成 `workflow/incidents/YYYY-MM-DD-<主题>.md`,进 `maintain.md`(止血方案用户拍板,见 maintain.md §0)
 - 事故响应:单用途账号 + 最小权限;不得跨智能体协作推送修复(参考 Anthropic 教训)

package/templates/_agents/commands/design.md

@@ -24,7 +24,7 @@ next: .agents/commands/build.md
 
 起草 intent / spec / plan 任一件后，**在输出草稿全文前先给三件要点总览**（各一件：目标 / 关键取舍 /
 验收判据 diff，合计 ≤12 行）——用户一次看整体再逐件拍板，省三次盲确认的上下文切换。
-确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录、禁复用同句）。本阶段总览侧重：spec 方案取舍与 L3 复核安排。
+确认纪律不变：逐件过目全文 + 逐件 `confirm-doc` 代录（禁并录；摘要可复用——分辨力由 scope+指纹承担，2026-10-09 起）。本阶段总览侧重：spec 方案取舍与 L3 复核安排。
 
 ## 1. 执行
 
@@ -57,6 +57,6 @@ next: .agents/commands/build.md
 ## 4. 确认后
 
 - spec 状态 draft → approved
-- **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件调用+逐件原话 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
+- **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件代录（摘要可复用——分辨力由 scope+指纹承担）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 - 立即 `docs(workflow)` 单独提交留痕(根 `AGENTS.md` 提交约定;check-loop 检查 14 口径)
 - 进 `next: .agents/commands/build.md`

package/templates/_agents/commands/gate-checklist.md

@@ -88,6 +88,4 @@ npm test                                       # 含 gate-checklist 套件
 
 ## 6. 相关留痕
 
-- intent（登记表重写）：`workflow/intents/2026-09-25-gate-checklist-registry.md`
-- intent（工具首建）：`workflow/intents/2026-09-25-gate-checklist.md`
-- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（owned 漂移未对账，催生本工具）
+- 立法出处：2026-09-25（登记表重写 + 工具首建；父事件 = owned 漂移未对账，催生本工具）——留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径

package/templates/_agents/commands/plan.md

@@ -28,7 +28,7 @@ next: L1 → .agents/commands/build.md (起草 Quick-Plan) ；L2/L3 → .agents/
    - 红线勾选对照根 `AGENTS.md` 红线/约束相关节（如「项目适配区」「门禁与提交」）+ 改动域目录级 `AGENTS.md`（如有）;**没触及就全不勾**,不要硬填
 3. 写不出可测试判据 = 还没想清楚 → 反问澄清,不要硬填。
 4. 起草后停下,输出草稿全文给用户过目,一句"可以"即确认。
-   **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件调用+逐件原话 / 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
+   **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（draft→approved / approved→done；TTY 两形态 / 逐件代录（摘要可复用——分辨力由 scope+指纹承担）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
 
 ## 2. 技能辅助(可选,宿主级 skills)
 

package/templates/_agents/commands/source-sync-check.md

@@ -100,6 +100,4 @@ flow-kit doctor                                     # 10/0/0
 
 ## 6. 相关留痕
 
-- intent：`workflow/intents/2026-09-25-source-sync-check.md`
-- plan：`workflow/plans/2026-09-25-source-sync-check.md`
-- 父 incident：`workflow/incidents/2026-09-25-wf-runtime.md`（包源改了装副本未同步——本工具预防性体检）
+- 立法出处：2026-09-25 source-sync-check（intent/plan；父事件 = 包源改了装副本未同步，本工具预防性体检）——留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径

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

@@ -80,6 +80,4 @@ sh .agents/scripts/check-loop.sh                # Windows 无 sh 时 doctor 已
 
 ## 5. 相关留痕
 
-- intent：`workflow/intents/2026-09-25-cross-host-sync.md`
-- plan：`workflow/plans/2026-09-25-cross-host-sync.md`（含 B-b 方案拍板）
-- incident：`workflow/incidents/2026-09-25-wf-runtime.md`（双源纪律教训，规范 §7.x 包源环境跳过）
+- 立法出处：2026-09-25 cross-host-sync（intent/plan，含 B-b 方案拍板；父事件 = wf-runtime 双源纪律教训，规范 §7.x 包源环境跳过）——留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径

package/templates/_agents/commands/test.md

@@ -35,7 +35,7 @@ next: L1 关单结束 ；L2/L3 上 prod 时 → .agents/commands/deploy.md
 项目测试命令                                       # 自动化测试
 项目类型检查命令                                  # 前端类型检查/构建(涉及前端时跑)
 node .agents/scripts/verify-wiki-consistency.mjs   # 触及 wiki/ 时跑(exit 1 即先修台账再继续:跑 gen-wiki-board.mjs 补索引/看板;pre-commit 已按增量自动拦,此行用于改完即验)
-node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 owned 漂移 + §6.7 跨宿主薄适配正文漂移(装户环境；包源环境 §6.7 skipped)
+npx agentic-flow-kit doctor                        # §6.5 delegations + §6.6 owned 漂移 + §6.7 跨宿主薄适配正文漂移(装户环境；包源环境 §6.7 skipped)
 ```
 
 > **环境注记**：本地服务占用构建产物导致编译失败、多会话并行时「谁跑静态门 / 提交谁先停服务」等约定——如有,见项目注记 `.agents/notes/runtime-env.md` §2,跑静态门前先过一眼。
@@ -74,11 +74,12 @@ node bin/flow-kit.mjs doctor                       # §6.5 delegations + §6.6 o
 
 - 输出测试报告(通过项 / 失败项);失败项已修复并复测通过。
 - **关单**（日常闭环点，不依赖是否上 prod）:
-  - 关单前一键过门：`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**`--doc` 把测试绿凭证绑到本单**——不带它落下的绿行不给任何单背书，confirm-doc 前置与检查 8 对账只认带本单 `--doc` 的绿行（仅 v6+ 生效）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定（2026-10-07 papercut）
+  - 关单前一键过门：`node .agents/scripts/verify.mjs --doc workflow/intents/<本单>.md`（npm test + check-loop 固定编排，任一失败非零退出，非绿不关单）；**`--doc` 把测试绿凭证绑到本单**——不带它落下的绿行不给任何单背书，confirm-doc 前置与检查 8 对账只认带本单 `--doc` 的绿行（仅 v6+ 生效）；**装户仓**（根目录无 `package.json`，工程在子目录）默认 `npm test` 不可跑 → 脚本**显式跳过步骤 1 且不落测试绿凭证**（防假绿）并提示；此时按项目口径手工跑测试，或带 `--test-cmd "<项目测试命令>"` 指定
   - 新需求：逐条勾验入口 intent「验收标准」，每条补「证据：」（例如：粘贴 CI 运行结果、UI 截图路径、或具体的 commit SHA），intent → done；同名 spec/Quick-Plan（若有）仍 approved → done。**注意：勾选但缺证据会被 check-loop 拦截（hard-block）**
-  - **approved 留痕提交**（2026-09-30 起）：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
-  - **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（两形态 / 逐件+逐件原话 / done 内容绑定（关单编辑先于 done 确认、confirm-doc 是最后一次写入）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
+  - **approved 留痕提交**：done 确认前确认**本次关单文档**的 approved 态已进 git 历史（越早越好——approved 后即应提交；若尚未，先补提交再 done；门为逐份校验，三件套均关单时逐份各自满足）——confirm-doc 的 done 前置门硬校验（历史未出现「状态: approved」→ 拒绝落账）；done 后再提交 done 态与其余改动
+  - **确认落态**：唯一入口 `node .agents/scripts/confirm-doc.mjs <path>`（两形态 / 逐件代录（摘要可复用——分辨力由 scope+指纹承担）/ done 内容绑定（关单编辑先于 done 确认、confirm-doc 是最后一次写入）/ 台账对质全口径见根 `AGENTS.md` §1.3 确认门）。
   - 修复：防复发验证已落地，incident → closed（经确认门 confirm-doc：open→fixed / fixed→closed 两跳、无单跳；2026-09-28 起 check-loop 15 对账——关单编辑先于 closed 确认，口径同 done 内容绑定）
+  - **沉淀草稿**：intent done / incident closed 后跑 `node .agents/scripts/draft-sediment.mjs workflow/<intents|incidents>/<本单>.md`——自动抽高价值节（intent：影响面/触达红线；incident：影响面/根因/为什么之前没拦住/复盘三件套）落 `wiki/drafts-archive/<日期-主题>/` 草稿、回写源文件 `沉淀` 字段、重跑 gen-wiki-board（归档计数随动，否则 verify-wiki-consistency 拦提交）。全占位单拒抽（正常，无沉淀价值）。`--dry-run` 先预览。草稿是**中间态**：人工读一遍归类到 `wiki/<主题>/`（补主题与用途、保留 `来源` 字段）后跑 gen-wiki-board + verify-wiki-consistency。沉淀是人工判断——机器只代抽与登记，值不值得入库由人定；不沉淀写 `沉淀: 无` 显式豁免（check-loop 的 `[WARN 未沉淀]` 随之消除）
   - **同族收尾**：入口置终态时，同名 plan 一并置 `done`（spec 见上条），不留 `approved` 孤儿（口径同看板「入口已 done，本 plan 未终态」告警）
   - 主智能体自做的 L1+ 新需求在 `workflow/delegations.md`「自做任务结果表」记一行（修复类不重复记）
   - **委派快照回写**：关单后若 `workflow/delegations.md` §月度聚合快照缺当月行或 doctor §6.5 报陈旧 → 跑 `node .agents/scripts/agg-delegations.cjs` 并回贴当月快照行

package/templates/_agents/control-surfaces.txt

@@ -0,0 +1,53 @@
+# 控制面清单（单源：本文件——check-lane-surface.mjs 检查 C 共读，pre-commit「泳道完整性」门禁）
+# 格式：每行一条 ERE（grep -E 兼容），匹配暂存文件的仓库相对路径（/ 分隔）。
+#   # 注释与空行忽略；本文件缺失或清单为空 = 检查 C 跳过（装户无感升级，同 lane-surfaces.txt 口径）。
+#   正则语法错误行 → 门禁 fail-closed 阻断（防静默空洞）。
+#
+# 语义（与 lane-surfaces.txt 的「触达面」不同一档）：命中本清单 = **改动门禁/授权/权限系统本身**。
+#   此时必须有活跃（draft/approved / open/fixed）L2/L3 入口罩着，**否则 hard 拦**——
+#   与检查 A 的唯一区别是「无任何活跃入口」这一档：检查 A 出 advisory（docs/bootstrap 豁免的合法形态），
+#   检查 C 出 BLOCK。理由（2026-10-09 P0-A）：此前 `.agents/` 脚本与 commands 属 new-task.md §5
+#   「docs 级豁免 → 直接 commit」，而检查 A 在无活跃入口时只 advisory，两条各自合理的规则**组合起来**
+#   等于「改 check-loop.mjs 削弱某条检查 → 不需要入口文档 → 不触发同步确认门 → 提交通过」；
+#   CI 侧又跑被测分支自己的 check-loop（自指裁判）。本清单把这条通路从「advisory」抬到「必过同步确认门」。
+#   边界（诚实声明）：仍是本地信任边界内的**归因**机制——整文件删清单即可摘掉本门（该文件本身在清单内，
+#   删它同样要过门，但门是可以被 `--no-verify` / 不挂 hooksPath 绕过的）；堵的是「顺手改弱」，
+#   不宣称关闭「刻意绕过」。事后对质面 = 台账 + git 历史 + check-engine-integrity 的基线比对。
+#
+# 覆盖哪些面（为什么各条目都在控制面上）：
+#   引擎判据本体（包源 + 装副本两面都列——单边改动同样要过门）
+^templates/_agents/scripts/
+^\.agents/scripts/
+#   git 钩子面（本地唯一机器门的编排）与钩子内的门禁实现件
+^templates/_githooks/
+^\.githooks/
+^templates/_agents/hooks/
+^\.agents/hooks/
+#   CI 远端门定义（GitHub 面；owned 件，删一行等于摘一道门）
+^templates/_github/
+^\.github/
+#   权限与门禁配置本体（deny 表 / 自治信任 / 触达面与豁免清单 / 引擎基线 / 检查豁免登记）
+#   .json 件为装户安装时生成、无包源双生子；.txt 单源件包源与装副本两面都列
+^\.agents/settings\.json$
+^\.agents/trust-mode\.json$
+^\.agents/kit\.json$
+^\.agents/lane-surfaces\.txt$
+^templates/_agents/lane-surfaces\.txt$
+^\.agents/control-surfaces\.txt$
+^templates/_agents/control-surfaces\.txt$
+^\.agents/engine-lock\.json$
+^templates/_agents/engine-lock\.json$
+^\.agents/scripts-test-exempt\.txt$
+^templates/_agents/scripts-test-exempt\.txt$
+^\.agents/workflow-enums\.txt$
+^templates/_agents/workflow-enums\.txt$
+^\.agents/ledger-line-exempt\.json$
+^\.agents/rule-budgets\.txt$
+^templates/_agents/rule-budgets\.txt$
+^\.agents/metric-claims\.txt$
+^templates/_agents/metric-claims\.txt$
+#   常驻规则面（AI 行为契约本体——改 prompt 面与改判据面同档；体积预算只约束「多大」不约束「改了什么」）
+^AGENTS\.md$
+^templates/AGENTS\.md$
+#   可装门禁模块（红线守卫的判据）
+^modules/gates/