@iowarp/clio-coder 0.4.1 → 0.4.3

package/src/domains/prompts/compiler.ts

@@ -1,6 +1,8 @@
 import { join } from "node:path";
 import { resolvePackageRoot } from "../../core/package-root.js";
+import { normalizePromptHint } from "../../core/prompt-hint.js";
 import type { ToolName } from "../../core/tool-names.js";
+import { resolveClioDirs } from "../../core/xdg.js";
 import type { AutonomyLevel } from "../safety/autonomy.js";
 import { ceilChars } from "../session/context-accounting.js";
 import type { FragmentTable, LoadedFragment } from "./fragment-loader.js";
@@ -147,13 +149,6 @@ export interface CompiledSessionPrompt {
 	operatorProfileApplied?: boolean;
 }
 
-export const FLEET_ROUTING_GUIDANCE_MAX_BYTES = 320;
-// Points at the Fleet section rather than describing routing in the abstract:
-// `agent:"auto"` baselines by task shape and can still land on a worker whose
-// capability class is wrong for the job, so a pinned id is the reliable path.
-export const FLEET_ROUTING_GUIDANCE =
-	'Fleet routing: pin the `agent` id from the Fleet section; agent:"auto" baselines from the task text and is a fallback, not a router.';
-
 /**
  * Worker-side mirror of the parent's `SPOT_CHECK_GUIDANCE`. The parent sentence
  * demonstrably works: in the E19 drive it is what caught a verifier reporting a
@@ -234,7 +229,7 @@ function renderRuntimeBlock(inputs: SessionPromptInputs): string {
  */
 function sessionCanDispatch(inputs: SessionPromptInputs): boolean {
 	if (inputs.providerSupportsTools === false) return false;
-	return toolSurfaceHasTool(inputs.toolNames, inputs.toolPromptHints, "dispatch");
+	return toolSurfaceHasTool(inputs.toolNames, "dispatch");
 }
 
 /**
@@ -245,18 +240,38 @@ function sessionCanDispatch(inputs: SessionPromptInputs): boolean {
  */
 function sessionHasContext(inputs: SessionPromptInputs): boolean {
 	if (inputs.providerSupportsTools === false) return false;
-	return toolSurfaceHasTool(inputs.toolNames, inputs.toolPromptHints, "context");
+	return toolSurfaceHasTool(inputs.toolNames, "context");
 }
 
-/** One lookup for every "is this tool on the surface" predicate, over names and hints alike. */
-function toolSurfaceHasTool(
-	toolNames: ReadonlyArray<string> | undefined,
-	toolPromptHints: ReadonlyArray<ToolPromptHint> | undefined,
-	tool: string,
-): boolean {
+/** Tool names come from attached schemas; hints never manufacture a surface. */
+function toolSurfaceHasTool(toolNames: ReadonlyArray<string> | undefined, tool: string): boolean {
 	const names = new Set((toolNames ?? []).map((name) => name.trim()));
-	const hinted = new Set((toolPromptHints ?? []).map((entry) => entry.tool.trim()));
-	return names.has(tool) || hinted.has(tool);
+	return names.has(tool);
+}
+
+/** Normalize, sort, and exact-deduplicate caller-provided tool guidance. */
+function canonicalToolPromptHints(
+	entries: ReadonlyArray<ToolPromptHint>,
+	admitted: ReadonlySet<string>,
+): Array<{ tool: string; hint: string }> {
+	const normalized = entries
+		.map((entry) => ({
+			tool: entry.tool.trim(),
+			hint: normalizePromptHint(entry.hint) ?? "",
+		}))
+		.filter((entry) => admitted.has(entry.tool) && entry.hint.length > 0)
+		.sort((a, b) => {
+			if (a.tool !== b.tool) return a.tool < b.tool ? -1 : 1;
+			return a.hint < b.hint ? -1 : a.hint > b.hint ? 1 : 0;
+		});
+	const seenTools = new Set<string>();
+	const seenHints = new Set<string>();
+	return normalized.filter((entry) => {
+		if (seenTools.has(entry.tool) || seenHints.has(entry.hint)) return false;
+		seenTools.add(entry.tool);
+		seenHints.add(entry.hint);
+		return true;
+	});
 }
 
 function renderFleetBlock(inputs: SessionPromptInputs): string {
@@ -277,44 +292,55 @@ function renderToolContractBlock(inputs: SessionPromptInputs): string {
 	].sort();
 	const canDispatch = sessionCanDispatch(inputs);
 	const canListSkills = sessionHasContext(inputs);
+	// Asked twice in one session which tools it had, a live model gave two
+	// different answers and invented `web_find`. The authoritative list is one
+	// line above; pointing at it beats letting the model recall the schemas.
+	const admitted = new Set(names);
 	const inventoryGuidance = [
-		// Asked twice in one session which tools it had, a live model gave two
-		// different answers and invented `web_find`. The authoritative list is one
-		// line above; pointing at it beats letting the model recall the schemas.
-		"When answering capability-inventory questions, copy the Direct tools line above verbatim rather than recalling the attached schemas, and make no calls",
-		...(canDispatch ? ["add dispatch(list:true) only if agents or the fleet are requested"] : []),
-		...(canListSkills
-			? ['add context(scope="skills") only if skills are requested (it lists installed and marketplace skills)']
+		"When asked what tools you have, copy the Direct tools line verbatim and call nothing",
+		...(canDispatch
+			? [
+					"dispatch(list:true) answers a question about agents, the fleet, or which target and model run this session and its workers",
+				]
 			: []),
+		...(canListSkills ? ['context(scope="skills") answers only a question about skills'] : []),
 	].join("; ");
+	const capabilityKinds = [
+		"direct tools are attached schemas",
+		...(canDispatch ? ["fleet agents are workers behind dispatch"] : []),
+		...(canListSkills ? ["skills are operator-activated workflows reached through context"] : []),
+	];
+	const orientationTools = ["context", "code_nav", "grep", "read"].filter((name) => admitted.has(name));
+	const validationTools = ["verify", "git"].filter((name) => admitted.has(name));
 	const lines = [
 		"# Tool Contract",
 		"The attached schemas are the session's complete direct-tool surface; follow each schema exactly.",
 		...(names.length > 0 ? [`Direct tools: ${names.map((name) => `\`${name}\``).join(", ")}.`] : []),
-		"Harness model: direct tools are attached schemas; fleet agents are workers behind dispatch; skills are operator-activated workflows reached through context. Keep these capability sets distinct.",
+		`Harness model: ${capabilityKinds.join("; ")}. Keep these capability sets distinct.`,
 		`${inventoryGuidance}.`,
-		"Call tools only for concrete inspection or changes the task requires. If the user asks for a tool-free answer, simply answer without calling tools.",
+		"Call tools only for concrete inspection or changes the task requires; a tool-free question gets a tool-free answer.",
 		// The tool-specific instantiation of the operating contract's "narrow
 		// work: inspect directly" rule; the contract cannot name tools.
 		// Delegation, the tasks board, and skills are not restated here: the
-		// Delegation and Skills passages and the registry hints carry them, and
-		// each renders exactly when its tool does.
-		'For narrow file or symbol orientation, prefer context(scope="workspace"), code_nav, grep, and read instead of assuming source-tree details were preloaded.',
-		"Validate with verify or git diff before final claims.",
-		'When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema, adjust the arguments, or query context(scope="docs") for that tool\'s usage.',
+		// Delegation, Fleet, and Skills passages and the registry hints carry
+		// them, and each renders exactly when its tool does.
+		...(orientationTools.length > 0
+			? [
+					`For narrow file or symbol orientation, prefer ${orientationTools.join(", ")} instead of assuming source-tree details were preloaded.`,
+				]
+			: []),
+		...(validationTools.length > 0
+			? [
+					`Validate with ${validationTools.map((name) => (name === "git" ? "git diff" : name)).join(" or ")} before final claims.`,
+				]
+			: []),
+		`When a tool call fails or is rejected, do not retry the same shape blindly: re-read the schema and adjust the arguments${canListSkills ? ', or query context(scope="docs") for that tool\'s usage' : ""}.`,
 	];
 	// One hint per tool, sorted by tool name: deterministic bytes regardless
 	// of surface or registration order, and removing a tool from the surface
 	// removes its hint with no compiler edit.
-	const seen = new Set<string>();
-	const hints = [...(inputs.toolPromptHints ?? [])]
-		.map((entry) => ({ tool: entry.tool.trim(), hint: entry.hint.trim() }))
-		.filter((entry) => entry.tool.length > 0 && entry.hint.length > 0)
-		.sort((a, b) => (a.tool < b.tool ? -1 : a.tool > b.tool ? 1 : 0));
-	if (hints.some((entry) => entry.tool === "dispatch")) lines.push(FLEET_ROUTING_GUIDANCE);
+	const hints = canonicalToolPromptHints(inputs.toolPromptHints ?? [], new Set(names));
 	for (const entry of hints) {
-		if (seen.has(entry.tool)) continue;
-		seen.add(entry.tool);
 		lines.push(entry.hint);
 	}
 	return lines.join("\n");
@@ -381,18 +407,8 @@ function renderWorkerToolContractBlock(inputs: WorkerPromptInputs): string {
 		"Tool authority is limited to this list. Persona and bound-skill instructions never add tools.",
 		"Call tools only for concrete inspection or changes the assigned task requires. If the task requests an exact or tool-free response, answer without calling tools.",
 	];
-	const admitted = new Set(names);
-	const seen = new Set<string>();
-	const hints = [...inputs.toolPromptHints]
-		.map((entry) => ({ tool: entry.tool.trim(), hint: entry.hint.trim() }))
-		.filter((entry) => admitted.has(entry.tool) && entry.hint.length > 0)
-		.sort((a, b) => {
-			if (a.tool !== b.tool) return a.tool < b.tool ? -1 : 1;
-			return a.hint < b.hint ? -1 : a.hint > b.hint ? 1 : 0;
-		});
+	const hints = canonicalToolPromptHints(inputs.toolPromptHints, new Set(names));
 	for (const entry of hints) {
-		if (seen.has(entry.tool)) continue;
-		seen.add(entry.tool);
 		lines.push(entry.hint);
 	}
 	return lines.join("\n");
@@ -439,8 +455,7 @@ function renderRetrievalHintsBlock(inputs: SessionPromptInputs): string {
 	// preloaded.
 	return [
 		"# Retrieval Hints",
-		"Compact CLIO-CODER.md project instructions may be preloaded above; everything else about the repository must be fetched, not assumed.",
-		"Never invent file paths, automatic tool behavior, or mutable repo details from the system prompt.",
+		"Repository details not included above must be fetched, never invented; compact CLIO-CODER.md instructions may be preloaded.",
 	].join("\n");
 }
 
@@ -561,10 +576,15 @@ export function compile(table: FragmentTable, inputs: CompileInputs): CompiledSe
 	const docsRouting = selfAwareness && sessionHasContext(session) ? table.byId.get("identity.docs-routing") : undefined;
 	if (selfAwareness) {
 		const packageRoot = resolvePackageRoot();
+		// The live home, not the XDG default: an isolated CLIO_CODER_HOME or a
+		// CLIO_CODER_CONFIG_DIR override moves the file the operator would edit.
+		const clioDirs = resolveClioDirs();
 		const rendered = selfAwareness.body
 			.replace("{CLIO_DOCS_PATH}", join(packageRoot, "docs"))
 			.replace("{CLIO_SRC_PATH}", join(packageRoot, "src"))
-			.replace("{CLIO_CODEWIKI_PATH}", join(packageRoot, "dist", "assets", "codewiki.json"));
+			.replace("{CLIO_CODEWIKI_PATH}", join(packageRoot, "dist", "assets", "codewiki.json"))
+			.replace("{CLIO_SETTINGS_PATH}", join(clioDirs.config, "settings.yaml"))
+			.replace("{CLIO_STATE_PATH}", clioDirs.state);
 		identityBody = [identity.body.trim(), rendered.trim(), ...(docsRouting ? [docsRouting.body.trim()] : [])].join(
 			"\n\n",
 		);

package/src/domains/prompts/contract.ts

@@ -1,6 +1,8 @@
 import type { CompiledSessionPrompt, SessionPromptInputs, WorkerPromptInputs } from "./compiler.js";
 
 export interface CompileSessionPromptInput {
+	/** Stable session identity that owns the compiler's frozen disk-input snapshot. */
+	sessionId: string;
 	sessionInputs: SessionPromptInputs;
 	autonomy?: string;
 	cwd?: string;
@@ -23,11 +25,21 @@ export interface CompileWorkerPromptInput extends WorkerPromptInputs {
 }
 
 export interface PromptsContract {
+	/**
+	 * Revision of compiler-owned inputs. Fragment, agent-catalog, and
+	 * session-source invalidation components advance independently and are
+	 * combined without loss. Project handbooks, rules, operator profile, and
+	 * repo awareness are frozen in a real per-session snapshot until a config
+	 * invalidation or a new session.
+	 */
+	inputEpoch(): string;
+
 	/**
 	 * Compile the session system prompt. Called once per session (and again
 	 * only on explicit, logged events: model/target change, autonomy-level
-	 * change, fragment reload, session switch). Inputs must be constant for
-	 * the session's lifetime.
+	 * change, fragment reload, session switch). Compiler-owned disk inputs are
+	 * selected from the session snapshot even when another identity input causes
+	 * a recompile.
 	 */
 	compileSessionPrompt(input: CompileSessionPromptInput): Promise<CompiledSessionPrompt>;
 
@@ -39,6 +51,6 @@ export interface PromptsContract {
 	 */
 	compileWorkerPrompt(input: CompileWorkerPromptInput): Promise<CompiledSessionPrompt>;
 
-	/** Reload fragment table (triggered by config.hotReload). */
+	/** Reload fragment table and advance `inputEpoch` after a successful load. */
 	reload(): void;
 }

package/src/domains/prompts/extension.ts

@@ -8,9 +8,11 @@ import type { AgentsContract } from "../agents/contract.js";
 import type { ConfigContract } from "../config/contract.js";
 import {
 	type ContextContract,
+	type LoadedOperatorProfile,
 	loadOperatorProfile,
 	loadProjectRules,
 	type ProjectPromptContext,
+	type ProjectRulesLoad,
 	renderOperatorProfile,
 	selectActiveRules,
 } from "../context/index.js";
@@ -28,11 +30,26 @@ export interface PromptsBundleOptions {
 const CLIO_REPO_AWARENESS_ID = "context.clio-repo-awareness";
 const WORKSPACE_ROOT_ID = "context.workspace-root";
 
+interface CustomizationSourceSnapshot {
+	rules: ProjectRulesLoad["rules"];
+	operatorProfile: LoadedOperatorProfile | null;
+}
+
+interface SessionPromptSourceSnapshot {
+	projectContext: ProjectPromptContext | null;
+	customization: CustomizationSourceSnapshot;
+	workspaceRoot: RenderedPromptFragment[];
+	clioRepoAwareness: RenderedPromptFragment[];
+}
+
 export function createPromptsBundle(
 	context: DomainContext,
 	options: PromptsBundleOptions = {},
 ): DomainBundle<PromptsContract> {
 	let table: FragmentTable | null = null;
+	let fragmentEpoch = 0;
+	let sessionSourceEpoch = 0;
+	const sessionSourceSnapshots = new Map<string, SessionPromptSourceSnapshot>();
 	const suppressContextFiles = options.noContextFiles === true;
 
 	function config(): ConfigContract | undefined {
@@ -60,6 +77,7 @@ export function createPromptsBundle(
 	function reload(): void {
 		try {
 			table = loadFragments();
+			fragmentEpoch += 1;
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			process.stderr.write(`[clio-coder:prompts] reload failed: ${msg}\n`);
@@ -73,7 +91,42 @@ export function createPromptsBundle(
 		return false;
 	}
 
+	function sessionSourceKey(sessionId: string, cwd: string): string {
+		return `${sessionId}\0${cwd}`;
+	}
+
+	function captureSessionSourceSnapshot(cwd: string): SessionPromptSourceSnapshot {
+		let projectContext: ProjectPromptContext | null = null;
+		if (!suppressContextFiles) {
+			projectContext = contextDomain()?.renderPromptContext(cwd) ?? null;
+			for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
+		}
+		return {
+			projectContext,
+			customization: captureCustomizationSources(cwd),
+			workspaceRoot: workspaceRootFragment(cwd),
+			clioRepoAwareness: clioRepoAwarenessFragments(cwd),
+		};
+	}
+
+	function sessionSourceSnapshot(sessionId: string, cwd: string): SessionPromptSourceSnapshot {
+		const key = sessionSourceKey(sessionId, cwd);
+		const existing = sessionSourceSnapshots.get(key);
+		if (existing) return existing;
+		const captured = captureSessionSourceSnapshot(cwd);
+		sessionSourceSnapshots.set(key, captured);
+		return captured;
+	}
+
+	function invalidateSessionSources(): void {
+		sessionSourceSnapshots.clear();
+		sessionSourceEpoch += 1;
+	}
+
 	const contract: PromptsContract = {
+		inputEpoch() {
+			return `${fragmentEpoch}:${agentsDomain()?.revision() ?? 0}:${sessionSourceEpoch}`;
+		},
 		async compileSessionPrompt(input: CompileSessionPromptInput) {
 			if (!table) throw new Error("prompts domain not started");
 			if (table.byId.size === 0) {
@@ -83,11 +136,12 @@ export function createPromptsBundle(
 			const settings: Readonly<ClioSettings> | undefined = configContract?.get();
 			const safety = input.autonomy ?? settings?.safety.autonomy ?? "auto-edit";
 			const cwd = input.cwd ?? process.cwd();
+			const sources = sessionSourceSnapshot(input.sessionId, cwd);
 			let contextFiles = "";
 			let projectPreload: ProjectPreloadClass | null = null;
 			let projectHandbookFiles: string[] = [];
 			if (!suppressContextFiles) {
-				const projectContext = contextDomain()?.renderPromptContext(cwd);
+				const projectContext = sources.projectContext;
 				contextFiles = projectContext
 					? selectProjectContext(projectContext, input.sessionInputs.providerSupportsTools ?? null)
 					: "";
@@ -98,7 +152,6 @@ export function createPromptsBundle(
 					});
 					projectHandbookFiles = projectContext.handbookFiles;
 				}
-				for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
 			}
 			const roster = fleetRoster();
 			const sessionInputs = {
@@ -112,9 +165,9 @@ export function createPromptsBundle(
 				safety: `safety.${safety}`,
 				sessionInputs,
 				additionalFragments: [
-					...workspaceRootFragment(cwd),
-					...clioRepoAwarenessFragments(cwd),
-					...customizationFragments(cwd, input.workingContextPaths ?? []).fragments,
+					...sources.workspaceRoot,
+					...sources.clioRepoAwareness,
+					...renderCustomizationFragments(sources.customization, cwd, input.workingContextPaths ?? []).fragments,
 				],
 			});
 			return { ...compiled, projectPreload, projectHandbookFiles };
@@ -141,25 +194,38 @@ export function createPromptsBundle(
 	};
 
 	let unsubscribeHotReload: (() => void) | null = null;
+	let unsubscribeExtensionsReload: (() => void) | null = null;
 	const extension: DomainExtension = {
 		async start() {
 			try {
 				table = loadFragments();
+				fragmentEpoch += 1;
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				process.stderr.write(`[clio-coder:prompts] initial load failed: ${msg}\n`);
 				table = { byId: new Map(), rootDir: "" };
 			}
 			unsubscribeHotReload = context.bus.on(BusChannels.ConfigHotReload, (payload: unknown) => {
+				invalidateSessionSources();
 				const diff = (payload as { diff?: { hotReload?: string[] } } | undefined)?.diff;
 				const paths = diff?.hotReload ?? [];
 				if (!diffTouchesFragments(paths)) return;
 				reload();
 			});
+			// Extension prompt and skill roots feed fragments through the
+			// resources domain; a committed generation with new content means
+			// the table must be rebuilt from the new roots.
+			unsubscribeExtensionsReload = context.bus.on(BusChannels.ExtensionsReloaded, (payload: unknown) => {
+				if ((payload as { changed?: unknown } | undefined)?.changed !== true) return;
+				reload();
+			});
 		},
 		async stop() {
 			unsubscribeHotReload?.();
 			unsubscribeHotReload = null;
+			unsubscribeExtensionsReload?.();
+			unsubscribeExtensionsReload = null;
+			sessionSourceSnapshots.clear();
 		},
 	};
 
@@ -189,13 +255,36 @@ export interface CustomizationFragmentsResult {
 export function customizationFragments(
 	cwd: string,
 	workingContextPaths: ReadonlyArray<string>,
+): CustomizationFragmentsResult {
+	return renderCustomizationFragments(captureCustomizationSources(cwd), cwd, workingContextPaths);
+}
+
+function captureCustomizationSources(cwd: string): CustomizationSourceSnapshot {
+	let rules: ProjectRulesLoad["rules"] = [];
+	let operatorProfile: LoadedOperatorProfile | null = null;
+	try {
+		rules = loadProjectRules(cwd).rules;
+	} catch {
+		// Project rules are best-effort; a load failure freezes an empty set.
+	}
+	try {
+		operatorProfile = loadOperatorProfile(cwd);
+	} catch {
+		// The operator profile is best-effort; a load failure freezes no profile.
+	}
+	return { rules, operatorProfile };
+}
+
+function renderCustomizationFragments(
+	sources: CustomizationSourceSnapshot,
+	cwd: string,
+	workingContextPaths: ReadonlyArray<string>,
 ): CustomizationFragmentsResult {
 	const fragments: RenderedPromptFragment[] = [];
 	let activeRuleIds: string[] = [];
 	let operatorProfileApplied = false;
 	try {
-		const loaded = loadProjectRules(cwd);
-		const active = selectActiveRules(loaded.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
+		const active = selectActiveRules(sources.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
 		if (active.length > 0) {
 			const body = ["# Project rules", ...active.map((rule) => rule.body)].join("\n\n");
 			fragments.push({
@@ -211,8 +300,7 @@ export function customizationFragments(
 		// Project rules are best-effort; a load failure must not block compilation.
 	}
 	try {
-		const profile = loadOperatorProfile(cwd);
-		const rendered = renderOperatorProfile(profile.profile);
+		const rendered = renderOperatorProfile(sources.operatorProfile?.profile ?? {});
 		if (rendered.text.length > 0) {
 			fragments.push({
 				id: "context.operator-profile",

package/src/domains/prompts/fragments/identity/clio-worker.md

@@ -6,6 +6,4 @@ description: Identity for a bounded Clio fleet worker
 
 # Identity
 
-You are Clio, IOWarp's coding agent, running as one bounded worker in a Clio fleet.
-Complete only the assigned task within the admitted tool and autonomy contracts, then return a concise handoff to the coordinating session.
-You do not coordinate the fleet unless an admitted tool and the assigned task explicitly authorize delegation.
+You are Clio, IOWarp's coding agent, running as one bounded worker in a Clio fleet. Return a concise handoff to the coordinating session; do not coordinate the fleet unless the assigned task and an admitted tool explicitly authorize it.

package/src/domains/prompts/fragments/identity/clio.md

@@ -1,25 +1,19 @@
 ---
 id: identity.clio
 version: 1
-budgetTokens: 200
 description: Clio identity and persona block
 ---
 
 # Clio identity
 
 You are Clio, the coding agent in IOWarp's CLIO ecosystem of agentic
-science (NSF-funded, iowarp.ai). CLIO stands for Context Layer for
-Input/Output. You are the first female agentic coder, named for the
-Greek muse of history who proclaimed and made famous the great
-deeds of the past. Developed by the Gnosis Research Center
-at Illinois Tech (github.com/grc-iit, @grc-iit) and the IOWarp
-team, you focus on HPC and scientific-software engineering for
-researchers and developers.
+science (Context Layer for Input/Output), developed by the Gnosis
+Research Center at Illinois Tech for HPC and scientific-software
+engineering.
 
-Whichever weights run you, your name and persona are Clio. You are
-not Claude, GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's
-assistant, and you do not claim to be from Anthropic, OpenAI,
-Alibaba, Google, Meta, or any other model vendor.
+Whichever weights run you, your name and persona are Clio: not Claude,
+GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's assistant, and
+you claim no model vendor.
 
 You do not invent capabilities, and you do not bypass confirmations,
 privilege limits, or git safety rails.

package/src/domains/prompts/fragments/identity/docs-routing.md

@@ -1,10 +1,9 @@
 ---
 id: identity.docs-routing
 version: 1
-budgetTokens: 120
 description: Directive to route questions about Clio herself through context(scope="docs"); rendered only when context is on the surface
 ---
 
 # Clio documentation routing
 
-When the user asks about Clio herself, her commands, configuration, targets, fleet, dispatch, extensions, skills, safety model, or any other Clio behavior, call context (scope="docs", query=<the question>) before answering and before any grep, find, or read: Clio's documentation ships with the package, not in the working tree, so searching the workspace for it finds nothing. Every response lists the whole corpus alongside the ranked sections, so one call routes the question to its document; then read that document completely from the installed documentation path above.
+For a question about Clio herself, call context (scope="docs", query=<the question>) before answering and before any workspace search, then read the document it names from the installed documentation path above.

package/src/domains/prompts/fragments/identity/self-awareness.md

@@ -1,19 +1,11 @@
 ---
 id: identity.self-awareness
 version: 1
-budgetTokens: 260
 description: Clio self-awareness, installed documentation, and harness configuration paths
 ---
 
 # Clio's own harness
 
-Read these only when the user asks about Clio herself, her configuration, targets, fleet, extensions, skills, dispatch, or safety model; never for ordinary coding work.
-
-Installed documentation: {CLIO_DOCS_PATH}
-Installed source: {CLIO_SRC_PATH}
-Code map: {CLIO_CODEWIKI_PATH} (a structural index of Clio's own files, symbols, and import edges; paths are POSIX-relative to the installed source root)
-When reading Clio documentation, resolve docs/... there, not in the current working directory.
-Documentation routes, code decides: when precision matters, verify against the installed source, because code outranks docs.
-
-User configuration lives in ~/.config/clio-coder/settings.yaml and machine-produced session state lives in the XDG state directory (~/.local/state/clio-coder on Linux, ~/Library/Application Support/clio-coder/state on macOS, %LOCALAPPDATA%/clio-coder/state on Windows). Extension and skill authoring is documented in docs/extensions-and-sharing.md and docs/skills-marketplace.md.
-Always read Clio .md documentation files completely and follow cross-references before acting.
+Only for questions about Clio herself (her commands, configuration, targets, fleet, dispatch, extensions, skills, or safety model), never for ordinary coding work.
+Her documentation and source ship with the package, not in the workspace: documentation at {CLIO_DOCS_PATH}, source at {CLIO_SRC_PATH}. Code outranks docs when precision matters.
+User settings live in {CLIO_SETTINGS_PATH}; session state lives in {CLIO_STATE_PATH}.

package/src/domains/prompts/fragments/operating/contract.md

@@ -1,27 +1,19 @@
 ---
 id: operating.contract
 version: 1
-budgetTokens: 400
 description: Constitutional operating posture shared by every Clio prompt
 ---
 
 # Operating Contract
 
-Clio has one operating posture. There is no read-only posture or
-user-facing posture toggle.
+Use tools when they materially help the task. Prefer a structured tool
+over bash when one exists; for narrow file or symbol work, inspect
+directly with the observe tools.
 
-Use the available tools when they materially help the current task.
-Prefer structured tools over bash when a structured tool exists. For
-narrow file or symbol work, inspect directly with structured observe
-tools. When a final report is requested but file
-modification is forbidden, put the report in the final assistant response;
-do not create a report artifact.
-
-Safety policy is authoritative for every tool call: allow decisions
-run normally; hard blocks (destructive git,
-protected artifacts, project or path policy violations) remain hard
-blocks. When a call is blocked or cancelled, pivot to a safer
-approach or explain the blocker. Do not retry the same blocked
+Safety policy is authoritative for every tool call. Hard blocks
+(destructive git, protected artifacts, project or path policy
+violations) stay blocked: when a call is blocked or cancelled, pivot to
+a safer approach or explain the blocker, and never retry the blocked
 action through another tool. After a loop guard blocks a repeated call,
 do not retry it or a syntactic variant: synthesize, delegate narrowly,
 use another source, or mark the claim unverified.