@rhize/skill-forge 0.6.1 → 0.7.0

package/LICENSE

@@ -18,6 +18,7 @@ Pro Modules
 - src/gate/mcpOverlap.ts
 - src/provenance.ts
 - src/queue.ts
+- src/evolve.ts
 
 ...and the portions of built artifacts (e.g. dist/cli.js in the published npm
 package) generated from these files. Each Pro Module carries a header

package/README.md

@@ -65,11 +65,12 @@ anything ending in `.git`), or a local filesystem path.
 ## Commands
 
 ```
-skill-forge init [options]             Detect installed agents and set gate targets / handoff agent
-skill-forge add <source> [options]     Quarantine-install a skill and run it through the gate
-skill-forge scan <source> [options]    Gate a skill without installing it (always cleans up)
-skill-forge list                       List skills currently held in quarantine
-skill-forge status                     Show configuration and quarantine summary
+skill-forge init [options]                     Detect installed agents and set gate targets / handoff agent
+skill-forge add <source> [options]             Quarantine-install a skill and run it through the gate
+skill-forge scan <source> [options]            Gate a skill without installing it (always cleans up)
+skill-forge evolve <skill-dir> [options]       Self-evolve an installed skill via SkillOpt-Sleep, re-gate, decide (Pro)
+skill-forge list                               List skills currently held in quarantine
+skill-forge status                             Show configuration and quarantine summary
 ```
 
 ### `init`
@@ -132,6 +133,69 @@ anything — the quarantine sandbox is always cleaned up afterward, on success o
 nonzero when the safety verdict is `block`. `--json` prints the same gate-result payload shape as
 `add`'s.
 
+### `evolve` (v0.7)
+
+```bash
+skill-forge evolve .claude/skills/my-skill
+skill-forge evolve .claude/skills/my-skill --yes
+skill-forge evolve .claude/skills/my-skill --dry-run
+skill-forge evolve .claude/skills/my-skill --backend claude --yes
+```
+
+Pro (free during the 0.x beta). Orchestrates [microsoft/SkillOpt](https://github.com/microsoft/SkillOpt)'s
+`skillopt-sleep` CLI (`pip install skillopt`) to propose a self-evolution of an already-installed
+skill — harvest recent sessions, generate a candidate replacement `SKILL.md`/`CLAUDE.md`, and stage
+it — then runs the **staged proposal**, never the live skill, back through skill-forge's own static
+safety ruleset before you decide anything. SkillOpt-Sleep's own validation gate is score-only; it
+never content-vets the generated markdown. This closes that gap.
+
+| Option | Effect |
+|---|---|
+| `--project <dir>` | Project dir passed to SkillOpt-Sleep as `--project`. Defaults to cwd. |
+| `--dry-run` | Uses SkillOpt-Sleep's `dry-run` subcommand — report only, nothing staged. |
+| `--backend <name>` | SkillOpt-Sleep backend. Defaults to `mock` (offline, deterministic, no network). |
+| `--lookback-hours <n>` | Hours of session history for SkillOpt-Sleep to harvest. |
+| `-y, --yes` | Skips interactive prompts (the disclosure confirm below, and the promote/hold/reject prompt) and honors the re-gate verdict automatically. |
+| `--json` | Prints the re-gate result as JSON instead of the terminal report. Implies non-interactive, same as `add`'s `--json`. |
+| `--force` | Allows re-adopting a staging dir whose proposed content already matches the live skill (see the double-adopt guard below). |
+
+**Requires `skillopt-sleep` on PATH** — skill-forge never installs it for you. If it's missing,
+`evolve` prints `pip install skillopt` + a docs pointer and exits, rather than attempting an
+auto-install (the same "detect, don't install" discipline the rest of the gate follows).
+
+**Data boundary.** The default `mock` backend is fully offline — harvesting and proposal
+generation both run locally, no session data leaves the machine. Any other backend (`claude`,
+`codex`, `azure_openai`, ...) sends truncated excerpts from harvested sessions and derived tasks to
+the provider you selected; per SkillOpt-Sleep's own docs this is not currently guaranteed to be
+secret-free. `evolve` prints that disclosure and requires either `--yes` or an interactive `y/N`
+confirmation before a non-`mock` run proceeds — `--json` is non-interactive, so a non-`mock` run
+under `--json` without `--yes` is refused rather than silently sending data off-machine.
+
+**Re-gate.** SkillOpt-Sleep only ever *stages* a proposal (`<project>/.skillopt-sleep/staging/<timestamp>/`
+— full replacement files, never auto-adopted). `evolve` copies just `proposed_SKILL.md` (and
+`proposed_CLAUDE.md`, if present) into a fresh temporary directory and runs skill-forge's own
+static safety ruleset over that copy — the same one `add`/`scan` use, at your configured
+`strictness`. `report.json`/`diagnostics.json` (SkillOpt-Sleep's own redacted holdout evidence) are
+never scanned. The result renders through the same terminal report / `--json` shape as `add`/`scan`.
+
+**Decision.** Same promote/hold/reject semantics as `add`: `--yes`/`--json` honor the re-gate
+verdict (a `block` is rejected); otherwise you're prompted.
+
+- **promote** — runs SkillOpt-Sleep's own `adopt --staging <dir>` (which backs up the live file(s)
+  before copying the proposal over them), then records a provenance entry to the target skill's
+  `SOURCES.md` and a pending-ingestion queue entry (`origin: "evolve"`, see
+  [docs/queue-schema.md](docs/queue-schema.md)) so a later ingest pass reviews the evolution rather
+  than an external source.
+- **hold** — leaves the staging dir exactly as SkillOpt-Sleep produced it (its own `status` command
+  still lists it); `report.md` has the full evidence.
+- **reject** — deletes the staging dir.
+
+**Double-adopt guard.** SkillOpt-Sleep's `adopt` has no confirmation of its own, and adopting the
+same staging dir twice overwrites *its* backup — the pre-evolution original would be lost. Before
+adopting, `evolve` refuses (unless `--force`) when the staged proposal is already byte-identical to
+the live skill it would replace, since that's the signature of a staging dir that was already
+adopted once.
+
 ### `list` / `status`
 
 `list` shows what's currently held in quarantine (installed via `add`, answered "hold", not yet
@@ -237,6 +301,7 @@ JSON. Detection/overlap is agent-format-agnostic; writing is JSON-only.
 | Overlap analysis against your configured skill set | | ✓ |
 | Provenance ledger (`SOURCES.md` audit trail) | | ✓ |
 | Pending-ingestion queue + `--ingest` handoff | | ✓ |
+| `evolve` — SkillOpt-Sleep self-evolution, re-gating, provenance, queueing (v0.7) | | ✓ |
 | Set-level organizer (capability registry, redundancy, dependency graph) | | ✓ |
 
 Free is the complete safety gate on its own — quarantine, profile, safety scan, and an explicit

package/dist/cli.js

@@ -5,7 +5,6 @@ import { Command } from "commander";
 import { createRequire } from "module";
 
 // src/commands/add.ts
-import { createInterface as createInterface2 } from "readline/promises";
 import { join as join15 } from "path";
 
 // src/config.ts
@@ -519,6 +518,9 @@ function verdictFor(findings, strictness) {
   if (findings.length > 0) return "warn";
   return "pass";
 }
+function formatSafetyFinding(f) {
+  return `${f.severity} [${f.rule}] ${f.file}: ${f.detail}`;
+}
 
 // src/gate/mcpCapabilities.ts
 var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
@@ -725,6 +727,22 @@ function profileSkill(inputPath) {
   }
   return profileSkillDir(p);
 }
+function asSkillProfile(profile, context) {
+  if (profile.kind !== "skill") {
+    throw new Error(`expected a skill candidate ${context}, found a ${profile.kind}`);
+  }
+  return profile;
+}
+function asProfile(candidatePath, artifact) {
+  const profile = profileSkill(candidatePath);
+  if (artifact === "mcp") {
+    if (profile.kind !== "mcp") {
+      throw new Error(`expected an MCP candidate at ${candidatePath} (--artifact mcp), found a ${profile.kind}`);
+    }
+    return profile;
+  }
+  return asSkillProfile(profile, `at ${candidatePath}`);
+}
 function classifyInput(p) {
   if (existsSync8(join8(p, ".claude-plugin", "plugin.json"))) return "plugin";
   if (detectArtifactType(p) === "mcp") return "mcp";
@@ -1201,14 +1219,14 @@ your you it its as at by from into via per also any all not no than then so if u
 skill skills user claude code based comprehensive enhanced practical including include includes
 `.split(/\s+/).filter(Boolean)
 );
-function splitLimited(text, sep, maxSplit) {
+function splitLimited(text, sep2, maxSplit) {
   const parts = [];
   let rest = text;
   for (let i = 0; i < maxSplit; i++) {
-    const idx = rest.indexOf(sep);
+    const idx = rest.indexOf(sep2);
     if (idx === -1) break;
     parts.push(rest.slice(0, idx));
-    rest = rest.slice(idx + sep.length);
+    rest = rest.slice(idx + sep2.length);
   }
   parts.push(rest);
   return parts;
@@ -1743,6 +1761,14 @@ function proFeatureStatus(feature, betaFree = BETA_FREE) {
 }
 
 // src/report/render.ts
+var SAFETY_VERDICT_MAP = {
+  pass: "ALLOW",
+  warn: "CAUTION",
+  block: "BLOCK"
+};
+function mapSafetyFindings(findings) {
+  return findings.map((f) => ({ severity: f.severity, rule: f.rule, message: `${f.file}: ${f.detail}` }));
+}
 var BORDER = "\u2501".repeat(55);
 var LABEL_WIDTH = 20;
 function padLabel(text) {
@@ -1817,29 +1843,14 @@ function renderReport(result) {
 function renderJson(result) {
   return JSON.stringify(result, null, 2);
 }
-
-// src/commands/gatePipeline.ts
-var SAFETY_VERDICT_MAP = {
-  pass: "ALLOW",
-  warn: "CAUTION",
-  block: "BLOCK"
-};
 function printGateOutput(gateResult, json) {
   if (!json) {
     for (const notice of gateResult.notices ?? []) console.log(`[skill-forge] ${notice}`);
   }
   console.log(json ? renderJson(gateResult) : renderReport(gateResult));
 }
-function asProfile(candidatePath, artifact) {
-  const profile = profileSkill(candidatePath);
-  const expectedKind = artifact === "mcp" ? "mcp" : "skill";
-  if (profile.kind !== expectedKind) {
-    throw new Error(
-      artifact === "mcp" ? `expected an MCP candidate at ${candidatePath} (--artifact mcp), found a ${profile.kind}` : `expected a skill candidate at ${candidatePath}, found a ${profile.kind}`
-    );
-  }
-  return profile;
-}
+
+// src/commands/gatePipeline.ts
 function tryOverlap(candidatePath, skillsRoot) {
   try {
     return scanOverlap(candidatePath, skillsRoot);
@@ -1891,11 +1902,7 @@ async function runGate(candidatePath, skillsRoot, {
     notices: proStatus.notice ? [proStatus.notice] : void 0,
     safety: {
       verdict: SAFETY_VERDICT_MAP[safety.verdict],
-      findings: safety.findings.map((f) => ({
-        severity: f.severity,
-        rule: f.rule,
-        message: `${f.file}: ${f.detail}`
-      }))
+      findings: mapSafetyFindings(safety.findings)
     }
   };
   return { safety, gateResult, proEnabled: proStatus.enabled };
@@ -2429,13 +2436,38 @@ async function maybeOfferInit(options = {}) {
   }
 }
 
-// src/commands/add.ts
-var PRO_FEATURE_LABEL = "overlap analysis, the provenance ledger, and the pending-ingestion queue";
-var MCP_PRO_FEATURE_LABEL = "overlap analysis and the pending-ingestion queue";
+// src/decision.ts
+import { createInterface as createInterface2 } from "readline/promises";
 function logOutcome(message, json) {
   if (json) console.error(message);
   else console.log(message);
 }
+function yesDecision(verdict) {
+  return verdict === "block" ? "reject" : "promote";
+}
+async function promptDecision(verdict, subject) {
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  const defaultChoice = verdict === "block" ? "reject" : verdict === "warn" ? "hold" : "promote";
+  const prompt = `Promote, hold, or reject ${subject}? [promote/hold/reject] (default: ${defaultChoice}) `;
+  try {
+    process.stdout.write(prompt);
+    for await (const raw of rl) {
+      const answer = raw.trim().toLowerCase() || defaultChoice;
+      if (answer === "p" || answer === "promote") return "promote";
+      if (answer === "h" || answer === "hold") return "hold";
+      if (answer === "r" || answer === "reject") return "reject";
+      process.stdout.write(`Please answer promote, hold, or reject (or p/h/r).
+${prompt}`);
+    }
+    return defaultChoice;
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/add.ts
+var PRO_FEATURE_LABEL = "overlap analysis, the provenance ledger, and the pending-ingestion queue";
+var MCP_PRO_FEATURE_LABEL = "overlap analysis and the pending-ingestion queue";
 async function add(source, options = {}) {
   await maybeOfferInit({ json: options.json, yes: options.yes });
   const config = loadConfig();
@@ -2472,7 +2504,7 @@ async function add(source, options = {}) {
     throw new Error(`expected a skill candidate, found a ${profile.kind}`);
   }
   printGateOutput(gateResult, options.json);
-  const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict);
+  const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict, "this skill");
   let installedPath = null;
   if (decision === "promote") {
     const result = promote(entry, targetRoot);
@@ -2512,7 +2544,7 @@ async function add(source, options = {}) {
       gate: {
         license: profile.license ?? null,
         safetyVerdict: safety.verdict,
-        safetyFindings: safety.findings.map((f) => `${f.severity} [${f.rule}] ${f.file}: ${f.detail}`),
+        safetyFindings: safety.findings.map(formatSafetyFinding),
         overlapTop: overlap ? overlap.ranking.slice(0, 3).map((r) => ({ skill: r.skill, score: r.score })) : [],
         suggestedVerb: overlap ? suggestVerbCode(overlap.nearestScore) : null
       },
@@ -2544,7 +2576,7 @@ async function addMcp(source, config, options) {
     );
   }
   printGateOutput(gateResult, options.json);
-  const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict);
+  const decision = options.yes || options.json ? yesDecision(safety.verdict) : await promptDecision(safety.verdict, "this skill");
   let installedPath = null;
   if (decision === "promote") {
     const detail = resolveMcpCandidateDetail(profile);
@@ -2585,7 +2617,7 @@ async function addMcp(source, config, options) {
       gate: {
         license: null,
         safetyVerdict: safety.verdict,
-        safetyFindings: safety.findings.map((f) => `${f.severity} [${f.rule}] ${f.file}: ${f.detail}`),
+        safetyFindings: safety.findings.map(formatSafetyFinding),
         overlapTop: overlap ? overlap.ranking.slice(0, 3).map((r) => ({ skill: r.skill, score: r.score })) : [],
         suggestedVerb: overlap ? suggestVerbCode(overlap.nearestScore) : null
       },
@@ -2598,28 +2630,6 @@ async function addMcp(source, config, options) {
     }
   }
 }
-function yesDecision(verdict) {
-  return verdict === "block" ? "reject" : "promote";
-}
-async function promptDecision(verdict) {
-  const rl = createInterface2({ input: process.stdin, output: process.stdout });
-  const defaultChoice = verdict === "block" ? "reject" : verdict === "warn" ? "hold" : "promote";
-  const prompt = `Promote, hold, or reject this skill? [promote/hold/reject] (default: ${defaultChoice}) `;
-  try {
-    process.stdout.write(prompt);
-    for await (const raw of rl) {
-      const answer = raw.trim().toLowerCase() || defaultChoice;
-      if (answer === "p" || answer === "promote") return "promote";
-      if (answer === "h" || answer === "hold") return "hold";
-      if (answer === "r" || answer === "reject") return "reject";
-      process.stdout.write(`Please answer promote, hold, or reject (or p/h/r).
-${prompt}`);
-    }
-    return defaultChoice;
-  } finally {
-    rl.close();
-  }
-}
 
 // src/commands/scan.ts
 async function scan(source, options = {}) {
@@ -2711,6 +2721,319 @@ async function status() {
   console.log(`  held in quarantine: ${heldCount}`);
 }
 
+// src/evolve.ts
+import { createInterface as createInterface3 } from "readline/promises";
+import { createHash } from "crypto";
+import { cpSync as cpSync3, existsSync as existsSync14, lstatSync, mkdtempSync as mkdtempSync2, readFileSync as readFileSync10, rmSync as rmSync3 } from "fs";
+import { tmpdir as tmpdir2 } from "os";
+import { basename as basename6, dirname as dirname5, join as join17, resolve as resolvePath2, sep } from "path";
+var SKILLOPT_BIN = "skillopt-sleep";
+var PRO_FEATURE_LABEL2 = "self-evolution via SkillOpt-Sleep (evolve) \u2014 re-gating, provenance, and the pending-ingestion queue";
+async function evolve(targetSkillDir, options = {}, deps = {}) {
+  const exec = deps.exec ?? defaultExec;
+  const json = options.json;
+  const resolvedTargetDir = resolvePath2(targetSkillDir);
+  const skillMdPath = join17(resolvedTargetDir, "SKILL.md");
+  if (!existsSync14(skillMdPath)) {
+    throw new UserError(`no SKILL.md found at ${skillMdPath} \u2014 evolve requires an existing, installed skill directory`);
+  }
+  const proStatus = proFeatureStatus(PRO_FEATURE_LABEL2);
+  if (!proStatus.enabled) {
+    throw new UserError(proStatus.notice ?? "evolve is a Pro feature \u2014 set SKILL_FORGE_LICENSE or config.licenseKey to a valid license to unlock.");
+  }
+  const notices = proStatus.notice ? [proStatus.notice] : [];
+  const backend = options.backend ?? "mock";
+  if (backend !== "mock") {
+    const disclosure = `data boundary: this run uses the "${backend}" backend. Per SkillOpt-Sleep's own docs, harvesting itself is local and read-only, but a real backend sends truncated excerpts from harvested sessions and derived tasks to the provider you selected \u2014 this is not currently guaranteed to be secret-free.`;
+    if (options.yes) {
+      notices.push(`${disclosure} Proceeding (--yes).`);
+    } else if (json) {
+      throw new UserError(`${disclosure} Pass --yes to proceed \u2014 --json is non-interactive and cannot prompt for confirmation.`);
+    } else {
+      console.log(`[skill-forge] ${disclosure}`);
+      const confirmFn = deps.confirm ?? defaultConfirm;
+      const confirmed = await confirmFn("Proceed and send session data to this backend? [y/N] ");
+      if (!confirmed) {
+        throw new UserError("evolve cancelled \u2014 data-boundary disclosure was not accepted.");
+      }
+      notices.push(`${disclosure} Confirmed interactively.`);
+    }
+  } else {
+    notices.push('using the offline "mock" backend \u2014 deterministic, no network calls, no session data leaves this machine.');
+  }
+  const project = resolvePath2(options.project ?? process.cwd());
+  const present = await detectSkillopt(exec, project);
+  if (!present) {
+    throw new UserError(
+      "`skillopt-sleep` not found on PATH. Install it with `pip install skillopt` (https://github.com/microsoft/SkillOpt) and re-run `skill-forge evolve`."
+    );
+  }
+  const subcommand = options.dryRun ? "dry-run" : "run";
+  const runArgs = [subcommand, "--project", project, "--target-skill-path", skillMdPath, "--json", "--backend", backend];
+  if (options.lookbackHours !== void 0) {
+    runArgs.push("--lookback-hours", String(options.lookbackHours));
+  }
+  const runResult = await exec(SKILLOPT_BIN, runArgs, { cwd: project });
+  if (runResult.code !== 0) {
+    throw new UserError(`skillopt-sleep ${subcommand} failed (exit ${runResult.code}): ${tail(runResult.stderr || runResult.stdout)}`);
+  }
+  let rawOutput;
+  try {
+    rawOutput = JSON.parse(runResult.stdout);
+  } catch (err) {
+    throw new UserError(`could not parse skillopt-sleep JSON output: ${err.message}`);
+  }
+  const parsed = validateRunOutput(rawOutput);
+  if (!parsed.accepted || !parsed.staging_dir) {
+    if (json) {
+      console.log(JSON.stringify({ ok: true, accepted: parsed.accepted, stagingDir: parsed.staging_dir }, null, 2));
+    } else {
+      console.log("[skill-forge] skillopt-sleep produced no accepted proposal \u2014 nothing to re-gate or adopt.");
+    }
+    return;
+  }
+  const stagingRoot = join17(project, ".skillopt-sleep", "staging");
+  const stagingDir = resolvePath2(parsed.staging_dir);
+  if (stagingDir !== stagingRoot && !stagingDir.startsWith(stagingRoot + sep)) {
+    throw new UserError(
+      `skillopt-sleep reported a staging_dir outside the expected sandbox (${stagingRoot}): ${stagingDir} \u2014 refusing to use it`
+    );
+  }
+  const proposedSkillMd = join17(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join17(stagingDir, "proposed_CLAUDE.md");
+  const reportMdPath = join17(stagingDir, "report.md");
+  if (!existsSync14(proposedSkillMd)) {
+    throw new UserError(`skillopt-sleep reported an accepted proposal but ${proposedSkillMd} is missing`);
+  }
+  if (existsSync14(reportMdPath)) {
+    notices.push(`SkillOpt-Sleep's full report: ${reportMdPath}`);
+  }
+  assertNotSymlink(proposedSkillMd, "proposed_SKILL.md");
+  assertNotSymlink(proposedClaudeMd, "proposed_CLAUDE.md");
+  const scannedSkillHash = sha256File(proposedSkillMd);
+  const scannedClaudeHash = sha256File(proposedClaudeMd);
+  const tempDir = mkdtempSync2(join17(tmpdir2(), "skill-forge-evolve-"));
+  let profile;
+  let safety;
+  try {
+    cpSync3(proposedSkillMd, join17(tempDir, "SKILL.md"));
+    if (existsSync14(proposedClaudeMd)) {
+      cpSync3(proposedClaudeMd, join17(tempDir, "CLAUDE.md"));
+    }
+    profile = asSkillProfile(profileSkill(tempDir), "for the evolved proposal");
+    const strictness = loadConfig().strictness;
+    safety = await scanSafety(tempDir, strictness);
+  } finally {
+    try {
+      rmSync3(tempDir, { recursive: true, force: true });
+    } catch (err) {
+      console.error(`[skill-forge] failed to clean up temp re-gate dir ${tempDir}: ${err.message}`);
+    }
+  }
+  const safetyVerdict = safety.verdict;
+  const gateResult = {
+    profile,
+    safety: {
+      verdict: SAFETY_VERDICT_MAP[safetyVerdict],
+      findings: mapSafetyFindings(safety.findings)
+    },
+    notices
+  };
+  printGateOutput(gateResult, json);
+  if (options.dryRun) {
+    logOutcome("[skill-forge] --dry-run: report only, nothing staged or adopted.", json);
+    return;
+  }
+  const decision = options.yes || json ? yesDecision(safetyVerdict) : await promptDecision(safetyVerdict, "this evolution proposal");
+  if (decision === "promote") {
+    const manifest = readManifest(stagingDir);
+    if (isAlreadyAdopted(stagingDir, manifest) && !options.force) {
+      throw new UserError(
+        `staging dir ${stagingDir} looks already adopted \u2014 its proposed content is byte-identical to the live skill (and memory, if present). Pass --force to re-adopt anyway.`
+      );
+    }
+    if (sha256File(proposedSkillMd) !== scannedSkillHash || sha256File(proposedClaudeMd) !== scannedClaudeHash) {
+      throw new UserError(`proposal changed after it was re-gated (staging dir: ${stagingDir}) \u2014 refusing to adopt`);
+    }
+    const adoptResult = await exec(SKILLOPT_BIN, ["adopt", "--staging", stagingDir, "--project", project], { cwd: project });
+    if (adoptResult.code !== 0) {
+      throw new UserError(`skillopt-sleep adopt failed (exit ${adoptResult.code}): ${tail(adoptResult.stderr || adoptResult.stdout)}`);
+    }
+    logOutcome(`[skill-forge] adopted -> ${resolvedTargetDir}`, json);
+    const skillsRootForProvenance = dirname5(resolvedTargetDir);
+    let ledgerPath;
+    try {
+      ledgerPath = appendProvenance(
+        {
+          name: profile.name ?? basename6(resolvedTargetDir),
+          source: resolvedTargetDir,
+          version: profile.version,
+          license: profile.license,
+          verb: "DEFER",
+          target: resolvedTargetDir,
+          took: `self-evolved via SkillOpt-Sleep (staging: ${stagingDir})`,
+          notes: `self-evolved via SkillOpt-Sleep; re-gated (verdict: ${safetyVerdict})`
+        },
+        skillsRootForProvenance
+      );
+    } catch (err) {
+      throw new UserError(
+        `adopt succeeded and the live skill at ${resolvedTargetDir} has already changed, but recording the provenance entry failed: ${err.message}`
+      );
+    }
+    logOutcome(`[skill-forge] provenance recorded -> ${ledgerPath}`, json);
+    try {
+      appendQueueEntry({
+        source: resolvedTargetDir,
+        sourceType: "local",
+        installedPath: resolvedTargetDir,
+        quarantinePath: stagingDir,
+        gate: {
+          license: profile.license ?? null,
+          safetyVerdict,
+          safetyFindings: safety.findings.map(formatSafetyFinding),
+          overlapTop: [],
+          suggestedVerb: null
+        },
+        status: "pending",
+        artifactType: "skill",
+        origin: "evolve"
+      });
+    } catch (err) {
+      throw new UserError(
+        `adopt succeeded and the live skill at ${resolvedTargetDir} has already changed (provenance was recorded), but appending the pending-ingestion queue entry failed: ${err.message}`
+      );
+    }
+    logOutcome("[skill-forge] queued for ingestion review", json);
+  } else if (decision === "reject") {
+    try {
+      rmSync3(stagingDir, { recursive: true, force: true });
+    } catch (err) {
+      throw new UserError(
+        `rejected the proposal, but removing the staging dir ${stagingDir} failed: ${err.message} \u2014 remove it manually.`
+      );
+    }
+    logOutcome("[skill-forge] rejected \u2014 staging dir removed", json);
+    if (safetyVerdict === "block") process.exitCode = 1;
+  } else {
+    logOutcome(`[skill-forge] held \u2014 staging dir left in place -> ${stagingDir}`, json);
+    if (existsSync14(reportMdPath)) {
+      logOutcome(`[skill-forge] see ${reportMdPath} for the full evidence report`, json);
+    }
+  }
+}
+async function defaultConfirm(question) {
+  const rl = createInterface3({ input: process.stdin, output: process.stdout });
+  try {
+    process.stdout.write(question);
+    for await (const raw of rl) {
+      return /^y(es)?$/i.test(raw.trim());
+    }
+    return false;
+  } finally {
+    rl.close();
+  }
+}
+async function detectSkillopt(exec, cwd) {
+  try {
+    const result = await exec(SKILLOPT_BIN, ["--help"], { cwd });
+    return result.code === 0;
+  } catch {
+    return false;
+  }
+}
+function tail(text, maxLines = 20) {
+  return text.trim().split("\n").slice(-maxLines).join("\n");
+}
+function validateRunOutput(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new UserError(`skillopt-sleep produced unexpected JSON output (expected an object): ${JSON.stringify(raw)}`);
+  }
+  const obj = raw;
+  const stagingDirRaw = obj.staging_dir;
+  if (stagingDirRaw !== null && stagingDirRaw !== void 0 && typeof stagingDirRaw !== "string") {
+    throw new UserError(
+      `skillopt-sleep produced an unexpected "staging_dir" (expected a string or null): ${JSON.stringify(stagingDirRaw)}`
+    );
+  }
+  return { accepted: Boolean(obj.accepted), staging_dir: stagingDirRaw ?? null };
+}
+function readManifest(stagingDir) {
+  const manifestPath = join17(stagingDir, "manifest.json");
+  let raw;
+  try {
+    raw = readFileSync10(manifestPath, "utf-8");
+  } catch (err) {
+    throw new UserError(`could not read staging manifest ${manifestPath}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new UserError(`could not parse staging manifest ${manifestPath}: ${err.message}`);
+  }
+  return validateManifest(parsed, manifestPath);
+}
+function validateManifest(raw, manifestPath) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new UserError(`staging manifest ${manifestPath} has an unexpected shape (expected an object)`);
+  }
+  const obj = raw;
+  if (typeof obj.live_skill_path !== "string") {
+    throw new UserError(`staging manifest ${manifestPath} is missing a valid "live_skill_path" string`);
+  }
+  if (obj.live_memory_path !== void 0 && obj.live_memory_path !== null && typeof obj.live_memory_path !== "string") {
+    throw new UserError(`staging manifest ${manifestPath} has an unexpected "live_memory_path" (expected a string or null)`);
+  }
+  if (typeof obj.has_skill !== "boolean" || typeof obj.has_memory !== "boolean") {
+    throw new UserError(`staging manifest ${manifestPath} is missing valid "has_skill"/"has_memory" booleans`);
+  }
+  return {
+    live_skill_path: obj.live_skill_path,
+    live_memory_path: obj.live_memory_path ?? null,
+    has_skill: obj.has_skill,
+    has_memory: obj.has_memory
+  };
+}
+function filesIdentical(a, b) {
+  if (!existsSync14(a) || !existsSync14(b)) return false;
+  return readFileSync10(a).equals(readFileSync10(b));
+}
+function isAlreadyAdopted(stagingDir, manifest) {
+  const proposedSkillMd = join17(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join17(stagingDir, "proposed_CLAUDE.md");
+  let sawComparison = false;
+  if (existsSync14(proposedSkillMd)) {
+    sawComparison = true;
+    if (!filesIdentical(proposedSkillMd, manifest.live_skill_path)) return false;
+  }
+  if (existsSync14(proposedClaudeMd) && manifest.live_memory_path) {
+    sawComparison = true;
+    if (!filesIdentical(proposedClaudeMd, manifest.live_memory_path)) return false;
+  }
+  return sawComparison;
+}
+function assertNotSymlink(path, label) {
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch {
+    return;
+  }
+  if (stat.isSymbolicLink()) {
+    throw new UserError(`refusing to re-gate ${label}: ${path} is a symlink (a staged proposal must be a plain file)`);
+  }
+}
+function sha256File(path) {
+  if (!existsSync14(path)) return null;
+  return createHash("sha256").update(readFileSync10(path)).digest("hex");
+}
+
+// src/commands/evolve.ts
+async function evolveCommand(targetSkillDir, options = {}) {
+  await evolve(targetSkillDir, options);
+}
+
 // src/cli.ts
 var require2 = createRequire(import.meta.url);
 var pkg = require2("../package.json");
@@ -2720,6 +3043,13 @@ function parseArtifact(value) {
   }
   return value;
 }
+function parseLookbackHours(value) {
+  const n = Number(value);
+  if (value.trim() === "" || !Number.isFinite(n) || n < 0) {
+    throw new UserError(`--lookback-hours must be a non-negative number (got "${value}")`);
+  }
+  return n;
+}
 var program = new Command();
 program.name("skill-forge").description("The supply-chain gate for agent skills").version(pkg.version);
 program.command("add <source>").description("Quarantine-install a skill and run it through the safety gate").option("-y, --yes", "skip the interactive prompt; honor the gate verdict automatically").option("-t, --target <dir>", "skills root to promote into (defaults to config defaultTarget, then skillsRoots[0])").option("--json", "print the gate result as JSON instead of the terminal report").option("--ingest", "after a successful promote, hand off the bundled ingest prompt to a coding agent").option("--artifact <type>", 'gate as a "skill" or an "mcp" server (default: skill)', parseArtifact).option(
@@ -2729,6 +3059,7 @@ program.command("add <source>").description("Quarantine-install a skill and run
 program.command("scan <source>").description("Run the safety gate against a skill without installing it").option("--json", "print the gate result as JSON instead of the terminal report").option("--artifact <type>", 'gate as a "skill" or an "mcp" server (default: skill)', parseArtifact).action(scan);
 program.command("list").description("List skills currently in quarantine").action(list);
 program.command("status").description("Show skill-forge configuration and quarantine status").action(status);
+program.command("evolve <target-skill-dir>").description("Self-evolve a skill via SkillOpt-Sleep, re-gate the proposal, then promote/hold/reject (Pro)").option("--project <dir>", "project dir passed to SkillOpt-Sleep as --project (defaults to cwd)").option("--dry-run", "SkillOpt-Sleep dry-run: report only, nothing staged").option("--backend <name>", "SkillOpt-Sleep backend (default: mock, offline \u2014 a real backend requires --yes or interactive confirmation)").option("--lookback-hours <n>", "hours of session history for SkillOpt-Sleep to harvest", parseLookbackHours).option("-y, --yes", "skip interactive prompts; honor the re-gate verdict automatically").option("--json", "print the re-gate result as JSON instead of the terminal report").option("--force", "allow re-adopting a staging dir whose proposed content already matches the live skill").action(evolveCommand);
 program.command("init").description("Detect installed agents and set gate targets, default promotion target, and handoff agent").option("--defaults", "non-interactive: use all detected agents as gate targets, the first as the default target").option("--list", "print detected agent skill roots and exit \u2014 no writes").action(init);
 try {
   await program.parseAsync();