@iowarp/clio-coder 0.4.3 → 0.4.4

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";

package/src/domains/safety/policy-engine.ts

@@ -204,12 +204,15 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 	const pathPolicyInput = projectPolicy.disableDefaultPathPolicy
 		? projectPolicy.pathPolicy
 		: mergePathPolicyInputs(DEFAULT_DAMAGE_CONTROL_PATH_POLICY, projectPolicy.pathPolicy);
-	// Clio's own secret store, by absolute path. The static default list carries
-	// the `credentials.yaml` literal; the expansion has to happen here because
+	// Clio's own secret store and user skills, by absolute path.
+	// Config directory expansion has to happen here because
 	// the list cannot call config helpers at module scope.
 	const expandedDefaults = projectPolicy.disableDefaultPathPolicy
 		? pathPolicyInput
-		: mergePathPolicyInputs(pathPolicyInput, { zeroAccessPaths: clioCredentialStorePaths() });
+		: mergePathPolicyInputs(pathPolicyInput, {
+				zeroAccessPaths: clioCredentialStorePaths(),
+				readOnlyPaths: clioSkillsRootPaths(),
+			});
 	const pathPolicy = compilePathPolicy(expandedDefaults, projectPolicyRoot);
 	// Bash-read scanning tests argument tokens against zero-access entries only:
 	// read-only paths stay readable from bash by design, secrets do not.
@@ -478,6 +481,15 @@ function clioCredentialStorePaths(): string[] {
 	}
 }
 
+/** Absolute path of Clio's user skills, when resolvable. */
+function clioSkillsRootPaths(): string[] {
+	try {
+		return [path.join(clioConfigDir(), "skills")];
+	} catch {
+		return [];
+	}
+}
+
 /**
  * The exact safe presence form: `grep -q` or `grep -sq` (either flag order)
  * with a `^NAME=`-shaped pattern and a single file argument. Exit code only;
@@ -966,10 +978,16 @@ function cwdArg(args: Record<string, unknown> | undefined, fallback: string): st
 }
 
 /**
- * Tools whose arguments are a file's contents rather than a command line.
- * Their damage-control scan is the destination path alone.
+ * Tools whose arguments carry file contents or task prose, not command lines.
+ * Their damage-control scan is the destination path alone, when present.
  */
-const CONTENT_BEARING_TOOLS: ReadonlySet<string> = new Set([ToolNames.Write, ToolNames.Edit, ToolNames.Artifact]);
+const CONTENT_BEARING_TOOLS: ReadonlySet<string> = new Set([
+	ToolNames.Write,
+	ToolNames.Edit,
+	ToolNames.Artifact,
+	ToolNames.Dispatch,
+	ToolNames.Tasks,
+]);
 
 /**
  * The text damage-control rules are matched against.
@@ -991,6 +1009,8 @@ const CONTENT_BEARING_TOOLS: ReadonlySet<string> = new Set([ToolNames.Write, Too
  * full. Only the destination path is scanned for a mutation tool, which keeps
  * any path-shaped rule working; where the file may land is the write tool's own
  * gate in `writePathClass`.
+ * Dispatch and task-board prose likewise does not execute; worker commands
+ * are scanned when the worker calls an execute-class tool.
  */
 function damageControlScan(call: ClassifierCall): string {
 	if (!CONTENT_BEARING_TOOLS.has(call.tool)) return serializeArgs(call.args);

package/src/domains/safety/rigor.ts

@@ -5,44 +5,71 @@
  *
  * - `normal`: the finish-contract advisory stays a soft `warn` reminder.
  * - `high`: an unvalidated completion claim re-prompts the model to run
- *   validation or state a limitation before the turn settles.
+ *   validation or record a limitation before the turn settles.
  *
  * Rigor resolves from a per-session / per-dispatch override (the `CLIO_CODER_RIGOR`
  * env var today) layered over a repo-derived default. The repo-derived default
- * is `high` when the workspace declares a scientific-validation contract by the
- * documented path convention below, and `normal` otherwise. This keeps the
- * evidence bar derived from what the repo actually is rather than from a global
- * toggle.
+ * is `high` only when the workspace's scientific-validation contract parses
+ * under the version-1 schema in `validation-contract.ts`. A contract that
+ * fails to parse is diagnosed and leaves rigor at `normal`, and a Markdown
+ * `VALIDATION.md` is advisory prose that never raises rigor on its own. This
+ * keeps the evidence bar derived from what the repo actually declares rather
+ * than from a filename or a global toggle.
  */
 
-import { existsSync } from "node:fs";
-import path from "node:path";
+import { describeValidationContract, loadValidationContract } from "./validation-contract.js";
 
 export type Rigor = "normal" | "high";
 
-/**
- * Workspace-root files that declare a scientific-validation contract. Presence
- * of any one of these raises the repo-derived rigor default to `high`. The
- * convention is intentionally small and explicit: a project opts into a higher
- * evidence bar by committing a validation contract at its root.
- */
-const VALIDATION_CONTRACT_FILES: ReadonlyArray<string> = [
-	path.join(".clio-coder", "validation.yaml"),
-	path.join(".clio-coder", "validation.yml"),
-	"validation.yaml",
-	"validation.yml",
-	"VALIDATION.md",
-];
+/** Why rigor settled where it did, so a caller can print the reason. */
+export type RigorSource = "override" | "validation-contract" | "invalid-contract" | "markdown-advisory" | "none";
+
+export interface RigorResolution {
+	rigor: Rigor;
+	source: RigorSource;
+	/** Present when a contract was found but could not raise rigor: the parse fault or the Markdown advisory note. */
+	diagnostic?: string;
+	/** The repository-relative contract path, when one was found. */
+	contractPath?: string;
+}
+
+export interface RigorOptions {
+	cwd?: string;
+	override?: Rigor | null;
+}
 
 /**
- * Resolve the effective rigor. An explicit override (`"high"` | `"normal"`)
- * always wins; otherwise the repo-derived default keys off the presence of a
- * validation contract at the workspace root.
+ * Resolve the effective rigor and the reason for it. An explicit override
+ * (`"high"` | `"normal"`) always wins; otherwise the repo-derived default keys
+ * off the parsed validation contract at the workspace root.
  */
-export function resolveRigor(options: { cwd?: string; override?: Rigor | null }): Rigor {
-	if (options.override === "high" || options.override === "normal") return options.override;
+export function rigorResolution(options: RigorOptions): RigorResolution {
+	if (options.override === "high" || options.override === "normal") {
+		return { rigor: options.override, source: "override" };
+	}
 	const cwd = options.cwd ?? process.cwd();
-	return hasValidationContract(cwd) ? "high" : "normal";
+	const loaded = loadValidationContract(cwd);
+	if (!loaded.ok) {
+		const resolution: RigorResolution = { rigor: "normal", source: "invalid-contract", contractPath: loaded.path };
+		const diagnostic = describeValidationContract(loaded);
+		if (diagnostic !== null) resolution.diagnostic = diagnostic;
+		return resolution;
+	}
+	if (loaded.contract !== null) {
+		return { rigor: "high", source: "validation-contract", contractPath: loaded.path };
+	}
+	if ("advisory" in loaded) {
+		const resolution: RigorResolution = { rigor: "normal", source: "markdown-advisory", contractPath: loaded.path };
+		const diagnostic = describeValidationContract(loaded);
+		if (diagnostic !== null) resolution.diagnostic = diagnostic;
+		return resolution;
+	}
+	return { rigor: "normal", source: "none" };
+}
+
+/** The effective rigor alone; see {@link rigorResolution} for the reason. */
+export function resolveRigor(options: RigorOptions): Rigor {
+	return rigorResolution(options).rigor;
 }
 
 /**
@@ -57,16 +84,3 @@ export function parseRigorOverride(value: string | null | undefined): Rigor | nu
 	if (normalized === "normal") return "normal";
 	return null;
 }
-
-/**
- * True when the workspace declares a scientific-validation contract by the
- * documented path convention. Pure and resilient: any filesystem error is
- * swallowed and treated as "no contract".
- */
-function hasValidationContract(cwd: string): boolean {
-	try {
-		return VALIDATION_CONTRACT_FILES.some((relative) => existsSync(path.join(cwd, relative)));
-	} catch {
-		return false;
-	}
-}