@voybio/ace-swarm 2.4.9 → 2.4.10

package/dist/learned-artifacts.js

@@ -0,0 +1,321 @@
+import { learningLifecycle } from './learning-lifecycle.js';
+import { decodeLearned } from './learning-records.js';
+export { decodeLearned } from './learning-records.js';
+import { readLearningPolicy, learningScopeKey, canonicalLearningScopeKey } from './learning-policy.js';
+/** Checked learned artifacts live in existing playbook / knowledge owners. */
+import { createHash } from 'node:crypto';
+import { parse, stringify } from 'yaml';
+import { join } from 'node:path';
+import { GoalRepository, defaultGoalBudgets } from './store/repositories/goal-repository.js';
+import { createTaskPlan, amendTaskPlan } from './orchestrator-supervisor.js';
+import { PlaybookRepository, withPlaybookTransaction } from './store/repositories/playbook-repository.js';
+import { listStoreKeysSync, readStoreBlobSync, getWorkspaceStorePath } from './store/store-snapshot.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+import { openStore } from './store/ace-packed-store.js';
+import { ContentSource } from './store/types.js';
+import { operationalArtifactKey } from './store/store-artifacts.js';
+import { listEpisodes, compactEpisode } from './host-learning.js';
+import { exactRedGreen } from './experience-reflector.js';
+import { proveLearnedSkill } from './skill-auditor.js';
+import { ALL_AGENTS, DEFAULTS_SKILLS_ROOT } from './helpers/constants.js';
+import { existsSync } from 'node:fs';
+import { getShingles, calculateJaccard } from './semantic-hash.js';
+const hash = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+function encode(item, front = {}) {
+    const { body, key: _, ...metadata } = item;
+    return `---\n${stringify({ ...front, origin: 'learned', status: item.status, label: item.label, episodes: item.episodes, checked_at: item.checked_at, ace_learning: metadata }).trim()}\n---\n${body}`;
+}
+export function listLearnedArtifacts(root) {
+    return listStoreKeysSync(root, 'knowledge/').filter(k => /(?:\/SKILL\.md|\/LEARNED\.md|\/references\/proposals\/[^/]+\.md)$/.test(k)).flatMap(key => { const item = decodeLearned(readStoreBlobSync(root, key) ?? '', key); return item ? [item] : []; });
+}
+export async function withLearnedStore(root, apply) {
+    return withStoreWriteCoordinator(getWorkspaceStorePath(root), async () => {
+        const store = await openStore(getWorkspaceStorePath(root));
+        try {
+            const result = await apply(store);
+            await store.commit();
+            return result;
+        }
+        catch (error) {
+            store.discardPending();
+            throw error;
+        }
+        finally {
+            await store.close({ commit: false });
+        }
+    }, { operation_label: 'learned_artifact' });
+}
+export async function saveLearnedArtifact(root, item) {
+    const oldText = readStoreBlobSync(root, item.key);
+    let front = {};
+    try {
+        front = parse(oldText?.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? '') ?? {};
+    }
+    catch { }
+    await withLearnedStore(root, store => writeItem(store, item, front));
+}
+export async function updateLearnedArtifact(root, key, update) {
+    await withLearnedStore(root, async (store) => {
+        const text = await store.getBlob(key);
+        if (!text)
+            return;
+        const item = decodeLearned(text, key);
+        if (!item)
+            return;
+        const next = update(item);
+        if (next)
+            await writeItem(store, next, frontBody(text).front);
+    });
+}
+async function writeItem(store, item, front = {}) {
+    const previous = decodeLearned(await store.getBlob(item.key) ?? '', item.key);
+    Object.assign(item, learningLifecycle(item, previous?.id === item.id ? previous : undefined, new Date().toISOString()));
+    const skill = item.key.match(/^knowledge\/skills\/(.+)\/([^/]+)$/), agent = item.key.match(/^knowledge\/agents\/([^/]+)\/([^/]+)$/);
+    if (skill)
+        await store.setSkillContent(skill[1], skill[2], encode(item, front), ContentSource.User);
+    else if (agent)
+        await store.setAgentInstruction(agent[1], agent[2], encode(item, front), ContentSource.User);
+    else
+        await store.setSkillContent(item.key.replace(/^knowledge\/skills\//, '').split('/references/')[0], `references/proposals/${item.proposal_id}.md`, encode(item, front), ContentSource.User);
+}
+const similarity = (a, b) => calculateJaccard(getShingles(a.toLowerCase().replace(/\s+/g, ' ').trim(), 3), getShingles(b.toLowerCase().replace(/\s+/g, ' ').trim(), 3));
+const scoped = (scope) => !!(scope.role || scope.failure_signature || scope.paths?.length || scope.task_tags?.length);
+function frontBody(text) {
+    const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n/);
+    try {
+        return { front: m ? parse(m[1]) ?? {} : {}, body: m ? text.slice(m[0].length) : text };
+    }
+    catch {
+        return { front: {}, body: text };
+    }
+}
+export async function prepareLearned(root, payload, context, deps = {}) {
+    const policy = readLearningPolicy(root);
+    const episodes = listEpisodes(root), catalog = listLearnedArtifacts(root), id = hash([context, payload]), at = new Date().toISOString();
+    const effects = [];
+    const outcome = { ok: true, ids: [], errors: [] };
+    const resolveEpisodes = (ids, min = 1) => {
+        const cited = episodes.filter(e => ids.includes(e.id));
+        const errors = [];
+        if (new Set(ids).size < min)
+            errors.push(`Cite at least ${min} distinct episodes.`);
+        if (cited.length !== new Set(ids).size)
+            errors.push('Cited episode unavailable: ' + ids.filter(i => !cited.some(e => e.id === i)).join(', '));
+        return { cited, errors };
+    };
+    const run = deps.runVerification ?? (await import('./goal-engine.js')).resolveGoalDeps({ workspaceRoot: root }).runVerification;
+    const demonstrated = (eps, checks) => eps.some(ep => exactRedGreen(ep.observed_runs ?? []).length || (ep.checks ?? []).some(c => !c.ok && checks.some(p => p.ok && p.command === c.command && p.cwd === c.cwd)));
+    const snapshots = (eps) => eps.map(compactEpisode);
+    if ((payload.lessons?.length ?? 0) > 3)
+        outcome.errors.push('At most three lessons per completion.');
+    const proposedLessons = [];
+    for (const lesson of (payload.lessons ?? []).slice(0, 3)) {
+        const resolved = resolveEpisodes(lesson.episodes), errors = [...resolved.errors];
+        const repo = new PlaybookRepository(root), previous = lesson.bullet_id ? repo.getBullet(lesson.bullet_id) : undefined;
+        if (lesson.content.length > 400 || !lesson.content.trim())
+            errors.push('Lesson must contain 1–400 characters.');
+        if (!scoped(lesson.scope))
+            errors.push('Lesson needs an explicit scope.');
+        if (lesson.op !== 'add' && !previous)
+            errors.push('Existing lesson not found.');
+        if (previous && lesson.op === 'edit' && (lesson.content.length < previous.content.length * 0.6 || previous.evidence_snapshots?.some(e => !lesson.episodes.includes(e.id) && !lesson.retired_episodes?.includes(e.id))))
+            errors.push('Edit must retain 60% of content and prior episode citations.');
+        const duplicate = repo.listBullets({ status: 'active' }).find(b => b.bullet_id !== lesson.bullet_id && JSON.stringify(b.scope) === JSON.stringify(lesson.scope) && similarity(b.content, lesson.content) >= 0.9);
+        if (duplicate && lesson.op === 'add')
+            errors.push(`Use or edit existing lesson ${duplicate.bullet_id}.`);
+        if (proposedLessons.some(p => JSON.stringify(p.scope) === JSON.stringify(lesson.scope) && similarity(p.content, lesson.content) >= 0.9))
+            errors.push('Duplicate lesson in this completion; submit one scoped delta.');
+        proposedLessons.push({ content: lesson.content, scope: lesson.scope });
+        const check = lesson.content.match(/Check:\s*([^\n]+)/)?.[1]?.trim();
+        const checks = [];
+        if (!errors.length && lesson.op !== 'retire' && check) {
+            const result = await run(check, root).catch(error => ({ ok: false, output: String(error) }));
+            checks.push({ command: check, cwd: root, ok: result.ok });
+            if (!result.ok)
+                errors.push('Lesson check failed: ' + result.output.slice(-1000));
+        }
+        effects.push(async () => {
+            const saved = await withPlaybookTransaction(root, r => {
+                if (previous && !errors.length) {
+                    return r.saveBullet({ ...previous, content: lesson.content, section: lesson.section, scope: lesson.scope, evidence_refs: lesson.episodes, evidence_snapshots: snapshots(resolved.cited), status: lesson.op === 'retire' ? 'retired' : 'active', retired_reason: lesson.op === 'retire' ? lesson.content : undefined, label: demonstrated(resolved.cited, checks) ? 'demonstrated' : 'checked', validation_checks: checks, acceptance_errors: [] });
+                }
+                const existing = r.listBullets().find(b => b.provenance.run_id === `distill:${id}` && b.content.replace(/\s+/g, ' ').trim() === lesson.content.replace(/\s+/g, ' ').trim() && JSON.stringify(b.scope) === JSON.stringify(lesson.scope));
+                if (existing)
+                    return existing;
+                return r.createBullet({ section: lesson.section, scope: lesson.scope, content: lesson.content, evidence_refs: lesson.episodes, evidence_snapshots: snapshots(resolved.cited), status: errors.length ? 'quarantined' : 'active', label: demonstrated(resolved.cited, checks) ? 'demonstrated' : 'checked', validation_checks: checks, acceptance_errors: errors, provenance: { source: 'operator', run_id: `distill:${id}`, note: JSON.stringify(context) } });
+            });
+            outcome.ids.push(saved.bullet_id);
+        });
+        outcome.errors.push(...errors);
+    }
+    if (payload.skill) {
+        const s = payload.skill, resolved = resolveEpisodes(s.episodes, 3), errors = [...resolved.errors], parts = frontBody(s.skill_md), scope = (typeof parts.front.scope === 'object' ? parts.front.scope : { task_tags: typeof parts.front.scope === 'string' ? [parts.front.scope] : [] });
+        const isMeta = s.slug === 'learn-from-work' && context.goal_id === 'G-learning' && new GoalRepository(root).getPlan(context.goal_id)?.steps.find(s => s.step_id === context.step_id)?.learning_kind === 'meta';
+        const artifactId = `learned/${/^[a-z0-9-]{3,48}$/.test(s.slug) ? s.slug : 'invalid-' + id}`, key = isMeta ? 'knowledge/skills/learn-from-work/LEARNED.md' : `knowledge/skills/${artifactId}/SKILL.md`, previous = catalog.find(x => x.key === key && x.status === 'active');
+        if (!/^[a-z0-9-]{3,48}$/.test(s.slug))
+            errors.push('Skill slug must be 3–48 lowercase letters, digits or hyphens.');
+        if (new Set(resolved.cited.map(e => e.goal_id)).size < 2)
+            errors.push('A skill needs episodes from at least two goals.');
+        if (parts.front.name !== s.slug)
+            errors.push('Skill frontmatter name must match its slug.');
+        if (!scoped(scope))
+            errors.push('Skill frontmatter must have a matching scope.');
+        if (!isMeta && existsSync(join(DEFAULTS_SKILLS_ROOT, s.slug)))
+            errors.push('Cannot shadow a packaged skill.');
+        if (s.op === 'add' && previous)
+            errors.push('Skill exists; submit an edit.');
+        if (s.op === 'edit' && !previous && !isMeta)
+            errors.push('Cannot edit a missing active skill.');
+        if (previous && s.skill_md.length < Number(previous.source_length ?? previous.body.length) * 0.6)
+            errors.push('Edit retains less than 60% of prior skill.');
+        if (previous?.episodes.some(e => !s.episodes.includes(e) && !s.retired_episodes?.includes(e)))
+            errors.push('Edit must retain prior episode citations.');
+        if (!isMeta && !previous && catalog.filter(x => x.kind === 'skill' && x.status === 'active').length >= policy.max_learned_skills)
+            errors.push('Learned skill cap reached; edit an existing skill.');
+        const refs = Object.entries(s.references ?? {});
+        if (refs.length > 3 || refs.some(([name, text]) => !/^[-a-zA-Z0-9_]+\.md$/.test(name) || text.split(/\r?\n/).length > 400))
+            errors.push('At most three safe Markdown reference files, 400 lines each.');
+        const proof = await proveLearnedSkill(s.skill_md, root, errors.length ? async () => ({ ok: false, output: 'Not executed: proposal metadata did not qualify' }) : run, previous?.body);
+        errors.push(...proof.errors);
+        const duplicate = catalog.find(a => a.id !== artifactId && a.kind === 'skill' && a.status === 'active' && similarity(String(frontBody(readStoreBlobSync(root, a.key) ?? '').front.description ?? ''), proof.description) >= 0.9);
+        if (duplicate)
+            errors.push('Use or edit existing skill ' + duplicate.id);
+        const item = { id: isMeta ? `distiller:learn-from-work:${id}` : artifactId, key, kind: isMeta ? 'distiller' : 'skill', status: errors.length ? 'quarantined' : isMeta ? 'proposed' : 'active', label: demonstrated(resolved.cited, proof.checks) ? 'demonstrated' : 'checked', episodes: s.episodes, evidence_snapshots: snapshots(resolved.cited), scope, body: parts.body, acceptance_errors: errors, checked_at: at, proposal_id: id, helpful_count: previous?.helpful_count ?? 0, harmful_count: previous?.harmful_count ?? 0, references: s.references, served_count: previous?.served_count, used_count: previous?.used_count, used_goals: previous?.used_goals, scored_attempts: previous?.scored_attempts, served_outcomes: previous?.served_outcomes, source_length: s.skill_md.length, validation_checks: proof.checks.map(c => ({ command: c.command, cwd: c.cwd, ok: c.ok, output: c.output.slice(-1000) })) };
+        if (isMeta && previous)
+            item.key = `knowledge/skills/learn-from-work/references/proposals/${id}.md`;
+        if (errors.length && previous) {
+            item.id = `${artifactId}:proposal:${id}`;
+            item.key = `knowledge/skills/${isMeta ? 'learn-from-work' : artifactId}/references/proposals/${id}.md`;
+        }
+        effects.push(() => withLearnedStore(root, async (store) => {
+            const latestText = await store.getBlob(key), latest = latestText ? decodeLearned(latestText, key) : undefined;
+            if (latest && (!previous || latest.proposal_id !== previous.proposal_id || latest.status !== 'active')) {
+                const error = 'Active skill changed during qualification; review the retained proposal against its current version.';
+                errors.push(error);
+                outcome.errors.push(error);
+                item.status = 'quarantined';
+                item.id = `${artifactId}:proposal:${id}`;
+                item.key = `knowledge/skills/${isMeta ? 'learn-from-work' : artifactId}/references/proposals/${id}.md`;
+                outcome.ids = outcome.ids.map(value => value === artifactId ? item.id : value);
+            }
+            else if (latest)
+                for (const field of ['helpful_count', 'harmful_count', 'served_count', 'used_count', 'used_goals', 'scored_attempts', 'served_outcomes'])
+                    item[field] = latest[field];
+            if (previous && !errors.length && !isMeta) {
+                const history = previous.history ?? [];
+                const version = `${at.replace(/[^0-9]/g, '')}-${id}`;
+                await store.setSkillContent(artifactId, `references/history/${version}.md`, latestText ?? '', ContentSource.User);
+                item.history = [...history, version].slice(-3);
+                for (const old of history.slice(0, Math.max(0, history.length - 2)))
+                    await store.delete(`knowledge/skills/${artifactId}/references/history/${old}.md`);
+            }
+            await writeItem(store, item, parts.front);
+            if (!errors.length) {
+                for (const [name, body] of refs)
+                    await store.setSkillContent(artifactId, `references/${name}`, body, ContentSource.User);
+                await store.setSkillContent(artifactId, 'references/episodes.md', resolved.cited.map(e => `## ${e.id}\n${JSON.stringify(snapshots([e])[0], null, 2)}`).join('\n\n'), ContentSource.User);
+            }
+        }));
+        outcome.ids.push(item.id);
+        outcome.errors.push(...errors);
+    }
+    if (payload.instruction) {
+        const i = payload.instruction, resolved = resolveEpisodes(i.episodes), errors = [...resolved.errors];
+        if (!ALL_AGENTS.includes(i.role))
+            errors.push('Unknown role.');
+        if (!i.text.trim() || i.text.length > 1200)
+            errors.push('Instruction must contain 1–1200 characters.');
+        if (catalog.some(a => a.kind === 'instruction' && a.scope.role === i.role && a.status !== 'quarantined' && similarity(a.body, i.text) >= 0.9))
+            errors.push('Use the existing matching instruction proposal.');
+        const key = `knowledge/agents/${i.role}/LEARNED.md`, prior = catalog.find(a => a.key === key);
+        const item = { id: `instruction:${i.role}:${id}`, key: prior?.status === 'active' ? `knowledge/skills/learn-from-work/references/proposals/${id}.md` : key, kind: 'instruction', status: errors.length ? 'quarantined' : 'proposed', label: 'checked', episodes: i.episodes, evidence_snapshots: snapshots(resolved.cited), scope: { role: i.role }, body: i.text, acceptance_errors: errors, checked_at: at, proposal_id: id, helpful_count: 0, harmful_count: 0 };
+        effects.push(() => saveLearnedArtifact(root, item));
+        outcome.ids.push(item.id);
+        outcome.errors.push(...errors);
+    }
+    outcome.ok = !outcome.errors.length;
+    if (!outcome.ok) {
+        outcome.reason_code = 'learning_unchecked';
+        outcome.options = [{ tool: 'next_step', args: { goal_id: 'G-learning' }, why: 'Use the corrective learning step with the retained acceptance errors.' }];
+    }
+    return { result: outcome, publish: async () => { for (const effect of effects)
+            await effect(); outcome.ok = !outcome.errors.length; if (!outcome.ok) {
+            outcome.reason_code = 'learning_unchecked';
+            outcome.options = [{ tool: 'next_step', args: { goal_id: 'G-learning' }, why: 'Review the retained acceptance errors in the corrective learning assignment.' }];
+        } await regenerateLearnedProjection(root); } };
+}
+export async function acceptLearned(root, payload, context, deps = {}) {
+    const checked = await prepareLearned(root, payload, context, deps);
+    await checked.publish();
+    return checked.result;
+}
+export async function regenerateLearnedProjection(root) {
+    const bullets = new PlaybookRepository(root).listBullets(), artifacts = listLearnedArtifacts(root);
+    const body = ['# Learned in this workspace', '', ...bullets.filter(b => b.evidence_snapshots?.length).map(b => `- ${b.bullet_id} [${b.status}; ${b.label ?? 'candidate'}]: ${b.content}\n  Episodes: ${b.evidence_snapshots.map(e => e.id).join(', ')}`), ...artifacts.map(a => `- ${a.id} [${a.status}; ${a.label}]\n  Episodes: ${a.episodes.join(', ')}${a.acceptance_errors.length ? '\n  Acceptance: ' + a.acceptance_errors.join('; ') : ''}`)].join('\n');
+    await withLearnedStore(root, store => store.setBlob(operationalArtifactKey('agent-state/LEARNED.md'), body));
+}
+export async function ensureLearningStep(root, force) {
+    const policy = readLearningPolicy(root);
+    if (!policy.enabled)
+        return;
+    const bullets = new PlaybookRepository(root).listBullets().filter(b => ['active', 'quarantined'].includes(b.status) && b.evidence_snapshots?.length);
+    const groups = new Map();
+    for (const b of bullets) {
+        const scope = learningScopeKey(b.scope);
+        groups.set(scope, [...(groups.get(scope) ?? []), b]);
+    }
+    const eligible = [...groups.entries()].filter(([, items]) => items.length >= policy.distill_min_items && new Set(items.flatMap(b => b.evidence_snapshots.map(e => e.goal_id))).size >= policy.distill_min_goals);
+    if (!eligible.length && !force)
+        return;
+    const repo = new GoalRepository(root), now = new Date().toISOString();
+    await withStoreWriteCoordinator(repo.planPath('G-learning'), async () => {
+        let goal = repo.getGoal('G-learning'), plan = repo.getPlan('G-learning');
+        if (plan?.steps.some(s => ['planned', 'running', 'blocked'].includes(s.status)))
+            return;
+        const cooling = (key) => plan?.steps.some(s => canonicalLearningScopeKey(s.learning_scope ?? '') === key && Date.now() - Date.parse(s.learning_opened_at ?? s.started_at ?? now) < policy.distill_cooldown_days * 86400000);
+        const chosen = force ? undefined : eligible.find(([key]) => !cooling(key));
+        if (!force && !chosen)
+            return;
+        const scope = force?.scope ?? chosen[1][0].scope, scopeKey = learningScopeKey(scope);
+        if (cooling(scopeKey))
+            return;
+        const items = force ? bullets.filter(b => b.scope.failure_signature === scope.failure_signature) : chosen[1];
+        const cited = [...items.flatMap(b => b.evidence_snapshots ?? []), ...(force ? listEpisodes(root).filter(e => e.failure_signature === scope.failure_signature) : [])];
+        const task = `Distill what this workspace has learned about ${scopeKey}.\nInputs: the referenced episodes and existing artifacts.\nProduce, via complete_step outcome.learned:\n(a) up to 3 lessons: trigger → action → check; keep commands, paths, error text verbatim; edit or retire existing lessons rather than duplicate them.\n(b) optionally one skill, only if ≥3 episodes share a reusable procedure.\n(c) optionally one role-instruction proposal, only if a rule applies to every task of that role.\nCite episode ids for every item. Do not invent steps the episodes do not show.\nLoad get_skill_instructions(learn-from-work).\n${force?.reason ?? ''}`;
+        const learning_inputs = { episodes: [...new Set(cited.map(e => e.id))], artifacts: [...items.map(b => b.bullet_id), ...listLearnedArtifacts(root).map(a => a.id)] };
+        if (!plan) {
+            plan = createTaskPlan({ task: 'Keep this workspace\'s learned artifacts current', steps: [] });
+            goal = { goal_id: 'G-learning', objective: plan.task, executor: 'host', status: 'executing', plan_id: plan.plan_id, success_contract: { expected_artifacts: [], required_evidence_refs: [], verification_commands: [], gate_ids: [], uncompilable_criteria: [] }, budgets: defaultGoalBudgets(), created_at: now, updated_at: now, tick_count: 0, replan_count: 0, stop_requested: false, escalations: [] };
+        }
+        plan = amendTaskPlan(plan, { append_steps: [{ role: 'coders', task, learning_inputs, learning_scope: scopeKey, learning_opened_at: now }] });
+        // G-learning is a retained container. New work after a closed batch
+        // gets a start time here; host restart/resume never resets deadlines.
+        if (goal.status === 'done' || !goal.started_at)
+            goal.started_at = now;
+        goal.status = 'executing';
+        goal.stop_requested = false;
+        repo.savePlan('G-learning', plan);
+        repo.saveGoal(goal);
+    }, { operation_label: 'learning_step' });
+}
+export async function reopenLearningCorrection(root, errors) {
+    const repo = new GoalRepository(root);
+    await withStoreWriteCoordinator(repo.planPath('G-learning'), async () => {
+        const g = repo.getGoal('G-learning');
+        let p = repo.getPlan('G-learning');
+        if (!g || !p || p.steps.some(s => ['planned', 'running'].includes(s.status)))
+            return;
+        if (g.budgets.replan_budget_explicit && g.replan_count >= g.budgets.max_replans) {
+            g.status = 'blocked';
+            g.reason_code = 'Learning correction budget reached: ' + errors.join('; ');
+            repo.saveGoal(g);
+            return;
+        }
+        p = amendTaskPlan(p, { append_steps: [{ role: 'coders', learning_scope: p.steps.at(-1)?.learning_scope ?? 'correction', learning_inputs: { rejected_steps: p.steps.at(-1) ? [p.steps.at(-1).step_id] : [] }, task: 'Correct the retained learned payload using the referenced acceptance errors and original payload.' }] });
+        g.replan_count++;
+        g.status = 'executing';
+        repo.savePlan('G-learning', p);
+        repo.saveGoal(g);
+    }, { operation_label: 'learning_correction' });
+}
+//# sourceMappingURL=learned-artifacts.js.map

package/dist/learning-controls.d.ts

@@ -0,0 +1,142 @@
+import { type LearnedArtifact } from './learned-artifacts.js';
+export declare function listLearning(root: string): {
+    lessons: import("./store/repositories/playbook-repository.js").PlaybookBullet[];
+    artifacts: LearnedArtifact[];
+};
+export declare function showLearning(root: string, id: string): import("./store/repositories/playbook-repository.js").PlaybookBullet | LearnedArtifact | undefined;
+export declare function approveLearning(root: string, id: string): Promise<void>;
+export declare function retireLearning(root: string, id: string, reason: string): Promise<void>;
+export { approvedInstructionText, approvedDistillerText } from './learning-overlays.js';
+export declare function learningReport(root: string): {
+    scorecard: {
+        active_learned_artifacts: {
+            lessons: number;
+            skills: number;
+            approved_instructions: number;
+        };
+        repeat_failure_rate: {
+            signatures_served: number;
+            signatures_recurred: number;
+            rate: number | null;
+            missing_context_attempts: number;
+            interpretation: string;
+        };
+        first_attempt_success_by_scope: {
+            scope: string;
+            before: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            after: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            unclassified: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+            unexposed: ReturnType<() => {
+                done: number;
+                steps: number;
+                rate: number | null;
+            }>;
+        }[];
+        first_attempt_coverage: {
+            missing_first_attempts: number;
+            reconstructed_scopes: number;
+            interpretation: string;
+        };
+        served_helpfulness: {
+            helpful: number;
+            harmful: number;
+            ratio: number | null;
+            counter_scope: string;
+        };
+        distill_acceptance: {
+            checked: number;
+            submitted: number;
+            rate: number | null;
+            demonstrated_current_artifacts: number;
+        };
+        learning_overhead: {
+            learning_steps: number;
+            all_steps: number;
+            ratio: number | null;
+            opportunistic_payload_steps: number;
+            assignments: {
+                episode_id: string;
+                utf8_bytes: number;
+                token_upper_bound: number;
+            }[];
+            max_served_token_upper_bound: number | null;
+            token_method: string;
+        };
+        retirement_health: {
+            window_days: number;
+            retired: number;
+            ever_active: number;
+            ratio: number | null;
+            unknown_history: number;
+        };
+        distillation_steps: {
+            goal_id: string;
+            step_id: string;
+            checked: boolean;
+            items_after_20_serves: number;
+            mean_strong_helpfulness: number | null;
+        }[];
+        coverage: string;
+    };
+    enabled: boolean;
+    policy_issue: string | null;
+    observation: string;
+    episodes: number;
+    attempts: number;
+    first_attempts_done: number;
+    steps_with_outcomes: number;
+    artifacts: {
+        lessons: number;
+        skills: number;
+        quarantined: number;
+    };
+    instructions: {
+        active: number;
+        proposed: number;
+    };
+    served: number;
+    used: number;
+    helpful: number;
+    harmful: number;
+    weak_outcomes: {
+        done_first_attempt: number;
+        failed_same_signature: number;
+        other: number;
+    };
+    repeat_signatures: {
+        signature: string;
+        count: number;
+    }[];
+    distillation: {
+        submitted: number;
+        checked: number;
+        acceptance_rate: number | null;
+        demonstrated: number;
+        helpfulness_after_20_serves: {
+            id: unknown;
+            helpful: number;
+            harmful: number;
+            used: number;
+        }[];
+    };
+    limitations: string[];
+};
+export declare function exportLearning(root: string, to: string): Promise<{
+    files: string[];
+    unexported: string[];
+}>;
+/** Open the next useful proposal, never a coordinator or automatic approval. */
+export declare function advanceLearning(root: string): Promise<void>;
+//# sourceMappingURL=learning-controls.d.ts.map

package/dist/learning-controls.js

@@ -0,0 +1,135 @@
+import { buildLearningScorecard } from './learning-scorecard.js';
+/** Explicit operator controls and reports over existing learning records. */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { GoalRepository, defaultGoalBudgets } from './store/repositories/goal-repository.js';
+import { amendTaskPlan, createTaskPlan } from './orchestrator-supervisor.js';
+import { PlaybookRepository, withPlaybookTransaction } from './store/repositories/playbook-repository.js';
+import { listLearnedArtifacts, saveLearnedArtifact, regenerateLearnedProjection, withLearnedStore } from './learned-artifacts.js';
+import { withStoreWriteCoordinator } from './store/write-coordinator.js';
+import { readLearningPolicy } from './learning-policy.js';
+import { ContentSource } from './store/types.js';
+import { listEpisodes } from './host-learning.js';
+export function listLearning(root) { return { lessons: new PlaybookRepository(root).listBulletsReadOnly(), artifacts: listLearnedArtifacts(root) }; }
+export function showLearning(root, id) { const all = listLearning(root); return all.lessons.find(b => b.bullet_id === id) ?? all.artifacts.find(a => a.id === id); }
+export async function approveLearning(root, id) {
+    const a = listLearnedArtifacts(root).find(a => a.id === id);
+    if (!a || a.status !== 'proposed' || !['instruction', 'distiller'].includes(a.kind))
+        throw Error('Choose an existing proposed instruction or distiller overlay. Lessons and skills do not need operator approval.');
+    const sourceKey = a.key, canonical = a.kind === 'instruction' ? `knowledge/agents/${a.scope.role}/LEARNED.md` : 'knowledge/skills/learn-from-work/LEARNED.md';
+    await withLearnedStore(root, async (store) => {
+        const prior = await store.getBlob(canonical);
+        if (prior) {
+            const name = `references/history/${new Date().toISOString().replace(/[^0-9]/g, '')}.md`;
+            if (a.kind === 'instruction')
+                await store.setAgentInstruction(a.scope.role, name, prior, ContentSource.User);
+            else
+                await store.setSkillContent('learn-from-work', name, prior, ContentSource.User);
+        }
+    });
+    if (sourceKey !== canonical)
+        await saveLearnedArtifact(root, { ...a, id: a.id + ':proposal-record', status: 'retired', retired_reason: 'Approved into ' + canonical });
+    a.status = 'active';
+    a.approved_at = new Date().toISOString();
+    a.approval = 'explicit ace learn approve';
+    a.key = canonical;
+    await saveLearnedArtifact(root, a);
+    await regenerateLearnedProjection(root);
+}
+export async function retireLearning(root, id, reason) {
+    if (!reason.trim())
+        throw Error('Retirement needs a reason.');
+    const a = listLearnedArtifacts(root).find(a => a.id === id);
+    if (a) {
+        await saveLearnedArtifact(root, { ...a, status: 'retired', retired_reason: reason });
+    }
+    else
+        await withPlaybookTransaction(root, repo => {
+            const b = repo.getBullet(id);
+            if (!b)
+                throw Error('Learning item not found: ' + id);
+            repo.saveBullet({ ...b, status: 'retired', retired_reason: reason });
+        });
+    await regenerateLearnedProjection(root);
+}
+export { approvedInstructionText, approvedDistillerText } from './learning-overlays.js';
+export function learningReport(root) {
+    const all = listLearning(root), repo = new GoalRepository(root), steps = repo.listGoals().flatMap(g => (repo.getPlan(g.goal_id)?.steps ?? []).map(s => ({ goal: g.goal_id, step: s }))), episodes = listEpisodes(root);
+    const logs = steps.flatMap(({ goal, step }) => (step.attempts_log ?? []).map(a => ({ ...a, goal, step_id: step.step_id })));
+    const distill = steps.filter(({ step }) => step.learning_payload && step.learning_result), skills = all.artifacts.filter(a => a.kind === 'skill'), instructions = all.artifacts.filter(a => a.kind === 'instruction'), served = [...all.lessons, ...skills];
+    const signatureCounts = new Map();
+    for (const ep of episodes)
+        if (ep.failure_signature)
+            signatureCounts.set(ep.failure_signature, (signatureCounts.get(ep.failure_signature) ?? 0) + 1);
+    return { scorecard: buildLearningScorecard(steps, episodes, all.lessons, all.artifacts), enabled: readLearningPolicy(root).enabled, policy_issue: readLearningPolicy(root).issue ?? null, observation: 'unavailable unless a qualified Vericify adapter supplied Linked records', episodes: episodes.length, attempts: logs.length, first_attempts_done: logs.filter(a => a.attempt === 1 && a.status === 'done').length, steps_with_outcomes: new Set(logs.map(a => `${a.goal}:${a.step_id}`)).size, artifacts: { lessons: all.lessons.filter(b => b.status === 'active').length, skills: skills.filter(a => a.status === 'active').length, quarantined: all.lessons.filter(b => b.status === 'quarantined').length + all.artifacts.filter(a => a.status === 'quarantined').length }, instructions: { active: instructions.filter(a => a.status === 'active').length, proposed: instructions.filter(a => a.status === 'proposed').length }, served: served.reduce((sum, b) => sum + (b.served_count ?? 0), 0), used: served.reduce((sum, b) => sum + (b.used_count ?? 0), 0), helpful: served.reduce((sum, b) => sum + b.helpful_count, 0), harmful: served.reduce((sum, b) => sum + b.harmful_count, 0), weak_outcomes: served.reduce((sum, b) => ({ done_first_attempt: sum.done_first_attempt + (b.served_outcomes?.done_first_attempt ?? 0), failed_same_signature: sum.failed_same_signature + (b.served_outcomes?.failed_same_signature ?? 0), other: sum.other + (b.served_outcomes?.other ?? 0) }), { done_first_attempt: 0, failed_same_signature: 0, other: 0 }), repeat_signatures: [...signatureCounts.entries()].filter(([, count]) => count > 1).map(([signature, count]) => ({ signature, count })), distillation: { submitted: distill.length, checked: distill.filter(({ step }) => step.learning_result?.ok).length, acceptance_rate: distill.length ? distill.filter(({ step }) => step.learning_result?.ok).length / distill.length : null, demonstrated: all.artifacts.filter(a => a.label === 'demonstrated').length + all.lessons.filter(b => b.label === 'demonstrated').length, helpfulness_after_20_serves: served.filter(a => (a.served_count ?? 0) >= 20).map(a => ({ id: 'bullet_id' in a ? a.bullet_id : a.id, helpful: a.helpful_count, harmful: a.harmful_count, used: a.used_count ?? 0 })) }, limitations: ['Attempt context retains five entries; pinned citations preserve cited earlier episodes.', 'No provider quality, causal benefit or unavailable external observation is inferred from these counters.'] };
+}
+export async function exportLearning(root, to) {
+    const all = listLearning(root), files = [], unexported = [];
+    const target = resolve(root, to);
+    const emit = (path, text) => { const file = join(target, path); mkdirSync(dirname(file), { recursive: true }); const marker = '<!-- Generated by ace learn export; review changes before committing. -->\n'; const output = text.startsWith('---\n') ? text.replace(/\n---\n/, '\n---\n' + marker) : marker + text; writeFileSync(file, output.endsWith('\n') ? output : output + '\n'); files.push(file); };
+    const grouped = new Map();
+    for (const b of all.lessons.filter(b => b.status === 'active')) {
+        if (!b.evidence_snapshots?.length) {
+            unexported.push(`${b.bullet_id}: no ACE episode citation`);
+            continue;
+        }
+        const key = createHash('sha256').update(JSON.stringify(b.scope)).digest('hex').slice(0, 8);
+        grouped.set(key, [...(grouped.get(key) ?? []), b]);
+    }
+    for (const [key, items] of grouped)
+        emit(`lessons/${key}.md`, '# Learned lessons\n\n' + items.map(b => `## ${b.bullet_id} (${b.label ?? 'checked'})\n\n${b.content}\n\nEpisodes: ${b.evidence_snapshots.map(e => e.id).join(', ')}\n\nScope: ${JSON.stringify(b.scope)}`).join('\n\n'));
+    for (const a of all.artifacts.filter(a => a.status === 'active')) {
+        if (!a.episodes.length) {
+            unexported.push(`${a.id}: no episode citation`);
+            continue;
+        }
+        const name = a.kind === 'skill' ? `skills/${a.id.replace(/^learned\//, '')}/SKILL.md` : a.kind === 'instruction' ? `agents/${a.scope.role}/LEARNED.md` : 'skills/learn-from-work/LEARNED.md';
+        const front = a.kind === 'skill' ? `---\nname: ${JSON.stringify(a.id.replace(/^learned\//, ''))}\ndescription: ${JSON.stringify(a.description ?? 'Use for ' + JSON.stringify(a.scope))}\nscope: ${JSON.stringify(a.scope)}\norigin: learned\nlabel: ${a.label}\nepisodes: ${JSON.stringify(a.episodes)}\n---\n` : '';
+        emit(name, front + (a.kind === 'skill' ? a.body : `# ${a.id}\n\nLabel: ${a.label}\n\nEpisodes: ${a.episodes.join(', ')}\n\n${a.body}`));
+        for (const [name, body] of Object.entries(a.references ?? {}))
+            emit(`skills/${a.id.replace(/^learned\//, '')}/references/${name}`, `Episodes: ${a.episodes.join(', ')}\n\n${body}`);
+        if (a.kind === 'skill')
+            emit(`skills/${a.id.replace(/^learned\//, '')}/references/episodes.md`, a.evidence_snapshots.map(e => { const current = listEpisodes(root).find(item => item.id === e.id) ?? e; return `## ${e.id}\n\n${JSON.stringify(current, null, 2)}`; }).join('\n\n'));
+    }
+    return { files, unexported };
+}
+/** Open the next useful proposal, never a coordinator or automatic approval. */
+export async function advanceLearning(root) {
+    const policy = readLearningPolicy(root);
+    if (!policy.enabled)
+        return;
+    const repo = new GoalRepository(root), catalog = listLearnedArtifacts(root), eligible = catalog.filter(a => a.kind === 'skill' && a.status === 'active' && a.label === 'demonstrated' && a.helpful_count >= 10 && a.harmful_count === 0 && (a.used_goals?.length ?? 0) >= 3);
+    const prior = repo.getPlan('G-learning');
+    if (prior?.steps.some(s => ['planned', 'running', 'blocked'].includes(s.status)))
+        return;
+    const priorBase = (prior?.steps ?? []).filter(s => s.learning_payload && s.learning_result && s.learning_kind !== 'meta').slice(-10);
+    if (!eligible.length && !(priorBase.length === 10 && priorBase.filter(s => s.learning_result.ok).length < 5))
+        return;
+    await withStoreWriteCoordinator(repo.planPath('G-learning'), async () => {
+        let g = repo.getGoal('G-learning'), p = repo.getPlan('G-learning');
+        if (p?.steps.some(s => ['planned', 'running', 'blocked'].includes(s.status)))
+            return;
+        const base = (p?.steps ?? []).filter(s => s.learning_payload && s.learning_result && s.learning_kind !== 'meta').slice(-10), trigger = base.map(s => s.step_id).join(',');
+        const coolingMeta = (p?.steps ?? []).some(s => s.learning_kind === 'meta' && Date.now() - Date.parse(s.learning_opened_at ?? new Date().toISOString()) < policy.distill_cooldown_days * 86400000);
+        const meta = !coolingMeta && base.length === 10 && base.filter(s => s.learning_result.ok).length < 5 && !(p?.steps ?? []).some(s => s.learning_kind === 'meta' && s.learning_trigger === trigger);
+        const candidate = eligible.find(a => !p?.steps.some(s => s.learning_kind === 'graduation' && s.learning_source === a.id));
+        const graduate = !!candidate;
+        if (!meta && !graduate)
+            return;
+        const now = new Date().toISOString();
+        const body = meta ? 'Propose one depth-one revision to the learn-from-work distillation skill. Use outcome.learned.skill with slug learn-from-work. Keep it proposed for operator approval. Never propose a revision about this overlay itself. Inspect the referenced rejected base payloads and acceptance errors.' : 'Propose the role-level rule this demonstrated skill implies, if any. Submit outcome.learned.instruction; it remains proposed until an operator approves it. Inspect the referenced demonstrated skill.';
+        const learning_inputs = meta ? { rejected_steps: base.map(s => s.step_id) } : { artifacts: [candidate.id] };
+        if (!p) {
+            p = createTaskPlan({ task: 'Keep this workspace\'s learned artifacts current', steps: [] });
+            g = { goal_id: 'G-learning', objective: p.task, status: 'executing', executor: 'host', plan_id: p.plan_id, success_contract: { expected_artifacts: [], required_evidence_refs: [], verification_commands: [], gate_ids: [], uncompilable_criteria: [] }, budgets: defaultGoalBudgets(), created_at: now, updated_at: now, tick_count: 0, replan_count: 0, stop_requested: false, escalations: [] };
+        }
+        p = amendTaskPlan(p, { append_steps: [{ role: 'coders', task: body, learning_inputs, learning_scope: meta ? 'distiller-depth-1' : `graduate:${candidate.id}`, learning_kind: meta ? 'meta' : 'graduation', learning_source: meta ? undefined : candidate.id, learning_trigger: meta ? trigger : undefined, learning_opened_at: now }] });
+        if (g.status === 'done' || !g.started_at)
+            g.started_at = now;
+        g.status = 'executing';
+        repo.savePlan('G-learning', p);
+        repo.saveGoal(g);
+    }, { operation_label: 'learning_proposal' });
+}
+//# sourceMappingURL=learning-controls.js.map

package/dist/learning-input-context.d.ts

@@ -0,0 +1,9 @@
+/** Bounded derived context. The existing plans/knowledge retain every full input. */
+import type { TaskStep } from './orchestrator-supervisor.js';
+export interface LearningInputRefs {
+    episodes?: string[];
+    artifacts?: string[];
+    rejected_steps?: string[];
+}
+export declare function renderLearningTask(root: string, goalId: string, step: TaskStep): string;
+//# sourceMappingURL=learning-input-context.d.ts.map