mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-09-14 14:01:28 +08:00
rUv
1e64c2fd3b
* docs(adr): ADR-378/379/380 — npm trusted publishing, statusline segments, AGNTCY runtime integration Renumbered from the original 322/323/324 (chosen when this branch was based on an older main) — origin/main has since merged real, Accepted ADRs at those numbers (322=metaharness-flywheel-integration, 323=typed-memory-provenance, 324=agentic-policy-engine-codex-swarm). Content unchanged from the original commit, only the numbers and filenames moved to the next free slot after ADR-377. ADR-378: npm Trusted Publishing (OIDC) for CI/CD release automation, replacing the standing NPM_TOKEN class with per-run short-lived tokens; pairs GCP WIF for the helpers-signing-secret fetch instead of a static service-account key. ADR-379: optional context/session/week usage segments and extra statusline tip lines for .claude/helpers/statusline.cjs, following the existing CONFIG.hideCost toggle precedent; session/week/effort default OFF pending a stdin-schema verification spike. ADR-380: AGNTCY/Outshift runtime integration (SLIM transport, CASA enforcement, IOC Layer 9 coordination events) as an optional, removable augmentation per ADR-150's pattern. Companion to metaharness repo ADR-237 (agent/adr-237-agntcy-outshift-integration branch), which owns the build-time half (identity, OASF export, observability). * feat(agntcy): ADR-380 scaffolding — CASA envelope, SLIM/IOC CLI verbs, Rust crate Renumbered from the original ADR-324 (origin/main has since merged a real, unrelated, Accepted ADR-324 — see the companion docs commit). Content and behavior unchanged; only the ADR number/filename and every in-file reference to it moved to ADR-380. Implements the buildable-now portion of ADR-380 (AGNTCY/Outshift runtime integration) as optional, removable augmentation per ADR-150's pattern. No AGNTCY/SLIM/Outshift npm or crates.io packages exist yet under any plausible name (verified live) — every network touchpoint is a clearly-logged stub gated behind explicit config, never a fake success. - plugins/ruflo-agntcy/: CASA envelope schema (Zod) + deterministic compiler + enforcement gate (checkAuthorization, deny-by-default) + bypass-attempt tests; Ed25519-signed CASA decision receipts (.swarm/casa-receipts.jsonl); AGNTCY OTel span attribute constants this repo owns (coordination.episode, authorization.decision). - v3/@claude-flow/cli/src/commands/agntcy/: `ruflo transport use slim`, `ruflo agent publish`, `ruflo swarm join <namespace>` — wired into the top-level command registry and into agent.ts/swarm.ts's existing subcommand arrays (merged alongside main's concurrently-added pheromoneCommand); all exit 0 with a clear message when AGNTCY/SLIM isn't configured (RUFLO_AGNTCY_SLIM_ENDPOINT unset). - v3/crates/ruflo-agntcy/: Rust CasaEnvelope + check_authorization mirroring the TS enforcement logic exactly, LocalTransport (real, working, in-process) + SlimTransport stub behind a non-default `slim` Cargo feature. Added to the workspace; also fixed a pre-existing `cargo check` blocker (v3/plugins/gastown-bridge's nested [workspace] table conflicting with the parent workspace) by moving it from `members` to `exclude`. Adversarial security review (as ADR-380 §3 requires before trusting this gate) found and this commit fixes two real bugs in the first pass: - enforce.ts trusted the erased TS type instead of validating its own input — a non-array `allow`/`deny` collapsed `.includes()` into JS's substring-match overload, and a malformed `now`/`expires_at` silently skipped the expiry check instead of failing closed. checkAuthorization now runs CasaEnvelopeSchema.safeParse() on entry, requires an explicit timezone offset on all timestamps, and treats any unparseable timestamp as expired. - compile.ts's keyword table matched bare "push"/"publish"/"release"/ "deploy" with no contextual gate, false-permissively granting git.push/deployment.create for objectives like "push notification integration" or "review the release notes". Patterns now require a co-occurring contextual noun (git/commit/branch for push; service/app/production/version/etc. for deploy). Deferred to a follow-up pass (documented, not silently dropped): plugins/ruflo-agntcy has no package.json yet (this repo's plugins/ ruflo-* convention is Claude Code plugin content, not an npm workspace package — unlike @metaharness/agntcy's sibling-package convention on the metaharness side), so no optionalDependencies entry was added anywhere; adding one now would reference a package shape that doesn't exist and break installs. Companion: metaharness repo ADR-237 (agent/adr-237-agntcy-outshift- integration branch) — build-time half of this integration. * docs(agntcy): fix stale companion-ADR cross-reference (metaharness ADR-237 -> ADR-240) Metaharness's own numbering collided too (ADR-237 was already taken by evals-math-live-gsm8k-fast-domain on their main) and got renumbered to ADR-240 — this repo's references to it were stale. * fix(agntcy): add missing allowed-tools frontmatter to agntcy-status skill CI's fleet-wide SKILL.md frontmatter audit correctly flagged this — no implicit 'all tools' is allowed. Scoped to Read since this is a scaffolding stub (not yet implemented) that will only ever need to inspect local package.json/config state, never execute commands.
13 KiB
13 KiB
Claude Flow V3 - Architecture Decision Records
All ADRs are located in /v3/implementation/adrs/.
Quick Links
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Adopt agentic-flow as Core Foundation | Complete |
| ADR-002 | Domain-Driven Design Structure | Complete |
| ADR-003 | Single Coordination Engine | Complete |
| ADR-004 | Plugin Architecture | Complete |
| ADR-005 | MCP-First API Design | Complete |
| ADR-006 | Unified Memory Service | Complete |
| ADR-007 | Event Sourcing | Complete |
| ADR-008 | Vitest Testing | Complete |
| ADR-009 | Hybrid Memory Backend | Complete |
| ADR-010 | Node.js Only | Complete |
| ADR-011 | LLM Provider System | Complete |
| ADR-012 | MCP Security Features | Complete |
| ADR-013 | Core Security Module | Complete |
| ADR-014 | Workers System | Complete |
| ADR-015 | Unified Plugin System | Complete |
| ADR-016 | Collaborative Issue Claims | Complete |
| ADR-017 | RuVector Integration | Complete |
| ADR-018 | Claude Code Integration | Complete |
| ADR-019 | Headless Runtime Package | Complete |
| ADR-020 | Headless Worker Integration | Complete |
| ADR-046 | Dual Umbrella: claude-flow + ruflo | Accepted |
| ADR-047 | Fast Mode Integration | Proposed |
| ADR-178 | Verifiable Memory Governance and RepE IPI Detection | Proposed |
| ADR-301 | Promotional Status Surface for CLI Runtime | Proposed |
| ADR-302 | Post-Initialization Capability Enrollment | Proposed |
| ADR-303 | Intelligent Credit Exhaustion Experience | Proposed |
| ADR-304 | Local Meta LLM Proxy Product | Proposed |
| ADR-305 | Customer Lifecycle Funnel (RuFlo → Cognitum) | Proposed |
| ADR-306 | Cognitum Authentication and Account Linking | Proposed |
| ADR-307 | Proxy Runtime, Packaging, and Service Lifecycle | Proposed |
| ADR-308 | Cognitum Public API and Server Contract | Proposed |
| ADR-309 | Funnel Governance, Privacy, and Ecosystem Policy | Proposed |
| ADR-310 | Funnel Rollout, Measurement, and Emergency Controls | Proposed |
| ADR-320 | MCP Tool Composition Inspector + Inter-Agent Channel Guardrails | Accepted |
| ADR-323 | Typed Memory Provenance in AgentDB (MemIR-style claim typing, corrects #2804's dream-cycle proposal) | Accepted |
| ADR-324 | Agentic Policy Engine and Policy-Governed Codex Swarms | Accepted |
| ADR-325 | Claim Federation as a Zero-Trust Capability and Work-Ownership Plane | Proposed |
| ADR-326 | Cognitum Product-Plane Claim Federation Profile | Proposed |
| ADR-327 | Federated Concurrent Development Harness | Proposed |
| ADR-328 | Cognitum-Assisted Agent Learning Capability Plane | Proposed |
| ADR-329 | Ruflo Capability Brain for MCP Guidance | Accepted |
| ADR-330 | Adaptive Pheromone Swarm Consensus | Accepted |
| ADR-331 | Project-Local Flywheel Evaluation Anchors | Accepted |
| ADR-332 | Hermetic Release Verification and Supported Runtime Baseline | Accepted |
| ADR-333 | Efficiency-First Orchestration — Pre-hoc Failure Inference and Adaptive Agent Count Routing | Proposed |
| ADR-334 | Hierarchical Consensus Topology for Large-Scale Swarm Coordination | Proposed |
| ADR-335 | Upgrade to Multi-Vector HNSW (MV-HNSW) for Agent Memory Retrieval | Proposed |
| ADR-336 | Agent Authorization Propagation and MCP Authentication Enforcement | Proposed |
| ADR-337 | Plugin Supply Chain Integrity and Memory Namespace Governance | Proposed |
| ADR-338 | SONA Behavioral Trajectory Auditing via Embedding-Space Trait Vectors | Proposed |
| ADR-339 | Memory Write Integrity Validation & MCP Tool Verification | Proposed |
| ADR-340 | Retrospective Harness Optimization (RHO) for SONA Intelligence Loop | Proposed |
| ADR-341 | Multi-Signal Memory Retrieval | Proposed |
| ADR-342 | RuVector Production-Scale Backend Adoption | Proposed |
| ADR-343 | Shared-Context Parallel Dispatch for Multi-Agent Performance | Proposed |
| ADR-344 | Knowledge Graph Index for ReasoningBank | Proposed |
| ADR-345 | Swarm Credit Routing via Shapley-Value Attribution | Proposed |
| ADR-346 | Multi-Layer Agent Security Stack | Proposed |
| ADR-347 | Trajectory-Quality JUDGE Scoring for ReasoningBank | Proposed |
| ADR-348 | Task-Adaptive Swarm Topology Selector | Proposed |
| ADR-349 | FLARE-Style Lookahead Planning Buffer for SONA Intelligence Layer | Proposed |
| ADR-350 | Trust-Weighted Consensus for Swarm Coordination | Proposed |
| ADR-351 | Stateful Execution Loop with KV-Cache Discipline and Agent Execution Graphs | Proposed |
| ADR-352 | MCP Tool Permission Attestation (Min-Privilege Contract) | Proposed |
| ADR-353 | Trace-to-Skill Distillation for Intelligence Pipeline | Proposed |
| ADR-354 | AgentDB Memory Write Verification and Temporal Supersession Layer | Proposed |
| ADR-355 | Reinforcement-Learned Stopping Policy for Ruflo Swarm Orchestration | Proposed |
| ADR-356 | Cross-Agent KV-Cache Sharing for Swarm Performance | Proposed |
| ADR-357 | Dimension-Aware Intelligence Routing for Heterogeneous Agent Pools | Proposed |
| ADR-358 | AutoMem-Style RL Training Loop for AgentDB Memory Operations | Proposed |
| ADR-359 | Swarm Dissent Mechanism: Inverse-Wisdom Law Compliance | Proposed |
| ADR-360 | Cross-Agent Shared KV Pool (PolyKV Architecture) | Proposed |
| ADR-361 | Skill Evolution Worker (SEW) — Runtime RL-Based Skill Acquisition for SONA | Proposed |
| ADR-362 | HNSW-as-Communication-Fabric (HCF) for RuVector Swarm Knowledge Gossip | Proposed |
| ADR-363 | Workflow-Atomic Inference Scheduling (WAIS) for Multi-Agent Execution | Proposed |
| ADR-364 | Plugin Supply-Chain Scanner and Behavioral Manifest | Proposed |
| ADR-365 | Recurrence-Gated Memory Consolidation for AgentDB | Proposed |
| ADR-366 | Self-Evolving Swarm Skill Distillation via Trajectory Feedback | Proposed |
| ADR-367 | Epistemic Working Memory in the Intelligence Pipeline | Proposed |
| ADR-368 | Selective Persistent Memory Categories for AgentDB | Proposed |
| ADR-369 | Information-Bottleneck Vector-Quantized Inter-Agent Messaging | Proposed |
| ADR-370 | World-Model Agent Planning for Cost-Aware Task Pre-Simulation | Proposed |
| ADR-371 | Neural Cryptographic Authorization Gate for Agentic Action Execution | Proposed |
| ADR-372 | Cognitive Mode Router for Agent Memory Query Dispatch | Proposed |
| ADR-373 | Budget-Dependent Memory Operator Selection (OAS) | Proposed |
| ADR-374 | SubagentPermissionDelegate: Workspace-Scoped Privilege Delegation for Swarm Agents | Proposed |
| ADR-375 | Agentic Inference Benchmarking Standard + Mixture-of-Agents Test-Time Scaling | Proposed |
| ADR-376 | Heterogeneous Agent Ensemble Composition API | Proposed |
| ADR-377 | AgentDB Retrieval Security Layer | Proposed |
| ADR-378 | npm Trusted Publishing for CI/CD Release Automation | Proposed |
| ADR-379 | Optional Context/Session/Week Usage Segments and Extra Statusline Lines | Proposed |
| ADR-380 | AGNTCY/Outshift Runtime Integration: SLIM Transport, CASA Enforcement, IOC Coordination Events | Proposed |
Summary Documents
- ADR Status Summary - Implementation status overview
- V3 ADRs Master - Complete ADR document
- Full README - Detailed index with roadmap
Performance Targets
| Metric | Target | Status |
|---|---|---|
| HNSW Search | 150x-12,500x faster | ✅ Achieved |
| Flash Attention | 2.49x-7.47x speedup | ✅ Achieved (alpha.102) |
| Memory Reduction | 50-75% | ✅ Achieved |
| MCP Response | <100ms | ✅ Achieved |
| CLI Startup | <500ms | ✅ Achieved |
Neural Features (alpha.102+)
| Component | Status | Lines | Notes |
|---|---|---|---|
| SONA Optimizer | ✅ Real | 841 | Pattern learning from trajectories |
| EWC++ Consolidation | ✅ Real | ~600 | Fisher matrix, prevents forgetting |
| MoE Router | ✅ Real | ~500 | 8 experts with gating network |
| Flash Attention | ✅ Real | ~500 | O(N) block attention |
| LoRA Adapter | ✅ Real | ~400 | 128x compression (rank=8) |
| Hyperbolic Embeddings | ✅ Real | - | Poincaré ball model |
| Int8 Quantization | ✅ Real | - | 3.92x memory savings |
Security Status
| CVE | Severity | Status |
|---|---|---|
| CVE-2 | Critical | ✅ Fixed |
| CVE-3 | Critical | ✅ Fixed |
| HIGH-1 | High | ✅ Fixed |
| HIGH-2 | High | ✅ Fixed |
Security Score: 10/10
Last Updated: 2026-01-14 CLI Version: @claude-flow/cli@3.0.0-alpha.104