@claude-flow/cli 3.63.9 → 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.d.ts

@@ -105,6 +105,7 @@ export declare const hooksTaskCompleted: MCPTool;
  * names its store and a `consistency` block flags relationships that drift.
  */
 export declare const hooksIntelligenceUnifiedStats: MCPTool;
+export declare const hooksVerifiedIngest: MCPTool;
 export declare const hooksTools: MCPTool[];
 export default hooksTools;
 //# sourceMappingURL=hooks-tools.d.ts.map

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

@@ -1181,6 +1181,9 @@ export const hooksRoute = {
             // Q-learning and keyword suggestions retain their existing routing paths.
             try {
                 const sonaStart = performance.now();
+                // #4581: fold in any verified outcomes the ruflo-mods learning loop
+                // recorded since the last call (one stat when nothing changed).
+                await ingestVerifiedQuietly();
                 const sona = await getSONAOptimizer();
                 const suggestion = await sona?.getRoutingSuggestion(task);
                 const { isSupportedSonaAgent } = await import('../memory/sona-optimizer.js');
@@ -2639,9 +2642,11 @@ export const hooksSessionEnd = {
                 }
             }
         }
+        const verifiedOutcomes = await ingestVerifiedQuietly();
         return {
             sessionId,
             duration,
+            verifiedOutcomes,
             statePath: saveState ? `.claude/sessions/${sessionId}.json` : undefined,
             daemon: { stopped: daemonStopped },
             sessionPersistence: sessionPersistence || { controller: 'none', persisted: false },
@@ -5450,6 +5455,38 @@ export const hooksIntelligenceUnifiedStats = {
         return intel.getUnifiedLearningStats();
     },
 };
+/**
+ * #4581 / ADR-502: ingest the ruflo-mods learning loop's verified outcomes.
+ * Never throws; null when the module or SONA is unavailable.
+ */
+async function ingestVerifiedQuietly(force = false) {
+    try {
+        const { ingestVerifiedOutcomes } = await import('../memory/verified-outcomes.js');
+        const sona = await getSONAOptimizer();
+        return await ingestVerifiedOutcomes({ force, sona: sona });
+    }
+    catch {
+        return null;
+    }
+}
+export const hooksVerifiedIngest = {
+    name: 'hooks_intelligence_verified-ingest',
+    description: 'Ingest the ruflo-mods learning loop\'s recorded turns (.claude-flow/data/verified-trajectories.jsonl, #4581): turns a test, build or typecheck process verified train SONA; unverified turns are counted and never train. Writes .claude-flow/data/learned-lessons.json (patterns at or above the 0.6 routing gate, plus repeated verified failures as cautions). hooks_route and hooks_session-end already ingest automatically; call this to see the counts or to force a re-read. Use when native Bash hooks (via Claude Code\'s settings.json) are wrong because the outcome must reach Ruflo-side state — SONA pattern persistence and routing — and must be gated on a verifier\'s exit status rather than recorded unconditionally.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            dryRun: { type: 'boolean', description: 'Count only: train nothing and write nothing' },
+            force: { type: 'boolean', description: 'Re-read the file even if it has not changed since the last ingest' },
+        },
+    },
+    handler: async (params) => {
+        const { ingestVerifiedOutcomes } = await import('../memory/verified-outcomes.js');
+        const sona = await getSONAOptimizer();
+        // 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 };
+    },
+};
 // Export all hooks tools
 export const hooksTools = [
     hooksIntelligenceUnifiedStats,
@@ -5479,6 +5516,7 @@ export const hooksTools = [
     hooksTrajectoryStart,
     hooksTrajectoryStep,
     hooksTrajectoryEnd,
+    hooksVerifiedIngest,
     hooksPatternStore,
     hooksPatternSearch,
     hooksIntelligenceStats,

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