@thincoder/core 0.9.1 → 0.9.3

package/agent-tools/batch-segment.mjs

@@ -1,265 +1,18 @@
 /**
- * agent-tools/batch-segment.mjs — 批次档段写入工具（ENGINEERING-MODE.md §2.20 · FR22 F1-F7）。
- *
- * 规则、守卫与 fail-closed 清单的**权威正文在 §2.20.1**（本文件不重述——D2 单一权威源）；
- * 实现要点（正文未定死、由代码承载）：
- *  - 身份判据 = 评审实例绑定（`review` 形态）/ `agent._role`；
- *  - append-only：在段尾（下一条 `## §N` 或 EOF）插入，既有行字节不变；
- *  - 来源戳 `### 轮次 N（评审子代理）`（仅 §3）——N = §3 内该形态行计数 + 1，**调用方自带**
- *    的同名标题行被丢弃（否则伪造戳会污染 N 计数——§2.20.8 #5）；
- *  - 凭证剥除：含凭证形态的行剥掉该子串，剥后为空则整行丢弃（「零命中」+「其余逐字保留」）；
- *  - 路径门禁：`resolveBatchDocPath`（评审侧「若传则须可读」）；工具内再查一次可读性。
- *  - v2 增量（ENGINEERING-MODE-V2-MODULE-BATCH-SEGMENT.md §2.1）：§1 状态行解析
- *    （`readBatchStatusLine`——「已收口」→ 冻结拒写、「进行中」→ 放行、缺失/不可解析 →
- *    fail-closed 拒）；`resolveBatchDocPath` 加 manifest `docRoot.batches` 双基底
- *    （值形态 = 串 | 多根数组——逐基底按序复判；manifest 缺失/非法/读错 → v1 单基底
- *    语义零变）；冻结只覆盖 `batch_segment` 通道（§2.5）。
- *
- * 导出面：`batchSegmentTool` · `resolveBatchDocPath` · `batchDocForReview`（异步评审实例键取绑定）·
- * `configureBatchSegment` / `resetBatchSegment`（#84 记账面注入缝——缺省 no-op，见下）。
- *
- * #84 记账面（CORE-UNIFICATION §2.13.4）：写入成功后的记账（把绑定档记入调用者写域）
- * **按端注入**（形态参 §2.13.5 注入缝）——核内缺省 no-op = CLI 语义零行为变；端装配
- * 经 `configureBatchSegment({ onWrite })` 覆盖（VSC 侧现形 = `_touchedFiles` 记账）。
+ * agent-tools/batch-segment.mjs — **过渡 shim**（batch 工具单名化收口，BATCH-RECORD §4.14）：
+ * 本档仅 re-export `batch.mjs` 主档导出面（旧 import 面 = VSC `setup-tooltable.mjs` 经此 import
+ * `configureBatchSegment` / 旧测试消费——导出全超集，行为零变）。权威实现 = batch.mjs
+ * （batchTool 四 action + append 迁移面 + 过渡别名 batchSegmentTool）；撤除判据 = §4.14
+ * （消费面清零后删本档——先例债：删档需同步 tooltable 装配 import，随批登记）。
  */
-import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { resolve } from "node:path"
-
-import { docRootPaths, readManifest } from "../manifest.mjs"
-
-/** text 单次上限（§2.20.1——超出引导分段追加，不承诺"不新盖戳"）。 */
-export const MAX_TEXT_CHARS = 20000
-/** 身份 → 可写段号（§2.20.1 段白名单）。 */
-export const SEGMENT_BY_ROLE = { "eng-designer": 2, "eng-coder": 5 }
-/** 工具写入的轮次节标题形态（N 计数口径 = 该形态行；`### 轮次与发现（…）` 骨架行不匹配）。 */
-const ROUND_HEADING_RE = /^### 轮次 \d+（评审子代理）/
-/** 段标题定位（`## §N` 独立标题——`## §20` 不误命中 §2）。 */
-const sectionHeaderRe = (seg) => new RegExp(`^## §${seg}(?=\\s|$)`, "m")
-/** 凭证形态（§2.7 冒号态）：`[DESIGN-TOKEN:…]` 与 `designId: …`——本节自有正则。 */
-const CRED_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/g
-const CRED_TEST_RE = /\[DESIGN-TOKEN:[^\]]*\]|designId\s*:\s*\S+/
-/** §1 状态行前缀（`**状态行**：` 独立行——表格行 / 块引用行不命中；判定只认关键字）。 */
-const STATUS_LINE_RE = /^\s*\*\*状态行\*\*[：:]\s*(.*)$/
-
-// ─── #84 记账面注入缝（「记账面按端注入」，形态参 §2.13.5 注入缝）───────────────
-/**
- * 写入成功后的记账注入面（**缺省 no-op** = CLI 语义零行为变）：端装配层可覆盖——把写成的
- * 批次档记入调用者写域（VSC 侧现形 = `agent._touchedFiles` 记账，供子代理合入 / recent_changes /
- * verify / advisor 默认范围消费）。核内零端名分支（契约 5——本档只认 `onWrite` 函数名）。
- * 形态与 `tools/write-path.mjs` 的 `configureWritePath` 同款：模块级、缺省不覆盖、null 撤销。
- */
-let injectedOnWrite = null
-export function configureBatchSegment(impl) {
-  injectedOnWrite = impl && typeof impl.onWrite === "function" ? impl.onWrite : null
-}
-/** 撤销注入（测试与端装配生命周期用——缺省态 = 零记账）。 */
-export function resetBatchSegment() { injectedOnWrite = null }
-
-/** 可读文件判据（存在且为文件——目录/缺失同判不可读）。 */
-function readableFile(abs) {
-  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
-}
-
-/**
- * 批次档路径门禁（评审侧 §2.20.2 口径 = **「若传则须可读」**）：空/非字符串/不可读 → throw。
- * 非空且可读 → 返回绝对路径（`\` 归一——照 `files`/`batchDoc` spawn 门先例）。
- * v2：cwd 不可读 → manifest `docRoot.batches` 复判（M3 模块设计 §2.1#4——N3 可迁移；
- * 值形态 = 串 | 多根数组——逐基底按序复判，首个可读者胜）。
- */
-export function resolveBatchDocPath(cwd, given) {
-  const base = cwd ?? process.cwd()
-  const raw = typeof given === "string" ? given.trim() : ""
-  if (!raw) {
-    throw new Error("batchDoc must be a non-empty path to the batch record — pass the batch record currently in flight, or omit the parameter entirely when no batch record is in flight.")
-  }
-  const abs = resolve(base, raw.replace(/\\/g, "/"))
-  if (readableFile(abs)) return abs
-  // 双基底（M3 模块设计 §2.1#4）：cwd 不可读 → manifest docRoot.batches 复判（逐基底按序，
-  // 首个可读者胜）；manifest 缺失 / 非法 / 读错 → 无第二基底（v1 单基底语义零变），
-  // 全不可读 → throw。
-  let man = { ok: false }
-  try { man = readManifest(base) } catch { /* 权限等读错——按无 manifest 处理（v1 语义） */ }
-  if (man.ok) {
-    for (const root of docRootPaths(man.manifest?.docRoot?.batches, base)) {
-      const alt = resolve(root, raw.replace(/\\/g, "/"))
-      if (readableFile(alt)) return alt
-    }
-  }
-  throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.`)
-}
-
-/**
- * §1 状态行解析（内部——M3 模块设计 §2.1#1）：解析对象 = §1 段内 `**状态行**：` 前缀行
- * （§1 边界 = `## §1` 标题到下一 `## §` 标题；其他段内「状态行」字样不参与判定）。
- * 判定只认关键字（emoji / 括号装饰 / 日期后缀容忍）：含「已收口」→ "closed"（冻结优先）、
- * 含「进行中」→ "open"；无 §1 / 无该行 / 两关键字皆不命中 → "unknown"（fail-closed 视为冻结）。
- */
-function readBatchStatusLine(src) {
-  const s1 = /^## §1(?=\s|$)/m.exec(src)
-  if (!s1) return "unknown"
-  const nextRe = /^## §\d/gm
-  nextRe.lastIndex = s1.index + s1[0].length
-  const next = nextRe.exec(src)
-  const body = src.slice(s1.index + s1[0].length, next ? next.index : src.length)
-  const m = body.split("\n").map((line) => STATUS_LINE_RE.exec(line)).find(Boolean)
-  if (!m) return "unknown"
-  const value = m[1].trim()
-  if (value.includes("已收口")) return "closed"
-  if (value.includes("进行中")) return "open"
-  return "unknown"
-}
-
-/**
- * 设计评审的实例绑定解析（§2.20.2/§2.20.3——batch_segment 的唯一路径来源）：
- *  - 同步路径：调用方（advisor 工具）把实例绑定显式放进 callbacks（**带 batchDoc 键**，
- *    未绑定即 null）——以此为准，不再回看池条目（防同步/异步混跑时串档）；
- *  - 异步路径：本评审所在**池条目**的 `run.batchDoc`（文档集 = 实例键，各评审各取各条）。
- */
-export function batchDocForReview(agent, documents, callbacks = null) {
-  if (callbacks && "batchDoc" in callbacks) return callbacks.batchDoc ?? null
-  const key = JSON.stringify([...(documents ?? [])].sort())
-  for (const e of agent?._asyncAdvisors?.values?.() ?? []) {
-    if (e.status === "running" && e.reviewType === "design" && JSON.stringify([...(e.documents ?? [])].sort()) === key) {
-      return e.run?.batchDoc ?? null
-    }
-  }
-  return null
-}
-
-/** 段号解析：`§2` / `2` / `§2 批次任务` 均可；无法解析 → null。 */
-function segmentNumber(raw) {
-  const m = /^§?\s*(\d+)/.exec(String(raw ?? "").trim())
-  return m ? Number(m[1]) : null
-}
-
-/** 身份 → 可写段号；无写权身份 → null。评审实例绑定优先（评审者的身份即"设计评审"。） */
-function allowedSegment(agent, review) {
-  if (review) return 3
-  return SEGMENT_BY_ROLE[agent?._role] ?? null
-}
-
-/**
- * 凭证剥除 + 伪造轮次标题丢弃（§2.20.1 F6/AC30/AC34）。
- * 逐行处理：含凭证形态的行 → 剥除该子串，剥后为空则整行丢弃（其余内容逐字保留）。
- * `dropStamp`（仅 §3 目标段）：调用方自带的 `### 轮次 N（评审子代理）` 行被丢弃——
- * 工具生成才是唯一来源戳（否则伪造戳会污染 N 计数）。
- */
-function sanitizeText(text, dropStamp) {
-  const kept = []
-  for (const line of text.replace(/\r\n?/g, "\n").split("\n")) {
-    if (dropStamp && ROUND_HEADING_RE.test(line)) continue
-    if (!CRED_TEST_RE.test(line)) { kept.push(line); continue }
-    const cleaned = line.replace(CRED_RE, "").replace(/[ \t]+$/, "")
-    if (cleaned.trim()) kept.push(cleaned)
-  }
-  return kept.join("\n")
-}
-
-/** §3 内工具写入的轮次行计数（N = 计数 + 1；收窄口径——只数工具戳形态）。 */
-function roundCount(src, headerMatch, endIdx) {
-  const body = src.slice(headerMatch.index + headerMatch[0].length, endIdx)
-  return body.split("\n").filter((l) => ROUND_HEADING_RE.test(l)).length
-}
-
-/** 段尾定位 + 插入（append-only：只在段尾插入，既有字节不变；返回新全文 + 本轮 N）。 */
-function insertIntoSection(src, seg, text) {
-  const hdr = sectionHeaderRe(seg).exec(src)
-  if (!hdr) {
-    throw new Error(`batch_segment: the bound batch record has no "## §${seg}" section header — the six-section skeleton is written by the record's creator before any segment write. Fix: ask the parent/creator to add the "## §${seg} …" heading (with the template's sub-headings) first, then call batch_segment again. Nothing was written.`)
-  }
-  const nextRe = /^## §\d/gm
-  nextRe.lastIndex = hdr.index + hdr[0].length
-  const next = nextRe.exec(src)
-  const endIdx = next ? next.index : src.length
-  // 来源戳（仅 §3）：工具生成标题 + N——调用方写不进自己的标题（sanitize 已丢弃同名行）。
-  const roundN = seg === 3 ? roundCount(src, hdr, endIdx) + 1 : 0
-  const payload = (seg === 3 ? `### 轮次 ${roundN}（评审子代理）\n\n` : "") + text
-  const before = src.slice(0, endIdx)
-  const after = src.slice(endIdx)
-  const eol = src.includes("\r\n") ? "\r\n" : "\n"
-  const lead = before === "" ? "" : before.endsWith(eol + eol) ? "" : before.endsWith(eol) ? eol : eol + eol
-  // 尾随 eol 恒加（块自成行）；后面还有段标题时再补一个空行（保持模板的空行分隔）。
-  const written = before + lead + payload.replaceAll("\n", eol) + eol + (after === "" ? "" : eol) + after
-  return { written, roundN }
-}
-
-/**
- * 批次档段写入工具工厂。
- * @param {string|null} batchDoc — 绑定的目标档（spawn：`child._batchDoc`；评审：实例键）
- * @param {{review?: boolean}} [opts] — review=true 表示"设计评审实例"形态（写 §3 + 工具盖戳）
- */
-export function batchSegmentTool(batchDoc = null, { review = false } = {}) {
-  const own = review ? "§3" : null
-  return {
-    name: "batch_segment",
-    description:
-      "Append your own section of the batch record (一段一作者). " +
-      "There is NO path parameter: the target record is bound to you (at spawn for eng-designer/eng-coder, per review instance for a design review) and your identity fixes the section you may write " +
-      "(eng-designer → §2, design review → §3, eng-coder → §5) — a write outside your own section is refused. " +
-      "Append-only: the text lands at the end of your section; existing lines are never rewritten or deleted. " +
-      "Credential values are stripped mechanically before writing (never write a token or designId value). " +
-      "A design review's append is stamped by the tool with a `### 轮次 N（评审子代理）` heading — N is tool-counted; do not write your own heading (it would be dropped). " +
-      "Failures are hard and visible (no silent fallback): if the write is refused or fails, say so in your report — “§× 未写入”.",
-    parameters: {
-      type: "object",
-      properties: {
-        segment: {
-          type: "string",
-          description: `The batch-record section you are writing${own ? ` — yours is ${own}` : ""}. Declares the section number only; your identity decides what is actually writable.`,
-        },
-        text: {
-          type: "string",
-          description: "The markdown to append (verbatim — findings table + VERDICT + counts for a design review §3). Limit 20000 characters per call; longer content is refused — split it into multiple calls (each call becomes its own section, N continues).",
-        },
-      },
-      required: ["segment", "text"],
-    },
-    async execute(args, ctx) {
-      const agent = ctx?.agent ?? {}
-      const seg = allowedSegment(agent, review)
-      if (seg === null) {
-        throw new Error("batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); the parent agent writes §1/§4/§6 through ordinary document writes.")
-      }
-      const n = segmentNumber(args?.segment)
-      if (n === null) {
-        throw new Error(`batch_segment: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}").`)
-      }
-      if (n !== seg) {
-        throw new Error(`batch_segment: §${n} is not yours to write — this caller writes §${seg} only (一段一作者: eng-designer → §2, design review → §3, eng-coder → §5).`)
-      }
-      if (!batchDoc) {
-        throw new Error("batch_segment: no batch record is bound to this caller — there is no path parameter by design (the target arrives via the spawn binding / the review instance key). Report the section as not written.")
-      }
-      const abs = resolveBatchDocPath(agent.cwd ?? process.cwd(), batchDoc)
-      const src = readFileSync(abs, "utf8")
-      const status = readBatchStatusLine(src)
-      if (status === "closed") {
-        throw new Error("batch_segment: 已收口档不回改 — the bound batch record's §1 status line contains 「已收口」, so the record is frozen: its body is never written to again (整档冻结；改 = 新批新档). Nothing was written. Report the section as not written.")
-      }
-      if (status === "unknown") {
-        throw new Error("batch_segment: 状态行不可解析或缺失 — the bound batch record has no §1 `**状态行**：` line whose value contains 已收口 or 进行中 (fail-closed: the write is refused as if frozen). Ask the record's creator to set the §1 status line, then call again. Nothing was written.")
-      }
-      if (typeof args?.text !== "string") {
-        throw new Error("batch_segment: text must be a string (the markdown to append).")
-      }
-      if (args.text.length > MAX_TEXT_CHARS) {
-        throw new Error(`batch_segment: text is ${args.text.length} characters — the limit is ${MAX_TEXT_CHARS} per call. Split it into multiple calls: each call becomes its own section and the round number N continues (分段追加——每次调用各成节、N 顺延).`)
-      }
-      if (/^## §\d/m.test(args.text)) {
-        throw new Error("batch_segment: the text contains a section header line matching `^## §N` — that would break section location and the append-only guarantee. Rewrite it (escape the heading, or drop the leading `## §N`), then call again (骨架保护). Nothing was written.")
-      }
-      const body = sanitizeText(args.text, seg === 3).replace(/^\n+/, "").replace(/\s+$/, "")
-      if (!body.trim()) {
-        throw new Error("batch_segment: nothing to append — the text is empty after credential stripping (credential values never reach the record).")
-      }
-      const { written, roundN } = insertIntoSection(src, seg, body)
-      writeFileSync(abs, written)
-      // #84（S1 续轮第二批——VSC 侧并入 ④）：记账面**按端注入**（缺省 no-op = CLI 语义
-      // 零行为变——端装配经 configureBatchSegment 覆盖；VSC 侧现形 = 把绑定档记入调用者
-      // 写域 `_touchedFiles`）。核内不内建记账（设计裁定形态——CORE-UNIFICATION §2.13.4 #84
-      // 「记账面按端注入」）。
-      injectedOnWrite?.(agent, abs)
-      return `batch_segment: appended ${body.length} characters to §${seg} of the batch record${roundN ? ` (### 轮次 ${roundN}（评审子代理）)` : ""}.`
-    },
-  }
-}
+export {
+  MAX_TEXT_CHARS,
+  SEGMENT_BY_ROLE,
+  batchDocBases,
+  batchDocForReview,
+  batchSegmentTool,
+  batchTool,
+  configureBatchSegment,
+  resetBatchSegment,
+  resolveBatchDocPath,
+} from "./batch.mjs"

package/agent-tools/batch-skeleton.mjs

@@ -0,0 +1,156 @@
+/**
+ * agent-tools/batch-skeleton.mjs — 批次档骨架模板 + 状态行机械形态单源（KD-4 拆分档）。
+ *
+ * 本档是纯常量/纯函数单源（零副作用、零 fs）：`batch` 工具的 create 骨架、STATUS_WORDS
+ * 分段词表、状态行形态与解析全部只住这里——其他档 import 消费，**不复制字面**
+ * （BATCH-RECORD.md §4.10 / §4.12 / D-BR19；轮 2 #8——骨架占位状态行由 STATUS_WORDS §1 项
+ * 引用生成，全仓无第二份独立词表字面）。
+ *
+ * 状态行解析（readBatchStatusLine）住本档的理由：冻结门（append/status 写前判定）与
+ * lifecycle（status/close 写入、在飞批扫描）消费**同一个解析器**——解析单源即 gate 与
+ * 生命周期三 action 的判定字面零漂移。
+ *
+ * 段标题定位（sectionHeaderRe）同住本档：append 段尾定位与 status/close 段内状态行定位
+ * 消费**同一个段头正则**——`## §N` 形态单源（`## §20` 不误命中 §2）。
+ *
+ * F11-C（本批）：**骨架死占位枚举**（TEMPLATE_PLACEHOLDERS）与残留扫描纯函数
+ * （findPlaceholderResidue）同住本档——与骨架模板共址即判据不会与模板脱节。
+ */
+/**
+ * 段标题定位（`## §N` 独立标题——`## §20` 不误命中 §2）。
+ */
+export const sectionHeaderRe = (seg) => new RegExp(`^## §${seg}(?=\\s|$)`, "m")
+/**
+ * STATUS_WORDS——状态行合法关键字**分段词表常量单源**（D-BR19 / fix 轮 #1；轮 2 #3 裁定②）：
+ *  - §1 项 = gate 词表 `{ open: 进行中, closed: 已收口 }`——**gate 只消费 §1 项**（单源仍成立）；
+ *  - §2/§3/§5 各带段内生命周期词表（`done` 词 = 段属主的完成态关键字）；
+ *  - §4/§6 无项——主 agent 的 status 写域**仅 §1**（§4/§6 状态面走普通文档写，与 D-BR18 分工一致）。
+ * 词面纪律（最小词面）：一条状态行值只带**一个**关键字——校验面（batch 工具 status）拒绝
+ * 内嵌另一冻结词的值（含「进行中…已收口」双词 ⇒ 已收口优先误冻结——2026-09-20 词面纪律）。
+ * emoji / 括注 / 日期后缀容忍（**读侧** gate 判定 = 子串包含，同 gate——写入面 value 谓词
+ * 自本批起收紧为「剥装饰白名单后余核 = 关键词」，见 batch-lifecycle.mjs）；
+ * 全词表并集 = 各段项去重集合（note 字段零命中的判据面——括注永不误触 gate）。
+ */
+export const STATUS_WORDS = Object.freeze({
+  1: Object.freeze({ open: "进行中", closed: "已收口" }),
+  2: Object.freeze({ open: "进行中", done: "设计完成" }),
+  3: Object.freeze({ open: "进行中", done: "评审完成" }),
+  5: Object.freeze({ open: "进行中", done: "实施完成" }),
+})
+
+/** 身份 → 可写段号（append 段白名单的**子代理面**——原 batch-segment.mjs 逐字迁移；主 agent
+ *  的 depth-0 白名单（append = §1/§4/§6 · status = §1——轮 2 #3 裁定②）由身份判据在
+ *  batch.mjs / batch-lifecycle.mjs 分支，不经本表。旧 batch-segment.mjs 导出面等价保持——
+ *  本符号经 batch.mjs re-export（过渡 shim 面零触）。 */
+export const SEGMENT_BY_ROLE = { "eng-designer": 2, "eng-coder": 5 }
+
+/** §1 状态行前缀形态（`**状态行**：` 独立行——表格行 / 块引用行不命中；判定只认关键字）。 */
+export const STATUS_LINE_RE = /^\s*\*\*状态行\*\*[：:]\s*(.*)$/
+
+/**
+ * 骨架死占位**枚举单源**（F11-C 判据面——create 骨架产出过的全部死占位字面）：
+ *  - `#<编号>` / `<板块>` = 现行骨架仍在产出的两处（台账行——填充人 = 主 agent，时点 =
+ *    建档后、本档首个 append/status 之前）；
+ *  - `<BATCH-ID>` / `<讨论来源>` = 改形**删除**的两处旧占位（create 不再产出；旧档残留同判）。
+ * 判据 = 枚举而非泛形正则：`<[^>]{1,40}>` 一类泛形会误杀正文合法尖括号（`Error: <message>` /
+ * 泛型 `Array<T>` / 讨论字面本身）与 `<§N 模板占位：…>` 合法暂存行（append 不删行——段内留存
+ * 是常态）——设计档 `TOOLS.md` 6.15 裁定点④。
+ */
+export const TEMPLATE_PLACEHOLDERS = ["<BATCH-ID>", "<讨论来源>", "#<编号>", "<板块>"]
+
+/**
+ * 死占位残留扫描（F11-C——append/status 落笔前的机检；**纯函数 · 零 fs**）。
+ * 判定域 = **档头**（档首行起至首个 `## §N` 段头前）+ **本次目标段**段内——他段模板占位不归
+ * 本段作者管（一段一作者：§2 作者扫 §5 的占位 = 越权）。
+ * @param {string} src — 档全文
+ * @param {number|string} seg — 本次目标段号（`2` / `"2"`——同 sectionHeaderRe 消费形）
+ * @returns {Array<{line: number, text: string, where: "header"|"section"}>} 残留列表（空 = 无残留）；
+ *   `line` = 所在判定域内 1-based 行号（档头域自档首行起 · 段域自 `## §N` 标题行起——便于定位），
+ *   `text` = 命中行 trim 原文，`where` = 命中域（档头 / 目标段——错误句标注位置用）
+ */
+export function findPlaceholderResidue(src, seg) {
+  const out = []
+  const scan = (text, where) => {
+    text.split("\n").forEach((line, i) => {
+      if (TEMPLATE_PLACEHOLDERS.some((ph) => line.includes(ph))) out.push({ line: i + 1, text: line.trim(), where })
+    })
+  }
+  const firstSection = /^## §\d/m.exec(src)
+  scan(src.slice(0, firstSection ? firstSection.index : 0), "header")
+  const hdr = sectionHeaderRe(seg).exec(src)
+  if (hdr) {
+    const nextRe = /^## §\d/gm
+    nextRe.lastIndex = hdr.index + hdr[0].length
+    const next = nextRe.exec(src)
+    scan(src.slice(hdr.index, next ? next.index : src.length), "section")
+  }
+  return out
+}
+
+/**
+ * 占位残留拒绝句（F11-C——append / status 两个挂点共用单源文案；逐行列残留：位置标注 + 行号 + 原文）。
+ * 错误句前缀 = `batch:`（本批新增错误面——与 append 迁移面的 `batch_segment:` 旧面不混）。
+ * @param {Array<{line:number,text:string,where:string}>} residues — findPlaceholderResidue 的返回值（非空）
+ * @returns {string} 完整拒绝句（调用方 throw new Error(...)）
+ */
+export function placeholderResidueError(residues) {
+  const where = (r) => (r.where === "header" ? "档头" : "目标段")
+  const list = residues.map((r) => `  ${where(r)} line ${r.line}: ${r.text}`).join("\n")
+  return "batch: 骨架死占位残留 — the batch record still carries skeleton placeholders (档头 or your target section). " +
+    "Fill them before writing: create ⇒ the main agent fills the header's 台账编号 / 板块 placeholders ⇒ the record's first append/status opens. " +
+    `Nothing was written. Residue:\n${list}`
+}
+
+
+/**
+ * §1 状态行解析（冻结门与 lifecycle 共用的**单源解析器**——原 batch-segment.mjs 逐字迁移，
+ * 字面「已收口/进行中」改为消费 STATUS_WORDS[1]，行为零变）：解析对象 = §1 段内
+ * `**状态行**：` 前缀行（§1 边界 = `## §1` 标题到下一 `## §` 标题；其他段内「状态行」字样
+ * 不参与判定）。判定只认关键字（emoji / 括号装饰 / 日期后缀容忍）：含「已收口」→ "closed"
+ * （冻结优先）、含「进行中」→ "open"；无 §1 / 无该行 / 两关键字皆不命中 → "unknown"
+ * （fail-closed 视为冻结）。
+ */
+export function readBatchStatusLine(src) {
+  const s1 = /^## §1(?=\s|$)/m.exec(src)
+  if (!s1) return "unknown"
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = s1.index + s1[0].length
+  const next = nextRe.exec(src)
+  const body = src.slice(s1.index + s1[0].length, next ? next.index : src.length)
+  const m = body.split("\n").map((line) => STATUS_LINE_RE.exec(line)).find(Boolean)
+  if (!m) return "unknown"
+  const value = m[1].trim()
+  if (value.includes(STATUS_WORDS[1].closed)) return "closed"
+  if (value.includes(STATUS_WORDS[1].open)) return "open"
+  return "unknown"
+}
+
+/**
+ * create 骨架模板（BATCH-RECORD.md §4.10 行为规格的**代码单源**——红线：模板只覆盖骨架与
+ * 占位，不模板化内容）：`## §1–§6` 段头（含职责署名）+ 档头 boilerplate（六段一段一作者句 +
+ * 编制行 + 台账/前情指针行）+ §1 段内**占位状态行**（含 gate 合法关键字「进行中」——建档即过
+ * gate；整行不含「已收口」——gate 已收口优先，占位行不得携带冻结词）+ 各段模板子标题占位。
+ * 已知实参替换：date / topic / **source** / prev（§4.11 参数面 + F11-B——source 必填、prev 传
+ * 入值过幂等剥前缀，归一化在 lifecycle 面）；档头 `#<编号>` / `<板块>` 仍保持占位字面（台账
+ * 登记 = 主 agent 既有义务，create 不代建——填充时点 = 建档后、本档首个 append/status 之前）。
+ * 本批改形删除（F11-B）：旧 `# …（<BATCH-ID>）` 后缀与 `来源 = <讨论来源>` 占位实参化。
+ */
+export function batchSkeleton({ date, topic, source, prev }) {
+  return [
+    `# ${date} · ${topic}`,
+    "> 六段 append-only，一段一作者：§1 讨论（主 agent）· §2 批次任务与设计（eng-designer）· §3 设计评审（评审子代理）· §4 用户批准（主 agent）· §5 实施记录（eng-coder）· §6 验证与收口（父代理）。",
+    `> 编制：主 agent · ${date} · 来源 = ${source}。`,
+    `> 台账 = #<编号>（<板块> · 归批）。前情 = ${prev}。`,
+    "## §1 讨论（主 agent）",
+    `**状态行**：🔄 ${STATUS_WORDS[1].open}（…）`,
+    "<§1 模板占位：本批条目 / 关键判据 / 授权口径>",
+    "## §2 批次任务与设计（eng-designer）",
+    "**状态行**：（eng-designer 写入时更新）",
+    "<§2 模板占位：本批条目（覆盖） / 设计档落点 / 机制设计 / 受影响文件与测试面 / 验收对照 / 关键决策 / 上抛项>",
+    "## §3 设计评审（评审子代理）",
+    "## §4 用户批准（主 agent）",
+    "## §5 实施记录（eng-coder）",
+    "## §6 验证与收口（父代理）",
+    "",
+  ].join("\n")
+}