claude-flow
Version:
Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration
215 lines • 17 kB
JSON
{
"_comment": "Project-specific NEW_FIXES registered on each witness regen. Append { id, desc, file, marker } per shipped fix. Never edit verification.md.json directly \u2014 re-run scripts/regen-witness.mjs after editing this file.",
"fixes": [
{
"id": "#1867",
"desc": "Node 26 install: better-sqlite3 dynamic import + optionalDependencies",
"file": "v3/@claude-flow/memory/dist/sqlite-backend.js",
"marker": "(await import('better-sqlite3')).default"
},
{
"id": "#1859",
"desc": "CLI flag/positional priority swap \u2014 named flags win over stray positionals (14 sites in hooks.ts)",
"file": "v3/@claude-flow/cli/dist/src/commands/hooks.js",
"marker": "ctx.flags.file || ctx.args[0]"
},
{
"id": "#1862",
"desc": "ruflo-core PostToolUse hooks call documented CLI flags (-c/-s/-e, -f/-s) instead of bogus --format true. (#1921 moved the invocation behind scripts/ruflo-hook.sh — the documented-flag form is preserved.)",
"file": "plugins/ruflo-core/hooks/hooks.json",
"marker": "post-edit -f \\\"$FILE\\\" -s true"
},
{
"id": "ADR-101-C",
"desc": "Federation policy-engine wires claim-event + agent-handoff message types into CLAIMS_FOR_MESSAGE_TYPE (unblocked Build V3 after 3+ days of failures)",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/policy-engine.js",
"marker": "'agent-handoff': ['federation:write', 'federation:spawn']"
},
{
"id": "#1874-mcp",
"desc": "MCP server returns spec-compliant YYYY-MM-DD string for protocolVersion (was {major,minor,patch} object \u2014 Claude Code Zod rejected it)",
"file": "v3/@claude-flow/mcp/dist/server.js",
"marker": "protocolVersion = '2025-11-25'"
},
{
"id": "#1874-shared",
"desc": "Shared MCP server returns spec-compliant YYYY-MM-DD string for protocolVersion (companion to #1874-mcp)",
"file": "v3/@claude-flow/shared/dist/mcp/server.js",
"marker": "protocolVersion = '2024-11-05'"
},
{
"id": "#1883",
"desc": "memory_import_claude resolves project memory dir via multi-candidate hash (POSIX, WSL `/mnt/<d>/`-translated, leading-dash-stripped, space-replaced) + accepts explicit projectPath override; fixes WSL→Windows-host import returning imported=0",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js",
"marker": "function resolveProjectMemoryDir"
},
{
"id": "#1884",
"desc": "memory_import_claude sanitizes constructed keys via sanitizeMemoryKey before storeEntry, ensuring memory_delete can later remove them; closes the write-path/read-path validation asymmetry that stranded keys with shell-metacharacter section titles",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js",
"marker": "function sanitizeMemoryKey"
},
{
"id": "ADR-097-Phase2a",
"desc": "Federation peer state machine entity layer \u2014 FederationNode gains state field + suspend/evict/reactivate; canTransition gates all mutations; EVICTED is terminal under breaker flow",
"file": "v3/@claude-flow/plugin-agent-federation/dist/domain/entities/federation-node.js",
"marker": "FederationNodeState.ACTIVE"
},
{
"id": "ADR-097-Phase2b",
"desc": "Federation breaker service \u2014 pure evaluatePolicy + stateful FederationBreakerService with bounded per-peer telemetry buffer; coordinator sendMessage gates on !peer.isActive with PEER_SUSPENDED/PEER_EVICTED constant errors (anti-oracle)",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/federation-breaker-service.js",
"marker": "FAILURE_RATIO_EXCEEDED"
},
{
"id": "ADR-097-Phase2b-coordinator",
"desc": "Coordinator outbound short-circuit on !peer.isActive (companion to ADR-097-Phase2b) \u2014 refuses sends to SUSPENDED/EVICTED peers before session lookup, no remaining-budget echo",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/federation-coordinator.js",
"marker": "PEER_EVICTED"
},
{
"id": "ADR-097-Phase4-mcp",
"desc": "Federation Phase 4 operator surface: 3 new MCP tools (federation_breaker_status, federation_evict, federation_reactivate) for inspecting and operating the per-peer circuit breaker",
"file": "v3/@claude-flow/plugin-agent-federation/dist/mcp-tools.js",
"marker": "federation_breaker_status"
},
{
"id": "ADR-097-Phase4-doctor",
"desc": "ruflo doctor health-check: checkFederationBreaker probes plugin loadability + asserts FederationNodeState export presence (catches version-skew regressions where users have an older pre-Phase-2 federation plugin installed)",
"file": "v3/@claude-flow/cli/dist/src/commands/doctor.js",
"marker": "checkFederationBreaker"
},
{
"id": "ADR-097-Phase3-upstream",
"desc": "Federation Phase 3 upstream \u2014 coordinator.reportSpend() with SpendReporter interface + breaker fan-out + federation_report_spend MCP tool. Closes ADR-097 100% end-to-end. Event shape matches cost-tracker consumer contract verbatim (peerId, taskId, tokensUsed, usdSpent, ts, success).",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/spend-reporter.js",
"marker": "InMemorySpendReporter"
},
{
"id": "ADR-104-transport",
"desc": "Federation plugin wires real wire transport via agentic-flow/transport/loader (loadQuicTransport). plugin.ts loads transport in initialize(), binds optional listener on config.port, closes on shutdown. sendToNode now does real ws send to peer endpoint resolved via discovery.getPeer. Validated mac\u2194ruvultra over tailscale (150ms real send).",
"file": "v3/@claude-flow/plugin-agent-federation/dist/plugin.js",
"marker": "agentic-flow/transport/loader"
},
{
"id": "ADR-109-inbound-dispatch",
"desc": "Federation plugin subscribes to transport.onMessage (added in agentic-flow@2.0.12-fix.3) and dispatches inbound envelopes through inbound-dispatcher.ts. Security gates: PEER_UNKNOWN, PEER_SUSPENDED, PEER_EVICTED, MISSING_METADATA. Validated mac\u2192ruvultra: 3/3 envelopes delivered, dispatcher fired, audit recorded 3 rejections.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.js",
"marker": "FEDERATION_INBOUND_EVENT_PREFIX"
},
{
"id": "ADR-110-memory-spend-reporter",
"desc": "Federation MemorySpendReporter \u2014 production SpendReporter that satisfies the cost-tracker consumer contract (namespace=federation-spend, key=fed-spend-<peerId>-<ts>, default TTL 7d). Storage-agnostic via injected MemoryStore interface; integrators wire ruflo memory MCP/CLI/direct.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/spend-reporter.js",
"marker": "MemorySpendReporter"
},
{
"id": "ADR-109-sig-verify",
"desc": "Inbound dispatcher Ed25519 signature verification \u2014 closes the trust gap where sourceNodeId in metadata was a self-claim. canonicalizeEnvelopeForVerify produces deterministic signing bytes. Outbound side signs in plugin.ts sendToNode; receiver verifies against discovery's published peer.publicKey. Reject INVALID_SIGNATURE if missing or bad. Validated alpha.11.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/application/inbound-dispatcher.js",
"marker": "INVALID_SIGNATURE"
},
{
"id": "ADR-104-compression",
"desc": "WebSocket transport enables permessage-deflate (threshold 256B, zlib level 3, no-context-takeover both sides). Bytes-on-wire savings without latency cost \u2014 verified mac\u2194ruvultra at 10KB payload, p50=0ms, p95=1ms (same as 2KB baseline).",
"file": "v3/@claude-flow/plugin-agent-federation/dist/plugin.js",
"marker": "Ed25519 sig verify"
},
{
"id": "ADR-107-tls-pinning",
"desc": "agentic-flow loader supports wss:// + sha256 cert pinning (fail-closed) + CA validation. Federation plugin passes config.tls through to loadQuicTransport. Closes ADR-107 cross-tailnet TLS gap. agentic-flow@2.0.12-fix.6.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/plugin.js",
"marker": "loadQuicTransport"
},
{
"id": "ADR-104-stream-mux",
"desc": "Stream multiplexing \u2014 AgentMessage.streamId, per-(address,streamId) receive queue, scoped+catch-all onMessage handlers. Cross-OS validated mac\u2192ruvultra: 5 rpc + 3 event interleaved on wire, server's per-stream handlers received exactly 5 + 3 in correct order, catch-all saw all 8. agentic-flow@2.0.12-fix.8.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/plugin.js",
"marker": "loadQuicTransport"
},
{
"id": "ADR-111",
"desc": "Federation WG mesh layer (Phases 1-6) \u2014 opt-in WireGuard control plane that propagates federation breaker state to packet-layer reachability. readSafePeerWgFields validator closes peer-content injection vector found during security audit.",
"file": "v3/@claude-flow/plugin-agent-federation/dist/domain/services/wg-mesh-service.js",
"marker": "readSafePeerWgFields"
},
{
"id": "ADR-112",
"desc": "MCP tool discoverability audit \u2014 every tool description must include 'Use when ... is wrong because ...' guidance so Claude picks Ruflo over native Bash/Read/Write/Task correctly. CI guard at scripts/audit-tool-descriptions.mjs gates against regressions via monotone-decreasing baseline at verification/mcp-tool-baseline.json. 285/285 tools have guidance (was 6/285 before this work).",
"file": "scripts/audit-tool-descriptions.mjs",
"marker": "MIN_DESCRIPTION_LENGTH"
},
{
"id": "#1892",
"desc": "Statusline version no longer hardcoded to V3.5/V3.6 \u2014 reads from installed @claude-flow/cli package.json at runtime via resolveBannerVersion() so UI matches `ruflo doctor` output.",
"file": "v3/@claude-flow/cli/.claude/helpers/statusline.js",
"marker": "resolveBannerVersion"
},
{
"id": "#1889",
"desc": "agentdb_pattern-search now has a symmetric memory-store-fallback path (tiered: semantic \u2192 substring). Previously pattern-store wrote to memory-store-fallback while pattern-search only queried ReasoningBank (always empty), so writes were silently lost. New CI smoke at plugins/ruflo-core/scripts/test-mcp-roundtrips.mjs catches the paired-tool-round-trip regression class.",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/agentdb-tools.js",
"marker": "controller: 'memory-store-fallback'"
},
{
"id": "#1906",
"desc": "agent_execute model aliases (haiku/sonnet/opus/inherit) map to current Claude 4.x ids (claude-haiku-4-5-20251001 / claude-sonnet-4-6 / claude-opus-4-7) \u2014 previously stuck on claude-3-*-latest which the Anthropic API 404s. DEFAULT_ANTHROPIC_MODEL = claude-sonnet-4-6. Unit test __tests__/agent-execute-models.test.ts asserts no alias resolves to a claude-3.x id.",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js",
"marker": "claude-sonnet-4-6"
},
{
"id": "#1914",
"desc": "daemon start no longer SIGTERMs daemons belonging to OTHER workspaces (ADR-014 per-workspace scope). Forked daemon argv is stamped with `--workspace <root>` (kept last) and killStaleDaemons{Posix,Windows} filter on it via daemonCommandLineBelongsToWorkspace \u2014 exact trailing match, never a path-prefix match, so `/a/proj` start can't reap `/a/proj-other`'s daemon. Pre-#1914 daemons (no stamp) are left for `daemon stop` (PID file). Unit guard __tests__/daemon-workspace-scope.test.ts.",
"file": "v3/@claude-flow/cli/dist/src/commands/daemon.js",
"marker": "daemonCommandLineBelongsToWorkspace"
},
{
"id": "#1916",
"desc": "agent_logs MCP tool registered (the `ruflo agent logs <id>` CLI subcommand called a tool that didn't exist \u2192 `MCP tool not found: agent_logs`). Also agent_status/agent_list/agent_logs now resolve hive-mind-spawned workers via loadAllAgents() \u2014 hive-mind_spawn writes to `.claude-flow/agents.json`, a different file from `.claude-flow/agents/store.json`, so `agent status <hive-worker-id>` returned `not_found`. (Task-execution dispatch for hive workers \u2014 #1916 items 3/4 \u2014 is a tracked follow-up.) Unit guard __tests__/agent-logs-hive-resolution.test.ts.",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js",
"marker": "loadAllAgents"
},
{
"id": "#1916-guard",
"desc": "CLI\u2194MCP tool coverage CI guard (scripts/audit-cli-mcp-tools.mjs) \u2014 fails if any `ruflo <cmd>` subcommand callMCPTool()s a name not registered in src/mcp-tools/*.ts. Monotone-decreasing baseline at verification/cli-mcp-tool-baseline.json \u2014 now at 0 (was 20). Wired into v3-ci.yml `tool-descriptions-audit` job (already in witness-verify needs[]).",
"file": "scripts/audit-cli-mcp-tools.mjs",
"marker": "cli-mcp-tool-baseline.json"
},
{
"id": "#1916-cli-tools",
"desc": "Registered the 16 MCP tools that CLI subcommands referenced but that were never wired into the registry (the `MCP tool not found` class surfaced by #1916-guard): task_retry, workflow_stop, workflow_validate, session_current/export/import, memory_detailed-stats/cleanup/compress/export/import, hive-mind_optimize-memory, hooks_teammate-idle, hooks_task-completed, mcp_start, mcp_stop \u2014 plus renamed the coverage tools `hooks/coverage-*` \u2192 `hooks_coverage-*` (now match the CLI's underscore calls) and pointed `swarm stop` at `swarm_shutdown`. cli-mcp-tool-baseline.json is now 0.",
"file": "v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js",
"marker": "workflow_validate"
},
{
"id": "#1902-#1903-guard",
"desc": "Plugin package.json install-safety CI guard (scripts/audit-plugin-packages.mjs) \u2014 fails CI on (A) an unpublished @claude-flow/* hard dep / non-optional peer (#1903 ruvector-upstream class), (B) a bare-stable peer range that can't resolve a 3.x prerelease publish (#1902), (C) a main/module/exports path not covered by `files`, (D) post-build, a main/module/exports path that doesn't exist on disk (#1904). Wired into v3-ci.yml as `plugin-package-audit` (builds plugins first so check D is live) and added to witness-verify needs[].",
"file": "scripts/audit-plugin-packages.mjs",
"marker": "KNOWN_PUBLISHED"
},
{
"id": "#1904",
"desc": "plugin-gastown-bridge \u2014 package.json `exports` advertised ./dist/index.mjs (+ ./formula, ./convoy subpaths) that the build never emitted, so those import specifiers 404'd in the published tarball. Fix: tsup.config.ts builds the formula/convoy entries (previously commented out), and package.json exports/main/module point at the actually-emitted .js/.cjs filenames. Validated by the plugin-package-audit CI guard (check D).",
"file": "v3/plugins/gastown-bridge/tsup.config.ts",
"marker": "formula: 'src/formula/index.ts'"
},
{
"id": "#1921",
"desc": "Plugin hooks no longer do a bare `npx <pkg>@alpha hooks \u2026` on every PreToolUse/PostToolUse/Stop fire \u2014 they invoke scripts/ruflo-hook.sh, which prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and ALWAYS exits 0 so a CLI/install crash (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces a hook error in Claude Code or wastes a cold-cache reinstall per turn. CI guard: scripts/audit-hook-commands.mjs (fails on bare-npx-without-prefer-offline / non-guarded CLI invocation) wired into v3-ci.yml `hook-command-audit` + added to witness-verify needs[].",
"file": "scripts/audit-hook-commands.mjs",
"marker": "NONFATAL_RE"
},
{
"id": "#1921-shim",
"desc": "scripts/ruflo-hook.sh \u2014 resilient invoker shipped in each plugin (.claude-plugin/, plugin/, plugins/ruflo-core/): prefers a local `ruflo`/`claude-flow` binary, else `npx --prefer-offline --yes ruflo@alpha`, always `exit 0`. stdin (hook event JSON) passes through unchanged. Companion to #1921.",
"file": "plugins/ruflo-core/scripts/ruflo-hook.sh",
"marker": "npx --prefer-offline --yes ruflo@alpha hooks"
},
{
"id": "#1927",
"desc": "ruflo-cost-tracker track.mjs encodeProjectPath now replaces Windows path separators (`\\`) and the drive colon (`:`), not just `/`, so `D:\\project\\Foo` encodes to `D--project-Foo` (matching Claude Code's ~/.claude/projects/<encoded-cwd>/ scheme) instead of being passed through unchanged on Windows. Behavioral CI guard: smoke.sh step 29b runs track.mjs with a Windows-style TRACK_CWD and asserts the 'looked under' path is encoded. (Also fixed smoke.sh step 8 \u2014 ADR-0001 is Accepted, not Proposed.)",
"file": "plugins/ruflo-cost-tracker/scripts/track.mjs",
"marker": "#1927: Claude Code encodes"
}
]
}