skilldrop-cli 0.16.25 → 0.16.27

package/bin/governance.js

@@ -0,0 +1,212 @@
+/* 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", "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.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 };
+}
+
+module.exports = { 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,12 @@ 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):
+  --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 +143,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 +433,35 @@ 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;
+}
+
+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,6 +1263,7 @@ 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);
   fs.mkdirSync(dest, { recursive: true });
@@ -1233,6 +1276,7 @@ function install(args) {
     console.log(`installed ${s}@${m.version} -> ${dest}`);
   }
   saveLedger(l);
+  gov.audit(policy, "install", names.map((s) => auditUnit(cat, s, "skill", lver(l.data[s]), dest)));
   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 +1398,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 +1409,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 +1427,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 +1537,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 +1975,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 +1991,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 +2022,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 +2046,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 +2059,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 +2192,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 +2220,118 @@ 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,
+                      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 +2361,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,46 @@
+{
+  "$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." }
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.16.25",
+  "version": "0.16.27",
   "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",

package/packs/solution-architect/skills/interactive-diagram/SKILL.md

@@ -99,10 +99,9 @@ Two things follow:
    right lines or mark the item assumed. Add `--mermaid diagram.mmd` for a version to paste
    into a README, and `--compare old.json` to show what a change adds, removes and alters.
 
-5. **Reply with the map first.** The script prints the line to open with: a link to the page,
-   titled. Use it as the first line, then the takeaway in one or two sentences, then one line
-   each for what is drawn as an assumption and what was left out, and last how many citations
-   were checked:
+5. **Lead the reply with the map.** The script prints a titled link to the page. Put it at the
+   top, then the takeaway in one or two sentences, then one line each for what is drawn as an
+   assumption and what was left out, and last how many citations were checked:
 
    > **What a checkout request touches** (the script's link line: the title, linked to the page)
    >
@@ -110,8 +109,8 @@ Two things follow:
    > Assumed: the shopper's browser (no client in this repo). Left out: the products table's
    > other readers. 22 of 22 citations checked.
 
-   Keep the spec beside the page so the map can be rebuilt after the code changes. No recap of
-   commands or layout, and nothing before the link.
+   Keep the spec beside the page so the map can be rebuilt after the code changes. At most one
+   short line about the build may come before the link; no recap of commands or layout.
 
 6. **When the script can't run** (no `python3`), give the Mermaid version in the reply, with
    assumptions marked, and say that the interactive page needs Python 3.
@@ -131,7 +130,8 @@ don't cite them in the first place, and read the page before it leaves the team.
 - **Nothing on the map comes only from a README, a plan or what such systems usually have.**
 - **The map answers one stated question,** and what was left out is said.
 - **One HTML file that works offline:** no CDN, no external fonts, no network requests.
-- **The reply opens with the link and the takeaway,** not with how it was made.
+- **The link and the takeaway lead the reply,** with at most one short line about the build
+  before them and no account of how it was made.
 
 ## When to use this skill
 

package/packs/solution-architect/skills/interactive-diagram/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "interactive-diagram",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Turn a codebase, a system description, a process or a database schema into one self-contained interactive HTML diagram (architecture, workflow, data flow, lifecycle, ERD, sequence, class, tree, timeline or waterfall) where every box and arrow cites the file and line or the words it came from, anything inferred is drawn dashed as an assumption, and each cited line is checked against the repository before the page is written. Laid out automatically, opens offline with no CDN, and exports SVG, PNG and Mermaid. Use when the user asks to \"visualize\", \"map\" or \"make an interactive diagram of\" a repo, a request path, a pipeline, an approval process, a set of tables, an incident's events or a slow trace, or wants a diagram they can click through and share as one file.",
   "entrypoint": "SKILL.md",
   "deps": {

package/packs/solution-architect/skills/interactive-diagram/scripts/build_diagram.py

@@ -2591,7 +2591,7 @@ def main(argv=None):
         else:
             item, link = {"sequence": ("participants", "messages"), "tree": ("items", "links"), "timeline": ("events", "links"),
                           "waterfall": ("spans", "parent links"), "class": ("types", "relations")}.get(spec["type"], ("nodes", "edges"))
-            print("Your reply starts with this line, before anything else:\n" + receipt["reply_first_line"] + "\n")
+            print("Lead the reply with this line, then the takeaway:\n" + receipt["reply_first_line"] + "\n")
             print("For the end of the reply: %d of %d file citations checked; %d drawn as assumptions. (%s, %d KB: %d %s, %d %s.)" % (
                 receipt["verified"], receipt["file_citations"], receipt["assumed"], a.out, receipt["bytes"] // 1024,
                 receipt["nodes"], item, receipt["edges"], link))