skillshelf 0.2.0 → 0.4.0

package/src/commands/show.ts

@@ -1,28 +1,126 @@
-// `skl show <name>` — print ONLY the SKILL.md instruction layer (the body
-// after frontmatter) and list bundled reference-file paths. Reference file
-// CONTENTS are never printed; the agent Reads them on demand. Manual
-// progressive disclosure: cheap by default, deep on demand.
+// `skl show <name>` — print the SKILL.md instruction layer (the body after
+// frontmatter) and list the bundled reference files. By default only PATHS are
+// listed; the agent Reads them on demand (manual progressive disclosure: cheap
+// by default, deep on demand).
+//
+// `--file <relpath>` opens one bundled file: its CONTENTS are printed (or
+// carried in `--json` `body`). The path is resolved INSIDE the skill dir — any
+// attempt to escape it (`..`, absolute) is refused. This is what powers the
+// drawer's file navigator: one deterministic verb per file, code or prose.
 
+import { join, resolve, sep } from "node:path";
+import { readdir } from "node:fs/promises";
+import { existsSync, statSync, realpathSync } from "node:fs";
+import type { Dirent } from "node:fs";
 import type { Ctx, Skill } from "../types.ts";
-import { findByName } from "../core/library.ts";
+import { findByName, entryModeInfo } from "../core/library.ts";
 import { parseFrontmatter } from "../lib/frontmatter.ts";
 
 export const meta = {
   name: "show",
-  summary: "Print SKILL.md body; list reference-file paths (not contents)",
-  usage: "skl show <name> [--json]",
+  summary: "Print SKILL.md body; list (or open with --file) reference files",
+  usage: "skl show <name> [--file <relpath>] [--json]",
 } as const;
 
+const SKILL_FILE = "SKILL.md";
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+// Refuse to dump anything that smells binary or is too big to be a readable
+// reference. Keeps `--file` honest: it serves text, not blobs.
+const MAX_FILE_BYTES = 2_000_000;
+
 async function bodyOf(skill: Skill): Promise<string> {
   const raw = await Bun.file(skill.bodyPath).text();
   const { body, hasFrontmatter } = parseFrontmatter(raw);
   return hasFrontmatter ? body : raw;
 }
 
+/**
+ * Recursively enumerate every bundled file AND directory under the skill dir
+ * (absolute paths), excluding SKILL.md, the lock/sidecar, and VCS/noise dirs.
+ * Directory entries are emitted too so the UI can render a tree. Sorted so a
+ * directory always precedes its children (lexical: "ref" < "ref/x").
+ */
+async function walkRefFiles(
+  skillDir: string,
+  skillName: string,
+): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries: Dirent[];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.name === ".DS_Store") continue;
+      if (dir === skillDir) {
+        if (e.name === SKILL_FILE) continue;
+        if (e.name === `${skillName}.shelf.json`) continue;
+        if (e.name === "shelf.lock.json") continue;
+      }
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        out.push(abs);
+        await walk(abs);
+      } else {
+        out.push(abs);
+      }
+    }
+  }
+  await walk(skillDir);
+  return out.sort();
+}
+
+/**
+ * Resolve a user-supplied `--file` path INSIDE the skill dir. Returns the
+ * absolute path, or null if it escapes the dir / does not exist / is not a
+ * regular file / is too large.
+ */
+function resolveBundledFile(skillDir: string, rel: string): string | null {
+  const root = resolve(skillDir);
+  const abs = resolve(root, rel);
+  if (abs !== root && !abs.startsWith(root + sep)) return null; // lexical escape
+  if (!existsSync(abs)) return null;
+  const st = statSync(abs);
+  if (!st.isFile()) return null;
+  if (st.size > MAX_FILE_BYTES) return null;
+  // Symlink guard: a bundled file can be a symlink (third-party skills are
+  // untrusted) and the lexical check above is fooled by it (`statSync` follows
+  // links). Re-check the REAL paths — realpath BOTH, since the skill dir itself
+  // can sit under a symlinked component (e.g. macOS /var -> /private/var).
+  let realRoot: string;
+  let realAbs: string;
+  try {
+    realRoot = realpathSync(root);
+    realAbs = realpathSync(abs);
+  } catch {
+    return null;
+  }
+  if (realAbs !== realRoot && !realAbs.startsWith(realRoot + sep)) return null;
+  return abs;
+}
+
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
     const json = argv.includes("--json");
-    const positional = argv.filter((a) => !a.startsWith("--"));
+    let fileArg: string | undefined;
+    const positional: string[] = [];
+    for (let i = 0; i < argv.length; i++) {
+      const a = argv[i]!;
+      if (a === "--json") continue;
+      if (a === "--file") {
+        fileArg = argv[++i];
+        continue;
+      }
+      if (a.startsWith("--file=")) {
+        fileArg = a.slice("--file=".length);
+        continue;
+      }
+      if (a.startsWith("--")) continue;
+      positional.push(a);
+    }
     const name = positional[0];
 
     if (!name) {
@@ -37,9 +135,25 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       return 1;
     }
 
-    const body = await bodyOf(skill);
+    // Which file are we serving? SKILL.md (default) gets frontmatter stripped;
+    // any other bundled file is served verbatim.
+    const wantsFile = fileArg && fileArg !== SKILL_FILE && fileArg !== ".";
+    let body: string;
+    let file = SKILL_FILE;
+    if (wantsFile) {
+      const abs = resolveBundledFile(skill.path, fileArg!);
+      if (!abs) {
+        ctx.error(`No readable file "${fileArg}" in skill "${name}".`);
+        return 1;
+      }
+      body = await Bun.file(abs).text();
+      file = fileArg!;
+    } else {
+      body = await bodyOf(skill);
+    }
 
     if (json) {
+      const { mode, linkTarget } = entryModeInfo(ctx.libraryPath, skill.name);
       ctx.json({
         name: skill.name,
         description: skill.description,
@@ -47,17 +161,22 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         domains: skill.domains,
         path: skill.path,
         bodyPath: skill.bodyPath,
+        file,
         body,
-        refFiles: skill.refFiles,
+        refFiles: await walkRefFiles(skill.path, skill.name),
         retired: skill.retired,
         source: skill.source,
+        mode,
+        linkTarget,
       });
       return 0;
     }
 
     ctx.log(body.replace(/\n+$/, ""));
 
-    if (skill.refFiles.length) {
+    // The reference-file index is part of the SKILL.md view only; when a
+    // specific file is opened its contents are the whole output.
+    if (!wantsFile && skill.refFiles.length) {
       ctx.log("");
       ctx.log(`# Reference files (${skill.refFiles.length}) — Read on demand:`);
       for (const f of skill.refFiles) ctx.log(f);

package/src/commands/status.ts

@@ -4,6 +4,7 @@
 
 import { join } from "node:path";
 import type { Ctx, Skill } from "../types.ts";
+import { resolveReadTarget } from "../core/agents.ts";
 import {
   pathExists,
   isSymlink,
@@ -13,8 +14,8 @@ import {
 
 export const meta = {
   name: "status",
-  summary: "Which library skills are linked into ./.claude/skills",
-  usage: "skl status [--json]",
+  summary: "Which library skills are linked into an agent's project skills dir (default: ./.claude/skills)",
+  usage: "skl status [--agent <id>] [--project <dir>] [--json]",
 } as const;
 
 interface LinkedEntry {
@@ -26,21 +27,41 @@ interface LinkedEntry {
 
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
-    const json = argv.includes("--json");
-    const cwd = process.cwd();
-    const skillsDir = join(cwd, ".claude", "skills");
+    const rt = resolveReadTarget(argv);
+    if ("error" in rt) {
+      ctx.error(`skl status: ${rt.error}`);
+      ctx.error("usage: " + meta.usage);
+      return 1;
+    }
+    const json = rt.rest.includes("--json");
+    // --project <dir> / --agent <id> let status inspect the SAME dir `skl use
+    // --project … --agent …` wrote to; default stays the cwd project's .claude/skills.
+    const baseDir = rt.projectDir ?? process.cwd();
+    const agentId = rt.agentId ?? "claude";
+    const cwd = baseDir;
+    const skillsDir = join(baseDir, `.${agentId}`, "skills");
 
     const skills = await ctx.loadLibrary();
     // index library skills by their realpath for matching
     const byReal = new Map<string, Skill>();
     for (const s of skills) byReal.set(realpathOrSelf(s.path), s);
 
+    // index library skills by NAME too, to flag a real project copy that shadows a
+    // library skill (a drift-prone unmanaged copy — a symlink can't drift, a copy can).
+    const byName = new Map<string, Skill>(skills.map((s) => [s.name, s]));
+
     const linked: LinkedEntry[] = [];
+    const unmanaged: Array<{ name: string; inLibrary: boolean }> = [];
     if (pathExists(skillsDir)) {
       const names = await listDirNames(skillsDir);
       for (const name of names) {
         const linkPath = join(skillsDir, name);
-        if (!isSymlink(linkPath)) continue; // only count managed symlinks
+        if (!isSymlink(linkPath)) {
+          // a real (non-symlink) skill dir sitting in the project — unmanaged; if it
+          // shadows a library skill it is a drift-prone copy, not a clean deployment.
+          unmanaged.push({ name, inLibrary: byName.has(name) });
+          continue;
+        }
         const target = realpathOrSelf(linkPath);
         linked.push({
           link: name,
@@ -51,6 +72,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
       }
     }
     linked.sort((a, b) => (a.link < b.link ? -1 : a.link > b.link ? 1 : 0));
+    unmanaged.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
     // group resolved skills by bundle (domain tag) for the human summary
     const bundles = new Map<string, string[]>();
@@ -69,6 +91,7 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         skillsDir,
         skillsDirExists: pathExists(skillsDir),
         linkedCount: linked.length,
+        unmanaged,
         bundles: [...bundles.keys()].sort().map((name) => ({
           name,
           skills: bundles.get(name)!.slice().sort(),
@@ -78,13 +101,16 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
           target: e.target,
           skill: e.skill ? e.skill.name : null,
           inLibrary: e.skill != null,
+          // aliased: the link resolves to a library skill under a DIFFERENT name
+          // (a name-keyed blind spot — see `skl where --problems`).
+          aliased: e.skill != null && e.skill.name !== e.link,
           domains: e.skill ? e.skill.domains : [],
         })),
       });
       return 0;
     }
 
-    if (linked.length === 0) {
+    if (linked.length === 0 && unmanaged.length === 0) {
       ctx.log(`No skills linked into ${skillsDir}`);
       return 0;
     }
@@ -95,7 +121,8 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         const dom = e.skill.domains.length
           ? ` [${e.skill.domains.join(", ")}]`
           : "";
-        ctx.log(`  ${e.link}${dom} -> ${e.skill.name}`);
+        const alias = e.skill.name !== e.link ? "  ⚠ aliased (link name ≠ skill)" : "";
+        ctx.log(`  ${e.link}${dom} -> ${e.skill.name}${alias}`);
       } else {
         ctx.log(`  ${e.link} -> ${e.target} (not a library skill)`);
       }
@@ -109,6 +136,14 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
         ctx.log(`  ${name} (${members.length}): ${members.join(", ")}`);
       }
     }
+
+    if (unmanaged.length) {
+      ctx.log("");
+      ctx.log(`⚠ Unmanaged real copies (${unmanaged.length}) — not symlinks, can drift:`);
+      for (const u of unmanaged) {
+        ctx.log(`  ${u.name}${u.inLibrary ? " (shadows a library skill — `skl where --fix` to dedupe)" : ""}`);
+      }
+    }
     return 0;
   } catch (err) {
     ctx.error(`status failed: ${(err as Error).message}`);

package/src/commands/tag.test.ts

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run as tagRun } from "./tag.ts";
+import { run as untagRun } from "./untag.ts";
+import { run as retagRun } from "./retag.ts";
+import { loadLibrary } from "../core/library.ts";
+import { readTaxonomy } from "../core/taxonomy.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 };
+}
+
+async function writeSkill(library: string, name: string, frontmatterDomains?: string[]) {
+  const dir = join(library, name);
+  await mkdir(dir, { recursive: true });
+  const dom = frontmatterDomains ? `domains: [${frontmatterDomains.join(", ")}]\n` : "";
+  await writeFile(join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: ${name}\n${dom}---\n\nbody\n`);
+}
+
+describe("skl tag/untag/retag — surgical taxonomy edits (friction #4)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-tag-")));
+    library = join(tmp, "library");
+    await writeSkill(library, "alpha", ["bio"]); // bio is a FRONTMATTER domain
+    await writeSkill(library, "beta");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("tag adds new domains and reports already-present ones", async () => {
+    const { ctx, json } = makeCtx(library);
+    await tagRun(["alpha", "coding", "nlp", "--json"], ctx);
+    expect(json[0]).toMatchObject({ added: ["coding", "nlp"], already: [] });
+
+    const { ctx: c2, json: j2 } = makeCtx(library);
+    await tagRun(["alpha", "coding", "--json"], c2);
+    expect(j2[0]).toMatchObject({ added: [], already: ["coding"] });
+  });
+
+  test("tag refuses an unknown skill", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await tagRun(["ghost", "x"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+  });
+
+  test("untag removes a taxonomy domain", async () => {
+    const { ctx } = makeCtx(library);
+    await tagRun(["beta", "coding", "nlp"], ctx);
+    const { ctx: c2, json } = makeCtx(library);
+    const code = await untagRun(["beta", "coding", "--json"], c2);
+    expect(code).toBe(0);
+    expect(json[0]).toMatchObject({ removed: "coding", domains: ["nlp"] });
+  });
+
+  test("untag a frontmatter domain explains it can't be removed from the taxonomy", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await untagRun(["alpha", "bio"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("frontmatter");
+  });
+
+  test("untag a never-present domain errors (no silent no-op)", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await untagRun(["beta", "zzz"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not tagged");
+  });
+
+  test("retag renames a domain across the whole taxonomy deterministically", async () => {
+    const { ctx } = makeCtx(library);
+    await tagRun(["alpha", "ml"], ctx);
+    await tagRun(["beta", "ml"], makeCtx(library).ctx);
+
+    const { ctx: c3, json } = makeCtx(library);
+    const code = await retagRun(["ml", "machine-learning", "--json"], c3);
+    expect(code).toBe(0);
+    expect((json[0] as { changed: string[] }).changed.sort()).toEqual(["alpha", "beta"]);
+
+    const tax = await readTaxonomy(library);
+    expect(tax.skills.alpha).toContain("machine-learning");
+    expect(tax.skills.beta).toContain("machine-learning");
+    expect(tax.skills.alpha).not.toContain("ml");
+  });
+
+  test("retag a domain no skill carries is a clean no-op (changed:[])", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await retagRun(["nonexistent", "whatever", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { changed: string[] }).changed).toEqual([]);
+  });
+});

package/src/commands/tag.ts

@@ -0,0 +1,68 @@
+// `skl tag <name> <domain>...` — add one or more domain tags to a skill, surgically
+// and deterministically, in the central taxonomy.json (ADR-0002). The only other
+// taxonomy writer is the non-deterministic AI `infer` pass; this is the precise,
+// no-LLM edit for "give this one skill this one tag" that previously forced a
+// hand-edit of taxonomy.json (or a silently-failing frontmatter sed).
+//
+//   skl tag <name> <domain> [<domain>...] [--json]
+
+import type { Ctx } from "../types.ts";
+import { findByName } from "../core/library.ts";
+import { addDomainsForName } from "../core/taxonomy.ts";
+import { reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "tag",
+  summary: "Add domain tag(s) to a skill in the central taxonomy",
+  usage: "skl tag <name> <domain> [<domain>...] [--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 tag: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [name, ...domains] = positional;
+  if (!name || domains.length === 0) {
+    ctx.error("skl tag: a <name> and at least one <domain> are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const bad = domains.find((d) => !SLUG_RE.test(d));
+  if (bad) {
+    ctx.error(`skl tag: invalid domain "${bad}" — use lowercase letters, digits, and hyphens`);
+    return 1;
+  }
+
+  try {
+    const skills = await ctx.loadLibrary();
+    if (!findByName(skills, name)) {
+      ctx.error(`skl tag: '${name}' is not in the library`);
+      return 1;
+    }
+    const { added, already, domains: resulting } = await addDomainsForName(
+      ctx.libraryPath,
+      name,
+      domains,
+    );
+    if (added.length > 0) await reindexLibrary(ctx.libraryPath);
+
+    if (json) {
+      ctx.json({ ok: true, name, added, already, domains: resulting });
+    } else {
+      if (added.length > 0) ctx.log(`tagged ${name} += [${added.join(", ")}]`);
+      if (already.length > 0) ctx.log(`  (already had: ${already.join(", ")})`);
+      ctx.log(`  domains: [${resulting.join(", ")}]`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl tag: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/track.test.ts

@@ -0,0 +1,170 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, symlink, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import { run as trackRun } from "./track.ts";
+import { run as untrackRun } from "./untrack.ts";
+import { readLockfile } from "../core/provenance.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const logs: string[] = [];
+  const errors: string[] = [];
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: (...a: unknown[]) => logs.push(a.join(" ")),
+    error: (...a: unknown[]) => errors.push(a.join(" ")),
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, logs, errors, json };
+}
+
+function bodyHash(body: string): string {
+  return createHash("sha256").update(body, "utf8").digest("hex");
+}
+
+describe("skl track — adopt provenance offline", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-track-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "foo"), { recursive: true });
+    await writeFile(join(library, "foo", "SKILL.md"), "---\nname: foo\ndescription: a foo\n---\n\nBODY OF FOO\n");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("attaches an adopted lock entry with the local body hash and empty ref", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await trackRun(["foo", "--source", "github:owner/repo", "--json"], ctx);
+    expect(code).toBe(0);
+
+    const lock = await readLockfile(library);
+    const e = lock.entries.foo!;
+    expect(e.source).toBe("github:owner/repo");
+    expect(e.channel).toBe("github");
+    expect(e.ref).toBe("");
+    expect(e.adopted).toBe(true);
+    expect(e.localEdits).toBe(false);
+    const expectedBody = parseFrontmatter("---\nname: foo\ndescription: a foo\n---\n\nBODY OF FOO\n").body;
+    expect(e.installedHash).toBe(bodyHash(expectedBody));
+
+    const summary = json[0] as { adopted: boolean; ref: string };
+    expect(summary.adopted).toBe(true);
+  });
+
+  test("stores a github subpath in the add.ts @-convention and round-trips", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await trackRun(["foo", "--source", "github:owner/repo@skills/foo"], ctx);
+    expect(code).toBe(0);
+    const lock = await readLockfile(library);
+    expect(lock.entries.foo!.source).toBe("github:owner/repo@skills/foo");
+  });
+
+  test("--ref asserts the exact commit and clears adopted", async () => {
+    const { ctx } = makeCtx(library);
+    const code = await trackRun(["foo", "--source", "github:owner/repo", "--ref", "deadbeef"], ctx);
+    expect(code).toBe(0);
+    const e = (await readLockfile(library)).entries.foo!;
+    expect(e.ref).toBe("deadbeef");
+    expect(e.adopted).toBe(false);
+  });
+
+  test("refuses a skill not in the library, pointing at import/add", async () => {
+    const { ctx, errors } = makeCtx(library);
+    const code = await trackRun(["nope", "--source", "github:owner/repo"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("not in the library");
+    expect((await readLockfile(library)).entries.nope).toBeUndefined();
+  });
+
+  test("refuses a LINKED entry (dev repo owns versioning, ADR-0004)", async () => {
+    // Make a LINKED skill: library/bar -> external dev repo.
+    const dev = join(tmp, "dev", "bar");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: bar\ndescription: d\n---\n\nbody\n");
+    await symlink(dev, join(library, "bar"));
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await trackRun(["bar", "--source", "github:owner/repo"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("LINKED");
+    expect((await readLockfile(library)).entries.bar).toBeUndefined();
+  });
+
+  test("refuses an ALIASED LINKED entry where the symlink slug != frontmatter name", async () => {
+    // Regression for the linked-guard bypass: a dev repo linked as library/aka-dir but
+    // whose SKILL.md frontmatter name is `aka-name`. findByName matches the frontmatter
+    // name, but linked-ness must be resolved by the on-disk slug (basename of the path),
+    // or a LINKED skill slips the guard and `update` later clobbers the dev repo (ADR-0004).
+    const dev = join(tmp, "dev", "aka-dir");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: aka-name\ndescription: d\n---\n\nbody\n");
+    await symlink(dev, join(library, "aka-dir"));
+
+    const { ctx, errors } = makeCtx(library);
+    const code = await trackRun(["aka-name", "--source", "github:owner/repo"], ctx);
+    expect(code).toBe(1);
+    expect(errors.join("\n")).toContain("LINKED");
+    expect((await readLockfile(library)).entries["aka-name"]).toBeUndefined();
+    expect((await readLockfile(library)).entries["aka-dir"]).toBeUndefined();
+  });
+
+  test("refuses an existing lock entry without --force, allows with --force", async () => {
+    const { ctx } = makeCtx(library);
+    await trackRun(["foo", "--source", "github:owner/repo"], ctx);
+
+    const second = makeCtx(library);
+    const code = await trackRun(["foo", "--source", "github:other/repo"], second.ctx);
+    expect(code).toBe(1);
+    expect(second.errors.join("\n")).toContain("already");
+    // unchanged
+    expect((await readLockfile(library)).entries.foo!.source).toBe("github:owner/repo");
+
+    const third = makeCtx(library);
+    const fcode = await trackRun(["foo", "--source", "github:other/repo", "--force"], third.ctx);
+    expect(fcode).toBe(0);
+    expect((await readLockfile(library)).entries.foo!.source).toBe("github:other/repo");
+  });
+});
+
+describe("skl untrack — inverse of track, idempotent", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-untrack-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "foo"), { recursive: true });
+    await writeFile(join(library, "foo", "SKILL.md"), "---\nname: foo\ndescription: d\n---\n\nbody\n");
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("removes an existing entry", async () => {
+    const a = makeCtx(library);
+    await trackRun(["foo", "--source", "github:owner/repo"], a.ctx);
+    expect((await readLockfile(library)).entries.foo).toBeDefined();
+
+    const b = makeCtx(library);
+    const code = await untrackRun(["foo", "--json"], b.ctx);
+    expect(code).toBe(0);
+    expect((b.json[0] as { removed: boolean }).removed).toBe(true);
+    expect((await readLockfile(library)).entries.foo).toBeUndefined();
+  });
+
+  test("is a no-op (exit 0) when absent", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await untrackRun(["ghost", "--json"], ctx);
+    expect(code).toBe(0);
+    expect((json[0] as { removed: boolean }).removed).toBe(false);
+  });
+});