skillrepo 4.11.0 → 4.12.0

package/README.md

@@ -187,13 +187,27 @@ 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 +600,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.0",
+  "version": "4.12.0",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

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/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,12 +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
- *       `harness_unresolvable` response, 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,
     });
   }

package/src/lib/foreign-content.mjs

@@ -105,10 +105,14 @@ export const UNMANAGED_CONTENT_CATEGORY = "unmanaged";
  * @param {Record<string, unknown> | null | undefined} options.managedSkills
  *        The `.last-sync` `skills` map (post-sync state) — keys are
  *        `"<owner>/<name>"`. Only the name half is used: placement
- *        dirs are keyed by skill name alone.
+ *        dirs are keyed by skill name alone. A skillset-scoped sync
+ *        (#2365) passes its per-repo resolved set in the same shape.
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365): a
+ *        skillset-scoped sync scans the placement roots at the repo's
+ *        detected root, not cwd. Omitted → cwd (unchanged behavior).
  * @returns {ForeignScanResult}
  */
-export function scanForeignContent({ vendors, global, managedSkills }) {
+export function scanForeignContent({ vendors, global, managedSkills, baseDir }) {
   /** @type {ForeignScanResult} */
   const result = { roots: [], foreignCount: 0 };
 
@@ -137,7 +141,7 @@ export function scanForeignContent({ vendors, global, managedSkills }) {
       // Normalized (realpath + win32 case-fold) because `root` doubles
       // as the seen-state key — see normalizeStateKey. The D12 sibling
       // state store already uses realpath-keyed state; same reasoning.
-      root = normalizeStateKey(resolvePlacementRoot(target));
+      root = normalizeStateKey(resolvePlacementRoot(target, baseDir));
     } catch {
       continue;
     }

package/src/lib/gitignore-section.mjs

@@ -59,9 +59,13 @@ export const MANAGED_ROOT_ENTRIES = Object.freeze({
  * repo content, so there is nothing to ignore.
  *
  * @param {string[]} targets - PlacementTarget values for the current write.
+ * @param {object} [options]
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365): a
+ *        skillset-scoped sync heals the .gitignore at the repo's
+ *        detected root, not cwd. Omitted → cwd (unchanged behavior).
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
-export function ensureManagedRootIgnores(targets) {
+export function ensureManagedRootIgnores(targets, options = {}) {
   const entries = [];
   if (Array.isArray(targets)) {
     for (const [target, entry] of Object.entries(MANAGED_ROOT_ENTRIES)) {
@@ -71,7 +75,7 @@ export function ensureManagedRootIgnores(targets) {
   if (entries.length === 0) {
     return { path: ".gitignore", action: "skipped", added: [] };
   }
-  return ensureGitignoreEntries(entries);
+  return ensureGitignoreEntries(entries, options);
 }
 
 /**
@@ -84,10 +88,12 @@ export function ensureManagedRootIgnores(targets) {
  * `"updated"` otherwise.
  *
  * @param {string[]} requiredEntries
+ * @param {object} [options]
+ * @param {string} [options.baseDir] - Project-scope anchor (#2365).
  * @returns {{ path: string; action: "created" | "updated" | "skipped"; added: string[] }}
  */
-export function ensureGitignoreEntries(requiredEntries) {
-  const filePath = gitignorePath();
+export function ensureGitignoreEntries(requiredEntries, options = {}) {
+  const filePath = gitignorePath(options.baseDir);
   let existing;
   try {
     existing = readFileSafe(filePath);

package/src/lib/http.mjs

@@ -26,6 +26,7 @@ import {
   authError,
   networkError,
   scopeError,
+  unresolvableError,
   validationError,
   withRetry,
 } from "./errors.mjs";
@@ -370,6 +371,20 @@ async function mapErrorResponse(res, url) {
   if (res.status === 404) {
     return null; // Caller decides
   }
+  if (res.status === 422 && code === "skillset_unresolvable") {
+    // H6 #2363's typed fail-closed response for a skillset-scoped sync
+    // (design doc D9, wire name locked by the 2026-08-11 owner
+    // decision — never `harness_unresolvable`). Every cause — malformed
+    // params, skillsets not enabled for the organization, declaration
+    // owner mismatch, unknown skillset name — maps onto the ONE stable
+    // EXIT_UNRESOLVABLE (6) via the machine `code` field, never a
+    // message string-compare. The server's `error` text is the
+    // complete actionable copy and is surfaced VERBATIM: no CLI-side
+    // hint, nothing appended. The server never falls back to a
+    // whole-library payload on this class, so the caller writes and
+    // deletes nothing (#2365).
+    return unresolvableError(message);
+  }
   if (res.status === 422 && code === "handle_required") {
     // #2310: the push would CREATE a skill while the account's Author ID
     // is still an unchosen placeholder. Line 1 is the server's message
@@ -530,12 +545,28 @@ export async function validateAccessKey(serverUrl, apiKey, source = "validate")
  */
 
 /**
+ * @typedef {Object} SkippedExtra
+ * @property {string} skill   - `"owner/name"` of the unhonorable extra.
+ * @property {string} reason  - Stable machine enum (`extras_disabled` |
+ *   `not_in_library`). The CLI categorizes and stores by this field only.
+ * @property {string} message - Canonical remediation copy — printed
+ *   VERBATIM, one warn line per entry (E5-as-revised), never persisted
+ *   or echoed upstream (presentation-only).
+ *
+ * @typedef {Object} SkillsetBlock
+ * @property {string} name
+ * @property {string} updatedAt
+ * @property {SkippedExtra[]} skippedExtras
+ *
  * @typedef {Object} LibrarySyncResult
  * @property {SyncSkill[]} skills
  * @property {Removal[]} removals
  * @property {string} syncedAt
  * @property {string|null} etag
  * @property {boolean} notModified  - True if the server returned 304
+ * @property {SkillsetBlock|null} skillset - Present only on a
+ *   skillset-scoped 200 (#2365, H6 #2363 contract); null on the bulk
+ *   path and on 304.
  */
 
 /**
@@ -563,6 +594,15 @@ export async function validateAccessKey(serverUrl, apiKey, source = "validate")
  *   the server returns empty `files` for every skill and records NO
  *   delivery. Used by `skillrepo list` for a read-only drift check that
  *   must not set sync state (#1832).
+ * @param {string} [opts.skillset]    - Skillset-scoped sync (#2365, H6
+ *   #2363 contract): the declaration's `use` pointer (`"owner/name"`).
+ *   When present the request carries `skillset`, `repo`, and repeated
+ *   `extra` params — callers must NOT combine with `since` (the server
+ *   ignores it on this path; D10 full-set semantics).
+ * @param {string} [opts.repo]        - The declaration's `name`.
+ *   REQUIRED by the server whenever `skillset` is present.
+ * @param {string[]} [opts.extra]     - Declaration `extra` entries,
+ *   appended verbatim in declaration order (server dedups).
  * @returns {Promise<LibrarySyncResult>}
  */
 export async function getLibrary(serverUrl, apiKey, opts = {}) {
@@ -573,6 +613,17 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
   // `skillrepo list`. A peek must not set sync state, so the server
   // returns empty `files` and records no delivery for this request.
   if (opts.manifest) params.set("manifest", "1");
+  // Skillset-scoped params (#2365). Wire identity (D2): a caller that
+  // omits `skillset` produces a byte-identical request to the
+  // pre-skillset CLI — these branches add params only when the scoped
+  // sync explicitly asks for them.
+  if (opts.skillset) {
+    params.set("skillset", opts.skillset);
+    if (opts.repo !== undefined) params.set("repo", opts.repo);
+    for (const extra of Array.isArray(opts.extra) ? opts.extra : []) {
+      params.append("extra", extra);
+    }
+  }
   const url = params.toString()
     ? `${base}/api/v1/library?${params.toString()}`
     : `${base}/api/v1/library`;
@@ -593,6 +644,7 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
       syncedAt: new Date().toISOString(),
       etag: opts.ifNoneMatch || null,
       notModified: true,
+      skillset: null,
     };
   }
 
@@ -609,8 +661,24 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
     skills: body.skills ?? [],
     removals: body.removals ?? [],
     syncedAt: body.syncedAt ?? new Date().toISOString(),
+    // Verbatim as received (#2365 ETag rule): Vercel serves strong
+    // ETags as weak (`W/"ss-…"`) — the value is OPAQUE, stored and
+    // round-tripped exactly, never parsed or normalized.
     etag: res.headers.get("etag"),
     notModified: false,
+    // Skillset block (#2365): present only on a scoped 200. Normalized
+    // to null (not undefined) so consumers can branch without optional
+    // chaining surprises; skippedExtras normalizes to [].
+    skillset:
+      body.skillset && typeof body.skillset === "object"
+        ? {
+            name: body.skillset.name,
+            updatedAt: body.skillset.updatedAt,
+            skippedExtras: Array.isArray(body.skillset.skippedExtras)
+              ? body.skillset.skippedExtras
+              : [],
+          }
+        : null,
   };
 }
 
@@ -633,6 +701,14 @@ export async function getLibrary(serverUrl, apiKey, opts = {}) {
  * @param {{owner: string, name: string, version: string}[]} receipt.skills
  *   The skills written to disk this sync. Empty array is a valid no-op.
  * @param {string} receipt.syncedAt - ISO timestamp of the sync.
+ * @param {object} [receipt.repo] - Skillset-scoped repo block (#2365,
+ *   H7 #2364 wire contract): `{ name, skillset, resolved, and optional
+ *   skippedExtras / violations }`. OMITTED ENTIRELY on no-file repos —
+ *   the D2 wire-identity contract requires a plain sync's receipt body
+ *   to stay byte-identical to the pre-skillset CLI, so the key is only
+ *   serialized when a scoped sync supplies it. The block is assembled
+ *   by sync.mjs (`buildRepoReceiptBlock`) — this layer passes it
+ *   through verbatim.
  * @returns {Promise<{recorded: number}>}
  */
 export async function postSyncReceipt(serverUrl, apiKey, receipt) {
@@ -646,9 +722,12 @@ export async function postSyncReceipt(serverUrl, apiKey, receipt) {
     body: JSON.stringify({
       syncedAt: receipt.syncedAt,
       skills: receipt.skills,
+      ...(receipt.repo ? { repo: receipt.repo } : {}),
     }),
     // Idempotent server-side (dedup bucket + idempotent UPDATE), so a
-    // transient 5xx / network blip is safe to retry.
+    // transient 5xx / network blip is safe to retry. Receipts carrying
+    // the `repo` block are idempotent by construction too (#2364:
+    // change-only event append server-side), so the same posture holds.
     retry: true,
   });
   if (!res.ok) {

package/src/lib/paths.mjs

@@ -1,6 +1,13 @@
 /**
  * Cross-platform path resolution for all config files the CLI writes.
  * Uses Node built-ins only — no dependencies.
+ *
+ * Project-scope resolvers accept an optional `baseDir` (#2365): a
+ * skillset-scoped sync anchors every repo-scoped path at the walk-up's
+ * DETECTED ROOT (H5 `rootDir`, design doc D6), not cwd. Omitting the
+ * argument resolves against `process.cwd()` — byte-identical to the
+ * pre-#2365 behavior, which is what keeps undeclared repos on today's
+ * cwd-anchored path (D2).
  */
 
 import { join } from "node:path";
@@ -8,6 +15,18 @@ import { homedir } from "node:os";
 
 const cwd = () => process.cwd();
 
+/**
+ * Resolve a project-scope base directory: the caller-supplied anchor
+ * (a skillset repo's detected root) or the process cwd. A non-string /
+ * empty override falls back to cwd rather than producing a relative
+ * join off `""`.
+ *
+ * @param {string} [baseDir]
+ * @returns {string}
+ */
+const projectBase = (baseDir) =>
+  typeof baseDir === "string" && baseDir.length > 0 ? baseDir : cwd();
+
 // Claude Code
 export const claudeMcpJson = () => join(cwd(), ".mcp.json");
 export const claudeDir = () => join(cwd(), ".claude");
@@ -49,6 +68,19 @@ export const globalNpmVersionCheckPath = () =>
 export const globalGovernanceSeenPath = () =>
   join(homedir(), ".claude", "skillrepo", ".governance-seen");
 
+/**
+ * Per-repo skillset sync state directory (#2365, design doc D12).
+ * One JSON file per declared repo, named by the sha-256 of the
+ * repo root's normalized realpath — see `repo-sync-state.mjs` for
+ * the schema and keying rules. Separate SUBDIRECTORY (not another
+ * dot-file) because the population is unbounded (one file per repo)
+ * and uninstall / support flows want to sweep it as a unit. Same
+ * parent dir as `.last-sync` so `rm -rf ~/.claude/skillrepo/` still
+ * removes every piece of machine state.
+ */
+export const globalRepoStateDir = () =>
+  join(homedir(), ".claude", "skillrepo", "repos");
+
 // ── Skill placement targets ────────────────────────────────────────────
 //
 // Per-vendor placement decisions live in `agent-registry.mjs`. This
@@ -58,22 +90,26 @@ export const globalGovernanceSeenPath = () =>
 // the verified vendor-by-vendor reference and primary-source citations.
 
 /** Claude Code project-local skill directory for a specific skill name. */
-export const claudeSkillsProject = (name) => join(cwd(), ".claude", "skills", name);
+export const claudeSkillsProject = (name, baseDir) =>
+  join(projectBase(baseDir), ".claude", "skills", name);
 
 /** Claude Code personal/global skill directory for a specific skill name. */
 export const claudeSkillsGlobal = (name) => join(homedir(), ".claude", "skills", name);
 
 /** Parent directory of the project-local Claude Code skills (used by orphan cleanup). */
-export const claudeSkillsProjectRoot = () => join(cwd(), ".claude", "skills");
+export const claudeSkillsProjectRoot = (baseDir) =>
+  join(projectBase(baseDir), ".claude", "skills");
 
 /** Parent directory of the personal/global Claude Code skills (used by orphan cleanup). */
 export const claudeSkillsGlobalRoot = () => join(homedir(), ".claude", "skills");
 
 /** Cross-vendor `.agents/skills/<name>/` project-local placement (cursor, windsurf, gemini, codex, cline, copilot). */
-export const agentsSkillsProject = (name) => join(cwd(), ".agents", "skills", name);
+export const agentsSkillsProject = (name, baseDir) =>
+  join(projectBase(baseDir), ".agents", "skills", name);
 
 /** Parent of the project-local `.agents/skills/` cohort root (used by orphan cleanup). */
-export const agentsSkillsProjectRoot = () => join(cwd(), ".agents", "skills");
+export const agentsSkillsProjectRoot = (baseDir) =>
+  join(projectBase(baseDir), ".agents", "skills");
 
 /** Cross-vendor personal `.agents/skills/<name>/` placement (cursor, gemini, codex, cline). */
 export const agentsSkillsGlobal = (name) => join(homedir(), ".agents", "skills", name);
@@ -96,8 +132,10 @@ export const envLocal = () => join(cwd(), ".env.local");
 /**
  * Project .gitignore — used by the file-write pipeline to ensure the
  * `.agents/skills/` cohort directory is gitignored on first write.
+ * `baseDir` (#2365): a skillset-scoped sync heals the .gitignore at
+ * the repo's detected root, not cwd.
  */
-export const gitignorePath = () => join(cwd(), ".gitignore");
+export const gitignorePath = (baseDir) => join(projectBase(baseDir), ".gitignore");
 
 // ── Claude Code settings ──────────────────────────────────────────────
 //