@cohortapp/agent-sdk 2.3.0

package/lib/learning/curator.mjs

@@ -0,0 +1,453 @@
+/**
+ * lib/learning/curator.mjs — deterministic skill lifecycle (WS3).
+ *
+ * Pure state-machine over the usage sidecar (state/learning/skills.json), run
+ * as a low-frequency `skill-curator` cadence. No LLM:
+ *
+ *   active  ──(30d no activity)──▶  stale
+ *   stale   ──(90d no activity)──▶  archived
+ *
+ * `last_activity` is bumped by the reflect pass whenever a skill id appears in a
+ * transcript (lib/learning/skill-writer.touchSkill). ARCHIVE means MOVE the
+ * `.md` into plugins/agent-skills/skills/_archive/ and DROP it from plugin.json
+ * — never delete, so a re-surfaced procedure can be restored. `pinned` skills
+ * are exempt from every transition.
+ *
+ * Fail-open: any FS error on an individual skill is recorded but never aborts
+ * the sweep; the function never throws.
+ *
+ * @module lib/learning/curator
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { readSidecar, writeSidecar, skillsDir, writeSkill, appendSkillAudit } from "./skill-writer.mjs";
+
+const PLUGIN_JSON_REL = join("plugins", "agent-skills", "plugin.json");
+const ARCHIVE_SUBDIR = "_archive";
+const DAY_MS = 86400_000;
+
+/** Consolidation defaults (mirror config/learning.yaml consolidation block). */
+export const DEFAULT_MIN_SKILLS = 5;
+export const DEFAULT_CONSOLIDATION_INTERVAL_DAYS = 14;
+const CONSOLIDATE_TIMEOUT_MS = 120_000;
+const SKILL_BODY_EXCERPT_CHARS = 1200;
+const MAX_SKILLS_IN_PROMPT = 40;
+
+/** Default thresholds (days). Overridable via runCurator opts / config. */
+export const DEFAULT_STALE_DAYS = 30;
+export const DEFAULT_ARCHIVE_DAYS = 90;
+
+/** Age in ms of a sidecar record relative to `nowMs`. Falls back to created_at. */
+function ageMs(rec, nowMs) {
+  const stamp = rec.last_activity || rec.created_at;
+  const t = Date.parse(stamp);
+  if (!Number.isFinite(t)) return 0; // unknown stamp → treat as fresh (no transition)
+  return nowMs - t;
+}
+
+/**
+ * Compute the next state for one record given its age. Pure — the transition
+ * core, unit-tested directly.
+ *
+ *   pinned                         → unchanged (exempt)
+ *   active, age ≥ archiveDays      → archived (skip straight past stale)
+ *   active, age ≥ staleDays        → stale
+ *   stale,  age ≥ archiveDays      → archived
+ *   else                           → unchanged
+ *
+ * @param {object} rec - sidecar record { state, pinned, last_activity, created_at }
+ * @param {object} opts - { nowMs, staleDays, archiveDays }
+ * @returns {string} the next state
+ */
+export function nextState(rec, opts = {}) {
+  const cur = rec.state || "active";
+  if (rec.pinned === true) return cur;
+  if (cur === "archived") return cur;
+  const nowMs = Number.isFinite(opts.nowMs) ? opts.nowMs : Date.now();
+  const staleDays = Number.isFinite(opts.staleDays) ? opts.staleDays : DEFAULT_STALE_DAYS;
+  const archiveDays = Number.isFinite(opts.archiveDays) ? opts.archiveDays : DEFAULT_ARCHIVE_DAYS;
+  const age = ageMs(rec, nowMs);
+  if (age >= archiveDays * DAY_MS) return "archived";
+  if (cur === "active" && age >= staleDays * DAY_MS) return "stale";
+  return cur;
+}
+
+/** Atomic file write (tmp + rename in the same dir). */
+function writeAtomicFile(absPath, contents) {
+  mkdirSync(dirname(absPath), { recursive: true });
+  const tmp = `${absPath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, contents);
+  renameSync(tmp, absPath);
+}
+
+/** Drop a skill id (by manifest `name`) from plugin.json, atomically. Fail-open. */
+function dropFromPlugin(agentRoot, id) {
+  try {
+    const p = join(agentRoot, PLUGIN_JSON_REL);
+    if (!existsSync(p)) return;
+    const manifest = JSON.parse(readFileSync(p, "utf8"));
+    if (!manifest || !Array.isArray(manifest.skills)) return;
+    const before = manifest.skills.length;
+    manifest.skills = manifest.skills.filter((s) => s && s.name !== id);
+    if (manifest.skills.length !== before) {
+      writeAtomicFile(p, JSON.stringify(manifest, null, 2) + "\n");
+    }
+  } catch { /* fail-open */ }
+}
+
+/**
+ * Move a skill .md into skills/_archive/. Returns true if the file was moved
+ * (or was already absent — archive is idempotent). Fail-open → false on error.
+ */
+function archiveFile(agentRoot, id) {
+  try {
+    const dir = skillsDir(agentRoot);
+    const from = join(dir, `${id}.md`);
+    const archiveDir = join(dir, ARCHIVE_SUBDIR);
+    const to = join(archiveDir, `${id}.md`);
+    if (!existsSync(from)) return true; // nothing to move (already archived/removed)
+    mkdirSync(archiveDir, { recursive: true });
+    renameSync(from, to);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run one curator sweep over the sidecar. Applies active→stale→archived
+ * transitions, performs the archive move + plugin.json drop on newly-archived
+ * skills, and persists the updated sidecar. Deterministic; never throws.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {number|Date} [o.now]          injectable clock (tests)
+ * @param {number} [o.staleDays]
+ * @param {number} [o.archiveDays]
+ * @returns {{transitioned:Array<{id,from,to}>, archived:string[], errors:string[]}}
+ */
+export function runCurator(o = {}) {
+  const agentRoot = o.agentRoot;
+  const out = { transitioned: [], archived: [], errors: [] };
+  if (!agentRoot) return out;
+
+  const nowMs = o.now instanceof Date ? o.now.getTime() : (Number.isFinite(o.now) ? o.now : Date.now());
+  const sidecar = readSidecar(agentRoot);
+  let dirty = false;
+
+  for (const id of Object.keys(sidecar)) {
+    const rec = sidecar[id];
+    if (!rec || typeof rec !== "object") continue;
+    const from = rec.state || "active";
+    const to = nextState(rec, { nowMs, staleDays: o.staleDays, archiveDays: o.archiveDays });
+    if (to === from) continue;
+
+    if (to === "archived") {
+      const moved = archiveFile(agentRoot, id);
+      if (!moved) { out.errors.push(id); continue; } // leave state as-is; retry next sweep
+      dropFromPlugin(agentRoot, id);
+      out.archived.push(id);
+    }
+    rec.state = to;
+    rec.archived_at = to === "archived" ? new Date(nowMs).toISOString() : rec.archived_at;
+    out.transitioned.push({ id, from, to });
+    dirty = true;
+  }
+
+  if (dirty) writeSidecar(agentRoot, sidecar);
+  return out;
+}
+
+/**
+ * Cheap guard for the guarded cadence: is there at least one non-pinned skill
+ * that would transition on a sweep right now? Lets the cadence handler skip the
+ * sweep entirely when nothing has crossed a boundary. Pure-ish (reads sidecar).
+ * @param {string} agentRoot
+ * @param {object} [opts] - { now, staleDays, archiveDays }
+ * @returns {boolean}
+ */
+export function hasPendingTransitions(agentRoot, opts = {}) {
+  if (!agentRoot) return false;
+  const nowMs = opts.now instanceof Date ? opts.now.getTime() : (Number.isFinite(opts.now) ? opts.now : Date.now());
+  const sidecar = readSidecar(agentRoot);
+  for (const id of Object.keys(sidecar)) {
+    const rec = sidecar[id];
+    if (!rec || typeof rec !== "object") continue;
+    if (nextState(rec, { nowMs, staleDays: opts.staleDays, archiveDays: opts.archiveDays }) !== (rec.state || "active")) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ===========================================================================
+// LLM umbrella consolidation (WS3 phase 2)
+// ---------------------------------------------------------------------------
+// The deterministic transitions above are housekeeping; consolidation is the
+// one place the curator needs judgement. It MERGES narrowly-overlapping
+// agent-authored skills into ONE class-level umbrella skill, so a swarm of
+// near-duplicate procedures collapses into a reusable parent. The LLM is a
+// bounded, injectable function (default: one `claude --print` sonnet call built
+// like reflect.mjs); it runs as a DETACHED worker from the skill-curator guard,
+// never as a nested sub-session. Fully fail-open + time-boxed: any throw → a
+// no-op summary, never an exception.
+// ===========================================================================
+
+/** Read a skill's .md (name/description from frontmatter + a body excerpt). Fail-open. */
+function readSkillSummary(agentRoot, id) {
+  try {
+    const p = join(skillsDir(agentRoot), `${id}.md`);
+    if (!existsSync(p)) return null;
+    const md = readFileSync(p, "utf8");
+    // Frontmatter is a leading --- … --- block (skill-writer renderSkillMd).
+    let name = id, description = "", body = md;
+    const fm = md.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (fm) {
+      body = fm[2] || "";
+      for (const line of fm[1].split("\n")) {
+        const m = line.match(/^(name|description):\s*(.*)$/);
+        if (m && m[1] === "name") name = m[2].trim() || id;
+        else if (m && m[1] === "description") description = m[2].trim();
+      }
+    }
+    const excerpt = String(body).trim().slice(0, SKILL_BODY_EXCERPT_CHARS);
+    return { id, name, description, excerpt };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Select consolidation candidates: agent-authored, active, non-pinned skills
+ * that still have a .md on disk. Returns enriched summaries (capped). Pure-ish.
+ * @param {string} agentRoot
+ * @returns {Array<{id,name,description,excerpt}>}
+ */
+export function selectConsolidationCandidates(agentRoot) {
+  const sidecar = readSidecar(agentRoot);
+  const out = [];
+  for (const id of Object.keys(sidecar)) {
+    const rec = sidecar[id];
+    if (!rec || typeof rec !== "object") continue;
+    if (rec.created_by !== "agent") continue;
+    if ((rec.state || "active") !== "active") continue;
+    if (rec.pinned === true) continue;
+    const summary = readSkillSummary(agentRoot, id);
+    if (summary) out.push(summary);
+    if (out.length >= MAX_SKILLS_IN_PROMPT) break;
+  }
+  return out;
+}
+
+/**
+ * Build the consolidation prompt (ports the intent of Hermes's CURATOR_REVIEW
+ * prompt). Asks the model to cluster the candidates and propose ONE umbrella per
+ * cluster of ≥2 genuinely-overlapping siblings; strict-JSON output, conservative.
+ * @param {Array<{id,name,description,excerpt}>} candidates
+ * @returns {string}
+ */
+export function buildConsolidationPrompt(candidates) {
+  const lines = [
+    "You are the skill CURATOR for an autonomous AI agent. Over time the agent",
+    "has authored many narrow skills. Your job is to consolidate genuinely-",
+    "overlapping siblings into a single CLASS-LEVEL umbrella skill that subsumes",
+    "them — so the agent reaches for one well-scoped parent instead of a dozen",
+    "near-duplicates.",
+    "",
+    "Cluster the skills below. For each cluster of TWO OR MORE narrowly-",
+    "overlapping skills, propose ONE umbrella skill that covers all of them as a",
+    "general, re-runnable method. Reuse the concrete steps from the members.",
+    "",
+    "Be CONSERVATIVE. Only merge genuinely-overlapping siblings:",
+    "  - DO NOT merge skills from unrelated domains (e.g. a billing-reconciliation",
+    "    skill and a calendar-scheduling skill are NOT siblings — leave them).",
+    "  - DO NOT merge a single skill into an 'umbrella' (a cluster needs ≥2).",
+    "  - DO NOT invent capabilities the members don't have; the umbrella must be a",
+    "    faithful generalisation of its absorbed members, nothing more.",
+    "  - When in doubt, leave skills separate. A missed merge is cheap; a wrong",
+    "    merge buries two distinct procedures under one vague parent.",
+    "",
+    "Each umbrella's `absorbs` MUST list the exact skill ids (from the list) it",
+    "replaces. Those skills will be archived and the umbrella created in their",
+    "place. Never list an id that isn't in the candidate list below.",
+    "",
+    "Respond with STRICT JSON and nothing else (no prose, no code fence):",
+    '  {"umbrellas": []}                         — if nothing should be merged, OR',
+    '  {"umbrellas": [{',
+    '     "name": "<short class-level name>",',
+    '     "description": "<one line: when to use this umbrella>",',
+    '     "body": "<markdown: trigger, ordered steps covering the members, success criteria>",',
+    '     "absorbs": ["<skill-id>", "<skill-id>", ...]   // ≥2 ids from the list',
+    "  }]}",
+    "",
+    "Default to {\"umbrellas\": []} unless a cluster is clearly overlapping.",
+    "",
+    "=== CANDIDATE SKILLS (agent-authored, active) ===",
+  ];
+  for (const c of candidates) {
+    lines.push(
+      `- id: ${c.id}`,
+      `  name: ${c.name}`,
+      `  description: ${c.description}`,
+      `  body: ${JSON.stringify(c.excerpt)}`,
+    );
+  }
+  lines.push("=== END ===");
+  return lines.join("\n");
+}
+
+/**
+ * Parse + validate the consolidation envelope against the known candidate ids.
+ * Filters absorbs to real candidate ids, rejects clusters of <2 valid ids, and
+ * (defensively) prevents the same id being absorbed by two umbrellas. Pure.
+ * @param {string} text
+ * @param {Set<string>} validIds
+ * @returns {Array<{name,description,body,absorbs:string[]}>}
+ */
+export function parseConsolidationEnvelope(text, validIds) {
+  if (!text || typeof text !== "string") return [];
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start === -1 || end === -1 || end <= start) return [];
+  let obj;
+  try { obj = JSON.parse(text.slice(start, end + 1)); }
+  catch { return []; }
+  if (!obj || typeof obj !== "object" || !Array.isArray(obj.umbrellas)) return [];
+  const claimed = new Set();
+  const out = [];
+  for (const u of obj.umbrellas) {
+    if (!u || typeof u !== "object") continue;
+    const name = String(u.name || "").trim();
+    const description = String(u.description || "").trim();
+    const body = String(u.body || "").trim();
+    if (!name || !body) continue;
+    const absorbs = Array.isArray(u.absorbs)
+      ? Array.from(new Set(u.absorbs.map((s) => String(s || "").trim())))
+          .filter((id) => id && validIds.has(id) && !claimed.has(id))
+      : [];
+    if (absorbs.length < 2) continue; // never merge a single skill into an umbrella
+    for (const id of absorbs) claimed.add(id);
+    out.push({ name, description, body, absorbs });
+  }
+  return out;
+}
+
+/** Default consolidation spawn: one `claude --print --model <sonnet>`. Fail-open → "". */
+export async function defaultConsolidateSpawn(prompt, opts = {}) {
+  try {
+    const { spawnSync } = await import("node:child_process");
+    const { resolveClaudeBin, daemonClaudeArgs, augmentedPath } = await import("../claude-bin.mjs");
+    const model = opts.model || "sonnet";
+    const args = ["--print", "--model", model, ...daemonClaudeArgs()];
+    const res = spawnSync(resolveClaudeBin(), args, {
+      input: prompt,
+      encoding: "utf8",
+      timeout: opts.timeoutMs || CONSOLIDATE_TIMEOUT_MS,
+      env: { ...process.env, PATH: augmentedPath() },
+      maxBuffer: 8 * 1024 * 1024,
+    });
+    if (res.status === 0 && res.stdout) return res.stdout;
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Consolidate narrowly-overlapping agent-authored skills into class-level
+ * umbrellas. Reads the sidecar → selects candidates → (if ≥ minSkills) builds a
+ * conservative clustering prompt → calls the injectable `spawn` → for each valid
+ * umbrella: writes it via skill-writer (secret-scan + plugin.json + audit), then
+ * archives every absorbed member (move to _archive/ + drop from plugin.json +
+ * sidecar state:"archived"/absorbed_into) and appends a consolidate audit row.
+ *
+ * Time-boxed, FULLY fail-open: any throw → { umbrellas:[], error }; never throws.
+ *
+ * @param {object} o
+ * @param {string}   o.agentRoot
+ * @param {Function} [o.spawn]      injectable reviewer (tests; no network). default = claude --print
+ * @param {number|Date} [o.now]
+ * @param {number}   [o.minSkills]  candidate floor below which we don't spawn (default 5)
+ * @param {string}   [o.model]      reviewer model (default "sonnet")
+ * @returns {Promise<{umbrellas:Array<{id,absorbed:string[]}>, reason?:string, error?:string}>}
+ */
+export async function consolidateUmbrellas(o = {}) {
+  try {
+    const agentRoot = o.agentRoot;
+    if (!agentRoot) return { umbrellas: [], reason: "no-agent-root" };
+    const minSkills = Number.isFinite(o.minSkills) ? o.minSkills : DEFAULT_MIN_SKILLS;
+    const nowMs = o.now instanceof Date ? o.now.getTime() : (Number.isFinite(o.now) ? o.now : Date.now());
+    const nowIso = new Date(nowMs).toISOString();
+
+    const candidates = selectConsolidationCandidates(agentRoot);
+    if (candidates.length < minSkills) {
+      return { umbrellas: [], reason: "below-threshold" };
+    }
+
+    const validIds = new Set(candidates.map((c) => c.id));
+    const prompt = buildConsolidationPrompt(candidates);
+    const spawn = o.spawn || defaultConsolidateSpawn;
+
+    let raw = "";
+    try {
+      raw = await spawn(prompt, { model: o.model || "sonnet", timeoutMs: CONSOLIDATE_TIMEOUT_MS, agentRoot });
+    } catch (e) {
+      // A throwing spawn is fail-open at the function boundary.
+      return { umbrellas: [], error: e && e.message ? e.message : String(e) };
+    }
+
+    const proposals = parseConsolidationEnvelope(raw, validIds);
+    if (!proposals.length) return { umbrellas: [], reason: "no-merge" };
+
+    const applied = [];
+    for (const u of proposals) {
+      // 1. Create the umbrella (skill-writer secret-scans + writes + plugin.json + audit).
+      //    trusted:true — this is system-internal consolidation, not untrusted
+      //    agent-authored output, so the umbrella lands live (not quarantined).
+      const wr = writeSkill({
+        agentRoot, action: "create", name: u.name, description: u.description, body: u.body,
+        sourceSession: "skill-curator", nowIso, trusted: true,
+      });
+      if (!wr.ok) {
+        appendSkillAudit(agentRoot, { action: "consolidate_abort", name: u.name, reason: wr.reason, absorbs: u.absorbs });
+        continue; // skip this cluster; don't archive members if the umbrella didn't land
+      }
+
+      // 2. Archive each absorbed member: move .md → _archive/, drop from plugin.json,
+      //    mark the sidecar record archived + absorbed_into the umbrella.
+      const sidecar = readSidecar(agentRoot);
+      const absorbed = [];
+      for (const id of u.absorbs) {
+        if (id === wr.id) continue; // never absorb the umbrella into itself
+        const moved = archiveFile(agentRoot, id);
+        if (!moved) continue; // FS error on this member → leave it; never abort the batch
+        dropFromPlugin(agentRoot, id);
+        if (sidecar[id] && typeof sidecar[id] === "object") {
+          sidecar[id].state = "archived";
+          sidecar[id].archived_at = nowIso;
+          sidecar[id].absorbed_into = wr.id;
+        }
+        absorbed.push(id);
+      }
+      writeSidecar(agentRoot, sidecar);
+
+      // 3. Audit the consolidation.
+      appendSkillAudit(agentRoot, { action: "consolidate", umbrella: wr.id, absorbed });
+      applied.push({ id: wr.id, absorbed });
+    }
+
+    return { umbrellas: applied };
+  } catch (e) {
+    // Absolute fail-open: any unexpected throw → no umbrellas, never rethrow.
+    return { umbrellas: [], error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export default {
+  runCurator, nextState, hasPendingTransitions, consolidateUmbrellas,
+  selectConsolidationCandidates, buildConsolidationPrompt, parseConsolidationEnvelope,
+  DEFAULT_STALE_DAYS, DEFAULT_ARCHIVE_DAYS, DEFAULT_MIN_SKILLS, DEFAULT_CONSOLIDATION_INTERVAL_DAYS,
+};

package/lib/learning/curator.test.mjs

@@ -0,0 +1,106 @@
+/**
+ * curator.test.mjs — deterministic skill lifecycle tests.
+ * Run: node --test lib/learning/curator.test.mjs
+ *
+ * Covers: 30d active→stale, 90d →archived, archive MOVES (not deletes) +
+ * drops from plugin.json, pinned exempt, hasPendingTransitions guard.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runCurator, nextState, hasPendingTransitions } from "./curator.mjs";
+import { writeSkill, readSidecar, writeSidecar } from "./skill-writer.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "maestro-curator-"));
+}
+const skillPath = (root, id) => join(root, "plugins", "agent-skills", "skills", `${id}.md`);
+const archivePath = (root, id) => join(root, "plugins", "agent-skills", "skills", "_archive", `${id}.md`);
+const pluginJson = (root) => JSON.parse(readFileSync(join(root, "plugins", "agent-skills", "plugin.json"), "utf8"));
+
+const NOW = Date.parse("2026-06-09T00:00:00Z");
+const daysAgo = (n) => new Date(NOW - n * 86400_000).toISOString();
+
+test("nextState: pure transitions by age", () => {
+  assert.equal(nextState({ state: "active", last_activity: daysAgo(5) }, { nowMs: NOW }), "active");
+  assert.equal(nextState({ state: "active", last_activity: daysAgo(31) }, { nowMs: NOW }), "stale");
+  assert.equal(nextState({ state: "stale", last_activity: daysAgo(95) }, { nowMs: NOW }), "archived");
+  // active that's been silent >90d jumps straight to archived.
+  assert.equal(nextState({ state: "active", last_activity: daysAgo(120) }, { nowMs: NOW }), "archived");
+  // pinned is exempt regardless of age.
+  assert.equal(nextState({ state: "active", pinned: true, last_activity: daysAgo(365) }, { nowMs: NOW }), "active");
+  // archived is terminal.
+  assert.equal(nextState({ state: "archived", last_activity: daysAgo(365) }, { nowMs: NOW }), "archived");
+});
+
+test("runCurator: active→stale at 30d, no file move", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Aging Skill", description: "d", body: "x", nowIso: daysAgo(40), trusted: true });
+  // Backdate last_activity so it's stale-eligible.
+  const sc = readSidecar(root);
+  sc[a.id].last_activity = daysAgo(40);
+  writeSidecar(root, sc);
+
+  const res = runCurator({ agentRoot: root, now: NOW });
+  assert.deepEqual(res.transitioned, [{ id: a.id, from: "active", to: "stale" }]);
+  assert.deepEqual(res.archived, []);
+  assert.equal(readSidecar(root)[a.id].state, "stale");
+  assert.ok(existsSync(skillPath(root, a.id)), "stale skill still in place");
+});
+
+test("runCurator: stale→archived at 90d MOVES the file + drops from plugin.json (never deletes)", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Old Skill", description: "d", body: "ARCHIVE ME", nowIso: daysAgo(120), trusted: true });
+  const sc = readSidecar(root);
+  sc[a.id].state = "stale";
+  sc[a.id].last_activity = daysAgo(120);
+  writeSidecar(root, sc);
+  assert.equal(pluginJson(root).skills.length, 1);
+
+  const res = runCurator({ agentRoot: root, now: NOW });
+  assert.deepEqual(res.archived, [a.id]);
+  assert.equal(readSidecar(root)[a.id].state, "archived");
+
+  // File MOVED — gone from skills/, present in skills/_archive/ with body intact.
+  assert.ok(!existsSync(skillPath(root, a.id)), "removed from active skills dir");
+  assert.ok(existsSync(archivePath(root, a.id)), "moved into _archive (not deleted)");
+  assert.match(readFileSync(archivePath(root, a.id), "utf8"), /ARCHIVE ME/);
+
+  // Dropped from plugin.json manifest.
+  assert.equal(pluginJson(root).skills.length, 0, "dropped from plugin.json");
+});
+
+test("runCurator: pinned skill is exempt from all transitions", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Pinned Skill", description: "d", body: "keep", nowIso: daysAgo(400), trusted: true });
+  const sc = readSidecar(root);
+  sc[a.id].pinned = true;
+  sc[a.id].last_activity = daysAgo(400);
+  writeSidecar(root, sc);
+
+  const res = runCurator({ agentRoot: root, now: NOW });
+  assert.deepEqual(res.transitioned, []);
+  assert.equal(readSidecar(root)[a.id].state, "active");
+  assert.ok(existsSync(skillPath(root, a.id)), "pinned skill untouched");
+});
+
+test("hasPendingTransitions: true only when something would move", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Fresh", description: "d", body: "x", nowIso: daysAgo(2), trusted: true });
+  assert.equal(hasPendingTransitions(root, { now: NOW }), false, "fresh → nothing pending");
+  const sc = readSidecar(root);
+  sc[a.id].last_activity = daysAgo(45);
+  writeSidecar(root, sc);
+  assert.equal(hasPendingTransitions(root, { now: NOW }), true, "45d-old active → stale pending");
+});
+
+test("runCurator: no agentRoot / empty sidecar is a clean no-op", () => {
+  assert.deepEqual(runCurator({}), { transitioned: [], archived: [], errors: [] });
+  const root = tmpRoot();
+  assert.deepEqual(runCurator({ agentRoot: root, now: NOW }), { transitioned: [], archived: [], errors: [] });
+});

package/lib/learning/log.mjs

@@ -0,0 +1,40 @@
+/**
+ * lib/learning/log.mjs — append-only decision log for the self-learning loop.
+ *
+ * Every reflect decision (skipped / no-skill / skill-written / write-failed)
+ * lands in logs/learning/<YYYY-MM-DD>.jsonl. This is the operator-facing trail
+ * that complements logs/audit/skills.jsonl (which is the security trail of every
+ * create/patch/abort). Fail-open: never throws.
+ *
+ * @module lib/learning/log
+ */
+
+"use strict";
+
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const LOG_DIR_REL = join("logs", "learning");
+
+/** UTC date stamp for the log filename. */
+function dayStamp(nowMs) {
+  return new Date(Number.isFinite(nowMs) ? nowMs : Date.now()).toISOString().slice(0, 10);
+}
+
+/**
+ * Append one structured decision row to today's learning log. Fail-open.
+ * @param {string} agentRoot
+ * @param {object} row
+ * @param {object} [opts] - { nowMs }
+ */
+export function appendLearningLog(agentRoot, row, opts = {}) {
+  if (!agentRoot) return;
+  try {
+    const dir = join(agentRoot, LOG_DIR_REL);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, `${dayStamp(opts.nowMs)}.jsonl`);
+    appendFileSync(file, JSON.stringify({ ts: new Date(opts.nowMs || Date.now()).toISOString(), ...row }) + "\n");
+  } catch { /* fail-open */ }
+}
+
+export default { appendLearningLog };