@thincoder/core 0.10.12 → 0.11.1

package/agent-tools/advisor.mjs

@@ -8,6 +8,8 @@
  * blocking review); depth>0 (eng-coder self-review) stays synchronous always.
  */
 import { runAdvisorReview, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
+import { readFileSync } from "node:fs"
+import { countRoundBlocks } from "./batch-skeleton.mjs"
 import { resolveBatchDocPath } from "./batch.mjs"
 // 设计评审的文档受理面单源 = review-facts.mjs 的 resolveReviewDocPaths（判据正文 =
 // docs/core/design/ADVISOR-GUARDS.md §12：相对形按会话项目根 / 绝对形照用 / 受理 = 项目内现存 `.md`）。
@@ -22,7 +24,10 @@ import {
 } from "./advisor-async.mjs"
 // F30/F31（2026-09-18 顾问面治理批）：类型门判定 / 拒发串 / 对象标识行——单源 `advisor/notice.mjs`
 // （文案逐字 = ADVISOR-GUARDS.md §2.4 / §2.5）；零计数载体（计数护栏随撤 cap 整体退场）。
-import { typeGateCriterion, buildTypeGateRefusal, scopeSummary, withIdentityLine } from "../advisor/notice.mjs"
+import { typeGateCriterion, buildTypeGateRefusal, identityLine, scopeSummary, withIdentityLine } from "../advisor/notice.mjs"
+// 账链门判据（设计单源 = `docs/core/design/ADVISOR-GUARDS.md` §2 第 7 条）：批档之外还须有未决台账行指着它。
+// 判据档零静态仓内依赖（台账链在档内动态 import——W8 契约②），故本档可静态引用。
+import { resolveBatchLedgerLink } from "./batch-ledger-link.mjs"
 // #15 描述外置：描述文本单点 = tool-docs/advisor.md（DESC 单解析面，缺档抛错语义不变）
 import { DESC } from "../tools/shared.mjs"
 
@@ -31,6 +36,74 @@ import { DESC } from "../tools/shared.mjs"
 // here for the tests' import surface (implementation re-exported).
 export { validateDesignToken } from "./advisor-async.mjs"
 
+/**
+ * §3 点火基线（`docs/core/design/ADVISOR-GUARDS.md` §1.1 判据 1）：绑了批档 ⇒ 记下点火时该档 §3
+ * 已有的轮次块数（块计数单源 = `countRoundBlocks`）；未绑 / 读不到 ⇒ `null`——读不到不等于
+ * 「没有记录要验」，结算面的 §3 落地门据此判 `batch-unreadable`。每轮发起刷新：同一实例的修轮
+ * 是新的一轮，基线随之推进（否则上一轮留下的块会让本轮一字未写也过门）。
+ */
+function section3BlocksBaseline(batchDocAbs) {
+  if (typeof batchDocAbs !== "string" || !batchDocAbs) return null
+  try {
+    return countRoundBlocks(readFileSync(batchDocAbs, "utf8"), 3)
+  } catch {
+    return null
+  }
+}
+
+/** `batchDoc` 缺失形态（缺失 ∥ `null` ∥ 空串 ∥ 纯空白——非字符串不在此判，留给 `resolveBatchDocPath` 的既有文案）。 */
+function missingBatchDoc(raw) {
+  return raw === undefined || raw === null || (typeof raw === "string" && raw.trim() === "")
+}
+
+/**
+ * 设计评审准入门拒文（**逐字**——单源 `docs/core/design/ADVISOR-GUARDS.md` §2 第 6 条）：首行 = 稳定前缀
+ * `Advisor: launch refused` + 标识行（与类型门同族形态）；其后 Why + 两个期望形 + 可执行的下一步 + 收尾句。
+ * 与类型门的唯一形态偏差 = 多一句「没有批档 ⇒ 先建档」：本门判的是「参数在不在」，用户知道怎么传不等于
+ * 知道没档时怎么办。
+ */
+function buildBatchDocRefusal(identity) {
+  return [
+    `Advisor: launch refused — a design review must carry \`batchDoc\`: the batch record this review belongs to. ${identity}`,
+    "Why: the token a design review issues is closed by its batch — closing that record consumes it. A review with no batch mints a token nothing can close: it rides the 7-day TTL and nothing else. Refusing the review at launch is how that token never exists.",
+    "Expected form 1 — project-root-relative: docs/batches/<batch>-<topic>.md (resolved against the session project root).",
+    "Expected form 2 — absolute: D:\\repo\\docs\\batches\\<batch>-<topic>.md (used as-is).",
+    'No batch record in flight: create one first — batch({action:"create", …}) — one command; the record is the premise of the review, not paperwork.',
+    "Nothing was sent: no review instance, no round consumed, no design token minted, no LLM call.",
+  ].join("\n")
+}
+
+/**
+ * 账链门拒文（**逐字**——单源 `docs/core/design/ADVISOR-GUARDS.md` §2 第 7 条）：首行 = 稳定前缀
+ * `Advisor: launch refused` + 标识行（与准入门同族形态）；其后 Why + `Record:` 读数 + 三条修法 + 收尾句。
+ *
+ * 偏差（相对准入门）= 判据从「参数在不在」进到「账在不在」，因此多一行 `Record:` 读数值：让下一步可判——
+ * 是行丢了（`db: open` ∧ `unsettled: 0`），还是库根本不在盘（`db: not on disk`，Fix 1 无行可改）。
+ */
+function buildBatchNoLedgerRefusal({ batchDocAbs, chain, scope }) {
+  const dbText = chain.db === "open"
+    ? `open at ${chain.dbFile}`
+    : chain.db === "not-on-disk"
+      ? `not on disk at ${chain.dbFile}`
+      : chain.db === "unreadable"
+        ? `unreadable at ${chain.dbFile}`
+        : "—" // 无项目根：没有库位可点名（`ledger base: —` 同因）
+  return [
+    `Advisor: launch refused — a design review needs its batch record to carry an unsettled ledger row. ${identityLine({
+      type: "design",
+      scope,
+      round: "—", // 判定先于实例解析——本次发起无轮次（§2 第 5 条字段行）
+      criterion: "batchdoc-no-ledger",
+    })}`,
+    `Why: the record says the work is in flight, the ledger says whose work it is — and no unsettled row points at this record (reason=${chain.reason}).`,
+    `Record: ${batchDocAbs} — ledger base: ${chain.root ?? "—"} · db: ${dbText} · rows whose task_book resolves here: ${chain.rows} (unsettled: ${chain.unsettled}).`,
+    'Fix 1 (the row was archived, still recoverable): ledger({action:"update", id:<N>, status:"在途"}) — 待核销 → 在途 是六态唯一的回退边; then ledger({action:"update", id:<N>, task_book:"<仓根相对指针>"}). Row is 已核销 / 已废弃 ⇒ that edge is gone, use Fix 2.',
+    'Fix 2 (this record is the right home, no row can come back): start a new record — batch({action:"create", …}) opens its ledger row in the same call — and launch the review under it.',
+    "Fix 3 (this record is finished): close it, and launch the review under the record that owns the work.",
+    "Nothing was sent: no review instance, no round consumed, no design token minted, no LLM call.",
+  ].join("\n")
+}
+
 export const advisorTool = {
   name: "advisor",
   description: DESC("advisor"),
@@ -65,7 +138,7 @@ export const advisorTool = {
       },
       batchDoc: {
         type: "string",
-        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/batches/…, or absolute). Omit when no batch record is in flight (no write channel — zero regression).",
+        description: "Design review only, REQUIRED: the batch record this review belongs to — the reviewer then also gets the `batch` write channel to record its findings + verdict. A design review without it is refused at launch (a token with no batch has no closer); a path that does not resolve to a readable file is refused. Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/batches/…, or absolute). Code reviews do not pass it.",
       },
     },
     required: ["type"],
@@ -95,6 +168,43 @@ export const advisorTool = {
       })
     }
     const reviewType = args.type
+    // 准入门：`type="design"` 且 `batchDoc` 缺失 / 空 ⇒ 拒发（判据与拒文 = `docs/core/design/ADVISOR-GUARDS.md`
+    // §2 第 6 条）；「携了须可读」那半幅随账链门（下段）一并判——判据与文案仍单源 `resolveBatchDocPath`。
+    // 绑定落 `resolved.run`（评审实例键）。
+    // 理由：设计评审签出的 token 由关档收口，而关档只认批归属——批外签发的授权没有第二个关闭者
+    // （spawn 只校验不消费、关档消费对无归属槽不适用，只剩 7 天 TTL）⇒ 堵法是让这种授权根本发不出去。
+    // 位置 = 类型门之后、文档范围解析之前：类型诊断与「参数在不在」都先于范围诊断（真因不被次要报错掩盖），
+    // 且二者都先于实例解析 / 签发 / LLM（零实例 / 零 token / 零槽 / 零 LLM）。
+    if (reviewType === "design" && missingBatchDoc(args.batchDoc)) {
+      if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+      return buildBatchDocRefusal(identityLine({
+        type: reviewType,
+        scope: scopeSummary(args.documents?.length ? args.documents : args.paths),
+        round: "—", // 判定先于实例解析——本次发起无轮次（§2 第 5 条字段行）
+        criterion: "batchdoc-missing",
+      }))
+    }
+    // 账链门（`docs/core/design/ADVISOR-GUARDS.md` §2 第 7 条）：`type="design"` ∧ `batchDoc` 已解析为绝对路径且
+    // 可读 ⇒ 点火拍查一次账——本档还有没有 ≥1 行未决台账行（`PENDING_STATUSES` 四态）的 `task_book` 指着它；
+    // 查不出「有」⇒ 拒发（`criterion=batchdoc-no-ledger`，reason 三值），登记 `_advisorRefusals`。
+    // 理由：第 6 条只要求「参数在 + 路径可读」，账侧从头到尾不问——行被撤回 ∥ 被结 ∥ 被改挂之后，
+    // 评审照发、token 照签，收口时重锚不到任何行。
+    // 批档绝对路径在本门就要用 ⇒ `resolveBatchDocPath` 从绑定行提前到此处调一次（绑定行复用同值，不二次解析）；
+    // 携了不可读 ⇒ 走其既有 throw（顺序表第 3 行：可读是账链的前提，前提坏先报前提）。
+    // 代码评审不走本门（绑定行对 `type="code"` 仍走原解析——行为零变）。
+    let designBatchDocAbs = null
+    if (reviewType === "design") {
+      designBatchDocAbs = resolveBatchDocPath(agent.cwd, args.batchDoc)
+      const chain = await resolveBatchLedgerLink({ batchDocAbs: designBatchDocAbs, anchor: agent.cwd })
+      if (!chain.ok) {
+        if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
+        return buildBatchNoLedgerRefusal({
+          batchDocAbs: designBatchDocAbs,
+          chain,
+          scope: scopeSummary(args.documents?.length ? args.documents : args.paths),
+        })
+      }
+    }
     const documents = args.documents || null
     // Scope fallback: the runtime mutation record (zero git) covers guard-triggered
     // reviews where the model did not pass explicit paths.
@@ -115,12 +225,14 @@ export const advisorTool = {
       const { invalid } = resolveReviewDocPaths(documents, agent.cwd)
       if (invalid.length > 0) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
-        // 拒发文案：既有稳定前缀逐字（行首）+ 逐文档「输入 → 解析后绝对路径 ∥ 拒因」+ 锚态（仅无项目根）+ 期望形两句。
-        const lines = invalid.map((v) => `- ${v.doc} → ${v.resolved ?? "(no base)"} ∥ reason=${v.reason}`)
-        if (invalid.some((v) => v.reason === "no-project-root")) {
+        // 拒发文案：既有稳定前缀逐字（行首）+ 逐文档「输入 → 解析后绝对路径 ∥ 拒因」+ 锚态（仅无唯一基根）+ 候选全列 + 期望形两句。
+        const lines = invalid.map((v) => `- ${v.doc} → ${v.resolved ?? "(no base)"} ∥ reason=${v.reason}${Array.isArray(v.sameName) && v.sameName.length > 0 ? `（盘上同名：${v.sameName.join(" ∥ ")}）` : ""}`)
+        if (invalid.some((v) => v.reason === "ambiguous-path" || v.reason === "dangling-path")) {
           const view = projectRootView(agent.cwd)
           const where = view.state === "workspace" ? `workspace (${view.candidates.join(", ")})` : "none (no PROJECT-MANIFEST.json here or above)"
-          lines.push(`Session anchor is ${where} — no project root, so a relative path has no base to resolve against.`)
+          lines.push(`Session anchor is ${where} — no single project root, so a relative path has no base to resolve against.`)
+          const cands = [...new Set(invalid.flatMap((v) => v.candidates ?? []))]
+          if (cands.length > 0) lines.push(`Candidates: ${cands.join(" ∥ ")} — pass one explicitly (an absolute path is the surest form).`)
         }
         lines.push("Expected form 1 — project-root-relative: docs/core/design/ADVISOR-GUARDS.md (resolved against the session project root).", "Expected form 2 — absolute: D:\\repo\\docs\\core\\design\\ADVISOR-GUARDS.md (used as-is).")
         return withIdentityLine(
@@ -154,13 +266,17 @@ export const advisorTool = {
     // scopes agent._advisorRound/_lastAdvisorOutput so the message builder and
     // the run.mjs cap read THIS instance's round/prior (multi-review isolation).
     const resolved = resolveAdvisorLaunch(agent, reviewType, { documents })
-    // BATCH-RECORD.md §4.2 评审侧批次档门禁 + 实例键绑定（评审实例的唯一路径来源）：
-    // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
-    // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
-    // 并发设计评审各绑各档，不用单值会话态（BATCH-RECORD.md §4.7 #6）。
+    // BATCH-RECORD.md §4.2 评审侧批次档绑定（评审实例的唯一路径来源）：准入面与账链门已保证设计评审的
+    // `batchDoc`（判据 = `docs/core/design/ADVISOR-GUARDS.md` §2 第 6 ∥ 7 条），本段只剩绑定落 `resolved.run`
+    // （评审实例键，与 reviewType/round/designId 同族）——并发设计评审各绑各档，不用单值会话态
+    // （BATCH-RECORD.md §4.7 #6）。
     if (args.batchDoc !== undefined && args.batchDoc !== null) {
-      resolved.run.batchDoc = resolveBatchDocPath(agent.cwd, args.batchDoc)
+      // 设计评审的绝对路径由账链门那一段算好（`designBatchDocAbs`——不二次解析）；代码评审仍走原解析。
+      resolved.run.batchDoc = designBatchDocAbs ?? resolveBatchDocPath(agent.cwd, args.batchDoc)
     }
+    // §3 点火基线（ADVISOR-GUARDS.md §1.1 判据 1）：结算面判「§3 已被本轮写过」需要「本轮之前有几块」
+    // 这个点——只在点火拍可得（结算时再读只能得到「现在有几块」）。两轨同源（`run` 由池条目透传）。
+    resolved.run.section3BlocksAtStart = section3BlocksBaseline(resolved.run.batchDoc)
     // Design token minted for EVERY design round — the reviewer echoes it only on
     // a clean pass; on pass it is slotted under the instance's designId at settle
     // (sync: right here; async: the settle callback — fix #2). A NEW instance

package/agent-tools/async-settle.mjs

@@ -139,7 +139,7 @@ export function parkAsyncPending(parent, entry) {
 
 /**
  * §6.31.5 升级账本写助手（消化账务批）：`_unsettledDigests` 追加一行
- * （`{ id, role, failures, report, at }`）。载体吸收（父字段优先 / history 借用——形态同
+ * （`{ id, role, missRounds, report, at }`）。载体吸收（父字段优先 / history 借用——形态同
  * `parkAsyncPending`）；行序 = 升级序（读面 = `digest-account.mjs` `unsettledRows`）。
  */
 export function appendUnsettledDigest(parent, row) {
@@ -187,7 +187,7 @@ export function releaseSettledEntry(entry) {
 
 /**
  * §6.31.4 投递面（消化账务批 · 2026-10-05 · 台账 #930）：会话态注入后**仅**释放 `childAgent`——
- * `report` 保留至销账 / 升级（重投需原文；驻留增量以报告量级 ∥ 重投上限封顶）。fallback 面零调用
+ * `report` 保留至销账 / 升级（升级终局披露需原文；驻留增量以报告量级 ∥ 未签收条数封顶）。fallback 面零调用
  * （既有 `releaseSettledEntry` 逐字沿用——注入即释放）。
  */
 export function releaseChildHold(entry) {

package/agent-tools/bash-async.mjs

@@ -38,6 +38,8 @@ import { cleanupOldToolResults, escapeXml } from "../agent/helpers.mjs"
 import { pushReal } from "../context.mjs"
 import { makeDecoder, sanitizeOutput } from "../tools/shared.mjs"
 import { killProcessTree } from "../tools/process-tree.mjs"
+// 过程档标记（TOOLS.md §6.28）：后台径的结算摘要也是输出行——解析基准 = entry 记下的 spawn 局部 `cwd`。
+import { markProcessDocLines } from "../tools/process-doc-mark.mjs"
 import { buildBashEnv } from "../tools/bash.mjs"
 import {
   bindChildController, buildChildSignal, carrierField, getAsyncPool, parkAsyncPending,
@@ -119,7 +121,7 @@ export async function launchBgTask(parent, ctx, { command, timeout = null, shell
   consumeSubagentToken(parent, id, "bash async launch", "bash")
   assertPoolKeyFree(pool, id, "bash")
   const logPath = join(dir, `${Date.now()}-bash-${id}.log`)
-  const cwd = ctx?.cwd ?? parent.cwd ?? process.cwd()
+  const cwd = ctx?.cwd ?? parent.cwd
   // UTF-8 码页前缀 = 同步径同款（win32 + 默认 shell）；解码走 `makeDecoder`（同源）。
   const effectiveCommand = process.platform === "win32" && !shell ? `chcp 65001 >nul && ${command}` : command
   const child = spawn(effectiveCommand, [], {
@@ -132,6 +134,8 @@ export async function launchBgTask(parent, ctx, { command, timeout = null, shell
   })
   const entry = {
     id, role: "bg", command, child, logPath,
+    // 解析基准 = 传给 spawn 的那个局部值（`ctx.cwd` 缺省时它跟着 undefined，另取就错位）
+    cwd,
     status: "running", done: false, cancelled: false, discarded: false,
     startedAt: Date.now(), endedAt: null, exit: null, killed: null, error: null,
     report: null, tail: "", tailDropped: false, bytes: 0,
@@ -211,7 +215,7 @@ function finalizeBgEntry(parent, entry, { code = null, signal = null, background
   wakeAsyncWaiters(parent)
 }
 
-/** 注入面尾截（双帽 + 截尾判据：行帽/字符帽/环形缓冲丢头三径合一）。 */
+/** 注入面尾截（双帽 + 截尾判据：行帽/字符帽/环形缓冲丢头三径合一），截帽完成后接过程档打标。 */
 function renderTail(entry) {
   let text = String(entry.tail ?? "")
   let truncated = entry.tailDropped === true
@@ -224,6 +228,8 @@ function renderTail(entry) {
     text = text.slice(-DIGEST_TAIL_MAX_CHARS)
     truncated = true
   }
+  // §6.28：两个消费点（`finalizeBgEntry` 的 `entry.report` ∥ `injectBgResult` 拼 body）同得标好的文本
+  text = markProcessDocLines(text, entry.cwd)
   return { text, truncated }
 }
 

package/agent-tools/batch-closeout.mjs

@@ -0,0 +1,206 @@
+/**
+ * agent-tools/batch-closeout.mjs — 收口面的四道判据与回执（从 `batch-lifecycle.mjs` 拆出，2026-10-27）。
+ *
+ * 权威规格 = `docs/core/design/BATCH-LEDGER-REVIEW-UNIFY.md` §2.6（四道门）∥ §2.11（收口前显式处置）；
+ * 链门的原文契约 = `docs/core/design/BATCH-RECORD.md` §4.18-A。
+ *
+ * 本档承载三件（都不碰 fs 写、只读与判）：
+ * ① `assertCloseoutGates` —— 收口两路（`close` ∥ `status` 写 `§1 已收口`）共调的判序：
+ *    链完整性门（§2/§3/§4/§6 各段须有内容——`不适用` 声明机制已退役）→ **`§3` 状态词臂**（无条件 = `评审通过`）
+ *    → 本批批内单测档门（`TESTING.md` §3.5）→ 文档机检门（`DOC-DISCIPLINE.md` §3.20）。
+ * ② `assertSectionFiveGate` —— §5 写入门（段序门）：两条合取——① `§3` 状态行 = `评审通过`；② `§3` 最近一轮
+ *    轮次块自己携 pass 裁定行（块 = `lastRoundBlock`；裁定读数 = 骨架档 `verdictGapOf`，`append §3` 写入闸与
+ *    签发面读同一个函数）。旧的第一条旁路（`§1` 声明 §3 不适用）已随本批删除：实现只发生在评审之后，没有例外段。
+ * ③ `reanchorReceiptLine` —— 收口重锚回执三行（§2.11 逐字）。
+ *
+ * 为什么 §3 内容臂留着（不换成只判状态词）：内容臂守的是「段里真跑过」，状态词臂守的是「跑的结论是
+ * pass」——换掉内容臂 = 门被放宽（一段空着但状态词对就过），那正是本批要堵的洞。所以是**加**一条臂。
+ *
+ * 依赖单向（KD-4）：`skeleton ← closeout ← bind ← reopen ← lifecycle`——本档不 import lifecycle。
+ */
+import { readFileSync } from "node:fs"
+
+import {
+  countRoundBlocks, inapplicableDeclarationError, lastRoundBlock, malformedInapplicableLine, readSectionStatusWord,
+  sectionContentState, STATUS_WORDS, verdictGapOf,
+} from "./batch-skeleton.mjs"
+// 裁定读数 = 骨架档 `verdictGapOf` 一个函数（设计档 §2.6.1「判据单源」）：`§5` 门判据 2 与签发面判的是同一份
+// 回执文本，组合序各写一遍必然一处变一处不变。本档不再 import 两条裁定锚——锚与序都在那个函数里。
+import { assertUnitTestFilesCleared } from "./batch-unit-test-gate.mjs"
+import { gateRefusalMessage, runBatchGate } from "./batch-gate.mjs"
+
+/** 链判段集（§2/§3/§4/§6——§5 段号豁免恒不判；§1 主 agent 自述段不设前置）。 */
+const CHAIN_SEGMENTS = [2, 3, 4, 6]
+
+/** §6 空闸拒句（#422①——空 ⇒ 拒 + 提示先写 §6；防「append 被拒 ⇒ close 照常 ⇒ §6 永久为空」复发）。
+ *  **§6 为唯一缺段时**拒串取本函数（§4.18-A J2——「非空门」文案逐字零回归）；判据本体 = 单源谓词
+ *  `sectionContentState(src, 6)`。 */
+function emptySectionSixError() {
+  return "batch: §6 收口段为空（non-empty gate）— close refuses: the closeout section (§6) has no content, and closing would freeze the record with that section permanently empty. Write the section first (append §6: the closeout / verification summary), then call close again. Nothing was written."
+}
+
+/** 链门拒绝句（§4.18-A J1——缺段非仅 §6 时；`missing` = 点名串，
+ *  形如 `§2 / §3 / §4`——按段号升序列出）。不再提声明路：机制已退役，提它就等于又给一条可照抄的路。 */
+function closeoutChainError(missing) {
+  return "batch: 收口链未跑完（closeout chain gate）— close refuses: the record's closeout chain has not run, and closing would freeze it that way. " +
+    `Missing: ${missing}. Each named section must carry its own content — the \`不适用\` declaration is retired (every batch needs its design, its review and its approval). ` +
+    "§6 must carry its verification. Nothing was written."
+}
+
+/** `§3` 状态词臂拒句（设计档 §2.6 `R-G1` 逐字形）：链门已过、只剩评审结论没到时出这一条。
+ *  `value` = 读到的状态词（缺失 ⇒ `（无状态行）`）。本臂无条件——没有「声明不适用」这条旁路。 */
+function closeoutS3Error(value) {
+  return "batch: 收口链未跑完（closeout chain gate）— close refuses: " +
+    `§3 状态行 = ${value}，须 = 评审通过（评审须真跑过并给 pass）。Missing: §3. Nothing was written.`
+}
+
+/**
+ * 链完整性门（§4.18-A——**收口前置**）：判据 = §2 / §3 / §4 / §6 每段须 `sectionContentState(src, seg) !== "empty"`
+ * （有内容）；不满足 ⇒ throw 并点名缺段（J1；§6 为唯一缺段时 = J2 旧串逐字）。门不判内容质量、
+ * 不做自动修复、不判 §1 / §5。声明行扫描先行（J3——那类行现在一律拒，不静默当作无声明）。
+ * @param {string} src — 档全文（写盘前只读）
+ */
+export function assertCloseoutChainComplete(src) {
+  const badDecl = malformedInapplicableLine(src)
+  if (badDecl !== null) throw new Error(inapplicableDeclarationError(badDecl))
+  const missing = CHAIN_SEGMENTS.filter((n) => sectionContentState(src, n) === "empty")
+  if (missing.length === 0) return
+  if (missing.length === 1 && missing[0] === 6) throw new Error(emptySectionSixError()) // J2——零回归
+  throw new Error(closeoutChainError(missing.map((n) => `§${n}`).join(" / "))) // J1
+}
+
+/**
+ * 收口两路共调判序（设计档 §2.4–§2.6 · 2026-10-27 四道门）：
+ *   ① 链完整性门（§2 / §3 / §4 / §6 各段须有内容）
+ *   ② **`§3` 状态词臂**：`§3` 状态行 = `评审通过`（无条件）
+ *   ③ 本批批内单测档门（仍在盘 ⇒ 拒——零留存的结构兜底）
+ *   ④ 文档机检门（REFUSED ∥ ERROR ⇒ 拒）
+ * 位次 = 既有拒因之后、写盘之前（任一被拒 ⇒ 档字节不变）。返回 `④` 的门结果供回执拼行（`null` = 未跑）。
+ * @param {{abs:string, cwd:string, agent:object, src:string, action:"close"|"status"}} o
+ *   `src` = 调用方已读的写盘前全文（判据与写盘读同一份字节，不二次读盘）。
+ * @returns {object|null} 文档机检门结果
+ */
+export function assertCloseoutGates({ abs, cwd, agent, src, action = "close" }) {
+  assertCloseoutChainComplete(src) // ① 链门（§2 / §3 / §4 / §6 各段须有内容）
+  // ② §3 状态词臂（无条件）：评审须真跑过并给 pass。旧旁路「§1 声明 §3 不适用」已随声明机制退役删除。
+  const s3 = readSectionStatusWord(src, 3)
+  if (s3 !== STATUS_WORDS[3].done) throw new Error(closeoutS3Error(s3 ?? "（无状态行）"))
+  assertUnitTestFilesCleared(abs, action) // ③
+  const gate = runBatchGate({ abs, cwd, agent, scope: "close" }) // ④
+  if (gate.state === "refused" || gate.state === "error") throw new Error(gateRefusalMessage(gate, action))
+  return gate
+}
+
+/** 读档（本档只读一面——写盘归 lifecycle 与 bind；读错上抛不伪装）。 */
+export function readCloseoutSource(abs) { return readFileSync(abs, "utf8") }
+
+/**
+ * 判据 2 的块内裁定读数（设计档 §2.6「pass 谓词」）：`null` = pass；否则 = 拒文括注里的那一格。
+ * 组合序不在本档——一律取骨架档 `verdictGapOf`（判据单源，设计档 §2.6.1）：写面、`§5` 门与签发面三处同读
+ * 一个函数，锚与顺序都只有那一份。本函数只留名字：拒文（`R-G2b`）与设计档用的就是这个符号，读者按它对账。
+ * 块 = `null`（段内无块）⇒ `verdictGapOf(null)` = 「无裁定行」，与改前同值。
+ * @param {string|null} block — `lastRoundBlock(src, 3)` 的返回形
+ * @returns {string|null} 拒文括注值 ∥ `null`（块自己说了 pass）
+ */
+function lastRoundVerdictGap(block) {
+  return verdictGapOf(block)
+}
+
+/** 判据 2 拒文（设计档 §2.6 `R-G2b` 逐字；`blocks` = 段内轮次块数——无块时取 0）。
+ *  `gap` = `lastRoundVerdictGap` 的非空返回形，落进括注的裁定格。 */
+function sectionFiveVerdictBlockError(src, gap) {
+  const blocks = countRoundBlocks(src, 3)
+  return "batch: §5 append refused — the last §3 round block carries no pass verdict " +
+    `(§3 最近一轮轮次块 = 第 ${blocks} 轮，块内裁定 = ${gap}). A pass means that block carries a \`VERDICT: pass\` line and no changes-required line — ` +
+    "a round that does not state a pass is not a pass: append the verdict line to that block (`VERDICT: pass`)，或按裁定行重跑评审。Nothing was written."
+}
+
+/**
+ * §5 写入门（段序门 · 设计档 §2.6）：实现发生在评审通过之后，序在这里才判得出真假。
+ * 判据 = 两条合取（**没有第一条的旁路**：`§1` 声明 §3 不适用已随声明机制退役——实现只发生在评审之后），
+ * 先判状态词、过了再判块（状态词不过时拒文已足以说明，不必再报块）：
+ *   ① `§3` 状态行 = `评审通过`（拒文 `R-G2`）；
+ *   ② `§3` **最近一轮轮次块自己携 pass 裁定行**（拒文 `R-G2b`）——评审写了一笔 `§3` 却不带任何裁定行时，
+ *      上一轮的 `评审通过` 仍是字面字，只判 ① 就会放行。② 只问一个可读的事实「门所依赖的块自己有没有
+ *      说结论」，不猜意图（补记 ∥ 隐性打回的处置是同一条）；`§3` 无任何轮次块 ⇒ ② 不成立、照拒——
+ *      真跑过的 pass 必落本轮块，无块即无 pass 可依。
+ * 修正轮在 §3 已 pass 之后追加 §5，末块携 pass 裁定 ⇒ 两判据当场成立。`status` 单写不再足以开 `§5`（只置状态词、不落一块携 pass 裁定的
+ * 轮次块 ⇒ 照拒）。
+ * @param {string} src — 写盘前的档全文
+ */
+export function assertSectionFiveGate(src) {
+  const s3 = readSectionStatusWord(src, 3)
+  if (s3 !== STATUS_WORDS[3].done) {
+    throw new Error("batch: §5 append refused — the implementation section opens only after the design review passed " +
+      `(§3 状态行 = ${s3 ?? "（无状态行）"}，须 = 评审通过). Nothing was written.`)
+  }
+  const gap = lastRoundVerdictGap(lastRoundBlock(src, 3))
+  if (gap !== null) throw new Error(sectionFiveVerdictBlockError(src, gap))
+}
+
+/**
+ * 收口重锚回执段（设计档 §2.11 逐字三行；空行不出）：
+ *   `[ledger reanchor] 本批在途行 → 待核销 N 行：#12 「…」；#15 「…」 —— 认领行只有两种终局：…`
+ *   `[ledger reanchor] 本批未动行 → 条件 M 行：#16 「…」 —— 这些行不是本批的活（未认领却被绑在本档 = 点火违规）…`
+ *   `[ledger reanchor] 本批 N+M 行由重锚默认推进，父侧未显式处置：#12, #15, #16`
+ * **建议句贴在自己那一类行上**：第一行只装 `在途` 行、第二行只装 `待讨论` / `待设计` 行——两类的出路相反
+ * （认领行只有两种终局；未认领行本来就不该在本批），一句管两类正是要收的病句；汇总行因此只点名、不给建议。
+ * 第三行只在 N+M > 0 时出现（父侧全处置过 ⇒ 零该行，回执不噪）。失败 ⇒ 只出失败行（台账零写、冻结照常）。
+ * @param {{reanchored:Array, failed:string|null}|null} result — `ledgerReanchorBatch` 返回形
+ */
+export function reanchorReceiptLine(result) {
+  if (!result) return ""
+  if (result.failed) return `\n[ledger reanchor] 未重锚：${result.failed}——台账零写；记录冻结照常完成`
+  const face = (r) => `#${r.id} 「${r.title}」`
+  const toSettle = (result.reanchored ?? []).filter((r) => r.to === "待核销")
+  const toCondition = (result.reanchored ?? []).filter((r) => r.to === "条件")
+  const lines = []
+  // 建议句各贴其行（§2.11）：第一行只装认领行、第二行只装未认领行，第三行只点名。
+  if (toSettle.length) {
+    lines.push(`\n[ledger reanchor] 本批在途行 → 待核销 ${toSettle.length} 行：${toSettle.map(face).join("；")}` +
+      " —— 认领行只有两种终局：做完的 close 勾销（待核销 → 已核销），判定不做的 update → 已废弃 并写判据（认领即承诺，没有第三种）")
+  }
+  if (toCondition.length) {
+    lines.push(`\n[ledger reanchor] 本批未动行 → 条件 ${toCondition.length} 行：${toCondition.map(face).join("；")}` +
+      " —— 这些行不是本批的活（未认领却被绑在本档 = 点火违规）；已落 trigger = 条件 + 复启句，由下一批接手，本批不再处置")
+  }
+  const all = result.reanchored ?? []
+  if (all.length) {
+    lines.push(`\n[ledger reanchor] 本批 ${all.length} 行由重锚默认推进，父侧未显式处置：${all.map((r) => `#${r.id}`).join(", ")}`)
+  }
+  return lines.join("")
+}
+
+/** 新事理由的 `evidence` 前缀（单源 = `docs/core/design/LEDGER.md` §6.3「参数面」；写入侧由
+ *  `thincoder-core/ledger-write-ops.mjs` 的 `NEW_DEBT_EVIDENCE_PREFIX` 造，本档按同一字面取文）。 */
+const NEW_DEBT_PREFIX = "新事理由："
+/** `evidence` 追加相接符（追加形 `旧｜新` 零空格——§6.3「取文」）。 */
+const EVIDENCE_JOINER = "｜"
+
+/**
+ * 取一行新事理由（设计档 §6.3「取文」）：`evidence` 中 `新事理由：` 之后、至首个 `｜`（追加相接符）
+ * 或串尾的一段。无该前缀 ∥ 取到空串 ⇒ `null`（负向锁：不是本机制写的行不引）。**只读**——不改入参。
+ * @param {string|null} evidence — 行 `evidence` 原值
+ * @returns {string|null} 理由原文 ∥ `null`
+ */
+export function newDebtReasonOf(evidence) {
+  const s = String(evidence ?? "")
+  const at = s.indexOf(NEW_DEBT_PREFIX)
+  if (at < 0) return null
+  const rest = s.slice(at + NEW_DEBT_PREFIX.length)
+  const cut = rest.indexOf(EVIDENCE_JOINER)
+  const value = (cut < 0 ? rest : rest.slice(0, cut)).trim()
+  return value === "" ? null : value
+}
+
+/**
+ * 收口回执的新事理由引文段（逐字 = 设计档 §6.3「理由的读面与时点」：`  新事理由（#<id>）：<理由原文>`）。
+ * 读者 = 本批收口那一笔的主 agent · 时点 = 本批收口。**零新清单、只引不写**：纯格式化、零库访问、
+ * 不改入参；一条理由一行。取不到本批行 ⇒ 入参无该键 ⇒ 不出该段（收口不被否决）。
+ * @param {{newDebtReasons?:{id:number, reason:string}[]}|null} result — `reanchorOnClose` 返回形
+ * @returns {string} 以换行起头；无引文 ⇒ 空串
+ */
+export function newDebtReasonReceiptLine(result) {
+  const rows = result?.newDebtReasons ?? []
+  return rows.map((r) => `\n  新事理由（#${r.id}）：${r.reason}`).join("")
+}