skillshelf 0.2.0 → 0.3.0

package/src/commands/outdated.ts

@@ -6,17 +6,22 @@
 //
 // Read command: supports --json.
 
-import type { Ctx, LockEntry } from "../types.ts";
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import type { Ctx, LockEntry, Skill } from "../types.ts";
 import { readLockfile } from "../core/provenance.ts";
+import { entryMode, entryModeInfo, loadLibrary, findByName } from "../core/library.ts";
+import { hashContent } from "../core/crawl.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
 import { parseStoredSource, latestRef } from "../core/fetch.ts";
 
 export const meta = {
   name: "outdated",
   summary: "Check upstream ref per tracked skill and mark stale ones",
-  usage: "skl outdated [name] [--json]",
+  usage: "skl outdated [name] [--check-local] [--json]",
 } as const;
 
-type Status = "stale" | "current" | "unknown";
+type Status = "stale" | "current" | "unknown" | "linked" | "diverged";
 
 interface Row {
   name: string;
@@ -59,53 +64,168 @@ async function checkEntry(entry: LockEntry): Promise<Row> {
   };
 }
 
+/**
+ * A LINKED entry (library/<name> symlinks to an external dev repo) has no tracked
+ * upstream — its own git owns versioning. Report it as such instead of probing a
+ * (possibly stale) github ref (ADR-0004).
+ */
+function linkedRow(entry: LockEntry): Row {
+  return {
+    name: entry.name,
+    channel: "local",
+    source: entry.source,
+    installedRef: entry.ref,
+    latestRef: null,
+    status: "linked",
+    note: "dev repo owns versioning",
+  };
+}
+
+/**
+ * A LINKED library skill with NO lockfile entry (the normal case for `skl link
+ * --from` — it drops any lock entry). Without this, a freshly-linked dev skill is
+ * INVISIBLE to outdated, giving an agent zero positive evidence its dev repo is the
+ * canonical source. Surface it as a `linked` row regardless.
+ */
+function linkedRowFromName(name: string, linkTarget: string | null): Row {
+  return {
+    name,
+    channel: "local",
+    source: linkTarget ?? "(dev repo)",
+    installedRef: "-",
+    latestRef: null,
+    status: "linked",
+    note: "dev repo owns versioning",
+  };
+}
+
+/**
+ * Offline (no network) divergence check for an OWNED tracked skill: compare the local
+ * SKILL.md body hash to the baseline recorded at install/update time
+ * (lockfile.installedHash). Answers "have I locally edited this?" without probing
+ * upstream — usable on a plane / in CI with no creds.
+ */
+function checkEntryLocal(entry: LockEntry, library: Skill[], libraryPath: string): Row {
+  const skill = findByName(library, entry.name);
+  const bodyPath = skill?.bodyPath ?? join(libraryPath, entry.name, "SKILL.md");
+  let localHash: string | null = null;
+  try {
+    if (existsSync(bodyPath)) {
+      const raw = readFileSync(bodyPath, "utf8");
+      localHash = hashContent(parseFrontmatter(raw).body);
+    }
+  } catch {
+    /* leave null */
+  }
+  const base = {
+    name: entry.name,
+    channel: entry.channel,
+    source: entry.source,
+    installedRef: entry.ref,
+    latestRef: null,
+  };
+  if (entry.installedHash == null) {
+    return { ...base, status: "unknown", note: "no recorded baseline (installed before hash tracking) — re-run `skl update` to record one" };
+  }
+  if (localHash == null) {
+    return { ...base, status: "unknown", note: "local SKILL.md unreadable" };
+  }
+  return localHash === entry.installedHash
+    ? { ...base, status: "current", note: "matches installed baseline (offline)" }
+    : { ...base, status: "diverged", note: "local body diverged from installed baseline (offline)" };
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   const json = argv.includes("--json");
+  const checkLocal = argv.includes("--check-local");
   const nameArg = argv.find((a) => !a.startsWith("-")) ?? null;
+  const libraryPath = ctx.config.libraryPath;
 
   try {
-    const lock = await readLockfile(ctx.config.libraryPath);
+    const lock = await readLockfile(libraryPath);
     let entries = Object.values(lock.entries);
     if (nameArg) entries = entries.filter((e) => e.name === nameArg);
     entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-    if (entries.length === 0) {
+    // Load the library so we can (a) hash local bodies for --check-local and
+    // (b) surface LINKED skills that have NO lock entry — the normal `skl link
+    // --from` case — which would otherwise be invisible here.
+    const library = await loadLibrary(libraryPath);
+
+    const rows = await Promise.all(
+      entries.map((e) =>
+        entryMode(libraryPath, e.name) === "linked"
+          ? Promise.resolve(linkedRow(e))
+          : checkLocal
+            ? Promise.resolve(checkEntryLocal(e, library, libraryPath))
+            : checkEntry(e),
+      ),
+    );
+
+    // Augment: LINKED library skills not already represented by a lock entry get a
+    // `linked` row, so a freshly-shelved dev skill shows positive evidence.
+    const known = new Set(rows.map((r) => r.name));
+    for (const s of library) {
+      if (known.has(s.name)) continue;
+      if (nameArg && s.name !== nameArg) continue;
+      const info = entryModeInfo(libraryPath, s.name);
+      if (info.mode === "linked") rows.push(linkedRowFromName(s.name, info.linkTarget));
+    }
+    rows.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    if (rows.length === 0) {
       if (json) ctx.json({ ok: true, checked: 0, stale: 0, rows: [] });
       else if (nameArg) ctx.log(`no tracked skill named "${nameArg}"`);
       else ctx.log("no tracked third-party skills (lockfile is empty)");
       return 0;
     }
 
-    const rows = await Promise.all(entries.map((e) => checkEntry(e)));
     const stale = rows.filter((r) => r.status === "stale");
+    const diverged = rows.filter((r) => r.status === "diverged");
 
     if (json) {
       ctx.json({
         ok: true,
         checked: rows.length,
         stale: stale.length,
+        diverged: diverged.length,
         rows,
       });
     } else {
       for (const r of rows) {
-        const mark = r.status === "stale" ? "STALE  " : r.status === "current" ? "current" : "unknown";
+        const mark =
+          r.status === "stale" ? "STALE   "
+            : r.status === "diverged" ? "DIVERGED"
+              : r.status === "current" ? "current "
+                : r.status === "linked" ? "linked  "
+                  : "unknown ";
         const refInfo =
-          r.status === "stale"
-            ? `${shortRef(r.installedRef)} -> ${shortRef(r.latestRef ?? "")}`
-            : r.status === "current"
-              ? shortRef(r.installedRef)
-              : `${shortRef(r.installedRef)} (${r.note})`;
-        const extra = r.note && r.status !== "unknown" ? `  [${r.note}]` : "";
+          r.status === "linked"
+            ? r.note
+            : r.status === "stale"
+              ? `${shortRef(r.installedRef)} -> ${shortRef(r.latestRef ?? "")}`
+              : r.status === "diverged"
+                ? r.note
+                : r.status === "current"
+                  ? shortRef(r.installedRef) + (checkLocal ? " (offline)" : "")
+                  : `${shortRef(r.installedRef)} (${r.note})`;
+        const extra =
+          r.note && !["unknown", "linked", "diverged"].includes(r.status) ? `  [${r.note}]` : "";
         ctx.log(`${mark}  ${r.name.padEnd(28)} ${r.channel.padEnd(15)} ${refInfo}${extra}`);
       }
       ctx.log("");
-      ctx.log(`${rows.length} tracked, ${stale.length} stale.`);
-      if (stale.length > 0) {
-        ctx.log(`run \`skl update [name]\` to re-pull (overlays are preserved).`);
+      if (checkLocal) {
+        ctx.log(`${rows.length} tracked, ${diverged.length} locally diverged (offline check — no upstream probed).`);
+        if (diverged.length > 0) ctx.log("re-run \`skl update [name]\` to see the upstream diff, or \`--force\` to overwrite.");
+      } else {
+        ctx.log(`${rows.length} tracked, ${stale.length} stale.`);
+        if (stale.length > 0) ctx.log(`run \`skl update [name]\` to re-pull (domain tags are preserved).`);
       }
     }
-    // Non-zero exit when stale skills exist, so agents/CI can branch on it.
-    return stale.length > 0 ? 2 : 0;
+    // Non-zero exit when stale (or, offline, locally-diverged) skills exist, so
+    // agents/CI can branch on it.
+    const flagged = checkLocal ? diverged.length : stale.length;
+    return flagged > 0 ? 2 : 0;
   } catch (err) {
     ctx.error("outdated: failed:", err instanceof Error ? err.message : String(err));
     return 1;

package/src/commands/refresh.ts

@@ -0,0 +1,133 @@
+// `skl refresh` — re-sync THIS project's ./.claude/skills/ symlinks to current library
+// reality. The idempotent re-`use` was already the de-facto re-sync; this names it.
+//
+// For every managed symlink in the project skills dir:
+//   - resolves to a library skill that still exists  -> repoint at its current path
+//     (repairs a relocated library: SKILLSHELF_LIBRARY moved, absolute link stale)
+//   - the same-named library skill no longer exists   -> prune (renamed/removed/retired)
+//   - points somewhere unrelated (not a library skill) -> left untouched
+//
+// Deliberately does NOT expand bundles (that would guess intent) — to pick up NEW
+// members of a bundle, re-run `skl use <bundle>` (also idempotent).
+//
+//   skl refresh [--dry-run] [--json]
+
+import { join, resolve, isAbsolute, dirname } from "node:path";
+import { readdir, readlink } from "node:fs/promises";
+import type { Ctx, Skill } from "../types.ts";
+import { activeSkills } from "../core/library.ts";
+import {
+  pathExists,
+  isSymlink,
+  realpathOrSelf,
+  realpathOrSelfAsync,
+  safeSymlink,
+  removeSymlink,
+} from "../lib/fs.ts";
+
+/** Direct entry names in a dir that are symlinks — INCLUDING dead ones (which
+ *  listDirNames drops because they don't resolve to a directory). */
+async function symlinkNames(dir: string): Promise<string[]> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isSymbolicLink()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+export const meta = {
+  name: "refresh",
+  summary: "Re-sync this project's .claude/skills symlinks to current library reality",
+  usage: "skl refresh [--dry-run] [--json]",
+} as const;
+
+type Action = "repointed" | "ok" | "pruned" | "foreign";
+
+interface Outcome {
+  name: string;
+  action: Action;
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const dryRun = argv.includes("--dry-run");
+  const skillsDir = join(process.cwd(), ".claude", "skills");
+
+  try {
+    const skills = activeSkills(await ctx.loadLibrary());
+    const byName = new Map<string, Skill>(skills.map((s) => [s.name, s]));
+    // Two library prefixes: realpath (resolves /tmp -> /private/tmp etc.) and the
+    // plain resolved path. A DEAD link's target can't be realpath'd, so we match its
+    // raw readlink target against either form to decide if it pointed into the library.
+    const libPrefixes = [realpathOrSelf(ctx.libraryPath), resolve(ctx.libraryPath)].map((p) =>
+      p.endsWith("/") ? p : p + "/",
+    );
+
+    const outcomes: Outcome[] = [];
+    if (pathExists(skillsDir)) {
+      for (const name of await symlinkNames(skillsDir)) {
+        const link = join(skillsDir, name);
+        if (!isSymlink(link)) continue; // only manage symlinks; never touch real files
+        const skill = byName.get(name);
+
+        if (skill) {
+          // The same-named library skill exists: ensure the link points at it.
+          const cur = realpathOrSelf(link);
+          const want = await realpathOrSelfAsync(skill.path);
+          if (cur === want) {
+            outcomes.push({ name, action: "ok" });
+          } else {
+            if (!dryRun) await safeSymlink(skill.path, link, { force: true });
+            outcomes.push({ name, action: "repointed" });
+          }
+          continue;
+        }
+
+        // No same-named library skill. Read the RAW target to decide if it pointed
+        // into the library (renamed/removed -> prune) or somewhere unrelated (leave).
+        const raw = await readlink(link).catch(() => null);
+        const targetAbs = raw == null ? "" : isAbsolute(raw) ? raw : resolve(dirname(link), raw);
+        // Strictly UNDER the library (a per-skill entry) — a link to the library ROOT
+        // itself was never a skill deployment, so leave it as `foreign` rather than prune.
+        const pointsIntoLibrary = libPrefixes.some((pre) => targetAbs.startsWith(pre));
+
+        if (pointsIntoLibrary) {
+          // Was a library skill (link still resolves into the library tree) but no
+          // active skill of this name remains — renamed/removed/retired. Prune.
+          if (!dryRun) await removeSymlink(link, { force: true });
+          outcomes.push({ name, action: "pruned" });
+        } else {
+          outcomes.push({ name, action: "foreign" });
+        }
+      }
+    }
+
+    const count = (a: Action) => outcomes.filter((o) => o.action === a).length;
+    if (json) {
+      ctx.json({
+        dryRun,
+        skillsDir,
+        outcomes,
+        repointed: count("repointed"),
+        pruned: count("pruned"),
+        ok: count("ok"),
+      });
+      return 0;
+    }
+
+    if (outcomes.length === 0) {
+      ctx.log(`No managed symlinks in ${skillsDir} — nothing to refresh.`);
+      return 0;
+    }
+    const verb = dryRun ? "would" : "did";
+    ctx.log(`Refresh ${skillsDir}:`);
+    for (const o of outcomes) ctx.log(`  ${o.name}  [${o.action}]`);
+    ctx.log("");
+    ctx.log(`${count("repointed")} repointed, ${count("pruned")} pruned, ${count("ok")} already current (${verb} apply).`);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl refresh: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/remediation.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { remediate } from "./where.ts";
+import { run as refreshRun } from "./refresh.ts";
+import { run as statusRun } from "./status.ts";
+import { isSymlink, realpathOrSelf } from "../lib/fs.ts";
+import { loadLibrary } from "../core/library.ts";
+import { inventoryDeployments, remediationFor } from "../core/deployments.ts";
+import type { Ctx, DeploymentSite } from "../types.ts";
+
+function site(partial: Partial<DeploymentSite> & Pick<DeploymentSite, "name" | "path" | "kind">): DeploymentSite {
+  return { surface: "/surface", target: null, inLibrary: false, drift: false, ...partial };
+}
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: () => {},
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json };
+}
+
+describe("where remediation + refresh + status drift (friction #6)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-rem-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "alpha"), { recursive: true });
+    await writeFile(join(library, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("--prune removes dead links only; copies stay manual", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(surface, { recursive: true });
+    await symlink(join(tmp, "gone"), join(surface, "deadlink"));
+    const dead = site({ name: "deadlink", path: join(surface, "deadlink"), kind: "dead" });
+    const copy = site({ name: "alpha", path: join(surface, "alpha"), kind: "copy", inLibrary: true, drift: false });
+
+    const outcomes = await remediate([dead, copy], library, { fix: false, dryRun: false });
+    expect(outcomes.find((o) => o.name === "deadlink")!.action).toBe("remove-dead");
+    expect(outcomes.find((o) => o.name === "deadlink")!.applied).toBe(true);
+    expect(existsSync(join(surface, "deadlink"))).toBe(false);
+    // under --prune a dedupe-able copy is left as manual
+    expect(outcomes.find((o) => o.name === "alpha")!.action).toBe("manual");
+  });
+
+  test("--fix dedupes a content-identical copy into a library symlink", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(join(surface, "alpha"), { recursive: true });
+    await writeFile(join(surface, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+    const copy = site({ name: "alpha", path: join(surface, "alpha"), kind: "copy", inLibrary: true, drift: false });
+
+    const outcomes = await remediate([copy], library, { fix: true, dryRun: false });
+    expect(outcomes[0]!.action).toBe("dedupe-copy");
+    expect(isSymlink(join(surface, "alpha"))).toBe(true);
+    expect(realpathOrSelf(join(surface, "alpha"))).toBe(realpathOrSelf(join(library, "alpha")));
+  });
+
+  test("--fix never auto-resolves a drifted copy or a foreign link", async () => {
+    const drifted = site({ name: "alpha", path: "/s/alpha", kind: "copy", inLibrary: true, drift: true });
+    const foreign = site({ name: "beta", path: "/s/beta", kind: "foreign-link", target: "/elsewhere" });
+    const outcomes = await remediate([drifted, foreign], library, { fix: true, dryRun: true });
+    expect(outcomes.every((o) => o.action === "manual")).toBe(true);
+    expect(outcomes.every((o) => !o.applied)).toBe(true);
+  });
+
+  test("--dry-run reports without mutating", async () => {
+    const surface = join(tmp, "surface");
+    await mkdir(surface, { recursive: true });
+    await symlink(join(tmp, "gone"), join(surface, "deadlink"));
+    const dead = site({ name: "deadlink", path: join(surface, "deadlink"), kind: "dead" });
+    const outcomes = await remediate([dead], library, { fix: true, dryRun: true });
+    expect(outcomes[0]!.applied).toBe(false);
+    expect(isSymlink(join(surface, "deadlink"))).toBe(true); // still there
+  });
+
+  test("refresh prunes a stale link whose library skill is gone, leaves foreign links", async () => {
+    const proj = join(tmp, "proj");
+    const skillsDir = join(proj, ".claude", "skills");
+    await mkdir(skillsDir, { recursive: true });
+    await symlink(join(library, "alpha"), join(skillsDir, "alpha")); // valid
+    await symlink(join(library, "ghost"), join(skillsDir, "ghost")); // dead, was-library
+    await symlink("/foreign/x", join(skillsDir, "foreign")); // foreign
+
+    const prev = process.cwd();
+    process.chdir(proj);
+    try {
+      const { ctx, json } = makeCtx(library);
+      await refreshRun(["--json"], ctx);
+      const out = json[0] as { outcomes: Array<{ name: string; action: string }> };
+      const by = Object.fromEntries(out.outcomes.map((o) => [o.name, o.action]));
+      expect(by.alpha).toBe("ok");
+      expect(by.ghost).toBe("pruned");
+      expect(by.foreign).toBe("foreign");
+      expect(existsSync(join(skillsDir, "ghost"))).toBe(false);
+      expect(isSymlink(join(skillsDir, "foreign"))).toBe(true);
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
+  test("a copy with identical body but a CUSTOMIZED description is drift, not dedupe-able", async () => {
+    // the load-bearing `description` differs while the body is byte-identical —
+    // `where --fix` must NOT silently replace it with a symlink (data loss).
+    const surface = join(tmp, "surface");
+    await mkdir(join(surface, "alpha"), { recursive: true });
+    await writeFile(
+      join(surface, "alpha", "SKILL.md"),
+      "---\nname: alpha\ndescription: CUSTOMIZED trigger text\n---\n\nbody\n", // same body, diff description
+    );
+    const lib = await loadLibrary(library);
+    const report = await inventoryDeployments([surface], library, lib);
+    const alpha = report.sites.find((s) => s.surface === surface && s.name === "alpha")!;
+    expect(alpha.kind).toBe("copy");
+    expect(alpha.drift).toBe(true); // description difference counts as drift
+    expect(remediationFor(alpha)).toBe("manual"); // never auto-deduped
+  });
+
+  test("status flags an unmanaged real copy (drift-prone)", async () => {
+    const proj = join(tmp, "proj2");
+    const skillsDir = join(proj, ".claude", "skills");
+    await mkdir(join(skillsDir, "realcopy"), { recursive: true });
+    await writeFile(join(skillsDir, "realcopy", "SKILL.md"), "---\nname: realcopy\n---\n\nx\n");
+
+    const prev = process.cwd();
+    process.chdir(proj);
+    try {
+      const { ctx, json } = makeCtx(library);
+      await statusRun(["--json"], ctx);
+      const out = json[0] as { unmanaged: Array<{ name: string }> };
+      expect(out.unmanaged.map((u) => u.name)).toContain("realcopy");
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

package/src/commands/rename.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm as fsRm, realpath, readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as renameRun } from "./rename.ts";
+import { loadLibrary } from "../core/library.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const errors: string[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    loadLibrary: () => loadLibrary(libraryPath),
+    log: () => {},
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json, errors };
+}
+
+describe("skl rename — atomic slug move (friction #5)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-rename-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "alpha"), { recursive: true });
+    await writeFile(join(library, "alpha", "SKILL.md"), "---\nname: alpha\ndescription: a\n---\n\nbody\n");
+    await writeFile(join(library, "taxonomy.json"), JSON.stringify({ version: 1, skills: { alpha: ["bio"] } }));
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({ version: 1, entries: { alpha: { name: "alpha", source: "github:o/r", ref: "x", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false } } }),
+    );
+  });
+  afterEach(async () => {
+    await fsRm(tmp, { recursive: true, force: true });
+  });
+
+  test("moves dir + frontmatter + taxonomy + lock together", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await renameRun(["alpha", "alpha2", "--json"], ctx);
+    expect(code).toBe(0);
+
+    expect(existsSync(join(library, "alpha"))).toBe(false);
+    expect(existsSync(join(library, "alpha2"))).toBe(true);
+
+    const fm = await readFile(join(library, "alpha2", "SKILL.md"), "utf8");
+    expect(fm).toContain("name: alpha2");
+
+    const tax = JSON.parse(await readFile(join(library, "taxonomy.json"), "utf8"));
+    expect(tax.skills.alpha2).toEqual(["bio"]);
+    expect(tax.skills.alpha).toBeUndefined();
+
+    const lock = JSON.parse(await readFile(join(library, "shelf.lock.json"), "utf8"));
+    expect(lock.entries.alpha2.name).toBe("alpha2");
+    expect(lock.entries.alpha).toBeUndefined();
+  });
+
+  test("refuses an existing target name", async () => {
+    await mkdir(join(library, "beta"), { recursive: true });
+    await writeFile(join(library, "beta", "SKILL.md"), "---\nname: beta\n---\n\nb\n");
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["alpha", "beta"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("already exists");
+  });
+
+  test("refuses a missing source", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["ghost", "x"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+  });
+
+  test("renames a RETIRED skill in place (stays under _retired/)", async () => {
+    // retire alpha by moving it into _retired/
+    await mkdir(join(library, "_retired"), { recursive: true });
+    const { rename: fsRename } = await import("node:fs/promises");
+    await fsRename(join(library, "alpha"), join(library, "_retired", "alpha"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await renameRun(["alpha", "alpha2", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { wasRetired: boolean }).wasRetired).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha2", "SKILL.md"))).toBe(true);
+    expect(existsSync(join(library, "_retired", "alpha"))).toBe(false);
+    expect(existsSync(join(library, "alpha2"))).toBe(false); // did NOT escape to active
+  });
+
+  test("refuses a path-traversal <old> name", async () => {
+    const victim = join(tmp, "victim");
+    await mkdir(victim, { recursive: true });
+    const { ctx, errors } = makeCtx(library);
+    const code = await renameRun(["../victim", "stolen"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("path separators");
+    expect(existsSync(victim)).toBe(true);
+    expect(existsSync(join(library, "stolen"))).toBe(false);
+  });
+
+  test("a LINKED entry rekeys metadata but leaves the dev-repo SKILL.md untouched", async () => {
+    const dev = join(tmp, "dev", "linked");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: linked\n---\n\nbody\n");
+    await symlink(dev, join(library, "linked"));
+
+    const { ctx, json } = makeCtx(library);
+    const code = await renameRun(["linked", "linked2", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { frontmatterRewritten: boolean }).frontmatterRewritten).toBe(false);
+    // dev-repo body is NOT rewritten (we must not edit the dev repo)
+    const devFm = await readFile(join(dev, "SKILL.md"), "utf8");
+    expect(devFm).toContain("name: linked");
+    // library symlink now lives under the new name, still resolving to the dev repo
+    expect(existsSync(join(library, "linked2", "SKILL.md"))).toBe(true);
+  });
+});

package/src/commands/rename.ts

@@ -0,0 +1,64 @@
+// `skl rename <old> <new>` (alias `skl mv`) — rename a skill's slug, moving every
+// coupled piece of state together in ONE op: the library dir, the SKILL.md
+// frontmatter `name:`, the taxonomy key, and the lockfile key. A hand `mv` alone
+// leaves a half-renamed skill (dir=new, frontmatter/taxonomy=old) — the exact
+// multi-file-consistency hazard the dogfood pass hit.
+//
+//   skl rename <old> <new> [--json]
+//
+// Does NOT repoint external deploy symlinks (they point at the old library path);
+// re-run `skl use` in affected projects (or `skl where` to find stragglers) after.
+
+import type { Ctx } from "../types.ts";
+import { renameSkill, reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "rename",
+  summary: "Rename a skill slug atomically (dir + frontmatter + taxonomy + lock)",
+  usage: "skl rename <old> <new> [--json]",
+} as const;
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const positional = argv.filter((a) => !a.startsWith("--"));
+  const unknownFlag = argv.find((a) => a.startsWith("--") && a !== "--json");
+  if (unknownFlag) {
+    ctx.error(`skl rename: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [from, to] = positional;
+  if (!from || !to) {
+    ctx.error("skl rename: an <old> and a <new> name are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!SLUG_RE.test(to)) {
+    ctx.error(`skl rename: invalid name "${to}" — use lowercase letters, digits, and hyphens`);
+    return 1;
+  }
+  if (from === to) {
+    ctx.error("skl rename: <old> and <new> are the same");
+    return 1;
+  }
+
+  try {
+    const result = await renameSkill(ctx.libraryPath, from, to);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) {
+      ctx.json({ ok: true, ...result });
+    } else {
+      ctx.log(`renamed ${from} -> ${to}`);
+      if (result.frontmatterRewritten) ctx.log("  rewrote SKILL.md frontmatter name:");
+      if (result.taxonomyMoved) ctx.log("  moved taxonomy entry");
+      if (result.lockMoved) ctx.log("  moved lockfile entry");
+      ctx.log("  note: deploy symlinks pointing at the old name are now stale — re-run `skl use` (or `skl where`).");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl rename: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}