@iowarp/clio-coder 0.4.3 → 0.4.4

package/src/cli/verifiers.ts

@@ -6,8 +6,15 @@ import {
 	runVerifierAuthoringWorkflow,
 	type VerifierRevision,
 } from "../tools/verify/authoring.js";
-import { loadProjectVerifierCatalog, PROJECT_VERIFIER_CATALOG_RELATIVE_PATH } from "../tools/verify/catalog.js";
+import {
+	DECLARED_CHECK_KINDS,
+	type DeclaredCheckKind,
+	loadProjectVerifierCatalog,
+	PROJECT_VERIFIER_CATALOG_RELATIVE_PATH,
+} from "../tools/verify/catalog.js";
 import { verifyTool } from "../tools/verify/index.js";
+import { normalizeNumericTolerance } from "../tools/verify/numeric.js";
+import { recordPerfBaseline } from "../tools/verify/scripts.js";
 import { printError, printOk } from "./argv.js";
 import { runVerifiersInspect } from "./verifiers-inspect.js";
 
@@ -23,11 +30,22 @@ Usage:
   clio-coder verifiers edit <id> [--description <text>] [--command <json-argv>] [fields] [--yes]
   clio-coder verifiers rename <old> <new> [--yes]
   clio-coder verifiers remove <id> [--yes]
+  clio-coder verifiers baseline <id>
 
 Fields:
   --cwd <path>            repository-relative working directory (default .)
   --timeout-ms <number>   bounded timeout in milliseconds (default 120000)
   --tags <a,b>            comma-separated catalog tags
+  --kind <kind>           command (default), numeric-compare, or perf-budget
+  --reference <path>      numeric-compare: repository-relative reference JSON of string -> number | number[]
+  --tolerance <json>      numeric-compare: {"relative"?,"absolute"?,"ulp"?}, at least one;
+                          perf-budget with --baseline: {"relative"} headroom over the baseline
+  --budget-ms <number>    perf-budget: wall-time bound in milliseconds
+  --budget-relative <r>   perf-budget with --budget-ms: fractional headroom over the bound
+  --baseline <path>       perf-budget: repository-relative baseline JSON written by 'verifiers baseline <id>'
+
+baseline runs a perf-budget check once and records its wall time at the check's
+baseline path; a failing or timed-out command records nothing.
 
 Discovery and every preview are read-only. Mutating commands write only with
 --yes after printing the exact argv, cwd, timeout, tags, source provenance, and
@@ -48,6 +66,12 @@ const VALUE_OPTIONS = new Set([
 	"--exclude",
 	"--rename",
 	"--dry-run",
+	"--kind",
+	"--reference",
+	"--tolerance",
+	"--budget-ms",
+	"--budget-relative",
+	"--baseline",
 ]);
 
 interface ParsedAuthoringArgs {
@@ -124,6 +148,93 @@ function tags(value: string | undefined): string[] {
 				.filter((tag) => tag.length > 0);
 }
 
+type KindFields = Pick<Extract<VerifierRevision, { kind: "add" }>["check"], "kind" | "numeric" | "perf">;
+
+function parseJsonObject(value: string, option: string): Record<string, unknown> | Error {
+	try {
+		const parsed = JSON.parse(value) as unknown;
+		if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+			return new Error(`${option} must be a JSON object`);
+		}
+		return parsed as Record<string, unknown>;
+	} catch (error) {
+		return new Error(`${option} must be valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+
+/**
+ * The kind and its parameters from the option set. Returns `{}` when no kind
+ * option was given so a plain command check keeps the version-1 shape, and an
+ * Error when the options disagree with the kind the way the catalog parser
+ * would refuse them, so the operator reads one message here instead of a
+ * rejected preview.
+ */
+function kindFieldsFromArgs(parsed: ParsedAuthoringArgs): KindFields | Error {
+	const kindValue = oneValue(parsed, "--kind") ?? "command";
+	if (!(DECLARED_CHECK_KINDS as ReadonlyArray<string>).includes(kindValue)) {
+		return new Error(`--kind must be one of ${DECLARED_CHECK_KINDS.join(", ")}`);
+	}
+	const kind = kindValue as DeclaredCheckKind;
+	const reference = oneValue(parsed, "--reference");
+	const toleranceValue = oneValue(parsed, "--tolerance");
+	const budgetMs = oneValue(parsed, "--budget-ms");
+	const budgetRelative = oneValue(parsed, "--budget-relative");
+	const baseline = oneValue(parsed, "--baseline");
+	if (kind === "command") {
+		const stray = [
+			["--reference", reference],
+			["--tolerance", toleranceValue],
+			["--budget-ms", budgetMs],
+			["--budget-relative", budgetRelative],
+			["--baseline", baseline],
+		].filter(([, value]) => value !== undefined);
+		if (stray.length > 0)
+			return new Error(`${stray.map(([name]) => name).join(", ")} require --kind numeric-compare or perf-budget`);
+		return {};
+	}
+	if (kind === "numeric-compare") {
+		if (budgetMs !== undefined || budgetRelative !== undefined || baseline !== undefined) {
+			return new Error("--budget-ms, --budget-relative, and --baseline belong to --kind perf-budget");
+		}
+		if (reference === undefined) return new Error("--reference is required for --kind numeric-compare");
+		if (toleranceValue === undefined) return new Error("--tolerance is required for --kind numeric-compare");
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const tolerance = normalizeNumericTolerance(toleranceJson);
+		if (tolerance instanceof Error) return new Error(`--tolerance ${tolerance.message}`);
+		return { kind, numeric: { reference, tolerance } };
+	}
+	if (reference !== undefined) return new Error("--reference belongs to --kind numeric-compare");
+	if ((budgetMs === undefined) === (baseline === undefined)) {
+		return new Error("--kind perf-budget requires exactly one of --budget-ms or --baseline");
+	}
+	if (budgetMs !== undefined) {
+		if (toleranceValue !== undefined) return new Error("use --budget-relative for headroom over --budget-ms");
+		const wallTimeMs = Number(budgetMs);
+		if (!Number.isFinite(wallTimeMs) || wallTimeMs <= 0) return new Error("--budget-ms must be a positive number");
+		const budget: NonNullable<KindFields["perf"]>["budget"] = { wallTimeMs };
+		if (budgetRelative !== undefined) {
+			const relative = Number(budgetRelative);
+			if (!Number.isFinite(relative) || relative < 0) return new Error("--budget-relative must be a non-negative number");
+			budget.tolerance = { relative };
+		}
+		return { kind, perf: { budget } };
+	}
+	if (budgetRelative !== undefined)
+		return new Error("--budget-relative belongs with --budget-ms; use --tolerance with --baseline");
+	const perf: NonNullable<KindFields["perf"]> = { baseline: baseline as string };
+	if (toleranceValue !== undefined) {
+		const toleranceJson = parseJsonObject(toleranceValue, "--tolerance");
+		if (toleranceJson instanceof Error) return toleranceJson;
+		const relative = toleranceJson.relative;
+		if (typeof relative !== "number" || !Number.isFinite(relative) || relative < 0) {
+			return new Error('--tolerance for a baseline must be {"relative": <non-negative number>}');
+		}
+		perf.tolerance = { relative };
+	}
+	return { kind, perf };
+}
+
 function requiredValue(parsed: ParsedAuthoringArgs, option: string): string | Error {
 	const value = oneValue(parsed, option);
 	return value === undefined || value.length === 0 ? new Error(`${option} is required`) : value;
@@ -151,6 +262,8 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	if (command instanceof Error) return command;
 	const timeoutMs = parseTimeout(oneValue(parsed, "--timeout-ms"));
 	if (timeoutMs instanceof Error) return timeoutMs;
+	const kindFields = kindFieldsFromArgs(parsed);
+	if (kindFields instanceof Error) return kindFields;
 	return {
 		kind: "add",
 		check: {
@@ -160,6 +273,7 @@ function addRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 			cwd: oneValue(parsed, "--cwd") ?? ".",
 			timeoutMs,
 			tags: tags(oneValue(parsed, "--tags")),
+			...kindFields,
 		},
 	};
 }
@@ -186,6 +300,13 @@ function editRevision(parsed: ParsedAuthoringArgs): VerifierRevision | Error {
 	}
 	const tagValue = oneValue(parsed, "--tags");
 	if (tagValue !== undefined) changes.tags = tags(tagValue);
+	if (oneValue(parsed, "--kind") !== undefined) {
+		const kindFields = kindFieldsFromArgs(parsed);
+		if (kindFields instanceof Error) return kindFields;
+		changes.kind = kindFields.kind ?? "command";
+		if (kindFields.numeric !== undefined) changes.numeric = kindFields.numeric;
+		if (kindFields.perf !== undefined) changes.perf = kindFields.perf;
+	}
 	if (Object.keys(changes).length === 0) return new Error("edit requires at least one changed field");
 	return { kind: "edit", id, changes };
 }
@@ -260,6 +381,30 @@ async function executeWorkflow(
 	return code;
 }
 
+async function baselineCommand(id: string | undefined): Promise<number> {
+	if (id === undefined) {
+		printError("baseline requires a check ID");
+		return 2;
+	}
+	const loaded = loadProjectVerifierCatalog(process.cwd());
+	if (!loaded.ok) {
+		printError(`production catalog parser rejected ${loaded.reason}`);
+		return 1;
+	}
+	const check = loaded.source?.checks.find((candidate) => candidate.id === id);
+	if (check === undefined) {
+		printError(`no catalog check '${id}' in ${PROJECT_VERIFIER_CATALOG_RELATIVE_PATH}`);
+		return 1;
+	}
+	const recorded = await recordPerfBaseline(check);
+	if (!recorded.ok) {
+		printError(`baseline '${id}' not recorded: ${recorded.message}`);
+		return 1;
+	}
+	printOk(`recorded baseline for '${id}': ${Math.round(recorded.wallTimeMs)}ms at ${recorded.path}`);
+	return 0;
+}
+
 async function discoverCommand(): Promise<number> {
 	const discovery = discoverVerifierAuthoring();
 	if (!discovery.ok) {
@@ -304,6 +449,7 @@ export async function runVerifiersCommand(argv: string[]): Promise<number> {
 	const command = parsed.positional[0];
 	if (command === "discover") return discoverCommand();
 	if (command === "validate") return validateCommand();
+	if (command === "baseline") return baselineCommand(parsed.positional[1]);
 	if (command === "dry-run") {
 		const id = parsed.positional[1];
 		if (id === undefined) {

package/src/cli/wiki-generate.ts

@@ -336,6 +336,7 @@ async function runPagePhase(
 			codewiki: input.codewiki,
 			page,
 			siblings: plan.pages,
+			...(input.decisions ? { decisions: input.decisions } : {}),
 			outputDir: input.outputDir,
 			seeded,
 		}),

package/src/core/commit-attribution.ts

@@ -15,6 +15,21 @@ export const CLIO_COMMIT_TRAILERS = {
 	coAuthored: `Co-authored-by: ${CLIO_COMMIT_IDENTITY}`,
 } as const;
 
+export const CLIO_DECISION_TRAILER_KEY = "Clio-Decision";
+
+/** Most `Clio-Decision:` trailers one commit carries; matches the receipt cap. */
+export const CLIO_DECISION_TRAILER_CAP = 32;
+
+/**
+ * A decision ref is `<interviewId>/<key>`: an `ask_user` interview id or an
+ * `agent:<uuid>` decision-set id, then the decision key. Operator keys are
+ * snake_case and agent keys are kebab-case, the same shape `isDecisionRecord`
+ * admits. Only refs of this shape become trailers, so a malformed value can
+ * never inject a second trailer line or a stray control character into a
+ * commit message.
+ */
+export const DECISION_REF_PATTERN = /^[A-Za-z0-9][A-Za-z0-9:._-]{0,127}\/[a-z0-9]+(?:[_-][a-z0-9]+)*$/u;
+
 export interface CommitReceiptEvidence {
 	version: 20;
 	algorithm: "sha256";
@@ -37,6 +52,12 @@ export interface CommitAttributionEvidence {
 	materiallyAuthored?: boolean;
 	/** Optional sealed receipt for a directly relevant fact above. */
 	receipt?: CommitReceiptEvidence;
+	/**
+	 * Decision refs (`<interviewId>/<key>`) the committed work was done under,
+	 * read from the session decision board or a sealed receipt's
+	 * `decisionRefs`. Each becomes one `Clio-Decision:` trailer.
+	 */
+	decisions?: ReadonlyArray<string>;
 }
 
 const TRAILER_LINE = /^([A-Za-z0-9][A-Za-z0-9-]*):[ \t]+(.+)$/u;
@@ -58,7 +79,25 @@ const KNOWN_CLIO_TRAILERS = new Set(
 );
 
 function isClioTrailer(key: string): boolean {
-	return KNOWN_CLIO_TRAILERS.has(key) || key.startsWith("clio-evidence:receipt-v20/sha256:");
+	return (
+		KNOWN_CLIO_TRAILERS.has(key) ||
+		key.startsWith("clio-evidence:receipt-v20/sha256:") ||
+		key.startsWith(`${CLIO_DECISION_TRAILER_KEY.toLowerCase()}:`)
+	);
+}
+
+/** Well-formed decision refs from the evidence, deduplicated, sorted, and capped. */
+export function decisionTrailerRefs(decisions: ReadonlyArray<string> | undefined): string[] {
+	if (decisions === undefined) return [];
+	const refs = new Set<string>();
+	for (const ref of decisions) {
+		if (typeof ref === "string" && DECISION_REF_PATTERN.test(ref)) refs.add(ref);
+	}
+	return [...refs].sort().slice(0, CLIO_DECISION_TRAILER_CAP);
+}
+
+function decisionTrailer(ref: string): string {
+	return `${CLIO_DECISION_TRAILER_KEY}: ${ref}`;
 }
 
 /**
@@ -138,6 +177,7 @@ export function attributeCommitMessage(
 	if (evidence.materiallyAuthored === true) desired.push(CLIO_COMMIT_TRAILERS.coAuthored);
 	const receipt = receiptTrailer(evidence.receipt);
 	if (receipt !== null) desired.push(receipt);
+	for (const ref of decisionTrailerRefs(evidence.decisions)) desired.push(decisionTrailer(ref));
 
 	const existing = new Set(
 		(blockStart === null ? [] : retained.slice(blockStart))

package/src/core/git-commit-attribution.ts

@@ -12,17 +12,24 @@ import {
 } from "node:fs";
 import { join, resolve } from "node:path";
 import { AI_AGENT_NAME } from "./agent-environment.js";
-import { CLIO_COMMIT_TRAILERS, type CommitAttributionEvidence } from "./commit-attribution.js";
+import {
+	CLIO_COMMIT_TRAILERS,
+	CLIO_DECISION_TRAILER_KEY,
+	type CommitAttributionEvidence,
+	decisionTrailerRefs,
+} from "./commit-attribution.js";
 import { clioStateDir } from "./xdg.js";
 
 /** Effective `attribution.gitCommits` for child-process seams. Internal state, not an operator override. */
 export const CLIO_GIT_COMMITS_ENABLED_ENV = "CLIO_CODER_GIT_COMMITS_ENABLED";
 const ASSISTED_ENV = "CLIO_CODER_COMMIT_ASSISTED";
 const AUTHORED_ENV = "CLIO_CODER_COMMIT_AUTHORED";
+/** Space-separated decision refs the spawn was made under; each becomes one `Clio-Decision:` trailer. */
+const DECISIONS_ENV = "CLIO_CODER_COMMIT_DECISIONS";
 /** Present iff this environment carries Clio's command-scope core.hooksPath pair; holds the count below it. */
 const CONFIG_BASE_COUNT_ENV = "CLIO_CODER_GIT_CONFIG_BASE_COUNT";
 const DEFAULT_HOOKS_EQUIVALENT_ENV = "CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT";
-const MANAGED_HOOK_VERSION = 2;
+const MANAGED_HOOK_VERSION = 3;
 const DIAGNOSTIC_MAX_CHARS = 300;
 const COUNT = /^(?:0|[1-9][0-9]*)$/u;
 const reportedDiagnostics = new Set<string>();
@@ -45,7 +52,33 @@ type RepositoryProbe =
 const probeCache = new Map<string, { at: number; probe: RepositoryProbe }>();
 let installedHooksDirectory: string | null = null;
 
-const PER_SPAWN_ENV_NAMES = [ASSISTED_ENV, AUTHORED_ENV, CONFIG_BASE_COUNT_ENV, DEFAULT_HOOKS_EQUIVALENT_ENV] as const;
+const PER_SPAWN_ENV_NAMES = [
+	ASSISTED_ENV,
+	AUTHORED_ENV,
+	DECISIONS_ENV,
+	CONFIG_BASE_COUNT_ENV,
+	DEFAULT_HOOKS_EQUIVALENT_ENV,
+] as const;
+
+let decisionRefsProvider: (() => ReadonlyArray<string>) | null = null;
+
+/**
+ * Register the live decision board's active refs for the session seam. Each
+ * Clio-spawned commit is then stamped with the decisions it was made under,
+ * the same way `ASSISTED_ENV` carries assistance. Explicit `evidence.decisions`
+ * on a spawn still wins over the provider.
+ */
+export function setCommitDecisionRefsProvider(provider: (() => ReadonlyArray<string>) | null): void {
+	decisionRefsProvider = provider;
+}
+
+function providedDecisionRefs(): ReadonlyArray<string> {
+	try {
+		return decisionRefsProvider?.() ?? [];
+	} catch {
+		return [];
+	}
+}
 
 export interface ManagedCommitAttributionOptions {
 	cwd?: string;
@@ -242,6 +275,14 @@ if [ "$${ASSISTED_ENV}" = '1' ] || [ "$${AUTHORED_ENV}" = '1' ]; then
   append_trailer '${CLIO_COMMIT_TRAILERS.assisted}'
 fi
 if [ "$${AUTHORED_ENV}" = '1' ]; then append_trailer '${CLIO_COMMIT_TRAILERS.coAuthored}'; fi
+# Decision refs are validated again here: only <id>/<key> shapes become
+# trailers, so a stray value cannot inject a second line into the message.
+for decision_ref in $${DECISIONS_ENV}; do
+  case "$decision_ref" in
+    *[!A-Za-z0-9:._/-]* | */*/* | /* | */ | *-*-) continue ;;
+    */*) append_trailer "${CLIO_DECISION_TRAILER_KEY}: $decision_ref" ;;
+  esac
+done
 exit 0
 `;
 
@@ -344,6 +385,8 @@ export function withManagedGitCommitAttributionEnvironment(
 	const evidence = options.evidence ?? { materiallyAssisted: true, materiallyAuthored: true };
 	env[ASSISTED_ENV] = evidence.materiallyAssisted === true ? "1" : "0";
 	env[AUTHORED_ENV] = evidence.materiallyAuthored === true ? "1" : "0";
+	const decisions = decisionTrailerRefs(evidence.decisions ?? providedDecisionRefs());
+	if (decisions.length > 0) env[DECISIONS_ENV] = decisions.join(" ");
 
 	const countRaw = env.GIT_CONFIG_COUNT;
 	const count = countRaw === undefined ? 0 : COUNT.test(countRaw) ? Number(countRaw) : Number.NaN;

package/src/core/run-overrides.ts

@@ -18,8 +18,6 @@ export const RUN_OVERRIDES_ENV = "CLIO_CODER_RUN_OVERRIDES";
 export interface RunOverrides {
 	/** One-run context-window override for supported local runtimes. */
 	maxContextTokens?: number;
-	/** One-run KV-cache quantization mode; the consuming runtime validates it. */
-	kvCacheMode?: string;
 	/**
 	 * One-run sampling parameter overrides. Kept as a loose numeric record
 	 * here (undefined fields are dropped at serialization);
@@ -45,9 +43,6 @@ export function runOverrides(env: NodeJS.ProcessEnv = process.env): RunOverrides
 	if (typeof maxContextTokens === "number" && Number.isInteger(maxContextTokens) && maxContextTokens > 0) {
 		out.maxContextTokens = maxContextTokens;
 	}
-	if (typeof record.kvCacheMode === "string" && record.kvCacheMode.length > 0) {
-		out.kvCacheMode = record.kvCacheMode;
-	}
 	const sampling = record.sampling;
 	if (sampling !== null && typeof sampling === "object" && !Array.isArray(sampling)) {
 		const numeric: Record<string, number> = {};

package/src/core/skill-activation.ts

@@ -189,6 +189,9 @@ export function evaluateSkillToolSurface(
 		.filter(([, declared]) => declared.disallowedTools?.includes(tool) === true)
 		.map(([name]) => name);
 	if (disallowedBy.length > 0) return { skills, mergedAllowedTools: null, disallowedBy, carriedSurface };
+	// A finish receipt records a limitation without performing another action.
+	// Keep it available under allow-narrowing, while honoring explicit denials.
+	if (tool === "limitation") return null;
 	const allowLists = entries.map(([, declared]) => declared.allowedTools);
 	if (allowLists.some((list) => list === undefined || list.length === 0)) return null;
 	const merged = [...new Set(allowLists.flatMap((list) => [...(list ?? [])]))];

package/src/core/tool-names.ts

@@ -4,10 +4,10 @@
  *
  * The surface is organized in seven planes; each plane is one policy unit
  * (action class, size posture, details schema, concurrency rule):
- *   OBSERVE      read, grep, find, ls, code_nav, context, credential_present
+ *   OBSERVE      evidence, read, grep, find, ls, code_nav, context, credential_present
  *   MUTATE       write, edit
  *   EXECUTE      bash, git, verify
- *   ORCHESTRATE  dispatch, monitor, steer, tasks, panes
+ *   ORCHESTRATE  dispatch, monitor, steer, tasks, ledger, panes, limitation, decide
  *   RETRIEVE     web_fetch
  *   INTERACT     ask_user
  *   ARTIFACT     artifact
@@ -16,6 +16,7 @@
 export const ToolNames = {
 	// OBSERVE
 	Read: "read",
+	Evidence: "evidence",
 	Grep: "grep",
 	Find: "find",
 	Ls: "ls",
@@ -36,6 +37,8 @@ export const ToolNames = {
 	Tasks: "tasks",
 	Ledger: "ledger",
 	Panes: "panes",
+	Limitation: "limitation",
+	Decide: "decide",
 	// RETRIEVE
 	WebFetch: "web_fetch",
 	// INTERACT

package/src/domains/agents/builtins/architect.md

@@ -4,7 +4,7 @@ name: Architect
 description: Designs a change across boundaries and slices it into a sprint. Covers contracts, migrations, and validation gates, and turns an existing plan into a dependency-ordered sprint through its bound cut-it skill.
 tools:
   required: [artifact, context]
-  optional: [read, grep, find, ls, code_nav, git, ledger]
+  optional: [read, grep, find, ls, code_nav, git, ledger, limitation]
 skills: [cut-it]
 audience: base
 category: plan

package/src/domains/agents/builtins/coder.md

@@ -4,7 +4,7 @@ name: Coder
 description: Implements bounded code changes, repairs, and refactors. Behavior-preserving by default.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
-  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
+  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger, limitation]
 skills: [fix-issue, ship]
 audience: base
 category: implement

package/src/domains/agents/builtins/documenter.md

@@ -4,7 +4,7 @@ name: Documenter
 description: Updates developer docs, examples, and operational runbooks.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, git, verify, code_nav, context, ledger]
+  optional: [grep, find, ls, git, verify, code_nav, context, ledger, limitation]
 skills: []
 audience: base
 category: implement

package/src/domains/agents/builtins/git-master.md

@@ -4,7 +4,7 @@ name: Git Master
 description: Runs bounded git operations end to end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
 tools:
   required: [read, {anyOf: [write, edit]}, context, git]
-  optional: [bash, grep, find, ls, code_nav, ledger]
+  optional: [bash, grep, find, ls, code_nav, ledger, limitation]
 skills: [fix-issue, ship, worktree-create, worktree-merge]
 audience: base
 category: implement

package/src/domains/agents/builtins/provenance.md

@@ -3,8 +3,8 @@ version: 1
 name: Provenance
 description: Reads receipts, diffs, and telemetry for evidence. Shadow agent for source-backed handoffs.
 tools:
-  required: [read]
-  optional: [grep, find, ls, git, ledger]
+  required: [evidence]
+  optional: [read, grep, find, ls, git, ledger]
 skills: []
 audience: shadow
 category: operations
@@ -20,11 +20,11 @@ tags: [receipts, evidence, telemetry]
 
 You are Provenance, a shadow evidence agent for Clio orchestration.
 Start by restating the receipt, run id, diff, telemetry path, or evidence question.
-Read only the artifacts needed to answer provenance questions: receipts, logs, diffs, session entries, manifests, or summaries.
-Connect claims to concrete evidence paths, hashes, commands, timestamps, or run ids.
-Receipts carry an `outcome` (succeeded, failed, timed_out, stalled, canceled, denied_by_policy, spawn_failed) and a `lineage` block (parentRunId, rootRunId, attempt, depth); use lineage to walk retry chains and nested fleet steps back to the operator-initiated root run.
-Receipts also carry an `identity` block with host, user, and any Slurm/PBS/LSF allocation (scheduler, jobId, jobName, cluster); cite it when anchoring results to an HPC job.
-Do not infer success from file existence; cite the receipt, command output, or validation record that proves it.
+Start with `evidence(mode="list")` to find bundles, `evidence(mode="inspect", id="...")` for a named bundle, or `evidence(mode="run", runId="...")` for a run.
+Cite the tool's canonical trust tier, all relevant trust axes, gate decisions, and finding ids when answering evidence questions.
+Keep missing or historical trust status explicit. Do not infer success from file existence or turn unverified claims into confirmed facts.
+Connect each confirmed fact to its evidence id, run id, finding id, or gate decision.
+Fall back to raw artifact reads only when the tool reports the artifact absent. Report those reads as unverified leads, and never use raw receipts to override an integrity failure or canonical trust status.
 Do not edit files, run commands, write plans, write reviews, or approve memory.
 Keep the result compact enough for the main agent to synthesize directly.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"confirmedFacts":["..."],"missingEvidence":["..."],"nextInspections":["..."]}`.

package/src/domains/agents/builtins/tester.md

@@ -4,7 +4,7 @@ name: Tester
 description: Adds focused deterministic regression and coverage tests.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, git, verify, code_nav, ledger]
+  optional: [grep, find, ls, git, verify, code_nav, ledger, limitation]
 skills: []
 audience: base
 category: quality

package/src/domains/agents/builtins/verifier.md

@@ -4,7 +4,7 @@ name: Verifier
 description: Runs test, lint, build, review, and release gates. Reports each gate independently.
 tools:
   required: [verify]
-  optional: [read, grep, find, ls, git, code_nav, ledger]
+  optional: [evidence, read, grep, find, ls, git, code_nav, ledger]
 skills: []
 audience: base
 category: quality
@@ -26,7 +26,7 @@ Run only the checks required for the requested confidence level.
 Prefer typed validation tools over arbitrary shell execution.
 Call `verify()` before choosing an executable check. It lists package scripts and strict project entries from `.clio-coder/verifiers.yaml` through the same metadata shape.
 Run a project entry only by its listed ID. Do not add args, cwd, timeout, environment, or shell composition; the catalog's exact argv, cwd, and timeout are authoritative.
-Treat scientific validation contracts and generated handbook expectations as advisory evidence requirements. They do not become executable until the project declares a corresponding verifier-catalog entry.
+A parsed validation contract's `artifacts` and `validators` are requirements to satisfy, and they are executable only through `.clio-coder/verifiers.yaml` entries.
 Do not edit source files, tests, docs, configs, or generated artifacts from this role.
 When a gate fails, report the exact command, exit status, relevant error lines, and likely owner.
 Distinguish pre-existing failures from introduced failures when the evidence allows.

package/src/domains/agents/builtins/wiki-writer.md

@@ -4,7 +4,7 @@ name: Wiki Writer
 description: Plans a repository wiki or writes one wiki page. Works against a supplied plan.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, code_nav, context, ledger]
+  optional: [grep, find, ls, code_nav, context, ledger, limitation]
 skills: []
 audience: base
 category: implement
@@ -37,5 +37,6 @@ over a batch of parallel guesses. Never read `.env` files or other secret-bearin
 Write the file as soon as you can ground it, then improve it in place. A written page is worth
 more than a researched one, and your budget is sized for a single subject, not a repository tour.
 
-The file you wrote is your result. When it is on disk, stop and say in one line what you wrote
-and what you could not ground. There is no report to file and no JSON to emit.
+The file you wrote is your result. When it is on disk, call `limitation` with the scope and reason
+for anything you could not ground, then stop and say in one line what you wrote. There is no
+report to file and no JSON to emit.

package/src/domains/context/extension.ts

@@ -2,8 +2,13 @@ import { existsSync } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
 import { BusChannels, type ContextActivityPayload } from "../../core/bus-events.js";
 import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
-import { clioDataDir } from "../../core/xdg.js";
+import { clioDataDir, clioStateDir } from "../../core/xdg.js";
 import { loadMemoryRecordsSync } from "../memory/index.js";
+import { describeValidationContract, loadValidationContract } from "../safety/index.js";
+import { readSessionEntriesForId } from "../session/archive-readers.js";
+import type { SessionContract } from "../session/contract.js";
+import { foldDecisionBoard } from "../session/decision-board.js";
+import { filterEntriesToActivePath } from "../session/tree/active-path.js";
 import { detectProjectType, type ProjectType } from "../session/workspace/project-type.js";
 import { adoptionSourcesChanged } from "./adoption.js";
 import { runBootstrap } from "./bootstrap.js";
@@ -148,6 +153,12 @@ function collectStartupHints(cwd: string, options: ContextBundleOptions = {}): s
 	for (const issue of clio.errors) {
 		hints.push(`clio-coder: malformed ${issue.path} ignored: ${issue.error}`);
 	}
+	// An invalid validation contract leaves rigor at normal; say so once here
+	// rather than letting the finish gate quietly behave as if no contract existed.
+	const contract = loadValidationContract(cwd);
+	if (!contract.ok) {
+		hints.push(`clio-coder: validation contract ignored, rigor stays normal: ${describeValidationContract(contract)}`);
+	}
 	const state = readClioState(cwd);
 	if (!state) return hints;
 	if (state.contextSources !== undefined && adoptionSourcesChanged(state.contextSources, { cwd })) {
@@ -290,9 +301,11 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				const result = await runContextRefresh(
-					input ? { ...input, onProgress: emitProgress } : { onProgress: emitProgress },
-				);
+				const result = await runContextRefresh({
+					...input,
+					...(input?.wiki ? { decisions: input.decisions ?? (await currentDecisions(_context)) } : {}),
+					onProgress: emitProgress,
+				});
 				const cwd = input?.cwd ?? process.cwd();
 				contextState.invalidate(cwd);
 				if (cwd === lastCwd) startupHints = collectStartupHints(cwd, options);
@@ -313,9 +326,11 @@ export function createContextBundle(
 				input?.onProgress?.(event);
 			};
 			try {
-				return await runWikiGenerate(
-					input ? { ...input, onProgress: emitProgress } : { model: "configured-clio-target", onProgress: emitProgress },
-				);
+				return await runWikiGenerate({
+					...(input ?? { model: "configured-clio-target" }),
+					decisions: input?.decisions ?? (await currentDecisions(_context)),
+					onProgress: emitProgress,
+				});
 			} catch (err) {
 				emitProgress({
 					phase: "done",
@@ -353,3 +368,12 @@ export function createContextBundle(
 
 	return { extension, contract };
 }
+
+async function currentDecisions(context: DomainContext) {
+	const session = context.getContract<SessionContract>("session");
+	const current = session?.current();
+	if (!session || !current) return [];
+	session.flushAppends?.();
+	const read = await readSessionEntriesForId(clioStateDir(), current.id);
+	return foldDecisionBoard(filterEntriesToActivePath(read.entries, session.tree(current.id).leafId ?? undefined));
+}

package/src/domains/context/refresh.ts

@@ -1,5 +1,6 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { DecisionLedgerEntry } from "../session/entries.js";
 import { detectProjectType } from "../session/workspace/project-type.js";
 import { type BootstrapIo, type BootstrapProgressSink, codewikiSections } from "./bootstrap.js";
 import { serializeClioMd, tryReadClioMd } from "./clio-md.js";
@@ -18,6 +19,7 @@ import { wikiCompleteness, wikiStaleness } from "./wiki/staleness.js";
  */
 
 export interface RunContextRefreshInput {
+	decisions?: ReadonlyArray<DecisionLedgerEntry>;
 	cwd?: string;
 	io?: BootstrapIo;
 	now?: () => Date;
@@ -146,6 +148,7 @@ export async function runContextRefresh(input: RunContextRefreshInput = {}): Pro
 		wikiResult = await runWikiGenerate({
 			cwd,
 			mode: "update",
+			...(input.decisions ? { decisions: input.decisions } : {}),
 			model: input.wikiModel ?? "unresolved-documenter-target",
 			...(input.wikiGenerate ? { generate: input.wikiGenerate } : {}),
 			...(input.onProgress ? { onProgress: input.onProgress } : {}),