kodelyth-ecc 1.5.10 → 1.7.0

package/bundles/enterprise.md

@@ -0,0 +1,172 @@
+# BUNDLE — Enterprise
+
+You are running in **Enterprise** mode. This installation was configured for teams operating under compliance, audit, and supply-chain accountability requirements (SOC 2, ISO 27001, HIPAA-adjacent, regulated industries).
+
+The full ECC toolkit is installed — this file biases the AI toward workflows that produce auditable, attributable, reproducible work. Read this on every session start.
+
+---
+
+## Mindset
+
+- **Auditability is a feature.** Every change traces to a ticket, a reviewer, a justification.
+- **Reproducible builds.** No "works on my machine." Lockfiles, signed tags, pinned versions.
+- **License hygiene is non-optional.** Procurement reads your SBOM. Lawyers read your LICENSE bundle.
+- **Supply chain is a threat surface.** Direct deps + transitive deps + build environment.
+- **Documentation is a deliverable.** Code without runbooks is debt.
+- **Security gates are blocking, not advisory.** CRITICAL findings stop releases.
+
+---
+
+## Featured Agents
+
+| Agent | Role |
+|---|---|
+| `architect` | System design with explicit constraints, trade-off documentation, ADRs |
+| `code-architect` | Implementation matching architecture; produces audit-friendly diffs |
+| `code-reviewer` | Quality bar enforced uniformly; documented review decisions |
+| `security-reviewer` | OWASP Top 10 + project-specific threat model |
+| `api-guardian` | Contract management, breaking-change discipline, OpenAPI authority |
+| `performance-optimizer` | Measured optimization with before/after benchmarks |
+| `release-captain` | Tag, sign, ship, document — with full release notes |
+| `doc-updater` | Every code change reflected in docs |
+| `migration-guide` | Phased migrations with rollback plans, version compat matrices |
+| `incident-commander` | Production response with formal postmortem discipline |
+
+### Required adversarial crew (compliance-relevant)
+
+| Agent | Compliance role |
+|---|---|
+| `license-violation-finder` | SBOM hygiene, copyleft tracking, attribution bundles |
+| `supply-chain-auditor` | SLSA-style attestation, lockfile integrity, dep provenance |
+| `secret-hunter` | Quarterly mandated key audits, rotation evidence |
+| `code-stealer-detector` | M&A due diligence, IP audit before any disclosure |
+
+---
+
+## Featured Commands
+
+```
+/team-review              # Multi-angle code review for PR sign-off
+/pre-release              # Release readiness gate (3-agent parallel)
+/security-audit           # Standard 3-agent security sweep
+/devil-mode --pre-launch  # Adversarial sweep before any major release
+/devil-mode --pre-public  # Before any open-source publication or public API change
+```
+
+---
+
+## Suggested Workflow
+
+### Per-PR (every change)
+
+```
+1. PR opened — author runs /team-review on local branch
+2. CI runs:
+   - lint + tests + coverage gate
+   - /devil-mode auto-runs on diff
+   - SBOM generated, license check
+3. Review by humans references CI output
+4. Merge requires green CI + 1+ approvals
+5. doc-updater confirms docs match code
+```
+
+### Per-release (cut version)
+
+```
+1. /pre-release agent crew runs:
+   - release-captain: changelog + tag plan
+   - security-reviewer: full sweep
+   - code-reviewer: regression risk
+2. /devil-mode --pre-launch:
+   - prompt-injection-hunter (if AI features touched)
+   - supply-chain-auditor (lockfile + provenance)
+   - secret-hunter (env var leaks)
+   - backdoor-hunter (third-party code review)
+3. SBOM generated, signed with cosign
+4. SLSA Level 3 attestation generated
+5. Release notes published, tag signed, artifacts pushed
+```
+
+### Quarterly (compliance cadence)
+
+```
+1. license-violation-finder: full dep audit, attribution bundle refreshed
+2. secret-hunter: mandatory rotation audit (proves all keys < 90 days old)
+3. code-stealer-detector: provenance audit, M&A-ready
+4. /devil-mode --all: comprehensive adversarial sweep
+5. supply-chain-auditor: SBOM diff vs last quarter
+6. Document all findings; close or accept-with-justification
+```
+
+### Pre-incident (every quarter)
+
+```
+1. chaos-engineer designs game-day scenarios
+2. Run in staging with full team observing
+3. Document findings as runbook entries
+4. Update incident response runbooks
+5. incident-commander reviews postmortem template
+```
+
+---
+
+## Required Defaults
+
+- **Lockfiles strict** — `npm ci`, `pnpm install --frozen-lockfile`, `yarn install --frozen-lockfile` only in CI/prod
+- **Signed tags only** — sigstore/cosign signing on every release tag
+- **SBOM generation** — CycloneDX format on every release
+- **License bundle** — `THIRD-PARTY.md` regenerated on every dep change
+- **Audit log** — every agent invocation logged with input/output for compliance review
+- **No telemetry** — verified by `secret-hunter` periodic scan of code
+- **Branch protection** — main requires PR + reviews + green CI + signed commits
+- **Secret store integration** — Vault / AWS Secrets Manager / Doppler / Infisical, never `.env` in production
+- **CVE policy** — CRITICAL CVEs block release, HIGH require triage doc
+
+---
+
+## Compliance Mode Hooks
+
+Recommended hooks to enable for SOC 2 / ISO 27001 readiness:
+
+- `pre-commit` — `gitleaks`, `detect-secrets`, `lint`, `test --bail`
+- `pre-push` — `npm audit --audit-level=high` blocking
+- `post-merge` — SBOM regenerate, license diff
+- `pre-tag` — full `/devil-mode` + `/pre-release` parallel run
+
+---
+
+## What This Bundle Surfaces First
+
+You still have all 70 agents — but routing is biased toward:
+
+1. **Auditability** — every recommendation comes with rationale
+2. **Documentation** — every change has a doc impact note
+3. **Reproducibility** — no "magic" commands, everything pinned
+4. **Risk-tiered triage** — CRITICAL / HIGH / MEDIUM / LOW classifications match common compliance frameworks
+
+---
+
+## Anti-Patterns This Bundle Catches
+
+- "Trust me bro" PRs without justification → `code-reviewer` requires reasoning
+- Undocumented architectural decisions → `architect` writes ADRs
+- Unsigned releases → `release-captain` blocks
+- Floating dep versions → `dependency-doctor` flags
+- License cocktails without attribution bundles → `license-violation-finder` blocks
+- Production patches without postmortem → `incident-commander` enforces
+
+---
+
+## When You Need Even Stricter
+
+If your compliance posture is HIPAA / PCI / FedRAMP, layer the relevant skill bundles:
+
+- `healthcare-phi-compliance` (HIPAA)
+- `healthcare-eval-harness` (clinical safety gating)
+- `defi-amm-security` (financial protocol hardening)
+
+These provide additional audit playbooks on top of the enterprise baseline.
+
+---
+
+**Powered by Kodelyth ECC v1.6.0+ · Enterprise bundle**

package/bundles/indie-hacker.md

@@ -0,0 +1,106 @@
+# BUNDLE — Indie Hacker
+
+You are running in **Indie Hacker** mode. This installation was configured for solo founders and small teams shipping fast, validating quickly, and hardening before the audience grows.
+
+The full ECC toolkit is installed — this file biases the AI toward workflows that match how indie builders work. Read this on every session start.
+
+---
+
+## Mindset
+
+- **Ship beats polish** until product-market fit. Don't gold-plate.
+- **One bug at a time.** Don't refactor while debugging.
+- **Cost is real.** Prefer Sonnet/Haiku over Opus unless the task warrants it.
+- **Distribution is the moat.** SEO, accessibility, and onboarding matter as much as code.
+- **Security debt is real but staged.** Critical issues now (secrets, auth) — full audit before public launch.
+
+---
+
+## Featured Agents (start with these)
+
+| Agent | When to reach for it |
+|---|---|
+| `kodelyth-advisor` | When unsure where to start, what to prioritize, or which approach to take |
+| `pair-programmer` | About to write a feature — get the approach right before coding |
+| `debug-detective` | Bug, error, unexpected behavior — root cause not symptom |
+| `tdd-guide` | Adding a feature you'll later regret — write the test first |
+| `ux-reviewer` | Form feels clunky, mobile broken, accessibility gaps |
+| `seo-specialist` | Page not ranking, meta tags, structured data |
+| `dependency-doctor` | `npm install` failing, CVE alert, dep upgrade |
+| `build-error-resolver` | Vercel / Railway / build failing |
+| `security-reviewer` | Auth, payments, user input — single-file security focus |
+| `release-captain` | Cut a version, tag, ship |
+
+---
+
+## Featured Commands (paste-and-go)
+
+```
+/project-launch           # New project — 5 agents plan in parallel
+/devil-mode --pre-public  # Before going open-source — full red-team sweep
+/tdd                      # TDD workflow on a single feature
+/debug-blitz              # Bug stuck >30min — 3-agent parallel attack
+/team-review              # Pre-deploy review — code + security + perf + API
+/memory                   # See / search / capture solutions across projects
+/lessons                  # Save preferences ("we use pnpm not npm")
+/onboard                  # New repo or new collaborator — 3-agent overview
+```
+
+---
+
+## Suggested Workflow (typical indie sprint)
+
+```
+Day 1 — Idea
+  → Use /project-launch to get a parallel plan from architect + pair-programmer + ux-reviewer + tdd-guide + security-reviewer
+
+Day 2-N — Build
+  → Each new feature: pair-programmer → tdd-guide → impl → code-reviewer
+  → Memory captures patterns automatically; corrections stack into tasks/lessons.md
+
+Pre-launch — Harden
+  → /devil-mode --pre-public            (secret scan + supply chain + AI safety + backdoors)
+  → /team-review                         (code quality + perf + API surface)
+  → /pre-release                         (release-captain confirms tag-readiness)
+
+Post-launch — Iterate
+  → /debug-blitz on stubborn bugs
+  → /memory recall <topic> to surface past solutions
+```
+
+---
+
+## Cost-Aware Defaults
+
+This bundle prefers cheap models for routine work:
+
+- Trivial tasks (rename, format, JSDoc) → Haiku / Gemini Flash
+- Standard tasks (review, simple bug fix) → Sonnet (default)
+- Hard tasks (architecture, complex debug, security) → Opus / GPT-5
+
+If you have `/model-route` available, lean on it.
+
+---
+
+## What This Bundle Skips by Default
+
+You still have access to all 70 agents — these just aren't surfaced first:
+
+- Heavy enterprise agents (`compliance-checker` patterns, `architect-of-architects`)
+- Most language-specific reviewers if you're TypeScript/Python only — they're there if you need them
+- Multi-agent enterprise workflows (`/team-review` is plenty)
+
+Run `/devil-mode --all` or `use <agent-name>` any time to access the full crew.
+
+---
+
+## Anti-Patterns This Bundle Catches
+
+- Fixing symptoms instead of root cause → routes to `debug-detective`
+- "Just one more feature" before fixing tech debt → `kodelyth-advisor` gets a word in
+- Going public without secret/license sweep → `/devil-mode --pre-public` reminder
+- Slow iteration loop because of bad TDD → `tdd-guide` enforces test-first rhythm
+
+---
+
+**Powered by Kodelyth ECC v1.6.0+ · Indie Hacker bundle**

package/bundles/red-team.md

@@ -0,0 +1,138 @@
+# BUNDLE — Red Team
+
+You are running in **Red Team** mode. This installation was configured for security-focused engineers, pentesters, and teams shipping AI features who need adversarial review on every commit.
+
+The full ECC toolkit is installed — this file biases the AI toward attacker-mindset workflows. Read this on every session start.
+
+---
+
+## Mindset
+
+- **Read every line as malicious until proven benign.** Especially third-party code.
+- **Every input is hostile.** Every byte the LLM sees was written by an attacker until verified.
+- **Hidden assumptions are bugs.** What can break your system, will, eventually.
+- **Defense in depth.** No single control is enough.
+- **Disclosure is the deliverable.** Findings without proof and fix paths are not findings.
+
+---
+
+## Featured Agents (the devil-mode crew)
+
+The 8-agent adversarial crew is the heart of this bundle. Lead with these:
+
+| Agent | Hunts |
+|---|---|
+| `prompt-injection-hunter` | Jailbreaks, indirect injection, system-prompt leaks, tool hijacking |
+| `supply-chain-auditor` | Typosquats, malicious postinstall, lockfile drift, slopsquats |
+| `secret-hunter` | Leaked creds in code + git history + encoded blobs + bundled to client |
+| `license-violation-finder` | GPL contamination, missing attributions, license cocktails |
+| `jailbreak-tester` | 10-tier live AI feature red-team (refusal bypass to PII exfil) |
+| `code-stealer-detector` | Code provenance, copy-paste origins, AI-gen code with copyleft hits |
+| `backdoor-hunter` | Obfuscated payloads, beacons, time bombs, reverse shells, cryptominers |
+| `chaos-engineer` | Hypothesis-first fault injection (kill processes, network partition, fuzz inputs) |
+
+Plus the standard security crew:
+
+| Agent | Role |
+|---|---|
+| `security-reviewer` | OWASP Top 10, single-file security focus |
+| `api-guardian` | API contract security, exposed endpoints, broken auth |
+| `dependency-doctor` | CVE scan, dep updates, vulnerability triage |
+| `incident-commander` | When the threat is actually live in production |
+
+---
+
+## Featured Commands
+
+```
+/devil-mode                   # 4-agent default sweep (the daily driver)
+/devil-mode --all             # All 8 adversarial agents
+/devil-mode --pre-public      # Pre-open-source — adds license + theft check
+/devil-mode --pre-launch      # Pre-launch — adds AI red-team + chaos planning
+/security-audit               # Standard 3-agent security sweep
+/pre-release                  # Tag-readiness with security gate
+```
+
+---
+
+## Suggested Workflow
+
+### Daily security review (per-PR)
+
+```
+1. /devil-mode                       (4-agent parallel sweep on diff)
+2. Manual review of CRITICAL findings
+3. Fix or quarantine
+4. /security-audit on touched files  (deeper dive on auth/API surface)
+```
+
+### Pre-public sweep (before any repo goes open)
+
+```
+1. /devil-mode --pre-public          (secret + license + IP + supply chain)
+2. Address every CRITICAL — rotate, replace, attribute
+3. Manual review of all HIGH findings
+4. Document residual risk in SECURITY.md
+```
+
+### Pre-launch sweep (before any AI feature goes public)
+
+```
+1. jailbreak-tester running 10-tier battery
+2. prompt-injection-hunter reviewing the prompt + RAG pipeline
+3. /devil-mode --pre-launch          (full sweep)
+4. chaos-engineer designs failure-mode game day
+5. Run game day in staging
+6. Ship only when green
+```
+
+### Post-compromise sweep (after security alert)
+
+```
+1. /devil-mode --all                 (entire crew on the codebase)
+2. backdoor-hunter focused on the touched files / time window
+3. secret-hunter checking key validity (rotate any active leaks)
+4. supply-chain-auditor on the implicated dep
+5. Document IOCs and report to vendor / users
+```
+
+---
+
+## Strict Defaults
+
+This bundle assumes adversarial environments. Defaults to:
+
+- Token budget enforced via hooks (no runaway model spend)
+- Output sanitization layer on any LLM-rendered content
+- Outbound network calls flagged in code review
+- `npm ci` instead of `npm install` (lockfile-strict)
+- Pre-commit hooks: `gitleaks` + `detect-secrets` + lint
+- Sigstore / cosign signed tags expected on releases
+
+---
+
+## Required Reading
+
+The first 4 agents in this bundle ship with full attacker playbooks. Read them before running:
+
+- `agents/prompt-injection-hunter.md`
+- `agents/supply-chain-auditor.md`
+- `agents/secret-hunter.md`
+- `agents/backdoor-hunter.md`
+
+Each ~300 lines of real audit logic, not theatrical persona.
+
+---
+
+## Anti-Patterns This Bundle Catches
+
+- Trusting `package.json` `license` field over actual `LICENSE` file
+- Treating "no error" as "no problem" in AI features
+- Running chaos in production without abort criteria
+- Considering CVE-free deps as safe (typosquats and slopsquats are CVE-less)
+- Treating system prompt as confidential when it's user-extractable
+- Calling `npm install` directly in production deploy
+
+---
+
+**Powered by Kodelyth ECC v1.6.0+ · Red Team bundle**

package/commands/dashboard.md

@@ -0,0 +1,67 @@
+---
+description: Boot the localhost-only Kodelyth ECC observability dashboard. Visualizes memory, evolve signals, catalog, swarm sessions, and token-budget snapshots. Read-only. Zero telemetry.
+---
+
+# /dashboard
+
+A localhost web UI over every local data source ECC produces. No external dependencies, no telemetry, no network access. Auto-opens your browser.
+
+## Usage
+
+```
+/dashboard                          # default: 127.0.0.1:5747, opens browser
+/dashboard --port 8088              # custom port
+/dashboard --no-open                # don't auto-open browser
+/dashboard --host localhost         # explicit localhost binding
+```
+
+## What you'll see
+
+| Tab | Content |
+|---|---|
+| **Overview** | Counts of every shipped asset, captured memories, surfaces, routing misses, pending proposals, swarm sessions, plus token-budget snapshot. |
+| **Memory** | Live BM25 search box + recent captures with tags. |
+| **Evolve** | Top reused memories, top miss clusters, proposals with status pills. |
+| **Catalog** | Searchable browser over every agent / skill / command / rule / bundle. |
+| **Sessions** | Swarm/orchestration sessions with per-worker drill-down. |
+
+## Hard rules
+
+1. **GET-only.** No mutation endpoints. The dashboard cannot accept proposals, capture memories, or change any state. Mutations stay in the CLI.
+2. **Localhost-only by default.** Refuses to bind `0.0.0.0` or remote IPs without `KODELYTH_DASHBOARD_ALLOW_REMOTE=1` (intentionally noisy escape hatch).
+3. **No external assets.** No CDNs, no Google Fonts. Works fully offline.
+4. **No cache.** Always-fresh data on refresh.
+5. **No telemetry.** All data stays on this machine.
+
+## API endpoints (curl-friendly)
+
+```
+GET /api/health
+GET /api/overview
+GET /api/memory[?limit=N]
+GET /api/memory/search?q=…
+GET /api/evolve
+GET /api/catalog?kind=skills&q=…
+GET /api/sessions
+GET /api/sessions/:name
+GET /api/token-budget
+```
+
+The frontend is a thin consumer of these. Anything the UI shows you can also pipe through `jq`.
+
+## Companion commands
+
+- **`/memory remember`** — capture a memory; appears in the Memory tab on next refresh.
+- **`kodelyth-ecc evolve analyze`** — generates proposals; they appear in the Evolve tab as pending.
+- **`kodelyth-ecc evolve accept <id>`** — write a draft to disk; status pill flips.
+- **`kodelyth-ecc swarm --task "…"`** — spawns sessions visible in the Sessions tab.
+
+## Implementation
+
+Backed by:
+
+- `scripts/dashboard/server.js` — HTTP server using only Node built-ins (`http`, `fs`, `path`, `child_process`)
+- `scripts/dashboard/data.js` — pure aggregators across memory/evolve/catalog/sessions/token-budget
+- `scripts/dashboard/static/index.html` — single-page UI with hand-rolled CSS, vanilla JS, no build
+
+Skill: `observability-dashboard`. Full reference: `docs/dashboard.md`.

package/commands/devil-mode.md

@@ -0,0 +1,121 @@
+---
+description: Parallel adversarial sweep — fires prompt-injection-hunter + supply-chain-auditor + secret-hunter + backdoor-hunter simultaneously. The full attacker-mindset audit in one command.
+---
+
+# /devil-mode — Adversarial Parallel Sweep
+
+Four red-team specialists attack your codebase from every angle attackers actually use. What would take a security firm a week of billable hours, your repo gets in 20 minutes.
+
+> **Read the brief first.** Each agent thinks like a hostile actor. Findings will be uncomfortable. That's the point.
+
+## What Gets Launched in Parallel
+
+| Agent | Hunts |
+|---|---|
+| `prompt-injection-hunter` | Jailbreak vectors, indirect injection, system-prompt leaks, tool-call hijacking |
+| `supply-chain-auditor` | Typosquats, malicious post-install, lockfile drift, slopsquats, compromised deps |
+| `secret-hunter` | Live secrets, git history leaks, encoded creds, bundled-to-client env vars |
+| `backdoor-hunter` | Obfuscated payloads, network beacons, time bombs, eval/exec abuse, cryptominers |
+
+## Optional Extension Agents
+
+Use these flags to add more agents to the sweep:
+
+| Flag | Adds |
+|---|---|
+| `--license` | `license-violation-finder` (GPL contamination, attribution gaps) |
+| `--theft` | `code-stealer-detector` (copy-paste provenance, copyleft hits) |
+| `--jailbreak` | `jailbreak-tester` (live AI feature red-team) |
+| `--chaos` | `chaos-engineer` (fault-injection plan generation) |
+| `--all` | All 8 agents — the **full devil sweep** |
+
+## Usage
+
+```
+/devil-mode                  # 4-agent default sweep
+/devil-mode --all            # all 8 adversarial agents
+/devil-mode src/auth/        # focus on auth module
+/devil-mode --pre-public     # before going open-source: --license + --theft + default
+/devil-mode --pre-launch     # before public launch: --jailbreak + default + --chaos
+```
+
+## Report Format
+
+```
+## DEVIL MODE REPORT
+
+### Prompt Injection Surface (prompt-injection-hunter)
+CRITICAL: [list]
+HIGH:     [list]
+DEFENSE GAPS: [where existing protections can be bypassed]
+
+### Supply Chain (supply-chain-auditor)
+THREATS:    [confirmed malicious / typosquat / drift]
+WATCHLIST:  [suspicious patterns]
+LOCKFILE:   [OK / drift / missing]
+
+### Leaked Secrets (secret-hunter)
+ACTIVE:     [rotate now — still valid]
+HISTORICAL: [git history leaks — assume compromised]
+BUNDLED:    [exposed to every client visit]
+
+### Backdoors / Malicious Code (backdoor-hunter)
+CRITICAL:   [confirmed reverse-shell / RCE / exfiltration]
+SUSPICIOUS: [needs manual decode/review]
+
+---
+TOTAL EXPOSURE:    X critical, Y high, Z medium across N agents
+PRIORITIZED ACTIONS:
+  1. [first action — usually rotate or revert]
+  2. [second]
+  3. [third]
+```
+
+## When to Use
+
+- **Before going open-source** — any repo about to be public, run with `--pre-public`
+- **Before any public launch** — run with `--pre-launch`
+- **After accepting code from new contractor / contributor** — full audit with `--all`
+- **Quarterly red-team review** — schedule it
+- **After any compromise alert / vendor security advisory** — verify your exposure
+- **Before M&A due diligence** — what their lawyers will find, you find first
+- **After major dep update** — supply-chain + backdoor + secret sweep
+
+## When NOT to Use
+
+- ❌ On code you don't have permission to audit (run only on your own repos / authorized targets)
+- ❌ On production systems for `chaos-engineer` flag — chaos requires `--staging` or signed-off blast radius
+- ❌ As a substitute for actual security review — this finds patterns; humans verify exploitability
+
+## Execute Now
+
+Invoking this command is confirmation to proceed. Execute immediately:
+
+1. Parse `$ARGUMENTS` for scope path and flags (`--all`, `--license`, `--theft`, `--jailbreak`, `--chaos`, `--pre-public`, `--pre-launch`).
+2. Determine the agent set:
+   - Default: `prompt-injection-hunter`, `supply-chain-auditor`, `secret-hunter`, `backdoor-hunter`
+   - `--pre-public`: default + `license-violation-finder` + `code-stealer-detector`
+   - `--pre-launch`: default + `jailbreak-tester` + `chaos-engineer`
+   - `--all`: all 8
+3. Spawn all selected agents simultaneously with `run_in_background: true`.
+4. Wait for all to complete.
+5. Aggregate findings into the Devil Mode Report format above.
+6. Prioritize actions by severity (critical first), with concrete recommended fix for each.
+7. End with: "Which threat do you want to neutralize first?"
+
+## Severity Priority Order
+
+When aggregating across agents, sort findings by:
+
+1. **Active credential leak** (still valid keys) — rotate immediately
+2. **Confirmed backdoor / malicious code** in current dep — quarantine + revert
+3. **Confirmed prompt injection** with tool-call abuse possible — disable affected agent
+4. **Critical supply-chain threat** (typosquat, malicious postinstall) — remove dep
+5. **Historical credential leak** in git history — rotate, plan history rewrite
+6. **High-severity prompt injection** without tool abuse — patch + monitor
+7. **License/IP exposure** — remediate before any public action
+8. **Suspicious patterns needing manual review** — schedule deep dive
+
+---
+
+**Remember:** The devil-mode report is uncomfortable on purpose. Every finding here is one an attacker can find too — the only question is whether you fix it first.

package/commands/memory-evolve.md

@@ -0,0 +1,71 @@
+---
+description: Phase 3.4 self-evolving memory. Convert reuse + routing-miss signals into PR-ready proposals (skill drafts + routing-rule additions). Never auto-applies.
+---
+
+# /memory-evolve
+
+Run the self-evolving memory loop. Inspect what ECC has learned from your sessions, generate proposals, accept the ones you want as drafts, reject the rest. **Nothing is ever committed automatically** — accept writes a draft file you review.
+
+## Usage
+
+```
+/memory-evolve                    # default: stats + analyze + list
+/memory-evolve stats              # snapshot of recorded signals
+/memory-evolve analyze            # signals → proposals (idempotent)
+/memory-evolve list               # show all proposals
+/memory-evolve list --status pending
+/memory-evolve show <id>          # full proposed content + evidence
+/memory-evolve accept <id>        # write draft file to disk (NEVER commits)
+/memory-evolve reject <id> --note "covered by existing agent"
+```
+
+## Behavior
+
+1. **stats** prints the current signal snapshot:
+   - reuse: how many memories are tracked, total surfaces, top reused
+   - routing misses: how many substantive prompts had zero memory matches, top token clusters
+2. **analyze** applies thresholds and writes proposals to `~/.kodelyth/evolve/proposals.jsonl`. Stable IDs — re-running does NOT duplicate.
+3. **list** filters by state. **show** prints the full draft markdown + evidence.
+4. **accept** writes the draft to its target path under `--root` (defaults to package root). Refuses to overwrite without `--overwrite`. Marks the proposal `accepted` with the absolute path.
+5. **reject** marks a proposal rejected with optional note.
+
+## Default thresholds
+
+| Signal | Default threshold | Override flag |
+|---|---|---|
+| Memory reuse count | 3 | `--reuse-min N` |
+| Distinct sessions per memory | 2 | `--reuse-min-sessions N` |
+| Routing-miss cluster total | 3 | `--miss-min N` |
+| Distinct prompts per cluster | 2 | `--miss-min-distinct N` |
+
+## Use cases
+
+- **Promote a recurring memory to a skill.** A memory that's been recalled 5 times across 4 sessions is probably ready to graduate.
+- **Find routing gaps.** Ten substantive prompts about "feature flags" that hit zero memories and (you suspect) no specialist agent → propose a routing entry.
+- **Audit what ECC has learned.** Before tagging a release, see what proposals are pending and decide which to accept.
+- **Reject noisy patterns.** Some clusters look real but cover ground that's already covered by an existing agent. Reject with a note for the audit trail.
+
+## Companion commands
+
+- **`/memory remember`** — manual memory capture. Without captured memories, evolve has nothing to learn from.
+- **`/skill-create`** — alternative path: create a skill from scratch instead of from an evolved memory.
+- **`/devil-mode`** — adversarial review of the accepted draft before commit.
+
+## Hard rules
+
+1. **NEVER commit accepted drafts automatically.** The CLI writes the file. The user reviews, edits, commits.
+2. **NEVER overwrite an existing file** without `--overwrite`. Even on accept.
+3. **Routing-addition diffs ship `TODO-agent`** intentionally so they cannot accidentally route real traffic.
+4. **All recording is fire-and-forget.** Hooks NEVER block on signal write failure.
+5. **Append-only proposal log.** State changes preserve the full audit trail.
+
+## Implementation
+
+Backed by:
+
+- `scripts/evolve/stats.js` — pure record/read of `~/.kodelyth/evolve/{reuse.json, routing-misses.jsonl}`
+- `scripts/evolve/analyze.js` — pure functions: signals → proposals
+- `scripts/evolve/proposals.js` — append-only proposal log with state transitions
+- `hooks/memory/auto-recall.js` — fire-and-forget signal recording on every UserPromptSubmit
+
+CLI surface: `kodelyth-ecc evolve <stats|analyze|list|show|accept|reject>`. Skill: `self-evolving-memory`. Full reference: `docs/evolve.md`.