ContextQMD
Back to Ruflo

ADR-059: Bug Triage & Priority Matrix — March 2026

v3/implementation/adrs/ADR-059-bug-triage-2026-03.md

3.6.3014.3 KB
Original Source

ADR-059: Bug Triage & Priority Matrix — March 2026

Status: Accepted — Fixes Verified Date: 2026-03-05 (updated 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

LevelMeaningSLA
P0 — CriticalSecurity risk, data loss, or blocks all usersFix within 24h
P1 — HighCore functionality broken for a platform or major featureFix within 1 week
P2 — MediumIncorrect behavior, cosmetic UX bugs, missing configFix within 2 weeks
P3 — LowEnhancements, polish, branding consistencyNext 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.
  • Status: ✅ FIXED in PR #1298. Preinstall script removed from root package.json. Issue #1261 closed.

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 PR #1297. Added toHexString detection and isObjectIdLike helper to rvf.ts. Verified: two conversations return distinct data via API. 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.
  • Status: ✅ FIXED in PR #1298. All hook commands in settings-generator.ts and executor.ts now use git rev-parse --show-toplevel for absolute path resolution. Issue #1284 closed.

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().
  • Status: ✅ FIXED in PR #1298. Added hookCmd(), hookCmdEsm(), hookHandlerCmd(), autoMemoryCmd() helpers that resolve paths via git rev-parse --show-toplevel. Issue #1259 closed.

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.
  • Status: ✅ FIXED in PR #1298. Added activateControllerRegistry() in memory-initializer.ts (lines 1089-1139). CLI memory init now wires ControllerRegistry singleton, activating ReasoningBank, SkillLibrary, and ExplainableRecall. Issue #1264 closed.

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.
  • Status: ✅ FIXED in PR #1298. Added items field to 13 array schemas across 7 MCP tool files (system-tools, github-tools, hooks-tools, coordination-tools, daa-tools, performance-tools). Issue #1294 closed.

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.
  • Status: ✅ FIXED in PR #1298. MCP system-tools.ts now reads version from package.json at runtime via getPackageVersion(). Branding updated to "RuFlo" across 20+ CLI files. Statusline.cjs updated. Issue #1280 closed.

14. Statusline shows 'Claude Flow V3' instead of 'Ruflo V3' (#1254)

  • Impact: Branding inconsistency in IDE status bar.
  • Fix: Update statusline configuration defaults.
  • Status: ✅ FIXED in PR #1298. Updated statusline.cjs (lines 3, 552, 619) from "Claude Flow V3" to "RuFlo V3". Updated settings.json version to 3.5.2. Issue #1254 closed.

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.
  • Status: ✅ FIXED in PR #1298. Replaced hardcoded '3.0.0-alpha' with PKG_VERSION read from package.json via getPackageVersion() in system-tools.ts. Issue #1253 closed.

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.
  • Status: ✅ FIXED in PR #1298. Added empty-query validation in mcp-bridge/index.js executeTool() — returns graceful MCP-formatted error instead of 400.

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.
  • Status: ✅ FIXED in PR #1298. Added deduplication pass in rvf.ts — sorts by updatedAt, keeps newest, deletes duplicates. findOneAndUpdate now 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

PriorityCountFixedRemainingKey Themes
P0321Supply-chain security, data corruption, platform failure
P1743Daemon stability, hooks reliability, MCP compliance, AgentDB wiring
P21156Branding, version strings, CLI UX, Chat UI runtime, neural wiring
P3909Feature requests, enhancements, housekeeping
Total301119

Resolution Log

Fixes delivered in PR #1297 and PR #1298, merged to main on 2026-03-05.

Issues Closed (11)

#IssuePRFix Summary
1#1261 — Obfuscated preinstall#1298Removed preinstall script from root package.json
2(Chat UI) — RVF ObjectId#1297toHexString detection + isObjectIdLike helper in rvf.ts
5#1284 — Hooks silent failures#1298All hook commands use git rev-parse --show-toplevel
6#1259 — Hooks relative paths#1298hookCmd(), hookCmdEsm(), hookHandlerCmd(), autoMemoryCmd() helpers
8#1264 — AgentDB ControllerRegistry#1298activateControllerRegistry() in memory-initializer.ts
9#1294 — MCP array missing items#129813 schemas fixed across 7 MCP tool files
13#1280 — MCP branding v3.0.0#1298getPackageVersion() reads from package.json at runtime
14#1254 — Statusline branding#1298statusline.cjs updated to "RuFlo V3"
15#1253 — MCP version mismatch#1298Hardcoded '3.0.0-alpha' replaced with PKG_VERSION
20(Chat UI) — Empty web_search#1298Empty-query validation in mcp-bridge/index.js
21(Chat UI) — Settings duplication#1298Dedup pass on startup + string _id comparison

Validation Results (2026-03-05)

All fixes validated via Docker-based regression testing:

  • ✅ Preinstall script removed (no preinstall in package.json)
  • ✅ TypeScript compilation clean (tsc --noEmit)
  • ✅ Docker build succeeds (all containers healthy)
  • ✅ Conversation isolation verified (two distinct conversations return different data)
  • ✅ MCP bridge healthy (/health returns 200)
  • ✅ Empty web_search handled gracefully (no 400 error)
  • ✅ All static assets return 200 (logo, favicons, manifest)

Remaining Open Issues (19)

P0 (1): #1282 Windows daemon/memory init P1 (3): #1283 macOS daemon, #1287 auto-memory-hook resolution, #1291 settings-generator completeness P2 (6): #1281 missing MCP tools, #1256 CacheManager unref, #1288 doctor disk space, #1289 stdio status, #1279 zero swarms, #1243 SONA wiring P3 (9): Feature requests and housekeeping (#1276, #1290, #1238, #1262, #1267, #1268, #1273, #1272, #1236, #1245, #1242, #1251)

Decision

  1. Immediately address P0 items — ✅ Done (2 of 3). #1282 Windows remains.
  2. This week fix P1 hooks/MCP issues — ✅ Partially done (4 of 7). Daemon (#1283), auto-memory (#1287), settings-generator (#1291) remain.
  3. Next sprint batch P2 branding/version fixes — ✅ Partially done (5 of 11). Six P2 items remain.
  4. Backlog P3 feature requests for roadmap planning.

Consequences

  • P0/P1/P2 fixes shipped as PR #1297 and PR #1298 (merged to main).
  • Remaining P0 item (#1282 Windows) requires platform-specific CI matrix — target v3.5.3.
  • Remaining P1 items (#1283, #1287, #1291) should ship as v3.6.0 with macOS CI.
  • The AgentDB wiring gap (#1264) is now resolved — ControllerRegistry is wired and the intelligence layer is active.