prreviewbuddy 0.91.1 → 0.92.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.92.0
+
+**Older issues catch up on Update.** An issue from an earlier review that is still outstanding now
+gains its summary the next time Update finds new commits or new discussion. The summary is written
+from the evidence the review already holds plus what the update read, and may land in any of the
+four groups. It is a rewording, not a re-check: confidence, severity and the technical account stay
+as they were. Resolved, dismissed and closed issues keep the card they had, and an Update that finds
+nothing new still makes no analysis and changes nothing.
+
+**To fix.** Besides **To verify** and **To decide**, a card can now name the change that would
+correct it, marked **To fix**, when the evidence supports one. The line above the issues counts
+fixes separately. Issues are grouped by what they cause and how well that is shown, never by the
+kind of file: a wrong step in a recovery runbook can be a failure.
+
+**Questions lead with what they mean.** Each question from a new analysis opens with the question in
+plain terms, why the answer matters, and what is needed. The original question, its reasoning and its
+files are under **Technical context** on the card. Answers so far, including a partial one, stay in
+view. Updates keep each question's framing true, restate it to name only what is still open when part
+of it is answered, and write one for an older question still open.
+
+**No leftover notes.** When an update answers a question or changes an issue's status without
+saying anything new about it, the card no longer shows the previous round's note beside the new
+status. Before, a question could read as answered with "this commit did not change it" underneath.
+
+**Quieter cards.** The age of the pull request discussion is one line, "PR discussion checked 2 days
+ago", with its explanation one click away and **Re-check in PR context** beside it. Cards are
+tighter, and **Technical details** shares a row with the card's actions.
+
+For coding agents, `list_findings` and `findings --json` now carry each issue's `confidence` and
+each question's `framing`, and `next.kind` may be `fix`. `get_finding` carries the same, beside the
+original technical text.
+
 ## 0.91.1
 
 **Issues lead with what they mean.** Each issue from a new analysis now opens with its consequence:

package/dist/main.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { $ as readAskRequest, $a as runnableAgents, $i as explanationOf, Aa as TargetError, Ar as attemptIdOf, At as UpdateAlreadyRunningError, Ba as agentIdOf, Bt as append, Da as resolveTarget, Dt as parkedUpdateRefusal, E as relativeTime, Ea as kissOutcome, Er as forgeResolver, F as spawnRunner, Ft as prepareReview, G as reviewTag, Ga as STORE_ROOT, Gr as isClaimed, Gt as recordTelemetryUploadConsent, H as findingRef, Ha as readAgentPreference, Hr as purposeOf, I as applyUpdate, Ia as git, It as settleReview, J as forgetAskRequest, Ji as reviewerDispositions, Jr as followedRefName, Jt as BUILD_VERSION, Ka as AGENT_IDS, Kt as telemetryUploadConsent, L as modelProvenanceOf, Lr as PHASES, Lt as reanalyseReview, Mt as runningJobs, Na as AmbiguousRefError, Nr as isTerminal$1, Nt as failureOf, P as runDetached, Pr as loadJob, Qa as parkedReason, Ra as resolveAgent, T as runBatch, Ta as WITHHELD_REASON, Ua as writeAgentPreference, Ui as isIssueOutstanding, Ur as clearClaim, Ut as stamp, Vr as progressSteps, Wa as CONFIG_PATH, Wi as isQuestionOutstanding, Wr as driverGone, Wt as deliver, Xa as detectAgents, Y as interruption, Ya as agentIdentityOf, Yi as verdictClosure, Yt as PACKAGE_NAME, Z as isTerminalAsk, Za as isAgentId, _t as parseWorkspacePort, at as healthyPort, br as findExistingReview, bt as writePortPreference, ca as findingAssessment, di as reviewedRepositories, dr as MANAGED_ROOT, dt as stopServer, et as recordAskAccepted, fi as summarise, ft as workspaceUrl, gr as removeWorktree, gt as MIN_WORKSPACE_PORT, hr as readMarker, ht as MAX_WORKSPACE_PORT, i as deleteReview$1, ii as matchingWorkspaceIds, it as ensureServer, j as RUNNER_KINDS, jt as liveUpdateFor, k as queueForReview, kr as allJobs, li as recentWorkspaces, mi as workspaceRevision, mt as DEFAULT_WORKSPACE_PORT, ni as lineagePosition, nt as bootstrapUrl, o as liveJobsFor, oi as positionInLineage, ot as readServerRecord, q as endAskRequest, qa as agentById, qt as telemetryUploadEnabled, ri as loadWorkspace, s as wasBlocked, sr as modelHelpLines, st as reviewsUrl, t as MCP_SERVER_INFO_NAME, tt as readIndexToken, u as recordKissRun, ua as findingStatus, ui as reviewedCommit, vr as describeMovement, x as batchIdentity, xt as COMMIT_REVIEW_CANNOT_UPDATE, yr as describeSubject, yt as statedWorkspacePort, za as resolveModel, zt as startJob } from "./mcp_tools-BR7_XprF.js";
+import { $ as readAskRequest, $a as runnableAgents, $i as explanationOf, Aa as TargetError, Ar as attemptIdOf, At as UpdateAlreadyRunningError, Ba as agentIdOf, Bt as append, Da as resolveTarget, Dt as parkedUpdateRefusal, E as relativeTime, Ea as kissOutcome, Er as forgeResolver, F as spawnRunner, Ft as prepareReview, G as reviewTag, Ga as STORE_ROOT, Gr as isClaimed, Gt as recordTelemetryUploadConsent, H as findingRef, Ha as readAgentPreference, Hr as purposeOf, I as applyUpdate, Ia as git, It as settleReview, J as forgetAskRequest, Ji as reviewerDispositions, Jr as followedRefName, Jt as BUILD_VERSION, Ka as AGENT_IDS, Kt as telemetryUploadConsent, L as modelProvenanceOf, Lr as PHASES, Lt as reanalyseReview, Mt as runningJobs, Na as AmbiguousRefError, Nr as isTerminal$1, Nt as failureOf, P as runDetached, Pr as loadJob, Qa as parkedReason, Ra as resolveAgent, T as runBatch, Ta as WITHHELD_REASON, Ua as writeAgentPreference, Ui as isIssueOutstanding, Ur as clearClaim, Ut as stamp, Vr as progressSteps, Wa as CONFIG_PATH, Wi as isQuestionOutstanding, Wr as driverGone, Wt as deliver, Xa as detectAgents, Y as interruption, Ya as agentIdentityOf, Yi as verdictClosure, Yt as PACKAGE_NAME, Z as isTerminalAsk, Za as isAgentId, _t as parseWorkspacePort, at as healthyPort, br as findExistingReview, bt as writePortPreference, ca as findingAssessment, di as reviewedRepositories, dr as MANAGED_ROOT, dt as stopServer, et as recordAskAccepted, fi as summarise, ft as workspaceUrl, gr as removeWorktree, gt as MIN_WORKSPACE_PORT, hr as readMarker, ht as MAX_WORKSPACE_PORT, i as deleteReview$1, ii as matchingWorkspaceIds, it as ensureServer, j as RUNNER_KINDS, jt as liveUpdateFor, k as queueForReview, kr as allJobs, li as recentWorkspaces, mi as workspaceRevision, mt as DEFAULT_WORKSPACE_PORT, ni as lineagePosition, nt as bootstrapUrl, o as liveJobsFor, oi as positionInLineage, ot as readServerRecord, q as endAskRequest, qa as agentById, qt as telemetryUploadEnabled, ri as loadWorkspace, s as wasBlocked, sr as modelHelpLines, st as reviewsUrl, t as MCP_SERVER_INFO_NAME, tt as readIndexToken, u as recordKissRun, ua as findingStatus, ui as reviewedCommit, vr as describeMovement, x as batchIdentity, xt as COMMIT_REVIEW_CANNOT_UPDATE, yr as describeSubject, yt as statedWorkspacePort, za as resolveModel, zt as startJob } from "./mcp_tools-BKPpd9dN.js";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -1051,7 +1051,13 @@ function summaryOf(tag, entry, judge) {
 			...issue.consequence.group ? { group: issue.consequence.group } : {},
 			...issue.consequence.next ? { next: { ...issue.consequence.next } } : {}
 		} } : {},
-		...issue?.resolvedBehaviour && status === "resolved" ? { resolved_behaviour: issue.resolvedBehaviour } : {}
+		...issue?.resolvedBehaviour && status === "resolved" ? { resolved_behaviour: issue.resolvedBehaviour } : {},
+		...issue?.confidence ? { confidence: issue.confidence } : {},
+		...question?.framing ? { framing: {
+			question: question.framing.question,
+			why: question.framing.why,
+			...question.framing.needed ? { needed: question.framing.needed } : {}
+		} } : {}
 	};
 }
 /** A question can run to a paragraph. The list carries its first line; `get_finding` has the rest. */
@@ -1088,7 +1094,6 @@ function detailOf(workspace, tag, entry, judge) {
 			...section ? { title: section.title } : {}
 		} } : {},
 		...finding.relatedFiles?.length ? { related_files: finding.relatedFiles } : {},
-		...issue?.confidence ? { confidence: issue.confidence } : {},
 		...question?.category ? { category: question.category } : {},
 		...issue?.existingDiscussion ? { existing_discussion: {
 			thread_id: issue.existingDiscussion.threadId,

package/dist/{mcp_tools-BR7_XprF.js → mcp_tools-BKPpd9dN.js}

@@ -4213,6 +4213,11 @@ var IMPACT_GROUPS = [
 	"intent",
 	"maintenance"
 ];
+var STEP_KINDS = [
+	"verify",
+	"decide",
+	"fix"
+];
 /**
 * The JSON in a reply, whether or not the model wrapped it in a fence.
 *
@@ -4414,11 +4419,33 @@ function normalizeStep(value) {
 	const item = value;
 	const text = asString$1(item.text).trim();
 	if (!text) return void 0;
-	return item.kind === "verify" || item.kind === "decide" ? {
+	return STEP_KINDS.includes(item.kind) ? {
 		kind: item.kind,
 		text
 	} : { text };
 }
+/**
+* A question's scan-first framing, or nothing.
+*
+* Well-formedness only, the consequence's rule: a framing with no question or no reason has nothing
+* to say and is dropped, so the card shows the original question rather than an empty headline.
+*/
+function normalizeQuestionFraming(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const item = value;
+	const question = asString$1(item.question).trim();
+	const why = asString$1(item.why).trim();
+	if (!question || !why) return void 0;
+	const needed = asString$1(item.needed).trim();
+	return {
+		question,
+		why,
+		...needed ? { needed } : {}
+	};
+}
+function withFraming(framing) {
+	return framing ? { framing } : {};
+}
 /** Spread form, so an issue without one carries no `consequence` key at all. */
 function withConsequence(consequence) {
 	return consequence ? { consequence } : {};
@@ -4449,7 +4476,8 @@ function normalizeQuestions(value) {
 			importance: REVIEW_ATTENTIONS.includes(item.importance) ? item.importance : void 0,
 			whyThisMatters: typeof item.whyThisMatters === "string" ? item.whyThisMatters : void 0,
 			file: typeof item.file === "string" ? item.file : void 0,
-			sectionId: asSectionId(item)
+			sectionId: asSectionId(item),
+			...withFraming(normalizeQuestionFraming(item.framing))
 		};
 	}).filter((question) => question.question.trim() !== "");
 }
@@ -5739,6 +5767,20 @@ function reviewerDispositions(session) {
 		isStale: (issue) => issue.reconciliationStatus === "affected" && (byId.get(issue.id)?.sessionId ?? session.id) !== session.id
 	};
 }
+function framableFindings(session) {
+	const dispositions = reviewerDispositions(session);
+	const answered = new Set(session.answeredQuestionIds ?? []);
+	const verdicts = verdictClosure(session);
+	return {
+		issue: (issue) => isIssueOutstanding(issue, dispositions),
+		question: (question) => isQuestionOutstanding(question, answered, verdicts.question)
+	};
+}
+/** For a caller with no session: nothing may gain framing. */
+var NOTHING_FRAMABLE = {
+	issue: () => false,
+	question: () => false
+};
 /**
 * An issue is done when the commits fixed it, or when the reviewer dismissed it and that decision
 * still stands.
@@ -12557,14 +12599,20 @@ var SUMMARY_GUIDANCE = `"summary": WHAT the change does, for a reviewer about to
 * extension's investigation cannot drift apart. The fragment is the whole shape, never an
 * abbreviation: a model cannot follow a schema it was not shown.
 */
-var CONSEQUENCE_FIELD = "\"consequence\": { \"title\": string, \"scenario\": string, \"group\": \"failure\" | \"risk\" | \"intent\" | \"maintenance\", \"next\"?: { \"kind\": \"verify\" | \"decide\", \"text\": string } }";
+var CONSEQUENCE_FIELD = "\"consequence\": { \"title\": string, \"scenario\": string, \"group\": \"failure\" | \"risk\" | \"intent\" | \"maintenance\", \"next\"?: { \"kind\": \"verify\" | \"decide\" | \"fix\", \"text\": string } }";
 /** The same shape on a prior finding's entry in an update, where null withdraws it and absence keeps it. */
 var CONSEQUENCE_REVISION_FIELD = `${CONSEQUENCE_FIELD.replace("\"consequence\": ", "\"consequence\"?: ")} | null`;
 var CONSEQUENCE_GUIDANCE = `"consequence" on an issue: the same issue told as what it means, for someone who knows the product but may not know its implementation. It is shown first; "title" and "description" stay the technical account behind it. Reframe around the consequence, do not just simplify the technical wording.
   - "title": the observable consequence or the meaningful development constraint, as a short sentence (e.g. "Creating a meal can fail halfway, leaving it outside the planner").
   - "scenario": one or two sentences: the triggering condition and what happens (e.g. "If adding it to the day fails after saving, the user sees an error but the meal still exists. Retrying may then be blocked by its name.").
-  - "next": the one step that would settle it, when there is a specific one. "kind" is "verify" for a check or test that would establish whether it happens (e.g. "Try a receipt with an unreadable amount.") and "decide" for an acceptance or intent call only the reviewer can make (e.g. "Confirm this broader change is intended."). Omit "next" rather than writing a generic step.
-  - "group", by the evidence behind the issue, never by how sure you sound and independently of "severity": "failure" when the code you read establishes an incorrect outcome under a stated condition; "risk" when a plausible undesirable consequence still needs verifying; "intent" when the change has a concrete behavioural consequence whose correctness depends on what was intended; "maintenance" when it constrains future development, maintainability or reliability rather than current behaviour. "confidence" is reported separately and does not decide the group: if the evidence does not establish the failure, it is a "risk", and say what is unverified.
+  - "next": the one specific step this issue calls for, when there is one. "kind" is "verify" for a test or evidence-gathering step that would settle whether it happens (e.g. "Try a receipt with an unreadable amount."), "decide" for an acceptance, requirement or intent call only the reviewer can make (e.g. "Confirm this broader change is intended."), and "fix" for a concrete corrective action the finding itself supports (e.g. "Update the recovery runbook to name the new restore command."). A fix is not a verification: do not label a remedy "verify". Omit "next" rather than write a generic step or invent a remedy the evidence does not support.
+  - "group", by the consequence and the evidence behind it, never by the kind of file, never by how sure you sound and independently of "severity":
+    - "failure" when the evidence you read establishes an incorrect outcome under a stated condition (e.g. "Saving a meal with no ingredients deletes the existing ones.").
+    - "risk" when a plausible adverse consequence still needs verifying (e.g. "Two people editing the same plan at once may overwrite each other; nothing shows whether saves are serialised."), and say what is unverified.
+    - "intent" when there is a concrete behavioural consequence whose acceptability depends on requirements or intent (e.g. "Rotating the sign-in secret now signs every customer out.").
+    - "maintenance" when it constrains future development, maintainability or reliability and no concrete failure or risk fits better (e.g. "Each new payment provider has to be added in four places that must stay in step.").
+    - Documentation, runbooks, configuration and scripts are classified by what they cause like any code: recovery instructions that restore to the wrong database cause an operational failure when the text establishes it, or a risk when unverified. They are not "maintenance" because they are documentation.
+    - "confidence" is reported separately and does not decide the group. A well-evidenced failure stays a failure at medium confidence; a high severity does not make an unverified risk a failure; a low confidence does not by itself turn a failure into a risk.
   - Keep every condition and qualification that affects the decision. Avoid code identifiers unless the consequence cannot be understood without one. Do not state severity.
   - Never claim user harm, a measured performance effect, a reproduction or a certainty the evidence does not give. A performance concern nobody measured says so (e.g. "Opening a meal may do unnecessary work for nested meals... The effect has not been measured."). A maintenance or intent issue is described as one, not as a user-facing failure.
   - An issue names a concrete consequence. A request for missing requirements with no concrete consequence is a question for the author, not an issue, and is never raised as both.`;
@@ -12578,20 +12626,40 @@ var ORIENTATION_GUIDANCE = `"orientation": one sentence, at most about 25 words,
 * consequence that no longer describes the finding is worse than none, so the model is shown each
 * one and must keep, restate or withdraw it.
 */
-var CONSEQUENCE_UPDATE_GUIDANCE = `"consequence" on a finding entry: a finding marked [consequence: ...] has an impact summary the reviewer reads first. Omit "consequence" when it still describes the finding accurately, which is the usual case. Return a restated "consequence" (same shape as on a new issue) when what has changed since alters the condition, the evidence, the next step or the group it describes, most often for an "affected" finding. Return null when it no longer holds and you cannot restate it accurately. Never return "consequence" for a finding without a [consequence: ...] marker.
+var CONSEQUENCE_UPDATE_GUIDANCE = `"consequence" on a finding entry: a finding marked [consequence: ...] has an impact summary the reviewer reads first. Omit "consequence" when it still describes the finding accurately, which is the usual case. Return a restated "consequence" (same shape as on a new issue) when what has changed since alters the condition, the evidence, the next step or the group it describes, most often for an "affected" finding. Return null when it no longer holds and you cannot restate it accurately.
+A finding marked [consequence: none yet, write one] is still outstanding and has no impact summary: unless you mark it "resolved", return a "consequence" for it, written from the evidence its description already gives together with anything these changes show. Classify it into whichever of the four groups that evidence supports; do not default to "risk", and do not demand fresh proof to keep a failure the existing evidence already establishes. Keep its uncertainty as stated: rewording a finding is not re-verifying it, so never describe it as newly confirmed or tested. Never return "consequence" for a finding with neither marker.
 "resolvedBehaviour" on a finding entry: only with "resolved", and only when the changed code shows what now happens under the finding's condition, in one sentence for someone who knows the product (e.g. "If adding the meal to the planner fails, the meal is no longer saved."). Omit it when the code does not show that, and whenever the finding is settled by a comment rather than by code.`;
 /**
 * The impact summary the reviewer reads first, shown under a prior finding so a later pass can keep,
 * restate or withdraw it (`CONSEQUENCE_UPDATE_GUIDANCE`, and the investigation's own rule). Group
-* and step are included: either can go stale on its own. A finding stored without one shows
-* nothing, which is also what tells the model not to add one.
+* and step are included: either can go stale on its own. A finding stored without one is marked
+* as needing one only when the update may add it (`framable`, an outstanding finding); otherwise it
+* shows nothing, which is what tells the model not to add one.
 */
-function formatPriorConsequence(issue) {
+function formatPriorConsequence(issue, framable = false) {
 	const consequence = issue.consequence;
-	if (!consequence) return "";
+	if (!consequence) return framable ? "\n   [consequence: none yet, write one]" : "";
 	const next = consequence.next ? ` Next (${consequence.next.kind ?? "step"}): ${consequence.next.text}` : "";
 	return `\n   [consequence: group ${consequence.group ?? "none"}] ${consequence.title.trim().replace(/[.!?]$/, "")}. ${consequence.scenario.trim()}${next}`;
 }
+/** A question's scan-first framing, as every prompt that asks questions asks for it. The whole shape. */
+var QUESTION_FRAMING_FIELD = "\"framing\": { \"question\": string, \"why\": string, \"needed\"?: string }";
+/** The same shape on a prior question's entry in an update, where null withdraws it and absence keeps it. */
+var QUESTION_FRAMING_REVISION_FIELD = `${QUESTION_FRAMING_FIELD.replace("\"framing\": ", "\"framing\"?: ")} | null`;
+var QUESTION_FRAMING_GUIDANCE = `"framing" on a question: the same question, asked so a reviewer who knows the product but not the code can see at a glance what is being asked and why. It is shown first; the original "question" and "whyThisMatters" stay the technical account behind it. It is a presentation of this question, never a second one.
+  - "question": short, at product or operations level (e.g. "Should rotating the sign-in secret require all customers to sign in again?").
+  - "why": one or two sentences on why the answer matters, keeping every condition and uncertainty (e.g. "The current encryption ties stored sessions to that secret."). A conditional premise stays conditional: do not turn "if" into a fact.
+  - "needed": the specific answer or confirmation required, when the question does not already make it plain (e.g. "Confirm whether this consequence is acceptable and documented."). Omit it otherwise.
+  - A question with several parts names every part, so none is lost from view. Do not answer the question in its framing.`;
+var QUESTION_FRAMING_UPDATE_GUIDANCE = `"framing" on a question entry: a question marked [framing: ...] has a short framing the reviewer reads first. Omit "framing" when it still describes the question accurately. Return a restated "framing" (same shape as on a new question) when these changes alter what is being asked, its condition or what is needed; in particular, when you mark a question "answered" or the changes answer part of it, restate it to name only what is still open, or return null if nothing in it still needs asking. Return null when it no longer holds and you cannot restate it.
+A question marked [framing: none yet, write one] is still outstanding and has no framing: unless you mark it "answered", return a "framing" for it from what the question and its reasons already say together with anything these changes show, keeping its conditions and uncertainty. Never return "framing" for a question with neither marker.`;
+/** A prior question's framing, or the marker asking for one, as the update shows it. */
+function formatPriorFraming(question, framable = false) {
+	const framing = question.framing;
+	if (!framing) return framable ? "\n   [framing: none yet, write one]" : "";
+	const needed = framing.needed ? ` Needed: ${framing.needed.trim()}` : "";
+	return `\n   [framing] ${framing.question.trim()} ${framing.why.trim()}${needed}`;
+}
 //#endregion
 //#region ../../packages/review-harness/src/domain/discussion/discussion_delta.ts
 /**
@@ -13371,7 +13439,7 @@ var STRUCTURED_OUTPUT_INSTRUCTIONS = `In addition to the review principles above
     "recommendedStartingPoint": boolean
   }],
   "issues": [{ "id": string, "severity": "critical" | "major" | "minor" | "nit", "title": string, "description": string, "file"?: string, "line"?: number, "sectionId"?: string, "confidence"?: "high" | "medium" | "low", ${CONSEQUENCE_FIELD}, "existingDiscussion"?: { "threadId": string, "relation": "same" | "related" } }],
-  "questions": [{ "id": string, "question": string, "importance"?: "high" | "medium" | "low", "whyThisMatters"?: string, "file"?: string, "sectionId"?: string }],
+  "questions": [{ "id": string, "question": string, "importance"?: "high" | "medium" | "low", "whyThisMatters"?: string, ${QUESTION_FRAMING_FIELD}, "file"?: string, "sectionId"?: string }],
   "recommendation": string,
   "nextSteps": string[]
 }
@@ -13391,6 +13459,7 @@ Field guidance:
 - "nextSteps": concrete actions to take before merging (specific tests to run, files to double-check), not a restatement of the Guide.
 - "issues": report only issues worth the reviewer's attention — do not invent issues to fill out the array, and do not omit significant issues. Let the count reflect the actual PR (a trivial PR may have zero or one issue; a large or risky PR may have several).
 - ${CONSEQUENCE_GUIDANCE}
+- ${QUESTION_FRAMING_GUIDANCE}
 - ${ORIENTATION_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.
@@ -18089,13 +18158,13 @@ function priorFindingVerdict(issue, flag) {
 * reviewer may have moved it, and a model told only the analysis's grade would re-judge from where
 * the review no longer stands. A caller with no ledger passes `ANALYSIS_ONLY`.
 */
-function formatPriorFindings(issues, assess, reassess = /* @__PURE__ */ new Map(), status = NO_STATUS) {
+function formatPriorFindings(issues, assess, reassess = /* @__PURE__ */ new Map(), status = NO_STATUS, framable = NOTHING_FRAMABLE) {
 	if (!issues.length) return "(The previous analysis raised no issues.)";
 	return issues.map((issue, index) => {
 		const related = (issue.relatedFiles ?? []).map((file) => ` [related: ${file}, not changed]`).join("");
 		const location = (issue.file ? ` [${issue.file}${issue.line ? `:${issue.line}` : ""}]` : "") + related;
 		const description = issue.description.trim();
-		return `${index}. (${promptGrade(assess("issue", issue))})${location}${priorFindingVerdict(issue, reassess.get(index))}${acceptedVerdict(status("issue", issue.id))} ${issue.title.trim()}${description ? `\n   ${description}` : ""}${formatPriorConsequence(issue)}`;
+		return `${index}. (${promptGrade(assess("issue", issue))})${location}${priorFindingVerdict(issue, reassess.get(index))}${acceptedVerdict(status("issue", issue.id))} ${issue.title.trim()}${description ? `\n   ${description}` : ""}${formatPriorConsequence(issue, framable.issue(issue))}`;
 	}).join("\n");
 }
 /**
@@ -18104,7 +18173,7 @@ function formatPriorFindings(issues, assess, reassess = /* @__PURE__ */ new Map(
 * of the issue shape returned issues with no severity, no file and in some cases no content.
 * Keep in step with STRUCTURED_OUTPUT_INSTRUCTIONS in pipeline.ts.
 */
-var QUESTION_SHAPE_LINE = "  \"questions\": [{ \"sourceIndex\": number, \"status\": \"answered\" | \"still-open\" | \"affected\", \"answer\"?: string, \"note\"?: string, \"importance\"?: \"high\" | \"medium\" | \"low\", \"importanceReason\"?: string }],";
+var QUESTION_SHAPE_LINE = `  "questions": [{ "sourceIndex": number, "status": "answered" | "still-open" | "affected", "answer"?: string, "note"?: string, ${QUESTION_FRAMING_REVISION_FIELD}, "importance"?: "high" | "medium" | "low", "importanceReason"?: string }],`;
 var RECONCILIATION_SHAPE = `{
   "findings": [{ "sourceIndex": number, "status": "resolved" | "still-open" | "affected", "note"?: string, ${CONSEQUENCE_REVISION_FIELD}, "resolvedBehaviour"?: string, "severity"?: "critical" | "major" | "minor" | "nit", "severityReason"?: string }],
   "newIssues": [{ "id": string, "severity": "critical" | "major" | "minor" | "nit", "title": string, "description": string, "file"?: string, "line"?: number, ${CONSEQUENCE_FIELD}, "confidence"?: "high" | "medium" | "low" }],
@@ -18150,7 +18219,7 @@ function reconciliationShape(includeQuestions, withDiscussion = false) {
 * question's own id is withheld so it cannot be echoed back in place of an index, and enough
 * context travels for a judgement without inviting a rewrite of the question itself.
 */
-function formatPriorQuestions(questions, assess, status = NO_STATUS) {
+function formatPriorQuestions(questions, assess, status = NO_STATUS, framable = NOTHING_FRAMABLE) {
 	if (!questions.length) return "(The previous analysis raised no questions.)";
 	return questions.map((question, index) => {
 		const related = (question.relatedFiles ?? []).map((file) => ` [related: ${file}, not changed]`).join("");
@@ -18159,7 +18228,7 @@ function formatPriorQuestions(questions, assess, status = NO_STATUS) {
 		const verdict = alreadyAnswered(question) ? " [previously: answered]" : priorVerdict(question);
 		const assessment = assess("question", question);
 		const importance = assessment.current ? ` [importance: ${promptGrade(assessment)}]` : "";
-		return `${index}.${location}${verdict}${acceptedVerdict(status("question", question.id))}${importance} ${question.question.trim()}${why ? `\n   ${why}` : ""}`;
+		return `${index}.${location}${verdict}${acceptedVerdict(status("question", question.id))}${importance} ${question.question.trim()}${why ? `\n   ${why}` : ""}${formatPriorFraming(question, framable.question(question))}`;
 	}).join("\n");
 }
 /**
@@ -18240,7 +18309,7 @@ function buildReconciliationInstructions(input, options = {}) {
 	const discussion = options.discussion;
 	const conversationOnly = discussion !== void 0 && !discussion.codeChanged;
 	const truncationWarning = possiblyTruncated ? `\n\nIMPORTANT: the list of changes above is INCOMPLETE — more files changed than could be retrieved. Do not mark a previous finding "resolved" on the strength of absence: a file you cannot see may or may not contain the fix. Prefer "still-open" or "affected" where you cannot see the relevant code, and say so in the note.` : "";
-	const questionList = includeQuestions ? `\n\nPrevious open questions, numbered — refer to each by its number in "sourceIndex":\n${formatPriorQuestions(previous.questions, input.assess, input.status)}` : "";
+	const questionList = includeQuestions ? `\n\nPrevious open questions, numbered — refer to each by its number in "sourceIndex":\n${formatPriorQuestions(previous.questions, input.assess, input.status, input.framable)}` : "";
 	const tasks = [
 		`${discussion ? `For EVERY numbered finding above, decide what ${conversationOnly ? "the changes in the conversation" : "the new commits and the changes in the conversation"} did to it:
    - "resolved": ${conversationOnly ? "" : "the new commits fix it, and you can point at the change that does so; or "}the conversation gives evidence that invalidates its premise, under the rules below.
@@ -18278,7 +18347,7 @@ Overall risk: ${previous.overallRisk}
 Recommendation: ${previous.recommendation}
 
 Previous findings, numbered — refer to each by its number in "sourceIndex":
-${formatPriorFindings(previous.issues, input.assess, reassess, input.status)}${questionList}${truncationWarning}
+${formatPriorFindings(previous.issues, input.assess, reassess, input.status, input.framable)}${questionList}${truncationWarning}
 ${discussion ? `\n${DISCUSSION_RULES}\n` : ""}
 YOUR TASK
 
@@ -18292,7 +18361,7 @@ ${reconciliationShape(includeQuestions, discussion !== void 0)}
 ${CONSEQUENCE_UPDATE_GUIDANCE}
 
 ${CONSEQUENCE_GUIDANCE}
-
+${includeQuestions ? `\n${QUESTION_FRAMING_UPDATE_GUIDANCE}\n\n${QUESTION_FRAMING_GUIDANCE}\n` : ""}
 "severity" on a new issue is how much it would matter if real; "confidence" is how sure you are that it is real. Separate axes — do not let one stand in for the other, and omit "confidence" rather than guessing a middle. Report only what is worth the reviewer's attention: empty arrays are valid answers and are far better than padded ones.`;
 }
 /**
@@ -18454,14 +18523,14 @@ function parseReconciliationResult(raw, priorCount, options = {}) {
 * Every prior finding therefore survives into the new result, in its original order, carrying its
 * original id, severity and text. Only the status is added.
 */
-function reconcileIssues(prior, findings, record) {
+function reconcileIssues(prior, findings, record, framable = NOTHING_FRAMABLE) {
 	const byIndex = new Map(findings.map((f) => [f.sourceIndex, f]));
 	return prior.map((issue, index) => {
 		const verdict = byIndex.get(index);
 		const flag = issue.reconciliationStatus === "resolved" ? record?.flags?.get(index) : void 0;
 		if (flag && record) {
 			const entry = reassessedEntry(verdict, flag, record);
-			const { resolvedBehaviour: _reopened, ...reassessed } = withRevisedConsequence(issue, verdict);
+			const { resolvedBehaviour: _reopened, ...reassessed } = withRevisedConsequence(issue, verdict, false);
 			return {
 				...reassessed,
 				reconciliationStatus: entry.status,
@@ -18474,26 +18543,45 @@ function reconcileIssues(prior, findings, record) {
 		const status = verdict?.status ?? "still-open";
 		const recorded = record && isStatusChange(issue.reconciliationStatus, status) ? { statusHistory: appendStatusChange(issue, changeEntry(status, verdict, record)) } : {};
 		const fixedInCode = status === "resolved" && !verdict?.evidence && record?.basis !== "conversation";
-		const { resolvedBehaviour: _previous, ...current } = withRevisedConsequence(issue, verdict);
+		const { resolvedBehaviour: _previous, ...current } = withRevisedConsequence(issue, verdict, status !== "resolved" && framable.issue(issue));
 		return {
-			...current,
+			...withNote(current, verdict?.note, isStatusChange(issue.reconciliationStatus, status)),
 			...fixedInCode && verdict?.resolvedBehaviour ? { resolvedBehaviour: verdict.resolvedBehaviour } : {},
 			reconciliationStatus: status,
-			...verdict?.note ? { reconciliationNote: verdict.note } : {},
 			...recorded,
 			...record?.against ? { reconciledAgainst: verdict?.evidence ? "conversation" : record.against } : {}
 		};
 	});
 }
 /**
-* The issue with its consequence kept, restated or withdrawn, as the update said.
+* The finding with the note this round gave, or the one it had. A note argues for the status it was
+* written with, so silence keeps it only while that status holds: one this round changed leaves it
+* behind, where it would contradict the new status on the card.
+*/
+function withNote(finding, note, statusChanged) {
+	if (note) return {
+		...finding,
+		reconciliationNote: note
+	};
+	if (!statusChanged) return finding;
+	const { reconciliationNote: _superseded, ...rest } = finding;
+	return rest;
+}
+/**
+* The issue with its consequence kept, restated, withdrawn or added, as the update said.
 *
-* Only for an issue that already had one. An update is never the place a historical issue gains
-* an impact summary it was not written with, so an answer for one without is ignored. Silence
-* keeps it: the model was shown it and asked to change it only where it no longer holds.
+* Silence keeps it: the model was shown it and asked to change it only where it no longer holds.
+* An issue stored without one gains the one offered only when `mayFrame`: it is still outstanding
+* after this update, so the card the reviewer is about to work from becomes scan-first. A resolved,
+* dismissed or verdict-closed issue is never given presentation it was not written with, and a
+* `null` for an issue that has nothing to withdraw changes nothing.
 */
-function withRevisedConsequence(issue, verdict) {
-	if (!issue.consequence || verdict?.consequence === void 0) return issue;
+function withRevisedConsequence(issue, verdict, mayFrame) {
+	if (verdict?.consequence === void 0) return issue;
+	if (!issue.consequence) return mayFrame && verdict.consequence ? {
+		...issue,
+		consequence: verdict.consequence
+	} : issue;
 	if (verdict.consequence === null) {
 		const { consequence: _withdrawn, ...rest } = issue;
 		return rest;
@@ -18526,10 +18614,12 @@ function parseQuestions(value, priorCount) {
 		const note = asString$1(item.note).trim();
 		const answer = asString$1(item.answer).trim();
 		const grade = parseGrade("question", item.importance, item.importanceReason);
+		const framing = item.framing === null ? null : normalizeQuestionFraming(item.framing);
 		questions.push({
 			sourceIndex,
 			status,
 			...note ? { note } : {},
+			...framing !== void 0 ? { framing } : {},
 			...status === "answered" && answer ? { answer } : {},
 			...grade ? { grade: {
 				to: grade.to,
@@ -18564,7 +18654,7 @@ function parseQuestions(value, priorCount) {
 function alreadyAnswered(question) {
 	return question.reconciliationStatus === "answered" || question.reconciliationAnswer !== void 0;
 }
-function reconcileQuestions(prior, reconciled, against) {
+function reconcileQuestions(prior, reconciled, against, framable = NOTHING_FRAMABLE) {
 	const recorded = against ? { reconciledAgainst: against } : {};
 	const byIndex = new Map(reconciled.map((entry) => [entry.sourceIndex, entry]));
 	return prior.map((question, index) => {
@@ -18580,15 +18670,35 @@ function reconcileQuestions(prior, reconciled, against) {
 		};
 		const answered = verdict.status === "answered" && verdict.answer !== void 0;
 		const status = verdict.status !== "answered" ? verdict.status : answered ? "answered" : "affected";
+		const changed = (question.reconciliationStatus ?? "still-open") !== status;
 		return {
-			...question,
+			...withNote(withRevisedFraming(question, verdict, status !== "answered" && framable.question(question)), verdict.note, changed),
 			reconciliationStatus: status,
-			...verdict.note ? { reconciliationNote: verdict.note } : {},
 			...answered ? { reconciliationAnswer: verdict.answer } : {},
 			...recorded
 		};
 	});
 }
+/**
+* The question with its framing kept, restated, withdrawn or added: `withRevisedConsequence`'s rule.
+* A framed question is revised whatever its new status, because an answer is exactly what can make
+* its "needed" line stale; an unframed one gains a framing only while it is still outstanding.
+*/
+function withRevisedFraming(question, verdict, mayFrame) {
+	if (verdict.framing === void 0) return question;
+	if (!question.framing) return mayFrame && verdict.framing ? {
+		...question,
+		framing: verdict.framing
+	} : question;
+	if (verdict.framing === null) {
+		const { framing: _withdrawn, ...rest } = question;
+		return rest;
+	}
+	return {
+		...question,
+		framing: verdict.framing
+	};
+}
 /** Marks a reconciliation's own findings as new, so the UI can tell them from carried-forward ones. */
 function markNewIssues(issues, against) {
 	return issues.map((issue) => ({
@@ -18691,8 +18801,8 @@ function applyReconciliation(previous, parsed, context) {
 		basis: context.codeChanged ? "code" : "conversation",
 		flags,
 		against
-	}), ...markNewIssues(parsed.newIssues, against)];
-	const questions = reconcileQuestions(previous.questions, parsed.questions, against);
+	}, context.framable), ...markNewIssues(parsed.newIssues, against)];
+	const questions = reconcileQuestions(previous.questions, parsed.questions, against, context.framable);
 	const { motivation } = context;
 	const composed = {
 		schemaVersion: 1,
@@ -19132,7 +19242,8 @@ async function reconcile(workspace, runners, reviewedSha, remote, conversationOk
 		codeChanged: delta !== null,
 		conversation: prepared,
 		assess: assessmentLookup(workspace.session),
-		motivation
+		motivation,
+		framable: framableFindings(workspace.session)
 	});
 	signal.throwIfAborted();
 	cancellers.delete(jobId);
@@ -19641,6 +19752,7 @@ ${buildReconciliationInstructions({
 		previous,
 		assess: assessmentLookup(workspace.session),
 		status: statusLookup(workspace.session),
+		framable: framableFindings(workspace.session),
 		fromSha: reviewedSha,
 		toSha: newHead,
 		totalCommits: commits,