@jpkme/diff-review 0.1.16 → 0.1.18

package/lib/extract-cache.test.mjs

@@ -1,162 +1,162 @@
-import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, test } from "node:test";
-import { extractBranchDiff, parseGitDiffFiles } from "./extract.mjs";
-import { OUTPUT_DIR } from "./output-name.mjs";
-import { companionPaths, ensureReviewDir, writeDiffText } from "./review-dir.mjs";
-import { checkReportFile } from "./check-report.mjs";
-
-const sample = [
-  "diff --git a/src/a.ts b/src/a.ts",
-  "index 111..222 100644",
-  "--- a/src/a.ts",
-  "+++ b/src/a.ts",
-  "@@ -1,2 +1,3 @@",
-  " keep",
-  "-old",
-  "+new",
-  "+extra",
-  "diff --git a/package-lock.json b/package-lock.json",
-  "index 1..2 100644",
-  "--- a/package-lock.json",
-  "+++ b/package-lock.json",
-  "@@ -1 +1 @@",
-  "-{}",
-  "+{ }",
-  "diff --git a/old.ts b/new.ts",
-  "similarity index 90%",
-  "rename from old.ts",
-  "rename to new.ts",
-  "index 1..2 100644",
-  "--- a/old.ts",
-  "+++ b/new.ts",
-  "@@ -1 +1 @@",
-  "-x",
-  "+y",
-].join("\n");
-
-const dirs = [];
-afterEach(() => {
-  for (const d of dirs.splice(0)) {
-    try {
-      rmSync(d, { recursive: true, force: true });
-    } catch {
-      /* ignore */
-    }
-  }
-});
-
-test("parseGitDiffFiles splits paths and change types", () => {
-  const files = parseGitDiffFiles(sample);
-  assert.equal(files.length, 3);
-  assert.equal(files[0].path, "src/a.ts");
-  assert.equal(files[0].changeType, "modified");
-  assert.match(files[0].hunkDiff, /^@@/);
-  assert.equal(files[1].path, "package-lock.json");
-  assert.equal(files[2].changeType, "renamed");
-  assert.equal(files[2].path, "new.ts");
-  assert.equal(files[2].oldPath, "old.ts");
-});
-
-test("extractBranchDiff with cachedDiff applies DEFAULT_IGNORE", () => {
-  const repo = mkdtempSync(join(tmpdir(), "diff-review-cache-"));
-  dirs.push(repo);
-  mkdirSync(join(repo, "src"), { recursive: true });
-  // repo path only used for config/guidelines; no git needed when cachedDiff is set
-  const skeleton = extractBranchDiff({
-    repo,
-    branch: "feature",
-    base: "develop",
-    cachedDiff: sample,
-  });
-  assert.deepEqual(
-    skeleton.files.map((f) => f.path).sort(),
-    ["new.ts", "src/a.ts"]
-  );
-  assert.ok(skeleton.context.ignored.includes("package-lock.json"));
-  assert.match(skeleton.files.find((f) => f.path === "src/a.ts").diff, /^@@/);
-});
-
-test("checkReportFile reuses companion .diff paths without inventing coverage", () => {
-  const repo = mkdtempSync(join(tmpdir(), "diff-review-check-"));
-  dirs.push(repo);
-  ensureReviewDir(repo);
-  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
-  writeDiffText(repo, filename, sample);
-  const payload = {
-    meta: {
-      agent: "Cursor",
-      model: "composer",
-      repo,
-      branch: "feature",
-      base: "develop",
-    },
-    intent: "Cambia src/a.ts y renombra old.ts para dejar el módulo listo en la rama.",
-    groups: [{ id: "g1", kind: "feat", title: "Ajuste", intent: "base" }],
-    blocks: [
-      {
-        id: "b1",
-        group: "g1",
-        file: "src/a.ts",
-        lines: "L1-3",
-        op: "mod",
-        what: "cambia la lógica",
-        why: "hace falta",
-        source: "code",
-      },
-      {
-        id: "b2",
-        group: "g1",
-        file: "new.ts",
-        lines: "L1",
-        op: "rename",
-        what: "renombra el módulo",
-        why: "nombre más claro",
-        source: "code",
-      },
-    ],
-    findings: [],
-    skipped: [{ file: "package-lock.json", reason: "lockfile" }],
-  };
-  const jsonPath = companionPaths(repo, filename).json;
-  writeFileSync(jsonPath, JSON.stringify(payload));
-  // Sin git: loadBranchDiff lee el .diff y aplica ignore (lockfile fuera de paths).
-  const result = checkReportFile(jsonPath, { repo, branch: "feature", base: "develop" });
-  assert.equal(result.ok, true, result.errors.join("; "));
-});
-
-test("buildPrompt with precomputed context skips merge-base rediscovery", async () => {
-  const { buildPrompt } = await import("./prompt.mjs");
-  const text = buildPrompt(
-    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
-    {
-      outputFilename: "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json",
-      diffRelPath: ".diff-review/diff-rev_aaaaaaaaaa_bbbbbbbbbb.diff",
-      mergeBase: "abc123",
-      branchSha: "def456",
-      baseSha: "789abc",
-      files: [{ path: "src/a.ts", changeType: "modified" }],
-      ignored: ["package-lock.json"],
-      ignoreGlobs: ["**/package-lock.json"],
-    }
-  );
-  assert.match(text, /Precomputed git context/);
-  assert.match(text, /diff-rev_aaaaaaaaaa_bbbbbbbbbb\.diff/);
-  assert.match(text, /Merge-base SHA: `abc123`/);
-  assert.match(text, /modified: src\/a\.ts/);
-  assert.doesNotMatch(text, /Resolve the merge-base/);
-  assert.doesNotMatch(text, /Run exactly: `git diff/);
-});
-
-test("buildPrompt acp omits validate CLI", async () => {
-  const { buildPrompt, validateCliCommand } = await import("./prompt.mjs");
-  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
-  const text = buildPrompt(
-    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
-    { outputFilename: filename, acp: true, diffRelPath: `.${OUTPUT_DIR}/${filename.replace(/\.json$/, ".diff")}` }
-  );
-  assert.doesNotMatch(text, new RegExp(validateCliCommand(filename).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
-  assert.match(text, /host validates/i);
-});
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, test } from "node:test";
+import { extractBranchDiff, parseGitDiffFiles } from "./extract.mjs";
+import { OUTPUT_DIR } from "./output-name.mjs";
+import { companionPaths, ensureReviewDir, writeDiffText } from "./review-dir.mjs";
+import { checkReportFile } from "./check-report.mjs";
+
+const sample = [
+  "diff --git a/src/a.ts b/src/a.ts",
+  "index 111..222 100644",
+  "--- a/src/a.ts",
+  "+++ b/src/a.ts",
+  "@@ -1,2 +1,3 @@",
+  " keep",
+  "-old",
+  "+new",
+  "+extra",
+  "diff --git a/package-lock.json b/package-lock.json",
+  "index 1..2 100644",
+  "--- a/package-lock.json",
+  "+++ b/package-lock.json",
+  "@@ -1 +1 @@",
+  "-{}",
+  "+{ }",
+  "diff --git a/old.ts b/new.ts",
+  "similarity index 90%",
+  "rename from old.ts",
+  "rename to new.ts",
+  "index 1..2 100644",
+  "--- a/old.ts",
+  "+++ b/new.ts",
+  "@@ -1 +1 @@",
+  "-x",
+  "+y",
+].join("\n");
+
+const dirs = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    try {
+      rmSync(d, { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+});
+
+test("parseGitDiffFiles splits paths and change types", () => {
+  const files = parseGitDiffFiles(sample);
+  assert.equal(files.length, 3);
+  assert.equal(files[0].path, "src/a.ts");
+  assert.equal(files[0].changeType, "modified");
+  assert.match(files[0].hunkDiff, /^@@/);
+  assert.equal(files[1].path, "package-lock.json");
+  assert.equal(files[2].changeType, "renamed");
+  assert.equal(files[2].path, "new.ts");
+  assert.equal(files[2].oldPath, "old.ts");
+});
+
+test("extractBranchDiff with cachedDiff applies DEFAULT_IGNORE", () => {
+  const repo = mkdtempSync(join(tmpdir(), "diff-review-cache-"));
+  dirs.push(repo);
+  mkdirSync(join(repo, "src"), { recursive: true });
+  // repo path only used for config/guidelines; no git needed when cachedDiff is set
+  const skeleton = extractBranchDiff({
+    repo,
+    branch: "feature",
+    base: "develop",
+    cachedDiff: sample,
+  });
+  assert.deepEqual(
+    skeleton.files.map((f) => f.path).sort(),
+    ["new.ts", "src/a.ts"]
+  );
+  assert.ok(skeleton.context.ignored.includes("package-lock.json"));
+  assert.match(skeleton.files.find((f) => f.path === "src/a.ts").diff, /^@@/);
+});
+
+test("checkReportFile reuses companion .diff paths without inventing coverage", () => {
+  const repo = mkdtempSync(join(tmpdir(), "diff-review-check-"));
+  dirs.push(repo);
+  ensureReviewDir(repo);
+  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
+  writeDiffText(repo, filename, sample);
+  const payload = {
+    meta: {
+      agent: "Cursor",
+      model: "composer",
+      repo,
+      branch: "feature",
+      base: "develop",
+    },
+    intent: "Cambia src/a.ts y renombra old.ts para dejar el módulo listo en la rama.",
+    groups: [{ id: "g1", kind: "feat", title: "Ajuste", intent: "base" }],
+    blocks: [
+      {
+        id: "b1",
+        group: "g1",
+        file: "src/a.ts",
+        lines: "L1-3",
+        op: "mod",
+        what: "cambia la lógica",
+        why: "hace falta",
+        source: "code",
+      },
+      {
+        id: "b2",
+        group: "g1",
+        file: "new.ts",
+        lines: "L1",
+        op: "rename",
+        what: "renombra el módulo",
+        why: "nombre más claro",
+        source: "code",
+      },
+    ],
+    findings: [],
+    skipped: [{ file: "package-lock.json", reason: "lockfile" }],
+  };
+  const jsonPath = companionPaths(repo, filename).json;
+  writeFileSync(jsonPath, JSON.stringify(payload));
+  // Sin git: loadBranchDiff lee el .diff y aplica ignore (lockfile fuera de paths).
+  const result = checkReportFile(jsonPath, { repo, branch: "feature", base: "develop" });
+  assert.equal(result.ok, true, result.errors.join("; "));
+});
+
+test("buildPrompt with precomputed context skips merge-base rediscovery", async () => {
+  const { buildPrompt } = await import("./prompt.mjs");
+  const text = buildPrompt(
+    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
+    {
+      outputFilename: "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json",
+      diffRelPath: ".diff-review/diff-rev_aaaaaaaaaa_bbbbbbbbbb.diff",
+      mergeBase: "abc123",
+      branchSha: "def456",
+      baseSha: "789abc",
+      files: [{ path: "src/a.ts", changeType: "modified" }],
+      ignored: ["package-lock.json"],
+      ignoreGlobs: ["**/package-lock.json"],
+    }
+  );
+  assert.match(text, /Precomputed git context/);
+  assert.match(text, /diff-rev_aaaaaaaaaa_bbbbbbbbbb\.diff/);
+  assert.match(text, /Merge-base SHA: `abc123`/);
+  assert.match(text, /modified: src\/a\.ts/);
+  assert.doesNotMatch(text, /Resolve the merge-base/);
+  assert.doesNotMatch(text, /Run exactly: `git diff/);
+});
+
+test("buildPrompt acp omits validate CLI", async () => {
+  const { buildPrompt, validateCliCommand } = await import("./prompt.mjs");
+  const filename = "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json";
+  const text = buildPrompt(
+    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
+    { outputFilename: filename, acp: true, diffRelPath: `.${OUTPUT_DIR}/${filename.replace(/\.json$/, ".diff")}` }
+  );
+  assert.doesNotMatch(text, new RegExp(validateCliCommand(filename).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  assert.match(text, /host validates/i);
+});

package/lib/git.mjs

@@ -49,12 +49,14 @@ export function tryResolveGitRoot(cwd) {
   }
 }
 
-export function git(repo, args, { maxBuffer = 64 * 1024 * 1024 } = {}) {
+export function git(repo, args, { maxBuffer = 64 * 1024 * 1024, quiet = false } = {}) {
   return execFileSync("git", args, {
     cwd: repo,
     encoding: "utf8",
     maxBuffer,
     windowsHide: true,
+    // Evita `fatal: …` en la terminal cuando el fallo es esperado (repo vacío, etc.).
+    ...(quiet ? { stdio: ["ignore", "pipe", "ignore"] } : {}),
   });
 }
 
@@ -136,13 +138,22 @@ export function showFileLines(repo, rev, path) {
 }
 
 export function listBranches(repo) {
-  const raw = git(repo, [
-    "for-each-ref",
-    "--sort=-committerdate",
-    "--format=%(refname:short)",
-    "refs/heads",
-    "refs/remotes",
-  ]);
+  let raw = "";
+  try {
+    raw = git(
+      repo,
+      [
+        "for-each-ref",
+        "--sort=-committerdate",
+        "--format=%(refname:short)",
+        "refs/heads",
+        "refs/remotes",
+      ],
+      { quiet: true },
+    );
+  } catch {
+    throw new Error(`No es un repositorio git usable: ${repo}`);
+  }
   const names = raw
     .split("\n")
     .map((s) => s.trim())
@@ -153,7 +164,12 @@ export function listBranches(repo) {
   // Dedup conservando el orden de for-each-ref (más reciente primero).
   const unique = [...new Set(names)];
 
-  const current = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+  let current;
+  try {
+    current = git(repo, ["rev-parse", "--abbrev-ref", "HEAD"], { quiet: true }).trim();
+  } catch {
+    throw new Error("El repositorio no tiene commits (falta HEAD).");
+  }
   const bases = unique.filter((n) => n === "develop" || n === "main" || n === "master");
   const defaultBase = bases.includes("develop")
     ? "develop"

package/lib/model-label.mjs

@@ -209,8 +209,22 @@ export function sortModelSelectOptions(options) {
   return [...defaults, ...autos, ...middle];
 }
 
+/** ¿ACP trajo un catálogo real (no solo default/auto)? */
+export function liveModelsHaveCatalog(models) {
+  return (Array.isArray(models) ? models : []).some((m) => {
+    const v = String(m?.value ?? "")
+      .trim()
+      .toLowerCase();
+    if (!v || v === "default" || v.startsWith("default[")) return false;
+    if (v === "auto" || v.startsWith("auto[")) return false;
+    return true;
+  });
+}
+
 /**
- * Misma lista que la UI: default + aliases fijos + modelos ACP.
+ * Lista para el select: default + modelos ACP.
+ * Los aliases fijos (`opus`/`sonnet`/`haiku`) solo se usan si ACP no trajo catálogo;
+ * si no, se ven repetidos (p. ej. `opus` + Opus 4.6 / 4.7 / 5).
  * Clack: `label` = título amigable, `hint` = `[ 300k, medium ]`.
  * UI: también `title` + `badges` para chips.
  *
@@ -220,9 +234,11 @@ export function sortModelSelectOptions(options) {
  */
 export function buildAcpModelSelectOptions(live, fixed) {
   const fixedOptions = fixed?.options ?? [];
-  const fallback = fixedOptions.filter((m) => m.value !== "");
+  const liveModels = Array.isArray(live?.models) ? live.models : [];
+  const useFixedAliases = !liveModelsHaveCatalog(liveModels);
+  const fallback = useFixedAliases ? fixedOptions.filter((m) => m.value !== "") : [];
   const configuredLabel = fixedOptions.find((m) => m.value === "")?.label;
-  const current = live.models.find((m) => m.value === live.currentModel);
+  const current = liveModels.find((m) => m.value === live.currentModel);
   const seen = new Set(["", "default"]);
   /** @type {{ value: string, label: string, hint?: string, title?: string, badges?: string[] }[]} */
   const options = [
@@ -246,7 +262,7 @@ export function buildAcpModelSelectOptions(live, fixed) {
     });
   }
 
-  for (const m of live.models) {
+  for (const m of liveModels) {
     if (seen.has(m.value)) continue;
     seen.add(m.value);
     const formatted = formatModelOption(m.name, m.value);

package/lib/model-label.test.mjs

@@ -42,7 +42,7 @@ test("formatModelOption compacto y amigable", () => {
   assert.deepEqual(c.badges, []);
 });
 
-test("buildAcpModelSelectOptions fusiona aliases y formatea ACP", () => {
+test("buildAcpModelSelectOptions usa catálogo ACP y omite aliases fijos", () => {
   const { options } = buildAcpModelSelectOptions(
     {
       currentModel: "default",
@@ -62,13 +62,26 @@ test("buildAcpModelSelectOptions fusiona aliases y formatea ACP", () => {
     }
   );
   assert.equal(options[0].label, "Por defecto (opus)");
-  assert.ok(options.some((o) => o.value === "opus"));
+  assert.ok(!options.some((o) => o.value === "opus"));
   const opusAcp = options.find((o) => o.value.startsWith("claude-opus-5-5"));
   assert.equal(opusAcp?.title, "Claude Opus 5.5");
   assert.deepEqual(opusAcp?.badges, ["300k", "medium"]);
   assert.equal(opusAcp?.hint, "[ 300k, medium ]");
 });
 
+test("buildAcpModelSelectOptions cae a aliases si ACP no trae catálogo", () => {
+  const { options } = buildAcpModelSelectOptions(
+    { currentModel: "default", models: [{ value: "default", name: "Default" }] },
+    {
+      options: [
+        { value: "", label: "Por defecto del agente" },
+        { value: "opus", label: "opus", hint: "el más capaz" },
+      ],
+    }
+  );
+  assert.ok(options.some((o) => o.value === "opus"));
+});
+
 test("modelOptionLabel compat", () => {
   assert.equal(
     modelOptionLabel("grok-4.7", "grok-4.7[context=256k,fast=true]"),

package/lib/prompt.mjs

@@ -35,7 +35,7 @@ export const OUTPUT_SCHEMA_BLOCK = `{
       "id": "t1",
       "kind": "feat|fix|refactor|perf|test|chore|docs|infra",
       "title": "string, aim for ≤72 chars, imperative, no kind prefix",
-      "intent": "string"
+      "intent": "string: why this theme exists + what it changes for the reader (not a restatement of the title)"
     }
   ],
   "blocks": [
@@ -48,8 +48,8 @@ export const OUTPUT_SCHEMA_BLOCK = `{
       "start": 40,
       "end": 58,
       "op": "add|mod|del|rename",
-      "what": "string, aim for ≤120 chars: concrete change + effect",
-      "why": "string, aim for ≤120 chars",
+      "what": "string: concrete change + effect (aim ≤120 chars; longer OK if needed for clarity)",
+      "why": "string: motivation / why this change belongs in the branch (aim ≤120 chars)",
       "source": "code|commit|pr|issue|inferred"
     }
   ],
@@ -63,8 +63,8 @@ export const OUTPUT_SCHEMA_BLOCK = `{
       "file": "relative/path.ext",
       "line": 87,
       "block": "b1",
-      "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"
+      "what": "string: cause + why it is a problem + observable consequence (aim ≤120 chars; prefer clarity over brevity)",
+      "fix": "string: suggested change + why that change resolves the problem / what it avoids (aim ≤120 chars)"
     }
   ],
   "skipped": [
@@ -79,13 +79,15 @@ const RULES = `- Ids: themes use \`t1\`, \`t2\`, …; findings use \`f1\`, \`f2\
 - 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.
+- Theme "intent": explain why the theme exists and what it changes for the reader — not a paraphrase of "title". One short sentence is too little; aim for 1–3 sentences with cause and scope.
+- Top-level "intent": 2–4 sentences on what the branch solves and why it matters.
+- Finding "what": cover (1) the concrete cause in the diff, (2) why it is a problem (failure mode, risk, or cost), and (3) the observable consequence. Do not stop at a symptom label.
+- Finding "fix": cover (1) the suggested change and (2) why that change resolves the problem / what the reader gains or avoids. Vague advice ("mejorar el manejo") is not enough.
 - 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.
+- Parallelize: when several read-only lookups are independent (Read, Grep/search, Glob, etc.), issue them in the same turn if your tools allow parallel calls. Do not serialize independent work — finish faster by batching.
 - 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 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.
+- Length is a soft target, not a check: aim for title ≤72 characters and what/why/fix ≤120 characters when possible. Prefer clarity over shortening — thin one-liners that omit cause, impact, or why-the-fix-works are worse than a slightly longer explanation. Longer text is still valid. Do not rewrite the file only to shorten it.
 - If the output JSON already exists and findings have \`resolution\` ({ kind: ignored|fix|corrected, detail?: string }), preserve those fields on rewrite (coverage / edit / regenerate). Keep existing finding ids when possible; do not drop or reshuffle resolutions.`;
 
 /** @param {{ hasDiff?: boolean }} [ctx] */
@@ -315,7 +317,7 @@ Write the result to \`${outputPath}\` (relative to the repo root; use forward sl
 
 ${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).
+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, Copilot, …) 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 loads the companion \`.diff\` (or computes with git if missing) when opening the report. Do not invent hunks or paste patches into the JSON. If you are rewriting an existing review JSON, copy through any per-finding \`resolution\` already present.
 

package/lib/prompt.test.mjs

@@ -35,3 +35,15 @@ test("buildPrompt tells agent to preserve finding resolution on rewrite", () =>
   assert.match(text, /resolution/);
   assert.match(text, /copy through any per-finding `resolution`/i);
 });
+
+test("buildPrompt asks for richer theme/finding explanations and parallel work", () => {
+  const text = buildPrompt(
+    { source: "local", repo: "/tmp/r", branch: "feat", base: "develop" },
+    { outputFilename: "diff-rev_aaaaaaaaaa_bbbbbbbbbb.json" }
+  );
+  assert.match(text, /Theme "intent"/i);
+  assert.match(text, /why it is a problem/i);
+  assert.match(text, /why that change resolves the problem/i);
+  assert.match(text, /Parallelize/i);
+  assert.match(text, /same turn/i);
+});

package/lib/review-meta.mjs

@@ -7,12 +7,15 @@ 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, agentSession?: { agentId: string, sessionId: string, outputFilename: string } }} provenance
+ * `modelLabel` = nombre legible que el agente da al modelo ("Haiku 5.5"): `model` puede ser un alias
+ * (`haiku`) que más adelante apunte a otra versión.
+ * @param {{ agent?: string, model?: string, modelLabel?: string, agentSession?: { agentId: string, sessionId: string, outputFilename: string } }} provenance
  * @returns {boolean}
  */
-export function stampReviewProvenance(filePath, { agent, model, agentSession } = {}) {
+export function stampReviewProvenance(filePath, { agent, model, modelLabel, agentSession } = {}) {
   const agentName = String(agent || "").trim();
   const modelId = String(model || "").trim();
+  const label = String(modelLabel || "").trim();
   if (!agentName && !modelId && !agentSession) return false;
 
   let payload;
@@ -27,7 +30,12 @@ export function stampReviewProvenance(filePath, { agent, model, agentSession } =
   const meta =
     current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
   if (agentName) meta.agent = agentName;
-  if (modelId) meta.model = modelId;
+  if (modelId) {
+    meta.model = modelId;
+    // Un label viejo describiría otro modelo: se reemplaza o se borra junto con `model`.
+    if (label && label !== modelId) meta.modelLabel = label;
+    else delete meta.modelLabel;
+  }
   if (agentSession) meta.agentSession = { ...agentSession };
   payload.meta = meta;
   writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");

package/lib/review-meta.test.mjs

@@ -22,10 +22,10 @@ test("stampReviewProvenance no pisa el modelo si no hay uno", () => {
   const file = join(dir, "diff-rev_a_b.json");
   writeFileSync(file, JSON.stringify({ meta: { model: "sonnet" }, intent: "x" }));
 
-  stampReviewProvenance(file, { agent: "Codex" });
+  stampReviewProvenance(file, { agent: "Cursor" });
 
   const saved = JSON.parse(readFileSync(file, "utf8"));
-  assert.equal(saved.meta.agent, "Codex");
+  assert.equal(saved.meta.agent, "Cursor");
   assert.equal(saved.meta.model, "sonnet");
 });
 
@@ -39,3 +39,20 @@ test("stampReviewProvenance guarda la sesión del agente", () => {
 
   assert.deepEqual(JSON.parse(readFileSync(file, "utf8")).meta.agentSession, agentSession);
 });
+
+test("stampReviewProvenance guarda el nombre con versión junto al alias", () => {
+  const dir = mkdtempSync(join(tmpdir(), "diff-review-meta-"));
+  const file = join(dir, "diff-rev_a_b.json");
+  writeFileSync(file, JSON.stringify({ meta: { model: "claude-haiku-5-5" }, intent: "x" }));
+
+  stampReviewProvenance(file, { agent: "Claude Code", model: "haiku", modelLabel: "Haiku 5.5" });
+  let meta = JSON.parse(readFileSync(file, "utf8")).meta;
+  assert.equal(meta.model, "haiku");
+  assert.equal(meta.modelLabel, "Haiku 5.5");
+
+  // Otro modelo sin nombre conocido: el label anterior ya no corresponde.
+  stampReviewProvenance(file, { model: "claude-opus-5" });
+  meta = JSON.parse(readFileSync(file, "utf8")).meta;
+  assert.equal(meta.model, "claude-opus-5");
+  assert.equal(meta.modelLabel, undefined);
+});