agentic-flow-kit 1.7.0 → 1.7.16

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

@@ -24,6 +24,12 @@
 //   6. 子智能体角色契约 + OpenCode/Trae/ZCode Adapter 一致性(含旧委派残留/钉死模型)  [warning]
 //   7. 阶段索引同步(AGENTS.md 与 new-task.md 须双向索引全部阶段指令)                [warning]
 //   8. intent 验收标准对账(新建:done 未勾验/缺节=hard,勾选缺证据=warning;存量聚合 warning,含「存量对账豁免」声明者出账)
+//      + 场景覆盖子判据(2026-10-10 scenario-coverage,灰度 warning):同名 spec 有「验收场景」节时,
+//        done intent 验收标准须逐场景 ID 引用(场景:S1…),缺引用=warning;spec 无该节则不适用(零变化)
+//        + THEN 断言子判据(2026-10-11 then-assertion,灰度 warning):声明场景缺「- THEN」行=空壳场景,
+//          聚合一条「场景无断言」warning(THEN 是机器对账锚;节不存在=零变化)
+//        + 引用断链子判据(2026-10-11 dangling-ref,灰度 warning):验收标准引用 spec 未声明的场景 ID
+//          (含 spec 无场景节)=「场景引用断链」warning——场景未覆盖的反向对账,共用同一次解析
 //      **生效日锚=git 首次加入日期(2026-09-28 改;此前取文件名前 10 字符——命名规范强制的字段、
 //      写早零成本,一条 hard 门可被平凡绕过;incident 2026-09-28-check8-git-anchor 实证)**:
 //      非 git / 查不到加入记录 → 不可判定 → 走存量口径(不误报 hard)
@@ -31,6 +37,8 @@
 //   9. 文件名英文 kebab-case(非 ASCII 文件名=warning,2026-09-11 规则)
 //  10. 级别 vs 迁移文件一致性(L1/L2 入口文档加入提交触及迁移 SQL/Migrations=疑似判低,warning)
 //  11. 生成物漂移：workflow/INDEX.md(2026-09-21 检索层) + workflow/DASHBOARD.md(2026-10-08 扩覆盖面)=warning;
+//      wiki 侧（wiki/INDEX.md + 看板 DATA）由 doctor §6b 经 gen-wiki-board --check 校验，不在此重复
+//      （2026-10-10：wiki 生成区此前零机器校验，现与 workflow 侧对称为 doctor 单路）；
 //  12. frontmatter「模块:」合法性(枚举非法 / 2026-09-22 起新建缺字段=warning;词表单源 .agents/workflow-modules.txt)
 //  13. 常驻面体积预算(超限=warning;判定单源 rule-budget.sh——经 sh 调用,
 //      无 sh 环境静默跳过:advisory 级且 pre-commit 侧在 git 钩子 sh 环境照常硬拦)
@@ -118,8 +126,10 @@ import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { loadEnums } from './workflow-enums.mjs';
 import { runCheck16 } from './check-metric-claims.mjs';
-import { auditEnabled, loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, scopeMatches } from './policy.mjs';
+import { auditEnabled, loadKitPolicy, hasFreshVerifyLine, ledgerChainHash, ledgerDocChainActive, scopeMatches } from './policy.mjs';
 import { laneOfEntry } from './stage-gates.mjs';
+import { readLedgerRows, readLedgerEntries, LEDGER_REL } from './ledger-loader.mjs';
+import { prunedHashes as prunedHashesOf } from './ledger-prune.mjs';
 // MARK_RE：incident 留痕形态的单源（第七轮复核 N3——此前 check-loop 内联复制一份同口径字面量，
 // 两处靠注释与人工同步；改为复用 stage-gates.mjs 的导出，从结构上消除漂移可能）
 import { MARK_RE, approvedTraceHit } from './stage-gates.mjs';
@@ -156,7 +166,7 @@ function takeOpts() {
   return opts;
 }
 
-// ---- runCheckLoop：门禁主流程可 import 化（2026-10-08 checkloop-importable；papercuts 2026-10-04 isMain 行点名单独立项）----
+// ---- runCheckLoop：门禁主流程可 import 化（2026-10-08 checkloop-importable；2026-10-04 isMain 行点名单独立项）----
 // import 本模块零副作用（isMain 主守卫，board-kb-p1 先例）；opts = { root?, rev?, hardening? }——root 显式参数
 // 优先于 CHECK_LOOP_ROOT env 优先于 git toplevel（CLI 缺省行为逐字节不变）；返回 { exitCode, blockers, warnings }，
 // 输出打印照旧在本函数内（稳定输出契约：banner 后空行、条目 `- ` 前缀、HARD-BLOCK/WARN 两段式——消费者 .githooks/pre-push）。
@@ -168,7 +178,7 @@ function takeOpts() {
 
 // writeGateStats：门禁 ROI 落盘（2026-10-08 gate-roi-metrics）——append 一行到
 // <root>/.agents/cache/gate-stats.jsonl（该目录已 gitignore，属运行时数据、不入 git、不进 kit.json
-// managed 台账——刻意避开 papercuts 2026-10-05 探针临时件被 sync 收编的事故面）。
+// managed 台账——刻意避开 2026-10-05 探针临时件被 sync 收编的事故面）。
 // IO 失败只出账不阻断（沿 verify.mjs 凭证落账同款容错——度量失败不该让门禁变成红灯）。
 export function writeGateStats(root, segs) {
   try {
@@ -325,6 +335,18 @@ export function runCheckLoop(opts = {}) {
     return '';
   }
 
+  // 落点空壳告警（2026-10-11 landing-reality，沉淀追踪第三级，incident/intent 两侧共用）：
+  //   「沉淀: <路径>」存在 ≠ 有效——文件存在但 sedimentLandingIsShell 为真（无来源 frontmatter
+  //   且非占位正文不足 3 行）→ WARN 落点空壳（advisory，灰度第一档）。调用方须先出过「沉淀断档」
+  //   分支（文件不存在），故此处 readFileSync 异常 = 真读取故障，按空壳出账并在文案注明读取失败。
+  const warnSedimentShell = (single, sed) => {
+    let text = null;
+    try { text = fs.readFileSync(path.resolve(ROOT, sed), 'utf8'); } catch { text = null; }
+    if (!sedimentLandingIsShell(text)) return;
+    const readFail = text === null ? '；落点文件读取失败' : '';
+    warnings.push(`- [WARN 落点空壳] ${single} frontmatter「沉淀: ${sed}」指向的文件存在但无有效内容（无来源 frontmatter 且非占位正文不足 3 行${readFail}）——沉淀须真实整理而非空壳占位（advisory，灰度第一档）`);
+  };
+
   const WF = 'workflow';
   const DOC_DIRS = ['intents', 'specs', 'plans', 'incidents'];
   const blockers = [];
@@ -459,9 +481,25 @@ export function runCheckLoop(opts = {}) {
     }
 
     // 三件套：正文行锚定 /^1\. /^2\. /^3\. （sh awk 同款）
+    let trioOk = true;
     for (const n of [1, 2, 3]) {
       if (!lines.some((l) => l.startsWith(`${n}. `))) {
         warnings.push(`- [WARN 三件套不全] ${name} 缺复盘三件套之 ${n}`);
+        trioOk = false;
+      }
+    }
+    // 沉淀追踪（incident 侧，与检查 8 intent 侧对称）：closed 且三件套齐全 = 最高价值沉淀源。
+    //   frontmatter「沉淀: <相对仓根路径>」登记去向；缺登记 → WARN 未沉淀（advisory，灰度第一档）；
+    //   登记了但文件不存在 → WARN 沉淀断档；存在但空壳（无来源且非占位正文不足 3 行）→ WARN 落点空壳。
+    //   同「沉淀: 无」显式豁免口径。
+    if (incSt === 'closed' && trioOk) {
+      const sed = fmGet(inc, '沉淀');
+      if (!sed) {
+        warnings.push(`- [WARN 未沉淀] ${name} 复盘三件套齐全（closed）但未登记沉淀去向——整理到 wiki 后在 frontmatter 记「沉淀: wiki/<主题>/<文件>」，或显式写「沉淀: 无」（advisory，灰度第一档；沉淀是人工判断，机器只提醒不强制）`);
+      } else if (sed !== '无' && !fs.existsSync(path.resolve(ROOT, sed))) {
+        warnings.push(`- [WARN 沉淀断档] ${name} frontmatter「沉淀: ${sed}」指向的文件不存在——沉淀文件移动/改名后须同步更新本字段（advisory，灰度第一档）`);
+      } else if (sed !== '无') {
+        warnSedimentShell(name, sed); // 落点真实性（P1-3）：存在但空壳 → WARN 落点空壳
       }
     }
     const hasParent = lines.some((l) => l.includes('是否需要新 intent'));
@@ -742,7 +780,7 @@ export function runCheckLoop(opts = {}) {
   // --- 8. intent 验收标准对账（done 须逐条勾验并补证据；新建 hard，存量聚合 warning）---
   markGate('8', '验收标准对账');
   // 生效日锚 2026-09-28 改「git 首次加入日期」（此前取文件名前 10 字符——命名规范强制的字段、
-  // 写早零成本，见 incidents/2026-09-28-check8-git-anchor）。非 git → 不可判定 → 走存量口径（不误报 hard）。
+  // 写早零成本）。非 git → 不可判定 → 走存量口径（不误报 hard）。
   {
     const accCutoff = '2026-09-12';
     let legacyUnaccounted = 0;
@@ -769,16 +807,10 @@ export function runCheckLoop(opts = {}) {
     const doneTsOf = (() => {
       const map = new Map();
       try {
-        const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-        if (fs.existsSync(lp)) {
-          for (const line of fs.readFileSync(lp, 'utf8').split(/\r?\n/)) {
-            if (!line.trim()) continue;
-            try {
-              const e = JSON.parse(line);
-              // append-only 取末次 done 跳转（同一 doc 多次 done 取最后一条 ts）
-              if (e && e.doc && ['done', 'closed'].includes(e.stage)) map.set(e.doc, e.ts || '');
-            } catch { /* 坏行跳过（同检查 15 口径） */ }
-          }
+        // 读法收敛 ledger-loader（2026-10-12 ledger-loader-p1）：末次 done 跳转取自物理读序，
+        // loader 保持读序返回故「取末次」语义与逐处直读一致（分片按文件名序排在主台账之后＝较新）
+        for (const e of readLedgerRows(ROOT)) {
+          if (e && e.doc && ['done', 'closed'].includes(e.stage)) map.set(e.doc, e.ts || '');
         }
       } catch { /* 台账不可读 → 无锚 → 全走全局布尔（fail-open，不误报 hard） */ }
       return map;
@@ -877,6 +909,65 @@ export function runCheckLoop(opts = {}) {
         else if (!ex) legacyUnaccounted++;
         continue;
       }
+      // 场景覆盖子判据（2026-10-10 scenario-coverage，灰度第一档 = warning）：
+      //   同名 spec 写了「## 验收场景」节（GIVEN/WHEN/THEN，每条带 ID：S1、S2…）时，
+      //   done intent 的验收标准须**逐场景 ID 引用**（`场景：S1`）。缺引用只出 warning——
+      //   有意不进 hard：新判据先灰度观察存量装户告警噪音，沿检查 8 自身 / 检查 15 / 检查 18
+      //   「先 WARN、装户吃过警告后升 FAIL」的既有路径；spec 无该节 = 原判据零变化。
+      //   ID 提取单源 = 本块（spec 侧），引用匹配只认验收标准节内的 `场景：S<n>` 行。
+      // 引用断链子判据（2026-10-11 dangling-ref，P2-1，灰度第一档 = warning）：
+      //   上判据的**反向对账**——验收标准引用了 spec 未声明的场景 ID = 悬空引用（改 ID 漏改 / 复制粘贴
+      //   残留的机器信号）；spec 无场景节但引用了 S<n> 同样算断链（引用了不存在的场景）。与「场景未覆盖」
+      //   共用同一次 ID 解析与引用遍历（covered 一份两用），不重复解析。
+      // THEN 断言子判据（2026-10-11 then-assertion，P2-2，灰度第一档 = warning）：
+      //   声明了场景却无 THEN 断言行 = 空壳场景——THEN 是可观测结果的机器对账锚（GIVEN/WHEN 可省），
+      //   聚合一条不逐场景刷屏；验收场景节本身可选，节不存在 → 零变化。
+      const specPath = path.join(ROOT, WF, 'specs', base);
+      if (fs.existsSync(specPath)) {
+        const sids = scenarioIdsOf(specPath);
+        // 引用遍历单次（覆盖/断链两方向共用）：不锁进 sids.length 分支——spec 无场景节时引用同样悬空
+        const covered = new Set();
+        for (const line of lines) {
+          const m = line.match(/场景[：:]\s*S(\d+)/);
+          if (m) covered.add(`S${m[1]}`);
+        }
+        if (sids.length) {
+          const missing = sids.filter((id) => !covered.has(id));
+          if (missing.length) {
+            warnings.push(`- [WARN 场景未覆盖] ${base} 同名 spec 有验收场景但验收标准未逐场景引用：缺 ${missing.join('、')}——在「## 验收标准」按「- [x] 场景：S<n> <判据>（证据：…）」补齐（advisory，灰度第一档；不写场景节的 spec 不适用）`);
+          }
+          // THEN 对账需 spec 全文（scenarioIdsOf 只回 ID）；读取失败 = 不可判定 → 跳过不误报（fail-open）
+          let thenMap = null;
+          try { thenMap = extractThenByScenario(fs.readFileSync(specPath, 'utf8')); } catch { /* 极窄竞态，不判空壳 */ }
+          if (thenMap) {
+            const noThen = sids.filter((id) => !(thenMap.get(id) || []).length);
+            if (noThen.length) {
+              warnings.push(`- [WARN 场景无断言] ${base} 同名 spec 场景缺 THEN 断言：${noThen.join('、')}——每场景至少一行「- THEN <可观测结果>」（GIVEN/WHEN 可省；advisory，灰度第一档）`);
+            }
+          }
+        }
+        const dangling = [...covered].filter((id) => !sids.includes(id));
+        if (dangling.length) {
+          warnings.push(`- [WARN 场景引用断链] ${base} 验收标准引用了 spec 未声明的场景 ID：${dangling.join('、')}——修正 ID 或在 spec「## 验收场景」补该场景（advisory，灰度第一档）`);
+        }
+      }
+      // 沉淀追踪子判据（2026-10-10 sediment-tracking，灰度第一档 = warning）：
+      //   intent 高价值节（影响面 / 触达红线）是 wiki 沉淀的主源——frontmatter「沉淀: <相对仓根路径>」
+      //   登记去向（如 wiki/项目规范/xxx.md），「沉淀: 无」= 显式声明不沉淀。缺登记且内容高价值
+      //   → WARN 未沉淀（advisory：沉淀是人工判断，机器只提醒不强制，不进 hard）；登记了但文件
+      //   不存在 → WARN 沉淀断档（路径漂移）；存在但空壳（无来源且非占位正文不足 3 行）→ WARN 落点
+      //   空壳（2026-10-11 landing-reality，P1-3 落点真实性）。高价值判据 = 两节之一有非占位正文内容。
+      //   incident 侧对称（检查 3 内）：closed 且复盘三件套齐全 = 最高价值沉淀源，同款提醒。
+      //   有意不加 policyVersion 锚：字段缺失 = 未登记，无字段语义零变化（沿场景覆盖子判据同款口径）。
+      const sed = fmGet(intent, '沉淀');
+      const highValue = sectionHasBody(lines, '影响面') || sectionHasBody(lines, '触达红线');
+      if (highValue && !sed) {
+        warnings.push(`- [WARN 未沉淀] ${base} 含高价值沉淀内容（影响面/触达红线）但未登记沉淀去向——整理到 wiki 后在 frontmatter 记「沉淀: wiki/<主题>/<文件>」，或显式写「沉淀: 无」（advisory，灰度第一档；沉淀是人工判断，机器只提醒不强制）`);
+      } else if (sed && sed !== '无' && !fs.existsSync(path.resolve(ROOT, sed))) {
+        warnings.push(`- [WARN 沉淀断档] ${base} frontmatter「沉淀: ${sed}」指向的文件不存在——沉淀文件移动/改名后须同步更新本字段（advisory，灰度第一档）`);
+      } else if (sed && sed !== '无') {
+        warnSedimentShell(base, sed); // 落点真实性（P1-3）：存在但空壳 → WARN 落点空壳
+      }
       if (!uc && !ne) continue;
         if (isNew) {
           if (uc) blockers.push(`- [验收未对账] done intent 验收标准有未勾验项:${base}（逐条勾验并补证据：commit/用例/冒烟输出）`);
@@ -929,15 +1020,8 @@ export function runCheckLoop(opts = {}) {
     // 台账 approved 文档集合：单次读取（坏行容忍跳过，与检查 15 同口径）；缺失视为空集（git 判据仍守门）
     const ledgerApproved = new Set();
     try {
-      const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-      if (fs.existsSync(lp)) {
-        for (const line of fs.readFileSync(lp, 'utf8').split(/\r?\n/)) {
-          if (!line.trim()) continue;
-          try {
-            const e = JSON.parse(line);
-            if (e && typeof e.doc === 'string' && e.stage === 'approved') ledgerApproved.add(e.doc);
-          } catch { /* 坏行容忍跳过 */ }
-        }
+      for (const e of readLedgerRows(ROOT)) {
+        if (typeof e.doc === 'string' && e.stage === 'approved') ledgerApproved.add(e.doc);
       }
     } catch { /* 台账不可读视为无 approved 行 */ }
     for (const sub of ['specs', 'plans']) {
@@ -976,18 +1060,26 @@ export function runCheckLoop(opts = {}) {
   // 台账坏行容忍跳过（审计件，jsonl 追加式）；frontmatter 存 16 位、台账存 64 位，按前 16 位配对。
   {
     const EFFECTIVE = kitPolicy.confirmDocsEffective;
-    const ledgerPath = path.join(ROOT, '.agents', 'confirmations.jsonl');
+    // 取数走 ledger-loader 的**带来源行号视图**（2026-10-12 ledger-shard-write）：主台账 + 分片
+    // `.agents/confirmations.d/*.jsonl`。分片里的行同样受链校验——否则 `--shard` 写入就等于给台账开了
+    // 一个防伪盲区（门禁看得见分片行、却不验它们的链）。
+    // **此处曾刻意不走 loader**（单源化时留的例外，因当时要物理行号对齐）；引入分片后该理由已不成立
+    // ——单一行号跨来源无法定位，故改用带 rel 的定位。第二处例外仍是 check-ledger-invariant.mjs
+    // （它审的是**盘面字节**的 append-only 前缀不变量，不是台账语义，见该文件头部）。
     const ledger = [];
-    const ledgerBadLines = []; // 坏行（JSON.parse 失败）的物理行号（复核 P2-1：报文行号须对齐物理行）
-    if (fs.existsSync(ledgerPath)) {
-      for (const [lineNo, line] of (linesOf(ledgerPath) || []).entries()) {
-        if (!line.trim()) continue;
-        try { ledger.push(JSON.parse(line)); } catch { ledgerBadLines.push(lineNo + 1); }
-      }
+    const ledgerRefs = [];   // 与 ledger 同下标：{rel, no}——断裂报文的定位来源
+    for (const e of readLedgerEntries(ROOT)) {
+      if (e.row === null) continue; // 坏行跳过（容错口径同前；它占物理行号但不入 ledger 下标）
+      ledger.push(e.row);
+      ledgerRefs.push({ rel: e.rel, no: e.no });
     }
-    // 台账哈希链校验（2026-10-09 engine-quality-round2 D；写入侧=confirm-doc appendLedger，哈希单源
-    // policy.ledgerChainHash——判定零复刻）。判据：连续带 hash 行段内，① prevHash 须等于前一带 hash
-    // 行的 hash（无 hash 行后链段重启 ''，与写入侧读末行口径一致）；② hash 须可重算一致。
+    // 台账哈希链校验（2026-10-09 engine-quality-round2 D；2026-10-12 ledger-doc-chain 改链域；
+    // 写入侧=confirm-doc appendLedger，哈希单源 policy.ledgerChainHash——判定零复刻）。
+    // **链域已从「文件物理序」改为「按 doc 的逻辑序」**（锚后生效，理由与不追溯口径见 POLICIES v8）：
+    //   原判据 ① prevHash = 前一带 hash 行（物理）的 hash；新判据 ① = **同行 doc** 最后一个带 hash 行的
+    //   hash。两者都要求 ② hash 可重算一致。无 hash 行仍按「链段重启」处理。
+    //   并发 append / git 并集合并 / 分片归并这三种**正常协作**都会打断物理链——门禁若继续据此 hard 拦，
+    //   必然被 --no-verify 绕过，治理失效；而 doc 链对就地改行 / 删行 / 插行三类篡改的检出能力不变。
     // **坏行口径（复核 P2-1 勘误，此前注释误称「与写入侧一致」）**：坏行被本解析整体剔除、不重置游标
     // ——坏行后写入的链行（写入侧读末行遇坏行 prevHash=''）验链必失配出账。这是**预期 fail-loud**
     // （坏行本身即台账完整性事故，应人工查验），非口径一致场景。
@@ -998,19 +1090,36 @@ export function runCheckLoop(opts = {}) {
       let prevHash = '';
       let brokenAt = 0;
       let brokenCount = 0;
+      // 链域分界（2026-10-12 ledger-doc-chain）：doc 链锚存在且合法时，**按行分域**验链——
+      //   锚前行（ts < 锚）维持物理链口径（存量零变化）；锚后行（ts ≥ 锚）按「同行 doc 的最后一个
+      //   带 hash 行」接续，并同样要求 hash 可重算一致。锚缺键（v1-v7）→ 全表走物理链（= 旧行为）。
+      // byDoc 对**两种域的行都更新**：锚后行需要接到锚前该 doc 的最后一行，跨域才能连续。
+      const docChainOn = ledgerDocChainActive(kitPolicy);
+      const docChainSince = docChainOn ? kitPolicy.ledgerDocChainSince : '';
+      const byDoc = new Map();
+      const prunedHashSet = prunedHashesOf(ROOT); // 特许修剪凭据（无 manifest 时为空集，零 IO 成本）
       ledger.forEach((row, idx) => {
         if (!row || typeof row.hash !== 'string') { prevHash = ''; return; } // 存量行/无链字段 → 链段重启
         const { hash, prevHash: p, ...rest } = row;
-        const ok = (p ?? '') === prevHash && ledgerChainHash(rest, p ?? '') === hash;
+        const inDocChain = docChainOn && typeof row.ts === 'string' && row.ts >= docChainSince;
+        const expected = inDocChain ? (byDoc.get(row.doc) ?? '') : prevHash;
+        // 特许修剪链段重启（2026-10-12 ledger-prune-manifest）：删掉某 doc 的链行后，其后继行仍带被删行
+        //   的 prevHash，而该行已不在表内 → 必然失配。本行的 prevHash 若出现在 manifest 声明的被删哈希里，
+        //   即视为**有凭据的合法重启点**而非篡改（凭据 = .agents/ledger-prune-manifest.json，入库可对质）。
+        const prunedRestart = (p ?? '') !== expected && prunedHashSet.has(p ?? '');
+        const ok = ((p ?? '') === expected || prunedRestart) && ledgerChainHash(rest, p ?? '') === hash;
         if (!ok) {
-          if (!brokenAt) brokenAt = idx + 1;
+          if (!brokenAt) brokenAt = idx + 1; // 1-based 下标，供 ledgerRefs 定位
           brokenCount++;
         }
         prevHash = hash;
+        if (typeof row.doc === 'string') byDoc.set(row.doc, hash);
       });
       if (brokenAt) {
-        const physical = brokenAt + ledgerBadLines.filter((n) => n <= brokenAt).length; // 物理行号（复核 P2-1：剔除坏行会令数组下标漂移）
-        blockers.push(`- [台账链断裂] confirmations.jsonl 自第 ${physical} 行（物理）起哈希链校验失败（共 ${brokenCount} 行不一致——append-only 台账出现就地改/删痕迹；prevHash 接续或内容重算不符。整文件重写不可机器防，对质走台账自身 git 历史）`);
+        // 定位用 ledgerRefs（来源 + 行号）：跨来源后单一行号无法定位；坏行占位不计入 ledger 下标
+        const at = ledgerRefs[brokenAt - 1] || { rel: LEDGER_REL, no: brokenAt };
+        const domain = docChainOn ? '锚前物理链 / 锚后 doc 链' : '物理链';
+        blockers.push(`- [台账链断裂] 自 ${at.rel}:${at.no} 起哈希链校验失败（${domain}，共 ${brokenCount} 行不一致——append-only 台账出现就地改/删痕迹；prevHash 接续或内容重算不符。整文件重写不可机器防，对质走台账自身 git 历史）`);
       }
     }
     // scope 子项（2026-10-09 审查 A1 干净版）：受管台账行须带**机器派生**的改动面 scope{files,sha256}。
@@ -1137,7 +1246,7 @@ export function runCheckLoop(opts = {}) {
         if (rows.every((r) => r.brief === true)) continue;
         const of = Math.max(...rows.map((r) => (typeof r.of === 'number' ? r.of : 0)));
         const docs = rows.map((r) => String(r.doc).replace(/^workflow\//, '')).join('、');
-        warnings.push(`- [WARN 确认并录] 单次调用落账 ${rows.length} 份（batch ${b}，of=${of}）：${docs}——同一次 --delegated 调用放行多份，塌掉「逐件确认」门（build.md）；口径见 workflow/papercuts.md 2026-09-28 与 incidents/2026-09-28-batch-ledger-audit.md`);
+        warnings.push(`- [WARN 确认并录] 单次调用落账 ${rows.length} 份（batch ${b}，of=${of}）：${docs}——同一次 --delegated 调用放行多份，塌掉「逐件确认」门（build.md；口径见根 AGENTS.md「门禁与提交」确认门节）`);
       }
     }
   }
@@ -1240,13 +1349,7 @@ export function runCheckLoop(opts = {}) {
     if (typeof since === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(since)) {
       const ledgerRows = [];
       {
-        const lp = path.join(ROOT, '.agents', 'confirmations.jsonl');
-        if (fs.existsSync(lp)) {
-          for (const line of linesOf(lp) || []) {
-            if (!line.trim()) continue;
-            try { ledgerRows.push(JSON.parse(line)); } catch { /* 坏行跳过（同检查 15 口径） */ }
-          }
-        }
+        for (const e of readLedgerRows(ROOT)) ledgerRows.push(e);
       }
       const hasRow = (rel) => ledgerRows.some((e) => e && e.doc === rel && (e.stage === 'approved' || e.stage === 'done'));
       const docConfirmed = (rel, abs) => {
@@ -1556,3 +1659,110 @@ function readdirOrNull(dir) {
 function isDirectoryOrNull(p) {
   try { return fs.statSync(p).isDirectory(); } catch { return false; }
 }
+
+// 场景 ID 提取（2026-10-10 scenario-coverage，检查 8 场景覆盖子判据的 spec 侧单源）：
+//   认「## 验收场景」节内的场景声明——三级标题 `### S1 <名>` 或列表项 `- S1 <名>`，
+//   提取 S<n> 形 ID（按出现序去重）。节外不认（防「## 功能行为」里偶然出现的 S1 干扰）。
+//   无该节 / 无场景声明 → 空数组（调用方按「不适用」跳过，原判据零变化）。
+//   独立 export 供单元测试直测（纯函数：只吃文件路径、只读）。
+export function scenarioIdsOf(specPath) {
+  let lines;
+  try { lines = fs.readFileSync(specPath, 'utf8').split(/\r?\n/); } catch { return []; }
+  const ids = [];
+  let inSec = false;
+  for (const line of lines) {
+    if (/^\s*##\s+[^#]*验收场景/.test(line)) { inSec = true; continue; }
+    if (inSec && /^\s*##\s/.test(line)) break; // 下一二级标题 = 节末
+    if (!inSec) continue;
+    const m = line.match(/^\s*(?:###|-)\s*\**S(\d+)\b/i);
+    if (m && !ids.includes(`S${m[1]}`)) ids.push(`S${m[1]}`);
+  }
+  return ids;
+}
+
+// THEN 断言抽取（2026-10-11 then-assertion，检查 8「场景无断言」子判据的 spec 侧单源）：
+//   输入 spec 全文，定位「## 验收场景」节（节定位正则与 scenarioIdsOf 同款——口径单源，改写法时两处同步），
+//   按场景块分组（`### S1 <名>` 三级标题或 `- S1 <名>` 列表项，声明正则同 scenarioIdsOf），抽块内 THEN 断言行。
+//   行匹配口径：剥缩进后以 `- THEN` 开头（模板规定形式）；`THEN:` / `THEN `（无连字符）也认——
+//   防「写了断言但少了 `- ` 前缀」的写法漂移把断言误判为空；只认行首 THEN，GIVEN/WHEN 行中段的
+//   "THEN" 字样不误抽。返回 Map<S-ID, string[]>（声明即建键，无 THEN = 空数组——空壳判定交给调用方）；
+//   节不存在 / 非字符串输入 → 空 Map（验收场景节本身可选，调用方零变化）。
+//   独立 export 供单元测试直测（纯函数：只吃文本、无 IO）。
+export function extractThenByScenario(text) {
+  const byScen = new Map();
+  if (typeof text !== 'string') return byScen; // 读取失败（调用方传 null）→ 空 Map，调用方按不可判定跳过
+  const lines = text.split(/\r?\n/);
+  let cur = null; // 当前场景块 ID（null = 尚未进入任何场景块，节头说明行不算断言）
+  let inSec = false;
+  for (const line of lines) {
+    if (/^\s*##\s+[^#]*验收场景/.test(line)) { inSec = true; continue; }
+    if (inSec && /^\s*##\s/.test(line)) break; // 下一二级标题 = 节末
+    if (!inSec) continue;
+    const decl = line.match(/^\s*(?:###|-)\s*\**S(\d+)\b/i);
+    if (decl) {
+      const id = `S${decl[1]}`;
+      if (!byScen.has(id)) byScen.set(id, []);
+      cur = id;
+      continue;
+    }
+    if (cur === null) continue;
+    const s = line.trim();
+    if (/^-\s*THEN\b/i.test(s) || /^THEN\b/i.test(s)) byScen.get(cur).push(s);
+  }
+  return byScen;
+}
+
+// 节体非空判定（2026-10-10 sediment-tracking，检查 8 沉淀追踪子判据的「高价值」信号）：
+//   认 `## <标题前缀>` 节内**标题之后**存在非空非占位行（占位 = `<…>` 单行包揽 / HTML 注释 / 引用）。
+//   只有光标题（如模板未填的 `## 影响面`）= 未沉淀价值，不出告警——防模板未填段被误判为高价值。
+//   前缀匹配（startsWith）：兼容「## 影响面」「## 影响面与边界」等变体写法。
+//   独立 export 供单元测试直测（纯函数：只吃行数组、无 IO）。
+export function sectionHasBody(lines, headingPrefix) {
+  let inSec = false;
+  for (const line of lines) {
+    if (/^\s*##\s/.test(line)) {
+      const t = line.replace(/^\s*##\s*/, '').trim();
+      inSec = t.startsWith(headingPrefix);
+      continue;
+    }
+    if (!inSec) continue;
+    const s = line.trim();
+    if (!s) continue;
+    if (/^<.*>$/.test(s) || s.startsWith('<!--') || s.startsWith('>')) continue; // 占位 / 注释 / 引用
+    return true;
+  }
+  return false;
+}
+
+// 沉淀落点空壳判定（2026-10-11 landing-reality，「存在 ≠ 有效」的落点真实性一环）：
+//   落点文件可能是只有标题没有内容的空壳。满足任一即**非**空壳（有效沉淀）：
+//   ① frontmatter 含「来源:」键（人工已登记来源 = 真实整理的机器信号；frontmatter 口径同 fmGet 受限子集）；
+//   ② frontmatter / 标题行 / 占位行剔除后的非空正文 ≥ 3 行（占位口径逐字对齐 sectionHasBody：
+//     `<…>` 单行包揽 / HTML 注释 / 引用块）——标题行不算正文，防「只有标题」凑行数绕过。
+//   text = 落点文件全文；非字符串（调用方读取失败传 null）按空壳处理，调用方在告警文案注明读取失败。
+//   独立 export 供单元测试直测（纯函数：只吃文本、无 IO）。
+export function sedimentLandingIsShell(text) {
+  if (typeof text !== 'string') return true; // 读取失败 → 按空壳
+  const lines = text.split(/\r?\n/);
+  const isDelim = (l) => /^---\s*$/.test(l); // 同 fmGet：首行 --- 进入、下一 --- 闭合
+  let inFm = isDelim(lines[0] || '');
+  if (inFm) {
+    for (let i = 1; i < lines.length; i++) {
+      if (isDelim(lines[i])) break; // 下一 --- = frontmatter 闭合
+      if (lines[i].startsWith('来源:')) return false; // ① 有来源登记 = 有效
+    }
+  }
+  let body = 0;
+  for (let i = inFm ? 1 : 0; i < lines.length; i++) {
+    if (inFm) {
+      if (isDelim(lines[i])) inFm = false; // frontmatter 闭合，其后才开始数正文
+      continue;
+    }
+    const s = lines[i].trim();
+    if (!s) continue;
+    if (s.startsWith('#')) continue; // 标题行 = 结构不算正文（空壳 = 只有标题没有内容）
+    if (/^<.*>$/.test(s) || s.startsWith('<!--') || s.startsWith('>')) continue; // 占位 / 注释 / 引用（同 sectionHasBody）
+    if (++body >= 3) return false; // ② 非占位正文 ≥ 3 行 = 有效
+  }
+  return true;
+}