Pepps233 · Aug 31, 2026 · Aug 29, 2026 · Aug 29, 2026 · Aug 29, 2026
diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
@@ -174,8 +174,10 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | [`/llama`](docs/llama-cpp.md) | Download, load, and unload llama.cpp router models |
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Thinking level, theme, message delivery, transport |
+| `/settings` | Thinking level, theme, installed skills, message delivery, transport |
 | [`/skills`](docs/skills.md#skill-commands) | Search and reference one or more skills in the editor |
+| [`/evolve`](docs/evolution.md) | Inspect and control harness evolution and generated skills |
+| [`/version`](docs/evolution.md#controls) | Select the active harness revision |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
@@ -230,6 +232,10 @@ On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/ter
 
 Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports.
 
+### Harness Evolution
+
+`/evolve` shows evidence eligibility, jobs, memory proposals, generated skill candidates, provenance, draft diffs, validation, evaluation, target revisions, activation, and rollback. `/version` selects a complete immutable harness revision. Memory and evolved skills change together at the next prompt boundary; in-flight and admitted queued requests remain pinned. The footer shows the active harness and background activity. See [Harness Evolution](docs/evolution.md).
+
 ---
 
 ## Sessions

diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json
@@ -31,6 +31,10 @@
           "title": "Settings",
           "path": "settings.md"
         },
+        {
+          "title": "Harness Evolution",
+          "path": "evolution.md"
+        },
         {
           "title": "Keybindings",
           "path": "keybindings.md"

diff --git a/packages/coding-agent/docs/evolution.md b/packages/coding-agent/docs/evolution.md
@@ -0,0 +1,55 @@
+# Harness Evolution
+
+Diffex can derive workspace-scoped guidance from persisted invocation evidence and store it in immutable harness revisions. A revision can contain `EVOLVE.md` memory and evolved `skills/<name>/SKILL.md` artifacts. The selected revision changes both together.
+
+## Controls
+
+Use `/evolve` to:
+
+- inspect evidence eligibility and running or completed jobs;
+- start, resume, cancel, or browse evolution work;
+- inspect memory proposals and their evidence;
+- inspect skill-candidate provenance, textual draft diffs, deterministic validation, and retrieval/behavior evaluation;
+- activate a skill candidate only after its persisted evaluation is accepted;
+- inspect target revisions and roll back an activated evolved skill to its immutable parent revision;
+- enable or disable future tracing and evolution work.
+
+Skill activation always requires explicit confirmation. Automatic skill activation is not enabled. Candidates that have not passed every required gate remain read-only.
+
+Use `/version` to inspect compatible revisions for the current workspace and select one. Selection validates the complete bundle. A revision with corrupt, unsupported, or workspace-mismatched artifacts is not activated.
+
+## Request boundaries
+
+Harness selection is resolved at prompt admission. A fresh prompt observes the selected revision; in-flight work and already admitted queued messages keep their pinned memory and skill versions. If `/version` changes while an evolution job is running, the job continues from its frozen base and cannot replace the newer selection.
+
+The footer identifies the active harness and shows background evolution activity. `/skills` lists only evolved skills from the active revision whose workspace identity matches the current workspace.
+
+## Automatic eligibility
+
+When evolution is enabled, automatic work requires all of the following:
+
+- more than 1,000,000 estimated unprocessed evidence tokens;
+- at least three eligible settled invocations;
+- no blocking job;
+- a 20-minute cooldown after the previous automatic run.
+
+Evolution model calls use the configured provider and may consume provider quota. Manual `/evolve` work uses the same frozen evidence and validation boundaries.
+
+## Validation and security
+
+Source traces, tool output, files, and generated drafts are treated as untrusted data. Deterministic validation checks structure, provenance, workspace scope, immutable versions, inventory, and bounded sensitive-data rules. Retrieval and behavioral evaluation are separate gates.
+
+These checks do not prove semantic safety and are not a sandbox. Review candidate provenance, draft diffs, validation issues, and evaluation results before activation. See [Security](security.md).
+
+## Storage and recovery
+
+Evolution state is stored beneath the effective agent directory:
+
+- `traces/` contains immutable invocation evidence intervals;
+- `evolution/` contains jobs, artifacts, candidate history, observations, receipts, and recovery state;
+- `evolution-failures/` contains failure reports;
+- `harness-state/` contains immutable revisions and the selected pointer.
+
+Interrupted jobs and candidate work resume from durable checkpoints. Writer retries use stable idempotency keys, leases, exact base revisions, and compare-and-swap selection. Rollback selects an existing immutable parent; it does not mutate historical revisions.
+
+Set `evolution.enabled` to `false` in global settings or use the toggle in `/evolve` to stop future tracing and background/manual evolution controls. Disabling evolution does not unselect the current harness or remove already active evolved skills.
diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md
@@ -219,11 +219,13 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `diffex config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `diffex config` starts in global settings (`~/.diffex/agent/settings.json`); press Tab to switch between global and project-local modes. Use `diffex config -l` to start in project overrides (`.diffex/settings.json`) with inherited global resources dimmed.
+Use `diffex config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `diffex config` starts in global settings (`~/.diffex/agent/settings.json`); press Tab to switch between global and project-local modes. Use `diffex config -l` to start in project overrides (`.diffex/settings.json`) with inherited global resources dimmed. Interactive sessions also expose installed-skill inspection and toggles under **Installed skills** in `/settings`; use `/reload` after changing them.
 
 ## Scope and Deduplication
 
-Packages can appear in both global and project settings. If the same package appears in both, the project entry wins unless the project entry has `autoload: false`, in which case it is applied as a delta over the global entry. Identity is determined by:
+Packages can appear in both global and project settings. If the same package appears in both, the project entry wins unless the project entry has `autoload: false`, in which case it is applied as a delta over the global entry. Project-installed skills take precedence over user and package skills with the same name. An installed skill also retains the unsuffixed name when it collides with an evolved skill. See [Skills](skills.md) for complete catalog and collision rules.
+
+Identity is determined by:
 
 - npm: package name
 - git: repository URL without ref

diff --git a/packages/coding-agent/docs/rpc.md b/packages/coding-agent/docs/rpc.md
@@ -833,6 +833,12 @@ Each command has:
 
 **Note**: Built-in TUI commands (`/settings`, `/hotkeys`, etc.) are not included. They are handled only in interactive mode and would not execute if sent via `prompt`.
 
+## Evolution and Harness Revisions
+
+Persisted CLI RPC sessions participate in invocation tracing and background evolution when `evolution.enabled` is enabled. The selected harness revision is refreshed at prompt admission, and explicit skill references use the same versioned expansion path as other modes.
+
+`/evolve` and `/version` are interactive-only controls. RPC currently has no commands to list, select, activate, or roll back harness revisions, and `get_state` does not expose the active revision. An RPC process therefore follows the globally selected compatible harness unless its embedded session was explicitly pinned through SDK composition.
+
 ## Events
 
 Events are streamed to stdout as JSON lines during agent operation. Events do not generally include an `id` field; `bash_execution_update` includes the `id` of its originating `bash` command when one was provided.

diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md
@@ -770,6 +770,33 @@ const { session } = await createAgentSession({ resourceLoader: loader });
 
 > See [examples/sdk/04-skills.ts](../examples/sdk/04-skills.ts)
 
+### Harness Revisions and Evolved Skills
+
+`createAgentSession()` loads the selected compatible harness by default. Its memory and workspace-matching evolved skills are pinned together for each admitted request. The SDK does not start invocation tracing or evolution workers; those are composed by the CLI runtime.
+
+```typescript
+const active = session.activeHarnessVersion;
+const bundle = session.harnessVersionBundle;
+const versions = await session.listHarnessVersions();
+
+await session.switchHarnessVersion(versions.versions[0]!.manifest.version);
+const references = session.createSkillReferences();
+```
+
+Use explicit harness options when composing a custom runtime:
+
+```typescript
+const { session } = await createAgentSession({
+  harnessStateStore,
+  harnessVersionBundle,
+  pinHarnessVersion: true,
+});
+```
+
+`pinHarnessVersion: true` prevents later prompt admissions from following changes to the selected global pointer. Child sessions pin the parent's memory and evolved-skill snapshot. Custom `ResourceLoader` implementations must implement `setEvolvedSkills()`; `getSkills()` must return the unified installed/evolved catalog.
+
+See [Harness Evolution](evolution.md) and [Skills](skills.md).
+
 ### Context Files
 
 ```typescript

diff --git a/packages/coding-agent/docs/security.md b/packages/coding-agent/docs/security.md
@@ -52,6 +52,14 @@ Common patterns are documented in [Containerization](containerization.md):
 
 If you bind-mount a host workspace read/write, writes from inside the container or VM can still modify host files. Use read-only mounts or copy files into and out of the sandbox when you need stronger protection from unintended writes.
 
+## Evolution Data and Generated Skills
+
+Invocation traces, evolution artifacts and failures, candidate history, lifecycle observations, writer receipts, and harness revisions persist beneath the effective agent directory. They can contain session evidence, generated instructions, skill content, paths, and runtime metadata. Evolution model calls may consume provider quota.
+
+Evolved skills are generated instructions and can direct the model to use tools or referenced assets. Structural, provenance, scope, security, retrieval, and behavioral gates reduce risk but do not prove semantic safety and are not a sandbox. Project trust does not sandbox an already selected harness revision.
+
+Review `/evolve` provenance, draft diffs, validation, and evaluation before activation. Use `/version` and rollback controls to select immutable revisions, and use OS or container isolation for unattended work. See [Harness Evolution](evolution.md).
+
 ## Reporting Security Issues
 
 To report a security issue, follow the repository [Security Policy](https://github.com/diffexai/diffex/blob/main/SECURITY.md). Do not open a public issue for security-sensitive reports.

diff --git a/packages/coding-agent/docs/settings.md b/packages/coding-agent/docs/settings.md
@@ -108,6 +108,14 @@ Set `DIFFEX_SKIP_VERSION_CHECK=1` to disable the upstream compatibility release
 }
 ```
 
+### Evolution
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `evolution.enabled` | boolean | `true` | Global-only. Enables future invocation tracing and manual/background evolution controls. Disabling it does not unselect the active harness or remove active evolved skills. |
+
+Automatic work requires more than 1,000,000 estimated unprocessed evidence tokens, at least three eligible settled invocations, and a 20-minute cooldown after the previous automatic run. Evolution model calls may consume provider quota. See [Harness Evolution](evolution.md).
+
 ### Compaction
 
 | Setting | Type | Default | Description |
@@ -234,6 +242,8 @@ When multiple sources specify a session directory, precedence is `--session-dir`
 
 These settings define where to load extensions, skills, prompts, and themes from.
 
+Use **Installed skills** in `/settings` to inspect global and workspace skill paths, sources, scopes, and enabled state. Toggle entries to persist global or project overrides, then use `/reload` to apply them to the current session. Evolved skills are read-only outside `/evolve` and `/version`.
+
 Paths in `~/.diffex/agent/settings.json` resolve relative to `~/.diffex/agent`. Paths in `.diffex/settings.json` resolve relative to `.diffex`. Absolute paths and `~` are supported.
 
 | Setting | Type | Default | Description |

diff --git a/packages/coding-agent/docs/skills.md b/packages/coding-agent/docs/skills.md
@@ -72,9 +72,15 @@ For project-level Claude Code skills, add to `.diffex/settings.json`:
 
 This is progressive disclosure: only names, descriptions, and locations are always in context; full instructions load on-demand. The TUI, system prompt, SDK, and evolution snapshots all read from the same catalog. Trace observations do not infer that a skill was used or caused an outcome.
 
+### Evolved Skills
+
+Evolved skills are immutable, workspace-scoped artifacts in a harness revision. Diffex exposes them only when the active revision and workspace identity match. Selecting another revision changes `EVOLVE.md` memory and the evolved-skill set together at the next prompt boundary; in-flight and already admitted queued requests remain pinned.
+
+An evolved reference binds its skill ID, content version, digest, workspace, and harness revision. A reference from an inactive revision is rejected. `/reload` refreshes installed skills while preserving the evolved overlay from the active harness. Use `/evolve` to inspect provenance, validation, evaluation, activation, and rollback. See [Harness Evolution](evolution.md).
+
 ## Skill Commands
 
-Use `/skills` in interactive mode to choose installed workspace, installed global, or evolved skills, then search and select one or more skills within that category. Selected skills appear in the editor as purple skill-name tokens while retaining versioned references internally, so you can add the task before submitting. Each reference loads that exact reviewed skill content for one request, including queued steering and follow-up messages. Skills not selected remain progressively disclosed by name, description, and location.
+Use `/skills` in interactive mode to choose installed workspace, installed global, or evolved skills, then search and select one or more skills within that category. Selected skills appear in the editor as purple skill-name tokens while retaining versioned references internally, so you can add the task before submitting. Each reference loads that exact captured skill content for one request, including queued steering and follow-up messages. Skills not selected remain progressively disclosed by name, description, and location.
 
 To install a package containing skills from an interactive terminal, run `diffex install <source>` and choose `Install globally` or `Install for this workspace`. The prompt shows both destinations and the trust implications. Workspace installation requires project trust and never falls back to global installation. Non-interactive installs retain the global default; pass `-l` to select workspace scope explicitly.
 
@@ -174,7 +180,7 @@ Unknown frontmatter fields are ignored.
 
 **Exception:** Skills with missing description are not loaded.
 
-Name collisions (same name from different locations) warn and keep the first skill found.
+Installed skill name precedence is project, user, then package order. Collisions warn and retain the higher-precedence installed skill. When an evolved skill has the same name, the installed skill retains the unsuffixed name and the evolved skill is exposed as `<name>-Evolved`; if that alias also collides, the evolved skill is omitted with a diagnostic.
 
 ## Example
 

diff --git a/packages/coding-agent/docs/usage.md b/packages/coding-agent/docs/usage.md
@@ -40,8 +40,10 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Thinking level, theme, message delivery, transport |
+| `/settings` | Thinking level, theme, installed skills, message delivery, transport |
 | `/skills` | Browse installed workspace, installed global, and evolved skills |
+| [`/evolve`](evolution.md) | Inspect and control harness evolution and generated skills |
+| [`/version`](evolution.md#controls) | Select the active harness revision |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
 | `/name <name>` | Set session display name |
@@ -125,6 +127,10 @@ On Windows Terminal, Alt+Enter is fullscreen by default. Remap it as described i
 
 Configure delivery in [Settings](settings.md) with `steeringMode` and `followUpMode`.
 
+## Harness Evolution
+
+`/evolve` shows evidence eligibility, jobs, memory proposals, generated skill candidates, provenance, draft diffs, validation, evaluation, target revisions, activation, and rollback. `/version` selects a complete immutable harness revision. Memory and evolved skills change together at the next prompt boundary; in-flight and admitted queued requests remain pinned. An active evolution job continues from its frozen base if the selected revision changes. The footer shows the active harness and background activity. See [Harness Evolution](evolution.md).
+
 ## Sessions
 
 Sessions are saved automatically to `~/.diffex/agent/sessions/`, organized by working directory.