agentic-flow-kit 1.7.0 → 1.7.16

package/templates/_agents/scripts/check-loop.test.mjs

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { computeFingerprint } from './confirm-doc.mjs';
 import { POLICIES, loadKitPolicy } from './policy.mjs';
 import { entryConfirmed, laneOfEntry, laneOfDoc } from './stage-gates.mjs';
-import { parseAddedDatesLog, addedDatesWithCache } from './check-loop.mjs';
+import { parseAddedDatesLog, addedDatesWithCache, scenarioIdsOf, extractThenByScenario, sectionHasBody, sedimentLandingIsShell } from './check-loop.mjs';
 
 const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
 const CHECK_LOOP = path.join(SCRIPT_DIR, 'check-loop.mjs');
@@ -28,6 +28,10 @@ const check = (desc, cond, detail = '') => {
   else { fail++; console.log(`FAIL  ${desc}${detail ? '\n      ' + detail : ''}`); }
 };
 
+// 夹具闭包工具（2026-10-12 fixture-closure-rootfix）：本文件此前 5 处手写依赖枚举，2026-10-12 那批
+// 台账改动漏拷 ledger-loader.mjs 就假绿过（看板漂移门恒绿）。改为按入口自动求传递闭包——新增依赖自动跟随。
+const { copyScriptClosure, copyAgentsFiles } = await import('./fixture-scripts.mjs');
+
 // mkfix：空 fixture 根（四目录 + 枚举单源内联 8 键——fixture 自包含，测消费逻辑而非当前词表值）
 const ENUMS_FIXTURE = [
   'doc.status.all=draft approved done superseded cancelled',
@@ -383,9 +387,8 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
 {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'gen-workflow-index.mjs'), path.join(T, '.agents', 'scripts', 'gen-workflow-index.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'workflow-enums.mjs'), path.join(T, '.agents', 'scripts', 'workflow-enums.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+  copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs']);
+  copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
   w(T, 'workflow/intents/2026-09-22-mod-ok.md', INTENT('mod ok', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline', '\n## 验收标准（可测试）\n- [ ] 用例通过\n'));
   w(T, 'workflow/plans/2026-09-22-mod-ok.md', PLAN('mod ok', '状态: approved\n级别: L1\n模块: pipeline'));
   spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -412,9 +415,8 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
 {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'gen-workflow-index.mjs'), path.join(T, '.agents', 'scripts', 'gen-workflow-index.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, 'workflow-enums.mjs'), path.join(T, '.agents', 'scripts', 'workflow-enums.mjs'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+  copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs']);
+  copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
   w(T, 'workflow/intents/2026-09-22-drift.md', INTENT('drift', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
   w(T, 'workflow/plans/2026-09-22-drift.md', PLAN('drift', '状态: approved\n级别: L1\n模块: pipeline'));
   spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -430,10 +432,10 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   const mkDashFix = () => {
     const T = mkfix();
     fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
-    for (const f of ['gen-workflow-index.mjs', 'gen-workflow-dashboard.mjs', 'agg-delegations.cjs', 'workflow-enums.mjs']) {
-      fs.copyFileSync(path.join(SCRIPT_DIR, f), path.join(T, '.agents', 'scripts', f));
-    }
-    fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'workflow-modules.txt'), path.join(T, '.agents', 'workflow-modules.txt'));
+    // 看板/索引生成器的台账读取依赖（ledger-loader 等）由闭包自动带入——此前手写枚举漏拷过，
+    // 表现是「import 失败 → 看板静默不生成 → 漂移门恒绿」，即假绿比红危险（2026-10-12 已修，见 fixture-scripts.mjs）
+    copyScriptClosure(path.join(T, '.agents', 'scripts'), ['gen-workflow-index.mjs', 'gen-workflow-dashboard.mjs']);
+    copyAgentsFiles(path.join(T, '.agents'), ['workflow-modules.txt']);
     w(T, 'workflow/intents/2026-09-22-dash.md', INTENT('dash', '状态: approved\n级别: L1\n日期: 2026-09-22\n模块: pipeline'));
     w(T, 'workflow/plans/2026-09-22-dash.md', PLAN('dash', '状态: approved\n级别: L1\n模块: pipeline'));
     spawnSync(process.execPath, ['.agents/scripts/gen-workflow-index.mjs'], { cwd: T });
@@ -460,7 +462,7 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
   const T = mkfix();
   fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
   fs.copyFileSync(path.join(SCRIPT_DIR, 'rule-budget.sh'), path.join(T, '.agents', 'scripts', 'rule-budget.sh'));
-  fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'rule-budgets.txt'), path.join(T, '.agents', 'rule-budgets.txt'));
+  copyAgentsFiles(path.join(T, '.agents'), ['rule-budgets.txt']);
   // 超限样本自校准：从拷入的预算表读 AGENTS.md 上限（预算可上调，硬编码样本会随上调失效——2026-10-06-v114-backflow-batch）
   const agLimit = Number(fs.readFileSync(path.join(T, '.agents', 'rule-budgets.txt'), 'utf8').split(/\r?\n/).find((l) => l.startsWith('AGENTS.md ')).trim().split(' ').pop());
   w(T, 'AGENTS.md', '# AGENTS 小体积 fixture\n');
@@ -488,7 +490,7 @@ const mkConfirmedDoc = (root, rel, fmBody) => {
     const T = mkfix();
     fs.mkdirSync(path.join(T, '.agents', 'scripts'), { recursive: true });
     fs.copyFileSync(path.join(SCRIPT_DIR, 'rule-budget.sh'), path.join(T, '.agents', 'scripts', 'rule-budget.sh'));
-    fs.copyFileSync(path.join(SCRIPT_DIR, '..', 'rule-budgets.txt'), path.join(T, '.agents', 'rule-budgets.txt'));
+    copyAgentsFiles(path.join(T, '.agents'), ['rule-budgets.txt']);
     const agLimit = Number(fs.readFileSync(path.join(T, '.agents', 'rule-budgets.txt'), 'utf8').split(/\r?\n/).find((l) => l.startsWith('AGENTS.md ')).trim().split(' ').pop());
     gitInit(T);
     w(T, 'AGENTS.md', 'x'.repeat(agLimit + 512));
@@ -2919,8 +2921,11 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   writeLedger(T, [tampered, row2]);
   let r = run(T);
   let out = outOf(r);
+  // 定位措辞随 2026-10-12 ledger-shard-write 由「第 N 行（物理）」改为 `rel:行号`——
+  // 台账视图含主台账 + 分片后，单一行号跨来源无法定位，必须带来源。首断行号仍须精确指向第 1 行。
   check('场景 21a 链断裂：中间行篡改 → hard 台账链断裂（指首断行号）',
-    r.status !== 0 && out.includes('台账链断裂') && /第 1 行/.test(out), `exit=${r.status}\n${out.slice(-400)}`);
+    r.status !== 0 && out.includes('台账链断裂') && /\.agents\/confirmations\.jsonl:1\b/.test(out),
+    `exit=${r.status}\n${out.slice(-400)}`);
   // 反证还原：篡改行恢复原 quote → 链复通（断言非恒绿）
   writeLedger(T, [row1, row2]);
   r = run(T);
@@ -3023,5 +3028,315 @@ w(T, 'workflow/intents/2026-09-12-deep.md', INTENT('deep', '状态: draft\n级
   fs.rmSync(cacheP, { force: true });
 }
 
+// ---- 场景 23：场景覆盖子判据（2026-10-10 scenario-coverage，灰度 warning）----
+// scenarioIdsOf 纯函数 + 端到端（spec 有「验收场景」节 → done intent 须逐场景引用；缺 = warning 不阻断）
+{
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'scen-ids-'));
+  fs.writeFileSync(path.join(d, 's1.md'),
+    '---\n状态: draft\n---\n# SPEC\n## 功能行为\n### S0 不该被提取（节外）\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n## 数据流\n### S3 也不提取（节外）\n');
+  const ids = scenarioIdsOf(path.join(d, 's1.md'));
+  check('场景 24a scenarioIdsOf：只提「验收场景」节内 ID，按序去重', ids.join(',') === 'S1,S2', JSON.stringify(ids));
+  fs.writeFileSync(path.join(d, 's2.md'), '---\n状态: draft\n---\n# SPEC\n## 功能行为\n无场景节\n');
+  check('场景 24b scenarioIdsOf：无「验收场景」节 → 空数组', scenarioIdsOf(path.join(d, 's2.md')).length === 0);
+  check('场景 24c scenarioIdsOf：文件不可读 → 空数组（fail-open）', scenarioIdsOf(path.join(d, 'nope.md')).length === 0);
+  fs.rmSync(d, { recursive: true, force: true });
+}
+{
+  // 端到端：spec 两场景 + intent 全引用 → exit 0 且无「场景未覆盖」warning
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:冒烟 checkout.json）\n- [x] 场景：S2 退款到账（证据:refund.test.js）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24d spec 有场景且 intent 全引用 → exit 0 无告警', r.status === 0 && !outOf(r).includes('场景未覆盖'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // 端到端：缺 S2 引用 → warning（灰度，不阻断：exit 仍 0）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n### S2 退款\n- GIVEN a\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:冒烟 checkout.json）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24e 缺场景引用 → warning 且不阻断（exit 0）',
+    r.status === 0 && outOf(r).includes('场景未覆盖') && outOf(r).includes('缺 S2'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：spec 无场景节 → 零变化（不出现「场景未覆盖」）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-sc.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — sc\n## 功能行为\n普通 spec\n');
+  w(T, 'workflow/intents/2026-09-12-sc.md', INTENT('sc', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-sc.md', PLAN('sc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 24f spec 无场景节 → 零变化（无场景告警，exit 0）', r.status === 0 && !outOf(r).includes('场景未覆盖'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+
+// ---- 场景 25：沉淀追踪子判据（2026-10-10 sediment-tracking，灰度 warning）----
+// sectionHasBody 纯函数 + 端到端（done intent 含影响面/触达红线 且 frontmatter 无「沉淀」→ WARN 未沉淀；
+// incident closed 且三件套齐全 → 同款；「沉淀: 无」豁免；路径断档 → WARN 沉淀断档）
+{
+  check('场景 25a sectionHasBody：标题后有实质行 → true',
+    sectionHasBody(['## 影响面', '- 页面 A', ''], '影响面') === true);
+  check('场景 25b sectionHasBody：光标题（模板未填）→ false',
+    sectionHasBody(['## 影响面', '<页面 / 接口 / 数据范围>', ''], '影响面') === false);
+  check('场景 25c sectionHasBody：无该节 → false',
+    sectionHasBody(['## 目标', '做 X'], '影响面') === false);
+  check('场景 25d sectionHasBody：前缀匹配 + 节外有同名行不算',
+    sectionHasBody(['## 目标', '提影响面', '## 影响面与边界', '- 内容'], '影响面') === true);
+}
+{
+  // intent 侧：done + 影响面有内容 + 无沉淀字段 → WARN 未沉淀（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A / 接口 B\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25e done intent 高价值无沉淀 → WARN 未沉淀且不阻断',
+    r.status === 0 && outOf(r).includes('未沉淀') && outOf(r).includes('2026-09-12-sed.md'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 「沉淀: 无」显式豁免 → 无未沉淀告警
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: 无',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25f 「沉淀: 无」显式豁免 → 无未沉淀告警',
+    r.status === 0 && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 沉淀字段指向不存在的文件 → WARN 沉淀断档
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/不存在.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25g 沉淀字段指向缺失文件 → WARN 沉淀断档',
+    r.status === 0 && outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // intent 无影响面/触达红线 → 零变化（不出现未沉淀告警）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25h intent 无高价值节 → 零变化', r.status === 0 && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // incident 侧：closed 且三件套齐全 且无沉淀 → WARN 未沉淀
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25i closed incident 三件套齐全无沉淀 → WARN 未沉淀',
+    r.status === 0 && outOf(r).includes('未沉淀') && outOf(r).includes('2026-09-12-inc.md'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // incident 三件套不全 → 沉淀子判据不触发（不出未沉淀，只出三件套不全）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n1. 结构性修复\n - 修复 commit:abc1234\n - 是否需要新 intent:\n - 否 → 理由:单点修复\n`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25j incident 三件套不全 → 只告三件套不全，不出未沉淀',
+    r.status === 0 && outOf(r).includes('三件套不全') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
+// ---- 场景 25 续：落点真实性（2026-10-11 landing-reality，P1-3，灰度 warning）----
+// sedimentLandingIsShell 纯函数 + 端到端（落点只有标题/占位 → WARN 落点空壳；带「来源:」frontmatter
+// 或 ≥3 行非占位正文 → 不出；不存在 → 仍 WARN 沉淀断档（回归）；指向目录（读取失败）→ 空壳并注明读取失败）
+{
+  check('场景 25k sedimentLandingIsShell：只有标题+占位（空壳）→ true',
+    sedimentLandingIsShell('---\n标题: 某主题\n---\n# 某主题\n<状态:待整理>\n') === true);
+  check('场景 25l sedimentLandingIsShell：frontmatter 有「来源:」→ false',
+    sedimentLandingIsShell('---\n来源: workflow/incidents/2026-09-12-inc.md\n---\n# 某主题\n') === false);
+  check('场景 25m sedimentLandingIsShell：非占位正文 ≥3 行 → false',
+    sedimentLandingIsShell('# 某主题\n- 要点一\n- 要点二\n- 要点三\n') === false);
+  check('场景 25n sedimentLandingIsShell：非占位正文仅 2 行 → true',
+    sedimentLandingIsShell('# 某主题\n- 要点一\n- 要点二\n') === true);
+  check('场景 25o sedimentLandingIsShell：读取失败（null）→ true',
+    sedimentLandingIsShell(null) === true);
+}
+{
+  // incident 侧：closed + 三件套齐全 + 沉淀指向只有标题/占位的文件 → WARN 落点空壳（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/shell.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/shell.md', '---\n标题: 某主题沉淀\n---\n# 某主题沉淀\n<状态:待整理>\n');
+  const r = run(T);
+  check('场景 25p incident 沉淀落点为标题/占位空壳 → WARN 落点空壳',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('2026-09-12-inc.md')
+    && !outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // intent 侧对称：done + 影响面有内容 + 沉淀指向空壳文件 → WARN 落点空壳（不阻断）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/shell.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/shell.md', '# 某主题沉淀\n<待整理>\n');
+  const r = run(T);
+  check('场景 25q intent 沉淀落点为标题/占位空壳 → WARN 落点空壳',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('2026-09-12-sed.md')
+    && !outOf(r).includes('沉淀断档') && !outOf(r).includes('未沉淀'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点带「来源:」frontmatter → 非空壳（无落点空壳告警）
+  const T = mkfix();
+  w(T, 'workflow/intents/2026-09-12-sed.md', INTENT('sed', '状态: done\n级别: L1\n日期: 2026-09-12\n沉淀: wiki/项目规范/real.md',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n## 影响面\n- 页面 A\n'));
+  w(T, 'workflow/plans/2026-09-12-sed.md', PLAN('sed', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/real.md', '---\n来源: workflow/incidents/2026-09-12-inc.md\n---\n# 某主题沉淀\n');
+  const r = run(T);
+  check('场景 25r 沉淀落点带来源 frontmatter → 不出落点空壳',
+    r.status === 0 && !outOf(r).includes('落点空壳') && !outOf(r).includes('沉淀断档'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点有 ≥3 行非占位正文 → 非空壳（incident 侧非空壳路径）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/real.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  w(T, 'wiki/项目规范/real.md', '---\n标题: 某主题沉淀\n---\n# 某主题沉淀\n- 要点一\n- 要点二\n- 要点三\n');
+  const r = run(T);
+  check('场景 25s 沉淀落点有 ≥3 行非占位正文 → 不出落点空壳',
+    r.status === 0 && !outOf(r).includes('落点空壳') && !outOf(r).includes('沉淀断档'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 回归：沉淀指向不存在的文件 → 仍是 WARN 沉淀断档（incident 侧；intent 侧由既有 25g 锚定）
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范/不存在.md\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 25t 沉淀指向缺失文件 → 仍 WARN 沉淀断档（不出落点空壳）',
+    r.status === 0 && outOf(r).includes('沉淀断档') && !outOf(r).includes('落点空壳'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 落点指向目录（readFileSync 抛异常）→ 按空壳出账并在文案注明读取失败
+  const T = mkfix();
+  w(T, 'workflow/incidents/2026-09-12-inc.md',
+    `---\n状态: closed\n级别: L1\n发现: 2026-09-12\n沉淀: wiki/项目规范\n---\n# INCIDENT — inc\n## 时间线\n- 用户确认：草稿过目通过（2026-09-12）\n## 复盘三件套（缺一不可）\n\n${三件套(false)}`);
+  w(T, 'workflow/plans/2026-09-12-inc.md', PLAN('inc', '状态: done\n级别: L1'));
+  fs.mkdirSync(path.join(T, 'wiki', '项目规范'), { recursive: true });
+  const r = run(T);
+  check('场景 25u 沉淀落点读取失败（目录）→ WARN 落点空壳并注明读取失败',
+    r.status === 0 && outOf(r).includes('落点空壳') && outOf(r).includes('读取失败'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
+// ---- 场景 92：THEN 断言抽取（2026-10-11 then-assertion，P2-2，灰度 warning）----
+// extractThenByScenario 纯函数 + 端到端（声明场景缺 THEN 行 = 空壳场景 → WARN 场景无断言，聚合一条；
+// 验收场景节本身可选——节不存在零变化）
+{
+  const spec = [
+    '## 验收场景（可选）',
+    '<说明行，不属于任何场景块>',
+    '### S1 折扣',
+    '- GIVEN 购物车有商品 THEN 不误抽（行中段 THEN 字样不算断言）',
+    '- WHEN 结算',
+    '- THEN 折扣金额入账',
+    '  - THEN 重复结算幂等（缩进变体也认）',
+    '### S2 退款',
+    'THEN: 退款单生成（无连字符带冒号也认）',
+    'THEN 审计流水落库（无连字符空格也认）',
+  ].join('\n');
+  const m = extractThenByScenario(spec);
+  check('场景 92a extractThenByScenario：- THEN / 缩进 / THEN: / THEN 变体均抽取',
+    m.get('S1').length === 2 && m.get('S2').length === 2
+    && m.get('S1')[0] === '- THEN 折扣金额入账' && m.get('S2')[0] === 'THEN: 退款单生成（无连字符带冒号也认）',
+    JSON.stringify([...m]));
+  check('场景 92b extractThenByScenario：GIVEN 行中段 THEN 字样不误抽',
+    !m.get('S1').some((s) => s.includes('GIVEN')), JSON.stringify(m.get('S1')));
+  check('场景 92c extractThenByScenario：无验收场景节 → 空 Map（节外 THEN 不认）',
+    extractThenByScenario('# SPEC\n## 功能行为\n- THEN 节外不认\n').size === 0);
+  check('场景 92d extractThenByScenario：非字符串（读取失败）→ 空 Map（不可判定不误报）',
+    extractThenByScenario(null).size === 0);
+}
+{
+  // 端到端：全场景带 THEN → 无「场景无断言」
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- WHEN y\n- THEN z\n### S2 退款\n- GIVEN a\n- THEN b\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1 折扣生效（证据:checkout.json）\n- [x] 场景：S2 退款到账（证据:refund.test.js）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92e 全场景带 THEN → 无场景无断言告警（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景无断言'), `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：S2/S3 缺 THEN → 聚合一条 WARN，S1（有断言）不在列
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n### S2 退款\n- GIVEN a\n### S3 对账\n- WHEN c\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S2（证据:b.log）\n- [x] 场景：S3（证据:c.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92f 场景缺 THEN → 聚合 WARN 且只列缺断言的 ID（S2、S3）',
+    r.status === 0 && outOf(r).includes('场景无断言') && outOf(r).includes('缺 THEN 断言：S2、S3'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+{
+  // 端到端：spec 无验收场景节 → THEN 对账不适用（零变化）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-thn.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — thn\n## 功能行为\n普通 spec，无场景节\n');
+  w(T, 'workflow/intents/2026-09-12-thn.md', INTENT('thn', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 用例通过（证据:jest 全绿）\n'));
+  w(T, 'workflow/plans/2026-09-12-thn.md', PLAN('thn', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 92g spec 无验收场景节 → 零场景告警（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景无断言') && !outOf(r).includes('场景引用断链'),
+    `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+
+// ---- 场景 93：引用断链反向对账（2026-10-11 dangling-ref，P2-1，灰度 warning）----
+// 端到端（与「场景未覆盖」共用同一次解析）：验收标准引用 spec 未声明的场景 ID → WARN 场景引用断链
+{
+  // 引用 S1（已声明且覆盖）+ S9（未声明）→ 只出断链，不出未覆盖
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S9 幻影场景（证据:ghost.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93a 引用 spec 未声明的 S9 → WARN 场景引用断链（不阻断）',
+    r.status === 0 && outOf(r).includes('场景引用断链') && outOf(r).includes('S9'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+  check('场景 93b 已覆盖的 S1 不触发未覆盖（两方向互不误伤）',
+    !outOf(r).includes('场景未覆盖'), outOf(r).slice(0, 400));
+}
+{
+  // 引用与声明完全一致 → 无断链
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 验收场景（可选）\n### S1 折扣\n- GIVEN x\n- THEN z\n### S2 退款\n- GIVEN a\n- THEN b\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n- [x] 场景：S2（证据:b.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93c 引用与声明一致 → 无断链无未覆盖（exit 0）',
+    r.status === 0 && !outOf(r).includes('场景引用断链') && !outOf(r).includes('场景未覆盖'),
+    `exit=${r.status}\n${outOf(r).slice(0, 400)}`);
+}
+{
+  // spec 无场景节但 intent 引用 S1 → 同样算断链（引用了不存在的场景）
+  const T = mkfix();
+  w(T, 'workflow/specs/2026-09-12-dr.md', '---\n状态: approved\n级别: L1\n---\n# SPEC — dr\n## 功能行为\n普通 spec，无场景节\n');
+  w(T, 'workflow/intents/2026-09-12-dr.md', INTENT('dr', '状态: done\n级别: L1\n日期: 2026-09-12',
+    '\n## 验收标准（可测试）\n- [x] 场景：S1（证据:a.log）\n'));
+  w(T, 'workflow/plans/2026-09-12-dr.md', PLAN('dr', '状态: done\n级别: L1'));
+  const r = run(T);
+  check('场景 93d spec 无场景节且引用 S1 → 断链 WARN（exit 0）',
+    r.status === 0 && outOf(r).includes('场景引用断链') && outOf(r).includes('S1'),
+    `exit=${r.status}\n${outOf(r).slice(0, 500)}`);
+}
+
 console.log(`\n合计: PASS ${pass} / FAIL ${fail}`);
-process.exit(fail ? 1 : 0);
+process.exit(fail ? 1 : 0);

package/templates/_agents/scripts/check-metric-claims.mjs

@@ -17,14 +17,16 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { readLedgerLines } from './ledger-loader.mjs';
 
 export function runCheck16(ctx) {
   const { ROOT, ENUMS, docFiles, fmGet, inSet, isTracked, linesOf, readdirOrNull, warnings } = ctx;
   const mcFile = path.join(ROOT, '.agents', 'metric-claims.txt');
   if (fs.existsSync(mcFile)) {
     const ledgerLines = () => {
-      const p = path.join(ROOT, '.agents', 'confirmations.jsonl');
-      const ls = (linesOf(p) || []).filter((l) => l.trim());
+      // 读法收敛 ledger-loader（2026-10-12 ledger-loader-p1）：本指标按**原始文本行**计数
+      // （total / 含 "batch" 字段的行数），故用 lines 视图而非 rows 视图。
+      const ls = readLedgerLines(ROOT);
       return { total: ls.length, withBatch: ls.filter((l) => /"batch"/.test(l)).length };
     };
     // 内置取数器：全部本地确定性、零网络。**装户零配置即用**（不依赖任何装户文件）。

package/templates/_agents/scripts/compact-ledgers.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// compact-ledgers.mjs — 台账分片归并器（2026-10-12 ledger-shard-write 配套）
+// 用途：里程碑节点或发布前，把 `.agents/confirmations.d/*.jsonl` 的分片确认行并回主台账
+//   `.agents/confirmations.jsonl` 并清理分片。`--shard` 写入的分片若长期不归并，会让台账面无限碎片化，
+//   且分片的历史不受主台账的前缀不变量约束（见 check-ledger-invariant 已知边界）——本脚本就是收敛动作。
+//
+// 保持 append-only 前缀不变量：主台账既有行**严格保序不动**，分片新行只追加到末尾——这正是
+//   check-ledger-invariant 的「旧 blob 是新 blob 的逐字节前缀」所要求的形态。绝不做重排/去重改写。
+//
+// 安全设计（三条，缺一条都可能损坏主台账）：
+//   ① 默认 dry-run：只报告「将并入 N 行」，不动盘。必须显式 execute 才写。
+//   ② 原子覆写：同目录临时文件 + rename。中途崩溃 = 主台账原样、分片未删，可安全重跑。
+//   ③ 幂等：并集按整行文本去重（复用 git-merge-jsonl 的同款判据），重复执行结果不变。
+//   任一分片读取失败 → 立即中止，主台账与全部分片保持原样。
+//
+// 用法：node .agents/scripts/compact-ledgers.mjs [--root <仓库根>] [--execute]
+import fs from 'node:fs';
+import path from 'node:path';
+import { mergeJsonlLines } from './git-merge-jsonl.mjs';
+import { LEDGER_REL, SHARD_DIR_REL } from './ledger-loader.mjs';
+
+const linesOf = (t) => (t || '').replace(/\r\n/g, '\n').split('\n').filter((l) => l.trim().length > 0);
+
+// compactLedgers(root, { execute })：纯函数形态，供测试直测。
+//   返回 { ok, skipped?, reason?, added, before, after, shards, shardLines, error? }
+export function compactLedgers(root = process.cwd(), { execute = false } = {}) {
+  const mainLedger = path.join(root, ...LEDGER_REL.split('/'));
+  const shardDir = path.join(root, ...SHARD_DIR_REL.split('/'));
+
+  if (!fs.existsSync(shardDir) || !fs.statSync(shardDir).isDirectory()) {
+    return { ok: true, skipped: true, reason: '无分片目录', added: 0, before: 0, after: 0, shards: 0, shardLines: 0 };
+  }
+  const shardFiles = fs.readdirSync(shardDir).filter((f) => f.endsWith('.jsonl')).sort();
+  if (shardFiles.length === 0) {
+    return { ok: true, skipped: true, reason: '分片目录无 .jsonl', added: 0, before: 0, after: 0, shards: 0, shardLines: 0 };
+  }
+
+  const mainBefore = fs.existsSync(mainLedger) ? fs.readFileSync(mainLedger, 'utf8') : '';
+  const mainBeforeLines = linesOf(mainBefore);
+
+  let shardCombined = '';
+  let shardLineCount = 0;
+  for (const f of shardFiles) {
+    try {
+      const t = fs.readFileSync(path.join(shardDir, f), 'utf8');
+      shardLineCount += linesOf(t).length;
+      shardCombined += '\n' + t;
+    } catch (err) {
+      // fail-soft 中止：主台账与全部分片保持原样（修好重跑即可——并集按行去重，重跑安全）
+      return { ok: false, error: `读取分片失败: ${f} (${err.message})`, added: 0, before: mainBeforeLines.length, after: mainBeforeLines.length, shards: shardFiles.length, shardLines: shardLineCount };
+    }
+  }
+
+  const merged = mergeJsonlLines(mainBefore, shardCombined);
+  const added = linesOf(merged).filter((l) => !mainBeforeLines.includes(l)).length;
+  const after = linesOf(merged).length;
+
+  if (!execute) {
+    return { ok: true, skipped: true, reason: 'dry-run', added, before: mainBeforeLines.length, after, shards: shardFiles.length, shardLines: shardLineCount };
+  }
+
+  const tmpMain = `${mainLedger}.tmp`;
+  try {
+    fs.writeFileSync(tmpMain, merged, 'utf8');
+    fs.renameSync(tmpMain, mainLedger);
+  } catch (err) {
+    try { fs.unlinkSync(tmpMain); } catch { /* tmp 可能未创建或删除失败 */ }
+    return { ok: false, error: `主台账写入失败: ${err.message}`, added: 0, before: mainBeforeLines.length, after: mainBeforeLines.length, shards: shardFiles.length, shardLines: shardLineCount };
+  }
+
+  for (const f of shardFiles) {
+    try { fs.unlinkSync(path.join(shardDir, f)); } catch { /* 残留分片不影响正确性，下轮再清 */ }
+  }
+  try { if (fs.readdirSync(shardDir).length === 0) fs.rmdirSync(shardDir); } catch { /* 忽略 */ }
+
+  return { ok: true, added, before: mainBeforeLines.length, after, shards: shardFiles.length, shardLines: shardLineCount };
+}
+
+const isMain = process.argv[1] && process.argv[1].replace(/\\/g, '/').endsWith('compact-ledgers.mjs');
+if (isMain) {
+  const argv = process.argv.slice(2);
+  const i = argv.indexOf('--root');
+  const root = path.resolve(i >= 0 && argv[i + 1] ? argv[i + 1] : process.cwd());
+  const execute = argv.includes('--execute');
+  const r = compactLedgers(root, { execute });
+
+  if (!r.ok) { console.error(`[compact-ledgers] ${r.error}`); console.error('[compact-ledgers] 已中止：主台账与分片保持原样，修好重跑即可。'); process.exit(1); }
+  if (r.skipped) { console.log(`[compact-ledgers] ${r.reason}，无需归并。`); process.exit(0); }
+  if (!execute) {
+    console.log(`[compact-ledgers] dry-run：将并入 ${r.added} 行（分片共 ${r.shardLines} 行 / ${r.shards} 个文件，其中 ${r.shardLines - r.added} 行主台账已有），主台账 ${r.before} → ${r.after} 行`);
+    console.log('[compact-ledgers] 加 --execute 执行（未加则不动盘）。');
+    process.exit(0);
+  }
+  console.log(`[compact-ledgers] ✅ 归并完成：并入 ${r.added} 行，主台账 ${r.before} → ${r.after} 行；${r.shards} 个分片已清理。`);
+  console.log('[compact-ledgers] 提醒：归并产生的台账变更请随下一笔提交入库——历史前缀不变量按提交判，不入库等于没生效。');
+  process.exit(0);
+}