xdrs-core 0.49.1 → 0.51.0

package/lib/lint.js

@@ -25,10 +25,12 @@ const SKILL_DIR_RE = /^[a-z0-9-]+$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'initiatives']);
 const RESOURCE_DIR_NAME = '.assets';
-const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME]);
+const SOURCE_SNAPSHOT_DIR_NAME = 'sources';
+const SOURCE_TRACKING_FILE_NAME = 'source.md';
+const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME, 'dist']);
 
 const POLICY_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'freeze-reference']);
-const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata', 'compatibility', 'allowed-tools']);
+const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata']);
 const SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'extends']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
@@ -37,7 +39,14 @@ const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const POLICY_MAX_WORDS = 2600;
 const ARTICLE_MAX_WORDS = 8000;
 const RESEARCH_MAX_WORDS = 5000;
-const SKILL_MAX_WORDS = 6500;
+const SKILL_MAX_WORDS = 7000;
+const REFERENCE_MAX_WORDS = 4000;
+const SEMVER_RE = /^\d+\.\d+\.\d+$/;
+const SKILL_OPTIONAL_RUNTIME_SECTION = '### Runtime Requirements';
+const SKILL_OPTIONAL_USER_INTERACTION_SECTION = '### User Interaction';
+const SKILL_ANTI_PATTERNS_MIN_ENTRIES = 3;
+const SKILL_BUNDLING_MAKEFILE_TARGETS = ['build', 'test', 'clean'];
+const SCRIPT_HEADER_RE = /^(#!|#|\/\/|\/\*|<!--|--|;)/;
 
 // Subject number block ranges per _core-adr-policy-017
 const SUBJECT_NUMBER_RANGES = {
@@ -73,6 +82,7 @@ const DOC_TYPE_POLICY_REF = {
   Research: '[_core-adr-policy-006]',
   Initiative: '[_core-adr-policy-007]',
   Slide: '[_core-adr-policy-009]',
+  Reference: '[_core-adr-policy-003]',
 };
 
 function runLintCli(args) {
@@ -762,19 +772,58 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope = fa
         errors.push(`Local meta-policy companion "${path.basename(companion.filePath)}" requires a primary "NNN-core.md" in the same type folder "${typeName}": ${toDisplayPath(companion.filePath)} [_core-adr-policy-010.10b-local-primary-required]`);
       }
     }
-    // For compiled scopes: primary meta-policy must include ## Sources and ## Selectors
+    // For compiled scopes: primary meta-policy must include ## Sources, ## Selectors, and ## Sync Settings
     if (isCompiledScope && primaryInFolder) {
       let metaContent;
       try { metaContent = fs.readFileSync(primaryInFolder.filePath, 'utf8'); } catch { /* will be caught elsewhere */ }
       if (metaContent !== undefined) {
         const metaLines = metaContent.split(/\r?\n/);
         const metaIgnored = findIgnoredMarkdownLines(metaLines);
-        if (findHeadingLine(metaLines, metaIgnored, '## Sources') === -1) {
+        const metaHeadingLines = findHeadingLines(metaLines, metaIgnored);
+
+        const sourcesHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sources');
+        if (sourcesHeadingIdx === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Sources" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [sourcesStart, sourcesEnd] = sectionBodyRange(metaLines, metaHeadingLines, sourcesHeadingIdx);
+          for (let i = sourcesStart; i < sourcesEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            if (!/^-\s+\[(web|git|local)\]\s+[a-z0-9-]+:\s+.+$/.test(trimmed)) {
+              errors.push(`Compiled scope "## Sources" bullet must include a NAME slug in the format "- [web|git|local] name: value": ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
         }
+
         if (findHeadingLine(metaLines, metaIgnored, '## Selectors') === -1) {
           errors.push(`Compiled scope meta-policy must include a "## Selectors" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
         }
+
+        const syncHeadingIdx = findHeadingLine(metaLines, metaIgnored, '## Sync Settings');
+        if (syncHeadingIdx === -1) {
+          errors.push(`Compiled scope meta-policy must include a "## Sync Settings" section: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+        } else {
+          const [syncStart, syncEnd] = sectionBodyRange(metaLines, metaHeadingLines, syncHeadingIdx);
+          let hasValidResyncPeriod = false;
+          for (let i = syncStart; i < syncEnd; i += 1) {
+            if (metaIgnored[i]) continue;
+            const trimmed = metaLines[i].trim();
+            if (!trimmed.startsWith('-')) continue;
+            const periodMatch = trimmed.match(/^-\s+Source re-sync period days:\s*(\d+)\s*$/);
+            if (periodMatch) {
+              hasValidResyncPeriod = Number(periodMatch[1]) > 0;
+              continue;
+            }
+            const storageMatch = trimmed.match(/^-\s+Source storage:\s*(.+)$/);
+            if (storageMatch && storageMatch[1].trim() !== 'temporary') {
+              errors.push(`Compiled scope "## Sync Settings" "Source storage" value must be "temporary" if present: ${toDisplayPath(primaryInFolder.filePath)}:${i + 1} [_core-adr-policy-019.07-compilation-meta-policy]`);
+            }
+          }
+          if (!hasValidResyncPeriod) {
+            errors.push(`Compiled scope "## Sync Settings" section must include a "Source re-sync period days: N" bullet with a positive integer: ${toDisplayPath(primaryInFolder.filePath)} [_core-adr-policy-019.07-compilation-meta-policy]`);
+          }
+        }
       }
     }
     // Check qualifier uniqueness across all type folders
@@ -845,7 +894,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
         continue;
       }
       if (entry.name === 'skills') {
-        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, externalScopes));
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, entryPath, errors, externalScopes));
         continue;
       }
       if (entry.name === 'articles') {
@@ -876,7 +925,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
 
   const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
   const xdrsDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
-  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors);
+  lintOrphanAssets(subjectAssetsDir, xdrsDocsInSubject, xdrsRoot, errors, isCompiledScope);
 
   return artifacts;
 }
@@ -1010,9 +1059,9 @@ function lintXdrsElementFrontmatter(content, expectedName, filePath, errors, war
   }
 }
 
-function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, externalScopes = new Set()) {
+function lintSkillsDirectory(xdrsRoot, scopeName, skillsPath, errors, externalScopes = new Set()) {
   const artifacts = [];
-  const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
+  const entries = safeReadDir(skillsPath, errors, `read skills directory ${toDisplayPath(skillsPath)}`);
 
   for (const entry of entries) {
     const entryPath = path.join(skillsPath, entry.name);
@@ -1041,10 +1090,30 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     for (const packageEntry of packageEntries) {
       const packageEntryPath = path.join(entryPath, packageEntry.name);
 
+      if (packageEntry.isFile() && packageEntry.name === 'Makefile') {
+        lintSkillBundlingMakefile(packageEntryPath, entryPath, xdrsRoot, errors);
+      }
+
       if (!packageEntry.isDirectory()) {
         continue;
       }
 
+      if (packageEntry.name === 'references') {
+        const referenceEntries = safeReadDir(packageEntryPath, errors, `read references directory ${toDisplayPath(packageEntryPath)}`);
+        for (const referenceEntry of referenceEntries) {
+          if (referenceEntry.isDirectory() || !referenceEntry.name.endsWith('.md')) {
+            continue;
+          }
+          const referencePath = path.join(packageEntryPath, referenceEntry.name);
+          const referenceContent = fs.readFileSync(referencePath, 'utf8');
+          lintWordCount(referenceContent, referencePath, 'Reference', REFERENCE_MAX_WORDS, errors);
+        }
+      }
+
+      if (packageEntry.name === 'scripts') {
+        lintSkillScriptHeaders(packageEntryPath, errors);
+      }
+
       if (SKILL_PACKAGE_OPTIONAL_DIRS.has(packageEntry.name)) {
         continue;
       }
@@ -1061,6 +1130,11 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
 
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
     lintRequiredSections(skillContent, skillFilePath, SKILL_REQUIRED_SECTIONS, 'Skill', errors);
+    lintSkillAntiPatternsCount(skillContent, skillFilePath, errors);
+    lintSkillNestedSubsections(skillContent, skillFilePath, errors);
+    lintSkillItemListWordCounts(skillContent, skillFilePath, errors);
+    lintSkillTopLevelSectionOrder(skillContent, skillFilePath, errors);
+    lintSkillOverviewSubsections(skillContent, skillFilePath, errors);
     const skillFm = extractFrontmatter(skillContent);
     if (!skillFm.present) {
       errors.push(`SKILL.md must start with a YAML frontmatter block: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
@@ -1085,6 +1159,7 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
           errors.push(`SKILL.md frontmatter has unknown field "${key}": ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
         }
       }
+      lintSkillMetadata(skillFm.metadata, skillFilePath, errors);
     }
 
     lintNoEmojis(skillContent, skillFilePath, 'Skill', errors);
@@ -1096,6 +1171,381 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
   return artifacts;
 }
 
+/**
+ * Validates the required `metadata` block of a SKILL.md frontmatter per _core-adr-policy-003:
+ * version, author, and updated are all required fields.
+ */
+function lintSkillMetadata(metadata, skillFilePath, errors) {
+  if (!metadata || !metadata.present) {
+    errors.push(`SKILL.md frontmatter must include a metadata block: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+    return;
+  }
+
+  const fields = metadata.fields;
+
+  if (!fields.version) {
+    errors.push(`SKILL.md frontmatter metadata must include a non-empty version field: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+  } else if (!SEMVER_RE.test(fields.version)) {
+    errors.push(`SKILL.md frontmatter metadata.version must use full semantic versioning (MAJOR.MINOR.PATCH): ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+  }
+
+  if (!fields.author) {
+    errors.push(`SKILL.md frontmatter metadata must include a non-empty author field: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+  }
+
+  if (!fields.updated) {
+    errors.push(`SKILL.md frontmatter metadata must include a non-empty updated field: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+  } else if (!isIsoDate(fields.updated)) {
+    errors.push(`SKILL.md frontmatter metadata.updated must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(skillFilePath)} [_core-adr-policy-003]`);
+  }
+}
+
+/**
+ * Returns the [start, end) body line range for a top-level "##" section given its heading
+ * line index and the file's full list of "##" heading line indices.
+ */
+function sectionBodyRange(lines, headingLines, headingIndex) {
+  const nextHeadingIndex = headingLines.find((index) => index > headingIndex);
+  return [headingIndex + 1, nextHeadingIndex === undefined ? lines.length : nextHeadingIndex];
+}
+
+/**
+ * Finds the first line within [start, end) whose trimmed text exactly matches headingText.
+ */
+function findHeadingLineInRange(lines, ignoredLines, headingText, start, end) {
+  for (let index = start; index < end; index += 1) {
+    if (ignoredLines[index]) continue;
+    if (lines[index].trim() === headingText) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Finds all "###"-prefixed heading line indices within [start, end).
+ */
+function findSubHeadingLines(lines, ignoredLines, start, end) {
+  const result = [];
+  for (let index = start; index < end; index += 1) {
+    if (ignoredLines[index]) continue;
+    if (/^###\s+/.test(lines[index].trim())) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+/**
+ * Finds all "####"-prefixed heading line indices within [start, end).
+ */
+function findSubSubHeadingLines(lines, ignoredLines, start, end) {
+  const result = [];
+  for (let index = start; index < end; index += 1) {
+    if (ignoredLines[index]) continue;
+    if (/^####\s+/.test(lines[index].trim())) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+/**
+ * Validates that "### Inputs" contains "#### Required" then "#### Optional", and that
+ * "### Outputs" contains "#### Contents" then "#### Changes", per _core-adr-policy-003. Both
+ * parents are nested inside "## Overview". Skips silently when "## Overview" or a parent
+ * subsection itself is missing (already reported elsewhere).
+ */
+function lintSkillNestedSubsections(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  const overviewIndex = findHeadingLine(lines, ignoredLines, '## Overview');
+  if (overviewIndex === -1) return;
+  const [overviewStart, overviewEnd] = sectionBodyRange(lines, headingLines, overviewIndex);
+  const subHeadingLines = findSubHeadingLines(lines, ignoredLines, overviewStart, overviewEnd);
+
+  function checkPair(parentHeadingText, firstSub, secondSub) {
+    const parentIndex = findHeadingLineInRange(lines, ignoredLines, parentHeadingText, overviewStart, overviewEnd);
+    if (parentIndex === -1) return;
+
+    const nextParent = subHeadingLines.find((index) => index > parentIndex);
+    const parentEnd = nextParent === undefined ? overviewEnd : nextParent;
+    const firstIndex = findHeadingLineInRange(lines, ignoredLines, firstSub, parentIndex + 1, parentEnd);
+    const secondIndex = findHeadingLineInRange(lines, ignoredLines, secondSub, parentIndex + 1, parentEnd);
+
+    if (firstIndex === -1) {
+      errors.push(`Skill "${parentHeadingText}" section is missing "${firstSub}": ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+    if (secondIndex === -1) {
+      errors.push(`Skill "${parentHeadingText}" section is missing "${secondSub}": ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+    if (firstIndex !== -1 && secondIndex !== -1 && secondIndex < firstIndex) {
+      errors.push(`Skill "${parentHeadingText}" subsections must appear in order (${firstSub}, ${secondSub}): ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+  }
+
+  checkPair('### Inputs', '#### Required', '#### Optional');
+  checkPair('### Outputs', '#### Contents', '#### Changes');
+}
+
+/**
+ * Validates a bullet-list section's item shape: either a single "None" bullet, or one-or-more
+ * bullets each under 10 words, per _core-adr-policy-003. No-op when the range has no bullets
+ * at all (an empty required section is reported by other checks).
+ */
+function lintBulletWordCountSection(lines, ignoredLines, start, end, label, filePath, errors) {
+  const bullets = [];
+  for (let i = start; i < end; i += 1) {
+    if (ignoredLines[i]) continue;
+    const trimmed = lines[i].trim();
+    if (!trimmed) continue;
+    const bulletMatch = trimmed.match(/^-\s+(.*)$/);
+    if (bulletMatch) {
+      bullets.push(bulletMatch[1].trim());
+    }
+  }
+
+  if (bullets.length === 0) {
+    return;
+  }
+
+  if (bullets.length === 1 && bullets[0].toLowerCase() === 'none') {
+    return;
+  }
+
+  for (const bullet of bullets) {
+    const wordCount = countWords(bullet);
+    if (wordCount >= 10) {
+      errors.push(`${label} bullet must be under 10 words or a single "None" (found ${wordCount}): ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+  }
+}
+
+/**
+ * Validates the item word-count rule (single "None" bullet, or one-or-more sub-10-word
+ * bullets) across "### Inputs" -> "#### Required"/"#### Optional", "### Outputs" ->
+ * "#### Contents"/"#### Changes", "### Halt Conditions", and "### User Interaction" (only
+ * when present, since it is optional). All 4 subsections live inside "## Overview", per
+ * _core-adr-policy-003.
+ */
+function lintSkillItemListWordCounts(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  const overviewIndex = findHeadingLine(lines, ignoredLines, '## Overview');
+  if (overviewIndex === -1) return;
+  const [overviewStart, overviewEnd] = sectionBodyRange(lines, headingLines, overviewIndex);
+  const subHeadingLines = findSubHeadingLines(lines, ignoredLines, overviewStart, overviewEnd);
+
+  function subsectionRange(headingText) {
+    const index = findHeadingLineInRange(lines, ignoredLines, headingText, overviewStart, overviewEnd);
+    if (index === -1) return null;
+    const next = subHeadingLines.find((i) => i > index);
+    return [index + 1, next === undefined ? overviewEnd : next];
+  }
+
+  function subSubsectionRange(parentHeadingText, subHeadingText) {
+    const parentRange = subsectionRange(parentHeadingText);
+    if (!parentRange) return null;
+    const [parentStart, parentEnd] = parentRange;
+    const subIndex = findHeadingLineInRange(lines, ignoredLines, subHeadingText, parentStart, parentEnd);
+    if (subIndex === -1) return null;
+    const subSubHeadingLines = findSubSubHeadingLines(lines, ignoredLines, parentStart, parentEnd);
+    const nextSub = subSubHeadingLines.find((index) => index > subIndex);
+    return [subIndex + 1, nextSub === undefined ? parentEnd : nextSub];
+  }
+
+  const subsectionTargets = [
+    { range: subSubsectionRange('### Inputs', '#### Required'), label: 'Skill "### Inputs" -> "#### Required"' },
+    { range: subSubsectionRange('### Inputs', '#### Optional'), label: 'Skill "### Inputs" -> "#### Optional"' },
+    { range: subSubsectionRange('### Outputs', '#### Contents'), label: 'Skill "### Outputs" -> "#### Contents"' },
+    { range: subSubsectionRange('### Outputs', '#### Changes'), label: 'Skill "### Outputs" -> "#### Changes"' },
+  ];
+
+  for (const target of subsectionTargets) {
+    if (!target.range) continue; // missing heading already reported elsewhere
+    lintBulletWordCountSection(lines, ignoredLines, target.range[0], target.range[1], target.label, filePath, errors);
+  }
+
+  const haltRange = subsectionRange('### Halt Conditions');
+  if (haltRange) {
+    lintBulletWordCountSection(lines, ignoredLines, haltRange[0], haltRange[1], 'Skill "### Halt Conditions"', filePath, errors);
+  }
+
+  const interactionRange = subsectionRange(SKILL_OPTIONAL_USER_INTERACTION_SECTION);
+  if (interactionRange) {
+    lintBulletWordCountSection(lines, ignoredLines, interactionRange[0], interactionRange[1], 'Skill "### User Interaction"', filePath, errors);
+  }
+}
+
+/**
+ * Validates that all recognized top-level "##" sections present in the file appear in the
+ * template order defined by _core-adr-policy-003. Missing sections are not an error here
+ * (see lintRequiredSections and lintSkillOverviewSubsections for presence checks).
+ */
+function lintSkillTopLevelSectionOrder(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  const presentKnownHeadings = headingLines
+    .map((index) => lines[index].trim())
+    .filter((headingText) => SKILL_TEMPLATE_SECTION_ORDER.includes(headingText));
+
+  for (let i = 1; i < presentKnownHeadings.length; i += 1) {
+    const prevOrder = SKILL_TEMPLATE_SECTION_ORDER.indexOf(presentKnownHeadings[i - 1]);
+    const currOrder = SKILL_TEMPLATE_SECTION_ORDER.indexOf(presentKnownHeadings[i]);
+    if (currOrder < prevOrder) {
+      errors.push(`Skill sections must appear in template order (${SKILL_TEMPLATE_SECTION_ORDER.join(', ')}): ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+      break;
+    }
+  }
+}
+
+/**
+ * Validates the "## Overview" section's nested subsections per _core-adr-policy-003:
+ * "### Inputs", "### Outputs", and "### Halt Conditions" are required; "### User
+ * Interaction" and "### Runtime Requirements" are optional but, when present, must be
+ * non-empty. All recognized subsections found must appear in template order. No-op when
+ * "## Overview" itself is missing (already reported by lintRequiredSections).
+ */
+function lintSkillOverviewSubsections(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  const overviewIndex = findHeadingLine(lines, ignoredLines, '## Overview');
+  if (overviewIndex === -1) return;
+
+  const [overviewStart, overviewEnd] = sectionBodyRange(lines, headingLines, overviewIndex);
+  const subHeadingLines = findSubHeadingLines(lines, ignoredLines, overviewStart, overviewEnd);
+  const presentSubsections = subHeadingLines
+    .map((index) => lines[index].trim())
+    .filter((headingText) => SKILL_OVERVIEW_SUBSECTION_ORDER.includes(headingText));
+
+  for (const required of SKILL_OVERVIEW_REQUIRED_SUBSECTIONS) {
+    if (!presentSubsections.includes(required)) {
+      errors.push(`Skill "## Overview" is missing required subsection "${required}": ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+  }
+
+  for (const section of [SKILL_OPTIONAL_USER_INTERACTION_SECTION, SKILL_OPTIONAL_RUNTIME_SECTION]) {
+    const headingIndex = findHeadingLineInRange(lines, ignoredLines, section, overviewStart, overviewEnd);
+    if (headingIndex === -1) continue;
+
+    const nextSub = subHeadingLines.find((index) => index > headingIndex);
+    const bodyEnd = nextSub === undefined ? overviewEnd : nextSub;
+    const hasContent = lines
+      .slice(headingIndex + 1, bodyEnd)
+      .some((line, offset) => !ignoredLines[headingIndex + 1 + offset] && line.trim().length > 0);
+    if (!hasContent) {
+      errors.push(`Skill section "${section}" must not be empty: ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+    }
+  }
+
+  for (let i = 1; i < presentSubsections.length; i += 1) {
+    const prevOrder = SKILL_OVERVIEW_SUBSECTION_ORDER.indexOf(presentSubsections[i - 1]);
+    const currOrder = SKILL_OVERVIEW_SUBSECTION_ORDER.indexOf(presentSubsections[i]);
+    if (currOrder < prevOrder) {
+      errors.push(`Skill "## Overview" subsections must appear in order (${SKILL_OVERVIEW_SUBSECTION_ORDER.join(', ')}): ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+      break;
+    }
+  }
+}
+
+/**
+ * Validates the SKILL.md "## Anti-Patterns" section has at least the minimum number of
+ * "- **Mistake:**" entries required by _core-adr-policy-003.
+ */
+function lintSkillAntiPatternsCount(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const headingIndex = findHeadingLine(lines, ignoredLines, '## Anti-Patterns');
+  if (headingIndex === -1) {
+    return; // Missing section is already reported by lintRequiredSections.
+  }
+
+  const headingLines = findHeadingLines(lines, ignoredLines);
+  const nextHeadingIndex = headingLines.find((index) => index > headingIndex);
+  const sectionEnd = nextHeadingIndex === undefined ? lines.length : nextHeadingIndex;
+
+  let mistakeCount = 0;
+  for (let i = headingIndex + 1; i < sectionEnd; i += 1) {
+    if (!ignoredLines[i] && /^-\s+\*\*Mistake:\*\*/.test(lines[i].trim())) {
+      mistakeCount += 1;
+    }
+  }
+
+  if (mistakeCount < SKILL_ANTI_PATTERNS_MIN_ENTRIES) {
+    errors.push(`Skill "## Anti-Patterns" section must include at least ${SKILL_ANTI_PATTERNS_MIN_ENTRIES} entries (found ${mistakeCount}): ${toDisplayPath(filePath)} [_core-adr-policy-003]`);
+  }
+}
+
+/**
+ * Validates that each file inside a skill's scripts/ directory declares its runtime or
+ * interpreter at the top (shebang or header comment) per _core-adr-policy-003.
+ */
+function lintSkillScriptHeaders(scriptsPath, errors) {
+  const entries = safeReadDir(scriptsPath, errors, `read scripts directory ${toDisplayPath(scriptsPath)}`);
+  for (const entry of entries) {
+    if (!entry.isFile()) {
+      continue;
+    }
+    const scriptPath = path.join(scriptsPath, entry.name);
+    const content = fs.readFileSync(scriptPath, 'utf8');
+    if (!SCRIPT_HEADER_RE.test(firstNonEmptyLine(content))) {
+      errors.push(`Script must declare its runtime/interpreter at the top (shebang or header comment): ${toDisplayPath(scriptPath)} [_core-adr-policy-003]`);
+    }
+  }
+}
+
+/**
+ * Validates an optional skill bundling Makefile per _core-adr-policy-021: it must expose
+ * build/test/clean targets, and its dist/ output must be covered by a .gitignore.
+ */
+function lintSkillBundlingMakefile(makefilePath, skillPackagePath, xdrsRoot, errors) {
+  const content = fs.readFileSync(makefilePath, 'utf8');
+  for (const target of SKILL_BUNDLING_MAKEFILE_TARGETS) {
+    const targetRe = new RegExp(`^${target}\\s*:`, 'm');
+    if (!targetRe.test(content)) {
+      errors.push(`Skill bundling Makefile is missing required "${target}" target: ${toDisplayPath(makefilePath)} [_core-adr-policy-021.09-standard-targets]`);
+    }
+  }
+
+  const buildTargetMatch = content.match(/^build\s*:(.*)$/m);
+  if (buildTargetMatch && !buildTargetMatch[1].trim().split(/\s+/).includes('clean')) {
+    errors.push(`Skill bundling Makefile's "build" target must depend on "clean" (e.g. "build: clean"): ${toDisplayPath(makefilePath)} [_core-adr-policy-021.11-build-depends-on-clean]`);
+  }
+
+  if (!isDistGitignoredForSkill(skillPackagePath, xdrsRoot)) {
+    errors.push(`Skill bundling Makefile's "dist" output is not covered by any .gitignore (cover it in the repository root .gitignore or in a local .gitignore inside the skill package): ${toDisplayPath(makefilePath)} [_core-adr-policy-021.02-dist-output-location]`);
+  }
+}
+
+function gitignoreCoversDistAnyDepth(content) {
+  return content.split(/\r?\n/).some((line) => {
+    const trimmed = line.trim().replace(/\/$/, '');
+    return trimmed === 'dist' || trimmed === '**/dist';
+  });
+}
+
+function isDistGitignoredForSkill(skillPackagePath, xdrsRoot) {
+  const localGitignorePath = path.join(skillPackagePath, '.gitignore');
+  if (existsFile(localGitignorePath) && gitignoreCoversDistAnyDepth(fs.readFileSync(localGitignorePath, 'utf8'))) {
+    return true;
+  }
+
+  const rootGitignorePath = path.join(path.dirname(xdrsRoot), '.gitignore');
+  if (existsFile(rootGitignorePath) && gitignoreCoversDistAnyDepth(fs.readFileSync(rootGitignorePath, 'utf8'))) {
+    return true;
+  }
+
+  return false;
+}
+
 function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors, externalScopes = new Set()) {
   const artifacts = [];
   const articleNumbers = new Map();
@@ -1347,7 +1797,23 @@ const XDRS_REQUIRED_SECTIONS = ['## Context and Problem Statement', '## Decision
 const ARTICLE_REQUIRED_SECTIONS = ['## Overview', '## Content', '## References'];
 const RESEARCH_REQUIRED_SECTIONS = ['## Abstract', '## Introduction', '## Methods', '## Results', '## Discussion', '## Conclusion', '## References'];
 const INITIATIVE_REQUIRED_SECTIONS = ['## Executive Summary', '## Context and Problem Statement', '## Proposed Solution'];
-const SKILL_REQUIRED_SECTIONS = ['## Overview', '## Instructions'];
+const SKILL_REQUIRED_SECTIONS = ['## Overview', '## Instructions', '## Anti-Patterns'];
+const SKILL_TEMPLATE_SECTION_ORDER = [
+  '## Overview',
+  '## Instructions',
+  '## Examples',
+  '## Edge Cases',
+  '## Anti-Patterns',
+  '## References',
+];
+const SKILL_OVERVIEW_REQUIRED_SUBSECTIONS = ['### Inputs', '### Outputs', '### Halt Conditions'];
+const SKILL_OVERVIEW_SUBSECTION_ORDER = [
+  '### Inputs',
+  '### Outputs',
+  '### Halt Conditions',
+  '### User Interaction',
+  '### Runtime Requirements',
+];
 
 function lintRequiredSections(content, filePath, requiredSections, docType, errors) {
   const lines = content.split(/\r?\n/);
@@ -1408,11 +1874,16 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors, externalScopes =
   }
 }
 
-function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
+function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors, isCompiledScope = false) {
   if (!existsDirectory(assetsDir)) {
     return;
   }
 
+  const sourcesDir = path.join(assetsDir, SOURCE_SNAPSHOT_DIR_NAME);
+  if (isCompiledScope) {
+    lintSourceSnapshotTracking(sourcesDir, errors);
+  }
+
   const assetTree = collectAssetTree(assetsDir, errors);
   if (assetTree.files.length === 0 && assetTree.directories.length === 0) {
     return;
@@ -1434,6 +1905,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     if (!referencedAssets.has(assetPath)) {
       errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)} [_core-adr-policy-001]`);
     }
@@ -1441,6 +1915,9 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
 
   // Lint slide/presentation files inside .assets
   for (const assetPath of assetTree.files) {
+    if (isCompiledScope && isPathInside(sourcesDir, assetPath)) {
+      continue;
+    }
     const fileName = path.basename(assetPath);
     if (SLIDE_FILE_RE.test(fileName)) {
       lintSlideFile(assetPath, documentPaths, xdrsRoot, errors);
@@ -1448,6 +1925,47 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
   }
 }
 
+function lintSourceSnapshotTracking(sourcesDir, errors) {
+  if (!existsDirectory(sourcesDir)) {
+    return;
+  }
+
+  const entries = safeReadDir(sourcesDir, errors, `read source snapshot directory ${toDisplayPath(sourcesDir)}`);
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    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]`);
+      continue;
+    }
+    validateSourceTrackingFile(trackingFilePath, errors);
+  }
+}
+
+function validateSourceTrackingFile(filePath, errors) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  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]`);
+  }
+
+  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]`);
+      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]`);
+    }
+  }
+}
+
 function lintSlideFile(filePath, documentPaths, xdrsRoot, errors) {
   const fileName = path.basename(filePath);
 
@@ -1558,6 +2076,10 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalSc
       if (isResourceLink && !isPathInside(resourceDir, 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]`);
+      }
     }
   }
 }
@@ -1644,6 +2166,11 @@ function shouldValidateResourceLink(rawTarget) {
     || IMAGE_EXTENSIONS.has(extension);
 }
 
+function isSourceSnapshotPath(resolvedPath) {
+  const normalized = normalizePath(resolvedPath).split(path.sep).join('/');
+  return normalized.includes(`/${RESOURCE_DIR_NAME}/${SOURCE_SNAPSHOT_DIR_NAME}/`);
+}
+
 function extractDescriptionText(block) {
   const lines = block.split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
@@ -1670,7 +2197,7 @@ function extractDescriptionText(block) {
 function extractFrontmatter(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
   if (!match) {
-    return { present: false, name: null, description: false, descriptionText: null, validFrom: undefined, appliedTo: undefined, topLevelKeys: [] };
+    return { present: false, name: null, description: false, descriptionText: null, validFrom: undefined, appliedTo: undefined, topLevelKeys: [], metadata: { present: false, fields: {} } };
   }
   const block = match[1];
   const nameMatch = block.match(/^name:\s*(.+)$/m);
@@ -1683,6 +2210,7 @@ function extractFrontmatter(content) {
   }
   const freezeReferenceMatch = block.match(/^freeze-reference:\s*(.+)$/m);
   const descriptionText = extractDescriptionText(block);
+  const metadata = extractMetadataBlock(block);
   return {
     present: true,
     name: nameMatch ? nameMatch[1].trim() || null : null,
@@ -1691,10 +2219,69 @@ function extractFrontmatter(content) {
     validFrom: validFromMatch ? validFromMatch[1].trim() : undefined,
     appliedTo: appliedToMatch ? appliedToMatch[1].trim() : undefined,
     freezeReference: freezeReferenceMatch ? freezeReferenceMatch[1].trim() === 'true' : false,
+    metadata,
     topLevelKeys,
   };
 }
 
+/**
+ * Parses the nested `metadata:` block within a frontmatter YAML block, if present.
+ * Supports scalar values, quoted strings, inline arrays (`tags: [a, b]`), and
+ * block-style lists (`tags:` followed by `  - a` / `  - b` lines).
+ */
+function extractMetadataBlock(block) {
+  const lines = block.split('\n');
+  const metadataIndex = lines.findIndex((line) => /^metadata:\s*$/.test(line));
+  if (metadataIndex === -1) {
+    return { present: false, fields: {} };
+  }
+
+  const fields = {};
+  let i = metadataIndex + 1;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.trim() === '') { i++; continue; }
+    if (!/^\s+\S/.test(line)) break; // back to a top-level (unindented) key: stop
+
+    const kvMatch = line.match(/^\s+([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (!kvMatch) { i++; continue; }
+
+    const key = kvMatch[1];
+    let rawValue = kvMatch[2].trim();
+
+    if (rawValue === '') {
+      // Possible block-style list on the following, more-indented lines.
+      const listValues = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const listMatch = lines[j].match(/^\s+-\s*(.+)$/);
+        if (!listMatch) break;
+        listValues.push(listMatch[1].trim().replace(/^["']|["']$/g, ''));
+        j++;
+      }
+      if (listValues.length > 0) {
+        fields[key] = listValues;
+        i = j;
+        continue;
+      }
+      fields[key] = '';
+      i++;
+      continue;
+    }
+
+    rawValue = rawValue.replace(/^["']|["']$/g, '');
+    if (/^\[.*\]$/.test(rawValue)) {
+      const inner = rawValue.slice(1, -1).trim();
+      fields[key] = inner === '' ? [] : inner.split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    } else {
+      fields[key] = rawValue;
+    }
+    i++;
+  }
+
+  return { present: true, fields };
+}
+
 function stripFrontmatter(content) {
   const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
   return match ? content.slice(match[0].length) : content;