skillrepo 4.14.1 → 4.15.0

package/package.json

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

package/src/lib/sync.mjs

@@ -253,6 +253,7 @@ import {
   normalizeStateKey,
   receiptViolationSummary,
   formatRepoComplianceSummary,
+  buildRepoCompliance,
 } from "./foreign-content.mjs";
 import {
   scanGlobalBoundary,
@@ -2738,36 +2739,23 @@ function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMo
  * @returns {{skillsetRef: string, unmanagedCount: number, shadowedCount: number, globalBeyondCount: number, editRefusedCount: number, memberReplacedCount: number, notDeliveredCount: number}}
  */
 function composeRepoCompliance({ skillsetRef, foreignCount, gbScan, resolved, stderr, hookMode }) {
-  // Bucket the served-but-not-written entries by their recorded reason
-  // (#2665 review): "modified" is the only bucket allowed to claim a
-  // local edit. "unmanaged" (a hand-authored dir squatting a member's
-  // name — invisible to the foreign scan because the name IS managed)
-  // gets its own bucket rather than folding into `unmanagedCount`, so
-  // the state line's extras count stays consistent with the receipt's
-  // scan-derived `unmanaged` violation count. Everything else —
-  // "incomplete", "invalid", and entries from older CLIs/state files
-  // that carry no reason — reads as the neutral "not delivered as
-  // approved", never as an edit accusation.
-  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;
-  }
-  const compliance = {
+  // The served-but-not-written bucketing (#2665 review — "modified" is
+  // the only bucket allowed to claim a local edit; "unmanaged" gets its
+  // own bucket so the state line's extras count stays consistent with
+  // the receipt's scan-derived `unmanaged`; everything else reads as the
+  // neutral "not delivered as approved") lives in `buildRepoCompliance`
+  // so `list` (#2672) composes the identical object read-only. The
+  // scan-derived counts are extracted from THIS sync's fresh gbScan here,
+  // where the global-boundary category constants are already imported.
+  const compliance = buildRepoCompliance({
     skillsetRef,
-    unmanagedCount: foreignCount ?? 0,
+    foreignCount,
     shadowedCount: gbScan?.counts?.[GLOBAL_SHADOWED_CATEGORY] ?? 0,
     globalBeyondCount:
       (gbScan?.counts?.[GLOBAL_LIBRARY_CATEGORY] ?? 0) +
       (gbScan?.counts?.[GLOBAL_FOREIGN_CATEGORY] ?? 0),
-    editRefusedCount,
-    memberReplacedCount,
-    notDeliveredCount,
-  };
+    resolved,
+  });
   if (!hookMode) {
     try {
       const line = formatRepoComplianceSummary(compliance);

package/src/test/commands/list.test.mjs

@@ -16,7 +16,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import { runList } from "../../commands/list.mjs";
-import { CliError, EXIT_AUTH, EXIT_NETWORK } from "../../lib/errors.mjs";
+import { CliError, EXIT_AUTH, EXIT_NETWORK, EXIT_UNRESOLVABLE } from "../../lib/errors.mjs";
 import { computeSkillShas } from "../../lib/crypto-shas.mjs";
 import { globalLastSyncPath } from "../../lib/paths.mjs";
 import { writeRepoSyncState } from "../../lib/repo-sync-state.mjs";
@@ -1400,3 +1400,476 @@ describe("runList — global-boundary disclosure (#2495)", () => {
     );
   });
 });
+
+// ── Skillset-declared view (#2672) ─────────────────────────────────────
+//
+// In a repo whose skillrepo.json DECLARES a skillset, `list` shows that
+// repo's DELIVERED set (the per-repo state file's `resolved` manifest),
+// its per-row drift against the per-repo SHA baselines at the DETECTED
+// ROOT, and the #2665 compliance line — never the whole library. The
+// capture stream is non-TTY, so status cells render as ASCII tokens
+// (OK / EDIT / MISS / NOT DELIVERED), matching the library-view tests.
+describe("runList — skillset-declared view (#2672)", () => {
+  beforeEach(async () => {
+    await setup();
+    forceClaudeCodeDetected();
+  });
+  afterEach(async () => {
+    unforceDetection();
+    await teardown();
+  });
+
+  /** Write a DECLARING skillrepo.json (+ .git walk boundary) into cwd. */
+  function declareSkillset({ name = "checkout", use = "acme/backend-core", extra } = {}) {
+    mkdirSync(join(process.cwd(), ".git"), { recursive: true });
+    const block = { version: 1, name, use, ...(extra ? { extra } : {}) };
+    writeFileSync(join(process.cwd(), "skillrepo.json"), JSON.stringify({ skillset: block }));
+  }
+
+  /** A written:true resolved entry whose baseline SHAs match `files` on disk. */
+  function deliveredMember(owner, name, version, files) {
+    const shas = seedClaudeSkillOnDisk(name, files);
+    return {
+      owner,
+      name,
+      version,
+      written: true,
+      skillMdSha256: shas.skillMdSha256,
+      filesSha256: shas.filesSha256,
+    };
+  }
+
+  it("shows the delivered set under the skillset header, never the whole library", async () => {
+    declareSkillset();
+    const member = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [member],
+    });
+    // The library the skillset view must NOT show.
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Skillset: acme\/backend-core \(declared as checkout\)/);
+    assert.match(out, /acme\/deploy/);
+    assert.match(out, /1 member delivered and current/);
+    assert.match(out, /\[ok\] compliant with skillset acme\/backend-core/);
+    assert.ok(!out.includes("pdf-helper"), "the whole library is never shown in a declared repo");
+  });
+
+  it("is fully offline and read-only: no library GET, no receipt, no state writes", async () => {
+    const { existsSync } = await import("node:fs");
+    const { globalGovernanceSeenPath } = await import("../../lib/paths.mjs");
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        deliveredMember("acme", "deploy", "1.0.0", [
+          { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+        ]),
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    assert.equal(server.getLibraryRequestCount(), 0, "skillset view must not hit the library endpoint");
+    assert.equal(server.getReceiptRequestCount(), 0, "list never writes a receipt");
+    assert.equal(existsSync(globalLastSyncPath()), false, "list must not create .last-sync");
+    assert.equal(existsSync(globalGovernanceSeenPath()), false, "list must not write governance-seen");
+  });
+
+  it("leaves the per-repo state file byte-unchanged (read-only, hardened)", async () => {
+    const { readFileSync } = await import("node:fs");
+    const { repoStatePathFor } = await import("../../lib/repo-sync-state.mjs");
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        deliveredMember("acme", "deploy", "1.0.0", [
+          { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+        ]),
+      ],
+    });
+    const statePath = repoStatePathFor(process.cwd());
+    const before = readFileSync(statePath, "utf8");
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+
+    assert.equal(
+      readFileSync(statePath, "utf8"),
+      before,
+      "list must never rewrite the per-repo state file it reads",
+    );
+  });
+
+  it("classifies delivered members: current / edited / missing (against the per-repo baseline)", async () => {
+    declareSkillset();
+    // current — on-disk content matches the recorded baseline.
+    const current = deliveredMember("acme", "keep", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("keep") },
+    ]);
+    // edited — on disk, but the baseline SHAs are for different content.
+    seedClaudeSkillOnDisk("touched", [{ path: "SKILL.md", content: SKILL_MD_BODY("touched-now") }]);
+    const original = computeSkillShas([
+      { path: "SKILL.md", content: SKILL_MD_BODY("touched-original") },
+    ]);
+    const edited = {
+      owner: "acme",
+      name: "touched",
+      version: "1.0.0",
+      written: true,
+      skillMdSha256: original.skillMdSha256,
+      filesSha256: original.filesSha256,
+    };
+    // missing — a written baseline but nothing on disk.
+    const missing = deliveredMember("acme", "gone", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("gone") },
+    ]);
+    rmSync(join(process.cwd(), ".claude", "skills", "gone"), { recursive: true, force: true });
+
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [current, edited, missing],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    // Bind each status to ITS member (same table row — names are short
+    // enough not to wrap), so a status-swap regression can't pass.
+    assert.match(out, /@acme\/keep[^\n]*OK/);
+    assert.match(out, /@acme\/touched[^\n]*EDIT/);
+    assert.match(out, /@acme\/gone[^\n]*MISS/);
+    assert.match(out, /3 members in skillset acme\/backend-core\. 2 need attention/);
+  });
+
+  it("escapes control characters in a state-file-sourced member name (no terminal injection)", async () => {
+    declareSkillset();
+    // A corrupt / tampered per-repo state file with a raw ANSI escape in
+    // a member name — the CLI must not emit it to the terminal verbatim.
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        { owner: "acme", name: "deploy\u001b[31mFAKE", version: "1.0.0", written: false, unwrittenReason: "invalid" },
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    // Assert on the ATTACKER's payload specifically, not "any ESC byte":
+    // cli-table3 emits its own ANSI for the table border/header when colors
+    // are enabled (e.g. on Windows CI), so a blanket !includes(ESC) is a
+    // false positive there. The injected raw ESC[31mFAKE must not survive...
+    assert.ok(!out.includes("\u001b[31mFAKE"), "the injected raw ANSI sequence must never reach stdout");
+    // ...it is rendered as its escaped form instead.
+    assert.ok(out.includes("\\u001b[31mFAKE"), "the injected control char is rendered escaped");
+    assert.match(out, /deploy/, "the (escaped) name is still shown");
+  });
+
+  it("re-scans project foreign content: an extra dir drives unmanagedCount + non-compliance (human + json)", async () => {
+    declareSkillset();
+    const member = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    // A non-member directory squatting in the managed placement root.
+    seedClaudeSkillOnDisk("rogue", [{ path: "SKILL.md", content: SKILL_MD_BODY("rogue") }]);
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [member],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /1 extra skill in the project/);
+    assert.match(out, /not compliant to your organization/);
+
+    const jsonStdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout: jsonStdout });
+    const parsed = JSON.parse(jsonStdout.text());
+    assert.equal(parsed.skillset.compliance.unmanagedCount, 1, "the fresh foreign re-scan reaches the JSON compliance");
+    assert.equal(parsed.skillset.compliant, false);
+  });
+
+  it("re-scans global content: a shadowing global copy drives shadowedCount + non-compliance", async () => {
+    declareSkillset();
+    const member = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    // A global-scope dir with the SAME name as a member → global_shadowed.
+    const globalDir = join(process.env.HOME, ".claude", "skills", "deploy");
+    mkdirSync(globalDir, { recursive: true });
+    writeFileSync(join(globalDir, "SKILL.md"), SKILL_MD_BODY("deploy-global"));
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [member],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /shadowed by a global copy/);
+    assert.match(out, /not compliant to your organization/);
+
+    const jsonStdout = createCaptureStream();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout: jsonStdout });
+    const parsed = JSON.parse(jsonStdout.text());
+    assert.ok(parsed.skillset.compliance.shadowedCount >= 1, "the fresh global re-scan reaches the JSON compliance");
+    assert.equal(parsed.skillset.compliant, false);
+  });
+
+  it("renders a served-but-not-written member as a 'not delivered' row and flags non-compliance", async () => {
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        { owner: "acme", name: "locked", version: "1.0.0", written: false, unwrittenReason: "modified" },
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /NOT DELIVERED · edited locally/);
+    assert.match(
+      out,
+      /warning: this repo does not match its skillset acme\/backend-core: 1 member edited locally\. It is reported as not compliant to your organization\./,
+    );
+  });
+
+  it("buckets not-delivered reasons (replaced / not-delivered) in the status cells and compliance line", async () => {
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        { owner: "acme", name: "squatted", version: "1.0.0", written: false, unwrittenReason: "unmanaged" },
+        { owner: "acme", name: "partial", version: "1.0.0", written: false, unwrittenReason: "incomplete" },
+        { owner: "acme", name: "bad", version: "1.0.0", written: false, unwrittenReason: "invalid" },
+        { owner: "acme", name: "legacy", version: "1.0.0", written: false },
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /replaced/);
+    assert.match(out, /incomplete/);
+    assert.match(out, /invalid/);
+    assert.match(
+      out,
+      /1 member replaced by unmanaged content, 3 members not delivered as approved/,
+    );
+  });
+
+  it("declared but never scoped-synced (no state file): points at update, never the library view", async () => {
+    declareSkillset();
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /This repo declares skillset acme\/backend-core, but there is no local sync state/);
+    assert.match(out, /Run `skillrepo update`/);
+    assert.ok(!out.includes("pdf-helper"), "never falls back to the library view (D9)");
+    assert.equal(server.getLibraryRequestCount(), 0, "no state → still no library GET");
+  });
+
+  it("declared, never-synced, --json: emits the synced:false skillset block, not a bare array", async () => {
+    declareSkillset();
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const parsed = JSON.parse(stdout.text());
+    assert.ok(!Array.isArray(parsed), "declared repos emit a wrapped object");
+    assert.equal(parsed.skillset.ref, "acme/backend-core");
+    assert.equal(parsed.skillset.synced, false);
+    assert.deepEqual(parsed.skills, []);
+  });
+
+  it("an INVALID declaration fails closed (exit 6) and never shows the library", async () => {
+    // A `use` with no slash is invalid → resolveDeclaration returns the
+    // typed fail-closed error, exactly as sync surfaces it.
+    declareSkillset({ use: "noslash" });
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+
+    await assert.rejects(
+      () => runList(["--key", VALID_KEY, "--url", serverUrl], { stdout }),
+      (err) => err instanceof CliError && err.exitCode === EXIT_UNRESOLVABLE,
+    );
+    assert.equal(server.getLibraryRequestCount(), 0, "a mis-declared repo is never shown the whole library");
+  });
+
+  it("a config-only skillrepo.json (no skillset key) keeps the whole-library view", async () => {
+    mkdirSync(join(process.cwd(), ".git"), { recursive: true });
+    writeFileSync(join(process.cwd(), "skillrepo.json"), JSON.stringify({ someOtherConfig: true }));
+    server.setLibraryResponse({
+      skills: [makeSkill("alice", "pdf-helper")],
+      removals: [],
+      syncedAt: "x",
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.ok(!out.includes("Skillset:"), "config-only is not a declaration");
+    assert.match(out, /pdf-helper/);
+    assert.equal(server.getLibraryRequestCount(), 1, "config-only still uses the library path");
+  });
+
+  it("--json (declared + synced) is a wrapped object with machine-readable compliance", async () => {
+    declareSkillset();
+    const delivered = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        delivered,
+        { owner: "acme", name: "locked", version: "2.0.0", written: false, unwrittenReason: "modified" },
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const parsed = JSON.parse(stdout.text());
+    assert.ok(!Array.isArray(parsed));
+    assert.equal(parsed.skillset.ref, "acme/backend-core");
+    assert.equal(parsed.skillset.synced, true);
+    assert.equal(parsed.skillset.compliant, false, "an editRefused member is non-compliant");
+    assert.equal(parsed.skillset.compliance.editRefusedCount, 1);
+    const deployRow = parsed.skills.find((s) => s.name === "deploy");
+    const lockedRow = parsed.skills.find((s) => s.name === "locked");
+    assert.equal(deployRow.delivered, true);
+    assert.equal(deployRow.state, "current");
+    assert.equal(lockedRow.delivered, false);
+    assert.equal(lockedRow.state, "not-delivered");
+    assert.equal(lockedRow.reason, "modified");
+  });
+
+  it("--json marks a fully-compliant repo compliant:true", async () => {
+    declareSkillset();
+    const member = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [member],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl, "--json"], { stdout });
+    const parsed = JSON.parse(stdout.text());
+    assert.equal(parsed.skillset.compliant, true);
+    assert.equal(parsed.skills[0].state, "current");
+  });
+
+  it("an empty skillset (zero resolved members) says so and is compliant", async () => {
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Skillset acme\/backend-core resolves to no members/);
+    assert.match(out, /\[ok\] compliant with skillset acme\/backend-core/);
+  });
+
+  it("resolves by walking up and reads placements at the DETECTED ROOT, not cwd", async () => {
+    // Declaration, state, and placements all live at the repo ROOT; the
+    // command runs from a nested subdirectory. The pre-#2672 cwd walk
+    // would find no placement (→ missing); the detected-root walk finds
+    // it (→ current). Detection is env-forced, so it survives the chdir.
+    declareSkillset();
+    const member = deliveredMember("acme", "deploy", "1.0.0", [
+      { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+    ]);
+    const root = process.cwd();
+    writeRepoSyncState(root, {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [member],
+    });
+    const sub = join(root, "packages", "app");
+    mkdirSync(sub, { recursive: true });
+    process.chdir(sub);
+    try {
+      await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    } finally {
+      process.chdir(root);
+    }
+    const out = stdout.text();
+    assert.match(out, /Skillset: acme\/backend-core/);
+    assert.match(out, /1 member delivered and current/);
+  });
+
+  it("declared repo with no detected agents: still the skillset view, member reads MISS", async () => {
+    unforceDetection(); // no agent footprint on this machine/project
+    declareSkillset();
+    writeRepoSyncState(process.cwd(), {
+      repoName: "checkout",
+      skillsetRef: "acme/backend-core",
+      resolved: [
+        {
+          owner: "acme",
+          name: "deploy",
+          version: "1.0.0",
+          written: true,
+          skillMdSha256: "a".repeat(64),
+          filesSha256: "b".repeat(64),
+        },
+      ],
+    });
+
+    await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout });
+    const out = stdout.text();
+    assert.match(out, /Skillset: acme\/backend-core/);
+    assert.match(out, /No agents detected in this project/);
+    // No detected vendor → nothing to compare against → missing.
+    assert.match(out, /MISS/);
+  });
+
+  it("renders glyphs on a TTY (delivered current + not-delivered)", async () => {
+    const noColorSnapshot = process.env.NO_COLOR;
+    delete process.env.NO_COLOR; // canUseGlyphs short-circuits false if set
+    const ttyStdout = createTtyCaptureStream();
+    try {
+      declareSkillset();
+      const member = deliveredMember("acme", "deploy", "1.0.0", [
+        { path: "SKILL.md", content: SKILL_MD_BODY("deploy") },
+      ]);
+      writeRepoSyncState(process.cwd(), {
+        repoName: "checkout",
+        skillsetRef: "acme/backend-core",
+        resolved: [
+          member,
+          { owner: "acme", name: "locked", version: "1.0.0", written: false, unwrittenReason: "modified" },
+        ],
+      });
+
+      await runList(["--key", VALID_KEY, "--url", serverUrl], { stdout: ttyStdout });
+      const out = ttyStdout.text();
+      assert.match(out, /✓ current/);
+      assert.match(out, /⊘ not delivered · edited locally/);
+    } finally {
+      if (noColorSnapshot !== undefined) process.env.NO_COLOR = noColorSnapshot;
+    }
+  });
+});

package/src/test/dispatcher.test.mjs

@@ -14,8 +14,9 @@ import { describe, it } from "node:test";
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
-import { readFileSync } from "node:fs";
+import { dirname, resolve, join } from "node:path";
+import { readFileSync, mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_BIN = resolve(__dirname, "../../bin/skillrepo.mjs");
@@ -32,6 +33,9 @@ const PKG_PATH = resolve(__dirname, "../../package.json");
  *        prove "no global config" code paths fire correctly. Pass
  *        SKILLREPO_ACCESS_KEY: "" explicitly to override an inherited
  *        env var from the developer's shell.
+ * @param {string} [opts.cwd] - Working directory to spawn the binary in.
+ *        Used by declaration-aware commands (they walk up from cwd to a
+ *        `skillrepo.json`). Undefined → the test process's cwd (default).
  */
 function runCli(args = [], opts = {}) {
   return new Promise((resolve) => {
@@ -52,6 +56,7 @@ function runCli(args = [], opts = {}) {
       {
         encoding: "utf-8",
         timeout: 10_000,
+        cwd: opts.cwd,
         env: { ...baseEnv, ...(opts.env || {}) },
       },
       (err, stdout, stderr) => {
@@ -331,3 +336,31 @@ describe("dispatcher — init still works (PR1 keeps existing init untouched)",
   // Real init flow is exercised by src/test/e2e/cli-init.test.mjs
   // against the mock server. We don't duplicate that here.
 });
+
+describe("dispatcher — skillset declaration fail-closed (#2672)", () => {
+  // Locks the D9 fail-closed contract at the PRODUCTION entry point:
+  // `list` in a repo whose skillrepo.json is a declaration but cannot be
+  // honored must exit 6 (EXIT_UNRESOLVABLE) through bin → runList → the
+  // dispatcher's CliError→process.exit mapping — not just at the function
+  // level. This is the one exit code that had no spawned-process coverage.
+  it("`skillrepo list` with an INVALID declaration exits 6 (never shows the library)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cli-disp-2672-"));
+    try {
+      mkdirSync(join(dir, ".git"), { recursive: true });
+      // `use` with no slash is a fail-closed declaration error.
+      writeFileSync(
+        join(dir, "skillrepo.json"),
+        JSON.stringify({ skillset: { version: 1, name: "x", use: "noslash" } }),
+      );
+      // A key is required before the declaration gate is reached, so pass
+      // one via flag (beats the empty SKILLREPO_ACCESS_KEY in baseEnv).
+      const r = await runCli(["list", "--key", "sk_live_test"], { cwd: dir });
+      assert.equal(r.status, 6, "invalid declaration must fail closed with EXIT_UNRESOLVABLE");
+      assert.match(r.stderr + r.stdout, /must have the form "owner\/name"/);
+      // D9: the whole-library table is never rendered on an invalid decl.
+      assert.ok(!/in your library/.test(r.stdout));
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});