@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/domains/prompts/extension.ts

@@ -0,0 +1,304 @@
+import { isAbsolute, relative } from "node:path";
+import { BusChannels } from "../../core/bus-events.js";
+import { detectClioCoderRepo } from "../../core/clio-repo.js";
+import type { ClioSettings } from "../../core/config.js";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { renderFleetPromptSection } from "../agents/catalog.js";
+import type { AgentsContract } from "../agents/contract.js";
+import type { ConfigContract } from "../config/contract.js";
+import {
+	type ContextContract,
+	loadOperatorProfile,
+	loadProjectRules,
+	type ProjectPromptContext,
+	renderOperatorProfile,
+	selectActiveRules,
+} from "../context/index.js";
+import { compile, compileWorker, type RenderedPromptFragment } from "./compiler.js";
+import type { CompileSessionPromptInput, CompileWorkerPromptInput, PromptsContract } from "./contract.js";
+import { type FragmentTable, loadFragments } from "./fragment-loader.js";
+import { sha256 } from "./hash.js";
+import { classifyProjectPreload, type ProjectPreloadClass } from "./preload.js";
+
+export interface PromptsBundleOptions {
+	/** When true, the dynamic context.files fragment renders the empty string. */
+	noContextFiles?: boolean;
+}
+
+const CLIO_REPO_AWARENESS_ID = "context.clio-repo-awareness";
+const WORKSPACE_ROOT_ID = "context.workspace-root";
+
+export function createPromptsBundle(
+	context: DomainContext,
+	options: PromptsBundleOptions = {},
+): DomainBundle<PromptsContract> {
+	let table: FragmentTable | null = null;
+	const suppressContextFiles = options.noContextFiles === true;
+
+	function config(): ConfigContract | undefined {
+		return context.getContract<ConfigContract>("config");
+	}
+
+	function contextDomain(): ContextContract | undefined {
+		return context.getContract<ContextContract>("context");
+	}
+
+	function agentsDomain(): AgentsContract | undefined {
+		return context.getContract<AgentsContract>("agents");
+	}
+
+	/**
+	 * The roster is compiled into the prompt, so a session that starts before
+	 * the agents domain is available renders no Fleet section rather than a
+	 * partial one that would churn the prompt prefix on the next compile.
+	 */
+	function fleetRoster(): string {
+		const specs = agentsDomain()?.listSpecs() ?? [];
+		return specs.length > 0 ? renderFleetPromptSection(specs) : "";
+	}
+
+	function reload(): void {
+		try {
+			table = loadFragments();
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`[clio:prompts] reload failed: ${msg}\n`);
+		}
+	}
+
+	function diffTouchesFragments(paths: ReadonlyArray<string>): boolean {
+		for (const p of paths) {
+			if (p.includes("prompt") || p.includes("fragment")) return true;
+		}
+		return false;
+	}
+
+	const contract: PromptsContract = {
+		async compileSessionPrompt(input: CompileSessionPromptInput) {
+			if (!table) throw new Error("prompts domain not started");
+			if (table.byId.size === 0) {
+				throw new Error("prompts: no fragments loaded, check startup logs");
+			}
+			const configContract = config();
+			const settings: Readonly<ClioSettings> | undefined = configContract?.get();
+			const safety = input.autonomy ?? settings?.autonomy ?? "auto-edit";
+			const cwd = input.cwd ?? process.cwd();
+			let contextFiles = "";
+			let projectPreload: ProjectPreloadClass | null = null;
+			if (!suppressContextFiles) {
+				const projectContext = contextDomain()?.renderPromptContext(cwd);
+				contextFiles = projectContext
+					? selectProjectContext(projectContext, input.sessionInputs.providerSupportsTools ?? null)
+					: "";
+				if (projectContext) {
+					projectPreload = classifyProjectPreload({
+						hasClioMd: projectContext.clioMd !== null,
+						text: projectContext.text,
+					});
+				}
+				for (const warning of projectContext?.warnings ?? []) process.stderr.write(`${warning}\n`);
+			}
+			const roster = fleetRoster();
+			const sessionInputs = {
+				...input.sessionInputs,
+				...(contextFiles.length > 0 ? { contextFiles } : {}),
+				...(roster.length > 0 ? { fleetRoster: roster } : {}),
+			};
+			const compiled = compile(table, {
+				identity: "identity.clio",
+				operatingContract: "operating.contract",
+				safety: `safety.${safety}`,
+				sessionInputs,
+				additionalFragments: [
+					...workspaceRootFragment(cwd),
+					...clioRepoAwarenessFragments(cwd),
+					...customizationFragments(cwd, input.workingContextPaths ?? []),
+				],
+			});
+			return { ...compiled, projectPreload };
+		},
+		async compileWorkerPrompt(input: CompileWorkerPromptInput) {
+			if (!table) throw new Error("prompts domain not started");
+			if (table.byId.size === 0) {
+				throw new Error("prompts: no fragments loaded, check startup logs");
+			}
+			return compileWorker(table, input);
+		},
+		reload,
+	};
+
+	let unsubscribeHotReload: (() => void) | null = null;
+	const extension: DomainExtension = {
+		async start() {
+			try {
+				table = loadFragments();
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				process.stderr.write(`[clio:prompts] initial load failed: ${msg}\n`);
+				table = { byId: new Map(), rootDir: "" };
+			}
+			unsubscribeHotReload = context.bus.on(BusChannels.ConfigHotReload, (payload: unknown) => {
+				const diff = (payload as { diff?: { hotReload?: string[] } } | undefined)?.diff;
+				const paths = diff?.hotReload ?? [];
+				if (!diffTouchesFragments(paths)) return;
+				reload();
+			});
+		},
+		async stop() {
+			unsubscribeHotReload?.();
+			unsubscribeHotReload = null;
+		},
+	};
+
+	return { extension, contract };
+}
+
+/**
+ * Inline prompt fragments for the project's customization surfaces. Unconditional
+ * `.clio-coder/rules/**` rules load with project context here; path-scoped rules stay
+ * out of the base prompt and activate through the rule loader once a matching
+ * file is in working context. The operator profile renders as one capped
+ * section. Both are deterministic (rules sort by id), so a local model's cached
+ * prompt prefix stays stable. Best-effort: a load failure injects nothing.
+ */
+function customizationFragments(cwd: string, workingContextPaths: ReadonlyArray<string>): RenderedPromptFragment[] {
+	const fragments: RenderedPromptFragment[] = [];
+	try {
+		const loaded = loadProjectRules(cwd);
+		const active = selectActiveRules(loaded.rules, normalizeWorkingContextPaths(cwd, workingContextPaths));
+		if (active.length > 0) {
+			const body = ["# Project rules", ...active.map((rule) => rule.body)].join("\n\n");
+			fragments.push({
+				id: "context.project-rules",
+				relPath: "inline/project-rules",
+				body,
+				contentHash: sha256(body),
+				dynamic: true,
+			});
+		}
+	} catch {
+		// Project rules are best-effort; a load failure must not block compilation.
+	}
+	try {
+		const profile = loadOperatorProfile(cwd);
+		const rendered = renderOperatorProfile(profile.profile);
+		if (rendered.text.length > 0) {
+			fragments.push({
+				id: "context.operator-profile",
+				relPath: "inline/operator-profile",
+				body: rendered.text,
+				contentHash: sha256(rendered.text),
+				dynamic: true,
+			});
+		}
+	} catch {
+		// The operator profile is best-effort; a load failure injects nothing.
+	}
+	return fragments;
+}
+
+function normalizeWorkingContextPaths(cwd: string, paths: ReadonlyArray<string>): string[] {
+	const normalized = new Set<string>();
+	for (const filePath of paths) {
+		const rel = isAbsolute(filePath) ? relative(cwd, filePath) : filePath;
+		if (!rel || rel.startsWith("..") || isAbsolute(rel)) continue;
+		normalized.add(rel.replace(/\\/g, "/"));
+	}
+	return [...normalized].sort();
+}
+
+/**
+ * The absolute workspace root, stated once. Tools take paths and working
+ * directories, and a model that was never told the root guesses one: an
+ * observed run passed the container convention `/workspace` to bash and had
+ * the call blocked as a workspace escape. Naming the real root removes the
+ * guess for every tool at once, which no single tool description can do.
+ */
+function workspaceRootFragment(cwd: string): RenderedPromptFragment[] {
+	const body = [
+		"# Workspace",
+		`Absolute workspace root: ${cwd}`,
+		"Relative paths resolve here. Do not invent a root such as /workspace or /repo, and do not pass a working directory unless the command must run in a subdirectory of this root.",
+	].join("\n");
+	return [
+		{
+			id: WORKSPACE_ROOT_ID,
+			relPath: "inline/workspace-root",
+			body,
+			contentHash: sha256(body),
+			dynamic: true,
+		},
+	];
+}
+
+function clioRepoAwarenessFragments(cwd: string): RenderedPromptFragment[] {
+	const awareness = detectClioCoderRepo(cwd);
+	if (!awareness.isClioCoderRepo || !awareness.repoRoot) return [];
+	const body = [
+		"# Clio Source Tree",
+		"This workspace is Clio Coder's own source tree.",
+		"When running inside this repo, Clio can modify her own TUI, skills, agents, tools, prompts, context/bootstrap, and harness as ordinary local source work when the user asks.",
+		"Shared contribution/publishing/push/PR/release requires explicit user intent and normal Git/GitHub etiquette. Do not imply autonomous publishing.",
+	].join("\n");
+	return [
+		{
+			id: CLIO_REPO_AWARENESS_ID,
+			relPath: "inline/clio-repo-awareness",
+			body,
+			contentHash: sha256(body),
+			dynamic: true,
+		},
+	];
+}
+
+function projectTypeFromPromptContext(text: string): string | null {
+	const match = /<project-type>([^<]+)<\/project-type>/.exec(text);
+	const value = match?.[1]?.trim();
+	return value && value !== "unknown" ? value : null;
+}
+
+function hasCodewiki(text: string): boolean {
+	return text.includes("<codewiki>");
+}
+
+function wikiAvailabilityFromPromptContext(text: string): string | null {
+	const match = /<wiki>([^<]+)<\/wiki>/.exec(text);
+	const value = match?.[1]?.trim();
+	return value && value.length > 0 ? value : null;
+}
+
+function renderProjectSynopsis(context: ProjectPromptContext, providerSupportsTools: boolean | null): string {
+	const projectType = projectTypeFromPromptContext(context.text);
+	const wiki = wikiAvailabilityFromPromptContext(context.text);
+	const lines = ["<project-synopsis>"];
+	if (projectType) lines.push(`Language: ${projectType}`);
+	if (context.clioMd) {
+		lines.push(`Project: ${context.clioMd.projectName}`);
+		lines.push(
+			"CLIO-CODER.md: available; compact synopsis only because the handbook is too large for automatic preload.",
+		);
+	}
+	if (hasCodewiki(context.text)) lines.push("Codewiki: available via code_nav.");
+	if (wiki) lines.push(`Wiki: ${wiki}`);
+	if (providerSupportsTools === false) {
+		lines.push("Tools: unavailable for this target; use this synopsis only as fallback context.");
+	} else {
+		lines.push('Retrieve exact repository facts with context(scope="workspace"), code_nav, grep, and read.');
+	}
+	lines.push("</project-synopsis>");
+	return lines.join("\n");
+}
+
+/**
+ * Project context is selected once per session compile: the full CLIO-CODER.md
+ * preload when it is small enough, a compact synopsis otherwise. No per-turn
+ * selection — the session prompt is stable for the session's lifetime. The
+ * cliff itself lives in prompts/preload.ts so reporting surfaces classify
+ * with the same rule.
+ */
+function selectProjectContext(context: ProjectPromptContext, providerSupportsTools: boolean | null): string {
+	const preload = classifyProjectPreload({ hasClioMd: context.clioMd !== null, text: context.text });
+	if (preload.mode === "none") return "";
+	if (preload.mode === "full") return context.text.trim();
+	return renderProjectSynopsis(context, providerSupportsTools);
+}

package/src/domains/prompts/fragment-loader.ts

@@ -0,0 +1,139 @@
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "yaml";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { sha256 } from "./hash.js";
+
+/**
+ * A single prompt fragment loaded from disk, with parsed frontmatter plus the
+ * raw content hash used to seed the prompts domain's reproducibility contract.
+ */
+export interface LoadedFragment {
+	path: string;
+	relPath: string;
+	id: string;
+	version: number;
+	description: string;
+	dynamic: boolean;
+	body: string;
+	contentHash: string;
+}
+
+export interface FragmentTable {
+	byId: ReadonlyMap<string, LoadedFragment>;
+	rootDir: string;
+}
+
+export interface LoadFragmentsOptions {
+	rootDir?: string;
+}
+
+const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const fragmentIdRegex = /^[a-z0-9-]+(?:\.[a-z0-9-]+)+$/;
+
+function defaultRootDir(): string {
+	return path.join(resolvePackageRoot(), "src", "domains", "prompts", "fragments");
+}
+
+function walk(root: string): string[] {
+	const out: string[] = [];
+	let entries: import("node:fs").Dirent[];
+	try {
+		entries = readdirSync(root, { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const entry of entries) {
+		const full = path.join(root, entry.name);
+		if (entry.isDirectory()) {
+			if (entry.name === "wiki") continue;
+			out.push(...walk(full));
+			continue;
+		}
+		if (entry.isFile() && entry.name.endsWith(".md")) {
+			out.push(full);
+		}
+	}
+	return out.sort((left, right) => left.localeCompare(right));
+}
+
+function parseFragment(filePath: string, rootDir: string): LoadedFragment {
+	const raw = readFileSync(filePath, "utf8");
+	// Normalize to POSIX forward slashes so staticCompositionHash is identical
+	// across Windows and POSIX hosts.
+	const rawRel = path.relative(rootDir, filePath);
+	const relPath = rawRel.split(path.sep).join("/");
+	const match = raw.match(frontmatterRegex);
+	if (!match) {
+		throw new Error(`fragment-loader: ${relPath}: missing or malformed YAML frontmatter`);
+	}
+	const frontmatterText = match[1] ?? "";
+	const body = match[2] ?? "";
+
+	let parsed: unknown;
+	try {
+		parsed = yaml.parse(frontmatterText);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`fragment-loader: ${relPath}: invalid YAML frontmatter (${reason})`);
+	}
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter must be a YAML object`);
+	}
+	const fm = parsed as Record<string, unknown>;
+
+	const id = fm.id;
+	if (typeof id !== "string" || !fragmentIdRegex.test(id)) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.id must be a dot-separated namespace`);
+	}
+	const version = fm.version;
+	if (version !== 1) {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.version must be 1`);
+	}
+	const description = fm.description;
+	if (typeof description !== "string" || description.trim() === "") {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.description must be a non-empty string`);
+	}
+	const dynamicRaw = fm.dynamic;
+	if (dynamicRaw !== undefined && typeof dynamicRaw !== "boolean") {
+		throw new Error(`fragment-loader: ${relPath}: frontmatter.dynamic must be a boolean when present`);
+	}
+
+	return {
+		path: filePath,
+		relPath,
+		id,
+		version,
+		description,
+		dynamic: dynamicRaw === true,
+		body,
+		contentHash: sha256(raw),
+	};
+}
+
+/**
+ * Walk `src/domains/prompts/fragments/**\/*.md` (relative to the package root
+ * or the supplied `rootDir`) and return a fragment table keyed by id.
+ *
+ * Duplicate ids throw; malformed or policy-violating fragments throw with a
+ * relPath-qualified error so that the prompts compiler never receives a
+ * partially loaded table.
+ */
+export function loadFragments(options?: string | LoadFragmentsOptions): FragmentTable {
+	const rootDir = typeof options === "string" ? options : options?.rootDir;
+	const resolvedRoot = rootDir ? path.resolve(rootDir) : defaultRootDir();
+	const files = walk(resolvedRoot);
+	const byId = new Map<string, LoadedFragment>();
+	for (const file of files) {
+		const fragment = parseFragment(file, resolvedRoot);
+		const existing = byId.get(fragment.id);
+		if (existing) {
+			throw new Error(
+				`fragment-loader: duplicate fragment id "${fragment.id}" in ${existing.relPath} and ${fragment.relPath}`,
+			);
+		}
+		byId.set(fragment.id, fragment);
+	}
+	return { byId, rootDir: resolvedRoot };
+}

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

@@ -12,8 +12,9 @@ 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 under PI @akougkas, you focus on HPC and
-scientific-software engineering for researchers and developers.
+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.
 
 Whichever weights run you, your name and persona are Clio. You are
 not Claude, GPT, Qwen, Gemini, Llama, Mistral, or any other vendor's

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

@@ -0,0 +1,63 @@
+---
+id: identity.self-awareness
+version: 1
+budgetTokens: 360
+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.
+
+Documentation routing:
+- Commands -> docs/commands-and-modes.md
+- Context window resolution -> docs/context-engine.md
+- Runtime targets -> docs/configuration-and-targets.md
+- Every environment variable the runtime reads -> docs/environment-variables.md
+- Argonne ALCF Sophia/Metis inference targets over Globus OAuth -> docs/alcf-provider.md
+- Installation -> docs/installation-and-lifecycle.md
+- Safety posture -> docs/safety-model.md
+- Source layout -> docs/architecture.md
+- Why the dispatch domain is not split -> docs/dispatch-architecture-rationale.md
+- Prompt envelope reuse -> docs/prompt-envelope-and-tools.md
+- In-depth reference for all 20 worker tools -> docs/tool-usage.md
+- Developer guide to implementing custom model runtimes and inference server integrations -> docs/provider-adapter-cookbook.md
+- Built-in agent recipes -> docs/built-in-agents.md
+- Artifact browsing -> docs/observability.md
+- Where every generated file lands -> docs/artifact-placement.md
+- Evidence directory structures -> docs/evidence-and-memory.md
+- Local YAML eval suites -> docs/eval-runner.md
+- Prompt and skill resources -> docs/extensions-and-sharing.md
+- Skills Hub marketplace discovery -> docs/skills-marketplace.md
+- Runtime model refresh -> docs/model-catalog.md
+- Active component snapshots and the experimental middleware hook/effect contract -> docs/middleware-and-components.md
+- Advisory validation-contract patterns for scientific artifacts and HPC assumptions -> docs/scientific-validation.md
+- Falsifiable Change Manifest JSON templates -> docs/evolution.md
+- Source-first docs workflow -> docs/documentation-guide.md
+- Interface layout -> docs/tui-design.md
+- NDJSON parent-child socket protocols -> docs/worker-dispatch-mechanics.md
+- Multi-node fleet dispatch -> docs/fleet-dispatch.md
+- Multi-process capacity leases -> docs/capacity-and-scheduling.md
+- Executable multi-node demo with reviewer gate and receipt provenance walkthrough -> docs/fleet-demo-runbook.md
+- Session lifecycle -> docs/session-lifecycle.md
+- Agent Client Protocol (ACP) server over stdio -> docs/acp.md
+- Version registry and migration policies for all 9 serialized artifact schemas -> docs/artifact-versions.md
+- Process exit code taxonomy -> docs/exit-codes-and-output.md
+- Actionable error remediation and diagnostics keyed by exact user-facing messages -> docs/troubleshooting.md
+- Canonical definitions of 17 core architectural concepts mapped to src/ types -> docs/glossary.md
+- Complete source-to-documentation mapping matrix and subsystem coverage status -> docs/documentation-coverage.md
+- Issue-driven development lifecycle -> docs/development-pipeline.md
+- Proactive task memory architecture -> docs/proactive-memory.md
+- WAL SQLite trace mirror database schema -> docs/trace-store.md
+- Private context index determinism -> docs/evals-internal.md
+- Point-in-time inventory of legacy environment variables (Historical Appendix) -> docs/config-knobs-audit.md
+- Clock and timestamp conventions -> docs/time-conventions.md
+
+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.

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

@@ -1,7 +1,7 @@
 ---
 id: operating.contract
 version: 1
-budgetTokens: 560
+budgetTokens: 680
 description: Single operating posture contract
 ---
 
@@ -30,6 +30,15 @@ repeating a "tests pass" claim.
 Parent spot-checking is not independent specialist confirmation. Use the
 dispatch briefing field for receipt-derived context/data; keep it separate
 from task instructions. Collect detached runs before final synthesis.
+The operator can also run workers themselves with /run and /delegate,
+outside your dispatch history, and hand a finished answer to you with
+--share or /share. Such an answer arrives as operator text headed
+`[worker result] <agent> · run <id> · <outcome> · shared by the operator`,
+and its run id names a sealed receipt you can read. Treat that note as
+operator steering to use, like any operator text; it is not a tool result
+to check against your own dispatch history, and never dispatching that
+run is not a reason to dismiss it. Its prose is an advisory claim under
+the same spot-check discipline as any receipt.
 Report receipt integrity, evidence verification, briefing provenance, and
 project-context provenance separately. Failed, cap-exhausted, zero-tool,
 and citation-free reconnaissance is non-evidence: treat it as unconfirmed

package/src/domains/prompts/hash.ts

@@ -0,0 +1,73 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Lowercase-hex SHA-256 of a UTF-8 string.
+ *
+ * Used as the single hash primitive for prompt reproducibility. The prompts
+ * domain wraps this together with `canonicalJson` so that any structural input
+ * (fragment manifests, rendered prompt text) lands on a byte-identical hash
+ * whenever the underlying content is equivalent.
+ */
+export function sha256(input: string): string {
+	return createHash("sha256").update(input, "utf8").digest("hex");
+}
+
+/**
+ * Canonical JSON serialization with stable key order and no whitespace.
+ *
+ * Object keys are sorted recursively; arrays preserve their element order.
+ * Primitives (string, number, boolean, null) serialize via JSON.stringify.
+ * Undefined values in objects are dropped; undefined array entries become null
+ * (matching standard JSON.stringify behavior for arrays). Non-finite numbers
+ * and symbols throw, because they cannot be represented deterministically.
+ */
+export function canonicalJson(value: unknown): string {
+	return serialize(value);
+}
+
+function serialize(value: unknown): string {
+	if (value === null) return "null";
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) {
+			throw new Error(`canonicalJson: non-finite number ${String(value)} is not representable`);
+		}
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "bigint") {
+		throw new Error("canonicalJson: bigint is not representable");
+	}
+	if (typeof value === "symbol" || typeof value === "function") {
+		throw new Error(`canonicalJson: ${typeof value} is not representable`);
+	}
+	if (value === undefined) {
+		throw new Error("canonicalJson: undefined is not representable at root");
+	}
+	if (Array.isArray(value)) {
+		const parts: string[] = [];
+		for (let i = 0; i < value.length; i++) {
+			// `i in value` distinguishes a real `undefined` from a sparse hole;
+			// both serialize as `null` to match JSON.stringify's array behavior.
+			if (!(i in value) || value[i] === undefined) {
+				parts.push("null");
+				continue;
+			}
+			parts.push(serialize(value[i]));
+		}
+		return `[${parts.join(",")}]`;
+	}
+	if (typeof value === "object") {
+		const obj = value as Record<string, unknown>;
+		const keys = Object.keys(obj).sort();
+		const parts: string[] = [];
+		for (const key of keys) {
+			const child = obj[key];
+			if (child === undefined) continue;
+			parts.push(`${JSON.stringify(key)}:${serialize(child)}`);
+		}
+		return `{${parts.join(",")}}`;
+	}
+	throw new Error(`canonicalJson: unsupported value of type ${typeof value}`);
+}

package/src/domains/prompts/index.ts

@@ -0,0 +1,32 @@
+import type { DomainModule } from "../../core/domain-loader.js";
+import { createPromptsBundle, type PromptsBundleOptions } from "./extension.js";
+import { PromptsManifest } from "./manifest.js";
+
+export const PromptsDomainModule: DomainModule = {
+	manifest: PromptsManifest,
+	createExtension: createPromptsBundle,
+};
+
+/**
+ * Build a `PromptsDomainModule` with bundle options closed over the factory
+ * call. Used by the orchestrator and `clio-coder run` to thread the global
+ * `--no-context-files` startup flag into the prompts domain without
+ * restructuring the domain loader.
+ */
+export function createPromptsDomainModule(options: PromptsBundleOptions = {}): DomainModule {
+	return {
+		manifest:
+			options.noContextFiles === true
+				? {
+						...PromptsManifest,
+						dependsOn: PromptsManifest.dependsOn.filter((name) => name !== "context"),
+					}
+				: PromptsManifest,
+		createExtension: (context) => createPromptsBundle(context, options),
+	};
+}
+
+export type { CompiledSessionPrompt, RenderedPromptFragment, ToolPromptHint, WorkerPromptInputs } from "./compiler.js";
+export type { CompileSessionPromptInput, CompileWorkerPromptInput, PromptsContract } from "./contract.js";
+export type { PromptsBundleOptions } from "./extension.js";
+export { PromptsManifest } from "./manifest.js";

package/src/domains/prompts/manifest.ts

@@ -0,0 +1,8 @@
+import type { DomainManifest } from "../../core/domain-loader.js";
+
+export const PromptsManifest: DomainManifest = {
+	name: "prompts",
+	// agents: the compiled session prompt carries the fleet roster, so the
+	// recipe registry must be loaded before the first compile.
+	dependsOn: ["config", "context", "resources", "agents"],
+};