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

package/dist/walk-link-graph.js

@@ -8,11 +8,34 @@
  * Non-markdown assets (images, JSON, etc.) won't be in the registry and still
  * require `existsSync()` checks — this is acceptable since the goal is eliminating
  * redundant I/O for markdown files that are already parsed.
+ *
+ * ## Membership is not traversability
+ *
+ * A registry MEMBER is a file VAT has parsed: its links are known, so the
+ * packager's rewriter can reach inside it and repoint them at bundled copies. A
+ * ROUTABLE file is one the walker walks THROUGH — it enqueues that file's link
+ * targets as further bundle members. Routing is markdown-only
+ * ({@link isRoutable}); HTML is "a leaf we can read, not a door we walk
+ * through".
+ *
+ * These used to be the same thing, by accident: any link target that
+ * `getResourceById` found was queued, so a registry's include globs silently
+ * WERE the routability policy. The two production registries disagreed as a
+ * result. `crawlAndResolveRegistry` includes HTML, so `vat audit` and
+ * post-build validation walked THROUGH a bundled page and counted its targets
+ * as bundled; the packager's `createProjectRegistry` is markdown-only, so at
+ * walk time the same page was an opaque asset and its targets were dropped.
+ * Same tree, two answers to "is HTML a door" — and audit's answer described a
+ * bundle the build never produced.
+ *
+ * Links out of a non-routable member are not silently dropped: each one whose
+ * target the walk never bundled by some other route is reported as a
+ * `non-routable-source` exclusion (`LINK_FROM_NON_ROUTABLE_FILE`).
  */
-import { existsSync, statSync } from 'node:fs';
 import { basename, dirname } from 'node:path';
-import { isLocalFileLink, resolveLocalHref } from '@vibe-agent-toolkit/resources';
-import { isGitIgnored, toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
+import { isLocalFileLink, parserKindForPath, resolveLocalHref, } from '@vibe-agent-toolkit/resources';
+import { CRAWL_PASS_INSIDE, CRAWL_WALKER_GITIGNORE_ID, CRAWL_WALKER_ID, crawlTimingStart, FsLookupCache, recordCrawlPass, relativeEscapesRoot, toForwardSlash, safePath, } from '@vibe-agent-toolkit/utils';
+import { isGitIgnored } from '@vibe-agent-toolkit/utils/git';
 import picomatch from 'picomatch';
 import { isAgentInstructionBasename, isNavigationBasename } from './validators/validation-rules.js';
 // ============================================================================
@@ -48,36 +71,55 @@ function resolveHrefToPath(hrefWithoutAnchor, sourceFilePath, projectRoot) {
 }
 /** Check if a link targets a file outside the project boundary */
 function isOutsideProject(targetPath, projectRoot) {
-    return safePath.relative(projectRoot, targetPath).startsWith('..');
+    return relativeEscapesRoot(safePath.relative(projectRoot, targetPath));
 }
 // Navigation / agent-instruction classification is the shared, case-insensitive
 // matcher from validation-rules (`isNavigationBasename` / `isAgentInstructionBasename`),
 // used directly at the call sites below. On APFS/NTFS a `Claude.md` is loaded as
 // instructions exactly as a `CLAUDE.md` is, so the walker must refuse both spellings.
-/** Create an exclusion record */
-function makeExclusion(targetPath, sourcePath, targetExists, reason, link, matchedRule) {
+function makeFollowedLink(targetPath, sourcePath, targetExists, link) {
     return {
         path: targetPath,
         sourcePath,
         ...(link.line !== undefined && { sourceLine: link.line }),
         targetExists,
+        bundled: true,
+        linkText: link.text,
+        linkHref: link.href,
+    };
+}
+/** Create an exclusion record */
+function makeExclusion(targetPath, sourcePath, targetExists, reason, link, matchedRule) {
+    return {
+        ...makeFollowedLink(targetPath, sourcePath, targetExists, link),
         bundled: false,
         excludeReason: reason,
         ...(matchedRule ? { matchedRule } : {}),
-        linkText: link.text,
-        linkHref: link.href,
     };
 }
 /**
- * Check if a target path is a not-yet-materialized deferred build artifact, and
- * record it in the deferred set if so. Must run BEFORE any statSync / directory
- * check to avoid blowing up on missing paths.
+ * Build the pass-1′ row for one link target.
+ *
+ * The two syscalls come from {@link FsLookupCache.probe}, which memoizes them
+ * across links, so repeated calls for the same path are free of I/O.
+ */
+function fillPathFacts(targetPath, options, state) {
+    const { exists, isDirectory } = state.pathProbe.probe(targetPath);
+    return {
+        exists,
+        isDirectory,
+        insideProject: !isOutsideProject(targetPath, options.projectRoot),
+    };
+}
+/**
+ * Check if a target path is a not-yet-materialized deferred build artifact.
+ * Must run BEFORE any directory check to avoid classifying a missing path.
  *
  * This check is gated on the target NOT existing on disk: it classifies the
  * "hasn't been built yet" half of the deferred-artifact lifecycle. An
  * existing real file at a covered files: dest (or source) is NOT deferred by
  * THIS check — it falls through to the directory-target check and beyond.
- * The gitignore branch further down in {@link checkExclusions} carries its
+ * The gitignore branch further down ({@link classifyGitignored}) carries its
  * OWN, unconditional `deferredArtifacts` exemption (existing or not) for the
  * "already built, and gitignored as expected" half — see the comment there.
  * So an existing-but-gitignored covered path still ends up classified as
@@ -85,17 +127,12 @@ function makeExclusion(targetPath, sourcePath, targetExists, reason, link, match
  * existing-and-NOT-gitignored covered path (or an uncovered path) reaches
  * normal handling. {@link DeferredArtifacts.covers} does the exact-OR-
  * directory-prefix membership test (pure, no filesystem access); the
- * existence answer is supplied by the caller, which probes the target once
- * for the whole classifier.
+ * existence answer comes from the target's pass-1′ row.
  *
  * @returns true if the path was classified as deferred
  */
-function checkDeferred(targetPath, targetExists, deferredArtifacts, deferredAssetSet) {
-    if (deferredArtifacts.covers(targetPath) && !targetExists) {
-        deferredAssetSet.add(toForwardSlash(targetPath));
-        return true;
-    }
-    return false;
+function checkDeferred(targetPath, targetExists, deferredArtifacts) {
+    return deferredArtifacts.covers(targetPath) && !targetExists;
 }
 /**
  * Does the walker refuse to bundle this target because it is a repo-internal
@@ -141,8 +178,8 @@ function refusesAgentInstructionFile(targetPath, options) {
     return !declaredSources.has(toForwardSlash(safePath.relative(options.projectRoot, targetPath)));
 }
 /**
- * Record a gitignored target as either a leak or an exempted `files:` build
- * artifact — the caller always excludes it from the walk either way; only
+ * Classify a target already known to be gitignored as either a leak or an
+ * exempted `files:` build artifact — the walk excludes it either way; only
  * the record differs.
  *
  * A files:-declared DEST is exempt from the leak rule EVEN WHEN it already
@@ -161,18 +198,13 @@ function refusesAgentInstructionFile(targetPath, options) {
  * coverage must NOT exempt it. An uncovered path, or a path covered only via
  * `sourcePaths`, still reports the leak normally.
  */
-function recordGitignoredTarget(targetPath, sourcePath, link, deferredArtifacts, excludedReferences, deferredAssetSet) {
-    if (deferredArtifacts?.coversDest(targetPath)) {
-        deferredAssetSet.add(toForwardSlash(targetPath));
-        return;
-    }
-    // `targetExists: true` is not an assumption here — the caller only reaches
-    // this function for a target it has already stat'ed and found present.
-    excludedReferences.push(makeExclusion(targetPath, sourcePath, true, 'gitignored', link));
+function classifyGitignoredTarget(targetPath, deferredArtifacts) {
+    return deferredArtifacts?.coversDest(targetPath)
+        ? { kind: 'deferred' }
+        : { kind: 'excluded', reason: 'gitignored' };
 }
 /**
- * The gitignore branch of {@link checkExclusions}, extracted to keep that
- * classifier within its cognitive-complexity budget.
+ * The `files:`-dest exemption for a target already known to be gitignored.
  *
  * GATED ON EXISTENCE, and the gate is the point. A path that is not there
  * cannot leak anything, and neither ignore oracle can be trusted to say so:
@@ -187,69 +219,125 @@ function recordGitignoredTarget(targetPath, sourcePath, link, deferredArtifacts,
  * Prefer the pre-populated GitTracker when the caller plumbed one through: it
  * answers in O(1) against the active set, no `git check-ignore` spawn.
  *
- * @returns true if the target was recorded (as a leak, or as an exempted
- *          `files:` build artifact) and the caller should stop classifying
+ * **Memoized per walk**, so a target named by many documents costs one answer
+ * rather than one per reference. The memo cannot change the answer: both
+ * oracles are pure functions of the tree, and the memo's lifetime is one walk.
+ *
+ * ⛔ **Measured on VAT's own tree, and the result is a NEGATIVE —
+ * do not sell this as a performance win.** Counting asks vs. memo misses in the
+ * built lane: `vat audit .` = 3 asks / 2 distinct, `vat skills build` = 0 / 0,
+ * `vat inventory .` = 0 / 0. **One** oracle call avoided across all three.
+ *
+ * The reason is structural, not incidental: this branch is LAST in the cascade,
+ * so a target only reaches it after surviving all seven earlier discriminators
+ * *and* existing on disk. Nearly every link target is classified before then —
+ * bundled markdown, a directory, a navigation file, a pattern match. The memo's
+ * real justification is therefore **shape, not speed**: it is what lets the
+ * oracle read sit outside {@link classifyExclusion} so that function can be a
+ * pure predicate over the row. Any future claim of a spawn-count win needs its
+ * own measurement on a corpus where this branch is actually hot.
+ *
+ * Two further bounds, so nobody reads more into it than it does:
+ *
+ * - **The collapse is within-ONE-walk fan-in only.** `collectLinkedFiles` calls
+ *   {@link walkLinkGraph} once per skill, so a target shared across skills is
+ *   still asked about once per skill. That per-walk lifetime is exactly what
+ *   makes the memo safe against `packageSkill` writing `dist/` between skills,
+ *   so it is a deliberate ceiling, not a missed optimization.
+ * - **Not every repeat was a subprocess.** {@link isGitIgnored} settles "is
+ *   there a repository here?" from the filesystem and returns early when there
+ *   is none, so on a tree with no `.git` ancestor the repeats were ancestor
+ *   walks rather than `git check-ignore` spawns. Inside a real repository they
+ *   were spawns.
+ *
+ * @returns whether the target is gitignored
  */
-function checkGitignored(targetPath, sourcePath, targetExists, link, options, excludedReferences, deferredAssetSet) {
-    if (!targetExists) {
-        return false;
-    }
+function readGitignored(targetPath, options, state) {
+    const cached = state.gitignoreFacts.get(targetPath);
+    if (cached !== undefined)
+        return cached;
+    // Charged on the MISS path only, so `calls` counts oracle READS rather than
+    // asks — a memo hit costs nothing worth a bracket, and counting it would make
+    // the row's ms/call meaningless. This is the branch that can spawn
+    // `git check-ignore`, which is why it is separated from the walk's own row at
+    // all: the walk's cost and the oracle's cost move for different reasons.
+    const startedAt = crawlTimingStart();
     const isIgnored = options.gitTracker === undefined
         ? isGitIgnored(targetPath, options.projectRoot)
         : options.gitTracker.isIgnoredByActiveSet(targetPath);
-    if (!isIgnored) {
-        return false;
-    }
-    recordGitignoredTarget(targetPath, sourcePath, link, options.deferredArtifacts, excludedReferences, deferredAssetSet);
-    return true;
+    recordCrawlPass(CRAWL_WALKER_GITIGNORE_ID, 'crawl', CRAWL_PASS_INSIDE, startedAt);
+    state.gitignoreFacts.set(targetPath, isIgnored);
+    return isIgnored;
 }
 /**
- * Check if a target path should be excluded for structural reasons
- * (deferred build artifact, directory, outside project, navigation file, or
- * pattern match).
+ * The `exists` × `isDirectory` corner of the cascade — the only place the row's
+ * three-state `isDirectory` is read.
  *
- * @returns true if the link was excluded or deferred (caller should skip to next link)
+ * `null` means *no answer about the kind*: the path is present to `existsSync`
+ * and unstattable anyway (a permissions problem, or a change racing the two
+ * calls). The classifier can say nothing about WHAT the target is — but it can
+ * say that the target is there and could not be read, and that is the report.
+ *
+ * ✅ **This used to skip silently, and that was D6 in the spec's deferred-fixes
+ * ledger — now fixed.** `{ kind: 'skipped' }` recorded nothing at all, so an
+ * unreadable link target vanished from the report entirely: no exclusion, no
+ * bundling, no issue. It survived the pass-1′ refactor only because that
+ * refactor was held to byte-identical output (it is what the pre-refactor
+ * `catch { return true }` did). Meanwhile the resources lane turned the
+ * IDENTICAL class of read failure into a `RESOURCE_UNREADABLE` finding, so one
+ * unreadable file got two answers depending on which lane found it. It is now
+ * an `unreadable-target` exclusion, which the verdict engine reports as
+ * `LINK_TARGET_UNREADABLE` — the resources code's skill-packaging sibling.
+ *
+ * @returns a verdict when the path's kind decides the outcome, else `undefined`
  */
-function checkExclusions(targetPath, sourcePath, link, options, excludeMatchers, excludedReferences, deferredAssetSet) {
-    // ONE existence probe for the whole classifier. Several branches below are
-    // meaningful only for a target that is actually there, and one of them
-    // (gitignore) is actively WRONG without it — see the comment on that branch.
-    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path from parsed markdown
-    const targetExists = existsSync(targetPath);
+function classifyPathKind(facts) {
+    if (!facts.exists)
+        return undefined;
+    if (facts.isDirectory === true)
+        return { kind: 'excluded', reason: 'directory-target' };
+    if (facts.isDirectory === null)
+        return { kind: 'excluded', reason: 'unreadable-target' };
+    return undefined;
+}
+/**
+ * The first-match-wins exclusion cascade, as a **pure function of the pass-1′
+ * row**. No filesystem access, no walk-state mutation, no recording.
+ *
+ * ⚠️ **The order IS the behaviour.** This is a cascade, not a set of
+ * independent predicates: a directory that is also pattern-matched is reported
+ * as `directory-target`, and rewriting it as `reasons.find(...)` over
+ * independently-evaluated conditions would silently repick which reason wins.
+ * Every branch below sits exactly where it sat when the classifier did its own
+ * I/O inline; only the source of the facts changed.
+ *
+ * The one branch that is not a column is the last one — see
+ * {@link readGitignored} for why the gitignore oracle is demand-read at the
+ * point the cascade reaches it rather than filled for every row.
+ *
+ * @returns the verdict, or `undefined` when nothing excludes the target
+ */
+function classifyExclusion(targetPath, options, excludeMatchers, facts) {
     // The deferred check is the FIRST discriminator: a not-yet-materialized target
     // must be classified before any check that would read it off disk.
-    if (options.deferredArtifacts && checkDeferred(targetPath, targetExists, options.deferredArtifacts, deferredAssetSet)) {
-        return true;
+    if (options.deferredArtifacts && checkDeferred(targetPath, facts.exists, options.deferredArtifacts)) {
+        return { kind: 'deferred' };
     }
     // Check if target is a directory
-    if (targetExists) {
-        try {
-            // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path from parsed markdown
-            if (statSync(targetPath).isDirectory()) {
-                excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'directory-target', link));
-                return true;
-            }
-        }
-        catch {
-            // statSync failure = skip
-            return true;
-        }
-    }
+    const kindVerdict = classifyPathKind(facts);
+    if (kindVerdict)
+        return kindVerdict;
     // Check project boundary
-    if (isOutsideProject(targetPath, options.projectRoot)) {
-        excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'outside-project', link));
-        return true;
-    }
+    if (!facts.insideProject)
+        return { kind: 'excluded', reason: 'outside-project' };
     // Check navigation file exclusion
     if (options.excludeNavigationFiles && isNavigationBasename(basename(targetPath))) {
-        excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'navigation-file', link));
-        return true;
+        return { kind: 'excluded', reason: 'navigation-file' };
     }
     // Repo-internal agent-instruction files — see {@link refusesAgentInstructionFile}
     // for why they cannot travel, and for the explicit-`files:` escape hatch.
     if (refusesAgentInstructionFile(targetPath, options)) {
-        excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'agent-instruction-file', link));
-        return true;
+        return { kind: 'excluded', reason: 'agent-instruction-file' };
     }
     // Check for cross-skill SKILL.md links — a SKILL.md is a skill definition marker,
     // not a resource. Bundling another skill's SKILL.md creates duplicate skill definitions
@@ -260,21 +348,78 @@ function checkExclusions(targetPath, sourcePath, link, options, excludeMatchers,
     // prevents re-traversal, and the duplicate-definition risk does not apply to the
     // current skill itself.
     if (basename(targetPath) === 'SKILL.md') {
-        if (safePath.resolve(targetPath) !== safePath.resolve(options.skillRootPath)) {
-            excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'skill-definition', link));
-        }
-        return true;
+        return safePath.resolve(targetPath) === safePath.resolve(options.skillRootPath)
+            ? { kind: 'skipped' }
+            : { kind: 'excluded', reason: 'skill-definition' };
     }
     // Check exclude patterns (relative to projectRoot)
     const relativePath = toForwardSlash(safePath.relative(options.projectRoot, targetPath));
     const matchedExclude = excludeMatchers.find((m) => m.isMatch(relativePath));
     if (matchedExclude) {
-        excludedReferences.push(makeExclusion(targetPath, sourcePath, targetExists, 'pattern-matched', link, matchedExclude.rule));
-        return true;
+        return { kind: 'excluded', reason: 'pattern-matched', matchedRule: matchedExclude.rule };
     }
-    // Check if the file is gitignored (prevents leaking data from ignored
-    // directories) — existence-gated; see {@link checkGitignored}.
-    return checkGitignored(targetPath, sourcePath, targetExists, link, options, excludedReferences, deferredAssetSet);
+    // Falls through to the cascade's final branch, which is the one that needs an
+    // oracle rather than a column — see {@link classifyGitignored}.
+    return undefined;
+}
+/**
+ * The cascade's LAST branch, kept out of {@link classifyExclusion} so that
+ * function can stay a pure function of the row.
+ *
+ * Its position at the end is not an implementation detail — it is why the
+ * demand-read is safe. Every earlier discriminator has already declined, so the
+ * set of paths this asks the oracle about is exactly the set the shipped
+ * classifier asked about, link for link.
+ *
+ * Existence-gated, and the gate is the point: a path that is not there cannot
+ * leak anything, and neither oracle can be trusted to say so — see
+ * {@link readGitignored}.
+ */
+function classifyGitignored(targetPath, options, facts, state) {
+    if (!facts.exists)
+        return undefined;
+    if (!readGitignored(targetPath, options, state))
+        return undefined;
+    return classifyGitignoredTarget(targetPath, options.deferredArtifacts);
+}
+/**
+ * Apply a verdict to the walk state — the only place the classifier's decision
+ * becomes a mutation.
+ *
+ * @returns true if the caller should stop processing this link
+ */
+function applyExclusionVerdict(verdict, targetPath, sourcePath, link, facts, state) {
+    switch (verdict.kind) {
+        case 'deferred': {
+            state.deferredAssetSet.add(toForwardSlash(targetPath));
+            return true;
+        }
+        case 'excluded': {
+            state.excludedReferences.push(makeExclusion(targetPath, sourcePath, facts.exists, verdict.reason, link, verdict.matchedRule));
+            return true;
+        }
+        case 'skipped': {
+            return true;
+        }
+    }
+}
+/**
+ * Check if a target path should be excluded for structural reasons
+ * (deferred build artifact, directory, outside project, navigation file, or
+ * pattern match).
+ *
+ * Pass 1′ fills the row, pass 4 judges it, and the recording is a third step —
+ * the three used to be one interleaved function that stat'ed paths mid-cascade.
+ *
+ * @returns true if the link was excluded or deferred (caller should skip to next link)
+ */
+function checkExclusions(targetPath, sourcePath, link, options, excludeMatchers, state) {
+    const facts = fillPathFacts(targetPath, options, state);
+    const verdict = classifyExclusion(targetPath, options, excludeMatchers, facts)
+        ?? classifyGitignored(targetPath, options, facts, state);
+    if (verdict === undefined)
+        return false;
+    return applyExclusionVerdict(verdict, targetPath, sourcePath, link, facts, state);
 }
 /**
  * Process a single local_file link during the graph walk.
@@ -292,7 +437,7 @@ function processLink(link, currentResource, currentDepth, registry, options, exc
     // Resolve the target path from the link href
     const targetPath = resolveHrefToPath(hrefWithoutAnchor, currentResource.filePath, options.projectRoot);
     // Check structural exclusions (deferred, directory, boundary, navigation, pattern, gitignore)
-    if (checkExclusions(targetPath, currentResource.filePath, link, options, excludeMatchers, state.excludedReferences, state.deferredAssetSet)) {
+    if (checkExclusions(targetPath, currentResource.filePath, link, options, excludeMatchers, state)) {
         return;
     }
     // Try to find the target in the registry (markdown files)
@@ -301,22 +446,96 @@ function processLink(link, currentResource, currentDepth, registry, options, exc
         : registry.getResource(targetPath);
     if (targetResource) {
         processRegistryResource(targetResource, targetPath, currentResource.filePath, link, currentDepth, options, state);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Path from parsed markdown
+        // Straight to the probe, not through `fillPathFacts`: this site wants one
+        // column, and building a whole row to read it would compute an
+        // `insideProject` the caller immediately discards. The probe memo is what
+        // makes it free — this used to be a second `existsSync` of the identical
+        // path in the same tick.
     }
-    else if (existsSync(targetPath)) {
-        // Not in registry — non-markdown asset that exists on disk
+    else if (state.pathProbe.probe(targetPath).exists) {
+        // Not in registry — non-markdown asset that exists on disk.
+        //
+        // ⚠️ `currentDepth` is deliberately NOT consulted here, and its absence is
+        // the behaviour, not an oversight. An asset is a leaf: bundling it enqueues
+        // nothing, so there is no depth for a limit to bound. A `maxDepth` of 1
+        // therefore still ships every image, JSON and PDF hanging off a
+        // depth-3 document, provided some routed markdown reached that document.
+        // Stated in {@link walkLinkGraph}'s own semantics list ("Non-markdown
+        // assets bypass depth limits") and mirrored for non-routable REGISTRY
+        // members in {@link processRegistryResource} — do not "fix" one site
+        // without the other; they are one rule with two arms.
         state.bundledAssetSet.add(toForwardSlash(targetPath));
     }
     else {
         // File doesn't exist and not in registry, and not deferred (handled above).
         // Record as missing-target so downstream emits LINK_MISSING_TARGET.
         state.excludedReferences.push(makeExclusion(targetPath, currentResource.filePath, false, 'missing-target', link));
+        return;
+    }
+    if (relativeEscapesRoot(safePath.relative(dirname(options.skillRootPath), targetPath))) {
+        state.followedOutsideSkillDir.push(makeFollowedLink(targetPath, currentResource.filePath, true, link));
     }
 }
 /**
- * Process a registry resource link: check depth, cycle, and either bundle or exclude.
+ * Is this file one the walker walks THROUGH, enqueuing its link targets as
+ * further bundle members?
+ *
+ * Routing is markdown-only. HTML may be a registry member — parsed, links
+ * known, reachable by the rewriter — without being a door: the decision is
+ * "a leaf we can read, not a door we walk through", and it is spec-backed
+ * (Anthropic's skill guidance is markdown throughout, and VAT's own stance docs
+ * mention HTML nowhere).
+ *
+ * Keyed on {@link parserKindForPath} rather than a local extension test, so
+ * VAT keeps ONE parser discriminator: a format that gains a parser gains a
+ * routability answer in the same edit.
+ */
+function isRoutable(filePath) {
+    return parserKindForPath(filePath) === 'markdown';
+}
+/**
+ * Record every local-file link out of a bundled non-routable member as a
+ * candidate `non-routable-source` exclusion.
+ *
+ * Without this the targets simply vanish: `SKILL.md → guide.html →
+ * diagram.svg` bundles the HTML, never looks inside it, and ships a bundled
+ * page whose `<img src>` points at a file that is not there. A silent drop
+ * becomes a reported one.
+ */
+function recordUnfollowedLinks(member, options, state) {
+    for (const link of member.links) {
+        if (!isLocalFileLink(link.type))
+            continue;
+        const hrefWithoutAnchor = link.href.split('#')[0] ?? link.href;
+        if (hrefWithoutAnchor === '')
+            continue;
+        const targetPath = resolveHrefToPath(hrefWithoutAnchor, member.filePath, options.projectRoot);
+        const targetExists = state.pathProbe.probe(targetPath).exists;
+        state.unfollowedFromNonRoutable.push(makeExclusion(targetPath, member.filePath, targetExists, 'non-routable-source', link));
+    }
+}
+/**
+ * Process a registry resource link: check routability, depth, cycle, and either
+ * bundle or exclude.
  */
 function processRegistryResource(targetResource, targetPath, sourcePath, link, currentDepth, options, state) {
+    // A non-routable member is a leaf, and leaves are bundled on the same terms
+    // as plain assets — which bypass `maxDepth` entirely. Checking routability
+    // BEFORE depth is what makes adding HTML to a registry a pure gain: the file
+    // still travels exactly as it did when it was an unparsed asset, it is merely
+    // parsed now so the rewriter can reach its links. Applying the depth limit
+    // here instead would silently DROP HTML that a markdown-only registry shipped.
+    if (!isRoutable(targetResource.filePath)) {
+        if (state.visitedResourceIds.has(targetResource.id)) {
+            return;
+        }
+        state.visitedResourceIds.add(targetResource.id);
+        state.bundledResourceMap.set(targetResource.id, targetResource);
+        // `maxBundledDepth` describes how far the walk ROUTED. A leaf does not
+        // extend that, any more than a bundled PNG does.
+        recordUnfollowedLinks(targetResource, options, state);
+        return;
+    }
     // Check depth limit. A registry resource came from a disk crawl, so it
     // exists by construction — `targetExists: true` is a fact here, not a guess.
     if (currentDepth >= options.maxDepth) {
@@ -352,9 +571,36 @@ function processRegistryResource(targetResource, targetPath, sourcePath, link, c
  * @returns Graph walk result with bundled resources, assets, and exclusions
  */
 export function walkLinkGraph(skillResourceId, registry, options) {
+    // This walker is not a projection contributor, so the merge driver never sees
+    // it and it has no stratum of its own. It records under the synthetic id
+    // `walk-link-graph:walk` in the `crawl` stratum — declared in
+    // `crawl-timing.ts`, deliberately not an ad-hoc string here, because a
+    // synthetic id that arrives by accident is indistinguishable in the dump from
+    // a real contributor's.
+    //
+    // `try`/`finally` rather than a record before each `return`: the early exit
+    // for an unknown skill id is a real (cheap) call and must still be counted,
+    // and a throw must not silently drop a bracket.
+    const startedAt = crawlTimingStart();
+    try {
+        return walkLinkGraphBody(skillResourceId, registry, options);
+    }
+    finally {
+        recordCrawlPass(CRAWL_WALKER_ID, 'crawl', CRAWL_PASS_INSIDE, startedAt);
+    }
+}
+/**
+ * The walk itself, with no timing concern in it.
+ *
+ * @param skillResourceId - The resource ID of the skill's SKILL.md in the registry
+ * @param registry - A walkable registry with pre-parsed resources
+ * @param options - Walk options (depth, excludes, etc.)
+ * @returns Graph walk result with bundled resources, assets, and exclusions
+ */
+function walkLinkGraphBody(skillResourceId, registry, options) {
     const skillResource = registry.getResourceById(skillResourceId);
     if (!skillResource) {
-        return { bundledResources: [], bundledAssets: [], excludedReferences: [], maxBundledDepth: 0, deferredAssets: [] };
+        return { bundledResources: [], bundledAssets: [], excludedReferences: [], outsideSkillDirLinks: [], maxBundledDepth: 0, deferredAssets: [] };
     }
     // Compile exclude patterns once
     const excludeMatchers = options.excludeRules.map((rule) => ({
@@ -374,6 +620,10 @@ export function walkLinkGraph(skillResourceId, registry, options) {
         excludedReferences: [],
         maxBundledDepth: 0,
         queue: [[skillResource, 0]],
+        unfollowedFromNonRoutable: [],
+        followedOutsideSkillDir: [],
+        pathProbe: options.pathProbe ?? new FsLookupCache(),
+        gitignoreFacts: new Map(),
     };
     while (state.queue.length > 0) {
         const entry = state.queue.shift();
@@ -387,10 +637,44 @@ export function walkLinkGraph(skillResourceId, registry, options) {
             }
         }
     }
+    // What actually SHIPPED, resolved once the walk is over. Deferred artifacts
+    // count as accounted-for: the target will exist once the build materializes
+    // it, which is the same reason they are not `missing-target`.
+    const bundledPaths = new Set([
+        ...state.bundledAssetSet,
+        ...state.deferredAssetSet,
+        ...[...state.bundledResourceMap.values()].map(r => toForwardSlash(r.filePath)),
+    ]);
+    const targetShipped = (r) => bundledPaths.has(toForwardSlash(r.path));
+    // 🔑 Two reasons ask ONE question — "did the target ship?" — and both can only
+    // answer it here, against the FINAL bundle, or the answer depends on queue
+    // order.
+    //
+    // `depth-exceeded` is recorded eagerly, at the moment an edge is refused, and
+    // that is correct: the refusal is a fact about the EDGE. It is not a fact
+    // about the TARGET, and `LINK_DROPPED_BY_DEPTH` claims the latter — "this link
+    // was not bundled". On any diamond the two diverge: the same reference cited
+    // from SKILL.md and again from a page one hop deeper ships via the shallow
+    // route and is refused on the deep one, and the finding used to fire anyway.
+    // Measured on `packages/vat-example-cat-agents`, whose
+    // `cat-breed-selection.md` is in the built bundle at depth 1 and was reported
+    // dropped for its depth-2 occurrence via `workflow-orchestration.md`. The
+    // remedy the message implies — raise `linkFollowDepth` — is a no-op for a link
+    // that already works.
+    //
+    // Filtered in place rather than held back and appended, so the surviving
+    // exclusions keep the order the walk found them in.
+    const excludedReferences = state.excludedReferences.filter((r) => r.excludeReason !== 'depth-exceeded' || !targetShipped(r));
+    for (const unfollowed of state.unfollowedFromNonRoutable) {
+        if (!targetShipped(unfollowed)) {
+            excludedReferences.push(unfollowed);
+        }
+    }
     return {
         bundledResources: [...state.bundledResourceMap.values()],
         bundledAssets: [...state.bundledAssetSet],
-        excludedReferences: state.excludedReferences,
+        excludedReferences,
+        outsideSkillDirLinks: state.followedOutsideSkillDir.filter(targetShipped),
         maxBundledDepth: state.maxBundledDepth,
         deferredAssets: [...state.deferredAssetSet],
     };