kodelyth-ecc 1.5.9 → 1.7.0

package/.github/workflows/publish.yml

@@ -39,3 +39,22 @@ jobs:
         run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      # ── Phase 2.9: SLSA / SBOM ───────────────────────────────────────────
+      # npm publish above already issues SLSA Level 3 build provenance via
+      # npm's sigstore integration (--provenance). Below we additionally emit a
+      # CycloneDX SBOM and a content manifest, both attached to the release.
+      - name: Generate CycloneDX SBOM
+        run: node bin/kodelyth-ecc.js sbom --out kodelyth-ecc-sbom.cdx.json
+
+      - name: Generate content manifest
+        run: node bin/kodelyth-ecc.js manifest --out kodelyth-ecc-manifest.json
+
+      - name: Upload SBOM + manifest to the GitHub release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "$GITHUB_REF_NAME" \
+            kodelyth-ecc-sbom.cdx.json \
+            kodelyth-ecc-manifest.json \
+            --clobber

package/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This file is read by AI agents (Cascade, Cursor, Codex, etc.) on every session. It tells them how to work in this repo and how to use the 61 specialist agents and 188 skills shipped with Kodelyth ECC.
+This file is read by AI agents (Cascade, Cursor, Codex, etc.) on every session. It tells them how to work in this repo and how to use the 70 specialist agents and 194 skills shipped with Kodelyth ECC.
 
 ---
 

package/CHANGELOG.md

@@ -2,6 +2,461 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v1.7.0 — MCP SERVER: Universal adapter for any agent framework (May 2026)
+
+ECC is now consumable from Claude Desktop, LangGraph, AutoGen, CrewAI, OpenAI Agents SDK, Cursor, Windsurf, and any MCP-compatible client. Every framework that speaks Model Context Protocol can now route to ECC's 70 agents, 194 skills, 97 commands, and the local self-learning memory store.
+
+### New: MCP server (`npx kodelyth-ecc mcp`)
+
+A thin, stdio-only MCP server (Node, JSON-RPC) that exposes the full ECC stack:
+
+- **16 tools** — `route_intent`, `list_agents`, `list_skills`, `list_commands`, `list_rules`, `list_bundles`, `get_agent`, `get_skill`, `get_command`, `get_rule`, `get_bundle`, `recall_memory`, `capture_memory`, `memory_stats`, `catalog_stats`, `audit_skill_match`.
+- **6 prompts** — `routing-rule` (full 10-tier intent routing), `agents-overview`, `skills-overview`, `commands-overview`, `handoff-chains`, `devil-mode`.
+- **365 resources** — every agent, skill, command, rule, and bundle addressable via `kodelyth://agents/<name>`, `kodelyth://skills/<name>`, `kodelyth://commands/<name>`, `kodelyth://rules/<name>`, `kodelyth://bundles/<name>`. All `text/markdown`.
+
+Design principles:
+
+- **Pure file reads + memory passthrough.** Server adds zero LLM calls of its own.
+- **Local only.** stdio transport. No network egress. No telemetry.
+- **Optional dependency.** `@modelcontextprotocol/sdk` is in `optionalDependencies` — installs work without it; the `mcp` subcommand prints a friendly install hint if missing.
+- **Cached catalog.** Sub-millisecond catalog reads after first hit.
+- **Project-aware memory.** `recall_memory` accepts an optional `project_root` to scope BM25 results, falling back to global memories if scoped results are sparse.
+
+### New files
+
+- `scripts/mcp/server.js` — SDK wiring + stdio transport (lazy-loaded).
+- `scripts/mcp/tools.js` — 16 tool handlers + tool definitions.
+- `scripts/mcp/prompts.js` — 6 prompt definitions.
+- `scripts/mcp/resources.js` — 365-resource catalog with `kodelyth://` URIs.
+- `scripts/mcp/catalog.js` — read-only loader for agents/skills/commands/rules/bundles with minimal YAML frontmatter parser.
+- `docs/mcp.md` — full reference, client config snippets, design notes, troubleshooting.
+- `tests/mcp/catalog.test.js` — catalog loader + frontmatter parser (12 tests).
+- `tests/mcp/tools.test.js` — pure-function tool handlers including memory roundtrip (15 tests).
+- `tests/mcp/resources-prompts.test.js` — resource discovery + prompt rendering (8 tests).
+
+### Updated files
+
+- `bin/kodelyth-ecc.js` — `mcp` subcommand dispatch, help text updated.
+- `package.json` — `mcp` and `model-context-protocol` keywords, `optionalDependencies` for `@modelcontextprotocol/sdk@^1.0.4`, `npm run mcp` script.
+- `README.md` — new "MCP server" section under install options with Claude Desktop config snippet.
+
+### CLI surface
+
+```bash
+npx kodelyth-ecc mcp                         # start stdio MCP server
+npx kodelyth-ecc --help                      # mcp subcommand documented
+```
+
+### Test count
+
+47 → **82 tests** (added 35 MCP server tests). Final v1.7.0 count is **336 tests** — covering MCP server, model router, swarm orchestrator, session replay, supply-chain tooling, safety hooks, self-evolving memory, and the local observability dashboard.
+
+### Counts (post-1.7.0)
+
+| Asset            | Count |
+|------------------|-------|
+| Agents           | 70    |
+| Skills           | 194   |
+| Slash commands   | 97    |
+| Parallel commands| 8     |
+| Rules            | 14    |
+| Power bundles    | 3     |
+| MCP tools        | 16    |
+| MCP prompts      | 6     |
+| MCP resources    | 377   |
+| Hooks            | 22+ (incl. prompt-injection-guard + token-budget) |
+| Install targets  | 12    |
+| Tests            | 336   |
+
+### New: Local observability dashboard
+
+A localhost-only single-page web UI over every local data source ECC produces. Zero telemetry, zero external runtime dependencies, fully offline, read-only.
+
+Delivered surfaces:
+
+- **`scripts/dashboard/server.js`** — HTTP server using ONLY Node.js built-ins (`http`, `fs`, `path`, `child_process`). Eight JSON API routes + one static-file route. GET-only — any other method returns 405. Hardened response headers on every reply (`X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer`, `Cache-Control: no-store`). Path-traversal-safe static resolution sandboxed under `scripts/dashboard/static/`.
+- **`scripts/dashboard/data.js`** — pure aggregators across catalog, BM25 memory store, evolve signals + proposals, swarm/orchestration sessions, and token-budget hook state. Every read defensively wrapped — broken data sources render empty cards, never crash the dashboard.
+- **`scripts/dashboard/static/index.html`** — single-page UI. Hand-rolled CSS (no Tailwind, no CDN), vanilla JavaScript (`fetch`-only), no build step, no transpilation. Five tabs: Overview / Memory / Evolve / Catalog / Sessions. Lazy-loads each tab's data only when shown. 15-second health-ping pulses a green liveness indicator.
+- **`bin/kodelyth-ecc.js`** — new `dashboard` subcommand. `--port N`, `--host H`, `--no-open` flags. **Refuses to bind non-localhost without `KODELYTH_DASHBOARD_ALLOW_REMOTE=1`** — the escape hatch is intentionally noisy. Default port 5747. Auto-opens browser on macOS (`open`), Linux (`xdg-open`), Windows (`start`).
+- **`skills/observability-dashboard/SKILL.md`** + **`commands/dashboard.md`** + **`docs/dashboard.md`** — explicit-invocation skill, slash command, and full reference docs with curl examples.
+- **`tests/dashboard/{data,server}.test.js`** — 39 new tests. Aggregator tests cover overview shape, catalog filtering, session detail reading, token-budget JSON aggregation, malformed-input resilience. Server tests boot the real HTTP server on ephemeral ports and exercise every route + every security guardrail (POST blocked, bad-kind 400, path traversal blocked, hardened headers present, remote-bind refused, override env var honored).
+
+API surface (read-only, GET-only):
+
+```
+GET /api/health                            # liveness
+GET /api/overview                          # counts + storage paths
+GET /api/memory[?limit=N]                  # stats + recent captures
+GET /api/memory/search?q=…[&limit=N]       # BM25 search
+GET /api/evolve[?limit=N]                  # reuse + miss + proposals
+GET /api/catalog?kind=…[&q=…&limit=N]      # agents | skills | commands | rules | bundles
+GET /api/sessions[?limit=N]                # swarm session list
+GET /api/sessions/:name                    # one session, all workers
+GET /api/token-budget                      # per-session token usage
+```
+
+The frontend is a thin consumer of these. Anything the UI shows you can also pipe through `jq`:
+
+```bash
+curl -s http://127.0.0.1:5747/api/evolve | jq '.proposals[] | select(.status == "pending")'
+```
+
+Verified end-to-end: booted on an ephemeral port → 200 OK on every happy path → 400 on bad kind → 404 on unknown route → 405 on POST → hardened headers present on every response → remote bind to `0.0.0.0` refused with the documented error message → override env var allows it.
+
+Pairs with: BM25 memory store (Memory tab data source), swarm orchestrator (Sessions tab), token-budget hook (Overview budget snapshot), and self-evolving memory (Evolve tab). The Evolve tab makes the proposal state machine visible at a glance — status pills (⏸ ✓ ✗ ★) reflect the same state the CLI sees.
+
+### New: Self-evolving memory
+
+The BM25 memory system now closes its own learning loop. Repeated memory hits become draft skills. Repeated routing misses become proposed routing-rule additions. **Nothing is ever auto-applied** — the user reviews, accepts (writes a draft file to disk), edits, and commits.
+
+Delivered surfaces:
+
+- **`scripts/evolve/stats.js`** — pure record/read of two signal streams in `~/.kodelyth/evolve/`:
+  - `reuse.json` — per-memory surface counter, idempotent per (memoryId, sessionId), tracks distinct sessions + projects
+  - `routing-misses.jsonl` — append-only log of substantive prompts where memory recall returned zero matches; capped at 1000 chars per prompt
+- **`scripts/evolve/analyze.js`** — pure, deterministic, no I/O. Two analysis paths:
+  - reuse → skill-upgrade proposals (default thresholds: count≥3 AND sessions≥2)
+  - misses → routing-addition proposals (cluster by ≥2-token overlap; default thresholds: count≥3 AND distinct≥2)
+  - proposal IDs are deterministic over evidence → re-running `analyze` never duplicates
+- **`scripts/evolve/proposals.js`** — append-only proposal log with state transitions: `pending → accepted → applied` or `pending → rejected`. Full audit trail preserved (every state change is a new event). `applyProposalToDisk` refuses to overwrite without `--overwrite`.
+- **`hooks/memory/auto-recall.js`** — minimal augmentation. Two fire-and-forget calls: `recordSurface` when a memory is shown to the user, `recordRoutingMiss` when a substantive prompt yields zero matches. Both wrapped in try/catch — the hook NEVER blocks recall on stats failure.
+- **`bin/kodelyth-ecc.js`** — new `evolve` subcommand with six sub-actions: `stats`, `analyze`, `list`, `show`, `accept`, `reject`. All support `--json`. Accept refuses to clobber existing files unless `--overwrite` is explicit.
+- **`skills/self-evolving-memory/SKILL.md`** — explicit-invocation skill with full CLI reference, hard rules, composition matrix.
+- **`commands/memory-evolve.md`** — `/memory-evolve` slash command (avoids collision with the pre-existing `/evolve` command for `continuous-learning-v2`).
+- **`docs/evolve.md`** — full reference: signal definitions, threshold flags, proposal anatomy, sample diffs, worked example, hard rules.
+- **`tests/evolve/{stats,analyze,proposals}.test.js`** — 42 new tests. Cover counter idempotence per session, distinct-session bumping, project deduplication, miss aggregation by hash, prompt capping, threshold gating, deterministic IDs, cluster overlap rules, append-only audit trail across pending→rejected→accepted, overwrite refusal, malformed input rejection, and combined `analyzeAll` cross-stream output.
+
+Routing-addition diffs intentionally ship `TODO-agent` as the placeholder — even if accepted and committed verbatim, no real traffic gets routed until the user fills in the agent name. This is a deliberate safety property.
+
+Verified end-to-end: seeded a memory, surfaced it 4x across 4 sessions, logged 3 routing-miss prompts on a shared token cluster, ran `evolve analyze` → 2 proposals generated, `evolve accept` wrote the skill draft to disk + marked accepted, `evolve reject --note` recorded the routing rejection. Re-running `analyze` did not duplicate. Append-only log preserved every state event.
+
+CLI snapshot:
+
+```bash
+# After a few weeks of normal ECC usage:
+npx kodelyth-ecc evolve stats             # snapshot of recorded signals
+npx kodelyth-ecc evolve analyze            # signals → proposals (idempotent)
+npx kodelyth-ecc evolve list               # what's pending
+npx kodelyth-ecc evolve show <id>          # full draft + evidence
+npx kodelyth-ecc evolve accept <id>        # write draft to disk (NEVER commits)
+npx kodelyth-ecc evolve reject <id> --note "covered by existing agent"
+```
+
+Pairs with the BM25 memory store (signal source), `/memory remember` (manual capture), `rules/common/agent-intent-routing.md` (target for routing-addition proposals), swarm orchestrator (repeated swarm-task memories → skills the picker can choose), session replay (replay re-triggers reuse signals), and token-budget hook (skills are cheaper than per-prompt memory recalls).
+
+### New: Supply chain — SLSA + SBOM + content manifest
+
+Enterprise-grade supply-chain credentials. Every kodelyth-ecc release now ships with three independent attestations a downstream consumer can verify without trusting kodelyth-ecc:
+
+1. **SLSA Level 3 build provenance** — sigstore-signed via `npm publish --provenance`. Verifiable on npmjs.com and via `npm audit signatures`.
+2. **CycloneDX 1.5 SBOM** — `kodelyth-ecc-sbom.cdx.json`, attached to the GitHub release. Lists every component in `package-lock.json` with purl, license, and SHA-512 integrity.
+3. **sha256 content manifest** — `kodelyth-ecc-manifest.json`, attached to the GitHub release. Hashes every shipped asset (730 files) so any consumer can detect tamper.
+
+Delivered surfaces:
+
+- **`scripts/supply-chain/sbom.js`** — CycloneDX 1.5 generator. Pure function, zero deps. Reads `package.json` + `package-lock.json` v3. Stable `serialNumber` derived from `name@version + timestamp`. Components carry purl (`pkg:npm/...`), normalized license, and base64→hex SRI hashes.
+- **`scripts/supply-chain/manifest.js`** — deterministic content manifest. Walks `agents/`, `skills/`, `commands/`, `rules/`, `hooks/`, `scripts/`, `bin/`, `parallel-commands/`, `bundles/`, plus root files. Skips `node_modules/`, `.git/`, `.DS_Store`, `__pycache__/`, `*.pyc`. Top-level digest is sha256 over deterministic JSON of entries — reproducible.
+- **`scripts/supply-chain/verify.js`** — pure-function verifier. Categorizes every file into `ok / modified / missing / extra`. Modified or missing files fail verify; extras are advisory. Schema-versioned at `kodelyth.content-manifest/v1`.
+- **`bin/kodelyth-ecc.js`** — three new subcommands: `sbom [--out FILE] [--json]`, `manifest [--out FILE] [--json]`, `verify [--manifest FILE] [--json]`. `verify` exits 1 on any tamper.
+- **`.github/workflows/publish.yml`** — extended to emit the SBOM + manifest after `npm publish --provenance` and upload both to the GitHub release via `gh release upload`.
+- **`skills/supply-chain-verification/SKILL.md`** — explicit-invocation skill with full CLI reference, programmatic API, hard rules.
+- **`commands/verify-supply-chain.md`** — `/verify-supply-chain` slash command.
+- **`docs/supply-chain.md`** — full reference: artifact table, downstream verification flow, `npm audit signatures` integration, composition with other phases.
+- **`tests/supply-chain/sbom.test.js`** + **`tests/supply-chain/manifest.test.js`** + **`tests/supply-chain/verify.test.js`** — 31 new tests. Cover SBOM round-trip on synthetic + real lockfiles, scoped purl, SRI base64→hex, deterministic manifest digest, all four verify categories (ok/modified/missing/extra), schema validation, round-trip across copy.
+
+Verified end-to-end on the real repo: 730 files manifested, 91 SBOM components, full round-trip clean, single-byte tamper detected.
+
+CLI snapshot:
+
+```bash
+# Generate the three artifacts
+npx kodelyth-ecc sbom     --out kodelyth-ecc-sbom.cdx.json
+npx kodelyth-ecc manifest --out kodelyth-ecc-manifest.json
+
+# Verify a downstream install
+npx kodelyth-ecc verify --manifest kodelyth-ecc-manifest.json
+# → exit 0 if clean, exit 1 if any file is tampered or missing
+
+# CI-friendly
+npx kodelyth-ecc verify --manifest manifest.json --json | jq .ok
+```
+
+Pairs with swarm orchestrator (pre-flight verify), session replay (replay bundles can carry the producing toolkit's manifest digest), safety hooks (can warn on tampered toolkit), and the MCP server (can expose `verify` to downstream agents).
+
+### New: Session replay
+
+Every swarm coordination dir is now a portable, replayable artifact. Bundle a session into a single JSON file, ship it anywhere, re-run it with optional A/B variations (different harness, different agents, different base ref). Composes with swarm orchestrator and cost-aware model router for prompt regression testing and model A/B comparison.
+
+- **`scripts/replay/bundle.js`** — pure read/write of session bundles. Stable schema `kodelyth.session-bundle/v1`. Exports task/handoff/status per worker, validates on import, supports diff between two bundles, auto-generates `-replay-N` session names.
+- **`scripts/replay/replay.js`** — replay engine. Extracts shared task from bundle (prefers `meta.task`, falls back to parsing the worker's `## Shared Task` block, final fallback to orchestrator's `## Objective` block). Wires bundle + swarm builder + orchestrator with full variation support.
+- **`bin/kodelyth-ecc.js`** — three new subcommands: `session-export <session> [--task] [--agents] [--harness] [--base-ref] [--out]`, `session-import <bundle> [--target] [--overwrite]`, `replay <bundle|session> [--harness] [--agents] [--base-ref] [--session] [--replace] [--execute|--write-only|--json]`.
+- **`skills/session-replay/SKILL.md`** — explicit-invocation form with examples for bug-report bundles, model A/B tests, regression checks.
+- **`commands/replay.md`** — `/replay` slash command.
+- **`docs/replay.md`** — full reference: CLI commands, bundle format, replay reconstruction logic, variation matrix, hard rules, programmatic API.
+- **`tests/replay/bundle.test.js`** + **`tests/replay/replay.test.js`** — 27 new tests covering bundle round-trip, schema validation, diff correctness, import/overwrite semantics, replay name generation, task extraction (3 fallback paths), variation flags, and orchestrator integration.
+
+CLI snapshot:
+
+```bash
+# Export a finished swarm with rich meta
+npx kodelyth-ecc session-export swarm-2026-05-10-4a \
+  --task "audit oauth flow" \
+  --agents security-reviewer,code-reviewer,pair-programmer,tdd-guide \
+  --harness claude \
+  --out oauth-audit.bundle.json
+
+# Replay with a different harness (model A/B test)
+npx kodelyth-ecc replay oauth-audit.bundle.json --harness codex --execute
+
+# Replay with different agents
+npx kodelyth-ecc replay oauth-audit.bundle.json \
+  --agents supply-chain-auditor,prompt-injection-hunter,secret-hunter \
+  --execute
+
+# Replay against new code
+npx kodelyth-ecc replay oauth-audit.bundle.json --base-ref refactor/oauth-rewrite --execute
+```
+
+Replays auto-name as `<original>-replay-N` to never collide. Bundles are pure JSON — diff-friendly for regression review and shippable as bug-report artifacts.
+
+### New: Swarm orchestrator
+
+The generalized form of `/devil-mode`, `/team-review`, `/security-audit`, and `/pre-release`. Pick any task, pick any agents (or let ECC pick from task signals), get N parallel git-worktrees + a tmux session ready to attach. Promotes the existing `tmux-worktree-orchestrator` infrastructure to a first-class CLI surface.
+
+- **`scripts/swarm/build-plan.js`** — pure-function plan builder. Takes simple flags and produces a config compatible with the orchestrator. Smart agent picker: 14 signal classes (security, perf, API, tests, …), baseline anchors (code-reviewer + pair-programmer), 4/6/8-agent default rotations. Per-agent task shaping (required handoff sections).
+- **`bin/kodelyth-ecc.js`** — new `swarm` subcommand: `--task`, `--agents N|name1,name2,...`, `--harness claude|codex|opencode|windsurf|echo`, `--seed`, `--session`, `--base-ref`, `--replace`, `--execute`/`--write-only`/`--dry-run`/`--json`, plus power-user `--plan plan.json`.
+- **`skills/swarm-orchestrator/SKILL.md`** — explicit-invocation form; full pairing matrix with cost-router (2.4), token-budget hook (2.10), MCP client mode (2.5).
+- **`commands/swarm.md`** — `/swarm` slash command.
+- **`docs/swarm.md`** — full reference: CLI flags, smart agent picker, harness adapters, coordination protocol, lifecycle, troubleshooting.
+- **`tests/swarm/build-plan.test.js`** — 21 new tests covering pickAgents (signal-driven, baseline, rotation, dedup, count clamping), shapeTaskForAgent, buildWorker (4 harnesses + custom), buildSwarmPlan (validation, orchestrator integration, explicit agents preserved, full pass-through).
+
+CLI snapshot:
+
+```bash
+# Smart agent picking from signals:
+npx kodelyth-ecc swarm --task "audit oauth flow for security regressions" --agents 4
+# → picks security-reviewer + code-reviewer + pair-programmer + tdd-guide
+
+# Explicit agents:
+npx kodelyth-ecc swarm \
+  --task "ship v2.0" \
+  --agents release-captain,security-reviewer,e2e-runner \
+  --execute
+
+# Pre-launch full sweep:
+npx kodelyth-ecc swarm --task "Pre-launch sweep for v2.0" --agents 8 --replace --execute
+tmux attach -t swarm-2026-05-10-8a
+```
+
+Default mode is **dry-run** — prints a summary, doesn't spawn anything. `--write-only` materializes the coordination files (task.md / handoff.md / status.md per worker). `--execute` creates worktrees + tmux + launches agents with full rollback on failure.
+
+### New: MCP client mode
+
+The other half of MCP. While 2.1 serves ECC to any client, 2.5 lets ECC **consume** any external MCP server (Stripe, GitHub, Postgres, Redis, Brave, Filesystem, Shopify, anything). ECC is now the MCP **hub**.
+
+- **`scripts/mcp/client.js`** — registry + connect/list-tools/call-tool/list-resources/read-resource/list-prompts/get-prompt helpers. Lazy-loads `@modelcontextprotocol/sdk` with a friendly install hint if missing.
+- **`bin/kodelyth-ecc.js`** — five new subcommands: `mcp-add`, `mcp-list`, `mcp-remove`, `mcp-tools`, `mcp-resources`, `mcp-prompts`, `mcp-call`. JSON args via `--json '{"arg":"value"}'`. Env vars via `--env KEY=VAL`.
+- **`docs/mcp-clients.md`** — full reference, examples for github/postgres/stripe/brave/filesystem/redis, programmatic API, privacy notes, troubleshooting.
+- **`tests/mcp/client.test.js`** — 9 new tests including end-to-end stdio handshake using the LOCAL kodelyth MCP server itself as a real test target (registry persistence, addServer validation, listTools, callTool, listResources, listPrompts, error path).
+
+CLI snapshot:
+
+```bash
+# Register
+npx kodelyth-ecc mcp-add github \
+  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
+  -- npx -y @modelcontextprotocol/server-github
+
+# Inspect
+npx kodelyth-ecc mcp-list
+npx kodelyth-ecc mcp-tools github
+
+# Call
+npx kodelyth-ecc mcp-call github create_issue \
+  --json '{"owner":"sifxprime","repo":"kodelyth-ecc","title":"hi from ECC"}'
+```
+
+The registry lives at `~/.kodelyth/mcp-clients.json` (override with `KODELYTH_MCP_CLIENT_DIR`). Each call spawns a fresh stdio subprocess — no long-lived process pool, no credential leakage between sessions.
+
+### New: Cost-aware model router
+
+The orthogonal companion to agent intent routing. While intent routing picks _which specialist agent_ handles a task, this router picks _which model tier_ runs it — keeping teams from burning frontier-model tokens on doc typos and rename refactors.
+
+- **`rules/common/cost-aware-model-routing.md`** — always-on rule. Three tiers (trivial/standard/hard) with weighted signal classification. Hard rules: security/incident/adversarial agents never downgrade; production framing wins; multi-file (3+) refactors never go to trivial; respect explicit user choice; bias downward when token-budget > 70%.
+- **`skills/cost-aware-model-routing/SKILL.md`** — explicit-invocation form for "what model should I use" questions.
+- **`commands/route-model.md`** — `/route-model` slash command for ad-hoc on-demand routing.
+- **`scripts/router/classify.js`** — pure-function deterministic classifier with full config loader (env vars + `.kodelyth/router.json` project file).
+- **`bin/kodelyth-ecc.js`** — new `route` CLI subcommand: `npx kodelyth-ecc route "<task>" [--files N] [--agent <name>] [--current <model>] [--json]`.
+- **`tests/router/classify.test.js`** — 19 new tests covering classification, config precedence (env > project file > defaults), agent override, and disabled-mode.
+
+Configuration surface:
+
+```bash
+# Disable entirely
+KODELYTH_ROUTER=off
+
+# Override per tier (provider-agnostic)
+KODELYTH_ROUTER_TRIVIAL=gpt-4.1-mini
+KODELYTH_ROUTER_STANDARD=claude-sonnet-4-6
+KODELYTH_ROUTER_HARD=gpt-5
+
+# Or via .kodelyth/router.json at project root
+{ "trivial": "...", "standard": "...", "hard": "...", "notes": "set by infra team" }
+```
+
+Pairs with the `token-budget` safety hook for full cost discipline (the hook caps total spend; the router cuts the steady leak from frontier-model overuse on routine work). Together they typically reduce LLM bills by 50–70% with no measurable quality drop on standard tasks.
+
+### New: Safety hooks
+
+Two production-ready safety primitives that ride on the existing hook pipeline. **Off by default** — opt in via env vars so existing users see zero behavior change.
+
+- **`hooks/safety/prompt-injection-guard.js`** — scans inbound text on `UserPromptSubmit` and `PostToolUse` (Read, WebFetch, mcp__*) for jailbreak / instruction-override patterns. Three modes: `off` (default), `warn`, `block`. Detects 11 pattern classes across 3 severity tiers (critical / high / medium) plus base64-decoded payload jailbreak detection. Configurable audit log at `KODELYTH_PI_GUARD_LOG`.
+- **`hooks/safety/token-budget.js`** — per-session token-budget enforcer on `SessionStart` and `Stop`. Tracks usage via 4-chars-per-token heuristic over transcript size + visible message lengths. Three modes: `off` (default), `warn`, `<positive integer>`. Blocks `SessionStart` once usage ≥ budget; warns at 70%. State files live at `${KODELYTH_TOKEN_BUDGET_DIR}/budget-<sessionId>.json`.
+- **`hooks/safety/lib/patterns.js`** — shared, auditable regex pattern catalog. 11 named patterns + decoded base64 probe.
+- **`hooks/safety/README.md`** — full configuration + rollout guide.
+- **`tests/safety/*.test.js`** — 29 new tests covering pattern detection, hook block/warn/off paths, malformed JSON recovery, and reset flow.
+
+Both hooks always exit 0 on internal errors so they never block users due to a bug.
+
+### Test count
+
+47 → **336 tests** (added 35 MCP server + 9 MCP client + 29 safety + 19 router + 21 swarm + 27 replay + 31 supply-chain + 42 self-evolving memory + 39 dashboard + 37 from prior phases). All pass.
+
+### What shipped in v1.7.0
+
+- ✅ Devil-mode adversarial agents (8 agents + `/devil-mode` command)
+- ✅ MCP server (16 tools, 6 prompts, 370+ resources)
+- ✅ Local observability dashboard
+- ✅ Cost-aware model router
+- ✅ MCP client mode (consume external MCP servers)
+- ✅ Swarm orchestrator (parallel agents in git worktrees)
+- ✅ Session replay + portable bundles
+- ✅ SLSA L3 + SBOM + content manifest
+- ✅ Safety hooks (prompt-injection-guard + token-budget)
+- ✅ Self-evolving memory (proposals from usage patterns)
+- ✅ Power bundles (indie-hacker / red-team / enterprise)
+- ✅ GitHub Action (CI/CD PR review integration)
+- ✅ 5 new IDE platforms (Cline, Roo Code, Aider, Kimi, Gemini CLI)
+- ✅ README rewrite (infrastructure-first framing)
+
+---
+
+## v1.6.0 — DEVIL MODE: Adversarial agent crew + `/devil-mode` parallel sweep (May 2026)
+
+This release introduces the 8-agent adversarial red-team crew, a new parallel command that fires four of them in one shot, power bundles, and 5 new IDE platform targets.
+
+### New Agents (8 — adversarial / red-team mindset)
+
+Each ships with a full attacker-mindset playbook, real bash-grep patterns, severity calibration, and remediation steps. Not theatrical personas — they do real audit work.
+
+- **`prompt-injection-hunter`** — adversarial AI safety auditor. Hunts jailbreaks, indirect injection, system-prompt leaks, tool-call hijacking. Probes RAG pipelines, MCP servers, and any code that feeds untrusted text into an LLM.
+- **`supply-chain-auditor`** — dependency attacker review. Detects typosquats, malicious post-install scripts, lockfile drift, slopsquats (AI-generated phantom packages), tarball-vs-repo divergence.
+- **`secret-hunter`** — leaked-credential detective. Scans live code, git history, env files, build artifacts, CI logs, encoded blobs (base64/hex), and bundled-to-client env vars. Includes provider pattern catalog (AWS, Stripe, GitHub, Slack, JWT, etc.) and key-validity probing.
+- **`license-violation-finder`** — IP / copyleft contamination auditor. Hunts GPL/AGPL deps in proprietary code, missing attributions, license cocktails, license changes between versions (Elastic/Mongo/HashiCorp pattern), AI-generated code with copyleft training data.
+- **`jailbreak-tester`** — live AI-feature red-teamer. 10-tier attack battery: surface filter bypass, fictional framing, instruction-following hijack, system-prompt extraction, encoded payloads, tool abuse, multi-turn drift, overrefusal probing, PII exfil, output-channel abuse.
+- **`code-stealer-detector`** — code-provenance auditor. Hunts copy-pasted Stack Overflow snippets, copyleft contamination, leaked private code, AI-generated code with unverified provenance, vendored libs without attribution, embedded encoded blobs.
+- **`backdoor-hunter`** — malicious-code-pattern detector. 12 hunt categories: obfuscated execution, network beacons, time bombs (xz utils CVE-2024-3094 pattern), reverse shells, credential exfiltration, build-time injection, webshells, dynamic loading, cryptominers, telemetry exfil.
+- **`chaos-engineer`** — adversarial reliability tester. Hypothesis-first fault injection: process death, network partition, latency injection, DNS failure, disk full, clock skew, memory pressure, dependency failure, concurrency abuse, input fuzzing. Includes pre-flight checklist + abort criteria for safe execution.
+
+### New Parallel Command
+
+- **`/devil-mode`** — fires `prompt-injection-hunter` + `supply-chain-auditor` + `secret-hunter` + `backdoor-hunter` simultaneously. The "attacker mindset on the whole codebase" sweep.
+  - `/devil-mode --all` — fires all 8 adversarial agents
+  - `/devil-mode --pre-public` — pre-open-source sweep (adds license + theft check)
+  - `/devil-mode --pre-launch` — pre-launch sweep (adds AI red-team + chaos planning)
+
+### Intent Routing Updates
+
+- Added a new "Devil-Mode Adversarial Crew" section under Priority 3 with intent patterns for all 8 agents
+- Added `/devil-mode` to the parallel commands section with full trigger matrix
+- Added 11 new rows to the Quick Reference Table covering attacker-mindset phrasings ("think like an attacker", "going open-source full audit", "we were hacked", etc.)
+- Users can now route to any devil-mode agent or command in plain language without remembering names
+
+### Power Bundles
+
+Three audience-tailored bundles installable via `--bundle` flag. Each installs the full ECC toolkit + a curated `BUNDLE.md` cheat sheet that biases the AI toward workflows fit for that audience.
+
+```bash
+npx kodelyth-ecc --bundle indie-hacker    # Solo founder / SaaS — ship fast, validate, harden
+npx kodelyth-ecc --bundle red-team        # Security engineer — devil-mode + adversarial workflows
+npx kodelyth-ecc --bundle enterprise      # Compliance team — SBOM, license, supply chain
+```
+
+- New files: `bundles/indie-hacker.md`, `bundles/red-team.md`, `bundles/enterprise.md`
+- `install.sh` and `install.ps1` accept `--bundle` / `-Bundle` flag, both with full alias support (`indie`, `redteam`, `security`, `compliance`)
+- Bundle pre-selects sensible language modules (`typescript+python` for indie/red-team, `typescript+java+python` for enterprise)
+- `BUNDLE.md` is copied to install destination so the AI reads it on every session start
+- Bundle name persisted in `kodelyth-ecc-install-state.json`
+- Bundle-specific reminder displayed at install end with the right lead-with commands
+
+### New IDE Platforms
+
+ECC now installs natively to **5 additional AI coding platforms**, closing the platform-coverage gap with `agency-agents` and unlocking new communities:
+
+```bash
+npx kodelyth-ecc --target cline             # Cline (VS Code) — .clinerules/
+npx kodelyth-ecc --target roocode           # Roo Code (VS Code) — .roo/
+npx kodelyth-ecc --target aider             # Aider terminal agent — .aider-ecc/ + CONVENTIONS.md
+npx kodelyth-ecc --target kimi              # Kimi Code — .kimi/
+npx kodelyth-ecc --target gemini-project    # Gemini CLI (project) — .gemini/
+npx kodelyth-ecc --target gemini-home       # Gemini CLI (global) — ~/.gemini/
+```
+
+Per-target install layouts:
+
+| Target | Destination | Layout |
+|---|---|---|
+| `cline` | `./.clinerules/` | Flat: rules + agents + commands all merged as `.md` |
+| `roocode` | `./.roo/` | Subdirs: `rules/`, `agents/`, `skills/`, `commands/` |
+| `aider` | `./.aider-ecc/` + `./CONVENTIONS.md` | Subdirs + auto-generated CONVENTIONS.md if missing |
+| `kimi` | `./.kimi/` | Subdirs: `rules/`, `agents/`, `skills/`, `commands/` |
+| `gemini-project` | `./.gemini/` + `GEMINI.md` | Subdirs: `agents/`, `skills/`, `rules/` |
+| `gemini-home` | `~/.gemini/` + `GEMINI.md` | Same as above, global |
+
+Each target writes a tailored "what to do now" message at install end, and Aider/Gemini get auto-generated bootstrap files (`CONVENTIONS.md`, `GEMINI.md`) that their CLIs auto-load.
+
+Total IDE coverage jumps from **6** to **11** platforms — making ECC easily the most cross-platform AI coding toolkit shipped.
+
+### README Rewrite
+
+- Sharper "Why ECC ≠ Another Agent Collection" hero anchored on the **infrastructure thesis** (layered stack vs flat agent folders)
+- New **Layer Stack** table showing what each layer does and how it's missing from competitors
+- New **Quick Comparison vs Other Kits** table — 13 rows comparing ECC against `agency-agents`, `awesome-claude-agents`, generic prompt libs
+- New **Devil Mode** showcase block in hero
+- New **Power Bundles** section under Install
+- "What's Inside" updated to v1.6.0 counts + new Parallel Commands row
+
+### Counts
+
+| Metric | v1.5.10 | v1.6.0 |
+|---|---|---|
+| Agents | 62 | **70** |
+| Commands | 90 | **91** |
+| Parallel commands | 7 | **8** |
+| Power bundles | 0 | **3** |
+| Audience-tailored installs | 0 | **3** |
+| IDE platform targets | 7 | **13** (added cline, roocode, aider, kimi, gemini-project, gemini-home) |
+| IDE platform families | 6 | **11** |
+
+### What shipped in v1.6.0
+
+- 8 adversarial devil-mode agents (prompt-injection-hunter, supply-chain-auditor, secret-hunter, license-violation-finder, jailbreak-tester, code-stealer-detector, backdoor-hunter, chaos-engineer)
+- `/devil-mode` parallel command — attacker-mindset sweep with `--all`, `--pre-public`, `--pre-launch` variants
+- 3 power bundles (`indie-hacker`, `red-team`, `enterprise`) installable via `--bundle` flag
+- 6 new IDE platform targets (cline, roocode, aider, kimi, gemini-project, gemini-home)
+- Revamped README with comparison table and Layer Stack section
+- Full intent routing for all 8 devil-mode agents in plain language
+
+---
+
+## v1.5.10 — Fix install crash on macOS bash 3.2 (May 2026)
+
+### Bug Fix
+
+- **`install.sh` crashes after Rules (common) on `claude-home` target** — `set -euo pipefail` + bash 3.2 (macOS default) treats an empty array `"${LANGUAGE_MODULES[@]}"` as an unbound variable and exits. Fixed by using the bash 3.2-safe empty-array expansion `"${LANGUAGE_MODULES[@]+"${LANGUAGE_MODULES[@]}"}"`, matching the pattern already correctly used for the JSON install state on line 430. Users who install without any `--profile` or language flags (the majority) were affected.
+
+---
+
 ## v1.5.9 — Intent routing for all 5 parallel commands (May 2026)
 
 ### Bug Fix / Feature

package/CLAUDE.md

@@ -6,24 +6,27 @@ Guidance for Claude Code when working with this repository.
 
 **Kodelyth ECC** — a production-grade AI coding toolkit:
 
-- **62 specialist agents** — debug-detective, incident-commander, load-tester, image-architect, kodelyth-memory, security-reviewer, etc.
-- **188 skills** — domain knowledge, patterns, testing, security, intent routing, local memory
-- **88 commands** — slash workflows (`/tdd`, `/plan`, `/code-review`, `/team-review`, `/project-launch`, `/debug-blitz`, `/security-audit`, ...)
-- **20+ hooks** — automated quality gates, session memory, memory inject + capture, correction encoding
-- **17 rules** — always-on coding standards + semantic intent routing + memory protocol
+- **70 specialist agents** — debug-detective, incident-commander, load-tester, image-architect, kodelyth-memory, security-reviewer, plus 8 adversarial devil-mode agents
+- **194 skills** — domain knowledge, patterns, testing, security, intent routing, local memory, swarm orchestration, MCP integration
+- **97 commands** — slash workflows (`/tdd`, `/plan`, `/code-review`, `/team-review`, `/devil-mode`, `/debug-blitz`, `/security-audit`, ...)
+- **22+ hooks** — quality gates, memory inject + capture, correction encoding, prompt-injection guard, token-budget enforcer
+- **14 rules** — always-on coding standards + semantic intent routing + memory protocol + self-improvement
 
-Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, and OpenCode.
+Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, OpenCode, Cline, Roo Code, Aider, Kimi, and Gemini CLI — **12 platforms total**.
 
 ## Architecture
 
 ```
-agents/      → Specialist subagents (planner, code-reviewer, debug-detective, ...)
-skills/      → Workflow + domain knowledge files (loadable via slash commands)
-commands/    → Slash commands users invoke directly
-hooks/       → Trigger-based automations (pre-commit, session memory, etc.)
-rules/       → Always-on guidelines including agent-intent-routing.md
-scripts/     → Cross-platform Node.js utilities for hooks and setup
-tests/       → Test suite for scripts and hooks
+agents/      → 70 specialist subagents (planner, code-reviewer, debug-detective, devil-mode crew, ...)
+commands/    → 97 slash commands (8 parallel multi-agent, rest single-agent)
+skills/      → 194 workflow + domain knowledge files (loadable via slash commands)
+hooks/       → 22+ automations (pre-commit, session memory, prompt-injection guard, token-budget)
+rules/       → 14 always-on guidelines (agent-intent-routing, self-improvement, memory-protocol, ...)
+scripts/     → Node.js utilities: MCP server, dashboard, swarm, replay, router, memory, supply-chain
+bundles/     → 3 power bundles (indie-hacker, red-team, enterprise)
+actions/     → GitHub Action (CI/CD integration for PR review)
+docs/        → Feature docs (mcp.md, dashboard.md, swarm.md, replay.md, evolve.md, supply-chain.md)
+tests/       → 336 passing tests across 24 test files
 ```
 
 ## Running Tests
@@ -34,7 +37,25 @@ npm test
 node tests/run-all.js
 ```
 
-## Intent Routing (v1.3.0+)
+## CLI Subcommands
+
+Beyond install, the `npx kodelyth-ecc` CLI exposes:
+
+```bash
+npx kodelyth-ecc mcp                          # Start MCP server (stdio JSON-RPC)
+npx kodelyth-ecc route "<task>"               # Cost-aware model-tier recommendation
+npx kodelyth-ecc swarm --task "..."           # Parallel agents in git worktrees
+npx kodelyth-ecc dashboard                    # Localhost observability dashboard
+npx kodelyth-ecc evolve analyze               # Self-evolving memory proposals
+npx kodelyth-ecc replay <bundle>              # Re-run a past session
+npx kodelyth-ecc sbom                         # CycloneDX 1.5 SBOM
+npx kodelyth-ecc manifest                     # sha256 content manifest
+npx kodelyth-ecc verify                       # Verify install against manifest
+npx kodelyth-ecc mcp-add <name> -- <cmd>      # Register external MCP server
+npx kodelyth-ecc session-export <session>     # Export session bundle
+```
+
+## Intent Routing
 
 The toolkit ships with a god-tier intent routing rule (`rules/common/agent-intent-routing.md`) that auto-loads on every session. It maps user intent → specialist agent across 10 priority tiers.
 
@@ -47,7 +68,7 @@ When a user message matches a routing pattern, you MUST:
 
 ## Parallel Commands (Fastest Paths — Multi-Agent)
 
-These fire multiple specialist agents simultaneously. Use these for the fastest results:
+These fire multiple specialist agents simultaneously:
 
 | Command | Agents Fired | Best For |
 |---|---|---|
@@ -58,6 +79,7 @@ These fire multiple specialist agents simultaneously. Use these for the fastest
 | `/refactor-sprint` | refactor-cleaner + code-simplifier + type-design-analyzer + tdd-guide | Full cleanup before a feature sprint |
 | `/pre-release` | release-captain + security-reviewer + code-reviewer | Go/no-go verdict before shipping |
 | `/onboard` | code-explorer + architect + doc-updater | Understand any codebase in 15 minutes |
+| `/devil-mode` | prompt-injection-hunter + supply-chain-auditor + secret-hunter + backdoor-hunter | Adversarial sweep (use `--all` for all 8) |
 
 ## Key Commands
 
@@ -68,6 +90,10 @@ These fire multiple specialist agents simultaneously. Use these for the fastest
 - `/code-review` — quality review
 - `/git-mastery` — git workflows + recovery patterns
 - `/observability` — logging, metrics, OpenTelemetry, SLOs
+- `/dashboard` — launch local observability dashboard
+- `/route-model` — cost-aware model selection
+- `/swarm` — parallel agent swarm in git worktrees
+- `/memory-evolve` — self-evolving memory proposals
 
 ## Specialist Agents (Pick the Right One)
 
@@ -91,14 +117,20 @@ These fire multiple specialist agents simultaneously. Use these for the fastest
 | Tests / coverage | `tdd-guide` |
 | Refactor / cleanup | `refactor-cleaner` |
 | Open-source a project | `opensource-forker` (chain start) |
+| Leaked secrets in code/history | `secret-hunter` |
+| Malicious deps / supply chain | `supply-chain-auditor` |
+| AI feature jailbreak safety | `prompt-injection-hunter` |
+| Backdoors / obfuscated code | `backdoor-hunter` |
+| Chaos / fault injection testing | `chaos-engineer` |
 
 ## Development Notes
 
 - Package manager detection: npm, pnpm, yarn, bun
 - Cross-platform: Windows (`install.ps1`), macOS / Linux (`install.sh`), or `npx` anywhere
-- Agent format: Markdown with YAML frontmatter (name, description, tools)
+- Agent format: Markdown with YAML frontmatter (name, description, tools, model)
 - Skill format: Markdown with clear sections (description, when to use, how it works)
 - Hook format: JSON with matcher conditions and command/notification hooks
+- No runtime deps in core — `@modelcontextprotocol/sdk` is an optionalDependency for MCP server only
 
 ## Contributing