skillrepo 4.11.1 → 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,17 +195,46 @@ 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
 finds the file from any subdirectory (it walks up to the repository
-root) and validates it before syncing. Skillset delivery is not yet
-available: a repository with a declaration fails its sync closed
-(exit code `6`) rather than receiving the whole library — a declared
-repo only ever receives its declared skillset. Keep the declaration
-while your team prepares for skillsets, or remove the `skillset`
-block to sync your whole library. A `skillrepo.json` without a
-`skillset` key is plain configuration and does not change sync.
+root), validates it, and syncs that repository against the declared
+skillset instead of your whole library — a declared repo only ever
+receives its declared skillset. Skillset-scoped sync resolves the
+complete set on every pass: skills added to the skillset appear,
+skills removed from it are deleted from the repo's skill folders, and
+everything lands at the repository root no matter which subdirectory
+you run from. Deletes are guarded — a directory the CLI did not write,
+or one you modified locally, is never removed or overwritten; it stays
+put with a warning and shows up in your team's sync reporting instead.
+Declared entries in `extra` that cannot be honored (for example when
+extras are not enabled for your organization) are skipped loudly with
+the reason, never silently. If the registry is unreachable, the repo
+keeps serving its last-verified skills and the sync still exits
+successfully with a warning (the warning escalates once the state is
+more than ~72 hours old). If the declaration itself cannot be honored
+— unknown skillset, skillsets not enabled for your organization, an
+invalid file — the sync fails closed with exit code `6` and nothing is
+written or removed. A `skillrepo.json` without a `skillset` key is
+plain configuration and does not change sync. See
+[`docs/skillset-declaration.md`](docs/skillset-declaration.md) for the
+full file-format reference.
 
 ### `get` — fetch a single skill
 
@@ -586,7 +627,7 @@ citations on each agent's read paths.
 | 3 | Disk error (cannot read or write a file/directory) |
 | 4 | Scope error (key lacks the required `registry:write` scope) |
 | 5 | Validation error (bad flag, malformed identifier, unknown vendor) |
-| 6 | Unresolvable skillset declaration — the repo's root `skillrepo.json` declares a skillset that cannot be honored (invalid or nested declaration, reserved `@` version syntax, or skillset delivery not yet available). Fail-closed: nothing was written or removed. |
+| 6 | Unresolvable skillset declaration — the repo's root `skillrepo.json` declares a skillset that cannot be honored: an invalid or nested declaration, reserved `@` version syntax, an unknown skillset, or skillsets not enabled for your organization. Fail-closed: nothing was written or removed. A registry that is merely unreachable is NOT this class — the sync serves the last-verified skillset and exits `0` with a warning. |
 
 Pass `--verbose` to any command to print stack traces and retry
 attempts on failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "4.11.1",
+  "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/uninstall.mjs

@@ -102,6 +102,7 @@ const FILE_REMOVERS = Object.freeze({
   // Directory artifacts — handled inline.
   "skills-dir-project": null,
   "skills-dir-global": null,
+  "repo-sync-state-dir": null,
   "global-config-dir": null,
 });
 
@@ -141,12 +142,16 @@ function removeDirectoryArtifact(descriptor, { dryRun }) {
       error: `Cannot resolve ${path}: ${err.message}. Refusing to rmSync a path that doesn't resolve.`,
     };
   }
+  // "skills" = the placement caches, "skillrepo" = the global config
+  // dir, "repos" = the per-repo skillset state dir (#2365,
+  // repo-sync-state-dir descriptor).
+  const ALLOWED_DIR_BASENAMES = new Set(["skills", "skillrepo", "repos"]);
   const basename = realPath.split(/[\\/]/).filter(Boolean).pop();
-  if (basename !== "skills" && basename !== "skillrepo") {
+  if (!ALLOWED_DIR_BASENAMES.has(basename)) {
     return {
       path: displayPath,
       action: "skipped",
-      error: `Refusing to recursively remove ${path} (resolved to ${realPath}): basename "${basename}" is neither "skills" nor "skillrepo".`,
+      error: `Refusing to recursively remove ${path} (resolved to ${realPath}): basename "${basename}" is not a CLI-owned directory name (${[...ALLOWED_DIR_BASENAMES].join(", ")}).`,
     };
   }
 

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/artifact-registry.mjs

@@ -39,6 +39,7 @@ import {
   gitignorePath,
   claudeSkillsProjectRoot,
   claudeSkillsGlobalRoot,
+  globalRepoStateDir,
 } from "./paths.mjs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -359,14 +360,28 @@ export const ARTIFACT_REGISTRY = Object.freeze([
     pathFn: claudeSkillsGlobalRoot,
     displayPath: "~/.claude/skills/",
   }),
+  Object.freeze({
+    // Per-repo skillset sync state (#2365, design doc D12): one JSON
+    // file per declared repo, keyed by realpath hash. Listed BEFORE
+    // its parent `global-config-dir` so the uninstall preview
+    // discloses the state class explicitly and the child is removed
+    // first (the parent sweep then finds it already gone — removal
+    // stays idempotent either way).
+    id: "repo-sync-state-dir",
+    scope: "global",
+    kind: "directory",
+    pathFn: globalRepoStateDir,
+    displayPath: "~/.claude/skillrepo/repos/",
+  }),
   Object.freeze({
     id: "global-config-dir",
     scope: "global",
     kind: "directory",
     // `~/.claude/skillrepo/` — the parent dir of config.json,
-    // .last-sync, .npm-version-check, and .governance-seen (#2361).
-    // Whole-directory removal is correct because every child is
-    // CLI-owned and there's no room for user content.
+    // .last-sync, .npm-version-check, .governance-seen (#2361), and
+    // the repos/ state dir above (#2365). Whole-directory removal is
+    // correct because every child is CLI-owned and there's no room
+    // for user content.
     pathFn: () => join(homedir(), ".claude", "skillrepo"),
     displayPath: "~/.claude/skillrepo/",
   }),

package/src/lib/crypto-shas.mjs

@@ -56,6 +56,22 @@
 
 import { createHash } from "node:crypto";
 
+/**
+ * Hex SHA-256 of a single UTF-8 string. The shared low-level digest
+ * this module is built on, exported (#2365) so the per-repo state
+ * store can hash its realpath-derived state key without hand-rolling
+ * a second `createHash` call site (shared-logic rule). Pure — no I/O.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function sha256Hex(value) {
+  if (typeof value !== "string") {
+    throw new TypeError("sha256Hex: value must be a string");
+  }
+  return createHash("sha256").update(value, "utf8").digest("hex");
+}
+
 /**
  * @typedef {Object} SkillFileLike
  * @property {string} path     - Canonical POSIX path relative to skill root.

package/src/lib/errors.mjs

@@ -12,14 +12,15 @@
  *   6 — unresolvable skillset declaration (#2362, design doc D9): the
  *       repo's `skillrepo.json` skillset declaration cannot be honored
  *       (unparseable file, invalid sub-schema, nested declarations,
- *       reserved `@` version syntax, or skillset delivery not yet
- *       available). Fail-closed: nothing was written or removed. This
- *       one code covers the WHOLE D9 fail-closed class, locally AND —
- *       once H8 (#2365) wires the server — the server's typed 422
- *       `skillset_unresolvable` response (H6 #2363; renamed from the
- *       never-emitted `harness_unresolvable` per the D19 extension,
- *       owner decision 2026-08-11), so CI scripts get one stable
- *       "declaration cannot be honored" signal.
+ *       reserved `@` version syntax, or a server-determined cause —
+ *       unknown skillset, skillsets not enabled for the organization,
+ *       declaration owner mismatch). Fail-closed: nothing was written
+ *       or removed. This one code covers the WHOLE D9 fail-closed
+ *       class, locally AND the server's typed 422
+ *       `skillset_unresolvable` response consumed by the scoped sync
+ *       (#2365; H6 #2363 emitter — named per the D19 extension, never
+ *       `harness_unresolvable`, owner decision 2026-08-11), so CI
+ *       scripts get one stable "declaration cannot be honored" signal.
  *
  * These mirror the documented behavior in #683 and are the contract
  * shell users and CI scripts can rely on.

package/src/lib/file-write.mjs

@@ -235,18 +235,24 @@ export function validateFilePath(rawPath) {
  * Resolve the absolute filesystem directory for a skill at a given
  * placement target. The directory does not need to exist yet.
  *
+ * `baseDir` (#2365) anchors PROJECT-scope targets at a skillset repo's
+ * detected root instead of cwd; global targets ignore it (they live in
+ * the user's home regardless of where the sync runs). Omitted →
+ * cwd-anchored, byte-identical to the pre-#2365 behavior (D2).
+ *
  * @param {PlacementTarget} target
  * @param {string} skillName
+ * @param {string} [baseDir]
  * @returns {string}
  */
-export function resolvePlacementDir(target, skillName) {
+export function resolvePlacementDir(target, skillName, baseDir) {
   switch (target) {
     case "claudeProject":
-      return claudeSkillsProject(skillName);
+      return claudeSkillsProject(skillName, baseDir);
     case "claudeGlobal":
       return claudeSkillsGlobal(skillName);
     case "agentsProject":
-      return agentsSkillsProject(skillName);
+      return agentsSkillsProject(skillName, baseDir);
     case "agentsGlobal":
       return agentsSkillsGlobal(skillName);
     case "windsurfGlobal":
@@ -290,34 +296,25 @@ export function describePlacementTarget(target) {
  * detection in #1555) can enumerate skill placements without
  * duplicating the target→root mapping that already lives here.
  *
- * @param {PlacementTarget} target
- * @returns {string}
- */
-export function resolvePlacementRoot(target) {
-  return placementRootFn(target)();
-}
-
-/**
- * Map a `PlacementTarget` to its parent root resolver. Used by
- * `cleanupOrphans` to know which directories to scan for `.tmp`/`.old`
- * siblings, and by `resolvePlacementRoot` above for read-side
- * consumers.
+ * `baseDir` anchors project-scope roots (#2365) — same contract as
+ * `resolvePlacementDir` above.
  *
  * @param {PlacementTarget} target
- * @returns {() => string}
+ * @param {string} [baseDir]
+ * @returns {string}
  */
-function placementRootFn(target) {
+export function resolvePlacementRoot(target, baseDir) {
   switch (target) {
     case "claudeProject":
-      return claudeSkillsProjectRoot;
+      return claudeSkillsProjectRoot(baseDir);
     case "claudeGlobal":
-      return claudeSkillsGlobalRoot;
+      return claudeSkillsGlobalRoot();
     case "agentsProject":
-      return agentsSkillsProjectRoot;
+      return agentsSkillsProjectRoot(baseDir);
     case "agentsGlobal":
-      return agentsSkillsGlobalRoot;
+      return agentsSkillsGlobalRoot();
     case "windsurfGlobal":
-      return windsurfSkillsGlobalRoot;
+      return windsurfSkillsGlobalRoot();
     default: {
       throw validationError(`Unknown placement target: ${target}`);
     }
@@ -412,6 +409,9 @@ export function readFrontmatterName(files) {
  * @param {object} options
  * @param {string[]} [options.vendors] - Vendor keys; required unless `global`.
  * @param {boolean} [options.global] - If true, write to global Claude Code dir.
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365): a
+ *        skillset-scoped sync writes at the repo's detected root, not
+ *        cwd. Applies to placement dirs AND the .gitignore heal.
  * @returns {{ written: string[] }} Per-target absolute directory paths.
  *
  * Note: `writeSkillDir` does NOT short-circuit when an existing skill on
@@ -444,12 +444,12 @@ export function writeSkillDir(skill, options = {}) {
   // failure here AFTER a successful write to an earlier target would
   // leave the user with a half-applied state and an error message
   // that doesn't reflect what's actually on disk.
-  ensureProjectGitignore(targets);
+  ensureProjectGitignore(targets, options.baseDir);
 
   const written = [];
 
   for (const target of targets) {
-    const targetDir = resolvePlacementDir(target, skill.name);
+    const targetDir = resolvePlacementDir(target, skill.name, options.baseDir);
 
     try {
       writeSkillToDir(skill, targetDir);
@@ -473,6 +473,7 @@ export function writeSkillDir(skill, options = {}) {
  * @param {object} options
  * @param {string[]} [options.vendors]
  * @param {boolean} [options.global]
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365).
  * @returns {{ removed: string[], notFound: string[] }}
  */
 export function removeSkillDir(skillName, options = {}) {
@@ -485,7 +486,7 @@ export function removeSkillDir(skillName, options = {}) {
   const notFound = [];
 
   for (const target of targets) {
-    const targetDir = resolvePlacementDir(target, skillName);
+    const targetDir = resolvePlacementDir(target, skillName, options.baseDir);
     if (!existsSync(targetDir)) {
       notFound.push(targetDir);
       continue;
@@ -533,6 +534,7 @@ export function removeSkillDir(skillName, options = {}) {
  * @param {object} options
  * @param {string[]} [options.vendors]
  * @param {boolean} [options.global]
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365).
  * @returns {{ cleaned: string[] }}
  */
 export function cleanupOrphans(options = {}) {
@@ -543,19 +545,19 @@ export function cleanupOrphans(options = {}) {
       global: !!options.global,
     });
     for (const target of targets) {
-      roots.add(placementRootFn(target)());
+      roots.add(resolvePlacementRoot(target, options.baseDir));
     }
   } else if (options.global) {
     // No vendors under --global — sweep every known global root so a
     // stale orphan from any prior --global write is cleaned.
     for (const target of GLOBAL_TARGETS) {
-      roots.add(placementRootFn(target)());
+      roots.add(resolvePlacementRoot(target, options.baseDir));
     }
   } else {
     // No vendors and no --global — sweep every root we know about so
     // any orphan from any prior run is cleaned.
     for (const target of ALL_TARGETS) {
-      roots.add(placementRootFn(target)());
+      roots.add(resolvePlacementRoot(target, options.baseDir));
     }
   }
 
@@ -836,13 +838,15 @@ function writeSkillToDir(skill, targetDir) {
  * suspenders wrap here only converts a non-CliError escape.
  *
  * @param {PlacementTarget[]} targets
+ * @param {string} [baseDir] - Project-scope anchor (#2365): the heal
+ *        targets the repo root's .gitignore on a skillset-scoped sync.
  */
-function ensureProjectGitignore(targets) {
+function ensureProjectGitignore(targets, baseDir) {
   try {
-    ensureManagedRootIgnores(targets);
+    ensureManagedRootIgnores(targets, { baseDir });
   } catch (err) {
     if (err instanceof CliError) throw err;
-    throw diskError(`Cannot update ${gitignorePath()}: ${err.message}`, {
+    throw diskError(`Cannot update ${gitignorePath(baseDir)}: ${err.message}`, {
       cause: err,
     });
   }