@thincoder/core 0.10.8 → 0.10.10

package/doc-check/index.mjs

@@ -1,61 +1,172 @@
 /**
- * doc-check/index.mjs — 文档纪律机检 · 引擎入口（域扫描 + 声明面读取 + 报面行）。
+ * doc-check/index.mjs — 文档纪律机检 · 引擎入口（两条判据 + 报面行）。
  *
  * 判据两条（起步 · 闭集——口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S）：
  *   ① 锚（档缺 / 节缺）——实现 = `./anchors.mjs`；② 行宽——口径 = §3.18 条目 Q，实现 = `./width.mjs`。
- * 判据参数由**被开发项目**的 `PROJECT-MANIFEST.json` `checkConfig` 声明（不硬编码任何本仓路径）。
- * 纯函数：**零门禁 / 零退出码 / 零阻断**——报告态由工具面 `agent-tools/doc-check.mjs` 呈现；
- * 输出不得被读作拒执行的理由（用户令 > 机检）。
+ * 判据参数 = **工具内置常量** `DOC_CHECK_BUILTINS`：不读任何项目的声明面，因而没有「缺参数 ⇒ 拒跑」这一层，
+ *   也没有常量校验面——改判据 = 改代码、走评审。
+ * 判定范围 = **调用方传入的文件清单**（判定范围 = 解析范围 = 传入的那几档；无目录遍历、无全域兜底）：
+ *   不给清单 ⇒ 明确报错要求显式清单——判了本轮没碰过的档，别轮的存量问题会记到本轮头上。
+ * 两种问法（§3.20「工具形」——同一条判据）：
+ *   `report`（缺省）= 报告态——**零门禁 / 零退出码 / 零阻断**，输出不得被读作拒执行的理由（用户令 > 机检）；
+ *   清单里不可判档（不在盘 ∥ 非 .md）⇒ 报错点名、整次零判定；
+ *   `gate` = 交付时点的裁定——首行给机器可判 verdict；不可判档给跳过行（可见，不静默丢掉）。
+ *   强制面住交付协议 + 批次档 §6 前置，工具本体不阻断任何动作。
  */
+import { statSync } from "node:fs"
 import { relative, resolve } from "node:path"
-import { MANIFEST_REL, readManifest } from "../manifest.mjs"
-import { scanDomain, checkDocWidths } from "./width.mjs"
+import { checkDocWidths } from "./width.mjs"
 import { checkAnchors } from "./anchors.mjs"
 
+/** 判据参数（内置常量 · 冻结）：阈值 300 字符；两项空列表 = 区带类 / 豁免类默认值且恒空
+ *  ——豁免谓词（表行 / 围栏 / 可执行行 / 引文）住代码，没有「登记后放过」的写入口（空列表 ≠ 可登记豁免）。 */
+export const DOC_CHECK_BUILTINS = Object.freeze({
+  lineWidth: 300,
+  widthExemptZones: Object.freeze([]),
+  exemptions: Object.freeze([]),
+})
+
 /** 相对路径显示形（正斜杠——跨平台同形）。 */
 const rel = (root, p) => relative(root, p).replace(/\\/g, "/")
 
+/** 平台路径键（Windows 大小写不敏感——只用于清单去重，非判据面）。 */
+const pathKey = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+
+/** 不可判档的两因（闭集 · 判序 = 存在性 → 类型）：不在盘 ∥ 非 markdown 档（目录归后因）。 */
+function undecidableReason(abs) {
+  let st
+  try { st = statSync(abs) } catch { return "not on disk" }
+  if (!st.isFile() || !abs.toLowerCase().endsWith(".md")) return "not a markdown document"
+  return null
+}
+
+/** 清单 → 可判集（去重保序）+ 不可判档两类（`missing` ∥ `notMarkdown`）+ 非法条目下标（非字符串 / 空白）。 */
+function resolveRange(base, docs) {
+  const seen = new Set()
+  const check = []
+  const undecidable = []
+  const missing = []
+  const notMarkdown = []
+  const invalid = []
+  docs.forEach((d, i) => {
+    if (typeof d !== "string" || d.trim() === "") { invalid.push(i); return }
+    const abs = resolve(base, d)
+    const key = pathKey(abs)
+    const reason = undecidableReason(abs)
+    if (reason === null) { if (!seen.has(key)) { seen.add(key); check.push(abs) } return }
+    undecidable.push({ abs, reason })
+    if (reason === "not on disk") missing.push(abs)
+    else notMarkdown.push(abs)
+  })
+  return { check: check.sort(), undecidable, missing, notMarkdown, invalid }
+}
+
+/** gate 报面（固定句形——§3.20「报面（固定句形 · 交付门 gate）」）：首行 verdict = 唯一机判串。 */
+function gateReport({ base, docsSource, checkFiles, skipped, anchors, widths, lineWidth }) {
+  const total = anchors.hits.length + widths.length
+  const src = docsSource === "session" ? "本会话写过的文档" : "显式 docs"
+  const out = [
+    total ? `DOC-CHECK GATE: REFUSED（命中 ${total} 条）` : (checkFiles.length ? "DOC-CHECK GATE: PASS" : "DOC-CHECK GATE: PASS（0 档）"),
+    "文档纪律机检（交付门 · gate）",
+    checkFiles.length
+      ? `范围：${src} ${checkFiles.length} 档 · 阈值 ${lineWidth} 字符（工具内置常量）`
+      : `范围：${src} —— **0 档受检**（空清单：本次没有判任何档，不得读作「已检」）· 阈值 ${lineWidth} 字符（工具内置常量）`,
+    "判据：工具内置常量（锚 ∥ 行宽）——判定范围 = 解析范围 = 传入档",
+  ]
+  if (skipped.missing.length) out.push(`跳过 ${skipped.missing.length} 档（已不在盘，未检）：${skipped.missing.map((p) => rel(base, p)).join(" ∥ ")}`)
+  if (skipped.notMarkdown.length) out.push(`跳过 ${skipped.notMarkdown.length} 档（非 markdown 档，未检）：${skipped.notMarkdown.map((p) => rel(base, p)).join(" ∥ ")}`)
+  if (checkFiles.length === 0) {
+    // 空范围不静默当通过（K6）——照实说明 + 给出补充通道（两侧都不得读成「已检」）。
+    // 措辞按「有没有跳过行」分流：无跳过行时不得写「见上方跳过行」。
+    const hasSkips = skipped.missing.length > 0 || skipped.notMarkdown.length > 0
+    out.push(docsSource === "session"
+      ? (hasSkips
+        ? "范围为空：本会话触达的档均不可判（见上方跳过行）——若确认改过 ⇒ 显式传 docs"
+        : "范围为空：本会话没有写过 .md 档——若确认改过 ⇒ 显式传 docs")
+      : (hasSkips
+        ? "范围为空：显式 docs 里没有可判档——见上方跳过行"
+        : "范围为空：显式 docs 是空清单——列出要判的档后复跑"))
+  } else if (total === 0) {
+    out.push(`结论：0 条命中（${checkFiles.length} 档全清）`)
+  } else {
+    for (const h of anchors.hits) {
+      out.push(h.clazz === "档缺"
+        ? `✗ 锚·档缺 ${rel(base, h.file)}:${h.line} \`${h.token}\``
+        : `✗ 锚·节缺 ${rel(base, h.file)}:${h.line} \`${h.token}\`（目标 ${rel(base, h.target)} 无 §${h.section}）`)
+    }
+    for (const w of widths) out.push(`✗ 行宽 ${rel(base, w.file)}:${w.line}（${w.len} 字符）`)
+    out.push("处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）")
+  }
+  return out.join("\n")
+}
+
 /**
- * 跑一次文档纪律机检（报告态）。
- * @param {string} root 项目根（判据参数取该根的 `PROJECT-MANIFEST.json` `checkConfig`）
+ * 跑一次文档纪律机检。
+ * @param {string} root 项目根（解析序 ① 的基准）
+ * @param {{docs?:string[], mode?:'report'|'gate', docsSource?:'session'|'explicit'}} [o]
+ *   `mode` 缺省 = `report`；`docs` = 被判档清单（相对 `root` 或绝对）——**必填**（两种问法同）：
+ *   缺省 ∥ 非数组 ⇒ 报错要求显式清单（零遍历、零全域兜底）；`report` 面**空数组也报错**，`gate` 面空数组 ⇒
+ *   `PASS（0 档）` + 空范围说明（「本轮一档没碰」是真实读数）；`report` 面不可判档 ⇒ 报错、整次零判定；
+ *   `gate` 面不可判档 ⇒ 跳过行；`docsSource` = 范围来源标签（`session` = 本会话触达记账 ∥ `explicit` = 显式
+ *   `docs`）——缺省 = `explicit`；只影响报面措辞。
  * @returns {{report:string, hits:{total:number, anchors:number, width:number}, anchorHits:Array,
- *   widthHits:Array, anchorReports:Array, files:string[], scanDirs:string[], lineWidth:number,
- *   zones:string[], exclude:string[]}}
+ *   widthHits:Array, files:string[], checkFiles:string[], lineWidth:number,
+ *   skipped:{missing:string[], notMarkdown:string[]}}}
+ *   消费面判「清」须读 `report` 首行（gate）∥ `hits.total`（report），不得只看其中一个。
  */
-export function runDocCheck(root) {
+export function runDocCheck(root, { docs, mode = "report", docsSource } = {}) {
   const base = resolve(root)
-  const read = readManifest(base)
-  if (!read.ok) {
-    throw new Error(`doc_check: cannot read ${MANIFEST_REL} at ${base} — the check parameters come from that project's checkConfig (${read.reason ?? read.errors.join("；")})`)
+  const gate = mode === "gate"
+  if (docs !== undefined && !Array.isArray(docs)) {
+    throw new Error(`doc_check: \`docs\` must be an array of paths (got ${typeof docs}) — a bare string is refused rather than read as a whole-domain request; pass ["<path>"].`)
+  }
+  if (!Array.isArray(docs)) {
+    throw new Error('doc_check: `docs` is required — pass the explicit list of documents to judge. There is no default range: nothing is scanned unless you name it.')
+  }
+  // 报告态空清单 = 报错（「没跑」不得装成「跑了且清」）；gate 面空清单照实出 `PASS（0 档）` + 空范围说明
+  // ——交付面「本轮一档没碰」是一种真实读数，不是省略。
+  if (!gate && (docs.length === 0 || docs.every((d) => typeof d !== "string" || d.trim() === ""))) {
+    throw new Error('doc_check: docs is empty — an empty list names no document, so nothing can be judged; list the documents you mean.')
+  }
+  const source = docsSource ?? "explicit"
+  const range = resolveRange(base, docs)
+  // 清单条目本身非法（非字符串 / 空白）——调用方错误，两种问法同拒：静默丢掉一条就是不静默地收窄范围。
+  if (range.invalid.length) {
+    throw new Error(`doc_check: \`docs\` entries ${range.invalid.map((i) => `[${i}]`).join(", ")} are not paths — every entry must be a non-empty string; no document was judged.`)
   }
-  const cfg = read.manifest.checkConfig ?? {}
-  const scanDirs = (Array.isArray(cfg.scanDirs) ? cfg.scanDirs : []).filter((d) => typeof d === "string" && d !== "")
-  const exclude = Array.isArray(cfg.anchors?.exclude) ? cfg.anchors.exclude : []
-  const lineWidth = cfg.lineWidth
-  const zones = (Array.isArray(cfg.widthExemptZones) ? cfg.widthExemptZones : []).filter((z) => typeof z === "string" && z !== "")
+  // 报告态 fail-closed：清单里有一个不可判档 ⇒ 报错点名、整次零判定——清单写错却报 0 命中就是「没跑」装成「跑了且清」。
+  if (!gate && range.undecidable.length) {
+    const named = range.undecidable.map((u) => `${rel(base, u.abs)}（${u.reason}）`).join(" ∥ ")
+    throw new Error(`doc_check: docs names ${range.undecidable.length} document(s) that cannot be judged — no document was checked: ${named}. Fix the list and re-run; nothing is silently skipped and the check never widens beyond the list.`)
+  }
+  const checkFiles = range.check
+  const { lineWidth, widthExemptZones } = DOC_CHECK_BUILTINS
+  const anchors = checkAnchors(base, { files: checkFiles })
+  const widths = checkDocWidths({ lineWidth, exemptZones: widthExemptZones, files: checkFiles })
 
-  const files = scanDomain(base, { scanDirs, exclude })
-  const anchors = checkAnchors(base, { scanDirs, files })
-  const widths = checkDocWidths(base, { lineWidth, scanDirs, exclude, exemptZones: zones, files })
+  const hits = { total: anchors.hits.length + widths.length, anchors: anchors.hits.length, width: widths.length }
+  const shared = {
+    hits, anchorHits: anchors.hits, widthHits: widths, files: checkFiles, checkFiles, lineWidth,
+    skipped: { missing: range.missing, notMarkdown: range.notMarkdown },
+  }
+  if (gate) {
+    return { ...shared, report: gateReport({ base, docsSource: source, checkFiles, skipped: shared.skipped, anchors, widths, lineWidth }) }
+  }
 
-  const total = anchors.hits.length + widths.length
   const out = [
     "文档纪律机检（报告态 · 非门禁）",
-    `射程：${base} · ${scanDirs.join(" + ") || "（无）"}（${files.length} 档）· 阈值 ${lineWidth} 字符 · 区带豁免：${zones.length ? zones.join(" ∥ ") : "无"} · 排除：${exclude.length ? exclude.join(" ∥ ") : "（无）"}`,
-    "声明：判据参数依据 `PROJECT-MANIFEST.json` `checkConfig`",
-    `命中 ${total} 条（锚 ${anchors.hits.length} · 行宽 ${widths.length}）`,
+    `射程：${base} · 传入清单 ${checkFiles.length} 档 · 阈值 ${lineWidth} 字符（工具内置常量）· 区带豁免：${widthExemptZones.length ? widthExemptZones.join(" ∥ ") : "无"}`,
+    "声明：判据参数 = 工具内置常量；范围 = 传入文件（判定范围 = 解析范围）",
+    `范围：传入清单 ${checkFiles.length} 档（整档入判 · 判定范围 = 解析范围）`,
+    `命中 ${hits.total} 条（锚 ${anchors.hits.length} · 行宽 ${widths.length}）`,
   ]
-  // 报告面（不作判）：域内同名 ≥2 ⇒ 多义不判（残余登记——fail-open 方向，归评审核验面）
-  for (const r of anchors.reports) {
-    out.push(`报告 锚·多义 ${rel(base, r.file)}:${r.line} \`${r.token}\`（同名 ${r.candidates.length}：${r.candidates.map((c) => rel(base, c)).join(" ∥ ")}——报告面，不作判）`)
-  }
   for (const h of anchors.hits) {
     out.push(h.clazz === "档缺"
       ? `✗ 锚·档缺 ${rel(base, h.file)}:${h.line} \`${h.token}\``
       : `✗ 锚·节缺 ${rel(base, h.file)}:${h.line} \`${h.token}\`（目标 ${rel(base, h.target)} 无 §${h.section}）`)
   }
   for (const w of widths) out.push(`✗ 行宽 ${rel(base, w.file)}:${w.line}（${w.len} 字符）`)
-  out.push(total ? `结论：${total} 条命中——报告态，不作拒执行的理由` : "结论：0 条命中（锚 ∥ 行宽 均清）")
+  out.push(hits.total ? `结论：${hits.total} 条命中——报告态，不作拒执行的理由` : "结论：0 条命中（锚 ∥ 行宽 均清）")
 
-  return { report: out.join("\n"), hits: { total, anchors: anchors.hits.length, width: widths.length }, anchorHits: anchors.hits, widthHits: widths, anchorReports: anchors.reports, files, scanDirs, lineWidth, zones, exclude }
+  return { ...shared, report: out.join("\n") }
 }

package/doc-check/version.mjs

@@ -0,0 +1,84 @@
+/**
+ * doc-check/version.mjs — 引擎版本一致性的**单源**（纯函数 + 常量；两个消费面共用一个判据）。
+ *
+ * 权威规格 = `docs/core/design/DOC-DISCIPLINE.md` §3.20「引擎版本一致」（判据 / 比较 / 裁定 / 保守方向；
+ * 本档只实现，不重述口径）。消费面两处：工具面 `agent-tools/doc-check.mjs` 的 gate 分支（转口导出、
+ * 导出面不变）∥ 结构门 `agent-tools/batch-gate.mjs`（batch 两机械点）——两处不得各持一份清单。
+ *
+ * 问题形态：`thincoder-core/doc-check/**` 是 ESM，进程启动时加载即缓存；引擎档在启动后被改写 ⇒
+ * 本会话仍跑旧模块 ⇒ 假阳（旧误报消不掉）/ 假绿（引擎变严时旧版放过）。故 gate 在跑判据前先判版本。
+ *
+ * `ENGINE_FILES` 六档 = 判据面：三判据档 + 本档（版本函数单源，自身入清单 = fail-closed）+ 工具面 +
+ * 描述档。路径按本档 `import.meta.url` 解析到产品核根，**不随 target 变**。
+ */
+import { statSync } from "node:fs"
+import { resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** 产品核根（版本清单基线——本档住 `doc-check/`，上跳一级）。 */
+const CORE_ROOT = fileURLToPath(new URL("..", import.meta.url))
+
+/** 引擎六档 = 版本一致性的判据面（§3.20「引擎版本一致」· 判据）。 */
+export const ENGINE_FILES = [
+  "doc-check/index.mjs",
+  "doc-check/anchors.mjs",
+  "doc-check/width.mjs",
+  "doc-check/version.mjs",
+  "agent-tools/doc-check.mjs",
+  "tool-docs/doc_check.md",
+]
+
+/**
+ * 引擎版本一致性（纯函数——时钟 ∥ stat 可注 ⇒ 可测，不碰产品档 mtime）：
+ * 逐档 `mtimeMs` 与**本进程启动时刻**（`nowMs − uptimeSec × 1000`）比较——晚于启动 ⇒ 该档可能晚于模块加载 ⇒ stale。
+ * 不可 `stat` 的档同样入 stale（fail-closed，不静默忽略）。`mtime ≤ 启动` 一定不比缓存新；
+ * `mtime > 启动` 只是**可能**晚于加载 —— 取 fail-closed 方向（误判代价 = 一次会话重启）。
+ * @param {{nowMs?:number, uptimeSec?:number, stat?:Function}} [o] 注入缝（缺省 = 真时钟 / 真 `statSync`）
+ * @returns {{startMs:number, stale:{file:string, mtimeMs:number|null}[]}} `file` = 相对 `thincoder-core/` 的正斜杠路径
+ */
+export function staleEngineFiles({ nowMs = Date.now(), uptimeSec = process.uptime(), stat = statSync } = {}) {
+  const startMs = nowMs - uptimeSec * 1000
+  const stale = []
+  for (const file of ENGINE_FILES) {
+    let mtimeMs = null
+    try { mtimeMs = stat(resolve(CORE_ROOT, file)).mtimeMs } catch { stale.push({ file, mtimeMs: null }); continue }
+    if (typeof mtimeMs !== "number" || !Number.isFinite(mtimeMs)) { stale.push({ file, mtimeMs: null }); continue }
+    if (mtimeMs > startMs) stale.push({ file, mtimeMs })
+  }
+  return { startMs, stale }
+}
+
+/** stale 列表形（`<文件> mtime <ISO 8601>`，`；` 连列）——gate ERROR 行 ∥ report 注记行共用一处格式。 */
+function staleParts(stale) {
+  const when = (t) => new Date(t).toISOString()
+  return stale.map((s) => `${s.file} mtime ${s.mtimeMs === null ? "不可读（stat 失败）" : when(s.mtimeMs)}`)
+}
+
+/** 引擎版本 ERROR 报面（固定句形）：多档 stale ⇒ 逐档 `<文件> mtime <时间>` 以 `；` 连列——**不产 PASS**。 */
+export function gateEngineError({ startMs, stale }) {
+  const when = (t) => new Date(t).toISOString()
+  return [
+    `DOC-CHECK GATE: ERROR（引擎已更新（${staleParts(stale).join("；")} > 进程启动 ${when(startMs)}），请重启会话后复跑）`,
+    "原因：本会话进程加载的引擎模块早于盘上引擎档——旧引擎读数不可信（假阳：旧误报消不掉 ∥ 假绿：引擎变严时旧版放过）",
+    "处置：重启会话后复跑 gate（`report` 不裁定、不产 verdict（陈旧时只在首行前加注记））",
+  ].join("\n")
+}
+
+/** 报告态引擎陈旧注记（纯函数）：stale 空 ⇒ `null`；非空 ⇒ 一行注记（逐字单源 = `DOC-DISCIPLINE.md`
+ *  §3.20「gate 裁定 · report 注记」——多档以 `；` 连列，与 `gateEngineError` 同形）。 */
+export function reportEngineNote({ startMs, stale } = {}) {
+  if (!Array.isArray(stale) || stale.length === 0) return null
+  const when = (t) => new Date(t).toISOString()
+  return `[doc_check note] 引擎陈旧（${staleParts(stale).join("；")} > 进程启动 ${when(startMs)}）——本次读数由会话启动时加载的旧引擎产出，不可作为交付判据；重启会话后复跑。`
+}
+
+/** 报面 + 注记：有注记 ⇒ 注记行 + 原报面；无 ⇒ 原报面逐字返回（三不改：既有行 ∥ verdict ∥ PASS 语义）。 */
+export function withEngineNote(report, version) {
+  const note = reportEngineNote(version ?? {})
+  return note ? `${note}\n${report}` : report
+}
+
+/** 报面首行取形（唯一机判串 = 首行 `DOC-CHECK GATE:` 前缀——消费面共用一个取法，不各自 split）。 */
+export function firstVerdictLine(report) {
+  return String(report ?? "").split("\n")[0] ?? ""
+}

package/doc-check/width.mjs

@@ -1,60 +1,16 @@
 /**
- * doc-check/width.mjs — 文档纪律机检的产品档位（行宽谓词族 + 域扫描 + 行宽判据——实现单源）。
+ * doc-check/width.mjs — 文档纪律机检的产品档位（行宽谓词族 + 行宽判据——实现单源）。
  *
- * 口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.18 条目 Q（度量 / 域 / 豁免类 / 阈值）；
+ * 口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.18 条目 Q（度量 / 豁免类）；
  * 产品内建裁定 = 同档 §3.20 条目 S——谓词单源随迁：本仓 `scripts/doc-check-width.mjs` 改述为
  * **再出口缝**（薄档 · 零逻辑 · 逐名再出口），盘上不留第二份谓词实现。
- * 度量 = `[...line].length`（CJK 计 1——不引显示宽度 / 字体）；阈值 / 域 / 排除全部读
- * `PROJECT-MANIFEST.json` 的 `checkConfig`——零硬编码本仓路径，换项目开箱可用。
+ * 度量 = `[...line].length`（CJK 计 1——不引显示宽度 / 字体）；阈值 = 调用方的内置常量
+ * （`DOC_CHECK_BUILTINS.lineWidth`）——不读声明面，也不扫目录：**判定集 = 调用方传入的文件清单**。
  * 豁免五类 = 表格行 ∥ fenced 块 ∥ 可执行行 ∥ 连续引文 ∥ 区带：**只认结构谓词**，
  * 无行级白名单（按行号 / 注释声明的豁免不入判）。
  * 边界：本档零门禁 / 零退出码 / 零阻断——报告态由 `agent-tools/doc-check.mjs` 呈现。
  */
-import { readdirSync, readFileSync, statSync } from "node:fs"
-import { join, resolve } from "node:path"
-import { MANIFEST_REL } from "../manifest.mjs"
-
-/** 域发现跳过目录（不视作候选产品域；递归亦不进入）。 */
-const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".turbo", ".thincoder"])
-
-/** 域发现（声明面）：cwd 根（持 manifest）+ 各持自身 manifest 的一级子目录——判据 = manifest 在场，无路径硬编码。 */
-export function discoverDomains(root) {
-  const rootAbs = resolve(root)
-  const hasManifest = (p) => { try { return statSync(join(p, MANIFEST_REL)).isFile() } catch { return false } }
-  const out = []
-  if (hasManifest(rootAbs)) out.push(rootAbs)
-  let names = []
-  try { names = readdirSync(rootAbs) } catch { /* 不可读：仅根域 */ }
-  for (const n of names) {
-    if (SKIP_DIRS.has(n) || n.startsWith("dist-")) continue
-    const p = join(rootAbs, n)
-    try { if (statSync(p).isDirectory() && hasManifest(p)) out.push(p) } catch { /* 跳过 */ }
-  }
-  return out
-}
-
-/** 递归列 .md（跳过 SKIP_DIRS ∧ 声明面 exclude 段——exclude 逐层生效）。 */
-function walkMd(dir, exclude, out) {
-  let names = []
-  try { names = readdirSync(dir) } catch { return out }
-  for (const n of names) {
-    if (SKIP_DIRS.has(n) || n.startsWith("dist-") || exclude.includes(n)) continue
-    const p = join(dir, n)
-    let st
-    try { st = statSync(p) } catch { continue }
-    if (st.isDirectory()) walkMd(p, exclude, out)
-    else if (n.endsWith(".md")) out.push(p)
-  }
-  return out
-}
-
-/** 源域（单源）：`scanDirs` × `exclude` 声明面下的全部 .md——锚检查与行宽检查同一文件集。 */
-export function scanDomain(base, { scanDirs = [], exclude = [] } = {}) {
-  const ex = Array.isArray(exclude) ? exclude : []
-  const out = []
-  for (const d of Array.isArray(scanDirs) ? scanDirs : []) walkMd(resolve(base, d), ex, out)
-  return [...new Set(out)].sort()
-}
+import { readFileSync } from "node:fs"
 
 /** 表格行谓词（markdown 表格行结构性不可折行——行宽豁免，与锚检查同源）。 */
 export const isTableRow = (l) => /^\s*\|.*\|\s*$/.test(String(l))
@@ -94,15 +50,15 @@ export function inCodeSpan(line, idx) {
   return (String(line).slice(0, idx).match(/`/g) ?? []).length % 2 === 1
 }
 
-/** 行宽判据（单判据 = `checkConfig.lineWidth`）：`[...line].length` > 阈值 ∧ 非表格行 ∧ 非 fenced 块内
+/** 行宽判据（阈值 = 调用方内置常量 `lineWidth`）：`[...line].length` > 阈值 ∧ 非表格行 ∧ 非 fenced 块内
  *  ∧ 非可执行行 ∧ 非连续引文 ∧ 非区带内 ⇔ 命中（口径逐字 = §3.18 条目 Q）。
  *  单遍扫描携标题栈（`^(#{1,6})\s` 行入栈——同级 ∥ 更高级出栈）：行所属标题链任一为区带头 ⇒ 豁免。
- *  围栏未闭合 ⇒ 至档尾整块免（fail-open 方向——§3.18 残余登记 ①）；`exemptZones` 缺省 ∥ 空集 ⇒ 零豁免。 */
-export function checkDocWidths(base, { lineWidth, scanDirs, exclude, exemptZones = [], files } = {}) {
+ *  围栏未闭合 ⇒ 至档尾整块免（fail-open 方向——§3.18 残余登记 ①）；`exemptZones` 缺省 ∥ 空集 ⇒ 零豁免。
+ *  `files`（必填）= **判定集**（调用方传入的档清单——本档不遍历任何目录；空集 ⇒ 零命中）。 */
+export function checkDocWidths({ lineWidth, exemptZones = [], files = [] } = {}) {
   const zones = (Array.isArray(exemptZones) ? exemptZones : []).filter((z) => typeof z === "string" && z !== "")
   const hits = []
-  // `files` 给定时直接用（调用方已扫同一域 ⇒ 域只走一遍、文件集由值保证同一）；缺省自扫（既有调用面不变）。
-  for (const f of files ?? scanDomain(base, { scanDirs, exclude })) {
+  for (const f of files) {
     let text = ""
     try { text = readFileSync(f, "utf8") } catch { continue }
     const stack = [] // 标题栈 —— { level, exempt }；exempt = 自身 ∥ 祖先命中区带

package/i18n.mjs

@@ -60,6 +60,11 @@ export const CORE_MESSAGES = Object.freeze({
   "sub.cancelled": { en: "cancelled", zh: "已取消" },
   "sub.awaitingDigest": { en: "done · awaiting digestion", zh: "已完成 · 等待消化" },
   "sub.queueSlot": { en: "queued · position ${n} (slot full)", zh: "排队中 · 位置 ${n}（槽满等位）" },
+  // #1507 补四键（核字典缺键——值形与宿主同形：desktop `renderer/i18n.mjs:197-200` ∥ VSC `locales/{en,zh}.json`）
+  "sub.async": { en: "async", zh: "异步" },
+  "sub.sync": { en: "sync", zh: "同步" },
+  "sub.waiting": { en: "waiting", zh: "等待中" },
+  "sub.awaitingApproval": { en: "Awaiting approval: ${tool}", zh: "等待审批: ${tool}" },
   // ── 会诊状态词 ──
   "consult.answered": { en: "answered", zh: "已回复" },
   "consult.terminated": { en: "terminated", zh: "已终止" },
@@ -84,6 +89,8 @@ export const CORE_MESSAGES = Object.freeze({
   "ssh.field.user": { en: "Username", zh: "用户名" },
   "ssh.field.password": { en: "Password", zh: "密码" },
   "ssh.field.secret": { en: "Secret", zh: "密文" },
+  // 保存面（用户裁定 A+B · 台账 #1602 · §6.22 ⑪）：窗内勾选标签（三端 `ssh.field.<name>` 投影自动命中）
+  "ssh.field.save": { en: "Save credential (encrypted, this user account)", zh: "保存凭据（加密，本机用户账户）" },
   // 无 UI 失败句（E6；三端投影单源）：en 侧 = CLI 端 `SECRET_NO_UI_TEXT` 逐字（端常量收正为核键）。
   "ssh.no_ui": { en: "ssh credential input requires an interactive UI (none in this context) - use key-based auth or ssh-agent", zh: "ssh 凭据输入需要交互界面（当前场合没有）——请改用密钥认证或 ssh-agent" },
 })