kodelyth-ecc 2.4.6 → 2.4.8

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v2.4.8 — Phase 3: agent polish + token-savings skill (July 2026)
+
+Phase 3 of the sequenced plan (audit → routing → skills/agents). Disciplined polish — fixed the one agent with a real actionable gap, added the one skill filling a real gap, and deliberately did **not** pad agents that are already complete.
+
+### Agent polish
+
+- **`security-reviewer` — added a validated Active Hunt command library.** The agent described what to check (OWASP checklist, severity table) but had almost no concrete detection commands, so it could only review code it was shown, not actively hunt. Added 15 copy-paste ripgrep patterns covering hardcoded secrets, SQL/shell/code injection, XSS/DOM sinks, SSRF, authZ gaps (alg=none, decode-without-verify), weak crypto, and unsafe deserialization / prototype pollution. **Every pattern was run against the repo to confirm it parses and executes** — caught and fixed one that used a negative lookahead ripgrep's Rust regex engine rejects.
+- **Assessed the other "thin" agents and left them alone.** `refactor-cleaner` (knip/depcheck/ts-prune + risk tiers) and `tdd-guide` (red-green-refactor + coverage) are short because those workflows are concise — they already have real commands. Padding them would be bloat, against KISS/YAGNI. Line count ≠ quality.
+
+### New skill
+
+- **`skills/ecc-token-savings/SKILL.md`** — 195 skills existed but **only one referenced the new 2.x features and none unified the savings stack**. A user on 2.4.7 has three shipped savings layers (RTK input, Terse output, codebase-graph structural queries) and no single guide. This skill is the playbook: which axis each layer cuts, how to verify/enable each, a per-session-type recommendation table, how to measure real savings in the dashboard, and honest caveats (Terse per-turn overhead, RTK not covering built-in file tools, graph needing an index). All commands verified real. Now 196 skills.
+
+### Assets
+
+- SVG version badges → v2.4.8, all 31 8K PNGs re-rendered to match.
+
+### Verified
+
+- 384 tests, 0 failures
+- All 15 security-reviewer detection patterns run clean against the repo
+- New skill's 11 referenced CLI subcommands all resolve to real handlers
+- Installed copies (agent + skill) synced to this machine
+
+## v2.4.7 — Command frontmatter + 8K asset regeneration (July 2026)
+
+Final review pass across every subsystem, plus asset refresh.
+
+### Fixed
+
+- **20 slash commands had no YAML frontmatter** — so they showed up in the `/` menu with no description (part of the earlier "commands don't show properly" complaint). Added `description` + `argument-hint` to all of them: `build-fix`, `checkpoint`, `gan-build`, `gan-design`, `harness-audit`, `learn`, `loop-start`, `loop-status`, `model-route`, `multi-backend`, `multi-execute`, `multi-frontend`, `multi-plan`, `multi-workflow`, `pm2`, `quality-gate`, `refactor-clean`, `test-coverage`, `update-codemaps`, `update-docs`. All 99 commands now carry frontmatter.
+
+### Assets
+
+- **Regenerated all 31 social images at 8K** (7680px wide, aspect-preserved) into `social/exports/8k/` — e.g. `hype-mcp-server.png` is a true 7680×4320 8K UHD frame.
+- **Removed the old 4K exports** (`social/exports/4k/`, 13 MB).
+- **`brand/` left untouched** (7 SVGs + 5 PNGs) as requested.
+- SVG version badges bumped to v2.4.7; PNGs re-rendered to match.
+- 8K PNGs stay git-only — `.npmignore` already excludes `social/` and `*.png`, so the npm tarball stays lean.
+
+### Review pass (all clean)
+
+- 384 tests, 0 failures across 27 files
+- Every JS file parses
+- Versions consistent (package.json / VERSION / npm all 2.4.7)
+- 70/70 agents valid frontmatter; all internal doc links resolve
+- All 58 hook command paths in hooks.json resolve to real files
+- All 13 MCP tools callable; 381 MCP resources readable; 12 dashboard endpoints serve real data
+- manifest→verify roundtrip works
+
 ## v2.4.6 — Phase 2: measurable intent routing (38% → 100% top-1) (July 2026)
 
 The `route_intent` MCP tool was thin token-overlap against agent descriptions — no way to know if it actually worked. Now it's **measured** and **10x better**.

package/VERSION

@@ -1 +1 @@
-2.4.6
+2.4.8

package/agents/security-reviewer.md

@@ -18,13 +18,47 @@ You are an expert security specialist focused on identifying and remediating vul
 5. **Dependency Security** — Check for vulnerable npm packages
 6. **Security Best Practices** — Enforce secure coding patterns
 
-## Analysis Commands
+## Active Hunt — run these first, don't wait to be shown code
+
+You are a hunter, not a passive reviewer. On any security task, sweep the codebase with these before reasoning. Each is copy-paste ready (ripgrep; fall back to `grep -rn` if `rg` is absent). Triage every hit — most are real, some are false positives (see that section).
 
 ```bash
-npm audit --audit-level=high
-npx eslint . --plugin security
+# ── Dependency + lint baseline ──────────────────────────────────────────────
+npm audit --audit-level=high 2>/dev/null || pnpm audit || yarn audit
+npx eslint . --plugin security --quiet 2>/dev/null
+
+# ── Hardcoded secrets (CRITICAL) ────────────────────────────────────────────
+rg -n --no-heading -i '(api[_-]?key|secret|passwd|password|token|private[_-]?key)\s*[:=]\s*["\x27][A-Za-z0-9/+_-]{16,}' --glob '!*.example' --glob '!*.test.*'
+rg -n 'sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{36}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]+'   # OpenAI, GitHub, AWS, Slack
+rg -n -- '-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----'
+
+# ── Injection (CRITICAL) ────────────────────────────────────────────────────
+rg -n 'query\(\s*[`"\x27].*\$\{|execute\(\s*f["\x27]|\.raw\(|sequelize\.query\([^,]*\+'   # string-built SQL
+rg -n 'exec\(|execSync\(|child_process|os\.system\(|subprocess\.(call|run|Popen)\(.*(shell\s*=\s*True|\+)'  # shell injection
+rg -n 'eval\(|new Function\(|setTimeout\(\s*["\x27]|vm\.runIn'                              # code injection
+
+# ── XSS / DOM sinks (HIGH) ──────────────────────────────────────────────────
+rg -n 'innerHTML\s*=|dangerouslySetInnerHTML|v-html|\.html\(|document\.write\('
+rg -n 'res\.send\([^)]*req\.(query|params|body)|render\([^)]*\$\{req\.'                    # reflected
+
+# ── SSRF (HIGH) ─────────────────────────────────────────────────────────────
+rg -n '(fetch|axios|got|request|urllib|requests\.get)\([^)]*\b(req\.(query|params|body)|request\.)'
+
+# ── AuthZ gaps (CRITICAL) ───────────────────────────────────────────────────
+rg -n 'router\.(get|post|put|patch|delete)\(' -l | head          # then verify each route has an auth guard
+rg -n 'jwt\.(decode|verify)\([^,)]*\)' -A1                        # decode-without-verify, missing secret/alg
+rg -n 'algorithms?\s*:\s*\[?\s*["\x27]none|verify\([^,]*,\s*null'  # alg=none / null secret
+
+# ── Weak crypto + password handling (CRITICAL/HIGH) ─────────────────────────
+rg -n 'createHash\(\s*["\x27](md5|sha1)|hashlib\.(md5|sha1)|password\s*===|==\s*req\.body\.password'
+rg -n 'Math\.random\(\)'                                          # non-CSPRNG for tokens/ids
+
+# ── Unsafe deserialization + prototype pollution (HIGH) ─────────────────────
+rg -n 'pickle\.loads|yaml\.load\(|Marshal\.load|JSON\.parse\([^)]*req\.|_\.merge\(\{\}|Object\.assign\(target'   # yaml.load: confirm it lacks SafeLoader
 ```
 
+Report every confirmed hit with: file:line, severity, the exact fix, and (for secrets) "rotate immediately."
+
 ## Review Workflow
 
 ### 1. Initial Scan

package/commands/build-fix.md

@@ -1,3 +1,7 @@
+---
+description: Incrementally fix build and type errors with minimal, safe changes
+---
+
 # Build and Fix
 
 Incrementally fix build and type errors with minimal, safe changes.

package/commands/checkpoint.md

@@ -1,3 +1,8 @@
+---
+description: Save a git checkpoint commit of the current working state
+argument-hint: "[message]"
+---
+
 # Checkpoint Command
 
 Create or verify a checkpoint in your workflow.

package/commands/gan-build.md

@@ -1,3 +1,8 @@
+---
+description: GAN harness — generator/evaluator build loop for autonomous feature implementation
+argument-hint: "<spec>"
+---
+
 Parse the following from $ARGUMENTS:
 1. `brief` — the user's one-line description of what to build
 2. `--max-iterations N` — (optional, default 15) maximum generator-evaluator cycles

package/commands/gan-design.md

@@ -1,3 +1,8 @@
+---
+description: GAN harness — expand a one-line prompt into a full product spec
+argument-hint: "<idea>"
+---
+
 Parse the following from $ARGUMENTS:
 1. `brief` — the user's description of the design to create
 2. `--max-iterations N` — (optional, default 10) maximum design-evaluate cycles

package/commands/harness-audit.md

@@ -1,3 +1,7 @@
+---
+description: Audit and optimize the local agent harness for reliability, cost, and throughput
+---
+
 # Harness Audit Command
 
 Run a deterministic repository harness audit and return a prioritized scorecard.

package/commands/learn.md

@@ -1,3 +1,7 @@
+---
+description: Extract reusable patterns from this session and save them as learned skills
+---
+
 # /learn - Extract Reusable Patterns
 
 Analyze the current session and extract any patterns worth saving as skills.

package/commands/loop-start.md

@@ -1,3 +1,8 @@
+---
+description: Start an autonomous agent loop with quality gates and recovery controls
+argument-hint: "<task>"
+---
+
 # Loop Start Command
 
 Start a managed autonomous loop pattern with safety defaults.

package/commands/loop-status.md

@@ -1,3 +1,7 @@
+---
+description: Show the status of running autonomous agent loops
+---
+
 # Loop Status Command
 
 Inspect active loop state, progress, and failure signals.

package/commands/model-route.md

@@ -1,3 +1,8 @@
+---
+description: Recommend the right model tier (trivial/standard/hard) for the current task
+argument-hint: "<task>"
+---
+
 # Model Route Command
 
 Recommend the best model tier for the current task by complexity and budget.

package/commands/multi-backend.md

@@ -1,3 +1,8 @@
+---
+description: Fan out backend implementation across parallel specialist agents
+argument-hint: "<task>"
+---
+
 # Backend - Backend-Focused Development
 
 Backend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Codex-led.

package/commands/multi-execute.md

@@ -1,3 +1,8 @@
+---
+description: Execute a multi-agent plan across parallel workers
+argument-hint: "<plan>"
+---
+
 # Execute - Multi-Model Collaborative Execution
 
 Multi-model collaborative execution - Get prototype from plan → Claude refactors and implements → Multi-model audit and delivery.

package/commands/multi-frontend.md

@@ -1,3 +1,8 @@
+---
+description: Fan out frontend implementation across parallel specialist agents
+argument-hint: "<task>"
+---
+
 # Frontend - Frontend-Focused Development
 
 Frontend-focused workflow (Research → Ideation → Plan → Execute → Optimize → Review), Gemini-led.

package/commands/multi-plan.md

@@ -1,3 +1,8 @@
+---
+description: Plan a task for parallel multi-agent execution
+argument-hint: "<task>"
+---
+
 # Plan - Multi-Model Collaborative Planning
 
 Multi-model collaborative planning - Context retrieval + Dual-model analysis → Generate step-by-step implementation plan.

package/commands/multi-workflow.md

@@ -1,3 +1,8 @@
+---
+description: Orchestrate a multi-step workflow across parallel agents
+argument-hint: "<workflow>"
+---
+
 # Workflow - Multi-Model Collaborative Development
 
 Multi-model collaborative development workflow (Research → Ideation → Plan → Execute → Optimize → Review), with intelligent routing: Frontend → Gemini, Backend → Codex.

package/commands/pm2.md

@@ -1,3 +1,8 @@
+---
+description: Manage long-running dev processes with pm2 (start, stop, logs, status)
+argument-hint: "[action]"
+---
+
 # PM2 Init
 
 Auto-analyze project and generate PM2 service commands.

package/commands/quality-gate.md

@@ -1,3 +1,7 @@
+---
+description: Run the full quality gate — build, lint, types, tests, security scan
+---
+
 # Quality Gate Command
 
 Run the ECC quality pipeline on demand for a file or project scope.

package/commands/refactor-clean.md

@@ -1,3 +1,7 @@
+---
+description: Remove dead code, duplicates, and tech debt with safe automated cleanup
+---
+
 # Refactor Clean
 
 Safely identify and remove dead code with test verification at every step.

package/commands/test-coverage.md

@@ -1,3 +1,7 @@
+---
+description: Analyze test coverage and identify the highest-value gaps to fill
+---
+
 # Test Coverage
 
 Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.

package/commands/update-codemaps.md

@@ -1,3 +1,7 @@
+---
+description: Regenerate codemaps and architecture docs from the current source
+---
+
 # Update Codemaps
 
 Analyze the codebase structure and generate token-lean architecture documentation.

package/commands/update-docs.md

@@ -1,3 +1,7 @@
+---
+description: Update README and documentation to match the current code
+---
+
 # Update Documentation
 
 Sync documentation with the codebase, generating from source-of-truth files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kodelyth-ecc",
-  "version": "2.4.6",
+  "version": "2.4.8",
   "description": "Production-grade AI coding toolkit — 70 agents (incl. devil-mode adversarial crew), 194 skills, 97 commands, parallel multi-agent commands, semantic intent routing, self-learning memory, and a built-in MCP server (16 tools / 6 prompts / 377 resources) that bridges to Claude Desktop, LangGraph, AutoGen, CrewAI, and OpenAI Agents SDK. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, OpenCode, Cline, RooCode, Aider, Kimi, and Gemini CLI.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",

package/skills/ecc-token-savings/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: ecc-token-savings
+description: Maximize token savings across an ECC-equipped session by combining the three shipped layers — RTK (input compression on shell output), Terse mode (output compression on AI replies), and the codebase graph (structural queries instead of file-by-file grep). Use when the user asks how to cut token cost, why a session is expensive, or how to use RTK/Terse/codebase-graph together.
+origin: ECC
+---
+
+# ECC Token Savings Stack
+
+Kodelyth ECC ships three independent token-savings layers. They stack. Used together on a typical coding session they cut **55-65% of total token cost** — more on explain-heavy or exploration-heavy work. This skill is the unified playbook; the per-feature docs live in `docs/rtk.md`, `docs/terse-mode.md`, `docs/codebase-graph.md`.
+
+## The three layers (know which axis each cuts)
+
+| Layer | Cuts | How | Typical saving |
+|---|---|---|---|
+| **RTK** | Input tokens | Filters shell-command output before the LLM sees it | 60-90% on `git`/`ls`/`test`/`docker`/... |
+| **Terse mode** | Output tokens | Compresses what the AI writes, code stays byte-exact | 40-70% on replies |
+| **Codebase graph** | Input tokens | One structural query replaces dozens of grep/read cycles | ~99% on "who calls X" questions |
+
+They are orthogonal — RTK and codebase-graph shrink what goes *in*, Terse shrinks what comes *out*. Turning on all three compounds.
+
+## Verify what's active
+
+```bash
+kodelythecc rtk status        # RTK binary + wired IDEs + live ledger
+kodelythecc terse status      # skill installed? current ledger totals
+kodelythecc codebase status   # binary version + indexed projects
+```
+
+If any is missing, install it:
+
+```bash
+kodelythecc rtk enable --all              # wire RTK into every ECC-installed IDE
+kodelythecc terse enable --all            # install /terse + /terse-compress
+kodelythecc codebase install              # install codebase-memory-mcp + register
+```
+
+## The workflow — what to actually do
+
+### 1. Let RTK ride silently (already on after install)
+
+RTK is a PreToolUse hook. Once wired, every shell command the AI runs is auto-filtered. Nothing to do per-session. If you want the compact output in `Read`/`Grep` too, prefer shell (`rg`, `cat`, `find`) or explicit `rtk read`/`rtk grep` — the Bash hook doesn't cover the built-in file tools.
+
+### 2. Turn on Terse mode for the session
+
+```
+/terse full         # telegram-style fragments, ~50% output cut (default)
+/terse ultra        # maximum, ~70% cut — for expert users on familiar work
+/terse lite         # light trim, ~25% — when you still want readable prose
+/terse off          # restore normal voice (docs writing, teaching, onboarding)
+```
+
+Rule of thumb: `full` for day-to-day coding, `off` when the *output itself is the deliverable* (documentation, explanations for others, teaching).
+
+### 3. Query the graph instead of grepping
+
+Once a project is indexed (`"Index this project"` in your AI tool), replace exploration greps with structural queries:
+
+```bash
+kodelythecc codebase query search_graph '{"name_pattern": ".*Handler.*"}'
+kodelythecc codebase query trace_path   '{"function_name": "processOrder"}'
+kodelythecc codebase query get_architecture '{}'
+```
+
+"Who calls X", "what's the impact of changing Y", "show the architecture" — all one query, ~3k tokens, versus ~400k tokens of file-by-file reading.
+
+### 4. Compress persistent memory files once, save forever
+
+```bash
+kodelythecc terse compress CLAUDE.md          # ~30% smaller, code/URLs/paths byte-exact
+kodelythecc terse compress tasks/lessons.md
+```
+
+Every session that loads these files now costs ~30% fewer input tokens — permanently, not per-turn.
+
+## Measure it — don't guess
+
+```bash
+kodelythecc dashboard        # Token Savings tab: RTK (input) + Terse (output), live ledgers
+kodelythecc rtk gain --all   # raw RTK savings numbers
+kodelythecc terse stats      # output tokens saved, by level
+```
+
+The dashboard shows real ledger data, never estimates. Point the user there when they ask "how much am I actually saving."
+
+## Honest caveats — say these, don't oversell
+
+- **Terse adds ~800-1200 input tokens per turn** (the skill prompt). On turns under ~2k output tokens it can be net-negative — skip Terse for short back-and-forth.
+- **RTK only covers the Bash tool.** `Read`/`Grep`/`Glob` bypass it. Use shell equivalents to get RTK compression there.
+- **The codebase graph must be indexed first** and re-indexed after big changes (`"Index this project"` or `codebase-memory-mcp` auto-watch).
+- Native Windows RTK install is manual (`.zip` from releases); WSL and macOS/Linux auto-install.
+
+## Quick recommendation by session type
+
+| Session type | RTK | Terse | Graph |
+|---|:---:|:---:|:---:|
+| Day-to-day coding | on | `full` | query on explore |
+| Deep debugging | on | `lite` (keep reasoning readable) | `trace_path` heavily |
+| Codebase exploration / onboarding | on | `off` | primary tool |
+| Writing docs / teaching | on | `off` | as needed |
+| Expert on familiar code | on | `ultra` | query on explore |
+
+## See also
+
+- `docs/rtk.md`, `docs/terse-mode.md`, `docs/codebase-graph.md` — per-feature deep dives
+- Skills: [[terse-mode]], [[token-budget-advisor]], [[cost-aware-model-routing]]
+- The `cost-aware-model-routing` rule picks the model *tier*; this skill cuts the *token count* at whatever tier you're on.