@voybio/ace-swarm 2.4.8 → 2.4.10

package/dist/kanban.d.ts

@@ -1,4 +1,4 @@
-export type KanbanColumn = "backlog" | "blocked" | "in_progress" | "gated" | "done";
+export type KanbanColumn = "backlog" | "blocked" | "in_progress" | "gated" | "done" | "cancelled";
 export interface AceKanbanCard {
     id: string;
     title: string;
@@ -10,8 +10,10 @@ export interface AceKanbanBoard {
     in_progress: AceKanbanCard[];
     gated: AceKanbanCard[];
     done: AceKanbanCard[];
+    cancelled: AceKanbanCard[];
 }
 export interface AceKanbanSnapshot {
+    refresh_scheduled?: boolean;
     version: number;
     generated_at: string;
     trigger: string;
@@ -21,6 +23,7 @@ export interface AceKanbanSnapshot {
     json_path: string;
 }
 export declare function renderKanbanHtml(snapshot: AceKanbanSnapshot): string;
+export declare function formatKanbanRefresh(snapshot: AceKanbanSnapshot): string;
 export declare function refreshKanbanArtifacts(trigger: string): AceKanbanSnapshot;
 export declare function getOrRefreshKanbanSnapshot(trigger: string): AceKanbanSnapshot;
 export declare function shouldAutoRefreshKanbanForPath(path: string): boolean;

package/dist/kanban.js

@@ -1,13 +1,13 @@
-import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, safeRead, safeWrite, wsPath } from "./helpers.js";
+import { ACE_ROOT_REL, ACE_TASKS_ROOT_REL, safeRead, safeWrite, wsPath, resolveWorkspaceRoot, withWorkspaceRoot } from "./helpers.js";
 import { isReadError, slugify } from "./shared.js";
 import { readHandoffRegistry } from "./handoff-registry.js";
 import { readTodoState } from "./todo-state.js";
 /** Debounce threshold in milliseconds. Skip re-render if within this window. */
 const KANBAN_DEBOUNCE_MS = 2000;
-let lastKanbanRenderTimestamp = 0;
+const renderState = new Map();
 const KANBAN_JSON_REL = "agent-state/kanban.json";
 const KANBAN_HTML_REL = "agent-state/kanban.html";
-const COLUMNS = ["backlog", "blocked", "in_progress", "gated", "done"];
+const COLUMNS = ["backlog", "blocked", "in_progress", "gated", "done", "cancelled"];
 function nowIso() {
     return new Date().toISOString();
 }
@@ -18,6 +18,7 @@ function emptyBoard() {
         in_progress: [],
         gated: [],
         done: [],
+        cancelled: [],
     };
 }
 function escapeHtml(input) {
@@ -236,7 +237,7 @@ export function renderKanbanHtml(snapshot) {
         "@keyframes spin{to{transform:rotate(360deg)}}",
         "h1{margin:0;font-family:'Space Grotesk','Avenir Next',sans-serif;font-size:24px}",
         ".stamp{margin:0;font-size:12px;opacity:.75}",
-        ".grid{display:grid;grid-template-columns:repeat(5,minmax(220px,1fr));gap:12px}",
+        ".grid{display:grid;grid-template-columns:repeat(6,minmax(220px,1fr));gap:12px}",
         ".column{background:rgba(255,255,255,.62);border:1px solid var(--line);border-radius:12px;min-height:220px}",
         ".column>header{display:flex;justify-content:space-between;align-items:center;padding:10px 12px;border-bottom:1px solid var(--line)}",
         ".column h2{margin:0;font-size:14px;text-transform:capitalize}",
@@ -265,16 +266,38 @@ export function renderKanbanHtml(snapshot) {
         "</html>",
     ].join("");
 }
+export function formatKanbanRefresh(snapshot) {
+    return snapshot.refresh_scheduled
+        ? `Kanban refresh scheduled: ${snapshot.html_path} (last generated ${snapshot.generated_at})`
+        : `Kanban updated: ${snapshot.html_path}`;
+}
 export function refreshKanbanArtifacts(trigger) {
-    // Debounce: skip expensive re-render if within threshold
-    const now = Date.now();
-    if (now - lastKanbanRenderTimestamp < KANBAN_DEBOUNCE_MS) {
-        // Return cached snapshot if available
-        const cached = getOrRefreshKanbanSnapshot(trigger);
-        if (cached.generated_at)
-            return cached;
+    const root = resolveWorkspaceRoot();
+    const state = renderState.get(root) ?? { last: 0 };
+    const delay = KANBAN_DEBOUNCE_MS - (Date.now() - state.last);
+    const cached = readKanbanSnapshot();
+    if (delay > 0 && cached) {
+        if (state.timer)
+            clearTimeout(state.timer);
+        state.timer = setTimeout(() => withWorkspaceRoot(root, () => {
+            state.timer = undefined;
+            try {
+                renderKanbanNow(trigger);
+            }
+            catch (error) {
+                state.last = 0;
+                console.error(`Kanban refresh failed for ${root}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }), delay);
+        state.timer.unref();
+        renderState.set(root, state);
+        return { ...cached, refresh_scheduled: true };
     }
-    lastKanbanRenderTimestamp = now;
+    if (state.timer)
+        clearTimeout(state.timer);
+    return renderKanbanNow(trigger);
+}
+function renderKanbanNow(trigger) {
     const board = emptyBoard();
     addTodoCards(board);
     addStatusCard(board);
@@ -292,15 +315,17 @@ export function refreshKanbanArtifacts(trigger) {
             in_progress: board.in_progress.length,
             gated: board.gated.length,
             done: board.done.length,
+            cancelled: board.cancelled.length,
         },
         html_path: wsPath(KANBAN_HTML_REL),
         json_path: wsPath(KANBAN_JSON_REL),
     };
     safeWrite(KANBAN_HTML_REL, renderKanbanHtml(snapshot));
     safeWrite(KANBAN_JSON_REL, JSON.stringify(snapshot, null, 2));
+    renderState.set(resolveWorkspaceRoot(), { last: Date.now() });
     return snapshot;
 }
-export function getOrRefreshKanbanSnapshot(trigger) {
+function readKanbanSnapshot() {
     const raw = safeRead(KANBAN_JSON_REL);
     if (!isReadError(raw)) {
         const parsed = tryParseJson(raw);
@@ -316,14 +341,17 @@ export function getOrRefreshKanbanSnapshot(trigger) {
                 version,
                 generated_at: generated,
                 trigger: savedTrigger,
-                board,
-                counts,
+                board: { ...emptyBoard(), ...board },
+                counts: { ...Object.fromEntries(COLUMNS.map((key) => [key, 0])), ...counts },
                 html_path: htmlPath,
                 json_path: jsonPath,
             };
         }
     }
-    return refreshKanbanArtifacts(trigger);
+    return undefined;
+}
+export function getOrRefreshKanbanSnapshot(trigger) {
+    return readKanbanSnapshot() ?? refreshKanbanArtifacts(trigger);
 }
 export function shouldAutoRefreshKanbanForPath(path) {
     const normalized = path.replace(/\\/g, "/").replace(/^\.?\//, "");

package/dist/learned-artifacts.d.ts

@@ -0,0 +1,64 @@
+import { type LearnedArtifact } from './learning-records.js';
+export { decodeLearned, type LearnedArtifact } from './learning-records.js';
+import { type PlaybookScope, type PlaybookSection } from './store/repositories/playbook-repository.js';
+import { type IAcePackedStore } from './store/types.js';
+import type { GoalEngineDeps } from './goal-engine.js';
+export interface LearnedPayload {
+    lessons?: Array<{
+        op: 'add' | 'edit' | 'retire';
+        bullet_id?: string;
+        section: PlaybookSection;
+        content: string;
+        scope: PlaybookScope;
+        episodes: string[];
+        retired_episodes?: string[];
+    }>;
+    skill?: {
+        op: 'add' | 'edit';
+        slug: string;
+        skill_md: string;
+        references?: Record<string, string>;
+        episodes: string[];
+        retired_episodes?: string[];
+    };
+    instruction?: {
+        role: string;
+        text: string;
+        episodes: string[];
+    };
+}
+export interface LearningAcceptance {
+    ok: boolean;
+    ids: string[];
+    errors: string[];
+    reason_code?: string;
+    options?: Array<{
+        tool: string;
+        args: Record<string, unknown>;
+        why: string;
+    }>;
+}
+export declare function listLearnedArtifacts(root: string): LearnedArtifact[];
+export declare function withLearnedStore<T>(root: string, apply: (store: IAcePackedStore) => Promise<T>): Promise<T>;
+export declare function saveLearnedArtifact(root: string, item: LearnedArtifact): Promise<void>;
+export declare function updateLearnedArtifact(root: string, key: string, update: (item: LearnedArtifact) => LearnedArtifact | undefined): Promise<void>;
+export declare function prepareLearned(root: string, payload: LearnedPayload, context: {
+    goal_id: string;
+    step_id: string;
+    attempt: number;
+}, deps?: GoalEngineDeps): Promise<{
+    result: LearningAcceptance;
+    publish: () => Promise<void>;
+}>;
+export declare function acceptLearned(root: string, payload: LearnedPayload, context: {
+    goal_id: string;
+    step_id: string;
+    attempt: number;
+}, deps?: GoalEngineDeps): Promise<LearningAcceptance>;
+export declare function regenerateLearnedProjection(root: string): Promise<void>;
+export declare function ensureLearningStep(root: string, force?: {
+    scope: PlaybookScope;
+    reason: string;
+}): Promise<void>;
+export declare function reopenLearningCorrection(root: string, errors: string[]): Promise<void>;
+//# sourceMappingURL=learned-artifacts.d.ts.map

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