skillrepo 4.14.0 → 4.15.0

package/package.json

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

package/src/commands/list.mjs

@@ -8,7 +8,23 @@
  * reports the library-level ETag state ("library in sync" vs
  * "library has changed since last sync").
  *
- * Pipeline:
+ * Skillset-declared repos (#2672, epic #2357). When cwd walks up to a
+ * `skillrepo.json` that DECLARES a skillset, `list` shows that repo's
+ * DELIVERED view instead of the whole library: rows are the per-repo
+ * state file's `resolved` manifest (the same set the sync receipts
+ * attest — NOT a live re-resolution of the declaration), drift is
+ * computed against the per-repo SHA baselines and the DETECTED-ROOT
+ * placements (never `.last-sync`/cwd, which scoped syncs bypass by
+ * design — D12), and the #2665 compliance line is appended. This path
+ * is fully offline (no library GET) and read-only. An `invalid`
+ * declaration fails closed exactly as `sync` does — a mis-declared
+ * repo is never shown the whole library (D9). Undeclared and
+ * config-only repos keep the whole-library view below, byte-identical
+ * to pre-#2672 (D2). Recall status is deliberately NOT surfaced here
+ * (the CLI has no recall signal — recall is absence in delivery);
+ * tracked separately in #2793.
+ *
+ * Pipeline (whole-library view):
  *   1. `getLibrary` returns the current registry skills + ETag.
  *   2. `readLastSync` reads the v2 `.last-sync` map (per-skill SHAs +
  *      versions) for the on-disk-vs-synced comparison.
@@ -47,8 +63,18 @@ import {
   scanGlobalBoundary,
   formatGlobalBoundaryDisclosure,
   managedGlobalNamesFrom,
-  resolveBoundaryMemberContext,
+  GLOBAL_SHADOWED_CATEGORY,
+  GLOBAL_LIBRARY_CATEGORY,
+  GLOBAL_FOREIGN_CATEGORY,
 } from "../lib/global-boundary.mjs";
+import { resolveDeclaration } from "../lib/skillset-declaration.mjs";
+import { readRepoSyncState } from "../lib/repo-sync-state.mjs";
+import {
+  scanForeignContent,
+  buildRepoCompliance,
+  formatRepoComplianceSummary,
+} from "../lib/foreign-content.mjs";
+import { escapeControlChars } from "../lib/file-write.mjs";
 
 /**
  * Run `list`. Throws CliError on any failure.
@@ -60,8 +86,43 @@ import {
  */
 export async function runList(argv, io = {}) {
   const stdout = io.stdout ?? process.stdout;
+  const stderr = io.stderr ?? process.stderr;
   const flags = resolveFlags(argv);
 
+  // #2672: dispatch on the repo's skillset declaration BEFORE any
+  // network call, so the skillset path stays fully offline. Resolution
+  // is local-only and never throws for the undeclared cases; `invalid`
+  // carries a typed fail-closed error.
+  const declaration = resolveDeclaration();
+
+  if (declaration.status === "invalid") {
+    // Fail closed, exactly as `sync` does (D9): a mis-declared repo must
+    // never be shown the whole library — that fail-OPEN is the bug this
+    // issue removes. The dispatcher prints this typed error cleanly.
+    throw declaration.error;
+  }
+
+  if (declaration.status === "declared") {
+    return runSkillsetListView({ declaration, flags, stdout, stderr });
+  }
+
+  // `absent` | `config-only` → the whole-library view, byte-identical
+  // to pre-#2672 (D2).
+  return runLibraryListView({ flags, stdout });
+}
+
+/**
+ * The whole-library `list` view (#679 / #1555): fetch the manifest,
+ * classify each library skill's on-disk drift against `.last-sync`, and
+ * render the table + ETag footer + global-boundary disclosure. Reached
+ * for undeclared and config-only repos; behavior is unchanged from
+ * pre-#2672.
+ *
+ * @param {object} args
+ * @param {ReturnType<typeof resolveFlags>} args.flags
+ * @param {NodeJS.WritableStream} args.stdout
+ */
+async function runLibraryListView({ flags, stdout }) {
   // `list` is a read-only drift check — it must NEVER set sync state,
   // and (#2495) it never writes the governance-seen file either: the
   // boundary disclosure below scans without committing warn-state, so
@@ -153,7 +214,15 @@ export async function runList(argv, io = {}) {
  */
 function printGlobalBoundaryDisclosure(vendors, lastSync, stdout) {
   try {
-    const { memberNames, baseDir } = resolveBoundaryMemberContext();
+    // Reached ONLY for undeclared / config-only repos — the dispatcher
+    // routes declared repos to the skillset view and throws on invalid —
+    // so there is never a skillset member set here. `resolveBoundaryMemberContext()`
+    // would just re-walk the declaration the dispatcher already resolved
+    // and return exactly `{ memberNames: null, baseDir: undefined }`;
+    // inlining it avoids that redundant second walk-up per plain `list`
+    // (#2672 review).
+    const memberNames = null;
+    const baseDir = undefined;
     const scan = scanGlobalBoundary({
       vendors,
       memberNames,
@@ -255,6 +324,391 @@ function validateBaselineShape(entry) {
   return entry;
 }
 
+// ── Skillset-declared view (#2672) ─────────────────────────────────────
+
+/**
+ * Sentinel status for a resolved member that was SERVED but not written
+ * to disk by the CLI (`written: false`). Distinct from the four
+ * `SKILL_STATE` drift values, which only apply to delivered members.
+ */
+const SKILLSET_NOT_DELIVERED = "not-delivered";
+
+/**
+ * Render `list` for a skillset-declared repo: the repo's DELIVERED set,
+ * sourced from the per-repo state file (`repo-sync-state.mjs`) — the
+ * same manifest the sync receipts attest, NOT a live re-resolution of
+ * the declaration. Fully offline and read-only: no library GET, no state
+ * writes, no `.governance-seen` writes.
+ *
+ * Sub-cases:
+ *   - No per-repo state (declared but never scoped-synced here) → say so
+ *     and point at `skillrepo update`; NEVER fall back to the library
+ *     view (that silent fallback is the D9 shape this issue removes).
+ *   - Have state → the delivered manifest as rows (per-row drift for
+ *     written members against the per-repo SHA baseline at the detected
+ *     root; a distinct "not delivered" row for served-but-refused
+ *     members) plus the #2665 compliance line, composed the way `sync`'s
+ *     304 path does — REPLAY the delivery-reason counts from `resolved`,
+ *     RE-SCAN foreign + global content fresh from disk (read-only).
+ *
+ * @param {object} args
+ * @param {import("../lib/skillset-declaration.mjs").DeclarationResolution} args.declaration
+ * @param {ReturnType<typeof resolveFlags>} args.flags
+ * @param {NodeJS.WritableStream} args.stdout
+ * @param {NodeJS.WritableStream} args.stderr
+ */
+function runSkillsetListView({ declaration, flags, stdout, stderr }) {
+  const rootDir = declaration.rootDir;
+  const skillsetRef = declaration.declaration.use;
+  const repoName = declaration.declaration.name;
+
+  // The state reader warns ONCE on a corrupt file — that diagnostic
+  // belongs on stderr, never stdout (which `--json` consumers parse).
+  const state = readRepoSyncState(rootDir, { stderr });
+
+  if (!state) {
+    // Declared but no readable per-repo state → never scoped-synced here
+    // (or the state file was corrupt, which the reader already flagged on
+    // stderr). Either way the remediation is a sync — NOT a library-view
+    // fallback.
+    if (flags.json) {
+      stdout.write(
+        JSON.stringify(
+          { skillset: { ref: skillsetRef, repo: repoName, synced: false }, skills: [] },
+          null,
+          2,
+        ) + "\n",
+      );
+      return;
+    }
+    stdout.write(
+      `\n  This repo declares skillset ${skillsetRef}, but there is no local sync state for it yet.\n` +
+        "  Run `skillrepo update` to fetch it.\n\n",
+    );
+    return;
+  }
+
+  const detected = detectAgents().filter((d) => d.detected);
+  const detectedVendorEntries = detected
+    .map((d) => getAgentByKey(d.key))
+    .filter((entry) => entry !== null && entry.projectTarget !== null);
+  const detectedKeys = detectedVendorEntries.map((e) => e.key);
+
+  // Placements anchored at the DETECTED ROOT (#2672), not cwd.
+  const placementsMap = walkDetectedPlacements(detectedKeys, rootDir);
+
+  const resolved = Array.isArray(state.resolved) ? state.resolved : [];
+  const members = resolved.map((entry) =>
+    augmentMember(entry, detectedVendorEntries, placementsMap),
+  );
+
+  const { compliance, gbScan } = evaluateSkillsetGovernance({
+    skillsetRef,
+    resolved,
+    detectedKeys,
+    rootDir,
+  });
+
+  if (flags.json) {
+    stdout.write(
+      JSON.stringify(
+        formatSkillsetJson({ skillsetRef, repoName, members, compliance }),
+        null,
+        2,
+      ) + "\n",
+    );
+    return;
+  }
+
+  printSkillsetTable({ skillsetRef, repoName, detected, members, compliance, gbScan, out: stdout });
+}
+
+/**
+ * Per-member drift for the skillset view. `written: true` members are
+ * classified against their per-repo SHA baseline exactly like the
+ * library view (reusing `computeSkillState`), but with the SERVED
+ * version as both the library version and the baseline version — so this
+ * view has no STALE axis (the delivered version IS the approved one; an
+ * upstream bump is invisible offline). `written: false` members were
+ * served but the CLI refused to write them; they carry no baseline and
+ * become a distinct "not delivered" row keyed by `unwrittenReason`.
+ *
+ * @param {import("../lib/repo-sync-state.mjs").RepoResolvedEntry} entry
+ * @param {import("../lib/agent-registry.mjs").AgentEntry[]} detectedVendorEntries
+ * @param {Map<string, import("../lib/placement-walk.mjs").LocalPlacement>} placementsMap
+ */
+function augmentMember(entry, detectedVendorEntries, placementsMap) {
+  const owner = entry.owner;
+  const name = entry.name;
+  const version = entry.version ?? null;
+
+  if (entry.written !== true) {
+    return {
+      owner,
+      name,
+      version,
+      delivered: false,
+      reason: typeof entry.unwrittenReason === "string" ? entry.unwrittenReason : null,
+      status: SKILLSET_NOT_DELIVERED,
+      placements: [],
+    };
+  }
+
+  const baseline = validateBaselineShape({
+    version: entry.version,
+    skillMdSha256: entry.skillMdSha256,
+    filesSha256: entry.filesSha256,
+  });
+  const placements = [];
+  for (const vendorEntry of detectedVendorEntries) {
+    const onDisk = placementsMap.get(`${vendorEntry.key}::project::${name}`) ?? null;
+    const localPlacement = onDisk
+      ? { present: true, skillMdSha256: onDisk.skillMdSha256, filesSha256: onDisk.filesSha256 }
+      : { present: false, skillMdSha256: null, filesSha256: null };
+    const state = computeSkillState({
+      libraryVersion: version,
+      lastSyncEntry: baseline,
+      localPlacement,
+    });
+    placements.push({ vendor: vendorEntry.key, scope: "project", state });
+  }
+  const status = rollupState(placements.map((p) => p.state));
+  return { owner, name, version, delivered: true, reason: null, status, placements };
+}
+
+/**
+ * Run the read-only governance scans for the skillset view ONCE and
+ * return both the #2665 compliance object and the raw global-boundary
+ * scan (the latter feeds the #2495 disclosure line, so both surfaces
+ * share one scan). Compliance is composed the way `sync`'s 304 path
+ * does: REPLAY the delivery-reason counts from `resolved` (via
+ * `buildRepoCompliance`) and RE-SCAN foreign + global content fresh from
+ * disk. Uses the raw `scanForeignContent` / `scanGlobalBoundary` — never
+ * `sync`'s `runGlobalBoundaryScan`, which also emits warnings and would
+ * commit seen-state (forbidden here). Best-effort: a scan failure leaves
+ * the scan-derived counts at zero (and `gbScan` null), so the
+ * delivery-reason half of compliance still stands.
+ *
+ * @param {object} args
+ * @param {string} args.skillsetRef
+ * @param {import("../lib/repo-sync-state.mjs").RepoResolvedEntry[]} args.resolved
+ * @param {string[]} args.detectedKeys
+ * @param {string} args.rootDir
+ * @returns {{ compliance: ReturnType<typeof buildRepoCompliance>, gbScan: (import("../lib/global-boundary.mjs").GlobalBoundaryScan | null) }}
+ */
+function evaluateSkillsetGovernance({ skillsetRef, resolved, detectedKeys, rootDir }) {
+  const managedSkills = {};
+  for (const e of resolved) {
+    if (e && e.owner && e.name) {
+      managedSkills[`${e.owner}/${e.name}`] = { version: e.version };
+    }
+  }
+
+  let foreignCount = 0;
+  let gbScan = null;
+  try {
+    foreignCount = scanForeignContent({
+      vendors: detectedKeys,
+      global: false,
+      managedSkills,
+      baseDir: rootDir,
+    }).foreignCount;
+    gbScan = scanGlobalBoundary({
+      vendors: detectedKeys,
+      memberNames: new Set(resolved.map((e) => e.name)),
+      managedGlobalNames: managedGlobalNamesFrom(readLastSync()?.skills),
+      baseDir: rootDir,
+    });
+  } catch {
+    // Best-effort: a scan failure must never crash the delivered-set view.
+  }
+
+  const compliance = buildRepoCompliance({
+    skillsetRef,
+    foreignCount,
+    shadowedCount: gbScan?.counts?.[GLOBAL_SHADOWED_CATEGORY] ?? 0,
+    globalBeyondCount:
+      (gbScan?.counts?.[GLOBAL_LIBRARY_CATEGORY] ?? 0) +
+      (gbScan?.counts?.[GLOBAL_FOREIGN_CATEGORY] ?? 0),
+    resolved,
+  });
+  return { compliance, gbScan };
+}
+
+/**
+ * Skillset `--json` shape (#2672). Undeclared repos keep the #679 bare
+ * array (see `formatJson`); a declared repo grows a top-level object so
+ * the skillset ref and machine-readable compliance have a home — no
+ * existing script consumes `list --json` inside a declared repo, so this
+ * new shape breaks no contract. Recall is absent by design (#2793).
+ */
+function formatSkillsetJson({ skillsetRef, repoName, members, compliance }) {
+  return {
+    skillset: {
+      ref: skillsetRef,
+      repo: repoName,
+      synced: true,
+      // Single source of truth for "compliant": the formatter returns
+      // null iff there are zero causes, so a future 7th cause updates both
+      // the warning line and this flag in lockstep (#2672 review).
+      compliant: formatRepoComplianceSummary(compliance) === null,
+      compliance: {
+        unmanagedCount: compliance.unmanagedCount,
+        shadowedCount: compliance.shadowedCount,
+        globalBeyondCount: compliance.globalBeyondCount,
+        editRefusedCount: compliance.editRefusedCount,
+        memberReplacedCount: compliance.memberReplacedCount,
+        notDeliveredCount: compliance.notDeliveredCount,
+      },
+    },
+    skills: members
+      .slice()
+      .sort(sortByOwnerAndName)
+      .map((m) => ({
+        owner: m.owner,
+        name: m.name,
+        version: m.version,
+        delivered: m.delivered,
+        state: m.delivered ? m.status : SKILLSET_NOT_DELIVERED,
+        ...(m.delivered ? {} : { reason: m.reason }),
+        placements: m.placements,
+      })),
+  };
+}
+
+/**
+ * Human table for the skillset view. Columns are Skill / Version /
+ * Status — no Updated/Description (the per-repo state carries neither;
+ * fetching them would mean a library GET this offline view deliberately
+ * avoids). The #2665 compliance line is appended via the SAME formatter
+ * `sync` uses; when compliant, a positive one-liner replaces it.
+ */
+function printSkillsetTable({ skillsetRef, repoName, detected, members, compliance, gbScan, out }) {
+  const useGlyphs = canUseGlyphs(out);
+
+  out.write(`\n  Skillset: ${skillsetRef}${repoName ? ` (declared as ${repoName})` : ""}\n`);
+  if (detected.length > 0) {
+    const detectedLabel = detected.map((d) => `${d.displayName} (project)`).join(", ");
+    out.write(`  Detected: ${detectedLabel}\n`);
+  } else {
+    out.write("  No agents detected in this project.\n");
+  }
+
+  const sorted = members.slice().sort(sortByOwnerAndName);
+
+  if (sorted.length === 0) {
+    out.write(`\n  Skillset ${skillsetRef} resolves to no members.\n\n`);
+  } else {
+    const table = new Table({
+      head: ["Skill", "Version", "Status"],
+      colWidths: computeSkillsetColWidths(streamColumns(out)),
+      wordWrap: true,
+      style: { head: ["bold"] },
+    });
+    for (const m of sorted) {
+      // Escape control chars in the state-file-sourced identifier and
+      // version before printing (#2402 class). The per-repo state file is
+      // filesystem-sourced and could be corrupt or tampered; a raw ANSI
+      // sequence in a member `name` would otherwise clear the screen or
+      // spoof the compliance verdict this view exists to report truthfully.
+      // `cli-table3` emits cell content verbatim (it only ignores escapes
+      // for width). `--json` needs no escaping — JSON.stringify handles it.
+      table.push([
+        escapeControlChars(formatIdentifier(m)),
+        escapeControlChars(String(m.version ?? "")) || "—",
+        renderSkillsetStatusCell(m, useGlyphs),
+      ]);
+    }
+    out.write("\n" + table.toString() + "\n\n");
+
+    // "needs attention" = any delivered member that isn't CURRENT, plus
+    // every not-delivered member.
+    const attention = sorted.filter(
+      (m) => !m.delivered || m.status !== SKILL_STATE.CURRENT,
+    ).length;
+    const total = sorted.length;
+    if (attention === 0) {
+      out.write(`  ${total} member${total === 1 ? "" : "s"} delivered and current.\n`);
+    } else {
+      out.write(
+        `  ${total} member${total === 1 ? "" : "s"} in skillset ${skillsetRef}. ` +
+          `${attention} need${attention === 1 ? "s" : ""} attention.\n`,
+      );
+    }
+  }
+
+  // #2665 compliance state line — same formatter as `sync`, appended when
+  // any cause is present (the formatter returns null when compliant).
+  const line = formatRepoComplianceSummary(compliance);
+  if (line) {
+    out.write(`${line}\n`);
+  } else {
+    out.write(`  ${useGlyphs ? "✓" : "[ok]"} compliant with skillset ${skillsetRef}.\n`);
+  }
+
+  // #2495 global-boundary disclosure — the same read-only one-liner the
+  // library view and session hook print, naming the global skills that
+  // ALSO load in this session. Complementary to the compliance verdict
+  // above (operational awareness vs governance verdict); best-effort, so
+  // it never fails the view.
+  try {
+    const disclosure = gbScan ? formatGlobalBoundaryDisclosure(gbScan) : null;
+    if (disclosure) out.write(`  ${disclosure}\n`);
+  } catch {
+    // Disclosure is best-effort on every surface.
+  }
+  out.write("\n");
+}
+
+/**
+ * Status cell for a skillset member. Delivered members use the drift
+ * vocabulary; not-delivered members key their copy off the refusal
+ * reason, matching the compliance line ("edited locally" / "replaced").
+ */
+function renderSkillsetStatusCell(m, useGlyphs) {
+  if (!m.delivered) {
+    const detail =
+      m.reason === "modified"
+        ? "edited locally"
+        : m.reason === "unmanaged"
+          ? "replaced"
+          : m.reason === "incomplete"
+            ? "incomplete"
+            : m.reason === "invalid"
+              ? "invalid"
+              : null;
+    const base = useGlyphs ? "⊘ not delivered" : "NOT DELIVERED";
+    return detail ? `${base} · ${detail}` : base;
+  }
+  switch (m.status) {
+    case SKILL_STATE.CURRENT:
+      return useGlyphs ? "✓ current" : "OK";
+    case SKILL_STATE.EDITED:
+      return useGlyphs ? "✎ edited" : "EDIT";
+    case SKILL_STATE.MISSING:
+      return useGlyphs ? "✗ missing" : "MISS";
+    default:
+      // Only current/edited/missing are reachable for a delivered member —
+      // its served version IS its baseline version, so `computeSkillState`
+      // never returns `stale` here. `?` is the defensive catch-all.
+      return useGlyphs ? "?" : "?";
+  }
+}
+
+/**
+ * Three-column widths for the skillset table (Skill / Version /
+ * Status), same cap/floor policy as the library table's
+ * `computeColWidths`.
+ */
+function computeSkillsetColWidths(terminalColumns) {
+  const total = terminalColumns > 60 ? Math.min(terminalColumns, 120) : 100;
+  const skillCol = 34;
+  const versionCol = 12;
+  // -4 accounts for the 2 between-column borders + edge padding.
+  const statusCol = Math.max(20, total - skillCol - versionCol - 4);
+  return [skillCol, versionCol, statusCol];
+}
+
 // ── JSON formatter ─────────────────────────────────────────────────────
 
 /**

package/src/commands/update.mjs

@@ -65,6 +65,8 @@ import {
  *
  *   - 304 Not Modified → exit 0, NO output.
  *   - 200 with changes → exit 0, ONE line: `[SkillRepo] Library synced: N added, N updated, N removed.`
+ *     ("Skillset" replaces "Library" when a declared repo ran a scoped
+ *     skillset sync — #2679.)
  *   - Any failure → exit 0, ONE line: `[SkillRepo] Sync failed: <reason>.`
  *   - Global-boundary disclosure (#2495): when the sync's summary
  *     reports global skills that will also load in this session
@@ -172,6 +174,7 @@ export async function runUpdate(argv, io = {}) {
       const skipped = summary.skipped ?? 0;
       const total =
         summary.added + summary.updated + summary.removed + skipped;
+      const subject = syncSubject(summary);
       // Global-boundary disclosure (#2495), computed BEFORE the silent
       // branch below: the quiet 304/zero-delta/throttled session is
       // the COMMON session, and it must still disclose — the line
@@ -232,7 +235,7 @@ export async function runUpdate(argv, io = {}) {
         return;
       }
       stdout.write(
-        `[SkillRepo] Library synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
+        `[SkillRepo] ${subject} synced: ${summary.added} added, ${summary.updated} updated, ${summary.removed} removed` +
           (skipped > 0 ? `, ${skipped} SKIPPED (could not be written)` : "") +
           `.\n`,
       );
@@ -338,17 +341,28 @@ export async function runUpdate(argv, io = {}) {
   printSummary(summary, stdout);
 }
 
+// The noun for the scope a sync operated on (#2679). A declared repo's
+// scoped sync carries a top-level `skillsetRef` (stamped by the runSync
+// dispatcher on EVERY scoped return, including the grace/fail-closed path);
+// a whole-library sync does not. Keying off THIS — not the #2665
+// `compliance` object, whose presence excludes the non-fresh-scan paths —
+// is what keeps a scoped grace sync from mislabeling itself "Library".
+function syncSubject(summary) {
+  return summary.skillsetRef ? "Skillset" : "Library";
+}
+
 function printSummary(s, out) {
   // `skipped` counts here: a run that dropped a skill is NOT "up to date",
   // and saying so was a false statement to the user (#2413 adversarial
   // review — the counter was incremented and never read).
   const skipped = s.skipped ?? 0;
   const total = s.added + s.updated + s.removed + skipped;
+  const subject = syncSubject(s);
   if (s.notModified || total === 0) {
-    out.write("  ✓ Library is up to date.\n");
+    out.write(`  ✓ ${subject} is up to date.\n`);
     return;
   }
-  out.write("\n  Library sync complete:\n");
+  out.write(`\n  ${subject} sync complete:\n`);
   if (s.added > 0)   out.write(`    + ${s.added} added\n`);
   if (s.updated > 0) out.write(`    ↻ ${s.updated} updated\n`);
   if (s.removed > 0) out.write(`    − ${s.removed} removed\n`);

package/src/lib/foreign-content.mjs

@@ -334,6 +334,64 @@ export function formatRepoComplianceSummary({
   );
 }
 
+/**
+ * Bucket a per-repo `resolved` manifest into the #2665 compliance
+ * object. Pure — no I/O, no printing — so both `sync` (which prints the
+ * line to stderr, `composeRepoCompliance`) and `list` (#2672, which
+ * renders it under the skillset table) share ONE definition of how
+ * served-but-not-written entries map to the three delivery-reason
+ * buckets.
+ *
+ * The scan-derived counts (`foreignCount`, `shadowedCount`,
+ * `globalBeyondCount`) are computed by the caller from the fresh
+ * foreign + global-boundary scans and passed in — keeping the
+ * global-boundary category constants out of this module (there is a
+ * one-directional import global-boundary → foreign-content already, so
+ * importing them back would cycle). This function owns only the
+ * `resolved`-derived half, the part identical wherever a per-repo state
+ * is read: `written: true` entries never contribute (they were
+ * delivered); `written: false` entries bucket by `unwrittenReason` —
+ * "modified" → editRefused (the one bucket allowed to claim a local
+ * edit), "unmanaged" → memberReplaced, everything else
+ * (incomplete/invalid, or a legacy entry with no reason) →
+ * notDelivered, never phrased as an edit.
+ *
+ * @param {object} input
+ * @param {string} input.skillsetRef
+ * @param {number} [input.foreignCount] - Project-scope foreign dirs
+ *        (the scan's `foreignCount`) → `unmanagedCount`.
+ * @param {number} [input.shadowedCount]
+ * @param {number} [input.globalBeyondCount]
+ * @param {Array<{written?: boolean, unwrittenReason?: string}>} [input.resolved]
+ * @returns {{skillsetRef: string, unmanagedCount: number, shadowedCount: number, globalBeyondCount: number, editRefusedCount: number, memberReplacedCount: number, notDeliveredCount: number}}
+ */
+export function buildRepoCompliance({
+  skillsetRef,
+  foreignCount = 0,
+  shadowedCount = 0,
+  globalBeyondCount = 0,
+  resolved = [],
+}) {
+  let editRefusedCount = 0;
+  let memberReplacedCount = 0;
+  let notDeliveredCount = 0;
+  for (const e of resolved ?? []) {
+    if (!e || e.written === true) continue;
+    if (e.unwrittenReason === "modified") editRefusedCount += 1;
+    else if (e.unwrittenReason === "unmanaged") memberReplacedCount += 1;
+    else notDeliveredCount += 1;
+  }
+  return {
+    skillsetRef,
+    unmanagedCount: foreignCount ?? 0,
+    shadowedCount: shadowedCount ?? 0,
+    globalBeyondCount: globalBeyondCount ?? 0,
+    editRefusedCount,
+    memberReplacedCount,
+    notDeliveredCount,
+  };
+}
+
 // ── Warn-on-new state (#2361 owner directive: no repeat warnings) ──────
 //
 // A warning that repeats unchanged findings on every sync trains users

package/src/lib/placement-walk.mjs

@@ -68,9 +68,13 @@ import { getAgentByKey } from "./agent-registry.mjs";
  * vendors that map to the same target share the walk's results.
  *
  * @param {string[]} detectedVendorKeys
+ * @param {string} [baseDir] - Project-scope anchor (#2672): the skillset
+ *   view passes the declaration's DETECTED ROOT so placements are read
+ *   from the repo root, not cwd. Omitted (undefined) → today's
+ *   cwd-anchored behavior, byte-identical for the whole-library view.
  * @returns {Map<string, LocalPlacement>}
  */
-export function walkDetectedPlacements(detectedVendorKeys) {
+export function walkDetectedPlacements(detectedVendorKeys, baseDir) {
   if (!Array.isArray(detectedVendorKeys) || detectedVendorKeys.length === 0) {
     return new Map();
   }
@@ -91,7 +95,7 @@ export function walkDetectedPlacements(detectedVendorKeys) {
   /** @type {Map<string, LocalPlacement>} */
   const result = new Map();
   for (const [target, vendorKeys] of targetToVendors) {
-    const skillsAtTarget = walkPlacementTarget(target);
+    const skillsAtTarget = walkPlacementTarget(target, baseDir);
     for (const skill of skillsAtTarget) {
       for (const vendorKey of vendorKeys) {
         const key = `${vendorKey}::project::${skill.skillName}`;
@@ -119,12 +123,14 @@ export function walkDetectedPlacements(detectedVendorKeys) {
  * vendor/scope expansion happens in `walkDetectedPlacements`.
  *
  * @param {string} target - PlacementTarget enum value.
+ * @param {string} [baseDir] - Project-scope anchor (#2672), threaded to
+ *   `resolvePlacementRoot`. Omitted → cwd-anchored (unchanged).
  * @returns {{ skillName: string, skillMdSha256: string | null, filesSha256: string | null }[]}
  */
-export function walkPlacementTarget(target) {
+export function walkPlacementTarget(target, baseDir) {
   let parentDir;
   try {
-    parentDir = resolvePlacementRoot(target);
+    parentDir = resolvePlacementRoot(target, baseDir);
   } catch {
     // Unknown target — surface as no placements rather than throwing.
     // Defensive: detect-agents + agent-registry should never produce