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): ADR-150 review-round-1 β€” architectural constraint + tightened SelfEvolvingRouter gates + Phase 3 (8.9/10 review)

ruv4f47d64f4eea
diff --git a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
index d6054804c3..125c00d661 100644
--- a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
+++ b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
@@ -29,6 +29,19 @@ Three signals make this the right time to commit a broader integration:
| Both packages MIT-licensed, same maintainer as ruflo | npm registry | HIGH |
| Existing benchmark proves `@metaharness/router` native backend loads on the test host: `mh_native_available: true` | `docs/benchmarks/runs/router-4way-seed99-2026-06-15T14-12-40Z.json` | HIGH |
+## Architectural Constraint (load-bearing invariant)
+
+**MetaHarness may augment ruflo. MetaHarness must never become a required runtime dependency for core orchestration, memory, routing, MCP dispatch, agent execution, or federation.**
+
+Every integration in this ADR, and every future ADR that extends it, must satisfy:
+
+1. **Removable**: ruflo's `npm ls` with all `@metaharness/*` packages removed must still produce a working CLI. The triple-gate pattern used for `@metaharness/router` (env flag + artifact + import success) is the reference implementation.
+2. **Optional in `package.json`**: `@metaharness/*` packages MUST appear in `optionalDependencies` or `peerDependencies` (optional), never in `dependencies`.
+3. **Graceful degradation**: every code path that imports a `@metaharness/*` symbol must catch `MODULE_NOT_FOUND` and fall back to a built-in path (or a clearly-degraded but functional state).
+4. **CI coverage of the absent path**: at least one CI job must run `--ignore-optional` (or equivalent) and assert ruflo still passes its smoke contract. This is the only structural defense against accidentally promoting an optional dep to required.
+
+The intent of this constraint is to prevent ruflo from becoming a hidden second orchestration framework wrapped around its sibling's runtime. Reviewer's framing: *"Ruflo remains operational if every MetaHarness package is removed."* That sentence is now part of the API surface contract β€” any PR that breaks it is a breaking change requiring its own ADR.
+
## Decision
Adopt MetaHarness as ruflo's downstream sibling tool, surfaced through three integration channels that match its three distinct contributions:
@@ -64,12 +77,28 @@ Semver: MINOR β€” additive plugin, additive CI gates, additive MCP tools. No bre
**Phase 2 β€” Expansion (1–4 weeks, one or two MINOR releases).**
- `npx ruflo eject` command wrapping `metaharness --from-existing ./` for one-shot harness extraction (attribution preserved via the `<!-- ruflo-attribution-block -->` convention).
-- `SelfEvolvingRouter` (from `@metaharness/kernel`) parallel-logged alongside the Thompson bandit in `model-router.ts` for two weeks; promote to default only if disagreement < 5% or quality improvement > 2%.
+- `SelfEvolvingRouter` (from `@metaharness/kernel`) parallel-logged alongside the Thompson bandit in `model-router.ts` for two weeks. **Promotion criteria (AND, not OR β€” must satisfy all three):**
+ 1. **Quality**: `qualityScore` improvement > 2% (where `qualityScore` is the existing per-task verdict-weighted reward used by the bandit)
+ 2. **Cost**: `usdPerDecision` increase < 1% (no expensive regressions hiding behind quality wins)
+ 3. **Latency**: p95 routing-decision latency increase < 5%
+ Each metric measured over an identical workload between bandit-only and SelfEvolvingRouter-only periods, separated by a 24h washout window. Failing any one criterion blocks promotion; the bandit stays primary. This tightening is deliberate β€” the "OR" form would let quality gains mask cost or latency regressions, which is the exact failure mode ADR-149's Pareto framing was built to prevent.
- Harness entries in the ruflo plugin registry β€” accept `type: 'harness'` in `discovery.ts`; surface via `npx ruflo plugins list --type harness`.
- 13th background worker `oia-audit` that runs `buildOiaManifest()` + `buildThreatModel()` + `scanMcp()` on a schedule and stores results in the `metaharness-audit` memory namespace.
Each Phase-2 item is independently scoped and can ship as separate MINOR releases.
+**Phase 3 β€” Harness Intelligence Layer (future, scope-only β€” separate ADR per item).**
+
+A class of capability that exists nowhere else in the agent-framework space, made possible by `buildGenomeReport()` + `buildRepoScorecard()` + `buildRegistryEntry()`'s shared schema:
+
+- **Genome similarity search** β€” given two harnesses (or one harness + a candidate repo), compute a similarity vector across the 7 genome sections + scorecard dimensions; surface the closest match in the registry.
+- **Harness recommendation engine** β€” given a repo + a user description, recommend (a) the closest existing harness in the registry, (b) the closest template, and (c) the minimum delta to fork from either.
+- **Fleet-wide architecture drift detection** β€” for organisations running multiple harnesses, track genome-section drift over time; alert when a harness diverges from its template lineage beyond a threshold.
+- **Cross-harness capability graph** β€” `compare <a> <b>` already exists in `harness` CLI; lift it into a fleet-aware diff that answers "which harness in our fleet has the closest capability set to this task?".
+- **Plugin compatibility analysis** β€” given a `plugins/X/` and a target harness, predict whether the plugin's `allowed-tools` requirements are satisfied by the harness's MCP server declarations.
+
+These are scope-only in this ADR. Each item gets its own ADR before implementation. They are listed here so the architectural constraint (above) covers them up front β€” the Harness Intelligence Layer must also satisfy the four removable/optional/graceful/CI-coverage rules.
+
## Consequences
### Positive
@@ -115,6 +144,7 @@ Rejected. Touching the MCP dispatch core affects all 314 tools and is too high-b
- Should the Phase-1 plugin's `harness-mint` skill require explicit user confirmation in the Claude Code UI before writing any files? Lean yes β€” destructive-action-confirmation matches ruflo's "executing actions with care" principle.
- Should the seed-corpus retraining cadence be ad-hoc (Phase-1) or scheduled (e.g., monthly cron in a Phase-2 follow-up)? Defer to Phase-2 once we see the trajectory volume.
- Does the `oia-audit` background worker (Phase 2) belong in `ruflo-loop-workers` or in `ruflo-metaharness`? Probably the latter, since the audit output is MetaHarness-specific.
+- How does the architectural constraint's CI gate (the `--ignore-optional` smoke run) interact with the existing `all-plugins-smoke.yml` workflow? Probably a new sibling workflow `no-metaharness-smoke.yml` that re-runs the same matrix with `--ignore-optional`; lighter than adding a second axis to the existing matrix.
## References