pi-daddy 0.27.0 → 0.27.2

package/src/cli.ts

@@ -28,7 +28,7 @@ import { panelText } from "./daily-panel.ts";
 const USAGE = `pi-daddy — capability governance for pi sub-agents
 
 Usage:
-  pi-daddy init [--force] [--dir <path>]   scaffold .pi/skills/ and .pi/grants.env from installed
+  pi-daddy init [--force] [--dir <path>]   prepare .pi/grants.env from enabled installed
                                            packages that declare skills (package.json "pi": {"skills": …})
   pi-daddy work add --id <id> --outcome <text> [--dir <path>]
                                            declare one current obligation for ordinary delegation
@@ -39,12 +39,12 @@ Usage:
   pi-daddy guide | current               installed product guide / current requirement register
   pi-daddy --help | --version
 
-init copies each declared SKILL.md into .pi/skills/ and writes a grant naming exactly what those files
-declare. It never chooses a ceiling: a skill declaring no \`allowed-tools\` is copied with a commented
-placeholder and stays unspawnable until you fill it in. Capabilities that can change your machine
+init references skills already enabled in Pi at their installed or local paths. Legacy unregistered npm
+skills are copied into .pi/skills/. It never chooses a ceiling: missing or unusable \`allowed-tools\`
+stays unspawnable. Capabilities that can change your machine
 (bash, write, edit) are written COMMENTED — uncomment them deliberately. Review the files, then commit.
 
-  --force   rewrite the SKILL.md copies that already exist. This DISCARDS any \`allowed-tools\` you added.
+  --force   rewrite legacy unregistered npm SKILL.md copies that already exist. This DISCARDS any \`allowed-tools\` you added.
             It never rewrites .pi/grants.env — delete that file if you want it regenerated.`;
 
 export interface ParsedArgs {
@@ -131,7 +131,7 @@ async function init(cwd: string, force: boolean): Promise<number> {
     // `pi install npm:principal-pi-skills`, which installs to the agent root, was told to install a package
     // they had already installed (R-75).
     console.log(
-      `pi-daddy init: no installed package declares skills (a package.json "pi": {"skills": [...]} ` +
+      `pi-daddy init: no enabled configured skills or unregistered npm package declares skills (a package.json "pi": {"skills": [...]} ` +
         `field). Nothing to scaffold.\n\nLooked in:\n` +
         skillPackageRoots(cwd).map((r) => `  ${r}\n`).join("") +
         `\n  pi install npm:principal-pi-skills    # seven skills, and registers it with pi\n` +
@@ -171,7 +171,7 @@ async function init(cwd: string, force: boolean): Promise<number> {
   // `--force` is destructive and says so at the moment it acts, not only in `--help` — which is the one
   // place the operator running the command is not reading.
   if (force) {
-    const existing = plan.skills.length;
+    const existing = plan.skills.filter(s => !s.referenced).length;
     console.log(
       `\n--force: rewriting up to ${existing} SKILL.md cop${existing === 1 ? "y" : "ies"} from the installed\n` +
         `packages. Any \`allowed-tools\` you wrote in them is DISCARDED. .pi/grants.env is never rewritten.`,
@@ -180,6 +180,7 @@ async function init(cwd: string, force: boolean): Promise<number> {
 
   const outcome = await applyInit(plan, { force });
   const short = (path: string) => relative(cwd, path) || path;
+  for (const skill of plan.skills.filter(s => s.referenced)) console.log(`using ${short(skill.sourcePath)} (enabled in Pi; no copy)`);
   for (const path of outcome.written) console.log(`wrote ${short(path)}`);
   for (const path of outcome.kept) console.log(`kept  ${short(path)} (already present — left exactly as it is)`);
   for (const failure of outcome.failed) console.error(`FAILED ${short(failure.path)}: ${failure.error}`);

package/src/definitions.ts

@@ -20,9 +20,8 @@
  */
 
 import { createHash } from "node:crypto";
-import { readFile, readdir } from "node:fs/promises";
-import { join } from "node:path";
-import { skillDirs } from "./catalog.ts";
+import { readFile } from "node:fs/promises";
+import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { CAPABILITY_NAMESPACE_PREFIXES } from "./capabilities.ts";
 import type { Capability } from "./resolve.ts";
 
@@ -133,6 +132,11 @@ export function parseSkillDefinition(source: string, text: string): SkillDefinit
       continue;
     }
 
+    // A YAML collection/block we cannot parse is not an explicit empty ceiling.
+    if (key === "allowed-tools" && value === "") {
+      const nextValue = lines.slice(i + 1).find(line => line.trim() !== "" && !/^\s*#/.test(line));
+      if (/^\s+\S/.test(nextValue ?? "")) continue;
+    }
     fields.set(key, value);
   }
 
@@ -144,7 +148,7 @@ export function parseSkillDefinition(source: string, text: string): SkillDefinit
     // skills by their directory, so trusting a frontmatter `name` lets our view and the loader's
     // disagree about which file a name refers to. The spec requires `name` to match the parent
     // directory anyway, so a mismatch is the file's defect and not something to honour.
-    name: nameFromPath(source),
+    name: skillResourceName(source),
     description,
     allowedTools: fields.get("allowed-tools"),
     metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
@@ -153,14 +157,6 @@ export function parseSkillDefinition(source: string, text: string): SkillDefinit
   };
 }
 
-/** `/skills/review/SKILL.md` -> `review`; `/skills/triage.md` -> `triage`. */
-function nameFromPath(source: string): string {
-  const parts = source.split("/").filter((p) => p.length > 0);
-  const last = parts.at(-1) ?? "";
-  if (last.toLowerCase() === "skill.md") return parts.at(-2) ?? "";
-  return last.replace(/\.md$/i, "");
-}
-
 /**
  * Turn a definition's `allowed-tools` into a capability ceiling.
  *
@@ -199,41 +195,17 @@ export function ceilingForDefinition(definition: SkillDefinition): DefinitionCei
 }
 
 /**
- * Discover `SKILL.md` definitions under pi's skill roots.
- *
- * Deliberately the SAME roots and the same convention the catalog uses (`skillDirs`): a directory
- * containing `SKILL.md` is one definition named after the directory, and a top-level `.md` is one named
- * after the file. If discovery and the catalog disagreed, a definition could be spawnable but not
- * grantable, or listed but unspawnable.
- *
- * Earlier directories win on a name collision, matching pi's own precedence — project before global.
+ * Read definitions from Pi's enabled resources, including installed packages and local overrides.
+ * Resolver precedence and filters are shared with the capability catalog; unregistered npm packages
+ * are not runtime resources until legacy init explicitly scaffolds them.
  */
 export async function loadDefinitions(cwd: string): Promise<Map<string, SkillDefinition>> {
   const definitions = new Map<string, SkillDefinition>();
-  for (const dir of skillDirs(cwd)) {
-    let names: string[];
-    try {
-      names = await readdir(dir);
-    } catch {
-      continue; // an absent skill root is normal
-    }
-    for (const name of [...names].sort()) {
-      // A directory holding SKILL.md, or a top-level .md — try the former first, exactly as the
-      // catalog does, so the two cannot disagree about what exists.
-      const candidates = [join(dir, name, "SKILL.md"), ...(name.endsWith(".md") ? [join(dir, name)] : [])];
-      for (const path of candidates) {
-        let text: string;
-        try {
-          text = await readFile(path, "utf8");
-        } catch {
-          continue; // not this shape; try the next candidate
-        }
-        const parsed = parseSkillDefinition(path, text);
-        // First writer wins, so project definitions shadow global ones rather than the reverse.
-        if (parsed && !definitions.has(parsed.name)) definitions.set(parsed.name, parsed);
-        break;
-      }
-    }
+  for (const { path } of (await resolveSkillResources(cwd)).skills) {
+    let text: string;
+    try { text = await readFile(path, "utf8"); } catch { continue; }
+    const parsed = parseSkillDefinition(path, text);
+    if (parsed && !definitions.has(parsed.name)) definitions.set(parsed.name, parsed);
   }
   return definitions;
 }

package/src/init.ts

@@ -1,9 +1,9 @@
 /**
  * `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.
+ * Legacy unregistered npm packages can be scaffolded per skill: create a directory, copy the
+ * body and declaration copies plus a starting `PI_GRANTS_GRANT`. Configured enabled Pi resources
+ * are referenced where installed instead (ADR-0074); no competing .pi/skills copy is created.
  *
  * **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
@@ -32,23 +32,9 @@ 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.
+ * Count declarations, not authorizations (R-73). Both pattern and needs-withheld mean the skill
+ * declared a ceiling; only undeclared means it did not. The CLI must report the same distinction.
  */
 export function countDeclaring(skills: PlannedSkill[], from: string): number {
   return skills.filter((s) => s.from === from && s.withheld !== "undeclared").length;
@@ -62,6 +48,8 @@ export interface PlannedSkill {
   from: string;
   sourcePath: string;
   targetPath: string;
+  /** Configured skills stay at their installed/local source, including when --force is used. */
+  referenced?: boolean;
   /** 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. */
@@ -191,7 +179,8 @@ export function planInit(
         name,
         from: `${pkg.name}@${pkg.version}`,
         sourcePath: skill.path,
-        targetPath: join(cwd, ".pi", "skills", name, "SKILL.md"),
+        targetPath: skill.referenced ? skill.path : join(cwd, ".pi", "skills", name, "SKILL.md"),
+        referenced: skill.referenced,
         content: withPlaceholder(skill.text, withheld === null, note),
         ceiling: ceiling.capabilities,
         withheld,
@@ -391,6 +380,7 @@ export async function applyInit(plan: InitPlan, options: { force?: boolean } = {
   }
   const force = options.force === true;
   for (const skill of plan.skills) {
+    if (skill.referenced) continue;
     if (force) await replace(skill.targetPath, skill.content, outcome);
     else await createUnlessPresent(skill.targetPath, skill.content, outcome);
   }

package/src/skill-packages.ts

@@ -1,34 +1,15 @@
 /**
- * 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.
+ * Setup discovers enabled Pi resources in place through its package resolver. Configured packages
+ * are never copied into another autoload root. For legacy npm installs unregistered with Pi only,
+ * the explicit package.json pi.skills declaration remains a scaffold source (ADR-0074).
+ * Names, ceilings and bytes are checked before they can enter the generated shell grant.
  */
 
 import { readdir, readFile, realpath } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
 import { ceilingForDefinition, parseSkillDefinition, type SkillDefinition } from "./definitions.ts";
+import { resolveSkillResources, skillResourceName } from "./skill-resources.ts";
 import { WILDCARD } from "./pi-tools.ts";
 import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
 import { isSafeCapability } from "./capabilities.ts";
@@ -38,6 +19,8 @@ export interface DiscoveredSkill {
   /** The file verbatim. `init` copies it rather than regenerating it, so nothing is lost in a round trip. */
   text: string;
   path: string;
+  /** Already enabled by Pi; setup must reference it rather than making a competing copy. */
+  referenced?: boolean;
 }
 
 /** Why a declared skill was refused before it could be planned. Each has a different fix. */
@@ -248,21 +231,63 @@ export function skillPackageRoots(cwd: string): string[] {
 }
 
 export async function discoverSkillPackages(cwd: string): Promise<SkillPackage[]> {
+  const resolved = await resolveSkillResources(cwd);
+  const packages: SkillPackage[] = [];
+  const seenSkills = new Set<string>();
+  const runtimeNames = new Set(resolved.skills.map(s => skillResourceName(s.path)));
+  const configuredRoots = new Set(resolved.configured.flatMap(p => p.installedPath ? [resolve(p.installedPath)] : []));
+  const configuredNames = new Set<string>(resolved.configured.flatMap(p => {
+    if (!p.source.startsWith("npm:")) return [];
+    const spec = p.source.slice(4);
+    const versionAt = spec.indexOf("@", 1);
+    return [versionAt < 0 ? spec : spec.slice(0, versionAt)];
+  }));
+  for (const root of configuredRoots) {
+    try { configuredNames.add(JSON.parse(await readFile(join(root, "package.json"), "utf8")).name); } catch { /* absent */ }
+  }
+  for (const resource of resolved.skills) {
+    const bytes = await readFile(resource.path).catch(() => null);
+    if (bytes === null) continue;
+    const text = bytes.toString("utf8");
+    const resourceName = skillResourceName(resource.path);
+    if (seenSkills.has(resourceName)) continue;
+    seenSkills.add(resourceName);
+    let name = resource.metadata.source;
+    let version = "local";
+    if (resource.metadata.origin === "package" && resource.metadata.baseDir) {
+      try {
+        const manifest = JSON.parse(await readFile(join(resource.metadata.baseDir, "package.json"), "utf8"));
+        name = manifest.name ?? name; version = manifest.version ?? version;
+      } catch { /* the resource can be used without optional display metadata */ }
+    } else name = `${resource.metadata.scope} skills`;
+    let pkg = packages.find(p => p.name === name && p.version === version);
+    if (!pkg) { pkg = { name, version, skills: [], refused: [], unreadable: [] }; packages.push(pkg); }
+    if (!Buffer.from(text, "utf8").equals(bytes)) {
+      pkg.refused.push({ subject: resourceName, reason: "not-utf8", detail: [] });
+      continue;
+    }
+    const definition = parseSkillDefinition(resource.path, text);
+    if (!definition) continue;
+    const skill = { definition, text, path: resource.path, referenced: true };
+    const refusal = refusalFor(skill);
+    if (refusal) pkg.refused.push(refusal); else pkg.skills.push(skill);
+  }
+
+  // Compatibility for npm installs that were never registered with Pi. Runtime discovery never scans
+  // node_modules. A configured package (including one disabled by a filter) must not re-enter here.
   const dirs: string[] = [];
-  const seenNames = new Set<string>();
   for (const root of skillPackageRoots(cwd)) await collectFrom(root, dirs);
-
-  const packages: SkillPackage[] = [];
+  const seenNames = new Set(packages.map(p => p.name));
   for (const dir of dirs) {
+    if (configuredRoots.has(resolve(dir))) continue;
     const found = await readSkillPackage(dir);
-    // First root wins on a name collision: the project's pinned copy outranks the machine-wide one, and
-    // silently preferring the other would make a committed lockfile stop meaning anything.
-    if (found && !seenNames.has(found.name)) {
-      seenNames.add(found.name);
-      packages.push(found);
-    }
+    if (!found || configuredNames.has(found.name) || seenNames.has(found.name)) continue;
+    seenNames.add(found.name);
+    found.skills = found.skills.filter(skill => !runtimeNames.has(skill.definition.name));
+    packages.push(found);
   }
-  return packages.sort((a, b) => a.name.localeCompare(b.name));
+  return packages;
+
 }
 
 /** Append every package directory under one `node_modules`, scoped packages included. */

package/src/skill-resources.ts

@@ -0,0 +1,48 @@
+/** Read Pi's configured resource surface without locks, installs, extension execution or model calls. */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { DefaultPackageManager, getAgentDir, SettingsManager } from "@earendil-works/pi-coding-agent";
+
+interface SkillResources {
+  skills: { path: string; enabled: boolean; metadata: { source: string; scope: string; origin: string; baseDir?: string } }[];
+  configured: { source: string; scope: string; installedPath?: string }[];
+}
+
+export function skillResourceName(path: string): string {
+  const parts = path.split(/[\\/]/);
+  const file = parts.at(-1) ?? "";
+  return file.toLowerCase() === "skill.md" ? parts.at(-2) ?? "" : file.replace(/\.md$/i, "");
+}
+
+export async function resolveSkillResources(cwd: string): Promise<SkillResources> {
+  const agentDir = getAgentDir();
+  const settingsManager = SettingsManager.fromStorage({
+    withLock(scope, read) {
+      const path = scope === "global" ? join(agentDir, "settings.json") : join(cwd, ".pi", "settings.json");
+      let text: string | undefined;
+      try { text = readFileSync(path, "utf8"); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; }
+      // This storage is intentionally read-only: no lock files or migrated settings are persisted.
+      read(text);
+    },
+  });
+  const errors = settingsManager.drainErrors();
+  if (errors.length) throw new Error(`Cannot discover skills: ${errors.map(e => `${e.scope} settings: ${e.error.message}`).join("; ")}`);
+  const manager = new DefaultPackageManager({ cwd, agentDir, settingsManager });
+  const resolved = await manager.resolve(async () => "skip");
+  // Pi has already applied package identity, scope, manifest and settings filters and precedence.
+  const seen = new Set<string>();
+  const skills = resolved.skills.filter(resource => resource.enabled).flatMap(resource => {
+    try {
+      const path = statSync(resource.path).isDirectory() ? join(resource.path, "SKILL.md") : resource.path;
+      return statSync(path).isFile() ? [{ ...resource, path }] : [];
+    } catch { return []; }
+  }).filter(resource => {
+    // Reserve identity before parsing: a malformed local override cannot reveal a wider package ceiling.
+    const name = skillResourceName(resource.path);
+    if (seen.has(name)) return false;
+    seen.add(name);
+    return true;
+  });
+  return { skills, configured: manager.listConfiguredPackages() };
+}