docs: document self-improving automation loops

CONTRIBUTING.md

@@ -121,12 +121,21 @@ refactor: simplify reference resolver lookup
 
 Keep the first line under 72 characters. Add a body explaining *why* if the change isn't obvious.
 
+Install the local `commit-msg` hook once per checkout:
+
+```bash
+scripts/install-git-hooks.sh
+```
+
 CI validates commit subjects with:
 
 ```bash
 scripts/check-conventional-commits.sh origin/master..HEAD
 ```
 
+Run the same command locally before pushing to lint every non-merge commit in a
+branch range. Merge commits are skipped to match CI behavior.
+
 ## Pull Requests
 
 - Target `master` for bug fixes and stable features.

README.md

@@ -152,6 +152,21 @@ Each agent gets the integration that matches its host:
 
 All changes are idempotent -- safe to run again after upgrading. After agent setup, you'll be offered a global git post-commit hook.
 
+Managed skills generated by the self-improvement loop are exported through the
+host surface that each provider can load safely:
+
+| Host | Managed-skill surface |
+|---|---|
+| Cursor | Native skill overlay under the Cursor plugin's managed skill directory. |
+| Codex | Native skill overlay inside the Codex plugin bundle/cache; Codex sessions load approved skills after the plugin is installed or refreshed. |
+| Claude Code, Kimi, OpenCode, Copilot/Vibe, generic Agents targets | Prompt-index block that points the host at `tracedecay_skill_list` and `tracedecay_skill_view` instead of copying full skill bodies into global prompts. |
+| Kiro | Dedicated steering index at `~/.kiro/steering/tracedecay-managed-skills.md`, referenced by the tracedecay-managed Kiro agent. |
+| Hermes | Read-only bridge only. Hermes owns its native skill store; TraceDecay does not export or mutate Hermes skills. |
+
+The curation backend is provider-agnostic. Hermes remains a compatibility bridge
+and reference source; TraceDecay automation can delegate intelligence to hosts
+such as the Codex app server without requiring Hermes to run.
+
 For project-scoped setup, run from the repository root:
 
 ```bash

docs/DASHBOARD-API-AUDIT.md

@@ -114,7 +114,7 @@ in several handlers and omitted from the table for brevity.
 | 3 | GET | `/api/plugins/holographic/projection` | `projection` | `q`, `limit`(25/`PROJECTION_POINT_CAP`=2000) | `{exists, dim, limit, method, points, error}` | `vector_facts` decodes HRR blobs → PCA on `spawn_blocking`. **Cached** by `(query,limit,VectorStateFingerprint)`. |
 | 4 | GET | `/api/plugins/holographic/similarity` | `similarity` | `min_similarity`, `limit`(25/`SIMILARITY_PAIR_CAP`) | `{exists, dim, count, limit, threshold, min_similarity, total_pairs, score_distribution, pairs, error}` | O(n²·d) pairwise phase-cosine on `spawn_blocking`. **Cached** by fingerprint. Emits `threshold` AND `min_similarity` for shape compat. |
 | 5 | GET | `/api/plugins/holographic/curation/status` | `curation_status` | — | curator status stub | Reads `curate_preview`. Mostly static (`paused:false`, `mode:"similarity_dedup"`). |
-| 6 | GET | `/api/plugins/holographic/curation/activity` | `curation_activity` | `limit` | `{events:[], count:0, limit, error}` | **Stub** — no live event stream. |
+| 6 | GET | `/api/plugins/holographic/curation/activity` | `curation_activity` | `limit` | `{events, count, limit, error}` | In-memory deterministic curation activity stream capped to the newest events. Preview/apply, agent-plan, and queued automation paths emit phases such as `queued`, `evidence`, `backend`, `validation`, `apply`, `report`, `finish`, `failure`, and `rejection`. |
 | 7 | GET | `/api/plugins/holographic/curation/preview` | `curation_preview` | — | `{report, saved_at, stale, stale_reason, error}` | Reads saved dry-run preview; recomputes `memory_facts` fingerprint to flag staleness. |
 | 8 | POST | `/api/plugins/holographic/curate` | `curate` | body `{dry_run:bool}` (default true) | `{ran, dry_run, actions, hygiene_candidates, counts, applied_counts, llm_calls, coverage, provider, mode}` | `build_delete_plan` (similarity dedup). dry_run saves preview to state + disk; apply **hard-deletes** losers via `MemoryStore::remove_fact`, records oplog summary. |
 | 9 | POST | `/api/plugins/holographic/curate/apply` | `curate_apply` | body `{ops:[{op:"delete"\|"merge", ...}]}` | `{results, counts:{deleted, merged, errors}}` | Generic ops endpoint. `delete`→`MemoryStore::remove_fact`; `merge`→`MemoryStore::merge_facts` (optional content rewrite + hard-delete losers). Per-op failures reported inline (HTTP 200). |

docs/KIRO-INTEGRATION.md

@@ -16,6 +16,7 @@ so does not overwrite a user's existing custom default-agent choice.
 |---|---|
 | `~/.kiro/settings/mcp.json` | Registers the global `tracedecay` MCP server with `command`, `args: ["serve"]`, and `disabled: false`. Approval policy is left to the managed Kiro agent. |
 | `~/.kiro/steering/tracedecay.md` | Adds global Kiro steering that tells normal Kiro sessions to prefer tracedecay MCP tools for codebase research. |
+| `~/.kiro/steering/tracedecay-managed-skills.md` | Adds a tracedecay-managed skill index for approved managed skills. The index points Kiro at `tracedecay_skill_list` and `tracedecay_skill_view`; full skill bodies remain in TraceDecay's managed skill store. |
 | `~/.kiro/agents/tracedecay.json` | Adds the tracedecay-managed Kiro agent with `tools: ["*"]`, `allowedTools: ["@builtin", "@tracedecay"]`, hooks for delegation guardrails, post-write sync, and an absolute `resources` entry for `~/.kiro/steering/tracedecay.md`. The agent leaves `prompt` unset so Kiro's default prompt is used. |
 | `~/.kiro/settings/cli.json` | Sets `chat.defaultAgent` to `tracedecay` when the setting is absent or still points at Kiro's built-in default. |
 
@@ -25,9 +26,10 @@ tracedecay also does not point `chat.defaultAgent` at that user-managed file.
 If `chat.defaultAgent` already names another custom agent, install leaves that
 choice unchanged and prints a warning.
 
-Uninstall removes only the `tracedecay.md` steering block, the global MCP server entry,
-the tracedecay-owned agent file, and `chat.defaultAgent` when it points at that
-owned agent. User-authored steering after the installed block remains in place.
+Uninstall removes only the `tracedecay.md` steering block, the managed-skill
+index, the global MCP server entry, the tracedecay-owned agent file, and
+`chat.defaultAgent` when it points at that owned agent. User-authored steering
+after the installed block remains in place.
 
 ## Tool approval defaults
 

docs/SELF-IMPROVING-LOOPS-CONTRACTS.md

@@ -0,0 +1,67 @@
+# Self-Improving Loop Contracts
+
+This is the durable contract for TraceDecay-owned self-improvement loops. Hermes is a reference implementation and compatibility bridge, not a requirement for curation, managed skills, scheduler jobs, or artifact generation. The first standalone backend is the Codex app-server adapter, and the same contracts are intended to support other delegated or CLI hosts later.
+
+## Host Matrix
+
+| Host | TraceDecay-owned behavior | Host-owned behavior | Skill delivery |
+| --- | --- | --- | --- |
+| Cursor | Config, ledgers, curation validation, managed skill storage, telemetry sidecars, native overlay export | Native host loading and any host-local transcript signals | Approved managed `SKILL.md` packages under the generated plugin overlay |
+| Codex | Config, ledgers, curation validation, managed skill storage, telemetry sidecars, native overlay export, shareable plugin artifact generation | Native plugin discovery, app-server execution when selected as backend | Approved managed `SKILL.md` packages under the Codex plugin overlay or plugin artifact |
+| Hermes | Read-only bridge over profile skills, pending approvals, usage, curator/write-approval state, and hosted proposals | Auxiliary LLM calls, background review, `skill_manage`, write approvals, skill mutations, curator decisions | Hermes profile skills remain Hermes-owned |
+| Claude Code | Config, ledgers, managed-skill index generation, MCP skill body serving | Prompt-file loading and any host-local execution | Compact `CLAUDE.md` prompt index plus `tracedecay_skill_view` |
+| OpenCode | Config, ledgers, managed-skill index generation, MCP skill body serving | Prompt-file loading and any host-local execution | Compact `AGENTS.md` prompt index plus `tracedecay_skill_view` |
+| Kimi | Config, ledgers, managed-skill index generation, MCP skill body serving | Prompt-file loading and any host-local execution | Compact prompt index plus `tracedecay_skill_view` |
+| Kiro | Config, ledgers, managed-agent prompt-index content, MCP skill body serving | Managed-agent file ownership and host execution | Existing managed-agent path with prompt index plus `tracedecay_skill_view` |
+| Prompt-only agents | Config, ledgers, prompt-index generation, MCP skill body serving | Prompt ingestion and execution | Compact prompt index plus `tracedecay_skill_view` |
+
+## Standalone And Delegated Modes
+
+`standalone` means TraceDecay owns backend calls, evidence collection, validation, run ledger writes, approval staging, dashboard review payloads, and optional scheduler execution. Backend output can propose changes, but TraceDecay validates every proposed mutation before it can be applied.
+
+`delegated_host` means the host owns intelligence and mutation decisions. TraceDecay exposes contracts and storage views, validates proposed operations when asked, and records bridge-visible evidence. It must not call its own backend for memory curation, session reflection, or skill writing in this mode. Legacy `hermes_hosted` config is only an alias for `delegated_host`.
+
+## Curation Operation Contract
+
+Curation proposals are advisory until TraceDecay validation accepts them. Every proposal must identify the reviewed evidence item it targets, include a supported operation kind, provide a confidence/reason, and pass the existing evidence guard before any apply policy is considered.
+
+Timestamp semantics follow the Hermes memory-curator rule:
+
+1. Prove same subject first.
+2. Prove same atomic claim second.
+3. Prefer semantic freshness fields such as `asserted_at`, `effective_at`, `observed_at`, `occurred_at`, or `created_at`.
+4. Treat maintenance `updated_at` as storage metadata, not truth freshness.
+5. Use deterministic tie-breakers only after the subject, claim, and semantic timestamp checks are resolved.
+
+## Managed Skill Contract
+
+TraceDecay-owned managed skills live under the profile `agent_managed/skills` store and static bundled skills stay immutable. Managed skill metadata includes id, title, summary, category, targets, lifecycle state, pinned flag, checksum, timestamps, and provenance. Support files are restricted to `references`, `templates`, `scripts`, and `assets`.
+
+Agent-authored or backend-authored changes enter pending approval first. Activation, disable, archive, restore, and staged updates are explicit lifecycle operations. Pinned and user-authored skills are excluded from automatic archive or patch recommendations; shipped and Hermes-owned skills remain outside TraceDecay-owned mutation surfaces.
+
+## Telemetry And Recommendations
+
+Skill telemetry is a sidecar ledger, not frontmatter. The ledger tracks view/use/patch counts, last timestamps, created_by, state, pinned, targets, and provenance. TraceDecay may normalize its own analytics into this ledger. In delegated Hermes mode, TraceDecay reads Hermes usage/provenance data as bridge evidence and does not write Hermes state.
+
+Archive/prune recommendations are explainable review recommendations only. They cannot auto-delete skills. Skill improvement recommendations must cite repeated corrections, failed workflows, underused tool evidence, or validation artifacts before proposing a patch.
+
+## Local Skill Versus Plugin Artifact
+
+Use a local managed skill when the workflow is personal, project-specific, unstable, or still pending validation.
+
+Use a managed overlay when an approved skill should be available to a local native host without changing shipped TraceDecay skills.
+
+Generate a Codex plugin artifact when an approved workflow is stable, shareable, and should travel with plugin metadata, native `skills/`, optional `.mcp.json`, optional hooks, and marketplace metadata.
+
+## Improvement Artifacts
+
+Every automation run that reaches backend validation should be able to produce a review chain:
+
+- traces
+- feedback
+- generated evals
+- validation gate
+- optimizer diagnosis
+- Codex handoff
+
+The handoff is the durable output for broader code or behavior changes. It must preserve approval gates and list validation requirements before any generated recommendation is applied.

docs/dashboard-port-handoff.md

@@ -54,7 +54,7 @@ that reuses it, never a fork.
                 └──────────────┬─────────────────────────────┘
             register via window.__HERMES_PLUGINS__ / SDK
            ┌───────────────────┴────────────────────────┐
-           │ standalone                                 │ hermes-hosted
+           │ standalone                                 │ delegated-host
 ┌──────────▼─────────────┐                 ┌────────────▼─────────────────┐
 │ shell/dist/shell.js    │                 │ hermes-wrapper dist/index.js │
 │ (bundles React 19,     │                 │ (uses host SDK; evaluates    │
@@ -138,7 +138,7 @@ Hermes `~/.hermes/memory_store.db` (`facts`/`entities`/`memory_banks`).
 | `GET /similarity` | pure-python `mean(cos(p_i−p_j))` + lexical overlap + classification | same math in Rust (`SIMILARITY_FACT_CAP` 500, identical thresholds) | working |
 | `GET /archive` / `POST /archive/{id}/restore` | `facts.state='archived'` / provider restore | **removed by design** — tracedecay curation hard-DELETEs losing facts; there is no archive state and no restore. The UI's Archive tab was removed accordingly. | n/a |
 | `GET /curation/status` | hermes curator state files | Returns `enabled:true`, `mode: similarity_dedup`, last preview timestamp | **working** |
-| `GET /curation/activity` | curator activity events | Always empty (no LLM/agent event stream) | working |
+| `GET /curation/activity` | curator activity events | Structured TraceDecay curation activity events from preview/apply, agent-plan, and automation paths (`queued`, `evidence`, `backend`, `validation`, `apply`, `report`, `finish`, `failure`, or `rejection` as applicable) | working |
 | `GET /curation/preview` | saved dry-run file | Last `dry_run=true` result, persisted to a `.tracedecay/dashboard/curation_preview.json` sidecar (survives restarts); stale when fact count changes | **working** |
 | `POST /curate` | `agent.memory_curator.run_memory_curation` | Similarity-based dedup: proposes/applies `delete` actions for `likely_duplicate` pairs; `dry_run=true` returns plan, `dry_run=false` hard-deletes losers via `MemoryStore::remove_fact` | **working** |
 | `POST /curate/apply` | (new, no Hermes equivalent) | Generic curation-ops apply API: `{"ops": [{"op":"delete",...} \| {"op":"merge",...}]}` with per-op results; the contract for external (LLM) planners | **working** |
@@ -302,17 +302,20 @@ each op is one of:
 Response: `{"results": [per-op result], "counts": {"deleted", "merged",
 "errors"}}`. Ids are validated per-op; partial failures are reported per-op
 (status stays 200), never as a whole-request 500. A 400 is returned only for a
-malformed body. This is the contract the Hermes wrapper's future LLM curation
-planner builds against.
+malformed body. Standalone automation backends and delegated host planners use
+this contract.
 
 ### Capabilities
 
-`GET /api/capabilities` returns `"curation": true, "llm_curation": false`
-(standalone). The Hermes wrapper flips `llm_curation` when it adds an
-LLM-backed planner that proposes merge/retag-style ops and applies them via
-`/curate/apply`. The UI's CurationPanel consumes the same ops shape either
-way (its Archive tab was removed; `delete` ops render as high-risk actions
-with a permanent-deletion warning).
+`GET /api/capabilities` returns `"curation": true` plus automation metadata.
+TraceDecay reports `automation.mode` as `"disabled"`, `"standalone_backend"`,
+or `"delegated_host"`. In standalone mode, a configured backend can set
+`features.llm_curation` true. In delegated-host mode, planning remains
+host-owned and the host submits proposed ops via `/curate/apply`; Hermes is one
+compatibility bridge for this provider-neutral contract. The UI's
+CurationPanel consumes the same ops shape either way (its Archive tab was
+removed; `delete` ops render as high-risk actions with a permanent-deletion
+warning).
 
 ### Hermes live render + holographic_plus retirement (2026-06-10)
 
@@ -514,9 +517,11 @@ conservatism backstop, and callers can pass a higher `threshold` /
 
 ## What's stubbed / known gaps
 
-1. **Curation activity stream**: `GET /curation/activity` always returns an empty
-   event list. The holographic_plus backend streams structured phases from a live
-   LLM agent run; the similarity-dedup implementation has no equivalent events.
+1. **Curation activity stream**: RESOLVED — `GET /curation/activity` returns the
+   in-memory structured activity log for preview/apply, standalone agent-plan,
+   and queued automation paths. Events use phases such as `queued`, `evidence`,
+   `backend`, `validation`, `apply`, `report`, `finish`, `failure`, and
+   `rejection` as applicable.
 2. **Rich curation ops**: the built-in planner only proposes `delete`. The apply
    API additionally executes `merge` (content rewrite + loser deletion), but
    `supersede`, `retag`, and `entity_*` ops from holographic_plus are not
@@ -640,7 +645,7 @@ cd /home/zack/projects/tracedecay
 cargo build --bin tracedecay
 ./target/debug/tracedecay dashboard            # http://127.0.0.1:7341/
 
-# 3. Hermes-hosted (wrapper spawns the server automatically)
+# 3. Delegated host (wrapper spawns the server automatically)
 TRACEDECAY_BIN=/home/zack/projects/tracedecay/target/debug/tracedecay \
 TRACEDECAY_DASHBOARD_PROJECT=/home/zack/projects/tracedecay \
 hermes dashboard   # → "TraceDecay" tab (named "Hermes Intelligence" at port time)