xdrs-core 0.52.1 → 0.52.2

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -75,6 +75,8 @@ Examples:
 
 Multiple skills under the same `[subject]/skills/` folder MAY share common instruction modules through a sibling `.assets/` directory placed directly under `skills/` (not inside any individual skill package) — for example `skills/.assets/shared-check.md`, referenced with a relative link from any skill in that folder. This keeps shared procedures DRY without duplicating instructions across skills.
 
+A skill's own `.assets/` folder and the shared `skills/.assets/` folder are exempt from orphan-asset tracking: their files do not need to be linked from `SKILL.md`, because they may hold scripts, templates, installed dependencies (e.g., `node_modules/`), or other runtime resources used by the skill. When `SKILL.md` does link to an asset, the link MUST point either to the skill's own `.assets/` folder or to the shared `../.assets/` folder.
+
 A skill MAY optionally be distributed as a self-contained standalone package (for example, to share it outside this repository) using the bundling mechanism defined in [`_core-adr-policy-021`](021-skill-bundling.md). Bundling is optional; skills that are always consumed as part of the full package do not need it.
 
 **Directory roles**
@@ -84,7 +86,7 @@ A skill MAY optionally be distributed as a self-contained standalone package (fo
 | `SKILL.md` | Required entry point: frontmatter + instructions. |
 | `scripts/` | Optional executable scripts the agent may run. |
 | `references/` | Optional deep reference material split out of `SKILL.md`. |
-| `.assets/` | Optional images, templates, and other local resource files. |
+| `.assets/` | Optional images, templates, scripts, dependencies, and other local resource files. Not subject to orphan-asset tracking. |
 
 **Skill naming**
 

package/lib/lint.js

@@ -1351,7 +1351,6 @@ function lintSkillsDirectory(xdrsRoot, scopeName, skillsPath, errors, externalSc
     lintNoEmojis(skillContent, skillFilePath, 'Skill', errors);
     lintWordCount(skillContent, skillFilePath, 'Skill', SKILL_MAX_WORDS, errors);
     lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors, externalScopes);
-    lintOrphanAssets(path.join(entryPath, RESOURCE_DIR_NAME), [skillFilePath], xdrsRoot, errors);
   }
 
   return artifacts;
@@ -2238,6 +2237,8 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalSc
   const ignoredLines = findIgnoredMarkdownLines(lines);
   const documentDir = path.dirname(documentPath);
   const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
+  const isSkillFile = path.basename(documentPath) === 'SKILL.md' && path.basename(path.dirname(documentDir)) === 'skills';
+  const sharedSkillResourceDir = isSkillFile ? path.join(path.dirname(documentDir), RESOURCE_DIR_NAME) : null;
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
   const repoRoot = path.dirname(xdrsRoot);
 
@@ -2267,7 +2268,8 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalSc
         errors.push(`Non-_local document must not link into _local scope in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget} [_core-adr-policy-001]`);
       }
 
-      if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
+      if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)
+        && !(sharedSkillResourceDir && isPathInside(sharedSkillResourceDir, link.resolvedPath))) {
         errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget} [_core-adr-policy-001]`);
       }
 

package/lib/lint.test.js

@@ -2664,6 +2664,56 @@ test('reports orphan asset in articles .assets directory', () => {
   expect(result.errors.join('\n')).not.toContain('used.png');
 });
 
+test('does not report orphan asset errors for unlinked files in a skill package .assets directory', () => {
+  const workspaceRoot = createWorkspace('skill-assets-not-orphan', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Test instructions.'),
+    '.xdrs/_local/adrs/principles/skills/check-links/.assets/template.json': '{}',
+    '.xdrs/_local/adrs/principles/skills/check-links/.assets/run.sh': 'echo run\n',
+    '.xdrs/_local/adrs/principles/skills/check-links/.assets/node_modules/pkg/index.js': 'module.exports = {};\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Orphan asset file');
+});
+
+test('allows SKILL.md links to the shared skills .assets directory', () => {
+  const workspaceRoot = createWorkspace('skill-shared-assets-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Follow [shared check](../.assets/shared-check.md).'),
+    '.xdrs/_local/adrs/principles/skills/.assets/shared-check.md': '# Shared check\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Asset links in');
+  expect(result.errors.join('\n')).not.toContain('Broken asset link');
+});
+
+test('reports SKILL.md links to another skill package .assets directory', () => {
+  const workspaceRoot = createWorkspace('skill-other-assets-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links',
+      '- [other-skill](principles/skills/other-skill/SKILL.md) - Other skill'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Use [template](../other-skill/.assets/template.md).'),
+    '.xdrs/_local/adrs/principles/skills/other-skill/SKILL.md': skillDocument('Test instructions.').replace('name: check-links', 'name: other-skill'),
+    '.xdrs/_local/adrs/principles/skills/other-skill/.assets/template.md': '# Template\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Asset links in');
+});
+
 test('reports unexpected directories inside a skill package', () => {
   const workspaceRoot = createWorkspace('unexpected-skill-package-directory', {
     '.xdrs/index.md': rootIndex(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.52.1",
+  "version": "0.52.2",
   "description": "XDRS (eXtensible Decision Record System): a framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",