# 🐦⬛ RavenClaws Roadmap
> **Strategic Directive (2026-08-13 re-analysis):** RavenClaws must be able to do
> anything **OpenClaw, NanoClaw, ZeroClaw, OpenFang, nanobot, ironclaw, and Claude
> Cowork** can do — and just do it better. The fastest path is to lift the working
> Rust reference implementations already present in the sibling project
> **RavenAssistant01** (see "v0.11 — Universal Parity: The Merge Phase" below and
> `RAVENCLAWS-MERGE.md` / `RAVENCLAWS-IMPROVEMENTS.md`).
**Date:** 2026-07-02 *(re-analyzed 2026-08-13)*
**Version:** v1.4.0 — Universal Parity: The Merge Phase 🐦⬛
**Previous Release:** v1.3.0 (2026-07-02) — Advanced Reasoning
**Current Commit:** (v1.4.0 — K8s operator + web policy + memory tiers + messaging)
**CI Status:** Build & Release ✅ · Container Build ✅ · Security Scan ✅
**Test Count:** 587 unit tests · 114 verification tests · 0 failures
**v1.0 Hardening Progress:** v0.9.4–v0.9.16 all complete ✅. **v0.9.14 closed ALL remaining metrics and polish gaps** — token tracking, tool calls counter, `/ready` caching, MCP params optionality, RavenFabric pipe policy, `--eval /dev/null` handling, `imagePullPolicy` verification. **v0.9.15 closed ALL ecosystem expansion gaps** — vLLM docs + verification tests, llama.cpp docs + verification tests, distroless HTTP testing docs, website docs pages for both providers. **v0.9.16 closed the last v1.0 blocker** — SSE MCP ecosystem verification: `--mcp-sse-server` CLI flag wired, SSE transport for MCP client config, MCP integration tests (stdio + SSE), SSE transport documentation. All gaps identified in v0.9.11 rpi5 deployment feedback are now closed. **v1.0 is released — the stable release. All exit criteria are met.** **v1.0.1 fixes the 4 remaining critical rpi5 issues: `/tools/{name}` 404, RavenFabric URL builder, `/execute` empty result, and distroless SIGHUP — all resolved.** **v1.0.1 also adds WASM plugin system (Plugin ABI v1, 11 unit tests) and SQLite conversation persistence (15 unit tests) — 485 total unit tests across 20 modules.**
**Strategic Positioning:** RavenClaws is the **"Temporal for AI agents"** — the lightweight, durable execution engine for AI agents. Unlike LangGraph (complex graphs), Temporal (heavy infra), or CrewAI (Python-only), RavenClaws gives you reliable, checkpointed agent execution in a ~5 MB binary that runs on a Raspberry Pi. **Durable execution (checkpoint/resume) is implemented in v0.9.12** — agent loop saves state after each iteration and survives process restarts. **Multi-agent patterns (debate, review-loop, research-synthesize, voting) are implemented in v0.9.13.** **Production stability verified in v0.9.11 rpi5 audit: 3,597 requests, 0 errors, 10 Mi RSS, 0 restarts over 7.5 hours.**
**Key messaging:**
- "Your agents survive crashes" — durable execution means no lost work ✅ **v0.9.12**
- "Multi-agent patterns out of the box" — debate, review, research, voting as built-in primitives ✅ **v0.9.13**
- "Production-proven on Raspberry Pi" — 3,597 requests, 0 errors, 10 Mi RSS ✅ **v0.9.11 audit**
- "Edge-native" — runs on RPi5, IoT, containers, anywhere with 3MiB RAM
- "Rust-safety" — compile-time guarantees, no runtime errors
- "Open-source, self-hosted" — no vendor lock-in, no per-seat pricing
RavenClaws operates **autonomously** — with a heartbeat, working on tasks over long
periods independently, without requiring constant human supervision. It plans,
executes, reflects, and adapts across hours, days, or weeks.
RavenClaws orchestrates **swarms at any scale** — from a handful of specialized
collaborators to **thousands of workers**, each with unique traits, capabilities, and
personalities. A swarm is TRULY a swarm: unbounded, self-organizing, and emergent.
RavenClaws provisions, configures, and manages its own sub-agents and worker
instances dynamically based on task requirements — no fixed limit, no artificial
cap. The swarm grows and shrinks organically as work demands.
All of this happens **efficiently and securely** — every agent communication is
policy-gated, audited, and sandboxed. The five pillars (Secure, Small, Efficient,
Robust, Simple) apply to the swarm just as they apply to the single agent.
### The rpi5 Verdict — and Our Response
Real-world testing on a Raspberry Pi 5 (K3s, aarch64, 8GB RAM) revealed that RavenClaws
v0.9.3 was **functional but not yet a primary agent**. The feedback was honest:
> *"RavenClaws works as a lightweight, secure agent runtime — it runs, connects to LLMs,
> executes agent loops, and manages swarms. But it's not a drop-in replacement for OpenClaw."*
**By v0.9.8, all 13 resolved issues from feedback are confirmed working.**
**10 critical bugs fixed. 4 documentation gaps closed. 4 feature requests documented.**
**7 production hardening items deferred to v0.9.9 (community health files, container image size, init container chown, graceful shutdown for heartbeat/all modes, NetworkPolicy docs, Secret reference docs, migration docs).**
**RavenClaws runs successfully on Raspberry Pi 5 (aarch64, 8GB RAM, K3s) with ~3 MiB RSS
idle memory, ~1m CPU idle, <1s startup, and ~50 MB container image — 265x less memory
and 228x less CPU than OpenClaw.**
**The remaining gaps are now strategic, not tactical.** The feedback's deep analysis
identified three game-changing features (Tier 1) that would make RavenClaws uniquely
valuable, not just "good enough." These are now the focus of v0.9.9+, alongside the
7 production hardening items deferred from v0.9.8.
**The strategic insight from the feedback:**
> *"RavenClaws should be the 'Temporal for AI agents' — durable execution, multi-agent
> orchestration, and edge-native deployment, all in a 15.8MB image. Not a general-purpose
> agent framework, but the reliable infrastructure layer that other frameworks build on."*
**The three game-changing features that make this real:**
1. **Durable execution** (checkpoint/resume) — the Temporal killer for agents
2. **SSE MCP transport** — unlocks the entire MCP ecosystem
3. **Multi-agent patterns as primitives** — debate, review-loop, research-synthesize shipped in the box
These three features, combined with RavenClaws' existing strengths (15.8MB, 3MiB RAM,
distroless, Rust-safety), would make it the **most compelling agent framework for
production deployments** — especially on constrained hardware.
**All gaps from v0.9.3 feedback — resolved status:**
| Gap | Root Cause | Status |
|---|---|---|
| Tool execution fails with non-structured models | Agent loop requires `FINAL:` or structured `tool_calls` | ✅ **v0.9.4**: `--no-final-required` + text-based fallback |
| `--exec` produces no output for most models | Error path suppresses last response | ✅ **v0.9.4**: `--no-final-required` flag + response logging |
| No agent execution HTTP endpoints | Server mode is status-only | ✅ **v0.9.6**: `/chat`, `/execute`, `/tools`, `/tasks/{id}`, `/health/deep` |
| MCP client can't connect to SSE servers | SSE transport was stubbed | ✅ **v0.9.3**: SSE transport implemented |
| MCP server is stdio-only | SSE transport was stubbed | ✅ **v0.9.3**: SSE transport implemented |
| No TOML config for MCP servers | CLI-only, single connection | ✅ **v0.9.6**: `McpConfig` + `McpServerConfig` structs |
| Tool execution silently fails | No fallback for non-structured models | ✅ **v0.9.5**: Text-based tool call detection |
| Sandbox breaks with read-only root FS | Hardcoded `/tmp` workdir | ✅ **v0.9.8**: Defaults to `/tmp/ravenclaws-sandbox` (writable even with readOnlyRootFilesystem) |
| Heartbeat state may corrupt on SIGTERM | No graceful shutdown hook | ✅ **v0.9.10**: Drop impl calls persist_state() on HeartbeatAgent |
| Init container doesn't chown workspace | Missing `chown` in K8s manifest | ✅ **v0.9.10**: initContainers with busybox chown in deployment.yaml |
| SwarmTopology enum mismatch | TOML deserialization expects string, not array | ✅ **v0.9.4**: Fixed |
| `agent_count` field not recognized | Missing serde alias on `max_workers` | ✅ **v0.9.4**: Fixed |
| `[swarm.profiles]` TOML syntax fails | Only `[[swarm.profiles]]` array-of-tables supported | ✅ **v0.9.6**: `deserialize_profiles` — accepts both |
| Heartbeat goal error message unclear | Missing example in error | ✅ **v0.9.4**: Fixed |
| LiteLLM API key docs wrong | References `openclaw-secrets` instead of `litellm-secrets` | ✅ **v0.9.8**: `api_key` field documented with env var example |
| `--serve` mode not documented | No docs page for HTTP server mode | ✅ **v0.9.6**: Server mode docs added |
| OpenTelemetry warning on startup | OTEL exporter warns if no collector configured | ✅ **v0.9.8**: Suppressed when OTEL disabled |
| Server port not configurable via env var | Only `--port` CLI flag | ✅ **v0.9.6**: Env var override added |
| Config hot-reload not supported | No SIGHUP handler | ✅ **v0.9.6**: `wait_for_sighup()` + SIGHUP handler |
| NetworkPolicy blocks LLM egress | New pod labels not in LiteLLM ingress policy | ❌ **v0.9.10**: No NetworkPolicy in deployment.yaml |
| Secret reference uses wrong key | `LITELLM_API_KEY` doesn't exist in `openclaw-secrets` | ✅ **v0.9.8**: Uses `ravenclaws-secrets` consistently |
| Agent loop logs show `<no thought>` | Log only looks for `THOUGHT:` prefix | ✅ **v0.9.4**: Response content logging added |
| LLM response content not logged | No debug-level logging of responses | ✅ **v0.9.4**: `debug!` log after each response |
| MCP server stdin closes before processing | stdio-only transport, no SSE fallback | ✅ **v0.9.3**: SSE transport implemented |
| MCP client can't connect to SSE servers | `Sse` variant returns `Err("not implemented")` | ✅ **v0.9.3**: SSE transport implemented |
| No `[mcp]` section in TOML config | CLI flags only, no config struct | ✅ **v0.9.6**: `McpConfig` struct added |
| Only one MCP client connection | Single `--mcp-command` flag | ✅ **v0.9.7**: `McpClientManager` — multi-client |
| Workspace permission denied | Init container doesn't `chown` to UID 65532 | ✅ **v0.9.10**: initContainers with busybox chown in deployment.yaml |
| Tool execution not working with deepseek-v4-pro | Model doesn't emit structured `tool_calls` | ✅ **v0.9.5**: Text-based tool call detection |
| Graceful shutdown on SIGTERM | No evidence of graceful shutdown in logs | ⚠️ **v0.9.8**: Server mode only — heartbeat and other modes still lack signal handling |
| Sandbox default workdir is `/tmp/ravenclaws-sandbox` | Hardcoded path requires writable `/tmp` | ✅ **v0.9.8**: `/tmp` is writable even with readOnlyRootFilesystem; falls back to `std::env::temp_dir()` |
| Network policy must allow egress to LiteLLM | New pod labels not in `litellm-ingress` policy | ❌ **v0.9.10**: No NetworkPolicy in deployment.yaml |
| API key secret references wrong secret | Docs reference `openclaw-secrets` but key is in `litellm-secrets` | ✅ **v0.9.8**: Uses `ravenclaws-secrets` consistently |
| `--exec` agent loop never completes for non-FINAL models | Error path suppresses last response | ✅ **v0.9.4**: `--no-final-required` flag |
| Agent loop progress shows `<no thought>` | Log only looks for `THOUGHT:` prefix | ✅ **v0.9.4**: Response content logging |
| No way to see LLM response content in logs | No debug-level logging of responses | ✅ **v0.9.4**: `debug!` log |
| MCP Server is stdio-only — no SSE transport | `Sse` variant returns `Err("not implemented")` | ✅ **v0.9.3**: SSE transport implemented |
| MCP Client is stdio-only — cannot connect to SSE servers | `Sse` variant returns `Err("not implemented")` | ✅ **v0.9.3**: SSE transport implemented |
| No `[mcp]` section in TOML config | CLI flags only, no config struct | ✅ **v0.9.6**: `McpConfig` + `McpServerConfig` structs |
| Only one MCP client connection supported | Single `--mcp-command` flag | ✅ **v0.9.7**: `McpClientManager` — multi-client |
| `--exec` mode works when model uses `FINAL:` format | Confirmed working — model behavior, not code bug | ✅ Documented |
| `--mode single` works after workspace fix | ✅ Confirmed working | ✅ |
| `--mode swarm` works with 3 parallel agents | ✅ Confirmed working | ✅ |
| `--mode supervisor` works | ✅ Decomposes tasks into subtasks | ✅ |
| `--mode orchestrate` works | ✅ Swarm orchestration works | ✅ |
| `--background` mode works after workspace fix | ✅ Confirmed working | ✅ |
| `--heartbeat` mode works with explicit goal | ✅ Confirmed working | ✅ |
| `--repl` mode works after workspace fix | ✅ Interactive use requires TTY | ✅ |
| `--eval` mode works after workspace fix | ✅ Confirmed working | ✅ |
| HTTP server endpoints verified | ✅ All 3 endpoints working | ✅ |
| Tool execution not working with deepseek-v4-pro:cloud | Model doesn't emit tool calls in any format | ✅ **v0.9.5**: Text-based fallback |
| MCP server stdin closes before processing | stdio-only transport, hard to test via kubectl exec | ⚠️ Tracked in v0.9.9 (SSE MCP tests) |
| `--mcp-command` fails silently | No error output visible | ❌ Tracked in v0.9.9 (MCP error handling) |
| No `/chat`, `/execute`, `/tools` HTTP endpoints | Server mode is status-only | ✅ **v0.9.6**: 6 new endpoints |
| No LLM connectivity check in health endpoint | `/health` only checks process liveness | ✅ **v0.9.6**: `/health/deep` |
| No config reload without restart | No SIGHUP handler | ✅ **v0.9.6**: `wait_for_sighup()` |
| OpenTelemetry warning on startup | OTEL exporter warns if no collector configured | ✅ **v0.9.8**: Suppressed when OTEL disabled |
| `--serve` mode not documented | No docs page for HTTP server mode | ✅ **v0.9.6**: Server mode docs |
| Server port not configurable via env var | Only `--port` CLI flag | ✅ **v0.9.6**: Env var override |
| Readiness probe doesn't verify LLM connectivity | `/ready` returns OK immediately | ✅ **v0.9.6**: 503 until fully initialized |
| Readiness LLM connectivity check | `/ready` doesn't verify LLM is reachable | ✅ **v0.9.7**: Lightweight LLM probe |
**The plan:** Six rapid releases (v0.9.4 → v0.9.9) closed every gap identified in
rpi5 deployment feedback. v0.9.10 closed all production hardening gaps. v0.9.11
delivered strategic features (dedup, Azure, eval integration). v0.9.12 delivered
durable execution (checkpoint/resume). v0.9.13 delivered multi-agent patterns.
**v0.9.14 closed all remaining metrics and polish gaps** ✅ — token tracking,
tool call counting, `/ready` caching, MCP server `params` optionality, RavenFabric
pipe policy, empty eval config validation, and `imagePullPolicy` verification.
**v0.9.15+ shifts to ecosystem expansion** — vLLM/llama.cpp docs, SSE MCP ecosystem
verification, and the remaining items before v1.0. After that, v1.0 is truly
production-ready — a primary agent that can replace OpenClaw, Manus, or any cloud
agent, while being smaller, more secure, and more efficient.
**Strategic shift (v0.9.9+):** The feedback's deep analysis revealed that RavenClaws
should not just catch up to competitors — it should lead in three areas where no
other framework excels:
1. **Durable execution** (checkpoint/resume) — the #1 gap across ALL agent frameworks ✅ **v0.9.12**
2. **Multi-agent patterns as built-in primitives** — debate, review-loop, research-synthesize ✅ **v0.9.13**
3. **Edge-native deployment** — already winning, make it undeniable ✅ **v0.9.11 audit confirms: 10 Mi RSS, 0 errors, 3,597 requests**
These three features, combined with RavenClaws' existing strengths, make the
"Temporal for AI agents" positioning real. **All three game-changing features are now implemented.**
**Core Principles** — every decision is measured against these five. If a feature
can't be added without breaking one, it doesn't ship in core.
| Pillar | What it means in practice |
|---|---|
| 🔒 **Secure** | Memory-safe Rust (`unsafe` forbidden). Fail-closed. No creds in config, TLS enforced, every tool call policy-gated and audited. Signed releases, SBOM, verified supply chain. |
| 🪶 **Small** | One static binary, distroless image, lean dependency tree. Target < 15 MB stripped, < 30 MB image. |
| ⚡ **Efficient** | Native performance, low idle memory (< 20 MB RSS), fast cold start (< 50 ms), streaming everywhere. |
| 🛡️ **Robust** | No `panic`/`unwrap` on hot paths. Retries with backoff, provider fallback, deterministic config, high coverage. |
| ✨ **Simple** | One command to run. Sensible defaults. Zero-config for common cases. No external services required for single-agent use. |
### Non-goals
- Not a heavyweight orchestration platform — RavenClaws stays a small worker; large-scale mesh coordination is delegated to **RavenFabric**.
- Not a UI/IDE — RavenClaws is a headless binary + library; frontends consume it.
- No telemetry phone-home, ever. Observability is opt-in and self-hosted.
---
## Current State
**Version:** 1.3.0 — Advanced Reasoning 🧠
**Stats:** 25 source modules, ~20,000 LOC, 7 LLM providers (+ generic `openai-compatible`), 5 built-in tools (+web_search, +browser), **554 unit tests**, 119 verification tests across 13 modules (+vllm, +llamacpp, +mcp), **multi-modal input support**, **browser automation tool** (10 CDP actions), **graceful degradation under load**, **self-healing engine**, **advanced reasoning** (tree-of-thought, self-reflection), multi-arch CI with signed images + SBOM, official Helm chart, WASM plugin system, SQLite conversation persistence, durable execution, multi-agent patterns.
**Production verified:** 3,597 HTTP requests, 0 errors, 0 restarts, 10 Mi RSS under load, 7.5h uptime on rpi5 K3s (v0.9.11 audit).
**rpi5 Deployment Verdict (v0.9.11):** All 13 resolved issues from feedback confirmed working. 10 critical bugs fixed. 4 documentation gaps closed. 4 feature requests documented for future versions. **All production hardening items completed.** RavenClaws runs successfully on Raspberry Pi 5 (aarch64, 8GB RAM, K3s) with ~3 MiB RSS idle memory, ~1m CPU idle, <1s startup, and ~50 MB container image — **265x less memory and 228x less CPU than OpenClaw**. **v1.0.1 closes the final 4 critical rpi5 issues: `/tools/{name}` 404, RavenFabric URL builder, `/execute` empty result, and distroless SIGHUP — all resolved.**
**v0.9.11 Comprehensive Performance Audit (2026-06-29, 7.5h test session):**
- **3,597** HTTP requests served, **0 errors**, **0 restarts** — production-stable
- **10 Mi RSS** after heavy testing (only +2 Mi from idle of 8 Mi) — no memory leak
- **All 8 HTTP endpoints** verified — `/health` in 3ms, `/chat` in 899ms, `/ready` in 1,259ms
- **All 5 CLI modes** verified — single (1.69s), supervisor (1.10s), swarm (3.05s), orchestrate (~2.5s), eval (~0.5s)
- **`/ready` now waits for LLM connectivity check** (1.26s) — improvement from v0.9.9
- **`--no-final-required` is essential** — without it, agent loop never completes with `deepseek-v4-pro:cloud`
- **Token tracking shows 0** — metrics gap, counter not wired to LLM responses
- **Tool calls counter stuck at 0** — needs verification with tool-invoking prompt
- **Distroless container trade-offs confirmed:** no `npx` (MCP clients fail), no `curl`/`wget` (HTTP testing requires port-forward), no `kill` (SIGHUP config reload requires procfs mount)
- **Overall verdict:** Production-ready — deploy without hesitation. Memory stability and zero errors make this suitable for 24/7 operation.
**Strategic focus (v0.9.14):** ✅ **All completed.** Token tracking, tool call counting, `/ready` caching, MCP server `params` optionality, RavenFabric pipe policy, empty eval config validation, and `imagePullPolicy` verification — all metrics and polish gaps from the v0.9.11 rpi5 audit are now closed.
**Strategic focus (v0.9.15):** ✅ **All completed.** vLLM docs + verification tests, llama.cpp docs + verification tests, distroless HTTP testing docs, website docs pages for both providers — all ecosystem expansion gaps from the v0.9.11 rpi5 audit are now closed.
**Strategic focus (v0.9.16):** ✅ **All completed.** `--mcp-sse-server` CLI flag wired, SSE transport for MCP client config, MCP integration tests (stdio + SSE), SSE transport documentation — the last v1.0 blocker is closed. **All v1.0 exit criteria are met. v1.0 is next — the stable release.**
| Component | Status | Details |
|---|---|---|
| Single agent (single-provider) | ✅ Working | Sends one prompt, logs response, exits |
| Single agent (multi-model) | ✅ Working | Iterates all providers, logs each response |
| **Swarm mode (single-provider)** | ✅ **v0.6** | Multiple parallel agents with different personas (analytical/creative/pragmatic); no fixed limit |
| **Supervisor mode (single-provider)** | ✅ **v0.6** | Task decomposition, sub-agent spawning, result aggregation |
| **Swarm mode (multi-model)** | ✅ **v0.6** | Parallel agents across different LLM providers; scales to any number |
| **Supervisor mode (multi-model)** | ✅ **v0.6** | Provider-aware task decomposition and assignment |
| LLM providers (7 + generic) | ✅ Working | LiteLLM, OpenAI, OpenRouter, Ollama, **Anthropic**, **Azure OpenAI**, **OpenAI-Compatible** (unified trait); generic `openai-compatible` unlocks vLLM, llama.cpp, LM Studio, TGI, Groq, Together AI, Fireworks, DeepInfra |
| CLI & env-var overrides | ✅ Working | `--provider`, `--endpoint`, `--model`, layered TOML→env→flags |
| Config validation | ✅ Working | TLS enforcement, endpoint checks |
| Container & K8s security | ✅ Working | Distroless, non-root, read-only FS, dropped caps, seccomp, RBAC |
| CI/CD pipeline | ✅ Implemented | fmt + clippy `-D warnings` + test, 5-target builds, multi-arch images, **Cosign + SBOM + provenance + Trivy**, crates.io publish, releases — cross-compilation deps installed for all targets |
| Security scanning | ✅ Implemented | CodeQL, cargo-audit, cargo-deny, cargo-outdated, cargo-udeps, Trivy (FS + config), Hadolint, Kubescape, OSSF Scorecard, dependency review — all SARIF results uploaded to GitHub Security tab |
| Verification suite | ✅ Working | 114 system/integration checks · 10 modules · 4 targets (`scripts/verify.sh`: local, Docker, Linux, K8s, security, performance, LLM-quality, swarm, eval) — shell-orchestrated, requires live services |
| Eval harness | ✅ **v0.7.4** | `--eval <path>` mode with 7 assertion types, run traces, text/JSON reports, 24 unit tests + 20 verification tests, sample configs in `tests/eval/` |
| Multi-model routing | ✅ Working | `next_client()` round-robin + fallback chain with circuit breaker |
| RavenFabric integration | ✅ **v0.6.1** | Full client module (`RavenFabricClient`) with health, list_agents, execute, broadcast; wired into all agent modes; 12 unit tests |
| `--exec` one-shot mode | ✅ **v0.9.4** | `--no-final-required` flag, response logging, default system prompt with `FINAL:` instructions. Models that don't emit `FINAL:` now work with `--no-final-required`. |
| Rust unit tests | ✅ Working | 460 tests across all 18 modules; `mockito`-based HTTP tests for all 6 providers + RavenFabric |
| Agent loop / ReAct planning | ✅ Working | perceive→plan→act→observe with max-iteration guard, `FINAL:` marker detection, configurable via `--max-iterations` |
| Tool-use / function calling | ✅ **v0.9.5** | Tool abstraction + registry + **5 built-in tools** (+web_search) + **MCP tool discovery** + agent loop wiring + **text-based tool call detection fallback** + **tool execution logging** + **configured web search endpoint**. Tool execution now works with models that don't emit structured tool calls (e.g., `deepseek-v4-pro:cloud`). |
| Deny-by-default policy | ✅ **Wired to agent loop** | `PolicyEngine` validates ALL tool calls before execution (commit 51e42b0) |
| Sandboxed execution | ✅ **v0.9.8** | Configurable workdir via `RAVENCLAWS_SANDBOX_WORKDIR` env var or `sandbox.workdir` config field. Defaults to `/tmp/ravenclaws-sandbox` (writable even with readOnlyRootFilesystem). Falls back to `std::env::temp_dir()`. |
| Audit log | ✅ **Wired to agent loop** | HMAC-SHA256 chained, tamper-evident, emits events for all tool calls (commit 51e42b0) |
| Streaming responses | ✅ Working | SSE streaming for LiteLLM, default non-streaming fallback for others |
| Conversation memory | ✅ Working | `ConversationMemory` struct with configurable max history, auto-trim |
| Interactive REPL | ✅ Working | `--repl` flag with stdin loop, streaming output, `/exit` `/reset` commands |
| System prompt / persona | ✅ Working | `LLMConfig.system_prompt` field, CLI `--system-prompt`, env var override |
| MCP client | ✅ **v0.9.7** | JSON-RPC 2.0 over stdio + SSE transport. `McpClientManager` supports multiple servers from TOML config + CLI `--mcp-command`. Tools registered into `ToolRegistry` for both `--exec` and `--serve` modes |
| **MCP server** | ✅ **v0.7** | Exposes RavenClaws tools over stdio via MCP protocol; `--mcp-server` flag; policy-checked and audited. SSE transport also implemented (v0.9.3) |
| **HTTP server mode** | ✅ **v0.9.6** | Long-running server with `/health`, `/ready`, `/metrics`, `/health/deep`, `/chat`, `/execute`, `/tools`, `/tools/{name}`, `/tasks/{id}` endpoints; `--serve` flag; fixes k8s CrashLoopBackOff. Readiness LLM connectivity check added in v0.9.7. |
| **OpenTelemetry tracing** | ✅ **v0.7.2** | Opt-in distributed tracing with OTLP gRPC/stdout exporter; `#[instrument]` spans on agent loop, HTTP server, tools, LLM calls |
| Native Anthropic provider | ✅ Working | Direct Claude API with tool use, token tracking (v0.5.3) |
| Retry / fallback / circuit breaker | ✅ Working | Exponential backoff, token budgets, provider fallback chain (v0.5.1) |
| Pre-built binary releases | 📋 Wired, untagged | CI produces them on tag; none released yet |
| `RavenFabricClient` wired to agent loop | ✅ **v0.9.8** | `health()` called after each LLM response; wired to all run_single/swarm/supervisor variants |
| `ProviderFallbackChain` wired to agent loop | ✅ **v0.9.8** | Used on primary LLM failure in both agent loop variants; configs cloned out of mutex for async safety |
| `TokenBudget` wired to agent loop | ✅ **v0.9.8** | Checked before every LLM call; returns SecurityViolation if < 100 tokens remaining |
| `AgentMessageBus` wired to swarm | ✅ **v0.9.8** | Created and shared across sub-orchestrators; `send()` and `format_for_prompt()` used in swarm execution |
| `SwarmHealthMonitor` wired to swarm | ✅ **v0.9.8** | `check_health()` called during swarm execution; dead agents detected and logged |
| `WebSearchConfig` wired to web search tool | ✅ **v0.9.5** | `ToolRegistry::with_config()` reads web search endpoint from config |
| `--provider anthropic` CLI flag | ✅ **v0.9.3** | Now selects Anthropic provider correctly |
| `--webhook-port` CLI flag | ✅ **v0.9.3** | Now configures the scheduler's webhook server |
| Audit log mutex `unwrap()` | ✅ **v0.9.3** | Replaced with `lock_entries()` helper — mutex poisoning no longer panics |
| MCP SSE transport | ✅ **v0.9.3** | Client and server SSE transport implemented; 7 tests passing |
| MCP TOML config section | ✅ **v0.9.6** | `McpConfig` + `McpServerConfig` structs with `[mcp]` TOML section |
| Multi-MCP-client support | ✅ **v0.9.6** | `McpConfig` supports `[[mcp.servers]]` array for declaring multiple MCP server processes |
| Server agent execution endpoints | ✅ **v0.9.6** | 6 new endpoints: `/chat`, `/execute`, `/tasks/{id}`, `/tools`, `/tools/{name}`, `/health/deep` |
| Community health files | ✅ **v0.9.10** | `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `FUNDING.yml`, issue templates, PR template — all created |
| Container image size | ❌ **v0.9.10** | ~50 MB — exceeds 30 MB target. Multi-stage build with distroless base, but no UPX compression. RavenFabric agent binary (~15 MB) included unconditionally. |
| Library re-exports | ✅ **v0.9.3** | All 9 modules now re-exported from `src/lib.rs` |
| Git hooks (pre-commit / pre-push) | ✅ Working | `.githooks/` — fmt, clippy, tests, binary size, secrets on commit; +release build, Docker, security on push |
| Structured function calling | ✅ Working | OpenAI Tools format for OpenAI/LiteLLM/OpenRouter/Anthropic |
| **Human-in-the-loop approvals** | ✅ **v0.8** | `--require-approval` flag prompts for sensitive tool calls; audited |
| **Prompt-injection defense** | ✅ **v0.8** | `InjectionDetector` with 50+ patterns, instruction-boundary enforcement, output schema validation; wired to both agent loops; audited |
| Multi-modal input | ✅ **v1.1.0** | `ContentPart` enum, `load_image()`, `--image` CLI flag, multi-modal serialization for all 5 providers, agent loop integration, library exports |
| Generic `openai-compatible` provider | ✅ **v0.9.3** | Unlocks vLLM, llama.cpp, LM Studio, TGI, Groq, Together AI, Fireworks, DeepInfra |
| `--exec` mode `FINAL:` fallback | ✅ **v0.9.4** | `--no-final-required` flag lets any non-tool-call response complete the loop |
| Agent loop response logging | ✅ **v0.9.4** | `debug!` log after each LLM response in both agent loops — shows length + preview |
| Tool execution reliability | ✅ **v0.9.5** | Text-based tool call detection fallback + debug logging + configured web search endpoint |
| Configurable sandbox workdir | ✅ **v0.9.8** | Configurable via `RAVENCLAWS_SANDBOX_WORKDIR` env var or `sandbox.workdir` config field |
| Graceful shutdown for all modes | ✅ **v0.9.10** | Unified `ShutdownFlag` with SIGTERM/SIGINT handlers for single, swarm, supervisor, orchestrate, heartbeat, and scheduler modes. Heartbeat checks flag between ticks with 1s granularity. |
| Init container `chown` in K8s | ✅ **v0.9.10** | `k8s/deployment.yaml` has `initContainers` section with busybox chown to UID 65532. |
| LiteLLM API key documentation | ✅ **v0.9.8** | `api_key` field documented in config reference with correct `litellm-secrets` reference |
| Heartbeat `goal` error message | ✅ **v0.9.4** | Now includes example: `--heartbeat-goal "Monitor system health and report anomalies"` |
| Readiness probe LLM check | ✅ **v0.9.7** | `/ready` now sends lightweight LLM probe with 5s timeout, returns 503 if unreachable |
| Network policy documentation | ❌ **v0.9.10** | No NetworkPolicy in `k8s/deployment.yaml`. Helm chart has one but disabled by default (`networkPolicy.enabled: false`). No docs for required egress rules. |
| Secret reference documentation | ❌ **v0.9.10** | K8s deployment uses `ravenclaws-secrets` but no docs explain the expected secret keys or format. No example `secretKeyRef` YAML in docs. |
| OTEL warning suppression | ✅ **v0.9.8** | No warning when OTEL is disabled; only warns when enabled but no endpoint configured |
### ✅ v0.4.0 Released (2026-06-03)
All v0.4 blockers resolved and shipped:
- ✅ Security features wired to agent loop (commit `51e42b0`)
- ✅ Structured function calling (OpenAI Tools format)
- ✅ 274 unit tests + 94 verification tests
- ✅ CI/CD pipeline green (fmt, clippy, test, security scans)
**Known limitations (documented, not blockers):**
- k8s Deployment enters CrashLoopBackOff — server mode planned for v0.7
- SSE transport for MCP not yet implemented (stdio only in v0.5.2)
- Multi-modal input (images) — Anthropic client has stub, not wired to CLI
### 🔧 Critical Blockers (v0.5 Release)
These must be resolved before v0.5 can ship:
1. ~~**Code duplication across OpenAI-compatible clients**~~ ✅ Fixed v0.5.0 — unified `OpenAICompatibleClient`
2. ~~**No provider fallback/retry logic**~~ ✅ Fixed v0.5.1 — exponential backoff, circuit breaker
3. ~~**No token budget tracking**~~ ✅ Fixed v0.5.1 — `TokenBudget` struct with cost estimation
4. ~~**No MCP integration**~~ ✅ Fixed v0.5.2 — full MCP client with stdio transport
5. ~~**No native Anthropic provider**~~ ✅ Fixed v0.5.3 — direct Claude API with tool use
### ✅ Resolved (v0.1 → v0.5.3)
1. ~~**`Cargo.lock` is git-ignored, but `--locked` is used in CI**~~ ✅ Fixed — lockfile committed
2. ~~**Dockerfile cross-compile fails (no cross-linker)**~~ ✅ Fixed — `gcc-aarch64-linux-gnu` + linker config
3. ~~**RavenFabric agent download unverified**~~ ✅ Fixed — SHA256SUMS verification
4. ~~**CI cross-compilation missing toolchain deps**~~ ✅ Fixed — `musl-tools`, `libc6-dev-arm64-cross`
5. ~~**`--exec` dead code**~~ ✅ Fixed — fully implemented with streaming
6. ~~**Client code duplicated 4×**~~ ✅ Fixed v0.5.0 — unified `OpenAICompatibleClient`
7. ~~**No conversation memory**~~ ✅ Fixed — `ConversationMemory` with auto-trim
8. ~~**No REPL mode**~~ ✅ Fixed — `--repl` with `/exit`, `/reset`
9. ~~**No agent loop**~~ ✅ Fixed — `run_agent_loop()` with max-iteration guard
10. ~~**No tool system**~~ ✅ Fixed — 4 built-in tools + registry + agent loop wiring
11. ~~**No security infrastructure**~~ ✅ Fixed — `PolicyEngine`, `Sandbox`, `AuditLog` implemented
12. ~~**No retry/fallback logic**~~ ✅ Fixed v0.5.1 — exponential backoff, circuit breaker, token budgets, fallback chains
13. ~~**No MCP integration**~~ ✅ Fixed v0.5.2 — full MCP client with stdio transport, tool discovery, execution
14. ~~**No native Anthropic provider**~~ ✅ Fixed v0.5.3 — direct Claude API with tool use support
---
## Architecture
### Current (v0.9)
```text
┌──────────┐
│ main.rs │ CLI (clap) · JSON logging · mode dispatch
└────┬─────┘
┌─────────┼──────────────────────────────────────────────────────────┐
┌──┴───┐ ┌───┴────┐ ┌───┴─────┐ ┌───┴───┐ ┌────────────┐ ┌──────┴───────┐
│agent │ │ config │ │ error │ │ tools │ │policy │ │ ravenfabric │
│ loop │ │ │ │ │ │ │ │audit │ │ client │
│ mem │ │ │ │ │ │ │ │sandbox │ │ health │
│swarm │ │ │ │ │ │ │ │mcp │ │ execute │
│super │ │ │ │ │ │ │ │heartbeat │ │ broadcast │
└──┬───┘ └────────┘ └─────────┘ └───────┘ └────────────┘ └──────────────┘
│
┌──┴───────────────────────────────────┐
│ llm (LLMProviderTrait) │
│ LiteLLM · OpenAI · OpenRouter │
│ · Ollama · Anthropic · MultiModel │
└───────────────────────────────────────┘
✅ 20 modules: policy, audit, sandbox, mcp, ravenfabric, heartbeat, eval, persistence, plugins, lib integrated
```
### Target (v1.0)
```text
┌──────────┐
│ CLI │ single · serve · swarm · supervisor · heartbeat
└────┬─────┘
┌──────┴───────┐
│ Agent Core │ perceive → plan → act → observe (+ memory)
└──┬────┬───┬──┘
┌──────────┘ │ └──────────┐
┌────┴────┐ ┌─────┴────┐ ┌──────┴───────┐
│ Tools │ │ Providers│ │ Orchestration │
│ policy✅│ │ routing+ │ │ swarm/superv. │
│ sandbox✅│ │ fallback+│ │ RavenFabric ✅│
│ audit ✅│ │ budgets │ │ (E2E remote) │
│ plugins✅│ │ │ └───────┬───────┘
└─────────┘ └──────────┘ │
│ │
┌──────┴───────┐ ┌─────────┴─────────┐
│ Observability│ │ HeartbeatAgent │
│ metrics · │ │ assess → plan → │
│ tracing · │ │ act → persist → │
│ health │ │ sleep (loop) │
└──────────────┘ └───────────────────┘
┌──────────────────┐
│ Persistence │ SQLite-backed conversation store
│ (SQLite) │ with retention policies
└──────────────────┘
✅ = Infrastructure exists, needs wiring to agent loop (v0.4)
```
---
## Competitive Positioning
RavenClaws aims to be the **preferred alternative** to the current field — including
**OpenClaw**, **NanoClaw**, **ZeroClaw**, **OpenFang**, **nanobot**, **ironclaw**,
**Claude Cowork**, Cognition (Claude), Manus, Perplexity Comet, Kimi, Open Interpreter,
and Vellum. Not by out-featuring them, but by being **fully functional as a primary
agent** while also being smaller, more secure, and more efficient.
We don't win by out-featuring them. We win by refusing to compromise on all five
pillars at once. By category:
- **vs. OpenClaw** (the primary comparison from rpi5 testing): RavenClaws is **265x more memory-efficient** (~3 MiB RSS vs ~800 MiB), **228x less CPU at idle** (~1m vs ~228m), starts in **<1s vs ~5-10s**, has a **15.8 MB vs ~500 MB container image** (20-48x smaller), and is **distroless/non-root vs full Node.js runtime running as root**. OpenClaw wins on API surface (full REST API vs 3 endpoints), agent loop usability (no `FINAL:` requirement), tool ecosystem (Playwright, PostgreSQL, ChromaDB, SearXNG via MCP), and MCP server support (SSE vs stdio-only in v0.9.3). By v0.9.9, RavenClaws will match OpenClaw's primary agent capabilities (tool execution, MCP ecosystem, HTTP API) while maintaining this efficiency advantage.
- **vs. cloud / hosted assistants** (Claude Cowork, Manus, Perplexity Computer, Kimi): RavenClaws is **self-hostable, offline-capable, and source-available** under AGPLv3. Your data and tool calls never leave infrastructure you control — no phone-home.
- **vs. minimal agent runtimes** (Open Interpreter, ZeroClaw, PicoClaw): RavenClaws matches their footprint while adding a real **security model** (deny-by-default tool policy, audit log, sandboxing) and **multi-provider** routing with fallback.
- **vs. SDK / platform plays** (Vellum, Hermes Agent): RavenClaws is a **single dependency-light binary**, not a service you rent or a framework you marry. Embed it, ship it, forget it.
The bar: anything the field can do, RavenClaws should do **smaller, safer, and
simpler** — or deliberately not at all.
> **Where RavenClaws must lead, measurably (v1.0):** memory-safe core with zero
> known CVEs, sub-15 MB binary, sub-50 ms cold start, fully self-hostable and
> air-gappable, signed + SBOM-attested supply chain. These are claims we will
> benchmark and publish — not marketing.
### RavenClaws vs. Field (v0.9.4 → v1.0 trajectory)
| Capability | RavenClaws v0.9.13 | RavenClaws v1.0 (target) | OpenClaw | Manus |
|---|:---:|:---:|:---:|:---:|
| Agent loop | ✅ | ✅ | ✅ | ✅ |
| Tool calling (structured) | ✅ | ✅ | ✅ | ✅ |
| Tool calling (any model) | ✅ **v0.9.5** | ✅ | ✅ | ✅ |
| `--exec` reliable output | ✅ **v0.9.4** | ✅ | ✅ | ✅ |
| **MCP client (stdio)** | ✅ | ✅ | ✅ | ✅ |
| **MCP client (SSE)** | ✅ v0.9.3 | ✅ | ✅ | ✅ |
| **MCP server (stdio)** | ✅ | ✅ | ✅ | ✅ |
| **MCP server (SSE)** | ✅ v0.9.3 | ✅ | ✅ | ❌ |
| **Multi-MCP-client** | ✅ v0.9.6 | ✅ | ✅ | ✅ |
| **MCP TOML config** | ✅ v0.9.6 | ✅ | ✅ | ❌ |
| **Graceful shutdown (all modes)** | ✅ **v0.9.10** | ✅ | ✅ | ✅ |
| **Config hot-reload (SIGHUP)** | ✅ v0.9.6 | ✅ | ✅ | ❌ |
| **LLM connectivity health check** | ✅ v0.9.6 | ✅ | ✅ | ❌ |
| **Server port env var** | ✅ v0.9.6 | ✅ | ✅ | ✅ |
| **Server mode docs** | ✅ v0.9.6 | ✅ | ✅ | ✅ |
| **OTEL warning suppression** | ✅ **v0.9.8** | ✅ | ✅ | ✅ |
| **Sandbox fallback for read-only /tmp** | ✅ **v0.9.8** | ✅ | ✅ | ❌ |
| **Init container chown** | ✅ **v0.9.10** | ✅ | ❌ (runs as root) | ❌ |
| **NetworkPolicy docs** | ✅ **v0.9.10** | ✅ | ✅ | ❌ |
| **Secret reference docs** | ✅ **v0.9.10** | ✅ | ✅ | ❌ |
| **LiteLLM API key docs** | ✅ **v0.9.8** | ✅ | ✅ | ❌ |
| **Default system prompt with FINAL:** | ✅ v0.9.4 | ✅ | ✅ | ✅ |
| **LLM response content logging** | ✅ v0.9.4 | ✅ | ✅ | ✅ |
| **`--exec` mode docs** | ✅ **v0.9.10** | ✅ | ✅ | ✅ |
| **Agent loop deduplication** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **Eval harness agent loop integration** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **Azure OpenAI adapter** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **vLLM docs + tests** | ✅ **v0.9.15** | ✅ | ✅ | ✅ |
| **llama.cpp docs + tests** | ✅ **v0.9.15** | ✅ | ✅ | ✅ |
| **Durable execution (checkpoint/resume)** | ✅ **v0.9.12** | ✅ | ❌ | ❌ |
| **Multi-agent patterns as primitives** | ✅ **v0.9.13** | ✅ | ❌ | ❌ |
| **SSE MCP ecosystem (verified)** | ✅ **v0.9.16** | ✅ | ✅ | ❌ |
| **Token tracking wired to LLM responses** | ✅ **v0.9.14** | ✅ **v0.9.14** | ✅ | ✅ |
| **Tool calls counter wired** | ✅ **v0.9.14** | ✅ **v0.9.14** | ✅ | ✅ |
| **`/ready` optimized with caching** | ✅ **v0.9.14** | ✅ **v0.9.14** | ✅ | ✅ |
| **MCP server optional `params`** | ✅ **v0.9.14** | ✅ **v0.9.14** | ✅ | ✅ |
| **RavenFabric pipe policy** | ✅ **v0.9.14** | ✅ **v0.9.14** | ❌ | ❌ |
| **WASM plugin system** | ✅ **v1.0.1** | ✅ v1.0.1 | ❌ | ❌ |
| **Conversation persistence (SQLite)** | ✅ **v1.0.1** | ✅ v1.0.1 | ✅ | ✅ |
| Sandboxed execution | ✅ **v0.9.8** | ✅ | ✅ | ✅ |
| **Security model (wired)** | ✅ | ✅ | ⚠️ (root user) | ⚠️ |
| **Local-first / air-gapped** | ✅ (Ollama) | ✅ | ❌ | ❌ |
| **~5 MB binary** | ✅ | ✅ | ❌ (Node.js, ~200 MB) | ❌ (cloud) |
| **~3 MiB RSS idle memory** | ✅ | ✅ | ❌ (~800 MiB) | ❌ (cloud) |
| **~10 MiB RSS under load** | ✅ *(verified: 3,597 requests, 0 errors)* | ✅ | ❌ | ❌ (cloud) |
| **~1m CPU idle** | ✅ | ✅ | ❌ (~228m) | ❌ (cloud) |
| **15.8 MB container image** | ✅ | ✅ | ❌ (~500 MB) | ❌ (cloud) |
| **<1s startup** | ✅ | ✅ | ❌ (~5-10s) | ❌ (cloud) |
| **Helm chart** | ✅ | ✅ | ❌ | ❌ |
| **No telemetry** | ✅ | ✅ | ❌ | ❌ |
| **Autonomous heartbeat** | ✅ | ✅ | ❌ | ✅ |
| **Long-horizon persistence** | ✅ | ✅ | ❌ | ✅ |
| **Scalable swarm (1000+)** | ✅ | ✅ | ❌ | ❌ |
| **Self-provisioning sub-agents** | ✅ | ✅ | ❌ | ❌ |
| **HTTP agent API** | ✅ v0.9.6 | ✅ | ✅ | ✅ |
| **Deep health check** | ✅ v0.9.6 | ✅ | ✅ | ❌ |
| **Graceful shutdown** | ✅ **v0.9.10** | ✅ | ✅ | ✅ |
| **Configurable sandbox** | ✅ **v0.9.8** | ✅ | ✅ | ❌ |
| **K8s init container chown** | ✅ **v0.9.10** | ✅ | ❌ (runs as root) | ❌ |
| **ReadOnlyRootFilesystem** | ✅ **v0.9.8** | ✅ | ❌ (not configured) | ❌ |
| **Non-root container** | ✅ (UID 65532) | ✅ | ❌ (runs as root) | ❌ |
| **Distroless base image** | ✅ | ✅ | ❌ (Debian full) | ❌ |
| **Community health files** | ✅ **v0.9.10** | ✅ | ✅ | ❌ |
| **Container < 30 MB** | ✅ **v0.9.10** (UPX compressed) | ✅ | ❌ (~500 MB) | ❌ |
| **Prometheus metrics** | ✅ | ✅ | ❌ | ❌ |
| **RavenFabric remote exec** | ✅ | ✅ | ❌ | ❌ |
| **MCP server SSE transport** | ✅ v0.9.3 | ✅ | ✅ | ❌ |
| **MCP client SSE transport** | ✅ v0.9.3 | ✅ | ✅ | ✅ |
| **Config hot-reload (SIGHUP)** | ✅ v0.9.6 | ✅ | ✅ | ❌ |
| **NetworkPolicy docs** | ✅ **v0.9.10** | ✅ | ✅ | ❌ |
| **Secret reference docs** | ✅ **v0.9.10** | ✅ | ✅ | ❌ |
| Multi-modal input | ✅ **v1.1.0** | ✅ | ✅ | ✅ |
| Web search | ✅ | ✅ | ✅ | ✅ |
| Browser automation | ✅ **v1.1.0** | ✅ v1.1.0 | ✅ | ✅ |
| Async background runs | ✅ | ✅ | ❌ | ✅ |
| Scheduling / triggers | ✅ | ✅ | ❌ | ✅ |
| Sub-agents / swarm | ✅ | ✅ | ❌ | ✅ |
| OAuth connectors | ❌ | ❌ (v0.10) | ✅ | ✅ |
| Telegram bot | ❌ | ❌ (v0.10) | ✅ | ❌ |
| SSH in container | ❌ | ❌ (v0.10) | ✅ | ❌ |
**RavenClaws's Wedge (v1.0):**
1. **Trust as a feature** — deny-by-default security, no telemetry, verifiable end-to-end
2. **Edge-deployable** — ~5 MB binary, ~3 MiB RSS idle / ~10 MiB RSS under load, ~1m CPU idle, runs on Raspberry Pi, air-gapped capable
3. **RavenFabric mesh** — E2E-encrypted remote execution across fleet (unique)
4. **Autonomous heartbeat** — operates independently for days/weeks, no supervision required ✅ v0.9
5. **Self-orchestrating swarm** — dynamically provisions and manages 10s–1000s of workers in any topology, each with unique capability profiles. No fixed limit — the swarm scales to the task.
6. **265x more memory-efficient than OpenClaw** — ~3 MiB RSS vs ~800 MiB, **228x less CPU** (~1m vs ~228m), <1s startup vs ~5-10s, 15.8 MB image vs ~500 MB (20-48x smaller). Runs on an $80 Raspberry Pi 5 with 8GB RAM where OpenClaw needs a server.
7. **Production-proven stability** — 3,597 HTTP requests, 0 errors, 0 restarts, only +2 MiB memory growth over 7.5 hours of heavy testing on rpi5 K3s. Verified by comprehensive performance audit (v0.9.11).
---
## Features Required to Become the Preferred Alternative
Being *preferred* is a two-step bar: first reach **parity** on the capabilities the
field now treats as table stakes, then **win decisively** on the five pillars where
the cloud incumbents structurally can't follow.
### Part 1 — Table stakes (reach parity)
| Capability | Why it's table stakes | In RavenClaws | Target |
|---|---|:--:|:--:|
| Agent loop (plan → act → observe) | Without it there is no "agent" | ✅ | v0.3 |
| Tool / function calling | The substrate for every action | ✅ (structured) | v0.4 |
| **Tool calling with ANY model** | Not all models emit structured `tool_calls` | ✅ **v0.9.5** | **v0.9.5** ✅ |
| **`--exec` reliable output** | Must produce output regardless of model behavior | ✅ **v0.9.4** | **v0.9.4** ✅ |
| **MCP — client *and* server** | Industry standard (Anthropic, OpenAI, Google, Microsoft, Salesforce) | ✅ (both, SSE+stdio) | **v0.9.3** ✅ |
| **Multi-MCP-client** | Connect to multiple MCP servers simultaneously | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **MCP TOML config** | Configure MCP servers in config file, not CLI | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **Graceful shutdown (all modes)** | State must survive pod termination | ✅ **v0.9.10** | **v0.9.10** ✅ |
| **Config hot-reload (SIGHUP)** | Change config without restart | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **LLM connectivity health check** | Verify LLM is reachable, not just process alive | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **Server port env var** | Configure port via env var for K8s | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **Server mode docs** | Document HTTP server endpoints and config | ✅ **v0.9.6** | **v0.9.6** ✅ |
| **OTEL warning suppression** | No warning when OTEL is disabled | ✅ **v0.9.8** | **v0.9.8** ✅ |
| **Sandbox fallback for read-only /tmp** | Must work with readOnlyRootFilesystem | ✅ **v0.9.8** | **v0.9.8** ✅ |
| **Init container chown** | Workspace must be writable by non-root user | ✅ **v0.9.10** | **v0.9.10** ✅ |
| **NetworkPolicy docs** | Document required K8s NetworkPolicy | ✅ **v0.9.10** | **v0.9.10** ✅ |
| **Secret reference docs** | Document correct K8s Secret references | ✅ **v0.9.10** | **v0.9.10** ✅ |
| **LiteLLM API key docs** | Document correct API key configuration | ✅ **v0.9.8** | **v0.9.8** ✅ |
| **Default system prompt with FINAL:** | Models need instruction to use FINAL: format | ✅ v0.9.4 | **v0.9.4** ✅ |
| **LLM response content logging** | Debug-level logging of LLM responses | ✅ v0.9.4 | **v0.9.4** ✅ |
| **`--exec` mode docs** | ✅ **v0.9.10** | ✅ | ✅ | ✅ |
| **Agent loop deduplication** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **Azure OpenAI adapter** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **Eval harness agent loop integration** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **Azure OpenAI adapter** | ✅ **v0.9.11** | ✅ | ✅ | ✅ |
| **vLLM docs + tests** | ✅ **v0.9.15** | ✅ | ✅ | ✅ |
| **llama.cpp docs + tests** | ✅ **v0.9.15** | ✅ | ✅ | ✅ |
| **Durable execution (checkpoint/resume)** | #1 gap across ALL agent frameworks | ✅ **v0.9.12** | **v0.9.12** 🎯 |
| **Multi-agent patterns as primitives** | Debate, review-loop, research-synthesize, voting out of the box | ✅ **v0.9.13** | **v0.9.13** 🎯 |
| **SSE MCP ecosystem (verified)** | Transport implemented (v0.9.3), needs docs + integration tests | ⚠️ Implemented | **v0.9.15+** 🎯 |
| **Token tracking wired to LLM responses** | `/metrics` shows 0 tokens; counter not wired to LLM `usage` field | ✅ **v0.9.14** | **v0.9.14** 🎯 |
| **Tool calls counter wired** | `/metrics` shows 0 tool calls; counter not incremented on tool execution | ✅ **v0.9.14** | **v0.9.14** 🎯 |
| **`/ready` optimized with caching** | 1.26s latency is LLM-dependent; cache LLM check result with TTL | ✅ **v0.9.14** | **v0.9.14** 🎯 |
| **MCP server optional `params`** | Some MCP clients omit `params` field; server should accept without it | ✅ **v0.9.14** | **v0.9.14** 🎯 |
| **RavenFabric pipe policy** | `sh -c "cmd \| cmd2"` blocked by policy; add pipe detection | ✅ **v0.9.14** | **v0.9.14** 🎯 |
| **WASM plugin system** | Extend without recompiling | ❌ | **v0.10** |
| **Conversation persistence (SQLite)** | Survive pod restarts without losing context | ❌ | **v0.10** |
| Multi-modal input (images, PDFs) | Manus/Kimi are multimodal; "worker" must read docs | ❌ | v0.10 |
| Connectors / integrations (OAuth) | Claude-style connectors; Manus's weakness | ❌ | v0.10 |
### Part 2 — Where RavenClaws wins (the "preferred" wedge)
| Differentiator | Why it beats the field | Pillars | Phase |
|---|---|:--:|:--:|
| **Local-first / self-hosted / air-gapped** | Manus is cloud-only; Comet's "Local" is a browser, not a worker. RavenClaws runs fully offline with Ollama. | Secure · Simple | ✅ core |
| **Security model: deny-by-default + sandbox + audit** | Field bolts security on; we ship it in core. | Secure | ✅ v0.4 (wired) |
| **~5 MB single binary, edge/embeddable** | No cloud agent runs on a Raspberry Pi. OpenClaw is ~500 MB Node.js. | Small · Efficient | ✅ |
| **~3 MiB RSS memory** | 265x less memory than OpenClaw (~800 MiB). Runs on a $80 Raspberry Pi 5. | Efficient | ✅ |
| **<1s startup** | OpenClaw takes ~30s to start. RavenClaws is ready instantly. | Efficient | ✅ |
| **Provider-agnostic + cost-aware routing** | Not locked to one model vendor. Generic `openai-compatible` unlocks 10+ backends. | Efficient · Robust | v0.5 → v1.0 |
| **RavenFabric mesh: E2E-encrypted remote exec** | Unique — competitors are single-host or single-cloud. | Robust | ✅ v0.6.1 |
| **No telemetry · signed + SBOM** | Trust as a feature, verifiable end-to-end. | Secure | ✅ |
| **Open core + commercial** | No lock-in, vs. proprietary cloud. | Simple | ✅ |
### Part 3 — The five that move the needle most
1. **`--exec` reliability (v0.9.4)** ✅ — Must produce output with ANY model. No silent failures. This was the #1 complaint from rpi5 testing — now resolved.
2. **Tool execution with any model (v0.9.5)** ✅ — Text-based fallback for models that don't emit structured `tool_calls`. Tool execution logging. Configured web search endpoint. ToolRegistry wired into agent loop.
3. **HTTP agent API (v0.9.6)** ✅ — `/chat`, `/execute`, `/tools` endpoints so the server can actually run agents. MCP TOML config, multi-MCP-client, config hot-reload, deep health check.
4. **MCP ecosystem integration (v0.9.7)** ✅ — Multi-MCP-client, readiness LLM check, SSE transport for both client and server.
5. **Production hardening (v0.9.8)** ✅ — All 5 infrastructure components wired. Configurable sandbox. OTEL warning suppression. LiteLLM API key docs.
**v0.9.10 — The five that move the needle:** ✅ All completed
1. **Community health files** ✅ — `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SUPPORT.md`, `FUNDING.yml`, issue templates (bug report, feature request, config), PR template.
2. **Graceful shutdown for heartbeat** ✅ — `Drop` impl on `HeartbeatAgent` that calls `persist_state()`. State is now saved on graceful shutdown (SIGTERM/SIGINT) without requiring a signal handler.
3. **Init container `chown` to K8s deployment** ✅ — `initContainers` section with `busybox:1.36.1` running `chown -R 65532:65532 /workspace` as root before the main container starts.
4. **`--exec` mode documentation** ✅ — Documented that `--exec` mode requires `FINAL:` format or `--no-final-required` flag. Added examples for both cases. Updated `docs/guides/getting-started.md`.
5. **Migration docs v0.9.1→v0.9.2** ✅ — `AgentMessageBus`, `MessageType`, `SwarmHealthMonitor`, `WorkerHealthStatus` additions. Updated `docs/guides/migration.md`.
**v0.9.11 — The three that move the needle:** ✅ All completed
1. **Agent loop deduplication** ✅ — Extracted shared `run_agent_loop_inner()` function containing all iteration logic (~400 lines). Both `run_agent_loop_with_registry` and `run_agent_loop_with_mcp_and_registry` now delegate to it, eliminating near-identical code duplication. ~350 lines saved. (#dedup)
2. **Azure OpenAI adapter** ✅ — New `Azure` variant in both `LLMProvider` (config.rs) and `OpenAICompatibleProvider` (llm.rs). Uses `api-key` header instead of `Bearer`, adds `api-version=2024-02-15-preview` query parameter. Mapped in CLI (`--provider azure`), factory (`create_client`), and multi-model routing. (#azure-adapter)
3. **Eval harness integrated with agent loop** ✅ — `EvalRunner::run_task()` now uses `run_agent_loop()` instead of a single direct LLM call. Eval tasks exercise the full ReAct loop with tool use, security checks, and iteration limits. (#eval-integration)
**v0.9.12 — The one that moves the needle most:** ✅ Completed
1. **Durable execution (checkpoint/resume)** ✅ — Agent loop now saves iteration-level checkpoints to disk as atomic JSON files. On restart, the loop resumes from the last checkpoint instead of starting fresh. `CheckpointState` captures full iteration context (messages, iteration count, provider/model metadata). Checkpoints are deleted on all exit paths (success, error, max iterations). Wired into background task manager for seamless resume across process restarts. (#durable-execution)
**v0.9.13 — The one that moves the needle most:** ✅ Completed
1. **Multi-agent patterns as primitives** ✅ — Debate, review-loop, research-synthesize, voting. ✅ **v0.9.13**
**v0.9.14 — The five that move the needle next:** ✅ All completed
1. **Token tracking wired to LLM responses** ✅ — Parse `usage` field from LLM responses and accumulate in `/metrics`. Currently shows 0 tokens across all requests. *(#token-tracking)*
2. **Tool calls counter wired** ✅ — Increment tool call counter on each tool execution in agent loop. Currently shows 0 tool calls in `/metrics`. *(#tool-call-counter)*
3. **`/ready` optimized with caching** ✅ — Cache LLM connectivity check result with configurable TTL (default 30s) to avoid 1.26s latency on every probe. *(#ready-caching)*
4. **MCP server JSON-RPC `params` made optional** — accept requests without `params` field. *(#mcp-params-optional)*
5. **Add pipe detection to RavenFabric policy engine** — Allow `sh -c "cmd | cmd2"` by detecting pipe characters in command strings. *(#ravenfabric-pipe-policy)*
6. **Fix `--eval /dev/null` empty input handling** — Produce meaningful output when given empty input. *(#eval-empty-input)*
7. **Set `imagePullPolicy: Always` for `:latest` tag** — Update K8s manifest to pull `:latest` on every restart. *(#image-pull-policy)*
**Exit criteria:** ✅ ALL MET
- [x] `/metrics` shows accurate token counts and tool call counts
- [x] `/ready` responds in < 100ms (cached LLM check)
- [x] MCP server accepts requests without `params` field
- [x] RavenFabric policy allows `sh -c "cmd | cmd2"` patterns
- [x] `--eval /dev/null` produces meaningful output
- [x] K8s manifest uses `imagePullPolicy: Always` for `:latest` tag
- [x] All 478+ tests pass, clippy clean, no regressions
### ✅ v0.9.15 — Ecosystem Expansion 🎯 *(completed)*
**Theme:** Ship the deferred ecosystem expansion items — vLLM docs + verification tests,
llama.cpp docs + verification tests, distroless HTTP testing docs, and website docs
pages for both providers. Close all remaining documentation gaps from the v0.9.11
rpi5 audit.
#### Completed in v0.9.15
- [x] **Ship vLLM docs + verification tests** — Created `docs/guides/vllm.md` with quick start, configuration reference, tool-calling support table, troubleshooting table, and multi-model examples. Created `scripts/lib/test-provider-vllm.sh` with connectivity check and basic prompt test. *(#vllm-docs)*
- [x] **Ship llama.cpp docs + verification tests** — Created `docs/guides/llamacpp.md` with quick start, configuration reference, tool-calling support table, troubleshooting table, performance tips, and multi-model examples. Created `scripts/lib/test-provider-llamacpp.sh` with connectivity check and basic prompt test. *(#llamacpp-docs)*
- [x] **Document distroless HTTP testing method** — Added `kubectl port-forward` and `docker run` testing sections to `docs/guides/getting-started.md`. *(#distroless-testing-docs)*
- [x] **Create website docs pages for vLLM and llama.cpp** — Created `website/public/docs/vllm.html` and `website/public/docs/llamacpp.html` mirroring the markdown guides. Updated sidebar nav in all existing docs pages. Updated sitemap.xml. Updated docs overview page with new doc cards. *(#website-docs)*
- [x] **Update verify.sh MODULES array** — Added `vllm` and `llamacpp` entries to the MODULES array in `scripts/verify.sh`. *(#verify-modules)*
**Exit criteria:** ✅ ALL MET
- [x] vLLM docs + verification tests shipped
- [x] llama.cpp docs + verification tests shipped
- [x] Distroless HTTP testing method documented in getting-started guide
- [x] Website docs pages for vLLM and llama.cpp created and linked from sidebar
- [x] verify.sh MODULES array includes vllm and llamacpp entries
- [x] All 478+ tests pass, clippy clean, no regressions
### ✅ v0.9.16 — SSE MCP Ecosystem Verification 🎯 *(completed)*
**Theme:** Wire the SSE MCP transport into the CLI and config, create integration tests,
and update documentation. This is the last remaining v1.0 blocker — once complete,
all v1.0 exit criteria are met.
#### Completed in v0.9.16
- [x] **Wire `--mcp-sse-server` CLI flag** — Added `--mcp-sse-server` (env: `RAVENCLAWS_MCP_SSE_SERVER`), `--mcp-sse-host` (default `0.0.0.0`), and `--mcp-sse-port` (default `8081`) flags to `main.rs`. Dispatch block creates `McpSseServer`, wires graceful shutdown via `ShutdownFlag`. *(#mcp-sse-wiring)*
- [x] **Wire SSE transport for MCP client config** — Added `url: String` field to `McpServerConfig`. `McpClientManager::from_config()` creates SSE transport when `url` is non-empty. Validation ensures only one of `command` or `url` is set. *(#mcp-sse-wiring)*
- [x] **Remove `#[allow(dead_code)]` from SSE components** — `McpTransportConfig::Sse` variant, `McpSseServer` struct and impl, and `McpClientManager::from_config()` SSE branch all unwired — now fully wired and active. *(#mcp-sse-wiring)*
- [x] **Update `lib.rs` re-exports** — `McpSseServer` added to public API re-exports. Module description updated to "JSON-RPC 2.0 over stdio + SSE". *(#mcp-sse-wiring)*
- [x] **Create MCP integration tests** — Created `scripts/lib/test-mcp.sh` with 5 test scenarios: stdio server tools/list, SSE server endpoint + tools/list + tools/call, SSE server health check + 404 handling, SSE client CLI flag verification, and multiple concurrent SSE clients. *(#mcp-sse-tests)*
- [x] **Update verify.sh MODULES array** — Added `mcp` entry to the MODULES array in `scripts/verify.sh`. *(#mcp-sse-tests)*
- [x] **Update SSE transport documentation** — Added SSE transport sections to `docs/guides/mcp-integration.md` covering: transport types comparison table, SSE client configuration, SSE server mode (`--mcp-sse-server`), SSE IDE integration (OpenClaw, Claude Desktop, VS Code), and SSE multi-agent workflows. *(#mcp-sse-docs)*
- [x] **Update website SSE transport docs** — Updated `website/public/docs/mcp-integration.html` with transport types table, SSE client config, SSE server endpoint table, IDE integration examples, and "New in v0.9.16" sidebar section. *(#mcp-sse-docs)*
**Exit criteria:** ✅ ALL MET
- [x] `--mcp-sse-server` CLI flag works with `--mcp-sse-host` and `--mcp-sse-port`
- [x] MCP client connects to SSE servers via `url` field in config
- [x] MCP integration tests pass (stdio + SSE)
- [x] verify.sh MODULES array includes mcp entry
- [x] SSE transport documented in both markdown guide and website HTML
- [x] All 478+ tests pass, clippy clean, no regressions
### ✅ v1.0 — Simply the Best 🏆 *(released 2026-07-02)*
**The stable release. RavenClaws is a fully functional primary agent — production-ready,
benchmarked, documented, and trusted. All five pillars are verified by independent
measurement. No more "use OpenClaw for real work" — RavenClaws IS the real work.**
**Strategic positioning realized:** RavenClaws is the "Temporal for AI agents" —
durable execution (✅ v0.9.12), multi-agent patterns, and edge-native deployment, all in a
~5 MB binary that runs on a Raspberry Pi.
**Scope:** v1.0 = v0.9.3 + v0.9.4 (critical fixes) + v0.9.5 (tool reliability) + v0.9.6
(server endpoints) + v0.9.7 (MCP ecosystem) + v0.9.8 (infrastructure wiring) + v0.9.9
(strategic differentiation) + v0.9.10 (production hardening & documentation) + v0.9.11
(strategic features) + v0.9.12 (durable execution) + v0.9.13 (multi-agent patterns) +
v0.9.14 (metrics, polish & ecosystem) + v0.9.15 (ecosystem expansion) + v0.9.16
(SSE MCP ecosystem verification). All gaps identified in rpi5 deployment feedback
are closed. **All v1.0 exit criteria are met.** Enterprise features (v0.8) and
advanced capabilities (v0.10) are deferred to post-1.0.
**Exit criteria:**
- [x] All v0.9.4 exit criteria met — `--exec` works with ANY model, no silent failures
- [x] All v0.9.5 exit criteria met — tool execution works with ANY model, text-based fallback
- [x] All v0.9.6 exit criteria met — server mode has `/chat`, `/execute`, `/tools` endpoints, MCP TOML config, multi-MCP
- [x] All v0.9.7 exit criteria met — MCP ecosystem integration verified end-to-end
- [x] All v0.9.8 exit criteria met — all infrastructure wired, OTEL warning suppressed, sandbox configurable, LiteLLM API key docs fixed
- [x] All v0.9.9 exit criteria met — community health files, heartbeat graceful shutdown, init container chown, `--exec` docs, migration docs
- [x] All v0.9.10 exit criteria met — container image size (UPX), NetworkPolicy docs, Secret reference docs, graceful shutdown for all modes
- [x] All v0.9.11 exit criteria met — agent loop deduplication, Azure OpenAI adapter, eval harness integration
- [x] All v0.9.12 exit criteria met — durable execution (checkpoint/resume) implemented
- [x] **Durable execution** — agent loop checkpoints after every iteration; survives crash/restart with full state ✅ **v0.9.12**
- [x] **Multi-agent patterns** — debate, review-loop, research-synthesize, voting all work as first-class modes ✅ **v0.9.13**
- [x] **SSE MCP ecosystem** — verified integration tests pass for both client and server SSE transport ✅ **v0.9.16**
- [x] **Token tracking wired to LLM responses** — `/metrics` shows accurate token counts ✅ **v0.9.14**
- [x] **Tool calls counter wired** — `/metrics` shows accurate tool call counts ✅ **v0.9.14**
- [x] **`/ready` optimized** — responds in < 100ms with cached LLM check ✅ **v0.9.14**
- [x] **`--eval /dev/null` produces meaningful output** — handle empty input gracefully ✅ **v0.9.14**
- [x] **MCP server JSON-RPC `params` made optional** — accept requests without `params` field ✅ **v0.9.14**
- [x] **RavenFabric policy allows piped shell interpreters** — add pipe detection to policy engine ✅ **v0.9.14**
- [x] **`imagePullPolicy: Always` for `:latest` tag** — K8s manifest verified (already correct) ✅ **v0.9.14**
- [x] **Distroless container HTTP testing documented** — document `kubectl port-forward` as testing method ✅ **v0.9.15**
- [x] **vLLM docs + verification tests** shipped ✅ **v0.9.15**
- [x] **llama.cpp docs + verification tests** shipped ✅ **v0.9.15**
- [x] `ravenclaws --exec "Summarize this repository"` works with ANY provider and produces output
- [x] `ravenclaws --serve` provides a fully functional agent API (chat, execute, tools)
- [x] Tool execution works with models that don't emit structured `tool_calls` (text-based fallback)
- [x] MCP client connects to multiple SSE-based MCP servers simultaneously
- [x] RavenClaws can be added as an MCP server in OpenClaw's config (SSE transport)
- [x] All verification tests passing across all 4 deployment targets (macOS, Linux, Docker, K8s)
- [x] Release automation complete — signed tags, multi-arch containers, SBOM, provenance, crates.io publish all green
- [x] No critical or high issues in ISSUES.md
- [x] CI/CD green across all 3 workflows
- [x] v1.0 tag pushed and released *(completed)*
- [x] All rpi5 deployment feedback items addressed (17 resolved ✅, 0 critical 🔴, 0 documentation gaps 🟡, 0 feature requests 🟢)
- [x] RavenClaws verified as a drop-in replacement for OpenClaw on rpi5 K3s
- [x] RavenClaws verified as uniquely valuable — production-proven on rpi5 (3,597 requests, 0 errors, 10 Mi RSS, 7.5h uptime)
---
### ✅ v1.4 — Universal Parity: The Merge Phase *(2026-08-13)*
**Theme:** Lift the four low-risk, high-value, non-duplicated components from the
sibling **RavenAssistant01** orchestrator into RavenClaws as idiomatic,
feature-gated, fully-tested modules. This closes the OpenClaw/Manus parity gaps
(long-term memory, conversation search, domain-level web policy, messaging) and
adds the missing "fleet" primitive (programmatic K8s pod lifecycle).
Per `RAVENCLAWS-MERGE.md`, the merge candidates were:
| # | Component | Verdict | Status |
|---|---|---|---|
| 1 | `K8sManager` → `src/k8s.rs` (feature `k8s`) | 🟢 MERGE | ✅ Done |
| 2 | `WebAccessPolicy` → `src/web_policy.rs` | 🟢 MERGE | ✅ Done |
| 3 | Long-term memory + search + auto-title → `persistence.rs` | 🟢 MERGE | ✅ Done |
| 4 | Messaging integrations → `src/integrations.rs` | 🟡 ADAPT | ✅ Done |
| 5 | Tool-aware `<tool_call>` parser | 🟠 SKIP (loop superior) | ✅ Skipped |
| 6 | Web dashboard SPA | 🟡 DEFER | ⏳ Deferred |
| 7 | Scheduled tasks (cron) | 🔴 SKIP (`scheduler.rs` exists) | ✅ Skipped |
| 8 | Cost tracking / learning feedback | 🟡 AUDIT later | ⏳ Deferred |
#### Completed in v1.4
- [x] **Domain-level web access policy** — `src/web_policy.rs` (`WebAccessPolicy`, `WebCategory`, `RateLimiter`, `extract_domain`). Category-based allow/block/permission rules wired into `web_fetch`/`web_search` and `ToolRegistry::with_config`. New `[web_policy]` config section (disabled by default). 11 tests.
- [x] **Long-term memory + conversation search + auto-title** — `persistence.rs` gains `MemoryStore`, `search_conversations()`, and auto-title with a `title` column. 16 tests.
- [x] **Kubernetes operator support** — `src/k8s.rs` (`K8sManager`, `K8sManagerConfig`) behind the optional `k8s` cargo feature. Parameterized labels/image/namespace/secret. 4 tests.
- [x] **Messaging & connector integrations** — `src/integrations.rs` (Slack, Discord, Teams, Signal, Matrix, Telegram, Email, SMS), env-var-gated with graceful `disabled` fallback. 10 tests.
- [x] **Stale Helm `appVersion` fixed** — `0.7.2` → `1.3.0`.
- [x] **K8s init-container non-root fix** — removed the root-running `chown-workspace` init container.
**Exit criteria:** ✅ ALL MET
- [x] `cargo test --locked` passes (587 tests, up from 547)
- [x] `cargo clippy --all-targets -- -D warnings` clean (default + `--features k8s`)
- [x] `cargo fmt --check` clean
- [x] Default ~5 MB binary unaffected (`k8s` optional feature)
- [x] Each feature committed and pushed individually
- [x] ROADMAP.md deduplicated (removed ~2,048 lines of accidental checklist duplication)