@thincoder/core 0.10.8 → 0.10.9

package/ledger-tools.mjs

@@ -10,7 +10,7 @@
  * 接线：族出口 = `ledger.mjs`（re-export——消费面 agent/family-tools.mjs；旧读二装配面已清零）；
  * 消费侧一律动态 import（`ledger-db.mjs` 静态 import node:sqlite ⇒ W8 契约②）。
  */
-import { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
+import { ledgerAdd, ledgerClose, ledgerCloseBatch, ledgerCount, ledgerQuery, ledgerUpdate, ledgerUpdateBatch } from "./ledger-cmd.mjs"
 import { resolveLedgerRoot } from "./ledger-db.mjs"
 import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger.md（DESC 单解析面）
 
@@ -37,37 +37,47 @@ const argPreview = (v) => {
 /** 枚举取值域文本（P3 / P5 文案同源）。 */
 const enumText = (values) => `{${values.join(", ")}}`
 
-/** P3 后缀（声明派生）：枚举字段带取值域 / 非枚举必填串带「非空字符串」/ 数字字段仅「必填」。 */
-const requiredSuffix = (spec) => (spec.enum ? `；取值 ∈ ${enumText(spec.enum)}` : spec.type === "string" ? "；非空字符串" : "")
+/** P3 后缀（声明派生）：枚举字段带取值域 / 非枚举必填串带「非空字符串」/ 数字字段仅「必填」
+ *  （`domain` = 按形条件判据给出的取值域——`whenPresent.enum` 优先于基本形）。 */
+const requiredSuffix = (spec, domain) => (domain ? `；取值 ∈ ${enumText(domain)}` : spec.type === "string" ? "；非空字符串" : "")
+
+/** 值非空字段（P6 字段级：空串 / 全空白 ⇒ 拒——声明面不表达值级判据，与 `title` 同源一处）。 */
+const NON_EMPTY_FIELDS = ["title", "resume_when"]
 
 /**
- * 工具层参数守卫（设计档 §3.2 · Gitee #IKIQGK / 台账 #472）：判序 P1–P6，文案逐字 = §3.2 模板；
- * 消费工具自身 `parameters` 声明派生（`required` / `type` / `enum`——枚举 / 必填 / 类型不在守卫内复写）；
- * 只判不改（零缺省填充 / 零类型转换 / 零文本改写），返回入参对象（唯一归一 = 判序① 的缺省 / `null`
- * ⇒ `{}`）。非法 ⇒ throw——判于核函数之前（零写、零库动作）。
+ * 工具层参数守卫（设计档 §3.2 · Gitee #IKIQGK / 台账 #472）：判序 P1–P7，文案逐字 = §3.2 模板；
+ * 消费工具自身声明派生（`required` / `type` / `enum` / `oneOfRequired` / `whenPresent`——枚举 / 必填 /
+ * 类型 / 组判据不在守卫内复写）；只判不改（零缺省填充 / 零类型转换 / 零文本改写），返回入参对象
+ * （唯一归一 = 判序① 的缺省 / `null` ⇒ `{}`）。非法 ⇒ throw——判于核函数之前（零写、零库动作）。
+ * 按形条件判据（`whenPresent`）：`when` 字段在本笔入参**在场**（非 `null`）⇒ 该条生效（`required` 按
+ * P3 判、`enum` 按 P5 判并取代基本形取值域）；不在场 ⇒ 本条不生效、按基本形判。
  */
 function assertToolArgs(tool, args) {
   const name = tool.name
   const decl = tool.parameters ?? {}
   const props = decl.properties ?? {}
   const fields = Object.keys(props)
+  // 组判据两键居声明条目顶层（不入 `parameters`——自定义键不随声明交模型 / provider）
+  const conditional = tool.whenPresent ?? []
   // P1：入参缺省 / `null` ⇒ 视作 `{}`；非对象（数组 / 标量）⇒ 拒
   if (args == null) args = {}
   else if (typeof args !== "object" || Array.isArray(args)) throw new Error(`${name}：参数须为对象（收到 ${argPreview(args)}）`)
   // P2：未知键 ⇒ 拒（判序先于缺参——typo 键先给可用参数集）
   const unknown = Object.keys(args).filter((k) => !Object.hasOwn(props, k))
   if (unknown.length > 0) throw new Error(`${name}：未知参数：${unknown.join(" / ")}（可用参数 = ${fields.join(" / ")}）`)
-  // P3–P6：逐字段（声明序）——缺失（必填；显式 `null` 同判）→ 类型 / 枚举 → `title` 空串 / 全空白
+  // P3–P6：逐字段（声明序）——缺失（必填；显式 `null` 同判）→ 类型 / 枚举 → 值非空
   for (const field of fields) {
     const spec = props[field]
     const value = args[field]
-    const required = (decl.required ?? []).includes(field)
+    const rule = conditional.find((c) => c.field === field && args[c.when] != null)
+    const required = rule?.required ?? (decl.required ?? []).includes(field)
+    const domain = rule?.enum ?? spec.enum
     if (value === undefined || value === null) {
-      if (required) throw new Error(`${name}：${field} 缺失（必填${requiredSuffix(spec)}）`)
+      if (required) throw new Error(`${name}：${field} 缺失（必填${requiredSuffix(spec, domain)}）`)
       continue // 可空字段 `null` ⇒ 放行（≡ 略去——与 `patch.x ?? 行值` 既有语义同源）
     }
-    if (spec.enum) {
-      if (!spec.enum.includes(value)) throw new Error(`${name}：${field} 非法：${argPreview(value)}（取值 ∈ ${enumText(spec.enum)}）`)
+    if (domain) {
+      if (!domain.includes(value)) throw new Error(`${name}：${field} 非法：${argPreview(value)}（取值 ∈ ${enumText(domain)}）`)
     } else if (spec.type === "string" && typeof value !== "string") {
       throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为字符串）`)
     } else if (spec.type === "number" && typeof value !== "number") {
@@ -75,10 +85,16 @@ function assertToolArgs(tool, args) {
     } else if (spec.type === "boolean" && typeof value !== "boolean") {
       throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为布尔）`)
     }
-    if (field === "title" && typeof value === "string" && value.trim() === "") {
+    if (NON_EMPTY_FIELDS.includes(field) && typeof value === "string" && value.trim() === "") {
       throw new Error(`${name}：${field} 为空（${required ? "必填；" : ""}非空字符串）`)
     }
   }
+  // P7：组判据（声明派生 `oneOfRequired`）——组内恰携其一 ⇒ 过；同携 / 双缺 ⇒ 拒
+  for (const group of tool.oneOfRequired ?? []) {
+    if (group.filter((f) => args[f] != null).length === 1) continue
+    const received = Object.fromEntries(group.map((f) => [f, args[f] ?? null]))
+    throw new Error(`${name}：${group.join(" ∥ ")} 须恰携其一（收到 ${argPreview(received)}）`)
+  }
   return args
 }
 
@@ -91,68 +107,90 @@ const READ_ACTIONS = ["query", "count"]
 /** cwd 参数描述（五前身声明同文——文本单点）。 */
 const CWD_DESC = "本次动作的目标路径——项目根由它推导：沿祖先链最近的项目目录（带 PROJECT-MANIFEST.json 或已有台账库）；容器目录下收敛到子项目。台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话锚"
 
-/** 各 action 声明条目（= 前身旧工具 `parameters` 逐字；伪工具对象守卫 + 弃用壳共用单源）。 */
+/** 各 action 声明条目（= 前身旧工具 `parameters` 逐字；伪工具对象守卫 + 弃用壳共用单源）。
+ *  `parameters` 内的键 = 交模型 / provider 的那一份声明；**组判据两键（`oneOfRequired` / `whenPresent`）
+ *  居本条条目顶层、不入 `parameters`**——自定义键不随声明外泄（provider 面零风险），守卫仍只读声明。 */
 const ACTION_SPECS = {
   add: {
-    type: "object",
-    required: ["kind", "title"],
-    properties: {
-      cwd: { type: "string", description: CWD_DESC },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
-      title: { type: "string", description: "条目标题" },
-      board: { type: "string", description: "归属板块（需求档文档名，可空）" },
-      req_doc: { type: "string", description: "需求档指针（可空）" },
-      task_book: { type: "string", description: "任务书指针（可空；在途 / 待核销必填——咬合 CHECK）" },
-      evidence: { type: "string", description: "最小证据行（可空）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（可空）" },
+    parameters: {
+      type: "object",
+      required: ["kind", "title"],
+      properties: {
+        cwd: { type: "string", description: CWD_DESC },
+        kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
+        title: { type: "string", description: "条目标题" },
+        board: { type: "string", description: "归属板块（需求档文档名，可空）" },
+        req_doc: { type: "string", description: "需求档指针（可空）" },
+        task_book: { type: "string", description: "任务书指针（可空；在途 / 待核销必填——咬合 CHECK）" },
+        evidence: { type: "string", description: "最小证据行（可空）" },
+        trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（可空）" },
+        resume_when: { type: "string", description: "复启条件句（可空；`trigger=条件` 行的一句话条件 + 可选锚 `@YYYY-MM-DD` ∥ `@事件件名`）——值非空：空串 / 全空白 ⇒ 拒" },
+      },
+      additionalProperties: false,
     },
-    additionalProperties: false,
   },
   update: {
-    type: "object",
-    required: ["id"],
-    properties: {
-      cwd: { type: "string", description: CWD_DESC },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "目标状态（六态之一，缺省 = 不变）" },
-      title: { type: "string", description: "标题（缺省 = 不变）" },
-      board: { type: "string", description: "归属板块（缺省 = 不变）" },
-      req_doc: { type: "string", description: "需求档指针（缺省 = 不变）" },
-      task_book: { type: "string", description: "任务书指针（缺省 = 不变）" },
-      evidence: { type: "string", description: "证据（缺省 = 不变；传入 = 追加——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传）" },
-      evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
-      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进入待设计 / 在途自动写本会话；出在途 / 撤回清空）" },
+    parameters: {
+      type: "object",
+      properties: {
+        cwd: { type: "string", description: CWD_DESC },
+        id: { type: "number", description: "条目 id（与 batch 恰携其一）" },
+        batch: { type: "string", description: "批档指针（与 id 恰携其一）——批级批量：一次结算该批的行；携 status ⇒ 逐行按迁移表重判，不携 status ⇒ 纯字段补丁（status 零写）" },
+        status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "目标状态（六态之一，缺省 = 不变）" },
+        title: { type: "string", description: "标题（缺省 = 不变）" },
+        board: { type: "string", description: "归属板块（缺省 = 不变）" },
+        req_doc: { type: "string", description: "需求档指针（缺省 = 不变）" },
+        task_book: { type: "string", description: "任务书指针（缺省 = 不变）" },
+        evidence: { type: "string", description: "证据（缺省 = 不变；传入 = 追加——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传）" },
+        evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
+        trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
+        resume_when: { type: "string", description: "复启条件句（缺省 = 不变；值非空——空串 / 全空白 ⇒ 拒）" },
+        executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进入待设计 / 在途自动写本会话；出在途 / 撤回清空）" },
+      },
+      additionalProperties: false,
     },
-    additionalProperties: false,
+    oneOfRequired: [["id", "batch"]],
   },
   close: {
-    type: "object",
-    required: ["id", "status"],
-    properties: {
-      cwd: { type: "string", description: CWD_DESC },
-      id: { type: "number", description: "条目 id" },
-      status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 追认核销 / 撤回）" },
-      evidence: { type: "string", description: "最小证据行（可选；传入 = 追加缺省——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传。追认核销面判结果值须非空：缺 / 全空白 ⇒ 拒）" },
-      evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
+    parameters: {
+      type: "object",
+      required: ["status"],
+      properties: {
+        cwd: { type: "string", description: CWD_DESC },
+        id: { type: "number", description: "条目 id（与 batch 恰携其一）" },
+        batch: { type: "string", description: "批档指针（与 id 恰携其一）——批级批量结算：只销已到 待核销 的行；待讨论 / 待设计 点名跳过（追认核销不入批量面）" },
+        status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 追认核销 / 撤回）——携 batch 时可不给（缺省 = 勾销单值），给了只能是 已核销" },
+        evidence: { type: "string", description: "最小证据行（可选；传入 = 追加缺省——旧值非空 ⇒ 拼 `旧｜新`（「｜」零空格）、旧空直写；新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传。追认核销面判结果值须非空：缺 / 全空白 ⇒ 拒）" },
+        evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换（旧文零保留）；缺省 / false = 追加；旗独传（无新文）⇒ 拒" },
+      },
+      additionalProperties: false,
     },
-    additionalProperties: false,
+    oneOfRequired: [["id", "batch"]],
+    whenPresent: [{ when: "batch", field: "status", required: false, enum: ["已核销"] }],
   },
   query: {
-    type: "object",
-    properties: {
-      cwd: { type: "string", description: CWD_DESC },
-      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
-      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
-      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "按技术待办触发过滤（三枚举，缺省 = 不过滤——无触发（NULL）不过滤）" },
+    parameters: {
+      type: "object",
+      properties: {
+        cwd: { type: "string", description: CWD_DESC },
+        status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
+        kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
+        board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
+        trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "按技术待办触发过滤（三枚举，缺省 = 不过滤——无触发（NULL）不过滤）" },
+        task_book: { type: "string", description: "按任务书指针过滤（原值等值——批→行反查；缺省 = 不过滤）" },
+      },
+      additionalProperties: false,
     },
-    additionalProperties: false,
   },
   count: {
-    type: "object",
-    properties: { cwd: { type: "string", description: CWD_DESC } },
-    additionalProperties: false,
+    parameters: {
+      type: "object",
+      properties: {
+        cwd: { type: "string", description: CWD_DESC },
+        task_book: { type: "string", description: "按任务书指针过滤（原值等值）" },
+      },
+      additionalProperties: false,
+    },
   },
 }
 
@@ -171,8 +209,10 @@ const UNION_PARAMETERS = {
     evidence: { type: "string", description: "最小证据行（add 可空；update / close 传入 = 追加缺省——旧空直写、旧非空拼 `旧｜新`（「｜」零空格）、新值全空白 ⇒ 拒；覆盖 = 与 `evidenceReplace: true` 同传；update 缺省 = 不变 / close 缺省 = 判行值；追认核销须非空）" },
     evidenceReplace: { type: "boolean", description: "覆盖旗（布尔）：与 evidence 同传 = 整段替换；缺省 / false = 追加；旗独传（无新文）⇒ 拒（update / close）" },
     trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（add / update 可空 / query 过滤）" },
-    id: { type: "number", description: "条目 id（update / close 必填）" },
-    status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "状态（close 必填 ∈ {已核销, 已废弃}；update 迁移 / query 过滤——六态之一）" },
+    resume_when: { type: "string", description: "复启条件句（add / update 可空；值非空——空串 / 全空白 ⇒ 拒；`trigger=条件` 行的一句话条件 + 可选锚 `@YYYY-MM-DD` ∥ `@事件件名`）" },
+    id: { type: "number", description: "条目 id（update / close：与 batch 恰携其一）" },
+    batch: { type: "string", description: "批档指针（update / close：与 id 恰携其一）——批级批量：一次结算该批的行（update 携 status ⇒ 逐行迁移表重判；不携 status ⇒ 纯字段补丁；close 只销 待核销 行、status 可空）" },
+    status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "状态（单行 close 必填 ∈ {已核销, 已废弃}；close 携 batch 时可空、给了只能是 已核销；update 迁移 / query 过滤——六态之一）" },
     executor: { type: "string", description: "执行者 sessionId（update 可选——接手改写归属；缺省 = 按状态迁移语义：进入待设计 / 在途自动写本会话；出在途 / 撤回清空）" },
   },
   additionalProperties: false,
@@ -210,8 +250,10 @@ function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
       // ② 入口级 action 判（P3 缺失 / P5 非法——消费 action；取值域 = 本装配面枚举）
       const { action, ...rest0 } = args
       assertToolArgs(entryTool, { action })
-      // ③ 余键喂该 action 伪工具对象（声明源 = 前身工具 parameters 逐字——`action` 键不入 P2 域）
-      const rest = assertToolArgs({ name: `ledger(${action})`, parameters: ACTION_SPECS[action] }, rest0)
+      // ③ 余键喂该 action 伪工具对象（声明源 = 前身工具 parameters 逐字——`action` 键不入 P2 域；
+      //   组判据两键在条目顶层，与 `parameters` 同送守卫）
+      const spec = ACTION_SPECS[action]
+      const rest = assertToolArgs({ name: `ledger(${action})`, ...spec }, rest0)
       // ④ 路由既有核函数（包装细节携自原工具 execute 逐字保留：cwd 缺省 / JSON 缩进 / getSessionId 动态 import）
       switch (action) {
         case "add": {
@@ -221,7 +263,7 @@ function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
           return JSON.stringify({ id, status: "待讨论", ...reportedRoot(target) })
         }
         case "update": {
-          const { cwd, id, ...patch } = rest
+          const { cwd, id, batch, ...patch } = rest
           const target = cwd ?? cwdOf(ctx)
           let executorSessionId
           if (patch.executor == null) {
@@ -229,17 +271,21 @@ function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
             const { getSessionId } = await import("./session-slots.mjs")
             executorSessionId = getSessionId()
           }
+          // 批级批量（§3.3）——`batch` 与 `id` 恰携其一（守卫 P7 已先裁）
+          if (batch != null) return JSON.stringify({ ...ledgerUpdateBatch({ cwd: target, batch, patch, executorSessionId }), ...reportedRoot(target) })
           return JSON.stringify({ ...ledgerUpdate({ cwd: target, id, patch, executorSessionId }), ...reportedRoot(target) })
         }
         case "close": {
           const target = rest.cwd ?? cwdOf(ctx)
+          // 批级批量结算（§3.3——勾销径）
+          if (rest.batch != null) return JSON.stringify({ ...ledgerCloseBatch({ cwd: target, batch: rest.batch, evidence: rest.evidence, evidenceReplace: rest.evidenceReplace }), ...reportedRoot(target) })
           return JSON.stringify({ ...ledgerClose({ cwd: target, id: rest.id, status: rest.status, evidence: rest.evidence, evidenceReplace: rest.evidenceReplace }), ...reportedRoot(target) })
         }
         case "query":
-          return JSON.stringify(ledgerQuery({ cwd: rest.cwd ?? cwdOf(ctx), status: rest.status, kind: rest.kind, board: rest.board, trigger: rest.trigger }), null, 2)
+          return JSON.stringify(ledgerQuery({ cwd: rest.cwd ?? cwdOf(ctx), status: rest.status, kind: rest.kind, board: rest.board, trigger: rest.trigger, task_book: rest.task_book }), null, 2)
         case "count": {
           const target = rest.cwd ?? cwdOf(ctx)
-          return JSON.stringify({ count: ledgerCount({ cwd: target }), ...reportedRoot(target) })
+          return JSON.stringify({ ...ledgerCount({ cwd: target, task_book: rest.task_book }), ...reportedRoot(target) })
         }
         default:
           // 不可达（② 枚举守门已先拒）——fail-loud 兜底（防未来变体增量 drift）
@@ -262,7 +308,7 @@ const deprecatedLine = (old, action) => `${old} 已退役（本名不再装配
 const deprecatedShell = (old, action, readonly) => ({
   name: old,
   description: deprecatedLine(old, action),
-  parameters: ACTION_SPECS[action],
+  parameters: ACTION_SPECS[action].parameters,
   readonly,
   async execute() { throw new Error(deprecatedLine(old, action)) },
 })

package/ledger.mjs

@@ -65,9 +65,11 @@ export function discoverFamily(anchor) {
 }
 
 /** scan 组装（SQLite 行集 + 计数单源 → scan 对象）——形状契约（设计档 §2.2）：pool/tech/aged/
- *  agedKeys/agedTitles/thresholdReached/boards/actionable/root/name/ledger。行龄 = 时间戳
+ *  agedKeys/agedTitles/overdue/thresholdReached/boards/actionable/root/name/ledger。行龄 = 时间戳
  *  （updated_at ?? created_at 距今 > days；未知不计——零假阳降级，同 v1 行龄未知口径）。
  *  `now`/`days` = 注入面（确定性用例——替代 v1 ageOf git 注入面）。
+ *  **`days` 只作用于展示面 `aged`**（本函数局部阈值）；`overdue`（出口态）恒按核常量 `AGING_DAYS`
+ *  （`overdueOf` 单源）——故 `days` 调小时 `aged` 会先于 `overdue` 涨（两数口径不同，非矛盾）。
  *  **根推导**（设计档 §3.8）：`root` / `name` / `ledger` = `resolveLedgerRoot(anchor)` 推导所得项目根（非锚
  *  ——容器 ∥ 工作区锚取收敛序之根）——与行集读取同一单源；无根 ⇒ `ledger` = `null`（不落兜底根——
  *  该态下 `root` / `name` 回落锚、行集为空，且该 scan 不进族枚举（`discoverFamily` 容器支只列已注册子目录））。
@@ -77,7 +79,7 @@ export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
   const anchor = resolve(cwd)
   const derived = resolveLedgerRoot(anchor)
   const root = derived ? derived.root : anchor
-  const rows = ledgerQuery({ cwd: anchor })
+  const rows = ledgerQuery({ cwd: anchor, now }) // `now` 透传（两读数同时钟——`overdue` 的行键由核同一 `now` 算）
   const pending = rows.filter((r) => PENDING_STATUSES.includes(r.status))
   const poolEntries = pending.filter((r) => r.kind === "requirement")
   const techEntries = pending.filter((r) => r.kind === "tech_todo")
@@ -98,6 +100,7 @@ export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
   return {
     name: basename(root), root, ledger: derived ? ledgerDbPath(root) : null,
     pool: poolEntries.length, tech: techEntries.length, aged: aged.length,
+    overdue: pending.filter((r) => r.overdue != null).length, // 待处置（§3.7——机判单源 = 行集 `overdue` 键，行值与 `now` 均同源）
     agedKeys: aged.map((r) => normalizeEntry(r.title)), agedTitles: aged.map((r) => entryTitle(r.title)),
     thresholdReached, boards, actionable: aged.length > 0 || thresholdReached,
     inflightExecutors,
@@ -113,8 +116,8 @@ export function formatMarker(scan) {
  *  `root` = `family.current.root` 的 scan（命中但不在 `scans`——不可读 ⇒ 空范围，不掺兄弟）；
  *  `current` 缺席（容器根锚）⇒ 范围 = `scans` 全体（族内已读项目——构建期不可读已跳过）。
  *  空范围 ⇒ `{ marker: null, warn: false }`（不落 `0·0`）；范围非空 ⇒ `marker` = `formatMarker`
- *  逐字（两池分列求和——F1）；`warn` = 范围内任一项 `aged>0 ∨ deadExecutors>0`（端零重算）。
- *  消费面 = 核拍面（`ledger-surface.mjs`）∥ VSC item——端零自算单源。 */
+ *  逐字（两池分列求和——F1）；`warn` = 范围内任一项 `overdue>0 ∨ deadExecutors>0`（§3.7——`aged ⊂
+ *  overdue` ⇒ 警示色不缩；端零重算）。消费面 = 核拍面（`ledger-surface.mjs`）∥ VSC item。 */
 export function scopeMarkerOf(scans, family) {
   const list = Array.isArray(scans) ? scans : []
   const currentRoot = family?.current?.root ?? null
@@ -126,15 +129,15 @@ export function scopeMarkerOf(scans, family) {
   for (const s of range) {
     pool += s.pool
     tech += s.tech
-    if (s.aged > 0 || s.deadExecutors > 0) warn = true
+    if (s.overdue > 0 || s.deadExecutors > 0) warn = true
   }
   return { marker: formatMarker({ pool, tech }), warn }
 }
 
-/** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`；判活尾段 = executorTail 三态——
- *  在途 executor 缺席时尾段空串，既有逐字断言零破）。 */
+/** L2 明细行（逐字——`（老化 <n> · 待处置 <m>）` 两数恒显（含 0——§3.7 出口面恒显位扩）；
+ *  阈值达成加 ` — 可开批`；判活尾段 = executorTail 三态——在途 executor 缺席时尾段空串）。 */
 export function formatDetailLine(scan) {
-  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}${executorTail(scan)}`
+  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged} · 待处置 ${scan.overdue}）${scan.thresholdReached ? " — 可开批" : ""}${executorTail(scan)}`
 }
 
 /** 明细行集 = {current} ∪ {可动作项目}（发现序——current 在前，其余按目录名升序；同项去重）。 */
@@ -148,8 +151,8 @@ export function detailScans(scans, current) {
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3；`AGING_DAYS` 常量单源 = `ledger-db.mjs`
 //    ——2026-10-07 批 ledger-tool 自本档迁入，公共面零变；`ledgerChildren` / `MAX_SIBLING_SCAN` / `resolveLedgerRoot`
 //    ——2026-10-16 批 ledger-root-derivation 随迁 / 新增，公共面形零改） ──
-export { AGING_DAYS, ALLOWED_MIGRATIONS, MAX_SIBLING_SCAN, ledgerChildren, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, resolveLedgerRoot, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
-export { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
+export { AGING_DAYS, ALLOWED_MIGRATIONS, EVIDENCE_SOFT_LIMIT, MAX_SIBLING_SCAN, ledgerChildren, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, resolveLedgerRoot, _setLedgerDirForTest, _resetLedgerDirForTest, ensureColumn, ensureExecutorColumn } from "./ledger-db.mjs"
+export { ledgerAdd, ledgerBatchRows, ledgerClose, ledgerCloseBatch, ledgerCount, ledgerEvidenceOversize, ledgerQuery, ledgerReanchorBatch, ledgerUpdate, ledgerUpdateBatch, overdueOf } from "./ledger-cmd.mjs"
 export { ledgerTool, ledgerReadTool, ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
 export { runLedgerAudit, runLedgerMigrate } from "./ledger-migrate.mjs"
 export { resolveExecutorStates, executorTail, _setExecutorProbeTtlForTest } from "./ledger-executors.mjs"

package/log.mjs

@@ -18,8 +18,8 @@
  *      → 整个字段丢弃；
  *   ② 内容只扫密钥形态（sk-xxx / Bearer xxx / key=… / token 值形等）→ 截断到形态之前
  *      ——宁可丢信息不漏密钥。
- *      token 值形（`uuid:epoch`——2026-10-14 design-token-recovery 批并入）：design-slots
- *      reveal 结果经 `tool:done` head 落盘时不落值（与 batch.mjs 凭据第三形同判据）。
+ *      token 值形（`uuid:epoch`——2026-10-14 批并入）：工具结果经 `tool:done` head 落盘
+ *      时在形态前截断、不落值（与 batch.mjs 凭据第三形同判据）。
  *   工具事件不记 args；URL 不入事件（llm/tool 事件从不携带 URL；err 文本经形态扫描）。
  * - 摘要截断（B 方案，2026-09-03 用户裁定）：截断处带 "…" 标记（截后仍 ≤上限）。
  * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实

package/manifest-schema.mjs

@@ -25,6 +25,20 @@ export function isValidDocRootValue(value) {
   return value.every((p) => typeof p === "string" && p.trim() !== "")
 }
 
+/** `checkConfig.anchors.roots` **单元素值形判据**（判据单源——解析根 = 相对项目根的目录）：
+ *  合法 ⇒ `null`；非法 ⇒ 理由句（非空字符串 ∥ 相对路径 ∥ 无 `..` 越界段）。
+ *  消费面两处：产品引擎 `doc-check/anchors.mjs`（报告态逐元素弃用）∥ `doc-check/index.mjs`
+ *  （gate 面 `configError` 拒，fail-closed）。
+ * @param {unknown} value 解析根元素
+ * @returns {string|null}
+ */
+export function anchorRootError(value) {
+  if (typeof value !== "string" || value.trim() === "") return "元素须为非空字符串"
+  if (/^(?:[A-Za-z]:[\\/]|[\\/])/.test(value)) return "元素须为相对项目根的路径（不得为绝对路径）"
+  if (value.split(/[\\/]/).includes("..")) return "元素不得含 `..` 越界段"
+  return null
+}
+
 /** 默认八键（架构 §2.3 E1 五键 + 三族声明键——KD-M1-31）——整档初始化的写源与缺键 fallback 的补源。 */
 export const DEFAULT_MANIFEST = Object.freeze({
   version: 1,
@@ -41,7 +55,7 @@ export const DEFAULT_MANIFEST = Object.freeze({
     scanDirs: Object.freeze(["docs"]),
     lineWidth: 300,
     widthExemptZones: Object.freeze([]),
-    anchors: Object.freeze({ domain: "docs", exclude: Object.freeze(["_archive", "batches"]) }),
+    anchors: Object.freeze({ domain: "docs", exclude: Object.freeze(["_archive", "batches"]), roots: Object.freeze([]) }),
     exemptions: Object.freeze([]),
   }),
   // 项目声明三族（2026-09-27 声明载体唯一化批并入——键名 / 形态逐字承前；来源档已退役）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thincoder/core",
-  "version": "0.10.8",
+  "version": "0.10.9",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",

package/permission.mjs

@@ -14,6 +14,7 @@
  */
 import { createInterface } from "node:readline"
 import { lastPageUrl } from "./browser/session.mjs"
+import { composeTaskBookBrief } from "./agent-tools/spawn-gates.mjs"
 
 /** CLI tool arg summary (truncated long JSON) */
 export function summarize(toolArgs) {
@@ -34,7 +35,7 @@ export function formatPermission(name, args) {
     return `${args.path}\n${oldLines}\n  ↓\n${newLines}`
   }
   if (base === "delete") return `${args.path}${args.force ? "（force：跟踪文件也删）" : ""}`
-  if (base === "subagent") return cap(args.task ?? "", 500)
+  if (base === "subagent") return cap(composeTaskBookBrief(args, args.role) || args.task || "", 500)
   if (base === "memory") {
     // §6 action-routed preview: put shows content, batch delete/clear show the gate args
     const action = String(args.action ?? "")
@@ -86,6 +87,11 @@ export function formatPermission(name, args) {
     }
     if (action === "send") return `${sid} — 将发送：\n${cap(String(args.data ?? ""), 500)}`
     if (action === "secret_input") return `${sid} — 将发送：••••••（携密——值不回显）${args.label ? `（${args.label}）` : ""}`
+    if (action === "forget") {
+      // ⑫ 删除面：明示目标主机（无值——保存件不含可展示的凭据值）
+      const target = args.host ? `${args.host}${args.port ? `:${args.port}` : ""}` : "(missing host)"
+      return cap(`${target} — 删除已保存的 ssh 凭据`, 300)
+    }
     if (action === "close") return `${sid} — 关闭会话`
     return cap(`${action} ${sid}`, 300)
   }

package/prompts/advisor-design.md

@@ -3,10 +3,10 @@ You are an independent design reviewer for a design review inside an engineering
 
 ## Your role (identity — read before the criteria)
 You are an INDEPENDENT REVIEWER — authority in judgment, not in decisions.
-1. **Stance**: you judge the design/code on its own merits against the review criteria. You are not the author, not the implementer, not the editor — you FIND and REPORT; the parent agent (and the user) decides what changes. Do NOT write replacement text or patch code in your findings — the suggestion column stays advisory guidance (the parent agent decides what changes; you evidence and recommend, you do not rewrite).
-2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite file:line) — or explicitly marked `unverified`. NEVER assert "Known behavior…", "I'm confident…", or rely on remembered API semantics when the source is readable in scope — a behavioral question is an EVIDENCE question, not a reasoning question.
-3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope. Do NOT expand it. With no object declaration (legacy calls) your target = the review scope only. Findings that touch something outside this scope (parent-side docs, other modules) go in a trailing "out-of-scope note" — NO severity assigned to them.
-4. **Neutrality**: no git diff, no conversation-history archaeology — the state of the files/documents as you read them is the truth. Do not guess author intent.
+1. **Stance**: you judge the design/code on its own merits against the review criteria. You are not the author, not the implementer, not the editor — you FIND and REPORT; the parent agent (and the user) decides what changes. Writing replacement text or patch code in your findings would make you the author of what you judge, so the suggestion column stays advisory guidance — you evidence and recommend, and the rewrite belongs to the parent agent.
+2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite `file:line`) — or explicitly marked `unverified`. An assertion has two sources only: what you read (cite `file:line`) or an explicit `unverified` — "Known behavior…" and "I'm confident…" rest on memory, which has a cut-off and misremembers, so no one can check a remembered API answer; where the source is readable, a behavioral question is an EVIDENCE question, not a reasoning question.
+3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope; a finding outside that surface has nobody in this round to dispose of it and dilutes the object, so the target does not expand. With no object declaration (legacy calls) your target = the review scope only. Out-of-scope: not looked at; report it only when it **blocks the judgment** — that is the **task being blocked**, not a finding.
+4. **Neutrality**: the state of the files/documents as you read them is the truth — a git diff or conversation-history archaeology shows history rather than the current state, and guessed author intent adds a claim nobody can verify.
 The agent has written a design document and is asking you to review it before any code is written.
 
 ## Review Criteria
@@ -20,8 +20,8 @@ Evaluate the design against these dimensions:
 6. **Scope** — Is the scope appropriate? Are there opportunities to simplify? Is there scope creep?
 7. **Document ownership** — Does the change amend the document that already owns its topic (per the project's document map, when the review context provides one), or does it fragment by creating a new file for an existing section? Does the wording duplicate or contradict existing documents?
 8. **Affected-file size annotations** — Check the design's affected-files table: every source/test file it will modify must be annotated with its current line count and expected delta (`≤±N` or "structure unchanged"; pure `.md` documents are exempt). Any file crossing a code-structure tier must carry a split plan in the design (file tier: >500 lines → proactive split review, >800 lines → must split — hard cap, no exemption channel; the function tier is the first criterion — a file ≤500 lines containing a 300+ line single function is still non-compliant). Spot-check the annotated numbers. Tier authority: the code-structure criteria stated in this bullet.
-9. **Closest-precedent check** — check whether the design doc carries a **closest-precedent line**: precedent coordinates (implementation coordinates ∥ the matching design-doc section ∥ precedent batches) + alignment ∥ deviation rationale. **For an intended deviation the rationale must be explicit** (it names the surveyed precedent and states why the existing form does not apply — missing either = not explicit); **where no precedent exists, an explicit declaration** is required (never silently skip the line).
-10. **Survey-evidence check** — check whether the design doc carries a **survey-evidence line**: which public source docs were checked (independent doc repos above all) ∥ whether anything was relevant. **A missing line ⇒ not surveyed, or not recorded**; **a "none relevant" answer must be recorded too** (never silently skip the line) — the review chain had no such item; "not surveyed" needs a place to surface.
+9. **Closest-precedent check** — check whether the design doc carries a **closest-precedent line**: precedent coordinates (implementation coordinates ∥ the matching design-doc section ∥ precedent batches) + alignment ∥ deviation rationale. **For an intended deviation the rationale must be explicit** (it names the surveyed precedent and states why the existing form does not apply — missing either = not explicit); **where no precedent exists, an explicit declaration** is required: a line left out is indistinguishable from a survey that did not happen.
+10. **Survey-evidence check** — check whether the design doc carries a **survey-evidence line**: which public source docs were checked (independent doc repos above all) ∥ whether anything was relevant. **A missing line ⇒ not surveyed, or not recorded**; **a "none relevant" answer must be recorded too**: its absence reads as "not surveyed", and "not surveyed" needs a place to surface — the review chain had no such item.
 
 ## Output Format
 Produce a table with your findings:
@@ -31,7 +31,7 @@ Produce a table with your findings:
 | 2 | Clarity | 🟡 | ... | ... |
 
 Severity levels:
-- **`Suggestion` 列只写改法、不写执行人**（the Suggestion column carries the fix, never the executor）：禁「由主 agent / 父侧收正」式归属句（下游读到即判「不归我干」⇒ **整张发现表绕开**）；处置归属由父侧派单时定。**判据句**：`Suggestion` 列出现归属句 ⇒ 判违规。
+- **The `Suggestion` column carries the fix, not the executor** — an attribution sentence reads as "not mine" and the whole findings table gets bypassed: forbid attribution-shaped phrasing ("to be corrected by the main agent / parent side"), since downstream reads it as "not my job" ⇒ **the entire findings table is skipped**; who disposes of an item is decided when the parent dispatches. **Judgment line**: an attribution sentence in the `Suggestion` column ⇒ violation.
 - 🔴 Critical — design is incomplete or infeasible; must be addressed before implementation. Any 🔴 blocks approval.
 - 🟡 Advisory — design could be improved; NOT a blocker for approval
 - 🔵 Note — optional observation; NOT a blocker
@@ -41,36 +41,36 @@ Document ownership severity:
 - Creating a new file for an existing section, or duplicating a description that already exists elsewhere → 🟡
 
 ## Citation Discipline
-When you cite design-document text, use the exact `file:line` format (e.g. `path/to/file.ext:42`) — host-side verification will check the citation against the current disk state. If you have not read/verified the cited content, mark it `unverified` instead of presenting it as fact. Never abbreviate a quote with an ellipsis ("…" or "...") — a citation must be one CONTIGUOUS substring of the cited line; an abbreviated quote is reported as a non-contiguous citation (quote one contiguous excerpt instead).
+When you cite design-document text, use the exact `file:line` format (e.g. `path/to/file.ext:42`) — host-side verification checks the citation against the current disk state, so a citation you did not read/verify is marked `unverified` rather than presented as fact. An abbreviated quote with an ellipsis ("…" or "...") can no longer be checked against the line and is reported as a non-contiguous citation — a citation must be one CONTIGUOUS substring of the cited line (quote one contiguous excerpt instead).
 
 ## Approval Signal
 The user message contains an exact token and the exact designId in an `## Approval Signal` section. Close your findings with a single verdict line — `VERDICT: pass` or `VERDICT: changes-required` — as the line immediately before the token echo; the verdict is the closing decision, output nothing beyond the token echo below.
-- VERDICT: pass = no 🔴 (Critical) issue remains — 🟡 (Advisory) and 🔵 (Note) findings do NOT block pass: list them in your table and still pass.
-- VERDICT: changes-required = any 🔴 (Critical) issue — then do NOT include the token or the designId below; list the issues instead.
+- VERDICT: pass = no 🔴 (Critical) issue remains — 🟡 (Advisory) and 🔵 (Note) findings are listed in the table and still pass: they change nothing in the verdict, and a verdict mixing both values parses as neither.
+- VERDICT: changes-required = any 🔴 (Critical) issue — the token and the designId stay out of the reply and the issues are listed instead: an echoed token opens the write gate for a design that was not approved.
 - The verdict line itself is the approval statement — no separate prose around it, no post-verdict commentary.
 - After the VERDICT line, the ONLY allowed content is the token echo: if — and ONLY if — your verdict is pass, echo this exact token: [DESIGN-TOKEN:<token>] and this exact designId: <designId>. Copy BOTH values verbatim — every character, including the colon and the digits after the uuid inside the token brackets; a shortened echo is flagged as truncated. The designId must be the LAST thing you output.
 
 Important:
-- Review the design on its own merits — do NOT expect code to exist yet.
-- Read the design document fully. Judge against the Project Guide (when present in the review context) and the review criteria in this prompt — do not assume any particular project files.
-- Do NOT run git diff or look for code changes — there are none at this stage.
+- Review the design on its own merits — at this stage no code exists yet, so the design is the only object there is to review.
+- Read the design document fully. Judge against the Project Guide (when present in the review context) and the review criteria in this prompt — a project file you assume instead of reading becomes a criterion you invented.
+- A git diff at this stage returns no code changes and costs a turn — there is no implementation to inspect yet.
 
 ## Batch-record §3 landing (design review only — when the tool is mounted)
-Design review only (**applicable only when this review is a design review and the tool face has `batch` mounted** — code review has no such tool, this section does not apply): in addition to the report, use `batch({action:"append", segment:"§3", text})` to write this round's **findings table + VERDICT + counts verbatim** into batch record §3 (no path parameter; the tool stamps its own `### 轮次 N（评审子代理）` source marker — do not write your own heading).
-If the write does not land (refused / failed) → say「§3 未写入」plainly in the report — never skip it silently, and never pretend it was written (a parent-side ghost-write must be marked).
+Design-review only (**applicable only when this review is a design review and the tool face has `batch` mounted** — code review has no such tool, so this section does not apply): in addition to the report, use `batch({action:"append", segment:"§3", text})` to write this round's **findings table + VERDICT + counts verbatim** into batch record §3 — a review that leaves no §3 entry leaves the parent nothing to settle (no path parameter; the tool stamps its own `### 轮次 N（评审子代理）` source marker, so a heading you write yourself would be a second source).
+If the write does not land (refused / failed) → say "§3 not written" plainly in the report. A silent skip makes the parent settle against a record that is not there; claiming it was written records a write that never happened — and a parent-side ghost-write is marked as such.
 
-## Judgment Rules (apply directly — do not re-derive)
+## Judgment Rules (apply directly — these are the settled convention, and re-deriving them spends the round and drifts)
 Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply.
-R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)
+R1 Doc contradiction / state inconsistency → 🟡 (the parent doc layer reports and fixes it — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴, because two live descriptions leave the reader no way to tell which copy is authoritative — keep this convention, no downgrade)
 R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
-Doc-hygiene rule (added 2026-09-18, user ruling): revision-style expressions left on the **normative face** (`~~strikethrough~~` / "previously X ⇒ corrected Y" / corpse-marked "void / scrapped" in feature points / AC / judgment lines / discipline lines / boundaries / status statements) → 🟡 (Doc hygiene) — the invalidated expression must be **deleted** (history belongs to the record face: changelogs / history sections / batch records). Residue makes readers re-open dead items as live work orders (this actually happened).
-R3 Ruling (debt like file size) → 🟡/🔵, do not escalate, do not re-litigate
+Doc-hygiene rule (added 2026-09-18, user ruling): revision-style expressions left on the **normative face** of a **design doc / requirement doc** (`~~strikethrough~~` / "previously X ⇒ corrected Y" / corpse-marked "void / scrapped" in feature points / AC / judgment lines / discipline lines / boundaries / status statements) → 🟡 (Doc hygiene) — the invalidated expression must be **deleted** (history belongs to the record face: batch records and **git commits** — a changelog or history section inside a design / requirement doc is itself the violation). Residue makes readers re-open dead items as live work orders (this actually happened).
+R3 Ruling (debt like file size) → 🟡/🔵 — it was settled in round 1: escalating or re-litigating spends a round and changes nothing
 R4 Fragile test (wall-clock / serialization-shape dependency) → 🔵 + suggest determinism
 R5 Scope coordination (parent-side TODO) → 🟡 "coordination item" (not a defect)
-R6 Test seam — when testing needs to mock an internal tool set / slow tools and the set is hard-coded inside the loop (not injectable): do NOT try real slow tools / FIFO / large files (non-deterministic) / onTool observation (insufficient) / mock-LLM-returning-real-tools (too fast) — the only path is a test seam (module-level setter or parameter override + `??` default fallback; default null → production behavior unchanged; restore in finally) — the generic rule applies to both ends; concrete symbol names live in design notes only (never in the generic prompt)
+R6 Test seam — when testing needs to mock an internal tool set / slow tools and the set is hard-coded inside the loop (not injectable): a real slow tool / FIFO / large file is non-deterministic, an onTool observation is insufficient, and a mock LLM returning real tools is too fast — none of them yields a reading that proves anything about the seam, so the only path is a test seam (module-level setter or parameter override + `??` default fallback; default null → production behavior unchanged; restore in finally) — the generic rule applies to both ends; concrete symbol names live in design notes only, not in the generic prompt
 R7a Doc-state contradiction / cross-file lag → 🟡 report without editing (review is read-only; mechanism-level contradiction excluded — see R1 exception — = 🔴)
 R7b Content contradiction → higher layer wins: Design (D) > Requirements (F) > records (TODO)
 R7c Numeric drift / TODO unchecked / doc hygiene → 🔵
 R7d Semantic dangling → 🟡 report the design gap (parent fixes)
-R7e Never block "pass" due to doc-state contradiction — contradiction = 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — must be resolved before pass)
+R7e A doc-state contradiction is a 🟡 report-and-pass: blocking "pass" on it buys a full-chain stall and no fix (except mechanism-level description mismatch — = 🔴 — which must be resolved before pass)
 Source: 7-round sample — verified judgments — continuously re-reviewed. You have received the review-object declaration above — no need to infer the review target from the documents.