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-059): bug triage priority matrix for March 2026

rUvf645fbf0125b
diff --git a/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md b/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md
new file mode 100644
index 0000000000..8367c0f983
--- /dev/null
+++ b/v3/implementation/adrs/ADR-059-bug-triage-2026-03.md
@@ -0,0 +1,177 @@
+# ADR-059: Bug Triage & Priority Matrix β€” March 2026
+
+**Status:** Accepted
+**Date:** 2026-03-05
+**Author:** claude-flow
+
+## Context
+
+As of v3.5.2, ruflo has 30 open issues spanning security, platform stability, CLI correctness, MCP protocol compliance, and Chat UI runtime bugs. This ADR triages every open issue into a priority matrix to guide engineering effort.
+
+Note: `@claude-flow/memory` (AgentDB) is now published at `@latest`, which affects several wiring issues below.
+
+## Priority Levels
+
+| Level | Meaning | SLA |
+|-------|---------|-----|
+| **P0 β€” Critical** | Security risk, data loss, or blocks all users | Fix within 24h |
+| **P1 β€” High** | Core functionality broken for a platform or major feature | Fix within 1 week |
+| **P2 β€” Medium** | Incorrect behavior, cosmetic UX bugs, missing config | Fix within 2 weeks |
+| **P3 β€” Low** | Enhancements, polish, branding consistency | Next release cycle |
+
+---
+
+## P0 β€” Critical (Fix Immediately)
+
+### 1. Obfuscated preinstall script deletes npm cache entries (#1261)
+- **Impact:** Supply-chain trust β€” the `preinstall` script in `package.json` silently deletes npm cache entries for `claude-flow` and `ruflo`. This resembles malicious behavior and will trigger security scanners (Socket, Snyk, npm audit).
+- **Risk:** Package ban from npm registry; user trust erosion.
+- **Fix:** Remove the obfuscated preinstall script entirely. If cache-busting is needed, document it as an explicit post-install step.
+
+### 2. RVF ObjectId cross-package matching failure (Chat UI β€” fixed in #1297)
+- **Impact:** All conversation lookups returned wrong data. `findOne({_id})` matched ALL documents because MongoDB's `ObjectId` was treated as an empty operator object by the RVF store.
+- **Status:** Fixed in `feat/ruflo-chat-ui-branding` (merged). Verify no regression.
+
+### 3. Windows: daemon and memory init silently fail (#1282)
+- **Impact:** `init --start-all` reports success but creates nothing on Windows. Zero functionality for Windows users.
+- **Risk:** Platform exclusion β€” Windows is a primary target for CLI tools.
+- **Fix:** Audit all `child_process.spawn` calls for POSIX-only flags; add Windows CI matrix.
+
+---
+
+## P1 β€” High (Fix This Week)
+
+### 4. macOS: daemon dies immediately after start (#1283)
+- **Impact:** Daemon always shows STOPPED on macOS. Background workers, learning hooks, and neural training are all non-functional.
+- **Fix:** Likely PID file or signal handling issue. Add launchd/plist support as alternative to raw daemon.
+
+### 5. Claude Code hooks: misconfigured commands cause silent failures (#1284)
+- **Impact:** Generated `settings.json` contains broken hook commands. Users get no feedback β€” hooks silently fail, degrading learning, session management, and intelligence features.
+- **Fix:** Validate all hook commands at generation time; add `--dry-run` flag to hooks.
+
+### 6. Hook commands use relative paths, break when CWD != project root (#1259)
+- **Impact:** All hooks break when invoked from subdirectories or IDE integrations that set CWD differently.
+- **Fix:** Resolve all hook command paths to absolute paths at generation time using `findRepoRoot()`.
+
+### 7. auto-memory-hook.mjs fails to resolve @claude-flow/memory (#1287)
+- **Impact:** Auto-memory import fails when installed as nested dependency (common in monorepos and npx). Memory persistence across sessions broken.
+- **Note:** AgentDB is now @latest β€” update import paths accordingly.
+- **Fix:** Use `createRequire(import.meta.url)` resolution or bundle the memory module.
+
+### 8. AgentDB bridge always unavailable β€” ControllerRegistry not exported (#1264)
+- **Impact:** AgentDB v3 controllers (ReasoningBank, SkillLibrary, ExplainableRecall) are implemented but never instantiated at runtime. The entire intelligence layer is dead code.
+- **Note:** `@claude-flow/memory` (AgentDB) is now published at `@latest`. The export is available but CLI init doesn't wire it.
+- **Fix:** Update CLI to `import { ControllerRegistry } from '@claude-flow/memory'` (now on @latest); wire into init sequence.
+
+### 9. MCP schema invalid for strict clients β€” array missing `items` (#1294)
+- **Impact:** MCP tool schemas fail validation on strict OpenAI-compatible clients. Tools with array parameters are rejected, blocking tool execution for some models.
+- **Fix:** Audit all MCP tool schemas; add `items` to every array-type parameter.
+
+### 10. Settings-generator.js missing 13 hooks, 9 env vars, and memory config (#1291)
+- **Impact:** Fresh installs get incomplete configuration. 13 hooks never fire, 9 env vars undocumented.
+- **Fix:** Reconcile settings-generator against the actual hooks registry.
+
+---
+
+## P2 β€” Medium (Fix Within 2 Weeks)
+
+### 11. `workflow run` and `task assign` call missing MCP tools (#1281)
+- **Impact:** `workflow_run` and `task_assign` MCP tools referenced in CLI but not registered in the MCP server.
+- **Fix:** Register missing tools or remove dead references.
+
+### 12. CacheManager setInterval missing .unref() prevents process exit (#1256)
+- **Impact:** CLI process hangs after completion. Users must Ctrl+C to exit.
+- **Fix:** Add `.unref()` to all `setInterval` timers in CacheManager.
+
+### 13. MCP server and statusline report 'claude-flow' v3.0.0 branding (#1280)
+- **Impact:** Confusing branding β€” MCP server still identifies as `claude-flow` v3.0.0 instead of `ruflo` v3.5.x.
+- **Fix:** Update MCP server metadata, version string, and statusline template.
+
+### 14. Statusline shows 'Claude Flow V3' instead of 'Ruflo V3' (#1254)
+- **Impact:** Branding inconsistency in IDE status bar.
+- **Fix:** Update statusline configuration defaults.
+
+### 15. MCP server version mismatch β€” reports v3.0.0-alpha, package is v3.5.2 (#1253)
+- **Impact:** Version confusion for users and integrations checking compatibility.
+- **Fix:** Read version from `package.json` at runtime instead of hardcoding.
+
+### 16. doctor: disk space check reports wrong capacity percentage (#1288)
+- **Impact:** Misleading health check output. Low severity but erodes trust in diagnostics.
+- **Fix:** Fix arithmetic in disk space calculation (likely bytes vs KB unit mismatch).
+
+### 17. MCP server status reports 'Stopped' when running in stdio mode (#1289)
+- **Impact:** `status` command shows STOPPED for a correctly-running stdio-mode MCP server. Confusing UX.
+- **Fix:** Detect stdio transport mode and report status accordingly.
+
+### 18. Zero swarms always: `ruflo spawn hive-mind --claude` (#1279)
+- **Impact:** Hive-mind spawning returns zero agents. The flagship multi-agent feature is non-functional via CLI.
+- **Fix:** Debug agent spawn path; likely missing topology init or agent pool connection.
+
+### 19. SonaTrajectoryService does not use native @ruvector/sona API (#1243)
+- **Impact:** SONA neural learning uses a stub instead of the real RuVector API. Learning is no-op.
+- **Fix:** Wire SonaTrajectoryService to actual `@ruvector/sona` package methods.
+
+### 20. Chat UI: web_search sends empty queries β†’ 400 errors
+- **Impact:** MCP `web_search` tool invoked with empty `{}` input, returning 400. Observed in runtime logs.
+- **Fix:** Validate search query is non-empty before dispatching; return graceful "no query" message.
+
+### 21. Chat UI: settings duplication in RVF store
+- **Impact:** 23+ duplicate settings entries for single session. `findOneAndUpdate` creates new docs instead of updating existing ones due to ObjectId matching issue (same root cause as #2, partially fixed).
+- **Fix:** Add deduplication pass on startup; verify `findOneAndUpdate` uses string comparison for `_id`.
+
+---
+
+## P3 β€” Low (Next Release Cycle)
+
+### 22. ruvi MCP server: Edge Functions failing (semantic-search 500, ai-chat 401) (#1276)
+- **Impact:** Supabase Edge Functions intermittently fail. Affects cloud-hosted deployments only.
+- **Fix:** Add retry logic and proper auth token refresh.
+
+### 23. Intelligence-type hooks crash with undefined.toLowerCase (#1290 β€” closed)
+- **Status:** Closed but verify fix doesn't regress.
+
+### 24. Rollback incident templates (#1238, #1262, #1267, #1268)
+- **Impact:** Four identical rollback incident stubs with no content. Noise in issue tracker.
+- **Fix:** Close all four; create a proper incident template.
+
+### 25. Context Optimization Engine β€” 95-98% compression (#1273)
+- **Type:** Feature request. Valuable but not a bug.
+
+### 26. Multilingual embedding model support (#1272)
+- **Type:** Feature request for Chinese embeddings.
+
+### 27. Ship `dsp` as bin entry for `--dangerously-skip-permissions` (#1236)
+- **Type:** Feature request for convenience alias.
+
+### 28. ADR-058: Self-Contained ruflo.rvf Appliance (#1245)
+- **Type:** Enhancement. Already has implementation from Phase 3-4.
+
+### 29. ADR-057: Replace sql.js with RVF native storage (#1242)
+- **Type:** Enhancement. Architectural improvement.
+
+### 30. "How to use ruflo" (#1251)
+- **Type:** Documentation/support request. Needs getting-started guide.
+
+---
+
+## Summary Matrix
+
+| Priority | Count | Key Themes |
+|----------|-------|------------|
+| **P0** | 3 | Supply-chain security, data corruption, platform failure |
+| **P1** | 7 | Daemon stability, hooks reliability, MCP compliance, AgentDB wiring |
+| **P2** | 11 | Branding, version strings, CLI UX, Chat UI runtime, neural wiring |
+| **P3** | 9 | Feature requests, enhancements, housekeeping |
+
+## Decision
+
+1. **Immediately** address P0 items β€” the preinstall script (#1261) is a trust/security emergency.
+2. **This week** fix P1 daemon and hooks issues β€” they block the core value proposition (learning, agents, memory).
+3. **Next sprint** batch P2 branding/version fixes and Chat UI stabilization.
+4. **Backlog** P3 feature requests for roadmap planning.
+
+## Consequences
+
+- P0 fixes may require an emergency patch release (v3.5.3).
+- P1 fixes should ship as v3.6.0 with improved platform test matrix (Windows CI, macOS CI).
+- The AgentDB wiring gap (#1264) is the single highest-leverage fix β€” now that `@claude-flow/memory` is on @latest, the export is available and just needs CLI wiring. This unblocks the entire intelligence layer.