π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(metaharness): drift-from-history β one-command drift detection (iter 53)
ruvbe1401d8ab3b
diff --git a/plugins/ruflo-metaharness/scripts/drift-from-history.mjs b/plugins/ruflo-metaharness/scripts/drift-from-history.mjsnew file mode 100755index 0000000000..5fb6d468b3--- /dev/null+++ b/plugins/ruflo-metaharness/scripts/drift-from-history.mjs@@ -0,0 +1,199 @@+#!/usr/bin/env node+// drift-from-history.mjs β iter 53 β one-command drift detection.+//+// Composes the existing pipeline into the workflow users actually want:+// "did my repo drift since the last audit?" Implementation:+//+// 1. List audit records from `metaharness-audit` memory namespace+// 2. Pick the most recent one (or filter --since Nd to skip recent ones+// and use an older baseline)+// 3. Run a fresh oia-audit against the current repo state+// 4. Diff via audit-trend β structural distance + severity rollup+// 5. Alert if structural similarity falls below --threshold+//+// Until this iter, doing this required the user to:+// $ npx ruflo metaharness audit-list --format json+// $ # ... pick a key by hand from the listing+// $ npx ruflo metaharness oia-audit --format json > /tmp/curr.json+// $ npx ruflo metaharness audit-trend --baseline-key X --current-file /tmp/curr.json+// Now it's:+// $ npx ruflo metaharness drift-from-history --threshold 0.95+//+// USAGE+// node scripts/drift-from-history.mjs # default: last record vs now+// node scripts/drift-from-history.mjs --baseline-since 7d # use an audit β₯ 7d old+// node scripts/drift-from-history.mjs --threshold 0.95 # alert under 0.95 similarity+// node scripts/drift-from-history.mjs --format json+// node scripts/drift-from-history.mjs --dry-run # don't persist current+//+// EXIT CODES+// 0 ok (no drift below --threshold)+// 1 drift below --threshold (alert fired)+// 2 config / input error (no history available, etc.)+// 3 upstream metaharness absent β degraded payload returned++import { spawnSync } from 'node:child_process';+import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, dirname } from 'node:path';+import { fileURLToPath } from 'node:url';++const SCRIPTS_DIR = dirname(fileURLToPath(import.meta.url));+const NS = process.env.METAHARNESS_AUDIT_NAMESPACE || 'metaharness-audit';+const CLI_PKG = process.env.CLI_CORE === '1'+ ? '@claude-flow/cli-core@alpha'+ : '@claude-flow/cli@latest';++const ARGS = (() => {+ const a = {+ path: '.', baselineSince: null, threshold: 0.95,+ dryRun: false, format: 'table',+ };+ for (let i = 2; i < process.argv.length; i++) {+ const v = process.argv[i];+ if (v === '--path') a.path = process.argv[++i];+ else if (v === '--baseline-since') a.baselineSince = process.argv[++i];+ else if (v === '--threshold') a.threshold = Number(process.argv[++i]);+ else if (v === '--dry-run') a.dryRun = true;+ else if (v === '--format') a.format = process.argv[++i];+ }+ return a;+})();++function emitAndExit(payload, code) {+ if (ARGS.format === 'json') {+ console.log(JSON.stringify(payload, null, 2));+ } else {+ console.log(`# drift-from-history\n`);+ if (payload.degraded) {+ console.log(`β ${payload.reason}`);+ } else if (payload.error) {+ console.log(`β ${payload.error}`);+ } else {+ console.log(`Baseline: ${payload.baseline?.key ?? payload.baseline?.startedAt}`);+ console.log(`Current: ${payload.current?.startedAt ?? '(fresh)'}`);+ console.log('');+ const sd = payload.drift?.structuralDistance;+ if (sd && sd.verdict !== 'unavailable') {+ console.log(`Structural similarity: ${sd.overall} (${sd.verdict})`);+ console.log(`Distance: ${sd.distance}`);+ }+ console.log('');+ if (payload.alert?.triggered) {+ console.log(`β ALERT: ${payload.alert.reason}`);+ } else if (payload.alert) {+ console.log(`β ${payload.alert.reason}`);+ }+ }+ }+ process.exit(code);+}++function runScriptJson(script, args) {+ const r = spawnSync('node', [join(SCRIPTS_DIR, script), ...args, '--format', 'json'], {+ encoding: 'utf-8',+ });+ const m = /\{[\s\S]*\}/.exec(r.stdout || '');+ const json = m ? JSON.parse(m[0]) : null;+ // audit-list emits {records:[...]} β check that shape too+ const arrM = /\[[\s\S]*\]/.exec(r.stdout || '');+ return { json, exitCode: r.status ?? -1, stdout: r.stdout || '', stderr: r.stderr || '', arrMatch: arrM };+}++async function main() {+ // Step 1: list audit records+ const listArgs = ['--limit', '50'];+ if (ARGS.baselineSince) listArgs.push('--since', ARGS.baselineSince);+ const listResult = runScriptJson('audit-list.mjs', listArgs);+ if (listResult.exitCode !== 0) {+ emitAndExit({+ error: `audit-list failed (exit ${listResult.exitCode})`,+ stderrTail: listResult.stderr.slice(-200),+ }, 2);+ }+ const records = listResult.json?.records ?? listResult.json?.entries ?? [];+ if (records.length === 0) {+ emitAndExit({+ error: 'no audit records found in namespace ' + NS,+ hint: 'Run `ruflo metaharness oia-audit` at least once to seed history.',+ }, 2);+ }+ // Pick the most recent record (records are typically newest-first; if not,+ // sort by startedAt). Each record's key is in the entry.+ const sorted = [...records].sort((a, b) =>+ String(b.startedAt ?? b.key ?? '').localeCompare(String(a.startedAt ?? a.key ?? '')));+ const baseline = sorted[0];+ if (!baseline?.key) {+ emitAndExit({+ error: 'audit record has no `key` field β cannot reference',+ sample: baseline,+ }, 2);+ }++ // Step 2: run fresh oia-audit (write to temp file so audit-trend can read it)+ const tmp = mkdtempSync(join(tmpdir(), 'drift-from-history-'));+ const currPath = join(tmp, 'current.json');+ try {+ const auditArgs = ['--path', ARGS.path];+ if (ARGS.dryRun) auditArgs.push('--dry-run');+ const auditResult = runScriptJson('oia-audit.mjs', auditArgs);+ if (!auditResult.json || auditResult.exitCode !== 0) {+ emitAndExit({+ error: `oia-audit failed (exit ${auditResult.exitCode})`,+ stderrTail: auditResult.stderr.slice(-200),+ }, 2);+ }+ if (auditResult.json.degraded === true) {+ emitAndExit({+ degraded: true,+ reason: auditResult.json.reason || 'metaharness-not-available',+ }, 3);+ }+ writeFileSync(currPath, JSON.stringify(auditResult.json));++ // Step 3: audit-trend+ const trendArgs = [+ '--baseline-key', baseline.key,+ '--current', currPath,+ '--alert-on-distance-below', String(ARGS.threshold),+ ];+ const trendResult = runScriptJson('audit-trend.mjs', trendArgs);+ if (!trendResult.json) {+ emitAndExit({+ error: `audit-trend produced no JSON (exit ${trendResult.exitCode})`,+ stderrTail: trendResult.stderr.slice(-200),+ }, 2);+ }+ const trend = trendResult.json;+ const alertTriggered = trendResult.exitCode === 1;++ const payload = {+ adr: 'ADR-150 + ADR-152 Β§3.1',+ command: 'drift-from-history',+ baseline: {+ key: baseline.key,+ startedAt: baseline.startedAt ?? null,+ },+ current: {+ startedAt: auditResult.json.startedAt,+ composite: auditResult.json.composite,+ },+ drift: trend.delta,+ alert: {+ threshold: ARGS.threshold,+ triggered: alertTriggered,+ reason: trend.alert?.reasons?.join('; ')+ ?? (alertTriggered ? `similarity < ${ARGS.threshold}` : `similarity β₯ ${ARGS.threshold} β OK`),+ },+ generatedAt: new Date().toISOString(),+ };+ emitAndExit(payload, alertTriggered ? 1 : 0);+ } finally {+ try { rmSync(tmp, { recursive: true, force: true }); } catch { /* ignore */ }+ }+}++main().catch((e) => {+ console.error('drift-from-history crashed:', e.message || e);+ process.exit(2);+});diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.shindex 3175708289..5003f73763 100755--- a/plugins/ruflo-metaharness/scripts/smoke.sh+++ b/plugins/ruflo-metaharness/scripts/smoke.sh@@ -191,6 +191,30 @@ 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 "17z16. drift-from-history one-command primitive (iter 53)"+miss=""+F="$ROOT/scripts/drift-from-history.mjs"+[[ -x "$F" ]] || miss="$miss not-executable"+node --check "$F" 2>/dev/null || miss="$miss syntax-error"+# Required flags+grep -q -- "--baseline-since" "$F" 2>/dev/null || miss="$miss no-baseline-since"+grep -q -- "--threshold" "$F" 2>/dev/null || miss="$miss no-threshold"+grep -q -- "--dry-run" "$F" 2>/dev/null || miss="$miss no-dry-run"+# Composes the 3 sub-scripts+grep -q "audit-list.mjs" "$F" 2>/dev/null || miss="$miss no-audit-list-compose"+grep -q "oia-audit.mjs" "$F" 2>/dev/null || miss="$miss no-oia-audit-compose"+grep -q "audit-trend.mjs" "$F" 2>/dev/null || miss="$miss no-audit-trend-compose"+# Skill manifest + dispatcher entry+SK="$ROOT/skills/harness-drift-from-history/SKILL.md"+[[ -f "$SK" ]] || miss="$miss no-skill-md"+grep -q "name: harness-drift-from-history" "$SK" 2>/dev/null || miss="$miss skill-name-wrong"+DISP="$ROOT/../../v3/@claude-flow/cli/src/commands/metaharness.ts"+grep -q "'drift-from-history': 'drift-from-history.mjs'" "$DISP" 2>/dev/null || miss="$miss no-dispatcher-entry"+grep -q "drift-from-history.*iter 53" "$DISP" 2>/dev/null || miss="$miss no-help-line"+# 4-exit-code semantic β script exits 0/1/2/3 based on threshold + dep state+grep -q "process.exit(code)\|process.exit(2)\|process.exit(3)" "$F" 2>/dev/null || miss="$miss no-exit-semantics"+[[ -z "$miss" ]] && ok || bad "$miss"+step "17z15. iter-50 parser locked at MCP layer + doctor (iter 52)"miss=""# MCP runtime test enrolls mcp_scan positive casediff --git a/plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.md b/plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.mdnew file mode 100644index 0000000000..5e48feb907--- /dev/null+++ b/plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.md@@ -0,0 +1,65 @@+---+name: harness-drift-from-history+description: One-command drift detection. Composes audit-list + oia-audit + audit-trend into a single primitive β finds the most recent audit in `metaharness-audit` namespace, runs a fresh audit against the current repo, diffs them via ADR-152 Β§3.1 similarity, and alerts when structural distance crosses `--threshold`. Iter 53 of ADR-150 deep integration.+argument-hint: "[--path .] [--baseline-since 7d] [--threshold 0.95] [--dry-run] [--format json|table]"+allowed-tools: Bash+---++The natural ops question after running `oia-audit` weekly is "did anything drift?" Before this skill, the answer required a three-step sequence:++```bash+npx ruflo metaharness audit-list --format json # β pick a key by hand+npx ruflo metaharness oia-audit --format json > /tmp/curr.json+npx ruflo metaharness audit-trend \+ --baseline-key <picked-key> --current /tmp/curr.json \+ --alert-on-distance-below 0.95+```++This skill collapses it into one command:++```bash+npx ruflo metaharness drift-from-history --threshold 0.95+```++## What it does++1. Lists records from `metaharness-audit` namespace via audit-list.mjs+2. Picks the most recent record by `startedAt` (or `--baseline-since 7d` skips anything newer than 7 days)+3. Runs a fresh `oia-audit` against the current path+4. Diffs the two via audit-trend, applying `--alert-on-distance-below ${threshold}`+5. Returns the structured drift report++## Architectural constraint inheritance (ADR-150)++| Constraint | How drift-from-history satisfies it |+|---|---|+| Removable | Pure subprocess composition over existing scripts β no new `@metaharness/*` import |+| Optional | If oia-audit reports `degraded:true`, this skill exits 3 with a degraded payload |+| Graceful | Empty audit history β exit 2 with hint to seed it; never crashes |+| CI-gate | Smoke step 17z16 anchors the dispatcher entry + subcommand listing |++## Exit codes++- 0 β similarity β₯ threshold (or threshold not crossed)+- 1 β drift detected: similarity < threshold (alert fired)+- 2 β config error (no history, audit-list failed)+- 3 β upstream metaharness absent (degraded payload returned)++## Example++```bash+$ npx ruflo metaharness drift-from-history --threshold 0.95+# drift-from-history++Baseline: audit-2026-06-16T22-58-47-840Z+Current: 2026-06-16T23:05:02.231Z++Structural similarity: 1 (near-identical)+Distance: 0++β similarity β₯ 0.95 β OK+```++## Implementation++[`scripts/drift-from-history.mjs`](../../scripts/drift-from-history.mjs)diff --git a/v3/@claude-flow/cli/src/commands/metaharness.ts b/v3/@claude-flow/cli/src/commands/metaharness.tsindex 8a8326aa8d..c14e29a619 100644--- a/v3/@claude-flow/cli/src/commands/metaharness.ts+++ b/v3/@claude-flow/cli/src/commands/metaharness.ts@@ -57,6 +57,8 @@ const SUBCOMMANDS: Record<string, string> = {'audit-list': 'audit-list.mjs',// iter 36 β ADR-152 Β§3.1 weighted similarity between two harness fingerprintssimilarity: 'similarity.mjs',+ // iter 53 β one-command drift detection (compose audit-list + oia-audit + audit-trend)+ 'drift-from-history': 'drift-from-history.mjs',mint: 'mint.mjs',};@@ -167,6 +169,7 @@ export const metaharnessCommand: Command = {output.writeln(' audit-list enumerate timestamped audit records');output.writeln(' audit-trend diff two audit records (drift detection)');output.writeln(' similarity ADR-152 β weighted similarity between two harness fingerprints');+ output.writeln(' drift-from-history iter 53 β diff current state against most recent audit (1-command drift)');output.writeln(' mint scaffold a custom harness (dry-run by default)');output.writeln('');output.writeln('Each subcommand accepts --format json|table and --help.');