skillshelf 0.2.0 → 0.3.0

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/unretire.ts

@@ -0,0 +1,33 @@
+// `skl unretire <name>` — restore a retired skill from <library>/_retired/<name>/
+// back to the active library. The inverse of `skl retire`.
+//
+//   skl unretire <name> [--json]
+
+import type { Ctx } from "../types.ts";
+import { unretireSkill, reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "unretire",
+  summary: "Restore a retired skill back to the active library",
+  usage: "skl unretire <name> [--json]",
+} as const;
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const json = argv.includes("--json");
+  const name = argv.find((a) => !a.startsWith("--"));
+  if (!name) {
+    ctx.error("skl unretire: a <name> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  try {
+    const dest = await unretireSkill(ctx.libraryPath, name);
+    await reindexLibrary(ctx.libraryPath);
+    if (json) ctx.json({ ok: true, name, restoredTo: dest });
+    else ctx.log(`unretired ${name} (active again)`);
+    return 0;
+  } catch (err) {
+    ctx.error(`skl unretire: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/untag.ts

@@ -0,0 +1,73 @@
+// `skl untag <name> <domain>` — remove ONE domain tag from a skill in the central
+// taxonomy.json (ADR-0002). The inverse of `skl tag`. Errors (does not silently
+// no-op) when the domain isn't a taxonomy tag — a typo'd untag should be visible —
+// and distinguishes a frontmatter-declared domain (which lives in the skill body,
+// not the taxonomy, and can't be removed here).
+//
+//   skl untag <name> <domain> [--json]
+
+import type { Ctx } from "../types.ts";
+import { findByName } from "../core/library.ts";
+import { readTaxonomy, domainsForName, removeDomainForName } from "../core/taxonomy.ts";
+import { reindexLibrary } from "../core/lifecycle.ts";
+
+export const meta = {
+  name: "untag",
+  summary: "Remove a domain tag from a skill in the central taxonomy",
+  usage: "skl untag <name> <domain> [--json]",
+} as const;
+
+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 untag: unknown argument: ${unknownFlag}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const [name, domain] = positional;
+  if (!name || !domain) {
+    ctx.error("skl untag: a <name> and a <domain> are required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  try {
+    const skills = await ctx.loadLibrary();
+    const skill = findByName(skills, name);
+    if (!skill) {
+      ctx.error(`skl untag: '${name}' is not in the library`);
+      return 1;
+    }
+
+    const removed = await removeDomainForName(ctx.libraryPath, name, domain);
+    if (!removed) {
+      // Distinguish "never had it" from "it's declared in SKILL.md frontmatter".
+      const tax = await readTaxonomy(ctx.libraryPath);
+      const inTaxonomy = domainsForName(tax, name).includes(domain);
+      if (!inTaxonomy && skill.domains.includes(domain)) {
+        ctx.error(
+          `skl untag: '${domain}' is declared in ${name}'s SKILL.md frontmatter, not the taxonomy — edit the skill body to remove it`,
+        );
+      } else {
+        ctx.error(`skl untag: '${name}' is not tagged '${domain}'`);
+      }
+      return 1;
+    }
+
+    await reindexLibrary(ctx.libraryPath);
+    const tax = await readTaxonomy(ctx.libraryPath);
+    const resulting = domainsForName(tax, name);
+    if (json) {
+      ctx.json({ ok: true, name, removed: domain, domains: resulting });
+    } else {
+      ctx.log(`untagged ${name} -= ${domain}`);
+      ctx.log(`  taxonomy domains: [${resulting.join(", ")}]`);
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl untag: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/update.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile, readFile, symlink, rm, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "./update.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 };
+}
+
+describe("skl update — LINKED entries are skipped (ADR-0004 safety)", () => {
+  let tmp: string;
+  let library: string;
+  let devRepo: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-update-")));
+    library = join(tmp, "library");
+    devRepo = join(tmp, "dev", "devskill");
+    await mkdir(library, { recursive: true });
+    await mkdir(devRepo, { recursive: true });
+    // The dev repo's canonical body — must NOT be clobbered by update.
+    await writeFile(join(devRepo, "SKILL.md"), "---\nname: devskill\n---\n\nDEV REPO BODY v1\n");
+    // library/devskill is a LINKED entry (symlink to the dev repo).
+    await symlink(devRepo, join(library, "devskill"));
+    // A STALE lockfile entry — as if devskill had once been a github import.
+    const lock = {
+      version: 1,
+      entries: {
+        devskill: {
+          name: "devskill",
+          source: "github:owner/repo",
+          ref: "0000000000000000000000000000000000000000",
+          channel: "github",
+          installedAt: "2020-01-01T00:00:00.000Z",
+          localEdits: false,
+        },
+      },
+    };
+    await writeFile(join(library, "shelf.lock.json"), JSON.stringify(lock, null, 2));
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("does not pull upstream into a LINKED dev repo", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["devskill", "--json"], ctx);
+
+    expect(code).toBe(0); // skipped is not an error
+    const report = json[0] as { results: Array<{ name: string; outcome: string; note: string }> };
+    const row = report.results.find((r) => r.name === "devskill")!;
+    expect(row.outcome).toBe("skipped");
+    expect(row.note).toContain("LINKED");
+
+    // The dev repo body is untouched — update never followed the symlink.
+    const body = await readFile(join(devRepo, "SKILL.md"), "utf8");
+    expect(body).toContain("DEV REPO BODY v1");
+  });
+});

package/src/commands/update.ts

@@ -1,7 +1,9 @@
 // skl update [name] — re-pull the upstream SKILL.md body for tracked skills.
 //
 // Invariants (the whole point of this command):
-//   - The overlay (<name>.shelf.json) is NEVER touched: taxonomy/bundles survive.
+//   - Domain tags are NEVER touched: they live in the central <library>/taxonomy.json
+//     (ADR-0002), which is separate from skill bodies, so re-pulling SKILL.md leaves
+//     every skill's domains intact. (There is no longer a per-skill overlay file.)
 //   - Only the upstream body (SKILL.md + bundled reference files) is replaced.
 //   - If the LOCAL body diverged from the previously-installed upstream (the user
 //     hand-edited it), DO NOT clobber. Show a diff and skip, unless --force.
@@ -11,7 +13,7 @@
 // to preview without writing; --force to overwrite diverged local edits.
 
 import { join, basename } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, type Dirent } from "node:fs";
 import { cp, rm, readdir } from "node:fs/promises";
 import type { Ctx, LockEntry } from "../types.ts";
 import { readLockfile, recordEntry } from "../core/provenance.ts";
@@ -24,11 +26,11 @@ import {
 } from "../core/fetch.ts";
 import { hashContent } from "../core/crawl.ts";
 import { parseFrontmatter } from "../lib/frontmatter.ts";
-import { loadLibrary, findByName } from "../core/library.ts";
+import { loadLibrary, findByName, entryMode } from "../core/library.ts";
 
 export const meta = {
   name: "update",
-  summary: "Re-pull upstream body, preserve overlay, diff if local body diverged",
+  summary: "Re-pull upstream body, preserve domain tags, diff if local body diverged",
   usage: "skl update [name] [--force] [--dry-run] [--json]",
 } as const;
 
@@ -50,11 +52,18 @@ function bodyOf(text: string): string {
   return parseFrontmatter(text).body;
 }
 
-/** Replace SKILL.md + bundled reference files from upstream; preserve overlay/lock. */
-async function applyUpstream(destDir: string, upstreamDir: string, name: string): Promise<void> {
-  const PRESERVE = new Set([`${name}.shelf.json`, "shelf.lock.json"]);
-  // Remove existing upstream-managed files (everything except overlay/lock/.git).
-  let entries: Awaited<ReturnType<typeof readdir>> = [];
+/**
+ * Replace SKILL.md + bundled reference files from upstream within a single skill
+ * dir. Domain tags and provenance are NOT stored inside the skill dir — the central
+ * taxonomy.json and shelf.lock.json both live at the LIBRARY ROOT (ADR-0002), never
+ * inside `destDir` — so the only thing to protect here is the skill's own `.git`.
+ * We still keep `shelf.lock.json`/`taxonomy.json` in the preserve set defensively,
+ * so a stray copy inside a skill dir is never deleted by this cleanup.
+ */
+async function applyUpstream(destDir: string, upstreamDir: string, _name: string): Promise<void> {
+  const PRESERVE = new Set(["shelf.lock.json", "taxonomy.json"]);
+  // Remove existing upstream-managed files (everything except lock/taxonomy/.git).
+  let entries: Dirent[] = [];
   try {
     entries = await readdir(destDir, { withFileTypes: true });
   } catch {
@@ -158,7 +167,8 @@ async function updateOne(
       };
     }
 
-    // Apply: replace body + ref files, preserve overlay/lock.
+    // Apply: replace body + ref files; domain tags + lock live at the library
+    // root (taxonomy.json / shelf.lock.json), untouched by this skill-dir cleanup.
     await applyUpstream(destDir, fetched.skillDir, entry.name);
 
     // Update lockfile ref + record the new installed body hash + clear localEdits
@@ -179,7 +189,7 @@ async function updateOne(
       fromRef: entry.ref,
       toRef: fetched.ref,
       outcome: "updated",
-      note: opts.force && localDiverged ? "overwrote diverged local body" : "upstream body re-pulled; overlay preserved",
+      note: opts.force && localDiverged ? "overwrote diverged local body" : "upstream body re-pulled; domain tags preserved",
     };
   } catch (err) {
     return {
@@ -208,23 +218,63 @@ export async function run(argv: string[], ctx: Ctx): Promise<number> {
     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) {
+    // Resolve on-disk dirs via the library so renames/domain folders are honored;
+    // also lets us surface LINKED skills that have NO lock entry (the normal `skl
+    // link --from` case) as positive 'skipped (linked)' evidence rather than silence.
+    const library = await loadLibrary(ctx.config.libraryPath);
+    const lockNames = new Set(entries.map((e) => e.name));
+    const linkedNoLock = library.filter(
+      (s) =>
+        !lockNames.has(s.name) &&
+        (!nameArg || s.name === nameArg) &&
+        entryMode(ctx.config.libraryPath, s.name) === "linked",
+    );
+
+    if (entries.length === 0 && linkedNoLock.length === 0) {
       if (json) ctx.json({ ok: true, updated: 0, diverged: 0, results: [] });
       else if (nameArg) ctx.error(`no tracked skill named "${nameArg}"`);
       else ctx.log("no tracked third-party skills (lockfile is empty)");
       return nameArg && !json ? 1 : 0;
     }
 
-    // Resolve on-disk dirs via the library so renames/domain folders are honored.
-    const library = await loadLibrary(ctx.config.libraryPath);
-
     const results: Result[] = [];
     for (const entry of entries) {
+      // LINKED entries (library/<name> is a symlink to an external dev repo) own their
+      // own versioning via their own git. Re-pulling upstream would follow the symlink
+      // and clobber the dev repo, so skip them outright (ADR-0004). A stale lock entry
+      // can exist if an OWNED import was later converted with `skl link --from --force`.
+      if (entryMode(ctx.config.libraryPath, entry.name) === "linked") {
+        results.push({
+          name: entry.name,
+          source: entry.source,
+          channel: entry.channel,
+          fromRef: entry.ref,
+          toRef: null,
+          outcome: "skipped",
+          note: "LINKED to a dev repo — its own git owns versioning; not pulling upstream",
+        });
+        continue;
+      }
       const skill = findByName(library, entry.name);
       const destDir = skill?.path ?? join(ctx.config.libraryPath, entry.name);
       results.push(await updateOne(ctx, entry, destDir, { force, dryRun }));
     }
 
+    // LINKED skills with no lock entry: report them as explicitly skipped so the
+    // never-clobber-a-dev-repo guarantee is visible, not silent.
+    for (const s of linkedNoLock) {
+      results.push({
+        name: s.name,
+        source: "(dev repo)",
+        channel: "local",
+        fromRef: "-",
+        toRef: null,
+        outcome: "skipped",
+        note: "LINKED to a dev repo — its own git owns versioning; not pulling upstream",
+      });
+    }
+    results.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
     const updated = results.filter((r) => r.outcome === "updated").length;
     const diverged = results.filter((r) => r.outcome === "diverged").length;
     const errored = results.filter((r) => r.outcome === "error").length;