kodelyth-ecc 2.25.0 → 2.30.0

package/scripts/super-agent/orchestrator.js

@@ -0,0 +1,175 @@
+// scripts/super-agent/orchestrator.js
+//
+// The super-agent driver — the piece Agent B found missing. It is an Arena-style
+// state machine: a PURE nextAction(run) decides what to do next, and the driving
+// LLM performs that action (decompose with blueprint, dispatch via the swarm,
+// evaluate with the GAN loop, integrate branches, verify) and reports back
+// through a submit* function, which advances the run and persists it.
+//
+//   plan ──decompose──▶ execute ──(all steps done)──▶ integrate ──▶ verify ──▶ done
+//                         │
+//                         └─ dispatch ready steps (deps satisfied), budget-gated
+//
+// nextAction never mutates, so the whole control plane is tested without spawning
+// a single agent. Mutations + phase transitions live in the submit* recorders.
+'use strict';
+
+const dag = require('./dag.js');
+const state = require('./state.js');
+const { PHASE } = state;
+
+// Rough per-step token estimate for the budget gate. Deliberately conservative;
+// real spend is accrued from what the driver reports.
+const DEFAULT_STEP_TOKENS = 4000;
+
+function estimateTokens(steps) {
+  return (steps.length || 1) * DEFAULT_STEP_TOKENS;
+}
+
+function stepBrief(s) {
+  return {
+    id: s.id,
+    description: s.description || '',
+    deps: s.deps || [],
+    contextBrief: s.contextBrief || s.context || '',
+    exitCriteria: s.exitCriteria || s.exit || '',
+  };
+}
+
+function branchesOf(run) {
+  return run.steps
+    .filter((s) => s.status === dag.STATUS.DONE && s.branch)
+    .map((s) => ({ step: s.id, branch: s.branch }));
+}
+
+// ── The state machine (pure) ─────────────────────────────────────────────────
+function nextAction(run) {
+  if (!run || run.status !== 'running') {
+    return { action: 'report', reason: (run && (run.stopReason || run.status)) || 'no run', run: run && state.summarize(run) };
+  }
+
+  switch (run.phase) {
+    case PHASE.PLAN:
+      // No plan yet → ask the driver to decompose the goal into a step DAG.
+      return { action: 'decompose', goal: run.goal, scope: run.scope };
+
+    case PHASE.EXECUTE: {
+      if (dag.isStalled(run.steps)) {
+        return { action: 'halt', reason: 'plan stalled — a dependency failed, so no remaining step can run' };
+      }
+      const ready = dag.readySteps(run.steps);
+      if (ready.length === 0) {
+        // Not stalled and nothing ready → steps are in progress; wait for results.
+        return { action: 'await', inProgress: run.steps.filter((s) => s.status === dag.STATUS.IN_PROGRESS).map((s) => s.id) };
+      }
+      const afford = state.canAfford(run, estimateTokens(ready));
+      if (!afford.ok) return { action: 'halt', reason: `budget: ${afford.reason}` };
+      return { action: 'dispatch', parallel: ready.length > 1, steps: ready.map(stepBrief) };
+    }
+
+    case PHASE.INTEGRATE:
+      return { action: 'integrate', branches: branchesOf(run), scope: run.scope };
+
+    case PHASE.VERIFY:
+      return { action: 'verify', scope: run.scope };
+
+    case PHASE.DONE:
+      return { action: 'report', reason: 'done', run: state.summarize(run) };
+
+    default:
+      return { action: 'report', reason: `unknown phase: ${run.phase}`, run: state.summarize(run) };
+  }
+}
+
+// ── Recorders (mutate + advance + persist) ───────────────────────────────────
+
+// The driver decomposed the goal (via blueprint). Install the plan.
+function submitPlan(run, rawSteps, { persist = true } = {}) {
+  requirePhase(run, PHASE.PLAN);
+  const steps = dag.normalizeSteps(rawSteps);
+  const v = dag.validate(steps);
+  if (!v.ok) throw new Error(`super-agent: invalid plan — ${v.errors.join('; ')}`);
+  if (steps.length === 0) throw new Error('super-agent: plan has no steps');
+  run.steps = steps;
+  run.phase = PHASE.EXECUTE;
+  state.record(run, { event: 'planned', steps: steps.length });
+  return persist ? state.save(run) : run;
+}
+
+// Mark a step as about to run (so nextAction reports it as in-progress, not ready).
+function markDispatched(run, stepIds, { persist = true } = {}) {
+  const want = new Set((Array.isArray(stepIds) ? stepIds : [stepIds]).map(String));
+  for (const s of run.steps) {
+    if (want.has(s.id) && s.status === dag.STATUS.PENDING) s.status = dag.STATUS.IN_PROGRESS;
+  }
+  state.record(run, { event: 'dispatched', steps: [...want] });
+  return persist ? state.save(run) : run;
+}
+
+// The driver finished a step. Record result + budget, then advance the phase if
+// the plan is now complete or stalled.
+function submitStepResult(run, stepId, { status = dag.STATUS.DONE, branch = null, result = null, tokensSpent = 0 } = {}, { persist = true } = {}) {
+  const s = run.steps.find((x) => x.id === String(stepId));
+  if (!s) throw new Error(`super-agent: unknown step ${stepId}`);
+  s.status = status;
+  if (branch) s.branch = branch;
+  if (result != null) s.result = result;
+  state.accrue(run, { tokensSpent, steps: 1 });
+  state.record(run, { event: 'step', step: s.id, status, tokensSpent });
+
+  if (dag.isComplete(run.steps)) {
+    run.phase = PHASE.INTEGRATE;
+  } else if (dag.isStalled(run.steps)) {
+    state.stop(run, 'plan stalled after a step failed');
+  }
+  return persist ? state.save(run) : run;
+}
+
+// The driver merged the worker branches.
+function submitIntegration(run, { merged = true, conflicts = [], tokensSpent = 0 } = {}, { persist = true } = {}) {
+  requirePhase(run, PHASE.INTEGRATE);
+  state.accrue(run, { tokensSpent });
+  if (Array.isArray(conflicts) && conflicts.length > 0) {
+    state.record(run, { event: 'integration-conflicts', conflicts });
+    state.stop(run, `integration conflicts in: ${conflicts.join(', ')}`);
+  } else if (!merged) {
+    state.stop(run, 'integration reported not merged');
+  } else {
+    run.phase = PHASE.VERIFY;
+    state.record(run, { event: 'integrated' });
+  }
+  return persist ? state.save(run) : run;
+}
+
+// The driver ran the verification gate (tests/build).
+function submitVerification(run, { passed = false, detail = '', tokensSpent = 0 } = {}, { persist = true } = {}) {
+  requirePhase(run, PHASE.VERIFY);
+  state.accrue(run, { tokensSpent });
+  if (passed) {
+    run.phase = PHASE.DONE;
+    run.status = 'done';
+    state.record(run, { event: 'verified', detail });
+  } else {
+    run.status = 'failed';
+    run.stopReason = `verification failed: ${detail || 'tests/build did not pass'}`;
+    state.record(run, { event: 'verification-failed', detail });
+  }
+  return persist ? state.save(run) : run;
+}
+
+function requirePhase(run, expected) {
+  if (run.phase !== expected) {
+    throw new Error(`super-agent: expected phase "${expected}" but run is in "${run.phase}"`);
+  }
+}
+
+module.exports = {
+  nextAction,
+  submitPlan,
+  markDispatched,
+  submitStepResult,
+  submitIntegration,
+  submitVerification,
+  estimateTokens,
+  DEFAULT_STEP_TOKENS,
+};

package/scripts/super-agent/state.js

@@ -0,0 +1,136 @@
+// scripts/super-agent/state.js
+//
+// Run lifecycle, persistence (so a run resumes after a crash or a new session),
+// and the budget governor for the super-agent orchestrator. Mirrors the pattern
+// of scripts/arena/state.js: the control plane is tokenless and durable, so the
+// expensive part (actually running agents) can stop and pick up again.
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
+const dag = require('./dag.js');
+
+const RUN_DIR = process.env.KODELYTH_SUPER_AGENT_DIR
+  || path.join(os.homedir(), '.kodelythecc', 'super-agent');
+
+const PHASE = Object.freeze({
+  PLAN: 'plan',
+  EXECUTE: 'execute',
+  INTEGRATE: 'integrate',
+  VERIFY: 'verify',
+  DONE: 'done',
+});
+
+function runPath(id) {
+  return path.join(RUN_DIR, `${id}.json`);
+}
+
+function createRun({ goal, limits = {}, scope = '.' } = {}) {
+  if (!goal || !String(goal).trim()) throw new Error('super-agent: a run needs a goal');
+  return {
+    id: crypto.randomBytes(6).toString('hex'),
+    goal: String(goal).trim(),
+    scope,
+    createdAt: new Date().toISOString(),
+    status: 'running',           // running | done | failed | stopped
+    phase: PHASE.PLAN,
+    steps: [],
+    budget: {
+      // 0 / null means "no cap". Caps are the governor Agent B flagged as missing
+      // — a single per-session token-budget could not bound a whole run.
+      tokenCap: limits.tokenCap || 0,
+      stepCap: limits.stepCap || 0,
+      tokensSpent: 0,
+      stepsRun: 0,
+    },
+    history: [],
+    stopReason: null,
+  };
+}
+
+function record(run, event) {
+  run.history.push({ at: new Date().toISOString(), ...event });
+}
+
+// Budget governor. Returns { ok, reason? }. Checks both the token cap and the
+// step cap; an estimate of 0 still fails if we are already over.
+function canAfford(run, estTokens = 0) {
+  const b = run.budget;
+  if (b.stepCap && b.stepsRun >= b.stepCap) {
+    return { ok: false, reason: `step cap reached (${b.stepsRun}/${b.stepCap})` };
+  }
+  if (b.tokenCap && b.tokensSpent + estTokens > b.tokenCap) {
+    return { ok: false, reason: `token cap would be exceeded (${b.tokensSpent}+${estTokens} > ${b.tokenCap})` };
+  }
+  return { ok: true };
+}
+
+function accrue(run, { tokensSpent = 0, steps = 0 } = {}) {
+  run.budget.tokensSpent += Math.max(0, tokensSpent) || 0;
+  run.budget.stepsRun += Math.max(0, steps) || 0;
+}
+
+function stop(run, reason) {
+  run.status = 'stopped';
+  run.stopReason = reason;
+  record(run, { event: 'stopped', reason });
+}
+
+function save(run) {
+  fs.mkdirSync(RUN_DIR, { recursive: true });
+  // Atomic: a crash mid-write must not corrupt a resumable run.
+  safeFs.replaceFileAtomic(runPath(run.id), JSON.stringify(run, null, 2) + '\n', 0o600);
+  return run;
+}
+
+function load(id) {
+  const raw = fs.readFileSync(runPath(id), 'utf8');
+  return JSON.parse(raw);
+}
+
+function exists(id) {
+  return fs.existsSync(runPath(id));
+}
+
+function list() {
+  if (!fs.existsSync(RUN_DIR)) return [];
+  return fs.readdirSync(RUN_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => {
+      try { return JSON.parse(fs.readFileSync(path.join(RUN_DIR, f), 'utf8')); }
+      catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+
+function summarize(run) {
+  return {
+    id: run.id,
+    goal: run.goal,
+    status: run.status,
+    phase: run.phase,
+    progress: dag.progress(run.steps),
+    budget: run.budget,
+    stopReason: run.stopReason,
+  };
+}
+
+module.exports = {
+  PHASE,
+  RUN_DIR,
+  runPath,
+  createRun,
+  record,
+  canAfford,
+  accrue,
+  stop,
+  save,
+  load,
+  exists,
+  list,
+  summarize,
+};

package/wiki/Agent-Reference.md

@@ -1,6 +1,6 @@
 # Agent Reference
 
-70 specialist subagents — all auto-routed via semantic intent routing. You never need to type agent names unless you want to.
+71 specialist subagents — all auto-routed via semantic intent routing. You never need to type agent names unless you want to.
 
 ---
 

package/wiki/FAQ.md

@@ -6,7 +6,7 @@
 
 **What is Kodelyth ECC?**
 
-An AI coding toolkit (v1.8.0) that installs into 11 AI coding platforms (13 install targets). It adds 70 specialist agents (including 8 adversarial devil-mode agents), 194 skills, 97 slash commands, 20+ automation hooks, and a compound learning system. Zero cloud, zero telemetry, all local.
+An AI coding toolkit (v1.8.0) that installs into 12 AI coding platforms (14 install targets). It adds 71 specialist agents (including 8 adversarial devil-mode agents), 196 skills, 97 slash commands, 20+ automation hooks, and a compound learning system. Zero cloud, zero telemetry, all local.
 
 **Is it free?**
 
@@ -28,7 +28,7 @@ Node.js 18 or higher.
 
 **What platforms does ECC support?**
 
-11 platforms (13 install targets): Claude Code, Windsurf (project/home), Cursor, Google Antigravity, Codex CLI, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI (project/home). Feature depth varies — see the platform support table in the README for what each platform gets.
+12 platforms (14 install targets): Claude Code, Windsurf (project/home), Cursor, Google Antigravity, Codex CLI, OpenCode, Cline, Roo Code, Aider, Kimi, Gemini CLI (project/home). Feature depth varies — see the platform support table in the README for what each platform gets.
 
 ---
 
@@ -75,7 +75,7 @@ Three layers that make Claude increasingly match your style:
 
 1. **Project Lessons** — corrections you give Claude are encoded as hard rules in `tasks/lessons.md` and applied every session
 2. **Global Memory** — past solutions recalled cross-project, auto-evolving
-3. **Semantic Routing** — 70 specialists routing from intent
+3. **Semantic Routing** — 71 specialists routing from intent
 
 **How do lessons get written?**
 
@@ -139,7 +139,7 @@ Opens automatically at `http://localhost:5173` (or your configured port).
 - **Overview** — Agent counts, installed components, config status
 - **Memory** — View, search, tag, and delete stored memories
 - **Evolve** — Analyze memory for patterns, surface high-impact solutions
-- **Catalog** — Browse all 70 agents and 194 skills with descriptions
+- **Catalog** — Browse all 71 agents and 196 skills with descriptions
 - **Sessions** — Replay session transcripts, see token usage, review lessons captured
 
 ---
@@ -254,7 +254,7 @@ Verifies SBOM, manifest, and signatures. Reports any tampering or missing artifa
 
 No. Semantic intent routing detects what you need from how you describe the problem. You never need to type `use debug-detective` — just describe the bug.
 
-**What are the 70 agents?**
+**What are the 71 agents?**
 
 62 standard specialist agents (reviewers, debuggers, architects, etc.) + 8 adversarial devil-mode agents (injection hunter, supply chain auditor, secret hunter, etc.).
 

package/wiki/Home.md

@@ -158,13 +158,13 @@ Month 3:    You try another tool. It uses pnpm. You praise the consistency.
 |---|---|---|
 | Project Lessons | `tasks/lessons.md` | Per-project hard rules from your corrections |
 | Global Memory | `~/.kodelyth/memory/` | Cross-project BM25 recall of past solutions |
-| Semantic Routing | 70 agents | Routes every message to the right specialist |
+| Semantic Routing | 71 agents | Routes every message to the right specialist |
 
 ---
 
-## Platform Support (11 platforms, 13 install targets)
+## Platform Support (12 platforms, 14 install targets)
 
-Kodelyth ECC installs on 11 AI coding platforms. Feature depth varies — hooks are a Claude Code native format with no equivalent on other platforms, and Cursor's agent system uses a different format:
+Kodelyth ECC installs on 12 AI coding platforms. Feature depth varies — hooks are a Claude Code native format with no equivalent on other platforms, and Cursor's agent system uses a different format:
 
 | Platform | Agents | Skills | Commands | Hooks | Rules |
 |---|---|---|---|---|---|
@@ -185,10 +185,10 @@ Kodelyth ECC installs on 11 AI coding platforms. Feature depth varies — hooks
 ## Wiki Pages
 
 - [Installation Guide](Installation-Guide) — all install methods, targets, profiles, bundles, OS support
-- [Agent Reference](Agent-Reference) — all 70 agents including 8 adversarial devil-mode agents
-- [Skill Reference](Skill-Reference) — all 194 skills including MCP, swarm, dashboard, and safety hooks
+- [Agent Reference](Agent-Reference) — all 71 agents including 8 adversarial devil-mode agents
+- [Skill Reference](Skill-Reference) — all 196 skills including MCP, swarm, dashboard, and safety hooks
 - [Hook Reference](Hook-Reference) — all 22+ hooks and how they work
-- [Platform Support](Platform-Support) — per-platform capabilities for 11 platforms
+- [Platform Support](Platform-Support) — per-platform capabilities for 12 platforms
 - [FAQ](FAQ) — memory, MCP server, dashboard, devil-mode, swarm, SLSA/SBOM, privacy, troubleshooting
 
 ---
@@ -199,8 +199,8 @@ Kodelyth ECC installs on 11 AI coding platforms. Feature depth varies — hooks
 |---|---|
 | **v1.8.0** | Real-time IDE-aware dashboard (Claude Code + Windsurf + Windsurf-Next + Cursor + Antigravity), cross-IDE memory protocol via MCP tools, `KODELYTH_EXTRA_IDE_WATCH` env var, 3 s SSE realtime, 373 tests |
 | **v1.7.3** | Social hype pack (5 X/Twitter SVGs + 5 thread scripts), full SVG version sync, GitHub issue templates, repo polish |
-| **v1.7.0** | Adversarial devil-mode (8 agents), MCP server, local dashboard, swarm orchestrator, cost-aware routing, self-evolving memory, SLSA L3 + SBOM, 11 platforms, 194 skills |
-| **v1.6.0** | 8 adversarial devil-mode agents, power bundles, 6 new IDE platform targets, 97 commands |
+| **v1.7.0** | Adversarial devil-mode (8 agents), MCP server, local dashboard, swarm orchestrator, cost-aware routing, self-evolving memory, SLSA L3 + SBOM, 12 platforms, 196 skills |
+| **v1.6.0** | 8 adversarial devil-mode agents, power bundles, 6 new IDE platform targets, 104 commands |
 | **v1.5.3** | Semantic intent routing — intent not keywords, code/trace paste detection, 62 agents, 188 skills |
 | **v1.5.2** | Parallel agents, `image-architect`, `/project-launch`, `/team-review`, `/lessons` |
 | **v1.5.1** | Compound learning — `capture-correction.js`, `read-lessons.js`, self-improvement workflow |

package/wiki/Installation-Guide.md

@@ -19,7 +19,7 @@ This detects your project type, installs the right component set, and wires ever
 
 ---
 
-## Targets (11 platforms, 13 install targets)
+## Targets (12 platforms, 14 install targets)
 
 Install into a specific AI tool:
 

package/wiki/Platform-Support.md

@@ -1,6 +1,6 @@
 # Platform Support
 
-Kodelyth ECC installs on 11 AI coding platforms via 13 install targets. Feature depth varies — hooks use Claude Code's native settings format and have no equivalent elsewhere; Cursor's agent system is incompatible with ECC's markdown agent format.
+Kodelyth ECC installs on 12 AI coding platforms via 14 install targets. Feature depth varies — hooks use Claude Code's native settings format and have no equivalent elsewhere; Cursor's agent system is incompatible with ECC's markdown agent format.
 
 ---
 
@@ -8,9 +8,9 @@ Kodelyth ECC installs on 11 AI coding platforms via 13 install targets. Feature
 
 | Feature | Claude Code | Roo Code | Codex CLI | Aider | Kimi | Windsurf | Antigravity | Gemini CLI | Cursor | Cline | OpenCode |
 |---|---|---|---|---|---|---|---|---|---|---|---|
-| 70 Agents | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓* | — |
-| 194 Skills | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | partial | ✓ | ✓ | — | — |
-| 97 Commands | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | ✓* | — |
+| 71 Agents | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓* | — |
+| 196 Skills | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | partial | ✓ | ✓ | — | — |
+| 104 Commands | ✓ | ✓ | ✓ | ✓ | ✓ | — | ✓ | — | — | ✓* | — |
 | 22+ Hooks | ✓ | — | — | — | — | — | — | — | — | — | — |
 | Rules | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
 | Auto lessons | ✓ | — | — | — | — | — | — | — | — | — | — |
@@ -36,8 +36,8 @@ npx kodelyth-ecc
 **File layout:**
 ```
 ~/.claude/
-├── agents/          → 70 specialist agents
-├── skills/          → 194 skills
+├── agents/          → 71 specialist agents
+├── skills/          → 196 skills
 ├── commands/        → 97 slash commands
 ├── rules/           → always-on coding standards + routing
 └── hooks/           → hooks.json (wired into settings.json)
@@ -185,8 +185,8 @@ npx kodelyth-ecc --target antigravity
 **File layout:**
 ```
 .agent/
-├── skills/          → 70 agents (mapped to Antigravity's skills system)
-├── workflows/       → 97 commands (mapped to Antigravity's workflows)
+├── skills/          → 71 agents (mapped to Antigravity's skills system)
+├── workflows/       → 104 commands (mapped to Antigravity's workflows)
 └── rules/           → rules + 4 featured ECC skills as context
 ```
 

package/wiki/Skill-Reference.md

@@ -1,6 +1,6 @@
 # Skill Reference
 
-Skills are domain knowledge and workflow definitions loaded into your session with a slash command. 194 skills total.
+Skills are domain knowledge and workflow definitions loaded into your session with a slash command. 196 skills total.
 
 Skills provide deep, actionable guidance — patterns, checklists, code templates, anti-patterns — that agents draw on when they are active. Rules define *what* to do; skills define *how* to do it.
 
@@ -40,7 +40,7 @@ Type the skill name with a `/` prefix. Skills load instantly and activate for th
 |---|---|---|
 | Memory Protocol | `/memory` | BM25 recall workflow, capture triggers, review-pending flow |
 | Memory Evolve | `/memory-evolve` | Self-improving memory analysis, pattern extraction (v1.7.0) |
-| Lessons | `/lessons` | Load/save/manage `tasks/lessons.md` on all 11 platforms |
+| Lessons | `/lessons` | Load/save/manage `tasks/lessons.md` on all 12 platforms |
 | Configure ECC | `/configure-ecc` | Customize agents, hooks, and rules for your project |
 | Quickstart | `/kodelyth-quickstart` | 5-minute tour of the entire toolkit |
 
@@ -276,14 +276,14 @@ AI:   → Loading /smart-debug (debugging workflow signal)
 - **8 specialized skills** — ClickHouse, SEO, video, research
 - **8 devil-mode security skills** — red-team, penetration testing (v1.7.0)
 
-**Total: 194 skills**
+**Total: 196 skills**
 
 ---
 
 ## Installing All Skills
 
 ```bash
-# Download and cache all 194 skills locally
+# Download and cache all 196 skills locally
 npx kodelyth-ecc --profile full
 ```