@thincoder/core 0.9.5 → 0.10.1

package/ledger-tools.mjs

@@ -0,0 +1,188 @@
+/**
+ * ledger-tools.mjs — 台账五工具定义（查询二 = 只读全角色 / 写三 = 仅主 agent 装配）+ 工具层参数守卫。
+ * 自 `ledger-cmd.mjs` 拆出（2026-09-28 守卫族微修批 · 台账 #473——纯搬移、语义零变；核函数留原档）。
+ * 守卫 = **声明派生**（设计档 §3.2：枚举 / 必填 / 类型取自工具自身 `parameters`，不在守卫内复写——
+ * D2「声明即校验」）；判于核函数之前 ⇒ 非法入参零写、零库动作、零 SQLite 原文外泄。读面二具同拍
+ * （#473：非法过滤参数 ⇒ 拒——不再「静默空集 / 绑原文」）。
+ * 接线：族出口 = `ledger.mjs`（re-export——消费面 tools/index.mjs · agent/family-tools.mjs 零改）；
+ * 消费侧一律动态 import `ledger.mjs`（ledger-db.mjs 静态 import node:sqlite ⇒ W8 契约②）。
+ */
+import { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
+import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger_*.md（DESC 单解析面）
+
+/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
+const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
+
+// ── 工具层参数守卫（设计档 §3.2 · 2026-09-27 快车道修复 · Gitee #IKIQGK / 台账 #472） ──
+
+/** 值预览（P1–P5 文案的 `<预览>`——设计档 §3.2）：`JSON.stringify`，超 80 字符截断加 `…`
+ *  （`undefined` 无 JSON 形 ⇒ 取文本形）。 */
+const argPreview = (v) => {
+  const s = JSON.stringify(v) ?? String(v)
+  return s.length > 80 ? `${s.slice(0, 80)}…` : s
+}
+
+/** 枚举取值域文本（P3 / P5 文案同源）。 */
+const enumText = (values) => `{${values.join(", ")}}`
+
+/** P3 后缀（声明派生）：枚举字段带取值域 / 非枚举必填串带「非空字符串」/ 数字字段仅「必填」。 */
+const requiredSuffix = (spec) => (spec.enum ? `；取值 ∈ ${enumText(spec.enum)}` : spec.type === "string" ? "；非空字符串" : "")
+
+/**
+ * 工具层参数守卫（设计档 §3.2 · Gitee #IKIQGK / 台账 #472）：判序 P1–P6，文案逐字 = §3.2 模板；
+ * 消费工具自身 `parameters` 声明派生（`required` / `type` / `enum`——枚举 / 必填 / 类型不在守卫内复写）；
+ * 只判不改（零缺省填充 / 零类型转换 / 零文本改写），返回入参对象（唯一归一 = 判序① 的缺省 / `null`
+ * ⇒ `{}`）。非法 ⇒ throw——判于核函数之前（零写、零库动作）。
+ */
+function assertToolArgs(tool, args) {
+  const name = tool.name
+  const decl = tool.parameters ?? {}
+  const props = decl.properties ?? {}
+  const fields = Object.keys(props)
+  // 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` 空串 / 全空白
+  for (const field of fields) {
+    const spec = props[field]
+    const value = args[field]
+    const required = (decl.required ?? []).includes(field)
+    if (value === undefined || value === null) {
+      if (required) throw new Error(`${name}：${field} 缺失（必填${requiredSuffix(spec)}）`)
+      continue // 可空字段 `null` ⇒ 放行（≡ 略去——与 `patch.x ?? 行值` 既有语义同源）
+    }
+    if (spec.enum) {
+      if (!spec.enum.includes(value)) throw new Error(`${name}：${field} 非法：${argPreview(value)}（取值 ∈ ${enumText(spec.enum)}）`)
+    } else if (spec.type === "string" && typeof value !== "string") {
+      throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为字符串）`)
+    } else if (spec.type === "number" && typeof value !== "number") {
+      throw new Error(`${name}：${field} 非法：${argPreview(value)}（应为数字）`)
+    }
+    if (field === "title" && typeof value === "string" && value.trim() === "") {
+      throw new Error(`${name}：${field} 为空（${required ? "必填；" : ""}非空字符串）`)
+    }
+  }
+  return args
+}
+
+// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
+
+export const ledgerQueryTool = {
+  name: "ledger_query",
+  description: DESC("ledger_query"), // #15 外置：文本单点 = tool-docs/ledger_query.md（两池词表逐字保留）
+  parameters: {
+    type: "object",
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
+      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
+      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
+    },
+    additionalProperties: false,
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    args = assertToolArgs(ledgerQueryTool, args)
+    return JSON.stringify(ledgerQuery({ cwd: args.cwd ?? cwdOf(ctx), status: args.status, kind: args.kind, board: args.board }), null, 2)
+  },
+}
+
+export const ledgerCountTool = {
+  name: "ledger_count",
+  description: DESC("ledger_count"), // #15 外置：文本单点 = tool-docs/ledger_count.md
+  parameters: {
+    type: "object",
+    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
+    additionalProperties: false,
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    args = assertToolArgs(ledgerCountTool, args)
+    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
+  },
+}
+
+export const ledgerAddTool = {
+  name: "ledger_add",
+  description: DESC("ledger_add"), // #15 外置：文本单点 = tool-docs/ledger_add.md（两池词表逐字保留）
+  parameters: {
+    type: "object",
+    required: ["kind", "title"],
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      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: "技术待办触发（可空）" },
+    },
+    additionalProperties: false,
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    args = assertToolArgs(ledgerAddTool, args)
+    const { cwd, ...row } = args
+    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
+    return JSON.stringify({ id, status: "待讨论" })
+  },
+}
+
+export const ledgerUpdateTool = {
+  name: "ledger_update",
+  description: DESC("ledger_update"), // #15 外置：文本单点 = tool-docs/ledger_update.md
+  parameters: {
+    type: "object",
+    required: ["id"],
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      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: "证据（缺省 = 不变）" },
+      trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "触发（缺省 = 不变）" },
+      executor: { type: "string", description: "执行者 sessionId（可选——接手改写归属用；缺省 = 按状态迁移语义：进在途自动写本会话 / 出在途自动清空 / 其余不变）" },
+    },
+    additionalProperties: false,
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    args = assertToolArgs(ledgerUpdateTool, args)
+    const { cwd, id, ...patch } = args
+    let executorSessionId
+    if (patch.executor == null) {
+      // 显式 `null` ≡ 略去（§3.1 `null` 口径 · #474——与缺省同分支）；动态 import——零新静态边（K-LX1）；
+      // 工具层供值，核心函数保持参数注入纯函数
+      const { getSessionId } = await import("./session-slots.mjs")
+      executorSessionId = getSessionId()
+    }
+    return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch, executorSessionId }))
+  },
+}
+
+export const ledgerCloseTool = {
+  name: "ledger_close",
+  description: DESC("ledger_close"), // #15 外置：文本单点 = tool-docs/ledger_close.md
+  parameters: {
+    type: "object",
+    required: ["id", "status"],
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      id: { type: "number", description: "条目 id" },
+      status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 追认核销 / 撤回）" },
+    },
+    additionalProperties: false,
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    args = assertToolArgs(ledgerCloseTool, args)
+    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
+  },
+}

package/ledger.mjs

@@ -5,7 +5,8 @@
  * v1 md 台账（docs/TODO.md 扫描器）→ SQLite 单表（ledger.db，项目级、不进 git）：六态 CHECK 机械
  * 锁死、COUNT 单源计数、事务保证收口原子、归档 = 软删除。行龄源 = SQLite 时间戳（无 git blame）。
  *
- * 面：① 命令族（查询 = 只读全角色 / 写 = 仅主 agent——接线见 tools/index.mjs 与 agent/family-tools.mjs）
+ * 面：① 命令族（查询 = 只读全角色 / 写 = 仅主 agent——核函数 `ledger-cmd.mjs` + 工具定义 `ledger-tools.mjs`
+ * 两源，接线见 tools/index.mjs 与 agent/family-tools.mjs）
  * ② 族发现（findProject / discoverFamily——标记 = ledger.db）③ scan 组装（buildScan——行集 + ledgerCount
  * → scan 对象，形状契约 = pool/tech/aged/thresholdReached/actionable/root/name/ledger）
  * ④ 通知去重（送达门 + 一次性去重——去重档跨会话、跨端共享）⑤ 格式 helper（行文本逐字契约）。
@@ -20,6 +21,8 @@ import { configDir } from "./config.mjs"
 import { ledgerDbPath, PENDING_STATUSES } from "./ledger-db.mjs"
 import { ledgerQuery } from "./ledger-cmd.mjs"
 import { executorTail } from "./ledger-executors.mjs"
+// 归一步单源（#585——盘符大写契约直引 `session-slots.mjs`；先例 = `ledger-db.mjs:23`）。
+import { normalizeCwd } from "./session-slots.mjs"
 
 /** 老化阈值（天——口径 = 需求档；`days` 参数可覆盖）。 */
 export const AGING_DAYS = 30
@@ -182,9 +185,10 @@ export function planChangeLines(prev, scan) {
 
 /** 去重档键 = 台账库绝对路径·正斜杠 + **盘符大写**（跨端同规则——CLI 的 `process.cwd()` 盘符大写、
  *  VSC 的 `uri.fsPath` 小写（`session-slots.mjs` `normalizeCwd` 同一契约——session / checkpoint /
- *  trace 跨端共享即赖此）；CLI 写的键 VSC 须逐字认得）。 */
+ *  trace 跨端共享即赖此）；盘符步 = `normalizeCwd` 直调（单源——#585；先例 = `ledger-db.mjs:23`）、
+ *  分隔符折叠自持；CLI 写的键 VSC 须逐字认得）。 */
 export function notifyKey(ledger) {
-  return resolve(ledger).replace(/\\/g, "/").replace(/^([a-z]):/, (_, d) => `${d.toUpperCase()}:`)
+  return normalizeCwd(resolve(ledger).replace(/\\/g, "/"))
 }
 
 /** 去重档读（缺失 / 坏 JSON → 空态——N1 降级不崩）。 */
@@ -209,6 +213,7 @@ export function saveNotifyState(file, state) {
 
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3） ──
 export { ALLOWED_MIGRATIONS, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
-export { ledgerAdd, ledgerAddTool, ledgerClose, ledgerCloseTool, ledgerCount, ledgerCountTool, ledgerQuery, ledgerQueryTool, ledgerUpdate, ledgerUpdateTool } from "./ledger-cmd.mjs"
+export { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
+export { 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

@@ -21,8 +21,8 @@
  *   工具事件不记 args；URL 不入事件（llm/tool 事件从不携带 URL；err 文本经形态扫描）。
  * - 摘要截断（B 方案，2026-09-03 用户裁定）：截断处带 "…" 标记（截后仍 ≤上限）。
  * - 测试隔离：node --test 进程（NODE_TEST_CONTEXT）默认不写盘——防测试事件污染真实
- *   诊断日志（两端测试套件都会跑真实 agent 管线）；显式设置 THINCODER_LOG_DIR 强制
- *   写入该目录（log.test.mjs 用它隔离临时目录——refinement #6）。
+ *   诊断日志（两端测试套件都会跑真实 agent 管线）；显式测试缝（_setLogsDirForTest）
+ *   强制写入该目录（log.test.mjs 用它隔离临时目录——refinement #6）。
  * - 轮转清理（refinement #3——长驻进程覆盖）：非仅启动时——每进程每日**首次写事件**
  *   时顺带清理 >1 天的 agent-*.log（extension host 可长驻数月，启动清理覆盖不到）。
  * - seq：每进程单调计数器。双端同写一个文件时 seq 会各自重复——定位同文件时序以
@@ -46,9 +46,14 @@ let _seq = 0
 let _dead = false // 进程内写失败即死（NF-L1 静默降级——不逐事件重复空转）
 let _cleanupDate = null // 本进程已执行过清理的日期（每日首次写时清一次）
 
-/** 日志目录：THINCODER_LOG_DIR（测试隔离/override）> ~/.thincoder/logs（与 sessions/ 同域） */
+/** Test seam: override the logs directory (process-internal seam — CONFIG.md §6.2 ③ 通道). */
+let _logsDir = null
+export function _setLogsDirForTest(p) { _logsDir = p }
+export function _resetLogsDirForTest() { _logsDir = null }
+
+/** 日志目录：显式测试缝 > ~/.thincoder/logs（与 sessions/ 同域） */
 export function logsDir() {
-  return process.env.THINCODER_LOG_DIR ?? join(homedir(), ".thincoder", "logs")
+  return _logsDir ?? join(homedir(), ".thincoder", "logs")
 }
 
 /** 今日日志文件路径（agent-YYYY-MM-DD.log） */
@@ -58,10 +63,10 @@ export function todayLogPath(now = new Date()) {
 }
 
 /** 写门（测试隔离）：test runner 进程（NODE_TEST_CONTEXT）默认跳过——除显式
- *  THINCODER_LOG_DIR override（log.test.mjs 隔离临时目录——refinement #6）。 */
+ *  测试缝 override（log.test.mjs 隔离临时目录——refinement #6）。 */
 function writeEnabled() {
   if (_dead) return false
-  if (process.env.NODE_TEST_CONTEXT && !process.env.THINCODER_LOG_DIR) return false
+  if (process.env.NODE_TEST_CONTEXT && _logsDir === null) return false
   return true
 }
 
@@ -138,7 +143,7 @@ export function logEvent(kind, fields = {}) {
   }
 }
 
-/** 共享脱敏（§18.6 D-TR2——trace-store 复用；logEvent 自身保持"丢弃字段"语义，
+/** 共享脱敏（TRACES.md §6.1 D-TR2——trace-store 复用；logEvent 自身保持"丢弃字段"语义，
  *  本函数提供"遮蔽标记"语义——同一字段名黑名单 + 同一 SECRET_FORM 形态扫描，
  *  不发明新遮蔽模式）。字段名命中黑名单 → "[REDACTED]（整个字段遮蔽）；内容命中
  *  密钥形态 → 截断到形态前 + "[redacted]" 标记（宁可丢信息不漏密钥——§2.4）。 */

package/manifest-discovery.mjs

@@ -0,0 +1,131 @@
+/**
+ * manifest-discovery.mjs — **发现 ∕ 归属族**出档（2026-09-29 structure-split-2 · 台账 #620）：自 `manifest.mjs`
+ * 全量迁出〔原 `:39-143`〕——`MANIFEST_REL` · 测试注入位（`_setProjectRootForTest` / `_resetProjectRootForTest`）·
+ * `scanChildren`（两条梯表共用 walk 内核）· `discoverProjects`（项目梯）· `discoverRepos`（仓梯）·
+ * `owningProject`（归属形）· `resolveProjectRoot`（归属 ∨ 发现）；**结构拆分零语义**（面不变 ∕ 判据不变，
+ * 只换宿主档；切点 ∕ 缝单源 = 批档 `docs/batches/2026-09-29-structure-split-2.md` §2.2-C）。
+ *
+ * 缝 = 同名再出口：宿主 `manifest.mjs` 转口本档七名既有导出（消费者 import 面零改）；宿主自用四名
+ * （`MANIFEST_REL` ∥ `discoverProjects` ∥ `owningProject` ∥ `resolveProjectRoot`）随 import。
+ * 零环：本档不引宿主（方向单行）；档外依赖 = `node:fs` ∥ `node:path`；机制详述 = `docs/core/design/MANIFEST.md` §2.2 / §2.9。
+ */
+import { existsSync, readdirSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+/** 数据档文件名（**每个项目一份**——项目根 = 带档目录；**git 非前提**。2026-09-17 / 2026-09-21 用户裁定）。 */
+export const MANIFEST_REL = "PROJECT-MANIFEST.json"
+/** 测试注入：强制项目根（测试 tmp 非 git 仓——同 ledger `_setLedgerDirForTest` 先例）。 */
+let _projectRootOverride = null
+export function _setProjectRootForTest(dir) { _projectRootOverride = dir }
+export function _resetProjectRootForTest() { _projectRootOverride = null }
+
+/**
+ * 一层扫描内核（**模块私有**——两条梯表共用；KD-M1-23 / 设计 §2.2「单源结构」）：枚举锚的
+ * **直接子目录**一层（不递归）+ 按名排序 + 谓词过滤 ⇒ 命中表（绝对路径）。
+ * 全档唯一 `readdirSync` 落点（结构机判 T54）；锚不可读 ⇒ `[]`（不抛——调用方按「零命中」处置）。
+ * @param {string} anchor 锚绝对路径
+ * @param {(dir:string)=>boolean} isHit 子目录谓词
+ * @returns {string[]} 命中子目录绝对路径（按名排序）
+ */
+function scanChildren(anchor, isHit) {
+  try {
+    return readdirSync(anchor, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort()
+      .map((e) => join(anchor, e))
+      .filter(isHit)
+  } catch { return [] }
+}
+
+/**
+ * **项目发现**（项目梯五级——KD-M1-23 / 设计 `docs/core/design/MANIFEST.md` §2.2；**git 非前提**，
+ * 2026-09-21 用户裁定）：① 锚自身带 `MANIFEST_REL` ⇒ 锚；② 锚含 `.git` ⇒ 锚（缺档 = 建档机会）；
+ * ③ 直接子目录中**带档**者优先（非空即只看此级：恰一 ⇒ `unique` / ≥2 ⇒ `ambiguous`）；
+ * ④ 零带档才看含 `.git` 的**裸仓**（同判）；⑤ 均无 ⇒ `none`（⇒ 建档流，落点 = 会话锚）。
+ * `candidates` 一律**按名排序**（`self` / `none` ⇒ `[]`）；`matched` ∈ `manifest` / `git` / `null`
+ * 记命中（或歧义）出自哪一级。**纯 fs**（只判存在性——不解析档内容）· **不抛** · **不向上** · **不递归**。
+ * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**（测试注入面——先于真判据，同 `discoverRepos`）。
+ * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
+ * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ */
+export function discoverProjects(cwd) {
+  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
+  const anchor = resolve(cwd ?? ".")
+  if (existsSync(join(anchor, MANIFEST_REL))) return { kind: "self", root: anchor, candidates: [], matched: "manifest" }
+  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
+  const withManifest = scanChildren(anchor, (d) => existsSync(join(d, MANIFEST_REL)))
+  if (withManifest.length > 1) return { kind: "ambiguous", root: null, candidates: withManifest, matched: "manifest" }
+  if (withManifest.length === 1) return { kind: "unique", root: withManifest[0], candidates: [...withManifest], matched: "manifest" }
+  const bareRepos = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
+  if (bareRepos.length > 1) return { kind: "ambiguous", root: null, candidates: bareRepos, matched: "git" }
+  if (bareRepos.length === 1) return { kind: "unique", root: bareRepos[0], candidates: [...bareRepos], matched: "git" }
+  return { kind: "none", root: null, candidates: [], matched: null }
+}
+
+/**
+ * **仓发现**（仓梯——KD-M1-23 / `docs/core/design/TOOLS.md` §6.13；**单源** KD-M1-22——`git` 工具
+ * 经此符号接线，禁第二份实现）：① 锚含 `.git` ⇒ 锚；② 直接子目录中 `.git` **∧** 带档者恰一 ⇒ 命中
+ * （≥2 ⇒ 歧义）；③ **零个此类时才看**含 `.git` 的裸仓（恰一 ⇒ 命中 / ≥2 ⇒ 歧义）；④ 均无 ⇒ `none`。
+ * 与 `discoverProjects` = **同一 walk 内核**（`scanChildren`）的两种梯表——差异只在谓词与级序。
+ * `candidates` 按名排序；`matched` 记档位；纯 fs / 不抛 / 不递归 / 不向上；覆盖位 ⇒ 头部短路。
+ * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
+ * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ */
+export function discoverRepos(cwd) {
+  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
+  const anchor = resolve(cwd ?? ".")
+  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
+  const scoped = scanChildren(anchor, (d) => existsSync(join(d, ".git")) && existsSync(join(d, MANIFEST_REL)))
+  if (scoped.length > 1) return { kind: "ambiguous", root: null, candidates: scoped, matched: "manifest" }
+  if (scoped.length === 1) return { kind: "unique", root: scoped[0], candidates: [...scoped], matched: "manifest" }
+  const bare = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
+  if (bare.length > 1) return { kind: "ambiguous", root: null, candidates: bare, matched: "git" }
+  if (bare.length === 1) return { kind: "unique", root: bare[0], candidates: [...bare], matched: "git" }
+  return { kind: "none", root: null, candidates: [], matched: null }
+}
+
+/**
+ * **归属形单点**（KD-M1-30 / 设计 §2.9 A——2026-09-21 用户裁定「最近者优先」）：自 `target`
+ * （目录含自身；文件路径自其父目录起）沿**祖先链**逐级上溯至盘根，取**最近**带 `MANIFEST_REL`
+ * 的目录；无 ⇒ `null`（⇒ 调用方走发现兜底）。**嵌套合法**：子内归子、根其余归根。
+ * **纯 fs**（只判存在性——不解析档内容 / 不问模式）· **不跨兄弟** · **无全局优先级**。
+ * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**：直接返回覆盖值（不查档存在性——
+ * 保「覆盖即覆盖值」语义，回归守卫 = 本批批内件基座腿（`docs/batches/2026-10-02-manifest-resolution-fix.test.mjs`——
+ * 基座三态 + 覆盖位 + 薄委托等价逐格）+ `docs/batches/2026-09-29-structure-split-2.test.mjs` 导出枚举探针（`Object.keys` 名面核））。
+ * @param {string} [target] 目标路径（目录 / 文件）
+ * @returns {string|null} 最近带档祖先目录绝对路径 / null
+ */
+export function owningProject(target) {
+  if (_projectRootOverride) return resolve(_projectRootOverride)
+  let dir = resolve(target ?? ".")
+  for (;;) {
+    if (existsSync(join(dir, MANIFEST_REL))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null // 盘根 → 祖先链无档
+    dir = parent
+  }
+}
+
+/** **项目根解析的歧义直读形**（判定单点——设计 `MANIFEST.md` §2.2 `projectRootView` 契约行 / §2.5
+ *  「多档解析消费面收口」条）：`ok`（唯一解析：归属命中 ∥ 发现 `self` / `unique`）/ `ambiguous`
+ *  （≥2 候选 ⇒ `root` null + 候选全列**按名排序**）/ `none`（无项目 ⇒ 双空）；覆盖位在场 ⇒
+ *  头部短路（`ok` + 覆盖值）。**非抛错 / 零写**；`resolveProjectRoot` 薄委托本函数（行为逐字零变）。
+ *  @returns {{state:'ok'|'ambiguous'|'none', root:string|null, candidates:string[]}} */
+export function projectRootView(cwd) {
+  const owning = owningProject(cwd)
+  if (owning) return { state: "ok", root: owning, candidates: [] }
+  const d = discoverProjects(cwd)
+  if (d.root) return { state: "ok", root: d.root, candidates: [] }
+  if (d.kind === "ambiguous") return { state: "ambiguous", root: null, candidates: d.candidates }
+  return { state: "none", root: null, candidates: [] }
+}
+
+/** 项目根解析（**归属 ∨ 发现**——KD-M1-30 / M1-24）：**薄委托** `projectRootView(cwd).root`（判定
+ *  单点见上——#828）。带档路径与批前**逐字同**；变更面两条（设计 §2.2 同条）：① 项目树内路径
+ *  （祖先带档）⇒ 该项目根；② 裸仓恰一 ⇒ 该仓根（零档降级 = 建档机会）。`none` / `ambiguous` ⇒
+ *  `null`。调用方零改（行为随语义变更——设计 §2.5 键面条 / 错层条）。
+ *  @returns {string|null} 项目根绝对路径 / null */
+export function resolveProjectRoot(cwd) {
+  return projectRootView(cwd).root
+}

package/manifest-schema.mjs

@@ -0,0 +1,166 @@
+/**
+ * manifest-schema.mjs — **校验 ∕ 默认值族**出档（2026-09-29 structure-split-2 · 台账 #620）：自 `manifest.mjs`
+ * 全量迁出〔原 `:194-205` + `:240-369` 两段非连续〕——`isValidDocRootValue`（docRoot 子键值形态判据）·
+ * `DEFAULT_MANIFEST`（默认八键）· `MANIFEST_SCHEMA`（判据单源）· 元素层谓词两件 · `validateManifest` ·
+ * `fillDefaults`；**结构拆分零语义**（面不变 ∕ 判据不变，只换宿主档；切点 ∕ 缝单源 =
+ * 批档 `docs/batches/2026-09-29-structure-split-2.md` §2.2-C）。
+ *
+ * 缝 = 同名再出口：宿主 `manifest.mjs` 转口四名既有导出（`DEFAULT_MANIFEST` ∥ `MANIFEST_SCHEMA` ∥
+ * `isValidDocRootValue` ∥ `validateManifest`）；`fillDefaults` 被宿主 `readManifest` 消费 ⇒ 随迁导出（宿主 import）。
+ * 零环：本档零 import（纯谓词 ∥ 冻结常量——不引宿主 ∥ 不引它档）；机制详述 = `docs/core/design/MANIFEST.md` §2.2。
+ */
+
+/**
+ * `docRoot` 子键**值形态判据**（F7 / KD-M1-6 / KD-M1-8——判据单源）：非空字符串（`trim` 后
+ * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空）；其余（空串 /
+ * 空白串 / 空数组 / 数组含非串 / 空串 / 空白串元素 / 非串非数组）为非法。
+ * @param {unknown} value docRoot 某子键的值
+ * @returns {boolean}
+ */
+export function isValidDocRootValue(value) {
+  if (typeof value === "string") return value.trim() !== ""
+  if (!Array.isArray(value) || value.length === 0) return false
+  return value.every((p) => typeof p === "string" && p.trim() !== "")
+}
+
+/** 默认八键（架构 §2.3 E1 五键 + 三族声明键——KD-M1-31）——整档初始化的写源与缺键 fallback 的补源。 */
+export const DEFAULT_MANIFEST = Object.freeze({
+  version: 1,
+  phase: "initial-dev",
+  docRoot: Object.freeze({
+    requirements: "docs/requirements",
+    specs: "docs/requirements/specs",
+    design: "docs/design",
+    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([]),
+    lineCounts: Object.freeze([]), // 行数面机检声明（#546）：[] = 未载惰性（doc-check 行数族）
+  }),
+  // 项目声明三族（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）。 */
+export const MANIFEST_SCHEMA = Object.freeze({
+  $anchor: "docs/core/design/MANIFEST.md",
+  enum: Object.freeze({
+    phase: Object.freeze(["initial-dev", "production"]),
+  }),
+  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)),
+  }),
+})
+
+/** 三族声明键**元素层**判据（KD-M1-32）：数组且各元素为非空字符串（`trim` 后非空）；
+ *  **数组层**自身可空（`[]` 合法——`codePaths:[]` = 无段名代码面 / `index.*:[]` = 追加零项）。 */
+function isNonEmptyStringArray(v) {
+  return Array.isArray(v) && v.every((e) => typeof e === "string" && e.trim() !== "")
+}
+
+/** `checkConfig.lineCounts` 元素层判据（#546）：数组且各元素为非数组对象、`doc` / `section` 皆非空串（`trim` 后非空）；`[]` = 未载惰性。 */
+function isLineCountsValue(v) {
+  return Array.isArray(v) && v.every((e) => e !== null && typeof e === "object" && !Array.isArray(e)
+    && typeof e.doc === "string" && e.doc.trim() !== "" && typeof e.section === "string" && e.section.trim() !== "")
+}
+
+/**
+ * 形状校验（模块设计 §2.2）——枚举 / version 数值恒做；**纯函数、零 fs**（原 `{ cwd }`
+ * 指针腿已随字段整链裁撤——KD-M1-5 墓志）；不落盘。键存在性入 missingKeys（非拒）：
+ * 缺键 = 便利 fallback（补默认值），不是错（与整档缺失两分——KD-M1-2）。
+ * @param {object} obj 待校验 manifest 对象
+ * @returns {{ok:boolean, errors:string[], missingKeys:string[]}}
+ */
+export function validateManifest(obj) {
+  const errors = []
+  const missingKeys = []
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return { ok: false, errors: ["manifest 顶层必须是 JSON 对象"], missingKeys }
+  }
+  for (const key of MANIFEST_SCHEMA.keys) {
+    if (!(key in obj)) missingKeys.push(key)
+  }
+  for (const [nested, subkeys] of Object.entries(MANIFEST_SCHEMA.nestedKeys)) {
+    const value = obj[nested]
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+      missingKeys.push(nested) // 整键缺失/非对象 → 与整键缺同语义（整键补默认）
+      continue
+    }
+    for (const sub of subkeys) {
+      if (!(sub in value)) { missingKeys.push(`${nested}.${sub}`); continue } // 子键路径（AC-3 / T3b）
+      // docRoot 子键值形态（F7 / KD-M1-7）：串 | 非空串数组；非法 → 拒（不静默跳过）。
+      if (nested === "docRoot" && !isValidDocRootValue(value[sub])) {
+        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串或非空字符串数组——KD-M1-6 / KD-M1-7）`)
+      }
+      // checkConfig.lineCounts 元素层形态（#546）：数组，元素 = { doc, section } 非空串；非法 → 拒（不静默跳过）。
+      if (nested === "checkConfig" && sub === "lineCounts" && !isLineCountsValue(value[sub])) {
+        errors.push(`checkConfig.lineCounts 值形态非法：${JSON.stringify(value[sub])}（须为数组，元素 = { doc: 非空串, section: 非空串 }——#546）`)
+      }
+    }
+  }
+  // 三族声明键形态（KD-M1-32——fail-closed：非法即 errors，不静默跳过；缺键仍在 missingKeys）。
+  // `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)
+  const idxBad = obj.index === undefined ? null : objErr("index", obj.index)
+  if (idxBad) errors.push(idxBad)
+  else if (obj.index !== undefined) {
+    for (const k of ["codeExtensions", "docExtensions"]) if (obj.index[k] !== undefined) strArrErr(`index.${k}`, obj.index[k])
+    if (obj.index.excludePaths !== undefined && !Array.isArray(obj.index.excludePaths)) {
+      errors.push(`index.excludePaths 值形态非法：${JSON.stringify(obj.index.excludePaths)}（须为数组——非数组 fail-closed；空 ∕ 非串元素由归一剔除）`)
+    }
+    if (obj.index.publicRepos !== undefined && !Array.isArray(obj.index.publicRepos)) {
+      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(" | ")}）`)
+  }
+  if (obj.version !== undefined && (typeof obj.version !== "number" || !Number.isFinite(obj.version))) {
+    errors.push(`version 非法：${JSON.stringify(obj.version)}（须为数值）`)
+  }
+  return { ok: errors.length === 0, errors, missingKeys }
+}
+
+/** 缺键补默认值（module 设计 §2.2 管线）：顶层缺键补默认、嵌套键（docRoot/checkConfig/index/advisor）
+ *  子键补默认（与整键缺同语义）；不覆写既有值。深拷贝默认源（structuredClone）——冻结常量永不外泄引用。
+ *  三族键的非对象值**原样透传**（不洗白——再校验拒，KD-M1-32）。 */
+export function fillDefaults(obj) {
+  const out = structuredClone(DEFAULT_MANIFEST)
+  for (const key of MANIFEST_SCHEMA.keys) {
+    if (!(key in obj)) continue
+    const def = out[key]
+    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 保持默认
+        continue
+      }
+      for (const sub of Object.keys(def)) {
+        if (sub in src) out[key][sub] = src[sub]
+      }
+    } else {
+      out[key] = obj[key]
+    }
+  }
+  return out
+}