@thincoder/core 0.10.13 → 0.11.1

package/agent-tools/batch-gate.mjs

@@ -4,29 +4,44 @@
  * 权威规格 = `docs/core/design/DOC-DISCIPLINE.md` §3.20「结构兜底」（判据 / 范围 / 适用面 /
  * ERROR 消费分野 / 门自身异常 / 不检面）——本档只实现，**不重述口径**（D2）。需求 = `DOC-CHECK.md` F9 / AC-7。
  *
- * 调用面两处、各一取值（`scope` 语义 = 规范「调用面开关，无第三值」）：
- *   ① `batch.mjs` append 写 §2 / §5（`!depth0 && !review`）⇒ `scope: "writer"`——范围 = 写者触达记账
- *      （与工具面 gate 同源 `docsSource="session"`）；`REFUSED` ⇒ 调用面 throw；`ERROR` / 门自身异常 ⇒ 放行 +
- *      回执明示（子代理无法重启会话，卡死写账 = 无账之笔；② 会拒收口 ⇒ 轮次不会被当成已通过）。
+ * 调用面（`scope` 语义 = 规范「调用面开关，无第三值」）：
+ *   ① `batch.mjs` append——**全部 append 同挂**（§1–§6，含 depth-0 与评审写 §3）⇒ `scope: "writer"`；
+ *      强制集 = 本次写入文本命中 ∪ 写者触达账命中；`REFUSED` ⇒ 调用面 throw；`ERROR` / 门自身异常 ⇒
+ *      放行 + 回执明示（子代理无法重启会话，卡死写账 = 无账之笔；② 会拒收口 ⇒ 轮次不会被当成已通过）。
  *   ② `batch-lifecycle.mjs` close ∥ status 值余核「已收口」⇒ `scope: "close"`——范围 = 本批笔域集
- *      （父侧触达账 ∪ 本批提交 diff = `git diff --name-only <批起 sha> HEAD` 内的 `.md`）；
+ *      （父侧触达账 ∪ 本批提交 diff = `git diff --name-only <批起 sha> HEAD` 内的 `.md` ∪ 批档自身）；
  *      `REFUSED`（K ≥ 1）∥ `ERROR` ⇒ 调用面 throw（fail-closed）。
  *      **单集**：范围内不设第二集——工作树里范围外的档不入判、不入报面（用户 2026-10-25 裁定「只判指定文件」）。
  *
+ * **批档自身恒在判域（两 scope 同）**：批档生于此轮、冻结于此轮（`close` 之后整档冻结）⇒ 其全文字面
+ * 即本轮的笔面，档内没有「别轮写的存量」可排；存量 = 别批的档，已由单集规则排除。于是：
+ *   · ① 面**已落段命中**的处置按动作分两种（判集 = `docs/core/design/BATCH-RECORD.md` §4.9 门 ④ 判集两句）：
+ *     `append` ⇒ 只入回执、不阻本次写——追加不碰既有行，拒一个改不动的人只会让这一段永远写不进
+ *     （无账之笔）；本次追加文（片段档）与触达账命中当场拒。
+ *     `edit`（携 `pending.recordView` = **改写后的整档**）⇒ **判集两类**：段长类（段落过长 · 行过长）只判
+ *     `newText`（片段档）——一条早先就在的超长段不拦本段的无关改动；**锚类判整档、当场拒**——引用完整性
+ *     是档级属性，且这一段的作者改得动那一行。盘上旧字节不参判（拿改写前的档判，#2021 那条死引文
+ *     永远过不去）；
+ *   · ② 面命中即 K，且命中落在批档内时逐条带 `§N（作者：<角色>）`（答「谁该改」；作者取自档头
+ *     「一段一作者」映射，取不到 ⇒ 只出 `§N`，不猜）。
+ *
  * 判据零变：本档不新增判据——只决定「判谁」与「何时强制」；判据与裁定串由产品引擎
  * `doc-check/index.mjs` 产出（判据源唯一）。
  *
  * 两条边界（设计与实测同口径）：
- * ① **批档自身不入范围**（载体不是判据对象——判它只会把载体的超段记成本批欠账）；
+ * ① **本次写入文本的判法** = 落批档同目录的隐藏片段档（`.gate-<pid>-<rand>.md`）——锚解析序 ② 是
+ *    「引用方档所在目录相对」，同目录 ⇒ 判法与批档本体逐字同源；一次 `runDocCheck` 判两档，按命中
+ *    所在档切强制集 / 明示集，回执把片段档显示成「本次写入文本」。片段档 `finally` 删；同目录的
+ *    `.gate-*` 残留**只明示、不代删**（并发进程的活片段是别人正在判的档）。
  * ② **提交 diff 腿的基 sha 只读批档 §1 的记入行**（`批起 sha = <sha>`——取行内首个 40 位十六进制串）；
  *    取不到（无该行 ∥ 形态不合 ∥ git 跑不出该 diff）⇒ 只认触达账 + 回执明示「基 sha 未定」（不静默）。
  */
 import { execFileSync } from "node:child_process"
-import { readFileSync } from "node:fs"
-import { relative, resolve } from "node:path"
+import { readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs"
+import { dirname, join, relative, resolve } from "node:path"
 
 import { owningProject, readManifest } from "../manifest.mjs"
-import { runDocCheck } from "../doc-check/index.mjs"
+import { runDocCheck, PARA_DISPOSE, DOC_CLASS } from "../doc-check/index.mjs"
 import { sectionHeaderRe } from "./batch-skeleton.mjs"
 import { batchProjectRoot } from "./batch-paths.mjs"
 
@@ -41,6 +56,85 @@ function docPaths(list, base) {
   return out
 }
 
+/** 锚类命中（引擎大类中的锚面；其余 clazz = 段判据命中）。类名由引擎产出，本档只作切分。
+ *  三属同计「锚 N 条」：`档缺` / `节缺` / `引缺`（引文不在所指档内——同属锚判据，不是段类）。 */
+const ANCHOR_CLASSES = new Set(["档缺", "节缺", "引缺"])
+
+/** 片段档名前缀（与批档同目录的隐藏档——锚解析序 ② 与批档本体同源）。**导出面**：`batch-lifecycle.mjs` 的在飞
+ *  扫描要靠它把两类片段档排除在外——`edit` 面的 `recordView` 是**整档副本**（`## §1` 段头 + `进行中` 都在），
+ *  不排除就会被当成第二本在飞批（假拒），进程被杀则残留一本永久 open 的幽灵档。 */
+export const FRAGMENT_PREFIX = ".gate-"
+
+/** 片段档路径（每次一个随机名：并发两次门不撞名，也不互删）。 */
+function fragmentPathOf(abs) {
+  return join(dirname(abs), `${FRAGMENT_PREFIX}${process.pid}-${Math.random().toString(36).slice(2, 10)}.md`)
+}
+
+/** 同目录 `.gate-*` 残留（进程在写片段后、清理前被杀）：**只扫不删**——并发进程的活片段是别人正在判的档。 */
+function strayFragmentsOf(dir, ownAbs) {
+  let names
+  try { names = readdirSync(dir) } catch { return [] }
+  const skip = ownAbs ? pathKey(ownAbs) : null
+  return names.filter((n) => n.startsWith(FRAGMENT_PREFIX) && n.endsWith(".md") && pathKey(join(dir, n)) !== skip)
+}
+
+/** 读档（读不到 ⇒ 空串：归属标注取不到就只出 `§N`，不猜）。 */
+function safeRead(abs) {
+  try { return readFileSync(abs, "utf8") } catch { return "" }
+}
+
+/** 批档档头骨架行的「一段一作者」映射（`batch` create 落骨架时写入）——取不到 ⇒ 空表。 */
+function authorMapOf(src) {
+  const map = new Map()
+  for (const line of String(src ?? "").split("\n")) {
+    if (!line.includes("一段一作者")) continue
+    for (const m of line.matchAll(/§\s*(\d+)\s*[^（(]*[（(]([^）)]+)[）)]/g)) {
+      const n = Number(m[1])
+      if (!map.has(n)) map.set(n, m[2].trim())
+    }
+  }
+  return map
+}
+
+/** 行号 → 所属段号（`## §N` 段头分段；首个段头之前 ⇒ null）。 */
+function sectionOfLine(src, line) {
+  const lines = String(src ?? "").split("\n")
+  const end = Math.min(line, lines.length)
+  let cur = null
+  for (let i = 0; i < end; i++) {
+    const m = /^## §(\d+)(?=\s|$)/.exec(lines[i])
+    if (m) cur = Number(m[1])
+  }
+  return cur
+}
+
+/** 命中行落在批档内时的归属标注：` §N（作者：<角色>）`；作者取不到 ⇒ 只出 ` §N`（不猜）。 */
+function attributionOf(src, line, authors) {
+  const seg = sectionOfLine(src, line)
+  if (seg === null) return ""
+  const who = authors.get(seg)
+  return who ? ` §${seg}（作者：${who}）` : ` §${seg}`
+}
+
+/** 明示集的单条摘要（`§N 第 M 行（作者：<角色>）`）。 */
+function landedSummary(src, entry, authors) {
+  const seg = sectionOfLine(src, entry.line)
+  const at = seg === null ? `第 ${entry.line} 行` : `§${seg} 第 ${entry.line} 行`
+  const who = seg === null ? null : authors.get(seg)
+  return who ? `${at}（作者：${who}）` : at
+}
+
+/** 命中集按类分列（`锚 A 条 · P 处<类名>`）——引擎报面行形不动，只在这里做计数。 */
+function classifyCounts(entries) {
+  const parts = []
+  const anchor = entries.filter((e) => ANCHOR_CLASSES.has(e.clazz)).length
+  if (anchor) parts.push(`锚 ${anchor} 条`)
+  const byClass = new Map()
+  for (const e of entries) if (!ANCHOR_CLASSES.has(e.clazz)) byClass.set(e.clazz, (byClass.get(e.clazz) ?? 0) + 1)
+  for (const [clazz, n] of byClass) parts.push(`${n} 处${clazz}`)
+  return parts.join(" · ")
+}
+
 /**
  * `<批起 sha>` 的取法（唯一）= 批档 §1 的记入行 `批起 sha = <sha>`：段界消费 `sectionHeaderRe(1)`
  * （段头形态单源——`## §10` 不误命中 `§1`），取段内该行行内首个 40 位十六进制串。
@@ -82,50 +176,58 @@ function committedDocs(root, sha) {
   }
 }
 
-/** 命中 → `{ aligned, entries }`：`file` = 判定用（引擎给绝对路径）；显示行取引擎已产出的 `✗` 行
- *   （报面单源不重写）；行数与命中数不等（引擎报面行序变动）⇒ `aligned: false` + 自造行，由调用面回执明示。 */
-function hitEntries(res, root) {
+/** 命中 → `{ aligned, entries }`：`file` / `line` / `clazz` = 判定用（引擎给绝对路径）；
+ *  显示行取引擎已产出的 `✗` 行（报面单源不重写），过 `translate` 换掉片段档的临时路径；
+ *  行数与命中数不等（引擎报面行序变动）⇒ `aligned: false` + 自造行，由调用面回执明示。 */
+function hitEntries(res, root, translate) {
   const lines = res.report.split("\n").filter((l) => l.startsWith("✗ "))
   const hits = [...res.anchorHits, ...res.paragraphHits]
   const aligned = lines.length === hits.length
   const entries = hits.map((h, i) => ({
     file: h.file,
-    line: aligned ? lines[i] : `✗ ${relative(root, h.file).replace(/\\/g, "/")}:${h.line}`,
+    line: h.line,
+    clazz: h.clazz,
+    text: translate(aligned ? lines[i] : `✗ ${relative(root, h.file).replace(/\\/g, "/")}:${h.line}`),
   }))
   return { aligned, entries }
 }
 
-/** 报面组装：只换首行 + 插入本条附加行（其余行 = 引擎原样，不重写格式）。 */
-function composeReport(res, first, notes) {
-  const lines = String(res.report).split("\n")
-  lines[0] = first
-  if (notes.length) {
-    const at = lines.findIndex((l) => l.startsWith("处置："))
-    if (at >= 0) lines.splice(at, 0, ...notes)
-    else lines.push(...notes)
+/** 报面组装：首行 verdict + 强制集命中行 + 明示集命中行 + 附注行 + 处置块（只跟段命中走——仅锚 ∥ 仅行命中不得叫人对段落动手；
+ *  字面单源 = 引擎导出的 `PARA_DISPOSE`，本档零字面副本）。明示集标题按面取形（`append` = 已落段命中；
+ *  `edit` = 档内段长类命中——段长类判集是本次写入文本，两件事在回执里不得叫同一个名字）。 */
+function composeReport({ first, forcedLines, disclosedLines, disclosedHeader, notes, disposePara }) {
+  const out = [first, ...forcedLines]
+  if (disclosedLines.length) {
+    out.push(disclosedHeader ?? "—— 批档已落段命中（只明示、不阻本次写；收口面 fail-closed 当场拦）：", ...disclosedLines)
   }
-  return lines.join("\n")
+  out.push(...notes)
+  if (disposePara) out.push(...PARA_DISPOSE)
+  return out.join("\n")
 }
 
 /** 空范围返回形（`range` 恒在场——回执要读 `范围 N 档`）。 */
 const emptyRange = (basis) => ({ count: 0, k: 0, basis })
-const errorState = (first, range = emptyRange("none")) => ({ state: "error", first, report: first, hitLines: [], noteLines: [], range })
+const errorState = (first, range = emptyRange("none")) => ({ state: "error", first, report: first, hitLines: [], noteLines: [], disposePara: false, range })
 
 /**
  * 跑一次门（**非抛错**：两因之外的门自身异常收为 `error` 态，由调用面按 `scope` 消费）。
- * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close'}} o
- *   `abs` = 目标批次档绝对路径（根解析用）；`agent._touchedFiles` = 触达记账。
+ * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close', pending?:{section?:number, body?:string, recordView?:string}|null}} o
+ *   `abs` = 目标批次档绝对路径（根解析用；**同时恒是判域一员**）；`agent._touchedFiles` = 触达记账；
+ *   `pending` = 本次写入的段号与文本（`writer` 面强制集；缺省 ⇒ 无本次文本腿，`close` 面恒缺省）：
+ *   `body` = 本次写进来的文本（append = 追加文 ∥ edit = `newText`——片段档判）；
+ *   `recordView` = **改写后的整档全文**（仅 `edit` 面传：锚类判这个视图，盘上旧字节不参判）。
  * @returns {{state:'pass'|'refused'|'error'|'not-applicable', first:string|null, report:string,
- *   hitLines:string[], noteLines:string[], range:{count:number, k:number, basis:string}}}
- *   `first` = 唯一机判串（首行 `DOC-CHECK GATE:`）；`not-applicable` ⇒ `first = null` + 固定回执行。
+ *   hitLines:string[], noteLines:string[], disposePara:boolean, range:{count:number, k:number, basis:string}}}
+ *   `first` = 唯一机判串（首行 `DOC-CHECK GATE:`）；`not-applicable` ⇒ `first = null` + 固定回执行；
+ *   `disposePara` = 判域内存在「文字太长，难于阅读」类命中（拒串据此选「空行 + 五行块」还是照旧一句处置）。
  */
-export function runBatchGate({ abs, cwd, agent = {}, scope = "writer" } = {}) {
+export function runBatchGate({ abs, cwd, agent = {}, scope = "writer", pending = null } = {}) {
   // `scope` 两取值、无第三值（设计「`scope` 语义」）——未知值不静默降级（降级即 ② 变 fail-open）
   if (scope !== "writer" && scope !== "close") {
     return errorState(`DOC-CHECK GATE: ERROR（未知 scope：${JSON.stringify(scope)}——取值只有 "writer" ∥ "close"）`)
   }
   try {
-    return evaluate({ abs, cwd, agent, scope })
+    return evaluate({ abs, cwd, agent, scope, pending })
   } catch (e) {
     const first = `DOC-CHECK GATE: ERROR（门自身异常：${e?.message ?? String(e)}）`
     return errorState(first)
@@ -133,9 +235,10 @@ export function runBatchGate({ abs, cwd, agent = {}, scope = "writer" } = {}) {
 }
 
 /** 门体（正常路径——异常由上抛给 `runBatchGate` 收口）。 */
-function evaluate({ abs, cwd, agent, scope }) {
-  const base = resolve(cwd ?? process.cwd())
-  const root = owningProject(resolve(abs)) ?? batchProjectRoot(base)
+function evaluate({ abs, cwd, agent, scope, pending }) {
+  const base = resolve(cwd)
+  const selfAbs = resolve(abs)
+  const root = owningProject(selfAbs, base) ?? batchProjectRoot(base)
   const close = scope === "close"
 
   let read
@@ -144,44 +247,141 @@ function evaluate({ abs, cwd, agent, scope }) {
   }
   // 适用面（声明面驱动）：无 manifest ⇒ 不适用 + 回执明示；**不是豁免清单**——判据参数 = 引擎内置常量。
   if (!read.ok && read.reason === "missing") {
-    return { state: "not-applicable", first: null, report: "[doc-check gate] 未跑（本项目无声明面）", hitLines: [], noteLines: [], range: emptyRange("none") }
+    return { state: "not-applicable", first: null, report: "[doc-check gate] 未跑（本项目无声明面）", hitLines: [], noteLines: [], disposePara: false, range: emptyRange("none") }
   }
-  // 范围（判谁）：writer = 写者触达账；close = 本批笔域集 = 触达账 ∪ 本批提交 diff（**单集**——
-  // 范围内不设第二集：工作树里范围外的档不入判、不入报面）。
-  // 批档自身不入范围（载体不是判据对象——判它只会把载体的超段记成本批欠账）。
-  const selfKey = pathKey(resolve(abs))
-  const touched = docPaths(agent?._touchedFiles, base).filter((p) => pathKey(p) !== selfKey)
-  const baseSha = close ? baseShaOf(abs) : null
+
+  // 范围（判谁）：writer = 写者触达账 ∪ 本次写入文本 ∪ 批档自身；
+  //                   close = 本批笔域集 = 触达账 ∪ 本批提交 diff ∪ 批档自身（**单集**——范围外的档不入判、不入报面）。
+  const touched = docPaths(agent?._touchedFiles, base)
+  const baseSha = close ? baseShaOf(selfAbs) : null
   const diff = baseSha ? committedDocs(root, baseSha) : { ok: false, base: root, files: [] }
-  const diffDocs = docPaths(diff.ok ? diff.files : [], diff.base).filter((p) => pathKey(p) !== selfKey)
-  const docs = close ? [...new Set([...touched, ...diffDocs])] : touched
-  const basis = !close ? "touched" : diff.ok ? "touched+diff" : "touched（基 sha 未定）"
-  const res = runDocCheck(root, { mode: "gate", docs, docsSource: close ? "explicit" : "session" })
-
-  const { aligned, entries } = hitEntries(res, root)
-  const k = entries.length // 单集：命中数即 K（没有第二集可排除）
-  const first = k >= 1
-    ? `DOC-CHECK GATE: REFUSED（命中 ${k} 条）`
-    : (res.checkFiles.length ? "DOC-CHECK GATE: PASS" : "DOC-CHECK GATE: PASS（0 档）")
-
-  // 附加行（不静默面）：命中行不可对齐（判定面自述）+ 收口面取不到基（只认触达账）。
-  const notes = []
-  if (!aligned) notes.push("命中行不可对齐（引擎报面 ✗ 行数与命中数不等）——显示行按自造形，判定按命中对象")
-  if (close && !diff.ok) notes.push("基 sha 未定——本批笔域集只认触达账")
-
-  return {
-    state: k >= 1 ? "refused" : "pass",
-    first,
-    report: composeReport(res, first, notes),
-    hitLines: entries.map((e) => e.line),
-    noteLines: notes,
-    range: { count: res.checkFiles.length, k, basis },
+  const diffDocs = docPaths(diff.ok ? diff.files : [], diff.base)
+
+  const strays = strayFragmentsOf(dirname(selfAbs), null)
+  const pendingBody = !close && pending && typeof pending.body === "string" && pending.body.trim() ? pending.body : null
+  const fragAbs = pendingBody ? fragmentPathOf(selfAbs) : null
+  // 改写后的整档视图（`edit` 面——锚类判它，不判盘上旧字节：本批要消的正是「死引文那行改不动」那个死锁）。
+  const viewBody = !close && pending && typeof pending.recordView === "string" ? pending.recordView : null
+  const viewAbs = viewBody === null ? null : fragmentPathOf(selfAbs)
+  // 判域内「哪一档是批档本体」：有视图时 = 视图（同目录、同骨架、同引用解析序）；判据与属性标注都读它。
+  const selfKey = pathKey(viewAbs ?? selfAbs)
+
+  try {
+    // 片段档写在 try 内：写失败也走同一条 finally（不存在就 unlink 失败无害）
+    if (fragAbs) writeFileSync(fragAbs, pendingBody.endsWith("\n") ? pendingBody : `${pendingBody}\n`)
+    if (viewAbs) writeFileSync(viewAbs, viewBody)
+    const docs = close ? [...touched, ...diffDocs, selfAbs] : [...touched, viewAbs ?? selfAbs, ...(fragAbs ? [fragAbs] : [])]
+    const res = runDocCheck(root, { mode: "gate", docs, docsSource: close ? "explicit" : "session" })
+    const basis = !close
+      ? (pendingBody ? "pending+touched" : "touched")
+      : diff.ok ? "touched+diff" : "touched（基 sha 未定）"
+
+    // 批档自身（或它的改写后视图）恒在判域（在盘即入）⇒ 判域恒非空，「0 档」这一形不可达。不成立 = 构造异常 ⇒ fail-closed，不产 PASS。
+    if (!res.checkFiles.some((p) => pathKey(p) === selfKey)) {
+      return errorState("DOC-CHECK GATE: ERROR（判域为空——批档自身应恒在判域）", { count: res.checkFiles.length, k: 0, basis })
+    }
+
+    const selfRel = relative(root, selfAbs).replace(/\\/g, "/")
+    const fragRel = fragAbs ? relative(root, fragAbs).replace(/\\/g, "/") : null
+    const viewRel = viewAbs ? relative(root, viewAbs).replace(/\\/g, "/") : null
+    const translate = (text) => {
+      let out = fragRel ? text.split(fragRel).join("本次写入文本") : text
+      return viewRel ? out.split(viewRel).join(selfRel) : out // 视图档显示成批档自身的相对路径（读者不必知道临时档名）
+    }
+    const { aligned, entries } = hitEntries(res, root, translate)
+
+    const selfSrc = viewBody ?? safeRead(selfAbs)
+    const authors = authorMapOf(selfSrc)
+    const labeled = entries.map((e) => {
+      const inSelf = pathKey(e.file) === selfKey
+      return { ...e, inSelf, text: inSelf ? `${e.text}${attributionOf(selfSrc, e.line, authors)}` : e.text }
+    })
+    // ① 面（**按动作分两种**——判集单源 = `BATCH-RECORD.md` §4.9 门 ④ 判集两句）：
+    //   append（无视图）⇒ 批档已落段命中只明示、不阻写（追加不碰既有行，拒一个改不动的人 = 无账之笔）；其余当场拒。
+    //   edit（有视图）⇒ **判集两类**：档内**锚类**命中当场拒（引用完整性是档级属性）；档内**段长类**命中只明示
+    //     （段长类只判 `newText`——那条在片段档里判，不在这里）。
+    // ② 面：范围内全部命中即 K。
+    const blocks = (e) => !e.inSelf || (viewAbs !== null && ANCHOR_CLASSES.has(e.clazz))
+    const disclosed = close ? [] : labeled.filter((e) => !blocks(e))
+    const forced = close ? labeled : labeled.filter(blocks)
+    const k = forced.length
+    const forcedLines = forced.map((e) => e.text)
+    const disclosedLines = disclosed.map((e) => e.text)
+
+    const inFrag = (e) => !!fragAbs && pathKey(e.file) === pathKey(fragAbs)
+    const textHits = forced.filter(inFrag)
+    const recordHits = forced.filter((e) => e.inSelf) // 仅 edit 面可达：整档锚类命中
+    const touchHits = forced.filter((e) => !inFrag(e) && !e.inSelf)
+    let first = "DOC-CHECK GATE: PASS"
+    if (k >= 1) {
+      if (close) {
+        first = `DOC-CHECK GATE: REFUSED（命中 ${k} 条）`
+      } else {
+        const parts = []
+        if (textHits.length) parts.push(`本次写入文本（${classifyCounts(textHits)}）`)
+        if (recordHits.length) parts.push(`批档整档（${classifyCounts(recordHits)}）`)
+        if (touchHits.length) parts.push(`触达账（${classifyCounts(touchHits)}）`)
+        first = `DOC-CHECK GATE: REFUSED（命中 ${k} 条——${parts.join(" · ")}）`
+      }
+    }
+
+    // 附加行（不静默面）：命中行不可对齐 / 收口面取不到基 / 拒后零字节 / 本次文本已判行数 /
+    // 已落段命中（谁该改、为什么不阻本次写）/ 同目录片段档残留（只明示、不代删）。
+    const notes = []
+    if (!aligned) notes.push("命中行不可对齐（引擎报面 ✗ 行数与命中数不等）——显示行按自造形，判定按命中对象")
+    if (close && !diff.ok) notes.push("基 sha 未定——本批笔域集只认触达账")
+    if (!close && k >= 1) {
+      notes.push("本次写入文本尚未落盘——一个字没写（档字节逐字不变：append 面另有段号不前进、轮次 N 不推进；edit 面另有目标区间以外逐字不变）")
+    }
+    if (!close && k === 0 && pendingBody) {
+      const segLabel = Number.isInteger(pending?.section) ? `§${pending.section}` : "本段"
+      const lineCount = pendingBody.split("\n").length
+      notes.push(viewAbs !== null
+        ? `本次写入文本（${segLabel}）${lineCount} 行已判——段长类只判这一段（档内既有超长段不进你的拒面）；锚类判整档（引用完整性是档级属性）`
+        : `本次写入文本（${segLabel}）${lineCount} 行已判——强制集只有这一段（别人的段字面改不动，不进你的拒面）`)
+    }
+    if (disclosed.length) {
+      const list = disclosed.map((e) => landedSummary(selfSrc, e, authors)).join(" · ")
+      notes.push(viewAbs !== null
+        ? `档内段长类命中 ${disclosed.length} 条：${list}—— 段长类判集 = 本次写入文本，档级旧段不入判、不阻本次写；收口面 fail-closed 会拦`
+        : `已落段命中 ${disclosed.length} 条：${list}—— 不属本次笔面，不阻本次写；收口面 fail-closed 会拦`)
+    }
+    if (strays.length) {
+      notes.push(`\`.gate-*\` 残留 ${strays.length} 档（异常退出的片段档）—— 手工删除后再提交`)
+    }
+    // 声明面坏而门照判：manifest 非法 JSON 时判据参数 = 引擎内置常量、不读声明面 ⇒ 行为本身正确
+    // （比短路成「未跑」强——一份坏档不该把整个门关掉）。但那一支过去**不点名**，收口人看不出
+    // 声明面已坏；与 `missing` 支「未跑（本项目无声明面）」的明示不对称 ⇒ 两种坏法一种明示一种沉默。
+    if (!read.ok && read.reason === "invalid") {
+      notes.push("声明面不可解析（`PROJECT-MANIFEST.json` 非法 JSON）—— 判据参数为引擎内置常量，本轮仍已判")
+    }
+
+    // 处置块只看**段**类命中——设计口径是「只要存在该类命中就出」，没按「谁写的」切；
+    // 仅锚 ∥ 仅行命中不得叫人对段落动手（叫错方向比不给方向贵）——类名单源 = 引擎的 `DOC_CLASS`。
+    // edit 面只看**强制集**：档内段长类命中不入本次判集，把它们摆进拒面 = 把写者叫去改一段与本笔无关的文字。
+    const disposePara = (viewAbs !== null ? forced : labeled).some((e) => e.clazz === DOC_CLASS.para)
+    return {
+      state: k >= 1 ? "refused" : "pass",
+      first,
+      report: composeReport({
+        first, forcedLines, disclosedLines, notes, disposePara,
+        disclosedHeader: viewAbs !== null ? "—— 档内段长类命中（只明示、不阻本次写；段长类判集 = 本次写入文本）：" : undefined,
+      }),
+      hitLines: forcedLines,
+      noteLines: notes,
+      // 处置面分形用（拒串读它：段命中 ⇒ 五行块 ∥ 仅锚·仅行 ⇒ 照旧一句处置）
+      disposePara,
+      range: { count: res.checkFiles.length, k, basis },
+    }
+  } finally {
+    if (viewAbs) { try { unlinkSync(viewAbs) } catch { /* 清理失败不覆盖判定结果——残留由下一次门明示 */ } }
+    if (fragAbs) { try { unlinkSync(fragAbs) } catch { /* 清理失败不覆盖判定结果——残留由下一次门明示 */ } }
   }
 }
 
 /** 成功回执行（append / close / status 三面同形；`null` 门 ⇒ 零改——非挂门路径回执逐字旧形）。
- *  两件 = verdict + `范围 N 档` 事实行；附注行（「基 sha 未定」∥ 命中行不可对齐）紧随其后**逐字**列出——
- *  不静默吞掉可见性。 */
+ *  两件 = verdict + `范围 N 档` 事实行；附注行（「基 sha 未定」∥ 命中行不可对齐 ∥ 已落段命中 ∥ 片段档残留）紧随其后
+ *  **逐字**列出——不静默吞掉可见性。 */
 export function gateReceiptLine(gate) {
   if (!gate) return ""
   if (gate.state === "not-applicable") return "\n[doc-check gate] 未跑（本项目无声明面）"
@@ -190,16 +390,30 @@ export function gateReceiptLine(gate) {
 }
 
 /**
- * 拒绝串（throw 载荷；两机械点同源措辞）：`batch:` 前缀 + verdict 首行 + 逐条 `✗` 行 + 处置句；
- * ① 追加同路既有句「失败 ⇒ 勿 close」（字面同 append 既有拒因，不新造措辞）。
+ * 拒绝串（throw 载荷；两机械点同源措辞）：`batch:` 前缀 + verdict 首行 + 逐条 `✗` 行 + 附注行 + 处置面。
+ * **处置面按命中类分形**（本批裁定）：
+ *   · 段命中 ⇒ **空行 + 五行处置块**（字面单源 = 引擎的 `PARA_DISPOSE`）。块末行逐字就是「同轮修正后复跑；不转台账」，
+ *     故旧尾句那一截删去——留着就是两句「处置：」+ 一句重复；收尾的裁决指引与「Nothing was written」两句不重复，随原因面照出。
+ *   · 仅锚 ∥ 仅行命中 ⇒ **照旧一句**（那五条出路是给「段」的，对错误的面对动手比不给方向更贵）。
+ * ① 写盘面两路（`append` 段尾 ∥ `edit` 段内区间）同路既有句「失败 ⇒ 勿 close」（字面同 append 既有拒因，不新造措辞）。
  */
 export function gateRefusalMessage(gate, action = "append") {
-  const lead = action === "append"
-    ? "batch: 文档机检门拒写（doc-check gate · 结构兜底 ①）—— 本次段写入未落盘，档字节不变。"
-    : `batch: 文档机检门拒收口（doc-check gate · 结构兜底 ②）—— ${action === "close" ? "close" : "status → 已收口"} 被拒绝，§1 状态行字节不变。`
+  const writeFace = action === "append" || action === "edit" // 写盘面两路：段尾追加 ∥ 段内区间改写
+  const lead = action === "edit"
+    ? "batch: 文档机检门拒写（doc-check gate · 结构兜底 ①）—— 本次段内就地改未落盘，档字节不变。"
+    : writeFace
+      ? "batch: 文档机检门拒写（doc-check gate · 结构兜底 ①）—— 本次段写入未落盘，档字节不变。"
+      : `batch: 文档机检门拒收口（doc-check gate · 结构兜底 ②）—— ${action === "close" ? "close" : "status → 已收口"} 被拒绝，§1 状态行字节不变。`
   const detail = gate.state === "error" ? String(gate.report ?? "").split("\n").slice(1) : gate.hitLines
-  const tail = action === "append"
-    ? "处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close)."
-    : "处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。Nothing was written."
-  return [lead, gate.first, ...(detail ?? []), ...(gate.noteLines ?? []), tail].join("\n")
+  const routing = "拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）。"
+  // 尾句按动作取形：`edit` 拒后段里本就有内容，劝「勿 close」把两件事说成一件（那句防的是收口冻结一个空段）。
+  const noBytes = writeFace
+    ? action === "edit"
+      ? "Nothing was written — the target range and every other byte of the record are unchanged."
+      : "Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close)."
+    : "Nothing was written."
+  const head = [lead, gate.first, ...(detail ?? []), ...(gate.noteLines ?? [])]
+  // 段命中：原因面 + 空行 + 五行块（处置面 = 块，不再另起一句「处置：同轮修正后复跑…」）
+  if (gate.disposePara) return [...head, `${routing}${noBytes}`, "", ...PARA_DISPOSE].join("\n")
+  return [...head, `处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；${routing}${noBytes}`].join("\n")
 }

package/agent-tools/batch-ledger-bind.mjs

@@ -0,0 +1,183 @@
+/**
+ * agent-tools/batch-ledger-bind.mjs — 建档 = 建台账行（一件事；从 `batch-lifecycle.mjs` 拆出，2026-10-27）。
+ *
+ * 权威规格 = `docs/core/design/BATCH-LEDGER-REVIEW-UNIFY.md` §2.4。用户裁定（2026-10-27 11:40）：
+ * 「如果已有台账，可以在创建时把台帐号传进去，没有就要创建台账。」——建档与台账登记不再是两步靠自觉，
+ * 是同一个动作的两次落笔：`batch({action:"create"})` 一次调用，档与行同时成立，否则两边都不成立。
+ *
+ * **步序不能换**（§2.4，第 3 轮评审的 🔴）：
+ *   `BEGIN IMMEDIATE` → （新建）INSERT 一行 `待讨论`（无指针、`trigger` 不填）→ `writeRecord(#N)` 写批档
+ *   （`wx` 独占创建）→ `applyRowUpdateTx` 迁 `在途` + 写 `task_book`（过写门）→ `COMMIT`。
+ *   写门两形都判「解析出的档在盘」（在册旧形 ∥ 新形臂②）——先写指针、后落档，会被自己的门当场拒。
+ *   `在途` 行的 DDL 咬合 CHECK（`docs/core/design/LEDGER.md` §2.2）又封死「先 INSERT `在途`、后落档」，
+ *   所以第一笔只能是一条不带指针的 `待讨论`，`待讨论 → 在途` 因此是**必经一步**。
+ *
+ * 失败清理只删**本笔所建**的档：步 3 是 `wx` 独占创建，撞已有同名档时抛 EEXIST，无条件 unlink 会删掉
+ * 别人的档（第 4 轮评审 🟡2）。`created` 旗由写回调置位，清理只认它。
+ *
+ * 依赖单向（KD-4）：`skeleton ← closeout ← bind ← reopen ← lifecycle`——本档不 import lifecycle。
+ */
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs"
+import { dirname, relative } from "node:path"
+
+import { batchSkeleton } from "./batch-skeleton.mjs"
+import { resolveBatchCreatePath } from "./batch-paths.mjs"
+
+/** 可读文件判据（存在且为文件——目录/缺失同判不可读；与主档同名 helper 同型——KD-4 单向依赖下各自持有，
+ *  三行谓词不构成第二权威源）。 */
+function readableFile(abs) {
+  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
+}
+
+/** main-agent-only 门（BR-19/BR-24）：create 仅 depth-0 放行（eng 子代理 / 评审皆拒）。 */
+function assertMainAgentOnly(ctx, action, review) {
+  if (review || ctx?.depth !== 0) {
+    throw new Error(`batch: ${action} is main-agent-only — ${action} manages the record lifecycle and is depth-0 only (eng sub-agents and design reviews are refused).`)
+  }
+}
+
+/** 档头可选参归一（`board`）：trim ∥ 单行（拒句逐字）∥ 空串 ≡ 未给（null）。 */
+function normalizeBoard(raw) {
+  const v = typeof raw === "string" ? raw.trim() : ""
+  if (!v) return null
+  if (/\r?\n/.test(v)) {
+    throw new Error("batch: create board must be a single line — a multi-line value would break the header's 台账 line. Nothing was written.")
+  }
+  return v
+}
+
+/** `ledger` 参解析：缺省 / 空 ⇒ `null`（新建一行）；否则取行号（`#1830` ∥ `1830` ∥ 数字）。 */
+function parseLedgerNo(raw) {
+  const v = typeof raw === "string" ? raw.trim() : raw
+  if (v == null || v === "") return null
+  const m = /^#?\s*(\d+)$/.exec(String(v).trim())
+  if (!m) {
+    throw new Error(`batch: ledger must be a ledger entry number (e.g. "#1830") — got ${JSON.stringify(raw)}. Pass an existing number, or omit ledger — with no unsettled row on the same face that opens a new row; otherwise pass newDebt:"<why this is a new debt>". Nothing was written.`)
+  }
+  return Number(m[1])
+}
+
+/** `newDebt` 参归一（设计档 §6.3「参数面」）：trim；空串 / 全空白 ⇒ `null`（按未给判——没声明新事）。 */
+function normalizeNewDebt(raw) {
+  const v = typeof raw === "string" ? raw.trim() : ""
+  return v || null
+}
+
+/** 同面判回执增量（设计档 §6.3「回执增量（成功路径）」逐字）：面名 + 本面未决数 + 他面未决读数。
+ *  `n = 0` 半幅也打（免得把「本面无候选」读成「池子空」——他面读数同列）；接手路径无此段（该径零判）。
+ *  `declared` 缺省 ⇒ `—`（本仓「无值」的既有形，同档头 `台账 = #N（… · —）`）。 */
+function sameFaceReceiptLine(check) {
+  if (!check) return ""
+  return `\nsame-face check: face = ${check.face ?? "no board"} · unsettled on this face = ${check.n} (n = 0 ⇒ nothing to take over; n > 0 ⇒ declared a new debt: ${check.declared ?? "—"}) · unsettled on other faces = ${check.m} (a reading; never blocks).`
+}
+
+/**
+ * create——建档（§4.11 + §2.4，仅 depth-0）：六段骨架一次预齐，台账行同拍成立。
+ * 不传 `ledger` ⇒ 新建一行（`在途` · `kind` = `board` 给则 `requirement` 否则 `tech_todo` · `title` = `topic` ·
+ * `task_book` = 本档相对指针 · `trigger` = 归批）——**同面（本笔 `board`）无未决行时如此；有则须 `newDebt:"<一句理由>"`，
+ * 两者皆无 ⇒ 拒并列候选**（设计档 `docs/core/design/LEDGER.md` §6.3）；传 `#N` ⇒ 接管该行（`待讨论` / `待设计` → `在途`；
+ * `在途` 且指针指回本档 ⇒ 零台账写；其余 ⇒ 三形拒文，见 §2.4）。
+ * 档头 `台账` 行由**真实行号**填（`board` 未给 ⇒ 括注 `—`，不拒）。
+ * @returns {Promise<string>} 成功消息（含落盘绝对路径、行号与同面判读数）
+ */
+export async function createBatchRecord({ args, ctx, review, cwd, bases, onWritten }) {
+  assertMainAgentOnly(ctx, "create", review)
+  const raw = typeof args?.path === "string" ? args.path.trim() : ""
+  if (!raw) {
+    throw new Error("batch: create requires path — the new batch record's location (a .md path under the batch base roots, relative or absolute). Nothing was written.")
+  }
+  if (!/\.md$/.test(raw)) {
+    throw new Error(`batch: create path must end in .md — got ${JSON.stringify(raw)} (fail-closed: non-markdown targets are refused). Nothing was written.`)
+  }
+  const primary = bases?.[0]
+  if (!primary) {
+    throw new Error("batch: no batch-record base root is available — fix PROJECT-MANIFEST.json docRoot.batches (or its default) before creating a record. Nothing was written.")
+  }
+  const abs = resolveBatchCreatePath(cwd, raw, bases)
+  if (readableFile(abs)) {
+    throw new Error(`batch: create target already exists — refusing to overwrite an existing batch record (fail-closed, BR-20): ${raw}`)
+  }
+  const topic = typeof args?.topic === "string" && args.topic.trim() ? args.topic.trim() : null
+  if (!topic) {
+    throw new Error("batch: create requires topic — the batch subject word shared by the record header (档名与档头共用——keep the file name aligned with it). Nothing was written.")
+  }
+  const source = typeof args?.source === "string" ? args.source.trim() : ""
+  if (!source) {
+    throw new Error("batch: create requires source — the record's origin line (来源 = …). Pass where this batch came from (the request / discussion that started it); it lands in the header's 编制 line. Nothing was written.")
+  }
+  if (/\r?\n/.test(source)) {
+    throw new Error("batch: create source must be a single line — a multi-line source would break the header's 编制 line. Nothing was written.")
+  }
+  const board = normalizeBoard(args?.board)
+  const ledgerNo = parseLedgerNo(args?.ledger)
+  const newDebt = normalizeNewDebt(args?.newDebt)
+  const date = typeof args?.date === "string" && args.date.trim() ? args.date.trim() : todayLocalIso()
+  // F11-B：prev 幂等 strip——调用方自带「前情 = 」前缀（单或重复）一并剥净；默认值形态「零变」。
+  const prevRaw = typeof args?.prev === "string" ? args.prev.trim() : ""
+  const prev = prevRaw ? (prevRaw.replace(/^(?:前情\s*[=：:]\s*)+/g, "").trim() || "无（独立批）") : "无（独立批）"
+  // 模式位执行期实读（§4.16——骨架取形时点 = 建档即固；翻转不回写既有骨架）
+  const mode = ctx?.agent?.config?.agent?.engineering ? "engineering" : "normal"
+  const anchor = cwd ?? ctx?.agent?.cwd
+  const created = { flag: false }
+
+  // 台账链只经动态 import（ledger-db.mjs 静态引 node:sqlite ⇒ 消费侧静态 import 破 W8 契约②）
+  const { ledgerBindBatch, resolveLedgerRoot } = await import("../ledger.mjs")
+  const root = resolveLedgerRoot(dirname(abs), anchor)?.root ?? null
+  if (!root) {
+    throw new Error(`batch: the new record's project root cannot be derived — the ledger row cannot be opened without it (fail-closed). Path: ${abs}. Nothing was written.`)
+  }
+  const taskBook = relative(root, abs).replace(/\\/g, "/")
+  // executor = 本会话（AC-M2-7「进入在途的迁移带 executor = 会话 sessionId」）——与 `ledger-tools.mjs` 同一取值面
+  let executorSessionId = null
+  try { executorSessionId = (await import("../session-slots.mjs")).getSessionId() } catch { executorSessionId = null }
+  mkdirSync(dirname(abs), { recursive: true })
+  const writeRecord = (id) => {
+    try {
+      writeFileSync(abs, batchSkeleton({ date, topic, source, prev, ledger: `#${id}`, board, mode }), { flag: "wx" })
+    } catch (e) {
+      if (e?.code === "EEXIST") {
+        throw new Error(`batch: create target already exists — refusing to overwrite an existing batch record (fail-closed, BR-20): ${raw}`)
+      }
+      throw e
+    }
+    created.flag = true
+    onWritten?.(ctx?.agent ?? {}, abs)
+  }
+
+  let result
+  try {
+    result = await ledgerBindBatch({
+      cwd: root,
+      ledgerNo,
+      newDebt,
+      targetAbs: abs,
+      taskBook,
+      title: topic,
+      kind: board ? "requirement" : "tech_todo",
+      board,
+      boundary: anchor,
+      executorSessionId,
+      agent: ctx?.agent ?? {},
+    }, writeRecord)
+  } catch (e) {
+    // 失败清理只删本笔所建的档（`created` 旗——撞同名档时我们什么都没建，不得 unlink 别人的档）
+    let residue = ""
+    if (created.flag) {
+      try { unlinkSync(abs) } catch (unlinkErr) { residue = ` 档残留 ${abs}（清理失败：${unlinkErr?.message ?? unlinkErr}）` }
+    }
+    const rollbackNote = e?.ledgerRollbackFailed ? "台账回滚失败——行可能残留，收口前请人工核对。" : ""
+    const note = `${rollbackNote}${residue}`
+    if (!note) throw e
+    const wrapped = new Error(`${e?.message ?? e}${note ? `\n（${note}）` : ""}`)
+    throw wrapped
+  }
+  const took = result.tookOver === "new" ? "opened" : result.tookOver === "live" ? "taken over (already live — zero ledger write)" : "taken over"
+  return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder); ledger row #${result.id} ${took} in the same call (row status = 在途 · task_book = ${taskBook} · trigger = 归批). header 台账 line filled (#${result.id} · ${board ?? "—"}).${sameFaceReceiptLine(result.sameFace)}`
+}
+
+/** 本地今天（YYYY-MM-DD）——create 的缺省 date。 */
+function todayLocalIso() {
+  const d = new Date()
+  const p = (n) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+}