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 implementation notes reflect iters 13-59 (iter 60)

ruvcf22b3fb9b19
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
index 35b934ac8b..c7f676a212 100755
--- a/plugins/ruflo-metaharness/scripts/smoke.sh
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -191,6 +191,20 @@ grep -q "execCli(\[\s*'-y'\s*,\s*'metaharness@latest'" "$F" 2>/dev/null || \
grep -q "cwd: opts" "$F" || miss="$miss no-cwd-passthrough"
[[ -z "$miss" ]] && ok || bad "$miss"
+step "17z23. ADR-150 implementation notes reflect iters 13-59 (iter 60)"
+miss=""
+ADR="$ROOT/../../v3/docs/adr/ADR-150-metaharness-integration-surfaces.md"
+grep -q "Phase 3 Β§3.1 βœ… iters 33–59" "$ADR" 2>/dev/null || miss="$miss no-phase3-status"
+grep -q "sixty iterations of /loop" "$ADR" 2>/dev/null || miss="$miss no-60-iter-marker"
+grep -q "Phase 2 continued (iters 13–32)" "$ADR" 2>/dev/null || miss="$miss no-phase2-continued"
+grep -q "Phase 3 Β§3.1 β€” Genome Similarity Search (iters 33–59)" "$ADR" 2>/dev/null || miss="$miss no-phase3-section"
+grep -q "Real-data bug-discovery arc (iters 47-51)" "$ADR" 2>/dev/null || miss="$miss no-bug-arc"
+grep -q "Anti-regression locks (iters 42-44)" "$ADR" 2>/dev/null || miss="$miss no-anti-regression"
+grep -q "Parallelization sweep (iters 56-59)" "$ADR" 2>/dev/null || miss="$miss no-perf-sweep"
+grep -q "14 distinct surfaces" "$ADR" 2>/dev/null || miss="$miss no-surface-count"
+grep -q "Fleet status (post-iter-59)" "$ADR" 2>/dev/null || miss="$miss no-post-iter-59-fleet"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
step "17z22. oia-audit timing field + parallel-speedup gate (iter 59)"
miss=""
OIA="$ROOT/scripts/oia-audit.mjs"
@@ -232,8 +246,9 @@ grep -q "getaddrinfo\|ECONNREFUSED\|ETIMEDOUT" "$HARNESS" 2>/dev/null || miss="$
# Gap C: drift-from-history probes oia-audit to disambiguate no-history vs dep-absent
DRIFT="$ROOT/scripts/drift-from-history.mjs"
grep -q "disambiguate" "$DRIFT" 2>/dev/null || miss="$miss no-disambiguate-comment"
-grep -q "probe.json?.degraded === true" "$DRIFT" 2>/dev/null || miss="$miss no-probe-degraded-check"
-grep -q "emitAndExit.*degraded: true" "$DRIFT" 2>/dev/null || miss="$miss no-degraded-exit-3"
+# iter 58 refactored the probe into the parallel batch β€” accept either form
+grep -qE "probe\.json\?\.degraded === true|auditResult\.json\?\.degraded === true" "$DRIFT" 2>/dev/null || miss="$miss no-degraded-check"
+grep -q "degraded: true" "$DRIFT" 2>/dev/null || miss="$miss no-degraded-exit-3"
[[ -z "$miss" ]] && ok || bad "$miss"
step "17z19. oia-audit parallelizes 5 subprocesses (iter 56 β€” closes iter-55 gap A)"
diff --git a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
index 459a24ca7d..0bc390c45f 100644
--- a/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
+++ b/v3/docs/adr/ADR-150-metaharness-integration-surfaces.md
@@ -1,7 +1,7 @@
# ADR-150 β€” MetaHarness Integration Surfaces in `npx ruflo`
-**Status**: Implemented (Phase 1 βœ… iters 1–3 Β· Phase 2 βœ… iters 4–12 Β· KRR retrain pending production data Β· Phase 3 scoped in [ADR-151](ADR-151-harness-intelligence-layer.md))
-**Date**: 2026-06-16 (revised 2026-06-16 β€” twelve iterations of /loop)
+**Status**: Implemented (Phase 1 βœ… iters 1–3 Β· Phase 2 βœ… iters 4–32 Β· Phase 3 Β§3.1 βœ… iters 33–59 Β· KRR retrain pending production data Β· Phase 3 Β§3.2-Β§3.5 scoped in [ADR-151](ADR-151-harness-intelligence-layer.md))
+**Date**: 2026-06-16 (revised 2026-06-16 β€” sixty iterations of /loop)
**Related**: ADR-148 (cost-optimal router lifecycle via `@metaharness/router`), ADR-149 (per-model cost-optimal routing), ADR-026 (3-tier model routing), ADR-097 (federation budget circuit breaker), ADR-124 (optional native dependencies), ADR-144 (agent-authorization-propagation)
**External reference**: [`ruvnet/agent-harness-generator`](https://github.com/ruvnet/agent-harness-generator) β€” the upstream that publishes `metaharness` + `@metaharness/*`. Same author (rUv), explicitly designed around ruflo primitives.
**Research dossier**: published as a gist (linked from the tracking issue) with full graded-evidence sourcing.
@@ -254,6 +254,112 @@ real routing data; retrain in a follow-up PR.
- 117 SKILL.md files across 34 plugins (was 117/32 β€” adding
6 new SKILL.md files from this plugin pushed the count)
+### Phase 2 continued (iters 13–32)
+Additional Phase-2 surface landed over iters 13-32, all on the same
+`feat/metaharness-integration-research` branch:
+
+- **iter 15** `audit-trend.mjs` β€” diff two `oia-audit` records (drift
+ detection). Pulls baseline + current snapshots from
+ `metaharness-audit` namespace; reports composite severity delta +
+ per-component status + introduced/cleared findings.
+- **iter 16** `audit-list.mjs` β€” enumerate timestamped records in
+ `metaharness-audit` namespace, with `--since 30d`-style filtering.
+- **iter 20-23** `metaharness-tools.ts` MCP surface β€” 7 tools registered:
+ score, genome, mcp-scan, threat-model, oia-audit, audit-list,
+ audit-trend. Each backed by subprocess invocation through the same
+ `_harness.mjs` bridge. `test-mcp-tools.mjs` enforces the runtime
+ contract: `{success, data, degraded, exitCode}` shape, never-throws
+ invariant.
+- **iter 27-29** mint hardening β€” explicit npx argv (was a single
+ string token), `cwd: dirname(target)` + `basename(target)` as cliName
+ workaround for upstream `--target` bug (now fixed at [email protected]).
+- **iter 30-32** `.harness/mcp-policy.json` + manifest.json β€” security
+ posture: default-deny, allow shell/network/file-write: false,
+ audit-log on; iter-31 exact-pins close LOW severity vector; iter-32
+ manifest documents witness-key gap.
+
+### Phase 3 Β§3.1 β€” Genome Similarity Search (iters 33–59)
+Phase-3 Β§3.1 from [ADR-152](ADR-152-genome-similarity-search.md) shipped
+across 27 iterations. The implementation is now deeply integrated across
+**14 distinct surfaces**:
+
+| # | Surface | Iter |
+|---|---|---|
+| 1 | Spike with 2 invariants (selfMatch, verticalAffinity) | 35 |
+| 2 | Production module `_similarity.mjs` (5 exports) | 36 |
+| 3 | CLI skill `similarity.mjs` (file + memory inputs) | 36 |
+| 4 | MCP tool `metaharness_similarity` | 36 |
+| 5 | CLI dispatcher entry | 36 |
+| 6 | MCP runtime contract test (74β†’115 assertions) | 37, 43, 52 |
+| 7 | Pipeline consumers (oia-audit fingerprint + audit-trend) | 38 |
+| 8 | 53 unit-test assertions over 8 phases | 39 |
+| 9 | Dedicated CI job `similarity-tests` | 40 |
+| 10 | Performance benchmark with regression gate | 41 |
+| 11 | End-to-end pipeline roundtrip test | 47, 49, 51 |
+| 12 | CI job `metaharness-real-data` running roundtrip | 48 |
+| 13 | Doctor health check distinct from upstream | 45, 52 |
+| 14 | `drift-from-history` one-command primitive + MCP tool | 53, 54 |
+
+#### Real-data bug-discovery arc (iters 47-51)
+End-to-end roundtrip caught FOUR latent bugs that synthetic-fixture
+tests had missed for 9+ iterations each:
+- **iter 47** β€” schema mismatch: oia-audit captured fingerprint via
+ the wrong CLI binary (harness vs metaharness; different schemas).
+ Fingerprint silently fed wrong shape to `_similarity.mjs`. Fixed by
+ routing score+genome through `runMetaharness`.
+- **iter 49** β€” mcp-scan dead-code: `audit-trend` read `json.findings`
+ expecting an array, but mcp-scan emitted text-only. Flagged.
+- **iter 50** β€” closed (b) via shared `parseMcpScanText` parser in
+ `_harness.mjs`, wired into both mcp-scan.mjs and oia-audit.mjs.
+- **iter 51** β€” proved drift detection actually fires on mutated
+ audits, not just confirms self-match. Stage 7 mutates all 3
+ similarity components; verdict flips from near-identical to
+ moderate-drift; alert at 0.95 fires.
+
+#### Anti-regression locks (iters 42-44)
+- **iter 42** β€” fixed dispatcher's flag-drop bug (silent for 6 iters).
+ Iter-36 wired SUBCOMMANDS but only `context.args` (positionals) were
+ forwarded to subprocess. Now reads `context.flags` and re-kebabs
+ camelCase→kebab. Affects ALL metaharness subcommands.
+- **iter 43** β€” generalized iter-42's catch into 16 structural
+ positive-case assertions on the MCP runtime test.
+- **iter 44** β€” MCP wrapper `success = (exitCode === 0)` (was
+ `!degraded`). Affects all 9 metaharness MCP tools. Documented 3
+ observable cases.
+
+#### Parallelization sweep (iters 56-59)
+Composite operations now use Promise.all where dependency graph allows:
+- **iter 56** β€” oia-audit's 5 subprocess calls parallelize β†’ 4.59x
+ measured speedup on Apple Silicon / Node 22 (close to theoretical 5x).
+- **iter 58** β€” drift-from-history's audit-list + oia-audit
+ parallelize β†’ ~30% reduction. Folded the iter-57 probe into the same
+ batch.
+- **iter 59** β€” `timing.{wallMs, sumComponentMs, parallelSpeedup}`
+ field in oia-audit output. Smoke gate asserts speedup > 2.0 to catch
+ silent serialization regression.
+
+#### Iter-55 graceful-degradation drill expansion
+The architectural-constraint workflow (`no-metaharness-smoke.yml`)
+drilled only 4 skills pre-iter-55. Extended to 7. Discovered 3 latent
+gaps (oia-audit timeout, mint marker missing, drift-from-history exit
+code), all closed in iters 56-57.
+
+#### Upstream contribution
+Two issues filed at `ruvnet/agent-harness-generator`:
+- [#15](https://github.com/ruvnet/agent-harness-generator/issues/15) β€”
+ harness vs metaharness CLI schema confusion (iter 47 discovery)
+- [#16](https://github.com/ruvnet/agent-harness-generator/issues/16) β€”
+ harness mcp-scan plain text instead of JSON (iter 50 discovery)
+Both still OPEN as of iter 59. Downstream workarounds remain in place.
+
+### Fleet status (post-iter-59)
+- Smoke step count: 19 β†’ 62 (43 new structural invariants since iter 8)
+- MCP tool runtime contract: 115 assertions across 9 tools
+- Real-data roundtrip: 31 pipeline assertions
+- Unit tests: 53 similarity-module assertions
+- Total ruflo-metaharness smoke surface: ~260 assertions
+- 33/33 plugin fleet still green
+
### Quote architecture invariant β€” no static metaharness imports
The single non-test ruflo source file that statically imports a