skilldrop-cli 0.16.26 → 0.16.28

package/bin/governance.js

@@ -0,0 +1,273 @@
+/* Organisation governance (RFC-0050, OWASP AST09): a policy the installer enforces, an audit
+   log that shows when its history was edited, and a check that a mirror still matches what was
+   packaged. Node's standard library only, like the rest of the CLI.
+
+   The policy is a JSON file an organisation hands out (MDM, a dotfiles repo, an image):
+     --policy <file>  >  SKILLDROP_POLICY  >  ~/.config/skilldrop/policy.json
+   A policy that is named but missing, unreadable, or carries a key this version doesn't know
+   stops the command: a policy that fails open is not a policy. */
+"use strict";
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const crypto = require("crypto");
+const { execFileSync } = require("child_process");
+
+const SEVERITY = { "🟥": 3, "🟧": 2, "🟨": 1 };          // scan findings; ⚪ (fixtures) never count
+const MAX = { none: 0, low: 1, medium: 2, high: 3 };      // policy scan.max: the worst finding allowed
+const KEYS = {
+  "": ["version", "catalogues", "skills", "scan", "audit", "require_containment", "note"],
+  catalogues: ["allow", "require_pinned"],
+  skills: ["allow", "block"],
+  scan: ["max"],
+  audit: ["log", "actor", "salt_env"],
+};
+
+function die(msg) { console.error(`error: ${msg}`); process.exit(1); }
+const sha256 = (s) => crypto.createHash("sha256").update(s).digest("hex");
+const tilde = (p) => (p.startsWith(os.homedir()) ? "~" + p.slice(os.homedir().length) : p);
+const untilde = (p) => (p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p);
+
+function policyPath(flags) {
+  if (flags.policy && flags.policy !== true) return { file: path.resolve(String(flags.policy)), named: true };
+  if (process.env.SKILLDROP_POLICY) return { file: path.resolve(untilde(process.env.SKILLDROP_POLICY)), named: true };
+  const dflt = path.join(os.homedir(), ".config", "skilldrop", "policy.json");
+  return { file: dflt, named: false };
+}
+
+/* The policy in force, or null when none is set. */
+function load(flags) {
+  const { file, named } = policyPath(flags || {});
+  if (!fs.existsSync(file)) {
+    if (named) die(`policy ${file} does not exist — nothing was changed`);
+    return null;
+  }
+  let raw, p;
+  try { raw = fs.readFileSync(file, "utf8"); p = JSON.parse(raw); }
+  catch (e) { die(`policy ${file} is not valid JSON (${e.message}) — nothing was changed`); }
+  const problems = [];
+  const closed = (obj, where) => {
+    if (obj === undefined) return;
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) return problems.push(`${where || "the policy"} must be an object`);
+    for (const k of Object.keys(obj)) if (!KEYS[where].includes(k)) problems.push(`unknown key '${where ? where + "." : ""}${k}'`);
+  };
+  closed(p, "");
+  for (const k of ["catalogues", "skills", "scan", "audit"]) closed(p[k], k);
+  if (p.version !== 1) problems.push("version must be 1");
+  const list = (v, where) => { if (v !== undefined && !(Array.isArray(v) && v.every((x) => typeof x === "string"))) problems.push(`${where} must be a list of strings`); };
+  list(p.catalogues && p.catalogues.allow, "catalogues.allow");
+  list(p.skills && p.skills.allow, "skills.allow");
+  list(p.skills && p.skills.block, "skills.block");
+  if (p.catalogues && p.catalogues.require_pinned !== undefined && typeof p.catalogues.require_pinned !== "boolean")
+    problems.push("catalogues.require_pinned must be true or false");
+  if (p.require_containment !== undefined && typeof p.require_containment !== "boolean")
+    problems.push("require_containment must be true or false");
+  if (p.scan && p.scan.max !== undefined && !(p.scan.max in MAX)) problems.push(`scan.max must be one of ${Object.keys(MAX).join(", ")}`);
+  if (p.audit) {
+    const a = p.audit.actor;
+    const ok = a === undefined || ["none", "pseudonym", "os-user"].includes(a) ||
+               (a && typeof a === "object" && Object.keys(a).length === 1 && typeof a.fixed === "string" && a.fixed.trim());
+    if (!ok) problems.push('audit.actor must be "none", "pseudonym", "os-user" or {"fixed": "<name>"}');
+    if (p.audit.log !== undefined && typeof p.audit.log !== "string") problems.push("audit.log must be a path");
+  }
+  if (problems.length) die(`policy ${file} is not usable — nothing was changed:\n  ${problems.join("\n  ")}`);
+  return Object.assign(p, { file, hash: sha256(raw).slice(0, 16) });
+}
+
+const glob = (pat) => new RegExp("^" + pat.split("*").map((s) => s.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join(".*") + "$", "i");
+const matches = (name, pats) => (pats || []).some((p) => glob(p).test(name));
+
+/* A catalogue source as the policy compares it: "bundled", an absolute path, or a git URL
+   without its #ref, trailing slash or .git. */
+function sourceKey(source) {
+  if (!source || source === "bundled") return "bundled";
+  const i = source.lastIndexOf("#");
+  const url = i > 0 ? source.slice(0, i) : source;
+  if (fs.existsSync(url)) return path.resolve(url);
+  return url.replace(/\/+$/, "").replace(/\.git$/i, "");
+}
+
+/* Why the policy refuses these units, as [{name, why}]; an empty list means allowed.
+   worst: {name: "🟥" | "🟧" | "🟨" | undefined}, the worst scan finding per unit. */
+function check(policy, { source, pinned, names, worst = {}, kind = "skill" }) {
+  if (!policy) return [];
+  const out = [];
+  const key = sourceKey(source);
+  const cats = policy.catalogues || {};
+  if (cats.allow && !cats.allow.some((a) => (a === "bundled" ? key === "bundled" : matches(key, [sourceKey(a)]))))
+    for (const n of names) out.push({ name: n, why: `catalogue '${key}' is not in the policy's allowed list` });
+  else if (cats.require_pinned && key !== "bundled" && !pinned)
+    for (const n of names) out.push({ name: n, why: `catalogue '${key}' must be pinned to a commit (--from <url>#<commit>)` });
+  const sk = policy.skills || {};
+  for (const n of names) {
+    if (matches(n, sk.block)) out.push({ name: n, why: `${kind} '${n}' is blocked by the policy` });
+    else if (sk.allow && !matches(n, sk.allow)) out.push({ name: n, why: `${kind} '${n}' is not in the policy's allowed list` });
+    const max = policy.scan && policy.scan.max;
+    if (max !== undefined && worst[n] && SEVERITY[worst[n]] > MAX[max])
+      out.push({ name: n, why: `the supply-chain scan found a ${worst[n]} pattern, above the policy's limit (${max})` });
+  }
+  return out;
+}
+
+/* ---------- audit log ----------
+   One JSON object per line. Each line carries the SHA-256 of the line before it, so a line
+   edited or removed afterwards breaks the chain, and `skilldrop audit verify` says where. */
+function auditFile(policy) {
+  const env = process.env.SKILLDROP_AUDIT_LOG;
+  if (!(policy && policy.audit) && !env) return null;
+  const f = path.resolve(untilde(env || (policy.audit.log || "~/.config/skilldrop/audit.jsonl")));
+  // Never inside a git working tree, where it could be committed.
+  try {
+    const dir = path.dirname(f);
+    fs.mkdirSync(dir, { recursive: true });
+    const top = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (top) die(`the audit log ${tilde(f)} is inside a git working tree (${tilde(top)}); keep it outside any repository`);
+  } catch (e) { /* not inside a repository (or no git): good */ }
+  return f;
+}
+
+function actor(policy) {
+  const mode = (policy && policy.audit && policy.audit.actor) || "pseudonym";
+  if (mode === "none") return null;
+  if (typeof mode === "object") return mode.fixed;
+  const user = (() => { try { return os.userInfo().username; } catch (e) { return "unknown"; } })();
+  if (mode === "os-user") return user;
+  const saltVar = (policy && policy.audit && policy.audit.salt_env) || "SKILLDROP_AUDIT_SALT";
+  const salt = process.env[saltVar];
+  if (!salt) die(`the audit log names people by pseudonym, which needs a secret salt: set ${saltVar} (the organisation keeps it), or set audit.actor to "none"`);
+  return "p:" + crypto.createHmac("sha256", salt).update(`${user}@${os.hostname()}`).digest("hex").slice(0, 16);
+}
+
+function lastLine(f) {
+  if (!fs.existsSync(f)) return null;
+  const lines = fs.readFileSync(f, "utf8").split("\n").filter(Boolean);
+  return lines.length ? lines[lines.length - 1] : null;
+}
+
+/* Everything the audit log needs (where it goes, who is acting), worked out before a command
+   changes anything: an install must not land and then fail to be recorded. */
+const ready = new Map();
+function prepare(policy) {
+  const key = policy || "env";
+  if (ready.has(key)) return ready.get(key);
+  const f = auditFile(policy);
+  const r = f ? { f, who: actor(policy) } : null;
+  ready.set(key, r);
+  return r;
+}
+
+/* Append one event per unit. Does nothing when no audit log is configured. */
+function audit(policy, action, units, extra) {
+  const r = prepare(policy);
+  if (!r || !units.length) return;
+  const { f, who } = r;
+  for (const u of units) {
+    const prev = lastLine(f);
+    const entry = Object.assign({ ts: new Date().toISOString(), action }, u, extra || {},
+      { actor: who, policy: policy ? policy.hash : null, prev: prev ? sha256(prev) : "0".repeat(64) });
+    if (entry.target) entry.target = tilde(entry.target);
+    if (entry.source) entry.source = tilde(entry.source);  // a catalogue on local disk names no home directory
+    fs.appendFileSync(f, JSON.stringify(entry) + "\n", { mode: 0o600 });
+  }
+}
+
+function verifyAudit(file) {
+  const f = path.resolve(untilde(file));
+  if (!fs.existsSync(f)) die(`no audit log at ${tilde(f)}`);
+  const lines = fs.readFileSync(f, "utf8").split("\n").filter(Boolean);
+  let prev = "0".repeat(64);
+  for (let i = 0; i < lines.length; i++) {
+    let e;
+    try { e = JSON.parse(lines[i]); } catch (err) { return { ok: false, line: i + 1, why: "not valid JSON", count: lines.length }; }
+    if (e.prev !== prev) return { ok: false, line: i + 1, why: "does not follow the line before it: a line was edited, removed or inserted", count: lines.length };
+    prev = sha256(lines[i]);
+  }
+  return { ok: true, count: lines.length };
+}
+
+/* ---------- mirrors ----------
+   MIRROR.json (skilldrop package) records a SHA-256 for every file it copied. */
+function verifyMirror(dir) {
+  const root = path.resolve(dir);
+  const mf = path.join(root, "MIRROR.json");
+  if (!fs.existsSync(mf)) die(`${root} has no MIRROR.json — it wasn't made by skilldrop package`);
+  let m;
+  try { m = JSON.parse(fs.readFileSync(mf, "utf8")); } catch (e) { die(`${mf} is not valid JSON`); }
+  const want = m.files || {};
+  const found = {};
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      if (e.name === ".git") continue;
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else found[path.relative(root, p).split(path.sep).join("/")] = p;
+    }
+  };
+  walk(root);
+  const own = new Set(["MIRROR.json", "catalogue.json"]);
+  const missing = Object.keys(want).filter((f) => !found[f]);
+  const changed = Object.keys(want).filter((f) => found[f] && sha256(fs.readFileSync(found[f])) !== want[f]);
+  const extra = Object.keys(found).filter((f) => !(f in want) && !own.has(f) && !/^packs\/[^/]+\/pack\.json$/.test(f));
+  return { source: m.source, created: m.created, files: Object.keys(want).length, missing, changed, extra };
+}
+
+/* ---------- containment (RFC-0051, OWASP AST06) ----------
+   Claude Code's sandbox confines the shell commands a session runs, and every process they
+   start: writes to the working directory and temp, network only to allowed hosts. It applies
+   to a whole project session, not to one skill, so containing a skill means turning the strict
+   sandbox on for the project it is installed into, sized to what its manifest declares
+   (permissions.network, permissions.files). It only ever adds restrictions: it never removes
+   a setting, never sets one to something looser, and never widens a sandbox that is already
+   on. Facts from code.claude.com/docs/en/sandboxing and /permissions, checked 2026-10-19. */
+function readSettings(f) {
+  if (!f || !fs.existsSync(f)) return {};
+  try { return JSON.parse(fs.readFileSync(f, "utf8")); }
+  catch (e) { die(`${tilde(f)} is not valid JSON — fix it before containment changes it; nothing was installed`); }
+}
+const strictIn = (d) => !!(d && d.sandbox && d.sandbox.enabled === true && d.sandbox.allowUnsandboxedCommands === false);
+
+/* units: [{name, perms}]; files: {local, project, user}; opts: {require}.
+   Returns what --contain would change, without writing anything. */
+function containmentPlan(units, files, opts = {}) {
+  const uncontainable = units.filter((u) => u.perms && u.perms.files === "anywhere").map((u) => u.name);
+  const hosts = [...new Set(units.flatMap((u) => (u.perms && u.perms.network) || []))].sort();
+  const local = readSettings(files.local);
+  const others = [files.project, files.user].filter((f) => f && f !== files.local).map(readSettings);
+  const before = JSON.stringify(local);
+  const next = JSON.parse(before);
+  const sb = (next.sandbox = next.sandbox && typeof next.sandbox === "object" ? next.sandbox : {});
+  const alreadyOn = sb.enabled === true || others.some((d) => d.sandbox && d.sandbox.enabled === true);
+  const changes = [], notes = [];
+  if (sb.enabled !== true) { sb.enabled = true; changes.push("sandbox.enabled: true — shell commands and what they start run in the OS sandbox"); }
+  if (sb.allowUnsandboxedCommands !== false) {
+    sb.allowUnsandboxedCommands = false;
+    changes.push("sandbox.allowUnsandboxedCommands: false — a command that fails in the sandbox can't retry outside it");
+  }
+  if (opts.require && sb.failIfUnavailable !== true) {
+    sb.failIfUnavailable = true;
+    changes.push("sandbox.failIfUnavailable: true — Claude Code won't start here if the sandbox can't (the policy requires containment)");
+  }
+  if (hosts.length && alreadyOn)
+    notes.push(`these skills declare network hosts (${hosts.join(", ")}). The sandbox was already on, so they were not added: ` +
+               "adding hosts would widen it. Add them to sandbox.network.allowedDomains yourself if the skills should reach them.");
+  else if (hosts.length) {
+    sb.network = sb.network && typeof sb.network === "object" ? sb.network : {};
+    const have = new Set(sb.network.allowedDomains || []);
+    const add = hosts.filter((h) => !have.has(h));
+    if (add.length) {
+      sb.network.allowedDomains = [...(sb.network.allowedDomains || []), ...add];
+      changes.push(`sandbox.network.allowedDomains: ${add.join(", ")} — the hosts these skills declare; shell commands reach no other host without asking`);
+    }
+  } else if (!alreadyOn) notes.push("these skills declare no network hosts, so shell commands reach none without asking");
+  if ((sb.excludedCommands || []).length)
+    notes.push(`this file's sandbox.excludedCommands (${sb.excludedCommands.join(", ")}) still run outside the sandbox`);
+  notes.push('the sandbox covers shell commands only: Claude Code\'s file tools, web tools, MCP servers and hooks follow permission rules instead. ' +
+             'To keep these skills off the web entirely, add "permissions": {"deny": ["WebFetch", "WebSearch"]} to this file.');
+  return { uncontainable, hosts, changes, notes, next, changed: JSON.stringify(next) !== before };
+}
+
+/* Is a project already contained (strict sandbox on in its own settings)? For inventory and
+   for a policy that requires containment. */
+function contained(files) { return strictIn(readSettings(files.local)) || strictIn(readSettings(files.project)); }
+
+module.exports = { containmentPlan, contained, load, check, prepare, audit, verifyAudit, verifyMirror, sourceKey, tilde, SEVERITY };

package/bin/skilldrop.js

@@ -15,6 +15,7 @@ const path = require("path");
 const os = require("os");
 const { execFileSync } = require("child_process");
 const crypto = require("crypto");
+const gov = require("./governance");  // org policy, audit log, mirror check (RFC-0050)
 
 const ROOT = path.resolve(__dirname, "..");
 const LEDGER = ".skilldrop.json";
@@ -75,6 +76,11 @@ Usage:
   skilldrop init-catalogue <dir> [--pack <name>]  start a private catalogue for your team's skills
   skilldrop package <dir> [--pack a,b] [--skills x,y] [--agents]  copy a vetted subset of a catalogue
                                           into a standalone one to host internally (writes MIRROR.json)
+  skilldrop inventory [--json] [--label <machine>]  every skilldrop install on this machine, with
+                                          what the policy thinks of each (RFC-0050)
+  skilldrop inventory --merge <files...>  combine inventory reports from many machines into one view
+  skilldrop audit verify|show [<file>]    check the audit log's chain, or show its last entries
+  skilldrop verify-mirror <dir>           check a mirror against the SHA-256s its MIRROR.json recorded
   skilldrop --version                     print the CLI version
   skilldrop bootstrap                     add the skilldrop marketplace to ~/.claude/settings.json
                                           (idempotent — safe to run in onboarding scripts)
@@ -98,6 +104,15 @@ Install/update/uninstall targets (pick one):
   --local            project scope, hidden from git via .git/info/exclude — try skills in a
                      repo you don't own without touching its tracked files or .gitignore
 
+Organisation policy (RFC-0050):
+  --contain          Claude Code project installs: turn on the strict sandbox for this project in
+                     .claude/settings.local.json, allowing only the network hosts the skills declare.
+                     Only adds restrictions; refuses a skill that declares writing anywhere (RFC-0051)
+  --policy <file>    the policy to enforce; also SKILLDROP_POLICY, else ~/.config/skilldrop/policy.json.
+                     It can allow only some catalogues (and require them pinned), allow or block skills,
+                     cap the supply-chain scan's findings, and turn on an audit log. A policy that is
+                     named but missing or unreadable stops the command.
+
 Options:
   --dry-run          install | update | uninstall | new-skill: print what would change, change nothing
   --yes              skip the confirmation uninstall and update --force ask for at a terminal
@@ -131,7 +146,8 @@ function parseArgs(argv) {
   const out = { _: [], flags: {} };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from" || a === "--panel" || a === "--profile" || a === "--tier" || a === "--skills" || a === "--days") out.flags[a.slice(2)] = argv[++i];
+    if (a === "--pack" || a === "--ide" || a === "--dest" || a === "--from" || a === "--panel" || a === "--profile" || a === "--tier" || a === "--skills" || a === "--days" ||
+        a === "--policy" || a === "--merge" || a === "--label" || a === "--last") out.flags[a.slice(2)] = argv[++i];
     else if (a.startsWith("--")) out.flags[a.slice(2)] = true;
     else out._.push(a);
   }
@@ -420,6 +436,91 @@ function gate(cat, names) {
   if (bad) die(`${bad} skill(s) failed the structural check — nothing was installed`);
 }
 
+/* RFC-0050: the worst scan finding per skill, for a policy's scan.max. Eval fixtures and
+   example inputs (⚪) never count. */
+function worstFindings(cat, names) {
+  const out = {};
+  for (const s of names) {
+    let w;
+    for (const f of scanSkill(cat, s)) if (!f.fixture && (!w || gov.SEVERITY[f.sev] > gov.SEVERITY[w])) w = f.sev;
+    if (w) out[s] = w;
+  }
+  return out;
+}
+
+/* Refuse the whole install when the policy in force forbids any part of it. */
+function enforcePolicy(flags, cat, names, kind) {
+  const policy = gov.load(flags);
+  gov.prepare(policy);  // an audit log that can't be written stops the install before it starts
+  if (!policy || !names.length) return policy;
+  const worst = kind === "skill" && policy.scan && policy.scan.max !== undefined ? worstFindings(cat, names) : {};
+  const problems = gov.check(policy, { source: cat.source, pinned: cat.pinned, names, worst, kind });
+  if (problems.length) {
+    for (const pr of problems) console.error(`refused ${pr.name}: ${pr.why}`);
+    die(`the policy in ${gov.tilde(policy.file)} refuses ${new Set(problems.map((x) => x.name)).size} ${kind}(s) — nothing was installed`);
+  }
+  return policy;
+}
+
+/* RFC-0051: --contain turns on Claude Code's strict sandbox for the project a skill is installed
+   into, sized to what the skills declare. Planned (and refused) before anything is copied;
+   applied after. Only ever adds restrictions; see gov.containmentPlan. */
+function containmentFor(flags, cat, names, dest, ide, policy) {
+  const require = !!(policy && policy.require_containment);
+  if (!flags.contain && !require) return null;
+  if (ide !== "claude") {
+    if (require) die(`the policy requires containment, which skilldrop sets up for Claude Code project installs; ` +
+                     `${ide === "generic" ? "--dest" : "--ide " + ide} has no sandbox it can configure — nothing was installed`);
+    const want = names.map((s) => { const pm = manifestOf(cat, s).permissions; return pm ? `${s}: network ${(pm.network || []).join(", ") || "none"}, writes ${pm.files}` : `${s}: no scripts`; });
+    console.log(`note: ${ide === "generic" ? "this target" : ide} has no sandbox skilldrop can configure. What the skills expect:\n  ${want.join("\n  ")}`);
+    return null;
+  }
+  const userDir = path.join(os.homedir(), ".claude", "skills");
+  if (path.resolve(dest) === userDir)
+    die("containment applies to one project: install with --project --contain (or --local --contain). A user-scope " +
+        "install reaches every project, and skilldrop won't change your user settings — nothing was installed");
+  const base = path.dirname(dest);
+  const files = { local: path.join(base, "settings.local.json"), project: path.join(base, "settings.json"),
+                  user: path.join(os.homedir(), ".claude", "settings.json") };
+  if (!flags.contain) {
+    if (gov.contained(files)) return null;
+    die("the policy requires containment: re-run with --contain, which turns on Claude Code's strict sandbox for this " +
+        "project — nothing was installed");
+  }
+  const plan = gov.containmentPlan(names.map((s) => ({ name: s, perms: manifestOf(cat, s).permissions })), files, { require });
+  if (plan.uncontainable.length)
+    die(`${plan.uncontainable.join(", ")} declare${plan.uncontainable.length === 1 ? "s" : ""} writing anywhere on disk ` +
+        "(permissions.files), so it can't run inside the sandbox. Install without --contain, or leave it out — nothing was installed");
+  return Object.assign(plan, { files });
+}
+
+function applyContainment(plan, dry) {
+  const f = plan.files.local;
+  const where = path.relative(process.cwd(), f) || f;
+  console.log(`\n${dry ? "would contain" : "Contained"} (RFC-0051): ${where}`);
+  if (!plan.changed) console.log("  already contained: nothing to change");
+  for (const c of plan.changes) console.log(`  ${dry ? "would set" : "set"} ${c}`);
+  for (const n of plan.notes) console.log(`  note: ${n}`);
+  if (dry) return;
+  if (plan.changed) {
+    fs.mkdirSync(path.dirname(f), { recursive: true });
+    fs.writeFileSync(f, JSON.stringify(plan.next, null, 2) + "\n");
+  }
+  // settings.local.json is personal: keep it out of git if nothing ignores it already
+  const root = gitRoot(process.cwd());
+  if (root && path.resolve(f).startsWith(path.resolve(root) + path.sep)) {
+    let ignored = false;
+    try { execFileSync("git", ["check-ignore", "-q", f], { cwd: root, stdio: "ignore" }); ignored = true; } catch (e) { /* not ignored */ }
+    if (!ignored) {
+      writeExclude(root, readExclude(root).entries.concat(excludeEntry(root, f, false)));
+      console.log(`  listed it in ${path.relative(process.cwd(), excludePath(root)) || excludePath(root)} so git won't see it`);
+    }
+  }
+}
+
+const auditUnit = (cat, name, kind, version, dest) =>
+  ({ kind, name, version: version || null, source: cat.source, commit: cat.commit || null, pinned: !!cat.pinned, target: dest });
+
 /* ---------- supply-chain scan (RFC-0022) ----------
    A skill is instruction prose an agent will obey, and its scripts are code that runs on the
    user's machine — so installing a third-party catalog is a supply-chain event. Anthropic's own
@@ -1221,8 +1322,10 @@ function install(args) {
     }
   }
   gate(cat, names);
+  const policy = enforcePolicy(args.flags, cat, names, "skill");
   const { dest, ide } = target(args.flags);
-  if (args.flags["dry-run"]) return planInstall(cat, names, dest, ide, args.flags);
+  const contain = containmentFor(args.flags, cat, names, dest, ide, policy);
+  if (args.flags["dry-run"]) { planInstall(cat, names, dest, ide, args.flags); if (contain) applyContainment(contain, true); return; }
   fs.mkdirSync(dest, { recursive: true });
   const l = ledger(dest);
   const pipDeps = [], suggestions = new Set(), notes = [];
@@ -1233,6 +1336,8 @@ function install(args) {
     console.log(`installed ${s}@${m.version} -> ${dest}`);
   }
   saveLedger(l);
+  if (contain) applyContainment(contain, false);
+  gov.audit(policy, "install", names.map((s) => Object.assign(auditUnit(cat, s, "skill", lver(l.data[s]), dest), contain ? { contained: true } : {})));
   console.log(`\n${names.length} skill(s) installed (${ide}).`);
   if (notes.length) console.log(`\nCleanup:\n${notes.join("\n")}`);
   const local = !!args.flags.local;
@@ -1354,7 +1459,10 @@ function update(args) {
     }
   }
   if (dry) return planUpdate(dest, ide, l, rows, args.flags);
-  let n = 0, conflicts = 0;
+  const policy = gov.load(args.flags);
+  gov.prepare(policy);
+  const done = [];
+  let n = 0, conflicts = 0, refusedByPolicy = 0;
   const silent = rows.filter((r) => r.current === r.installed && r.changed.length && !args.flags.changed);
   for (const r of rows) {
     if (r.retired) { console.log(`skip ${r.retired}\n  Remove it with: skilldrop uninstall ${r.s}${targetHint(args.flags)}`); continue; }
@@ -1362,6 +1470,9 @@ function update(args) {
     if (!isDue(r)) continue;
     const problems = unitCheck(r.cat, r.s, r.loop);
     if (problems.length) { console.log(`skip ${unitLabel(r)}: fails structural check in '${r.src}' (${problems[0]})`); continue; }
+    const refused = gov.check(policy, { source: r.src, pinned: r.pinned, names: [r.s], kind: r.loop ? "loop" : "skill",
+      worst: !r.loop && policy && policy.scan && policy.scan.max !== undefined ? worstFindings(r.cat, [r.s]) : {} });
+    if (refused.length) { console.log(`skip ${unitLabel(r)}: the policy refuses it (${refused[0].why})`); refusedByPolicy++; continue; }
     // No baseline (installed before RFC-0032, or a loop installed before 0.16.11) or --force:
     // overwrite as before, and record one.
     const entry = l.data[r.s];
@@ -1377,9 +1488,12 @@ function update(args) {
       conflicts += kept.length;
     }
     n++;
+    done.push(auditUnit(r.cat, r.s, r.loop ? "loop" : "skill", r.current, dest));
   }
   saveLedger(l);
-  console.log(n ? `\n${n} skill(s) or loop(s) updated.` : (silent.length ? "no version changes." : rows.some((r) => r.retired) ? "nothing else to update." : "everything up to date."));
+  gov.audit(policy, "update", done);
+  if (refusedByPolicy) console.log(`\n${refusedByPolicy} not updated because the policy refuses them; they stay as they are. Remove them with skilldrop uninstall, or change the policy.`);
+  else console.log(n ? `\n${n} skill(s) or loop(s) updated.` : (silent.length ? "no version changes." : rows.some((r) => r.retired) ? "nothing else to update." : "everything up to date."));
   if (silent.length)
     console.log(`\nNot taken: ${silent.map((r) => r.s).join(", ")} changed upstream without a version bump.` +
                 `\n  Read the change (skilldrop diff <skill>), then take it with: skilldrop update --changed`);
@@ -1484,11 +1598,14 @@ function uninstall(args) {
   const what = `Remove ${present.length} skill(s) from ${dest}: ${present.join(", ")}` +
                (edits.length ? `\n  (${edits.length} of the files have your edits: ${edits.join(", ")})` : "") + "?";
   if (!confirm(what, args.flags)) return console.log("cancelled — nothing removed.");
+  gov.prepare(gov.load(args.flags));
   for (const s of present) {
     fs.rmSync(path.join(dest, s), { recursive: true, force: true });
     const w = wiringPath(ide, dest, s);
     if (w) fs.rmSync(w, { force: true });
     removeHooksFor(s, dest, ide);
+    gov.audit(gov.load(args.flags), "uninstall", [{ kind: "skill", name: s, version: l.data[s] ? lver(l.data[s]) : null,
+      source: l.data[s] ? lsrc(l.data[s]) : null, target: dest }]);
     delete l.data[s];
     console.log(`removed ${s} from ${dest}`);
   }
@@ -1919,6 +2036,12 @@ function installLoops(args) {
     if (problems.length) bad++;
   }
   if (bad) die(`${bad} loop(s) failed the structural check — nothing was installed`);
+  const policy = enforcePolicy(args.flags, cat, names, "loop");
+  if (!args.flags["no-skills"]) {
+    const stage = [];
+    for (const n of names) for (const sk of loopSkills(cat, n)) if (!stage.includes(sk)) stage.push(sk);
+    enforcePolicy(args.flags, cat, stage, "skill");
+  }
 
   const { dest, ide } = target(args.flags);
   fs.mkdirSync(dest, { recursive: true });
@@ -1929,6 +2052,7 @@ function installLoops(args) {
     console.log(`installed loop ${n} -> ${path.join(dest, n)}`);
   }
   saveLedger(l);
+  gov.audit(policy, "install", names.map((n) => auditUnit(cat, n, "loop", lver(l.data[n]), dest)));
   if (args.flags.local) addLocal(dest, ide, names);
 
   const wanted = [];
@@ -1959,6 +2083,8 @@ function uninstallLoops(args) {
     fs.rmSync(path.join(dest, n), { recursive: true, force: true });
     const w = wiringPath(ide, dest, n);
     if (w) fs.rmSync(w, { force: true });
+    gov.audit(gov.load(args.flags), "uninstall", [{ kind: "loop", name: n, version: l.data[n] ? lver(l.data[n]) : null,
+      source: l.data[n] ? lsrc(l.data[n]) : null, target: dest }]);
     delete l.data[n];
     console.log(`removed loop ${n} from ${dest} (stage skills left in place)`);
   }
@@ -1981,6 +2107,7 @@ function installAgents(args) {
     if (problems.length) bad++;
   }
   if (bad) die(`${bad} agent(s) failed the structural check — nothing was installed`);
+  const policy = enforcePolicy(args.flags, cat, names, "agent");
 
   const { dest, ide } = agentTarget(args.flags);
   fs.mkdirSync(dest, { recursive: true });
@@ -1993,6 +2120,7 @@ function installAgents(args) {
     console.log(`installed ${a} -> ${path.join(dest, file)}`);
   }
   saveLedger(l);
+  gov.audit(policy, "install", names.map((a) => auditUnit(cat, a, "agent", null, dest)));
   console.log(`\n${names.length} agent(s) installed (${ide}).`);
   if (warns.length) console.log(`\nTool mapping:\n${warns.join("\n")}`);
   if (ide === "claude") console.log("Delegate by name, e.g. \"use the devils-advocate agent on this diff\".");
@@ -2125,6 +2253,10 @@ function validateCmd(args) {
   const cat = resolveCatalog(args.flags.from);
   const names = skillsIn(cat);
   let bad = 0;
+  // RFC-0050: this CLI accepts the policy example the contract describes (validate.py checks the
+  // other half), so the schema and the enforcement can't drift apart unnoticed.
+  const example = path.join(cat.dir || ROOT, "contracts", "policy.example.json");
+  if (!args.flags.from && fs.existsSync(example)) gov.load({ policy: example });
   for (const s of names) {
     const problems = checkSkill(cat, s);
     for (const f of scanSkill(cat, s).filter((x) => x.id.startsWith("undeclared-")))
@@ -2149,6 +2281,120 @@ const BOOTSTRAP_MARKETPLACE_KEY = "skilldrop";
 const BOOTSTRAP_GITHUB_OWNER = "sananthanarayan";
 const BOOTSTRAP_GITHUB_REPO = "skilldrop";
 
+/* ---------- inventory (RFC-0050) ----------
+   Every skilldrop install on this machine, from each target's ledger: one report an
+   organisation can collect, and --merge to combine many into one view. Paths under the home
+   directory are written as ~ so a report names no one. */
+function inventoryTargets(flags) {
+  if (flags.dest) return [{ dest: path.resolve(flags.dest), ide: "generic", scope: "dest" }];
+  const out = [];
+  for (const [ide, [proj, user]] of Object.entries(SKILL_DIRS)) {
+    out.push({ dest: path.resolve(...proj), ide, scope: "project" });
+    if (user) out.push({ dest: path.join(os.homedir(), ...user), ide, scope: "user" });
+  }
+  for (const ide of ["claude", "codex"]) for (const project of [true, false]) {
+    try { const t = agentTarget({ ide, project }); out.push({ dest: t.dest, ide, scope: project ? "project" : "user" }); } catch (e) { /* no target */ }
+  }
+  const seen = new Set();
+  return out.filter((t) => !seen.has(t.dest) && seen.add(t.dest));
+}
+
+function inventory(args) {
+  if (args.flags.merge) return mergeInventories([String(args.flags.merge), ...args._], args.flags);
+  const policy = gov.load(args.flags);
+  const installs = [];
+  for (const t of inventoryTargets(args.flags)) {
+    const l = ledger(t.dest);
+    for (const name of Object.keys(l.data).sort()) {
+      const e = l.data[name];
+      const kind = isLoopEntry(e) ? "loop" : e && e.file ? "agent" : "skill";
+      const src = lsrc(e);
+      const pinned = isPinned(src);
+      const refused = gov.check(policy, { source: src, pinned, names: [name], kind });
+      installs.push({ target: gov.tilde(t.dest), scope: t.scope, ide: t.ide, kind, name, version: lver(e) || null,
+                      source: gov.tilde(src), commit: (e && e.commit) || null, pinned,
+                      edited: kind === "agent" ? 0 : editedFiles(t.dest, name, e).length,
+                      contained: t.ide === "claude" && t.scope === "project" && kind !== "agent"
+                        ? gov.contained({ local: path.join(path.dirname(t.dest), "settings.local.json"), project: path.join(path.dirname(t.dest), "settings.json") }) : null,
+                      policy: policy ? (refused.length ? refused.map((x) => x.why) : "ok") : null });
+    }
+  }
+  const report = { inventory: 1, created: new Date().toISOString(), label: args.flags.label && args.flags.label !== true ? String(args.flags.label) : null,
+                   cli: readJSON(path.join(ROOT, "package.json")).version, policy: policy ? policy.hash : null, installs };
+  if (args.flags.json) return emitJSON(report);
+  if (!installs.length) return console.log("no skilldrop installs found on this machine (looked in every --ide target, user and project scope)");
+  for (const i of installs)
+    console.log(`${i.target}  ${i.kind} ${i.name}@${i.version || "-"}  ${i.source}${i.pinned ? " (pinned)" : ""}` +
+                (i.edited ? `  ${i.edited} edited file(s)` : "") + (Array.isArray(i.policy) ? `  REFUSED: ${i.policy[0]}` : ""));
+  const bad = installs.filter((i) => Array.isArray(i.policy));
+  console.log(`\n${installs.length} install(s)` + (policy ? `, ${bad.length} the policy refuses` : "") +
+              ". For an organisation-wide view: skilldrop inventory --json --label <machine> > <file>, then skilldrop inventory --merge <files...>");
+  if (bad.length) process.exitCode = 1;
+}
+
+function mergeInventories(files, flags) {
+  const by = {};
+  let reports = 0;
+  for (const f of files) {
+    let r;
+    try { r = readJSON(f); } catch (e) { die(`${f} is not an inventory report`); }
+    if (r.inventory !== 1 || !Array.isArray(r.installs)) die(`${f} is not an inventory report (skilldrop inventory --json)`);
+    reports++;
+    const who = r.label || path.basename(f);
+    for (const i of r.installs) {
+      const k = `${i.kind}\u0000${i.name}\u0000${i.source}`;
+      const a = (by[k] = by[k] || { kind: i.kind, name: i.name, source: i.source, machines: new Set(), versions: new Set(), unpinned: 0, edited: 0, refused: 0 });
+      a.machines.add(who);
+      a.versions.add(i.version || "-");
+      if (i.source !== "bundled" && !i.pinned) a.unpinned++;
+      if (i.edited) a.edited++;
+      if (Array.isArray(i.policy)) a.refused++;
+    }
+  }
+  const rows = Object.values(by).map((a) => Object.assign(a, { machines: [...a.machines].sort(), versions: [...a.versions].sort() }))
+    .sort((x, y) => x.name.localeCompare(y.name));
+  if (flags.json) return emitJSON({ reports, units: rows });
+  for (const a of rows)
+    console.log(`${a.kind} ${a.name}  ${a.source}  on ${a.machines.length} machine(s)  version(s) ${a.versions.join(", ")}` +
+                (a.unpinned ? `  ${a.unpinned} unpinned` : "") + (a.edited ? `  ${a.edited} edited` : "") + (a.refused ? `  ${a.refused} REFUSED by policy` : ""));
+  console.log(`\n${rows.length} distinct install(s) across ${reports} report(s).`);
+}
+
+/* skilldrop audit verify|show [<file>] — the append-only log install, update and uninstall
+   write when a policy turns it on (or SKILLDROP_AUDIT_LOG names a file). */
+function auditCmd(args) {
+  const sub = args._.shift();
+  const policy = gov.load(args.flags);
+  const file = args._[0] || process.env.SKILLDROP_AUDIT_LOG || (policy && policy.audit && (policy.audit.log || "~/.config/skilldrop/audit.jsonl"));
+  if (!file) die("no audit log: pass a file, set SKILLDROP_AUDIT_LOG, or turn it on in the policy (audit.log)");
+  if (sub === "verify") {
+    const r = gov.verifyAudit(file);
+    if (r.ok) return console.log(`ok: ${r.count} entr${r.count === 1 ? "y" : "ies"}, each following the one before it`);
+    console.log(`BROKEN at line ${r.line} of ${r.count}: ${r.why}`);
+    process.exitCode = 1;
+  } else if (sub === "show") {
+    const lines = fs.readFileSync(path.resolve(file.replace(/^~(?=\/)/, os.homedir())), "utf8").split("\n").filter(Boolean);
+    const n = args.flags.last && args.flags.last !== true ? Math.max(1, parseInt(args.flags.last, 10) || 20) : 20;
+    for (const line of lines.slice(-n)) {
+      const e = JSON.parse(line);
+      console.log(`${e.ts}  ${e.action} ${e.kind} ${e.name}${e.version ? "@" + e.version : ""}  ${e.source || ""}${e.pinned ? " (pinned)" : ""}  ${e.target || ""}${e.actor ? "  by " + e.actor : ""}`);
+    }
+  } else die("usage: skilldrop audit verify|show [<file>] [--last N]");
+}
+
+/* skilldrop verify-mirror <dir> — is an internal mirror still what skilldrop package made? */
+function verifyMirrorCmd(args) {
+  const r = gov.verifyMirror(args._[0] || die("usage: skilldrop verify-mirror <dir>"));
+  if (args.flags.json) { emitJSON(r); if (r.missing.length || r.changed.length || r.extra.length) process.exitCode = 1; return; }
+  for (const f of r.changed) console.log(`changed  ${f}`);
+  for (const f of r.missing) console.log(`missing  ${f}`);
+  for (const f of r.extra) console.log(`added    ${f}  (not in MIRROR.json)`);
+  const bad = r.changed.length + r.missing.length + r.extra.length;
+  console.log(bad ? `\n${bad} file(s) differ from what was packaged from '${r.source}' on ${r.created}.`
+                  : `ok: all ${r.files} file(s) match what was packaged from '${r.source}' on ${r.created}.`);
+  if (bad) process.exitCode = 1;
+}
+
 function bootstrap() {
   const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
   let data = {};
@@ -2178,7 +2424,8 @@ function bootstrap() {
 
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, profiles: listProfiles, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, diff, doctor, "new-skill": newSkill, "loop-stats": loopStats, "init-catalogue": initCatalogue, package: packageCatalogue, validate: validateCmd, scan, bootstrap };
+const commands = { list, info, packs: listPacks, profiles: listProfiles, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, diff, doctor, "new-skill": newSkill, "loop-stats": loopStats, "init-catalogue": initCatalogue, package: packageCatalogue, validate: validateCmd, scan, bootstrap,
+                   inventory, audit: auditCmd, "verify-mirror": verifyMirrorCmd };
 if (args.flags.version || cmd === "version") console.log(readJSON(path.join(ROOT, "package.json")).version);
 else if (!cmd || cmd === "help" || args.flags.help) console.log(HELP);
 else if (commands[cmd]) commands[cmd](args);

package/contracts/policy.example.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "note": "Example: Platform Security owns this policy. Ask in #ai-tools before adding a catalogue.",
+  "catalogues": {
+    "allow": ["bundled", "https://git.example.org/ai/skills"],
+    "require_pinned": true
+  },
+  "skills": {
+    "allow": ["*"],
+    "block": ["figma-diagrams"]
+  },
+  "scan": { "max": "medium" },
+  "audit": { "actor": "pseudonym", "salt_env": "SKILLDROP_AUDIT_SALT" }
+}

package/contracts/policy.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sananthanarayan/skilldrop/contracts/policy.schema.json",
+  "title": "skilldrop organisation policy",
+  "$comment": "RFC-0050. The file an organisation hands out (--policy, SKILLDROP_POLICY, or ~/.config/skilldrop/policy.json). Closed at every level: an unknown key stops the command, because a misspelt rule that is silently ignored is a rule that isn't there. bin/governance.js enforces the same shape; contracts/policy.example.json must satisfy both.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "note": {
+      "type": "string",
+      "description": "Free text: who owns this policy and where to ask about it."
+    },
+    "catalogues": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Catalogue sources allowed: \"bundled\", a git URL (a trailing * matches a prefix, e.g. https://git.example.org/skills/*), or a path. Absent: any."
+        },
+        "require_pinned": {
+          "type": "boolean",
+          "description": "Every catalogue other than the bundled one must be pinned to a commit (--from <url>#<commit>)."
+        }
+      }
+    },
+    "skills": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Skill, loop and agent names allowed; * matches anything. Absent: any."
+        },
+        "block": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Names refused even when allowed."
+        }
+      }
+    },
+    "scan": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "max": {
+          "enum": [
+            "none",
+            "low",
+            "medium",
+            "high"
+          ],
+          "description": "The worst supply-chain scan finding a skill may carry: none, low (🟨), medium (🟧), high (🟥). Findings in eval fixtures and example inputs never count."
+        }
+      }
+    },
+    "audit": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Present: install, update and uninstall append to a tamper-evident log.",
+      "properties": {
+        "log": {
+          "type": "string",
+          "description": "Where the log goes. Default ~/.config/skilldrop/audit.jsonl. Refused inside a git working tree."
+        },
+        "actor": {
+          "description": "Who each entry names: \"pseudonym\" (default; a keyed hash of user and machine, needs the salt), \"none\", \"os-user\", or {\"fixed\": \"<name>\"} such as a team or machine id."
+        },
+        "salt_env": {
+          "type": "string",
+          "description": "The environment variable holding the organisation's secret salt for pseudonyms. Default SKILLDROP_AUDIT_SALT."
+        }
+      }
+    },
+    "require_containment": {
+      "type": "boolean",
+      "description": "RFC-0051. true: an install must be contained (--contain, or a Claude Code project whose own settings already run the strict sandbox); targets that can't be are refused, and --contain also sets sandbox.failIfUnavailable."
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.26",
+  "version": "0.16.28",
   "description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",