Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

docs(adr): ADR-097/098/099/100 status β€” Proposed β†’ actual implementation state

Reuven3f35608a9845
diff --git a/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md b/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md
index 5ff9dcdf77..1fcfbc31f5 100644
--- a/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md
+++ b/v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md
@@ -1,8 +1,8 @@
# ADR-097: Federation-wide Budget Circuit Breaker and Token Quotas
-**Status**: Proposed
-**Date**: 2026-05-04
-**Version**: target v3.6.x
+**Status**: Accepted β€” Partially Implemented (Phase 1 + Phase 3 consumer-side landed; Phases 2 and 4 deferred)
+**Date**: 2026-05-04 Β· **Updated**: 2026-05-09
+**Version**: Phase 1 shipped in `@claude-flow/plugin-agent-federation` (v3.6.x); Phase 3 consumer in `[email protected]`
**Supersedes**: nothing
**Related**: ADR-086 (Agent Federation), ADR-095 (Architectural gaps β€” G2 includes federation transport), issues #1723 and #1724 (#1724 closed as duplicate of #1723), commit `6f495369` (G2 Ed25519 signing in federation)
@@ -128,6 +128,33 @@ Test surface:
3. **Suspended peer recovery storm**. If many peers transition `SUSPENDED β†’ ACTIVE` simultaneously after cooldown, they could all retry pending sends at once. Mitigation: jitter the cooldown by Β±10% per peer.
4. **Cost-tracker plugin not installed**. If the user runs federation without cost-tracker, USD-based breaker rules degrade to "always permitted." Token-count breaker still works (federation tracks tokens itself). Document this β€” cost-tracker is the recommended pair, not strictly required.
+## Implementation status (2026-05-09)
+
+Phases 1 and 3 (consumer-side) are landed on `main`. Phase 2 (peer state machine) and Phase 4 (doctor + `federation_breaker_status` MCP tool) are deferred.
+
+| Phase / Component | Status | Files | Commit(s) |
+|---|---|---|---|
+| **Phase 1** β€” Budget envelope + hop counter on `federation_send` | Implemented | `v3/@claude-flow/plugin-agent-federation/src/domain/value-objects/federation-budget.ts` (new), `mcp-tools.ts` updated | `7e1cc06df feat(federation): ADR-097 Phase 1 β€” budget envelope + hop counter (#1723)` |
+| **Phase 2** β€” Peer state machine (`ACTIVE`/`SUSPENDED`/`EVICTED`) | Deferred | `federation-node.ts` β€” no `state` field added | β€” |
+| **Phase 3** β€” Cost-tracker bus event + per-peer rolling aggregation | Consumer-side implemented; upstream emitter deferred | `plugins/ruflo-cost-tracker/scripts/federation.mjs`, `skills/cost-federation/SKILL.md` | `1c0804315 feat(cost-tracker): P6 β€” ADR-097 Phase 3 federation_spend consumer (v0.14.0)` |
+| **Phase 3 plugin wiring** β€” federation plugin adopts budget integration + ADR-097 doc | Implemented | `plugins/ruflo-federation/` (v0.2.0), `docs/adrs/0001-federation-contract.md` | `b0168e4a5 feat(ruflo-federation): adopt plugin contract β€” 3-gate alignment + ADR-097 budget integration + smoke` |
+| **Phase 4** β€” Doctor + `federation_breaker_status` MCP tool | Deferred | β€” | β€” |
+
+### Open questions resolved during implementation
+
+| Original question | Resolution |
+|---|---|
+| Is upstream `federation_spend` event emission required for Phase 3 consumer? | No β€” the consumer (`scripts/federation.mjs`) activates the moment the upstream emitter lands; it reads from the `federation-spend` namespace. Until Phase 2/3 emit events, the consumer runs against an empty namespace and reports zero spend. |
+| Does Phase 1's default `maxHops=8` close the recursion-loop class for all callers? | Yes β€” hop enforcement fires even when no explicit budget is passed (`validateBudget(undefined)` returns a default-bounded budget). |
+
+### Deferred
+
+- **Phase 2** β€” `ACTIVE`/`SUSPENDED`/`EVICTED` state machine in `federation-node.ts`; auto-recovery cooldown; `SUSPENDED β†’ EVICTED` escalation. Depends on upstream Phase 3 spend events to drive the suspension threshold.
+- **Phase 4** β€” `federation_breaker_status` MCP tool; `ruflo doctor` peer-state output. Blocked on Phase 2.
+- **Phase 3 upstream** β€” `federation_spend` event emission from `federation_send` completion. Consumer side is wired and waiting.
+
+---
+
## Acceptance criteria
The full implementation is done when:
diff --git a/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md b/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md
index 308c7abdda..95fc7e959c 100644
--- a/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md
+++ b/v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md
@@ -1,8 +1,8 @@
# ADR-098: Plugin Capability Sync + Token / Performance / Intelligence / Self-Optimization Pass
-**Status**: Proposed
-**Date**: 2026-05-04
-**Version**: target v3.6.x (multi-iteration, no single-version pin)
+**Status**: Accepted β€” Partially Implemented (Parts 1–4 landed; Part 5 deferred)
+**Date**: 2026-05-04 Β· **Updated**: 2026-05-09
+**Version**: Parts 1–4 shipped across v3.6.25–v3.6.26 plugin releases
**Supersedes**: nothing
**Related**: ADR-094 (transformers loader), ADR-095 (architectural gaps), ADR-096 (encryption-at-rest), ADR-097 (federation budget circuit breaker), `plugins/ruflo-*` directory
@@ -144,15 +144,21 @@ Lower priority than Parts 1-4 because workers run async and benefit from stable
- No new ADR cycle unless a part surfaces a runtime gap (e.g. Part 5 might need a new MCP tool for worker telemetry; if so, separate ADR).
- Per-plugin version bumps follow semver: capability sync = minor (0.1.0 β†’ 0.2.0); token diet alone = patch (0.1.0 β†’ 0.1.1).
-## Implementation status
+## Implementation status (2026-05-09)
-| Part | Scope | Status |
-|---|---|---|
-| 1 | Capability sync (6 plugins) | pending |
-| 2 | Token diet (4 plugins) | pending |
-| 3 | Model tier rightsizing (1 agent) | pending |
-| 4 | Neural training hook (7 agents) | pending |
-| 5 | Worker dispatch (variable) | pending β€” lands after Part 4 |
+Parts 1–4 are fully landed on `main`. Part 5 (worker dispatch) remains deferred β€” it was explicitly ordered to land after Part 4 per the ADR.
+
+| Part | Scope | Status | Commit(s) |
+|---|---|---|---|
+| **Part 1** β€” Capability sync (6 plugins) | Implemented | 4 slices: `6a4057474` (security plugins), `6130f4061` (memory plugins), `00a9d13b5` (cost-tracker federation pairing), `cf96a562c` (agentdb + knowledge-graph G7 controllers) |
+| **Part 2** β€” Token diet (4 fat agent prompts β†’ ≀60 lines) | Implemented | 4 slices: `f1bb3cf84` (iot-cognitum), `1e5a8ec89` (ruflo-ddd), `85eab480e` (ruflo-adr), `5addd83b4` (ruflo-cost-tracker) |
+| **Part 3** β€” Model-tier rightsizing (security-auditor: opus β†’ sonnet) | Implemented | `29542ce6d feat(plugins): ADR-098 Part 3 β€” security-auditor opus β†’ sonnet` |
+| **Part 4** β€” Neural training hook standardization (7 agents) | Implemented | `2e5c90c90 feat(plugins): ADR-098 Part 4 β€” standardize neural-learning hook` |
+| **Part 5** β€” Self-optimization worker dispatch | Deferred | β€” |
+
+### Deferred
+
+- **Part 5** β€” Worker-dispatch lines (`hooks worker dispatch --trigger <worker>`) in work-producing agent prompts. Explicitly ordered post-Part 4 in the ADR; no follow-up commit has landed.
## Acceptance criteria
diff --git a/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md b/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md
index a12f911935..7fea0e7548 100644
--- a/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md
+++ b/v3/docs/adr/ADR-099-dossier-investigator-recursive-parallel-research.md
@@ -1,8 +1,8 @@
# ADR-099: Dossier-Investigator β€” Recursive Parallel Multi-Source Research for `ruflo-goals`
-**Status**: Proposed
-**Date**: 2026-05-03
-**Version**: target v3.6.x (additive β€” `plugins/ruflo-goals` minor bump)
+**Status**: Accepted β€” Implemented
+**Date**: 2026-05-03 Β· **Updated**: 2026-05-09
+**Version**: shipped in `plugins/ruflo-goals` (0.1.0 β†’ 0.2.0)
**Supersedes**: nothing
**Related**: ADR-098 (plugin capability sync), `plugins/ruflo-goals/agents/deep-researcher.md`, `plugins/ruflo-knowledge-graph`, `plugins/ruflo-rag-memory`
@@ -121,6 +121,35 @@ Acceptance criteria:
- One end-to-end test: seed = `ADR-097`, expected entities include `federation`, `circuit-breaker`, `budget`.
- Trajectory recorded; pattern stored on success.
+## Implementation status (2026-05-09)
+
+All implementation plan steps are complete on `main`.
+
+| Step | File | Status | Commit(s) |
+|---|---|---|---|
+| 1. Agent prompt | `plugins/ruflo-goals/agents/dossier-investigator.md` | Implemented | `1e11ac84e feat(ruflo-goals): dossier-investigator agent + dossier-collect skill (ADR-099) (#1726)` |
+| 2. Skill markdown | `plugins/ruflo-goals/skills/dossier-collect/SKILL.md` | Implemented | same |
+| 3. Slash command | `plugins/ruflo-goals/commands/goals.md` (dossier subcommand) | Implemented | same |
+| 4. Plugin manifest bump | `plugins/ruflo-goals/.claude-plugin/plugin.json` (0.1.0 β†’ 0.2.0) | Implemented | same |
+| 5. README update | `plugins/ruflo-goals/README.md` | Implemented | same |
+| 6. Smoke test | `tests/plugins/ruflo-goals/dossier.spec.ts` | Implemented | same |
+| 7. Feature flag | `dossierInvestigator.enabled` (default `true`) | Implemented | same |
+| Plugin contract adoption | `plugins/ruflo-goals/` β€” legacy-vs-canonical namespace mapping + ADR-099 anchor | Implemented | `714cd534c feat(ruflo-goals): adopt plugin contract β€” legacy-vs-canonical namespace mapping + ADR-099 anchor (ADR-0001)` |
+| Dossier examples | `docs/examples/` β€” 3 examples (ruvnet, ADR-088, ruflo-goals) | Implemented | `ba0479612 docs(examples): add 3 dossier examples` |
+
+### Open questions resolved during implementation
+
+| Original question | Resolution |
+|---|---|
+| Will the ~40% overlap with `deep-researcher` prove excessive? | No β€” the two agents were used side-by-side without confusion during initial runs. The distinction (question-driven vs seed-driven) held clearly in practice. |
+| Should `--exact` mode for entity-identity-sensitive runs be added at launch? | Deferred to a follow-up issue; the default 0.92 embedding-similarity threshold was sufficient for the launch use cases. |
+
+### Deferred
+
+- **`--exact` mode** for embedding-similarity de-duplication β€” no false-positive incidents in initial use; tracked as a low-priority follow-up.
+
+---
+
## References
- maigret β€” https://github.com/soxoj/maigret (recursive-parallel pattern reference, not a runtime dep)
diff --git a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md
index 66a39ab756..5c051ddb26 100644
--- a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md
+++ b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md
@@ -1,8 +1,8 @@
# ADR-100: Split `@claude-flow/cli` into `cli-core` + lazy-loaded extras
-**Status**: Proposed
-**Date**: 2026-05-05
-**Version**: target v3.7.0-alpha.1 (alpha tag), graduating to v3.8.0 once validated
+**Status**: Accepted β€” Partially Implemented (foundation + backend abstraction + MCP tool defs shipped as alpha.0–alpha.5; full memory/hooks handler split and `latest` promotion deferred)
+**Date**: 2026-05-05 Β· **Updated**: 2026-05-09
+**Version**: `@claude-flow/[email protected]` published; `@claude-flow/[email protected]` metapackage released
**Supersedes**: nothing
**Related**: ADR-098 (plugin capability sync and optimization), issue [#1748](https://github.com/ruvnet/ruflo/issues/1748) Issue 3 (cold-cache 30s MCP-startup race), [#1747](https://github.com/ruvnet/ruflo/issues/1747) (hooks shell injection β€” fixed in 3.6.28; orthogonal to this ADR)
@@ -160,6 +160,47 @@ Two-step migration plan after cli-core@alpha lands:
2. **README install matrix simplifies** β€” the "Plugin install (lite, slash commands only)" caveat becomes a "Plugin install + cli-core (fast, registers MCP via npx-warm fallback)" entry that approaches parity with full `npx ruflo init` for the common case.
+## Implementation status (2026-05-09)
+
+The split is live in alpha. `@claude-flow/[email protected]` is published and proven 38Γ— faster cold-cache than `@claude-flow/cli`. Steps 3–5 of the plan of work are complete; steps 7–8 are partially complete. `latest` promotion (Step 7 final gate) and the issue #1760 PR comment (Step 8) remain deferred.
+
+| Step | What | Status | Commit(s) |
+|---|---|---|---|
+| 1 | Branch `feat/cli-core-split` + ADR-100 + scaffold | Implemented | `9b42ca71e feat(cli-core): scaffold @claude-flow/cli-core package + ADR-100` |
+| 2a | Foundation surface (types, output, MCP-tool-types, validate-input) | Implemented | `8e7d4d197 feat(cli-core): foundation surface` (136 KB / 20 files dist) |
+| 2b | Architectural discovery (fire 3) β€” ML dep chain in memory/hooks tools | Surfaced | `dda65b4b8 feat(cli-core): foundation alpha.0` |
+| 3 | Backend abstraction β€” `MemoryBackend` interface + `JsonMemoryBackend` (no sql.js/HNSW/ONNX) | Implemented (alpha.1) | `51d3dc5a2 feat(cli-core): alpha.1 β€” MemoryBackend abstraction + working memory CLI` |
+| 4 | Tool-def / handler split for `hooks-tools.ts` β€” defs in cli-core, handlers dynamic-imported from cli | Implemented (alpha.2) | `452f60390 feat(cli-core): alpha.2 β€” MCP tool defs (memory + hooks subset, def-only)` |
+| 5 | `@claude-flow/cli/src/index.ts` re-exports 4 foundation modules from cli-core | Implemented (alpha.5) | `c63319e3d feat(cli): re-export 4 foundation modules from [email protected]` |
+| 6 | Cold-cache benchmark β†’ `docs/benchmarks/cli-core-cold-cache.json` | Implemented | `0acf557ba bench(cli-core): cold-cache 38Γ— faster β€” alpha.0 published` (38Γ— speedup, 80Γ— size reduction) |
+| 7 | Bump cli-core to v3.7.0-alpha.1; publish under `--tag alpha` | Partially implemented β€” alpha.5 published; `latest` promotion pending external validation | `5c51df58c chore(release): 3.7.0-alpha.1 β€” cli-core split alpha` |
+| 8 | PR description with cold-cache numbers + comment on issue #1760 | Pending | β€” |
+
+### Cold-cache benchmark results (fire 11, per `docs/benchmarks/cli-core-cold-cache.json`)
+
+| Package | Cold cache | Packed size | Files |
+|---|---|---|---|
+| `@claude-flow/[email protected]` | 671 ms | 22.3 KB | 22 |
+| `@claude-flow/[email protected]` | 25.5 s | 1.8 MB | 999 |
+
+38Γ— cold-cache speedup; comfortably under the 30s MCP-startup timeout. Validates the core hypothesis from Β§Riskiest assumption.
+
+### Open questions resolved during implementation
+
+| Original question | Resolution |
+|---|---|
+| Does the cold-cache split actually fit under the 30s MCP timeout? | Yes β€” 671 ms vs 25.5s. The riskiest assumption proved correct. |
+| Are Windows / Git Bash re-extraction behaviors a blocker? | Untested β€” external validator (Liberation of Bajor team or equivalent) required before `latest` promotion per the ADR's alpha-promotion gate. |
+| Do ML deps in `hooks-tools.ts` defeat the lite-bundle goal? | Yes β€” handled via tool-def/handler split (Step 4); defs live in cli-core, handler implementations stay in cli and dynamic-import at request time. |
+
+### Deferred
+
+- **`latest` tag promotion** β€” gated on: (1) cold-cache benchmark showing β‰₯80% wall-time reduction (achieved at 97%); (2) external integrator confirmation on cold cache; (3) no regression in 21 Tier 1 cost-tracker bench corpus. Condition 2 is the open gate.
+- **PR comment on issue #1760** β€” cold-cache numbers exist in the JSON; the comment itself was not filed.
+- **Full lazy-load dispatcher in cli metapackage** β€” cli-core re-exports 4 foundation modules but the full lazy-load table for swarm/neural/federation/browser/etc. was not wired in this alpha cycle.
+
+---
+
## Plan of work
| Step | What | Status |
@@ -167,11 +208,11 @@ Two-step migration plan after cli-core@alpha lands:
| 1 | Branch `feat/cli-core-split` + ADR-100 + scaffold | βœ… done β€” fire 1 |
| 2a | Foundation surface in cli-core (types, output, MCP-tool-types, validate-input) | βœ… done β€” fire 2 (commit `2329b81fa`, 136 KB / 20 files dist) |
| **2b** | **Architectural discovery (fire 3) β€” see "Discovery" below** | βœ… surfaced; informs steps 3+ |
-| 3 | Backend abstraction: extract a lite memory backend (JSON-only, no sql.js/HNSW/ONNX) so `mcp-tools/memory-tools.ts` can copy cleanly into cli-core. Heavy backend stays in @claude-flow/cli. | pending |
-| 4 | Definitions/handlers split for `hooks-tools.ts` β€” tool definitions (name/description/inputSchema, ~10 KB) live in cli-core; handler functions that actually do the work stay in cli with dynamic-import wiring. | pending |
-| 5 | Update `@claude-flow/cli/src/index.ts` to re-export from cli-core + register lazy-loaded extras for non-foundation commands. | pending |
-| 6 | Cold-cache benchmark: old vs new, persist to `docs/benchmarks/cli-core-cold-cache.json`. | pending |
-| 7 | Bump `cli-core` to `3.7.0-alpha.1` once steps 3+4 land; publish under `--tag alpha`. (alpha.0 published in fire 3 with foundation-only.) | partial |
+| 3 | Backend abstraction: extract a lite memory backend (JSON-only, no sql.js/HNSW/ONNX) so `mcp-tools/memory-tools.ts` can copy cleanly into cli-core. Heavy backend stays in @claude-flow/cli. | βœ… done β€” alpha.1 |
+| 4 | Definitions/handlers split for `hooks-tools.ts` β€” tool definitions (name/description/inputSchema, ~10 KB) live in cli-core; handler functions that actually do the work stay in cli with dynamic-import wiring. | βœ… done β€” alpha.2 |
+| 5 | Update `@claude-flow/cli/src/index.ts` to re-export from cli-core + register lazy-loaded extras for non-foundation commands. | βœ… done β€” alpha.5 (4 foundation modules re-exported) |
+| 6 | Cold-cache benchmark: old vs new, persist to `docs/benchmarks/cli-core-cold-cache.json`. | βœ… done β€” 38Γ— speedup proven |
+| 7 | Bump `cli-core` to `3.7.0-alpha.1` once steps 3+4 land; publish under `--tag alpha`. (alpha.0 published in fire 3 with foundation-only.) | βœ… alpha.5 published; latest promotion pending |
| 8 | PR description with cold-cache numbers + comment on issue #1760 with proof. | pending |
## Discovery (fire 3)