prreviewbuddy 0.53.1 → 0.55.1

package/dist/{delete_review-DMJXD3bf.js → delete_review-B2bqhgtx.js}

@@ -1643,7 +1643,8 @@ function completeReviewSession(session, result, context, options = {}) {
 			...session.metadata,
 			...context ? reviewFacts(result, context) : {
 				fileCoverage: void 0,
-				discussionStats: void 0
+				discussionStats: void 0,
+				authorDescription: void 0
 			},
 			commitSha: options.commitSha ?? session.metadata.commitSha,
 			durationMs: Math.max(0, now - session.metadata.generatedAt)
@@ -1664,7 +1665,8 @@ function reviewFacts(result, context) {
 			reviewedFiles: sectionedFiles(result, context),
 			totalChangedFiles: context.fileCoverage.totalChangedFiles
 		},
-		...context.prContext ? { discussionStats: countDiscussion(context) } : {}
+		...context.prContext ? { discussionStats: countDiscussion(context) } : {},
+		authorDescription: context.prContext?.pullRequest.body
 	};
 }
 /**
@@ -2237,6 +2239,7 @@ async function buildChangeSet(options) {
 				number: 0,
 				title: changeTitle(subjects, headRef),
 				body: subjects.length > 1 ? subjects.map((s) => `- ${s}`).join("\n") : null,
+				bodySource: "commit-subjects",
 				base: {
 					ref: base.display,
 					sha: mergeBase
@@ -6296,6 +6299,7 @@ function sanitisePullRequest(value) {
 	};
 	const title = typeof value.title === "string" ? value.title.trim() : "";
 	if (title) pr.title = title.slice(0, 200);
+	if (typeof value.body === "string" && value.body.trim()) pr.body = value.body;
 	const headSha = label(value.headSha);
 	if (headSha) pr.headSha = headSha;
 	const headRef = label(value.headRef);
@@ -6851,7 +6855,7 @@ function slug(repo) {
 * `baseRefOid` is a diff taken against the wrong *commit*, which is worse because the branch name
 * is right and everything reads as normal. A list nobody asserts is a list somebody tidies.
 */
-var PR_FIELDS = "number,url,title,headRefName,headRefOid,baseRefName,baseRefOid,changedFiles,author";
+var PR_FIELDS = "number,url,title,body,headRefName,headRefOid,baseRefName,baseRefOid,changedFiles,author";
 async function viewRequest(repo, reference, cwd, env) {
 	return await ghJson([
 		"pr",
@@ -6863,7 +6867,7 @@ async function viewRequest(repo, reference, cwd, env) {
 		PR_FIELDS
 	], cwd, env);
 }
-function text(value) {
+function text$1(value) {
 	return typeof value === "string" ? value.trim() : "";
 }
 /**
@@ -6884,30 +6888,31 @@ function fileUrlTemplate(prUrl) {
 * email address all live in `pr_context.ts` and in nothing else.
 */
 function identity(raw) {
-	const url = text(raw.url);
+	const url = text$1(raw.url);
 	const author = raw.author ?? null;
 	return {
 		provider: GITHUB_FORGE_ID,
 		number: typeof raw.number === "number" ? raw.number : 0,
 		url,
-		title: text(raw.title),
-		headSha: text(raw.headRefOid),
-		headRef: text(raw.headRefName),
-		baseRef: text(raw.baseRefName),
+		title: text$1(raw.title),
+		body: raw.body,
+		headSha: text$1(raw.headRefOid),
+		headRef: text$1(raw.headRefName),
+		baseRef: text$1(raw.baseRefName),
 		filesUrl: url ? `${url}/files` : "",
 		fileUrlTemplate: fileUrlTemplate(url),
 		author: author ? {
-			name: text(author.name),
-			handle: text(author.login)
+			name: text$1(author.name),
+			handle: text$1(author.login)
 		} : null
 	};
 }
 /**
 * The watcher's query: where the branch is, and whether the request is still open.
 *
-* Deliberately not `PR_FIELDS`. That list exists because a review needs all nine of them, and its
+* Deliberately not `PR_FIELDS`. That list exists because a review needs all ten of them, and its
 * docblock warns that trimming it fails silently rather than loudly. Sharing it here would put a
-* nine-field query on a five-minute timer across the whole working set, and would put the watcher
+* ten-field query on a five-minute timer across the whole working set, and would put the watcher
 * in a position to "optimise" a list that must never shrink.
 *
 * `state` rides on the same call rather than being a second one, which keeps the watcher's rate
@@ -6930,7 +6935,7 @@ var STATES = /* @__PURE__ */ new Map([
 * about a request GitHub declined to describe, once per cycle, indefinitely.
 */
 function readHeadSha(raw) {
-	const sha = text(raw?.headRefOid);
+	const sha = text$1(raw?.headRefOid);
 	if (!sha) return {
 		kind: "failed",
 		detail: "GitHub reported no head commit for this request."
@@ -6938,7 +6943,7 @@ function readHeadSha(raw) {
 	return {
 		kind: "head",
 		sha,
-		state: STATES.get(text(raw?.state)) ?? null
+		state: STATES.get(text$1(raw?.state)) ?? null
 	};
 }
 async function headOf(repo, number, env, cwd) {
@@ -6973,8 +6978,8 @@ async function resolve$1(repo, reference, env, cwd) {
 	} catch (error) {
 		throw new TargetError(`${reference} could not be looked up on GitHub: ${error.message}`);
 	}
-	const headRef = text(raw.headRefName);
-	const headSha = text(raw.headRefOid);
+	const headRef = text$1(raw.headRefName);
+	const headSha = text$1(raw.headRefOid);
 	if (!headRef || !headSha) throw new TargetError(`${reference} was found on GitHub but reported no branch and commit.`);
 	const resolved = {
 		reference,
@@ -6982,12 +6987,12 @@ async function resolve$1(repo, reference, env, cwd) {
 		headSha,
 		provider: GITHUB_FORGE_ID
 	};
-	const baseRef = text(raw.baseRefName);
+	const baseRef = text$1(raw.baseRefName);
 	if (baseRef) resolved.baseRef = baseRef;
-	const baseSha = text(raw.baseRefOid);
+	const baseSha = text$1(raw.baseRefOid);
 	if (baseSha) resolved.baseSha = baseSha;
 	if (typeof raw.changedFiles === "number") resolved.changedFiles = raw.changedFiles;
-	const url = text(raw.url);
+	const url = text$1(raw.url);
 	if (url) resolved.url = url;
 	if (typeof raw.number === "number") resolved.number = raw.number;
 	return resolved;
@@ -9081,7 +9086,7 @@ Follow-up Prompts:
 ${buildFollowUpPromptsSpec()}
 
 PR Title: ${raw.pullRequest.title}
-${raw.pullRequest.body ? `\nPR Description:\n${raw.pullRequest.body}\n` : ""}
+${raw.pullRequest.body ? `\n${raw.pullRequest.bodySource === "commit-subjects" ? "Commit subjects (there is no PR Description)" : "PR Description"}:\n${raw.pullRequest.body}\n` : ""}
 ${diff}`;
 	const overheadChars = assemble({
 		diff: "",
@@ -9390,10 +9395,304 @@ function normalizeSections(value) {
 	return sections;
 }
 //#endregion
+//#region ../../packages/review-harness/src/domain/ai_review/author_description.ts
+/**
+* Reading a pull request's description for whether it says anything, without ever changing it.
+*
+* Nothing here returns a copy to store or show. The description is shown verbatim, so a cleaned
+* copy is only ever a means of asking a question of it: whether it says anything, and whether a
+* quote is something the author said.
+*/
+/**
+* Lines that are a pull request template's scaffolding when they stand alone.
+*
+* Matched against a whole line only, after its heading marker, bold and trailing colon are gone.
+* A heading that says something of its own, `## Fix startup crashes`, is not a label and survives.
+*/
+var TEMPLATE_LABELS = /* @__PURE__ */ new Set([
+	"description",
+	"summary",
+	"changes",
+	"what",
+	"why",
+	"how",
+	"context",
+	"motivation",
+	"motivation and context",
+	"what changed",
+	"what does this pr do",
+	"why is this needed",
+	"type of change",
+	"testing",
+	"tests",
+	"test plan",
+	"how to test",
+	"how has this been tested",
+	"screenshots",
+	"notes",
+	"checklist",
+	"related issues",
+	"related issue",
+	"links"
+]);
+var HTML_COMMENT = /<!--[\s\S]*?-->/g;
+var HEADING_MARKER = /^#{1,6}\s*/;
+var UNCHECKED_TASK = /^[-*+]\s+\[ \]/;
+var EMPTY_LIST_ITEM = /^(?:[-*+]|\d+[.)])\s*$/;
+function asLabel(line) {
+	return line.replace(HEADING_MARKER, "").replace(/^\*\*(.*)\*\*$/, "$1").replace(/^__(.*)__$/, "$1").replace(/:\s*$/, "").trim().toLowerCase();
+}
+/** One line, reduced to whatever in it is the author's own words. Empty when none are. */
+function substance(line) {
+	const trimmed = line.trim();
+	if (!trimmed || UNCHECKED_TASK.test(trimmed) || EMPTY_LIST_ITEM.test(trimmed)) return "";
+	if (TEMPLATE_LABELS.has(asLabel(trimmed))) return "";
+	return trimmed.replace(HEADING_MARKER, "");
+}
+/**
+* The parts of a description the author wrote, one line each, with the template's scaffolding gone.
+*
+* Only HTML comments, unticked checklist items, empty list items and bare template labels are
+* discounted. A ticked item is the author asserting something, so it stays.
+*/
+function authorText(description) {
+	if (!description) return "";
+	return description.replace(HTML_COMMENT, "").split("\n").map(substance).filter((line) => line !== "").join("\n");
+}
+/**
+* Whether a description has anything in it beyond an unfilled template.
+*
+* Conservative by design: any line that survives counts, so a sparse description is shown rather
+* than hidden.
+*/
+function hasAuthorContent(description) {
+	return authorText(description) !== "";
+}
+function isLongDescription(description) {
+	const trimmed = description.trim();
+	return trimmed.split("\n").length > 10 || trimmed.length > 700;
+}
+//#endregion
+//#region ../../packages/review-harness/src/domain/ai_review/motivation.ts
+var MOTIVATION_STATUSES = [
+	"stated",
+	"inferred",
+	"unclear"
+];
+var MOTIVATION_EVIDENCE_KINDS = [
+	"test",
+	"behaviour",
+	"issue",
+	"commit",
+	"docs",
+	"code"
+];
+/** Ours, not the model's: what an unsupported claim is replaced with when a question remains. */
+var UNESTABLISHED_MOTIVATION = "The reason for this change isn't established by the description or the code.";
+/** Stable, so "Mark answered" on it survives a reload like any other question's. */
+var INTENT_QUESTION_ID = "intent-motivation";
+/**
+* Fewer words than this cannot attribute a reason to anyone: "the cache" is in most descriptions
+* that mention a cache. An initial setting, not a measured one.
+*/
+var MIN_QUOTE_WORDS = 3;
+function text(value) {
+	if (typeof value !== "string") return void 0;
+	return value.trim() || void 0;
+}
+function normalizeEvidence(value) {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((raw) => {
+		const item = raw ?? {};
+		const kind = item.kind;
+		const detail = text(item.detail);
+		if (!MOTIVATION_EVIDENCE_KINDS.includes(kind) || !detail) return [];
+		const file = text(item.file);
+		return [{
+			kind,
+			detail,
+			...file ? { file } : {}
+		}];
+	});
+}
+/** The model's `motivation`, if it is one at all. Absent, or the wrong shape, is no motivation. */
+function normalizeMotivation(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const item = value;
+	const status = item.status;
+	const summary = text(item.summary);
+	if (!MOTIVATION_STATUSES.includes(status) || !summary) return void 0;
+	const sourceQuote = text(item.sourceQuote);
+	const authorQuestion = text(item.authorQuestion);
+	return {
+		status,
+		summary,
+		evidence: normalizeEvidence(item.evidence),
+		...sourceQuote ? { sourceQuote } : {},
+		...authorQuestion ? { authorQuestion } : {}
+	};
+}
+/** Whitespace is the one thing a faithful quote may differ in: line wrapping is not wording. */
+function collapse(value) {
+	return value.replace(/\s+/g, " ").trim();
+}
+/**
+* Whether the author wrote this, in these words, in the description the analysis read.
+*
+* Searched in the author's own text only. A template's instructions are in the description too, and
+* "Explain why this change is needed" would otherwise pass as the author explaining why.
+*/
+function isAuthorQuote(quote, description) {
+	if (!quote) return false;
+	const needle = collapse(quote);
+	if (needle.split(" ").length < MIN_QUOTE_WORDS) return false;
+	return collapse(authorText(description)).includes(needle);
+}
+/**
+* The checks, applied to one candidate.
+*
+* Each status has one thing it cannot stand without: a verified quote, evidence, a question. The
+* fields that belong to the other statuses are dropped rather than carried, so a `stated` motive
+* cannot also show a guess and an `unclear` one cannot also show a quote.
+*
+* A claim that fails becomes unclear only if the model also asked the question that would settle
+* it, and then in our words rather than its own. Otherwise there is nothing to show that the
+* reviewer could act on, and nothing is shown.
+*/
+function verifyMotivation(candidate, authorDescription) {
+	if (!candidate) return {};
+	const base = {
+		contractVersion: 1,
+		summary: candidate.summary
+	};
+	if (candidate.status === "stated" && isAuthorQuote(candidate.sourceQuote, authorDescription)) return { motivation: {
+		...base,
+		status: "stated",
+		sourceQuote: candidate.sourceQuote
+	} };
+	if (candidate.status === "inferred" && candidate.evidence.length > 0) return { motivation: {
+		...base,
+		status: "inferred",
+		evidence: candidate.evidence
+	} };
+	if (candidate.status === "unclear" && candidate.authorQuestion) return { motivation: {
+		...base,
+		status: "unclear",
+		authorQuestion: candidate.authorQuestion
+	} };
+	const reason = candidate.status === "stated" ? candidate.sourceQuote ? "unverified-quote" : "missing-quote" : candidate.status === "inferred" ? "no-evidence" : "no-question";
+	const correction = {
+		status: candidate.status,
+		summary: candidate.summary,
+		reason
+	};
+	if (candidate.status !== "unclear" && candidate.authorQuestion) return {
+		motivation: {
+			contractVersion: 1,
+			status: "unclear",
+			summary: UNESTABLISHED_MOTIVATION,
+			authorQuestion: candidate.authorQuestion
+		},
+		correction: {
+			...correction,
+			outcome: "downgraded"
+		}
+	};
+	return { correction: {
+		...correction,
+		outcome: "withheld"
+	} };
+}
+/**
+* The one evidence-link policy, for both hosts.
+*
+* A changed file is a diff link and a real unchanged file a source link. A path the host can show
+* does not exist is removed and returned for the audit. A path the host cannot check keeps its
+* text and gets no state, so it is never presented as a link the reader can trust.
+*/
+function placeEvidenceFiles(motivation, paths) {
+	if (!motivation?.evidence) return {
+		motivation,
+		removed: []
+	};
+	const removed = [];
+	const evidence = motivation.evidence.map(({ fileState: _ignored, ...item }) => {
+		if (!item.file) return item;
+		if (paths.changed(item.file)) return {
+			...item,
+			fileState: "changed"
+		};
+		if (!paths.exists) return item;
+		if (paths.exists(item.file)) return {
+			...item,
+			fileState: "unchanged"
+		};
+		removed.push(item.file);
+		const { file: _gone, ...rest } = item;
+		return rest;
+	});
+	return {
+		motivation: {
+			...motivation,
+			evidence
+		},
+		removed
+	};
+}
+/** Two questions are the same question when they differ only in case, spacing or end punctuation. */
+function sameQuestion(a, b) {
+	const key = (value) => collapse(value).toLowerCase().replace(/[?.!\s]+$/, "");
+	return key(a) === key(b);
+}
+/**
+* File an unclear motive's question with the rest, as the one Intent question.
+*
+* A question the model already asked in the same words is tagged rather than repeated, so the
+* reader meets it once, in the Intent group. Telling two differently worded questions apart is
+* judgement and is left to the prompt.
+*/
+function withIntentQuestion(questions, motivation) {
+	if (motivation?.status !== "unclear" || !motivation.authorQuestion) return questions;
+	const asked = motivation.authorQuestion;
+	const existing = questions.findIndex((q) => sameQuestion(q.question, asked));
+	if (existing >= 0) return questions.map((q, index) => index === existing ? {
+		...q,
+		category: "intent"
+	} : q);
+	const taken = new Set(questions.map((q) => q.id));
+	let id = INTENT_QUESTION_ID;
+	for (let n = 2; taken.has(id); n += 1) id = `${INTENT_QUESTION_ID}-${n}`;
+	return [...questions, {
+		id,
+		question: asked,
+		category: "intent"
+	}];
+}
+/** The candidate checked and, when it ends unclear, its question filed. */
+function applyMotivation(result, candidate, authorDescription) {
+	const { motivation, correction } = verifyMotivation(candidate, authorDescription);
+	const { motivation: _unverified, ...rest } = result;
+	return {
+		result: {
+			...rest,
+			...motivation ? { motivation } : {},
+			questions: withIntentQuestion(result.questions, motivation)
+		},
+		...correction ? { correction } : {}
+	};
+}
+//#endregion
 //#region ../../packages/review-harness/src/domain/ai_review/pipeline.ts
 var STRUCTURED_OUTPUT_INSTRUCTIONS = `In addition to the review principles above, first understand the implementation, then respond with a single JSON object (no markdown, no surrounding text) matching exactly this shape:
 {
   "summary": string,
+  "motivation"?: {
+    "status": "stated" | "inferred" | "unclear",
+    "summary": string,
+    "sourceQuote"?: string,
+    "evidence"?: [{ "kind": "test" | "behaviour" | "issue" | "commit" | "docs" | "code", "detail": string, "file"?: string }],
+    "authorQuestion"?: string
+  },
   "overallRisk": "low" | "medium" | "high",
   "sections": [{
     "id": string,
@@ -9416,6 +9715,11 @@ var STRUCTURED_OUTPUT_INSTRUCTIONS = `In addition to the review principles above
 }
 
 Field guidance:
+- "motivation": WHY this change exists, which is a different question from what it does ("summary" covers that). Name the problem being solved or the goal being served, never the mechanics: "adds a retry loop" is what the code does, "the sync job was failing on transient network errors" is why. Weigh sources in this order: the PR Description and any issue it links; then tests and user-visible behaviour; then commit messages and docs; then the implementation itself. Choose exactly one "status":
+  - "stated": the author's own words in the PR Description say why. "sourceQuote" is REQUIRED: a short passage (one sentence or less, at least three words) copied character for character from the PR Description, which says why. Only the PR Description counts as the author stating it. Never use "stated" when the description only restates what the code does.
+  - "inferred": nothing states it, but the change gives real evidence of it. "evidence" is REQUIRED and non-empty: each entry names what points to the motive, such as a test asserting the fixed behaviour, an issue reference, or a commit message, with "file" set to the changed file it is in where there is one. Never infer a motive from names alone (a branch, a function or a file being called "fix-x" is not evidence). Word the summary as a likely reading, not a fact: "This appears to..." rather than "This fixes...".
+  - "unclear": neither the description nor the change establishes why, AND knowing why would change how this change should be reviewed (for example, whether a behaviour change is intended). "authorQuestion" is REQUIRED: one focused question for the author that would settle it. Do not also ask that question, in any wording, in "questions".
+  If the motive is unclear and knowing it would not change the review, omit "motivation" entirely. Do not add it just to fill the field.
 - "sections": partition the pull request into logical implementation sections (e.g. "Authentication", "Database Migration", "API Changes"), grouped by responsibility/purpose, not by directory or file type. Identify a sensible number of sections — most PRs will naturally have between 2 and 8, but do not invent or split sections simply to reach a target; let the actual structure of the change decide the count. For each section: "oneLineSummary" is a single sentence; "purpose" explains why this part of the change exists; "whyReview" is a short note aimed at the reviewer about what to focus on; "checklist" is a short list of things to verify (review prompts, not findings — never report bugs, code smells, or recommendations inside a section, that's what "issues" is for). Assign "order" starting at 1 in the sequence a reviewer should walk through the sections (narrative order, not file count or alphabetical). "reviewWeight" is a relative time-budget indicator from 1 (skim) to 5 (spend the most time here), independent of "priority" and "reviewAttention". Set "recommendedStartingPoint": true on exactly one section — whichever one a reviewer should actually read first for the rest of the review to make sense. This is not necessarily the section with "order": 1 (e.g. a foundational database migration might naturally come first while a reviewer should still start with the authentication logic it enables). Set it to false on every other section. Every file in the diff must appear in exactly one section — the sections are the only file list the developer sees, so an omitted file is a file they never review. Files with no natural home (lockfiles, dependency bumps, generated output, formatting-only changes) go in a single final catch-all section — title it for what it contains, e.g. "Supporting changes" or "Dependency and config updates" — with "priority": "supporting" and "reviewAttention": "low". Never drop a file just because it is uninteresting; say that it is uninteresting instead.
 - "files" inside a section: "path" is the file path exactly as it appears in the diff. "focus" is REQUIRED on every file — if a file is worth listing in a section, it is worth explaining why the reviewer has been brought to it. Keep it to one or two short sentences, roughly 20-35 words, never more than two sentences. Make it actionable rather than descriptive: name the role this specific file plays in the section, then say what the reviewer should verify there. For example: "Introduces the new association reader. Verify it preserves the existing lookup behaviour." / "Implements the retry path. Confirm error handling matches the existing gateway implementation." / "Registers the generated behaviour with Active Record. Check the hook fires for subclasses too." Do not restate the section's summary or checklist, do not use bullet points, and do not write filler such as "Review this file carefully."
 - "file" on an issue or question: prefer anchoring a finding to the changed file responsible for the concern, named exactly as it appears in the diff. If an unchanged repository file is necessary context and no changed-file location accurately represents the finding, it may be referenced as an unchanged related file. Never list an unchanged file in a section's "files" array, and never describe an unchanged file as part of the pull request.
@@ -9426,7 +9730,7 @@ Field guidance:
 - "existingDiscussion" on an issue: set this only when a thread in the PR DISCUSSION CONTEXT block already raises this same concern, and you have independently confirmed from the diff that it still applies. "threadId" must be copied verbatim from that thread's [T_...] marker — never invent an id, never guess, and omit the field entirely if no thread matches. Set "relation" to "same" when the thread already makes this exact point, or "related" when it discusses this area without covering the finding — a reviewer acts differently on "someone said this already" than on "someone was looking near here". Still write the issue normally; this field only records that the point was raised before, so the reviewer is not shown it as a fresh discovery. Do not use it to pad the review with issues you would otherwise have left out.
 - "confidence" on an issue: how sure you are the issue is real, on the same high/medium/low scale as a question's "importance". This is a separate axis from "severity", which is how much it would matter if real — a critical issue you are unsure about and a nit you are certain of are different things to act on, so do not let one field stand in for the other. Use LOW when you are reasoning from a diff excerpt without the surrounding code, and say what would confirm it in the description. Omit the field rather than guessing a middle value.
 - "questions": each one is a genuine open item the reviewer needs answered before they can sign off, not a rhetorical prompt. "importance" is how much attention it deserves, on the same high/medium/low scale as a section's "reviewAttention" (e.g. a question about a possibly-exposed secret is "high"; a naming preference is "low"). "whyThisMatters" is 1-2 sentences explaining the concrete consequence of the question going unanswered — not a restatement of the question itself.
-- Every section's "oneLineSummary"/"purpose"/"whyReview", each file's "focus", and each question's "whyThisMatters" are rendered as plain prose paragraphs, not markdown — write them as normal sentences. Do not use "- " bullet points or numbered lists inside these fields; if you're enumerating several points, join them into flowing sentences instead. Inline code/identifiers may use backtick spans (e.g. \`ErrorSeverity\`) — those do render.
+- Every section's "oneLineSummary"/"purpose"/"whyReview", each file's "focus", each question's "whyThisMatters", and every text field inside "motivation" are rendered as plain prose paragraphs, not markdown — write them as normal sentences. Do not use "- " bullet points or numbered lists inside these fields; if you're enumerating several points, join them into flowing sentences instead. Inline code/identifiers may use backtick spans (e.g. \`ErrorSeverity\`) — those do render.
 - "summary", "recommendation" and each "nextSteps" entry are rendered as Markdown, so use it where it carries meaning: backtick spans for identifiers, a fenced block for a snippet worth reading as code, a short bullet list where the content genuinely is a list. Prose is still the default and these fields are still short. Do not add headings, and do not turn a paragraph into bullets to look organised.
 
 This JSON object is the only output the developer sees. The free-text sections above (Overview, Guide, Issues, Questions, Follow-up Prompts) are for your own internal reasoning — do not copy them verbatim into any JSON field.`;
@@ -9444,7 +9748,22 @@ function buildStructuredReviewPrompt(pr, options = {}) {
 		partialFiles: partialFiles ?? []
 	};
 }
-function parseReviewResult(raw) {
+/**
+* A reply, parsed, with the motivation checked against the description the analysis read.
+*
+* The check happens here rather than after, so there is no parsed result anywhere whose motivation
+* has not been through it. `correction` says what the check refused, for a caller with an audit to
+* put it in.
+*/
+function parseReviewResponse(raw, authorDescription) {
+	const { result, motivation } = parseUnchecked(raw);
+	const applied = applyMotivation(result, motivation, authorDescription);
+	return {
+		result: applied.result,
+		...applied.correction ? { motivationCorrection: applied.correction } : {}
+	};
+}
+function parseUnchecked(raw) {
 	const jsonText = extractJsonText(raw);
 	let parsed;
 	try {
@@ -9458,14 +9777,17 @@ function parseReviewResult(raw) {
 	const recommendation = asString(obj.recommendation);
 	if (!summary && !recommendation && !Array.isArray(obj.issues) && !Array.isArray(obj.nextSteps)) throw new Error("The AI returned valid JSON, but not in the expected analysis shape (missing summary/recommendation/issues/nextSteps). This usually means the model ignored the requested schema.");
 	return {
-		schemaVersion: 1,
-		summary,
-		overallRisk: RISKS.includes(obj.overallRisk) ? obj.overallRisk : "medium",
-		sections: normalizeSections(obj.sections),
-		issues: normalizeIssues(obj.issues),
-		questions: normalizeQuestions(obj.questions),
-		recommendation,
-		nextSteps: asStringArray(obj.nextSteps)
+		result: {
+			schemaVersion: 1,
+			summary,
+			overallRisk: RISKS.includes(obj.overallRisk) ? obj.overallRisk : "medium",
+			sections: normalizeSections(obj.sections),
+			issues: normalizeIssues(obj.issues),
+			questions: normalizeQuestions(obj.questions),
+			recommendation,
+			nextSteps: asStringArray(obj.nextSteps)
+		},
+		motivation: normalizeMotivation(obj.motivation)
 	};
 }
 var EXPLAIN_SIMPLY_PROMPT = "Explain this review in plain English for someone unfamiliar with this codebase. Avoid jargon, use a simple everyday analogy if it helps, and keep it skippable — a couple of short paragraphs is enough.";
@@ -9836,6 +10158,7 @@ async function assemble(changeSet, budget, lens, prContext) {
 		...changeSet.data,
 		files: selection.inline,
 		changedFileCount: allFiles.length,
+		...prContext ? { pullRequest: pullRequestFor(changeSet.data.pullRequest, prContext) } : {},
 		discussion: prContext?.discussion
 	}, selection.inline.length, null);
 	const shared = {
@@ -9865,6 +10188,21 @@ async function assemble(changeSet, budget, lens, prContext) {
 	};
 }
 /**
+* The change's pull request, as the prompt should present it once a forge request is attached.
+*
+* With no description, the commit subjects stay: they are still the best account of the change
+* there is, and still labelled as commits rather than as the author's words.
+*/
+function pullRequestFor(local, prContext) {
+	const body = prContext.pullRequest.body;
+	if (!body) return local;
+	const { bodySource: _commits, ...rest } = local;
+	return {
+		...rest,
+		body
+	};
+}
+/**
 * The inline patches as one blob, for grounding the assistant.
 *
 * No ceiling of its own. `selectInlineDiffs` already bounded this, and a second constant guarding
@@ -10199,13 +10537,14 @@ async function existingPaths(repoPath, paths, commit = "HEAD") {
 * from the change set, and it costs one git call, or none when the guide cites nothing off-diff.
 */
 async function validateGuide(rawResponse, context) {
-	const result = parseReviewResult(rawResponse);
+	const { result, motivationCorrection } = parseReviewResponse(rawResponse, context.prContext?.pullRequest.body);
 	const changedPaths = new Set(context.changeSet.data.files.map((file) => file.name));
 	const sectionIds = new Set(result.sections.map((section) => section.id));
 	const findings = [...result.issues, ...result.questions];
 	const offDiff = /* @__PURE__ */ new Set();
 	for (const section of result.sections) for (const file of section.files) if (!changedPaths.has(file.path)) offDiff.add(file.path);
 	for (const finding of findings) if (finding.file && !changedPaths.has(finding.file)) offDiff.add(finding.file);
+	for (const evidence of result.motivation?.evidence ?? []) if (evidence.file && !changedPaths.has(evidence.file)) offDiff.add(evidence.file);
 	const realButUnchanged = await existingPaths(context.changeSet.repoPath, [...offDiff]);
 	const unknownPaths = /* @__PURE__ */ new Set();
 	const sectioned = /* @__PURE__ */ new Set();
@@ -10246,6 +10585,13 @@ async function validateGuide(rawResponse, context) {
 			orphanedSectionRefs += 1;
 		}
 	}
+	const placed = placeEvidenceFiles(result.motivation, {
+		changed: (path) => changedPaths.has(path),
+		exists: (path) => realButUnchanged.has(path)
+	});
+	if (placed.motivation) result.motivation = placed.motivation;
+	for (const path of placed.removed) unknownPaths.add(path);
+	for (const evidence of placed.motivation?.evidence ?? []) if (evidence.fileState === "unchanged" && evidence.file) noteReferenced(evidence.file);
 	const attribution = attributeIssuesToDiscussion(result, context.processed.discussion);
 	return {
 		result: attribution.result,
@@ -10253,7 +10599,8 @@ async function validateGuide(rawResponse, context) {
 			unknownPaths: [...unknownPaths].sort(),
 			relocatedFindings,
 			orphanedSectionRefs,
-			rejectedAttributions: attribution.rejected
+			rejectedAttributions: attribution.rejected,
+			...motivationCorrection ? { motivationCorrection } : {}
 		},
 		referencedFiles: [...referenced].map(([path, sections]) => ({
 			path,
@@ -12317,6 +12664,7 @@ function movable(fetched) {
 	};
 	copy("headSha");
 	copy("title");
+	copy("body");
 	copy("filesUrl");
 	copy("fileUrlTemplate");
 	copy("author");
@@ -12526,6 +12874,7 @@ async function reconcile(workspace, runners, reviewedSha, remote, conversationOk
 	const result = {
 		schemaVersion: 1,
 		summary: parsed.summary || previous.summary,
+		...previous.motivation ? { motivation: previous.motivation } : {},
 		overallRisk: parsed.overallRisk ?? previous.overallRisk,
 		recommendation: parsed.recommendation || previous.recommendation,
 		nextSteps: parsed.nextSteps.length ? parsed.nextSteps : previous.nextSteps,
@@ -13084,4 +13433,4 @@ function lineageIds(id) {
 	return [.../* @__PURE__ */ new Set([id, ...lineage.map((review) => review.id)])];
 }
 //#endregion
-export { compactQueue as $, agentById as $n, latestKissRun as $t, createPrState as A, isIssueOutstanding as An, followedBranch as At, toneOf as B, resolveTarget as Bn, phasesFor as Bt, readEvents as C, sectionOf as Cn, claimRequestUrl as Ct, announceJob as D, queueStamp as Dn, fillFileUrlTemplate as Dt, telemetryUploadConsent as E, queueRemove as En, remoteHost as Et, markAllRead as F, processDiscussion as Fn, isTerminal as Ft, extractJsonText as G, resolveModel as Gn, isClaimed as Gt, withUsageRecorded as H, isCommitReview as Hn, purposeOf as Ht, markRead as I, recommendationsOf as In, loadJob as It, readMarker as J, writeAgentPreference as Jn, groupByLineage as Jt, ReviewBeingDeletedError as K, clearAgentPreference as Kn, decideKissRecommendation as Kt, pruneNotifications as L, describeAuthorship as Ln, saveJob as Lt, eventName as M, issuesOutstanding as Mn, allJobs as Mt, headline as N, questionsOutstanding as Nn, endedAt as Nt, branchOf as O, readQueue as On, checkCodeFreshness as Ot, listNotifications as P, reviewerDispositions as Pn, fail as Pt, activateQueued as Q, DEFAULT_AGENT_ID as Qn, kissDecisionsOf as Qt, readNotification as R, WITHHELD_REASON as Rn, PHASES as Rt, startJob as S, parseLifecycle as Sn, writePortPreference as St, recordTelemetryUploadConsent as T, queueAddMany as Tn, forgeFor as Tt, EXPLAIN_SIMPLY_PROMPT as U, git as Un, clearClaim as Ut, unreadCount as V, displayRef as Vn, progressSteps as Vt, asString as W, resolveAgent as Wn, driverGone as Wt, modelHelpLines as X, STORE_ROOT as Xn, indexReviewGroups as Xt, removeWorktree as Y, CONFIG_PATH as Yn, indexKeptIds as Yt, relativeTime as Z, AGENT_IDS as Zn, kissDecisionRefusal as Zt, agentEnvOf as _, isLifecycle as _n, MAX_WORKSPACE_PORT as _t, wasBlocked as a, positionInLineage as an, ensureServer as at, reanalyseReview as b, lifecyclePill as bn, resolveWorkspacePort as bt, RefreshUnavailableError as c, recentWorkspaces as cn, serverEntryExists as ct, refreshPrContext as d, summarise as dn, workspaceUrl as dt, lineageKeyFor as en, agentFor as er, queueForReview as et, isUnchanged as f, touchWorkspace as fn, writeServerRecord as ft, runningJobs as g, activityLabel as gn, DEFAULT_WORKSPACE_PORT as gt, liveUpdateFor as h, LIFECYCLES as hn, feedbackUrl as ht, liveJobsFor as i, mutateWorkspace as in, clearServerRecord as it, createPrUpdate as j, isQuestionOutstanding as jn, reviewedShaOf as jt, subjectOf as k, doneVerb as kn, checkReview as kt, mergeUpdateInto as l, reviewedCommit as ln, spawnServer as lt, UpdateAlreadyRunningError as m, workspaceStamps as mn, PACKAGE_NAME as mt, deleteReview as n, loadWorkspace as nn, AgentCancelledError as nr, readIndexToken as nt, discardJob as o, presentedKissRunOf as on, readServerRecord as ot, askCheckout as p, workspaceRevision as pn, BUILD_VERSION as pt, MANAGED_ROOT as q, readAgentPreference as qn, followedRefName as qt, lineageIds as r, matchingWorkspaceIds as rn, AgentUnavailableError as rr, bootstrapUrl as rt, FETCH_TIMEOUT_MS as s, previousKissResult as sn, reviewsUrl as st, deleteLineage as t, lineagePosition as tn, detectAgents as tr, settleQueue as tt, updateReview as u, reviewedRepositories as un, stopServer as ut, recordKissRun as v, lifecycleAction as vn, MIN_WORKSPACE_PORT as vt, record as w, queueAdd as wn, forgeResolver as wt, runJob as x, offersLifecycle as xn, statedWorkspacePort as xt, startKissJob as y, lifecycleChip as yn, parseWorkspacePort as yt, removeNotification as z, kissOutcome as zn, isLiveJob as zt };
+export { relativeTime as $, AGENT_IDS as $n, kissDecisionRefusal as $t, createPrState as A, readQueue as An, checkCodeFreshness as At, toneOf as B, WITHHELD_REASON as Bn, PHASES as Bt, readEvents as C, offersLifecycle as Cn, statedWorkspacePort as Ct, announceJob as D, queueAddMany as Dn, forgeFor as Dt, telemetryUploadConsent as E, queueAdd as En, forgeResolver as Et, markAllRead as F, questionsOutstanding as Fn, endedAt as Ft, isLongDescription as G, git as Gn, clearClaim as Gt, withUsageRecorded as H, resolveTarget as Hn, phasesFor as Ht, markRead as I, reviewerDispositions as In, fail as It, ReviewBeingDeletedError as J, clearAgentPreference as Jn, decideKissRecommendation as Jt, asString as K, resolveAgent as Kn, driverGone as Kt, pruneNotifications as L, processDiscussion as Ln, isTerminal as Lt, eventName as M, isIssueOutstanding as Mn, followedBranch as Mt, headline as N, isQuestionOutstanding as Nn, reviewedShaOf as Nt, branchOf as O, queueRemove as On, remoteHost as Ot, listNotifications as P, issuesOutstanding as Pn, allJobs as Pt, modelHelpLines as Q, STORE_ROOT as Qn, indexReviewGroups as Qt, readNotification as R, recommendationsOf as Rn, loadJob as Rt, startJob as S, lifecyclePill as Sn, resolveWorkspacePort as St, recordTelemetryUploadConsent as T, sectionOf as Tn, claimRequestUrl as Tt, EXPLAIN_SIMPLY_PROMPT as U, displayRef as Un, progressSteps as Ut, unreadCount as V, kissOutcome as Vn, isLiveJob as Vt, hasAuthorContent as W, isCommitReview as Wn, purposeOf as Wt, readMarker as X, writeAgentPreference as Xn, groupByLineage as Xt, MANAGED_ROOT as Y, readAgentPreference as Yn, followedRefName as Yt, removeWorktree as Z, CONFIG_PATH as Zn, indexKeptIds as Zt, agentEnvOf as _, LIFECYCLES as _n, feedbackUrl as _t, wasBlocked as a, matchingWorkspaceIds as an, AgentUnavailableError as ar, bootstrapUrl as at, reanalyseReview as b, lifecycleAction as bn, MIN_WORKSPACE_PORT as bt, RefreshUnavailableError as c, presentedKissRunOf as cn, readServerRecord as ct, refreshPrContext as d, reviewedCommit as dn, spawnServer as dt, kissDecisionsOf as en, DEFAULT_AGENT_ID as er, activateQueued as et, isUnchanged as f, reviewedRepositories as fn, stopServer as ft, runningJobs as g, workspaceStamps as gn, PACKAGE_NAME as gt, liveUpdateFor as h, workspaceRevision as hn, BUILD_VERSION as ht, liveJobsFor as i, loadWorkspace as in, AgentCancelledError as ir, readIndexToken as it, createPrUpdate as j, doneVerb as jn, checkReview as jt, subjectOf as k, queueStamp as kn, fillFileUrlTemplate as kt, mergeUpdateInto as l, previousKissResult as ln, reviewsUrl as lt, UpdateAlreadyRunningError as m, touchWorkspace as mn, writeServerRecord as mt, deleteReview as n, lineageKeyFor as nn, agentFor as nr, queueForReview as nt, discardJob as o, mutateWorkspace as on, clearServerRecord as ot, askCheckout as p, summarise as pn, workspaceUrl as pt, extractJsonText as q, resolveModel as qn, isClaimed as qt, lineageIds as r, lineagePosition as rn, detectAgents as rr, settleQueue as rt, FETCH_TIMEOUT_MS as s, positionInLineage as sn, ensureServer as st, deleteLineage as t, latestKissRun as tn, agentById as tr, compactQueue as tt, updateReview as u, recentWorkspaces as un, serverEntryExists as ut, recordKissRun as v, activityLabel as vn, DEFAULT_WORKSPACE_PORT as vt, record as w, parseLifecycle as wn, writePortPreference as wt, runJob as x, lifecycleChip as xn, parseWorkspacePort as xt, startKissJob as y, isLifecycle as yn, MAX_WORKSPACE_PORT as yt, removeNotification as z, describeAuthorship as zn, saveJob as zt };

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $n as agentById, Bn as resolveTarget, E as telemetryUploadConsent, Ft as isTerminal, Gn as resolveModel, Gt as isClaimed, Ht as purposeOf, It as loadJob, J as readMarker, Jn as writeAgentPreference, Jt as groupByLineage, Mt as allJobs, Qn as DEFAULT_AGENT_ID, Rn as WITHHELD_REASON, Rt as PHASES, S as startJob, St as writePortPreference, T as recordTelemetryUploadConsent, Un as git, Ut as clearClaim, Vn as displayRef, Vt as progressSteps, Wn as resolveAgent, Wt as driverGone, X as modelHelpLines, Xn as STORE_ROOT, Y as removeWorktree, Yn as CONFIG_PATH, Z as relativeTime, Zn as AGENT_IDS, _t as MAX_WORKSPACE_PORT, a as wasBlocked, an as positionInLineage, at as ensureServer, b as reanalyseReview, cn as recentWorkspaces, dn as summarise, dt as workspaceUrl, en as lineageKeyFor, et as queueForReview, g as runningJobs, gt as DEFAULT_WORKSPACE_PORT, h as liveUpdateFor, i as liveJobsFor, in as mutateWorkspace, kt as checkReview, l as mergeUpdateInto, m as UpdateAlreadyRunningError, mt as PACKAGE_NAME, n as deleteReview$1, nn as loadWorkspace, nt as readIndexToken, pt as BUILD_VERSION, q as MANAGED_ROOT, qn as readAgentPreference, qt as followedRefName, rn as matchingWorkspaceIds, rt as bootstrapUrl, st as reviewsUrl, tr as detectAgents, u as updateReview, un as reviewedRepositories, ut as stopServer, v as recordKissRun, vt as MIN_WORKSPACE_PORT, w as record$1, wt as forgeResolver, x as runJob, xt as statedWorkspacePort, yt as parseWorkspacePort, zn as kissOutcome } from "./delete_review-DMJXD3bf.js";
+import { $ as relativeTime, $n as AGENT_IDS, Bn as WITHHELD_REASON, Bt as PHASES, Ct as statedWorkspacePort, E as telemetryUploadConsent, Et as forgeResolver, Gn as git, Gt as clearClaim, Hn as resolveTarget, Kn as resolveAgent, Kt as driverGone, Lt as isTerminal, Pt as allJobs, Q as modelHelpLines, Qn as STORE_ROOT, Rt as loadJob, S as startJob, T as recordTelemetryUploadConsent, Un as displayRef, Ut as progressSteps, Vn as kissOutcome, Wt as purposeOf, X as readMarker, Xn as writeAgentPreference, Xt as groupByLineage, Y as MANAGED_ROOT, Yn as readAgentPreference, Yt as followedRefName, Z as removeWorktree, Zn as CONFIG_PATH, a as wasBlocked, an as matchingWorkspaceIds, at as bootstrapUrl, b as reanalyseReview, bt as MIN_WORKSPACE_PORT, er as DEFAULT_AGENT_ID, fn as reviewedRepositories, ft as stopServer, g as runningJobs, gt as PACKAGE_NAME, h as liveUpdateFor, ht as BUILD_VERSION, i as liveJobsFor, in as loadWorkspace, it as readIndexToken, jt as checkReview, l as mergeUpdateInto, lt as reviewsUrl, m as UpdateAlreadyRunningError, n as deleteReview$1, nn as lineageKeyFor, nt as queueForReview, on as mutateWorkspace, pn as summarise, pt as workspaceUrl, qn as resolveModel, qt as isClaimed, rr as detectAgents, sn as positionInLineage, st as ensureServer, tr as agentById, u as updateReview, un as recentWorkspaces, v as recordKissRun, vt as DEFAULT_WORKSPACE_PORT, w as record$1, wt as writePortPreference, x as runJob, xt as parseWorkspacePort, yt as MAX_WORKSPACE_PORT } from "./delete_review-B2bqhgtx.js";
 import { basename, dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";