@thincoder/core 0.9.1

package/ledger-cmd.mjs

@@ -0,0 +1,209 @@
+/**
+ * ledger-cmd.mjs — 台账命令族（查询 = 只读全角色 / 写 = 仅主 agent 装配）+ 工具定义
+ * （M2 模块拆分件——设计档 docs/core/design/modules/ENGINEERING-MODE-V2-MODULE-LEDGER.md §2.3 拆分计划）。
+ *
+ * 接线（设计档 §2.2 命令面接线）：查询命令 ← tools/index.mjs（assembleBuiltinTools 全角色面）；
+ * 写命令 ← agent/family-tools.mjs（assembleFamilyTools 的 depthOnly 分支）——一律**动态 import** 本模块链
+ * （ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧静态 import 会破 W8 契约②）。
+ */
+import { statSync } from "node:fs"
+import { resolve } from "node:path"
+import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES } from "./ledger-db.mjs"
+import { resolveProjectRoot } from "./manifest.mjs"
+
+/** 查询（只读，全角色）：SELECT 行集（status/kind/board 过滤，缺省 = 全部行；id 升序）。库不在 = 空账。 */
+export function ledgerQuery({ cwd, status = null, kind = null, board = null } = {}) {
+  const db = openLedger(cwd)
+  if (!db) return []
+  try {
+    const where = [], args = []
+    if (status) { where.push("status = ?"); args.push(status) }
+    if (kind) { where.push("kind = ?"); args.push(kind) }
+    if (board) { where.push("board = ?"); args.push(board) }
+    return db.prepare(`SELECT * FROM items${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY id`).all(...args)
+  } finally { db.close() }
+}
+
+/** 计数单源（只读，全角色）：COUNT(*) WHERE 未决四态——替代 v1 md 计数面（AC-M2-3）。库不在 = 0。 */
+export function ledgerCount({ cwd } = {}) {
+  const db = openLedger(cwd)
+  if (!db) return 0
+  try {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM items WHERE status IN (${PENDING_STATUSES.map(() => "?").join(",")})`).get(...PENDING_STATUSES)
+    return Number(row.n)
+  } finally { db.close() }
+}
+
+/** 路径 = 存在的**档**？（目录 / 缺失 → false——写门存在性判据用）。 */
+const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
+/** 写门·指针存在性（设计档 §6.1 · 台账 #38 · AC-M2-8）：写命令落盘前判**结果行**——`status ∈
+ *  {在途, 待核销}` 且 `task_book` 非空 ⇒ 文件部分（首个 `§` 前子串，trim）须经基准 `resolve(base, …)`
+ *  指向存在的档；缺文件部分（`§2` / 全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
+ *  判位与迁移表判同层（落盘前）；文案前缀 = 调用函数名（与同函数既有两条文案同款）。
+ *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
+ *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
+ *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。 */
+function assertTaskBookGate(cwd, fnName, status, taskBook) {
+  if (status !== "在途" && status !== "待核销") return
+  if (taskBook == null || taskBook === "") return
+  const part = String(taskBook).split("§")[0].trim()
+  if (!part) throw new Error(`${fnName}：task_book 不可解析（缺文件部分）：${taskBook}`)
+  const base = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+  const abs = resolve(base, part)
+  if (!isFile(abs)) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
+}
+
+/** 新增（写命令，仅主 agent）：INSERT——入待讨论（六态状态机入口）。 */
+export function ledgerAdd({ cwd, row }) {
+  const db = openLedger(cwd, { create: true })
+  try {
+    // 结果行状态 = INSERT 硬编码「待讨论」⇒ 门当下恒不触发（两入口形态统一——为将来「add 带状态」留位）
+    assertTaskBookGate(cwd, "ledgerAdd", "待讨论", row.task_book ?? null)
+    const now = nowIso()
+    const r = db.prepare(`INSERT INTO items (kind, status, title, board, req_doc, task_book, evidence, trigger, created_at, updated_at) VALUES (?, '待讨论', ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(row.kind, row.title, row.board ?? null, row.req_doc ?? null, row.task_book ?? null, row.evidence ?? null, row.trigger ?? null, now, now)
+    return Number(r.lastInsertRowid)
+  } finally { db.close() }
+}
+
+/** 更新（写命令，仅主 agent）：UPDATE——状态迁移前判允许迁移表（不在表内 → 拒，行不变）。 */
+export function ledgerUpdate({ cwd, id, patch }) {
+  const db = openLedger(cwd, { create: true })
+  try {
+    const row = db.prepare("SELECT * FROM items WHERE id = ?").get(id)
+    if (!row) throw new Error(`ledgerUpdate：行 ${id} 不存在`)
+    const to = patch.status ?? row.status
+    if (to !== row.status && !(ALLOWED_MIGRATIONS[row.status] ?? []).includes(to)) {
+      throw new Error(`ledgerUpdate：迁移 ${row.status} → ${to} 不在允许迁移表`)
+    }
+    const nextTaskBook = patch.task_book ?? row.task_book
+    assertTaskBookGate(cwd, "ledgerUpdate", to, nextTaskBook) // 判序：迁移表判 → 本门 → UPDATE
+    const now = nowIso()
+    db.prepare(`UPDATE items SET status = ?, title = ?, board = ?, req_doc = ?, task_book = ?, evidence = ?, trigger = ?, updated_at = ? WHERE id = ?`)
+      .run(to, patch.title ?? row.title, patch.board ?? row.board, patch.req_doc ?? row.req_doc, nextTaskBook, patch.evidence ?? row.evidence, patch.trigger ?? row.trigger, now, id)
+    return { id }
+  } finally { db.close() }
+}
+
+/** 收口（写命令，仅主 agent）：勾销（待核销 → 已核销）/ 撤回（任意态 → 已废弃），事务包裹；归档 = 软删除。 */
+export function ledgerClose({ cwd, id, status }) {
+  if (status !== "已核销" && status !== "已废弃") throw new Error(`ledgerClose：目标态 ${status} ∉ {已核销, 已废弃}`)
+  const db = openLedger(cwd, { create: true })
+  try {
+    db.exec("BEGIN")
+    try {
+      const row = db.prepare("SELECT * FROM items WHERE id = ?").get(id)
+      if (!row) throw new Error(`ledgerClose：行 ${id} 不存在`)
+      if (status === "已核销" && row.status !== "待核销") throw new Error(`ledgerClose：勾销仅限待核销（现态 ${row.status}）`)
+      const now = nowIso()
+      db.prepare("UPDATE items SET status = ?, closed_at = ?, updated_at = ? WHERE id = ?").run(status, now, now, id)
+      db.exec("COMMIT")
+      return { id, status }
+    } catch (e) { db.exec("ROLLBACK"); throw e }
+  } finally { db.close() }
+}
+
+// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
+
+/** 工具 cwd 供值面（缺省 → 当前项目根）。 */
+const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
+
+export const ledgerQueryTool = {
+  name: "ledger_query",
+  description: "台账查询（需求池 / 技术待办）——SQLite 行集，只读、全角色可用。未决四态 = 待讨论 / 待设计 / 在途 / 待核销；已核销 / 已废弃 = 归档态（软删除，行保留）。过滤参数缺省 = 全部行。",
+  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: "按归属板块过滤（需求档文档名）" },
+    },
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    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: "台账计数单源：未决四态（待讨论 / 待设计 / 在途 / 待核销）COUNT(*)，只读、全角色可用。",
+  parameters: {
+    type: "object",
+    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
+  },
+  readonly: true,
+  async execute(args, ctx) {
+    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
+  },
+}
+
+export const ledgerAddTool = {
+  name: "ledger_add",
+  description: "台账新增条目（写命令，仅主 agent）——入待讨论（六态状态机入口）。kind = requirement（需求池）/ tech_todo（技术待办）；trigger = 归批 / 条件 / 认账不排期（可空）。",
+  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: "技术待办触发（可空）" },
+    },
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    const { cwd, ...row } = args
+    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
+    return JSON.stringify({ id, status: "待讨论" })
+  },
+}
+
+export const ledgerUpdateTool = {
+  name: "ledger_update",
+  description: "台账更新条目（写命令，仅主 agent）——状态迁移按六态允许迁移表：待讨论→待设计 / 待设计→在途 / 在途→待核销 / 待核销→已核销 / 任意态→已废弃；表外迁移被拒。status 缺省 = 仅更新字段。",
+  parameters: {
+    type: "object",
+    required: ["id"],
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      id: { type: "number", description: "条目 id" },
+      status: { type: "string", 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: "触发（缺省 = 不变）" },
+    },
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    const { cwd, id, ...patch } = args
+    return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch }))
+  },
+}
+
+export const ledgerCloseTool = {
+  name: "ledger_close",
+  description: "台账收口（写命令，仅主 agent）——勾销：待核销 → 已核销；撤回：任意态 → 已废弃。归档 = 软删除（写 closed_at，行保留）。",
+  parameters: {
+    type: "object",
+    required: ["id", "status"],
+    properties: {
+      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      id: { type: "number", description: "条目 id" },
+      status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 撤回）" },
+    },
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
+  },
+}

package/ledger-db.mjs

@@ -0,0 +1,86 @@
+/**
+ * ledger-db.mjs — 台账 SQLite 连接 / DDL / 枚举常量（M2 模块拆分件——设计档
+ * docs/core/design/modules/ENGINEERING-MODE-V2-MODULE-LEDGER.md §2.3 拆分计划）。
+ *
+ * items 单表 + 三 CHECK 枚举（kind / status / trigger）+ task_book 咬合 CHECK——枚举机械锁死
+ * 靠 DDL（AC-M2-2），不靠应用层 if。归档 = 软删除（状态值，无物理 DELETE——KD-M2-4）。
+ * 本档静态 import node:sqlite ⇒ 消费侧一律动态 import 本模块链（W8 契约②——KD-M2-3）。
+ *
+ * 落点（2026-09-17 用户裁定收正）：台账库**不在项目目录**——住用户数据目录
+ * `~/.thincoder/ledger/<sha1(项目根绝对路径)[:16]>.db`（工作树外、天然不进 git；
+ * 同区先例 = configDir 的 memory.db / tool-results）。项目根仅作**关联键**，不在项目内留任何文件。
+ */
+import { createHash } from "node:crypto"
+import { existsSync, mkdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { DatabaseSync } from "node:sqlite"
+
+import { configDir } from "./config-io.mjs"
+import { resolveProjectRoot } from "./manifest.mjs"
+
+/** 台账库目录（默认 = 用户数据目录；测试注入面 `_setLedgerDirForTest` 覆盖）。 */
+let ledgerDir = join(configDir, "ledger")
+
+/** 测试注入：覆盖台账库目录（同 `_setConfigPathForTest` 先例——测试不碰真实用户目录）。 */
+export function _setLedgerDirForTest(dir) { ledgerDir = dir }
+export function _resetLedgerDirForTest() { ledgerDir = join(configDir, "ledger") }
+
+/** 项目根 → 库路径（稳定键 = sha1(规范化项目根绝对路径) 前 16 位——路径唯一标识，不含分隔符。
+ *  项目根与 manifest 同一判据（git 仓根 / 显式声明容器根）——两端会话键一致）。 */
+export function ledgerDbPath(cwd) {
+  const key = createHash("sha1").update(resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")).digest("hex").slice(0, 16)
+  return join(ledgerDir, `${key}.db`)
+}
+
+/** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
+export const PENDING_STATUSES = ["待讨论", "待设计", "在途", "待核销"]
+
+/** 六态允许迁移表（ledgerUpdate 迁移前判，不在表内 → 拒——规格 ②.2；设计档 §2.1）。 */
+export const ALLOWED_MIGRATIONS = {
+  "待讨论": ["待设计", "已废弃"],
+  "待设计": ["在途", "已废弃"],
+  "在途": ["待核销", "已废弃"],
+  "待核销": ["已核销", "已废弃"],
+  "已核销": ["已废弃"],
+  "已废弃": [],
+}
+
+/** 建表 DDL（幂等——设计档 §2.2 逐字；CHECK 字符串用单引号——KD7 实核）。 */
+const DDL = `
+CREATE TABLE IF NOT EXISTS items (
+  id         INTEGER PRIMARY KEY,
+  kind       TEXT NOT NULL CHECK(kind IN ('requirement','tech_todo')),
+  status     TEXT NOT NULL CHECK(status IN ('待讨论','待设计','在途','待核销','已核销','已废弃')),
+  title      TEXT NOT NULL,
+  board      TEXT,
+  req_doc    TEXT,
+  task_book  TEXT,
+  evidence   TEXT,
+  trigger    TEXT CHECK(trigger IN ('归批','条件','认账不排期') OR trigger IS NULL),
+  created_at TEXT,
+  updated_at TEXT,
+  closed_at  TEXT,
+  CHECK (status NOT IN ('在途','待核销') OR (task_book IS NOT NULL AND task_book <> ''))
+)`
+
+/** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表。
+ *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
+ *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。 */
+export function openLedger(cwd, { create = false } = {}) {
+  const dir = resolve(cwd ?? ".")
+  const file = ledgerDbPath(dir)
+  if (!existsSync(dir)) {
+    throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
+  }
+  if (!existsSync(file) && !create) return null
+  try { mkdirSync(ledgerDir, { recursive: true }) } catch { /* 已存在 / 并发建目录竞争——忽略 */ }
+  const db = new DatabaseSync(file)
+  try { db.exec(DDL) } catch (e) {
+    db.close()
+    throw new Error(`台账库打开失败：${file}（${e.message}）`)
+  }
+  return db
+}
+
+/** 时间戳统一口径（ISO 字符串——行龄源 = 时间戳差值，KD-M2-6）。 */
+export const nowIso = () => new Date().toISOString()

package/ledger-surface.mjs

@@ -0,0 +1,76 @@
+/**
+ * ledger-surface.mjs — 台账可见面（核内结构归位；CORE-UNIFICATION §2.5 #174
+ * 「融合：取一侧 + 渲染面按端注入」）。
+ *
+ * 来源 = `thincoder-cli/src/tui/ledger-surface.mjs`（CLI 住 `tui/`、VSC 住 `extension/`；
+ * VSC 头注自述同构）——逐字随迁，**渲染面收核为注入**：原档 `import { C } from "./ansi.mjs"`
+ * 是 TUI 专用件的颜色表 ⇒ ④ 端差，改由调用方传入 `colors`（未注入 ⇒ 空对象，输出纯文本，
+ * 核内零端名分支——契约 5 / 10）。
+ *
+ * 三面：① 启动行（首扫、**任一项目可动作**才出——明细行集每项目一行）② 变化行（老化首次
+ * 越线 / 池达阈值——一次性去重 + **送达门**：未送达不记账）③ 状态位（`state.ledger`——L1
+ * 常驻标记，渲染端消费；**不受启动行门约束**——F2 按标记态照显）。
+ * 只读台账；唯一写面 = 去重档（`~/.thincoder/ledger-notify.json`）。
+ */
+import { buildScan, detailScans, discoverFamily, formatDetailLine, formatMarker, loadNotifyState, NOTIFY_FILE, notifyKey, planChangeLines, REFRESH_MS, saveNotifyState } from "./ledger.mjs"
+
+/** 单次扫描（直驱面——timer 包装见 `startLedgerSurface`）。
+ *  `startup=true` = 会话首扫（补启动行；变化行在前、明细行在后）。
+ *  `colors` = 端注入的渲染色表（`{ warn, dim }`）；未注入 ⇒ `{}`（`undefined` 色值 = 纯文本）。 */
+export function runLedgerScan({ state, agent = null, anchor = null, notifyFile = NOTIFY_FILE, pushLine = () => {}, render = () => {}, startup = false, colors = {} } = {}) {
+  const base = anchor ?? agent?.cwd ?? process.cwd()
+  const family = discoverFamily(base)
+  const scans = []
+  for (const p of family.projects) {
+    try { scans.push(buildScan({ cwd: p.root })) } catch { /* 台账不可读 → 该项目跳过（余者照常——N1/T110①） */ }
+  }
+  const current = family.current ? scans.find((s) => s.root === family.current.root) ?? null : null
+  const notify = loadNotifyState(notifyFile)
+  const plans = scans.map((s) => ({ s, plan: planChangeLines(notify.ledgers[notifyKey(s.ledger)], s) }))
+  const changeLines = plans.flatMap(({ plan }) => plan.lines)
+  const showStartup = startup && scans.some((s) => s.actionable)
+  const rows = showStartup
+    ? [...changeLines, ...detailScans(scans, current).map((s) => ({ text: formatDetailLine(s), warn: s.actionable }))]
+    : changeLines
+  let delivered = true
+  for (const line of rows) {
+    try { pushLine(line.text, line.warn ? colors.warn : colors.dim) } catch { delivered = false; break }
+  }
+  // 送达门（F5）：有事件行 → 仅在送达后记账；无事件行 → 仅状态确有变化时静默同步（跌回 false 即重置）
+  const changed = plans.some(({ s, plan }) => {
+    const prev = notify.ledgers[notifyKey(s.ledger)]
+    return !prev || JSON.stringify(prev.aged ?? []) !== JSON.stringify(plan.next.aged) || Boolean(prev.threshold) !== plan.next.threshold
+  })
+  if (changeLines.length ? delivered : changed) {
+    const ledgers = { ...notify.ledgers }
+    for (const { s, plan } of plans) ledgers[notifyKey(s.ledger)] = { ...plan.next, updatedAt: Date.now() }
+    saveNotifyState(notifyFile, { version: 1, ledgers })
+  }
+  state.ledger = { marker: current ? formatMarker(current) : null, warn: Boolean(current && current.aged > 0), scannedAt: Date.now() }
+  render()
+}
+
+/** 挂载：首扫（`setImmediate`——不抢首帧）+ 周期（`REFRESH_MS`；`state.processing` 期间跳过本轮）。
+ *  端注入的渲染面（`ctx.colors`）与推送面（`ctx.pushLine` / `ctx.render`）照传。 */
+export function startLedgerSurface(ctx = {}) {
+  let disposed = false
+  let timer = null
+  const tick = (startup) => {
+    if (disposed) return
+    if (!startup && ctx.state?.processing) return // 扫描不打断回合帧
+    try { runLedgerScan({ ...ctx, startup }) } catch { /* 可见面尽力——不崩（N1） */ }
+  }
+  setImmediate(() => {
+    if (disposed) return
+    tick(true)
+    timer = setInterval(() => tick(false), REFRESH_MS)
+    timer.unref?.()
+  })
+  return {
+    dispose() {
+      disposed = true
+      if (timer) clearInterval(timer)
+      timer = null
+    },
+  }
+}

package/ledger.mjs

@@ -0,0 +1,202 @@
+/**
+ * ledger.mjs — 台账（需求池 / 技术待办）单一权威源（M2 模块——设计档
+ * docs/core/design/modules/ENGINEERING-MODE-V2-MODULE-LEDGER.md §2.2）。
+ *
+ * v1 md 台账（docs/TODO.md 扫描器）→ SQLite 单表（ledger.db，项目级、不进 git）：六态 CHECK 机械
+ * 锁死、COUNT 单源计数、事务保证收口原子、归档 = 软删除。行龄源 = SQLite 时间戳（无 git blame）。
+ *
+ * 面：① 命令族（查询 = 只读全角色 / 写 = 仅主 agent——接线见 tools/index.mjs 与 agent/family-tools.mjs）
+ * ② 族发现（findProject / discoverFamily——标记 = ledger.db）③ scan 组装（buildScan——行集 + ledgerCount
+ * → scan 对象，形状契约 = pool/tech/aged/thresholdReached/actionable/root/name/ledger）
+ * ④ 通知去重（送达门 + 一次性去重——去重档跨会话、跨端共享）⑤ 格式 helper（行文本逐字契约）。
+ *
+ * W8 契约②：ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧一律**动态 import** 本档（禁止静态 import）。
+ */
+import { mkdirSync, opendirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+import { configDir } from "./config.mjs"
+import { ledgerDbPath, PENDING_STATUSES } from "./ledger-db.mjs"
+import { ledgerQuery } from "./ledger-cmd.mjs"
+
+/** 老化阈值（天——口径 = 需求档；`days` 参数可覆盖）。 */
+export const AGING_DAYS = 30
+/** 「可开批」阈值：同一板块（需求类条目 board 列）未决 ≥ 2。 */
+export const THRESHOLD_BOARD = 2
+/** 「可开批」阈值：需求池未决 ≥ 3。 */
+export const THRESHOLD_POOL = 3
+/** 刷新周期（N2 实现常量；VSC 端另有换项目事件触发）。 */
+export const REFRESH_MS = 120000
+/** 变化行去重档（跨会话、跨端共享——需求档 §1.18 F5；configDir 先例 = crash-reports 同区）。 */
+export const NOTIFY_FILE = join(configDir, "ledger-notify.json")
+/** 空族提示（仅命令面——运行时面静默，N1 / 设计档 §2.30.3.3）。 */
+export const EMPTY_FAMILY_LINE = "台账：未发现台账。"
+
+/** 条目归一化文本 = 条目键（去 `- [ ] ` 前缀 + 去首尾空白 + 连续空白折叠单空格）。
+ *  位置无关（位移 / 他条编辑稳定）；自身文本变更 = 键变（最坏一次重报）。§2.30.3.2。 */
+export function normalizeEntry(text) {
+  return text.replace(/^- \[[ x]\]\s+/, "").trim().replace(/\s+/g, " ")
+}
+
+/** 条目标题：首个 `**…**` 段；无粗体段 → 归一化文本前 20 字（超出加 `…`）。§2.30.3.3 L3。 */
+export function entryTitle(text) {
+  const m = /\*\*(.+?)\*\*/.exec(text)
+  if (m) return m[1]
+  const norm = normalizeEntry(text)
+  return norm.length > 20 ? norm.slice(0, 20) + "…" : norm
+}
+
+const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
+/** 向上（含自身）最近的已注册台账项目根 → {root, ledger} / null（F4——CLI 锚 = cwd；
+ *  标记 = 用户数据目录里以该项目路径为键的台账库——项目目录内不落任何标记文件）。 */
+export function findProject(anchor) {
+  let dir = resolve(anchor)
+  for (;;) {
+    const ledger = ledgerDbPath(dir)
+    if (isFile(ledger)) return { root: dir, ledger }
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/** 同级枚举上限（N2 成本有界：父目录超此规模 = 缓存 / 临时等非仓族形态 → 退化空集，只显当前项目）。 */
+export const MAX_SIBLING_SCAN = 100
+
+/** 目录下已注册台账的直接子目录（目录名升序；不可读 → []；**惰性枚举 + 上限**——大目录零全量扫描）。 */
+function ledgerChildren(dir) {
+  const out = []
+  let handle
+  try { handle = opendirSync(dir) } catch { return out }
+  try {
+    let n = 0
+    for (;;) {
+      const ent = handle.readSync()
+      if (!ent) break
+      if (++n > MAX_SIBLING_SCAN) return []
+      if (!ent.isDirectory()) continue
+      const root = join(dir, ent.name)
+      const ledger = ledgerDbPath(root)
+      if (isFile(ledger)) out.push({ root, ledger })
+    }
+  } catch { /* 读中断 → 已得子集（尽力而为） */ }
+  finally { try { handle.closeSync() } catch { /* 已关 */ } }
+  return out.sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0))
+}
+
+/** 项目族发现：{current, projects}——projects = current + 其同级含台账库目录（**发现序：current 在前**，
+ *  其余按目录名升序）；current 缺（容器目录，K6）→ 上下文目录向上最近「含台账子目录」者取其子目录。 */
+export function discoverFamily(anchor) {
+  const current = findProject(anchor)
+  if (current) {
+    const siblings = ledgerChildren(dirname(current.root)).filter((p) => p.root !== current.root)
+    return { current, projects: [current, ...siblings] }
+  }
+  let dir = resolve(anchor)
+  for (;;) {
+    const kids = ledgerChildren(dir)
+    if (kids.length) return { current: null, projects: kids }
+    const parent = dirname(dir)
+    if (parent === dir) return { current: null, projects: [] }
+    dir = parent
+  }
+}
+
+/** scan 组装（SQLite 行集 + 计数单源 → scan 对象）——形状契约（设计档 §2.2）：pool/tech/aged/
+ *  agedKeys/agedTitles/thresholdReached/boards/actionable/root/name/ledger。行龄 = 时间戳
+ *  （updated_at ?? created_at 距今 > days；未知不计——零假阳降级，同 v1 行龄未知口径）。
+ *  `now`/`days` = 注入面（确定性用例——替代 v1 ageOf git 注入面）。 */
+export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
+  const rows = ledgerQuery({ cwd })
+  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")
+  const candidates = techEntries.filter((r) => !r.trigger)
+  const aged = candidates.filter((r) => {
+    const t = r.updated_at ?? r.created_at
+    return t != null && (now - Date.parse(t)) / 86400000 > days
+  })
+  const boards = new Map()
+  for (const e of poolEntries) {
+    const key = e.board ?? (e.req_doc ? basename(String(e.req_doc).split(/\s+/)[0]) : null)
+    if (key) boards.set(key, (boards.get(key) ?? 0) + 1)
+  }
+  const thresholdReached = poolEntries.length >= THRESHOLD_POOL || [...boards.values()].some((n) => n >= THRESHOLD_BOARD)
+  const root = resolve(cwd)
+  return {
+    name: basename(root), root, ledger: ledgerDbPath(root),
+    pool: poolEntries.length, tech: techEntries.length, aged: aged.length,
+    agedKeys: aged.map((r) => normalizeEntry(r.title)), agedTitles: aged.map((r) => entryTitle(r.title)),
+    thresholdReached, boards, actionable: aged.length > 0 || thresholdReached,
+  }
+}
+
+/** L1 状态标记（逐字——§2.30.3.3）。 */
+export function formatMarker(scan) {
+  return scan ? `台账 ${scan.pool}·${scan.tech}` : null
+}
+
+/** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`）。 */
+export function formatDetailLine(scan) {
+  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}`
+}
+
+/** L3 变化行·老化（titles = 新增老化条目标题；> 3 条时第三项后接 `；…`）。 */
+export function formatAgingLine(scan, titles) {
+  return `台账变化：${scan.name} 老化首次越线 ${titles.length} 条（超 30 天未处置）：${titles.slice(0, 3).join("；")}${titles.length > 3 ? "；…" : ""}`
+}
+
+/** L4 变化行·阈值。 */
+export function formatThresholdLine(scan) {
+  return `台账变化：${scan.name} 需求池达阈值（${scan.pool} 条）— 可开批`
+}
+
+/** 明细行集 = {current} ∪ {可动作项目}（发现序——current 在前，其余按目录名升序；同项去重）。 */
+export function detailScans(scans, current) {
+  const out = []
+  if (current) out.push(current)
+  for (const s of scans) if (s !== current && s.actionable) out.push(s)
+  return out
+}
+
+/** 变化行规划（纯函数）：{lines:[{text,warn}], next:{aged,threshold}}（去重口径 §2.30.3.2）。 */
+export function planChangeLines(prev, scan) {
+  const p = prev && typeof prev === "object" ? prev : {}
+  const before = new Set(Array.isArray(p.aged) ? p.aged : [])
+  const freshTitles = scan.agedKeys.map((k, i) => (before.has(k) ? null : scan.agedTitles[i])).filter((t) => t != null)
+  const lines = []
+  if (freshTitles.length) lines.push({ text: formatAgingLine(scan, freshTitles), warn: true })
+  if (scan.thresholdReached && !p.threshold) lines.push({ text: formatThresholdLine(scan), warn: true })
+  return { lines, next: { aged: scan.agedKeys, threshold: scan.thresholdReached } }
+}
+
+/** 去重档键 = 台账库绝对路径·正斜杠 + **盘符大写**（跨端同规则——CLI 的 `process.cwd()` 盘符大写、
+ *  VSC 的 `uri.fsPath` 小写（`session-slots.mjs` `normalizeCwd` 同一契约——session / checkpoint /
+ *  trace 跨端共享即赖此）；CLI 写的键 VSC 须逐字认得）。 */
+export function notifyKey(ledger) {
+  return resolve(ledger).replace(/\\/g, "/").replace(/^([a-z]):/, (_, d) => `${d.toUpperCase()}:`)
+}
+
+/** 去重档读（缺失 / 坏 JSON → 空态——N1 降级不崩）。 */
+export function loadNotifyState(file = NOTIFY_FILE) {
+  try {
+    const j = JSON.parse(readFileSync(file, "utf8"))
+    if (j && typeof j === "object" && j.ledgers && typeof j.ledgers === "object") return { version: 1, ledgers: j.ledgers }
+  } catch { /* 缺失 / 坏档 → 空态 */ }
+  return { version: 1, ledgers: {} }
+}
+
+/** 去重档写（temp + rename 防撕裂；写失败静默返回 false——唯一写面，仅送达后调）。 */
+export function saveNotifyState(file, state) {
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    const tmp = `${file}.tmp-${process.pid}`
+    writeFileSync(tmp, JSON.stringify(state), "utf8")
+    renameSync(tmp, file)
+    return true
+  } catch { return false }
+}
+
+// ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3） ──
+export { ALLOWED_MIGRATIONS, ledgerDbPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest } from "./ledger-db.mjs"
+export { ledgerAdd, ledgerAddTool, ledgerClose, ledgerCloseTool, ledgerCount, ledgerCountTool, ledgerQuery, ledgerQueryTool, ledgerUpdate, ledgerUpdateTool } from "./ledger-cmd.mjs"