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

MetaHarness hardening: repair the dependency contract + strict sequential promotion evidence (#2956)

rUv0b3cfb77d657
diff --git a/.github/workflows/metaharness-ci.yml b/.github/workflows/metaharness-ci.yml
index 1853fa1f7d..55490331bc 100644
--- a/.github/workflows/metaharness-ci.yml
+++ b/.github/workflows/metaharness-ci.yml
@@ -22,6 +22,8 @@ on:
- 'v3/@claude-flow/cli/src/ruvector/neural-router.ts'
- 'v3/@claude-flow/cli/src/ruvector/router-trajectory.ts'
- 'scripts/check-metaharness-compat.mjs'
+ - 'scripts/check-metaharness-pins.mjs'
+ - 'scripts/metaharness-clean-install-test.mjs'
- '.github/workflows/metaharness-ci.yml'
pull_request:
paths:
@@ -30,6 +32,8 @@ on:
- 'v3/@claude-flow/cli/src/ruvector/neural-router.ts'
- 'v3/@claude-flow/cli/src/ruvector/router-trajectory.ts'
- 'scripts/check-metaharness-compat.mjs'
+ - 'scripts/check-metaharness-pins.mjs'
+ - 'scripts/metaharness-clean-install-test.mjs'
- '.github/workflows/metaharness-ci.yml'
workflow_dispatch:
@@ -96,6 +100,27 @@ jobs:
path: /tmp/metaharness-genome.json
retention-days: 30
+ # MANDATORY dependency-contract gate: the declared installable pins must
+ # actually install from a pristine directory and export their advertised
+ # symbols. This is the failure the optional-peer era shipped: a clean ruflo
+ # install with zero MetaHarness packages on disk while every advertised
+ # surface assumed they might be present. No continue-on-error β€” a red run
+ # here means an advertised integration degrades on a fresh install.
+ clean-install:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: '20'
+
+ - name: Pin declaration contract (fails on undeclared / peer-only / stale)
+ run: node scripts/check-metaharness-pins.mjs
+
+ - name: Clean-directory install + advertised-symbol contract
+ run: node scripts/metaharness-clean-install-test.mjs
+
mcp-scan:
runs-on: ubuntu-latest
timeout-minutes: 5
diff --git a/.github/workflows/no-cli-optdep-bloat-2561.yml b/.github/workflows/no-cli-optdep-bloat-2561.yml
index 1cd1be1f5f..1e0c657e16 100644
--- a/.github/workflows/no-cli-optdep-bloat-2561.yml
+++ b/.github/workflows/no-cli-optdep-bloat-2561.yml
@@ -49,19 +49,30 @@ jobs:
// Budgets set by #2561 (610575ea5). Tightened intentionally so the
// in-process --version fast-path at bin/cli.js:101-117 is not
// starved by a cold npm install of dozens of native/wasm deps.
- const CLI_MAX = 8;
+ // Raised 8 β†’ 10 for the metaharness dependency-contract repair
+ // (PR #2956): @metaharness/{darwin,flywheel,radio} are each
+ // dependency-FREE pure-JS packages (1.8M + 348K + 180K unpacked,
+ // no lifecycle scripts, zero transitive deps β€” measured 753ms to
+ // cold-install all three into an empty dir on 2026-08-10). That
+ // profile is the opposite of the #2561 native/wasm trees.
+ const CLI_MAX = 10;
const RUFLO_MAX = 0;
// Specific packages proven to trigger the cold-npx timeout in
// #2561. Re-adding any of these to optionalDependencies re-opens
// the regression regardless of the count budget.
+ // NOTE: "@metaharness/darwin" was on this list from the pre-0.8
+ // era when it dragged a heavy dependency tree; [email protected] has
+ // ZERO dependencies and no install scripts (evidence above and in
+ // scripts/metaharness-clean-install-test.mjs, which CI runs on
+ // every PR touching these pins). Removed per the guard escape
+ // clause documented above; the rest of the list stands.
const FORBIDDEN = [
"@claude-flow/aidefence",
"@claude-flow/codex",
"@claude-flow/embeddings",
"@claude-flow/guidance",
"@claude-flow/plugin-gastown-bridge",
- "@metaharness/darwin",
"@metaharness/kernel",
"@metaharness/redblue",
"@metaharness/router",
diff --git a/.gitignore b/.gitignore
index feb7d8b7dd..e9bfe6f932 100644
--- a/.gitignore
+++ b/.gitignore
@@ -181,3 +181,7 @@ v3/@claude-flow/cli/plugins/
# Runtime proven-config adoption state (per-install, not source)
.claude/proven-config.json
.claude/.proven-config-version
+
+# Node V8 compile cache emitted by workspace builds (NODE_COMPILE_CACHE) β€”
+# machine-local artifact keyed by node version, never source
+node-compile-cache/
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
index 48d0c5a121..b65551e642 100755
--- a/plugins/ruflo-metaharness/scripts/smoke.sh
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -2282,9 +2282,11 @@ miss=""
# The check function exists, with ADR-150 anchor
grep -q "async function checkMetaharness" "$F" || miss="$miss no-check-function"
grep -q "ADR-150" "$F" || miss="$miss no-adr-anchor"
-# Registered in BOTH the allChecks array AND the componentMap
+# Registered in BOTH the allChecks array AND the componentMap. The
+# componentMap entry is now an ARRAY (upstream + declared-deps + integration
+# checks, PR #2956) β€” accept either the legacy bare form or the array form.
grep -q "checkMetaharness, // ADR-150" "$F" || miss="$miss not-in-allChecks"
-grep -q "'metaharness': checkMetaharness" "$F" || miss="$miss not-in-componentMap"
+grep -Eq "'metaharness': (checkMetaharness|\[checkMetaharness)" "$F" || miss="$miss not-in-componentMap"
# Help text mentions it
grep -q "metaharness)" "$F" || miss="$miss not-in-help-text"
# Graceful: never throws; returns warn (not fail) on missing
diff --git a/scripts/check-metaharness-pins.mjs b/scripts/check-metaharness-pins.mjs
index cb48d38091..cab6ef3a1d 100644
--- a/scripts/check-metaharness-pins.mjs
+++ b/scripts/check-metaharness-pins.mjs
@@ -9,10 +9,22 @@
// packages; this script diffs each declared range against npm `latest` and
// flags any pin whose range no longer admits the current release.
//
-// Checked pins (single source of truth = v3/@claude-flow/cli/package.json):
-// - metaharness (dependencies) β€” the umbrella / MCP subprocess CLI
-// - @metaharness/router (dependencies) β€” neural-router.ts dynamic import
-// - @metaharness/darwin (optionalDependencies) β€” Darwin evolve / GEPA subprocess
+// Checked pins (single source of truth = v3/@claude-flow/cli/package.json).
+// Each pin is looked up across dependencies, optionalDependencies, AND
+// peerDependencies β€” an earlier revision searched only the first two, so pins
+// moved to (optional) peerDependencies silently vanished from the watcher
+// ('undeclared' was not treated as drift). Both failure modes are now fatal:
+// - undeclared: the pin is missing from every dependency block
+// - peer-only for an installable pin: darwin / flywheel / radio are
+// advertised integration surfaces and MUST live in optionalDependencies so
+// a clean `npm install` actually materializes them; an optional PEER
+// dependency is never auto-installed, which is how a fresh ruflo install
+// shipped with zero MetaHarness packages on disk.
+// - metaharness β€” the umbrella / MCP subprocess CLI (npx path; peer ok)
+// - @metaharness/router β€” neural-router.ts dynamic import (peer ok β€” triple-gated)
+// - @metaharness/darwin β€” Darwin evolve / GEPA subprocess (must be installable)
+// - @metaharness/flywheel β€” receipt/gate interop (must be installable)
+// - @metaharness/radio β€” coordination-policy optimizer (must be installable)
// Plus a lock-step check: the MH_DARWIN_PIN constant in distill-oracle.ts (used
// for the Tier-1 oracle's `npx @metaharness/darwin@<pin>` calls) must satisfy
// the declared @metaharness/darwin range, so the two can't drift apart.
@@ -73,18 +85,37 @@ function npmLatest(pkg) {
return out.trim();
}
+/** Find a package's declared range across every dependency block, in priority order. */
+function declaredRange(pkg, name) {
+ for (const where of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+ const range = pkg[where]?.[name];
+ if (range) return { range, where };
+ }
+ return { range: undefined, where: null };
+}
+
async function main() {
const pkg = JSON.parse(readFileSync(CLI_PKG, 'utf-8'));
- const pins = [
- { name: 'metaharness', range: pkg.dependencies?.metaharness, where: 'dependencies' },
- { name: '@metaharness/router', range: pkg.dependencies?.['@metaharness/router'], where: 'dependencies' },
- { name: '@metaharness/darwin', range: pkg.optionalDependencies?.['@metaharness/darwin'], where: 'optionalDependencies' },
- { name: '@metaharness/flywheel', range: pkg.optionalDependencies?.['@metaharness/flywheel'], where: 'optionalDependencies' },
+ // installable: true β‡’ the package must be declared in `dependencies` or
+ // `optionalDependencies` (something npm actually installs); a peer-only
+ // declaration is a contract break, because optional peers never materialize
+ // on a clean install.
+ const WATCHED = [
+ { name: 'metaharness', installable: false },
+ { name: '@metaharness/router', installable: false },
+ { name: '@metaharness/darwin', installable: true },
+ { name: '@metaharness/flywheel', installable: true },
+ { name: '@metaharness/radio', installable: true },
];
+ const pins = WATCHED.map((w) => ({ ...w, ...declaredRange(pkg, w.name) }));
const rows = [];
for (const p of pins) {
- if (!p.range) { rows.push({ ...p, status: 'undeclared', latest: null, note: 'pin not found in package.json' }); continue; }
+ if (!p.range) { rows.push({ ...p, status: 'UNDECLARED', latest: null, note: 'pin not found in any dependency block β€” the watcher cannot protect an undeclared pin' }); continue; }
+ if (p.installable && p.where === 'peerDependencies') {
+ rows.push({ ...p, status: 'PEER-ONLY', latest: null, note: 'declared only as a peer β€” never installed by a clean `npm install`; move to optionalDependencies' });
+ continue;
+ }
if (ARGS.offline) { rows.push({ ...p, status: 'skipped', latest: null, note: 'offline mode' }); continue; }
let latest;
try { latest = npmLatest(p.name); }
@@ -97,31 +128,34 @@ async function main() {
let constRow = null;
try {
const m = readFileSync(DISTILL, 'utf-8').match(/MH_DARWIN_PIN\s*=\s*['"]([^'"]+)['"]/);
- const declared = pkg.optionalDependencies?.['@metaharness/darwin'];
+ const declared = declaredRange(pkg, '@metaharness/darwin').range;
if (m && declared) {
const inRange = satisfies(declared, m[1]);
constRow = { name: 'MH_DARWIN_PIN (distill-oracle.ts)', pin: m[1], declared, status: inRange === false ? 'OUT-OF-RANGE' : 'in-range' };
}
} catch { /* non-fatal */ }
- const stale = rows.filter((r) => r.status === 'STALE');
+ const stale = rows.filter((r) => r.status === 'STALE' || r.status === 'UNDECLARED' || r.status === 'PEER-ONLY');
const constBad = constRow && constRow.status === 'OUT-OF-RANGE';
const apiErrors = [];
if (ARGS.requireInstalled) {
const cliDir = dirname(CLI_PKG);
- try {
- const darwin = await import(pathToFileURL(join(cliDir, 'node_modules/@metaharness/darwin/dist/index.js')).href);
- if (typeof darwin.evolve !== 'function') apiErrors.push('@metaharness/darwin must export evolve');
- } catch (error) {
- apiErrors.push(`@metaharness/darwin import failed: ${error.message}`);
- }
- try {
- const flywheel = await import(pathToFileURL(join(cliDir, 'node_modules/@metaharness/flywheel/dist/index.js')).href);
- for (const symbol of ['runFlywheelGenerations', 'meetsPromotionRule', 'makeSigner', 'verifyReplayBundle']) {
- if (typeof flywheel[symbol] !== 'function') apiErrors.push(`@metaharness/flywheel must export ${symbol}`);
+ // Advertised symbol contract per package β€” verified against the real
+ // published artifacts (darwin 0.8.3 / flywheel 0.1.10 / radio 0.1.0).
+ const API_CONTRACT = {
+ '@metaharness/darwin': ['evolve', 'RefineMutator', 'summarizeFailedTraces'],
+ '@metaharness/flywheel': ['runFlywheelGenerations', 'meetsPromotionRule', 'makeSigner', 'verifyReplayBundle', 'sequentialEvidence', 'withSequentialEvidence'],
+ '@metaharness/radio': ['RadioBus', 'runProtocol', 'runSim'],
+ };
+ for (const [pkgName, symbols] of Object.entries(API_CONTRACT)) {
+ try {
+ const mod = await import(pathToFileURL(join(cliDir, 'node_modules', pkgName, 'dist/index.js')).href);
+ for (const symbol of symbols) {
+ if (typeof mod[symbol] !== 'function') apiErrors.push(`${pkgName} must export ${symbol}`);
+ }
+ } catch (error) {
+ apiErrors.push(`${pkgName} import failed: ${error.message}`);
}
- } catch (error) {
- apiErrors.push(`@metaharness/flywheel import failed: ${error.message}`);
}
}
const drift = stale.length > 0 || constBad || apiErrors.length > 0;
@@ -138,17 +172,18 @@ async function main() {
console.log(JSON.stringify(payload, null, 2));
} else {
console.log('# check-metaharness-pins\n');
- console.log('| Package | Declared | npm latest | Status |');
- console.log('|---|---|---|---|');
- for (const r of rows) console.log(`| ${r.name} | ${r.range ?? 'β€”'} | ${r.latest ?? 'β€”'} | ${r.status} |`);
- if (constRow) console.log(`| ${constRow.name} | =${constRow.pin} (vs ${constRow.declared}) | β€” | ${constRow.status} |`);
+ console.log('| Package | Declared | Where | npm latest | Status |');
+ console.log('|---|---|---|---|---|');
+ for (const r of rows) console.log(`| ${r.name} | ${r.range ?? 'β€”'} | ${r.where ?? 'β€”'} | ${r.latest ?? 'β€”'} | ${r.status} |`);
+ if (constRow) console.log(`| ${constRow.name} | =${constRow.pin} (vs ${constRow.declared}) | β€” | β€” | ${constRow.status} |`);
if (ARGS.requireInstalled) console.log(`\nInstalled API check: ${apiErrors.length ? `FAIL β€” ${apiErrors.join('; ')}` : 'PASS'}`);
console.log('');
if (drift) {
- console.log('⚠ **Pin drift detected.** One or more metaharness pins no longer admit the current npm release.');
- console.log('Bump the range in v3/@claude-flow/cli/package.json (and MH_DARWIN_PIN if darwin moved), then re-run.');
+ console.log('⚠ **Pin drift detected.** A metaharness pin is stale, undeclared, or declared peer-only.');
+ console.log('Fix the declaration in v3/@claude-flow/cli/package.json (installable pins belong in optionalDependencies;');
+ console.log('bump MH_DARWIN_PIN if darwin moved), then re-run.');
} else {
- console.log('βœ“ All metaharness pins admit the current npm `latest`.');
+ console.log('βœ“ All metaharness pins are declared installably and admit the current npm `latest`.');
}
}
process.exit(drift ? 1 : 0);
diff --git a/scripts/metaharness-clean-install-test.mjs b/scripts/metaharness-clean-install-test.mjs
new file mode 100644
index 0000000000..abc63ebdaf
--- /dev/null
+++ b/scripts/metaharness-clean-install-test.mjs
@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// metaharness-clean-install-test β€” the dependency-contract acceptance gate.
+//
+// WHY: the MetaHarness packages were once declared only as OPTIONAL PEER
+// dependencies, which npm never auto-installs β€” so a clean `npm install` of
+// ruflo shipped with zero MetaHarness packages on disk while every advertised
+// surface (`ruflo metaharness …`) assumed they might be there. The pin watcher
+// missed it because it never looked at peerDependencies. This script closes
+// the loop end-to-end: it installs the EXACT ranges v3/@claude-flow/cli
+// declares into a pristine temp project (no repo node_modules in scope), then
+// imports each package and asserts the advertised symbol contract.
+//
+// USAGE
+// node scripts/metaharness-clean-install-test.mjs # human output
+// node scripts/metaharness-clean-install-test.mjs --format json
+//
+// EXIT CODES
+// 0 every declared installable pin installs cleanly and exports its contract
+// 1 a pin is missing from optionalDependencies, fails to install, or is
+// missing an advertised export
+// 2 unexpected error (temp-dir creation, package.json unreadable, …)
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_PKG = join(HERE, '..', 'v3', '@claude-flow', 'cli', 'package.json');
+const FORMAT = process.argv.includes('--format') && process.argv[process.argv.indexOf('--format') + 1] === 'json' ? 'json' : 'table';
+
+// Advertised symbol contract per package β€” verified against the real published
+// artifacts (darwin 0.8.3 / flywheel 0.1.10 / radio 0.1.0). Keep in sync with
+// the --require-installed check in check-metaharness-pins.mjs.
+const API_CONTRACT = {
+ '@metaharness/darwin': ['evolve', 'RefineMutator', 'summarizeFailedTraces'],
+ '@metaharness/flywheel': ['runFlywheelGenerations', 'meetsPromotionRule', 'makeSigner', 'verifyReplayBundle', 'sequentialEvidence', 'withSequentialEvidence'],
+ '@metaharness/radio': ['RadioBus', 'runProtocol', 'runSim'],
+};
+
+async function main() {
+ const pkg = JSON.parse(readFileSync(CLI_PKG, 'utf-8'));
+ const results = [];
+ let failed = false;
+
+ const specs = [];
+ for (const name of Object.keys(API_CONTRACT)) {
+ const range = pkg.optionalDependencies?.[name];
+ if (!range) {
+ results.push({ name, status: 'FAIL', note: 'not declared in optionalDependencies β€” a clean install never materializes it' });
+ failed = true;
+ continue;
+ }
+ specs.push({ name, range });
+ }
+
+ let workDir = null;
+ if (specs.length) {
+ workDir = mkdtempSync(join(tmpdir(), 'ruflo-mh-clean-install-'));
+ writeFileSync(join(workDir, 'package.json'), JSON.stringify({ name: 'mh-clean-install-probe', private: true, type: 'module' }, null, 2));
+ try {
+ execFileSync('npm', [
+ 'install', '--no-audit', '--no-fund', '--no-save',
+ ...specs.map((s) => `${s.name}@${s.range}`),
+ ], { cwd: workDir, stdio: 'pipe', timeout: 300_000 });
+ } catch (error) {
+ for (const s of specs) results.push({ name: s.name, range: s.range, status: 'FAIL', note: `npm install failed: ${String(error.message).slice(0, 200)}` });
+ failed = true;
+ specs.length = 0;
+ }
+ }
+
+ for (const s of specs) {
+ try {
+ const mod = await import(pathToFileURL(join(workDir, 'node_modules', s.name, 'dist', 'index.js')).href);
+ const missing = API_CONTRACT[s.name].filter((sym) => typeof mod[sym] !== 'function');
+ if (missing.length) {
+ results.push({ name: s.name, range: s.range, status: 'FAIL', note: `missing exports: ${missing.join(', ')}` });
+ failed = true;
+ } else {
+ results.push({ name: s.name, range: s.range, status: 'PASS', note: `${API_CONTRACT[s.name].length} advertised exports present` });
+ }
+ } catch (error) {
+ results.push({ name: s.name, range: s.range, status: 'FAIL', note: `import failed: ${String(error.message).slice(0, 200)}` });
+ failed = true;
+ }
+ }
+
+ if (workDir) { try { rmSync(workDir, { recursive: true, force: true }); } catch { /* best-effort */ } }
+
+ if (FORMAT === 'json') {
+ console.log(JSON.stringify({ generatedAt: new Date().toISOString(), pass: !failed, results }, null, 2));
+ } else {
+ console.log('# metaharness-clean-install-test\n');
+ console.log('| Package | Declared range | Status | Note |');
+ console.log('|---|---|---|---|');
+ for (const r of results) console.log(`| ${r.name} | ${r.range ?? 'β€”'} | ${r.status} | ${r.note} |`);
+ console.log('');
+ console.log(failed
+ ? 'βœ— Clean-install contract BROKEN β€” an advertised MetaHarness surface would degrade on a fresh install.'
+ : 'βœ“ Every advertised MetaHarness package installs from a clean directory and exports its contract.');
+ }
+ process.exit(failed ? 1 : 0);
+}
+
+main().catch((e) => { console.error('metaharness-clean-install-test crashed:', e?.message || e); process.exit(2); });
diff --git a/v3/@claude-flow/cli/__tests__/evolve-proof.test.ts b/v3/@claude-flow/cli/__tests__/evolve-proof.test.ts
index 3f4b2cf81b..bb4cfe668e 100644
--- a/v3/@claude-flow/cli/__tests__/evolve-proof.test.ts
+++ b/v3/@claude-flow/cli/__tests__/evolve-proof.test.ts
@@ -217,6 +217,65 @@ describe('mutationEffectiveness β€” evidence-grounded meta-learning', () => {
});
});
+describe('accept/v2+seq β€” sequential-evidence conjunct (ADR-381 Β§3)', () => {
+ const baseline = { alpha: 0.5, subjectWeight: 2, mmrLambda: 0.7, bodyWeight: 1, typePenaltyFactor: 1 };
+ const candidate = { alpha: 0.3, subjectWeight: 1, mmrLambda: 0.5, bodyWeight: 1.5, typePenaltyFactor: 0.5 };
+ // 10 all-win pairs: clears test 1 (1.5^10 β‰ˆ 57.7 β‰₯ 32.9) but not test 2 (β‰ˆ131.6).
+ const strongHoldout = Array.from({ length: 10 }, (_, i) => ({ taskId: `s${i}`, baselineScore: 0.5, candidateScore: 0.6 + i / 100 }));
+ // 5 all-win pairs: bootstrap-significant but sequentially insufficient at test 1.
+ const weakHoldout = Array.from({ length: 5 }, (_, i) => ({ taskId: `w${i}`, baselineScore: 0.5, candidateScore: 0.62 + i / 100 }));
+
+ it('promotes under v2 only when the sequential term also holds, and pins the v2 version', () => {
+ const b = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 0, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 1 } });
+ expect(b.meetsPromotionRule.version).toBe('accept/v2+seq');
+ expect(b.sequentialEvidence).toMatchObject({ testIndex: 1, significant: true, informativePairs: 10 });
+ expect(b.decisionReceipt.promoted).toBe(true);
+ });
+
+ it('rejects a bootstrap-significant candidate whose sequential evidence is insufficient β€” cause "sequential"', () => {
+ const b = runRealEvolveRound({ baseline, candidate, holdout: weakHoldout, generation: 0, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 1 } });
+ expect(b.decisionReceipt.significant).toBe(true); // v1 term holds
+ expect(b.sequentialEvidence?.significant).toBe(false); // v2 term refuses
+ expect(b.decisionReceipt.promoted).toBe(false);
+ expect(b.regression?.failureCause).toBe('sequential');
+ expect(b.decisionReceipt.reason).toMatch(/sequential_evidence/);
+ });
+
+ it('the same evidence fails at a later stream position (alpha allocation bites)', () => {
+ const early = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 0, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 1 } });
+ const late = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 5, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 2 } });
+ expect(early.decisionReceipt.promoted).toBe(true);
+ expect(late.decisionReceipt.promoted).toBe(false);
+ });
+
+ it('v2 bundles replay independently, and a tampered sequential record is detected', () => {
+ const b = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 0, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 1 } });
+ expect(verifyReceiptBundle(b).valid).toBe(true);
+ expect(verifyReceiptBundle(b).explanation).toMatch(/accept\/v2\+seq/);
+
+ const tampered = structuredClone(b);
+ tampered.sequentialEvidence!.eValue = 999;
+ const v = verifyReceiptBundle(tampered);
+ expect(v.valid).toBe(false);
+ expect(v.mismatches.join(' ')).toMatch(/sequential-evidence verdict does not recompute/);
+
+ // Claiming an easier stream position than recorded is also caught: the
+ // verdict was recorded at index 2; rewriting it to index 1 changes the
+ // threshold, so significance no longer recomputes.
+ const rejected = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 5, parent: null, now: 1, corpus: 'x', sequential: { testIndex: 2 } });
+ const indexShopped = structuredClone(rejected);
+ indexShopped.sequentialEvidence!.testIndex = 1;
+ expect(verifyReceiptBundle(indexShopped).valid).toBe(false);
+ });
+
+ it('v1 bundles (no sequential input) keep v1 semantics and still verify', () => {
+ const b = runRealEvolveRound({ baseline, candidate, holdout: strongHoldout, generation: 0, parent: null, now: 1, corpus: 'x' });
+ expect(b.meetsPromotionRule.version).toBe(PROMOTION_RULE_VERSION);
+ expect(b.sequentialEvidence).toBeUndefined();
+ expect(verifyReceiptBundle(b).valid).toBe(true);
+ });
+});
+
describe('detectPlateau β€” rigorous, not intuitive', () => {
it('insufficient-data below the window', () => {
expect(detectPlateau(chainOf(3), { window: 20 }).status).toBe('insufficient-data');
diff --git a/v3/@claude-flow/cli/__tests__/flywheel-receipt.test.ts b/v3/@claude-flow/cli/__tests__/flywheel-receipt.test.ts
index 688918bdf3..1dbc40ca22 100644
--- a/v3/@claude-flow/cli/__tests__/flywheel-receipt.test.ts
+++ b/v3/@claude-flow/cli/__tests__/flywheel-receipt.test.ts
@@ -82,6 +82,46 @@ describe('flywheel receipt protocol', () => {
);
});
+ it('carries task-level paired outcomes and refuses ones that cannot reproduce their aggregate', () => {
+ const key = keys();
+ const heldOutDeltas = [0.1, 0.12, 0.2, 0.08];
+ const receipt = createFlywheelReceipt({
+ baselineRef: policyCandidateId({ alpha: 0.5 }),
+ candidatePolicy: { alpha: 0.3 },
+ safetyEnvelopeRef: 'sha256:safety',
+ corpusVersion: 'corpus-v1',
+ corpusHash: 'sha256:corpus',
+ baselineScore: 0.5,
+ candidateScore: 0.65,
+ heldOutDeltas,
+ pairedOutcomes: heldOutDeltas.map((delta, i) => ({
+ taskId: `t${i}`,
+ baselineScore: 0.5,
+ candidateScore: 0.5 + delta,
+ })),
+ frozenAnchorRegression: 0,
+ gates: { heldOut: true },
+ bootstrapIterations: 500,
+ ...key,
+ });
+ expect(receipt.payload.pairedOutcomes).toHaveLength(4);
+ expect(verifyFlywheelReceipt(receipt, new Set([key.publicKeyPem])).valid).toBe(true);
+
+ // Tampering with a per-task score breaks BOTH the content ID and the
+ // delta-reproducibility check β€” the paired rows are evidence, not decoration.
+ const tampered = structuredClone(receipt);
+ tampered.payload.pairedOutcomes![0].candidateScore = '0.9';
+ const verification = verifyFlywheelReceipt(tampered, new Set([key.publicKeyPem]));
+ expect(verification.valid).toBe(false);
+ expect(verification.errors.join(' ')).toMatch(/paired outcomes inconsistent/);
+ });
+
+ it('keeps receipts without paired outcomes verifiable (backward compatibility)', () => {
+ const { key, receipt } = acceptedReceipt();
+ expect(receipt.payload.pairedOutcomes).toBeUndefined();
+ expect(verifyFlywheelReceipt(receipt, new Set([key.publicKeyPem])).valid).toBe(true);
+ });
+
it('rejects small relative lifts even when every held-out delta is positive', () => {
const { privateKeyPem, publicKeyPem } = keys();
const receipt = createFlywheelReceipt({
diff --git a/v3/@claude-flow/cli/__tests__/flywheel-sequential-evidence.test.ts b/v3/@claude-flow/cli/__tests__/flywheel-sequential-evidence.test.ts
new file mode 100644
index 0000000000..d67ece61a8
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/flywheel-sequential-evidence.test.ts
@@ -0,0 +1,135 @@
+import { describe, expect, it } from 'vitest';
+import {
+ DEFAULT_ALPHA_TOTAL,
+ DEFAULT_LAMBDA,
+ alphaForTest,
+ checkPairedOutcomesConsistency,
+ minInformativePairsToClear,
+ remainingAlphaBudget,
+ sequentialEvidenceVerdict,
+ type PairedTaskOutcome,
+} from '../src/services/flywheel-sequential-evidence.js';
+
+const win = (i: number): PairedTaskOutcome => ({ taskId: `t${i}`, baselineScore: 0.5, candidateScore: 0.7 });
+const loss = (i: number): PairedTaskOutcome => ({ taskId: `t${i}`, baselineScore: 0.7, candidateScore: 0.5 });
+const tie = (i: number): PairedTaskOutcome => ({ taskId: `t${i}`, baselineScore: 0.6, candidateScore: 0.6 });
+
+describe('alpha allocation across the candidate stream', () => {
+ it('sums to at most alphaTotal over arbitrarily many tests', () => {
+ let spent = 0;
+ for (let k = 1; k <= 10_000; k++) spent += alphaForTest(k, 0.05);
+ expect(spent).toBeLessThanOrEqual(0.05);
+ // and converges to (nearly all of) the budget rather than wasting it
+ expect(spent).toBeGreaterThan(0.0499);
+ });
+
+ it('rejects invalid indices and budgets', () => {
+ expect(() => alphaForTest(0)).toThrow(RangeError);
+ expect(() => alphaForTest(1.5)).toThrow(RangeError);
+ expect(() => alphaForTest(1, 1)).toThrow(RangeError);
+ });
+
+ it('minInformativePairsToClear is exactly the all-win count that clears the threshold', () => {
+ for (const k of [1, 2, 5, 10]) {
+ const n = minInformativePairsToClear(k);
+ // n all-win pairs clear; n-1 do not.
+ expect(Math.pow(1 + DEFAULT_LAMBDA, n)).toBeGreaterThanOrEqual(1 / alphaForTest(k));
+ expect(Math.pow(1 + DEFAULT_LAMBDA, n - 1)).toBeLessThan(1 / alphaForTest(k));
+ }
+ // Concrete anchor: test 1 needs 9 net wins at lambda 0.5.
+ expect(minInformativePairsToClear(1)).toBe(9);
+ });
+
+ it('remainingAlphaBudget decreases monotonically and never goes negative', () => {
+ let prev = DEFAULT_ALPHA_TOTAL;
+ for (let k = 0; k <= 50; k += 5) {
+ const left = remainingAlphaBudget(k);
+ expect(left).toBeLessThanOrEqual(prev + 1e-12);
+ expect(left).toBeGreaterThanOrEqual(0);
+ prev = left;
+ }
+ expect(remainingAlphaBudget(0)).toBe(DEFAULT_ALPHA_TOTAL);
+ });
+});
+
+describe('sequential evidence e-process', () => {
+ it('carries no information in concordant pairs', () => {
+ const verdict = sequentialEvidenceVerdict([tie(0), tie(1), tie(2)], 1);
+ expect(verdict.eValue).toBe(1);
+ expect(verdict.informativePairs).toBe(0);
+ expect(verdict.significant).toBe(false);
+ });
+
+ it('reaches significance on a strong candidate at test 1 but not at test 2', () => {
+ const outcomes = Array.from({ length: 10 }, (_, i) => win(i)); // e = 1.5^10 β‰ˆ 57.7
+ const first = sequentialEvidenceVerdict(outcomes, 1);
+ expect(first.significant).toBe(true);
+ expect(first.threshold).toBeCloseTo(1 / alphaForTest(1), 6);
+ const second = sequentialEvidenceVerdict(outcomes, 2); // threshold β‰ˆ 131.6
+ expect(second.significant).toBe(false);
+ });
+
+ it('is order-invariant and symmetric between wins and losses', () => {
+ const mixed = [win(0), loss(1), win(2), win(3)];
+ const shuffled = [win(3), win(0), win(2), loss(1)];
+ expect(sequentialEvidenceVerdict(mixed, 1).eValue).toBeCloseTo(sequentialEvidenceVerdict(shuffled, 1).eValue, 12);
+ // one win and one loss cancel: (1.5)(0.5) = 0.75 < 1
+ expect(sequentialEvidenceVerdict([win(0), loss(1)], 1).eValue).toBeCloseTo(0.75, 12);
+ });
+});
+
+describe('paired-outcome consistency', () => {
+ const outcomes: PairedTaskOutcome[] = [
+ { taskId: 'a', baselineScore: 0.5, candidateScore: 0.6 },
+ { taskId: 'b', baselineScore: 0.4, candidateScore: 0.55 },
+ ];
+
+ it('accepts outcomes that reproduce their aggregate deltas', () => {
+ expect(checkPairedOutcomesConsistency(outcomes, [0.1, 0.15]).ok).toBe(true);
+ });
+
+ it('refuses length mismatch, duplicate ids, and irreproducible deltas', () => {
+ expect(checkPairedOutcomesConsistency(outcomes, [0.1]).ok).toBe(false);
+ expect(checkPairedOutcomesConsistency([outcomes[0], { ...outcomes[1], taskId: 'a' }], [0.1, 0.15]).ok).toBe(false);
+ expect(checkPairedOutcomesConsistency(outcomes, [0.1, 0.2]).ok).toBe(false);
+ expect(checkPairedOutcomesConsistency([], []).ok).toBe(false);
+ });
+});
+
+describe('acceptance: family-wise false promotion under the null', () => {
+ it('stays at or below the 5% budget across 1,000 null-improvement streams', () => {
+ // Each stream simulates an ADAPTIVE flywheel run under the global null
+ // (no candidate is truly better): 20 candidates per stream, 40 paired
+ // tasks per candidate, every pair discordant with P(candidate wins) = 1/2
+ // β€” the worst case for the e-process, since concordant pairs carry no
+ // signal. A false promotion is ANY candidate in the stream clearing its
+ // allocated threshold. The theoretical bound is
+ // sum_k alpha_k = alphaTotal = 5%.
+ let seed = 0x5eed5eed >>> 0;
+ const rnd = () => {
+ seed = (1664525 * seed + 1013904223) >>> 0;
+ return seed / 4294967296;
+ };
+
+ const STREAMS = 1_000;
+ const CANDIDATES_PER_STREAM = 20;
+ const PAIRS_PER_CANDIDATE = 40;
+ let streamsWithFalsePromotion = 0;
+
+ for (let s = 0; s < STREAMS; s++) {
+ let promotedFalsely = false;
+ for (let k = 1; k <= CANDIDATES_PER_STREAM; k++) {
+ const outcomes: PairedTaskOutcome[] = Array.from({ length: PAIRS_PER_CANDIDATE }, (_, i) =>
+ rnd() < 0.5 ? win(i) : loss(i));
+ if (sequentialEvidenceVerdict(outcomes, k).significant) {
+ promotedFalsely = true;
+ break;
+ }
+ }
+ if (promotedFalsely) streamsWithFalsePromotion++;
+ }
+
+ const rate = streamsWithFalsePromotion / STREAMS;
+ expect(rate).toBeLessThanOrEqual(DEFAULT_ALPHA_TOTAL);
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/flywheel-transaction.test.ts b/v3/@claude-flow/cli/__tests__/flywheel-transaction.test.ts
index 49d92fa5a0..e84333bad9 100644
--- a/v3/@claude-flow/cli/__tests__/flywheel-transaction.test.ts
+++ b/v3/@claude-flow/cli/__tests__/flywheel-transaction.test.ts
@@ -12,6 +12,7 @@ import {
readFlywheelTransactionState,
recoverFlywheelMaterialization,
registerFlywheelReceipt,
+ resetSequentialEvidence,
verifyFlywheelLedger,
} from '../src/services/flywheel-transaction.js';
@@ -23,6 +24,15 @@ function keyPair() {
};
}
+// 10 all-candidate-win paired tasks: enough sequential evidence to clear the
+// e-process at test 1 (e = 1.5^10 β‰ˆ 57.7 β‰₯ 1/alpha_1 β‰ˆ 32.9).
+const HELD_DELTAS = [0.1, 0.12, 0.2, 0.08, 0.15, 0.11, 0.09, 0.14, 0.13, 0.1];
+const PAIRED = HELD_DELTAS.map((delta, i) => ({
+ taskId: `t${i}`,
+ baselineScore: 0.5,
+ candidateScore: 0.5 + delta,
+}));
+
function makeReceipt(
key: ReturnType<typeof keyPair>,
over: Partial<Parameters<typeof createFlywheelReceipt>[0]> = {},
@@ -35,7 +45,8 @@ function makeReceipt(
corpusHash: 'sha256:corpus-v1',
baselineScore: 0.5,
candidateScore: 0.65,
- heldOutDeltas: [0.1, 0.12, 0.2, 0.08, 0.15, 0.11],
+ heldOutDeltas: HELD_DELTAS,
+ pairedOutcomes: PAIRED,
frozenAnchorRegression: 0,
gates: { heldOut: true, redblue: true, replay: true },
termVerification: ['heldOut', 'redblue', 'replay'].map((term) => ({
@@ -127,6 +138,206 @@ describe('flywheel promotion transaction', () => {
expect(readFlywheelTransactionState(root).commits).toHaveLength(0);
});
+ it('refuses aggregate-only receipts by default and honors the explicit escape hatch', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-aggregate-'));
+ const key = keyPair();
+ const receipt = makeReceipt(key, { pairedOutcomes: undefined });
+ await registerFlywheelReceipt(root, receipt);
+ const common = {
+ confirm: true,
+ now: 1_700_000_000_100,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ };
+
+ const refused = await promoteFlywheelCandidate(root, receipt.payload.receiptId, common);
+ expect(refused.success).toBe(false);
+ expect(refused.reason).toMatch(/aggregate-only evidence/);
+ expect(readFlywheelTransactionState(root).commits).toHaveLength(0);
+
+ const allowed = await promoteFlywheelCandidate(root, receipt.payload.receiptId, {
+ ...common,
+ requirePairedEvidence: false,
+ });
+ expect(allowed.success).toBe(true);
+ });
+
+ it('refuses a size-inviable receipt WITHOUT spending alpha (ancillary refusal)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-size-inviable-'));
+ const key = keyPair();
+ // 5 pairs < 9 required at test 1: refused on sample size alone β€” no
+ // evidence looked at, no alpha index allocated.
+ const tinyDeltas = [0.1, 0.12, 0.2, 0.08, 0.15];
+ const receipt = makeReceipt(key, {
+ heldOutDeltas: tinyDeltas,
+ pairedOutcomes: tinyDeltas.map((delta, i) => ({ taskId: `t${i}`, baselineScore: 0.5, candidateScore: 0.5 + delta })),
+ });
+ await registerFlywheelReceipt(root, receipt);
+ const refused = await promoteFlywheelCandidate(root, receipt.payload.receiptId, {
+ confirm: true,
+ now: 1_700_000_000_100,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ });
+ expect(refused.success).toBe(false);
+ expect(refused.reason).toMatch(/cannot clear sequential evidence at test 1.*no alpha spent/);
+ expect(readFlywheelTransactionState(root).sequentialTests ?? {}).toEqual({});
+ });
+
+ it('refuses weak paired evidence at the allocated alpha and records the spend once', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-weak-evidence-'));
+ const key = keyPair();
+ // 10 pairs (size-viable at test 1) but 9 wins + 1 loss: the receipt's own
+ // gate accepts (bootstrap still significant) while e = 1.5^9 Β· 0.5 β‰ˆ 19.2
+ // < 32.9 = 1/alpha_1 β€” the sequential gate must refuse AND record the
+ // spend: this evidence was genuinely looked at.
+ const weakDeltas = [0.1, 0.12, 0.2, 0.08, 0.15, 0.11, 0.09, 0.14, 0.13, -0.1];
+ const receipt = makeReceipt(key, {
+ heldOutDeltas: weakDeltas,
+ pairedOutcomes: weakDeltas.map((delta, i) => ({
+ taskId: `w${i}`,
+ baselineScore: 0.5,
+ candidateScore: 0.5 + delta,
+ })),
+ });
+ expect(receipt.payload.decision).toBe('accepted');
+ await registerFlywheelReceipt(root, receipt);
+ const common = {
+ confirm: true,
+ now: 1_700_000_000_100,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ };
+
+ const refused = await promoteFlywheelCandidate(root, receipt.payload.receiptId, common);
+ expect(refused.success).toBe(false);
+ expect(refused.reason).toMatch(/insufficient sequential evidence/);
+
+ // Alpha was spent by looking: the allocation is persisted, and a retry
+ // reuses the same test index instead of shopping for a fresh one.
+ let state = readFlywheelTransactionState(root);
+ expect(state.sequentialTests?.[receipt.payload.receiptId]).toBe(1);
+ await promoteFlywheelCandidate(root, receipt.payload.receiptId, common);
+ state = readFlywheelTransactionState(root);
+ expect(state.sequentialTests?.[receipt.payload.receiptId]).toBe(1);
+ expect(Object.keys(state.sequentialTests ?? {})).toHaveLength(1);
+ expect(state.commits).toHaveLength(0);
+ });
+
+ it('allocates successive test indices to distinct receipts (alpha allocation across the stream)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-alpha-stream-'));
+ const key = keyPair();
+ const first = makeReceipt(key);
+ await registerFlywheelReceipt(root, first);
+ const common = {
+ confirm: true,
+ now: 1_700_000_000_100,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ };
+ const promoted = await promoteFlywheelCandidate(root, first.payload.receiptId, common);
+ expect(promoted.success).toBe(true);
+
+ // Second candidate in the stream: judged at test 2's stricter threshold
+ // (1/alpha_2 β‰ˆ 131.6). 14 pairs keeps it size-viable (min 13 at test 2)
+ // but 12 wins + 2 losses give e = 1.5^12 Β· 0.5^2 β‰ˆ 32.4 < 131.6 β€” an
+ // e-process refusal that spends index 2.
+ const state = readFlywheelTransactionState(root);
+ const secondDeltas = [0.1, 0.12, 0.2, 0.08, 0.15, 0.11, 0.09, 0.14, 0.13, 0.1, 0.12, 0.11, -0.05, -0.06];
+ const second = makeReceipt(key, {
+ evaluationRunId: '01900000-0000-7000-8000-000000000003',
+ baselineRef: state.activeChampionRef!,
+ expectedLedgerHead: state.ledgerHead,
+ candidatePolicy: { alpha: 0.25 },
+ heldOutDeltas: secondDeltas,
+ pairedOutcomes: secondDeltas.map((delta, i) => ({ taskId: `s${i}`, baselineScore: 0.5, candidateScore: 0.5 + delta })),
+ });
+ await registerFlywheelReceipt(root, second);
+ const refused = await promoteFlywheelCandidate(root, second.payload.receiptId, common);
+ expect(refused.success).toBe(false);
+ expect(refused.reason).toMatch(/insufficient sequential evidence/);
+ const after = readFlywheelTransactionState(root);
+ expect(after.sequentialTests?.[first.payload.receiptId]).toBe(1);
+ expect(after.sequentialTests?.[second.payload.receiptId]).toBe(2);
+ });
+
+ it('evidence reset starts a new epoch: archives spend, expires outstanding receipts, and re-opens the budget (ADR-381)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-evidence-reset-'));
+ const key = keyPair();
+ const common = {
+ confirm: true,
+ now: 1_700_000_000_100,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ };
+
+ // Spend alpha with a weak receipt (size-viable, e-process refused at
+ // test 1), leaving it 'evaluated'.
+ const weakDeltas = [0.1, 0.12, 0.2, 0.08, 0.15, 0.11, 0.09, 0.14, 0.13, -0.1];
+ const weak = makeReceipt(key, {
+ heldOutDeltas: weakDeltas,
+ pairedOutcomes: weakDeltas.map((delta, i) => ({ taskId: `w${i}`, baselineScore: 0.5, candidateScore: 0.5 + delta })),
+ });
+ await registerFlywheelReceipt(root, weak);
+ expect((await promoteFlywheelCandidate(root, weak.payload.receiptId, common)).reason).toMatch(/insufficient sequential evidence/);
+
+ // Governance requirements: confirm + non-empty reason.
+ expect((await resetSequentialEvidence(root, { confirm: false, reason: 'x' })).success).toBe(false);
+ expect((await resetSequentialEvidence(root, { confirm: true, reason: ' ' })).success).toBe(false);
+
+ const reset = await resetSequentialEvidence(root, { confirm: true, reason: 'baseline rollback β€” fresh campaign', now: 1_700_000_000_200 });
+ expect(reset).toMatchObject({ success: true, closedEpoch: 0, newEpoch: 1, testsArchived: 1, receiptsExpired: 1 });
+
+ const state = readFlywheelTransactionState(root);
+ expect(state.evidenceEpoch).toBe(1);
+ expect(state.sequentialTests).toEqual({});
+ expect(state.sequentialResets).toHaveLength(1);
+ expect(state.sequentialResets![0]).toMatchObject({
+ epoch: 0,
+ reason: 'baseline rollback β€” fresh campaign',
+ testsSpent: { [weak.payload.receiptId]: 1 },
+ expiredReceipts: [weak.payload.receiptId],
+ });
+
+ // The expired receipt cannot be promoted in the new epoch β€” fresh data only.
+ expect((await promoteFlywheelCandidate(root, weak.payload.receiptId, common)).reason).toMatch(/receipt state is expired/);
+
+ // A receipt evaluated AFTER the reset promotes from test 1 of the new epoch.
+ // `now` here is the receipt's own evidence timestamp (payload.issuedAt),
+ // not just its registration time β€” it must postdate the reset's
+ // evidenceEpochStartedAt (1_700_000_000_200) for the epoch boundary check
+ // to accept it as belonging to the new epoch.
+ const fresh = makeReceipt(key, { evaluationRunId: '01900000-0000-7000-8000-000000000009', now: 1_700_000_000_250 });
+ await registerFlywheelReceipt(root, fresh, 1_700_000_000_300);
+ const promoted = await promoteFlywheelCandidate(root, fresh.payload.receiptId, common);
+ expect(promoted.success).toBe(true);
+ expect(readFlywheelTransactionState(root).sequentialTests?.[fresh.payload.receiptId]).toBe(1);
+ });
+
+ it('refuses to promote a receipt whose evidence predates the current evidence epoch, even if registered after the reset (ADR-381 Β§2 index-shopping guard)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'flywheel-epoch-boundary-'));
+ const key = keyPair();
+ const common = {
+ confirm: true,
+ now: 1_700_000_000_400,
+ trustedPublicKeys: new Set([key.publicKeyPem]),
+ applyFn: apply,
+ };
+ await resetSequentialEvidence(root, { confirm: true, reason: 'fresh campaign', now: 1_700_000_000_200 });
+ expect(readFlywheelTransactionState(root).evidenceEpochStartedAt).toBe(1_700_000_000_200);
+
+ // Evidence issued BEFORE the reset, but registered AFTER it β€” simulates a
+ // stale/cached evaluation or any path that decouples evaluation from
+ // immediate registration. Registration order alone must not be enough to
+ // admit it into the new, cheaper epoch.
+ const stale = makeReceipt(key, { evaluationRunId: '01900000-0000-7000-8000-00000000000a', now: 1_700_000_000_100 });
+ await registerFlywheelReceipt(root, stale, 1_700_000_000_350);
+ const result = await promoteFlywheelCandidate(root, stale.payload.receiptId, common);
+ expect(result.success).toBe(false);
+ expect(result.reason).toMatch(/predates the current evidence epoch/);
+ expect(readFlywheelTransactionState(root).sequentialTests?.[stale.payload.receiptId]).toBeUndefined();
+ });
+
it('recovers consistently from faults before and after the atomic commit', async () => {
const root = mkdtempSync(join(tmpdir(), 'flywheel-fault-'));
const key = keyPair();
diff --git a/v3/@claude-flow/cli/__tests__/harness-flywheel-generations.test.ts b/v3/@claude-flow/cli/__tests__/harness-flywheel-generations.test.ts
index 6515661a8c..54119fcdb3 100644
--- a/v3/@claude-flow/cli/__tests__/harness-flywheel-generations.test.ts
+++ b/v3/@claude-flow/cli/__tests__/harness-flywheel-generations.test.ts
@@ -10,7 +10,7 @@ import { join } from 'node:path';
import { tmpdir } from 'node:os';
import {
runFlywheelGeneration, checkServedChampionDrift, flywheelStatus, loadPromotions, currentChampion, servedChampion,
- axisEffectiveness, biasedGrid,
+ axisEffectiveness, biasedGrid, loadAttempts,
type GenerationDeps, type AnchorTask,
} from '../src/services/harness-flywheel-generations.js';
import type { RankedItem } from '../src/services/harness-flywheel.js';
@@ -89,6 +89,25 @@ describe('runFlywheelGeneration β€” compounding autonomy loop', () => {
expect(s.champion.hash).toBe(currentChampion(root).hash);
});
+ it('concurrent generations against the same root never collide on a sequential-evidence test index (ADR-381 Β§3)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'fwg-race-'));
+ // Two overlapping ticks racing on the same root (e.g. a manual run while
+ // the daemon is also mid-cycle). Both read attempts.jsonl's length before
+ // either appends unless the read-index→append critical section is locked
+ // β€” without the lock this reliably reproduces a duplicate index.
+ const [a, b] = await Promise.all([
+ runFlywheelGeneration(root, makeDeps(1000)),
+ runFlywheelGeneration(root, makeDeps(1000)),
+ ]);
+ expect(a.ran).toBe(true);
+ expect(b.ran).toBe(true);
+
+ const attempts = loadAttempts(root);
+ expect(attempts.length).toBe(2);
+ const indices = attempts.map((att) => att.sequentialEvidence?.testIndex).sort((x, y) => (x ?? 0) - (y ?? 0));
+ expect(indices).toEqual([1, 2]); // distinct β€” never [1, 1]
+ });
+
it('meta-learning: attributes payoff to the axis that moved and biases the search toward it', async () => {
const root = mkdtempSync(join(tmpdir(), 'fwg-'));
await runFlywheelGeneration(root, makeDeps(1000)); // gen 0 moves alpha (the only axis that helps)
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 8a6ce2853a..0c70e5a8be 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -123,24 +123,19 @@
"@agntcy/slim-bindings": "2.0.0-alpha.5",
"@napi-rs/keyring": "1.3.0",
"@claude-flow/memory": "^3.0.0-alpha.21",
+ "@metaharness/darwin": "~0.8.3",
+ "@metaharness/flywheel": "~0.1.10",
+ "@metaharness/radio": "~0.1.0",
"agentdb": "^3.0.0-alpha.17",
"agentic-flow": "^3.0.0-alpha.1",
"better-sqlite3": "^12.9.0",
"ruvector": "^0.2.27"
},
"peerDependencies": {
- "@metaharness/darwin": "^0.8.0",
- "@metaharness/flywheel": "^0.1.7",
"@metaharness/router": "^0.3.2",
"metaharness": "^0.4.1"
},
"peerDependenciesMeta": {
- "@metaharness/darwin": {
- "optional": true
- },
- "@metaharness/flywheel": {
- "optional": true
- },
"@metaharness/router": {
"optional": true
},
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index d4aef22764..39b348aed9 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -1809,6 +1809,71 @@ async function checkMetaharnessIntegration(): Promise<HealthCheck> {
}
}
+/**
+ * Dependency-contract check: every `@metaharness/*` package this CLI DECLARES
+ * in its own optionalDependencies must actually resolve at runtime. Declared
+ * packages are advertised integration surfaces (`ruflo metaharness evolve`,
+ * flywheel receipt interop, radio coordination) β€” a declared-but-absent
+ * package means the install dropped an optional dep (or the declaration
+ * regressed to peer-only), so the advertised integration silently degrades.
+ * That is a FAIL, not a warn: warn is reserved for surfaces that were never
+ * advertised as installed (the `npx metaharness` umbrella path above).
+ */
+async function checkMetaharnessDeclaredPackages(): Promise<HealthCheck> {
+ const NAME = 'MetaHarness declared packages (ADR-150)';
+ try {
+ // Walk up from this module to the CLI package root (works for npx cache,
+ // global install, project-local install, and monorepo dev alike).
+ let root: string | null = null;
+ let q = dirname(fileURLToPath(import.meta.url));
+ for (let i = 0; i < 8; i++) {
+ const pj = join(q, 'package.json');
+ if (existsSync(pj)) {
+ try {
+ if ((JSON.parse(readFileSync(pj, 'utf-8')) as { name?: string }).name === '@claude-flow/cli') { root = q; break; }
+ } catch { /* keep walking */ }
+ }
+ q = dirname(q);
+ }
+ if (!root) return { name: NAME, status: 'warn', message: 'could not locate the @claude-flow/cli package root' };
+
+ const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')) as { optionalDependencies?: Record<string, string> };
+ const declared = Object.keys(pkg.optionalDependencies ?? {}).filter((n) => n === 'metaharness' || n.startsWith('@metaharness/'));
+ if (declared.length === 0) {
+ return {
+ name: NAME,
+ status: 'fail',
+ message: 'no @metaharness/* packages declared in optionalDependencies β€” the dependency contract regressed (peer-only declarations are never installed)',
+ fix: 'Restore @metaharness/darwin, @metaharness/flywheel, @metaharness/radio to optionalDependencies in @claude-flow/cli',
+ };
+ }
+
+ // Node resolution: nearest node_modules wins, walking upward from the CLI root.
+ const resolves = (name: string): boolean => {
+ let d = root as string;
+ for (let i = 0; i < 10; i++) {
+ if (existsSync(join(d, 'node_modules', name, 'package.json'))) return true;
+ const parent = dirname(d);
+ if (parent === d) break;
+ d = parent;
+ }
+ return false;
+ };
+ const missing = declared.filter((n) => !resolves(n));
+ if (missing.length > 0) {
+ return {
+ name: NAME,
+ status: 'fail',
+ message: `declared but not installed: ${missing.join(', ')} β€” advertised MetaHarness surfaces are degraded`,
+ fix: 'npm install --include=optional # optional deps were skipped or pruned',
+ };
+ }
+ return { name: NAME, status: 'pass', message: `${declared.length} declared package(s) resolve: ${declared.join(', ')}` };
+ } catch (err) {
+ return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+ }
+}
+
async function checkMetaharness(): Promise<HealthCheck> {
try {
const version = await runCommand('npx -y metaharness@latest --version 2>&1', 15000);
@@ -2163,6 +2228,7 @@ export const doctorCommand: Command = {
checkEncryptionAtRest, // ADR-096 Phase 5
checkFederationBreaker, // ADR-097 Phase 4
checkMetaharness, // ADR-150 β€” MetaHarness upstream package
+ checkMetaharnessDeclaredPackages, // dependency contract β€” declared optional deps must resolve
checkMetaharnessIntegration, // iter 45 β€” ruflo-side integration layer
checkFunnel, // ADR-305 β€” effective funnel state + deciding precedence source
checkProxySponsoredConsent, // ADR-313 β€” Meta LLM Proxy sponsored-downtime health
@@ -2206,7 +2272,7 @@ export const doctorCommand: Command = {
'agentic-flow': checkAgenticFlow,
'encryption': checkEncryptionAtRest, // ADR-096 Phase 5
'federation': checkFederationBreaker, // ADR-097 Phase 4
- 'metaharness': checkMetaharness, // ADR-150 β€” upstream package
+ 'metaharness': [checkMetaharness, checkMetaharnessDeclaredPackages, checkMetaharnessIntegration], // ADR-150 β€” upstream + declared deps + ruflo-side
'metaharness-integration': checkMetaharnessIntegration, // iter 45 β€” ruflo-side
'funnel': checkFunnel, // ADR-305
// ADR-307 β€” deep-dive array, same pattern as 'memory' above: the cheap
diff --git a/v3/@claude-flow/cli/src/commands/metaharness.ts b/v3/@claude-flow/cli/src/commands/metaharness.ts
index 11ef263ff1..44c0380889 100644
--- a/v3/@claude-flow/cli/src/commands/metaharness.ts
+++ b/v3/@claude-flow/cli/src/commands/metaharness.ts
@@ -45,6 +45,7 @@ import {
listFlywheelReceipts,
promoteFlywheelCandidate,
readFlywheelTransactionState,
+ resetSequentialEvidence,
verifyFlywheelLedger,
} from '../services/flywheel-transaction.js';
import { evaluatePolicyRequest } from '../services/policy-runtime.js';
@@ -134,6 +135,34 @@ async function dispatchFlywheel(
} else if (operation === 'history') {
const state = readFlywheelTransactionState(projectRoot);
data = { ledgerHead: state.ledgerHead, commits: state.commits };
+ } else if (operation === 'evidence-reset') {
+ // ADR-381 Β§2 β€” start a new evidence epoch. Same policy gate as promote:
+ // this reopens the family-wise alpha budget, so it is a governance action.
+ const reason = String(flywheelFlag(flags, 'reason', '')).trim();
+ if (!reason) {
+ data = { success: false, reason: 'evidence-reset requires --reason "<why>" β€” the reset audit trail records intent' };
+ } else {
+ const policy = await evaluatePolicyRequest({
+ identity: { id: process.env.CLAUDE_FLOW_PRINCIPAL_ID ?? 'metaharness-local', type: 'agent', roles: ['optimizer'] },
+ action: {
+ type: 'metaharness.evidence.reset',
+ resource: projectRoot,
+ environment: 'production',
+ destructive: true,
+ },
+ context: {
+ approvalIds: String(flywheelFlag(flags, 'approvalId', '')).split(',').filter(Boolean),
+ },
+ }, projectRoot);
+ if (policy.enforcedOutcome !== 'allowed') {
+ data = { success: false, reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId };
+ } else {
+ data = await resetSequentialEvidence(projectRoot, {
+ confirm: flywheelFlag<boolean>(flags, 'confirm', false) === true,
+ reason,
+ });
+ }
+ }
} else if (operation === 'promote') {
const receiptId = positional[0];
const publicKeyPath = flywheelFlag<string>(flags, 'publicKey');
@@ -159,6 +188,10 @@ async function dispatchFlywheel(
data = await promoteFlywheelCandidate(projectRoot, receiptId, {
confirm: flywheelFlag<boolean>(flags, 'confirm', false) === true,
trustedPublicKeys: new Set([publicKey]),
+ // --allow-aggregate-evidence: explicit migration escape hatch for
+ // pre-upgrade receipts without task-level pairedOutcomes. Default
+ // is strict β€” aggregate-only evidence is refused.
+ requirePairedEvidence: flywheelFlag<boolean>(flags, 'allowAggregateEvidence', false) !== true,
});
}
}
@@ -295,7 +328,7 @@ export const metaharnessCommand: Command = {
output.writeln(' redblue adversarial red/blue LLM testing (init|run|patch|attack|report)');
output.writeln(' evolve Darwin candidate evolution');
output.writeln(' bench create or verify a stable benchmark suite');
- output.writeln(' flywheel receipt loop: run | status | receipts | history | promote');
+ output.writeln(' flywheel receipt loop: run | status | receipts | history | promote | evidence-reset');
output.writeln('');
output.writeln('Each subcommand accepts --format json|table and --help.');
output.writeln('');
diff --git a/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
index 1516af6786..40322b93b7 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/metaharness-tools.ts
@@ -59,6 +59,7 @@ import {
listFlywheelReceipts,
promoteFlywheelCandidate,
readFlywheelTransactionState,
+ resetSequentialEvidence,
verifyFlywheelLedger,
} from '../services/flywheel-transaction.js';
@@ -624,7 +625,7 @@ export const metaharnessTools: MCPTool[] = [
inputSchema: {
type: 'object',
properties: {
- operation: { type: 'string', enum: ['run', 'status', 'receipts', 'history', 'promote'], description: 'Flywheel operation', default: 'status' },
+ operation: { type: 'string', enum: ['run', 'status', 'receipts', 'history', 'promote', 'evidence-reset'], description: 'Flywheel operation', default: 'status' },
projectRoot: { type: 'string', description: 'Target project root (default: active project cwd)' },
receiptId: { type: 'string', description: 'Receipt content ID for promote' },
sample: { type: 'number', description: 'Maximum harvested evaluation sample', default: 40 },
@@ -638,6 +639,8 @@ export const metaharnessTools: MCPTool[] = [
anchorHash: { type: 'string', description: 'Pinned sha256 of canonical anchor tasks; requires anchorPath' },
anchorManifestPath: { type: 'string', description: 'Project-contained anchor manifest path (default .claude/eval/flywheel-anchor.manifest.json)' },
approvalIds: { type: 'array', items: { type: 'string' }, description: 'Scoped ADR-324 approval IDs for privileged promotion' },
+ allowAggregateEvidence: { type: 'boolean', description: 'Migration escape hatch: accept a pre-upgrade receipt without task-level pairedOutcomes. Default false β€” aggregate-only evidence is refused by the strict sequential-evidence gate.', default: false },
+ reason: { type: 'string', description: 'Required for evidence-reset (ADR-381): the human intent recorded in the append-only reset audit trail.' },
},
required: ['operation'],
},
@@ -692,6 +695,36 @@ export const metaharnessTools: MCPTool[] = [
});
return { success: data.ran, data, degraded: false, exitCode: data.ran ? 0 : 1 };
}
+ if (operation === 'evidence-reset') {
+ // ADR-381 Β§2 β€” reopens the family-wise alpha budget; same policy
+ // gate as promote, plus a mandatory recorded reason.
+ const reason = String(input.reason ?? '').trim();
+ if (!reason) {
+ return { success: false, data: { reason: 'evidence-reset requires a non-empty reason β€” the reset audit trail records intent' }, degraded: false, exitCode: 2 };
+ }
+ const policy = await evaluatePolicyRequest({
+ identity: { id: 'metaharness-mcp', type: 'agent', roles: ['optimizer'] },
+ action: {
+ type: 'metaharness.evidence.reset',
+ resource: projectRoot,
+ environment: 'production',
+ destructive: true,
+ },
+ context: {
+ approvalIds: Array.isArray(input.approvalIds) ? input.approvalIds.map(String) : undefined,
+ },
+ }, projectRoot);
+ if (policy.enforcedOutcome !== 'allowed') {
+ return {
+ success: false,
+ data: { reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId },
+ degraded: false,
+ exitCode: 1,
+ };
+ }
+ const data = await resetSequentialEvidence(projectRoot, { confirm: input.confirm === true, reason });
+ return { success: data.success, data, degraded: false, exitCode: data.success ? 0 : 1 };
+ }
if (operation === 'promote') {
if (!input.receiptId || !input.publicKeyPath) {
return { success: false, data: { reason: 'receiptId and publicKeyPath are required' }, degraded: false, exitCode: 2 };
@@ -720,6 +753,7 @@ export const metaharnessTools: MCPTool[] = [
const data = await promoteFlywheelCandidate(projectRoot, String(input.receiptId), {
confirm: input.confirm === true,
trustedPublicKeys: new Set([publicKey]),
+ requirePairedEvidence: input.allowAggregateEvidence !== true,
});
return { success: data.success, data, degraded: false, exitCode: data.success ? 0 : 1 };
}
diff --git a/v3/@claude-flow/cli/src/services/distill-oracle.ts b/v3/@claude-flow/cli/src/services/distill-oracle.ts
index 1cc99bc363..f3bc648aa6 100644
--- a/v3/@claude-flow/cli/src/services/distill-oracle.ts
+++ b/v3/@claude-flow/cli/src/services/distill-oracle.ts
@@ -51,8 +51,8 @@ import {
// behavior mid-run (the #142 pin-drift failure mode). Pin it, and let
// scripts/check-metaharness-pins.mjs watch this constant for drift. Kept in
// lock-step with the optionalDependencies pin in package.json and the plugin
-// darwin cache (darwin-cache-0.8.0).
-export const MH_DARWIN_PIN = '0.8.0';
+// darwin cache (versioned by the plugin's own `~0.8.0` pin in _darwin.mjs).
+export const MH_DARWIN_PIN = '0.8.3';
// ── Provenance ─────────────────────────────────────────────────────────────
diff --git a/v3/@claude-flow/cli/src/services/evolve-proof.ts b/v3/@claude-flow/cli/src/services/evolve-proof.ts
index cbc5a3547a..03f1eb0f77 100644
--- a/v3/@claude-flow/cli/src/services/evolve-proof.ts
+++ b/v3/@claude-flow/cli/src/services/evolve-proof.ts
@@ -21,6 +21,12 @@
import { createHash } from 'node:crypto';
import { accept, type PromotionVerdict, type AcceptResult } from './harness-benchmark.js';
import { bootstrapDeltaCILow } from './harness-improvement-ledger.js';
+import {
+ DEFAULT_ALPHA_TOTAL,
+ DEFAULT_LAMBDA,
+ SEQUENTIAL_EVIDENCE_VERSION,
+ sequentialEvidenceVerdict,
+} from './flywheel-sequential-evidence.js';
import { canonicalManifestBytes, type ProvenConfigManifest } from '../config/proven-config.js';
/**
@@ -29,8 +35,16 @@ import { canonicalManifestBytes, type ProvenConfigManifest } from '../config/pro
* term: the per-held-out-task deltas must have a positive one-sided 95% bootstrap
* lower bound, so a small-N mean gain can't ride on noise. The canary term is a
* SEPARATE deployment-safety signal (a distinct slice), not held-out dominance.
+ *
+ * v2+seq (ADR-381 Β§3) adds a third conjunct: an anytime-valid sequential-
+ * evidence e-process over the holdout's paired per-task scores, judged at the
+ * alpha allocated to this bundle's position in the lineage's adaptive test
+ * stream (alpha_k = alphaTotal Β· 6/(π²kΒ²)). The rule version is pinned PER
+ * BUNDLE, so a lineage may contain both v1 and v2 bundles and each replays
+ * under its own recorded semantics.
*/
export const PROMOTION_RULE_VERSION = 'accept/v1+sig';
+export const PROMOTION_RULE_VERSION_V2 = 'accept/v2+seq';
export const PROOF_LABEL = 'single-round proof-of-mechanism';
export const NOT_CLAIMS = ['not flywheel proof', 'not compounding learning', 'not production learning'] as const;
@@ -92,10 +106,28 @@ export interface RegressionRecord {
candidateManifestHash: string;
ancestor: string | null; // the policy this mutated from
mutationClass: string;
- failureCause: 'holdout' | 'security' | 'drift' | 'replay' | 'governance' | 'canary' | 'significance';
+ failureCause: 'holdout' | 'security' | 'drift' | 'replay' | 'governance' | 'canary' | 'significance' | 'sequential';
failedTerms: string[]; // the accept() terms that failed
}
+/**
+ * The v2 sequential-evidence term, embedded so `verifyReceiptBundle` can
+ * replay it from the bundle's own holdout: the recorded testIndex/alphaTotal/
+ * lambda fully determine the threshold, and the e-value recomputes from the
+ * embedded per-task scores.
+ */
+export interface SequentialEvidenceRecord {
+ version: typeof SEQUENTIAL_EVIDENCE_VERSION;
+ testIndex: number;
+ alphaTotal: number;
+ lambda: number;
+ alphaAllocated: number;
+ eValue: number;
+ threshold: number;
+ informativePairs: number;
+ significant: boolean;
+}
+
export interface EvolveReceiptBundle {
label: typeof PROOF_LABEL;
disclaimers: typeof NOT_CLAIMS;
@@ -109,6 +141,8 @@ export interface EvolveReceiptBundle {
baselineManifestHash: string;
candidateManifestHash: string;
meetsPromotionRule: { version: string; result: boolean };
+ /** Present iff the bundle was decided under accept/v2+seq (ADR-381 Β§3). */
+ sequentialEvidence?: SequentialEvidenceRecord;
decisionReceipt: DecisionReceipt;
shadow: ShadowRegistration | null; // null when the candidate did NOT pass
costReceipt: CostReceipt;
@@ -155,6 +189,12 @@ export interface AssembleOpts {
humanRelevanceDelta?: number; // per-gen Ξ” on the frozen human eval set
humanEvalHash?: string; // which frozen human eval set the delta is against
layer?: string; corpus?: string;
+ /**
+ * ADR-381 Β§3 β€” supply to decide the bundle under accept/v2+seq: the bundle's
+ * 1-based position in the lineage's adaptive test stream, plus optional
+ * alpha/lambda overrides. Omit for legacy v1+sig semantics.
+ */
+ sequential?: { testIndex: number; alphaTotal?: number; lambda?: number };
}
/**
@@ -174,13 +214,38 @@ export function assembleBundle(baseline: Record<string, number>, candidate: Reco
const deltaCILow = bootstrapDeltaCILow(holdout.map((h) => h.candidateScore - h.baselineScore));
const significant = deltaCILow > 0;
+ // v2 sequential term (ADR-381 Β§3): anytime-valid e-process over the paired
+ // per-task scores, at this bundle's allocated share of the family-wise alpha.
+ let sequentialEvidence: SequentialEvidenceRecord | undefined;
+ if (o.sequential) {
+ const alphaTotal = o.sequential.alphaTotal ?? DEFAULT_ALPHA_TOTAL;
+ const lambda = o.sequential.lambda ?? DEFAULT_LAMBDA;
+ const verdict = sequentialEvidenceVerdict(
+ holdout.map((h) => ({ taskId: h.taskId, baselineScore: h.baselineScore, candidateScore: h.candidateScore })),
+ o.sequential.testIndex,
+ { alphaTotal, lambda },
+ );
+ sequentialEvidence = {
+ version: SEQUENTIAL_EVIDENCE_VERSION,
+ testIndex: verdict.testIndex,
+ alphaTotal,
+ lambda,
+ alphaAllocated: verdict.alphaAllocated,
+ eValue: verdict.eValue,
+ threshold: verdict.threshold,
+ informativePairs: verdict.informativePairs,
+ significant: verdict.significant,
+ };
+ }
+ const ruleVersion = sequentialEvidence ? PROMOTION_RULE_VERSION_V2 : PROMOTION_RULE_VERSION;
+
const verdictInputs: PromotionVerdict = {
heldOutScore: candidateHeldOut, baselineHeldOutScore: baselineHeldOut,
redblue: o.redblue ?? 'PASS', drift: o.drift ?? 0, driftThreshold: 0.05,
replayDeterministic: true, receiptCoverage: 1, canaryRollbackRate, baselineRollbackRate: 0,
};
const result = accept(verdictInputs);
- const promoted = result.accept && significant;
+ const promoted = result.accept && significant && (sequentialEvidence?.significant ?? true);
const baselineManifest = mkManifest(baseline, o.layer, o.corpus);
const candidateManifest = mkManifest(candidate, o.layer, o.corpus);
@@ -188,10 +253,14 @@ export function assembleBundle(baseline: Record<string, number>, candidate: Reco
const candidateManifestHash = manifestHash(candidateManifest);
const inputHoldoutHash = sha256(canon(holdout));
- const failed = [...result.failed, ...(!significant ? ['significant'] : [])];
+ const failed = [
+ ...result.failed,
+ ...(!significant ? ['significant'] : []),
+ ...(sequentialEvidence && !sequentialEvidence.significant ? ['sequential_evidence'] : []),
+ ];
const decisionReceipt: DecisionReceipt = {
- promotionRuleVersion: PROMOTION_RULE_VERSION, verdictInputs, result, significant, deltaCILow, promoted,
- reason: promoted ? `promoted (all ${PROMOTION_RULE_VERSION} terms held)` : `rejected β€” ${failed.join(', ')}`,
+ promotionRuleVersion: ruleVersion, verdictInputs, result, significant, deltaCILow, promoted,
+ reason: promoted ? `promoted (all ${ruleVersion} terms held)` : `rejected β€” ${failed.join(', ')}`,
};
const shadow: ShadowRegistration | null = promoted ? {
registrationId: sha256(`${candidateManifestHash}|gen${o.generation}|shadow`).replace('sha256:', 'shadow:'),
@@ -203,13 +272,17 @@ export function assembleBundle(baseline: Record<string, number>, candidate: Reco
const promotion: PromotionRecord | null = promoted ? { parentManifestHash: o.parent, candidateManifestHash, mutationClass, mutationSummary, deltas, decisionReceipt } : null;
const regression: RegressionRecord | null = promoted ? null : {
candidateManifestHash, ancestor: o.parent ?? baselineManifestHash, mutationClass,
- failureCause: !significant && result.accept ? 'significance' : (FAILURE_CAUSE[result.failed[0]] ?? 'holdout'), failedTerms: failed,
+ failureCause: result.accept
+ ? (!significant ? 'significance' : 'sequential')
+ : (FAILURE_CAUSE[result.failed[0]] ?? 'holdout'),
+ failedTerms: failed,
};
return {
label: PROOF_LABEL, disclaimers: NOT_CLAIMS, generation: o.generation, parent: o.parent, branch: o.branch, kind: o.kind, createdAt: o.now,
inputHoldoutHash, baselineManifestHash, candidateManifestHash,
- meetsPromotionRule: { version: PROMOTION_RULE_VERSION, result: promoted },
+ meetsPromotionRule: { version: ruleVersion, result: promoted },
+ ...(sequentialEvidence ? { sequentialEvidence } : {}),
decisionReceipt, shadow,
costReceipt: { usd: 0, llmCalls: 0, tier: o.cost.tier, notes: o.cost.notes },
mutationClass, mutationSummary, deltas, humanEvalHash: o.humanEvalHash, promotion, regression,
@@ -229,6 +302,7 @@ export function runRealEvolveRound(opts: {
generation: number; parent: string | null; branch?: string; now: number;
redblue?: 'PASS' | 'FAIL' | 'SKIPPED'; drift?: number; canaryRollbackRate?: number;
humanRelevanceDelta?: number; humanEvalHash?: string; corpus: string;
+ sequential?: AssembleOpts['sequential'];
}): EvolveReceiptBundle {
return assembleBundle(opts.baseline, opts.candidate, opts.holdout, {
generation: opts.generation, parent: opts.parent, branch: opts.branch ?? 'main', now: opts.now, kind: 'real',
@@ -236,6 +310,7 @@ export function runRealEvolveRound(opts: {
redblue: opts.redblue, drift: opts.drift, canaryRollbackRate: opts.canaryRollbackRate,
humanRelevanceDelta: opts.humanRelevanceDelta, humanEvalHash: opts.humanEvalHash,
layer: 'real/retrieval', corpus: opts.corpus,
+ sequential: opts.sequential,
});
}
@@ -308,16 +383,39 @@ export function verifyReceiptBundle(bundle: EvolveReceiptBundle): VerifyReport {
const deltaCILow = bootstrapDeltaCILow(bundle.holdout.map((h) => h.candidateScore - h.baselineScore));
const significant = deltaCILow > 0;
- // Re-run the SAME versioned rule on independently-recomputed inputs.
- const ruleVersionMatches = bundle.decisionReceipt.promotionRuleVersion === PROMOTION_RULE_VERSION
- && bundle.meetsPromotionRule.version === PROMOTION_RULE_VERSION;
- if (!ruleVersionMatches) mismatches.push(`promotion rule version != ${PROMOTION_RULE_VERSION}`);
+ // Re-run the SAME versioned rule the bundle was decided under (pinned per
+ // bundle β€” a lineage may legitimately mix v1 and v2, ADR-381 Β§3). The rule
+ // version and the presence of the sequential record must agree.
+ const expectedVersion = bundle.sequentialEvidence ? PROMOTION_RULE_VERSION_V2 : PROMOTION_RULE_VERSION;
+ const ruleVersionMatches = bundle.decisionReceipt.promotionRuleVersion === expectedVersion
+ && bundle.meetsPromotionRule.version === expectedVersion;
+ if (!ruleVersionMatches) mismatches.push(`promotion rule version != ${expectedVersion} (or sequential record inconsistent with version)`);
+
+ // v2: replay the sequential e-process from the embedded holdout using the
+ // recorded testIndex/alphaTotal/lambda β€” the recorded verdict must recompute.
+ let sequentialOk = true;
+ if (bundle.sequentialEvidence) {
+ const s = bundle.sequentialEvidence;
+ try {
+ const replayed = sequentialEvidenceVerdict(
+ bundle.holdout.map((h) => ({ taskId: h.taskId, baselineScore: h.baselineScore, candidateScore: h.candidateScore })),
+ s.testIndex,
+ { alphaTotal: s.alphaTotal, lambda: s.lambda },
+ );
+ sequentialOk = Math.abs(replayed.eValue - s.eValue) < 1e-9
+ && replayed.significant === s.significant
+ && replayed.informativePairs === s.informativePairs;
+ } catch {
+ sequentialOk = false;
+ }
+ if (!sequentialOk) mismatches.push('recorded sequential-evidence verdict does not recompute from the embedded holdout');
+ }
const decision = accept({
...bundle.decisionReceipt.verdictInputs,
heldOutScore: candidateHeldOut, baselineHeldOutScore: baselineHeldOut,
});
- const promotedRecomputed = decision.accept && significant;
+ const promotedRecomputed = decision.accept && significant && (bundle.sequentialEvidence ? bundle.sequentialEvidence.significant && sequentialOk : true);
const decisionMatches = promotedRecomputed === bundle.decisionReceipt.promoted && promotedRecomputed === bundle.meetsPromotionRule.result;
if (!decisionMatches) mismatches.push('recomputed decision != recorded decision');
@@ -334,11 +432,15 @@ export function verifyReceiptBundle(bundle: EvolveReceiptBundle): VerifyReport {
if (!causalConsistent) mismatches.push('causal record inconsistent with the decision (promotion/regression/delta)');
const valid = hashChecks.inputHoldout && hashChecks.baselineManifest && hashChecks.candidateManifest
- && ruleVersionMatches && decisionMatches && noAutoServe && causalConsistent;
+ && ruleVersionMatches && decisionMatches && noAutoServe && causalConsistent && sequentialOk;
const why = promotedRecomputed
- ? `PASS under ${PROMOTION_RULE_VERSION}: held_out ${candidateHeldOut.toFixed(4)} > ${baselineHeldOut.toFixed(4)} (Ξ” CI-low ${deltaCILow.toFixed(4)} > 0, significant), canary rollback ${canaryRollbackRate} ≀ 0, all terms held`
- : `FAIL under ${PROMOTION_RULE_VERSION}: ${[...decision.failed, ...(!significant ? ['significant'] : [])].join(', ')}`;
+ ? `PASS under ${expectedVersion}: held_out ${candidateHeldOut.toFixed(4)} > ${baselineHeldOut.toFixed(4)} (Ξ” CI-low ${deltaCILow.toFixed(4)} > 0, significant), canary rollback ${canaryRollbackRate} ≀ 0, all terms held`
+ : `FAIL under ${expectedVersion}: ${[
+ ...decision.failed,
+ ...(!significant ? ['significant'] : []),
+ ...(bundle.sequentialEvidence && !(bundle.sequentialEvidence.significant && sequentialOk) ? ['sequential_evidence'] : []),
+ ].join(', ')}`;
return {
valid, hashChecks,
diff --git a/v3/@claude-flow/cli/src/services/flywheel-receipt.ts b/v3/@claude-flow/cli/src/services/flywheel-receipt.ts
index a9bbaedd78..fbd7f5eddf 100644
--- a/v3/@claude-flow/cli/src/services/flywheel-receipt.ts
+++ b/v3/@claude-flow/cli/src/services/flywheel-receipt.ts
@@ -12,6 +12,7 @@ import {
sign as edSign,
verify as edVerify,
} from 'node:crypto';
+import { checkPairedOutcomesConsistency, type PairedTaskOutcome } from './flywheel-sequential-evidence.js';
export const RECEIPT_SCHEMA = 'ruflo.flywheel-receipt/v1';
export const RECEIPT_DOMAIN = 'ruflo/flywheel-receipt/v1';
@@ -88,6 +89,14 @@ export interface FlywheelReceiptPayload {
baselineScore: string;
candidateScore: string;
heldOutDeltas: string[];
+ /**
+ * Task-level paired outcomes behind heldOutDeltas β€” same order, same length,
+ * per-task delta reproducible from the two scores. Optional in the payload
+ * so pre-existing receipts still verify byte-identically, but the promotion
+ * authority (flywheel-transaction.ts) REQUIRES it by default: aggregate-only
+ * evidence is refused rather than silently falling back to the weaker gate.
+ */
+ pairedOutcomes?: Array<{ taskId: string; baselineScore: string; candidateScore: string }>;
statistics: PromotionStatistics;
gates: Record<string, boolean>;
resourceEvidence: ResourceEvidence;
@@ -121,6 +130,8 @@ export interface CreateReceiptInput {
baselineScore: number;
candidateScore: number;
heldOutDeltas: number[];
+ /** Task-level paired outcomes behind heldOutDeltas (same order). */
+ pairedOutcomes?: PairedTaskOutcome[];
frozenAnchorRegression: number;
gates: Record<string, boolean>;
resourceEvidence?: Partial<ResourceEvidence>;
@@ -344,6 +355,15 @@ export function createFlywheelReceipt(input: CreateReceiptInput): FlywheelEvalua
baselineScore: decimal(input.baselineScore),
candidateScore: decimal(input.candidateScore),
heldOutDeltas: input.heldOutDeltas.map((v) => decimal(v)),
+ ...(input.pairedOutcomes
+ ? {
+ pairedOutcomes: input.pairedOutcomes.map((o) => ({
+ taskId: o.taskId,
+ baselineScore: decimal(o.baselineScore),
+ candidateScore: decimal(o.candidateScore),
+ })),
+ }
+ : {}),
statistics,
gates: input.gates,
resourceEvidence: {
@@ -418,6 +438,17 @@ export function verifyFlywheelReceipt(receipt: FlywheelEvaluationReceipt, truste
? 'accepted'
: 'rejected';
if (receipt.payload.decision !== recomputedDecision) errors.push('receipt decision does not recompute');
+ if (receipt.payload.pairedOutcomes) {
+ // Paired outcomes must reproduce the aggregate they claim to back.
+ // Tolerance covers the decimal(scale 12) round-trip of both scores.
+ const paired = receipt.payload.pairedOutcomes.map((o) => ({
+ taskId: o.taskId,
+ baselineScore: Number(o.baselineScore),
+ candidateScore: Number(o.candidateScore),
+ }));
+ const check = checkPairedOutcomesConsistency(paired, receipt.payload.heldOutDeltas.map(Number), 1e-9);
+ if (!check.ok) errors.push(`paired outcomes inconsistent: ${check.reasons.join('; ')}`);
+ }
if (!receipt.signature) {
errors.push('receipt is unsigned');
} else {
diff --git a/v3/@claude-flow/cli/src/services/flywheel-sequential-evidence.ts b/v3/@claude-flow/cli/src/services/flywheel-sequential-evidence.ts
new file mode 100644
index 0000000000..0577e2eee3
--- /dev/null
+++ b/v3/@claude-flow/cli/src/services/flywheel-sequential-evidence.ts
@@ -0,0 +1,185 @@
+/**
+ * Sequential promotion evidence β€” family-wise error control for an ADAPTIVE
+ * candidate stream (report item 2 / upstream @metaharness/flywheel 0.1.10
+ * `withSequentialEvidence` interop, implemented in-house so ruflo keeps the
+ * property with every MetaHarness package removed).
+ *
+ * THE GAP THIS CLOSES: every promotion gate ruflo runs (accept/v1+sig, the
+ * ruflo.flywheel-gate/v1 bootstrap) spends a FRESH alpha per candidate. A
+ * flywheel proposes candidates adaptively β€” each new candidate is chosen after
+ * looking at the last one's scores β€” so per-candidate alpha does not bound the
+ * probability that ANY promotion in the stream is false. Published
+ * measurements of greedy accept-if-improved loops put the false-commit rate at
+ * 30-42% under exactly this regime.
+ *
+ * TWO COMPOSED MECHANISMS, both required by the promotion authority:
+ *
+ * 1. Anytime-valid e-process per candidate (testing-by-betting). Per paired
+ * task, a discordant pair multiplies the e-value by (1+lambda) when the
+ * candidate wins and (1-lambda) when the baseline wins; concordant pairs
+ * carry no information (McNemar). Under the null the e-value is a
+ * non-negative martingale with expectation 1, so by Ville's inequality
+ * P(e ever reaches 1/alpha) <= alpha β€” no penalty for peeking mid-stream.
+ *
+ * 2. Alpha allocation ACROSS candidates. Candidate k in the lineage's test
+ * stream must clear 1/alpha_k where alpha_k = alphaTotal * 6/(pi^2 * k^2),
+ * so sum(alpha_k) = alphaTotal for arbitrarily many adaptively-chosen
+ * candidates. The allocation index is persisted per receipt in the
+ * transaction state β€” looking spends alpha whether or not the candidate
+ * promotes, and retrying the same receipt reuses its index (no double
+ * spend, no index shopping).
+ *
+ * Family-wise guarantee: P(any false promotion, ever, in the stream)
+ * <= sum_k alpha_k = alphaTotal. The acceptance test for this module is the
+ * 1,000-null-simulation in flywheel-sequential-evidence.test.ts.
+ *
+ * Pure, $0, deterministic. Never throws on well-typed input.
+ */
+
+export const SEQUENTIAL_EVIDENCE_VERSION = 'ruflo.sequential-evidence/v1';
+
+export const DEFAULT_ALPHA_TOTAL = 0.05;
+export const DEFAULT_LAMBDA = 0.5;
+/** Score tie-band: |candidate - baseline| <= epsilon is a concordant (uninformative) pair. */
+export const DEFAULT_SCORE_EPSILON = 1e-9;
+
+/** Task-level paired outcome β€” the evidence unit receipts must now carry. */
+export interface PairedTaskOutcome {
+ taskId: string;
+ baselineScore: number;
+ candidateScore: number;
+}
+
+export interface SequentialEvidenceConfig {
+ /** Total family-wise type-I budget across the WHOLE candidate stream. */
+ alphaTotal?: number;
+ /** Betting fraction in (0,1); 0.5 needs no tuning. */
+ lambda?: number;
+ /** Tie band on score comparisons. */
+ epsilon?: number;
+}
+
+export interface SequentialEvidenceVerdict {
+ significant: boolean;
+ eValue: number;
+ threshold: number; // 1 / alphaAllocated
+ alphaAllocated: number; // this test's share of the family-wise budget
+ testIndex: number; // 1-based position in the lineage's test stream
+ informativePairs: number; // discordant pairs β€” the only ones carrying signal
+ totalPairs: number;
+ version: typeof SEQUENTIAL_EVIDENCE_VERSION;
+}
+
+/**
+ * Alpha share for the k-th test in the stream: alphaTotal * 6/(pi^2 k^2).
+ * Chosen over 2^-k because it decays polynomially β€” test 10 still gets a
+ * workable ~0.6% of a 5% budget instead of ~0.005%.
+ */
+export function alphaForTest(testIndex: number, alphaTotal = DEFAULT_ALPHA_TOTAL): number {
+ if (!Number.isInteger(testIndex) || testIndex < 1) throw new RangeError('testIndex must be a positive integer');
+ if (!(alphaTotal > 0 && alphaTotal < 1)) throw new RangeError('alphaTotal must be in (0, 1)');
+ return (alphaTotal * 6) / (Math.PI * Math.PI * testIndex * testIndex);
+}
+
+/**
+ * Fold paired outcomes into an anytime-valid e-value and judge it against the
+ * k-th test's allocated alpha. Deterministic; order of outcomes does not
+ * change the final e-value (the product commutes).
+ */
+export function sequentialEvidenceVerdict(
+ outcomes: PairedTaskOutcome[],
+ testIndex: number,
+ config: SequentialEvidenceConfig = {},
+): SequentialEvidenceVerdict {
+ const alphaTotal = config.alphaTotal ?? DEFAULT_ALPHA_TOTAL;
+ const lambda = config.lambda ?? DEFAULT_LAMBDA;
+ const epsilon = config.epsilon ?? DEFAULT_SCORE_EPSILON;
+ if (!(lambda > 0 && lambda < 1)) throw new RangeError('lambda must be in (0, 1)');
+ const alphaAllocated = alphaForTest(testIndex, alphaTotal);
+ const threshold = 1 / alphaAllocated;
+
+ let eValue = 1;
+ let informativePairs = 0;
+ for (const o of outcomes) {
+ const delta = o.candidateScore - o.baselineScore;
+ if (Math.abs(delta) <= epsilon) continue; // concordant: no information
+ informativePairs++;
+ // Under the null a discordant pair favors either arm with probability 1/2,
+ // so E[multiplier] = 1 and the running product is a martingale.
+ eValue *= delta > 0 ? 1 + lambda : 1 - lambda;
+ }
+
+ return {
+ significant: eValue >= threshold,
+ eValue,
+ threshold,
+ alphaAllocated,
+ testIndex,
+ informativePairs,
+ totalPairs: outcomes.length,
+ version: SEQUENTIAL_EVIDENCE_VERSION,
+ };
+}
+
+/**
+ * Minimum number of INFORMATIVE (discordant) pairs a candidate must win β€”
+ * with zero losses β€” to clear the k-th test's threshold: the smallest n with
+ * (1+lambda)^n >= 1/alpha_k. The pre-flight power check (ADR-381 Β§4): an
+ * evaluation whose promotion holdout is smaller than this cannot promote even
+ * on a perfect sweep, so it should be refused BEFORE compute is spent and
+ * before a doomed receipt can be presented to the gate (spending alpha).
+ */
+export function minInformativePairsToClear(testIndex: number, config: SequentialEvidenceConfig = {}): number {
+ const alphaTotal = config.alphaTotal ?? DEFAULT_ALPHA_TOTAL;
+ const lambda = config.lambda ?? DEFAULT_LAMBDA;
+ if (!(lambda > 0 && lambda < 1)) throw new RangeError('lambda must be in (0, 1)');
+ const threshold = 1 / alphaForTest(testIndex, alphaTotal);
+ return Math.ceil(Math.log(threshold) / Math.log(1 + lambda));
+}
+
+/** Family-wise budget left after `testsRun` allocated tests: alphaTotal - Ξ£ alpha_k. */
+export function remainingAlphaBudget(testsRun: number, alphaTotal = DEFAULT_ALPHA_TOTAL): number {
+ if (!Number.isInteger(testsRun) || testsRun < 0) throw new RangeError('testsRun must be a non-negative integer');
+ let spent = 0;
+ for (let k = 1; k <= testsRun; k++) spent += alphaForTest(k, alphaTotal);
+ return Math.max(0, alphaTotal - spent);
+}
+
+export interface PairedEvidenceCheck {
+ ok: boolean;
+ reasons: string[];
+}
+
+/**
+ * Structural consistency between a receipt's paired outcomes and its
+ * aggregate heldOutDeltas: same length and order, unique non-empty task IDs,
+ * and each delta must equal candidateScore - baselineScore. This is what makes
+ * paired outcomes EVIDENCE rather than decoration β€” an aggregate that cannot
+ * be reproduced from its own per-task rows is refused.
+ */
+export function checkPairedOutcomesConsistency(
+ pairedOutcomes: PairedTaskOutcome[],
+ heldOutDeltas: number[],
+ tolerance = 1e-9,
+): PairedEvidenceCheck {
+ const reasons: string[] = [];
+ if (pairedOutcomes.length === 0) reasons.push('pairedOutcomes is empty');
+ if (pairedOutcomes.length !== heldOutDeltas.length) {
+ reasons.push(`pairedOutcomes length ${pairedOutcomes.length} != heldOutDeltas length ${heldOutDeltas.length}`);
+ }
+ const ids = new Set<string>();
+ for (const [i, o] of pairedOutcomes.entries()) {
+ if (!o.taskId || typeof o.taskId !== 'string') reasons.push(`pairedOutcomes[${i}] has an empty taskId`);
+ else if (ids.has(o.taskId)) reasons.push(`duplicate taskId '${o.taskId}'`);
+ else ids.add(o.taskId);
+ if (!Number.isFinite(o.baselineScore) || !Number.isFinite(o.candidateScore)) {
+ reasons.push(`pairedOutcomes[${i}] has a non-finite score`);
+ continue;
+ }
+ const delta = heldOutDeltas[i];
+ if (delta !== undefined && Math.abs((o.candidateScore - o.baselineScore) - delta) > tolerance) {
+ reasons.push(`pairedOutcomes[${i}] delta ${(o.candidateScore - o.baselineScore).toFixed(12)} != heldOutDeltas[${i}] ${delta}`);
+ }
+ }
+ return { ok: reasons.length === 0, reasons };
+}
diff --git a/v3/@claude-flow/cli/src/services/flywheel-transaction.ts b/v3/@claude-flow/cli/src/services/flywheel-transaction.ts
index e2d38665bb..e7226cdd2e 100644
--- a/v3/@claude-flow/cli/src/services/flywheel-transaction.ts
+++ b/v3/@claude-flow/cli/src/services/flywheel-transaction.ts
@@ -17,6 +17,12 @@ import {
verifyFlywheelReceipt,
type FlywheelEvaluationReceipt,
} from './flywheel-receipt.js';
+import {
+ DEFAULT_ALPHA_TOTAL,
+ DEFAULT_LAMBDA,
+ minInformativePairsToClear,
+ sequentialEvidenceVerdict,
+} from './flywheel-sequential-evidence.js';
const STATE_VERSION = 1 as const;
const STATE_DIR = ['.claude-flow', 'flywheel-v1'] as const;
@@ -62,6 +68,53 @@ export interface FlywheelTransactionState {
servedChampionRef: string | null;
receiptStates: Record<string, ReceiptState>;
commits: PromotionCommit[];
+ /**
+ * Sequential-evidence alpha ledger (ADR-381): receiptId β†’ 1-based test
+ * index in this ledger's promotion-test stream for the CURRENT evidence
+ * epoch. The stream is scoped to the transaction state itself (one ledger,
+ * one champion chain, one stream) β€” NOT to receipt lineageIds, which
+ * default to a fresh UUID per run and would void the control. An index is
+ * allocated the first time a receipt is presented to the promotion gate
+ * and persists whether or not the candidate promoted β€” looking spends
+ * alpha, and retrying the same receipt reuses its index (no double spend,
+ * no index shopping). Absent in pre-upgrade state files; readers treat
+ * missing as empty.
+ */
+ sequentialTests?: Record<string, number>;
+ /** Current evidence epoch (ADR-381 Β§2). Incremented only by an explicit governed reset. */
+ evidenceEpoch?: number;
+ /**
+ * Wall-clock boundary (ms) of the current evidence epoch β€” the `now` an
+ * explicit reset ran at. A receipt whose OWN evidence (payload.issuedAt)
+ * predates this boundary belongs to a prior epoch even if it happens to be
+ * registered/promoted after the reset β€” the exact "index shopping" ADR-381
+ * Β§2 requires the epoch mechanism to prevent. Undefined for the genesis
+ * epoch (no lower bound) and for state files written before this field
+ * existed.
+ */
+ evidenceEpochStartedAt?: number;
+ /** Append-only audit trail of evidence resets. Nothing is ever deleted from it. */
+ sequentialResets?: SequentialResetRecord[];
+}
+
+export interface SequentialResetRecord {
+ /** The epoch that was CLOSED by this reset. */
+ epoch: number;
+ at: number;
+ reason: string;
+ /** Alpha spend archived from the closed epoch (receiptId β†’ test index). */
+ testsSpent: Record<string, number>;
+ /** Outstanding 'evaluated' receipts expired by the reset (fresh-data enforcement). */
+ expiredReceipts: string[];
+}
+
+export interface EvidenceResetResult {
+ success: boolean;
+ reason: string;
+ closedEpoch?: number;
+ newEpoch?: number;
+ testsArchived?: number;
+ receiptsExpired?: number;
}
export interface PromotionResult {
@@ -84,6 +137,18 @@ export interface PromoteOptions {
approvedAttestors?: Set<string>;
allowedProposerSubstitutions?: Set<string>;
applyFn?: (root: string, policy: Record<string, unknown>, championRef: string, previous: string | null, now: number) => ApplyResult;
+ /**
+ * Strict promotion evidence (default true): the receipt must carry
+ * task-level pairedOutcomes AND clear the sequential-evidence e-process at
+ * this test's allocated share of the family-wise alpha budget. Set false
+ * ONLY as an explicit migration escape hatch for pre-upgrade receipts β€”
+ * aggregate-only evidence is otherwise refused, never silently accepted.
+ */
+ requirePairedEvidence?: boolean;
+ /** Family-wise type-I budget across the whole candidate stream (default 0.05). */
+ sequentialAlphaTotal?: number;
+ /** e-process betting fraction in (0,1) (default 0.5). */
+ sequentialLambda?: number;
/** Test-only crash hook; production callers leave unset. */
faultAt?: 'before-commit' | 'after-commit-before-materialize';
}
@@ -215,6 +280,52 @@ export function readFlywheelReceipt(root: string, receiptId: string): FlywheelEv
}
}
+/**
+ * Start a new evidence epoch (ADR-381 Β§2): archive the current alpha spend
+ * into the append-only reset audit trail, EXPIRE every outstanding
+ * 'evaluated' receipt (the new epoch may only promote evidence produced
+ * after the reset β€” structurally enforcing fresh data), clear the spend
+ * ledger, and increment the epoch. Requires explicit confirmation and a
+ * non-empty human reason; the CLI/MCP surfaces additionally gate this
+ * through the same policy engine as promotion.
+ */
+export async function resetSequentialEvidence(
+ root: string,
+ options: { confirm: boolean; reason: string; now?: number },
+): Promise<EvidenceResetResult> {
+ if (!options.confirm) return { success: false, reason: 'explicit confirmation required' };
+ const reason = (options.reason ?? '').trim();
+ if (!reason) return { success: false, reason: 'a non-empty reason is required β€” the reset audit trail records intent' };
+ const now = options.now ?? Date.now();
+ return withStateLock(root, () => {
+ const state = readFlywheelTransactionState(root);
+ const closedEpoch = state.evidenceEpoch ?? 0;
+ const testsSpent = { ...(state.sequentialTests ?? {}) };
+ const expiredReceipts: string[] = [];
+ for (const record of Object.values(state.receiptStates)) {
+ if (record.status === 'evaluated') {
+ record.status = 'expired';
+ expiredReceipts.push(record.receiptId);
+ }
+ }
+ const resets = state.sequentialResets ?? [];
+ resets.push({ epoch: closedEpoch, at: now, reason, testsSpent, expiredReceipts: [...expiredReceipts].sort() });
+ state.sequentialResets = resets;
+ state.sequentialTests = {};
+ state.evidenceEpoch = closedEpoch + 1;
+ state.evidenceEpochStartedAt = now;
+ atomicWriteJson(statePath(root), state);
+ return {
+ success: true,
+ reason: `evidence epoch ${closedEpoch} closed β€” ${Object.keys(testsSpent).length} test(s) archived, ${expiredReceipts.length} outstanding receipt(s) expired`,
+ closedEpoch,
+ newEpoch: state.evidenceEpoch,
+ testsArchived: Object.keys(testsSpent).length,
+ receiptsExpired: expiredReceipts.length,
+ };
+ });
+}
+
export async function registerFlywheelReceipt(
root: string,
receipt: FlywheelEvaluationReceipt,
@@ -363,6 +474,80 @@ export async function promoteFlywheelCandidate(
&& (!evidence.attestor || !options.approvedAttestors?.has(evidence.attestor))
) return { success: false, idempotent: false, reason: `unapproved evidence attestor for gate: ${term}` } satisfies PromotionResult;
}
+
+ // Strict sequential evidence (default ON). Two refusals, both explicit:
+ // 1. aggregate-only receipts (no pairedOutcomes) β€” the upstream-style
+ // "degrade to the base gate" fallback is exactly the hole this closes;
+ // 2. paired evidence that cannot clear the e-process at this test's
+ // allocated share of the family-wise alpha budget.
+ // Alpha is spent by LOOKING: the allocation is persisted even when the
+ // verdict refuses, and a retried receipt reuses its index.
+ if (options.requirePairedEvidence !== false) {
+ const rawOutcomes = receipt.payload.pairedOutcomes;
+ if (!rawOutcomes || rawOutcomes.length === 0) {
+ return {
+ success: false,
+ idempotent: false,
+ reason: 'receipt carries aggregate-only evidence (no task-level pairedOutcomes) β€” re-evaluate the candidate with a current ruflo, or pass the explicit aggregate-evidence override',
+ } satisfies PromotionResult;
+ }
+ // Epoch-boundary enforcement (ADR-381 Β§2): a receipt whose OWN evidence
+ // predates the current epoch's start must be refused even if it was
+ // registered after the reset β€” registration time is not evidence time.
+ // Without this check a receipt built from a stale/cached evaluation (or
+ // any future path that decouples evaluation from immediate
+ // registration) could be presented into the fresh, low-alpha epoch β€”
+ // exactly the index-shopping the reset mechanism exists to prevent.
+ if (state.evidenceEpochStartedAt !== undefined) {
+ const issuedAtMs = Date.parse(receipt.payload.issuedAt);
+ if (!Number.isNaN(issuedAtMs) && issuedAtMs < state.evidenceEpochStartedAt) {
+ return {
+ success: false,
+ idempotent: false,
+ reason: `receipt evidence (issued ${receipt.payload.issuedAt}) predates the current evidence epoch ${state.evidenceEpoch ?? 0} (started ${new Date(state.evidenceEpochStartedAt).toISOString()}) β€” re-evaluate the candidate to produce fresh evidence`,
+ } satisfies PromotionResult;
+ }
+ }
+ // Consistency with heldOutDeltas was already enforced by verifyFlywheelReceipt.
+ const outcomes = rawOutcomes.map((o) => ({
+ taskId: o.taskId,
+ baselineScore: Number(o.baselineScore),
+ candidateScore: Number(o.candidateScore),
+ }));
+ if (!state.sequentialTests) state.sequentialTests = {};
+ const priorIndex = state.sequentialTests[receiptId];
+ const testIndex = priorIndex ?? (Object.keys(state.sequentialTests).length + 1);
+ // Size pre-flight (ADR-381 Β§4): refuse BEFORE allocating an alpha index
+ // when the receipt cannot clear this test's threshold even on a perfect
+ // all-win sweep. Sample size is ancillary β€” independent of the outcomes
+ // β€” so this refusal looks at no evidence and spends no alpha.
+ if (priorIndex === undefined) {
+ const minPairs = minInformativePairsToClear(testIndex, {
+ alphaTotal: options.sequentialAlphaTotal ?? DEFAULT_ALPHA_TOTAL,
+ lambda: options.sequentialLambda ?? DEFAULT_LAMBDA,
+ });
+ if (outcomes.length < minPairs) {
+ return {
+ success: false,
+ idempotent: false,
+ reason: `receipt cannot clear sequential evidence at test ${testIndex}: ${outcomes.length} paired task(s) < ${minPairs} required even on a perfect sweep β€” no alpha spent; re-evaluate with a larger promotion holdout (ADR-381)`,
+ } satisfies PromotionResult;
+ }
+ }
+ const verdict = sequentialEvidenceVerdict(outcomes, testIndex, {
+ alphaTotal: options.sequentialAlphaTotal ?? DEFAULT_ALPHA_TOTAL,
+ lambda: options.sequentialLambda ?? DEFAULT_LAMBDA,
+ });
+ if (priorIndex === undefined) state.sequentialTests[receiptId] = testIndex;
+ if (!verdict.significant) {
+ if (priorIndex === undefined) atomicWriteJson(statePath(root), state); // record the alpha spend
+ return {
+ success: false,
+ idempotent: false,
+ reason: `insufficient sequential evidence: e-value ${verdict.eValue.toFixed(3)} < ${verdict.threshold.toFixed(1)} at test ${verdict.testIndex} (alpha ${verdict.alphaAllocated.toFixed(5)} of family-wise ${(options.sequentialAlphaTotal ?? DEFAULT_ALPHA_TOTAL).toFixed(2)}; ${verdict.informativePairs}/${verdict.totalPairs} informative pairs)`,
+ } satisfies PromotionResult;
+ }
+ }
if (options.faultAt === 'before-commit') throw new Error('fault injection: before-commit');
const transactionId = uuidV7(now);
diff --git a/v3/@claude-flow/cli/src/services/harness-flywheel-generations.ts b/v3/@claude-flow/cli/src/services/harness-flywheel-generations.ts
index 5291d46565..b69351cdcc 100644
--- a/v3/@claude-flow/cli/src/services/harness-flywheel-generations.ts
+++ b/v3/@claude-flow/cli/src/services/harness-flywheel-generations.ts
@@ -24,6 +24,12 @@ import {
runRealEvolveRound, reconstructLineage, detectPlateau, mutationEffectiveness,
type EvolveReceiptBundle, type LineageTelemetry, type PlateauReport, type MutationStat,
} from './evolve-proof.js';
+import {
+ DEFAULT_ALPHA_TOTAL,
+ alphaForTest,
+ minInformativePairsToClear,
+ remainingAlphaBudget,
+} from './flywheel-sequential-evidence.js';
import { harvestSelfSupervisedTasks, type HarvestPattern } from './harness-corpus-harvester.js';
import { applyChampionParams, rollbackActivePolicy } from '../config/harness-feedback-applier.js';
import { DEFAULT_CONFIG, type RetrievalConfig, type RankedItem } from './harness-flywheel.js';
@@ -32,8 +38,12 @@ export const FLYWHEEL_DIR = ['.claude-flow', 'flywheel'];
export const FROZEN_CORPUS = 'harvested-selfsup-frozen-v1';
const SERVED_FILE = 'served.json';
const ATTEMPTS_FILE = 'attempts.jsonl';
+const ATTEMPTS_LOCK_FILE = 'attempts.lock';
const ANCHOR_TOL = 0.02;
const CANARY_CATASTROPHE = 0.5;
+const ATTEMPTS_LOCK_TIMEOUT_MS = 10_000;
+const ATTEMPTS_LOCK_STALE_MS = 60_000;
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
export interface AnchorTask { id: string; q: string; labels: string[]; }
export interface GenerationDeps {
@@ -85,6 +95,44 @@ function appendPromotion(root: string, b: EvolveReceiptBundle): void {
try { fs.mkdirSync(dir(root), { recursive: true }); fs.writeFileSync(path.join(dir(root), `generation-${b.generation}.json`), JSON.stringify(b, null, 2) + '\n', 'utf-8'); } catch { /* */ }
}
+/**
+ * Serialize the read-testIndex β†’ build-bundle β†’ append critical section
+ * (ADR-381 Β§3): attempts.jsonl's length IS the sequential-evidence test
+ * stream position, so two concurrent runFlywheelGeneration calls reading it
+ * before either appends would be assigned the SAME test index and spend the
+ * SAME alpha_k twice β€” silently doubling the true false-promotion rate the
+ * e-process math is meant to bound. Mirrors flywheel-transaction.ts's
+ * withStateLock (O_EXCL lock file, stale-lock takeover, bounded retry).
+ */
+async function withAttemptsLock<T>(root: string, fn: () => T): Promise<T> {
+ fs.mkdirSync(dir(root), { recursive: true });
+ const lock = path.join(dir(root), ATTEMPTS_LOCK_FILE);
+ const deadline = Date.now() + ATTEMPTS_LOCK_TIMEOUT_MS;
+ for (;;) {
+ try {
+ const fd = fs.openSync(lock, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+ fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }), 'utf-8');
+ fs.closeSync(fd);
+ try {
+ return fn();
+ } finally {
+ try { fs.unlinkSync(lock); } catch { /* lock already gone */ }
+ }
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+ try {
+ const stat = fs.lstatSync(lock);
+ if (Date.now() - stat.mtimeMs > ATTEMPTS_LOCK_STALE_MS) {
+ fs.unlinkSync(lock);
+ continue;
+ }
+ } catch { /* raced with owner */ }
+ if (Date.now() >= deadline) throw new Error('timed out acquiring flywheel attempts lock');
+ await delay(5);
+ }
+ }
+}
+
/** The current operating champion (last promotion's config), or defaults. */
export function currentChampion(root: string): { config: Record<string, number>; hash: string | null; generation: number } {
const p = loadPromotions(root);
@@ -241,9 +289,19 @@ export async function runFlywheelGeneration(root: string, deps: GenerationDeps):
// visibility): if this stays ~0 while benchmark Ξ” > 0, the loop is overfitting.
const humanRelevanceDelta = candAnchor - baseAnchor;
- const bundle = runRealEvolveRound({ baseline: baseline as unknown as Record<string, number>, candidate: cand as unknown as Record<string, number>, holdout, generation, parent, branch: 'main', now: deps.now, redblue, canaryRollbackRate, humanRelevanceDelta, humanEvalHash: deps.humanEvalHash, corpus: FROZEN_CORPUS });
- appendAttempt(root, bundle);
- if (bundle.decisionReceipt.promoted) appendPromotion(root, bundle);
+ // ADR-381 Β§3 β€” every generation is one look at the same adaptive stream;
+ // attempts.jsonl IS the stream record, so this attempt's 1-based position
+ // is its sequential test index. Promoted or not, the next tick's index
+ // moves on (this bundle is appended below). Read-index, build, and append
+ // happen inside withAttemptsLock so two concurrent generations can never
+ // be assigned β€” and spend alpha on β€” the same test index.
+ const bundle = await withAttemptsLock(root, () => {
+ const testIndex = loadAttempts(root).length + 1;
+ const b = runRealEvolveRound({ baseline: baseline as unknown as Record<string, number>, candidate: cand as unknown as Record<string, number>, holdout, generation, parent, branch: 'main', now: deps.now, redblue, canaryRollbackRate, humanRelevanceDelta, humanEvalHash: deps.humanEvalHash, corpus: FROZEN_CORPUS, sequential: { testIndex } });
+ appendAttempt(root, b);
+ if (b.decisionReceipt.promoted) appendPromotion(root, b);
+ return b;
+ });
return {
ran: true, reason: bundle.decisionReceipt.reason, generation, promoted: bundle.decisionReceipt.promoted,
@@ -318,6 +376,20 @@ export interface FlywheelStatus {
humanEvalHash: string | null; // frozen human eval set the deltas are against
served: ServedState;
champion: { config: Record<string, number>; hash: string | null };
+ /**
+ * ADR-381 Β§3 β€” visibility into the sequential alpha stream so budget
+ * exhaustion reads as a plateau signal, not a mystery: the next test's
+ * index, its allocated alpha and e-value threshold, the minimum all-win
+ * informative pairs needed to clear it, and the family-wise budget left.
+ */
+ sequential: {
+ nextTestIndex: number;
+ alphaAllocatedNext: number;
+ thresholdNext: number;
+ minInformativePairsNext: number;
+ remainingAlphaBudget: number;
+ alphaTotal: number;
+ };
}
/** Reconstruct the persisted lineage + telemetry for a status endpoint / CLI. */
@@ -337,5 +409,17 @@ export function flywheelStatus(root: string): FlywheelStatus {
humanEvalHash: promotions.length ? (promotions[promotions.length - 1].humanEvalHash ?? null) : null,
served: servedChampion(root),
champion: { config: champ.config, hash: champ.hash },
+ sequential: (() => {
+ const nextTestIndex = attempts.length + 1;
+ const alphaAllocatedNext = alphaForTest(nextTestIndex);
+ return {
+ nextTestIndex,
+ alphaAllocatedNext,
+ thresholdNext: 1 / alphaAllocatedNext,
+ minInformativePairsNext: minInformativePairsToClear(nextTestIndex),
+ remainingAlphaBudget: remainingAlphaBudget(attempts.length),
+ alphaTotal: DEFAULT_ALPHA_TOTAL,
+ };
+ })(),
};
}
diff --git a/v3/@claude-flow/cli/src/services/harness-flywheel.ts b/v3/@claude-flow/cli/src/services/harness-flywheel.ts
index 06adb29bb7..15a8e5d48f 100644
--- a/v3/@claude-flow/cli/src/services/harness-flywheel.ts
+++ b/v3/@claude-flow/cli/src/services/harness-flywheel.ts
@@ -35,6 +35,7 @@ import {
readFlywheelTransactionState,
registerFlywheelReceipt,
} from './flywheel-transaction.js';
+import { minInformativePairsToClear } from './flywheel-sequential-evidence.js';
import { runBoundedPool } from './bounded-worker-pool.js';
export interface RetrievalConfig { alpha: number; subjectWeight: number; mmrLambda: number; bodyWeight: number; typePenaltyFactor: number; }
@@ -88,6 +89,14 @@ export interface FlywheelResult {
receipt?: FlywheelEvaluationReceipt;
promotable?: boolean;
legacyDeprecation?: boolean;
+ /**
+ * ADR-381 Β§4 soft pre-flight: whether this evaluation's promotion holdout
+ * can clear the sequential-evidence threshold at the ledger's next test
+ * index even on a perfect all-win sweep. viable:false does NOT block the
+ * evaluation (learn value stands; the gate refuses size-inviable receipts
+ * without alpha spend) β€” it tells the operator promotion is out of reach.
+ */
+ sequentialPreflight?: { viable: boolean; heldSize: number; minPairsRequired: number; nextTestIndex: number };
}
const EPS = 1e-3;
@@ -251,6 +260,13 @@ export async function evaluateFlywheelCandidate(projectRoot: string, deps: Flywh
// resampling, not ride on one lucky task. FINAL accept = loop-accept AND
// significant, so the ledger's accepted subsequence stays monotonic + real.
const heldDeltas = held.map((t) => heldScoreFor(candidate, t) - heldScoreFor(baseline, t));
+ // Task-level paired outcomes β€” the evidence the promotion authority now
+ // requires; must stay in the exact order of heldDeltas.
+ const pairedOutcomes = held.map((t) => ({
+ taskId: t.id,
+ baselineScore: heldScoreFor(baseline, t),
+ candidateScore: heldScoreFor(candidate, t),
+ }));
const deltaCILow = bootstrapDeltaCILow(heldDeltas);
const significant = deltaCILow > 0;
const provisionalGates = Object.fromEntries(Object.entries(result.verdict?.terms ?? {}).map(([k, v]) => [k, v.pass]));
@@ -277,6 +293,7 @@ export async function evaluateFlywheelCandidate(projectRoot: string, deps: Flywh
baselineScore,
candidateScore,
heldOutDeltas: heldDeltas,
+ pairedOutcomes,
frozenAnchorRegression: guardRegressed ? 1 : 0,
gates: provisionalGates,
resourceEvidence: {
@@ -325,6 +342,26 @@ export async function evaluateFlywheelCandidate(projectRoot: string, deps: Flywh
await registerFlywheelReceipt(projectRoot, receipt, deps.now ?? Date.now());
const finalAccept = result.accepted && significant && receipt.payload.decision === 'accepted';
+ // Soft pre-flight (ADR-381 Β§4): can the held half of the objective clear
+ // the sequential-evidence threshold at the ledger's NEXT test index even
+ // on a perfect all-win sweep? Annotate β€” never block: evaluation has
+ // learn value regardless, anchors may legitimately be small (β‰₯4), and
+ // the promote gate refuses size-inviable receipts without spending alpha.
+ // Read as LATE as possible (after registration, right before returning)
+ // to minimize β€” but not eliminate β€” the window in which a concurrent
+ // promoteFlywheelCandidate call can move the ledger's next test index.
+ // This is inherently ADVISORY, not authoritative: promoteFlywheelCandidate
+ // (under its own lock) is the sole authority for index allocation, so a
+ // promotion racing between this read and an operator's subsequent
+ // `flywheel promote` call can still flip the outcome. Callers must not
+ // treat `promotable: true` as a guarantee β€” only as "was viable as of
+ // this evaluation".
+ const postState = readFlywheelTransactionState(projectRoot);
+ const nextTestIndex = Object.keys(postState.sequentialTests ?? {}).length + 1;
+ const heldSize = Math.max(1, Math.round(objective.length * 0.5)); // held half per split(objective, 0.5)
+ const minPairsRequired = minInformativePairsToClear(nextTestIndex);
+ const sequentialPreflight = { viable: heldSize >= minPairsRequired, heldSize, minPairsRequired, nextTestIndex };
+
const entry: LedgerEntry = {
ts: deps.now ?? Date.now(),
corpusVersion: blended.version, corpusHash: blended.corpusHash,
@@ -344,7 +381,9 @@ export async function evaluateFlywheelCandidate(projectRoot: string, deps: Flywh
baselineScore, candidateScore, delta: candidateScore - baselineScore,
anchorRegressed, championRef: finalAccept ? refOf(candidate) : undefined,
corpusVersion: blended.version, candidateConfig: candidate,
- receiptId: receipt.payload.receiptId, receipt, promotable: finalAccept && !!receipt.signature,
+ receiptId: receipt.payload.receiptId, receipt,
+ promotable: finalAccept && !!receipt.signature && sequentialPreflight.viable,
+ sequentialPreflight,
};
} catch (e) {
return { ran: false, reason: `error: ${(e as Error)?.message ?? e}` };
diff --git a/v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md b/v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md
new file mode 100644
index 0000000000..d83821a6d4
--- /dev/null
+++ b/v3/docs/adr/ADR-381-sequential-promotion-evidence-governance.md
@@ -0,0 +1,64 @@
+# ADR-381 β€” Sequential Promotion Evidence: Ξ±-Stream Governance, Reset Epochs, and accept/v2+seq
+
+- **Status**: Proposed
+- **Date**: 2026-08-10
+- **Related**: ADR-176 (stateful flywheel / single-round proof-of-mechanism), ADR-322 (flywheel receipt protocol + atomic promotion transaction), ADR-150 (MetaHarness optional/removable augmentation), PR #2956 (strict sequential promotion evidence β€” the mechanism this ADR governs)
+- **Prompted by**: the August-10 MetaHarness integration review, which found that per-candidate significance testing "does not control error across an adaptive candidate stream", and the follow-on question PR #2956 deliberately left open: what happens when the family-wise Ξ± budget is spent, and which promotion streams are covered.
+
+## Context
+
+PR #2956 added the mechanism: evaluation receipts carry task-level `pairedOutcomes`, and `promoteFlywheelCandidate` (the ADR-322 authority) requires an anytime-valid e-process verdict at an allocated per-test Ξ±, with allocation `Ξ±_k = Ξ±_total Β· 6/(π²kΒ²)` so that `Ξ£ Ξ±_k = Ξ±_total = 5%` across arbitrarily many adaptively-chosen candidates. The 1,000-null-simulation acceptance test measures 0.6% family-wise false promotion.
+
+Three governance questions were intentionally deferred:
+
+1. **Budget exhaustion.** The spend ledger (`sequentialTests`) only grows. As k rises, `Ξ±_k` shrinks polynomially and the e-value threshold `1/Ξ±_k` rises; a long-lived project eventually cannot promote anything. That is the mathematics working as designed β€” but without a legitimate recovery path it converts a safety property into a dead end, and operators will route around a gate that cannot be reopened, which is worse than a governed reset.
+
+2. **Stream identity.** What is "the stream" the family-wise guarantee quantifies over? Receipt `lineageId` is unsuitable: it defaults to a fresh UUIDv7 per evaluation run, so scoping the ledger by `lineageId` would give every receipt its own stream at test 1 and silently void the control.
+
+3. **Coverage.** The ADR-176 self-supervised generations loop (`runFlywheelGeneration`, driven by the daemon) is the *most active* adaptive candidate stream in the system β€” one candidate per tick, compounding on a persisted champion, with serve-after-shadow β€” and it still tested each generation at a fresh Ξ±=0.05. Extending the control there was deferred because it changes what `verifyReceiptBundle` must replay.
+
+## Decision
+
+### 1. The promotion ledger IS the stream
+
+The Ξ± ledger is scoped to the ADR-322 **transaction state** (one per project root): one ledger head, one champion chain, one evidence stream. This matches the statistical object β€” every candidate tested against that chain is one look at the same adaptive process β€” and is immune to the auto-generated-`lineageId` trap. No per-lineage sub-streams.
+
+### 2. Reset is an explicit, auditable governance action β€” an *evidence epoch*
+
+`resetSequentialEvidence(root, { confirm, reason })` starts a new evidence epoch:
+
+- **Requires** `confirm: true` and a non-empty human `reason`. At the CLI/MCP surface it passes through the same ADR-324 policy gate as promotion (`metaharness.evidence.reset`, destructive).
+- **Expires all outstanding `evaluated` receipts.** The new epoch may only promote receipts evaluated *after* the reset β€” this structurally enforces the fresh-data requirement: you cannot reopen the budget and replay old evidence against it. (Under the null, evidence evaluated in the old epoch has already been "looked at"; carrying it into a fresh budget would be exactly the peeking the e-process exists to prevent.)
+- **Archives the spend** into an append-only `sequentialResets` audit trail (`epoch`, timestamp, reason, tests spent, receipts expired) and increments `evidenceEpoch`. Nothing is deleted; a reviewer can reconstruct every epoch's spend.
+- **Guarantee after reset**: family-wise false-promotion probability is ≀ Ξ±_total *per epoch*, and epochs are separated by an explicit, logged human decision with fresh evaluation data. That is the honest statement of what a governed reset can promise β€” the per-epoch bound is the invariant; the audit trail is what makes the epoch boundary a real governance event rather than a bypass.
+
+Legitimate reasons to reset: baseline rollback, corpus replacement, a policy-schema migration, or a deliberate "we accept a new 5% budget for a new optimization campaign" decision. The `reason` field is free text precisely so the audit trail captures intent.
+
+### 3. The ADR-176 generations loop adopts the control: `accept/v2+seq`
+
+- `assembleBundle` accepts an optional `sequential` input (`testIndex`, `alphaTotal`, `lambda`). When present, the promotion rule version recorded in the bundle is **`accept/v2+seq`**, the e-process verdict over the bundle's own embedded per-task holdout becomes an additional conjunct (`promoted = accept() AND bootstrap-significant AND sequential-significant`), and the full verdict (`testIndex`, `alphaAllocated`, `eValue`, `threshold`, `informativePairs`, `significant`) is embedded in the bundle.
+- **Replayability is preserved**: `verifyReceiptBundle` recomputes the e-process from the embedded holdout and the recorded `testIndex`/`alphaTotal`/`lambda`, for v2 bundles, and continues to verify v1 bundles under v1 semantics. A lineage may contain both β€” the rule version is pinned per bundle, which is the whole point of versioned rules.
+- **Test index** = number of prior attempts in the persisted stream (`attempts.jsonl`) + 1. Every generation is one look, promoted or not, which is already exactly what `attempts.jsonl` records.
+- **Fresh samples per test** come free: each tick harvests a fresh self-supervised corpus from the evolving store.
+- **Interaction with plateau**: as k grows the threshold rises and the promotion rate falls; `detectPlateau` will report `local-optimum`/`optimizer-failure` more readily. This is correct β€” an exhausted budget *is* a plateau signal. `flywheelStatus` surfaces the remaining budget and the next test's threshold so the exhaustion is visible, not mysterious. Recovery for this loop is archival of the flywheel dir (a new stream with a new store state), which the status output points at; a finer-grained governed reset can be added later if operators need it.
+
+### 4. Pre-flight power check β€” annotate evaluations, protect the gate
+
+`minInformativePairsToClear(testIndex, cfg)` = ⌈ln(1/Ξ±_k)/ln(1+Ξ»)βŒ‰ is exported from the sequential-evidence module, and the check applies at two layers with different strengths:
+
+- **Evaluation (soft)**: `evaluateFlywheelCandidate` computes the next test index from the transaction state before running and *annotates* the result (`sequentialPreflight: { viable, heldSize, minPairsRequired, nextTestIndex }`) when the promotion holdout cannot reach the threshold even on a perfect sweep. It does **not** refuse: project anchors may legitimately be as small as 4 tasks, evaluation has learn value independent of promotion (ledger, telemetry), and unsigned local receipts cannot promote anyway. Blocking evaluation would turn `flywheel run` into a permanent no-op for small projects.
+- **Promotion (hard, Ξ±-free)**: `promoteFlywheelCandidate` refuses a receipt whose paired-outcome count is below the minimum for the next test index **before allocating an Ξ± index**. This costs no budget and is statistically sound: the refusal depends only on sample *size*, which is ancillary β€” independent of the outcomes β€” so no evidence has been "looked at". A doomed receipt therefore cannot waste Ξ±, and the refusal message states exactly how many paired tasks the next test requires.
+
+## Consequences
+
+- **State file**: `FlywheelTransactionState` gains `evidenceEpoch` (default 0) and `sequentialResets` (default empty). Both optional-on-read; version stays 1; pre-existing state needs no migration.
+- **Operators** get `flywheel evidence-reset --reason … --confirm` (CLI) and `metaharness_flywheel { operation: "evidence-reset" }` (MCP). Both refuse without a reason.
+- **The daemon loop** becomes strictly more conservative: late-stream generations need overwhelming evidence to promote. Serving safety was never dependent on this (shadow delay + drift canary + rollback are unchanged); what changes is that a long run of marginal "improvements" can no longer compound into the champion chain.
+- **Not covered**: cross-project or cross-tenant Ξ± coordination (each project root is its own stream), and confidence-interval-style effect-size reporting (the e-value is a likelihood ratio, not an interval). Both are out of scope until a concrete need appears.
+
+## Acceptance evidence
+
+- Reset semantics under test: outstanding receipts expired, spend archived, epoch incremented, new-epoch receipts promote from test 1, expired receipts refused.
+- v2 bundles: promoted only when all three conjuncts hold; `verifyReceiptBundle` replays v2 (and still v1) from embedded evidence alone; tampering with the recorded sequential verdict is detected.
+- Pre-flight: an undersized holdout is annotated at evaluation time and refused at the gate without Ξ± spend; a viable holdout allocates and proceeds.
+- The PR #2956 null-simulation guarantee is unchanged (per epoch).
diff --git a/v3/pnpm-lock.yaml b/v3/pnpm-lock.yaml
index c94dd977c1..73feaca485 100644
--- a/v3/pnpm-lock.yaml
+++ b/v3/pnpm-lock.yaml
@@ -44,7 +44,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/aidefence':
dependencies:
@@ -110,7 +110,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/cli':
dependencies:
@@ -138,12 +138,6 @@ importers:
'@iarna/toml':
specifier: ^2.2.5
version: 2.2.5
- '@metaharness/darwin':
- specifier: ^0.8.0
- version: 0.8.0
- '@metaharness/flywheel':
- specifier: ^0.1.7
- version: 0.1.7
'@metaharness/router':
specifier: ^0.3.2
version: 0.3.2
@@ -196,6 +190,15 @@ importers:
'@claude-flow/memory':
specifier: ^3.0.0-alpha.21
version: link:../memory
+ '@metaharness/darwin':
+ specifier: ~0.8.3
+ version: 0.8.3
+ '@metaharness/flywheel':
+ specifier: ~0.1.10
+ version: 0.1.10
+ '@metaharness/radio':
+ specifier: ~0.1.0
+ version: 0.1.0
'@napi-rs/keyring':
specifier: 1.3.0
version: 1.3.0
@@ -262,7 +265,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/deployment':
dependencies:
@@ -275,7 +278,7 @@ importers:
version: 25.0.2([email protected])
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/embeddings':
dependencies:
@@ -325,7 +328,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/hooks':
dependencies:
@@ -360,7 +363,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/integration':
dependencies:
@@ -405,7 +408,7 @@ importers:
version: 8.18.1
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/memory':
dependencies:
@@ -457,7 +460,7 @@ importers:
devDependencies:
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/plugin-agent-federation':
dependencies:
@@ -507,7 +510,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/plugins':
dependencies:
@@ -535,7 +538,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/providers':
dependencies:
@@ -560,7 +563,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/security':
dependencies:
@@ -580,7 +583,7 @@ importers:
devDependencies:
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/shared':
dependencies:
@@ -614,7 +617,7 @@ importers:
version: 7.2.0
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
ws:
specifier: ^8.16.0
version: 8.19.0
@@ -626,7 +629,7 @@ importers:
devDependencies:
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
'@claude-flow/testing':
devDependencies:
@@ -644,7 +647,7 @@ importers:
version: 5.9.3
vitest:
specifier: '>=4.1.0'
- version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ version: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
packages:
@@ -1752,16 +1755,23 @@ packages:
hasBin: true
dev: false
- /@metaharness/[email protected]:
- resolution: {integrity: sha512-Pgefr/es0Btofh7GxQrOAg/i43ZKcLUfeD9rndOAkpA8s3ZYohSmfLerJLNsGOOKc2eTvmmauljl8QEVmKC2dw==}
+ /@metaharness/[email protected]:
+ resolution: {integrity: sha512-v5Ph7y9U6nqfvWajOjJiSuQDjPwvCKwOui793cSGUxIYUcfMoVoMzDfEDxOczFU61z0UUd7lD0I1b2zl+eYnag==}
engines: {node: '>=20.0.0'}
hasBin: true
requiresBuild: true
dev: false
+ optional: true
+
+ /@metaharness/[email protected]:
+ resolution: {integrity: sha512-yrLXDXNdf4jKqHlW6QZw3Cy5T0eMMjjaPqn1XB717/Xx/y0Iv9R03W0OhMEiR/kfqMNebRBW1fi6D7inStEyqA==}
+ dev: false
- /@metaharness/[email protected]:
- resolution: {integrity: sha512-am7dROkjyS1Zkms3TOcn2LVHjwMLQXPJ6Pu1aP55q40vWJLRONGdGvnrcBL/VhMFqjQrVB57lmSn2E+s5CSZwA==}
+ /@metaharness/[email protected]:
+ resolution: {integrity: sha512-m1GCeGCbjo7h5OLMCgb2VZFbhY6aHP5x28q0j/AFqXRWwStt5/Z+sWMuGNaNKVtnB7PGueNbtVoxLzMQ53rrFg==}
+ requiresBuild: true
dev: false
+ optional: true
/@metaharness/[email protected]:
resolution: {integrity: sha512-JaAk6bs3xA7Ks5RnAcZoxI3WfzpYL+Bk262SCI07w82BDOA7C6VxwGM63F7b86lRTKUVjTEnSqf7QZ3uyElT/g==}
@@ -6781,7 +6791,7 @@ packages:
obug: 2.1.1
std-env: 4.1.0
tinyrainbow: 3.1.0
- vitest: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
+ vitest: 4.1.8(@opentelemetry/[email protected])(@types/[email protected])(@vitest/[email protected])([email protected])
dev: true
@@ -6809,7 +6819,7 @@ packages:
'@vitest/spy': 4.1.8
estree-walker: 3.0.3
magic-string: 0.30.21
- vite: 7.3.0(@types/[email protected])([email protected])
+ vite: 7.3.0(@types/[email protected])([email protected])
dev: true
@@ -10383,7 +10393,7 @@ packages:
optional: true
dependencies:
'@metaharness/darwin': 0.2.8
- '@metaharness/flywheel': 0.1.7
+ '@metaharness/flywheel': 0.1.10
'@metaharness/redblue': 0.1.4
'@metaharness/weight-eft': 0.1.1
kolorist: 1.8.0
@@ -13044,6 +13054,7 @@ packages:
yaml: 2.8.2
optionalDependencies:
fsevents: 2.3.3
+ dev: false
resolution: {integrity: sha512-flY6ScbCIt9HThs+C5HS7jvGOB560DJtk/Z15IQROTA6zEy49Nh8T/dofWTQL+n3vswqn87sbJNiuqw1SDp5Ig==}
@@ -13175,7 +13186,7 @@ packages:
tinyexec: 1.0.2
tinyglobby: 0.2.15
tinyrainbow: 3.1.0
- vite: 7.3.0(@types/[email protected])([email protected])
+ vite: 7.3.0(@types/[email protected])([email protected])
why-is-node-running: 2.3.0
transitivePeerDependencies:
- msw