@thincoder/core 0.9.1

package/advisor/notice.mjs

@@ -0,0 +1,141 @@
+/**
+ * advisor/notice.mjs — advisor 拒回 / 失败结论文案 + 对象标识行（单源；2026-09-18 顾问面治理批）。
+ *
+ * 三族文案共用本档（设计权威 = `docs/core/design/ADVISOR-GUARDS.md` §2.4 / §2.5 / §7）：
+ *  1. **类型门拒回**（F30——顶层 `type` 缺 / 非法 / 与 `object` 声明冲突 ⇒ 拒发）；
+ *  2. **范围拒回标识行**（F31——三处范围拒绝的既有稳定前缀逐字 + 标识块尾随）；
+ *  3. **失败结算结论块**（F28/F29——code / design 两轨共用；判据名纯函数 + 人读说明表）。
+ * 本档为叶子模块（零仓内导入——纯函数、零状态、零 LLM 输出解析 = N20）；文案逐字 = 设计档，
+ * 改动须同轮同步该档（D2 单一权威源）。
+ */
+
+/** 对象标识行（F31 单源）：`[type=… · scope=… · round=… · criterion=…]`。 */
+export function identityLine({ type, scope, round, criterion }) {
+  return `[type=${type} · scope=${scope} · round=${round} · criterion=${criterion}]`
+}
+
+/** 范围摘要（首路径 + `+N more`；无范围 ⇒ `none`）。 */
+export function scopeSummary(list) {
+  const items = (Array.isArray(list) ? list : []).filter((p) => typeof p === "string" && p.trim())
+  if (items.length === 0) return "none"
+  return items.length === 1 ? items[0] : `${items[0]} +${items.length - 1} more`
+}
+
+/** 拒回族统一形态（F31）：既有稳定前缀逐字（行首）+ 标识块尾随——两句同时满足。 */
+export function withIdentityLine(text, fields) {
+  return `${text} ${identityLine(fields)}`
+}
+
+// ─── ① 类型门（F30——ADVISOR-GUARDS.md §2.4）───────────────────────────────────
+
+const isLegalTrack = (v) => v === "code" || v === "design"
+
+/** 实收值原样回显（非字符串经 JSON 化——不推断、不近似）。 */
+function receivedText(rawType) {
+  if (typeof rawType === "string") return rawType
+  try {
+    return JSON.stringify(rawType) ?? String(rawType)
+  } catch {
+    return String(rawType)
+  }
+}
+
+/**
+ * 类型门判据名（纯函数——判定枚举闭合三值；`null` = 放行）。
+ * `type-missing` = 缺失 / `null` / 空串 / 纯空白串；`type-invalid` = 非空非法值 / 非字符串；
+ * `type-object-conflict` = 顶层显式合法值 ∧ `object.type` 声明为**另一**合法值（窄读法：非法
+ * 声明值不构成轨矛盾——`object` 只描述评审对象、不选轨）。
+ */
+export function typeGateCriterion(rawType, declaredType) {
+  if (rawType === undefined || rawType === null || (typeof rawType === "string" && rawType.trim() === "")) {
+    return "type-missing"
+  }
+  if (!isLegalTrack(rawType)) return "type-invalid"
+  return isLegalTrack(declaredType) && declaredType !== rawType ? "type-object-conflict" : null
+}
+
+/** 类型门拒发串（逐字——§2.4：前缀行 + `Why` 三形态 + 对象声明追加行 + 两个合法值行）。 */
+export function buildTypeGateRefusal({ criterion, received = null, declared = null, scope = "none" }) {
+  const line = identityLine({
+    // 冲突拒回记顶层实收值（未定轨）；未定轨两分支记 absent / invalid。
+    type: criterion === "type-object-conflict" ? String(received) : (criterion === "type-missing" ? "absent" : "invalid"),
+    scope,
+    round: "—", // 判定先于实例解析——本次发起无轮次（§2.5 字段行）
+    criterion,
+  })
+  const why = criterion === "type-missing"
+    ? "Why: the call carried no type at the top level — an omitted type must not silently fall back to the code track (that is how a design review becomes a code review without anyone noticing)."
+    : criterion === "type-invalid"
+      ? `Why: "${receivedText(received)}" is not one of the two legal values — there is no closest-match guessing and no silent fallback.`
+      : `Why: the top-level type="${received}" disagrees with the object declaration object.type="${declared}" — align them: set the top-level type to "${declared}", or change the object.type declaration to "${received}".`
+  const parts = [
+    `Advisor: launch refused — the tool call must carry an explicit type at the top level, one of the two legal values below. ${line}`,
+    why,
+  ]
+  // 对象声明追加行（归位——附于未定轨两分支，仅当 object.type === "design" 声明在位）。
+  if (declared === "design" && criterion !== "type-object-conflict") {
+    parts.push('The object declaration says type="design"; the declaration describes the review target, it does not select the review track.')
+  }
+  parts.push(
+    '  • type="code"   — code review: reviews the code you changed; pass paths=[...] to scope files/directories (documents=[...] adds acceptance-criteria context).',
+    '  • type="design" — design review: reviews design / requirement documents; pass documents=[...] (the explicit list) — plus batchDoc when a batch record is in flight.',
+    "Nothing was sent: no review instance, no round consumed, no design token minted, no LLM call.",
+  )
+  return parts.join("\n")
+}
+
+// ─── ② 失败结算（F28 / F29——ADVISOR-GUARDS.md §7）─────────────────────────────
+
+/**
+ * 失败结算判据名（纯函数单源、零状态——§7 契约一优先级，自上而下首个命中）。
+ * @returns {string|null} 判据名；`null` = 可用判决 / 无尝试发生（不产结论块）。
+ */
+export function settlementCriterion(input) {
+  const { launchRefused = false, stale = false, hasResult = true, incomplete = null, persistFailed = false } = input ?? {}
+  if (launchRefused) return null // 1. 未发起请求（无尝试发生）
+  if (stale) return "stale" // 2. 陈旧结算（未产出可用凭证）
+  if (!hasResult) return "no_report" // 3. 无报告（fail-closed）
+  if (incomplete && incomplete !== "interrupted") return String(incomplete) // 4. 宿主截断尾五 kind
+  if (incomplete === "interrupted") return null // 5. 用户 / 系统中断——被丢弃的尝试
+  if (persistFailed) return "no_credential" // 6. pass 但槽落盘失败（设计专属面）
+  return null // 7. 可用判决（pass 且落盘成功 / changes-required）
+}
+
+/** 判据名 → 人读说明（逐字——§7 表第三列；`no_credential` 设计专属、`stale` 两轨）。 */
+const CRITERION_MEANINGS = {
+  timeout: "review exceeded the wall-clock budget (agent.advisor.timeoutMs)",
+  context_limit: "review exceeded the model context budget",
+  turn_cap: "review exceeded the tool-round limit",
+  empty: "the provider returned an empty response",
+  review_failed: "provider / transport error",
+  stale: "the reviewed target changed while the review was in flight",
+  no_credential: "the token could not be written to the session ledger",
+  no_report: "the review settled without a report",
+}
+
+export function criterionMeaning(name) {
+  return CRITERION_MEANINGS[name] ?? String(name ?? "")
+}
+
+/**
+ * 失败结论块（逐字——§7 契约二；**两轨共用**）：块首行 = 对象标识行，既有结算正文逐字下沉为
+ * 块体，尝试表 = **本次尝试单行**（`#` = 实例尝试序号；零跨次载体），选项三值不自动执行。
+ * @param {{type: string, scope: string, round: number, criterion: string, body: string|null}} p
+ */
+export function buildSettlementConclusion({ type, scope, round, criterion, body }) {
+  const lines = [
+    `Advisor: review failure — 本轮未产出可用结论 (no usable settlement) ${identityLine({
+      type, scope, round: `${round}/uncapped`, criterion,
+    })}`,
+  ]
+  const text = String(body ?? "").trim()
+  if (text) lines.push(text)
+  lines.push(
+    "Failed attempts in this review instance (most recent last):",
+    "| # | outcome | meaning |",
+    "|---|---|---|",
+    `| ${round} | ${criterion} | ${criterionMeaning(criterion)} |`,
+    "Options: 1. proceed as-is (no usable conclusion — design: no token, implementation stays gated; code: the code face stays unapproved) · 2. narrow or change the scope and re-run · 3. stop and report to the user",
+  )
+  return lines.join("\n")
+}

package/advisor/project-context.mjs

@@ -0,0 +1,197 @@
+/**
+ * advisor/project-context.mjs — project-context discovery and injection for review
+ * messages (Project Guide, document map, project standards, change-set context).
+ *
+ * Split out of messages.mjs (the split registered as D-1 in ENGINEERING-MODE.md
+ * §2.26.3, trigger "thicken again" — met by this batch). messages.mjs keeps its
+ * pre-split surface via re-export; this module is consumed by it only.
+ *
+ * Portability contract (PORTABILITY FR10/FR11 · PO-1/PO-2 · P8): every discovery
+ * step here is either satisfied or DEGRADED VISIBLY. The old code probed a fixed
+ * `docs/README.md` and a fixed `METHODOLOGY.md` and skipped injection silently when
+ * absent — in a project with a different layout the reviewer still scored the
+ * dimension it could no longer check (silent failure, the worst class: invisible
+ * and unfixable by the user). Missing pieces now say so, and the reviewer is told
+ * to state the limitation in its findings. Projects can point at their own files
+ * through `.thincoder/conventions.json` (advisor.docMap / advisor.standardsDoc).
+ */
+import { readFileSync, existsSync } from "node:fs"
+import { resolve, join, relative, dirname, sep } from "node:path"
+import { providerSpec } from "../config.mjs"
+import { loadConventions } from "../conventions.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
+
+/** Absent-AGENTS.md notice (guide is optional: the conversation carries intent). */
+export const NO_GUIDE_NOTICE = "(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.)"
+
+/** Explicit degradation sentences (PORTABILITY design §4.4 — verbatim). */
+export const NO_DOC_MAP_NOTICE = "(No document map found under the project root, and none is declared — the Document ownership criterion is degraded: check placement against the Project Guide where present, and state the limitation in your findings.)"
+export const NO_STANDARDS_NOTICE = "(No project standards document was declared — judge methodology compliance from the Project Guide (when present) and the review criteria above; state the limitation in your findings.)"
+export const NO_GIT_NOTICE = "(No git repository detected — change-set context is unavailable; read the review-scope files directly.)"
+
+/**
+ * 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
+ */
+export 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
+ */
+export 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_GUIDE_NOTICE)
+    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_GUIDE_NOTICE)
+    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).
+  // 字段名归一：解析后的 provider 挂点两端其一（`provider` 本体字段 / `_provider` 运载字段）
+  // ——取在场者，两形态同语义（都指本回合生效的 provider 对象）。
+  const resolvedProvider = agent.provider ?? agent._provider
+  const ctx = providerSpec(resolvedProvider).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)
+}
+
+/**
+ * Inject the project document map (PO-1). Resolution: the DECLARED path
+ * (`advisor.docMap`, project-root-relative) wins; the built-in probe
+ * (`docs/README.md` → `docs/design/README.md`) stays as a fallback for projects
+ * laid out that way. Neither usable → an explicit degradation sentence — never a
+ * silent skip: the reviewer must know the Document-ownership criterion is unchecked.
+ * @returns {string|null} the injected map path, or null when degraded
+ */
+export function injectDocumentMap(agent, parts, root) {
+  const base = root ?? agent.cwd
+  const conv = loadConventions(agent.cwd)
+  let mapPath = null
+  if (conv.advisor.docMap) {
+    const declared = resolve(base, conv.advisor.docMap)
+    if (existsSync(declared)) mapPath = declared
+  } else {
+    mapPath = [resolve(base, "docs", "README.md"), resolve(base, "docs", "design", "README.md")]
+      .find((p) => existsSync(p)) ?? null
+  }
+  parts.push("## Document Map")
+  let text = null
+  if (mapPath) {
+    try {
+      text = readFileSync(mapPath, "utf8")
+    } catch (e) {
+      console.warn(`[advisor] document map unreadable at ${mapPath}: ${e.message}`)
+    }
+  }
+  if (text === null) {
+    parts.push(NO_DOC_MAP_NOTICE) // degraded — visible by contract
+    parts.push("")
+    return null
+  }
+  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(text)
+  parts.push("")
+  return mapPath
+}
+
+/**
+ * Inject the project standards document (PO-2). DECLARATION ONLY
+ * (`advisor.standardsDoc`, project-root-relative): the old hardcoded
+ * `METHODOLOGY.md` probe injected a file most projects do not have — and its
+ * absence was silent. Undeclared (or unreadable) → explicit degradation sentence.
+ * @returns {string|null} the injected standards path, or null when degraded
+ */
+export function injectProjectStandards(agent, parts, root) {
+  const base = root ?? agent.cwd
+  const conv = loadConventions(agent.cwd)
+  const declared = conv.advisor.standardsDoc ? resolve(base, conv.advisor.standardsDoc) : null
+  parts.push("## Project Standards")
+  let text = null
+  if (declared && existsSync(declared)) {
+    try {
+      text = readFileSync(declared, "utf8")
+    } catch (e) {
+      console.warn(`[advisor] project standards unreadable at ${declared}: ${e.message}`)
+    }
+  }
+  if (text === null) {
+    parts.push(NO_STANDARDS_NOTICE) // degraded — visible by contract
+    parts.push("")
+    return null
+  }
+  parts.push("The project declares these standards for this review. Judge the design/changes against them:")
+  parts.push(text)
+  parts.push("")
+  return declared
+}

package/advisor/repos.mjs

@@ -0,0 +1,150 @@
+/**
+ * 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"
+import { loadConventions, isCodePath } from "../conventions.mjs"
+
+const GIT_TIMEOUT = 5_000
+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
+}
+
+// Path classification (code / doc / temp) lives in ../conventions.mjs — the single
+// authority shared by every gate and guard (PORTABILITY FR12 / PO-10). This module
+// consumes it: `isDocFile` / `isTempFile` were retired here (no re-export — a second
+// import path would recreate the drift the authority exists to remove).
+
+/**
+ * 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.
+ * Classification semantics (incl. "a declared code segment wins over temp/doc")
+ * live in conventions.mjs; _touchedFiles stores ABSOLUTE paths, which the
+ * segment matcher handles at any depth.
+ */
+export function hasCodeMutations({ _touchedFiles, _mutatedThisRun, cwd }) {
+  const files = _touchedFiles ?? []
+  if (files.length === 0) return _mutatedThisRun
+  const conv = loadConventions(cwd)
+  return files.some((p) => isCodePath(p, conv))
+}
+
+/** True when all changed files across repos are documentation (md/txt/LICENSE etc.).
+ *  Anything inside a code segment (incl. src/prompts/*.md) counts as product code —
+ *  the same authority the design gate uses. Paths here are repo-relative. */
+export function isDocOnlyChange(repos, cwd) {
+  const conv = loadConventions(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, "")
+      // Code (a declared code segment is unconditional, even for tmp-*.mjs) →
+      // not a doc-only change; docs and temp scratch files fall through.
+      if (isCodePath(filePath, conv)) return false
+    }
+  }
+  return sawChanges
+}