kodelyth-ecc 1.5.9 → 1.7.0

package/scripts/supply-chain/sbom.js

@@ -0,0 +1,202 @@
+// scripts/supply-chain/sbom.js
+//
+// CycloneDX 1.5 Software Bill of Materials generator for kodelyth-ecc.
+//
+// Pure functions — given { rootDir }, produces a CycloneDX-shaped JS object.
+// No network, no external deps. Reads package.json + package-lock.json (v3).
+//
+// Consumers should JSON.stringify with deterministic key order
+// (we already build keys in fixed order so default JSON.stringify is fine).
+//
+// Exports:
+//   - SBOM_SPEC_VERSION
+//   - generateSBOM({ rootDir, timestamp? }) → CycloneDX object
+//   - readSBOMSources({ rootDir }) → { pkg, lock }   (mostly for tests)
+//   - buildComponentFromLockEntry(name, entry) → CycloneDX component
+//
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const SBOM_SPEC_VERSION = '1.5';
+const SBOM_FORMAT = 'CycloneDX';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function readJSON(p) {
+  return JSON.parse(fs.readFileSync(p, 'utf8'));
+}
+
+function safeReadJSON(p) {
+  try { return readJSON(p); } catch { return null; }
+}
+
+function readSBOMSources({ rootDir }) {
+  const pkgPath  = path.join(rootDir, 'package.json');
+  const lockPath = path.join(rootDir, 'package-lock.json');
+  const pkg  = readJSON(pkgPath);
+  const lock = safeReadJSON(lockPath);
+  return { pkg, lock };
+}
+
+// purl (package URL) per spec: pkg:npm/<name>@<version>
+// Scoped packages keep the leading @ but the slash is encoded.
+function npmPurl(name, version) {
+  if (!name || !version) return null;
+  // scoped: @scope/name → @scope/name (slash kept, leading @ kept)
+  // CycloneDX uses raw form; npm purl spec keeps "@scope/name"
+  return `pkg:npm/${name}@${version}`;
+}
+
+function bomRefFor(name, version) {
+  return `${name}@${version}`;
+}
+
+function buildComponentFromLockEntry(installPath, entry) {
+  // installPath is the lockfile key like "node_modules/foo" or "" (root)
+  // entry has: { name?, version, dev?, optional?, devOptional?, license?, integrity?, resolved? }
+  const name = entry.name || pkgNameFromPath(installPath);
+  if (!name || !entry.version) return null;
+
+  const component = {
+    type:     'library',
+    'bom-ref': bomRefFor(name, entry.version),
+    name,
+    version:  entry.version,
+    purl:     npmPurl(name, entry.version),
+    scope:    entry.dev ? 'optional' : 'required',
+  };
+
+  if (entry.license)   component.licenses = normalizeLicense(entry.license);
+  if (entry.integrity) component.hashes   = parseIntegrity(entry.integrity);
+
+  return component;
+}
+
+function pkgNameFromPath(installPath) {
+  // "node_modules/foo" → "foo"
+  // "node_modules/@scope/bar" → "@scope/bar"
+  // "node_modules/foo/node_modules/@scope/bar" → "@scope/bar" (deepest)
+  if (!installPath) return null;
+  const parts = installPath.split('node_modules/').filter(Boolean);
+  if (parts.length === 0) return null;
+  return parts[parts.length - 1].replace(/\/$/, '');
+}
+
+function normalizeLicense(license) {
+  // license may be a string ("MIT") or an array
+  if (typeof license === 'string') {
+    return [{ license: { id: license } }];
+  }
+  if (Array.isArray(license)) {
+    return license.map(l => typeof l === 'string' ? { license: { id: l } } : { license: l });
+  }
+  if (license && typeof license === 'object') {
+    return [{ license }];
+  }
+  return undefined;
+}
+
+function parseIntegrity(integrity) {
+  // npm SRI strings look like "sha512-base64==" — possibly multiple, space-separated.
+  return integrity.split(/\s+/).filter(Boolean).map(sri => {
+    const idx = sri.indexOf('-');
+    if (idx === -1) return null;
+    const alg = sri.slice(0, idx).toLowerCase();
+    const b64 = sri.slice(idx + 1);
+    // CycloneDX uses hex; convert base64 to hex.
+    let hex;
+    try { hex = Buffer.from(b64, 'base64').toString('hex'); }
+    catch { return null; }
+    const algMap = { sha256: 'SHA-256', sha384: 'SHA-384', sha512: 'SHA-512' };
+    return algMap[alg] ? { alg: algMap[alg], content: hex } : null;
+  }).filter(Boolean);
+}
+
+// ── main entry ────────────────────────────────────────────────────────────────
+
+function generateSBOM({ rootDir, timestamp } = {}) {
+  if (!rootDir) throw new Error('generateSBOM: rootDir is required');
+  const { pkg, lock } = readSBOMSources({ rootDir });
+
+  const ts = timestamp || new Date().toISOString();
+
+  const rootComponent = {
+    type:     'application',
+    'bom-ref': bomRefFor(pkg.name, pkg.version),
+    name:     pkg.name,
+    version:  pkg.version,
+    purl:     npmPurl(pkg.name, pkg.version),
+    description: pkg.description || undefined,
+  };
+  if (pkg.license) rootComponent.licenses = normalizeLicense(pkg.license);
+
+  const components = [];
+  const dependencies = [];
+
+  if (lock && lock.packages) {
+    // Walk every entry except the root ("")
+    for (const [installPath, entry] of Object.entries(lock.packages)) {
+      if (!installPath) continue; // root handled as metadata.component
+      const c = buildComponentFromLockEntry(installPath, entry);
+      if (c) components.push(c);
+    }
+
+    // Dependency graph for the root only — direct dependencies + optionalDependencies.
+    const rootEntry = lock.packages[''] || {};
+    const directDeps = []
+      .concat(Object.keys(rootEntry.dependencies        || {}))
+      .concat(Object.keys(rootEntry.optionalDependencies || {}));
+    if (directDeps.length) {
+      const seen = new Map();
+      for (const c of components) seen.set(c.name, c['bom-ref']);
+      const dependsOn = directDeps
+        .map(n => seen.get(n))
+        .filter(Boolean);
+      dependencies.push({
+        ref: rootComponent['bom-ref'],
+        dependsOn,
+      });
+    }
+  }
+
+  const bom = {
+    bomFormat:   SBOM_FORMAT,
+    specVersion: SBOM_SPEC_VERSION,
+    serialNumber: `urn:uuid:${deriveSerial(pkg, ts)}`,
+    version: 1,
+    metadata: {
+      timestamp: ts,
+      tools: [{
+        vendor:  'kodelyth-ecc',
+        name:    'kodelyth-ecc-sbom',
+        version: pkg.version,
+      }],
+      component: rootComponent,
+    },
+    components,
+    dependencies,
+  };
+
+  return bom;
+}
+
+// Derive a stable, deterministic UUID-ish serial from package + timestamp.
+// Not a cryptographic UUID; it's stable across re-runs at same time.
+function deriveSerial(pkg, ts) {
+  const crypto = require('crypto');
+  const h = crypto.createHash('sha256').update(`${pkg.name}@${pkg.version}|${ts}`).digest('hex');
+  // 8-4-4-4-12 layout
+  return `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20,32)}`;
+}
+
+module.exports = {
+  SBOM_SPEC_VERSION,
+  SBOM_FORMAT,
+  generateSBOM,
+  readSBOMSources,
+  buildComponentFromLockEntry,
+  // exposed for testing only
+  _internals: { npmPurl, parseIntegrity, normalizeLicense, pkgNameFromPath, deriveSerial },
+};

package/scripts/supply-chain/verify.js

@@ -0,0 +1,102 @@
+// scripts/supply-chain/verify.js
+//
+// Verify an installed copy of kodelyth-ecc against a shipped content manifest.
+//
+// Pure functions — given { rootDir, manifest }, returns a structured report
+// with categorized differences. No process.exit calls; CLI layer decides.
+//
+// Categories:
+//   ok        — file exists with matching size + sha256
+//   modified  — file exists but sha256 differs
+//   missing   — file in manifest but not on disk
+//   extra     — file on disk under shipped dirs but not in manifest (advisory)
+//
+// Exports:
+//   - verifyAgainstManifest({ rootDir, manifest }) → { ok, summary, details }
+//   - VERIFY_RESULT_KEYS
+//
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { hashFile, walkFiles, MANIFEST_SCHEMA } = require('./manifest.js');
+
+const VERIFY_RESULT_KEYS = ['ok', 'modified', 'missing', 'extra'];
+
+function verifyAgainstManifest({ rootDir, manifest } = {}) {
+  if (!rootDir)  throw new Error('verifyAgainstManifest: rootDir is required');
+  if (!manifest) throw new Error('verifyAgainstManifest: manifest is required');
+  if (manifest.schema !== MANIFEST_SCHEMA) {
+    throw new Error(
+      `verifyAgainstManifest: unsupported manifest schema "${manifest.schema}" (expected "${MANIFEST_SCHEMA}")`
+    );
+  }
+
+  const okFiles       = [];
+  const modifiedFiles = [];
+  const missingFiles  = [];
+  const extraFiles    = [];
+
+  const expectedByPath = new Map();
+  for (const entry of manifest.files || []) {
+    expectedByPath.set(entry.path, entry);
+  }
+
+  // Pass 1: every manifest file → check disk.
+  for (const entry of expectedByPath.values()) {
+    const abs = path.join(rootDir, entry.path);
+    if (!fs.existsSync(abs)) {
+      missingFiles.push({ path: entry.path, expected_sha256: entry.sha256 });
+      continue;
+    }
+    let actualSha;
+    try { actualSha = hashFile(abs); }
+    catch (err) {
+      missingFiles.push({ path: entry.path, expected_sha256: entry.sha256, error: err.message });
+      continue;
+    }
+    if (actualSha === entry.sha256) {
+      okFiles.push(entry.path);
+    } else {
+      modifiedFiles.push({
+        path:            entry.path,
+        expected_sha256: entry.sha256,
+        actual_sha256:   actualSha,
+      });
+    }
+  }
+
+  // Pass 2: walk disk → flag files NOT in manifest. Advisory only.
+  const onDisk = walkFiles(rootDir);
+  for (const abs of onDisk) {
+    const rel = path.relative(rootDir, abs).split(path.sep).join('/');
+    if (!expectedByPath.has(rel)) extraFiles.push(rel);
+  }
+
+  const summary = {
+    total_in_manifest: expectedByPath.size,
+    ok:       okFiles.length,
+    modified: modifiedFiles.length,
+    missing:  missingFiles.length,
+    extra:    extraFiles.length,
+  };
+
+  // verify is "ok" if no missing and no modified files. Extras are non-fatal.
+  const ok = summary.missing === 0 && summary.modified === 0;
+
+  return {
+    ok,
+    summary,
+    details: {
+      ok:       okFiles,
+      modified: modifiedFiles,
+      missing:  missingFiles,
+      extra:    extraFiles,
+    },
+  };
+}
+
+module.exports = {
+  VERIFY_RESULT_KEYS,
+  verifyAgainstManifest,
+};

package/scripts/swarm/build-plan.js

@@ -0,0 +1,193 @@
+// =============================================================================
+// Kodelyth ECC — Swarm Plan Builder (Phase 2.7)
+//
+// Promotes the existing `tmux-worktree-orchestrator` infrastructure to a first-
+// class CLI surface. Takes simple flags (--task, --agents N, --harness <h>, ...)
+// and produces a full plan compatible with scripts/lib/tmux-worktree-orchestrator.js.
+//
+// Pure-function builder. Zero side effects. Tested without spawning tmux/git.
+//
+// Two modes:
+//   1. Generic swarm: N agents work in parallel on the SAME task in isolated
+//      worktrees, then their handoff files are merged for review.
+//   2. Specialist swarm: a list of named ECC agents (architect, code-reviewer,
+//      security-reviewer, …) each run with an agent-shaped prompt over the
+//      same task. The swarm IS a generalized /devil-mode.
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+
+// ── Smart-default specialist rotations (4 / 6 / 8 agents) ────────────────────
+// Picked for breadth — code, security, architecture, test, perf, UX, API, docs.
+const DEFAULT_ROTATIONS = {
+  4: ['code-reviewer', 'security-reviewer', 'pair-programmer', 'tdd-guide'],
+  6: ['code-reviewer', 'security-reviewer', 'pair-programmer', 'tdd-guide', 'performance-optimizer', 'api-guardian'],
+  8: ['code-reviewer', 'security-reviewer', 'pair-programmer', 'tdd-guide', 'performance-optimizer', 'api-guardian', 'ux-reviewer', 'doc-updater'],
+};
+
+// ── Task-keyword signal weights for smart agent rotation ─────────────────────
+const SIGNAL_AGENTS = [
+  { regex: /\b(security|auth|vuln|cve|secrets?|injection|owasp)\b/i, agent: 'security-reviewer' },
+  { regex: /\b(perf(?:ormance)?|slow|p99|latency|throughput|bottleneck)\b/i, agent: 'performance-optimizer' },
+  { regex: /\b(load[\s-]?test|stress[\s-]?test|capacity|k6|locust|artillery)\b/i, agent: 'load-tester' },
+  { regex: /\b(architect|design|adr|rfc|trade[\s-]?off|system\s+design)\b/i, agent: 'architect' },
+  { regex: /\b(api|endpoint|contract|breaking\s+change|rest|graphql)\b/i, agent: 'api-guardian' },
+  { regex: /\b(test|tdd|coverage|spec|unit\s+test)\b/i, agent: 'tdd-guide' },
+  { regex: /\b(refactor|cleanup|tech\s+debt|code\s+smell|simplify)\b/i, agent: 'refactor-cleaner' },
+  { regex: /\b(ux|accessibility|wcag|a11y|usability|ui)\b/i, agent: 'ux-reviewer' },
+  { regex: /\b(doc(?:s|umentation)?|readme|guide|tutorial|comment)\b/i, agent: 'doc-updater' },
+  { regex: /\b(release|ship|tag|semver|rollback)\b/i, agent: 'release-captain' },
+  { regex: /\b(incident|outage|down|p[01]|sev[12]|on[\s-]?call)\b/i, agent: 'incident-commander' },
+  { regex: /\b(debug|why\s+is|stack\s+trace|silent\s+fail)\b/i, agent: 'debug-detective' },
+  { regex: /\b(database|sql|postgres|mysql|index|n\+1)\b/i, agent: 'database-reviewer' },
+  { regex: /\b(devil[\s-]?mode|adversarial|red[\s-]?team)\b/i, agent: 'prompt-injection-hunter' },
+];
+
+// Always-included anchors when count >= N.
+const BASELINE_ANCHORS = ['code-reviewer', 'pair-programmer'];
+
+// ── Harness launcher templates ───────────────────────────────────────────────
+// Placeholders: {worker_name} {worker_slug} {repo_root} {worktree_path}
+//               {branch_name} {task_file} {handoff_file} {status_file}
+//               {session_name}
+const HARNESS_LAUNCHERS = {
+  claude:   'claude --print --dangerously-skip-permissions "$(cat {task_file_sh})" 2>&1 | tee -a {handoff_file_sh}; printf "\\nstate: completed\\n" >> {status_file_sh}',
+  codex:    `bash {repo_root_sh}/scripts/orchestrate-codex-worker.sh {task_file_sh} {handoff_file_sh} {status_file_sh}`,
+  opencode: 'opencode run --task-file {task_file_sh} --output {handoff_file_sh} --status {status_file_sh}',
+  windsurf: 'windsurf-cli run --task-file {task_file_sh} --output {handoff_file_sh}',
+  echo:     `printf 'demo worker {worker_slug}\\n' >> {handoff_file_sh}; printf 'state: completed\\n' >> {status_file_sh}`,
+};
+
+// ── Core: pick agents for a swarm of size N ──────────────────────────────────
+function pickAgents({ count, task, explicit }) {
+  if (Array.isArray(explicit) && explicit.length > 0) {
+    return explicit.map(String);
+  }
+  const n = Math.max(1, Math.min(Number(count) || 4, 12));
+  const text = String(task || '');
+  const picked = new Set();
+
+  // 1. Signal-driven picks first (highest priority).
+  for (const { regex, agent } of SIGNAL_AGENTS) {
+    if (regex.test(text)) picked.add(agent);
+    if (picked.size >= n) break;
+  }
+
+  // 2. Baseline anchors next.
+  for (const anchor of BASELINE_ANCHORS) {
+    if (picked.size >= n) break;
+    picked.add(anchor);
+  }
+
+  // 3. Fill from rotation if we still need more.
+  const rotationKey = n <= 4 ? 4 : (n <= 6 ? 6 : 8);
+  for (const a of DEFAULT_ROTATIONS[rotationKey]) {
+    if (picked.size >= n) break;
+    picked.add(a);
+  }
+
+  // 4. Fallback fill (shouldn't normally hit).
+  const fallback = DEFAULT_ROTATIONS[8];
+  for (const a of fallback) {
+    if (picked.size >= n) break;
+    picked.add(a);
+  }
+
+  return [...picked].slice(0, n);
+}
+
+// ── Core: build a worker plan-config for a single agent ──────────────────────
+function buildWorker({ agent, task, harness, launcherCommand }) {
+  const launcher = launcherCommand || HARNESS_LAUNCHERS[harness];
+  if (!launcher) {
+    throw new Error(`No launcher template for harness "${harness}". Pass --launcher-cmd or use one of: ${Object.keys(HARNESS_LAUNCHERS).join(', ')}.`);
+  }
+  return {
+    name: agent,
+    task: shapeTaskForAgent(agent, task),
+    launcherCommand: launcher,
+  };
+}
+
+function shapeTaskForAgent(agent, task) {
+  return [
+    `# ${agent} — swarm task`,
+    '',
+    `You are running as the ECC \`${agent}\` specialist in a parallel swarm. ` +
+    'Other agents are running the same shared task in sibling worktrees. ' +
+    'Stay strictly inside your specialty — do not duplicate what other agents will cover. ' +
+    'Produce a focused handoff that names exactly which findings are yours and yours alone.',
+    '',
+    '## Shared Task',
+    '',
+    String(task || '').trim() || '(no task description provided)',
+    '',
+    '## Required handoff sections',
+    '1. Summary',
+    '2. Files Changed',
+    '3. Validation',
+    '4. Remaining Risks',
+  ].join('\n');
+}
+
+// ── Public API: full plan ────────────────────────────────────────────────────
+function buildSwarmPlan({
+  task,
+  agents,
+  count       = 4,
+  harness     = 'claude',
+  launcherCmd,
+  sessionName,
+  repoRoot    = process.cwd(),
+  worktreeRoot,
+  coordinationRoot,
+  baseRef     = 'HEAD',
+  seedPaths   = [],
+  replaceExisting = false,
+} = {}) {
+  if (!task || typeof task !== 'string' || task.trim().length === 0) {
+    throw new Error('buildSwarmPlan: --task is required');
+  }
+  const explicit = Array.isArray(agents) ? agents : null;
+  const picked = pickAgents({ count, task, explicit });
+
+  const session = sessionName || `swarm-${new Date().toISOString().slice(0,10)}-${picked.length}a`;
+
+  const workers = picked.map(agent => buildWorker({
+    agent,
+    task,
+    harness,
+    launcherCommand: launcherCmd,
+  }));
+
+  return {
+    sessionName: session,
+    repoRoot,
+    worktreeRoot,
+    coordinationRoot,
+    baseRef,
+    replaceExisting: !!replaceExisting,
+    seedPaths,
+    workers,
+    // For debugging / dashboards:
+    _meta: {
+      task,
+      harness,
+      pickedAgents: picked,
+      count: picked.length,
+    },
+  };
+}
+
+module.exports = {
+  HARNESS_LAUNCHERS,
+  DEFAULT_ROTATIONS,
+  BASELINE_ANCHORS,
+  SIGNAL_AGENTS,
+  pickAgents,
+  shapeTaskForAgent,
+  buildWorker,
+  buildSwarmPlan,
+};

package/skills/cost-aware-model-routing/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: cost-aware-model-routing
+description: Pick the right model tier (trivial/standard/hard) for each ECC session task. Companion to the cost-aware-model-routing rule and the token-budget safety hook. Use when the user asks "what model should I use" or when a session is burning frontier-model tokens on routine work.
+origin: ECC
+---
+
+# Cost-Aware Model Routing — Explicit Skill
+
+The companion skill to the always-on routing rule. Invoke this when the user explicitly asks "what model should I use for this task" or when you (the agent) want to surface a routing recommendation deliberately rather than via the implicit rule.
+
+> Pairs with `rules/common/cost-aware-model-routing.md` (the always-on rule), `hooks/safety/token-budget.js` (spend control), and the `cost-aware-llm-pipeline` skill (patterns for user code).
+
+---
+
+## When to invoke
+
+Trigger this skill when:
+
+- The user asks "which model should I use", "is opus overkill for this", "can haiku handle this", "what's the cheapest tier for this".
+- A session is approaching budget limits and the next task looks trivial.
+- The user is on a frontier model but the next task is mechanical (rename, format, doc).
+- You want to teach the user how to route deliberately for the next 10 turns instead of just this one.
+
+Do NOT invoke when:
+
+- The user is mid-task on something hard (architecture, incident, security audit) — keep them on the high tier.
+- The user has explicitly chosen a model in this session — respect their choice.
+
+---
+
+## Workflow
+
+### 1. Classify the current task
+
+Use the three-tier framework from the rule:
+
+| Tier | Examples |
+|---|---|
+| **trivial** | Rename, format, fix typo, add JSDoc, summarize, list files, version bump, kebab→camel |
+| **standard** | Code review of a PR, write a unit test, refactor one file, fix a non-critical bug, write a doc section |
+| **hard** | Architecture decision, debug-blitz of intermittent prod bug, security audit, multi-file refactor (3+ files), incident postmortem, devil-mode, agent harness changes |
+
+Weight signals together. Single signals are noisy; three or four together are reliable.
+
+### 2. Read the team's config
+
+Check for `.kodelyth/router.json` at the project root and these env vars:
+
+```
+KODELYTH_ROUTER          off | (unset)
+KODELYTH_ROUTER_TRIVIAL  override trivial-tier model id
+KODELYTH_ROUTER_STANDARD override standard-tier model id
+KODELYTH_ROUTER_HARD     override hard-tier model id
+KODELYTH_ROUTER_DEFAULT  trivial | standard | hard (fallback for ambiguous tasks)
+```
+
+If `KODELYTH_ROUTER=off`, do NOT emit recommendations — the team has chosen to opt out.
+
+### 3. Emit a single, structured recommendation
+
+Use this exact format so the user can scan it instantly:
+
+```
+[model-router] task=<tier> · suggested=<model-id> · current=<active or "unknown">
+  why: <one short sentence on the dominant signals>
+  next: <how to switch — provider-specific>
+```
+
+Only emit when the active model is mismatched with the suggested tier. If the user is already on the right tier, route silently and do not interrupt.
+
+### 4. If the user wants ad-hoc routing for a future task
+
+Tell them:
+
+```
+npx kodelyth-ecc route "<task description>"            # quick CLI hint
+npx kodelyth-ecc route "<task>" --files 5 --agent debug-detective
+```
+
+Or for an in-session check, they can `use cost-aware-model-routing` and describe the task.
+
+---
+
+## Hard rules (never break these)
+
+1. **Security / incident / adversarial work never downgrades.** If the active agent is `security-reviewer`, `incident-commander`, `debug-detective`, or any devil-mode agent (`prompt-injection-hunter`, `supply-chain-auditor`, `secret-hunter`, `backdoor-hunter`, `chaos-engineer`, `jailbreak-tester`, `code-stealer-detector`, `license-violation-finder`) — recommend **hard** tier even if the surface task looks trivial.
+2. **Production framing wins.** "Down", "leaking", "outage", "incident", "P0", "P1" → hard.
+3. **Multi-file refactors (3+) never go to trivial.**
+4. **Respect explicit user choice.** If the user said "use haiku", don't override unless a new turn introduces conflicting signals.
+5. **Budget-aware:** if `token-budget` reports usage > 70% of budget, bias one tier downward when ambiguous to extend the session.
+
+---
+
+## Examples
+
+### Example 1 — clear downgrade opportunity
+
+```
+User: "rename getUserName to getUserDisplayName everywhere"
+[active model: claude-opus-4-1]
+
+Recommendation:
+[model-router] task=trivial · suggested=claude-haiku-4-5-20251001 · current=claude-opus-4-1
+  why: single mechanical rename, no behavior change, no tests need updating.
+  next: switch to /model claude-haiku for this turn — saves ~80% in tokens with no quality loss.
+```
+
+### Example 2 — never downgrade incident work
+
+```
+User: "production is down and the auth service is throwing 502s, help"
+[active model: claude-haiku-4-5-20251001]
+
+Recommendation:
+[model-router] task=hard · suggested=claude-opus-4-1 · current=claude-haiku-4-5-20251001
+  why: production incident with security-relevant subsystem.
+  next: switch to /model claude-opus before continuing — this is incident-commander territory.
+```
+
+### Example 3 — match, no recommendation
+
+```
+User: "review this 40-line PR for typos and obvious bugs"
+[active model: claude-sonnet-4-6]
+
+Recommendation: (silent — already on the right tier)
+```
+
+### Example 4 — devil-mode never downgrades
+
+```
+User: "/devil-mode --all"
+[active model: claude-haiku-4-5-20251001]
+
+Recommendation:
+[model-router] task=hard · suggested=claude-opus-4-1 · current=claude-haiku-4-5-20251001
+  why: devil-mode adversarial sweep — security/quality assertions need frontier reasoning.
+  next: switch to /model claude-opus or your equivalent frontier model.
+```
+
+---
+
+## Implementation references
+
+- Rule: `rules/common/cost-aware-model-routing.md`
+- Classifier: `scripts/router/classify.js` (pure-function, deterministic)
+- CLI: `npx kodelyth-ecc route <task>`
+- Companion safety hook: `hooks/safety/token-budget.js` (spend cap)
+- Skill for user-code patterns (different scope): `cost-aware-llm-pipeline`
+
+---
+
+Built into [Kodelyth ECC](../../README.md). MIT licensed.

package/skills/kodelyth-quickstart/SKILL.md

@@ -166,6 +166,12 @@ use debug-detective
 ```
 Tell the agent the symptom. It will trace the bug to its root cause.
 
+**Bonus: See your AI workspace at a glance**
+```
+npx kodelyth-ecc dashboard
+```
+Opens the local observability dashboard at `http://127.0.0.1:5747`. Inspect memory captures, BM25 search across past solutions, evolve proposals, the full skill and agent catalog, swarm sessions, and token-budget snapshots — all local, zero telemetry.
+
 ---
 
 ## Common Questions
@@ -200,6 +206,7 @@ BUILD BROKEN?               →  use build-error-resolver  or  /build-fix
 UX REVIEW?                  →  use ux-reviewer
 LOAD LANGUAGE PATTERNS?     →  /python-patterns, /golang-patterns, etc.
 GENERAL CODE STANDARDS?     →  /coding-standards
+OBSERVABILITY DASHBOARD?    →  npx kodelyth-ecc dashboard  (localhost:5747)
 ```
 
 ---