@iowarp/clio-coder 0.4.3 → 0.4.5

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

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
 import path from "node:path";
 import { artifactDefaultPath } from "../../core/artifact-paths.js";
 import { pathBoundaryCovers, resolvePathBoundary } from "../../core/path-boundary.js";
@@ -8,7 +9,11 @@ import { clioConfigDir } from "../../core/xdg.js";
 import { type DeclaredCheck, loadProjectVerifierCatalog } from "../../tools/verify/catalog.js";
 import { type ActionClass, type Classification, type ClassifierCall, classify } from "./action-classifier.js";
 import type { DamageControlMatch, DamageControlRule } from "./damage-control.js";
-import { DEFAULT_DAMAGE_CONTROL_PATH_POLICY, mergePathPolicyInputs } from "./default-path-policy.js";
+import {
+	DEFAULT_DAMAGE_CONTROL_PATH_POLICY,
+	mergePathPolicyInputs,
+	OPERATOR_PATH_POLICY,
+} from "./default-path-policy.js";
 import {
 	type CompiledPathPolicy,
 	compilePathPolicy,
@@ -32,6 +37,8 @@ import { formatRejection, type RejectionMessage } from "./rejection-feedback.js"
 import { getCachedDefaultRulePacks, type PackId, type RulePacks } from "./rule-pack-loader.js";
 import { activeClioSkillRoots, skillMutationReason } from "./skill-authority.js";
 
+import { gateProjectSafetyPolicy, workspaceTrustDirectory } from "./workspace-trust.js";
+
 export type SafetyPolicySource =
 	| "damage-control:base"
 	| "project-policy"
@@ -79,6 +86,8 @@ export interface SafetyPolicyMetadata {
 	projectPolicyHash: string | null;
 	projectPolicyValid: boolean;
 	projectPolicyErrors: ReadonlyArray<string>;
+	disableDefaultPathPolicy?: boolean;
+	workspaceTrustVerdict?: "trusted" | "untrusted" | "changed";
 	cwd: string;
 }
 
@@ -113,6 +122,9 @@ const BUILTIN_ALLOWLIST: ReadonlyArray<{ id: string; re: RegExp }> = [
 	{ id: "builtin:git-status", re: /^git\s+status(?:\s+--short|\s+--branch|\s+-sb)*$/ },
 	{ id: "builtin:git-diff", re: /^git\s+diff(?:\s+--cached|\s+--stat|\s+--name-only|\s+--\s+[\w./-]+)*$/ },
 	{ id: "builtin:git-log", re: /^git\s+log\s+--oneline(?:\s+-n\s+[1-9]\d{0,2})?(?:\s+--\s+[\w./-]+)?$/ },
+];
+
+const PROJECT_SCRIPT_COMMANDS: ReadonlyArray<{ id: string; re: RegExp }> = [
 	{ id: "builtin:npm-test", re: /^npm\s+(?:test|run\s+test)(?:\s+--\s+[\w=./:-]+(?:\s+[\w=./:-]+)*)?$/ },
 	{ id: "builtin:npm-lint", re: /^npm\s+run\s+lint(?:\s+--\s+[\w=./:-]+(?:\s+[\w=./:-]+)*)?$/ },
 	{ id: "builtin:npm-build", re: /^npm\s+run\s+build(?:\s+--\s+[\w=./:-]+(?:\s+[\w=./:-]+)*)?$/ },
@@ -198,18 +210,19 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 	const writeRoots = (options.writeRoots ?? []).map((root) => resolvePathBoundary(writeRootCwd, root));
 	const skillRoots = activeClioSkillRoots(cwd);
 	const packs = options.rulePacks ?? getCachedDefaultRulePacks();
-	const projectPolicy = options.projectPolicy ?? loadProjectSafetyPolicy(cwd);
+	const projectPolicy = options.projectPolicy ?? gateProjectSafetyPolicy(cwd, loadProjectSafetyPolicy(cwd));
 	const projectPolicyRoot =
-		projectPolicy.path === null ? cwd : path.dirname(path.dirname(canonicalizeExistingPath(projectPolicy.path)));
+		projectPolicy.path === null ? cwd : path.dirname(path.dirname(path.resolve(projectPolicy.path)));
 	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() });
+	const expandedDefaults = mergePathPolicyInputs(mergePathPolicyInputs(pathPolicyInput, OPERATOR_PATH_POLICY), {
+		zeroAccessPaths: clioCredentialStorePaths(),
+		readOnlyPaths: [...clioSkillsRootPaths(), path.join(clioConfigDir(), "settings.yaml"), workspaceTrustDirectory()],
+	});
 	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.
@@ -314,6 +327,31 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 			// Editing active instructions is an operator privilege at every autonomy
 			// level, in both the coordinator and the shared worker safety contract.
 			const mutationCommand = call.tool === ToolNames.Bash ? command : catalogCommand;
+			if (mutationCommand !== null && invokesTrustMutation(mutationCommand)) {
+				return blockDecision(base, {
+					reasonCode: "trust-authority",
+					ruleId: "trust-authority",
+					reasons: ["workspace trust grants require the operator CLI"],
+					policySource: "builtin-classifier",
+				});
+			}
+			// Reuse the canonical authority boundary scan for parent deletions,
+			// shell cwd changes and aliases that a literal path-policy lookup misses.
+			if (
+				skillMutationReason(
+					[path.join(clioConfigDir(), "settings.yaml"), workspaceTrustDirectory()],
+					pathPolicyTargets(catalogCommand === null ? call : { tool: ToolNames.Bash, args: { command: catalogCommand } }),
+					callCwd,
+					mutationCommand,
+				) !== null
+			) {
+				return blockDecision(base, {
+					reasonCode: "path-policy:readOnlyPaths",
+					ruleId: "path-policy:readOnlyPaths",
+					reasons: ["Clio settings and workspace trust records are operator-owned and cannot be mutated by tools"],
+					policySource: "builtin-classifier",
+				});
+			}
 			const skillReason =
 				mutationCommand !== null && invokesClioSkillMutation(mutationCommand)
 					? "skill installation and updates require the operator CLI or an explicit operator install choice; draft outside active skill roots"
@@ -418,8 +456,39 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 				return posture === "confirmed" ? allowDecision(base, input) : askDecision(base, input);
 			}
 
-			if (call.tool === ToolNames.Bash && classification.actionClass === "execute") {
-				const bash = evaluateBashPolicy(command ?? "", callCwd, cwd, posture, projectPolicy);
+			const packageCommand =
+				call.tool === ToolNames.Verify &&
+				catalogCheck === null &&
+				typeof call.args?.check === "string" &&
+				call.args.check !== "frontend"
+					? `npm run ${call.args.check}`
+					: null;
+			if (
+				(call.tool === ToolNames.Bash || catalogCheck !== null || packageCommand !== null) &&
+				classification.actionClass === "execute"
+			) {
+				const bash = evaluateBashPolicy(
+					catalogCheck?.command ?? packageCommand ?? command ?? "",
+					catalogCheck === null ? callCwd : path.resolve(cwd, catalogCheck.cwd),
+					cwd,
+					posture,
+					projectPolicy,
+				);
+				if (
+					(catalogCheck !== null || packageCommand !== null) &&
+					bash.kind === "allow" &&
+					bash.execRecognition !== "recognized" &&
+					posture !== "confirmed"
+				) {
+					return askDecision(base, {
+						...bash,
+						reasonCode: "project-verifier-confirm",
+						reasons: [
+							...bash.reasons,
+							`Repository verifier requires confirmation or an approved safety declaration: ${catalogCommand ?? packageCommand}`,
+						],
+					});
+				}
 				if (bash.kind === "block") return blockDecision(base, bash);
 				if (bash.kind === "ask") return askDecision(base, bash);
 				return allowDecision(base, bash);
@@ -435,22 +504,9 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 			};
 			if (hit?.match.ruleId !== undefined) allowInput.ruleId = hit.match.ruleId;
 			if (hit?.match !== undefined) allowInput.match = hit.match;
-			// The typed execution tool (verify) sits in the no-prompt set when the
-			// check is a package script or the frontend validator: both are bounded
-			// by the verification-script family and run a fixed argv shape. A
-			// project-catalog check runs whatever argv the workspace file declares,
-			// so it is unrecognized: auto-edit parks it for one confirmation that
-			// shows the argv, full-auto runs it, and the damage-control match and
-			// zero-access scan above have already seen the declared vector.
-			if (classification.actionClass === "execute") {
-				allowInput.execRecognition = catalogCheck === null ? "recognized" : "unrecognized";
-				if (catalogCheck !== null) {
-					allowInput.reasons = [
-						...allowInput.reasons,
-						`project verifier '${catalogCheck.id}' runs declared argv: ${catalogCommand ?? ""}`,
-					];
-				}
-			}
+			// Catalog argv already went through canonical command recognition above.
+			// Package scripts and the frontend validator retain their fixed typed surface.
+			if (classification.actionClass === "execute") allowInput.execRecognition = "recognized";
 			return allowDecision(base, allowInput);
 		},
 		metadata() {
@@ -463,6 +519,8 @@ export function createSafetyPolicyEngine(options: SafetyPolicyEngineOptions = {}
 				projectPolicyHash: projectPolicy.hash,
 				projectPolicyValid: projectPolicy.valid,
 				projectPolicyErrors: [...projectPolicy.errors, ...pathPolicy.diagnostics],
+				disableDefaultPathPolicy: projectPolicy.disableDefaultPathPolicy,
+				workspaceTrustVerdict: projectPolicy.trustVerdict ?? "trusted",
 				cwd,
 			};
 		},
@@ -478,6 +536,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;
@@ -601,12 +668,27 @@ function pathPolicyTargets(call: ClassifierCall): Array<{ operation: PathPolicyO
  * admission seam decides whether it runs, asks, or is denied.
  */
 function evaluateBashPolicy(
-	command: string,
+	input: string | ReadonlyArray<string>,
 	callCwd: string,
 	workspaceRoot: string,
 	posture: string | undefined,
 	policy: LoadedProjectSafetyPolicy,
 ): Omit<SafetyPolicyDecision, "classification" | "tool" | "actionClass" | "cwd" | "posture" | "command"> {
+	// Catalog commands execute as argv, never as shell source. Only bare words
+	// have an unambiguous representation in the canonical command matcher.
+	// Keep whitespace, empty arguments, and shell syntax out of recognition;
+	// joining them would erase argument boundaries or invent a shell chain.
+	if (typeof input !== "string" && !input.every((arg) => /^[\w=./:-]+$/u.test(arg))) {
+		return {
+			kind: posture === "confirmed" ? "allow" : "ask",
+			ruleId: "verify-unrecognized-argv",
+			reasonCode: "verify-unrecognized-argv",
+			reasons: ["project verifier argv is outside the bare-word no-prompt command set"],
+			policySource: "builtin-command-allowlist",
+			execRecognition: "unrecognized",
+		};
+	}
+	const command = typeof input === "string" ? input : input.join(" ");
 	if (command.trim().length === 0) {
 		return {
 			kind: "block",
@@ -616,6 +698,21 @@ function evaluateBashPolicy(
 			policySource: "builtin-command-allowlist",
 		};
 	}
+	if (
+		typeof input === "string" &&
+		(/\$(?:[A-Za-z_{0-9@*#?!-])/.test(command) ||
+			/(?:^|[\s;&|])(?:python[\d.]*|node|ruby|perl|php|lua)\s+(?:[^\n]*?\s)?-[ce]\b/.test(command)) &&
+		posture !== "confirmed"
+	) {
+		return {
+			kind: "ask",
+			reasonCode: "bash-hidden-content",
+			ruleId: "bash-hidden-content",
+			reasons: ["shell variables or interpreter source hide paths from the safety scan and require one-shot confirmation"],
+			policySource: "builtin-command-allowlist",
+			execRecognition: "unrecognized",
+		};
+	}
 	const projectMatch = matchingProjectCommand(policy, command, callCwd);
 	if (projectMatch) {
 		const base: Omit<
@@ -668,15 +765,34 @@ function evaluateBashPolicy(
 			execRecognition: "unrecognized",
 		};
 	}
+	if (PROJECT_SCRIPT_COMMANDS.some((entry) => entry.re.test(recognitionCommand))) {
+		return {
+			kind: posture === "confirmed" ? "allow" : "ask",
+			reasonCode: "project-script-confirm",
+			ruleId: "project-script-confirm",
+			reasons: [
+				"Repository-authored code requires one-shot confirmation or an operator-approved safety command declaration.",
+				projectScriptPreview(recognitionCommand, callCwd),
+			],
+			policySource: "builtin-command-allowlist",
+			execRecognition: "unrecognized",
+		};
+	}
 	const chain = recognizeCommandChain(recognitionCommand, callCwd, workspaceRoot, policy);
 	if (chain !== null) {
 		const chainReasons = [`every step of the && chain is recognized: ${chain.ruleIds.join(", ")}`];
+		if (chain.requiresConfirmation) {
+			for (const segment of recognitionCommand.split("&&").map((part) => part.trim())) {
+				if (PROJECT_SCRIPT_COMMANDS.some((entry) => entry.re.test(segment)))
+					chainReasons.push(projectScriptPreview(segment, callCwd));
+			}
+		}
 		if (chain.requiresConfirmation && posture !== "confirmed") {
 			return {
 				kind: "ask",
 				ruleId: "bash-recognized-chain",
 				reasonCode: "bash-recognized-chain",
-				reasons: [...chainReasons, "project policy requires confirmation for one step"],
+				reasons: [...chainReasons, "repository code or project policy requires confirmation for one step"],
 				policySource: "builtin-command-allowlist",
 				execRecognition: "recognized",
 			};
@@ -697,6 +813,23 @@ function evaluateBashPolicy(
 	// the full string, so a destructive verb behind an operator was caught before
 	// this point.
 	if (hasSequencingOperators(command)) {
+		const scriptSegments = recognitionCommand
+			.split(/&&|\|\||[;|\n]/)
+			.map((part) => part.trim())
+			.filter((part) => PROJECT_SCRIPT_COMMANDS.some((entry) => entry.re.test(part)));
+		if (scriptSegments.length > 0 && posture !== "confirmed") {
+			return {
+				kind: "ask",
+				ruleId: "project-script-confirm",
+				reasonCode: "project-script-confirm",
+				reasons: [
+					"Repository scripts in compound commands require one-shot confirmation",
+					...scriptSegments.map((part) => projectScriptPreview(part, callCwd)),
+				],
+				policySource: "builtin-command-allowlist",
+				execRecognition: "unrecognized",
+			};
+		}
 		return {
 			kind: "allow",
 			ruleId: "bash-shell-operators",
@@ -913,6 +1046,11 @@ function recognizeCommandChain(
 			if (projectMatch.requireConfirmation) requiresConfirmation = true;
 			continue;
 		}
+		if (PROJECT_SCRIPT_COMMANDS.some((entry) => entry.re.test(rendered))) {
+			ruleIds.push("project-script-confirm");
+			requiresConfirmation = true;
+			continue;
+		}
 		const builtin = BUILTIN_ALLOWLIST.find((entry) => entry.re.test(rendered));
 		if (builtin === undefined) return null;
 		ruleIds.push(builtin.id);
@@ -966,10 +1104,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 +1135,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);
@@ -1004,9 +1150,9 @@ function damageControlScan(call: ClassifierCall): string {
  * declare. The catalog is an argv vector the operator authored, but the file
  * sits in the workspace, so the engine reads it fresh on every verify call and
  * treats the declared argv exactly like a bash command string: it is what the
- * damage-control rules and the zero-access read guard scan, and it is not in
- * the no-prompt set. An unreadable or invalid catalog resolves to null here and
- * fails closed in the tool itself.
+ * damage-control rules and the zero-access read guard scan. Recognition uses
+ * canonical command policy with argv boundaries preserved. An unreadable or
+ * invalid catalog resolves to null here and fails closed in the tool itself.
  */
 function resolveVerifyCatalogCheck(call: ClassifierCall, workspaceRoot: string): DeclaredCheck | null {
 	if (call.tool !== ToolNames.Verify) return null;
@@ -1057,3 +1203,34 @@ function packPayload(rules: ReadonlyArray<DamageControlRule>): Array<Record<stri
 		...(rule.ask !== undefined ? { ask: rule.ask } : {}),
 	}));
 }
+
+function invokesTrustMutation(command: string): boolean {
+	// Wrappers, package launchers, quoted argv and source-tree CLI invocations
+	// must not turn an operator-only grant into model authority.
+	const words = scanShellLike(command)
+		.filter((token) => !token.operator)
+		.map((token) => token.value);
+	return (
+		words.some((word, index) => word === "config" && words[index + 1] === "trust") ||
+		/\bconfig\s+trust\b/.test(inlineShellScript(command) ?? "")
+	);
+}
+
+function projectScriptPreview(command: string, cwd: string): string {
+	const match = /^npm\s+(?:run\s+)?([\w:-]+)/.exec(command);
+	if (match) {
+		try {
+			const manifest = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8")) as {
+				scripts?: Record<string, unknown>;
+			};
+			const name = match[1] ?? "test";
+			const scripts = [`pre${name}`, name, `post${name}`].flatMap((key) =>
+				typeof manifest.scripts?.[key] === "string" ? [`${key}: ${manifest.scripts[key]}`] : [],
+			);
+			return `package.json scripts (repository data): ${scripts.join("; ") || "no script resolved"}`;
+		} catch {
+			return "package.json script body could not be resolved; repository code will execute.";
+		}
+	}
+	return `Repository command: ${command}. Its test/build files and dependencies execute with the child process permissions.`;
+}

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

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import type { ActionClass } from "./action-classifier.js";
@@ -29,6 +29,7 @@ export interface ProjectCommandPolicy {
 }
 
 export interface LoadedProjectSafetyPolicy {
+	trustVerdict?: "trusted" | "untrusted" | "changed";
 	path: string | null;
 	hash: string | null;
 	valid: boolean;
@@ -80,7 +81,7 @@ function projectSafetyPolicyPath(cwd: string = process.cwd()): string | null {
 }
 
 export function loadProjectSafetyPolicy(cwd: string = process.cwd()): LoadedProjectSafetyPolicy {
-	const policyPath = projectSafetyPolicyPath(cwd);
+	let policyPath = projectSafetyPolicyPath(cwd);
 	if (policyPath === null) {
 		return {
 			path: null,
@@ -94,6 +95,10 @@ export function loadProjectSafetyPolicy(cwd: string = process.cwd()): LoadedProj
 	}
 	let raw: string;
 	try {
+		// Relative entries are interpreted against this source directory. Pin its
+		// canonical identity before reading; downstream trust and compilation use
+		// the captured path, not a symlink that may move after admission.
+		policyPath = realpathSync(policyPath);
 		raw = readFileSync(policyPath, "utf8");
 	} catch (err) {
 		return {

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