mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
Dragan Spiridonov
c86211c620
Independent adversarial review of 2768c29 found three blockers and two
should-fixes. All five are addressed. Three of the blockers were mine, and two
of them were the same mistake I had already been given once in this work.
B1 — THE LABELLING FIX HAD NO TEST ON THE WIRING.
Reverting channel_read's handler to the pre-PR flat return — the entire defect
this branch exists to fix — left the suite green. All four tests exercised
`labelRelayRead` as a pure function; none reached the handler, which is the half
that regresses by accident. The module reaches the relay through
`await import('ws')`, so that is now mocked and the handler is driven end to end:
a fixture event goes in, and the test asserts the envelope fields and that
`out.channel` is undefined because the payload is nested. That mutant now
reddens two tests.
B2 — AND THE ONE TEST THAT NAMED THE WIRING WAS VACUOUS.
It asserted the tool description matched /Use when/, which matches all six
descriptions in the file: a house-style check wearing a security test's name.
Replaced.
B3 — "ONLY channel_read NEEDED IT" WAS WRONG.
channel_accept pushed `JSON.parse(ev.content).channel` verbatim into
`unopenable[]` on both failure paths — unvalidated third-party text reaching the
caller beside this machine's key-store path, which is the class #3300 exists to
prevent. A grant whose id is not a channel id cannot be a real grant, so it is
refused and reported as `malformedGrants`, a count. No publisher string reaches
the caller.
My first fix for B3 repeated B1's mistake: the test asserted CHANNEL_ID_RE's
behaviour rather than that the handler uses it, and deleting the guard left the
suite green. There is now a handler-level test driving a hostile grant through
the fake relay.
S3 — THE RETURNED LEDGER KEPT ITS NULL PROTOTYPE.
The previous commit spread it back to an ordinary object, which restored the
exact hazard being fixed on the read side: `board.toString` is a truthy
function, so `!board[r]` — the same idiom the reducer uses — reports an unowned
resource as owned, and `Object.assign({}, board)` silently drops a `__proto__`
claim. The justification given for the spread was also wrong: loose
`assert.deepEqual(Object.create(null), {})` passes, and the two tests that broke
did so because this file imports `node:assert/strict`. Both were asserting the
shape of an EMPTY board, not a caller contract, so they now assert
`Object.keys(...)` and the prototype stays off.
S5 — A NON-STRING resourceId IS REFUSED RATHER THAN COERCED.
`fetchRecent` spreads arbitrary JSON, so resourceId is not necessarily a string:
`["repo/website"]` keys as 'repo/website' and squats that resource, and any
object collapses to '[object Object]'. The comment claiming it is a string is
now true.
Mutants, all reddening their own tests: handler reverted to a flat return,
CHANNEL_ID_RE guard deleted, label dropped, label fields made overwritable,
plain-object ledger, ledger returned through a spread, string guard removed.
CLI suite 90 failed files / 112 failed tests before and after (pre-existing),
passing 2426 -> 2433. tsc 463 before and after. Gateway 42 -> 49 pass, 0 fail.
graph-analyzer 0/6 runs failed.
Co-Authored-By: Ruflo & AQE
Claude-Session: https://claude.ai/code/session_01NpXyuvm9QACWhD8egqw8zU
Ruflo Plugins
32 Claude Code plugins for agent-powered development workflows. Load with --plugin-dir.
Quick Start
# Load specific plugins
claude --plugin-dir plugins/ruflo-core --plugin-dir plugins/ruflo-swarm
# Load all plugins
claude $(ls -d plugins/ruflo-*/ | sed 's|^|--plugin-dir |' | tr '\n' ' ')
Plugin Catalog
Core & Coordination
| Plugin | Description |
|---|---|
| ruflo-core | MCP server, status, doctor, coder/researcher/reviewer agents |
| ruflo-swarm | Swarm topologies (hierarchical, mesh), Monitor streaming |
| ruflo-autopilot | Autonomous /loop task completion with prediction |
| ruflo-loop-workers | 12 background workers via /loop or CronCreate |
| ruflo-workflows | Workflow templates, parallel execution, branching |
Memory & Intelligence
| Plugin | Description |
|---|---|
| ruflo-agentdb | AgentDB with HNSW vector search (150x-12,500x faster) |
| ruflo-rag-memory | SOTA RAG — hybrid search, Graph RAG, MMR diversity, memory bridge |
| ruflo-rvf | Portable RVF memory format, session persistence |
| ruflo-ruvector | ruvector — FlashAttention-3, Graph RAG, hybrid search, 103 MCP tools, Brain AGI |
| ruflo-knowledge-graph | Entity extraction, relation mapping, pathfinder traversal |
| ruflo-intelligence | SONA neural patterns, trajectory learning, model routing |
| ruflo-daa | Dynamic Agentic Architecture, cognitive patterns |
Architecture & Methodology
| Plugin | Description |
|---|---|
| ruflo-adr | ADR lifecycle — create, index, supersede, compliance checking |
| ruflo-ddd | DDD scaffolding — bounded contexts, aggregates, domain events |
| ruflo-sparc | SPARC methodology with 5 phases and quality gates |
Quality & Security
| Plugin | Description |
|---|---|
| ruflo-security-audit | CVE scanning, dependency vulnerability checks |
| ruflo-aidefence | Prompt injection detection, PII scanning |
| ruflo-testgen | Test gap detection, TDD London School workflow |
| ruflo-browser | Playwright browser automation and testing |
Development Tools
| Plugin | Description |
|---|---|
| ruflo-jujutsu | Diff analysis, risk scoring, reviewer recommendations |
| ruflo-docs | Doc generation, drift detection, API docs |
| ruflo-ruvllm | Local LLM inference, MicroLoRA, chat formatting |
| ruflo-agent | WASM agent sandboxing and gallery |
| ruflo-plugin-creator | Scaffold and validate new plugins |
| ruflo-migrations | Database schema migration management |
| ruflo-observability | Structured logging, tracing, metrics correlation |
| ruflo-cost-tracker | Token usage tracking, budget alerts, cost optimization |
Domain-Specific
| Plugin | Description |
|---|---|
| ruflo-goals | GOAP planning, deep research, horizon tracking |
| ruflo-federation | Zero-trust cross-installation agent federation |
| ruflo-iot-cognitum | Cognitum Seed IoT — trust scoring, anomaly detection, fleet management |
| ruflo-neural-trader | neural-trader — 4 agents, LSTM/Transformer, Rust/NAPI backtesting, 112+ MCP tools |
| ruflo-market-data | Market data ingestion, OHLCV vectorization, pattern matching |
Recommended Stacks
| Use Case | Plugins |
|---|---|
| Feature development | ruflo-core + ruflo-swarm + ruflo-testgen + ruflo-ddd |
| Security audit | ruflo-core + ruflo-security-audit + ruflo-aidefence |
| Architecture work | ruflo-core + ruflo-adr + ruflo-ddd + ruflo-sparc |
| Deep research | ruflo-core + ruflo-goals + ruflo-rag-memory + ruflo-intelligence |
| Vector search | ruflo-core + ruflo-ruvector + ruflo-rag-memory + ruflo-knowledge-graph |
| IoT development | ruflo-core + ruflo-iot-cognitum + ruflo-agentdb |
| Trading systems | ruflo-core + ruflo-neural-trader + ruflo-market-data + ruflo-ruvector |
| Full stack | All 32 plugins |
npm Package Integration
Several plugins wrap standalone npm packages for deeper functionality:
| Plugin | npm Package | What It Adds |
|---|---|---|
ruflo-neural-trader |
neural-trader |
112+ MCP tools, Rust/NAPI engine, LSTM/Transformer models |
ruflo-ruvector |
ruvector |
103 MCP tools, FlashAttention-3, Graph RAG, Brain AGI |
# Install backing packages
npm install neural-trader ruvector
# Add as MCP servers (optional, for direct tool access)
claude mcp add neural-trader -- npx neural-trader mcp start
claude mcp add ruvector -- npx ruvector mcp start
Plugin Structure
Each plugin follows the Claude Code plugin specification:
ruflo-<name>/
.claude-plugin/plugin.json # Plugin manifest
agents/<name>.md # Agent definitions (frontmatter: name, description, model)
commands/<name>.md # CLI command mappings
skills/<name>/SKILL.md # Interactive skills (frontmatter: name, description, argument-hint, allowed-tools)
README.md # Plugin documentation
Creating a Plugin
claude --plugin-dir plugins/ruflo-plugin-creator
# Then: /create-plugin my-new-plugin
Or manually: copy any existing plugin directory and modify.
Validation
claude plugin validate plugins/ruflo-<name>
Verification & Discoverability
Every MCP tool description across the 32 plugins must answer "use this over native (Bash/Read/Grep/Glob/Task/TodoWrite) when?" per ADR-112. The rule is enforced by CI:
# Run the audit (scans all MCPTool definitions across all plugins)
node scripts/audit-tool-descriptions.mjs
# Gates: every description must include "Use when …" guidance,
# be ≥ 80 chars, and be unique. Baseline at verification/mcp-tool-baseline.json
# is monotone-decreasing — CI fails on any regression.
Combined with verification/ (Ed25519-signed witness manifest, 103+ documented fixes attested), the plugin surface is regression-protected at three layers: install smoke (npm i), behavioral smoke (paired-tool round-trips), and presence attestation (every load-bearing line of every documented fix). See verification/README.md for the full stack.
License
MIT