agentic-flow-kit 1.8.1 → 1.8.7

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

@@ -406,12 +406,19 @@ if (isMain) {
         refused++;
         continue;
       }
-      // 待澄清项门（2026-10-12 needs-clarification）：起草期挂「待澄清」标记**不阻断**（零阻塞），
-      // 但 draft→approved 确认时若仍挂着未澄清项则拒绝——确认即「认可这份文档」，文档里还写着
-      // 「这里我不知道」，确认就没有意义。与上面的前置门分开出账：拒绝原因必须指向真正的原因
-      // （合并会让作者去查「前置」，而前置其实是好的）。
-      // ⚠️ 文案锚点硬约束：本段禁止并入上方 gate 分支的输出契约（既有 confirm-doc.test.mjs 断言
-      // 锚定「未过逐阶段前置门（stage-gates）」子串），故单列独立分支。
+    }
+    // 待澄清项门（2026-10-12 needs-clarification；2026-10-18 立项跳对称化扩到 intents）：起草期挂
+    // 「待澄清」标记**不阻断**（零阻塞），但 draft→approved 确认时若仍挂着未澄清项则拒绝——确认即
+    // 「认可这份文档」，文档里还写着「这里我不知道」，确认就没有意义。intents 原不挂本门（旧判例
+    // 「澄清天然发生在需求单处」，S19c 旧断言），2026-10-18 推翻：intent 是后链全部文档的种子，
+    // 立项时被含混带过的不确定项到 spec/plan 跳已无人能补标——与 specs/plans 同口径挂门。判据与
+    // 文档类型无关（clarifyGateFor 只扫正文标记行），存量 intent 无标记零回溯；incidents 生命周期
+    // 无 approved 态，不在本门面。与上面的前置门分开出账：拒绝原因必须指向真正的原因（合并会让
+    // 作者去查「前置」，而前置其实是好的；前置门只适用于 specs/plans——入口文档无「前置」概念）。
+    // ⚠️ 文案锚点硬约束：本段禁止并入上方 gate 分支的输出契约（既有 confirm-doc.test.mjs 断言
+    // 锚定「未过逐阶段前置门（stage-gates）」子串），故单列独立分支。
+    if (target === 'approved' && (doc.startsWith('workflow/specs/') || doc.startsWith('workflow/plans/')
+      || doc.startsWith('workflow/intents/'))) {
       const cl = clarifyGateFor(abs);
       if (!cl.ok) {
         console.error(`❌ ${doc} 含未澄清项（needs-clarification）：${cl.reason}`);
@@ -541,9 +548,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

@@ -436,15 +436,31 @@ const readLedgerOf = (root) => {
       JSON.stringify({ status: r.status, stderr: r.stderr }));
     fs.rmSync(root, { recursive: true, force: true });
   }
-  // intents 不受本门约束（歧义标记的落点是 spec/plan 的设计判据；intent 是需求单，澄清天然发生在此处）
-  const root3 = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl3-'));
-  fs.mkdirSync(path.join(root3, 'workflow', 'intents'), { recursive: true });
-  fs.writeFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), '---\n状态: draft\n级别: L1\n---\n# I\n\n- 待澄清：范围含不含移动端？\n');
-  const r3 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
-  check('S19c 待澄清门：intent 不受本门约束（澄清天然发生在需求单处）',
-    r3.status === 0 && fs.readFileSync(path.join(root3, 'workflow', 'intents', '2026-10-12-p.md'), 'utf8').includes('状态: approved'),
-    JSON.stringify({ status: r3.status, stderr: r3.stderr }));
-  fs.rmSync(root3, { recursive: true, force: true });
+  // intents 挂门（2026-10-18 立项跳对称化，推翻旧判例「澄清天然发生在需求单处」——intent 是后链
+  // 全部文档的种子，立项时被含混带过的不确定项到 spec/plan 跳已无人能补标；存量无标记零回溯）
+  {
+    const root3 = fs.mkdtempSync(path.join(os.tmpdir(), 'confirm-cl3-'));
+    fs.mkdirSync(path.join(root3, 'workflow', 'intents'), { recursive: true });
+    const ip = path.join(root3, 'workflow', 'intents', '2026-10-12-p.md');
+    fs.writeFileSync(ip, '---\n状态: draft\n级别: L1\n---\n# I\n\n- 待澄清：范围含不含移动端？\n');
+    const r3 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
+    check('S19c 待澄清门：intent 挂未澄清项 → exit 2 + 点名内容 + 未落盘（立项跳对称化）',
+      r3.status === 2 && /needs-clarification/.test(r3.stderr) && /移动端/.test(r3.stderr)
+        && !/逐阶段前置门/.test(r3.stderr)
+        && fs.readFileSync(ip, 'utf8').includes('状态: draft'),
+      JSON.stringify({ status: r3.status, stderr: r3.stderr }));
+    fs.writeFileSync(ip, '---\n状态: draft\n级别: L1\n---\n# I\n\n- 已澄清：范围仅桌面端（用户 10-12 拍板）\n');
+    const r4 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
+    check('S19c 待澄清门：intent 已澄清 → 放行落态',
+      r4.status === 0 && fs.readFileSync(ip, 'utf8').includes('状态: approved'),
+      JSON.stringify({ status: r4.status, stderr: r4.stderr }));
+    fs.writeFileSync(ip, '---\n状态: draft\n级别: L1\n---\n# I\n\n## 目标\n- 无标记存量件\n');
+    const r5 = spawnSync(process.execPath, [CLI, 'workflow/intents/2026-10-12-p.md', '--delegated', '可以'], { cwd: root3, encoding: 'utf8' });
+    check('S19c 待澄清门：intent 无标记（存量口径）→ 放行零回溯',
+      r5.status === 0 && fs.readFileSync(ip, 'utf8').includes('状态: approved'),
+      JSON.stringify({ status: r5.status, stderr: r5.stderr }));
+    fs.rmSync(root3, { recursive: true, force: true });
+  }
 }
 
 // ---- S20【逐阶段门】入口存在但未确认（draft）→ 拒绝 ----
@@ -1056,5 +1072,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);