thincoder 0.12.11 → 0.12.13

package/src/advisor/messages.mjs

@@ -3,31 +3,138 @@
  * 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 } 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.
  * @param {Object} agent — the parent agent
- * @param {Object|null} [_prior] — prior issue table
+ * @param {Object|null} [prior] — prior issue table
  * @param {string} [reviewType] — "design" or "code" (default)
  * @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)
  * @returns {string} the user message
  */
-export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken = null, documents = null, paths = null) {
-  const prior = _prior ?? extractPriorIssueTable(agent.history)
+export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = 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 = []
   const docList = Array.isArray(documents) ? documents.filter((d) => typeof d === "string" && d.trim()) : []
-  const pathList = Array.isArray(paths) ? paths.filter((p) => typeof p === "string" && p.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") {
+  if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     const repos = findReviewRepos(agent)
     parts.push("## Design Review")
     if (docList.length > 0) {
@@ -65,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:")
@@ -84,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")
@@ -95,25 +204,33 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
     return parts.join("\n")
   }
 
-  // Convergence data (round 2+). Design reviews returned above — only code reviews reach here.
-  if (prior && (agent._advisorRound || 0) > 0) {
-    const response = extractAgentResponseTable(agent.history, prior.sinceIdx)
-      || "(Agent did not provide a response table — re-evaluate each issue)"
+  // 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
-    const label = round === 2 ? "Verify Prior Table + Flag New Issues" : "Strict Verification"
-    parts.push(`## Round ${round} — ${label}`)
-    parts.push("")
-    parts.push("## Prior Issue Table")
-    parts.push(prior.text)
-    parts.push("")
-    parts.push("## Agent Response")
-    parts.push(response)
+    parts.push(buildConvergenceBody(p, response, round, scopeFiles))
     parts.push("")
     parts.push("---")
     parts.push("")
   }
 
-  parts.push("## Review Scope")
+  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("")
@@ -144,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:")
@@ -158,19 +282,20 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
     } catch { /* file doesn't exist — skip */ }
   }
 
-  // Instructions — round-aware: re-reviews skip convention discovery entirely
-  const isReReview = prior && (agent._advisorRound || 0) > 0
+  // 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: in the diff, `-` lines are REMOVED content (no longer in the file), `+` lines are ADDED. The prior issue table (if any) is HISTORY — always verify current file state with `read` before judging an item.")
+  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) {
-    parts.push("2. STALE-CONTEXT WARNING: any diff or file content embedded in earlier messages is a historical snapshot — treat it as expired. Only fresh `read` results describe the current state. Never quote a `-` line from an earlier diff as if it were live code.")
-    parts.push("3. Verify the prior issue table against the CURRENT FILE STATE — use `read`, never `git diff` alone. Fixes may already be committed: an empty `git diff` does NOT mean nothing changed. `git log -3` shows recent commits.")
-    parts.push("4. `read` the files in the Review Scope in full — ALWAYS, regardless of what `git diff` shows. Batch reads/greps in a single reply.")
-    parts.push("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 come from the stale prior table. Findings without a fresh quoted line are treated as unverified and will not be accepted.")
-    parts.push("6. Produce your verification table. Do not re-read content you already have.")
+    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("3. `read` changed files for full context beyond the diff. Batch independent reads/greps in a single reply instead of one call per round-trip.")
+    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.")
@@ -180,3 +305,24 @@ export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken =
 
   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
+}
+

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