kodelyth-ecc 1.5.10 → 1.7.0

package/skills/observability-dashboard/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: observability-dashboard
+description: Localhost-only observability dashboard for Kodelyth ECC. Visualizes memory captures, BM25 search, evolve signals + proposals, full catalog browser, swarm sessions, and token-budget snapshots. Zero telemetry.
+trigger:
+  - dashboard
+  - observability
+  - kodelyth dashboard
+  - show me the memory
+  - browse skills
+  - inspect proposals
+  - what has ECC learned
+---
+
+# Skill: observability-dashboard
+
+A read-only HTTP server bound to `127.0.0.1` that renders a single-page UI over every local data source ECC produces. No build step, no external runtime dependencies, no telemetry, no network access required.
+
+## What you can see
+
+| Tab | Powered by | Shows |
+|---|---|---|
+| **Overview** | catalog + memory store + evolve store + .orchestration + token-budget | One-glance counts: agents, skills, commands, rules, bundles, captured memories, surfaces, routing misses, pending proposals, swarm sessions. Plus storage paths and token-budget snapshot. |
+| **Memory** | `scripts/memory/store.js` | Total / projects / language breakdown. Live BM25 search box (proxies `recall()`). Recent capture stream with tags + source. |
+| **Evolve** | `scripts/evolve/{stats,proposals}.js` | Top reused memories, top routing-miss clusters, every proposal with status pill. Tells you the exact CLI command to accept. |
+| **Catalog** | `scripts/mcp/catalog.js` | Browse + filter every shipped agent / skill / command / rule / bundle by name, description, or tag. |
+| **Sessions** | `.orchestration/<session>/` | Swarm session list with worker counts and per-worker drill-down (task.md / handoff.md / status.md excerpts). |
+
+## When to invoke
+
+Use **explicitly**:
+
+```bash
+use observability-dashboard
+
+# Boots on http://127.0.0.1:5747, auto-opens browser
+npx kodelyth-ecc dashboard
+
+# Custom port, suppress browser open
+npx kodelyth-ecc dashboard --port 8088 --no-open
+
+# Bind to a different localhost-aliased host
+npx kodelyth-ecc dashboard --host localhost
+```
+
+Implicit triggers (the AI should route here):
+
+- "show me the memory"
+- "what has ECC learned?"
+- "browse the skills"
+- "what's pending in evolve?"
+- "is there a UI for this?"
+- "open the dashboard"
+
+## CLI surface
+
+```
+kodelyth-ecc dashboard [--port N] [--host 127.0.0.1] [--no-open]
+```
+
+| Flag | Default | Behavior |
+|---|---|---|
+| `--port N` | `5747` | Port to bind. Picks a free port pattern. |
+| `--host H` | `127.0.0.1` | Bind interface. Refuses non-localhost without escape hatch. |
+| `--no-open` | off | Suppress browser auto-open (useful in remote shells / CI smoke). |
+
+### Localhost lock
+
+Binding to `0.0.0.0`, a public IP, or a non-localhost name is **refused** unless you explicitly set:
+
+```bash
+KODELYTH_DASHBOARD_ALLOW_REMOTE=1 \
+  npx kodelyth-ecc dashboard --host 0.0.0.0
+```
+
+This is intentionally noisy. The dashboard exposes everything the BM25 store and evolve log have ever recorded. Don't expose it to networks you don't fully control.
+
+## API surface (read-only, GET-only)
+
+The frontend is just a consumer of these endpoints. You can curl them directly:
+
+| Endpoint | Returns |
+|---|---|
+| `GET /api/health` | liveness probe |
+| `GET /api/overview` | counts + storage paths |
+| `GET /api/memory[?limit=N]` | stats + recent captures |
+| `GET /api/memory/search?q=…[&limit=N]` | BM25 results |
+| `GET /api/evolve[?limit=N]` | reuse + miss + proposals snapshot |
+| `GET /api/catalog?kind=…[&q=…&limit=N]` | agents \| skills \| commands \| rules \| bundles |
+| `GET /api/sessions[?limit=N]` | swarm session list |
+| `GET /api/sessions/:name` | worker details for one session |
+| `GET /api/token-budget` | per-session token usage |
+
+**Only `GET` is supported.** Any `POST`/`PUT`/`DELETE` returns `405 method not allowed`. The dashboard is a *strict observer* — it cannot mutate memories, accept proposals, or modify any state. All mutations stay in the CLI (`evolve accept`, `memory remember`, etc.).
+
+## Hard rules
+
+1. **NEVER expose remotely without explicit opt-in.** Default refuses everything except `127.0.0.1` / `localhost`.
+2. **NEVER write data.** GET-only routes. No mutation endpoints.
+3. **NEVER include external assets.** No CDNs, no fonts loaded over the network. Works offline.
+4. **NEVER swallow data-source failures with crashes.** A broken memory store or evolve dir renders empty cards, not a 500 page.
+5. **NEVER cache.** `Cache-Control: no-store` on every response — data is always fresh.
+6. **NEVER allow path traversal.** Static file resolution sandboxed under `scripts/dashboard/static/`.
+
+## Composition with other features
+
+| Pair with | Effect |
+|---|---|
+| **`/memory remember`** | New memories appear in the **Memory** tab on next refresh. |
+| **`kodelyth-ecc evolve analyze`** | New proposals appear in the **Evolve** tab as `pending`. |
+| **`kodelyth-ecc evolve accept`** | The status pill flips from `pending` → `accepted` after refresh. |
+| **`kodelyth-ecc swarm`** | New `.orchestration/<session>/` dirs surface in the **Sessions** tab. |
+| **token-budget hook** | Per-session token totals appear on the **Overview** tab. |
+
+## See also
+
+- `commands/dashboard.md` — `/dashboard` slash command
+- `docs/dashboard.md` — full reference + curl examples + architecture notes
+- `scripts/dashboard/{server,data}.js` — implementation
+- `scripts/dashboard/static/index.html` — single-page UI

package/skills/self-evolving-memory/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: self-evolving-memory
+description: Phase 3.4 — turn repeated memory hits and routing misses into proposed skill / routing-rule upgrades. Never auto-applies; produces PR-ready drafts the user reviews and commits.
+trigger:
+  - self-evolving memory
+  - skill proposals
+  - routing proposals
+  - memory feedback loop
+  - kodelyth evolve
+  - propose skill
+  - propose routing
+---
+
+# Skill: self-evolving-memory
+
+## What this skill does
+
+Closes the learning loop on the BM25 memory system. Two signals drive proposals:
+
+| Signal | Source | Outcome when threshold hit |
+|---|---|---|
+| **Memory reuse** | Auto-recall hook bumps a counter every time a memory is surfaced to the user | Propose **promoting the memory to a draft `SKILL.md`** |
+| **Routing miss** | Auto-recall hook logs substantive prompts where memory recall returned nothing | Propose **adding a routing entry** to `rules/common/agent-intent-routing.md` |
+
+Both proposals are written to a local proposal log. **Nothing is ever auto-applied.** The user reviews, accepts (which writes a draft file), edits, and commits.
+
+---
+
+## When to use this skill
+
+Use **explicitly** by name when:
+
+- You've been running ECC for weeks and want to surface what the toolkit has learned about your work.
+- A pattern keeps coming back in your sessions and you want to formalize it as a skill.
+- You suspect there's a gap in the routing rule (you keep getting the wrong agent for a class of prompts).
+- You want to inspect how the self-learning loop is doing without committing to anything.
+
+```bash
+use self-evolving-memory
+
+# See what signals have been collected
+npx kodelyth-ecc evolve stats
+
+# Generate proposals from current signals
+npx kodelyth-ecc evolve analyze
+
+# Review what's pending
+npx kodelyth-ecc evolve list
+
+# Inspect a specific proposal end-to-end (incl. proposed file content)
+npx kodelyth-ecc evolve show <proposalId>
+
+# Accept → writes a draft file. NEVER auto-commits.
+npx kodelyth-ecc evolve accept <proposalId>
+
+# Reject — appends a state event with optional note
+npx kodelyth-ecc evolve reject <proposalId> --note "covered by existing agent"
+```
+
+Implicit triggers (the AI should route here automatically):
+
+- "what has ECC learned from my sessions?"
+- "promote this memory to a skill"
+- "add this to the routing rule"
+- "what's missing from the routing intent rule?"
+
+---
+
+## CLI surface
+
+### `kodelyth-ecc evolve stats`
+
+Snapshot of currently recorded signals:
+
+- **Reuse:** memories tracked, total surfaces, top reused entries.
+- **Routing misses:** total misses, unique prompts, top clusters.
+
+### `kodelyth-ecc evolve analyze`
+
+Reads signals + your `~/.kodelyth/memory/` store, applies thresholds, and writes proposals to `~/.kodelyth/evolve/proposals.jsonl`. Idempotent — re-running with the same evidence produces the same proposal IDs and does NOT duplicate.
+
+| Flag | Default | Effect |
+|---|---|---|
+| `--reuse-min N` | 3 | Memory must have surfaced ≥ N times to be eligible |
+| `--reuse-min-sessions N` | 2 | …across ≥ N distinct sessions |
+| `--miss-min N` | 3 | A token cluster must have ≥ N total miss events |
+| `--miss-min-distinct N` | 2 | …with ≥ N distinct prompts |
+| `--json` | off | Stream the full report instead of the pretty summary |
+
+### `kodelyth-ecc evolve list [--status pending|accepted|rejected|applied]`
+
+Show proposals filtered by state. Proposals are append-only — every state change is a new event, full audit trail preserved.
+
+### `kodelyth-ecc evolve show <id>`
+
+Print the full proposed file content + evidence. **Always preview before accepting.**
+
+### `kodelyth-ecc evolve accept <id> [--root DIR] [--overwrite]`
+
+Writes the proposed `diff` to its `target_path` under `--root` (defaults to package root). **Refuses to overwrite an existing file** unless `--overwrite` is passed. After writing, marks the proposal `accepted` with the absolute `applied_path`.
+
+The user must still review the draft, edit, and commit. The CLI does not stage or commit anything.
+
+### `kodelyth-ecc evolve reject <id> [--note "..."]`
+
+Marks a proposal `rejected`. Optional `--note` is preserved for the audit trail.
+
+---
+
+## How signals are recorded
+
+The auto-recall hook (`hooks/memory/auto-recall.js`) does two things in addition to its normal job:
+
+1. **On a memory surface** — calls `evolve.recordSurface({ memoryId, sessionId, projectRoot })`. This bumps the per-memory counter in `~/.kodelyth/evolve/reuse.json`. Idempotent per `(memoryId, sessionId)` — you can't game the counter by surfacing the same memory ten times in one session.
+2. **On a substantive prompt with zero memory matches** — calls `evolve.recordRoutingMiss({ prompt, sessionId, projectRoot })`. Appends one line to `~/.kodelyth/evolve/routing-misses.jsonl`. The prompt is capped to 1000 chars and stored alongside its top tokens for clustering.
+
+Both calls are **fire-and-forget**: any error is swallowed silently. The hook NEVER blocks recall on stats failure.
+
+---
+
+## How proposals are generated
+
+`scripts/evolve/analyze.js` is pure, deterministic, no I/O.
+
+**Skill upgrade** — for every memory whose reuse meets thresholds, build a draft `SKILL.md` from the memory's problem / approach / tags / language. Target path: `skills/<slug>/SKILL.md`.
+
+**Routing addition** — cluster routing-miss entries by their top-K tokens (≥2-token overlap). For every cluster meeting thresholds, build a draft markdown block to add to `rules/common/agent-intent-routing.md`. Target path: the rule itself (the diff is meant to be merged in by hand under the right priority tier — the agent name in the draft is intentionally `TODO-agent`).
+
+Proposal IDs are deterministic over their evidence — the same evidence always produces the same ID, so re-running `analyze` does not duplicate.
+
+---
+
+## Hard rules
+
+1. **NEVER auto-apply.** `accept` writes a draft file. The user reviews, edits, and commits. No git operations.
+2. **NEVER overwrite by default.** `accept` refuses to clobber an existing file unless `--overwrite` is explicit.
+3. **NEVER block the recall hook.** All evolve recording is fire-and-forget with try/catch around every call.
+4. **NEVER auto-route to a `TODO-agent` proposal.** The routing-addition diff intentionally names `TODO-agent` so accepting it cannot accidentally flip routing behavior. The user must rename + place it under the right priority tier.
+5. **Idempotent IDs.** Re-running `analyze` does not duplicate proposals. Stable evidence → stable ID.
+6. **Append-only proposal log.** Every state change is a new event. Full audit trail preserved.
+
+---
+
+## Pairing with other ECC features
+
+| Pair with | What you get |
+|---|---|
+| **BM25 memory store** | Source of reuse signals. Without captured memories, this skill has nothing to learn from. |
+| **`/memory remember`** | Manual capture. Explicitly captured memories that get reused → skill proposals. |
+| **`rules/common/agent-intent-routing.md`** | The exact target for routing-addition proposals. |
+| **Phase 2.7 swarm** | Repeated swarm tasks that surface the same memories → those memories become skills the swarm can pick automatically. |
+| **Phase 2.8 replay** | Replay bundles can re-trigger reuse signals when the same memory is surfaced again. |
+| **Phase 2.10 token-budget hook** | Promoting memories → skills means cheaper recalls (skills are loaded once, memories are recalled per-prompt). |
+
+---
+
+## Storage layout
+
+```
+~/.kodelyth/evolve/
+├── reuse.json               # per-memory reuse counters
+├── routing-misses.jsonl     # append-only miss log
+└── proposals.jsonl          # append-only proposal events
+```
+
+Override with `KODELYTH_EVOLVE_DIR`. All zero telemetry. All local.
+
+---
+
+## See also
+
+- `commands/evolve.md` — `/evolve` slash command
+- `docs/evolve.md` — full reference + worked example
+- `scripts/evolve/{stats,analyze,proposals}.js` — pure-function implementation
+- `hooks/memory/auto-recall.js` — signal capture (Phase 3.4 augmentation)

package/skills/session-replay/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: session-replay
+description: Bundle, share, and re-run swarm sessions with optional variations (different harness, different agents, different base ref). Used for regression testing prompts, reproducible bug reports, A/B testing model versions, and post-mortems on swarm runs.
+origin: ECC
+---
+
+# Session Replay — Reproducible Swarm Runs
+
+Every swarm session writes to `<repo>/.orchestration/<session>/`. That directory is the **session record**: task prompts, agent handoffs, status markers. Replay turns it into a portable, re-runnable artifact.
+
+> Phase 2.8 of the [Devil Roadmap](../../README.md). Pairs with the swarm orchestrator (Phase 2.7), the cost-aware model router (Phase 2.4), and the token-budget safety hook (Phase 2.10).
+
+---
+
+## When to invoke
+
+Trigger this skill when the user wants to:
+
+- **Reproduce a swarm run** with different settings (different model, different agent, different base ref).
+- **Share a swarm result** with a teammate as a single JSON file (no need to ship a whole repo).
+- **Compare runs** — same task, two harnesses, side-by-side handoff diff.
+- **Regression-test prompts** — replay a known-good swarm against a new agent rev to see if quality regressed.
+- **Build a reproducible bug report** — bundle a buggy run and ship to maintainers.
+
+---
+
+## Three primitives
+
+### 1. Export a session
+
+```bash
+npx kodelyth-ecc session-export swarm-2026-05-10-4a \
+  --task "audit oauth flow for security regressions" \
+  --agents security-reviewer,code-reviewer,pair-programmer,tdd-guide \
+  --harness claude \
+  --out ~/Desktop/oauth-audit.bundle.json
+```
+
+The `--task` / `--agents` / `--harness` / `--base-ref` flags enrich the bundle's `meta` block for richer replays. They're optional — without them, the bundle still works but replays default to whatever the bundle's first worker hint reveals.
+
+### 2. Import a bundle
+
+```bash
+npx kodelyth-ecc session-import ~/Desktop/oauth-audit.bundle.json
+# or:
+npx kodelyth-ecc session-import oauth-audit.bundle.json --target /tmp/audit-restore --overwrite
+```
+
+Restores the bundle into a coordination directory. Useful for inspecting handoffs locally before replaying.
+
+### 3. Replay a session
+
+```bash
+# By bundle file
+npx kodelyth-ecc replay oauth-audit.bundle.json --execute
+
+# By session name (in current repo's .orchestration/)
+npx kodelyth-ecc replay swarm-2026-05-10-4a --execute
+
+# A/B variation: same task, different harness
+npx kodelyth-ecc replay oauth-audit.bundle.json --harness codex --execute
+
+# A/B variation: different agent set
+npx kodelyth-ecc replay oauth-audit.bundle.json \
+  --agents security-reviewer,supply-chain-auditor,prompt-injection-hunter \
+  --execute
+
+# Replay against new code
+npx kodelyth-ecc replay oauth-audit.bundle.json --base-ref refactor/oauth-rewrite --execute
+```
+
+Default mode is **dry-run**. Pass `--execute` to actually spawn worktrees + tmux + agents. The replay session is auto-named `<original>-replay-<n>` so it never collides with the source.
+
+---
+
+## Bundle format
+
+Single JSON file. Stable schema `kodelyth.session-bundle/v1`:
+
+```json
+{
+  "schema":      "kodelyth.session-bundle/v1",
+  "session":     "swarm-2026-05-10-4a",
+  "exported_at": "2026-05-10T17:30:00Z",
+  "exported_by": "kodelyth-ecc@1.7.0",
+  "meta": {
+    "task":     "audit oauth flow for security regressions",
+    "agents":   ["security-reviewer", "code-reviewer", "pair-programmer", "tdd-guide"],
+    "harness":  "claude",
+    "base_ref": "HEAD"
+  },
+  "workers": [
+    { "slug": "code-reviewer",     "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "pair-programmer",   "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "security-reviewer", "task": "...", "handoff": "...", "status": "..." },
+    { "slug": "tdd-guide",         "task": "...", "handoff": "...", "status": "..." }
+  ]
+}
+```
+
+Pure JSON. No archives, no binaries. Diff-friendly for git review of regression bundles.
+
+---
+
+## Replay variations matrix
+
+| Want to test | Flags |
+|---|---|
+| Same task, different model | `--harness claude` vs `--harness codex` (or use `KODELYTH_ROUTER_*` env vars) |
+| Same task, different agents | `--agents new1,new2,new3` |
+| Same task, new code | `--base-ref refactor-branch` |
+| Same task, custom session name | `--session my-replay-1` |
+| Inspect plan only | (default — dry-run prints plan) |
+| Just write coordination files | `--write-only` |
+| Full execute | `--execute` |
+
+---
+
+## Hard rules
+
+1. **Never replay with `--execute` without inspecting the dry-run first.** Worktrees mutate disk; bad replays waste storage.
+2. **Replays are auto-named** to avoid collisions. Don't manually reuse the origin name.
+3. **Bundles are public artifacts** — strip secrets from `task.md` / `handoff.md` before sharing externally. Use `opensource-sanitizer` if needed.
+4. **A/B comparisons require human review.** Never auto-pick a "winner" between two replays.
+
+---
+
+## Pairing with the rest of ECC
+
+| Pairs with | How |
+|---|---|
+| **2.7 swarm orchestrator** | Replay only works on swarm coordination dirs. The two ship together. |
+| **2.4 cost router** | Vary `KODELYTH_ROUTER_*` env vars across replays for A/B model tests. |
+| **2.10 token-budget hook** | Replays open new sessions with fresh budgets — no spillover from the origin. |
+| **2.5 MCP client mode** | Replays inherit the same MCP registry, so tool calls reproduce. |
+| **opensource-sanitizer** | Run on a bundle before sharing externally. |
+| **kodelyth-memory** | Capture the bundle path as a memory: `kodelyth-ecc remember "oauth audit replay" --approach "..."`. |
+
+---
+
+## Examples
+
+### Bug report bundle
+
+```bash
+# 1. Capture the buggy run
+npx kodelyth-ecc swarm --task "..." --execute
+
+# 2. After it finishes, export
+npx kodelyth-ecc session-export swarm-2026-05-10-4a --out bug-report.bundle.json
+
+# 3. Strip secrets if needed
+# (manually edit bug-report.bundle.json or use opensource-sanitizer)
+
+# 4. Ship to maintainers
+gh issue create --body "Reproducer: bug-report.bundle.json (attached)"
+```
+
+### Model A/B test
+
+```bash
+# Run with claude
+npx kodelyth-ecc swarm --task "refactor payments module" --agents 4 --harness claude --execute
+npx kodelyth-ecc session-export swarm-... --out claude-run.bundle.json
+
+# Replay with codex against the same task
+npx kodelyth-ecc replay claude-run.bundle.json --harness codex --execute
+npx kodelyth-ecc session-export swarm-...-replay-1 --out codex-run.bundle.json
+
+# Compare handoffs side-by-side
+diff <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' claude-run.bundle.json) \
+     <(jq -r '.workers[] | "\(.slug):\n\(.handoff)"' codex-run.bundle.json)
+```
+
+### Regression check after agent rev
+
+```bash
+# 1. Save a known-good run as a baseline.
+npx kodelyth-ecc session-export swarm-baseline --out baseline.bundle.json
+
+# 2. After updating an agent prompt, replay and compare.
+npx kodelyth-ecc replay baseline.bundle.json --execute
+npx kodelyth-ecc session-export swarm-baseline-replay-1 --out replay.bundle.json
+# Inspect the diff manually — has quality regressed?
+```
+
+---
+
+## Implementation references
+
+- Bundle library: `scripts/replay/bundle.js` (pure read/write, validation, diff helper).
+- Replay engine: `scripts/replay/replay.js` (extracts task from bundle, builds replay plan-config).
+- CLI: `npx kodelyth-ecc session-export | session-import | replay`.
+- Slash command: `/replay`.
+- Full reference: `docs/replay.md`.
+
+---
+
+Built into [Kodelyth ECC](../../README.md). MIT licensed.