@thincoder/core 0.9.5 → 0.10.2

package/agent/write-gate.mjs

@@ -3,7 +3,7 @@
  *
  * v2 唯一增量（模块设计 §2.1）：评审对象 / 被审文件路径来源改读 manifest `docRoot`
  * （去硬编码 `docs/`），token 门（`anyLiveDesignSlot`）与冻结窗口谓词本体继承 v1 零改
- * （KD-M4-3）——本档只承载两个单点：
+ * （KD-M4-3）——本档承载三个单点：
  *
  * 1. `resolveReviewTargetPaths(agent)` —— 评审目标解析单点：读 manifest `docRoot`
  *    产出评审对象 / 被审文件的绝对路径集合（目录级；子键值形态 = 串 | 多根数组，
@@ -15,19 +15,28 @@
  *    KD-M1-12）：CLI make-agent.mjs / VSC setup.mjs 同判）；读错（权限等）→ 上抛不伪装成缺失（manifest.mjs 契约）。
  *    M6 的 `advisor.mjs` design-review 分类分支消费本导出
  *    （KD-M6-1——同源不重复实现；落 dispatch.mjs 会让 advisor 反向 import 门禁簇成环）。
+ *    **按用点形（2026-10-02 收口 · 台账 #828）**：`resolveReviewRootsFor(dir)`——同单点
+ *    非第二实现（按目标目录 ∥ 所属项目根解析；多档锚下各文档按各自项目判定）。
  * 2. `freezeWindowConflict(agent, absPaths)` —— D5 冻结窗口判据组装：被审文件集 =
  *    声明文档集（`inflightDesignReviewConflict` 同源 docAbs 腿）+ 批次档（`run.batchDoc`
- *    腿——评审绑定批档在途时，写批档同样致 stale）。dispatch.mjs / VSC tool-gates.mjs
+ *    腿——评审绑定批档在途时，写批档同样致 stale）。dispatch.mjs
  *    只 import 消费，不再各自直连 `advisor-settle.mjs`。
+ * 3. `batchRecordWriteConflict(agent, depth, absPaths)` —— 批次档写门判据组装（#309 ·
+ *    `AGENT-LOOP-SUBAGENT.md` §6.29.1）：判据与拒绝文案同址（文案字面只出本档）。
+ *    2026-09-29 收窄（台账 #545）：自身批次伴随件（非 `.md` · 同目录 · 词干族 = 三合取）放行——
+ *    批次档本体 ∕ 他批伴随件 ∕ 异目录伴随件照拒；两端取用 = 核 `agent/dispatch.mjs` Phase 1（两端同径）。
  *
  * 继承零改面（本档不碰）：token 门资格判据（anyLiveDesignSlot / validateDesignToken）、
  * 代码路径判定（conventions.mjs 单一权威分类——KD-M4-1 保留为代码路径判定用）。
  */
+import { basename, dirname, resolve } from "node:path"
 import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
 // advisor-settle 无上游依赖本簇（dispatch → write-gate → advisor-settle 单向）。normAbs
 // 权威本体 = review-facts.mjs（第 33 批迁入），advisor-settle re-export；本档再 re-export
 // （指针链非副本），M6 经本档一行 import 取齐。
 import { inflightDesignReviewConflict, normAbs } from "../agent-tools/advisor-settle.mjs"
+// 批次档路径单源（叶档——`BATCH-RECORD.md` §4.15）：批次档写门基底集取 `batchDocBases`。
+import { batchDocBases } from "../agent-tools/batch-paths.mjs"
 export { normAbs }
 
 /** 评审目标解析读的 docRoot 键集（评审对象/被审文件可住的所有文档层——M6 分类据此判定）。 */
@@ -44,14 +53,21 @@ const REVIEW_ROOT_KEYS = ["requirements", "specs", "design", "modules", "batches
  * @returns {string[]} 评审目标目录的绝对路径（去重）
  */
 export function resolveReviewTargetPaths(agent) {
-  const cwd = agent?.cwd ?? process.cwd()
-  // 读错上抛（manifest.mjs:readManifest 契约——不伪装成缺失）；整档缺失/非法 → {ok:false}。
-  const man = readManifest(cwd)
+  return resolveReviewRootsFor(agent?.cwd ?? process.cwd())
+}
+
+/** 同单点之**按用点解析**增量（2026-09-21「参数按用点解析」之裁收口 · 台账 #828）：按**目标目录**
+ *  （其所属项目根——最近带档祖先）解析评审目标根集——多档锚下各文档按各自项目判定。
+ *  @param {string} dir 目标目录（项目根——最近带档祖先）
+ *  @returns {string[]} 评审目标目录绝对路径（去重）
+ */
+export function resolveReviewRootsFor(dir) {
+  const man = readManifest(dir)
   const root = man.ok && man.manifest?.docRoot && typeof man.manifest.docRoot === "object"
     ? man.manifest.docRoot
     : DEFAULT_MANIFEST.docRoot
   const out = []
-  for (const key of REVIEW_ROOT_KEYS) out.push(...docRootPaths(root?.[key], cwd))
+  for (const key of REVIEW_ROOT_KEYS) out.push(...docRootPaths(root?.[key], dir))
   return [...new Set(out)]
 }
 
@@ -85,3 +101,84 @@ export function freezeWindowConflict(agent, absPaths) {
   }
   return null
 }
+
+/** 批次档写门基底集**按 run 记忆化**（每 run 一次 manifest 读——§6.29.1；键 = agent 对象）。
+ *  载体 = WeakMap（agent 回收即随 GC——无跨 run 残留）；cwd 变更即失效重读。
+ *  **歧义锚**（多项目并存 · #828）⇒ 基底 = 候选项目基底**并集**（`batchDocBases` 解析单点——覆盖随之对齐）。 */
+const batchGateBasesMemo = new WeakMap()
+
+/** 比较键（绝对形态归一：`.` 段归位 + 分隔符归一 `/` + win32 大小写归一——§6.29.1 判据）。 */
+const gateKey = (p) => {
+  const s = resolve(String(p)).replace(/\\/g, "/")
+  return process.platform === "win32" ? s.toLowerCase() : s
+}
+
+function memoizedBatchBases(agent, cwd) {
+  const memo = agent && typeof agent === "object" ? batchGateBasesMemo.get(agent) : null
+  if (memo && memo.cwd === cwd) return memo.bases
+  const bases = batchDocBases(cwd)
+  if (agent && typeof agent === "object") batchGateBasesMemo.set(agent, { cwd, bases })
+  return bases
+}
+
+/** 目标是否落基底根内（按路径段——win32 大小写归一；同 `batch-paths.mjs` 越基底判据口径）。 */
+function underBase(targetKey, baseAbs, cwd) {
+  const root = gateKey(normAbs(baseAbs, cwd))
+  return targetKey === root || targetKey.startsWith(root.endsWith("/") ? root : root + "/")
+}
+
+/** 自身批次伴随件判据（三合取——`AGENT-LOOP-SUBAGENT.md` §6.29.1 · 2026-09-29 收窄 · 台账 #545）：
+ *  ① 目标非 `.md`（批次档本体永在门内——含近词干 `<词干>-v2.md`；`.md` 判定大小写不敏感 = fail-closed 侧）；
+ *  ② 目标与绑定档同目录；③ 目标基名以 `<词干>.` 或 `<词干>-` 打头（词干 = 绑定档基名剥 `.md`）。
+ *  入参 = 比较键（gateKey 归一后——win32 大小写归一同覆盖 ②③ 的字面比较）。
+ *  @returns {boolean} 三合取全中 = true（放行面）；余者 false（照拒） */
+function isOwnBatchCompanion(targetKey, boundKey) {
+  const targetBase = basename(targetKey)
+  if (targetBase.toLowerCase().endsWith(".md")) return false // ① 批次档本体（任何 `.md`）永在门内
+  if (dirname(targetKey) !== dirname(boundKey)) return false // ② 同目录（按比较键）
+  const boundBase = basename(boundKey)
+  const stem = boundBase.toLowerCase().endsWith(".md") ? boundBase.slice(0, -3) : boundBase
+  return targetBase.startsWith(stem + ".") || targetBase.startsWith(stem + "-") // ③ 词干族（`.` ∕ `-` 前缀）
+}
+
+/**
+ * 批次档写门判据（#309 · `docs/core/design/AGENT-LOOP-SUBAGENT.md` §6.29.1——containment；
+ * 2026-09-29 收窄 · 台账 #545）：
+ * 工程角色子代理（`depth > 0` ∧ `agent._batchDoc` 在场）对**批次档文件**的写 ⇒ 目标 ≠ 绑定档
+ * **且非绑定批次的伴随件**（见 `isOwnBatchCompanion`）⇒ 冲突（fail-closed；写自己绑定的档 ∥
+ * 自身批次伴随件 = 正常面放行）。比较键 = 绝对路径 + win32 大小写归一。
+ * 界面：depth 0（主 agent——跨档处置是父侧职责）· 无 `_batchDoc`（非工程绑定族）· 主基底外的
+ * 普通文件写 —— 三种形态均不进本门（返回 null，行为零变）。判据集由调用方限定 = `FILE_MUTATORS`
+ * （`file_ops` / 读类不在门内——§6.29.1 边界）。
+ * 拒绝文案**单源 = 本档**（两端直取 `message`——零字面副本）。
+ * 恒零抛（形照 `freezeWindowConflict` 先例——全判据带形态守卫）。
+ * @param {Object} agent — 子代理 agent（读 `_batchDoc` / `cwd`）
+ * @param {number} depth — 执行深度（> 0 = 子代理）
+ * @param {string[]} absPaths — 本次写将触碰的绝对路径集（调用方已 resolve）
+ * @returns {{bound: string, target: string, message: string}|null} 命中 = 冲突信息 / 否则 null
+ */
+export function batchRecordWriteConflict(agent, depth, absPaths) {
+  if (!(depth > 0)) return null
+  const bound = agent?._batchDoc
+  if (typeof bound !== "string" || bound.length === 0) return null
+  const wanted = (absPaths ?? []).filter((p) => typeof p === "string" && p.length > 0)
+  if (wanted.length === 0) return null
+  const cwd = typeof agent?.cwd === "string" && agent.cwd.length > 0 ? agent.cwd : process.cwd()
+  const bases = memoizedBatchBases(agent, cwd)
+  const boundAbs = normAbs(bound, cwd)
+  const boundKey = gateKey(boundAbs)
+  for (const p of wanted) {
+    const target = normAbs(p, cwd)
+    const targetKey = gateKey(target)
+    if (targetKey === boundKey) continue // 写自己绑定的档 = 正常面
+    if (!bases.some((b) => underBase(targetKey, b, cwd))) continue // 非批次档文件（含缺 manifest 的基底外盘面）
+    if (isOwnBatchCompanion(targetKey, boundKey)) continue // 自身批次伴随件 = 放行面（三合取——见判据）
+    return {
+      bound: boundAbs,
+      target,
+      message: `write refused — cross-batch batch-record write: this child is bound to ${basename(boundAbs)}; ${basename(target)} belongs to a different batch. Write only your own bound record and its companion files (the batch tool targets your bound record); the parent agent handles other batch records.`,
+    }
+  }
+  return null
+}
+

package/agent-tools/advisor-async.mjs

@@ -110,7 +110,7 @@ function openDesignRun(agent, key) {
 }
 
 /**
- * Resolve the review instance a launch continues (§11.2 ③ — per-review
+ * Resolve the review instance a launch continues (AGENT-LOOP-ASYNC-POOL.md §6.10 ③ — per-review
  * rounds/prior; reviewId = designId for design reviews, a random id for code).
  *  - design: continue the OPEN instance of the same document set (fix rounds of
  *    a review thread keep its designId and its round/prior); none → new instance.
@@ -172,7 +172,7 @@ export function effectiveAdvisorRound(agent) {
 
 export const ADVISOR_POOL_LIMIT = 4
 
-/** §11.2 advisor 池生效上限（纯——读 agent.poolLimits.advisor——合法 ≥1 整数生效——
+/** AGENT-LOOP-ASYNC-POOL.md §6.10 advisor 池生效上限（纯——读 agent.poolLimits.advisor——合法 ≥1 整数生效——
  *  非法/缺省回退 ADVISOR_POOL_LIMIT——与 subagent 域 resolvePoolLimits 独立不共享
  *  （subagent 两键表不含本键——键表语义不同——POOL-CONFIG-UNIFIED F-2））。 */
 export function resolveAdvisorPoolLimit(raw) {
@@ -185,7 +185,7 @@ export function resolveAdvisorPoolLimit(raw) {
 export function advisorPoolLimitFor(agent) {
   return resolveAdvisorPoolLimit(agent?.config?.agent?.poolLimits)
 }
-/** §11.2 同 scope 守卫（F-5——用户裁①）：同 reviewType+scope 有 running 评审 → true
+/** §6.10 同 scope 守卫（F-5——用户裁①）：同 reviewType+scope 有 running 评审 → true
  *  （拒——running 并行多实例歧义放大——settled 续跑语义不变）。design scope = 文档集键
  *  （docSetKey）；code = 单 code 线程（记录不记路径键——与 openCodeRun 语义一致）。
  *  与池容量守卫独立：容量 = 全局 ≤N——scope = 同 scope ≤1——两关都过才启动。 */
@@ -257,7 +257,7 @@ export function cancelAsyncAdvisor(agent, id, onToken) {
     return { id: key, status: "cancelled", was: "queued" }
   }
   entry.cancelled = true
-  // §20.3 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷）
+  // AGENT-LOOP-SUBAGENT.md §6.12 站点 #11（第 24 批）：定向中止 = cancel（reason 载荷）
   entry.controller?.abort?.({ abortTrigger: "cancel", abortDetail: "advisor-cancel" })
   return { id: key, status: "cancelled" }
 }
@@ -352,13 +352,13 @@ export function refillAdvisorQueue(parent, onToken) {
  * digest/panel/freeze consumers route it like any other settled block.
  * @returns {{ok: true, id: string}} — ack; or {{ok: true, id: string, queued: true,
  *   position: number}} — ED-4 排队 ack（池满 + 异 scope——slot 释放自动起跑）; or
- *   {{error: string}} — scope guard (same reviewType+scope running — §11.2 F-5)
+ *   {{error: string}} — scope guard (same reviewType+scope running — §6.10 F-5)
  *   or invalid ctx.
  */
 export function launchAsyncAdvisor(parent, ctx, launch) {
   const { reviewType, documents, paths, object, designToken, designId, run } = launch
   const limit = advisorPoolLimitFor(parent)
-  // §11.2 same-scope guard（F-5——用户裁①）：同 type+scope 有 running → 拒——与池容量
+  // §6.10 same-scope guard（F-5——用户裁①）：同 type+scope 有 running → 拒——与池容量
   // 守卫独立两关都过才启动——同 scope 不等不排（settled 续跑不变；排队仅异 scope 面）。
   if (runningAdvisorOfScope(parent, reviewType, run?.docSetKey ?? null)) {
     const scopeNote = reviewType === "design"
@@ -398,7 +398,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
   // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md）。
   const ctrl = new AbortController()
   entry.controller = ctrl
-  // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
+  // §6.12 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
   // Ctrl+I 不逐链中止飞行评审）。
   bindChildController(ctrl, buildChildSignal(parent, ctx))
   entry.promise = new Promise((res) => { entry._settle = res })
@@ -416,7 +416,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
       signal: entry.controller.signal,
     }, designToken, documents, paths, object, designId)
       .then((report) => { entry.report = report })
-      // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+      // §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
       .catch((err) => { entry.error = deathLine(err, entry.controller?.signal) })
       .finally(() => {
         // settle 公共收尾单点（ASYNC-RESULT-CONTAINER.md D3——settleAsyncEntry）：日志三连
@@ -430,7 +430,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
           ctx,
           onAccounting: () => {
             const settled = settleAdvisorRun(parent, entry)
-            // §29 fix B：settle 分支输出（清洗/未签发提示）写回 entry.report——digest 原样进。
+            // fix B：settle 分支输出（清洗/未签发提示）写回 entry.report——digest 原样进。
             if (settled.report != null) entry.report = settled.report
           },
         })

package/agent-tools/advisor-settle.mjs

@@ -6,11 +6,11 @@
  *
  * 内容 = 迁入（逐字搬移含注释）+ 本批两处接线：
  *  - `settleAdvisorRun` —— 记账本体零改（轮次 / 陈旧 / token D1 落盘 / prior）；A 族
- *    未完成判定改用单谓词 `advisorIncompleteMarker`（§14.3 消费点 1/2）：design 结算经
+ *    未完成判定改用单谓词 `advisorIncompleteMarker`（ADVISOR-GUARDS.md §1 消费点 1/2）：design 结算经
  *    `settleDesignReview(…, { incomplete })` 未完成即不签发；code 完成守卫同谓词
  *    （旧 `^` 锚首行失败正则退役——六形态语义零丢，含 review_failed 字符串
  *    resolve 形态）；
- *  - `inflightDesignReviewConflict` —— E 族（F17/§14.14）D5 冻结窗口冲突检测：与
+ *  - `inflightDesignReviewConflict` —— E 族（F17/ADVISOR-GUARDS.md §5）D5 冻结窗口冲突检测：与
  *    `reviewIsStale` 同族（同 docAbs / 同 normAbs）、仅扫 running 且未取消的设计条目
  *    （dispatch Phase-1 预闸消费）。
  *
@@ -23,7 +23,7 @@
 import { persistEngTokens } from "../token-ttl.mjs"
 import { settleDesignReview, makeDesignTokenRegex, stripApprovedSuffix } from "./design-token.mjs"
 import { looksLikeReviewOutput, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
-import { isCodePath, loadConventions } from "../conventions.mjs"
+import { isCodePath, loadProjectDeclaration } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
 // 第 33 批（评审失败护栏）：`normAbs` 迁 `review-facts.mjs`（中立模块——陈旧判定与事实面共用同一归一）；
 // 2026-09-18：结算分类 / 结论文案单源迁 `advisor/notice.mjs`（纯函数、零状态、零计数载体）。
@@ -40,7 +40,7 @@ export function mutationSeqOf(agent) {
 }
 
 /** Record a file-mutation commit — bounded ring feeding the stale scan. paths = ABSOLUTE.
- *  唯一记账点（§29 fix A）：dispatch runOne 写执行成功即刻调用（取代批后段 + 中断分支——
+ *  唯一记账点（fix A）：dispatch runOne 写执行成功即刻调用（取代批后段 + 中断分支——
  *  不双计）；mergeChildMutations（子代理合入）是独立事件面。 */
 export function noteMutations(agent, paths) {
   const list = (paths ?? []).filter((p) => typeof p === "string" && p.length > 0)
@@ -68,14 +68,14 @@ export function reviewIsStale(agent, entry) {
     const set = new Set(scope)
     return since.some((m) => (m.paths ?? []).some((p) => set.has(normAbs(p, agent?.cwd))))
   }
-  // Code face = the shared classifier (src/conventions.mjs) — one authority with
+  // Code face = the shared classifier (thincoder-core/conventions.mjs) — one authority with
   // the design gate and the mutation guard (PORTABILITY FR12 / PO-10).
-  const conv = loadConventions(agent?.cwd)
+  const conv = loadProjectDeclaration(agent?.cwd)
   return since.some((m) => (m.paths ?? []).some((p) => isCodePath(normAbs(p, agent?.cwd), conv)))
 }
 
 /**
- * E 族（F17/§14.14 E-3d）——D5 冻结窗口写前拦截的冲突检测：设计评审**在途**（点火 → 结算）
+ * E 族（F17/ADVISOR-GUARDS.md §5 E-3d）——D5 冻结窗口写前拦截的冲突检测：设计评审**在途**（点火 → 结算）
  * 期间，父侧对被审文件集（`docAbs` = 声明文档集，含批次档）的写入会被 dispatch 预闸拒绝。
  * 判据与 `reviewIsStale` **同源**（同一 docAbs / 同一 normAbs）；仅扫 **running 且未取消**
  * 的设计条目（已结算 / 已取消条目不拦——结算后写不再致 stale、取消的结算早退不判）。
@@ -112,7 +112,7 @@ export function inflightDesignReviewConflict(agent, absPaths) {
  *     mirror retired per DESIGN-TOKEN-SETTLEMENT D3) + D1 settle-time slot persist
  *     (persistEngTokens — write failure = settle failure: no registration, no
  *     Approved echo, re-review — 评审 #1);
- *  4. §29 fix B — branch-shaped report output (the caller writes it back to
+ *  4. fix B — branch-shaped report output (the caller writes it back to
  *     entry.report; digest injects the CLEANED form): pass → stripped +
  *     Approved/designId suffix (sync 参照形态); persist-failed → stripped +
  *     "D1: …token could NOT be durably written…" re-review notice (no Approved
@@ -140,7 +140,7 @@ export function settleAdvisorRun(agent, entry) {
   let report = result
   let passed = false
   let persistFailed = false
-  // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；§14.3 消费点 1/2）。
+  // 宿主尾族判定（单谓词——design 结算与 code 守卫共用；ADVISOR-GUARDS.md §1 消费点 1/2）。
   const incomplete = result != null ? advisorIncompleteMarker(String(result)) : null
   // 启动拒绝报告（未发起请求——无评审产出）：第 33 批上移为本结算段**单点**——消费 = ① design
   // 失败分类（neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）② code 守卫 failureVerdict（既有语义零变）。
@@ -199,7 +199,7 @@ export function settleAdvisorRun(agent, entry) {
     // 第 11 批（F16/A3）：失败判定 = 单谓词六 kind（含 review_failed 字符串 resolve 形态）
     // ——旧 `^` 锚正则只认首行形态，漏「时间线 + 尾」；语义零丢（六形态全覆盖）。
     // 另：设计评审的**启动拒绝报告**（未发起请求——无评审产出）同样不得计为评审覆盖
-    // （§14.4 异步结算面判据；与同步工具面 _advisorRefusals 同源前缀；正常链不可达＝防御纵深）
+    // （异步结算面判据；与同步工具面 _advisorRefusals 同源前缀；正常链不可达＝防御纵深）
     // ——判定已上移为本结算段单点（launchRefused，上方）。
     const failureVerdict = (run.reviewType !== "design" && (
       incomplete !== null ||
@@ -209,7 +209,7 @@ export function settleAdvisorRun(agent, entry) {
       agent._calledAdvisorThisRun = true
     }
   } else if (run.reviewType === "design" && entry.designToken && result != null) {
-    // §29 fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
+    // fix B（stale 分支）：陈旧评审不签发——digest 不得展示未注册 token——先剥
     // 方括号回显 + 前置 "评审目标已变更——token 未签发"（不变式——两分支都清洗）。
     const stripped = String(result)
       .replace(makeDesignTokenRegex(entry.designToken, "g"), "")
@@ -217,7 +217,7 @@ export function settleAdvisorRun(agent, entry) {
     report = `评审目标已变更——token 未签发 (review target changed after launch — this review judged a stale state; no design token was issued — re-run the review on the current state)\n\n${stripped}`.trim()
   }
   // Prior of round 2+ = the last REVIEW-LOOKING output (mirror of run.mjs's guard).
-  // F2e (§29.1): strip the engine-approved suffix FIRST — the prior must never
+  // F2e: strip the engine-approved suffix FIRST — the prior must never
   // carry the raw token / designId (exact truncation — zero collateral).
   // 结论块（下方）刻意晚于 prior 归一：prior 只承载评审正文，不携带机制文案。
   if (report && looksLikeReviewOutput(report)) {

package/agent-tools/advisor.mjs

@@ -3,16 +3,17 @@
  * The agent calls this explicitly to get an independent review.
  * The top-level `type` is REQUIRED and must be exactly "code" or "design"
  * (F30 fail-closed — no silent default; ADVISOR-GUARDS.md §2.4).
- * §11.2 (R13 — async advisor): at depth 0 the review launches into the
+ * AGENT-LOOP-ASYNC-POOL.md §6.10 (R13 — async advisor): at depth 0 the review launches into the
  * background pool by DEFAULT (async:true / omitted; async:false forces the
  * blocking review); depth>0 (eng-coder self-review) stays synchronous always.
  */
 import { runAdvisorReview, advisorIncompleteMarker, ADVISOR_LAUNCH_REFUSAL_PREFIX } from "../advisor/run.mjs"
 import { resolveBatchDocPath } from "./batch.mjs"
 // M6（模块设计 §2.1 F3）：评审对象来源读 manifest docRoot（声明面）——复用 M4 的
-// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的 loadConventions/isDocPath 分类；
+// write-gate.mjs 单一权威源（KD-M6-1），替代 v1 的逐档分类面（isDocPath）；
 // normAbs 同源 re-export（指针非副本）。不 import dispatch.mjs（簇间回边，环风险）。
-import { resolveReviewTargetPaths, normAbs } from "../agent/write-gate.mjs"
+import { resolveReviewTargetPaths, resolveReviewRootsFor, normAbs } from "../agent/write-gate.mjs"
+import { owningProject } from "../manifest-discovery.mjs"
 import { sep } from "node:path"
 import {
   generateDesignToken,
@@ -24,6 +25,8 @@ import {
 // F30/F31（2026-09-18 顾问面治理批）：类型门判定 / 拒发串 / 对象标识行——单源 `advisor/notice.mjs`
 // （文案逐字 = ADVISOR-GUARDS.md §2.4 / §2.5）；零计数载体（计数护栏随撤 cap 整体退场）。
 import { typeGateCriterion, buildTypeGateRefusal, scopeSummary, withIdentityLine } from "../advisor/notice.mjs"
+// #15 描述外置：描述文本单点 = tool-docs/advisor.md（DESC 单解析面，缺档抛错语义不变）
+import { DESC } from "../tools/shared.mjs"
 
 // Design-token utilities moved to advisor-async.mjs (the async settle shares
 // them — no wrapper↔runner module cycle); validateDesignToken stays exported
@@ -32,36 +35,14 @@ export { validateDesignToken } from "./advisor-async.mjs"
 
 export const advisorTool = {
   name: "advisor",
-  description:
-    "Run an independent review on your work. " +
-    "type is REQUIRED — exactly one of the two legal values: type='design' reviews design / requirement documents before implementation (pass documents=[...] with the explicit list of doc paths; plus batchDoc when a batch record is in flight); type='code' reviews the code you changed after implementation (pass paths=[...] to scope files/directories — documents=[...] adds acceptance-criteria context). " +
-    "A call without a type (or with a conflicting object.type) is refused — there is no default and no silent fallback. " +
-    "The advisor is an independent read-only sub-agent that explores the codebase, " +
-    "reads files, and traces callers via grep/lsp. " +
-    "For code review: round 1 does a full review, round 2 verifies the agent's fix claims, " +
-    "round 3+ strictly checks only the fix claims — convergence, not divergence. " +
-    "For design review: single-pass review against methodology and requirements. " +
-    "Review criteria come from .thincoder/advisor.md (if present) or sensible defaults. " +
-    "After the review, you MUST produce a response table (see discipline rules for format). " +
-    "If advisor says all clear, call verify. " +
-    "Optionally pass object={type,target,status,reason,exclude} to anchor the review target " +
-    " (the review-object declaration is mechanically injected into the review message); " +
-    "absent → legacy behavior (no injection). " +
-    "ASYNC: at depth 0 the review runs in the BACKGROUND by default " +
-    "(async:true or omitted) — the call returns an ack immediately, the turn ends, and the report " +
-    "arrives automatically in a digest turn when the review finishes; background reviews share one pool — " +
-    "at most agent.poolLimits.advisor concurrent reviews (default 4 — configurable via /config 并发池 or " +
-    "config.json; pool-full and same-scope refusals state the current limit) — launch reviews one at a time. " +
-    "Inside a child (depth>0 — eng-coder self-review) " +
-    "reviews are always synchronous; async:true is rejected there. " +
-    "Returns the review report — the advisor's findings verdict: all-clear (call verify) or a findings list to fix.",
+  description: DESC("advisor"),
   parameters: {
     type: "object",
     properties: {
       type: { type: "string", enum: ["code", "design"], description: "Review type (required): 'design' for design doc review, 'code' for code review. Omitting it is refused — there is no default." },
       async: {
         type: "boolean",
-        description: "Background review: default at depth 0 = true (async — ack now, report via digest); async:false forces the blocking review (mechanism parameter — top-level launches are async by default). depth>0 → always sync (async:true rejected).",
+        description: "Background review: default at depth 0 = true (ack now, report via digest); async:false forces the blocking review. depth>0 → always sync.",
       },
       object: {
         type: "object",
@@ -72,21 +53,21 @@ export const advisorTool = {
           reason: { type: "string", description: "Why this review runs: user-initiated / delivery verification" },
           exclude: { type: "string", description: "Explicit exclusion list — approved/implemented items NOT in this review" },
         },
-        description: "Review-object declaration: mechanically injected at the start of the review user message so the advisor does not re-derive the review target. Absent → no injection (legacy behavior).",
+        description: "Review-object declaration — mechanically injected at the start of the review message. Absent → no injection (legacy behavior).",
       },
       paths: {
         type: "array",
         items: { type: "string" },
-        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reads the files/directories listed here — it has no git tool and never inspects diffs.",
+        description: "Code files or directories to review (for code review). Required unless documents is provided. The advisor reads exactly these — it has no git tool and never inspects diffs.",
       },
       documents: {
         type: "array",
         items: { type: "string" },
-        description: "Explicit list of doc paths to review (design docs, requirements docs, referenced docs). The advisor reviews ONLY these — it does NOT scan git diff. Use for both design review and code review to pass the task's Docs involved list.",
+        description: "Doc paths to review (design / requirements / referenced docs). The advisor reviews ONLY these — no git diff scan. Use for both review types to pass the task's docs list.",
       },
       batchDoc: {
         type: "string",
-        description: "Design review only: path to the batch record currently in flight. Validated WHENEVER passed (any review type) — a value that is not a readable file is refused with an error rather than ignored; for design reviews the reviewer then ALSO gets the `batch` write channel (transition alias `batch_segment`) to record its findings table + VERDICT + counts into §3. Omit when no batch record is in flight — the review then runs unchanged with no write channel (zero regression).",
+        description: "Design review only: the in-flight batch record path — validated whenever passed (unreadable ⇒ refused, not ignored); the reviewer then also gets the `batch` write channel to record its findings + verdict. Omit when no batch record is in flight (no write channel — zero regression).",
       },
     },
     required: ["type"],
@@ -96,7 +77,7 @@ export const advisorTool = {
   outputPanel: true,
   async execute(args, ctx) {
     const agent = ctx.agent
-    // Review-object declaration (§18.8 D-OA3): the PARENT constructs it and the
+    // Review-object declaration (AGENT-LOOP-ASYNC-POOL.md §6.18 D-OA3): the PARENT constructs it and the
     // advisor tool passes it through — mechanical anchoring, not model inference.
     // Any non-object value (string/array/primitive, possibly from a malformed
     // tool call) degrades to null = no injection (legacy calls unchanged).
@@ -137,9 +118,23 @@ export const advisorTool = {
     // elsewhere declares them in PROJECT-MANIFEST.json docRoot).
     if (reviewType === "design" && documents) {
       const roots = resolveReviewTargetPaths(agent).map((r) => r.replace(/[\\/]/g, sep))
+      // 按用点解析（2026-09-21 之裁收口 · 台账 #828）：逐文档按**其所属项目**（最近带档祖先）
+      // 的 docRoot 判定；无主档文档回退会话根集判定（原行为零变）。
+      const ownerRootsCache = new Map()
+      const ownRoots = (abs) => {
+        const owner = owningProject(abs)
+        if (!owner) return []
+        let r = ownerRootsCache.get(owner)
+        if (!r) {
+          r = resolveReviewRootsFor(owner).map((x) => x.replace(/[\\/]/g, sep))
+          ownerRootsCache.set(owner, r)
+        }
+        return r
+      }
       const invalidDocs = documents.filter((doc) => {
         const n = normAbs(doc, agent.cwd).replace(/[\\/]/g, sep)
-        return !roots.some((r) => n === r || n.startsWith(r + sep))
+        const under = (r) => n === r || n.startsWith(r + sep)
+        return !roots.some(under) && !ownRoots(n).some(under)
       })
       if (invalidDocs.length > 0) {
         if (ctx._toolCallId !== undefined) (agent._advisorRefusals ??= new Set()).add(ctx._toolCallId)
@@ -150,7 +145,7 @@ export const advisorTool = {
       }
     }
 
-    // §11.2 (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
+    // §6.10 (R13 — ruling ②-3 A): async gate. Depth-0 defaults to the
     // background pool; depth>0 (eng-coder internal self-review) is ALWAYS sync —
     // an explicit async:true there is rejected, the default never flips.
     // depth 显式校验（归一形态——判定单点：`depth` 取一次 + `asyncRequested` 显式布尔，
@@ -168,13 +163,13 @@ export const advisorTool = {
     }
     const isAsync = asyncRequested || (depth === 0 && args.async !== false)
 
-    // Per-review instance resolution (§11.2 ③ — ruling ②-5 A): fix rounds
+    // Per-review instance resolution (§6.10 ③ — ruling ②-5 A): fix rounds
     // continue the same reviewId (design = the doc-set instance's designId —
     // slot/spawn continuity; code = the newest OPEN instance). The resolution
     // scopes agent._advisorRound/_lastAdvisorOutput so the message builder and
     // the run.mjs cap read THIS instance's round/prior (multi-review isolation).
     const resolved = resolveAdvisorLaunch(agent, reviewType, { documents })
-    // BATCH-RECORD.md §4.2 评审侧批次档门禁 + 实例键绑定（batch_segment 的唯一路径来源）：
+    // BATCH-RECORD.md §4.2 评审侧批次档门禁 + 实例键绑定（评审实例的唯一路径来源）：
     // 口径 = **「若传则须可读」**（空/不可读 → throw；不强制必传——无批次档的在途设计评审
     // 零回归，N5）；绑定落在 resolved.run（评审实例键，与 reviewType/round/designId 同族）——
     // 并发设计评审各绑各档，不用单值会话态（BATCH-RECORD.md §4.7 #6）。
@@ -185,7 +180,7 @@ export const advisorTool = {
     // a clean pass; on pass it is slotted under the instance's designId at settle
     // (sync: right here; async: the settle callback — fix #2). A NEW instance
     // gets a fresh designId; a continued fix round keeps the original one — and a
-    // same-scope re-review after a pass REUSES the session's id (F2h §29.1).
+    // same-scope re-review after a pass REUSES the session's id (F2h).
     const designToken = reviewType === "design" ? generateDesignToken(agent) : null
     const designId = reviewType === "design" ? resolved.designId : null
 
@@ -209,7 +204,7 @@ export const advisorTool = {
       if (ctx._toolCallId !== undefined) {
         (agent._advisorAsyncAcks ??= new Set()).add(ctx._toolCallId)
       }
-      // E（F17/§14.14 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
+      // E（F17/ADVISOR-GUARDS.md §5 E-3c）：设计评审点火回执追加冻结句（代码评审 ack 零改）——窗口下界以
       // 可观察信号表达：报告送达 / 取消前，被审文档（含批次档）零写入。
       const freezeNote = reviewType === "design"
         ? "；D5 冻结窗口：被审文档（含批次档）在报告送达前零写入——在途写入会被拒绝，写入将使本轮结算为陈旧 (pass 不发 token)"
@@ -244,7 +239,7 @@ export const advisorTool = {
       batchDoc: resolved.run.batchDoc ?? null,
     }, designToken, documents, paths, reviewObject, designId)
 
-    // B 启动拒绝（§14.4 #2——稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
+    // B 启动拒绝（稳定前缀）：拒发登记（同池满 / cap 款——不置 called、不耗轮次），
     // 可见报错照常返回（record-results 的 REFUSED 契约）。第 33 批：判定单点——同时供设计
     // 失败分类复用（launchRefused ⇒ neutral——无尝试发生；`ADVISOR-GUARDS.md` §7 失败结算表行 1）。
     const launchRefused = String(result).startsWith(ADVISOR_LAUNCH_REFUSAL_PREFIX)
@@ -265,12 +260,12 @@ export const advisorTool = {
       const settled = settleDesignReview(agent, resolved.run, designToken, result, { incomplete })
       // 撤计数（2026-09-18 用户裁定）：原同步面“分类落账”随会话级计数器整体退场（零载体——F28③）；
       // 失败结论块由**结算出口**产出（异步结算 `settleAdvisorRun`——两轨共用，ADVISOR-GUARDS.md §7）。
-      // F2e (§29.1): the sync prior mirror must not carry the raw echo the runner
+      // F2e: the sync prior mirror must not carry the raw echo the runner
       // stored — overwrite with the clean settled form (exact-suffix truncation).
       if (settled.passed) {
         agent._lastAdvisorOutput = stripApprovedSuffix(settled.output, resolved.run.approvedSuffix)
       } else if (incomplete) {
-        // 未完成 ⇒ 同步 prior 镜像覆写为清洗后输出（防未注册 token 进 prior——§14.3）。
+        // 未完成 ⇒ 同步 prior 镜像覆写为清洗后输出（防未注册 token 进 prior——ADVISOR-GUARDS.md §1）。
         agent._lastAdvisorOutput = settled.output
       }
       return settled.output

package/agent-tools/async-discard.mjs

@@ -13,6 +13,11 @@
  * - 保留 ⟺ 其余——存活条目（controller 未中止——报告沿自动通道到达）/ done-in-pool（回合尾
  *   收集 / 挂起 sweep 消化）/ cancelled（settle cancelled 分支收尾）。
  *
+ * #9 后台 bash 任务族（三族同面并入——D9-7 收尾档②）：bg 条目的「已死」不由 controller 杀达
+ * ——其控制器链只作**判据**（杀 ⟺ 控制器已中止），杀树动作经本收尾面 `spec.dispose` 钩子落
+ * `bash-async.mjs` 杀单点（`killBgTree`）；回合中断（Ctrl+I）经 `bindChildController`
+ * interrupt 豁免不中止控制器 ⇒ 本面零动作（F2 同款豁免——池保留）。
+ *
  * 判据口径（D-AD6）：两接线点**均不传 `ctx`** ⇒ 实走 controller 支（`parentAborted(null, entry)`）
  * ——与对侧有效判据同判（对侧传入的 `ctx` 为死参）；`ctx` 保留为签名备用面（直调用例 / 对侧收敛）。
  * 「controller 已中止 = 条目真死」由 `bindChildController` 单点保证（`async-settle.mjs:88-98`
@@ -36,6 +41,8 @@ import { carrierField, getAsyncPool, parentAborted, writeTombstone } from "./asy
 import { pushReal } from "../context.mjs"
 import { escapeXml } from "../agent/helpers.mjs"
 import { logEvent } from "../log.mjs"
+// #9（后台 bash 任务族——收尾档②）：杀单点（树杀）经 `bash-async.mjs` 落面。
+import { killBgTree } from "./bash-async.mjs"
 
 /** 提醒模板（verbatim 同源 = 对侧 `async-discard.mjs:37-44`；测试断关键子串，不逐行断）。 */
 const subagentReminderText = (n, list) =>
@@ -47,6 +54,11 @@ const advisorReminderText = (n, list) =>
   `[System reminder: ${n} background advisor review(s) were discarded by the user's Stop — their reports will NOT arrive: ${list}.\n` +
   "No design token was issued for a discarded design review; launch the review again if it is still needed.]"
 
+/** #9 后台 bash 任务族提醒模板（同族形态——报告不可达的可视化：进程已杀，全量 log 仍在盘上）。 */
+const bgReminderText = (n, list) =>
+  `[System reminder: ${n} background bash task(s) were killed by the user's Stop — their processes are gone and no digest will arrive: ${list}. ` +
+  "Full output logs remain on disk (paths were given in the start ack).]"
+
 /** 列表词（wasStatus 数据源）：queued → "(was queued — never started)"；其余 "(was running)"。 */
 const wasPhrase = (wasStatus) => (wasStatus === "queued" ? " (was queued — never started)" : " (was running)")
 
@@ -87,6 +99,7 @@ function discardRole(parent, spec, ctx) {
     if (!discardable(entry, ctx)) continue
     out.discarded.push(spec.describe(entry))
     ids.add(String(entry.id))
+    spec.dispose?.(entry) // 族特有处置（#9 bg：杀树——判据成立即条目真死；其余族无此钩子）
     writeTombstone(parent, entry.id, "discarded", spec.roleOf(entry))
     removeFromPool(map, entry.id)
   }
@@ -94,7 +107,11 @@ function discardRole(parent, spec, ctx) {
   if (out.discarded.length === 0) return out // 零丢弃 = 零噪音（零注入 / 零事件）
   spec.pruneQueue?.(parent, ids)
   const list = out.discarded.map(spec.listPhrase).join(", ")
-  pushReal(parent, { role: "user", content: spec.reminder(out.discarded.length, escapeXml(list)) })
+  // 注入面（#94 载体两形吸收）：agent 形（run-stages ∕ 挂起中止接线点——`parent.history` 在）走
+  // `pushReal`（机器 + 人读双线）；**history 数组本体形**（VSC 挂起载体——池挂数组）无注入目标 ⇒
+  // 跳过（与对侧 VSC copy 的 `parent?.history` 守卫同判；§6.20.1「carrier 形无注入目标」先例）
+  // ——墓碑与 `ev:discarded` 照发，仅模型可见提醒缺席（数组形无人读线可达面）。
+  if (parent?.history) pushReal(parent, { role: "user", content: spec.reminder(out.discarded.length, escapeXml(list)) })
   logEvent("ev:discarded", { n: out.discarded.length, ids: out.discarded.map((d) => `${d.role}#${d.id}`).join(", ") })
   return out
 }
@@ -120,6 +137,20 @@ const ADVISOR_SPEC = {
   pruneQueue: (parent, ids) => pruneQueue(parent, ids, "_asyncAdvisorQueue"),
 }
 
+/** #9 后台 bash 任务族 spec（收尾档②）：dispose = 杀树（杀单点 `killBgTree`）+ 标记 discarded
+ *  （settle 面据此不注入——报告不可达）；无队列面（超限 = 起跑显式拒，无排队语义）。 */
+const BG_SPEC = {
+  pool: "bg",
+  describe: (entry) => ({ id: entry.id, role: "bg", command: entry.command }),
+  roleOf: () => "bg",
+  listPhrase: (d) => `bash#${d.id} (\`${d.command}\`)`,
+  reminder: bgReminderText,
+  dispose: (entry) => {
+    entry.discarded = true
+    killBgTree(entry)
+  },
+}
+
 /**
  * 中止收尾（F1–F3）：只清已死子代理条目——写 `discarded` 墓碑 + 出池 + 队列剔除 + 整批一次提醒。
  * @param parent agent 形态（载体双形经 `getAsyncPool` / `writeTombstone` 吸收）
@@ -141,3 +172,15 @@ export function discardAbortedPool(parent, ctx = null) {
 export function discardAbortedAdvisors(parent, ctx = null) {
   return discardRole(parent, ADVISOR_SPEC, ctx)
 }
+
+/**
+ * 中止收尾（#9 后台 bash 任务族——收尾档②）：只清已死条目——逐条**杀树**（判据成立 ⟺ 条目
+ * 控制器已中止；杀单点经 `killBgTree`）+ `discarded` 墓碑 + 出池 + 整批一次提醒；回合中断
+ * （Ctrl+I）不中止控制器 ⇒ 本面零动作（池保留——F2 同款豁免）。
+ * @param parent agent 形态
+ * @param ctx 判据 ctx（接线点不传——controller 支，同上）
+ * @returns {{discarded: Array<{id, role: "bg", command}>, kept: number}}
+ */
+export function discardAbortedBgTasks(parent, ctx = null) {
+  return discardRole(parent, BG_SPEC, ctx)
+}