skillrepo 4.10.0 → 4.11.0

package/README.md

@@ -183,6 +183,18 @@ Sync also warns — once per repo, same rules — when a `skillrepo.json`
 at the repo root is gitignored: the skillset declaration only works as
 a committed file, so remove it from `.gitignore` and commit it.
 
+A repository can declare a skillset in a root `skillrepo.json`:
+`{"skillset": {"version": 1, "name": "<repo-identity>", "use":
+"owner/skillset-name"}}` (optional `extra: ["owner/skill"]`). The CLI
+finds the file from any subdirectory (it walks up to the repository
+root) and validates it before syncing. Skillset delivery is not yet
+available: a repository with a declaration fails its sync closed
+(exit code `6`) rather than receiving the whole library — a declared
+repo only ever receives its declared skillset. Keep the declaration
+while your team prepares for skillsets, or remove the `skillset`
+block to sync your whole library. A `skillrepo.json` without a
+`skillset` key is plain configuration and does not change sync.
+
 ### `get` — fetch a single skill
 
 ```sh
@@ -574,6 +586,7 @@ citations on each agent's read paths.
 | 3 | Disk error (cannot read or write a file/directory) |
 | 4 | Scope error (key lacks the required `registry:write` scope) |
 | 5 | Validation error (bad flag, malformed identifier, unknown vendor) |
+| 6 | Unresolvable skillset declaration — the repo's root `skillrepo.json` declares a skillset that cannot be honored (invalid or nested declaration, reserved `@` version syntax, or skillset delivery not yet available). Fail-closed: nothing was written or removed. |
 
 Pass `--verbose` to any command to print stack traces and retry
 attempts on failure.

package/package.json

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

package/src/commands/init.mjs

@@ -94,6 +94,7 @@ import {
   authError,
   validationError,
   EXIT_AUTH,
+  EXIT_UNRESOLVABLE,
 } from "../lib/errors.mjs";
 import { cliAuthUrl } from "../lib/constants.mjs";
 import {
@@ -658,10 +659,23 @@ export async function runInit(argv, io = {}, deps = {}) {
       // rethrow) as an inconsistent contract: the warning told users
       // to retry with `update`, but the non-zero exit code made it
       // look like the whole init had failed.
-      p.warning(
-        `Config saved but first sync failed: ${err.message}. ` +
-          `Run \`skillrepo update\` later to retry.`,
-      );
+      // Declaration-gated repos (#2362) get tailored copy: "run
+      // update later to retry" is wrong advice when the sync failed
+      // closed on the repo's skillset declaration — retrying changes
+      // nothing until the declaration is fixed/removed (or, for the
+      // not-yet-available case, until skillset delivery ships). The
+      // error message + hint already carry why and what to do.
+      if (err instanceof CliError && err.exitCode === EXIT_UNRESOLVABLE) {
+        p.warning(
+          `Config saved, but this repository's library sync is blocked: ${err.message}` +
+            (err.hint ? ` ${err.hint}` : ""),
+        );
+      } else {
+        p.warning(
+          `Config saved but first sync failed: ${err.message}. ` +
+            `Run \`skillrepo update\` later to retry.`,
+        );
+      }
       syncFailedReason = err.message;
       // Synthesize a zero-delta summary matching the SyncSummary
       // typedef in sync.mjs (added, updated, removed, notModified,

package/src/lib/errors.mjs

@@ -9,6 +9,15 @@
  *   3 — disk error (cannot read or write a file/directory)
  *   4 — scope error (key lacks the required scope for the requested action)
  *   5 — validation error (bad CLI input — invalid flag, malformed identifier, etc.)
+ *   6 — unresolvable skillset declaration (#2362, design doc D9): the
+ *       repo's `skillrepo.json` skillset declaration cannot be honored
+ *       (unparseable file, invalid sub-schema, nested declarations,
+ *       reserved `@` version syntax, or skillset delivery not yet
+ *       available). Fail-closed: nothing was written or removed. This
+ *       one code covers the WHOLE D9 fail-closed class, locally AND —
+ *       once H8 (#2365) wires the server — the server's typed 422
+ *       `harness_unresolvable` response, so CI scripts get one stable
+ *       "declaration cannot be honored" signal.
  *
  * These mirror the documented behavior in #683 and are the contract
  * shell users and CI scripts can rely on.
@@ -40,6 +49,7 @@ export const EXIT_AUTH = 2;
 export const EXIT_DISK = 3;
 export const EXIT_SCOPE = 4;
 export const EXIT_VALIDATION = 5;
+export const EXIT_UNRESOLVABLE = 6;
 
 /**
  * Base error class for typed CLI errors. Carries an exit code and
@@ -89,6 +99,19 @@ export function validationError(message, options) {
   return new CliError(message, EXIT_VALIDATION, options);
 }
 
+/**
+ * Unresolvable skillset declaration (#2362). Distinct from
+ * `validationError` on purpose: exit 5 means "your CLI input is bad",
+ * and one member of this class — skillset delivery not yet being
+ * available — is not the user's fault at all (the declaration file may
+ * be perfectly valid). D9's fail-closed contract holds for every
+ * member: nothing was written or removed, and the sync NEVER falls
+ * back to whole-library delivery.
+ */
+export function unresolvableError(message, options) {
+  return new CliError(message, EXIT_UNRESOLVABLE, options);
+}
+
 // ── Retry helper ───────────────────────────────────────────────────────
 
 /**

package/src/lib/file-write.mjs

@@ -160,6 +160,21 @@ export function escapeControlChars(value) {
   );
 }
 
+/**
+ * True when the value contains any control character (C0, DEL, or C1 —
+ * the same class `escapeControlChars` escapes). Exported (#2362) so
+ * validators can REJECT control characters up front with the one
+ * canonical class instead of hand-rolling a second, narrower regex —
+ * the skillset-declaration validator is the first consumer. Single
+ * source per the shared-logic rule.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function hasControlChars(value) {
+  return CONTROL_CHARS.test(value);
+}
+
 /**
  * Validate a single file path inside a skill directory.
  *

package/src/lib/skillset-declaration.mjs

@@ -0,0 +1,477 @@
+/**
+ * Repo skillset-declaration resolution (#2362, epic #2357).
+ *
+ * The committed, human-owned governance contract lives at the repo
+ * root in `skillrepo.json`, nested under a `skillset` key (design doc
+ * D6 amendment + sub-schema note, 2026-08-07):
+ *
+ *   {
+ *     "skillset": {
+ *       "version": 1,
+ *       "name": "checkout-service",
+ *       "use": "acme/backend-core",
+ *       "extra": ["acme/db-migrations"]
+ *     }
+ *   }
+ *
+ * This module DISCOVERS the declaration (walk-up from cwd) and
+ * VALIDATES it (imperative, fail-closed per D9). It performs no
+ * network work and never writes anything. Resolution against the
+ * server-side skillset entity is H8 (#2365); until that lands, a
+ * well-formed declaration is unresolvable BY DEFINITION and sync
+ * fails closed with the "not yet available" copy below — the error
+ * must never imply the user's file is wrong (H5 design note under D9).
+ *
+ * WALK-UP SEMANTICS (H5 design note under D6, 2026-08-07):
+ *
+ *   - Directories are probed from cwd upward. The walk's boundary is
+ *     the first directory containing `.git` (a directory OR a file —
+ *     worktrees and submodules use a `gitdir:` file), probed
+ *     INCLUSIVE, so the repo root itself is checked and parent repos
+ *     are never consulted. Outside any git repo the walk continues to
+ *     the filesystem root (also inclusive) — ancestor-config
+ *     semantics, same family as `.gitignore`/`.editorconfig`.
+ *   - Exactly ONE `skillrepo.json` may exist on the walk path. Two or
+ *     more is the deferred monorepo-nesting shape and fails closed
+ *     with a "not yet supported" error (the documented FUTURE
+ *     semantic is nearest-file-wins; erroring today holds that door
+ *     open without guessing). Nesting is detected on file PRESENCE,
+ *     not parsed content — a config-only `skillrepo.json` below a
+ *     declared root still errors, because silently picking one of two
+ *     governance-relevant files is exactly the ambiguity D9 forbids.
+ *   - The single file's directory is the DETECTED ROOT. It — not
+ *     cwd — anchors everything repo-scoped that follows: H8's
+ *     skillset-scoped placement writes, D12's realpath-hash state
+ *     key, and (already in H5) the gitignored-declaration probe and
+ *     its warn-on-new seen key. Repos with no declaration keep
+ *     today's cwd-anchored behavior byte-identical (D2).
+ *
+ * A `skillrepo.json` whose top level parses but has NO `skillset` key
+ * is plain tool config, not a declaration — sync proceeds on today's
+ * whole-library path. Unknown TOP-LEVEL keys are tolerated (future
+ * `skillrepo.json` features version themselves); unknown keys INSIDE
+ * the `skillset` block fail closed, because a typo like `"extras"`
+ * silently ignored would mean silently mis-delivering what the user
+ * believes they declared.
+ *
+ * Error class: every fail-closed outcome here throws/carries a
+ * `CliError` with EXIT_UNRESOLVABLE (6) — see errors.mjs for why this
+ * is one code for the whole D9 class rather than a validation error.
+ */
+
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { dirname, join, relative, resolve, isAbsolute } from "node:path";
+
+import { SKILLSET_DECLARATION_FILE } from "./constants.mjs";
+import { unresolvableError } from "./errors.mjs";
+import { escapeControlChars, hasControlChars } from "./file-write.mjs";
+
+/** Top-level key under which the declaration lives (D6 sub-schema). */
+export const DECLARATION_KEY = "skillset";
+
+/**
+ * The declaration-schema version this CLI understands. Versions the
+ * BLOCK, not the whole file — future top-level `skillrepo.json` keys
+ * version themselves (D6 sub-schema note).
+ */
+export const DECLARATION_SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {Object} SkillsetDeclaration
+ * @property {number} version - Declaration-schema version (=== 1).
+ * @property {string} name    - Repo self-declared identity (D12 keys
+ *                              per-repo server state on it).
+ * @property {string} use     - `"owner/skillset-name"` pointer to the
+ *                              server-side named skillset.
+ * @property {string[]} extra - Optional per-repo additions, normalized
+ *                              to `[]` when absent.
+ *
+ * @typedef {Object} DeclarationResolution
+ * @property {"absent" | "config-only" | "declared" | "invalid"} status
+ * @property {string} [filePath] - Absolute path of the found file.
+ *           Present on config-only / declared and on every "invalid"
+ *           outcome EXCEPT multiple-files: with two or more files on
+ *           the walk path there is no single file (and no single
+ *           detected root) to name, so both fields are deliberately
+ *           absent rather than normalized to an arbitrary winner —
+ *           H6/H8 consumers must not assume them on "invalid".
+ * @property {string} [rootDir]  - The DETECTED ROOT: directory of the
+ *           found file. Anchors repo-scoped behavior (see module doc).
+ *           Same multiple-files exception as `filePath`.
+ * @property {import("./errors.mjs").CliError} [error] - Only on
+ *           status "invalid" — the typed EXIT_UNRESOLVABLE error the
+ *           caller throws. Constructed here so copy lives with the
+ *           schema it describes.
+ */
+
+/**
+ * Collect every `skillrepo.json` on the walk path, cwd upward to the
+ * repo boundary (first `.git`-containing dir, inclusive) or the
+ * filesystem root (inclusive). Pure discovery — no parsing.
+ *
+ * Directory entries named `skillrepo.json` are skipped (a directory
+ * cannot be a declaration; probing it as one would fail-close every
+ * sync under a bizarre-but-harmless tree shape).
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Test seam; defaults to process.cwd().
+ * @returns {string[]} Absolute file paths, nearest (cwd-most) first.
+ */
+export function findDeclarationFiles({ cwd = process.cwd() } = {}) {
+  const files = [];
+  let dir = resolve(cwd);
+  for (;;) {
+    const candidate = join(dir, SKILLSET_DECLARATION_FILE);
+    // lstat (never existsSync/stat, which FOLLOW symlinks): a DANGLING
+    // symlink named skillrepo.json must be collected, not skipped —
+    // existsSync reports it false, which silently classified the repo
+    // as undeclared and delivered the whole library (fail-OPEN; the
+    // 2026-08-07 prod-readiness QA audit caught this inverting D9).
+    // A dangling entry flows into resolveDeclaration's readFileSync,
+    // which throws there and routes into the fail-closed cannot-read
+    // branch; a WORKING file symlink reads through like a plain file.
+    let entry = null;
+    try {
+      entry = lstatSync(candidate);
+    } catch {
+      // No directory entry at this path at all.
+    }
+    if (entry && (entry.isFile() || entry.isSymbolicLink())) {
+      files.push(candidate);
+    }
+    // Plain directories (and sockets etc.) stay skipped, as before.
+    // `.git` may be a directory (normal clone) or a file (worktree /
+    // submodule `gitdir:` pointer) — existsSync covers both. The
+    // boundary dir itself was just probed above (inclusive).
+    if (existsSync(join(dir, ".git"))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break; // filesystem root reached (probed above)
+    dir = parent;
+  }
+  return files;
+}
+
+/**
+ * Discover and validate the repo's skillset declaration.
+ *
+ * Read-only and local-only: no network, no writes. Returns a
+ * discriminated resolution rather than throwing so callers on
+ * non-gating paths (e.g. the governance-warning plumbing) can consume
+ * `rootDir` without try/catch; the sync gate throws `resolution.error`
+ * itself.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd] - Test seam; defaults to process.cwd().
+ * @returns {DeclarationResolution}
+ */
+export function resolveDeclaration({ cwd = process.cwd() } = {}) {
+  const files = findDeclarationFiles({ cwd });
+
+  if (files.length === 0) {
+    return { status: "absent" };
+  }
+
+  if (files.length > 1) {
+    // Detection is by file PRESENCE, so one of these may be plain
+    // config rather than a declaration — the copy says "at most one
+    // is supported" instead of branding both as declarations.
+    const shown = files.map((f) => displayPath(f, cwd)).join(", ");
+    return {
+      status: "invalid",
+      error: unresolvableError(
+        `found ${files.length} ${SKILLSET_DECLARATION_FILE} files between this directory and the repository root (${shown}). ` +
+          `At most one is supported today (nested and monorepo declarations are not yet supported), and choosing between them silently could deliver the wrong skillset, so nothing was synced.`,
+        {
+          hint: `Keep a single ${SKILLSET_DECLARATION_FILE} at the repository root and remove the others.`,
+        },
+      ),
+    };
+  }
+
+  const filePath = files[0];
+  const rootDir = dirname(filePath);
+  const shownPath = displayPath(filePath, cwd);
+
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf8");
+  } catch (err) {
+    // The file exists but cannot be read — we cannot rule out a
+    // declaration, so ignoring it could deliver the whole library
+    // into a deliberately-scoped repo (the exact D9 rejection).
+    return {
+      status: "invalid",
+      filePath,
+      rootDir,
+      error: unresolvableError(
+        `cannot read ${shownPath} (${escapeControlChars(err.message)}), so this repository's skillset declaration cannot be checked and nothing was synced.`,
+        { cause: err, hint: `Fix the file's permissions (or its symlink target), or remove it to resume whole-library sync.` },
+      ),
+    };
+  }
+
+  let parsed;
+  try {
+    // Strip a UTF-8 BOM — Windows editors add one and JSON.parse
+    // rejects it (Windows compat is mandatory for CLI work).
+    parsed = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+  } catch (err) {
+    return {
+      status: "invalid",
+      filePath,
+      rootDir,
+      error: unresolvableError(
+        // JSON.parse errors can quote raw file bytes — escape them,
+        // same as the path (#2402 class).
+        `${shownPath} is not valid JSON (${escapeControlChars(err.message)}), so this repository's skillset declaration cannot be read and nothing was synced.`,
+        { cause: err, hint: `Fix the JSON, or remove the file to resume whole-library sync.` },
+      ),
+    };
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return {
+      status: "invalid",
+      filePath,
+      rootDir,
+      error: unresolvableError(
+        `${shownPath} must contain a JSON object at the top level (found ${describeType(parsed)}), so this repository's skillset declaration cannot be read and nothing was synced.`,
+        { hint: `Fix the file, or remove it to resume whole-library sync.` },
+      ),
+    };
+  }
+
+  if (!(DECLARATION_KEY in parsed)) {
+    // Plain tool config — not a declaration. Sync proceeds on the
+    // whole-library path; rootDir still anchors the gitignored probe.
+    return { status: "config-only", filePath, rootDir };
+  }
+
+  const blockError = validateDeclarationBlock(parsed[DECLARATION_KEY], shownPath);
+  if (blockError) {
+    return { status: "invalid", filePath, rootDir, error: blockError };
+  }
+
+  const block = parsed[DECLARATION_KEY];
+  return {
+    status: "declared",
+    filePath,
+    rootDir,
+    declaration: {
+      version: block.version,
+      name: block.name,
+      use: block.use,
+      extra: Array.isArray(block.extra) ? [...block.extra] : [],
+    },
+  };
+}
+
+/**
+ * The pre-H8 dark-shipping error (H5 design note under D9): a
+ * well-formed declaration cannot resolve because skillset delivery
+ * does not exist yet — server feature (H6) and client wiring (H8) are
+ * both unshipped. The copy therefore says "not yet available" and
+ * must NEVER imply the user's file is wrong. H8 replaces the call
+ * site with real resolution; a server-side `harness_unresolvable`
+ * 422 then maps onto this same exit code.
+ *
+ * @param {DeclarationResolution} resolution - A "declared" resolution.
+ * @returns {import("./errors.mjs").CliError}
+ */
+export function declarationUnavailableError(resolution) {
+  // `use` passed shape validation, but it is still file-sourced text
+  // headed for a terminal — escape control characters (#2402 class).
+  const use = escapeControlChars(resolution.declaration.use);
+  return unresolvableError(
+    `this repository declares skillset "${use}" in ${SKILLSET_DECLARATION_FILE}, but skillset delivery is not yet available. ` +
+      `Nothing was synced: a repository that declares a skillset receives only that skillset, never the whole library.`,
+    {
+      hint:
+        `Keep the declaration while your team prepares for skillsets, or remove the ` +
+        `"${DECLARATION_KEY}" block from ${SKILLSET_DECLARATION_FILE} to sync your whole library here.`,
+    },
+  );
+}
+
+// ── Internals ──────────────────────────────────────────────────────────
+
+/**
+ * Fields the version-1 sub-schema defines. Anything else inside the
+ * block fails closed (typo guard — see module doc).
+ */
+const KNOWN_BLOCK_FIELDS = new Set(["version", "name", "use", "extra"]);
+
+
+/**
+ * Validate the `skillset` block against the D6 sub-schema. Returns
+ * null when valid, or the typed EXIT_UNRESOLVABLE error to surface.
+ * These messages DO describe problems with the user's file — that is
+ * exactly their job; only the not-yet-available error above must not.
+ *
+ * @param {unknown} block
+ * @param {string} shownPath - Display path for error copy.
+ * @returns {import("./errors.mjs").CliError | null}
+ */
+function validateDeclarationBlock(block, shownPath) {
+  const fail = (problem, hint) =>
+    unresolvableError(
+      `${shownPath}: ${problem} Nothing was synced — a repository with a skillset declaration only receives its declared skillset once the declaration is valid.`,
+      { hint },
+    );
+
+  if (!block || typeof block !== "object" || Array.isArray(block)) {
+    return fail(
+      `the "${DECLARATION_KEY}" value must be an object (found ${describeType(block)}).`,
+      `Use {"${DECLARATION_KEY}": {"version": 1, "name": "<repo-identity>", "use": "owner/skillset-name"}}.`,
+    );
+  }
+
+  const unknown = Object.keys(block).filter((k) => !KNOWN_BLOCK_FIELDS.has(k));
+  if (unknown.length > 0) {
+    const shown = unknown.map((k) => `"${escapeControlChars(k)}"`).join(", ");
+    return fail(
+      `the "${DECLARATION_KEY}" block has unknown field${unknown.length > 1 ? "s" : ""} ${shown}.`,
+      `Supported fields are "version", "name", "use", and "extra" — check for typos (a misspelled field would otherwise be silently ignored).`,
+    );
+  }
+
+  if (!Number.isInteger(block.version)) {
+    return fail(
+      `the "${DECLARATION_KEY}" block needs an integer "version" field (found ${describeType(block.version)}).`,
+      `Set "version": ${DECLARATION_SCHEMA_VERSION}.`,
+    );
+  }
+  if (block.version !== DECLARATION_SCHEMA_VERSION) {
+    return fail(
+      `declaration schema version ${block.version} is not supported by this CLI (it understands version ${DECLARATION_SCHEMA_VERSION}).`,
+      `Install the latest skillrepo CLI, or set "version": ${DECLARATION_SCHEMA_VERSION} if the file was written by hand.`,
+    );
+  }
+
+  if (typeof block.name !== "string" || block.name.trim() === "") {
+    return fail(
+      `the "${DECLARATION_KEY}" block needs a non-empty string "name" field (found ${describeType(block.name)}) — it is this repository's self-declared identity.`,
+      `Set "name" to a stable identifier for this repository, e.g. "checkout-service".`,
+    );
+  }
+  // Control characters (C0/DEL/C1, the canonical file-write.mjs
+  // class) are never valid in an identifier — no legitimate repo
+  // identity or owner/name contains them, and letting them through
+  // would defer a certain rejection to copy that blames the wrong
+  // thing ("not yet available"). Rejected up front with an honest
+  // message; still escaped wherever echoed (#2402 class).
+  if (hasControlChars(block.name)) {
+    return fail(
+      `the "name" field ("${escapeControlChars(block.name)}") contains control characters, which are never valid in an identifier.`,
+      `Set "name" to a plain identifier for this repository, e.g. "checkout-service".`,
+    );
+  }
+
+  const useError = validatePointer(block.use, "use", fail);
+  if (useError) return useError;
+
+  if (block.extra !== undefined) {
+    if (!Array.isArray(block.extra)) {
+      return fail(
+        `the "extra" field must be an array of "owner/skill" strings (found ${describeType(block.extra)}).`,
+        `Use "extra": ["owner/skill", ...], or remove the field.`,
+      );
+    }
+    for (let i = 0; i < block.extra.length; i++) {
+      const entryError = validatePointer(block.extra[i], `extra[${i}]`, fail);
+      if (entryError) return entryError;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Shared shape check for the `use` pointer and each `extra` entry:
+ * a non-empty `"owner/name"` string with exactly one slash and no
+ * reserved `@` version syntax (D3 reservation).
+ *
+ * @param {unknown} value
+ * @param {string} field - Field label for error copy.
+ * @param {(problem: string, hint: string) => import("./errors.mjs").CliError} fail
+ * @returns {import("./errors.mjs").CliError | null}
+ */
+function validatePointer(value, field, fail) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return fail(
+      `the "${field}" field must be a non-empty "owner/name" string (found ${describeType(value)}).`,
+      field === "use"
+        ? `Set "use" to the skillset this repository runs, e.g. "acme/backend-core".`
+        : `Each "extra" entry names one library skill, e.g. "acme/db-migrations".`,
+    );
+  }
+  const shown = escapeControlChars(value);
+  if (hasControlChars(value)) {
+    return fail(
+      `"${field}": "${shown}" contains control characters, which are never valid in an owner/name identifier.`,
+      field === "use"
+        ? `Set "use" to the skillset this repository runs, e.g. "acme/backend-core".`
+        : `Each "extra" entry names one library skill, e.g. "acme/db-migrations".`,
+    );
+  }
+  if (value.includes("@")) {
+    // D3: one version-control point in v1 (the library pin). The
+    // `@range` syntax is reserved, not silently ignored.
+    return fail(
+      `"${field}": "${shown}" uses "@" version syntax, which is not yet supported — versions are controlled by library pins in v1.`,
+      `Remove the "@..." suffix; the approved version is decided in your library.`,
+    );
+  }
+  const slashAt = value.indexOf("/");
+  if (slashAt <= 0 || slashAt !== value.lastIndexOf("/") || slashAt === value.length - 1) {
+    return fail(
+      `"${field}": "${shown}" must have the form "owner/name" (one slash, both parts non-empty).`,
+      field === "use"
+        ? `Set "use" to the skillset this repository runs, e.g. "acme/backend-core".`
+        : `Each "extra" entry names one library skill, e.g. "acme/db-migrations".`,
+    );
+  }
+  return null;
+}
+
+/**
+ * Human-facing path for error copy: relative to cwd when the file is
+ * at or below it (the common run-at-root case reads as plain
+ * `skillrepo.json`), absolute otherwise — a `../../..`-chain is worse
+ * than an absolute path.
+ *
+ * Control characters are escaped HERE, at the single point display
+ * paths are produced: every segment comes from real directory names
+ * on disk — filesystem-sourced, attacker-influenceable strings (a
+ * cloned repo chooses its own directory names), the exact #2402
+ * injection class — and the messages carrying them are printed
+ * verbatim by the dispatcher and the session-hook one-liner.
+ *
+ * @param {string} filePath - Absolute path.
+ * @param {string} cwd
+ * @returns {string}
+ */
+function displayPath(filePath, cwd) {
+  const rel = relative(resolve(cwd), filePath);
+  if (rel === "") return SKILLSET_DECLARATION_FILE;
+  if (rel.startsWith("..") || isAbsolute(rel)) return escapeControlChars(filePath);
+  return escapeControlChars(rel);
+}
+
+/**
+ * Type description for error copy. Distinguishes null and arrays from
+ * plain objects because "found object" for a null is actively
+ * misleading in a JSON context.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeType(value) {
+  if (value === null) return "null";
+  if (value === undefined) return "nothing";
+  if (Array.isArray(value)) return "an array";
+  if (typeof value === "string") return "a string";
+  if (typeof value === "number") return "a number";
+  if (typeof value === "boolean") return "a boolean";
+  return `${typeof value === "object" ? "an" : "a"} ${typeof value}`;
+}