@thincoder/core 0.10.9 → 0.10.11

package/declaration.mjs

@@ -1,5 +1,5 @@
 /**
- * declaration.mjs — 声明装载面（PROJECT-MANIFEST.json 三族 `codePaths` / `index.*` / `advisor.*`）
+ * declaration.mjs — 声明装载面（PROJECT-MANIFEST.json 两族 `codePaths` / `index.*`）
  * · 自 `conventions.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786。
  * 投影单源 = `manifest.mjs`（ONE reader / ONE root resolution——`readManifest` + `manifestFilePath`；
  * name / shape / defaults = schema 面 `docs/core/design/MANIFEST.md` §2.2）。迁出块逐字；
@@ -62,11 +62,7 @@ function normalizePathList(v) {
   return out
 }
 
-function normalizeString(v) {
-  return typeof v === "string" && v.trim() ? v.trim() : ""
-}
-
-/** Project the manifest three families into the frozen declaration object.
+/** Project the manifest two families into the frozen declaration object.
  *  `declared` = VALUE comparison against the defaults — at least one family deviates
  *  (a key written with its default value still counts as NOT declared; the design-gate
  *  hint reads it to decide whether to point at the manifest, PORTABILITY §3.1).
@@ -80,11 +76,9 @@ function buildDeclaration(m, root = null) {
   const excludePaths = normalizePathList(m?.index?.excludePaths)
   const publicRepos = normalizePathList(m?.index?.publicRepos)
   const batchRecords = batchSegments(m?.docRoot?.batches) // §6.14 面⑥ 声明值投影（`declared` 旗不涉——docRoot 族现状零改）
-  const docMap = normalizeString(m?.advisor?.docMap)
-  const standardsDoc = normalizeString(m?.advisor?.standardsDoc)
   const defaults = normalizeCodePaths(DEFAULT_MANIFEST.codePaths) ?? []
   const pathsDiffer = codePaths.length !== defaults.length || codePaths.some((p, i) => p !== defaults[i])
-  const declared = pathsDiffer || codeExtensions.length > 0 || docExtensions.length > 0 || excludePaths.length > 0 || publicRepos.length > 0 || Boolean(docMap) || Boolean(standardsDoc)
+  const declared = pathsDiffer || codeExtensions.length > 0 || docExtensions.length > 0 || excludePaths.length > 0 || publicRepos.length > 0
   return Object.freeze({
     declared,
     codePaths: Object.freeze(codePaths),
@@ -95,7 +89,6 @@ function buildDeclaration(m, root = null) {
       excludePaths: Object.freeze(excludePaths),
       publicRepos: Object.freeze(publicRepos),
     }),
-    advisor: Object.freeze({ docMap, standardsDoc }),
     root,
   })
 }
@@ -317,7 +310,7 @@ onManifestInit(clearDeclarationCache)
 
 /** Retired-carrier warning (existence check only — zero content parsing, zero fallback). */
 function warnRetiredCarrier(root) {
-  console.warn(`[declaration] ${RETIRED_REL_PATH} is retired and no longer read — move codePaths / index.*Extensions / advisor.{docMap,standardsDoc} into PROJECT-MANIFEST.json`)
+  console.warn(`[declaration] ${RETIRED_REL_PATH} is retired and no longer read — move codePaths / index.*Extensions into PROJECT-MANIFEST.json`)
   logEvent("declaration:retired-file", { cwd: root })
 }
 
@@ -334,7 +327,7 @@ function warnRetiredCarrier(root) {
  * @param {string} cwd — project dir / anchor (root resolved by manifest.mjs)
  * @returns {Readonly<{declared: boolean, codePaths: readonly string[], batchRecords: readonly (readonly string[])[],
  *   index: {codeExtensions: string[], docExtensions: string[], excludePaths: string[], publicRepos: string[]},
- *   advisor: {docMap: string, standardsDoc: string}, root: string|null}>}
+ *   root: string|null}>}
  */
 export function loadProjectDeclaration(cwd) {
   const file = manifestFilePath(cwd) // data-file path (single source — manifest.mjs KD-M1-18)

package/doc-check/anchors.mjs

@@ -6,17 +6,18 @@
  *   **行号坐标（`:N`）不作节指示**——行号不作引用；
  * · 档不在盘 ⇒ `档缺`；带节指示 ∧ 节不在盘 ⇒ `节缺`。
  *
- * 抽取面：逐行扫；fenced 块整块跳过；可执行行（`isExecutableLine`）整行跳过（命令保字面）。
- * 解析序：① 仓根相对 → ② 域根相对（`scanDirs` 逐根）→ ③ 引用方档所在目录相对 →
- *   ④ 域内唯一 basename 索引（同名 ≥2 ⇒ **不判**，列报告面 = 终结）→ ⑤ 声明解析根相对（`anchors.roots` 逐根，按声明序）。
- * 节在盘：目标档内存在标题行，其标题编号（标题文本去 `^#{1,6}\s` 后的首个 `\d+(?:\.\d+)*`）= 指针节号。
- * 残余登记（fail-open 方向——归评审核验面）：裸档名在域内多义 ⇒ 不判；未闭合围栏 ⇒ 至档尾免；
- *   指针行的坐标尾不入判、同行的档 token 照判。
+ * 抽取面：逐行扫；fenced 块整块跳过；可执行行（`isExecutableLine`）整行跳过（命令保字面）；
+ *   提示词面另剥 CANON 操作数（面判据 = `./paragraph.mjs` 的 `isPromptFace`——七名整串删除后再抽，见 `CANON_OPERANDS`）。
+ * 解析序**两级**：① 仓根相对全路径 → ② 引用方档所在目录相对。零命中 ⇒ `档缺`。
+ *   **裸名不跨目录解析**：跨目录解析须先建全域目录索引——为认出一个裸名而重建索引，等于把全仓扫描请回来；
+ *   写全路径后解析零索引，逐档判就是全部（与 D4 实现坐标口径一致）。
+ * 节在盘：**只读解析命中的那一档**（点查，不遍历）——目标档内存在标题行，其标题编号
+ *   （标题文本去 `^#{1,6}\s` 后的首个 `\d+(?:\.\d+)*`）= 指针节号。
+ * 残余登记（fail-open 方向——归评审核验面）：未闭合围栏 ⇒ 至档尾免；指针行的坐标尾不入判、同行的档 token 照判。
  */
 import { readFileSync, statSync } from "node:fs"
 import { basename, dirname, resolve } from "node:path"
-import { anchorRootError } from "../manifest-schema.mjs"
-import { fenceMark, isExecutableLine } from "./width.mjs"
+import { fenceMark, isExecutableLine, isPromptFace } from "./paragraph.mjs"
 
 /** 文档指针 token：`(目录段/)*名.md` + 可选行号坐标尾 + 可选节指示（`§` + 编号）。
  *  左界守卫排除更长 token 的尾段；右界排除后续字母数字（`.md` 之后紧邻 `[\w]` ⇒ 非完整 token）。 */
@@ -34,12 +35,35 @@ const PLACEHOLDER_STEMS = new Set([
   "x", "a", "b", "file", "out", "foo", "bar", "example", "sample", "name", "path",
 ])
 
+/** CANON 操作数族（**规范豁免串** · 判据单源 = `docs/core/design/PROMPT-SYSTEM.md` §6.6「判保留面」）：
+ *  七个名字在模型面是**模型要写出来 / 读写的文件名**（行为操作数 · 路径操作数），不是「去读这个档」的指针——
+ *  换个目录解析必然 `档缺`。**只对提示词面剥**（面判据 = `isPromptFace`，单源住 `./paragraph.mjs`）：`docs/` 面不会因本条多放行一个名——
+ *  `README.md` / `MANIFEST.md` 在那里仍按指针判（其余四名早已走 `FILENAME_CLASSES` 类名免，非本条引入）。
+ *  **一处定义、两处消费**：`scripts/prompt-refs-check.mjs` 的 J3 豁免从本档 import 本表与剥除函数（不复制）；
+ *  反方向零 import——判据链自持 = `docs/core/design/DOC-DISCIPLINE.md` A-DD29 ⑤（`thincoder-core/**` 对
+ *  `scripts/**` 的 import 点 = 0）。闭集外的同形 token（非操作数）照报。 */
+export const CANON_OPERANDS = [
+  "AGENTS.md", "SKILL.md", "README.md", "MANIFEST.md",
+  ".thincoder/advisor.md", "project_rules.md",
+  "RTM.md",
+]
+
+/** 操作数剥除：逐行先整串删除七名 CANON 操作数再抽（与 `scripts/prompt-refs-check.mjs` 的 J3 豁免同式）。 */
+export function stripCanonOperands(line) {
+  let out = line
+  for (const s of CANON_OPERANDS) out = out.split(s).join("")
+  return out
+}
+
+/** 操作数豁免的**作用面** = 提示词面（`thincoder-core/prompts/**`）——**只此一面**：`docs/` 面同名 token 仍按指针判
+ *  （`README.md` / `MANIFEST.md` 在那里照报 `档缺`；其余四名走既有的 `FILENAME_CLASSES` 类名免，非本条引入）。
+ *  这是锚判自己的面判据——与段判据零共享开关：段判据按传入档全量判（提示词面照判——逐行裸判，无面级豁免）。 */
+// 提示词面判据单源 = `./paragraph.mjs` 的 `isPromptFace`（§3.18 ②——形态与旧 `OPERAND_FACE` 逐字同）。
+const isOperandFace = isPromptFace
+
 /** 文件存在性（目录 / 读错 ⇒ false）。 */
 function isFile(p) { try { return statSync(p).isFile() } catch { return false } }
 
-/** 目录存在性（文件 / 读错 ⇒ false）。 */
-function isDir(p) { try { return statSync(p).isDirectory() } catch { return false } }
-
 /** 标题编号（标题文本去 `^#{1,6}\s` 后的首个 `\d+(?:\.\d+)*`）；非标题行 ⇒ null。 */
 function headingNumber(line) {
   const m = /^#{1,6}\s+/.exec(line)
@@ -56,63 +80,32 @@ function sectionOnDisk(path, num) {
   return false
 }
 
-/** 档解析（判据 ① 的解析序 ①–⑤）：命中 ⇒ `{ ok, path }`；同名 ≥2 ⇒ `{ ambiguous, candidates }`；零命中 ⇒ `{ ok:false }`。
+/** 档解析（判据 ① 的解析序两级）：命中 ⇒ `{ ok, path }`；零命中 ⇒ `{ ok:false }`。
  *  行号坐标尾（`:N`）不参与档解析——token 只取 `.md` 段（抽取面已剥离坐标尾与节指示）。
- *  `roots` = 声明解析根（已按值形 ∧ 根在盘过滤）——第 ⑤ 步，口径单源 = `DOC-DISCIPLINE.md` §3.20 判据 ①。 */
-function resolveDoc(token, refFile, base, scanDirs, index, roots) {
+ *  `num` = 指针节号（`§` 后编号；无节指示 ⇒ null）——仅用于判定节在盘，不参与档解析。 */
+function resolveDoc(token, refFile, base) {
   const p1 = resolve(base, token)
-  if (isFile(p1)) return { ok: true, path: p1 } // ① 仓根相对
-  for (const d of scanDirs) { const p = resolve(base, d, token); if (isFile(p)) return { ok: true, path: p } } // ② 域根相对
-  const p3 = resolve(dirname(refFile), token)
-  if (isFile(p3)) return { ok: true, path: p3 } // ③ 引用方档所在目录相对
-  const cands = index.get(basename(token)) ?? [] // ④ 域内唯一 basename 索引
-  if (cands.length === 1) return { ok: true, path: cands[0] }
-  if (cands.length > 1) return { ambiguous: true, candidates: cands } // ④ 多义 ⇒ 终结，不进 ⑤
-  for (const r of roots) { const p = resolve(base, r, token); if (isFile(p)) return { ok: true, path: p } } // ⑤ 声明解析根相对
+  if (isFile(p1)) return { ok: true, path: p1 } // ① 仓根相对全路径
+  const p2 = resolve(dirname(refFile), token)
+  if (isFile(p2)) return { ok: true, path: p2 } // ② 引用方档所在目录相对
   return { ok: false }
 }
 
-/** 声明解析根逐元素归类（口径单源 = `DOC-DISCIPLINE.md` §3.20 判据 ① 解析序 ⑤）：
- *  `usable` = 参与解析的根（声明序）；`gaps` = 报告面（不作判）。缺键 ⇒ 本步零效（不产报告行）。 */
-function classifyRoots(base, roots) {
-  const out = { usable: [], gaps: [] }
-  if (roots === undefined) return out
-  if (!Array.isArray(roots)) { out.gaps.push({ kind: "invalid", root: roots, reason: "非字符串数组" }); return out }
-  for (const r of roots) {
-    const why = anchorRootError(r)
-    if (why) { out.gaps.push({ kind: "invalid", root: r, reason: why }); continue }
-    if (!isDir(resolve(base, r))) { out.gaps.push({ kind: "missing", root: r }); continue }
-    out.usable.push(r)
-  }
-  return out
-}
-
 /**
- * 锚判据主行程：域内逐档逐行抽取 + 解析 + 节在盘判定。
- * @param {string} root 项目根（判据参数已由调用方自 `checkConfig` 读出）
- * @param {{scanDirs?:string[], files?:string[], checkFiles?:string[], roots?:string[]}} o `files` = 域内 `.md` 全集（单源 = `scanDomain`）；
- *   `checkFiles` = **被判集**（gate 的范围收窄面——缺省 ⇒ `files`）：索引仍按 `files` 建（解析基线不缩），
- *   只把「抽哪几档的行」收窄——否则改过的档引用未改档会假报 `档缺`（假阳即机制失效）；
- *   `roots` = 声明解析根原值（值形 ∥ 根在盘的门归本函数——报告面逐元素弃用 / 列缺位）。
- * @returns {{hits:Array, reports:Array, rootGaps:Array}} hits = 命中（`档缺` / `节缺`）；reports = 报告面（多义——不作判）；
- *   rootGaps = 报告面（解析根弃用 ∥ 缺位——不作判）
+ * 锚判据主行程：传入档逐档逐行抽取 + 解析 + 节在盘判定。
+ * @param {string} root 项目根（解析序 ① 的基准）
+ * @param {{files?:string[]}} o `files` = **判定集兼解析集**（调用方传入的档清单——判定范围 = 解析范围，
+ *   无目录遍历、无全域索引：清单外的档既不判也不参与解析）
+ * @returns {{hits:Array}} hits = 命中（`档缺` / `节缺`）
  */
-export function checkAnchors(root, { scanDirs = [], files = [], checkFiles, roots } = {}) {
+export function checkAnchors(root, { files = [] } = {}) {
   const base = resolve(root)
-  const dirs = Array.isArray(scanDirs) ? scanDirs : []
-  const { usable, gaps } = classifyRoots(base, roots)
-  const index = new Map()
-  for (const f of files) {
-    const k = basename(f)
-    if (!index.has(k)) index.set(k, [])
-    index.get(k).push(f)
-  }
   const hits = []
-  const reports = []
-  for (const f of checkFiles ?? files) {
+  for (const f of files) {
     let text = ""
     try { text = readFileSync(f, "utf8") } catch { continue }
     const re = new RegExp(ANCHOR_RE.source, "g") // 每档一份实例（零共享 lastIndex 状态）
+    const stripOperands = isOperandFace(f) // 只有提示词面剥（面判据 = `isPromptFace`）
     let fence = null // 围栏标记（` ∥ ~）；null = 不在块内
     text.split("\n").forEach((l, i) => {
       const mark = fenceMark(l)
@@ -123,20 +116,20 @@ export function checkAnchors(root, { scanDirs = [], files = [], checkFiles, root
       }
       if (fence !== null) return
       if (isExecutableLine(l)) return // 可执行行整行跳过
+      const scan = stripOperands ? stripCanonOperands(l) : l // 提示词面：操作数先剥再抽；文档面 = 原行
       let m
-      while ((m = re.exec(l)) !== null) {
+      while ((m = re.exec(scan)) !== null) {
         const token = m[1]
         const num = m[2] ?? null
         const bn = basename(token).toLowerCase()
         const stem = bn.replace(/\.md$/, "")
         // 类名 ∥ 占位符两免：抽取面不把它们当指针（判据 = DOC-DISCIPLINE §3.20 ① 的「档 token」定义面）
         if (FILENAME_CLASSES.has(bn) || stem.length <= 1 || PLACEHOLDER_STEMS.has(stem)) continue
-        const r = resolveDoc(token, f, base, dirs, index, usable)
-        if (r.ambiguous) { reports.push({ file: f, line: i + 1, token, candidates: r.candidates }); continue }
+        const r = resolveDoc(token, f, base)
         if (!r.ok) { hits.push({ file: f, line: i + 1, token, clazz: "档缺" }); continue }
         if (num !== null && !sectionOnDisk(r.path, num)) hits.push({ file: f, line: i + 1, token, clazz: "节缺", section: num, target: r.path })
       }
     })
   }
-  return { hits, reports, rootGaps: gaps }
+  return { hits }
 }

package/doc-check/index.mjs

@@ -1,109 +1,95 @@
 /**
- * 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` 声明（不硬编码任何本仓路径）。
+ *   ① 锚（档缺 / 节缺）——实现 = `./anchors.mjs`；② 段判据（段太长 ∥ 行太长）——口径 = §3.18 条目 Q，实现 = `./paragraph.mjs`。
+ * 判据参数 = **工具内置常量** `DOC_CHECK_BUILTINS`：不读任何项目的声明面，因而没有「缺参数 ⇒ 拒跑」这一层，
+ *   也没有常量校验面——改判据 = 改代码、走评审。
+ * 判定范围 = **调用方传入的文件清单**（判定范围 = 解析范围 = 传入的那几档；无目录遍历、无全域兜底）：
+ *   不给清单 ⇒ 明确报错要求显式清单——判了本轮没碰过的档，别轮的存量问题会记到本轮头上。
  * 两种问法（§3.20「工具形」——同一条判据）：
- *   `report`（缺省）= 全域报告态——**零门禁 / 零退出码 / 零阻断**，输出不得被读作拒执行的理由（用户令 > 机检）；
- *   `gate` = 交付时点的**范围化裁定**——只判本轮改过的档（整档入判），首行给机器可判 verdict；
- *   强制面住交付协议 + 批次档 §6 前置，工具本体仍不阻断任何动作。
+ *   `report`（缺省）= 报告态——**零门禁 / 零退出码 / 零阻断**，输出不得被读作拒执行的理由（用户令 > 机检）；
+ *   清单里不可判档（不在盘 ∥ 非 .md）⇒ 报错点名、整次零判定；
+ *   `gate` = 交付时点的裁定——首行给机器可判 verdict；不可判档给跳过行（可见，不静默丢掉）。
+ *   强制面住交付协议 + 批次档 §6 前置，工具本体不阻断任何动作。
  */
 import { statSync } from "node:fs"
 import { relative, resolve } from "node:path"
-import { MANIFEST_REL, readManifest } from "../manifest.mjs"
-import { anchorRootError } from "../manifest-schema.mjs"
-import { scanDomain, checkDocWidths } from "./width.mjs"
+import { checkParagraphs } from "./paragraph.mjs"
 import { checkAnchors } from "./anchors.mjs"
 
+/** 判据参数（内置常量 · 冻结）：阈值 300 字符（一段 ∥ 一行同值——§3.18 ④）；两项空列表 = 区带类 / 豁免类默认值且恒空
+ *  ——豁免谓词（表行 / 围栏 / 列表项 / 引文）住代码，没有「登记后放过」的写入口（空列表 ≠ 可登记豁免）。 */
+export const DOC_CHECK_BUILTINS = Object.freeze({
+  paragraphMax: 300,
+  lineMax: 300,
+  paragraphExemptZones: Object.freeze([]),
+  exemptions: Object.freeze([]),
+})
+
 /** 相对路径显示形（正斜杠——跨平台同形）。 */
 const rel = (root, p) => relative(root, p).replace(/\\/g, "/")
 
-/** 平台路径键（Windows 大小写不敏感——只用于域集比对，非判据面）。 */
+/** 平台路径键（Windows 大小写不敏感——只用于清单去重，非判据面）。 */
 const pathKey = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
 
-/** 文件存在性（目录 / 读错 ⇒ false）。 */
-function isFile(p) { try { return statSync(p).isFile() } catch { return false } }
-
-/** gate 取参失败（manifest 不可读 ∥ checkConfig 不合法）——**不产 PASS**（消费面 fail-closed）。 */
-function gateParamError(base, read) {
-  const reason = read.reason === "missing"
-    ? `${MANIFEST_REL} 不在 ${base}`
-    : (read.errors?.length ? read.errors.join("；") : String(read.reason ?? "未知原因"))
-  return {
-    report: [
-      `DOC-CHECK GATE: ERROR（manifest 不可读 —— ${reason}）`,
-      "原因：取参失败——判据参数来自 `PROJECT-MANIFEST.json` `checkConfig`，无声明面即无判据",
-      "处置：修声明面（`checkConfig`）后复跑",
-    ].join("\n"),
-    hits: { total: 0, anchors: 0, width: 0 }, anchorHits: [], widthHits: [], anchorReports: [],
-    files: [], checkFiles: [], scanDirs: [], lineWidth: null, zones: [], exclude: [],
-    skipped: { outside: [], gone: [] }, error: "manifest",
-  }
-}
-
-/** 声明面形态判据（gate 专用——报告态行为逐字不变）：取参不合法 ⇒ 判据失效却出 PASS = fail-open，故 gate 先判后跑。
- *  分工：**整键缺** = 上方 `read.missingKeys` 判据（`fillDefaults` 会补内置默认值）；**子键形态** = 本函数
- *  （`validateManifest` 只拒 `docRoot` 值与三族键形态，`checkConfig` 子键不拒 ⇒ 不在这里判就没人判）。 */
-function configError(cfg) {
-  if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg)) return "`checkConfig` 须为对象"
-  if (!Array.isArray(cfg.scanDirs) || cfg.scanDirs.length === 0 || !cfg.scanDirs.every((d) => typeof d === "string" && d.trim() !== "")) {
-    return "`checkConfig.scanDirs` 须为非空字符串数组（空域不得出 PASS——空域假绿比红更坏）"
-  }
-  if (typeof cfg.lineWidth !== "number" || !Number.isFinite(cfg.lineWidth) || cfg.lineWidth <= 0) return "`checkConfig.lineWidth` 须为正有限数值"
-  if (cfg.widthExemptZones !== undefined && !Array.isArray(cfg.widthExemptZones)) return "`checkConfig.widthExemptZones` 须为数组"
-  if (cfg.anchors !== undefined) {
-    if (cfg.anchors === null || typeof cfg.anchors !== "object" || Array.isArray(cfg.anchors)) return "`checkConfig.anchors` 须为对象"
-    if (cfg.anchors.exclude !== undefined && !Array.isArray(cfg.anchors.exclude)) return "`checkConfig.anchors.exclude` 须为数组"
-    if (cfg.anchors.roots !== undefined) {
-      if (!Array.isArray(cfg.anchors.roots)) return "`checkConfig.anchors.roots` 须为字符串数组（元素 = 相对项目根的目录）"
-      for (const r of cfg.anchors.roots) {
-        const why = anchorRootError(r)
-        if (why) return `\`checkConfig.anchors.roots\` ${why}：${JSON.stringify(r)}`
-      }
-    }
-  }
+/** 不可判档的两因（闭集 · 判序 = 存在性 → 类型）：不在盘 ∥ 非 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
 }
 
-/**
- * gate 范围求交：候选（`docs`）= 显式清单 ∥ 本会话触达记账 ⇒ **声明域内 ∧ 盘上存在的 `.md`**。
- * 域外 / 已删**不是命中**但必须可见（跳过行）——静默丢掉会把「没跑」装成「跑了且清」。
- * 解析基线不缩：域内全集仍交锚判据建索引（只收窄被判档）。
- */
-function resolveRange(base, files, docs) {
-  const inDomain = new Map(files.map((f) => [pathKey(f), f]))
-  const check = new Set()
-  const outside = []
-  const gone = []
-  for (const d of Array.isArray(docs) ? docs : []) {
-    if (typeof d !== "string" || d.trim() === "") continue
+/** 清单 → 可判集（去重保序）+ 不可判档两类（`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 hit = inDomain.get(pathKey(abs))
-    if (hit) check.add(hit)
-    else if (isFile(abs)) outside.push(abs)
-    else gone.push(abs)
-  }
-  return { check: [...check].sort(), outside, gone }
+    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 }
 }
 
+/** 段判据命中行（报面单源——两类命中同形，按 `clazz` 分词）。 */
+const paragraphHitLine = (base, h) => `✗ ${h.clazz} ${rel(base, h.file)}:${h.line}（${h.len} 字符）`
+
 /** gate 报面（固定句形——§3.20「报面（固定句形 · 交付门 gate）」）：首行 verdict = 唯一机判串。 */
-function gateReport({ base, docsSource, checkFiles, domainCount, skipped, anchors, widths, lineWidth, exclude }) {
-  const total = anchors.hits.length + widths.length
+function gateReport({ base, docsSource, checkFiles, skipped, anchors, paragraphs, paragraphMax }) {
+  const total = anchors.hits.length + paragraphs.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）",
-    `范围：${src} ${checkFiles.length} 档（声明域 ${domainCount} 档）· 阈值 ${lineWidth} 字符（运行时取 checkConfig.lineWidth）· 排除：${exclude.length ? exclude.join(" ∥ ") : "（无）"}`,
-    "判据：与报告态同源（`PROJECT-MANIFEST.json` `checkConfig`）——范围只收窄被判档，不收窄解析",
+    checkFiles.length
+      ? `范围：${src} ${checkFiles.length} 档 · 阈值 ${paragraphMax} 字符（工具内置常量）`
+      : `范围：${src} —— **0 档受检**（空清单：本次没有判任何档，不得读作「已检」）· 阈值 ${paragraphMax} 字符（工具内置常量）`,
+    "判据：工具内置常量（锚 ∥ 段判据）——判定范围 = 解析范围 = 传入档",
   ]
-  if (skipped.outside.length) out.push(`跳过 ${skipped.outside.length} 档（不在声明域内，未检）：${skipped.outside.map((p) => rel(base, p)).join(" ∥ ")}`)
-  if (skipped.gone.length) out.push(`跳过 ${skipped.gone.length} 档（已不在盘，未检）：${skipped.gone.map((p) => rel(base, p)).join(" ∥ ")}`)
+  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）——照实说明 + 给出补充通道
+    // 空范围不静默当通过（K6）——照实说明 + 给出补充通道（两侧都不得读成「已检」）。
+    // 措辞按「有没有跳过行」分流：无跳过行时不得写「见上方跳过行」。
+    const hasSkips = skipped.missing.length > 0 || skipped.notMarkdown.length > 0
     out.push(docsSource === "session"
-      ? "范围为空：本会话没有写过声明域内的文档——若确认改过 ⇒ 显式传 docs"
-      : "范围为空：显式 docs 无一落在声明域内——见上方跳过行")
+      ? (hasSkips
+        ? "范围为空：本会话触达的档均不可判（见上方跳过行）——若确认改过 ⇒ 显式传 docs"
+        : "范围为空：本会话没有写过 .md 档——若确认改过 ⇒ 显式传 docs")
+      : (hasSkips
+        ? "范围为空：显式 docs 里没有可判档——见上方跳过行"
+        : "范围为空：显式 docs 是空清单——列出要判的档后复跑"))
   } else if (total === 0) {
     out.push(`结论：0 条命中（${checkFiles.length} 档全清）`)
   } else {
@@ -112,7 +98,7 @@ function gateReport({ base, docsSource, checkFiles, domainCount, skipped, anchor
         ? `✗ 锚·档缺 ${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} 字符）`)
+    for (const w of paragraphs) out.push(paragraphHitLine(base, w))
     out.push("处置：同轮修正后复跑（改文档 ∥ 修引擎）；不转台账；拿不准 ⇒ 上抛主 agent 裁决（主 agent 拿不准 ⇒ 转呈用户）")
   }
   return out.join("\n")
@@ -120,91 +106,71 @@ function gateReport({ base, docsSource, checkFiles, domainCount, skipped, anchor
 
 /**
  * 跑一次文档纪律机检。
- * @param {string} root 项目根（判据参数取该根的 `PROJECT-MANIFEST.json` `checkConfig`）
+ * @param {string} root 项目根（解析序 ① 的基准）
  * @param {{docs?:string[], mode?:'report'|'gate', docsSource?:'session'|'explicit'}} [o]
- *   `mode` 缺省 = `report`（全域报告态）；`docs` = **仅 gate** 的范围候选（相对 `root` 或绝对）；
- *   `docsSource` = 范围来源标签（`session` = 本会话触达记账 ∥ `explicit` = 显式 `docs`）——缺省按 `docs` 是否给定推定；只影响报面措辞。
- * @returns {{report:string, hits:{total:number, anchors:number, width:number}, anchorHits:Array,
- *   widthHits:Array, anchorReports:Array, anchorRootGaps:Array, files:string[], checkFiles:string[], scanDirs:string[],
- *   lineWidth:number|null, zones:string[], exclude:string[], skipped:{outside:string[], gone:string[]},
- *   error?:"manifest"}}
- *   `error` 在场 ⇒ 取参失败形（首行 = `DOC-CHECK GATE: ERROR（…）`、`lineWidth` = null、`hits` 恒 0）——
- *   消费面判「清」须读 `report` 首行，不得只看 `hits.total`（0 与「未跑成」不同义）。
+ *   `mode` 缺省 = `report`；`docs` = 被判档清单（相对 `root` 或绝对）——**必填**（两种问法同）：
+ *   缺省 ∥ 非数组 ⇒ 报错要求显式清单（零遍历、零全域兜底）；`report` 面**空数组也报错**，`gate` 面空数组 ⇒
+ *   `PASS（0 档）` + 空范围说明（「本轮一档没碰」是真实读数）；`report` 面不可判档 ⇒ 报错、整次零判定；
+ *   `gate` 面不可判档 ⇒ 跳过行；`docsSource` = 范围来源标签（`session` = 本会话触达记账 ∥ `explicit` = 显式
+ *   `docs`）——缺省 = `explicit`；只影响报面措辞。
+ * @returns {{report:string, hits:{total:number, anchors:number, paragraph:number}, anchorHits:Array,
+ *   paragraphHits:Array, files:string[], checkFiles:string[], paragraphMax:number,
+ *   skipped:{missing:string[], notMarkdown:string[]}}}
+ *   消费面判「清」须读 `report` 首行（gate）∥ `hits.total`（report），不得只看其中一个。
  */
 export function runDocCheck(root, { docs, mode = "report", docsSource } = {}) {
   const base = resolve(root)
   const gate = mode === "gate"
-  // `docs` = gate 专属（report + docs ⇒ 拒，不静默忽略——与工具面同一判据）
-  if (!gate && docs !== undefined) throw new Error("doc_check: `docs` is gate-only — report mode always checks the whole declared domain")
-  const source = docsSource ?? (docs === undefined ? "session" : "explicit")
-  let read
-  try {
-    read = readManifest(base)
-  } catch (e) {
-    if (!gate) throw e // 报告态既有行为逐字不变（读错 fail-closed 上抛）
-    return gateParamError(base, { reason: "unreadable", errors: [e?.message ?? String(e)] })
+  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 (!read.ok) {
-    if (gate) return gateParamError(base, read)
-    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("；")})`)
+  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.')
   }
-  // `checkConfig` 整键缺失：`readManifest` 会经 `fillDefaults` 灌入默认值（`missingKeys` 是唯一痕迹）——
-  // gate 不得拿内置默认值当声明面（设计「取参失败 ⇒ ERROR」的第一支）。
-  if (gate && (read.missingKeys ?? []).includes("checkConfig")) {
-    return gateParamError(base, { reason: "invalid-config", errors: ["`checkConfig` 缺——声明面未声明判据参数"] })
+  // 报告态空清单 = 报错（「没跑」不得装成「跑了且清」）；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 cfg = read.manifest.checkConfig ?? {}
-  if (gate) {
-    const bad = configError(cfg)
-    if (bad) return gateParamError(base, { reason: "invalid-config", errors: [bad] })
+  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.`)
+  }
+  // 报告态 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 scanDirs = (Array.isArray(cfg.scanDirs) ? cfg.scanDirs : []).filter((d) => typeof d === "string" && d !== "")
-  const exclude = Array.isArray(cfg.anchors?.exclude) ? cfg.anchors.exclude : []
-  const roots = cfg.anchors?.roots // 原值下传：值形 ∥ 根在盘的门归 anchors（报告态弃用、不炸）
-  const lineWidth = cfg.lineWidth
-  const zones = (Array.isArray(cfg.widthExemptZones) ? cfg.widthExemptZones : []).filter((z) => typeof z === "string" && z !== "")
-
-  const files = scanDomain(base, { scanDirs, exclude })
-  const range = gate ? resolveRange(base, files, docs) : { check: files, outside: [], gone: [] }
   const checkFiles = range.check
-  const anchors = checkAnchors(base, { scanDirs, files, checkFiles, roots })
-  const widths = checkDocWidths(base, { lineWidth, scanDirs, exclude, exemptZones: zones, files, checkFiles })
+  const { paragraphMax, lineMax, paragraphExemptZones } = DOC_CHECK_BUILTINS
+  const anchors = checkAnchors(base, { files: checkFiles })
+  const paragraphs = checkParagraphs({ paragraphMax, lineMax, exemptZones: paragraphExemptZones, files: checkFiles })
 
-  const hits = { total: anchors.hits.length + widths.length, anchors: anchors.hits.length, width: widths.length }
+  const hits = { total: anchors.hits.length + paragraphs.length, anchors: anchors.hits.length, paragraph: paragraphs.length }
   const shared = {
-    hits, anchorHits: anchors.hits, widthHits: widths, anchorReports: anchors.reports, anchorRootGaps: anchors.rootGaps,
-    files, checkFiles, scanDirs, lineWidth, zones, exclude, skipped: { outside: range.outside, gone: range.gone },
+    hits, anchorHits: anchors.hits, paragraphHits: paragraphs, files: checkFiles, checkFiles, paragraphMax,
+    skipped: { missing: range.missing, notMarkdown: range.notMarkdown },
   }
   if (gate) {
-    return {
-      ...shared,
-      report: gateReport({ base, docsSource: source, checkFiles, domainCount: files.length, skipped: shared.skipped, anchors, widths, lineWidth, exclude }),
-    }
+    return { ...shared, report: gateReport({ base, docsSource: source, checkFiles, skipped: shared.skipped, anchors, paragraphs, paragraphMax }) }
   }
 
-  const total = hits.total
   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} 档 · 阈值 ${paragraphMax} 字符（工具内置常量）· 区带豁免：${paragraphExemptZones.length ? paragraphExemptZones.join(" ∥ ") : "无"}`,
+    "声明：判据参数 = 工具内置常量；范围 = 传入文件（判定范围 = 解析范围）",
+    `范围：传入清单 ${checkFiles.length} 档（整档入判 · 判定范围 = 解析范围）`,
+    `命中 ${hits.total} 条（锚 ${anchors.hits.length} · 段太长 ${paragraphs.filter((h) => h.clazz === "段太长").length} · 行太长 ${paragraphs.filter((h) => h.clazz === "行太长").length}）`,
   ]
-  // 报告面（不作判）：① 声明解析根弃用 ∥ 缺位（⑤ 的配置面）；② 域内同名 ≥2 ⇒ 多义不判（残余登记——fail-open 方向，归评审核验面）
-  for (const g of anchors.rootGaps) {
-    out.push(g.kind === "missing"
-      ? `报告 锚·声明解析根缺位 \`${g.root}\`（未核、不入判）`
-      : `报告 锚·解析根弃用 ${JSON.stringify(g.root)}（值形非法：${g.reason} · 本元素不入判）`)
-  }
-  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 条命中（锚 ∥ 行宽 均清）")
+  for (const w of paragraphs) out.push(paragraphHitLine(base, w))
+  out.push(hits.total ? `结论：${hits.total} 条命中——报告态，不作拒执行的理由` : "结论：0 条命中（锚 ∥ 段太长 ∥ 行太长 均清）")
 
   return { ...shared, report: out.join("\n") }
 }