pi-subagents 0.34.0 → 0.35.0

package/src/runs/shared/acceptance.ts

@@ -9,7 +9,9 @@ import type {
 	AcceptanceLedger,
 	AcceptanceLevel,
 	AcceptanceReport,
+	AcceptanceRole,
 	AcceptanceRuntimeCheck,
+	AcceptanceRuntimeCheckStatus,
 	AcceptanceReviewResult,
 	AcceptanceVerifyCommand,
 	AcceptanceVerifyResult,
@@ -18,6 +20,7 @@ import type {
 	SingleResult,
 	SubagentRunMode,
 } from "../../shared/types.ts";
+import { classifyTaskMutationIntent, taskMayMutate } from "./task-intent.ts";
 
 const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
 	none: 0,
@@ -43,6 +46,7 @@ const ACCEPTANCE_CONFIG_KEYS = new Set(["level", "criteria", "evidence", "verify
 const ACCEPTANCE_GATE_KEYS = new Set(["id", "must", "evidence", "severity"]);
 const ACCEPTANCE_VERIFY_KEYS = new Set(["id", "command", "timeoutMs", "cwd", "env", "allowFailure"]);
 const ACCEPTANCE_REVIEW_KEYS = new Set(["agent", "focus", "required"]);
+const EXPLICIT_REVIEWED_UNAVAILABLE = "cannot be requested explicitly because this run cannot supply an independent reviewer result; use checked/verified and orchestrate the reviewer separately, or omit acceptance for read-only review tasks.";
 
 function normalizeLevel(level: AcceptanceLevel | undefined): Exclude<AcceptanceLevel, "auto"> | "auto" {
 	return level ?? "auto";
@@ -68,6 +72,7 @@ function requiredEvidenceForLevel(level: Exclude<AcceptanceLevel, "auto">): Acce
 
 function inferLevel(input: {
 	agentName: string;
+	acceptanceRole?: AcceptanceRole;
 	task?: string;
 	mode?: SubagentRunMode;
 	async?: boolean;
@@ -77,14 +82,27 @@ function inferLevel(input: {
 	const agent = input.agentName.toLowerCase();
 	const task = input.task?.toLowerCase() ?? "";
 	const reasons: string[] = [];
-	const readOnlyAgent = /\b(?:reviewer|scout|context-builder|researcher|analyst)\b/.test(agent);
-	const readOnlyTask = /\b(?:read[- ]only|review[- ]only|do not edit|don't edit|no edits|without edits|inspect|summari[sz]e)\b/.test(task);
-	const writeTask = /\b(?:fix|implement|update|write|edit|modify|migrate|release|security|delete|remove|refactor|commit)\b/.test(task)
-		|| /\bworker\b/.test(agent);
+	// Declared roles replace name heuristics, so use the full writer grammar to detect explicit mutation independently of the actual agent name.
+	const intent = classifyTaskMutationIntent(input.acceptanceRole ? "worker" : input.agentName, input.task ?? "");
+	const readOnlyTask = intent.kind === "read-only"
+		|| (intent.kind === "unknown" && /\b(?:read[- ]only|review[- ]only|no edits|without edits|inspect|summari[sz]e)\b/.test(task));
+	const rolePatchTask = input.acceptanceRole !== undefined
+		&& intent.kind !== "read-only"
+		&& !/\b(?:do not|don't|must not)\s+patch\b/.test(task)
+		&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(task);
+	const taskMayWrite = taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
+	const readOnlyAgent = input.acceptanceRole === "read-only"
+		|| (input.acceptanceRole === undefined && /\b(?:reviewer|scout|context-builder|researcher|analyst)\b/.test(agent));
+	const writeTask = taskMayWrite
+		|| (input.acceptanceRole === "writer" && !readOnlyTask)
+		|| (input.acceptanceRole === undefined && /\bworker\b/.test(agent) && !readOnlyTask);
+	const inferredReadOnly = readOnlyTask || (input.acceptanceRole === "read-only" && !taskMayWrite);
+	const roleResolvesReadOnly = input.acceptanceRole !== undefined && inferredReadOnly;
+	const keywordRiskReadOnly = input.acceptanceRole === undefined ? intent.kind === "read-only" : inferredReadOnly;
 	const risky = Boolean(input.async && writeTask)
-		|| Boolean(input.dynamic)
-		|| Boolean(input.dynamicGroup)
-		|| /\b(?:release|migration|migrate|security|data[- ]loss|destructive|post-review|fix pass)\b/.test(task);
+		|| (Boolean(input.dynamic) && !roleResolvesReadOnly)
+		|| (Boolean(input.dynamicGroup) && !roleResolvesReadOnly)
+		|| (!keywordRiskReadOnly && /\b(?:release|migration|migrate|security|data[- ]loss|destructive|post-review|fix pass)\b/.test(task));
 
 	if (risky) {
 		reasons.push(input.async ? "async write-capable or risky run" : "risky write-capable run");
@@ -98,7 +116,7 @@ function inferLevel(input: {
 		};
 	}
 	if (writeTask && !readOnlyTask) {
-		reasons.push("write-capable worker/task");
+		reasons.push(input.acceptanceRole === "writer" && !taskMayWrite ? "declared writer acceptance role" : "write-capable worker/task");
 		return {
 			level: "checked",
 			reasons,
@@ -107,7 +125,7 @@ function inferLevel(input: {
 		};
 	}
 	if (readOnlyAgent || readOnlyTask) {
-		reasons.push(readOnlyAgent ? "read-only/reviewer-style agent" : "read-only task wording");
+		reasons.push(input.acceptanceRole === "read-only" && !readOnlyTask ? "declared read-only acceptance role" : readOnlyAgent ? "read-only/reviewer-style agent" : "read-only task wording");
 		return {
 			level: "attested",
 			reasons,
@@ -141,6 +159,8 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	if (input === false) return errors;
 	if (typeof input === "string") {
 		if (!VALID_LEVELS.has(input as AcceptanceLevel)) errors.push(`${pathLabel} has invalid level '${input}'.`);
+		else if (input === "none") errors.push(`${pathLabel} level "none" requires a reason; use { level: "none", reason: "..." }.`);
+		else if (input === "reviewed") errors.push(`${pathLabel} ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 		return errors;
 	}
 	if (!input || typeof input !== "object" || Array.isArray(input)) {
@@ -157,9 +177,11 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	if (value.level === "none" && (typeof value.reason !== "string" || !value.reason.trim())) {
 		errors.push(`${pathLabel}.reason is required when level is none.`);
 	}
+	if (value.level === "reviewed") errors.push(`${pathLabel}.level ${EXPLICIT_REVIEWED_UNAVAILABLE}`);
 	if (value.reason !== undefined && typeof value.reason !== "string") errors.push(`${pathLabel}.reason must be a string.`);
 	if (value.criteria !== undefined && !Array.isArray(value.criteria)) errors.push(`${pathLabel}.criteria must be an array.`);
 	if (Array.isArray(value.criteria)) {
+		const criterionIds = new Set<string>();
 		for (const [index, criterion] of value.criteria.entries()) {
 			if (typeof criterion === "string") continue;
 			const criterionPath = `${pathLabel}.criteria[${index}]`;
@@ -171,7 +193,13 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 			for (const key of Object.keys(gate)) {
 				if (!ACCEPTANCE_GATE_KEYS.has(key)) errors.push(`${criterionPath}.${key} is not supported.`);
 			}
-			if (typeof gate.id !== "string" || !gate.id.trim()) errors.push(`${criterionPath}.id is required.`);
+			if (typeof gate.id !== "string" || !gate.id.trim()) {
+				errors.push(`${criterionPath}.id is required.`);
+			} else {
+				const normalizedId = normalizedToken(gate.id);
+				if (criterionIds.has(normalizedId)) errors.push(`${criterionPath}.id duplicates normalized criterion id '${normalizedId}'.`);
+				criterionIds.add(normalizedId);
+			}
 			if (typeof gate.must !== "string" || !gate.must.trim()) errors.push(`${criterionPath}.must is required.`);
 			if (gate.evidence !== undefined && !Array.isArray(gate.evidence)) errors.push(`${criterionPath}.evidence must be an array.`);
 			if (Array.isArray(gate.evidence)) {
@@ -248,6 +276,31 @@ export function validateAcceptanceInput(input: unknown, pathLabel = "acceptance"
 	return errors;
 }
 
+export function validateExecutionAcceptance(input: {
+	acceptance?: unknown;
+	tasks?: Array<{ acceptance?: unknown }>;
+	chain?: Array<{
+		acceptance?: unknown;
+		parallel?: Array<{ acceptance?: unknown }> | { acceptance?: unknown };
+	}>;
+}): string[] {
+	const errors = validateAcceptanceInput(input.acceptance, "acceptance");
+	for (const [index, task] of (input.tasks ?? []).entries()) {
+		errors.push(...validateAcceptanceInput(task.acceptance, `tasks[${index}].acceptance`));
+	}
+	for (const [stepIndex, step] of (input.chain ?? []).entries()) {
+		errors.push(...validateAcceptanceInput(step.acceptance, `chain[${stepIndex}].acceptance`));
+		if (Array.isArray(step.parallel)) {
+			for (const [taskIndex, task] of step.parallel.entries()) {
+				errors.push(...validateAcceptanceInput(task.acceptance, `chain[${stepIndex}].parallel[${taskIndex}].acceptance`));
+			}
+		} else if (step.parallel) {
+			errors.push(...validateAcceptanceInput(step.parallel.acceptance, `chain[${stepIndex}].parallel.acceptance`));
+		}
+	}
+	return errors;
+}
+
 function normalizeCriteria(criteria: Array<string | { id?: string; must?: string; evidence?: AcceptanceEvidenceKind[]; severity?: "required" | "recommended" }> | undefined, evidence: AcceptanceEvidenceKind[]): ResolvedAcceptanceGate[] {
 	return (criteria ?? []).map((criterion, index) => {
 		if (typeof criterion === "string") {
@@ -265,6 +318,7 @@ function normalizeCriteria(criteria: Array<string | { id?: string; must?: string
 export function resolveEffectiveAcceptance(input: {
 	explicit?: AcceptanceInput;
 	agentName: string;
+	acceptanceRole?: AcceptanceRole;
 	task?: string;
 	mode?: SubagentRunMode;
 	async?: boolean;
@@ -285,7 +339,7 @@ export function resolveEffectiveAcceptance(input: {
 		evidence,
 	);
 	let review = explicit.review !== undefined ? explicit.review : inferred.review;
-	if (level === "reviewed" && explicitLevel !== "auto" && explicitLevel !== "reviewed" && explicit.review === undefined && review && review !== false) {
+	if (level === "reviewed" && input.explicit !== undefined && explicitLevel !== "reviewed" && explicit.review === undefined && review && review !== false) {
 		review = { ...review, required: false };
 	}
 	return {
@@ -329,9 +383,14 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig): st
 		"",
 		"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
 		"Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
+		"`criteriaSatisfied[].status` must be exactly one of: satisfied, not-satisfied, not-applicable.",
+		"`commandsRun[].result` must be exactly one of: passed, failed, not-run.",
+		"`manualNotes` and `notes` are optional strings; an empty string means no note and does not satisfy `manual-notes` evidence.",
 		"```acceptance-report",
 		JSON.stringify({
-			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof" }],
+			criteriaSatisfied: acceptance.criteria
+				.filter((criterion) => criterion.severity !== "recommended")
+				.map((criterion) => ({ id: criterion.id, status: "satisfied", evidence: "specific proof" })),
 			changedFiles: ["src/file.ts"],
 			testsAddedOrUpdated: ["test/file.test.ts"],
 			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
@@ -372,38 +431,166 @@ function extractBalancedJson(text: string, start: number): string | undefined {
 	return undefined;
 }
 
-function unwrapAcceptanceReport(value: unknown): unknown {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
-	const record = value as { acceptance?: unknown; "acceptance-report"?: unknown };
-	if ("acceptance" in record) return record.acceptance;
-	if ("acceptance-report" in record) return record["acceptance-report"];
+const ACCEPTANCE_REPORT_WRAPPERS = new Set(["acceptance", "acceptance-report", "acceptance_report", "acceptanceReport"]);
+
+const ACCEPTANCE_REPORT_FIELDS: Record<string, keyof AcceptanceReport> = {
+	criteriaSatisfied: "criteriaSatisfied",
+	criteria_satisfied: "criteriaSatisfied",
+	changedFiles: "changedFiles",
+	changed_files: "changedFiles",
+	testsAddedOrUpdated: "testsAddedOrUpdated",
+	tests_added_or_updated: "testsAddedOrUpdated",
+	commandsRun: "commandsRun",
+	commands_run: "commandsRun",
+	validationOutput: "validationOutput",
+	validation_output: "validationOutput",
+	residualRisks: "residualRisks",
+	residual_risks: "residualRisks",
+	noStagedFiles: "noStagedFiles",
+	no_staged_files: "noStagedFiles",
+	diffSummary: "diffSummary",
+	diff_summary: "diffSummary",
+	reviewFindings: "reviewFindings",
+	review_findings: "reviewFindings",
+	manualNotes: "manualNotes",
+	manual_notes: "manualNotes",
+	notes: "notes",
+};
+
+const CRITERION_REPORT_FIELDS = new Set(["id", "status", "evidence"]);
+const COMMAND_REPORT_FIELDS = new Set(["command", "result", "summary"]);
+
+function normalizedToken(value: string): string {
+	return value.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/-+/g, "-");
+}
+
+function normalizeCriterionStatus(value: unknown): unknown {
+	if (typeof value !== "string") return value;
+	const token = normalizedToken(value);
+	if (["satisfied", "met", "complete", "completed", "done", "pass", "passed", "success", "succeeded"].includes(token)) return "satisfied";
+	if (["not-satisfied", "not-met", "unmet", "incomplete", "fail", "failed"].includes(token)) return "not-satisfied";
+	if (["not-applicable", "n-a", "na", "skip", "skipped"].includes(token)) return "not-applicable";
 	return value;
 }
 
-function isCommandsRunArray(value: unknown): value is NonNullable<AcceptanceReport["commandsRun"]> {
-	return Array.isArray(value) && value.every((item) => {
-		if (!item || typeof item !== "object" || Array.isArray(item)) return false;
-		const command = item as { command?: unknown; result?: unknown; summary?: unknown };
-		return typeof command.command === "string"
-			&& (command.result === "passed" || command.result === "failed" || command.result === "not-run")
-			&& typeof command.summary === "string";
-	});
+function normalizeCommandResult(value: unknown): unknown {
+	if (typeof value !== "string") return value;
+	const token = normalizedToken(value);
+	if (["passed", "pass", "success", "successful", "succeeded", "ok"].includes(token)) return "passed";
+	if (["failed", "fail", "failure", "error"].includes(token)) return "failed";
+	if (["not-run", "not-executed", "skip", "skipped"].includes(token)) return "not-run";
+	return value;
+}
+
+function normalizeCriterionReport(value: unknown, pathLabel: string, errors: string[]): unknown {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const normalized: Record<string, unknown> = {};
+	for (const [key, fieldValue] of Object.entries(value as Record<string, unknown>)) {
+		if (!CRITERION_REPORT_FIELDS.has(key)) {
+			errors.push(`${pathLabel}.${key}: unsupported acceptance criterion field`);
+			continue;
+		}
+		normalized[key] = key === "id" && typeof fieldValue === "string"
+			? normalizedToken(fieldValue)
+			: key === "status"
+				? normalizeCriterionStatus(fieldValue)
+				: fieldValue;
+	}
+	return normalized;
+}
+
+function normalizeCommandReport(value: unknown, pathLabel: string, errors: string[]): unknown {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+	const normalized: Record<string, unknown> = {};
+	for (const [key, fieldValue] of Object.entries(value as Record<string, unknown>)) {
+		if (!COMMAND_REPORT_FIELDS.has(key)) {
+			errors.push(`${pathLabel}.${key}: unsupported acceptance command field`);
+			continue;
+		}
+		normalized[key] = key === "result" ? normalizeCommandResult(fieldValue) : fieldValue;
+	}
+	return normalized;
+}
+
+function normalizeAcceptanceReportValue(value: unknown, pathLabel = ""): { value: unknown; pathLabel: string; errors: string[] } {
+	const errors: string[] = [];
+	let reportValue = value;
+	let reportPath = pathLabel;
+	if (reportValue && typeof reportValue === "object" && !Array.isArray(reportValue)) {
+		const record = reportValue as Record<string, unknown>;
+		const wrapperKeys = Object.keys(record).filter((key) => ACCEPTANCE_REPORT_WRAPPERS.has(key));
+		if (wrapperKeys.length > 0) {
+			const wrapperKey = wrapperKeys[0]!;
+			if (wrapperKeys.length > 1) errors.push(`${pathLabel || "acceptance-report"}: multiple acceptance report wrappers are ambiguous`);
+			for (const key of Object.keys(record)) {
+				if (key !== wrapperKey) errors.push(`${pathFor(pathLabel, key)}: unsupported alongside acceptance report wrapper '${wrapperKey}'`);
+			}
+			reportValue = record[wrapperKey];
+			reportPath = pathFor(pathLabel, wrapperKey);
+		}
+	}
+	if (!reportValue || typeof reportValue !== "object" || Array.isArray(reportValue)) return { value: reportValue, pathLabel: reportPath, errors };
+
+	const normalized: Record<string, unknown> = {};
+	for (const [key, fieldValue] of Object.entries(reportValue as Record<string, unknown>)) {
+		const canonical = ACCEPTANCE_REPORT_FIELDS[key];
+		if (!canonical) {
+			errors.push(`${pathFor(reportPath, key)}: unsupported acceptance report field`);
+			continue;
+		}
+		if (Object.hasOwn(normalized, canonical)) {
+			errors.push(`${pathFor(reportPath, key)}: duplicates normalized field '${canonical}'`);
+			continue;
+		}
+		const fieldPath = pathFor(reportPath, canonical);
+		switch (canonical) {
+			case "criteriaSatisfied": {
+				const items = Array.isArray(fieldValue) ? fieldValue : fieldValue && typeof fieldValue === "object" ? [fieldValue] : fieldValue;
+				normalized[canonical] = Array.isArray(items)
+					? items.map((item, index) => normalizeCriterionReport(item, `${fieldPath}[${index}]`, errors))
+					: items;
+				break;
+			}
+			case "commandsRun": {
+				const items = Array.isArray(fieldValue) ? fieldValue : fieldValue && typeof fieldValue === "object" ? [fieldValue] : fieldValue;
+				normalized[canonical] = Array.isArray(items)
+					? items.map((item, index) => normalizeCommandReport(item, `${fieldPath}[${index}]`, errors))
+					: items;
+				break;
+			}
+			case "changedFiles":
+			case "testsAddedOrUpdated":
+			case "validationOutput":
+			case "residualRisks":
+			case "reviewFindings":
+				normalized[canonical] = typeof fieldValue === "string" ? [fieldValue] : fieldValue;
+				break;
+			case "noStagedFiles": {
+				const token = typeof fieldValue === "string" ? fieldValue.trim().toLowerCase() : undefined;
+				normalized[canonical] = token === "true" ? true : token === "false" ? false : fieldValue;
+				break;
+			}
+			default:
+				normalized[canonical] = fieldValue;
+		}
+	}
+	return { value: normalized, pathLabel: reportPath, errors };
 }
 
 function hasGenericAcceptanceReportSignal(value: unknown): boolean {
 	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
 	const record = value as Record<string, unknown>;
-	return "criteriaSatisfied" in record && (
-		isStringArray(record.changedFiles)
-		|| isStringArray(record.testsAddedOrUpdated)
-		|| isCommandsRunArray(record.commandsRun)
-		|| isStringArray(record.validationOutput)
-		|| isStringArray(record.residualRisks)
-		|| typeof record.noStagedFiles === "boolean"
-		|| typeof record.diffSummary === "string"
-		|| isStringArray(record.reviewFindings)
-		|| typeof record.manualNotes === "string"
-	);
+	return "criteriaSatisfied" in record && [
+		"changedFiles",
+		"testsAddedOrUpdated",
+		"commandsRun",
+		"validationOutput",
+		"residualRisks",
+		"noStagedFiles",
+		"diffSummary",
+		"reviewFindings",
+		"manualNotes",
+	].some((key) => key in record);
 }
 
 function parseReportJson(body: string): unknown {
@@ -426,30 +613,29 @@ function fencedBlocks(output: string, tag: string): string[] {
 		.filter((value): value is string => Boolean(value));
 }
 
-function validationPathLabelForWrapper(value: unknown): string {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return "";
-	const record = value as Record<string, unknown>;
-	if ("acceptance" in record) return "acceptance";
-	if ("acceptance-report" in record) return "acceptance-report";
-	return "";
-}
-
 function parseAcceptanceReportBody(body: string): { report?: AcceptanceReport; errors: string[] } {
-	const parsed = parseReportJson(body);
-	const report = unwrapAcceptanceReport(parsed);
-	return validateAcceptanceReport(report, validationPathLabelForWrapper(parsed));
+	return validateAcceptanceReport(parseReportJson(body));
 }
 
-function parseGenericJsonAcceptanceReportBody(body: string): AcceptanceReport | undefined {
+function parseGenericJsonAcceptanceReportBody(body: string): { report?: AcceptanceReport; error?: string } {
 	const parsed = parseReportJson(body);
-	const report = unwrapAcceptanceReport(parsed);
-	const validation = validateAcceptanceReport(report);
-	if (!validation.report) return undefined;
-	return hasGenericAcceptanceReportSignal(validation.report) ? validation.report : undefined;
+	const normalized = normalizeAcceptanceReportValue(parsed);
+	const hasCriteriaMarker = normalized.value !== null
+		&& typeof normalized.value === "object"
+		&& !Array.isArray(normalized.value)
+		&& "criteriaSatisfied" in normalized.value;
+	if (!hasGenericAcceptanceReportSignal(normalized.value) && !(hasCriteriaMarker && normalized.errors.length > 0)) return {};
+	const validation = validateAcceptanceReport(parsed);
+	return validation.report
+		? { report: validation.report }
+		: { error: `Invalid acceptance-report: ${validation.errors.join("; ")}` };
 }
 
+export const ACCEPTANCE_REPORT_NOT_FOUND = "Structured acceptance report not found.";
+
 export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
-	const fenced = fencedBlocks(output, "acceptance-report");
+	const explicitFencePresent = /```acceptance[-_]report\b/i.test(output);
+	const fenced = fencedBlocks(output, "acceptance[-_]report");
 	const parseErrors: string[] = [];
 	for (const body of fenced) {
 		try {
@@ -461,38 +647,65 @@ export function parseAcceptanceReport(output: string): { report?: AcceptanceRepo
 		}
 	}
 	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	if (explicitFencePresent) {
+		return { error: "Failed to parse acceptance-report: Empty or unterminated acceptance-report fence." };
+	}
 	for (const body of fencedBlocks(output, "(?:json|jsonc|json5)")) {
 		try {
-			const report = parseGenericJsonAcceptanceReportBody(body);
-			if (report) return { report };
+			const parsed = parseGenericJsonAcceptanceReportBody(body);
+			if (parsed.report) return { report: parsed.report };
+			if (parsed.error) return { error: `Failed to parse acceptance-report: ${parsed.error}` };
 		} catch {
-			// Ignore unrelated or malformed generic JSON fences; only explicit
-			// acceptance-report fences should turn parse failures into blockers.
+			// Ignore unrelated malformed generic JSON. A recognizable report shape
+			// returns exact validation errors above instead of being mistaken for prose.
 		}
 	}
 	const markerIndex = output.search(/ACCEPTANCE_REPORT\s*:/i);
 	if (markerIndex !== -1) {
 		const jsonStart = output.indexOf("{", markerIndex);
-			if (jsonStart !== -1) {
-				const json = extractBalancedJson(output, jsonStart);
-				if (json) {
-					try {
-						const parsed = JSON.parse(json) as unknown;
-						const report = unwrapAcceptanceReport(parsed);
-						const validation = validateAcceptanceReport(report, validationPathLabelForWrapper(parsed));
-						if (validation.report) return { report: validation.report };
-						return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
-					} catch (error) {
-						return { error: error instanceof Error ? error.message : String(error) };
-					}
-				}
-			}
+		if (jsonStart === -1) {
+			return { error: "Failed to parse acceptance-report: Expected a JSON object after ACCEPTANCE_REPORT:." };
 		}
-	return { error: "Structured acceptance report not found." };
+		const json = extractBalancedJson(output, jsonStart);
+		if (!json) {
+			return { error: "Failed to parse acceptance-report: Unterminated JSON object after ACCEPTANCE_REPORT:." };
+		}
+		try {
+			const parsed = JSON.parse(json) as unknown;
+			const validation = validateAcceptanceReport(parsed);
+			if (validation.report) return { report: validation.report };
+			return { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return { error: `Failed to parse acceptance-report: ${message}` };
+		}
+	}
+	return { error: ACCEPTANCE_REPORT_NOT_FOUND };
+}
+
+function parseAcceptanceReportSources(
+	output: string,
+	fileOutput: { content: string; path: string; authoritative?: boolean } | undefined,
+): { report?: AcceptanceReport; error?: string } {
+	const fromText = () => parseAcceptanceReport(output);
+	const fromFile = () => {
+		if (!fileOutput) return { error: ACCEPTANCE_REPORT_NOT_FOUND };
+		const parsed = parseAcceptanceReport(fileOutput.content);
+		return parsed.report || parsed.error === ACCEPTANCE_REPORT_NOT_FOUND
+			? parsed
+			: { error: `${parsed.error} (in configured output ${fileOutput.path})` };
+	};
+	const [primary, secondary] = fileOutput?.authoritative ? [fromFile, fromText] : [fromText, fromFile];
+	const first = primary();
+	// A malformed report in the primary source is a defect to surface, not a
+	// miss to paper over with the secondary source; only a genuinely absent
+	// report falls through.
+	if (first.report || first.error !== ACCEPTANCE_REPORT_NOT_FOUND) return first;
+	return secondary();
 }
 
 export function stripAcceptanceReport(output: string): string {
-	const trailingFencePattern = /\n?```(acceptance-report|json|jsonc|json5)\s*\n([\s\S]*?)```\s*/gi;
+	const trailingFencePattern = /\n?```(acceptance[-_]report|json|jsonc|json5)\s*\n([\s\S]*?)```\s*/gi;
 	let trailingFence: { index: number; tag: string; body: string } | undefined;
 	for (const match of output.matchAll(trailingFencePattern)) {
 		const end = (match.index ?? 0) + match[0].length;
@@ -501,15 +714,15 @@ export function stripAcceptanceReport(output: string): string {
 		}
 	}
 	if (trailingFence) {
-		if (trailingFence.tag === "acceptance-report") return output.slice(0, trailingFence.index).trimEnd();
+		if (trailingFence.tag === "acceptance-report" || trailingFence.tag === "acceptance_report") return output.slice(0, trailingFence.index).trimEnd();
 		try {
-			if (parseGenericJsonAcceptanceReportBody(trailingFence.body)) return output.slice(0, trailingFence.index).trimEnd();
+			if (parseGenericJsonAcceptanceReportBody(trailingFence.body).report) return output.slice(0, trailingFence.index).trimEnd();
 		} catch {
 			// Leave unrelated or malformed generic JSON fences visible.
 		}
 	}
 	return output
-		.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
+		.replace(/\n?```acceptance[-_]report\s*\n[\s\S]*?```\s*$/i, "")
 		.replace(/\n?ACCEPTANCE_REPORT\s*:\s*\{[\s\S]*\}\s*$/i, "")
 		.trimEnd();
 }
@@ -544,12 +757,15 @@ function validateStringArrayField(errors: string[], value: unknown, pathLabel: s
 		return;
 	}
 	for (const [index, item] of value.entries()) {
-		if (typeof item !== "string") pushTypeError(errors, `${pathLabel}[${index}]`, "string", item);
+		if (typeof item !== "string" || !item.trim()) pushTypeError(errors, `${pathLabel}[${index}]`, "non-empty string", item);
 	}
 }
 
 function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: AcceptanceReport; errors: string[] } {
-	const errors: string[] = [];
+	const normalized = normalizeAcceptanceReportValue(value, pathLabel);
+	value = normalized.value;
+	pathLabel = normalized.pathLabel;
+	const errors = normalized.errors;
 	if (!value || typeof value !== "object" || Array.isArray(value)) {
 		pushTypeError(errors, pathLabel || "acceptance-report", "object", value);
 		return { errors };
@@ -559,6 +775,7 @@ function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: Ac
 		if (!Array.isArray(report.criteriaSatisfied)) {
 			pushTypeError(errors, pathFor(pathLabel, "criteriaSatisfied"), "array", report.criteriaSatisfied);
 		} else {
+			const criterionIds = new Set<string>();
 			for (const [index, item] of report.criteriaSatisfied.entries()) {
 				const itemPath = `${pathFor(pathLabel, "criteriaSatisfied")}[${index}]`;
 				if (!item || typeof item !== "object" || Array.isArray(item)) {
@@ -566,7 +783,12 @@ function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: Ac
 					continue;
 				}
 				const criterion = item as { id?: unknown; status?: unknown; evidence?: unknown };
-				if (criterion.id !== undefined && typeof criterion.id !== "string") pushTypeError(errors, `${itemPath}.id`, "string", criterion.id);
+				if (criterion.id !== undefined && typeof criterion.id !== "string") {
+					pushTypeError(errors, `${itemPath}.id`, "string", criterion.id);
+				} else if (typeof criterion.id === "string" && criterion.id) {
+					if (criterionIds.has(criterion.id)) errors.push(`${itemPath}.id: duplicate normalized criterion id '${criterion.id}'`);
+					criterionIds.add(criterion.id);
+				}
 				if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable") {
 					pushTypeError(errors, `${itemPath}.status`, "one of \"satisfied\", \"not-satisfied\", \"not-applicable\"", criterion.status);
 				}
@@ -591,14 +813,14 @@ function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: Ac
 				if (command.result !== "passed" && command.result !== "failed" && command.result !== "not-run") {
 					pushTypeError(errors, `${itemPath}.result`, "one of \"passed\", \"failed\", \"not-run\"", command.result);
 				}
-				if (typeof command.summary !== "string") pushTypeError(errors, `${itemPath}.summary`, "string", command.summary);
+				if (typeof command.summary !== "string" || !command.summary.trim()) pushTypeError(errors, `${itemPath}.summary`, "non-empty string", command.summary);
 			}
 		}
 	}
 	if (report.validationOutput !== undefined) validateStringArrayField(errors, report.validationOutput, pathFor(pathLabel, "validationOutput"));
 	if (report.residualRisks !== undefined) validateStringArrayField(errors, report.residualRisks, pathFor(pathLabel, "residualRisks"));
 	if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean") pushTypeError(errors, pathFor(pathLabel, "noStagedFiles"), "boolean", report.noStagedFiles);
-	if (report.diffSummary !== undefined && typeof report.diffSummary !== "string") pushTypeError(errors, pathFor(pathLabel, "diffSummary"), "string", report.diffSummary);
+	if (report.diffSummary !== undefined && (typeof report.diffSummary !== "string" || !report.diffSummary.trim())) pushTypeError(errors, pathFor(pathLabel, "diffSummary"), "non-empty string", report.diffSummary);
 	if (report.reviewFindings !== undefined) validateStringArrayField(errors, report.reviewFindings, pathFor(pathLabel, "reviewFindings"));
 	if (report.manualNotes !== undefined && typeof report.manualNotes !== "string") pushTypeError(errors, pathFor(pathLabel, "manualNotes"), "string", report.manualNotes);
 	if (report.notes !== undefined && typeof report.notes !== "string") pushTypeError(errors, pathFor(pathLabel, "notes"), "string", report.notes);
@@ -620,26 +842,30 @@ function validateAcceptanceReport(value: unknown, pathLabel = ""): { report?: Ac
 }
 
 function checkCriteriaSatisfied(criteria: ResolvedAcceptanceGate[], report: AcceptanceReport): AcceptanceRuntimeCheck[] {
-	const reports = new Map((report.criteriaSatisfied ?? []).filter((item) => item.id).map((item) => [item.id!, item]));
+	const reports = new Map((report.criteriaSatisfied ?? []).filter((item) => item.id).map((item) => [normalizedToken(item.id!), item]));
 	return criteria.filter((criterion) => criterion.severity !== "recommended").map((criterion) => {
-		const item = reports.get(criterion.id);
+		const item = reports.get(normalizedToken(criterion.id));
 		if (!item) return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was not reported.` };
 		if (item.status !== "satisfied") return { id: `criterion:${criterion.id}`, status: "failed", message: `Required criterion '${criterion.id}' was reported as ${item.status}.` };
 		return { id: `criterion:${criterion.id}`, status: "passed", message: `Required criterion '${criterion.id}' satisfied.` };
 	});
 }
 
-function reportEvidencePresent(report: AcceptanceReport, kind: AcceptanceEvidenceKind): boolean {
+function reportEvidenceStatus(report: AcceptanceReport, kind: AcceptanceEvidenceKind): AcceptanceRuntimeCheckStatus {
 	switch (kind) {
-		case "changed-files": return isStringArray(report.changedFiles) && report.changedFiles.length > 0;
-		case "tests-added": return isStringArray(report.testsAddedOrUpdated) && report.testsAddedOrUpdated.length > 0;
-		case "commands-run": return Array.isArray(report.commandsRun) && report.commandsRun.length > 0;
-		case "validation-output": return isStringArray(report.validationOutput) && report.validationOutput.length > 0;
-		case "residual-risks": return isStringArray(report.residualRisks);
-		case "no-staged-files": return report.noStagedFiles === true;
-		case "diff-summary": return typeof report.diffSummary === "string" && report.diffSummary.trim().length > 0;
-		case "review-findings": return isStringArray(report.reviewFindings);
-		case "manual-notes": return Boolean((report.manualNotes ?? report.notes)?.trim());
+		case "changed-files":
+			if (!isStringArray(report.changedFiles)) return "failed";
+			return report.changedFiles.length === 0 ? "not-applicable" : "passed";
+		case "tests-added":
+			if (!isStringArray(report.testsAddedOrUpdated)) return "failed";
+			return report.testsAddedOrUpdated.length === 0 ? "not-applicable" : "passed";
+		case "commands-run": return Array.isArray(report.commandsRun) && report.commandsRun.length > 0 ? "passed" : "failed";
+		case "validation-output": return isStringArray(report.validationOutput) && report.validationOutput.length > 0 ? "passed" : "failed";
+		case "residual-risks": return isStringArray(report.residualRisks) ? "passed" : "failed";
+		case "no-staged-files": return report.noStagedFiles === true ? "passed" : "failed";
+		case "diff-summary": return typeof report.diffSummary === "string" && report.diffSummary.trim().length > 0 ? "passed" : "failed";
+		case "review-findings": return isStringArray(report.reviewFindings) ? "passed" : "failed";
+		case "manual-notes": return Boolean((report.manualNotes ?? report.notes)?.trim()) ? "passed" : "failed";
 	}
 }
 
@@ -657,11 +883,15 @@ function checkNoStagedFiles(cwd: string): AcceptanceRuntimeCheck {
 function runStructuralChecks(acceptance: ResolvedAcceptanceConfig, report: AcceptanceReport, cwd: string): AcceptanceRuntimeCheck[] {
 	const checks: AcceptanceRuntimeCheck[] = [];
 	for (const kind of acceptance.evidence) {
-		const present = reportEvidencePresent(report, kind);
+		const status = reportEvidenceStatus(report, kind);
 		checks.push({
 			id: `evidence:${kind}`,
-			status: present ? "passed" : "failed",
-			message: present ? `${kind} evidence present.` : `${kind} evidence missing from child report.`,
+			status,
+			message: status === "passed"
+				? `${kind} evidence present.`
+				: status === "not-applicable"
+					? `${kind} evidence explicitly reported as not applicable.`
+					: `${kind} evidence missing from child report.`,
 		});
 	}
 	if (acceptance.evidence.includes("no-staged-files")) checks.push(checkNoStagedFiles(cwd));
@@ -788,6 +1018,13 @@ export async function evaluateAcceptance(input: {
 	acceptance: ResolvedAcceptanceConfig;
 	output: string;
 	cwd: string;
+	/**
+	 * Content the child sent to its configured output file (from its own write
+	 * tool calls, not from disk, so a concurrent writer to the same path cannot
+	 * be misattributed). Searched for the acceptance report; searched before
+	 * the assistant output when `authoritative` (outputMode "file-only").
+	 */
+	fileOutput?: { content: string; path: string; authoritative?: boolean };
 	report?: AcceptanceReport;
 	reviewResult?: AcceptanceReviewResult;
 	signal?: AbortSignal;
@@ -805,7 +1042,14 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
-	const parsed = input.report ? { report: input.report } : parseAcceptanceReport(input.output);
+	const parsed = input.report
+		? (() => {
+			const validation = validateAcceptanceReport(input.report);
+			return validation.report
+				? { report: validation.report }
+				: { error: `Failed to parse acceptance-report: Invalid acceptance-report: ${validation.errors.join("; ")}` };
+		})()
+		: parseAcceptanceReportSources(input.output, input.fileOutput);
 	if (parsed.report) {
 		ledger.childReport = parsed.report;
 		ledger.status = "attested";
@@ -867,6 +1111,20 @@ export async function evaluateAcceptance(input: {
 	return ledger;
 }
 
+export function buildSkippedAcceptanceLedger(acceptance: ResolvedAcceptanceConfig, input: { id: string; message: string }): AcceptanceLedger {
+	return {
+		status: acceptance.level === "none" ? "not-required" : "rejected",
+		explicit: acceptance.explicit,
+		effectiveAcceptance: acceptance,
+		inferredReason: acceptance.inferredReason,
+		criteria: acceptance.criteria,
+		runtimeChecks: acceptance.level === "none"
+			? []
+			: [{ id: input.id, status: "failed", message: input.message }],
+		verifyRuns: [],
+	};
+}
+
 export function acceptanceFailureMessage(ledger: AcceptanceLedger): string | undefined {
 	if (ledger.status !== "rejected") return undefined;
 	const failedCheck = ledger.runtimeChecks.find((check) => check.status === "failed");