@thincoder/core 0.10.9 → 0.10.11

package/model-context.mjs

@@ -0,0 +1,98 @@
+/**
+ * model-context.mjs — 模型上下文解析的运行时事实面（`PROVIDER.md` §6.15 · 五级链 L1/L3 两层来源）。
+ *
+ * 组成三件：模块级 `baseURL → (归一 id → 条目表)` 只读缓存 · 键归一（末段 + 小写）· 值域校验
+ * （`positiveInt`）。零本地 import（只碰运行时内建）⇒ 零 import 环。
+ *
+ *  - L1 `providers[].modelContext[模型]`（人工声明，**K** 单位）→ `manualContextK`（返 K）
+ *  - L3 `/models` 自报窗口（**token**）→ `listedContextTokens`（返 token）
+ * 单位进函数名：乘点唯一在 `model-specs.mjs`（L1 ∥ L2 ×1024，L3 不乘）——读函数名即知单位。
+ *
+ * 缓存触发 = 既有列表拉取（写面只在 `provider/list-models.mjs` 成功返回时调 `recordListedContext`）：
+ * 六个消费面本来就要拉列表，顺带把窗口留在核里，**零新增请求**（D2）。读面是同步纯查表：未命中返
+ * `null`、调用侧落下一层，永不抛、永不等待（R28）。
+ *
+ * 键归一 = 末段 + 小写（规则单源 = `PROVIDER.md` §6.9）：`qwen/ZHIPU/GLM-5.3` ⇒ `glm-5.3`。
+ * **本面算子 = 末段相等**（不是前缀）：用户键 `glm-5.3` 不命中模型 `glm-5.3-flashx`（R29③）。
+ * 同侧两条键归一后相撞 = 同一模型的两种写法 ⇒ **命中即取**（对象键序 ∥ 列表序第一条，不排序、
+ * 不比较；R29④）——不拒、不告警、不落下一层。
+ */
+
+/** 值域校验单点（L1 K ∥ L3 token 共用谓词）：正整数才收，其余一律 `null`（= 未提供）。
+ *  只认 `number`——写面交互输入是字符串，须先 `Number(String(v).trim())` 再判（调用侧责任）。 */
+export function positiveInt(v) {
+  return typeof v === "number" && Number.isInteger(v) && v > 0 ? v : null
+}
+
+/** 模型名归一（末段 + 小写——§6.9 三面同一把尺子）。非串归一等价空串（脏载不抛）。 */
+export function normalizeModelKey(name) {
+  const m = (typeof name === "string" ? name : "").toLowerCase()
+  const slash = m.lastIndexOf("/")
+  return slash >= 0 ? m.slice(slash + 1) : m
+}
+
+function normalizeBaseURL(baseURL) {
+  return (typeof baseURL === "string" ? baseURL : "").replace(/\/+$/, "")
+}
+
+/** 告警一次（模块级去重键）——本模块唯一告警出口；去重键决定「一次」的射程。 */
+const warned = new Set()
+export function warnContextOnce(key, message) {
+  if (warned.has(key)) return
+  warned.add(key)
+  console.warn(message)
+}
+
+// ─── L3 缓存：归一 baseURL → (归一 id → 条目表) ───────────────────────────────────
+// 键 = 归一后的 baseURL（列表是端点的事实，不是本地别名的事实——探针目标常缺 name）。
+// 写 = 每次成功拉取**整条替换**（不合并）：列表不再报某模型 ⇒ 该模型回到 L4；拉取失败不写、
+// 不清空上次成功值（上次自报比静态表更接近事实）。归一索引在写时建好 ⇒ 读面是一次 `Map` 查表
+// （同键多条目 = 末段相撞，读面取列表序第一条——R29④）。
+const listedByEndpoint = new Map()
+
+/** L3 写面（唯一入口）：记录一个端点的列表自报窗口表。`entries` = `[id, tokens]` 可迭代
+ *  （Map ∥ 数组）；非法值当场丢弃（= 该模型列表未报）。空表也写入——「这次一条都没报」是事实。 */
+export function recordListedContext(baseURL, entries) {
+  const base = normalizeBaseURL(baseURL)
+  if (!base) return
+  const index = new Map()
+  for (const [id, tokens] of entries ?? []) {
+    if (typeof id !== "string" || !id) continue
+    const value = positiveInt(tokens)
+    if (value === null) continue
+    const key = normalizeModelKey(id)
+    if (!key) continue
+    const bucket = index.get(key)
+    if (bucket) bucket.push({ id, tokens: value })
+    else index.set(key, [{ id, tokens: value }])
+  }
+  listedByEndpoint.set(base, index)
+}
+
+/** L3 读面：列表自报窗口（token，不乘）。未报 ⇒ `null`（落下一层）；同端点两 id 末段相撞
+ *  ⇒ 取列表序第一条即用（同一模型，R29④——不排序、不比较、不告警）。 */
+export function listedContextTokens(provider) {
+  const base = normalizeBaseURL(provider?.baseURL)
+  const target = normalizeModelKey(provider?.model)
+  if (!base || !target) return null
+  const bucket = listedByEndpoint.get(base)?.get(target)
+  return bucket ? positiveInt(bucket[0].tokens) : null
+}
+
+/** L1 读面：`providers[].modelContext[模型]` 人工声明（K 单位）。未声明 ∥ 值非法 ⇒ `null`
+ *  （落下一层）；两条键归一后相同 = 同一模型的两种写法 ⇒ 取对象键序第一条即用（R29④——
+ *  不排序、不比较、不告警）。值非法在装载期已告警一次（`config.mjs`），此处只判不告（热路径）。 */
+export function manualContextK(provider) {
+  const table = provider?.modelContext
+  if (!table || typeof table !== "object" || Array.isArray(table)) return null
+  const target = normalizeModelKey(provider?.model)
+  if (!target) return null
+  for (const [key, value] of Object.entries(table)) if (normalizeModelKey(key) === target) return positiveInt(value)
+  return null
+}
+
+/** 测试缝：清空 L3 缓存 + 告警去重（单元档用；生产零调用）。 */
+export function _resetModelContextForTest() {
+  listedByEndpoint.clear()
+  warned.clear()
+}

package/model-specs.mjs

@@ -7,8 +7,10 @@
  * config-presets.mjs — the core's single preset face, re-exported by config.mjs.)
  */
 
+import { listedContextTokens, manualContextK, warnContextOnce } from "./model-context.mjs"
+
 /**
- * Known model capability spec table (prefix match, longer first).
+ * Known model capability spec table (prefix match within the model's last "/"-segment, longer first).
  * Used for compaction threshold derivation, continuation protocol selection, and capability-aware optimization.
  *
  * context:           context window (tokens)
@@ -42,8 +44,6 @@ const MODEL_SPECS = [
   ["deepseek-v4-flash-vision-exp", { context: 1_000_000, maxOutput: 384_000, thinking: true,  prefixMode: true,  thinkApi: "type", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"], tempRange: [0, 2], multimodal: true }],
   // Kimi series
   ["kimi-k3",           { context: 1_000_000, maxOutput: 131_072, thinking: true,  partialMode: true, multimodal: true,  thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
-  // Qwen router prefixes model IDs with provider namespace: kimi/kimi-k3 → kimi-k3 (IK7K4V)
-  ["kimi/kimi-k3",      { context: 1_000_000, maxOutput: 131_072, thinking: true,  partialMode: true, multimodal: true,  thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
   // Kimi For Coding endpoint uses the short model ID "k3" (same specs as kimi-k3) — IK5VGJ
   ["k3",                { context: 1_000_000, maxOutput: 131_072, thinking: true,  partialMode: true, multimodal: true,  thinkApi: "effort", reasoningEcho: "required", reasoningEffortEnum: ["low", "high", "max"] }],
   // kimi-for-coding / k3-256k / kimi-for-coding-highspeed（Kimi For Coding 端点三名 · 2026-09-25 批 §14.2 #7-9 · 活测 = §1.4 服务端 200 /models）：
@@ -249,36 +249,32 @@ const MODEL_SPECS = [
 ]
 const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000 }
 
-/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models.
+/** 查表规则（单源 = PROVIDER.md §6.9 · 用户 2026-10-23 17:34 裁定「匹配 / 拆分以后的最后一段」）：
  *
- * Vendor-namespace stripping (2026-09-04；末段形 2026-10-10——用户裁定「只取最后一段」)：第三方
- * token 市场（roapi/new-api/one-api/aiproxy 聚合网关）惯例在模型名前加厂商前缀（zhipu/glm-5.3、
- * openai/gpt-4o），链式网关下可叠多段（测试服务器 qwen/ZHIPU/GLM-5.3）。完整名未命中且含 "/" 时，
- * 取最后一个 "/" 之后的段再按前缀匹配一次——单段 ZHIPU/GLM-5.3 → glm-5.3（两法等价）、多段
- * qwen/ZHIPU/GLM-5.3 → glm-5.3 均命中真实规格，不再降级 128K 默认。kimi/kimi-k3 的显式 alias
- * 行保留为文档锚（发送路径 provider.core isRouter 依赖含 "/" 判定），通用机制已覆盖同类。 */
+ * 模型名匹配 = **末段唯一**：按 "/" 拆开只拿最后一段查表（单段名末段 = 自身），段内仍按前缀匹配
+ * （`glm-5.3-flashx` 命中 `glm-5.3` 行）。完整名**不再先扫**——旧法把 `glm-5.3/zzz` 误判成
+ * `glm-5.3`（1M 上下文 ⇒ 压缩永不触发 ⇒ 溢出）；新法取末段 `zzz` ⇒ 未命中 ⇒ DEFAULT_SPEC + 告警。
+ * 聚合网关惯例 `vendor/model`（roapi/new-api/one-api/aiproxy）因此天然命中：`zhipu/glm-5.3` /
+ * 链式 `qwen/ZHIPU/GLM-5.3` ⇒ `glm-5.3`。末段为空（`foo/`）⇒ 未命中（空串不做匹配）。 */
 const warnedModels = new Set() // warn once per model name — spec lookup runs on every request (hot path)
 // Pre-sorted once at module scope — spec lookup runs on every request (agent, provider core,
 // context, auto-think, TUI rendering); re-sorting per call was wasteful.
 const SORTED_SPECS = [...MODEL_SPECS].sort((a, b) => b[0].length - a[0].length)
 
-/** Single table lookup shared by specForModel / specMatch — prefix match (case-insensitive)
- *  with vendor-namespace stripping. Returns null on a miss (DEFAULT_SPEC is the caller-side
- *  fallback and is deliberately NOT returned here — `matched` needs the miss itself).
+/** Single table lookup shared by specForModel / specMatch — prefix match (case-insensitive) on the
+ *  model's LAST "/"-segment only (末段唯一 · PROVIDER.md §6.9). The full name is NOT scanned first:
+ *  `glm-5.3/zzz` takes `zzz` and misses (the old full-name-first scan mis-hit `glm-5.3`).
+ *  Returns null on a miss (DEFAULT_SPEC is the caller-side fallback and is deliberately NOT
+ *  returned here — `matched` needs the miss itself).
  *  非串 model（外端脏载 / 手工档）归一等价空串 ⇒ 未命中 ⇒ 调用侧 DEFAULT_SPEC（#638 查表全性：
  *  下游无类型门——`.toLowerCase` 只认串，非串归一后本函数恒 total，同 providerSpec 文档句）。 */
 function lookupSpec(model) {
   const m = (typeof model === "string" ? model : "").toLowerCase()
-  for (const [prefix, spec] of SORTED_SPECS) {
-    if (m.startsWith(prefix.toLowerCase())) return spec
-  }
-  // Vendor-namespace strip: take the LAST "/"-separated segment — retry the prefix match on it.
   const slash = m.lastIndexOf("/")
-  if (slash > 0) {
-    const bare = m.slice(slash + 1)
-    for (const [prefix, spec] of SORTED_SPECS) {
-      if (bare.startsWith(prefix.toLowerCase())) return spec
-    }
+  const bare = slash >= 0 ? m.slice(slash + 1) : m   // 末段唯一；单段名 = 自身
+  if (!bare) return null                             // 末段为空 ⇒ 未命中（空串不做前缀匹配）
+  for (const [prefix, spec] of SORTED_SPECS) {
+    if (bare.startsWith(prefix.toLowerCase())) return spec
   }
   return null
 }
@@ -312,27 +308,104 @@ export function specMatch(model) {
   return { spec: DEFAULT_SPEC, matched: false }
 }
 
+/** Context window 展示串，**收 token**（核单源——三端读面同一格式器出词，R31④）：`128K` ∥ `1M`。
+ *  本批由 CLI 私有 `fmtContextK` 上提——三端各自拼串会漂。服务链上 L3/L4 值（token）的展示；
+ *  人工声明（K）的展示走 `formatDeclaredContextK`，一个换算方向一个入口，不混用。 */
+export function formatContextK(tokens) {
+  if (tokens >= 1_000_000) return `${Math.round(tokens / 1_048_576)}M`
+  return `${Math.round(tokens / 1024)}K`
+}
+
+/** 人工声明上下文的展示串，**收 K**（`modelContext` ∥ 旧键 `context` 的存储单位）：`128` ⇒ `128K`、
+ *  `1024` ⇒ `1M`。K→token 的展示换算**只此一处**（内部转 token 再交给 `formatContextK`）——三端读面
+ *  把已声明原值直接交进来，不自己换算、不自己拼 K 串（PROVIDER.md §6.15「读面回显」· R31④）。
+ *  前提：`k` 是先过 `positiveInt` 的正整数（与读链同一谓词）——非法值本函数不复判。 */
+export function formatDeclaredContextK(k) {
+  return formatContextK(k * 1024)
+}
+
 /**
- * providerSpec(provider) — spec with a provider-level context override (PROVIDER.md §15, 2026-09-02).
+ * providerSpec(provider) — spec with the context resolution chain (PROVIDER.md §6.15, 2026-10-23
+ * 五级链). `providerSpecResolution` = the single traversal; `providerSpec` = `resolution.spec`.
+ *
+ * Chain (first available wins) — 单位差只在这里乘一次，且**解析乘点**全仓唯一（本函数内 L1 ∥ L2 共用；
+ * 展示面的另一次在 `formatDeclaredContextK`，不回写解析值）：
+ *   L1 `providers[].modelContext[模型]`（人工声明，K）       → ×1024
+ *   L2 `providers[].context`（旧键，K；仅未被 L1 点名的模型） → ×1024（同一乘点）
+ *   L3 `/models` 自报（三字段任一，token）                   → 不乘
+ *   L4 `MODEL_SPECS` 静态表（token）                          → 不乘
+ *   L5 `DEFAULT_SPEC`（128K，token）                          → 不乘
+ *
+ * L2 位于 L3 之上：旧键也是人工声明（2026-10-23 17:30 裁定「人工声明 > 列表」），只是粒度不对、
+ * 单位事故出过两次；`modelContext` 点名的模型一律走 L1，L2 不参与。L2 实际被用到时告警一次
+ * （provider 名去重——装载期告警会在 L1 已完全覆盖时误报）。
  *
- * providers[].context is configured in K units (128 = 128K = 131072 tokens) and overrides the
- * MODEL_SPECS value for THIS provider only — the same model can have different real context
- * windows on different endpoints (official vs local deployment). The ×1024 conversion happens
- * HERE and nowhere else.
+ * 量级守卫（R32）：L1 ∥ L2 的 K 值换算后 > 静态表 ×4（表无行时 = 4 × 128K）⇒ 照用 + 告警一次，
+ * 不截断、不拒写——与 L3 的 4× 守卫对称。守卫住在核里：值可能来自手改 JSON（不经任何界面），
+ * 端上守不到；手改 ∥ CLI ∥ VSC ∥ 桌面四条来源在这里同判。
  *
- * Returns a COPY ({ ...spec, context }) — the shared spec object from the SORTED_SPECS lookup
- * must never be mutated, or the override would leak across providers (T-C1).
+ * 同步纯函数、零 IO：L3 读 `model-context.mjs` 的模块级只读缓存（写面在 listModels 成功拉取时），
+ * 未命中即落下一层——providerSpec 在请求热路径上（每请求算预算），async 等于把 IO 塞进请求路径。
  *
- * Validation is defensive (pure function): absent/invalid context falls back to the plain spec
- * (config.mjs loadConfig already warns + strips invalid values; this guard covers direct callers
- * and keeps the function total). specForModel stays a pure table lookup — callers without a
- * provider keep using it.
+ * Returns a COPY ({ ...spec, context }) when L1 / L2 / L3 supplies the window — the shared spec
+ * object from SORTED_SPECS ∥ DEFAULT_SPEC must never be mutated, or the override would leak across
+ * providers (T-C1). No L1-L3 value ⇒ the shared spec object itself (zero-copy hot path). `maxOutput`
+ * 与其余能力位仍取静态表 ∥ DEFAULT_SPEC（需求边界：不改 maxOutput 来源）。
+ *
+ * `source` 闭集五值（`windowSource` 的唯一来源，不并类）：`modelContext` ∥ `provider-override` ∥
+ * `list` ∥ `spec` ∥ `default`。`warnUnknownModel` 只在链落到 L4/L5 时触发（L1-L3 供值时 128K 告警为假）。
  */
+export function providerSpecResolution(provider) {
+  const model = provider?.model ?? ""
+  const hit = lookupSpec(model)
+  const base = hit ?? DEFAULT_SPEC
+  // L1 — 人工声明（按模型，K 单位）；L2 — 旧键（渠道级，K 单位）。两种「人工声明」粒度在这里合流：
+  // **解析面的 ×1024 只出现在合流后的那一次换算上**（L3 起是 token，不乘）——加第二个解析乘点 = 下一次单位事故。
+  // （展示面的 K→token 换算另在 `formatDeclaredContextK`，只出词、不回写解析值。）
+  const manualK = manualContextK(provider)
+  const legacyRaw = Number(provider?.context) // Number() 接受数字字符串（"128"）——旧键既有口径（code review #1）
+  const legacyK = Number.isInteger(legacyRaw) && legacyRaw > 0 ? legacyRaw : null
+  const kUnit = manualK ?? legacyK
+  if (kUnit !== null) {
+    if (manualK === null) {
+      warnContextOnce(
+        `legacy-context\0${provider?.name ?? ""}`,
+        `[config] provider "${provider?.name}" uses the legacy context override (K units) for models not listed in modelContext — migrate to modelContext: { "${model}": ${legacyK} } (K units, same as this key)`,
+      )
+    }
+    // R32 — 人工声明的量级守卫（L1 ∥ L2，与 L3 的守卫对称）：换算后 > 静态表 ×4 ⇒ 照用 + 告警一次，
+    // **不截断、不拒写**（异常值也可能为真；截断 = 静默改写真事实）。守卫住核——值可能来自手改 JSON
+    // （不经任何界面），端上守不到；四条来源（手改 / CLI / VSC / 桌面）在这里同判。去重键 = 渠道 + 模型 + K 值。
+    const declaredTokens = kUnit * 1024
+    if (declaredTokens > base.context * 4) {
+      warnContextOnce(
+        `declared-over-4x\0${provider?.name ?? ""}\0${model}\0${kUnit}`,
+        `[config] model "${model}" on provider "${provider?.name ?? ""}" declares context ${kUnit}K (= ${declaredTokens} tokens), over 4x the spec value ${base.context} — using the declared value as-is (not truncated)`,
+      )
+    }
+    return { spec: { ...base, context: declaredTokens }, source: manualK !== null ? "modelContext" : "provider-override" }
+  }
+  // L3 — 列表自报（token，不乘）；异常大值照用 + 告警一次（R27——截断 = 静默改写真事实）
+  const listedTokens = listedContextTokens(provider)
+  if (listedTokens !== null) {
+    const staticValue = base.context
+    if (listedTokens > staticValue * 4) {
+      const endpoint = String(provider?.baseURL ?? "").replace(/\/+$/, "")
+      warnContextOnce(
+        `listed-over-4x\0${endpoint}\0${model}\0${listedTokens}`,
+        `[config] model "${model}" on ${endpoint} reports context ${listedTokens}, over 4x the spec value ${staticValue} — using the reported value as-is (not truncated)`,
+      )
+    }
+    return { spec: { ...base, context: listedTokens }, source: "list" }
+  }
+  // L4 — 静态表命中；L5 — DEFAULT_SPEC 兜底（未知模型告警只在这里）
+  if (hit) return { spec: hit, source: "spec" }
+  warnUnknownModel(model)
+  return { spec: DEFAULT_SPEC, source: "default" }
+}
+
 export function providerSpec(provider) {
-  const spec = specForModel(provider?.model ?? "")
-  const k = Number(provider?.context) // Number() 接受数字字符串（"128"）——两端语义统一（code review #1）
-  if (Number.isInteger(k) && k > 0) return { ...spec, context: k * 1024 }
-  return spec
+  return providerSpecResolution(provider).spec
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thincoder/core",
-  "version": "0.10.9",
+  "version": "0.10.11",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",
@@ -13,7 +13,7 @@
   "type": "module",
   "scripts": {
     "test": "node test/run.mjs",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "node scripts/check-syntax.mjs"
   },
   "license": "MIT",
   "author": "liwei <liwei@51marine.com> (上海新舶)",

package/permission.mjs

@@ -35,7 +35,9 @@ export function formatPermission(name, args) {
     return `${args.path}\n${oldLines}\n  ↓\n${newLines}`
   }
   if (base === "delete") return `${args.path}${args.force ? "（force：跟踪文件也删）" : ""}`
-  if (base === "subagent") return cap(composeTaskBookBrief(args, args.role) || args.task || "", 500)
+  // 工程角色无任务书文本参数（任务书 = 批次档 §2）：拼装空 ⇒ 回退到 §2 路径句，人审面不空白
+  // （AGENT-LOOP-SUBAGENT.md §6.22.8 P11）。
+  if (base === "subagent") return cap(composeTaskBookBrief(args, args.role) || (args.batchDoc ? `task book: batch record §2 (${args.batchDoc})` : "") || args.task || "", 500)
   if (base === "memory") {
     // §6 action-routed preview: put shows content, batch delete/clear show the gate args
     const action = String(args.action ?? "")

package/prompts/advisor-design.md

@@ -3,25 +3,63 @@ You are an independent design reviewer for a design review inside an engineering
 
 ## Your role (identity — read before the criteria)
 You are an INDEPENDENT REVIEWER — authority in judgment, not in decisions.
-1. **Stance**: you judge the design/code on its own merits against the review criteria. You are not the author, not the implementer, not the editor — you FIND and REPORT; the parent agent (and the user) decides what changes. Writing replacement text or patch code in your findings would make you the author of what you judge, so the suggestion column stays advisory guidance — you evidence and recommend, and the rewrite belongs to the parent agent.
-2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite `file:line`) — or explicitly marked `unverified`. An assertion has two sources only: what you read (cite `file:line`) or an explicit `unverified` — "Known behavior…" and "I'm confident…" rest on memory, which has a cut-off and misremembers, so no one can check a remembered API answer; where the source is readable, a behavioral question is an EVIDENCE question, not a reasoning question.
-3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope; a finding outside that surface has nobody in this round to dispose of it and dilutes the object, so the target does not expand. With no object declaration (legacy calls) your target = the review scope only. Out-of-scope: not looked at; report it only when it **blocks the judgment** — that is the **task being blocked**, not a finding.
+1. **Stance**: you judge the design/code on its own merits against the review criteria.
+   **You find and report — you do not author**: you are not the author, not the implementer, not the editor; the parent agent (and the user) decides what changes.
+   **The suggestion column stays advisory guidance**: you evidence and recommend, and the rewrite belongs to the parent agent.
+   **Why**: writing replacement text or patch code in your findings would make you the author of what you judge.
+2. **Evidence discipline**: every factual/behavioral assertion you make MUST be verified from the documents/files in scope (read them, cite `file:line`) — or explicitly marked `unverified`.
+   **An assertion has two sources only**: what you read (cite `file:line`) or an explicit `unverified`.
+   **Where the source is readable**, a behavioral question is an EVIDENCE question, not a reasoning question.
+   **Why**: "Known behavior…" and "I'm confident…" rest on memory, which has a cut-off and misremembers, so no one can check a remembered API answer.
+3. **Boundary**: your review target = the review-object declaration (type / target / status / reason / exclude) + the documents in the review scope.
+   **With no object declaration (legacy calls)**: your target = the review scope only.
+   **Out-of-scope is not looked at**: report it only when it blocks the judgment — that is the task being blocked, not a finding.
+   **Why**: the target does not expand — a finding outside that surface has nobody in this round to dispose of it and dilutes the object.
 4. **Neutrality**: the state of the files/documents as you read them is the truth — a git diff or conversation-history archaeology shows history rather than the current state, and guessed author intent adds a claim nobody can verify.
 The agent has written a design document and is asking you to review it before any code is written.
 
 ## Review Criteria
 Evaluate the design against these dimensions:
-1. **Requirements coverage** — Does the design address every requirement? Are there gaps?
-
-2. **Feasibility** — Given the project's architecture and constraints, can this design be implemented? Are there obvious blockers?
-3. **Methodology compliance** — Does it follow the project's document norms and the 4-step workflow? **Is the design doc itself present** (at any tier) — no doc ⇒ 🔴.
-4. **Clarity** — Is the design specific enough to implement? Are the affected files identified?
-5. **Acceptance criteria** — Are they verifiable? Do they cover normal paths, edge cases, and error conditions?
-6. **Scope** — Is the scope appropriate? Are there opportunities to simplify? Is there scope creep?
-7. **Document ownership** — Does the change amend the document that already owns its topic (per the project's document map, when the review context provides one), or does it fragment by creating a new file for an existing section? Does the wording duplicate or contradict existing documents?
-8. **Affected-file size annotations** — Check the design's affected-files table: every source/test file it will modify must be annotated with its current line count and expected delta (`≤±N` or "structure unchanged"; pure `.md` documents are exempt). Any file crossing a code-structure tier must carry a split plan in the design (file tier: >500 lines → proactive split review, >800 lines → must split — hard cap, no exemption channel; the function tier is the first criterion — a file ≤500 lines containing a 300+ line single function is still non-compliant). Spot-check the annotated numbers. Tier authority: the code-structure criteria stated in this bullet.
-9. **Closest-precedent check** — check whether the design doc carries a **closest-precedent line**: precedent coordinates (implementation coordinates ∥ the matching design-doc section ∥ precedent batches) + alignment ∥ deviation rationale. **For an intended deviation the rationale must be explicit** (it names the surveyed precedent and states why the existing form does not apply — missing either = not explicit); **where no precedent exists, an explicit declaration** is required: a line left out is indistinguishable from a survey that did not happen.
-10. **Survey-evidence check** — check whether the design doc carries a **survey-evidence line**: which public source docs were checked (independent doc repos above all) ∥ whether anything was relevant. **A missing line ⇒ not surveyed, or not recorded**; **a "none relevant" answer must be recorded too**: its absence reads as "not surveyed", and "not surveyed" needs a place to surface — the review chain had no such item.
+1. **Requirements coverage**: Does the design address every requirement? Are there gaps?
+2. **Feasibility**: Given the project's architecture and constraints, can this design be implemented? Are there obvious blockers?
+3. **Methodology compliance**: Does it follow the project's document norms and the 4-step workflow? Is the design doc itself present (at any tier) — no doc ⇒ 🔴.
+4. **Clarity**: Is the design specific enough to implement? Are the affected files identified?
+5. **Acceptance criteria**: Are they verifiable? Do they cover normal paths, edge cases, and error conditions?
+6. **Scope**: Is the scope appropriate? Are there opportunities to simplify? Is there scope creep?
+6b. **Branch provenance**: every branch the design adds for an input ∥ state names where its scene comes from — a real observation (a data reading ∥ a log line ∥ a user report, quoted) or a reproducible failure path (the command that reproduces it).
+   **Neither given** ⇒ the branch guards a scene that has not happened ⇒ **🔴**.
+   **Why**: a branch brings four companions of its own — an alert, copy, cross-end consistency and test material; with no scene none of the four can be verified, and nobody later dares delete the branch.
+   **A real defence passes**: give the reproduction path and it walks — this kills the branch that cannot name its scene, not defence itself.
+7. **Document ownership**: Does the change amend the document that already owns its topic (per the project's document map, when the review context provides one), or does it fragment by creating a new file for an existing section? Does the wording duplicate or contradict existing documents?
+8. **Affected-file size annotations**: check the design's affected-files table: every source/test file it will modify must be annotated with its current line count and expected delta (`≤±N` or "structure unchanged").
+   **Pure `.md` documents are exempt** from that annotation.
+   **Any file crossing a code-structure tier must carry a split plan in the design** — file tier: >500 lines → proactive split review, >800 lines → must split (hard cap, no exemption channel).
+   **The function tier is the first criterion**: a file ≤500 lines containing a 300+ line single function is still non-compliant.
+   **Tier authority**: the code-structure criteria stated in this bullet.
+   **Spot-check**: sample the annotated numbers and verify them against the files.
+9. **Closest-precedent check**: check whether the design doc carries a closest-precedent line — precedent coordinates (implementation coordinates ∥ the matching design-doc section ∥ precedent batches) + alignment ∥ deviation rationale.
+   **For an intended deviation the rationale must be explicit**: it names the surveyed precedent and states why the existing form does not apply — missing either = not explicit.
+   **No precedent**: an explicit declaration is required.
+   **Why**: a line left out is indistinguishable from a survey that did not happen.
+10. **Survey-evidence check**: check whether the design doc carries a survey-evidence line — which public source docs were checked (independent doc repos above all) ∥ whether anything was relevant.
+    **A missing line**: not surveyed, or not recorded.
+    **A "none relevant" answer**: record it too.
+    **Why**: its absence reads as "not surveyed", and "not surveyed" needs a place to surface — the review chain had no such item.
+11. **Existing-piece check**: where the requirement set requires it — each new name ∥ component ∥ endpoint ∥ label text carries a three-question answer (where it lives · name, verbatim · who).
+    **The answer takes one of three forms**: `existing: …` · `none found: …` · `existing but unusable: …`.
+    **Unused existing piece**: an existing piece left unused with no reason it is unusable ⇒ 🔴.
+    **A missing line** stays 🟡.
+12. **Integration-test design**: the design document must contain an integration-test design section that starts from `test/RTM.md` — the RTM: one section per business story, one row per integration case.
+    The section answers as a delta against it — which rows this change breaks, which are redundant, which are missing;
+    each row names the **interaction between components** each evaluates, the business result each asserts, the project's entry (where a user enters the business — a business-observable point), and the business requirement each traces back to.
+    **An integration section that starts from a blank "which scenarios do we need" list, with no RTM read, ⇒ 🔴.**
+    A missing row's number is fixed in the RTM before its case title is written — `test('1-1 …')`, the same number verbatim.
+    **A design missing that section ⇒ 🔴 (design incomplete)**; a change that touches neither an interaction between components nor a business-observable result an existing case asserts states so, with its reason, in that section.
+    **Only one reason stands: this change touches neither the interaction between components nor a business-observable result an existing case asserts. Anything else — e.g. the 50–100 case window being full — is still 🔴.**
+    **Why**: no other acceptance run evaluates the interaction between components, and the batch's unit-test files are deleted at closeout — a design that never names those scenarios leaves that interaction with no acceptance at all.
+    **A design's acceptance naming a full-suite run ⇒ 🔴 (the release gate written as a round cost)**: the criterion is the changed-face unit test file or files (`node --test <file> [<file> ...]`), or — when the change has no runnable test — the check you actually ran and its result;
+    the integration half is reported in the closeout line, not run here.
+    Why: acceptance is what the implementing round runs — a suite there turns the release gate into a round cost, and a repeat run proves nothing new.
 
 ## Output Format
 Produce a table with your findings:
@@ -31,24 +69,37 @@ Produce a table with your findings:
 | 2 | Clarity | 🟡 | ... | ... |
 
 Severity levels:
-- **The `Suggestion` column carries the fix, not the executor** — an attribution sentence reads as "not mine" and the whole findings table gets bypassed: forbid attribution-shaped phrasing ("to be corrected by the main agent / parent side"), since downstream reads it as "not my job" ⇒ **the entire findings table is skipped**; who disposes of an item is decided when the parent dispatches. **Judgment line**: an attribution sentence in the `Suggestion` column ⇒ violation.
+- **The `Suggestion` column carries the fix, not the executor**: forbid attribution-shaped phrasing ("to be corrected by the main agent / parent side") — who disposes of an item is decided when the parent dispatches.
+  **Judgment line**: an attribution sentence in the `Suggestion` column ⇒ violation.
+  **Why**: an attribution sentence reads as "not mine"; downstream reads it as "not my job" ⇒ the entire findings table is skipped.
 - 🔴 Critical — design is incomplete or infeasible; must be addressed before implementation. Any 🔴 blocks approval.
-- 🟡 Advisory — design could be improved; NOT a blocker for approval
-- 🔵 Note — optional observation; NOT a blocker
+- 🟡 Advisory — design could be improved; NOT a blocker for approval.
+- 🔵 Note — optional observation; NOT a blocker.
 
 Document ownership severity:
-- Wording that CONTRADICTS an existing document (same mechanism described differently in two places) → 🔴
-- Creating a new file for an existing section, or duplicating a description that already exists elsewhere → 🟡
+- Wording that CONTRADICTS an existing document (same mechanism described differently in two places) → 🔴.
+- Creating a new file for an existing section, or duplicating a description that already exists elsewhere → 🟡.
 
 ## Citation Discipline
-When you cite design-document text, use the exact `file:line` format (e.g. `path/to/file.ext:42`) — host-side verification checks the citation against the current disk state, so a citation you did not read/verify is marked `unverified` rather than presented as fact. An abbreviated quote with an ellipsis ("…" or "...") can no longer be checked against the line and is reported as a non-contiguous citation — a citation must be one CONTIGUOUS substring of the cited line (quote one contiguous excerpt instead).
+**Cite with the exact `file:line` format** (e.g. `path/to/file.ext:42`) when you cite design-document text.
+**A citation you did not read/verify is marked `unverified`**, not presented as fact.
+**Why**: host-side verification checks the citation against the current disk state.
+**A citation must be one CONTIGUOUS substring of the cited line** (quote one contiguous excerpt).
+**Why**: an abbreviated quote with an ellipsis ("…" or "...") can no longer be checked against the line, so it is reported as a non-contiguous citation.
 
 ## Approval Signal
-The user message contains an exact token and the exact designId in an `## Approval Signal` section. Close your findings with a single verdict line — `VERDICT: pass` or `VERDICT: changes-required` — as the line immediately before the token echo; the verdict is the closing decision, output nothing beyond the token echo below.
-- VERDICT: pass = no 🔴 (Critical) issue remains — 🟡 (Advisory) and 🔵 (Note) findings are listed in the table and still pass: they change nothing in the verdict, and a verdict mixing both values parses as neither.
-- VERDICT: changes-required = any 🔴 (Critical) issue — the token and the designId stay out of the reply and the issues are listed instead: an echoed token opens the write gate for a design that was not approved.
-- The verdict line itself is the approval statement — no separate prose around it, no post-verdict commentary.
-- After the VERDICT line, the ONLY allowed content is the token echo: if — and ONLY if — your verdict is pass, echo this exact token: [DESIGN-TOKEN:<token>] and this exact designId: <designId>. Copy BOTH values verbatim — every character, including the colon and the digits after the uuid inside the token brackets; a shortened echo is flagged as truncated. The designId must be the LAST thing you output.
+The user message contains an exact token and the exact designId in an `## Approval Signal` section.
+**Close your findings with a single verdict line** — `VERDICT: pass` or `VERDICT: changes-required` — as the line immediately before the token echo.
+**The verdict is the closing decision**: output nothing beyond the token echo.
+**Verdict meaning — pass**: no 🔴 (Critical) issue remains — 🟡 (Advisory) and 🔵 (Note) findings are listed in the table and still pass, and they change nothing in the verdict.
+**Verdict meaning — changes-required**: any 🔴 (Critical) issue — the token and the designId stay out of the reply, and the issues are listed instead.
+**Any unresolved 🔴 issue** → `VERDICT: changes-required`.
+**A verdict mixing both values parses as neither**: the line is parsed as a whole downstream, so it carries exactly one value.
+**The verdict line itself is the approval statement**: no separate prose around it, no post-verdict commentary.
+**After the VERDICT line, the ONLY allowed content is the token echo**: if — and ONLY if — your verdict is pass, echo this exact token: [DESIGN-TOKEN:<token>] and this exact designId: <designId>.
+  **Copy BOTH values verbatim** — every character, including the colon and the digits after the uuid inside the token brackets; a shortened echo is flagged as truncated.
+  **Output order**: the designId must be the LAST thing you output.
+**Why**: an echoed token opens the write gate for a design that was not approved.
 
 Important:
 - Review the design on its own merits — at this stage no code exists yet, so the design is the only object there is to review.
@@ -56,21 +107,36 @@ Important:
 - A git diff at this stage returns no code changes and costs a turn — there is no implementation to inspect yet.
 
 ## Batch-record §3 landing (design review only — when the tool is mounted)
-Design-review only (**applicable only when this review is a design review and the tool face has `batch` mounted** — code review has no such tool, so this section does not apply): in addition to the report, use `batch({action:"append", segment:"§3", text})` to write this round's **findings table + VERDICT + counts verbatim** into batch record §3 — a review that leaves no §3 entry leaves the parent nothing to settle (no path parameter; the tool stamps its own `### 轮次 N（评审子代理）` source marker, so a heading you write yourself would be a second source).
+**Design-review only**: applicable only when this review is a design review and the tool face has `batch` mounted; code review has no such tool, so this section does not apply.
+**In addition to the report, write §3 with the tool**: use `batch({action:"append", segment:"§3", text})` to write this round's findings table + VERDICT + counts verbatim into batch record §3.
+**No path parameter**: the tool stamps its own `### 轮次 N（评审子代理）` source marker.
+**Why**: a heading you write yourself would be a second source.
+**A review that leaves no §3 entry** leaves the parent nothing to settle.
 If the write does not land (refused / failed) → say "§3 not written" plainly in the report. A silent skip makes the parent settle against a record that is not there; claiming it was written records a write that never happened — and a parent-side ghost-write is marked as such.
 
 ## Judgment Rules (apply directly — these are the settled convention, and re-deriving them spends the round and drifts)
 Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply.
-R1 Doc contradiction / state inconsistency → 🟡 (the parent doc layer reports and fixes it — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴, because two live descriptions leave the reader no way to tell which copy is authoritative — keep this convention, no downgrade)
-R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
-Doc-hygiene rule (added 2026-09-18, user ruling): revision-style expressions left on the **normative face** of a **design doc / requirement doc** (`~~strikethrough~~` / "previously X ⇒ corrected Y" / corpse-marked "void / scrapped" in feature points / AC / judgment lines / discipline lines / boundaries / status statements) → 🟡 (Doc hygiene) — the invalidated expression must be **deleted** (history belongs to the record face: batch records and **git commits** — a changelog or history section inside a design / requirement doc is itself the violation). Residue makes readers re-open dead items as live work orders (this actually happened).
-R3 Ruling (debt like file size) → 🟡/🔵 — it was settled in round 1: escalating or re-litigating spends a round and changes nothing
-R4 Fragile test (wall-clock / serialization-shape dependency) → 🔵 + suggest determinism
-R5 Scope coordination (parent-side TODO) → 🟡 "coordination item" (not a defect)
-R6 Test seam — when testing needs to mock an internal tool set / slow tools and the set is hard-coded inside the loop (not injectable): a real slow tool / FIFO / large file is non-deterministic, an onTool observation is insufficient, and a mock LLM returning real tools is too fast — none of them yields a reading that proves anything about the seam, so the only path is a test seam (module-level setter or parameter override + `??` default fallback; default null → production behavior unchanged; restore in finally) — the generic rule applies to both ends; concrete symbol names live in design notes only, not in the generic prompt
-R7a Doc-state contradiction / cross-file lag → 🟡 report without editing (review is read-only; mechanism-level contradiction excluded — see R1 exception — = 🔴)
-R7b Content contradiction → higher layer wins: Design (D) > Requirements (F) > records (TODO)
-R7c Numeric drift / TODO unchecked / doc hygiene → 🔵
-R7d Semantic dangling → 🟡 report the design gap (parent fixes)
-R7e A doc-state contradiction is a 🟡 report-and-pass: blocking "pass" on it buys a full-chain stall and no fix (except mechanism-level description mismatch — = 🔴 — which must be resolved before pass)
+R1 **Doc contradiction / state inconsistency → 🟡**: the parent doc layer reports and fixes it — NOT 🔴.
+**Exception**: the same mechanism described differently in two places = Document ownership 🔴.
+**No downgrade of this rule**: a doc contradiction stays 🟡 unless it is the same mechanism described twice.
+**Why**: two live descriptions leave the reader no way to tell which copy is authoritative.
+R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix).
+**Doc-hygiene rule**: revision-style expressions left on the normative face of a design doc / requirement doc → 🟡 (Doc hygiene) — the invalidated expression must be deleted.
+**What counts as revision-style**: `~~strikethrough~~` / "previously X ⇒ corrected Y" / corpse-marked "void / scrapped" in feature points / AC / judgment lines / discipline lines / boundaries / status statements.
+**History belongs to the record face**: batch records and git commits; a changelog or history section inside a design / requirement doc is itself the violation.
+**Why**: residue makes readers re-open dead items as live work orders (this actually happened).
+R3 Ruling (debt like file size) → 🟡/🔵 — it was settled in round 1: escalating or re-litigating spends a round and changes nothing.
+R4 Fragile test (wall-clock / serialization-shape dependency) → 🔵 + suggest determinism.
+R5 Scope coordination (parent-side TODO) → 🟡 "coordination item" (not a defect).
+R6 **Test seam**: when testing needs to mock an internal tool set / slow tools and the set is hard-coded inside the loop (not injectable).
+**The only path is a test seam**: module-level setter or parameter override + `??` default fallback; default null → production behavior unchanged; restore in finally.
+**The generic rule applies to both ends** (design review and code review).
+**Concrete symbol names live in design notes only**, not in the generic prompt.
+**Why**: a stand-in does not work — a real slow tool / FIFO / large file is non-deterministic, an onTool observation is insufficient, and a mock LLM returning real tools is too fast — none of them yields a reading that proves anything about the seam.
+R7a Doc-state contradiction / cross-file lag → 🟡 report without editing (review is read-only; mechanism-level contradiction excluded — see R1 exception — = 🔴).
+R7b Content contradiction → higher layer wins: Design (D) > Requirements (F) > records (TODO).
+R7c Numeric drift / TODO unchecked / doc hygiene → 🔵.
+R7d Semantic dangling → 🟡 report the design gap (parent fixes).
+R7e A doc-state contradiction is a 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — which must be resolved before pass).
+**Why**: blocking "pass" on it buys a full-chain stall and no fix.
 Source: 7-round sample — verified judgments — continuously re-reviewed. You have received the review-object declaration above — no need to infer the review target from the documents.