thincoder 0.12.59 → 0.12.61

package/src/advisor/loop.mjs

@@ -0,0 +1,293 @@
+/**
+ * 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 } from "../config.mjs"
+import { toOpenAISchema } from "../tools/index.mjs"
+import { describeToolArgs } from "../tui/tool-args.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.
+ * @param {Object} agent — only used for the code index (agent.memory); the
+ *   semantic code_search tool needs it. Without a memory, the set is 5 tools.
+ */
+function advisorToolsFor(agent, reviewType = "code", batchDoc = null) {
+  const search = agent?.memory ? codeSearchTool(agent.memory) : null
+  const tools = search
+    ? [readTool, globTool, grepTool, lsTool, lspTool, search]
+    : [readTool, globTool, grepTool, lsTool, lspTool]
+  // §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 (agent.memory → code_search inclusion).
+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}} [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
+  // 第 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({
+      role: "assistant",
+      content: response.content || null,
+      tool_calls: response.toolCalls.map((tc) => ({
+        id: tc.id, type: "function",
+        function: { name: tc.name, arguments: tc.arguments },
+      })),
+      ...(response.reasoning && providerSpec(provider).reasoningEcho === "required"
+        ? { reasoning_content: response.reasoning }
+        : {}),
+    })
+
+    // 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 = describeToolArgs(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/src/advisor/messages.mjs

@@ -2,108 +2,17 @@
  * 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 { readFileSync, existsSync } from "node:fs"
-import { resolve, join, relative, dirname, sep } from "node:path"
-import { providerSpec } from "../config.mjs"
+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"
 
-/** Project guide (AGENTS.md) injection budget — decision 2026-08-08:
- *  NO fixed truncation; long-context models (1M+) get up to 5% of their context
- *  window for the doc map, small windows still get a floor so the map is always
- *  visible. The map is what tells the reviewer WHERE the requirements docs live
- *  (requirement-fit is judged against those docs, not the conversation only). */
-const PROJECT_GUIDE_MIN = 8192 // chars — floor for small-window models
-const PROJECT_GUIDE_FRACTION = 0.05 // 5% of the reviewer model's context window
-
-/**
- * Discover the project root for the review — user decision 2026-08-08:
- * the project root is a SUBDIRECTORY of the working directory, never an
- * ancestor above it. Priority:
- *   1. Walk UP from each review-scope file's directory, bounded by cwd —
- *      the NEAREST AGENTS.md inside the workspace wins. In a monorepo this is
- *      the subproject's own doc map even when cwd itself has an AGENTS.md
- *      (a workspace-level meta map must not shadow the subproject guide).
- *   2. No scope files / nothing found → cwd (single project; the walk's
- *      last step naturally lands on cwd's own AGENTS.md when it exists).
- * @param {string} cwd — the agent's working directory (workspace root)
- * @param {string[]} scopeFiles — cwd-relative review-scope paths (may be empty)
- * @returns {string|null} absolute project root with an AGENTS.md, or null
- */
-function findProjectRoot(cwd, scopeFiles) {
-  // Normalize separators before comparing: input paths may use either
-  // convention (join() → "\\" on Windows; tool args / tests → "/"). Mixed
-  // styles made isInside(cwd + sep) miss legitimately nested paths.
-  const norm = (p) => p.replaceAll("\\", "/")
-  const isInside = (dir) => {
-    const d = norm(dir)
-    const c = norm(cwd)
-    return d === c || d.startsWith(c + "/")
-  }
-  for (const f of scopeFiles) {
-    let dir = dirname(resolve(cwd, f))
-    while (isInside(dir) && dir !== dirname(dir)) {
-      if (existsSync(join(dir, "AGENTS.md"))) return dir
-      dir = dirname(dir)
-    }
-  }
-  // No scope files, or none found in the walk — cwd itself (its AGENTS.md is
-  // checked as the walk's final step for scope files; for empty scopes, check
-  // it explicitly so a bare cwd project still gets its guide).
-  if (existsSync(join(cwd, "AGENTS.md"))) return cwd
-  return null
-}
-
-/**
- * Inject the project guide (AGENTS.md) into the review message. AGENTS.md is the
- * project's doc map — it defines the structure and where requirements/design
- * documents live. The reviewer must see it FIRST: requirement-fit is judged
- * against the documents it points to, with the conversation background as a
- * supplement. Absent AGENTS.md degrades honestly (no pretending there is a map).
- * @param {Object} agent — the parent agent
- * @param {string[]} parts — message parts (mutated)
- * @param {string[]} [scopeFiles] — cwd-relative review-scope paths for project-root discovery
- * @returns {string|null} the discovered project root (abs), or null when no guide
- */
-function injectProjectGuide(agent, parts, scopeFiles = []) {
-  parts.push("## Project Guide (AGENTS.md)")
-  const root = findProjectRoot(agent.cwd, scopeFiles)
-  const path = root ? join(root, "AGENTS.md") : null
-  let text
-  if (!path) {
-    parts.push("(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)")
-    parts.push("")
-    return null // no guide — requirement-fit falls back to the conversation
-  }
-  try {
-    text = readFileSync(path, "utf8")
-  } catch (e) {
-    if (e.code !== "ENOENT") {
-      // File exists but is unreadable (EACCES etc.) — log, don't masquerade as "not found".
-      console.warn(`[advisor] AGENTS.md unreadable at ${path}: ${e.message}`)
-    }
-    parts.push("(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)")
-    parts.push("")
-    return null // no guide — requirement-fit falls back to the conversation
-  }
-  // readFileSync succeeded — compute the budget OUTSIDE the try so a spec
-  // lookup failure can never masquerade as "no AGENTS.md".
-  // providerSpec: the project-guide budget follows the provider-level context
-  // override (PROVIDER.md §15 — advisor messages budget is context-based).
-  const ctx = providerSpec(agent.provider).context
-  const cap = Math.max(PROJECT_GUIDE_MIN, Math.floor(ctx * PROJECT_GUIDE_FRACTION))
-  const shown = text.length <= cap
-    ? text
-    : [...text].slice(0, cap).join("") + `\n\n…(truncated at ${cap} chars — read the full file if you need more)` // codepoint-safe slice: no broken surrogate pairs at the boundary
-  parts.push(`<!-- Project root: ${relative(agent.cwd, path).split(sep).join("/")} (inferred from the review scope under ${agent.cwd}) -->`)
-  parts.push("This file defines the project's structure and where its requirements/design documents live. Read the documents it points to — the user's requirements live THERE, not only in the conversation background.")
-  parts.push("")
-  parts.push(shown)
-  parts.push("")
-  return root // guide injected — requirement-fit criteria apply (truthy root)
-}
+// 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
@@ -129,6 +38,25 @@ export function buildObjectDeclarationBlock(object = null) {
   ].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
@@ -142,9 +70,23 @@ export function buildObjectDeclarationBlock(object = null) {
  * @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) {
+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.
@@ -172,6 +114,11 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   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
@@ -207,48 +154,30 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
       }
     }
 
-    // Engineering mode: inject project methodology (resolved from the
-    // DISCOVERED project root — in a monorepo that is the subproject, not cwd)
+    // Engineering mode: the project's DECLARED standards document
+    // (advisor.standardsDoc) — undeclared degrades visibly (PO-2).
     if (agent.config?.agent?.engineering) {
-      try {
-        const mpath = resolve(guideRoot ?? agent.cwd, "METHODOLOGY.md")
-        const methodology = readFileSync(mpath, "utf8")
-        parts.push("## Project Methodology")
-        parts.push("Evaluate the design against this methodology:")
-        parts.push(methodology)
-        parts.push("")
-      } catch { /* file doesn't exist — skip */ }
+      injectProjectStandards(agent, parts, guideRoot)
     }
 
-    // Document map (docs/design/README.md) — inject when the discovered
-    // project root has one: the reviewer checks document ownership against it
-    // (a change for an existing section must amend that section's document,
-    // not spawn a new file for it). Absent map → skip (nothing to check against).
-    try {
-      const mapPath = resolve(guideRoot ?? agent.cwd, "docs", "design", "README.md")
-      if (existsSync(mapPath)) {
-        parts.push("## Document Map")
-        parts.push("The document map below registers which document files exist per section. Use it for the Document ownership criterion: a change for an existing section must amend that section's document, not create a new file.")
-        parts.push(readFileSync(mapPath, "utf8"))
-        parts.push("")
-      }
-    } catch { /* file doesn't exist or is unreadable — skip */ }
+    // 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. Read METHODOLOGY.md to understand the project's standards.")
+      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. Read METHODOLOGY.md to understand the project's standards.")
+      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 METHODOLOGY.md?), clarity (specific enough?), acceptance criteria (verifiable?), scope (appropriate?).")
+    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("## Approval Signal")
-      parts.push(`If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}]`)
-      parts.push("🟡 (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.")
+      parts.push(buildDesignApprovalBlock(designToken, designId))
     }
     return parts.join("\n")
   }
@@ -318,17 +247,10 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   }
   parts.push("")
 
-  // Engineering mode: inject project methodology so advisor knows the rules
-  // (resolved from the DISCOVERED project root — subproject in a monorepo)
+  // Engineering mode: project standards (declaration-only, same helper as the
+  // design path) — undeclared degrades visibly (PO-2).
   if (agent.config?.agent?.engineering) {
-    try {
-      const mpath = resolve(guideRoot ?? agent.cwd, "METHODOLOGY.md")
-      const methodology = readFileSync(mpath, "utf8")
-      parts.push("## Project Methodology (Engineering Mode)")
-      parts.push("The project follows this methodology. Evaluate the changes against it:")
-      parts.push(methodology)
-      parts.push("")
-    } catch { /* file doesn't exist — skip */ }
+    injectProjectStandards(agent, parts, guideRoot)
   }
 
   // Instructions — round-aware: re-reviews skip convention discovery entirely.