@claude-flow/cli 3.34.0 → 3.36.0

package/dist/src/services/flywheel-sequential-evidence.js

@@ -0,0 +1,148 @@
+/**
+ * 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;
+/**
+ * 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, alphaTotal = DEFAULT_ALPHA_TOTAL) {
+    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, testIndex, config = {}) {
+    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, config = {}) {
+    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, alphaTotal = DEFAULT_ALPHA_TOTAL) {
+    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);
+}
+/**
+ * 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, heldOutDeltas, tolerance = 1e-9) {
+    const reasons = [];
+    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();
+    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 };
+}
+//# sourceMappingURL=flywheel-sequential-evidence.js.map

package/dist/src/services/flywheel-transaction.d.ts

@@ -35,6 +35,51 @@ 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 {
     success: boolean;
@@ -55,11 +100,37 @@ 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';
 }
 export declare function readFlywheelTransactionState(root: string): FlywheelTransactionState;
 export declare function readFlywheelReceipt(root: string, receiptId: string): FlywheelEvaluationReceipt | null;
+/**
+ * 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 declare function resetSequentialEvidence(root: string, options: {
+    confirm: boolean;
+    reason: string;
+    now?: number;
+}): Promise<EvidenceResetResult>;
 export declare function registerFlywheelReceipt(root: string, receipt: FlywheelEvaluationReceipt, now?: number): Promise<ReceiptState>;
 export declare function recoverFlywheelMaterialization(root: string, opts?: Pick<PromoteOptions, 'now' | 'applyFn'>): Promise<PromotionResult>;
 export declare function promoteFlywheelCandidate(root: string, receiptId: string, options: PromoteOptions): Promise<PromotionResult>;

package/dist/src/services/flywheel-transaction.js

@@ -10,6 +10,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { applyChampionParams } from '../config/harness-feedback-applier.js';
 import { GENESIS_LEDGER_HEAD, canonicalizeJcs, sha256Ref, uuidV7, verifyFlywheelReceipt, } from './flywheel-receipt.js';
+import { DEFAULT_ALPHA_TOTAL, DEFAULT_LAMBDA, minInformativePairsToClear, sequentialEvidenceVerdict, } from './flywheel-sequential-evidence.js';
 const STATE_VERSION = 1;
 const STATE_DIR = ['.claude-flow', 'flywheel-v1'];
 const STATE_FILE = 'transaction-state.json';
@@ -147,6 +148,50 @@ export function readFlywheelReceipt(root, receiptId) {
         return null;
     }
 }
+/**
+ * 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, options) {
+    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 = [];
+        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, receipt, now = Date.now()) {
     ensureDir(root);
     validateReceiptId(receipt.payload.receiptId);
@@ -287,6 +332,82 @@ export async function promoteFlywheelCandidate(root, receiptId, options) {
                 && (!evidence.attestor || !options.approvedAttestors?.has(evidence.attestor)))
                 return { success: false, idempotent: false, reason: `unapproved evidence attestor for gate: ${term}` };
         }
+        // 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',
+                };
+            }
+            // 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`,
+                    };
+                }
+            }
+            // 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)`,
+                    };
+                }
+            }
+            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)`,
+                };
+            }
+        }
         if (options.faultAt === 'before-commit')
             throw new Error('fault injection: before-commit');
         const transactionId = uuidV7(now);

package/dist/src/services/harness-flywheel-generations.d.ts

@@ -109,6 +109,20 @@ export interface FlywheelStatus {
         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. */
 export declare function flywheelStatus(root: string): FlywheelStatus;

package/dist/src/services/harness-flywheel-generations.js

@@ -21,6 +21,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { runRealEvolveRound, reconstructLineage, detectPlateau, mutationEffectiveness, } from './evolve-proof.js';
+import { DEFAULT_ALPHA_TOTAL, alphaForTest, minInformativePairsToClear, remainingAlphaBudget, } from './flywheel-sequential-evidence.js';
 import { harvestSelfSupervisedTasks } from './harness-corpus-harvester.js';
 import { applyChampionParams, rollbackActivePolicy } from '../config/harness-feedback-applier.js';
 import { DEFAULT_CONFIG } from './harness-flywheel.js';
@@ -28,8 +29,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) => new Promise((resolve) => setTimeout(resolve, ms));
 // ── Lineage store ─────────────────────────────────────────────────────────────
 function dir(root) { return path.join(root, ...FLYWHEEL_DIR); }
 function readJson(p) { try {
@@ -74,6 +79,51 @@ function appendPromotion(root, b) {
     }
     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(root, fn) {
+    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.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) {
     const p = loadPromotions(root);
@@ -270,10 +320,20 @@ export async function runFlywheelGeneration(root, deps) {
         // per-generation HUMAN-RELEVANCE delta on the frozen eval set (anti-overfitting
         // visibility): if this stays ~0 while benchmark Δ > 0, the loop is overfitting.
         const humanRelevanceDelta = candAnchor - baseAnchor;
-        const bundle = runRealEvolveRound({ baseline: baseline, candidate: cand, 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, candidate: cand, 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,
             delta: bundle.deltas.benchmark, significant: bundle.decisionReceipt.significant,
@@ -355,6 +415,18 @@ export function flywheelStatus(root) {
         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,
+            };
+        })(),
     };
 }
 //# sourceMappingURL=harness-flywheel-generations.js.map

package/dist/src/services/harness-flywheel.d.ts

@@ -60,6 +60,19 @@ 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;
+    };
 }
 export declare function retrievalPolicyNeighbors(base: RetrievalConfig): RetrievalConfig[];
 /**

package/dist/src/services/harness-flywheel.js

@@ -28,6 +28,7 @@ import { applyChampionParams } from '../config/harness-feedback-applier.js';
 import { appendLedger, bootstrapDeltaCILow } from './harness-improvement-ledger.js';
 import { createFlywheelReceipt, sha256Ref, } from './flywheel-receipt.js';
 import { readFlywheelTransactionState, registerFlywheelReceipt, } from './flywheel-transaction.js';
+import { minInformativePairsToClear } from './flywheel-sequential-evidence.js';
 import { runBoundedPool } from './bounded-worker-pool.js';
 export const DEFAULT_CONFIG = { alpha: 0.5, subjectWeight: 2.0, mmrLambda: 0.7, bodyWeight: 1.0, typePenaltyFactor: 1.0 };
 const EPS = 1e-3;
@@ -193,6 +194,13 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
         // 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]));
@@ -219,6 +227,7 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
             baselineScore,
             candidateScore,
             heldOutDeltas: heldDeltas,
+            pairedOutcomes,
             frozenAnchorRegression: guardRegressed ? 1 : 0,
             gates: provisionalGates,
             resourceEvidence: {
@@ -266,6 +275,25 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
         });
         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 = {
             ts: deps.now ?? Date.now(),
             corpusVersion: blended.version, corpusHash: blended.corpusHash,
@@ -283,7 +311,9 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
             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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.34.0",
+  "version": "3.36.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -123,24 +123,20 @@
     "@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.9.0",
+    "@metaharness/flywheel": "~0.1.10",
+    "@metaharness/radio": "~0.1.0",
+    "@metaharness/turn-credit": "~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/router": "^0.4.0",
     "metaharness": "^0.4.1"
   },
   "peerDependenciesMeta": {
-    "@metaharness/darwin": {
-      "optional": true
-    },
-    "@metaharness/flywheel": {
-      "optional": true
-    },
     "@metaharness/router": {
       "optional": true
     },