@iowarp/clio-coder 0.4.3 → 0.4.5

package/src/domains/safety/extension.ts

@@ -118,6 +118,11 @@ export function createSafetyBundle(context: DomainContext): DomainBundle<SafetyC
 	let unsubscribeDispatchFailed: (() => void) | null = null;
 	const recordedRequestedPermissionIds = new Set<string>();
 
+	function activePolicyEngine(): SafetyPolicyEngine {
+		policyEngine ??= createSafetyPolicyEngine();
+		return policyEngine;
+	}
+
 	function writeAudit(rec: AuditRecord): void {
 		if (writer === null) return;
 		writer.write(rec);
@@ -274,7 +279,7 @@ export function createSafetyBundle(context: DomainContext): DomainBundle<SafetyC
 			return classifyCall(call);
 		},
 		evaluate(call, posture) {
-			const policy = (policyEngine ?? createSafetyPolicyEngine()).evaluate(call, posture);
+			const policy = activePolicyEngine().evaluate(call, posture);
 			const classification = policy.classification;
 
 			context.bus.emit(BusChannels.SafetyClassified, {
@@ -363,7 +368,11 @@ export function createSafetyBundle(context: DomainContext): DomainBundle<SafetyC
 		},
 		scopes: { readonly: READONLY_SCOPE, workspace: WORKSPACE_SCOPE, confirmed: CONFIRMED_SCOPE },
 		isSubset,
-		policy: { metadata: (posture) => (policyEngine ?? createSafetyPolicyEngine()).metadata(posture) },
+		policy: {
+			metadata: (posture) => activePolicyEngine().metadata(posture),
+			allowsObservationPath: (path) =>
+				activePolicyEngine().evaluate({ tool: "read", args: { path } }).reasonCode !== "path-policy:zeroAccessPaths",
+		},
 		audit: {
 			recordCount: () => recordCount,
 			recordToolCall: recordToolCallAudit,

package/src/domains/safety/finish-contract-registration.ts

@@ -4,16 +4,22 @@
  * The chat-loop fires `turn_end` with the final assistant text and this
  * registration emits an advisory `inject_reminder` (severity "warn") when the
  * turn mutated workspace state but recorded no validation evidence and no
- * explicit limitation. The trigger is the observed mutation, not the wording of
- * the assistant's text. The chat-loop's generic effect application renders the
+ * `limitation` receipt. The trigger is the observed mutation, not the wording
+ * of the assistant's text, and the text never enters the assessment. The chat-loop's generic effect application renders the
  * notice, persists the session entry, and flushes the reminder into the next
  * model request. Every decision is also written to the audit ledger.
  */
 
 import { VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
 import type { MiddlewareEffect, MiddlewareHookInput, MiddlewareHookRegistration } from "../middleware/index.js";
+import type { UserTaskAcceptance } from "../user-tasks/acceptance.js";
 import type { CompletionContractAuditInput } from "./audit.js";
-import { assessFinishContract, type FinishContractAssessment } from "./finish-contract.js";
+import {
+	assessFinishContract,
+	DEFAULT_RECENT_ENTRY_LIMIT,
+	type FinishContractAssessment,
+	recentEntries,
+} from "./finish-contract.js";
 import type { Rigor } from "./rigor.js";
 
 export const FINISH_CONTRACT_REGISTRATION_ID = "assessor.finish-contract";
@@ -21,15 +27,15 @@ export const FINISH_CONTRACT_REGISTRATION_ID = "assessor.finish-contract";
 /**
  * High-rigor re-prompt directive. Injected dynamically via effects (never added
  * to the static system prompt) so the prompt prefix stays byte-stable. It tells
- * the model to validate with a verification-family command or to state what
- * could not be verified before claiming done. The command hint mirrors the
+ * the model to validate with a verification-family command or to record a
+ * `limitation` receipt before claiming done. The command hint mirrors the
  * vocabulary `detectValidationCommand` and `isVerificationScriptName` accept.
  */
 export const HIGH_RIGOR_REVALIDATION_MESSAGE =
 	`[Clio Coder] high-rigor finish gate: this completion claim has no validation evidence. ` +
 	`Before claiming done, run a verification command (the ${VERIFICATION_SCRIPT_FAMILY_HINT} family, ` +
-	`e.g. "npm run test", "npm run lint", "npm run build") or explicitly state what could not be verified ` +
-	`and why. Do not end the turn until you have validated or recorded the limitation.`;
+	`e.g. "npm run test", "npm run lint", "npm run build") or call the limitation tool with the scope ` +
+	`and reason of what could not be verified. Do not end the turn until you have validated or recorded the limitation.`;
 
 export interface CreateFinishContractRegistrationOptions {
 	/**
@@ -45,6 +51,7 @@ export interface CreateFinishContractRegistrationOptions {
 	 * limitation instead of merely warning.
 	 */
 	resolveRigor?: () => Rigor;
+	readActiveAcceptance?: (window: ReadonlyArray<unknown>) => UserTaskAcceptance | undefined;
 	/**
 	 * Record the contract's decision to the audit ledger. Optional; when wired
 	 * (production passes the safety audit sink), every turn_end decision — each
@@ -59,7 +66,7 @@ export function createFinishContractRegistration(
 ): MiddlewareHookRegistration {
 	return {
 		id: FINISH_CONTRACT_REGISTRATION_ID,
-		description: "advise when a turn mutated files without validation evidence or an explicit limitation",
+		description: "advise when a turn mutated files without validation evidence or a limitation receipt",
 		hooks: ["turn_end"],
 		evaluate(input: MiddlewareHookInput, context): ReadonlyArray<MiddlewareEffect> {
 			if (input.hook !== "turn_end") return [];
@@ -70,8 +77,9 @@ export function createFinishContractRegistration(
 			// finalAssistantStopMessage.
 			const stopReason = input.metadata?.stopReason;
 			if (stopReason !== undefined && stopReason !== "stop") return [];
-			const assistantText = input.text?.trim() ?? "";
-			if (assistantText.length === 0) return [];
+			// An empty final text is not a completion claim. The assessor reads
+			// only ledger receipts, so the text is otherwise unused here.
+			if ((input.text?.trim() ?? "").length === 0) return [];
 			let entries: ReadonlyArray<unknown> | null;
 			try {
 				entries = options.readSessionEntries();
@@ -79,21 +87,28 @@ export function createFinishContractRegistration(
 				return [];
 			}
 			if (entries === null) return [];
+			const rigor = options.resolveRigor?.() ?? "normal";
+			const activeAcceptance =
+				rigor === "high"
+					? options.readActiveAcceptance?.(recentEntries(entries, input.turnId ?? null, DEFAULT_RECENT_ENTRY_LIMIT))
+					: undefined;
 			const assessment = assessFinishContract({
-				assistantText,
 				sessionEntries: entries,
+				workspaceRoot: process.cwd(),
+				rigor,
+				...(activeAcceptance ? { activeAcceptance } : {}),
 				assistantTurnId: input.turnId ?? null,
 			});
-			const rigor = options.resolveRigor?.() ?? "normal";
 			recordDecision(options, input.turnId ?? null, assessment, rigor);
 			if (assessment.kind !== "engage") return [];
 			if (rigor === "high") {
 				// Withhold the completion and force a re-prompt: a continuation
 				// request carries the turn onward, and the paired reminder gives
 				// the directive its own visible system-reminder line.
+				const message = activeAcceptance?.verification.length ? assessment.message : HIGH_RIGOR_REVALIDATION_MESSAGE;
 				return [
-					{ kind: "request_continuation", message: HIGH_RIGOR_REVALIDATION_MESSAGE },
-					{ kind: "inject_reminder", message: HIGH_RIGOR_REVALIDATION_MESSAGE, severity: "warn" },
+					{ kind: "request_continuation", message },
+					{ kind: "inject_reminder", message, severity: "warn" },
 				];
 			}
 			return [{ kind: "inject_reminder", message: assessment.message, severity: "warn" }];

package/src/domains/safety/finish-contract.ts

@@ -1,14 +1,18 @@
+import { resolve } from "node:path";
 import { ToolNames } from "../../core/tool-names.js";
 import { isProjectVerifierCheckId, isVerificationScriptName } from "../../core/verification-scripts.js";
+import { type DeclaredCheckSourceRef, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../../tools/verify/catalog.js";
+import type { UserTaskAcceptance } from "../user-tasks/acceptance.js";
 import {
 	detectValidationCommand,
 	extractCommandDeleteTargets,
 	extractCommandWriteTargets,
 	toolMutationPaths,
 } from "./protected-artifacts.js";
+import type { Rigor } from "./rigor.js";
 
 export const FINISH_CONTRACT_ADVISORY_MESSAGE =
-	"[Clio Coder] finish-contract advisory: you changed files this turn without recording validation evidence or an explicit limitation. Run a verification command or state what could not be verified.";
+	"[Clio Coder] finish-contract advisory: you changed files this turn without recording validation evidence or a limitation receipt. Run a verification command or call limitation with the scope and reason.";
 
 /**
  * The recent-window cap (entries since the last user message). Exported so a
@@ -17,11 +21,24 @@ export const FINISH_CONTRACT_ADVISORY_MESSAGE =
  */
 export const DEFAULT_RECENT_ENTRY_LIMIT = 80;
 
-export type FinishContractEvidenceKind = "validation_command" | "protected_artifact" | "dispatch_receipt";
+export type FinishContractEvidenceKind =
+	| "validation_command"
+	| "protected_artifact"
+	| "dispatch_receipt"
+	| "limitation";
+
+interface ValidationExecutionEvidence {
+	source?: DeclaredCheckSourceRef;
+	cwd?: string;
+	argv?: ReadonlyArray<string>;
+	durationMs?: number;
+}
 
-export interface FinishContractEvidence {
+export interface FinishContractEvidence extends ValidationExecutionEvidence {
 	kind: FinishContractEvidenceKind;
 	summary: string;
+	check?: string;
+	paths?: ReadonlyArray<string>;
 	turnId?: string;
 }
 
@@ -48,16 +65,22 @@ export type FinishContractAssessment =
 	  };
 
 export interface FinishContractInput {
-	assistantText: string;
 	sessionEntries?: ReadonlyArray<unknown>;
 	assistantTurnId?: string | null;
 	recentEntryLimit?: number;
+	rigor?: Rigor;
+	activeAcceptance?: UserTaskAcceptance;
+	/** Owning session workspace, supplied by the finish registration. */
+	workspaceRoot?: string;
 }
 
 interface ToolCallEvidenceCandidate {
 	turnId?: string;
 	toolCallId: string;
 	command: string;
+	check?: string;
+	paths?: string[];
+	execution?: ValidationExecutionEvidence;
 }
 
 interface MutationCandidate {
@@ -65,32 +88,26 @@ interface MutationCandidate {
 	paths: string[];
 }
 
-const LIMITATION_PATTERNS: ReadonlyArray<RegExp> = [
-	/\b(?:blocked by|blocker|blockers|unable to|not able to|could not|couldn't|cannot|can't)\b/i,
-	/\b(?:did not|didn't|have not|haven't|has not|hasn't|was not able|wasn't able)\b/i,
-	/\b(?:not complete|incomplete)\b/i,
-	/\b(?:not|un)(?:\s|-)?(?:validated|verified|tested)\b/i,
-	/^\s*Tests\s*:\s*(?:not run|not executed|not available|failed|blocked|skipped)\b/im,
-	/^\s*Known gaps?\s*:\s*(?!\s*(?:none|no\b|n\/a|not applicable)\b).+/im,
-	/\bremaining(?:\s+\w+){0,3}\s+(?:work|issue|issues|gap|gaps|blocker|blockers)\b/i,
-];
-
 /**
  * Action-scoped completion contract. The engine keys off what the turn actually
  * DID, not how the prompt was phrased: it engages only when the recent window
  * mutated workspace state and then settled (turn_end) without recording
- * validation evidence or an explicit limitation. The turn settling is itself
+ * validation evidence or a limitation receipt. The turn settling is itself
  * the completion signal, so the model never has to type "done" to be gated, and
  * a work request phrased as a question cannot bypass the gate.
  *
  * Decision order (pure function of ledger receipts):
  *   1. no mutating receipt in the window        -> ok/no_mutation
  *   2. validation evidence present              -> ok/validation_evidence
- *   3. explicit limitation stated in the text   -> ok/explicit_limitation
+ *   3. successful `limitation` receipt present  -> ok/explicit_limitation
  *   4. otherwise                                -> engage/unvalidated_mutation
+ *
+ * The assistant's prose never enters the decision. A limitation counts only
+ * as a `limitation` tool_call paired with a non-error tool_result inside the
+ * same window the mutation scan uses, so a run cannot satisfy the contract by
+ * wording alone and a real limitation is never missed for its phrasing.
  */
 export function assessFinishContract(input: FinishContractInput): FinishContractAssessment {
-	const assistantText = input.assistantText.trim();
 	const sessionEntries = input.sessionEntries ?? [];
 	const assistantTurnId = input.assistantTurnId ?? null;
 	const window = recentEntries(sessionEntries, assistantTurnId, input.recentEntryLimit ?? DEFAULT_RECENT_ENTRY_LIMIT);
@@ -100,13 +117,39 @@ export function assessFinishContract(input: FinishContractInput): FinishContract
 		return { kind: "ok", reason: "no_mutation", evidence: [], mutatedPaths };
 	}
 
-	const evidence = collectValidationEvidence(window);
+	const acceptanceChecks = new Set(input.activeAcceptance?.verification.map((item) => item.check) ?? []);
+	const evidence = collectValidationEvidence(window, acceptanceChecks, input.workspaceRoot);
+	const limitations = collectLimitationEvidence(window);
+	const required = input.rigor === "high" ? (input.activeAcceptance?.verification ?? []) : [];
+	if (required.length > 0) {
+		const passes = new Set(
+			required.filter((check) => evidence.some((item) => acceptanceCheckPassed(item, check, input.workspaceRoot))),
+		);
+		const limited = new Set(limitations.flatMap((item) => item.paths ?? []));
+		const missing = [
+			...new Set(required.filter((check) => !passes.has(check) && !limited.has(check.check)).map((item) => item.check)),
+		];
+		if (missing.length > 0)
+			return {
+				kind: "engage",
+				reason: "unvalidated_mutation",
+				message: `[Clio Coder] high-rigor finish gate: operator acceptance still requires passing validation for: ${missing.join(", ")}. Run each named check or include its exact id in limitation.paths.`,
+				evidence: [...evidence, ...limitations],
+				mutatedPaths,
+			};
+		return {
+			kind: "ok",
+			reason: passes.size === required.length ? "validation_evidence" : "explicit_limitation",
+			evidence: [...evidence, ...limitations],
+			mutatedPaths,
+		};
+	}
 	if (evidence.length > 0) {
 		return { kind: "ok", reason: "validation_evidence", evidence, mutatedPaths };
 	}
 
-	if (hasExplicitLimitation(assistantText)) {
-		return { kind: "ok", reason: "explicit_limitation", evidence: [], mutatedPaths };
+	if (limitations.length > 0) {
+		return { kind: "ok", reason: "explicit_limitation", evidence: limitations, mutatedPaths };
 	}
 
 	return {
@@ -118,16 +161,80 @@ export function assessFinishContract(input: FinishContractInput): FinishContract
 	};
 }
 
+function acceptanceCheckPassed(
+	evidence: FinishContractEvidence,
+	required: UserTaskAcceptance["verification"][number],
+	workspaceRoot: string | undefined,
+): boolean {
+	if (evidence.kind !== "validation_command" || evidence.check !== required.check || !workspaceRoot || !evidence.source)
+		return false;
+	if (evidence.durationMs !== undefined && evidence.durationMs > required.timeoutMs) return false;
+	const root = resolve(workspaceRoot);
+	if (evidence.source.kind === "project-catalog")
+		return evidence.source.path === resolve(root, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH);
+	return (
+		evidence.source.path === resolve(root, "package.json") &&
+		evidence.cwd === root &&
+		validationCheckId(evidence.argv?.join(" ") ?? "") === required.check
+	);
+}
+
 /**
- * The single retained text escape valve: the assistant explicitly states what
- * it could not verify. Everything else about the contract is receipt-grounded;
- * this is the one place prose still drives the decision. Candidate for a future
- * structured "limitation" signal so the whole gate becomes text-independent.
+ * Successful `limitation` receipts over the recent window. A receipt is a
+ * `limitation` tool_call whose tool_result in the same window is not an
+ * error, judged by the same `successfulToolResultId` rule the mutation and
+ * validation scans use. A call the tool rejected (bad reason, empty scope)
+ * leaves no receipt, so it cannot settle the contract.
  */
-function hasExplicitLimitation(text: string): boolean {
-	const normalized = text.trim();
-	if (normalized.length === 0) return false;
-	return LIMITATION_PATTERNS.some((pattern) => pattern.test(normalized));
+function collectLimitationEvidence(recent: ReadonlyArray<unknown>): FinishContractEvidence[] {
+	const evidence: FinishContractEvidence[] = [];
+	const calls = new Map<string, ToolCallEvidenceCandidate>();
+	const seen = new Set<string>();
+
+	for (const entry of recent) {
+		const call = limitationToolCall(entry);
+		if (call !== null) {
+			calls.set(call.toolCallId, call);
+			continue;
+		}
+		const resultId = successfulToolResultId(entry);
+		if (resultId === null) continue;
+		const candidate = calls.get(resultId);
+		if (candidate === undefined) continue;
+		const item: FinishContractEvidence = {
+			kind: "limitation",
+			summary: candidate.command,
+			...(candidate.paths ? { paths: candidate.paths } : {}),
+		};
+		if (candidate.turnId !== undefined) item.turnId = candidate.turnId;
+		pushEvidence(evidence, seen, item);
+	}
+
+	return evidence;
+}
+
+function limitationToolCall(entry: unknown): ToolCallEvidenceCandidate | null {
+	const record = asRecord(entry);
+	if (record?.kind !== "message" || record.role !== "tool_call") return null;
+	const payload = asRecord(record.payload);
+	if (payload === null) return null;
+	const toolName = stringFromFirst(payload, ["name", "toolName", "tool"]);
+	if (toolName !== ToolNames.Limitation) return null;
+	const toolCallId = stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]) ?? turnIdOf(entry);
+	if (toolCallId === null) return null;
+	const args = asRecord(payload.args ?? payload.arguments ?? payload.input);
+	const scope = typeof args?.scope === "string" ? args.scope.trim() : "";
+	const reason = typeof args?.reason === "string" ? args.reason.trim() : "";
+	const candidate: ToolCallEvidenceCandidate = {
+		toolCallId,
+		paths: Array.isArray(args?.paths)
+			? args.paths.filter((item): item is string => typeof item === "string").map((item) => item.trim())
+			: [],
+		command: `limitation recorded: ${scope.length > 0 ? scope : "unspecified"} (reason=${reason.length > 0 ? reason : "unspecified"})`,
+	};
+	const turnId = turnIdOf(entry);
+	if (turnId !== null) candidate.turnId = turnId;
+	return candidate;
 }
 
 /**
@@ -226,7 +333,11 @@ function pushPath(paths: string[], seen: Set<string>, path: string): void {
  * Inspection was removed because inspecting the repo is never a mutation, so it
  * can no longer be on the path to engaging the contract.
  */
-function collectValidationEvidence(recent: ReadonlyArray<unknown>): FinishContractEvidence[] {
+function collectValidationEvidence(
+	recent: ReadonlyArray<unknown>,
+	acceptanceChecks: ReadonlySet<string>,
+	workspaceRoot: string | undefined,
+): FinishContractEvidence[] {
 	const evidence: FinishContractEvidence[] = [];
 	const toolCalls = new Map<string, ToolCallEvidenceCandidate>();
 	const dispatchCalls = new Map<string, ToolCallEvidenceCandidate>();
@@ -239,7 +350,7 @@ function collectValidationEvidence(recent: ReadonlyArray<unknown>): FinishContra
 			continue;
 		}
 
-		const call = bashValidationCall(entry);
+		const call = bashValidationCall(entry, acceptanceChecks, workspaceRoot);
 		if (call !== null) {
 			toolCalls.set(call.toolCallId, call);
 			continue;
@@ -267,19 +378,19 @@ function collectValidationEvidence(recent: ReadonlyArray<unknown>): FinishContra
 			}
 			const candidate = toolCalls.get(resultId);
 			if (candidate !== undefined) {
-				pushEvidence(evidence, seen, validationEvidence(candidate));
+				pushEvidence(evidence, seen, validationEvidence(candidate, entry));
 			}
 			continue;
 		}
 
-		const bashExecution = bashExecutionEvidence(entry);
+		const bashExecution = bashExecutionEvidence(entry, acceptanceChecks, workspaceRoot);
 		if (bashExecution !== null) pushEvidence(evidence, seen, bashExecution);
 	}
 
 	return evidence;
 }
 
-function recentEntries(
+export function recentEntries(
 	entries: ReadonlyArray<unknown>,
 	assistantTurnId: string | null,
 	recentEntryLimit: number,
@@ -299,7 +410,11 @@ function recentEntries(
 	return entries.slice(startInclusive, endExclusive);
 }
 
-function bashValidationCall(entry: unknown): ToolCallEvidenceCandidate | null {
+function bashValidationCall(
+	entry: unknown,
+	acceptanceChecks: ReadonlySet<string>,
+	workspaceRoot: string | undefined,
+): ToolCallEvidenceCandidate | null {
 	const record = asRecord(entry);
 	if (record?.kind !== "message" || record.role !== "tool_call") return null;
 	const payload = asRecord(record.payload);
@@ -309,13 +424,15 @@ function bashValidationCall(entry: unknown): ToolCallEvidenceCandidate | null {
 	const args = asRecord(payload.args ?? payload.arguments ?? payload.input);
 	const command = typeof args?.command === "string" ? args.command : null;
 	if (command === null) return null;
-	const detected = detectValidationCommand(command);
+	const detected = acceptanceValidationCommand(command, acceptanceChecks);
 	if (detected.kind !== "validation") return null;
 	const toolCallId = stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]) ?? turnIdOf(entry);
 	if (toolCallId === null) return null;
 	const candidate: ToolCallEvidenceCandidate = {
 		toolCallId,
 		command: detected.matched,
+		...validationCheckFields(detected.matched),
+		execution: packageCommandExecution(command, args?.cwd, workspaceRoot),
 	};
 	const turnId = turnIdOf(entry);
 	if (turnId !== null) candidate.turnId = turnId;
@@ -380,6 +497,7 @@ function validationToolCall(entry: unknown): ToolCallEvidenceCandidate | null {
 	const candidate: ToolCallEvidenceCandidate = {
 		toolCallId,
 		command: summary,
+		...validationCheckFields(summary),
 	};
 	const turnId = turnIdOf(entry);
 	if (turnId !== null) candidate.turnId = turnId;
@@ -414,7 +532,8 @@ function successfulToolResultId(entry: unknown): string | null {
 	if (payload.isError === true || payload.error === true) return null;
 	const result = asRecord(payload.result);
 	const details = asRecord(result?.details);
-	if (details?.kind === "error") return null;
+	if (result?.kind === "error" || details?.kind === "error") return null;
+	if (typeof details?.exitCode === "number" && details.exitCode !== 0) return null;
 	return stringFromFirst(payload, ["toolCallId", "tool_call_id", "id"]);
 }
 
@@ -482,18 +601,24 @@ function dispatchReceiptAgentId(
 	return candidate?.command.match(/^agent=([^\s]+)/)?.[1] ?? "unknown";
 }
 
-function bashExecutionEvidence(entry: unknown): FinishContractEvidence | null {
+function bashExecutionEvidence(
+	entry: unknown,
+	acceptanceChecks: ReadonlySet<string>,
+	workspaceRoot: string | undefined,
+): FinishContractEvidence | null {
 	const record = asRecord(entry);
 	if (record?.kind !== "bashExecution") return null;
 	if (typeof record.command !== "string") return null;
 	if (record.cancelled === true) return null;
 	if (record.exitCode !== 0) return null;
-	const detected = detectValidationCommand(record.command);
+	const detected = acceptanceValidationCommand(record.command, acceptanceChecks);
 	if (detected.kind !== "validation") return null;
 	const contextMarker = record.excludeFromContext === true ? " [not sent to model]" : "";
 	const evidence: FinishContractEvidence = {
 		kind: "validation_command",
 		summary: `validation command passed: ${detected.matched}${contextMarker}`,
+		...validationCheckFields(detected.matched),
+		...packageCommandExecution(record.command, record.cwd, workspaceRoot),
 	};
 	const turnId = turnIdOf(entry);
 	if (turnId !== null) evidence.turnId = turnId;
@@ -515,17 +640,80 @@ function protectedArtifactEvidence(entry: unknown): FinishContractEvidence | nul
 	return evidence;
 }
 
-function validationEvidence(candidate: ToolCallEvidenceCandidate): FinishContractEvidence {
+function validationEvidence(candidate: ToolCallEvidenceCandidate, entry: unknown): FinishContractEvidence {
 	const evidence: FinishContractEvidence = {
 		kind: "validation_command",
 		summary: `validation command passed: ${candidate.command}`,
+		...(candidate.check ? { check: candidate.check } : {}),
+		...(candidate.execution ?? declaredCheckExecution(entry, candidate.check)),
 	};
 	if (candidate.turnId !== undefined) evidence.turnId = candidate.turnId;
 	return evidence;
 }
 
+/** Preserve the verifier's execution facts only when they identify the declared check. */
+function declaredCheckExecution(entry: unknown, check: string | undefined): ValidationExecutionEvidence {
+	const payload = asRecord(asRecord(entry)?.payload);
+	const details = asRecord(asRecord(payload?.result)?.details);
+	const source = asRecord(details?.source);
+	if (
+		!details ||
+		details.check !== check ||
+		details.exitCode !== 0 ||
+		details.aborted === true ||
+		details.timedOut === true ||
+		details.outputCapped === true ||
+		(source?.kind !== "package.json" && source?.kind !== "project-catalog") ||
+		typeof source.path !== "string" ||
+		typeof details.cwd !== "string" ||
+		!Array.isArray(details.argv) ||
+		!details.argv.every((arg): arg is string => typeof arg === "string")
+	)
+		return {};
+	if (source.kind === "project-catalog") {
+		const argv = details.argv;
+		if (
+			!Array.isArray(details.declaredCommand) ||
+			details.declaredCommand.length !== details.argv.length ||
+			!details.declaredCommand.every((arg, index) => arg === argv[index]) ||
+			typeof details.declaredCwd !== "string" ||
+			typeof details.declaredTimeoutMs !== "number" ||
+			typeof details.durationMs !== "number" ||
+			details.durationMs > details.declaredTimeoutMs ||
+			resolve(source.path, "../..", details.declaredCwd) !== details.cwd
+		)
+			return {};
+	}
+	return {
+		source: { kind: source.kind, path: source.path },
+		cwd: details.cwd,
+		argv: details.argv,
+		...(typeof details.durationMs === "number" ? { durationMs: details.durationMs } : {}),
+	};
+}
+
+/** Exact package commands retain their execution cwd; a matched substring proves no project identity. */
+function packageCommandExecution(
+	command: string,
+	cwd: unknown,
+	workspaceRoot: string | undefined,
+): ValidationExecutionEvidence {
+	if (
+		!workspaceRoot ||
+		!/^(?:npm|pnpm|yarn|bun) /u.test(command.trim()) ||
+		validationCheckId(command.trim()) === undefined
+	)
+		return {};
+	const executionCwd = resolve(workspaceRoot, typeof cwd === "string" ? cwd : ".");
+	return {
+		source: { kind: "package.json", path: resolve(executionCwd, "package.json") },
+		cwd: executionCwd,
+		argv: command.trim().split(/\s+/u),
+	};
+}
+
 function pushEvidence(evidence: FinishContractEvidence[], seen: Set<string>, item: FinishContractEvidence): void {
-	const key = `${item.kind}\0${item.summary}\0${item.turnId ?? ""}`;
+	const key = JSON.stringify(item);
 	if (seen.has(key)) return;
 	seen.add(key);
 	evidence.push(item);
@@ -554,3 +742,27 @@ function stringFromFirst(record: Record<string, unknown>, keys: ReadonlyArray<st
 function asRecord(value: unknown): Record<string, unknown> | null {
 	return value !== null && typeof value === "object" ? (value as Record<string, unknown>) : null;
 }
+
+/** Exact check ids, never substring matches against rendered evidence summaries. */
+function validationCheckId(command: string): string | undefined {
+	return (
+		/^(?:npm|pnpm|yarn|bun) (?:run )?([a-z0-9][a-z0-9._:-]*)$/.exec(command)?.[1] ??
+		/^verify ([a-z0-9][a-z0-9._:-]*)$/.exec(command)?.[1]
+	);
+}
+
+function validationCheckFields(command: string): { check?: string } {
+	const check = validationCheckId(command);
+	return check ? { check } : {};
+}
+
+/** Additional package scripts are admitted only by the operator's typed acceptance. */
+function acceptanceValidationCommand(
+	command: string,
+	checks: ReadonlySet<string>,
+): ReturnType<typeof detectValidationCommand> {
+	const exact = command.trim();
+	const check = /^npm run ([a-z0-9][a-z0-9._:-]*)$/.exec(exact)?.[1];
+	if (check && checks.has(check)) return { kind: "validation", matched: exact };
+	return detectValidationCommand(command);
+}

package/src/domains/safety/index.ts

@@ -42,4 +42,23 @@ export {
 	type PathPolicyKind,
 	type PathPolicyOperation,
 } from "./path-policy.js";
-export { parseRigorOverride, type Rigor, resolveRigor } from "./rigor.js";
+export {
+	parseRigorOverride,
+	type Rigor,
+	type RigorResolution,
+	type RigorSource,
+	resolveRigor,
+	rigorResolution,
+} from "./rigor.js";
+export {
+	describeValidationContract,
+	loadValidationContract,
+	parseValidationContractText,
+	VALIDATION_CONTRACT_CAPS,
+	VALIDATION_CONTRACT_MARKDOWN_PATH,
+	VALIDATION_CONTRACT_YAML_PATHS,
+	type ValidationContract,
+	type ValidationContractArtifact,
+	type ValidationContractLoadResult,
+	type ValidationContractRuntime,
+} from "./validation-contract.js";