@jpkme/diff-review 0.1.10 → 0.1.12

package/lib/prompt.mjs

@@ -5,13 +5,17 @@
 import {
   makeOutputFilename,
   isOutputFilename,
+  OUTPUT_DIR,
   OUTPUT_FILENAME_LEGACY,
+  outputRelPath,
 } from "./output-name.mjs";
 
 export {
   makeOutputFilename,
   isOutputFilename,
+  OUTPUT_DIR,
   OUTPUT_FILENAME_LEGACY,
+  outputRelPath,
 };
 
 export const OUTPUT_SCHEMA_BLOCK = `{
@@ -28,7 +32,7 @@ export const OUTPUT_SCHEMA_BLOCK = `{
   "intent": "string",
   "groups": [
     {
-      "id": "g1",
+      "id": "t1",
       "kind": "feat|fix|refactor|perf|test|chore|docs|infra",
       "title": "string, aim for ≤72 chars, imperative, no kind prefix",
       "intent": "string"
@@ -37,14 +41,14 @@ export const OUTPUT_SCHEMA_BLOCK = `{
   "blocks": [
     {
       "id": "b1",
-      "group": "g1",
+      "group": "t1",
       "file": "relative/path.ext",
       "lines": "L40-58",
       "side": "new|old",
       "start": 40,
       "end": 58,
       "op": "add|mod|del|rename",
-      "what": "string, aim for ≤120 chars",
+      "what": "string, aim for ≤120 chars: concrete change + effect",
       "why": "string, aim for ≤120 chars",
       "source": "code|commit|pr|issue|inferred"
     }
@@ -59,8 +63,8 @@ export const OUTPUT_SCHEMA_BLOCK = `{
       "file": "relative/path.ext",
       "line": 87,
       "block": "b1",
-      "what": "string, aim for ≤120 chars",
-      "fix": "string, aim for ≤120 chars"
+      "what": "string, aim for ≤120 chars: concrete cause + observable consequence (what fails / risk / cost)",
+      "fix": "string, aim for ≤120 chars: suggested change + what the reader gains or avoids if applied"
     }
   ],
   "skipped": [
@@ -69,17 +73,29 @@ export const OUTPUT_SCHEMA_BLOCK = `{
   "notes": ["optional short limitations"]
 }`;
 
-const RULES = `- Coverage (hard): every path in the diff MUST appear in "blocks" and/or "skipped". Prefer a skipped glob when many files share one reason.
+const RULES = `- Ids: themes use \`t1\`, \`t2\`, …; findings use \`f1\`, \`f2\`, …; blocks use \`b1\`, \`b2\`, …. Reference themes from blocks via \`"group": "t1"\`.
+- Coverage (hard): every path in the diff MUST appear in "blocks" and/or "skipped". Prefer a skipped glob when many files share one reason.
 - Do NOT invent files, hunks, or line ranges that are not in the diff.
 - Line anchors: "lines"/"start"/"end"/"line" MUST match the chosen "side" ("new" = post-image / right side of @@; "old" = pre-image, typically deletions). One block per coherent change span, not one per line. Point findings at that block; leave "block" empty only if cross-cutting.
 - Do NOT report: pre-existing code outside the diff; linter/formatter noise; naming/style prefs with no real consequence; intentional branch behavior; silenced lint rules; "missing docs/coverage" without a concrete broken scenario.
 - Quality findings must name a concrete cost, not a vague feeling.
+- Finding "what": state the concrete cause and the observable consequence (what fails, the risk, or the cost) — not only a symptom.
+- Finding "fix": state the suggested change and what the reader gains or avoids if they apply it.
 - Signal over volume: prefer fewer high-signal findings. Order findings by severity (high, then nit). Use "nit" sparingly.
 - "blocking": true ONLY if the branch should not merge as-is. Use only with class "risk".
+- When several read-only lookups are independent (files, searches), batch them in the same turn if your tools allow parallel calls.
 - Write human-readable strings (intent, title, what, why, fix, notes) in Spanish. Keep enums/ids/paths/JSON keys exactly as in the schema.
-- Length is a target, not a check: aim for title ≤72 characters and what/why/fix ≤120 characters. Longer text is still valid. Do not rewrite the file only to shorten it.`;
+- Length is a soft target, not a check: aim for title ≤72 characters and what/why/fix ≤120 characters. Prefer clarity over shortening. Longer text is still valid. Do not rewrite the file only to shorten it.`;
 
-function workflowLocal(base, branch) {
+/** @param {{ hasDiff?: boolean }} [ctx] */
+function workflowLocal(base, branch, ctx = {}) {
+  if (ctx.hasDiff) {
+    return `Workflow:
+1. Read the three-dot diff from the path given in "Precomputed git context" below. Do not re-run \`git diff\` unless that file is missing.
+2. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+3. Emit the JSON file. Do not modify the repo.
+4. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
+  }
   return `Workflow:
 1. Resolve the merge-base of \`${base}\` and \`${branch}\`.
 2. Run exactly: \`git diff ${base}...${branch}\` (three-dot / merge-base diff). Do not use two-dot unless three-dot is impossible.
@@ -88,13 +104,22 @@ function workflowLocal(base, branch) {
 5. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
 }
 
-/** Comando que el agente debe correr; npx por si el bin no está en PATH. */
+/** Comando que el agente debe correr (sobre `.diff-review/<nombre>`); npx por si el bin no está en PATH. */
 export function validateCliCommand(filename) {
-  const file = String(filename || "diff-rev_<branchTip>_<baseTip>.json").trim();
+  const file = outputRelPath(String(filename || "diff-rev_<branchTip>_<baseTip>.json").trim());
   return `npx --yes @jpkme/diff-review validate ${file}`;
 }
 
-function workflowUrl(base, branch) {
+/** @param {{ hasDiff?: boolean }} [ctx] */
+function workflowUrl(base, branch, ctx = {}) {
+  if (ctx.hasDiff) {
+    return `Workflow:
+1. If the repo is not local, clone it (or use whatever access you have). Do not modify it.
+2. Read the three-dot diff from the path given in "Precomputed git context" below. Do not re-run \`git diff\` unless that file is missing.
+3. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+4. Emit the JSON file.
+5. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
+  }
   return `Workflow:
 1. If the repo is not local, clone it (or use whatever access you have). Do not modify it.
 2. Resolve the merge-base of \`${base}\` and \`${branch}\`.
@@ -104,6 +129,35 @@ function workflowUrl(base, branch) {
 6. Validate it with the command in the output section. If it prints INVALID, follow "How to continue" and re-run until it prints OK.`;
 }
 
+/** Workflow sin paso de validate por CLI (sesiones ACP: valida el server). */
+function workflowLocalAcp(ctx = {}) {
+  if (ctx.hasDiff) {
+    return `Workflow:
+1. Read the three-dot diff from the path given in "Precomputed git context" below. Do not re-run \`git diff\` unless that file is missing.
+2. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+3. Write the JSON with your file Write/Edit tool (never shell redirection). Do not modify other repo files. The host validates when your turn ends — do not run the validate CLI.`;
+  }
+  return `Workflow:
+1. Resolve the merge-base of the base and branch named above, then run the three-dot \`git diff base...branch\`.
+2. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+3. Write the JSON with your file Write/Edit tool (never shell redirection). Do not modify other repo files. The host validates when your turn ends — do not run the validate CLI.`;
+}
+
+function workflowUrlAcp(ctx = {}) {
+  if (ctx.hasDiff) {
+    return `Workflow:
+1. If the repo is not local, clone it (or use whatever access you have). Do not modify it.
+2. Read the three-dot diff from the path given in "Precomputed git context" below. Do not re-run \`git diff\` unless that file is missing.
+3. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+4. Write the JSON with your file Write/Edit tool (never shell redirection). The host validates when your turn ends — do not run the validate CLI.`;
+  }
+  return `Workflow:
+1. If the repo is not local, clone it (or use whatever access you have). Do not modify it.
+2. Resolve the merge-base, then run the three-dot \`git diff base...branch\`.
+3. Read enough surrounding code (types, callers, tests) to judge behavior, not only the hunk lines.
+4. Write the JSON with your file Write/Edit tool (never shell redirection). The host validates when your turn ends — do not run the validate CLI.`;
+}
+
 /**
  * @param {{ source?: string, repo?: string, branch?: string, base?: string, remoteUrl?: string }} meta
  */
@@ -130,18 +184,113 @@ export function outputSchemaBlock(meta) {
   return OUTPUT_SCHEMA_BLOCK.replace(/"meta": \{[\s\S]*?\n  \}/, metaBlock);
 }
 
+/**
+ * Bloque de contexto git ya resuelto (diff en disco, tips, lista de archivos, ignores).
+ * @param {{
+ *   diffRelPath?: string | null,
+ *   mergeBase?: string,
+ *   branchSha?: string,
+ *   baseSha?: string,
+ *   files?: Array<{ path: string, changeType?: string }>,
+ *   ignored?: string[],
+ *   ignoreGlobs?: string[],
+ * }} ctx
+ */
+function formatPrecomputedContext(ctx) {
+  const lines = ["Precomputed git context (do not rediscover):"];
+  if (ctx.mergeBase) lines.push(`- Merge-base SHA: \`${ctx.mergeBase}\``);
+  if (ctx.branchSha) lines.push(`- Branch tip SHA: \`${ctx.branchSha}\``);
+  if (ctx.baseSha) lines.push(`- Base tip SHA: \`${ctx.baseSha}\``);
+  if (ctx.diffRelPath) {
+    lines.push(
+      `- Diff file (relative to repo root): \`${ctx.diffRelPath}\` — read this file; do not re-run \`git diff\` unless it is missing.`
+    );
+  }
+  const files = Array.isArray(ctx.files) ? ctx.files : [];
+  if (files.length) {
+    lines.push(`- Files in the diff (${files.length}):`);
+    const limit = 200;
+    for (const f of files.slice(0, limit)) {
+      const path = String(f?.path || "").trim();
+      if (!path) continue;
+      const kind = String(f?.changeType || "").trim();
+      lines.push(kind ? `  - ${kind}: ${path}` : `  - ${path}`);
+    }
+    if (files.length > limit) lines.push(`  - … and ${files.length - limit} more`);
+  }
+  const ignored = Array.isArray(ctx.ignored) ? ctx.ignored.filter(Boolean) : [];
+  if (ignored.length) {
+    lines.push(
+      `- Ignored paths (excluded from the file list; if you mention them use "skipped" with reason "ignored"):`
+    );
+    for (const p of ignored.slice(0, 40)) lines.push(`  - ${p}`);
+    if (ignored.length > 40) lines.push(`  - … and ${ignored.length - 40} more`);
+  }
+  const globs = Array.isArray(ctx.ignoreGlobs) ? ctx.ignoreGlobs.filter(Boolean) : [];
+  if (globs.length) {
+    lines.push(`- Ignore globs (DEFAULT + config): ${globs.map((g) => `\`${g}\``).join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * @param {{ source?: string, repo?: string, branch?: string, base?: string, remoteUrl?: string }} meta
- * @param {{ outputFilename?: string }} [opts]
+ * @param {{
+ *   outputFilename?: string,
+ *   acp?: boolean,
+ *   diffRelPath?: string | null,
+ *   mergeBase?: string,
+ *   branchSha?: string,
+ *   baseSha?: string,
+ *   files?: Array<{ path: string, changeType?: string }>,
+ *   ignored?: string[],
+ *   ignoreGlobs?: string[],
+ * }} [opts]
  */
 export function buildPrompt(meta, opts = {}) {
   const outputFilename = opts.outputFilename || makeOutputFilename();
+  const outputPath = outputRelPath(outputFilename);
   const repo =
     String(meta.repo || "").trim() ||
     (meta.source === "url" ? "<git URL>" : "<absolute repo path>");
   const branch = String(meta.branch || "").trim() || "<branch under review>";
   const base = String(meta.base || "").trim() || "develop";
-  const workflow = meta.source === "url" ? workflowUrl(base, branch) : workflowLocal(base, branch);
+  const acp = Boolean(opts.acp);
+  const hasDiff = Boolean(String(opts.diffRelPath || "").trim());
+  const workflow = acp
+    ? meta.source === "url"
+      ? workflowUrlAcp({ hasDiff })
+      : workflowLocalAcp({ hasDiff })
+    : meta.source === "url"
+      ? workflowUrl(base, branch, { hasDiff })
+      : workflowLocal(base, branch, { hasDiff });
+
+  const precomputed = formatPrecomputedContext({
+    diffRelPath: opts.diffRelPath,
+    mergeBase: opts.mergeBase,
+    branchSha: opts.branchSha,
+    baseSha: opts.baseSha,
+    files: opts.files,
+    ignored: opts.ignored,
+    ignoreGlobs: opts.ignoreGlobs,
+  });
+  const hasPrecomputed =
+    hasDiff ||
+    opts.mergeBase ||
+    opts.branchSha ||
+    opts.baseSha ||
+    (opts.files && opts.files.length) ||
+    (opts.ignored && opts.ignored.length) ||
+    (opts.ignoreGlobs && opts.ignoreGlobs.length);
+
+  const validateSection = acp
+    ? `When done writing \`${outputPath}\`, stop. The host validates the JSON automatically and will send you any problems — do not run \`npx … validate\` yourself.`
+    : `After writing the file, validate it (npx so it works even if \`diff-review\` is not on PATH):
+
+\`${validateCliCommand(outputFilename)}\`
+
+- Exit 0 and a line starting with \`OK\` means the JSON is acceptable. Then tell me that \`${outputPath}\` was written.
+- Exit 1 prints \`INVALID\`, the problems, and how to continue. Fix the same file and re-run that exact command until it prints OK. Do not stop before OK.`;
 
   return `You are a senior code reviewer: strict but fair.
 
@@ -150,11 +299,13 @@ Branch under review: ${branch}
 Base (merge-base): ${base}
 
 ${workflow}
-
+${hasPrecomputed ? `\n${precomputed}\n` : ""}
 Rules:
 ${RULES}
 
-Write the result to \`${outputFilename}\` at the repo root.
+Write the result to \`${outputPath}\` (relative to the repo root; use forward slashes, never \`\\\`). The \`${OUTPUT_DIR}/\` folder is already created by the host — do not \`mkdir\` it.
+- If that file already exists: **Read it first**, then Edit/overwrite (or Write after Read). Many agents reject Write with "File has not been read yet" unless you Read that exact path first.
+- If it does not exist yet: Write is fine. Do NOT use shell redirection (\`>\`, \`>>\`, \`Out-File\`, \`tee\`, etc.) — those are rejected.
 - One JSON object only: first character \`{\`, last character \`}\`.
 - No prose before/after, no markdown fences.
 - Shape (copy "meta" source/repo/branch/base/remoteUrl as given; "agent" and "model" are required):
@@ -163,12 +314,7 @@ ${outputSchemaBlock(meta)}
 
 Include "meta" with the source/repo/branch/base above (and origin "remoteUrl" when local). "agent" and "model" are required: set "agent" to the product you are (Claude Code, Cursor, Codex, Copilot, Gemini, …) and "model" to the exact model id you are running. Do not leave placeholders or omit them; validation fails without both. "generatedAt" is optional (ISO-8601 now).
 
-Do NOT include diffs or a "files" array. The tool computes them with git when opening the report. Do not invent hunks or paste patches into the JSON.
-
-After writing the file, validate it (npx so it works even if \`diff-review\` is not on PATH):
+Do NOT include diffs or a "files" array. The tool loads the companion \`.diff\` (or computes with git if missing) when opening the report. Do not invent hunks or paste patches into the JSON.
 
-\`${validateCliCommand(outputFilename)}\`
-
-- Exit 0 and a line starting with \`OK\` means the JSON is acceptable. Then tell me that \`${outputFilename}\` was written.
-- Exit 1 prints \`INVALID\`, the problems, and how to continue. Fix the same file and re-run that exact command until it prints OK. Do not stop before OK.`;
+${validateSection}`;
 }

package/lib/review-dir.mjs

@@ -0,0 +1,108 @@
+/**
+ * Carpeta `.diff-review/` en la raíz del repo revisado: el JSON del reporte, el diff con el que se hizo y la sesión
+ * del agente, todo con el mismo nombre base (`diff-rev_<branchTip>_<baseTip>`). Se ignora sola con su propio
+ * `.gitignore`, así no deja cambios en archivos trackeados del repo.
+ *
+ * Los JSON viejos en la raíz del repo se siguen encontrando (`locateReviewFile`).
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { git } from "./git.mjs";
+import { OUTPUT_DIR } from "./output-name.mjs";
+
+export { OUTPUT_DIR };
+
+/** @typedef {{ agentId: string, sessionId: string, model?: string, updatedAt?: string }} SessionRef */
+
+export function reviewDir(repoRoot) {
+  return join(repoRoot, OUTPUT_DIR);
+}
+
+/** Crea `.diff-review/` (con su `.gitignore`) si no existe. */
+export function ensureReviewDir(repoRoot) {
+  const dir = reviewDir(repoRoot);
+  mkdirSync(dir, { recursive: true });
+  const ignore = join(dir, ".gitignore");
+  if (!existsSync(ignore)) writeFileSync(ignore, "# Generado por diff-review: nada de esta carpeta va al repo.\n*\n");
+  return dir;
+}
+
+/** `diff-rev_a_b.json` → `{ json, diff, session }` dentro de `.diff-review/`. */
+export function companionPaths(repoRoot, filename) {
+  const name = basename(String(filename || ""));
+  const stem = name.replace(/\.json$/i, "");
+  const dir = reviewDir(repoRoot);
+  return {
+    json: join(dir, name),
+    diff: join(dir, `${stem}.diff`),
+    session: join(dir, `${stem}.session.json`),
+  };
+}
+
+/** Dónde está el JSON de la review: `.diff-review/` primero y, si no, la raíz del repo (formato viejo). */
+export function locateReviewFile(repoRoot, filename) {
+  const name = basename(String(filename || ""));
+  if (!name) return null;
+  for (const candidate of [companionPaths(repoRoot, name).json, join(repoRoot, name)]) {
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      /* siguiente */
+    }
+  }
+  return null;
+}
+
+/**
+ * Guarda `git diff base...branch` junto al JSON (una vez por par de commits: el nombre ya trae los tips).
+ * @returns {string | null} el path, o null si git falló
+ */
+export function writeDiffCache(repoRoot, filename, { branch, base }) {
+  const { diff } = companionPaths(repoRoot, filename);
+  if (existsSync(diff)) return diff;
+  try {
+    const text = git(repoRoot, ["diff", `${base}...${branch}`]);
+    ensureReviewDir(repoRoot);
+    writeFileSync(diff, text);
+    return diff;
+  } catch {
+    return null;
+  }
+}
+
+/** Guarda un diff ya armado (p. ej. el que muestra la web), pisando el anterior. */
+export function writeDiffText(repoRoot, filename, text) {
+  ensureReviewDir(repoRoot);
+  const { diff } = companionPaths(repoRoot, filename);
+  writeFileSync(diff, String(text ?? ""));
+  return diff;
+}
+
+/** @returns {string | null} texto del companion `.diff`, o null si no existe / no se pudo leer */
+export function readDiffCache(repoRoot, filename) {
+  const { diff } = companionPaths(repoRoot, filename);
+  try {
+    if (!existsSync(diff)) return null;
+    return readFileSync(diff, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {SessionRef | null} */
+export function readSessionRef(repoRoot, filename) {
+  try {
+    const ref = JSON.parse(readFileSync(companionPaths(repoRoot, filename).session, "utf8"));
+    return ref && typeof ref.agentId === "string" && typeof ref.sessionId === "string" ? ref : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @param {SessionRef} ref */
+export function writeSessionRef(repoRoot, filename, ref) {
+  ensureReviewDir(repoRoot);
+  const full = { ...ref, updatedAt: new Date().toISOString() };
+  writeFileSync(companionPaths(repoRoot, filename).session, `${JSON.stringify(full, null, 2)}\n`);
+  return full;
+}

package/lib/review-meta.mjs

@@ -5,14 +5,15 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { decodePayload } from "./json-payload.mjs";
 
 /**
+ * `agentSession` = la sesión ACP que generó la review, para seguir conversando con el agente desde la web.
  * @param {string} filePath
- * @param {{ agent?: string, model?: string }} provenance
+ * @param {{ agent?: string, model?: string, agentSession?: { agentId: string, sessionId: string, outputFilename: string } }} provenance
  * @returns {boolean}
  */
-export function stampReviewProvenance(filePath, { agent, model } = {}) {
+export function stampReviewProvenance(filePath, { agent, model, agentSession } = {}) {
   const agentName = String(agent || "").trim();
   const modelId = String(model || "").trim();
-  if (!agentName && !modelId) return false;
+  if (!agentName && !modelId && !agentSession) return false;
 
   let payload;
   try {
@@ -27,6 +28,7 @@ export function stampReviewProvenance(filePath, { agent, model } = {}) {
     current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
   if (agentName) meta.agent = agentName;
   if (modelId) meta.model = modelId;
+  if (agentSession) meta.agentSession = { ...agentSession };
   payload.meta = meta;
   writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
   return true;

package/lib/review-meta.test.mjs

@@ -28,3 +28,14 @@ test("stampReviewProvenance no pisa el modelo si no hay uno", () => {
   assert.equal(saved.meta.agent, "Codex");
   assert.equal(saved.meta.model, "sonnet");
 });
+
+test("stampReviewProvenance guarda la sesión del agente", () => {
+  const dir = mkdtempSync(join(tmpdir(), "diff-review-meta-"));
+  const file = join(dir, "diff-rev_a_b.json");
+  writeFileSync(file, JSON.stringify({ meta: { agent: "x" }, intent: "x" }));
+
+  const agentSession = { agentId: "claude", sessionId: "s-1", outputFilename: "diff-rev_a_b.json" };
+  stampReviewProvenance(file, { agent: "Claude Code", model: "opus", agentSession });
+
+  assert.deepEqual(JSON.parse(readFileSync(file, "utf8")).meta.agentSession, agentSession);
+});

package/lib/review-prep.mjs

@@ -0,0 +1,63 @@
+/**
+ * Precomputa contexto git para el prompt de review (diff cache + lista de archivos).
+ */
+import { loadReviewConfig } from "./config.mjs";
+import { extractBranchDiff } from "./extract.mjs";
+import { outputRelPath } from "./output-name.mjs";
+import { ensureReviewDir, readDiffCache, writeDiffCache } from "./review-dir.mjs";
+
+/**
+ * Cachea el three-dot diff y arma las opciones de `buildPrompt` (tips, files, ignores).
+ * @param {{
+ *   repo: string,
+ *   branch: string,
+ *   base?: string,
+ *   outputFilename: string,
+ *   acp?: boolean,
+ * }} input
+ */
+export function prepareReviewPromptOpts(input) {
+  const repo = String(input.repo || "").trim();
+  const branch = String(input.branch || "").trim();
+  const base = String(input.base || "develop").trim() || "develop";
+  const outputFilename = String(input.outputFilename || "").trim();
+  if (!repo || !branch || !outputFilename) {
+    throw new Error("prepareReviewPromptOpts requiere repo, branch y outputFilename.");
+  }
+
+  ensureReviewDir(repo);
+  writeDiffCache(repo, outputFilename, { branch, base });
+  const cached = readDiffCache(repo, outputFilename);
+
+  let extracted;
+  try {
+    extracted = extractBranchDiff({
+      repo,
+      branch,
+      base,
+      ...(cached ? { cachedDiff: cached } : {}),
+    });
+  } catch {
+    extracted = extractBranchDiff({ repo, branch, base });
+  }
+
+  const config = loadReviewConfig(repo);
+  const diffRelPath = cached
+    ? outputRelPath(outputFilename).replace(/\.json$/i, ".diff")
+    : null;
+
+  return {
+    outputFilename,
+    acp: Boolean(input.acp),
+    diffRelPath,
+    mergeBase: extracted.mergeBase || undefined,
+    branchSha: extracted.branchSha || undefined,
+    baseSha: extracted.baseSha || undefined,
+    files: (extracted.files || []).map((f) => ({
+      path: f.path,
+      changeType: f.changeType,
+    })),
+    ignored: extracted.context?.ignored || [],
+    ignoreGlobs: config.ignore,
+  };
+}

package/lib/validate.mjs

@@ -218,9 +218,9 @@ TEXT LANGUAGE: Spanish (rioplatense, technical) for intent, groups.intent, block
 
 {
   "intent": "2-4 sentences on what the branch solves",
-  "groups": [{ "id": "g1", "kind": "feat", "title": "scope: summary (do not repeat kind)", "intent": "why this theme exists" }],
+  "groups": [{ "id": "t1", "kind": "feat", "title": "scope: summary (do not repeat kind)", "intent": "why this theme exists" }],
   "meta": { "agent": "<required: product name, e.g. Claude Code>", "model": "<required: exact model id>" },
-  "blocks": [{ "id": "b1", "group": "g1", "file": "exact/path.ts", "lines": "L40-58", "op": "mod", "what": "what changed", "why": "why", "source": "code" }],
+  "blocks": [{ "id": "b1", "group": "t1", "file": "exact/path.ts", "lines": "L40-58", "op": "mod", "what": "what changed", "why": "why", "source": "code" }],
   "findings": [{ "id": "f1", "class": "risk", "severity": "high", "blocking": true, "kind": "bug", "file": "path.ts", "line": 42, "block": "b1", "what": "what is wrong", "fix": "what to do" }],
   "skipped": [{ "file": "bun.lock", "reason": "lockfile" }]
 }

package/lib/wait-output.mjs

@@ -1,9 +1,10 @@
 /**
- * Espera a que aparezca un JSON de review válido en el repo.
+ * Espera a que aparezca un JSON de review válido en el repo: en `.diff-review/` o, como antes, en la raíz.
  */
 import { existsSync, readFileSync, statSync, watch } from "node:fs";
 import { basename, join } from "node:path";
 import { decodePayload } from "./json-payload.mjs";
+import { companionPaths, ensureReviewDir, locateReviewFile } from "./review-dir.mjs";
 import { REVIEW_SCHEMA, validateAgainst } from "./validate.mjs";
 
 /**
@@ -38,7 +39,8 @@ function readReview(target, since) {
  * @returns {{ path: string, payload: unknown } | null}
  */
 export function existingReviewOutput(repoRoot, filename) {
-  const target = join(repoRoot, filename);
+  const target = locateReviewFile(repoRoot, filename);
+  if (!target) return null;
   const read = readReview(target);
   return read && !read.errors.length ? { path: target, payload: read.payload } : null;
 }
@@ -51,13 +53,28 @@ export function existingReviewOutput(repoRoot, filename) {
  * @returns {Promise<{ path: string, payload: unknown }>}
  */
 export function waitForReviewOutput(repoRoot, filename, opts = {}) {
-  const target = join(repoRoot, filename);
   const name = basename(filename);
+  // Primero `.diff-review/`; también la raíz del repo por compatibilidad con salidas viejas.
+  const targets = [companionPaths(repoRoot, name).json, join(repoRoot, name)];
   const pollMs = opts.pollMs ?? 800;
   let lastInvalidKey = "";
+  let reviewDir = "";
+  try {
+    reviewDir = ensureReviewDir(repoRoot);
+  } catch {
+    /* repo de solo lectura: se espera igual en la raíz */
+  }
 
   const tryRead = () => {
-    const read = readReview(target, opts.since);
+    let target = "";
+    let read = null;
+    for (const candidate of targets) {
+      read = readReview(candidate, opts.since);
+      if (read) {
+        target = candidate;
+        break;
+      }
+    }
     if (!read) return null;
     const { payload, errors } = read;
     if (errors.length) {
@@ -73,8 +90,8 @@ export function waitForReviewOutput(repoRoot, filename, opts = {}) {
 
   return new Promise((resolve, reject) => {
     let settled = false;
-    /** @type {import('node:fs').FSWatcher | null} */
-    let watcher = null;
+    /** @type {import('node:fs').FSWatcher[]} */
+    const watchers = [];
     /** @type {ReturnType<typeof setInterval> | null} */
     let timer = null;
 
@@ -82,10 +99,12 @@ export function waitForReviewOutput(repoRoot, filename, opts = {}) {
       if (settled) return;
       settled = true;
       if (timer) clearInterval(timer);
-      try {
-        watcher?.close();
-      } catch {
-        /* ignore */
+      for (const w of watchers) {
+        try {
+          w.close();
+        } catch {
+          /* ignore */
+        }
       }
       resolve(result);
     };
@@ -94,10 +113,12 @@ export function waitForReviewOutput(repoRoot, filename, opts = {}) {
       if (settled) return;
       settled = true;
       if (timer) clearInterval(timer);
-      try {
-        watcher?.close();
-      } catch {
-        /* ignore */
+      for (const w of watchers) {
+        try {
+          w.close();
+        } catch {
+          /* ignore */
+        }
       }
       reject(err);
     };
@@ -114,15 +135,17 @@ export function waitForReviewOutput(repoRoot, filename, opts = {}) {
     tick();
     if (settled) return;
 
-    try {
-      watcher = watch(repoRoot, { persistent: true }, (_event, changed) => {
-        if (!changed || String(changed) === name || String(changed).endsWith(name)) tick();
-      });
-      watcher.on("error", () => {
-        /* poll sigue */
-      });
-    } catch {
-      /* solo poll */
+    // Los watchers solo adelantan el aviso; el poll de abajo alcanza si fallan.
+    for (const dir of [reviewDir, repoRoot].filter(Boolean)) {
+      try {
+        const w = watch(dir, { persistent: true }, (_event, changed) => {
+          if (!changed || String(changed) === name || String(changed).endsWith(name)) tick();
+        });
+        w.on("error", () => {});
+        watchers.push(w);
+      } catch {
+        /* solo poll */
+      }
     }
 
     timer = setInterval(tick, pollMs);