@claude-flow/cli 3.65.0 → 3.66.0

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

@@ -0,0 +1,113 @@
+/**
+ * The lessons file the learning loop writes (#4581 ADR-502, ADR-511): SONA patterns that verified outcomes trained,
+ * at or above the routing gate as lessons, repeated verified failures as cautions.
+ *
+ * ADR-511 adds what a lesson can act on: the project files the passing fixes edited, counted per pattern in the
+ * ingest ledger and named (at most three, most often first) in the lesson. A path reaches the file only if it passes
+ * `lessonFile`, the same screen the mod applies when it records and again when it reads.
+ */
+import { createHash } from 'node:crypto';
+import { emptyStats, holdReason } from './verified-guards.js';
+/** The SONA routing gate (sona-optimizer.ts `SONA_ROUTING_GATE`); a lesson below it never influences routing. */
+export const LESSON_GATE = 0.6;
+export const MAX_LESSONS = 20;
+/** Verified failures (and more failures than successes) before a pattern becomes a caution. */
+export const CAUTION_MIN_FAILURES = 2;
+/** ADR-511: files a record may carry, files a pattern counts, and files a lesson names. */
+export const MAX_RECORD_FILES = 5;
+export const MAX_PATTERN_FILES = 20;
+export const MAX_LESSON_FILES = 3;
+const AGENT = /^[a-z][a-z0-9-]{0,40}$/;
+/** Keywords a lesson may show: SONA keeps any non-separator text, the prompt gets only plain words. */
+const SAFE_KEYWORD = /^[a-z0-9][a-z0-9 _./-]{0,40}$/;
+const FILE = /^[A-Za-z0-9_][A-Za-z0-9_./-]{0,119}$/;
+/** Names that may hold a secret, whatever their contents. */
+const SENSITIVE = /(?:^|[._-])(?:env|secrets?|credentials?|passwords?|tokens?|private|id_rsa|id_ed25519)(?:[._-]|$)|\.(?:pem|key|p12|pfx|crt|keystore)$|^(?:npmrc|netrc|pypirc)$/i;
+/** Test files and verifier config (taint.ts in the mod): a lesson that says "edit the test" would teach gaming. */
+const TEST_FILE = /(?:\.(?:test|spec)\.[A-Za-z0-9]+|^test_[^/]*\.py|_test\.(?:go|rs))$/;
+const TEST_DIRS = new Set(['__tests__', 'tests', 'test']);
+const VERIFIER_CONFIG = /^(?:package\.json|vitest\.config\.[^/]+|jest\.config\.[^/]+|pytest\.ini|pyproject\.toml|setup\.cfg|tox\.ini|Cargo\.toml|go\.mod|tsconfig[^/]*\.json|eslint\.config\.[^/]+|Makefile)$/;
+/**
+ * ADR-511: whether a path may be named in a lesson. Project-relative source files only: no absolute path, no `..`,
+ * no dot-file or dot-directory, no name that may hold a secret, no test file and no verifier config.
+ */
+export function lessonFile(path) {
+    if (typeof path !== 'string' || !FILE.test(path))
+        return false;
+    const segs = path.split('/');
+    if (segs.some(s => s === '' || s === '..' || s.startsWith('.')))
+        return false;
+    const base = segs[segs.length - 1];
+    if (SENSITIVE.test(base) || TEST_FILE.test(base) || VERIFIER_CONFIG.test(base))
+        return false;
+    return !segs.slice(0, -1).some(d => TEST_DIRS.has(d));
+}
+/** A record's `files`, screened. */
+export const recordFiles = (raw) => Array.isArray(raw) ? [...new Set(raw.filter(lessonFile))].slice(0, MAX_RECORD_FILES) : [];
+/** A ledger pattern's file counts, screened; a hostile ledger keeps nothing it should not. */
+export function parseFileCounts(raw) {
+    const out = {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return out;
+    for (const [f, n] of Object.entries(raw).slice(0, MAX_PATTERN_FILES)) {
+        if (lessonFile(f) && typeof n === 'number' && Number.isFinite(n) && n >= 1)
+            out[f] = Math.min(Math.floor(n), 1_000_000);
+    }
+    return out;
+}
+/** Counts one verified success's files; past the cap, the least-counted file makes room. */
+export function addFiles(counts, files) {
+    for (const f of files) {
+        if (counts[f] !== undefined)
+            counts[f]++;
+        else
+            counts[f] = 1;
+    }
+    const keys = Object.keys(counts);
+    if (keys.length > MAX_PATTERN_FILES) {
+        for (const k of keys.sort((a, b) => counts[a] - counts[b] || a.localeCompare(b)).slice(0, keys.length - MAX_PATTERN_FILES))
+            delete counts[k];
+    }
+}
+/** The files a lesson names: most often first, ties by name, at most three. */
+export const topFiles = (counts) => Object.entries(counts ?? {})
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .slice(0, MAX_LESSON_FILES)
+    .map(([f]) => f);
+/** A lesson's citation: a short hash of the SONA pattern key, so the key's own text never reaches a prompt. */
+export const lessonId = (patternKey) => `L-${createHash('sha256').update(patternKey).digest('hex').slice(0, 10)}`;
+/**
+ * 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 function buildLessons(patterns, verified, now) {
+    const lessons = [];
+    const held = [];
+    let belowGate = 0;
+    for (const [id, p] of Object.entries(patterns)) {
+        const v = verified[id];
+        if (!v || !p || !Array.isArray(p.keywords))
+            continue;
+        const keywords = p.keywords.filter(k => typeof k === 'string' && SAFE_KEYWORD.test(k)).slice(0, 10);
+        if (keywords.length === 0 || !AGENT.test(p.agent))
+            continue;
+        const base = { id: lessonId(id), agent: p.agent, keywords, confidence: Math.round(p.confidence * 1000) / 1000, successes: p.successCount, failures: p.failureCount, evidence: v.evidence };
+        if (p.failureCount >= CAUTION_MIN_FAILURES && p.failureCount > p.successCount)
+            lessons.push({ ...base, kind: 'caution' });
+        else if (p.confidence >= LESSON_GATE) {
+            const reason = holdReason(v.stats ?? emptyStats(), p.successCount);
+            if (reason)
+                held.push({ id: base.id, reason });
+            else {
+                const files = topFiles(v.files);
+                lessons.push({ ...base, kind: 'lesson', ...(files.length ? { files } : {}) });
+            }
+        }
+        else
+            belowGate++;
+    }
+    lessons.sort((a, b) => b.confidence - a.confidence || b.successes + b.failures - (a.successes + a.failures));
+    held.sort((a, b) => a.id.localeCompare(b.id));
+    return { version: 1, gate: LESSON_GATE, generatedAt: now, lessons: lessons.slice(0, MAX_LESSONS), belowGate, held: held.slice(0, MAX_LESSONS) };
+}
+//# sourceMappingURL=verified-lessons.js.map

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

@@ -26,20 +26,17 @@
  * 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 LoopConfig, type PatternStats, type Taint } from './verified-guards.js';
 import { type ReverifyRunner } from './verified-reverify.js';
+import { type LessonsFile, type PatternExport } from './verified-lessons.js';
+export { buildLessons, CAUTION_MIN_FAILURES, LESSON_GATE, lessonFile, lessonId, MAX_LESSONS, type Lesson, type LessonsFile } from './verified-lessons.js';
 export declare const VERIFIED_PATH: string;
 export declare const LEDGER_PATH: string;
 export declare const LESSONS_PATH: string;
-/** The SONA routing gate (sona-optimizer.ts `SONA_ROUTING_GATE`); a lesson below it never influences routing. */
-export declare const LESSON_GATE = 0.6;
 /** Ingested ids remembered; the mod keeps at most 500 lines, so this always covers the whole file. */
 export declare const MAX_LEDGER_IDS = 2000;
 /** A file past this many bytes is not read (the mod caps its own at far less). */
 export declare const MAX_FILE_BYTES: number;
-export declare const MAX_LESSONS = 20;
-/** Verified failures (and more failures than successes) before a pattern becomes a caution. */
-export declare const CAUTION_MIN_FAILURES = 2;
 export type Outcome = 'verified-success' | 'verified-failure' | 'unknown';
 export type VerifierKind = 'test' | 'build' | 'typecheck' | 'lint';
 export interface VerifiedRecord {
@@ -61,6 +58,8 @@ export interface VerifiedRecord {
     readonly taint: readonly Taint[];
     /** The mod process that recorded it, when the mod wrote one (ADR-503 §2.4). */
     readonly session: string | null;
+    /** ADR-511: files a verified turn edited, screened (`lessonFile`); empty for `unknown`. */
+    readonly files: readonly string[];
     readonly startedAt: number;
     readonly endedAt: number;
 }
@@ -84,6 +83,7 @@ export interface IngestLedger {
         evidence: string;
         at: number;
         stats: PatternStats;
+        files: Record<string, number>;
     }>;
     /** ADR-503 §2.3: the rotation cursor and the latest re-verifications (which commit, which check, what happened). */
     reverify: {
@@ -99,29 +99,6 @@ export interface ReverifyLogEntry {
     readonly at: number;
 }
 export declare const MAX_REVERIFY_LOG = 50;
-export interface Lesson {
-    readonly id: string;
-    readonly kind: 'lesson' | 'caution';
-    readonly agent: string;
-    readonly keywords: string[];
-    readonly confidence: number;
-    readonly successes: number;
-    readonly failures: number;
-    readonly evidence: string;
-}
-export interface LessonsFile {
-    version: 1;
-    gate: number;
-    generatedAt: number;
-    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: {
@@ -166,35 +143,20 @@ export interface SonaLike {
         }>;
         duration?: number;
         feedback?: string;
+        /** ADR-511: the edited files, which decide only which pattern the outcome reinforces. */
+        anchors?: string[];
     }): {
         learned: boolean;
         patternKey: string;
         confidence: number;
     };
-    exportPatterns(): Record<string, {
-        keywords: string[];
-        agent: string;
-        confidence: number;
-        successCount: number;
-        failureCount: number;
-    }>;
+    exportPatterns(): PatternExport;
 }
 /** One line of the mod's file, validated; anything malformed is null. Unknown fields never survive. */
 export declare function parseRecord(line: string): VerifiedRecord | null;
 export declare function emptyLedger(): IngestLedger;
 /** A ledger file read back; a corrupt or hostile one starts over (re-ingest is bounded by the mod's 500-line cap). */
 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. 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;

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

@@ -26,23 +26,19 @@
  * it trains, and an anomaly gate holds suspicious patterns back from the
  * prompt. Every one of these can only downgrade.
  */
-import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { addOutcome, blockedTaints, emptyStats, holdReason, parseStats, parseTaint, readLoopConfig } from './verified-guards.js';
+import { addOutcome, blockedTaints, emptyStats, parseStats, parseTaint, readLoopConfig } from './verified-guards.js';
 import { gitWorktreeRunner, ReverifySession } from './verified-reverify.js';
+import { addFiles, buildLessons, parseFileCounts, recordFiles } from './verified-lessons.js';
+export { buildLessons, CAUTION_MIN_FAILURES, LESSON_GATE, lessonFile, lessonId, MAX_LESSONS } from './verified-lessons.js';
 export const VERIFIED_PATH = join('.claude-flow', 'data', 'verified-trajectories.jsonl');
 export const LEDGER_PATH = join('.claude-flow', 'data', 'verified-ingest.json');
 export const LESSONS_PATH = join('.claude-flow', 'data', 'learned-lessons.json');
-/** The SONA routing gate (sona-optimizer.ts `SONA_ROUTING_GATE`); a lesson below it never influences routing. */
-export const LESSON_GATE = 0.6;
 /** Ingested ids remembered; the mod keeps at most 500 lines, so this always covers the whole file. */
 export const MAX_LEDGER_IDS = 2000;
 /** A file past this many bytes is not read (the mod caps its own at far less). */
 export const MAX_FILE_BYTES = 2 * 1024 * 1024;
-export const MAX_LESSONS = 20;
-/** Verified failures (and more failures than successes) before a pattern becomes a caution. */
-export const CAUTION_MIN_FAILURES = 2;
 export const MAX_REVERIFY_LOG = 50;
 const OUTCOMES = ['verified-success', 'verified-failure', 'unknown'];
 const KINDS = ['test', 'build', 'typecheck', 'lint'];
@@ -92,7 +88,8 @@ export function parseRecord(line) {
         : [];
     const taint = outcome === 'verified-success' ? parseTaint(r.taint) : [];
     const session = typeof r.session === 'string' && /^[A-Za-z0-9_-]{1,40}$/.test(r.session) ? r.session : null;
-    return { id: r.id, task, agent, outcome, verifier, steps, edits: num(r.edits, 10_000), taint, session, startedAt: num(r.startedAt), endedAt: num(r.endedAt) };
+    const files = outcome === 'unknown' ? [] : recordFiles(r.files);
+    return { id: r.id, task, agent, outcome, verifier, steps, edits: num(r.edits, 10_000), taint, session, files, startedAt: num(r.startedAt), endedAt: num(r.endedAt) };
 }
 export function emptyLedger() {
     return { version: 1, ids: [], lastMtimeMs: 0, totals: { verifiedSuccess: 0, verifiedFailure: 0, unknown: 0, rejected: 0, tainted: 0 }, patterns: {}, reverify: { cursor: 0, log: [] } };
@@ -110,7 +107,7 @@ export function readLedger(raw) {
         for (const [k, v] of Object.entries(j.patterns && typeof j.patterns === 'object' ? j.patterns : {})) {
             if (k === '__proto__' || typeof k !== 'string' || k.length > 400 || !v || typeof v !== 'object')
                 continue;
-            patterns[k] = { evidence: text(v.evidence, 80), at: num(v.at), stats: parseStats(v.stats) };
+            patterns[k] = { evidence: text(v.evidence, 80), at: num(v.at), stats: parseStats(v.stats), files: parseFileCounts(v.files) };
         }
         const rv = (j.reverify && typeof j.reverify === 'object' ? j.reverify : {});
         const STATUS = ['pass', 'fail', 'timeout', 'error'];
@@ -141,42 +138,6 @@ async function redact(task) {
         return task;
     }
 }
-/** Keywords a lesson may show: SONA keeps any non-separator text, the prompt gets only plain words. */
-const SAFE_KEYWORD = /^[a-z0-9][a-z0-9 _./-]{0,40}$/;
-/** A lesson's citation: a short hash of the SONA pattern key, so the key's own text never reaches a prompt. */
-export const lessonId = (patternKey) => `L-${createHash('sha256').update(patternKey).digest('hex').slice(0, 10)}`;
-/**
- * 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 function buildLessons(patterns, verified, now) {
-    const lessons = [];
-    const held = [];
-    let belowGate = 0;
-    for (const [id, p] of Object.entries(patterns)) {
-        const v = verified[id];
-        if (!v || !p || !Array.isArray(p.keywords))
-            continue;
-        const keywords = p.keywords.filter(k => typeof k === 'string' && SAFE_KEYWORD.test(k)).slice(0, 10);
-        if (keywords.length === 0 || !AGENT.test(p.agent))
-            continue;
-        const base = { id: lessonId(id), agent: p.agent, keywords, confidence: Math.round(p.confidence * 1000) / 1000, successes: p.successCount, failures: p.failureCount, evidence: v.evidence };
-        if (p.failureCount >= CAUTION_MIN_FAILURES && p.failureCount > p.successCount)
-            lessons.push({ ...base, kind: 'caution' });
-        else if (p.confidence >= LESSON_GATE) {
-            const reason = holdReason(v.stats ?? emptyStats(), p.successCount);
-            if (reason)
-                held.push({ id: base.id, reason });
-            else
-                lessons.push({ ...base, kind: 'lesson' });
-        }
-        else
-            belowGate++;
-    }
-    lessons.sort((a, b) => b.confidence - a.confidence || b.successes + b.failures - (a.successes + a.failures));
-    held.sort((a, b) => a.id.localeCompare(b.id));
-    return { version: 1, gate: LESSON_GATE, generatedAt: now, lessons: lessons.slice(0, MAX_LESSONS), belowGate, held: held.slice(0, MAX_LESSONS) };
-}
 function writeAtomic(path, body) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.tmp`;
@@ -299,12 +260,16 @@ export async function ingestVerifiedOutcomes(options = {}) {
             steps: record.steps.map(s => ({ action: s.tool, result: s.ok ? 'ok' : 'error', quality: s.ok ? 1 : 0, timestamp: new Date(record.endedAt || now).toISOString() })),
             duration: record.endedAt > record.startedAt ? record.endedAt - record.startedAt : 0,
             feedback: `verified by ${record.verifier.kind}: ${record.verifier.command}`,
+            // ADR-511: a failure anchors too, so a reworded failure lowers the same lesson; only a success names files.
+            anchors: [...record.files],
         });
         if (result.learned && result.patternKey) {
-            const entry = ledger.patterns[result.patternKey] ?? { evidence: '', at: now, stats: emptyStats() };
+            const entry = ledger.patterns[result.patternKey] ?? { evidence: '', at: now, stats: emptyStats(), files: {} };
             entry.evidence = record.verifier.command;
             entry.at = now;
             addOutcome(entry.stats, success, record.taint, record.session);
+            if (success)
+                addFiles(entry.files, record.files);
             ledger.patterns[result.patternKey] = entry;
         }
         if (success)

package/dist/src/update/rate-limiter.d.ts

@@ -10,6 +10,12 @@ export interface RateLimitState {
 }
 export declare function loadState(): RateLimitState;
 export declare function saveState(state: RateLimitState): void;
+/**
+ * Whether this is a CI run. CI systems set `CI` to `true`, `1` or other values, so any value
+ * except empty, `0` or `false` counts (GitHub Actions sets CI=true). Matching only `true` let CI=1 runs check for updates and
+ * install one (`npm install @claude-flow/cli@<latest>`) into the working directory mid-run.
+ */
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
 export declare function shouldCheckForUpdates(intervalHours?: number): {
     allowed: boolean;
     reason?: string;

package/dist/src/update/rate-limiter.js

@@ -45,9 +45,20 @@ export function saveState(state) {
     ensureDir();
     fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
 }
+/**
+ * Whether this is a CI run. CI systems set `CI` to `true`, `1` or other values, so any value
+ * except empty, `0` or `false` counts (GitHub Actions sets CI=true). Matching only `true` let CI=1 runs check for updates and
+ * install one (`npm install @claude-flow/cli@<latest>`) into the working directory mid-run.
+ */
+export function isCI(env = process.env) {
+    return ['CI', 'CONTINUOUS_INTEGRATION'].some((name) => {
+        const value = env[name];
+        return value !== undefined && value.trim() !== '' && !/^(0|false)$/i.test(value.trim());
+    });
+}
 export function shouldCheckForUpdates(intervalHours = DEFAULT_INTERVAL_HOURS) {
     // Skip in CI environments
-    if (process.env.CI === 'true' || process.env.CONTINUOUS_INTEGRATION === 'true') {
+    if (isCI()) {
         return { allowed: false, reason: 'CI environment detected' };
     }
     // Skip if explicitly disabled

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.65.0",
+  "version": "3.66.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",