@vibe-agent-toolkit/agent-skills 0.1.41-rc.7 → 0.1.41

package/dist/skill-packager.js

@@ -17,14 +17,16 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { basename, dirname } from 'node:path';
-import { runValidationFramework, } from '@vibe-agent-toolkit/agent-schema';
+import { allowUnusedIssues, createAllowUsageLedger, runValidationFramework, } from '@vibe-agent-toolkit/agent-schema';
 import { DeferredArtifacts, ResourceRegistry, loadConfig, openFrontmatter, resolveLocalHref, rewriteFrontmatterUriReferencesFromSchema, rewriteHtmlLinks, transformContent, parseMarkdown, } from '@vibe-agent-toolkit/resources';
-import { findProjectRoot, isGlob, resolveAssetReference, toForwardSlash, safePath, } from '@vibe-agent-toolkit/utils';
-import { getTargetSubdir } from './content-type-routing.js';
-import { applyFilesConfig, buildArtifactHint } from './files-config.js';
+import { findProjectRoot, isGlob, issueLocation, resolveAssetReference, toForwardSlash, safePath, } from '@vibe-agent-toolkit/utils';
+import { CLAUDE_WEB_REFERENCES_SUBDIR, getTargetSubdir } from './content-type-routing.js';
+import { applyFilesConfig, buildArtifactHint, droppedGlobMatchesToIssues, explicitFilesConfigDests, globEntryDest, } from './files-config.js';
 import { checkBrokenPackagedLinks, checkUnreferencedFiles } from './post-build-checks.js';
 import { checkPackagedTestInput, partitionTestInputFileEntries, resolveTestInputDirs, testInputExcludeRules, testInputFileEntryIssues, testInputLinkIssues, } from './test-input.js';
+import { detectPackagedAgentInstructionFiles } from './validators/agent-instruction-presence.js';
 import { validateSkillForPackaging } from './validators/packaging-validator.js';
+import { materializeIssue } from './validators/rule-engine/index.js';
 import { deferredAssetsToIssues, walkerExclusionsToIssues } from './validators/walker-to-issues.js';
 import { walkLinkGraph } from './walk-link-graph.js';
 const PACKAGE_JSON_FILENAME = 'package.json';
@@ -96,8 +98,15 @@ const DEFAULT_PACKAGING_TARGET = 'claude-code';
  * The single canonical conversion used by BOTH `vat skills build` and
  * `vat skill test` (the pool build), so the dist a test exercises is byte-for-byte
  * what `vat skills build` would produce. `basePath` defaults to `dirname(skillPath)`.
+ *
+ * `projectSkills` is EVERY skill the project declares, with its effective packaging
+ * config — assembled ONCE per invocation by the calling lane and passed down, never
+ * recomputed per skill (a per-skill walk of the whole project config is an N+1 this
+ * repo has been bitten by). It is required rather than defaulted because the test-input
+ * rule is project-wide: omitting it silently packages another skill's eval answer key.
+ * A lane with genuinely no project to enumerate passes `[]` explicitly.
  */
-export function packagingConfigToPackageOptions(config, anchors) {
+export function packagingConfigToPackageOptions(config, anchors, projectSkills) {
     return {
         outputPath: anchors.outputPath,
         formats: ['directory'],
@@ -106,14 +115,27 @@ export function packagingConfigToPackageOptions(config, anchors) {
         ...(config.resourceNaming && { resourceNaming: config.resourceNaming }),
         ...(config.stripPrefix && { stripPrefix: config.stripPrefix }),
         ...(config.linkFollowDepth !== undefined && { linkFollowDepth: config.linkFollowDepth }),
+        // `!== undefined`, not truthiness: `false` is the only value that carries
+        // information here (the packager defaults to `true`), so a truthiness spread
+        // would drop exactly the setting a user bothered to write. Dropping it made
+        // this conversion disagree with `packaging-validator.ts`, which reads the same
+        // key straight off the config — the gate predicted a README ships and the
+        // build stripped it, from one config, inside the conversion that promises
+        // byte-for-byte parity between lanes.
+        ...(config.excludeNavigationFiles !== undefined && {
+            excludeNavigationFiles: config.excludeNavigationFiles,
+        }),
         ...(config.excludeReferencesFromBundle && { excludeReferencesFromBundle: config.excludeReferencesFromBundle }),
         ...(config.files && { files: config.files }),
         ...(config.validation && { validation: config.validation }),
         // Declared test input never ships. Derived here — the ONE conversion both
         // `vat skills build` and the plugin build go through — so no lane can package a
-        // skill without the rule applied.
+        // skill without the rule applied. PROJECT-WIDE: `projectSkills` carries every
+        // other skill's declaration too, so a link into a SIBLING skill's suite is
+        // excluded as well. Keyed to this skill alone, that sibling's answer key was
+        // ordinary content and shipped.
         ...(() => {
-            const testInputDirs = resolveTestInputDirs(config, dirname(anchors.skillPath));
+            const testInputDirs = resolveTestInputDirs(config, dirname(anchors.skillPath), projectSkills);
             return testInputDirs.length > 0 ? { testInputDirs } : {};
         })(),
     };
@@ -125,9 +147,36 @@ export function packagingConfigToPackageOptions(config, anchors) {
  * then packages each skill against the shared registry. This eliminates
  * redundant I/O when building multiple skills from the same project.
  *
+ * **One skill's failure never discards the batch.** `packageSkill` reports most
+ * problems by RETURNING a result whose `hasErrors` is set, which callers already
+ * degrade gracefully on — but it also THROWS on structural packaging failures
+ * (an absent or unreadable `files:` source). Letting that throw escape the loop
+ * made the two failure paths behave in opposite ways through one contract:
+ * measured on a 90-skill project, one such failure discarded 89 completed builds
+ * and collapsed the whole report into a single string. Each iteration is
+ * therefore contained and reported as a `failed` outcome instead.
+ *
+ * A filename collision is NOT one of the throwing paths — it is a returned
+ * `FILENAME_COLLISION` finding. Do not reach for a collision as the fixture when
+ * testing this containment: the loop completes normally either way, so such a
+ * test passes whether or not the containment exists.
+ *
+ * The registry build is deliberately OUTSIDE the containment: it is the run's
+ * shared prerequisite, so its failure really does doom every skill and must
+ * still propagate. Only per-skill work is contained.
+ *
  * @param skills - Array of skill build specifications
  * @param projectRoot - Absolute path to the project root directory
- * @returns Array of package results (one per skill)
+ * @param allowLedger - The RUN's allow-usage ledger. Required, not
+ *   optional-with-a-default, for the same reason `runValidationFramework`'s is:
+ *   this function loops, so it can never honestly conclude on its own that an
+ *   allow entry matched nothing — an entry matched while building skill A is
+ *   USED for the run. It is never drained here; the caller drains it once with
+ *   `allowUnusedIssues()` after everything in the invocation has been seen
+ *   (`vat build` also validates the SOURCE tree, whose matches count too).
+ *   Containment does not change that: a skill that threw may still have matched
+ *   allow entries before it threw, and those matches count for the run.
+ * @returns One outcome per input spec, in input order
  *
  * @example
  * ```typescript
@@ -135,22 +184,35 @@ export function packagingConfigToPackageOptions(config, anchors) {
  *   { skillPath: '/project/skills/SKILL.md', options: { outputPath: '/out/skill-a' } },
  *   { skillPath: '/project/skills/SKILL2.md', options: { outputPath: '/out/skill-b' } },
  * ];
- * const results = await packageSkills(specs, '/project');
+ * const ledger = createAllowUsageLedger();
+ * const outcomes = await packageSkills(specs, '/project', ledger);
+ * const runIssues = allowUnusedIssues(ledger);
  * ```
  */
-export async function packageSkills(skills, projectRoot) {
+export async function packageSkills(skills, projectRoot, allowLedger) {
     // 1. Create one registry for the entire project. Through the shared builder:
     // this used to call `fromCrawl` directly and omit the config, so skills built
     // here belonged to no collection while a skill built through the single-skill
     // fallback did.
     const registry = await createProjectRegistry(projectRoot);
     // 2. Package each skill against the shared registry
-    const results = [];
+    const outcomes = [];
     for (const { skillPath, options } of skills) {
-        const result = await packageSkill(skillPath, { ...options, registry });
-        results.push(result);
+        try {
+            const result = await packageSkill(skillPath, { ...options, registry, allowLedger });
+            outcomes.push({ status: 'built', skillPath, result });
+        }
+        catch (error) {
+            // Not swallowed: the error is carried on the outcome so the caller reports
+            // WHICH skill failed and why, and gates the run's exit code on it.
+            outcomes.push({
+                status: 'failed',
+                skillPath,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
     }
-    return results;
+    return outcomes;
 }
 /**
  * Package a skill with all its dependencies
@@ -179,6 +241,21 @@ export async function packageSkill(skillPath, options = {}) {
     // Library callers fall back to the skill directory when canonical
     // findProjectRoot returns null. The CLI command boundary is responsible
     // for any user-facing warning about missing project roots.
+    //
+    // COORDINATE-SYSTEM ASSUMPTION, not an enforced invariant. This root is the base
+    // every path this call REPORTS is stated in — `namingBasePath` at step 8, and the
+    // `projectRoot` handed to `walkerExclusionsToIssues` / `testInputLinkIssues` /
+    // `deferredAssetsToIssues` at step 13b. It is derived HERE, per skill, from the
+    // skill's own path. It is NOT the `projectRoot` argument `packageSkills` was called
+    // with (that one is used only for `createProjectRegistry`), and it is not the `cwd`
+    // that `vat skills build` treats as the root of the document it emits.
+    //
+    // UNVERIFIED that these can actually diverge: in every path exercised so far the two
+    // have coincided (`vat skills build` passes its `cwd`, and the skills it discovers
+    // live under it), and no run has been observed where they differ. Nothing enforces
+    // the equality, though — a caller packaging a skill from outside its own project
+    // root would get issue locations in one coordinate system and a report header in
+    // another, with no error anywhere.
     const projectRoot = findProjectRoot(dirname(skillPath)) ?? dirname(skillPath);
     const skillRoot = dirname(skillPath);
     // 3. Get or create the resource registry.
@@ -247,10 +324,15 @@ export async function packageSkill(skillPath, options = {}) {
     }
     // 8. Build path map for file copying and link rewriting
     const namingBasePath = projectRoot;
-    const pathMap = buildPathMap(skillPath, bundledFiles, outputPath, resourceNaming, namingBasePath, stripPrefix, target);
-    // 8b. Apply files config: register single-file entries in path map.
-    // GLOB entries are skipped — late binding via applyFilesConfig owns their expansion.
-    applyNonGlobEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMap, skillMetadata.name);
+    const pathMapSkill = { path: skillPath, name: skillMetadata.name };
+    const pathMap = buildPathMap(pathMapSkill, bundledFiles, outputPath, resourceNaming, namingBasePath, stripPrefix, target);
+    // 8b. Apply files config to the path map: single-file entries by name, and glob
+    // entries by re-pointing the link-bundled files they claim at the declared dest.
+    applyFilesEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMap, skillMetadata.name, bundledFiles);
+    // 8c. Collisions are judged on the FINAL destination map, so a `files:` remap is
+    // a real remedy and a `files:`-created collision is still caught. See
+    // detectDestinationCollisions for why this cannot run inside buildPathMap.
+    const collisionIssues = detectDestinationCollisions(pathMapSkill, pathMap, outputPath, resourceNaming, namingBasePath);
     // 9. Build "to" registry for link rewriting (maps same resource IDs to output paths)
     const outputResources = bundledResources.map(resource => ({
         ...resource,
@@ -313,9 +395,16 @@ export async function packageSkill(skillPath, options = {}) {
     // Keep the dests it reports: they are what makes the orphan check below able to
     // tell "the author forgot to document this" from "VAT put this here because the
     // config said to." Discarding them makes the build fail on its own payload.
-    const filesConfigDests = await applyFilesConfig({
+    const appliedFiles = await applyFilesConfig({
         filesConfig, projectRoot, skillOutputDir: outputPath, bundledFiles,
     });
+    const filesConfigDests = appliedFiles.dests;
+    // Dests a glob matched and the never-package list refused. Two consumers, and
+    // both are load-bearing: the broken-link check below needs them to tell a link
+    // broken by policy from a link broken by the rewriter, and the finding channel
+    // needs them or the structured report says `warnings: 0` about a build that
+    // silently shipped less than the config asked for.
+    const droppedGlobDests = appliedFiles.dropped.map((drop) => drop.dest);
     // 13. Post-build integrity check: no SKILL.md in subdirectories
     // A SKILL.md is a skill definition marker — it must only exist at the root.
     // If another skill's SKILL.md was bundled as a resource, it creates duplicate
@@ -329,8 +418,31 @@ export async function packageSkill(skillPath, options = {}) {
     // Walker-exclusion issues (depth drops, missing targets, outside-project, etc.)
     // are combined with post-build checks and run through the validation framework.
     const rawPostBuildIssues = [
+        // Found back at step 8, reported here: the path map is decided before any
+        // file is written, but a collision is a packaging FINDING and rides the same
+        // channel as every other one rather than aborting the run from inside a
+        // helper.
+        ...collisionIssues,
         ...await checkUnreferencedFiles(outputPath, filesConfigDests),
-        ...await checkBrokenPackagedLinks(outputPath),
+        ...await checkBrokenPackagedLinks(outputPath, droppedGlobDests),
+        // A receipt for every file a glob matched and the never-package list refused.
+        // Reported as an issue, not written to stderr: a file vanishing from a bundle
+        // has to be visible in `issueCounts`, or CI reads a clean report for a build
+        // that quietly shipped less than the config declared.
+        // Anchored at the PROJECT root, not `outputPath` like its neighbours here: a
+        // dropped file is a source file that never reached the output, so the only
+        // path a reader can open is its source path.
+        ...droppedGlobMatchesToIssues(appliedFiles.dropped, projectRoot),
+        // Presence-side backstop for agent-instruction files. The walker excludes
+        // them from link-following, but a `files:` glob can still copy one in, and
+        // a file that arrives without a link is invisible to the link lane.
+        //
+        // Explicitly-declared dests are exempt (§8.2 precedence): the build KNOWS the
+        // config here, and an explicit `files:` entry is an instruction to ship that
+        // exact file. Reporting it fired this warning on the very config the guide
+        // prescribes as the escape hatch, with a remedy ("remove the file") that says
+        // to undo what the author was told to write.
+        ...detectPackagedAgentInstructionFiles(outputPath, outputPath, explicitFilesConfigDests(filesConfig)),
         // A receipt for each `files:` entry that was dropped for pointing into declared
         // test input — the build already produced the right artifact; this just says so.
         ...testInputFileEntryIssues(droppedTestInputFiles),
@@ -346,9 +458,26 @@ export async function packageSkill(skillPath, options = {}) {
         ...testInputLinkIssues(excludedReferences, testInputDirs, projectRoot),
         ...deferredAssetsToIssues(deferredAssets, projectRoot),
     ];
-    const framework = runValidationFramework([...rawLinkIssues, ...rawPostBuildIssues], options.validation ?? {});
+    // ONE ledger for BOTH lanes below. `options.validation.allow` governs the
+    // build-receipt lane AND the built-SKILL.md lane, but the two see disjoint
+    // issue populations — so a lane that drains its own ledger calls "unused" an
+    // entry the OTHER lane matched. (Measured before the fix: an entry that
+    // suppressed a real LINK_MISSING_TARGET error still emitted ALLOW_UNUSED from
+    // the built-output lane, and a genuinely dead entry was reported twice.) Same
+    // defect, same fix as the validate lane — see
+    // `SkillValidationSharedContext.allowLedger`.
+    //
+    // Whose run it is comes from the caller. Given a ledger, this call is one unit
+    // of a larger run (a batch, and/or a source-tree validation pass that matches
+    // entries this build's two lanes structurally cannot) and must NOT drain —
+    // draining here is what reported a package-scoped entry matched while building
+    // skill A as unused while building skill B. Given none, the caller has claimed
+    // this call IS the run, so the drain below is honest.
+    const ownsRun = options.allowLedger === undefined;
+    const buildRunLedger = options.allowLedger ?? createAllowUsageLedger();
+    const framework = runValidationFramework([...rawLinkIssues, ...rawPostBuildIssues], options.validation ?? {}, buildRunLedger);
     // 13c. Run full validation suite on built output
-    const postBuildValidation = await runPostBuildValidation(outputPath, options.validation);
+    const postBuildValidation = await runPostBuildValidation(outputPath, options.validation, buildRunLedger);
     // 14. Generate distribution artifacts
     const artifacts = await generatePackageArtifacts(outputPath, skillMetadata, formats, target);
     // Get relative paths for result
@@ -360,18 +489,37 @@ export async function packageSkill(skillPath, options = {}) {
         relativeLinkedFiles,
         artifacts,
         postBuildValidation,
-        framework,
+        // Drain point — but only when this call owns the run. Both lanes have now
+        // contributed; whether anything ELSE still will is the caller's claim.
+        framework: ownsRun ? withRunAllowUnused(framework, buildRunLedger) : framework,
         excludedReferences,
         skillRoot,
     });
 }
+/**
+ * Fold the build run's ALLOW_UNUSED verdict into the build-issue lane.
+ *
+ * ALLOW_UNUSED belongs to the RUN, not to whichever lane happened to be looking
+ * when an entry went unmatched — so it is drained once, here, and reported on
+ * the single channel (`postBuildIssues`) rather than on both.
+ */
+function withRunAllowUnused(framework, ledger) {
+    const unused = allowUnusedIssues(ledger);
+    if (unused.length === 0)
+        return framework;
+    const emitted = [...framework.emitted, ...unused];
+    return { ...framework, emitted, hasErrors: emitted.some(i => i.severity === 'error') };
+}
 /**
  * Run full validation suite against built output (context = 'built').
  * Source-only codes are automatically filtered out by validateSkillForPackaging.
+ *
+ * `allowLedger` is required, not optional: this lane is one half of a build, so
+ * it must never conclude on its own that an allow entry matched nothing.
  */
-async function runPostBuildValidation(outputPath, validation) {
+async function runPostBuildValidation(outputPath, validation, allowLedger) {
     const builtSkillPath = safePath.join(outputPath, 'SKILL.md');
-    return validateSkillForPackaging(builtSkillPath, validation ? { validation } : undefined, 'built');
+    return validateSkillForPackaging(builtSkillPath, validation ? { validation } : undefined, 'built', { allowLedger });
 }
 /**
  * Assemble the final PackageSkillResult from intermediate data.
@@ -387,7 +535,7 @@ function assemblePackageResult(input) {
         },
         artifacts: input.artifacts,
         postBuildValidation: input.postBuildValidation,
-        hasErrors: input.framework.hasErrors || input.postBuildValidation.activeErrors.length > 0,
+        hasErrors: input.framework.hasErrors || input.postBuildValidation.status === 'error',
     };
     if (input.framework.emitted.length > 0) {
         result.postBuildIssues = input.framework.emitted;
@@ -597,17 +745,53 @@ function buildSyntheticAssetResource(assetPath, outputFilePath) {
     };
 }
 /**
- * Register single-file (non-glob) files config entries in the path map.
+ * Re-point every LINK-BUNDLED file a GLOB `files:` entry also claims at the dest
+ * that entry declares.
+ *
+ * A glob's expansion is late-bound to copy time, so its matches used to be absent
+ * from the path map entirely — and a match that link traversal ALSO discovered was
+ * therefore parked at its type-derived location (`resources/GUIDE.md`) while
+ * `applyFilesConfig` copied the same bytes to the declared dest
+ * (`packs/alpha/GUIDE.md`). Two identical files shipped, the rewritten link pointed
+ * at traversal's copy, the declared `dest:` was dead, and nothing said so — a size
+ * regression for anyone shipping multi-megabyte artifacts, and a `dest:` that lies
+ * whenever the same file is also referenced from prose.
+ *
+ * Only files already in `bundledFiles` are considered: this is not a second
+ * expansion of the glob (that stays with {@link copyGlobEntry}), it is the path map
+ * — the authority on where a file ends up — learning what the config already said.
+ */
+function applyGlobEntryToPathMap(entry, projectRoot, outputPath, pathMap, bundledFiles) {
+    for (const bundled of bundledFiles) {
+        const dest = globEntryDest(entry, projectRoot, bundled);
+        if (dest === undefined)
+            continue;
+        // joinUnderRoot mirrors the non-glob branch's zip-slip guard below.
+        pathMap.set(toForwardSlash(bundled), safePath.joinUnderRoot(outputPath, dest));
+    }
+}
+/**
+ * Register `files:` config entries in the path map.
  *
- * GLOB entries are skipped — their source contains glob magic, never exists as a
- * literal path at build time, and would wrongly throw. Late binding via
- * applyFilesConfig owns their expansion at copy time.
+ * Two passes, GLOBS FIRST, and the order is the precedence rule: an explicit entry
+ * naming a file outranks a glob that merely caught it, exactly as it does on the
+ * copy side (see `partitionNeverPackaged` — a glob is a net, not a declaration).
+ * Applying globs second would let one silently overwrite the dest an author spelled
+ * out, and the explicit entry's own copy is then skipped as "already bundled at its
+ * dest" — so the declared file would never be written at all.
  *
  * Called from step 8b of packageSkill to keep the main function under the
  * cognitive-complexity limit.
  */
-function applyNonGlobEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMap, skillName) {
+function applyFilesEntriesToPathMap(filesConfig, projectRoot, outputPath, pathMap, skillName, bundledFiles) {
     for (const fileEntry of filesConfig) {
+        if (isGlob(fileEntry.source)) {
+            applyGlobEntryToPathMap(fileEntry, projectRoot, outputPath, pathMap, bundledFiles);
+        }
+    }
+    for (const fileEntry of filesConfig) {
+        // A glob source contains magic, never exists as a literal path, and would
+        // wrongly throw the existence check below; its dests were handled above.
         if (isGlob(fileEntry.source))
             continue;
         const absoluteSource = safePath.resolve(safePath.join(projectRoot, fileEntry.source));
@@ -760,37 +944,107 @@ function stampDeferredDestResolvedId(resources, absDestTarget, id) {
  */
 export function getResourceSubdirForFile(filePath, target) {
     if (target === 'claude-web') {
-        return 'references';
+        return CLAUDE_WEB_REFERENCES_SUBDIR;
     }
     return getTargetSubdir(filePath);
 }
 /**
- * Build a map of source paths (forward-slash normalized) to output paths.
- * Checks for filename collisions.
+ * The FILENAME_COLLISION finding for one pair of sources that package to one dest.
+ *
+ * Naming the skill is the whole point of the first line: neither colliding file
+ * need be referenced by SKILL.md directly (both are commonly reached by deep
+ * link traversal), so without it the only way to find the owner in a large
+ * batch is to bisect it one skill at a time.
+ *
+ * By NAME, not by absolute path: this message is published verbatim in
+ * `vat skills build`'s stdout payload, the name is what that payload's per-skill
+ * rows already key on, and a `/Users/<someone>/…` prefix answers no question the
+ * reader has while naming the machine the build ran on. The colliding files
+ * follow the same rule — stated in the project's coordinates, like every other
+ * "where" this package renders (`issueLocation`).
+ *
+ * `location` is the SECOND file: of the two, it is the one whose packaging the
+ * first pre-empted, so it is the one an author renames. The remedy that is not
+ * a rename (switch `resourceNaming`) comes from the registry `fix`.
  */
-function buildPathMap(skillPath, bundledFiles, outputPath, resourceNaming, namingBasePath, stripPrefix, target = DEFAULT_PACKAGING_TARGET) {
+function filenameCollisionIssue(skill, existingSource, linkedFile, targetRelPath, resourceNaming, namingBasePath) {
+    const location = issueLocation(linkedFile, namingBasePath);
+    return materializeIssue('FILENAME_COLLISION', {
+        location,
+        message: `Filename collision detected when packaging skill: ${skill.name} — ` +
+            `File 1: ${issueLocation(existingSource, namingBasePath)}, ` +
+            `File 2: ${location}; both would be packaged as ${targetRelPath} ` +
+            `(current resourceNaming strategy: ${resourceNaming})`,
+    });
+}
+/**
+ * Build a map of source paths (forward-slash normalized) to output paths, plus
+ * a FILENAME_COLLISION finding for every pair of sources that land on one dest.
+ *
+ * A collision is REPORTED, not thrown. It used to throw a raw `Error`, which
+ * escaped the contract every other packaging finding honours — the caller got a
+ * bare string instead of a coded, located, fixable `ValidationIssue`, and the
+ * batch lane had to special-case it. The build still fails: the finding's
+ * registry severity is `error`, so it flips `hasErrors`.
+ *
+ * The colliding source keeps its path-map entry rather than being dropped. The
+ * build is failing either way, and keeping it means the link rewriter still
+ * resolves both links to a file that exists in the output — dropping it would
+ * add a second, derived PACKAGED_BROKEN_LINK on top of the real finding and
+ * point the surviving link at an unrewritable source path.
+ *
+ * @param namingBasePath - The project root. Resource names are generated
+ *   relative to it AND every path this function REPORTS is stated in its
+ *   coordinates, so no message leaves here in machine-specific terms.
+ */
+function buildPathMap(skill, bundledFiles, outputPath, resourceNaming, namingBasePath, stripPrefix, target = DEFAULT_PACKAGING_TARGET) {
     const pathMap = new Map();
-    pathMap.set(toForwardSlash(skillPath), safePath.join(outputPath, 'SKILL.md'));
+    pathMap.set(toForwardSlash(skill.path), safePath.join(outputPath, 'SKILL.md'));
     for (const linkedFile of bundledFiles) {
         const targetRelPath = generateTargetPath(linkedFile, namingBasePath, resourceNaming, stripPrefix);
         const fileSubdir = getResourceSubdirForFile(linkedFile, target);
-        const targetPath = safePath.join(outputPath, fileSubdir, targetRelPath);
-        // Check for filename collisions
-        const existingSource = [...pathMap.entries()].find(([_src, target]) => target === targetPath)?.[0];
-        if (existingSource !== undefined && existingSource !== toForwardSlash(linkedFile)) {
-            throw new Error(`Filename collision detected when packaging skill:\n` +
-                `  File 1: ${existingSource}\n` +
-                `  File 2: ${linkedFile}\n` +
-                `  Both would be packaged as: ${targetRelPath}\n` +
-                `\n` +
-                `  To resolve: Use a different resourceNaming strategy or ensure unique filenames.\n` +
-                `  Current strategy: ${resourceNaming}\n` +
-                `  Try 'resource-id' or 'preserve-path' for path-based naming.`);
-        }
-        pathMap.set(toForwardSlash(linkedFile), targetPath);
+        pathMap.set(toForwardSlash(linkedFile), safePath.join(outputPath, fileSubdir, targetRelPath));
     }
     return pathMap;
 }
+/**
+ * Report a FILENAME_COLLISION for every destination claimed by more than one source.
+ *
+ * MUST run against the FINAL destination map — after `files:` single-file entries
+ * have overridden the naming-strategy destinations. Detecting collisions while
+ * building the map (where this logic used to live) answers the question one step
+ * too early: `files:` is a legitimate remedy for a basename collision, and an
+ * adopter who remapped both sides to distinct dests still had the build failed at
+ * `error` severity for a collision that no longer physically occurred. It also
+ * could not see the inverse — two `files:` entries pointing at ONE dest is a real
+ * collision the naming-strategy map contains no trace of.
+ *
+ * Scope: glob `files:` entries expand later (`applyFilesConfig`) and so are not in
+ * this map; their destinations are directories, which cannot collide this way.
+ */
+function detectDestinationCollisions(skill, pathMap, outputPath, resourceNaming, namingBasePath) {
+    const sourcesByDest = new Map();
+    for (const [source, dest] of pathMap) {
+        const existing = sourcesByDest.get(dest);
+        if (existing)
+            existing.push(source);
+        else
+            sourcesByDest.set(dest, [source]);
+    }
+    const issues = [];
+    for (const [dest, sources] of sourcesByDest) {
+        // Map iteration is insertion-ordered, so sources[0] is the entry that "won"
+        // the destination — the same File 1 / File 2 framing the message always used.
+        const [winner, ...losers] = sources;
+        if (winner === undefined || losers.length === 0)
+            continue;
+        const targetRelPath = toForwardSlash(safePath.relative(outputPath, dest));
+        for (const loser of losers) {
+            issues.push(filenameCollisionIssue(skill, winner, loser, targetRelPath, resourceNaming, namingBasePath));
+        }
+    }
+    return issues;
+}
 // ============================================================================
 // Rewrite Rules
 // ============================================================================