@thincoder/core 0.10.9 → 0.10.11

package/agent-tools/advisor.mjs

@@ -9,10 +9,9 @@
  */
 import { runAdvisorReview, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { resolveBatchDocPath } from "./batch.mjs"
-// M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——单一权威源 =
-// review-facts.mjs 的 resolveReviewDocPaths（2026-10-04 · #921 · KD-2——分类四分支 + B 文案
-// 诊断数据单源；write-gate 同名再出口保 normAbs 面）。不 import dispatch.mjs（簇间回边，环风险）。
-import { normAbs } from "../agent/write-gate.mjs"
+// 设计评审的文档受理面单源 = review-facts.mjs 的 resolveReviewDocPaths（判据正文 =
+// docs/core/design/ADVISOR-GUARDS.md §12：相对形按会话项目根 / 绝对形照用 / 受理 = 项目内现存 `.md`）。
+import { projectRootView } from "../manifest-discovery.mjs"
 import { resolveReviewDocPaths } from "./review-facts.mjs"
 import {
   generateDesignToken,
@@ -62,7 +61,7 @@ export const advisorTool = {
       documents: {
         type: "array",
         items: { type: "string" },
-        description: "Doc paths to review (design / requirements / referenced docs). Relative paths resolve against the session cwd first, then candidate project roots (project-root-relative e.g. <repo>/docs/…, or absolute). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
+        description: "Doc paths to review (design / requirements / referenced docs). One rule: a relative path resolves against the session project root (e.g. docs/core/design/ADVISOR-GUARDS.md); an absolute path is used as-is. Accepted = an existing .md file anywhere inside a project (a repo-root doc such as METHODOLOGY.md counts); anything else is refused with the resolved path, the reason, and the two expected forms. The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
       },
       batchDoc: {
         type: "string",
@@ -111,36 +110,21 @@ export const advisorTool = {
       )
     }
 
-    // Design review: the review scope must be documentation files. Classification =
-    // resolveReviewDocPaths (2026-10-04 · #921 · the four-leg single authority in
-    // review-facts.mjs): legs ① session-root set / ② owning-project root set keep the
-    // legacy behavior verbatim; leg ③ probes candidate project roots for bare
-    // project-root-relative forms; leg ④ disambiguates by readable-file uniqueness
-    // (fail-closed — criterion=scope-doc-ambiguous when ≥2 candidates are readable).
+    // 设计评审：受理面 = 项目内现存 `.md`——相对形按会话项目根解析（越根 ⇒ 拒）· 绝对形照用 · 解析不出 ⇒ 拒并说清期望形；零试探、零歧义归一。
     if (reviewType === "design" && documents) {
-      const { resolved, invalid, ambiguous, candidates } = resolveReviewDocPaths(documents, agent.cwd)
-      if (invalid.length > 0 || ambiguous) {
+      const { invalid } = resolveReviewDocPaths(documents, agent.cwd)
+      if (invalid.length > 0) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
-        if (ambiguous) {
-          // 歧义拒（KD-4 独立判据——不混入 not-doc；列全部可读命中——fail-closed 不静默挑一）。
-          return withIdentityLine(
-            `Advisor: design review document "${ambiguous.doc}" matches several projects: ${ambiguous.hits.join(", ")}. Pass an absolute path to select one.`,
-            { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-doc-ambiguous" },
-          )
+        // 拒发文案：既有稳定前缀逐字（行首）+ 逐文档「输入 → 解析后绝对路径 ∥ 拒因」+ 锚态（仅无项目根）+ 期望形两句。
+        const lines = invalid.map((v) => `- ${v.doc} → ${v.resolved ?? "(no base)"} ∥ reason=${v.reason}`)
+        if (invalid.some((v) => v.reason === "no-project-root")) {
+          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.`)
         }
-        // not-doc 拒：既有稳定前缀逐字（行首）+ 解析诊断尾（B 面根治——逐文档「解析后绝对
-        // 路径 ← 基面 = 会话 cwd」+ 候选项目根提示 cap 5 + 重试指引——纠正「误报因」缺陷）。
-        const invalidList = invalid.map((v) => v.doc).join(", ")
-        const attemptedList = invalid
-          .map((v) => `${v.doc} → ${v.attempted.length > 0 ? v.attempted.join(" | ") : normAbs(v.doc, agent.cwd)}`)
-          .join("; ")
-        const shown = candidates.slice(0, 5)
-        const more = candidates.length - shown.length
-        const candidateNote = shown.length > 0
-          ? `(candidates: ${shown.join(", ")}${more > 0 ? ` +${more} more` : ""}) — pass project-root-relative (e.g. ${shown[0]}/docs/…) or absolute paths`
-          : "— pass project-root-relative or absolute paths"
+        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(
-          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid: ${invalidList}\nDiagnosis: resolved against session cwd ${agent.cwd} → ${attemptedList}; no candidate project docRoot contains it ${candidateNote}.`,
+          `Advisor: design review documents must be documentation files (per the project's conventions). Invalid:\n${lines.join("\n")}`,
           { type: reviewType, scope: scopeSummary(documents), round: "—", criterion: "scope-not-doc" },
         )
       }

package/agent-tools/audit-block.mjs

@@ -3,74 +3,26 @@
  *
  * 自 `subagent-spawn.mjs` **逐字搬移**（D23-3 外提：spawn 档越 300 软线 + 块构造成纯函数
  * ⇒ 判据可直测；D23-4：块内文本零改——含块内自指词，整块搬移不改真值）。本档承载
- * spawn 级固定机制性指令的第二块（审计模板 + A2 任务书摘要 + touched 快照）：
+ * spawn 级固定机制性指令的第二块（审计模板 + 批档 §2 指向 + touched 快照）：
  * 装配侧只收集（`thincoder-core/agent-tools/subagent-spawn.mjs`），下发面 = system 固块
  * （`child._spawnSystemBlock` → 核 `prepareRun` 拼接——`thincoder-core/agent/setup.mjs`）。
+ *
+ * 2026-10-24（§6.22 KD-SC6）：任务书 = 批次档 §2（子代理自读）；A2 拼装摘要面（按 marker 抽取
+ * 设计档 / 文件清单 / 验收三段）已随 KD-SC6 删除——审计块只注入批档路径行 + §2 指向句（路径取
+ * `ctx.agent._batchDoc`）。理由：工程角色 `_engTaskInput` 只剩一行机械文本，摘要失去来源。
  */
 
-/**
- * AGENT-LOOP-SUBAGENT.md §6.7.6 D-TS5 (A2): mechanically summarize the parent spawn task book for the
- * audit spawn — the three audit-relevant elements VERBATIM (design doc paths /
- * affected-file list / acceptance criteria); verbose context/background is
- * dropped (the auditor can read the design docs themselves — they stay
- * available outside this input). Independence preserved: the input is
- * _engTaskInput (mechanically kept by the parent spawn) — never the
- * eng-coder's self-report. Sections are located by header marker, prioritizing
- * header lines (structured task books: "## 文件清单 …") and falling back to
- * inline markers (flat one-line task books); a section runs to the next header
- * of the SAME OR HIGHER level ("## 文件清单" survives a "### 修改" sub-header).
- * Marker not found → the section is reported as missing (never fabricate).
- */
-export function summarizeEngTaskBook(taskInput) {
-  if (!taskInput) return "(unavailable)"
-  // 五项拼装形下，`designPoints` 一段同时承载「设计档落点」与「受影响文件清单」——
-  // 前两段同取该块是有意的（语义都在其中）；代价 = 摘要里该块出现两次，不是抽取失败。
-  const SECTIONS = [
-    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/, /^Design points/i] },
-    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/, /^Design points/i] },
-    { name: "Acceptance criteria", markers: [/Acceptance(?: criteria)?/i, /验收标准/] },
-  ]
-  const lines = taskInput.split("\n")
-  const headerLevel = (l) => {
-    const m = l.match(/^\s*(#{1,6})\s/)
-    return m ? m[1].length : 0
-  }
-  const headerIdx = lines.map((l, i) => (headerLevel(l) > 0 ? i : -1)).filter((i) => i >= 0)
-  const boundsFor = (from, level) => {
-    for (const j of headerIdx) {
-      if (j > from && (level === 0 || headerLevel(lines[j]) <= level)) return j
-    }
-    return lines.length
-  }
-  const out = []
-  for (const { name, markers } of SECTIONS) {
-    let from = -1
-    let level = 0
-    for (const i of headerIdx) {
-      if (markers.some((m) => m.test(lines[i]))) { from = i; level = headerLevel(lines[i]); break }
-    }
-    if (from === -1) {
-      for (let i = 0; i < lines.length; i++) {
-        if (markers.some((m) => m.test(lines[i]))) { from = i; level = 0; break }
-      }
-    }
-    if (from === -1) { out.push(`${name}: (not found in the parent task book)`); continue }
-    const body = lines.slice(from, boundsFor(from, level)).join("\n").trim()
-    out.push(body || `${name}: (empty section)`)
-  }
-  return out.join("\n\n")
-}
-
 /**
  * 审计块（spawn 级固定 ⇒ system 固块——§6.26 分类裁定表「审计块」行）：纯函数——touched 快照
- * （`ctx.agent._touchedFiles`——机制面证据，非 eng-coder 自述）+ A2 任务书摘要
- * （`summarizeEngTaskBook(ctx.agent._engTaskInput)`）+ 指令 / 范围 / 零 git 权威 / 预算 /
- * 报告格式五段模板**逐字**。零副作用（只读 ctx）；块内文本与搬移前逐字节一致。
- * @param {{ agent?: { _touchedFiles?: string[], _engTaskInput?: string } }} ctx
+ * （`ctx.agent._touchedFiles`——机制面证据，非 eng-coder 自述）+ 批档路径行与 §2 指向句
+ * （`ctx.agent._batchDoc`——任务书由审计子代理自读 §2）+ 指令 / 范围 / 零 git 权威 / 预算 /
+ * 报告格式五段模板**逐字**。零副作用（只读 ctx）。
+ * @param {{ agent?: { _touchedFiles?: string[], _batchDoc?: string } }} ctx
  * @returns {string} 块文本（不含与其它块之间的分隔符——分隔由装配侧 `join("\n\n")` 施加）
  */
 export function buildAuditBlock(ctx) {
   const touched = (ctx.agent._touchedFiles ?? []).map((f) => `- ${f}`).join("\n") || "- (none yet)"
+  const batchDoc = typeof ctx.agent?._batchDoc === "string" ? ctx.agent._batchDoc : "(unavailable)"
   return `[Audit scope — mechanical context, independent of the eng-coder's self-report:]\n` +
     // §6.7.6 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
     // 不再靠模型自悟；范围限制是 §6.7.4 D-AG3 声明（下方 Zero-git scope authority）
@@ -85,9 +37,11 @@ export function buildAuditBlock(ctx) {
     `workspace changes not listed there are unrelated to this delivery and are NOT grounds for an out-of-list finding.\n` +
     `Scope discipline (F-TS6 A1): read ONLY the audited files and the design-doc sections relevant to this delivery — do NOT re-read whole documents.\n` +
     `Every deviation item MUST be fieldized: file:line + design reference (doc path + section/AC id) + severity + evidence (quoted code or doc text).\n` +
-    // §6.7.6 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
-    `[Parent spawn task book — mechanical summary: design docs + affected-file list + acceptance criteria verbatim; verbose context/background dropped — the design docs are still available for reading outside this input:]\n` +
-    `${summarizeEngTaskBook(ctx.agent._engTaskInput)}\n` +
+    // §6.22 KD-SC6：任务书 = 批次档 §2（审计子代理自读）——审计块注入批档路径 + §2 指向句
+    // （A2 拼装摘要面已删：工程角色 _engTaskInput = 一行机械文本，摘要无来源）。审计子代理本身是
+    // explore（任务书 = 父侧五项）——故指向句限定为「**交付**的任务书 = §2」，不冒称本 child 的唯一通道。
+    `Batch record (batchDoc): ${batchDoc}\n` +
+    `Delivery task book: §2 of the batch record at ${batchDoc} — read it before judging the delivery; it is the criterion source for this audit.\n` +
     `Files actually touched by the eng-coder (mechanical union — audit these against the file list):\n${touched}\n` +
     // §18.5 D-AG3（2026-09-04）：审计零 git 范围权威声明——本审计任务零 git（不注入
     // git 上下文——§6.7.4 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
@@ -95,7 +49,7 @@ export function buildAuditBlock(ctx) {
     "Zero-git scope authority: this audit task receives NO git context — nothing is injected. " +
     "The evidence base is the design documents, the current disk state (read/glob/grep), and the _touchedFiles list above. " +
     "Workspace changes NOT listed in _touchedFiles are unrelated to this delivery — they are NOT grounds for an out-of-file-list finding." +
-    // §6.7.6 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
+    // §6.7.6 D-A1.2：审计预算句——A1 指令模板 + 批档指向块之后、A3 报告模板之前（定序——评审 #7）。
     // 逐字设计锚（D-A1.2 代码块）：只读该读的——10 轮机械预算——超时报 PROBLEM 下结论。
     // 前导 \n 与 A3 同款块分隔约定（上一句 Zero-git 句末无换行——不触碰既有句）。
     `\n[Audit budget — mechanical]: read ONLY the touched files listed above and the design-doc sections the parent task book names (affected-files table, acceptance criteria, status line). Do NOT read whole documents. Budget = 10 tool rounds max — if you cannot conclude within it, report PROBLEM (inconclusive) rather than continuing to explore.\n` +

package/agent-tools/batch-gate.mjs

@@ -14,10 +14,10 @@
  *      `REFUSED`（K ≥ 1）∥ `ERROR` ⇒ 调用面 throw（fail-closed）；命中 ⊆ 他批在途集 ⇒ 不阻收口 + 固定行逐档列出。
  *
  * 判据零变：本档不新增判据——只决定「判谁」与「何时强制」；判据与裁定串由产品引擎
- * `doc-check/index.mjs` 产出（判据源唯一）。引擎版本前置同源 = `doc-check/version.mjs`。
+ * `doc-check/index.mjs` 产出（判据源唯一）。
  *
- * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象；声明域已排除 `batches`，
- * 传入只产「跳过域外」行 = 假检查）；② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
+ * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象——判它只会把载体的超段记成本批欠账）；
+ * ② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
  * ② 的写入集只认触达账 + 回执明示「基 sha 未定」，提交面由父侧协议清单兜（不静默）。
  */
 import { execFileSync } from "node:child_process"
@@ -25,7 +25,6 @@ import { relative, resolve } from "node:path"
 
 import { owningProject, readManifest } from "../manifest.mjs"
 import { runDocCheck } from "../doc-check/index.mjs"
-import { firstVerdictLine, gateEngineError, staleEngineFiles } from "../doc-check/version.mjs"
 import { batchProjectRoot } from "./batch-paths.mjs"
 
 /** 平台路径键（win32 大小写不敏感——只作集比对，非判据面）。 */
@@ -61,7 +60,7 @@ function gitSurface(root) {
  *   （报面单源不重写）；行数与命中数不等（引擎报面行序变动）⇒ `aligned: false` + 自造行，由调用面回执明示。 */
 function hitEntries(res, root) {
   const lines = res.report.split("\n").filter((l) => l.startsWith("✗ "))
-  const hits = [...res.anchorHits, ...res.widthHits]
+  const hits = [...res.anchorHits, ...res.paragraphHits]
   const aligned = lines.length === hits.length
   const entries = hits.map((h, i) => ({
     file: h.file,
@@ -93,20 +92,20 @@ const emptyRange = (basis) => ({ count: 0, k: 0, foreign: 0, basis })
 const errorState = (first, range = emptyRange("none")) => ({ state: "error", first, report: first, hitLines: [], noteLines: [], range })
 
 /**
- * 跑一次门（**非抛错**：三因之外的门自身异常收为 `error` 态，由调用面按 `scope` 消费）。
- * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close', clock?:object}} o
- *   `abs` = 目标批次档绝对路径（根解析用）；`agent._touchedFiles` = 触达记账；`clock` = 版本判定的测试注入缝。
+ * 跑一次门（**非抛错**：两因之外的门自身异常收为 `error` 态，由调用面按 `scope` 消费）。
+ * @param {{abs:string, cwd?:string, agent?:object, scope?:'writer'|'close'}} o
+ *   `abs` = 目标批次档绝对路径（根解析用）；`agent._touchedFiles` = 触达记账。
  * @returns {{state:'pass'|'refused'|'error'|'not-applicable', first:string|null, report:string,
  *   hitLines:string[], noteLines:string[], range:{count:number, k:number, foreign:number, basis:string}}}
  *   `first` = 唯一机判串（首行 `DOC-CHECK GATE:`）；`not-applicable` ⇒ `first = null` + 固定回执行。
  */
-export function runBatchGate({ abs, cwd, agent = {}, scope = "writer", clock } = {}) {
+export function runBatchGate({ abs, cwd, agent = {}, scope = "writer" } = {}) {
   // `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, clock })
+    return evaluate({ abs, cwd, agent, scope })
   } catch (e) {
     const first = `DOC-CHECK GATE: ERROR（门自身异常：${e?.message ?? String(e)}）`
     return errorState(first)
@@ -114,7 +113,7 @@ export function runBatchGate({ abs, cwd, agent = {}, scope = "writer", clock } =
 }
 
 /** 门体（正常路径——异常由上抛给 `runBatchGate` 收口）。 */
-function evaluate({ abs, cwd, agent, scope, clock }) {
+function evaluate({ abs, cwd, agent, scope }) {
   const base = resolve(cwd ?? process.cwd())
   const root = owningProject(resolve(abs)) ?? batchProjectRoot(base)
   const close = scope === "close"
@@ -123,19 +122,12 @@ function evaluate({ abs, cwd, agent, scope, clock }) {
   try { read = readManifest(root) } catch (e) {
     return errorState(`DOC-CHECK GATE: ERROR（manifest 不可读 —— ${e?.message ?? String(e)}）`)
   }
-  // 适用面（声明面驱动）：无 manifest ⇒ 不适用 + 回执明示；**不是豁免清单**——判据参数来自 checkConfig。
+  // 适用面（声明面驱动）：无 manifest ⇒ 不适用 + 回执明示；**不是豁免清单**——判据参数 = 引擎内置常量。
   if (!read.ok && read.reason === "missing") {
     return { state: "not-applicable", first: null, report: "[doc-check gate] 未跑（本项目无声明面）", hitLines: [], noteLines: [], range: emptyRange("none") }
   }
-  // 引擎版本前置（fail-closed）：stale ⇒ 直接 ERROR 串，不进引擎（不产 PASS）。
-  const version = staleEngineFiles(clock ?? {})
-  if (version.stale.length) {
-    const report = gateEngineError(version)
-    return { state: "error", first: firstVerdictLine(report), report, hitLines: [], noteLines: [], range: emptyRange("none") }
-  }
-
   // 范围（判谁）：writer = 写者触达账；close = 本批笔域集（触达账）∪ git 面。
-  // 批档自身不入范围（载体不是判据对象；声明域已排除 batches ⇒ 传入只产「跳过域外」行 = 假检查）。
+  // 批档自身不入范围（载体不是判据对象——判它只会把载体的超段记成本批欠账）。
   const selfKey = pathKey(resolve(abs))
   const touched = docPaths(agent?._touchedFiles, base).filter((p) => pathKey(p) !== selfKey)
   const git = close ? gitSurface(root) : { ok: false, base: root, files: [] }
@@ -143,7 +135,6 @@ function evaluate({ abs, cwd, agent, scope, clock }) {
   const docs = close ? [...new Set([...touched, ...gitDocs])] : touched
   const basis = close ? (git.ok ? "touched+git" : "touched（git 面不可得）") : "touched"
   const res = runDocCheck(root, { mode: "gate", docs, docsSource: close ? "explicit" : "session" })
-  if (res.error) return { state: "error", first: firstVerdictLine(res.report), report: res.report, hitLines: [], noteLines: [], range: { count: res.checkFiles.length, k: 0, foreign: 0, basis } }
 
   const { aligned, entries } = hitEntries(res, root)
   const ownKeys = new Set(touched.map(pathKey))

package/agent-tools/checkpoint.mjs

@@ -21,13 +21,16 @@ import { getAsyncPool } from "./async-settle.mjs"
  * 段数 / 累计轮次二元文本（§4 留痕口径——两值同读一次）：
  * `_continueSegments`（链内段数，首段 1）· `_turnSeq`（链内累计轮次，跨段不重置）。
  * 两值均挂子 agent 本体。
- * #417 追加第三元「本段零落盘轮数」（`_zeroWriteTurns`——核回合环采集，与 `_turnSeq` 同源面）：
- * **只报数**（零阈值 / 零自动动作——父侧据此判断「在推进」还是「在原地读」）。缺该字段的
- * 执行面（端侧自有回合环、未跟踪）不渲染该元——缺省不冒充 `0`（「未跟踪」不得读作「零消耗」）。
+ * #417 追加第三元「本段零落盘轮数」，#934 收正后带分母（`_zeroWriteTurns` of `_segmentTurns`）：
+ * **只报数**（零阈值 / 零自动动作——父侧据此判断「在推进」还是「在原地读」）。分子分母任一缺字段
+ * 或非整数的执行面（端侧自有回合环、未跟踪）不渲染该元——缺省不冒充 `0`（「未跟踪」不得读作「零消耗」）。
  */
 function traceText(child) {
   const base = `segments ${child?._continueSegments ?? 1} · accumulated ${child?._turnSeq ?? 0} turns`
-  return Number.isInteger(child?._zeroWriteTurns) ? `${base} · zero-write rounds this segment: ${child._zeroWriteTurns}` : base
+  const zw = child?._zeroWriteTurns, seg = child?._segmentTurns
+  return Number.isInteger(zw) && Number.isInteger(seg)
+    ? `${base} · ${zw} of this segment's ${seg} rounds produced no file write`
+    : base
 }
 
 /** 留痕片段（§3.1 池条目留痕行）：挂池条目摘要**文本**面（status / observe）——桥字段零新增。 */
@@ -45,7 +48,7 @@ function replyHint(parent, carrier, key) {
 
 /**
  * 登记检查点并挂起（异步族 askContinue 的唯一实现——逃逸 ①②③）：
- * 登记 `carrier._turnCapRec` + 父侧 ask（载荷 = 段数 / 累计轮次 + 去向一句话）——
+ * 登记 `carrier._turnCapRec` + 父侧 ask（载荷 = 段数 / 累计轮次 / 本段零落笔读数 + 职责句 + 去向一句话）——
  * ask 入队即唤醒父侧挂起驱动（`pushChildUpstream`）。
  * @param {object} child   撞帽的子 agent（`_upstream` 携父与来源标签）。
  * @param {object} carrier 兑现载体：池条目（子代 / 飞刀）或会诊 session。
@@ -83,7 +86,9 @@ export function registerTurnCapCheckpoint(child, carrier, { turn = 0, signal } =
     from: child._upstream.label,
     kind: "ask",
     message: `[turn cap] ${traceText(child)} — this child hit its per-segment turn cap and is suspended `
-      + `(history kept, no re-dispatch). ${replyHint(parent, carrier, key)}`,
+      + `(history kept, no re-dispatch). `
+      + `Check for a non-writing loop before you grant or stop: inspect (subagent action:'observe'), then steer or cancel. `
+      + replyHint(parent, carrier, key),
   })
   return promise
 }

package/agent-tools/context.mjs

@@ -92,7 +92,7 @@ function statsReport(agent) {
   return [
     `Context ≈${usage.total} tokens (${pct}% of ${usage.window} window); compaction line ${usage.threshold} (${toGo} to the line)`,
     // §6.16.4 字面单源（该行为唯一字面，逐字；预算面同源 requestBudget——不自算第二套）:
-    // window {window} ({spec|provider-override}) · max_tokens {maxTokens|not sent} ({explicit|spec|absent})
+    // window {window} ({modelContext|provider-override|list|spec|default}) · max_tokens {maxTokens|not sent} ({explicit|spec|absent})
     // · prompt {total} · to compaction line {threshold − total} · to window limit {limit − total}
     // 两距离带符号（负 = 已越）；maxTokens 未发写 not sent、来源写 absent（该档守卫不覆盖——§6.17 射程）。
     (() => {

package/agent-tools/design-token.mjs

@@ -97,8 +97,15 @@ const TRUNCATED_ECHO_MARK = "注：回显被截断（uuid 之后缺失或不符
 
 /** §5.2 verdict gate (#940): the echo alone is NOT the verdict — the receipt must
  *  carry a `VERDICT: pass` line and no `VERDICT: changes-required` line (fail-closed). */
-const VERDICT_PASS_LINE    = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*pass[ \t]*[*_`]*[ \t]*$/m
-const VERDICT_CHANGES_LINE = /^[ \t]*[*_`]*[ \t]*VERDICT:[ \t]*changes-required[ \t]*[*_`]*[ \t]*$/m
+// 裁定行接受本地化等价形（GitHub #32 / #14）：评审席用中文回执很常见，
+// 只认英文会让 pass 落成 no-pass-line、凭证永不签发；判据仍只认整行逐字面，
+// 不做「句中含『通过』」这类模糊匹配——那样会把「未通过」也放过。
+const _V_PRE = "^[ \\t]*[*_`]*[ \\t]*"
+const _V_SUF = "[ \\t]*[*_`]*[ \\t]*$"
+const VERDICT_PASS_LINE = new RegExp(
+  _V_PRE + "(?:VERDICT:[ \\t]*(?:pass|通过|通过。)|结论[:：][ \\t]*(?:通过|pass))" + _V_SUF, "mi")
+const VERDICT_CHANGES_LINE = new RegExp(
+  _V_PRE + "(?:VERDICT:[ \\t]*(?:changes-required|不通过|需修改)|结论[:：][ \\t]*(?:不通过|需修改|changes-required))" + _V_SUF, "mi")
 export function verdictGateFailure(rawResult) {
   if (typeof rawResult !== "string") return "no-pass-line"
   if (VERDICT_CHANGES_LINE.test(rawResult)) return "changes-required"

package/agent-tools/digest-budget.mjs

@@ -58,6 +58,8 @@ export function digestBudgetOver(agent, size) {
 /** Test seam: 落盘目录重定向（单元测试沙箱——生产从不调用）。 */
 let _digestOffloadDirOverride = null
 export function _setDigestOffloadDirForTest(dir) { _digestOffloadDirOverride = dir }
+/** 缝的读取面（无参）：生产恒 undefined ⇒ 消费方取各自默认目录。一条缝覆盖本档与 `offloadToolResult` 两族（TIMEOUT-DIGEST.md §2.2）。 */
+export function _digestOffloadDirForTest() { return _digestOffloadDirOverride ?? undefined }
 
 /** 超限条目全量落盘（返回清单行文本；失败 null——调用方回退 inline——结果零丢失）。
  *  tag 入文件名（溯源：写入族 + 条目 id）。 */

package/agent-tools/doc-check.mjs

@@ -1,28 +1,23 @@
 /**
  * agent-tools/doc-check.mjs — `doc_check` 工具：文档纪律机检（产品内建 · 两种问法）。
  *
- * 设计 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S（判据 = 锚 ∥ 行宽 · 声明面驱动）。
- * 工具形：**无动作枚举**——`mode` = 同一条判据的两种问法（`report` = 全域报告态 ∥ `gate` = 交付时点
- * 的范围化裁定）；**只读**（零副作用 · 免审批 · 可并行）；参数 `target` / `mode` / `docs`
+ * 设计 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S（判据 = 锚 ∥ 段判据 · 参数内置常量）。
+ * 工具形：**无动作枚举**——`mode` = 同一条判据的两种问法（`report` = 报告态 ∥ `gate` = 交付时点的裁定）；
+ * **只读**（零副作用 · 免审批 · 可并行）；参数 `target` / `mode` / `docs`
  * （`target` 指向多项目工作区 ⇒ 报明候选并要求指名，同 `manifest` 工具面）。
- * 判据参数读目标项目的 `PROJECT-MANIFEST.json` `checkConfig`——不硬编码任何本仓路径（换项目开箱可用）。
+ * 判据参数 = 引擎内置常量 `DOC_CHECK_BUILTINS`——不读 manifest、不硬编码本仓路径、不扫目录。
+ * 判定范围 = 调用方传入的档：`report` 面 `docs` 必填（不给 ⇒ 明确报错，零遍历）；
+ * `gate` 面缺省 = 本会话触达记账里的 `.md`（交付面按轮次收窄的唯一来源）。
  * `report` 非门禁（硬）：输出不得被读作拒执行的理由（用户令 > 机检——§2 总则族）；
  * `gate` 的强制面住交付协议 + 批次档 §6 前置，工具本体同样不阻断任何动作。
- * gate 前置（fail-closed）= 引擎版本一致：本会话进程持启动时加载的 ESM 引擎，引擎档晚于启动 ⇒ ERROR
- * （判据单源 = `doc-check/version.mjs`——与 `batch-gate.mjs` 共用一份清单，不各持一份）。
  * 描述外置：模型可见文本单点 = `tool-docs/doc_check.md`（`DESC` 单一解析面）。
  * 装配段 = `agent/family-tools.mjs` 三处（depth-0 / eng-coder / eng-designer）——写文档 / 设计档的角色面。
  */
 import { resolve } from "node:path"
 import { projectRootView } from "../manifest.mjs"
 import { runDocCheck } from "../doc-check/index.mjs"
-import { staleEngineFiles, gateEngineError, withEngineNote } from "../doc-check/version.mjs"
 import { DESC } from "../tools/shared.mjs"
 
-// 版本函数单源 = `doc-check/version.mjs`（两消费面：本档 gate 分支 ∥ `batch-gate.mjs` 两机械点）——
-// 本档只转口，导出面不变（原五档清单已随之六档：`version.mjs` 自身入清单）。
-export { staleEngineFiles, gateEngineError }
-
 export const docCheckTool = {
   name: "doc_check",
   description: DESC("doc_check"),
@@ -30,8 +25,8 @@ export const docCheckTool = {
     type: "object",
     properties: {
       target: { type: "string", description: "Explicit project root to check — defaults to the session anchor; relative paths resolve against it. A workspace target (several projects below it) is reported with the full candidate list — pass the project root you mean." },
-      mode: { type: "string", enum: ["report", "gate"], description: "How to ask the same two-criteria check. \"report\" (default): the whole declared domain, non-gating report. \"gate\": the delivery gate — only the documents this round touched, whole-file judged, first line a machine-readable verdict (DOC-CHECK GATE: PASS / REFUSED / ERROR)." },
-      docs: { type: "array", items: { type: "string" }, description: "Gate only: the documents this round touched (paths relative to the project root, or absolute). Omitted in gate mode ⇒ the documents this session wrote. Passing docs with mode \"report\" is refused, not silently ignored." },
+      mode: { type: "string", enum: ["report", "gate"], description: "How to ask the same two-criteria check. \"report\" (default): a non-gating report over the documents you list in docs. \"gate\": the delivery gate — the documents this round touched (docs, or this session's written documents when docs is omitted), whole-file judged, first line a machine-readable verdict (DOC-CHECK GATE: PASS / REFUSED / ERROR)." },
+      docs: { type: "array", items: { type: "string" }, description: "The documents to judge, as paths relative to the project root or absolute — each is judged whole; nothing else is read except the targets those documents point at. Required in \"report\" mode (there is no default range: omitting it is refused, not widened). Omitted in \"gate\" mode ⇒ the Markdown documents this session wrote. A path that is not on disk or is not a Markdown document is an error (no document judged) in report mode and a visible skipped line in gate mode." },
     },
   },
   readonly: true,
@@ -39,13 +34,13 @@ export const docCheckTool = {
     const anchor = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
     const target = args?.target ? resolve(anchor, String(args.target)) : resolve(anchor)
     const mode = args?.mode === undefined ? "report" : String(args.mode)
-    if (mode !== "report" && mode !== "gate") return `doc_check: unknown mode "${mode}" — use "report" (default: the whole declared domain) or "gate" (this round's documents).`
-    const explicit = Array.isArray(args?.docs) ? args.docs.map(String) : null
+    if (mode !== "report" && mode !== "gate") return `doc_check: unknown mode "${mode}" — use "report" (a report over the documents you list) or "gate" (this round's documents).`
+    const explicit = Array.isArray(args?.docs) ? args.docs : null
     if (args?.docs !== undefined && !Array.isArray(args.docs)) {
       return `doc_check: \`docs\` must be an array of paths (got ${typeof args.docs}) — a bare string is refused rather than read as a whole-domain request; pass ["<path>"].`
     }
-    if (mode === "report" && explicit) {
-      return "doc_check: `docs` is only valid with mode:\"gate\" — report mode always checks the whole declared domain; pass mode:\"gate\" to scope the check to the documents this round touched."
+    if (explicit && explicit.some((d) => typeof d !== "string")) {
+      return "doc_check: every `docs` entry must be a path string — a non-string entry is refused rather than coerced (no document was judged)."
     }
     const view = projectRootView(target)
     if (view.state === "workspace") {
@@ -61,15 +56,14 @@ export const docCheckTool = {
     }
     const root = view.state === "ok" ? view.root : target
     if (mode === "gate") {
-      // 引擎版本校验先于引擎（A-DD30 ①）：stale 非空 ⇒ 直接 ERROR 串，不进引擎
-      const version = staleEngineFiles()
-      if (version.stale.length) return gateEngineError(version)
-      // 会话候选先取 `.md`（触达记账含代码档——代码档不是文档，不该进范围行）；域求交归引擎单源
       const docs = explicit ?? (Array.isArray(ctx?.agent?._touchedFiles) ? ctx.agent._touchedFiles : [])
         .filter((p) => typeof p === "string" && p.toLowerCase().endsWith(".md"))
       return runDocCheck(root, { mode: "gate", docs, docsSource: explicit ? "explicit" : "session" }).report
     }
-    // 报告态读数标注（A-DD30 ①）：引擎陈旧 ⇒ 首行前一行注记；无陈旧 ⇒ 报面逐字同改前
-    return withEngineNote(runDocCheck(root).report, staleEngineFiles())
+    // 报告态：清单是唯一范围来源——不给就是拒绝（不是「全域」）。
+    if (explicit === null) {
+      return "doc_check: `docs` is required in report mode — pass the explicit list of documents to judge (e.g. docs: [\"docs/design/X.md\"]). There is no default range: nothing is scanned unless you name it."
+    }
+    return runDocCheck(root, { docs: explicit, docsSource: "explicit" }).report
   },
 }

package/agent-tools/manifest.mjs

@@ -11,10 +11,9 @@
  *  - `write` ⇒ **点改**：读现档 → 设节点 → 落盘（`writeManifest` 内先 `validateManifest`——
  *              编辑结果非法 ⇒ 拒 + 盘零变）；**缺档 ⇒ 拒** + 引导 `init`（写不建档）。
  *
- * 写面白名单（判据单源 = `MANIFEST_SCHEMA`——钉死谓词）：`keys` 中**非** `nestedKeys` 父键者
- * （`version` / `phase` / `promptsLanding` / `codePaths` 整键）+ `nestedKeys` 子键
- * （`docRoot.*` / `checkConfig.*` / `index.*`（含 `publicRepos`）/ `advisor.*`）；**四族整键写
- * （传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
+ * 写面白名单（判据单源 = `MANIFEST_SCHEMA`——钉死谓词）：**12 个可写节点** = `keys` 中**非** `nestedKeys`
+ * 父键者（`version` / `phase` / `codePaths` 整键）+ `nestedKeys` 子键（`docRoot.*` 五子键 / `index.*` 四子键）；
+ * **两族整键写（传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
  * `value` 解析 = 同款口径 `settings.mjs` 的 `parseValue`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
  * ——`docRoot.*` 的「本面无」，KD-M1-37）。
  *
@@ -31,6 +30,11 @@
  * 缓存失效（#1367 面⑦）：写档成功（init ∥ write——全部成功路径）⇒ `clearDeclarationCache()`——
  * 「补档即回归」进程内即时（声明 ∥ 范围缓存同清）；失败路径不清（盘零变 ⇒ 缓存照旧）；
  * 手工改档 ⇒ 重启生效（零文件侦听）。
+ *
+ * 只读变体（`manifestReadTool`——2026-10-22 · 台账 #1738）：子代理面同名 `manifest`，`action` 枚举只剩
+ * `read`（schema 级不可达 = 权限面第一道）+ execute 入口机械拒绝（第二道，providers 不强制 schema enum）；
+ * `readAction` 的 `canInit=false` 让缺档 / 无项目两态的引导行不指 `init`。全量工具 `manifestTool` 零改
+ * （`readonly: false` = 动作级分类面，只读性归 `dispatch-gates` 的 `read` 判定）。
  */
 import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
@@ -51,8 +55,8 @@ function resolveTarget(args, ctx) {
 }
 
 /** 写面白名单谓词（**钉死**——设计 §2.10）：点分路径恰两形——
- *  ① 单段：`keys` ∩ ∉ `nestedKeys`（= `version` / `phase` / `promptsLanding` / `codePaths` 整键）；
- *  ② 双段：`nestedKeys[父]` 含子键（四族子键）；其余（四族整键写 / 未知键 / 更深路径）⇒ 拒。
+ *  ① 单段：`keys` ∩ ∉ `nestedKeys`（= `version` / `phase` / `codePaths` 整键）；
+ *  ② 双段：`nestedKeys[父]` 含子键（两族子键）；其余（两族整键写 / 未知键 / 更深路径）⇒ 拒。
  *  `Array.isArray` 守卫：原型链名（`__proto__` / `constructor` / `toString` 类）取到非数组 ⇒ 落拒面
  *  （不得 TypeError 直出——白名单外一律 `refused` 统一前缀）。 */
 function isWritableKey(key) {
@@ -90,21 +94,26 @@ function workspaceReason(target, candidates) {
 }
 
 /** read 动作（五态报明——**不抛**）：`state=` 稳定锚 + 各态附行（ok 细节面 / missing 引导 /
- *  workspace 下辖项目全列 / invalid 错误行）。 */
-function readAction(target) {
+ *  workspace 下辖项目全列 / invalid 错误行）。
+ *  `canInit`（缺省 `true` ⇒ depth-0 输出逐字零变）：`false` 时 `missing` / `no-project` 的引导行不指
+ *  `init`——子代理面无该动作，指向不可达动作会把模型送进必然失败的调用。 */
+function readAction(target, { canInit = true } = {}) {
   const view = projectView(target)
   const lines = [`state=${view.state}`]
   if (view.path) lines.push(`path=${view.path}`)
   if (view.state === "ok") {
-    const m = readManifest(view.root) // 细节面：missingKeys / unknownKeys / errors（非空才出）
+    const m = readManifest(view.root) // 细节面：missingKeys / errors（非空才出）
     lines.push(`manifest=${JSON.stringify(m.manifest)}`)
     if (m.missingKeys?.length) lines.push(`missingKeys=${m.missingKeys.join(", ")}`)
-    if (m.unknownKeys?.length) lines.push(`unknownKeys=${m.unknownKeys.join(", ")}`)
     if (m.errors?.length) lines.push(`errors=${m.errors.join("；")}`)
   } else if (view.state === "missing") {
-    lines.push(`hint: run manifest action=init to create the default manifest here`)
+    lines.push(canInit
+      ? "hint: run manifest action=init to create the default manifest here"
+      : "hint: no manifest here — report it; creating one is a main-agent action")
   } else if (view.state === "no-project") {
-    lines.push(`hint: no project on the ancestor chain and none below — manifest action=init can create one at the target`)
+    lines.push(canInit
+      ? "hint: no project at this directory and none in the direct children — manifest action=init can create one at the target"
+      : "hint: no project at this directory and none in the direct children — report it; creating one is a main-agent action")
   } else if (view.state === "workspace") {
     lines.push(`projects (${(view.candidates ?? []).length}):`)
     for (const c of view.candidates ?? []) lines.push(`- ${c}`)
@@ -123,7 +132,7 @@ export const manifestTool = {
     properties: {
       action: { type: "string", enum: ["read", "init", "write"], description: "read — current manifest + validation state (five-state anchor, never throws); init — create the default manifest when missing (refused when one already exists); write — point-edit one node (key + value) of an existing manifest" },
       target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. A workspace target (several projects below it) is refused with the full project list — pass the project root you mean." },
-      key: { type: "string", description: "(write) Dot path of the node to set — version / phase / promptsLanding / codePaths, or a sub-key of docRoot / checkConfig / index / advisor (e.g. docRoot.design / index.publicRepos / advisor.docMap); whole-object writes of those four families are refused", },
+      key: { type: "string", description: "(write) Dot path of the node to set — version / phase / codePaths, or a sub-key of docRoot / index (e.g. docRoot.design / index.publicRepos); whole-object writes of those two families are refused", },
       value: { type: "string", description: "(write) New value — parsed as JSON first (null / true / 5 / [\"a\"]), otherwise kept as a literal string; \"null\" is the explicit no-such-face for docRoot.<key>" },
     },
     required: ["action"],
@@ -169,7 +178,7 @@ export const manifestTool = {
     if (!key) throw new Error("manifest write: key is required (dot path, e.g. docRoot.design)")
     if (args?.value === undefined) throw new Error("manifest write: value is required (JSON-parsed first, otherwise a literal string)")
     if (!isWritableKey(key)) {
-      throw refuse("write", `key "${key}" is not writable — writable nodes: version / phase / promptsLanding / codePaths + sub-keys of docRoot / checkConfig / index / advisor (whole-object writes of the four families are refused)`)
+      throw refuse("write", `key "${key}" is not writable — writable nodes: version / phase / codePaths + sub-keys of docRoot / index (whole-object writes of the two families are refused)`)
     }
     let current
     try {
@@ -198,3 +207,25 @@ export const manifestTool = {
     return `manifest write: set ${key} = ${JSON.stringify(value)}\npath=${file}`
   },
 }
+
+/** 子代理只读变体（同名 `manifest`——action 枚举只剩 `read`）：init / write schema 级不可达（权限面第一道）；
+ *  execute 入口再做一次机械拒绝（providers 不强制 schema enum——第二道）。 */
+export const manifestReadTool = {
+  name: "manifest",
+  description: DESC("manifest-read"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["read"], description: "read — current manifest + validation state (five-state anchor, never throws)" },
+      target: { type: "string", description: "Explicit target directory — defaults to the session anchor; relative paths resolve against it. A workspace target (several projects below it) is reported with the full project list — pass the project root you mean." },
+    },
+    required: ["action"],
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    if (args?.action !== "read") {
+      throw new Error(`manifest read: refused — this read-only variant exposes only action=read (got ${JSON.stringify(args?.action)})`)
+    }
+    return readAction(resolveTarget(args, ctx), { canInit: false })
+  },
+}