pi-daddy 0.13.0 → 0.14.0

package/src/init.ts

@@ -0,0 +1,344 @@
+/**
+ * `pi-daddy init` — scaffold a governed project from the skill packages already installed (B2, P3).
+ *
+ * Today an operator wanting to govern a package of skills must, per skill: create a directory, copy the
+ * body, hand-write frontmatter, choose a capability set with no guidance, and assemble a `PI_GRANTS_GRANT`
+ * string by hand. Seven times, for `principal-pi-skills`. This does the mechanical parts.
+ *
+ * **The line it does not cross, and the reason this module exists at all:** `init` writes files an operator
+ * then **reviews, edits and commits**. It never chooses a ceiling. A skill that declares `allowed-tools` is
+ * copied *verbatim* — the author's declaration is the ceiling, and re-deriving it here would put a second
+ * opinion between the file and the enforcer. A skill that declares none is copied with a **commented**
+ * placeholder and stays unspawnable until a human fills it in.
+ *
+ * **What it DOES choose is the starting grant, which is a stronger act** — ADR-0029, added after a reviewer
+ * pointed out that ADR-0028 drew its boundary around the wrong object. The handoff's reason a third party
+ * may safely author `allowed-tools` is that *"the operator's `PI_GRANTS_GRANT` still bounds it"*; a
+ * generated union gives the bound and the bounded one author, and it is not the operator. So capabilities
+ * that can change a machine are emitted **commented** (`./grant-env.ts`).
+ *
+ * The placeholder is deliberately not a working example. Uncommenting it unedited yields capability ids
+ * like `tool:<list` which the catalog refuses as unknown — a loud failure, in the direction rule 8 asks
+ * for, rather than a grant nobody decided.
+ */
+
+import { mkdir, open, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { agentCapability } from "./capabilities.ts";
+import { ceilingForDefinition } from "./definitions.ts";
+import { ALWAYS_LIVE, assertGrantIsWritable, isLiveByDefault, renderGrantEnv, type GrantEnvSkill } from "./grant-env.ts";
+import { PI_BUILTIN_TOOLS } from "./pi-tools.ts";
+import type { Capability } from "./resolve.ts";
+import type { SkillPackage } from "./skill-packages.ts";
+
+/** Why a discovered skill is not authorised in the generated grant. `null` means it is. */
+/**
+ * How many of `from`'s skills actually **declare** a ceiling.
+ *
+ * Exported because the number is printed to an operator and was wrong: `cli.ts` filtered on
+ * `withheld === null`, which is false for all three `WithholdReason`s — so a skill that declares
+ * `allowed-tools` perfectly well and merely needs a withheld capability counted as not declaring one.
+ * Against `principal-pi-skills` that printed *"7 skill(s), 3 declaring allowed-tools"* while all seven
+ * declared. R-28's shape: a diagnostic disagreeing with the thing it describes.
+ *
+ * **It was invisible until the integration worked.** Before ceilings shipped, none of the seven declared
+ * and the line read *"0 declaring"* — correct by coincidence, for the wrong reason. A count that is right
+ * only while the interesting case is absent is the kind this project keeps finding.
+ *
+ * `undeclared` is the only reason that means "did not declare". `pattern` declared something this package
+ * refuses to reinterpret, and `needs-withheld` declared something fine that the operator must opt into —
+ * both are declarations.
+ */
+export function countDeclaring(skills: PlannedSkill[], from: string): number {
+  return skills.filter((s) => s.from === from && s.withheld !== "undeclared").length;
+}
+
+export type WithholdReason = "undeclared" | "pattern" | "needs-withheld";
+
+export interface PlannedSkill {
+  name: string;
+  /** Which package it came from, as `name@version`. */
+  from: string;
+  sourcePath: string;
+  targetPath: string;
+  /** Exactly what would be written — the file verbatim, or the file plus a commented note. */
+  content: string;
+  /** The declared ceiling, empty when the declaration is absent or unusable. */
+  ceiling: Capability[];
+  withheld: WithholdReason | null;
+  /** e.g. a sub-tool pattern pi's `--tools` cannot express. Reported, never reinterpreted. */
+  notes: string[];
+}
+
+export interface InitPlan {
+  skills: PlannedSkill[];
+  /** Definitions two packages both declare. First wins; the loser is named rather than silently dropped. */
+  collisions: string[];
+  /** The live grant — what `source .pi/grants.env` actually sets. */
+  grant: Capability[];
+  /** Withheld capability → the definitions that declared it (ADR-0029). Emitted commented. */
+  withheldCapabilities: Map<Capability, string[]>;
+  grantEnvPath: string;
+  grantEnvContent: string;
+  /** Capabilities a declared ceiling names that pi 0.84.1 has no tool for — a caution, not a verdict. */
+  cautions: string[];
+}
+
+const PLACEHOLDER = [
+  "# pi-daddy: this skill declares no `allowed-tools`, so it CANNOT be spawned as a governed sub-agent —",
+  "# an undeclared capability set is treated as NONE, never as everything. Decide what it needs, then",
+  "# uncomment and complete the line below. pi-daddy does not choose this for you: the capability set is",
+  "# the thing you are meant to review and commit.",
+  "# pi 0.84.1's tools: " + PI_BUILTIN_TOOLS.join(", ") + ".",
+  "# allowed-tools: <list the tools this skill needs, e.g. Read, Grep>",
+];
+
+/**
+ * A copied file that is unspawnable for a reason an operator cannot see by reading it.
+ *
+ * The undeclared case got four explanatory lines from the start; a pattern-carrying one got nothing, so
+ * opening `.pi/skills/git-ops/SKILL.md` to find out why it will not spawn showed a perfectly ordinary file.
+ * Same argument, opposite treatment — now the same treatment.
+ */
+const patternNote = (patterns: string[]) => [
+  "# pi-daddy: this skill CANNOT be spawned as a governed sub-agent. Its `allowed-tools` restricts a tool",
+  `# with a pattern (${patterns.join(", ")}), and pi's --tools matches whole tool names only — granting the`,
+  "# bare tool would widen the declaration and dropping it would silently narrow, so neither is done.",
+  "# Replace the pattern with whole tool names to make it spawnable.",
+];
+
+/**
+ * The file to write for one skill: verbatim when it declares a usable ceiling, plus a commented note when
+ * it does not.
+ *
+ * Inserted at the END of the frontmatter block, so the rest of the file — including its own key order and
+ * its body — is byte-identical to the package's. A `#` line is a YAML comment and this package's
+ * frontmatter reader skips it, so an undeclared copy is still *undeclared*: not spawnable until a human
+ * edits it, which is the whole point.
+ */
+export function withPlaceholder(text: string, declared: boolean, note: string[] = PLACEHOLDER): string {
+  if (declared) return text;
+  const match = /^(---\r?\n)([\s\S]*?)(\r?\n---(?:\r?\n|$))/.exec(text);
+  // No frontmatter at all means `parseSkillDefinition` returned null and this skill was never discovered;
+  // inventing one here would invent a file shape. Left exactly as it is.
+  if (!match) return text;
+  const [full, opening, body, close] = match;
+  const eol = close.startsWith("\r\n") ? "\r\n" : "\n";
+  return opening + body + eol + note.join(eol) + close + text.slice(full.length);
+}
+
+/** `tool:` ids pi 0.84.1 has no tool for. `delegate` is this package's own, hence the exemption. */
+function unknownToolIds(capabilities: Capability[]): Capability[] {
+  const builtins = new Set<string>(PI_BUILTIN_TOOLS);
+  return capabilities.filter(
+    (c) => c.startsWith("tool:") && c !== ALWAYS_LIVE && !builtins.has(c.slice("tool:".length)),
+  );
+}
+
+/**
+ * Decide what `init` would write. Pure: no filesystem, no npm, no decisions taken on the operator's behalf.
+ *
+ * The grant is **the read-only part** of what the copied skills declare, plus one `agent:` id per definition
+ * that can actually run within it, plus `tool:delegate` — without which the session registers no delegation
+ * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
+ * away (ADR-0029).
+ */
+export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
+  const skills: PlannedSkill[] = [];
+  const collisions: string[] = [];
+  const seen = new Set<string>();
+
+  for (const pkg of packages) {
+    for (const skill of pkg.skills) {
+      const name = skill.definition.name;
+      if (seen.has(name)) {
+        collisions.push(`${name} (also in ${pkg.name}@${pkg.version}, not written)`);
+        continue;
+      }
+      seen.add(name);
+
+      const ceiling = ceilingForDefinition(skill.definition);
+      const notes: string[] = [];
+      let withheld: WithholdReason | null = null;
+      let note = PLACEHOLDER;
+      if (ceiling.undeclared) withheld = "undeclared";
+      else if (ceiling.patterns.length > 0) {
+        withheld = "pattern";
+        note = patternNote(ceiling.patterns);
+        notes.push(
+          `declares ${ceiling.patterns.join(", ")} — pi's --tools matches whole tool names only, so a ` +
+            `sub-tool pattern is refused rather than reinterpreted (granting the bare tool would widen it)`,
+        );
+      }
+
+      skills.push({
+        name,
+        from: `${pkg.name}@${pkg.version}`,
+        sourcePath: skill.path,
+        targetPath: join(cwd, ".pi", "skills", name, "SKILL.md"),
+        content: withPlaceholder(skill.text, withheld === null, note),
+        ceiling: ceiling.capabilities,
+        withheld,
+        notes,
+      });
+    }
+  }
+
+  // ADR-0029: split what the declared ceilings ask for into what `init` grants live and what it comments.
+  const declared = skills.filter((s) => s.withheld === null);
+  const withheldCapabilities = new Map<Capability, string[]>();
+  for (const skill of declared) {
+    for (const capability of skill.ceiling) {
+      if (isLiveByDefault(capability)) continue;
+      withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
+    }
+  }
+
+  // A definition needing a withheld capability does not get a live `agent:` id either: authorising it to run
+  // and then refusing it at spawn time is a worse answer than not authorising it, and it would put an
+  // `agent:` id in the grant whose definition cannot work — the shape ADR-0028 rule 3 already refuses.
+  for (const skill of declared) {
+    if (skill.ceiling.some((c) => !isLiveByDefault(c))) skill.withheld = "needs-withheld";
+  }
+
+  const authorised = skills.filter((s) => s.withheld === null);
+  const written = new Set(authorised.map((s) => s.name));
+  // `agent:<other>` in a ceiling is legitimate — it is how a delegator learns which definitions IT may
+  // spawn — but a name `init` did not write here would authorise a file from another skill root that the
+  // operator is not reviewing, including `~/.pi/agent/skills`, which other tools install into. Reported,
+  // never granted: the same objection ADR-0028 rule 3 makes to authorising an undeclared skill.
+  const crossReferences: { from: string; capability: Capability }[] = [];
+  const live = new Set<Capability>([ALWAYS_LIVE]);
+  for (const skill of authorised) {
+    live.add(agentCapability(skill.name));
+    for (const capability of skill.ceiling) {
+      if (capability.startsWith("agent:") && !written.has(capability.slice("agent:".length))) {
+        crossReferences.push({ from: skill.name, capability });
+        continue;
+      }
+      live.add(capability);
+    }
+  }
+  const grant = [...live].sort();
+
+  const cautions = authorised.flatMap((s) =>
+    unknownToolIds(s.ceiling).map(
+      (c) =>
+        `${s.name} declares ${c}, which pi 0.84.1 has no tool for — unless an extension provides it, ` +
+        `spawning ${s.name} is refused as an unknown capability`,
+    ),
+  );
+
+  // R-78's structural backstop. Throws rather than rendering something a shell could read as more than a
+  // value, so a gap in the per-entry whitelist costs a refusal instead of an injection.
+  assertGrantIsWritable(grant);
+
+  const describe: Record<WithholdReason, (s: PlannedSkill) => string> = {
+    undeclared: (s) => "declares no `allowed-tools` — fill it in, then add `agent:" + s.name + "` below",
+    pattern: (s) => s.notes.join("; "),
+    "needs-withheld": (s) =>
+      `needs ${s.ceiling.filter((c) => !isLiveByDefault(c)).join(", ")}, withheld by default — see below`,
+  };
+
+  const grantEnvSkills: GrantEnvSkill[] = skills.map((s) => ({
+    name: s.name,
+    ceiling: s.ceiling,
+    ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
+  }));
+
+  return {
+    skills,
+    collisions,
+    grant,
+    withheldCapabilities,
+    grantEnvPath: join(cwd, ".pi", "grants.env"),
+    grantEnvContent: renderGrantEnv({
+      skills: grantEnvSkills,
+      live: grant,
+      withheld: withheldCapabilities,
+      withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
+      crossReferences,
+      cautions,
+    }),
+    cautions,
+  };
+}
+
+export interface InitOutcome {
+  written: string[];
+  /** Present already, so left alone. `init` never silently overwrites an edited ceiling. */
+  kept: string[];
+  failed: { path: string; error: string }[];
+}
+
+/**
+ * Create a file only if nothing is there, and **never through a symlink**.
+ *
+ * Both properties come from `O_CREAT|O_EXCL` (`flag: "wx"`), and both were defects in the first version
+ * (R-79). It probed for existence with `readFile` and then called `writeFile`:
+ *
+ *  - `readFile` conflates *unreadable* with *absent*, so an operator's `SKILL.md` with restrictive
+ *    permissions was reported `wrote` and their narrowed `allowed-tools: Read` was replaced by the
+ *    package's wider one — **without `--force`**, falsifying this package's own documented "Kept" rule.
+ *    A FIFO at the target path hung the probe forever, with no timeout anywhere in the path.
+ *  - `writeFile` follows symlinks, so a dangling symlink at a target path created the file at the link's
+ *    destination, outside the project, while reporting an in-project path. That is **B-I6**, which
+ *    `approval-store.ts` already fixed for the approval store under ADR-0014 — a new writer in the same
+ *    package reintroducing a defect the package documents as closed, and whose comment says in so many
+ *    words *"never through a symlink"*.
+ *
+ * `wx` fails with `EEXIST` on anything at the path, including a dangling symlink, so there is no probe, no
+ * race between the probe and the write, and no way to write through a link.
+ */
+async function createUnlessPresent(path: string, content: string, outcome: InitOutcome): Promise<void> {
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    const handle = await open(path, "wx");
+    try {
+      await handle.writeFile(content, "utf8");
+    } finally {
+      await handle.close();
+    }
+    outcome.written.push(path);
+  } catch (error) {
+    if ((error as { code?: string }).code === "EEXIST") outcome.kept.push(path);
+    else outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/** Replace a file, unlinking first so a symlink is REPLACED rather than written through. */
+async function replace(path: string, content: string, outcome: InitOutcome): Promise<void> {
+  try {
+    await mkdir(join(path, ".."), { recursive: true });
+    // `rm` unlinks the LINK, never its target — which is exactly the semantics `--force` should have.
+    await rm(path, { force: true });
+    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+    outcome.written.push(path);
+  } catch (error) {
+    outcome.failed.push({ path, error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+/**
+ * Apply a plan.
+ *
+ * **Existing files are kept, not overwritten**, and that default is load-bearing rather than polite: the
+ * edit an operator makes to one of these files IS the capability decision, and the second run of a
+ * scaffolding command is exactly when it would be destroyed.
+ *
+ * **`--force` never regenerates `.pi/grants.env`** (R-79). It rewrites the definition copies, which is the
+ * documented re-sync path for R-74 — but the grant file is the *reviewed artifact*, and an operator who had
+ * deleted `agent:build` and added a ledger path would have had both silently restored to generated defaults
+ * by a command whose usage text mentions only `allowed-tools`. Deleting the file is how to regenerate it,
+ * and that is not something anyone does by accident.
+ */
+export async function applyInit(plan: InitPlan, options: { force?: boolean } = {}): Promise<InitOutcome> {
+  const outcome: InitOutcome = { written: [], kept: [], failed: [] };
+  const force = options.force === true;
+  for (const skill of plan.skills) {
+    if (force) await replace(skill.targetPath, skill.content, outcome);
+    else await createUnlessPresent(skill.targetPath, skill.content, outcome);
+  }
+  await createUnlessPresent(plan.grantEnvPath, plan.grantEnvContent, outcome);
+  return outcome;
+}

package/src/skill-packages.ts

@@ -0,0 +1,251 @@
+/**
+ * Which installed npm packages ship `SKILL.md` definitions — read from their own manifests.
+ *
+ * `pi-daddy init` scaffolds a governed project from whatever skill packages are already installed, and
+ * this is how it finds them: **a package declares its skills in `package.json`'s `pi.skills` array**, which
+ * is pi's own convention and how pi itself loads them. Measured against `principal-pi-skills@2.3.1`:
+ *
+ * ```json
+ * "pi": { "skills": ["./decide", "./architect", "./plan", "./build", "./review", "./debug", "./git-ops"] }
+ * ```
+ *
+ * **A declaration, never a heuristic.** Walking `node_modules` looking for files called `SKILL.md` would
+ * find a package's test fixtures, its examples, and its vendored copies of someone else's skills — and
+ * would then offer to install them as spawnable sub-agents. A package that says which of its files are
+ * skills has said so on purpose, and that is the only list this reads.
+ *
+ * What it deliberately does NOT do: scan `~/.pi/agent/skills/`. Definitions already in a skill root are
+ * discovered by `loadDefinitions` and governed as they stand; copying them into a project would duplicate
+ * them under a name that shadows the original (project wins on collision), which is a change nobody asked
+ * for.
+ *
+ * **Everything read here comes from a third party**, so this module is also where the refusals live: a
+ * name, a declared capability id, or a path that cannot safely be written into a generated file is refused
+ * with a reason rather than passed on (R-77, R-78, R-80). `init` generates a shell file an operator
+ * `source`s; the only strings that may reach it are ones that survived a whitelist here.
+ */
+
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
+import { WILDCARD } from "./pi-tools.ts";
+import { AGENT_WILDCARD, type Capability } from "./resolve.ts";
+
+export interface DiscoveredSkill {
+  definition: SkillDefinition;
+  /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
+  text: string;
+  path: string;
+}
+
+/** Why a declared skill was refused before it could be planned. Each has a different fix. */
+export type RefusalReason =
+  /** The name cannot be a capability id, a line in a sourced file, or a path segment. */
+  | "unsafe-name"
+  /** A declared `allowed-tools` entry cannot be one either — R-78, the sibling of R-77. */
+  | "unsafe-capability"
+  /** The declaration claims `tool:*` or `agent:*`: root authority, which a package may not hand itself. */
+  | "wildcard"
+  /** The bytes are not valid UTF-8, so "copied verbatim" could not be honoured. */
+  | "not-utf8";
+
+export interface RefusedSkill {
+  /** The `pi.skills` entry or the definition name, whichever the operator can act on. */
+  subject: string;
+  reason: RefusalReason;
+  /** The offending id(s), when the reason names any. */
+  detail: string[];
+}
+
+export interface SkillPackage {
+  name: string;
+  version: string;
+  /** Paths `pi.skills` named that could not be read as a `SKILL.md`, so the report can say so out loud. */
+  unreadable: string[];
+  /** Skills refused for a reason that would otherwise reach a generated file. Never silently dropped. */
+  refused: RefusedSkill[];
+  skills: DiscoveredSkill[];
+}
+
+/**
+ * May this definition's name be written into a capability id, a shell file and a path?
+ *
+ * **Measured before it was written, and it was a defect in this module's first version (R-77).** A
+ * definition's identity is its directory name, and `init` interpolates that name into three places at once:
+ * `agent:<name>` inside a **comma-separated** `PI_GRANTS_GRANT`, a `.pi/grants.env` an operator **sources**,
+ * and the path it writes the copy to. An installed package with a directory called `a,tool:bash` produced
+ *
+ * ```
+ * export PI_GRANTS_GRANT="agent:a,tool:bash,tool:delegate,tool:read"
+ * ```
+ *
+ * — `tool:bash` in an operator's grant, declared by nobody. A quote character reaches a file that gets
+ * `source`d, and a name of `..` writes outside `.pi/skills/`. One rule closes all three, and it is
+ * deliberately a **whitelist**: the safe set here is small and the unsafe set is the rest of Unicode.
+ *
+ * The first character must be alphanumeric, so `..` and dotfiles are refused along with everything else.
+ */
+export function isSafeName(name: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
+}
+
+/**
+ * May this DECLARED capability id be written into the generated grant? — R-78.
+ *
+ * **R-77's other half, and the reason a whitelist beats a blocklist twice.** R-77 was closed on the name
+ * channel; the `allowed-tools` *value* travels to the identical interpolation site and was unchecked, so a
+ * package declaring
+ *
+ * ```yaml
+ * allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="
+ * ```
+ *
+ * produced a `.pi/grants.env` that executed arbitrary code the moment the operator ran the `source` line
+ * `init` itself prints. Reproduced end to end before this existed. `ceilingForDefinition` passes `ext:`,
+ * `skill:` and `agent:` entries through **as written** by design (a translation table would invent or drop
+ * grants), which is right for the enforcement path — the catalog refuses what it does not know — and is
+ * exactly why the check has to be here, at the boundary that *generates* rather than the one that enforces.
+ *
+ * The grammar is the one `docs/SPEC.md` documents: `tool:<name>`, `skill:<name>`, `agent:<name>`, and
+ * `ext:<pkg>/<tool>` where `<pkg>` may be npm-scoped. No wildcards — those are refused separately and
+ * loudly, because "you tried to grant yourself everything" is a different fact from "that is not a name".
+ */
+export function isSafeCapability(id: Capability): boolean {
+  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+  return (
+    new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+    new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
+  );
+}
+
+/** The two ids that confer root authority. A package declaring one is claiming it, not describing a need. */
+function wildcardsIn(capabilities: Capability[]): Capability[] {
+  return capabilities.filter((c) => c === WILDCARD || c === AGENT_WILDCARD);
+}
+
+/**
+ * Everything about one declared skill that would make it unsafe to scaffold. `null` when it is fine.
+ *
+ * Ordered so the operator is told the most actionable thing: a wildcard is a deliberate claim, an unsafe id
+ * is probably a typo or an attack, and a bad name is neither.
+ */
+function refusalFor(skill: DiscoveredSkill): RefusedSkill | null {
+  const name = skill.definition.name;
+  if (!isSafeName(name)) return { subject: name, reason: "unsafe-name", detail: [name] };
+
+  const ceiling = ceilingForDefinition(skill.definition);
+  const wildcards = wildcardsIn(ceiling.capabilities);
+  if (wildcards.length > 0) return { subject: name, reason: "wildcard", detail: wildcards };
+
+  const unsafe = ceiling.capabilities.filter((c) => !isSafeCapability(c));
+  if (unsafe.length > 0) return { subject: name, reason: "unsafe-capability", detail: unsafe };
+
+  return null;
+}
+
+/** One `pi.skills` entry: a directory holding `SKILL.md`, or a `.md` file — the same two shapes pi allows. */
+async function readSkill(packageDir: string, entry: string): Promise<DiscoveredSkill | "not-utf8" | null> {
+  const target = resolve(packageDir, entry);
+  // A manifest is data from another package, so an entry escaping its own directory is refused rather than
+  // followed. **`realpath`, not a lexical prefix test** (R-80): `resolve()` normalises `..` and knows
+  // nothing about symlinks, so a packaged symlink walked straight past the first version of this check and
+  // a definition from outside the package was copied in, with its `allowed-tools` landing in the operator's
+  // grant. Measured. This is the same lesson as the `realpathSync` fix in `cli.ts`, which was found by the
+  // smoke test one day earlier and not applied here.
+  const realPackageDir = await realpath(packageDir).catch(() => packageDir);
+  for (const path of [join(target, "SKILL.md"), ...(target.endsWith(".md") ? [target] : [])]) {
+    let bytes: Buffer;
+    try {
+      bytes = await readFile(path);
+    } catch {
+      continue;
+    }
+    const realPath = await realpath(path).catch(() => path);
+    if (!realPath.startsWith(realPackageDir + sep)) return null;
+
+    // "The file verbatim … nothing is lost in a round trip" is a claim this module makes, so bytes that
+    // cannot survive the round trip are refused rather than silently replaced. A latin-1 `0xE9` used to come
+    // back as U+FFFD, changing the file's length and its digest, with no warning.
+    const text = bytes.toString("utf8");
+    if (!Buffer.from(text, "utf8").equals(bytes)) return "not-utf8";
+
+    const definition = parseSkillDefinition(path, text);
+    return definition ? { definition, text, path } : null;
+  }
+  return null;
+}
+
+/** Read one installed package, if it declares skills. `null` means "not a skill package", not an error. */
+export async function readSkillPackage(packageDir: string): Promise<SkillPackage | null> {
+  let manifest: { name?: string; version?: string; pi?: { skills?: unknown } };
+  try {
+    manifest = JSON.parse(await readFile(join(packageDir, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+  const declared = manifest.pi?.skills;
+  if (!Array.isArray(declared) || declared.length === 0) return null;
+
+  const skills: DiscoveredSkill[] = [];
+  const unreadable: string[] = [];
+  const refused: RefusedSkill[] = [];
+  for (const entry of declared) {
+    if (typeof entry !== "string") continue;
+    const skill = await readSkill(packageDir, entry);
+    if (skill === null) {
+      unreadable.push(entry);
+    } else if (skill === "not-utf8") {
+      refused.push({ subject: entry, reason: "not-utf8", detail: [] });
+    } else {
+      const refusal = refusalFor(skill);
+      if (refusal) refused.push(refusal);
+      else skills.push(skill);
+    }
+  }
+
+  return {
+    name: manifest.name ?? packageDir.split(sep).pop() ?? "(unnamed)",
+    version: manifest.version ?? "(no version)",
+    unreadable,
+    refused,
+    skills,
+  };
+}
+
+/**
+ * Every installed package under `<cwd>/node_modules` that declares `pi.skills`, sorted by name.
+ *
+ * Top level and one scope deep, which is what npm's layout has. Nothing recurses into a dependency's own
+ * `node_modules`: a transitive skill package is not something an operator asked to install definitions
+ * from, and scaffolding one into their project would be a surprise wearing a helpful face.
+ */
+export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]> {
+  const root = join(cwd, "node_modules");
+  let entries: string[];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return []; // no node_modules is a normal state, not a failure
+  }
+
+  const dirs: string[] = [];
+  for (const entry of entries.sort()) {
+    if (entry.startsWith(".")) continue; // .bin, .package-lock.json
+    if (entry.startsWith("@")) {
+      try {
+        for (const scoped of (await readdir(join(root, entry))).sort()) dirs.push(join(root, entry, scoped));
+      } catch {
+        continue;
+      }
+    } else {
+      dirs.push(join(root, entry));
+    }
+  }
+
+  const packages: SkillPackage[] = [];
+  for (const dir of dirs) {
+    const found = await readSkillPackage(dir);
+    if (found) packages.push(found);
+  }
+  return packages.sort((a, b) => a.name.localeCompare(b.name));
+}