pi-workflow-engine 0.13.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/review/github-pr-comments.ts

@@ -1,6 +1,7 @@
 import { throwIfAborted } from "../cancellation.ts";
-import { isCommentableIssue, type ReviewIssue } from "./review-issues.ts";
-import type { ReviewContext } from "./review-report.ts";
+import { isFiniteNumber, isRecord } from "../guards.ts";
+import type { CommentableReviewIssue, ReviewIssue } from "./review-issues.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
 
 export interface ExecResultLike {
   readonly stdout: string;
@@ -30,24 +31,16 @@ export type InlineCommentStatus =
   | { readonly issueId: string; readonly status: "skipped"; readonly reason: string }
   | { readonly issueId: string; readonly status: "failed"; readonly reason: string };
 
-const PR_VIEW_JSON_FIELDS = "number,headRefOid,url";
-
 export async function resolveGitHubPrContext(
   exec: ExecLike,
   cwd: string,
-  reviewContext: ReviewContext | undefined,
+  number: number,
   signal?: AbortSignal,
 ): Promise<ResolveGitHubPrContextResult> {
-  const parsedNumber = reviewContext?.diffTarget.kind === "pull-request" ? reviewContext.diffTarget.number : undefined;
-  const prArgs = parsedNumber
-    ? ["pr", "view", String(parsedNumber), "--json", PR_VIEW_JSON_FIELDS]
-    : ["pr", "view", "--json", PR_VIEW_JSON_FIELDS];
-  const prView = await runJson(exec, cwd, prArgs, signal);
+  const prView = await runJson(exec, cwd, ["pr", "view", String(number), "--json", "headRefOid,url"], signal);
   if (!prView.ok) return { ok: false, reason: prView.reason };
 
-  const number = numberField(prView.value, "number") ?? parsedNumber;
   const headSha = stringField(prView.value, "headRefOid");
-  if (number === undefined) return { ok: false, reason: "No GitHub PR number found." };
   if (!headSha) return { ok: false, reason: "GitHub PR head SHA is missing." };
 
   const url = stringField(prView.value, "url");
@@ -82,15 +75,13 @@ ${evidence}
 Recommendation: ${finding.recommendation}`;
 }
 
-export async function postInlineComment(
+async function postInlineComment(
   exec: ExecLike,
   cwd: string,
   prContext: GitHubPrContext,
-  issue: ReviewIssue,
+  issue: CommentableReviewIssue,
   signal?: AbortSignal,
 ): Promise<InlineCommentStatus> {
-  if (!isCommentableIssue(issue)) return { issueId: issue.id, status: "skipped", reason: "Finding has no commentable file/line." };
-
   const result = await runCommand(exec, cwd, [
     "api",
     `repos/${prContext.owner}/${prContext.repo}/pulls/${prContext.number}/comments`,
@@ -113,7 +104,7 @@ export async function postInlineComments(
   exec: ExecLike,
   cwd: string,
   prContext: GitHubPrContext,
-  issues: readonly ReviewIssue[],
+  issues: readonly CommentableReviewIssue[],
   signal?: AbortSignal,
 ): Promise<InlineCommentStatus[]> {
   throwIfAborted(signal);
@@ -125,14 +116,14 @@ export async function postInlineComments(
   const statuses: InlineCommentStatus[] = [];
   for (const issue of issues) {
     throwIfAborted(signal);
-    const key = inlineCommentKey(issue, prContext.headSha);
-    if (key && existing.keys.has(key)) {
+    const key = commentKey(buildInlineCommentBody(issue), issue.file, issue.line, prContext.headSha);
+    if (existing.keys.has(key)) {
       statuses.push({ issueId: issue.id, status: "skipped", reason: "An identical inline comment already exists on this PR head." });
       continue;
     }
     const status = await postInlineComment(exec, cwd, prContext, issue, signal);
     statuses.push(status);
-    if (key && status.status === "posted") existing.keys.add(key);
+    if (status.status === "posted") existing.keys.add(key);
   }
   return statuses;
 }
@@ -161,7 +152,7 @@ async function runJson(
   try {
     return { ok: true, value: JSON.parse(result.stdout) };
   } catch (error) {
-    return { ok: false, reason: error instanceof Error ? `Invalid gh JSON: ${error.message}` : "Invalid gh JSON." };
+    return { ok: false, reason: `Invalid gh JSON: ${unknownErrorMessage(error)}` };
   }
 }
 
@@ -179,7 +170,7 @@ async function runCommand(
     return { ok: true, stdout: result.stdout };
   } catch (error) {
     throwIfAborted(signal);
-    return { ok: false, reason: error instanceof Error ? error.message : "gh command failed." };
+    return { ok: false, reason: unknownErrorMessage(error) };
   }
 }
 
@@ -197,10 +188,6 @@ function parseExistingInlineCommentKeys(value: unknown): Set<string> | undefined
   return keys;
 }
 
-function inlineCommentKey(issue: ReviewIssue, headSha: string): string | undefined {
-  return isCommentableIssue(issue) ? commentKey(buildInlineCommentBody(issue), issue.file, issue.line, headSha) : undefined;
-}
-
 function commentKey(body: string, path: string, line: number, headSha: string): string {
   return JSON.stringify([body, path, line, headSha]);
 }
@@ -208,7 +195,7 @@ function commentKey(body: string, path: string, line: number, headSha: string):
 function numberField(value: unknown, key: string): number | undefined {
   if (!isRecord(value)) return undefined;
   const field = value[key];
-  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+  return isFiniteNumber(field) ? field : undefined;
 }
 
 function stringField(value: unknown, key: string): string | undefined {
@@ -243,7 +230,3 @@ function parsePostedCommentUrl(stdout: string): string | undefined {
     return undefined;
   }
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null;
-}

package/.pi/extensions/pi-workflow-engine/src/review/patch-validation.ts

@@ -37,7 +37,7 @@ export function initialPatchValidation(baseline: WorktreeBaseline, baselineOid:
 }
 
 interface PatchValidationOptions {
-  cwd: string; baseline: WorktreeBaseline; expectedFingerprint: string; baselineOid: string; patch: string;
+  cwd: string; baseline: WorktreeBaseline; baselineOid: string; patch: string;
   evaluation: PatchEvaluation; signal?: AbortSignal;
 }
 
@@ -45,7 +45,6 @@ interface PatchValidationOptions {
 export async function validateCandidatePatch(options: PatchValidationOptions): Promise<PatchValidation> {
   const validation = initialPatchValidation(options.baseline, options.baselineOid, options.patch);
   validation.evaluation = options.evaluation;
-  if (validation.baselineFingerprint !== options.expectedFingerprint) return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
   if (!options.patch.trim()) return validation;
   const worktrees = new WorktreeRegistry(options.cwd);
   let result = validation;
@@ -78,7 +77,7 @@ async function evaluateCandidateInWorktrees(
   if ("error" in candidate) return { ...validation, reason: candidate.error };
   if (candidate.baselineOid !== options.baselineOid) return { ...validation, status: "rejected", reason: "Candidate was produced from a different baseline." };
   const applied = await worktrees.applyPatch(candidate.path, options.patch, options.signal);
-  if (!applied.ok) return { ...validation, status: "rejected", reason: applied.error ?? applied.stderr };
+  if (!applied.ok) return { ...validation, status: "rejected", reason: applied.error };
   const rejected = options.evaluation.outcome === "rejected" ? [options.evaluation.reason] : [];
   const blocked = options.evaluation.outcome === "blocked" ? [options.evaluation.reason] : [];
   if (!options.evaluation.checks.some((check) => check.required)) blocked.push("No required behavior check was selected.");
@@ -94,7 +93,7 @@ async function evaluateCandidateInWorktrees(
       const original = await worktrees.add(options.signal, options.baseline);
       if ("error" in original) { blocked.push(`Baseline worktree setup failed: ${original.error}`); continue; }
       const testApplied = await worktrees.applyPatch(original.path, check.regression.baselinePatch, options.signal);
-      if (!testApplied.ok) { blocked.push(`Baseline regression setup failed: ${testApplied.error ?? testApplied.stderr}`); continue; }
+      if (!testApplied.ok) { blocked.push(`Baseline regression setup failed: ${testApplied.error}`); continue; }
       const baselineResult = await runCheck(check, original.path, options.signal);
       validation.checks.push({ ...check, stage: "baseline", result: baselineResult });
       throwIfAborted(options.signal);

package/.pi/extensions/pi-workflow-engine/src/review/review-actions.ts

@@ -104,7 +104,7 @@ async function handleCommentAction(
   }
 
   const exec = toExecLike(pi);
-  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context, ctx.signal);
+  const resolved = await resolveGitHubPrContext(exec, ctx.cwd, context.diffTarget.number, ctx.signal);
   if (!resolved.ok) {
     await queueCommentFallback(pi, ctx, commentable, context, baseline.ref, resolved.reason);
     return;

package/.pi/extensions/pi-workflow-engine/src/review/review-diff-lines.ts

@@ -0,0 +1,54 @@
+import { repoPathCandidates } from "../advisory-evidence.ts";
+import type { AdvisoryLocation } from "../advisory-schema.ts";
+
+const C_QUOTE_ESCAPES: Readonly<Record<string, number>> = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, "\\": 92 };
+
+/** Undo git's C-style quoting of unusual path names, e.g. `"b/caf\303\251.txt"`. */
+function unquoteGitPath(path: string): string {
+  if (path.length < 2 || !path.startsWith('"') || !path.endsWith('"')) return path;
+  const bytes: number[] = [];
+  for (const [, escape, literal] of path.slice(1, -1).matchAll(/\\([0-7]{3}|.)|([^\\]+)/g)) {
+    if (literal !== undefined) bytes.push(...Buffer.from(literal));
+    else if (escape !== undefined) bytes.push(escape.length === 3 ? parseInt(escape, 8) : (C_QUOTE_ESCAPES[escape] ?? escape.charCodeAt(0)));
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+/** Parse a unified diff into the set of added/changed new-file line numbers per file. */
+export function changedLines(diff: string): Map<string, Set<number>> {
+  const byFile = new Map<string, Set<number>>();
+  let file: string | null = null;
+  let newLine = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = unquoteGitPath(raw.slice(4).trim());
+      file = path === "/dev/null" ? null : path.replace(/^b\//, "");
+      if (file && !byFile.has(file)) byFile.set(file, new Set());
+    } else if (raw.startsWith("@@")) {
+      const match = /\+(\d+)/.exec(raw);
+      newLine = match ? Number(match[1]) : 0;
+    } else if (file === null || raw.startsWith("---") || raw.startsWith("\\")) {
+      // file header, deletion, or "No newline" marker — record nothing
+    } else if (raw.startsWith("+")) {
+      byFile.get(file)!.add(newLine++);
+    } else if (!raw.startsWith("-")) {
+      newLine++; // context line advances the new-file counter; deletions do not
+    }
+  }
+  return byFile;
+}
+
+/**
+ * The location re-keyed to its repo-relative diff path when it is inside the diff, else undefined.
+ * The exact path wins; a stray `./`, `a/` or `b/` prefix is tolerated. File-level locations count
+ * if the file changed; lines get ±1 of fuzz.
+ */
+export function diffAnchor(changed: ReadonlyMap<string, ReadonlySet<number>>, location: AdvisoryLocation): AdvisoryLocation | undefined {
+  for (const file of repoPathCandidates(location.file)) {
+    const lines = changed.get(file);
+    if (!lines) continue;
+    const { line } = location;
+    return line == null || lines.has(line) || lines.has(line - 1) || lines.has(line + 1) ? { ...location, file } : undefined;
+  }
+  return undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/review/review-fix-workflow.ts

@@ -94,7 +94,7 @@ export async function runReviewFixWorkflow(
         tools: [...REVIEW_FIX_TOOLS],
         toolHints: ["search"],
       });
-      const validation = await evaluateReviewFix(api, { issue, context, baseline, isolated });
+      const validation = await evaluateReviewFix(api, { issue, baseline, isolated });
       return {
         findingId: issue.id,
         result: isolated.result,
@@ -123,17 +123,14 @@ function isReviewFixPreview(outcome: ReviewFixOutcome): outcome is ReviewFixPrev
   return "patch" in outcome;
 }
 
+/** `baseline` was already revalidated against the reviewed snapshot identity by resolveReviewWorktreeBaseline. */
 async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
-  issue: ReviewIssue; context: ReviewContext | undefined; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
+  issue: ReviewIssue; baseline: WorktreeBaseline; isolated: IsolatedAgentResult<string>;
 }): Promise<PatchValidation> {
-  const { issue, context, baseline, isolated } = input;
+  const { issue, baseline, isolated } = input;
   const validation = initialPatchValidation(baseline, isolated.baselineOid, isolated.patch);
   if (!isolated.patch.trim()) return validation;
   if (!isolated.baselineOid) return { ...validation, reason: "Candidate has no recorded baseline identity." };
-  if (!context?.snapshot) return { ...validation, reason: "Reviewed snapshot identity is unavailable." };
-  if (validation.baselineFingerprint !== context.snapshot.baselineFingerprint) {
-    return { ...validation, status: "rejected", reason: "Stale reviewed baseline identity." };
-  }
   try {
     const evaluated = await api.agent(
       `Independently evaluate a candidate repair. Your fresh worktree contains the exact reviewed baseline plus the captured patch. The implementer's report is not validation evidence. Inspect the finding, callers and tests. Reject incorrect repairs; return blocked if required validation is unavailable. Select at most six focused deterministic checks with executable and argument arrays. Require at least one meaningful behavior check. If a regression test is applicable, supply a test-only baselinePatch and specific expectedFailure so the engine can prove it fails before the repair and passes after. Do not edit, install dependencies, commit or change branches. The engine will execute checks independently.\nFinding: ${JSON.stringify(serializeReviewIssue(issue))}\nBaseline: ${isolated.baselineOid}\nPatch SHA-256: ${validation.patchHash}\nPatch:\n${isolated.patch}`,
@@ -141,10 +138,11 @@ async function evaluateReviewFix(api: ReviewFixWorkflowApi, input: {
         label: `evaluate:${issue.id}`, phase: "Validate patch previews", profile: "medium", resume: "off",
         tools: ["read", "bash", "grep", "find", "ls"], toolHints: ["search"], schema: PatchEvaluationSchema },
     );
+    // Drift here is usually a test byproduct in the evaluator's worktree, not evidence against the repair.
     if (evaluated.baselineOid !== isolated.baselineOid || evaluated.patch !== isolated.patch) {
-      return { ...validation, status: "rejected", reason: "Evaluator changed the candidate or used a different baseline.", evaluation: evaluated.result };
+      return { ...validation, status: "blocked", reason: "Evaluator session changed its workspace (candidate patch or baseline drifted); independent checks were not run.", evaluation: evaluated.result };
     }
-    return await validateCandidatePatch({ cwd: api.cwd, baseline, expectedFingerprint: context.snapshot.baselineFingerprint,
+    return await validateCandidatePatch({ cwd: api.cwd, baseline,
         baselineOid: isolated.baselineOid, patch: isolated.patch, evaluation: evaluated.result, signal: api.signal });
   } catch (error) {
     if (isFatalWorkflowError(error, api.signal)) throw error;

package/.pi/extensions/pi-workflow-engine/src/review/review-format.ts

@@ -1,133 +1,67 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { truncateDisplay, type WorkflowThemeColor } from "../ui/workflow-format.ts";
-import { formatIssueLocation, type ReviewIssue } from "./review-issues.ts";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { dot, fit, GLYPH, hangingWrap, severityBadge, severityRank, truncatePath } from "../ui/kit.ts";
+import type { ReviewIssue } from "./review-issues.ts";
 
-export interface RenderIssuesTableOptions {
-  readonly maxRows?: number;
+/** Most severe first; report order (and so the stable R-number) breaks ties. */
+export function sortIssuesForDisplay(issues: readonly ReviewIssue[]): ReviewIssue[] {
+  return issues
+    .map((issue, index) => ({ issue, index }))
+    .sort((a, b) => severityRank(a.issue.finding.severity) - severityRank(b.issue.finding.severity) || a.index - b.index)
+    .map(({ issue }) => issue);
 }
 
-const DEFAULT_MAX_ROWS = 12;
-const ID_WIDTH = 4;
-const SEVERITY_WIDTH = 6;
-const CONFIDENCE_WIDTH = 6;
-const CATEGORY_WIDTH = 8;
-const LOCATION_WIDTH = 30;
-const SUMMARY_WIDTH = 58;
-
-export function renderIssuesTable(issues: readonly ReviewIssue[], theme: Theme, options: RenderIssuesTableOptions = {}): string {
-  const maxRows = options.maxRows ?? DEFAULT_MAX_ROWS;
-  const visible = maxRows >= 0 ? issues.slice(0, maxRows) : issues;
-  const lines = [
-    renderRow(["ID", "Sev", "Conf", "Cat", "Location", "Summary"], theme.fg("dim", "│"), theme, true),
-    theme.fg("dim", renderSeparator()),
-  ];
-
-  for (const issue of visible) {
-    lines.push(
-      renderRow(
-        [
-          issue.id,
-          issue.finding.severity,
-          issue.finding.confidence,
-          issue.finding.category,
-          formatIssueLocation(issue),
-          issue.finding.summary,
-        ],
-        theme.fg("dim", "│"),
-        theme,
-        false,
-        issue,
-      ),
-    );
-  }
-
-  if (issues.length > visible.length) {
-    lines.push(theme.fg("dim", `… ${issues.length - visible.length} more finding(s)`));
-  }
-
-  return lines.join("\n");
-}
-
-export function renderIssueDetails(issue: ReviewIssue, theme: Theme): string {
-  return renderIssueDetailLines(issue, theme, 120).join("\n");
-}
-
-export function renderIssueDetailLines(issue: ReviewIssue, theme: Theme, width: number): string[] {
-  const finding = issue.finding;
-  const metadata = `${finding.category} · severity ${finding.severity} · confidence ${finding.confidence}${finding.verdict ? ` · ${finding.verdict}` : ""}`;
-  const lines = [`${theme.fg("accent", issue.id)} ${theme.fg("text", finding.summary)}`];
-  lines.push(...fieldLines("Metadata", metadata, width, theme));
-  if (finding.sourceCandidateIds?.length) lines.push(...fieldLines("Sources", finding.sourceCandidateIds.join(", "), width, theme));
-  lines.push(...fieldLines("Location", formatIssueLocation(issue), width, theme, "accent"));
-  lines.push(...fieldLines("Impact", finding.impact, width, theme));
-  lines.push(...fieldLines("Evidence", finding.evidence.join("; ") || "(none cited)", width, theme));
-  lines.push(...fieldLines("Recommendation", finding.recommendation, width, theme));
-  return lines.flatMap((line) => wrapTextWithAnsi(line, Math.max(10, width)));
+/** `src/cache.ts:13`, without the symbol; the detail view shows the symbol on its own. */
+export function issuePath(issue: ReviewIssue): string {
+  if (!issue.file) return "no location";
+  return issue.line === undefined ? issue.file : `${issue.file}:${issue.line}`;
 }
 
-function fieldLines(label: string, value: string, width: number, theme: Theme, valueColor: WorkflowThemeColor = "muted"): string[] {
-  const prefix = `  ${theme.fg("dim", `${label}:`)}`;
-  const separator = " ";
-  const valueText = theme.fg(valueColor, value);
-  const available = Math.max(10, width - visibleWidth(`${label}:  `) - 2);
-  const wrapped = wrapTextWithAnsi(valueText, available);
-  if (wrapped.length === 0) return [`${prefix}${separator}`];
-  const continuation = " ".repeat(visibleWidth(`${label}:  `) + 2);
-  return wrapped.map((line, index) => (index === 0 ? `${prefix}${separator}${line}` : `${continuation}${line}`));
+/**
+ * One aligned row: `HIGH R003  src/cache.ts:13      The parser accepts an empty value…`.
+ * `pathColumn` (from `findingPathColumn`) narrows the location column to the paths actually listed.
+ */
+export function renderFindingRow(issue: ReviewIssue, width: number, theme: Theme, pathColumn?: number): string {
+  const head = `${severityBadge(issue.finding.severity, theme)} ${theme.fg("dim", issue.id)}`;
+  const room = Math.max(0, width - visibleWidth(head) - 2);
+  const pathWidth = Math.min(pathColumn ?? Number.POSITIVE_INFINITY, maxPathWidth(room));
+  if (room < pathWidth + 10) return fit(`${head}  ${theme.fg("text", issue.finding.summary)}`, width);
+  const path = theme.fg("accent", fit(truncatePath(issuePath(issue), pathWidth), pathWidth));
+  return fit(`${head}  ${path}  ${theme.fg("text", issue.finding.summary)}`, width);
 }
 
-function renderRow(
-  cells: readonly [string, string, string, string, string, string],
-  separator: string,
-  theme: Theme,
-  header: boolean,
-  issue?: ReviewIssue,
-): string {
-  const rendered = [
-    cell(cells[0], ID_WIDTH),
-    colorCell(cell(cells[1], SEVERITY_WIDTH), header ? "dim" : severityColor(issue?.finding.severity ?? "low"), theme),
-    colorCell(cell(cells[2], CONFIDENCE_WIDTH), header ? "dim" : confidenceColor(issue?.finding.confidence ?? "low"), theme),
-    cell(cells[3], CATEGORY_WIDTH),
-    cell(cells[4], LOCATION_WIDTH),
-    cell(cells[5], SUMMARY_WIDTH),
-  ];
-  if (header) {
-    return rendered.map((entry) => theme.fg("dim", entry)).join(` ${separator} `);
-  }
-  return rendered.join(` ${separator} `);
+function maxPathWidth(room: number): number {
+  return Math.min(Math.max(16, Math.floor(room * 0.38)), 34);
 }
 
-function cell(value: string, width: number): string {
-  return truncateDisplay(value, width).padEnd(width, " ");
+/** A location column as wide as the longest listed path, never below 12 columns. */
+export function findingPathColumn(issues: readonly ReviewIssue[]): number {
+  return Math.max(12, ...issues.map((issue) => visibleWidth(issuePath(issue))));
 }
 
-function colorCell(value: string, color: WorkflowThemeColor, theme: Theme): string {
-  return theme.fg(color, value);
-}
+const LABEL_WIDTH = 10;
 
-function renderSeparator(): string {
-  return [ID_WIDTH, SEVERITY_WIDTH, CONFIDENCE_WIDTH, CATEGORY_WIDTH, LOCATION_WIDTH, SUMMARY_WIDTH].map((width) => "─".repeat(width)).join("─┼─");
-}
-
-function severityColor(severity: ReviewIssue["finding"]["severity"]): WorkflowThemeColor {
-  switch (severity) {
-    case "high":
-      return "error";
-    case "medium":
-      return "warning";
-    case "low":
-      return "muted";
-  }
+/** The full finding: headline, wrapped summary, then aligned Location / Impact / Evidence / Fix sections. */
+export function renderFindingDetail(issue: ReviewIssue, width: number, theme: Theme): string[] {
+  const finding = issue.finding;
+  const meta = [finding.category, `confidence ${finding.confidence}`, finding.verdict?.toLowerCase()].filter(Boolean).join(dot(theme));
+  const lines = [
+    `${severityBadge(finding.severity, theme)} ${theme.fg("accent", theme.bold(issue.id))}${dot(theme)}${theme.fg("muted", meta)}`,
+    ...hangingWrap(theme.bold(finding.summary), width),
+    "",
+  ];
+  const location = [theme.fg("accent", issuePath(issue)), issue.symbol ? theme.fg("muted", issue.symbol) : undefined].filter(Boolean).join(dot(theme));
+  lines.push(...labelledLines("Location", [location], width, theme));
+  lines.push(...labelledLines("Impact", [finding.impact], width, theme));
+  const evidence = finding.evidence.length > 0 ? finding.evidence.map((item) => `${GLYPH.bullet} ${item}`) : [theme.fg("dim", "none cited")];
+  lines.push(...labelledLines("Evidence", evidence, width, theme, "  "));
+  lines.push(...labelledLines("Fix", [finding.recommendation], width, theme));
+  return lines;
 }
 
-function confidenceColor(confidence: ReviewIssue["finding"]["confidence"]): WorkflowThemeColor {
-  switch (confidence) {
-    case "high":
-      return "success";
-    case "medium":
-      return "warning";
-    case "low":
-      return "muted";
-  }
+/** A dim label column (10 wide) with each item wrapped beside it, so result sections align with finding details. */
+export function labelledLines(label: string, items: readonly string[], width: number, theme: Theme, itemIndent = ""): string[] {
+  const first = theme.fg("dim", label.padEnd(LABEL_WIDTH, " "));
+  const rest = " ".repeat(LABEL_WIDTH);
+  return items.flatMap((item, index) => hangingWrap(item, width, index === 0 ? first : rest, rest + itemIndent));
 }

package/.pi/extensions/pi-workflow-engine/src/review/review-handoff.ts

@@ -23,7 +23,7 @@ Instructions:
 - Do not edit files or make code changes.
 - Prefer installed GitHub MCP/tools if present; otherwise use the GitHub CLI (gh).
 - Before posting, resolve the current PR head and require it to equal the verified reviewed head \`${verifiedHead}\`; stop if it differs.
-- With gh, resolve the PR using \`gh pr view\` and \`gh repo view\`, then call \`gh api repos/{owner}/{repo}/pulls/{number}/comments\` with \`commit_id\`, \`path\`, \`line\`, and \`side=RIGHT\`.
+- With gh, resolve the PR using \`gh pr view <context.diffTarget.number> --json headRefOid,url\` and take owner/repo from the PR \`url\` (the base repository, so fork PRs are commented upstream), then call \`gh api repos/{owner}/{repo}/pulls/{number}/comments\` with \`commit_id\`, \`path\`, \`line\`, and \`side=RIGHT\`.
 - Do not post duplicate comments.
 - Do not post line-less findings as inline comments.
 - Ask the user if the upstream PR cannot be identified.

package/.pi/extensions/pi-workflow-engine/src/review/review-issues.ts

@@ -1,4 +1,5 @@
-import type { AdvisoryFinding, AdvisoryReport } from "../advisory-schema.ts";
+import { formatAdvisoryLocation, type AdvisoryFinding, type AdvisoryReport } from "../advisory-schema.ts";
+import { isFiniteNumber } from "../guards.ts";
 
 export type ReviewIssueAction = "fix" | "comment" | "close";
 
@@ -9,8 +10,6 @@ export interface ReviewIssueSelection {
 
 export interface ReviewIssue {
   readonly id: string;
-  readonly index: number;
-  readonly workflowName: string;
   readonly file?: string;
   readonly line?: number;
   readonly symbol?: string;
@@ -35,13 +34,11 @@ export interface SerializedReviewIssue {
   readonly recommendation: string;
 }
 
-export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
+export function toReviewIssues(report: Pick<AdvisoryReport, "findings">): ReviewIssue[] {
   return report.findings.map((finding, index) => {
     const location = finding.reviewAnchor ?? finding.locations[0];
     return {
       id: formatIssueId(index),
-      index,
-      workflowName: name,
       file: location?.file,
       line: location?.line,
       symbol: location?.symbol,
@@ -52,9 +49,7 @@ export function toReviewIssues(name: string, report: Pick<AdvisoryReport, "findi
 
 export function formatIssueLocation(issue: ReviewIssue): string {
   if (!issue.file) return "(no location)";
-  const line = issue.line != null ? `:${issue.line}` : "";
-  const symbol = issue.symbol ? ` (${issue.symbol})` : "";
-  return `${issue.file}${line}${symbol}`;
+  return formatAdvisoryLocation({ file: issue.file, line: issue.line, symbol: issue.symbol });
 }
 
 export function serializeReviewIssue(issue: ReviewIssue): SerializedReviewIssue {
@@ -76,10 +71,10 @@ export function serializeReviewIssue(issue: ReviewIssue): SerializedReviewIssue
   };
 }
 
-export function isCommentableIssue(
-  issue: ReviewIssue,
-): issue is ReviewIssue & { readonly file: string; readonly line: number } {
-  return typeof issue.file === "string" && issue.file.trim().length > 0 && typeof issue.line === "number" && Number.isFinite(issue.line);
+export type CommentableReviewIssue = ReviewIssue & { readonly file: string; readonly line: number };
+
+export function isCommentableIssue(issue: ReviewIssue): issue is CommentableReviewIssue {
+  return typeof issue.file === "string" && issue.file.trim().length > 0 && isFiniteNumber(issue.line);
 }
 
 function formatIssueId(index: number): string {

package/.pi/extensions/pi-workflow-engine/src/review/review-report.ts

@@ -1,7 +1,7 @@
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 import { AdvisoryReportWithStatsSchema } from "../advisory-schema.ts";
-import { formatReviewDiffTarget, isReviewDiffTarget, ReviewDiffTargetSchema } from "../review-diff-target.ts";
+import { formatReviewDiffTarget, isAllowedReviewDiffTarget, ReviewDiffTargetSchema } from "../review-diff-target.ts";
 
 /** Atomic identity of the exact diff and post-change snapshot that were reviewed. */
 export const ReviewSnapshotIdentitySchema = Type.Object({
@@ -27,13 +27,9 @@ export type ReviewSnapshotIdentity = Static<typeof ReviewSnapshotIdentitySchema>
 export type ReviewContext = Static<typeof ReviewContextSchema>;
 export type ReviewReport = Static<typeof ReviewReportSchema>;
 
+/** The schema check covers the nested context; the diff target also has to round-trip through the allowlist parser. */
 export function isReviewReport(value: unknown): value is ReviewReport {
-  if (!Value.Check(ReviewReportSchema, value)) return false;
-  return value.reviewContext === undefined || isReviewContext(value.reviewContext);
-}
-
-export function isReviewContext(value: unknown): value is ReviewContext {
-  return Value.Check(ReviewContextSchema, value) && isReviewDiffTarget(value.diffTarget);
+  return Value.Check(ReviewReportSchema, value) && (value.reviewContext === undefined || isAllowedReviewDiffTarget(value.reviewContext.diffTarget));
 }
 
 /** Prompt-facing context retains the canonical display command without persisting duplicate identity. */