@thincoder/core 0.10.8 → 0.10.10

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

@@ -1,7 +1,7 @@
 /**
  * manifest-schema.mjs — **校验 ∕ 默认值族**出档（2026-09-29 structure-split-2 · 台账 #620）：自 `manifest.mjs`
  * 全量迁出——`isValidDocRootValue`（docRoot 子键值形态判据）·
- * `DEFAULT_MANIFEST`（默认八键）· `MANIFEST_SCHEMA`（判据单源）· 元素层谓词一件 · `validateManifest` ·
+ * `DEFAULT_MANIFEST`（默认五键）· `MANIFEST_SCHEMA`（判据单源）· 元素层谓词一件 · `validateManifest` ·
  * `fillDefaults`；**结构拆分零语义**（面不变 ∕ 判据不变，只换宿主档；切点 ∕ 缝单源 =
  * 批档 `docs/batches/2026-09-29-structure-split-2.md` §2.2-C）。
  *
@@ -25,7 +25,8 @@ export function isValidDocRootValue(value) {
   return value.every((p) => typeof p === "string" && p.trim() !== "")
 }
 
-/** 默认八键（架构 §2.3 E1 五键 + 三族声明键——KD-M1-31）——整档初始化的写源与缺键 fallback 的补源。 */
+/** 默认五键——整档初始化的写源与缺键 fallback 的补源；每一键描述的都是这个用户项目自身
+ *  （阶段 / 文档层 / 代码段 / 索引），产品内部布局与工具参数不住这里。 */
 export const DEFAULT_MANIFEST = Object.freeze({
   version: 1,
   phase: "initial-dev",
@@ -36,18 +37,9 @@ export const DEFAULT_MANIFEST = Object.freeze({
     modules: "docs/design/modules",
     batches: "docs/batches",
   }),
-  promptsLanding: "thincoder-core/prompts",
-  checkConfig: Object.freeze({
-    scanDirs: Object.freeze(["docs"]),
-    lineWidth: 300,
-    widthExemptZones: Object.freeze([]),
-    anchors: Object.freeze({ domain: "docs", exclude: Object.freeze(["_archive", "batches"]) }),
-    exemptions: Object.freeze([]),
-  }),
   // 项目声明三族（2026-09-27 声明载体唯一化批并入——键名 / 形态逐字承前；来源档已退役）。
   codePaths: Object.freeze(["src"]),
   index: Object.freeze({ codeExtensions: Object.freeze([]), docExtensions: Object.freeze([]), excludePaths: Object.freeze([]), publicRepos: Object.freeze([]) }),
-  advisor: Object.freeze({ docMap: "", standardsDoc: "" }),
 })
 
 /** 校验判据（模块设计 §2.2）——枚举 / 键存在（fallback 用）；判据单源（KD-M1-4）。 */
@@ -59,9 +51,7 @@ export const MANIFEST_SCHEMA = Object.freeze({
   keys: Object.freeze(Object.keys(DEFAULT_MANIFEST)),
   nestedKeys: Object.freeze({
     docRoot: Object.freeze(Object.keys(DEFAULT_MANIFEST.docRoot)),
-    checkConfig: Object.freeze(Object.keys(DEFAULT_MANIFEST.checkConfig)),
     index: Object.freeze(Object.keys(DEFAULT_MANIFEST.index)),
-    advisor: Object.freeze(Object.keys(DEFAULT_MANIFEST.advisor)),
   }),
 })
 
@@ -75,7 +65,7 @@ function isNonEmptyStringArray(v) {
  * 形状校验（模块设计 §2.2）——枚举 / version 数值恒做；**纯函数、零 fs**（原 `{ cwd }`
  * 指针分支已随字段整链裁撤——KD-M1-5 墓志）；不落盘。键存在性入 missingKeys（非拒）：
  * 缺键 = 便利 fallback（补默认值），不是错（与整档缺失两分——KD-M1-2）。
- * 未知键（#802 / KD-M1-36）：顶层 + 四嵌套层产 `unknownKeys`（非拒——ok 定性零变；产线恰 =
+ * 未知键（#802 / KD-M1-36）：顶层 + 两嵌套层产 `unknownKeys`（非拒——ok 定性零变；产线恰 =
  * fillDefaults 丢弃面；嵌套键用点形路径——同 missingKeys 口径）。
  * @param {object} obj 待校验 manifest 对象
  * @returns {{ok:boolean, errors:string[], missingKeys:string[], unknownKeys:string[]}}
@@ -86,7 +76,7 @@ export function validateManifest(obj) {
   if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
     return { ok: false, errors: ["manifest 顶层必须是 JSON 对象"], missingKeys, unknownKeys: [] }
   }
-  // #802（KD-M1-36——未知键可见化）：顶层 + 四嵌套层逐键对照（非拒——ok 定性零变；嵌套键点形）。
+  // #802（KD-M1-36——未知键可见化）：顶层 + 两嵌套层逐键对照（非拒——ok 定性零变；嵌套键点形）。
   const unknownKeys = []
   for (const key of Object.keys(obj)) if (!MANIFEST_SCHEMA.keys.includes(key)) unknownKeys.push(key)
   for (const [nested, subkeys] of Object.entries(MANIFEST_SCHEMA.nestedKeys)) {
@@ -115,7 +105,6 @@ export function validateManifest(obj) {
   // `index.excludePaths`（§6.14 面①）：**数组层** fail-closed（非数组 ⇒ 拒）；元素层宽容——空 ∕ 非串
   // 元素由归一剔除（L-①-1 夹具 `["./openclaw/","refs",""]` ⇒ `["openclaw","refs"]`）；`index.publicRepos`（§6.15）同款。
   const strArrErr = (key, v) => { if (!isNonEmptyStringArray(v)) errors.push(`${key} 值形态非法：${JSON.stringify(v)}（须为非空字符串数组——KD-M1-32）`) }
-  const strErr = (key, v) => { if (typeof v !== "string") errors.push(`${key} 值形态非法：${JSON.stringify(v)}（须为字符串——KD-M1-32）`) }
   const objErr = (key, v) => (v === null || typeof v !== "object" || Array.isArray(v)
     ? `${key} 值形态非法：${JSON.stringify(v)}（须为对象——KD-M1-32）` : null)
   if (obj.codePaths !== undefined) strArrErr("codePaths", obj.codePaths)
@@ -130,9 +119,6 @@ export function validateManifest(obj) {
       errors.push(`index.publicRepos 值形态非法：${JSON.stringify(obj.index.publicRepos)}（须为数组——非数组 fail-closed；空 ∕ 非串元素由归一剔除）`)
     }
   }
-  const advBad = obj.advisor === undefined ? null : objErr("advisor", obj.advisor)
-  if (advBad) errors.push(advBad)
-  else if (obj.advisor !== undefined) for (const k of ["docMap", "standardsDoc"]) if (obj.advisor[k] !== undefined) strErr(`advisor.${k}`, obj.advisor[k])
   if (obj.phase !== undefined && !MANIFEST_SCHEMA.enum.phase.includes(obj.phase)) {
     errors.push(`phase 取值非法："${obj.phase}"（允许：${MANIFEST_SCHEMA.enum.phase.join(" | ")}）`)
   }
@@ -142,7 +128,7 @@ export function validateManifest(obj) {
   return { ok: errors.length === 0, errors, missingKeys, unknownKeys }
 }
 
-/** 缺键补默认值（module 设计 §2.2 管线）：顶层缺键补默认、嵌套键（docRoot/checkConfig/index/advisor）
+/** 缺键补默认值（module 设计 §2.2 管线）：顶层缺键补默认、嵌套键（docRoot/index）
  *  子键补默认（与整键缺同语义）；不覆写既有值。深拷贝默认源（structuredClone）——冻结常量永不外泄引用。
  *  三族键的非对象值**原样透传**（不洗白——再校验拒，KD-M1-32）。 */
 export function fillDefaults(obj) {
@@ -153,7 +139,7 @@ export function fillDefaults(obj) {
     if (def !== null && typeof def === "object" && !Array.isArray(def)) {
       const src = obj[key]
       if (src === null || typeof src !== "object" || Array.isArray(src)) {
-        if (key === "index" || key === "advisor") out[key] = src // 形态错 → 透传（再校验拒）；docRoot/checkConfig 保持默认
+        if (key === "index") out[key] = src // 形态错 → 透传（再校验拒）；docRoot 保持默认
         continue
       }
       for (const sub of Object.keys(def)) {

package/manifest.mjs

@@ -11,8 +11,8 @@
  *    同档同键集去重、读到零未知键清该档 memo）——非拒定性零变。
  *  - validateManifest(obj) → { ok, errors, missingKeys, unknownKeys }：枚举 / version 数值 /
  *    docRoot 子键值形态（串 | 数组 | null（本面无——KD-M1-37），F7）——**纯函数、零 fs**；不落盘。
- *  - 三族声明键（`codePaths` / `index.{codeExtensions,docExtensions,publicRepos}` / `advisor.{docMap,standardsDoc}`——
- *    KD-M1-31 / M1-32）：缺键补默认；形态错 = 档非法（fail-closed，与 docRoot 子键同款）；
+ *  - 两族声明键（`codePaths` / `index.{codeExtensions,docExtensions,publicRepos}`——KD-M1-31 / M1-32）：
+ *    缺键补默认；形态错 = 档非法（fail-closed，与 docRoot 子键同款）；
  *    读向 = `declaration.mjs`（2026-10-01 自 `conventions.mjs` 迁出——经其转口可达）经 `readManifest` /
  *    `manifestFilePath` 投影（单向——KD-M1-33）；`index.publicRepos` 绝对根集 = `declaredPublicRoots`（§6.15）。
  *  - isValidDocRootValue(value) / docRootPaths(value, cwd)（F7 判据单源 KD-M1-8）：值形态谓词
@@ -35,7 +35,7 @@
  *    落盘）；仅 writer === 'main' 落盘（fail-closed 缺省拒）。
  *
  * N1 零依赖：仅 node:fs / node:path + 标准库 JSON.parse——无第三方解析器、无 node:sqlite。
- * N3 可迁移：本模块不硬编码任何本仓路径（docRoot / checkConfig 由被开发项目声明）。
+ * N3 可迁移：本模块不硬编码任何本仓路径（docRoot 由被开发项目声明；机检参数不在 manifest 面——住引擎内置常量）。
  */
 import { readFileSync, writeFileSync } from "node:fs"
 import { join, resolve } from "node:path"
@@ -277,7 +277,7 @@ export function writeManifest(cwd, manifest, { writer = "subagent" } = {}) {
 }
 
 /**
- * 初始化 = 写默认八键档（模块设计 §2.2）：只提供机制，不包交互问答（问答归壳面）。
+ * 初始化 = 写默认五键档（模块设计 §2.2）：只提供机制，不包交互问答（问答归壳面）。
  * 落盘走同一写门（内部 writeManifest(cwd, DEFAULT_MANIFEST, { writer })）——与 AC-M1-5
  * 同一闸，无第二条写路径（KD-M1-4 / 评审 #12）。
  * @returns {object} 写入的默认 manifest

package/memory/code-search.mjs

@@ -8,7 +8,8 @@
 import { embed, embedTolerant, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { scanVectors, createTopK } from "./scan.mjs"
 import { normalizeOrigin } from "./origin.mjs"
-import { declaredPublicRoots, loadProjectDeclaration, isExcludedRelPath, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs"
+import { declaredPublicRoots } from "../conventions.mjs"
+import { createReadGate } from "./read-gate.mjs" // 面⑥∪面⑦ 读面准入单源（#1372 抽件——两档原各持一份逐字相同的 rowHidden）
 import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
 import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/code_search.md
@@ -35,19 +36,9 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const origins = searchOrigins(memory)
   const ftsOriginFilter = origins.length === 1 ? `AND c.origin = ?` : origins.length > 1 ? `AND c.origin IN (${origins.map(() => "?").join(", ")})` : ""
   const originParams = origins
-  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前；两判据并列互不吞）：排除谓词（面①∪面⑥，
-  // 行 origin 为 `base`）∪ 声明范围门（面⑦——`isInDeclaredScope(path, declaredIndexScope(origin), origin)`，
-  // 逐 origin 预载一次）⇒「批次档 ∥ 范围外路径从未入索引」等价检索；存量行不删（收尾保护位）；窗口欠额接受。
-  const declCache = new Map()
-  const scopeCache = new Map()
-  const rowHidden = (origin, path) => {
-    const d = declCache.get(origin) ?? loadProjectDeclaration(origin)
-    declCache.set(origin, d)
-    if (isExcludedRelPath(path, d, origin)) return true
-    let scope = scopeCache.get(origin)
-    if (scope === undefined) { scope = declaredIndexScope(origin); scopeCache.set(origin, scope) }
-    return !isInDeclaredScope(path, scope, origin)
-  }
+  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前）——判据与逐 origin 预载单源 = `./read-gate.mjs`；
+  // 存量行不删（收尾保护位）；窗口欠额接受。
+  const { rowHidden } = createReadGate()
   const ftsNeedOrigin = origins.length !== 1 // 单 origin 形 SQL 零改；多 origin ∥ 无过滤形补 `origin` 列（行 origin 随行可得）
 
   const ftsList = ftsQuery ? memory.db.prepare(`

package/memory/docs.mjs

@@ -12,7 +12,8 @@ import { _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { markIndexedCommit, listProjectFiles, indexExtensions, declaredRootEntries } from "./code-sync.mjs"
 import { searchOrigins } from "./code-search.mjs"
 import { createRowBudget, rowCountOfPath, sweepStaleRows } from "./sync-tail.mjs"
-import { loadProjectDeclaration, isExcludedRelPath, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs" // 面① 谓词经 `decl` 传 `sweepStaleRows`；面⑥∪面⑦ 读面准入本档直调
+import { loadProjectDeclaration, declaredIndexScope } from "../conventions.mjs" // 面① 谓词经 `decl` 传 `sweepStaleRows`
+import { createReadGate } from "./read-gate.mjs" // 面⑥∪面⑦ 读面准入单源（#1372 抽件——两档原各持一份逐字相同的 rowHidden）
 import { logEvent } from "../log.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
 import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/*.md（DESC 单解析面，缺档抛错语义不变）
@@ -117,19 +118,9 @@ export async function docSearch(memory, query, { limit = 5, origins: originsOver
   const origins = originsOverride ?? searchOrigins(memory)
   const ftsOriginFilter = origins.length === 1 ? `AND d.origin = ?` : origins.length > 1 ? `AND d.origin IN (${origins.map(() => "?").join(", ")})` : ""
   const originParams = origins
-  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前；两判据并列互不吞）：排除谓词（面①∪面⑥，
-  // 行 origin 为 `base`）∪ 声明范围门（面⑦——`isInDeclaredScope(path, declaredIndexScope(origin), origin)`，
-  // 逐 origin 预载一次）⇒「批次档 ∥ 范围外路径从未入索引」等价检索；存量行不删（收尾保护位）；窗口欠额接受。
-  const declCache = new Map()
-  const scopeCache = new Map()
-  const rowHidden = (origin, path) => {
-    const d = declCache.get(origin) ?? loadProjectDeclaration(origin)
-    declCache.set(origin, d)
-    if (isExcludedRelPath(path, d, origin)) return true
-    let scope = scopeCache.get(origin)
-    if (scope === undefined) { scope = declaredIndexScope(origin); scopeCache.set(origin, scope) }
-    return !isInDeclaredScope(path, scope, origin)
-  }
+  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前）——判据与逐 origin 预载单源 = `./read-gate.mjs`；
+  // 存量行不删（收尾保护位）；窗口欠额接受。
+  const { rowHidden } = createReadGate()
   const ftsNeedOrigin = origins.length !== 1 // 单 origin 形 SQL 零改；多 origin ∥ 无过滤形补 `origin` 列（行 origin 随行可得）
 
   const ftsList = ftsQuery ? memory.db.prepare(`