@csark0812/skeleton 1.5.5 → 1.5.7

package/dist/cli.js

@@ -3037,6 +3037,7 @@ var require_utils = __commonJS((exports, module) => {
   var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
   var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
   var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
+  var isQueryFragmentCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/?]$/iu);
   function stringArrayToHexStripped(input) {
     let acc = "";
     let code = 0;
@@ -3180,7 +3181,7 @@ var require_utils = __commonJS((exports, module) => {
             continue;
           }
         } else if (input[0] === "/") {
-          if (input[1] === "." || input[1] === "/") {
+          if (input[1] === ".") {
             output.push("/");
             break;
           }
@@ -3262,10 +3263,30 @@ var require_utils = __commonJS((exports, module) => {
     }
     return output;
   }
+  var BYTE_HEX = new Array(256);
+  {
+    const HEX_DIGITS = "0123456789ABCDEF";
+    for (let i = 0;i < 256; i++) {
+      BYTE_HEX[i] = "%" + HEX_DIGITS[i >> 4] + HEX_DIGITS[i & 15];
+    }
+  }
+  function isEscapeSafe(cp) {
+    return cp >= 48 && cp <= 57 || cp >= 65 && cp <= 90 || cp >= 97 && cp <= 122 || cp === 42 || cp === 43 || cp === 45 || cp === 46 || cp === 47 || cp === 64 || cp === 95;
+  }
+  function percentEncodeNonAscii(cp) {
+    if (cp < 2048) {
+      return BYTE_HEX[192 | cp >> 6] + BYTE_HEX[128 | cp & 63];
+    }
+    if (cp < 65536) {
+      return BYTE_HEX[224 | cp >> 12] + BYTE_HEX[128 | cp >> 6 & 63] + BYTE_HEX[128 | cp & 63];
+    }
+    return BYTE_HEX[240 | cp >> 18] + BYTE_HEX[128 | cp >> 12 & 63] + BYTE_HEX[128 | cp >> 6 & 63] + BYTE_HEX[128 | cp & 63];
+  }
   function normalizePathEncoding(input) {
     let output = "";
     for (let i = 0;i < input.length; i++) {
-      if (input[i] === "%" && i + 2 < input.length) {
+      const ch = input[i];
+      if (ch === "%" && i + 2 < input.length) {
         const hex = input.slice(i + 1, i + 3);
         if (isHexPair(hex)) {
           const normalizedHex = hex.toUpperCase();
@@ -3279,10 +3300,66 @@ var require_utils = __commonJS((exports, module) => {
           continue;
         }
       }
-      if (isPathCharacter(input[i])) {
-        output += input[i];
+      if (isPathCharacter(ch)) {
+        output += ch;
+      } else {
+        const code = input.charCodeAt(i);
+        if (code < 128) {
+          output += isEscapeSafe(code) ? ch : BYTE_HEX[code];
+        } else if (code < 55296 || code > 57343) {
+          output += percentEncodeNonAscii(code);
+        } else if (code <= 56319 && i + 1 < input.length) {
+          const low = input.charCodeAt(i + 1);
+          if (low >= 56320 && low <= 57343) {
+            output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+            i++;
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
+        } else {
+          output += percentEncodeNonAscii(65533);
+        }
+      }
+    }
+    return output;
+  }
+  function normalizeQueryFragmentEncoding(input) {
+    let output = "";
+    for (let i = 0;i < input.length; i++) {
+      const ch = input[i];
+      if (ch === "%" && i + 2 < input.length) {
+        const hex = input.slice(i + 1, i + 3);
+        if (isHexPair(hex)) {
+          const normalizedHex = hex.toUpperCase();
+          const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+          if (isUnreserved(decoded)) {
+            output += decoded;
+          } else {
+            output += "%" + normalizedHex;
+          }
+          i += 2;
+          continue;
+        }
+      }
+      if (isQueryFragmentCharacter(ch)) {
+        output += ch;
       } else {
-        output += escape(input[i]);
+        const code = input.charCodeAt(i);
+        if (code < 128) {
+          output += isEscapeSafe(code) ? ch : BYTE_HEX[code];
+        } else if (code < 55296 || code > 57343) {
+          output += percentEncodeNonAscii(code);
+        } else if (code <= 56319 && i + 1 < input.length) {
+          const low = input.charCodeAt(i + 1);
+          if (low >= 56320 && low <= 57343) {
+            output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+            i++;
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
+        } else {
+          output += percentEncodeNonAscii(65533);
+        }
       }
     }
     return output;
@@ -3290,7 +3367,8 @@ var require_utils = __commonJS((exports, module) => {
   function escapePreservingEscapes(input) {
     let output = "";
     for (let i = 0;i < input.length; i++) {
-      if (input[i] === "%" && i + 2 < input.length) {
+      const ch = input[i];
+      if (ch === "%" && i + 2 < input.length) {
         const hex = input.slice(i + 1, i + 3);
         if (isHexPair(hex)) {
           output += "%" + hex.toUpperCase();
@@ -3298,7 +3376,22 @@ var require_utils = __commonJS((exports, module) => {
           continue;
         }
       }
-      output += escape(input[i]);
+      const code = input.charCodeAt(i);
+      if (code < 128) {
+        output += isEscapeSafe(code) ? ch : BYTE_HEX[code];
+      } else if (code < 55296 || code > 57343) {
+        output += percentEncodeNonAscii(code);
+      } else if (code <= 56319 && i + 1 < input.length) {
+        const low = input.charCodeAt(i + 1);
+        if (low >= 56320 && low <= 57343) {
+          output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+          i++;
+        } else {
+          output += percentEncodeNonAscii(65533);
+        }
+      } else {
+        output += percentEncodeNonAscii(65533);
+      }
     }
     return output;
   }
@@ -3332,6 +3425,7 @@ var require_utils = __commonJS((exports, module) => {
     reescapeHostDelimiters,
     normalizePercentEncoding,
     normalizePathEncoding,
+    normalizeQueryFragmentEncoding,
     escapePreservingEscapes,
     removeDotSegments,
     isIPv4,
@@ -3517,7 +3611,7 @@ var require_schemes = __commonJS((exports, module) => {
 
 // node_modules/fast-uri/index.js
 var require_fast_uri = __commonJS((exports, module) => {
-  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
+  var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, normalizeQueryFragmentEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
   var { SCHEMES, getSchemeHandler } = require_schemes();
   function normalize(uri, options) {
     if (typeof uri === "string") {
@@ -3529,7 +3623,12 @@ var require_fast_uri = __commonJS((exports, module) => {
   }
   function resolve(baseURI, relativeURI, options) {
     const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-    const resolved = resolveComponent(parse(baseURI, schemelessOptions), parse(relativeURI, schemelessOptions), schemelessOptions, true);
+    const { parsed: baseParsed, malformedAuthorityOrPort: baseMalformed } = parseWithStatus(baseURI, schemelessOptions);
+    const { parsed: relativeParsed, malformedAuthorityOrPort: relativeMalformed } = parseWithStatus(relativeURI, schemelessOptions);
+    if (baseMalformed || relativeMalformed) {
+      throw new Error(baseParsed.error || relativeParsed.error || "URI is malformed.");
+    }
+    const resolved = resolveComponent(baseParsed, relativeParsed, schemelessOptions, true);
     schemelessOptions.skipEscape = true;
     return serialize(resolved, schemelessOptions);
   }
@@ -3655,6 +3754,8 @@ var require_fast_uri = __commonJS((exports, module) => {
     return uriTokens.join("");
   }
   var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+  var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
+  var AUTHORITY_INTRODUCER_REGION = /^(?:[^#/:?]+:)?([/\\\t\n\r]*)/;
   function getParseError(parsed, matches) {
     if (matches[2] !== undefined && parsed.path && parsed.path[0] !== "/") {
       return 'URI path must start with "/" when authority is present.';
@@ -3684,9 +3785,28 @@ var require_fast_uri = __commonJS((exports, module) => {
         uri = "//" + uri;
       }
     }
+    const authorityMatch = uri.match(AUTHORITY_PREFIX);
+    if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+      parsed.error = "URI authority must not contain a literal backslash.";
+      malformedAuthorityOrPort = true;
+    }
+    const introducerMatch = uri.match(AUTHORITY_INTRODUCER_REGION);
+    if (introducerMatch !== null) {
+      const region = introducerMatch[1];
+      const normalizedRegion = region.replace(/[\t\n\r]/g, "");
+      if (normalizedRegion.length >= 2) {
+        if (normalizedRegion.slice(0, 2) !== "//") {
+          parsed.error = parsed.error || "URI authority must not contain a literal backslash.";
+          malformedAuthorityOrPort = true;
+        } else if (region.length !== normalizedRegion.length) {
+          parsed.error = parsed.error || "URI authority introducer must not contain whitespace.";
+          malformedAuthorityOrPort = true;
+        }
+      }
+    }
     const matches = uri.match(URI_PARSE);
     if (matches) {
-      parsed.scheme = matches[1];
+      parsed.scheme = matches[1] === undefined ? undefined : matches[1].toLowerCase();
       parsed.userinfo = matches[3];
       parsed.host = matches[4];
       parsed.port = parseInt(matches[5], 10);
@@ -3745,12 +3865,11 @@ var require_fast_uri = __commonJS((exports, module) => {
         if (parsed.path) {
           parsed.path = normalizePathEncoding(parsed.path);
         }
+        if (parsed.query) {
+          parsed.query = normalizeQueryFragmentEncoding(parsed.query);
+        }
         if (parsed.fragment) {
-          try {
-            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
-          } catch {
-            parsed.error = parsed.error || "URI malformed";
-          }
+          parsed.fragment = normalizeQueryFragmentEncoding(parsed.fragment);
         }
       }
       if (schemeHandler && schemeHandler.parse) {
@@ -15653,11 +15772,13 @@ var require_extend = __commonJS((exports, module) => {
 
 // src/cli.ts
 import { readFileSync as readFileSync22 } from "node:fs";
+import process7 from "node:process";
 
 // src/audit/config/load.ts
 var import_ajv = __toESM(require_ajv(), 1);
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import process2 from "node:process";
 import { fileURLToPath } from "node:url";
 
 // node_modules/yaml/dist/index.js
@@ -15745,7 +15866,7 @@ function isExternalLink(target) {
   return EXTERNAL_LINK_RE.test(target);
 }
 function isPlaceholderLink(target) {
-  return !target.includes("/") && !target.includes(".") && !target.startsWith("#");
+  return !(target.includes("/") || target.includes(".") || target.startsWith("#"));
 }
 function escapeRegexLiteral(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -15826,7 +15947,7 @@ var COVERAGE_BUILTIN_EXCLUDES = [
   "**/fixtures/**",
   "templates/**"
 ];
-function findRepoRoot(startDir = process.cwd()) {
+function findRepoRoot(startDir = process2.cwd()) {
   let dir = startDir;
   while (true) {
     if (existsSync(join(dir, ".skeleton", "config.yaml")))
@@ -16861,6 +16982,44 @@ function assertUnderSkeleton(root, absPath) {
 }
 
 // src/plugins/load.ts
+function rulesAgree(a, b) {
+  return a.length === b.length && !a.some((rule, i) => rule.id !== b[i]?.id || rule.run !== b[i]?.run);
+}
+function policiesAgree(a, b) {
+  return Array.isArray(a) && Array.isArray(b) && a.length === b.length && !a.some((p, i) => p !== b[i]);
+}
+function resolveRules(defaultRules, namedRules) {
+  if (defaultRules !== undefined && namedRules !== undefined && !rulesAgree(defaultRules, namedRules)) {
+    throw new Error("Plugin exports disagree on rules: default and named `rules` must match when both are set");
+  }
+  return defaultRules ?? namedRules;
+}
+function resolvePolicies(defaultPolicies, namedPolicies) {
+  if (defaultPolicies !== undefined && namedPolicies !== undefined && !policiesAgree(defaultPolicies, namedPolicies)) {
+    throw new Error("Plugin exports disagree on policies: default and named `policies` must match when both are set");
+  }
+  return defaultPolicies ?? namedPolicies;
+}
+function validateRules(rules) {
+  for (const rule of rules) {
+    if (!rule || typeof rule.id !== "string" || typeof rule.run !== "function") {
+      throw new Error("Plugin rules must each have string id and run()");
+    }
+  }
+}
+function validatePolicies(policies) {
+  if (policies === undefined)
+    return;
+  if (!Array.isArray(policies) || policies.some((p) => typeof p !== "string")) {
+    throw new Error("Plugin policies must be string[] (globs relative to .skeleton/) — got non-array");
+  }
+}
+function readDefaultExport(record) {
+  const value = record.default;
+  if (!("default" in record) || typeof value !== "object" || value === null)
+    return null;
+  return value;
+}
 function normalizeExport(mod) {
   if (!mod || typeof mod !== "object") {
     throw new Error("Plugin module must export { rules: AuditRule[]; policies?: string[] }");
@@ -16868,44 +17027,17 @@ function normalizeExport(mod) {
   const record = mod;
   const namedRules = Array.isArray(record.rules) ? record.rules : undefined;
   const namedPoliciesRaw = "policies" in record ? record.policies : undefined;
-  const def = "default" in record && record.default && typeof record.default === "object" ? record.default : null;
+  const def = readDefaultExport(record);
   const defaultRules = def && Array.isArray(def.rules) ? def.rules : undefined;
   const defaultPoliciesRaw = def && "policies" in def ? def.policies : undefined;
-  let rules;
-  if (defaultRules !== undefined && namedRules !== undefined) {
-    if (defaultRules.length !== namedRules.length || defaultRules.some((rule, i) => rule.id !== namedRules[i]?.id || rule.run !== namedRules[i]?.run)) {
-      throw new Error("Plugin exports disagree on rules: default and named `rules` must match when both are set");
-    }
-    rules = defaultRules;
-  } else {
-    rules = defaultRules ?? namedRules;
-  }
-  let policies;
-  if (defaultPoliciesRaw !== undefined && namedPoliciesRaw !== undefined) {
-    if (!Array.isArray(defaultPoliciesRaw) || !Array.isArray(namedPoliciesRaw) || defaultPoliciesRaw.length !== namedPoliciesRaw.length || defaultPoliciesRaw.some((p, i) => p !== namedPoliciesRaw[i])) {
-      throw new Error("Plugin exports disagree on policies: default and named `policies` must match when both are set");
-    }
-    policies = defaultPoliciesRaw;
-  } else {
-    policies = defaultPoliciesRaw ?? namedPoliciesRaw;
-  }
+  const rules = resolveRules(defaultRules, namedRules);
+  const policies = resolvePolicies(defaultPoliciesRaw, namedPoliciesRaw);
   if (!Array.isArray(rules)) {
     throw new Error("Plugin module must export { rules: AuditRule[]; policies?: string[] }");
   }
-  for (const rule of rules) {
-    if (!rule || typeof rule.id !== "string" || typeof rule.run !== "function") {
-      throw new Error("Plugin rules must each have string id and run()");
-    }
-  }
-  if (policies !== undefined) {
-    if (!Array.isArray(policies) || policies.some((p) => typeof p !== "string")) {
-      throw new Error("Plugin policies must be string[] (globs relative to .skeleton/) — got non-array");
-    }
-  }
-  return {
-    rules,
-    policies
-  };
+  validateRules(rules);
+  validatePolicies(policies);
+  return { rules, policies };
 }
 function expandPolicyGlobs(root, globs) {
   const base = skeletonDir(root);
@@ -16940,20 +17072,23 @@ function loadPoliciesFromGlobs(root, globs) {
   }
   return policies;
 }
+async function importBuiltPlugin(root, entry) {
+  const tsAbs = resolvePluginTsPath(root, entry);
+  const mjsAbs = mjsPathForTs(tsAbs);
+  if (!existsSync4(mjsAbs)) {
+    const rel = relative2(skeletonDir(root), tsAbs) || entry;
+    throw new Error(`Plugin not built: ${rel} (missing ${relative2(root, mjsAbs) || mjsAbs}). Run: skeleton build-plugin`);
+  }
+  const mod = await import(pathToFileURL(mjsAbs).href);
+  return normalizeExport(mod);
+}
 async function collectWiredPolicyRelPaths(root, config) {
   const entries = config.plugins ?? [];
   const wired = new Set;
   if (entries.length === 0)
     return wired;
   for (const entry of entries) {
-    const tsAbs = resolvePluginTsPath(root, entry);
-    const mjsAbs = mjsPathForTs(tsAbs);
-    if (!existsSync4(mjsAbs)) {
-      const rel = relative2(skeletonDir(root), tsAbs) || entry;
-      throw new Error(`Plugin not built: ${rel} (missing ${relative2(root, mjsAbs) || mjsAbs}). Run: skeleton build-plugin`);
-    }
-    const mod = await import(pathToFileURL(mjsAbs).href);
-    const normalized = normalizeExport(mod);
+    const normalized = await importBuiltPlugin(root, entry);
     if (!normalized.policies?.length)
       continue;
     for (const abs of expandPolicyGlobs(root, normalized.policies)) {
@@ -16970,14 +17105,7 @@ async function loadPlugins(root, config) {
   const rules = [];
   const policies = [];
   for (const entry of entries) {
-    const tsAbs = resolvePluginTsPath(root, entry);
-    const mjsAbs = mjsPathForTs(tsAbs);
-    if (!existsSync4(mjsAbs)) {
-      const rel = relative2(skeletonDir(root), tsAbs) || entry;
-      throw new Error(`Plugin not built: ${rel} (missing ${relative2(root, mjsAbs) || mjsAbs}). Run: skeleton build-plugin`);
-    }
-    const mod = await import(pathToFileURL(mjsAbs).href);
-    const normalized = normalizeExport(mod);
+    const normalized = await importBuiltPlugin(root, entry);
     rules.push(...normalized.rules);
     if (normalized.policies?.length) {
       policies.push(...loadPoliciesFromGlobs(root, normalized.policies));
@@ -17001,6 +17129,39 @@ var DEFAULT_SKILLS_LOCKFILE = "skills-lock.json";
 function isForeignLockSourceType(sourceType) {
   return sourceType !== "local";
 }
+function parseLockSkillEntry(input) {
+  const { lockfileRel, slug, value, warnings } = input;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    warnings.push(`${lockfileRel}: skill "${slug}" has invalid entry`);
+    return null;
+  }
+  const entry = value;
+  const source = entry.source;
+  const sourceType = entry.sourceType;
+  if (typeof source !== "string" || source.length === 0) {
+    warnings.push(`${lockfileRel}: skill "${slug}" missing source`);
+    return null;
+  }
+  if (typeof sourceType !== "string" || sourceType.length === 0) {
+    warnings.push(`${lockfileRel}: skill "${slug}" missing sourceType`);
+    return null;
+  }
+  const parsed = { source, sourceType };
+  if (typeof entry.skillPath === "string")
+    parsed.skillPath = entry.skillPath;
+  if (typeof entry.computedHash === "string")
+    parsed.computedHash = entry.computedHash;
+  return parsed;
+}
+function parseLockSkills(lockfileRel, skillsRaw, warnings) {
+  const entries = {};
+  for (const [slug, value] of Object.entries(skillsRaw)) {
+    const parsed = parseLockSkillEntry({ lockfileRel, slug, value, warnings });
+    if (parsed)
+      entries[slug] = parsed;
+  }
+  return entries;
+}
 function loadSkillsLock(root, lockfileRel = DEFAULT_SKILLS_LOCKFILE) {
   const warnings = [];
   const abs = join4(root, lockfileRel);
@@ -17028,31 +17189,11 @@ function loadSkillsLock(root, lockfileRel = DEFAULT_SKILLS_LOCKFILE) {
     warnings.push(`${lockfileRel}: missing or invalid "skills" object`);
     return { lockfile: lockfileRel, entries: {}, warnings };
   }
-  const entries = {};
-  for (const [slug, value] of Object.entries(skillsRaw)) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-      warnings.push(`${lockfileRel}: skill "${slug}" has invalid entry`);
-      continue;
-    }
-    const entry = value;
-    const source = entry.source;
-    const sourceType = entry.sourceType;
-    if (typeof source !== "string" || source.length === 0) {
-      warnings.push(`${lockfileRel}: skill "${slug}" missing source`);
-      continue;
-    }
-    if (typeof sourceType !== "string" || sourceType.length === 0) {
-      warnings.push(`${lockfileRel}: skill "${slug}" missing sourceType`);
-      continue;
-    }
-    const parsed = { source, sourceType };
-    if (typeof entry.skillPath === "string")
-      parsed.skillPath = entry.skillPath;
-    if (typeof entry.computedHash === "string")
-      parsed.computedHash = entry.computedHash;
-    entries[slug] = parsed;
-  }
-  return { lockfile: lockfileRel, entries, warnings };
+  return {
+    lockfile: lockfileRel,
+    entries: parseLockSkills(lockfileRel, skillsRaw, warnings),
+    warnings
+  };
 }
 function classifySkillOwnership(slug, provenance, ownership) {
   const ownedOverrides = new Set(ownership?.ownedSlugs ?? []);
@@ -17111,7 +17252,7 @@ function listNestedSlugs(root, relRoot) {
   const absRoot = join5(root, relRoot);
   if (!existsSync6(absRoot))
     return [];
-  return readdirSync2(absRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NESTED_EXCLUDED_DIRS.has(entry.name)).filter((entry) => existsSync6(join5(absRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort();
+  return readdirSync2(absRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && !NESTED_EXCLUDED_DIRS.has(entry.name)).filter((entry) => existsSync6(join5(absRoot, entry.name, "SKILL.md"))).map((entry) => entry.name).sort((a, b) => a.localeCompare(b));
 }
 function listFlatSlugs(root) {
   const slugs = [];
@@ -17124,34 +17265,46 @@ function listFlatSlugs(root) {
       slugs.push(entry.name);
     }
   }
-  return slugs.sort();
+  return slugs.sort((a, b) => a.localeCompare(b));
+}
+function shouldSkipAgentsRoot(root, relRoot, claudeReal) {
+  if (relRoot !== ".agents/skills" || !claudeReal)
+    return false;
+  const abs = join5(root, relRoot);
+  const agentsReal = safeRealpath(abs);
+  if (agentsReal && agentsReal === claudeReal)
+    return true;
+  const linkTarget = safeRealpath(abs);
+  if (linkTarget === claudeReal)
+    return true;
+  try {
+    const link = readlinkSync(abs);
+    if (link && safeRealpath(join5(root, link)) === claudeReal)
+      return true;
+  } catch {}
+  return false;
+}
+function addNestedSkillRoot(input) {
+  const { roots, root, relRoot } = input;
+  let { claudeReal } = input;
+  const abs = join5(root, relRoot);
+  if (!existsSync6(abs))
+    return claudeReal;
+  if (relRoot === ".claude/skills") {
+    claudeReal = safeRealpath(abs);
+  }
+  if (shouldSkipAgentsRoot(root, relRoot, claudeReal))
+    return claudeReal;
+  if (listNestedSlugs(root, relRoot).length > 0 || existsSync6(abs)) {
+    roots.push({ kind: "nested", relPath: relRoot });
+  }
+  return claudeReal;
 }
 function detectSkillRoots(root) {
   const roots = [];
   let claudeReal = null;
   for (const relRoot of NESTED_SKILL_ROOTS) {
-    const abs = join5(root, relRoot);
-    if (!existsSync6(abs))
-      continue;
-    if (relRoot === ".claude/skills") {
-      claudeReal = safeRealpath(abs);
-    }
-    if (relRoot === ".agents/skills" && claudeReal) {
-      const agentsReal = safeRealpath(abs);
-      if (agentsReal && agentsReal === claudeReal)
-        continue;
-      const linkTarget = safeRealpath(abs);
-      if (linkTarget === claudeReal)
-        continue;
-      try {
-        const link = readlinkSync(abs);
-        if (link && claudeReal && safeRealpath(join5(root, link)) === claudeReal)
-          continue;
-      } catch {}
-    }
-    if (listNestedSlugs(root, relRoot).length > 0 || existsSync6(abs)) {
-      roots.push({ kind: "nested", relPath: relRoot });
-    }
+    claudeReal = addNestedSkillRoot({ roots, root, relRoot, claudeReal });
   }
   const flatSlugs = listFlatSlugs(root);
   if (flatSlugs.length > 0) {
@@ -17193,22 +17346,30 @@ function resolveSkillPath(index, root, slug) {
 function isSkillPath(relPath, index) {
   return skillSlugForPath(relPath, index) !== null;
 }
+function nestedSlugForPath(normalized, skillRoot, index) {
+  const prefix = `${skillRoot.relPath}/`;
+  if (!normalized.startsWith(prefix))
+    return null;
+  const slug = normalized.slice(prefix.length).split("/")[0];
+  return slug && index.slugs.includes(slug) ? slug : null;
+}
+function flatSlugForPath(normalized, index) {
+  const flat = new Set(index.flatSlugs);
+  const first = normalized.split("/")[0];
+  return first && flat.has(first) ? first : null;
+}
 function skillSlugForPath(relPath, index) {
   const normalized = normalizeRelPath(relPath);
-  const flat = new Set(index.flatSlugs);
   for (const skillRoot of index.roots) {
     if (skillRoot.kind === "nested") {
-      const prefix = `${skillRoot.relPath}/`;
-      if (!normalized.startsWith(prefix))
-        continue;
-      const slug = normalized.slice(prefix.length).split("/")[0];
-      if (slug && index.slugs.includes(slug))
-        return slug;
+      const slug2 = nestedSlugForPath(normalized, skillRoot, index);
+      if (slug2)
+        return slug2;
       continue;
     }
-    const first = normalized.split("/")[0];
-    if (first && flat.has(first))
-      return first;
+    const slug = flatSlugForPath(normalized, index);
+    if (slug)
+      return slug;
   }
   return null;
 }
@@ -17249,46 +17410,54 @@ function slugFromPath(filePath, workspaceRoot) {
   }
   return flatSlug;
 }
+function augmentPatternsForRoot(skillRoot, index, owned) {
+  if (skillRoot.kind === "nested") {
+    return index.ownedSlugs.map((slug) => `${skillRoot.relPath}/${slug}/**`);
+  }
+  return index.flatSlugs.filter((slug) => owned.has(slug)).map((slug) => `${slug}/**`);
+}
 function skillCollectAugments(index) {
   const owned = new Set(index.ownedSlugs);
   const patterns = [];
   for (const skillRoot of index.roots) {
-    if (skillRoot.kind === "nested") {
-      for (const slug of index.ownedSlugs) {
-        patterns.push(`${skillRoot.relPath}/${slug}/**`);
-      }
-    } else {
-      for (const slug of index.flatSlugs) {
-        if (!owned.has(slug))
-          continue;
-        patterns.push(`${slug}/**`);
-      }
-    }
+    patterns.push(...augmentPatternsForRoot(skillRoot, index, owned));
   }
   return patterns;
 }
+function markdownPathsForSkillDir(root, absDir) {
+  const paths = [];
+  for (const abs of globSync("**/*.{md,mdc}", {
+    cwd: absDir,
+    absolute: true,
+    onlyFiles: true,
+    dot: true
+  })) {
+    paths.push(normalizeRelPath(relative3(root, abs)));
+  }
+  return paths;
+}
+function markdownPathsForRoot(root, skillRoot, owned) {
+  const paths = [];
+  const slugs = skillRoot.kind === "nested" ? listNestedSlugs(root, skillRoot.relPath) : listFlatSlugs(root);
+  for (const slug of slugs) {
+    if (!owned.has(slug))
+      continue;
+    const absDir = skillRoot.kind === "nested" ? join5(root, skillRoot.relPath, slug) : join5(root, slug);
+    if (!existsSync6(absDir))
+      continue;
+    paths.push(...markdownPathsForSkillDir(root, absDir));
+  }
+  return paths;
+}
 function listSkillMarkdownPaths(root, index) {
   const owned = new Set(index.ownedSlugs);
   const paths = new Set;
   for (const skillRoot of index.roots) {
-    const slugs = skillRoot.kind === "nested" ? listNestedSlugs(root, skillRoot.relPath) : listFlatSlugs(root);
-    for (const slug of slugs) {
-      if (!owned.has(slug))
-        continue;
-      const absDir = skillRoot.kind === "nested" ? join5(root, skillRoot.relPath, slug) : join5(root, slug);
-      if (!existsSync6(absDir))
-        continue;
-      for (const abs of globSync("**/*.{md,mdc}", {
-        cwd: absDir,
-        absolute: true,
-        onlyFiles: true,
-        dot: true
-      })) {
-        paths.add(normalizeRelPath(relative3(root, abs)));
-      }
+    for (const rel of markdownPathsForRoot(root, skillRoot, owned)) {
+      paths.add(rel);
     }
   }
-  return [...paths].sort();
+  return [...paths].sort((a, b) => a.localeCompare(b));
 }
 function listSkillSlugs(index) {
   return index.slugs;
@@ -17306,6 +17475,24 @@ function isMarkdownFile(absPath) {
 function shouldExclude(relPath, exclude) {
   return exclude.some((pattern) => matchesGlobScope(relPath, pattern));
 }
+function rememberMarkdownFile(input) {
+  const { byReal, root, abs, exclude } = input;
+  if (!isMarkdownFile(abs))
+    return;
+  const rel = normalizeRelPath(relative4(root, abs));
+  if (shouldExclude(rel, exclude))
+    return;
+  let real;
+  try {
+    real = realpathSync4(abs);
+  } catch {
+    real = abs;
+  }
+  const existing = byReal.get(real);
+  if (existing === undefined || abs === real && existing !== real) {
+    byReal.set(real, abs);
+  }
+}
 function expandPatterns(root, patterns, exclude) {
   const byReal = new Map;
   for (const pattern of patterns) {
@@ -17313,23 +17500,10 @@ function expandPatterns(root, patterns, exclude) {
       cwd: root,
       absolute: true,
       onlyFiles: true,
-      dot: true
+      dot: true,
+      ignore: exclude
     })) {
-      if (!isMarkdownFile(abs))
-        continue;
-      const rel = normalizeRelPath(relative4(root, abs));
-      if (shouldExclude(rel, exclude))
-        continue;
-      let real;
-      try {
-        real = realpathSync4(abs);
-      } catch {
-        real = abs;
-      }
-      const existing = byReal.get(real);
-      if (existing === undefined || abs === real && existing !== real) {
-        byReal.set(real, abs);
-      }
+      rememberMarkdownFile({ byReal, root, abs, exclude });
     }
   }
   return [...byReal.values()];
@@ -17358,7 +17532,8 @@ function collectBannedFiles(config, root) {
       cwd: root,
       absolute: true,
       onlyFiles: true,
-      dot: false
+      dot: false,
+      ignore: exclude
     })) {
       const rel = normalizeRelPath(relative4(root, abs));
       if (shouldExclude(rel, exclude))
@@ -17375,7 +17550,8 @@ function collectCoverageCandidateFiles(root, exclude) {
       cwd: root,
       absolute: true,
       onlyFiles: true,
-      dot: false
+      dot: false,
+      ignore: exclude
     })) {
       const rel = normalizeRelPath(relative4(root, abs));
       if (shouldExclude(rel, exclude))
@@ -17390,31 +17566,41 @@ function excludeForeignSkillDocMetaPaths(docMetaPaths, skillIndex) {
     return docMetaPaths;
   return docMetaPaths.filter((rel) => !isForeignSkillPath(rel, skillIndex));
 }
-function collectDocMetaPaths(config, root, registryPaths, skillIndex) {
+function collectRegistryDocMeta(ctx) {
   const paths = [];
-  for (const abs of expandPatterns(root, ["docs/*/README.md"], mergedExcludes(config))) {
-    paths.push(normalizeRelPath(relative4(root, abs)));
-  }
-  const extras = ["docs/README.md", ".skeleton/registry.md"];
-  for (const file of extras) {
-    const abs = join6(root, file);
-    if (existsSync7(abs))
-      paths.push(normalizeRelPath(file));
-  }
-  for (const rel of registryPaths) {
-    if (!rel.endsWith(".md") && !rel.endsWith(".mdc"))
+  for (const rel of ctx.registryPaths) {
+    if (!(rel.endsWith(".md") || rel.endsWith(".mdc")))
       continue;
-    const abs = join6(root, rel);
+    const abs = join6(ctx.root, rel);
     if (existsSync7(abs))
       paths.push(normalizeRelPath(rel));
   }
-  for (const abs of collectScanFiles(config, root, skillIndex)) {
+  return paths;
+}
+function collectScannedDocMeta(ctx) {
+  const paths = [];
+  for (const abs of collectScanFiles(ctx.config, ctx.root, ctx.skillIndex)) {
     const content = readFileSync5(abs, "utf8");
     if (/<!--\s*doc-meta:/.test(content)) {
-      paths.push(normalizeRelPath(relative4(root, abs)));
+      paths.push(normalizeRelPath(relative4(ctx.root, abs)));
     }
   }
-  return excludeForeignSkillDocMetaPaths([...new Set(paths)], skillIndex);
+  return paths;
+}
+function collectDocMetaPaths(ctx) {
+  const paths = [];
+  for (const abs of expandPatterns(ctx.root, ["docs/*/README.md"], mergedExcludes(ctx.config))) {
+    paths.push(normalizeRelPath(relative4(ctx.root, abs)));
+  }
+  const extras = ["docs/README.md", ".skeleton/registry.md"];
+  for (const file of extras) {
+    const abs = join6(ctx.root, file);
+    if (existsSync7(abs))
+      paths.push(normalizeRelPath(file));
+  }
+  paths.push(...collectRegistryDocMeta(ctx));
+  paths.push(...collectScannedDocMeta(ctx));
+  return excludeForeignSkillDocMetaPaths([...new Set(paths)], ctx.skillIndex);
 }
 function validateScanRoots(config, root) {
   const missing = [];
@@ -17437,31 +17623,34 @@ function filterToPaths(files, paths, root) {
     return normalizedPaths.some((path) => rel === path || rel.startsWith(`${path}/`));
   });
 }
+function addExplicitPath(out, root, raw) {
+  const rel = normalizeRelPath(raw);
+  const abs = join6(root, rel);
+  if (!existsSync7(abs))
+    return;
+  if (isMarkdownFile(rel)) {
+    out.add(abs);
+    return;
+  }
+  try {
+    if (!statSync2(abs).isDirectory())
+      return;
+  } catch {
+    return;
+  }
+  for (const md of globSync("**/*.{md,mdc}", {
+    cwd: abs,
+    absolute: true,
+    onlyFiles: true,
+    dot: true
+  })) {
+    out.add(md);
+  }
+}
 function includeExplicitMarkdownPaths(files, paths, root) {
   const out = new Set(files);
   for (const raw of paths) {
-    const rel = normalizeRelPath(raw);
-    const abs = join6(root, rel);
-    if (!existsSync7(abs))
-      continue;
-    if (isMarkdownFile(rel)) {
-      out.add(abs);
-      continue;
-    }
-    try {
-      if (!statSync2(abs).isDirectory())
-        continue;
-    } catch {
-      continue;
-    }
-    for (const md of globSync("**/*.{md,mdc}", {
-      cwd: abs,
-      absolute: true,
-      onlyFiles: true,
-      dot: true
-    })) {
-      out.add(md);
-    }
+    addExplicitPath(out, root, raw);
   }
   return [...out];
 }
@@ -17498,9 +17687,6 @@ function parseRegistry(root) {
   }
   return { paths: [...new Set(paths)], hasTableHeader };
 }
-function parseRegistryPaths(root) {
-  return parseRegistry(root).paths;
-}
 
 // src/audit/core/context.ts
 function createContext(options = {}) {
@@ -17516,7 +17702,12 @@ function createContext(options = {}) {
     files = filterToPaths(files, options.paths, root);
   }
   const registry = parseRegistry(root);
-  const allDocMetaPaths = collectDocMetaPaths(config, root, registry.paths, skillIndex);
+  const allDocMetaPaths = collectDocMetaPaths({
+    config,
+    root,
+    registryPaths: registry.paths,
+    skillIndex
+  });
   return {
     root,
     config,
@@ -21788,9 +21979,9 @@ function factoryTitle(effects, ok2, nok, type, markerType, stringType) {
       return atBreak(code);
     }
     effects.consume(code);
-    return code === codes.backslash ? escape2 : inside;
+    return code === codes.backslash ? escape : inside;
   }
-  function escape2(code) {
+  function escape(code) {
     if (code === marker || code === codes.backslash) {
       effects.consume(code);
       return inside;
@@ -28817,174 +29008,213 @@ function stripYamlFrontmatter(content3) {
     return "";
   return content3;
 }
-function destinationConsumesToSliceEnd(slice, afterDest) {
-  let i = afterDest;
-  if (i >= slice.length)
-    return false;
-  if (slice[i] === ")") {
-    return i === slice.length - 1;
-  }
-  if (!/\s/.test(slice[i]))
-    return false;
-  while (i < slice.length && /\s/.test(slice[i]))
+function skipWhitespace(slice, start) {
+  let i = start;
+  while (i < slice.length) {
+    const ch = slice[i];
+    if (ch === undefined || !/\s/.test(ch))
+      break;
     i++;
-  if (i >= slice.length)
-    return false;
-  if (slice[i] === ")") {
-    return i === slice.length - 1;
   }
-  const open = slice[i];
+  return i;
+}
+function skipTitle(slice, start) {
+  if (start >= slice.length)
+    return start;
+  const open = slice[start];
   if (open !== '"' && open !== "'" && open !== "(")
-    return false;
+    return start;
   const close = open === "(" ? ")" : open;
-  i++;
+  let i = start + 1;
   while (i < slice.length && slice[i] !== close)
     i++;
+  return i < slice.length ? i + 1 : i;
+}
+function destinationConsumesToSliceEnd(slice, afterDest) {
+  if (afterDest >= slice.length)
+    return false;
+  if (slice[afterDest] === ")")
+    return afterDest === slice.length - 1;
+  const first = slice[afterDest];
+  if (first === undefined || !/\s/.test(first))
+    return false;
+  let i = skipWhitespace(slice, afterDest);
   if (i >= slice.length)
     return false;
-  i++;
-  while (i < slice.length && /\s/.test(slice[i]))
-    i++;
+  if (slice[i] === ")")
+    return i === slice.length - 1;
+  i = skipTitle(slice, i);
+  i = skipWhitespace(slice, i);
   return i === slice.length - 1 && slice[i] === ")";
 }
-function findUrlSpanInSlice(content3, nodeStart, nodeEnd, url) {
-  const slice = content3.slice(nodeStart, nodeEnd);
+function spanForAngleUrl(slice, after) {
+  if (!slice.content.startsWith(`<${slice.url}>`, after))
+    return null;
+  const afterDest = after + 2 + slice.url.length;
+  if (!destinationConsumesToSliceEnd(slice.content, afterDest))
+    return null;
+  const urlStart = slice.nodeStart + after + 1;
+  return { urlStart, urlEnd: urlStart + slice.url.length };
+}
+function spanForBareUrl(slice, after) {
+  if (!slice.content.startsWith(slice.url, after))
+    return null;
+  const next = slice.content[after + slice.url.length];
+  if (!(next === ")" || next !== undefined && /\s/.test(next)))
+    return null;
+  if (!destinationConsumesToSliceEnd(slice.content, after + slice.url.length))
+    return null;
+  const urlStart = slice.nodeStart + after;
+  return { urlStart, urlEnd: urlStart + slice.url.length };
+}
+function tryLinkDestination(slice, openParen) {
+  const after = openParen + 2;
+  return spanForAngleUrl(slice, after) ?? spanForBareUrl(slice, after);
+}
+function findUrlSpanInSlice(slice) {
+  const nodeSlice = slice.content.slice(slice.nodeStart, slice.nodeEnd);
   let searchFrom = 0;
-  while (searchFrom < slice.length) {
-    const openParen = slice.indexOf("](", searchFrom);
+  while (searchFrom < nodeSlice.length) {
+    const openParen = nodeSlice.indexOf("](", searchFrom);
     if (openParen === -1)
       break;
-    const after = openParen + 2;
-    if (slice.startsWith(`<${url}>`, after)) {
-      const afterDest = after + 2 + url.length;
-      if (destinationConsumesToSliceEnd(slice, afterDest)) {
-        const urlStart = nodeStart + after + 1;
-        return { urlStart, urlEnd: urlStart + url.length };
-      }
-    } else if (slice.startsWith(url, after)) {
-      const next = slice[after + url.length];
-      if (next === ")" || next !== undefined && /\s/.test(next)) {
-        if (destinationConsumesToSliceEnd(slice, after + url.length)) {
-          const urlStart = nodeStart + after;
-          return { urlStart, urlEnd: urlStart + url.length };
-        }
-      }
-    }
+    const span = tryLinkDestination({ content: nodeSlice, nodeStart: slice.nodeStart, nodeEnd: slice.nodeEnd, url: slice.url }, openParen);
+    if (span)
+      return span;
     searchFrom = openParen + 1;
   }
-  const auto = `<${url}>`;
-  if (slice === auto) {
-    return { urlStart: nodeStart + 1, urlEnd: nodeStart + 1 + url.length };
+  return matchAutolinkOrBare(nodeSlice, slice);
+}
+function matchAutolinkOrBare(nodeSlice, slice) {
+  const auto = `<${slice.url}>`;
+  if (nodeSlice === auto) {
+    return { urlStart: slice.nodeStart + 1, urlEnd: slice.nodeStart + 1 + slice.url.length };
   }
-  if (slice === url) {
-    return { urlStart: nodeStart, urlEnd: nodeEnd };
+  if (nodeSlice === slice.url) {
+    return { urlStart: slice.nodeStart, urlEnd: slice.nodeEnd };
   }
-  const trimmed = slice.trim();
+  const trimmed = nodeSlice.trim();
   if (trimmed === auto) {
-    const lead = slice.indexOf(auto);
+    const lead = nodeSlice.indexOf(auto);
     if (lead !== -1) {
-      return { urlStart: nodeStart + lead + 1, urlEnd: nodeStart + lead + 1 + url.length };
+      return {
+        urlStart: slice.nodeStart + lead + 1,
+        urlEnd: slice.nodeStart + lead + 1 + slice.url.length
+      };
     }
   }
-  if (trimmed === url) {
-    const lead = slice.indexOf(url);
+  if (trimmed === slice.url) {
+    const lead = nodeSlice.indexOf(slice.url);
     if (lead !== -1) {
-      return { urlStart: nodeStart + lead, urlEnd: nodeStart + lead + url.length };
+      return {
+        urlStart: slice.nodeStart + lead,
+        urlEnd: slice.nodeStart + lead + slice.url.length
+      };
     }
   }
-  return;
 }
-function findUrlInDefinitionSlice(content3, nodeStart, nodeEnd, url) {
-  const slice = content3.slice(nodeStart, nodeEnd);
-  const labelEnd2 = slice.indexOf("]:");
+function findUrlInDefinitionSlice(slice) {
+  const nodeSlice = slice.content.slice(slice.nodeStart, slice.nodeEnd);
+  const labelEnd2 = nodeSlice.indexOf("]:");
   if (labelEnd2 === -1)
     return;
   let i = labelEnd2 + 2;
-  while (i < slice.length && /\s/.test(slice[i] ?? ""))
+  while (i < nodeSlice.length && /\s/.test(nodeSlice[i] ?? ""))
     i++;
-  if (slice.startsWith(`<${url}>`, i)) {
-    const urlStart = nodeStart + i + 1;
-    return { urlStart, urlEnd: urlStart + url.length };
+  if (nodeSlice.startsWith(`<${slice.url}>`, i)) {
+    const urlStart = slice.nodeStart + i + 1;
+    return { urlStart, urlEnd: urlStart + slice.url.length };
   }
-  if (slice.startsWith(url, i)) {
-    const urlStart = nodeStart + i;
-    return { urlStart, urlEnd: urlStart + url.length };
+  if (nodeSlice.startsWith(slice.url, i)) {
+    const urlStart = slice.nodeStart + i;
+    return { urlStart, urlEnd: urlStart + slice.url.length };
   }
-  return;
 }
-function collectReferenceDefinitions(content3, tree) {
-  const defs = new Map;
-  visit2(tree, (node2) => {
-    if (node2.type !== "definition")
-      return;
-    if (!("identifier" in node2) || !("url" in node2))
-      return;
-    const id = String(node2.identifier).toLowerCase();
-    if (defs.has(id))
-      return;
-    const url = typeof node2.url === "string" ? node2.url : "";
-    if (!url)
-      return;
-    const start = node2.position?.start.offset;
-    const end = node2.position?.end.offset;
-    if (start === undefined || end === undefined)
-      return;
-    const span = findUrlInDefinitionSlice(content3, start, end, url);
-    if (!span)
+function definitionFromNode(content3, node2, defs) {
+  if (!(("identifier" in node2) && ("url" in node2)))
+    return;
+  const id = String(node2.identifier).toLowerCase();
+  if (defs.has(id))
+    return;
+  const url = typeof node2.url === "string" ? node2.url : "";
+  if (!url)
+    return;
+  const start = node2.position?.start?.offset;
+  const end = node2.position?.end?.offset;
+  if (start === undefined || end === undefined)
+    return;
+  const span = findUrlInDefinitionSlice({ content: content3, nodeStart: start, nodeEnd: end, url });
+  if (!span)
+    return;
+  defs.set(id, {
+    url,
+    urlStart: span.urlStart,
+    urlEnd: span.urlEnd,
+    line: lineFromOffset(content3, start) ?? 1
+  });
+}
+function collectReferenceDefinitions(content3, tree) {
+  const defs = new Map;
+  visit2(tree, (node2) => {
+    if (node2.type !== "definition")
       return;
-    defs.set(id, {
-      url,
-      urlStart: span.urlStart,
-      urlEnd: span.urlEnd,
-      line: lineFromOffset(content3, start) ?? 1
-    });
+    definitionFromNode(content3, node2, defs);
   });
   return defs;
 }
+function linkFromDirectNode(content3, node2) {
+  const target = node2.url.trim();
+  const start = node2.position?.start?.offset;
+  const end = node2.position?.end?.offset;
+  const span = start !== undefined && end !== undefined ? findUrlSpanInSlice({ content: content3, nodeStart: start, nodeEnd: end, url: target }) : undefined;
+  return {
+    target,
+    line: lineFromOffset(content3, node2.position?.start?.offset),
+    urlStart: span?.urlStart,
+    urlEnd: span?.urlEnd
+  };
+}
+function linkFromReference(id, refDefs) {
+  const def = refDefs.get(id);
+  if (!def)
+    return null;
+  return {
+    target: def.url.trim(),
+    line: def.line,
+    urlStart: def.urlStart,
+    urlEnd: def.urlEnd
+  };
+}
 function extractLinksFromMarkdown(content3, _filePath) {
   const tree = processor.parse(content3);
   const refDefs = collectReferenceDefinitions(content3, tree);
   const links = [];
   visit2(tree, (node2) => {
     if (node2.type === "link" && "url" in node2 && typeof node2.url === "string") {
-      const target = node2.url.trim();
-      const start = node2.position?.start.offset;
-      const end = node2.position?.end.offset;
-      const span = start !== undefined && end !== undefined ? findUrlSpanInSlice(content3, start, end, target) : undefined;
-      links.push({
-        target,
-        line: lineFromOffset(content3, node2.position?.start.offset),
-        urlStart: span?.urlStart,
-        urlEnd: span?.urlEnd
-      });
+      links.push(linkFromDirectNode(content3, node2));
     }
     if (node2.type === "linkReference" && "identifier" in node2) {
-      const id = String(node2.identifier).toLowerCase();
-      const def = refDefs.get(id);
-      if (def) {
-        links.push({
-          target: def.url.trim(),
-          line: def.line,
-          urlStart: def.urlStart,
-          urlEnd: def.urlEnd
-        });
-      }
+      const refLink = linkFromReference(String(node2.identifier).toLowerCase(), refDefs);
+      if (refLink)
+        links.push(refLink);
     }
   });
   return links;
 }
+function textFromPhrasingNode(node2) {
+  if (node2.type === "text" || node2.type === "inlineCode") {
+    return "value" in node2 && node2.value !== undefined ? String(node2.value) : "";
+  }
+  return "";
+}
 function phrasingText(nodes) {
   if (!nodes?.length)
     return "";
   let out = "";
   for (const node2 of nodes) {
-    if (node2.type === "text" || node2.type === "inlineCode") {
-      out += "value" in node2 && node2.value !== undefined ? String(node2.value) : "";
-      continue;
-    }
-    if (node2.children?.length) {
+    out += textFromPhrasingNode(node2);
+    if (node2.children?.length)
       out += phrasingText(node2.children);
-    }
   }
   return out;
 }
@@ -29074,60 +29304,86 @@ function replaceAnchorInTarget(target, oldAnchor, newAnchor) {
     return target;
   return `${pathPart}#${newAnchor}${queryPart}`;
 }
+function anchorTargetReplacement(filePath, target) {
+  if (isExternalLink(target) && !target.startsWith("#"))
+    return null;
+  if (isPlaceholderLink(target))
+    return null;
+  const anchor = target.includes("#") ? target.split("#")[1]?.split("?")[0] ?? "" : "";
+  if (!anchor)
+    return null;
+  const resolved = resolveLink(filePath, target);
+  if (!existsSync9(resolved))
+    return null;
+  const targetContent = readFileSync7(resolved, "utf8");
+  const slugs = extractHeadingSlugs(targetContent, resolved);
+  const anchorSlug = slugifyAnchor(anchor);
+  if (slugs.has(anchorSlug))
+    return null;
+  const match = findBestAnchorMatch(anchorSlug, slugs);
+  if (!match)
+    return null;
+  const nextTarget = replaceAnchorInTarget(target, anchor, match.slug);
+  if (nextTarget === target)
+    return null;
+  return { nextTarget, match, anchor };
+}
+function pendingAnchorForLink(input) {
+  const { filePath, content: content3, relFile, link: link2 } = input;
+  const { target, line, urlStart, urlEnd } = link2;
+  const replacement = anchorTargetReplacement(filePath, target);
+  if (!replacement)
+    return null;
+  if (urlStart === undefined || urlEnd === undefined || content3.slice(urlStart, urlEnd) !== target) {
+    return null;
+  }
+  const lineLabel = line ? `${relFile}:${line}` : relFile;
+  return {
+    urlStart,
+    urlEnd,
+    from: target,
+    to: replacement.nextTarget,
+    description: `${lineLabel} #${replacement.anchor} → #${replacement.match.slug} (score ${replacement.match.score.toFixed(2)})`
+  };
+}
+function applyPendingEdits(content3, pending) {
+  const uniqueBySpan = new Map;
+  for (const edit of pending) {
+    uniqueBySpan.set(`${edit.urlStart}:${edit.urlEnd}:${edit.from}`, edit);
+  }
+  const uniquePending = [...uniqueBySpan.values()].sort((a, b) => b.urlStart - a.urlStart);
+  let updated = content3;
+  const descriptions = [];
+  for (const edit of uniquePending) {
+    if (updated.slice(edit.urlStart, edit.urlEnd) !== edit.from)
+      continue;
+    updated = updated.slice(0, edit.urlStart) + edit.to + updated.slice(edit.urlEnd);
+    descriptions.push(edit.description);
+  }
+  if (updated === content3 || descriptions.length === 0)
+    return null;
+  return { content: updated, descriptions };
+}
+function collectFileAnchorFixes(ctx, filePath) {
+  const content3 = readFileContent(filePath);
+  const links = extractLinksFromMarkdown(content3, filePath);
+  const relFile = relPath(filePath, ctx.root);
+  const pending = [];
+  for (const link2 of links) {
+    const edit = pendingAnchorForLink({ ctx, filePath, content: content3, relFile, link: link2 });
+    if (edit)
+      pending.push(edit);
+  }
+  if (pending.length === 0)
+    return null;
+  return applyPendingEdits(content3, pending);
+}
 function collectAnchorFixes(ctx) {
   const editsByFile = new Map;
   for (const filePath of ctx.files) {
-    const content3 = readFileContent(filePath);
-    const links = extractLinksFromMarkdown(content3, filePath);
-    const pending = [];
-    const relFile = relPath(filePath, ctx.root);
-    for (const { target, line, urlStart, urlEnd } of links) {
-      if (isExternalLink(target) && !target.startsWith("#"))
-        continue;
-      if (isPlaceholderLink(target))
-        continue;
-      const anchor = target.includes("#") ? target.split("#")[1]?.split("?")[0] ?? "" : "";
-      if (!anchor)
-        continue;
-      const resolved = resolveLink(filePath, target);
-      if (!existsSync9(resolved))
-        continue;
-      const targetContent = readFileSync7(resolved, "utf8");
-      const slugs = extractHeadingSlugs(targetContent, resolved);
-      const anchorSlug = slugifyAnchor(anchor);
-      if (slugs.has(anchorSlug))
-        continue;
-      const match = findBestAnchorMatch(anchorSlug, slugs);
-      if (!match)
-        continue;
-      const nextTarget = replaceAnchorInTarget(target, anchor, match.slug);
-      if (nextTarget === target)
-        continue;
-      const lineLabel = line ? `${relFile}:${line}` : relFile;
-      const description = `${lineLabel} #${anchor} → #${match.slug} (score ${match.score.toFixed(2)})`;
-      if (urlStart !== undefined && urlEnd !== undefined && content3.slice(urlStart, urlEnd) === target) {
-        pending.push({ urlStart, urlEnd, from: target, to: nextTarget, description });
-      }
-    }
-    if (pending.length === 0)
-      continue;
-    const uniqueBySpan = new Map;
-    for (const edit of pending) {
-      uniqueBySpan.set(`${edit.urlStart}:${edit.urlEnd}:${edit.from}`, edit);
-    }
-    const uniquePending = [...uniqueBySpan.values()];
-    uniquePending.sort((a, b) => b.urlStart - a.urlStart);
-    let updated = content3;
-    const descriptions = [];
-    for (const edit of uniquePending) {
-      if (updated.slice(edit.urlStart, edit.urlEnd) !== edit.from)
-        continue;
-      updated = updated.slice(0, edit.urlStart) + edit.to + updated.slice(edit.urlEnd);
-      descriptions.push(edit.description);
-    }
-    if (updated === content3 || descriptions.length === 0)
-      continue;
-    editsByFile.set(filePath, { content: updated, descriptions });
+    const result = collectFileAnchorFixes(ctx, filePath);
+    if (result)
+      editsByFile.set(filePath, result);
   }
   const edits = [];
   for (const [absPath, { content: content3, descriptions }] of editsByFile) {
@@ -29170,32 +29426,37 @@ function bumpDocMetaLastReviewed(content3, gitDate) {
     return null;
   return replaceDocMetaLastReviewed(content3, gitDate);
 }
+function docMetaFixForPath(ctx, relPath2) {
+  const abs = join9(ctx.root, relPath2);
+  if (!existsSync10(abs))
+    return null;
+  const content3 = readFileSync8(abs, "utf8");
+  if (!DOC_META_RE.test(content3))
+    return null;
+  const reviewedStr = docMetaLastReviewed(content3);
+  if (!reviewedStr)
+    return null;
+  const reviewed = new Date(`${reviewedStr}T00:00:00Z`);
+  if (Number.isNaN(reviewed.getTime()))
+    return null;
+  const gitDate = lastGitCommitDate(relPath2, ctx.root);
+  if (!gitDate)
+    return null;
+  const updated = bumpDocMetaLastReviewed(content3, gitDate);
+  if (!updated)
+    return null;
+  return {
+    file: relPath2,
+    description: `last-reviewed ${reviewedStr} → ${gitDate}`,
+    content: updated
+  };
+}
 function collectDocMetaFixes(ctx) {
   const edits = [];
   for (const relPath2 of ctx.docMetaPaths) {
-    const abs = join9(ctx.root, relPath2);
-    if (!existsSync10(abs))
-      continue;
-    const content3 = readFileSync8(abs, "utf8");
-    if (!DOC_META_RE.test(content3))
-      continue;
-    const reviewedStr = docMetaLastReviewed(content3);
-    if (!reviewedStr)
-      continue;
-    const reviewed = new Date(`${reviewedStr}T00:00:00Z`);
-    if (Number.isNaN(reviewed.getTime()))
-      continue;
-    const gitDate = lastGitCommitDate(relPath2, ctx.root);
-    if (!gitDate)
-      continue;
-    const updated = bumpDocMetaLastReviewed(content3, gitDate);
-    if (!updated)
-      continue;
-    edits.push({
-      file: relPath2,
-      description: `last-reviewed ${reviewedStr} → ${gitDate}`,
-      content: updated
-    });
+    const fix = docMetaFixForPath(ctx, relPath2);
+    if (fix)
+      edits.push(fix);
   }
   return edits;
 }
@@ -29237,28 +29498,31 @@ function overlayLastReviewed(targetContent, metaContent) {
 function underRoot(rootAbs, candidateAbs) {
   return candidateAbs === rootAbs || candidateAbs.startsWith(rootAbs + sep3);
 }
-function resolveWritePath(root2, relFile) {
-  const rootResolved = resolve6(root2);
-  const abs = resolve6(rootResolved, relFile);
-  if (!underRoot(rootResolved, abs)) {
-    throw new Error(`Refusing autofix outside repo root: ${relFile}`);
-  }
+function shouldStopPathWalk(rootResolved, parent, cursor) {
+  return parent === cursor || !underRoot(rootResolved, parent) && parent !== rootResolved;
+}
+function resolveExistingRealPath(rootResolved, abs, relFile) {
   const rootReal = existsSync11(rootResolved) ? realpathSync5(rootResolved) : rootResolved;
   let cursor = abs;
-  while (true) {
-    if (existsSync11(cursor)) {
-      const real = realpathSync5(cursor);
-      if (!underRoot(rootReal, real)) {
-        throw new Error(`Refusing autofix outside repo root: ${relFile}`);
-      }
-      return abs;
-    }
+  while (!existsSync11(cursor)) {
     const parent = dirname6(cursor);
-    if (parent === cursor || !underRoot(rootResolved, parent) && parent !== rootResolved) {
+    if (shouldStopPathWalk(rootResolved, parent, cursor))
       return abs;
-    }
     cursor = parent;
   }
+  const real = realpathSync5(cursor);
+  if (!underRoot(rootReal, real)) {
+    throw new Error(`Refusing autofix outside repo root: ${relFile}`);
+  }
+  return abs;
+}
+function resolveWritePath(root2, relFile) {
+  const rootResolved = resolve6(root2);
+  const abs = resolve6(rootResolved, relFile);
+  if (!underRoot(rootResolved, abs)) {
+    throw new Error(`Refusing autofix outside repo root: ${relFile}`);
+  }
+  return resolveExistingRealPath(rootResolved, abs, relFile);
 }
 function applyFixes(ctx, options) {
   const kinds = new Set(options.kinds);
@@ -29302,13 +29566,14 @@ function fixKindsForOnly(kinds, only) {
 }
 
 // src/audit/core/report.ts
-function issue(rule, file, message, opts) {
+function issue(rule, file, details) {
+  const message = typeof details === "string" ? details : details.message;
   return {
     rule,
     file,
-    link: opts?.link,
+    link: typeof details === "string" ? undefined : details.link,
     message,
-    severity: opts?.severity ?? "error"
+    severity: typeof details === "string" ? "error" : details.severity ?? "error"
   };
 }
 function finalizeIssues(issues, strict) {
@@ -29321,31 +29586,39 @@ function printReport(issues, options) {
   const errors2 = finalized.filter((i) => i.severity === "error");
   const warnings = finalized.filter((i) => i.severity === "warning");
   const label = options.label ?? "Audit";
-  if (options.json) {
-    console.log(JSON.stringify({
-      label,
-      fileCount: options.fileCount,
-      errors: errors2.length,
-      warnings: warnings.length,
-      issues: finalized
-    }, null, 2));
-    return errors2.length > 0 ? 1 : 0;
-  }
-  if (warnings.length > 0) {
-    console.log(`${label} warnings:
+  const ctx = { label, options, errors: errors2, warnings, finalized };
+  if (options.json)
+    return printJsonReport(ctx);
+  return printTextReport(ctx);
+}
+function printJsonReport(ctx) {
+  console.log(JSON.stringify({
+    label: ctx.label,
+    fileCount: ctx.options.fileCount,
+    errors: ctx.errors.length,
+    warnings: ctx.warnings.length,
+    issues: ctx.finalized
+  }, null, 2));
+  return ctx.errors.length > 0 ? 1 : 0;
+}
+function printWarnings(label, warnings) {
+  if (warnings.length === 0)
+    return;
+  console.log(`${label} warnings:
 `);
-    for (const i of warnings) {
-      const linkPart = i.link ? ` (${i.link})` : "";
-      console.log(`- ${i.file}${linkPart}: ${i.message}`);
-    }
-    console.log("");
-  }
-  if (errors2.length === 0) {
-    const warnNote = warnings.length > 0 ? `, ${warnings.length} warning(s)` : "";
-    const countNote = options.successSuffix ?? (options.fileCount !== undefined ? ` (${options.fileCount} files scanned${warnNote})` : "");
-    console.log(`${label} passed${countNote}.`);
-    return 0;
+  for (const i of warnings) {
+    const linkPart = i.link ? ` (${i.link})` : "";
+    console.log(`- ${i.file}${linkPart}: ${i.message}`);
   }
+  console.log("");
+}
+function printSuccess(label, options, warnings) {
+  const warnNote = warnings.length > 0 ? `, ${warnings.length} warning(s)` : "";
+  const countNote = options.successSuffix ?? (options.fileCount !== undefined ? ` (${options.fileCount} files scanned${warnNote})` : "");
+  console.log(`${label} passed${countNote}.`);
+  return 0;
+}
+function printErrors(label, errors2) {
   console.log(`${label} failed:
 `);
   for (const i of errors2) {
@@ -29354,6 +29627,13 @@ function printReport(issues, options) {
   }
   return 1;
 }
+function printTextReport(ctx) {
+  const { label, options, errors: errors2, warnings } = ctx;
+  printWarnings(label, warnings);
+  if (errors2.length === 0)
+    return printSuccess(label, options, warnings);
+  return printErrors(label, errors2);
+}
 
 // src/references/check.ts
 import { existsSync as existsSync13, readdirSync as readdirSync4, readFileSync as readFileSync10 } from "node:fs";
@@ -29413,73 +29693,86 @@ function findSharedRefLinks(content3, sourceFile) {
   }
   return links;
 }
+function findSiblingRefLinks(root2, content3, sourceFile) {
+  const links = [];
+  if (!/\/references\//.test(sourceFile))
+    return links;
+  const refsIdx = sourceFile.lastIndexOf("/references/");
+  const withinRefs = sourceFile.slice(refsIdx + "/references/".length);
+  const withinDir = withinRefs.includes("/") ? withinRefs.slice(0, withinRefs.lastIndexOf("/")) : "";
+  const siblingRe = /\((?!https?:|#|\.\.\/)([a-z0-9./_-]+\.md)\)/gi;
+  for (const match of content3.matchAll(siblingRe)) {
+    const raw = normalizeRelPath(match[1] ?? "");
+    if (!raw)
+      continue;
+    const refPath = withinDir ? normalizeRelPath(join10(withinDir, raw)) : raw;
+    if (!canonicalExists(root2, refPath))
+      continue;
+    links.push({ refPath, sourceFile });
+  }
+  return links;
+}
 function findLocalCanonicalLinks(root2, content3, sourceFile) {
   const links = [];
   const localRefRe = /\((?:\.\/)?references\/([^)]+)\)/g;
   for (const match of content3.matchAll(localRefRe)) {
     const refPath = normalizeRelPath(match[1] ?? "");
-    if (!refPath || !canonicalExists(root2, refPath))
+    if (!(refPath && canonicalExists(root2, refPath)))
       continue;
     links.push({ refPath, sourceFile });
   }
-  const inReferencesDir = /\/references\//.test(sourceFile);
-  if (inReferencesDir) {
-    const refsIdx = sourceFile.lastIndexOf("/references/");
-    const withinRefs = sourceFile.slice(refsIdx + "/references/".length);
-    const withinDir = withinRefs.includes("/") ? withinRefs.slice(0, withinRefs.lastIndexOf("/")) : "";
-    const siblingRe = /\((?!https?:|#|\.\.\/)([a-z0-9./_-]+\.md)\)/gi;
-    for (const match of content3.matchAll(siblingRe)) {
-      const raw = normalizeRelPath(match[1] ?? "");
-      if (!raw)
-        continue;
-      const refPath = withinDir ? normalizeRelPath(join10(withinDir, raw)) : raw;
-      if (!canonicalExists(root2, refPath))
+  links.push(...findSiblingRefLinks(root2, content3, sourceFile));
+  return links;
+}
+function collectLinksForFile(root2, relFile) {
+  const content3 = readFileSync9(join10(root2, relFile), "utf8");
+  if (isGeneratedReference(content3))
+    return [];
+  return [
+    ...findSharedRefLinks(content3, relFile),
+    ...findLocalCanonicalLinks(root2, content3, relFile)
+  ];
+}
+function expandTransitiveRefs(input) {
+  const { root: root2, slug: slug2, refPaths, links } = input;
+  const queue = [...refPaths];
+  while (queue.length > 0) {
+    const refPath = queue.pop();
+    if (!(refPath && canonicalExists(root2, refPath)))
+      continue;
+    const canonicalContent = readFileSync9(join10(root2, CANONICAL_REFS_DIR, refPath), "utf8");
+    const syntheticSource = generatedRefPath(slug2, refPath);
+    for (const link2 of findLocalCanonicalLinks(root2, canonicalContent, syntheticSource)) {
+      if (refPaths.has(link2.refPath))
         continue;
-      links.push({ refPath, sourceFile });
+      refPaths.add(link2.refPath);
+      links.push(link2);
+      queue.push(link2.refPath);
     }
   }
-  return links;
+}
+function planForSkill(root2, slug2) {
+  const skillDir = join10(root2, slug2);
+  if (!existsSync12(join10(skillDir, "SKILL.md")))
+    return null;
+  const refPaths = new Set;
+  const links = [];
+  for (const relFile of walkMarkdownFiles(skillDir, root2)) {
+    for (const link2 of collectLinksForFile(root2, relFile)) {
+      refPaths.add(link2.refPath);
+      links.push(link2);
+    }
+  }
+  expandTransitiveRefs({ root: root2, slug: slug2, refPaths, links });
+  return refPaths.size > 0 ? { skill: slug2, refPaths, links } : null;
 }
 function discoverSkillReferencePlans(root2, ownership) {
   const index2 = buildSkillIndex(root2, ownership);
   const plans = [];
   for (const slug2 of index2.ownedSlugs) {
-    const skillDir = join10(root2, slug2);
-    if (!existsSync12(join10(skillDir, "SKILL.md")))
-      continue;
-    const refPaths = new Set;
-    const links = [];
-    for (const relFile of walkMarkdownFiles(skillDir, root2)) {
-      const content3 = readFileSync9(join10(root2, relFile), "utf8");
-      if (isGeneratedReference(content3))
-        continue;
-      for (const link2 of findSharedRefLinks(content3, relFile)) {
-        refPaths.add(link2.refPath);
-        links.push(link2);
-      }
-      for (const link2 of findLocalCanonicalLinks(root2, content3, relFile)) {
-        refPaths.add(link2.refPath);
-        links.push(link2);
-      }
-    }
-    const queue = [...refPaths];
-    while (queue.length > 0) {
-      const refPath = queue.pop();
-      if (!refPath || !canonicalExists(root2, refPath))
-        continue;
-      const canonicalContent = readFileSync9(join10(root2, CANONICAL_REFS_DIR, refPath), "utf8");
-      const syntheticSource = generatedRefPath(slug2, refPath);
-      for (const link2 of findLocalCanonicalLinks(root2, canonicalContent, syntheticSource)) {
-        if (refPaths.has(link2.refPath))
-          continue;
-        refPaths.add(link2.refPath);
-        links.push(link2);
-        queue.push(link2.refPath);
-      }
-    }
-    if (refPaths.size > 0) {
-      plans.push({ skill: slug2, refPaths, links });
-    }
+    const plan = planForSkill(root2, slug2);
+    if (plan)
+      plans.push(plan);
   }
   return plans.sort((a, b) => a.skill.localeCompare(b.skill));
 }
@@ -29510,30 +29803,75 @@ function rewriteSharedRefLinks(content3, sourceFile, skill) {
 }
 
 // src/references/check.ts
+function walkMarkdown(dir, onFile) {
+  if (!existsSync13(dir))
+    return;
+  for (const entry of readdirSync4(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith("."))
+      continue;
+    const fullPath = join11(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkMarkdown(fullPath, onFile);
+      continue;
+    }
+    if (!entry.name.endsWith(".md"))
+      continue;
+    onFile(fullPath);
+  }
+}
 function listAllGeneratedFiles(root2) {
   const files = [];
-  const walk = (dir) => {
-    if (!existsSync13(dir))
-      return;
-    for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-      if (entry.name.startsWith("."))
-        continue;
-      const fullPath = join11(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(fullPath);
-        continue;
-      }
-      if (!entry.name.endsWith(".md"))
-        continue;
-      const content3 = readFileSync10(fullPath, "utf8");
-      if (isGeneratedReference(content3)) {
-        files.push(normalizeRelPath(relative7(root2, fullPath)));
-      }
+  walkMarkdown(root2, (fullPath) => {
+    const content3 = readFileSync10(fullPath, "utf8");
+    if (isGeneratedReference(content3)) {
+      files.push(normalizeRelPath(relative7(root2, fullPath)));
     }
-  };
-  walk(root2);
+  });
   return files;
 }
+function checkNeededCopy(root2, targetRel) {
+  const targetPath = join11(root2, targetRel);
+  if (!existsSync13(targetPath)) {
+    return issue("generated-references", targetRel, "missing generated copy — run skeleton references sync");
+  }
+  const generated = readFileSync10(targetPath, "utf8");
+  if (!isGeneratedReference(generated)) {
+    return issue("generated-references", targetRel, "expected generated-reference provenance header");
+  }
+  const body = stripGeneratedHeader(generated);
+  const sourceRel = normalizeRelPath(generated.match(/source: ([^\n]+)/)?.[1] ?? join11(CANONICAL_REFS_DIR, targetRel.split("/references/")[1] ?? ""));
+  const canonicalPath = join11(root2, sourceRel);
+  if (!existsSync13(canonicalPath)) {
+    return issue("generated-references", targetRel, `canonical source missing: ${sourceRel}`);
+  }
+  const canonical = readFileSync10(canonicalPath, "utf8");
+  if (body !== canonical) {
+    return issue("generated-references", targetRel, "stale generated copy — run skeleton references sync");
+  }
+  return null;
+}
+function checkOrphanedCopies(root2, needed, skillIndex) {
+  const issues = [];
+  for (const generatedRel of listAllGeneratedFiles(root2)) {
+    if (isForeignSkillPath(generatedRel, skillIndex))
+      continue;
+    if (!needed.has(generatedRel)) {
+      issues.push(issue("generated-references", generatedRel, "orphaned generated copy — run skeleton references sync"));
+    }
+  }
+  return issues;
+}
+function checkStaleSharedLinks(root2, skillDir) {
+  const issues = [];
+  walkMarkdown(skillDir, (fullPath) => {
+    const relFile = normalizeRelPath(relative7(root2, fullPath));
+    const content3 = readFileSync10(fullPath, "utf8");
+    if (!content3.match(SHARED_REF_LINK_RE))
+      return;
+    issues.push(issue("generated-references", relFile, "still links to shared root references/ — run skeleton references sync"));
+  });
+  return issues;
+}
 function runGeneratedReferencesCheck(root2, ownership) {
   const issues = [];
   const canonicalDir = join11(root2, CANONICAL_REFS_DIR);
@@ -29548,58 +29886,13 @@ function runGeneratedReferencesCheck(root2, ownership) {
     }
   }
   for (const targetRel of needed) {
-    const targetPath = join11(root2, targetRel);
-    if (!existsSync13(targetPath)) {
-      issues.push(issue("generated-references", targetRel, "missing generated copy — run skeleton references sync"));
-      continue;
-    }
-    const generated = readFileSync10(targetPath, "utf8");
-    if (!isGeneratedReference(generated)) {
-      issues.push(issue("generated-references", targetRel, "expected generated-reference provenance header"));
-      continue;
-    }
-    const body = stripGeneratedHeader(generated);
-    const sourceRel = normalizeRelPath(generated.match(/source: ([^\n]+)/)?.[1] ?? join11(CANONICAL_REFS_DIR, targetRel.split("/references/")[1] ?? ""));
-    const canonicalPath = join11(root2, sourceRel);
-    if (!existsSync13(canonicalPath)) {
-      issues.push(issue("generated-references", targetRel, `canonical source missing: ${sourceRel}`));
-      continue;
-    }
-    const canonical = readFileSync10(canonicalPath, "utf8");
-    if (body !== canonical) {
-      issues.push(issue("generated-references", targetRel, "stale generated copy — run skeleton references sync"));
-    }
-  }
-  for (const generatedRel of listAllGeneratedFiles(root2)) {
-    if (isForeignSkillPath(generatedRel, skillIndex))
-      continue;
-    if (!needed.has(generatedRel)) {
-      issues.push(issue("generated-references", generatedRel, "orphaned generated copy — run skeleton references sync"));
-    }
+    const found = checkNeededCopy(root2, targetRel);
+    if (found)
+      issues.push(found);
   }
+  issues.push(...checkOrphanedCopies(root2, needed, skillIndex));
   for (const plan of plans) {
-    const skillDir = join11(root2, plan.skill);
-    if (!existsSync13(skillDir))
-      continue;
-    const walk = (dir) => {
-      for (const entry of readdirSync4(dir, { withFileTypes: true })) {
-        if (entry.name.startsWith("."))
-          continue;
-        const fullPath = join11(dir, entry.name);
-        if (entry.isDirectory()) {
-          walk(fullPath);
-          continue;
-        }
-        if (!entry.name.endsWith(".md"))
-          continue;
-        const relFile = normalizeRelPath(relative7(root2, fullPath));
-        const content3 = readFileSync10(fullPath, "utf8");
-        if (content3.match(SHARED_REF_LINK_RE)) {
-          issues.push(issue("generated-references", relFile, "still links to shared root references/ — run skeleton references sync"));
-        }
-      }
-    };
-    walk(skillDir);
+    issues.push(...checkStaleSharedLinks(root2, join11(root2, plan.skill)));
   }
   return issues;
 }
@@ -29626,6 +29919,51 @@ var bannedRule = { id: "banned", run: runBannedRule };
 // src/audit/rules/doc-meta.ts
 import { existsSync as existsSync14, readFileSync as readFileSync11 } from "node:fs";
 import { join as join12 } from "node:path";
+function checkDocMetaBanner(relPath2, content3) {
+  if (DOC_META_RE.test(content3))
+    return null;
+  return issue("doc-meta", relPath2, "missing doc-meta comment (owner + last-reviewed)");
+}
+function checkStaleReview(input) {
+  const { relPath: relPath2, content: content3, today, staleDays } = input;
+  const reviewedStr = docMetaLastReviewed(content3);
+  if (!reviewedStr)
+    return null;
+  const reviewed = new Date(`${reviewedStr}T00:00:00Z`);
+  if (Number.isNaN(reviewed.getTime()))
+    return null;
+  const ageDays = (today.getTime() - reviewed.getTime()) / 86400000;
+  if (ageDays <= staleDays)
+    return null;
+  return issue("doc-meta", relPath2, {
+    message: `doc-meta last-reviewed ${reviewedStr} is stale (>${staleDays} days)`,
+    severity: "warning"
+  });
+}
+function checkGitFreshness(input) {
+  const { relPath: relPath2, content: content3, root: root2, lockedSkillSlugs } = input;
+  const reviewedStr = docMetaLastReviewed(content3);
+  if (!reviewedStr)
+    return null;
+  const reviewed = new Date(`${reviewedStr}T00:00:00Z`);
+  if (Number.isNaN(reviewed.getTime()))
+    return null;
+  const slug2 = slugFromPath(relPath2, root2);
+  if (slug2 !== null && lockedSkillSlugs.has(slug2))
+    return null;
+  const gitDate = lastGitCommitDate(relPath2, root2);
+  if (!gitDate)
+    return null;
+  const committed = new Date(`${gitDate}T00:00:00Z`);
+  if (Number.isNaN(committed.getTime()))
+    return null;
+  if (committed.getTime() <= reviewed.getTime())
+    return null;
+  return issue("doc-meta", relPath2, {
+    message: `content changed after last-reviewed ${reviewedStr} (git: ${gitDate}) — bump last-reviewed or confirm review`,
+    severity: "warning"
+  });
+}
 function runDocMetaRule(ctx) {
   const issues = [];
   const today = new Date;
@@ -29634,32 +29972,27 @@ function runDocMetaRule(ctx) {
     if (!existsSync14(abs))
       continue;
     const content3 = readFileSync11(abs, "utf8");
-    if (!DOC_META_RE.test(content3)) {
-      issues.push(issue("doc-meta", relPath2, "missing doc-meta comment (owner + last-reviewed)"));
-      continue;
-    }
-    const reviewedStr = docMetaLastReviewed(content3);
-    if (!reviewedStr)
+    const banner = checkDocMetaBanner(relPath2, content3);
+    if (banner) {
+      issues.push(banner);
       continue;
-    const reviewed = new Date(`${reviewedStr}T00:00:00Z`);
-    if (Number.isNaN(reviewed.getTime()))
-      continue;
-    const ageDays = (today.getTime() - reviewed.getTime()) / 86400000;
-    if (ageDays > ctx.config.daysUntilStale) {
-      issues.push(issue("doc-meta", relPath2, `doc-meta last-reviewed ${reviewedStr} is stale (>${ctx.config.daysUntilStale} days)`, { severity: "warning" }));
-    }
-    const slug2 = slugFromPath(relPath2, ctx.root);
-    if (slug2 !== null && ctx.lockedSkillSlugs.has(slug2))
-      continue;
-    const gitDate = lastGitCommitDate(relPath2, ctx.root);
-    if (!gitDate)
-      continue;
-    const committed = new Date(`${gitDate}T00:00:00Z`);
-    if (Number.isNaN(committed.getTime()))
-      continue;
-    if (committed.getTime() > reviewed.getTime()) {
-      issues.push(issue("doc-meta", relPath2, `content changed after last-reviewed ${reviewedStr} (git: ${gitDate}) — bump last-reviewed or confirm review`, { severity: "warning" }));
     }
+    const stale = checkStaleReview({
+      relPath: relPath2,
+      content: content3,
+      today,
+      staleDays: ctx.config.daysUntilStale
+    });
+    if (stale)
+      issues.push(stale);
+    const git = checkGitFreshness({
+      relPath: relPath2,
+      content: content3,
+      root: ctx.root,
+      lockedSkillSlugs: ctx.lockedSkillSlugs
+    });
+    if (git)
+      issues.push(git);
   }
   return issues;
 }
@@ -29674,57 +30007,88 @@ function resolveLink2(sourceFile, target) {
     return sourceFile;
   return resolve7(dirname7(sourceFile), withoutAnchor);
 }
-function validateTarget(ctx, sourceFile, target, linkLabel) {
-  const issues = [];
-  if (isExternalLink(target) && !target.startsWith("#"))
-    return issues;
-  if (isPlaceholderLink(target))
-    return issues;
-  const relSource = relPath(sourceFile, ctx.root);
-  const anchor = target.includes("#") ? target.split("#")[1]?.split("?")[0] ?? "" : "";
-  const pathPart = target.split("#")[0]?.split("?")[0] ?? "";
-  const resolved = resolveLink2(sourceFile, target);
-  const relTarget = relPath(resolved, ctx.root);
-  const skillMatch = SKILL_LINK_IN_TARGET_RE.exec(target);
-  if (skillMatch?.[1] && ctx.retiredSkills.has(skillMatch[1])) {
-    issues.push(issue("links", relSource, `references retired skill "${skillMatch[1]}/SKILL.md"`, {
-      link: linkLabel
-    }));
-    return issues;
-  }
-  if (target.includes("/SKILL.md")) {
-    const slug2 = skillMatch?.[1];
-    if (slug2 && !resolveSkillPath(ctx.skillIndex, ctx.root, slug2)) {
-      issues.push(issue("links", relSource, `missing skill "${slug2}/SKILL.md"`, {
-        link: linkLabel
-      }));
-      return issues;
-    }
-  }
-  if ((target.includes(".claude/agents/") || target.includes(".cursor/agents/")) && target.endsWith(".md")) {
-    const agentPath = resolved.endsWith(".md") ? resolved : `${resolved}.md`;
-    if (!existsSync15(agentPath)) {
-      issues.push(issue("links", relSource, "missing agent file", { link: linkLabel }));
-    }
-    return issues;
-  }
-  if (pathPart && !existsSync15(resolved)) {
-    issues.push(issue("links", relSource, `broken link → ${relTarget}`, {
-      link: linkLabel
-    }));
-    return issues;
-  }
-  if (anchor && existsSync15(resolved)) {
-    const targetContent = readFileSync12(resolved, "utf8");
-    const slugs = extractHeadingSlugs(targetContent, resolved);
-    const anchorSlug = slugifyAnchor(anchor);
-    if (!slugs.has(anchorSlug)) {
-      issues.push(issue("links", relSource, `broken anchor → #${anchor} in ${relTarget}`, {
-        link: linkLabel
-      }));
-    }
+function checkRetiredSkill(input) {
+  const skillMatch = SKILL_LINK_IN_TARGET_RE.exec(input.target);
+  const slug2 = skillMatch?.[1];
+  if (!(slug2 && input.ctx.retiredSkills.has(slug2)))
+    return null;
+  return issue("links", relPath(input.sourceFile, input.ctx.root), {
+    message: `references retired skill "${slug2}/SKILL.md"`,
+    link: input.linkLabel
+  });
+}
+function checkMissingSkill(input, relSource) {
+  if (!input.target.includes("/SKILL.md"))
+    return null;
+  const slug2 = SKILL_LINK_IN_TARGET_RE.exec(input.target)?.[1];
+  if (!(slug2 && !resolveSkillPath(input.ctx.skillIndex, input.ctx.root, slug2)))
+    return null;
+  return issue("links", relSource, {
+    message: `missing skill "${slug2}/SKILL.md"`,
+    link: input.linkLabel
+  });
+}
+function checkAgentFile(input, resolved, relSource) {
+  if (!((input.target.includes(".claude/agents/") || input.target.includes(".cursor/agents/")) && input.target.endsWith(".md"))) {
+    return null;
   }
-  return issues;
+  const agentPath = resolved.endsWith(".md") ? resolved : `${resolved}.md`;
+  if (existsSync15(agentPath))
+    return null;
+  return issue("links", relSource, { message: "missing agent file", link: input.linkLabel });
+}
+function checkBrokenPath(ctx) {
+  const { input, pathPart, resolved, relSource, relTarget } = ctx;
+  if (!(pathPart && !existsSync15(resolved)))
+    return null;
+  return issue("links", relSource, {
+    message: `broken link → ${relTarget}`,
+    link: input.linkLabel
+  });
+}
+function checkBrokenAnchor(ctx) {
+  const { input, anchor, resolved, relSource, relTarget } = ctx;
+  if (!(anchor && existsSync15(resolved)))
+    return null;
+  const targetContent = readFileSync12(resolved, "utf8");
+  const slugs = extractHeadingSlugs(targetContent, resolved);
+  const anchorSlug = slugifyAnchor(anchor);
+  if (slugs.has(anchorSlug))
+    return null;
+  return issue("links", relSource, {
+    message: `broken anchor → #${anchor} in ${relTarget}`,
+    link: input.linkLabel
+  });
+}
+function resolveTargetParts(sourceFile, target, root2) {
+  const relSource = relPath(sourceFile, root2);
+  const anchor = target.includes("#") ? target.split("#")[1]?.split("?")[0] ?? "" : "";
+  const pathPart = target.split("#")[0]?.split("?")[0] ?? "";
+  const resolved = resolveLink2(sourceFile, target);
+  const relTarget = relPath(resolved, root2);
+  return { relSource, anchor, pathPart, resolved, relTarget };
+}
+function validateTarget(input) {
+  const { ctx, sourceFile, target } = input;
+  if (isExternalLink(target) && !target.startsWith("#"))
+    return [];
+  if (isPlaceholderLink(target))
+    return [];
+  const parts = resolveTargetParts(sourceFile, target, ctx.root);
+  const retired = checkRetiredSkill(input);
+  if (retired)
+    return [retired];
+  const missingSkill = checkMissingSkill(input, parts.relSource);
+  if (missingSkill)
+    return [missingSkill];
+  const agent = checkAgentFile(input, parts.resolved, parts.relSource);
+  if (agent)
+    return [agent];
+  const brokenPath = checkBrokenPath({ input, ...parts });
+  if (brokenPath)
+    return [brokenPath];
+  const brokenAnchor = checkBrokenAnchor({ input, ...parts });
+  return brokenAnchor ? [brokenAnchor] : [];
 }
 function runLinksRule(ctx) {
   const issues = [];
@@ -29733,7 +30097,7 @@ function runLinksRule(ctx) {
     const links = extractLinksFromMarkdown(content3, filePath);
     for (const { target, line } of links) {
       const linkLabel = line ? `line ${line}` : target;
-      issues.push(...validateTarget(ctx, filePath, target, linkLabel));
+      issues.push(...validateTarget({ ctx, sourceFile: filePath, target, linkLabel }));
     }
   }
   return issues;
@@ -29741,6 +30105,44 @@ function runLinksRule(ctx) {
 var linksRule = { id: "links", run: runLinksRule };
 
 // src/audit/rules/prose-policy.ts
+function checkDraftEntry(input) {
+  const { rel, lines, entry, draftPrefixes } = input;
+  const issues = [];
+  for (let i = 0;i < lines.length; i++) {
+    if (entry.regex?.test(lines[i] ?? "") && !isDraftPlacementAllowed(rel, draftPrefixes)) {
+      issues.push(issue("prose-policy", rel, {
+        message: entry.message,
+        link: `line ${i + 1}`,
+        severity: entry.severity
+      }));
+    }
+  }
+  return issues;
+}
+function checkLineEntry(rel, lines, entry) {
+  const issues = [];
+  for (let i = 0;i < lines.length; i++) {
+    if (entry.regex?.test(lines[i] ?? "")) {
+      issues.push(issue("prose-policy", rel, {
+        message: entry.message,
+        link: `line ${i + 1}`,
+        severity: entry.severity
+      }));
+    }
+  }
+  return issues;
+}
+function checkPolicyEntry(input) {
+  const { rel, content: content3, lines, entry, draftPrefixes } = input;
+  if (entry.id === "draft-marker") {
+    return checkDraftEntry({ rel, lines, entry, draftPrefixes });
+  }
+  const isMultiline = entry.pattern?.includes("[\\s\\S]");
+  if (isMultiline) {
+    return entry.regex?.test(content3) ? [issue("prose-policy", rel, { message: entry.message, severity: entry.severity })] : [];
+  }
+  return checkLineEntry(rel, lines, entry);
+}
 function runProsePolicyRule(ctx) {
   if (ctx.policies.length === 0)
     return [];
@@ -29753,36 +30155,9 @@ function runProsePolicyRule(ctx) {
 `);
     const policies = policiesForFile(ctx.policies, rel);
     for (const entry of policies) {
-      if (entry.mode === "fingerprint")
-        continue;
-      if (!entry.regex)
+      if (entry.mode === "fingerprint" || !entry.regex)
         continue;
-      if (entry.id === "draft-marker") {
-        for (let i = 0;i < lines.length; i++) {
-          if (entry.regex.test(lines[i] ?? "") && !isDraftPlacementAllowed(rel, draftPrefixes)) {
-            issues.push(issue("prose-policy", rel, entry.message, {
-              link: `line ${i + 1}`,
-              severity: entry.severity
-            }));
-          }
-        }
-        continue;
-      }
-      const isMultiline = entry.pattern?.includes("[\\s\\S]");
-      if (isMultiline) {
-        if (entry.regex.test(content3)) {
-          issues.push(issue("prose-policy", rel, entry.message, { severity: entry.severity }));
-        }
-        continue;
-      }
-      for (let i = 0;i < lines.length; i++) {
-        if (entry.regex.test(lines[i] ?? "")) {
-          issues.push(issue("prose-policy", rel, entry.message, {
-            link: `line ${i + 1}`,
-            severity: entry.severity
-          }));
-        }
-      }
+      issues.push(...checkPolicyEntry({ rel, content: content3, lines, entry, draftPrefixes }));
     }
   }
   return issues;
@@ -29792,12 +30167,8 @@ var prosePolicyRule = { id: "prose-policy", run: runProsePolicyRule };
 // src/audit/rules/registry.ts
 import { existsSync as existsSync16, readFileSync as readFileSync13 } from "node:fs";
 import { join as join13 } from "node:path";
-function runRegistryRule(ctx) {
+function checkRegistryEntries(ctx) {
   const issues = [];
-  const registry = new Set(ctx.registryPaths);
-  if (ctx.registryHasTableHeader && ctx.registryPaths.length === 0) {
-    issues.push(issue("registry", REGISTRY_REL_PATH, "registry table header found but 0 rows parsed — check | Topic | Canonical file | format and link syntax"));
-  }
   for (const rel of ctx.registryPaths) {
     const abs = join13(ctx.root, rel);
     if (!existsSync16(abs)) {
@@ -29809,11 +30180,15 @@ function runRegistryRule(ctx) {
       issues.push(issue("registry", rel, "missing **Source of truth for** banner (required for registry entry)"));
     }
   }
+  return issues;
+}
+function checkUnregisteredBanners(ctx, registry) {
+  const issues = [];
   for (const filePath of ctx.files) {
     const rel = relPath(filePath, ctx.root);
     if (rel === REGISTRY_REL_PATH)
       continue;
-    if (!rel.endsWith(".md") && !rel.endsWith(".mdc"))
+    if (!(rel.endsWith(".md") || rel.endsWith(".mdc")))
       continue;
     const content3 = readFileSync13(filePath, "utf8");
     if (!SOURCE_OF_TRUTH_BANNER_LINE_RE.test(content3))
@@ -29824,6 +30199,16 @@ function runRegistryRule(ctx) {
   }
   return issues;
 }
+function runRegistryRule(ctx) {
+  const issues = [];
+  const registry = new Set(ctx.registryPaths);
+  if (ctx.registryHasTableHeader && ctx.registryPaths.length === 0) {
+    issues.push(issue("registry", REGISTRY_REL_PATH, "registry table header found but 0 rows parsed — check | Topic | Canonical file | format and link syntax"));
+  }
+  issues.push(...checkRegistryEntries(ctx));
+  issues.push(...checkUnregisteredBanners(ctx, registry));
+  return issues;
+}
 var registryRule = { id: "registry", run: runRegistryRule };
 
 // src/audit/rules/scan-gaps.ts
@@ -29835,7 +30220,10 @@ function runCoverageGapsRule(ctx) {
   for (const rel of candidates) {
     if (scanned.has(rel))
       continue;
-    issues.push(issue("coverage-gaps", rel, "markdown outside audit scan perimeter — extend .skeleton/config.yaml scan.include", { severity: "warning" }));
+    issues.push(issue("coverage-gaps", rel, {
+      message: "markdown outside audit scan perimeter — extend .skeleton/config.yaml scan.include",
+      severity: "warning"
+    }));
   }
   return issues;
 }
@@ -29905,70 +30293,79 @@ function scanFileForSkillLinks(ctx, filePath, index2) {
   }
   return issues;
 }
+function taxonomyIssuesForReadme(input) {
+  const { ctx, index: index2, skillRoot, diskSlugs, nonPublic } = input;
+  const readmePath = join14(ctx.root, skillRoot.relPath, "README.md");
+  if (!existsSync17(readmePath))
+    return [];
+  const readme = readFileSync14(readmePath, "utf8");
+  if (!readme.includes("## Taxonomy"))
+    return [];
+  const taxonomySlugs = parseReadmeTaxonomySlugs(readme);
+  const nestedSlugs = diskSlugs.filter((slug2) => existsSync17(join14(ctx.root, skillRoot.relPath, slug2, "SKILL.md")));
+  const foreign = new Set(index2.foreignSlugs);
+  const publicSlugs = nestedSlugs.filter((slug2) => !(nonPublic.has(slug2) || foreign.has(slug2)));
+  const relReadme = `${skillRoot.relPath}/README.md`;
+  const issues = [];
+  for (const slug2 of publicSlugs) {
+    if (!taxonomySlugs.includes(slug2)) {
+      issues.push(issue("skill-index", relReadme, `taxonomy missing public skill "${slug2}"`));
+    }
+  }
+  for (const slug2 of taxonomySlugs) {
+    if (!nestedSlugs.includes(slug2)) {
+      issues.push(issue("skill-index", relReadme, `taxonomy lists skill "${slug2}" with no SKILL.md on disk`));
+    }
+  }
+  return issues;
+}
 function validateReadmeTaxonomy(ctx, index2, diskSlugs) {
   const issues = [];
   const nonPublic = new Set(nonPublicSkills(ctx.config));
   for (const skillRoot of index2.roots) {
     if (skillRoot.kind !== "nested")
       continue;
-    const readmePath = join14(ctx.root, skillRoot.relPath, "README.md");
-    if (!existsSync17(readmePath))
-      continue;
-    const readme = readFileSync14(readmePath, "utf8");
-    if (!readme.includes("## Taxonomy"))
+    issues.push(...taxonomyIssuesForReadme({ ctx, index: index2, skillRoot, diskSlugs, nonPublic }));
+  }
+  return issues;
+}
+function slugsForRoot(skillRoot, index2, owned) {
+  return skillRoot.kind === "nested" ? index2.ownedSlugs : index2.flatSlugs.filter((slug2) => owned.has(slug2));
+}
+function auditSkillRoot(input) {
+  const { ctx, index: index2, skillRoot, owned } = input;
+  const issues = [];
+  const base = skillRoot.kind === "nested" ? join14(ctx.root, skillRoot.relPath) : ctx.root;
+  for (const slug2 of slugsForRoot(skillRoot, index2, owned)) {
+    const skillDir = join14(base, slug2);
+    if (!existsSync17(skillDir))
       continue;
-    const taxonomySlugs = parseReadmeTaxonomySlugs(readme);
-    const nestedSlugs = diskSlugs.filter((slug2) => existsSync17(join14(ctx.root, skillRoot.relPath, slug2, "SKILL.md")));
-    const foreign = new Set(index2.foreignSlugs);
-    const publicSlugs = nestedSlugs.filter((slug2) => !nonPublic.has(slug2) && !foreign.has(slug2));
-    const relReadme = `${skillRoot.relPath}/README.md`;
-    for (const slug2 of publicSlugs) {
-      if (!taxonomySlugs.includes(slug2)) {
-        issues.push(issue("skill-index", relReadme, `taxonomy missing public skill "${slug2}"`));
-      }
-    }
-    for (const slug2 of taxonomySlugs) {
-      if (!nestedSlugs.includes(slug2)) {
-        issues.push(issue("skill-index", relReadme, `taxonomy lists skill "${slug2}" with no SKILL.md on disk`));
-      }
+    for (const skillMd of walkSkillMarkdown(skillDir)) {
+      issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
     }
   }
   return issues;
 }
+function auditOwnedSkillFiles(ctx, index2) {
+  const owned = new Set(index2.ownedSlugs);
+  const issues = [];
+  for (const skillRoot of index2.roots) {
+    issues.push(...auditSkillRoot({ ctx, index: index2, skillRoot, owned }));
+  }
+  return issues;
+}
 function runSkillIndexRule(ctx) {
   const issues = [];
   const index2 = ctx.skillIndex;
   const diskSlugs = listSkillSlugs(index2);
   for (const warning of index2.provenance.warnings) {
-    issues.push(issue("skill-index", index2.provenance.lockfile ?? "skills-lock.json", `skill provenance: ${warning}`, {
+    issues.push(issue("skill-index", index2.provenance.lockfile ?? "skills-lock.json", {
+      message: `skill provenance: ${warning}`,
       severity: "warning"
     }));
   }
   issues.push(...validateReadmeTaxonomy(ctx, index2, diskSlugs));
-  const owned = new Set(index2.ownedSlugs);
-  for (const skillRoot of index2.roots) {
-    if (skillRoot.kind === "nested") {
-      for (const slug2 of index2.ownedSlugs) {
-        const skillDir = join14(ctx.root, skillRoot.relPath, slug2);
-        if (!existsSync17(skillDir))
-          continue;
-        for (const skillMd of walkSkillMarkdown(skillDir)) {
-          issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
-        }
-      }
-      continue;
-    }
-    for (const slug2 of index2.flatSlugs) {
-      if (!owned.has(slug2))
-        continue;
-      const skillDir = join14(ctx.root, slug2);
-      if (!existsSync17(skillDir))
-        continue;
-      for (const skillMd of walkSkillMarkdown(skillDir)) {
-        issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
-      }
-    }
-  }
+  issues.push(...auditOwnedSkillFiles(ctx, index2));
   return issues;
 }
 var skillIndexRule = { id: "skill-index", run: runSkillIndexRule };
@@ -29996,6 +30393,19 @@ var skillsRules = [
   prosePolicyRule
 ];
 var allRules = [...docsRules, ...skillsRules];
+function attachPluginRule(docs, skills, rule) {
+  const suites = rule.suites ?? ["docs"];
+  const inDocs = suites.includes("docs");
+  const inSkills = suites.includes("skills");
+  if (!(inDocs || inSkills)) {
+    const listed = suites.length === 0 ? "(empty)" : suites.join(", ");
+    throw new Error(`Plugin rule "${rule.id}" suites attach to no known suite (got ${listed}; allowed: docs, skills). ` + `"self" is the union of docs+skills — put the rule in docs and/or skills.`);
+  }
+  if (inDocs)
+    docs.push(rule);
+  if (inSkills)
+    skills.push(rule);
+}
 function assembleRules(pluginRules = []) {
   const coreIds = new Set(allRules.map((rule) => rule.id));
   const seenPlugin = new Set;
@@ -30008,17 +30418,7 @@ function assembleRules(pluginRules = []) {
   const docs = [...docsRules];
   const skills = [...skillsRules];
   for (const rule of pluginRules) {
-    const suites = rule.suites ?? ["docs"];
-    const inDocs = suites.includes("docs");
-    const inSkills = suites.includes("skills");
-    if (!inDocs && !inSkills) {
-      const listed = suites.length === 0 ? "(empty)" : suites.join(", ");
-      throw new Error(`Plugin rule "${rule.id}" suites attach to no known suite (got ${listed}; allowed: docs, skills). ` + `"self" is the union of docs+skills — put the rule in docs and/or skills.`);
-    }
-    if (inDocs)
-      docs.push(rule);
-    if (inSkills)
-      skills.push(rule);
+    attachPluginRule(docs, skills, rule);
   }
   const selfById = new Map;
   for (const rule of [...docs, ...skills]) {
@@ -30041,46 +30441,70 @@ function rulesForSuite(suite, pluginRules = []) {
 }
 
 // src/audit/run.ts
+function parseFixArg(argv, index2) {
+  const next = argv[index2 + 1];
+  if (next && !next.startsWith("-")) {
+    if (next !== "doc-meta" && next !== "anchors") {
+      throw new Error(`Unknown --fix kind: ${next}. Use --fix, --fix=doc-meta, or --fix=anchors.`);
+    }
+    return { fix: next, nextIndex: index2 + 1 };
+  }
+  return { fix: true, nextIndex: index2 };
+}
+function applyAuditFlag(input) {
+  const { state, arg, argv, index: index2 } = input;
+  if (arg.startsWith("--suite=")) {
+    state.suite = arg.slice("--suite=".length);
+    return index2;
+  }
+  if (arg === "--strict") {
+    state.strict = true;
+    return index2;
+  }
+  if (arg === "--json") {
+    state.json = true;
+    return index2;
+  }
+  if (arg === "--dry-run") {
+    state.dryRun = true;
+    return index2;
+  }
+  if (arg.startsWith("--dry-run=")) {
+    throw new Error("audit: use --dry-run (boolean flag), not --dry-run=<value>");
+  }
+  if (arg === "--fix") {
+    const parsed = parseFixArg(argv, index2);
+    state.fix = parsed.fix;
+    return parsed.nextIndex;
+  }
+  if (arg.startsWith("--fix=")) {
+    state.fix = arg.slice("--fix=".length);
+    return index2;
+  }
+  if (arg.startsWith("--paths=")) {
+    state.paths = arg.slice("--paths=".length).split(",").map((path2) => path2.trim()).filter(Boolean);
+    return index2;
+  }
+  if (arg.startsWith("--only=")) {
+    state.only = new Set(arg.slice("--only=".length).split(",").filter(Boolean));
+    return index2;
+  }
+  return index2;
+}
 function parseAuditArgs(argv) {
-  let suite = "docs";
-  let strict = false;
-  let json = false;
-  let dryRun = false;
-  let paths = [];
-  let only = null;
-  let fix = null;
+  const state = {
+    suite: "docs",
+    strict: false,
+    json: false,
+    dryRun: false,
+    paths: [],
+    only: null,
+    fix: null
+  };
   for (let i = 0;i < argv.length; i++) {
-    const arg = argv[i] ?? "";
-    if (arg.startsWith("--suite=")) {
-      suite = arg.slice("--suite=".length);
-    } else if (arg === "--strict") {
-      strict = true;
-    } else if (arg === "--json") {
-      json = true;
-    } else if (arg === "--dry-run") {
-      dryRun = true;
-    } else if (arg.startsWith("--dry-run=")) {
-      throw new Error("audit: use --dry-run (boolean flag), not --dry-run=<value>");
-    } else if (arg === "--fix") {
-      const next = argv[i + 1];
-      if (next && !next.startsWith("-")) {
-        if (next !== "doc-meta" && next !== "anchors") {
-          throw new Error(`Unknown --fix kind: ${next}. Use --fix, --fix=doc-meta, or --fix=anchors.`);
-        }
-        fix = next;
-        i++;
-      } else {
-        fix = true;
-      }
-    } else if (arg.startsWith("--fix=")) {
-      fix = arg.slice("--fix=".length);
-    } else if (arg.startsWith("--paths=")) {
-      paths = arg.slice("--paths=".length).split(",").map((path2) => path2.trim()).filter(Boolean);
-    } else if (arg.startsWith("--only=")) {
-      only = new Set(arg.slice("--only=".length).split(",").filter(Boolean));
-    }
+    i = applyAuditFlag({ state, arg: argv[i] ?? "", argv, index: i });
   }
-  return { suite, strict, json, paths, only, fix, dryRun };
+  return state;
 }
 function labelForSuite(suite) {
   switch (suite) {
@@ -30103,6 +30527,29 @@ function shouldRunRule(rule, options, pathScoped) {
     return false;
   return true;
 }
+async function runAuditFixes(options, ctx, loaded) {
+  if (options.fix === null || options.fix === undefined)
+    return null;
+  if (options.suite !== "docs") {
+    console.error("--fix is supported only for audit docs");
+    return 1;
+  }
+  const kinds = fixKindsForOnly(parseFixKinds(options.fix), options.only);
+  if (kinds.length === 0) {
+    console.error("--fix has no overlapping rules with --only (doc-meta → doc-meta, anchors → links).");
+    return 1;
+  }
+  applyFixes(ctx, { kinds, dryRun: options.dryRun });
+  if (!options.dryRun) {
+    const refreshed = createContext({
+      root: options.root,
+      paths: options.paths.length > 0 ? options.paths : undefined,
+      policies: loaded.policies
+    });
+    Object.assign(ctx, refreshed);
+  }
+  return null;
+}
 async function runAudit(options) {
   const pathScoped = options.paths.length > 0;
   const base = createContext({
@@ -30112,26 +30559,9 @@ async function runAudit(options) {
   });
   const loaded = await loadPlugins(base.root, base.config);
   const ctx = { ...base, policies: loaded.policies };
-  if (options.fix !== null && options.fix !== undefined) {
-    if (options.suite !== "docs") {
-      console.error("--fix is supported only for audit docs");
-      return 1;
-    }
-    const kinds = fixKindsForOnly(parseFixKinds(options.fix), options.only);
-    if (kinds.length === 0) {
-      console.error("--fix has no overlapping rules with --only (doc-meta → doc-meta, anchors → links).");
-      return 1;
-    }
-    applyFixes(ctx, { kinds, dryRun: options.dryRun });
-    if (!options.dryRun) {
-      const refreshed = createContext({
-        root: options.root,
-        paths: options.paths.length > 0 ? options.paths : undefined,
-        policies: loaded.policies
-      });
-      Object.assign(ctx, refreshed);
-    }
-  }
+  const fixExit = await runAuditFixes(options, ctx, loaded);
+  if (fixExit !== null)
+    return fixExit;
   const rules = rulesForSuite(options.suite, loaded.rules).filter((r) => !options.only || options.only.has(r.id));
   const skipGlobalsForPaths = pathScoped && !options.globalOnly;
   const issues = [];
@@ -30161,7 +30591,7 @@ function customizePathForSlug(root2, slug2) {
   return join15(customizeDir(root2), `${slug2}.md`);
 }
 function findCustomizeViaRegistry(root2, slug2) {
-  for (const rel of parseRegistryPaths(root2)) {
+  for (const rel of parseRegistry(root2).paths) {
     const expected = `${REGISTRY_DIR_REL}/customize/${slug2}.md`;
     if (normalizeRelPath(rel) === expected && existsSync18(join15(root2, rel))) {
       return rel;
@@ -30214,11 +30644,11 @@ function readAlwaysInclude(root2, basenames, skipBasename) {
 function resolveCustomize(root2, slug2) {
   const slugFile = resolveSlugFile(root2, slug2);
   const alwaysNames = alwaysIncludeBasenames(root2);
-  const skip = slugFile.path != null ? basename3(slugFile.path) : null;
+  const skip = slugFile.path !== null && slugFile.path !== undefined ? basename3(slugFile.path) : null;
   const always = readAlwaysInclude(root2, alwaysNames, skip);
   const parts = [];
   const included = [];
-  if (slugFile.content != null && slugFile.content.trim().length > 0) {
+  if (slugFile.content !== null && slugFile.content !== undefined && slugFile.content.trim().length > 0) {
     parts.push(slugFile.content.trimEnd());
     if (slugFile.path)
       included.push(slugFile.path);
@@ -30246,6 +30676,7 @@ function resolveCustomizeFromRoot(slug2, startDir) {
 }
 
 // src/hooks/run.ts
+import process3 from "node:process";
 function parsePayload(raw) {
   if (!raw.trim())
     return {};
@@ -30276,7 +30707,7 @@ function extractSkillSlug(payload) {
   }
   const path2 = extractPath(payload);
   if (path2)
-    return slugFromPath(path2, process.cwd());
+    return slugFromPath(path2, process3.cwd());
   return null;
 }
 function cursorResponse(content3) {
@@ -30331,6 +30762,7 @@ Customize override for /${slug2} (from ${from}):
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { copyFileSync, existsSync as existsSync22, mkdirSync as mkdirSync2, readFileSync as readFileSync17 } from "node:fs";
 import { join as join19 } from "node:path";
+import process4 from "node:process";
 
 // src/init/merge-hooks.ts
 import { existsSync as existsSync21, mkdirSync, readFileSync as readFileSync16, writeFileSync as writeFileSync2 } from "node:fs";
@@ -30400,7 +30832,7 @@ function walkNodeModulesCli(cwd) {
 }
 function isInsidePackageRoot(cwd) {
   const rel = relative10(PACKAGE_ROOT, resolve8(cwd)).replace(/\\/g, "/");
-  return rel === "" || !rel.startsWith("..") && !rel.startsWith("/");
+  return rel === "" || !(rel.startsWith("..") || rel.startsWith("/"));
 }
 function nodeCliHookCommand(cliPath) {
   return `node ${cliPath} hook customize`;
@@ -30450,6 +30882,36 @@ function writeJson(path2, value) {
 function deepEqual(a, b) {
   return JSON.stringify(a) === JSON.stringify(b);
 }
+function mergeExistingCursorHook(input) {
+  const { postToolUse, skeletonIdx, canonical, opts } = input;
+  const current = postToolUse[skeletonIdx];
+  const userEdited = current && !opts.forceHooks && (current.matcher !== canonical.matcher || !isSkeletonHookCommand(current.command));
+  if (userEdited) {
+    return {
+      platform: "cursor",
+      action: "conflict",
+      message: identityKey("cursor", "postToolUse", String(current.matcher ?? "Read"))
+    };
+  }
+  const extras = Object.fromEntries(Object.entries(current ?? {}).filter(([key]) => !["command", "matcher"].includes(key)));
+  const merged = { ...extras, ...canonical };
+  if (deepEqual(current, merged))
+    return { platform: "cursor", action: "skipped" };
+  postToolUse[skeletonIdx] = merged;
+  return null;
+}
+function persistCursorHooks(input) {
+  const { targetPath, existing, hooks, postToolUse, skeletonIdx } = input;
+  const next = {
+    ...existing,
+    version: existing.version ?? 1,
+    hooks: { ...hooks, postToolUse }
+  };
+  if (deepEqual(existing, next))
+    return { platform: "cursor", action: "skipped" };
+  writeJson(targetPath, next);
+  return { platform: "cursor", action: skeletonIdx >= 0 ? "updated" : "added" };
+}
 function mergeCursorHooks(targetPath, fragment, opts) {
   const existing = readJson(targetPath) ?? {};
   const hooks = existing.hooks ?? {};
@@ -30460,79 +30922,103 @@ function mergeCursorHooks(targetPath, fragment, opts) {
   const skeletonIdx = postToolUse.findIndex((entry) => isSkeletonHookCommand(entry.command));
   const canonical = { ...incoming, matcher: incoming.matcher ?? "Read" };
   if (skeletonIdx >= 0) {
-    const current = postToolUse[skeletonIdx];
-    const userEdited = current && !opts.forceHooks && (current.matcher !== canonical.matcher || !isSkeletonHookCommand(current.command));
-    if (userEdited) {
-      return {
-        platform: "cursor",
-        action: "conflict",
-        message: identityKey("cursor", "postToolUse", String(current.matcher ?? "Read"))
-      };
-    }
-    const extras = Object.fromEntries(Object.entries(current ?? {}).filter(([key]) => !["command", "matcher"].includes(key)));
-    const merged = { ...extras, ...canonical };
-    if (deepEqual(current, merged))
-      return { platform: "cursor", action: "skipped" };
-    postToolUse[skeletonIdx] = merged;
+    const conflict = mergeExistingCursorHook({ postToolUse, skeletonIdx, canonical, opts });
+    if (conflict)
+      return conflict;
   } else {
     postToolUse.push(canonical);
   }
-  const next = {
-    ...existing,
-    version: existing.version ?? 1,
-    hooks: { ...hooks, postToolUse }
-  };
-  if (deepEqual(existing, next))
-    return { platform: "cursor", action: "skipped" };
-  writeJson(targetPath, next);
-  return { platform: "cursor", action: skeletonIdx >= 0 ? "updated" : "added" };
+  return persistCursorHooks({ targetPath, existing, hooks, postToolUse, skeletonIdx });
 }
-function mergeNestedHooks(platform, targetPath, fragment, eventName, opts) {
-  const existing = readJson(targetPath) ?? {};
-  const rootHooks = existing.hooks ?? {};
-  const eventHooks = [...rootHooks[eventName] ?? []];
-  const incomingGroups = fragment.hooks?.[eventName] ?? [];
+function mergeExistingNestedSkeletonHook(input) {
+  const { hooks, skeletonIdx, incomingHook, opts, platform, eventName, matcher } = input;
+  const current = hooks[skeletonIdx];
+  const userEdited = current && !opts.forceHooks && (current.type !== incomingHook.type || !isSkeletonHookCommand(current.command));
+  if (userEdited) {
+    return {
+      changed: false,
+      conflict: {
+        platform,
+        action: "conflict",
+        message: identityKey(platform, eventName, matcher)
+      }
+    };
+  }
+  const extras = Object.fromEntries(Object.entries(current ?? {}).filter(([key]) => !["type", "command"].includes(key)));
+  const merged = { ...extras, ...incomingHook };
+  if (!deepEqual(current, merged)) {
+    hooks[skeletonIdx] = merged;
+    return { changed: true };
+  }
+  return { changed: false };
+}
+function mergeIncomingHookGroup(args) {
+  const { group, incomingHook, eventHooks, opts, platform, eventName } = args;
+  const matcher = group.matcher ?? "";
+  const groupIdx = eventHooks.findIndex((g) => g.matcher === matcher);
+  if (groupIdx < 0) {
+    eventHooks.push({ ...group, hooks: [{ ...incomingHook }] });
+    return { changed: true };
+  }
+  const existingGroup = eventHooks[groupIdx];
+  const hooks = [...existingGroup?.hooks ?? []];
+  const skeletonIdx = hooks.findIndex((entry) => isSkeletonHookCommand(entry.command));
+  if (skeletonIdx >= 0) {
+    const result = mergeExistingNestedSkeletonHook({
+      hooks,
+      skeletonIdx,
+      incomingHook,
+      opts,
+      platform,
+      eventName,
+      matcher
+    });
+    if (result.conflict)
+      return { changed: false, conflict: result.conflict };
+    eventHooks[groupIdx] = { ...existingGroup, matcher, hooks };
+    return { changed: result.changed };
+  }
+  hooks.push({ ...incomingHook });
+  eventHooks[groupIdx] = { ...existingGroup, matcher, hooks };
+  return { changed: true };
+}
+function mergeIncomingGroups(args) {
   let changed = false;
-  for (const incomingGroup of incomingGroups) {
-    const matcher = incomingGroup.matcher ?? "";
+  for (const incomingGroup of args.incomingGroups) {
     const incomingHook = incomingGroup.hooks?.[0];
     if (!incomingHook)
       continue;
-    const groupIdx = eventHooks.findIndex((group2) => group2.matcher === matcher);
-    if (groupIdx < 0) {
-      eventHooks.push({
-        ...incomingGroup,
-        hooks: [{ ...incomingHook }]
-      });
-      changed = true;
-      continue;
-    }
-    const group = eventHooks[groupIdx];
-    const hooks = [...group?.hooks ?? []];
-    const skeletonIdx = hooks.findIndex((entry) => isSkeletonHookCommand(entry.command));
-    if (skeletonIdx >= 0) {
-      const current = hooks[skeletonIdx];
-      const userEdited = current && !opts.forceHooks && (current.type !== incomingHook.type || !isSkeletonHookCommand(current.command));
-      if (userEdited) {
-        return {
-          platform,
-          action: "conflict",
-          message: identityKey(platform, eventName, matcher)
-        };
-      }
-      const extras = Object.fromEntries(Object.entries(current ?? {}).filter(([key]) => !["type", "command"].includes(key)));
-      const merged = { ...extras, ...incomingHook };
-      if (!deepEqual(current, merged)) {
-        hooks[skeletonIdx] = merged;
-        changed = true;
-      }
-    } else {
-      hooks.push({ ...incomingHook });
+    const result = mergeIncomingHookGroup({
+      group: incomingGroup,
+      incomingHook,
+      eventHooks: args.eventHooks,
+      opts: args.opts,
+      platform: args.platform,
+      eventName: args.eventName
+    });
+    if (result.conflict)
+      return { changed: false, conflict: result.conflict };
+    if (result.changed)
       changed = true;
-    }
-    eventHooks[groupIdx] = { ...group, matcher, hooks };
   }
-  if (!changed)
+  return { changed };
+}
+function mergeNestedHooks(args) {
+  const { platform, targetPath, eventName } = args;
+  const existing = readJson(targetPath) ?? {};
+  const rootHooks = existing.hooks ?? {};
+  const eventHooks = [...rootHooks[eventName] ?? []];
+  const incomingGroups = args.fragment.hooks?.[eventName] ?? [];
+  const result = mergeIncomingGroups({
+    incomingGroups,
+    eventHooks,
+    opts: args.opts,
+    platform,
+    eventName
+  });
+  if (result.conflict)
+    return result.conflict;
+  if (!result.changed)
     return { platform, action: "skipped" };
   const next = {
     ...existing,
@@ -30548,11 +31034,23 @@ function mergeHookConfigs(opts) {
   results.push(mergeCursorHooks(cursorPath, cursorFragment, opts));
   const claudePath = join18(opts.cwd, ".claude/settings.json");
   const claudeFragment = loadFragment("claude-settings.fragment.json", opts.hookCommand);
-  results.push(mergeNestedHooks("claude", claudePath, claudeFragment, "PostToolUse", opts));
+  results.push(mergeNestedHooks({
+    platform: "claude",
+    targetPath: claudePath,
+    fragment: claudeFragment,
+    eventName: "PostToolUse",
+    opts
+  }));
   const codexPath = join18(opts.cwd, ".codex/hooks.json");
   if (existsSync21(join18(opts.cwd, ".codex"))) {
     const codexFragment = loadFragment("codex-hooks.fragment.json", opts.hookCommand);
-    results.push(mergeNestedHooks("codex", codexPath, codexFragment, "PostToolUse", opts));
+    results.push(mergeNestedHooks({
+      platform: "codex",
+      targetPath: codexPath,
+      fragment: codexFragment,
+      eventName: "PostToolUse",
+      opts
+    }));
   } else {
     results.push({ platform: "codex", action: "skipped", message: "missing .codex directory" });
   }
@@ -30657,26 +31155,36 @@ function runSkillsAdd(args, cwd) {
   });
   return result.status ?? 1;
 }
+function logHookMergeResult(result) {
+  if (result.action === "conflict") {
+    console.error(`init: skipped ${result.platform} hook (user-edited) — re-run with --force-hooks to restore`);
+    return;
+  }
+  if (result.action === "added")
+    console.log(`init: added ${result.platform} customize hook`);
+  if (result.action === "updated")
+    console.log(`init: updated ${result.platform} customize hook`);
+}
+function installSkillsIfRequested(options, cwd) {
+  if (!(options.skills && !options.noSkills))
+    return "skipped";
+  const args = skillsAddArgs({ skillsFlags: options.skillsFlags });
+  const run = options.runSkillsCommand ?? runSkillsAdd;
+  const exitCode = run(args, cwd);
+  if (exitCode !== 0)
+    throw new Error(`skills install failed: npx ${args.join(" ")}`);
+  console.log("init: installed /skeleton skill");
+  return "installed";
+}
 function runInit(options = {}) {
-  const cwd = options.cwd ?? process.cwd();
+  const cwd = options.cwd ?? process4.cwd();
   assertPackageResolvable(cwd);
   const scaffold = writeScaffold(cwd);
   const hookCommand = resolveHookCommand(cwd);
-  const hooks = mergeHookConfigs({
-    cwd,
-    hookCommand,
-    forceHooks: options.forceHooks
-  });
+  const hooks = mergeHookConfigs({ cwd, hookCommand, forceHooks: options.forceHooks });
   const scripts = mergePackageJsonScripts(cwd);
-  for (const result of hooks) {
-    if (result.action === "conflict") {
-      console.error(`init: skipped ${result.platform} hook (user-edited) — re-run with --force-hooks to restore`);
-    } else if (result.action === "added") {
-      console.log(`init: added ${result.platform} customize hook`);
-    } else if (result.action === "updated") {
-      console.log(`init: updated ${result.platform} customize hook`);
-    }
-  }
+  for (const result of hooks)
+    logHookMergeResult(result);
   if (scaffold === "created") {
     console.log("init: wrote .skeleton/config.yaml and registry.md");
   } else {
@@ -30685,17 +31193,7 @@ function runInit(options = {}) {
   if (scripts === "updated") {
     console.log("init: merged validate/audit scripts into package.json");
   }
-  let skills = "skipped";
-  if (options.skills && !options.noSkills) {
-    const args = skillsAddArgs({ skillsFlags: options.skillsFlags });
-    const run = options.runSkillsCommand ?? runSkillsAdd;
-    const exitCode = run(args, cwd);
-    if (exitCode !== 0) {
-      throw new Error(`skills install failed: npx ${args.join(" ")}`);
-    }
-    skills = "installed";
-    console.log("init: installed /skeleton skill");
-  }
+  const skills = installSkillsIfRequested(options, cwd);
   return { scaffold, hooks, scripts, skills };
 }
 
@@ -30786,7 +31284,7 @@ function sourceFingerprint(tsAbs, seen = new Set) {
     hash.update("\x00");
     hash.update(content3);
     hash.update("\x00");
-    for (const dep of localImportPaths(abs, content3).sort()) {
+    for (const dep of localImportPaths(abs, content3).sort((a, b) => a.localeCompare(b))) {
       walk(dep);
     }
   }
@@ -30857,6 +31355,9 @@ async function runBuildPlugin(options = {}) {
   return { built, checked };
 }
 
+// src/references/run.ts
+import process6 from "node:process";
+
 // src/references/sync.ts
 import {
   existsSync as existsSync24,
@@ -30867,14 +31368,13 @@ import {
   writeFileSync as writeFileSync4
 } from "node:fs";
 import { dirname as dirname12, join as join20, relative as relative11 } from "node:path";
+import process5 from "node:process";
 function resolveOwnership(root2, override) {
   if (override !== undefined)
     return override;
   try {
     return loadConfig(root2).skillOwnership;
-  } catch {
-    return;
-  }
+  } catch {}
 }
 function walkMarkdownFiles2(dir, root2) {
   const files = [];
@@ -30894,89 +31394,97 @@ function walkMarkdownFiles2(dir, root2) {
   }
   return files;
 }
+function collectGeneratedInDir(input) {
+  const { dir, refsDir, skill, files } = input;
+  for (const entry of readdirSync6(dir, { withFileTypes: true })) {
+    const fullPath = join20(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectGeneratedInDir({ dir: fullPath, refsDir, skill, files });
+      continue;
+    }
+    if (!entry.name.endsWith(".md"))
+      continue;
+    const content3 = readFileSync19(fullPath, "utf8");
+    if (!isGeneratedReference(content3))
+      continue;
+    const refPath = normalizeRelPath(relative11(refsDir, fullPath));
+    files.push(generatedRefPath(skill, refPath));
+  }
+}
 function listGeneratedReferenceFiles(skillDir, skill) {
   const refsDir = join20(skillDir, "references");
   if (!existsSync24(refsDir))
     return [];
   const files = [];
-  const walk = (dir) => {
-    for (const entry of readdirSync6(dir, { withFileTypes: true })) {
-      const fullPath = join20(dir, entry.name);
-      if (entry.isDirectory()) {
-        walk(fullPath);
-        continue;
-      }
-      if (!entry.name.endsWith(".md"))
-        continue;
-      const content3 = readFileSync19(fullPath, "utf8");
-      if (isGeneratedReference(content3)) {
-        const refPath = normalizeRelPath(relative11(refsDir, fullPath));
-        files.push(generatedRefPath(skill, refPath));
-      }
-    }
-  };
-  walk(refsDir);
+  collectGeneratedInDir({ dir: refsDir, refsDir, skill, files });
   return files;
 }
+function syncGeneratedCopy(ctx, refPath) {
+  const { root: root2, plan, options, result } = ctx;
+  const sourceRel = normalizeRelPath(join20(CANONICAL_REFS_DIR, refPath));
+  const canonicalPath = join20(root2, sourceRel);
+  if (!existsSync24(canonicalPath)) {
+    throw new Error(`canonical reference missing: ${sourceRel}`);
+  }
+  const targetRel = generatedRefPath(plan.skill, refPath);
+  const targetPath = join20(root2, targetRel);
+  const canonicalContent = readFileSync19(canonicalPath, "utf8");
+  const nextContent = formatGeneratedHeader(sourceRel) + canonicalContent;
+  if (!options.dryRun)
+    mkdirSync3(dirname12(targetPath), { recursive: true });
+  const existing = existsSync24(targetPath) ? readFileSync19(targetPath, "utf8") : null;
+  if (existing !== nextContent) {
+    if (!options.dryRun)
+      writeFileSync4(targetPath, nextContent, "utf8");
+    result.written.push(targetRel);
+  } else {
+    result.skipped.push(targetRel);
+  }
+}
+function rewritePlanLinks(ctx, skillDir) {
+  const { root: root2, plan, options, result } = ctx;
+  if (options.rewriteLinks === false)
+    return;
+  for (const relFile of walkMarkdownFiles2(skillDir, root2)) {
+    const filePath = join20(root2, relFile);
+    const content3 = readFileSync19(filePath, "utf8");
+    const next = rewriteSharedRefLinks(content3, relFile, plan.skill);
+    if (next === content3)
+      continue;
+    if (!options.dryRun)
+      writeFileSync4(filePath, next, "utf8");
+    result.rewritten.push(relFile);
+  }
+}
+function removeStaleGenerated(ctx, skillDir) {
+  const { root: root2, plan, options, result } = ctx;
+  for (const generatedRel of listGeneratedReferenceFiles(skillDir, plan.skill)) {
+    const refPath = generatedRel.slice(`${plan.skill}/references/`.length);
+    if (plan.refPaths.has(refPath))
+      continue;
+    if (!options.dryRun)
+      unlinkSync(join20(root2, generatedRel));
+    result.removed.push(generatedRel);
+  }
+}
+function syncPlan(ctx) {
+  const skillDir = join20(ctx.root, ctx.plan.skill);
+  for (const refPath of ctx.plan.refPaths) {
+    syncGeneratedCopy(ctx, refPath);
+  }
+  rewritePlanLinks(ctx, skillDir);
+  removeStaleGenerated(ctx, skillDir);
+}
 function syncReferences(options = {}) {
-  const root2 = options.root ?? process.cwd();
+  const root2 = options.root ?? process5.cwd();
   const canonicalDir = join20(root2, CANONICAL_REFS_DIR);
   if (!existsSync24(canonicalDir)) {
     throw new Error(`canonical references dir not found: ${CANONICAL_REFS_DIR}`);
   }
-  const result = {
-    written: [],
-    rewritten: [],
-    removed: [],
-    skipped: []
-  };
+  const result = { written: [], rewritten: [], removed: [], skipped: [] };
   const plans = discoverSkillReferencePlans(root2, resolveOwnership(root2, options.ownership));
-  for (const plan of plans) {
-    const skillDir = join20(root2, plan.skill);
-    for (const refPath of plan.refPaths) {
-      const sourceRel = normalizeRelPath(join20(CANONICAL_REFS_DIR, refPath));
-      const canonicalPath = join20(root2, sourceRel);
-      if (!existsSync24(canonicalPath)) {
-        throw new Error(`canonical reference missing: ${sourceRel}`);
-      }
-      const targetRel = generatedRefPath(plan.skill, refPath);
-      const targetPath = join20(root2, targetRel);
-      const canonicalContent = readFileSync19(canonicalPath, "utf8");
-      const nextContent = formatGeneratedHeader(sourceRel) + canonicalContent;
-      if (!options.dryRun) {
-        mkdirSync3(dirname12(targetPath), { recursive: true });
-      }
-      const existing = existsSync24(targetPath) ? readFileSync19(targetPath, "utf8") : null;
-      if (existing !== nextContent) {
-        if (!options.dryRun)
-          writeFileSync4(targetPath, nextContent, "utf8");
-        result.written.push(targetRel);
-      } else {
-        result.skipped.push(targetRel);
-      }
-    }
-    if (options.rewriteLinks !== false) {
-      for (const relFile of walkMarkdownFiles2(skillDir, root2)) {
-        const filePath = join20(root2, relFile);
-        const content3 = readFileSync19(filePath, "utf8");
-        const next = rewriteSharedRefLinks(content3, relFile, plan.skill);
-        if (next !== content3) {
-          if (!options.dryRun)
-            writeFileSync4(filePath, next, "utf8");
-          result.rewritten.push(relFile);
-        }
-      }
-    }
-    for (const generatedRel of listGeneratedReferenceFiles(skillDir, plan.skill)) {
-      const refPath = generatedRel.slice(`${plan.skill}/references/`.length);
-      if (!plan.refPaths.has(refPath)) {
-        const fullPath = join20(root2, generatedRel);
-        if (!options.dryRun)
-          unlinkSync(fullPath);
-        result.removed.push(generatedRel);
-      }
-    }
-  }
+  for (const plan of plans)
+    syncPlan({ root: root2, plan, options, result });
   return result;
 }
 
@@ -30985,7 +31493,7 @@ function runReferencesSync(options = {}) {
   return syncReferences(options);
 }
 function runReferencesCheck(options = {}) {
-  const root2 = options.root ?? process.cwd();
+  const root2 = options.root ?? process6.cwd();
   let ownership;
   try {
     ownership = loadConfig(root2).skillOwnership;
@@ -30999,22 +31507,17 @@ function runReferencesCheck(options = {}) {
     label: "References check"
   });
 }
+function printSyncSection(label, files, prefix) {
+  if (files.length === 0)
+    return;
+  console.log(label);
+  for (const file of files)
+    console.log(`  ${prefix} ${file}`);
+}
 function printSyncResult(result) {
-  if (result.written.length > 0) {
-    console.log(`references sync: wrote ${result.written.length} file(s)`);
-    for (const file of result.written)
-      console.log(`  + ${file}`);
-  }
-  if (result.rewritten.length > 0) {
-    console.log(`references sync: rewrote links in ${result.rewritten.length} file(s)`);
-    for (const file of result.rewritten)
-      console.log(`  ~ ${file}`);
-  }
-  if (result.removed.length > 0) {
-    console.log(`references sync: removed ${result.removed.length} stale file(s)`);
-    for (const file of result.removed)
-      console.log(`  - ${file}`);
-  }
+  printSyncSection(`references sync: wrote ${result.written.length} file(s)`, result.written, "+");
+  printSyncSection(`references sync: rewrote links in ${result.rewritten.length} file(s)`, result.rewritten, "~");
+  printSyncSection(`references sync: removed ${result.removed.length} stale file(s)`, result.removed, "-");
   if (result.written.length === 0 && result.rewritten.length === 0 && result.removed.length === 0) {
     console.log(`references sync: up to date (${result.skipped.length} file(s) checked)`);
   }
@@ -31048,7 +31551,7 @@ function parseRegistryRows(content3) {
   for (const line of content3.split(`
 `)) {
     const match = REGISTRY_TABLE_ROW_RE2.exec(line);
-    if (!match?.[1] || !match[2])
+    if (!(match?.[1] && match[2]))
       continue;
     rows.push({ topic: match[1].trim(), link: match[2].trim(), line });
   }
@@ -31079,7 +31582,8 @@ ${REGISTRY_TABLE_HEADER}
 
 `;
 }
-function upsertRow(content3, topic, link2, section, root2) {
+function upsertRow(opts) {
+  const { content: content3, topic, link: link2, section, root: root2 } = opts;
   const rows = parseRegistryRows(content3);
   const targetPath = link2;
   const existingByLink = rows.find((row) => row.link === targetPath);
@@ -31119,13 +31623,19 @@ ${newLine}
 `;
   return { content: appended, action: "added" };
 }
-function registerPath(options) {
-  const root2 = options.root ?? findRepoRoot();
-  const relPath2 = normalizeRelPath(options.path);
-  const absPath = join21(root2, relPath2);
-  if (!existsSync25(absPath)) {
-    throw new Error(`File not found: ${relPath2}`);
+function printRegisterResult(options, result, relPath2) {
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (options.dryRun) {
+    console.log(`dry-run: would ${result.action} registry row for ${relPath2} → ${result.topic}`);
+  } else if (result.action === "noop") {
+    console.log(`register: ${relPath2} already registered (${result.topic})`);
+  } else {
+    console.log(`register: ${result.action} ${relPath2} → ${result.topic}`);
   }
+}
+function resolveRegistrationTopic(input) {
+  const { options, root: root2, relPath: relPath2, absPath } = input;
   const content3 = readFileSync20(absPath, "utf8");
   let topic = options.topic ?? extractTopic(content3);
   if (!topic) {
@@ -31133,13 +31643,36 @@ function registerPath(options) {
   }
   const registryLink = toRegistryLink(root2, absPath);
   topic = ensureCustomizeTopic(topic, registryLink);
-  const section = inferSection(registryLink);
+  return { topic, registryLink, section: inferSection(registryLink) };
+}
+function loadRegistryContent(root2) {
   const registryAbs = join21(root2, REGISTRY_REL_PATH);
-  let registryContent = existsSync25(registryAbs) ? readFileSync20(registryAbs, "utf8") : defaultRegistryContent();
-  if (!existsSync25(registryAbs) && !existsSync25(join21(root2, ".skeleton/config.yaml"))) {
+  if (!(existsSync25(registryAbs) || existsSync25(join21(root2, ".skeleton/config.yaml")))) {
     throw new Error("Missing .skeleton/config.yaml — run skeleton init first");
   }
-  const { content: updated, action } = upsertRow(registryContent, topic, registryLink, section, root2);
+  return existsSync25(registryAbs) ? readFileSync20(registryAbs, "utf8") : defaultRegistryContent();
+}
+function registerPath(options) {
+  const root2 = options.root ?? findRepoRoot();
+  const relPath2 = normalizeRelPath(options.path);
+  const absPath = join21(root2, relPath2);
+  if (!existsSync25(absPath)) {
+    throw new Error(`File not found: ${relPath2}`);
+  }
+  const { topic, registryLink, section } = resolveRegistrationTopic({
+    options,
+    root: root2,
+    relPath: relPath2,
+    absPath
+  });
+  let registryContent = loadRegistryContent(root2);
+  const { content: updated, action } = upsertRow({
+    content: registryContent,
+    topic,
+    link: registryLink,
+    section,
+    root: root2
+  });
   registryContent = updated;
   const result = {
     topic,
@@ -31148,6 +31681,7 @@ function registerPath(options) {
     action,
     warnOutsideScan: isOutsideScan(root2, relPath2)
   };
+  const registryAbs = join21(root2, REGISTRY_REL_PATH);
   if (!options.dryRun && action !== "noop") {
     const dir = dirname13(registryAbs);
     if (!existsSync25(dir)) {
@@ -31158,15 +31692,7 @@ function registerPath(options) {
   if (result.warnOutsideScan) {
     console.error(`warning: ${relPath2} is outside scan.include — register succeeded but audit will not scan it`);
   }
-  if (options.json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else if (options.dryRun) {
-    console.log(`dry-run: would ${action} registry row for ${relPath2} → ${topic}`);
-  } else if (action === "noop") {
-    console.log(`register: ${relPath2} already registered (${topic})`);
-  } else {
-    console.log(`register: ${action} ${relPath2} → ${topic}`);
-  }
+  printRegisterResult(options, result, relPath2);
   return result;
 }
 
@@ -31212,41 +31738,49 @@ function isSkeletonYamlCandidate(normalized, ext) {
     return false;
   return true;
 }
-function bucketFor(relPath2, root2, wiredPolicies, skillIndex) {
+function bucketForSkillPath(normalized, skillIndex) {
+  if (!isSkillPath(normalized, skillIndex))
+    return "skip";
+  if (isForeignSkillPath(normalized, skillIndex))
+    return "foreign-skill";
+  return "skills";
+}
+function bucketForDocPath(normalized, ctx) {
+  const ext = extname2(normalized).toLowerCase();
+  if (!DOC_EXTENSIONS.has(ext))
+    return "skip";
+  const config = loadConfig(ctx.root);
+  if (isInScanPerimeter(normalized, { config, root: ctx.root, skillIndex: ctx.skillIndex })) {
+    return "docs";
+  }
+  return "skip";
+}
+function bucketFor(relPath2, ctx) {
   const normalized = normalizeRelPath(relPath2);
   const ext = extname2(normalized).toLowerCase();
   const name = basename5(normalized);
-  if (SKIP_EXTENSIONS.has(ext))
-    return "skip";
-  if (COMMAND_CONFIG_NAMES.has(name))
+  if (SKIP_EXTENSIONS.has(ext) || COMMAND_CONFIG_NAMES.has(name))
     return "skip";
   if (isSkeletonYamlCandidate(normalized, ext)) {
-    if (wiredPolicies.has(normalized))
-      return "policy";
-    return "skip";
-  }
-  if (isSkillPath(normalized, skillIndex)) {
-    if (isForeignSkillPath(normalized, skillIndex))
-      return "foreign-skill";
-    return "skills";
-  }
-  if (DOC_EXTENSIONS.has(ext)) {
-    const config = loadConfig(root2);
-    if (isInScanPerimeter(normalized, config, root2, skillIndex))
-      return "docs";
-    return "skip";
-  }
+    return ctx.wiredPolicies.has(normalized) ? "policy" : "skip";
+  }
+  const skillBucket = bucketForSkillPath(normalized, ctx.skillIndex);
+  if (skillBucket !== "skip")
+    return skillBucket;
+  const docBucket = bucketForDocPath(normalized, ctx);
+  if (docBucket !== "skip")
+    return docBucket;
   if (SHELL_EXTENSIONS.has(ext))
     return "shell";
   if (ext === ".json")
     return "json";
   return "skip";
 }
-function isInScanPerimeter(relPath2, config, root2, skillIndex) {
-  const scanned = new Set(collectScanFiles(config, root2, skillIndex).map((abs) => relPath(abs, root2)));
+function isInScanPerimeter(relPath2, ctx) {
+  const scanned = new Set(collectScanFiles(ctx.config, ctx.root, ctx.skillIndex).map((abs) => relPath(abs, ctx.root)));
   if (scanned.has(relPath2))
     return true;
-  return config.scan.include.some((pattern) => matchesGlobScope(relPath2, pattern));
+  return ctx.config.scan.include.some((pattern) => matchesGlobScope(relPath2, pattern));
 }
 function parseJsonContent(content3) {
   try {
@@ -31298,27 +31832,30 @@ function resolvePaths(options) {
     root: options.root
   });
 }
-function codeValidationHint(root2) {
-  let pm2 = null;
+function packageManagerFromPackageJson(root2) {
   const pkgPath = join22(root2, "package.json");
-  if (existsSync26(pkgPath)) {
-    try {
-      const pkg = JSON.parse(readFileSync21(pkgPath, "utf8"));
-      const raw = pkg.packageManager?.split("@")[0];
-      if (raw === "bun" || raw === "npm" || raw === "pnpm" || raw === "yarn")
-        pm2 = raw;
-    } catch {}
-  }
-  if (!pm2) {
-    if (existsSync26(join22(root2, "bun.lock")) || existsSync26(join22(root2, "bun.lockb")))
-      pm2 = "bun";
-    else if (existsSync26(join22(root2, "pnpm-lock.yaml")))
-      pm2 = "pnpm";
-    else if (existsSync26(join22(root2, "yarn.lock")))
-      pm2 = "yarn";
-    else if (existsSync26(join22(root2, "package-lock.json")))
-      pm2 = "npm";
-  }
+  if (!existsSync26(pkgPath))
+    return null;
+  try {
+    const pkg = JSON.parse(readFileSync21(pkgPath, "utf8"));
+    const raw = pkg.packageManager?.split("@")[0];
+    if (raw === "bun" || raw === "npm" || raw === "pnpm" || raw === "yarn")
+      return raw;
+  } catch {}
+  return null;
+}
+function packageManagerFromLockfiles(root2) {
+  if (existsSync26(join22(root2, "bun.lock")) || existsSync26(join22(root2, "bun.lockb")))
+    return "bun";
+  if (existsSync26(join22(root2, "pnpm-lock.yaml")))
+    return "pnpm";
+  if (existsSync26(join22(root2, "yarn.lock")))
+    return "yarn";
+  if (existsSync26(join22(root2, "package-lock.json")))
+    return "npm";
+  return null;
+}
+function hintForPackageManager(pm2) {
   switch (pm2) {
     case "bun":
       return "  Run: bun test && bun run typecheck && bun run build";
@@ -31328,126 +31865,113 @@ function codeValidationHint(root2) {
       return "  Run: pnpm test && pnpm run typecheck";
     case "yarn":
       return "  Run: yarn test && yarn typecheck";
-    default:
-      return "  Run your local code validation gates (test + typecheck + build).";
   }
 }
-async function runValidateChanged(options = {}) {
-  const root2 = options.root ?? findRepoRoot();
-  const relPaths = resolvePaths(options);
-  if (relPaths.length === 0) {
-    console.log("validate changed: no changed files.");
-    return 0;
-  }
-  const config = loadConfig(root2);
-  const skillIndex = buildSkillIndex(root2, config.skillOwnership);
-  let wiredPolicies;
-  try {
-    wiredPolicies = await collectWiredPolicyRelPaths(root2, config);
-  } catch (error) {
-    console.error(`validate changed: ${error instanceof Error ? error.message : error}`);
-    return 1;
-  }
-  const buckets = {
-    docs: [],
-    skills: [],
-    shell: [],
-    json: [],
-    policy: []
-  };
-  let missing = 0;
-  let skipped = 0;
-  let foreignSkipped = 0;
-  const orphans = [];
-  for (const relPath2 of relPaths) {
-    const normalized = normalizeRelPath(relPath2);
-    const abs = join22(root2, normalized);
-    if (!existsSync26(abs)) {
-      missing++;
-      console.error(`validate changed: path not found: ${relPath2}`);
-      continue;
-    }
-    const ext = extname2(normalized).toLowerCase();
-    if (isSkeletonYamlCandidate(normalized, ext) && !wiredPolicies.has(normalized)) {
-      orphans.push(normalized);
-      continue;
-    }
-    const bucket = bucketFor(normalized, root2, wiredPolicies, skillIndex);
-    if (bucket === "skip") {
-      skipped++;
-      continue;
-    }
-    if (bucket === "foreign-skill") {
-      foreignSkipped++;
-      console.log(`validate changed: skipping foreign skill ${normalized} (owned upstream; see skills-lock.json / skillOwnership)`);
-      continue;
-    }
-    buckets[bucket].push(normalized);
+function codeValidationHint(root2) {
+  const pm2 = packageManagerFromPackageJson(root2) ?? packageManagerFromLockfiles(root2);
+  return pm2 ? hintForPackageManager(pm2) : "  Run your local code validation gates (test + typecheck + build).";
+}
+function emptyBuckets() {
+  return { docs: [], skills: [], shell: [], json: [], policy: [] };
+}
+function classifySinglePath(input) {
+  const { relPath: relPath2, ctx, state, bucketCtx } = input;
+  const normalized = normalizeRelPath(relPath2);
+  const abs = join22(ctx.root, normalized);
+  if (!existsSync26(abs)) {
+    state.missing++;
+    console.error(`validate changed: path not found: ${relPath2}`);
+    return;
   }
-  if (orphans.length > 0) {
-    for (const orphan of orphans) {
-      console.error(`validate changed: ${orphan} is under .skeleton/ but not referenced by any plugin policies glob.
-` + "  Export it from a plugin `policies` array (see docs/developer/plugins.md), or remove the file.");
-    }
-    return 1;
+  const ext = extname2(normalized).toLowerCase();
+  if (isSkeletonYamlCandidate(normalized, ext) && !ctx.wiredPolicies.has(normalized)) {
+    state.orphans.push(normalized);
+    return;
   }
-  const audited = buckets.docs.length + buckets.skills.length + buckets.shell.length + buckets.json.length + buckets.policy.length;
-  let exitCode = 0;
-  if (missing > 0 && audited === 0 && skipped === 0) {
-    console.error("validate changed: no paths existed on disk. Pass real paths or use --staged / --base.");
-    return 1;
+  const bucket = bucketFor(normalized, bucketCtx);
+  if (bucket === "skip") {
+    state.skipped++;
+    return;
   }
-  if (options.base) {
-    const globalExit = await runAudit({
-      suite: "self",
-      strict: false,
-      json: false,
-      paths: [],
-      only: null,
-      root: root2,
-      globalOnly: true
-    });
-    if (globalExit !== 0)
-      exitCode = 1;
+  if (bucket === "foreign-skill") {
+    state.foreignSkipped++;
+    console.log(`validate changed: skipping foreign skill ${normalized} (owned upstream; see skills-lock.json / skillOwnership)`);
+    return;
   }
-  if (skipped > 0 && audited === 0) {
-    console.error(`validate changed: all paths were skipped (code/config). This does not verify TypeScript or app code.
-` + codeValidationHint(root2));
-    return 1;
+  state.buckets[bucket].push(normalized);
+}
+function classifyPaths(ctx) {
+  const state = {
+    buckets: emptyBuckets(),
+    missing: 0,
+    skipped: 0,
+    foreignSkipped: 0,
+    orphans: []
+  };
+  const bucketCtx = {
+    root: ctx.root,
+    wiredPolicies: ctx.wiredPolicies,
+    skillIndex: ctx.skillIndex
+  };
+  for (const relPath2 of ctx.relPaths) {
+    classifySinglePath({ relPath: relPath2, ctx, state, bucketCtx });
   }
-  if (buckets.docs.length > 0) {
-    const docExit = await runAudit({
-      suite: "docs",
-      strict: false,
-      json: false,
-      paths: buckets.docs,
-      only: null,
-      root: root2,
-      pathScopedOnly: true
-    });
-    if (docExit !== 0)
-      exitCode = 1;
+  return state;
+}
+function reportOrphans(orphans) {
+  for (const orphan of orphans) {
+    console.error(`validate changed: ${orphan} is under .skeleton/ but not referenced by any plugin policies glob.
+` + "  Export it from a plugin `policies` array (see docs/developer/plugins.md), or remove the file.");
   }
-  if (buckets.skills.length > 0) {
-    if (!options.base) {
-      console.error(`validate changed: skill paths need the full skills suite (path-scoped skill rules are empty).
+  return 1;
+}
+async function runGlobalAuditIfBase(base, root2) {
+  if (!base)
+    return 0;
+  return runAudit({
+    suite: "self",
+    strict: false,
+    json: false,
+    paths: [],
+    only: null,
+    root: root2,
+    globalOnly: true
+  });
+}
+async function auditDocsBucket(paths, root2) {
+  if (paths.length === 0)
+    return 0;
+  return runAudit({
+    suite: "docs",
+    strict: false,
+    json: false,
+    paths,
+    only: null,
+    root: root2,
+    pathScopedOnly: true
+  });
+}
+async function auditSkillsBucket(paths, root2, base) {
+  if (paths.length === 0)
+    return 0;
+  if (!base) {
+    console.error(`validate changed: skill paths need the full skills suite (path-scoped skill rules are empty).
 ` + `  Run: skeleton audit skills
 ` + "  (audit self covers docs + .skeleton; excluded skill trees still need audit skills)");
-      exitCode = 1;
-    } else {
-      const skillExit = await runAudit({
-        suite: "skills",
-        strict: false,
-        json: false,
-        paths: buckets.skills,
-        only: null,
-        root: root2,
-        pathScopedOnly: true
-      });
-      if (skillExit !== 0)
-        exitCode = 1;
-    }
+    return 1;
   }
+  return runAudit({
+    suite: "skills",
+    strict: false,
+    json: false,
+    paths,
+    only: null,
+    root: root2,
+    pathScopedOnly: true
+  });
+}
+function validateLocalBuckets(buckets, root2) {
+  let exitCode = 0;
   for (const relPath2 of buckets.shell) {
     if (validateShell(relPath2, root2) !== 0)
       exitCode = 1;
@@ -31460,49 +31984,124 @@ async function runValidateChanged(options = {}) {
     if (validatePolicy(relPath2, root2) !== 0)
       exitCode = 1;
   }
-  if (buckets.policy.length > 0) {
-    if (options.base) {
-      const proseExit = await runAudit({
-        suite: "docs",
-        strict: false,
-        json: false,
-        paths: [],
-        only: null,
-        root: root2
-      });
-      if (proseExit !== 0)
-        exitCode = 1;
-      const skillPaths = listSkillMarkdownPaths(root2, skillIndex);
-      if (skillPaths.length > 0) {
-        const skillProseExit = await runAudit({
-          suite: "skills",
-          strict: false,
-          json: false,
-          paths: skillPaths,
-          only: null,
-          root: root2,
-          pathScopedOnly: true
-        });
-        if (skillProseExit !== 0)
-          exitCode = 1;
-      }
-    } else {
-      console.error(`validate changed: policy YAML changes need a full prose-policy pass (path-scoped docs are not enough).
+  return exitCode;
+}
+async function provePolicyProse(root2, skillIndex) {
+  const proseExit = await runAudit({
+    suite: "docs",
+    strict: false,
+    json: false,
+    paths: [],
+    only: null,
+    root: root2
+  });
+  if (proseExit !== 0)
+    return 1;
+  const skillPaths = listSkillMarkdownPaths(root2, skillIndex);
+  if (skillPaths.length === 0)
+    return 0;
+  const skillProseExit = await runAudit({
+    suite: "skills",
+    strict: false,
+    json: false,
+    paths: skillPaths,
+    only: null,
+    root: root2,
+    pathScopedOnly: true
+  });
+  return skillProseExit !== 0 ? 1 : 0;
+}
+async function auditPolicyBucket(ctx) {
+  if (ctx.policyPaths.length === 0)
+    return 0;
+  if (!ctx.base) {
+    console.error(`validate changed: policy YAML changes need a full prose-policy pass (path-scoped docs are not enough).
 ` + `  Run: skeleton audit docs
 ` + `  And: skeleton audit skills
 ` + "  (audit self covers docs + .skeleton; excluded skill trees still need audit skills)");
-      return 1;
-    }
+    return 1;
   }
-  if (exitCode === 0) {
-    const parts = [];
-    if (skipped > 0)
-      parts.push(`${skipped} path(s) skipped`);
-    if (foreignSkipped > 0)
-      parts.push(`${foreignSkipped} foreign skill(s) ignored`);
-    const note = parts.length > 0 ? ` (${parts.join(", ")})` : "";
-    console.log(`validate changed passed${note}.`);
+  return provePolicyProse(ctx.root, ctx.skillIndex);
+}
+function printSuccess2(skipped, foreignSkipped) {
+  const parts = [];
+  if (skipped > 0)
+    parts.push(`${skipped} path(s) skipped`);
+  if (foreignSkipped > 0)
+    parts.push(`${foreignSkipped} foreign skill(s) ignored`);
+  const note = parts.length > 0 ? ` (${parts.join(", ")})` : "";
+  console.log(`validate changed passed${note}.`);
+}
+function auditedPathCount(buckets) {
+  return buckets.docs.length + buckets.skills.length + buckets.shell.length + buckets.json.length + buckets.policy.length;
+}
+function earlyExitForClassification(classification, root2, base) {
+  const { buckets, missing, skipped, orphans } = classification;
+  if (orphans.length > 0)
+    return reportOrphans(orphans);
+  const audited = auditedPathCount(buckets);
+  if (missing > 0 && audited === 0 && skipped === 0) {
+    console.error("validate changed: no paths existed on disk. Pass real paths or use --staged / --base.");
+    return 1;
   }
+  if (skipped > 0 && audited === 0 && !base) {
+    console.error(`validate changed: all paths were skipped (code/config). This does not verify TypeScript or app code.
+` + codeValidationHint(root2));
+    return 1;
+  }
+  return null;
+}
+async function runBucketAudits(ctx) {
+  let exitCode = 0;
+  const mergeExit = (code3) => {
+    if (code3 !== 0)
+      exitCode = 1;
+  };
+  mergeExit(await runGlobalAuditIfBase(ctx.base, ctx.root));
+  mergeExit(await auditDocsBucket(ctx.buckets.docs, ctx.root));
+  mergeExit(await auditSkillsBucket(ctx.buckets.skills, ctx.root, ctx.base));
+  mergeExit(validateLocalBuckets(ctx.buckets, ctx.root));
+  mergeExit(await auditPolicyBucket({
+    policyPaths: ctx.buckets.policy,
+    root: ctx.root,
+    skillIndex: ctx.skillIndex,
+    base: ctx.base
+  }));
+  return exitCode;
+}
+async function runValidateChanged(options = {}) {
+  const root2 = options.root ?? findRepoRoot();
+  const relPaths = resolvePaths(options);
+  if (relPaths.length === 0) {
+    console.log("validate changed: no changed files.");
+    return 0;
+  }
+  const config = loadConfig(root2);
+  const skillIndex = buildSkillIndex(root2, config.skillOwnership);
+  let wiredPolicies;
+  try {
+    wiredPolicies = await collectWiredPolicyRelPaths(root2, config);
+  } catch (error) {
+    console.error(`validate changed: ${error instanceof Error ? error.message : error}`);
+    return 1;
+  }
+  const classification = classifyPaths({
+    relPaths,
+    root: root2,
+    wiredPolicies,
+    skillIndex
+  });
+  const earlyExit = earlyExitForClassification(classification, root2, options.base);
+  if (earlyExit !== null)
+    return earlyExit;
+  const exitCode = await runBucketAudits({
+    buckets: classification.buckets,
+    root: root2,
+    skillIndex,
+    base: options.base
+  });
+  if (exitCode === 0)
+    printSuccess2(classification.skipped, classification.foreignSkipped);
   return exitCode;
 }
 
@@ -31534,123 +32133,153 @@ function parseRegisterArgs(argv) {
       json = true;
     else if (arg.startsWith("--topic="))
       topic = arg.slice("--topic=".length);
-    else if (!arg.startsWith("-") && !path2)
+    else if (!(arg.startsWith("-") || path2))
       path2 = arg;
   }
   return { path: path2, topic, dryRun, json };
 }
+function parseValidateChangedArgs(rest) {
+  const paths = [];
+  let staged = false;
+  let base;
+  for (let i = 0;i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--staged")
+      staged = true;
+    else if (arg === "--base")
+      base = rest[++i];
+    else if (arg?.startsWith("--base="))
+      base = arg.slice("--base=".length);
+    else if (arg && !arg.startsWith("-"))
+      paths.push(arg);
+  }
+  return { paths, staged, base };
+}
+async function handleAudit(argv) {
+  const sub = argv[0];
+  if (sub !== "docs" && sub !== "self" && sub !== "skills") {
+    usage();
+    return 1;
+  }
+  const options = parseAuditArgs(argv.slice(1));
+  options.suite = sub;
+  return runAudit(options);
+}
+async function handleBuildPlugin(argv) {
+  const { entry, check } = parseBuildPluginArgs(argv);
+  const root2 = findRepoRoot();
+  const result = await runBuildPlugin({ root: root2, entry, check });
+  if (check) {
+    console.log(result.checked.length === 0 ? "build-plugin --check: no plugins configured." : `build-plugin --check: ${result.checked.length} plugin(s) up to date.`);
+  } else {
+    console.log(result.built.length === 0 ? "build-plugin: no plugins configured." : `build-plugin: built ${result.built.length} plugin(s).`);
+  }
+  return 0;
+}
+async function handleValidateChanged(argv) {
+  const { paths, staged, base } = parseValidateChangedArgs(argv);
+  return runValidateChanged({ paths, staged, base });
+}
+function handleRegister(argv) {
+  const opts = parseRegisterArgs(argv);
+  if (!opts.path) {
+    console.error("register: path required");
+    return 1;
+  }
+  registerPath({
+    path: opts.path,
+    topic: opts.topic,
+    dryRun: opts.dryRun,
+    json: opts.json
+  });
+  return 0;
+}
+function handleCustomizeResolve(argv) {
+  const slug2 = argv[0];
+  const json = argv.includes("--json");
+  if (!slug2) {
+    console.error("customize resolve: slug required");
+    return 1;
+  }
+  const result = resolveCustomizeFromRoot(slug2);
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.content) {
+    process7.stdout.write(result.content);
+  }
+  return 0;
+}
+function handleHook(argv) {
+  if (argv[0] !== "customize") {
+    usage();
+    return 1;
+  }
+  process7.stdout.write(runCustomizeHook(readFileSync22(0, "utf8")));
+  return 0;
+}
+function handleInit(argv) {
+  runInit(parseInitArgs(argv));
+  return 0;
+}
+function handleReferences(argv) {
+  const sub = argv[0];
+  if (sub === "sync") {
+    const dryRun = argv.includes("--dry-run");
+    const rewriteLinks = !argv.includes("--no-rewrite-links");
+    const result = runReferencesSync({ dryRun, rewriteLinks });
+    printSyncResult(result);
+    return 0;
+  }
+  if (sub === "check") {
+    return runReferencesCheck({
+      json: argv.includes("--json"),
+      strict: argv.includes("--strict")
+    });
+  }
+  usage();
+  return 1;
+}
+async function dispatchCommand(argv) {
+  const command = argv[0];
+  const rest = argv.slice(1);
+  switch (command) {
+    case "audit":
+      return handleAudit(rest);
+    case "build-plugin":
+      return handleBuildPlugin(rest);
+    case "validate":
+      return rest[0] === "changed" ? handleValidateChanged(rest.slice(1)) : null;
+    case "register":
+      return handleRegister(rest);
+    case "customize":
+      return rest[0] === "resolve" ? handleCustomizeResolve(rest.slice(1)) : null;
+    case "hook":
+      return handleHook(rest);
+    case "init":
+      return handleInit(rest);
+    case "references":
+      return handleReferences(rest);
+    default:
+      return null;
+  }
+}
 async function main() {
-  const argv = process.argv.slice(2);
+  const argv = process7.argv.slice(2);
   const command = argv[0];
   if (!command || command === "--help" || command === "-h") {
     usage();
-    process.exit(command ? 0 : 1);
+    process7.exit(command ? 0 : 1);
   }
   try {
-    if (command === "audit") {
-      const sub = argv[1];
-      if (sub !== "docs" && sub !== "self" && sub !== "skills") {
-        usage();
-        process.exit(1);
-      }
-      const options = parseAuditArgs(argv.slice(2));
-      options.suite = sub;
-      process.exit(await runAudit(options));
-    }
-    if (command === "build-plugin") {
-      const { entry, check } = parseBuildPluginArgs(argv.slice(1));
-      const root2 = findRepoRoot();
-      const result = await runBuildPlugin({ root: root2, entry, check });
-      if (check) {
-        console.log(result.checked.length === 0 ? "build-plugin --check: no plugins configured." : `build-plugin --check: ${result.checked.length} plugin(s) up to date.`);
-      } else {
-        console.log(result.built.length === 0 ? "build-plugin: no plugins configured." : `build-plugin: built ${result.built.length} plugin(s).`);
-      }
-      process.exit(0);
-    }
-    if (command === "validate" && argv[1] === "changed") {
-      const rest = argv.slice(2);
-      const paths = [];
-      let staged = false;
-      let base;
-      for (let i = 0;i < rest.length; i++) {
-        const arg = rest[i];
-        if (arg === "--staged")
-          staged = true;
-        else if (arg === "--base")
-          base = rest[++i];
-        else if (arg?.startsWith("--base="))
-          base = arg.slice("--base=".length);
-        else if (arg && !arg.startsWith("-"))
-          paths.push(arg);
-      }
-      process.exit(await runValidateChanged({ paths, staged, base }));
-    }
-    if (command === "register") {
-      const opts = parseRegisterArgs(argv.slice(1));
-      if (!opts.path) {
-        console.error("register: path required");
-        process.exit(1);
-      }
-      registerPath({
-        path: opts.path,
-        topic: opts.topic,
-        dryRun: opts.dryRun,
-        json: opts.json
-      });
-      process.exit(0);
-    }
-    if (command === "customize" && argv[1] === "resolve") {
-      const slug2 = argv[2];
-      const json = argv.includes("--json");
-      if (!slug2) {
-        console.error("customize resolve: slug required");
-        process.exit(1);
-      }
-      const result = resolveCustomizeFromRoot(slug2);
-      if (json) {
-        console.log(JSON.stringify(result, null, 2));
-      } else if (result.content) {
-        process.stdout.write(result.content);
-      }
-      process.exit(0);
-    }
-    if (command === "hook") {
-      if (argv[1] !== "customize") {
-        usage();
-        process.exit(1);
-      }
-      process.stdout.write(runCustomizeHook(readFileSync22(0, "utf8")));
-      process.exit(0);
-    }
-    if (command === "init") {
-      const parsed = parseInitArgs(argv.slice(1));
-      runInit(parsed);
-      process.exit(0);
-    }
-    if (command === "references") {
-      const sub = argv[1];
-      if (sub === "sync") {
-        const dryRun = argv.includes("--dry-run");
-        const rewriteLinks = !argv.includes("--no-rewrite-links");
-        const result = runReferencesSync({ dryRun, rewriteLinks });
-        printSyncResult(result);
-        process.exit(0);
-      }
-      if (sub === "check") {
-        process.exit(runReferencesCheck({
-          json: argv.includes("--json"),
-          strict: argv.includes("--strict")
-        }));
-      }
+    const exitCode = await dispatchCommand(argv);
+    if (exitCode === null) {
       usage();
-      process.exit(1);
+      process7.exit(1);
     }
-    usage();
-    process.exit(1);
+    process7.exit(exitCode);
   } catch (error) {
     console.error(String(error));
-    process.exit(1);
+    process7.exit(1);
   }
 }
 main();