@iowarp/clio-coder 0.4.1 → 0.4.2

package/docs/{worker-dispatch-mechanics.md → architecture/worker-dispatch-mechanics.md}

@@ -1,17 +1,17 @@
 # Worker Dispatch Mechanics
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.4.0).
+> **Visual blueprint:** The source checkout includes the complete
+> [Worker Dispatch Mechanics visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/worker_dispatch_blueprint.html).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
 Source of truth:
-- Subprocess entry: [src/worker/entry.ts](../src/worker/entry.ts)
-- Input demultiplexing: [src/worker/stdin-demux.ts](../src/worker/stdin-demux.ts)
-- Heartbeat loop: [src/worker/heartbeat.ts](../src/worker/heartbeat.ts)
-- Spec contracts and exit codes: [src/worker/spec-contract.ts](../src/worker/spec-contract.ts)
-- Dispatch orchestrator: [src/domains/dispatch/index.ts](../src/domains/dispatch/index.ts)
-- Engine worker runtime: [src/engine/worker-runtime.ts](../src/engine/worker-runtime.ts)
+- Subprocess entry: [src/worker/entry.ts](../../src/worker/entry.ts)
+- Input demultiplexing: [src/worker/stdin-demux.ts](../../src/worker/stdin-demux.ts)
+- Heartbeat loop: [src/worker/heartbeat.ts](../../src/worker/heartbeat.ts)
+- Spec contracts and exit codes: [src/worker/spec-contract.ts](../../src/worker/spec-contract.ts)
+- Dispatch orchestrator: [src/domains/dispatch/index.ts](../../src/domains/dispatch/index.ts)
+- Engine worker runtime: [src/engine/worker-runtime.ts](../../src/engine/worker-runtime.ts)
 
 ---
 
@@ -71,7 +71,7 @@ The worker entry mounts a custom stdin demultiplexer (`createWorkerStdinDemux`)
 1. **Steering Commands:**
    `{"type": "steer", "text": "guidance message", "sequence": 1}`
    Instructs a live-input HTTP or SDK worker to alter course. Its runtime emits
-   the receipt-bearing `clio_steer_received` event only after accepting the
+   the receipt-bearing `clio_coder_steer_received` event only after accepting the
    message for the next turn boundary. Single-shot subprocess runtimes install
    no steering handler, drop unexpected guidance without claiming receipt, and
    are not offered steering by the dispatch contract or TUI.
@@ -110,7 +110,7 @@ stateDiagram-v2
 
     state EscalatePosture {
         [*] --> ParkCall
-        ParkCall --> EmitEscalatedEvent : stdout <- clio_permission_escalated
+        ParkCall --> EmitEscalatedEvent : stdout <- clio_coder_permission_escalated
         EmitEscalatedEvent --> WaitForInput
         WaitForInput --> ResolveApprove : stdin -> permission_decision (approve)
         WaitForInput --> ResolveDeny : stdin -> permission_decision (deny)
@@ -126,7 +126,7 @@ stateDiagram-v2
 2. **Fail:** Terminate the run immediately, exiting the worker subprocess with exit code `3` (`WORKER_EXIT_PERMISSION_REQUIRED`).
 3. **Escalate (Parking Loop):**
    - The worker parks the tool execution thread.
-   - It generates a unique `requestId` and emits a `clio_permission_escalated` event to `stdout`.
+   - It generates a unique `requestId` and emits a `clio_coder_permission_escalated` event to `stdout`.
    - The parent process intercepts this event, displays the approval prompt in the interactive TUI, and waits for the operator.
    - If the operator selects approve or deny, the parent writes `{"type":"permission_decision", "requestId":"...", "decision":"..."}` to the worker's `stdin`.
    - The demuxer resolves the parked promise, resuming tool execution.
@@ -157,7 +157,7 @@ stream ends when the assignment settles, not when one attempt's worker exits,
 so a consumer that drains it has seen exactly the run the terminal receipt
 describes. A canceled assignment ends its stream immediately.
 
-Retry timing is governed by `workers.maxRetries` and exponential backoff alone.
+Retry timing is governed by `fleet.retry.maxRetries` and exponential backoff alone.
 Target cooldowns gate *new* dispatches to a known-bad target and are not
 applied to retries of an in-flight assignment, whose retry budget already
 bounds it. A retry refused at admission settles the assignment failed and
@@ -207,7 +207,7 @@ The coordinator classifies failures into 13 explicit categories (`src/domains/di
 
 ### 5.2 Canonical Receipt Integrity Serialization
 
-Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 19`); any other version is invalid. It computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`).
+Receipts carry the current integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 20`). Verification computes a cryptographic SHA-256 digest over a strictly sorted, canonical JSON representation (`serializeCanonical` in `src/domains/dispatch/receipt-integrity.ts`). A pre-v20 receipt is retired and cannot be read as current evidence; a malformed or digest-mismatched v20 receipt is invalid.
 
 - **Object Key Sorting**: Keys are sorted lexicographically before serialization (`Object.keys(obj).sort()`).
 - **Strict Primitive Handling**: `undefined` object properties are omitted; non-finite numbers (`NaN`, `Infinity`) or `bigint` throw an explicit serialization error.
@@ -225,23 +225,20 @@ state vocabulary and compatibility map are documented in
 
 ### 5.3 Acceptance Coverage
 
-The assignment contract's acceptance scenarios map to deterministic contract
-tests as follows:
-
-| # | Scenario | Contract test |
-| --- | --- | --- |
-| 1 | Remote stall, approved local fallback, attached success | `dispatch-envelope.test.ts`: "falls back from remote to local only within an approved envelope" |
-| 2 | Detached collection returns successful terminal fallback | `dispatch-assignment-detached.test.ts`: "collects the terminal retry…" |
-| 3 | Pipeline consumes terminal fallback output | `dispatch-assignment-detached.test.ts`: "threads the successful retry output…" |
-| 4 | Failed attempt remains visible and integrity-verifiable | `dispatch-assignment.test.ts`: "resolves attached dispatch…" (also covered by detached collection) |
-| 5 | Cancellation starts no retry | `dispatch-assignment.test.ts`: "canceling the root attempt starts no retry" |
-| 6 | Cancellation does not cool the target | `dispatch-failure-class.test.ts`: "keeps cancellation and permission neutral…" |
-| 7 | Permission/policy rejection is retry- and breaker-neutral | `dispatch-failure-class.test.ts`: classification/decision table and neutral-target test |
-| 8 | Node-channel failure changes node but retains model | `dispatch-failure-class.test.ts`: "moves only the node…" |
-| 9 | Rate limit retains agent/model and delays or changes target | `dispatch-failure-class.test.ts`: "changes target after rate limiting…" |
-| 10 | Exhaustion returns one failure with all attempt receipts | `dispatch-assignment.test.ts`: "settles exhausted retries…" |
-| 11 | Exact manual pin never falls back | `dispatch-envelope.test.ts`: "keeps a manual exact pin fail-closed…" |
-| 12 | Approved envelope never spawns outside its candidate list | `dispatch-envelope.test.ts`: "settles failed instead of spawning an unlisted candidate" |
+The current reduced contract suite divides dispatch coverage by ownership:
+
+| Contract | Current executable coverage |
+| --- | --- |
+| `tests/contracts/dispatch-lifecycle.test.ts` | Attached and detached lifecycle deduplication, durable transitions, terminal finalization, and orphan recovery from durable attempts. |
+| `tests/contracts/dispatch-admission.test.ts` | Typed-scope authority, capability pairing, deterministic capacity admission, conservative slot defaults, and ACP authority boundaries. |
+| `tests/contracts/dispatch-schema.test.ts` | Capability-shaped model schema, referenced `$defs`, and hidden-field compatibility. |
+
+Earlier releases carried separate envelope, assignment, detached-assignment,
+and failure-class test files for the detailed retry scenarios. Those files are
+not present in the current tree, so this page does not cite them as executable
+coverage. Retry and failover behavior remains owned by the dispatch source and
+the three maintained contracts above cover only the responsibilities stated in
+this table.
 
 ## 6. Worker Exit Codes
 

package/docs/{built-in-agents.md → guide/built-in-agents.md}

@@ -1,9 +1,9 @@
 # Clio Coder Agent Fleet
 
-Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
+> **Visual blueprint:** The source checkout includes the complete
+> [Clio Coder Agent Fleet visual reference](https://github.com/iowarp/clio-coder/blob/main/docs/html/agents_blueprint.html).
 
-> [!TIP]
-> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.4.1).
+Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.
 
@@ -16,25 +16,27 @@ Clio's agent architecture distinguishes between authoring configurations and run
 *   **Recipe**: An authored Markdown file containing frontmatter configuration and an instruction body.
 *   **AgentSpec**: The normalized runtime and catalog policy object derived from a recipe.
 *   **audience**: Determines visibility and routing (`base` | `shadow` | `custom` | `internal`).
-*   **source**: Origin of the recipe (`builtin` | `user` | `project`).
+*   **source**: Origin of the recipe (`builtin` | `extension` | `user` | `project`).
 
 ### Discovery, Overrides, and Precedence
-At startup, Clio loads recipes from three roots:
+At startup, Clio loads recipes in four precedence tiers:
 
 | Source | Root | Notes |
 | --- | --- | --- |
 | **Built-in** | `src/domains/agents/builtins/*.md` in the installed package | Shipped defaults. |
+| **Extension** | Each enabled extension's `agents` resource root | Loaded in stable extension-source order. An extension recipe may bind only skills from the same extension. |
 | **User** | `<configDir>/agents/*.md` | Per-user recipes. `<configDir>` follows Clio's XDG/platform config directory. |
 | **Project** | `.clio-coder/agents/*.md` under the current repo | Repository-local overrides and additions (custom/domain agents). |
 
 Recipe IDs are derived from filenames (e.g., `architect.md` -> `architect`). Recipes must live directly under their respective directories.
 
 *   **Customization**: User-level agents can override/customize shipped base agents.
+*   **Extension Protection**: Extension recipes cannot override any shipped builtin.
 *   **Shadow Protection**: User or project agents can **never** override shadow or internal agents.
 *   **Built-in Protection**: Project agents cannot override any shipped built-ins; they are strictly treated as custom/domain agents.
-*   **Reserved IDs**: The IDs `worker` and `delegate` are strictly reserved for custom/internal contexts and cannot be registered as custom agent IDs.
+*   **Reserved IDs**: The IDs `worker`, `delegate`, and `auto` cannot be registered outside the builtin tier.
 *   **Local Ignored Custom Examples**: Local examples (e.g., `benchmark-runner`, `clio-dev`, `implementer`, `scientific-validator`) may exist under `.clio-coder/agents` for documentation or test purposes, but are ignored if they collide with reserved/built-in rules.
-*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Library-installed contracts live at `<configDir>/fleets/<name>.md`. Project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`. Contract v4 requires per-step write boundaries (`writes`).
+*   **Fleet Contracts**: Shipped builtin fleet contracts (`build-test`, `build-review`, `sdlc`) live under `src/domains/agents/fleets/*.md`. Enabled-extension contracts load next, user contracts at `<configDir>/fleets/<name>.md` load after them, and project contracts at `.clio-coder/fleets/<name>.md` take highest precedence. The parser accepts contract versions 1 through 5. Version 4 introduces enforced per-step `writes` boundaries; version 5 adds plan and gate steps, per-step target or profile routes, and the `writers: 1` single-writer declaration. Deterministic code steps reference commands declared in `.clio-coder/fleets/commands.yaml`.
 
 ---
 
@@ -47,25 +49,25 @@ User-facing agents visible in `clio-coder agents` and `/agents`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs changes across boundaries, contracts, migrations, and validation gates. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes and behavior-preserving refactors. | `workspace-edit` | `balanced` |
-| `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or receipts without making edits. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer-facing docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Executes bounded git operations: history, commits, worktrees, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic tests for regressions and missing coverage. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Independently runs and reports test, lint, build, review, and release gates. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans one repository wiki, or researches and writes one wiki page. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
+| `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or runs without editing, reading receipts, logs, and runtime behavior. | `verification` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
+| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
 
 ### Shipped Shadow and Internal Agents
-Internal orchestration helpers and internal process agents. They are hidden from default displays (but visible via `clio-coder agents --all` and in a separate section of the prompt catalog).
+Internal orchestration helpers and internal process agents. They are hidden from default displays but visible via `clio-coder agents --all`. The full on-demand catalog has a separate shadow section and omits internal recipes; the compact session prompt likewise omits internal recipes and also excludes the operator-only `oracle`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance, codebase orientation, structure and entry-point mapping, and multi-file symbol hunting. | `read-only` | `fast` |
-| `researcher` | read, web_fetch, context, ledger | Shadow docs and external-source researcher for coding decisions. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git, ledger | Shadow evidence, receipt, diff, and telemetry reader for handoffs. | `read-only` | `balanced` |
+| `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
+| `researcher` | read, web_fetch, context, ledger | Researches external docs, standards, and papers for coding decisions. | `read-only` | `deep` |
+| `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
-| `context-bootstrap` | read, grep, find, ls, context, code_nav, ledger | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
+| `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 
 The builtin `architect` also serves as the default author for a version 5 fleet `plan` step. In that role it returns the coordinator-owned `delegation-plan` result shape instead of writing its ordinary plan artifact. It may name only agents from the contract roster. The coordinator supplies the plan step's target or profile to every admitted task.
 
@@ -107,19 +109,19 @@ Two rounds only help when the reason is actionable, so a validator reason names
 ```yaml
 ---
 version: 1                            # recipe schema version
-name: Coder                           # string; defaults to recipe id when absent
-description: Bounded code changes     # string; defaults to empty string
+name: Coder                           # required non-empty string
+description: Bounded code changes     # required non-empty string
 tools:                                # required/optional tool mapping, not a flat list
   required: [read, {anyOf: [write, edit]}, context]   # anyOf: at least one must admit
   optional: [grep, git, verify, bash, ledger]         # attached when the target carries them
 skills: [fix-issue, ship]             # knowledge attachments; require the context tool, never expand tool authority
-audience: base                        # base | shadow | internal
+audience: base                        # base | shadow | custom | internal
 category: implement                   # explore | plan | research | implement | quality | science | evolution | operations | internal
 capabilityClass: workspace-edit       # read-only | artifact-write | workspace-edit | verification | orchestration | internal
 latencyClass: balanced                # fast | balanced | deep
 projectContextTier: bounded           # how much project context the worker is briefed with
 tags: [implementation, repair]        # short lowercase routing hints for catalog display
-budget:                               # optional strict worker-loop phase policy
+budget:                               # required strict worker-loop phase policy
   toolCalls: 50                       # admitted calls before final response handling
   readReserve: 5                      # final admitted slots reserved for canonical read
   synthesis: true                     # true: text-only final round; false: stop immediately
@@ -133,7 +135,9 @@ optional `product` key also exists for product-scoped recipes. There are no
 `model`, `target`, `thinkingLevel`, or `output` frontmatter keys — target and
 model selection belong to dispatch, not the recipe.
 
-A custom source recipe may omit `budget`; admission then materializes a concrete WorkerSpec v3 budget from the operator's current `guardrails.workerToolCallCap`. Built-in recipes declare the field and fail startup if their strict frontmatter is malformed. When a source recipe includes `budget`, it must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis` (plus an optional `maximum` ceiling object, e.g. architect's `maximum: {toolCalls: 150, readReserve: 16}`): the numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows declared policy or `operator-default`, never a mutable effective cap.
+Every recipe must declare `name`, `description`, `budget`, and every other key in the required set; no display defaults are synthesized. `budget` must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis`, plus an optional `maximum` ceiling object such as architect's `maximum: {toolCalls: 150, readReserve: 16}`. The numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows the declared policy, never a mutable effective cap.
+
+Only shipped recipes may declare the `base`, `shadow`, or `internal` audience. Extension, user, and project recipes must declare `audience: custom`; the discovery root determines that provenance and the parser refuses a conflicting claim.
 
 The operator cap is independent and cannot be widened by a recipe. Dispatch clamps `toolCalls` to that cap and clamps `readReserve` to zero when canonical `read` is absent after tool admission. Reserve slots admit only `read`, not every read-class tool. Blocked non-read attempts do not consume admitted reserve slots, but they still count toward the operator attempt ceiling.
 
@@ -157,13 +161,13 @@ Skills are knowledge attachments declared under `skills: [...]` in the YAML fron
 
 An assignment may request `agent: auto`, but agent choice is advisory by default and is independent of target/model/runtime/node route activation. The coordinator first removes recipes that fail audience, capability-class, execution-role, tool-surface, result-contract, target, or policy constraints. Those are hard constraints and never become score weights. The remaining recipes are ranked deterministically with measured evidence and bounded cold-start priors.
 
-Active agent selection requires an exact `{agentId, executionRole}` entry in `routing.agentAutomation.activeAgentRoles` and a passing readiness report for that same agent and role. Empty activation settings are the default. If no eligible agent is ready, active automation fails closed instead of falling back to the fixed requested recipe.
+Active agent selection requires an exact `{agentId, executionRole}` entry in `fleet.adaptiveRouting.agentRoles` and a passing readiness report for that same agent and role. Empty activation settings are the default. If no eligible agent is ready, active automation fails closed instead of falling back to the fixed requested recipe.
 
 Scout is the bounded escalation path for broad reconnaissance, not an authority shortcut. Its strict `scout-report` may return grounded findings or a split recommendation with typed subtasks. The coordinator validates the transition, assigns fresh authority and an absolute deadline to each child, and records the decision. A recovery attempt uses the dedicated recovery role and may not silently inherit broader builder authority.
 
 ### ACP Delegation Agents as First-Class Workers
 
-ACP delegation agents (registered under `delegation.agents` in `settings.yaml`) are integrated as first-class workers:
+ACP delegation agents (registered under `integrations.externalAgents.entries` in `settings.yaml`) are integrated as first-class workers:
 - **Automatic Routing:** When a task is dispatched to an agent ID matching a configured ACP delegation agent, the dispatch engine automatically routes the execution to that delegation agent.
 - **Dynamic Spec Discovery:** The agent registry automatically synthesizes complete AgentSpecs for configured ACP delegation agents. They are visible via `clio-coder agents` and in slash command menus.
 
@@ -179,7 +183,7 @@ In addition to standard HTTP targets and [Agent Client Protocol (ACP)](https://a
 - **`claude-code` (Claude Subprocess):** Runs `claude -p` as a subprocess worker, mapping autonomy levels to the CLI's permission modes. It is a black box: tool calls run inside the `claude` process and are not routed through Clio's per-tool mediation, so Clio cannot enforce a per-tool profile on it. Dispatching a narrowing `tool_profile` (`minimal-local` or `science-local`) to this runtime is refused; use `full-agent` (or a native / `claude-sdk` worker) instead.
 - **`antigravity-code` (Antigravity CLI):** Runs an Antigravity CLI subprocess as a subscription worker target for fleet dispatch. Like `claude-code`, it is a black box with no per-tool mediation and no per-tool allowlist, so a narrowing `tool_profile` is refused rather than silently ignored.
 
-Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. `claude-code` and `antigravity-code` reject recipes that explicitly declare `budget`, because silently ignoring numeric bounds would be unsafe; a custom source recipe without the field receives the concrete operator-default budget at admission. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
+Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. Every valid Markdown recipe declares a budget, so recipe-based runs are refused on `claude-code` and `antigravity-code`; those subprocess targets can accept only work that reaches admission without an explicit recipe or request budget. Silently ignoring numeric bounds would be unsafe. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
 
 Interactive TUI:
 
@@ -241,7 +245,7 @@ over run:
   `pipeline` provenance (source run, step position, input bytes, whether the
   cap truncated it). Step 1 and every non-pipeline run get none. The `pipeline`
   and `personaOverride` field shapes and their stability labels are documented
-  in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance).
+  in the [receipt provenance schema](../architecture/observability.md#receipt-fields-for-dispatch-provenance).
 
 ---
 
@@ -260,19 +264,19 @@ Subagent runs that terminate with retryable outcomes are placed in an in-memory
 Scheduled retries use an exponential backoff state to calculate subsequent retry delays. Furthermore, targets that fail are subject to a cooldown period. The retry engine ensures that a retried task waits for the maximum of the exponential backoff delay or the remaining target cooldown duration. Retries are brand-new runs that must re-pass all admission checks. If target policies or budgets deny a retry, the task chain terminates as denied.
 
 ### 3. Concurrency Limits
-The setting `budget.concurrency` restricts the number of concurrent subagent tasks. Setting it to `auto` determines the concurrency limit dynamically based on system capabilities.
+The setting `fleet.concurrency` restricts the number of concurrent subagent tasks. At this revision, `auto` resolves to the compiled default of four local workers; it does not probe the host dynamically.
 
 ### 4. Heartbeats and Reconciler
 For native subprocess workers, Clio uses a heartbeat mechanism. The reconciler monitors the active heartbeat timestamp. If a worker stops responding and updates no heartbeats, the reconciler terminates the stalled subprocess automatically.
 
 ### 5. Worker Permission Postures
-A dispatched worker has no operator by default, so a tool call that requires interactive permission must resolve within bounded time. The `workers.onPermission` setting picks the posture:
+A dispatched worker has no operator by default, so a tool call that requires interactive permission must resolve within bounded time. The `fleet.permissions.mode` setting picks the posture:
 
 - `deny` (default): the parked call becomes a structured tool denial and the run continues.
 - `fail`: the run finalizes immediately with outcome `failed`/`permission_required`.
-- `escalate`: the parked call is handed up to the interactive operator. The worker emits a `clio_permission_escalated` event over its stdout; the dispatch domain republishes it on the bus as a permission request tagged with the run id; the operator resolves it in the TUI permission overlay; and the decision travels back down the worker's stdin as a `permission_decision` line (the same pipe steers use). No model can approve a worker permission; resolution is human-only.
+- `escalate`: the parked call is handed up to the interactive operator. The worker emits a `clio_coder_permission_escalated` event over its stdout; the dispatch domain republishes it on the bus as a permission request tagged with the run id; the operator resolves it in the TUI permission overlay; and the decision travels back down the worker's stdin as a `permission_decision` line (the same pipe steers use). No model can approve a worker permission; resolution is human-only.
 
-Escalate is only meaningful with an interactive operator attached. Headless sessions have no subscriber, so the escalation resolves by the timeout fallback. The bounds are `workers.escalation` (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`): a parked ask that no operator answers within `timeoutMs` applies the fallback deny/fail, so an escalate-posture run can never hang forever. The heartbeat timer runs independently of the parked call, so an escalated worker keeps reporting alive while it waits. Each escalation and its resolution (operator or timeout) is tallied on the receipt's `safety.decisions` escalation counters, documented with their stability labels in the [receipt provenance schema](./observability.md#receipt-fields-for-dispatch-provenance); a timed-out or denied escalation also raises an `escalation` finding in the evidence bundle. ACP delegations are out of scope: they resolve permissions through their own mediator and have no worker stdin channel.
+Escalate is only meaningful with an interactive operator attached. Headless sessions have no subscriber, so the escalation resolves by the timeout fallback. The bounds are `fleet.permissions.escalation` (`{ timeoutMs, fallback }`, defaults 120000 ms and `deny`): a parked ask that no operator answers within `timeoutMs` applies the fallback deny/fail, so an escalate-posture run can never hang forever. The heartbeat timer runs independently of the parked call, so an escalated worker keeps reporting alive while it waits. Each escalation and its resolution (operator or timeout) is tallied on the receipt's `safety.decisions` escalation counters, documented with their stability labels in the [receipt provenance schema](../architecture/observability.md#receipt-fields-for-dispatch-provenance); a timed-out or denied escalation also raises an `escalation` finding in the evidence bundle. ACP delegations are out of scope: they resolve permissions through their own mediator and have no worker stdin channel.
 
 ---
 
@@ -283,9 +287,21 @@ Create `.clio-coder/agents/my-agent.md`:
 
 ```md
 ---
+version: 1
 name: My Agent
 description: Focused local review helper.
-tools: [read, grep, find, ls, git, artifact]
+tools:
+  required: [read, artifact]
+  optional: [grep, find, ls, git]
+skills: []
+audience: custom
+category: quality
+capabilityClass: artifact-write
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 20, readReserve: 4, synthesis: true}
+resultContract: {kind: artifact-report}
+tags: [review]
 ---
 
 You are My Agent. Inspect only the requested area. Never edit files. End by writing a concise review artifact (`artifact` kind="review") with risks, evidence, and follow-up tests.