thincoder 0.12.62 → 0.12.64

package/src/advisor/messages.mjs

@@ -1,299 +0,0 @@
-/**
- * advisor/messages.mjs — advisor user-message building (buildAdvisorUserMessage).
- * Split out of advisor.mjs to keep it under the 300-line advisory threshold
- * (.thincoder/advisor.md). System prompts live in advisor.mjs / prompts/.
- * Project-context discovery/injection lives in project-context.mjs (the D-1 registration,
- * ENGINEERING-MODE.md §2.26.3); the pre-split surface is re-exported below.
- */
-import { join, relative, sep } from "node:path"
-import { findReviewRepos, collectRepoSnapshots, collectChangedFiles } from "./repos.mjs"
-import { buildConvergenceBody, buildConvergenceInstructions } from "./convergence.mjs"
-import { loadAdvisorMd, extractConversationBackground, extractAgentResponseTable } from "./history.mjs"
-import { injectProjectGuide, injectDocumentMap, injectProjectStandards, NO_GIT_NOTICE } from "./project-context.mjs"
-
-// Structural split (not an authority migration): the moved helpers stay reachable here.
-export { findProjectRoot, injectProjectGuide } from "./project-context.mjs"
-
-/**
- * Build the mechanical review-object declaration block (AGENT-LOOP.md §18.8
- * D-OA2 — English anchored form). Injected at the START of the review user
- * message every round: round 1 (design + code), the legacy convergence path,
- * and the round-2+ follow-up (see buildAdvisorFollowUp) — the reviewer must
- * not re-derive "who is being reviewed / why" from the documents (T-OA2:
- * every round stays anchored). Absent object → "" (legacy calls degrade to
- * the current behavior — T-OA3).
- * @param {Object|null} [object] — { type, target, status, reason, exclude }
- *   (strings; `exclude` may also be a list — joined with ", ")
- * @returns {string} the declaration block (empty when no object)
- */
-export function buildObjectDeclarationBlock(object = null) {
-  if (!object || typeof object !== "object" || Array.isArray(object)) return ""
-  const field = (v) => (Array.isArray(v) ? v.join(", ") : v == null ? "" : String(v))
-  return [
-    "## Review-object declaration (mechanical — do not infer)",
-    `Review type: ${field(object.type)} | Target: ${field(object.target)} | Object state: ${field(object.status)} | Trigger: ${field(object.reason)}`,
-    `Excluded (not in this review): ${field(object.exclude)}`,
-    "Follow this declaration — do not infer the review target from the documents.",
-    "",
-  ].join("\n")
-}
-
-/**
- * Approval-signal block for design reviews (round 1 and round 2+ — §11.2 D-24b:
- * an async fix-round continuation must be able to re-approve, so the token is
- * injected into EVERY design round; the reviewer echoes it only on a clean pass).
- * §29.1 F2a (2026-09-07): BOTH values are injected — the token AND the designId
- * (anchor sentence verbatim — Copy BOTH values). designId null (legacy direct
- * callers without a resolved instance) degrades to the token-only form.
- */
-export function buildDesignApprovalBlock(designToken, designId) {
-  const echo = designId
-    ? `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}] and this exact designId: ${designId}. Copy BOTH values verbatim.`
-    : `If — and ONLY if — your review finds NO 🔴 (Critical) issues, end your reply with this exact token: [DESIGN-TOKEN:${designToken}]`
-  return [
-    "## Approval Signal",
-    echo,
-    "🟡 (Advisory) and 🔵 (Note) findings do NOT block approval — list them if present, but still include the token. If there are any 🔴 issues, do NOT include the token.",
-  ].join("\n")
-}
-
-/**
- * Build the user message for an advisor review session.
- * @param {Object} agent — the parent agent
- * @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)
- * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1/D-OA3):
- *   { type, target, status, reason, exclude } — mechanically injected at the
- *   start of the user message; absent → no injection (legacy calls unchanged).
- * @param {string|null} [designId] — §29.1 F2a: injected next to the token in the
- *   Approval Signal (both values — the reviewer copies both verbatim); null →
- *   token-only degradation (legacy direct callers).
- * @returns {string} the user message
- */
-export function buildAdvisorUserMessage(agent, prior, reviewType, designToken = null, documents = null, paths = null, object = null, designId = null) {
-  const body = buildAdvisorUserMessageInner(agent, prior, reviewType, designToken, documents, paths, object, designId)
-  // B 构建自愈（F12/§14.4 #1）：design + token 且输出不含逐字信号 ⇒ 尾包补齐 Approval Signal。
-  // 覆盖所有出口（含 code 形态分支降级态与 legacy 收敛分支）——既有分支语义零改：已在分支内
-  // 注入过的路径因 `[DESIGN-TOKEN:{token}` 逐字在场而不重复追加（幂等）。
-  if (reviewType !== "design" || !designToken) return body
-  if (body.includes(`[DESIGN-TOKEN:${designToken}`)) return body
-  return `${body}\n\n${buildDesignApprovalBlock(designToken, designId)}`
-}
-
-/** 内层构建（无自愈尾包）——出口、分支与消息形态与拆分前逐字一致。 */
-function buildAdvisorUserMessageInner(agent, prior, reviewType, designToken = null, documents = null, paths = null, object = null, designId = null) {
-  // prior = the full prior review output (string) when a convergence round is
-  // being built (decision 2026-08-08 — verbatim injection, model understands it).
-  // Deterministic: only _advisorRound > 0 with stored output counts.
-  const p = prior ?? ((agent._advisorRound || 0) > 0 ? agent._lastAdvisorOutput : null)
-
-  const parts = []
-  // Review-object declaration FIRST — D-OA1: at the start of the user message
-  // (after the system prompt, before the review content). Covers round 1
-  // design/code and the legacy convergence path; the round-2+ normal path
-  // prepends it in buildAdvisorFollowUp (T-OA2 — every round stays anchored).
-  const declaration = buildObjectDeclarationBlock(object)
-  if (declaration) parts.push(declaration)
-  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)
-    parts.push("## Design Review")
-    // FR15/P8: no git → change-set context is unavailable. Say it (never silent).
-    if (repos.length === 0) {
-      parts.push(NO_GIT_NOTICE)
-      parts.push("")
-    }
-    if (docList.length > 0) {
-      // Explicit review scope (engineering mode, FR2): the caller hands over the
-      // doc list — the advisor reviews ONLY these. No git-diff change-set
-      // 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.
-      const snapshots = collectRepoSnapshots(repos, agent.cwd)
-      if (snapshots.length > 0) {
-        parts.push("## Design Document (git diff)")
-        parts.push(...snapshots)
-        parts.push("")
-      }
-    }
-
-    // Engineering mode: the project's DECLARED standards document
-    // (advisor.standardsDoc) — undeclared degrades visibly (PO-2).
-    if (agent.config?.agent?.engineering) {
-      injectProjectStandards(agent, parts, guideRoot)
-    }
-
-    // Document map: declared path wins, the built-in fallback probe (docs/README.md
-    // → docs/design/README.md) stays; neither → explicit degradation sentence
-    // (never the old silent skip).
-    injectDocumentMap(agent, parts, guideRoot ?? agent.cwd)
-
-    parts.push("## Instructions")
-    if (docList.length > 0) {
-      parts.push("1. Read every document in the Documents to Review list in full — review ONLY those files.")
-    } else {
-      parts.push("1. Read the design document fully.")
-    }
-    parts.push("2. Review against: completeness (all requirements covered?), feasibility (can this be built?), methodology compliance (does it follow the project's standards as provided?), clarity (specific enough?), acceptance criteria (verifiable?), scope (appropriate?).")
-    parts.push("3. If the ## Project Guide (AGENTS.md) section above is present, also check requirement fit: does the design match what the requirements documents it points to actually ask for?")
-    parts.push("4. Do NOT run git diff or look for code changes — there are none at this stage.")
-    parts.push("5. If you find issues, produce your review table with the format: | # | Category | Severity | Issue | Suggestion |. If the design passes, no table is needed.")
-    if (designToken) {
-      parts.push("")
-      parts.push(buildDesignApprovalBlock(designToken, designId))
-    }
-    return parts.join("\n")
-  }
-
-  // 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
-    parts.push(buildConvergenceBody(p, response, round, scopeFiles))
-    parts.push("")
-    parts.push("---")
-    parts.push("")
-  }
-
-  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("")
-    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)
-  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: project standards (declaration-only, same helper as the
-  // design path) — undeclared degrades visibly (PO-2).
-  if (agent.config?.agent?.engineering) {
-    injectProjectStandards(agent, parts, guideRoot)
-  }
-
-  // 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.")
-  if (isReReview) {
-    const round = (agent._advisorRound || 0) + 1
-    parts.push(...buildConvergenceInstructions(round, pathList))
-  } else {
-    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.")
-  }
-  parts.push("")
-  parts.push("Return your review as a markdown table (or a clear statement that everything is fine).")
-
-  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/project-context.mjs

@@ -1,194 +0,0 @@
-/**
- * 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).
-  const ctx = providerSpec(agent.provider).context
-  const cap = Math.max(PROJECT_GUIDE_MIN, Math.floor(ctx * PROJECT_GUIDE_FRACTION))
-  const shown = text.length <= cap
-    ? text
-    : [...text].slice(0, cap).join("") + `\n\n…(truncated at ${cap} chars — read the full file if you need more)` // codepoint-safe slice: no broken surrogate pairs at the boundary
-  parts.push(`<!-- Project root: ${relative(agent.cwd, path).split(sep).join("/")} (inferred from the review scope under ${agent.cwd}) -->`)
-  parts.push("This file defines the project's structure and where its requirements/design documents live. Read the documents it points to — the user's requirements live THERE, not only in the conversation background.")
-  parts.push("")
-  parts.push(shown)
-  parts.push("")
-  return root // guide injected — requirement-fit criteria apply (truthy root)
-}
-
-/**
- * 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/src/advisor/repos.mjs

@@ -1,150 +0,0 @@
-/**
- * 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
-}