agentic-flow-kit 1.7.15 → 1.8.0

package/templates/_agents/scripts/resolve-merge-conflicts.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// resolve-merge-conflicts.mjs — 台账与派生生成物合并冲突一键自愈器（2026-10-10；B9 自 Shipyard.Material
+//   回灌——判定面逐字对齐，出处沿革留痕在包源仓 git 历史与 CHANGELOG，装户径不引实例路径）
+// 解决什么：多人并发提同一分支，或单人多 worktree 并行后合并时，派生生成物与 append-only 台账走
+//   git 文本合并产生冲突。第一道防线是 `.gitattributes` 的 `merge=jsonl-union` 驱动（台账类冲突直接
+//   确定性并集，见 git-merge-jsonl.mjs）；本脚本是**兜底**——driver / gitattributes 行漏配退化成文本
+//   冲突、或 INDEX.md 这类生成物仍要人工解时，一键消解派生面，把人留在业务冲突上。
+// 逻辑：
+// 1. 扫描当前 Git 处于 unmerged (UU / AA / DD / AU / UA 等) 状态的文件；
+// 2. 若 workflow/INDEX.md 冲突：checkout --ours 后重新调用 gen-workflow-index.mjs 全量生成并 git add；
+// 3. 若 .agents/ 下 *.jsonl 台账冲突且双方内容都在（UU/AA）：利用 git-merge-jsonl.mjs 合并当前与对方
+//    版本并 git add。判定面按「.agents/ 前缀 + .jsonl 后缀」匹配，**天然含 confirmations.d/ 分片**——
+//    分片是 kit 确认行的默认写入口径（2026-10-13 ledger-shard-default），分片 UU/AA 同走并集；
+//    删除/改删型（DD/AU/UD/UA/DU）不做任何写入——自动并集会复活被删文件或凭空建空文件，仅提示人工裁决；
+// 4. 输出处理清单，退出码 0。
+
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import { mergeJsonlLines } from './git-merge-jsonl.mjs';
+
+const git = (args) => {
+  try { return execFileSync('git', args, { encoding: 'utf8' }).trim(); }
+  catch (e) { return ''; }
+};
+
+export function getUnmergedFiles() {
+  const status = git(['status', '--porcelain']);
+  if (!status) return [];
+
+  const unmerged = [];
+  for (const line of status.split(/\r?\n/)) {
+    if (!line) continue;
+    const code = line.slice(0, 2);
+    const file = line.slice(3).trim();
+    // 冲突代码：UU (both modified), AA (both added), DU, UD 等
+    if (/^(UU|AA|DD|AU|UD|UA|DU)/.test(code)) {
+      unmerged.push({ file, code });
+    }
+  }
+  return unmerged;
+}
+
+export function autoResolveConflicts() {
+  const files = getUnmergedFiles();
+  if (files.length === 0) {
+    console.log('[resolve-conflicts] 当前无未解决的合并冲突。');
+    return { resolved: [], remaining: [] };
+  }
+
+  const resolved = [];
+  const remaining = [];
+
+  for (const { file, code } of files) {
+    const normFile = file.replace(/\\/g, '/');
+
+    // 1. workflow/INDEX.md 派生索引冲突：取当前版本为底，重新全量生成
+    if (normFile === 'workflow/INDEX.md') {
+      try {
+        execFileSync('git', ['checkout', '--ours', 'workflow/INDEX.md'], { stdio: 'pipe' });
+        // 调用索引生成器重新渲染
+        execFileSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { stdio: 'pipe' });
+        execFileSync('git', ['add', 'workflow/INDEX.md'], { stdio: 'pipe' });
+        resolved.push('workflow/INDEX.md (已自动全量重生成)');
+      } catch (err) {
+        remaining.push(`workflow/INDEX.md: 重生成失败 (${err.message})`);
+      }
+      continue;
+    }
+
+    // 2. .agents/ 下 *.jsonl 台账冲突（主台账与 confirmations.d/ 分片同判定面）：仅 UU/AA（双方内容
+    //    都在）取当前版本和对方版本合并去重；删除/改删型（DD/AU/UD/UA/DU）不可并集，自动写入会
+    //    复活被删文件或凭空建空文件
+    if (normFile.startsWith('.agents/') && normFile.endsWith('.jsonl')) {
+      if (!/^(UU|AA)$/.test(code)) {
+        remaining.push(`${file}: 删除/改删型冲突不自动处理，请人工裁决`);
+        continue;
+      }
+      try {
+        const ours = git(['show', `:2:${normFile}`]);
+        const theirs = git(['show', `:3:${normFile}`]);
+        const merged = mergeJsonlLines(ours, theirs);
+        fs.writeFileSync(file, merged, 'utf8');
+        execFileSync('git', ['add', file], { stdio: 'pipe' });
+        resolved.push(`${file} (已自动并集去重)`);
+      } catch (err) {
+        remaining.push(`${file}: 台账合并失败 (${err.message})`);
+      }
+      continue;
+    }
+
+    // 其余业务文件保持冲突，需人工审查
+    remaining.push(file);
+  }
+
+  return { resolved, remaining };
+}
+
+if (process.argv[1] && process.argv[1].endsWith('resolve-merge-conflicts.mjs')) {
+  const { resolved, remaining } = autoResolveConflicts();
+  if (resolved.length > 0) {
+    console.log('[resolve-conflicts] ✅ 已自动消解以下派生/台账冲突：');
+    resolved.forEach((f) => console.log(`  - ${f}`));
+  }
+  if (remaining.length > 0) {
+    console.log('\n[resolve-conflicts] ⚠️ 剩余业务代码冲突需手动介入处理：');
+    remaining.forEach((f) => console.log(`  - ${f}`));
+  } else if (resolved.length > 0) {
+    console.log('\n[resolve-conflicts] 所有台账冲突已全部清零，可继续 git commit 完成合并。');
+  }
+}

package/templates/_agents/scripts/resolve-merge-conflicts.test.mjs

@@ -0,0 +1,87 @@
+// resolve-merge-conflicts.test.mjs — 端到端测试合并冲突自愈器的收窄行为（临时 git 仓库夹具；B9 自 Shipyard.Material 回灌）：
+// UU（双方内容都在）走自动并集并 git add；删除/改删型（UD 等）不自动写入、不 git add，仅提示人工裁决。
+// 夹具说明：git merge 对「双方都删」会静默自动解决（不产生 DD 未合并条目，已实测），
+// 故删除型冲突用 modify/delete 构造（ours 修改 + theirs 删除 → UD），确定性复现未合并条目，
+// 且正是旧 bug 的复活路径（:3: 读取失败 → 吞错为 '' → 误写回 ours 内容并 git add）。
+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';
+
+let pass = 0, fail = 0;
+const check = (name, cond, detail = '') => {
+  if (cond) { pass++; console.log(`PASS  ${name}`); }
+  else { fail++; console.log(`FAIL  ${name}${detail ? ` —— ${detail}` : ''}`); }
+};
+
+const scriptPath = path.join(path.dirname(fileURLToPath(import.meta.url)), 'resolve-merge-conflicts.mjs');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'resolve-conflicts-test-'));
+
+const git = (...args) => spawnSync('git', args, { cwd: tmp, encoding: 'utf8' });
+const porcelain = () => git('status', '--porcelain').stdout.split(/\r?\n/).filter(Boolean);
+
+try {
+  // 夹具：临时 git 仓库，基线含主台账 + 分片
+  git('init');
+  git('config', 'user.email', 'test@local');
+  git('config', 'user.name', 'test');
+  git('config', 'core.autocrlf', 'false');
+  const ledger = path.join(tmp, '.agents', 'confirmations.jsonl');
+  const shard = path.join(tmp, '.agents', 'confirmations.d', 'shard-x.jsonl');
+  fs.mkdirSync(path.dirname(shard), { recursive: true });
+  fs.writeFileSync(ledger, '{"id":1}\n');
+  fs.writeFileSync(shard, '{"id":2}\n');
+  git('add', '-A');
+  git('commit', '-m', 'base');
+  const defaultBranch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout.trim();
+
+  // side：改主台账（追加 id:3）+ 删分片
+  git('checkout', '-b', 'side');
+  fs.writeFileSync(ledger, '{"id":1}\n{"id":3}\n');
+  fs.rmSync(shard);
+  git('add', '-A');
+  git('commit', '-m', 'side');
+
+  // main：改主台账（追加 id:4，与 side 不同行 → UU）+ 改分片（side 已删 → UD）
+  git('checkout', defaultBranch);
+  fs.writeFileSync(ledger, '{"id":1}\n{"id":4}\n');
+  fs.writeFileSync(shard, '{"id":2}\n{"id":5}\n');
+  git('add', '-A');
+  git('commit', '-m', 'main');
+
+  const merge = git('merge', 'side');
+  const statusConflicted = porcelain();
+  check('S1 夹具产生 UU+UD 冲突（merge 失败且两条未合并条目就位）',
+    merge.status !== 0 &&
+    statusConflicted.includes('UU .agents/confirmations.jsonl') &&
+    statusConflicted.includes('UD .agents/confirmations.d/shard-x.jsonl'),
+    `merge-exit=${merge.status} status=${statusConflicted.join(' | ')}`);
+
+  const shardBefore = fs.readFileSync(shard, 'utf8');
+
+  // 被测 CLI
+  const proc = spawnSync(process.execPath, [scriptPath], { cwd: tmp, encoding: 'utf8' });
+
+  check('S2 CLI exit 0（remaining 非零也 exit 0 的既有契约）', proc.status === 0, `status=${proc.status} stderr=${proc.stderr}`);
+
+  const merged = fs.readFileSync(ledger, 'utf8');
+  check('S3 UU 主台账=双方行并集', merged === '{"id":1}\n{"id":4}\n{"id":3}\n', merged);
+  check('S4 UU 主台账无冲突标记', !merged.includes('<<<<<<<'), merged);
+  const statusAfter = porcelain();
+  const ledgerLine = statusAfter.find((l) => l.endsWith('.agents/confirmations.jsonl'));
+  check('S5 UU 主台账已 git add（不再未合并）', !!ledgerLine && !/^(UU|AA|DD|AU|UD|UA|DU)/.test(ledgerLine), ledgerLine || '(不在 status 中)');
+
+  check('S6 UD 分片未被 git add（仍处未合并态）',
+    statusAfter.includes('UD .agents/confirmations.d/shard-x.jsonl'),
+    statusAfter.join(' | '));
+  check('S7 UD 分片内容未被自动改写', fs.readFileSync(shard, 'utf8') === shardBefore, fs.readFileSync(shard, 'utf8'));
+  check('S8 stdout 提示分片删除/改删型冲突需人工裁决',
+    proc.stdout.includes('.agents/confirmations.d/shard-x.jsonl') && proc.stdout.includes('删除/改删型冲突不自动处理'),
+    proc.stdout);
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/rewrite-file.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// rewrite-file.mjs — 按行字面替换 + 响亮失败（2026-10-12 silent-noop-loud-failure）
+// 背景（papercut 2026-10-06 行，留痕在包源仓 git 历史与 CHANGELOG；两次假落账实证）：
+//   `node -e "fs.writeFileSync(p, s.replace(A, B))"` 对 **CRLF 检出文件**用 `\n` 锚串定位时
+//   **静默无操作**，脚本照样打印「落账 OK」——假成功比响亮失败危险得多（台账/文档被以为改了）。
+// 本工具把该形态的三个失效点逐一堵死：
+//   ① 按行处理并保留原行尾（`/\r?\n/` 切分 + 检出 EOL 回写）——不再有「\n 锚串匹配不上 CRLF」这一类
+//   ② 替换数必须与 --expect 相符（默认 1）——0 命中即非零退出，**文件不写**，绝不存在「以为改了」
+//   ③ 写后回读校验（新锚已在、旧锚已零、行数不变、EOL 未变）——全过才打印成功；任一不过即非零退出
+// 另防两类自伤：find === replace（无操作却报成功）与目标文件不存在（fail-loud，不静默建文件）。
+// 原子写：同目录临时文件 + rename——中途崩溃不留半写文件（沿 git-merge-jsonl.mjs / compact-ledgers.mjs 惯例）。
+// 用法：node .agents/scripts/rewrite-file.mjs <文件> --find <字面串> --replace <字面串>
+//         [--expect N] [--allow-multi] [--dry-run] [--root <仓库根>]
+//   --expect N    期望命中数（默认 1）；实际 ≠ N → 非零退出且不写盘
+//   --allow-multi 显式声明允许多命中（等价 --expect 的宽松形态：N ≥ 1 即过，用于批量同串替换）
+//   --dry-run     只打印将发生的替换与校验预览，不写盘
+// 测试：node .agents/scripts/rewrite-file.test.mjs
+// 沿革：2026-10-12 立档（优先级 3：把「静默无操作」改成响亮失败）
+import fs from 'node:fs';
+import path from 'node:path';
+
+const argv = process.argv.slice(2);
+const argOf = (k) => {
+  const i = argv.indexOf(k);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : '';
+};
+const DRY = argv.includes('--dry-run');
+const MULTI = argv.includes('--allow-multi');
+let file = '';
+let find = null;
+let replace = null;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--find') find = argv[++i] ?? null;
+  else if (a === '--replace') replace = argv[++i] ?? null;
+  else if (a === '--expect') { /* 下面统一解析 */ }
+  else if (a === '--root') { /* 仅为与其它脚本口令一致，路径按 cwd 解析 */ i++; }
+  else if (a === '--dry-run' || a === '--allow-multi') { /* 旗标已处理 */ }
+  else if (!a.startsWith('--') && !file) file = a;
+}
+const expectRaw = argOf('--expect');
+
+const USAGE = `用法：node .agents/scripts/rewrite-file.mjs <文件> --find <字面串> --replace <字面串> [--expect N] [--allow-multi] [--dry-run]`;
+const die = (msg) => { console.error(`❌ rewrite-file: ${msg}\n${USAGE}`); process.exit(1); };
+if (argv.includes('--help') || argv.includes('-h')) { console.log(USAGE); process.exit(0); }
+if (!file) die('缺目标文件');
+if (find === null || replace === null) die('--find 与 --replace 必须成对给出');
+if (find === '') die('--find 不能为空串（空串会命中每一行，属误用）');
+if (find === replace) die(`--find 与 --replace 相同（「${find.slice(0, 40)}」）——无操作却会报成功，正是本工具要堵的形态`);
+let expect = 1;
+if (expectRaw !== '') {
+  if (!/^\d+$/.test(expectRaw)) die(`--expect 须为非负整数（现 ${expectRaw}）`);
+  expect = Number(expectRaw);
+}
+if (MULTI && expectRaw !== '') die('--allow-multi 与 --expect 互斥（一个宽松一个严格，同给无法裁决）');
+
+const abs = path.resolve(process.cwd(), file);
+if (!fs.existsSync(abs)) die(`目标文件不存在：${file}（不静默创建新文件——路径写错时应响亮失败）`);
+let raw;
+try { raw = fs.readFileSync(abs, 'utf8'); } catch (err) { die(`读取失败：${file}（${err.message}）`); }
+
+// ---- 按行处理 + EOL 保全 ----
+const crlf = raw.includes('\r\n');
+const eol = crlf ? '\r\n' : '\n';
+const hadTrailingNewline = /\r?\n$/.test(raw);
+const lines = raw.split(/\r?\n/);
+// 末行是「 trailing newline 产生的空串」时不计入可替换行集合（避免把 EOF 空串当一行改）
+const bodyLines = hadTrailingNewline ? lines.slice(0, -1) : lines;
+
+let hits = 0;
+const changedIdx = [];
+const newBody = bodyLines.map((l, i) => {
+  if (!l.includes(find)) return l;
+  const n = l.split(find).length - 1;
+  hits += n;
+  changedIdx.push(i + 1);
+  return l.split(find).join(replace);
+});
+
+if (hits === 0) {
+  console.error(`❌ rewrite-file: 0 命中——未写盘（文件保持原样）`);
+  console.error(`   文件：${file}`);
+  console.error(`   行尾：${crlf ? 'CRLF（仓库 autocrlf 检出态）' : 'LF'}｜总行数：${bodyLines.length}`);
+  console.error(`   锚串（前 80 字符）：${JSON.stringify(find.slice(0, 80))}`);
+  console.error(`   常见成因：① 锚串与文件实际内容不一致（空格/全角/标点）；② 用 \\n 跨行锚串去匹配 CRLF 文件——本工具按行匹配，跨行锚请拆成单行锚或改用 Edit 工具；③ 文件已被前一次改动写过。`);
+  process.exit(1);
+}
+if (MULTI) {
+  if (hits < 1) die('内部不变式违反：hits < 1');
+} else if (hits !== expect) {
+  console.error(`❌ rewrite-file: 命中数 ${hits} ≠ 期望 ${expect}——未写盘（文件保持原样）`);
+  console.error(`   文件：${file}｜命中行号：${changedIdx.join(', ')}`);
+  console.error(`   含义：锚串不是唯一命中——要么目标不唯一（应加 --expect ${hits} 或 --allow-multi 明示），要么文件已被改过。`);
+  process.exit(1);
+}
+
+const out = newBody.join(eol) + (hadTrailingNewline ? eol : '');
+if (newBody.length !== bodyLines.length) die('内部不变式违反：行数发生变化');
+
+if (DRY) {
+  console.log(`[dry-run] ${file}：将替换 ${hits} 处（行 ${changedIdx.join(', ')}），行尾 ${crlf ? 'CRLF' : 'LF'}，未写盘`);
+  process.exit(0);
+}
+
+// ---- 原子写 ----
+const tmp = `${abs}.rewrite-tmp`;
+try {
+  fs.writeFileSync(tmp, out, 'utf8');
+  fs.renameSync(tmp, abs);
+} catch (err) {
+  try { fs.unlinkSync(tmp); } catch { /* tmp 可能尚未创建 */ }
+  die(`写入失败：${file}（${err.message}）——原文件应保持原样，请核对后重试`);
+}
+
+// ---- 写后回读校验（③）：任一不过即非零退出，绝不打印成功 ----
+const problems = [];
+let back;
+try { back = fs.readFileSync(abs, 'utf8'); } catch (err) { die(`回读失败：${file}（${err.message}）——写入结果不可验证，请人工核对`); }
+if (back !== out) problems.push('回读内容与拟写内容不一致（写入被截断或并发改动）');
+if (back.includes(find)) problems.push('旧锚串仍存在于回读内容中（替换不完整）');
+if (replace !== '' && !back.includes(replace)) problems.push('新锚串不在回读内容中');
+const backLines = back.split(/\r?\n/);
+const backBody = hadTrailingNewline ? backLines.slice(0, -1) : backLines;
+if (backBody.length !== bodyLines.length) problems.push(`行数变化：${bodyLines.length} → ${backBody.length}`);
+if (back.includes('\r\n') !== crlf) problems.push(`行尾形态变化：${crlf ? 'CRLF' : 'LF'} → ${back.includes('\r\n') ? 'CRLF' : 'LF'}`);
+if (problems.length) {
+  console.error(`❌ rewrite-file: 写后回读校验未过——${file}`);
+  problems.forEach((p) => console.error(`   - ${p}`));
+  console.error('   现场已保留（不要手改），请核对后用 git 恢复或重新替换');
+  process.exit(1);
+}
+
+console.log(`✅ rewrite-file: ${file} 替换 ${hits} 处（行 ${changedIdx.join(', ')}）｜行尾 ${crlf ? 'CRLF' : 'LF'} 保全｜行数 ${bodyLines.length} 不变｜回读校验通过`);

package/templates/_agents/scripts/rewrite-file.test.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// rewrite-file.test.mjs — 按行字面替换 + 响亮失败 fixture 套件（2026-10-12 silent-noop-loud-failure）
+// 覆盖：CRLF 保全（papercut 2026-10-06 的静默无操作场景）/ 0 命中不写盘 / 命中数不符期望 /
+//       --allow-multi / --dry-run / 缺文件 fail-loud / find===replace 自伤防护 / 跨行锚串必失败 /
+//       无尾换行保全 / 写后回读校验成功形态
+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_DIR = path.dirname(fileURLToPath(import.meta.url));
+const SCRIPT = path.join(SCRIPT_DIR, 'rewrite-file.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 run = (file, args) => {
+  const r = spawnSync(process.execPath, [SCRIPT, file, ...args], { encoding: 'utf8' });
+  return { code: r.status, out: `${r.stdout || ''}${r.stderr || ''}` };
+};
+const mk = (name, content) => {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'rewrite-file-'));
+  const p = path.join(d, name);
+  fs.writeFileSync(p, content, 'utf8');
+  return p;
+};
+
+// T1：基本 LF 替换 → exit 0 + 内容正确 + 成功语含回读校验
+{
+  const p = mk('lf.md', 'a\nANCHOR\nc\n');
+  const r = run(p, ['--find', 'ANCHOR', '--replace', 'NEW']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T1 基本 LF 替换 → exit 0 且内容正确', r.code === 0 && after === 'a\nNEW\nc\n', r.out);
+  check('T1b 成功语含「回读校验通过」', /回读校验通过/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T2：CRLF 保全——papercut 2026-10-06 的静默无操作场景，本工具必须真改且不坏行尾
+{
+  const p = mk('crlf.md', 'line1\r\nANCHOR here\r\nline3\r\n');
+  const r = run(p, ['--find', 'ANCHOR', '--replace', 'NEW']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T2 CRLF 文件替换成功且行尾保全', r.code === 0 && after === 'line1\r\nNEW here\r\nline3\r\n', r.out);
+  check('T2b 未混入裸 LF（无 CRLF→LF 漂移）', !/[^\r]\n/.test(after), JSON.stringify(after));
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T3：0 命中 → exit 1 且文件逐字节不变（核心：绝不存在「以为改了」）
+{
+  const before = 'x\r\nZZZ not here\r\n';
+  const p = mk('nohit.md', before);
+  const r = run(p, ['--find', 'QQQ', '--replace', 'Q']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T3 0 命中 → exit 1 且文件逐字节不变', r.code === 1 && after === before, r.out);
+  check('T3b 报错点名行尾与常见成因（CRLF 检出态）', /0 命中/.test(r.out) && /CRLF/.test(r.out) && /跨行锚/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T4：命中数与期望不符 → exit 1 且不写盘（锚串非唯一时必须响亮，不可顺手全改）
+{
+  const before = 'k\nk\n';
+  const p = mk('multi.md', before);
+  const r = run(p, ['--find', 'k', '--replace', 'K']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T4 命中 2 ≠ 期望 1 → exit 1 且未写盘', r.code === 1 && after === before && /命中数 2 ≠ 期望 1/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T5：显式 --expect 2 → 过（同一行两处命中也按处计）
+{
+  const p = mk('expect2.md', 'k k\n');
+  const r = run(p, ['--find', 'k', '--replace', 'K', '--expect', '2']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T5 --expect 2 且命中 2 → exit 0 且两处都改', r.code === 0 && after === 'K K\n', r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T6：--allow-multi 多命中 → 过（宽松形态，明示批量）
+{
+  const p = mk('allowmulti.md', 'k\nk\nk\n');
+  const r = run(p, ['--find', 'k', '--replace', 'K', '--allow-multi']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T6 --allow-multi 三命中 → exit 0 且全改', r.code === 0 && after === 'K\nK\nK\n', r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T7：--allow-multi 与 --expect 互斥 → exit 1（一宽一严无法裁决）
+{
+  const p = mk('conflict.md', 'k\n');
+  const r = run(p, ['--find', 'k', '--replace', 'K', '--allow-multi', '--expect', '1']);
+  check('T7 --allow-multi 与 --expect 互斥 → exit 1', r.code === 1 && /互斥/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T8：--dry-run → 不写盘
+{
+  const p = mk('dry.md', 'a\nANCHOR\n');
+  const r = run(p, ['--find', 'ANCHOR', '--replace', 'NEW', '--dry-run']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T8 --dry-run → exit 0 且未写盘', r.code === 0 && after === 'a\nANCHOR\n' && /dry-run/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T9：目标文件不存在 → exit 1 fail-loud（不静默创建新文件）
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'rewrite-file-'));
+  const r = run(path.join(d, 'nope.md'), ['--find', 'a', '--replace', 'b']);
+  check('T9 文件不存在 → exit 1 且不创建文件', r.code === 1 && /不存在/.test(r.out) && !fs.existsSync(path.join(d, 'nope.md')), r.out);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+// T10：find === replace → exit 1（无操作却报成功，正是要堵的形态）
+{
+  const p = mk('same.md', 'a\nSAME\n');
+  const r = run(p, ['--find', 'SAME', '--replace', 'SAME']);
+  check('T10 find === replace → exit 1', r.code === 1 && /相同/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T11：跨行锚串（含 \n）→ 0 命中 exit 1——把「\n 锚串匹配 CRLF 文件静默无操作」变成响亮失败
+{
+  const p = mk('crossline.md', 'aaa\r\nbbb\r\n');
+  const r = run(p, ['--find', 'aaa\nbbb', '--replace', 'xxx']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T11 跨行锚串 → exit 1 且文件不变（提示拆单行锚）', r.code === 1 && after === 'aaa\r\nbbb\r\n' && /跨行锚/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T12：无尾换行保全
+{
+  const p = mk('notrailing.md', 'a\nANCHOR');
+  const r = run(p, ['--find', 'ANCHOR', '--replace', 'NEW']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T12 原文件无尾换行 → 替换后仍无尾换行', r.code === 0 && after === 'a\nNEW', JSON.stringify(after));
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T13：空 --find → exit 1（空串会命中每一行，属误用）
+{
+  const p = mk('emptyfind.md', 'a\n');
+  const r = run(p, ['--find', '', '--replace', 'b']);
+  check('T13 空 --find → exit 1', r.code === 1 && /不能为空串/.test(r.out), r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+// T14：同行的两处命中按处计数，且 --expect 3 精确匹配（处计数语义显式化）
+{
+  const p = mk('twiceinline.md', 'k-k-k\n');
+  const r = run(p, ['--find', 'k', '--replace', 'K', '--expect', '3']);
+  const after = fs.readFileSync(p, 'utf8');
+  check('T14 同行多处按处计数（3 处）→ exit 0', r.code === 0 && after === 'K-K-K\n', r.out);
+  fs.rmSync(path.dirname(p), { recursive: true, force: true });
+}
+
+console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
+process.exit(fail ? 1 : 0);

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

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// 常驻面体积预算检查（单源：本脚本 + .agents/rule-budgets.txt；触发点：check-hygiene 检查 13（--all，WARN）、
+// .githooks/pre-commit（--staged，硬拦））
+// 自 sh 版移植 node（2026-10-08 ci 去 sh 化；2026-10-13 自 Shipyard.Material 参考实现回灌）——CI agent（Windows）
+// 免 git-bash 依赖，check-loop 检查 13 从「无 sh 静默跳过」变恒可跑。语义逐条对齐 sh 版：
+//   --all    查「提交后树」全量；--staged 仅查本次暂存触及的条目 + 触及目录的合计
+//   退出码 0 通过 / 1 超限（违例打到 stdout，调用方决定警告还是阻断）；缺预算表 exit 0（fixture 沙箱不拦——既有语义）
+// 「提交后树」= 索引（index）内容：staged 版优先于 HEAD；无 git（fixture）回退工作区文件。
+// 字节口径 = 索引 / HEAD 内容（git cat-file，LF 归一）。禁用工作区 wc -c 口径（CRLF 膨胀系统性偏大，
+// 2026-09-21 实测差 ~500B 一度误判超限）——本脚本所有字节数都走 cat-file，仅无 git 时才落工作区。
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const mode = process.argv[2] === '--staged' ? '--staged' : '--all';
+
+const git = (args) => {
+  const r = spawnSync('git', args, { encoding: 'utf8' });
+  return { ok: !r.error && r.status === 0, out: (r.stdout || '').trim() };
+};
+const root = git(['rev-parse', '--show-toplevel']);
+if (root.ok) process.chdir(root.out); // 非 git 环境（fixture 沙箱）留在原地
+
+const BUDGETS = '.agents/rule-budgets.txt';
+if (!fs.existsSync(BUDGETS)) process.exit(0);
+
+// 「提交后」字节数：索引 → HEAD → 工作区
+const fsize = (f) => {
+  if (git(['cat-file', '-e', `:${f}`]).ok) return Number(git(['cat-file', '-s', `:${f}`]).out);
+  if (git(['cat-file', '-e', `HEAD:${f}`]).ok) return Number(git(['cat-file', '-s', `HEAD:${f}`]).out);
+  try { return fs.readFileSync(f).length; } catch { return 0; }
+};
+
+const staged = mode === '--staged'
+  ? git(['-c', 'core.quotepath=off', 'diff', '--cached', '--name-only']).out.split('\n').filter(Boolean)
+  : [];
+
+// intentional-simple: glob 仅支持预算表在用的两形态——「固定目录 + * 后缀」（.agents/commands/*.md）
+// 与目录本身（/ 结尾，展开一层直接子文件）；表出现更复杂 glob 时再升级
+const expand = (pat) => {
+  if (pat.endsWith('/')) {
+    const dir = pat.replace(/\/$/, '');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile())
+      .map((e) => path.join(dir, e.name));
+  }
+  if (pat.includes('*')) {
+    const i = pat.lastIndexOf('/');
+    const dir = i < 0 ? '.' : pat.slice(0, i);
+    const name = pat.slice(i + 1);
+    const star = name.indexOf('*');
+    const pre = name.slice(0, star), suf = name.slice(star + 1);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isFile()
+      && e.name.startsWith(pre) && e.name.endsWith(suf))
+      .map((e) => path.join(dir, e.name));
+  }
+  return fs.existsSync(pat) ? [pat] : [];
+};
+
+let viol = 0;
+const over = (what, bytes, lim) => { console.log(`常驻面超限：${what} ${bytes}B > 上限 ${lim}B`); viol = 1; };
+
+for (const line of fs.readFileSync(BUDGETS, 'utf8').split(/\r?\n/)) {
+  const sp = line.lastIndexOf(' ');
+  if (sp < 0) continue;
+  const pat = line.slice(0, sp), lim = line.slice(sp + 1);
+  if (pat === '' || pat.startsWith('#')) continue;
+  if (!/^\d+$/.test(lim)) continue;
+  if (pat.endsWith('/')) {
+    // 目录合计：--staged 下仅当暂存触及该目录内文件才查（字面前缀匹配，同 sh 版 2026-09-24 口径）
+    if (mode === '--staged' && !staged.some((sf) => sf.startsWith(pat))) continue;
+    const total = expand(pat).reduce((s, f) => s + fsize(f), 0);
+    if (total > Number(lim)) over(`${pat} 合计`, total, lim);
+  } else {
+    for (const f of expand(pat)) {
+      if (mode === '--staged' && !staged.includes(f.replace(/\\/g, '/'))) continue;
+      const b = fsize(f);
+      if (b > Number(lim)) over(f, b, lim);
+    }
+  }
+}
+process.exit(viol ? 1 : 0);