@thincoder/core 0.9.1

package/advisor/loop.mjs

@@ -0,0 +1,288 @@
+/**
+ * advisor/loop.mjs — advisor tool loop: chat → execute tools → repeat, plus the
+ * review timeline (split out of advisor/run.mjs, 第 11 批 — run.mjs was 498/500
+ * 硬帽；拆分保持既有 import 面：run.mjs 继续 re-export 本文件导出）。
+ *
+ * 第 11 批（F15/§14.6）：每次 chat 调用携带硬墙信号（`AbortSignal.any([signal,
+ * AbortSignal.timeout(remaining)])`；墙判定绑信号状态——抛错 / partial 两形态同判），
+ * 并按 0.75 一次性预算提示 + 结构化超时尾收尾；守卫与限额函数在 compaction.mjs。
+ */
+import { chat } from "../provider/core.mjs"
+import { providerSpec, assistantToolCallMessage } from "../config.mjs"
+import { toOpenAISchema } from "../tools/index.mjs"
+import { truncateAdvisorResult } from "./truncate.mjs"
+import { batchSegmentTool } from "../agent-tools/batch-segment.mjs"
+import {
+  estimateTokens, compactMessages, shouldBudgetNudge, budgetNudgeText, timeoutTail, renderTimeline,
+  MAX_ADVISOR_TURNS, advisorContextBudget, TOOL_TIMEOUT_MS, REVIEW_TIMEOUT_MS, MAX_RESULT_CHARS,
+  ADVISOR_THINKING_PLACEHOLDER,
+} from "./compaction.mjs"
+
+const { readTool, globTool, grepTool, lsTool } = await import("../tools/index.mjs")
+const { lspTool } = await import("../tools/lsp.mjs")
+const { codeSearchTool } = await import("../memory/code-sync.mjs")
+
+/**
+ * Advisor tool set — ZERO git, read-only ONLY, every round. The change surface comes from the
+ * review scope (paths / _touchedFiles injected by the caller), never from git: git output misled
+ * reviews (committed fixes never show in `git diff HEAD`, so "no changes" was read as "not
+ * fixed") and the user mandate is full decoupling (7d49a52 + d3be613). The reviewer reads files
+ * and searches code; it never touches git and never writes. No round parameter — the set is
+ * constant across all rounds. 检索面**恒在**（与索引绑定解耦）：`code_search` 永远在集内，
+ * 未绑定索引的会话在**执行面**降级为一句端中立说明（不崩、不伪造结果）——工具清单恒定。
+ * @param {Object} agent — 索引面载体（`agent.memory`）；缺省时执行面降级。
+ */
+function advisorCodeSearchTool(agent) {
+  return agent?.memory
+    ? codeSearchTool(agent.memory)
+    : { ...codeSearchTool(undefined), async execute() { return "(code index not available in this session)" } }
+}
+
+function advisorToolsFor(agent, reviewType = "code", batchDoc = null) {
+  const tools = [readTool, globTool, grepTool, lsTool, lspTool, advisorCodeSearchTool(agent)]
+  // §2.20.3（第 4 批）：**只有绑定了批次档的设计评审**额外拿到写通道——代码评审工具集
+  // 逐字节不变（零 git + 只读不变量，§2.20.8 #1）；未绑定 → 不挂载（fail-closed）。
+  if (reviewType === "design" && batchDoc) tools.push(batchSegmentTool(batchDoc, { review: true }))
+  return { schemas: tools.map(toOpenAISchema), byName: new Map(tools.map((t) => [t.name, t])) }
+}
+// Test seam: the tool set is pure（恒在六工具 + 批次档绑定條件）。
+export { advisorToolsFor, advisorToolsFor as _advisorToolsFor }
+
+/**
+ * Run the advisor's tool loop: chat → execute tools → repeat.
+ * Stops when the model produces text without tool calls.
+ *
+ * Progress lines (→ tool args) are emitted via onOutput between model bursts so
+ * the panel keeps moving while the advisor explores — otherwise the panel sits
+ * frozen through every tool-call phase and the review appears to have stalled.
+ *
+ * @param {string|null} [pinned] — 第 11 批：压缩定锚简报（评审参数构建——F13/§14.4 #3）。
+ * @param {{now?: Function, chat?: Function, describeArgs?: Function}} [seams] — 测试缝 + ④ 端差注入点
+ *   （默认 Date.now / chat / 无进度行——生产调用不传时进度行由端装配层补齐）。
+ */
+async function runAdvisorToolLoop(provider, messages, onOutput, signal, agent, cwd, toolsOverride = null, reviewType = "code", batchDoc = null, pinned = null, seams = {}) {
+  const now = seams.now ?? Date.now
+  const chatCall = seams.chat ?? chat
+  // ④ 端差注入点（CORE-UNIFICATION §2.5 #109「进度行按端注入」）：工具进度行的参数摘要
+  // 是**展示面**（CLI = `tui/tool-args.mjs` 的 `describeToolArgs`；VSC = 卡片头），不进核。
+  // 未注入 ⇒ 不发进度行（核内零端名分支——契约 5 / 10）。端在装配层传入自己的格式化器。
+  const describeArgs = seams.describeArgs ?? (() => "")
+  // 第 11 批硬墙 / 预算 / 尾：实现注解见下方各点；守卫函数与 renderTimeline 在 compaction.mjs。
+  // Kind-tagged wrappers: the TUI panel colors reasoning / answer / tool progress differently.
+  // Every chunk is ALSO recorded into an ordered timeline — the persisted record
+  // must show the review process (thinking ↔ tool progress ↔ final text) at its
+  // real positions, not a summary appended at the end. Same-kind consecutive
+  // chunks merge (token streams); kind flips start a new entry.
+  const timeline = []
+  const record = (kind, text) => {
+    const last = timeline.at(-1)
+    if (last && last.kind === kind) last.text += text
+    else timeline.push({ kind, text })
+  }
+  const emit = (kind) => (text) => { record(kind, text); onOutput?.({ kind, text }) }
+  const onThink = emit("think")
+  const onText = emit("text")
+  const onTool = emit("tool")
+  // toolsOverride = test seam (T-TS8/9): the real advisor tool set, or a mock
+  // set with controllable timing/errors.
+  const { schemas: toolSchemas, byName: toolByName } = toolsOverride ?? advisorToolsFor(agent, reviewType, batchDoc)
+  let turns = 0
+  let toolCallCount = 0
+  let reviewTextProduced = false
+  let budgetNudged = false
+  const startTime = now()
+  // 第 25 批（§16.3）：上下文预算跟随评审模型窗口——`providerSpec`（模型规格表 × provider 级
+  // context 覆盖）派生；函数体内、while 轮次外一次性（provider 全场不变），两档消费见下守卫。
+  const budget = advisorContextBudget(provider)
+
+  while (true) {
+    // Interrupted (Ctrl+I) — stop immediately instead of spinning a fresh uncancellable signal
+    if (signal?.aborted) return renderTimeline(timeline, "Advisor: interrupted.")
+    
+    // Check review timeout (10 minutes by default; agent.advisor.timeoutMs overrides)
+    // 运行时校验（设计评审 #1，2026-08-24）：手写 config.json 的非法值（0/负数/字符串）
+    // 不得静默禁用或立即触发超时——非法一律回退默认。
+    const cfg = agent.config?.advisor?.timeoutMs
+    const timeoutMs = (Number.isFinite(cfg) && cfg > 0) ? cfg : REVIEW_TIMEOUT_MS
+    const elapsed = now() - startTime
+    const remaining = timeoutMs - elapsed
+    // 硬墙（§14.6 #1）：预算用尽 → 结构化超时尾（首行 = 判定族 timeout 前缀）。
+    if (remaining <= 0) {
+      return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+    }
+    // 0.75 一次性预算提示（§14.6 #2——同一检查点、每场评审至多一次）：注入一条 user 消息
+    // 促模型在墙前收敛产出（不改语义判据、不碰提示词面）。
+    if (shouldBudgetNudge(elapsed, timeoutMs, budgetNudged)) {
+      budgetNudged = true
+      messages.push({ role: "user", content: budgetNudgeText(elapsed, timeoutMs) })
+    }
+    
+    if (++turns > MAX_ADVISOR_TURNS) {
+      return renderTimeline(timeline, "Advisor: stopped after " + MAX_ADVISOR_TURNS + " tool rounds — the review appears to be looping. You may retry with a narrower scope.")
+    }
+    
+    // Check context window and compact if needed
+    const currentTokens = estimateTokens(messages)
+    if (currentTokens > budget.compactAt) {
+      onText(`\n[Context compacted: ${currentTokens} tokens → reducing to fit window]\n`)
+      compactMessages(messages, pinned)
+      if (estimateTokens(messages) > budget.limit) {
+        // Report the POST-compaction count — the pre-compaction currentTokens
+        // is stale by the time compaction has run.
+        return renderTimeline(timeline, `Advisor: context window limit reached (${estimateTokens(messages)} tokens). Review incomplete — too many tool calls. Try a narrower scope.`)
+      }
+    }
+    
+    // LLM generation silence: the reasoning phase produces no SSE bytes for
+    // seconds to tens of seconds (server-side prefill on large contexts, per
+    // tool-round LLM return). A placeholder keeps the panel visibly working.
+    // kind "think" (NOT "text"): the placeholder must land in the SAME buffer
+    // and position as the upcoming reasoning — a "text"-kind placeholder
+    // rendered BELOW the think block, and the reasoning stream appeared ABOVE
+    // it ("the stream runs back to the front"). Same buffer = same spot; the
+    // reasoning continues right where the placeholder sits.
+    onOutput?.({ kind: "think", text: ADVISOR_THINKING_PLACEHOLDER })
+
+    // 硬墙（§14.6 #1）：单次请求信号 = 用户信号 × 本调用 deadline（remaining）。复合信号
+    // 无条件传入（上层检查与本调用之间的中止仍必须取消请求——已 aborted 的 composite 使请求
+    // 立即失败）；此处改正了原指向 provider/core.mjs 组合 AbortSignal 的陈旧注释（§14.10 #3）。
+    const callSignal = signal
+      ? AbortSignal.any([signal, AbortSignal.timeout(remaining)])
+      : AbortSignal.timeout(remaining)
+    let response
+    try {
+      response = await chatCall(provider, {
+        messages,
+        tools: toolSchemas,
+        signal: callSignal,
+        onToken: (t) => { if (String(t ?? "").trim()) reviewTextProduced = true; onText(t) },
+        onReasoning: onThink,
+        // LOGGING（vscode advisor/run.mjs parity——按 stage 可 grep）
+        // §18.6 D-TR4：轨迹元数据增补——kind=advisor（评审独立于子代理——T-TR2）；role
+        // 透出调用方角色（eng-coder 内嵌评审时为 "eng-coder"）；session/cwd 供轨迹对回；
+        // traces 开关沿 agent.config（D-TR6）。
+        logCtx: {
+          stage: "advisor",
+          role: agent?._role ?? null,
+          kind: "advisor",
+          session: agent?._sessionStart ?? null,
+          cwd,
+          traces: agent?.config?.traces?.enabled !== false,
+        },
+      })
+    } catch (e) {
+      // 墙判定绑信号状态（§14.6 #1——非异常名）：① 用户信号已中止 ⇒ 原样上抛（中断语义
+      // 零变）；② 复合信号已中止（墙触发）而用户信号未中止 ⇒ 结构化超时尾（形态①：抛错；
+      // AbortError / TimeoutError 两名兜底——AbortSignal.timeout 的 reason 是 TimeoutError
+      // DOMException）；③ 其余错误原样上抛（runAdvisorReview 的失败分类不变）。
+      if (signal?.aborted) throw e
+      if (callSignal.aborted || e?.name === "AbortError" || e?.name === "TimeoutError") {
+        return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+      }
+      throw e
+    }
+    if (signal?.aborted) return renderTimeline(timeline, "Advisor: interrupted.")
+    // 形态②（§14.6 #1）：不抛错而返回 partial（流已有内容时中断以 partial:true 透传）——
+    // 不得按普通结果收尾：墙触发（复合信号已中止）同判。
+    if (callSignal.aborted && response?.partial) {
+      return renderTimeline(timeline, timeoutTail(timeoutMs, turns, toolCallCount, reviewTextProduced))
+    }
+
+    // No tool calls — this is the final review text. The final answer was
+    // already streamed into the timeline via onText; fall back to
+    // response.content only if nothing was recorded.
+    if (!response.toolCalls?.length) {
+      if (!response.content?.trim()) return renderTimeline(timeline) || "Advisor: empty response — review was inconclusive"
+      return renderTimeline(timeline) || response.content.trim()
+    }
+
+    // Push assistant message with tool calls. reasoning_content ECHO is
+    // mandatory for reasoningEcho:"required" providers (deepseek/kimi): the
+    // server stops returning reasoning_content on later rounds when the
+    // tool-call assistant history lacks it — the observed "reasoning stops
+    // after the first tool call, returns only at the final answer" symptom.
+    // Mirrors the main agent's push (agent.mjs).
+    messages.push(assistantToolCallMessage(response, providerSpec(provider)))
+
+    // B1 (AGENT-LOOP.md §18.7 D-TS7): the SAME LLM reply's multiple read-only
+    // tool calls run in PARALLEL (Promise.all) — results are backfilled in
+    // toolCalls order (Promise.all preserves the input order → tool_call_id
+    // never mismatches); each tool's timeout/error is captured independently
+    // (the existing TOOL_TIMEOUT stays — one failing tool does not block the
+    // others); progress lines are emitted in toolCalls order. The read-only
+    // tool set has no side effects — no sequencing/serialization needed.
+    // Scope note (round1 review #10): B1 is ONLY in-loop tool parallelism — it
+    // does NOT solve the TODO "platform execution: advisor parallel calls are
+    // actually serial" mystery (docs/TODO.md — LOGGING evidence item), which
+    // concerns multiple advisor CALLS observed as serial, not one reply's
+    // tool calls.
+    const parsed = response.toolCalls.map((tc) => {
+      const tool = toolByName.get(tc.name)
+      let args = {}
+      let parseError = null
+      try {
+        args = JSON.parse(tc.arguments || "{}")
+      } catch (e) {
+        parseError = `Error: invalid JSON in tool arguments: ${e.message}\nRaw arguments: ${(tc.arguments || "").slice(0, 200)}`
+      }
+      return { tc, tool, args, parseError }
+    })
+    toolCallCount += parsed.length
+    // Progress lines first, in toolCalls order (emitted before the parallel
+    // run — display order is independent of completion order).
+    for (const p of parsed) {
+      if (p.parseError) continue // parse-error tools get no progress line (legacy behavior)
+      const argsLine = describeArgs(p.tc.name, p.args)
+      onTool(`\n→ ${p.tc.name}${argsLine ? " " + argsLine : ""}\n`)
+    }
+    // Every tool runs CONCURRENTLY; each result/error lands in its own slot —
+    // Promise.all preserves input order, so index i always matches parsed[i].
+    const executed = await Promise.all(parsed.map(async (p) => {
+      // Parse failure → error to model immediately (no execution)
+      if (p.parseError) return p.parseError
+      if (!p.tool) return `Error: unknown tool "${p.tc.name}". Available: ${[...toolByName.keys()].join(", ")}`
+      // Execute with timeout (clear the timer when the tool wins the race —
+      // otherwise up to MAX_ADVISOR_TURNS dangling timers accumulate)
+      try {
+        let timeoutId
+        const timeoutPromise = new Promise((_, reject) => {
+          timeoutId = setTimeout(() => reject(new Error(`tool timeout after ${TOOL_TIMEOUT_MS}ms`)), TOOL_TIMEOUT_MS)
+        })
+        let toolPromise
+        try {
+          toolPromise = p.tool.execute(p.args, { cwd, agent, onOutput, signal })
+          return await Promise.race([toolPromise, timeoutPromise])
+        } finally {
+          clearTimeout(timeoutId)
+          // Timeout won → toolPromise is still pending; a later rejection
+          // would surface as an unhandled rejection. The race already
+          // consumed the result/error in the normal path, so this no-op
+          // catch only fires for the abandoned-tool case.
+          toolPromise?.catch(() => {})
+        }
+      } catch (e) {
+        const errorType = e.message.includes("timeout") ? "timeout"
+          : e.message.includes("ENOENT") ? "file_not_found"
+          : e.message.includes("permission") ? "permission_denied"
+          : "execution_error"
+        return `Error (${errorType}): ${e.message}`
+      }
+    }))
+
+    // Backfill in toolCalls order (executed[i] ↔ parsed[i]); per-result
+    // non-string serialization + dual-end line-aware truncation stay per-tool
+    // (DUAL-END-TRUNCATION F-2 — truncate.mjs: head ≈60% + tail ≈40% — keep the
+    // tail verdicts; ≤ MAX_RESULT_CHARS results pass through untouched).
+    for (let i = 0; i < parsed.length; i++) {
+      let result = executed[i]
+      if (typeof result !== "string") result = JSON.stringify(result)
+
+      result = truncateAdvisorResult(result, MAX_RESULT_CHARS)
+
+      messages.push({ role: "tool", tool_call_id: parsed[i].tc.id, content: result })
+    }
+  }
+}
+// Test seam (T-TS8/9): the tool loop itself — toolsOverride injects a mock tool
+// set with controllable timing/errors (the real set comes from advisorToolsFor).
+export { runAdvisorToolLoop, runAdvisorToolLoop as _runAdvisorToolLoop }

package/advisor/messages.mjs

@@ -0,0 +1,299 @@
+/**
+ * advisor/messages.mjs — advisor user-message building (buildAdvisorUserMessage).
+ * Split out of advisor.mjs to keep it under the 300-line advisory threshold
+ * (.thincoder/advisor.md). System prompts live in advisor.mjs / prompts/.
+ * Project-context discovery/injection lives in project-context.mjs (the D-1 registration,
+ * ENGINEERING-MODE.md §2.26.3); the pre-split surface is re-exported below.
+ */
+import { join, relative, sep } from "node:path"
+import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
+import { buildConvergenceBody, buildConvergenceInstructions } from "./convergence.mjs"
+import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable } from "./history.mjs"
+import { injectProjectGuide, injectDocumentMap, injectProjectStandards, NO_GIT_NOTICE } from "./project-context.mjs"
+
+// Structural split (not an authority migration): the moved helpers stay reachable here.
+export { findProjectRoot, injectProjectGuide } from "./project-context.mjs"
+
+/**
+ * Build the mechanical review-object declaration block (AGENT-LOOP.md §18.8
+ * D-OA2 — English anchored form). Injected at the START of the review user
+ * message every round: round 1 (design + code), the legacy convergence path,
+ * and the round-2+ follow-up (see buildAdvisorFollowUp) — the reviewer must
+ * not re-derive "who is being reviewed / why" from the documents (T-OA2:
+ * every round stays anchored). Absent object → "" (legacy calls degrade to
+ * the current behavior — T-OA3).
+ * @param {Object|null} [object] — { type, target, status, reason, exclude }
+ *   (strings; `exclude` may also be a list — joined with ", ")
+ * @returns {string} the declaration block (empty when no object)
+ */
+export function buildObjectDeclarationBlock(object = null) {
+  if (!object || typeof object !== "object" || Array.isArray(object)) return ""
+  const field = (v) => (Array.isArray(v) ? v.join(", ") : v == null ? "" : String(v))
+  return [
+    "## Review-object declaration (mechanical — do not infer)",
+    `Review type: ${field(object.type)} | Target: ${field(object.target)} | Object state: ${field(object.status)} | Trigger: ${field(object.reason)}`,
+    `Excluded (not in this review): ${field(object.exclude)}`,
+    "Follow this declaration — do not infer the review target from the documents.",
+    "",
+  ].join("\n")
+}
+
+/**
+ * Approval-signal block for design reviews (round 1 and round 2+ — §11.2 D-24b:
+ * an async fix-round continuation must be able to re-approve, so the token is
+ * injected into EVERY design round; the reviewer echoes it only on a clean pass).
+ * §29.1 F2a (2026-09-07): BOTH values are injected — the token AND the designId
+ * (anchor sentence verbatim — Copy BOTH values). designId null (legacy direct
+ * callers without a resolved instance) degrades to the token-only form.
+ */
+export function buildDesignApprovalBlock(designToken, designId) {
+  const echo = designId
+    ? `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}] and this exact designId: ${designId}. Copy BOTH values verbatim.`
+    : `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}]`
+  return [
+    "## Approval Signal",
+    echo,
+    "🟡 (Advisory) and 🔵 (Note) findings do NOT block approval — list them if present, but still include the token. If there are any 🔴 issues, do NOT include the token.",
+  ].join("\n")
+}
+
+/**
+ * Build the user message for an advisor review session.
+ * @param {Object} agent — the parent agent
+ * @param {Object|null} [prior] — prior issue table
+ * @param {string} [reviewType] — "design" or "code" (已由工具层类型门定轨——此处无缺省；F30)
+ * @param {string|null} [designToken] — token injected into the design-review prompt; the advisor echoes it only on approval
+ * @param {string[]|null} [documents] — design review only: explicit list of doc paths to review (requirements + design + referenced docs).
+ *   When set, the review input is built from this list ONLY — no git-diff change-set collection.
+ *   When absent, the legacy git-diff-based scope is kept (backward compatible).
+ * @param {string[]|null} [paths] — code review only: explicit list of file/dir paths to review (deduped; shown under Review Scope)
+ * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1/D-OA3):
+ *   { type, target, status, reason, exclude } — mechanically injected at the
+ *   start of the user message; absent → no injection (legacy calls unchanged).
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the token in the
+ *   Approval Signal (both values — the reviewer copies both verbatim); null →
+ *   token-only degradation (legacy direct callers).
+ * @returns {string} the user message
+ */
+export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null, object = null, designId = null) {
+  const body = buildAdvisorUserMessageInner(agent, prior, reviewType, designToken, documents, paths, object, designId)
+  // B 构建自愈（F12/§14.4 #1）：design + token 且输出不含逐字信号 ⇒ 尾包补齐 Approval Signal。
+  // 覆盖所有出口（含 code 形态分支降级态与 legacy 收敛分支）——既有分支语义零改：已在分支内
+  // 注入过的路径因 `[DESIGN-TOKEN:{token}` 逐字在场而不重复追加（幂等）。
+  if (reviewType !== "design" || !designToken) return body
+  if (body.includes(`[DESIGN-TOKEN:${designToken}`)) return body
+  return `${body}\n\n${buildDesignApprovalBlock(designToken, designId)}`
+}
+
+/** 内层构建（无自愈尾包）——出口、分支与消息形态与拆分前逐字一致。 */
+function buildAdvisorUserMessageInner(agent, prior, reviewType, designToken = null, documents = null, paths = null, object = null, designId = null) {
+  // prior = the full prior review output (string) when a convergence round is
+  // being built (decision 2026-08-08 — verbatim injection, model understands it).
+  // Deterministic: only _advisorRound > 0 with stored output counts.
+  const p = prior ?? ((agent._advisorRound || 0) > 0 ? agent._lastAdvisorOutput : null)
+
+  const parts = []
+  // Review-object declaration FIRST — D-OA1: at the start of the user message
+  // (after the system prompt, before the review content). Covers round 1
+  // design/code and the legacy convergence path; the round-2+ normal path
+  // prepends it in buildAdvisorFollowUp (T-OA2 — every round stays anchored).
+  const declaration = buildObjectDeclarationBlock(object)
+  if (declaration) parts.push(declaration)
+  const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
+  const pathList = Array.isArray(paths) ? [...new Set(paths.filter((p) => typeof p === "string" && p.trim()))] : []
+
+  // Project guide FIRST in EVERY review path (code AND design round 0): the map
+  // to the requirements docs is needed for design reviews too (design must fit
+  // the requirements, not just the methodology). Design round 0 early-returns
+  // below — the guide must be injected before that return. Project root is
+  // discovered from the review scope (code paths AND design-doc paths, so a
+  // documents-only design review still finds the subproject guide).
+  const guideRoot = injectProjectGuide(agent, parts, [...pathList, ...docList])
+
+  // Design review: simplified message — focus on the design doc, not code
+  if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
+    const repos = findReviewRepos(agent)
+    parts.push("## Design Review")
+    // FR15/P8: no git → change-set context is unavailable. Say it (never silent).
+    if (repos.length === 0) {
+      parts.push(NO_GIT_NOTICE)
+      parts.push("")
+    }
+    if (docList.length > 0) {
+      // Explicit review scope (engineering mode, FR2): the caller hands over the
+      // doc list — the advisor reviews ONLY these. No git-diff change-set
+      // collection: diff-based discovery reviewed unrelated files, and untracked
+      // design docs were invisible to git diff anyway (ENGINEERING-MODE.md §2.4).
+      parts.push("The documents below are the review scope. Review ONLY these files — do not scan git diff or read any other files.")
+      parts.push("")
+      parts.push("## Documents to Review")
+      parts.push(docList.map((d) => `- ${d} — Read this file in full`).join("\n"))
+      parts.push("")
+    } else {
+      // Backward-compatible fallback (no documents): discover docs via git status/diff.
+      parts.push("The following changes are a design document. Review it against the project's methodology.")
+      parts.push("")
+
+      // List changed file paths explicitly — new design docs are untracked,
+      // so git diff HEAD won't show their content; the advisor must read the file itself
+      const changedFiles = collectChangedFiles(repos, agent.cwd)
+      if (changedFiles.length > 0) {
+        parts.push("## Changed Files")
+        parts.push(changedFiles.map((f) => `- ${f}`).join("\n"))
+        parts.push("")
+        parts.push("Read each changed file in full — untracked files are not shown in the diff below.")
+        parts.push("")
+      }
+
+      // Pre-collected changes — the design doc diff.
+      const snapshots = collectRepoSnapshots(repos, agent.cwd)
+      if (snapshots.length > 0) {
+        parts.push("## Design Document (git diff)")
+        parts.push(...snapshots)
+        parts.push("")
+      }
+    }
+
+    // Engineering mode: the project's DECLARED standards document
+    // (advisor.standardsDoc) — undeclared degrades visibly (PO-2).
+    if (agent.config?.agent?.engineering) {
+      injectProjectStandards(agent, parts, guideRoot)
+    }
+
+    // Document map: declared path wins, the built-in fallback probe (docs/README.md
+    // → docs/design/README.md) stays; neither → explicit degradation sentence
+    // (never the old silent skip).
+    injectDocumentMap(agent, parts, guideRoot ?? agent.cwd)
+
+    parts.push("## Instructions")
+    if (docList.length > 0) {
+      parts.push("1. Read every document in the Documents to Review list in full — review ONLY those files.")
+    } else {
+      parts.push("1. Read the design document fully.")
+    }
+    parts.push("2. Review against: completeness (all requirements covered?), feasibility (can this be built?), methodology compliance (does it follow the project's standards as provided?), clarity (specific enough?), acceptance criteria (verifiable?), scope (appropriate?).")
+    parts.push("3. If the ## Project Guide (AGENTS.md) section above is present, also check requirement fit: does the design match what the requirements documents it points to actually ask for?")
+    parts.push("4. Do NOT run git diff or look for code changes — there are none at this stage.")
+    parts.push("5. If you find issues, produce your review table with the format: | # | Category | Severity | Issue | Suggestion |. If the design passes, no table is needed.")
+    if (designToken) {
+      parts.push("")
+      parts.push(buildDesignApprovalBlock(designToken, designId))
+    }
+    return parts.join("\n")
+  }
+
+  // Convergence data (round 2+). LEGACY COMPATIBILITY PATH: the normal advisor
+  // flow routes convergence rounds through buildAdvisorFollowUp (fresh session,
+  // decision d698434); this block only fires for direct external callers of
+  // buildAdvisorUserMessage with a stored prior review output. Kept to avoid
+  // breaking those. Same rule as buildAdvisorFollowUp: the FULL prior review
+  // output is injected verbatim (decision 2026-08-08 — the model understands it;
+  // no table/header/phrase parsing).
+  // NOTE: this legacy path does NOT apply escapeLiteralEscapes (that lives in
+  // advisor.mjs and importing it here would create a top-level module cycle).
+  // Direct callers must escape the injected output themselves if the parent
+  // conversation can quote literal "\x"/"\u" sequences (server 400 risk).
+  if (p && (agent._advisorRound || 0) > 0) {
+    const scopeFiles = resolveScopeFiles(agent, paths)
+    const response = extractAgentResponseTable(agent.history)
+      || (scopeFiles?.length
+        ? "(Agent did not provide a response table — perform a fresh review of: " + scopeFiles.slice(0, 10).join(", ") + ")"
+        : "(Agent did not provide a response table — perform a fresh review of the files named in the system prompt context)")
+    const round = (agent._advisorRound || 0) + 1
+    parts.push(buildConvergenceBody(p, response, round, scopeFiles))
+    parts.push("")
+    parts.push("---")
+    parts.push("")
+  }
+
+  if (pathList.length > 0 || docList.length > 0) {
+    parts.push("## Review Scope")
+  }
+  if (pathList.length > 0) {
+    parts.push("Review these code files/directories — read them in full for context:")
+    parts.push("")
+    parts.push(pathList.map((p) => `- ${p}`).join("\n"))
+    parts.push("")
+  }
+  if (docList.length > 0) {
+    if (reviewType === "design") {
+      parts.push("The documents below are the review scope. Review ONLY these files — do NOT scan git diff or read any other files.")
+    } else {
+      parts.push("The documents below define acceptance criteria and review context. Read them for context, then read the code files specified in the review scope. Judge the implementation against these documents.")
+    }
+    parts.push("")
+    parts.push("## Documents to Review")
+    parts.push(docList.map((d) => `- ${d} — Read this file in full`).join("\n"))
+    parts.push("")
+  }
+
+  // Conversation background — recent user↔assistant exchanges for intent context
+  const background = extractConversationBackground(agent.history)
+  if (background) {
+    parts.push("## Conversation Background (recent turns)")
+    parts.push(background)
+    parts.push("")
+  }
+
+  // Review criteria
+  const criteria = loadAdvisorMd(agent.cwd)
+  parts.push("## Review Criteria")
+  parts.push(criteria)
+  if (guideRoot) {
+    // Requirement-fit is a first-class dimension when the project guide was
+    // found — the criteria file (advisor.md) may not mention it (legacy).
+    parts.push("")
+    parts.push("Additional criterion: **requirement fit** — does the implementation match what the requirements documents (referenced by the Project Guide above) actually ask for?")
+  }
+  parts.push("")
+
+  // Engineering mode: project standards (declaration-only, same helper as the
+  // design path) — undeclared degrades visibly (PO-2).
+  if (agent.config?.agent?.engineering) {
+    injectProjectStandards(agent, parts, guideRoot)
+  }
+
+  // Instructions — round-aware: re-reviews skip convention discovery entirely.
+  // These are SUPPLEMENTARY reminders to the system prompt's numbered workflow —
+  // deliberately not renumbered as a competing sequence.
+  const isReReview = p && (agent._advisorRound || 0) > 0
+  parts.push("## Instructions")
+  parts.push("1. IMPORTANT: the review scope lists the files under review — always verify current file state with `read` before judging. Never decide based on earlier snapshots alone.")
+  if (isReReview) {
+    const round = (agent._advisorRound || 0) + 1
+    parts.push(...buildConvergenceInstructions(round, pathList))
+  } else {
+    parts.push("2. " + (guideRoot
+      ? "The `## Project Guide (AGENTS.md)` section above maps the project — read the requirements/design documents it points to (they are the primary reference for requirement-fit). Use `read` to load those documents."
+      : "No AGENTS.md was found at the project root — rely on the conversation background for the user's requirements. If the requirements are unclear, state so explicitly."))
+    parts.push("3. `read` the files in the Review Scope in full — they define exactly what to inspect. Batch independent reads/greps in a single reply instead of one call per round-trip.")
+    parts.push("4. Use `grep` or `lsp` to trace callers, imports, and dependencies — only where the diff leaves genuine doubt.")
+    parts.push("5. Produce your review table based on the review criteria above. Do not re-read content you already have.")
+    parts.push("6. You may also flag other issues: crashes, data loss, logic errors — anything obvious. This is the convergence protocol: round 1 is the full review, later rounds only re-verify.")
+  }
+  parts.push("")
+  parts.push("Return your review as a markdown table (or a clear statement that everything is fine).")
+
+  return parts.join("\n")
+}
+
+/**
+ * Resolve the review surface for the convergence fallback: explicit `paths`
+ * win; otherwise the runtime mutation record (_touchedFiles, ABSOLUTE) is
+ * normalized to cwd-relative so the fallback list matches the relative-path
+ * norm the reviewer sees everywhere else. Paths outside cwd are relativized
+ * with path.relative — never a mixed absolute/relative list.
+ */
+export function resolveScopeFiles(agent, paths) {
+  const normalize = (p) => {
+    // sep-guarded prefix check — /proj vs /project-other must not collide
+    const abs = p === agent.cwd || p.startsWith(agent.cwd + sep) ? p : join(agent.cwd, p)
+    return relative(agent.cwd, abs)
+  }
+  if (Array.isArray(paths)) return [...new Set(paths.map(normalize))]
+  if (agent._touchedFiles?.length) {
+    return [...new Set(agent._touchedFiles.map(normalize))]
+  }
+  return null
+}
+