skillrepo 4.12.0 → 4.13.0

package/README.md

@@ -119,11 +119,23 @@ and just write the config + gitignore.
     "removed": 0,
     "notModified": false,
     "fullSync": true,
-    "syncedAt": "2026-05-01T00:00:00.000Z"
+    "syncedAt": "2026-05-01T00:00:00.000Z",
+    "globalBoundary": {
+      "total": 0,
+      "counts": { "global_library": 0, "global_foreign": 0, "global_shadowed": 0 },
+      "names": [],
+      "skillsetDeclared": false
+    }
   }
 }
 ```
 
+`sync.globalBoundary` (4.13.0) appears on every successful
+project-scope sync and describes the personal-scope skills that also
+load in sessions here; it is absent when the scan did not run
+(`--global`, or a scan failure). `names` stays local to your machine —
+sync reporting to your organization carries counts only.
+
 Field notes:
 - `vendors` is the resolved canonical-key list, NOT the raw `--agent` input. `--agent agents` produces every cohort vendor (cursor, windsurf, gemini, codex, cline, copilot); `--agent none` produces an empty array.
 - `sessionSync.cohortHooks[]` reports per-vendor outcomes for the auto-refresh hooks installed alongside the Claude Code SessionStart hook (one entry per cohort vendor with a non-null `agentHook` registry spec — Cursor, Gemini CLI, Codex CLI, VS Code + Copilot). `reason` is present only when `action: "failed"`. Empty array when `--no-session-sync` was passed or no cohort vendor was selected.
@@ -183,6 +195,21 @@ Sync also warns — once per repo, same rules — when a `skillrepo.json`
 at the repo root is gitignored: the skillset declaration only works as
 a committed file, so remove it from `.gitignore` and commit it.
 
+Project syncs also disclose the personal scope (the global boundary):
+skills under the global folders (`~/.claude/skills/`,
+`~/.agents/skills/`, `~/.codeium/windsurf/skills/`) load in every
+session run inside a project, whether or not they came through a
+skillset. When any exist, a one-line disclosure says how many global
+skills will also load — in a declared repo it also counts how many sit
+outside the repo's skillset and how many collide with a skillset
+member's name. Today the session auto-sync prints that line in Claude
+Code only (the other agents' background sync hooks run silently by
+their hook contracts — see `docs/vendor-paths.md` for each vendor's
+channel); `skillrepo list` shows the same line everywhere. Interactive
+syncs add a one-time warning per finding with the remediation, and
+your organization's sync reporting carries counts only
+(`global_library`, `global_foreign`, `global_shadowed`), never names.
+
 A repository can declare a skillset in a root `skillrepo.json`:
 `{"skillset": {"version": 1, "name": "<repo-identity>", "use":
 "owner/skillset-name"}}` (optional `extra: ["owner/skill"]`). The CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.12.0",
+  "version": "4.13.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/list.mjs

@@ -43,6 +43,12 @@ import { detectAgents } from "../lib/detect-agents.mjs";
 import { walkDetectedPlacements } from "../lib/placement-walk.mjs";
 import { getAgentByKey } from "../lib/agent-registry.mjs";
 import { computeSkillState, rollupState, SKILL_STATE } from "../lib/drift.mjs";
+import {
+  scanGlobalBoundary,
+  formatGlobalBoundaryDisclosure,
+  managedGlobalNamesFrom,
+  resolveBoundaryMemberContext,
+} from "../lib/global-boundary.mjs";
 
 /**
  * Run `list`. Throws CliError on any failure.
@@ -56,7 +62,10 @@ export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
   const flags = resolveFlags(argv);
 
-  // `list` is a read-only drift check — it must NEVER set sync state.
+  // `list` is a read-only drift check — it must NEVER set sync state,
+  // and (#2495) it never writes the governance-seen file either: the
+  // boundary disclosure below scans without committing warn-state, so
+  // running `list` can't consume a warning `update` owes the user.
   // Use the manifest read (#1832): metadata only, no file bodies, and the
   // server records no delivery for it. Per-skill drift is computed from
   // on-disk SHAs + `.last-sync` below, never from the response body, so
@@ -122,6 +131,42 @@ export async function runList(argv, io = {}) {
 
   printTable(augmented, detected, stdout);
   printFooter(augmented, libraryResponse.etag, lastSync, stdout, canUseGlyphs(stdout));
+  printGlobalBoundaryDisclosure(detectedKeys, lastSync, stdout);
+}
+
+/**
+ * Global-boundary disclosure for the table surface (#2495): one line,
+ * same format as the session-hook disclosure, printed only when the
+ * detected vendors' GLOBAL roots hold skill dirs. Read-only to the
+ * letter of list's contract above — no seen-state commit, no per-dir
+ * warning lines (those are `update`'s interactive job). Best-effort:
+ * the drift table must never fail because a disclosure probe did.
+ *
+ * The declaration is resolved TOLERANTLY, like the throttled sync
+ * exit: `list` is a reporting surface, so an invalid `skillrepo.json`
+ * stays `update`'s error to raise — here it just means the scan runs
+ * without a member set.
+ *
+ * @param {string[]} vendors - Detected vendor keys.
+ * @param {import("../lib/sync.mjs").SyncStateFile | null} lastSync
+ * @param {NodeJS.WritableStream} stdout
+ */
+function printGlobalBoundaryDisclosure(vendors, lastSync, stdout) {
+  try {
+    const { memberNames, baseDir } = resolveBoundaryMemberContext();
+    const scan = scanGlobalBoundary({
+      vendors,
+      memberNames,
+      managedGlobalNames: managedGlobalNamesFrom(lastSync?.skills),
+      baseDir,
+    });
+    const disclosure = formatGlobalBoundaryDisclosure(scan);
+    // Two-space indent matches every other list line; the line itself
+    // is byte-identical to the session-hook disclosure.
+    if (disclosure) stdout.write(`  ${disclosure}\n`);
+  } catch {
+    // Disclosure is best-effort on every surface.
+  }
 }
 
 // ── Per-skill augmentation ─────────────────────────────────────────────

package/src/commands/update.mjs

@@ -46,6 +46,7 @@
  */
 
 import { runSync } from "../lib/sync.mjs";
+import { formatGlobalBoundaryDisclosure } from "../lib/global-boundary.mjs";
 import {
   resolveFlags,
   effectiveVendors,
@@ -64,6 +65,14 @@ import {
  *   - 304 Not Modified → exit 0, NO output.
  *   - 200 with changes → exit 0, ONE line: `[SkillRepo] Library synced: N added, N updated, N removed.`
  *   - Any failure → exit 0, ONE line: `[SkillRepo] Sync failed: <reason>.`
+ *   - Global-boundary disclosure (#2495): when the sync's summary
+ *     reports global skills that will also load in this session
+ *     (`globalBoundary.total > 0`), ONE additional line prints on
+ *     EVERY success path — after the sync line, or alone on the
+ *     otherwise-silent 304/zero-delta/throttled paths. Plain stdout
+ *     enters the session's model context, which is the point: the
+ *     agent itself learns what extra skills are in play. Failure
+ *     paths never disclose (the failure line stays the single line).
  *
  * The "exit 0 on all errors" contract is non-negotiable: a sync
  * failure must NEVER block a Claude Code session start. Users on a
@@ -162,10 +171,41 @@ export async function runUpdate(argv, io = {}) {
       const skipped = summary.skipped ?? 0;
       const total =
         summary.added + summary.updated + summary.removed + skipped;
+      // Global-boundary disclosure (#2495), computed BEFORE the silent
+      // branch below: the quiet 304/zero-delta/throttled session is
+      // the COMMON session, and it must still disclose — the line
+      // exists so the session's model context knows about the global
+      // skills loading alongside the synced set, not to report sync
+      // work. Success paths only; the catch below never reaches here.
+      // Formatting is its OWN failure domain (architect review r1): a
+      // formatter defect must degrade to "no line", never fall into
+      // the outer catch and report a successful sync as failed —
+      // "disclosure must never break a sync" applies to the printer
+      // exactly as it does to the scanner.
+      let disclosure = null;
+      try {
+        disclosure =
+          summary.globalBoundary && summary.globalBoundary.total > 0
+            ? formatGlobalBoundaryDisclosure(summary.globalBoundary)
+            : null;
+      } catch {
+        // Degrade to no disclosure line.
+      }
+      const writeDisclosureLine = () => {
+        if (!disclosure) return;
+        try {
+          stdout.write(`${disclosure}\n`);
+        } catch {
+          // Same failure domain as the formatter: a write failure on
+          // the cosmetic line must not become a "Sync failed" report.
+        }
+      };
       if (summary.notModified || total === 0) {
         // 304 Not Modified OR 200 with zero deltas — silent by
-        // contract. Users should not see "Syncing..." on every
+        // contract (the boundary disclosure is the one sanctioned
+        // exception). Users should not see "Syncing..." on every
         // session for no visible value.
+        writeDisclosureLine();
         return;
       }
       stdout.write(
@@ -173,6 +213,7 @@ export async function runUpdate(argv, io = {}) {
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
+      writeDisclosureLine();
     } catch (err) {
       // The one-line failure message is the user's primary signal
       // that something's wrong. Do not surface a stack trace — the

package/src/lib/foreign-content.mjs

@@ -245,11 +245,41 @@ export function formatForeignWarnings(scan) {
  * @property {Record<string, boolean>} declarations - abs repo path →
  *           true when the gitignored-declaration warning was already
  *           shown and the declaration is still gitignored.
+ * @property {Record<string, Record<string, string[]>>} globalBoundary -
+ *           abs repo path → (abs global root → dir names already warned
+ *           about, sorted). The #2495 global-boundary counterpart to
+ *           `roots`, keyed per REPO because the same global dir means
+ *           different things in different repos (shadowing one repo's
+ *           skillset member, plain foreign content elsewhere) — one
+ *           repo consuming the warning must not silence it for another.
  */
 
 /** @returns {GovernanceSeenState} */
 function emptySeenState() {
-  return { schemaVersion: 1, roots: {}, declarations: {} };
+  return { schemaVersion: 1, roots: {}, declarations: {}, globalBoundary: {} };
+}
+
+/**
+ * Shape-check the `globalBoundary` field on read: an object of objects
+ * of arrays, or `{}` when anything about it is malformed — the same
+ * warn-everything degradation the other fields use, applied to the
+ * whole field (a partially-trusted structure isn't worth salvaging
+ * when the cost of a reset is one repeated warning).
+ *
+ * @param {unknown} value
+ * @returns {Record<string, Record<string, string[]>>}
+ */
+function coerceGlobalBoundary(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  for (const repoMap of Object.values(value)) {
+    if (!repoMap || typeof repoMap !== "object" || Array.isArray(repoMap)) {
+      return {};
+    }
+    for (const names of Object.values(repoMap)) {
+      if (!Array.isArray(names)) return {};
+    }
+  }
+  return /** @type {Record<string, Record<string, string[]>>} */ (value);
 }
 
 /** @returns {GovernanceSeenState} */
@@ -262,6 +292,11 @@ export function readGovernanceSeen() {
     // at the current schema. A future v2 that must PRESERVE v1 data
     // needs an explicit accept-in-place branch here, the way
     // sync.mjs's readLastSync accepts its immediately-prior schema.
+    // `globalBoundary` (#2495) is an ADDITIVE key at schemaVersion 1,
+    // not a bump: a pre-#2495 CLI sharing this file simply drops the
+    // key on its next write, and the cost is one repeated boundary
+    // warning on the next post-#2495 interactive sync — documented,
+    // acceptable, and self-healing.
     if (!parsed || typeof parsed !== "object" || parsed.schemaVersion !== 1) {
       return emptySeenState();
     }
@@ -277,6 +312,7 @@ export function readGovernanceSeen() {
         !Array.isArray(parsed.declarations)
           ? parsed.declarations
           : {},
+      globalBoundary: coerceGlobalBoundary(parsed.globalBoundary),
     };
   } catch {
     return emptySeenState();
@@ -396,7 +432,110 @@ export function commitGovernanceSeen({ scan, repoKey, declarationIgnored }) {
   } else {
     delete declarations[repoKey];
   }
-  writeGovernanceSeen({ schemaVersion: 1, roots, declarations });
+  writeGovernanceSeen({
+    schemaVersion: 1,
+    roots,
+    declarations,
+    // Pass-through from the FRESH read (#2495): this commit owns only
+    // `roots` + this repo's declaration flag; the boundary scan's keys
+    // belong to `commitGlobalBoundarySeen`, and dropping them here
+    // would re-warn every boundary finding after every project sync.
+    globalBoundary: fresh.globalBoundary,
+  });
+}
+
+/**
+ * Commit a global-boundary scan (#2495) into the seen-state file with
+ * the same NARROW merge discipline as `commitGovernanceSeen`: fresh
+ * read, rewrite ONLY `globalBoundary[repoKey]` (this repo's view), and
+ * pass `roots`/`declarations` — plus every OTHER repo's boundary key —
+ * through from the fresh read, so a concurrent sync elsewhere keeps
+ * its update even if this process writes last.
+ *
+ * Replace-not-merge per scanned root within the repo key: dirs that
+ * disappeared are pruned so a removed-then-reappearing dir warns
+ * again; a clean root deletes its key, and a repo whose every scanned
+ * root ended clean deletes its whole entry (state files should not
+ * accumulate empty husks).
+ *
+ * The RESIDUAL same-key race documented on `writeGovernanceSeen`
+ * applies here identically: two concurrent interactive syncs of ONE
+ * repo last-write-win on that repoKey, which can revive a pruned
+ * entry and suppress a re-warn — a repeated-or-suppressed warning,
+ * never a wrong receipt count (counts come from the live scan).
+ *
+ * @param {object} options
+ * @param {{ roots: { root: string, entries: { name: string }[] }[] }} options.scan
+ *        The FULL boundary scan (everything currently on disk, not
+ *        just the newly-warned entries).
+ * @param {string} options.repoKey - Normalized repo path.
+ */
+export function commitGlobalBoundarySeen({ scan, repoKey }) {
+  const fresh = readGovernanceSeen();
+  const globalBoundary = { ...fresh.globalBoundary };
+  const repoMap = { ...(globalBoundary[repoKey] ?? {}) };
+  for (const rootResult of scan?.roots ?? []) {
+    const names = (rootResult.entries ?? []).map((entry) => entry.name).sort();
+    if (names.length > 0) {
+      repoMap[rootResult.root] = names;
+    } else {
+      delete repoMap[rootResult.root];
+    }
+  }
+  if (Object.keys(repoMap).length === 0) {
+    delete globalBoundary[repoKey];
+  } else {
+    globalBoundary[repoKey] = repoMap;
+  }
+  writeGovernanceSeen({
+    schemaVersion: 1,
+    roots: fresh.roots,
+    declarations: fresh.declarations,
+    globalBoundary,
+  });
+}
+
+/**
+ * Select the boundary findings this repo has NOT been warned about
+ * yet. Pure — no IO; the `commitGlobalBoundarySeen` above does the
+ * bookkeeping. Mirrors `selectNewFindings`, keyed one level deeper
+ * (per repo, then per root).
+ *
+ * Gates ONLY the interactive warning lines: the disclosure line and
+ * the receipt categories always use the FULL scan — seen-state
+ * suppresses repetition for a human, never facts for the record.
+ *
+ * @param {import("./global-boundary.mjs").GlobalBoundaryScan} scan
+ * @param {GovernanceSeenState} seen
+ * @param {string} repoKey - Normalized repo path.
+ * @returns {{ roots: object[], counts: Record<string, number>, total: number }}
+ *          Scan-shaped (roots/counts/total recomputed over the unseen
+ *          entries). No `summary` — the disclosure surfaces never
+ *          consume a filtered scan, so embedding one here would invite
+ *          exactly the partial-disclosure bug the gating rule forbids.
+ */
+export function selectNewGlobalBoundaryFindings(scan, seen, repoKey) {
+  const repoMap =
+    seen?.globalBoundary && typeof seen.globalBoundary === "object"
+      ? seen.globalBoundary[repoKey] ?? {}
+      : {};
+  const counts = {};
+  for (const key of Object.keys(scan?.counts ?? {})) counts[key] = 0;
+  const result = { roots: [], counts, total: 0 };
+  for (const rootResult of scan?.roots ?? []) {
+    const prior = new Set(
+      Array.isArray(repoMap[rootResult.root]) ? repoMap[rootResult.root] : [],
+    );
+    const freshEntries = (rootResult.entries ?? []).filter(
+      (entry) => !prior.has(entry.name),
+    );
+    result.roots.push({ ...rootResult, entries: freshEntries });
+    for (const entry of freshEntries) {
+      counts[entry.bucket] = (counts[entry.bucket] ?? 0) + 1;
+      result.total += 1;
+    }
+  }
+  return result;
 }
 
 /**