@thincoder/core 0.10.9 → 0.10.10

package/advisor/messages.mjs

@@ -155,15 +155,14 @@ function buildAdvisorUserMessageInner(agent, prior, reviewType, designToken = nu
       }
     }
 
-    // Engineering mode: the project's DECLARED standards document
-    // (advisor.standardsDoc) — undeclared degrades visibly (PO-2).
+    // Engineering mode: the project standards section — the declaration face is gone with the
+    // manifest `advisor` key, so this is always an explicit degradation (PO-2).
     if (agent.config?.agent?.engineering) {
       injectProjectStandards(agent, parts, guideRoot)
     }
 
-    // Document map: declared path wins, the built-in fallback probe (docs/README.md
-    // → docs/design/README.md) stays; neither → explicit degradation sentence
-    // (never the old silent skip).
+    // Document map: derived from the manifest `docRoot` (declared roots' README, then their common
+    // ancestor); neither → explicit degradation sentence (never a silent skip).
     injectDocumentMap(agent, parts, guideRoot ?? agent.cwd)
 
     parts.push("## Instructions")

package/advisor/project-context.mjs

@@ -12,13 +12,14 @@
  * absent — in a project with a different layout the reviewer still scored the
  * dimension it could no longer check (silent failure, the worst class: invisible
  * and unfixable by the user). Missing pieces now say so, and the reviewer is told
- * to state the limitation in its findings. Projects can point at their own files
- * through the project manifest (advisor.docMap / advisor.standardsDoc).
+ * to state the limitation in its findings. The document map is derived from the
+ * manifest's `docRoot` (the one place that says where the docs live); the standards
+ * face has no derivable convention name and is therefore an explicit degradation.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { resolve, join, relative, dirname, sep } from "node:path"
 import { providerSpec } from "../config.mjs"
-import { loadProjectDeclaration } from "../conventions.mjs"
+import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
 
 /** Project guide (AGENTS.md) injection budget — decision 2026-08-08:
  *  NO fixed truncation; long-context models (1M+) get up to 5% of their context
@@ -32,8 +33,8 @@ const PROJECT_GUIDE_FRACTION = 0.05 // 5% of the reviewer model's context window
 export const NO_GUIDE_NOTICE = "(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)"
 
 /** Explicit degradation sentences (PORTABILITY design §4.4 — verbatim). */
-export const NO_DOC_MAP_NOTICE = "(No document map found under the project root, and none is declared — the Document ownership criterion is degraded: check placement against the Project Guide where present, and state the limitation in your findings.)"
-export const NO_STANDARDS_NOTICE = "(No project standards document was declared — judge methodology compliance from the Project Guide (when present) and the review criteria above; state the limitation in your findings.)"
+export const NO_DOC_MAP_NOTICE = "(No document map found — no README.md under the declared document roots and none at their common ancestor — the Document ownership criterion is degraded: check placement against the Project Guide where present, and state the limitation in your findings.)"
+export const NO_STANDARDS_NOTICE = "(No project standards document — nothing in the project declares one — judge methodology compliance from the Project Guide (when present) and the review criteria above; state the limitation in your findings.)"
 export const NO_GIT_NOTICE = "(No git repository detected — change-set context is unavailable; read the review-scope files directly.)"
 
 /**
@@ -126,25 +127,66 @@ export function injectProjectGuide(agent, parts, scopeFiles = []) {
   return root // guide injected — requirement-fit criteria apply (truthy root)
 }
 
+/** `docRoot` probe order: the face a reviewer needs first (design) → down to the batch records. */
+const DOC_ROOT_ORDER = ["design", "requirements", "specs", "modules", "batches"]
+
+/** Declared document roots as ABSOLUTE paths, in declaration order (`null` / missing face ⇒ no root). */
+function declaredDocRoots(base) {
+  const read = readManifest(base)
+  const docRoot = (read.ok && read.manifest ? read.manifest : DEFAULT_MANIFEST).docRoot ?? {}
+  const out = []
+  for (const key of DOC_ROOT_ORDER) {
+    for (const p of docRootPaths(docRoot[key], base)) if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/** Common ancestor of every root (segment-wise — `docs/design` and `docs/designX` are not siblings).
+ *  A lone drive root is no map home ⇒ null. */
+function commonAncestor(paths) {
+  if (paths.length === 0) return null
+  const split = (p) => p.split(/[\\/]+/)
+  let acc = split(paths[0])
+  for (const p of paths.slice(1)) {
+    const segs = split(p)
+    let i = 0
+    while (i < acc.length && i < segs.length && acc[i] === segs[i]) i++
+    acc = acc.slice(0, i)
+  }
+  if (acc.length === 0) return null
+  const joined = acc.join(sep)
+  return /^[A-Za-z]:$/.test(joined) ? null : joined
+}
+
 /**
- * Inject the project document map (PO-1). Resolution: the DECLARED path
- * (`advisor.docMap`, project-root-relative) wins; the built-in probe
- * (`docs/README.md` → `docs/design/README.md`) stays as a fallback for projects
- * laid out that way. Neither usable → an explicit degradation sentence — never a
- * silent skip: the reviewer must know the Document-ownership criterion is unchecked.
+ * Discover the document map from the manifest's `docRoot` — a pure fs probe, no index generation
+ * (the map is a hand-maintained register; a generated one would be a second index, and a second
+ * index is exactly the duplicate pointer the retired declaration face used to create).
+ * Ladder: ① `README.md` under each declared doc root (declaration order) ② `README.md` at the common
+ * ancestor of every declared root. Neither ⇒ null (caller injects `NO_DOC_MAP_NOTICE` — no silent skip).
+ * @param {string} base project root (or any dir inside it — `docRoot` resolves against the project root)
+ * @returns {string|null} absolute path of the map file, or null when degraded
+ */
+export function findDocumentMap(base) {
+  const roots = declaredDocRoots(base)
+  for (const r of roots) {
+    const p = join(r, "README.md")
+    if (existsSync(p)) return p
+  }
+  const ancestor = commonAncestor(roots)
+  if (!ancestor) return null
+  const p = join(ancestor, "README.md")
+  return existsSync(p) ? p : null
+}
+
+/**
+ * Inject the project document map (PO-1), derived from `docRoot`. Degrades visibly: the reviewer
+ * must know the Document-ownership criterion is unchecked — never a silent skip.
  * @returns {string|null} the injected map path, or null when degraded
  */
 export function injectDocumentMap(agent, parts, root) {
   const base = root ?? agent.cwd
-  const conv = loadProjectDeclaration(agent.cwd)
-  let mapPath = null
-  if (conv.advisor.docMap) {
-    const declared = resolve(base, conv.advisor.docMap)
-    if (existsSync(declared)) mapPath = declared
-  } else {
-    mapPath = [resolve(base, "docs", "README.md"), resolve(base, "docs", "design", "README.md")]
-      .find((p) => existsSync(p)) ?? null
-  }
+  const mapPath = findDocumentMap(base)
   parts.push("## Document Map")
   let text = null
   if (mapPath) {
@@ -166,32 +208,15 @@ export function injectDocumentMap(agent, parts, root) {
 }
 
 /**
- * Inject the project standards document (PO-2). DECLARATION ONLY
- * (`advisor.standardsDoc`, project-root-relative): the old hardcoded
- * `METHODOLOGY.md` probe injected a file most projects do not have — and its
- * absence was silent. Undeclared (or unreadable) → explicit degradation sentence.
- * @returns {string|null} the injected standards path, or null when degraded
+ * Inject the project standards section (PO-2). The declaration face is gone with the manifest
+ * `advisor` key, and no standards file name is derivable from what the project does declare (the old
+ * `METHODOLOGY.md` probe was deleted exactly because most projects have none). The section stays so the
+ * reviewer is TOLD the dimension is unchecked — visible degradation, not a silent skip.
+ * @returns {null} always degraded
  */
-export function injectProjectStandards(agent, parts, root) {
-  const base = root ?? agent.cwd
-  const conv = loadProjectDeclaration(agent.cwd)
-  const declared = conv.advisor.standardsDoc ? resolve(base, conv.advisor.standardsDoc) : null
+export function injectProjectStandards(_agent, parts, _root) {
   parts.push("## Project Standards")
-  let text = null
-  if (declared && existsSync(declared)) {
-    try {
-      text = readFileSync(declared, "utf8")
-    } catch (e) {
-      console.warn(`[advisor] project standards unreadable at ${declared}: ${e.message}`)
-    }
-  }
-  if (text === null) {
-    parts.push(NO_STANDARDS_NOTICE) // degraded — visible by contract
-    parts.push("")
-    return null
-  }
-  parts.push("The project declares these standards for this review. Judge the design/changes against them:")
-  parts.push(text)
+  parts.push(NO_STANDARDS_NOTICE) // degraded — visible by contract
   parts.push("")
-  return declared
+  return null
 }

package/agent/family-tools.mjs

@@ -26,7 +26,7 @@ export async function assembleFamilyTools({
   decorate = null,       // object   端差面：{ subagent?, consultStart?, consultStop?, settings? }
 } = {}) {
   // CORE-UNIFICATION TOOLS #83：consult 家族随统一登记册自 `../agent-tools.mjs` 取用（单一来源）
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, contextTool, batchTool, manifestTool, consultStartTool, consultStopTool, parentChannelTool, docCheckTool } = await import("../agent-tools.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, contextTool, batchTool, manifestTool, manifestReadTool, consultStartTool, consultStopTool, parentChannelTool, docCheckTool } = await import("../agent-tools.mjs")
   // 台账统一入口（2026-10-05 统一入口批——台账 #923）：全量变体 = depth-0 段 ∥ 只读变体 = 全部
   // depth>0 段。动态 import——ledger 链静态达 node:sqlite（W8 契约②）；两变体同名单对象、schema 窄化。
   const { ledgerTool, ledgerReadTool } = await import("../ledger.mjs")
@@ -149,7 +149,7 @@ export async function assembleFamilyTools({
       // 团队台账全量变体（五 action——同律：子代理段只挂读变体；登录态门在工具内）
       teamLedgerTool,
       // manifest 工具（`MANIFEST.md` §2.10 · 2026-10-08 · 台账 #1098）：主 agent 读写出口——
-      // **两模式同挂**（需求未设模式门）；子代理各段零挂（未装配 = 权限面第一道）。
+      // **两模式同挂**（需求未设模式门）；全量变体仅 depth-0——子代理各段挂只读变体（见下 `:187-193`）。
       manifestTool,
       // 文档纪律机检（`DOC-DISCIPLINE.md` §3.20 条目 S）：只读报告态——depth-0 主 agent 段；
       // 写文档 / 设计档的角色段（eng-coder / eng-designer）另挂（见下两分支）。
@@ -182,13 +182,15 @@ export async function assembleFamilyTools({
     // consult 段不入（其角色语义 = 父发起的一次性会诊，父在其 settle 前不期望中途对话）。
     // 台账只读变体（query / count）——全部 depth>0 角色段（含 consult ∕ 兜底；写三 schema 级不可达）；
     // 团队台账只读变体（team-ledger 批）同律。
-    : engChildRole === "eng-coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, advisorTool, verifyTool, batchTool(batchDoc), docCheckTool,
+    // manifest 只读变体（MANIFEST.md §2.10.1 · 2026-10-22 · 台账 #1738）：同名 `manifest`、action 枚举只剩 `read`；
+    // 与上两条只读先例同律挂在全部 depth>0 角色段（全量变体仅 depth-0——两变体互斥装配，同名不塌缩）。
+    : engChildRole === "eng-coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, advisorTool, verifyTool, batchTool(batchDoc), docCheckTool,
       ...(engChildSubagent ? [engChildSubagent] : [])]
-    : engChildRole === "eng-designer" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, batchTool(batchDoc), docCheckTool,
+    : engChildRole === "eng-designer" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, batchTool(batchDoc), docCheckTool,
       ...(engChildSubagent ? [engChildSubagent] : [])]
-    : role === "coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, verifyTool, advisorTool, ...(batchDoc ? [batchTool(batchDoc)] : [])]
-    : role === "consult" ? [recentChangesTool, ledgerReadTool, teamLedgerReadTool]
-    : [parentChannelTool, ledgerReadTool, teamLedgerReadTool]
+    : role === "coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, verifyTool, advisorTool, ...(batchDoc ? [batchTool(batchDoc)] : [])]
+    : role === "consult" ? [recentChangesTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool]
+    : [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool]
 
   // 固定段（装配序 = agent.tools → 固定段 → 家族段 → extraTools）：timer 全模式全深度；
   // plan 随模式位——ENG-PLAN-EXCLUSION（FR31 ① · KD8 卸载而非「注册 + 报错」· KD11 全深度两端）；

package/agent/helpers.mjs

@@ -275,6 +275,12 @@ export function turnFrame(seq, turn, maxTurns) {
   return { turn: seq, maxTurns: seq - turn - 1 + maxTurns }
 }
 
+/** #934（零落笔看门狗——AGENT-LOOP-UPSTREAM.md §6.32.2 ① 判据式）：上轮结账至今写序是否推进；非整数（未跟踪面 / NaN）⇒ true 记「有落笔」不判（不用 `?? 0` 兜底——未跟踪面当零落笔正是本收正要消除的误报方向）。 */
+export function wroteSince(agent, mark) {
+  const seq = agent._mutationSeq
+  return Number.isInteger(seq) ? seq !== mark : true
+}
+
 /** Repair malformed conversation history: remove orphan tool messages and fill missing tool results */
 export function repairHistory(history) {
   const out = []

package/agent/run-start.mjs

@@ -105,6 +105,7 @@ export async function beginRun(agent, input, callbacks, {
   // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值常量 / 零自动动作）：段起点复位（首段 /
   // 续跑新段——与 `_continueSegments` 同点）；段内累加，采集点在回合环（与 `_turnSeq` 同源面）。
   agent._zeroWriteTurns = 0
+  agent._segmentTurns = 0 // #934 B 面读数分母（§6.32.4）：同点复位——同段同源（分子 ≤ 分母）
   if (!resume) {
     // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：链内累计编号
     // 只在链起点复位——续跑（resume:true）不重置、不回退（编号帧公式见 helpers.mjs

package/agent/turn-loop.mjs

@@ -18,6 +18,7 @@ import {
   turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 TURN-CAP-CONTINUE.md §4）
   ContinueError,
   FILE_MUTATORS, toolTouchPaths,
+  wroteSince, // #934（§6.32.2 ① 判据式）：写序是否推进——轮顶 ∥ 撞帽收尾两处判据点共用
 } from "./helpers.mjs"
 
 export async function runTurnLoop(agent, {
@@ -57,9 +58,10 @@ export async function runTurnLoop(agent, {
   // §6.31.5 落痕写点门（#939）：载体吸收经 `carrierField` 单点（§6.31.4 同式）；动态 import = 零新增静态边（沿上方两条同款）。
   const { carrierField } = await import("../agent-tools/async-settle.mjs")
 
-  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）：计数基线——回合环逐轮
-  // 比对 `_touchedFiles` 增量（轮顶对上一轮结账；撞帽收尾轮在环外单结）。
-  agent._turnFilesMark = agent._touchedFiles.length
+  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）∥ #934（零落笔看门狗）：计数基线——
+  // 判据物 = 写序（每次写事件 +1，不去重）；`_touchedFiles` 是去重路径集，同档重写长度不变 ⇒ 旧判据在
+  // 此读成零落笔（本收正要消除的误报方向）。环内逐轮结账、撞帽收尾轮在环外单结（同一谓词）。
+  agent._mutSeqMark = agent._mutationSeq
 
   for (let turn = 0; turn < maxTurns; turn++) {
     // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环头检查点——中止恒以
@@ -73,21 +75,23 @@ export async function runTurnLoop(agent, {
     const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
     agent._currentTurn = frame.turn
     agent._maxTurns = frame.maxTurns
-    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今 `_touchedFiles`
-    // 零增 ⇒ 上一轮零落盘，计数 +1；mark 前移（收尾轮在环外结账——见下方 ContinueError 前）。
-    // #934（零落笔看门狗——§6.32.2 ① 单点采集）：streak 与越阈判定同点——上轮零写 ⇒ +1 并判越阈；
-    // 有写 ⇒ streak 归零 + 清闩（写后重臂——每连续零写段恰一条）。#417 计数语义逐字保持。
+    // #934 B 面读数分母（§6.32.4）：本段轮数逐轮 +1——段起点复位见 run-start.mjs（与零落笔计数同点）。
+    agent._segmentTurns = (agent._segmentTurns ?? 0) + 1
+    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今写序未推进
+    // ⇒ 上一轮零落笔，计数 +1；写序标每轮前移（撞帽收尾轮在环外结账——见下方 ContinueError 前）。
+    // #934（零落笔看门狗——§6.32.2 ① 单点采集）：streak 与越阈判定同点——上轮零落笔 ⇒ +1 并判越阈；
+    // 有落笔 ⇒ streak 归零 + 清闩（写后重臂——每连续零落笔段恰一条）。#417 计数与 streak 同源同谓词。
     if (turn > 0) {
-      if (agent._touchedFiles.length === agent._turnFilesMark) {
+      if (!wroteSince(agent, agent._mutSeqMark)) {
         agent._zeroWriteTurns += 1
         agent._zeroWriteStreak += 1
-        maybeZeroWriteAlert(agent) // #934：连续零写越阈 ⇒ 自动上行提醒（只推——§6.32）
+        maybeZeroWriteAlert(agent) // #934：连续零落笔越阈 ⇒ 自动上行提醒（只推——§6.32）
       } else {
         agent._zeroWriteStreak = 0
         agent._zeroWriteAlerted = false // 写后重臂
       }
     }
-    agent._turnFilesMark = agent._touchedFiles.length
+    agent._mutSeqMark = agent._mutationSeq
     // D2 (AGENT-LOOP-SUBAGENT.md §6.7.2): depth>0 children emit a ⟦ev⟧turn progress token each turn —
     // single emit point covering all three spawn tools; phase=llm (tool/done progress rides
     // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
@@ -271,9 +275,9 @@ export async function runTurnLoop(agent, {
     injectPostTurn(agent, results, recentCallSigs, callbacks, turn, { suspDriven })
   }
 
-  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）若零落盘同样计入——轮顶计数只
-  // 覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
-  if (maxTurns > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）单结——与环内同一谓词（不另作 alert ∥ streak
+  // 判定，链尾无下一轮可推报）；轮顶计数只覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
+  if (maxTurns > 0 && !wroteSince(agent, agent._mutSeqMark)) agent._zeroWriteTurns += 1
   // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环尾检查点——中止恒以
   // AbortError 收束（不落 ContinueError——用户 Stop 优先于继续提示；消费契约 = 外层按 reason 判定）。
   if (signal?.aborted) throw abortError(signal, "agent", "turn-tail")

package/agent-tools/batch-gate.mjs

@@ -16,8 +16,8 @@
  * 判据零变：本档不新增判据——只决定「判谁」与「何时强制」；判据与裁定串由产品引擎
  * `doc-check/index.mjs` 产出（判据源唯一）。引擎版本前置同源 = `doc-check/version.mjs`。
  *
- * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象；声明域已排除 `batches`，
- * 传入只产「跳过域外」行 = 假检查）；② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
+ * 两条边界（设计与实测同口径）：① **批档自身不入范围**（载体不是判据对象——判它只会把载体的行宽记成本批欠账）；
+ * ② **本轮提交面不在工具面**——`<批起 sha>` 只有父侧掌握，
  * ② 的写入集只认触达账 + 回执明示「基 sha 未定」，提交面由父侧协议清单兜（不静默）。
  */
 import { execFileSync } from "node:child_process"
@@ -123,7 +123,7 @@ 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") }
   }
@@ -135,7 +135,7 @@ function evaluate({ abs, cwd, agent, scope, clock }) {
   }
 
   // 范围（判谁）：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 +143,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/doc-check.mjs

@@ -1,11 +1,13 @@
 /**
  * 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
@@ -30,8 +32,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 +41,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") {
@@ -64,12 +66,15 @@ export const docCheckTool = {
       // 引擎版本校验先于引擎（A-DD30 ①）：stale 非空 ⇒ 直接 ERROR 串，不进引擎
       const version = staleEngineFiles()
       if (version.stale.length) return gateEngineError(version)
-      // 会话候选先取 `.md`（触达记账含代码档——代码档不是文档，不该进范围行）；域求交归引擎单源
+      // 会话候选先取 `.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())
+    // 报告态：清单是唯一范围来源——不给就是拒绝（不是「全域」）。引擎陈旧 ⇒ 首行前一行注记（A-DD30 ①）。
+    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 withEngineNote(runDocCheck(root, { docs: explicit, docsSource: "explicit" }).report, staleEngineFiles())
   },
 }

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,8 +94,10 @@ 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}`)
@@ -102,9 +108,13 @@ function readAction(target) {
     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 on the ancestor chain and none below — manifest action=init can create one at the target"
+      : "hint: no project on the ancestor chain and none below — 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 +133,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 +179,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 +208,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 })
+  },
+}