xdrs-core 0.52.0 → 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**
 
@@ -164,7 +166,7 @@ Rules:
 - `description` SHOULD stay near 250 characters when the activation trigger can be stated that tightly, even though the hard cap remains 1024 characters — it is loaded into context on every activation scan.
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter, and MUST contain nested subsections, in order, for `### Inputs`, `### Outputs`, `### Halt Conditions`, then the optional `### User Interaction` and `### Runtime Requirements`.
 - `### Inputs` MUST contain `#### Required` (the bare minimum needed to invoke the skill) then `#### Optional` (helpful extra context), in that order.
-- `## Instructions` SHOULD state one clearly recommended approach first when multiple are viable, noting alternatives briefly afterward, and SHOULD include verification steps or acceptance criteria at the end of the task or major phases.
+- `## Instructions` is REQUIRED. It SHOULD state one clearly recommended approach first when multiple are viable, noting alternatives briefly afterward, and SHOULD include verification steps or acceptance criteria at the end of the task or major phases.
 - `## Examples` SHOULD include 2-3 example prompts a user could give as input, alongside a short description of what to expect during execution and as output for each.
 - `### Outputs` covers only end-objective results, not intermediary items, and MUST contain `#### Contents` (generated files or chat-delivered results) then `#### Changes` (external system mutations that are part of the main objective), in that order.
 - `### Halt Conditions` MUST list this skill's specific stop-before-completing triggers, grounded in at least missing required input, dubious/ambiguous input, and insufficient agent confidence — distinct from `## Edge Cases` (activation/boundary conditions) and `## Anti-Patterns` (execution mistakes). A partial or empty result the skill still finishes and returns belongs in `### Outputs`, not `### Halt Conditions`.

package/.xdrs/_core/adrs/principles/008-policy-structured-standards.md

@@ -49,7 +49,7 @@ A rule title SHOULD include a normative keyword when the rule can be stated clea
 
 #### 08-rule-block-must-use-standard-syntax
 
-Each rule MUST be written as a level-4 heading with a two-digit zero-padded sequence number followed by a kebab-case title, and a body paragraph:
+Each rule MUST be written as a level-4 heading with a two-digit zero-padded sequence number followed by a kebab-case title of 12 words or fewer, and a body paragraph:
 
 ```markdown
 #### [NN]-[short-rule-title-in-kebab-case]

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;
@@ -2025,6 +2024,14 @@ function lintInitiativeExpectedEndDate(content, filePath, errors) {
     errors.push(`Initiative must not repeat Expected end date: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
   }
 
+  const sectionStart = findHeadingLine(lines, ignoredLines, '## Proposed Solution');
+  const sectionEnd = sectionStart === -1
+    ? -1
+    : (findHeadingLines(lines, ignoredLines).find((index) => index > sectionStart) ?? lines.length);
+  if (expectedEndDateLines.some((index) => index <= sectionStart || index >= sectionEnd)) {
+    errors.push(`Initiative Expected end date: field must be inside the "## Proposed Solution" section: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
+  }
+
   const value = lines[expectedEndDateLines[0]].slice('Expected end date:'.length).trim().replace(/\.$/, '');
   if (!isIsoDate(value)) {
     errors.push(`Initiative Expected end date: must be a valid ISO date in YYYY-MM-DD format: ${toDisplayPath(filePath)} [_core-adr-policy-007]`);
@@ -2123,7 +2130,7 @@ function lintSourceSnapshotTracking(sourcesDir, errors) {
     }
     const trackingFilePath = path.join(sourcesDir, entry.name, SOURCE_TRACKING_FILE_NAME);
     if (!existsFile(trackingFilePath)) {
-      errors.push(`Compiled source snapshot folder must contain a "${SOURCE_TRACKING_FILE_NAME}" tracking file: ${toDisplayPath(trackingFilePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      errors.push(`Compiled source snapshot folder must contain a "${SOURCE_TRACKING_FILE_NAME}" tracking file: ${toDisplayPath(trackingFilePath)} [_core-adr-policy-019.12-source-storage-and-tracking]`);
       continue;
     }
     validateSourceTrackingFile(trackingFilePath, errors);
@@ -2135,19 +2142,19 @@ function validateSourceTrackingFile(filePath, errors) {
   const lines = content.split(/\r?\n/);
 
   if (firstNonEmptyLine(content) !== '# Source') {
-    errors.push(`Source tracking file must start with a "# Source" heading: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+    errors.push(`Source tracking file must start with a "# Source" heading: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-and-tracking]`);
   }
 
   const timestampRe = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
   for (const field of ['last-fetch-timestamp', 'last-compilation-timestamp']) {
     const fieldLine = lines.find((line) => line.trim().startsWith(`${field}:`));
     if (!fieldLine) {
-      errors.push(`Source tracking file must include a "${field}:" line: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      errors.push(`Source tracking file must include a "${field}:" line: ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-and-tracking]`);
       continue;
     }
     const value = fieldLine.trim().slice(`${field}:`.length).trim();
     if (!timestampRe.test(value)) {
-      errors.push(`Source tracking file "${field}" must match "YYYY-MM-DD HH:MM:SS": ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-tracking]`);
+      errors.push(`Source tracking file "${field}" must match "YYYY-MM-DD HH:MM:SS": ${toDisplayPath(filePath)} [_core-adr-policy-019.12-source-storage-and-tracking]`);
     }
   }
 }
@@ -2230,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);
 
@@ -2259,12 +2268,13 @@ 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]`);
       }
 
       if (isSourceSnapshotPath(link.resolvedPath)) {
-        errors.push(`Document must not link directly to compiled-source snapshot content, which is not authoritative (see _core-adr-policy-019 rule 14) in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget} [_core-adr-policy-019.14-source-not-authoritative]`);
+        errors.push(`Document must not link directly to compiled-source snapshot content, which is not authoritative (see _core-adr-policy-019 rule 14) in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget} [_core-adr-policy-019.14-source-documents-not-authoritative]`);
       }
     }
   }
@@ -2724,20 +2734,20 @@ function lintStructuredRuleBlocks(content, filePath, errors) {
     const { lineIndex, number, title } = ruleEntries[r];
 
     if (!/^\d{2}$/.test(number)) {
-      errors.push(`Policy structured rule number must be exactly two digits ("${number}" in "${lines[lineIndex].trim()}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.02-rule-numbering-must-be-stable]`);
+      errors.push(`Policy structured rule number must be exactly two digits ("${number}" in "${lines[lineIndex].trim()}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.08-rule-block-must-use-standard-syntax]`);
     }
 
     if (title.length === 0 || !/^[a-z][a-z0-9-]*$/.test(title)) {
       if (/[A-Z]/.test(title)) {
         errors.push(`Policy structured rule title must be all lowercase ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.05-rule-title-must-be-all-lowercase]`);
       } else {
-        errors.push(`Policy structured rule title must be in kebab-case ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]`);
+        errors.push(`Policy structured rule title must be in kebab-case ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.08-rule-block-must-use-standard-syntax]`);
       }
     }
 
     const wordCount = title.split('-').filter(Boolean).length;
     if (wordCount > 12) {
-      errors.push(`Policy structured rule title must be 12 words or fewer ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]`);
+      errors.push(`Policy structured rule title must be 12 words or fewer ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.08-rule-block-must-use-standard-syntax]`);
     }
 
     if (ruleNumbers.has(number)) {

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(),
@@ -3860,7 +3910,7 @@ test('does not report orphan asset errors for files under .assets/sources in a c
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).not.toContain('raw-standard.md');
-  expect(result.errors.join('\n')).not.toContain('019.12-source-storage-tracking');
+  expect(result.errors.join('\n')).not.toContain('019.12-source-storage-and-tracking');
   expect(result.errors.join('\n')).toContain('Orphan asset file');
   expect(result.errors.join('\n')).toContain('unused.png');
 });
@@ -3879,7 +3929,7 @@ test('reports missing source.md tracking file in a compiled source snapshot fold
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).toContain('must contain a "source.md" tracking file');
-  expect(result.errors.join('\n')).toContain('019.12-source-storage-tracking');
+  expect(result.errors.join('\n')).toContain('019.12-source-storage-and-tracking');
 });
 
 test('reports malformed source.md tracking file content', () => {
@@ -3901,7 +3951,7 @@ test('reports malformed source.md tracking file content', () => {
   expect(result.errors.join('\n')).toContain('must start with a "# Source" heading');
   expect(result.errors.join('\n')).toContain('must include a "last-compilation-timestamp:" line');
   expect(result.errors.join('\n')).toContain('must match "YYYY-MM-DD HH:MM:SS"');
-  expect(result.errors.join('\n')).toContain('019.12-source-storage-tracking');
+  expect(result.errors.join('\n')).toContain('019.12-source-storage-and-tracking');
 });
 
 test('reports document linking directly into a compiled-source snapshot path', () => {
@@ -3917,7 +3967,7 @@ test('reports document linking directly into a compiled-source snapshot path', (
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).toContain('must not link directly to compiled-source snapshot content');
-  expect(result.errors.join('\n')).toContain('019.14-source-not-authoritative');
+  expect(result.errors.join('\n')).toContain('019.14-source-documents-not-authoritative');
 });
 
 test('enforces compiled scope checks when scope-type is comma-separated with compiled', () => {
@@ -4603,6 +4653,37 @@ test('reports invalid Expected end date format in initiative document', () => {
   expect(result.errors.join('\n')).toContain('Initiative Expected end date: must be a valid ISO date');
 });
 
+test('reports Expected end date outside Proposed Solution in initiative document', () => {
+  const workspaceRoot = createWorkspace('initiative-misplaced-end-date', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-myinitiative](principles/initiatives/001-myinitiative.md) - My initiative'
+    ]),
+    '.xdrs/_local/adrs/principles/initiatives/001-myinitiative.md': [
+      '# _local-adr-initiative-001: My initiative',
+      '',
+      '## Executive Summary',
+      '',
+      'Summary.',
+      '',
+      'Expected end date: 2026-12-31',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Body.',
+      '',
+      '## Proposed Solution',
+      '',
+      'We will fix it.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Expected end date: field must be inside the "## Proposed Solution" section');
+});
+
 // ─── Name / description length ────────────────────────────────────────────────
 
 test('reports XDRS element frontmatter name exceeding 64 characters', () => {
@@ -5175,7 +5256,7 @@ test('reports structured rule block with non-two-digit number', () => {
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).toContain('structured rule number must be exactly two digits');
-  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.02-rule-numbering-must-be-stable]');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.08-rule-block-must-use-standard-syntax]');
 });
 
 test('reports structured rule block with non-kebab-case title', () => {
@@ -5196,7 +5277,7 @@ test('reports structured rule block with non-kebab-case title', () => {
   const result = lintWorkspace(workspaceRoot);
 
   expect(result.errors.join('\n')).toContain('structured rule title must be in kebab-case');
-  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.08-rule-block-must-use-standard-syntax]');
 });
 
 test('reports structured rule block with duplicate rule number', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.52.0",
+  "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",