@cohortapp/agent-sdk 2.3.0

package/lib/learning/skill-writer.mjs

@@ -0,0 +1,474 @@
+/**
+ * lib/learning/skill-writer.mjs — the autonomous skill write-path (WS3).
+ *
+ * When the reflect pass (lib/learning/reflect.mjs) decides the agent should
+ * capture a repeatable method, it calls writeSkill() here. Maestro skills are
+ * FLAT `.md` files with `name`/`description` frontmatter (NOT `<name>/SKILL.md`)
+ * — Claude Code loads them straight off disk via the plugin.json manifest.
+ *
+ * QUARANTINE (W1/W3): a newly authored skill is attacker-influencable (its body
+ * is distilled from transcript content that can contain inbound, attacker-
+ * controlled text). To stop self-poisoning, a CREATE does NOT land live. It is
+ * written PENDING and is NOT registered in plugin.json, so Claude Code never
+ * loads it until an operator runs approveSkill():
+ *
+ *   plugins/agent-skills/.pending/<id>.md   (status: pending — NOT loaded)
+ *       ── approveSkill() ──▶
+ *   plugins/agent-skills/skills/<id>.md      (live)
+ *   plugins/agent-skills/plugin.json         (skills[] manifest, create-or-replace)
+ *
+ * A PATCH of an ALREADY-LIVE (operator-approved) skill edits it in place; a
+ * "patch" of a skill that is not live is treated as a CREATE → pending.
+ *
+ * Governance is fully autonomous but AUDITED: every create / patch / approve /
+ * abort is appended to logs/audit/skills.jsonl, and a pending create also emits
+ * an operator notification line on stderr naming the skill + how to approve it.
+ * Before any byte is written, the rendered skill body is SECRET-SCANNED
+ * (lib/security/redact.mjs primitives + explicit token patterns: sk-ant / ghp_ /
+ * AKIA / bearer / password=); a hit ABORTS the write (no skill on disk) and logs
+ * the abort. We never git-commit — Claude Code reads the dir, not git.
+ *
+ * A usage sidecar (state/learning/skills.json) tracks lifecycle for the curator:
+ *   { id, created_by, created_at, last_activity, state, pinned }
+ * where state is "pending" until approved, then "active".
+ *
+ * Everything is fail-open and atomic (tmp + rename in the same dir).
+ *
+ * @module lib/learning/skill-writer
+ */
+
+"use strict";
+
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, appendFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { isSensitiveParamName } from "../security/redact.mjs";
+
+const SKILLS_DIR_REL = join("plugins", "agent-skills", "skills");
+const PENDING_DIR_REL = join("plugins", "agent-skills", ".pending");
+const PLUGIN_JSON_REL = join("plugins", "agent-skills", "plugin.json");
+const AUDIT_REL = join("logs", "audit", "skills.jsonl");
+const SIDECAR_REL = join("state", "learning", "skills.json");
+
+/**
+ * Explicit secret token patterns. The redact module's URL/param helpers catch
+ * `password=`, `apikey=`, `token=` style assignments; these catch bare credential
+ * literals an LLM might paste into a body verbatim.
+ * @type {Array<{label:string, re:RegExp}>}
+ */
+export const SECRET_PATTERNS = Object.freeze([
+  { label: "anthropic-key", re: /\bsk-ant-[A-Za-z0-9_-]{8,}/ },
+  { label: "openai-key", re: /\bsk-[A-Za-z0-9]{20,}/ },
+  { label: "github-pat", re: /\bgh[pousr]_[A-Za-z0-9]{20,}/ },
+  { label: "aws-access-key-id", re: /\bAKIA[0-9A-Z]{12,}/ },
+  { label: "google-api-key", re: /\bAIza[0-9A-Za-z_-]{30,}/ },
+  { label: "slack-token", re: /\bxox[baprs]-[0-9A-Za-z-]{10,}/ },
+  { label: "bearer-token", re: /\bBearer\s+[A-Za-z0-9._~+/-]{16,}=*/i },
+  { label: "private-key-block", re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----/ },
+]);
+
+/** A `key=value` / `key: value` assignment whose key looks sensitive (password=, secret: …). */
+const ASSIGNMENT_RE = /([A-Za-z0-9_.-]{2,40})\s*[:=]\s*("?[^\s"'`]{6,}"?)/g;
+
+/**
+ * Scan a rendered skill body for embedded secrets. Returns the list of hits
+ * (label + the matched lead-in, never the full secret). Empty array = clean.
+ * Pure; never throws.
+ *
+ * @param {string} body
+ * @returns {Array<{label:string, sample:string}>}
+ */
+export function scanForSecrets(body) {
+  const text = typeof body === "string" ? body : "";
+  if (!text) return [];
+  const hits = [];
+  for (const { label, re } of SECRET_PATTERNS) {
+    const m = text.match(re);
+    if (m) hits.push({ label, sample: redactSample(m[0]) });
+  }
+  // key=value / key: value where the key name reads as a secret (password, token…).
+  let a;
+  ASSIGNMENT_RE.lastIndex = 0;
+  while ((a = ASSIGNMENT_RE.exec(text)) !== null) {
+    const name = a[1];
+    if (isSensitiveParamName(name)) {
+      hits.push({ label: `assignment:${name.toLowerCase()}`, sample: `${name}=***` });
+    }
+  }
+  return hits;
+}
+
+/** Show only a non-reversible lead-in of a matched secret for the audit row. */
+function redactSample(s) {
+  const str = String(s);
+  return str.length <= 10 ? "***" : str.slice(0, 6) + "…***";
+}
+
+/**
+ * Slugify a free-text name into a filesystem-safe skill id. Lowercase, hyphen-
+ * separated, alnum only, bounded length.
+ * @param {string} name
+ * @returns {string}
+ */
+export function slugify(name) {
+  const base = String(name || "")
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60);
+  return base || "skill";
+}
+
+/** Directory holding LIVE (operator-approved) agent-authored skill .md files. */
+export function skillsDir(agentRoot) {
+  return join(agentRoot, SKILLS_DIR_REL);
+}
+
+/** Directory holding PENDING (quarantined, not-yet-approved) skill .md files. */
+export function pendingDir(agentRoot) {
+  return join(agentRoot, PENDING_DIR_REL);
+}
+
+/** True if a skill id is already live (loaded by Claude Code). */
+function isLiveSkill(agentRoot, id) {
+  return existsSync(join(skillsDir(agentRoot), `${id}.md`));
+}
+
+/**
+ * Resolve a unique skill id for a CREATE: slug, then -2, -3… if the id is
+ * already taken in EITHER the live or the pending dir (so a quarantined skill
+ * can't be silently clobbered by the next create). For a PATCH the caller passes
+ * the existing id and we keep it.
+ * @param {string} agentRoot
+ * @param {string} slug
+ * @returns {string}
+ */
+function dedupeId(agentRoot, slug) {
+  const taken = (cand) =>
+    existsSync(join(skillsDir(agentRoot), `${cand}.md`)) ||
+    existsSync(join(pendingDir(agentRoot), `${cand}.md`));
+  if (!taken(slug)) return slug;
+  for (let n = 2; n < 1000; n++) {
+    const cand = `${slug}-${n}`;
+    if (!taken(cand)) return cand;
+  }
+  return `${slug}-${Date.now()}`;
+}
+
+/** One-line frontmatter-safe value (no newlines, no leading list/colon traps). */
+function fmValue(s) {
+  return String(s == null ? "" : s).replace(/\s+/g, " ").replace(/"/g, "'").trim();
+}
+
+/**
+ * Render the full flat-skill `.md` (frontmatter + body). Matches the maestro
+ * skill format consumed by Claude Code + generate-capability.mjs.
+ * @param {object} o - { id, name, description, body, sourceSession, createdAt, status }
+ * @returns {string}
+ */
+export function renderSkillMd(o) {
+  const fm = [
+    "---",
+    `name: ${fmValue(o.name || o.id)}`,
+    `description: ${fmValue(o.description)}`,
+    "created_by: agent",
+    `status: ${fmValue(o.status || "approved")}`,
+    `created_at: ${fmValue(o.createdAt)}`,
+    `source_session: ${fmValue(o.sourceSession || "")}`,
+    "---",
+    "",
+  ].join("\n");
+  const body = String(o.body || "").trim();
+  return fm + body + "\n";
+}
+
+/** Rewrite the `status:` frontmatter line of a rendered skill .md (best-effort). */
+function withStatus(md, status) {
+  const text = String(md);
+  if (/^status:.*$/m.test(text)) return text.replace(/^status:.*$/m, `status: ${status}`);
+  // Older skills may predate the status line — insert it after created_by.
+  if (/^created_by:.*$/m.test(text)) return text.replace(/^(created_by:.*)$/m, `$1\nstatus: ${status}`);
+  return text;
+}
+
+/** Atomic file write (tmp + rename in the same dir). Throws on hard FS failure. */
+function writeAtomicFile(absPath, contents) {
+  mkdirSync(dirname(absPath), { recursive: true });
+  const tmp = `${absPath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, contents);
+  renameSync(tmp, absPath);
+}
+
+/** Append a row to logs/audit/skills.jsonl. Fail-open (never throws). */
+export function appendSkillAudit(agentRoot, row) {
+  try {
+    const p = join(agentRoot, AUDIT_REL);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify({ ts: new Date().toISOString(), ...row }) + "\n");
+  } catch { /* fail-open */ }
+}
+
+// ---------------------------------------------------------------------------
+// plugin.json manifest (create-or-replace by name)
+// ---------------------------------------------------------------------------
+
+function readPluginJson(agentRoot) {
+  const p = join(agentRoot, PLUGIN_JSON_REL);
+  if (!existsSync(p)) {
+    return { name: "agent-skills", description: "Agent-authored skills", version: "0.1.0", skills: [] };
+  }
+  try {
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    if (!obj || typeof obj !== "object") throw new Error("bad");
+    if (!Array.isArray(obj.skills)) obj.skills = [];
+    return obj;
+  } catch {
+    return { name: "agent-skills", description: "Agent-authored skills", version: "0.1.0", skills: [] };
+  }
+}
+
+/** Upsert a skill entry (matched by name) into plugin.json, atomically. */
+function upsertPluginEntry(agentRoot, entry) {
+  const manifest = readPluginJson(agentRoot);
+  const idx = manifest.skills.findIndex((s) => s && s.name === entry.name);
+  if (idx >= 0) manifest.skills[idx] = { ...manifest.skills[idx], ...entry };
+  else manifest.skills.push(entry);
+  writeAtomicFile(join(agentRoot, PLUGIN_JSON_REL), JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// ---------------------------------------------------------------------------
+// Usage sidecar (state/learning/skills.json) — the curator's source of truth
+// ---------------------------------------------------------------------------
+
+/** Read the usage sidecar (map id → record). Fail-open → {}. */
+export function readSidecar(agentRoot) {
+  const p = join(agentRoot, SIDECAR_REL);
+  if (!existsSync(p)) return {};
+  try {
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    return obj && typeof obj === "object" && !Array.isArray(obj) ? obj : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Write the usage sidecar atomically. Fail-open → false. */
+export function writeSidecar(agentRoot, sidecar) {
+  try {
+    writeAtomicFile(join(agentRoot, SIDECAR_REL), JSON.stringify(sidecar, null, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Bump last_activity for a skill id (called when the id appears in a transcript).
+ * Creates no new record if the id is unknown. Fail-open.
+ * @param {string} agentRoot
+ * @param {string} id
+ * @param {object} [opts] - { nowIso }
+ */
+export function touchSkill(agentRoot, id, opts = {}) {
+  if (!agentRoot || !id) return;
+  const sidecar = readSidecar(agentRoot);
+  if (!sidecar[id]) return;
+  sidecar[id].last_activity = opts.nowIso || new Date().toISOString();
+  writeSidecar(agentRoot, sidecar);
+}
+
+function upsertSidecar(agentRoot, id, patch) {
+  const sidecar = readSidecar(agentRoot);
+  const now = patch.now || new Date().toISOString();
+  const prev = sidecar[id] || {};
+  sidecar[id] = {
+    id,
+    created_by: prev.created_by || "agent",
+    created_at: prev.created_at || now,
+    last_activity: now,
+    state: patch.state || prev.state || "active",
+    pinned: prev.pinned === true,
+  };
+  writeSidecar(agentRoot, sidecar);
+  return sidecar[id];
+}
+
+// ---------------------------------------------------------------------------
+// writeSkill — the public entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Create or patch an agent-authored skill on disk, with a pre-write secret scan,
+ * sidecar update, and audit logging.
+ *
+ * A CREATE is QUARANTINED: it lands in the `.pending/` dir (NOT registered in
+ * plugin.json, so Claude Code never loads it) with `state:"pending"`, and emits
+ * an operator notification (stderr + audit row) naming the skill and how to
+ * approve it. A PATCH of an already-live skill edits it in place and updates the
+ * manifest; a "patch" of a skill that is not live is downgraded to a pending
+ * create, since auto-loading unreviewed instructions is the exact vector we are
+ * closing (W1/W3).
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {"create"|"patch"} [o.action="create"]
+ * @param {string} o.name           human skill name (also the manifest match key)
+ * @param {string} o.description     one-line description (frontmatter + manifest)
+ * @param {string} o.body            the skill body markdown (scanned before write)
+ * @param {string} [o.sourceSession] originating session id (provenance)
+ * @param {string} [o.id]            explicit id (required-ish for patch; else slug)
+ * @param {boolean} [o.trusted=false] system-internal author: a create lands LIVE
+ *   (skips quarantine). Set ONLY by trusted internal callers (curator umbrella
+ *   consolidation), NEVER by the agent-authored/reflect path (the W1 vector).
+ * @param {string} [o.nowIso]        injectable timestamp (tests)
+ * @returns {{ok:boolean, action:string, status:string, id:?string, path:?string, reason:string, secrets?:Array}}
+ */
+export function writeSkill(o = {}) {
+  const agentRoot = o.agentRoot;
+  const requested = o.action === "patch" ? "patch" : "create";
+  const name = String(o.name || "").trim();
+  const description = String(o.description || "").trim();
+  const body = String(o.body || "");
+  const nowIso = o.nowIso || new Date().toISOString();
+
+  if (!agentRoot) return { ok: false, action: requested, status: "rejected", id: null, path: null, reason: "no-agent-root" };
+  if (!name) return { ok: false, action: requested, status: "rejected", id: null, path: null, reason: "no-name" };
+
+  // 1. SECRET SCAN — before any byte is written. A hit aborts the skill.
+  const secrets = scanForSecrets(body);
+  if (secrets.length > 0) {
+    appendSkillAudit(agentRoot, {
+      action: "abort",
+      requested,
+      name,
+      reason: "secret-scan",
+      secrets: secrets.map((s) => s.label),
+      source_session: o.sourceSession || null,
+    });
+    return { ok: false, action: requested, status: "rejected", id: null, path: null, reason: "secret-scan", secrets };
+  }
+
+  // 2. Resolve the id and decide live-patch vs. quarantined-create. A patch only
+  //    stays live if it targets a skill an operator already approved; otherwise
+  //    it is a create and must be quarantined.
+  let id;
+  let action = requested;
+  if (requested === "patch") {
+    id = String(o.id || slugify(name)).trim() || slugify(name);
+    if (!isLiveSkill(agentRoot, id)) action = "create";
+  }
+  if (action === "create") {
+    id = dedupeId(agentRoot, slugify(o.id || name));
+  }
+
+  // create → pending quarantine; patch → live edit. A TRUSTED create (o.trusted
+  // === true) is a system-internal author (e.g. curator umbrella consolidation),
+  // NOT untrusted agent-authored output, so it lands live. `trusted` must never
+  // be wired to the reflect/agent-authored path — that is the W1 vector.
+  const live = action === "patch" || (action === "create" && o.trusted === true);
+  const status = live ? "approved" : "pending";
+
+  // 3. Render + write the .md atomically into the live OR pending dir.
+  const md = renderSkillMd({ id, name, description, body, sourceSession: o.sourceSession, createdAt: nowIso, status });
+  const absPath = join(live ? skillsDir(agentRoot) : pendingDir(agentRoot), `${id}.md`);
+  try {
+    writeAtomicFile(absPath, md);
+  } catch (e) {
+    appendSkillAudit(agentRoot, { action: "abort", requested, name, id, reason: "write-failed", error: e && e.message ? e.message : String(e) });
+    return { ok: false, action, status: "rejected", id, path: null, reason: "write-failed" };
+  }
+
+  // 4. Manifest: ONLY live (approved) skills are registered so Claude Code loads
+  //    them. A pending skill is deliberately absent from plugin.json.
+  if (live) {
+    try { upsertPluginEntry(agentRoot, { name: id, description, path: `skills/${id}.md` }); } catch { /* fail-open */ }
+  }
+
+  // 5. Update the usage sidecar with the lifecycle state.
+  let rec = null;
+  try { rec = upsertSidecar(agentRoot, id, { state: live ? "active" : "pending", now: nowIso }); } catch { /* fail-open */ }
+
+  // 6. Audit + (for a quarantined create) notify the operator.
+  appendSkillAudit(agentRoot, { action, status, name, id, description, source_session: o.sourceSession || null });
+  if (!live) notifyPendingSkill(agentRoot, { id, name, path: absPath });
+
+  return { ok: true, action, status, id, path: absPath, reason: "ok", record: rec };
+}
+
+/**
+ * Approve a quarantined (pending) skill: move it from `.pending/` into the live
+ * `skills/` dir, flip its frontmatter to `status: approved`, register it in
+ * plugin.json so Claude Code loads it, and mark the sidecar `active`. Audited.
+ * Fail-open on FS errors. This is the operator gate the autonomous loop cannot
+ * cross on its own.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot
+ * @param {string} o.id            the pending skill id
+ * @param {string} [o.approvedBy]  who approved (recorded in the audit row)
+ * @param {string} [o.nowIso]      injectable timestamp (tests)
+ * @returns {{ok:boolean, id:string, path:?string, reason:string}}
+ */
+export function approveSkill(o = {}) {
+  const agentRoot = o.agentRoot;
+  const id = String(o.id || "").trim();
+  const nowIso = o.nowIso || new Date().toISOString();
+  if (!agentRoot) return { ok: false, id, path: null, reason: "no-agent-root" };
+  if (!id) return { ok: false, id, path: null, reason: "no-id" };
+
+  const pendingPath = join(pendingDir(agentRoot), `${id}.md`);
+  if (!existsSync(pendingPath)) return { ok: false, id, path: null, reason: "not-pending" };
+
+  let md;
+  try { md = readFileSync(pendingPath, "utf8"); }
+  catch (e) {
+    appendSkillAudit(agentRoot, { action: "abort", requested: "approve", id, reason: "read-failed", error: e && e.message ? e.message : String(e) });
+    return { ok: false, id, path: null, reason: "read-failed" };
+  }
+
+  const description = (md.match(/^description:\s*(.*)$/m) || [, ""])[1].trim();
+  const livePath = join(skillsDir(agentRoot), `${id}.md`);
+  try {
+    writeAtomicFile(livePath, withStatus(md, "approved"));
+    // Drop the pending copy once the live copy is in place.
+    try { renameSync(pendingPath, `${pendingPath}.approved.${Date.now()}.bak`); } catch { /* best-effort */ }
+  } catch (e) {
+    appendSkillAudit(agentRoot, { action: "abort", requested: "approve", id, reason: "write-failed", error: e && e.message ? e.message : String(e) });
+    return { ok: false, id, path: null, reason: "write-failed" };
+  }
+
+  try { upsertPluginEntry(agentRoot, { name: id, description, path: `skills/${id}.md` }); } catch { /* fail-open */ }
+  try { upsertSidecar(agentRoot, id, { state: "active", now: nowIso }); } catch { /* fail-open */ }
+  appendSkillAudit(agentRoot, { action: "approve", id, approved_by: o.approvedBy || null });
+
+  return { ok: true, id, path: livePath, reason: "ok" };
+}
+
+/**
+ * Emit an operator notification for a quarantined skill: a stderr line plus a
+ * dedicated audit row. Never throws (runs inside a fail-open write path).
+ */
+function notifyPendingSkill(agentRoot, { id, name, path }) {
+  const approveHint = `maestro skill approve ${id}`;
+  try {
+    process.stderr.write(
+      `[maestro:learning] PENDING skill authored — not loaded until approved: "${name}" (id=${id}) at ${path}. Approve with: ${approveHint}\n`,
+    );
+  } catch { /* stderr unavailable; the audit row below is the durable record */ }
+  appendSkillAudit(agentRoot, { action: "pending_review", id, name, path, approve_hint: approveHint });
+}
+
+export default {
+  writeSkill,
+  approveSkill,
+  scanForSecrets,
+  slugify,
+  renderSkillMd,
+  skillsDir,
+  pendingDir,
+  readSidecar,
+  writeSidecar,
+  touchSkill,
+  appendSkillAudit,
+  SECRET_PATTERNS,
+};

package/lib/learning/skill-writer.test.mjs

@@ -0,0 +1,210 @@
+/**
+ * skill-writer.test.mjs — autonomous skill write-path tests.
+ * Run: node --test lib/learning/skill-writer.test.mjs
+ *
+ * Covers: flat-skill frontmatter, slug dedupe, secret-scan ABORT, plugin.json
+ * upsert, atomic write, audit rows, patch overwrite, sidecar lifecycle.
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, existsSync, readFileSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  writeSkill, approveSkill, scanForSecrets, slugify, renderSkillMd, readSidecar, touchSkill,
+} from "./skill-writer.mjs";
+
+function tmpRoot() {
+  return mkdtempSync(join(tmpdir(), "maestro-skillwriter-"));
+}
+function skillPath(root, id) {
+  return join(root, "plugins", "agent-skills", "skills", `${id}.md`);
+}
+function pendingPath(root, id) {
+  return join(root, "plugins", "agent-skills", ".pending", `${id}.md`);
+}
+function pluginExists(root) {
+  return existsSync(join(root, "plugins", "agent-skills", "plugin.json"));
+}
+function pluginJson(root) {
+  return JSON.parse(readFileSync(join(root, "plugins", "agent-skills", "plugin.json"), "utf8"));
+}
+function auditRows(root) {
+  const p = join(root, "logs", "audit", "skills.jsonl");
+  if (!existsSync(p)) return [];
+  return readFileSync(p, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+test("slugify: filesystem-safe, hyphenated, bounded", () => {
+  assert.equal(slugify("Reconcile the Billing Export!"), "reconcile-the-billing-export");
+  assert.equal(slugify("   "), "skill");
+  assert.equal(slugify("a/b\\c"), "a-b-c");
+});
+
+test("renderSkillMd: agent provenance frontmatter + body", () => {
+  const md = renderSkillMd({
+    id: "x", name: "Do X", description: "does x", body: "# Do X\nsteps", sourceSession: "sess-1", createdAt: "2026-06-09T00:00:00Z",
+  });
+  assert.match(md, /^---\n/);
+  assert.match(md, /name: Do X/);
+  assert.match(md, /description: does x/);
+  assert.match(md, /created_by: agent/);
+  assert.match(md, /source_session: sess-1/);
+  assert.match(md, /\n# Do X\nsteps\n$/);
+});
+
+test("writeSkill create: QUARANTINES to .pending — not live, not in plugin.json, sidecar pending, audit", () => {
+  const root = tmpRoot();
+  const res = writeSkill({
+    agentRoot: root, action: "create", name: "Reconcile Billing Export",
+    description: "Re-run the monthly billing reconciliation", body: "# Reconcile\n1. pull export\n2. diff", sourceSession: "sess-42",
+    nowIso: "2026-06-09T00:00:00Z",
+  });
+  assert.equal(res.ok, true);
+  assert.equal(res.status, "pending", "a create lands pending, not live");
+  assert.equal(res.id, "reconcile-billing-export");
+
+  // The file is in the quarantine dir, NOT the live dir Claude Code loads.
+  assert.ok(existsSync(pendingPath(root, res.id)), "skill .md in .pending");
+  assert.ok(!existsSync(skillPath(root, res.id)), "NOT in the live skills dir");
+  // No plugin.json at all → Claude Code never loads the pending skill.
+  assert.ok(!pluginExists(root), "pending skill is NOT registered in plugin.json");
+
+  const body = readFileSync(pendingPath(root, res.id), "utf8");
+  assert.match(body, /created_by: agent/);
+  assert.match(body, /status: pending/);
+  assert.match(body, /pull export/);
+
+  const sidecar = readSidecar(root);
+  assert.equal(sidecar[res.id].created_by, "agent");
+  assert.equal(sidecar[res.id].state, "pending");
+  assert.equal(sidecar[res.id].pinned, false);
+
+  // Audit records the create + an operator-notification row.
+  const audit = auditRows(root);
+  assert.ok(audit.some((r) => r.action === "create" && r.id === "reconcile-billing-export" && r.status === "pending"));
+  const notice = audit.find((r) => r.action === "pending_review" && r.id === "reconcile-billing-export");
+  assert.ok(notice, "operator pending_review row emitted");
+  assert.match(notice.approve_hint, /approve reconcile-billing-export/);
+});
+
+test("approveSkill: promotes a pending skill to live + plugin.json + sidecar active", () => {
+  const root = tmpRoot();
+  const res = writeSkill({ agentRoot: root, name: "Daily Recon", description: "the recon", body: "# Steps\n1. go" });
+  assert.equal(res.status, "pending");
+
+  const ap = approveSkill({ agentRoot: root, id: res.id, approvedBy: "layla", nowIso: "2026-06-10T00:00:00Z" });
+  assert.equal(ap.ok, true);
+  assert.equal(ap.id, res.id);
+
+  // Now live and registered; the raw pending .md is gone.
+  assert.ok(existsSync(skillPath(root, res.id)), "approved skill is live");
+  assert.ok(!existsSync(pendingPath(root, res.id)), "pending copy removed");
+  const live = readFileSync(skillPath(root, res.id), "utf8");
+  assert.match(live, /status: approved/);
+
+  const manifest = pluginJson(root);
+  assert.equal(manifest.skills.length, 1);
+  assert.deepEqual(manifest.skills[0], { name: res.id, description: "the recon", path: `skills/${res.id}.md` });
+
+  assert.equal(readSidecar(root)[res.id].state, "active");
+  assert.ok(auditRows(root).some((r) => r.action === "approve" && r.id === res.id && r.approved_by === "layla"));
+});
+
+test("approveSkill: unknown / not-pending id is a no-op failure", () => {
+  const root = tmpRoot();
+  const ap = approveSkill({ agentRoot: root, id: "never-authored" });
+  assert.equal(ap.ok, false);
+  assert.equal(ap.reason, "not-pending");
+});
+
+test("writeSkill create: slug dedupe across BOTH pending and live", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Daily Recon", description: "d", body: "v1" });
+  const b = writeSkill({ agentRoot: root, name: "Daily Recon", description: "d", body: "v2" });
+  assert.equal(a.id, "daily-recon");
+  assert.equal(b.id, "daily-recon-2", "second create dedupes the slug even in quarantine");
+  assert.ok(existsSync(pendingPath(root, "daily-recon")));
+  assert.ok(existsSync(pendingPath(root, "daily-recon-2")));
+  // Approving the first must still not collide with the pending second.
+  approveSkill({ agentRoot: root, id: "daily-recon" });
+  const c = writeSkill({ agentRoot: root, name: "Daily Recon", description: "d", body: "v3" });
+  assert.equal(c.id, "daily-recon-3", "dedupe checks the live dir too");
+});
+
+test("writeSkill patch: a LIVE (approved) skill is edited in place and stays live", () => {
+  const root = tmpRoot();
+  const created = writeSkill({ agentRoot: root, name: "Patchable", description: "first", body: "OLD BODY" });
+  approveSkill({ agentRoot: root, id: created.id }); // operator approves before any patch
+  const b = writeSkill({ agentRoot: root, action: "patch", id: created.id, name: "Patchable", description: "second", body: "NEW BODY" });
+  assert.equal(b.ok, true);
+  assert.equal(b.status, "approved", "patch of a live skill stays live");
+  assert.equal(b.id, created.id, "patch keeps the id");
+  const body = readFileSync(skillPath(root, created.id), "utf8");
+  assert.match(body, /NEW BODY/);
+  assert.doesNotMatch(body, /OLD BODY/, "old body overwritten");
+  // create-or-replace by name → still one entry, updated description.
+  const manifest = pluginJson(root);
+  assert.equal(manifest.skills.length, 1);
+  assert.equal(manifest.skills[0].description, "second");
+});
+
+test("writeSkill patch: a NON-live target is downgraded to a quarantined create", () => {
+  const root = tmpRoot();
+  // Patch a skill that was never approved (only pending) → must not go live.
+  const res = writeSkill({ agentRoot: root, action: "patch", id: "ghost", name: "Ghost", description: "d", body: "BODY" });
+  assert.equal(res.ok, true);
+  assert.equal(res.action, "create", "patch of a non-live skill becomes a create");
+  assert.equal(res.status, "pending");
+  assert.ok(existsSync(pendingPath(root, res.id)));
+  assert.ok(!pluginExists(root), "still not registered");
+});
+
+test("scanForSecrets: flags credential literals and sensitive assignments", () => {
+  assert.deepEqual(scanForSecrets("nothing to see here"), []);
+  assert.ok(scanForSecrets("export KEY=sk-ant-" + "A".repeat(20)).some((h) => h.label === "anthropic-key"));
+  assert.ok(scanForSecrets("token gh" + "p_" + "B".repeat(30)).some((h) => h.label === "github-pat"));
+  assert.ok(scanForSecrets("AKIA" + "Z".repeat(16)).some((h) => h.label === "aws-access-key-id"));
+  assert.ok(scanForSecrets("Authorization: Bearer " + "c".repeat(24)).some((h) => h.label === "bearer-token"));
+  assert.ok(scanForSecrets("password=hunter2longenough").some((h) => /assignment:password/.test(h.label)));
+});
+
+test("writeSkill: ABORTS on a secret in the body — no file, no manifest, audit abort row", () => {
+  const root = tmpRoot();
+  const res = writeSkill({
+    agentRoot: root, name: "Leaky Skill", description: "should not land",
+    body: "# Setup\nRun with API_KEY=sk-ant-" + "S".repeat(24) + " then proceed.",
+  });
+  assert.equal(res.ok, false);
+  assert.equal(res.reason, "secret-scan");
+  assert.ok(res.secrets.length >= 1);
+  assert.ok(!existsSync(skillPath(root, "leaky-skill")), "no skill file written");
+  assert.ok(!existsSync(join(root, "plugins", "agent-skills", "plugin.json")), "no manifest written");
+  const audit = auditRows(root);
+  assert.equal(audit.length, 1);
+  assert.equal(audit[0].action, "abort");
+  assert.equal(audit[0].reason, "secret-scan");
+});
+
+test("writeSkill: atomic — leaves no .tmp turds behind", () => {
+  const root = tmpRoot();
+  writeSkill({ agentRoot: root, name: "Clean Write", description: "d", body: "x" });
+  // A create quarantines, so the atomic write lands in .pending.
+  const dir = join(root, "plugins", "agent-skills", ".pending");
+  const names = existsSync(dir) ? readdirSync(dir) : [];
+  assert.ok(names.length >= 1);
+  assert.ok(names.every((n) => !n.endsWith(".tmp")), "no leftover tmp files");
+});
+
+test("touchSkill: bumps last_activity only for known ids", () => {
+  const root = tmpRoot();
+  const a = writeSkill({ agentRoot: root, name: "Touchable", description: "d", body: "x", nowIso: "2026-06-01T00:00:00Z" });
+  touchSkill(root, a.id, { nowIso: "2026-06-09T00:00:00Z" });
+  assert.equal(readSidecar(root)[a.id].last_activity, "2026-06-09T00:00:00Z");
+  // Unknown id is a no-op (no new record created).
+  touchSkill(root, "does-not-exist", { nowIso: "2026-06-09T00:00:00Z" });
+  assert.ok(!readSidecar(root)["does-not-exist"]);
+});