pi-pr-review 1.15.2 → 1.15.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.15.3](https://github.com/10ego/pi-pr-review/compare/v1.15.2...v1.15.3) (2026-08-25)
+
+
+### Bug Fixes
+
+* **review:** harden the nonempty refusal check and document the contract ([#92](https://github.com/10ego/pi-pr-review/issues/92)) ([e8339a0](https://github.com/10ego/pi-pr-review/commit/e8339a029b1d12722f941339d1e8164e6d1ef09d))
+
 ## [1.15.2](https://github.com/10ego/pi-pr-review/compare/v1.15.1...v1.15.2) (2026-08-24)
 
 

package/extensions/pr-review-subagent.ts

@@ -429,6 +429,8 @@ function getPiInvocation(args: string[]): { command: string; args: string[] } {
 	return { command: "pi", args };
 }
 
+const NONEMPTY_CONTRACT_DESCRIPTION = "After a successful terminal stop, nonempty output is exact Markdown with no wrapper: the first nonblank line must be exactly `Review status: COMPLETE` with no leading or trailing whitespace. If you could not inspect required evidence for any reason, return the top-level exact line `Review status: INCOMPLETE` followed by a concise reason; INCOMPLETE and every other status are partial. COMPLETE must be followed in exact order by meaningful one-line `Overview: ...`, `Strengths: ...`, and `Risk areas: ...` sections, then either the exact standalone `NO FINDINGS.` line or one or more complete candidate blocks. Nonblank contract lines have no trailing spaces or tabs. Framing may use plain labels, bold labels, or an ATX label followed immediately by exactly one top-level value line; do not use list-indented or quoted contract lines. Candidate fields are in exact order and each appears once: title prefixed [P0], [P1], [P2], [P3], or [nit] (the tag must match severity); severity P0/P1/P2/P3/nit; meaningful why; location as repo-relative/path:positive-line or repo-relative/path:positive-start-positive-end (ordered), or repo-wide; side RIGHT/LEFT; in_diff yes/no; pr_related yes/no; confidence 0.0-1.0. Candidate labels may be plain/bold or use exactly one top-level `- ` list marker; no other indentation or list marker is accepted. A why value may continue only on lines beginning with exactly two spaces plus a non-list character until the next reserved field. Scalar and continuation values must not contain status/field/severity/sentinel productions, code fences, HTML/container wrappers, blockquotes, lists, or code indentation. Do not emit code fences, blockquotes, JSON, HTML/container wrappers, duplicate/out-of-order fields, arbitrary prose, or placeholder values (none, n/a, unavailable, unknown, skipped, error, review complete). Status/refusal/access/tool/model/error reasons belong in an INCOMPLETE status; inability discussed inside a valid candidate why is allowed. COMPLETE is the primary completion attestation; only obvious exact failure placeholders are rejected as defense-in-depth."
+
 const TIER_GUIDANCE: Record<Tier, string> = {
 	light:
 		"You are a fast overview reviewer. Produce a concise overview of what the change does and how, list genuine strengths, and note high-level risk areas worth closer specialist review. Do not deep-dive into defects.",
@@ -467,26 +469,27 @@ function buildSubagentSystemPrompt(tier: Tier, majorOnly = false, minorHygiene =
 		lines.push(
 			"Start from the supplied complete diff. Use repository tools only to substantiate a concrete candidate caused by that diff; never browse for unrelated issues or run broad repository audits/tests.",
 			"Before your first tool call, identify the evidence needed for all current candidates. Issue independent reads/searches/checks together when the interface supports concurrent calls, grouped to avoid rereading the same file. Use at most one follow-up tool turn, only for a dependency revealed by the first evidence wave. This schedules validation efficiently but never permits skipping evidence needed to substantiate a finding.",
-			"Return your findings as a concise Markdown list. For each finding include, on its own lines:",
-			majorOnly
-				? "- title: an imperative summary prefixed with [P0], [P1], or [P2]"
-				: "- title: an imperative summary prefixed with a severity tag [P0]|[P1]|[P2]|[P3]|[nit]",
-			majorOnly
-				? "- severity: one of P0, P1, P2 (P0/P1 are blocking)"
-				: "- severity: one of P0, P1, P2, P3, nit (P0/P1 are blocking)",
-			"- why: the impact and the exact input/environment needed for it to bite",
-			"- location: <repo-relative file path>:<start-end lines exactly as they appear in the diff> (or 'repo-wide')",
-			"- side: RIGHT for added/context lines, LEFT for removed lines",
-			"- in_diff: yes if those lines are inside the PR diff (so an inline comment can be posted), otherwise no",
-			"- pr_related: yes only if this PR introduces or provably affects the issue (drop pre-existing/unrelated issues)",
-			"- confidence: a float 0.0-1.0",
-			// A nonempty completion contract lets the pass carry framing prose
-			// (overview, strengths, risk) around its findings; the exact-match
-			// sentinel would forbid that and strand the lane as partial.
 			expectedOutput === "nonempty"
-				? majorOnly
-					? "If there are no substantiated P0-P2 findings, state that plainly in prose after your overview; do not emit the candidate fields."
-					: "If there are genuinely no findings at any severity, state that plainly in prose after your overview; do not emit the candidate fields."
+				? NONEMPTY_CONTRACT_DESCRIPTION
+				: "Return your findings as a concise Markdown list. For each finding include, on its own lines:",
+			expectedOutput === "nonempty"
+				? "For nonempty output, begin with the exact first nonblank top-level line `Review status: COMPLETE` with no trailing whitespace; use the exact top-level `Review status: INCOMPLETE` plus a concise reason whenever required evidence cannot be inspected. COMPLETE then requires Overview, Strengths, and Risk areas in order, followed immediately by NO FINDINGS. or complete candidate blocks; do not add other prose."
+				: majorOnly
+					? "- title: an imperative summary prefixed with [P0], [P1], or [P2]"
+					: "- title: an imperative summary prefixed with a severity tag [P0]|[P1]|[P2]|[P3]|[nit]",
+			...(expectedOutput === "nonempty" ? [] : [
+				majorOnly
+					? "- severity: one of P0, P1, P2 (P0/P1 are blocking)"
+					: "- severity: one of P0, P1, P2, P3, nit (P0/P1 are blocking)",
+				"- why: the impact and the exact input/environment needed for it to bite",
+				"- location: <repo-relative file path>:<start-end lines exactly as they appear in the diff> (or 'repo-wide')",
+				"- side: RIGHT for added/context lines, LEFT for removed lines",
+				"- in_diff: yes if those lines are inside the PR diff (so an inline comment can be posted), otherwise no",
+				"- pr_related: yes only if this PR introduces or provably affects the issue (drop pre-existing/unrelated issues)",
+				"- confidence: a float 0.0-1.0",
+			]),
+			expectedOutput === "nonempty"
+				? "After the exact COMPLETE status and three framing sections, the clean sentinel is one top-level standalone uppercase line `NO FINDINGS.`; never use `No findings.` or append a sentence. Candidate fields are top-level or use exactly one `- ` marker, with no arbitrary indentation; candidate `why` may use exactly-two-space non-list continuation lines, but never absorb a reserved field, status, sentinel, or wrapper."
 				: majorOnly
 					? "If there are no substantiated P0-P2 findings, reply exactly with: NO FINDINGS."
 					: "If there are genuinely no findings at any severity, reply exactly with: NO FINDINGS.",
@@ -1424,7 +1427,7 @@ const ReviewSubagentsParams = Type.Object({
 		Type.Object({
 			expected_output: Type.Optional(
 				StringEnum(["review_lane", "nonempty"] as const, {
-					description: "Completion contract for this pass. review_lane (default): candidate-evidence fields or exactly NO FINDINGS. nonempty: any nonempty terminal output completes; use for an integrated pass that carries framing prose around its findings.",
+					description: `Completion contract for this pass. review_lane (default): candidate-evidence fields or exactly NO FINDINGS. nonempty: ${NONEMPTY_CONTRACT_DESCRIPTION}`,
 				}),
 			),
 			id: Type.Optional(

package/lib/pr-review-artifacts.ts

@@ -114,34 +114,327 @@ function hasMeaningfulLightSection(text: string, field: string, fields: readonly
 		.some((line) => line.replace(/^[ \\t]*(?:[-*>][ \\t]*)+/, "").trim().length > 0);
 }
 
+/**
+ * The `nonempty` lane is a small Markdown grammar, not a prose detector. Its
+ * first nonblank line is the exact `Review status: COMPLETE` attestation;
+ * `INCOMPLETE` and every other status are partial. The remaining productions
+ * are documented in the public tool schema and both reviewer prompts: framing
+ * labels may be plain (`Overview:`), bold (`**Overview:**`), or ATX headings
+ * followed by one top-level value line; candidate fields may be plain/bold or
+ * use the one exact top-level `- ` list marker. Blockquotes, code fences, JSON,
+ * and other wrappers are not part of the contract. Nonblank contract lines do
+ * not carry trailing horizontal whitespace, and a `why` continuation is exactly
+ * two spaces plus a non-list line.
+ */
+const CANDIDATE_FIELDS = ["title", "severity", "why", "location", "side", "in_diff", "pr_related", "confidence"] as const;
+const CANDIDATE_SEVERITIES = new Set(["P0", "P1", "P2", "P3", "nit"]);
+const FRAMING_LABELS = ["Overview", "Strengths", "Risk areas"] as const;
+const PLACEHOLDER_ONLY = /^(?:none|n\/?a|na|unavailable|unknown|skipped|error|review complete|no findings|nothing to review)(?:\s+(?:identified|found|available|present))?[.!]?$/i;
+const NO_FINDINGS_SENTINEL = "NO FINDINGS.";
+const CODE_FENCE = /^ {0,3}(?:`{3,}|~{3,})/m;
+const COMMONMARK_HTML_BLOCK_TAGS = [
+	"address", "article", "aside", "base", "basefont", "blockquote", "body", "caption", "center", "col",
+	"colgroup", "dd", "details", "dialog", "dir", "div", "dl", "dt", "fieldset", "figcaption", "figure",
+	"footer", "form", "frame", "frameset", "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hr",
+	"html", "iframe", "legend", "li", "link", "main", "menu", "menuitem", "nav", "noframes", "ol",
+	"optgroup", "option", "p", "param", "search", "section", "summary", "table", "tbody", "td", "tfoot",
+	"th", "thead", "title", "tr", "track", "ul",
+].join("|");
+const COMMONMARK_BLANK_TERMINATED_HTML = new RegExp(
+	`^ {0,3}</?(?:${COMMONMARK_HTML_BLOCK_TAGS})(?:[ \\t]+|/?>|$)`,
+	"i",
+);
+// CommonMark type 7 accepts a complete open or closing tag for any tag name,
+// including custom elements. Unlike types 1–6, it cannot interrupt a paragraph.
+const COMMONMARK_COMPLETE_HTML_TAG = /^ {0,3}(?:<[A-Za-z][A-Za-z0-9-]*(?:[ \t]+[A-Za-z_:][A-Za-z0-9_.:-]*(?:[ \t]*=[ \t]*(?:[^ "'=<>`\u0000-\u0020]+|'[^']*'|"[^"]*"))?)*[ \t]*\/?>|<\/[A-Za-z][A-Za-z0-9-]*[ \t]*>)[ \t]*$/;
+// These are CommonMark HTML block openers. The opener itself is sufficient:
+// an assistant must not be able to hide later contract lines behind an
+// unterminated comment, declaration, raw block tag, or other container.
+function htmlBlockOpener(line: string): boolean {
+	return /^ {0,3}<(?:script|pre|style|textarea)(?:[ \t]+|>|$)/i.test(line) ||
+		/^ {0,3}<!--/.test(line) ||
+		/^ {0,3}<\?/.test(line) ||
+		/^ {0,3}<![A-Z]/i.test(line) ||
+		/^ {0,3}<!\[CDATA\[/i.test(line) ||
+		COMMONMARK_BLANK_TERMINATED_HTML.test(line) ||
+		COMMONMARK_COMPLETE_HTML_TAG.test(line);
+}
+
+function hasHtmlContainer(text: string): boolean {
+	return text.split("\n").some((line) => htmlBlockOpener(line));
+}
+
+const CONTAINER_PREFIX = /^(?:[-*+>]|#{1,6})[ \t]+/;
+const RESERVED_LABEL_PRODUCTION = /(?:^|[ \t])(?:\*\*|__)?(?:Overview|Strengths|Risk areas|title|severity|why|location|side|in_diff|pr_related|confidence)(?:\*\*|__)?[ \t]*:/i;
+const SEVERITY_TAG_PRODUCTION = /\[P[0-3]\]/gi;
+
+interface MarkdownLabel {
+	readonly field: string;
+	readonly value: string;
+	readonly kind: "inline" | "heading";
+}
+
+interface CandidateBlock {
+	readonly start: number;
+	readonly end: number;
+	readonly fields: ReadonlyMap<string, string>;
+}
+
+function normalizeReviewText(text: string): string {
+	// Only CRLF is transport normalization. In particular, do not trim or
+	// rewrite line-leading whitespace before applying the grammar.
+	return text.replace(/\r\n/g, "\n");
+}
+
+function hasTrailingHorizontalWhitespace(text: string): boolean {
+	return text.split("\n").some((line) => /[ \t]+$/.test(line));
+}
+
+function escapePattern(value: string): string {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Parse the exact framing forms; headings are accepted only for framing. */
+function framingLabel(line: string): MarkdownLabel | undefined {
+	if (/^[ \t]/.test(line)) return undefined;
+	let match = /^\*\*(Overview|Strengths|Risk areas):\*\*[ \t]*(.*)$/.exec(line);
+	if (match) return { field: match[1]!, value: match[2] ?? "", kind: "inline" };
+	match = /^__(Overview|Strengths|Risk areas):__[ \t]*(.*)$/.exec(line);
+	if (match) return { field: match[1]!, value: match[2] ?? "", kind: "inline" };
+	match = /^(Overview|Strengths|Risk areas):[ \t]*(.*)$/.exec(line);
+	if (match) return { field: match[1]!, value: match[2] ?? "", kind: "inline" };
+	match = /^#{1,6}[ \t]+(?:(?:\*\*)(Overview|Strengths|Risk areas):(?:\*\*)|(?:__)(Overview|Strengths|Risk areas):(?:__)|(Overview|Strengths|Risk areas):?)[ \t]*$/.exec(line);
+	if (match) return { field: (match[1] ?? match[2] ?? match[3])!, value: "", kind: "heading" };
+	return undefined;
+}
+
+/** Candidate fields are top-level one-line values with optional bold syntax or one exact `- ` marker. */
+function candidateLabel(line: string): MarkdownLabel | undefined {
+	const names = CANDIDATE_FIELDS.map(escapePattern).join("|");
+	const match = new RegExp(`^(?:- )?(?:(?:\\*\\*)(${names}):(?:\\*\\*)|(?:__)(${names}):(?:__)|(${names}):)[ \t]*(.*)$`).exec(line);
+	if (!match) return undefined;
+	return { field: (match[1] ?? match[2] ?? match[3])!, value: match[4] ?? "", kind: "inline" };
+}
+
+function canonicalField(field: string): string {
+	return field.toLowerCase();
+}
+
+function meaningfulValue(value: string): boolean {
+	const normalized = value.trim();
+	const words = normalized.match(/[\p{L}\p{N}]+/gu) ?? [];
+	return words.length >= 2 && !PLACEHOLDER_ONLY.test(normalized) &&
+		!/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(normalized);
+}
+
+function confidenceValue(value: string): boolean {
+	const normalized = value.trim();
+	if (!/^(?:0(?:\.\d+)?|1(?:\.0+)?)$/.test(normalized)) return false;
+	const number = Number(normalized);
+	return Number.isFinite(number) && number >= 0 && number <= 1;
+}
+
+/** Validate the prompt's repo-relative/path:positive-line-range location syntax. */
+function safeLocation(value: string): boolean {
+	const normalized = value.trim();
+	if (normalized === "repo-wide") return true;
+	const match = /^(.+):(\d+)(?:-(\d+))?$/.exec(normalized);
+	if (!match) return false;
+	const locationPath = match[1]!;
+	const start = Number(match[2]);
+	const end = match[3] === undefined ? start : Number(match[3]);
+	if (!Number.isSafeInteger(start) || start < 1 || !Number.isSafeInteger(end) || end < start) return false;
+	if (!locationPath || locationPath.startsWith("/") || locationPath.startsWith("~") || /^[A-Za-z]:/.test(locationPath)) return false;
+	if (/[\\\u0000-\u001f\u007f]/.test(locationPath)) return false;
+	const segments = locationPath.split("/");
+	return segments.length > 0 && segments.every((segment) => segment.length > 0 && segment === segment.trim() && segment !== "." && segment !== ".." && !segment.includes(":"));
+}
+
+function hasReservedStatusProduction(line: string): boolean {
+	return /^(?:[-*+>][ \t]+)?Review status\s*:/i.test(line.trim());
+}
+
+/**
+ * Values are prose, but they may not contain a line-shaped contract
+ * production. This is deliberately limited to the documented grammar (and
+ * containers), rather than an English keyword denylist. Every line is
+ * checked independently so a multiline `why` cannot hide a fence or an
+ * unterminated HTML block opener in a continuation.
+ */
+function hasReservedContractProduction(value: string): boolean {
+	if (!value) return false;
+	if (value.includes(NO_FINDINGS_SENTINEL) || /Review status\s*:/i.test(value) || RESERVED_LABEL_PRODUCTION.test(value)) return true;
+	if (hasHtmlContainer(value)) return true;
+	return value.split("\n").some((line) => {
+		const structural = line.trim();
+		return CODE_FENCE.test(line) || htmlBlockOpener(line) ||
+			structural === NO_FINDINGS_SENTINEL || hasReservedStatusProduction(structural) ||
+			!!framingLabel(structural) || !!candidateLabel(structural) || CONTAINER_PREFIX.test(structural);
+	});
+}
+
+function hasReservedCandidateProduction(field: string, value: string): boolean {
+	if (hasReservedContractProduction(value)) return true;
+	let allowedLeadingTitleTag = field === "title";
+	for (const [lineIndex, line] of value.split("\n").entries()) {
+		for (const match of line.matchAll(SEVERITY_TAG_PRODUCTION)) {
+			if (allowedLeadingTitleTag && lineIndex === 0 && match.index === 0) {
+				allowedLeadingTitleTag = false;
+				continue;
+			}
+			return true;
+		}
+	}
+	return false;
+}
+
+function validCandidateFields(fields: ReadonlyMap<string, string>): boolean {
+	if (CANDIDATE_FIELDS.some((field) => !fields.has(field))) return false;
+	if ([...fields.entries()].some(([field, value]) => hasReservedCandidateProduction(field, value))) return false;
+	const title = fields.get("title")!.trim();
+	const titleMatch = /^\[(P0|P1|P2|P3|nit)\][ \t]+(.+)$/.exec(title);
+	const severity = fields.get("severity")!.trim();
+	const why = fields.get("why")!;
+	const location = fields.get("location")!;
+	const side = fields.get("side")!.trim();
+	const inDiff = fields.get("in_diff")!.trim();
+	const prRelated = fields.get("pr_related")!.trim();
+	return !!titleMatch && meaningfulValue(titleMatch[2]!) &&
+		CANDIDATE_SEVERITIES.has(severity) && titleMatch[1] === severity &&
+		meaningfulValue(why) && safeLocation(location) &&
+		/^(?:RIGHT|LEFT)$/.test(side) &&
+		/^(?:yes|no)$/.test(inDiff) &&
+		/^(?:yes|no)$/.test(prRelated) &&
+		confidenceValue(fields.get("confidence")!);
+}
+
+function framingValueHasReservedProduction(value: string): boolean {
+	return hasReservedContractProduction(value);
+}
+
+function isReservedContractLine(line: string): boolean {
+	return hasReservedContractProduction(line);
+}
+
+/** Only obvious, deterministic placeholders are defense-in-depth; COMPLETE is the primary contract. */
+function topLevelFailure(text: string): boolean {
+	return text.split("\n").some((line) => /^(?:internal server error|fatal error|access denied|review (?:failed|unavailable|skipped)|no (?:diff|patch|source context|review context)(?: was)? (?:provided|available|accessible))[.!]?$/i.test(line.trim()));
+}
+
+/**
+ * Parse and validate the integrated deep-lane grammar statefully. COMPLETE is
+ * an explicit reviewer attestation: every other status, a missing/later/
+ * wrapped/duplicate status, or a malformed production is partial. Framing has
+ * exactly one nonempty value line per field. Candidate `why` may have
+ * indented continuation lines; reserved productions cannot be continuations.
+ */
+function parseIntegratedCompletion(text: string): boolean {
+	if (hasTrailingHorizontalWhitespace(text) || CODE_FENCE.test(text) || hasHtmlContainer(text)) return false;
+	const lines = text.split("\n");
+	let cursor = 0;
+	while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+	if (cursor >= lines.length || lines[cursor] !== "Review status: COMPLETE") return false;
+	const statusIndex = cursor;
+	if (lines.some((line, index) => index !== statusIndex && hasReservedStatusProduction(line))) return false;
+	cursor++;
+	const framingValues: string[] = [];
+	for (const expected of FRAMING_LABELS) {
+		while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+		const label = framingLabel(lines[cursor] ?? "");
+		if (!label || canonicalField(label.field) !== expected.toLowerCase()) return false;
+		cursor++;
+		let value = label.value;
+		if (label.kind === "heading") {
+			const valueLine = lines[cursor] ?? "";
+			if (!valueLine || !valueLine.trim() || /^[ \t]/.test(valueLine) || CONTAINER_PREFIX.test(valueLine) || isReservedContractLine(valueLine)) return false;
+			value = valueLine;
+			cursor++;
+		}
+		if (!meaningfulValue(value) || framingValueHasReservedProduction(value)) return false;
+		framingValues.push(value);
+	}
+	if (topLevelFailure(framingValues.join("\n"))) return false;
+
+	while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+	if (cursor < lines.length && lines[cursor] === NO_FINDINGS_SENTINEL) {
+		cursor++;
+		while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+		return cursor === lines.length;
+	}
+
+	const candidates: CandidateBlock[] = [];
+	while (cursor < lines.length) {
+		while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+		if (cursor >= lines.length) break;
+		const start = cursor;
+		const first = candidateLabel(lines[cursor]!);
+		if (!first || canonicalField(first.field) !== "title") return false;
+		const fields = new Map<string, string>();
+		for (const expected of CANDIDATE_FIELDS) {
+			while (cursor < lines.length && !lines[cursor]!.trim()) cursor++;
+			const field = candidateLabel(lines[cursor] ?? "");
+			if (!field || canonicalField(field.field) !== expected || fields.has(expected)) return false;
+			if (hasReservedCandidateProduction(expected, field.value)) return false;
+			fields.set(expected, field.value);
+			cursor++;
+			if (expected !== "why") continue;
+			const whyLines = [field.value];
+			while (cursor < lines.length) {
+				const continuation = lines[cursor]!;
+				if (!continuation.trim()) break;
+				if (isReservedContractLine(continuation)) break;
+				if (!/^ {2}\S/.test(continuation) || /^ {2}(?:[-*+>]|#{1,6})[ \t]+/.test(continuation)) return false;
+				if (hasReservedCandidateProduction("why", continuation.slice(2))) return false;
+				whyLines.push(continuation.slice(2));
+				cursor++;
+			}
+			fields.set("why", whyLines.join("\n"));
+		}
+		if (!validCandidateFields(fields)) return false;
+		candidates.push({ start, end: cursor, fields });
+	}
+	return candidates.length > 0;
+}
+
 function hasMeaningfulField(text: string, field: string): boolean {
-	const match = new RegExp(`^[ \\t]*(?:[-*][ \\t]*)?${field}[ \\t]*:[ \\t]*(.+?)[ \\t]*\\r?$`, "im").exec(text);
+	const match = fieldPattern(field).exec(text);
 	return !!match?.[1]?.trim();
 }
 
+function fieldPattern(field: string): RegExp {
+	return new RegExp(`^[ \\t]*(?:[-*+][ \\t]*)?(?:#{1,6}[ \\t]*)?(?:\\*\\*|__)?${escapePattern(field)}(?:\\*\\*|__)?[ \\t]*:[ \\t]*(.+?)[ \\t]*\\r?$`, "im");
+}
+
+function hasMeaningfulLightSection(text: string, field: string, fields: readonly string[]): boolean {
+	const escapedFields = fields.map((candidate) => escapePattern(candidate)).join("|");
+	const heading = new RegExp(`^[ \\t]*(?:#{1,6}[ \\t]*)?${escapePattern(field)}[ \\t]*:?[ \\t]*(.*)\\r?$`, "im").exec(text);
+	if (!heading || heading.index === undefined) return false;
+	const inlineValue = heading[1] ?? "";
+	const bodyStart = heading.index + heading[0].length;
+	const nextHeading = new RegExp(`^[ \\t]*(?:#{1,6}[ \\t]*)?(?:${escapedFields})[ \\t]*:?[ \\t]*`, "im").exec(text.slice(bodyStart));
+	const body = nextHeading ? text.slice(bodyStart, bodyStart + nextHeading.index) : text.slice(bodyStart);
+	return `${inlineValue}\n${body}`
+		.split("\n")
+		.some((line) => line.replace(/^[ \\t]*(?:[-*>][ \\t]*)+/, "").trim().length > 0);
+}
+
 function expectedLaneSections(input: ReviewLaneCompletionInput): boolean {
-	const text = input.rawText.trim();
-	if (!text) return false;
-	// The nonempty contract accepts framing prose around findings, but not
-	// degenerate refusals: the lane must either carry candidate evidence or a
-	// substantive statement (overview/no-findings text), not a bare refusal.
-	if (input.expectedOutput === "nonempty") {
-		if (["title", "severity", "why", "overview"].some((field) => hasMeaningfulField(text, field))) return true;
-		return text.length >= 16 && !/^(?:i could not|unable to|cannot|i cannot|error|failed)[^.]*\.*$/i.test(text);
-	}
+	const normalized = normalizeReviewText(input.rawText);
+	if (!normalized.trim()) return false;
+	if (input.expectedOutput === "nonempty") return parseIntegratedCompletion(normalized);
+	const text = normalized.trim();
 	if (input.tier === "light") {
 		const fields = input.minorHygiene ? ["overview", "strengths", "minor candidates"] : ["overview", "strengths"];
 		return fields.every((field) => hasMeaningfulLightSection(text, field, fields));
 	}
-	if (text === "NO FINDINGS.") return true;
-	return ["title", "severity", "why", "location", "side", "in_diff", "pr_related", "confidence"]
-		.every((field) => hasMeaningfulField(text, field));
+	if (text === NO_FINDINGS_SENTINEL) return true;
+	return CANDIDATE_FIELDS.every((field) => hasMeaningfulField(text, field));
 }
 
 /** Process exit is necessary but insufficient: only a terminal stop with valid lane output is complete. */
 export function classifyReviewLane(input: ReviewLaneCompletionInput): ReviewLaneLifecycle {
-	const reason = input.stopReason?.toLowerCase();
-	const error = input.errorMessage?.toLowerCase();
+	const reason = typeof input.stopReason === "string" ? input.stopReason.toLowerCase() : undefined;
+	const error = typeof input.errorMessage === "string" ? input.errorMessage.toLowerCase() : undefined;
 	if (reason?.includes("timeout") || error?.includes("timed out") || error?.includes("timeout")) return "timed_out";
 	const hasText = input.rawText.length > 0;
 	if (input.exitCode === 0 && reason === "stop" && expectedLaneSections(input)) return "complete";
@@ -162,11 +455,16 @@ export class ReviewLaneArtifactRegistry {
 	expect(generation: number, lanes: readonly ExpectedReviewLane[]): boolean {
 		if (
 			this.generation !== generation || lanes.length === 0 ||
-			lanes.some((lane) => !lane.key || !new Set(["light", "medium", "heavy"]).has(lane.tier))
+			lanes.some((lane) => !lane.key || !new Set(["light", "medium", "heavy"]).has(lane.tier) ||
+				(lane.expectedOutput !== undefined && !new Set(["review_lane", "nonempty"]).has(lane.expectedOutput)))
 		) return false;
 		for (const lane of lanes) {
 			const existing = this.expectedLanes.get(lane.key);
-			if (existing && (existing.tier !== lane.tier || existing.minorHygiene !== lane.minorHygiene)) return false;
+			if (existing && (
+				existing.tier !== lane.tier ||
+				existing.minorHygiene !== lane.minorHygiene ||
+				(existing.expectedOutput ?? "review_lane") !== (lane.expectedOutput ?? "review_lane")
+			)) return false;
 			this.expectedLanes.set(lane.key, Object.freeze({ ...lane }));
 		}
 		return true;

package/lib/pr-review-publish.ts

@@ -664,14 +664,44 @@ function parsePersistedInvocation(value: unknown): ReviewInvocation | undefined
 function parsePersistedLaneArtifacts(value: unknown): readonly ReviewLaneArtifact[] | undefined {
 	if (!Array.isArray(value)) return undefined;
 	const lifecycles = new Set(["complete", "partial", "timed_out", "failed"]);
+	const tiers = new Set(["light", "medium", "heavy"]);
+	const deadlineKinds = new Set(["total", "synthesis"]);
+	const deadlineSources = new Set(["default", "user", "project"]);
+	const optional = (object: Record<string, unknown>, key: string, predicate: (value: unknown) => boolean): boolean =>
+		object[key] === undefined || predicate(object[key]);
+	const isFiniteNumber = (item: unknown): boolean => typeof item === "number" && Number.isFinite(item);
+	const isString = (item: unknown): boolean => typeof item === "string";
+	const validAttempt = (attempt: unknown): attempt is Record<string, unknown> => {
+		if (!isObject(attempt)) return false;
+		return Number.isInteger(attempt.ordinal) &&
+			(attempt.kind === undefined || new Set(["primary", "fallback", "nearest", "default"]).has(String(attempt.kind))) &&
+			typeof attempt.rawText === "string" && Number.isInteger(attempt.exitCode) && lifecycles.has(String(attempt.lifecycle)) &&
+			(typeof attempt.retryable === "boolean" || attempt.retryable === undefined) &&
+			optional(attempt, "requestedModel", isString) && optional(attempt, "observedModel", isString) &&
+			optional(attempt, "usedTier", (item) => tiers.has(String(item))) &&
+			optional(attempt, "processSignal", isString) && optional(attempt, "stopReason", isString) &&
+			optional(attempt, "errorMessage", isString) && optional(attempt, "deadlineExpired", (item) => deadlineKinds.has(String(item))) &&
+			optional(attempt, "elapsedMs", isFiniteNumber) && optional(attempt, "firstEventMs", isFiniteNumber) &&
+			optional(attempt, "firstAssistantMs", isFiniteNumber) && optional(attempt, "toolElapsedMs", isFiniteNumber) &&
+			optional(attempt, "toolCallCount", (item) => Number.isInteger(item)) && optional(attempt, "timedOut", (item) => typeof item === "boolean") &&
+			optional(attempt, "terminationGraceMs", isFiniteNumber) && optional(attempt, "forcedTermination", (item) => typeof item === "boolean") &&
+			optional(attempt, "deadlineMs", isFiniteNumber) && optional(attempt, "configuredDeadlineMs", isFiniteNumber);
+	};
 	const lanes = value.filter((lane): lane is Record<string, unknown> => isObject(lane));
 	if (lanes.length !== value.length || lanes.some((lane) =>
 		!Number.isInteger(lane.generation) || typeof lane.key !== "string" || typeof lane.passId !== "string" ||
-		!new Set(["light", "medium", "heavy"]).has(String(lane.tier)) ||
+		!tiers.has(String(lane.tier)) ||
 		(lane.minorHygiene !== undefined && typeof lane.minorHygiene !== "boolean") || typeof lane.rawText !== "string" ||
-		!Number.isInteger(lane.exitCode) || !lifecycles.has(String(lane.lifecycle)) || !Array.isArray(lane.attempts) ||
-		lane.attempts.some((attempt) => !isObject(attempt) || !Number.isInteger(attempt.ordinal) ||
-			typeof attempt.rawText !== "string" || !Number.isInteger(attempt.exitCode) || !lifecycles.has(String(attempt.lifecycle)))
+		!Number.isInteger(lane.exitCode) || !lifecycles.has(String(lane.lifecycle)) ||
+		!Array.isArray(lane.attempts) || lane.attempts.some((attempt) => !validAttempt(attempt)) ||
+		!optional(lane, "requestedModel", isString) || !optional(lane, "observedModel", isString) ||
+		!optional(lane, "processSignal", isString) || !optional(lane, "stopReason", isString) ||
+		!optional(lane, "errorMessage", isString) || !optional(lane, "deadlineExpired", (item) => deadlineKinds.has(String(item))) ||
+		!optional(lane, "firstEventMs", isFiniteNumber) || !optional(lane, "firstAssistantMs", isFiniteNumber) ||
+		!optional(lane, "startOffsetMs", isFiniteNumber) || !optional(lane, "endOffsetMs", isFiniteNumber) ||
+		!optional(lane, "fallbackBudgetRejected", (item) => typeof item === "boolean") ||
+		!optional(lane, "deadlineSource", (item) => deadlineSources.has(String(item))) ||
+		!optional(lane, "batchDeadlineMs", isFiniteNumber) || !optional(lane, "totalDeadlineMs", isFiniteNumber)
 	)) return undefined;
 	return lanes as unknown as readonly ReviewLaneArtifact[];
 }
@@ -800,7 +830,8 @@ export class CompletedReviewCache {
 		const expectedLaneDescriptors = Array.isArray(value.expectedLaneDescriptors) &&
 			value.expectedLaneDescriptors.length <= 200 && value.expectedLaneDescriptors.every((lane) =>
 				isObject(lane) && typeof lane.key === "string" && !!lane.key &&
-				new Set(["light", "medium", "heavy"]).has(String(lane.tier)) && typeof lane.minorHygiene === "boolean") &&
+				new Set(["light", "medium", "heavy"]).has(String(lane.tier)) && typeof lane.minorHygiene === "boolean" &&
+				(lane.expectedOutput === undefined || lane.expectedOutput === "review_lane" || lane.expectedOutput === "nonempty")) &&
 			new Set(value.expectedLaneDescriptors.map((lane) => (lane as Record<string, unknown>).key)).size ===
 				value.expectedLaneDescriptors.length
 			? value.expectedLaneDescriptors as unknown as ExpectedReviewLane[]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-pr-review",
-  "version": "1.15.2",
+  "version": "1.15.3",
   "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

@@ -41,7 +41,7 @@ If the `review_subagents` batch tool is available, prefer it over multiple singl
 
 By default, and when `--balanced` is present, call `review_subagents` with `major_only: true`, `minor_hygiene: true`, and exactly these five passes: `overview`, `correctness`, `correctness-contracts`, `security-performance`, and `performance-resources`. Do **not** dispatch `conventions-maintainability`. For an ordinary diff use `max_parallel: 5`; for 200,000–399,999 byte multi-file diffs use `shard_count: 2` and `max_parallel: 10`; for diffs at least 400,000 bytes with at least three changed files use `shard_count: 3` and `max_parallel: 15`. The four heavy passes remain P0–P2-only. The overview remains context-only and may return at most three direct-diff P3/nit candidates; it must not use tools or conduct a repository audit.
 
-When `--deep` is present, call `review_subagents` with exactly one pass: id `deep-review`, `tier: heavy`, `tool_policy: configured`, `major_only: false`, `minor_hygiene: false`, `expected_output: "nonempty"`, and `max_parallel: 1`. The objective must be the integrated whole-PR review: read the complete diff and the PR's stated intent, explore the surrounding repository with configured tools (callers, tests, sibling implementations) as needed to confirm or refute each candidate, and return every substantiated finding from nit through P0 with severity proportional to real impact, in the reviewer's standard candidate-evidence field format (title, severity, why, location, side, confidence), preceded by a short overview of what the PR does, its strengths, and the highest-risk areas. When there are no findings, state that plainly in prose instead of emitting the fields — the nonempty completion contract accepts either shape. This pass replaces the Step 3 overview and every Step 5 lens: there is no separate overview lane and no sharding, whatever the diff size. You still own the terminal Markdown synthesis, verification handling, and final validation exactly as in any other mode.
+When `--deep` is present, call `review_subagents` with exactly one pass: id `deep-review`, `tier: heavy`, `tool_policy: configured`, `major_only: false`, `minor_hygiene: false`, `expected_output: "nonempty"`, and `max_parallel: 1`. The objective must be the integrated whole-PR review: read the complete diff and the PR's stated intent, explore the surrounding repository with configured tools (callers, tests, sibling implementations) as needed to confirm or refute each candidate, and return every substantiated finding from nit through P0 with severity proportional to real impact in the reviewer's standard candidate-evidence field format. The exact Markdown completion contract is fail-closed and explicit: the first nonblank line MUST be the top-level byte-exact `Review status: COMPLETE` with no leading or trailing whitespace when all required evidence was inspected; if required evidence could not be inspected for any reason, return the top-level byte-exact `Review status: INCOMPLETE` followed by a concise reason, and every non-COMPLETE/missing/duplicate/later/wrapped status is partial. Nonblank contract lines must not have trailing spaces or tabs. After COMPLETE, require exactly this order: one meaningful nonempty-line `Overview: ...`, `Strengths: ...`, and `Risk areas: ...` section (plain labels, bold labels, or an ATX label followed immediately by one top-level value line are accepted; no list-indented, quoted, fenced, HTML, or other wrapped framing), then either one top-level standalone uppercase `NO FINDINGS.` line or one or more complete candidate blocks. Candidate fields are exactly once and in order: `title` prefixed `[P0]`, `[P1]`, `[P2]`, `[P3]`, or `[nit]` with a tag matching `severity`; `severity` from `P0|P1|P2|P3|nit`; meaningful `why` (which may continue only on lines beginning with exactly two spaces plus a non-list character until the next reserved field); `location` as a safe repository-relative path plus a positive line or ordered positive line range, or `repo-wide`; `side` as `RIGHT|LEFT`; `in_diff` and `pr_related` as `yes|no`; and `confidence` as a decimal from `0.0` through `1.0`. Candidate labels may be plain/bold or use exactly one top-level `- ` list marker; arbitrary indentation and other list markers are invalid. Scalar and continuation values must not contain embedded status/field/severity/sentinel productions, code fences, HTML/container wrappers, blockquotes, lists, or code indentation. Do not emit arbitrary prose, code fences, blockquotes, JSON, HTML/container wrappers, duplicate/out-of-order/reserved productions, or placeholder values (`none`, `n/a`, `unavailable`, `unknown`, `skipped`, `error`, `review complete`); status/refusal/access/tool/model/error reasons belong in INCOMPLETE, while inability discussed inside a valid candidate why is allowed. COMPLETE is the primary contract; only obvious exact failure placeholders are deterministic defense-in-depth rejection. This pass replaces the Step 3 overview and every Step 5 lens: there is no separate overview lane and no sharding, whatever the diff size. You still own the terminal Markdown synthesis, verification handling, and final validation exactly as in any other mode.
 
 When `--major-only` is present, use the same five passes and parallelism with `major_only: true` and `minor_hygiene: false`. This removes P3/nit exploration without removing any major correctness/security/resource lens.