@rhize/skill-forge 0.6.1 → 0.7.1

package/dist/cli.js

@@ -5,8 +5,7 @@ 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";
+import { join as join16 } from "path";
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -296,16 +295,132 @@ function moveDir(src, dest) {
 }
 
 // src/install/promoteMcp.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 import { dirname } from "path";
+
+// src/gate/scanShared.ts
+import { readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { extname, join as join5 } from "path";
+var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv"]);
+var BINARY_EXT = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".ico",
+  ".pdf",
+  ".zip",
+  ".tar",
+  ".gz",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".mp4",
+  ".mp3",
+  ".wasm",
+  ".bin",
+  ".exe"
+]);
+var MAX_FILE_BYTES = 2 * 1024 * 1024;
+function* walk(dir) {
+  let entries;
+  try {
+    entries = readdirSync2(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join5(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS2.has(entry.name)) continue;
+      yield* walk(full);
+    } else if (entry.isFile()) {
+      yield full;
+    }
+  }
+}
+function readTextFile(file) {
+  if (BINARY_EXT.has(extname(file).toLowerCase())) return void 0;
+  try {
+    if (statSync2(file).size > MAX_FILE_BYTES) return void 0;
+    const content = readFileSync2(file, "utf-8");
+    if (content.slice(0, 512).includes("\0")) return void 0;
+    return content;
+  } catch {
+    return void 0;
+  }
+}
+var BLOCK_SEVERITIES_BY_STRICTNESS = {
+  "block-high": /* @__PURE__ */ new Set(["HIGH", "CRITICAL"]),
+  "block-medium": /* @__PURE__ */ new Set(["MEDIUM", "HIGH", "CRITICAL"]),
+  "warn-only": /* @__PURE__ */ new Set()
+};
+function verdictFor(findings, strictness) {
+  const blockSeverities = BLOCK_SEVERITIES_BY_STRICTNESS[strictness];
+  if (findings.some((f) => blockSeverities.has(f.severity))) return "block";
+  if (findings.length > 0) return "warn";
+  return "pass";
+}
+function formatSafetyFinding(f) {
+  return `${f.severity} [${f.rule}] ${f.file}: ${f.detail}`;
+}
+function isPinnedPackageSpec(spec) {
+  const withoutScope = spec.startsWith("@") ? spec.slice(spec.indexOf("/") + 1) : spec;
+  const atIdx = withoutScope.lastIndexOf("@");
+  if (atIdx <= 0) return false;
+  return /^\d/.test(withoutScope.slice(atIdx + 1));
+}
+function isNpxCommand(command) {
+  const base = command.split(/[\\/]/).pop() ?? command;
+  return base.replace(/\.(cmd|exe)$/i, "").toLowerCase() === "npx";
+}
+function packageSpecBase(spec) {
+  const scopeEnd = spec.startsWith("@") ? spec.indexOf("/") + 1 : 0;
+  const atIdx = spec.lastIndexOf("@");
+  return atIdx > scopeEnd ? spec.slice(0, atIdx) : spec;
+}
+var NPX_VALUE_FLAGS = /* @__PURE__ */ new Set(["p", "package", "c", "call", "cache", "userconfig", "shell", "n", "node-arg", "npm", "registry"]);
+var NPX_PACKAGE_SPEC_FLAGS = /* @__PURE__ */ new Set(["p", "package"]);
+function collectNpxPackageSpecs(args) {
+  const packageFlagSpecs = [];
+  let positionalSpec;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--") break;
+    if (arg.startsWith("-")) {
+      const eqIdx = arg.indexOf("=");
+      const key = (eqIdx === -1 ? arg : arg.slice(0, eqIdx)).replace(/^-+/, "");
+      const attached = eqIdx === -1 ? void 0 : arg.slice(eqIdx + 1);
+      if (NPX_VALUE_FLAGS.has(key)) {
+        let value = attached;
+        if (value === void 0) {
+          value = args[i + 1];
+          i++;
+        }
+        if (NPX_PACKAGE_SPEC_FLAGS.has(key) && value !== void 0) {
+          packageFlagSpecs.push(value);
+        }
+        continue;
+      }
+      continue;
+    }
+    positionalSpec = arg;
+    break;
+  }
+  return { packageFlagSpecs, positionalSpec };
+}
+
+// src/install/promoteMcp.ts
 function promoteMcp(_entry, profile, targetConfigPath, options = {}) {
   const force = options.force ?? false;
   const serverName = profile.name;
-  const { command, args, envVarsToFill } = deriveServerEntry(profile);
+  const { command, args, envVarsToFill, autoPinned } = deriveServerEntry(profile);
   let config = {};
   let rawExisting;
   if (existsSync5(targetConfigPath)) {
-    rawExisting = readFileSync2(targetConfigPath, "utf-8");
+    rawExisting = readFileSync3(targetConfigPath, "utf-8");
     try {
       config = JSON.parse(rawExisting);
     } catch (err) {
@@ -330,7 +445,7 @@ function promoteMcp(_entry, profile, targetConfigPath, options = {}) {
   mkdirSync4(dirname(targetConfigPath), { recursive: true });
   writeFileSync2(targetConfigPath, `${JSON.stringify(config, null, 2)}
 `);
-  return { target: targetConfigPath, serverName, envVarsToFill, backupPath };
+  return { target: targetConfigPath, serverName, envVarsToFill, backupPath, autoPinned };
 }
 function deriveServerEntry(profile) {
   const envNames = new Set(profile.envVars ?? []);
@@ -338,9 +453,41 @@ function deriveServerEntry(profile) {
     for (const key of Object.keys(profile.candidateEntry.env)) envNames.add(key);
   }
   if (profile.candidateEntry) {
+    const { command, args = [] } = profile.candidateEntry;
+    if (isNpxCommand(command)) {
+      const { packageFlagSpecs, positionalSpec } = collectNpxPackageSpecs(args);
+      const allSpecs = positionalSpec ? [...packageFlagSpecs, positionalSpec] : packageFlagSpecs;
+      const unpinned = allSpecs.filter((spec) => !isPinnedPackageSpec(spec));
+      if (unpinned.length > 0) {
+        const isSoleUnpinnedPositional = packageFlagSpecs.length === 0 && allSpecs.length === 1 && positionalSpec === unpinned[0];
+        if (isSoleUnpinnedPositional) {
+          const spec = unpinned[0];
+          const specPackage = packageSpecBase(spec);
+          if (profile.packageName && specPackage === profile.packageName && profile.version) {
+            const to = `${profile.packageName}@${profile.version}`;
+            const specIdx = args.indexOf(spec);
+            const pinnedArgs = [...args];
+            pinnedArgs[specIdx] = to;
+            return {
+              command,
+              args: pinnedArgs,
+              envVarsToFill: Array.from(envNames),
+              autoPinned: { from: spec, to }
+            };
+          }
+          const reason = profile.packageName && specPackage !== profile.packageName ? `the launch spec names package "${specPackage}", but the candidate's own package.json is "${profile.packageName}" \u2014 pinning it to a version scanned for a different package would be unsafe` : "no version was found in the candidate's own package.json to pin it to";
+          throw new UserError(
+            `cannot promote MCP server "${profile.name}": its documented launch command "npx ${spec}" is unpinned and can't be safely auto-pinned (${reason}). Pin the spec to an exact version in the candidate's config (e.g. \`${specPackage}@<version>\`) and try again \u2014 there is no override for this.`
+          );
+        }
+        throw new UserError(
+          `cannot promote MCP server "${profile.name}": its documented launch command "npx" has unpinned package spec(s) \u2014 ${unpinned.map((s) => `"${s}"`).join(", ")} \u2014 and this shape (a -p/--package dependency, or more than one spec) can't be safely auto-pinned. Pin every spec to an exact version in the candidate's config and try again \u2014 there is no override for this.`
+        );
+      }
+    }
     return {
-      command: profile.candidateEntry.command,
-      args: profile.candidateEntry.args ?? [],
+      command,
+      args,
       envVarsToFill: Array.from(envNames)
     };
   }
@@ -357,18 +504,22 @@ function deriveServerEntry(profile) {
 }
 
 // src/install/mcpCandidate.ts
-import { readFileSync as readFileSync3 } from "fs";
-function readPackageVersion(pkgPath) {
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
+function readPackageInfo(pkgPath) {
   try {
-    const pkg2 = JSON.parse(readFileSync3(pkgPath, "utf-8"));
-    return typeof pkg2.version === "string" ? pkg2.version : void 0;
+    const pkg2 = JSON.parse(readFileSync4(pkgPath, "utf-8"));
+    return {
+      name: typeof pkg2.name === "string" ? pkg2.name : void 0,
+      version: typeof pkg2.version === "string" ? pkg2.version : void 0
+    };
   } catch {
-    return void 0;
+    return {};
   }
 }
 function readConfigEntry(configPath, name) {
   try {
-    const cfg = JSON.parse(readFileSync3(configPath, "utf-8"));
+    const cfg = JSON.parse(readFileSync4(configPath, "utf-8"));
     const servers = cfg.mcpServers ?? cfg.servers ?? {};
     const raw = servers[name] ?? {};
     return {
@@ -383,15 +534,23 @@ function readConfigEntry(configPath, name) {
 function resolveMcpCandidateDetail(profile) {
   const name = profile.servers[0];
   if (profile.config.endsWith("package.json")) {
-    return { name, version: readPackageVersion(profile.config) };
+    return { name, version: readPackageInfo(profile.config).version };
   }
   const entry = readConfigEntry(profile.config, name);
-  return { name, command: entry?.command, args: entry?.args, env: entry?.env };
+  const sidecar = readPackageInfo(join6(dirname2(profile.config), "package.json"));
+  return {
+    name,
+    command: entry?.command,
+    args: entry?.args,
+    env: entry?.env,
+    version: sidecar.version,
+    packageName: sidecar.name
+  };
 }
 
 // src/provenance.ts
-import { appendFileSync, existsSync as existsSync6, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
-import { join as join5 } from "path";
+import { appendFileSync, existsSync as existsSync6, statSync as statSync3, writeFileSync as writeFileSync3 } from "fs";
+import { join as join7 } from "path";
 var FORGE_VERBS = ["DEFER", "ABSORB", "FORK", "REJECT", "WATCH"];
 var LEDGER_HEADER = "# Skill Forge \u2014 Provenance Ledger\n\nOne entry per external-skill ingestion decision.\n";
 function todayLocalIsoDate() {
@@ -405,7 +564,7 @@ function appendProvenance(entry, skillsRoot) {
   if (!FORGE_VERBS.includes(entry.verb)) {
     throw new Error(`verb must be one of ${FORGE_VERBS.join(", ")}`);
   }
-  if (!existsSync6(skillsRoot) || !statSync2(skillsRoot).isDirectory()) {
+  if (!existsSync6(skillsRoot) || !statSync3(skillsRoot).isDirectory()) {
     throw new Error(`skills-root not a directory: ${skillsRoot}`);
   }
   const today = todayLocalIsoDate();
@@ -422,7 +581,7 @@ function appendProvenance(entry, skillsRoot) {
 - **Drift check:** \`${driftCheck}\`
 - **Notes:** ${entry.notes ?? ""}
 `;
-  const ledgerPath = join5(skillsRoot, "SOURCES.md");
+  const ledgerPath = join7(skillsRoot, "SOURCES.md");
   if (!existsSync6(ledgerPath)) {
     writeFileSync3(ledgerPath, LEDGER_HEADER, "utf-8");
   }
@@ -432,7 +591,7 @@ function appendProvenance(entry, skillsRoot) {
 
 // src/commands/gatePipeline.ts
 import { readdirSync as readdirSync5 } from "fs";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 
 // src/gate/profile.ts
 import { execFileSync } from "child_process";
@@ -448,79 +607,11 @@ import {
   statSync as statSync4
 } from "fs";
 import { tmpdir } from "os";
-import { basename as basename3, dirname as dirname2, extname as extname3, join as join8, resolve as resolve2 } from "path";
+import { basename as basename3, dirname as dirname3, extname as extname3, join as join9, resolve as resolve2 } from "path";
 
 // src/gate/mcpCapabilities.ts
 import { existsSync as existsSync7, readFileSync as readFileSync5 } from "fs";
-import { extname as extname2, join as join7 } from "path";
-
-// src/gate/scanShared.ts
-import { readFileSync as readFileSync4, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
-import { extname, join as join6 } from "path";
-var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", "node_modules", "dist", "build", "__pycache__", ".venv", "venv"]);
-var BINARY_EXT = /* @__PURE__ */ new Set([
-  ".png",
-  ".jpg",
-  ".jpeg",
-  ".gif",
-  ".webp",
-  ".ico",
-  ".pdf",
-  ".zip",
-  ".tar",
-  ".gz",
-  ".woff",
-  ".woff2",
-  ".ttf",
-  ".eot",
-  ".mp4",
-  ".mp3",
-  ".wasm",
-  ".bin",
-  ".exe"
-]);
-var MAX_FILE_BYTES = 2 * 1024 * 1024;
-function* walk(dir) {
-  let entries;
-  try {
-    entries = readdirSync2(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const full = join6(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (SKIP_DIRS2.has(entry.name)) continue;
-      yield* walk(full);
-    } else if (entry.isFile()) {
-      yield full;
-    }
-  }
-}
-function readTextFile(file) {
-  if (BINARY_EXT.has(extname(file).toLowerCase())) return void 0;
-  try {
-    if (statSync3(file).size > MAX_FILE_BYTES) return void 0;
-    const content = readFileSync4(file, "utf-8");
-    if (content.slice(0, 512).includes("\0")) return void 0;
-    return content;
-  } catch {
-    return void 0;
-  }
-}
-var BLOCK_SEVERITIES_BY_STRICTNESS = {
-  "block-high": /* @__PURE__ */ new Set(["HIGH", "CRITICAL"]),
-  "block-medium": /* @__PURE__ */ new Set(["MEDIUM", "HIGH", "CRITICAL"]),
-  "warn-only": /* @__PURE__ */ new Set()
-};
-function verdictFor(findings, strictness) {
-  const blockSeverities = BLOCK_SEVERITIES_BY_STRICTNESS[strictness];
-  if (findings.some((f) => blockSeverities.has(f.severity))) return "block";
-  if (findings.length > 0) return "warn";
-  return "pass";
-}
-
-// src/gate/mcpCapabilities.ts
+import { extname as extname2, join as join8 } from "path";
 var SOURCE_EXT = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 var MAX_ITEMS_PER_CATEGORY = 200;
 function readJsonSafe(file) {
@@ -626,7 +717,7 @@ var MCP_SDK_IMPORT_RE = /@modelcontextprotocol\/sdk/;
 function extractMcpCapabilities(packageDir) {
   const buckets = { tools: /* @__PURE__ */ new Set(), resources: /* @__PURE__ */ new Set(), prompts: /* @__PURE__ */ new Set() };
   let hasPackageJsonMarker = false;
-  const pkgPath = join7(packageDir, "package.json");
+  const pkgPath = join8(packageDir, "package.json");
   if (existsSync7(pkgPath)) {
     const pkg2 = readJsonSafe(pkgPath);
     if (pkg2 && typeof pkg2 === "object" && !Array.isArray(pkg2)) {
@@ -634,7 +725,7 @@ function extractMcpCapabilities(packageDir) {
     }
   }
   for (const manifestName of [".mcp.json", "mcp.json"]) {
-    const manifestPath = join7(packageDir, manifestName);
+    const manifestPath = join8(packageDir, manifestName);
     if (!existsSync7(manifestPath)) continue;
     const parsed = readJsonSafe(manifestPath);
     if (parsed !== void 0) {
@@ -725,8 +816,24 @@ 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 (existsSync8(join9(p, ".claude-plugin", "plugin.json"))) return "plugin";
   if (detectArtifactType(p) === "mcp") return "mcp";
   return "skill";
 }
@@ -734,7 +841,7 @@ var MCP_SDK_DEP2 = "@modelcontextprotocol/sdk";
 var MCP_KEYWORD2 = "mcp-server";
 var MCP_BIN_PREFIX2 = /^mcp-/i;
 function readPackageJsonSafe(root) {
-  const pkgPath = join8(root, "package.json");
+  const pkgPath = join9(root, "package.json");
   if (!existsSync8(pkgPath)) return void 0;
   try {
     return JSON.parse(readFileSync6(pkgPath, "utf-8"));
@@ -758,7 +865,7 @@ function hasMcpPackageMarkers(pkg2) {
   return false;
 }
 function detectArtifactType(root) {
-  if (existsSync8(join8(root, ".mcp.json")) || existsSync8(join8(root, "mcp.json"))) return "mcp";
+  if (existsSync8(join9(root, ".mcp.json")) || existsSync8(join9(root, "mcp.json"))) return "mcp";
   const pkg2 = readPackageJsonSafe(root);
   if (pkg2 && hasMcpPackageMarkers(pkg2)) return "mcp";
   return "skill";
@@ -768,22 +875,22 @@ function resolveSkillMd(inputPath) {
   let tmpDir;
   const initialStat = statSync4(currentPath);
   if (extname3(currentPath) === ".skill" || initialStat.isFile() && isZipFile(currentPath)) {
-    tmpDir = mkdtempSync(join8(tmpdir(), "forge_"));
+    tmpDir = mkdtempSync(join9(tmpdir(), "forge_"));
     extractZip(currentPath, tmpDir);
     currentPath = tmpDir;
   }
   const stat = statSync4(currentPath);
   if (stat.isFile() && basename3(currentPath) === "SKILL.md") {
-    return { skillMd: currentPath, root: dirname2(currentPath), tmpDir };
+    return { skillMd: currentPath, root: dirname3(currentPath), tmpDir };
   }
   if (stat.isDirectory()) {
-    const direct = join8(currentPath, "SKILL.md");
+    const direct = join9(currentPath, "SKILL.md");
     if (existsSync8(direct)) {
       return { skillMd: direct, root: currentPath, tmpDir };
     }
     const matches = findSkillMdOneLevelDown(currentPath);
     if (matches.length === 1) {
-      return { skillMd: matches[0], root: dirname2(matches[0]), tmpDir };
+      return { skillMd: matches[0], root: dirname3(matches[0]), tmpDir };
     }
     if (matches.length > 1) {
       cleanupTmp(tmpDir);
@@ -803,15 +910,15 @@ function findSkillMdOneLevelDown(dir) {
   const matches = /* @__PURE__ */ new Set();
   for (const entry of readdirSync3(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
-      const candidate = join8(dir, entry.name, "SKILL.md");
+      const candidate = join9(dir, entry.name, "SKILL.md");
       if (existsSync8(candidate)) matches.add(candidate);
     }
   }
-  const skillsDir = join8(dir, "skills");
+  const skillsDir = join9(dir, "skills");
   if (isDir(skillsDir)) {
     for (const entry of readdirSync3(skillsDir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
-        const candidate = join8(skillsDir, entry.name, "SKILL.md");
+        const candidate = join9(skillsDir, entry.name, "SKILL.md");
         if (existsSync8(candidate)) matches.add(candidate);
       }
     }
@@ -895,7 +1002,7 @@ function detectLicense(root, fm) {
   if (fm.license) return fm.license;
   const names = ["LICENSE", "LICENSE.md", "LICENSE.txt", "COPYING", "license"];
   for (const name of names) {
-    const p = join8(root, name);
+    const p = join9(root, name);
     if (existsSync8(p) && statSync4(p).isFile()) {
       const head = readFileSync6(p, "utf-8").slice(0, 2e3).toLowerCase();
       for (const [hint, label] of Object.entries(SPDX_HINTS)) {
@@ -909,7 +1016,7 @@ function detectLicense(root, fm) {
 function walkFiles(dir) {
   const out = [];
   for (const entry of readdirSync3(dir, { withFileTypes: true })) {
-    const full = join8(dir, entry.name);
+    const full = join9(dir, entry.name);
     if (entry.isDirectory()) {
       out.push(...walkFiles(full));
     } else if (entry.isFile()) {
@@ -921,7 +1028,7 @@ function walkFiles(dir) {
 function countResources(root) {
   const resources = {};
   for (const d of RESOURCE_DIRS) {
-    const dp = join8(root, d);
+    const dp = join9(root, d);
     if (isDir(dp)) {
       resources[d] = walkFiles(dp).length;
     }
@@ -932,7 +1039,7 @@ function scanMcpAndImports(text, root) {
   const mcpRefRe = /mcp__[a-zA-Z0-9_]+/g;
   const mcpRefs = new Set(text.match(mcpRefRe) ?? []);
   const imports = /* @__PURE__ */ new Set();
-  const scriptsDir = join8(root, "scripts");
+  const scriptsDir = join9(root, "scripts");
   if (isDir(scriptsDir)) {
     for (const f of walkFiles(scriptsDir)) {
       if (!f.endsWith(".py")) continue;
@@ -981,19 +1088,19 @@ function profileSkillDir(inputPath) {
   }
 }
 function profilePlugin(p) {
-  const manifestPath = join8(p, ".claude-plugin", "plugin.json");
+  const manifestPath = join9(p, ".claude-plugin", "plugin.json");
   let manifest;
   try {
     manifest = JSON.parse(readFileSync6(manifestPath, "utf-8"));
   } catch (err) {
     throw new Error(`could not parse plugin.json under ${p}: ${err.message}`);
   }
-  const skillsDir = join8(p, "skills");
+  const skillsDir = join9(p, "skills");
   let skills = [];
   if (isDir(skillsDir)) {
-    skills = readdirSync3(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync8(join8(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
+    skills = readdirSync3(skillsDir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync8(join9(skillsDir, d.name, "SKILL.md"))).map((d) => d.name).sort();
   }
-  const commandsDir = join8(p, "commands");
+  const commandsDir = join9(p, "commands");
   const commands = isDir(commandsDir) ? readdirSync3(commandsDir).filter((f) => f.endsWith(".md")).length : 0;
   const mc = manifest.mcpServers ?? manifest.mcp_servers ?? {};
   const mcpServers = typeof mc === "object" && mc !== null ? Object.keys(mc).sort() : [];
@@ -1011,7 +1118,7 @@ function profilePlugin(p) {
   };
 }
 function profileMcp(p) {
-  const explicitConfig = existsSync8(join8(p, ".mcp.json")) ? join8(p, ".mcp.json") : existsSync8(join8(p, "mcp.json")) ? join8(p, "mcp.json") : void 0;
+  const explicitConfig = existsSync8(join9(p, ".mcp.json")) ? join9(p, ".mcp.json") : existsSync8(join9(p, "mcp.json")) ? join9(p, "mcp.json") : void 0;
   if (explicitConfig) {
     let cfg;
     try {
@@ -1031,7 +1138,7 @@ function profileMcp(p) {
       capabilities: extractMcpCapabilities(p)
     };
   }
-  const pkgPath = join8(p, "package.json");
+  const pkgPath = join9(p, "package.json");
   let pkg2;
   try {
     pkg2 = JSON.parse(readFileSync6(pkgPath, "utf-8"));
@@ -1053,7 +1160,7 @@ function profileMcp(p) {
 // src/gate/safety.ts
 import { statSync as statSync5 } from "fs";
 import { execFile } from "child_process";
-import { delimiter, join as join9 } from "path";
+import { delimiter, join as join10 } from "path";
 import { promisify } from "util";
 var execFileAsync = promisify(execFile);
 var DENY_RULES = [
@@ -1152,7 +1259,7 @@ function which(cmd) {
   const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
   for (const dir of dirs) {
     for (const ext of exts) {
-      const candidate = join9(dir, cmd + ext);
+      const candidate = join10(dir, cmd + ext);
       try {
         if (statSync5(candidate).isFile()) return candidate;
       } catch {
@@ -1193,7 +1300,7 @@ async function scanSafety(targetPath, strictness = DEFAULT_STRICTNESS) {
 
 // src/gate/overlap.ts
 import { existsSync as existsSync9, readFileSync as readFileSync7, readdirSync as readdirSync4 } from "fs";
-import { basename as basename4, dirname as dirname3, join as join10, resolve as resolve3 } from "path";
+import { basename as basename4, dirname as dirname4, join as join11, resolve as resolve3 } from "path";
 var STOPWORDS = new Set(
   `
 a an the and or of to for in on with use used using when whether this that these those is are be
@@ -1201,21 +1308,21 @@ 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;
 }
 function readFrontmatter(skillMdPath) {
   const text = readFileSync7(skillMdPath, "utf-8");
-  const meta = { name: basename4(dirname3(skillMdPath)), description: "" };
+  const meta = { name: basename4(dirname4(skillMdPath)), description: "" };
   if (text.startsWith("---\n")) {
     const block = splitLimited(text, "---", 2)[1] ?? "";
     const nameMatch = block.match(/^name:\s*(.+)$/m);
@@ -1316,21 +1423,21 @@ function listSubdirs(dir) {
   } catch {
     return [];
   }
-  return entries.filter((e) => e.isDirectory()).map((e) => join10(dir, e.name));
+  return entries.filter((e) => e.isDirectory()).map((e) => join11(dir, e.name));
 }
 function findSkillMdFiles(root) {
   const found = /* @__PURE__ */ new Set();
   for (const dir of listSubdirs(root)) {
-    const candidate = join10(dir, "SKILL.md");
+    const candidate = join11(dir, "SKILL.md");
     if (existsSync9(candidate)) found.add(resolve3(candidate));
   }
-  for (const dir of listSubdirs(join10(root, "skills"))) {
-    const candidate = join10(dir, "SKILL.md");
+  for (const dir of listSubdirs(join11(root, "skills"))) {
+    const candidate = join11(dir, "SKILL.md");
     if (existsSync9(candidate)) found.add(resolve3(candidate));
   }
   for (const topDir of listSubdirs(root)) {
-    for (const dir of listSubdirs(join10(topDir, "skills"))) {
-      const candidate = join10(dir, "SKILL.md");
+    for (const dir of listSubdirs(join11(topDir, "skills"))) {
+      const candidate = join11(dir, "SKILL.md");
       if (existsSync9(candidate)) found.add(resolve3(candidate));
     }
   }
@@ -1343,7 +1450,7 @@ function scanOverlap(candidatePath, skillsRoot) {
   }
   let cpath = resolve3(expandHome(candidatePath));
   if (isDir(cpath)) {
-    cpath = join10(cpath, "SKILL.md");
+    cpath = join11(cpath, "SKILL.md");
   }
   if (!existsSync9(cpath)) {
     throw new Error(`candidate SKILL.md not found: ${cpath}`);
@@ -1398,21 +1505,6 @@ function looksHighEntropy(value) {
   const uniqueChars = new Set(value).size;
   return varietyCount >= 2 && uniqueChars / value.length > 0.4;
 }
-function isPinnedPackageSpec(spec) {
-  const withoutScope = spec.startsWith("@") ? spec.slice(spec.indexOf("/") + 1) : spec;
-  const atIdx = withoutScope.lastIndexOf("@");
-  if (atIdx <= 0) return false;
-  return /^\d/.test(withoutScope.slice(atIdx + 1));
-}
-function isNpxCommand(command) {
-  const base = command.split(/[\\/]/).pop() ?? command;
-  return base.replace(/\.(cmd|exe)$/i, "").toLowerCase() === "npx";
-}
-function packageSpecBase(spec) {
-  const scopeEnd = spec.startsWith("@") ? spec.indexOf("/") + 1 : 0;
-  const atIdx = spec.lastIndexOf("@");
-  return atIdx > scopeEnd ? spec.slice(0, atIdx) : spec;
-}
 function collectServerNodes(node, out) {
   if (Array.isArray(node)) {
     for (const item of node) collectServerNodes(item, out);
@@ -1443,14 +1535,17 @@ function scanJsonConfig(file, parsed) {
     if (command && isNpxCommand(command)) {
       const flagIdx = args.findIndex((a) => a === "-y" || a === "--yes");
       if (flagIdx !== -1) {
-        const pkgSpec = args.slice(flagIdx + 1).find((a) => !a.startsWith("-"));
-        if (pkgSpec && !isPinnedPackageSpec(pkgSpec)) {
-          findings.push({
-            severity: "MEDIUM",
-            rule: "mcp-unpinned-npx",
-            file,
-            detail: `npx -y ${pkgSpec} is unpinned \u2014 pin an exact version (${packageSpecBase(pkgSpec)}@<version>) so the resolved server code can't change silently`
-          });
+        const { packageFlagSpecs, positionalSpec } = collectNpxPackageSpecs(args);
+        const allSpecs = positionalSpec ? [...packageFlagSpecs, positionalSpec] : packageFlagSpecs;
+        for (const pkgSpec of allSpecs) {
+          if (!isPinnedPackageSpec(pkgSpec)) {
+            findings.push({
+              severity: "MEDIUM",
+              rule: "mcp-unpinned-npx",
+              file,
+              detail: `npx -y ${pkgSpec} is unpinned \u2014 pin an exact version (${packageSpecBase(pkgSpec)}@<version>) so the resolved server code can't change silently`
+            });
+          }
         }
       }
     }
@@ -1743,6 +1838,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 +1920,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);
@@ -1872,7 +1960,7 @@ function resolveMcpCandidatePath(entry) {
     children = readdirSync5(entry.quarantinePath, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
   } catch {
   }
-  return children.length === 1 ? join11(entry.quarantinePath, children[0]) : entry.quarantinePath;
+  return children.length === 1 ? join12(entry.quarantinePath, children[0]) : entry.quarantinePath;
 }
 async function runGate(candidatePath, skillsRoot, {
   proFeatureLabel = "overlap analysis",
@@ -1891,11 +1979,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 };
@@ -1904,9 +1988,9 @@ async function runGate(candidatePath, skillsRoot, {
 // src/queue.ts
 import { randomUUID as randomUUID2 } from "crypto";
 import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 function getQueuePath() {
-  return join12(getHomeDir(), "queue.json");
+  return join13(getHomeDir(), "queue.json");
 }
 function readQueue() {
   const path = getQueuePath();
@@ -1944,15 +2028,15 @@ function generateId(existingIds) {
 // src/handoff.ts
 import { spawnSync } from "child_process";
 import { existsSync as existsSync12 } from "fs";
-import { dirname as dirname4, join as join13 } from "path";
+import { dirname as dirname5, join as join14 } from "path";
 import { fileURLToPath } from "url";
 var KNOWN_AGENT_BINARIES = ["claude", "codex", "cursor-agent", "windsurf", "opencode", "gemini"];
 var HANDOFF_INSTRUCTION = "Read {prompt} and follow its instructions for the skill installed at {path}";
 function resolvePromptPath() {
-  const here = dirname4(fileURLToPath(import.meta.url));
-  const builtCandidate = join13(here, "ingest-prompt.md");
+  const here = dirname5(fileURLToPath(import.meta.url));
+  const builtCandidate = join14(here, "ingest-prompt.md");
   if (existsSync12(builtCandidate)) return builtCandidate;
-  return join13(here, "..", "assets", "ingest-prompt.md");
+  return join14(here, "..", "assets", "ingest-prompt.md");
 }
 function defaultIsOnPath(bin) {
   const finder = process.platform === "win32" ? "where" : "which";
@@ -2014,7 +2098,7 @@ import { createInterface } from "readline/promises";
 // src/agents.ts
 import { statSync as statSync7 } from "fs";
 import { homedir as homedir3 } from "os";
-import { join as join14, resolve as resolve5 } from "path";
+import { join as join15, resolve as resolve5 } from "path";
 function isFile(p) {
   try {
     return statSync7(p).isFile();
@@ -2028,7 +2112,7 @@ function projectPath(root, cwd) {
 function globalPath(root, home) {
   if (!root) return void 0;
   if (root === "~") return home;
-  if (root.startsWith("~/")) return join14(home, root.slice(2));
+  if (root.startsWith("~/")) return join15(home, root.slice(2));
   return root;
 }
 function makeAgent(spec) {
@@ -2429,13 +2513,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 +2581,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 +2621,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 +2653,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);
@@ -2553,13 +2662,20 @@ async function addMcp(source, config, options) {
       // version may be absent — promoteMcp refuses the unpinnable npx fallback
       // rather than writing "npx pkg@unknown"; see deriveServerEntry in promoteMcp.ts.
       version: detail.version,
+      // packageName (v0.7) — the candidate's own scanned package.json name, so
+      // deriveServerEntry can auto-pin an unpinned npx spec in candidateEntry
+      // only when it provably matches the package that was actually scanned.
+      packageName: detail.packageName,
       envVars: detail.env ? Object.keys(detail.env) : void 0,
       candidateEntry: detail.command ? { command: detail.command, args: detail.args, env: detail.env } : void 0
     };
-    const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join15(process.cwd(), ".mcp.json");
+    const mcpTargetPath = options.mcpTarget ?? config.mcpTargets?.[0] ?? join16(process.cwd(), ".mcp.json");
     const result = promoteMcp(entry, serverProfile, mcpTargetPath, { force: options.force });
     reject(entry);
     logOutcome(`[skill-forge] promoted -> ${result.target} (server "${result.serverName}")`, options.json);
+    if (result.autoPinned) {
+      logOutcome(`[skill-forge] pinned launch spec ${result.autoPinned.from} -> ${result.autoPinned.to}`, options.json);
+    }
     if (result.backupPath) {
       logOutcome(`[skill-forge] backed up existing config -> ${result.backupPath}`, options.json);
     }
@@ -2585,7 +2701,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 +2714,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 = {}) {
@@ -2670,7 +2764,7 @@ async function scan(source, options = {}) {
 }
 
 // src/commands/list.ts
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 async function list() {
   await maybeOfferInit();
   const config = loadConfig();
@@ -2683,14 +2777,14 @@ async function list() {
   }
   console.log(`[skill-forge] ${ids.length} held in quarantine (${quarantineDir}):`);
   for (const id of ids) {
-    const skillDirs = findSkillDirs(join16(quarantineDir, id));
+    const skillDirs = findSkillDirs(join17(quarantineDir, id));
     if (skillDirs.length === 0) {
       console.log(`  ${id}  (no SKILL.md found)`);
       continue;
     }
     const names = skillDirs.map((dir) => {
       try {
-        return readFrontmatter(join16(dir, "SKILL.md")).name;
+        return readFrontmatter(join17(dir, "SKILL.md")).name;
       } catch {
         return dir;
       }
@@ -2711,6 +2805,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 dirname6, join as join18, 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 = join18(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 = join18(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 = join18(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join18(stagingDir, "proposed_CLAUDE.md");
+  const reportMdPath = join18(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(join18(tmpdir2(), "skill-forge-evolve-"));
+  let profile;
+  let safety;
+  try {
+    cpSync3(proposedSkillMd, join18(tempDir, "SKILL.md"));
+    if (existsSync14(proposedClaudeMd)) {
+      cpSync3(proposedClaudeMd, join18(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 = dirname6(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 = join18(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 = join18(stagingDir, "proposed_SKILL.md");
+  const proposedClaudeMd = join18(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 +3127,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 +3143,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();