π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdnew file mode 100644index 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.