@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/agent/self-improvement/evolution/worktree-scorer.js

@@ -0,0 +1,99 @@
+/**
+ * Worktree scorer (Phase B): materialize a git BRANCH in an isolated worktree, score it with the
+ * variant-fitness harness, then tear the worktree down. This is how a candidate variant is
+ * evaluated without touching the working tree or `main`.
+ *
+ * node_modules is symlinked from the base repo (git worktrees don't copy gitignored deps), which is
+ * correct as long as the variant didn't change dependencies (the common case; a deps change is a
+ * rare edge handled by a real install — flagged, not silently wrong). Disk is preflighted via the
+ * disk-guard. The worktree is always cleaned up (finally), the branch is kept as the artifact.
+ *
+ * @module agent/self-improvement/evolution/worktree-scorer
+ */
+import { existsSync, symlinkSync } from 'fs';
+import { join } from 'path';
+import { logger } from '../../../utils/logger.js';
+import { WorktreeSessionManager } from '../../../git/worktree-sessions.js';
+import { ensureFreeSpace } from '../../../utils/disk-guard.js';
+import { computeFitness, defaultDeterministicComponents, } from './variant-fitness.js';
+import { assertNoProtectedChanges, resetProtectedToBaseline } from './protected-paths.js';
+import { scrubbedEnv } from './scrub-env.js';
+/**
+ * Score a branch in an isolated worktree. The branch must NOT be the one currently checked out in
+ * `basePath` (git refuses to add a worktree for an already-checked-out branch). Never throws on
+ * cleanup; throws only if the worktree cannot be created.
+ */
+export async function scoreBranchInWorktree(branch, opts = {}) {
+    const basePath = opts.basePath ?? process.cwd();
+    const components = opts.components ?? defaultDeterministicComponents();
+    // Anti-self-weakening: reject a variant that changes any protected path (gates/benchmarks/
+    // held-out/harness) BEFORE building or scoring it. The core Phase-C guard.
+    if (opts.baselineRef) {
+        const check = assertNoProtectedChanges(branch, opts.baselineRef, basePath);
+        if (!check.ok) {
+            return {
+                branch,
+                worktreePath: '',
+                report: {
+                    score: 0,
+                    passedAll: false,
+                    regressions: [],
+                    components: [
+                        {
+                            name: 'protected-violation',
+                            weight: 1,
+                            score: 0,
+                            passed: false,
+                            detail: `variant changes protected paths: ${check.violations.join(', ')}`,
+                        },
+                    ],
+                },
+            };
+        }
+    }
+    // Preflight disk so a build/test loop can't fill the disk (disk-guard; throws if too low).
+    ensureFreeSpace(basePath, undefined, { label: 'evolve worktree' });
+    const mgr = WorktreeSessionManager.getInstance();
+    const session = mgr.createWorktreeSession(branch, basePath);
+    // Default scoring env: secrets stripped AND HOME redirected into the
+    // worktree so the variant's own code (which runs under `npx vitest`) cannot
+    // read `~/.codebuddy/*.json` credential files and exfiltrate them.
+    const env = opts.env ?? (opts.scrubEnv === false ? process.env : scrubbedEnv(process.env, { homeDir: session.worktreePath }));
+    try {
+        if (opts.linkNodeModules !== false) {
+            linkNodeModules(basePath, session.worktreePath);
+        }
+        // Defense-in-depth: even if detection missed something, restore protected paths to baseline.
+        if (opts.baselineRef) {
+            resetProtectedToBaseline(session.worktreePath, opts.baselineRef);
+        }
+        const ctx = {
+            checkoutDir: session.worktreePath,
+            env,
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+        };
+        const report = await computeFitness(ctx, components, opts.baseline);
+        return { branch, worktreePath: session.worktreePath, report };
+    }
+    finally {
+        try {
+            mgr.cleanupWorktree(branch);
+        }
+        catch (err) {
+            logger.warn(`[evolve] worktree cleanup failed for ${branch}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+}
+function linkNodeModules(basePath, worktreePath) {
+    const src = join(basePath, 'node_modules');
+    const dest = join(worktreePath, 'node_modules');
+    if (!existsSync(src) || existsSync(dest))
+        return;
+    try {
+        symlinkSync(src, dest, 'dir');
+    }
+    catch (err) {
+        logger.warn(`[evolve] node_modules symlink failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=worktree-scorer.js.map

package/dist/agent/self-improvement/evolutionary-archive.js

@@ -8,6 +8,7 @@
  */
 import fs from 'fs';
 import path from 'path';
+import { readJsonAtomicSync, writeJsonAtomicSync } from '../../utils/atomic-write.js';
 export const SELF_IMPROVEMENT_ARCHIVE_SCHEMA_VERSION = 1;
 export class EvolutionaryArchive {
     filePath;
@@ -22,7 +23,7 @@ export class EvolutionaryArchive {
     }
     read() {
         try {
-            const parsed = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+            const parsed = readJsonAtomicSync(this.filePath, {}, { mode: 0o600 });
             if (Array.isArray(parsed.entries)) {
                 return { schemaVersion: SELF_IMPROVEMENT_ARCHIVE_SCHEMA_VERSION, entries: parsed.entries };
             }
@@ -34,7 +35,7 @@ export class EvolutionaryArchive {
     }
     write(file) {
         fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
-        fs.writeFileSync(this.filePath, JSON.stringify(file, null, 2), 'utf-8');
+        writeJsonAtomicSync(this.filePath, file, { mode: 0o600 });
     }
     list() {
         return this.read().entries;

package/dist/agent/self-improvement/experience-source.d.ts

@@ -12,6 +12,7 @@
  * @module agent/self-improvement/experience-source
  */
 import type { Experience } from './types.js';
+export { EvolutionNotesExperienceSource, createDefaultEvolutionNotesExperienceSource, type EvolutionNotesExperienceSourceOptions, DelegationLogsExperienceSource, createDefaultDelegationLogsExperienceSource, type DelegationLogsExperienceSourceOptions, type DelegationFact, NAMED_DELEGATION_FAILURES, PILOT_LESSONS, } from './digest-sources.js';
 export interface ExperienceSource {
     readonly id: string;
     collect(): Promise<Experience[]>;
@@ -55,15 +56,67 @@ export declare function createDefaultRunExperienceSource(options?: {
     limit?: number;
 }): ExperienceSource;
 /**
- * SENSOR SEAM (robot future, interface-only). When the robot grants senses, a
- * world-model (JEPA) encodes each modality into a latent z and predicts z_{t+1};
- * the prediction error / latent surprise becomes the Experience signal here, and
- * the engine improves the policies/skills that reduce that surprise — the exact
- * same observe→propose→validate→keep loop, no engine change. NOT implemented in
- * V1: it must not silently emit experiences.
+ * SENSOR SEAM (the robot's 5 senses → the learning engine). The world-model
+ * (JEPA) encodes each modality into a latent z and predicts z_{t+1}; the
+ * prediction error ‖z_pred − z_target‖ is SURPRISE — the signal that the
+ * robot's model of the world was wrong. Each surprise becomes an Experience,
+ * and the engine improves the policies/skills that reduce it — the exact same
+ * observe→propose→validate→keep loop, no engine change.
+ */
+export interface SensorSurprise {
+    /** Modality that produced the surprise (vision, audio, screen, …). */
+    modality?: string;
+    /** Short machine label (e.g. `novel-scene`, `motion-unexpected`). */
+    kind?: string;
+    /** Human-readable description of what was (un)expected. */
+    detail?: string;
+    /** Prediction error magnitude ‖z_pred − z_target‖ (unnormalized, > 0). */
+    predictionError: number;
+    /** Wall-clock or sense-relative timestamp (ms) — used for the stable id. */
+    tsMs?: number;
+    /** Free-text context (scene/env id, frame path, …). */
+    context?: string;
+}
+export interface SensorExperienceSourceDeps {
+    /**
+     * Pull recent surprise events from the world model (A2A spoke / ONNX
+     * side-car). Injected so the class stays unit-testable and transport-free.
+     */
+    fetchSurprises: () => Promise<SensorSurprise[]>;
+    /** predictionError at or above this maps to severity 1 (default 1.0). */
+    errorScale?: number;
+    /** Cap on experiences per collect (default 50). */
+    limit?: number;
+}
+/**
+ * Turns world-model latent surprise into Experiences. NEVER throws: a dead or
+ * missing world-model endpoint yields [] (the engine simply learns from other
+ * sources), and malformed entries (non-finite / non-positive error) are
+ * skipped — a broken sensor must not poison the curriculum.
  */
 export declare class SensorExperienceSource implements ExperienceSource {
+    private readonly deps;
     readonly id = "sensor-surprise";
+    constructor(deps: SensorExperienceSourceDeps);
     collect(): Promise<Experience[]>;
 }
-export {};
+/**
+ * Wire SensorExperienceSource to the live world model.
+ *
+ * Opt-in & fail-open: unless `CODEBUDDY_WORLD_MODEL=true`, collect() returns []
+ * (the seam must not silently emit experiences). When enabled it polls the
+ * world-model side-car over HTTP — `CODEBUDDY_WORLD_MODEL_URL` (default
+ * `http://127.0.0.1:3061`), REST contract:
+ *
+ *   GET {base}/surprises →
+ *     { "surprises": [ { "modality": "vision", "kind": "novel-scene",
+ *       "predictionError": 0.42, "tsMs": 1760000000000,
+ *       "detail": "...", "context": "..." } ] }
+ *
+ * The GPU_NODE world-model spoke (encoder ONNX + dynamics) serves this; any
+ * error/timeout (3 s) yields [] so a dead spoke never blocks the engine.
+ */
+export declare function createDefaultSensorExperienceSource(options?: {
+    errorScale?: number;
+    limit?: number;
+}): ExperienceSource;

package/dist/agent/self-improvement/experience-source.js

@@ -11,6 +11,8 @@
  *
  * @module agent/self-improvement/experience-source
  */
+import { logger } from '../../utils/logger.js';
+export { EvolutionNotesExperienceSource, createDefaultEvolutionNotesExperienceSource, DelegationLogsExperienceSource, createDefaultDelegationLogsExperienceSource, NAMED_DELEGATION_FAILURES, PILOT_LESSONS, } from './digest-sources.js';
 const SEVERITY_SCORE = {
     low: 0.3,
     medium: 0.6,
@@ -75,18 +77,86 @@ export function createDefaultRunExperienceSource(options = {}) {
     };
 }
 /**
- * SENSOR SEAM (robot future, interface-only). When the robot grants senses, a
- * world-model (JEPA) encodes each modality into a latent z and predicts z_{t+1};
- * the prediction error / latent surprise becomes the Experience signal here, and
- * the engine improves the policies/skills that reduce that surprise — the exact
- * same observe→propose→validate→keep loop, no engine change. NOT implemented in
- * V1: it must not silently emit experiences.
+ * Turns world-model latent surprise into Experiences. NEVER throws: a dead or
+ * missing world-model endpoint yields [] (the engine simply learns from other
+ * sources), and malformed entries (non-finite / non-positive error) are
+ * skipped — a broken sensor must not poison the curriculum.
  */
 export class SensorExperienceSource {
+    deps;
     id = 'sensor-surprise';
+    constructor(deps) {
+        this.deps = deps;
+    }
     async collect() {
-        throw new Error('SensorExperienceSource is the robot 5-senses seam and is not implemented in V1. ' +
-            'Wire a world-model (JEPA) latent prediction-error stream here when sensors are available.');
+        const scale = this.deps.errorScale && this.deps.errorScale > 0 ? this.deps.errorScale : 1;
+        const limit = Math.max(1, this.deps.limit ?? 50);
+        let surprises;
+        try {
+            surprises = await this.deps.fetchSurprises();
+        }
+        catch (err) {
+            logger.warn(`SensorExperienceSource: world-model surprise fetch failed — no sensor experiences this cycle: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+        if (!Array.isArray(surprises))
+            return [];
+        const experiences = [];
+        for (const [index, s] of surprises.entries()) {
+            if (experiences.length >= limit)
+                break;
+            const err = typeof s?.predictionError === 'number' ? s.predictionError : NaN;
+            if (!Number.isFinite(err) || err <= 0)
+                continue;
+            const modality = s.modality ?? 'unknown';
+            experiences.push({
+                id: `sensor:${modality}:${s.tsMs ?? index}`,
+                source: 'sensor',
+                kind: s.kind ?? modality,
+                detail: s.detail ?? `world-model prediction error ${err.toFixed(4)} on ${modality}`,
+                context: s.context ?? '',
+                severity: Math.min(1, err / scale),
+            });
+        }
+        return experiences;
     }
 }
+/**
+ * Wire SensorExperienceSource to the live world model.
+ *
+ * Opt-in & fail-open: unless `CODEBUDDY_WORLD_MODEL=true`, collect() returns []
+ * (the seam must not silently emit experiences). When enabled it polls the
+ * world-model side-car over HTTP — `CODEBUDDY_WORLD_MODEL_URL` (default
+ * `http://127.0.0.1:3061`), REST contract:
+ *
+ *   GET {base}/surprises →
+ *     { "surprises": [ { "modality": "vision", "kind": "novel-scene",
+ *       "predictionError": 0.42, "tsMs": 1760000000000,
+ *       "detail": "...", "context": "..." } ] }
+ *
+ * The GPU_NODE world-model spoke (encoder ONNX + dynamics) serves this; any
+ * error/timeout (3 s) yields [] so a dead spoke never blocks the engine.
+ */
+export function createDefaultSensorExperienceSource(options = {}) {
+    return {
+        id: 'sensor-surprise',
+        async collect() {
+            if (process.env.CODEBUDDY_WORLD_MODEL !== 'true')
+                return [];
+            const base = (process.env.CODEBUDDY_WORLD_MODEL_URL ?? 'http://127.0.0.1:3061').replace(/\/$/, '');
+            const source = new SensorExperienceSource({
+                ...(options.errorScale !== undefined ? { errorScale: options.errorScale } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                fetchSurprises: async () => {
+                    const res = await fetch(`${base}/surprises`, { signal: AbortSignal.timeout(3000) });
+                    if (!res.ok)
+                        throw new Error(`world-model spoke HTTP ${res.status}`);
+                    const body = (await res.json());
+                    return Array.isArray(body?.surprises) ? body.surprises : [];
+                },
+            });
+            return source.collect();
+        },
+    };
+}
 //# sourceMappingURL=experience-source.js.map

package/dist/agent/self-improvement/index.d.ts

@@ -19,6 +19,7 @@ export * from './execution-gate.js';
 export * from './paired-gate.js';
 export * from './paired-runner.js';
 export * from './rule-store.js';
+export * from './digest.js';
 export { SelfImprovementEngine, resolveAutonomy, type Autonomy } from './engine.js';
 /** Adapt the real (offline, deterministic) LessonsTracker to the mutator port. */
 export declare function createLessonMutatorPort(workDir?: string): LessonMutatorPort;

package/dist/agent/self-improvement/index.js

@@ -23,6 +23,7 @@ export * from './execution-gate.js';
 export * from './paired-gate.js';
 export * from './paired-runner.js';
 export * from './rule-store.js';
+export * from './digest.js';
 export { SelfImprovementEngine, resolveAutonomy } from './engine.js';
 /** Adapt the real (offline, deterministic) LessonsTracker to the mutator port. */
 export function createLessonMutatorPort(workDir = process.cwd()) {
@@ -44,10 +45,12 @@ export function createLessonMutatorPort(workDir = process.cwd()) {
 export function createWorkspaceEngine(options = {}) {
     const workDir = options.workDir ?? process.cwd();
     // Default proposer is the deterministic, offline bootstrap pack. `useLlm`
-    // swaps in the model-backed proposer that discovers novel lessons from
-    // friction — still gated by the same deterministic empirical validator.
+    // or env CODEBUDDY_SELF_IMPROVE_PROPOSER=llm swaps in the model-backed proposer
+    // that discovers novel lessons from friction — still gated by the same deterministic empirical validator.
+    const wantsLlm = options.useLlm === true ||
+        process.env.CODEBUDDY_SELF_IMPROVE_PROPOSER?.trim().toLowerCase() === 'llm';
     const proposer = options.proposer ??
-        (options.useLlm ? new LlmProposer(createLlmDrafter()) : new StaticProposer(SEED_LESSON_DRAFTS));
+        (wantsLlm ? new LlmProposer(createLlmDrafter()) : new StaticProposer(SEED_LESSON_DRAFTS));
     return new SelfImprovementEngine({
         scenarios: SEED_BENCHMARK_SCENARIOS,
         port: createLessonMutatorPort(workDir),

package/dist/agent/self-improvement/learning-store.d.ts

@@ -47,6 +47,16 @@ export interface StoreVersion {
     /** Null for commits that predate a manifest (e.g. the init commit). */
     score: BenchmarkScore | null;
 }
+/** Read-only materialisation used by reporting/audit consumers. */
+export interface LearningStoreSnapshotVersion {
+    sha: string;
+    createdAt: string;
+    reason: string;
+    score: BenchmarkScore | null;
+    lessons: LessonSnapshot[];
+    scenarioId?: string;
+    delta?: number;
+}
 export interface LearningStoreOptions {
     workDir?: string;
     port: LearnableStatePort;
@@ -74,6 +84,12 @@ export declare class LearningStore {
     }>;
     /** List versions (newest first) with their committed benchmark score. */
     listVersions(): Promise<StoreVersion[]>;
+    /**
+     * List versioned lesson snapshots without mutating the store. This is kept
+     * separate from `listVersions()` because normal status output should not pay
+     * the extra `git show` calls needed to reconstruct lesson history.
+     */
+    listVersionSnapshots(): Promise<LearningStoreSnapshotVersion[]>;
     /** The highest-scoring version (ties → most recent). The "version qui marche mieux". */
     bestVersion(): Promise<StoreVersion | null>;
     /**

package/dist/agent/self-improvement/learning-store.js

@@ -20,6 +20,7 @@
 import { spawn } from 'child_process';
 import fs from 'fs';
 import path from 'path';
+import { writeJsonAtomicSync } from '../../utils/atomic-write.js';
 export const LEARNING_STORE_SCHEMA_VERSION = 1;
 const GIT_IDENTITY = [
     '-c', 'user.name=Code Buddy Self-Improve',
@@ -58,13 +59,19 @@ export class LearningStore {
         if (this.isRepo)
             return;
         fs.mkdirSync(this.storeDir, { recursive: true });
-        await this.runGit(['init', '-q']);
+        const init = await this.runGit(['init', '-q']);
+        // Fail loudly if git is unavailable: a silent no-op here made commitVersion
+        // return a fake success (sha '') while nothing was persisted, voiding the
+        // reversibility guarantee. Better an honest throw the caller can log.
+        if (init.code !== 0 || !this.isRepo) {
+            throw new Error(`learning store: git init failed (git unavailable?): ${init.stderr.trim() || `exit ${init.code}`}`);
+        }
         fs.writeFileSync(path.join(this.storeDir, '.gitignore'), '', 'utf-8');
         await this.runGit(['add', '-A']);
         await this.runGit([...GIT_IDENTITY, 'commit', '-q', '--allow-empty', '-m', 'init: learning store']);
     }
     writeSnapshot(manifest) {
-        const write = (name, value) => fs.writeFileSync(path.join(this.storeDir, name), JSON.stringify(value, null, 2), 'utf-8');
+        const write = (name, value) => writeJsonAtomicSync(path.join(this.storeDir, name), value, { mode: 0o600 });
         write('lessons.json', this.port.listLessons());
         write('archive.json', this.port.archive());
         if (this.port.listRules)
@@ -89,8 +96,14 @@ export class LearningStore {
             ? `improve(${options.scenarioId}): +${options.delta} coverage ${score.covered}/${score.total}`
             : `${options.reason} — coverage ${score.covered}/${score.total}`;
         const message = `${subject}\n\nCo-Authored-By: Code Buddy Self-Improve <self-improve@codebuddy.local>`;
-        await this.runGit([...GIT_IDENTITY, 'commit', '-q', '--allow-empty', '-m', message]);
+        const commit = await this.runGit([...GIT_IDENTITY, 'commit', '-q', '--allow-empty', '-m', message]);
         const sha = (await this.runGit(['rev-parse', 'HEAD'])).stdout.trim();
+        // The version is only reversible if it was actually committed. A blank or
+        // non-sha result means git silently failed — surface it instead of
+        // returning a fake `{ sha: '' }` success.
+        if (commit.code !== 0 || !/^[0-9a-f]{7,40}$/.test(sha)) {
+            throw new Error(`learning store: version commit did not persist (git error) — reversibility not guaranteed: ${commit.stderr.trim() || `exit ${commit.code}`}`);
+        }
         return { sha, score };
     }
     /** List versions (newest first) with their committed benchmark score. */
@@ -124,6 +137,73 @@ export class LearningStore {
         }
         return versions;
     }
+    /**
+     * List versioned lesson snapshots without mutating the store. This is kept
+     * separate from `listVersions()` because normal status output should not pay
+     * the extra `git show` calls needed to reconstruct lesson history.
+     */
+    async listVersionSnapshots() {
+        const versions = await this.listVersions();
+        const snapshots = [];
+        for (const version of versions) {
+            const [manifestShow, lessonsShow] = await Promise.all([
+                this.runGit(['show', `${version.sha}:manifest.json`]),
+                this.runGit(['show', `${version.sha}:lessons.json`]),
+            ]);
+            let manifest = null;
+            if (manifestShow.code === 0) {
+                try {
+                    const parsed = JSON.parse(manifestShow.stdout);
+                    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                        manifest = parsed;
+                    }
+                }
+                catch {
+                    manifest = null;
+                }
+            }
+            let lessons = [];
+            if (lessonsShow.code === 0) {
+                try {
+                    const parsed = JSON.parse(lessonsShow.stdout);
+                    if (Array.isArray(parsed)) {
+                        lessons = parsed.filter((lesson) => {
+                            if (!lesson || typeof lesson !== 'object' || Array.isArray(lesson))
+                                return false;
+                            const record = lesson;
+                            return ((record.category === 'PATTERN' ||
+                                record.category === 'RULE' ||
+                                record.category === 'CONTEXT' ||
+                                record.category === 'INSIGHT') &&
+                                typeof record.content === 'string' &&
+                                (record.context === undefined || typeof record.context === 'string'));
+                        });
+                    }
+                }
+                catch {
+                    lessons = [];
+                }
+            }
+            const generatedAt = typeof manifest?.generatedAt === 'string' &&
+                Number.isFinite(Date.parse(manifest.generatedAt))
+                ? manifest.generatedAt
+                : version.createdAt;
+            snapshots.push({
+                sha: version.sha,
+                createdAt: generatedAt,
+                reason: typeof manifest?.reason === 'string' && manifest.reason.trim()
+                    ? manifest.reason
+                    : version.message,
+                score: manifest?.score ?? version.score,
+                lessons,
+                ...(typeof manifest?.scenarioId === 'string' ? { scenarioId: manifest.scenarioId } : {}),
+                ...(typeof manifest?.delta === 'number' && Number.isFinite(manifest.delta)
+                    ? { delta: manifest.delta }
+                    : {}),
+            });
+        }
+        return snapshots;
+    }
     /** The highest-scoring version (ties → most recent). The "version qui marche mieux". */
     async bestVersion() {
         const scored = (await this.listVersions()).filter((v) => v.score !== null);

package/dist/agent/self-improvement/llm-drafter.d.ts

@@ -8,4 +8,6 @@
  * @module agent/self-improvement/llm-drafter
  */
 import { type LessonDrafter } from './proposer.js';
-export declare function createLlmDrafter(): LessonDrafter;
+export declare function createLlmDrafter(options?: {
+    explicitModel?: string;
+}): LessonDrafter;

package/dist/agent/self-improvement/llm-drafter.js

@@ -8,12 +8,18 @@
  * @module agent/self-improvement/llm-drafter
  */
 import { buildLessonDraftPrompt } from './proposer.js';
-export function createLlmDrafter() {
+export function createLlmDrafter(options = {}) {
     let clientPromise = null;
     const getClient = () => {
         if (!clientPromise) {
             clientPromise = (async () => {
                 try {
+                    const { resolveCommandProvider } = await import('../../commands/llm-provider-resolution.js');
+                    const resolved = resolveCommandProvider(options.explicitModel ? { explicitModel: options.explicitModel } : {});
+                    if (resolved?.apiKey) {
+                        const { CodeBuddyClient } = await import('../../codebuddy/client.js');
+                        return new CodeBuddyClient(resolved.apiKey, resolved.model, resolved.baseURL);
+                    }
                     const { detectProviderFromEnv } = await import('../../utils/provider-detector.js');
                     const { CodeBuddyClient } = await import('../../codebuddy/client.js');
                     const detected = detectProviderFromEnv();
@@ -33,7 +39,19 @@ export function createLlmDrafter() {
         if (!client)
             return null;
         try {
-            const prompt = buildLessonDraftPrompt(scenario, experiences);
+            // Ground the draft in the collective AI knowledge base (CKG) when it has been fed —
+            // ingested AI research makes self-improvement easier and better-founded. Optional/empty-safe.
+            let knowledge = [];
+            try {
+                const { getCollectiveKnowledgeGraph } = await import('../../memory/collective-knowledge-graph.js');
+                const q = `${scenario.query ?? ''} ${scenario.description ?? ''}`.trim();
+                // Hybrid (semantic+keyword) retrieval — degrades to keyword if embeddings are unavailable.
+                knowledge = (await getCollectiveKnowledgeGraph().recallHybrid(q, { limit: 3 })).map((r) => r.text);
+            }
+            catch {
+                /* CKG optional — proceed with no external knowledge */
+            }
+            const prompt = buildLessonDraftPrompt(scenario, experiences, knowledge);
             const response = await client.chat([{ role: 'user', content: prompt }], []);
             const text = response?.choices?.[0]?.message?.content?.trim();
             if (!text)

package/dist/agent/self-improvement/llm-tool-proposer.js

@@ -12,7 +12,7 @@
 import { AUTHORED_LANGUAGES, toAuthoredName } from './authored-tool-runtime.js';
 export function buildToolDraftPrompt(view) {
     const examples = view.visibleCases
-        .map((c, i) => `  ${i + 1}. input ${JSON.stringify(c.input)} → output must contain ${JSON.stringify(c.expectIncludes)}`)
+        .map((c, i) => `  ${i + 1}. input ${JSON.stringify(c.input)} → output must equal ${JSON.stringify(c.expectedOutput)}`)
         .join('\n');
     return [
         `Author a small, self-contained tool for this capability:`,

package/dist/agent/self-improvement/proposal-store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pending self-improvement proposals — durable propose-only candidates.
+ *
+ * `improve tools` / `improve skills` without `--apply` used to validate a
+ * candidate then throw it away, so "re-run with --apply" re-authored from
+ * scratch. Accepted proposals (candidate + gate evidence) now land under
+ * `.codebuddy/self-improvement/proposals/` and `--apply` reuses them.
+ *
+ * @module agent/self-improvement/proposal-store
+ */
+import type { SkillGateOutcome, SkillProposal } from './skill-types.js';
+import type { ToolGateOutcome, ToolProposal } from './tool-types.js';
+export declare const PENDING_PROPOSAL_SCHEMA_VERSION = 1;
+export type PendingProposalKind = 'tool' | 'skill';
+export interface PendingToolProposalRecord {
+    schemaVersion: typeof PENDING_PROPOSAL_SCHEMA_VERSION;
+    kind: 'tool';
+    scenarioId: string;
+    acceptedAt: string;
+    proposal: ToolProposal;
+    gate: ToolGateOutcome;
+}
+export interface PendingSkillProposalRecord {
+    schemaVersion: typeof PENDING_PROPOSAL_SCHEMA_VERSION;
+    kind: 'skill';
+    scenarioId: string;
+    acceptedAt: string;
+    proposal: SkillProposal;
+    gate: SkillGateOutcome;
+}
+export type PendingProposalRecord = PendingToolProposalRecord | PendingSkillProposalRecord;
+export interface PendingProposalStoreOptions {
+    workDir?: string;
+}
+export declare class PendingProposalStore {
+    readonly dir: string;
+    constructor(options?: PendingProposalStoreOptions);
+    pathFor(kind: PendingProposalKind, scenarioId: string): string;
+    saveTool(record: Omit<PendingToolProposalRecord, 'schemaVersion' | 'kind'>): PendingToolProposalRecord;
+    saveSkill(record: Omit<PendingSkillProposalRecord, 'schemaVersion' | 'kind'>): PendingSkillProposalRecord;
+    loadTool(scenarioId: string): PendingToolProposalRecord | null;
+    loadSkill(scenarioId: string): PendingSkillProposalRecord | null;
+    remove(kind: PendingProposalKind, scenarioId: string): boolean;
+    private write;
+    private read;
+}