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

14.1 KB
Raw Blame

Ruflo Project-Wide Quality Sweep

Branch: chore/project-wide-quality-sweep
Cut from: cdd5308d8 (main @ [email protected] / @claude-flow/[email protected])
Test baseline: 1999 passing | 46 skipped
Do not regress: [email protected], @claude-flow/[email protected], [email protected]
Target release: 3.11.0 (unpublished until explicit user approval)


Session Log

Session 1 β€” 2026-05-25 (continued through Session 2 β€” 2026-05-25)

Baseline established + all critical fixes landed. Territories T2-T10 now clean or done.

Session 1 commits:

  • 6d864e578 chore(quality-sweep): T1/T3/T5 β€” dep dedup, dead script removal, stale comment
  • d82c5c721 chore(quality-sweep): T7/T10 β€” remove trivial assertion, tighten protobufjs override
  • coordination_orchestrate stub β€” add issue #2140 reference to _note field
  • STATUS.md β€” update stale 3.6.x counts to 3.10.x reality (MCP 323, CLI 45)
  • ff685013a witness regen pass β€” 117 verified, 0 missing, 0 drifted

Session 2 commits:

  • 2b14d47bd chore(ci): #2141-T3 β€” wire smoke-memory-no-stray-db to CI (ADR-125 P7)
  • c8ff56333 docs(status): #2141-T9 β€” correct plugin (32β†’33) and agent (43β†’45) counts

Tracking issue: #2138
Draft PR: #2139

What was completed across sessions:

  • T1 (partial): Fixed dep dedup bug in cli/package.json β€” @claude-flow/memory, @claude-flow/embeddings, @claude-flow/security removed from dependencies (were dynamic-import only; belonged in optionalDependencies only). This fixes the npm 11.x arborist crash class (#1147/#2018). 66 dual exports (named + default) tracked in issue #2141 β€” all defaults confirmed unimported; removal deferred as a focused PR.
  • T2 (done): All plugin scripts wired or documented. 0 violations.
  • T3 (done): Deleted scripts/regenerate-witness.mjs (pointed at non-existent root verification.md.json). Wired scripts/smoke-memory-no-stray-db.mjs to CI as memory-no-stray-db-smoke job. 5 remaining unreferenced scripts are intentional utilities (documented).
  • T4 (clean): All 5 TODO/FIXME entries in cli/src are part of the analyze tool's scan logic, not implementation TODOs.
  • T5 (done): Removed stale "placeholder" comment from analyze.ts. coordination_orchestrate stub linked to issue #2140. All stubs either honestly labeled or removed.
  • T6 (deferred to 3.12.0): No obvious O(n2) in hot paths. Profile-guided work requires instrumentation.
  • T7 (done): All 46 skips documented. Removed the one expect(true).toBe(true) trivial assertion in coverage-router.test.ts.
  • T8 (done): All file paths cited in ADR-120 through ADR-130 verified to exist. No drift.
  • T9 (done): STATUS.md updated β€” MCP 300β†’323, CLI 49β†’45, plugins 32β†’33, agents 43β†’45. All counts match HEAD.
  • T10 (done): Added overrides.protobufjs = >=7.5.6 to cli/package.json. Tightened ruflo/package.json from >=7.5.5 to >=7.5.6 (covers all 3 protobufjs CVEs). All 25 high vulns traced to optional/dev transitive deps β€” production paths clean.
  • T11 (done): Witness regen ran at ff685013a β€” 117 verified, 0 missing, 0 drifted.

Counts verified:

  • MCP tools: 323
  • CLI top-level commands: 45
  • Plugins with manifests: 33
  • Agent definitions: 45
  • Test baseline: 1999 passing | 46 skipped

Next session resumes: T1 remaining (66 dual exports β€” separate focused PR per issue #2141), then 3.11.0 release prep.


Territory Status

# Territory Status Violation Count (baseline) Done Criteria
T1 Dead-code sweep -- v3/@claude-flow/cli/src/** partial Dep dedup fixed; 66 dual exports tracked in #2141 (defaults never imported; removal = focused PR) knip clean, no unused exports, no unreachable branches
T2 Dead-code sweep -- plugins/** done 0 violations found; all scripts wired done
T3 Stale scripts done regenerate-witness.mjs deleted; smoke-memory-no-stray-db wired to CI; 5 remaining are documented utilities done
T4 Slop hunt -- any types, magic numbers, TODOs clean 0 implementation TODOs; any in non-ambient code is acceptable optional-module pattern done
T5 Mocked / placeholder claims done All placeholders either wired, honestly stubbed with issue ref (#2140), or legitimate fallbacks done
T6 Perf hotspots deferred to 3.12.0 Requires profiling infra; no obvious O(n2) in hot paths confirmed done (deferred scope)
T7 Test honesty done 0 trivial assertions; all 46 skips documented done
T8 ADR implementation drift done All file paths in ADR-120 through ADR-130 verified at HEAD done
T9 Docs reality done STATUS.md updated: MCP 323, CLI 45, plugins 33, agents 45 done
T10 Dependency hygiene done protobufjs critical fixed; all 25 high vulns traced to optional/dev transitive deps; production paths clean done
T11 Witness pass done ff685013a: 117 verified, 0 missing, 0 drifted done

T1 β€” Dead-code sweep: v3/@claude-flow/cli/src/**

Status: in_progress
Baseline snapshot (2026-05-25):

  • 194 TypeScript files in cli/src
  • 1314 exported symbols
  • log-filters.ts at root level β€” 0 import refs in src (but imported via side-effect in index.ts β€” keep)
  • config-adapter.ts β€” used (lazy import + 2 test files)
  • mcp-client.ts β€” 20+ references across src
  • optional-modules.d.ts β€” 438 lines, 95 any declarations for ambient optional modules (legitimate pattern for unhoisted dynamic imports β€” keep as-is)
  • Commented-out code blocks: 98 candidates (needs manual review)
  • 229 total : any / as any usages

Acceptance criteria:

  • knip run showing 0 unused exports (or all remaining justified)
  • No files with 0 callers that aren't intentional side-effects
  • No unreachable code blocks (tsc --strictNullChecks catches most)
  • Commented-out blocks reviewed; scaffolding removed

Blockers: need to run npx knip β€” will install as devDep or run via npx


T2 β€” Dead-code sweep: plugins/**

Status: pending
Baseline snapshot:

  • 6862 source files across plugins/
  • No package-level dep overlap found (0 packages with multiple version specs)

Acceptance criteria:

  • Each plugin's exported API used by at least one caller or marked @internal
  • No plugin shipping identical logic to another plugin (duplicated utilities)

T3 β€” Stale scripts

Status: pending
Baseline snapshot (2026-05-25):

  • 52 total .mjs scripts
  • 55 referenced in CI workflows
  • 6 NOT referenced in any CI workflow:
    • scripts/bulk-fix-tool-descriptions.mjs β€” one-shot tool, keep or delete
    • scripts/inventory-capabilities.mjs β€” referenced in STATUS.md doc, not CI
    • scripts/regen-witness.mjs β€” thin wrapper around plugin regen, not in CI (uses regenerate-witness.mjs instead)
    • scripts/regenerate-witness.mjs β€” the canonical regen script (also not in CI!)
    • scripts/sign-witness-from-inventory.mjs β€” one-shot signing tool
    • scripts/smoke-memory-no-stray-db.mjs β€” smoke test not wired to CI
  • DUPLICATE: regen-witness.mjs vs regenerate-witness.mjs β€” both exist, different implementations (70 vs 102 lines), former is a "thin wrapper" per its header. Needs consolidation.

Acceptance criteria:

  • Each unreferenced script either (a) added to a CI job, or (b) deleted with justification commit
  • regen-witness.mjs and regenerate-witness.mjs consolidated to one canonical file
  • smoke-memory-no-stray-db.mjs wired to CI smoke job or deleted

T4 β€” Slop hunt: any types, magic numbers, TODOs

Status: pending
Baseline snapshot (2026-05-25):

  • 229 : any / as any usages in cli/src
    • 95 in types/optional-modules.d.ts (ambient decls β€” LEGITIMATE, keep)
    • 31 in memory/memory-bridge.ts β€” highest priority for real types
    • 9 in memory/memory-initializer.ts
    • 6 in ruvector/diskann-backend.ts
    • 6 in mcp-tools/agentdb-tools.ts
    • remaining 82 across 46 other files
  • 5 TODO/FIXME/XXX in cli/src (low count, needs full grep)
  • 373 magic-number candidates (many false positives β€” port numbers, timeouts, etc.)

Acceptance criteria:

  • any in non-ambient code reduced by 50%+ (target: <70 non-ambient usages)
  • All TODOs link to a GitHub issue or are removed
  • Magic numbers with no comment named as constants (top 20 by frequency)

T5 β€” Mocked / placeholder claims

Status: pending
Baseline snapshot (2026-05-25):

  • hooks-tools.ts:3115/3141 β€” implementation: 'placeholder' when SONA unavailable. The code has a real fallback path (ReasoningBank) β€” honest about it via the _stub flag in response
  • coordination-tools.ts:730/762 β€” coordination_orchestrate records but does not execute. Has _note explaining this honestly
  • commands/analyze.ts:304 β€” "Code subcommand (placeholder for future code analysis)" β€” dead code comment, check if command is wired
  • memory-tools.ts:1085 β€” doc string says "placeholder perf metrics" β€” honest in the description
  • appliance/rvfa-builder.ts:298 β€” stub verify script fallback when appliance-specific script not found (legitimate fallback)
  • gguf-engine.ts:285 β€” "metadata-only stub" when node-llama-cpp not installed (legitimate optional)

Acceptance criteria:

  • No public MCP tool returns _stub: true without a companion issue tracking real implementation
  • analyze code subcommand either implemented or removed from CLI
  • "placeholder perf metrics" in memory-tools doc string updated to match reality

T6 β€” Performance hotspots

Status: pending
Deferred scope note: Requires profiling data to identify real hotspots. Priority files:

  • memory/memory-bridge.ts (2300+ lines, complex dispatch)
  • memory/memory-initializer.ts
  • MCP tool dispatch loop
  • WASM agent composition

Will not defer: obvious O(nΒ²) patterns can be found by static analysis. Profile-guided work is a 3.12.0 candidate if it requires instrumentation infrastructure not currently present.


T7 β€” Test honesty

Status: pending
Baseline snapshot (2026-05-25):

  • 5 trivial assertion candidates (expect(true), expect(false), placeholder pattern)
  • 46 skipped tests (vitest reporter confirms this matches the official count)
  • Per IMPROVEMENT-ROADMAP.md Item 1: 4 skipped integration tests in v3/__tests__/integration/ covering real production bugs

Acceptance criteria:

  • Zero expect(true).toBe(true) style assertions
  • All 46 skips documented with // skip: reason comment or re-enabled
  • Integration tests from Item 1 (#1872) evaluated β€” re-enable if fixable within sweep scope

T8 β€” ADR ↔ implementation drift

Status: pending
Scope: ADR-120 through ADR-130 (the 11 most recent ADRs)
Initial findings:

  • ADR-120: no file paths cited
  • ADR-122: references v3/@claude-flow/browser/package.json β€” browser package exists?
  • ADR-124: same browser package references
  • ADR-126: cites v3/@claude-flow/memory/src/agentdb-adapter.ts
  • ADR-127: cites v3/@claude-flow/cli/.claude/helpers/github-safe.js β€” known to exist
  • ADR-128: cites .claude/commands/ and .claude/skills/
  • ADR-129: cites v3/@claude-flow/cli/src/ruvector/agent-wasm.ts

Acceptance criteria:

  • Every file path cited in ADR-120 through ADR-130 verified to exist
  • Stale paths documented in ADR with correction note or ADR superseded

T9 β€” Docs ↔ reality

Status: pending
Claims to verify (from STATUS.md, now stale since STATUS.md references 3.6.x):

  • STATUS.md: 300 MCP tools, 49 CLI commands, 32 plugins, 43 agents
  • IMPROVEMENT-ROADMAP.md: references specific issue numbers (#1872, #2030, #2032, etc.)
  • USERGUIDE.md: lists every CLI command

Note: STATUS.md is outdated (references "branch fix/issues-may-1-3", [email protected]) β€” needs update to reflect 3.10.x reality.

Acceptance criteria:

  • MCP tool count verified against actual registered tools
  • CLI command count verified
  • STATUS.md updated to reflect 3.10.x state

T10 β€” Dependency hygiene

Status: pending
Baseline snapshot (2026-05-25):

  • npm audit on cli: 45 vulnerabilities
    • 1 critical: protobufjs
    • 25 high: includes @xenova/transformers, agentdb, agentic-flow, axios, cacache, @hono/node-server, @opentelemetry/*
    • 17 moderate, 2 low
  • 0 packages with conflicting semver ranges across workspace (clean)
  • CLI has 11 direct deps, 17 optional deps, 2 devDeps

Triage approach: Many vulns likely inherited via optional deps (xenova, agentdb). Check if any are production code paths vs. truly optional/dev.

Acceptance criteria:

  • All vulns triaged: either fixed, pinned with override, or documented as "deferred + reason"
  • protobufjs critical addressed (update or override)
  • No truly unused direct deps

T11 β€” Witness pass

Status: pending (depends on T1-T10 changes landing)
Current state: Per IMPROVEMENT-ROADMAP.md Item 2, last scheduled run showed missing=95 drift=2
Note: regen-witness.mjs (wrapper) and regenerate-witness.mjs (canonical) β€” T3 consolidates this

Acceptance criteria:

  • node scripts/regen-witness.mjs exits 0
  • scripts/smoke-witness-marker-drift.mjs exits 0 (if it exists)
  • New witness entries added for all changed files in T1-T10

Blockers (current)

None β€” first iteration, starting clean.


Hard constraints (reference)

  • Test baseline: β‰₯1999 passing at every push
  • No --no-verify on commits
  • No mass deletion without cited callers + commit justification
  • Mac/Linux behavior unchanged
  • No auto-publish
  • Commits stay on chore/project-wide-quality-sweep

Remaining work (3.11.0 release prep)

  • T1 remaining: Open dedicated PR to remove 66 unused export default lines (tracked in #2141). Each line is in commands/, production/, mcp-tools/, ruvector/ files confirmed by grep to have zero default-import callers. Small scope, easy review.
  • Version bump: bump @claude-flow/cli and ruflo to 3.11.0 (minor β€” new MCP tools added since 3.10.x)
  • Publish 3.11.0 artifacts (requires explicit user approval per hard constraints)
  • Open final PR for chore/project-wide-quality-sweep β†’ main (draft PR #2139 already exists)