skillrepo 4.13.0 → 4.14.0

package/package.json

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

package/src/commands/update.mjs

@@ -47,6 +47,7 @@
 
 import { runSync } from "../lib/sync.mjs";
 import { formatGlobalBoundaryDisclosure } from "../lib/global-boundary.mjs";
+import { formatRepoComplianceSummary } from "../lib/foreign-content.mjs";
 import {
   resolveFlags,
   effectiveVendors,
@@ -191,6 +192,19 @@ export async function runUpdate(argv, io = {}) {
       } catch {
         // Degrade to no disclosure line.
       }
+      // Repo compliance state (#2665, owner decision 2026-08-20): a
+      // skillset-declared repo that does not match its set says so in
+      // EVERY session, hook mode included — a state, never a
+      // warn-on-new event. Same failure domain as the disclosure: a
+      // formatter defect degrades to no line, never a failed sync.
+      let compliance = null;
+      try {
+        compliance = summary.compliance
+          ? formatRepoComplianceSummary({ ...summary.compliance, hookMode: true })
+          : null;
+      } catch {
+        // Degrade to no compliance line.
+      }
       const writeDisclosureLine = () => {
         if (!disclosure) return;
         try {
@@ -200,12 +214,21 @@ export async function runUpdate(argv, io = {}) {
           // the cosmetic line must not become a "Sync failed" report.
         }
       };
+      const writeComplianceLine = () => {
+        if (!compliance) return;
+        try {
+          stdout.write(`${compliance}\n`);
+        } catch {
+          // Same failure domain as the disclosure write above.
+        }
+      };
       if (summary.notModified || total === 0) {
         // 304 Not Modified OR 200 with zero deltas — silent by
-        // contract (the boundary disclosure is the one sanctioned
-        // exception). Users should not see "Syncing..." on every
-        // session for no visible value.
+        // contract (the boundary disclosure and the compliance state
+        // are the sanctioned exceptions). Users should not see
+        // "Syncing..." on every session for no visible value.
         writeDisclosureLine();
+        writeComplianceLine();
         return;
       }
       stdout.write(
@@ -214,6 +237,7 @@ export async function runUpdate(argv, io = {}) {
           `.\n`,
       );
       writeDisclosureLine();
+      writeComplianceLine();
     } catch (err) {
       // The one-line failure message is the user's primary signal
       // that something's wrong. Do not surface a stack trace — the

package/src/lib/foreign-content.mjs

@@ -186,11 +186,25 @@ export function scanForeignContent({ vendors, global, managedSkills, baseDir })
  * rules. The names stay on this machine — see the module docstring's
  * privacy contract.
  *
+ * Two copy branches (#2665): in a skillset-declared repo the finding is
+ * a COMPLIANCE statement — the consequence is named ("reported as not
+ * compliant") and the remediation is the governed path (remove, or have
+ * a skillset manager add the skill). `skillrepo push` is deliberately
+ * NOT offered there: pushing publishes the dir to the library but does
+ * not put it in the skillset, so it cannot restore compliance — and the
+ * developer may not hold publish rights at all. Undeclared repos keep
+ * the original library-framed push-or-remove copy.
+ *
  * @param {ForeignScanResult} scan
+ * @param {object} [options]
+ * @param {string | null} [options.skillsetRef] - The declared skillset
+ *        (`owner/name`, schema-validated upstream) when the repo is
+ *        skillset-scoped; absent/null → library-framed copy.
  * @returns {string[]}
  */
-export function formatForeignWarnings(scan) {
+export function formatForeignWarnings(scan, { skillsetRef } = {}) {
   const lines = [];
+  const declared = typeof skillsetRef === "string" && skillsetRef.length > 0;
   for (const rootResult of scan.roots) {
     for (const dir of rootResult.foreignDirs) {
       // Directory names come from readdirSync — filesystem-sourced and
@@ -200,6 +214,15 @@ export function formatForeignWarnings(scan) {
       // server-path treatment in file-write.mjs (#2402 class).
       const safeDir = escapeControlChars(dir);
       const displayPath = `${rootResult.displayRoot}${safeDir}`;
+      if (declared) {
+        lines.push(
+          `  warning: ${displayPath}/ is not part of this repo's skillset ` +
+            `(${skillsetRef}), but agents still load it from disk. Remove the ` +
+            `directory, or ask a skillset manager to add the skill. Until ` +
+            `then this repo is reported as not compliant.`,
+        );
+        continue;
+      }
       // The remediation must be a RUNNABLE command. A tilde-shortened
       // display root ("~/.claude/skills/") breaks copy-paste — quotes
       // suppress shell tilde expansion and Windows cmd never expands
@@ -217,6 +240,100 @@ export function formatForeignWarnings(scan) {
   return lines;
 }
 
+/**
+ * The repo compliance state line (#2665, owner decisions 2026-08-20):
+ * ONE sentence stating that the repo does not currently match its
+ * declared skillset and is reported as not compliant, listing the
+ * locally-observable causes as counts. Unlike the per-dir warnings
+ * above this is a STATE, not an event — callers print it on EVERY
+ * scoped sync while any cause persists (never gated on
+ * `.governance-seen`), including session-hook syncs, where it takes
+ * the `[SkillRepo]` prefix so the agent session sees it too (the
+ * #2495 disclosure precedent). Counts only — names stay in the
+ * per-dir warnings, which remain local-only and warn-on-new.
+ *
+ * Server-side causes a fresh sync cannot observe (behind-version or
+ * missing members on a repo that has not re-synced) surface on the
+ * dashboard instead — this line covers what THIS machine can see now.
+ *
+ * @param {object} input
+ * @param {string} input.skillsetRef - Declared skillset (`owner/name`).
+ * @param {number} [input.unmanagedCount] - Project-scope foreign dirs
+ *        (the scan-derived count — matches the receipt's `unmanaged`
+ *        violation category, deliberately NOT mixed with the
+ *        member-name collisions below).
+ * @param {number} [input.shadowedCount] - Global copies shadowing members.
+ * @param {number} [input.globalBeyondCount] - Global-scope skills beyond
+ *        the set (`global_library` + `global_foreign`).
+ * @param {number} [input.editRefusedCount] - Members whose LOCAL EDITS
+ *        the sync refused to overwrite (`unwrittenReason: "modified"`
+ *        only — the one bucket allowed to claim an edit).
+ * @param {number} [input.memberReplacedCount] - Members whose slot is
+ *        occupied by hand-authored content the CLI never wrote
+ *        (`unwrittenReason: "unmanaged"` — invisible to the foreign
+ *        scan because the dir name IS a managed member name).
+ * @param {number} [input.notDeliveredCount] - Members not delivered as
+ *        approved for server/payload reasons ("incomplete", "invalid")
+ *        or unknown legacy reasons — never phrased as an edit.
+ * @param {boolean} [input.hookMode] - Session-hook formatting
+ *        (`[SkillRepo]` prefix, single line for the hook UI).
+ * @returns {string | null} The line, or null when every count is zero.
+ */
+export function formatRepoComplianceSummary({
+  skillsetRef,
+  unmanagedCount = 0,
+  shadowedCount = 0,
+  globalBeyondCount = 0,
+  editRefusedCount = 0,
+  memberReplacedCount = 0,
+  notDeliveredCount = 0,
+  hookMode = false,
+}) {
+  const parts = [];
+  if (unmanagedCount > 0) {
+    parts.push(
+      `${unmanagedCount} extra skill${unmanagedCount === 1 ? "" : "s"} in the project`,
+    );
+  }
+  if (shadowedCount > 0) {
+    parts.push(
+      `${shadowedCount} member${shadowedCount === 1 ? "" : "s"} shadowed by a global copy`,
+    );
+  }
+  if (globalBeyondCount > 0) {
+    parts.push(
+      `${globalBeyondCount} global skill${globalBeyondCount === 1 ? "" : "s"} beyond the set`,
+    );
+  }
+  if (memberReplacedCount > 0) {
+    parts.push(
+      `${memberReplacedCount} member${memberReplacedCount === 1 ? "" : "s"} replaced by unmanaged content`,
+    );
+  }
+  if (editRefusedCount > 0) {
+    parts.push(
+      `${editRefusedCount} member${editRefusedCount === 1 ? "" : "s"} edited locally`,
+    );
+  }
+  if (notDeliveredCount > 0) {
+    parts.push(
+      `${notDeliveredCount} member${notDeliveredCount === 1 ? "" : "s"} not delivered as approved`,
+    );
+  }
+  if (parts.length === 0) return null;
+  const causes = parts.join(", ");
+  if (hookMode) {
+    return (
+      `[SkillRepo] This repo does not match its skillset ${skillsetRef} ` +
+      `(${causes}) — it is reported as not compliant.`
+    );
+  }
+  return (
+    `  warning: this repo does not match its skillset ${skillsetRef}: ` +
+    `${causes}. It is reported as not compliant to your organization.`
+  );
+}
+
 // ── Warn-on-new state (#2361 owner directive: no repeat warnings) ──────
 //
 // A warning that repeats unchanged findings on every sync trains users

package/src/lib/global-boundary.mjs

@@ -421,10 +421,13 @@ export function formatGlobalBoundaryWarnings(
       // expands — is always the absolute (normalized) root + name.
       const globalPath = join(rootResult.root, safeName);
       if (entry.bucket === GLOBAL_SHADOWED_CATEGORY) {
+        // Shadowing only exists against a declared skillset's members, so
+        // this bucket is always a compliance statement (#2665).
         lines.push(
           `  warning: ${displayPath}/ has the same name as a skillset member. ` +
             `Depending on the agent, the global copy can load instead of the ` +
-            `approved version. Remove the global copy, or rename your local skill.`,
+            `approved version. Remove the global copy, or rename your local ` +
+            `skill. Until then this repo is reported as not compliant.`,
         );
       } else if (entry.bucket === GLOBAL_LIBRARY_CATEGORY) {
         if (skillsetDeclared !== true) continue;
@@ -440,7 +443,20 @@ export function formatGlobalBoundaryWarnings(
         lines.push(
           `  warning: ${displayPath}/ is from your library but outside this ` +
             `repo's skillset, and agents load it in sessions here. Add it to ` +
-            `the skillset, or remove the global copy at ${globalPath}.`,
+            `the skillset, or remove the global copy at ${globalPath}. Until ` +
+            `then this repo is reported as not compliant.`,
+        );
+      } else if (skillsetDeclared === true) {
+        // Foreign content in a DECLARED repo is a compliance statement
+        // (#2665): `skillrepo push` alone cannot restore compliance (it
+        // publishes to the library without touching the skillset, and the
+        // developer may not hold publish rights), so the governed path is
+        // named instead.
+        lines.push(
+          `  warning: ${displayPath}/ is not from your library, but agents ` +
+            `still load it from disk in sessions here. Remove the directory, ` +
+            `or publish it to your library and have a skillset manager add ` +
+            `it. Until then this repo is reported as not compliant.`,
         );
       } else {
         lines.push(

package/src/lib/repo-sync-state.mjs

@@ -110,6 +110,15 @@ export const REPO_SYNC_GRACE_WINDOW_MS = 72 * 60 * 60 * 1000;
  * @property {string} version
  * @property {boolean} written - True = written/kept-current by the CLI
  *           this sync; false = served-but-not-written (guard-refused).
+ * @property {string} [unwrittenReason] - WHY a `written: false` entry
+ *           was not written (#2665): "modified" (local edit refused),
+ *           "unmanaged" (hand-authored dir squatting the member name),
+ *           "incomplete" (partial server payload), "invalid"
+ *           (validation quarantine). LOCAL-ONLY — `buildRepoReceiptBlock`
+ *           whitelists wire fields, so this never leaves the machine.
+ *           Absent on entries written by older CLIs; readers must
+ *           tolerate that (the compliance line buckets unknowns as
+ *           "not delivered as approved", never as an edit claim).
  * @property {string} [skillMdSha256] - Payload SHA baseline; written
  *           entries only.
  * @property {string} [filesSha256]   - Payload SHA baseline; written

package/src/lib/sync.mjs

@@ -148,6 +148,21 @@
  *                                   `names` is LOCAL-ONLY (the disclosure
  *                                   line and `--json`); receipts carry
  *                                   counts-only categories, never names.
+ * @property {{skillsetRef: string, unmanagedCount: number, shadowedCount: number, globalBeyondCount: number, editRefusedCount: number, memberReplacedCount: number, notDeliveredCount: number}} [compliance] -
+ *                                   Repo compliance state (#2665),
+ *                                   counts-only — the input
+ *                                   `formatRepoComplianceSummary`
+ *                                   renders in hook mode. Presence
+ *                                   semantics: PRESENT (possibly
+ *                                   all-zero — the formatter returns
+ *                                   null then) only on the scoped
+ *                                   200 and scoped 304 paths, where a
+ *                                   declaration names the skillset to
+ *                                   compare against; ABSENT on
+ *                                   undeclared/whole-library syncs,
+ *                                   the throttled early-exit, and the
+ *                                   grace/fail-closed paths (no fresh
+ *                                   scans there to state a fact from).
  * @property {string} syncedAt    - ISO timestamp of the sync: the server
  *                                   response `syncedAt` on a 200, or the
  *                                   previously-cached sync timestamp on a
@@ -219,6 +234,7 @@ import {
   selectNewGlobalBoundaryFindings,
   normalizeStateKey,
   receiptViolationSummary,
+  formatRepoComplianceSummary,
 } from "./foreign-content.mjs";
 import {
   scanGlobalBoundary,
@@ -226,6 +242,9 @@ import {
   formatGlobalBoundaryWarnings,
   managedGlobalNamesFrom,
   resolveBoundaryMemberContext,
+  GLOBAL_SHADOWED_CATEGORY,
+  GLOBAL_LIBRARY_CATEGORY,
+  GLOBAL_FOREIGN_CATEGORY,
 } from "./global-boundary.mjs";
 import { resolveDeclaration } from "./skillset-declaration.mjs";
 import {
@@ -1659,6 +1678,7 @@ async function runSkillsetScopedSync({
       declarationDir: rootDir,
       baseDir: rootDir,
       scan: scan304,
+      skillsetRef: declaration.use,
     });
     // Global-boundary scan on the scoped 304 (#2495) — the omission
     // contract runs it on EVERY scoped 200 AND 304, no skippable path.
@@ -1681,6 +1701,16 @@ async function runSkillsetScopedSync({
       ...(freshViolationSummary.count > 0 ? [freshViolationSummary] : []),
       ...receiptGlobalViolations(gbScan304),
     ];
+    // Compliance state line (#2665) — always, from the FRESH scans + the
+    // stored served set; hook mode carries it via the summary instead.
+    const compliance304 = composeRepoCompliance({
+      skillsetRef: declaration.use,
+      foreignCount: scan304.foreignCount,
+      gbScan: gbScan304,
+      resolved: prior.resolved,
+      stderr,
+      hookMode: throttle === true,
+    });
 
     // Stamp BOTH clocks — lastAttemptAt (throttle re-arm, same
     // load-bearing rationale as the bulk 304 path) and lastVerifiedAt
@@ -1734,6 +1764,7 @@ async function runSkillsetScopedSync({
       fullSync: false,
       unmanaged,
       globalBoundary: gbScan304.summary,
+      compliance: compliance304,
       syncedAt: prior.lastSyncedAt ?? nowIso,
     };
   }
@@ -1844,7 +1875,11 @@ async function runSkillsetScopedSync({
       // written, local state does not advance (etag not persisted →
       // retried next session), and whatever is on disk stays.
       anyIncomplete = true;
-      resolvedEntries.push({ ...baseEntry, written: false });
+      resolvedEntries.push({
+        ...baseEntry,
+        written: false,
+        unwrittenReason: "incomplete",
+      });
       continue;
     }
 
@@ -1860,12 +1895,23 @@ async function runSkillsetScopedSync({
       // Serve-refused: the guard protects local work over delivery.
       // Counted in `skipped` so interactive and hook summaries can't
       // go silent on withheld content; `written: false` carries the
-      // durable drift signal in state + receipt.
+      // durable drift signal in state + receipt. The refusal REASON is
+      // kept locally (#2665): "modified" (a genuine local edit) and
+      // "unmanaged" (a hand-authored dir squatting the member's name)
+      // are different compliance facts and the state line must not
+      // call the latter an edit. A mixed multi-target refusal reads
+      // "modified" — an edit anywhere is the stronger claim.
       for (const refusal of decision.refusals) {
         stderr.write(`${formatServeRefusalWarning(refusal, skill)}\n`);
       }
       summary.skipped++;
-      resolvedEntries.push({ ...baseEntry, written: false });
+      resolvedEntries.push({
+        ...baseEntry,
+        written: false,
+        unwrittenReason: decision.refusals.some((r) => r.reason === "modified")
+          ? "modified"
+          : "unmanaged",
+      });
       continue;
     }
 
@@ -1889,7 +1935,11 @@ async function runSkillsetScopedSync({
           `  warning: skipped ${escapeControlChars(skill.owner)}/${escapeControlChars(skill.name)} (${err.message}). ` +
             `Other skills were still synced; this one will be retried next session.\n`,
         );
-        resolvedEntries.push({ ...baseEntry, written: false });
+        resolvedEntries.push({
+          ...baseEntry,
+          written: false,
+          unwrittenReason: "invalid",
+        });
         continue;
       }
       if (wasAlreadyOnDisk) {
@@ -1936,6 +1986,7 @@ async function runSkillsetScopedSync({
     declarationDir: rootDir,
     baseDir: rootDir,
     scan,
+    skillsetRef: declaration.use,
   });
 
   // Global-boundary scan (#2495): the disclosure counterpart to the
@@ -1959,6 +2010,16 @@ async function runSkillsetScopedSync({
     skillsetDeclared: true,
   });
   summary.globalBoundary = gbScan.summary;
+  // Compliance state line (#2665) — always, from this sync's fresh scans
+  // + served set; hook mode carries it via the summary instead.
+  summary.compliance = composeRepoCompliance({
+    skillsetRef: declaration.use,
+    foreignCount: scan.foreignCount,
+    gbScan,
+    resolved: resolvedEntries,
+    stderr,
+    hookMode: throttle === true,
+  });
   const violationSummary = receiptViolationSummary(scan);
   const violations = [
     ...(violationSummary.count > 0 ? [violationSummary] : []),
@@ -2584,7 +2645,7 @@ function emitGlobalBoundaryWarnings({ scan, stderr, hookMode, repoKey, skillsetD
  * @returns {number} Unmanaged-dir count across scanned roots (the
  *          summary's `unmanaged` field — total, not just new).
  */
-function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMode, declarationDir, baseDir, scan: precomputedScan }) {
+function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMode, declarationDir, baseDir, scan: precomputedScan, skillsetRef }) {
   let unmanagedCount = 0;
   try {
     const scan =
@@ -2595,7 +2656,9 @@ function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMo
 
     const seen = readGovernanceSeen();
     const newScan = selectNewFindings(scan, seen);
-    for (const line of formatForeignWarnings(newScan)) {
+    // Declared repos get the compliance-framed per-dir copy (#2665);
+    // undeclared repos keep the library-framed push-or-remove copy.
+    for (const line of formatForeignWarnings(newScan, { skillsetRef })) {
       stderr.write(`${line}\n`);
     }
 
@@ -2622,6 +2685,70 @@ function emitGovernanceWarnings({ vendors, global, managedSkills, stderr, hookMo
   return unmanagedCount;
 }
 
+/**
+ * Compose the repo's compliance state (#2665) from the two governance
+ * scans + the served set, emit the ONE state line on interactive scoped
+ * syncs, and return the counts for the sync summary. STATE, not event:
+ * unlike the per-dir warnings this is never gated on `.governance-seen`
+ * — it prints on EVERY scoped sync while any locally-observable cause
+ * persists (owner decision 2026-08-20, "always report"). Hook mode
+ * emits nothing here (both streams are black-holed by the hook runner);
+ * `update --session-hook` formats the same counts off the returned
+ * summary onto the session's stdout, the #2495 disclosure pattern.
+ * Formatting/writing is its own failure domain — a defect degrades to
+ * "no line", never a failed sync.
+ *
+ * @param {object} args
+ * @param {string} args.skillsetRef - The declared `owner/name`.
+ * @param {number} args.foreignCount - Project-scope foreign dirs.
+ * @param {import("./global-boundary.mjs").GlobalBoundaryScan} args.gbScan
+ * @param {import("./repo-sync-state.mjs").RepoResolvedEntry[]} args.resolved
+ * @param {NodeJS.WritableStream} args.stderr
+ * @param {boolean} args.hookMode
+ * @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 = {
+    skillsetRef,
+    unmanagedCount: foreignCount ?? 0,
+    shadowedCount: gbScan?.counts?.[GLOBAL_SHADOWED_CATEGORY] ?? 0,
+    globalBeyondCount:
+      (gbScan?.counts?.[GLOBAL_LIBRARY_CATEGORY] ?? 0) +
+      (gbScan?.counts?.[GLOBAL_FOREIGN_CATEGORY] ?? 0),
+    editRefusedCount,
+    memberReplacedCount,
+    notDeliveredCount,
+  };
+  if (!hookMode) {
+    try {
+      const line = formatRepoComplianceSummary(compliance);
+      if (line) stderr.write(`${line}\n`);
+    } catch {
+      // Best-effort by design — the state line must never fail a sync.
+    }
+  }
+  return compliance;
+}
+
 /**
  * Build sync-receipt entries from a `.last-sync` skills map (#1832).
  *

package/src/test/lib/foreign-content.test.mjs

@@ -24,6 +24,7 @@ import { execFileSync } from "node:child_process";
 import {
   scanForeignContent,
   formatForeignWarnings,
+  formatRepoComplianceSummary,
   receiptViolationSummary,
   checkDeclarationGitignored,
   formatDeclarationIgnoredWarning,
@@ -199,6 +200,38 @@ describe("formatForeignWarnings", () => {
     }
   });
 
+  it("declared repos get compliance-framed copy: consequence stated, no 'skillrepo push' (#2665)", () => {
+    seedDir(".claude/skills", "hand-rolled");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    const lines = formatForeignWarnings(scan, { skillsetRef: "acme/backend-core" });
+    assert.equal(lines.length, 1);
+    assert.match(lines[0], /^ {2}warning: \.claude\/skills\/hand-rolled\//);
+    assert.match(lines[0], /is not part of this repo's skillset \(acme\/backend-core\)/);
+    assert.match(lines[0], /Remove the directory, or ask a skillset manager to add the skill\./);
+    assert.match(lines[0], /Until then this repo is reported as not compliant\.$/);
+    assert.ok(
+      !lines[0].includes("skillrepo push"),
+      "push cannot restore compliance in a declared repo (#2665)",
+    );
+    assert.ok(!lines[0].includes("!"), "copy rules: no exclamation marks");
+  });
+
+  it("a null/absent skillsetRef keeps the library-framed push-or-remove copy", () => {
+    seedDir(".claude/skills", "hand-rolled");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    for (const options of [undefined, {}, { skillsetRef: null }]) {
+      const [line] = formatForeignWarnings(scan, options);
+      assert.match(line, /is not from your library/);
+      assert.match(line, /skillrepo push/);
+    }
+  });
+
   it("emits nothing for a clean scan", () => {
     const scan = scanForeignContent({
       vendors: ["claudeCode"],
@@ -208,6 +241,100 @@ describe("formatForeignWarnings", () => {
   });
 });
 
+describe("formatRepoComplianceSummary (#2665)", () => {
+  it("returns null when every count is zero (a compliant repo says nothing)", () => {
+    assert.equal(
+      formatRepoComplianceSummary({ skillsetRef: "acme/backend-core" }),
+      null,
+    );
+    assert.equal(
+      formatRepoComplianceSummary({
+        skillsetRef: "acme/backend-core",
+        unmanagedCount: 0,
+        shadowedCount: 0,
+        globalBeyondCount: 0,
+        editRefusedCount: 0,
+        hookMode: true,
+      }),
+      null,
+    );
+  });
+
+  it("interactive: one warning sentence naming the skillset, the causes, and the consequence", () => {
+    const line = formatRepoComplianceSummary({
+      skillsetRef: "acme/backend-core",
+      unmanagedCount: 2,
+      shadowedCount: 1,
+      globalBeyondCount: 3,
+      editRefusedCount: 1,
+    });
+    assert.equal(
+      line,
+      "  warning: this repo does not match its skillset acme/backend-core: " +
+        "2 extra skills in the project, 1 member shadowed by a global copy, " +
+        "3 global skills beyond the set, 1 member edited locally. " +
+        "It is reported as not compliant to your organization.",
+    );
+    assert.ok(!line.includes("!"), "copy rules: no exclamation marks");
+    assert.ok(
+      !line.includes("account") && !line.includes("team"),
+      "copy rules: 'organization', never 'account'/'team'",
+    );
+  });
+
+  it("hook mode: one [SkillRepo]-prefixed line for the agent session", () => {
+    const line = formatRepoComplianceSummary({
+      skillsetRef: "acme/backend-core",
+      unmanagedCount: 1,
+      hookMode: true,
+    });
+    assert.equal(
+      line,
+      "[SkillRepo] This repo does not match its skillset acme/backend-core " +
+        "(1 extra skill in the project) — it is reported as not compliant.",
+    );
+  });
+
+  it("includes only nonzero causes and pluralizes each", () => {
+    const line = formatRepoComplianceSummary({
+      skillsetRef: "acme/x",
+      shadowedCount: 2,
+    });
+    assert.match(line, /2 members shadowed by a global copy/);
+    assert.ok(!line.includes("extra skill"));
+    assert.ok(!line.includes("beyond the set"));
+    assert.ok(!line.includes("edited locally"));
+    const singular = formatRepoComplianceSummary({
+      skillsetRef: "acme/x",
+      globalBeyondCount: 1,
+      editRefusedCount: 2,
+    });
+    assert.match(singular, /1 global skill beyond the set/);
+    assert.match(singular, /2 members edited locally/);
+  });
+
+  it("keeps replaced-by-unmanaged and not-delivered as their own causes — never phrased as edits (#2665 review)", () => {
+    const line = formatRepoComplianceSummary({
+      skillsetRef: "acme/x",
+      memberReplacedCount: 1,
+      notDeliveredCount: 2,
+    });
+    assert.match(line, /1 member replaced by unmanaged content/);
+    assert.match(line, /2 members not delivered as approved/);
+    assert.ok(
+      !line.includes("edited"),
+      "server-side and squatting causes must never claim a local edit",
+    );
+    const plural = formatRepoComplianceSummary({
+      skillsetRef: "acme/x",
+      memberReplacedCount: 2,
+      notDeliveredCount: 1,
+    });
+    assert.match(plural, /2 members replaced by unmanaged content/);
+    assert.match(plural, /1 member not delivered as approved/);
+  });
+});
+
 describe("receiptViolationSummary — the H7/#2111 privacy seam", () => {
   it("carries category and count ONLY — never names", () => {
     seedDir(".claude/skills", "secret-internal-tool");

package/src/test/lib/global-boundary.test.mjs

@@ -463,7 +463,7 @@ describe("formatGlobalBoundaryWarnings", () => {
     assert.match(lines[0], /is from your library but outside this repo's skillset/);
     // Separator-agnostic: join() emits "\linter" on Windows, "/linter"
     // elsewhere — the path is real either way.
-    assert.match(lines[0], /Add it to the skillset, or remove the global copy at .*[/\\]linter\.$/);
+    assert.match(lines[0], /Add it to the skillset, or remove the global copy at .*[/\\]linter\./);
     // Must NOT suggest `skillrepo remove`: that deletes the item from the
     // whole library (DELETE /api/v1/library/{owner}/{name}), and a bare
     // name can't address it anyway — the CLI rejects it (#2495 audit).
@@ -498,6 +498,41 @@ describe("formatGlobalBoundaryWarnings", () => {
     );
   });
 
+  it("declared repos state the compliance consequence on every bucket (#2665)", () => {
+    seedGlobal(".claude/skills", "deploy"); // shadows a member
+    seedGlobal(".claude/skills", "linter"); // library, outside the set
+    seedGlobal(".claude/skills", "stranger"); // foreign
+    const scan = scanClaude({
+      memberNames: new Set(["deploy"]),
+      managedGlobalNames: new Set(["linter"]),
+    });
+    const lines = formatGlobalBoundaryWarnings(scan, { skillsetDeclared: true });
+    assert.equal(lines.length, 3);
+    for (const line of lines) {
+      assert.match(
+        line,
+        /Until then this repo is reported as not compliant\.$/,
+        `consequence missing on: ${line}`,
+      );
+      assert.ok(!line.includes("!"), "copy rules: no exclamation marks");
+    }
+  });
+
+  it("foreign (declared): governed remediation, never a bare 'skillrepo push' (#2665)", () => {
+    seedGlobal(".claude/skills", "stranger");
+    const scan = scanClaude();
+    const [line] = formatGlobalBoundaryWarnings(scan, { skillsetDeclared: true });
+    assert.match(line, /is not from your library/);
+    assert.match(
+      line,
+      /Remove the directory, or publish it to your library and have a skillset manager add it\./,
+    );
+    assert.ok(
+      !line.includes("skillrepo push"),
+      "push alone cannot restore compliance in a declared repo",
+    );
+  });
+
   it("escapes control characters in warning lines", { skip: platform() === "win32" }, () => {
     seedGlobal(".claude/skills", "evil\u001b]0;pwned\u0007");
     const [line] = formatGlobalBoundaryWarnings(scanClaude(), {

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

@@ -1467,3 +1467,185 @@ describe("skillset-scoped sync — session-hook mode exits 0 on every failure cl
     assert.match(stdout.text(), /^\[SkillRepo\] Sync failed: .+\n$/);
   });
 });
+
+// ── Repo compliance state line (#2665) ─────────────────────────────────
+
+describe("repo compliance state line (#2665) — always on while non-compliant", () => {
+  beforeEach(setupServer);
+  afterEach(teardownServer);
+
+  const STATE_LINE = /this repo does not match its skillset acme\/backend-core/;
+
+  it("prints on EVERY interactive scoped sync while per-dir details stay warn-on-new", async () => {
+    declareRepo();
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha")]));
+    const stderr0 = createCaptureStream();
+    await scopedSync({ io: { stderr: stderr0 } });
+    assert.ok(!STATE_LINE.test(stderr0.text()), "a compliant repo says nothing");
+
+    const handmadeDir = join(repoRoot(), ".claude", "skills", "handmade");
+    mkdirSync(handmadeDir, { recursive: true });
+    writeFileSync(join(handmadeDir, "SKILL.md"), "---\nname: handmade\n---\n");
+
+    // Second sync (304): the per-dir warning wears the declared-repo copy
+    // AND the one-line state summary prints.
+    const stderr1 = createCaptureStream();
+    await scopedSync({ io: { stderr: stderr1 } });
+    const t1 = stderr1.text();
+    assert.match(
+      t1,
+      /handmade\/ is not part of this repo's skillset \(acme\/backend-core\)/,
+      "declared repos get the compliance-framed per-dir copy",
+    );
+    assert.match(t1, /Until then this repo is reported as not compliant\./);
+    assert.ok(!t1.includes("skillrepo push"), "no push remediation in a declared repo");
+    assert.match(t1, STATE_LINE);
+    assert.match(
+      t1,
+      /1 extra skill in the project\. It is reported as not compliant to your organization\./,
+    );
+
+    // Third sync: the per-dir detail is seen-state-gated away; the STATE
+    // line still prints — a state, not an event (owner decision
+    // 2026-08-20, "always report").
+    const stderr2 = createCaptureStream();
+    await scopedSync({ io: { stderr: stderr2 } });
+    const t2 = stderr2.text();
+    assert.ok(!t2.includes("handmade"), "per-dir detail stays warn-on-new");
+    assert.match(t2, STATE_LINE, "state line prints on every sync while non-compliant");
+  });
+
+  it("counts edit-refused members in the state line", async () => {
+    declareRepo();
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha"), makeSkill("beta")]));
+    await scopedSync();
+    appendFileSync(
+      join(repoRoot(), ".claude", "skills", "beta", "SKILL.md"),
+      "\nlocal edit\n",
+    );
+    // The skillset moves on, so the next sync is a 200 full-set reconcile
+    // that serve-refuses the edited beta (written: false).
+    server.setSkillsetEtag(SS_ETAG_B);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha"), makeSkill("beta")]));
+    const stderr = createCaptureStream();
+    await scopedSync({ io: { stderr } });
+    assert.match(stderr.text(), STATE_LINE);
+    assert.match(stderr.text(), /1 member edited locally/);
+  });
+
+  it("session-hook mode surfaces the state line on stdout with the [SkillRepo] prefix, counts only", async () => {
+    declareRepo();
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha")]));
+    const handmadeDir = join(repoRoot(), ".claude", "skills", "handmade");
+    mkdirSync(handmadeDir, { recursive: true });
+    writeFileSync(join(handmadeDir, "SKILL.md"), "---\nname: handmade\n---\n");
+
+    const stdout = createCaptureStream();
+    await runUpdate(
+      ["--session-hook", "--key", VALID_KEY, "--url", serverUrl],
+      { stdout },
+    );
+    const out = stdout.text();
+    assert.match(out, /\[SkillRepo\] Library synced: 1 added/);
+    assert.match(
+      out,
+      /\[SkillRepo\] This repo does not match its skillset acme\/backend-core \(1 extra skill in the project\) — it is reported as not compliant\./,
+    );
+    assert.ok(
+      !out.includes("handmade"),
+      "hook line is counts-only — no dir names reach the session output",
+    );
+  });
+
+  it("a hand-authored dir squatting a MEMBER name reads 'replaced by unmanaged content', never 'edited locally' (#2665 review)", async () => {
+    declareRepo();
+    // The squat exists BEFORE the first sync: the CLI never wrote alpha,
+    // so decideScopedWrite refuses with reason "unmanaged".
+    const squat = join(repoRoot(), ".claude", "skills", "alpha");
+    mkdirSync(squat, { recursive: true });
+    writeFileSync(join(squat, "SKILL.md"), "---\nname: alpha\n---\nhand-authored\n");
+
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha")]));
+    const stderr = createCaptureStream();
+    const result = await scopedSync({ io: { stderr } });
+    const t = stderr.text();
+
+    assert.match(t, /1 member replaced by unmanaged content/);
+    assert.ok(!t.includes("edited locally"), "a squat is not an edit");
+    // Not folded into the extras count either — that stays scan-derived so
+    // it matches the receipt's `unmanaged` violation category (the squat's
+    // name IS a managed member name, so the foreign scan never counts it).
+    assert.ok(!t.includes("extra skill in the project"));
+    assert.equal(result.compliance.memberReplacedCount, 1);
+    assert.equal(result.compliance.editRefusedCount, 0);
+    assert.equal(result.compliance.unmanagedCount, 0);
+
+    // Wire whitelist proof: the receipt entry carries exactly the four
+    // fields — the local-only unwrittenReason never leaves the machine.
+    const receipt = server.getLastReceipt();
+    assert.deepEqual(receipt.repo.resolved, [
+      { owner: "acme", name: "alpha", version: "1.0.0", written: false },
+    ]);
+  });
+
+  it("a filesIncomplete member reads 'not delivered as approved', never 'edited locally' (#2665 review)", async () => {
+    declareRepo();
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(
+      scopedResponse([{ ...makeSkill("alpha"), filesIncomplete: true }]),
+    );
+    const stderr = createCaptureStream();
+    const result = await scopedSync({ io: { stderr } });
+    const t = stderr.text();
+    assert.match(t, /1 member not delivered as approved/);
+    assert.ok(!t.includes("edited locally"), "a server-side gap is not an edit");
+    assert.equal(result.compliance.notDeliveredCount, 1);
+    assert.equal(result.compliance.editRefusedCount, 0);
+  });
+
+  it("a legacy state entry without unwrittenReason buckets as not-delivered on the 304 path (#2665 review)", async () => {
+    declareRepo();
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha")]));
+    await scopedSync();
+
+    // Simulate state written by an older CLI: written:false, no reason.
+    const prior = readRepoSyncState(repoRoot());
+    writeRepoSyncState(repoRoot(), {
+      ...prior,
+      resolved: prior.resolved.map((e) => ({
+        owner: e.owner,
+        name: e.name,
+        version: e.version,
+        written: false,
+      })),
+    });
+
+    const stderr = createCaptureStream();
+    const result = await scopedSync({ io: { stderr } });
+    assert.equal(result.notModified, true);
+    const t = stderr.text();
+    assert.match(t, /1 member not delivered as approved/);
+    assert.ok(!t.includes("edited locally"), "no false edit claim for unknown legacy reasons");
+    assert.equal(result.compliance.notDeliveredCount, 1);
+  });
+
+  it("a global copy shadowing a member flows through the real boundary scan into the state line (#2665 review)", async () => {
+    declareRepo();
+    // Global scope lives under the sandbox HOME set by setupServer.
+    const globalDir = join(sandbox, "home", ".claude", "skills", "alpha");
+    mkdirSync(globalDir, { recursive: true });
+    writeFileSync(join(globalDir, "SKILL.md"), "---\nname: alpha\n---\nglobal copy\n");
+
+    server.setSkillsetEtag(SS_ETAG_A);
+    server.setSkillsetResponse(scopedResponse([makeSkill("alpha")]));
+    const stderr = createCaptureStream();
+    const result = await scopedSync({ io: { stderr } });
+    assert.equal(result.compliance.shadowedCount, 1);
+    assert.match(stderr.text(), /1 member shadowed by a global copy/);
+  });
+});