@csark0812/skeleton 1.6.2 → 1.6.3

package/README.md

@@ -4,11 +4,13 @@
 
 <!-- doc-meta: owner=eng | last-reviewed=2026-08-16 -->
 
+<!-- code-fit: targets=src/cli.ts surface=audit,validate,catalog,init,build-plugin,references -->
+
 Agent repos get messy fast. Skills get copied around, docs disagree, links go stale, and nobody remembers which file is actually canonical.
 
 Skeleton is an SSOT linter for that layer. Define the contract once; Skeleton checks it locally and in CI. If a canonical doc disappears, SSOT markers drift, a skill index stops matching disk, or a generated reference gets edited by hand, the audit fails before merge.
 
-Think ESLint — for the docs and skills your agents rely on.
+Think ESLint — for the docs and skills your agents rely on. Primary CLI from `src/cli.ts`: `audit`, `validate`, `catalog`, `init`, `build-plugin`, `references` (plus `customize` / `hook` when using overlays). Commands dispatch through that entry file.
 
 Skeleton is **not** a runtime agent harness. It doesn't execute tools, enforce permissions, or manage memory. It checks whether the repo around those systems still holds together.
 

package/dist/cli.js

@@ -15652,7 +15652,7 @@ var require_extend = __commonJS((exports, module) => {
 });
 
 // src/cli.ts
-import { readFileSync as readFileSync24 } from "node:fs";
+import { readFileSync as readFileSync25 } from "node:fs";
 import process7 from "node:process";
 
 // src/audit/config/load.ts
@@ -30817,184 +30817,12 @@ function runBannedRule(ctx) {
 }
 var bannedRule = { id: "banned", run: runBannedRule };
 
-// src/audit/rules/doc-meta.ts
+// src/audit/rules/code-fit.ts
+import { relative as relative8 } from "node:path";
+
+// src/audit/core/code-fit.ts
 import { existsSync as existsSync13, readFileSync as readFileSync12 } 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} exceeds re-read cadence (>${staleDays} days) — re-affirm the paper or bump after review`,
-    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}) — review no longer covers latest edit; bump last-reviewed after review`,
-    severity: "warning"
-  });
-}
-function runDocMetaRule(ctx) {
-  const issues = [];
-  const today = new Date;
-  for (const relPath2 of ctx.docMetaPaths) {
-    const abs = join12(ctx.root, relPath2);
-    if (!existsSync13(abs))
-      continue;
-    const content3 = readFileSync12(abs, "utf8");
-    const banner = checkDocMetaBanner(relPath2, content3);
-    if (banner) {
-      issues.push(banner);
-      continue;
-    }
-    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;
-}
-var docMetaRule = { id: "doc-meta", run: runDocMetaRule };
-
-// src/audit/rules/links.ts
-import { existsSync as existsSync14, readFileSync as readFileSync13 } from "node:fs";
-import { dirname as dirname7, resolve as resolve6 } from "node:path";
-function resolveLink2(sourceFile, target) {
-  const withoutAnchor = target.split("#")[0]?.split("?")[0] ?? "";
-  if (!withoutAnchor)
-    return sourceFile;
-  return resolve6(dirname7(sourceFile), withoutAnchor);
-}
-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;
-  }
-  const agentPath = resolved.endsWith(".md") ? resolved : `${resolved}.md`;
-  if (existsSync14(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 && !existsSync14(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 && existsSync14(resolved)))
-    return null;
-  const targetContent = readFileSync13(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 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 = [];
-  for (const filePath of ctx.files) {
-    const content3 = readFileContent(filePath);
-    const links = extractLinksFromMarkdown(content3, filePath);
-    for (const { target, line } of links) {
-      const linkLabel = line ? `line ${line}` : target;
-      issues.push(...validateTarget({ ctx, sourceFile: filePath, target, linkLabel }));
-    }
-  }
-  return issues;
-}
-var linksRule = { id: "links", run: runLinksRule };
-
-// src/audit/rules/near-duplicate.ts
-import { readFileSync as readFileSync14 } from "node:fs";
-import { join as join13 } from "node:path";
 
 // src/audit/core/ssot-fit.ts
 var DEFAULT_SSOT_OVERLAP_MIN = 0.35;
@@ -31217,7 +31045,421 @@ function evaluateSsotFit(files, options = {}) {
   return issues;
 }
 
+// src/audit/core/code-fit.ts
+var DEFAULT_CODE_FIT_OVERLAP_MIN = 0.03;
+var DEFAULT_CODE_FIT_SURFACE_CAP = 25;
+var CODE_FIT_RE = /<!--\s*code-fit:\s*([^>]*?)-->/gi;
+function parseCodeFitMarkers(content3) {
+  const withoutCode = content3.replace(/```[\s\S]*?```/g, `
+`).replace(/`[^`\n]+`/g, " ");
+  const out = [];
+  for (const match of withoutCode.matchAll(CODE_FIT_RE)) {
+    const body = (match[1] ?? "").trim();
+    const parsed = parseMarkerBody(body);
+    if (parsed)
+      out.push(parsed);
+  }
+  return out;
+}
+function parseMarkerBody(body) {
+  const targetsMatch = /\btargets\s*=\s*([^\s]+)/i.exec(body);
+  if (!targetsMatch?.[1])
+    return null;
+  const targets = targetsMatch[1].split(",").map((t) => t.trim()).filter(Boolean);
+  if (targets.length === 0)
+    return null;
+  const surfaceMatch = /\bsurface\s*=\s*([^\s]+)/i.exec(body);
+  const surface = surfaceMatch?.[1] ? surfaceMatch[1].split(",").map((s) => s.trim()).filter(Boolean) : null;
+  return { targets, surface, raw: body };
+}
+function stripCodeNoise(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, `
+`).replace(/\/\/[^\n]*/g, `
+`).replace(/`(?:\\.|[^`\\])*`/g, " ").replace(/'(?:\\.|[^'\\])*'/g, " ").replace(/"(?:\\.|[^"\\])*"/g, " ");
+}
+function extractPublicSurface(source) {
+  const names = new Set;
+  for (const m of source.matchAll(/\bcase\s+["']([^"']+)["']\s*:/g)) {
+    if (m[1])
+      names.add(m[1]);
+  }
+  for (const m of source.matchAll(/\bexport\s+(?:async\s+)?(?:function|class|const|let|var|type|interface|enum)\s+([A-Za-z_$][\w$]*)/g)) {
+    if (m[1])
+      names.add(m[1]);
+  }
+  for (const m of source.matchAll(/\bexport\s+default\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/g)) {
+    if (m[1])
+      names.add(m[1]);
+  }
+  for (const m of source.matchAll(/\bexport\s+default\s+class\s+([A-Za-z_$][\w$]*)/g)) {
+    if (m[1])
+      names.add(m[1]);
+  }
+  collectExportListNames(source, names);
+  return [...names].sort();
+}
+function collectExportListNames(source, names) {
+  for (const m of source.matchAll(/\bexport\s*\{([^}]+)\}/g)) {
+    const inner = m[1] ?? "";
+    for (const part of inner.split(",")) {
+      addExportListPart(part.trim(), names);
+    }
+  }
+}
+function addExportListPart(cleaned, names) {
+  if (!cleaned || cleaned === "type" || cleaned === "typeof")
+    return;
+  const asMatch = /^([\w$]+)\s+as\s+([\w$]+)$/.exec(cleaned);
+  if (asMatch?.[2]) {
+    names.add(asMatch[2]);
+    return;
+  }
+  const typeAs = /^type\s+([\w$]+)(?:\s+as\s+([\w$]+))?$/.exec(cleaned);
+  if (typeAs?.[1]) {
+    names.add(typeAs[2] ?? typeAs[1]);
+    return;
+  }
+  const id = /^([\w$]+)$/.exec(cleaned);
+  if (id?.[1])
+    names.add(id[1]);
+}
+function codeIdentifiers(source) {
+  const stripped = stripCodeNoise(source);
+  return uniqueContentTokens(stripped.replace(/[^A-Za-z0-9_$]+/g, " ").replace(/_/g, " "));
+}
+function identifierOverlap(docContent, codeSource) {
+  const codeIds = new Set(codeIdentifiers(codeSource));
+  if (codeIds.size === 0)
+    return 1;
+  const docToks = uniqueContentTokens(docContent);
+  if (docToks.length === 0)
+    return 0;
+  let hit = 0;
+  for (const t of docToks) {
+    if (codeIds.has(t))
+      hit++;
+  }
+  return hit / docToks.length;
+}
+function nameInDoc(name, docContent) {
+  const docToks = new Set(contentTokens(docContent));
+  const parts = uniqueContentTokens(name.replace(/_/g, " "));
+  if (parts.length === 0) {
+    return docToks.has(name.toLowerCase());
+  }
+  const asToken = contentTokens(name);
+  if (asToken.some((t) => docToks.has(t)))
+    return true;
+  return parts.every((p) => docToks.has(p));
+}
+function nameExistsInTarget(name, autoSurface, source) {
+  if (autoSurface.includes(name))
+    return true;
+  const ids = new Set(extractPublicSurface(source));
+  if (ids.has(name))
+    return true;
+  const re = new RegExp(`\\b${escapeRegExp(name)}\\b`);
+  return re.test(source);
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function pushCoverageGaps(issues, input, effective) {
+  if (effective.length === 0)
+    return;
+  const missing = effective.filter((n) => !nameInDoc(n, input.docContent));
+  if (missing.length === 0)
+    return;
+  issues.push({
+    path: input.docPath,
+    message: `code-fit coverage: doc does not mention ${missing.map((m) => `"${m}"`).join(", ")} (from ${input.target})`,
+    link: input.target
+  });
+}
+function pushLexicalGap(issues, input, source) {
+  const overlapMin = input.options.overlapMin ?? DEFAULT_CODE_FIT_OVERLAP_MIN;
+  const overlap = identifierOverlap(input.docContent, source);
+  if (overlap + 0.000000001 >= overlapMin)
+    return;
+  issues.push({
+    path: input.docPath,
+    message: `code-fit lexical overlap ${(overlap * 100).toFixed(0)}% < ${(overlapMin * 100).toFixed(0)}% vs ${input.target}`,
+    link: input.target
+  });
+}
+function evaluateTarget(input) {
+  const issues = [];
+  const abs = join12(input.options.root, input.target);
+  if (!existsSync13(abs)) {
+    issues.push({
+      path: input.docPath,
+      message: `code-fit target missing: ${input.target}`,
+      link: input.target
+    });
+    return issues;
+  }
+  const source = readFileSync12(abs, "utf8");
+  const auto = extractPublicSurface(source);
+  const cap = input.options.surfaceCap ?? DEFAULT_CODE_FIT_SURFACE_CAP;
+  if (input.surfaceOverride === null && auto.length > cap) {
+    issues.push({
+      path: input.docPath,
+      message: `code-fit auto-surface has ${auto.length} names (cap ${cap}); add surface=… to the marker for ${input.target}`,
+      link: input.target
+    });
+    return issues;
+  }
+  if (input.surfaceOverride !== null) {
+    for (const name of input.surfaceOverride) {
+      if (!nameExistsInTarget(name, auto, source)) {
+        issues.push({
+          path: input.docPath,
+          message: `code-fit surface name "${name}" not found in ${input.target}`,
+          link: input.target
+        });
+      }
+    }
+  }
+  const effective = input.surfaceOverride !== null ? input.surfaceOverride : auto;
+  pushCoverageGaps(issues, input, effective);
+  pushLexicalGap(issues, input, source);
+  return issues;
+}
+function evaluateCodeFitDoc(docPath, docContent, options) {
+  const markers = parseCodeFitMarkers(docContent);
+  if (markers.length === 0)
+    return [];
+  const issues = [];
+  for (const marker of markers) {
+    if (marker.targets.length === 0) {
+      issues.push({
+        path: docPath,
+        message: "code-fit marker missing targets="
+      });
+      continue;
+    }
+    for (const target of marker.targets) {
+      issues.push(...evaluateTarget({
+        docPath,
+        docContent,
+        target,
+        surfaceOverride: marker.surface,
+        options
+      }));
+    }
+  }
+  return issues;
+}
+
+// src/audit/rules/code-fit.ts
+function runCodeFitRule(ctx) {
+  const overlapMin = ctx.config.docsLint?.codeFitOverlapMin ?? DEFAULT_CODE_FIT_OVERLAP_MIN;
+  const surfaceCap = ctx.config.docsLint?.codeFitSurfaceCap ?? DEFAULT_CODE_FIT_SURFACE_CAP;
+  const options = { root: ctx.root, overlapMin, surfaceCap };
+  const corpus = collectScanFiles(ctx.config, ctx.root, ctx.skillIndex);
+  const issues = [];
+  for (const abs of corpus) {
+    const content3 = readFileContent(abs);
+    if (!parseCodeFitMarkers(content3).length)
+      continue;
+    const rel = normalizeRelPath(relative8(ctx.root, abs));
+    for (const fit of evaluateCodeFitDoc(rel, content3, options)) {
+      issues.push(issue("code-fit", fit.path, {
+        message: fit.message,
+        link: fit.link,
+        severity: "error"
+      }));
+    }
+  }
+  return issues;
+}
+var codeFitRule = {
+  id: "code-fit",
+  alwaysRun: true,
+  run: runCodeFitRule
+};
+
+// src/audit/rules/doc-meta.ts
+import { existsSync as existsSync14, readFileSync as readFileSync13 } from "node:fs";
+import { join as join13 } 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} exceeds re-read cadence (>${staleDays} days) — re-affirm the paper or bump after review`,
+    severity: "warning"
+  });
+}
+function gitFreshnessMessage(reviewedStr, gitDate) {
+  return `content changed after last-reviewed ${reviewedStr} (git: ${gitDate}) — REQUIRED: re-read the entire document, then bump last-reviewed only if the content is still correct; do not change the date alone`;
+}
+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: gitFreshnessMessage(reviewedStr, gitDate),
+    severity: "warning"
+  });
+}
+function runDocMetaRule(ctx) {
+  const issues = [];
+  const today = new Date;
+  for (const relPath2 of ctx.docMetaPaths) {
+    const abs = join13(ctx.root, relPath2);
+    if (!existsSync14(abs))
+      continue;
+    const content3 = readFileSync13(abs, "utf8");
+    const banner = checkDocMetaBanner(relPath2, content3);
+    if (banner) {
+      issues.push(banner);
+      continue;
+    }
+    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;
+}
+var docMetaRule = { id: "doc-meta", run: runDocMetaRule };
+
+// src/audit/rules/links.ts
+import { existsSync as existsSync15, readFileSync as readFileSync14 } from "node:fs";
+import { dirname as dirname7, resolve as resolve6 } from "node:path";
+function resolveLink2(sourceFile, target) {
+  const withoutAnchor = target.split("#")[0]?.split("?")[0] ?? "";
+  if (!withoutAnchor)
+    return sourceFile;
+  return resolve6(dirname7(sourceFile), withoutAnchor);
+}
+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;
+  }
+  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 = readFileSync14(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 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 = [];
+  for (const filePath of ctx.files) {
+    const content3 = readFileContent(filePath);
+    const links = extractLinksFromMarkdown(content3, filePath);
+    for (const { target, line } of links) {
+      const linkLabel = line ? `line ${line}` : target;
+      issues.push(...validateTarget({ ctx, sourceFile: filePath, target, linkLabel }));
+    }
+  }
+  return issues;
+}
+var linksRule = { id: "links", run: runLinksRule };
+
 // src/audit/rules/near-duplicate.ts
+import { readFileSync as readFileSync15 } from "node:fs";
+import { join as join14 } from "node:path";
 var DEFAULT_THRESHOLD = 0.72;
 var SHINGLE_N = 3;
 function tokenize2(text5) {
@@ -31282,7 +31524,7 @@ function runNearDuplicateRule(ctx) {
   const ignored = ignoredPairSet(ctx);
   const entries = eligibleEntries(ctx);
   const fingerprints = entries.map((e) => {
-    const content3 = readFileSync14(join13(ctx.root, e.path), "utf8");
+    const content3 = readFileSync15(join14(ctx.root, e.path), "utf8");
     const tokens = tokenize2(bodyWithoutSsotNoise(content3));
     return {
       path: e.path,
@@ -31406,16 +31648,16 @@ function runScanRootsRule(ctx) {
 var scanRootsRule = { id: "scan-roots", run: runScanRootsRule };
 
 // src/audit/rules/skill-index.ts
-import { existsSync as existsSync15, readdirSync as readdirSync5, readFileSync as readFileSync15 } from "node:fs";
-import { join as join14, relative as relative8 } from "node:path";
+import { existsSync as existsSync16, readdirSync as readdirSync5, readFileSync as readFileSync16 } from "node:fs";
+import { join as join15, relative as relative9 } from "node:path";
 function walkSkillMarkdown(dir) {
   const files = [];
-  if (!existsSync15(dir))
+  if (!existsSync16(dir))
     return files;
   for (const entry of readdirSync5(dir, { withFileTypes: true })) {
     if (entry.name.startsWith("."))
       continue;
-    const fullPath = join14(dir, entry.name);
+    const fullPath = join15(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...walkSkillMarkdown(fullPath));
       continue;
@@ -31441,8 +31683,8 @@ function parseReadmeTaxonomySlugs(content3) {
 }
 function scanFileForSkillLinks(ctx, filePath, index2) {
   const issues = [];
-  const rel = relative8(ctx.root, filePath).replace(/\\/g, "/");
-  const content3 = readFileSync15(filePath, "utf8");
+  const rel = relative9(ctx.root, filePath).replace(/\\/g, "/");
+  const content3 = readFileSync16(filePath, "utf8");
   if (isGeneratedReference(content3))
     return issues;
   for (const match of content3.matchAll(SKILL_LINK_RE)) {
@@ -31457,14 +31699,14 @@ function scanFileForSkillLinks(ctx, filePath, index2) {
 }
 function taxonomyIssuesForReadme(input) {
   const { ctx, index: index2, skillRoot, diskSlugs, nonPublic } = input;
-  const readmePath = join14(ctx.root, skillRoot.relPath, "README.md");
-  if (!existsSync15(readmePath))
+  const readmePath = join15(ctx.root, skillRoot.relPath, "README.md");
+  if (!existsSync16(readmePath))
     return [];
-  const readme = readFileSync15(readmePath, "utf8");
+  const readme = readFileSync16(readmePath, "utf8");
   if (!readme.includes("## Taxonomy"))
     return [];
   const taxonomySlugs = parseReadmeTaxonomySlugs(readme);
-  const nestedSlugs = diskSlugs.filter((slug2) => existsSync15(join14(ctx.root, skillRoot.relPath, slug2, "SKILL.md")));
+  const nestedSlugs = diskSlugs.filter((slug2) => existsSync16(join15(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`;
@@ -31497,10 +31739,10 @@ function slugsForRoot(skillRoot, index2, owned) {
 function auditSkillRoot(input) {
   const { ctx, index: index2, skillRoot, owned } = input;
   const issues = [];
-  const base = skillRoot.kind === "nested" ? join14(ctx.root, skillRoot.relPath) : ctx.root;
+  const base = skillRoot.kind === "nested" ? join15(ctx.root, skillRoot.relPath) : ctx.root;
   for (const slug2 of slugsForRoot(skillRoot, index2, owned)) {
-    const skillDir = join14(base, slug2);
-    if (!existsSync15(skillDir))
+    const skillDir = join15(base, slug2);
+    if (!existsSync16(skillDir))
       continue;
     for (const skillMd of walkSkillMarkdown(skillDir)) {
       issues.push(...scanFileForSkillLinks(ctx, skillMd, index2));
@@ -31550,8 +31792,8 @@ function runSsotRule(ctx) {
 var ssotRule = { id: "ssot", run: runSsotRule };
 
 // src/audit/rules/ssot-summary.ts
-import { readFileSync as readFileSync16 } from "node:fs";
-import { join as join15 } from "node:path";
+import { readFileSync as readFileSync17 } from "node:fs";
+import { join as join16 } from "node:path";
 function runSsotSummaryRule(ctx) {
   const overlapMin = ctx.config.docsLint?.ssotOverlapMin ?? DEFAULT_SSOT_OVERLAP_MIN;
   const margin = ctx.config.docsLint?.ssotBetterMatchMargin ?? DEFAULT_BETTER_MATCH_MARGIN;
@@ -31559,7 +31801,7 @@ function runSsotSummaryRule(ctx) {
   const files = ctx.ssotEntries.map((entry) => ({
     path: entry.path,
     summary: entry.summary,
-    content: readFileSync16(join15(ctx.root, entry.path), "utf8")
+    content: readFileSync17(join16(ctx.root, entry.path), "utf8")
   }));
   return evaluateSsotFit(files, {
     overlapMin,
@@ -31582,6 +31824,7 @@ var docsRules = [
   { ...coverageGapsRule, global: true },
   linksRule,
   docMetaRule,
+  codeFitRule,
   { ...bannedRule, global: true },
   prosePolicyRule
 ];
@@ -31720,8 +31963,8 @@ function shouldRunRule(rule, options, pathScoped) {
   if (options.globalOnly)
     return Boolean(rule.global);
   if (options.pathScopedOnly)
-    return !rule.global;
-  if (pathScoped && rule.global)
+    return !rule.global || Boolean(rule.alwaysRun);
+  if (pathScoped && rule.global && !rule.alwaysRun)
     return false;
   return true;
 }
@@ -31779,8 +32022,8 @@ async function runAudit(options) {
 }
 
 // src/catalog.ts
-import { existsSync as existsSync16, mkdirSync, readFileSync as readFileSync17, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname8, join as join16 } from "node:path";
+import { existsSync as existsSync17, mkdirSync, readFileSync as readFileSync18, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname8, join as join17 } from "node:path";
 function renderCatalog(entries) {
   const lines = [
     "# Skeleton catalog",
@@ -31809,17 +32052,17 @@ function buildCatalogContent(root2) {
 }
 function checkCatalog(root2) {
   const { content: expected, entries } = buildCatalogContent(root2);
-  const abs = join16(root2, CATALOG_REL_PATH);
-  if (!existsSync16(abs)) {
+  const abs = join17(root2, CATALOG_REL_PATH);
+  if (!existsSync17(abs)) {
     return { ok: false, missing: true, stale: false, expected, actual: null, entries };
   }
-  const actual = readFileSync17(abs, "utf8");
+  const actual = readFileSync18(abs, "utf8");
   const stale = actual !== expected;
   return { ok: !stale, missing: false, stale, expected, actual, entries };
 }
 function writeCatalog(root2) {
   const { content: content3, entries } = buildCatalogContent(root2);
-  const abs = join16(root2, CATALOG_REL_PATH);
+  const abs = join17(root2, CATALOG_REL_PATH);
   mkdirSync(dirname8(abs), { recursive: true });
   writeFileSync2(abs, content3, "utf8");
   return { path: normalizeRelPath(CATALOG_REL_PATH), entries };
@@ -31845,20 +32088,20 @@ function runCatalogCli(options = {}) {
 }
 
 // src/customize/resolve.ts
-import { existsSync as existsSync17, readFileSync as readFileSync18 } from "node:fs";
-import { basename as basename3, join as join17, relative as relative9 } from "node:path";
+import { existsSync as existsSync18, readFileSync as readFileSync19 } from "node:fs";
+import { basename as basename3, join as join18, relative as relative10 } from "node:path";
 function customizeDir(root2) {
-  return join17(root2, REGISTRY_DIR_REL, "customize");
+  return join18(root2, REGISTRY_DIR_REL, "customize");
 }
 function customizePathForSlug(root2, slug2) {
-  return join17(customizeDir(root2), `${slug2}.md`);
+  return join18(customizeDir(root2), `${slug2}.md`);
 }
 function resolveSlugFile(root2, slug2) {
   const direct = customizePathForSlug(root2, slug2);
-  if (existsSync17(direct)) {
+  if (existsSync18(direct)) {
     return {
-      content: readFileSync18(direct, "utf8"),
-      path: normalizeRelPath(relative9(root2, direct))
+      content: readFileSync19(direct, "utf8"),
+      path: normalizeRelPath(relative10(root2, direct))
     };
   }
   return { content: null, path: null };
@@ -31879,11 +32122,11 @@ function readAlwaysInclude(root2, basenames, skipBasename) {
     const file = basename3(name);
     if (skipBasename && file === skipBasename)
       continue;
-    const abs = join17(dir, file);
-    if (!existsSync17(abs))
+    const abs = join18(dir, file);
+    if (!existsSync18(abs))
       continue;
-    parts.push(readFileSync18(abs, "utf8").trimEnd());
-    paths.push(normalizeRelPath(relative9(root2, abs)));
+    parts.push(readFileSync19(abs, "utf8").trimEnd());
+    paths.push(normalizeRelPath(relative10(root2, abs)));
   }
   return { parts, paths };
 }
@@ -32006,39 +32249,39 @@ Customize override for /${slug2} (from ${from}):
 
 // src/init/init.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { copyFileSync, existsSync as existsSync21, mkdirSync as mkdirSync3, readFileSync as readFileSync20 } from "node:fs";
-import { join as join21 } from "node:path";
+import { copyFileSync, existsSync as existsSync22, mkdirSync as mkdirSync3, readFileSync as readFileSync21 } from "node:fs";
+import { join as join22 } from "node:path";
 import process4 from "node:process";
 
 // src/init/merge-hooks.ts
-import { existsSync as existsSync20, mkdirSync as mkdirSync2, readFileSync as readFileSync19, writeFileSync as writeFileSync3 } from "node:fs";
-import { dirname as dirname11, join as join20 } from "node:path";
+import { existsSync as existsSync21, mkdirSync as mkdirSync2, readFileSync as readFileSync20, writeFileSync as writeFileSync3 } from "node:fs";
+import { dirname as dirname11, join as join21 } from "node:path";
 
 // src/init/package-paths.ts
-import { existsSync as existsSync18 } from "node:fs";
-import { dirname as dirname9, join as join18 } from "node:path";
+import { existsSync as existsSync19 } from "node:fs";
+import { dirname as dirname9, join as join19 } from "node:path";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 var MODULE_DIR = dirname9(fileURLToPath5(import.meta.url));
-var PACKAGE_ROOT_CANDIDATES = [join18(MODULE_DIR, "../.."), join18(MODULE_DIR, "..")];
+var PACKAGE_ROOT_CANDIDATES = [join19(MODULE_DIR, "../.."), join19(MODULE_DIR, "..")];
 function resolvePackageRoot() {
   for (const candidate of PACKAGE_ROOT_CANDIDATES) {
-    if (existsSync18(join18(candidate, "package.json")))
+    if (existsSync19(join19(candidate, "package.json")))
       return candidate;
   }
   throw new Error("Could not resolve @csark0812/skeleton package root");
 }
 function resolveTemplatesDir() {
-  const dir = join18(resolvePackageRoot(), "templates/skeleton-init");
-  if (!existsSync18(dir)) {
+  const dir = join19(resolvePackageRoot(), "templates/skeleton-init");
+  if (!existsSync19(dir)) {
     throw new Error("Missing templates/skeleton-init in package");
   }
   return dir;
 }
 
 // src/init/resolve-hook-command.ts
-import { existsSync as existsSync19, realpathSync as realpathSync6 } from "node:fs";
+import { existsSync as existsSync20, realpathSync as realpathSync6 } from "node:fs";
 import { createRequire as createRequire3 } from "node:module";
-import { dirname as dirname10, join as join19, relative as relative10, resolve as resolve7 } from "node:path";
+import { dirname as dirname10, join as join20, relative as relative11, resolve as resolve7 } from "node:path";
 var PACKAGE_NAME = "@csark0812/skeleton";
 var CLI_DIST = "dist/cli.js";
 var PACKAGE_ROOT = resolvePackageRoot();
@@ -32052,12 +32295,12 @@ function safeRealpath2(path2) {
   }
 }
 function toRepoRelative(cwd, absPath) {
-  const rel = relative10(safeRealpath2(cwd), safeRealpath2(absPath)).replace(/\\/g, "/");
+  const rel = relative11(safeRealpath2(cwd), safeRealpath2(absPath)).replace(/\\/g, "/");
   return rel.startsWith("..") ? absPath.replace(/\\/g, "/") : rel;
 }
 function tryResolvePublishedCli(cwd) {
   try {
-    const req = createRequire3(join19(cwd, "package.json"));
+    const req = createRequire3(join20(cwd, "package.json"));
     return req.resolve(`${PACKAGE_NAME}/${CLI_DIST}`);
   } catch {
     return null;
@@ -32066,8 +32309,8 @@ function tryResolvePublishedCli(cwd) {
 function walkNodeModulesCli(cwd) {
   let dir = cwd;
   while (true) {
-    const candidate = join19(dir, "node_modules", PACKAGE_NAME, CLI_DIST);
-    if (existsSync19(candidate))
+    const candidate = join20(dir, "node_modules", PACKAGE_NAME, CLI_DIST);
+    if (existsSync20(candidate))
       return candidate;
     const parent = dirname10(dir);
     if (parent === dir)
@@ -32077,7 +32320,7 @@ function walkNodeModulesCli(cwd) {
   return null;
 }
 function isInsidePackageRoot(cwd) {
-  const rel = relative10(PACKAGE_ROOT, resolve7(cwd)).replace(/\\/g, "/");
+  const rel = relative11(PACKAGE_ROOT, resolve7(cwd)).replace(/\\/g, "/");
   return rel === "" || !(rel.startsWith("..") || rel.startsWith("/"));
 }
 function nodeCliHookCommand(cliPath) {
@@ -32108,14 +32351,14 @@ function identityKey(platform, event, matcher) {
   return `skeleton:customize:${platform}:${event}:${matcher}`;
 }
 function loadFragment(name, hookCommand) {
-  const raw = readFileSync19(join20(TEMPLATES_DIR, name), "utf8");
+  const raw = readFileSync20(join21(TEMPLATES_DIR, name), "utf8");
   return JSON.parse(raw.replaceAll("{{HOOK_COMMAND}}", hookCommand));
 }
 function readJson(path2) {
-  if (!existsSync20(path2))
+  if (!existsSync21(path2))
     return null;
   try {
-    return JSON.parse(readFileSync19(path2, "utf8"));
+    return JSON.parse(readFileSync20(path2, "utf8"));
   } catch (error) {
     throw new Error(`Invalid JSON in ${path2}: ${error}`);
   }
@@ -32275,10 +32518,10 @@ function mergeNestedHooks(args) {
 }
 function mergeHookConfigs(opts) {
   const results = [];
-  const cursorPath = join20(opts.cwd, ".cursor/hooks.json");
+  const cursorPath = join21(opts.cwd, ".cursor/hooks.json");
   const cursorFragment = loadFragment("cursor-hooks.fragment.json", opts.hookCommand);
   results.push(mergeCursorHooks(cursorPath, cursorFragment, opts));
-  const claudePath = join20(opts.cwd, ".claude/settings.json");
+  const claudePath = join21(opts.cwd, ".claude/settings.json");
   const claudeFragment = loadFragment("claude-settings.fragment.json", opts.hookCommand);
   results.push(mergeNestedHooks({
     platform: "claude",
@@ -32287,8 +32530,8 @@ function mergeHookConfigs(opts) {
     eventName: "PostToolUse",
     opts
   }));
-  const codexPath = join20(opts.cwd, ".codex/hooks.json");
-  if (existsSync20(join20(opts.cwd, ".codex"))) {
+  const codexPath = join21(opts.cwd, ".codex/hooks.json");
+  if (existsSync21(join21(opts.cwd, ".codex"))) {
     const codexFragment = loadFragment("codex-hooks.fragment.json", opts.hookCommand);
     results.push(mergeNestedHooks({
       platform: "codex",
@@ -32303,11 +32546,11 @@ function mergeHookConfigs(opts) {
   return results;
 }
 function mergePackageJsonScripts(cwd) {
-  const pkgPath = join20(cwd, "package.json");
-  if (!existsSync20(pkgPath))
+  const pkgPath = join21(cwd, "package.json");
+  if (!existsSync21(pkgPath))
     return "skipped";
-  const fragment = JSON.parse(readFileSync19(join20(TEMPLATES_DIR, "package.json.scripts.fragment.json"), "utf8"));
-  const pkg = JSON.parse(readFileSync19(pkgPath, "utf8"));
+  const fragment = JSON.parse(readFileSync20(join21(TEMPLATES_DIR, "package.json.scripts.fragment.json"), "utf8"));
+  const pkg = JSON.parse(readFileSync20(pkgPath, "utf8"));
   pkg.scripts ??= {};
   let changed = false;
   for (const [key, value] of Object.entries(fragment)) {
@@ -32363,23 +32606,23 @@ function skillsAddArgs(options = {}) {
 // src/init/init.ts
 var TEMPLATES_DIR2 = resolveTemplatesDir();
 function writeScaffold(cwd) {
-  const skeletonDir2 = join21(cwd, ".skeleton");
+  const skeletonDir2 = join22(cwd, ".skeleton");
   mkdirSync3(skeletonDir2, { recursive: true });
   let created = false;
-  const tomlPath = join21(cwd, "skeleton.toml");
-  const legacyYaml = join21(skeletonDir2, "config.yaml");
-  if (!(existsSync21(tomlPath) || existsSync21(legacyYaml))) {
-    copyFileSync(join21(TEMPLATES_DIR2, "skeleton.toml"), tomlPath);
+  const tomlPath = join22(cwd, "skeleton.toml");
+  const legacyYaml = join22(skeletonDir2, "config.yaml");
+  if (!(existsSync22(tomlPath) || existsSync22(legacyYaml))) {
+    copyFileSync(join22(TEMPLATES_DIR2, "skeleton.toml"), tomlPath);
     created = true;
   }
-  mkdirSync3(join21(skeletonDir2, "customize"), { recursive: true });
+  mkdirSync3(join22(skeletonDir2, "customize"), { recursive: true });
   return created ? "created" : "skipped";
 }
 function assertPackageResolvable(cwd) {
-  const pkgPath = join21(cwd, "package.json");
-  if (!existsSync21(pkgPath))
+  const pkgPath = join22(cwd, "package.json");
+  if (!existsSync22(pkgPath))
     return;
-  const pkg = JSON.parse(readFileSync20(pkgPath, "utf8"));
+  const pkg = JSON.parse(readFileSync21(pkgPath, "utf8"));
   const hasDep = pkg.devDependencies?.["@csark0812/skeleton"] || pkg.dependencies?.["@csark0812/skeleton"];
   if (!hasDep) {
     try {
@@ -32463,7 +32706,7 @@ function parseInitArgs(argv) {
 // src/plugins/build.ts
 import { spawnSync as spawnSync3 } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync as existsSync22, readFileSync as readFileSync21, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync23, readFileSync as readFileSync22, writeFileSync as writeFileSync4 } from "node:fs";
 import { basename as basename4, dirname as dirname12, resolve as resolve8 } from "node:path";
 function parseBuildPluginArgs(argv) {
   let check = false;
@@ -32504,7 +32747,7 @@ function localImportPaths(tsAbs, content3) {
       candidates.push(resolve8(dir, spec), resolve8(dir, `${spec}.ts`), resolve8(dir, `${spec}.js`), resolve8(dir, spec, "index.ts"));
     }
     for (const candidate of candidates) {
-      if (existsSync22(candidate) && candidate.endsWith(".ts")) {
+      if (existsSync23(candidate) && candidate.endsWith(".ts")) {
         deps.push(candidate);
         break;
       }
@@ -32521,7 +32764,7 @@ function sourceFingerprint(tsAbs, seen = new Set) {
     if (seen.has(abs))
       return;
     seen.add(abs);
-    const content3 = readFileSync21(abs, "utf8");
+    const content3 = readFileSync22(abs, "utf8");
     hash.update(basename4(abs));
     hash.update("\x00");
     hash.update(content3);
@@ -32539,7 +32782,7 @@ function writeStamp(tsAbs, mjsAbs) {
 }
 async function buildOne(tsAbs) {
   const mjsAbs = mjsPathForTs(tsAbs);
-  if (!existsSync22(tsAbs)) {
+  if (!existsSync23(tsAbs)) {
     throw new Error(`Plugin source not found: ${tsAbs}`);
   }
   const proc = spawnSync3("bun", ["build", tsAbs, "--target=node", "--format=esm", `--outfile=${mjsAbs}`, "--packages=external"], { encoding: "utf8" });
@@ -32559,17 +32802,17 @@ ${proc.stderr || proc.stdout || `exit ${proc.status}`}`);
 }
 function checkOne(tsAbs) {
   const mjsAbs = mjsPathForTs(tsAbs);
-  if (!existsSync22(mjsAbs)) {
+  if (!existsSync23(mjsAbs)) {
     throw new Error(`Plugin not built: ${tsAbs} (missing ${mjsAbs}). Run: skeleton build-plugin`);
   }
-  if (!existsSync22(tsAbs)) {
+  if (!existsSync23(tsAbs)) {
     throw new Error(`Plugin source not found: ${tsAbs}`);
   }
   const stampAbs = stampPathForMjs(mjsAbs);
-  if (!existsSync22(stampAbs)) {
+  if (!existsSync23(stampAbs)) {
     throw new Error(`Plugin stale: ${mjsAbs} has no fingerprint stamp. Run: skeleton build-plugin`);
   }
-  const expected = readFileSync21(stampAbs, "utf8").trim();
+  const expected = readFileSync22(stampAbs, "utf8").trim();
   const actual = sourceFingerprint(tsAbs);
   if (expected !== actual) {
     throw new Error(`Plugin stale: ${mjsAbs} does not match ${tsAbs} (or local imports). Run: skeleton build-plugin`);
@@ -32602,14 +32845,14 @@ import process6 from "node:process";
 
 // src/references/sync.ts
 import {
-  existsSync as existsSync23,
+  existsSync as existsSync24,
   mkdirSync as mkdirSync4,
   readdirSync as readdirSync6,
-  readFileSync as readFileSync22,
+  readFileSync as readFileSync23,
   unlinkSync,
   writeFileSync as writeFileSync5
 } from "node:fs";
-import { dirname as dirname13, join as join22, relative as relative11 } from "node:path";
+import { dirname as dirname13, join as join23, relative as relative12 } from "node:path";
 import process5 from "node:process";
 function resolveOwnership(root2, override) {
   if (override !== undefined)
@@ -32620,18 +32863,18 @@ function resolveOwnership(root2, override) {
 }
 function walkMarkdownFiles2(dir, root2) {
   const files = [];
-  if (!existsSync23(dir))
+  if (!existsSync24(dir))
     return files;
   for (const entry of readdirSync6(dir, { withFileTypes: true })) {
     if (entry.name.startsWith("."))
       continue;
-    const fullPath = join22(dir, entry.name);
+    const fullPath = join23(dir, entry.name);
     if (entry.isDirectory()) {
       files.push(...walkMarkdownFiles2(fullPath, root2));
       continue;
     }
     if (entry.name.endsWith(".md")) {
-      files.push(normalizeRelPath(relative11(root2, fullPath)));
+      files.push(normalizeRelPath(relative12(root2, fullPath)));
     }
   }
   return files;
@@ -32639,23 +32882,23 @@ function walkMarkdownFiles2(dir, root2) {
 function collectGeneratedInDir(input) {
   const { dir, refsDir, skill, files } = input;
   for (const entry of readdirSync6(dir, { withFileTypes: true })) {
-    const fullPath = join22(dir, entry.name);
+    const fullPath = join23(dir, entry.name);
     if (entry.isDirectory()) {
       collectGeneratedInDir({ dir: fullPath, refsDir, skill, files });
       continue;
     }
     if (!entry.name.endsWith(".md"))
       continue;
-    const content3 = readFileSync22(fullPath, "utf8");
+    const content3 = readFileSync23(fullPath, "utf8");
     if (!isGeneratedReference(content3))
       continue;
-    const refPath = normalizeRelPath(relative11(refsDir, fullPath));
+    const refPath = normalizeRelPath(relative12(refsDir, fullPath));
     files.push(generatedRefPath(skill, refPath));
   }
 }
 function listGeneratedReferenceFiles(skillDir, skill) {
-  const refsDir = join22(skillDir, "references");
-  if (!existsSync23(refsDir))
+  const refsDir = join23(skillDir, "references");
+  if (!existsSync24(refsDir))
     return [];
   const files = [];
   collectGeneratedInDir({ dir: refsDir, refsDir, skill, files });
@@ -32663,18 +32906,18 @@ function listGeneratedReferenceFiles(skillDir, skill) {
 }
 function syncGeneratedCopy(ctx, refPath) {
   const { root: root2, plan, options, result } = ctx;
-  const sourceRel = normalizeRelPath(join22(CANONICAL_REFS_DIR, refPath));
-  const canonicalPath = join22(root2, sourceRel);
-  if (!existsSync23(canonicalPath)) {
+  const sourceRel = normalizeRelPath(join23(CANONICAL_REFS_DIR, refPath));
+  const canonicalPath = join23(root2, sourceRel);
+  if (!existsSync24(canonicalPath)) {
     throw new Error(`canonical reference missing: ${sourceRel}`);
   }
   const targetRel = generatedRefPath(plan.skill, refPath);
-  const targetPath = join22(root2, targetRel);
-  const canonicalContent = readFileSync22(canonicalPath, "utf8");
+  const targetPath = join23(root2, targetRel);
+  const canonicalContent = readFileSync23(canonicalPath, "utf8");
   const nextContent = formatGeneratedHeader(sourceRel) + canonicalContent;
   if (!options.dryRun)
     mkdirSync4(dirname13(targetPath), { recursive: true });
-  const existing = existsSync23(targetPath) ? readFileSync22(targetPath, "utf8") : null;
+  const existing = existsSync24(targetPath) ? readFileSync23(targetPath, "utf8") : null;
   if (existing !== nextContent) {
     if (!options.dryRun)
       writeFileSync5(targetPath, nextContent, "utf8");
@@ -32688,8 +32931,8 @@ function rewritePlanLinks(ctx, skillDir) {
   if (options.rewriteLinks === false)
     return;
   for (const relFile of walkMarkdownFiles2(skillDir, root2)) {
-    const filePath = join22(root2, relFile);
-    const content3 = readFileSync22(filePath, "utf8");
+    const filePath = join23(root2, relFile);
+    const content3 = readFileSync23(filePath, "utf8");
     const next = rewriteSharedRefLinks(content3, relFile, plan.skill);
     if (next === content3)
       continue;
@@ -32705,12 +32948,12 @@ function removeStaleGenerated(ctx, skillDir) {
     if (plan.refPaths.has(refPath))
       continue;
     if (!options.dryRun)
-      unlinkSync(join22(root2, generatedRel));
+      unlinkSync(join23(root2, generatedRel));
     result.removed.push(generatedRel);
   }
 }
 function syncPlan(ctx) {
-  const skillDir = join22(ctx.root, ctx.plan.skill);
+  const skillDir = join23(ctx.root, ctx.plan.skill);
   for (const refPath of ctx.plan.refPaths) {
     syncGeneratedCopy(ctx, refPath);
   }
@@ -32719,8 +32962,8 @@ function syncPlan(ctx) {
 }
 function syncReferences(options = {}) {
   const root2 = options.root ?? process5.cwd();
-  const canonicalDir = join22(root2, CANONICAL_REFS_DIR);
-  if (!existsSync23(canonicalDir)) {
+  const canonicalDir = join23(root2, CANONICAL_REFS_DIR);
+  if (!existsSync24(canonicalDir)) {
     throw new Error(`canonical references dir not found: ${CANONICAL_REFS_DIR}`);
   }
   const result = { written: [], rewritten: [], removed: [], skipped: [] };
@@ -32767,8 +33010,8 @@ function printSyncResult(result) {
 
 // src/validate/changed.ts
 import { spawnSync as spawnSync5 } from "node:child_process";
-import { existsSync as existsSync24, readFileSync as readFileSync23 } from "node:fs";
-import { basename as basename5, extname as extname2, join as join23 } from "node:path";
+import { existsSync as existsSync25, readFileSync as readFileSync24 } from "node:fs";
+import { basename as basename5, extname as extname2, join as join24 } from "node:path";
 
 // src/validate/git-diff.ts
 import { spawnSync as spawnSync4 } from "node:child_process";
@@ -32861,9 +33104,9 @@ function parseJsonContent(content3) {
   }
 }
 function validateJson(relPath2, root2) {
-  const abs = join23(root2, relPath2);
+  const abs = join24(root2, relPath2);
   try {
-    parseJsonContent(readFileSync23(abs, "utf8"));
+    parseJsonContent(readFileSync24(abs, "utf8"));
     return 0;
   } catch (error) {
     console.error(`validate changed: invalid JSON in ${relPath2}: ${error}`);
@@ -32871,9 +33114,9 @@ function validateJson(relPath2, root2) {
   }
 }
 function validatePolicy(relPath2, root2) {
-  const abs = join23(root2, relPath2);
+  const abs = join24(root2, relPath2);
   try {
-    loadPolicyFile(abs, readFileSync23(abs, "utf8"));
+    loadPolicyFile(abs, readFileSync24(abs, "utf8"));
     return 0;
   } catch (error) {
     console.error(`validate changed: invalid policy ${relPath2}: ${error}`);
@@ -32881,7 +33124,7 @@ function validatePolicy(relPath2, root2) {
   }
 }
 function validateShell(relPath2, root2) {
-  const abs = join23(root2, relPath2);
+  const abs = join24(root2, relPath2);
   const shellcheck = spawnSync5("shellcheck", [abs], { encoding: "utf8" });
   if (shellcheck.status === 0)
     return 0;
@@ -32902,11 +33145,11 @@ function resolvePaths(options) {
   });
 }
 function packageManagerFromPackageJson(root2) {
-  const pkgPath = join23(root2, "package.json");
-  if (!existsSync24(pkgPath))
+  const pkgPath = join24(root2, "package.json");
+  if (!existsSync25(pkgPath))
     return null;
   try {
-    const pkg = JSON.parse(readFileSync23(pkgPath, "utf8"));
+    const pkg = JSON.parse(readFileSync24(pkgPath, "utf8"));
     const raw = pkg.packageManager?.split("@")[0];
     if (raw === "bun" || raw === "npm" || raw === "pnpm" || raw === "yarn")
       return raw;
@@ -32914,13 +33157,13 @@ function packageManagerFromPackageJson(root2) {
   return null;
 }
 function packageManagerFromLockfiles(root2) {
-  if (existsSync24(join23(root2, "bun.lock")) || existsSync24(join23(root2, "bun.lockb")))
+  if (existsSync25(join24(root2, "bun.lock")) || existsSync25(join24(root2, "bun.lockb")))
     return "bun";
-  if (existsSync24(join23(root2, "pnpm-lock.yaml")))
+  if (existsSync25(join24(root2, "pnpm-lock.yaml")))
     return "pnpm";
-  if (existsSync24(join23(root2, "yarn.lock")))
+  if (existsSync25(join24(root2, "yarn.lock")))
     return "yarn";
-  if (existsSync24(join23(root2, "package-lock.json")))
+  if (existsSync25(join24(root2, "package-lock.json")))
     return "npm";
   return null;
 }
@@ -32946,8 +33189,8 @@ function emptyBuckets() {
 function classifySinglePath(input) {
   const { relPath: relPath2, ctx, state, bucketCtx } = input;
   const normalized = normalizeRelPath(relPath2);
-  const abs = join23(ctx.root, normalized);
-  if (!existsSync24(abs)) {
+  const abs = join24(ctx.root, normalized);
+  if (!existsSync25(abs)) {
     state.missing++;
     console.error(`validate changed: path not found: ${relPath2}`);
     return;
@@ -33261,7 +33504,7 @@ function handleHook(argv) {
     usage();
     return 1;
   }
-  process7.stdout.write(runCustomizeHook(readFileSync24(0, "utf8")));
+  process7.stdout.write(runCustomizeHook(readFileSync25(0, "utf8")));
   return 0;
 }
 function handleInit(argv) {

package/dist/plugin-types.d.ts

@@ -25,6 +25,8 @@ export type AuditSuite = "docs" | "skills";
 export interface AuditRule {
 	id: string;
 	global?: boolean;
+	/** When true, still run under `--paths` (see code-fit). */
+	alwaysRun?: boolean;
 	suites?: AuditSuite[];
 	run: (ctx: AuditContext) => Issue[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@csark0812/skeleton",
-	"version": "1.6.2",
+	"version": "1.6.3",
 	"description": "SSOT audit CLI for agent harness repos",
 	"type": "module",
 	"bin": {

package/schemas/config.schema.json

@@ -47,7 +47,7 @@
 		"docsLint": {
 			"type": "object",
 			"additionalProperties": false,
-			"description": "Near-duplicate and SSOT-summary lint tunables",
+			"description": "Near-duplicate, SSOT-summary, and code-fit lint tunables",
 			"properties": {
 				"nearDuplicateThreshold": {
 					"type": "number",
@@ -85,6 +85,17 @@
 					"type": "array",
 					"items": { "type": "string", "minLength": 1 },
 					"description": "Globs excluded from near-dupe / duplicate-SSOT"
+				},
+				"codeFitOverlapMin": {
+					"type": "number",
+					"minimum": 0,
+					"maximum": 1,
+					"description": "Min fraction of doc tokens that must also appear as code identifiers (default 0.03)"
+				},
+				"codeFitSurfaceCap": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Max auto-extracted surface names before surface= is required (default 25)"
 				}
 			}
 		},