peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/loop/monotonic-guard.d.ts

@@ -0,0 +1,80 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.1
+ *
+ * Monotonic-improvement guard for the loop runtime. Compares adjacent
+ * cycles' per-evaluator scores (rescaled gateAction → 0..1) and
+ * returns a structured envelope indicating:
+ *
+ *   - status: 'pass' | 'warn' | 'block' | 'skip'
+ *   - regressions: per-evaluator score deltas where current < previous
+ *   - reason: human-readable summary
+ *
+ * Karpathy §2 Simplicity First: pure function, no IO, no new deps.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+/** Per-evaluator score row, derived from an `EvaluatorVerdictEnvelope`. */
+export interface MonotonicScoreRow {
+    readonly evaluator: string;
+    readonly score: number;
+    readonly gateAction: 'pass' | 'warn' | 'block';
+    readonly degraded: boolean;
+    /** ISO-8601 timestamp the verdict was recorded. */
+    readonly observedAt: string;
+}
+/** Cycle index — a single attempt at the loop. */
+export interface MonotonicCycle {
+    readonly cycle: number;
+    /** Per-evaluator score rows. Same evaluator appearing twice collapses
+     *  to the last entry (BC: deterministic, no merging surprises). */
+    readonly scores: readonly MonotonicScoreRow[];
+}
+export interface MonotonicRegression {
+    readonly evaluator: string;
+    readonly previousScore: number;
+    readonly currentScore: number;
+    readonly delta: number;
+}
+/** Result of a `checkMonotonicImprovement` call. */
+export interface MonotonicReport {
+    readonly status: 'pass' | 'warn' | 'block' | 'skip';
+    readonly ok: boolean;
+    readonly reason: string;
+    readonly threshold: number;
+    readonly previousCycle: number | null;
+    readonly currentCycle: number;
+    /** Per-evaluator regressions exceeding the threshold (sorted by |delta| desc). */
+    readonly regressions: readonly MonotonicRegression[];
+    /** Convenience boolean — true iff a regression exceeds the threshold. */
+    readonly monotonicityViolation: boolean;
+    /** Diagnostic hint surfaced as `MONOTONICITY_VIOLATION` in the CLI envelope. */
+    readonly code: 'MONOTONIC_OK' | 'MONOTONIC_NO_PREVIOUS' | 'MONOTONIC_VIOLATION' | 'MONOTONIC_INCOMPARABLE_EVALUATORS';
+}
+/** Convert an envelope-shaped verdict row to `MonotonicScoreRow`.
+ *  Pure helper, exported for the CLI layer. */
+export declare function toScoreRow(evaluator: string, gateAction: 'pass' | 'warn' | 'block', degraded: boolean, observedAtIso?: string): MonotonicScoreRow;
+/** Default threshold = 5% of [0,1] scale → 0.05. */
+export declare const DEFAULT_MONOTONIC_THRESHOLD = 0.05;
+export interface CheckMonotonicOptions {
+    /** Maximum regression permitted (in [0,1] scale). Default 0.05 (5%). */
+    readonly threshold?: number;
+    /** When provided, the guard logs the cycle id this report refers to. */
+    readonly nowIso?: string;
+}
+/** Compare `previous` against `current` and report monotonicity.
+ *
+ *  Rules (reflected in `tests/unit/loop/monotonic-guard.test.ts`):
+ *    - missing previous cycle → skip (`MONOTONIC_NO_PREVIOUS`)
+ *    - evaluators not present in both cycles → skip that evaluator
+ *    - score unchanged / up → ok
+ *    - score ↓ ≤ threshold → ok
+ *    - score ↓ > threshold → regression row + status 'block'
+ *      with `code = MONOTONICITY_VIOLATION`.
+ */
+export declare function checkMonotonicImprovement(previous: MonotonicCycle | null, current: MonotonicCycle, options?: CheckMonotonicOptions): MonotonicReport;
+/** Read `.peaks/_sub_agents/<sid>/shared/` cross-session signal — on
+ *  any IO error, return `null` so the guard never crashes on missing
+ *  cross-batch signal (per Slice C (b) case "跨 session 读
+ *  .peaks/_sub_agents/<sid>/shared/ 跨批 signal → 不 crash").
+ *  Pure helper; only present for the cross-session case. */
+export declare function loadCrossSessionSignal(projectRoot: string, sid: string): MonotonicCycle | null;

package/dist/services/loop/monotonic-guard.js

@@ -0,0 +1,232 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.1
+ *
+ * Monotonic-improvement guard for the loop runtime. Compares adjacent
+ * cycles' per-evaluator scores (rescaled gateAction → 0..1) and
+ * returns a structured envelope indicating:
+ *
+ *   - status: 'pass' | 'warn' | 'block' | 'skip'
+ *   - regressions: per-evaluator score deltas where current < previous
+ *   - reason: human-readable summary
+ *
+ * Karpathy §2 Simplicity First: pure function, no IO, no new deps.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+/** Score normalisation — gateAction maps to a 0..1 score:
+ *    pass  → 1.0
+ *    warn  → 0.5
+ *    block → 0.0
+ *
+ *  `degraded` (evaluator fell back to stub) collapses to 0.25 so the
+ *  guard never regresses past the boundary value; downstream callers
+ *  can surface `degraded` separately.
+ */
+function gateActionToScore(gateAction, degraded) {
+    if (degraded)
+        return 0.25;
+    if (gateAction === 'pass')
+        return 1.0;
+    if (gateAction === 'warn')
+        return 0.5;
+    return 0.0;
+}
+/** Strict-greater-than with a small epsilon to absorb FP rounding
+ *  (e.g. 1.0 - 0.95 = 0.04999999…). The boundary at exactly
+ *  threshold stays a pass. */
+const DELTA_EPSILON = 1e-9;
+/** Convert an envelope-shaped verdict row to `MonotonicScoreRow`.
+ *  Pure helper, exported for the CLI layer. */
+export function toScoreRow(evaluator, gateAction, degraded, observedAtIso = new Date(0).toISOString()) {
+    return {
+        evaluator,
+        score: gateActionToScore(gateAction, degraded),
+        gateAction,
+        degraded,
+        observedAt: observedAtIso
+    };
+}
+/** Default threshold = 5% of [0,1] scale → 0.05. */
+export const DEFAULT_MONOTONIC_THRESHOLD = 0.05;
+/** Compare `previous` against `current` and report monotonicity.
+ *
+ *  Rules (reflected in `tests/unit/loop/monotonic-guard.test.ts`):
+ *    - missing previous cycle → skip (`MONOTONIC_NO_PREVIOUS`)
+ *    - evaluators not present in both cycles → skip that evaluator
+ *    - score unchanged / up → ok
+ *    - score ↓ ≤ threshold → ok
+ *    - score ↓ > threshold → regression row + status 'block'
+ *      with `code = MONOTONICITY_VIOLATION`.
+ */
+export function checkMonotonicImprovement(previous, current, options = {}) {
+    const threshold = options.threshold ?? DEFAULT_MONOTONIC_THRESHOLD;
+    const at = options.nowIso ?? new Date().toISOString();
+    if (previous === null) {
+        return {
+            status: 'skip',
+            ok: true,
+            reason: 'no previous cycle recorded — monotonicity check is a no-op (first run is allowed to start anywhere)',
+            threshold,
+            previousCycle: null,
+            currentCycle: current.cycle,
+            regressions: [],
+            monotonicityViolation: false,
+            code: 'MONOTONIC_NO_PREVIOUS'
+        };
+    }
+    // Build previous evaluator → score lookup.
+    const prevMap = new Map();
+    for (const row of previous.scores)
+        prevMap.set(row.evaluator, row);
+    const regressions = [];
+    let comparable = 0;
+    for (const cur of current.scores) {
+        const prev = prevMap.get(cur.evaluator);
+        if (prev === undefined)
+            continue; // incomparable evaluator → skip
+        comparable++;
+        const delta = prev.score - cur.score; // positive = regression
+        if (delta > threshold + DELTA_EPSILON) {
+            regressions.push({
+                evaluator: cur.evaluator,
+                previousScore: prev.score,
+                currentScore: cur.score,
+                delta: round4(delta)
+            });
+        }
+    }
+    regressions.sort((a, b) => b.delta - a.delta);
+    if (comparable === 0) {
+        return {
+            status: 'skip',
+            ok: true,
+            reason: 'no evaluator appears in both the previous and current cycle — nothing to compare',
+            threshold,
+            previousCycle: previous.cycle,
+            currentCycle: current.cycle,
+            regressions: [],
+            monotonicityViolation: false,
+            code: 'MONOTONIC_INCOMPARABLE_EVALUATORS'
+        };
+    }
+    if (regressions.length > 0) {
+        const summary = regressions
+            .map((r) => `${r.evaluator} ${r.previousScore.toFixed(4)}→${r.currentScore.toFixed(4)} (Δ=${r.delta.toFixed(4)})`)
+            .join(', ');
+        return {
+            status: 'block',
+            ok: false,
+            reason: `MONOTONICITY_VIOLATION: ${regressions.length} evaluator(s) regressed beyond threshold ${threshold} (at ${at}): ${summary}`,
+            threshold,
+            previousCycle: previous.cycle,
+            currentCycle: current.cycle,
+            regressions,
+            monotonicityViolation: true,
+            code: 'MONOTONIC_VIOLATION'
+        };
+    }
+    return {
+        status: 'pass',
+        ok: true,
+        reason: `all ${comparable} evaluators held or improved (threshold ${threshold})`,
+        threshold,
+        previousCycle: previous.cycle,
+        currentCycle: current.cycle,
+        regressions: [],
+        monotonicityViolation: false,
+        code: 'MONOTONIC_OK'
+    };
+}
+function classifyFsError(err) {
+    const code = err?.code;
+    if (code === 'ENOENT')
+        return 'NOT_FOUND';
+    return 'IO_ERROR';
+}
+/** Read `.peaks/_sub_agents/<sid>/shared/` cross-session signal — on
+ *  any IO error, return `null` so the guard never crashes on missing
+ *  cross-batch signal (per Slice C (b) case "跨 session 读
+ *  .peaks/_sub_agents/<sid>/shared/ 跨批 signal → 不 crash").
+ *  Pure helper; only present for the cross-session case. */
+export function loadCrossSessionSignal(projectRoot, sid) {
+    // Lazily import so unit tests in non-windows environments don't pull
+    // node:fs through a static `import` (test envs stay small).
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    const path = require('node:path');
+    const sharedDir = path.join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
+    const readdir = (() => {
+        try {
+            return { ok: true, value: fs.readdirSync(sharedDir) };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readdir.ok)
+        return null; // missing dir or permission denied — both are no-ops.
+    const entries = readdir.value;
+    // Pick the highest cycle number from the filenames; tolerate garbage.
+    let best = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const cycle = parseInt(m[1] ?? '0', 10);
+        if (best === null || cycle > best)
+            best = cycle;
+    }
+    if (best === null)
+        return null;
+    const target = path.join(sharedDir, `cycle-${best}.json`);
+    const readFile = (() => {
+        try {
+            return { ok: true, value: fs.readFileSync(target, 'utf8') };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readFile.ok)
+        return null;
+    const parse = (() => {
+        try {
+            return { ok: true, value: JSON.parse(readFile.value) };
+        }
+        catch {
+            return { ok: false, reason: 'PARSE_ERROR' };
+        }
+    })();
+    if (!parse.ok)
+        return null;
+    const parsed = parse.value;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const cycleNo = typeof obj['cycle'] === 'number' ? obj['cycle'] : best;
+    const scoresRaw = Array.isArray(obj['scores']) ? obj['scores'] : [];
+    const scores = [];
+    for (const s of scoresRaw) {
+        if (s === null || typeof s !== 'object')
+            continue;
+        const r = s;
+        if (typeof r['evaluator'] !== 'string')
+            continue;
+        const gate = r['gateAction'];
+        if (gate !== 'pass' && gate !== 'warn' && gate !== 'block')
+            continue;
+        const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
+        const degraded = r['degraded'] === true;
+        scores.push({
+            evaluator: r['evaluator'],
+            score: typeof r['score'] === 'number' ? r['score'] : gateActionToScore(gate, degraded),
+            gateAction: gate,
+            degraded,
+            observedAt
+        });
+    }
+    return { cycle: cycleNo, scores };
+}
+function round4(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/dist/services/loop/monotonic-runner.d.ts

@@ -0,0 +1,64 @@
+import { type MonotonicCycle, type MonotonicScoreRow, type MonotonicReport } from './monotonic-guard.js';
+/** Set of evaluator kinds the loop walker actually scores — keeps the
+ *  guard surface tight (the verdict-aggregate is the cross-source merge
+ *  and not a per-cycle input). */
+declare const WALKED_EVALUATORS: readonly ["karpathy", "code-review", "security-review", "perf-baseline"];
+type WalkedKind = (typeof WALKED_EVALUATORS)[number];
+export interface RunMonotonicOptions {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    /** Threshold (0..1 scale). Default 0.05 (5%). */
+    readonly threshold?: number;
+    /** When set, write the current cycle score rows to disk (default: true). */
+    readonly persist?: boolean;
+    /** When set, override the auto-derived cycle index. */
+    readonly cycle?: number;
+    /** Override the peaks binary path (default: `node bin/peaks.js`). */
+    readonly peaksBin?: string;
+}
+export interface RunMonotonicResult {
+    readonly projectRoot: string;
+    readonly sid: string;
+    readonly rid: string;
+    readonly currentCycle: number;
+    readonly previousCycle: number | null;
+    readonly persistedAt: string | null;
+    readonly rows: readonly MonotonicScoreRow[];
+    readonly report: MonotonicReport;
+    /** Additive surface for non-fatal persistence warnings (e.g. append
+     *  failure). Optional so existing destructures keep compiling. */
+    readonly warnings?: readonly string[];
+}
+/** Resolve the slice dir — kept for API/BC (run-driver.ts uses it to
+ *  derive `cyclesDir`). The monotonic-runner writer no longer writes
+ *  here; the jsonl-store is the new persistence layer. */
+export declare function sliceDir(projectRoot: string, sid: string, rid: string): string;
+/** Load the most recent prior cycle for `(sid, rid)` from the
+ *  per-session jsonl store (tail scan, O(N) where N = total jsonl
+ *  lines, ~50-100 for a 24h run). Falls back to the legacy
+ *  `.peaks/_sub_agents/<sid>/shared/` dir for cross-session signal.
+ *  Returns `null` on any read error. */
+export declare function loadPreviousCycle(projectRoot: string, sid: string, rid: string): MonotonicCycle | null;
+/** Determine the next cycle index — reads the most recent jsonl
+ *  cycle line's `cycle` field + 1 (or `1` when none exist). `rid`
+ *  retained for API compatibility — the jsonl-store is per-session,
+ *  but the line tag carries `rid` so the reader filters to this rid.
+ */
+export declare function nextCycleIndex(projectRoot: string, sid: string, rid: string): number;
+/** Run the guard end-to-end: walk the 4 evaluators, persist the
+ *  current cycle to the jsonl store, compare against the prior cycle,
+ *  return a structured report. */
+export declare function runMonotonicCheck(options: RunMonotonicOptions): RunMonotonicResult;
+/** Helper for tests + CLI — resolve project root + sid consistently. */
+export declare function resolveMonotonicContext(opts: {
+    project?: string;
+    session: string;
+    rid: string;
+}): {
+    projectRoot: string;
+    sid: string;
+    rid: string;
+};
+/** Suppress unused-import lint when only the typedefs are exported. */
+export type { WalkedKind };

package/dist/services/loop/monotonic-runner.js

@@ -0,0 +1,270 @@
+/**
+ * peaks-loop v3.0.0 — Slice C.2
+ *
+ * Runtime for the `monotonic-improvement` evaluator. Walks the prior
+ * cycle's score rows (per evaluator), invokes each evaluator against
+ * the current rid + project, then compares adjacent cycles.
+ *
+ *  - current cycle score rows are appended to the per-session jsonl
+ *    store at `.peaks/_runtime/<sid>/metrics/slices.jsonl` with the
+ *    tag `{"kind":"monotonic-cycle","rid":"<rid>","cycle":N,"scores":[...]}`.
+ *  - previous cycle rows are read from the same jsonl store (last
+ *    matching tag, O(1) tail scan). When no jsonl record exists, the
+ *    reader falls back to the legacy `.peaks/_sub_agents/<sid>/shared/`
+ *    dir (still reads cycle-N.json) for cross-batch/session signal.
+ *  - missing previous cycle → skip (not abort).
+ *
+ * Karpathy §2 Simplicity First: reuse `appendMetricLine` +
+ * `readMetricLines` from `observability/jsonl-store.ts`. One append per
+ * cycle replaces N cycle-N.json files; tail scan replaces readdirSync +
+ * regex.
+ *
+ * File budget: ≤ 800 lines (Karpathy §2).
+ */
+import { join } from 'node:path';
+import { dispatchEvaluator } from './evaluator-dispatcher.js';
+import { checkMonotonicImprovement, toScoreRow, DEFAULT_MONOTONIC_THRESHOLD } from './monotonic-guard.js';
+import { appendMetricLine, readMetricLines } from '../observability/jsonl-store.js';
+import { findProjectRoot } from '../config/config-safety.js';
+function classifyFsError(err) {
+    const code = err?.code;
+    if (code === 'ENOENT')
+        return 'NOT_FOUND';
+    return 'IO_ERROR';
+}
+/** Tag for cycle lines in the jsonl-store. */
+const MONOTONIC_CYCLE_KIND = 'monotonic-cycle';
+/** Set of evaluator kinds the loop walker actually scores — keeps the
+ *  guard surface tight (the verdict-aggregate is the cross-source merge
+ *  and not a per-cycle input). */
+const WALKED_EVALUATORS = [
+    'karpathy',
+    'code-review',
+    'security-review',
+    'perf-baseline'
+];
+/** Resolve the slice dir — kept for API/BC (run-driver.ts uses it to
+ *  derive `cyclesDir`). The monotonic-runner writer no longer writes
+ *  here; the jsonl-store is the new persistence layer. */
+export function sliceDir(projectRoot, sid, rid) {
+    return join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid);
+}
+/** Load the most recent prior cycle for `(sid, rid)` from the
+ *  per-session jsonl store (tail scan, O(N) where N = total jsonl
+ *  lines, ~50-100 for a 24h run). Falls back to the legacy
+ *  `.peaks/_sub_agents/<sid>/shared/` dir for cross-session signal.
+ *  Returns `null` on any read error. */
+export function loadPreviousCycle(projectRoot, sid, rid) {
+    return loadMostRecentCycleFromJsonl(projectRoot, sid, rid)
+        ?? loadMostRecentCycleFromSubAgents(projectRoot, sid, rid);
+}
+/** Scan the jsonl-store from tail backwards for the most recent
+ *  `monotonic-cycle` line matching `rid`. Returns `null` when no
+ *  matching line exists or any line is malformed. */
+function loadMostRecentCycleFromJsonl(projectRoot, sid, rid) {
+    const lines = readMetricLines(projectRoot, sid);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i] ?? '';
+        const parsed = parseCycleLine(line, rid);
+        if (parsed !== null)
+            return parsed;
+    }
+    return null;
+}
+function parseCycleLine(raw, rid) {
+    let obj;
+    try {
+        const v = JSON.parse(raw);
+        if (v === null || typeof v !== 'object')
+            return null;
+        obj = v;
+    }
+    catch {
+        return null;
+    }
+    if (obj['kind'] !== MONOTONIC_CYCLE_KIND)
+        return null;
+    if (typeof obj['rid'] !== 'string' || obj['rid'] !== rid)
+        return null;
+    const cycle = typeof obj['cycle'] === 'number' ? obj['cycle'] : 0;
+    const scores = parseScoreRows(obj['scores']);
+    return { cycle, scores };
+}
+function parseScoreRows(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const s of raw) {
+        if (s === null || typeof s !== 'object')
+            continue;
+        const r = s;
+        if (typeof r['evaluator'] !== 'string')
+            continue;
+        const gate = r['gateAction'];
+        if (gate !== 'pass' && gate !== 'warn' && gate !== 'block')
+            continue;
+        const observedAt = typeof r['observedAt'] === 'string' ? r['observedAt'] : new Date(0).toISOString();
+        out.push({
+            evaluator: r['evaluator'],
+            score: typeof r['score'] === 'number' ? r['score'] : (gate === 'pass' ? 1.0 : gate === 'warn' ? 0.5 : 0.0),
+            gateAction: gate,
+            degraded: r['degraded'] === true,
+            observedAt
+        });
+    }
+    return out;
+}
+/** Legacy fallback: read the most recent `cycle-N.json` from the
+ *  `.peaks/_sub_agents/<sid>/shared/` dir (cross-session signal).
+ *  Kept verbatim so existing cross-batch signals remain readable. */
+function loadMostRecentCycleFromSubAgents(projectRoot, sid, rid) {
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sid, 'shared');
+    return loadMostRecentCycleFromDir(dir, rid);
+}
+function loadMostRecentCycleFromDir(dir, rid) {
+    // Lazily import so unit tests in non-windows environments don't pull
+    // node:fs through a static `import`.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    if (!fs.existsSync(dir))
+        return null;
+    const readdir = (() => {
+        try {
+            return { ok: true, value: fs.readdirSync(dir) };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readdir.ok)
+        return null;
+    const entries = readdir.value;
+    let bestCycle = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const n = parseInt(m[1] ?? '0', 10);
+        if (bestCycle === null || n > bestCycle)
+            bestCycle = n;
+    }
+    if (bestCycle === null)
+        return null;
+    const target = join(dir, `cycle-${bestCycle}.json`);
+    const readFile = (() => {
+        try {
+            return { ok: true, value: fs.readFileSync(target, 'utf8') };
+        }
+        catch (err) {
+            return { ok: false, reason: classifyFsError(err) };
+        }
+    })();
+    if (!readFile.ok)
+        return null;
+    const parsed = parseLegacyCycleFile(readFile.value, bestCycle);
+    // `rid` param retained for BC with the legacy dir shape (legacy
+    // files are shared across rids); include it in the parsed object so
+    // future cross-rid reads stay consistent.
+    void rid;
+    return parsed;
+}
+function parseLegacyCycleFile(raw, fallbackCycle) {
+    const parse = (() => {
+        try {
+            return { ok: true, value: JSON.parse(raw) };
+        }
+        catch {
+            return { ok: false, reason: 'PARSE_ERROR' };
+        }
+    })();
+    if (!parse.ok)
+        return null;
+    const parsed = parse.value;
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const obj = parsed;
+    const scores = parseScoreRows(obj['scores']);
+    return { cycle: typeof obj['cycle'] === 'number' ? obj['cycle'] : fallbackCycle, scores };
+}
+/** Determine the next cycle index — reads the most recent jsonl
+ *  cycle line's `cycle` field + 1 (or `1` when none exist). `rid`
+ *  retained for API compatibility — the jsonl-store is per-session,
+ *  but the line tag carries `rid` so the reader filters to this rid.
+ */
+export function nextCycleIndex(projectRoot, sid, rid) {
+    const prev = loadPreviousCycle(projectRoot, sid, rid);
+    if (prev === null)
+        return 1;
+    return prev.cycle + 1;
+}
+/** Run the guard end-to-end: walk the 4 evaluators, persist the
+ *  current cycle to the jsonl store, compare against the prior cycle,
+ *  return a structured report. */
+export function runMonotonicCheck(options) {
+    const threshold = options.threshold ?? DEFAULT_MONOTONIC_THRESHOLD;
+    const persist = options.persist !== false;
+    const cycle = options.cycle ?? nextCycleIndex(options.projectRoot, options.sid, options.rid);
+    const rows = [];
+    for (const kind of WALKED_EVALUATORS) {
+        let env;
+        try {
+            env = dispatchEvaluator(kind, {
+                projectRoot: options.projectRoot,
+                rid: options.rid,
+                ...(options.peaksBin !== undefined ? { peaksBin: options.peaksBin } : {})
+            });
+        }
+        catch {
+            // Per-evaluator failures never abort the loop — degrade to warn,
+            // score 0.25, degraded=true, observed-at=now.
+            const now = new Date().toISOString();
+            rows.push({
+                evaluator: kind,
+                score: 0.25,
+                gateAction: 'warn',
+                degraded: true,
+                observedAt: now
+            });
+            continue;
+        }
+        rows.push(toScoreRow(env.kind, env.gateAction, env.degraded, new Date().toISOString()));
+    }
+    const currentCycle = { cycle, scores: rows };
+    const previousCycle = loadPreviousCycle(options.projectRoot, options.sid, options.rid);
+    const report = checkMonotonicImprovement(previousCycle, currentCycle, { threshold });
+    let persistedAt = null;
+    const envelopeWarns = [];
+    if (persist) {
+        const line = {
+            kind: MONOTONIC_CYCLE_KIND,
+            rid: options.rid,
+            cycle,
+            persistedAt: new Date().toISOString(),
+            scores: rows
+        };
+        const ok = appendMetricLine(options.projectRoot, options.sid, JSON.stringify(line));
+        if (ok) {
+            persistedAt = `jsonl:${options.sid}#cycle=${cycle}`;
+        }
+        else {
+            persistedAt = null;
+            envelopeWarns.push(`append-failed: jsonl-store for sid=${options.sid} cycle=${cycle}`);
+        }
+    }
+    return {
+        projectRoot: options.projectRoot,
+        sid: options.sid,
+        rid: options.rid,
+        currentCycle: cycle,
+        previousCycle: previousCycle === null ? null : previousCycle.cycle,
+        persistedAt,
+        rows,
+        report,
+        ...(envelopeWarns.length > 0 ? { warnings: envelopeWarns } : {})
+    };
+}
+/** Helper for tests + CLI — resolve project root + sid consistently. */
+export function resolveMonotonicContext(opts) {
+    const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    return { projectRoot, sid: opts.session, rid: opts.rid };
+}