xdrs-core 0.49.0 → 0.50.0

package/lib/lint.test.js

@@ -53,9 +53,9 @@ test('reports broken local document links in skill files', () => {
   const workspaceRoot = createWorkspace('broken-skill-link', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check local links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -300,11 +300,11 @@ test('reports unknown frontmatter fields in SKILL.md files', () => {
   const workspaceRoot = createWorkspace('skill-unknown-frontmatter', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       'description: Test skill document',
       'unknown-field: some value',
       '---',
@@ -329,17 +329,15 @@ test('accepts all known frontmatter fields in SKILL.md files', () => {
   const workspaceRoot = createWorkspace('skill-known-frontmatter', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       'description: Test skill document',
       'license: MIT',
       'metadata:',
       '  version: "1.0"',
-      'compatibility: node >= 18',
-      'allowed-tools: read_file grep_search',
       '---',
       '',
       '## Overview',
@@ -358,6 +356,581 @@ test('accepts all known frontmatter fields in SKILL.md files', () => {
   expect(result.errors.join('\n')).not.toContain('unknown field');
 });
 
+test('reports missing ### Inputs subsection in SKILL.md ## Overview', () => {
+  const workspaceRoot = createWorkspace('skill-missing-inputs', {
+    '.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': fullSkillDocument({ omitInputs: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "## Overview" is missing required subsection "### Inputs"');
+});
+
+test('reports missing ### Outputs subsection in SKILL.md ## Overview', () => {
+  const workspaceRoot = createWorkspace('skill-missing-outputs', {
+    '.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': fullSkillDocument({ omitOutputs: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "## Overview" is missing required subsection "### Outputs"');
+});
+
+test('reports missing ### Halt Conditions subsection in SKILL.md ## Overview', () => {
+  const workspaceRoot = createWorkspace('skill-missing-halt-conditions', {
+    '.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': fullSkillDocument({ omitHaltConditions: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "## Overview" is missing required subsection "### Halt Conditions"');
+});
+
+test('reports SKILL.md ### Inputs missing #### Optional subsection', () => {
+  const workspaceRoot = createWorkspace('skill-inputs-missing-optional', {
+    '.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': fullSkillDocument({ omitInputsOptional: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "### Inputs" section is missing "#### Optional"');
+});
+
+test('reports SKILL.md ### Inputs subsections out of order', () => {
+  const workspaceRoot = createWorkspace('skill-inputs-out-of-order', {
+    '.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': fullSkillDocument({ swapInputsOrder: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "### Inputs" subsections must appear in order (#### Required, #### Optional)');
+});
+
+test('reports SKILL.md ### Outputs missing #### Changes subsection', () => {
+  const workspaceRoot = createWorkspace('skill-outputs-missing-changes', {
+    '.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': fullSkillDocument({ omitOutputsChanges: true }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "### Outputs" section is missing "#### Changes"');
+});
+
+test('passes SKILL.md with valid None bullets in Inputs, Outputs, and Halt Conditions', () => {
+  const workspaceRoot = createWorkspace('skill-valid-none-bullets', {
+    '.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': fullSkillDocument({
+      inputsRequired: '- None',
+      inputsOptional: '- None',
+      outputsContents: '- None',
+      outputsChanges: '- None',
+      haltConditions: '- None',
+    }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('must be under 10 words or a single "None"');
+});
+
+test('reports SKILL.md bullet over 10 words in #### Required', () => {
+  const workspaceRoot = createWorkspace('skill-required-bullet-too-long', {
+    '.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': fullSkillDocument({
+      inputsRequired: '- A file path that is way too long to fit under the ten word limit',
+    }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "### Inputs" -> "#### Required" bullet must be under 10 words');
+});
+
+test('passes SKILL.md when both optional sections are omitted', () => {
+  const workspaceRoot = createWorkspace('skill-optional-sections-omitted', {
+    '.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': fullSkillDocument(),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('### Runtime Requirements');
+  expect(result.errors.join('\n')).not.toContain('### User Interaction');
+});
+
+test('reports empty ### Runtime Requirements section in SKILL.md', () => {
+  const workspaceRoot = createWorkspace('skill-empty-runtime-requirements', {
+    '.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': fullSkillDocument({ runtimeRequirements: '' }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill section "### Runtime Requirements" must not be empty');
+});
+
+test('reports empty ### User Interaction section in SKILL.md', () => {
+  const workspaceRoot = createWorkspace('skill-empty-user-interaction', {
+    '.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': fullSkillDocument({ userInteraction: '' }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill section "### User Interaction" must not be empty');
+});
+
+test('passes SKILL.md with a long free-form Runtime Requirements bullet', () => {
+  const workspaceRoot = createWorkspace('skill-runtime-requirements-free-form', {
+    '.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': fullSkillDocument({
+      runtimeRequirements: '- Write access to a directory that is not gitignored and has enough free disk space.',
+    }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('### Runtime Requirements');
+});
+
+test('reports SKILL.md User Interaction bullet over 10 words', () => {
+  const workspaceRoot = createWorkspace('skill-user-interaction-bullet-too-long', {
+    '.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': fullSkillDocument({
+      userInteraction: '- A clarifying question that is much too long to fit under the ten word limit',
+    }),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "### User Interaction" bullet must be under 10 words');
+});
+
+test('reports SKILL.md top-level sections out of template order', () => {
+  const workspaceRoot = createWorkspace('skill-sections-out-of-order', {
+    '.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': [
+      '---',
+      'name: check-links',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '### Inputs',
+      '',
+      '#### Required',
+      '- None',
+      '',
+      '#### Optional',
+      '- None',
+      '',
+      '### Outputs',
+      '',
+      '#### Contents',
+      '- None',
+      '',
+      '#### Changes',
+      '- None',
+      '',
+      '### Halt Conditions',
+      '- None',
+      '',
+      '## Anti-Patterns',
+      '',
+      '- **Mistake:** First mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Second mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Third mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill sections must appear in template order');
+});
+
+test('reports SKILL.md ## Overview subsections out of template order', () => {
+  const workspaceRoot = createWorkspace('skill-overview-subsections-out-of-order', {
+    '.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': [
+      '---',
+      'name: check-links',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '### Halt Conditions',
+      '- None',
+      '',
+      '### Inputs',
+      '',
+      '#### Required',
+      '- None',
+      '',
+      '#### Optional',
+      '- None',
+      '',
+      '### Outputs',
+      '',
+      '#### Contents',
+      '- None',
+      '',
+      '#### Changes',
+      '- None',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      '',
+      '## Anti-Patterns',
+      '',
+      '- **Mistake:** First mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Second mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Third mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill "## Overview" subsections must appear in order');
+});
+
+test('reports skill Anti-Patterns section with fewer than 3 entries', () => {
+  const workspaceRoot = createWorkspace('skill-anti-patterns-too-few', {
+    '.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': [
+      '---',
+      'name: check-links',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      '',
+      '## Anti-Patterns',
+      '',
+      '- **Mistake:** First mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Second mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('"## Anti-Patterns" section must include at least 3 entries (found 2)');
+});
+
+test('passes when skill Anti-Patterns section has at least 3 entries', () => {
+  const workspaceRoot = createWorkspace('skill-anti-patterns-enough', {
+    '.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': [
+      '---',
+      'name: check-links',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      '',
+      '## Anti-Patterns',
+      '',
+      '- **Mistake:** First mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Second mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      '- **Mistake:** Third mistake. **Why it happens:** Reason. **Instead:** Fix.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('"## Anti-Patterns" section must include at least');
+});
+
+test('reports skill bundling Makefile missing required targets', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-missing-targets', {
+    '.xdrs/index.md': rootIndex(),
+    '.gitignore': 'dist\n',
+    '.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/Makefile': [
+      'build:',
+      '\techo build',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill bundling Makefile is missing required "test" target');
+  expect(result.errors.join('\n')).toContain('Skill bundling Makefile is missing required "clean" target');
+  expect(result.errors.join('\n')).not.toContain('Skill bundling Makefile is missing required "build" target');
+});
+
+test('passes when skill bundling Makefile has build, test, and clean targets', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-complete', {
+    '.xdrs/index.md': rootIndex(),
+    '.gitignore': 'dist\n',
+    '.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/Makefile': [
+      'build: clean',
+      '\techo build',
+      'test:',
+      '\techo test',
+      'clean:',
+      '\trm -rf dist',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Skill bundling Makefile is missing required');
+});
+
+test('reports skill bundling Makefile build target not depending on clean', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-build-no-clean-dep', {
+    '.xdrs/index.md': rootIndex(),
+    '.gitignore': 'dist\n',
+    '.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/Makefile': [
+      'build:',
+      '\trm -rf dist',
+      '\techo build',
+      'test:',
+      '\techo test',
+      'clean:',
+      '\trm -rf dist',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill bundling Makefile\'s "build" target must depend on "clean"');
+});
+
+test('passes when skill bundling Makefile build target depends on clean', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-build-clean-dep', {
+    '.xdrs/index.md': rootIndex(),
+    '.gitignore': 'dist\n',
+    '.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/Makefile': [
+      'build: clean',
+      '\techo build',
+      'test:',
+      '\techo test',
+      'clean:',
+      '\trm -rf dist',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('must depend on "clean"');
+});
+
+test('reports skill bundling Makefile dist output not covered by any .gitignore', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-no-gitignore', {
+    '.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/Makefile': [
+      'build: clean',
+      '\techo build',
+      'test:',
+      '\techo test',
+      'clean:',
+      '\trm -rf dist',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('is not covered by any .gitignore');
+});
+
+test('passes when skill bundling Makefile dist output is covered by a local .gitignore', () => {
+  const workspaceRoot = createWorkspace('skill-makefile-local-gitignore', {
+    '.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/Makefile': [
+      'build: clean',
+      '\techo build',
+      'test:',
+      '\techo test',
+      'clean:',
+      '\trm -rf dist',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/skills/check-links/.gitignore': 'dist/\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('is not covered by any .gitignore');
+});
+
+test('reports scripts/ file missing a shebang or header comment', () => {
+  const workspaceRoot = createWorkspace('skill-script-missing-header', {
+    '.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/scripts/run.sh': [
+      'echo "no header here"',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Script must declare its runtime/interpreter at the top');
+});
+
+test('passes when scripts/ file declares a shebang', () => {
+  const workspaceRoot = createWorkspace('skill-script-with-shebang', {
+    '.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/scripts/run.sh': [
+      '#!/bin/bash',
+      'echo "has a shebang"',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Script must declare its runtime/interpreter at the top');
+});
+
+test('accepts skill package names containing digits, including as a prefix', () => {
+  const workspaceRoot = createWorkspace('skill-name-with-digits', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [2fa-setup](principles/skills/2fa-setup/SKILL.md) - 2FA setup'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/2fa-setup/SKILL.md': [
+      '---',
+      'name: 2fa-setup',
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Invalid skill package name');
+});
+
 test('derives expected frontmatter name from the markdown heading title', () => {
   const workspaceRoot = createWorkspace('heading-name-match', {
     '.xdrs/index.md': rootIndex(),
@@ -2063,10 +2636,10 @@ test('reports unexpected directories inside a skill package', () => {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check local links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Skill body.'),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/extras/note.txt': 'unexpected',
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Skill body.'),
+    '.xdrs/_local/adrs/principles/skills/check-links/extras/note.txt': 'unexpected',
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -3181,7 +3754,7 @@ function xdrDocument(body) {
 function skillDocument(body) {
   return [
     '---',
-    'name: 001-check-links',
+    'name: check-links',
     'description: Test skill document',
     '---',
     '',
@@ -3198,6 +3771,71 @@ function skillDocument(body) {
   ].join('\n');
 }
 
+function fullSkillDocument(overrides = {}) {
+  const {
+    omitInputs = false,
+    omitInputsOptional = false,
+    swapInputsOrder = false,
+    inputsRequired = '- A file path to scan',
+    inputsOptional = '- None',
+    runtimeRequirements = null,
+    omitOutputs = false,
+    omitOutputsChanges = false,
+    outputsContents = '- A list of broken links',
+    outputsChanges = '- None',
+    omitHaltConditions = false,
+    haltConditions = '- None',
+    userInteraction = null,
+  } = overrides;
+
+  const lines = ['---', 'name: check-links', 'description: Test skill document', '---', '', '## Overview', '', 'Test skill overview.', ''];
+
+  if (!omitInputs) {
+    lines.push('### Inputs', '');
+    if (omitInputsOptional) {
+      lines.push('#### Required', inputsRequired, '');
+    } else if (swapInputsOrder) {
+      lines.push('#### Optional', inputsOptional, '', '#### Required', inputsRequired, '');
+    } else {
+      lines.push('#### Required', inputsRequired, '', '#### Optional', inputsOptional, '');
+    }
+  }
+
+  if (!omitOutputs) {
+    lines.push('### Outputs', '');
+    if (omitOutputsChanges) {
+      lines.push('#### Contents', outputsContents, '');
+    } else {
+      lines.push('#### Contents', outputsContents, '', '#### Changes', outputsChanges, '');
+    }
+  }
+
+  if (!omitHaltConditions) {
+    lines.push('### Halt Conditions', '', haltConditions, '');
+  }
+
+  if (userInteraction !== null) {
+    lines.push('### User Interaction', '', userInteraction, '');
+  }
+
+  if (runtimeRequirements !== null) {
+    lines.push('### Runtime Requirements', '', runtimeRequirements, '');
+  }
+
+  lines.push('## Instructions', '', 'Test instructions.', '');
+
+  lines.push(
+    '## Anti-Patterns',
+    '',
+    '- **Mistake:** First mistake. **Why it happens:** Reason. **Instead:** Fix.',
+    '- **Mistake:** Second mistake. **Why it happens:** Reason. **Instead:** Fix.',
+    '- **Mistake:** Third mistake. **Why it happens:** Reason. **Instead:** Fix.',
+    ''
+  );
+
+  return lines.join('\n');
+}
+
 test('accepts a custom root folder name as the XDRS root when it contains index.md', () => {
   const doc = [
     '---',
@@ -3302,9 +3940,9 @@ test('reports emoji in SKILL.md', () => {
   const workspaceRoot = createWorkspace('skill-emoji', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Step 1: do something \u2705'),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Step 1: do something \u2705'),
   });
 
   const result = lintWorkspace(workspaceRoot);
@@ -3585,13 +4223,13 @@ test('reports XDRS element frontmatter description exceeding 1024 characters', (
 });
 
 test('reports SKILL.md frontmatter name exceeding 64 characters', () => {
-  const longName = '001-check-links-' + 'a'.repeat(50);
+  const longName = 'check-links-' + 'a'.repeat(60);
   const workspaceRoot = createWorkspace('skill-name-too-long', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
       `name: ${longName}`,
       'description: Test skill document',
@@ -3617,11 +4255,11 @@ test('reports SKILL.md frontmatter description exceeding 1024 characters', () =>
   const workspaceRoot = createWorkspace('skill-description-too-long', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': [
       '---',
-      'name: 001-check-links',
+      'name: check-links',
       `description: ${'x'.repeat(1025)}`,
       '---',
       '',
@@ -3688,19 +4326,19 @@ test('reports research exceeding 5000 word limit', () => {
   expect(result.errors.join('\n')).toContain('Research exceeds maximum word count of 5000');
 });
 
-test('reports SKILL.md exceeding 6500 word limit', () => {
-  const longBody = ('word '.repeat(6501)).trimEnd();
+test('reports SKILL.md exceeding 7000 word limit', () => {
+  const longBody = ('word '.repeat(7001)).trimEnd();
   const workspaceRoot = createWorkspace('skill-too-many-words', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument(longBody),
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument(longBody),
   });
 
   const result = lintWorkspace(workspaceRoot);
 
-  expect(result.errors.join('\n')).toContain('Skill exceeds maximum word count of 6500');
+  expect(result.errors.join('\n')).toContain('Skill exceeds maximum word count of 7000');
 });
 
 // ─── Files outside .assets in skill package root ────────────────────────────
@@ -3709,11 +4347,11 @@ test('passes when extra files exist at skill package root', () => {
   const workspaceRoot = createWorkspace('extra-skill-file', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
-      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+      '- [check-links](principles/skills/check-links/SKILL.md) - Check links'
     ]),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Body.'),
-    '.xdrs/_local/adrs/principles/skills/001-check-links/extra.md': 'Allowed extra file',
-    '.xdrs/_local/adrs/principles/skills/001-check-links/schema.json': '{"type":"object"}',
+    '.xdrs/_local/adrs/principles/skills/check-links/SKILL.md': skillDocument('Body.'),
+    '.xdrs/_local/adrs/principles/skills/check-links/extra.md': 'Allowed extra file',
+    '.xdrs/_local/adrs/principles/skills/check-links/schema.json': '{"type":"object"}',
   });
 
   const result = lintWorkspace(workspaceRoot);