thincoder 0.12.1 → 0.12.3

package/README.md

@@ -15,17 +15,17 @@ Design philosophy (the entire meaning of the name): if the Node standard library
 - **Fix-verify loop**: file changes without `verify` get pushed back — syntax check + tests must pass before the agent can claim completion (auto-repair up to 3 rounds)
 - **Checkpoint system**: auto-snapshot before every user task, `list`/`create`/`rewind` tools for the model, single-file restore — rewinding itself is reversible (pre-rewind state auto-saved)
 - **Codebase understanding** ⭐0.5.0: `repo_outline` (dependency outline, auto-injected at startup), `code_search` (source FTS5 + vectors + JSDoc extraction), `doc_search` (docs chunked by ## headings) — background indexing, auto-incremental updates on file writes, three tools guided by "structure → intent → details"
-- **Model adaptation** ⭐: top-tier only, latest only. Built-in flagship models from five leading Chinese vendors — DeepSeek / Kimi / GLM / Qwen / MiniMax. No legacy model compatibility, no local model support. Auto-matched context windows, truncation-resume protocols (prefix/partial), thinking-mode APIs (thinking.type / reasoning_effort), reasoning_content echo strategies (reasoningEcho), output limits, temperature range clamping — all five deeply adapted.
+- **Model adaptation** ⭐: top-tier only, latest only. Built-in flagship models from twelve providers — DeepSeek / Kimi / GLM / Qwen / MiniMax / OpenAI / Claude / Gemini / Grok / Mistral / Volcengine Ark (豆包) / Hunyuan (腾讯混元) / SiliconFlow (硅基流动) / OpenRouter / Groq. No legacy model compatibility, no local model support. Auto-matched context windows, truncation-resume protocols (prefix/partial), thinking-mode APIs (thinking.type / reasoning_effort), reasoning_content echo strategies (reasoningEcho), output limits, temperature range clamping — all deeply adapted.
 - **Toolset**: `read` / `write` / `edit` / `bash` / `glob` (supports `**`) / `grep` / `websearch` / `ls` / `fetch` + `read_image` (image/video paste) + three retrieval tools + MCP — all zero-dependency, file tools confined to the working directory
 - **Memory system**: three layers (personal/project/team), FTS5 + vector RRF hybrid retrieval, git-friendly markdown format
 - **Two-phase tool scheduling**: permission prompts serialized, read-only tools parallelized, side-effect tools serialized
-- **Session persistence** ⭐0.5.0: up to 5 archive slots, `/session` to switch anytime, tool results visible after restore
+- **Session persistence** ⭐0.5.0: up to 5 archive slots, `/session` to switch anytime, tool results visible after restore. Process-level isolation — multiple instances in the same directory each get their own session slot
 - **Concurrent subagents**: three roles — `explore`/`plan`/`coder` — dispatched in parallel, streaming output visible, reports land in the conversation
 - **Plan Mode**: read-only exploration + design, implement after user approval
 - **AUTO mode**: `/auto` full authorization, no confirmations on long tasks
 - **Task tracking**: `task` tool breaks down multi-step work, status bar ✓n/m live progress, auto-filters completed items
 - **Goal/Verify/Skills**: long-goal tracking, completion verification, reusable skills
-- **Streaming TUI**: bare ANSI, permission preview right above the input box, write/edit auto-shows diffs, paste shortcut hint in the input box corner for multimodal models (Win: Alt+V / Mac/Linux: Ctrl+V)
+- **Streaming TUI**: bare ANSI, permission preview right above the input box, write/edit auto-shows diffs, paste shortcut hint in the input box corner for multimodal models (Win: Alt+V / Mac/Linux: Ctrl+V). Two-level model picker (providers → models), search/filter support, Shift+Enter for multiline input
 
 ## Memory: What One Learns, the Whole Team Knows
 
@@ -85,7 +85,7 @@ thincoder upgrade
 
 Running from source: replace `thincoder` above with `node bin/thincoder.mjs`.
 
-Slash commands in the TUI: `/help`, `/model` (arrow-key picker across all models of all providers; `/model <name>` switches directly), `/provider` (add/remove providers, set keys, custom endpoints), `/think` (thinking mode toggle and reasoning effort), `/config` (view config, `/config embedkey` for the embedding key, `/config set` for parameters), `/session` (list/switch archived sessions), `/reindex` (rebuild the index), `/extract` (extract knowledge from the current session), `/restore` (restore checkpoint), `/clear`, `/exit`. High-frequency commands support abbreviations: `/h` `/x` `/m` `/p` `/t` `/c` `/n`. Typing `/` shows live matching hints in the status bar.
+Slash commands in the TUI: `/help`, `/model` (two-level picker: first select provider, then model; `/model <provider>:<name>` switches directly), `/provider` (add/remove providers, set keys, custom endpoints), `/think` (thinking mode toggle and reasoning effort), `/config` (view config, `/config embedkey` for the embedding key, `/config set` for parameters), `/session` (list/switch archived sessions), `/reindex` (rebuild the index), `/extract` (extract knowledge from the current session), `/restore` (restore checkpoint), `/clear`, `/exit`. High-frequency commands support abbreviations: `/h` `/x` `/m` `/p` `/t` `/c` `/n`. Typing `/` shows live matching hints in the status bar. Model picker supports search/filter — type to narrow down results.
 
 Environment variables: `THINCODER_API_KEY` (or `DEEPSEEK_API_KEY` / `OPENAI_API_KEY`), `THINCODER_BASE_URL`, `THINCODER_MODEL`, `SILICONFLOW_API_KEY`.
 
@@ -164,7 +164,7 @@ src/
   memory/           three-layer memory — schema.mjs (DDL/constants), core.mjs (CRUD + retrieval),
                     code-index.mjs + code-sync.mjs (code_chunks), docs.mjs (doc_chunks)
   memory.mjs        re-export shim → src/memory/*
-  session.mjs       session persistence (up to 5 archive slots, isolated by project cwd)
+  session.mjs       session persistence (up to 5 archive slots, isolated by project cwd, process-level isolation via sessionId + slotSessions)
   skills.mjs        skill discovery/loading (.thincoder/skills/*.md)
   markdown.mjs      entry format (frontmatter parse/serialize)
   git/              checkpoint.mjs (git patch snapshots / rewind), gitmem.mjs (Team layer git sync)
@@ -205,6 +205,19 @@ Code conventions: pure `.mjs`, no semicolons, no npm dependencies allowed (inclu
 
 ## Changelog
 
+### 0.12.3 (2026-08)
+- **Fix: user-level skills loading** — skills in `~/.thincoder/skills/` are now properly discovered and loaded alongside project-level skills. Project-level skills with the same name take priority. Both `skill list` and `skill load` support both directories.
+
+### 0.12.2 (2026-08)
+- **Session isolation for multiple processes** — each process gets a unique session ID (`pid-timestamp-random`), manifest tracks slot ownership via `slotSessions` mapping. Concurrent sessions in the same directory automatically get separate slots. Dead process slots are intelligently reclaimed via `isProcessAlive()` check
+- **Two-level model picker** — `/model` now shows providers first, then models for selected provider. Reduces visual clutter when many providers are configured. Direct switching still works: `/model qwen:qwen-max`
+- **Picker improvements** — auto-scroll keeps selected item visible, "type to filter" hint shown, search/filter support added
+- **Shift+Enter multiline input** — TUI now supports Shift+Enter for multiline input (regular Enter still submits)
+- **New provider presets** — added Volcengine Ark (豆包), Hunyuan (腾讯混元), SiliconFlow (硅基流动), OpenRouter, Groq (5 new providers, total now 12)
+- **Execute tool security hardening** — blocks dynamic `import()` calls to prevent sandbox escape. Pre-execution regex check + sandbox blocks `require()` and `process` access
+- **Advisor system overhaul** — convergence hardening with round-aware prompts, evidence rules, round cap (5 max). Design-review token gate. Simplified prompts, removed git dependency. Unified streaming block
+- **Verify guard improvements** — file path validation, error context enrichment, test coverage expanded
+
 ### 0.12.1 (2026-07)
 - **Fix: `/exit` screen artifacts** — `/exit` now uses synchronous `process.exit(0)` instead of the deferred cleanup callback, preventing the post-handler `render()` from redrawing the TUI over the cleaned terminal. Ctrl+C and `/exit` now produce identical clean exits.
 

package/package.json

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

package/src/advisor/history.mjs

@@ -0,0 +1,112 @@
+/**
+ * advisor/history.mjs — advisor history extraction: issue/response tables 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 |"
+export const CONVERGENCE_TABLE_HEADER = "| # | Orig# | File | Severity | Status | Notes |"
+export 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
+2. Security: unhandled exceptions, null references, resource leaks, race conditions
+3. Consistency: alignment with existing project patterns and conventions
+4. Completeness: missing callers, imports, or follow-up changes
+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).
+ */
+export function extractPriorIssueTable(history) {
+  // allClear: exact phrases the prompts instruct the advisor to use on a clean review.
+  // NOTE: "已修复" (Fixed) is NOT here — it's a per-row Status value in convergence tables,
+  // and a mixed table must continue convergence even if some rows are Fixed.
+  const allClear = ["no 🔴", "all clear", "全部通过", "review passed", "no issues found", "no new issues"]
+  // 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
+  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, 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 && partiallyFixedRe.test(lower)) return { text, sinceIdx: i }
+    if (allClear.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
+}
+
+/** 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++) {
+    const m = entries[i]
+    if (m.role !== "assistant" || typeof m.content !== "string") continue
+    if (m.content.includes(AGENT_RESPONSE_HEADER)) return m.content
+  }
+  return null
+}
+
+/**
+ * Load review criteria: project .thincoder/advisor.md if present,
+ * otherwise the built-in defaults.
+ */
+export function loadAdvisorMd(cwd) {
+  try {
+    return readFileSync(join(cwd, ADVISOR_MD_PATH), "utf8")
+  } catch {
+    return DEFAULT_CRITERIA
+  }
+}
+
+/** Extract recent user↔assistant exchanges (up to maxTurns) for intent context. */
+export function extractConversationBackground(history, maxTurns = 3) {
+  const entries = Array.isArray(history) ? history : []
+  const lines = []
+  let turns = 0
+  for (let i = entries.length - 1; i >= 0 && turns < maxTurns; i--) {
+    const m = entries[i]
+    if (m.role === "tool" || m.role === "system") continue
+    if (typeof m.content !== "string") continue
+    if (m.content.startsWith("[System reminder:") || m.content.startsWith("[System mode:") || m.content.startsWith("[Relevant memories")) continue
+    // ^ [System mode:] is not currently generated anywhere — kept as forward-looking
+    // defensive filtering in case convergence messages ever adopt a different prefix.
+    if (m.role === "user" || m.role === "assistant") {
+      lines.unshift(`${m.role === "user" ? "User" : "Assistant"}: ${m.content.slice(0, 400)}`)
+      if (m.role === "user") turns++
+    }
+  }
+  return lines.length > 0 ? lines.join("\n\n") : null
+}

package/src/advisor/messages.mjs

@@ -0,0 +1,182 @@
+/**
+ * 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/.
+ */
+import { readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
+import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable, extractPriorIssueTable } from "./history.mjs"
+
+/**
+ * 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" (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).
+ * @returns {string} the user message
+ */
+export function buildAdvisorUserMessage(agent, _prior, reviewType, designToken = null, documents = null, paths = null) {
+  const prior = _prior ?? extractPriorIssueTable(agent.history)
+
+  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()) : []
+
+  // Design review: simplified message — focus on the design doc, not code
+  if (reviewType === "design") {
+    const repos = findReviewRepos(agent)
+    parts.push("## Design Review")
+    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.
+      // _advisorLastSnapshot is only consumed by code-review convergence — skip the write here.
+      const snapshots = collectRepoSnapshots(repos, agent.cwd)
+      if (snapshots.length > 0) {
+        parts.push("## Design Document (git diff)")
+        parts.push(...snapshots)
+        parts.push("")
+      }
+    }
+
+    // Engineering mode: inject project methodology
+    if (agent.config?.agent?.engineering) {
+      try {
+        const mpath = resolve(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 */ }
+    }
+
+    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.")
+    } else {
+      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.")
+    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.")
+    }
+    return parts.join("\n")
+  }
+
+  // Convergence data (round 2+)
+  if (prior && (agent._advisorRound || 0) > 0) {
+    const response = extractAgentResponseTable(agent.history, prior.sinceIdx)
+      || "(Agent did not provide a response table — re-evaluate each issue)"
+    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("")
+    parts.push("---")
+    parts.push("")
+  }
+
+  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)
+  parts.push("")
+
+  // Engineering mode: inject project methodology so advisor knows the rules
+  if (agent.config?.agent?.engineering) {
+    try {
+      const mpath = resolve(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 */ }
+  }
+
+  // Instructions — round-aware: re-reviews skip convention discovery entirely
+  const isReReview = prior && (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.")
+  if (isReReview) {
+    parts.push("2. STALE-CONTEXT WARNING: any diff embedded in earlier messages is a historical snapshot — treat it as expired. Only the \"Current Changes\" section above and fresh `read` results describe the current state. Never quote a `-` line from any diff as if it were live code.")
+    parts.push("3. Do NOT re-read AGENTS.md / design docs — conventions were established in round 1. Focus on verifying the prior issue table against the current diff.")
+    parts.push("4. `read` only the files touched by the fixes. Batch independent reads/greps in a single reply.")
+    parts.push("5. Produce your verification table. Do not re-read content you already have.")
+  } 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("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")
+}

package/src/advisor/repos.mjs

@@ -0,0 +1,133 @@
+/**
+ * advisor/repos.mjs — git repository discovery and change collection for advisor reviews.
+ * Shared by message building (advisor.mjs) and the review runner (advisor/run.mjs).
+ */
+import { execFileSync } from "node:child_process"
+import { dirname, basename, resolve } from "node:path"
+
+export const GIT_TIMEOUT = 5_000
+export const MAX_EMBEDDED_DIFF = 50_000
+
+/**
+ * Find the git repository roots that contain the agent's touched files.
+ * Falls back to cwd if no repos found.
+ */
+export function findReviewRepos(agent, paths = null) {
+  const touched = agent._touchedFiles ?? []
+  const sources = paths ? [...touched, ...paths.map((p) => resolve(agent.cwd, p))] : touched
+  const repos = []
+
+  for (const abs of sources) {
+    try {
+      const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+        cwd: dirname(abs), encoding: "utf8", timeout: GIT_TIMEOUT,
+        stdio: ["ignore", "pipe", "pipe"],
+      }).trim()
+      if (root && !repos.includes(root)) repos.push(root)
+    } catch { /* not a git repo */ }
+  }
+
+  if (repos.length > 0) return repos
+
+  // Fallback: cwd itself
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      cwd: agent.cwd, encoding: "utf8", timeout: GIT_TIMEOUT,
+      stdio: ["ignore", "pipe", "pipe"],
+    }).trim()
+    if (root) return [root]
+  } catch { /* not a git repo */ }
+
+  return []
+}
+
+/**
+ * Collect git status + diff for each repo, embedded into the review context so
+ * the advisor doesn't need to spend its first tool calls discovering changes.
+ */
+export function collectRepoSnapshots(repos, cwd) {
+  const targets = repos.length > 0 ? repos : [cwd]
+  const parts = []
+  for (const repo of targets) {
+    let status = "", diff = ""
+    try {
+      status = execFileSync("git", ["status", "--porcelain"], {
+        cwd: repo, encoding: "utf8", timeout: GIT_TIMEOUT, stdio: ["ignore", "pipe", "pipe"],
+      }).trim()
+      diff = execFileSync("git", ["diff", "HEAD"], {
+        cwd: repo, encoding: "utf8", timeout: GIT_TIMEOUT, stdio: ["ignore", "pipe", "pipe"],
+        maxBuffer: 8 * 1024 * 1024,
+      })
+    } catch { continue /* not a git repo or git failed */ }
+    if (!status && !diff.trim()) continue
+    parts.push(`### ${repo}`)
+    if (status) parts.push("```", status, "```")
+    if (diff.trim()) {
+      const truncated = diff.length > MAX_EMBEDDED_DIFF
+      // Prepend a blockquote explaining diff notation to the LLM so it doesn't
+      // treat deleted lines (-) as still-present content (phantom-issue fix).
+      parts.push("**⚠️ IMPORTANT:** In the diff below, `-` lines are **REMOVED** (no longer in the file); `+` lines are **ADDED**. Always `read` the actual file for its current state — never treat a `-` line as still-present content.")
+      parts.push("```diff", truncated ? diff.slice(0, MAX_EMBEDDED_DIFF) : diff.trimEnd(), "```")
+      if (truncated) parts.push(`(diff truncated at ${MAX_EMBEDDED_DIFF} chars — use the git tool to see the rest)`)
+    }
+  }
+  return parts
+}
+
+/** List changed file paths (including untracked) across repos — used by design review
+ *  so the advisor knows which files to read even when git diff HEAD can't show them.
+ *  Multi-repo: each path is annotated with its repo basename so the advisor can resolve it. */
+export function collectChangedFiles(repos, cwd) {
+  const targets = repos.length > 0 ? repos : [cwd]
+  const files = []
+  for (const repo of targets) {
+    try {
+      const status = execFileSync("git", ["status", "--porcelain"], {
+        cwd: repo, encoding: "utf8", timeout: GIT_TIMEOUT, stdio: ["ignore", "pipe", "pipe"],
+      }).trim()
+      const repoLabel = targets.length > 1 ? `[${basename(repo)}] ` : ""
+      for (const line of status.split("\n")) {
+        // "XY path" or "XY old -> new" (rename) — take the final path, strip quotes
+        const pathParts = line.slice(3).split(" -> ")
+        const p = pathParts[pathParts.length - 1].trim().replace(/^"|"$/g, "")
+        if (p) files.push(repoLabel + p)
+      }
+    } catch { /* not a git repo — skip */ }
+  }
+  return files
+}
+
+const DOC_FILE = /(?:^|[/\\])(?:LICENSE|NOTICE|CHANGELOG|AUTHORS)(?:\.\w+)?$|\.(?:md|markdown|mdx|txt|rst|adoc)$/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
+ *  (e.g. src/prompts/*.md IS product code despite matching DOC_FILE).
+ *  See isDocOnlyChange for the combined check. */
+export function isDocFile(p) {
+  return DOC_FILE.test(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. */
+export function isDocOnlyChange(repos, cwd) {
+  const targets = repos.length > 0 ? repos : [cwd]
+  let sawChanges = false
+  for (const repo of targets) {
+    let status = ""
+    try {
+      status = execFileSync("git", ["status", "--porcelain"], {
+        cwd: repo, encoding: "utf8", timeout: GIT_TIMEOUT, stdio: ["ignore", "pipe", "pipe"],
+      }).trim()
+    } catch { continue /* repo inaccessible — check the rest */ }
+    if (!status) continue
+    sawChanges = true
+    for (const line of status.split("\n")) {
+      // porcelain: "XY path" or "XY old -> new" (rename)
+      const filePath = line.slice(3).split(" -> ").pop().replace(/^"|"$/g, "")
+      if (/^src[\\/]/.test(filePath) || !DOC_FILE.test(filePath)) return false
+    }
+  }
+  return sawChanges
+}