@thincoder/core 0.10.7 → 0.10.9

package/agent-tools/batch-skeleton.mjs

@@ -162,6 +162,93 @@ export function readSectionStatusWord(src, seg) {
   return null
 }
 
+/**
+ * 「不适用」声明行形态单源（§4.18-A——**一行一档**）：`> 不适用：§N —— <理由>`，§N ∈ {2,3,4}、
+ * 理由非空（`\S.*` = 至少一个非空白字符起头）。识别域 = §1 段体内（声明住 §1——D-BR30：工程模式
+ * 主 agent 的 append 域 = §1/§4/§6，写不进 §2/§3，而声明恰发生在 designer / 评审本轮不跑时 ⇒
+ * 段内声明形在需要的场合不可写）。声明 = 链门（`sectionContentState`）的合法满足面。
+ */
+const INAPPLICABLE_RE = /^>\s*不适用[：:]\s*§(\d+)\s*——\s*(\S.*)$/
+/** 可声明的段号集（§5 段号豁免——免声明；§6 不可声明——收口段必须带验证内容）。 */
+export const INAPPLICABLE_SEGMENTS = [2, 3, 4]
+/** §1 声明行的识别前缀（形不合扫描的宽网——行首命中它而完整形不合 ⇒ 拒，不静默当作无声明）。 */
+const INAPPLICABLE_PREFIX_RE = /^>\s*不适用/
+
+/** §N 段体行集（段头缺失 ⇒ null——create 是骨架唯一权威入口；行切分 = /\r?\n/——EOL 形态无关）。 */
+function sectionBodyLines(src, seg) {
+  const hdr = sectionHeaderRe(seg).exec(src)
+  if (!hdr) return null
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const body = src.slice(hdr.index + hdr[0].length, next ? next.index : src.length)
+  const nl = body.indexOf("\n") // 跳过段头行余文（`## §N …` 的标题部分）
+  return (nl >= 0 ? body.slice(nl + 1) : "").split(/\r?\n/)
+}
+
+/**
+ * 段内容判据**单源**（§4.18-A closeout chain gate 的判空口径；D-BR30 判据单源——**不许两套**；
+ * §4.13 的 §6 旧判据 `sectionSixHasContent` 改由本谓词承担——§6 为唯一缺段时拒串仍取旧函数）。
+ * 返回三态：`content`（段体至少一行非排除类）∥ `not-applicable`（§1 声明该段不适用且理由非空——
+ * 仅 §2/§3/§4）∥ `empty`。排除类（判空依据——「标题在、正文零行」判空）：空行 ∥ 标题行
+ * （`^#{1,6}\s`）∥ `**状态行**：` 行 ∥ `<§N 模板占位：…>` 行 ∥ 「不适用」声明行。
+ * 口径收正注：旧 `sectionSixHasContent` 对「只有子标题（`### …`）」判非空；本谓词按 §4.18-A 判空
+ * （子标题属排除类标题行）——设计档 §4.18-A 明文收窄。
+ * @param {string} src — 档全文
+ * @param {number|string} seg — 段号（§1–§6；§1 恒 `content`——主 agent 自述段不设前置）
+ * @returns {"content"|"not-applicable"|"empty"} 段内容三态
+ */
+export function sectionContentState(src, seg) {
+  const n = Number(seg)
+  if (n === 1) return "content"
+  const lines = sectionBodyLines(src, n)
+  if (lines === null) return "empty" // 段头缺失 = 空（骨架由 create 一次预写；缺失即无内容）
+  if (lines.some((l) => NONEMPTY_RE.test(l) && !EXCLUDED_LINE_RE.test(l))) return "content"
+  // 段体无实质内容 ⇒ 查 §1 声明（仅 §2/§3/§4 可声明；理由非空——INAPPLICABLE_RE 的 (\S.*) 已保证）
+  if (INAPPLICABLE_SEGMENTS.includes(n)) {
+    for (const l of sectionBodyLines(src, 1) ?? []) {
+      const m = INAPPLICABLE_RE.exec(l)
+      if (m && Number(m[1]) === n) return "not-applicable"
+    }
+  }
+  return "empty"
+}
+
+/** 非空白行谓词（空行排除）。 */
+const NONEMPTY_RE = /\S/
+/** 排除类行判据：标题行（`^#{1,6}\s`）∥ `**状态行**：` 行 ∥ `<§N 模板占位：…>` 行 ∥ 「不适用」声明行
+ *  （空行由 NONEMPTY_RE 单独排除——四类合一次判定）。 */
+const EXCLUDED_LINE_RE = /^#{1,6}\s|^\s*\*\*状态行\*\*[：:]|^<§\d+ 模板占位[：:]|^>\s*不适用/
+
+/**
+ * 声明形不合拒绝句（§4.18-A J3——形不合 ⇒ 拒，**不静默当作无声明**）：行首命中
+ * `^>\s*不适用` 却不满足完整形（缺 `——` ∥ 缺理由 ∥ § 号 ∉ {2,3,4}）。
+ * 逐字文本 = `TOOLS.md` §6.24 J3。
+ * @param {string} line — 违规行原文
+ * @returns {string} 完整拒绝句（调用方 throw new Error(...)）
+ */
+export function inapplicableDeclarationError(line) {
+  return "batch: 「不适用」声明形不合（malformed inapplicability declaration）— one line per section: " +
+    "`> 不适用：§N —— <reason>` with a non-empty reason, §N ∈ {2,3,4} (§5 needs no declaration; §6 is never declarable). " +
+    `Offending line: ${line}. Nothing was written.`
+}
+
+/**
+ * §1 声明行机械扫描（链门前置判据——形不合 ⇒ 拒，不静默）：识别域 = §1 段体。行首命中
+ * `^>\s*不适用` 而完整形不合（INAPPLICABLE_RE 不中 ∥ § 号 ∉ {2,3,4}）⇒ 返回违规行原文；
+ * § 号 ∈ {2,3,4} 且理由非空 ⇒ 合法。无违规 ⇒ null。
+ * @param {string} src — 档全文
+ * @returns {string|null} 首个形不合声明行原文 / null
+ */
+export function malformedInapplicableLine(src) {
+  for (const l of sectionBodyLines(src, 1) ?? []) {
+    if (!INAPPLICABLE_PREFIX_RE.test(l)) continue
+    const m = INAPPLICABLE_RE.exec(l)
+    if (!m || !INAPPLICABLE_SEGMENTS.includes(Number(m[1]))) return l
+  }
+  return null
+}
+
 /**
  * §N 段内「`**状态行**：` 行存在性」判据（#422③——close 对无状态行档自建机读位的**采集面**：
  * 与 readBatchStatusLine 的「值可解析」正交——无行 ⇒ 可自建；有行而值不可解析 ⇒ 仍 fail-closed）。

package/agent-tools/batch.mjs

@@ -32,6 +32,7 @@ import { readFileSync, writeFileSync } from "node:fs"
 import { DESC } from "../tools/shared.mjs"
 import { SEGMENT_BY_ROLE, SEGMENT_BY_ROLE_NORMAL, DEPTH0_SEGMENTS, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
 import { batchDocBases, resolveBatchDocPath } from "./batch-paths.mjs"
+import { gateReceiptLine, gateRefusalMessage, runBatchGate } from "./batch-gate.mjs"
 import { closeBatchRecord, createBatchRecord, findInFlightBatch, statusBatchRecord } from "./batch-lifecycle.mjs"
 
 export { SEGMENT_BY_ROLE, batchDocBases, resolveBatchDocPath }
@@ -154,7 +155,8 @@ function insertIntoSection(src, seg, text) {
  *    eng-coder → §5 · coder（普通模式分支增表）→ §5（迁移错误面，"batch_segment:" 前缀**逐字保持**）；
  *  - 目标定位（D-BR21）：depth-0 path 可选（缺省 = findInFlightBatch 唯一在飞批）；子代理/评审
  *    传 path ⇒ 拒，目标 = spawn/实例绑定；
- *  - 其余（gate / text 校验 / 剥凭证 / 骨架保护 / **死占位机检（F11-C）** / 插入 / 记账 / 回执）逐字保持原语义。
+ *  - 其余（gate / text 校验 / 剥凭证 / 骨架保护 / **死占位机检（F11-C）** / **文档机检门（§3.20 结构兜底 ①——
+ *    子代理写 §2 / §5：REFUSED ⇒ 拒写，ERROR ⇒ 写 + 回执明示）** / 插入 / 记账 / 回执）逐字保持原语义。
  */
 function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
   const agent = ctx?.agent ?? {}
@@ -228,11 +230,17 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
   // （段体引用豁免——判据可辨性收正，`TOOLS.md` §6.20；骨架枚举单源 = skeleton 档 TEMPLATE_PLACEHOLDERS）。
   const residues = findPlaceholderResidue(src)
   if (residues.length) throw new Error(placeholderResidueError(residues))
+  // 文档机检门（§3.20「结构兜底」①——门位 = 既有拒因全部之后、insertIntoSection / 写盘之前）：
+  // 只挂子代理写 §2 / §5（depth-0 与评审不检）；REFUSED ⇒ throw；PASS ⇒ 照写；ERROR / 门自身异常 ⇒ 写 + 回执明示。
+  const gate = !depth0 && !review && (n === 2 || n === 5)
+    ? runBatchGate({ abs, cwd, agent, scope: "writer" })
+    : null
+  if (gate?.state === "refused") throw new Error(gateRefusalMessage(gate, "append"))
   const { written, roundN } = insertIntoSection(src, n, body)
   writeFileSync(abs, written)
   // #84：记账面按端注入（缺省 no-op = CLI 语义零行为变——端装配经 configureBatchSegment 覆盖）。
   onWritten?.(agent, abs)
-  return `batch_segment: appended ${body.length} characters to §${n} of the batch record${roundN ? ` (### 轮次 ${roundN}（评审子代理）)` : ""}.`
+  return `batch_segment: appended ${body.length} characters to §${n} of the batch record${roundN ? ` (### 轮次 ${roundN}（评审子代理）)` : ""}.${gateReceiptLine(gate)}`
 }
 
 /**
@@ -271,7 +279,7 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
         },
         note: {
           type: "string",
-          description: "status only — prose that lands as a parenthetical on the status line (`**状态行**：进行中（note）`). Single line; must carry no STATUS_WORDS keyword (those go in `value`) and no skeleton placeholders. Omit for a plain value.",
+          description: "status only — prose that lands as a parenthetical on the status line (`**状态行**：进行中（note）`). Single line; must carry no STATUS_WORDS keyword (those go in `value`) and no skeleton placeholders. Omit for a plain value. On the reopen path (a frozen record, §1 → 进行中) `note` is REQUIRED and lands verbatim in the §1 reopen record instead of the status-line parenthetical (it may name the frozen keyword there).",
         },
         topic: {
           type: "string",

package/agent-tools/checkpoint.mjs

@@ -72,7 +72,7 @@ export function registerTurnCapCheckpoint(child, carrier, { turn = 0, signal } =
     const onAbort = () => finish(false)
     rec.resolve = finish
     signal?.addEventListener?.("abort", onAbort, { once: true })
-    // 注册后复检（`permission-gate.mjs:80-81` 同款序）：监听只认注册后的状态转移，
+    // 注册后复检（`permission-gate.mjs` 的 `permissionGate` 同款序）：监听只认注册后的状态转移，
     // 窗口内已中止 ⇒ 监听不落地，此处兜住。
     if (signal?.aborted) { abortedNow = true; onAbort() }
   })

package/agent-tools/context.mjs

@@ -3,9 +3,10 @@
  * 单一工具三操作（用户定形 F-CC5）：`stats`（感知 F-CC1）· `prune`（噪声清理 F-CC3）· `compact`（主动压缩 F-CC2，携 focus + 自动附任务/目标 + 可回查锚——裁令 A/D）。
  * 描述外置（tool-docs/context.md——#15 统一面：文本单点 = tool-docs，DESC 加载）；装配面 = 登记册 `agent-tools.mjs`（#83）+ `agent/family-tools.mjs` 的 depth-0 段（`depthOnly`）——两端自动同表；**depth>0 不给**（§6.16.6）。
  * 本档同时是**注记文案 / 轻推行 / 回执文案的单源**（核与 VSC 的 run-stages 消费点经动态 import 取用——零新增静态边）。
- * 机械面：`stats` 不新增第三口径（阈值取本回合判定值；百分比走 `historyPercent` 与状态行同式）；`prune` = 合格集（`token-window.mjs` 单源）+「原位换内容」应用面（`context.mjs`）；`compact` **当次零执行**（只登记 `agent._pendingCompact`，由下一安全点消费——§6.16.2）。
+ * 机械面：`stats` 不新增第三口径（首行主口径 = 窗口占用 total / window，压缩线以具名数值 + 距线呈现；第 4 行走 `historyPercent` 与状态行同式）；`prune` = 合格集（`token-window.mjs` 单源）+「原位换内容」应用面（`context.mjs`）；`compact` **当次零执行**（只登记 `agent._pendingCompact`，由下一安全点消费——§6.16.2）。
  */
 import { contextUsage, estimateTokens, collectStaleToolOutputs, historyPercent, PRUNE_MIN_TOKENS } from "../token-window.mjs"
+import { requestBudget } from "../config.mjs"
 import { pruneStaleToolOutputs, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
 import { slotPath } from "../session-slots.mjs"
 // #15 描述外置：描述文本单点 = tool-docs/context.md（DESC 单解析面，缺档抛错语义不变）
@@ -72,16 +73,38 @@ function statsReport(agent) {
     toolCount++
     toolOut += estimateTokens([m])
   }
-  const pct = Math.round((usage.total / usage.threshold) * 100)
+  const pct = Math.round((usage.total / usage.window) * 100) // 主口径 = 窗口占用（§6.16.4 首行定稿 / D-CC29）
   const toGo = Math.max(0, usage.threshold - usage.total) // 已越阈值 ⇒ 0（自动压缩将在下一安全点接手）
   const info = agent?._lastCompressInfo
   const compaction = !info ? "none"
     : info.mode === "summary" ? `last summary freed ${info.tokensFreed} tokens`
       : "last fallback truncation"
+  // Cache line (batch 2026-10-18-context-cache-visibility): the provider reports
+  // prompt_cache_hit/miss per response; the core now tallies them so the question
+  // "is the prefix cache actually helping?" is answered by a reading, not a guess.
+  const cacheHit = agent?._cacheHitTokens ?? 0
+  const cacheMiss = agent?._cacheMissTokens ?? 0
+  const cacheTurns = agent?._usageTurns ?? 0
+  const cacheTotal = cacheHit + cacheMiss
+  const cacheLine = cacheTurns === 0
+    ? "Cache: no provider usage readings yet (hit/miss arrive with the first response)"
+    : `Cache: hit ${cacheHit} · miss ${cacheMiss} tokens (${Math.round((cacheHit / cacheTotal) * 100)}% hit) across ${cacheTurns} response(s)`
   return [
-    `Context ≈${usage.total} tokens vs compaction threshold ${usage.threshold} (${pct}% — ${toGo} to go); window ${usage.window}`,
+    `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})
+    // · prompt {total} · to compaction line {threshold − total} · to window limit {limit − total}
+    // 两距离带符号（负 = 已越）；maxTokens 未发写 not sent、来源写 absent（该档守卫不覆盖——§6.17 射程）。
+    (() => {
+      const budget = requestBudget(agent?.provider)
+      const mt = budget.maxTokens === undefined ? "not sent" : String(budget.maxTokens)
+      return `Request budget: window ${budget.window} (${budget.windowSource}) · max_tokens ${mt} (${budget.maxTokensSource})`
+        + ` · prompt ${usage.total} · to compaction line ${usage.threshold - usage.total}`
+        + ` · to window limit ${budget.limit - usage.total}`
+    })(),
     `Segments ≈: system ${usage.system} · tools ${usage.tools} · history ${usage.history} (basis: ${usage.basis})`,
     `History: tool outputs ${toolOut} tokens in ${toolCount} msgs · prunable stale ${stale.tokens} tokens in ${stale.indexes.length} msgs · protected tail ${stale.tailCount} msgs`,
+    cacheLine,
     `Status line: context ${historyPercent(agent?.history ?? [], agent?.provider)}% (${usage.history} history estimate / ${usage.window} window)`,
     `Compaction so far: ${compaction} · failures ${agent?._compressFailures ?? 0}/${COMPRESS_FAILURE_LIMIT}`,
   ].join("\n")
@@ -100,8 +123,8 @@ function pruneReceipt(agent) {
 
 /**
  * 可回查锚（父侧裁令 A · §6.16.7 两分支逐字）：回执尾段给出「压掉的可一步取回」的坐标与调用形。
- * 取回面 = `read_history` 既有 `path=`（**不新建通道**）；未绑定槽（会话首次保存前 / VSC 端面板槽
- * 不在 agent 上）⇒ `cwd:` 发现面（等效取回，已登记的端差）。
+ * 取回面 = `read_history` 既有 `path=`（**不新建通道**）；未绑定槽（会话首次保存前——CLI；VSC 恒绑定、不落本支——§6.16.7）
+ * ⇒ `cwd:` 发现面（等效取回——`cwd` 缺省时字面 `cwd:undefined` 的降级形，工具内不抛）。
  */
 function retrievabilityAnchor(agent) {
   const slot = agent?._slot

package/agent-tools/design-slots.mjs

@@ -1,13 +1,14 @@
 /**
  * design-slots.mjs — design-token 槽位清点 + 消费核（2026-10-07 批 ledger-tool · 台账 #927 并入）。
- * 设计单源 = `docs/core/design/DESIGN-TOKEN-SETTLEMENT.md` §10（F-SL1 清点面 / F-SL2 批量消费）。
+ * 设计单源 = `docs/core/design/DESIGN-TOKEN-SETTLEMENT.md` §9（F-SL1 清点面 / F-SL2 批量消费）。
  *
  * 面一 `executeDesignSlotsAction`（`subagent` action `design-slots`——只读）：
  *   数据源 = 槽文件权威表（`readEngTokensFromSlot`——无 TTL 过滤原样）∪ 内存 Map（并集去重，
  *   冲突以槽为准——D-S3 同源）；**零写**（不 reconcile 回写、不落盘）。列表面 = 逐槽一行
- *   （designId ∥ live/expired ∥ ageDays ∥ expiresAt ∥ 批；龄序 = 最老在前）+ 计数尾行；
- *   「批」= `_advisorRuns` 按 designId 命中 run 的 `docSetKey` 中 `batches/` 段档取 basename
+ *   （designId ∥ live/expired ∥ ageDays ∥ expiresAt ∥ 批 ∥ designToken（末位，恒携）；龄序 = 最老在前）
+ *   + 计数尾行；「批」= `_advisorRuns` 按 designId 命中 run 的 `docSetKey` 中 `batches/` 段档取 basename
  *   （KD-SL2——零新存储；不可得 ⇒ `—`）。
+ *   `designId` 过滤单槽（trim 精确匹配；空串视同缺省；未知 ⇒ 拒 + 列在场 id）；缺省 = 现行清点面逐字零变；零写同前。
  * 面二 `executeConsumeDesignAction`（`subagent` action `consume-design` 消费核——自
  *   `subagent-spawn.mjs` 迁入）：选择器恰一（`designId` ∥ `designIds` ∥ `expired` ∥
  *   `olderThanDays`——KD-SL3 fail-closed 不猜）；目标集 = 并集视图按选择器解析 → 逐枚移出
@@ -84,6 +85,8 @@ const byOldest = (a, b) => (b.ageDays ?? -Infinity) - (a.ageDays ?? -Infinity)
  * `subagent` action `design-slots`（F-SL1——只读清点面）：工程模式父侧限定（与 consume-design
  * 同门）。输出 = 行文本（逐槽行 + 计数尾行）；字段 / 序 / 降级标记 = 契约，行内措辞 = 实现面。
  * 分类 = 只读（planMode 放行 / 免审批 / digest 放行——谓词在 `agent/dispatch-gates.mjs`）。
+ * `designId` 过滤单槽（trim 精确匹配；空串视同缺省；未知 ⇒ 拒 + 列在场 id）；
+ * 缺省 = 全量清点（不改变行契约——令牌列恒携）；零写（不 reconcile / 不落盘）。
  */
 export function executeDesignSlotsAction(args, ctx) {
   const parent = ctx?.agent
@@ -94,10 +97,20 @@ export function executeDesignSlotsAction(args, ctx) {
   const ttlMs = effectiveTokenTtlMs(parent)
   const entries = [...unionSlots(parent)].map(([id, t]) => slotFacts(parent, id, t, now, ttlMs))
   entries.sort(byOldest)
-  const lines = entries.map((e) =>
-    `- designId=${e.designId} status=${e.expired ? "expired" : "live"} ageDays=${e.ageDays === null ? "—" : e.ageDays.toFixed(1)} expiresAt=${e.expiresAt === null ? "—" : new Date(e.expiresAt).toISOString()} batch=${e.batch}`)
-  const live = entries.filter((e) => !e.expired).length
-  lines.push(`design-slots: ${entries.length} slot(s) — ${live} live / ${entries.length - live} expired`)
+  // 参数面（fail-closed——不猜）：`designId` trim 后精确匹配、空串视同缺省；未知 ⇒ 拒 + 列在场 id。
+  const rawId = args?.designId
+  const designId = rawId === undefined || rawId === null ? "" : String(rawId).trim()
+  let selected = entries
+  if (designId) {
+    selected = entries.filter((e) => e.designId === designId)
+    if (selected.length === 0) {
+      const held = entries.length > 0 ? entries.map((e) => e.designId).join(", ") : "(none)"
+      throw new Error(`design-slots: unknown designId ${JSON.stringify(designId)} — no slot holds this id (held design ids: ${held}).`)
+    }
+  }
+  const lines = selected.map((e) => `- designId=${e.designId} status=${e.expired ? "expired" : "live"} ageDays=${e.ageDays === null ? "—" : e.ageDays.toFixed(1)} expiresAt=${e.expiresAt === null ? "—" : new Date(e.expiresAt).toISOString()} batch=${e.batch} designToken=${e.expiresAt === null ? "—" : e.token}`)
+  const live = selected.filter((e) => !e.expired).length
+  lines.push(`design-slots: ${selected.length} slot(s) — ${live} live / ${selected.length - live} expired${designId ? " (filtered by designId)" : ""}`)
   return lines.join("\n")
 }
 

package/agent-tools/doc-check.mjs

@@ -0,0 +1,75 @@
+/**
+ * agent-tools/doc-check.mjs — `doc_check` 工具：文档纪律机检（产品内建 · 两种问法）。
+ *
+ * 设计 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S（判据 = 锚 ∥ 行宽 · 声明面驱动）。
+ * 工具形：**无动作枚举**——`mode` = 同一条判据的两种问法（`report` = 全域报告态 ∥ `gate` = 交付时点
+ * 的范围化裁定）；**只读**（零副作用 · 免审批 · 可并行）；参数 `target` / `mode` / `docs`
+ * （`target` 指向多项目工作区 ⇒ 报明候选并要求指名，同 `manifest` 工具面）。
+ * 判据参数读目标项目的 `PROJECT-MANIFEST.json` `checkConfig`——不硬编码任何本仓路径（换项目开箱可用）。
+ * `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"),
+  parameters: {
+    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." },
+    },
+  },
+  readonly: true,
+  execute(args, ctx) {
+    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 (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."
+    }
+    const view = projectRootView(target)
+    if (view.state === "workspace") {
+      if (mode === "gate") {
+        return [
+          "DOC-CHECK GATE: ERROR（多项目工作区：请指名 target）",
+          `候选：${view.candidates.join(" ∥ ")}`,
+          "处置：指名项目根（`target`）后复跑",
+        ].join("\n")
+      }
+      return `doc_check: ${target} is a workspace holding ${view.candidates.length} projects — pass the project root explicitly via target:\n` +
+        view.candidates.map((c) => `- ${c}`).join("\n")
+    }
+    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())
+  },
+}

package/agent-tools/eng.mjs

@@ -12,6 +12,7 @@
  * (subagent-spawn.mjs). See docs/design/ENG-TOKEN-BINDING-TUNING.md §5/§5.1 (F-R16).
  * #41（2026-09-18）：enter 分支改「先判后翻」——判据 = 入口决策树单源
  * `resolveEngineeringManifest`（docs/core/design/MANIFEST.md §2.8 F2 / KD-M1-20/21）；
+ * **可拒面 = 仅「档非法」一格**（工作区 `workspace` 放行——零附着，模式照开）；
  * 拒翻 ⇒ 返回原因串 + **零副作用**（模式保持 OFF）。OFF 方向与幂等 enter 零改。
  */
 import { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "../agent.mjs"
@@ -74,15 +75,16 @@ export const engTool = {
         return "Engineering mode already active. Existing design tokens stay valid."
       }
       // #41 先判后翻（MANIFEST.md §2.8 F2 / KD-M1-21）：判据 = 入口决策树**单源**
-      // （resolveEngineeringManifest——KD-M1-20），判据通过才写态。拒翻 ⇒ 返回原因串 +
+      // （resolveEngineeringManifest——KD-M1-20），判据通过才写态。**可拒面 = 仅「档非法」格**
+      // （工作区 `workspace` ⇒ 放行——**零附着**：无项目档可附，模式照开）；拒翻 ⇒ 返回原因串 +
       // **零副作用**（不清 token / 不重置 _advisorRuns / 不入列 ENG_ON_REMINDER /
       // 不动 _lastEngState / 不触镜像缝）；准 ⇒ 缺档格就地建档（writer:'main'）+
       // agent.manifest ← 结果（翻转面唯一赋值点——相位行当回合起活，§2.8 F2 放行行）。
       const r = resolveEngineeringManifest(ctx.agent.cwd ?? ctx.cwd ?? process.cwd(), { writer: "main" })
-      if (!r.ok) {
+      if (!r.ok && r.code !== "workspace") {
         return `Error: cannot enter engineering mode — ${r.message} (mode unchanged)`
       }
-      ctx.agent.manifest = r.manifest
+      ctx.agent.manifest = r.ok ? r.manifest : null // 工作区放行 ⇒ 零附着（显式置 null——§2.8 F2 放行行）
       ctx.agent.config.agent.engineering = true
       // FR31 ③ / KD10（翻转点①）：工程模式 ⇒ planMode 恒 false——中途开模式时清残留
       //（planMode 位 + reminder 计数 + 未注入的 plan 提示语），半状态（工程纪律 × plan 只读）不产生。

package/agent-tools/manifest.mjs

@@ -3,7 +3,7 @@
  * agent 侧读写出口（2026-10-08 · 台账 #1098；权威设计 = `docs/core/design/MANIFEST.md` §2.10）。
  *
  * 三动作（KD-M1-38）：
- *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|ambiguous|no-project`）；
+ *  - `read`  ⇒ `projectView(target)` 五态报明（稳定锚 `state=ok|missing|invalid|workspace|no-project`）；
  *              `ok` 态再 `readManifest(view.root)` 取细节面（`projectView` 面不含 `missingKeys` /
  *              `unknownKeys`）——**不抛**（缺档报明，非拒）。
  *  - `init`  ⇒ 缺档建默认档（`initManifest`——内容 = `DEFAULT_MANIFEST`）；**已带档 ⇒ 拒**
@@ -15,12 +15,12 @@
  * （`version` / `phase` / `promptsLanding` / `codePaths` 整键）+ `nestedKeys` 子键
  * （`docRoot.*` / `checkConfig.*` / `index.*`（含 `publicRepos`）/ `advisor.*`）；**四族整键写
  * （传整个对象）⇒ 拒**；白名单外 ⇒ 拒（拼写保护——未知键写盘 = 静默死键，KD-M1-36 问题本体）。
- * `value` 解析 = 同款口径 `settings.mjs:216-228`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
+ * `value` 解析 = 同款口径 `settings.mjs` 的 `parseValue`（先 `JSON.parse`，失败取字面串；`"null"` ⇒ `null`
  * ——`docRoot.*` 的「本面无」，KD-M1-37）。
  *
  * 目标面（KD-M1-39——判据复用零新解析器）：`read` = `projectView`；`init` / `write` =
- * `projectRootView`（歧义 ⇒ 拒 + 候选全列——不猜）；`resolveProjectRoot` 对歧义塌缩 `null` 再回落 cwd
- * ⇒ 写 / 建两动作**不得**直用。
+ * `projectRootView`（工作区 ⇒ 拒 + 下辖项目全列 + 显式 `target` 指引）；`resolveProjectRoot` 对
+ * 工作区塌缩 `null` 再回落 cwd ⇒ 写 / 建两动作**不得**直用。
  *
  * 写路径复用（零新写路径）：落盘恒经 `writeManifest` / `initManifest`——`writer` 恒显式 `'main'`
  * （缺省 `'subagent'` = 写门 fail-closed 缺省，KD-M1-3 / AC-M1-5 零改）。
@@ -43,7 +43,7 @@ function refuse(action, reason) {
   return new Error(`manifest ${action}: refused — ${reason}`)
 }
 
-/** `target` 解析（先例 `eng.mjs:81` 缺省会话锚 ∥ `git.mjs:32-35` 相对形归一）：缺省 = 会话锚
+/** `target` 解析（先例 `eng.mjs` 的 `resolveEngineeringManifest` 缺省会话锚 ∥ `git.mjs` 的 `resolveBaseDir` 相对形归一）：缺省 = 会话锚
  *  （`ctx.agent.cwd ?? ctx.cwd ?? process.cwd()`）；显式相对形按会话锚归一（绝对形原样）。 */
 function resolveTarget(args, ctx) {
   const base = ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
@@ -65,7 +65,7 @@ function isWritableKey(key) {
   return false
 }
 
-/** `value` 解析（同款口径 = `settings.mjs:216-228`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
+/** `value` 解析（同款口径 = `settings.mjs` 的 `parseValue`）：先 `JSON.parse`（`"null"` ⇒ `null`；数值 /
  *  布尔 / 数组皆 JSON 形），失败取字面串（裸串如 `docs/design`）。 */
 function parseValue(raw) {
   const s = String(raw)
@@ -83,14 +83,14 @@ function setKeyPath(obj, path, value) {
   cur[segs[segs.length - 1]] = value
 }
 
-/** 歧义拒文案（候选全列——不猜；init / write 共用）：多候选 = 显式指定 target，机制不代选。 */
-function ambiguousReason(target, candidates) {
-  return `ambiguous target ${target} — ${candidates.length} candidate projects (the mechanism never picks one); pass target explicitly:\n` +
+/** 工作区拒文案（下辖项目全列 + 显式 `target` 下一步——init / write 共用；事实行，非二义框定）。 */
+function workspaceReason(target, candidates) {
+  return `${target} is a workspace holding ${candidates.length} projects — pass the project root explicitly via target:\n` +
     candidates.map((c) => `- ${c}`).join("\n")
 }
 
 /** read 动作（五态报明——**不抛**）：`state=` 稳定锚 + 各态附行（ok 细节面 / missing 引导 /
- *  ambiguous 候选全列 / invalid 错误行）。 */
+ *  workspace 下辖项目全列 / invalid 错误行）。 */
 function readAction(target) {
   const view = projectView(target)
   const lines = [`state=${view.state}`]
@@ -105,10 +105,10 @@ function readAction(target) {
     lines.push(`hint: run manifest action=init to create the default manifest here`)
   } 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`)
-  } else if (view.state === "ambiguous") {
-    lines.push(`candidates (${(view.candidates ?? []).length}):`)
+  } else if (view.state === "workspace") {
+    lines.push(`projects (${(view.candidates ?? []).length}):`)
     for (const c of view.candidates ?? []) lines.push(`- ${c}`)
-    lines.push(`hint: pass target explicitly — the mechanism never picks one`)
+    lines.push(`hint: pass target explicitly — the target must be one of the projects above`)
   } else if (view.state === "invalid") {
     if (view.errors?.length) lines.push(`errors=${view.errors.join("；")}`)
   }
@@ -122,13 +122,13 @@ export const manifestTool = {
     type: "object",
     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. Ambiguous targets are refused with the full candidate list (never picks one)." },
+      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", },
       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"],
   },
-  readonly: false, // 动作级分类（dispatch-gates `isSubagentReadonlyAction`）：read = 只读类；init / write 保持侧效门
+  readonly: false, // 动作级分类（dispatch-gates `isReadonlyAction`）：read = 只读类；init / write 保持侧效门
   async execute(args, ctx) {
     const action = args?.action
     if (!["read", "init", "write"].includes(action)) {
@@ -138,10 +138,10 @@ export const manifestTool = {
 
     if (action === "read") return readAction(target)
 
-    // init / write：目标面 = `projectRootView`（歧义直读形——不猜；KD-M1-39）
+    // init / write：目标面 = `projectRootView`（直读形——工作区不成目标；KD-M1-39）
     const rootView = projectRootView(target)
-    if (rootView.state === "ambiguous") {
-      throw refuse(action, ambiguousReason(target, rootView.candidates))
+    if (rootView.state === "workspace") {
+      throw refuse(action, workspaceReason(target, rootView.candidates))
     }
 
     if (action === "init") {

package/agent-tools/parent-channel.mjs

@@ -34,7 +34,7 @@
  * 两端共用的提示行携参（队首 ask 的 `from` + 单行归一截断的 `message`）；两端各持一份 = 漂移源（D2）。
  *
  * 模块图：静态 import 核单点 `async-settle.mjs`（`carrierField` / `getAsyncPool` /
- * `tombstoneOf` / `wakeAsyncWaiters`——同层既有导出，同 `async-discard.mjs:35` 先例；唤醒走
+ * `tombstoneOf` / `wakeAsyncWaiters`——同层既有导出，同 `async-discard.mjs` 的 `async-settle.mjs` 静态导入先例；唤醒走
  * 既有静态边，零新增）+ `../context.mjs`（`pushReal`）
  * / `../agent/helpers.mjs`（`escapeXml`）/ `../log.mjs`（`logEvent`）；单向、叶子向、无环。
  * 登记册导出（`agent-tools.mjs`）→ 家族矩阵装配（`agent/family-tools.mjs` depth>0 段）。
@@ -55,7 +55,7 @@ export const UPSTREAM_ASK_MAX_INFLIGHT = 1
 
 /** 工具返回注（异步形——sync: false；答复按普通指令在下回合边界到达）。 */
 const ASYNC_NOTE =
-  "delivered to your parent's queue — consumed at the parent's next turn boundary (non-blocking). " +
+  "delivered to your parent's queue — consumed at the parent's next delivery round (idle wake or suspension window; not during a user turn), non-blocking. " +
   "Keep working on the unaffected parts; a reply arrives as an ordinary instruction at your next turn boundary. " +
   "If your run ends first, report the unanswered part as not done."
 
@@ -73,7 +73,7 @@ const refused = (error) => JSON.stringify({ status: "error", error })
  *   ① 父字段在场 ⇒ 父对象（CLI 形主容器——写侧不变）；
  *   ② 缺 ⇒ `carrierField` 回退 `history` 命中 ⇒ **借用同一容器**（不另建分叉）；
  *   ③ 两者皆无 ⇒ 建在父字段 + **载体别名**（`parent.history._childUpstream = parent._childUpstream`
- *      ——同 `writeTombstone` 借用规则扩张句的既有形态，`agent-tools/async-settle.mjs:73-83`）。
+ *      ——同 `writeTombstone` 借用规则扩张句的既有形态，`agent-tools/async-settle.mjs` 的 `writeTombstone`）。
  */
 function upstreamHolder(parent) {
   if (!Array.isArray(parent._childUpstream)) {

package/agent-tools/review-facts.mjs

@@ -142,11 +142,11 @@ export function noteReviewDelivered(agent, run) {
 }
 
 /** 分支③候选底座（`MANIFEST.md` §2.5「路径归一增量」族第四笔 · 2026-10-05 · #945）：现行
- *  `projectRootView(cwd)` 集（ok → [root]；ambiguous → candidates 按名序；none → 空集）＋
+ *  `projectRootView(cwd)` 集（ok → [root]；workspace → candidates 按名序；none → 空集）＋
  *  cwd 祖先链全量目录（自父目录起至盘根、最近→远、去重、现行集在前）——容器相对形在子仓锚下
  *  可解析；受理判据（目标解析位最近 manifest 声明面）∥ 围栏 ∥ 可读唯一化 ∥ fail-closed 歧义零改。 */
 function candidateRoots(view, cwd) {
-  const current = view.state === "ok" ? [view.root] : view.state === "ambiguous" ? view.candidates : []
+  const current = view.state === "ok" ? [view.root] : view.state === "workspace" ? view.candidates : []
   const ancestors = []
   for (let d = dirname(resolve(cwd)); ; ) {
     ancestors.push(d)

package/agent-tools/settings.mjs

@@ -127,7 +127,7 @@ function _checkShape(path, spec, value) {
     }
     return
   }
-  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs:25-36 同判据；
+  // nonEmptyString —— defaultModel 另加 provider:model 形态面（与 model-ref.mjs 的 `parseModelRef` 同判据；
   // 存在性面不查——D-S2.5）
   if (typeof value !== "string" || !value.trim()) throw _expectsError(path, spec.expects, value)
   if (spec.providerModel) {