pi-jev-wiki 0.2.0

package/src/pipeline/write.ts

@@ -0,0 +1,263 @@
+/**
+ * Writer pipeline: turn accepted claims into wiki pages or drafts.
+ *
+ * The model writes prose only; code assembles frontmatter from the adjudication
+ * results, so status/support/evidence cannot be hallucinated. Mode is adaptive:
+ * high-criticality claims downgrade auto -> draft -> guided.
+ */
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ResolvedConfig, WriterMode } from "../config.ts";
+import { checkLiterals } from "../grounding.ts";
+import { redact } from "../redact.ts";
+import { appendLedger } from "../ledger.ts";
+import { readPage, todayISO, writePage, writeTextAtomic, type WikiLayout } from "../wiki/layout.ts";
+import { appendLog, entryFromPage, updateIndex, upsertEntries, type TocEntry } from "../wiki/toc.ts";
+
+export interface WriterClaim {
+	text: string;
+	kind?: string;
+	pageType?: string;
+	topic?: string;
+	target?: string;
+	trustTier?: string;
+	files: string[];
+	evidence: string[];
+	grounded: number;
+	criticality: number;
+}
+
+export interface WriterPlan {
+	title: string;
+	topic: string;
+	sourcePath?: string;
+	claims: WriterClaim[];
+}
+
+export interface WriterResult {
+	mode: WriterMode;
+	written: string[];
+	drafted: string[];
+	groups: number;
+	flagged: Array<{ page: string; missing: string[] }>;
+	usage: { input_tokens: number; output_tokens: number };
+}
+
+export function resolveWriterMode(requested: WriterMode, claims: WriterClaim[], config: ResolvedConfig): WriterMode {
+	const worst = claims.reduce((max, claim) => Math.max(max, claim.criticality), 0);
+	let mode = requested;
+	if (worst >= config.review.escalateCriticality) {
+		if (mode === "auto") mode = "draft";
+		else if (mode === "draft") mode = "guided";
+	}
+	if (worst >= 0.95) mode = "guided";
+	return mode;
+}
+
+interface WriterGroup {
+	target?: string;
+	pageType: string;
+	topic: string;
+	claims: WriterClaim[];
+}
+
+function groupClaims(plan: WriterPlan): WriterGroup[] {
+	const groups: WriterGroup[] = [];
+	for (const claim of plan.claims) {
+		const key = claim.target ?? `${claim.pageType ?? "concept"}:${claim.topic ?? plan.topic}`;
+		let group = groups.find((candidate) => (candidate.target ?? `${candidate.pageType}:${candidate.topic}`) === key);
+		if (!group) {
+			group = {
+				target: claim.target,
+				pageType: claim.pageType ?? "concept",
+				topic: claim.topic ?? plan.topic,
+				claims: [],
+			};
+			groups.push(group);
+		}
+		group.claims.push(claim);
+	}
+	return groups;
+}
+
+function stripFences(text: string): string {
+	const trimmed = text.trim();
+	return trimmed.startsWith("```") ? trimmed.replace(/^```[a-z]*\s*/i, "").replace(/```\s*$/, "") : trimmed;
+}
+
+function parseWriterJson(text: string): { title?: string; summary?: string; tags?: string[]; body?: string } | undefined {
+	const cleaned = stripFences(text);
+	const start = cleaned.indexOf("{");
+	const end = cleaned.lastIndexOf("}");
+	if (start === -1 || end <= start) return undefined;
+	try {
+		return JSON.parse(cleaned.slice(start, end + 1)) as { title?: string; summary?: string; tags?: string[]; body?: string };
+	} catch {
+		return undefined;
+	}
+}
+
+const WRITER_RULES = `You maintain a project wiki that gives coding agents the mental model of a system.
+Write the page body in markdown: concrete, decision-oriented, no code blocks unless essential, no frontmatter.
+Use short sections (Responsibility, Invariants, Change impact, See also) as appropriate.
+Every factual statement must come from the supplied claims and evidence. Do not invent file paths, numbers, or behavior.
+Prefer updating an existing page over restating it: merge the new claims into the existing text, keeping it coherent.
+Return ONLY JSON: { "title": "...", "summary": "one line", "tags": ["..."], "body": "markdown body" }`;
+
+function buildUserPrompt(group: WriterGroup, plan: WriterPlan, existing: { body: string; data: Record<string, unknown> } | undefined, sourceExcerpt: string): string {
+	const claims = group.claims.map((claim) => `- (${claim.trustTier ?? "source_document"}) ${claim.text}`).join("\n");
+	const files = [...new Set(group.claims.flatMap((claim) => claim.files))];
+	const evidence = [...new Set(group.claims.flatMap((claim) => claim.evidence))];
+	return [
+		`Source title: ${plan.title}`,
+		`Page type: ${group.pageType}`,
+		`Topic: ${group.topic}`,
+		files.length ? `Related code files: ${files.join(", ")}` : "",
+		evidence.length ? `Evidence: ${evidence.join(", ")}` : "",
+		existing ? `\nExisting page to update (keep what is still true, integrate the claims):\n---\n${existing.body.slice(0, 6000)}\n---` : "",
+		`\nClaims to file:\n${claims}`,
+		sourceExcerpt ? `\nSource material (may be truncated):\n---\n${sourceExcerpt}\n---` : "",
+	].filter(Boolean).join("\n");
+}
+
+async function callWriter(
+	ctx: ExtensionContext,
+	group: WriterGroup,
+	plan: WriterPlan,
+	existing: { body: string; data: Record<string, unknown> } | undefined,
+	sourceExcerpt: string,
+): Promise<{ result?: { title?: string; summary?: string; tags?: string[]; body?: string }; usage: { input_tokens: number; output_tokens: number } }> {
+	const model = ctx.model;
+	if (!model) return { usage: { input_tokens: 0, output_tokens: 0 } };
+	const response = await ctx.modelRegistry.complete(
+		model,
+		{
+			systemPrompt: WRITER_RULES,
+			messages: [{ role: "user", content: [{ type: "text", text: buildUserPrompt(group, plan, existing, sourceExcerpt) }], timestamp: Date.now() }],
+		},
+		{ maxTokens: 6000, signal: ctx.signal, cacheRetention: "none" },
+	);
+	const text = response.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text")
+		.map((part) => part.text)
+		.join("\n");
+	return {
+		result: parseWriterJson(text),
+		usage: response.usage
+			? { input_tokens: response.usage.input ?? 0, output_tokens: response.usage.output ?? 0 }
+			: { input_tokens: 0, output_tokens: 0 },
+	};
+}
+
+export async function writeAcceptedPages(
+	ctx: ExtensionContext,
+	layout: WikiLayout,
+	config: ResolvedConfig,
+	plan: WriterPlan,
+	requestedMode: WriterMode,
+): Promise<WriterResult> {
+	const mode = resolveWriterMode(requestedMode, plan.claims, config);
+	const usage = { input_tokens: 0, output_tokens: 0 };
+	const flagged: Array<{ page: string; missing: string[] }> = [];
+	if (mode === "guided" || plan.claims.length === 0) {
+		return { mode, written: [], drafted: [], groups: 0, flagged, usage };
+	}
+
+	const groups = groupClaims(plan);
+	const sourceExcerpt =
+		plan.sourcePath && existsSync(join(layout.root, plan.sourcePath))
+			? redact((await readFile(join(layout.root, plan.sourcePath), "utf8")).slice(0, 12_000)).text
+			: "";
+
+	const written: string[] = [];
+	const drafted: string[] = [];
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const draftDir = join(layout.stateDir, "drafts", stamp);
+
+	for (const group of groups) {
+		const existing = group.target && existsSync(join(layout.wikiDir, group.target)) ? await readPage(join(layout.wikiDir, group.target)) : undefined;
+
+		const { result, usage: callUsage } = await callWriter(ctx, group, plan, existing, sourceExcerpt);
+		usage.input_tokens += callUsage.input_tokens;
+		usage.output_tokens += callUsage.output_tokens;
+		if (!result?.body) continue;
+
+		const typePrefix = group.pageType.includes("/") ? group.pageType.split("/")[1] : group.pageType;
+		const finalRel = group.target ?? `${group.topic}/${typePrefix}-${slugPart(result.title ?? group.claims[0].text)}.md`;
+		const absolute = join(layout.wikiDir, finalRel);
+
+		const claimRecords = group.claims.map((claim, index) => ({
+			id: `c${index + 1}`,
+			text: claim.text,
+			status: claim.trustTier === "user_stated" ? "user-stated" : "verified",
+			support: Number(claim.grounded.toFixed(2)),
+			evidence: claim.evidence.length > 0 ? claim.evidence : plan.sourcePath ? [plan.sourcePath] : [],
+		}));
+		const evidenceForCheck = [
+			group.claims.map((claim) => claim.text).join("\n"),
+			group.claims.flatMap((claim) => claim.evidence).join("\n"),
+			sourceExcerpt,
+		].join("\n");
+		const grounding = checkLiterals(result.body, evidenceForCheck);
+		if (grounding.missing.length > 0) {
+			flagged.push({ page: finalRel, missing: grounding.missing.slice(0, 5) });
+		}
+
+		const data: Record<string, unknown> = {
+			title: result.title ?? existing?.data.title ?? plan.title,
+			type: group.pageType,
+			topic: group.topic,
+			summary: result.summary ?? existing?.data.summary ?? "",
+			tags: Array.isArray(result.tags) ? result.tags.map(String).slice(0, 8) : [],
+			updated: todayISO(),
+			sources: [...new Set([...(Array.isArray(existing?.data.sources) ? existing!.data.sources.map(String) : []), ...(plan.sourcePath ? [plan.sourcePath] : [])])],
+			files: [...new Set([...(Array.isArray(existing?.data.files) ? existing!.data.files.map(String) : []), ...group.claims.flatMap((claim) => claim.files)])],
+			claims: [...(Array.isArray(existing?.data.claims) ? (existing!.data.claims as unknown[]) : []), ...claimRecords],
+			...(grounding.missing.length > 0 ? { needs_review: true } : {}),
+		};
+
+		if (mode === "draft") {
+			const draftPath = join(draftDir, finalRel);
+			await writePage(draftPath, data, result.body);
+			drafted.push(finalRel);
+		} else {
+			await writePage(absolute, data, result.body);
+			written.push(finalRel);
+		}
+		await appendLedger(layout, {
+			actor: "agent",
+			op: "wiki.write",
+			subject: finalRel,
+			action: mode,
+			reason: `${group.claims.length} accepted claim(s)`,
+			verdict: { mode, claims: group.claims.length, grounded: group.claims.map((claim) => claim.grounded), ungroundedLiterals: grounding.missing },
+		});
+	}
+
+	if (written.length > 0) {
+		const updates: TocEntry[] = [];
+		for (const rel of written) {
+			const page = await readPage(join(layout.wikiDir, rel));
+			updates.push(entryFromPage(rel, page.data));
+		}
+		await updateIndex(layout, (entries) => upsertEntries(entries, updates));
+		await appendLog(layout, "write", `${written.length} page(s) (${mode})`, written.map((rel) => `Written: ${rel}`));
+	}
+	if (drafted.length > 0) {
+		await writeTextAtomic(join(draftDir, "manifest.json"), `${JSON.stringify({ created: stamp, plan: plan.title, pages: drafted }, null, "\t")}\n`);
+		await appendLog(layout, "draft", `${drafted.length} page(s)`, drafted.map((rel) => `Draft: ${rel}`));
+	}
+	return { mode, written, drafted, groups: groups.length, flagged, usage };
+}
+
+function slugPart(text: string): string {
+	return text
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.split("-")
+		.slice(0, 5)
+		.join("-");
+}

package/src/provenance.ts

@@ -0,0 +1,137 @@
+/**
+ * Claim provenance: corroboration counting and supersession.
+ * These are the compounding mechanics — repeated insight strengthens a claim,
+ * newer knowledge retires it with a link instead of deleting it.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { readPage, todayISO, writePage, type WikiLayout } from "./wiki/layout.ts";
+
+export interface ReinforcementResult {
+	page: string;
+	claimId?: string;
+	corroborations: number;
+	support: number;
+}
+
+export interface SupersessionResult {
+	page: string;
+	claimId?: string;
+	supersededText: string;
+}
+
+function tokens(text: string): Set<string> {
+	return new Set(
+		text
+			.toLowerCase()
+			.split(/[^a-z0-9_]+/)
+			.filter((token) => token.length > 3),
+	);
+}
+
+function similarity(a: Set<string>, b: Set<string>): number {
+	if (a.size === 0 || b.size === 0) return 0;
+	let shared = 0;
+	for (const token of a) if (b.has(token)) shared++;
+	return shared / Math.min(a.size, b.size);
+}
+
+function findClaim(claims: Record<string, unknown>[], text: string, minimum = 0.5): number {
+	const needle = tokens(text);
+	let bestIndex = -1;
+	let bestScore = 0;
+	claims.forEach((claim, index) => {
+		if (typeof claim.text !== "string") return;
+		const status = String(claim.status ?? "verified");
+		if (status === "rejected" || status === "superseded") return;
+		const score = similarity(tokens(claim.text), needle);
+		if (score > bestScore) {
+			bestScore = score;
+			bestIndex = index;
+		}
+	});
+	return bestScore >= minimum ? bestIndex : -1;
+}
+
+/** Increment corroboration for the best-matching claim on a page. */
+export async function applyReinforcement(
+	layout: WikiLayout,
+	pageRel: string,
+	text: string,
+	options?: { evidence?: string[] },
+): Promise<ReinforcementResult | undefined> {
+	const pagePath = join(layout.wikiDir, pageRel);
+	if (!existsSync(pagePath)) return undefined;
+	const page = await readPage(pagePath);
+	const claims = Array.isArray(page.data.claims) ? (page.data.claims as Record<string, unknown>[]) : [];
+	const index = findClaim(claims, text);
+	if (index === -1) return undefined;
+	const claim = claims[index];
+	const corroborations = Number(claim.corroborations ?? 1) + 1;
+	claim.corroborations = corroborations;
+	claim.last_confirmed = todayISO();
+	claim.support = Math.min(0.99, Math.max(Number(claim.support ?? 0.8), 0.85 + 0.02 * corroborations));
+	if (options?.evidence?.length) {
+		const evidence = Array.isArray(claim.evidence) ? claim.evidence.map(String) : [];
+		for (const item of options.evidence) if (!evidence.includes(item)) evidence.push(item);
+		claim.evidence = evidence;
+	}
+	claims[index] = claim;
+	page.data.claims = claims;
+	page.data.updated = todayISO();
+	await writePage(pagePath, page.data, page.body);
+	return {
+		page: pageRel,
+		claimId: typeof claim.id === "string" ? claim.id : undefined,
+		corroborations,
+		support: Number(claim.support),
+	};
+}
+
+/** Mark the best-matching claim on a page as superseded by newer knowledge. */
+export async function applySupersession(
+	layout: WikiLayout,
+	pageRel: string,
+	byText: string,
+): Promise<SupersessionResult | undefined> {
+	const pagePath = join(layout.wikiDir, pageRel);
+	if (!existsSync(pagePath)) return undefined;
+	const page = await readPage(pagePath);
+	const claims = Array.isArray(page.data.claims) ? (page.data.claims as Record<string, unknown>[]) : [];
+	// find the claim that the new text supersedes: highest overlap with the new text
+	const index = findClaim(claims, byText, 0.35);
+	if (index === -1) return undefined;
+	const claim = claims[index];
+	const supersededText = String(claim.text ?? "");
+	claim.status = "superseded";
+	claim.superseded_by = byText.slice(0, 100);
+	claim.superseded_at = todayISO();
+	claims[index] = claim;
+	page.data.claims = claims;
+	page.data.updated = todayISO();
+	await writePage(pagePath, page.data, page.body);
+	return {
+		page: pageRel,
+		claimId: typeof claim.id === "string" ? claim.id : undefined,
+		supersededText,
+	};
+}
+
+/** Best-matching candidate claim page for a relation verdict. */
+export function bestCandidatePage(
+	candidates: Array<{ text: string; page?: string }>,
+	text: string,
+	minimum = 0.4,
+): string | undefined {
+	let best: string | undefined;
+	let bestScore = 0;
+	for (const candidate of candidates) {
+		if (!candidate.page) continue;
+		const score = similarity(tokens(candidate.text), tokens(text));
+		if (score > bestScore) {
+			bestScore = score;
+			best = candidate.page;
+		}
+	}
+	return bestScore >= minimum ? best : undefined;
+}

package/src/redact.ts

@@ -0,0 +1,46 @@
+/**
+ * Redaction: best-effort secret/PII stripping before content is written to raw/
+ * or sent to a model. Redaction is defensive, not a guarantee — regex cannot
+ * catch everything, and it is logged so the ledger shows what was removed.
+ */
+
+export interface RedactionFinding {
+	type: string;
+	count: number;
+}
+
+export interface RedactionResult {
+	text: string;
+	findings: RedactionFinding[];
+}
+
+const PATTERNS: Array<{ type: string; regex: RegExp; replacement: string }> = [
+	{ type: "private_key", regex: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, replacement: "[REDACTED_PRIVATE_KEY]" },
+	{ type: "openai_key", regex: /\bsk-(?!or-v1-|ant-)[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED_OPENAI_KEY]" },
+	{ type: "openrouter_key", regex: /\bsk-or-v1-[A-Za-z0-9]{20,}\b/g, replacement: "[REDACTED_OPENROUTER_KEY]" },
+	{ type: "anthropic_key", regex: /\bsk-ant-[A-Za-z0-9_-]{20,}\b/g, replacement: "[REDACTED_ANTHROPIC_KEY]" },
+	{ type: "github_token", regex: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replacement: "[REDACTED_GITHUB_TOKEN]" },
+	{ type: "aws_key", regex: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, replacement: "[REDACTED_AWS_KEY]" },
+	{ type: "bearer_token", regex: /\bBearer\s+[A-Za-z0-9._~+/-]{24,}=*/g, replacement: "Bearer [REDACTED_TOKEN]" },
+	{ type: "jwt", regex: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replacement: "[REDACTED_JWT]" },
+	{ type: "slack_token", regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, replacement: "[REDACTED_SLACK_TOKEN]" },
+	{
+		type: "generic_secret_assignment",
+		regex: /\b(?:api[_-]?key|secret|password|passwd|token)\s*[:=]\s*["']?[A-Za-z0-9_./+-]{16,}["']?/gi,
+		replacement: "[REDACTED_SECRET]",
+	},
+	{ type: "email", regex: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g, replacement: "[REDACTED_EMAIL]" },
+];
+
+/** Redact secrets and PII, returning what was found. */
+export function redact(text: string): RedactionResult {
+	let output = text;
+	const findings: RedactionFinding[] = [];
+	for (const pattern of PATTERNS) {
+		const matches = output.match(pattern.regex);
+		if (!matches || matches.length === 0) continue;
+		findings.push({ type: pattern.type, count: matches.length });
+		output = output.replace(pattern.regex, pattern.replacement);
+	}
+	return { text: output, findings };
+}

package/src/review.ts

@@ -0,0 +1,146 @@
+/**
+ * Review queue: items that need a decision (low confidence, needs recheck, disputes).
+ * The agent works the queue via the wiki_review tool; the user is escalated only for
+ * critical items. Code applies resolutions to page frontmatter.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readPage, todayISO, writePage, writeTextAtomic, type WikiLayout } from "./wiki/layout.ts";
+import { withWikiLock } from "./wiki/lock.ts";
+
+export type ReviewKind = "claim_review" | "needs_recheck" | "dispute";
+export type ReviewStatus = "open" | "resolved" | "deferred";
+export type ReviewResolution = "accept" | "reject" | "supersede" | "defer";
+
+export interface ReviewItem {
+	id: string;
+	ts: string;
+	kind: ReviewKind;
+	status: ReviewStatus;
+	claimText: string;
+	page?: string;
+	claimId?: string;
+	criticality: number;
+	reason?: string;
+	verdicts?: unknown;
+	resolution?: ReviewResolution;
+	note?: string;
+	resolvedAt?: string;
+}
+
+function newId(): string {
+	return `${Date.now().toString(36)}-${randomBytes(3).toString("hex")}`;
+}
+
+export async function readReviews(layout: WikiLayout): Promise<ReviewItem[]> {
+	if (!existsSync(layout.reviewQueuePath)) return [];
+	const text = await readFile(layout.reviewQueuePath, "utf8");
+	return text
+		.split(/\r?\n/)
+		.filter(Boolean)
+		.map((line) => {
+			try {
+				return JSON.parse(line) as ReviewItem;
+			} catch {
+				return undefined;
+			}
+		})
+		.filter((item): item is ReviewItem => Boolean(item));
+}
+
+export async function writeReviews(layout: WikiLayout, items: ReviewItem[]): Promise<void> {
+	const body = items.map((item) => JSON.stringify(item)).join("\n");
+	await writeTextAtomic(layout.reviewQueuePath, body ? `${body}\n` : "");
+}
+
+export async function openReviewCount(layout: WikiLayout): Promise<number> {
+	return (await readReviews(layout)).filter((item) => item.status === "open").length;
+}
+
+export async function enqueueReview(
+	layout: WikiLayout,
+	item: Omit<ReviewItem, "id" | "ts" | "status">,
+): Promise<ReviewItem | undefined> {
+	return withWikiLock(layout, async () => {
+		const items = await readReviews(layout);
+		const duplicate = items.find(
+			(existing) =>
+				existing.status === "open" &&
+				existing.kind === item.kind &&
+				existing.page === item.page &&
+				existing.claimText === item.claimText,
+		);
+		if (duplicate) return undefined;
+		const record: ReviewItem = { id: newId(), ts: new Date().toISOString(), status: "open", ...item };
+		items.push(record);
+		await writeReviews(layout, items);
+		return record;
+	});
+}
+
+export async function listOpenReviews(layout: WikiLayout, limit = 20): Promise<ReviewItem[]> {
+	const items = await readReviews(layout);
+	const order: Record<ReviewKind, number> = { dispute: 0, needs_recheck: 1, claim_review: 2 };
+	return items
+		.filter((item) => item.status === "open")
+		.sort((a, b) => order[a.kind] - order[b.kind] || b.criticality - a.criticality)
+		.slice(0, limit);
+}
+
+export async function resolveReview(
+	layout: WikiLayout,
+	id: string,
+	resolution: ReviewResolution,
+	note?: string,
+): Promise<ReviewItem | undefined> {
+	return withWikiLock(layout, async () => {
+		const items = await readReviews(layout);
+		const item = items.find((candidate) => candidate.id === id);
+		if (!item) return undefined;
+		item.status = resolution === "defer" ? "deferred" : "resolved";
+		item.resolution = resolution;
+		item.note = note;
+		item.resolvedAt = new Date().toISOString();
+		await writeReviews(layout, items);
+		return item;
+	});
+}
+
+/**
+ * Apply a resolution to the claim in its page frontmatter.
+ * Returns a status message; a missing page/claim is not fatal (the agent may handle it).
+ */
+export async function applyReviewResolution(
+	layout: WikiLayout,
+	item: ReviewItem,
+	resolution: ReviewResolution,
+): Promise<string> {
+	if (!item.page) return "no page attached; resolution recorded only";
+	const pagePath = join(layout.wikiDir, item.page);
+	if (!existsSync(pagePath)) return `page not found: ${item.page}`;
+	const page = await readPage(pagePath);
+	const claims = Array.isArray(page.data.claims) ? (page.data.claims as Record<string, unknown>[]) : [];
+	const index = claims.findIndex(
+		(claim) => (item.claimId && claim.id === item.claimId) || claim.text === item.claimText,
+	);
+	if (index === -1) return `claim not found on ${item.page}`;
+	const claim = claims[index];
+	if (resolution === "accept") {
+		if (claim.status !== "user-stated") {
+			claim.status = "verified";
+			claim.support = Math.max(Number(claim.support ?? 0), 0.8);
+		}
+	} else if (resolution === "reject") {
+		claim.status = "rejected";
+	} else if (resolution === "supersede") {
+		claim.status = "superseded";
+	}
+	claim.reviewed = todayISO();
+	claims[index] = claim;
+	page.data.claims = claims;
+	page.data.updated = todayISO();
+	await writePage(pagePath, page.data, page.body);
+	return `${resolution} applied to ${item.page}${item.claimId ? `#${item.claimId}` : ""}`;
+}