kodelyth-ecc 1.5.9 → 1.7.0

package/commands/replay.md

@@ -0,0 +1,61 @@
+---
+description: Replay a finished swarm session — same task, optional A/B variations (different harness, agents, base ref).
+argument-hint: "[bundle.json|session-name] [--harness h] [--agents a,b] [--base-ref ref] [--execute]"
+---
+
+# /replay
+
+Re-run a completed swarm session for regression testing, A/B comparison, or post-mortem analysis.
+
+## Quick examples
+
+```
+/replay swarm-2026-05-10-4a
+/replay oauth-audit.bundle.json --execute
+/replay swarm-2026-05-10-4a --harness codex --execute
+/replay oauth-audit.bundle.json --agents security-reviewer,supply-chain-auditor --execute
+/replay swarm-baseline --base-ref refactor-branch --execute
+```
+
+## Behavior
+
+By default, prints the dry-run plan. Add `--execute` to actually create worktrees, spawn the tmux session, and launch agents. The replay session is auto-named `<original>-replay-<n>` so it never collides with the source.
+
+| Flag | Effect |
+|---|---|
+| `<target>` | Required. Either a bundle file path (`*.json`) or a session name in `.orchestration/`. |
+| `--harness <h>` | Override the launcher harness (claude / codex / opencode / windsurf / echo). |
+| `--agents a,b,c` | Replace the original agent list. |
+| `--base-ref <ref>` | Branch base for replay worktrees (default: from bundle.meta or HEAD). |
+| `--session <name>` | Override the auto-generated `-replay-N` suffix. |
+| `--replace` | Tear down any existing session/worktrees with the same names. |
+| `--execute` | Spawn worktrees + tmux + launch agents. |
+| `--write-only` | Just materialize coordination files. |
+| `--json` | Print the full plan + planConfig as JSON. |
+
+## Use cases
+
+- **Regression test prompts** — capture a baseline, replay after agent rev, compare handoffs.
+- **Reproducible bug reports** — bundle a buggy session, ship to maintainers, they can `replay --execute` locally.
+- **Model A/B test** — same task, two harnesses, side-by-side handoff diff.
+- **Re-test against new code** — `--base-ref refactor-branch` re-runs the same audit on the new code.
+- **Post-mortem** — replay an incident response swarm with new agents to see what they would have caught.
+
+## Companion commands
+
+- `/session-export <name>` — export a coordination dir as a bundle JSON.
+- `/session-import <bundle>` — restore a bundle into `.orchestration/`.
+
+## Hard rules
+
+- Never `--execute` without dry-running first.
+- Bundles are public artifacts — strip secrets before sharing externally.
+- A/B comparisons require human review; never auto-pick winners.
+
+## Implementation
+
+- Skill: `session-replay`
+- Bundle library: `scripts/replay/bundle.js`
+- Replay engine: `scripts/replay/replay.js`
+- CLI: `npx kodelyth-ecc replay`
+- Full docs: `docs/replay.md`

package/commands/route-model.md

@@ -0,0 +1,48 @@
+---
+description: Recommend the right model tier (trivial/standard/hard) for the current task. Surfaces the cost-aware-model-routing rule on demand.
+argument-hint: "[task description]"
+---
+
+# /route-model
+
+Get an immediate model-tier recommendation for the current task. Combines the `cost-aware-model-routing` rule, the project's `.kodelyth/router.json` config, and the active session's token-budget pressure.
+
+## Usage
+
+```
+/route-model
+/route-model rename getUserName to getUserDisplayName
+/route-model audit the new oauth flow for vulnerabilities
+/route-model devil-mode adversarial sweep on the payments module
+```
+
+If you don't pass a task, the AI infers it from the most recent user turn.
+
+## What you get back
+
+A single, scannable block:
+
+```
+[model-router] task=<tier> · suggested=<model-id> · current=<active>
+  why: <one-line reason>
+  next: <how to switch>
+```
+
+If you're already on the right tier, the AI routes silently and confirms in one line.
+
+## Behind the scenes
+
+- Pure deterministic classifier (no LLM call) at `scripts/router/classify.js`.
+- Project config: `.kodelyth/router.json` (override per team).
+- Env-var overrides: `KODELYTH_ROUTER_{TRIVIAL,STANDARD,HARD,DEFAULT}`.
+- Disable with `KODELYTH_ROUTER=off`.
+- Pairs with the `token-budget` safety hook for spend control.
+
+## Hard rules
+
+- Security / incident / adversarial agents never downgrade.
+- Production framing ("down", "leaking", "outage") → hard tier.
+- Multi-file refactors (3+) never go to trivial.
+- Respect explicit user model choices unless new signals conflict.
+
+See: `rules/common/cost-aware-model-routing.md`, `skills/cost-aware-model-routing/SKILL.md`.

package/commands/swarm.md

@@ -0,0 +1,68 @@
+---
+description: Spawn N specialist agents in parallel inside isolated git worktrees + a tmux session. Generalized /devil-mode.
+argument-hint: "[task description] [--agents N|name1,name2,...] [--harness claude|codex|opencode|windsurf]"
+---
+
+# /swarm
+
+Run a parallel team of ECC specialists on the same task in isolated git worktrees coordinated by a tmux session. The generalized form of `/devil-mode`, `/team-review`, `/security-audit`, and `/pre-release` — pick any task, pick any agents, get N panes ready to attach.
+
+## Quick examples
+
+```
+/swarm audit oauth flow for security regressions
+/swarm ship v2.0 --agents release-captain,security-reviewer,e2e-runner --execute
+/swarm refactor payments module --agents 6 --harness codex --execute
+/swarm production is down, auth service 502s --agents incident-commander,debug-detective,silent-failure-hunter --execute
+```
+
+## Behavior
+
+By default, prints the dry-run plan (safe to inspect). Add `--execute` to actually create worktrees, spawn the tmux session, and launch agents.
+
+| Flag | Effect |
+|---|---|
+| `--task "..."` | Required (or use `--plan plan.json`). |
+| `--agents N` | Smart-pick N specialists from task signals + baseline anchors + rotation. |
+| `--agents name1,name2,...` | Explicit agent list. |
+| `--harness claude\|codex\|opencode\|windsurf\|echo` | Launcher template (default `claude`). |
+| `--seed <path>` | Overlay path from main repo into each worktree (e.g. `--seed .env`). |
+| `--base-ref <ref>` | Branch base for all worktrees (default `HEAD`). |
+| `--session <name>` | Override the auto-generated tmux session name. |
+| `--replace` | Tear down any existing session/worktrees with the same names. |
+| `--execute` | Create worktrees + tmux + launch agents. |
+| `--write-only` | Just write coordination files without spawning. |
+| `--json` | Print the full plan as JSON. |
+
+## Smart agent picking
+
+If you pass `--agents N` (a number), the swarm picks specialists in this order:
+
+1. **Signal-driven** — task keywords match specialist (security → `security-reviewer`, perf → `performance-optimizer`, API → `api-guardian`, …).
+2. **Baseline anchors** — `code-reviewer` + `pair-programmer` get added (every task benefits).
+3. **Rotation fill** — 4/6/8-agent default rotations tuned for breadth.
+
+## Hard rules
+
+- Never `--execute` without inspecting the dry-run first.
+- Cap N at 8 for a single repo (worktree + pane contention past 8).
+- Always human-merge handoffs from N parallel agents — don't auto-apply.
+- Use `--session NAME` if running multiple swarms in parallel.
+
+## Coordination protocol
+
+Each worker gets three files in `<repo>/.orchestration/<session>/<worker-slug>/`:
+
+- `task.md` — agent-shaped task with required handoff sections
+- `handoff.md` — where the agent writes its output
+- `status.md` — running/completed/failed marker
+
+Inspect any worker's progress with `cat .orchestration/<session>/<slug>/status.md`.
+
+## Implementation
+
+- Skill: `swarm-orchestrator`
+- Builder: `scripts/swarm/build-plan.js`
+- Orchestrator: `scripts/lib/tmux-worktree-orchestrator.js`
+- CLI: `npx kodelyth-ecc swarm`
+- Full docs: `docs/swarm.md`

package/commands/verify-supply-chain.md

@@ -0,0 +1,59 @@
+---
+description: Generate / verify SBOM, content manifest, and SLSA provenance for kodelyth-ecc. Use for compliance, audit, or tamper checks.
+---
+
+# /verify-supply-chain
+
+Run the supply-chain verification surface in one shot.
+
+## Usage
+
+```
+/verify-supply-chain                    # quick: verify current install against shipped manifest
+/verify-supply-chain --emit              # generate SBOM + manifest in cwd
+/verify-supply-chain --root /path/to/ecc --manifest /path/to/manifest.json
+```
+
+## Behavior
+
+1. If a manifest is provided (or the default `manifest.json` exists in `--root`), runs `verify` against it. Reports modified, missing, and extra files. Exits **non-zero** on any tamper.
+2. If `--emit` is set, generates fresh `kodelyth-ecc-sbom.cdx.json` and `kodelyth-ecc-manifest.json` in the current directory.
+3. If neither, prints a quick summary of what's available and what to do next.
+
+## Flags
+
+| Flag | Effect |
+|---|---|
+| `--root DIR` | Treat DIR as the kodelyth-ecc install root (default: package root). |
+| `--manifest FILE` | Path to a manifest to verify against (default: `<root>/manifest.json`). |
+| `--emit` | Generate fresh `sbom.cdx.json` + `manifest.json` in cwd. |
+| `--json` | Machine-readable output (verify report or generated docs). |
+
+## Use cases
+
+- **Audit response.** Generate fresh SBOM + manifest for a SOC 2 / ISO 27001 review.
+- **Tamper check.** Confirm that an installed copy hasn't been modified after install (matches the manifest shipped with the release).
+- **Reproducibility check.** Compare the manifest of an arbitrary downloaded release archive against the one published on GitHub.
+- **CI gate.** Pair with `--json` to fail a build when an installed dependency is tampered.
+
+## Companion commands
+
+- **`/security-audit`** — full red-team sweep using the devil-mode crew (focuses on app code).
+- **`/devil-mode`** — adversarial review of recent changes.
+- **`/release`** — release-captain handoff. Should always run `/verify-supply-chain --emit` before tagging.
+
+## Hard rules
+
+1. **Never** suppress a non-zero exit from `verify`. If a tamper is found, escalate.
+2. **Don't** publish without the SBOM + manifest attached to the GitHub release. The publish workflow handles this automatically.
+3. **Treat** the on-release manifest as authoritative — don't substitute a freshly-generated one when verifying a customer's install.
+
+## Implementation
+
+Backed by:
+
+- `scripts/supply-chain/sbom.js` — CycloneDX 1.5 generator
+- `scripts/supply-chain/manifest.js` — sha256 content manifest
+- `scripts/supply-chain/verify.js` — pure-function verifier
+
+CLI surface: `kodelyth-ecc sbom`, `kodelyth-ecc manifest`, `kodelyth-ecc verify`. See `docs/supply-chain.md` for the full reference.

package/docs/dashboard.md

@@ -0,0 +1,211 @@
+# Local observability dashboard
+
+> A localhost-only single-page web UI that renders every local data source Kodelyth ECC produces. Zero telemetry. Zero external runtime dependencies. Read-only.
+
+---
+
+## Why it exists
+
+ECC produces a lot of local state by default:
+
+- BM25 memory captures (`~/.kodelyth/memory/`)
+- Self-evolving memory signals + proposals (`~/.kodelyth/evolve/`)
+- Token-budget hook state (`~/.kodelyth/token-budget/`)
+- Swarm/orchestration session dirs (`.orchestration/<session>/`)
+- The full catalog of shipped agents / skills / commands / rules / bundles
+
+The only way to see all of this was to read JSON files by hand or run six different CLI subcommands. The dashboard is the one-glance answer.
+
+---
+
+## Boot
+
+```bash
+npx kodelyth-ecc dashboard                        # default: 127.0.0.1:5747, auto-opens browser
+npx kodelyth-ecc dashboard --port 8088            # custom port
+npx kodelyth-ecc dashboard --no-open              # don't auto-open browser (CI / remote shells)
+npx kodelyth-ecc dashboard --host localhost       # explicit localhost binding
+```
+
+Press `Ctrl+C` to stop. The server has no daemon mode by design — it lives only as long as your terminal session.
+
+---
+
+## Localhost lock
+
+The dashboard exposes everything the BM25 store and evolve log have ever recorded. Memories may contain code, problem statements, project paths, gotchas. The default bind is `127.0.0.1` and the server **refuses** to start on any other interface unless you explicitly opt out:
+
+```bash
+KODELYTH_DASHBOARD_ALLOW_REMOTE=1 \
+  npx kodelyth-ecc dashboard --host 0.0.0.0
+```
+
+This escape hatch is intentionally inconvenient. Don't use it on a network you don't fully control.
+
+Without the env var, attempting any non-localhost host produces:
+
+```
+[dashboard] refusing to bind host=0.0.0.0. Dashboard is localhost-only by default.
+To override (UNSAFE — exposes your memory + evolve data), set KODELYTH_DASHBOARD_ALLOW_REMOTE=1.
+```
+
+---
+
+## What you see
+
+### Overview tab
+
+A wall of stat cards: agents · skills · commands · rules · bundles · captured memories · surfaces · routing misses · pending proposals · swarm sessions. Plus storage paths and a token-budget snapshot.
+
+### Memory tab
+
+- Stats: total / projects / language count / tag classes
+- BM25 search box (proxies through `/api/memory/search`)
+- Recent captures table with tags + source
+
+### Evolve tab
+
+- Reuse + miss + proposal counts
+- Top 10 reused memories with surface count and last-seen
+- Top 10 miss clusters with token tags and a sample prompt
+- Proposals table with status pills (`pending` / `accepted` / `rejected` / `applied`)
+
+### Catalog tab
+
+- Selector for agents / skills / commands / rules / bundles
+- Free-text filter across name, description, tags
+- Tabular results with up to 200 entries per page
+
+### Sessions tab
+
+- Lists every swarm session in `.orchestration/`
+- Per-session: workers, modified time, expandable detail with `task.md` + `handoff.md` + `status.md` excerpts
+
+---
+
+## API surface
+
+The frontend is just a consumer of these endpoints. They're curl-friendly:
+
+| Endpoint | Returns |
+|---|---|
+| `GET /api/health` | `{ ok: true, time: <iso> }` — liveness probe |
+| `GET /api/overview` | counts + storage paths |
+| `GET /api/memory[?limit=N]` | `{ stats, recent }` |
+| `GET /api/memory/search?q=…[&limit=N]` | `{ query, results }` |
+| `GET /api/evolve[?limit=N]` | `{ reuse, miss, proposals }` |
+| `GET /api/catalog?kind=…[&q=…&limit=N]` | `{ kind, counts, items }` (kind ∈ agents/skills/commands/rules/bundles) |
+| `GET /api/sessions[?limit=N]` | `{ sessions }` |
+| `GET /api/sessions/:name` | `{ session, path, workers }` |
+| `GET /api/token-budget` | `{ sessions, total_tokens }` |
+
+### Examples
+
+```bash
+# Last 5 captured memories
+curl -s http://127.0.0.1:5747/api/memory?limit=5 | jq '.recent'
+
+# Search memory for "tailwind v4"
+curl -s 'http://127.0.0.1:5747/api/memory/search?q=tailwind+v4' | jq '.results'
+
+# Pending proposals
+curl -s http://127.0.0.1:5747/api/evolve | jq '.proposals[] | select(.status == "pending")'
+
+# All agents whose tags include "security"
+curl -s 'http://127.0.0.1:5747/api/catalog?kind=agents&q=security'
+```
+
+---
+
+## Hard rules (enforced by the server)
+
+1. **GET-only.** Any other method returns `405 method not allowed`. The dashboard CANNOT mutate state.
+2. **Localhost lock.** Non-localhost binds refused without `KODELYTH_DASHBOARD_ALLOW_REMOTE=1`.
+3. **Path-traversal-safe.** Static file resolution is sandboxed under `scripts/dashboard/static/`. `../` and similar are rejected.
+4. **No cache.** Every response carries `Cache-Control: no-store`. Data is always fresh.
+5. **Hardened headers.** `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`, `Referrer-Policy: no-referrer` on every response.
+6. **No external assets.** No CDNs, no Google Fonts, no analytics. Works fully offline.
+7. **Defensive aggregation.** Every data-source read is wrapped in try/catch with empty-default fallback. A broken memory store renders empty cards, never a 500.
+
+---
+
+## Architecture
+
+```
+scripts/dashboard/
+├── server.js          ← HTTP server. Routes API + static files.
+├── data.js            ← Pure aggregators. Reads memory + evolve + catalog + sessions + budget.
+└── static/
+    └── index.html     ← Single-page UI. Hand-rolled CSS + vanilla JS. No build step.
+```
+
+### `data.js`
+
+Pure functions only. Every aggregator:
+
+- Accepts its data-source paths as explicit arguments OR uses well-defined env-overridable defaults
+- Returns sane empty defaults on failure (never throws)
+- Has no global mutable state
+- Is unit-testable in isolation
+
+### `server.js`
+
+Uses only Node built-ins:
+
+- `http` for the listener
+- `fs`, `path` for static files
+- `child_process.execFileSync` for browser auto-open (`open` / `xdg-open` / `cmd /c start`) — no shell interpolation
+
+No `express`, no `koa`, no third-party static-file middleware. All hardening is hand-rolled and auditable in ~290 lines.
+
+### `index.html`
+
+- Hand-rolled CSS (no Tailwind, no CDN)
+- Vanilla JS with `fetch` → no build step, no transpilation
+- Tabs are simple data-attribute toggles
+- Lazy-loads each tab's data only when shown
+- SSE (`/api/events`) pushes `data-changed` events when watched files change; a `heartbeat` every 10 s keeps the green dot alive without triggering data reloads
+
+---
+
+## Worked example
+
+```bash
+$ npx kodelyth-ecc dashboard --port 5747
+✓ Kodelyth ECC dashboard
+  http://127.0.0.1:5747/
+  Press Ctrl+C to stop. Localhost only — zero telemetry.
+```
+
+In another shell:
+
+```bash
+$ curl -s http://127.0.0.1:5747/api/overview | jq '.catalog'
+{
+  "agents": 70,
+  "skills": 193,
+  "commands": 96,
+  "rules": 14,
+  "bundles": 3
+}
+```
+
+---
+
+## Composition with other features
+
+| Feature | Effect on the dashboard |
+|---|---|
+| **Memory store** | Source of the Memory tab. |
+| **Swarm orchestrator** | Source of the Sessions tab. |
+| **Token-budget hook** | Source of the budget snapshot card. |
+| **Self-evolving memory** | Source of the Evolve tab. Proposals appear automatically as they're generated. |
+
+---
+
+## See also
+
+- `skills/observability-dashboard/SKILL.md` — explicit-invocation skill
+- `commands/dashboard.md` — `/dashboard` slash command
+- `scripts/dashboard/{server,data}.js` — implementation
+- `tests/dashboard/` — aggregator + server smoke tests