agentic-flow-kit 1.8.0 → 1.8.2

package/templates/_agents/scripts/closeout-l1.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// closeout-l1 — L1 关单一把编排（2026-10-15 减重手段④ 自源仓回灌：记录性动作一把生成，判断留给人）
+// 把 test.md §6 的 L1 关单链（预检 → confirm-doc 代录 → INDEX 重生成 → 提交清单）收进一条命令。
+// 用法：node .agents/scripts/closeout-l1.mjs <workflow/plans/xxx.md>              # 预检模式：只查差距，不落任何状态
+//       node .agents/scripts/closeout-l1.mjs <plan> --delegated "<用户对话原话>"   # 执行模式：预检过 → confirm-doc 代录 → 重生成 INDEX
+//       （可加 --root <仓库根>；缺省 git toplevel，无 git 用 cwd）
+// 边界（判据单源，本工具不复制强判断）：
+//   - 证据格式 / approved 历史 / 测试绿硬门 = confirm-doc（stage-gates/policy 单源），本工具预检只是
+//     提前暴露差距的 advisory 快筛；执行模式原样转发 confirm-doc，其拒绝即本命令拒绝。
+//   - --delegated 调用纪律：AI 须先取得用户对话内明确放行（AGENTS.md 确认门条款），原话入账供对质。
+//   - L2/L3 不受理（spec 收敛对账 + 独立复核是防御道本体，不做捷径）；incidents 不受理（两跳制）。
+// kit 适配（源仓→kit 逐条）：① 源仓引用 test.md §5/§5.5，kit 关单链在 test.md §6；② verify 预检
+//   镜像 kit done 前置口径（policy v6+ 按 verifyDocSince 绑定本单绿行，不带 --doc 的绿行不给背书）；
+//   ③ 分片路径修复：源仓 main() 拼 `<基名.md>.jsonl`，而 confirm-doc/ledger-loader 写入口径是
+//   `<基名>.jsonl`（basename 去 .md）——源仓提交清单会把分片误报成主台账（其测试只盖纯函数未暴露），
+//   kit 抽 shardOf 纯函数修正并补断言。
+// 测试：node .agents/scripts/closeout-l1.test.mjs（parseArgs / fmOf / acceptanceOf / preflight / shardOf 纯函数进程内断言）
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { hasFreshVerifyLine, loadKitPolicy } from './policy.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+// parseArgs(argv)：{ plan, delegated, root } | { error }
+export function parseArgs(argv = []) {
+  const out = { plan: null, delegated: null, root: null, error: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--delegated') {
+      out.delegated = argv[++i];
+      if (!out.delegated) out.error = '--delegated 须带「<用户对话原话>」参数';
+    } else if (a.startsWith('--delegated=')) {
+      out.delegated = a.slice('--delegated='.length);
+    } else if (a === '--root') {
+      out.root = argv[++i];
+      if (!out.root) out.error = '--root 须带仓库根路径';
+    } else if (!a.startsWith('--')) {
+      if (out.plan) out.error = `只受理一份 plan（现已有 ${out.plan}）`;
+      else out.plan = a;
+    } else {
+      out.error = `未知参数 ${a}`;
+    }
+  }
+  if (!out.error && !out.plan) out.error = '用法：node .agents/scripts/closeout-l1.mjs <workflow/plans/xxx.md> [--delegated "<用户对话原话>"] [--root <仓库根>]';
+  return out;
+}
+
+// frontmatter 平铺解析（key: value；本工具只消费 状态/级别 两个键）
+export function fmOf(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  if (!/^---\s*$/.test(lines[0] || '')) return {};
+  const fm = {};
+  for (let i = 1; i < lines.length; i++) {
+    if (/^---\s*$/.test(lines[i])) break;
+    const m = /^([^\s:]+):\s*(.*)$/.exec(lines[i]);
+    if (m) fm[m[1]] = m[2].trim();
+  }
+  return fm;
+}
+
+// acceptanceOf(text)：定位「## …验收标准…」节，统计勾选框条目。
+// 返回 { found, total, unchecked: [条目文本] }；节内无任何勾选框条目 → found=true, total=0（判为异常）。
+export function acceptanceOf(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  let start = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i]) && lines[i].includes('验收标准')) { start = i; break; }
+    if (i > 0 && /^##\s/.test(lines[i]) && start >= 0) break; // 上一节结束仍无（不可达，防御）
+  }
+  if (start < 0) return { found: false, total: 0, unchecked: [] };
+  const unchecked = [];
+  let total = 0;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s/.test(lines[i])) break; // 节结束
+    const m = /^\s*-\s*\[([ xX])\]\s*(.*)$/.exec(lines[i]);
+    if (!m) continue;
+    total++;
+    if (m[1] === ' ') unchecked.push(m[2].trim());
+  }
+  return { found: true, total, unchecked };
+}
+
+// preflight({ rel, text, freshVerify })：L1 关单前置快筛（advisory；强门在 confirm-doc）。
+// 返回 { ok, problems: [], level, status, total, checked }。
+export function preflight({ rel, text, freshVerify }) {
+  const problems = [];
+  if (!/^workflow\/plans\/[^/]+\.md$/.test(rel) || rel.includes('_TEMPLATE')) {
+    problems.push(`路径须为 workflow/plans/ 直下文档（现「${rel}」）——L2/L3 intent/spec 与 incidents 不在本工具受理面`);
+  }
+  const fm = fmOf(text);
+  const level = fm['级别'] || '';
+  const status = fm['状态'] || '';
+  if (level !== 'L1') {
+    problems.push(`级别「${level || '缺失'}」≠ L1——L2/L3 关单走 .agents/commands/test.md 全流程（验收判据对账 + 独立复核），本工具只服务协作道 L1`);
+  }
+  if (status === 'done' || status === 'superseded' || status === 'cancelled') {
+    problems.push(`状态已为终态「${status}」——本 plan 已收口，无需重复关单`);
+  } else if (status !== 'approved') {
+    problems.push(`状态「${status || '缺失'}」≠ approved——draft 须先过起草确认（confirm-doc approved），关单只受理 approved → done`);
+  }
+  const acc = acceptanceOf(text);
+  if (!acc.found) {
+    problems.push('未找到「## 验收标准」节——L1 plan 须有可勾验的验收标准（模板口径）');
+  } else if (acc.total === 0) {
+    problems.push('「验收标准」节内无勾选框条目（- [ ] / - [x]）——验收标准须逐条可勾验');
+  } else if (acc.unchecked.length) {
+    problems.push(`验收标准 ${acc.unchecked.length}/${acc.total} 条未勾验（勾验与补证据是判断动作，留在关单前完成）：`);
+    for (const u of acc.unchecked) problems.push(`    - [ ] ${u}`);
+  }
+  if (!freshVerify) {
+    problems.push('24h 内无本单绑定的 verify 绿行（.agents/verifications.jsonl）——先跑 node .agents/scripts/verify.mjs --doc <本单路径>（全绿自动落绿凭证与 verify-evidence 摘要；v6+ 只认带本单 --doc 的绿行）');
+  }
+  return { ok: problems.length === 0, problems, level, status, total: acc.total, checked: acc.total - acc.unchecked.length };
+}
+
+// shardOf(rel)：该 plan 的确认台账分片路径（posix，仓库根相对）。写入口径单源 = ledger-loader
+// writeConfirmation（basename 去 .md）——源仓首版此处拼了 `<基名.md>.jsonl`，提交清单会漏列分片。
+export function shardOf(rel) {
+  return path.join('.agents', 'confirmations.d', `${path.basename(rel, '.md')}.jsonl`);
+}
+
+function gitRoot() {
+  const r = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  return r.status === 0 && r.stdout.trim() ? r.stdout.trim() : process.cwd();
+}
+
+// freshVerifyOf(root, rel)：镜像 kit confirm-doc done 前置的绿行口径（判定单源 policy.hasFreshVerifyLine）：
+// policy v5+（verifySince）才有 24h 绿行门；v6+（verifyDocSince）按本 doc 精确绑定。预检与强门同口径，
+// 差距快筛才不失真。只读，台账缺失/不可读一律 false（advisory 层 fail-open，同 confirm-doc）。
+function freshVerifyOf(root, rel) {
+  try {
+    const p = path.join(root, '.agents', 'verifications.jsonl');
+    if (!fs.existsSync(p)) return false;
+    const pol = loadKitPolicy(root);
+    if (typeof pol.verifySince !== 'string') return true; // v1-v4 无绿行门 → 预检不产差距
+    const bound = typeof pol.verifyDocSince === 'string' ? rel : null;
+    return hasFreshVerifyLine(fs.readFileSync(p, 'utf8').split(/\r?\n/), Date.now(), bound);
+  } catch {
+    return false;
+  }
+}
+
+function findArchived(root, rel) {
+  const base = path.basename(rel);
+  for (const monthDir of fs.existsSync(path.join(root, 'workflow', 'archive'))
+    ? fs.readdirSync(path.join(root, 'workflow', 'archive')) : []) {
+    const cand = path.join('workflow', 'archive', monthDir, 'plans', base);
+    if (fs.existsSync(path.join(root, cand))) return cand;
+  }
+  return null;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.error) {
+    console.error(`closeout-l1: ${args.error}`);
+    process.exit(2);
+  }
+  const root = path.resolve(args.root || gitRoot());
+  const rel = path.relative(root, path.resolve(args.plan)).replace(/\\/g, '/');
+  const abs = path.join(root, rel);
+  if (!fs.existsSync(abs)) {
+    console.error(`closeout-l1: 文件不存在 ${rel}（相对仓库根 ${root}）`);
+    process.exit(2);
+  }
+  const text = fs.readFileSync(abs, 'utf8');
+  const pf = preflight({ rel, text, freshVerify: freshVerifyOf(root, rel) });
+
+  console.log(`L1 关单预检｜${rel}`);
+  console.log(`  级别 ${pf.level || '—'}｜状态 ${pf.status || '—'}｜验收 ${pf.checked}/${pf.total || 0} 勾验｜verify 绿行 ${pf.problems.some((p) => p.includes('verify')) ? '✗' : '✓(24h)'}`);
+  if (!pf.ok) {
+    console.error(`\n预检未过（${pf.problems.length} 项差距，逐条处理后再来）：`);
+    for (const p of pf.problems) console.error(`  ✗ ${p}`);
+    process.exit(2);
+  }
+  console.log('  预检通过。');
+
+  if (!args.delegated) {
+    console.log('\n下一步（执行关单，须先取得用户对话内明确放行）：');
+    console.log(`  node .agents/scripts/closeout-l1.mjs ${rel} --delegated "<用户确认原话>"`);
+    return;
+  }
+
+  // 执行模式：confirm-doc 原样转发（全部强门在彼处），随后重生成 INDEX。
+  const cd = spawnSync(process.execPath, [
+    path.join(SCRIPT_DIR, 'confirm-doc.mjs'), rel, '--delegated', args.delegated, '--root', root,
+  ], { stdio: 'inherit' });
+  if (cd.status !== 0) {
+    console.error(`closeout-l1: confirm-doc 拒绝（exit ${cd.status}）——按上方提示修复后重试；本命令不做任何绕过。`);
+    process.exit(cd.status === null ? 2 : cd.status);
+  }
+  const gi = spawnSync(process.execPath, [path.join(SCRIPT_DIR, 'gen-workflow-index.mjs')], { cwd: root, encoding: 'utf8' });
+  if (gi.status !== 0) {
+    console.error('closeout-l1: ⚠️ INDEX 重生成失败（确认已落账不可回滚；提交前须手动跑 node .agents/scripts/gen-workflow-index.mjs 修齐，否则索引漂移门会拦提交）');
+  }
+
+  // 汇总：关单后的落盘面与提交清单（归档 mv 时给出新路径）。
+  const base = path.basename(rel);
+  const archivedTo = fs.existsSync(abs) ? null : findArchived(root, rel);
+  const shard = shardOf(rel);
+  const adds = [
+    archivedTo || rel,
+    fs.existsSync(path.join(root, shard)) ? shard : '.agents/confirmations.jsonl',
+    'workflow/INDEX.md',
+  ];
+  console.log(`\n关单完成：approved → done（台账已记 chat-delegated，原话入账供对质）`);
+  if (archivedTo) console.log(`📦 已随确认滚动归档：${rel} → ${archivedTo}（家族原子，git mv 已暂存）`);
+  console.log(`提交清单（git add）：
+  ${adds.join('\n  ')}`);
+  console.log(`建议提交说明：docs(workflow): 关单 ${base.replace(/\.md$/, '')}（L1 done）——用户对话内确认代录${archivedTo ? `，归档至 ${path.dirname(archivedTo)}/` : ''}`);
+  console.log('提醒：本会话自做任务另记 workflow/delegations.md 并跑 agg-delegations.mjs（test.md §6）；verify-evidence.md 有改动时随同提交。');
+}
+
+const isMain = process.argv[1] && process.argv[1].endsWith('closeout-l1.mjs');
+if (isMain) main();

package/templates/_agents/scripts/closeout-l1.test.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+// closeout-l1.test.mjs — L1 关单编排纯函数套件（2026-10-15 减重手段④ 自源仓回灌随附）
+// parseArgs / fmOf / acceptanceOf / preflight / shardOf 进程内断言：快筛差距逐项暴露、
+// L2/L3 与终态件不受理、勾验缺一即拦、verify 凭证缺失即拦、分片路径与写入口径同形。
+// 运行：node templates/_agents/scripts/closeout-l1.test.mjs
+import { parseArgs, fmOf, acceptanceOf, preflight, shardOf } from './closeout-l1.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 : ''}`); }
+};
+
+const PLAN_OK = `---
+状态: approved
+级别: L1
+模块: purchase
+---
+# PLAN — demo
+
+## 改动方案
+
+- 改 A
+
+## 验收标准（可测试）
+
+- [x] 判据一（证据：UI 实测 A1 PASS）
+- [x] 判据二（证据：UT 用例名 demo_case）
+`;
+
+// ---- A1 parseArgs ----
+{
+  const a = parseArgs(['workflow/plans/x.md', '--delegated', '可以关单', '--root', 'E:/r']);
+  check('A1 三参齐解析', a.plan === 'workflow/plans/x.md' && a.delegated === '可以关单' && a.root === 'E:/r' && !a.error, JSON.stringify(a));
+  check('A1 缺 plan → error', !!parseArgs(['--delegated', 'q']).error);
+  check('A1 --delegated 缺值 → error', !!parseArgs(['workflow/plans/x.md', '--delegated']).error);
+  check('A1 未知参数 → error', !!parseArgs(['workflow/plans/x.md', '--wow']).error);
+  check('A1 两份 plan → error', !!parseArgs(['a.md', 'b.md']).error);
+  check('A1 --delegated= 等号形态', parseArgs(['x.md', '--delegated=原话']).delegated === '原话');
+}
+
+// ---- A2 fmOf / acceptanceOf ----
+{
+  const fm = fmOf(PLAN_OK);
+  check('A2 frontmatter 状态/级别', fm['状态'] === 'approved' && fm['级别'] === 'L1' && fm['模块'] === 'purchase', JSON.stringify(fm));
+  const acc = acceptanceOf(PLAN_OK);
+  check('A2 验收节 2 条全勾', acc.found === true && acc.total === 2 && acc.unchecked.length === 0, JSON.stringify(acc));
+  check('A2 无验收节 → found=false', acceptanceOf('# 无节文档\n\n- [ ] 孤儿勾选不算').found === false);
+  const mixed = acceptanceOf('## 验收标准\n\n- [x] 甲\n- [ ] 乙待办\n- [X] 丙大写勾\n\n## 下一节\n\n- [ ] 节外不算\n');
+  check('A2 未勾只数节内（乙），大写 X 认勾、节外不计', mixed.total === 3 && mixed.unchecked.length === 1 && mixed.unchecked[0] === '乙待办', JSON.stringify(mixed));
+  check('A2 节在无勾选框条目 → total=0', acceptanceOf('## 验收标准\n\n纯文字段\n').total === 0);
+}
+
+// ---- A3 preflight 快乐路径 ----
+{
+  const pf = preflight({ rel: 'workflow/plans/2026-10-15-demo.md', text: PLAN_OK, freshVerify: true });
+  check('A3 L1+approved+全勾+有凭证 → ok', pf.ok === true && pf.problems.length === 0 && pf.checked === 2, JSON.stringify(pf));
+}
+
+// ---- A4 级别/状态不受理 ----
+{
+  const l2 = preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK.replace('级别: L1', '级别: L2'), freshVerify: true });
+  check('A4 L2 → 拒并指回 test.md', !l2.ok && l2.problems.some((p) => p.includes('L2/L3') && p.includes('test.md')), JSON.stringify(l2.problems));
+  const draft = preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK.replace('状态: approved', '状态: draft'), freshVerify: true });
+  check('A4 draft → 拒（须先过起草确认）', !draft.ok && draft.problems.some((p) => p.includes('draft')), JSON.stringify(draft.problems));
+  const done = preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK.replace('状态: approved', '状态: done'), freshVerify: true });
+  check('A4 done → 拒（已收口）', !done.ok && done.problems.some((p) => p.includes('终态')), JSON.stringify(done.problems));
+  check('A4 级别缺失也拒（fail-closed）', !preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK.replace('级别: L1\n', ''), freshVerify: true }).ok);
+}
+
+// ---- A5 路径受理面 ----
+{
+  check('A5 intents 路径不受理', !preflight({ rel: 'workflow/intents/x.md', text: PLAN_OK, freshVerify: true }).ok);
+  check('A5 incidents 路径不受理', !preflight({ rel: 'workflow/incidents/x.md', text: PLAN_OK, freshVerify: true }).ok);
+  check('A5 模板不受理', !preflight({ rel: 'workflow/plans/_TEMPLATE.md', text: PLAN_OK, freshVerify: true }).ok);
+  check('A5 子目录路径不受理', !preflight({ rel: 'workflow/plans/sub/x.md', text: PLAN_OK, freshVerify: true }).ok);
+}
+
+// ---- A6 勾验与凭证差距 ----
+{
+  const unchecked = preflight({
+    rel: 'workflow/plans/x.md',
+    text: PLAN_OK.replace('- [x] 判据二（证据：UT 用例名 demo_case）', '- [ ] 判据二'),
+    freshVerify: true,
+  });
+  check('A6 未勾验逐条列出（计数行 + 条目行分项）', !unchecked.ok
+    && unchecked.problems.some((p) => p.includes('1/2 条未勾验'))
+    && unchecked.problems.some((p) => p.includes('判据二')), JSON.stringify(unchecked.problems));
+  const noVerify = preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK, freshVerify: false });
+  check('A6 verify 凭证缺失 → 拦并指 verify.mjs --doc', !noVerify.ok && noVerify.problems.some((p) => p.includes('verify.mjs') && p.includes('--doc')), JSON.stringify(noVerify.problems));
+  const noAcc = preflight({ rel: 'workflow/plans/x.md', text: PLAN_OK.split('## 验收标准')[0], freshVerify: true });
+  check('A6 无验收节 → 拦', !noAcc.ok && noAcc.problems.some((p) => p.includes('验收标准')));
+}
+
+// ---- A7 shardOf：与 ledger-loader writeConfirmation 写入口径同形（<基名去.md>.jsonl）----
+// 源仓首版 main() 拼 `<基名.md>.jsonl` 与写入口径错位——提交清单会把分片误报成主台账。本断言钉死修正。
+{
+  const s = shardOf('workflow/plans/2026-10-15-demo.md');
+  check('A7 分片路径 = confirmations.d/<基名>.jsonl（去 .md）', s.replace(/\\/g, '/') === '.agents/confirmations.d/2026-10-15-demo.jsonl', s);
+  check('A7 分片路径不含 .md.jsonl 双后缀', !s.replace(/\\/g, '/').includes('.md.jsonl'), s);
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/commit-check-trigger.test.mjs

@@ -149,6 +149,55 @@ for (const [label, writePkg] of unsatisfied) {
     r.status === 0 && !ran(f.marks, 'build') && r.out.includes('pkg:scripts.build') && !r.out.includes('无匹配的源码变更'), r.out);
 }
 
+// 场景 10：--no-build 跳过全部构建（2026-10-16 构建门后移 pre-push）——ext 命中也不跑
+f = mkfix();
+stage(f.root, 'src/a.xyz', 'x');
+r = runHook(f.root, ['--no-build']);
+check('S10 --no-build 命中 ext 也不构建（后移 pre-push）',
+  r.status === 0 && !ran(f.marks, 'extbuild') && r.out.includes('--no-build'), r.out);
+
+// 场景 11：--range 推送范围模式——范围内 .xyz 触发 extbuild；敏感扫描跳过有提示
+f = mkfix();
+fs.writeFileSync(path.join(f.root, 'old.txt'), 'old\n');
+git(f.root, ['add', 'old.txt']);
+git(f.root, ['commit', '-q', '-m', 'old']);
+stage(f.root, 'src/ranged.xyz', 'x');
+const shaOld = git(f.root, ['rev-parse', 'HEAD']).stdout.trim();
+git(f.root, ['commit', '-q', '-m', 'ranged']);
+const shaNew = git(f.root, ['rev-parse', 'HEAD']).stdout.trim();
+r = runHook(f.root, ['--range', shaOld, shaNew]);
+check('S11 --range 范围内 .xyz 触发 extbuild 且提示跳过敏感扫描',
+  r.status === 0 && ran(f.marks, 'extbuild') && r.out.includes('SKIP: --range 模式跳过敏感扫描'), r.out);
+
+// 场景 11b：--range 范围只含非触发文件 → 零构建
+f = mkfix();
+fs.writeFileSync(path.join(f.root, 'a.txt'), 'a\n');
+git(f.root, ['add', 'a.txt']);
+git(f.root, ['commit', '-q', '-m', 'a']);
+const s1 = git(f.root, ['rev-parse', 'HEAD']).stdout.trim();
+fs.writeFileSync(path.join(f.root, 'b.txt'), 'b\n');
+git(f.root, ['add', 'b.txt']);
+git(f.root, ['commit', '-q', '-m', 'b']);
+const s2 = git(f.root, ['rev-parse', 'HEAD']).stdout.trim();
+r = runHook(f.root, ['--range', s1, s2]);
+check('S11b --range 范围无触发文件 → 零构建',
+  r.status === 0 && !ran(f.marks, 'extbuild') && !ran(f.marks, 'prefixbuild'), r.out);
+
+// 场景 12：--range 全零 old sha（新分支首推）→ 全量构建语义（等价 --full 构建面）
+f = mkfix();
+fs.writeFileSync(path.join(f.root, 'seed.txt'), 'seed\n');
+git(f.root, ['add', 'seed.txt']);
+git(f.root, ['commit', '-q', '-m', 'seed']);
+const shaHead = git(f.root, ['rev-parse', 'HEAD']).stdout.trim();
+r = runHook(f.root, ['--range', '0'.repeat(40), shaHead]);
+check('S12 --range 全零 old = 全量构建语义',
+  r.status === 0 && ran(f.marks, 'extbuild') && ran(f.marks, 'prefixbuild'), r.out);
+
+// 场景 13：--range sha 非法 → BLOCK（信任边界：sha 来自 git 管道仍校验）
+f = mkfix();
+r = runHook(f.root, ['--range', 'not-a-sha', 'HEAD']);
+check('S13 --range 非 sha 参数 → BLOCK exit 1', r.status === 1 && r.out.includes('BLOCK'), r.out);
+
 for (const d of fs.readdirSync(os.tmpdir()).filter((x) => x.startsWith('cc-trigger-test-'))) {
   fs.rmSync(path.join(os.tmpdir(), d), { recursive: true, force: true });
 }

package/templates/_agents/scripts/confirm-doc.mjs

@@ -541,9 +541,21 @@ if (isMain) {
   // 内容绑定约束，与既有归档批次同口径）。失败一律 fail-open：归档是卫生动作，不得回滚已完成的
   // 确认（**归档失败不阻断关单**——与源仓语义逐字一致）。启用锚（照搬源仓，无 policy 锚）：
   // ① 仓库已建立归档约定（workflow/archive/ 存在）——真实装户仓有，临时 fixture 无，避免测试夹具
-  //   被静默搬走（也避免在未采纳归档的仓库里凭空造目录）；② env 逃生门 CONFIRM_DOC_NO_ARCHIVE。
+  //   被静默搬走（也避免在未采纳归档的仓库里凭空造目录）；② env 逃生门 CONFIRM_DOC_NO_ARCHIVE；
+  //   ③ 特性分支默认不归档（2026-10-16 自源仓 13f67ef7 回灌）：分支上先关单再合并时，diff 只剩
+  //   archive/ 路径，泳道/配对增量门只认 workflow 活跃直路径，合法合并被拦。main/master/develop 与
+  //   游离 HEAD 维持关单即归档。CONFIRM_DOC_NO_ARCHIVE=1 仍强制关；CONFIRM_DOC_ARCHIVE=1 可在特性分支强制归档。
   const archiveRoot = path.join(root, 'workflow', 'archive');
-  if (confirmed > 0 && !process.env.CONFIRM_DOC_NO_ARCHIVE && fs.existsSync(archiveRoot)) {
+  let featureHold = false;
+  if (confirmed > 0 && !process.env.CONFIRM_DOC_NO_ARCHIVE && process.env.CONFIRM_DOC_ARCHIVE !== '1') {
+    let branch = '';
+    try { branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, encoding: 'utf8' }).trim(); } catch { branch = ''; }
+    featureHold = !!branch && branch !== 'HEAD' && !['main', 'master', 'develop'].includes(branch);
+    if (featureHold && fs.existsSync(archiveRoot)) {
+      console.log(`📦 特性分支 ${branch} 不归档（合并前保持 workflow 活跃路径；main/develop 关单才归档）。CONFIRM_DOC_ARCHIVE=1 可强制`);
+    }
+  }
+  if (confirmed > 0 && !process.env.CONFIRM_DOC_NO_ARCHIVE && !featureHold && fs.existsSync(archiveRoot)) {
     try {
       const { analyze, buildDocList, loadLastTouch, parseStatus, TERMINAL, ACTIVE } = await import('./archive-sweep.mjs');
       // 台账终态锚：kit 读侧单源 = readLedgerRows（主台账+分片透明合并；源仓走

package/templates/_agents/scripts/confirm-doc.test.mjs

@@ -1056,5 +1056,48 @@ const writeTrust = (root, cfg) => {
   fs.rmSync(root2, { recursive: true, force: true });
 }
 
+// ---- S45c/S45d 特性分支默认不归档（2026-10-16 自源仓 13f67ef7 回灌）----
+// 分支上先关单再合并时 diff 只剩 archive/ 路径，泳道/配对增量门只认 workflow 活跃直路径；
+// main/master/develop 与游离 HEAD 维持关单即归档。CONFIRM_DOC_ARCHIVE=1 可在特性分支强制归档。
+{
+  const mkRepoBranch = (branchName) => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-branch-'));
+    const git = (...a) => spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', a, { cwd: root, encoding: 'utf8' });
+    git('init', '-q');
+    git('config', 'user.email', 't@t');
+    git('config', 'user.name', 't');
+    git('checkout', '-q', '-b', branchName);
+    const ip = path.join(root, 'workflow', 'intents');
+    fs.mkdirSync(ip, { recursive: true });
+    fs.mkdirSync(path.join(root, 'workflow', 'archive'), { recursive: true });
+    const fp = branchName === 'main' ? 'eeee5555eeee5555' : 'ffff6666ffff6666';
+    fs.writeFileSync(path.join(ip, '2026-09-01-branch.md'), `---\n状态: approved\n级别: L1\n确认指纹: ${fp}\n---\n# I\n\n## 验收标准（可测试）\n- [x] 通过（证据:测试全绿）\n`, 'utf8');
+    git('add', '-A');
+    spawnSync(process.platform === 'win32' ? 'git.exe' : 'git', ['commit', '-q', '-m', 'c1'], { cwd: root, env: { ...process.env, GIT_AUTHOR_DATE: '2026-09-01T10:00:00+08:00', GIT_COMMITTER_DATE: '2026-09-01T10:00:00+08:00' } });
+    return { root, ip };
+  };
+  // S45c：特性分支关单 → 不归档（保持 workflow 活跃直路径），但状态照常 done
+  {
+    const { root, ip } = mkRepoBranch('feature/x');
+    const r = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-09-01-branch.md', '--delegated', '可以'],
+      { cwd: root, encoding: 'utf8', env: { ...process.env, CONFIRM_DOC_TEST_NOW: '2026-10-13' } });
+    check('S45c 特性分支关单默认不归档（状态置 done、文档留活跃路径）',
+      r.status === 0 && /状态: done/.test(fs.readFileSync(path.join(ip, '2026-09-01-branch.md'), 'utf8'))
+        && !fs.existsSync(path.join(root, 'workflow', 'archive', 'intents')) && /不归档/.test(r.stdout),
+      JSON.stringify({ status: r.status, stdout: String(r.stdout).slice(-260) }));
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  // S45d：特性分支 + CONFIRM_DOC_ARCHIVE=1 → 强制归档
+  {
+    const { root } = mkRepoBranch('feature/y');
+    const r = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-09-01-branch.md', '--delegated', '可以'],
+      { cwd: root, encoding: 'utf8', env: { ...process.env, CONFIRM_DOC_TEST_NOW: '2026-10-13', CONFIRM_DOC_ARCHIVE: '1' } });
+    check('S45d 特性分支 CONFIRM_DOC_ARCHIVE=1 强制归档',
+      r.status === 0 && /📦 归档/.test(r.stdout),
+      JSON.stringify({ status: r.status, stdout: String(r.stdout).slice(-260) }));
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
 process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/gen-workflow-metrics.mjs

@@ -14,6 +14,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadEnums } from './workflow-enums.mjs';
 import { readLedgerRows as loadLedgerRows } from './ledger-loader.mjs';
+import { analyze, buildDocList, loadLastTouch, loadLedgerTs, parseStatus, ACTIVE } from './archive-sweep.mjs';
 
 const USAGE = `用法：node .agents/scripts/gen-workflow-metrics.mjs [--month YYYY-MM] [--dry-run] [--help]
 
@@ -217,6 +218,22 @@ console.log(`  常驻面合计：${kb(surf.total)}`);
 console.log(`  闭环漏斗：收口 ${funnel.closed}（完整链 ${funnel.full} = 一次通过 ${funnel.once} + 返工 ${funnel.rework}；协议前 ${funnel.legacy}）｜中位周期 ${medianDays === null ? '—' : `${medianDays.toFixed(1)} 天`}｜台账行 ${funnel.ledgerRows}`);
 for (const it of funnel.items) console.log(`    ${String(it.doc).padEnd(58)} ${it.kind.padEnd(7)} ${it.days} 天`);
 if (funnel.items.length) console.log('  ℹ️ 机器口径可与 workflow/delegations.md 自做表的人工自报交叉对照（差异即信号，不对账）');
+// 归档积压提醒（2026-10-15 减重手段⑥ 自源仓回灌，回路别等人喊）：滚动归档已随确认门自动跑
+// （confirm-doc archive-on-close），历史积压走 archive-sweep 手工批次——月度 stdout 报候选数使积压可见。
+// 判定单源 = archive-sweep.analyze（21 天窗，禁第二套口径）；analyze/loadLastTouch 抛错（如
+// 浅克隆无 git 历史）fail-open 静默——观测提醒不挡快照。
+try {
+  const allDocs = buildDocList(process.cwd());
+  const arch = analyze({
+    docs: allDocs,
+    ledgerTs: loadLedgerTs(process.cwd()),
+    lastTouch: loadLastTouch(process.cwd()),
+    activeTexts: allDocs.filter((d) => ACTIVE.has(parseStatus(d.text))).map((d) => d.text),
+    windowDays: 21,
+  });
+  const fams = new Set(arch.candidates.map((x) => x.file));
+  console.log(`  归档积压：候选 ${arch.candidates.length} 篇 / ${fams.size} 族（21 天窗）${arch.candidates.length ? '——node .agents/scripts/archive-sweep.mjs 查看，--execute 执行' : ''}`);
+} catch { /* fail-open */ }
 console.log(`  ${DRY ? '（--dry-run，未写盘）' : ''}`);
 
 if (DRY) { console.log(`\n将写入行：\n${row}\n${funnelRow}`); process.exit(0); }

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

@@ -226,8 +226,30 @@ export function renderShard(name, rows, eol = '\n') {
   return out.length ? `${out.join(eol)}${eol}` : '';
 }
 
+// insertIntoSection(text, section, lines)：把行插进已有分片的对应 ## 节（下一节标题之前）。
+// 节不存在则整节追加到文末。无 section 的行不走这里（保持追加到文末 = 末表）。
+function insertIntoSection(text, section, lines) {
+  const eol = text.includes('\r\n') ? '\r\n' : '\n';
+  const parts = text.split(/\r?\n/);
+  if (parts.length && parts[parts.length - 1] === '') parts.pop();
+  const start = parts.findIndex((l) => l.startsWith('## ') && l.includes(section));
+  if (start < 0) {
+    return `${parts.join(eol)}${eol}${eol}## ${section}${eol}${eol}${lines.join(eol)}${eol}`;
+  }
+  let end = parts.length;
+  for (let i = start + 1; i < parts.length; i++) {
+    if (parts[i].startsWith('## ')) { end = i; break; }
+  }
+  let at = end;
+  while (at > start && parts[at - 1].trim() === '') at--;
+  parts.splice(at, 0, ...lines);
+  return `${parts.join(eol)}${eol}`;
+}
+
 // appendRows(root, name, rows, { month, section })：把数据行追加进指定月分片（缺省取行内日期月）。
 // rows 可为字符串数组或 { line, section } 数组（多表台账须带 section 才能归对表）。
+// 分片已存在时：带 section 的行插入该节（不落到文末自做表）；不带 section 的行仍追加到文末
+// （2026-10-16 自源仓 13f67ef7 回灌——修「合并丢共有行」时新增行误落末表）。
 // 返回实际写入的分片路径列表。写失败 fail-loud（不静默吞）。
 export function appendRows(root, name, rows, { month, section = '' } = {}) {
   const written = [];
@@ -247,9 +269,21 @@ export function appendRows(root, name, rows, { month, section = '' } = {}) {
     const existingRows = new Set(existing.split(/\r?\n/).filter((l) => l.trim()));
     const fresh = rs.filter((r) => !existingRows.has(r.line));
     if (!fresh.length) { written.push(p); continue; } // 已在分片 → 幂等跳过
-    const next = existing
-      ? `${existing.replace(/\s*$/, '')}\n${fresh.map((r) => r.line).join('\n')}\n`
-      : renderShard(name, fresh, '\n');
+    let next;
+    if (!existing) next = renderShard(name, fresh, '\n');
+    else {
+      const placed = fresh.filter((r) => r.section);
+      const tail = fresh.filter((r) => !r.section);
+      let text = existing;
+      const bySec = new Map();
+      for (const r of placed) {
+        if (!bySec.has(r.section)) bySec.set(r.section, []);
+        bySec.get(r.section).push(r.line);
+      }
+      for (const [sec, lines] of bySec) text = insertIntoSection(text, sec, lines);
+      if (tail.length) text = `${text.replace(/\s*$/, '')}\n${tail.map((r) => r.line).join('\n')}\n`;
+      next = text.endsWith('\n') ? text : `${text}\n`;
+    }
     fs.writeFileSync(p, next, 'utf8');
     written.push(p);
   }
@@ -296,11 +330,14 @@ function main() {
     if (!row) { console.error('--append 须带 --row "<数据行>"'); process.exit(2); }
     const mIdx = argv.indexOf('--month');
     const month = mIdx >= 0 ? argv[mIdx + 1] : undefined;
-    const written = appendRows(root, name, [row], { month });
+    const sIdx = argv.indexOf('--section');
+    const section = sIdx >= 0 ? argv[sIdx + 1] : '';
+    if (sIdx >= 0 && !section) { console.error('--section 须带节标题（如 委派结果）'); process.exit(2); }
+    const written = appendRows(root, name, [row], { month, section });
     console.log(`✓ 追加 1 行 → ${written.map((p) => path.relative(root, p).split(path.sep).join('/')).join(', ')}`);
     return;
   }
-  console.error('用法：node .agents/scripts/ledger-shards.mjs --check | --split <ledger> [--dry-run] | --append <ledger> --row "<行>" [--month YYYY-MM]');
+  console.error('用法：node .agents/scripts/ledger-shards.mjs --check | --split <ledger> [--dry-run] | --append <ledger> --row "<行>" [--month YYYY-MM] [--section <节标题>]');
   process.exit(2);
 }
 

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

@@ -247,6 +247,23 @@ const wf = (root, ...p) => path.join(root, 'workflow', ...p);
   fs.rmSync(root, { recursive: true, force: true });
 }
 
+// ---- S20 appendRows --section（2026-10-16 自源仓 13f67ef7 回灌）：已有双表时委派行插入委派节，
+//      不带 section 仍落文末（修「合并丢共有行」时新增行误落末表）----
+{
+  const root = mkroot();
+  appendRows(root, 'delegations', ['| 2026-10-15 | model | 委派甲 | 一次通过 | 备注 | |'], { section: '委派结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | 自做甲 | 一次通过 | 备注 | |'], { section: '自做任务结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | model | 委派乙 | 一次通过 | 备注 | |'], { section: '委派结果' });
+  appendRows(root, 'delegations', ['| 2026-10-15 | 自做乙 | 一次通过 | 备注 | |']);
+  const shard = fs.readFileSync(shardPathFor(root, 'delegations', '2026-10'), 'utf8');
+  const iSelf = shard.indexOf('## 自做任务结果');
+  const iDelegRow = shard.indexOf('委派乙');
+  const iSelfRow = shard.indexOf('自做乙');
+  check('S20 后追加的委派行仍在自做节之前', iDelegRow >= 0 && iDelegRow < iSelf, shard);
+  check('S20b 不带 section 的行落在文末', iSelf >= 0 && iSelf < iSelfRow, shard);
+  fs.rmSync(root, { recursive: true, force: true });
+}
+
 // ---- S18 appendRows 幂等：同行走两次只落一次 ----
 {
   const root = mkroot();