@iowarp/clio-coder 0.3.0 → 0.3.2

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

@@ -4,8 +4,8 @@ name: Coder
 description: Implements bounded code changes, repairs, and behavior-preserving refactors.
 tools:
   required: [read, {anyOf: [write, edit]}, context]
-  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash]
-skills: [commit-crafting, review-changes]
+  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash, ledger]
+skills: [fix-issue, ship]
 audience: base
 category: implement
 capabilityClass: workspace-edit
@@ -29,3 +29,4 @@ Run the narrowest useful validation first, then broaden when risk or shared beha
 Use `git` (op=diff) before finishing to verify the diff matches the task.
 If a requested simplification would change behavior, stop and report the boundary.
 Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.
+`validations` is never empty and never a list of strings. Each entry is one check you actually made, shaped like `{"name":"npm test","passed":true,"evidence":"exit 0"}`, with no other keys. When the task changed nothing, the read or command you did run is still the validation: name it and quote what it showed.

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

@@ -4,7 +4,7 @@ name: Debugger
 description: Diagnoses failing code, tests, receipts, or runtime behavior without making edits.
 tools:
   required: [verify]
-  optional: [read, grep, find, ls, git, code_nav]
+  optional: [read, grep, find, ls, git, code_nav, ledger]
 skills: []
 audience: base
 category: quality

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

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

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

@@ -4,8 +4,8 @@ name: Git Master
 description: Executes 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]
-skills: [commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge]
+  optional: [bash, grep, find, ls, code_nav, ledger]
+skills: [fix-issue, ship, worktree-create, worktree-merge]
 audience: base
 category: implement
 capabilityClass: workspace-edit
@@ -21,7 +21,7 @@ tags: [git, commit, worktree, merge, pr, history]
 You are Git Master, the base agent for repository state operations.
 Start by restating the assigned git task and the exact end state it must produce.
 Inspect before mutating: `git` (op=status) and op=diff before any add, commit, merge, or worktree change; read `git log` before any history claim.
-Load the bound skill that matches the task (commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge) and follow its steps instead of improvising the workflow.
+Load the bound skill that matches the task (fix-issue, ship, worktree-create, worktree-merge) and follow its steps instead of improvising the workflow.
 Local operations only, unless the task explicitly orders otherwise: never push, open a PR, tag, publish, or alter remotes on your own judgment; when a task stops at a boundary, report the boundary.
 Never run destructive history commands (`reset --hard`, `push --force`, `clean -fd`, branch -D on unmerged work) unless the task names the exact command and target.
 Stage files by explicit path after reviewing the untracked list; never blind `git add -A` past unreviewed or secret-shaped files.

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

@@ -4,7 +4,7 @@ name: Provenance
 description: Shadow evidence, receipt, diff, and telemetry reader for source-backed handoffs.
 tools:
   required: [read]
-  optional: [grep, find, ls, git]
+  optional: [grep, find, ls, git, ledger]
 skills: []
 audience: shadow
 category: operations

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

@@ -4,7 +4,7 @@ name: Researcher
 description: Shadow external-source researcher for coding decisions, official docs, standards, release notes, and academic papers.
 tools:
   required: [read]
-  optional: [web_fetch, context]
+  optional: [web_fetch, context, ledger]
 skills: []
 audience: shadow
 category: research

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

@@ -4,7 +4,7 @@ name: Scout
 description: Use for any broad repository reconnaissance, codebase orientation, structure/entry-point mapping, or multi-file symbol hunting; returns cited findings fast without spending main-context tool calls.
 tools:
   required: [read]
-  optional: [grep, find, ls, context, code_nav, git]
+  optional: [grep, find, ls, context, code_nav, git, ledger]
 skills: []
 audience: shadow
 category: explore

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

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

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

@@ -4,7 +4,7 @@ name: Verifier
 description: Independently runs and reports test, lint, build, review, and release gates.
 tools:
   required: [verify]
-  optional: [read, grep, find, ls, git, code_nav]
+  optional: [read, grep, find, ls, git, code_nav, ledger]
 skills: []
 audience: base
 category: quality

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

@@ -4,7 +4,7 @@ name: Wiki Writer
 description: Plans one repository wiki, or researches and writes one wiki page, against a supplied plan.
 tools:
   required: [read, {anyOf: [write, edit]}]
-  optional: [grep, find, ls, code_nav, context]
+  optional: [grep, find, ls, code_nav, context, ledger]
 skills: []
 audience: base
 category: implement

package/src/domains/agents/catalog.ts

@@ -0,0 +1,172 @@
+import type { AgentRecipe } from "./recipe.js";
+import { type AgentSpec, isUserVisibleAgent, normalizeAgentSpec } from "./spec.js";
+
+const DEFAULT_DISPATCH_AGENT_ID = "coder";
+
+export interface AgentCatalogSections {
+	stable: string;
+	volatile: string;
+}
+
+function renderAgentCatalogSections(recipes: ReadonlyArray<AgentRecipe>): AgentCatalogSections {
+	return renderAgentCatalogSectionsFromSpecs(recipes.map(normalizeAgentSpec));
+}
+
+/** Keeps one roster line short enough that the whole fleet block stays near its token budget. */
+const FLEET_PROMPT_PURPOSE_MAX_CHARS = 64;
+
+/**
+ * The delegation default stated as a rule the model can evaluate against the
+ * task in front of it. The E19 drive found the previous phrasing lost to
+ * inertia every time: an incentive ("dispatch is the cheap path") is not a
+ * test, so a model that had already started reading simply kept reading. A
+ * threshold it can count against is.
+ */
+export const FLEET_DELEGATION_RULE =
+	"Delegate when the task has two or more independent file-scoped subtasks, or any broad exploration. You keep synthesis and validation; a single narrow change stays with you.";
+
+/**
+ * S3 handed two files to a worker, then edited both itself before dispatching,
+ * reverted one, and disclosed neither. The delegation rule above says what to
+ * hand off; this says what handing off costs you.
+ */
+export const FLEET_HANDOFF_RULE =
+	"A file you assigned to a worker is not yours to edit while its dispatch is pending or after it succeeds; if you already changed it, say so in your report.";
+
+/**
+ * R5's admission correctly refused a verifier for mutation work and named the
+ * mismatch, and the final answer to the operator never mentioned it. A refusal
+ * the operator cannot see reads as a silent agent swap.
+ */
+export const FLEET_REFUSAL_DISCLOSURE =
+	"When admission refuses a dispatch, report the refusal and the reason it gave; never substitute another agent without saying why.";
+
+/**
+ * R6 issued five near-identical `tester` dispatches because each differed
+ * textually, so a string-identity rule never fired. The test that catches that
+ * run is about the work, and the model needs somewhere else to go than a sixth
+ * dispatch.
+ */
+export const FLEET_ANTI_CHURN_RULE =
+	"A dispatch with the same target files and the same goal as one you already ran is a repeat however differently you word it: read that run's receipt, or run the check yourself, instead of dispatching again.";
+
+/**
+ * `agent:"auto"` baselines from task text alone and cannot see the shape of a
+ * probe, so the jobs it most often misroutes are named against the roster ids
+ * directly below this line.
+ */
+export const FLEET_SPECIALIST_ROUTING =
+	"Pick by job: receipts, diffs, or telemetry -> provenance; external docs -> researcher; broad recon -> scout; tests -> tester; gates or review -> verifier.";
+
+function fleetPromptPurpose(description: string): string {
+	const trimmed = description.trim().replace(/\s+/gu, " ");
+	if (trimmed.length === 0) return "";
+	// One sentence is the useful unit: recipe descriptions put the agent's job
+	// first and its qualifications after the first period.
+	const stop = trimmed.indexOf(". ");
+	const sentence = stop > 0 ? trimmed.slice(0, stop) : trimmed.replace(/\.$/u, "");
+	if (sentence.length <= FLEET_PROMPT_PURPOSE_MAX_CHARS) return sentence;
+	const cut = sentence.lastIndexOf(" ", FLEET_PROMPT_PURPOSE_MAX_CHARS);
+	return `${sentence.slice(0, cut > 0 ? cut : FLEET_PROMPT_PURPOSE_MAX_CHARS).trimEnd()}...`;
+}
+
+function fleetPromptLine(spec: AgentSpec): string {
+	const budget = spec.budget ? `${spec.budget.toolCalls} calls` : "default budget";
+	const purpose = fleetPromptPurpose(spec.description);
+	return `- ${spec.id} (${spec.capabilityClass}, ${budget})${purpose.length > 0 ? `: ${purpose}` : ""}`;
+}
+
+/**
+ * Compact roster for the compiled session prompt. The full catalog above is a
+ * tool result the model has to ask for; this is the same roster small enough to
+ * live in the prompt, so choosing a specialist never costs a round trip. Shadow
+ * agents are listed because they are dispatchable, marked so the model does not
+ * offer them to the operator as `/run` choices. Byte-stable for a given spec
+ * set: the prompt prefix must not churn between turns.
+ */
+export function renderFleetPromptSection(input: ReadonlyArray<AgentSpec>): string {
+	const specs = input.slice().sort((a, b) => {
+		const category = a.category.localeCompare(b.category);
+		return category === 0 ? a.id.localeCompare(b.id) : category;
+	});
+	const publicSpecs = specs.filter(isUserVisibleAgent);
+	const shadowSpecs = specs.filter((spec) => spec.audience === "shadow");
+	if (publicSpecs.length === 0 && shadowSpecs.length === 0) return "";
+
+	const lines: string[] = [
+		"# Fleet",
+		FLEET_DELEGATION_RULE,
+		FLEET_HANDOFF_RULE,
+		FLEET_ANTI_CHURN_RULE,
+		FLEET_REFUSAL_DISCLOSURE,
+		`Workers you reach with \`dispatch\`, by \`agent\` id (default ${DEFAULT_DISPATCH_AGENT_ID}). Capability class is what a worker may do: a read-only worker cannot edit.`,
+		FLEET_SPECIALIST_ROUTING,
+	];
+	if (publicSpecs.length > 0) {
+		lines.push("", "Operator-facing:", ...publicSpecs.map(fleetPromptLine));
+	}
+	if (shadowSpecs.length > 0) {
+		// Dispatchable, but never a `/run` suggestion: they are plumbing.
+		lines.push("", "Internal specialists, dispatch-only:", ...shadowSpecs.map(fleetPromptLine));
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Spec-based roster used when the caller already holds normalized specs.
+ * `AgentsContract.listSpecs()` includes ACP delegation agents synthesized from
+ * settings.delegation.agents[], which never exist as recipe files; rendering
+ * from specs keeps those dispatchable targets discoverable in the fleet block.
+ */
+export function renderAgentCatalogSectionsFromSpecs(input: ReadonlyArray<AgentSpec>): AgentCatalogSections {
+	const specs = input.slice().sort((a, b) => {
+		const category = a.category.localeCompare(b.category);
+		return category === 0 ? a.id.localeCompare(b.id) : category;
+	});
+	const publicSpecs = specs.filter(isUserVisibleAgent);
+	const shadowSpecs = specs.filter((spec) => spec.audience === "shadow");
+
+	const lines: string[] = [
+		"Clio manages a small fleet of coding agents. Recipes are Markdown files; normalized specs carry audience, category, capability, tools, skills, latency, and worker-budget hints.",
+		"Use the `dispatch` tool to invoke one by `agent_id` when delegation helps.",
+		`Default dispatch agent: ${DEFAULT_DISPATCH_AGENT_ID}.`,
+		"User-facing agents are base/custom. Shadow agents are internal helpers for context, research, and provenance; do not recommend them as normal `/run` choices.",
+		"Prefer fast read-only agents for orientation, verification agents for gates, and workspace-edit agents only for bounded coding tasks.",
+		"When a task matches a skill named on an agent line (skills=...), prefer the recipe that binds it; its worker is told to load bound skills for the run.",
+		'After a dispatch succeeds, synthesize from the sealed receipt; the worker\'s prose is an advisory claim until its verification state is verified. Spot-check delegated claims before repeating them: re-read any cited file:line location, and re-run or inspect the named validation before repeating a "tests pass" claim.',
+		FLEET_ANTI_CHURN_RULE,
+	];
+
+	if (publicSpecs.length > 0) {
+		lines.push("", "User-facing agents:");
+		for (const spec of publicSpecs) {
+			const description = spec.description.trim();
+			const suffix = description.length > 0 ? ` - ${description}` : "";
+			lines.push(formatSpecLine(spec, suffix));
+		}
+	}
+	if (shadowSpecs.length > 0) {
+		lines.push("", "Shadow agents for internal orchestration:");
+		for (const spec of shadowSpecs) {
+			const description = spec.description.trim();
+			const suffix = description.length > 0 ? ` - ${description}` : "";
+			lines.push(formatSpecLine(spec, suffix));
+		}
+	}
+
+	return { stable: lines.join("\n"), volatile: "" };
+}
+
+function formatSpecLine(spec: AgentSpec, suffix: string): string {
+	const tags = spec.tags.length > 0 ? `, tags=${spec.tags.join("/")}` : "";
+	const skills = spec.skills.length > 0 ? `, skills=${spec.skills.join("/")}` : "";
+	const budget = spec.budget
+		? `, budget=${spec.budget.toolCalls}/${spec.budget.readReserve}/${spec.budget.synthesis ? "synthesize" : "stop"}`
+		: ", budget=operator-default";
+	return `- ${spec.name} [${spec.id}] (${spec.audience}, ${spec.category}, ${spec.capabilityClass}, ${spec.latencyClass}, ${spec.source}${tags}${skills}${budget})${suffix}`;
+}
+
+export function renderAgentCatalog(recipes: ReadonlyArray<AgentRecipe>): string {
+	const sections = renderAgentCatalogSections(recipes);
+	return [sections.stable, sections.volatile].filter((part) => part.trim().length > 0).join("\n\n");
+}

package/src/domains/agents/contract.ts

@@ -0,0 +1,16 @@
+import type { AgentRecipe } from "./recipe.js";
+import type { AgentRecipeDiagnostic } from "./registry.js";
+import type { AgentSpec } from "./spec.js";
+
+export interface AgentsContract {
+	/** Raw recipes as loaded from Markdown files. */
+	list(): ReadonlyArray<AgentRecipe>;
+	get(id: string): AgentRecipe | null;
+	/** Structured quarantine diagnostics; malformed recipes never appear in list/get. */
+	diagnostics(): ReadonlyArray<AgentRecipeDiagnostic>;
+	/** Normalized, policy-bearing specs for catalog and dispatch consumers. */
+	listSpecs(): ReadonlyArray<AgentSpec>;
+	getSpec(id: string): AgentSpec | null;
+	/** Discover all agents: builtins + user + project. */
+	reload(): void;
+}

package/src/domains/agents/extension.ts

@@ -0,0 +1,110 @@
+import path from "node:path";
+import type { DomainBundle, DomainContext, DomainExtension } from "../../core/domain-loader.js";
+import { resolvePackageRoot } from "../../core/package-root.js";
+import { clioConfigDir } from "../../core/xdg.js";
+import { assertAgentIdNamespace } from "../config/agent-namespace.js";
+import type { ConfigContract } from "../config/contract.js";
+import type { AgentsContract } from "./contract.js";
+import type { AgentRecipe } from "./recipe.js";
+import { type AgentRecipeDiagnostic, loadRecipesFromDir, mergeRecipes } from "./registry.js";
+import { type AgentSpec, normalizeAgentSpec } from "./spec.js";
+
+export function createAgentsBundle(_context: DomainContext): DomainBundle<AgentsContract> {
+	let recipes: ReadonlyArray<AgentRecipe> = [];
+	let specs: ReadonlyArray<AgentSpec> = [];
+	let diagnostics: ReadonlyArray<AgentRecipeDiagnostic> = [];
+
+	function discover(): void {
+		const builtinDir = path.join(resolvePackageRoot(), "src", "domains", "agents", "builtins");
+		const userDir = path.join(clioConfigDir(), "agents");
+		const projectDir = path.join(process.cwd(), ".clio-coder", "agents");
+		const nextDiagnostics: AgentRecipeDiagnostic[] = [];
+		const builtin = loadRecipesFromDir({ dir: builtinDir, source: "builtin" }, nextDiagnostics);
+		const user = loadRecipesFromDir({ dir: userDir, source: "user" }, nextDiagnostics);
+		const project = loadRecipesFromDir({ dir: projectDir, source: "project" }, nextDiagnostics);
+		const merged = mergeRecipes(builtin, user, project);
+		const config = _context.getContract<ConfigContract>("config");
+		assertAgentIdNamespace(merged, config?.get()?.delegation?.agents ?? []);
+		recipes = merged;
+		specs = recipes.map(normalizeAgentSpec);
+		diagnostics = nextDiagnostics;
+	}
+
+	const extension: DomainExtension = {
+		async start() {
+			discover();
+		},
+		async stop() {},
+	};
+
+	const contract: AgentsContract = {
+		list() {
+			return recipes;
+		},
+		get(id: string): AgentRecipe | null {
+			return recipes.find((r) => r.id === id) ?? null;
+		},
+		diagnostics() {
+			return diagnostics.map((diagnostic) => ({ ...diagnostic }));
+		},
+		listSpecs() {
+			const config = _context.getContract<ConfigContract>("config");
+			const delegationAgents = config?.get()?.delegation?.agents ?? [];
+			const delegationSpecs = delegationAgents.map((agent) => ({
+				version: 1 as const,
+				id: agent.id,
+				name: agent.id,
+				description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+				source: "custom" as const,
+				filepath: "settings.yaml",
+				tools: [],
+				toolRequirements: { required: [], optional: [] },
+				category: "explore" as const,
+				capabilityClass: "orchestration" as const,
+				latencyClass: "deep" as const,
+				projectContextTier: "none" as const,
+				audience: "custom" as const,
+				tags: ["delegation", "acp"],
+				skills: [],
+				resultContract: { kind: "external-delegation" } as const,
+				budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+				body: "External ACP delegation.",
+			}));
+			return [...specs, ...delegationSpecs];
+		},
+		getSpec(id: string): AgentSpec | null {
+			const found = specs.find((r) => r.id === id);
+			if (found) return found;
+			const config = _context.getContract<ConfigContract>("config");
+			const agent = config?.get()?.delegation?.agents?.find((entry) => entry.id === id);
+			if (agent) {
+				return {
+					version: 1 as const,
+					id: agent.id,
+					name: agent.id,
+					description: `External ACP delegation agent: ${agent.command} ${(agent.args ?? []).join(" ")}`,
+					source: "custom" as const,
+					filepath: "settings.yaml",
+					tools: [],
+					toolRequirements: { required: [], optional: [] },
+					category: "explore" as const,
+					capabilityClass: "orchestration" as const,
+					latencyClass: "deep" as const,
+					projectContextTier: "none" as const,
+					audience: "custom" as const,
+					tags: ["delegation", "acp"],
+					skills: [],
+					resultContract: { kind: "external-delegation" } as const,
+					budget: { toolCalls: 1, readReserve: 0, synthesis: false },
+					body: "External ACP delegation.",
+				};
+			}
+			return null;
+		},
+		reload() {
+			discover();
+		},
+	};
+
+	return { extension, contract };
+}

package/src/domains/agents/fleet-commands.ts

@@ -0,0 +1,154 @@
+/**
+ * Repo-owned deterministic command registry for fleet code steps.
+ *
+ * A code step names a command id; it never authors a shell string. The binding
+ * from id to argv lives in the repository at `.clio-coder/fleets/commands.yaml`,
+ * beside the fleet contracts that reference it. Two properties follow:
+ *
+ *   - A model cannot invent an invocation. The worst a contract can do is name
+ *     an id, and an unknown id fails contract validation before any dispatch.
+ *   - A contract stays portable. A shipped SDLC fleet can say "run the test
+ *     command" without knowing whether this repo uses npm, uv, or bun.
+ *
+ * The registry is deliberately not a front-matter block on each contract: the
+ * same `test` binding is needed by every contract that tests, and duplicating
+ * argv per contract is how one of the copies silently rots.
+ *
+ * Fail closed. A missing registry is not an empty registry; a contract with a
+ * code step and no registry is invalid, so an unconfigured repo cannot pass a
+ * test phase that never ran anything.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, normalize } from "node:path";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import yaml from "yaml";
+
+/** Upper bound on any single deterministic step, generous enough for a full suite. */
+const FLEET_COMMAND_MAX_TIMEOUT_MS = 3_600_000;
+const FLEET_COMMAND_MIN_TIMEOUT_MS = 1_000;
+export const FLEET_COMMAND_DEFAULT_TIMEOUT_MS = 600_000;
+
+/**
+ * Variables every registered command receives. Code steps run with a closed
+ * environment rather than the operator's, so a subprocess cannot read a
+ * provider key that happens to be exported in the orchestrator's shell. A
+ * command that genuinely needs one more variable names it in `env`.
+ */
+export const FLEET_COMMAND_BASE_ENV: ReadonlyArray<string> = ["PATH", "HOME", "LANG", "LC_ALL", "TZ", "TMPDIR"];
+
+export interface FleetCommand {
+	id: string;
+	/** argv list, never a shell string: no quoting bugs and no shell injection. */
+	argv: ReadonlyArray<string>;
+	/** Workspace-relative working directory; "" means the workspace root. */
+	cwd: string;
+	timeoutMs: number;
+	/** Extra environment variable names passed through on top of the base allowlist. */
+	env: ReadonlyArray<string>;
+	description: string;
+}
+
+export interface FleetCommandRegistry {
+	version: 1;
+	commands: ReadonlyMap<string, FleetCommand>;
+	path: string;
+}
+
+const CommandSchema = Type.Object(
+	{
+		argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+		cwd: Type.Optional(Type.String({ minLength: 1 })),
+		timeoutMs: Type.Optional(
+			Type.Integer({ minimum: FLEET_COMMAND_MIN_TIMEOUT_MS, maximum: FLEET_COMMAND_MAX_TIMEOUT_MS }),
+		),
+		env: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+		description: Type.Optional(Type.String()),
+	},
+	{ additionalProperties: false },
+);
+
+const RegistrySchema = Type.Object(
+	{
+		version: Type.Literal(1),
+		commands: Type.Record(Type.String({ minLength: 1 }), CommandSchema, { minProperties: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+const COMMAND_ID_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
+const ENV_NAME_RE = /^[A-Z_][A-Z0-9_]*$/u;
+
+export function fleetCommandsPath(cwd: string): string {
+	return join(cwd, ".clio-coder", "fleets", "commands.yaml");
+}
+
+function firstSchemaError(value: unknown): string | null {
+	if (Value.Check(RegistrySchema, value)) return null;
+	const first = [...Value.Errors(RegistrySchema, value)][0];
+	return first ? `${first.instancePath || "(root)"}: ${first.message}` : "command registry failed validation";
+}
+
+/** Reject a relative directory that climbs out of the workspace or is absolute. */
+function checkCwd(id: string, value: string, sourcePath: string): string {
+	if (isAbsolute(value)) {
+		throw new Error(`fleet commands ${sourcePath}: command '${id}' cwd must be workspace-relative`);
+	}
+	const normalized = normalize(value);
+	if (normalized === ".." || normalized.startsWith(`..${"/"}`) || normalized.split(/[\\/]/u).includes("..")) {
+		throw new Error(`fleet commands ${sourcePath}: command '${id}' cwd escapes the workspace`);
+	}
+	return normalized === "." ? "" : normalized;
+}
+
+export function parseFleetCommands(raw: string, sourcePath: string): FleetCommandRegistry {
+	let parsed: unknown;
+	try {
+		parsed = yaml.parse(raw);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`fleet commands ${sourcePath}: invalid YAML (${reason})`);
+	}
+	const schemaError = firstSchemaError(parsed);
+	if (schemaError !== null) throw new Error(`fleet commands ${sourcePath}: ${schemaError}`);
+	const registry = parsed as {
+		version: 1;
+		commands: Record<string, { argv: string[]; cwd?: string; timeoutMs?: number; env?: string[]; description?: string }>;
+	};
+	const commands = new Map<string, FleetCommand>();
+	for (const [id, entry] of Object.entries(registry.commands)) {
+		if (!COMMAND_ID_RE.test(id)) {
+			throw new Error(`fleet commands ${sourcePath}: command id '${id}' must match ${COMMAND_ID_RE.source}`);
+		}
+		const executable = entry.argv[0] ?? "";
+		if (executable.trim().length === 0) {
+			throw new Error(`fleet commands ${sourcePath}: command '${id}' has an empty executable`);
+		}
+		for (const name of entry.env ?? []) {
+			if (!ENV_NAME_RE.test(name)) {
+				throw new Error(`fleet commands ${sourcePath}: command '${id}' env name '${name}' is not a variable name`);
+			}
+		}
+		commands.set(id, {
+			id,
+			argv: [...entry.argv],
+			cwd: entry.cwd === undefined ? "" : checkCwd(id, entry.cwd, sourcePath),
+			timeoutMs: entry.timeoutMs ?? FLEET_COMMAND_DEFAULT_TIMEOUT_MS,
+			env: [...(entry.env ?? [])],
+			description: entry.description ?? "",
+		});
+	}
+	return { version: 1, commands, path: sourcePath };
+}
+
+/**
+ * Read the registry, or null when the repo declares none. Null is a distinct
+ * answer from an empty registry: callers turn it into a validation failure
+ * only for contracts that actually contain a code step.
+ */
+export function loadFleetCommands(cwd: string): FleetCommandRegistry | null {
+	const path = fleetCommandsPath(cwd);
+	if (!existsSync(path)) return null;
+	return parseFleetCommands(readFileSync(path, "utf8"), path);
+}