pi-pr-review 1.12.2 → 1.13.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.13.0](https://github.com/10ego/pi-pr-review/compare/v1.12.3...v1.13.0) (2026-08-20)
+
+
+### Features
+
+* **review:** render degraded syntheses as readable generic reviews ([#69](https://github.com/10ego/pi-pr-review/issues/69)) ([ee80cde](https://github.com/10ego/pi-pr-review/commit/ee80cdea6cddfd580a68bd6ab71b9625a1e06127))
+
+## [1.12.3](https://github.com/10ego/pi-pr-review/compare/v1.12.2...v1.12.3) (2026-08-19)
+
+
+### Bug Fixes
+
+* **review:** make host lane truth authoritative for completeness ([#67](https://github.com/10ego/pi-pr-review/issues/67)) ([ad70fc3](https://github.com/10ego/pi-pr-review/commit/ad70fc3b6376f215bf045b980fef06bd87036bd1))
+
 ## [1.12.2](https://github.com/10ego/pi-pr-review/compare/v1.12.1...v1.12.2) (2026-08-19)
 
 

package/README.md

@@ -176,7 +176,7 @@ Every invocation has a host-owned monotonic 15-minute hard cap, including the tw
 
 A timed-out or retryable quota/rate-limit/capacity lane may start at most one configured fallback attempt. It starts only when at least `minimumFallbackMs` plus cleanup reserve remains; the host never changes the configured model, thinking level, or tool policy to save time. If a tier is unset, its existing nearest-configured-tier/Pi-default behavior is unchanged.
 
-On an attempt deadline the host records timeout separately from user cancellation, sends TERM to the original child, waits only `terminationGraceMs`, then sends KILL if no exit was observed and stops draining after the cleanup reserve. Partial assistant text and telemetry survive this lifecycle. The synthesis cap arms only once review work goes quiet: any turn that starts or any review tool that runs again while the cap is armed defers it, and it re-arms from the next turn end, so early review-tool turns (for example verification discovery) cannot starve later heavy lanes. Batch/total expiry stops queued work and waiting lanes; completed and partial artifacts proceed to Markdown synthesis or deterministic lane assembly, identify every incomplete lens/shard, and remain eligible for the safe body-only `COMMENT` publication path. A timed-out lane is never reported as `NO FINDINGS` or full coverage, and a lane ended by the host total or synthesis deadline is disclosed with that kind (`deadline_expired`) instead of being mistaken for its own attempt deadline expiring.
+On an attempt deadline the host records timeout separately from user cancellation, sends TERM to the original child, waits only `terminationGraceMs`, then sends KILL if no exit was observed and stops draining after the cleanup reserve. Partial assistant text and telemetry survive this lifecycle. The synthesis cap arms only once review work goes quiet: any turn that starts or any review tool that runs again while the cap is armed defers it, and it re-arms from the next turn end, so early review-tool turns (for example verification discovery) cannot starve later heavy lanes. Batch/total expiry stops queued work and waiting lanes; completed and partial artifacts proceed to Markdown synthesis or deterministic lane assembly, identify every incomplete lens/shard, and remain eligible for the safe body-only `COMMENT` publication path. A timed-out lane is never reported as `NO FINDINGS` or full coverage, and a lane ended by the host total or synthesis deadline is disclosed with that kind (`deadline_expired`) instead of being mistaken for its own attempt deadline expiring. Host lane artifacts are authoritative for completeness in both directions: a false assistant completion claim cannot upgrade incomplete lanes, and a paraphrased or omitted `Lane completeness` line cannot downgrade a host-complete batch away from the concise renderer.
 
 Initial operating targets are ordinary-review p50 ≤ 6 minutes and p95 ≤ 12 minutes, and large-review p50 ≤ 10 minutes and p95 ≤ 14 minutes, with the 15-minute hard cap authoritative. Invocation telemetry starts before GitHub preflight and records configured deadline source/caps, termination grace, cleanup reserve, and active wall time; batch details record first event/output timing, lifecycle counts, configured and effective batch-truncated attempt deadlines, fallback starts/budget rejections, external total/synthesis deadline expiries per lane, and termination grace/escalation data. These are initial production targets, not a promise that every provider completes before its host deadline.
 
@@ -208,13 +208,13 @@ Publishing is off by default.
 
 The extension owns normal publishing. Before review execution it captures repository, hostname, PR number/title, reviewed head, lifecycle state, posting/stale authority, and invocation identity independently of assistant text. After synthesis, it caches one validated completed review (the host-owned canonical artifact) per repository and PR in the current Pi session. `autoPostReviews` and `--comment` publish that cached review after completion; `--no-comment` suppresses publication for the run.
 
-Review semantics are Markdown-first. A deterministic tolerant parser normalizes line endings, extracts complete findings when possible, and ignores heading-like text inside CommonMark fenced-code and HTML-block contexts. Ambiguous or partially parsed output preserves the complete original synthesis in one sanitized body-only `COMMENT`; completely malformed synthesis does the same, and absent synthesis becomes a deterministic body-only review assembled from retained complete/partial/failed lane artifacts. Reserved markers are sanitized, size limits are enforced, and the canonical marker is appended only by host code. Optional formatting repair is never required and can never suppress the raw fallback.
+Review semantics are Markdown-first. A deterministic tolerant parser normalizes line endings, extracts complete findings when possible, and ignores heading-like text inside CommonMark fenced-code and HTML-block contexts. Every degraded synthesis — ambiguous, partially parsed, incomplete lane coverage, or absent terminal synthesis — publishes one deterministic host-rendered `COMMENT` body with generic code-review labels: a `Coverage` section with the exact lane lifecycle disclosure, a `Findings` section with host-formatted parsed findings (never a clean-review claim when nothing parsed), and the complete original synthesis plus every retained lane artifact preserved verbatim under `Retained synthesis` / `Retained lane output` with heading levels shifted so they nest. A contradictory completion claim inside retained text is reconciled to the host verdict. Reserved markers are sanitized, size limits are enforced, and the canonical marker is appended only by host code. Optional formatting repair is never required and can never suppress the degraded fallback.
 
 You can publish the cache later with `/pr-review-publish 123`, or directly ask the agent to “post the inline review,” “post it as an inline review,” or “publish the review for PR #123.” The extension handles that request directly before an agent turn. `/pr-review-publish` and a matching direct request publish only the cache; they never start or rerun review agents. Unnumbered direct requests select the latest cached review for the current repository. Only fresh interactive/RPC input can use the direct path.
 
-Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; it never submits `REQUEST_CHANGES` or retries a rejected write with a fallback POST. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch and a standalone visible `All requested lanes completed.` disclosure (matched case-insensitively, with an optional final period) may emit a gated `APPROVE` through the same host binding, priority, lifecycle, self-author, and stale checks as strict JSON. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, partial or contradictory lane disclosures, malformed or unsafe output, and lane-fallback artifacts remain body-only `COMMENT` reviews. Cache restore reclassifies persisted lane output and requires the exact host-recorded artifact key set, with every complete artifact matching the frozen invocation generation, tier, and minor-hygiene contract, and re-synthesizes the retained raw text under that frozen binding before retaining approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The concise top-level body starts with the verdict, points readers to inline findings, and places nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow under `Other Notes`; overview, verification, strengths, and transport diagnostics stay out of the public summary. The complete original Markdown remains retained internally; if the concise body plus its canonical marker exceeds GitHub's limit, the host uses its sanitized, size-bounded Markdown projection instead of dropping the review. Stale or authorized non-open reviews are body-only. A stale approval additionally requires `allowStaleApprovals: true`.
+Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; it never submits `REQUEST_CHANGES` or retries a rejected write with a fallback POST. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch may emit a gated `APPROVE` through the same host binding, priority, lifecycle, self-author, and stale checks as strict JSON. Host lane evidence is authoritative for completeness: a paraphrased or omitted `All requested lanes completed.` disclosure cannot downgrade a host-complete batch, and a false disclosure cannot upgrade incomplete or missing lane coverage; the assistant's canonical line is consulted only when no batch evidence exists. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, incomplete or missing host lane coverage, malformed or unsafe output, and lane-fallback artifacts remain `COMMENT` reviews; their safely parsed findings keep inline placement, while unparsable output publishes body-only. Cache restore reclassifies persisted lane output and requires the exact host-recorded artifact key set, with every complete artifact matching the frozen invocation generation, tier, and minor-hygiene contract, and re-synthesizes the retained raw text under that frozen binding before retaining approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The concise top-level body starts with the verdict, points readers to inline findings, and places nits, off-diff findings, unavailable diff metadata, duplicate anchors, and overflow under `Other Notes`; overview, verification, strengths, and transport diagnostics stay out of the public summary. The complete original Markdown remains retained internally; if the concise body plus its canonical marker exceeds GitHub's limit, the host uses its sanitized, size-bounded Markdown projection instead of dropping the review. Stale or authorized non-open reviews are body-only. A stale approval additionally requires `allowStaleApprovals: true`.
 
-All publication paths apply host-enforced safety gates: captured posting authority, repository and requested-PR binding, reviewed/current-head and stale policy, bounded bodies and payloads, draft and lifecycle checks, non-open authorization, authenticated-identity same-head duplicate detection, and a final head check. Fully or partially parsed review paths additionally enforce safe inline locations. Raw and lane-assembled fallbacks are body-only and `COMMENT`-only; assistant text cannot select event, commit, repository, hostname, API path, or inline anchors. Unknown or invalid host states fail closed before a write.
+All publication paths apply host-enforced safety gates: captured posting authority, repository and requested-PR binding, reviewed/current-head and stale policy, bounded bodies and payloads, draft and lifecycle checks, non-open authorization, authenticated-identity same-head duplicate detection, and a final head check. Fully or partially parsed review paths additionally enforce safe inline locations, including degraded incomplete-lane reviews whose findings still parse. Raw and lane-assembled fallbacks without parsed findings are body-only; every degraded path is `COMMENT`-only, and assistant text cannot select event, commit, repository, hostname, API path, or inline anchors. Unknown or invalid host states fail closed before a write.
 
 Stale publication is enabled by default through `allowStalePublish: true`; disable it with `/pr-review-config allow_stale_publish=false`. Automatic posting and `/pr-review-publish` use the setting captured when the review starts unless the command supplies the explicit override:
 

package/extensions/review-table.ts

@@ -47,7 +47,7 @@ import {
 	type CompletedReviewSessionIdentity,
 	type ReviewInvocation,
 } from "../lib/pr-review-publish.ts";
-import { safeReviewBody, synthesizeReviewArtifact, type ReviewSynthesisArtifact } from "../lib/pr-review-markdown.ts";
+import { demoteHeadings, safeReviewBody, synthesizeReviewArtifact, type ReviewSynthesisArtifact } from "../lib/pr-review-markdown.ts";
 import { resolveReviewDeadlinesForContext } from "../lib/pr-review-deadline-config.ts";
 import { createReviewBudget } from "../lib/pr-review-deadlines.ts";
 import {
@@ -269,6 +269,18 @@ function verdictLine(r: Review): string {
 	return parts.join(" ");
 }
 
+export function renderDegradedReviewMarkdown(r: Review, body: string): string {
+	const out: string[] = [];
+	const num = r.pr?.number;
+	const title = (r.pr?.title ?? "").toString().replace(/\r?\n/g, " ").trim();
+	if (num != null) out.push(`## Code Review — PR #${num}${title ? `: ${title}` : ""}`, "");
+	else out.push("## Code Review", "");
+	// The host-built degraded body already carries verdict, coverage, findings,
+	// and every retained artifact; demote it under the render header.
+	out.push(demoteHeadings(body.trim()), "");
+	return out.join("\n").trimEnd();
+}
+
 function renderReviewMarkdown(r: Review): string {
 	const out: string[] = [];
 
@@ -440,8 +452,11 @@ async function publishCompletedReview(
 		...(record.synthesisQuality === "fully_parsed" && typeof record.rawText === "string" && record.rawText.trim()
 			? { fallbackPublicationBody: safeReviewBody(record.rawText) }
 			: {}),
+		// A degraded synthesis stays COMMENT-only, but its safely parsed findings
+		// still earn inline placement; only unparsable output is forced body-only.
 		forceBodyOnly: record.synthesisQuality !== undefined &&
-			(record.synthesisQuality !== "fully_parsed" || record.completeness === "incomplete"),
+			record.synthesisQuality !== "fully_parsed" &&
+			!(Array.isArray(record.review.findings) && record.review.findings.length > 0),
 		// A publication body identifies Markdown-derived or degraded synthesis.
 		// Enforce COMMENT again at the final publication boundary so restored
 		// canonical artifacts created by an older parser cannot inherit APPROVE.
@@ -935,10 +950,14 @@ export default function registerReviewTable(
 		// Keep the raw assistant response for automation; only prettify interactive TUI output.
 		if (ctx.mode !== "tui") return;
 		const nonText = event.message.content.filter((part) => part.type !== "text");
+		const degradedBody = artifact && artifact.quality !== "fully_parsed" ? artifact.body : undefined;
 		return {
 			message: {
 				...event.message,
-				content: [...nonText, { type: "text", text: renderReviewMarkdown(review) }],
+				content: [...nonText, {
+					type: "text",
+					text: degradedBody ? renderDegradedReviewMarkdown(review, degradedBody) : renderReviewMarkdown(review),
+				}],
 			},
 		};
 	});

package/lib/pr-review-markdown.ts

@@ -520,65 +520,156 @@ function incompleteLaneDisclosure(lanes: readonly ReviewLaneArtifact[]): string
 	].join("\n");
 }
 
-function bindIncompleteLaneDisclosure(raw: string, lanes: readonly ReviewLaneArtifact[]): string {
-	const disclosure = incompleteLaneDisclosure(lanes);
-	if (!disclosure) return raw;
-	const text = raw.replace(/All requested lanes completed\.?/gi, "Host verification found incomplete requested lanes.");
+/**
+ * Shift ATX headings down (converting setext headings to ATX first) so
+ * retained Markdown nests under host-owned sections. Text outside the heading
+ * construct — including the heading's own label — is preserved byte-for-byte;
+ * fenced-code and HTML-block content is never touched because markdownHeadings
+ * only reports structural headings.
+ */
+export function demoteHeadings(text: string, levels = 1): string {
 	const headings = markdownHeadings(text);
-	const matches = headings.filter((heading) => heading.level === 2 && heading.name.toLowerCase() === "lane completeness");
-	if (matches.length !== 1) {
-		return `${text.trim()}\n\n## Host-verified lane completeness\n${disclosure}`.trim();
-	}
-	const match = matches[0]!;
-	const bodyStart = match.index + match.length;
-	const next = headings.find((heading) => heading.index > match.index && heading.level <= match.level);
-	const bodyEnd = next?.index ?? text.length;
-	const assistantDisclosure = text.slice(bodyStart, bodyEnd).trim();
-	return `${text.slice(0, bodyStart)}\n${assistantDisclosure}${assistantDisclosure ? "\n\n" : ""}${disclosure}\n\n${text.slice(bodyEnd)}`.trim();
-}
-
-function safeReviewBodyWithLaneDisclosure(raw: string, lanes: readonly ReviewLaneArtifact[]): string {
-	const bound = bindIncompleteLaneDisclosure(raw, lanes);
-	const body = safeReviewBody(bound);
-	const disclosure = incompleteLaneDisclosure(lanes);
-	if (!disclosure || body.includes(disclosure)) return body;
-	const suffix = sanitize(`\n\n## Host-verified lane completeness\n${disclosure}`);
-	const prefixBudget = MAX_SYNTHESIS_BODY_BYTES - Buffer.byteLength(suffix, "utf8") - 2;
-	if (prefixBudget <= 0) return safeReviewBody(suffix);
-	return `${truncateUtf8(sanitize(bound), prefixBudget)}\n\n${suffix}`;
-}
-
-function retainedLaneEvidence(lanes: readonly ReviewLaneArtifact[]): string {
-	if (lanes.length === 0) return "";
-	const lines = ["## Host-retained lane evidence", ""];
-	for (const lane of lanes.slice(0, MAX_DISCLOSED_LANES)) {
-		lines.push(`### ${disclosedPassId(lane.passId)} — ${lane.lifecycle}`, "");
-		if (lane.deadlineExpired) {
-			lines.push(`Host ${lane.deadlineExpired} deadline expired while this lane was still running.`, "");
+	if (headings.length === 0) return text;
+	const shifted = "#".repeat(levels);
+	let out = "";
+	let cursor = 0;
+	for (const heading of headings) {
+		const construct = text.slice(heading.index, heading.index + heading.length);
+		const atx = /^( {0,3})(#{1,6})([\s\S]*)$/.exec(construct);
+		let replacement: string;
+		if (atx) {
+			// Indented ATX stays ATX; only the opening run grows (capped at six).
+			const next = "#".repeat(Math.min(6, atx[2]!.length + levels));
+			replacement = `${atx[1]!}${next}${atx[3]!}`;
+		} else {
+			// Setext: drop the underline and re-render the paragraph as one ATX line.
+			const indent = /^[ \t]*/.exec(construct)![0];
+			const next = "#".repeat(Math.min(6, heading.level + levels));
+			replacement = `${indent}${next} ${heading.name}`;
 		}
-		const text = retainedLaneText(lane);
-		if (text) lines.push(text, "");
-		else lines.push(`No substantive output was retained${lane.errorMessage ? `: ${lane.errorMessage}` : "."}`, "");
-	}
-	if (lanes.length > MAX_DISCLOSED_LANES) {
-		lines.push(`### ${lanes.length - MAX_DISCLOSED_LANES} additional lane artifact(s) omitted`, "");
+		out += `${text.slice(cursor, heading.index)}${replacement}`;
+		cursor = heading.index + heading.length;
 	}
-	return lines.join("\n").trim();
-}
-
-function laneFallback(lanes: readonly ReviewLaneArtifact[]): string {
-	const lines = ["# PR Review", "", "**Verdict:** comment", "", "## Lane completeness", ""];
-	if (lanes.length === 0) {
-		lines.push("- No synthesis or retained lane output was available.");
+	return out + text.slice(cursor);
+}
+
+function degradedFindingLocation(finding: ReviewFindingLike): string {
+	const location = finding.code_location;
+	const path = location?.absolute_file_path;
+	if (!path) return "summary-only";
+	const range = location?.line_range;
+	const start = range?.start;
+	const end = range?.end ?? start;
+	const side = location?.side === "LEFT" ? "LEFT" : location?.side === "RIGHT" ? "RIGHT" : undefined;
+	const linesPart = start !== undefined ? `:${start}${end !== undefined && end !== start ? `-${end}` : ""}` : "";
+	return `${String(path)}${linesPart}${side ? ` ${side}` : ""}`;
+}
+
+/** Host-rendered finding blocks that match the canonical synthesis labels. */
+function degradedFindingBlocks(findings: readonly ReviewFindingLike[]): string[] {
+	if (findings.length === 0) return [];
+	return findings.map((finding) => {
+		const severity = String(finding.severity ?? "P2");
+		const rawTitle = String(finding.title ?? "Finding").trim() || "Finding";
+		// Parsed titles may already carry their severity tag; never double it.
+		const title = rawTitle.replace(/^\[?(P0|P1|P2|P3|nit)\]\s*/i, "$1 ").replace(/^(P0|P1|P2|P3|nit)\s+/, "").trim() || rawTitle;
+		const lines = [
+			`### [${severity}] ${title}`,
+			`**Severity:** ${severity}`,
+		];
+		if (finding.body?.trim()) lines.push(finding.body.trim());
+		lines.push(`**Location:** \`${degradedFindingLocation(finding)}\``);
 		return lines.join("\n");
-	}
-	lines.push(retainedLaneEvidence(lanes));
-	return lines.join("\n").trim();
+	});
 }
 
-function synthesisWithRetainedLaneEvidence(raw: string, lanes: readonly ReviewLaneArtifact[]): string {
-	const evidence = retainedLaneEvidence(lanes);
-	return evidence ? `${raw.trim()}\n\n${evidence}`.trim() : raw;
+/**
+ * Deterministic, readable body for degraded syntheses. The model's raw Markdown
+ * and every retained lane artifact are preserved verbatim (only heading levels
+ * shift) under explicit host-owned labels, parsed findings are rendered in the
+ * canonical format, and coverage is disclosed instead of implied.
+ */
+function buildDegradedReviewBody(input: {
+	rawText: string;
+	lanes: readonly ReviewLaneArtifact[];
+	findings: readonly ReviewFindingLike[];
+	reason?: string;
+	/** Host-registered dispatch count for exact-coverage disclosure. */
+	expectedLaneCount?: number;
+	/** Whether retained lanes cover every expected dispatch (host-computed). */
+	exactCoverage?: boolean;
+}): string {
+	const blocking = input.findings.some((finding) => finding.severity === "P0" || finding.severity === "P1");
+	const verdict = blocking ? "Request changes" : "Comment";
+	const reason = input.reason?.trim();
+	const lines: string[] = [
+		"# PR Review",
+		"",
+		`**Verdict:** ${verdict}${reason ? ` — ${reason}` : ""}`,
+		"",
+		"## Coverage",
+		"",
+	];
+	// The host's own voice may only claim completion when every retained lane
+	// completed AND the retained artifacts cover every expected dispatch.
+	const disclosure = incompleteLaneDisclosure(input.lanes);
+	const expected = input.expectedLaneCount ?? 0;
+	let coverage: string;
+	if (input.lanes.length === 0 && expected === 0) {
+		coverage = "No host lane evidence was retained for this review.";
+	} else if (disclosure) {
+		coverage = disclosure;
+	} else if (expected === 0 || input.exactCoverage === true) {
+		coverage = "All requested lanes completed.";
+	} else {
+		coverage = [
+			"Host-verified incomplete requested lenses/shards:",
+			"Exact incomplete lifecycle counts: partial=0; timed_out=0; failed=0.",
+			`- retained lane artifacts do not cover every expected dispatch (${input.lanes.length} retained / ${expected} registered)`,
+		].join("\n");
+	}
+	lines.push(coverage, "");
+	const hasRetainedEvidence = input.rawText.trim().length > 0 || input.lanes.length > 0;
+	lines.push("## Findings", "");
+	if (input.findings.length === 0) {
+		lines.push("No structurally parsed findings were extracted from this degraded synthesis.");
+		if (hasRetainedEvidence) {
+			lines.push("The retained reviewer output below is the authoritative record; it is not evidence of a clean review.");
+		}
+		lines.push("");
+	} else {
+		for (const block of degradedFindingBlocks(input.findings)) lines.push(block, "");
+	}
+	const synthesis = input.rawText.trim();
+	if (synthesis) {
+		// A retained synthesis may still carry a completion claim the host has
+		// disproven; replace it so the published body never states both. With no
+		// batch evidence the model's own claim stays authoritative.
+		const claimComplete = coverage === "All requested lanes completed.";
+		const batchEvidence = input.lanes.length > 0 || expected > 0;
+		const reconciled = !claimComplete && batchEvidence
+			? synthesis.replace(/All requested lanes completed\.?/gi, "Host verification found incomplete requested lanes.")
+			: synthesis;
+		// Two levels keep the synthesis's own document heading below the host
+		// labels (its canonical "# PR Review" becomes a level-3 heading).
+		lines.push("## Retained synthesis", "", demoteHeadings(reconciled, 2).trim(), "");
+	}
+	if (input.lanes.length > 0) {
+		lines.push("## Retained lane output", "");
+		for (const lane of input.lanes.slice(0, MAX_DISCLOSED_LANES)) {
+			lines.push(`### ${disclosedPassId(lane.passId)} — ${lane.lifecycle}`, "");
+			if (lane.deadlineExpired) {
+				lines.push(`Host ${lane.deadlineExpired} deadline expired while this lane was still running.`, "");
+			}
+			const text = retainedLaneText(lane);
+			if (text) lines.push(demoteHeadings(text, 2).trim(), "");
+			else lines.push(`No substantive output was retained${lane.errorMessage ? `: ${lane.errorMessage}` : "."}`, "");
+		}
+		if (input.lanes.length > MAX_DISCLOSED_LANES) {
+			lines.push(`### ${input.lanes.length - MAX_DISCLOSED_LANES} additional lane artifact(s) omitted`, "");
+		}
+	}
+	return safeReviewBody(lines.join("\n").trim());
 }
 
 /** Build the canonical semantic artifact while taking every authority field from the host binding. */
@@ -597,12 +688,35 @@ export function synthesizeReviewArtifact(input: {
 			new Set(["light", "medium", "heavy"]).has(lane.tier) && typeof lane.minorHygiene === "boolean")
 		.map((lane) => Object.freeze({ ...lane })));
 	const expectedLaneCount = expectedLaneDescriptors.length;
+	const exactLaneCoverage = expectedLaneCount > 0 && lanes.length === expectedLaneCount &&
+		new Set(lanes.map((lane) => lane.key)).size === expectedLaneCount &&
+		new Set(expectedLaneDescriptors.map((lane) => lane.key)).size === expectedLaneCount &&
+		lanes.every((lane) => expectedLaneDescriptors.some((expected) =>
+			expected.key === lane.key && expected.tier === lane.tier &&
+			expected.minorHygiene === !!lane.minorHygiene));
 	if (input.strictJsonReview) {
-		const completeness = synthesisCompleteness(input.rawText, lanes);
+		// Strict JSON carries no assistant disclosure line; host lane evidence is
+		// the only completeness authority whenever a batch ran.
+		const batchEvidence = lanes.length > 0 || expectedLaneCount > 0;
+		const completeness = synthesisCompleteness(
+			input.rawText,
+			lanes,
+			batchEvidence ? lanes.every((lane) => lane.lifecycle === "complete") && (expectedLaneCount === 0 || exactLaneCoverage) : true,
+		);
 		const safe = publicationSafeStrictReview(input.strictJsonReview);
 		const bodyFallback = !safe || completeness === "incomplete";
+		const strictFindings = safe ? (input.strictJsonReview.findings ?? []) : [];
 		const body = bodyFallback
-			? safeReviewBodyWithLaneDisclosure(synthesisWithRetainedLaneEvidence(input.rawText, lanes), lanes)
+			? buildDegradedReviewBody({
+				rawText: input.rawText,
+				lanes,
+				findings: strictFindings,
+				expectedLaneCount,
+				exactCoverage: exactLaneCoverage || expectedLaneCount === 0,
+				reason: safe
+						? "incomplete lane evidence degraded this synthesis"
+						: "publication-invalid extracted content degraded this synthesis",
+			})
 			: "";
 		return Object.freeze({
 			quality: bodyFallback ? "raw" as const : "fully_parsed" as const,
@@ -612,7 +726,7 @@ export function synthesizeReviewArtifact(input: {
 			// Rebind every target field to the frozen host snapshot so an assistant
 			// cannot substitute the final head and bypass stale-head handling.
 			review: bodyFallback
-				? syntheticReview(input.prNumber, input.prTitle, input.headSha, body)
+				? syntheticReview(input.prNumber, input.prTitle, input.headSha, body, strictFindings)
 				: {
 						...input.strictJsonReview,
 						pr: { number: input.prNumber, title: input.prTitle, head_sha: input.headSha },
@@ -624,18 +738,24 @@ export function synthesizeReviewArtifact(input: {
 			mergeApprovalEligible: !bodyFallback,
 			diagnostics: Object.freeze(bodyFallback
 				? [safe
-					? "incomplete lane evidence forced sanitized body-only publication"
-					: "publication-invalid extracted content forced sanitized body-only publication"]
+					? "incomplete lane evidence degraded this synthesis"
+					: "publication-invalid extracted content degraded this synthesis"]
 				: []),
 		});
 	}
 	const raw = input.rawText.trim().replace(/\r\n?/g, "\n");
 	if (!raw) {
 		const completeness = synthesisCompleteness(input.rawText, lanes);
-		// The retained evidence itself can exceed the publication cap. Apply the
-		// same host-owned disclosure reservation used for raw synthesis so an
-		// early large lane cannot truncate away exact later incomplete shards.
-		const body = safeReviewBodyWithLaneDisclosure(laneFallback(lanes), lanes);
+		// Retained lane output is bounded by the host-owned body cap so an early
+		// large lane cannot truncate away the coverage disclosure above it.
+		const body = buildDegradedReviewBody({
+			rawText: "",
+			lanes,
+			findings: [],
+			expectedLaneCount,
+			exactCoverage: exactLaneCoverage,
+			reason: "terminal synthesis was absent",
+		});
 		return Object.freeze({
 			quality: "lane_fallback" as const,
 			rawText: input.rawText,
@@ -654,33 +774,78 @@ export function synthesizeReviewArtifact(input: {
 	const verification = section(raw, "Verification");
 	const laneDisclosure = section(raw, "Lane completeness");
 	const laneDisclosureClaimsComplete = /^all requested lanes completed\.?$/i.test(laneDisclosure?.trim() ?? "");
+	// Host lane artifacts are authoritative whenever a batch ran: they already
+	// stop a false complete claim from upgrading incomplete lanes, and they must
+	// equally stop a paraphrased or omitted disclosure line from downgrading a
+	// host-complete batch to body-only publication. Completeness additionally
+	// requires the retained lanes to cover every expected dispatch, so an
+	// expected-but-unretained artifact cannot make an incomplete batch look
+	// complete through vacuous satisfaction.
+	const batchEvidencePresent = lanes.length > 0 || expectedLaneCount > 0;
+	const laneTruthClaimsComplete = batchEvidencePresent
+		? lanes.every((lane) => lane.lifecycle === "complete") &&
+			(expectedLaneCount === 0 || exactLaneCoverage)
+		: laneDisclosureClaimsComplete;
 	const preamble = documentPreamble(raw);
 	const verdictField = field(preamble, "Verdict");
 	const verdict = verdictField?.toLowerCase().replace(/[ -]+/g, "_");
-	const extractedControlsSafe = publicationSafeText(overview) && publicationSafeText(verification) &&
-		publicationSafeText(laneDisclosure) && publicationSafeText(verdictField) &&
+	// A missing section is a structural gap handled by hasStructure and
+	// diagnostics; only present-but-unsafe text disables inline extraction.
+	const safeIfPresent = (value: string | undefined) => value === undefined || publicationSafeText(value);
+	const extractedControlsSafe = safeIfPresent(overview) && safeIfPresent(verification) &&
+		safeIfPresent(laneDisclosure) && safeIfPresent(verdictField) &&
 		new Set(["approve", "request_changes", "comment"]).has(verdict ?? "") &&
 		fieldCount(preamble, "Verdict") === 1 && fieldCount(raw, "Verdict") === 1;
 	const canonicalParsed = parsed.unsafe ? parsed : { ...parsed, unsafe: !extractedControlsSafe };
-	const completeness = synthesisCompleteness(raw, lanes, laneDisclosureClaimsComplete);
-	const hasStructure = !!overview && !!verification && laneDisclosureClaimsComplete && extractedControlsSafe;
+	const completeness = synthesisCompleteness(raw, lanes, laneTruthClaimsComplete);
+	const hasStructure = !!overview && !!verification && laneTruthClaimsComplete && extractedControlsSafe;
 	const quality: ReviewSynthesisQuality = canonicalParsed.unsafe
 		? "raw"
 		: hasStructure && canonicalParsed.complete && completeness === "complete"
 			? "fully_parsed"
 			: canonicalParsed.findings.length > 0 ? "partially_parsed" : "raw";
-	// Markdown is the durable semantic product. Keep it in the body even when
-	// deterministic extraction also makes safe inline placement available. Host
-	// lane artifacts override contradictory assistant completion claims.
-	const bodySource = quality === "fully_parsed" ? raw : synthesisWithRetainedLaneEvidence(raw, lanes);
-	const body = safeReviewBodyWithLaneDisclosure(bodySource, lanes);
 	const safeFindings = canonicalParsed.unsafe ? [] : canonicalParsed.findings;
-	const exactLaneCoverage = expectedLaneCount > 0 && lanes.length === expectedLaneCount &&
-		new Set(lanes.map((lane) => lane.key)).size === expectedLaneCount &&
-		new Set(expectedLaneDescriptors.map((lane) => lane.key)).size === expectedLaneCount &&
-		lanes.every((lane) => expectedLaneDescriptors.some((expected) =>
-			expected.key === lane.key && expected.tier === lane.tier &&
-			expected.minorHygiene === !!lane.minorHygiene));
+	const degradationReasons = (() => {
+		if (canonicalParsed.unsafe) {
+			return ["unsafe Markdown fields were preserved in the sanitized body and inline extraction was disabled"];
+		}
+		if (quality === "fully_parsed") return [];
+		const reasons: string[] = [];
+		if (!overview) reasons.push("Overview section missing or empty");
+		if (!verification) reasons.push("Verification section missing or empty");
+		if (!laneTruthClaimsComplete) {
+			if (lanes.length > 0 && !lanes.every((lane) => lane.lifecycle === "complete")) {
+				reasons.push("host lane evidence contains incomplete lanes");
+			} else if (expectedLaneCount > 0 && !exactLaneCoverage) {
+				reasons.push("retained lane evidence does not cover every expected lane dispatch");
+			} else {
+				reasons.push("Lane completeness section absent or did not state the canonical completion line");
+			}
+		}
+		if (verdictField !== undefined && !new Set(["approve", "request_changes", "comment"]).has(verdict ?? "")) {
+			reasons.push("Verdict field outside the canonical set");
+		}
+		if (fieldCount(preamble, "Verdict") !== 1 || fieldCount(raw, "Verdict") !== 1) {
+			reasons.push("Verdict field count is not exactly one");
+		}
+		if (parsed.count > parsed.findings.length) {
+			reasons.push(`${parsed.count - parsed.findings.length} finding section(s) could not be parsed and remain in the body`);
+		}
+		return reasons.length > 0 ? reasons : ["terminal synthesis was not structurally parseable; preserved as body-only Markdown"];
+	})();
+	// Markdown is the durable semantic product. A fully parsed complete synthesis
+	// publishes verbatim; every degraded synthesis publishes the deterministic
+	// host-rendered body so labels stay readable while all content is retained.
+	const body = quality === "fully_parsed"
+		? safeReviewBody(raw)
+		: buildDegradedReviewBody({
+			rawText: raw,
+			lanes,
+			findings: safeFindings,
+			expectedLaneCount,
+			exactCoverage: exactLaneCoverage,
+			reason: degradationReasons[0],
+		});
 	return Object.freeze({
 		quality,
 		rawText: input.rawText,
@@ -701,12 +866,6 @@ export function synthesizeReviewArtifact(input: {
 		// Markdown approval requires exact host evidence for every registered
 		// dispatch; a nonempty subset cannot establish requested coverage.
 		mergeApprovalEligible: quality === "fully_parsed" && completeness === "complete" && exactLaneCoverage,
-		diagnostics: Object.freeze(canonicalParsed.unsafe
-			? ["unsafe Markdown fields were preserved in the sanitized body and inline extraction was disabled"]
-			: quality === "partially_parsed"
-				? [completeness === "incomplete"
-					? "incomplete lane disclosure or evidence forced sanitized body-only publication"
-					: `${parsed.count - parsed.findings.length} finding section(s) could not be parsed and remain in the body`]
-				: quality === "raw" ? ["terminal synthesis was not structurally parseable; preserved as body-only Markdown"] : []),
+		diagnostics: Object.freeze(degradationReasons),
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.12.2",
+  "version": "1.13.0",
   "description": "Parallel AI code review for GitHub pull requests in the Pi coding agent, with model-agnostic tiered subagents, structured findings, optional verification, and host-gated COMMENT or qualified APPROVE publishing.",
   "keywords": [
     "pi-package",

package/prompts/pr-review.md

@@ -196,7 +196,7 @@ The orchestrator must never call `gh` to post comments or reviews. Always finish
 
 After host synthesis, the extension caches one validated completed review as a canonical host-owned artifact per repository and PR in the current Pi session. `autoPostReviews` and `--comment` publish that cached review after completion; `--no-comment` suppresses publication for the run. `/pr-review-publish` and a matching direct request publish only the cache and never start or rerun review agents. On a later turn, the extension intercepts that direct input before an agent turn and permits stale publication without asking the orchestrator to recreate the review.
 
-Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; the extension never submits `REQUEST_CHANGES`. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch, a standalone visible `All requested lanes completed.` disclosure (matched case-insensitively, with an optional final period), and retained strict host-bound JSON share the same gated `APPROVE` path. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, contradictory lane disclosures, and partial, malformed, unsafe, or lane-fallback Markdown remain body-only `COMMENT`. Restored cache entries must reclassify retained lane output, reproduce the exact host-recorded artifact key set, and bind every complete artifact to the frozen invocation generation, tier, and minor-hygiene contract and re-synthesize the retained raw text under that frozen binding before preserving approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The public body contains the verdict, an inline-review cue when applicable, and `Other Notes` for nits and every finding that cannot be inline; overview, verification, strengths, and transport diagnostics remain only in the retained internal artifact. If that concise body plus its canonical marker exceeds GitHub's limit, the host publishes the sanitized, size-bounded original Markdown projection instead of dropping the review. Stale reviews and authorized closed or merged reviews are body-only. A stale review may record a qualified `APPROVE` only with the separate trusted `allowStaleApprovals: true` opt-in captured before review execution. A failed write never triggers a fallback POST.
+Every authorized publish path builds one GitHub review payload and sends at most one review `POST`; the extension never submits `REQUEST_CHANGES`. Fully parsed Markdown with one complete retained artifact for every host-registered dispatch and retained strict host-bound JSON share the same gated `APPROVE` path. Host lane evidence is authoritative for completeness: a paraphrased or omitted `All requested lanes completed.` disclosure cannot downgrade a host-complete batch, and a false disclosure cannot upgrade incomplete or missing lane coverage; the assistant's canonical line is consulted only when no batch evidence exists. Verdict fields outside the document preamble, hidden in CommonMark code/HTML blocks, or inside lazy container continuations, severity-tagged headings outside `Findings`, incomplete or missing host lane coverage, and partial, malformed, unsafe, or lane-fallback Markdown remain `COMMENT` reviews that keep inline placement for every safely parsed finding and publish body-only when nothing parses. Restored cache entries must reclassify retained lane output, reproduce the exact host-recorded artifact key set, and bind every complete artifact to the frozen invocation generation, tier, and minor-hygiene contract and re-synthesize the retained raw text under that frozen binding before preserving approval eligibility. For a current, open PR, the first 50 eligible P0–P3 findings with valid, unique diff anchors are inline. The public body contains the verdict, an inline-review cue when applicable, and `Other Notes` for nits and every finding that cannot be inline; overview, verification, strengths, and transport diagnostics remain only in the retained internal artifact. If that concise body plus its canonical marker exceeds GitHub's limit, the host publishes the sanitized, size-bounded original Markdown projection instead of dropping the review. Stale reviews and authorized closed or merged reviews are body-only. A stale review may record a qualified `APPROVE` only with the separate trusted `allowStaleApprovals: true` opt-in captured before review execution. A failed write never triggers a fallback POST.
 
 Every path retains the same safety gates: captured posting authority, exact repository/PR/review binding, safe locations, no reserved review markers, bounded bodies and payloads, current-head and stale policy, draft and lifecycle checks, non-open authorization, same-head duplicate detection, and a final head check. Unknown lifecycle states and unconfirmed non-open writes fail closed. The session-backed cache survives extension reloads and session resumes but remains bound to the originating session instance and repository. If the captured stale setting disabled publication, the user may explicitly run `/pr-review-publish <PR-NUM> --allow-stale`. Never rerun the review merely to change posting intent, and never attempt a direct GitHub write yourself.