thincoder 0.12.58 → 0.12.59

package/src/memory/docs.mjs

@@ -7,7 +7,7 @@ import { join } from "node:path"
 import { embed, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { commitAndPush } from "../git/gitmem.mjs"
 import { DOC_EXTS, SKIP_DIRS, MAX_DOC_FILE_BYTES } from "./schema.mjs"
-import { buildFtsQuery, put, search, putMarkdown, deleteByUid, EMBED_TEXT_MAX_LEN } from "./core.mjs"
+import { buildFtsQuery, put, search, putMarkdown, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { markIndexedCommit, listProjectFiles } from "./code-sync.mjs"
 
@@ -164,7 +164,8 @@ export function docSearchTool(memory) {
   return {
     name: "doc_search",
     description:
-      "Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation.",
+      "Search the project's documentation (README, design docs, guides, markdown files) for relevant information. Use this to find design decisions, coding conventions, architecture docs, or project rules. Prefer this over code_search when you need to understand the project's intended design rather than existing implementation. " +
+      "Returns matching doc chunks: path, heading, line range, relevance score, content excerpt.",
     parameters: {
       type: "object",
       properties: {
@@ -186,9 +187,45 @@ export function docSearchTool(memory) {
 
 // ---------------------------------------------------------------- agent tools
 
+/** §6 shared tool surface — action enum / parameter shapes / descriptions byte-identical
+ *  with thincoder-vscode/src/memory.mjs (MEMORY.md §6 D-M1/F-M6); scope VALUES per end
+ *  (VS Code has no team layer and rejects it with CLI guidance). */
+const MEMORY_ACTIONS = ["search", "put", "list", "delete", "clear"]
+const MEMORY_SCOPES = ["personal", "project", "team"]
+const MEMORY_TOOL_DESCRIPTION =
+  "Manage long-term memory in ONE tool — the action parameter picks the operation:\n" +
+  "- search — find knowledge saved in previous sessions (query, optional scope/limit); results include every entry's id\n" +
+  "- put — save a piece of knowledge for future sessions (type: rule = coding standards, knowledge = project facts, decision = architecture decisions, pattern = debugging/workflow patterns; title/content/tags/scope)\n" +
+  "- list — inventory what memory holds: optional scope/type/keyword filters, limit default 50; one row per entry: id [type] title (date); a truncated list notes the full count\n" +
+  "- delete — SINGLE: {id, scope} deletes one entry by the id shown in put/search/list output. BATCH: {scope + type and/or keyword} deletes every matching entry in that scope — a call without confirm:true is refused and returns the count plus a preview (re-send with confirm:true to execute); scope-wide wipes without filters are refused on every layer\n" +
+  "- clear — {scope: \"personal\", confirm: true} wipes ALL personal memory entries. clear is personal-only: a missing scope or a project/team scope is refused (use delete batch filters on shared layers)\n" +
+  "Deleting project/team (CLI) entries removes the local markdown file and its index row — team deletion is local only and a later team sync may resurrect the file while the remote still has it.\n" +
+  "Save bugs, conventions, and preferences here — they persist across sessions."
+
+function validateTypeFilter(type) {
+  if (type === undefined || type === null || type === "") return null
+  const t = String(type)
+  if (!["rule", "knowledge", "decision", "pattern"].includes(t)) throw new Error(`Invalid memory type "${t}"; expected one of: rule, knowledge, decision, pattern`)
+  return t
+}
+
+function normalizeLimit(limit, dflt) {
+  const n = Number(limit)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt
+}
+
+function fmtDate(ts) {
+  return ts ? new Date(ts).toISOString().slice(0, 10) : "?"
+}
+
+const listRowLine = (r) => `${r.id} [${r.type}] ${r.title}（${fmtDate(r.ts)}）`
+
 /**
- * Generate the three memory-related agent tools (following the tools.mjs tool shape).
- * memory_put and memory_delete are side-effecting (need permission confirmation), memory_search is read-only.
+ * Generate the memory agent tool — ONE `memory` tool with five actions (MEMORY.md §6 D-M1).
+ * search/list are read-only actions (planMode pass / no permission ask — dispatch classifies
+ * them action-level, same as subagent check/status); put keeps its side-effect permission
+ * gate; batch delete/clear gate on confirm:true + scope inside the tool (direct-delete
+ * ruling — the confirm parameter IS the gate) and stay non-readonly like the retired tools.
  * opts: { cwd, projectDir, author, team: { dir, name } | null }
  */
 export function memoryTools(memory, opts = {}) {
@@ -196,99 +233,171 @@ export function memoryTools(memory, opts = {}) {
   const dirs = { project: projectDir, team: opts.team?.dir ?? null }
   return [
     {
-      name: "memory_put",
-      description:
-        "Save a piece of knowledge to long-term memory. Use when you learn something worth remembering across sessions: a project convention, a debugging insight, an architecture decision. Types: rule (coding standards), knowledge (project facts), decision (architecture decisions), pattern (debugging/workflow patterns). Scopes: personal (default, private to you), project (shared via this repo's .thincoder/memory/), team (org-wide team repo, if configured).",
+      name: "memory",
+      description: MEMORY_TOOL_DESCRIPTION,
       parameters: {
         type: "object",
         properties: {
-          type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"] },
-          title: { type: "string", description: "Short title" },
-          content: { type: "string", description: "Full content to remember" },
-          tags: { type: "string", description: "Space-separated tags" },
-          scope: { type: "string", enum: ["personal", "project", "team"], description: "Where to save (default personal)" },
+          action: { type: "string", enum: MEMORY_ACTIONS, description: "Operation to run (required)" },
+          scope: { type: "string", enum: MEMORY_SCOPES, description: "Where the memory lives: personal (private), project (shared via this repo's .thincoder/memory/), team (CLI only). put defaults to personal; search/list search every layer when omitted; delete/clear require it" },
+          type: { type: "string", enum: ["rule", "knowledge", "decision", "pattern"], description: "Entry type: put = what to save; list/delete batch = filter by type" },
+          title: { type: "string", description: "put: short title" },
+          content: { type: "string", description: "put: full content to remember" },
+          tags: { type: "string", description: "put: space-separated tags" },
+          query: { type: "string", description: "search: natural-language query" },
+          keyword: { type: "string", description: "list/delete batch: filter matching title/content" },
+          id: { type: "string", description: "delete single: the entry id from put/search/list output" },
+          limit: { type: "number", description: "Max rows: list 50 by default, search 5 by default" },
+          confirm: { type: "boolean", description: "delete batch/clear: must be true — without it the tool refuses" },
         },
-        required: ["type", "title", "content"],
+        required: ["action"],
       },
       readonly: false,
       async execute(args) {
-        const scope = args.scope ?? "personal"
-        if (scope === "personal") {
-          const id = await put(memory, args)
-          return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
-        }
-        if (scope === "project") {
-          if (!projectDir) throw new Error("project scope unavailable: no project directory configured")
-          const filename = await putMarkdown(memory, {
-            layer: "project",
-            dir: projectDir,
-            type: args.type,
-            title: args.title,
-            content: args.content,
-            tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-            author: opts.author ?? "unknown",
-          })
-          return `Saved to project memory (id=project:${projectDir}:${filename}): [${args.type}] ${args.title}`
+        const action = String(args?.action ?? "")
+        if (!MEMORY_ACTIONS.includes(action)) {
+          throw new Error(`memory: unknown action "${action}" — expected one of: ${MEMORY_ACTIONS.join("/")}`)
         }
-        if (!opts.team?.dir) {
-          throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+        switch (action) {
+          case "search": return execSearch(memory, args)
+          case "put": return execPut(memory, args, opts, dirs)
+          case "list": return execList(memory, args, dirs)
+          case "delete": return execDelete(memory, args, dirs)
+          case "clear": return execClear(memory, args)
         }
-        const filename = await putMarkdown(memory, {
-          layer: "team",
-          dir: opts.team.dir,
-          type: args.type,
-          title: args.title,
-          content: args.content,
-          tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
-          author: opts.author ?? "unknown",
-        })
-        await commitAndPush(opts.team.dir, filename, `memory: [${args.type}] ${args.title}`)
-        return `Saved to team memory and pushed (id=team:${opts.team.dir}:${filename}): [${args.type}] ${args.title}`
-      },
-    },
-    {
-      name: "memory_search",
-      description:
-        "Search long-term memory across all layers (personal/project/team) for relevant knowledge saved in previous sessions. Use the same language as the memories being searched.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Natural language search query" },
-          limit: { type: "number", description: "Max results (default 5)" },
-        },
-        required: ["query"],
-      },
-      readonly: true,
-      async execute(args) {
-        const results = await search(memory, args.query, { limit: args.limit ?? 5 })
-        if (results.length === 0) return "(no matching memories)"
-        return results.map((r) => `[${r.layer}][${r.type}] ${r.title} (id=${r.id})\n${r.content}`).join("\n\n")
-      },
-    },
-    {
-      name: "memory_delete",
-      description:
-        "Delete a memory entry by its id (as returned by memory_put / memory_search) and scope. " +
-        "Scope is required and must match the id prefix — this prevents accidental deletion in another scope. " +
-        "Returns the deleted entry's title and content so the deletion is auditable and recoverable.",
-      parameters: {
-        type: "object",
-        properties: {
-          id: { type: "string", description: "Entry id: personal:<n> / project:<origin>:<path> / team:<origin>:<path>" },
-          scope: { type: "string", enum: ["personal", "project", "team"], description: "Scope of the entry to delete (required)" },
-        },
-        required: ["id", "scope"],
-      },
-      readonly: false,
-      async execute(args) {
-        const uid = String(args.id)
-        const prefix = uid.split(":")[0]
-        const uidScope = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
-        if (!uidScope) throw new Error(`invalid memory id: ${uid}`)
-        if (uidScope !== args.scope) throw new Error(`id prefix ${prefix}: 与 scope ${args.scope} 不匹配`)
-        const entry = await deleteByUid(memory, uid, { dirs })
-        return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
       },
     },
   ]
 }
+
+/** action search — the retired search tool surface (read-only, same output contract). */
+async function execSearch(memory, args) {
+  const scope = args.scope
+  if (scope !== undefined && scope !== null && !MEMORY_SCOPES.includes(String(scope))) {
+    throw new Error(`memory search: invalid scope "${scope}"`)
+  }
+  const query = String(args.query ?? "").trim()
+  if (!query) return "(no matching memories)" // 空 query 短路——两端同语义（评审 code review #4）
+  const limit = normalizeLimit(args.limit, 5)
+  let results
+  if (!scope) {
+    results = await search(memory, query, { limit })
+  } else {
+    // scope filter: oversample then slice the requested layer (results keep global rank order).
+    // 窗口 = max(limit*4, 20) 是召回上限——大库 + 高 limit 时该层结果可能不足 limit（接受的取舍——评审 code review #3）
+    const wide = await search(memory, query, { limit: Math.max(limit * 4, 20) })
+    results = wide.filter((r) => r.layer === String(scope)).slice(0, limit)
+  }
+  if (results.length === 0) return "(no matching memories)"
+  return results.map((r) => `[${r.layer}][${r.type}] ${r.title} (id=${r.id})\n${r.content}`).join("\n\n")
+}
+
+/** action put — the retired put tool surface (side-effect gate, unchanged semantics). */
+async function execPut(memory, args, opts, dirs) {
+  const scope = String(args.scope ?? "personal")
+  if (!MEMORY_SCOPES.includes(scope)) throw new Error(`memory put: invalid scope "${scope}"`)
+  if (scope === "personal") {
+    const id = await put(memory, { type: args.type, title: args.title, content: args.content, tags: args.tags ?? "" })
+    return `Saved to personal memory (id=personal:${id}): [${args.type}] ${args.title}`
+  }
+  if (scope === "project") {
+    if (!dirs.project) throw new Error("project scope unavailable: no project directory configured")
+    const filename = await putMarkdown(memory, {
+      layer: "project",
+      dir: dirs.project,
+      type: args.type,
+      title: args.title,
+      content: args.content,
+      tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
+      author: opts.author ?? "unknown",
+    })
+    return `Saved to project memory (id=project:${dirs.project}:${filename}): [${args.type}] ${args.title}`
+  }
+  if (!dirs.team) {
+    throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+  }
+  const filename = await putMarkdown(memory, {
+    layer: "team",
+    dir: dirs.team,
+    type: args.type,
+    title: args.title,
+    content: args.content,
+    tags: (args.tags ?? "").split(/\s+/).filter(Boolean),
+    author: opts.author ?? "unknown",
+  })
+  await commitAndPush(dirs.team, filename, `memory: [${args.type}] ${args.title}`)
+  return `Saved to team memory and pushed (id=team:${dirs.team}:${filename}): [${args.type}] ${args.title}`
+}
+
+/** action list — new inventory action (read-only): scope/type/keyword filters + limit truncation note. */
+async function execList(memory, args, dirs) {
+  const scope = args.scope ?? null
+  if (scope && !MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory list: invalid scope "${scope}"`)
+  const rows = await matchMemoryRows(memory, {
+    scope: scope ? String(scope) : null,
+    type: validateTypeFilter(args.type),
+    keyword: args.keyword ? String(args.keyword).trim() : null,
+    projectDir: dirs.project,
+    teamDir: dirs.team,
+  })
+  if (rows.length === 0) return "0 条匹配"
+  const limit = normalizeLimit(args.limit, 50)
+  const shown = rows.slice(0, limit)
+  const lines = shown.map(listRowLine)
+  if (rows.length > shown.length) lines.unshift(`${shown.length} 条——截断前 ${rows.length}`)
+  return lines.join("\n")
+}
+
+/** action delete — single ({ id, scope } — §0.1-era single-delete semantics) + batch (scope + type/keyword + confirm). */
+async function execDelete(memory, args, dirs) {
+  const hasId = args.id !== undefined && args.id !== null && String(args.id) !== ""
+  if (hasId) return execDeleteSingle(memory, args, dirs)
+  // batch form
+  const scope = args.scope
+  if (!scope) throw new Error("batch delete requires scope plus type and/or keyword filter")
+  if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory delete: invalid scope "${scope}"`)
+  const type = validateTypeFilter(args.type)
+  const keyword = args.keyword ? String(args.keyword).trim() : null
+  if (!type && !keyword) {
+    throw new Error("batch delete requires type and/or keyword filter — a scope-wide wipe without filters is refused (personal full wipe is the clear action)")
+  }
+  if (scope === "project" && !dirs.project) throw new Error("project scope unavailable: no project directory configured")
+  if (scope === "team" && !dirs.team) throw new Error("team scope not configured: set memory.team in ~/.thincoder/config.json")
+  const filters = { scope: String(scope), type, keyword }
+  const rows = await matchMemoryRows(memory, { ...filters, projectDir: dirs.project, teamDir: dirs.team })
+  if (rows.length === 0) return "0 条匹配"
+  if (args.confirm !== true) {
+    const lines = [rows.length > 5 ? `将删 ${rows.length} 条：前 5 条预览` : `将删 ${rows.length} 条`]
+    lines.push(...rows.slice(0, 5).map(listRowLine))
+    if (rows.length > 5) lines.push(`5 条——截断前 ${rows.length}`)
+    lines.push("confirm:true required — re-send with it to execute the deletion")
+    return lines.join("\n")
+  }
+  const n = await deleteWhere(memory, filters, { dirs })
+  return `Deleted ${n} entries in scope ${scope}`
+}
+
+/** Single-entry delete — §0.1-era delete semantics (id + scope, NF2/NF3, direct-delete ruling). */
+async function execDeleteSingle(memory, args, dirs) {
+  if (!args.scope) throw new Error("delete requires id + scope")
+  const uid = String(args.id)
+  const prefix = uid.split(":")[0]
+  const uidScope = prefix === "personal" || prefix === "project" || prefix === "team" ? prefix : /^\d+$/.test(prefix) ? "personal" : null
+  if (!uidScope) throw new Error(`invalid memory id: ${uid}`)
+  if (uidScope !== args.scope) throw new Error(`id prefix ${prefix}: 与 scope ${args.scope} 不匹配`)
+  const entry = await deleteByUid(memory, uid, { dirs })
+  return `Deleted ${entry.id}: ${entry.title}\n${(entry.content ?? "").slice(0, 500)}`
+}
+
+/** action clear — personal-only full wipe (scope + confirm:true gates; project/team refused). */
+function execClear(memory, args) {
+  const scope = args.scope
+  if (!scope) throw new Error('clear requires scope "personal" — pass scope: "personal" plus confirm: true')
+  if (String(scope) !== "personal") {
+    if (!MEMORY_SCOPES.includes(String(scope))) throw new Error(`memory clear: invalid scope "${scope}"`)
+    throw new Error("shared layers don't support clear — use delete with type/keyword batch filters instead")
+  }
+  if (args.confirm !== true) throw new Error("clear requires confirm:true — this wipes ALL personal memory")
+  const n = clearPersonal(memory)
+  return `Cleared personal memory (${n} entries deleted)`
+}

package/src/memory.mjs

@@ -7,7 +7,7 @@
 export { createMemory, migrate, segmentCJK, VALID_TYPES, SCHEMA_VERSION, CODE_EXTS, DOC_EXTS, SKIP_DIRS, BIG_FILE_LINES } from "./memory/schema.mjs"
 
 // CRUD + search + ensureEmbeddings
-export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, remove, deleteByUid, buildFtsQuery } from "./memory/core.mjs"
+export { put, search, ftsSearch, fetchEntry, ensureEmbeddings, putMarkdown, syncDir, indexMarkdownFile, list, remove, deleteByUid, matchMemoryRows, deleteWhere, clearPersonal, buildFtsQuery } from "./memory/core.mjs"
 
 // code chunking + markdown chunking
 export { detectLanguage, extractSymbols, extractPySymbols, chunkCode, extractLeadingDoc, yieldTick, _upsertCodeFile, chunkMarkdown, _upsertDocFile } from "./memory/code-index.mjs"

package/src/model-specs.mjs

@@ -88,7 +88,13 @@ const MODEL_SPECS = [
 ]
 const DEFAULT_SPEC = { context: 128_000, maxOutput: 32_000, cacheMode: "none" }
 
-/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models */
+/** Look up spec by model name prefix (case-insensitive), conservative default for unknown models.
+ *
+ * Vendor-namespace prefix stripping (2026-09-04)：第三方 token 市场（roapi/new-api/one-api/
+ * aiproxy 聚合网关）惯例在模型名前加厂商前缀（zhipu/glm-5.3、openai/gpt-4o）。完整名未命中
+ * 且含 "/" 时，剥掉第一个 "/" 前的 namespace 再按前缀匹配一次——ZHIPU/GLM-5.3 → glm-5.3 命中
+ * 真实规格，不再降级 128K 默认。kimi/kimi-k3 的显式 alias 行保留为文档锚（发送路径
+ * provider.core isRouter 依赖含 "/" 判定），通用机制已覆盖同类。 */
 const warnedModels = new Set() // warn once per model name — specForModel is a hot path (every request)
 // Pre-sorted once at module scope — specForModel runs on every request (agent, provider core,
 // context, auto-think, TUI rendering); re-sorting per call was wasteful.
@@ -98,6 +104,14 @@ export function specForModel(model) {
   for (const [prefix, spec] of SORTED_SPECS) {
     if (m.startsWith(prefix.toLowerCase())) return spec
   }
+  // Vendor-namespace strip: vendor/model — retry the prefix match on the bare model part.
+  const slash = m.indexOf("/")
+  if (slash > 0) {
+    const bare = m.slice(slash + 1)
+    for (const [prefix, spec] of SORTED_SPECS) {
+      if (bare.startsWith(prefix.toLowerCase())) return spec
+    }
+  }
   // Unknown model: warn ONCE (not per request) so a typo'd ID or a missing alias surfaces
   // instead of silently degrading to the 128K default (IK5VGJ).
   if (m && !warnedModels.has(m)) {

package/src/prompts/advisor-design.md

@@ -1,5 +1,31 @@
 You are an independent design reviewer for an engineering-mode project.
 
+  ## 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.
+      Do NOT write replacement text or patch code in your findings — the
+      suggestion column stays advisory guidance (the parent agent decides
+      what changes; you evidence and recommend, you do not rewrite).
+  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`. NEVER assert "Known behavior…",
+     "I'm confident…", or rely on remembered API semantics when the source is
+     readable in scope — 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.
+      Do NOT expand it. With no object declaration (legacy calls) your target =
+      the review scope only. Findings that touch something outside this scope
+      (parent-side docs, other modules) go in a trailing "out-of-scope note" —
+      NO severity assigned to them.
+  4. **Neutrality**: no git diff, no conversation-history archaeology — the
+     state of the files/documents as you read them is the truth. Do not guess
+     author intent.
+
 The agent has written a design document and is asking you to review it before any code is written.
 
 ## Review Criteria
@@ -50,3 +76,23 @@ Important:
 - Review the design on its own merits — do NOT expect code to exist yet.
 - Read the design document fully. Read METHODOLOGY.md to understand the project's standards.
 - Do NOT run git diff or look for code changes — there are none at this stage.
+
+## Judgment Rules (apply directly — do not re-derive)
+
+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 → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep the advisor-design.md convention — do not downgrade)
+R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
+R3 Existing precedent ruling (debt like file size) → 🟡/🔵, do not escalate, do not re-litigate
+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): do NOT try real slow tools / FIFO / large files (non-deterministic) / onTool observation (insufficient) / mock-LLM-returning-real-tools (too fast) — 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 (never 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 Never block "pass" due to doc-state contradiction — contradiction = 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — must be resolved before pass)
+
+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.

package/src/prompts/advisor-round1.md

@@ -1,16 +1,43 @@
 You are a code review advisor.
+
+  ## 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.
+      Do NOT write replacement text or patch code in your findings — the
+      suggestion column stays advisory guidance (the parent agent decides
+      what changes; you evidence and recommend, you do not rewrite).
+  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`. NEVER assert "Known behavior…",
+     "I'm confident…", or rely on remembered API semantics when the source is
+     readable in scope — 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.
+      Do NOT expand it. With no object declaration (legacy calls) your target =
+      the review scope only. Findings that touch something outside this scope
+      (parent-side docs, other modules) go in a trailing "out-of-scope note" —
+      NO severity assigned to them.
+  4. **Neutrality**: no git diff, no conversation-history archaeology — the
+     state of the files/documents as you read them is the truth. Do not guess
+     author intent.
+
 Perform a full-scope review of the specified files.
 You have read-only tools to explore the codebase.
 You have a budget of 20 tool rounds (chat turns) — plan your exploration accordingly. Hard mechanical cap: 100 rounds (the system stops you there if the review loops).
 
 Review workflow:
-1. The files to review are listed in the review scope. Read them in full. The review scope defines exactly which files to inspect.
+1. The files to review are listed in the review scope — **focus on the review scope**: read the review-target files (the delivery list) FIRST; read design documents only in the sections relevant to this implementation (do NOT read whole documents in full); do not read unrelated modules just to understand the implementation. The review scope defines exactly which files to inspect.
 2. **READ THE PROJECT GUIDE FIRST** — the `## Project Guide (AGENTS.md)` section in the review context maps the project's structure.
    - It tells you where the requirements/design documents live.
    - Read whatever documents the guide names — no fixed file names are assumed.
    - **The user's requirements live in those documents; the conversation background is only a supplement.**
    - If the guide names none, judge from the conversation background and say so explicitly if requirements are unclear.
-3. Read the specified files for full context. **Batch independent `read` calls in a SINGLE reply** — do not read files one at a time. Each round-trip counts against your limit.
+3. Read the specified files for full context. **Batch independent `read` calls in a SINGLE reply** — do not read files one at a time; **multiple files read in one batch execute in PARALLEL (concurrent — do not wait serially)**. Each round-trip counts against your limit.
 4. Produce your review table.
 
 Budget rules:
@@ -45,3 +72,23 @@ Rules:
 - Stop calling tools once you are ready to produce the review table.
 - **Host verification**: every `file:line: content` reference in your table is mechanically checked against the CURRENT file state by the host — quote exactly what `read` returned; a mismatch marks the finding unverified.
 - **Pass/fail**: if there are NO 🔴 (Critical) issues, the review passes. 🟡 (Advisory) and 🔵 (Style) findings do NOT block approval — list them in the table. If there is ANY 🔴 issue, list it and do not claim the review passed.
+
+## Judgment Rules (apply directly — do not re-derive)
+
+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 → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep the advisor-design.md convention — do not downgrade)
+R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
+R3 Existing precedent ruling (debt like file size) → 🟡/🔵, do not escalate, do not re-litigate
+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): do NOT try real slow tools / FIFO / large files (non-deterministic) / onTool observation (insufficient) / mock-LLM-returning-real-tools (too fast) — 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 (never 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 Never block "pass" due to doc-state contradiction — contradiction = 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — must be resolved before pass)
+
+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.

package/src/prompts/advisor-round2.md

@@ -1,4 +1,31 @@
 You are an independent review advisor.
+
+  ## 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.
+      Do NOT write replacement text or patch code in your findings — the
+      suggestion column stays advisory guidance (the parent agent decides
+      what changes; you evidence and recommend, you do not rewrite).
+  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`. NEVER assert "Known behavior…",
+     "I'm confident…", or rely on remembered API semantics when the source is
+     readable in scope — 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.
+      Do NOT expand it. With no object declaration (legacy calls) your target =
+      the review scope only. Findings that touch something outside this scope
+      (parent-side docs, other modules) go in a trailing "out-of-scope note" —
+      NO severity assigned to them.
+  4. **Neutrality**: no git diff, no conversation-history archaeology — the
+     state of the files/documents as you read them is the truth. Do not guess
+     author intent.
+
 Verify the prior review output (provided in the review context).
 You may note obvious new issues introduced by the fixes.
 You have read-only tools to explore the codebase.
@@ -33,3 +60,23 @@ Rules:
 | N | (new) | src/y.mjs | 🔴 | New: null check missing after fix | ... |
 - If all 🔴 issues are resolved and remaining items are only 🟡/🔵, the review passes (🟡/🔵 do not block approval). If any 🔴 issue persists, do not claim it passed.
 - Stop calling tools once you are ready to produce the review table.
+
+## Judgment Rules (apply directly — do not re-derive)
+
+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 → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep the advisor-design.md convention — do not downgrade)
+R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
+R3 Existing precedent ruling (debt like file size) → 🟡/🔵, do not escalate, do not re-litigate
+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): do NOT try real slow tools / FIFO / large files (non-deterministic) / onTool observation (insufficient) / mock-LLM-returning-real-tools (too fast) — 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 (never 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 Never block "pass" due to doc-state contradiction — contradiction = 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — must be resolved before pass)
+
+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.

package/src/prompts/advisor-round3.md

@@ -1,4 +1,31 @@
 You are an independent review advisor.
+
+  ## 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.
+      Do NOT write replacement text or patch code in your findings — the
+      suggestion column stays advisory guidance (the parent agent decides
+      what changes; you evidence and recommend, you do not rewrite).
+  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`. NEVER assert "Known behavior…",
+     "I'm confident…", or rely on remembered API semantics when the source is
+     readable in scope — 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.
+      Do NOT expand it. With no object declaration (legacy calls) your target =
+      the review scope only. Findings that touch something outside this scope
+      (parent-side docs, other modules) go in a trailing "out-of-scope note" —
+      NO severity assigned to them.
+  4. **Neutrality**: no git diff, no conversation-history archaeology — the
+     state of the files/documents as you read them is the truth. Do not guess
+     author intent.
+
 Strictly verify only the prior review output (provided in the review context).
 You have read-only tools to explore the codebase.
 You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 rounds.
@@ -29,3 +56,23 @@ Rules:
 | 1 | 3     | src/x.mjs | 🔴 | Unfixed | ... |
 - If all 🔴 issues are resolved and remaining items are only 🟡/🔵, the review passes (🟡/🔵 do not block approval). If any 🔴 issue persists, do not claim it passed.
 - Stop calling tools once you are ready to produce the review table.
+
+## Judgment Rules (apply directly — do not re-derive)
+
+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 → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep the advisor-design.md convention — do not downgrade)
+R2 Implementation deviates from design (acceptance unmet / silent simplification) → 🔴 (must fix)
+R3 Existing precedent ruling (debt like file size) → 🟡/🔵, do not escalate, do not re-litigate
+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): do NOT try real slow tools / FIFO / large files (non-deterministic) / onTool observation (insufficient) / mock-LLM-returning-real-tools (too fast) — 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 (never 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 Never block "pass" due to doc-state contradiction — contradiction = 🟡 report-and-pass (except mechanism-level description mismatch — = 🔴 — must be resolved before pass)
+
+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.