thincoder 0.12.12 → 0.12.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thincoder",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "description": "Thin coding agent - zero dependencies, no build step, Node.js native. Sharp code, zero bloat.",
   "keywords": [
     "ai",

package/src/advisor/convergence.mjs

@@ -0,0 +1,80 @@
+/**
+ * advisor/convergence.mjs — shared convergence-round message building (round 2+).
+ * SINGLE source for the round-2+ sections used by BOTH the normal flow
+ * (buildAdvisorFollowUp in advisor.mjs) and the legacy path (buildAdvisorUserMessage
+ * in messages.mjs) — fixes must not be replicated in two places. Lives in its
+ * own module to avoid the messages.mjs ↔ advisor.mjs import cycle.
+ */
+
+/**
+ * Shared convergence-round instructions — single source for BOTH paths
+ * (buildAdvisorUserMessage's legacy convergence block and
+ * buildAdvisorFollowUp), so the wording cannot diverge.
+ * Round 2 may flag obvious new issues; round 3+ is strict verification.
+ * @param {number} round — convergence round number (2+)
+ * @param {string[]|null} scopeFiles — optional file list for the no-response fallback
+ * @returns {string[]} the numbered instruction lines (callers spread them)
+ */
+export function buildConvergenceInstructions(round, scopeFiles = null) {
+  const fileList = scopeFiles?.length
+    ? ` The review surface is: ${scopeFiles.slice(0, 10).join(", ")}.`
+    : ""
+  return [
+    `1. IMPORTANT: verify EVERY item of the prior review output against the CURRENT FILE STATE with \`read\` — never decide based on earlier snapshots alone.${fileList}`,
+    "2. STALE-CONTEXT WARNING: any diff or file content from earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state.",
+    "3. You have no git tool; git output in earlier messages is historical and untrustworthy (committed fixes never show in a diff).",
+    "4. `read` the files named in the prior review output (or the review surface above) in full — ALWAYS. Batch reads/greps in a single reply.",
+    "5. Evidence rule: every 'Unfixed'/'New' finding MUST quote the exact line content from THIS round's `read` output (e.g. `run.mjs:180: timeoutId = setTimeout(...)`). Line numbers alone are NOT evidence — they may be stale or fabricated. Findings without a fresh quoted line are treated as unverified and will not be accepted.",
+    "6. Produce your verification table. Do not re-read content you already have.",
+    round === 2
+      ? "7. You may flag obvious NEW issues introduced by the fixes (crashes, data loss, logic errors — not style)."
+      : "7. Do NOT look for new issues.",
+  ]
+}
+
+/**
+ * Shared convergence body — SINGLE source for the round-2+ message sections
+ * (decision 2026-08-08): the FULL verbatim prior review output is the only
+ * complete verification list; the agent response table is a focus aid only.
+ * Used by buildAdvisorFollowUp (the normal flow) and the legacy path in
+ * messages.mjs (direct external callers of buildAdvisorUserMessage) — fixes
+ * must not be replicated in two places.
+ * @param {string} p — full prior review output (verbatim)
+ * @param {string} response — agent fix-claims table (or fallback text)
+ * @param {number} round — next round number (>= 2)
+ * @param {string[]|null} [scopeFiles] — review surface for instructions
+ * @returns {string} the convergence message
+ */
+export function buildConvergenceBody(p, response, round, scopeFiles) {
+  const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
+  const reminder = round === 2
+    ? "verify every item in the prior review output and flag only obvious new issues introduced by the fixes"
+    : "strictly verify only the prior review output — do NOT look for new issues"
+  const parts = [
+    `## Round ${round} — ${label}`,
+    "",
+    `[System reminder: this is round ${round} of the convergence protocol. ` +
+      `The system prompt for this round has already narrowed the review scope — follow it: ${reminder}.]`,
+    "",
+    // Prior review output IS in the context (decision 2026-08-08): the FULL
+    // verbatim output of the last review — the only complete verification list.
+    // The agent response table covers only issues the agent chose to answer,
+    // so issues the agent skipped would silently escape convergence without
+    // the prior output. The model understands the review output directly —
+    // no table/header/phrase parsing. Restatement risk is handled
+    // mechanically: host-verified citations reject references that do not
+    // match the CURRENT disk state, and fresh sessions exclude old read data.
+    // The agent response table stays as a focus aid ("I fixed X"), not as the
+    // to-verify list.
+    "## Prior Review Output (verify every item it raises)",
+    p,
+    "",
+    "## Agent Response (fix claims — reference only)",
+    response,
+    "",
+    "## Instructions",
+    ...buildConvergenceInstructions(round, scopeFiles),
+    "",
+  ]
+  return parts.join("\n")
+}

package/src/advisor/history.mjs

@@ -1,16 +1,11 @@
 /**
- * advisor/history.mjs — advisor history extraction: issue/response tables and conversation background.
+ * advisor/history.mjs — advisor history extraction: agent response table and conversation background.
  */
 import { readFileSync } from "node:fs"
 import { join } from "node:path"
 
 export const ADVISOR_MD_PATH = ".thincoder/advisor.md"
-export const ADVISOR_TABLE_HEADER = "| # | File | Severity | Issue | Suggestion |"
-// Design-review table header (advisor-design.md round 1): | # | Category | Severity | Issue | Suggestion |
-const DESIGN_TABLE_HEADER = "| # | Category | Severity | Issue | Suggestion |"
-const CONVERGENCE_TABLE_HEADER = "| # | Orig# | File | Severity | Status | Notes |"
 const AGENT_RESPONSE_HEADER = "| # | Action | Detail |"
-export const LEGACY_ADVISOR_HEADER = "| # | 文件 | 严重程度 | 问题描述 | 建议修复 |"
 
 const DEFAULT_CRITERIA = `Review the code changes, focusing on:
 1. Correctness: logic errors, edge cases, off-by-one, incomplete modifications
@@ -20,77 +15,28 @@ const DEFAULT_CRITERIA = `Review the code changes, focusing on:
 5. Maintainability: vague naming, missing comments, overly complex logic`
 
 /**
- * Extract the most recent advisor review table from history.
- * Returns { text, sinceIdx } where sinceIdx is the index of the advisor call's
- * own history entry — extractAgentResponseTable skips it (role is "tool", not
- * "assistant") and scans forward for the agent's response table.
- * Returns null when: no advisor call, empty output, or the last review is
- * all-clear (nothing to follow up on).
+ * Extract the agent's response table (| # | Action | Detail |) — the fix-claims
+ * reference for convergence rounds.
+ * Semantics (decision 2026-08-08): without sinceIdx, scan BACKWARD for the
+ * MOST RECENT response table (no prior-table index is carried anymore — the
+ * agent response is a focus aid only; format drift falls back to the
+ * no-response text and never drives control flow). With sinceIdx, scan
+ * FORWARD from it (legacy callers/tests).
+ * @param {Array} history — message history
+ * @param {number} [sinceIdx] — legacy: start scanning forward from this index
+ * @returns {string|null} the response table content, or null
  */
-// All-clear phrases the prompts instruct the advisor to use on a clean review.
-// Used ONLY by extractPriorIssueTable (issue-table verdict — a phrase-free
-// issue table with rows is never all-clear). The round-reset guard no longer
-// depends on model output at all: prepareAdvisorMessages decides by the
-// deterministic _mutatedThisRun flag (user decision 2026-08-05). "no new
-// issues" is DELIBERATELY absent — verification-table outputs (round 2+)
-// commonly conclude with it (round 3+ instructions even SAY "do not look for
-// new issues"); treating it as all-clear would reset the convergence budget
-// after every round-2 review (the observed "always round 2" bug: prior → null
-// → _advisorRound reset → 1→2→1…).
-const ALL_CLEAR_PHRASES = ["no 🔴", "all clear", "全部通过", "review passed", "no issues found", "everything is fine"]
-
-export function extractPriorIssueTable(history) {
-  // Negative signals: a table listing SOME items as unfixed is NOT all-clear.
-  // Applied when the message carries a Status column (English or Chinese convergence
-  // format) — "failed"/"❌" in a round-1 Issue description must NOT trigger it.
-  const partiallyFixedRe = /\bunfixed\b|未修复|❌|\bfailed\b/i
+export function extractAgentResponseTable(history, sinceIdx) {
   const entries = Array.isArray(history) ? history : []
-
-  for (let i = entries.length - 1; i >= 0; i--) {
-    const m = entries[i]
-    if (m.role !== "tool" || typeof m.content !== "string") continue
-    // Only review outputs carry one of these table headers. Matched at LINE START:
-    // an `includes()` match would also fire on advisor output that quotes the
-    // header constants' own source code (e.g. history.mjs), producing a phantom
-    // "prior issue table" and re-opening convergence rounds against stale data.
-    if (!lineHasHeader(m.content, ADVISOR_TABLE_HEADER)
-      && !lineHasHeader(m.content, DESIGN_TABLE_HEADER)
-      && !lineHasHeader(m.content, CONVERGENCE_TABLE_HEADER)
-      && !lineHasHeader(m.content, LEGACY_ADVISOR_HEADER)) continue
-    const text = m.content
-    const lower = text.toLowerCase()
-    // Has a Status column? (English convergence format or any table with a Status-like
-    // column) — Chinese legacy tables lack it, but they are issue tables, not convergence.
-    const hasStatusColumn = lineHasHeader(text, CONVERGENCE_TABLE_HEADER)
-      || /Status|状态/.test(text.slice(0, text.indexOf("\n") + 1))
-    if (hasStatusColumn) {
-      // Convergence/verification table: pass/fail is row-level — free-text
-      // phrases like "no new issues found" / "review passed" are partial or
-      // boilerplate statements in verification outputs. Some row unfixed →
-      // convergence continues; every row fixed → all clear (fresh cycle).
-      if (partiallyFixedRe.test(lower)) return { text, sinceIdx: i }
-      return null
+  if (sinceIdx !== undefined) {
+    for (let i = sinceIdx; i < entries.length; i++) {
+      const m = entries[i]
+      if (m.role !== "assistant" || typeof m.content !== "string") continue
+      if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content
     }
-    // Issue table (round 1 / design): phrase-based all-clear detection.
-    if (ALL_CLEAR_PHRASES.some((s) => lower.includes(s))) return null
-    // sinceIdx = the advisor call's own index; extractAgentResponseTable skips it (role !== assistant)
-    return { text, sinceIdx: i }
+    return null
   }
-  return null
-}
-
-/** True when some line of `text` starts with `header` — table headers always sit at line start. */
-function lineHasHeader(text, header) {
-  return text.split("\n").some((l) => l.trimStart().startsWith(header))
-}
-
-/**
- * Extract the agent's response table (| # | Action | Detail |) that follows
- * the advisor review. Returns null when missing or no advisor review precedes.
- */
-export function extractAgentResponseTable(history, sinceIdx) {
-  const entries = Array.isArray(history) ? history : []
-  for (let i = sinceIdx ?? 0; i < entries.length; i++) {
+  for (let i = entries.length - 1; i >= 0; i--) {
     const m = entries[i]
     if (m.role !== "assistant" || typeof m.content !== "string") continue
     if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content

package/src/advisor/messages.mjs

@@ -3,10 +3,105 @@
  * Split out of advisor.mjs to keep it under the 300-line advisory threshold
  * (.thincoder/advisor.md). System prompts live in advisor.mjs / prompts/.
  */
-import { readFileSync } from "node:fs"
-import { resolve, join, relative } from "node:path"
+import { readFileSync, existsSync } from "node:fs"
+import { resolve, join, relative, dirname, sep } from "node:path"
+import { specForModel } from "../config.mjs"
 import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
-import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable, extractPriorIssueTable } from "./history.mjs"
+import { buildConvergenceBody, buildConvergenceInstructions } from "./convergence.mjs"
+import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable } from "./history.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".
+  const ctx = specForModel(agent.provider?.model ?? "").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)
+}
 
 /**
  * Build the user message for an advisor review session.
@@ -21,12 +116,23 @@ import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable
  * @returns {string} the user message
  */
 export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null) {
-  const p = prior ?? extractPriorIssueTable(agent.history)
+  // 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 = []
   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)
@@ -66,10 +172,11 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
       }
     }
 
-    // Engineering mode: inject project methodology
+    // Engineering mode: inject project methodology (resolved from the
+    // DISCOVERED project root — in a monorepo that is the subproject, not cwd)
     if (agent.config?.agent?.engineering) {
       try {
-        const mpath = resolve(agent.cwd, "METHODOLOGY.md")
+        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:")
@@ -85,8 +192,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
       parts.push("1. Read the design document fully. Read METHODOLOGY.md to understand the project's standards.")
     }
     parts.push("2. Review against: completeness (all requirements covered?), feasibility (can this be built?), clarity (specific enough?), acceptance criteria (verifiable?), scope (appropriate?).")
-    parts.push("3. Do NOT run git diff or look for code changes — there are none at this stage.")
-    parts.push("4. If you find issues, produce your review table with the format: | # | Category | Severity | Issue | Suggestion |. If the design passes, no table is needed.")
+    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")
@@ -99,24 +207,22 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   // 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 prior table. Kept to avoid breaking those.
-  // Same rule as buildAdvisorFollowUp: prior table IS injected (decision
-  // 2026-08-05, reversed) — it is the only complete verification list.
+  // 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, p.sinceIdx)
+    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
-    const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
-    parts.push(`## Round ${round} — ${label}`)
-    parts.push("")
-    parts.push("## Prior Issue Table (verify every item)")
-    parts.push(p.text)
-    parts.push("")
-    parts.push("## Agent Response (fix claims — reference only)")
-    parts.push(response)
+    parts.push(buildConvergenceBody(p, response, round, scopeFiles))
     parts.push("")
     parts.push("---")
     parts.push("")
@@ -155,12 +261,19 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
   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: inject project methodology so advisor knows the rules
+  // (resolved from the DISCOVERED project root — subproject in a monorepo)
   if (agent.config?.agent?.engineering) {
     try {
-      const mpath = resolve(agent.cwd, "METHODOLOGY.md")
+      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:")
@@ -169,7 +282,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
     } catch { /* file doesn't exist — skip */ }
   }
 
-  // Instructions — round-aware: re-reviews skip convention discovery entirely
+  // 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.")
@@ -177,7 +292,9 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
     const round = (agent._advisorRound || 0) + 1
     parts.push(...buildConvergenceInstructions(round, pathList))
   } else {
-    parts.push("2. Read `AGENTS.md` / design docs only if they exist (check once; do not re-probe with multiple patterns).")
+    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.")
@@ -198,7 +315,8 @@ export function buildAdvisorUserMessage(agent, prior, reviewType, designToken =
  */
 export function resolveScopeFiles(agent, paths) {
   const normalize = (p) => {
-    const abs = p.startsWith(agent.cwd) ? p : join(agent.cwd, 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))]
@@ -208,29 +326,3 @@ export function resolveScopeFiles(agent, paths) {
   return null
 }
 
-/**
- * Shared convergence-round instructions — single source for BOTH paths
- * (buildAdvisorUserMessage's legacy convergence block and
- * buildAdvisorFollowUp), so the wording cannot diverge.
- * Round 2 may flag obvious new issues; round 3+ is strict verification.
- * @param {number} round — convergence round number (2+)
- * @param {string[]|null} scopeFiles — optional file list for the no-response fallback
- * @returns {string[]} the numbered instruction lines (callers spread them)
- */
-export function buildConvergenceInstructions(round, scopeFiles = null) {
-  const fileList = scopeFiles?.length
-    ? ` The review surface is: ${scopeFiles.slice(0, 10).join(", ")}.`
-    : ""
-  return [
-    `1. IMPORTANT: verify EVERY item of the prior issue table against the CURRENT FILE STATE with \`read\` — never decide based on earlier snapshots alone.${fileList}`,
-    "2. STALE-CONTEXT WARNING: any diff or file content from earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state.",
-    "3. You have no git tool; git output in earlier messages is historical and untrustworthy (committed fixes never show in a diff).",
-    "4. `read` the files named in the prior table (or the review surface above) in full — ALWAYS. Batch reads/greps in a single reply.",
-    "5. Evidence rule: every 'Unfixed'/'New' finding MUST quote the exact line content from THIS round's `read` output (e.g. `run.mjs:180: timeoutId = setTimeout(...)`). Line numbers alone are NOT evidence — they may be stale or fabricated. Findings without a fresh quoted line are treated as unverified and will not be accepted.",
-    "6. Produce your verification table. Do not re-read content you already have.",
-    round === 2
-      ? "7. You may flag obvious NEW issues introduced by the fixes (crashes, data loss, logic errors — not style)."
-      : "7. Do NOT look for new issues.",
-  ]
-}
-

package/src/advisor/repos.mjs

@@ -99,6 +99,15 @@ export function collectChangedFiles(repos, cwd) {
 
 const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/i
 
+/** Temporary/scratch files that must NOT count as code mutations: tmp-* named
+ *  scratch scripts (tmp-c1.mjs, tmp-check.mjs…) and .tmp/.temp extensions.
+ *  The advisor/verify guards skip these — a throwaway diagnostic script is not
+ *  a code change, and writing one must not push the agent into a review loop.
+ *  NOTE: matches the tmp-* basename at ANY directory depth, not just root —
+ *  intentional: _touchedFiles stores absolute paths, so the pattern must work
+ *  for "D:/proj/tmp-check.mjs" as well as a bare "tmp-check.mjs". */
+const TEMP_FILE = /(?:^|[/\\])tmp-[^/\\]+$|\.(?:tmp|temp)$/i
+
 /** True when a path matches the doc/license pattern by extension or name.
  *  NOTE: this is extension-based only — it does NOT exclude src/ paths.
  *  Callers must separately check the src/ prefix for product-code semantics
@@ -108,6 +117,35 @@ export function isDocFile(p) {
   return DOC_FILE.test(p ?? "")
 }
 
+/** True when a path is a throwaway temp file (tmp-* name or .tmp/.temp ext).
+ *  Excluded from code-mutation detection so scratch scripts don't trigger
+ *  advisor/verify guards. */
+export function isTempFile(p) {
+  return TEMP_FILE.test(p ?? "")
+}
+
+/**
+ * True when this run mutated at least one CODE file. Shared single source of
+ * truth for the advisor/verify guards (agent.mjs + agent/completion.mjs).
+ * Doc-only changes (docs/, *.md, LICENSE…) must NOT trigger the guards — the
+ * design phase edits docs/ and must not be pushed to a code review. Temp/scratch
+ * files (tmp-*, .tmp, .temp) are excluded too — a throwaway diagnostic script
+ * is not a code change. Mutations without a known path (tools outside
+ * FILE_MUTATORS) are treated as code — cannot tell, so guard conservatively.
+ * Product-code semantics: anything under src/ (incl. src/prompts/*.md) is code;
+ * anything else that isn't a doc or temp file is code.
+ * NOTE: _touchedFiles stores ABSOLUTE paths (join(cwd, p)), so the src/ check
+ * matches a path component (works for "src/..." and "D:\...\src\..." alike),
+ * not a bare ^src prefix — the literal ^src[\\/] form would be dead code here.
+ */
+export function hasCodeMutations({ _touchedFiles, _mutatedThisRun }) {
+  const files = _touchedFiles ?? []
+  if (files.length === 0) return _mutatedThisRun
+  // src/ is unconditional — anything under src/ is code regardless of its name
+  // (incl. src/tmp-*.mjs). Temp/doc exclusions apply only outside src/.
+  return files.some((p) => /(?:^|[\\/])src[\\/]/.test(p) || (!isTempFile(p) && !isDocFile(p)))
+}
+
 /** True when all changed files across repos are documentation (md/txt/LICENSE etc.).
  *  Anything under src/ (incl. src/prompts/*.md) counts as product code —
  *  isProductCode semantics, consistent with the design gate. */
@@ -126,7 +164,9 @@ export function isDocOnlyChange(repos, cwd) {
     for (const line of status.split("\n")) {
       // porcelain: "XY path" or "XY old -> new" (rename)
       const filePath = line.slice(3).split(" -> ").pop().replace(/^"|"$/g, "")
+      // src/ is unconditional product code (even src/tmp-*.mjs) — check before the temp skip
       if (/^src[\\/]/.test(filePath) || !DOC_FILE.test(filePath)) return false
+      if (isTempFile(filePath)) continue
     }
   }
   return sawChanges

package/src/advisor/run.mjs

@@ -6,7 +6,6 @@ import { chat } from "../provider/core.mjs"
 import { findProvider, specForModel } from "../config.mjs"
 import { toOpenAISchema } from "../tools/index.mjs"
 import { prepareAdvisorMessages } from "../advisor.mjs"
-import { extractPriorIssueTable } from "../advisor/history.mjs"
 import { appendCitationReport } from "./citations.mjs"
 
 const MAX_ADVISOR_TURNS = 100
@@ -376,9 +375,10 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
   // blocks the next call. 5 rounds max; after that the review is never pushed back
   // (the caller decides: accept, manual re-check, or /new to reset).
   if ((agent._advisorRound || 0) >= MAX_ADVISOR_ROUNDS) {
-    // 提取未解决的问题，给出更具体的指导
-    const prior = extractPriorIssueTable(agent.history)
-    const unfixed = prior ? extractUnfixedIssues(prior.text) : []
+    // Summarize unresolved items from the last review output for guidance
+    // (line-level status-word scan — no table-header parsing, decision 2026-08-08).
+    const prior = agent._lastAdvisorOutput
+    const unfixed = prior ? extractUnfixedIssues(prior) : []
     
     let message = `Advisor: convergence cap reached after ${MAX_ADVISOR_ROUNDS} rounds.\n`
     if (unfixed.length > 0) {
@@ -409,6 +409,18 @@ export async function runAdvisorReview(agent, reviewType, callbacks, designToken
     let final = result
     if (!result.trimStart().startsWith("Advisor:")) {
       final = appendCitationReport(result, advisorCwd)
+      // Success path: keep the FULL review output for convergence rounds —
+      // round 2+ injects this verbatim and the model understands it (decision
+      // 2026-08-08: prior-table hard parsing removed; no phrase/header matching).
+      // Guard: only store outputs that actually carry a review — a markdown
+      // table row (`| a | b | c |`) or substantial prose (>200 chars). An
+      // empty or tool-progress-only reply must not become the "prior review"
+      // of round 2+.
+      const trimmed = final.trim()
+      const looksLikeReview = /\|.*\|.*\|/.test(trimmed) || trimmed.length >= 200
+      if (looksLikeReview) {
+        agent._lastAdvisorOutput = final
+      }
     }
 
     // Log review statistics for observability