skillrepo 4.12.0 → 4.14.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.14.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,8 @@
  */
 
 import { runSync } from "../lib/sync.mjs";
+import { formatGlobalBoundaryDisclosure } from "../lib/global-boundary.mjs";
+import { formatRepoComplianceSummary } from "../lib/foreign-content.mjs";
 import {
   resolveFlags,
   effectiveVendors,
@@ -64,6 +66,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 +172,63 @@ 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.
+      }
+      // Repo compliance state (#2665, owner decision 2026-08-20): a
+      // skillset-declared repo that does not match its set says so in
+      // EVERY session, hook mode included — a state, never a
+      // warn-on-new event. Same failure domain as the disclosure: a
+      // formatter defect degrades to no line, never a failed sync.
+      let compliance = null;
+      try {
+        compliance = summary.compliance
+          ? formatRepoComplianceSummary({ ...summary.compliance, hookMode: true })
+          : null;
+      } catch {
+        // Degrade to no compliance 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.
+        }
+      };
+      const writeComplianceLine = () => {
+        if (!compliance) return;
+        try {
+          stdout.write(`${compliance}\n`);
+        } catch {
+          // Same failure domain as the disclosure write above.
+        }
+      };
       if (summary.notModified || total === 0) {
         // 304 Not Modified OR 200 with zero deltas — silent by
-        // contract. Users should not see "Syncing..." on every
-        // session for no visible value.
+        // contract (the boundary disclosure and the compliance state
+        // are the sanctioned exceptions). Users should not see
+        // "Syncing..." on every session for no visible value.
+        writeDisclosureLine();
+        writeComplianceLine();
         return;
       }
       stdout.write(
@@ -173,6 +236,8 @@ export async function runUpdate(argv, io = {}) {
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
+      writeDisclosureLine();
+      writeComplianceLine();
     } 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

@@ -186,11 +186,25 @@ export function scanForeignContent({ vendors, global, managedSkills, baseDir })
  * rules. The names stay on this machine — see the module docstring's
  * privacy contract.
  *
+ * Two copy branches (#2665): in a skillset-declared repo the finding is
+ * a COMPLIANCE statement — the consequence is named ("reported as not
+ * compliant") and the remediation is the governed path (remove, or have
+ * a skillset manager add the skill). `skillrepo push` is deliberately
+ * NOT offered there: pushing publishes the dir to the library but does
+ * not put it in the skillset, so it cannot restore compliance — and the
+ * developer may not hold publish rights at all. Undeclared repos keep
+ * the original library-framed push-or-remove copy.
+ *
  * @param {ForeignScanResult} scan
+ * @param {object} [options]
+ * @param {string | null} [options.skillsetRef] - The declared skillset
+ *        (`owner/name`, schema-validated upstream) when the repo is
+ *        skillset-scoped; absent/null → library-framed copy.
  * @returns {string[]}
  */
-export function formatForeignWarnings(scan) {
+export function formatForeignWarnings(scan, { skillsetRef } = {}) {
   const lines = [];
+  const declared = typeof skillsetRef === "string" && skillsetRef.length > 0;
   for (const rootResult of scan.roots) {
     for (const dir of rootResult.foreignDirs) {
       // Directory names come from readdirSync — filesystem-sourced and
@@ -200,6 +214,15 @@ export function formatForeignWarnings(scan) {
       // server-path treatment in file-write.mjs (#2402 class).
       const safeDir = escapeControlChars(dir);
       const displayPath = `${rootResult.displayRoot}${safeDir}`;
+      if (declared) {
+        lines.push(
+          `  warning: ${displayPath}/ is not part of this repo's skillset ` +
+            `(${skillsetRef}), but agents still load it from disk. Remove the ` +
+            `directory, or ask a skillset manager to add the skill. Until ` +
+            `then this repo is reported as not compliant.`,
+        );
+        continue;
+      }
       // The remediation must be a RUNNABLE command. A tilde-shortened
       // display root ("~/.claude/skills/") breaks copy-paste — quotes
       // suppress shell tilde expansion and Windows cmd never expands
@@ -217,6 +240,100 @@ export function formatForeignWarnings(scan) {
   return lines;
 }
 
+/**
+ * The repo compliance state line (#2665, owner decisions 2026-08-20):
+ * ONE sentence stating that the repo does not currently match its
+ * declared skillset and is reported as not compliant, listing the
+ * locally-observable causes as counts. Unlike the per-dir warnings
+ * above this is a STATE, not an event — callers print it on EVERY
+ * scoped sync while any cause persists (never gated on
+ * `.governance-seen`), including session-hook syncs, where it takes
+ * the `[SkillRepo]` prefix so the agent session sees it too (the
+ * #2495 disclosure precedent). Counts only — names stay in the
+ * per-dir warnings, which remain local-only and warn-on-new.
+ *
+ * Server-side causes a fresh sync cannot observe (behind-version or
+ * missing members on a repo that has not re-synced) surface on the
+ * dashboard instead — this line covers what THIS machine can see now.
+ *
+ * @param {object} input
+ * @param {string} input.skillsetRef - Declared skillset (`owner/name`).
+ * @param {number} [input.unmanagedCount] - Project-scope foreign dirs
+ *        (the scan-derived count — matches the receipt's `unmanaged`
+ *        violation category, deliberately NOT mixed with the
+ *        member-name collisions below).
+ * @param {number} [input.shadowedCount] - Global copies shadowing members.
+ * @param {number} [input.globalBeyondCount] - Global-scope skills beyond
+ *        the set (`global_library` + `global_foreign`).
+ * @param {number} [input.editRefusedCount] - Members whose LOCAL EDITS
+ *        the sync refused to overwrite (`unwrittenReason: "modified"`
+ *        only — the one bucket allowed to claim an edit).
+ * @param {number} [input.memberReplacedCount] - Members whose slot is
+ *        occupied by hand-authored content the CLI never wrote
+ *        (`unwrittenReason: "unmanaged"` — invisible to the foreign
+ *        scan because the dir name IS a managed member name).
+ * @param {number} [input.notDeliveredCount] - Members not delivered as
+ *        approved for server/payload reasons ("incomplete", "invalid")
+ *        or unknown legacy reasons — never phrased as an edit.
+ * @param {boolean} [input.hookMode] - Session-hook formatting
+ *        (`[SkillRepo]` prefix, single line for the hook UI).
+ * @returns {string | null} The line, or null when every count is zero.
+ */
+export function formatRepoComplianceSummary({
+  skillsetRef,
+  unmanagedCount = 0,
+  shadowedCount = 0,
+  globalBeyondCount = 0,
+  editRefusedCount = 0,
+  memberReplacedCount = 0,
+  notDeliveredCount = 0,
+  hookMode = false,
+}) {
+  const parts = [];
+  if (unmanagedCount > 0) {
+    parts.push(
+      `${unmanagedCount} extra skill${unmanagedCount === 1 ? "" : "s"} in the project`,
+    );
+  }
+  if (shadowedCount > 0) {
+    parts.push(
+      `${shadowedCount} member${shadowedCount === 1 ? "" : "s"} shadowed by a global copy`,
+    );
+  }
+  if (globalBeyondCount > 0) {
+    parts.push(
+      `${globalBeyondCount} global skill${globalBeyondCount === 1 ? "" : "s"} beyond the set`,
+    );
+  }
+  if (memberReplacedCount > 0) {
+    parts.push(
+      `${memberReplacedCount} member${memberReplacedCount === 1 ? "" : "s"} replaced by unmanaged content`,
+    );
+  }
+  if (editRefusedCount > 0) {
+    parts.push(
+      `${editRefusedCount} member${editRefusedCount === 1 ? "" : "s"} edited locally`,
+    );
+  }
+  if (notDeliveredCount > 0) {
+    parts.push(
+      `${notDeliveredCount} member${notDeliveredCount === 1 ? "" : "s"} not delivered as approved`,
+    );
+  }
+  if (parts.length === 0) return null;
+  const causes = parts.join(", ");
+  if (hookMode) {
+    return (
+      `[SkillRepo] This repo does not match its skillset ${skillsetRef} ` +
+      `(${causes}) — it is reported as not compliant.`
+    );
+  }
+  return (
+    `  warning: this repo does not match its skillset ${skillsetRef}: ` +
+    `${causes}. It is reported as not compliant to your organization.`
+  );
+}
+
 // ── Warn-on-new state (#2361 owner directive: no repeat warnings) ──────
 //
 // A warning that repeats unchanged findings on every sync trains users
@@ -245,11 +362,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 +409,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 +429,7 @@ export function readGovernanceSeen() {
         !Array.isArray(parsed.declarations)
           ? parsed.declarations
           : {},
+      globalBoundary: coerceGlobalBoundary(parsed.globalBoundary),
     };
   } catch {
     return emptySeenState();
@@ -396,7 +549,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;
 }
 
 /**