skillrepo 4.5.1 → 4.5.2

package/package.json

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

package/src/commands/add.mjs

@@ -196,11 +196,11 @@ export async function runAdd(argv, io = {}) {
     .join(", ")})`;
   if (wasNewlyAdded) {
     stdout.write(
-      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ Added ${formatIdentifier({ owner, name })} to your library (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   } else {
     stdout.write(
-      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} files) → ${where}\n\n`,
+      `\n  ✓ ${formatIdentifier({ owner, name })} was already in your library — refreshed (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
     );
   }
 }

package/src/commands/get.mjs

@@ -143,6 +143,6 @@ export async function runGet(argv, io = {}) {
     .map(describePlacementTarget)
     .join(", ")})`;
   stdout.write(
-    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} files) → ${where}\n\n`,
+    `\n  ✓ Fetched ${formatIdentifier({ owner, name })} (${skill.files.length} file${skill.files.length === 1 ? "" : "s"}) → ${where}\n\n`,
   );
 }

package/src/commands/list.mjs

@@ -243,9 +243,13 @@ function printTable(augmented, detected, out) {
       .join(", ");
     out.write(`\n  Detected: ${detectedLabel}\n`);
   } else {
-    out.write(
-      "\n  No agents detected in this project — drift cannot be reported.\n",
-    );
+    // Earlier copy said "drift cannot be reported" but the table
+    // below DOES report drift — every skill rolls up as MISSING
+    // because no placement exists to compare against. The simpler
+    // statement of fact is what users need; the footer ("No sync
+    // history…" / "library has changed…") tells them what to do
+    // next.
+    out.write("\n  No agents detected in this project.\n");
   }
 
   const sorted = augmented.slice().sort(sortByOwnerAndName);
@@ -337,12 +341,27 @@ function printFooter(augmented, libraryEtag, lastSync, out, useGlyphs) {
   }
 
   if (etagMatches && driftCount > 0) {
-    out.write(
-      `\n  ${warn} library in sync — but ${driftCount} skill${
-        driftCount === 1 ? "" : "s"
-      } show${driftCount === 1 ? "s" : ""} local drift.\n` +
-        "    Run `skillrepo update` to refresh.\n\n",
-    );
+    // Distinguish EDITED (running update loses user changes) from
+    // MISS/STALE (running update is non-destructive — fills gaps or
+    // pulls a newer version). The earlier copy said "Run `skillrepo
+    // update` to refresh" for every drift case, which silently
+    // destroyed user edits when EDITED rows were present. Now we
+    // warn explicitly when edits are at risk.
+    const editedCount = augmented.filter(
+      (s) => s.state === SKILL_STATE.EDITED,
+    ).length;
+    const driftPhrase = `${driftCount} skill${driftCount === 1 ? "" : "s"} show${driftCount === 1 ? "s" : ""}`;
+    if (editedCount > 0) {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift, including ${editedCount} with local edit${editedCount === 1 ? "" : "s"}.\n` +
+          "    Run `skillrepo update` to refresh — this will OVERWRITE local edits.\n\n",
+      );
+    } else {
+      out.write(
+        `\n  ${warn} library in sync — but ${driftPhrase} local drift.\n` +
+          "    Run `skillrepo update` to refresh.\n\n",
+      );
+    }
     return;
   }
 

package/src/lib/sync.mjs

@@ -85,6 +85,7 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 
 import { getLibrary } from "./http.mjs";
 import {
@@ -110,6 +111,103 @@ import { computeSkillShas } from "./crypto-shas.mjs";
  */
 export const LAST_SYNC_SCHEMA_VERSION = 2;
 
+/**
+ * Check whether every skill in the `.last-sync` baseline already exists
+ * under every placement target the current sync would write to. Returns
+ * true when the 304 short-circuit is safe (skipping writes won't leave
+ * any placement empty), false when at least one (skill, target) pair
+ * is missing on disk.
+ *
+ * This is the load-bearing guard for the ETag fast path. The contract:
+ * "library content unchanged AND every expected placement already has
+ * its content" — the second clause is what this function enforces.
+ *
+ * See the call site in runSync for the full motivation (upgrade-path,
+ * --global ↔ project swap, and cwd-switch scenarios all funnel through
+ * this gate).
+ *
+ * @param {Record<string, {skillMdSha256: string, filesSha256: string, version: string}> | null | undefined} skillsMap
+ *   The `.skills` map from `.last-sync` — keyed by `"<owner>/<name>"`.
+ * @param {string[] | undefined} vendors
+ *   The current sync's vendor list (output of `effectiveVendors`).
+ * @param {boolean | undefined} global
+ *   Whether the current sync is `--global` mode.
+ * @returns {boolean}
+ */
+export function placementsAreComplete(skillsMap, vendors, global) {
+  // Empty baseline: we cannot trust the ETag short-circuit. Two
+  // legitimate code paths land here:
+  //   1. Genuine fresh install — no `.last-sync` file at all; this
+  //      function isn't called because runSync's caller checks
+  //      `lastSync?.etag` before invoking. So we never see this
+  //      branch in the fresh-install case.
+  //   2. v1 → v2 migration — `readLastSync` synthesizes an empty
+  //      `skills` map for a v1 file (which had no per-skill SHA
+  //      cache). The etag IS present but the baseline is empty;
+  //      a 304 would tell us "library unchanged" but we'd still
+  //      have no per-skill cache, so `list` would render every
+  //      skill as MISS. Forcing a re-fetch here populates the
+  //      cache and surfaces the actual library state.
+  // The conservative direction is "force re-fetch" — wire cost
+  // happens once per upgrade, not every time.
+  if (
+    !skillsMap ||
+    typeof skillsMap !== "object" ||
+    Object.keys(skillsMap).length === 0
+  ) {
+    return false;
+  }
+
+  // No vendors: this is the `--agent none` case or a degenerate config.
+  // requireVendorTargets will catch this downstream; from here, treat
+  // as "no placements to verify" → trivially complete.
+  if (!Array.isArray(vendors) || vendors.length === 0) {
+    return true;
+  }
+
+  let targets;
+  try {
+    targets = placementTargetsFor({ vendors, global: global === true });
+  } catch {
+    // placementTargetsFor throws on an invalid vendor + scope combo
+    // (e.g., `--global` with a vendor that has no `globalTarget`).
+    // The downstream runSync write loop will surface the same error
+    // with the correct typed exception; conservatively treat as
+    // "placement incomplete" so we drop the ETag and force the
+    // full-fetch path (which is what we'd want under any error).
+    return false;
+  }
+
+  for (const key of Object.keys(skillsMap)) {
+    // Skill keys are `"<owner>/<name>"`. We only need the name half
+    // because placement directories are keyed by skill name alone.
+    const slashAt = key.indexOf("/");
+    if (slashAt < 0) continue; // malformed entry — skip rather than crash
+    const skillName = key.slice(slashAt + 1);
+    if (!skillName) continue;
+
+    for (const target of targets) {
+      const dir = resolvePlacementDir(target, skillName);
+      // Probe `SKILL.md` rather than the bare directory. An empty or
+      // partial directory left behind by a hostile filesystem
+      // condition (manual mkdir, third-party tool, interrupted write
+      // before the atomic rename — rare but possible) would otherwise
+      // satisfy `existsSync(dir)` and let the 304 fire, leaving the
+      // user with a placement that contains no usable skill content.
+      // SKILL.md is the spec-required entry point; its presence is
+      // the load-bearing invariant the placement-presence check is
+      // really asserting.
+      if (!existsSync(join(dir, "SKILL.md"))) {
+        // ONE missing placement is enough — full re-fetch will re-write
+        // EVERY skill to EVERY target, restoring the invariant in one
+        // round.
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
 /**
  * Read the persisted last-sync state from ~/.claude/skillrepo/.last-sync.
  * Returns null if the file doesn't exist, is malformed, or has a
@@ -370,8 +468,61 @@ export async function runSync(options) {
 
   // Step 3: fetch with conditional headers
   const opts = {};
-  if (lastSync?.etag) opts.ifNoneMatch = lastSync.etag;
-  if (lastSync?.syncedAt) opts.since = lastSync.syncedAt;
+  // The ETag short-circuit is only safe when EVERY skill in
+  // `.last-sync`'s baseline is present in EVERY placement directory
+  // the current sync would write to. The 304 means "library content
+  // unchanged" — but the local placement set can change between
+  // syncs even when content does not:
+  //
+  //   - User upgrades from 4.5.0 (single-vendor default) to 4.5.1+
+  //     (all-detected default) — new vendors detected, their
+  //     placement dirs are empty.
+  //   - User runs `update --global` once, then `update` (no flag)
+  //     later — same vendor, but the resolved placement dir is
+  //     project-scoped now instead of global.
+  //   - User runs `update` in project A, then in project B — same
+  //     vendor and scope, but `<cwd>/.claude/skills/` resolves to a
+  //     different directory in B than in A.
+  //
+  // Without this check, any of those cases produces 304 → no writes
+  // → all-MISS output in `list`. The fix is a placement-presence
+  // check: for every (skill, target) pair the current sync would
+  // touch, the skill's directory MUST already exist under the
+  // target's root. If ANY is missing, drop `If-None-Match` so the
+  // server returns the full library and we populate the empty
+  // placement.
+  //
+  // Performance: N targets × M skills `existsSync` calls. For a 14-
+  // skill library with 2 targets, that's 28 stat calls — well under
+  // a millisecond. The conditional-fetch wire savings on a clean
+  // repeat sync still applies; this is the safety guard above it.
+  // BOTH the ETag short-circuit AND the `since` delta-query optimization
+  // depend on the same trust invariant: "the local placement set has
+  // every skill we expect." If a placement is missing, dropping ONLY
+  // `If-None-Match` is insufficient — the server filters `result.skills`
+  // by `updatedAt > since`, so a server response that we trigger by
+  // dropping the ETag will STILL omit any skill whose content hasn't
+  // changed on the server since the last sync. The missing placement
+  // would never be repopulated, producing a permanent ETag-miss loop
+  // that the user can only escape by `rm ~/.claude/skillrepo/.last-sync`.
+  //
+  // Verified against the production server at
+  // src/lib/queries/library.ts (`gt(skills.updatedAt, since)`): `since`
+  // alone is enough to filter unchanged skills out of the response.
+  //
+  // Fix: gate BOTH headers on the same `placementsAreComplete` check.
+  // When placements are incomplete, drop both — server returns the
+  // full library, runSync writes every skill to every detected
+  // vendor's placement, recovery is complete in one round.
+  const placementsComplete =
+    lastSync?.etag &&
+    placementsAreComplete(lastSync.skills, vendors, global);
+  if (placementsComplete) {
+    opts.ifNoneMatch = lastSync.etag;
+  }
+  if (lastSync?.syncedAt && placementsComplete) {
+    opts.since = lastSync.syncedAt;
+  }
 
   // Track whether this is a full or delta sync BEFORE the network
   // call, for the returned summary's `fullSync` field. A "full" sync
@@ -520,7 +671,13 @@ export async function runSync(options) {
     }
   }
 
-  // Step 7: persist new ETag + skills map (only if the response was complete)
+  // Step 7: persist new ETag + skills map (only if the response was
+  // complete). The placement-presence check in `placementsAreComplete`
+  // (called above before the conditional request) handles the safety
+  // gate for the ETag short-circuit — no need to persist a separate
+  // vendor-set field; the on-disk placements themselves are the
+  // source of truth for "did the local placement set change in a way
+  // that would invalidate 304?"
   if (!anyIncomplete && result.etag) {
     try {
       writeLastSync({

package/src/test/e2e/mock-server.mjs

@@ -80,6 +80,18 @@ export function createMockServer(initialPayload, options = {}) {
   /** @type {{ status: number, body: any } | null} */
   let forcedError = null;
 
+  // Library-request inspection. Tests use these to distinguish a true
+  // 304 wire exchange (`If-None-Match` sent, server replied 304) from
+  // a request that produced "up to date" output via some other path.
+  // PR #1575's placement-presence fix made this distinction
+  // load-bearing — see the assertion at the call sites in
+  // update-list-contract.integration.test.mjs.
+  /** @type {string | null} */
+  let lastLibraryIfNoneMatch = null;
+  /** @type {string | null} */
+  let lastLibrarySince = null;
+  let libraryRequestCount = 0;
+
   // PR3a mutable slots for POST/DELETE library routes
   //
   // Each entry is `{ status: number, body: any }` describing the
@@ -486,18 +498,57 @@ export function createMockServer(initialPayload, options = {}) {
         return;
       }
 
-      // ETag short-circuit
+      // ETag short-circuit. Capture the inbound If-None-Match and
+      // `since` into inspectable slots BEFORE deciding 304-vs-200 so
+      // tests can assert on what the client actually sent — not just
+      // whether the response was 304. PR #1575's placement-presence
+      // fix makes the wire-level distinction load-bearing.
       const ifNoneMatch = req.headers["if-none-match"];
+      const sinceParam = url.searchParams.get("since");
+      lastLibraryIfNoneMatch = ifNoneMatch ?? null;
+      lastLibrarySince = sinceParam ?? null;
+      libraryRequestCount++;
       if (libraryEtag && ifNoneMatch === libraryEtag) {
         res.writeHead(304, { ETag: libraryEtag });
         res.end();
         return;
       }
 
+      // Mirror the production server's `since` filter — only return
+      // skills updated AFTER the `since` timestamp. Pre-PR #1575 the
+      // mock returned every skill regardless of `since`, which hid a
+      // real production bug: dropping the ETag without ALSO dropping
+      // `since` made the server respond with an empty delta, leaving
+      // newly-detected vendor placements empty forever. Mirroring the
+      // filter here means any future regression of that class fails
+      // at test time. See src/lib/queries/library.ts in the server
+      // for the production behavior (`gt(skills.updatedAt, since)`).
+      let respondedSkills = libraryResponse.skills ?? [];
+      if (sinceParam && Array.isArray(respondedSkills)) {
+        const sinceDate = new Date(sinceParam);
+        if (!Number.isNaN(sinceDate.getTime())) {
+          respondedSkills = respondedSkills.filter((s) => {
+            // updatedAt is a string ISO timestamp in the fixture skills.
+            // Missing/invalid → treat as "older than since" → exclude
+            // (matches the production semantic of "not modified in
+            // the window").
+            if (typeof s.updatedAt !== "string") return false;
+            const updated = new Date(s.updatedAt);
+            if (Number.isNaN(updated.getTime())) return false;
+            return updated.getTime() > sinceDate.getTime();
+          });
+        }
+      }
+
+      const filteredResponse = {
+        ...libraryResponse,
+        skills: respondedSkills,
+      };
+
       const headers = { "Content-Type": "application/json" };
       if (libraryEtag) headers.ETag = libraryEtag;
       res.writeHead(200, headers);
-      res.end(JSON.stringify(libraryResponse));
+      res.end(JSON.stringify(filteredResponse));
       return;
     }
 
@@ -586,6 +637,45 @@ export function createMockServer(initialPayload, options = {}) {
       libraryEtag = etag;
     },
 
+    /**
+     * Inspect the inbound `If-None-Match` header from the LAST request
+     * to GET /api/v1/library. Returns the literal header string, or
+     * `null` if the request didn't send one (full-fetch path). Used
+     * by tests asserting that the placement-presence check correctly
+     * dropped or sent the ETag header. See PR #1575's coverage gap
+     * 2 — without this accessor, the "304 fires" tests could pass on
+     * an implementation that broke the wire-level optimization while
+     * preserving the user-facing "up to date" output.
+     */
+    getLastLibraryIfNoneMatch() {
+      return lastLibraryIfNoneMatch;
+    },
+
+    /** Count of GET /api/v1/library requests since server start or reset. */
+    getLibraryRequestCount() {
+      return libraryRequestCount;
+    },
+
+    /**
+     * Inspect the inbound `?since=` query param from the LAST request
+     * to GET /api/v1/library. Returns the literal string or `null` if
+     * not present. The placement-presence fix must drop BOTH the
+     * If-None-Match header AND the `since` query param when placements
+     * are incomplete — otherwise the server returns an empty delta
+     * and missing placements stay empty. Tests use this to assert the
+     * fix at the wire level.
+     */
+    getLastLibrarySince() {
+      return lastLibrarySince;
+    },
+
+    /** Reset the inspection slots — useful between phases of a multi-step test. */
+    resetLibraryInspection() {
+      lastLibraryIfNoneMatch = null;
+      lastLibrarySince = null;
+      libraryRequestCount = 0;
+    },
+
     /** Register a single-skill response keyed by `owner/name`. */
     setSkillResponse(owner, name, skill) {
       skillResponses.set(`${owner}/${name}`, skill);

package/src/test/integration/update-list-contract.integration.test.mjs

@@ -80,7 +80,7 @@ const VALID_KEY = "sk_live_test";
  * helper the unit tests use; replicated here so changes in either
  * place don't silently break the other.
  */
-function makeSkill(owner, name, version = "1.0.0") {
+function makeSkill(owner, name, version = "1.0.0", updatedAt) {
   const content = `---\nname: ${name}\ndescription: ${name} description\n---\n\nbody\n`;
   return {
     owner,
@@ -99,7 +99,14 @@ function makeSkill(owner, name, version = "1.0.0") {
         contentType: "text/markdown",
       },
     ],
-    updatedAt: "2025-01-01T12:00:00Z",
+    // Default to "now" so the mock server's `since` filter (mirrors
+    // production `gt(skills.updatedAt, since)`) treats fresh fixtures
+    // as in-window. Tests that need to simulate "skill unchanged
+    // since last sync" pass an older string explicitly. Pre-PR #1575
+    // mock-server-tightening hardcoded "2025-01-01" which made every
+    // skill look stale once `since` was applied — that masked the
+    // real production behavior.
+    updatedAt: updatedAt ?? new Date().toISOString(),
   };
 }
 
@@ -434,13 +441,18 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
     assert.match(entry.filesSha256, /^[a-f0-9]{64}$/, "filesSha256 must be a hex SHA-256");
   });
 
-  it("v1 state with NO content changes (304) preserves the etag and lets list see the upgrade transparently", async () => {
-    // Edge case: user upgrades, runs update, server returns 304 (no
-    // changes). The v1 etag was carried into the in-memory v2 shape
-    // so the 304 fires. No writeLastSync happens on 304 — so the
-    // on-disk file STAYS v1 until something actually changes. This
-    // is the documented behavior; the test makes it explicit so a
-    // future "always rewrite on 304" change would surface here.
+  it("v1 state with NO content changes → first sync after upgrade does a full re-fetch (recovery)", async () => {
+    // The recovery path for users upgrading from v1 `.last-sync`
+    // (4.4.x and earlier) or any state where the per-skill SHA map
+    // is empty. `placementsAreComplete` returns false when the
+    // baseline map is empty — that's the "we have an etag but no
+    // per-skill cache, so we can't trust the 304" signal. runSync
+    // drops `If-None-Match`, fetches the full library, and writes
+    // both the skill bytes and the per-skill SHA cache. The "library
+    // synced" message replaces "up to date" exactly once per
+    // upgrade; subsequent syncs (now with a populated skills map
+    // AND placement directories on disk) return to the 304 fast
+    // path.
     const v1Path = globalLastSyncPath();
     mkdirSync(join(v1Path, ".."), { recursive: true });
     writeFileSync(
@@ -460,27 +472,54 @@ describe("v1 → v2 .last-sync migration round-trip", () => {
       syncedAt: "2026-05-19T00:00:00Z",
     });
 
-    // Force a 304 — the mock server's `setEtag('"unchanged"')`
-    // combined with the v1 etag triggers the conditional short-circuit.
+    // First sync after upgrade: empty skills map → placementsAreComplete
+    // returns false → full re-fetch. User sees the "synced" message,
+    // not "up to date" — recovery is visible.
+    server.resetLibraryInspection();
     await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
-    assert.match(stdout.text(), /up to date/, "304 should produce the up-to-date message");
+    const firstOut = stdout.text();
+    // Negative assertion: the misleading "up to date" message must
+    // not appear during the recovery sync.
+    assert.ok(
+      !/up to date/.test(firstOut),
+      "first sync after upgrade must NOT 304 — empty skills map forces full re-fetch",
+    );
+    // Positive assertion: the recovery sync must report at least
+    // one write. Without this, a future regression where the command
+    // crashed before printing anything would also pass the negative
+    // assertion above. See QA Gap 4.
+    assert.match(
+      firstOut,
+      /Library sync complete|added|updated/,
+      "first sync after upgrade must positively report a sync, not silently no-op",
+    );
+    // Wire-level: ETag was dropped — placementsAreComplete returned
+    // false for the empty baseline. This is the load-bearing
+    // mechanism, not just a side-effect of output.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "v1 migration must drop If-None-Match (placementsAreComplete returns false for empty map)",
+    );
 
-    // The on-disk file stayed v1 because runSync's 304 branch
-    // doesn't write. readLastSync's in-memory migration is what kept
-    // the conditional request behaving correctly.
-    const afterRaw = readFileSync(v1Path, "utf-8");
-    const after = JSON.parse(afterRaw);
-    assert.equal(after.schemaVersion, 1, "304 should leave the v1 file untouched on disk");
-
-    // But — the migrated in-memory shape is what `list` consumes.
-    // Calling readLastSync directly should return the v2 shape
-    // (synthesized from v1 + empty skills map). The integration
-    // contract is: any reader on the new CLI sees a v2 shape, even
-    // if the file on disk is still v1.
-    const migrated = readLastSync();
-    assert.equal(migrated.schemaVersion, 2);
-    assert.equal(migrated.etag, '"unchanged"');
-    assert.deepEqual(migrated.skills, {});
+    // After the recovery sync, the on-disk file is v2 with the
+    // skills map populated. The skill is on disk in the claudeProject
+    // placement — the user-visible recovery.
+    const after = readLastSync();
+    assert.equal(after.schemaVersion, 2);
+    assert.ok(after.skills["alice/unmigrated"]);
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "unmigrated")));
+
+    // Second sync with the SAME vendor set: now the ETag short-circuit
+    // is safe and 304 fires (this proves we didn't accidentally make
+    // every sync do a full re-fetch — the fix is targeted).
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "second sync (vendor set now in .last-sync) should 304 normally",
+    );
   });
 });
 
@@ -1016,3 +1055,511 @@ describe("additional coverage from production-readiness audit", () => {
     }
   });
 });
+
+// ───────────────────────────────────────────────────────────────────────
+// Upgrade-path scenarios — the bugs the fresh-sandbox tests cannot see
+// ───────────────────────────────────────────────────────────────────────
+//
+// The 4.5.0 → 4.5.1 production-readiness audit missed a real user-facing
+// bug because every test in this file (and every reviewer-spawned
+// verification) ran in a freshly-created sandbox. The actual user
+// upgrade path is different: pre-existing `.last-sync` written by the
+// old CLI, then run the new CLI, expect new behavior to take effect.
+//
+// The specific bug: `runSync`'s ETag short-circuit fires when the
+// server hasn't changed library content since the last sync — but if
+// the local detected-vendor set has EXPANDED since that sync (the
+// classic 4.5.0 → 4.5.1 transition: claudeCode-only → all-detected),
+// the 304 means the new vendors NEVER receive their skills. User sees
+// "Library is up to date" followed by `list` reporting every skill as
+// MISS for the newly-detected vendors.
+//
+// These tests reproduce that specific scenario by:
+//   1. Seeding `.last-sync` with a state that mimics the old CLI's
+//      output (single-vendor sync, etag X).
+//   2. Setting the detection signals for additional vendors.
+//   3. Running `update` against a server that returns 304 for etag X.
+//   4. Asserting the new vendors' placements were populated anyway.
+
+describe("upgrade path: vendor set expands between syncs (regression for the bug 4.5.1 missed)", () => {
+  beforeEach(setup);
+  afterEach(teardown);
+
+  it("new vendor detected after prior sync → ETag is dropped and writes fire for the new vendor", async () => {
+    // STEP 1: simulate the 4.5.0 user's state — only claudeCode
+    // detected, sync completed, `.last-sync` has skill SHAs and an
+    // etag.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    const skill = makeSkill("alice", "shared", "1.0.0");
+    server.setLibraryResponse({
+      skills: [skill],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Sanity: only claudeProject got the write at this point.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "shared")),
+      "first sync wrote to claudeProject",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("agentsProject", "shared")),
+      false,
+      "first sync did NOT write to agentsProject (cursor not detected yet)",
+    );
+
+    // STEP 2: simulate the user installing Cursor — env signal fires
+    // on the NEXT `update` invocation. The library content has not
+    // changed on the server, so the server will return 304.
+    process.env.CURSOR_AGENT = "1";
+
+    // Mock server keeps the same etag → If-None-Match match → 304.
+    // No need to change the library response: the 304 branch in
+    // runSync skips reading the body anyway.
+
+    // STEP 3: run update. Pre-fix: short-circuits on 304, no writes
+    // to cursor, user sees "Library is up to date" but cursor's
+    // placement remains empty.
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // STEP 4: assert. THIS IS THE LOAD-BEARING CHECK.
+    // The newly-detected cursor vendor's placement MUST exist after
+    // the second `update`, even though the server responded 304.
+    // Pre-fix this assertion fails.
+    assert.ok(
+      existsSync(resolvePlacementDir("agentsProject", "shared")),
+      "agentsProject placement MUST exist after a 304 sync when cursor was newly detected — " +
+        "the ETag short-circuit must not prevent writes to vendors absent from the prior sync",
+    );
+    // Wire-level proof: the client did NOT send If-None-Match — the
+    // placement-presence check correctly forced a full re-fetch.
+    // Without this assertion, a regression that still sent the ETag
+    // but happened to re-write to cursor via some unrelated code
+    // path would pass the disk check above silently. See QA Gap 2.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "client must NOT have sent If-None-Match — placement-presence check should have dropped it",
+    );
+
+    // Confirm `list` agrees: every detected vendor reports current.
+    stdout = createCaptureStream();
+    await runList(
+      ["--key", VALID_KEY, "--url", serverUrl, "--json"],
+      { stdout },
+    );
+    const [item] = JSON.parse(stdout.text());
+    assert.equal(
+      item.state,
+      "current",
+      "list must show current after the upgrade-path sync — not MISS",
+    );
+    assert.equal(item.placements.length, 2);
+    for (const p of item.placements) {
+      assert.equal(p.state, "current");
+    }
+  });
+
+  it("vendor set unchanged across syncs → 304 short-circuit still fires (no wasted full re-fetch)", async () => {
+    // Defense-in-depth: the fix must NOT invalidate the 304 unless
+    // the placement set actually changed. A user who runs `update`
+    // twice in a row with the same vendors should still benefit from
+    // the 304 fast path. The assertion is BOTH the user-visible "up
+    // to date" output AND the wire-level `If-None-Match` header —
+    // otherwise a future regression that broke the ETag header but
+    // happened to produce the same output (e.g., full re-fetch with
+    // zero deltas) would pass this test silently. See QA reviewer
+    // Gap 2.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "unchanged", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Second run with the SAME vendor set — should 304 and produce
+    // the "up to date" message (no writes needed).
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "same vendor set + same library = 304 fast path still fires",
+    );
+    // Wire-level proof: the client actually sent If-None-Match.
+    // Without this, a regression that broke the conditional request
+    // but produced the same output would slip past output-only
+    // assertions.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      '"library-v1"',
+      "second sync MUST have sent If-None-Match: <prior-etag> — the ETag fast path is load-bearing",
+    );
+  });
+
+  it("--global sync followed by project sync → project placement gets populated", async () => {
+    // Edge case the vendor-set tracking alone misses: same vendors,
+    // different scope. The user runs `update --global` (writes to
+    // ~/.claude/skills/), then runs `update` with no flag (writes to
+    // <cwd>/.claude/skills/). Same vendor key (claudeCode) but
+    // entirely different placement directory. A naive syncedVendors
+    // check would say "set unchanged" → 304 → no writes → project
+    // placement empty → list shows MISS.
+    //
+    // The proper contract: invalidate the ETag whenever the resolved
+    // placement directories for the current sync don't ALL contain
+    // the skills they should. That covers vendor-set expansion AND
+    // scope changes AND cwd switches.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "scope-test", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync: --global → ~/.claude/skills/ (claudeGlobal target).
+    await runUpdate(
+      ["--key", VALID_KEY, "--url", serverUrl, "--global"],
+      { stdout },
+    );
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeGlobal", "scope-test")),
+      "first sync wrote to claudeGlobal",
+    );
+    assert.equal(
+      existsSync(resolvePlacementDir("claudeProject", "scope-test")),
+      false,
+      "first sync did NOT write to claudeProject (no --global flag inverted)",
+    );
+
+    // Second sync: no --global → <cwd>/.claude/skills/ (claudeProject).
+    // Same vendor (claudeCode), same library content (304 from server),
+    // but the destination directory is completely different. Without
+    // the fix, the 304 short-circuit fires and claudeProject stays
+    // empty.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // THE LOAD-BEARING CHECK: claudeProject must exist after the
+    // project-scope sync, even though the server 304'd.
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "scope-test")),
+      "claudeProject placement MUST exist after a 304 sync when the prior sync " +
+        "was --global — the ETag short-circuit must not skip writes when the " +
+        "resolved placement directory is empty",
+    );
+  });
+
+  it("cwd switch between syncs → second project's placement gets populated", async () => {
+    // Same bug class as the --global swap. User runs `update` in
+    // project A, then runs `update` in project B. Both projects use
+    // the same `.last-sync` (lives in HOME, not project) but the
+    // placement directories are cwd-dependent. Without the fix, the
+    // second project sees a 304 and never gets its placements.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "cwd-test", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync in project A.
+    const projectA = process.cwd();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "cwd-test")),
+      "first sync populated project A's placement",
+    );
+
+    // Switch to project B (a separate temp directory inside the same
+    // sandbox so the home-scoped `.last-sync` is shared).
+    const projectB = join(sandbox, "project-b");
+    mkdirSync(projectB, { recursive: true });
+    process.chdir(projectB);
+
+    try {
+      // Same library content, same vendor — server still 304s. Without
+      // the fix, no writes to project B.
+      stdout = createCaptureStream();
+      await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+      assert.ok(
+        existsSync(resolvePlacementDir("claudeProject", "cwd-test")),
+        "project B's claudeProject placement MUST exist after sync — " +
+          "ETag short-circuit must not skip writes when the cwd changed",
+      );
+    } finally {
+      process.chdir(projectA);
+    }
+  });
+
+  it("partial baseline recovery: delete 1 of 5 skills' placements → ETag dropped, all re-fetched (QA Gap 1)", async () => {
+    // Most probable failure mode in normal use: user has many
+    // skills, manually deletes one (or a cleanup script trims a
+    // skill they removed), then runs `update`. The library is
+    // unchanged on the server (304), but the placement-presence
+    // check sees the missing dir and forces a full re-fetch. This
+    // restores every skill in one round. The wire-level check
+    // proves the ETag was DROPPED, not silently sent and ignored.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "skill-1", "1.0.0"),
+        makeSkill("alice", "skill-2", "1.0.0"),
+        makeSkill("alice", "skill-3", "1.0.0"),
+        makeSkill("alice", "skill-4", "1.0.0"),
+        makeSkill("alice", "skill-5", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Sync — all 5 land.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    for (const n of ["skill-1", "skill-2", "skill-3", "skill-4", "skill-5"]) {
+      assert.ok(existsSync(resolvePlacementDir("claudeProject", n)));
+    }
+
+    // User deletes ONE skill — `skill-3`.
+    rmSync(resolvePlacementDir("claudeProject", "skill-3"), {
+      recursive: true,
+      force: true,
+    });
+
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // `skill-3` is restored. The other 4 are untouched (idempotent
+    // write — same content, same SHA).
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "skill-3")),
+      "deleted skill must be restored after self-healing sync",
+    );
+    for (const n of ["skill-1", "skill-2", "skill-4", "skill-5"]) {
+      assert.ok(
+        existsSync(resolvePlacementDir("claudeProject", n)),
+        `${n} must remain present (no collateral damage)`,
+      );
+    }
+    // Wire-level: ETag was dropped — placement-presence check fired.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "ETag MUST have been dropped — placement-presence check found the missing skill-3 dir",
+    );
+  });
+
+  it("multi-vendor + manual delete of ONE vendor's placement → next update self-heals", async () => {
+    // Real-world scenario flagged by reviewer: a user with two
+    // vendors syncs successfully, then manually deletes one
+    // vendor's placement directory (rm -rf the cohort dir, or a
+    // hostile cleanup script touched it). The `.last-sync` baseline
+    // and the OTHER vendor's placement are intact, so the server
+    // would 304. Without the placement-presence check, the deleted
+    // vendor's placement would stay empty forever — list would show
+    // MISS for every skill at that vendor.
+    //
+    // The placement-presence check sees the missing claudeProject
+    // SKILL.md and forces a re-fetch, restoring both vendors'
+    // placements in one round. This is the "self-healing" property
+    // of the fix.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [
+        makeSkill("alice", "a", "1.0.0"),
+        makeSkill("alice", "b", "1.0.0"),
+      ],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Initial sync — both vendors get both skills.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("claudeProject", "b")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "b")));
+
+    // User manually nukes the entire claudeProject cohort. cursor's
+    // placement at .agents/skills/ remains.
+    rmSync(resolvePlacementDir("claudeProject", "a"), {
+      recursive: true,
+      force: true,
+    });
+    rmSync(resolvePlacementDir("claudeProject", "b"), {
+      recursive: true,
+      force: true,
+    });
+
+    // Next update — server still 304s (same etag) — but the
+    // placement-presence check fires on missing claudeProject
+    // SKILL.md and forces full re-fetch.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "a")),
+      "claudeProject `a` must be restored after self-healing sync",
+    );
+    assert.ok(
+      existsSync(resolvePlacementDir("claudeProject", "b")),
+      "claudeProject `b` must be restored after self-healing sync",
+    );
+    // cursor's placements were never touched.
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "a")));
+    assert.ok(existsSync(resolvePlacementDir("agentsProject", "b")));
+  });
+
+  it("forced re-fetch drops BOTH If-None-Match AND ?since= (BLOCKER from Round 2 code-review)", async () => {
+    // The bug that almost shipped: PR #1575's first iteration dropped
+    // `If-None-Match` when placements were incomplete but kept `since`
+    // unconditionally. Production server filters by
+    // `gt(skills.updatedAt, since)`, so a forced re-fetch would
+    // return an empty delta for any skill not modified within the
+    // window — leaving the newly-discovered missing placement empty
+    // forever. Permanent ETag-miss loop.
+    //
+    // This test makes both wire-level conditions explicit. The
+    // mock server now mirrors production's `since` filter (see
+    // mock-server.mjs change in this commit), so a regression that
+    // re-introduces the bug would fail the FULL-LIBRARY assertion
+    // even before the wire-level check.
+    process.env.CLAUDECODE = "1";
+
+    // Use an OLD updatedAt so the skill would be filtered out by
+    // `since` if the bug regressed. The default "now" timestamp
+    // would mask the issue.
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "stale-fixture", "1.0.0", "2025-01-01T00:00:00Z")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // First sync: writes the skill to claudeProject.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const skillDir = resolvePlacementDir("claudeProject", "stale-fixture");
+    assert.ok(existsSync(join(skillDir, "SKILL.md")));
+
+    // Force the placement-incomplete path: delete the SKILL.md
+    // (placementsAreComplete will return false on next sync).
+    rmSync(skillDir, { recursive: true, force: true });
+
+    // Run update. Pre-fix: ETag dropped, since=2026-05-01 sent,
+    // server filters by `gt(updatedAt='2025-01-01', since='2026-05-01')`,
+    // returns empty skills array, runSync writes nothing, placement
+    // stays empty. Post-fix: BOTH headers dropped, server returns
+    // the full library, runSync re-writes everything.
+    server.resetLibraryInspection();
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // Outcome assertion: the skill is back on disk.
+    assert.ok(
+      existsSync(join(skillDir, "SKILL.md")),
+      "stale-fixture must be restored — full re-fetch must return it even though updatedAt < syncedAt",
+    );
+
+    // Wire-level assertions: BOTH headers dropped on the forced
+    // re-fetch path. If either is sent, the bug has regressed.
+    assert.equal(
+      server.getLastLibraryIfNoneMatch(),
+      null,
+      "If-None-Match MUST be dropped when placements are incomplete",
+    );
+    assert.equal(
+      server.getLastLibrarySince(),
+      null,
+      "?since= MUST also be dropped — otherwise server filters out unchanged skills " +
+        "and the missing placement stays empty (the BLOCKER from Round 2 code-review)",
+    );
+  });
+
+  it("placement dir exists but SKILL.md is missing (partial placement) → next update self-heals", async () => {
+    // Reviewer-flagged HIGH: `existsSync(dir)` alone would satisfy
+    // the placement-presence check even for an empty/partial
+    // directory. The fix probes for SKILL.md specifically. This
+    // test locks in that behavior: a placement directory that
+    // exists but lacks its SKILL.md is treated as MISSING and
+    // forces a re-fetch.
+    process.env.CLAUDECODE = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "partial", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+
+    // Initial sync writes SKILL.md.
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const dir = resolvePlacementDir("claudeProject", "partial");
+    const skillMd = join(dir, "SKILL.md");
+    assert.ok(existsSync(skillMd));
+
+    // User (or hostile tool) deletes just the SKILL.md, leaving the
+    // directory.
+    rmSync(skillMd);
+    assert.ok(existsSync(dir), "dir still exists");
+    assert.equal(existsSync(skillMd), false, "but SKILL.md is gone");
+
+    // Next update — placement-presence check sees no SKILL.md and
+    // forces re-fetch.
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.ok(
+      existsSync(skillMd),
+      "SKILL.md must be restored — empty dirs must not satisfy the placement check",
+    );
+  });
+
+  it("vendor REMOVED from detected set → next update still 304s (no over-eager full re-fetch)", async () => {
+    // Edge case: user uninstalls a tool between syncs. The detected
+    // vendor set shrinks. The library content hasn't changed.
+    // Question: should the next update do a full re-fetch?
+    //
+    // Answer (per the fix's design): no. We only invalidate the ETag
+    // when the vendor set EXPANDED (added vendors need writes). A
+    // shrunk set has no new writes to do — the remaining vendors
+    // already have what they need. The orphaned placements (from
+    // the removed vendor) are left in place; cleaning them up is a
+    // separate concern.
+    //
+    // Pre-fix: same behavior (304 fires regardless of vendor change).
+    // Post-fix: explicit policy — only invalidate on expansion.
+    process.env.CLAUDECODE = "1";
+    process.env.CURSOR_AGENT = "1";
+    server.setEtag('"library-v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "shrinkable", "1.0.0")],
+      removals: [],
+      syncedAt: "2026-05-01T00:00:00Z",
+    });
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    // "Uninstall" cursor — drop the env signal.
+    delete process.env.CURSOR_AGENT;
+
+    stdout = createCaptureStream();
+    await runUpdate(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    assert.match(
+      stdout.text(),
+      /up to date/,
+      "shrinking the vendor set should not force a wasteful re-fetch",
+    );
+  });
+});

package/src/test/lib/sync.test.mjs

@@ -38,6 +38,7 @@ import {
   runSync,
   readLastSync,
   writeLastSync,
+  placementsAreComplete,
   LAST_SYNC_SCHEMA_VERSION,
 } from "../../lib/sync.mjs";
 import { resolvePlacementDir } from "../../lib/file-write.mjs";
@@ -780,6 +781,48 @@ describe("runSync — ETag round-trip", () => {
     const after = readFileSync(join(dir, "SKILL.md"), "utf-8");
     assert.equal(before, after);
   });
+
+  it("forced re-fetch (placementsAreComplete=false) sets fullSync=false (prior state existed)", async () => {
+    // Locks in the semantic contract from QA Round 2 Gap 5: a forced
+    // full re-fetch (placementsAreComplete returns false because a
+    // placement was missing) does NOT bump fullSync to true. fullSync
+    // is determined by whether prior `syncedAt` existed, not by
+    // whether the server returned a delta or full payload. The
+    // distinction matters to init.mjs which interprets the
+    // `fullSync` × `counters-all-zero` combination — for an `init`
+    // that hits a placement-incomplete state, counters won't be all
+    // zero (the missing skill produces added>=1), so the consumer
+    // distinction is preserved. This test pins that behavior.
+    server.setEtag('"v1"');
+    server.setLibraryResponse({
+      skills: [makeSkill("forced")],
+      removals: [],
+      syncedAt: "2025-01-01T00:00:00Z",
+    });
+    await runSync({ serverUrl, apiKey: VALID_KEY, vendors: ["claudeCode"] });
+
+    // Delete the placement on disk — forces re-fetch on next runSync.
+    rmSync(resolvePlacementDir("claudeProject", "forced"), {
+      recursive: true,
+      force: true,
+    });
+
+    const result = await runSync({
+      serverUrl,
+      apiKey: VALID_KEY,
+      vendors: ["claudeCode"],
+    });
+    // Prior syncedAt was set → fullSync stays false even though a
+    // full re-fetch happened. This preserves the init.mjs consumer
+    // semantic: fullSync=true means "no prior sync state existed",
+    // not "this sync returned a full library payload."
+    assert.equal(result.fullSync, false);
+    // The forced re-fetch DOES produce a non-zero write count —
+    // which is why the behavioral consequence of the semantic
+    // mismatch is unreachable. Documents that fact.
+    assert.equal(result.added, 1, "forced re-fetch must restore the missing skill");
+    assert.equal(result.notModified, false);
+  });
 });
 
 // ── runSync — argument validation ──────────────────────────────────────
@@ -1093,3 +1136,180 @@ describe("runSync — cohort placement classification", () => {
     );
   });
 });
+
+// ───────────────────────────────────────────────────────────────────
+// placementsAreComplete unit tests (PR #1575 hotfix)
+// ───────────────────────────────────────────────────────────────────
+//
+// Direct unit coverage for the function that decides whether the ETag
+// short-circuit is safe. The integration tests in
+// update-list-contract.integration.test.mjs exercise the function
+// end-to-end through runSync; this suite covers the branches:
+//
+//   - empty/missing skills map (returns false — force re-fetch)
+//   - empty/missing vendors (returns true — nothing to verify)
+//   - placementTargetsFor throws (returns false — safe direction)
+//   - malformed skill keys (skip without crash)
+//   - skill present in EVERY target (returns true)
+//   - skill missing in ONE target (returns false)
+//   - directory exists but SKILL.md missing (returns false)
+
+describe("placementsAreComplete — direct unit coverage", () => {
+  beforeEach(() => {
+    sandbox = mkdtempSync(join(tmpdir(), "cli-pac-"));
+    mkdirSync(join(sandbox, "project"), { recursive: true });
+    mkdirSync(join(sandbox, "home"), { recursive: true });
+    originalCwd = process.cwd();
+    originalHomeEnv = captureHome();
+    process.chdir(join(sandbox, "project"));
+    setSandboxHome(join(sandbox, "home"));
+  });
+  afterEach(() => {
+    process.chdir(originalCwd);
+    restoreHome(originalHomeEnv);
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  function seedSkillMd(target, skillName) {
+    const dir = resolvePlacementDir(target, skillName);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      `---\nname: ${skillName}\ndescription: x\n---\n`,
+      "utf-8",
+    );
+  }
+
+  it("returns false on null skillsMap (can't trust empty baseline)", () => {
+    assert.equal(placementsAreComplete(null, ["claudeCode"], false), false);
+  });
+
+  it("returns false on undefined skillsMap", () => {
+    assert.equal(placementsAreComplete(undefined, ["claudeCode"], false), false);
+  });
+
+  it("returns false on empty skillsMap object (v1 → v2 recovery path)", () => {
+    assert.equal(placementsAreComplete({}, ["claudeCode"], false), false);
+  });
+
+  it("returns true on empty vendors array (no placements to verify)", () => {
+    // Defensive guard — `requireVendorTargets` in the command layer
+    // catches this case before runSync, but if it ever reached here
+    // we'd return true (no targets means trivially complete).
+    const skills = {
+      "alice/skill": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    assert.equal(placementsAreComplete(skills, [], false), true);
+  });
+
+  it("returns true on undefined vendors (same defensive path)", () => {
+    const skills = {
+      "alice/skill": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    assert.equal(placementsAreComplete(skills, undefined, false), true);
+  });
+
+  it("returns true when every (skill, target) pair has its SKILL.md on disk", () => {
+    seedSkillMd("claudeProject", "skill-a");
+    const skills = {
+      "alice/skill-a": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    assert.equal(placementsAreComplete(skills, ["claudeCode"], false), true);
+  });
+
+  it("returns false when ONE skill's SKILL.md is missing in ONE target", () => {
+    // Two skills, claudeProject + agentsProject expected. Only one
+    // skill landed in claudeProject; agentsProject has neither.
+    seedSkillMd("claudeProject", "skill-a");
+    const skills = {
+      "alice/skill-a": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    // Both claudeCode and cursor → both targets must have skill-a.
+    // Only claudeProject does → returns false → forces re-fetch.
+    assert.equal(
+      placementsAreComplete(skills, ["claudeCode", "cursor"], false),
+      false,
+    );
+  });
+
+  it("returns false when directory exists but SKILL.md is missing (partial dir guard)", () => {
+    // The HIGH finding from the code-reviewer audit: an empty
+    // directory satisfies existsSync but lacks the load-bearing
+    // SKILL.md. The check probes SKILL.md specifically.
+    const dir = resolvePlacementDir("claudeProject", "partial");
+    mkdirSync(dir, { recursive: true });
+    // NOTE: no writeFileSync — dir exists but is empty.
+    const skills = {
+      "alice/partial": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    assert.equal(placementsAreComplete(skills, ["claudeCode"], false), false);
+  });
+
+  it("returns false when placementTargetsFor throws (conservative direction)", () => {
+    // copilot has globalTarget=null. `--global` with copilot throws
+    // inside placementTargetsFor. placementsAreComplete catches the
+    // throw and returns false so we drop the ETag and the
+    // downstream write loop surfaces the same error with the
+    // correct typed exception.
+    const skills = {
+      "alice/skill": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    assert.equal(
+      placementsAreComplete(skills, ["copilot"], true),
+      false,
+    );
+  });
+
+  it("skips malformed skill keys (no slash) without crashing", () => {
+    seedSkillMd("claudeProject", "good");
+    const skills = {
+      "alice/good": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+      // Malformed key — no slash. Should be silently skipped so a
+      // corrupt entry doesn't poison the whole check.
+      "no-slash-key": {
+        version: "1.0.0",
+        skillMdSha256: "a".repeat(64),
+        filesSha256: "b".repeat(64),
+        syncedAt: "x",
+      },
+    };
+    // Returns true because the valid skill is on disk and the
+    // malformed entry is skipped (continue) — no false negative.
+    assert.equal(placementsAreComplete(skills, ["claudeCode"], false), true);
+  });
+});