@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/shared/assertExecOk.ts

@@ -0,0 +1,106 @@
+/**
+ * Guard an `exec`-composing Task against a silently-swallowed nonzero exit.
+ *
+ * The `@canonical/task` interpreter RESOLVES the `exec` effect on a nonzero exit
+ * code — it only REJECTS on a spawn error (e.g. ENOENT). A consumer that yields
+ * `exec` and ignores `ExecResult.exitCode` therefore reports a failed command
+ * (the common case being an EACCES-denied global `npm i -g`) as a silent
+ * success, discarding the subprocess's own stderr. Every `exec` consumer in
+ * `next/src` (`upgrade`, `setup lsp`) calls this immediately after its `exec`
+ * yield, so a failed subprocess surfaces as UNSUPPORTED (exit 1) carrying the
+ * command and the captured stderr instead of being reported as done.
+ *
+ * A denied `npm i -g` (EACCES), a registry/network failure, or any other
+ * nonzero exit is a fixable ENVIRONMENT condition — NOT a pragma bug — so it is
+ * classified UNSUPPORTED with an actionable recovery, never INTERNAL_ERROR's
+ * "please report this issue". (A spawn error like ENOENT REJECTS the effect
+ * instead of resolving, so it never reaches here.)
+ */
+
+import { type ExecResult, fail, recover, type Task } from "@canonical/task";
+import { PragmaError } from "../../kernel/error/PragmaError.js";
+import type { Recovery } from "../../kernel/error/types.js";
+
+/**
+ * Raise UNSUPPORTED when an `exec` result carries a nonzero exit code.
+ *
+ * @param command - Human-readable command, surfaced in the error message.
+ * @param result - The {@link ExecResult} the `exec` effect yielded.
+ * @throws PragmaError UNSUPPORTED (exit 1) when `result.exitCode !== 0`,
+ *   including the trimmed stderr when the subprocess emitted any, plus an
+ *   actionable recovery (a permissions/network failure the user can retry).
+ */
+export function assertExecOk(command: string, result: ExecResult): void {
+  if (result.exitCode === 0) return;
+  const stderr = result.stderr.trim();
+  throw new PragmaError({
+    code: "UNSUPPORTED",
+    message: `\`${command}\` exited with code ${result.exitCode}.${
+      stderr ? `\n${stderr}` : ""
+    }`,
+    recovery: {
+      message:
+        "The command failed — often a permissions or network issue. Check the output above and retry (for a global install, try elevated privileges).",
+    },
+  });
+}
+
+/**
+ * True when a rejected/normalised `exec` error is a missing-binary spawn failure.
+ *
+ * A spawn `ENOENT` (the command is absent from PATH) REJECTS the `exec` effect —
+ * unlike a nonzero exit, which RESOLVES it (see {@link assertExecOk}). The task
+ * interpreter normalises that reject into a `FILE_NOT_FOUND` TaskError carrying
+ * the raw spawn error as `.cause`, so this unwraps one level to recognise both
+ * the raw and normalised shapes.
+ *
+ * @param error - The thrown/rejected value (raw spawn error or its TaskError).
+ * @returns Whether it denotes a binary missing from PATH.
+ */
+export function isMissingBinaryError(error: unknown): boolean {
+  const codeOf = (value: unknown): unknown =>
+    value && typeof value === "object" && "code" in value
+      ? (value as { code: unknown }).code
+      : undefined;
+  if (codeOf(error) === "ENOENT") return true;
+  const cause = (error as { cause?: unknown } | null | undefined)?.cause;
+  return codeOf(cause) === "ENOENT";
+}
+
+/**
+ * Wrap an `exec`-composing Task so a missing-binary spawn (ENOENT) surfaces as a
+ * named UNSUPPORTED "`<bin>` not found on PATH" error with actionable recovery,
+ * rather than the interpreter's raw reject collapsing to INTERNAL_ERROR ("please
+ * report this issue") at the CLI/MCP boundary. Every spawn site that may hit an
+ * absent binary (`upgrade`'s package manager, `setup lsp`'s `bunx`) wraps its
+ * Task with this so they never reach the catch-all.
+ *
+ * Only real execution can trip it: a dry-run/plan mocks `exec` (exit 0, no
+ * spawn), so the guard is transparent to the preview. A nonzero exit RESOLVES
+ * the effect and is still {@link assertExecOk}'s job (its throw is a synchronous
+ * generator-body throw, not an effect failure, so it bypasses this handler); any
+ * other effect failure re-raises unchanged.
+ *
+ * @param bin - The binary name surfaced in the error message.
+ * @param recovery - The install/PATH recovery hint.
+ * @param task - The Task whose `exec` effect may reject with ENOENT.
+ * @returns The Task, guarded against a missing-binary spawn.
+ */
+export function guardMissingBinary<A>(
+  bin: string,
+  recovery: Recovery,
+  task: Task<A>,
+): Task<A> {
+  return recover(task, (error) => {
+    if (isMissingBinaryError(error)) {
+      throw new PragmaError({
+        code: "UNSUPPORTED",
+        message: `\`${bin}\` was not found on your PATH.`,
+        recovery,
+      });
+    }
+    // Not a missing binary — re-raise unchanged (the interpreter rethrows it as
+    // a TaskExecutionError, exactly as it would with no guard installed).
+    return fail(error);
+  });
+}

package/src/capabilities/shared/packageManager.ts

@@ -0,0 +1,62 @@
+/**
+ * Storeless install-source heuristic, shared by `info`, `upgrade`, and
+ * `doctor`'s `pragma version` check.
+ *
+ * Promotes the detector that lived inline in `info/collectInfo.ts`: the package
+ * manager comes from npm's `npm_config_user_agent` (set by npm/pnpm/yarn/bun
+ * when they run a script), the scope from whether the binary sits under
+ * `node_modules`. With no agent we report the honest runtime rather than
+ * guessing. The old shell's full package.json walk (`#package-manager`) is
+ * dropped — only this heuristic and the update-command map survive.
+ */
+
+/** The install source: package manager and a display label. */
+export interface InstallSource {
+  /** Package-manager name (`bun`/`npm`/`pnpm`/`yarn`), else the honest runtime. */
+  readonly pm: string;
+  /** `${pm} (${scope})` — the string `info`/`doctor` display. */
+  readonly label: string;
+}
+
+/** The package manager from npm's user-agent, else the honest runtime. */
+function packageManager(): string {
+  const agent = process.env.npm_config_user_agent;
+  const name = agent?.split("/")[0];
+  if (name) return name;
+  return process.versions.bun ? "bun" : "node";
+}
+
+/**
+ * Detect how the binary was installed — package manager and scope.
+ *
+ * @returns The install source (pm, label).
+ * @note Impure — reads `process.argv`/`process.env`.
+ */
+export function detectInstallSource(): InstallSource {
+  const bin = process.argv[1] ?? "";
+  const scope = bin.includes("node_modules") ? "local" : "global";
+  const pm = packageManager();
+  return { pm, label: `${pm} (${scope})` };
+}
+
+/** The npm global-update command — also the fallback for an unknown manager. */
+const npmUpdateCommand = (pkg: string): string => `npm i -g ${pkg}`;
+
+/** The global-update command per package manager (install-style). */
+const PM_UPDATE_COMMAND: Record<string, (pkg: string) => string> = {
+  bun: (pkg) => `bun add -g ${pkg}`,
+  npm: npmUpdateCommand,
+  pnpm: (pkg) => `pnpm add -g ${pkg}`,
+  yarn: (pkg) => `yarn global add ${pkg}`,
+};
+
+/**
+ * The command that updates `pkg` globally for a package manager.
+ *
+ * @param pm - The package-manager name (`bun`/`npm`/`pnpm`/`yarn`).
+ * @param pkg - The package to update.
+ * @returns The shell command; falls back to npm for an unknown manager.
+ */
+export function pmUpdateCommand(pm: string, pkg: string): string {
+  return (PM_UPDATE_COMMAND[pm] ?? npmUpdateCommand)(pkg);
+}

package/src/capabilities/shared/registry.ts

@@ -0,0 +1,70 @@
+/**
+ * npm registry version check — the shared network read `info` (enrichment) and
+ * `upgrade` (mutation) both consume.
+ *
+ * Ported verbatim from the old shell's `info/operations/checkRegistryVersion` +
+ * its `DIST_TAG_MAP`/`REGISTRY_TIMEOUT_MS` constants. A single GET against the
+ * registry's package document, a 3s timeout, and `undefined` on any failure
+ * (offline, non-2xx, timeout, missing dist-tag) — so a caller degrades silently
+ * rather than erroring. The whole request is preview-safe: it is a plain read
+ * with no side effects.
+ */
+
+import type { Channel } from "../../kernel/config/types.js";
+
+/**
+ * The published package `info`/`upgrade` check for updates: the stable name
+ * users installed, so the check answers "is a newer release of the tool
+ * available".
+ */
+export const PRAGMA_PACKAGE = "@canonical/pragma-cli";
+
+/** Maps each release channel to its corresponding npm dist-tag (internal). */
+const DIST_TAG_MAP: Record<Channel, string> = {
+  normal: "latest",
+  experimental: "experimental",
+  prerelease: "next",
+};
+
+/** Timeout in milliseconds for npm registry HTTP requests. */
+export const REGISTRY_TIMEOUT_MS = 3_000;
+
+/** Result of checking the npm registry for the latest package version. */
+export interface RegistryCheckResult {
+  readonly latest: string;
+}
+
+/**
+ * Check the npm registry for the latest published version of a package.
+ *
+ * @param packageName - The npm package name (e.g. `@canonical/pragma-cli`).
+ * @param channel - The release channel, selecting which dist-tag to read.
+ * @returns The latest version for the channel's dist-tag, or `undefined` when
+ *   offline / non-2xx / timed out / the dist-tag is absent.
+ * @note Impure — a single network GET (3s timeout, silent-fail).
+ */
+export async function checkRegistryVersion(
+  packageName: string,
+  channel: Channel,
+): Promise<RegistryCheckResult | undefined> {
+  const distTag = DIST_TAG_MAP[channel];
+  const url = `https://registry.npmjs.org/${encodeURIComponent(packageName)}`;
+
+  try {
+    const response = await fetch(url, {
+      signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+      headers: { Accept: "application/json" },
+    });
+    if (!response.ok) return undefined;
+
+    const data = (await response.json()) as {
+      "dist-tags"?: Record<string, string>;
+    };
+    const version = data["dist-tags"]?.[distTag];
+    if (!version) return undefined;
+
+    return { latest: version };
+  } catch {
+    return undefined;
+  }
+}

package/src/capabilities/skill/discover.ts

@@ -0,0 +1,178 @@
+/**
+ * Storeless skill discovery over the filesystem.
+ *
+ * A skill is a folder with a `SKILL.md` carrying YAML frontmatter (`name`,
+ * `description`, and the #856 `prompt` flag among others). Skills are discovered
+ * from conventional roots — project skills under `<cwd>/.pragma/skills`, which
+ * take precedence, then installed skills under `$XDG_DATA_HOME/pragma/skills` —
+ * with missing files and invalid frontmatter skipped gracefully. Reads only the
+ * filesystem, never the graph store, so `skill list`/`lookup` are storeless
+ * (needsStore: false).
+ */
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/** Parsed SKILL.md frontmatter. */
+export interface SkillFrontmatter {
+  readonly name: string;
+  readonly description: string;
+  /** #856 — whether this skill also registers as an MCP prompt. */
+  readonly prompt?: boolean;
+  readonly license?: string;
+}
+
+/** A discovered skill: its frontmatter plus where it was found. */
+export interface DiscoveredSkill {
+  readonly name: string;
+  readonly description: string;
+  readonly folderName: string;
+  readonly sourcePath: string;
+  readonly frontmatter: SkillFrontmatter;
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/** Parse one YAML scalar (string, boolean, number, or inline array). */
+function parseYamlValue(raw: string): unknown {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    return trimmed
+      .slice(1, -1)
+      .split(",")
+      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  const num = Number(trimmed);
+  if (!Number.isNaN(num) && trimmed !== "") return num;
+  return trimmed.replace(/^["']|["']$/g, "");
+}
+
+/** Parse a simple YAML subset (top-level keys + one nesting level). */
+function parseSimpleYaml(block: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  let currentKey: string | null = null;
+  let nested: Record<string, unknown> | null = null;
+  for (const line of block.split("\n")) {
+    if (line.trim() === "" || line.trim().startsWith("#")) continue;
+    const indented = line.match(/^(\s+)(\w[\w-]*)\s*:\s*(.*)/);
+    const topLevel = line.match(/^(\w[\w-]*)\s*:\s*(.*)/);
+    if (indented && currentKey && (indented[1]?.length ?? 0) >= 2) {
+      if (!nested) nested = {};
+      nested[indented[2] as string] = parseYamlValue(
+        (indented[3] ?? "").trim(),
+      );
+    } else if (topLevel) {
+      if (currentKey && nested) {
+        result[currentKey] = nested;
+        nested = null;
+      }
+      const key = topLevel[1] as string;
+      const value = topLevel[2] ?? "";
+      currentKey = key;
+      if (value === "") {
+        nested = {};
+      } else {
+        result[key] = parseYamlValue(value);
+        nested = null;
+      }
+    }
+  }
+  if (currentKey && nested) result[currentKey] = nested;
+  return result;
+}
+
+/** Extract and validate SKILL.md frontmatter; `null` when missing/invalid. */
+export function parseFrontmatter(content: string): SkillFrontmatter | null {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match?.[1]) return null;
+  const parsed = parseSimpleYaml(match[1]);
+  if (typeof parsed.name !== "string" || parsed.name === "") return null;
+  if (typeof parsed.description !== "string" || parsed.description === "") {
+    return null;
+  }
+  return {
+    name: parsed.name,
+    description: parsed.description,
+    ...(typeof parsed.prompt === "boolean" ? { prompt: parsed.prompt } : {}),
+    ...(typeof parsed.license === "string" ? { license: parsed.license } : {}),
+  };
+}
+
+/**
+ * The installed-skills root: `$XDG_DATA_HOME/pragma/skills`. This is where
+ * `sources update` INSTALLS package-provided skills (U10) — a symlink per skill
+ * — and the second discovery root below reads them back. The single source of
+ * truth for both, so the install target and the discovery root can never drift.
+ */
+export function installedSkillsDir(): string {
+  const dataHome =
+    process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+  return join(dataHome, "pragma", "skills");
+}
+
+/**
+ * The conventional roots skills are discovered from, in PRECEDENCE order: the
+ * project root (`<cwd>/.pragma/skills`) FIRST so a project-local skill overrides
+ * an installed skill of the same name (`discoverSkills` dedups first-seen-wins),
+ * then installed skills under `$XDG_DATA_HOME/pragma/skills` (where package
+ * skills land on `sources update`).
+ */
+export function skillRoots(cwd: string): string[] {
+  return [join(cwd, ".pragma", "skills"), installedSkillsDir()];
+}
+
+/** Immediate subdirectories of `root` (each a candidate skill folder). */
+function subdirs(root: string): string[] {
+  try {
+    return readdirSync(root)
+      .map((name) => join(root, name))
+      .filter((path) => {
+        try {
+          return statSync(path).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover every skill reachable from the conventional roots.
+ *
+ * @param cwd - The project directory (project skills root).
+ * @returns Discovered skills, sorted by name; malformed ones are skipped.
+ * @note Impure — reads SKILL.md files.
+ */
+export function discoverSkills(cwd: string): DiscoveredSkill[] {
+  const skills: DiscoveredSkill[] = [];
+  const seen = new Set<string>();
+  for (const root of skillRoots(cwd)) {
+    for (const dir of subdirs(root)) {
+      let content: string;
+      try {
+        content = readFileSync(join(dir, "SKILL.md"), "utf-8");
+      } catch {
+        continue;
+      }
+      const frontmatter = parseFrontmatter(content);
+      if (!frontmatter || seen.has(frontmatter.name)) continue;
+      seen.add(frontmatter.name);
+      skills.push({
+        name: frontmatter.name,
+        description: frontmatter.description,
+        folderName: basename(dir),
+        sourcePath: dir,
+        frontmatter,
+      });
+    }
+  }
+  return skills.sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+}

package/src/capabilities/skill/index.ts

@@ -0,0 +1,12 @@
+/**
+ * The `skill` capability module — storeless filesystem discovery.
+ */
+
+import type { CapabilityModule } from "../../kernel/spec/types.js";
+import { skillListVerb, skillLookupVerb } from "./verbs.js";
+
+/** The `skill` capability module (`list`, `lookup`). */
+export const skillModule: CapabilityModule = {
+  name: "skill",
+  verbs: [skillListVerb, skillLookupVerb],
+};

package/src/capabilities/skill/render.ts

@@ -0,0 +1,60 @@
+/**
+ * Formatters for `skill list` and `skill lookup`.
+ */
+
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { DiscoveredSkill } from "./discover.js";
+import type { SkillLookup } from "./verbs.js";
+
+/** Empty-state guidance (U5) — where skills come from now that packages ship them. */
+const EMPTY_PLAIN =
+  "No skills found.\nSkills come from installed design-system packages — add one to your config, run `pragma sources update`, then `pragma setup skills`.";
+const EMPTY_LLM =
+  "## Skills (0)\n\nNo skills found. Skills come from installed design-system packages — add one to the project config, run `pragma sources update`, then `pragma setup skills`.";
+
+export const skillListFormatters: Formatters<DiscoveredSkill[]> = {
+  plain: (skills) =>
+    skills.length === 0
+      ? EMPTY_PLAIN
+      : skills
+          .map(
+            (s) =>
+              `${s.name}${s.frontmatter.prompt ? " (prompt)" : ""}  ${s.description}`,
+          )
+          .join("\n"),
+  llm: (skills) =>
+    skills.length === 0
+      ? EMPTY_LLM
+      : [
+          `## Skills (${skills.length})`,
+          "",
+          ...skills.map(
+            (s) =>
+              `- **${s.name}**${s.frontmatter.prompt ? " (prompt)" : ""} — ${s.description}`,
+          ),
+        ].join("\n"),
+  json: (skills) => JSON.stringify(skills, null, 2),
+};
+
+export const skillLookupFormatters: Formatters<SkillLookup> = {
+  plain(skill) {
+    const lines = [
+      skill.name,
+      "═".repeat(Math.max(skill.name.length, 24)),
+      "",
+      `  ${skill.description}`,
+    ];
+    if (skill.frontmatter.prompt) lines.push("  registers as an MCP prompt");
+    if (skill.frontmatter.license) {
+      lines.push(`  license: ${skill.frontmatter.license}`);
+    }
+    if (skill.instructions) lines.push("", skill.instructions);
+    return lines.join("\n");
+  },
+  llm(skill) {
+    const lines = [`## ${skill.name}`, "", skill.description, ""];
+    if (skill.instructions) lines.push(skill.instructions);
+    return lines.join("\n").trimEnd();
+  },
+  json: (skill) => JSON.stringify(skill, null, 2),
+};

package/src/capabilities/skill/skill.test.ts

@@ -0,0 +1,142 @@
+/**
+ * Skill discovery (list + lookup) — storeless filesystem reads.
+ *
+ * Skills are SKILL.md folders under the project root; discovery reads only the
+ * filesystem, so the store must never boot (needsStore: false). The #856
+ * `prompt` frontmatter flag is preserved.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verbKey } from "../../kernel/packs/uniqueness.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { TEST_FLAGS } from "../../testing/helpers/projectCli.js";
+import type { DiscoveredSkill } from "./discover.js";
+import { skillModule } from "./index.js";
+import { skillListFormatters } from "./render.js";
+import type { SkillLookup } from "./verbs.js";
+
+const listVerb = skillModule.verbs.find(
+  (v) => verbKey(v.path) === "skill list",
+) as VerbSpec;
+const lookupVerb = skillModule.verbs.find(
+  (v) => verbKey(v.path) === "skill lookup",
+) as VerbSpec;
+
+let projectDir: string;
+let rt: PragmaRuntime;
+
+function writeSkill(name: string, body: string): void {
+  const dir = join(projectDir, ".pragma", "skills", name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), body);
+}
+
+beforeAll(() => {
+  projectDir = mkdtempSync(join(tmpdir(), "pragma-skills-"));
+  writeSkill(
+    "docx",
+    "---\nname: docx\ndescription: Work with Word documents.\n---\nUse this for .docx files.",
+  );
+  writeSkill(
+    "pdf",
+    "---\nname: pdf\ndescription: Work with PDF files.\nprompt: true\nlicense: MIT\n---\nUse this for PDFs.",
+  );
+  // A folder with no SKILL.md is skipped gracefully.
+  mkdirSync(join(projectDir, ".pragma", "skills", "empty"), {
+    recursive: true,
+  });
+  rt = bootRuntime(TEST_FLAGS, projectDir);
+});
+
+afterAll(() => {
+  rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe("skill list (storeless)", () => {
+  it("discovers skills by name, carrying the prompt flag", async () => {
+    const skills = (await listVerb.run({}, rt)) as DiscoveredSkill[];
+    expect(skills.map((s) => s.name)).toEqual(["docx", "pdf"]);
+    expect(skills.find((s) => s.name === "pdf")?.frontmatter.prompt).toBe(true);
+    expect(
+      skills.find((s) => s.name === "docx")?.frontmatter.prompt,
+    ).toBeUndefined();
+    // needsStore: false — discovery never boots the store.
+    expect(rt.store.booted).toBe(false);
+  });
+});
+
+describe("skill lookup (storeless)", () => {
+  it("returns metadata + instructions, and suggests on a miss", async () => {
+    const skill = (await lookupVerb.run({ name: "pdf" }, rt)) as SkillLookup;
+    expect(skill.description).toBe("Work with PDF files.");
+    expect(skill.frontmatter.license).toBe("MIT");
+    expect(skill.instructions).toBe("Use this for PDFs.");
+    expect(rt.store.booted).toBe(false);
+
+    await expect(lookupVerb.run({ name: "docs" }, rt)).rejects.toThrow(
+      /not found/i,
+    );
+  });
+});
+
+describe("skill list empty-state (U5)", () => {
+  it("plain output is non-blank and guides toward package sources", () => {
+    const plain = skillListFormatters.plain([]);
+    expect(plain).not.toBe("");
+    expect(plain).toContain("No skills found");
+    expect(plain).toContain("pragma sources update");
+  });
+
+  it("llm output announces zero and guides, json stays []", () => {
+    expect(skillListFormatters.llm([])).toContain("Skills (0)");
+    expect(skillListFormatters.llm([])).toContain("pragma sources update");
+    expect(skillListFormatters.json([])).toBe("[]");
+  });
+});
+
+describe("skill precedence (project overrides installed)", () => {
+  let precedenceDir: string;
+  let installedHome: string;
+  let savedDataHome: string | undefined;
+  let precedenceRt: PragmaRuntime;
+
+  beforeAll(() => {
+    precedenceDir = mkdtempSync(join(tmpdir(), "pragma-skills-proj-"));
+    installedHome = mkdtempSync(join(tmpdir(), "pragma-skills-installed-"));
+    // An installed skill and a project skill both claim the name `shared`.
+    const installed = join(installedHome, "pragma", "skills", "shared");
+    mkdirSync(installed, { recursive: true });
+    writeFileSync(
+      join(installed, "SKILL.md"),
+      "---\nname: shared\ndescription: INSTALLED copy.\n---\nInstalled body.",
+    );
+    const project = join(precedenceDir, ".pragma", "skills", "shared");
+    mkdirSync(project, { recursive: true });
+    writeFileSync(
+      join(project, "SKILL.md"),
+      "---\nname: shared\ndescription: PROJECT copy.\n---\nProject body.",
+    );
+    savedDataHome = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = installedHome;
+    precedenceRt = bootRuntime(TEST_FLAGS, precedenceDir);
+  });
+
+  afterAll(() => {
+    if (savedDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = savedDataHome;
+    rmSync(precedenceDir, { recursive: true, force: true });
+    rmSync(installedHome, { recursive: true, force: true });
+  });
+
+  it("returns the project skill, not the installed one, on a name clash", async () => {
+    const skills = (await listVerb.run({}, precedenceRt)) as DiscoveredSkill[];
+    const shared = skills.filter((s) => s.name === "shared");
+    expect(shared).toHaveLength(1);
+    expect(shared[0]?.description).toBe("PROJECT copy.");
+  });
+});