skillrepo 4.9.2 → 4.11.0

package/src/lib/sync.mjs

@@ -15,6 +15,13 @@
  *     direct write (avoids clock-skew on the `since` filter).
  *   • PR3a's `remove` does NOT use this — it deletes locally directly
  *     (avoids the ETag cache poisoning on tombstones, see #875).
+ *   • Because `add`/`get`/`remove` bypass `runSync`, they also bypass
+ *     the #2362 skillset-declaration gate below — DELIBERATE in H5:
+ *     the declaration governs the ambient sync surface, not a hard
+ *     per-repo ACL (D15: skillset curates, never authorizes). Whether
+ *     scoped repos should gate or receipts-surface these commands is
+ *     an open H8 decision, recorded on #2365 — do not "fix" the
+ *     bypass here as a bug.
  *   • PR3b's `init` calls `runSync({ vendors, global })` after writing
  *     the global config to perform the first pull.
  *
@@ -99,6 +106,18 @@
  *                                   Consumers must distinguish these to
  *                                   render accurate user messages (see
  *                                   init.mjs step 7).
+ * @property {number} [unmanaged] - Unmanaged (non-CLI-managed) skill dirs
+ *                                   detected in the managed placement roots
+ *                                   this sync writes to (#2361). "unmanaged"
+ *                                   is the one wire word for this concept —
+ *                                   same as the receipts category and the
+ *                                   warning copy; the design doc's internal
+ *                                   term is "foreign content". Warn-only
+ *                                   observability — NOT part of the change
+ *                                   totals the hook printers gate on, so a
+ *                                   304 with unmanaged content stays silent
+ *                                   in hook modes. Absent on a throttled
+ *                                   skip (detection doesn't run there).
  * @property {string} syncedAt    - ISO timestamp of the sync: the server
  *                                   response `syncedAt` on a 200, or the
  *                                   previously-cached sync timestamp on a
@@ -152,6 +171,20 @@ import {
   EXIT_VALIDATION,
 } from "./errors.mjs";
 import { computeSkillShas } from "./crypto-shas.mjs";
+import {
+  scanForeignContent,
+  formatForeignWarnings,
+  checkDeclarationGitignored,
+  formatDeclarationIgnoredWarning,
+  readGovernanceSeen,
+  commitGovernanceSeen,
+  selectNewFindings,
+  normalizeStateKey,
+} from "./foreign-content.mjs";
+import {
+  resolveDeclaration,
+  declarationUnavailableError,
+} from "./skillset-declaration.mjs";
 
 /**
  * Current schema version of the .last-sync file. Bump on any
@@ -641,6 +674,12 @@ export function deleteLastSyncEntry(owner, name) {
  *      (#2174): a hook-triggered sync (`throttle: true`) within
  *      MIN_SYNC_INTERVAL_MS of the last attempt short-circuits HERE with
  *      ZERO network calls. A bare interactive `update` never throttles.
+ *   1b. Skillset-declaration gate (#2362, project scope only): resolve
+ *      the repo's `skillrepo.json` via walk-up; any found declaration
+ *      fails the sync closed (typed EXIT 6) BEFORE any write, delete,
+ *      or network call — invalid files with a precise schema error,
+ *      well-formed ones with the pre-H8 "not yet available" error.
+ *      No declaration → everything below is byte-identical (D2).
  *   2. Clean up any orphan .tmp/.old directories from a crashed prior run
  *   3. Call GET /api/v1/library with `If-None-Match` (if we have a
  *      cached ETag) AND `since` (always, for delta semantics)
@@ -762,6 +801,39 @@ export async function runSync(options) {
     }
   }
 
+  // Skillset-declaration gate (#2362, D9). A repo that declares a
+  // skillset must NEVER receive whole-library delivery, and an
+  // invalid declaration must not sync at all — fail closed, before
+  // ANY write, delete, or network call (cleanupOrphans included: the
+  // contract is "nothing on disk changes"). Placement of this gate:
+  //
+  //   • AFTER the throttle early-exit — a throttled hook sync does
+  //     zero work of any kind (#2174), which trivially satisfies
+  //     fail-closed, and keeps session starts free of filesystem
+  //     walking. Interactive `update` is never throttled, so the
+  //     error always surfaces there within one command.
+  //   • Project-scoped syncs only. `--global` writes personal
+  //     placements in the user's home, not this repo — the
+  //     global-scope boundary is D20's territory (#2495 disclosure +
+  //     receipts category 3), not the declaration's.
+  //
+  // Pre-H8 dark shipping: there is no client-side skillset
+  // resolution yet, so a WELL-FORMED declaration is unresolvable by
+  // definition and gets the "not yet available" error. H8 (#2365)
+  // replaces that throw with real resolution against the server.
+  // Repos with no declaration take the `absent`/`config-only` path —
+  // read-only probes, byte-identical wire behavior (D2).
+  let declarationResolution = null;
+  if (global !== true) {
+    declarationResolution = resolveDeclaration();
+    if (declarationResolution.status === "invalid") {
+      throw declarationResolution.error;
+    }
+    if (declarationResolution.status === "declared") {
+      throw declarationUnavailableError(declarationResolution);
+    }
+  }
+
   // Step 2: clean orphans from prior crashes BEFORE doing any new writes
   cleanupOrphans({ vendors, global });
 
@@ -913,12 +985,27 @@ export async function runSync(options) {
           `Next sync will not be throttled.\n`,
       );
     }
+    // Foreign-content detection runs on the 304 path too (#2361): the
+    // library being unchanged says nothing about what else sits in the
+    // managed roots, and a deliberately-stable library would otherwise
+    // never surface violations. The on-disk managed set on a 304 is
+    // exactly the prior `.last-sync` skills map.
+    const unmanaged = emitGovernanceWarnings({
+      vendors,
+      global,
+      managedSkills: lastSync?.skills,
+      stderr,
+      hookMode: throttle === true,
+      declarationDir: declarationResolution?.rootDir,
+    });
+
     return {
       added: 0,
       updated: 0,
       removed: 0,
       notModified: true,
       fullSync,
+      unmanaged,
       syncedAt: lastSync?.syncedAt ?? new Date().toISOString(),
     };
   }
@@ -1130,6 +1217,18 @@ export async function runSync(options) {
     }
   }
 
+  // Foreign-content detection (#2361): after writes and tombstones, so
+  // skills delivered THIS round are already in `skillsMap` and never
+  // misclassified as unmanaged. Warn-only; never affects the sync result.
+  summary.unmanaged = emitGovernanceWarnings({
+    vendors,
+    global,
+    managedSkills: skillsMap,
+    stderr,
+    hookMode: throttle === true,
+    declarationDir: declarationResolution?.rootDir,
+  });
+
   // Re-assert the full on-disk state via a sync receipt (#1832). This
   // confirmed-write signal — not the fetch itself — is what sets team
   // sync state. We post the COMPLETE post-sync on-disk set (`skillsMap`:
@@ -1157,6 +1256,86 @@ export async function runSync(options) {
 
 // ── Internals ──────────────────────────────────────────────────────────
 
+/**
+ * Run the sync-time governance checks and write their warnings to the
+ * caller's stderr (#2361): foreign-content detection over the managed
+ * roots this sync writes to, plus the gitignored-declaration probe.
+ * Returns the unmanaged-dir count for the summary.
+ *
+ * Warn-only by construction — never throws, never changes sync
+ * behavior. Foreign dir NAMES appear only in these local warning
+ * lines; anything that leaves the machine goes through
+ * `receiptViolationSummary` (counts/category only — the H7 #2364
+ * seam; see foreign-content.mjs for the privacy contract).
+ *
+ * WARN-ON-NEW (owner directive, 2026-08-07): a warning that repeats
+ * unchanged findings on every sync trains users to ignore it. The
+ * already-warned set persists in `.governance-seen`; only NEW findings
+ * print, and a removed-then-reappearing dir re-warns. The returned
+ * count is always the TOTAL currently on disk (state observability),
+ * not just the new ones.
+ *
+ * HOOK SYNCS (`hookMode: true` — the --session-hook / --silent
+ * branches) neither print warnings nor mark findings as seen: the
+ * user isn't looking at those streams, and recording seen there would
+ * permanently swallow the warning before an interactive sync ever
+ * showed it. Governance warnings are an interactive-surface feature;
+ * hook syncs still contribute the count. The throttled early-exit
+ * returns before this runs at all (zero-work contract).
+ *
+ * @param {object} options
+ * @param {string[]} [options.vendors]
+ * @param {boolean} [options.global]
+ * @param {Record<string, unknown> | null | undefined} options.managedSkills
+ * @param {NodeJS.WritableStream} options.stderr
+ * @param {boolean} [options.hookMode] - True for hook-triggered syncs.
+ * @param {string} [options.declarationDir] - The walk-up's detected
+ *        root (#2362): the directory holding the repo's
+ *        `skillrepo.json`, when one was found. The gitignored probe
+ *        and its warn-on-new key anchor HERE, not cwd, so a sync run
+ *        from a subdirectory still probes the actual file and two
+ *        subdirectories of one repo share one seen flag. Absent (no
+ *        file found, or a `--global` sync where the walk never ran) →
+ *        cwd, preserving the H4 behavior.
+ * @returns {number} Unmanaged-dir count across scanned roots (the
+ *          summary's `unmanaged` field — total, not just new).
+ */
+function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMode, declarationDir }) {
+  let unmanagedCount = 0;
+  try {
+    const scan = scanForeignContent({ vendors, global, managedSkills });
+    unmanagedCount = scan.foreignCount;
+    if (hookMode) return unmanagedCount;
+
+    const seen = readGovernanceSeen();
+    const newScan = selectNewFindings(scan, seen);
+    for (const line of formatForeignWarnings(newScan)) {
+      stderr.write(`${line}\n`);
+    }
+
+    // Gitignored-declaration warning, gated the same way: once per
+    // repo while the state holds; leaving the gitignored state re-arms
+    // it. Keyed by the NORMALIZED repo path (realpath + win32
+    // case-fold) so two spellings of one checkout share a flag.
+    // Anchored at the walk-up's detected root when one exists (#2362).
+    const probeDir = declarationDir ?? process.cwd();
+    const repoKey = normalizeStateKey(probeDir);
+    const decl = checkDeclarationGitignored({ cwd: probeDir });
+    const declarationIgnored = decl.present && decl.ignored;
+    if (declarationIgnored && !seen.declarations[repoKey]) {
+      stderr.write(`${formatDeclarationIgnoredWarning()}\n`);
+    }
+
+    // Narrow-merge commit: re-reads the file and rewrites ONLY this
+    // sync's scanned roots + this repo's declaration flag, so a
+    // concurrent sync in another repo keeps its update.
+    commitGovernanceSeen({ scan, repoKey, declarationIgnored });
+  } catch {
+    // Detection is best-effort; a probe failure must never fail a sync.
+  }
+  return unmanagedCount;
+}
+
 /**
  * Build sync-receipt entries from a `.last-sync` skills map (#1832).
  *

package/src/test/commands/add.test.mjs

@@ -381,3 +381,27 @@ describe("runAdd — best-effort .last-sync write failure does not fail the comm
     );
   });
 });
+
+// ── Skillset-declaration NON-gating (#2362 baseline lock) ─────────────
+
+describe("runAdd — deliberately ungated by the skillset declaration (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("a declared repo can still `add` a single skill (D15: curate, never authorize)", async () => {
+    // Same baseline-lock rationale as the runGet twin: the open H8
+    // decision on #2365 must change this deliberately, never silently.
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+    // Default mock answers the add POST with 201; register the skill
+    // for the follow-up GET, same as the happy-path test above.
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runAdd(["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper"], { stdout });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "pdf-helper")));
+  });
+});

package/src/test/commands/get.test.mjs

@@ -309,3 +309,27 @@ describe("runGet — best-effort .last-sync write failure does not fail the comm
     );
   });
 });
+
+// ── Skillset-declaration NON-gating (#2362 baseline lock) ─────────────
+
+describe("runGet — deliberately ungated by the skillset declaration (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("a declared repo can still `get` a single skill (D15: curate, never authorize)", async () => {
+    // The declaration gates the ambient sync surface (runSync) only.
+    // Whether scoped repos should gate get/add is an OPEN H8 decision
+    // (#2365) — this test locks TODAY'S contract so H8 changes it
+    // deliberately, not by accident.
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+    server.setSkillResponse("alice", "pdf-helper", makeSkill("alice", "pdf-helper"));
+    await runGet(["--key", VALID_KEY, "--url", serverUrl, "@alice/pdf-helper"], { stdout });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "pdf-helper")));
+  });
+});

package/src/test/commands/init.test.mjs

@@ -2401,3 +2401,40 @@ describe("directoryHasContent", () => {
     }
   });
 });
+
+// ── Skillset-declaration awareness (#2362) ─────────────────────────────
+
+describe("runInit — skillset-declaration awareness (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("declared repo: init completes (exit path 0), config saved, tailored blocked-sync copy", async () => {
+    mkdirSync(join(process.cwd(), ".git"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+
+    await runInit(
+      ["--key", VALID_KEY, "--url", serverUrl, "--yes"],
+      { stdout, stderr },
+    );
+
+    // Config IS persisted — the sync gate must not fail the init.
+    const cfg = readConfig();
+    assert.ok(cfg, "config must be written even when the declaration gates the sync");
+    assert.equal(cfg.apiKey, VALID_KEY);
+
+    const out = stdout.text();
+    // Tailored copy: the generic "run update later to retry" advice is
+    // wrong for a declaration-gated repo (retrying changes nothing).
+    assert.match(out, /library sync is blocked/);
+    assert.match(out, /not yet available/);
+    assert.doesNotMatch(out, /Run `skillrepo update` later to retry/);
+    // The what-to-do hint from the typed error is included.
+    assert.match(out, /Keep the declaration/);
+    assert.match(out, /SkillRepo is ready/);
+  });
+});

package/src/test/commands/update.test.mjs

@@ -261,6 +261,25 @@ describe("runUpdate — --session-hook contract", () => {
     );
   });
 
+  it("stays silent on a zero-change sync even when foreign content is present (#2361)", async () => {
+    // Foreign dirs are observability, not changes: the hook-mode
+    // output gate keys on added+updated+removed+skipped, and the
+    // foreign count must never trip it. Both streams are black-holed
+    // in this mode, so the warning lines vanish too — session start
+    // stays clean.
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const dir = join(process.cwd(), ".claude", "skills", "hand-rolled");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: hand-rolled\n---\n");
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--session-hook"],
+      { stdout },
+    );
+    assert.equal(stdout.text(), "", "foreign content must not break hook silence");
+  });
+
   it("is silent on 304 / up-to-date (no 'Syncing' output every session)", async () => {
     // INTENT: 304 means nothing changed. Printing "Syncing..." on
     // every session start with no value to show would clutter the
@@ -473,6 +492,38 @@ describe("runUpdate — --silent contract", () => {
     assert.equal(stdout.text(), "{}\n");
   });
 
+  it("emits no governance warning under --silent, and does not consume it (#2361)", async () => {
+    // Governance warnings are an interactive-surface feature: hook
+    // syncs print nothing (the user is not looking at vendor hook
+    // logs) and must NOT mark the finding as seen — the next
+    // interactive `update` is the first to warn. Stdout stays pure
+    // JSON either way (Gemini contract).
+    const { mkdirSync, writeFileSync } = await import("node:fs");
+    const { join } = await import("node:path");
+    const { createCaptureStream } = await import("../helpers/capture-stream.mjs");
+    const dir = join(process.cwd(), ".claude", "skills", "hand-rolled");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "SKILL.md"), "---\nname: hand-rolled\n---\n");
+    const stderr = createCaptureStream();
+    server.setLibraryResponse({ skills: [], removals: [], syncedAt: "x" });
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--silent"],
+      { stdout, stderr },
+    );
+    assert.equal(stdout.text(), "{}\n", "stdout must stay pure JSON");
+    assert.ok(!stderr.text().includes("not from your library"), "hook sync must not warn");
+
+    // Interactive update afterwards: the warning is still available.
+    const stdout2 = createCaptureStream();
+    const stderr2 = createCaptureStream();
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl],
+      { stdout: stdout2, stderr: stderr2 },
+    );
+    assert.match(stderr2.text(), /hand-rolled/);
+    assert.match(stderr2.text(), /skillrepo push/);
+  });
+
   it("emits `{}\\n` even when the sync produced changes (no progress lines on stdout)", async () => {
     server.setLibraryResponse({
       skills: [makeSkill("silent-test")],
@@ -855,3 +906,146 @@ describe("runUpdate — SessionStart throttle (#2174)", () => {
     assert.deepEqual(after.skills, prior.skills, "per-skill SHA baseline preserved");
   });
 });
+
+// ── Skillset-declaration gate through the update command (#2362) ───────
+
+describe("runUpdate — skillset-declaration gate (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  function writeDeclaredRepo() {
+    // .git bounds the walk inside the sandbox project dir.
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+  }
+
+  it("normal mode: rejects with EXIT 6 and the not-yet-available copy", async () => {
+    writeDeclaredRepo();
+    await assert.rejects(
+      runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => {
+        assert.ok(err instanceof CliError);
+        assert.equal(err.exitCode, 6);
+        assert.match(err.message, /not yet available/);
+        assert.match(err.hint, /Keep the declaration/);
+        return true;
+      },
+    );
+  });
+
+  it("--session-hook: exits cleanly with the one-line failure message (contract: exit 0)", async () => {
+    writeDeclaredRepo();
+    // runUpdate must RESOLVE (the session-hook contract catches every
+    // error); the failure surfaces as the single stdout line.
+    await runUpdate(
+      ["--session-hook", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+    const out = stdout.text();
+    assert.match(out, /^\[SkillRepo\] Sync failed: /);
+    assert.match(out, /not yet available/);
+    assert.equal(out.trim().split("\n").length, 1, "exactly one output line");
+  });
+
+  it("--silent: propagates the typed error (cohort hooks surface real exit codes)", async () => {
+    writeDeclaredRepo();
+    await assert.rejects(
+      runUpdate(["--silent", "--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === 6,
+    );
+    assert.equal(stdout.text(), "", "no {} success line on failure");
+  });
+
+  it("invalid declaration through update: names the problem field", async () => {
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({ skillset: { version: 1, name: "checkout", use: "acme/x@2" } }),
+    );
+    await assert.rejects(
+      runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err.exitCode === 6 && /not yet supported/.test(err.message),
+    );
+  });
+});
+
+// ── Throttle window + declaration interplay through the hook flags ─────
+// (#2362 prod-readiness QA): a throttled hook sync returns BEFORE the
+// gate by documented design (#2174 zero-work contract). A repo that
+// synced successfully, then gained a declaration, stays SILENT in hook
+// modes until the window lapses — intentional, pinned here so it can
+// never be mistaken for (or regress into) a masked failure. Interactive
+// `update` is never throttled, so the error always surfaces there.
+
+describe("runUpdate — throttled hook syncs precede the declaration gate (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  function armThrottleThenDeclare() {
+    writeLastSync({
+      etag: '"e1"',
+      syncedAt: new Date().toISOString(),
+      skills: {},
+      lastAttemptAt: new Date().toISOString(),
+    });
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+  }
+
+  it("--silent within the window: '{}' success line, zero network", async () => {
+    armThrottleThenDeclare();
+    await runUpdate(["--silent", "--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.equal(stdout.text(), "{}\n");
+    assert.equal(server.getLibraryRequestCount(), 0);
+  });
+
+  it("--session-hook within the window: no output at all, zero network", async () => {
+    armThrottleThenDeclare();
+    await runUpdate(["--session-hook", "--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.equal(stdout.text(), "");
+    assert.equal(server.getLibraryRequestCount(), 0);
+  });
+
+  it("interactive update ignores the window and surfaces the gate error", async () => {
+    armThrottleThenDeclare();
+    await assert.rejects(
+      runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === 6,
+    );
+  });
+});
+
+// ── --json + declared repo: pin the CURRENT error contract (#2362) ─────
+
+describe("runUpdate — --json with a declared repo (#2362)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("rejects with the typed exit-6 error and writes NO stdout (no JSON error envelope today)", async () => {
+    // The dispatcher's catch prints plain text to stderr regardless of
+    // --json — a systemic CLI contract, not #2362-specific. Pinned so
+    // a structured-JSON error surface is a deliberate future change.
+    mkdirSync(join(sandbox, "project", ".git"), { recursive: true });
+    writeFileSync(
+      join(sandbox, "project", "skillrepo.json"),
+      JSON.stringify({
+        skillset: { version: 1, name: "checkout", use: "acme/backend-core" },
+      }),
+    );
+    await assert.rejects(
+      runUpdate(["--json", "--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === 6,
+    );
+    assert.equal(stdout.text(), "", "no partial JSON on the failure path");
+  });
+});

package/src/test/e2e/cli-commands.test.mjs

@@ -122,6 +122,69 @@ describe("CLI E2E — read commands", () => {
     assert.match(r.stdout, /up to date/);
   });
 
+  it("update warns about a foreign skill dir on stderr and exits 0 (#2361)", async () => {
+    const { writeFileSync } = await import("node:fs");
+    // Hand-authored dir the CLI never wrote — a governance violation,
+    // surfaced but never touched.
+    mkdirSync(join(tempDir, ".claude", "skills", "hand-rolled"), { recursive: true });
+    writeFileSync(
+      join(tempDir, ".claude", "skills", "hand-rolled", "SKILL.md"),
+      "---\nname: hand-rolled\n---\n",
+    );
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const r = await runCli([
+      "update",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    assert.match(r.stderr, /is not from your library/);
+    assert.match(r.stderr, /skillrepo push/);
+    assert.match(r.stderr, /\.claude\/skills\/hand-rolled\//);
+    // The foreign dir is surfaced, never destroyed.
+    assert.ok(existsSync(join(tempDir, ".claude", "skills", "hand-rolled", "SKILL.md")));
+    // The synced skill is managed — not warned about.
+    assert.ok(!r.stderr.includes("pdf-helper"));
+
+    // Warn-on-new: an identical second run repeats nothing.
+    const r2 = await runCli([
+      "update",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r2.status, 0, `stderr: ${r2.stderr}`);
+    assert.ok(
+      !r2.stderr.includes("hand-rolled"),
+      "unchanged finding must not re-warn on the next run",
+    );
+  });
+
+  it("update --json carries the unmanaged count (#2361)", async () => {
+    const { writeFileSync } = await import("node:fs");
+    mkdirSync(join(tempDir, ".claude", "skills", "rogue"), { recursive: true });
+    writeFileSync(
+      join(tempDir, ".claude", "skills", "rogue", "SKILL.md"),
+      "---\nname: rogue\n---\n",
+    );
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+    const r = await runCli([
+      "update", "--json",
+      "--key", VALID_KEY,
+      "--url", `http://127.0.0.1:${port}`,
+    ]);
+    assert.equal(r.status, 0, `stderr: ${r.stderr}`);
+    const json = JSON.parse(r.stdout);
+    assert.equal(json.unmanaged, 1);
+  });
+
   it("update writes a single skill and prints the summary", async () => {
     server.setLibraryResponse({
       skills: [makeSkill("alice", "pdf-helper")],

package/src/test/lib/errors.test.mjs

@@ -12,12 +12,14 @@ import {
   EXIT_DISK,
   EXIT_SCOPE,
   EXIT_VALIDATION,
+  EXIT_UNRESOLVABLE,
   CliError,
   networkError,
   authError,
   diskError,
   scopeError,
   validationError,
+  unresolvableError,
   isRetryable,
   computeBackoffDelay,
   withRetry,
@@ -357,3 +359,29 @@ describe("errors.mjs — withRetry", () => {
     );
   });
 });
+
+// ── EXIT_UNRESOLVABLE (#2362) ──────────────────────────────────────────
+
+describe("unresolvableError (#2362)", () => {
+  it("EXIT_UNRESOLVABLE is 6 and distinct from every prior code", () => {
+    assert.equal(EXIT_UNRESOLVABLE, 6);
+    const prior = [EXIT_OK, EXIT_NETWORK, EXIT_AUTH, EXIT_DISK, EXIT_SCOPE, EXIT_VALIDATION];
+    assert.ok(!prior.includes(EXIT_UNRESOLVABLE));
+  });
+
+  it("constructor carries the exit code, hint, and cause", () => {
+    const cause = new Error("inner");
+    const err = unresolvableError("declaration cannot be honored", {
+      hint: "fix or remove skillrepo.json",
+      cause,
+    });
+    assert.ok(err instanceof CliError);
+    assert.equal(err.exitCode, EXIT_UNRESOLVABLE);
+    assert.equal(err.hint, "fix or remove skillrepo.json");
+    assert.equal(err.cause, cause);
+  });
+
+  it("is never retryable — a declaration problem never succeeds on retry", () => {
+    assert.equal(isRetryable(unresolvableError("nope")), false);
+  });
+});

package/src/test/lib/file-write.test.mjs

@@ -956,7 +956,7 @@ describe("ensureFallbackGitignore — error surfacing", () => {
   });
 
   it("throws diskError when .gitignore cannot be READ (it is a directory → EISDIR)", () => {
-    // The read-error branch in ensureAgentsGitignore: readFileSafe
+    // The read-error branch in the gitignore-section core: readFileSafe
     // re-throws any non-ENOENT error. Making `.gitignore` a DIRECTORY
     // causes readFileSync to throw EISDIR, which surfaces as a typed
     // diskError with a "Cannot read" message before any write is