@claude-flow/cli 3.64.0 → 3.65.0

package/dist/src/init/risky-settings-gate.js

@@ -0,0 +1,130 @@
+/**
+ * ADR-509 §2.3: the stop `ruflo init` / `ruflo init upgrade --settings` makes
+ * before carrying a project settings file's auto-approve keys forward.
+ *
+ * The check runs BEFORE anything is written, so a stop leaves the project as
+ * it was. `keep` proceeds (the keys are still reported); `drop` proceeds and
+ * the merged file is written without them.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { isRufloHelperCommand } from './helper-commands.js';
+import { CRITICAL_HELPERS } from './helper-refresh.js';
+import { HELPERS_MANIFEST_FILE, sha256Hex, verifyHelpersManifest } from './helper-signing.js';
+import { dropAutoApproveKeys, formatRiskFindingsAsWarnings, scanProjectAutoApproveKeys, } from './settings-risk-scanner.js';
+export function scanAutoApprove(settings) {
+    return scanProjectAutoApproveKeys(settings, isRufloHelperCommand);
+}
+/** Reads a settings file and judges it; null when the file is absent, unreadable or not a JSON object. */
+export function checkRiskySettings(settingsPath, mode = 'stop') {
+    if (!fs.existsSync(settingsPath))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const findings = scanAutoApprove(parsed);
+    if (findings.length === 0)
+        return null;
+    return { mode, findings, lines: formatRiskFindingsAsWarnings(findings), stop: mode === 'stop' };
+}
+/**
+ * ADR-509 §2.3: the helpers ruflo's hooks launch, as the PROJECT ships them.
+ * `init` keeps an existing `.claude/helpers/<name>` unless --force, and the
+ * project-scope hook commands prefer the project's copy, so a repository that
+ * ships its own hook-handler.cjs runs it under an exact ruflo hook command. A
+ * helper is trusted when its bytes are the copy this ruflo ships, or its
+ * SHA-256 is in a helpers manifest signed with ruflo's key (this ruflo's, or
+ * the project's own, which an older signed release left). Anything else is a
+ * finding. A `.LOCKED` helpers dir (deliberate local edits) is skipped, and with
+ * no ground truth at all this fails open. `pubkeyPem` is injectable for tests.
+ */
+export function untrustedProjectHelpers(targetDir, sourceHelpersDir, pubkeyPem) {
+    const helpersDir = path.join(targetDir, '.claude', 'helpers');
+    // .LOCKED is the sanctioned marker for deliberately edited helpers (helper-refresh honours it too).
+    if (fs.existsSync(path.join(helpersDir, '.LOCKED')))
+        return [];
+    const signed = (dir) => {
+        if (!dir)
+            return null;
+        try {
+            return verifyHelpersManifest(fs.readFileSync(path.join(dir, HELPERS_MANIFEST_FILE), 'utf-8'), pubkeyPem);
+        }
+        catch {
+            return null;
+        }
+    };
+    const manifests = [signed(sourceHelpersDir), signed(helpersDir)].filter((m) => m !== null);
+    // No ground truth at all (no shipped copy, no signed manifest): fail open, as
+    // helper-integrity does, rather than flag every install.
+    if (!sourceHelpersDir && manifests.length === 0)
+        return [];
+    const out = [];
+    for (const name of CRITICAL_HELPERS) {
+        const file = path.join(helpersDir, name);
+        let bytes;
+        try {
+            if (!fs.lstatSync(file).isFile())
+                throw new Error('not a regular file');
+            bytes = fs.readFileSync(file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            out.push({ target: { kind: 'helper', name }, location: `.claude/helpers/${name}`, snippet: '(unreadable or not a regular file)', reason: "is not ruflo's signed helper; ruflo's hooks would run it" });
+            continue;
+        }
+        if (sourceHelpersDir) {
+            try {
+                if (bytes.equals(fs.readFileSync(path.join(sourceHelpersDir, name))))
+                    continue;
+            }
+            catch {
+                // not shipped by this ruflo: fall through to the signed manifests
+            }
+        }
+        const hash = sha256Hex(bytes);
+        if (manifests.some((m) => m.files[name] === hash))
+            continue;
+        out.push({
+            target: { kind: 'helper', name },
+            location: `.claude/helpers/${name}`,
+            snippet: `sha256 ${hash.slice(0, 16)}…`,
+            reason: "differs from ruflo's signed helper; init keeps it and ruflo's hooks would run it",
+        });
+    }
+    return out;
+}
+/**
+ * The init gate: the settings file's auto-approve keys plus the project's
+ * untrusted helpers. Null when there is nothing to report.
+ */
+export function checkInitTrust(targetDir, mode, sourceHelpersDir) {
+    const settings = checkRiskySettings(path.join(targetDir, '.claude', 'settings.json'), mode);
+    const helpers = untrustedProjectHelpers(targetDir, sourceHelpersDir);
+    const findings = [...(settings?.findings ?? []), ...helpers];
+    if (findings.length === 0)
+        return null;
+    return { mode, findings, lines: formatRiskFindingsAsWarnings(findings), stop: mode === 'stop' };
+}
+/** `drop`: the settings without the auto-approve keys; otherwise the settings unchanged. */
+export function applyRiskyMode(settings, mode) {
+    if (mode !== 'drop')
+        return { settings, dropped: 0 };
+    const findings = scanAutoApprove(settings);
+    return findings.length ? { settings: dropAutoApproveKeys(settings, findings), dropped: findings.length } : { settings, dropped: 0 };
+}
+/** Reads `--keep-risky-settings` / `--drop-risky-settings` (camel or kebab); both at once is an error. */
+export function riskyModeFromFlags(flags) {
+    const keep = flags.keepRiskySettings === true || flags['keep-risky-settings'] === true;
+    const drop = flags.dropRiskySettings === true || flags['drop-risky-settings'] === true;
+    if (keep && drop)
+        return { error: '--keep-risky-settings and --drop-risky-settings cannot be used together' };
+    return keep ? 'keep' : drop ? 'drop' : 'stop';
+}
+//# sourceMappingURL=risky-settings-gate.js.map

package/dist/src/init/settings-risk-scanner.d.ts

@@ -44,4 +44,39 @@ export declare function scanAllowRuleForRisk(rule: string): string[];
 export declare function scanSettingsForRisk(settings: Record<string, unknown>): SettingsRiskFinding[];
 /** Formats findings as short, human-readable CLI warning lines. */
 export declare function formatRiskFindingsAsWarnings(findings: SettingsRiskFinding[]): string[];
+/** What a finding points at, precisely enough for dropAutoApproveKeys to remove only that. */
+export type AutoApproveTarget = {
+    kind: 'enableAllProjectMcpServers';
+} | {
+    kind: 'enabledMcpjsonServers';
+} | {
+    kind: 'defaultMode';
+} | {
+    kind: 'allow';
+    index: number;
+} | {
+    kind: 'hook';
+    event: string;
+    group: number;
+    hook: number;
+}
+/** A project `.claude/helpers/<name>` that is not ruflo's signed copy (init keeps it without --force). */
+ | {
+    kind: 'helper';
+    name: string;
+};
+export interface AutoApproveFinding extends SettingsRiskFinding {
+    target: AutoApproveTarget;
+}
+/**
+ * The auto-approve keys of a PROJECT settings file (`.claude/settings.json` or
+ * `.claude/settings.local.json`). `isRufloHook` decides which hook commands are
+ * ruflo's own helpers (injected so this module stays dependency-free).
+ */
+export declare function scanProjectAutoApproveKeys(settings: Record<string, unknown>, isRufloHook: (command: string) => boolean): AutoApproveFinding[];
+/** A deep copy of `settings` without the keys/entries the findings point at. Never mutates its input. */
+export declare function dropAutoApproveKeys(settings: Record<string, unknown>, findings: readonly AutoApproveFinding[]): Record<string, unknown>;
+/** What `init` does when the existing settings carry auto-approve keys. */
+export type RiskySettingsMode = 'stop' | 'keep' | 'drop';
+export declare const RISKY_SETTINGS_HINT = "Re-run with --drop-risky-settings to write the merged settings without these keys (and replace any flagged helper with ruflo's copy), or --keep-risky-settings to keep them.";
 //# sourceMappingURL=settings-risk-scanner.d.ts.map

package/dist/src/init/settings-risk-scanner.js

@@ -177,4 +177,89 @@ export function scanSettingsForRisk(settings) {
 export function formatRiskFindingsAsWarnings(findings) {
     return findings.map((f) => `${f.location}: ${f.reason} — "${f.snippet}"`);
 }
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/** A bare `Bash`, `Bash(*)`, `Bash(*:*)` or a `*` wildcard pre-approves every command. */
+function isBlanketAllow(rule) {
+    const t = rule.trim();
+    return t === '*' || /^Bash$/i.test(t) || /^Bash\(\s*\*\s*(:\s*\*\s*)?\)$/i.test(t) || /^\*\s*\(.*\)$/.test(t);
+}
+/**
+ * The auto-approve keys of a PROJECT settings file (`.claude/settings.json` or
+ * `.claude/settings.local.json`). `isRufloHook` decides which hook commands are
+ * ruflo's own helpers (injected so this module stays dependency-free).
+ */
+export function scanProjectAutoApproveKeys(settings, isRufloHook) {
+    const out = [];
+    if (settings.enableAllProjectMcpServers === true) {
+        out.push({ target: { kind: 'enableAllProjectMcpServers' }, location: 'enableAllProjectMcpServers', snippet: 'true', reason: 'starts every .mcp.json server in the project without asking' });
+    }
+    const enabled = settings.enabledMcpjsonServers;
+    if (Array.isArray(enabled) && enabled.length > 0) {
+        out.push({ target: { kind: 'enabledMcpjsonServers' }, location: 'enabledMcpjsonServers', snippet: buildSnippet(enabled.map(String).join(', ')), reason: 'pre-approves .mcp.json servers before the trust dialog' });
+    }
+    const permissions = isRecord(settings.permissions) ? settings.permissions : undefined;
+    if (permissions?.defaultMode === 'bypassPermissions') {
+        out.push({ target: { kind: 'defaultMode' }, location: 'permissions.defaultMode', snippet: 'bypassPermissions', reason: 'turns off every permission prompt' });
+    }
+    if (Array.isArray(permissions?.allow)) {
+        permissions.allow.forEach((rule, index) => {
+            if (typeof rule === 'string' && isBlanketAllow(rule)) {
+                out.push({ target: { kind: 'allow', index }, location: `permissions.allow[${index}]`, snippet: buildSnippet(rule), reason: 'pre-approves every command (bare Bash or * wildcard)' });
+            }
+        });
+    }
+    const hooks = isRecord(settings.hooks) ? settings.hooks : undefined;
+    for (const [event, groups] of Object.entries(hooks ?? {})) {
+        if (!Array.isArray(groups))
+            continue;
+        groups.forEach((g, group) => {
+            const list = isRecord(g) && Array.isArray(g.hooks) ? g.hooks : [];
+            list.forEach((h, hook) => {
+                if (!isRecord(h) || typeof h.command !== 'string' || isRufloHook(h.command))
+                    return;
+                out.push({ target: { kind: 'hook', event, group, hook }, location: `hooks.${event}[${group}].hooks[${hook}]`, snippet: buildSnippet(h.command), reason: 'runs a command that is not a ruflo helper' });
+            });
+        });
+    }
+    return out;
+}
+/** A deep copy of `settings` without the keys/entries the findings point at. Never mutates its input. */
+export function dropAutoApproveKeys(settings, findings) {
+    const next = JSON.parse(JSON.stringify(settings));
+    const perms = isRecord(next.permissions) ? next.permissions : undefined;
+    const allowDrop = new Set();
+    const hookDrop = new Set();
+    for (const { target: t } of findings) {
+        if (t.kind === 'enableAllProjectMcpServers')
+            delete next.enableAllProjectMcpServers;
+        else if (t.kind === 'enabledMcpjsonServers')
+            delete next.enabledMcpjsonServers;
+        else if (t.kind === 'defaultMode' && perms)
+            delete perms.defaultMode;
+        else if (t.kind === 'allow')
+            allowDrop.add(t.index);
+        else if (t.kind === 'hook')
+            hookDrop.add(`${t.event}\u0000${t.group}\u0000${t.hook}`);
+    }
+    if (perms && Array.isArray(perms.allow))
+        perms.allow = perms.allow.filter((_, i) => !allowDrop.has(i));
+    if (isRecord(next.hooks) && hookDrop.size) {
+        for (const [event, groups] of Object.entries(next.hooks)) {
+            if (!Array.isArray(groups))
+                continue;
+            const kept = groups
+                .map((g, gi) => (isRecord(g) && Array.isArray(g.hooks) ? { ...g, hooks: g.hooks.filter((_, hi) => !hookDrop.has(`${event}\u0000${gi}\u0000${hi}`)) } : g))
+                .filter((g) => !(isRecord(g) && Array.isArray(g.hooks) && g.hooks.length === 0));
+            if (kept.length)
+                next.hooks[event] = kept;
+            else
+                delete next.hooks[event];
+        }
+        // No hooks left: drop the key, so init writes its own hooks as it does for a file without any.
+        if (Object.keys(next.hooks).length === 0)
+            delete next.hooks;
+    }
+    return next;
+}
+export const RISKY_SETTINGS_HINT = 'Re-run with --drop-risky-settings to write the merged settings without these keys (and replace any flagged helper with ruflo\'s copy), or --keep-risky-settings to keep them.';
 //# sourceMappingURL=settings-risk-scanner.js.map

package/dist/src/init/types.d.ts

@@ -296,6 +296,14 @@ export interface InitOptions {
      * GitHub contributor graph. Pass `--attribution` to opt in.
      */
     attribution?: boolean;
+    /**
+     * ADR-509 §2.3 — what to do when the existing project settings.json carries
+     * auto-approve keys (enableAllProjectMcpServers, enabledMcpjsonServers,
+     * bypassPermissions, blanket Bash allows, non-ruflo hooks): `stop`
+     * (default — nothing is written), `keep` (--keep-risky-settings) or `drop`
+     * (--drop-risky-settings).
+     */
+    riskySettings?: 'stop' | 'keep' | 'drop';
 }
 /**
  * Default init options - full V3 setup
@@ -334,5 +342,9 @@ export interface InitResult {
      * init — surfaced so a user can review before trusting it.
      */
     warnings?: string[];
+    /** ADR-509 §2.3 — auto-approve keys found in the existing project settings.json. */
+    riskySettings?: string[];
+    /** ADR-509 §2.3 — init stopped before writing anything because of riskySettings. */
+    stoppedOnRiskySettings?: boolean;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/src/mcp-tools/capability-brain.d.ts

@@ -97,7 +97,7 @@ export interface CapabilityBrain {
     };
 }
 /** Top-level commands from the CLI command loader. Kept as a checked manifest. */
-export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements", "tui", "harness"];
+export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "cost", "announcements", "tui", "harness"];
 export interface ImplementationLoopStep {
     id: string;
     name: string;

package/dist/src/mcp-tools/capability-brain.js

@@ -15,7 +15,7 @@ export const RUFLO_CLI_COMMANDS = [
     'doctor', 'verify', 'analyze', 'route', 'progress', 'issues', 'update',
     'ruvector', 'benchmark', 'guidance', 'appliance', 'appliance-advanced',
     'transfer-store', 'cleanup', 'autopilot', 'gaia-bench', 'metaharness',
-    'eject', 'funnel', 'settings', 'auth', 'proxy', 'advisor', 'spinner',
+    'eject', 'funnel', 'settings', 'auth', 'proxy', 'advisor', 'spinner', 'cost',
     'announcements', 'tui', 'harness',
 ];
 export const IMPLEMENTATION_LOOP = [

package/dist/src/mcp-tools/hooks-tools.js

@@ -5482,7 +5482,8 @@ export const hooksVerifiedIngest = {
     handler: async (params) => {
         const { ingestVerifiedOutcomes } = await import('../memory/verified-outcomes.js');
         const sona = await getSONAOptimizer();
-        const result = await ingestVerifiedOutcomes({ dryRun: params.dryRun === true, force: params.force === true || params.dryRun === true, sona: sona });
+        // ADR-503 §2.3: only this explicit ingest may re-verify (run project code), and only when learningLoop.reverify is on.
+        const result = await ingestVerifiedOutcomes({ dryRun: params.dryRun === true, force: params.force === true || params.dryRun === true, sona: sona, allowReverify: true });
         return { success: true, ...result };
     },
 };

package/dist/src/memory/verified-guards.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Gaming defences for the verified-outcome learning loop (ADR-503).
+ *
+ * Every rule here can only downgrade: a tainted record does not train, a
+ * pattern that looks gamed is held back from the prompt. Nothing here can
+ * turn an `unknown` into a verified outcome.
+ *
+ *  - §2.1/§2.2 taints: the mod marks a `verified-success` whose turn edited a
+ *    test file or a verifier config, or narrowed its check. Ingest never
+ *    trains a tainted record unless `.claude-flow/config.json`
+ *    `learningLoop.allowTaint` lists every one of its classes.
+ *  - §2.3 re-verify settings (the runner lives in verified-reverify.ts).
+ *  - §2.4 the anomaly gate on lessons.
+ */
+export type Taint = 'edited-tests' | 'edited-verifier-config' | 'narrowed-verifier';
+export declare const TAINTS: readonly Taint[];
+/** A record's `taint` field, validated: known classes only, each once. Anything else is dropped. */
+export declare function parseTaint(raw: unknown): Taint[];
+export interface LoopConfig {
+    /** Taint classes a project lets train (default none). */
+    readonly allowTaint: readonly Taint[];
+    /** Re-run a verifier at HEAD before a success trains (default off: it runs project code). */
+    readonly reverify: boolean;
+    readonly reverifyTimeoutMs: number;
+}
+export declare const DEFAULT_REVERIFY_TIMEOUT_MS = 300000;
+export declare const DEFAULT_LOOP_CONFIG: LoopConfig;
+/**
+ * `learningLoop` from `.claude-flow/config.json`. A missing, unreadable or
+ * malformed file means the defaults: no taint allowed, re-verify off. Only
+ * `reverify: true` (the boolean) turns re-verification on.
+ */
+export declare function readLoopConfig(root: string): LoopConfig;
+export declare function parseLoopConfig(raw: unknown): LoopConfig;
+/** The taint classes of a record that its project did not allow; non-empty means it never trains. */
+export declare const blockedTaints: (taint: readonly Taint[], config: LoopConfig) => Taint[];
+/**
+ * What ingest knows about a verified pattern, from verified records only
+ * (SONA's own counts include other feeders). Sessions are capped: the gate
+ * only asks whether there were two.
+ */
+export interface PatternStats {
+    successes: number;
+    failures: number;
+    /** Successes that carried an allowed taint. */
+    tainted: number;
+    /** Successes decided by a narrowed command. */
+    narrowed: number;
+    sessions: string[];
+}
+export declare const MAX_PATTERN_SESSIONS = 4;
+export declare const emptyStats: () => PatternStats;
+export declare function parseStats(raw: unknown): PatternStats;
+/** Folds one trained record into its pattern's stats. */
+export declare function addOutcome(stats: PatternStats, success: boolean, taint: readonly Taint[], session: string | null): void;
+export type HoldReason = 'perfect-and-tainted' | 'only-narrowed' | 'one-session';
+/** §2.4 case 1: records at or above which a perfect record with half its successes tainted is held. */
+export declare const PERFECT_MIN_RECORDS = 8;
+/**
+ * Why a would-be lesson is held back from the prompt (ADR-503 §2.4), or null.
+ * A held pattern stays in SONA; it only never becomes a prompt lesson.
+ *
+ * 1. 100% success over 8 or more records, half or more of them tainted (allowed).
+ * 2. Every success came from a narrowed command.
+ * 3. Every success came from one session: no independent repetition. A pattern
+ *    with no recorded sessions (a record from before ADR-503, or one without a
+ *    session) counts as one session.
+ */
+export declare function holdReason(stats: PatternStats, sonaSuccesses: number): HoldReason | null;
+//# sourceMappingURL=verified-guards.d.ts.map

package/dist/src/memory/verified-guards.js

@@ -0,0 +1,101 @@
+/**
+ * Gaming defences for the verified-outcome learning loop (ADR-503).
+ *
+ * Every rule here can only downgrade: a tainted record does not train, a
+ * pattern that looks gamed is held back from the prompt. Nothing here can
+ * turn an `unknown` into a verified outcome.
+ *
+ *  - §2.1/§2.2 taints: the mod marks a `verified-success` whose turn edited a
+ *    test file or a verifier config, or narrowed its check. Ingest never
+ *    trains a tainted record unless `.claude-flow/config.json`
+ *    `learningLoop.allowTaint` lists every one of its classes.
+ *  - §2.3 re-verify settings (the runner lives in verified-reverify.ts).
+ *  - §2.4 the anomaly gate on lessons.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const TAINTS = ['edited-tests', 'edited-verifier-config', 'narrowed-verifier'];
+/** A record's `taint` field, validated: known classes only, each once. Anything else is dropped. */
+export function parseTaint(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const t of raw.slice(0, 8))
+        if (TAINTS.includes(t) && !out.includes(t))
+            out.push(t);
+    return out;
+}
+export const DEFAULT_REVERIFY_TIMEOUT_MS = 300_000;
+export const DEFAULT_LOOP_CONFIG = { allowTaint: [], reverify: false, reverifyTimeoutMs: DEFAULT_REVERIFY_TIMEOUT_MS };
+/**
+ * `learningLoop` from `.claude-flow/config.json`. A missing, unreadable or
+ * malformed file means the defaults: no taint allowed, re-verify off. Only
+ * `reverify: true` (the boolean) turns re-verification on.
+ */
+export function readLoopConfig(root) {
+    const path = join(root, '.claude-flow', 'config.json');
+    try {
+        if (!existsSync(path))
+            return DEFAULT_LOOP_CONFIG;
+        const raw = JSON.parse(readFileSync(path, 'utf8'));
+        return parseLoopConfig(raw?.learningLoop);
+    }
+    catch {
+        return DEFAULT_LOOP_CONFIG;
+    }
+}
+export function parseLoopConfig(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return DEFAULT_LOOP_CONFIG;
+    const r = raw;
+    const sec = typeof r.reverifyTimeoutSec === 'number' && Number.isFinite(r.reverifyTimeoutSec) ? Math.min(Math.max(Math.floor(r.reverifyTimeoutSec), 10), 3600) : DEFAULT_REVERIFY_TIMEOUT_MS / 1000;
+    return { allowTaint: parseTaint(r.allowTaint), reverify: r.reverify === true, reverifyTimeoutMs: sec * 1000 };
+}
+/** The taint classes of a record that its project did not allow; non-empty means it never trains. */
+export const blockedTaints = (taint, config) => taint.filter(t => !config.allowTaint.includes(t));
+export const MAX_PATTERN_SESSIONS = 4;
+const SESSION = /^[A-Za-z0-9_-]{1,40}$/;
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? Math.min(Math.floor(v), 1_000_000) : 0);
+export const emptyStats = () => ({ successes: 0, failures: 0, tainted: 0, narrowed: 0, sessions: [] });
+export function parseStats(raw) {
+    const r = (raw && typeof raw === 'object' ? raw : {});
+    const sessions = Array.isArray(r.sessions) ? [...new Set(r.sessions.filter((s) => typeof s === 'string' && SESSION.test(s)))].slice(0, MAX_PATTERN_SESSIONS) : [];
+    return { successes: count(r.successes), failures: count(r.failures), tainted: count(r.tainted), narrowed: count(r.narrowed), sessions };
+}
+/** Folds one trained record into its pattern's stats. */
+export function addOutcome(stats, success, taint, session) {
+    if (!success) {
+        stats.failures++;
+        return;
+    }
+    stats.successes++;
+    if (taint.length > 0)
+        stats.tainted++;
+    if (taint.includes('narrowed-verifier'))
+        stats.narrowed++;
+    if (session && SESSION.test(session) && !stats.sessions.includes(session) && stats.sessions.length < MAX_PATTERN_SESSIONS)
+        stats.sessions.push(session);
+}
+/** §2.4 case 1: records at or above which a perfect record with half its successes tainted is held. */
+export const PERFECT_MIN_RECORDS = 8;
+/**
+ * Why a would-be lesson is held back from the prompt (ADR-503 §2.4), or null.
+ * A held pattern stays in SONA; it only never becomes a prompt lesson.
+ *
+ * 1. 100% success over 8 or more records, half or more of them tainted (allowed).
+ * 2. Every success came from a narrowed command.
+ * 3. Every success came from one session: no independent repetition. A pattern
+ *    with no recorded sessions (a record from before ADR-503, or one without a
+ *    session) counts as one session.
+ */
+export function holdReason(stats, sonaSuccesses) {
+    const s = stats.successes;
+    if (s >= PERFECT_MIN_RECORDS && stats.failures === 0 && stats.tainted * 2 >= s)
+        return 'perfect-and-tainted';
+    if (s > 0 && stats.narrowed === s)
+        return 'only-narrowed';
+    if ((s > 0 || sonaSuccesses > 0) && stats.sessions.length < 2)
+        return 'one-session';
+    return null;
+}
+//# sourceMappingURL=verified-guards.js.map

package/dist/src/memory/verified-outcomes.d.ts

@@ -19,7 +19,15 @@
  * verified outcomes produced, those at or above the SONA routing gate as
  * lessons, and repeated verified failures as cautions. The mod reads that
  * file and adds at most three cited lessons to a prompt.
+ *
+ * ADR-503 hardens it against gamed signals (verified-guards.ts,
+ * verified-reverify.ts): a tainted success does not train unless the project
+ * allows its taint class, an opt-in re-verify can downgrade a success before
+ * it trains, and an anomaly gate holds suspicious patterns back from the
+ * prompt. Every one of these can only downgrade.
  */
+import { type HoldReason, type LoopConfig, type PatternStats, type Taint } from './verified-guards.js';
+import { type ReverifyRunner } from './verified-reverify.js';
 export declare const VERIFIED_PATH: string;
 export declare const LEDGER_PATH: string;
 export declare const LESSONS_PATH: string;
@@ -49,6 +57,10 @@ export interface VerifiedRecord {
         readonly ok: boolean;
     }>;
     readonly edits: number;
+    /** ADR-503 §2.1: what the turn did to its own check; only a `verified-success` carries any. */
+    readonly taint: readonly Taint[];
+    /** The mod process that recorded it, when the mod wrote one (ADR-503 §2.4). */
+    readonly session: string | null;
     readonly startedAt: number;
     readonly endedAt: number;
 }
@@ -62,13 +74,31 @@ export interface IngestLedger {
         verifiedFailure: number;
         unknown: number;
         rejected: number;
+        tainted: number;
     };
-    /** Pattern keys verified outcomes trained, with the last verifier command that decided them (the lesson's evidence). */
+    /**
+     * Pattern keys verified outcomes trained, with the last verifier command that decided them (the lesson's evidence)
+     * and what the anomaly gate needs (ADR-503 §2.4).
+     */
     patterns: Record<string, {
         evidence: string;
         at: number;
+        stats: PatternStats;
     }>;
+    /** ADR-503 §2.3: the rotation cursor and the latest re-verifications (which commit, which check, what happened). */
+    reverify: {
+        cursor: number;
+        log: ReverifyLogEntry[];
+    };
+}
+export interface ReverifyLogEntry {
+    readonly id: string;
+    readonly check: string | null;
+    readonly commit: string | null;
+    readonly status: 'pass' | 'fail' | 'timeout' | 'error';
+    readonly at: number;
 }
+export declare const MAX_REVERIFY_LOG = 50;
 export interface Lesson {
     readonly id: string;
     readonly kind: 'lesson' | 'caution';
@@ -86,19 +116,38 @@ export interface LessonsFile {
     lessons: Lesson[];
     /** Verified patterns still below the gate, for the cold-start progress line. */
     belowGate: number;
+    /** Patterns at or above the gate that the anomaly gate kept out of the prompt (ADR-503 §2.4). */
+    held: Array<{
+        id: string;
+        reason: HoldReason;
+    }>;
 }
 export interface IngestResult {
+    /** `tainted`: successes whose taint the project did not allow, counted and never trained (ADR-503 §2.2). */
     ingested: {
         verifiedSuccess: number;
         verifiedFailure: number;
         unknown: number;
         rejected: number;
+        tainted: number;
     };
     trained: number;
     skipped: 'no-file' | 'unchanged' | 'too-large' | null;
     lessons: number;
     cautions: number;
     belowGate: number;
+    held: LessonsFile['held'];
+    /**
+     * ADR-503 §2.3: checks run, successes that passed or were downgraded to unknown, and successes left for an explicit
+     * ingest because this caller may not run project code.
+     */
+    reverify: {
+        enabled: boolean;
+        ran: number;
+        passed: number;
+        downgraded: number;
+        deferred: number;
+    };
     totals: IngestLedger['totals'];
     sonaAvailable: boolean;
 }
@@ -137,8 +186,15 @@ export declare function emptyLedger(): IngestLedger;
 export declare function readLedger(raw: string | null): IngestLedger;
 /** A lesson's citation: a short hash of the SONA pattern key, so the key's own text never reaches a prompt. */
 export declare const lessonId: (patternKey: string) => string;
-/** Builds the lessons file from SONA's patterns, keeping only the ones verified outcomes trained. */
-export declare function buildLessons(patterns: ReturnType<SonaLike['exportPatterns']>, verified: IngestLedger['patterns'], now: number): LessonsFile;
+/**
+ * Builds the lessons file from SONA's patterns, keeping only the ones verified outcomes trained. A would-be lesson the
+ * anomaly gate holds (ADR-503 §2.4) is listed under `held` instead: it stays in SONA, never in a prompt.
+ */
+export declare function buildLessons(patterns: ReturnType<SonaLike['exportPatterns']>, verified: Record<string, {
+    evidence: string;
+    at: number;
+    stats?: PatternStats;
+}>, now: number): LessonsFile;
 export interface IngestOptions {
     /** Project root; defaults to process.cwd(), where SONA keeps `.swarm/`. */
     root?: string;
@@ -149,6 +205,15 @@ export interface IngestOptions {
     /** SONA to train; defaults to the process's optimizer. Null means unavailable. */
     sona?: SonaLike | null;
     now?: number;
+    /** `learningLoop` settings; defaults to `.claude-flow/config.json` under `root` (ADR-503). */
+    config?: LoopConfig;
+    /**
+     * Whether this caller may run project code to re-verify (ADR-503 §2.3). Only an explicit ingest passes true; a hot
+     * caller (hooks_route) leaves successes un-ingested when re-verify is on, instead of blocking for the timeout.
+     */
+    allowReverify?: boolean;
+    /** Re-verify runner; defaults to the detached-git-worktree runner. Tests inject one. */
+    reverifier?: ReverifyRunner;
 }
 export declare function ingestVerifiedOutcomes(options?: IngestOptions): Promise<IngestResult>;
 /**