@agwab/pi-workflow 0.1.2 → 0.2.0

package/workflows/deep-research/helpers/render-executive.mjs

@@ -10,10 +10,11 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 function findSource(sources, stageId) {
-	for (const [specId, source] of Object.entries(sources ?? {})) {
-		if (specId === stageId || specId.startsWith(`${stageId}.`)) return source;
-	}
-	return null;
+	const entries = Object.entries(sources ?? {});
+	const exact = entries.find(([specId]) => specId === stageId);
+	if (exact) return exact[1];
+	const dotted = entries.find(([specId]) => specId.startsWith(`${stageId}.`));
+	return dotted?.[1] ?? null;
 }
 
 function asArray(value) {
@@ -33,6 +34,9 @@ function flattenItems(value) {
 		"finding",
 		"claim",
 		"note",
+		"reason",
+		"nextStep",
+		"evidenceState",
 		"whyItMatters",
 		"parentImpact",
 		"recommendation",
@@ -46,6 +50,16 @@ function flattenItems(value) {
 	) {
 		return [value];
 	}
+	if (
+		value.id ||
+		value.gapId ||
+		value.slotId ||
+		Array.isArray(value.relatedFactSlotIds) ||
+		Array.isArray(value.sourceUrls) ||
+		Array.isArray(value.sourceRefs)
+	) {
+		return [value];
+	}
 	return Object.values(value).flatMap((item) => flattenItems(item));
 }
 
@@ -83,6 +97,37 @@ function stringifyItem(item) {
 	return cleanText(String(item)) || "(empty item)";
 }
 
+function summaryText(report, fallback) {
+	const summary = report?.summary;
+	if (typeof summary === "string" && summary.trim()) return cleanText(summary);
+	if (isRecord(summary)) {
+		const parts = [
+			summary.directAnswer,
+			summary.answer,
+			summary.summary,
+			summary.finding,
+		]
+			.filter((value) => typeof value === "string" && value.trim())
+			.map(cleanText);
+		const confidence = cleanText(summary.confidence ?? "");
+		const caveat = cleanText(summary.keyCaveat ?? summary.caveat ?? "");
+		return (
+			[
+				parts[0],
+				confidence ? `Confidence: ${confidence}.` : undefined,
+				caveat ? `Key caveat: ${caveat}.` : undefined,
+			]
+				.filter(Boolean)
+				.join(" ") || stringifyItem(summary)
+		);
+	}
+	return cleanText(fallback ?? "Research completed with audited evidence.");
+}
+
+function hasObjectSerializationArtifact(text) {
+	return /\[object Object\]/.test(String(text ?? ""));
+}
+
 function truncateWords(text, maxWords) {
 	const items = words(text);
 	if (items.length <= maxWords) return cleanText(text);
@@ -156,6 +201,61 @@ function urlsOf(item, limit = 3) {
 	return uniqueStructuredUrls(item).slice(0, limit);
 }
 
+function normalizeLocalRef(value) {
+	if (typeof value !== "string") return null;
+	const text = value.trim();
+	if (!text || /^https?:\/\//i.test(text) || isWorkflowSourceRefText(text))
+		return null;
+	const stripped = text.replace(/^(?:file|repo):/i, "");
+	if (!/[\w./-]+\.[\w]+(?:#L\d+(?:-L?\d+)?)?$/i.test(stripped)) return null;
+	return stripped;
+}
+
+function isWorkflowSourceRefText(value) {
+	return /^wsrc_[a-z0-9]{16,}$/i.test(String(value ?? "").trim());
+}
+
+function collectLocalRefs(value, refs = []) {
+	if (!value || typeof value !== "object") return refs;
+	if (Array.isArray(value)) {
+		for (const item of value) collectLocalRefs(item, refs);
+		return refs;
+	}
+	for (const [key, item] of Object.entries(value)) {
+		if (/^(files?|paths?|sourceRefs?|sourceUrls?|sources?)$/i.test(key)) {
+			for (const candidate of asArray(item).length ? item : [item]) {
+				const ref = normalizeLocalRef(candidate);
+				if (ref) refs.push(ref);
+				else if (candidate && typeof candidate === "object")
+					collectLocalRefs(candidate, refs);
+			}
+			continue;
+		}
+		if (item && typeof item === "object") collectLocalRefs(item, refs);
+	}
+	return refs;
+}
+
+function localRefsOf(item, limit = 3) {
+	const out = [];
+	const seen = new Set();
+	for (const ref of collectLocalRefs(item, [])) {
+		if (seen.has(ref)) continue;
+		seen.add(ref);
+		out.push(ref);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+
+function referenceList(item, limit = 3) {
+	const urls = markdownLinkList(urlsOf(item, limit), limit);
+	const localRefs = localRefsOf(item, limit)
+		.map((ref) => `\`${ref}\``)
+		.join(", ");
+	return [urls, localRefs].filter(Boolean).join("; ");
+}
+
 function markdownLinkList(urls, maxItems = 3) {
 	return urls
 		.slice(0, maxItems)
@@ -195,19 +295,54 @@ function finiteNumber(value) {
 	return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+function normalizeClaimStatus(status) {
+	const text = cleanText(status).toLowerCase();
+	if (!text) return "";
+	if (text.includes("conflict")) return "conflicting";
+	if (text.includes("unsupported")) return "unsupported";
+	if (text.includes("partial")) return "partially_supported";
+	if (text.includes("verified")) return "verified";
+	return text;
+}
+
 function coverageCounts(coverage, fallback) {
 	if (!coverage || typeof coverage !== "object") return null;
-	return {
+	const counts = {
 		total: finiteNumber(coverage.verificationCandidates) ?? fallback.total,
 		verified: finiteNumber(coverage.verified) ?? fallback.verified,
 		partially_supported:
-			finiteNumber(coverage.partiallySupported) ?? fallback.partially_supported,
+			finiteNumber(coverage.partiallySupported) ??
+			finiteNumber(coverage.partially_supported) ??
+			fallback.partially_supported,
 		unsupported: finiteNumber(coverage.unsupported) ?? fallback.unsupported,
 		conflicting: finiteNumber(coverage.conflicting) ?? fallback.conflicting,
 	};
+	if (counts.total == null) {
+		counts.total =
+			counts.verified +
+			counts.partially_supported +
+			counts.unsupported +
+			counts.conflicting;
+	}
+	return counts;
 }
 
-function claimCounts(control) {
+function packetVerdictCounts(packet, fallback) {
+	const verdicts = packet?.verdictCounts;
+	if (!isRecord(verdicts)) return null;
+	const counts = coverageCounts(verdicts, fallback);
+	if (!counts) return null;
+	counts.total =
+		finiteNumber(packet?.invariantChecks?.candidateCount) ??
+		finiteNumber(verdicts.total) ??
+		counts.verified +
+			counts.partially_supported +
+			counts.unsupported +
+			counts.conflicting;
+	return counts;
+}
+
+function claimCounts(control, packet) {
 	const claims = asArray(control?.claimVerdictIndex?.claims);
 	const counts = {
 		total: claims.length,
@@ -217,9 +352,12 @@ function claimCounts(control) {
 		conflicting: 0,
 	};
 	for (const claim of claims) {
-		const status = claim?.status;
+		const status = normalizeClaimStatus(claim?.status);
 		if (status && Object.hasOwn(counts, status)) counts[status] += 1;
 	}
+	const packetCounts = packetVerdictCounts(packet, counts);
+	if (packetCounts) return packetCounts;
+
 	const coverage = coverageCounts(
 		control?.finalReport?.coverageSummary,
 		counts,
@@ -259,6 +397,326 @@ function factSlotSummary(factSlots) {
 	};
 }
 
+function stringArray(value, limit = Infinity) {
+	const out = [];
+	const seen = new Set();
+	for (const item of asArray(value)) {
+		if (typeof item !== "string") continue;
+		const text = item.trim();
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		out.push(text);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+
+function uniqueStrings(values, limit = Infinity) {
+	const out = [];
+	const seen = new Set();
+	for (const value of values) {
+		if (typeof value !== "string") continue;
+		const text = value.trim();
+		if (!text || seen.has(text)) continue;
+		seen.add(text);
+		out.push(text);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+
+function packetOf(packetSource) {
+	return isRecord(packetSource?.packet) ? packetSource.packet : {};
+}
+
+function claimIdOf(row) {
+	return cleanText(row?.id ?? row?.claimId ?? "");
+}
+
+function gapIdOf(row) {
+	return cleanText(row?.id ?? row?.gapId ?? "");
+}
+
+function claimLedger(packet, control) {
+	const packetLedger = asArray(packet?.claimVerdictLedger);
+	return packetLedger.length
+		? packetLedger
+		: asArray(control?.claimVerdictIndex?.claims);
+}
+
+function mapById(rows, idFn) {
+	const out = new Map();
+	for (const row of rows) {
+		const id = idFn(row);
+		if (id && !out.has(id)) out.set(id, row);
+	}
+	return out;
+}
+
+function numberedId(prefix, index) {
+	return `${prefix}-${String(index + 1).padStart(3, "0")}`;
+}
+
+function packetGapRows(packet) {
+	const remaining = asArray(packet?.remainingGaps).map((gap, index) => ({
+		id: gapIdOf(gap) || numberedId("gap-remaining", index),
+		kind: "Gap",
+		...gap,
+	}));
+	const coverage = asArray(packet?.coverageGaps).map((gap, index) => ({
+		id: gapIdOf(gap) || numberedId("gap-coverage", index),
+		kind: "Coverage gap",
+		...gap,
+	}));
+	return [...remaining, ...coverage];
+}
+
+function rowsForIds(ids, rowById, warnings, label) {
+	const rows = [];
+	for (const id of ids) {
+		const row = rowById.get(id);
+		if (row) {
+			rows.push(row);
+			continue;
+		}
+		warnings.push({
+			section: "references",
+			label,
+			total: 1,
+			rendered: 0,
+			missingId: id,
+		});
+	}
+	return rows;
+}
+
+function claimSourceUrls(rows, limit = 8) {
+	return uniqueStrings(
+		rows.flatMap((row) => [...asArray(row?.sourceUrls), ...urlsOf(row, limit)]),
+		limit,
+	);
+}
+
+function claimSourceRefs(rows, limit = 8) {
+	return uniqueStrings(
+		rows.flatMap((row) => asArray(row?.sourceRefs)),
+		limit,
+	);
+}
+
+function evidenceStrength(status) {
+	switch (normalizeClaimStatus(status)) {
+		case "verified":
+			return 3;
+		case "partially_supported":
+			return 2;
+		case "unsupported":
+			return 1;
+		case "conflicting":
+			return 0;
+		default:
+			return -1;
+	}
+}
+
+function evidenceStatusFromRows(rows, fallback) {
+	if (rows.length === 0) return cleanText(fallback) || "not specified";
+	let weakest = "verified";
+	let weakestScore = Infinity;
+	for (const row of rows) {
+		const status = normalizeClaimStatus(row?.status ?? row?.verdict);
+		const score = evidenceStrength(status);
+		if (score >= 0 && score < weakestScore) {
+			weakest = status;
+			weakestScore = score;
+		}
+	}
+	return weakestScore === Infinity
+		? cleanText(fallback) || "not specified"
+		: weakest;
+}
+
+function claimToFinding(row) {
+	return {
+		id: claimIdOf(row),
+		finding: cleanText(row?.claim ?? row?.support ?? stringifyItem(row)),
+		evidenceStatus: normalizeClaimStatus(row?.status) || row?.status,
+		confidence: row?.confidence,
+		sourceUrls: asArray(row?.sourceUrls),
+		sourceRefs: asArray(row?.sourceRefs),
+		rationale: row?.support,
+		caveat: row?.caveat,
+		correctionOrCounterclaim: row?.correctionOrCounterclaim,
+	};
+}
+
+function supportingClaimIds(item) {
+	return uniqueStrings([
+		...asArray(item?.supportingClaimIds),
+		...asArray(item?.claimIds),
+		...asArray(item?.relatedClaimIds),
+	]);
+}
+
+function withSupportingEvidence(item, claimRows) {
+	return {
+		...item,
+		evidenceStatus: evidenceStatusFromRows(claimRows, item?.evidenceStatus),
+		sourceUrls: uniqueStrings(
+			[...asArray(item?.sourceUrls), ...claimSourceUrls(claimRows)],
+			8,
+		),
+		sourceRefs: uniqueStrings(
+			[...asArray(item?.sourceRefs), ...claimSourceRefs(claimRows)],
+			8,
+		),
+	};
+}
+
+function coverageSummaryFromPacket(packet, fallback = {}) {
+	const counts = packetVerdictCounts(packet, {
+		total: 0,
+		verified: 0,
+		partially_supported: 0,
+		unsupported: 0,
+		conflicting: 0,
+	});
+	if (!counts) return fallback;
+	return {
+		...fallback,
+		verified: counts.verified,
+		partiallySupported: counts.partially_supported,
+		unsupported: counts.unsupported,
+		conflicting: counts.conflicting,
+		verificationCandidates: counts.total,
+		depth: packet?.researchMetadataSeed?.depth ?? fallback.depth,
+		researchQuestions:
+			packet?.researchMetadataSeed?.researchQuestions ??
+			fallback.researchQuestions,
+		preserved:
+			packet?.overflowLedger?.preservedClaimCount ?? fallback.preserved,
+		coverageGaps:
+			packet?.overflowLedger?.coverageGapCount ?? fallback.coverageGaps,
+	};
+}
+
+function composeResearchReport(control, packetSource) {
+	const packet = packetOf(packetSource);
+	const legacyReport = control?.finalReport ?? {};
+	const synthesis = isRecord(control?.synthesis) ? control.synthesis : null;
+	const ledger = claimLedger(packet, control);
+	const claimById = mapById(ledger, claimIdOf);
+	const gapRows = packetGapRows(packet);
+	const gapById = mapById(gapRows, gapIdOf);
+	const warnings = [];
+
+	if (!synthesis) {
+		const report = { ...legacyReport };
+		if (asArray(packet.factSlotCoverage).length > 0)
+			report.factSlotCoverage = packet.factSlotCoverage;
+		if (isRecord(packet.researchMetadataSeed))
+			report.researchMetadata = packet.researchMetadataSeed;
+		if (isRecord(packet.verdictCounts))
+			report.coverageSummary = coverageSummaryFromPacket(
+				packet,
+				report.coverageSummary,
+			);
+		if (asArray(report.remainingGaps).length === 0 && gapRows.length > 0)
+			report.remainingGaps = gapRows;
+		if (
+			asArray(report.researchScopeCoverage).length === 0 &&
+			asArray(packet.researchScopeCoverage).length > 0
+		) {
+			report.researchScopeCoverage = packet.researchScopeCoverage;
+		}
+		return { report, packet, ledger, warnings };
+	}
+
+	const keyFindingIds = stringArray(synthesis.keyFindingIds, 12);
+	const keyFindingRows = keyFindingIds.length
+		? rowsForIds(keyFindingIds, claimById, warnings, "key findings")
+		: ledger
+				.filter((row) => normalizeClaimStatus(row?.status) === "verified")
+				.slice(0, 8);
+	const mapOverlayItems = (items, textField) =>
+		asArray(items).map((item) => {
+			const ids = supportingClaimIds(item);
+			const rows = rowsForIds(ids, claimById, warnings, textField);
+			return withSupportingEvidence(item, rows);
+		});
+	const caveatNotes = asArray(synthesis.caveatNotes).map((item) => {
+		const rows = rowsForIds(
+			supportingClaimIds(item),
+			claimById,
+			warnings,
+			"caveat notes",
+		);
+		const gaps = rowsForIds(
+			stringArray(item?.gapIds, 12),
+			gapById,
+			warnings,
+			"gap notes",
+		);
+		return withSupportingEvidence(
+			{
+				...item,
+				relatedGaps: gaps,
+			},
+			rows,
+		);
+	});
+	const optionalUnsupported = rowsForIds(
+		stringArray(synthesis.notableUnsupportedClaimIds, 12),
+		claimById,
+		warnings,
+		"unsupported claims",
+	).map(claimToFinding);
+	const optionalContested = rowsForIds(
+		stringArray(synthesis.contestedClaimIds, 12),
+		claimById,
+		warnings,
+		"contested claims",
+	).map(claimToFinding);
+	const derivedUnsupported = ledger
+		.filter((row) => normalizeClaimStatus(row?.status) === "unsupported")
+		.map(claimToFinding);
+	const derivedContested = ledger
+		.filter((row) => normalizeClaimStatus(row?.status) === "conflicting")
+		.map(claimToFinding);
+
+	return {
+		report: {
+			summary: synthesis.bottomLine ?? control?.digest,
+			researchMetadata: packet.researchMetadataSeed ?? {},
+			coverageSummary: coverageSummaryFromPacket(packet, {}),
+			factSlotCoverage: asArray(packet.factSlotCoverage),
+			mainFindings: keyFindingRows.map(claimToFinding),
+			recommendations: mapOverlayItems(
+				synthesis.recommendations,
+				"recommendations",
+			),
+			actionPlan: mapOverlayItems(synthesis.actionPlan, "action plan"),
+			caveatedFindings: caveatNotes,
+			contestedAreas: optionalContested.length
+				? optionalContested
+				: derivedContested,
+			notableUnsupportedClaims: optionalUnsupported.length
+				? optionalUnsupported
+				: derivedUnsupported,
+			unverifiedButRelevant: asArray(packet.preservedClaims),
+			parentDecisionNotes: mapOverlayItems(
+				synthesis.parentDecisionNotes,
+				"decision notes",
+			),
+			researchScopeCoverage: asArray(packet.researchScopeCoverage),
+			remainingGaps: gapRows,
+		},
+		packet,
+		ledger,
+		warnings,
+	};
+}
+
 function statusRank(item) {
 	const status =
 		`${item?.evidenceStatus ?? item?.status ?? item?.confidence ?? ""}`.toLowerCase();
@@ -295,9 +753,7 @@ function renderEvidenceStrength(report) {
 			slot.label ?? slot.slotId ?? slot.bestValue ?? "Evidence area",
 		);
 		const status = escapeTableCell(evidenceStatusOf(slot));
-		const evidence = escapeTableCell(
-			markdownLinkList(urlsOf(slot, 2), 2) || "—",
-		);
+		const evidence = escapeTableCell(referenceList(slot, 2) || "—");
 		const impact = escapeTableCell(
 			slot.parentImpact ?? slot.whyItMatters ?? slot.notes ?? "",
 		);
@@ -353,7 +809,7 @@ function renderMainFindings(report) {
 	findings.forEach(({ item: finding, text }, index) => {
 		const status = evidenceStatusOf(finding);
 		const confidence = confidenceOf(finding);
-		const urls = markdownLinkList(urlsOf(finding, 4), 4);
+		const urls = referenceList(finding, 4);
 		out.push(`### ${index + 1}. ${text}`);
 		out.push("");
 		out.push(
@@ -378,7 +834,7 @@ function renderRecommendations(report) {
 	const out = ["## Recommendations", ""];
 	recommendations.forEach(({ item, text }, index) => {
 		const status = evidenceStatusOf(item);
-		const urls = markdownLinkList(urlsOf(item, 4), 4);
+		const urls = referenceList(item, 4);
 		out.push(`${index + 1}. **${text}**`);
 		out.push(`   - Evidence status: ${status || "not specified"}`);
 		if (urls) out.push(`   - Sources: ${urls}`);
@@ -394,7 +850,7 @@ function renderActionPlan(report) {
 	actions.forEach(({ item, text }, index) => {
 		const numericStep = Number(item?.step);
 		const step = Number.isFinite(numericStep) ? numericStep : index + 1;
-		const urls = markdownLinkList(urlsOf(item, 3), 3);
+		const urls = referenceList(item, 3);
 		const evidence = evidenceStatusOf(item);
 		out.push(`${step}. ${text}`);
 		if (evidence && evidence !== "not specified")
@@ -405,21 +861,52 @@ function renderActionPlan(report) {
 	return out;
 }
 
+function fallbackCaveatText(item) {
+	if (!isRecord(item)) return stringifyItem(item);
+	const id = cleanText(item.id ?? item.gapId ?? "");
+	const slotIds = uniqueStrings([
+		item.slotId,
+		...asArray(item.relatedFactSlotIds),
+	]).join(", ");
+	const kind = cleanText(item.kind ?? "gap");
+	return (
+		[kind, id, slotIds ? `related slots: ${slotIds}` : undefined]
+			.filter(Boolean)
+			.join(" — ") || stringifyItem(item)
+	);
+}
+
 function caveatText(item) {
 	return itemText(
 		item,
-		["gap", "finding", "claim", "note", "whyItMatters", "parentImpact"],
-		stringifyItem(item),
+		[
+			"gap",
+			"finding",
+			"claim",
+			"note",
+			"reason",
+			"nextStep",
+			"evidenceState",
+			"whyItMatters",
+			"parentImpact",
+		],
+		fallbackCaveatText(item),
 	);
 }
 
 function caveatCategories(report) {
 	return [
 		{ kind: "Gap", items: flattenItems(report.remainingGaps) },
-		{ kind: "Unsupported", items: flattenItems(report.notableUnsupportedClaims) },
+		{
+			kind: "Unsupported",
+			items: flattenItems(report.notableUnsupportedClaims),
+		},
 		{ kind: "Contested", items: flattenItems(report.contestedAreas) },
 		{ kind: "Caveat", items: flattenItems(report.caveatedFindings) },
-		{ kind: "Unverified lead", items: flattenItems(report.unverifiedButRelevant) },
+		{
+			kind: "Unverified lead",
+			items: flattenItems(report.unverifiedButRelevant),
+		},
 		{ kind: "Decision note", items: flattenItems(report.parentDecisionNotes) },
 	]
 		.map((category) => ({
@@ -450,7 +937,7 @@ function renderCaveats(report) {
 	if (selection.total === 0) return [];
 	const out = ["## Caveats and remaining gaps", ""];
 	for (const { kind, item, text } of selection.selected) {
-		const urls = markdownLinkList(urlsOf(item, 3), 3);
+		const urls = referenceList(item, 3);
 		out.push(`- **${kind}:** ${text}${urls ? ` (${urls})` : ""}`);
 	}
 	out.push("");
@@ -475,8 +962,8 @@ function renderSourceIndex(sourceIndex) {
 	return out;
 }
 
-function renderAuditSummary(control, claimSummary, slots) {
-	const coverage = control?.finalReport?.coverageSummary ?? {};
+function renderAuditSummary(report, claimSummary, slots) {
+	const coverage = report?.coverageSummary ?? {};
 	const mismatches = asArray(claimSummary.coverageSummaryMismatch);
 	return [
 		"## Audit summary",
@@ -493,7 +980,7 @@ function renderAuditSummary(control, claimSummary, slots) {
 		...(coverage.researchQuestions != null
 			? [`- Research questions: ${coverage.researchQuestions}.`]
 			: []),
-		"- Audit artifact: `final-audit.control.json`.",
+		"- Audit artifact: `audit.md`.",
 		"",
 	];
 }
@@ -521,9 +1008,10 @@ function renderWarnings(sectionCounts) {
 		}));
 }
 
-function renderResearchMarkdown(control, options = {}) {
-	const report = control?.finalReport ?? {};
-	const claimSummary = claimCounts(control);
+function renderResearchMarkdown(control, packetSource, options = {}) {
+	const composed = composeResearchReport(control, packetSource);
+	const report = composed.report;
+	const claimSummary = claimCounts(control, composed.packet);
 	const factSlots = sortedFactSlots(report);
 	const slots = factSlotSummary(asArray(report.factSlotCoverage));
 	const findings = mainFindingEntries(report);
@@ -541,7 +1029,7 @@ function renderResearchMarkdown(control, options = {}) {
 		report.remainingGaps,
 		report.parentDecisionNotes,
 		report.unverifiedButRelevant,
-		control?.claimVerdictIndex?.claims,
+		composed.ledger,
 	);
 	const maxUrls = Number.isFinite(Number(options.maxUrls))
 		? Math.max(0, Number(options.maxUrls))
@@ -569,18 +1057,14 @@ function renderResearchMarkdown(control, options = {}) {
 		sourceUrls: allSourceIndex.length,
 		renderedSourceUrls: sourceIndex.length,
 	};
-	const warnings = renderWarnings(sectionCounts);
+	const warnings = [...renderWarnings(sectionCounts), ...composed.warnings];
 
 	const sections = [
 		"# Research report",
 		"",
 		"## Bottom line",
 		"",
-		cleanText(
-			report.summary ??
-				control.digest ??
-				"Research completed with audited evidence.",
-		),
+		summaryText(report, control.digest),
 		"",
 		...renderEvidenceStrength(report),
 		...renderMainFindings(report),
@@ -588,7 +1072,7 @@ function renderResearchMarkdown(control, options = {}) {
 		...renderActionPlan(report),
 		...renderCaveats(report),
 		...renderSourceIndex(sourceIndex),
-		...renderAuditSummary(control, claimSummary, slots),
+		...renderAuditSummary(report, claimSummary, slots),
 	];
 
 	const markdown = sections
@@ -610,10 +1094,128 @@ function stripLeadingHeading(markdown) {
 	return String(markdown ?? "").replace(/^#\s+[^\n]+\n*/i, "");
 }
 
-export default async function renderExecutive({ sources, options = {}, context = {} }) {
+function synthesisClaimRows(control, rows) {
+	const synthesis = isRecord(control?.synthesis) ? control.synthesis : null;
+	if (!synthesis) return asArray(control?.claimVerdictIndex?.claims);
+	const rowById = mapById(rows, claimIdOf);
+	const ids = uniqueStrings([
+		...asArray(synthesis.keyFindingIds),
+		...asArray(synthesis.notableUnsupportedClaimIds),
+		...asArray(synthesis.contestedClaimIds),
+		...asArray(synthesis.recommendations).flatMap(supportingClaimIds),
+		...asArray(synthesis.actionPlan).flatMap(supportingClaimIds),
+		...asArray(synthesis.caveatNotes).flatMap(supportingClaimIds),
+		...asArray(synthesis.parentDecisionNotes).flatMap(supportingClaimIds),
+	]);
+	return ids.map((id) => rowById.get(id)).filter(Boolean);
+}
+
+function renderAuditMarkdown(control, packetSource, rendered) {
+	const packet = packetSource?.packet ?? {};
+	const report = control?.finalReport ?? {};
+	const ledger = asArray(packet.claimVerdictLedger);
+	const claims = synthesisClaimRows(control, ledger);
+	const gaps = asArray(packet.remainingGaps).length
+		? asArray(packet.remainingGaps)
+		: asArray(report.remainingGaps);
+	const sourceRefJoinFailures = asArray(packet.sourceRefJoinFailures).filter(
+		(failure) => uniqueStructuredUrls(failure).length > 0,
+	);
+	const factSlots = asArray(packet.factSlotCoverage).length
+		? asArray(packet.factSlotCoverage)
+		: asArray(report.factSlotCoverage);
+	const rows = ledger.length ? ledger : claims;
+	const out = [
+		"# Research audit",
+		"",
+		"This artifact preserves the detailed claim/gap/source ledger behind `executive.md`.",
+		"",
+		"## Claim verdict ledger",
+		"",
+	];
+	if (rows.length > 0) {
+		out.push(
+			"| ID | Status | Claim/support | Caveat/source |",
+			"|---|---|---|---|",
+		);
+		for (const row of rows) {
+			const id = escapeTableCell(row.id ?? row.claimId ?? "—");
+			const status = escapeTableCell(row.status ?? row.confidence ?? "—");
+			const support = escapeTableCell(
+				row.claim ??
+					row.support ??
+					row.verdictDigest?.support ??
+					stringifyItem(row),
+			);
+			const caveat = escapeTableCell(
+				row.caveat ??
+					row.correctionOrCounterclaim ??
+					markdownLinkList(urlsOf(row, 3), 3) ??
+					"—",
+			);
+			out.push(`| ${id} | ${status} | ${support} | ${caveat || "—"} |`);
+		}
+	} else {
+		out.push("No compact claim ledger was provided.");
+	}
+	out.push("", "## Fact slot coverage", "");
+	if (factSlots.length > 0) {
+		out.push(
+			"| Slot | Status | Best value | Gap/impact |",
+			"|---|---|---|---|",
+		);
+		for (const slot of factSlots) {
+			out.push(
+				`| ${escapeTableCell(slot.slotId ?? slot.label ?? "—")} | ${escapeTableCell(slot.status ?? "—")} | ${escapeTableCell(isRecord(slot.bestValue) ? stringifyItem(slot.bestValue) : (slot.bestValue ?? "—"))} | ${escapeTableCell(slot.gapReason || slot.parentImpact || "—")} |`,
+			);
+		}
+	} else {
+		out.push("No fact-slot ledger was provided.");
+	}
+	out.push("", "## Remaining gaps", "");
+	if (gaps.length > 0) {
+		for (const gap of gaps)
+			out.push(`- ${caveatText(gap) || stringifyItem(gap)}`);
+	} else {
+		out.push("No remaining gaps were reported.");
+	}
+	if (claims.length > 0 && ledger.length > 0) {
+		out.push("", "## Claims used in executive synthesis", "");
+		for (const claim of claims) {
+			out.push(
+				`- **${cleanText(claim.id ?? "claim")}** (${cleanText(claim.status ?? "unknown")}): ${cleanText(claim.claim ?? claim.support ?? stringifyItem(claim))}`,
+			);
+		}
+	}
+	if (sourceRefJoinFailures.length > 0) {
+		out.push("", "## Source reference join failures", "");
+		for (const failure of sourceRefJoinFailures)
+			out.push(`- ${caveatText(failure) || stringifyItem(failure)}`);
+	}
+	out.push(
+		"",
+		"## Renderer diagnostics",
+		"",
+		`- Executive word count: ${countWords(rendered.markdown)}.`,
+		`- Rendered source URLs: ${rendered.sourceIndex.length}/${rendered.allSourceIndex.length}.`,
+		`- Render warnings: ${rendered.renderWarnings.length}.`,
+		"",
+	);
+	return out
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+export default async function renderExecutive({
+	sources,
+	options = {},
+	context = {},
+}) {
 	const control =
 		findSource(sources, "final-audit") ??
 		sources?.[Object.keys(sources ?? {})[0]];
+	const auditPacket = findSource(sources, "final-audit-packet");
 	if (!control || typeof control !== "object") {
 		return {
 			schema: "deep-research-executive-render-v1",
@@ -623,13 +1225,32 @@ export default async function renderExecutive({ sources, options = {}, context =
 			blockers: ["missing final-audit control source"],
 			executiveMarkdown: "",
 			reportMarkdown: "",
+			auditMarkdown: "",
 			wordCount: 0,
 			sourceUrlCount: 0,
+			totalSourceUrlCount: 0,
+			sourceUrls: [],
+			sourceIndex: [],
+			claimSummary: {
+				total: 0,
+				verified: 0,
+				partially_supported: 0,
+				unsupported: 0,
+				conflicting: 0,
+			},
+			factSlotSummary: {
+				total: 0,
+				filled: 0,
+				partial: 0,
+				missingOrConflicting: 0,
+			},
+			sectionCounts: {},
 			renderWarnings: [],
 			gates: {
 				renderedAllStructuredItems: false,
 				passed: false,
 			},
+			auditArtifact: "final-audit.control.json",
 		};
 	}
 
@@ -650,13 +1271,17 @@ export default async function renderExecutive({ sources, options = {}, context =
 			? Math.max(0, Number(options.maxGaps))
 			: undefined,
 	};
-	const rendered = renderResearchMarkdown(control, opts);
+	const rendered = renderResearchMarkdown(control, auditPacket, opts);
 	let markdown = rendered.markdown;
 	let truncated = false;
 	if (Number.isFinite(opts.maxWords) && countWords(markdown) > opts.maxWords) {
 		truncated = true;
 		markdown = truncateWords(markdown, opts.maxWords);
 	}
+	const auditMarkdown = renderAuditMarkdown(control, auditPacket, rendered);
+	const serializationArtifact =
+		hasObjectSerializationArtifact(markdown) ||
+		hasObjectSerializationArtifact(auditMarkdown);
 	const wordCount = countWords(markdown);
 	const sourceUrlCount = rendered.sourceIndex.length;
 	const substantiveRenderWarnings = rendered.renderWarnings.filter(
@@ -665,10 +1290,14 @@ export default async function renderExecutive({ sources, options = {}, context =
 	const renderedAllStructuredItems = substantiveRenderWarnings.length === 0;
 	const truncatedWithOpenGaps =
 		truncated && Number(rendered.sectionCounts.caveatsAndGaps ?? 0) > 0;
-	const passed = renderedAllStructuredItems && !truncatedWithOpenGaps;
+	const passed =
+		renderedAllStructuredItems &&
+		!truncatedWithOpenGaps &&
+		!serializationArtifact;
 
 	let executiveSidecarPath;
 	let reportSidecarPath;
+	let auditSidecarPath;
 	try {
 		if (context.cwd && context.runId && context.taskId) {
 			const taskDir = join(
@@ -682,8 +1311,10 @@ export default async function renderExecutive({ sources, options = {}, context =
 			await mkdir(taskDir, { recursive: true });
 			executiveSidecarPath = join(taskDir, "executive.md");
 			reportSidecarPath = join(taskDir, "report.md");
+			auditSidecarPath = join(taskDir, "audit.md");
 			await writeFile(executiveSidecarPath, `${markdown}\n`, "utf8");
 			await writeFile(reportSidecarPath, `${markdown}\n`, "utf8");
+			await writeFile(auditSidecarPath, `${auditMarkdown}\n`, "utf8");
 		}
 	} catch {
 		// Sidecars are non-authoritative; keep control output deterministic.
@@ -696,6 +1327,7 @@ export default async function renderExecutive({ sources, options = {}, context =
 		renderMode: "evidence-backed-report",
 		executiveMarkdown: markdown,
 		reportMarkdown: markdown,
+		auditMarkdown,
 		wordCount,
 		sourceUrlCount,
 		totalSourceUrlCount: rendered.allSourceIndex.length,
@@ -717,10 +1349,12 @@ export default async function renderExecutive({ sources, options = {}, context =
 			maxGaps: opts.maxGaps,
 			truncated,
 			truncatedWithOpenGaps,
+			serializationArtifact,
 			passed,
 		},
-		auditArtifact: "final-audit.control.json",
+		auditArtifact: auditSidecarPath ? "audit.md" : "final-audit.control.json",
 		...(executiveSidecarPath ? { sidecarPath: "executive.md" } : {}),
 		...(reportSidecarPath ? { reportSidecarPath: "report.md" } : {}),
+		...(auditSidecarPath ? { auditSidecarPath: "audit.md" } : {}),
 	};
 }