@hmharness/evolution 0.14.7 → 0.14.9

package/dist/skills.js.v2bak.v2bak

@@ -0,0 +1,321 @@
+/**
+ * @hmharness/evolution - skills
+ * The skill library with a three-state lifecycle:
+ *   skills/draft/<name>/    drafted by the evolution loop, never injected
+ *   skills/active/<name>/   promoted skills, injected into the system prompt
+ *   skills/archive/<ts>_<name>/  snapshots taken before each promotion
+ * Root-level skills/<name>/ from Phase 0 still counts as active (compat).
+ * Promotion is move-based and each promote snapshots the incumbent so a
+ * bench regression can roll back - the DGM/GDPevo lesson: no promotion
+ * without a gate, no gate without a rollback path.
+ */
+import { cp, mkdir, readdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execCb = promisify(execFile);
+/** Skills the user pinned: evolution never moves, merges or decays them.
+ *  Marked by a .pin file next to SKILL.md (cheap, visible, git-friendly). */
+export async function pinSkill(home, name) {
+    for (const dir of [join(home, 'skills', 'active', sanitize(name)), join(home, 'skills', sanitize(name)), join(home, 'skills', 'canary', sanitize(name))]) {
+        try {
+            await writeFile(join(dir, '.pin'), String(new Date().toISOString()), 'utf8');
+            return true;
+        }
+        catch { /* try next location */ }
+    }
+    return false;
+}
+export async function unpinSkill(home, name) {
+    for (const dir of [join(home, 'skills', 'active', sanitize(name)), join(home, 'skills', sanitize(name)), join(home, 'skills', 'canary', sanitize(name))]) {
+        try {
+            await rm(join(dir, '.pin'), { force: true });
+            return true;
+        }
+        catch { /* try next */ }
+    }
+    return false;
+}
+export async function isPinned(file) {
+    try {
+        await readFile(join(dirname(file), '.pin'), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function dirname(p) {
+    const m = /^(.*)[\\/][^\\/]+$/.exec(p);
+    return m?.[1] ?? p;
+}
+/**
+ * Install skills from a git URL or a local directory (`hmh skills add <src>`).
+ * Handles the three common repo layouts: SKILL.md at the root (single skill),
+ * skills/<name>/SKILL.md (multi-skill pack, e.g. greensock/gsap-skills), and
+ * <name>/SKILL.md one level down. Existing skill names are never overwritten.
+ */
+export async function installSkills(src, home) {
+    let rootDir;
+    let tmpDir = null;
+    const isUrl = /^https?:\/\/|git@/.test(src);
+    if (isUrl) {
+        tmpDir = join(tmpdir(), `hmh-skill-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`);
+        await execCb('git', ['clone', '--depth', '1', src, tmpDir], { timeout: 120_000, windowsHide: true });
+        rootDir = tmpDir;
+    }
+    else {
+        rootDir = src;
+    }
+    try {
+        // locate SKILL.md directories
+        const found = [];
+        if (await exists(join(rootDir, 'SKILL.md'))) {
+            found.push({ name: basename(rootDir), dir: rootDir });
+        }
+        for (const sub of ['skills', '.claude/skills', '.agents/skills']) {
+            const packDir = join(rootDir, sub);
+            for (const d of await dirs(packDir)) {
+                if (await exists(join(d.path, 'SKILL.md')))
+                    found.push({ name: d.name, dir: d.path });
+            }
+        }
+        if (!found.length) {
+            for (const d of await dirs(rootDir)) {
+                if (['.git', 'node_modules', '.github', 'examples', 'assets'].includes(d.name))
+                    continue;
+                if (await exists(join(d.path, 'SKILL.md')))
+                    found.push({ name: d.name, dir: d.path });
+            }
+        }
+        const installed = [];
+        const skipped = [];
+        const dest = join(home, 'skills');
+        await mkdir(dest, { recursive: true });
+        const taken = new Set((await readdir(dest, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name));
+        for (const f of found) {
+            const name = f.name.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase();
+            if (taken.has(name) || (await listSkills(home)).some((s) => s.name === name)) {
+                skipped.push(name);
+                continue;
+            }
+            await cp(f.dir, join(dest, name), { recursive: true });
+            taken.add(name);
+            installed.push(name);
+        }
+        return { installed, skipped };
+    }
+    finally {
+        if (tmpDir)
+            await rm(tmpDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+async function exists(p) {
+    try {
+        await readFile(p, 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function dirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true }))
+            .filter((d) => d.isDirectory())
+            .map((d) => ({ name: d.name, path: join(p, d.name) }));
+    }
+    catch {
+        return [];
+    }
+}
+function basename(p) {
+    const m = /[\\/]?([^\\/]+)[\\/]?$/.exec(p.replace(/[\\/]+$/, ''));
+    return m?.[1] ?? 'skill';
+}
+export async function listSkills(home) {
+    const root = join(home, 'skills');
+    // Phase 0 layout: skills/<name>/SKILL.md directly under root (excluding lifecycle dirs)
+    const legacy = await scan(join(root), ['draft', 'active', 'canary', 'archive'], 'active');
+    const active = await scan(join(root, 'active'), [], 'active');
+    return [...legacy, ...active].sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function listDrafts(home) {
+    return scan(join(home, 'skills', 'draft'), [], 'draft');
+}
+/** Canary-state skills: promoted through the bench gates but still under
+ *  impact evaluation - injected into a sample of sessions, watermarked. */
+export async function listCanary(home) {
+    return scan(join(home, 'skills', 'canary'), [], 'canary');
+}
+async function scan(dir, exclude, state) {
+    let dirs;
+    try {
+        dirs = (await readdir(dir, { withFileTypes: true })).filter((d) => d.isDirectory() && !exclude.includes(d.name));
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const d of dirs) {
+        const file = join(dir, d.name, 'SKILL.md');
+        try {
+            entries.push({ name: d.name, description: parseDescription(await readFile(file, 'utf8')), file, state });
+        }
+        catch {
+            /* directory without SKILL.md - not a skill */
+        }
+    }
+    return entries;
+}
+export function skillsToPrompt(entries) {
+    if (entries.length === 0)
+        return '';
+    return entries.map((s) => `- ${s.name}: ${s.description || '(no description)'}`).join('\n');
+}
+/** Write (or overwrite) a draft; drafts are cheap and reversible by deletion. */
+export async function writeDraft(home, name, skillMd) {
+    const dir = join(home, 'skills', 'draft', sanitize(name));
+    await mkdir(dir, { recursive: true });
+    const file = join(dir, 'SKILL.md');
+    await writeFile(file, skillMd, 'utf8');
+    return file;
+}
+/**
+ * Promote a draft. Default target is `canary` (P0: bench-passing skills
+ * earn a canary slot first; full activation happens through the impact
+ * loop, not on the gate alone). `{canary: false}` promotes straight to
+ * active (used by the impact loop once evidence clears, and by `hmh skills
+ * promote`). If a same-name skill exists at the destination it is archived
+ * first (timestamped snapshot) so promotion is always reversible.
+ */
+export async function promoteSkill(home, name, opts = {}) {
+    const safe = sanitize(name);
+    const draftDir = join(home, 'skills', 'draft', safe);
+    const activeDir = join(home, 'skills', 'active', safe);
+    const canaryDir = join(home, 'skills', 'canary', safe);
+    const legacyDir = join(home, 'skills', safe);
+    await mkdir(join(home, 'skills', 'active'), { recursive: true });
+    await mkdir(join(home, 'skills', 'archive'), { recursive: true });
+    if (opts.canary !== false)
+        await mkdir(join(home, 'skills', 'canary'), { recursive: true });
+    let archivedPrevious = false;
+    // archive incumbents at both destinations: active/legacy AND an existing
+    // canary slot (re-promoting a canary skill must not rename onto an
+    // occupied directory - that is EPERM on Windows)
+    for (const existing of [activeDir, legacyDir, join(home, 'skills', 'canary', safe)]) {
+        try {
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            await rename(existing, join(home, 'skills', 'archive', `${stamp}_${safe}`));
+            archivedPrevious = true;
+        }
+        catch {
+            /* nothing at this path */
+        }
+    }
+    await rename(draftDir, opts.canary === false ? activeDir : canaryDir);
+    return { file: join(opts.canary === false ? activeDir : canaryDir, 'SKILL.md'), archivedPrevious };
+}
+/** Graduate a canary skill to full active (the impact loop's decision). */
+export async function promoteCanary(home, name) {
+    const safe = sanitize(name);
+    await mkdir(join(home, 'skills', 'active'), { recursive: true });
+    try {
+        await rename(join(home, 'skills', 'canary', safe), join(home, 'skills', 'active', safe));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Retire a canary skill back to draft (impact loop's rejection path) -
+ *  nothing is ever deleted (append-only red line). */
+export async function retireCanary(home, name) {
+    const safe = sanitize(name);
+    await mkdir(join(home, 'skills', 'draft'), { recursive: true });
+    try {
+        const dest = join(home, 'skills', 'draft', safe);
+        try {
+            await rm(dest, { recursive: true, force: true });
+        }
+        catch { /* not there */ }
+        await rename(join(home, 'skills', 'canary', safe), dest);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Restore the most recent archived snapshot of a skill back to active. */
+export async function rollbackSkill(home, name) {
+    const safe = sanitize(name);
+    const archiveRoot = join(home, 'skills', 'archive');
+    let snapshots;
+    try {
+        snapshots = (await readdir(archiveRoot)).filter((d) => d.endsWith(`_${safe}`)).sort();
+    }
+    catch {
+        return false;
+    }
+    const latest = snapshots.pop();
+    if (!latest)
+        return false;
+    await mkdir(join(home, 'skills', 'active'), { recursive: true });
+    // Move the regressed incumbent out of the way first (rename onto an
+    // existing directory fails on Windows), keeping it as a rejected snapshot.
+    for (const cur of [join(home, 'skills', 'active', safe), join(home, 'skills', safe)]) {
+        try {
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+            await rename(cur, join(archiveRoot, `rejected-${stamp}_${safe}`));
+            break;
+        }
+        catch {
+            /* nothing at this path */
+        }
+    }
+    await rename(join(archiveRoot, latest), join(home, 'skills', 'active', safe));
+    return true;
+}
+/** Demote an active skill back to draft without deleting anything. */
+export async function unpromoteSkill(home, name) {
+    const safe = sanitize(name);
+    for (const from of [join(home, 'skills', 'active', safe), join(home, 'skills', safe)]) {
+        try {
+            await mkdir(join(home, 'skills', 'draft'), { recursive: true });
+            await rename(from, join(home, 'skills', 'draft', safe));
+            return true;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return false;
+}
+export async function deleteDraft(home, name) {
+    try {
+        await rm(join(home, 'skills', 'draft', sanitize(name)), { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function sanitize(name) {
+    return name.replace(/[^a-zA-Z0-9_-]/g, '-').slice(0, 60) || 'skill';
+}
+function parseDescription(text) {
+    // frontmatter "description:" line, or first non-heading non-empty line
+    const fm = text.match(/^---\n([\s\S]*?)\n---/);
+    if (fm) {
+        const m = fm[1].match(/^description:\s*(.+)$/m);
+        if (m)
+            return m[1].trim().slice(0, 120);
+    }
+    for (const line of text.split('\n')) {
+        const t = line.trim();
+        if (t && !t.startsWith('#') && !t.startsWith('---'))
+            return t.slice(0, 120);
+    }
+    return '';
+}

package/dist/workflows.d.ts.v2bak.v2bak

@@ -0,0 +1,28 @@
+/**
+ * @hmharness/evolution - workflows (AWM: Agent Workflow Memory, arxiv 2409.07429)
+ * Verified lesson from the paper: inducing commonly REUSED routines from
+ * past task trajectories and injecting them on demand beats stacking raw
+ * trajectories or per-mistake notes. Here the "repeated trajectory" signal
+ * is insight clustering: the same task archetype occurring 3+ times
+ * triggers one meta-model call that distills a PARAMETERIZED workflow
+ * template ({{placeholders}}), which then flows through the EXISTING
+ * draft -> poison-screen -> bench-gate pipeline. No new gate is opened -
+ * a workflow is just a skill with a shape.
+ */
+import { type ProviderConfig } from '@hmharness/kernel';
+import { type SkillProposal } from './evolve.ts';
+export interface WorkflowCluster {
+    key: string;
+    tasks: string[];
+    outcomes: string[];
+}
+/** Find task archetypes that occurred >= minRepeat times in the recent
+ *  insight history - the AWM reuse signal. */
+export declare function findWorkflowClusters(home: string, minRepeat?: number, lookback?: number): Promise<WorkflowCluster[]>;
+/** Induce a parameterized workflow proposal from a cluster (one meta-model
+ *  call; falls back to null on any refusal/parse failure/poison hit). */
+export declare function induceWorkflow(provider: ProviderConfig, cluster: WorkflowCluster): Promise<SkillProposal | null>;
+/** The full AWM step for one evolution cycle: find fresh clusters and
+ *  induce at most one workflow proposal (budget-conscious; the existing
+ *  gate pipeline does the actual accept/reject). */
+export declare function workflowProposals(provider: ProviderConfig, home: string, say: (l: string) => void): Promise<SkillProposal[]>;

package/dist/workflows.js.v2bak.v2bak

@@ -0,0 +1,84 @@
+/**
+ * @hmharness/evolution - workflows (AWM: Agent Workflow Memory, arxiv 2409.07429)
+ * Verified lesson from the paper: inducing commonly REUSED routines from
+ * past task trajectories and injecting them on demand beats stacking raw
+ * trajectories or per-mistake notes. Here the "repeated trajectory" signal
+ * is insight clustering: the same task archetype occurring 3+ times
+ * triggers one meta-model call that distills a PARAMETERIZED workflow
+ * template ({{placeholders}}), which then flows through the EXISTING
+ * draft -> poison-screen -> bench-gate pipeline. No new gate is opened -
+ * a workflow is just a skill with a shape.
+ */
+import { chat } from '@hmharness/kernel';
+import { readInsights } from "./insights.js";
+import { screenForPoison } from "./evolve.js";
+/** Cluster insights by task archetype: normalized prefix (first ~24 chars,
+ *  alphanumerics lowercased) groups "fix build error in module X" tasks. */
+function archetypeKey(task) {
+    const norm = task.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff ]+/g, ' ').replace(/\s+/g, ' ').trim();
+    return norm.split(' ').slice(0, 6).join(' ').slice(0, 32) || norm.slice(0, 24);
+}
+/** Find task archetypes that occurred >= minRepeat times in the recent
+ *  insight history - the AWM reuse signal. */
+export async function findWorkflowClusters(home, minRepeat = 3, lookback = 120) {
+    const insights = await readInsights(home, lookback);
+    const groups = new Map();
+    for (const i of insights) {
+        const key = archetypeKey(i.task);
+        const g = groups.get(key) ?? { key, tasks: [], outcomes: [] };
+        g.tasks.push(i.task.slice(0, 100));
+        g.outcomes.push(i.outcome);
+        groups.set(key, g);
+    }
+    return [...groups.values()].filter((g) => g.tasks.length >= minRepeat);
+}
+/** Induce a parameterized workflow proposal from a cluster (one meta-model
+ *  call; falls back to null on any refusal/parse failure/poison hit). */
+export async function induceWorkflow(provider, cluster) {
+    const system = [
+        'You induce reusable workflow templates for a coding agent, from repeated task instances (Agent Workflow Memory).',
+        'Output ONE skill in the standard format. The body must be a parameterized routine: use {{placeholders}} for the varying parts (module names, error strings, targets) so the agent fills them per task.',
+        'Rules: name is kebab-case ending in "-workflow"; description is one line starting with the trigger condition ("when ..."); skill_md max 50 lines, concrete steps with real commands; no security/approval topics.',
+        'If the instances do not actually share a reusable routine, output exactly: NONE',
+        'Respond with ONLY JSON: {"name":"...","description":"...","skill_md":"..."} - no prose, no fences.',
+    ].join('\n');
+    const user = `Task archetype "${cluster.key}" occurred ${cluster.tasks.length}x:\n${cluster.tasks.map((t) => `- ${t}`).join('\n')}\n\nInduce the parameterized workflow.`;
+    try {
+        const r = await chat(provider, [
+            { role: 'system', content: system },
+            { role: 'user', content: user },
+        ]);
+        const raw = (r.message.content ?? '').trim();
+        if (!raw || raw === 'NONE')
+            return null;
+        const m = raw.match(/\{[\s\S]*\}/);
+        if (!m)
+            return null;
+        const o = JSON.parse(m[0]);
+        if (typeof o.name !== 'string' || typeof o.skill_md !== 'string' || !o.name || !o.skill_md)
+            return null;
+        if (screenForPoison(o.skill_md))
+            return null;
+        return { name: o.name, description: o.description ?? '', skill_md: o.skill_md };
+    }
+    catch {
+        return null;
+    }
+}
+/** The full AWM step for one evolution cycle: find fresh clusters and
+ *  induce at most one workflow proposal (budget-conscious; the existing
+ *  gate pipeline does the actual accept/reject). */
+export async function workflowProposals(provider, home, say) {
+    const clusters = await findWorkflowClusters(home, 3, 120);
+    if (clusters.length === 0)
+        return [];
+    // already-proposed archetypes (by name convention <arch>-workflow) need no re-run
+    say(`awm: ${clusters.length} repeated task archetype(s)`);
+    const cluster = clusters.sort((a, b) => b.tasks.length - a.tasks.length)[0];
+    const p = await induceWorkflow(provider, cluster);
+    if (!p) {
+        say('awm: no reusable routine induced');
+        return [];
+    }
+    return [p];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/evolution",
-  "version": "0.14.7",
+  "version": "0.14.9",
   "description": "hmharness evolution subsystem: persistent memory, insight capture, skill library, and the bench that gives evolution its fitness signal. First-class kernel citizen, not a plugin.",
   "type": "module",
   "main": "dist/index.js",