@roodriigoooo/pi-scrutiny 0.1.0

package/extensions/scrutiny/scout.ts

@@ -0,0 +1,314 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { ScrutinyParams, ScrutinySummary, ScrutinySurface } from "./types.js";
+import { scrutinyDataDir, truncate } from "./util.js";
+
+type ExecLike = (command: string, args: string[], options?: { timeout?: number; signal?: AbortSignal }) => Promise<{ stdout?: string; stderr?: string; code?: number; killed?: boolean }>;
+
+type Anchors = {
+	files: string[];
+	symbols: string[];
+	terms: string[];
+	reasons: string[];
+};
+
+type Candidate = {
+	kind: "file" | "match" | "prior";
+	title: string;
+	score: number;
+	why: string[];
+	preview?: string;
+};
+
+const MAX_SCOUT_CHARS = 4_000;
+const MAX_CANDIDATES = 12;
+const MAX_RG_MATCHES = 80;
+const MAX_PATTERN_PARTS = 12;
+const MAX_DIFF_FILES = 30;
+const MAX_PRIOR_RUNS = 3;
+
+export async function buildContextScoutSection(input: {
+	params: ScrutinyParams;
+	surface: ScrutinySurface;
+	cwd: string;
+	exec: ExecLike;
+	signal?: AbortSignal;
+}): Promise<string | undefined> {
+	if (input.surface === "verify") return undefined;
+	const explicit = extractExplicitAnchors(`${input.params.prompt}\n${input.params.context ?? ""}`);
+	const diffFiles = await readDiffFiles(input.exec, input.signal);
+	const anchors = buildAnchors({ text: input.params.prompt, explicitFiles: explicit.files, explicitSymbols: explicit.symbols, diffFiles });
+
+	if (anchors.files.length === 0 && anchors.symbols.length === 0 && anchors.terms.length === 0) {
+		return [
+			"## Context scout",
+			"skipped: no `@file`, path, symbol-like term, prompt keyword, or git diff file found. ask user to choose scope before broad repo scan.",
+		].join("\n");
+	}
+
+	const candidates: Candidate[] = [];
+	for (const file of diffFiles.slice(0, MAX_DIFF_FILES)) candidates.push({ kind: "file", title: file, score: 10, why: ["git diff file"] });
+	for (const file of explicit.files) candidates.push({ kind: "file", title: file, score: 12, why: ["explicit file anchor"] });
+	candidates.push(...await rgCandidates(input.cwd, input.exec, anchors, input.signal));
+	candidates.push(...await pathCandidates(input.cwd, input.exec, anchors, input.signal));
+	candidates.push(...await priorRunCandidates(input.cwd, anchors));
+
+	const ranked = dedupeCandidates(candidates).sort((a, b) => b.score - a.score || a.title.localeCompare(b.title)).slice(0, MAX_CANDIDATES);
+	return renderScout(anchors, ranked);
+}
+
+function buildAnchors(input: { text: string; explicitFiles: string[]; explicitSymbols: string[]; diffFiles: string[] }): Anchors {
+	const symbols = unique([...input.explicitSymbols, ...extractSymbols(input.text)]).slice(0, 12);
+	const files = unique([...input.explicitFiles, ...input.diffFiles]).slice(0, 40);
+	const terms = extractTerms(input.text, symbols, files).slice(0, 12);
+	const reasons = [
+		input.explicitFiles.length ? "explicit file refs" : undefined,
+		input.explicitSymbols.length || symbols.length ? "prompt symbols" : undefined,
+		input.diffFiles.length ? "git diff files" : undefined,
+		terms.length ? "prompt keywords" : undefined,
+	].filter((item): item is string => Boolean(item));
+	return { files, symbols, terms, reasons };
+}
+
+function extractExplicitAnchors(text: string): { files: string[]; symbols: string[] } {
+	const files: string[] = [];
+	const symbols: string[] = [];
+	for (const match of text.matchAll(/@([^\s`'"),;]+)/g)) {
+		const value = match[1].replace(/^\/+/, "");
+		if (looksLikePath(value)) files.push(value.replace(/^\.\//, ""));
+		else if (/^[A-Za-z_$][A-Za-z0-9_$.:-]*$/.test(value)) symbols.push(value.replace(/[:.].*$/, ""));
+	}
+	for (const match of text.matchAll(/(^|[\s([{"'`])((?:\.{1,2}\/)?(?:[A-Za-z0-9_.@+-]+\/)+[A-Za-z0-9_.@+-]+\.[A-Za-z0-9]+)(?=[:\s)'"`,.;]|$)/g)) {
+		const file = normalizeFile(match[2]);
+		if (file) files.push(file);
+	}
+	return { files: unique(files), symbols: unique(symbols) };
+}
+
+function extractSymbols(text: string): string[] {
+	const symbols: string[] = [];
+	for (const match of text.matchAll(/`([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)?)`/g)) symbols.push(match[1]);
+	for (const match of text.matchAll(/\b([A-Z][A-Za-z0-9]+(?:[A-Z][A-Za-z0-9]+)+|[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*)\b/g)) symbols.push(match[1]);
+	return symbols.filter((symbol) => symbol.length >= 4 && !STOP.has(symbol.toLowerCase()));
+}
+
+function extractTerms(text: string, symbols: string[], files: string[]): string[] {
+	const skip = new Set(symbols.map((symbol) => symbol.toLowerCase()));
+	for (const file of files) for (const part of file.toLowerCase().split(/[^a-z0-9]+/)) skip.add(part);
+	return unique((text.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) ?? [])
+		.filter((term) => !STOP.has(term) && !skip.has(term) && term.length <= 40));
+}
+
+async function readDiffFiles(exec: ExecLike, signal?: AbortSignal): Promise<string[]> {
+	try {
+		const inside = await exec("git", ["rev-parse", "--is-inside-work-tree"], { timeout: 3_000, signal });
+		if (inside.code !== 0 || inside.stdout?.trim() !== "true") return [];
+		const result = await exec("git", ["diff", "--name-only", "HEAD", "--"], { timeout: 5_000, signal });
+		const stdout = result.stdout?.trim() ? result.stdout : (await exec("git", ["diff", "--name-only", "--"], { timeout: 5_000, signal })).stdout;
+		return unique((stdout ?? "").split(/\r?\n/).map(normalizeFile).filter((file): file is string => Boolean(file))).slice(0, MAX_DIFF_FILES);
+	} catch {
+		return [];
+	}
+}
+
+async function rgCandidates(cwd: string, exec: ExecLike, anchors: Anchors, signal?: AbortSignal): Promise<Candidate[]> {
+	const patternParts = unique([...anchors.symbols, ...anchors.terms]).slice(0, MAX_PATTERN_PARTS);
+	if (patternParts.length === 0) return [];
+	const pattern = patternParts.map(escapeRegex).join("|");
+	try {
+		const result = await exec("rg", [
+			"--json", "-n", "-S", "--max-count", "3", "--max-filesize", "1M",
+			"--glob", "!node_modules/**", "--glob", "!.git/**", "--glob", "!.pi/scrutiny/**",
+			"--glob", "!package-lock.json", "--glob", "!pnpm-lock.yaml", "--glob", "!yarn.lock", "--glob", "!bun.lockb",
+			pattern, ".",
+		], { timeout: 6_000, signal });
+		return parseRgMatches(cwd, result.stdout ?? "", anchors);
+	} catch {
+		return [];
+	}
+}
+
+function parseRgMatches(cwd: string, stdout: string, anchors: Anchors): Candidate[] {
+	const candidates: Candidate[] = [];
+	const anchorFiles = new Set(anchors.files);
+	const terms = new Set([...anchors.terms, ...anchors.symbols].map((item) => item.toLowerCase()));
+	for (const line of stdout.split(/\r?\n/)) {
+		if (candidates.length >= MAX_RG_MATCHES) break;
+		if (!line.trim()) continue;
+		let event: any;
+		try { event = JSON.parse(line); } catch { continue; }
+		if (event.type !== "match") continue;
+		const file = normalizeFile(path.relative(cwd, path.resolve(cwd, event.data?.path?.text ?? "")));
+		if (!file) continue;
+		const lineNumber = Number(event.data?.line_number ?? 0) || undefined;
+		const text = String(event.data?.lines?.text ?? "").trim();
+		const why: string[] = [];
+		let score = 1;
+		if (anchorFiles.has(file)) { score += 8; why.push("anchor file"); }
+		const lower = `${file}\n${text}`.toLowerCase();
+		for (const term of terms) {
+			if (lower.includes(term)) {
+				score += anchors.symbols.map((symbol) => symbol.toLowerCase()).includes(term) ? 3 : 1;
+				why.push(`hit:${term}`);
+			}
+		}
+		if (isTestPath(file)) { score += 3; why.push("test file"); }
+		if (isDocConfigPath(file)) { score += 2; why.push("doc/config path"); }
+		candidates.push({ kind: "match", title: `${file}${lineNumber ? `:${lineNumber}` : ""}`, score, why: unique(why).slice(0, 5), preview: text });
+	}
+	return candidates;
+}
+
+async function pathCandidates(cwd: string, exec: ExecLike, anchors: Anchors, signal?: AbortSignal): Promise<Candidate[]> {
+	const terms = unique([...anchors.terms, ...anchors.symbols.map((symbol) => symbol.toLowerCase())]);
+	if (terms.length === 0) return [];
+	try {
+		const result = await exec("rg", ["--files", "--glob", "!node_modules/**", "--glob", "!.git/**", "--glob", "!.pi/scrutiny/**", "--glob", "!package-lock.json", "--glob", "!pnpm-lock.yaml", "--glob", "!yarn.lock", "--glob", "!bun.lockb"], { timeout: 5_000, signal });
+		return (result.stdout ?? "")
+			.split(/\r?\n/)
+			.map(normalizeFile)
+			.filter((file): file is string => Boolean(file))
+			.filter((file) => isDocConfigPath(file) || isTestPath(file))
+			.map((file): Candidate | undefined => {
+				const lower = file.toLowerCase();
+				const hits = terms.filter((term) => lower.includes(term));
+				return hits.length ? { kind: "file", title: file, score: 4 + hits.length + (isTestPath(file) ? 2 : 0), why: [`path:${hits.slice(0, 3).join(",")}`, isTestPath(file) ? "test file" : "doc/config path"].filter(Boolean) } : undefined;
+			})
+			.filter((item): item is Candidate => item !== undefined)
+			.slice(0, 30);
+	} catch {
+		return [];
+	}
+}
+
+async function priorRunCandidates(cwd: string, anchors: Anchors): Promise<Candidate[]> {
+	const indexPath = path.join(scrutinyDataDir(cwd), "index.jsonl");
+	let lines: string[];
+	try {
+		lines = (await fs.readFile(indexPath, "utf8")).split(/\r?\n/).filter(Boolean).slice(-100);
+	} catch {
+		return [];
+	}
+	const candidates: Candidate[] = [];
+	for (const line of lines) {
+		let summary: ScrutinySummary;
+		try { summary = JSON.parse(line) as ScrutinySummary; } catch { continue; }
+		const why: string[] = [];
+		let score = 0;
+		const fileHits = summary.files.filter((file) => anchors.files.includes(file));
+		if (fileHits.length) { score += 8 * fileHits.length; why.push(`file:${fileHits.slice(0, 2).join(",")}`); }
+		const symbolHits = summary.symbols.filter((symbol) => anchors.symbols.includes(symbol));
+		if (symbolHits.length) { score += 4 * symbolHits.length; why.push(`symbol:${symbolHits.slice(0, 2).join(",")}`); }
+		const keywordHits = summary.keywords.filter((keyword) => anchors.terms.includes(keyword));
+		if (keywordHits.length) { score += keywordHits.length; why.push(`keyword:${keywordHits.slice(0, 3).join(",")}`); }
+		const freshness = await summaryFreshness(cwd, summary);
+		if (freshness === "stale") score -= 4;
+		if (score <= 0) continue;
+		candidates.push({
+			kind: "prior",
+			title: `${summary.runId} · ${summary.surface} · ${summary.status}${freshness ? ` · ${freshness}` : ""}`,
+			score,
+			why,
+			preview: truncate([summary.prompt, ...summary.signals.slice(0, 2), ...summary.risks.slice(0, 2)].filter(Boolean).join("; "), 260),
+		});
+	}
+	return candidates.sort((a, b) => b.score - a.score).slice(0, MAX_PRIOR_RUNS);
+}
+
+async function summaryFreshness(cwd: string, summary: ScrutinySummary): Promise<"fresh" | "stale" | undefined> {
+	const hashes = Object.entries(summary.fileHashes ?? {});
+	if (!hashes.length) return undefined;
+	for (const [file, expected] of hashes) {
+		try {
+			const abs = path.resolve(cwd, file);
+			if (!isInside(cwd, abs)) return "stale";
+			const actual = createHash("sha1").update(await fs.readFile(abs)).digest("hex");
+			if (actual !== expected) return "stale";
+		} catch {
+			return "stale";
+		}
+	}
+	return "fresh";
+}
+
+function dedupeCandidates(candidates: Candidate[]): Candidate[] {
+	const byTitle = new Map<string, Candidate>();
+	for (const candidate of candidates) {
+		const existing = byTitle.get(candidate.title);
+		if (!existing) byTitle.set(candidate.title, candidate);
+		else byTitle.set(candidate.title, {
+			...existing,
+			score: Math.max(existing.score, candidate.score),
+			why: unique([...existing.why, ...candidate.why]).slice(0, 6),
+			preview: existing.preview ?? candidate.preview,
+		});
+	}
+	return [...byTitle.values()];
+}
+
+function renderScout(anchors: Anchors, candidates: Candidate[]): string {
+	const lines: string[] = [];
+	lines.push("## Context scout");
+	lines.push("cheap local anchor scan. source for orientation only; not authority.");
+	lines.push(`anchors: ${anchors.reasons.join(", ") || "none"}`);
+	pushInline(lines, "files", anchors.files, 8);
+	pushInline(lines, "symbols", anchors.symbols, 8);
+	pushInline(lines, "terms", anchors.terms, 8);
+	lines.push("");
+	if (candidates.length === 0) {
+		lines.push("no local candidates found from these anchors. if task depends on broader architecture, inspect scope manually before trusting panel output.");
+		return lines.join("\n");
+	}
+	lines.push("### Candidate context");
+	for (const candidate of candidates) {
+		lines.push(`- ${candidate.title} [${candidate.kind}; score ${candidate.score}; why: ${candidate.why.join(", ") || "anchor"}]`);
+		if (candidate.preview) lines.push(`  ${truncate(candidate.preview.replace(/\s+/g, " "), 220)}`);
+	}
+	return truncate(lines.join("\n"), MAX_SCOUT_CHARS);
+}
+
+function pushInline(lines: string[], label: string, items: string[], limit: number): void {
+	if (items.length === 0) return;
+	lines.push(`${label}: ${items.slice(0, limit).join(", ")}${items.length > limit ? `, +${items.length - limit}` : ""}`);
+}
+
+function normalizeFile(raw: string | undefined): string | undefined {
+	let file = raw?.trim().replace(/^['"`]|['"`,.;)\]]$/g, "");
+	if (!file) return undefined;
+	file = file.replace(/^@/, "").replace(/^(?:a|b)\//, "").replace(/^\.\//, "");
+	if (!file || file.includes("://") || path.isAbsolute(file)) return undefined;
+	if (file.split("/").some((part) => part === "..")) return undefined;
+	if (/^(?:node_modules|\.git|\.pi\/scrutiny)\//.test(file)) return undefined;
+	if (/^(?:package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb)$/.test(file)) return undefined;
+	return file;
+}
+
+function looksLikePath(value: string): boolean {
+	return value.includes("/") || /\.[A-Za-z0-9]+(?::\d+)?$/.test(value);
+}
+
+function isTestPath(file: string): boolean {
+	return /(^|\/)(test|tests|spec|__tests__)(\/|$)|\.(test|spec)\.[A-Za-z0-9]+$/i.test(file);
+}
+
+function isDocConfigPath(file: string): boolean {
+	return /(^|\/)(README|CONTEXT|docs|adr|architecture|service|schema|schemas|proto|openapi|routes|migrations|config|configs)(\/|\.|$)|\.(ya?ml|toml|json|proto|graphql|sql|properties|env)$/i.test(file);
+}
+
+function escapeRegex(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function unique(items: string[]): string[] {
+	return [...new Set(items.map((item) => item.trim()).filter(Boolean))];
+}
+
+function isInside(cwd: string, file: string): boolean {
+	const relative = path.relative(cwd, file);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+const STOP = new Set([
+	"about", "after", "again", "answer", "because", "before", "could", "first", "model", "panel", "there", "these", "thing", "which", "would", "should", "their", "while", "where", "under", "using", "without", "recommendation", "evidence", "position", "panelist", "scrutiny", "surface", "packet", "context", "result", "status", "failed", "error", "output", "outputs", "returned", "usable", "technical", "vocabulary", "shared", "confidence", "deterministic", "analysis", "compare", "review", "change", "changes", "patch", "please", "maybe", "think", "tell", "what", "when", "does", "this", "that", "with", "from", "into", "doesn", "isn", "aren", "have", "been", "will", "just", "really", "basically", "actually", "simply",
+]);

package/extensions/scrutiny/summary.ts

@@ -0,0 +1,270 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import type { PanelResponse, ScrutinyRunResult, ScrutinySummary } from "./types.js";
+import { scrutinyDataDir, truncate } from "./util.js";
+
+const MAX_ITEMS = 40;
+const MAX_SOURCE_REFS = 60;
+const MAX_HASH_BYTES = 8 * 1024 * 1024;
+
+export async function writeRunResult(input: { cwd: string; runDir: string; result: ScrutinyRunResult; prompt?: string }): Promise<void> {
+	await fs.writeFile(path.join(input.runDir, "result.json"), JSON.stringify(input.result, null, 2), { encoding: "utf8", mode: 0o600 });
+	await writeSurfaceArtifact(input).catch(() => undefined);
+	try {
+		await writeRunSummary(input);
+	} catch {
+		// Summary/index is best-effort. Never hide primary result.json write.
+	}
+}
+
+async function writeSurfaceArtifact(input: { runDir: string; result: ScrutinyRunResult }): Promise<void> {
+	const file = surfaceArtifactFile(input.result.surface);
+	if (!file) return;
+	const artifact = {
+		runId: input.result.runId,
+		surface: input.result.surface,
+		status: input.result.status,
+		failure_reason: input.result.failure_reason,
+		error: input.result.error,
+		packetPath: input.result.packetPath,
+		analysis: input.result.analysis,
+		panel: input.result.responses.map((response) => ({
+			model: response.model,
+			role: response.role,
+			status: response.status,
+			content: response.content,
+			error: response.error,
+			durationMs: response.durationMs,
+		})),
+		failed_models: input.result.failed_models,
+		verify: input.result.verify ? {
+			passed: input.result.verify.passed,
+			failed: input.result.verify.failed,
+			skipped: input.result.verify.skipped,
+			durationMs: input.result.verify.durationMs,
+		} : undefined,
+		startedAt: input.result.startedAt,
+		endedAt: input.result.endedAt,
+		durationMs: input.result.durationMs,
+	};
+	await fs.writeFile(path.join(input.runDir, file), JSON.stringify(artifact, null, 2), { encoding: "utf8", mode: 0o600 });
+}
+
+function surfaceArtifactFile(surface: ScrutinyRunResult["surface"]): string | undefined {
+	if (surface === "verify") return undefined; // verify already writes verify.json.
+	return `${surface}.json`;
+}
+
+export async function writeRunSummary(input: { cwd: string; runDir: string; result: ScrutinyRunResult; prompt?: string }): Promise<ScrutinySummary> {
+	const summary = await buildRunSummary(input);
+	await fs.writeFile(path.join(input.runDir, "summary.json"), JSON.stringify(summary, null, 2), { encoding: "utf8", mode: 0o600 });
+	await appendSummaryIndex(input.cwd, summary);
+	return summary;
+}
+
+async function buildRunSummary(input: { cwd: string; runDir: string; result: ScrutinyRunResult; prompt?: string }): Promise<ScrutinySummary> {
+	const { cwd, runDir, result } = input;
+	const prompt = truncate((input.prompt?.trim() || extractTask(result.packet) || result.error || "").trim(), 1_000);
+	const responseText = result.responses.map((response) => response.content).join("\n");
+	const analysisText = analysisToText(result);
+	const searchableText = [prompt, result.packet, responseText, analysisText].filter(Boolean).join("\n");
+	const sourceRefs = limit(extractSourceRefs(searchableText), MAX_SOURCE_REFS);
+	const files = limit(unique([...sourceRefs.map(fileFromRef), ...extractDiffFiles(result.packet)]).filter(Boolean), MAX_ITEMS);
+	const symbols = limit(extractSymbols(searchableText), MAX_ITEMS);
+	const keywords = limit(extractKeywords([prompt, analysisText, files.join(" ")].join("\n")), MAX_ITEMS);
+	const missingContext = limit(extractMissingContext(result.responses, result.analysis?.blind_spots), 8);
+	const fileHashes = await hashReferencedFiles(cwd, files);
+	const verifyPath = result.verify && await exists(path.join(runDir, "verify.json")) ? rel(cwd, path.join(runDir, "verify.json")) : undefined;
+	const responsesPath = await exists(path.join(runDir, "responses.json")) ? rel(cwd, path.join(runDir, "responses.json")) : undefined;
+	const surfaceArtifactName = surfaceArtifactFile(result.surface);
+	const surfaceArtifactPath = surfaceArtifactName && await exists(path.join(runDir, surfaceArtifactName)) ? rel(cwd, path.join(runDir, surfaceArtifactName)) : undefined;
+
+	return {
+		runId: result.runId,
+		surface: result.surface,
+		startedAt: result.startedAt,
+		endedAt: result.endedAt,
+		prompt,
+		status: result.status,
+		failure_reason: result.failure_reason,
+		error: result.error ? truncate(result.error, 500) : undefined,
+		files,
+		symbols,
+		keywords,
+		signals: limit(extractSignals(result), 8),
+		risks: limit(result.analysis?.risks ?? [], 8).map((item) => truncate(item, 300)),
+		contradictions: limit(extractContradictions(result), 6),
+		missingContext,
+		sourceRefs,
+		fileHashes,
+		resultPath: rel(cwd, path.join(runDir, "result.json")),
+		surfaceArtifactPath,
+		packetPath: result.packetPath ? rel(cwd, result.packetPath) : undefined,
+		responsesPath,
+		verifyPath,
+	};
+}
+
+async function appendSummaryIndex(cwd: string, summary: ScrutinySummary): Promise<void> {
+	const indexPath = path.join(scrutinyDataDir(cwd), "index.jsonl");
+	await fs.mkdir(path.dirname(indexPath), { recursive: true, mode: 0o700 });
+	await fs.appendFile(indexPath, `${JSON.stringify(summary)}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+function extractTask(packet: string): string {
+	const match = packet.match(/^## Task\s*\n([\s\S]*?)(?=\n## |$)/m);
+	return match?.[1]?.trim() ?? "";
+}
+
+function analysisToText(result: ScrutinyRunResult): string {
+	const analysis = result.analysis;
+	if (!analysis) return "";
+	return [
+		...(analysis.consensus ?? []),
+		...(analysis.risks ?? []),
+		...(analysis.coverage ?? []),
+		...(analysis.blind_spots ?? []),
+		...(analysis.unique_insights ?? []).map((item) => item.insight),
+		...(result.panel_mode === "roles" ? [] : (analysis.contradictions ?? []).flatMap((item) => [item.topic, ...item.stances.map((stance) => stance.stance)])),
+	].join("\n");
+}
+
+function extractSignals(result: ScrutinyRunResult): string[] {
+	const analysis = result.analysis;
+	if (!analysis) return [];
+	const consensus = (analysis.consensus ?? []).filter((item) => !/panelists returned usable output|shared technical vocabulary/i.test(item));
+	const uniqueInsights = (analysis.unique_insights ?? []).map((item) => item.insight);
+	return unique([...consensus, ...(analysis.coverage ?? []), ...uniqueInsights]).map((item) => truncate(item, 300));
+}
+
+function extractContradictions(result: ScrutinyRunResult): string[] {
+	if (result.panel_mode === "roles") return [];
+	return (result.analysis?.contradictions ?? []).map((item) => {
+		const stances = item.stances.map((stance) => `${stance.model}: ${stance.stance}`).join(" | ");
+		return truncate(`${item.topic}${stances ? ` — ${stances}` : ""}`, 400);
+	});
+}
+
+function extractMissingContext(responses: PanelResponse[], blindSpots: string[] | undefined): string[] {
+	const lines = responses.flatMap((response) => response.content.split(/\r?\n/));
+	const missing = lines
+		.map(cleanBullet)
+		.filter((line) => line.length >= 20 && line.length <= 500)
+		.filter((line) => /\b(missing|not shown|not in (the )?packet|insufficient|unknown|cannot determine|can't determine|need(?:s)? to inspect|must inspect|would need|need more evidence|not enough evidence)\b/i.test(line));
+	const nonGenericBlindSpots = (blindSpots ?? []).filter((line) => !/^Deterministic analysis does not infer/i.test(line));
+	return unique([...missing, ...nonGenericBlindSpots]).map((item) => truncate(item, 300));
+}
+
+function extractSourceRefs(text: string): string[] {
+	const refs: string[] = [];
+	for (const line of text.split(/\r?\n/)) {
+		const diff = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+		if (diff) {
+			pushRef(refs, diff[1]);
+			pushRef(refs, diff[2]);
+			continue;
+		}
+		const marker = line.match(/^(?:---|\+\+\+)\s+(?:a|b)\/(.+)$/);
+		if (marker) pushRef(refs, marker[1]);
+		const status = line.match(/^\s*(?:[MADRCU?]{1,2}|[ MADRCU?][ MADRCU?])\s+(.+?\.[A-Za-z0-9]+)$/);
+		if (status) pushRef(refs, status[1]);
+	}
+	const pathPattern = /(^|[\s([{"'`])((?:\.{1,2}\/)?(?:[A-Za-z0-9_.@+-]+\/)+[A-Za-z0-9_.@+-]+\.[A-Za-z0-9]+)(?::(\d+))?/g;
+	let match: RegExpExecArray | null;
+	while ((match = pathPattern.exec(text))) pushRef(refs, match[2], match[3]);
+	const rootFilePattern = /(^|[\s([{"'`])([A-Za-z0-9_.@+-]+\.(?:md|mdx|txt|json|ya?ml|toml|ts|tsx|js|jsx|py|java|kt|go|rs|sql|proto|graphql|gradle|xml|properties|env|sh))(?::(\d+))?/gi;
+	while ((match = rootFilePattern.exec(text))) pushRef(refs, match[2], match[3]);
+	return unique(refs);
+}
+
+function extractDiffFiles(packet: string): string[] {
+	const files: string[] = [];
+	for (const ref of extractSourceRefs(packet)) files.push(fileFromRef(ref));
+	return unique(files.filter(Boolean));
+}
+
+function pushRef(refs: string[], rawFile: string, line?: string): void {
+	const file = normalizeFilePath(rawFile);
+	if (!file) return;
+	refs.push(line ? `${file}:${line}` : file);
+}
+
+function normalizeFilePath(raw: string): string | undefined {
+	let file = raw.trim().replace(/^['"`]|['"`,.;)\]]$/g, "");
+	file = file.replace(/^(?:a|b)\//, "").replace(/^\.\//, "");
+	if (!file || file.includes("://") || path.isAbsolute(file)) return undefined;
+	if (file.split("/").some((part) => part === "..")) return undefined;
+	if (/^(?:node_modules|\.git|\.pi\/scrutiny)\//.test(file)) return undefined;
+	if (/^(?:packet\.md|responses\.json|result\.json|summary\.json|verify\.json)$/.test(file)) return undefined;
+	return file;
+}
+
+function fileFromRef(ref: string): string {
+	const match = ref.match(/^(.+?)(?::\d+)?$/);
+	return normalizeFilePath(match?.[1] ?? "") ?? "";
+}
+
+function extractSymbols(text: string): string[] {
+	const symbols: string[] = [];
+	for (const match of text.matchAll(/`([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)?)`/g)) symbols.push(match[1]);
+	for (const match of text.matchAll(/\b([A-Z][A-Za-z0-9]+(?:[A-Z][A-Za-z0-9]+)+|[a-z][A-Za-z0-9]*[A-Z][A-Za-z0-9]*)\b/g)) symbols.push(match[1]);
+	return unique(symbols.filter((symbol) => symbol.length >= 4 && !STOP.has(symbol.toLowerCase())));
+}
+
+function extractKeywords(text: string): string[] {
+	const tokens = text.toLowerCase().match(/[a-z][a-z0-9_-]{3,}/g) ?? [];
+	return unique(tokens.filter((token) => !STOP.has(token) && token.length <= 40));
+}
+
+async function hashReferencedFiles(cwd: string, files: string[]): Promise<Record<string, string>> {
+	const hashes: Record<string, string> = {};
+	for (const file of files) {
+		const abs = path.resolve(cwd, file);
+		if (!isInside(cwd, abs)) continue;
+		try {
+			const stat = await fs.stat(abs);
+			if (!stat.isFile() || stat.size > MAX_HASH_BYTES) continue;
+			const data = await fs.readFile(abs);
+			hashes[file] = createHash("sha1").update(data).digest("hex");
+		} catch {
+			// deleted/missing/generated file; leave unhashed.
+		}
+	}
+	return hashes;
+}
+
+async function exists(file: string): Promise<boolean> {
+	try {
+		await fs.access(file);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function rel(cwd: string, file: string): string {
+	const relative = path.relative(cwd, file);
+	return relative && !relative.startsWith("..") && !path.isAbsolute(relative) ? relative : file;
+}
+
+function isInside(cwd: string, file: string): boolean {
+	const relative = path.relative(cwd, file);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function cleanBullet(line: string): string {
+	return line.trim().replace(/^[-*•]\s+/, "").replace(/^\d+[.)]\s+/, "").trim();
+}
+
+function unique(items: string[]): string[] {
+	return [...new Set(items.map((item) => item.trim()).filter(Boolean))];
+}
+
+function limit<T>(items: T[], count: number): T[] {
+	return items.slice(0, count);
+}
+
+const STOP = new Set([
+	"about", "after", "again", "answer", "because", "before", "could", "first", "model", "panel", "there", "these", "thing", "which", "would", "should", "their", "while", "where", "under", "using", "without", "recommendation", "evidence", "position", "panelist", "scrutiny", "surface", "packet", "context", "result", "status", "failed", "error", "output", "outputs", "returned", "usable", "technical", "vocabulary", "shared", "confidence", "deterministic", "analysis",
+]);