@vibe-agent-toolkit/agent-skills 0.1.42 → 0.2.0-rc.10

package/dist/validators/packaging-validator.js

@@ -15,19 +15,21 @@
 import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
-import { CODE_REGISTRY, runSingleUnitValidation, runValidationFramework, } from '@vibe-agent-toolkit/agent-schema';
-import { DeferredArtifacts, parseMarkdown, ResourceRegistry } from '@vibe-agent-toolkit/resources';
-import { findProjectRoot, issueLocation, normalizedTmpdir, toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
+import { DeferredArtifacts, listingRefusalRemedy, loadConfig, parseFileCached, ResourceRegistry, } from '@vibe-agent-toolkit/resources';
+import { CODE_REGISTRY, runSingleUnitValidation, runValidationFramework, } from '@vibe-agent-toolkit/schema';
+import { findProjectRoot, issueLocation, normalizedTmpdir, toForwardSlash, toForwardSlashAnyPlatform, safePath, } from '@vibe-agent-toolkit/utils';
+import { DirectoryListingRefusedError } from '@vibe-agent-toolkit/utils/crawl';
 import { collectPreBuildGlobFindings, preBuildGlobFindingsToIssues } from '../files-config.js';
-import { packagedFileEntries, resolveTestInputDirs, testInputExcludeRules, testInputLinkIssues, } from '../test-input.js';
+import { conventionalSuiteProbe, partitionTestInputFileEntries, resolveTestInputDirs, testInputExcludeRules, testInputLinkIssues, } from '../test-input.js';
 import { walkLinkGraph } from '../walk-link-graph.js';
 import { observationToIssue, runCompatDetectors } from './compat-detectors.js';
 import { detectUndeclaredCrossSkillAuth } from './cross-skill-dependency-detection.js';
 import { validateFrontmatterRules, validateFrontmatterSchema } from './frontmatter-validation.js';
+import { collectUnqualifiedMcpToolIssues } from './mcp-tool-qualification.js';
 import { materializeIssue } from './rule-engine/index.js';
 import { SOURCE_ONLY_CODES } from './source-only-codes.js';
 import { VALIDATION_RULES, VALIDATION_THRESHOLDS, } from './validation-rules.js';
-import { deferredAssetsToIssues, walkerExclusionsToIssues } from './walker-to-issues.js';
+import { deferredAssetsToIssues, outsideSkillDirLinksToIssues, walkerExclusionsToIssues } from './walker-to-issues.js';
 /** Exclude reason constants to avoid duplicate string literals */
 const EXCLUDE_REASON_DIRECTORY = 'directory-target';
 const EXCLUDE_REASON_OUTSIDE_PROJECT = 'outside-project';
@@ -60,7 +62,7 @@ function validateFilesConfig(files, projectRoot, locationRoot) {
     const issues = [];
     const destSet = new Set();
     for (const entry of files) {
-        const normalized = toForwardSlash(entry.dest);
+        const normalized = toForwardSlashAnyPlatform(entry.dest);
         if (destSet.has(normalized)) {
             issues.push({
                 severity: 'error',
@@ -72,7 +74,6 @@ function validateFilesConfig(files, projectRoot, locationRoot) {
         // Check if an existing source resolves to a directory — a typed single-file
         // slot cannot be satisfied by a directory.
         const resolvedSource = safePath.resolve(safePath.join(projectRoot, entry.source));
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- resolvedSource derived from config-supplied path
         if (existsSync(resolvedSource) && statSync(resolvedSource).isDirectory()) {
             // Anchor at the resolved source, expressed in the run's ONE coordinate
             // system — not the raw config value, which is project-relative and so
@@ -88,10 +89,10 @@ function validateFilesConfig(files, projectRoot, locationRoot) {
  * anchored at a project-relative `location`.
  *
  * Thin wrapper over the shared {@link materializeIssue} so severity / fix /
- * reference come from the single CODE_REGISTRY source (issue #129 dedup); the
+ * reference come from the single CODE_REGISTRY source; the
  * caller supplies a fully-formed `message`.
  *
- * Deliberately NOT named `createRegistryIssue`: `@vibe-agent-toolkit/agent-schema`
+ * Deliberately NOT named `createRegistryIssue`: `@vibe-agent-toolkit/schema`
  * exports a function by that name whose third parameter is an EXTRAS OBJECT, not
  * a location string. Two same-named functions with incompatible third arguments
  * is a trap for anyone reading a call site.
@@ -99,13 +100,28 @@ function validateFilesConfig(files, projectRoot, locationRoot) {
 function registryIssueAt(code, message, location) {
     return materializeIssue(code, { message, location });
 }
+/**
+ * Settle the memoized refusals under THIS caller's policy — see {@link MemoizedRegistry}.
+ *
+ * @param refusals - What the one crawl of `projectRoot` was refused
+ * @param unreadable - This caller's ruling
+ * @param projectRoot - The crawl's root, for the refuse sentence
+ */
+function replayRefusals(refusals, unreadable, projectRoot) {
+    for (const refusal of refusals) {
+        if (unreadable === 'refuse') {
+            throw new DirectoryListingRefusedError(refusal, { root: projectRoot, remedy: listingRefusalRemedy(projectRoot) });
+        }
+        unreadable.degrade(refusal);
+    }
+}
 /**
  * Build a fresh ResourceRegistry for a single skill's projectRoot and resolve
  * internal links. Extracted so the skill validator can fall back to a private
  * registry when the caller does not supply a shared one.
  *
  * Crawls markdown AND HTML (`.html`/`.htm`) so the live audit/validate path
- * sees the same link graph the built path does (issue #129 AC2). The registry
+ * sees the same link graph the built path does. The registry
  * parses HTML via parse5 and surfaces its `local_file` links, so the walker
  * traverses HTML references and catches HTML broken links at source time — not
  * just at build time. (Previously the crawl was markdown-only, so source HTML
@@ -113,29 +129,89 @@ function registryIssueAt(code, message, location) {
  *
  * Exported so external callers (e.g. the inventory layer) can build a registry
  * once and pass it down rather than re-crawling per skill.
+ *
+ * ## Why the config is READ here rather than threaded in
+ *
+ * A collection may declare a `mimeType` that overrides `mime-type.ts`'s
+ * extension tables and so decides which parser runs; `ResourceRegistry` honours
+ * those declarations only when it was handed a config, and the projection lane
+ * behind `populationSource` reads them off the root. A config-less registry
+ * therefore disagrees with the population that enumerated it about whether a
+ * file is prose, inside a single command.
+ *
+ * Threading was considered and does not fit this function. Its callers discover
+ * `projectRoot` **per skill** (`findProjectRoot` from each SKILL.md's directory,
+ * and one `vat audit --user` run reached at least 72 distinct roots), so no
+ * caller holds one config that governs them all. Worse, the memo below is keyed
+ * on the root ALONE: an optional config argument would let two callers of one
+ * root disagree and silently share whichever registry was built first.
+ *
+ * Reading it here is what `createProjectRegistry` in `skill-packager.ts` already
+ * does, with the same `loadConfig`, for the same stated reason — "a registry
+ * built without config silently belongs to no collection, so a lane that built
+ * its own config-less registry rewrote frontmatter differently from the lane
+ * that used this one". One read per root per process, behind the memo, against a
+ * crawl that parses every document under it.
+ *
+ * ## A broken config falls back here, and is reported by the caller
+ *
+ * Unlike `createProjectRegistry`, this must NOT throw on a config that exists
+ * and will not parse. Its principal caller is `vat audit`, whose pinned
+ * behaviour is "tolerates, falls back to config-free validation" — a bulk linter
+ * over trees VAT does not own must not be aborted by someone else's YAML
+ * (`cli/test/integration/config-broken-behavior.integration.test.ts` is the map).
+ *
+ * The fallback is not the silent conflation that rule normally forbids, because
+ * nothing is being hidden: `vat audit` reads the same config at its own layer,
+ * catches `ConfigLoadError` there, and reports it. What this does is decline to
+ * abort a scan from four frames down. A config that will not parse also gives
+ * the projection lane no declarations, so the two lanes still AGREE — which is
+ * the property this function exists to hold.
  */
-export async function crawlAndResolveRegistry(projectRoot) {
+export async function crawlAndResolveRegistry(projectRoot, options) {
+    const { populationSource, unreadable } = options;
+    const cache = registryCacheFor(populationSource);
     const key = toForwardSlash(safePath.resolve(projectRoot));
-    const cached = registryCache.get(key);
+    const cached = cache.get(key);
     if (cached !== undefined) {
-        return cached;
+        const { registry, refusals } = await cached;
+        replayRefusals(refusals, unreadable, projectRoot);
+        return registry;
     }
     // The PROMISE is cached, not the resolved value, so two overlapping requests
     // for one root can never start two crawls.
     const pending = (async () => {
+        const config = await loadConfig(projectRoot).catch(() => undefined);
+        // Every refusal the crawl hands over is kept for the memo's later callers —
+        // see {@link MemoizedRegistry}. Under `'refuse'` the crawl throws instead and
+        // this stays empty.
+        const refusals = [];
+        const recorded = unreadable === 'refuse'
+            ? 'refuse'
+            : { degrade: (refusal) => { refusals.push(refusal); unreadable.degrade(refusal); } };
         const registry = await ResourceRegistry.fromCrawl({
             baseDir: projectRoot,
             include: ['**/*.md', '**/*.html', '**/*.htm'],
-        });
+            unreadable: recorded,
+            // Enumeration only. `ResourceRegistry.crawl` re-applies the include set
+            // above — and the crawl's default exclude — to whatever the source
+            // offers, through the same compiled matcher the walk itself uses, so a
+            // source that enumerates a whole tree still yields exactly this crawl's
+            // markdown and HTML. Handing this builder a projection is a cost change,
+            // not a scope change.
+            ...(populationSource !== undefined && { populationSource }),
+        }, config === undefined ? undefined : { config });
         registry.resolveLinks();
-        return registry;
+        return { registry, refusals };
     })();
-    registryCache.set(key, pending);
-    return pending;
+    cache.set(key, pending);
+    return (await pending).registry;
 }
 /**
- * Cache of (resolved project root → registry), so the crawl above is paid ONCE
- * per root per process rather than once per skill.
+ * Cache of (resolved project root → registry) for the INCUMBENT WALK, so the
+ * crawl above is paid ONCE per root per process rather than once per skill.
+ * Source-backed callers get {@link sourcedRegistryCache} instead, and the two
+ * never meet — see there for why that separation is the whole point.
  *
  * It lives beside the crawl because every caller wants the same thing and the
  * cost is a property of the crawl, not of any one lane. `vat audit` had already
@@ -149,8 +225,81 @@ export async function crawlAndResolveRegistry(projectRoot) {
  * Safe to hold for a process lifetime: every VAT entry point is a short-lived
  * CLI invocation. Note the crawl excludes build output (`BUILD_OUTPUT_GLOBS` via
  * the crawler's defaults), so packaging a skill mid-run cannot invalidate it.
+ *
+ * 🚨 That exclusion is ALSO the cause of a live defect, and this paragraph is the
+ * reason the defect must not be fixed by widening the crawl. The packager's
+ * post-build lane sees an EMPTY link graph because the built tree it validates
+ * falls under `**\/dist\/**` — measured, and now pinned by a committed test; the
+ * numbers, the control that proves the cause, and the fixture all live in the
+ * `runPostBuildValidation` docstring in `../skill-packager.ts`, and are not
+ * restated here.
+ *
+ * ⛔ The exclusion is the stated safety argument DIRECTLY ABOVE, for a memo shared
+ * by the audit lane, the validate lane AND the built lane. Widening the crawl so
+ * one lane can see its own output retracts that argument for every lane sharing
+ * this memo — it is not a one-lane fix, and it lands here, not there.
+ */
+const walkRegistryCache = new Map();
+/**
+ * The same memo for the SOURCE-BACKED lanes, keyed first by the population
+ * source's IDENTITY and only then by root.
+ *
+ * ## Why the source is part of the key
+ *
+ * This crawl is memoized for a process and SHARED across commands that do not
+ * know about each other: `vat skills build` reaches it per skill through
+ * {@link validateSkillForPackaging}, `vat audit` reaches it directly, and the
+ * pipeline oracles reach it as a lane. Keyed on the root ALONE, the FIRST
+ * caller's population binds for the whole process, and a later caller asking a
+ * different question transparently receives the earlier caller's answer — with
+ * nothing in any output saying so. The projection lane does not merely enumerate
+ * the same set faster: it sees uncommitted markdown, so it genuinely answers a
+ * different membership question and ADDS `LINK_BROKEN_FILE` findings. Serving
+ * one caller's answer to the other is a silent wrong answer in both directions.
+ *
+ * ## Why IDENTITY, and not a lane descriptor
+ *
+ * A `'walk' | 'projection'` tag would key two projection sources the same, and
+ * two projection sources can differ in their ignore oracle (a run with no
+ * `GitTracker` admits the ignored half of a tree), in which store answers them,
+ * and in whether that store is still OPEN — `withResourcePopulationSource`
+ * closes it when its bracket ends. A key that cannot see those differences is
+ * the same bug one level down. The closure itself can never be wrong about
+ * which of them it is.
+ *
+ * The win survives: one run holds ONE source closure for its whole bracket and
+ * hands the same one to every skill, so a `vat skills build` still pays a single
+ * crawl for the run rather than one per skill. Two independent callers cannot
+ * hold the same closure by accident, so they cannot collide.
+ *
+ * A `WeakMap` rather than a `Map` because the entry's useful life is the
+ * bracket's: once the source is unreachable its store is closed and its
+ * registries can never be served again, so holding them would be a leak with no
+ * upside. (`registryCacheFor` is what reads it; `resetPackagingRegistryCache`
+ * replaces it wholesale, since a `WeakMap` cannot be cleared in place.)
  */
-const registryCache = new Map();
+let sourcedRegistryCache = new WeakMap();
+/**
+ * The (root → registry) memo this call belongs in: the walk's, or the one
+ * private to this population source.
+ *
+ * Separate maps rather than a composite key, because the two are keyed on
+ * different KINDS — a path string and an object identity — and a composite key
+ * would have to stringify the source, which is exactly the information loss
+ * {@link sourcedRegistryCache} exists to avoid.
+ */
+function registryCacheFor(populationSource) {
+    if (populationSource === undefined) {
+        return walkRegistryCache;
+    }
+    const existing = sourcedRegistryCache.get(populationSource);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = new Map();
+    sourcedRegistryCache.set(populationSource, created);
+    return created;
+}
 /**
  * Drop every memoized registry.
  *
@@ -161,7 +310,34 @@ const registryCache = new Map();
  * as a fresh one. `resetAuditCaches` calls this alongside its own caches.
  */
 export function resetPackagingRegistryCache() {
-    registryCache.clear();
+    walkRegistryCache.clear();
+    // Both lanes, or the reset is a half-truth: a caller that reset the cache and
+    // then re-supplied the SAME source closure would be served the pre-reset parse
+    // of a tree it may have changed. A `WeakMap` has no `clear`, so it is replaced.
+    sourcedRegistryCache = new WeakMap();
+}
+/**
+ * The registry a skill is validated against: the caller's, when it covers the
+ * skill; otherwise one crawled here under the caller's `unreadable` ruling.
+ *
+ * No shared context is a single-skill lane whose result is acted on whole (the
+ * packager's post-build check passes one; a library caller that passes nothing
+ * is the same shape): it refuses. A caller with a context has ruled on
+ * `shared.unreadable` — see that field.
+ *
+ * @param skillPath - Path to SKILL.md
+ * @param projectRoot - The root the fallback crawl covers
+ * @param shared - The batching caller's context, if any
+ * @returns A registry whose links are resolved and that covers `skillPath`
+ */
+async function registryForSkill(skillPath, projectRoot, shared) {
+    if (shared?.registry !== undefined && registryCoversSkill(shared.registry, skillPath)) {
+        return shared.registry;
+    }
+    return crawlAndResolveRegistry(projectRoot, {
+        unreadable: shared === undefined ? 'refuse' : shared.unreadable,
+        ...(shared?.populationSource !== undefined && { populationSource: shared.populationSource }),
+    });
 }
 /**
  * True iff the shared registry's baseDir is an ancestor of (or equals) the
@@ -181,6 +357,34 @@ function registryCoversSkill(registry, skillPath) {
     // eslint-disable-next-line local/no-path-startswith -- both sides normalized via toForwardSlash above
     return skillDir.startsWith(`${normalizedBase}/`);
 }
+/**
+ * The refusal for a matched file that has no frontmatter object — either no
+ * `---` block at all, or one whose YAML did not parse (`frontmatterError`).
+ *
+ * Either way the file is not a skill, and it is refused with the SAME
+ * non-overridable code `validateSkill` in skill-validator.ts emits for it:
+ * `SKILL_MISSING_FRONTMATTER` has no CODE_REGISTRY entry, so the framework's
+ * `finalize()` passes it through and `validation.severity` cannot name it.
+ *
+ * This refusal used to be absent from the packaging lane — its frontmatter
+ * checks ran only `if (parseResult.frontmatter)` — so a plain `# Readme` a
+ * `skills.include` glob drifted onto, or a SKILL.md that lost its fence, ran
+ * zero frontmatter checks and came back `success` under its H1 as a name:
+ * `vat skills validate`, `vat validate` and `vat verify` were green on a
+ * project that shipped no skill.
+ */
+function missingFrontmatterIssue(frontmatterError, location) {
+    return {
+        severity: 'error',
+        code: 'SKILL_MISSING_FRONTMATTER',
+        message: frontmatterError === undefined
+            ? 'No YAML frontmatter found — a skill starts with a `---` block that names and describes it'
+            : `Frontmatter did not parse as YAML: ${frontmatterError}`,
+        location,
+        line: 1,
+        fix: 'Add YAML frontmatter with name and description fields, or narrow `skills.include` so it no longer matches this file',
+    };
+}
 /**
  * Validate a skill for packaging
  *
@@ -201,7 +405,7 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     // Validation-POLICY boundary (config root -> git root -> skill dir): what is
     // "outside the project", where `files:` sources resolve from, what the
     // registry crawls. Library fallback to skill dir keeps callers null-safe; CLI
-    // command boundary owns any user-facing warning. See plan 2026-05-17.
+    // command boundary owns any user-facing warning.
     const projectRoot = findProjectRoot(dirname(skillPath)) ?? dirname(skillPath);
     // ANCHOR base — deliberately a separate variable from projectRoot above.
     // Every emitted location is relative to this ONE root, computed once before
@@ -210,14 +414,19 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     const locationRoot = shared?.locationRoot ?? projectRoot;
     const skillLocation = issueLocation(skillPath, locationRoot);
     // Parse SKILL.md
-    const parseResult = await parseMarkdown(skillPath);
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- skillPath is validated function parameter
-    const skillContent = await readFile(skillPath, 'utf-8');
+    const parseResult = await parseFileCached(skillPath, 'markdown');
+    // The parser already decoded these bytes; a second whole-file read of the same
+    // path would only add a syscall and a TOCTOU window. `content` is the raw
+    // source verbatim, so fenced code blocks reach `runCompatDetectors` intact.
+    const skillContent = parseResult.content;
     const skillLines = skillContent.split('\n').length;
     // Validate frontmatter schema (name format, required fields, etc.)
     if (parseResult.frontmatter) {
         rawIssues.push(...validateFrontmatterSchema(parseResult.frontmatter, false, skillLocation), ...validateFrontmatterRules(parseResult.frontmatter, skillLocation));
     }
+    else {
+        rawIssues.push(missingFrontmatterIssue(parseResult.frontmatterError, skillLocation));
+    }
     // Compat capability detection: collect observations from SKILL.md and
     // surface each as a CAPABILITY_* issue. Observations are also returned
     // on the result so downstream verdict computation (CLI layer) can recover
@@ -240,21 +449,39 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     // per-file markdown parse is paid for exactly once across the batch. Only
     // reuse when the shared registry covers this skill's projectRoot; otherwise
     // fall back to a fresh crawl to avoid leaking resources across roots.
-    const registry = shared?.registry !== undefined && registryCoversSkill(shared.registry, skillPath)
-        ? shared.registry
-        : await crawlAndResolveRegistry(projectRoot);
+    const registry = await registryForSkill(skillPath, projectRoot, shared);
     const skillResource = registry.getResource(safePath.resolve(skillPath));
     // Only the entries the PACKAGER will actually copy defer a link: an entry pointing
     // into declared test input is dropped at build time, so its dest never appears and
     // a link to it is a genuine broken link — the same verdict `vat skills build`
-    // reaches. See packagedFileEntries in test-input.ts.
+    // reaches. Same derivation `packagedFileEntries` performs for the lanes that have
+    // no second use for the dirs — see test-input.ts.
     //
     // `projectSkills` is the PROJECT's declared eval suites, assembled once by the
     // calling lane (see SkillValidationSharedContext.projectSkills). Empty when the
     // caller has no project to enumerate — a single-skill audit of a tree with no
     // config — which narrows this lane to the subject's own suite and nothing else.
     const projectSkills = shared?.projectSkills ?? [];
-    const packagedFiles = packagedFileEntries(packagingConfig ?? {}, dirname(skillPath), projectRoot, projectSkills);
+    // ONE resolution per skill, shared by both consumers below (the `files:` filter and
+    // the walker's exclude rules), and ONE conventional-suite probe per RUN behind it.
+    //
+    // Two multipliers on the same filesystem question, both now closed. Resolving it
+    // once per CONSUMER doubled the term for no new information (the two call sites took
+    // identical arguments) — 6,844 probes on a 58-skill adopter declaring no `test:`
+    // block, of which 3,422 re-asked a question already answered. That fix removed the
+    // second call site and left the QUADRATIC standing: the resolution still probes the
+    // subject AND every entry in `projectSkills`, so a lane looping over S skills asked
+    // S^2 questions about S paths. Measured with the lab on a 103-skill adopter,
+    // `vat resources validate`: 10,815 probes over 103 distinct paths (~105 repeats
+    // each) — exactly 50% of that command's 21,648 user filesystem calls. With the run's
+    // probe threaded here it is ~103 probes and ~10,900 calls on the same tree.
+    //
+    // A caller that omits `suiteProbe` is claiming this call IS the run (see the field's
+    // docstring); the narrowing is written here, at the call site, so it cannot happen by
+    // omission inside `resolveTestInputDirs`.
+    const suiteProbe = shared?.suiteProbe ?? conventionalSuiteProbe();
+    const testInputDirs = resolveTestInputDirs(packagingConfig ?? {}, dirname(skillPath), projectSkills, suiteProbe);
+    const packagedFiles = partitionTestInputFileEntries(packagingConfig?.files ?? [], projectRoot, testInputDirs).kept;
     const deferred = DeferredArtifacts.from([{ files: packagedFiles, skillDir: dirname(skillPath) }], projectRoot);
     // What the `files:` GLOBs will do to this build, reported HERE — before any
     // build — because this is where it is still cheap to act on: `vat skills
@@ -270,7 +497,6 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     //     while staying silent about the fatal zero-match was the asymmetry that
     //     let `vat skills validate` return success on a config that cannot build.
     rawIssues.push(...preBuildGlobFindingsToIssues(await collectPreBuildGlobFindings(packagedFiles, projectRoot), locationRoot));
-    const testInputDirs = resolveTestInputDirs(packagingConfig ?? {}, dirname(skillPath), projectSkills);
     const walkOptions = {
         maxDepth,
         // The SAME test-input exclusion the packager applies. Without it this lane
@@ -289,20 +515,20 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     if (shared?.gitTracker !== undefined) {
         walkOptions.gitTracker = shared.gitTracker;
     }
-    const { bundledResources, bundledAssets, excludedReferences, maxBundledDepth, deferredAssets } = walkLinkGraph(skillResource?.id ?? '', registry, walkOptions);
+    const { bundledResources, bundledAssets, excludedReferences, outsideSkillDirLinks, maxBundledDepth, deferredAssets } = walkLinkGraph(skillResource?.id ?? '', registry, walkOptions);
     const bundledFiles = [...bundledResources.map(r => r.filePath), ...bundledAssets];
     // Count direct links that actually made it into the bundle
     const directLinks = getResolvedMarkdownLinks(parseResult.links, skillPath);
     const bundledFileSet = new Set(bundledFiles);
     const directFileCount = directLinks.filter(p => bundledFileSet.has(p)).length;
-    // Three producers, one append, order significant. Each is a receipt for a link
-    // the walker dropped or deferred, and all three anchor on `locationRoot`:
+    // Four producers, one append, order significant, all anchored on `locationRoot`:
     //  1. walker exclusions (LINK_OUTSIDE_PROJECT, LINK_TARGETS_DIRECTORY, etc.)
     //  2. links dropped for pointing into declared test input — the same issue, at
     //     the same location, the packager emits for it. `projectRoot` scopes WHICH
     //     dirs count as declared test input; `locationRoot` only anchors.
     //  3. one info issue per deferred asset declared in files: config
-    rawIssues.push(...walkerExclusionsToIssues(excludedReferences, locationRoot), ...testInputLinkIssues(excludedReferences, testInputDirs, projectRoot, locationRoot), ...deferredAssetsToIssues(deferredAssets, locationRoot));
+    //  4. followed links bundled from outside the skill directory (LINK_OUTSIDE_SKILL_DIR)
+    rawIssues.push(...walkerExclusionsToIssues(excludedReferences, locationRoot), ...testInputLinkIssues(excludedReferences, testInputDirs, projectRoot, locationRoot), ...deferredAssetsToIssues(deferredAssets, locationRoot), ...outsideSkillDirLinksToIssues(outsideSkillDirLinks, locationRoot));
     const fileCount = bundledFiles.length + 1; // +1 for SKILL.md itself
     const maxLinkDepth = maxBundledDepth;
     // Calculate total lines from bundled markdown files only, and scan each
@@ -311,13 +537,20 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     let totalLines = skillLines;
     for (const bundledFile of bundledFiles) {
         if (bundledFile.endsWith('.md')) {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- bundledFile resolved from markdown parser
             const content = await readFile(bundledFile, 'utf-8');
             totalLines += content.split('\n').length;
             // Anchor contract: never hand a producer an absolute path as `location`.
             const bundledLocation = issueLocation(bundledFile, locationRoot);
             collectNonPortableAssetReferenceIssues(content, bundledLocation, rawIssues);
             collectNonPortableCommandIssues(content, bundledLocation, rawIssues);
+            // Whole-file bytes, frontmatter included — safe because the detector
+            // strips leading frontmatter itself. It did not always, and this lane was
+            // the half of the invariant nobody was enforcing: a bundled file carrying
+            // `allowed-tools: [mcp__x__do_thing]` seeded the vocabulary the SKILL.md
+            // lane's comment (below) says must come from prose, then fired on its own
+            // body. Pinned by "does not let a bundled file's allowed-tools frontmatter
+            // supply the vocabulary" in packaging-validator.test.ts.
+            collectUnqualifiedMcpToolIssues(content, bundledLocation, rawIssues);
         }
     }
     const excludedDetails = deduplicateExcludedReferences(excludedReferences, skillPath);
@@ -329,8 +562,19 @@ export async function validateSkillForPackaging(skillPath, packagingConfig, cont
     collectTimeSensitiveContentIssues(parseResult.content, skillLocation, rawIssues);
     collectNonPortableAssetReferenceIssues(parseResult.content, skillLocation, rawIssues);
     collectNonPortableCommandIssues(parseResult.content, skillLocation, rawIssues);
+    // An `allowed-tools:` list of `mcp__…` names does not by itself supply the
+    // vocabulary: the qualified spelling has to appear in the prose an agent
+    // reads, or "the document contradicts itself" is not the finding. That holds
+    // because the DETECTOR strips frontmatter. ⛔ It was NEVER true that this call
+    // site passed a post-frontmatter slice — `parseResult.content` is the raw file
+    // verbatim, as the comment 190 lines above says — so before the detector
+    // stripped, this lane did read `allowed-tools:` as prose and did ship the
+    // findings that came of it.
+    collectUnqualifiedMcpToolIssues(parseResult.content, skillLocation, rawIssues);
     // Cross-skill dependency smell: body declares a requires/depends token the
-    // description does not mention. Uses the post-frontmatter content slice.
+    // description does not mention. Reads the RAW file, frontmatter included —
+    // which is what this detector wants, since the declaration it looks for can be
+    // written either side of the fence.
     if (parseResult.frontmatter) {
         rawIssues.push(...detectUndeclaredCrossSkillAuth(parseResult.frontmatter, parseResult.content, skillLocation));
     }
@@ -510,9 +754,23 @@ const RELATIVE_PATH_HINT = 'Reference bundled files by a path relative to the sk
  *     plain form; falling to (2) is what still flags the operator forms — a
  *     lone `\$\{NAME\}` alternative silently missed `${NAME:-default}`, an
  *     idiomatic non-portable reference.
+ *  3. `\$\{?env:NAME\b` — PowerShell's expansion, BOTH spellings. A skill that
+ *     documents a Windows invocation writes `$env:CLAUDE_SKILL_DIR` or
+ *     `${env:CLAUDE_SKILL_DIR}`, neither of which the two POSIX alternatives
+ *     match: after `$`/`${` comes `env:`, not the variable name. The forms are
+ *     equally non-portable, so leaving them out flagged the bash line of a skill
+ *     and waved through the PowerShell line directly beneath it.
+ *
+ * ⚠️ Compiled with the `i` flag, and that is about alternative 3 specifically.
+ * PowerShell variable and drive names are case-INSENSITIVE, so `$Env:NAME` and
+ * `$ENV:NAME` are as valid — and as commonly authored — as `$env:NAME`. A
+ * case-SENSITIVE `\$env:` matched one of the three and silently passed the other
+ * two, reintroducing exactly the asymmetry this alternative was added to remove.
+ * The variable names themselves are uppercase literals passed in by the call
+ * sites below, so case-insensitivity costs nothing there.
  */
 // eslint-disable-next-line security/detect-non-literal-regexp -- composed from a compile-time constant name, no user input
-const envVarPattern = (name) => new RegExp(String.raw `\$\{${name}\}|\$\{?${name}\b`);
+const envVarPattern = (name) => new RegExp(String.raw `\$\{${name}\}|\$\{?env:${name}\b|\$\{?${name}\b`, 'i');
 const NON_PORTABLE_ASSET_VARIANTS = [
     {
         label: 'claude-plugin-root',
@@ -530,6 +788,40 @@ const NON_PORTABLE_ASSET_VARIANTS = [
         pattern: envVarPattern('CLAUDE_PROJECT_DIR'),
         fix: '`CLAUDE_PROJECT_DIR` is a Claude Code-only variable, so a skill relying on it will not resolve the user\'s project on other runtimes. There is no skill-relative equivalent — if the skill genuinely operates on the user\'s repository, take the location as an explicit parameter with `$CLAUDE_PROJECT_DIR` as a fallback, and make sure the skill\'s declared `targets` reflect the Claude Code dependency.',
     },
+    {
+        // Load-bearing in Claude Code and MEANINGLESS in the API code-execution
+        // container. Both facts are true for good reasons, which is why this is a
+        // warning and not a rename: in Claude Code a skill may live under
+        // `~/.claude/skills/`, a plugin tree, a project dir or a marketplace install
+        // path while cwd is the user's repo, and the consumer needing a real path is
+        // often a PROCESS (a script argument) that does not share the model's
+        // context — there is no literal an author can write. The API container has
+        // the opposite property: the location is a stable literal (`/skills/<name>/`,
+        // cwd `/`) so nothing is parameterised and no equivalent variable is set,
+        // measured live against the Messages API. `${CLAUDE_SKILL_DIR}` therefore
+        // expands to empty there and `node "/scripts/x.mjs"` does not exist.
+        label: 'claude-skill-dir',
+        pattern: envVarPattern('CLAUDE_SKILL_DIR'),
+        fix: `\`CLAUDE_SKILL_DIR\` is set by Claude Code and is absent in the API code-execution container, where it expands to empty. ${RELATIVE_PATH_HINT} A relative path resolves on every target because the MODEL resolves it against the skill directory — not because cwd happens to be right. When a process genuinely needs an absolute path, instruct the agent to cd into the skill directory first rather than reaching for another variable.`,
+    },
+    {
+        // The same mistake pointed the other way: the API container's literal mount
+        // point hardcoded into a skill, which resolves nowhere in Claude Code. Anchored
+        // at a path boundary so `~/.claude/skills/x/` and `.claude/skills/` in prose
+        // (both preceded by a word character) are not flagged.
+        //
+        // ⚠️ The TRAILING separator is optional, and that is the common spelling —
+        // not an edge case. `/skills/<name>` with nothing after it is the mount
+        // POINT, which is what the sibling `claude-skill-dir` fix text tells authors
+        // to reach for ("cd into the skill directory first"). Requiring the trailing
+        // `/` made `cd /skills/my-skill && node scripts/run.mjs` invisible while
+        // firing on `node /skills/my-skill/scripts/run.mjs` on the next line. The
+        // `(?![\w.-])` branch keeps the name from being truncated mid-token, so a
+        // longer name is still matched whole rather than at a prefix.
+        label: 'api-skill-mount',
+        pattern: /(?:^|[\s"'`(])\/skills\/[A-Za-z0-9._-]+(?:\/|(?![\w.-]))/,
+        fix: `\`/skills/<name>/\` is the Anthropic API code-execution container's mount point and does not exist in Claude Code, a claude.ai upload, or any other host. ${RELATIVE_PATH_HINT} When a process genuinely needs an absolute path, instruct the agent to cd into the skill directory first.`,
+    },
     {
         label: 'absolute-script-path',
         pattern: /\b(?:node|bun|deno|python3?|ruby|sh|bash|uv)\s+["']?\/[^\s"']+\.(?:mjs|cjs|js|ts|py|rb|sh)\b/,
@@ -656,7 +948,7 @@ function collectPortabilityFamilyIssues(content, docLocation, issues, family) {
  * Collect NON_PORTABLE_ASSET_REFERENCE issues — scan one skill document for any
  * member of the non-portable asset-reference family.
  */
-function collectNonPortableAssetReferenceIssues(content, docLocation, issues) {
+export function collectNonPortableAssetReferenceIssues(content, docLocation, issues) {
     collectPortabilityFamilyIssues(content, docLocation, issues, {
         code: 'NON_PORTABLE_ASSET_REFERENCE',
         variants: NON_PORTABLE_ASSET_VARIANTS,
@@ -670,7 +962,7 @@ function collectNonPortableAssetReferenceIssues(content, docLocation, issues) {
  * Collect NON_PORTABLE_COMMAND issues — scan one skill document for any member of
  * the non-portable shell-command family.
  */
-function collectNonPortableCommandIssues(content, docLocation, issues) {
+export function collectNonPortableCommandIssues(content, docLocation, issues) {
     collectPortabilityFamilyIssues(content, docLocation, issues, {
         code: 'NON_PORTABLE_COMMAND',
         variants: NON_PORTABLE_COMMAND_VARIANTS,
@@ -689,10 +981,24 @@ function collectProgressiveDisclosureIssue(skillLines, referenceFileCount, skill
     }
 }
 /**
- * Process links from parsed markdown and return resolved .md file paths
+ * Process links from parsed markdown and return resolved .md file paths.
+ *
+ * Exported for unit test: the deduplication contract (one entry, and one existence
+ * probe, per DISTINCT target however many times it is linked) is not observable
+ * through `validateSkillForPackaging`'s result alone.
  */
-function getResolvedMarkdownLinks(links, markdownPath) {
-    const resolvedPaths = [];
+export function getResolvedMarkdownLinks(links, markdownPath) {
+    const markdownDir = dirname(markdownPath);
+    // Collapse to DISTINCT targets before touching the filesystem. `links` is one
+    // entry per link OCCURRENCE, and documents routinely point many occurrences at
+    // one file (a routing table linking every row to the same sub-skill). Two
+    // consequences, both fixed here rather than downstream:
+    //   - the caller derives `directFileCount` from this list, so occurrences made
+    //     it report more direct files than the whole bundle holds;
+    //   - the existence probe below ran once per occurrence. On this repo's own
+    //     cat-agents skill that was 42 probes over 9 distinct paths.
+    // A Set preserves insertion order, so the surviving order is unchanged.
+    const candidates = new Set();
     for (const link of links) {
         if (link.type !== 'local_file') {
             continue;
@@ -702,22 +1008,24 @@ function getResolvedMarkdownLinks(links, markdownPath) {
         if (hrefWithoutAnchor === '') {
             continue;
         }
-        // Resolve path
-        const resolvedPath = safePath.resolve(dirname(markdownPath), hrefWithoutAnchor);
-        // Only include .md files that exist
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path constructed from parsed markdown
-        if (!resolvedPath.endsWith('.md') || !existsSync(resolvedPath)) {
-            continue;
+        const resolvedPath = safePath.resolve(markdownDir, hrefWithoutAnchor);
+        // Only .md targets are candidates; existence is settled once, below.
+        if (resolvedPath.endsWith('.md')) {
+            candidates.add(resolvedPath);
         }
-        resolvedPaths.push(resolvedPath);
     }
-    return resolvedPaths;
+    return [...candidates].filter(candidate => existsSync(candidate));
 }
 /**
  * Reasons that are reported as validation errors instead of excluded references.
  * These are filtered out of the excluded references list.
  */
-const VALIDATION_ERROR_REASONS = new Set([EXCLUDE_REASON_DIRECTORY, EXCLUDE_REASON_OUTSIDE_PROJECT]);
+const EXCLUDE_REASON_UNREADABLE = 'unreadable-target';
+const VALIDATION_ERROR_REASONS = new Set([
+    EXCLUDE_REASON_DIRECTORY,
+    EXCLUDE_REASON_OUTSIDE_PROJECT,
+    EXCLUDE_REASON_UNREADABLE,
+]);
 /**
  * Deduplicate excluded references by path, preserving detail from first occurrence.
  * Filters out entries reported as validation errors (directory-target, outside-project).
@@ -751,9 +1059,15 @@ function mapExcludeReason(excludeReason) {
         case 'agent-instruction-file': return 'agent-instruction-file';
         case 'skill-definition': return 'skill-definition';
         case 'gitignored': return 'gitignored';
+        // Reported under its own name rather than falling into the default arm.
+        // The default answers `depth-exceeded`, which for this reason would be
+        // false: the walk never reached the edge at all, because the file holding
+        // it is not one VAT routes through.
+        case 'non-routable-source': return 'non-routable-source';
         case 'depth-exceeded':
         case EXCLUDE_REASON_DIRECTORY:
         case EXCLUDE_REASON_OUTSIDE_PROJECT:
+        case EXCLUDE_REASON_UNREADABLE:
         case 'missing-target':
         case undefined:
         default:
@@ -769,9 +1083,11 @@ function extractSkillName(parseResult, skillPath) {
     if (frontmatterName && typeof frontmatterName === 'string') {
         return frontmatterName;
     }
-    // Try H1 title (use [^\n] instead of .+ to avoid backtracking)
-    // eslint-disable-next-line sonarjs/slow-regex -- Using [^\n]+ instead of .+ to avoid backtracking
-    const h1Match = /^#\s+([^\n]+)$/m.exec(parseResult.content);
+    // Try H1 title. `[ \t]` is a single fixed-width class, not a quantifier, so it
+    // cannot compete with the `[^\n]*` capture for the same space — that ambiguity
+    // is what made the old `\s+([^\n]+)` form backtrack super-linearly. Trailing
+    // whitespace is removed by the .trim() below, exactly as before.
+    const h1Match = /^#[ \t]([^\n]*)$/m.exec(parseResult.content);
     if (h1Match?.[1]) {
         return h1Match[1].trim();
     }