pi-daddy 0.28.0 → 0.32.1

package/src/kernel/correlation.ts

@@ -0,0 +1,351 @@
+import { createHash } from "node:crypto";
+import type { DefinitionDigest } from "./definitions.ts";
+import type { Capability } from "./resolve.ts";
+import { GovernanceRefusal, refusal } from "./refusals.ts";
+import { isLedgerCorrelationIdentifier } from "./ledger-identifiers.ts";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export interface AssuranceScope {
+  type: "entire-run" | "selectors";
+  selectors: string[];
+}
+
+/**
+ * Non-authoritative workflow metadata copied onto runtime and ledger events.
+ *
+ * pi-daddy interprets only the pinned correlation wire contract: schema version 1.0 and the closed
+ * assurance-scope shape. Labels, selector meanings, timestamps and sequence floors remain non-authoritative.
+ * In particular, a digest-looking value here never substitutes for a digest computed by the planner. The
+ * snake_case names are the wire vocabulary used by external controllers.
+ */
+export interface CorrelationMetadata {
+  schema_version?: string;
+  run_id?: string;
+  task_id?: string;
+  workspace_id?: string;
+  context_id?: string;
+  phase?: string;
+  assurance?: string;
+  assurance_effective?: string;
+  policy_label?: string;
+  assurance_source?: string;
+  assurance_scope?: AssuranceScope;
+  activated_at?: string;
+  plan_digest?: string;
+  definition_digest?: string;
+  task_digest?: string;
+  base_sha?: string;
+  head_sha?: string;
+  tree_sha?: string;
+  event_seq?: number;
+  last_change_seq?: number;
+  last_authority_seq?: number;
+  check_receipt_id?: string;
+}
+
+const MAX_CORRELATION_BYTES = 32 * 1024;
+/**
+ * Per-field bound on the STRING fields — most are an id, a digest, a label or a timestamp. It does not
+ * apply to the three sequence numbers or to `assurance_scope`, which are checked separately; an earlier
+ * version of this comment claimed it covered every declared field.
+ */
+const MAX_CORRELATION_FIELD_CHARS = 512;
+/** `assurance_scope` is the one structured field, so it gets its own, larger bound. */
+const MAX_CORRELATION_SCOPE_BYTES = 4 * 1024;
+
+/**
+ * The exact field set of the pinned schema 1.0 contract. Anything else is refused by name.
+ *
+ * This is a whitelist rather than a size cap because `correlation` is a MODEL-FACING tool parameter that
+ * is copied verbatim onto every append-only ledger event. `src/governance/ledger.ts` states the invariant — capability
+ * ids, counts and identifiers only, never prompts, tool arguments or results — and ADR-0034 repeats that the
+ * ledger must never carry task text. A 32 KB "bounded JSON object" with no key whitelist and no per-field
+ * length bound satisfied neither: `assurance_scope` was declared `Type.Any()`, undeclared keys survived the
+ * round trip, and every string was unbounded, so a model could write 32 KB of arbitrary text into the
+ * ledger through it (R-111). Refusing an unknown key is also the loud option: if upstream adds a field, the
+ * refusal names it, which is an actionable break rather than a silent secrets sink.
+ */
+const CORRELATION_FIELDS = new Set<keyof CorrelationMetadata>([
+  "schema_version",
+  "run_id",
+  "task_id",
+  "workspace_id",
+  "context_id",
+  "phase",
+  "assurance",
+  "assurance_effective",
+  "policy_label",
+  "assurance_source",
+  "assurance_scope",
+  "activated_at",
+  "plan_digest",
+  "definition_digest",
+  "task_digest",
+  "base_sha",
+  "head_sha",
+  "tree_sha",
+  "event_seq",
+  "last_change_seq",
+  "last_authority_seq",
+  "check_receipt_id",
+]);
+
+const CORRELATION_NUMERIC = new Set<keyof CorrelationMetadata>(["event_seq", "last_change_seq", "last_authority_seq"]);
+
+// These fields are rendered as labels/identities. Treating arbitrary prose as an "id" let a model copy
+// task or output text into the ledger and dashboard through correlation while staying schema-valid.
+const CORRELATION_IDENTIFIERS = new Set<keyof CorrelationMetadata>([
+  "schema_version",
+  "run_id",
+  "task_id",
+  "workspace_id",
+  "context_id",
+  "phase",
+  "assurance",
+  "assurance_effective",
+  "policy_label",
+  "assurance_source",
+]);
+
+function correlationRefusal(message: string, details?: Record<string, string | number>): GovernanceRefusal {
+  return new GovernanceRefusal(refusal("CORRELATION_INVALID", `correlation metadata: ${message}`, details));
+}
+
+/**
+ * Size refusals get their own code, because they call for a different response: "you sent too much" is
+ * retryable by truncating, "you sent a field we do not recognise" is not. `CORRELATION_TOO_LARGE` was
+ * declared in the taxonomy and constructed nowhere, so the union advertised a distinction the code did not
+ * make — and the enumeration test kept the dead member green.
+ */
+function correlationTooLarge(message: string, details?: Record<string, string | number>): GovernanceRefusal {
+  return new GovernanceRefusal(refusal("CORRELATION_TOO_LARGE", `correlation metadata: ${message}`, details));
+}
+
+function normaliseAssuranceScope(value: unknown): AssuranceScope {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw correlationRefusal("assurance_scope must be an object with type and selectors");
+  }
+  const scope = value as Record<string, unknown>;
+  const keys = Object.keys(scope).sort();
+  if (keys.length !== 2 || keys[0] !== "selectors" || keys[1] !== "type") {
+    throw correlationRefusal("assurance_scope must contain only type and selectors");
+  }
+  if (
+    !Array.isArray(scope.selectors) ||
+    !scope.selectors.every((selector) => typeof selector === "string" && selector.length > 0)
+  ) {
+    throw correlationRefusal("assurance_scope selectors must be non-empty strings");
+  }
+  if (scope.type === "entire-run") {
+    if (scope.selectors.length !== 0) throw correlationRefusal("entire-run assurance_scope requires empty selectors");
+    return { type: "entire-run", selectors: [] };
+  }
+  if (scope.type === "selectors") {
+    if (scope.selectors.length === 0) throw correlationRefusal("selectors scope requires at least one selector");
+    return { type: "selectors", selectors: [...scope.selectors] };
+  }
+  throw correlationRefusal("assurance_scope type must be entire-run or selectors");
+}
+
+/**
+ * Snapshot bounded JSON metadata so a caller cannot mutate a record after planning, and so nothing
+ * unbounded or undeclared can reach the ledger through it.
+ *
+ * Refuses with a stable code rather than a bare `Error`: this is reachable from a model-facing tool
+ * parameter on all three delegation tools, and it used to throw outside every try, producing a governed
+ * refusal with no code and no ledger line at all (R-112).
+ */
+export function normaliseCorrelation(input: CorrelationMetadata | undefined): CorrelationMetadata | undefined {
+  if (input === undefined) return undefined;
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(input);
+  } catch (error) {
+    throw correlationRefusal(`must be JSON serializable (${String(error)})`);
+  }
+  if (encoded === undefined) throw correlationRefusal("must be a JSON object");
+  if (Buffer.byteLength(encoded) > MAX_CORRELATION_BYTES) {
+    throw correlationTooLarge(`exceeds ${MAX_CORRELATION_BYTES} bytes`, { limit: MAX_CORRELATION_BYTES });
+  }
+  const parsed = JSON.parse(encoded) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw correlationRefusal("must be a JSON object");
+  }
+
+  const source = parsed as Record<string, unknown>;
+  const undeclared = Object.keys(source).filter((key) => !CORRELATION_FIELDS.has(key as keyof CorrelationMetadata));
+  if (undeclared.length > 0) {
+    throw correlationRefusal(`carries fields outside the pinned schema 1.0 contract: ${undeclared.sort().join(", ")}`, {
+      undeclared: undeclared.sort().join(","),
+    });
+  }
+
+  const output: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined || value === null) continue;
+    if (key === "assurance_scope") {
+      const size = Buffer.byteLength(JSON.stringify(value) ?? "");
+      if (size > MAX_CORRELATION_SCOPE_BYTES) {
+        throw correlationTooLarge(`assurance_scope exceeds ${MAX_CORRELATION_SCOPE_BYTES} bytes`, {
+          limit: MAX_CORRELATION_SCOPE_BYTES,
+          actual: size,
+        });
+      }
+      output[key] = normaliseAssuranceScope(value);
+      continue;
+    }
+    if (CORRELATION_NUMERIC.has(key as keyof CorrelationMetadata)) {
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw correlationRefusal(`${key} must be a finite number`, { field: key });
+      }
+      output[key] = value;
+      continue;
+    }
+    if (typeof value !== "string") throw correlationRefusal(`${key} must be a string`, { field: key });
+    if (key === "schema_version" && value !== "1.0") {
+      throw correlationRefusal(`unsupported schema_version ${value}; supported version is 1.0`, {
+        field: key,
+        supported: "1.0",
+      });
+    }
+    if (value.length > MAX_CORRELATION_FIELD_CHARS) {
+      throw correlationTooLarge(`${key} exceeds ${MAX_CORRELATION_FIELD_CHARS} characters`, {
+        field: key,
+        limit: MAX_CORRELATION_FIELD_CHARS,
+        actual: value.length,
+      });
+    }
+    if (CORRELATION_IDENTIFIERS.has(key as keyof CorrelationMetadata) && !isLedgerCorrelationIdentifier(value)) {
+      throw correlationRefusal(`${key} must be an ASCII identifier, not free-form text`, { field: key });
+    }
+    output[key] = value;
+  }
+  return output as CorrelationMetadata;
+}
+
+export function digestTask(task: string): string {
+  return createHash("sha256").update(task, "utf8").digest("hex");
+}
+
+export function digestCapabilities(capabilities: readonly Capability[]): string {
+  const canonical = [...new Set(capabilities)].sort();
+  return createHash("sha256").update(JSON.stringify(canonical), "utf8").digest("hex");
+}
+
+/** Trusted, internally-computed scope of one gated approval. */
+export interface ApprovalBinding {
+  version: "1";
+  task_sha256: string;
+  requested_sha256: string;
+  effective_sha256: string;
+  requested: Capability[];
+  effective: Capability[];
+  definition_sha256?: string;
+  workspace_id?: string;
+  context_id?: string;
+  tree_sha?: string;
+  last_change_seq?: number;
+  parent_id: string;
+}
+
+/**
+ * Builds the binding from TRUSTED values only. It deliberately does not take a `CorrelationMetadata`.
+ *
+ * It used to read `workspace_id` and `context_id` straight out of caller-supplied correlation into what
+ * the comment above calls the trusted scope, and a bound approval could then be spent outside the
+ * workspace it named (R-110): approve a delegation carrying a real, registry-validated `workspace` spec,
+ * then re-issue the identical task with `correlation.workspace_id` set and NO `workspace` field — no
+ * registry lookup, no lease, the parent's own cwd, and every digest still matching. The guard that would
+ * have caught it can only fire when there is a spec to disagree with.
+ *
+ * `workspaceId` must therefore be the id of a workspace that was actually resolved and leased.
+ * `contextId` is a caller-declared label that nothing validates; it is included because it can only
+ * ever NARROW a binding, and a mismatch fails closed.
+ */
+export function buildApprovalBinding(input: {
+  task: string;
+  requested: readonly Capability[];
+  effective: readonly Capability[];
+  definitionSha256?: DefinitionDigest["sha256"] | string;
+  parentId: string;
+  /** Id of a workspace this delegation was actually routed to and holds a lease for. */
+  workspaceId?: string;
+  /** Caller-declared label. Narrows only; never a claim that anything was enforced. */
+  contextId?: string;
+  /** Optional upstream tree identity. When supplied, later approval use must match it exactly. */
+  treeSha?: string;
+  /** Optional upstream change floor. When supplied, later approval use must match it exactly. */
+  lastChangeSeq?: number;
+}): ApprovalBinding {
+  const requested = [...new Set(input.requested)].sort();
+  const effective = [...new Set(input.effective)].sort();
+  return {
+    version: "1",
+    task_sha256: digestTask(input.task),
+    requested_sha256: digestCapabilities(requested),
+    effective_sha256: digestCapabilities(effective),
+    requested,
+    effective,
+    ...(input.definitionSha256 ? { definition_sha256: input.definitionSha256 } : {}),
+    ...(input.workspaceId ? { workspace_id: input.workspaceId } : {}),
+    ...(input.contextId ? { context_id: input.contextId } : {}),
+    ...(input.treeSha !== undefined ? { tree_sha: input.treeSha } : {}),
+    ...(input.lastChangeSeq !== undefined ? { last_change_seq: input.lastChangeSeq } : {}),
+    parent_id: input.parentId,
+  };
+}
+
+export function approvalBindingDigest(binding: ApprovalBinding): string {
+  const ordered = {
+    version: binding.version,
+    task_sha256: binding.task_sha256,
+    requested_sha256: binding.requested_sha256,
+    effective_sha256: binding.effective_sha256,
+    requested: binding.requested,
+    effective: binding.effective,
+    definition_sha256: binding.definition_sha256 ?? null,
+    workspace_id: binding.workspace_id ?? null,
+    context_id: binding.context_id ?? null,
+    // Keep the exact pre-ADR-0039 serialization when both additions are absent: persisted approvals store
+    // this digest, so unconditional null placeholders would invalidate every existing bound approval.
+    ...(binding.tree_sha !== undefined ? { tree_sha: binding.tree_sha } : {}),
+    ...(binding.last_change_seq !== undefined ? { last_change_seq: binding.last_change_seq } : {}),
+    parent_id: binding.parent_id,
+  };
+  return createHash("sha256").update(JSON.stringify(ordered), "utf8").digest("hex");
+}
+
+export function isApprovalBinding(value: unknown): value is ApprovalBinding {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const binding = value as Partial<ApprovalBinding>;
+  return (
+    binding.version === "1" &&
+    [binding.task_sha256, binding.requested_sha256, binding.effective_sha256].every(
+      (digest) => typeof digest === "string" && /^[a-f0-9]{64}$/i.test(digest),
+    ) &&
+    Array.isArray(binding.requested) &&
+    binding.requested.every((item) => typeof item === "string") &&
+    Array.isArray(binding.effective) &&
+    binding.effective.every((item) => typeof item === "string") &&
+    typeof binding.parent_id === "string" &&
+    ["definition_sha256", "workspace_id", "context_id", "tree_sha"].every((key) => {
+      const value = (binding as Record<string, unknown>)[key];
+      return value === undefined || typeof value === "string";
+    }) &&
+    (binding.last_change_seq === undefined ||
+      (typeof binding.last_change_seq === "number" && Number.isFinite(binding.last_change_seq))) &&
+    // Self-consistency. This guard's only trust boundary is a binding parsed off DISK
+    // (`approval-store.ts`), so an internally contradictory record — digests that do not match the
+    // capability arrays sitting beside them — must be unrepresentable rather than merely unlikely.
+    binding.requested_sha256 === digestCapabilities(binding.requested as Capability[]) &&
+    binding.effective_sha256 === digestCapabilities(binding.effective as Capability[])
+  );
+}
+
+export function approvalBindingsEqual(a: ApprovalBinding | undefined, b: ApprovalBinding | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  if (!isApprovalBinding(a) || !isApprovalBinding(b)) return false;
+  return approvalBindingDigest(a) === approvalBindingDigest(b);
+}

package/src/kernel/definitions.ts

@@ -0,0 +1,215 @@
+/**
+ * Agent Skills (`SKILL.md`) as this package's definition format — ADR-0016.
+ *
+ * A subagent is a skill you spawn: the `SKILL.md` body becomes the child's system prompt
+ * (`--append-system-prompt`) and `allowed-tools` becomes its capability ceiling, enforced through
+ * `--tools`. That collapses a duplication `principal-pi-skills` already strains against, where
+ * `plan`/`review`/`debug` exist twice — once as a skill and once as a subagent prompt — and are
+ * generated from one contract precisely so the two cannot drift.
+ *
+ * **The spec's own words about `allowed-tools`:** *"a space-separated string of tools that are
+ * pre-approved to run"*, marked **experimental**. Pre-approved, not enforced — the field declares intent
+ * and blocks nothing, and implementations differ on whether they honour it at all. Turning that
+ * declaration into something structural is this package's entire value here.
+ *
+ * **One inversion is deliberate and load-bearing.** In pi-subagents' frontmatter an absent `tools:` key
+ * means *pi's full default toolset*, so an undeclared definition was the most powerful kind and any
+ * parse failure produced a wildcard — the direction that caused R-28 and review finding F18. Here an
+ * absent `allowed-tools` means **undeclared, therefore not spawnable**. A typo or an unreadable YAML
+ * form now costs a refusal instead of a grant.
+ */
+
+import { createHash } from "node:crypto";
+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";
+
+/**
+ * Identifies WHICH instructions a child was given, without reproducing them (ADR-0018).
+ *
+ * The ledger's standing rule is *capability ids, counts and identifiers only — never prompts, tool
+ * arguments or results*. A hash is an identifier: it names a version of an operator-authored file. The
+ * **task** is model-assembled from the parent's context and is never recorded anywhere, by decision.
+ */
+export interface DefinitionDigest {
+  name: string;
+  /** Where the definition was read from, so a reader can go and rehash it. */
+  source: string;
+  /** SHA-256 of the body — the exact text passed as `--append-system-prompt`. */
+  sha256: string;
+}
+
+/**
+ * Digest a definition's body.
+ *
+ * Over the **body alone**, deliberately: that is precisely the text the child receives, so a digest that
+ * also covered the frontmatter would change when `description` was reworded and report an instruction
+ * change that never happened. `allowed-tools` is already recorded in full on every record.
+ */
+export function digestDefinition(definition: SkillDefinition): DefinitionDigest {
+  return {
+    name: definition.name,
+    source: definition.source,
+    sha256: createHash("sha256").update(definition.body, "utf8").digest("hex"),
+  };
+}
+
+export interface SkillDefinition {
+  /** From the path, never the frontmatter — see `parseSkillDefinition`. */
+  name: string;
+  description: string;
+  /** Raw `allowed-tools` value. `undefined` means the key was absent; `""` means it declared none. */
+  allowedTools?: string;
+  /** The spec's sanctioned extension point: a map of string keys to string values. */
+  metadata?: Record<string, string>;
+  /** Everything after the frontmatter — the child's system prompt. */
+  body: string;
+  source: string;
+}
+
+export interface DefinitionCeiling {
+  /** The declared capabilities, as this package's ids. */
+  capabilities: Capability[];
+  /**
+   * Entries carrying a sub-tool pattern, e.g. `Bash(git:*)`.
+   *
+   * ADR-0016 refuses these rather than reinterpreting them, because every reinterpretation is wrong:
+   * granting bare `bash` **widens** a deliberately narrow declaration, dropping the tool silently
+   * **narrows** and yields a child that mysteriously cannot work, and matching patterns inside a wrapper
+   * would be a security control implemented by string-matching a shell command. Non-empty means the
+   * caller must refuse and say so.
+   */
+  patterns: string[];
+  /** The `allowed-tools` key was absent entirely: the definition is not spawnable. */
+  undeclared: boolean;
+}
+
+/**
+ * Read a `SKILL.md`.
+ *
+ * The frontmatter reader handles the subset these files use — `key: value`, block scalars (`>` / `|`),
+ * and a one-level `metadata:` map. Anything it cannot read leaves the key **absent**, which for
+ * `allowed-tools` means *undeclared* and therefore refused. That is the whole reason this parser can be
+ * hand-rolled without the hazard its sibling in `agent-types.ts` carries.
+ */
+export function parseSkillDefinition(source: string, text: string): SkillDefinition | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) return null;
+
+  const fields = new Map<string, string>();
+  const metadata: Record<string, string> = {};
+  const lines = match[1].split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const kv = /^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[i]);
+    if (!kv) continue;
+    const [, key, rawValue] = kv;
+    const value = rawValue.trim();
+
+    // A folded/literal scalar: fold the indented continuation into one line. `principal-pi-skills`
+    // writes every description this way, and the sibling parser SKIPS these — which is safe there only
+    // because it never needs the value. Here a skipped `description` would be a missing required field.
+    if (value === ">" || value === "|") {
+      const parts: string[] = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        if (!/^\s+\S/.test(lines[j])) break;
+        parts.push(lines[j].trim());
+        i = j;
+      }
+      fields.set(key, parts.join(" "));
+      continue;
+    }
+
+    // `metadata:` introduces a one-level map of string keys to string values (the spec's shape).
+    if (key === "metadata" && value === "") {
+      for (let j = i + 1; j < lines.length; j++) {
+        const item = /^\s+([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(lines[j]);
+        if (!item) break;
+        metadata[item[1]] = item[2].trim().replace(/^["']|["']$/g, "");
+        i = j;
+      }
+      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);
+  }
+
+  const description = fields.get("description");
+  if (description === undefined) return null;
+
+  return {
+    // Identity comes from the PATH. ADR-0013 learned this the hard way on the other format: pi keys
+    // 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: skillResourceName(source),
+    description,
+    allowedTools: fields.get("allowed-tools"),
+    metadata: Object.keys(metadata).length > 0 ? metadata : undefined,
+    body: text.slice(match[0].length).trim(),
+    source,
+  };
+}
+
+/**
+ * Turn a definition's `allowed-tools` into a capability ceiling.
+ *
+ * Name mapping is **lowercasing and nothing else**, deliberately. A translation table from Claude
+ * Code's names to pi's would have to decide what `Glob` means, and pi has no glob tool — so the table
+ * would either invent a grant or quietly drop one. Lowercasing leaves `Glob` as `tool:glob`, which the
+ * catalog then refuses as unknown, naming the actual problem to whoever wrote the file.
+ */
+export function ceilingForDefinition(definition: SkillDefinition): DefinitionCeiling {
+  const raw = definition.allowedTools;
+  if (raw === undefined) return { capabilities: [], patterns: [], undeclared: true };
+
+  const capabilities = new Set<Capability>();
+  const patterns: string[] = [];
+
+  // The spec says space-separated. Commas are tolerated because `Read, Grep` is what people type, and
+  // accepting them grants nothing extra — it only avoids a comma becoming part of a capability name.
+  for (const entry of raw.split(/[\s,]+/).filter((e) => e.length > 0)) {
+    if (entry.includes("(")) {
+      patterns.push(entry);
+      continue;
+    }
+    // Every namespaced id passes through untouched; only a BARE tool name gets the `tool:` prefix and the
+    // lowercasing. `workspace:` was missing here after ADR-0035 taught `normaliseCapability` about it, so a
+    // definition declaring `allowed-tools: workspace:prod` produced `tool:workspace:prod` — a capability
+    // that names nothing, refused as unknown, and dropped by `init` as "probably a typo or an attack". Two
+    // spellings of one grammar with this one wrong is R-28's shape; the list is now shared.
+    if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => entry.startsWith(prefix))) {
+      capabilities.add(entry);
+      continue;
+    }
+    capabilities.add(`tool:${entry.toLowerCase()}`);
+  }
+
+  return { capabilities: [...capabilities].sort(), patterns, undeclared: false };
+}
+
+/**
+ * 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 { 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;
+}