skillshelf 0.2.0 → 0.3.0

package/src/commands/link.ts

@@ -0,0 +1,317 @@
+// `skl link` — manage the symlink relationship between the library and on-disk copies.
+//
+// Two modes (the bookshelf model, ADR-0004):
+//
+//   skl link <name> --at <path>          OWNED side. The library already owns <name>; replace
+//                                        some other on-disk copy at <path> with a symlink INTO
+//                                        the library — fulfilling the one-canonical-copy rule for
+//                                        locations that were never consolidated (e.g. an old
+//                                        `.claude/skills/<name>` duplicate).
+//
+//   skl link [<name>] --from <dev-repo>  LINKED side. Register an external dev-repo skill as a
+//                                        library entry: make <library>/<name> a symlink pointing
+//                                        AT the dev repo, which stays canonical. The inverse of
+//                                        --at — the library shelves a reference instead of owning
+//                                        the bytes (for skills you actively develop in their own
+//                                        git repo). Name defaults to the dev-repo dir's basename.
+//
+//   --force   --at:   replace even if <path>'s body differs from the library copy (the divergent
+//                     copy is DISCARDED). Without it, a content mismatch is refused — pick a
+//                     winner: keep library (this, with --force) or make <path> canonical
+//                     (`skl import <name> --from <path> --force`).
+//             --from: replace an existing library entry (its current contents are DISCARDED).
+//   --json    machine-readable summary.
+//
+// Safety: --at never touches the library copy and refuses paths inside the library; --from
+// refuses a source inside the library; both verify the resulting symlink resolves as intended and
+// are idempotent when the link already points where intended.
+
+import { join, resolve, basename } from "node:path";
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import type { Ctx } from "../types.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import { removeEntry } from "../core/provenance.ts";
+import {
+  isDirectory,
+  isSymlink,
+  safeSymlink,
+  realpathOrSelfAsync,
+} from "../lib/fs.ts";
+
+export const meta = {
+  name: "link",
+  summary: "Link a skill to the library: collapse a copy (--at) or shelve a dev repo (--from)",
+  usage: "skl link <name> --at <path>  |  skl link [<name>] --from <dev-repo>  [--force] [--json]",
+} as const;
+
+interface Flags {
+  name: string | null;
+  at: string | null;
+  from: string | null;
+  force: boolean;
+  json: boolean;
+}
+
+function parseFlags(argv: string[]): { flags: Flags } | { error: string } {
+  const flags: Flags = { name: null, at: null, from: null, force: false, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--at") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--at requires a <path>" };
+      flags.at = v;
+    } else if (a.startsWith("--at=")) {
+      flags.at = a.slice("--at=".length);
+    } else if (a === "--from") {
+      const v = argv[++i];
+      if (v === undefined) return { error: "--from requires a <dev-repo path>" };
+      flags.from = v;
+    } else if (a.startsWith("--from=")) {
+      flags.from = a.slice("--from=".length);
+    } else if (a === "--force") {
+      flags.force = true;
+    } else if (a === "--json") {
+      flags.json = true;
+    } else if (a.startsWith("--")) {
+      return { error: `unknown argument: ${a}` };
+    } else if (flags.name === null) {
+      flags.name = a;
+    } else {
+      return { error: `unexpected argument: ${a}` };
+    }
+  }
+  return { flags };
+}
+
+/** sha-256 of a SKILL.md body (frontmatter stripped) — matches crawl/dedupe hashing. */
+async function bodyHash(skillMdPath: string): Promise<string | null> {
+  if (!existsSync(skillMdPath)) return null;
+  try {
+    const raw = await Bun.file(skillMdPath).text();
+    const { body } = parseFrontmatter(raw);
+    return createHash("sha256").update(body, "utf8").digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+export async function run(argv: string[], ctx: Ctx): Promise<number> {
+  const parsed = parseFlags(argv);
+  if ("error" in parsed) {
+    ctx.error(`skl link: ${parsed.error}`);
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  const flags = parsed.flags;
+
+  if (flags.at && flags.from) {
+    ctx.error("skl link: --at and --from are mutually exclusive (collapse a copy vs. shelve a dev repo)");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+  if (!flags.at && !flags.from) {
+    ctx.error("skl link: one of --at <path> or --from <dev-repo> is required");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  return flags.from
+    ? await runFrom(flags, ctx)
+    : await runAt(flags, ctx);
+}
+
+/**
+ * LINKED mode: register an external dev-repo skill as a library symlink. The library entry
+ * <library>/<name> becomes a symlink pointing AT the dev repo (which stays canonical).
+ */
+async function runFrom(flags: Flags, ctx: Ctx): Promise<number> {
+  const fromPath = resolve(flags.from!.trim());
+  const name = (flags.name?.trim()) || basename(fromPath);
+  if (!name || name === "." || name === "/") {
+    ctx.error("skl link: could not determine a <name> — pass one explicitly");
+    return 1;
+  }
+  const libraryPath = ctx.config.libraryPath;
+  const libDir = join(libraryPath, name);
+
+  try {
+    // The source must be a real skill dir (has a SKILL.md).
+    if (!existsSync(fromPath) || !(await isDirectory(fromPath))) {
+      ctx.error(`skl link: --from must be an existing directory: ${fromPath}`);
+      return 1;
+    }
+    if (!existsSync(join(fromPath, "SKILL.md"))) {
+      ctx.error(`skl link: ${fromPath} has no SKILL.md (not a skill dir).`);
+      return 1;
+    }
+
+    // Refuse a source inside the library — that would link the library to itself.
+    const fromReal = await realpathOrSelfAsync(fromPath);
+    const libRoot = await realpathOrSelfAsync(libraryPath);
+    if (fromReal === libRoot || fromReal.startsWith(libRoot + "/")) {
+      ctx.error(`skl link: --from is inside the library (${fromPath}) — nothing to register`);
+      return 1;
+    }
+
+    // Idempotent: library entry is already a symlink resolving to this source.
+    if (isSymlink(libDir)) {
+      const cur = await realpathOrSelfAsync(libDir);
+      if (cur === fromReal) {
+        const summary = { ok: true, name, from: fromPath, to: libDir, status: "already" as const, mode: "linked" as const, discarded: false };
+        if (flags.json) ctx.json(summary);
+        else ctx.log(`link: library/${name} already points at ${fromPath}`);
+        return 0;
+      }
+    }
+
+    // An existing library entry won't be clobbered silently.
+    const exists = existsSync(libDir) || isSymlink(libDir);
+    if (exists && !flags.force) {
+      ctx.error(`skl link: '${name}' already exists in the library (${libDir}).`);
+      ctx.error("Pass --force to replace it with a symlink to the dev repo (its current contents are discarded).");
+      return 1;
+    }
+    const discarded = exists && !isSymlink(libDir); // a real OWNED copy is being dropped
+    if (exists) await rm(libDir, { recursive: true, force: true });
+    await safeSymlink(fromPath, libDir, { force: true });
+
+    // Verify the library entry resolves to the dev repo.
+    const linkReal = await realpathOrSelfAsync(libDir);
+    if (linkReal !== fromReal) {
+      ctx.error(`skl link: verification failed — library/${name} resolves to ${linkReal}, expected ${fromReal}`);
+      return 1;
+    }
+
+    // A LINKED entry is not a tracked github import — drop any stale lock entry so
+    // `skl update`/`outdated` never try to pull upstream into the dev repo (ADR-0004).
+    await removeEntry(libraryPath, name);
+
+    const summary = { ok: true, name, from: fromPath, to: libDir, status: "linked" as const, mode: "linked" as const, discarded };
+    if (flags.json) {
+      ctx.json(summary);
+    } else {
+      ctx.log(`shelved ${name} -> ${fromPath} (LINKED)`);
+      if (discarded) ctx.log("  (discarded the previous owned library copy; library now points at the dev repo)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl link: failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}
+
+/**
+ * OWNED mode: replace a redundant on-disk copy at <path> with a symlink INTO the library copy
+ * the library already owns.
+ */
+async function runAt(flags: Flags, ctx: Ctx): Promise<number> {
+  if (!flags.name || flags.name.trim() === "") {
+    ctx.error("skl link: a <name> is required with --at");
+    ctx.error(`usage: ${meta.usage}`);
+    return 1;
+  }
+
+  const name = flags.name.trim();
+  const atPath = resolve(flags.at!.trim());
+  const libraryPath = ctx.config.libraryPath;
+  const libDir = join(libraryPath, name);
+
+  try {
+    // The library must already own this skill — link points AT the canonical copy.
+    if (!existsSync(libDir) || !existsSync(join(libDir, "SKILL.md"))) {
+      ctx.error(
+        `skl link: '${name}' is not in the library (${libDir}). Import it first with \`skl import\`.`,
+      );
+      return 1;
+    }
+
+    const libReal = await realpathOrSelfAsync(libDir);
+
+    // Idempotent: already a symlink resolving to the library copy.
+    if (isSymlink(atPath)) {
+      const cur = await realpathOrSelfAsync(atPath);
+      if (cur === libReal) {
+        const summary = { ok: true, name, at: atPath, to: libDir, status: "already" as const, discarded: false };
+        if (flags.json) ctx.json(summary);
+        else ctx.log(`link: ${atPath} already points at the library copy of ${name}`);
+        return 0;
+      }
+    }
+
+    // Safety: never operate on the library copy itself or anything inside the library.
+    const atReal = await realpathOrSelfAsync(atPath);
+    if (atReal === libReal) {
+      ctx.error(`skl link: --at is the library copy itself (${atPath}) — nothing to do`);
+      return 1;
+    }
+    const libRoot = await realpathOrSelfAsync(libraryPath);
+    if (atReal === libRoot || atReal.startsWith(libRoot + "/")) {
+      ctx.error(`skl link: refusing to operate on a path inside the library (${atPath})`);
+      return 1;
+    }
+
+    // If the target exists as a real dir, require it to look like a skill and compare
+    // content. A body mismatch means a real decision the tool won't make silently.
+    if (existsSync(atPath) && !isSymlink(atPath)) {
+      if (!(await isDirectory(atPath))) {
+        ctx.error(`skl link: --at must be a directory (the redundant copy): ${atPath}`);
+        return 1;
+      }
+      const atSkillMd = join(atPath, "SKILL.md");
+      if (!existsSync(atSkillMd) && !flags.force) {
+        ctx.error(
+          `skl link: ${atPath} has no SKILL.md (not a skill dir). Pass --force to replace it anyway.`,
+        );
+        return 1;
+      }
+      if (existsSync(atSkillMd) && !flags.force) {
+        const [a, b] = await Promise.all([
+          bodyHash(atSkillMd),
+          bodyHash(join(libDir, "SKILL.md")),
+        ]);
+        if (a !== b) {
+          ctx.error(
+            `skl link: ${atPath} differs from the library copy of '${name}'.`,
+          );
+          ctx.error(
+            "Pass --force to discard the divergent copy and replace it with a symlink,",
+          );
+          ctx.error(
+            `or make this copy canonical instead: \`skl import ${name} --from ${atPath} --force\`.`,
+          );
+          return 1;
+        }
+      }
+    }
+
+    // Replace the redundant copy with a symlink into the library.
+    const discarded = existsSync(atPath) && !isSymlink(atPath);
+    if (existsSync(atPath) || isSymlink(atPath)) {
+      await rm(atPath, { recursive: true, force: true });
+    }
+    await safeSymlink(libDir, atPath, { force: true });
+
+    // Verify the link resolves to the library copy.
+    const linkReal = await realpathOrSelfAsync(atPath);
+    if (linkReal !== libReal) {
+      ctx.error(
+        `skl link: verification failed — ${atPath} resolves to ${linkReal}, expected ${libReal}`,
+      );
+      return 1;
+    }
+
+    const summary = { ok: true, name, at: atPath, to: libDir, status: "linked" as const, discarded };
+    if (flags.json) {
+      ctx.json(summary);
+    } else {
+      ctx.log(`linked ${basename(atPath)} -> ${libDir}`);
+      if (discarded) ctx.log("  (discarded the redundant copy; old path now resolves to the library)");
+    }
+    return 0;
+  } catch (err) {
+    ctx.error(`skl link: failed: ${err instanceof Error ? err.message : String(err)}`);
+    return 1;
+  }
+}

package/src/commands/ls.ts

@@ -1,16 +1,49 @@
 // `skl ls [bundle]` — one-line listing of the whole library, or a single
 // bundle (tag query). Excludes retired by default; `--all` includes them.
 
+import { statSync } from "node:fs";
 import type { Ctx, Skill } from "../types.ts";
-import { activeSkills } from "../core/library.ts";
+import { activeSkills, entryModeInfo } from "../core/library.ts";
 import { resolveBundle } from "../core/bundle.ts";
+import { inventoryDeployments } from "../core/deployments.ts";
+import { knownAgentSurfacePaths } from "../core/surfaces.ts";
+import { isCleanSite } from "../core/agents.ts";
 
 export const meta = {
   name: "ls",
   summary: "One-line listing of the library, or one bundle",
-  usage: "skl ls [bundle] [--all] [--json]",
+  usage: "skl ls [bundle] [--all] [--sort modified|name|domain|deploys|source] [--json]",
 } as const;
 
+const SORT_FIELDS = ["modified", "name", "domain", "deploys", "source"] as const;
+type SortField = (typeof SORT_FIELDS)[number];
+
+/** Sort a copy of skills by a report field (modified/deploys descending). */
+function sortSkills(skills: Skill[], field: SortField, deployCounts: Map<string, number>): Skill[] {
+  const primary = (s: Skill) => s.primaryDomain ?? s.domains[0] ?? "_unclassified";
+  const mtimes =
+    field === "modified" ? new Map(skills.map((s) => [s.name, fileTimes(s.bodyPath).modifiedAt])) : null;
+  return skills.slice().sort((a, b) => {
+    if (field === "name") return a.name.localeCompare(b.name);
+    if (field === "domain") return primary(a).localeCompare(primary(b)) || a.name.localeCompare(b.name);
+    if (field === "source") {
+      const sa = a.source ? "vendored" : "local";
+      const sb = b.source ? "vendored" : "local";
+      return sa.localeCompare(sb) || a.name.localeCompare(b.name);
+    }
+    if (field === "deploys") {
+      return (deployCounts.get(b.name) ?? 0) - (deployCounts.get(a.name) ?? 0) || a.name.localeCompare(b.name);
+    }
+    // modified — most-recent first; null/untracked last.
+    const am = mtimes!.get(a.name) ?? null;
+    const bm = mtimes!.get(b.name) ?? null;
+    if (!am && !bm) return a.name.localeCompare(b.name);
+    if (!am) return 1;
+    if (!bm) return -1;
+    return bm.localeCompare(am);
+  });
+}
+
 function oneLine(desc: string, max = 100): string {
   const flat = desc.replace(/\s+/g, " ").trim();
   return flat.length <= max ? flat : flat.slice(0, max - 1).trimEnd() + "…";
@@ -29,46 +62,113 @@ function emitHuman(ctx: Ctx, skills: Skill[]): void {
   }
 }
 
-function toJson(skills: Skill[]): unknown {
-  return skills.map((s) => ({
-    name: s.name,
-    description: s.description,
-    primaryDomain: s.primaryDomain,
-    domains: s.domains,
-    path: s.path,
-    retired: s.retired,
-  }));
+/** Stat-derived timestamps for a skill's SKILL.md (ISO-8601), null if unavailable. */
+function fileTimes(bodyPath: string): { modifiedAt: string | null; createdAt: string | null } {
+  try {
+    const st = statSync(bodyPath);
+    const created = st.birthtimeMs > 0 ? st.birthtime : null;
+    return {
+      modifiedAt: st.mtime.toISOString(),
+      createdAt: created ? created.toISOString() : null,
+    };
+  } catch {
+    return { modifiedAt: null, createdAt: null };
+  }
+}
+
+function toJson(
+  skills: Skill[],
+  libraryPath: string,
+  deployCounts: Map<string, number>,
+): unknown {
+  return skills.map((s) => {
+    const { mode, linkTarget } = entryModeInfo(libraryPath, s.name);
+    const { modifiedAt, createdAt } = fileTimes(s.bodyPath);
+    return {
+      name: s.name,
+      description: s.description,
+      primaryDomain: s.primaryDomain,
+      domains: s.domains,
+      path: s.path,
+      retired: s.retired,
+      mode,
+      linkTarget,
+      // ADR-0008 §7.1 additions: a string source (UI maps "vendored"/"local"),
+      // stat timestamps, and the count of clean deployment sites.
+      source: s.source ? "vendored" : "local",
+      modifiedAt,
+      createdAt,
+      deployCount: deployCounts.get(s.name) ?? 0,
+    };
+  });
+}
+
+/** Count clean (`linked`) deployment sites per skill across all surfaces. */
+async function deployCountsFor(ctx: Ctx, lib: Skill[]): Promise<Map<string, number>> {
+  const counts = new Map<string, number>();
+  try {
+    const surfaces = [...ctx.roots, ctx.config.globalCoreTarget, ...knownAgentSurfacePaths()];
+    const report = await inventoryDeployments(surfaces, ctx.libraryPath, lib);
+    for (const site of report.sites) {
+      // "clean" = the ✓ states in `skl where` (linked OR canonical source), shared
+      // with the agents matrix via isCleanSite so the Deploys column agrees with it.
+      if (isCleanSite(site)) counts.set(site.name, (counts.get(site.name) ?? 0) + 1);
+    }
+  } catch {
+    // deployment scan is best-effort enrichment; ls still returns the library.
+  }
+  return counts;
 }
 
 export async function run(argv: string[], ctx: Ctx): Promise<number> {
   try {
     const json = argv.includes("--json");
     const all = argv.includes("--all");
-    const positional = argv.filter((a) => !a.startsWith("--"));
+    // Extract `--sort <field>` and its value so the value isn't taken as a bundle.
+    const sortIdx = argv.indexOf("--sort");
+    const sortField = sortIdx >= 0 ? argv[sortIdx + 1] : undefined;
+    if (sortField !== undefined && !SORT_FIELDS.includes(sortField as SortField)) {
+      ctx.error(`ls: --sort expects one of: ${SORT_FIELDS.join(", ")}`);
+      return 1;
+    }
+    const consumed = new Set<number>();
+    if (sortIdx >= 0) {
+      consumed.add(sortIdx);
+      consumed.add(sortIdx + 1);
+    }
+    const positional = argv.filter((a, i) => !a.startsWith("--") && !consumed.has(i));
     const bundleName = positional[0];
 
     const skills = await ctx.loadLibrary();
+    // deployCounts needed for --json, or to sort by deploys.
+    const deployCounts =
+      json || sortField === "deploys"
+        ? await deployCountsFor(ctx, skills)
+        : new Map<string, number>();
+    const applySort = (list: Skill[]) =>
+      sortField ? sortSkills(list, sortField as SortField, deployCounts) : list;
 
     if (bundleName) {
       const bundle = await resolveBundle(skills, bundleName, {
         includeRetired: all,
       });
+      const rows = applySort(bundle.skills);
       if (json) {
-        ctx.json({ bundle: bundle.name, skills: toJson(bundle.skills) });
+        ctx.json({ bundle: bundle.name, skills: toJson(rows, ctx.libraryPath, deployCounts) });
         return 0;
       }
-      if (bundle.skills.length === 0) {
+      if (rows.length === 0) {
         ctx.log(`Bundle "${bundle.name}" has no skills.`);
         return 0;
       }
-      ctx.log(`# ${bundle.name} (${bundle.skills.length})`);
-      emitHuman(ctx, bundle.skills);
+      ctx.log(`# ${bundle.name} (${rows.length})`);
+      emitHuman(ctx, rows);
       return 0;
     }
 
-    const listed = all ? skills : activeSkills(skills);
+    const listed = applySort(all ? skills : activeSkills(skills));
     if (json) {
-      ctx.json(toJson(listed));
+      ctx.json(toJson(listed, ctx.libraryPath, deployCounts));
       return 0;
     }
     emitHuman(ctx, listed);

package/src/commands/mode-surfacing.test.ts

@@ -0,0 +1,110 @@
+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 { run as lsRun } from "./ls.ts";
+import { run as outdatedRun } from "./outdated.ts";
+import { run as updateRun } from "./update.ts";
+import { loadLibrary } from "../core/library.ts";
+import { hashContent } from "../core/crawl.ts";
+import { parseFrontmatter } from "../lib/frontmatter.ts";
+import type { Ctx } from "../types.ts";
+
+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("owned-vs-linked surfacing (friction #7)", () => {
+  let tmp: string;
+  let library: string;
+  let dev: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-mode-")));
+    library = join(tmp, "library");
+    await mkdir(join(library, "owned1"), { recursive: true });
+    await writeFile(join(library, "owned1", "SKILL.md"), "---\nname: owned1\ndescription: o\n---\n\nbody\n");
+    dev = join(tmp, "dev", "devskill");
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: devskill\ndescription: d\n---\n\nbody\n");
+    await symlink(dev, join(library, "devskill"));
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("ls --json carries mode + linkTarget", async () => {
+    const { ctx, json } = makeCtx(library);
+    await lsRun(["--all", "--json"], ctx);
+    const rows = json[0] as Array<{ name: string; mode: string; linkTarget: string | null }>;
+    const owned = rows.find((r) => r.name === "owned1")!;
+    const linked = rows.find((r) => r.name === "devskill")!;
+    expect(owned.mode).toBe("owned");
+    expect(owned.linkTarget).toBeNull();
+    expect(linked.mode).toBe("linked");
+    expect(linked.linkTarget).toBe(dev);
+  });
+
+  test("outdated surfaces a LINKED skill that has NO lock entry", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--json"], ctx);
+    expect(code).toBe(0);
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "devskill")!.status).toBe("linked");
+  });
+
+  test("update reports a LINKED skill (no lock entry) as explicitly skipped", async () => {
+    const { ctx, json } = makeCtx(library);
+    await updateRun(["devskill", "--json"], ctx);
+    const results = (json[0] as { results: Array<{ name: string; outcome: string }> }).results;
+    expect(results.find((r) => r.name === "devskill")!.outcome).toBe("skipped");
+  });
+
+  test("outdated --check-local flags local divergence offline (no network)", async () => {
+    // owned1 tracked with an installedHash that does NOT match the local body.
+    const localBody = parseFrontmatter("---\nname: owned1\n---\n\nbody\n").body;
+    const staleHash = hashContent(localBody + "DIFFERENT");
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          owned1: { name: "owned1", source: "github:o/r", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false, installedHash: staleHash },
+        },
+      }),
+    );
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--check-local", "--json"], ctx);
+    expect(code).toBe(2); // diverged -> non-zero
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "owned1")!.status).toBe("diverged");
+  });
+
+  test("outdated --check-local reports a matching baseline as current (offline)", async () => {
+    const localBody = parseFrontmatter("---\nname: owned1\n---\n\nbody\n").body;
+    const matchHash = hashContent(localBody);
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          owned1: { name: "owned1", source: "github:o/r", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false, installedHash: matchHash },
+        },
+      }),
+    );
+    const { ctx, json } = makeCtx(library);
+    const code = await outdatedRun(["--check-local", "--json"], ctx);
+    expect(code).toBe(0);
+    const rows = (json[0] as { rows: Array<{ name: string; status: string }> }).rows;
+    expect(rows.find((r) => r.name === "owned1")!.status).toBe("current");
+  });
+});

package/src/commands/outdated.test.ts

@@ -0,0 +1,55 @@
+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 { run } from "./outdated.ts";
+import type { Ctx } from "../types.ts";
+
+function makeCtx(libraryPath: string) {
+  const json: unknown[] = [];
+  const ctx = {
+    config: { libraryPath },
+    libraryPath,
+    log: () => {},
+    error: () => {},
+    json: (v: unknown) => json.push(v),
+  } as unknown as Ctx;
+  return { ctx, json };
+}
+
+describe("skl outdated — LINKED entries are reported, not probed (ADR-0004)", () => {
+  let tmp: string;
+  let library: string;
+
+  beforeEach(async () => {
+    tmp = await realpath(await mkdtemp(join(tmpdir(), "skl-outdated-")));
+    library = join(tmp, "library");
+    const dev = join(tmp, "dev", "devskill");
+    await mkdir(library, { recursive: true });
+    await mkdir(dev, { recursive: true });
+    await writeFile(join(dev, "SKILL.md"), "---\nname: devskill\n---\n\nbody\n");
+    await symlink(dev, join(library, "devskill"));
+    await writeFile(
+      join(library, "shelf.lock.json"),
+      JSON.stringify({
+        version: 1,
+        entries: {
+          devskill: { name: "devskill", source: "github:owner/repo", ref: "abc", channel: "github", installedAt: "2020-01-01T00:00:00.000Z", localEdits: false },
+        },
+      }),
+    );
+  });
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("a LINKED entry is status 'linked', never counted stale", async () => {
+    const { ctx, json } = makeCtx(library);
+    const code = await run(["--json"], ctx);
+
+    expect(code).toBe(0); // not stale -> exit 0 (no network probe of the dead github ref)
+    const report = json[0] as { stale: number; rows: Array<{ name: string; status: string }> };
+    expect(report.stale).toBe(0);
+    expect(report.rows.find((r) => r.name === "devskill")!.status).toBe("linked");
+  });
+});