@iowarp/clio-coder 0.3.0

package/docs/README.md

@@ -0,0 +1,93 @@
+<p align="center">
+  <img src="../assets/clio-coder-logo-128.webp" alt="Clio Coder logo" width="96" height="96" />
+</p>
+
+# Clio Coder Documentation
+
+These pages document `v0.3.0` of Clio Coder, an open-source coding orchestrator within the [IOWarp](https://iowarp.ai) scientific computing platform, created by the [Gnosis Research Center](https://grc.iit.edu) at the [Illinois Institute of Technology](https://www.iit.edu).
+
+They are source-aligned guides: when prose and source disagree, prefer the
+current source, tests, and `CHANGELOG.md`.
+
+## Start Here
+
+| Need | Guide |
+| --- | --- |
+| Commands, slash commands, operating posture, keybindings, dispatch, verification, and troubleshooting | [commands-and-modes.md](commands-and-modes.md) ([Interactive Blueprint](html/commands_blueprint.html)) |
+| Context window resolution, per-model probe capabilities, token accounting, per-turn snapshots, compaction, and context priming | [context-engine.md](context-engine.md) ([Interactive Blueprint](html/context_blueprint.html)) |
+| Runtime targets, local model configuration, fleet profiles, and auth | [configuration-and-targets.md](configuration-and-targets.md) ([Interactive Blueprint](html/configuration_blueprint.html)) |
+| Every environment variable the runtime reads: guardrail overrides, directory layout, debug toggles, and internal plumbing | [environment-variables.md](environment-variables.md) ([Interactive Blueprint](html/environment_blueprint.html)) |
+| Argonne ALCF Sophia/Metis inference targets over Globus OAuth | [alcf-provider.md](alcf-provider.md) ([Interactive Blueprint](html/alcf_blueprint.html)) |
+| Installation, upgrade, reset, uninstallation, configuration folders, and permissions | [installation-and-lifecycle.md](installation-and-lifecycle.md) ([Interactive Blueprint](html/lifecycle_blueprint.html)) |
+| Safety posture, default-deny Bash, project policy, damage-control rules, and typed validation | [safety-model.md](safety-model.md) ([Interactive Blueprint](html/safety_blueprint.html)) |
+| Source layout, compile-time boundaries, domain loading, and runtime data flow | [architecture.md](architecture.md) ([Interactive Blueprint](html/architecture_blueprint.html)) |
+| Why the dispatch domain is not split, which invariants cross the obvious seams, and why direct subpath imports are permitted | [dispatch-architecture-rationale.md](dispatch-architecture-rationale.md) |
+| Prompt envelope reuse, provider tool delivery, and bounded tool results | [prompt-envelope-and-tools.md](prompt-envelope-and-tools.md) ([Interactive Blueprint](html/tools_blueprint.html)) |
+| In-depth reference for all 19 worker tools: parameters, typical payloads, and error examples | [tool-usage.md](tool-usage.md) ([Interactive Blueprint](html/tool_usage_blueprint.html)) |
+| Developer guide to implementing custom model runtimes and inference server integrations | [provider-adapter-cookbook.md](provider-adapter-cookbook.md) ([Interactive Blueprint](html/provider_adapter_blueprint.html)) |
+| Built-in agent recipes, discovery roots, frontmatter schema, and dispatch admission | [built-in-agents.md](built-in-agents.md) ([Interactive Blueprint](html/agents_blueprint.html)) |
+| Artifact browsing, receipt verification, dispatch diagnostics, and observability routing | [observability.md](observability.md) ([Interactive Blueprint](html/observability_blueprint.html)) |
+| Evidence directory structures, findings, and operator-approved memory retrieval | [evidence-and-memory.md](evidence-and-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
+| Local YAML eval suites, reports, comparisons, and command evidence | [eval-runner.md](eval-runner.md) ([Interactive Blueprint](html/eval_blueprint.html)) |
+| Prompt and skill resources, extension manifests, and portable share archives | [extensions-and-sharing.md](extensions-and-sharing.md) ([Interactive Blueprint](html/extensions_blueprint.html)) |
+| Skills Hub marketplace discovery, install actions, and publishing flow | [skills-marketplace.md](skills-marketplace.md) ([Interactive Blueprint](html/skills_blueprint.html)) |
+| Runtime model refresh, catalog sources, local/cloud model quirks, and benchmarking notes | [model-catalog.md](model-catalog.md) ([Interactive Blueprint](html/models_blueprint.html)) |
+| Active component snapshots and the experimental middleware hook/effect contract | [middleware-and-components.md](middleware-and-components.md) ([Interactive Blueprint](html/middleware_blueprint.html)) |
+| Advisory validation-contract patterns for scientific artifacts and HPC assumptions | [scientific-validation.md](scientific-validation.md) ([Interactive Blueprint](html/validation_blueprint.html)) |
+| Falsifiable Change Manifest JSON templates, auditability, and `clio-coder evolve` | [evolution.md](evolution.md) ([Interactive Blueprint](html/evolution_blueprint.html)) |
+| Source-first docs workflow, mapping matrix, and alpha wording guidance | [documentation-guide.md](documentation-guide.md) ([Interactive Blueprint](html/documentation_blueprint.html)) |
+| Interface layout, colors palette, Unicode character vocabulary, and drawing choreography | [tui-design.md](tui-design.md) ([Interactive Blueprint](html/tui_design_blueprint.html)) |
+| NDJSON parent-child socket protocols, watchdog timers, and exit status mapping | [worker-dispatch-mechanics.md](worker-dispatch-mechanics.md) ([Interactive Blueprint](html/worker_dispatch_blueprint.html)) |
+| Multi-node fleet dispatch: process-safe admission, attested workers, measured routing, activation, agent automation, topologies, and receipts | [fleet-dispatch.md](fleet-dispatch.md) ([Interactive Blueprint](html/fleet_dispatch_blueprint.html)) |
+| Multi-process capacity leases, heartbeat TTLs, cross-process locks, and cluster drain controls | [capacity-and-scheduling.md](capacity-and-scheduling.md) |
+| Executable multi-node demo with reviewer gate and receipt provenance walkthrough | [fleet-demo-runbook.md](fleet-demo-runbook.md) |
+| Session lifecycle, on-disk ledger format v3, `/tree` active-path lineage, `/fork`, `/resume`, checkpoints, and recovery | [session-lifecycle.md](session-lifecycle.md) |
+| Agent Client Protocol (ACP) server over stdio, tool mediation, non-stall permissions, and error taxonomy | [acp.md](acp.md) |
+| Version registry and migration policies for all 9 serialized artifact schemas | [artifact-versions.md](artifact-versions.md) |
+| Process exit code taxonomy, `--help` standard, machine-readable JSON streaming, and headless output contracts | [exit-codes-and-output.md](exit-codes-and-output.md) |
+| Actionable error remediation and diagnostics keyed by exact user-facing messages | [troubleshooting.md](troubleshooting.md) |
+| Canonical definitions of 17 core architectural concepts mapped to `src/` types | [glossary.md](glossary.md) |
+| Complete source-to-documentation mapping matrix and subsystem coverage status | [documentation-coverage.md](documentation-coverage.md) |
+| Proactive task memory architecture, session task bank, intervention rules, and handoff carrying | [proactive-memory.md](proactive-memory.md) ([Interactive Blueprint](html/memory_blueprint.html)) |
+| WAL SQLite trace mirror database schema, rowid cursor queries, rebuildability, and CLI trace subcommands | [trace-store.md](trace-store.md) ([Interactive Blueprint](html/trace_blueprint.html)) |
+| Private context index determinism, target smoke matrices, and Clio machinery soak benchmark suite | [evals-internal.md](evals-internal.md) ([Blueprints: evals_internal](html/evals_internal_blueprint.html), [soak](html/soak_blueprint.html)) |
+| Point-in-time inventory of legacy environment variables (Historical Appendix) | [config-knobs-audit.md](config-knobs-audit.md) ([Interactive Blueprint](html/config_knobs_audit_blueprint.html)) |
+
+Every project Clio works in gets its context from a checked-in `CLIO-CODER.md`,
+bootstrapped and maintained by `clio-coder context init`. The root
+[CLIO-CODER.md](../CLIO-CODER.md) of this repository is the maintained reference example
+of the format.
+
+## Developer Quick Start
+
+```bash
+git clone https://github.com/iowarp/clio-coder.git
+cd clio-coder
+npm run install:local
+hash -r
+clio-coder --version
+```
+
+The local symlink executes `dist/cli/index.js`. If you edit TypeScript files
+under `src/`, run `npm run build` again or keep `npm run dev` running.
+
+## Release Notes
+
+The release entry point is [../README.md](../README.md); detailed release
+history lives in [../CHANGELOG.md](../CHANGELOG.md). For v0.3.0 the supported
+install path is a source checkout through `npm run install:local`, the
+deterministic release gate is `npm run ci:release`, live model smoke
+validation is local/manual and opt-in through `npm run test:live` (add
+`-- --delegation` for opencode/copilot checks), and the package
+is not published to npm.
+
+## Writing Documentation
+
+Guidance for doc authors lives in
+[documentation-guide.md](documentation-guide.md). The short version:
+
+- State alpha status plainly; do not imply npm publication, production
+  stability, or universal local-model behavior without current proof.
+- Prefer command examples that are valid against
+  `node dist/cli/index.js --help`.
+- Keep the README short; detailed command explanations belong in these pages.

package/docs/acp.md

@@ -0,0 +1,120 @@
+# Agent Client Protocol (ACP) Server
+
+This document defines the architecture, transport protocols, tool mediation layers, permission handling, and error taxonomy for Clio Coder's Agent Client Protocol (ACP) server implementation in `v0.3.0`.
+
+Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
+
+---
+
+## 1. Overview & Protocol Specification
+
+Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
+
+The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
+
+```mermaid
+graph LR
+    client[External ACP Client] <-->|JSON-RPC 2.0 / stdio| server[Clio ACP Server]
+    server --> mediator[Tool Mediator & Safety Net]
+    mediator --> engine[Clio Execution Engine]
+    mediator --> session[Session Ledger v3]
+```
+
+---
+
+## 2. Server Command & Transport Wiring
+
+The server is invoked via:
+
+```bash
+clio-coder acp [--cwd PATH] [--permission-timeout MS]
+```
+
+- `--cwd PATH`: Sets the initial workspace root directory for ACP sessions.
+- `--permission-timeout MS`: Configures the maximum timeout for delegated permission resolution (defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` ms from `src/core/defaults.ts:40`).
+
+Transport frames are JSON-RPC 2.0 messages serialized over `stdin`/`stdout`. All logging and diagnostic output is strictly routed to `stderr` to preserve standard I/O framing integrity.
+
+---
+
+## 3. Supported ACP Methods
+
+The ACP server implements the core ACP RPC methods (`src/engine/acp/server.ts`):
+
+| Method | Direction | Description |
+| :--- | :--- | :--- |
+| `initialize` | Client → Server | Negotiates protocol version, agent capabilities, and server implementation info. |
+| `session/new` | Client → Server | Initializes a new Clio session, snapshotting the active autonomy posture and working directory. |
+| `session/load` | Client → Server | Resumes an existing session by ID and synchronizes message history. |
+| `session/list` | Client → Server | Lists known sessions for the current workspace root. |
+| `session/delete` | Client → Server | Deletes a session and its persistent files. |
+| `session/prompt` | Client → Server | Submits a user prompt to the session execution loop. |
+| `session/cancel` | Client → Server | Cancels an in-flight prompt stream or running tool operation. |
+| `session/request_permission` | Server → Client | Requests permission from the client for gated tool operations. |
+
+---
+
+## 4. Tool Mediation & Safety Governance
+
+Tool execution entering through the ACP server is mediated by `src/engine/acp/tool-mediator.ts:createAcpToolMediator`.
+
+### Canonical Tool Mapping
+
+Clio tool names are mapped to the closed ACP `ToolKind` enumeration (`src/engine/acp/types.ts`):
+
+| Clio Tool Name | ACP `ToolKind` | Primary Action Category |
+| :--- | :--- | :--- |
+| `read`, `ls`, `context` | `read` | Workspace inspection |
+| `write`, `edit`, `artifact` | `edit` | Workspace mutation |
+| `grep`, `find`, `code_nav` | `search` | Codebase exploration |
+| `bash`, `verify`, `git` | `execute` | Shell & command execution |
+| `web_fetch` | `fetch` | Network retrieval |
+| Dynamic / MCP tools | `other` | Unmapped fallback |
+
+### Non-Stall Permission Mediation
+
+Under `clio-policy` governance:
+1. Tool calls evaluate through the 10-step safety net policy engine.
+2. If the safety net or autonomy level yields an `ask` verdict (such as mutating actions at `suggest` level or unrecognized bash at `auto-edit` level), the mediator resolves the ask as a **non-stall denial** (`autonomyDenyRejection`).
+3. This non-stall behavior prevents external non-interactive client connections from hanging indefinitely while preserving safety boundaries.
+
+---
+
+## 5. Security & Boundary Guarantees
+
+The ACP boundary enforces strict isolation rules:
+
+1. **Autonomy Snapshotting**: The autonomy level is snapshotted at `session/new`. A subsequent configuration change on the host does not alter an active remote session's security policy.
+2. **Metadata Namespacing**: Clio-specific extensions travel exclusively within namespaced metadata fields (`ACP_USAGE_META_KEY = "clio.coder/usage"`, `ACP_SESSION_META_KEY = "clio.coder/session"` in `src/engine/acp/types.ts:8-9`). Strict clients (e.g. Zed Serde deserializers) never encounter unmapped top-level keys.
+3. **No External Outcome Overrides**: External ACP processes cannot self-assert terminal outcome codes (e.g. `worker_final_output_missing` is enforced at Clio's trusted finalization seam).
+
+---
+
+## 6. Error Taxonomy
+
+The ACP subsystem defines four typed error classes (`src/engine/acp/errors.ts`):
+
+```typescript
+export class AcpError extends Error {
+  readonly code: string;
+  readonly data?: unknown;
+}
+
+export class AcpProtocolError extends AcpError {
+  constructor(message: string, data?: unknown) {
+    super("acp_protocol_error", message, data);
+  }
+}
+
+export class AcpTimeoutError extends AcpError {
+  constructor(message: string, data?: unknown) {
+    super("acp_timeout", message, data);
+  }
+}
+
+export class AcpProcessError extends AcpError {
+  constructor(message: string, data?: unknown) {
+    super("acp_process_error", message, data);
+  }
+}
+```

package/docs/alcf-provider.md

@@ -0,0 +1,72 @@
+# ALCF Inference Provider
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive target configurator and Globus OAuth flow diagram is located at [docs/html/alcf_blueprint.html](html/alcf_blueprint.html) (Version: 0.3.0).
+
+Clio can use Argonne's ALCF inference gateway as an OpenAI-compatible target
+backed by Globus OAuth. The runtime id is `alcf`; each configured target points
+at one gateway cluster URL, such as Sophia or Metis.
+
+The login flow is SSH-friendly. `clio-coder auth login alcf` opens a Globus authorize
+URL and asks you to paste back the displayed authorization code. Clio stores the
+resulting OAuth refresh/access credential in `providers.auth` persisted through `openAuthStorage()`,
+refreshed through the same provider auth path used by other OAuth runtimes.
+
+## Configure
+
+Authenticate first:
+
+```bash
+clio-coder auth login alcf
+```
+
+Then register one or both cluster targets:
+
+```bash
+clio-coder configure \
+  --id alcf-sophia \
+  --runtime alcf \
+  --url https://inference-api.alcf.anl.gov/resource_server/sophia/vllm/v1 \
+  --model openai/gpt-oss-120b \
+  --max-tokens 4096
+
+clio-coder configure \
+  --id alcf-metis \
+  --runtime alcf \
+  --url https://inference-api.alcf.anl.gov/resource_server/metis/api/v1 \
+  --model gpt-oss-120b \
+  --max-tokens 4096
+```
+
+Sophia currently uses `vllm` in the URL and serves `openai/`-prefixed model ids.
+Metis currently uses `api` in the URL and serves bare model ids. Clio sends the
+configured wire model id literally and does not rewrite it.
+
+Set a target as the chat default when you are ready:
+
+```bash
+clio-coder targets use alcf-sophia
+clio-coder targets --probe
+clio-coder models --target alcf-sophia
+```
+
+## Implementation Notes
+
+The implementation is intentionally inside Clio Coder rather than downstream
+scientific apps:
+
+- `src/engine/alcf-oauth.ts` implements the Globus PKCE paste-code OAuth flow.
+- `src/engine/oauth.ts` registers the Clio-owned OAuth provider through the
+  engine boundary.
+- `src/domains/providers/runtimes/cloud/alcf.ts` implements Sophia/Metis
+  discovery and reuses the generic OpenAI-compatible chat synthesis.
+- `ProbeContext.authToken` carries a resolved stored/API/OAuth bearer into live
+  probes so authenticated model discovery does not reach into auth storage.
+- ALCF rejects non-standard `chat_template_kwargs` request fields. The runtime
+  marks synthesized models with `clio.chatTemplateKwargsUnsupported`, and the
+  OpenAI-compatible engine adapter omits that field while still sending the
+  accepted top-level `reasoning_effort`.
+
+Live model availability depends on which gateway jobs are running. The static
+model list is only a fallback for offline resolution; `clio-coder targets --probe`
+uses the ALCF catalog and jobs endpoints after authentication.

package/docs/architecture.md

@@ -0,0 +1,172 @@
+# Clio Coder Architecture and Boundaries
+
+> [!TIP]
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/architecture_blueprint.html](html/architecture_blueprint.html) (Version: 0.3.0).
+
+Clio Coder is an experimental, terminal-first coding harness for the CLIO ecosystem. CLIO stands for Context Layer for Input/Output; the project is named for the Greek muse of history and developed by the Gnosis Research Center at Illinois Tech. Its architecture favors small, auditable subsystems over a single monolithic agent loop: CLI entry points, the interactive TUI, provider/runtime code, worker subprocesses, tools, and feature domains are kept separate so local-model support and scientific-software workflows can evolve without collapsing safety boundaries.
+
+This page is source-code aligned for the current `v0.3.0` development line.
+
+---
+
+## Source layout
+
+```text
+src/
+├── cli/             # clio subcommands, argument parsing, headless run modes
+├── core/            # config/state paths, event bus, defaults, shared primitives
+├── domains/         # feature domains loaded through manifests/contracts
+├── engine/          # pi-ai/provider boundary and runtime adapters
+├── entry/           # orchestrator bootstrap wiring
+├── interactive/     # TUI panels, overlays, key routing, dashboard, slash commands
+├── tools/           # built-in tool specs and registry admission boundary
+├── worker/          # subprocess worker entry/runtime rehydration
+└── utils/           # small support utilities
+```
+
+Registered domain modules include:
+
+| Domain | Primary source | Public surface |
+| --- | --- | --- |
+| agents | `src/domains/agents/**` | Built-in, user, and project agent recipes. |
+| components | `src/domains/components/**` | Component snapshots, diffs, and classification. |
+| config | `src/domains/config/**`, `src/core/config.ts` | `settings.yaml`, keybindings, hot reload. |
+| context | `src/domains/context/**` | `CLIO-CODER.md`, codewiki indexer, repository context. |
+| dispatch | `src/domains/dispatch/**` | Fleet-agent jobs, receipts, worker spawning, route policies. |
+| eval | `src/domains/eval/**` | Local evaluation harness, suites, JUnit/SWE-bench reports. |
+| evidence | `src/domains/evidence/**` | Forensic evidence bundles, failure attribution. |
+| evolution | `src/domains/evolution/**` | Authority-tiered self-edit manifests and gates. |
+| extensions | `src/domains/extensions/**` | Extension discovery, packaging, and lifecycle. |
+| lifecycle | `src/domains/lifecycle/**` | Doctor diagnostics, upgrade mechanics, uninstallation. |
+| memory | `src/domains/memory/**` | Approved long-term memory, proactive task intervention. |
+| middleware | `src/domains/middleware/**` | Declarative and programmatic lifecycle hooks and budgets. |
+| observability | `src/domains/observability/**` | SQLite trace store, metrics projections, live telemetry. |
+| prompts | `src/domains/prompts/**` | Prompt fragments, system prompt envelope, template hashing. |
+| providers | `src/domains/providers/**` | Target-first runtime registry, model probing, credentials. |
+| resources | `src/domains/resources/**` | Skills loader, marketplace synchronization, prompts loader. |
+| safety | `src/domains/safety/**` | 10-step policy engine, path policy, zero-access rails, audit. |
+| scheduling | `src/domains/scheduling/**` | Budget ceilings, node cluster states, batch capacity checks. |
+| session | `src/domains/session/**` | Append-only JSONL transcripts, tree navigation, compaction. |
+| share | `src/domains/share/**` | Portable workspace and resource archive export/import. |
+
+---
+
+## Session Routing vs. Persisted Settings
+
+Clio maintains an explicit distinction between persisted user settings (`settings.yaml`) and session-local routing state (`src/core/session-routing.ts`).
+
+1. **Decoupled Overlays**: Turn-level selections (such as active target, model override, thinking level, and scoped models cycled via Alt+J / Alt+K) apply dynamically through `applySessionRouting` without mutating `settings.yaml`.
+2. **Lifecycle Flow**:
+   - `seedSessionRouting`: Seeds runtime fields from configuration at startup.
+   - `applyRoutingPatch`: Applies surgical routing mutations (such as changing active model or target in the TUI).
+   - `diffRouting`: Detects when an active session's routing diverges from `settings.yaml`.
+   - `routingChangeNotices`: Generates structured notifications when external edits modify `settings.yaml` during an active session, allowing graceful reconciliation.
+   - `restoreRoutingFields`: Restores persisted defaults when resetting session overlays.
+
+---
+
+## Workspace Enumeration and Language Classification
+
+Source: `src/core/workspace-files.ts`, `src/core/c-header-language.ts`.
+
+1. **Filesystem Walker Invariants**:
+   Fallback workspace file enumeration enforces strict safety caps to prevent runaway memory usage or hangs on massive trees:
+   - `maxVisitedEntries`: 100,000 entries
+   - `maxDepth`: 64 directory levels
+   - `maxPathBytes`: 64 MiB total path storage
+   - `maxDurationMs`: 5,000 ms timeout
+2. **C/C++ Header Classification**:
+   Header files (`.h`, `.hpp`, `.hxx`, `.hh`) are classified deterministically through a 3-tier inspection pipeline:
+   - Tier 1: Sibling source matches (for example matching `.cpp` or `.c` with the same base name).
+   - Tier 2: Distinctive `#include` directives (standard C++ headers vs standard C headers).
+   - Tier 3: Language-exclusive tokens (`template<`, `namespace `, `class `, `nullptr`, `constexpr`).
+
+## Boundary invariants
+
+`npm run check:boundaries` executes the boundary check suite (`tests/boundaries/check-boundaries.ts`). Treat these checks as executable specifications.
+
+These five enforced boundary rules constrain dependency **direction**, never import **form** (whether static vs dynamic, default vs named):
+
+### Rule 1: `@earendil-works/*` imports stay in `src/engine/**`
+
+Only files under `src/engine/**` may import `@earendil-works/*` packages. Since the 0.83.0 engine-boundary rework, no file outside `src/engine/**` may import `@earendil-works/*` at all, value or type-only. Domain modules import erased engine shapes (`EngineModel`, `Api`, `Model`) directly from `src/engine/types.ts`.
+
+Why: provider SDKs and pi-ai engine values must remain swappable behind one engine boundary. Domains and presentation layers operate against Clio contracts rather than vendor or runtime implementations.
+
+### Rule 2: Workers do not value-import domains except runtime rehydration
+
+Files under `src/worker/**` may not value-import `src/domains/**`, with the sole exception of worker-safe provider runtime rehydration modules:
+
+- `src/domains/providers/plugins.ts`
+- `src/domains/providers/registry.ts`
+- `src/domains/providers/runtimes/builtins.ts`
+
+Type-only imports erase at compile time and are permitted. Workers receive a serializable `WorkerSpec` envelope, rehydrate only necessary target/runtime descriptors, and avoid pulling interactive state or domain stores into worker subprocesses.
+
+### Rule 3: Domains do not import each other's `extension.ts`
+
+A file under `src/domains/<x>/**` must not import `src/domains/<y>/extension.ts` for `y != x`. Cross-domain behavior flows through public contracts exported from domain index files (`src/domains/<y>/index.ts`), the domain loader, event buses, or serialized manifests.
+
+### Rule 4: Tool substrate is surface-agnostic (`src/tools/**` never imports `src/interactive/**`)
+
+Files under `src/tools/**` may never import `src/interactive/**` (neither value nor type-only imports). The tool substrate is surface-agnostic across headless, interactive, ACP, and worker runs. Allowing tools to import TUI presentation modules would couple execution logic to presentation code.
+
+### Rule 5: One-way entry point composition (`chat-loop.ts` never imports `src/entry/**`)
+
+Turn modules and state machine files in the chat loop (`src/interactive/turn-*.ts`, `chat-loop.ts`) may never import `src/entry/**`. Composition flows in one direction only: the entry point composes the chat loop, never the reverse.
+
+---
+
+## Runtime flow
+
+```mermaid
+graph TD
+    CLI[cli/index.ts] --> ORCH[entry/orchestrator.ts]
+    TUI[interactive/index.ts] --> LOOP[interactive/chat-loop.ts]
+    ORCH --> DOMAINS[domain-loader + domain contracts]
+    LOOP --> PROMPTS[prompts compiler]
+    LOOP --> TOOLS[tool registry]
+    LOOP --> ENGINE[engine runtime]
+    TOOLS --> SAFETY[safety policy]
+    TOOLS --> MIDDLEWARE[middleware hook boundary]
+    ENGINE --> PROVIDERS[provider runtime descriptors]
+    DISPATCH[dispatch domain] --> WORKER[worker subprocess]
+    WORKER --> PROVIDERS
+```
+
+Core data paths:
+
+1. CLI or TUI boot initializes config, data, state, and cache directories through `src/core/init.ts`.
+2. The domain loader starts domains according to each `manifest.ts` dependency list.
+3. The chat loop resolves model/runtime state and visible tools for the selected target and request intent.
+4. The prompt compiler builds a hashed prompt envelope and dynamic turn fragments.
+5. Tool calls enter `src/tools/registry.ts`, which enforces visibility, safety, middleware hooks, protected artifacts, and result shaping before returning output.
+6. Fleet dispatch writes run ledger entries and receipts; evidence/memory/eval domains consume those artifacts later.
+
+---
+
+## Event and audit model
+
+Clio uses in-process event buses for status and audit surfaces, but safety is not delegated to events. The hard gate lives in code:
+
+- Provider capability resolution decides whether tool schemas are sent at all; tool-capable sessions receive the full registry as one deterministic session tool surface.
+- `src/domains/safety/policy-engine.ts` evaluates damage-control rules, project policy, Bash default-deny, and path policy. Write boundaries are detect-and-rollback mechanisms (such as change tracking and rollbacks), never OS-level sandboxing.
+- `src/tools/registry.ts` is the admission point for every tool invocation.
+- `src/domains/dispatch/receipt-integrity.ts` and related dispatch files persist receipts used by evidence and cost surfaces.
+
+## Command spec
+
+Interactive slash commands in Clio Coder are governed by a unified declarative command specification registry. This declarative system replaces hand-rolled parsing logic with structured specifications that define the names, aliases, flags, positionals, and subcommands for each entry. The central registry acts as the single source of truth for command matching, argument parsing, autocomplete suggestion generation, and usage help output. The parser processes user input strings using these declarative specifications to generate structured argument objects and canonical command representations. By deriving all command-related behavior from these specifications, the system ensures consistency across usage help messages and autocomplete overlays.
+
+---
+
+## Verification commands
+
+```bash
+npm run check:boundaries
+npm run typecheck
+npm run test
+npm run build
+```
+
+Run the focused boundary check before editing `src/engine/**`, `src/worker/**`, or cross-domain imports. Run the full test/build gate before release-facing documentation or behavior changes.

package/docs/artifact-versions.md

@@ -0,0 +1,54 @@
+# Artifact Versions & Serialization Contracts
+
+This document is the canonical registry of all versioned file formats, serialized data structures, integrity digests, and migration rules across Clio Coder in `v0.3.0`.
+
+---
+
+## 1. Versioned Artifacts Registry
+
+Clio Coder strictly versions every persistent or network-transported data structure. When a reader encounters an incompatible version, it either executes an automated migration or fails closed with a typed error.
+
+| Artifact / Subsystem | Current Version | Symbol / Type & Source Location | Persisted Path / Wire Location | Schema Semantics & Version Differences | Mismatch Handling |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Run Receipt** | `15` | `RUN_RECEIPT_INTEGRITY_VERSION = 15`<br>`src/domains/dispatch/receipt-integrity.ts:13` | `<stateDir>/receipts/<runId>.json` | Cryptographically sealed run record. Version 15 covers all base provenance fields, routing intent, quality labels, `validationGrounding`, and `capabilityMismatch`. | Fail-closed. Incompatible receipts fail verification and are never read as evidence. |
+| **Session Ledger** | `3` | `CURRENT_SESSION_FORMAT_VERSION = 3`<br>`src/engine/session.ts:66` | `<stateDir>/sessions/<cwdHash>/<sessionId>/` (`meta.json`, `current.jsonl`, `tree.json`) | Append-only ledger format with UUIDv7 turn IDs, session header line, and tree graph linkage. | Automated migration via `src/domains/session/migrations/` on `/resume`. Earlier unmigratable versions rejected. |
+| **Worker Spec** | `3` | `WORKER_SPEC_VERSION = 3`<br>`src/worker/spec-contract.ts:22` | Subprocess `stdin` control plane JSON payload | Worker invocation parameters, tool surface profile, and execution bounds. | Fail-closed preflight rejection before worker activation. |
+| **Worker Runtime Descriptor** | `2` | `WORKER_RUNTIME_DESCRIPTOR_VERSION = 2`<br>`src/worker/spec-contract.ts:23` | Worker attestation descriptor payload | Attestation descriptor for worker runtime environment and hardware facts. | Attestation mismatch causes immediate process termination. |
+| **Worker Protected Artifact State** | `1` | `WORKER_PROTECTED_ARTIFACT_STATE_VERSION = 1`<br>`src/worker/spec-contract.ts:24` | Worker spec initialization snapshot | Snapshot of active protected artifact paths and validation commands passed to worker. | Worker fails closed before executing mutations. |
+| **Fleet Contract** | `1 \| 2 \| 3 \| 4` (Current: `4`) | `FleetContractVersion = 1 \| 2 \| 3 \| 4`<br>`FLEET_WRITE_BOUNDARY_VERSION = 4`<br>`src/domains/agents/fleet-contract.ts:37, 140` | `.clio-coder/fleets/<name>.yaml`, `.clio-coder/fleets/<name>.yml`, or built-in recipes | Multi-agent workflow contract. v1 is agent-only; v2 adds deterministic code steps; v3 adds bounded loops (`FLEET_LOOP_MAX_ATTEMPTS = 5`) and commit steps; v4 adds declared per-step write boundaries (`writes`). | Reader refuses contracts whose version features it does not support. |
+| **Execution Plan** | `4` | `version: 4` in `interface ExecutionPlan`<br>`src/domains/dispatch/execution-plan.ts:98` | Statically compiled DAG representation in dispatch memory and receipts | Statically unrolled, deterministically hashed execution plan. v4 adds bounded loop nodes, verification staleness tracking, and commit nodes. | Preflight validation rejects unsupported plan versions. |
+| **Eval Artifact** | `4` | `version: 4` in `interface EvalArtifactV4`<br>`src/domains/eval/schema/artifact.ts:51-52` | `<stateDir>/evals/<evalId>.json` | Stored eval results with suite provenance, matrix parameters, and itemized metric outcomes. Note: `EVAL_ARTIFACT_VERSION = 1` in `src/domains/eval/types.ts:2` is legacy/dead code. | Incompatible eval artifacts are rejected during `clio-coder eval report` and `compare`. |
+| **Trace Database** | `1` | `TRACE_SCHEMA_VERSION = 1`<br>`src/domains/observability/trace-store.ts:23` | `<stateDir>/trace.sqlite` (`meta` table `schema_version`) | Schema version for the 7 SQLite trace mirror tables (`runs`, `phases`, `events`, `envelopes`, `gate_results`, `agent_sessions`, `processes`). | Log warning (`[clio:trace]`), trace writing degrades without failing the parent run. |
+| **Capacity State File** | `2` | `version: 2` in `interface CapacityStateFile`<br>`src/domains/dispatch/capacity-lease.ts:40` | `<stateDir>/dispatch-admission.json` | Active capacity leases, drain status, and cross-process lock state. | Corrupted or unparseable state file causes admission to fail closed. |
+| **Protected Artifact Journal** | `1` | `version: 1` in `interface PendingProtectedArtifactRecord`<br>`src/domains/session/protected-artifact-journal.ts:22` | `<stateDir>/protected-artifact-pending/<key>/<id>.json` | Write-ahead durability records for pending protected artifacts. | Leftover records reconciled during session initialization. |
+
+---
+
+## 2. Integrity Verification Contracts
+
+### Receipt Integrity (Version 15)
+
+Receipt integrity authenticates that a sealed receipt matches its ledger envelope without modification. Verification reproduces the canonical JSON serialization and computes the SHA-256 digest:
+
+```typescript
+export function computeReceiptDigest(receipt: RunReceiptV15): string {
+  const canonical = serializeCanonicalReceipt(receipt);
+  return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+```
+
+Receipt verification checks:
+1. `integrity.version === 15`.
+2. Calculated SHA-256 matches `integrity.digest`.
+3. All optional fields present in the schema (`validationGrounding`, `capabilityMismatch`, `steering`, `gate`, `plan`, `briefing`) conform to the strict v15 specification.
+
+---
+
+## 3. Migration Mechanics
+
+Session migrations execute automatically when resuming a session whose `meta.json` format version is less than `CURRENT_SESSION_FORMAT_VERSION = 3`:
+
+1. **Discovery**: `src/domains/session/migrations/index.ts:runMigrations` reads the recorded `sessionFormatVersion`.
+2. **Step Execution**: Sequentially runs migration passes (e.g. `v1 -> v2`, `v2 -> v3`), transforming `current.jsonl` entries and reconstructing `tree.json` linkages.
+3. **Atomic Commit**: Staged migrations are written to temporary files, fsync'd, and atomically renamed over the original session files.
+4. **Metadata Update**: `meta.sessionFormatVersion` is updated to `3` and committed to `meta.json`.