@jphutchins/code-review 0.1.0-alpha.5 → 0.1.0-alpha.6

package/README.md

@@ -42,6 +42,7 @@ npx @jphutchins/code-review <subcommand>
 | `inline` | Build the GitHub reviews `comments[]` payload from findings + diff (in-diff validation; strays demote to the summary) |
 | `adapt` | Map a native agent-CLI result envelope onto the abstract SPEC §6.1 envelope |
 | `extract` | Recover findings/triage JSON from a native envelope via the deterministic extraction ladder |
+| `lower-suggestions` | Validate each finding's `patch` against the real PR-head file and lower it to an exact `suggestion` + line range, or drop it |
 | `cost` | Recompute USD cost from the envelope's per-model token counts + a price map |
 | `validate` | Validate findings JSON against the published schema |
 | `print-schema` | Print a bundled schema (findings, triage, prices) |
@@ -75,6 +76,23 @@ endpoint is a per-repo **Actions variable** (`API_BASE_URL`, required, no defaul
 another provider requires adding that provider's API host to the workflow's egress allowlist in the
 same reviewed PR.
 
+## Artifacts
+
+The review job uploads two artifacts, each visible from the workflow run the sticky's disclosure
+links to:
+
+- **`code-review-findings`** — the findings JSON + result envelope the comment job renders. The
+  sticky comment embeds this same JSON directly, base64-encoded, in an
+  `<!-- code-review:findings-json;base64 <base64> -->` HTML comment — a reviewing agent (or any
+  downstream tool) SHOULD base64-decode and parse that marker rather than parse the comment's prose.
+  Embedding in the comment (rather than only linking the artifact) keeps the pointer from expiring
+  with artifact retention; when the encoded findings are too large to embed, the sticky falls back to
+  a `<!-- code-review:findings-json <url> -->` link marker instead
+  ([SPEC §5.1 item 7](SPEC.md#51-sticky-summary-comment)).
+- **`code-review-transcript`** — the full Claude Code session transcripts for the triage and review
+  phases. This is advisory/auditability only: it is never read by the comment job and never affects
+  what gets posted.
+
 ## What's here
 
 - **[SPEC.md](SPEC.md)** — the normative, provider-agnostic specification.

package/dist/index.js

@@ -73,6 +73,7 @@ var computeSeverityCounts = (findings) => findings.reduce(
   (acc, f) => f.severity in acc ? { ...acc, [f.severity]: acc[f.severity] + 1 } : acc,
   emptySeverityCounts()
 );
+var EMBED_LIMIT = 4e4;
 var render = (input) => {
   const eta = new Eta({ autoTrim: false });
   const usageAvailable = input.envelope !== null;
@@ -80,6 +81,8 @@ var render = (input) => {
   const route = input.route ?? input.envelope?.route ?? null;
   const effort = input.effort ?? input.envelope?.effort ?? null;
   const modelNames = input.envelope ? input.envelope.models.map((m) => m.model).join(", ") : "";
+  const findingsB64 = Buffer.from(JSON.stringify(input.findings), "utf-8").toString("base64");
+  const embeddedFindings = findingsB64.length <= EMBED_LIMIT ? findingsB64 : null;
   return eta.renderString(input.template, {
     findings: input.findings,
     envelope: input.envelope,
@@ -93,8 +96,12 @@ var render = (input) => {
     severityCounts: input.severityCounts ?? computeSeverityCounts(input.findings.findings),
     strays: (input.strays ?? []).map(sanitizeFinding),
     inlineDisposition: input.inlineDisposition ?? null,
+    runUrl: input.runUrl ?? null,
+    jsonUrl: input.jsonUrl ?? null,
+    embeddedFindings,
+    reviewUrl: input.reviewUrl ?? null,
     formatTokens: (n) => Number.isFinite(n) && n >= 0 ? n.toLocaleString("en-US") : "\u2014",
-    formatCost: (n) => Number.isFinite(n) ? `$${n.toFixed(3)}` : "\u2014",
+    formatCost: (n) => Number.isFinite(n) ? n > 0 && n.toFixed(2) === "0.00" ? "<$0.01" : `$${n.toFixed(2)}` : "\u2014",
     formatDuration: (ms) => {
       if (!Number.isFinite(ms) || ms < 0) return "\u2014";
       const s = Math.round(ms / 1e3);
@@ -183,8 +190,26 @@ var partitionFindings = (findings, index) => {
 
 // src/inline.ts
 var escapeBackticks2 = (text) => text.replace(/```/g, "`` ` ``");
-var buildCommentBody = (f) => {
-  const parts = [f.body];
+var severityEmoji = (s) => {
+  switch (s) {
+    case "critical":
+      return "\u{1F534}";
+    case "major":
+      return "\u{1F7E0}";
+    case "minor":
+      return "\u{1F535}";
+    case "nit":
+      return "\u26AA";
+    default:
+      return "\u2753";
+  }
+};
+var severityHeader = (f) => `${severityEmoji(f.severity)} **${f.severity}** \u2014 ${f.title}`;
+var jsonUrlMarker = (jsonUrl) => jsonUrl ? `<!-- code-review:findings-json ${jsonUrl} -->` : void 0;
+var formatModels = (models) => models.length > 0 ? models.map((m) => `\`${m}\``).join("/") : "an AI model";
+var buildCommentBody = (f, jsonUrl) => {
+  const marker = jsonUrlMarker(jsonUrl);
+  const parts = [...marker ? [marker] : [], severityHeader(f), f.body];
   if (f.suggestion !== null && f.suggestion !== void 0) {
     const safe = escapeBackticks2(f.suggestion);
     parts.push(`\`\`\`suggestion
@@ -193,22 +218,27 @@ ${safe}
   }
   return parts.join("\n\n");
 };
-var renderCommentBody = (f, eta, template) => {
+var renderCommentBody = (f, eta, template, modelsText, jsonUrl) => {
   return eta.renderString(template, {
     ...f,
-    suggestion: f.suggestion !== null && f.suggestion !== void 0 ? escapeBackticks2(f.suggestion) : null
+    suggestion: f.suggestion !== null && f.suggestion !== void 0 ? escapeBackticks2(f.suggestion) : null,
+    severityEmoji,
+    modelsText,
+    jsonUrl: jsonUrl ?? null
   });
 };
-var buildInlineComments = (findings, diff, inlineTemplate) => {
+var buildInlineComments = (findings, diff, context = {}) => {
+  const { inlineTemplate, models = [], jsonUrl } = context;
   const index = indexDiff(diff);
   const { inDiff, strays } = partitionFindings(findings, index);
   const eta = inlineTemplate ? new Eta({ autoTrim: false }) : null;
+  const modelsText = formatModels(models);
   const comments = inDiff.map((f) => {
     const comment = {
       path: f.path,
       line: f.end_line,
       side: defaultSide(f.side),
-      body: eta && inlineTemplate ? renderCommentBody(f, eta, inlineTemplate) : buildCommentBody(f)
+      body: eta && inlineTemplate ? renderCommentBody(f, eta, inlineTemplate, modelsText, jsonUrl) : buildCommentBody(f, jsonUrl)
     };
     if (f.start_line < f.end_line) {
       return {
@@ -269,7 +299,9 @@ var FindingShape = t.intersection([
     suggestion: t.union([t.string, t.null]),
     confidence: Confidence,
     code: t.string,
-    code_url: t.string
+    code_url: t.string,
+    reasoning: t.string,
+    patch: t.string
   })
 ]);
 var EndGeStart = t.refinement(
@@ -345,7 +377,7 @@ var TestSummaryCodec = t.intersection([
     failures: t.array(TestFailureCodec)
   })
 ]);
-var DEFAULT_SCHEMA_VERSION = "0.2.0";
+var DEFAULT_SCHEMA_VERSION = "0.3.0";
 
 // src/validate.ts
 var addFormats = _addFormats;
@@ -381,15 +413,45 @@ var unsafeUnwrap = (decoded) => {
   if (decoded._tag === "Right") return decoded.right;
   throw new Error("io-ts decode failed \u2014 data does not match expected shape");
 };
+
+// src/format.ts
+var FENCE_RE = /^\s*```/;
+var scanLine = (state, line) => {
+  if (FENCE_RE.test(line)) {
+    return { lines: [...state.lines, line], inFence: !state.inFence, blankRun: 0 };
+  }
+  if (state.inFence) {
+    return { lines: [...state.lines, line], inFence: true, blankRun: 0 };
+  }
+  const trimmed = line.replace(/[ \t]+$/, "");
+  if (trimmed !== "") {
+    return { lines: [...state.lines, trimmed], inFence: false, blankRun: 0 };
+  }
+  const blankRun = state.blankRun + 1;
+  return blankRun === 1 ? { lines: [...state.lines, ""], inFence: false, blankRun } : { ...state, blankRun };
+};
+var formatMarkdown = (md) => {
+  const { lines } = md.split("\n").reduce(scanLine, { lines: [], inFence: false, blankRun: 0 });
+  return `${lines.join("\n").replace(/\n+$/, "")}
+`;
+};
 var identity = (decoded) => decoded;
 var findingsTable = [
   {
-    minor: "0.2",
+    minor: "0.3",
     defaultVersion: DEFAULT_SCHEMA_VERSION,
     schemaFile: "findings.schema.json",
     codec: FindingsCodec,
     normalize: identity,
     latest: true
+  },
+  {
+    minor: "0.2",
+    defaultVersion: "0.2.0",
+    schemaFile: "v0.2/findings.schema.json",
+    codec: FindingsCodec,
+    normalize: identity,
+    latest: false
   }
 ];
 var triageTable = [
@@ -595,9 +657,19 @@ var loadTestReport = (path) => {
   }
   return decoded.right;
 };
-var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
+var parseHtmlUrl = (raw) => {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.html_url === "string" ? parsed.html_url : void 0;
+  } catch {
+    return void 0;
+  }
+};
+var postInlineReview = async (repo, prNumber, headSha, comments, stickyUrl, ghApi) => {
+  const sha7 = headSha.slice(0, 7);
+  const pointer = stickyUrl ? `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the [summary comment](${stickyUrl}) for the verdict, walkthrough, and cost.` : `\u{1F916} Automated code review for \`${sha7}\` \u2014 see the summary comment for the verdict, walkthrough, and cost.`;
   const body = JSON.stringify({
-    body: `\u{1F916} Automated code review for \`${headSha.slice(0, 7)}\` \u2014 verdict, walkthrough, and cost are in the summary comment.`,
+    body: pointer,
     commit_id: headSha,
     event: "COMMENT",
     comments: comments.map((c) => ({
@@ -605,10 +677,14 @@ var postInlineReview = async (repo, prNumber, headSha, comments, ghApi) => {
       line: c.line,
       side: c.side,
       ...c.start_line !== void 0 && c.start_side !== void 0 ? { start_line: c.start_line, start_side: c.start_side } : {},
-      body: c.body
+      body: formatMarkdown(c.body)
     }))
   });
-  await ghApi([`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"], body);
+  const stdout = await ghApi(
+    [`repos/${repo}/pulls/${String(prNumber)}/reviews`, "--input", "-"],
+    body
+  );
+  return parseHtmlUrl(stdout);
 };
 var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const stdout = await ghApi(
@@ -628,30 +704,42 @@ var findBotComment = async (repo, prNumber, botLogin, marker, ghApi) => {
   const parsed = JSON.parse(last);
   return { id: parsed.id, body: parsed.body };
 };
+var parseCommentRef = (raw) => {
+  try {
+    const parsed = JSON.parse(raw);
+    return typeof parsed.id === "number" && typeof parsed.html_url === "string" ? { id: parsed.id, html_url: parsed.html_url } : null;
+  } catch {
+    return null;
+  }
+};
 var patchComment = async (repo, commentId, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/comments/${String(commentId)}`, "--input", "-"],
     JSON.stringify({ body })
   );
+  const htmlUrl = parseHtmlUrl(stdout);
+  return htmlUrl !== void 0 ? { html_url: htmlUrl } : null;
 };
 var postComment = async (repo, prNumber, body, ghApi) => {
-  await ghApi(
+  const stdout = await ghApi(
     [`repos/${repo}/issues/${String(prNumber)}/comments`, "--input", "-"],
     JSON.stringify({ body })
   );
+  return parseCommentRef(stdout);
 };
 var upsertSticky = async (repo, prNumber, existing, body, ghApi) => {
   if (existing !== null) {
-    await patchComment(repo, existing.id, body, ghApi);
+    const patched = await patchComment(repo, existing.id, body, ghApi);
     process.stderr.write(
       `Updated sticky comment #${String(existing.id)} on PR #${String(prNumber)}
 `
     );
-  } else {
-    await postComment(repo, prNumber, body, ghApi);
-    process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
-`);
+    return { id: existing.id, url: patched?.html_url };
   }
+  const posted = await postComment(repo, prNumber, body, ghApi);
+  process.stderr.write(`Posted new sticky comment on PR #${String(prNumber)}
+`);
+  return posted ? { id: posted.id, url: posted.html_url } : null;
 };
 var isBotReview = (r) => typeof r === "object" && r !== null && typeof r.id === "number" && typeof r.state === "string" && typeof r.user?.login === "string";
 var fetchBotReviews = async (repo, prNumber, botLogin, ghApi) => {
@@ -720,15 +808,19 @@ var post = async (input, ghApi = runGhApi) => {
   }
   const template = readFileSync(input.templatePath, "utf-8");
   const inlineTemplate = input.inlineTemplatePath ? readFileSync(input.inlineTemplatePath, "utf-8") : void 0;
-  const renderNotice = (message) => render({
-    findings: noticeFindings(message),
-    envelope: null,
-    prices: decodedPrices.right,
-    template,
-    route: input.route,
-    reviewedSha: input.headSha,
-    effort: input.effort
-  });
+  const renderNotice = (message) => formatMarkdown(
+    render({
+      findings: noticeFindings(message),
+      envelope: null,
+      prices: decodedPrices.right,
+      template,
+      route: input.route,
+      reviewedSha: input.headSha,
+      effort: input.effort,
+      runUrl: input.runUrl,
+      jsonUrl: input.jsonUrl
+    })
+  );
   if (isEmptyDiff(diff)) {
     await upsertSticky(
       input.repo,
@@ -754,28 +846,32 @@ var post = async (input, ghApi = runGhApi) => {
   const envelope = loadEnvelope(input.envelopePath);
   const testReport = input.testReportPath ? loadTestReport(input.testReportPath) : void 0;
   if (envelope === null) {
-    const body2 = render({
-      findings,
-      envelope: null,
-      prices: decodedPrices.right,
-      template,
-      route: input.route,
-      reviewedSha: input.headSha,
-      effort: input.effort,
-      testReport,
-      inlineDisposition: { kind: "no-envelope" }
-    });
-    await upsertSticky(input.repo, prNumber, existingSticky, body2, ghApi);
+    const body = formatMarkdown(
+      render({
+        findings,
+        envelope: null,
+        prices: decodedPrices.right,
+        template,
+        route: input.route,
+        reviewedSha: input.headSha,
+        effort: input.effort,
+        testReport,
+        inlineDisposition: { kind: "no-envelope" },
+        runUrl: input.runUrl,
+        jsonUrl: input.jsonUrl
+      })
+    );
+    await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
     process.stderr.write(
       "Result envelope missing or malformed \u2014 posted sticky summary without usage/cost data; no inline review\n"
     );
     process.exit(0);
   }
-  const { comments: rawComments, strays } = buildInlineComments(
-    findings.findings,
-    diff,
-    inlineTemplate
-  );
+  const { comments: rawComments, strays } = buildInlineComments(findings.findings, diff, {
+    inlineTemplate,
+    models: envelope.models.map((m) => m.model),
+    jsonUrl: input.jsonUrl
+  });
   const { comments, longFiles } = checkLongSuggestions(rawComments);
   for (const wf of longFiles) {
     process.stderr.write(
@@ -786,7 +882,7 @@ var post = async (input, ghApi = runGhApi) => {
   const botReviews = comments.length > 0 ? await fetchBotReviews(input.repo, prNumber, input.botLogin, ghApi) : [];
   const alreadyReviewedThisSha = botReviews.some((r) => r.commitId === input.headSha);
   const inlineDisposition = comments.length > 0 ? alreadyReviewedThisSha ? { kind: "suppressed-existing-review", sha: input.headSha } : { kind: "posted", count: comments.length, sha: input.headSha } : strays.length > 0 ? { kind: "none-in-diff" } : void 0;
-  const body = render({
+  const commonRenderInput = {
     findings,
     envelope,
     prices: decodedPrices.right,
@@ -797,14 +893,18 @@ var post = async (input, ghApi = runGhApi) => {
     testReport,
     severityCounts: computeSeverityCounts(findings.findings),
     strays,
-    inlineDisposition
-  }) + (longFiles.length > 0 ? `
+    inlineDisposition,
+    runUrl: input.runUrl,
+    jsonUrl: input.jsonUrl
+  };
+  const longFilesNote = longFiles.length > 0 ? `
 
 ---
 
 > **Note:** ${String(longFiles.length)} suggestion(s) exceeded GitHub's ~10-line inline suggestion limit and were omitted from the inline comments; the affected findings remain in the review.
-` : "");
-  await upsertSticky(input.repo, prNumber, existingSticky, body, ghApi);
+` : "";
+  const renderBody = (reviewUrl2) => formatMarkdown(render({ ...commonRenderInput, reviewUrl: reviewUrl2 }) + longFilesNote);
+  const stickyRef = await upsertSticky(input.repo, prNumber, existingSticky, renderBody(), ghApi);
   if (comments.length === 0) return;
   if (alreadyReviewedThisSha) {
     process.stderr.write(
@@ -817,11 +917,30 @@ var post = async (input, ghApi = runGhApi) => {
   if (stalePriorReviewIds.length > 0) {
     await dismissReviews(input.repo, prNumber, stalePriorReviewIds, ghApi);
   }
-  await postInlineReview(input.repo, prNumber, input.headSha, comments, ghApi);
+  const reviewUrl = await postInlineReview(
+    input.repo,
+    prNumber,
+    input.headSha,
+    comments,
+    stickyRef?.url,
+    ghApi
+  );
   process.stderr.write(
     `Posted ${String(comments.length)} inline comments on PR #${String(prNumber)}
 `
   );
+  if (stickyRef !== null && reviewUrl !== void 0) {
+    try {
+      await patchComment(input.repo, stickyRef.id, renderBody(reviewUrl), ghApi);
+      process.stderr.write(`Linked sticky comment #${String(stickyRef.id)} to the review
+`);
+    } catch (err) {
+      process.stderr.write(
+        `Warning: failed to link the sticky summary to the review: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+    }
+  }
 };
 var renderOutputs = (result) => {
   switch (result.kind) {
@@ -1032,7 +1151,7 @@ var candidateFromJsonText = (kind, text) => {
 };
 var FENCE_OPEN = /^\s*(`{3,})/;
 var FENCE_MARKER_ONLY = /^`+$/;
-var scanLine = (state, line) => {
+var scanLine2 = (state, line) => {
   if (state.openLength === null) {
     const opened = FENCE_OPEN.exec(line)?.[1]?.length;
     return opened !== void 0 ? { blocks: state.blocks, openLength: opened, buffer: [] } : state;
@@ -1041,7 +1160,7 @@ var scanLine = (state, line) => {
   const closes = FENCE_MARKER_ONLY.test(trimmed) && trimmed.length >= state.openLength;
   return closes ? { blocks: [...state.blocks, state.buffer.join("\n")], openLength: null, buffer: [] } : { ...state, buffer: [...state.buffer, line] };
 };
-var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine, { blocks: [], openLength: null, buffer: [] }).blocks;
+var scanFencedBlocks = (text) => text.split("\n").reduce(scanLine2, { blocks: [], openLength: null, buffer: [] }).blocks;
 var ladderFailureDiagnostics = (input) => {
   const native = parseNativeForExtraction(input.native);
   const preview = (s) => {
@@ -1176,6 +1295,83 @@ var adapt = (adapterName, native, agentFilePath, meta = {}) => {
   }
 };
 
+// src/patch.ts
+var HUNK_HEADER_RE = /^@@ -(\d+)(?:,\d+)? \+\d+(?:,\d+)? @@/;
+var hunkOldStart = (line) => {
+  const raw = HUNK_HEADER_RE.exec(line)?.[1];
+  return raw !== void 0 ? Number(raw) : null;
+};
+var classifyBodyLine = (line) => {
+  if (line.startsWith(" ")) return { kind: "context", text: line.slice(1) };
+  if (line.startsWith("-")) return { kind: "removed", text: line.slice(1) };
+  if (line.startsWith("+")) return { kind: "added", text: line.slice(1) };
+  return null;
+};
+var trimmedMiddle = (body) => {
+  const first = body.findIndex((l) => l.kind !== "context");
+  if (first === -1) return [];
+  const last = body.findLastIndex((l) => l.kind !== "context");
+  return body.slice(first, last + 1);
+};
+var isContiguousChange = (middle) => {
+  if (middle.some((l) => l.kind === "context")) return false;
+  const firstAdded = middle.findIndex((l) => l.kind === "added");
+  if (firstAdded === -1) return true;
+  return middle.slice(0, firstAdded).every((l) => l.kind === "removed") && middle.slice(firstAdded).every((l) => l.kind === "added");
+};
+var removedRange = (body, oldStart) => body.reduce(
+  (acc, line) => line.kind === "added" ? acc : {
+    lineNumber: acc.lineNumber + 1,
+    firstRemoved: line.kind === "removed" && acc.firstRemoved === null ? acc.lineNumber : acc.firstRemoved,
+    lastRemoved: line.kind === "removed" ? acc.lineNumber : acc.lastRemoved
+  },
+  { lineNumber: oldStart, firstRemoved: null, lastRemoved: null }
+);
+var drop = (reason) => ({ kind: "drop", reason });
+var lowerPatch = (patch, fileLines) => {
+  const rawLines = patch.split("\n");
+  const lines = rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  const headerHits = lines.reduce(
+    (acc, line, index) => {
+      const oldStart = hunkOldStart(line);
+      return oldStart !== null ? [...acc, { index, oldStart }] : acc;
+    },
+    []
+  );
+  if (headerHits.length !== 1) {
+    return drop(`expected exactly one hunk, got ${String(headerHits.length)}`);
+  }
+  const hit = headerHits[0];
+  if (hit === void 0) return drop("malformed hunk header");
+  const bodyRaw = lines.slice(hit.index + 1).filter((line) => !line.startsWith("\\"));
+  const classified = bodyRaw.map(classifyBodyLine);
+  if (classified.some((line) => line === null)) return drop("malformed hunk body line");
+  const body = classified.filter((line) => line !== null);
+  const oldSideTexts = body.filter((l) => l.kind !== "added").map((l) => l.text);
+  const expected = fileLines.slice(hit.oldStart - 1, hit.oldStart - 1 + oldSideTexts.length);
+  const oldSideMatches = expected.length === oldSideTexts.length && expected.every((line, i) => line === oldSideTexts[i]);
+  if (!oldSideMatches) {
+    return drop(
+      `patch context does not match the file at lines ${String(hit.oldStart)}..${String(hit.oldStart + oldSideTexts.length - 1)}`
+    );
+  }
+  if (!isContiguousChange(trimmedMiddle(body))) {
+    return drop("change is not a single contiguous block");
+  }
+  const removedCount = body.filter((l) => l.kind === "removed").length;
+  const addedLines = body.filter((l) => l.kind === "added");
+  if (removedCount === 0 && addedLines.length === 0) return drop("hunk contains no changes");
+  if (removedCount === 0) return drop("pure insertion can't be expressed as a suggestion");
+  const { firstRemoved, lastRemoved } = removedRange(body, hit.oldStart);
+  if (firstRemoved === null || lastRemoved === null) return drop("malformed hunk body");
+  return {
+    kind: "ok",
+    startLine: firstRemoved,
+    endLine: lastRemoved,
+    suggestion: addedLines.map((l) => l.text).join("\n")
+  };
+};
+
 // src/index.ts
 var readJSON = (path) => {
   try {
@@ -1305,7 +1501,7 @@ var inlineCmd = defineCommand({
     const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
     const diff = readFileSync(resolve$1(args.diff), "utf-8");
     const inlineTemplate = args.template ? readFileSync(resolve$1(args.template), "utf-8") : void 0;
-    const { comments, strays } = buildInlineComments(findings.findings, diff, inlineTemplate);
+    const { comments, strays } = buildInlineComments(findings.findings, diff, { inlineTemplate });
     process.stdout.write(
       JSON.stringify({ comments, strays, stray_markdown: renderStraysSection(strays) }, null, 2)
     );
@@ -1475,6 +1671,72 @@ ${ladderFailureDiagnostics(input)}
     fail(describeLadderFailure(outcome));
   }
 });
+var withoutPatch = (finding) => {
+  const copy = { ...finding };
+  delete copy.patch;
+  return copy;
+};
+var readFileLines = (path) => {
+  try {
+    const rawLines = readFileSync(path, "utf-8").split("\n");
+    return rawLines.length > 0 && rawLines[rawLines.length - 1] === "" ? rawLines.slice(0, -1) : rawLines;
+  } catch {
+    return null;
+  }
+};
+var lowerFinding = (finding, repoRoot) => {
+  if (finding.patch === void 0) return finding;
+  const base = withoutPatch(finding);
+  const lines = readFileLines(resolve$1(repoRoot, finding.path));
+  if (lines === null) {
+    process.stderr.write(
+      `lower-suggestions: ${finding.path}: could not read file at "${repoRoot}" \u2014 dropping patch
+`
+    );
+    return base;
+  }
+  const result = lowerPatch(finding.patch, lines);
+  if (result.kind === "drop") {
+    process.stderr.write(
+      `lower-suggestions: ${finding.path}:${String(finding.start_line)}: ${result.reason} \u2014 dropping patch
+`
+    );
+    return base;
+  }
+  return {
+    ...base,
+    suggestion: result.suggestion,
+    start_line: result.startLine,
+    end_line: result.endLine
+  };
+};
+var lowerSuggestionsCmd = defineCommand({
+  meta: {
+    name: "lower-suggestions",
+    description: "Validate each finding's patch against the real PR-head tree and lower it to an exact suggestion + range, or drop it (issue #10)"
+  },
+  args: {
+    findings: {
+      type: "positional",
+      description: "Path to findings JSON",
+      required: true
+    },
+    "repo-root": {
+      type: "string",
+      description: "Directory to resolve each finding's path against \u2014 the review job's checked-out, clean PR-head tree (default: .)"
+    }
+  },
+  run: async ({ args }) => {
+    const findings = decode(FindingsCodec.decode(readJSON(args.findings)), "findings");
+    const repoRoot = args["repo-root"] ? resolve$1(args["repo-root"]) : process.cwd();
+    const lowered = {
+      ...findings,
+      findings: findings.findings.map((f) => lowerFinding(f, repoRoot))
+    };
+    process.stdout.write(`${JSON.stringify(lowered, null, 2)}
+`);
+  }
+});
 var requireAdapterName = (name) => {
   if (isAdapterName(name)) return name;
   fail(`Unknown adapter "${name}" \u2014 supported: claude-code`);
@@ -1626,6 +1888,14 @@ var postCmd = defineCommand({
     "test-report": {
       type: "string",
       description: TEST_REPORT_DESCRIPTION
+    },
+    "run-url": {
+      type: "string",
+      description: "Workflow run URL (transcript/traces), rendered as a link in the LLM Disclosure aside"
+    },
+    "json-url": {
+      type: "string",
+      description: "URL to the machine-readable findings JSON artifact, pointed at from the sticky and each inline comment"
     }
   },
   run: async ({ args }) => {
@@ -1641,7 +1911,9 @@ var postCmd = defineCommand({
       route: args.route,
       headBranch: args["head-branch"],
       effort: args.effort,
-      testReportPath: args["test-report"]
+      testReportPath: args["test-report"],
+      runUrl: args["run-url"],
+      jsonUrl: args["json-url"]
     });
   }
 });
@@ -1649,7 +1921,7 @@ var main = defineCommand({
   meta: {
     name: "code-review",
     version: packageVersion,
-    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, cost, and validate findings JSON"
+    description: "Deterministic commenter for agentic PR review \u2014 gather, render, inline, post, adapt, extract, lower-suggestions, cost, and validate findings JSON"
   },
   subCommands: {
     gather: gatherCmd,
@@ -1660,6 +1932,7 @@ var main = defineCommand({
     validate: validateCmd,
     adapt: adaptCmd,
     extract: extractCmd,
+    "lower-suggestions": lowerSuggestionsCmd,
     "print-schema": printSchemaCmd
   }
 });