xdrs-core 0.44.0 → 0.46.0

package/lib/lint.js

@@ -27,7 +27,7 @@ const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_D
 
 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 SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'related-scopes']);
+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$/;
 const SLIDE_MAX_NAME_LENGTH = 64;
@@ -220,21 +220,48 @@ function lintWorkspace(targetPath, options = {}) {
     }
   }
 
+  // Populated during lintScopeIndexFrontmatter: scopeName -> [extendedScopeNames...]
+  const extendsRelationships = new Map();
+
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, warnings, actualTypeIndexes, ignoreExternal, effectiveExternalScopes, knownScopeTypes, readOnlyScopes);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, warnings, actualTypeIndexes, ignoreExternal, effectiveExternalScopes, knownScopeTypes, readOnlyScopes, extendsRelationships);
+  }
+
+  // Detect cycles in extends: chains (DFS)
+  const visitedCycle = new Set();
+  const inStackCycle = new Set();
+  const detectExtendsCycles = (scope, stack) => {
+    if (inStackCycle.has(scope)) {
+      const cycleStart = stack.indexOf(scope);
+      const cycle = stack.slice(cycleStart).concat(scope).join(' -> ');
+      errors.push(`Circular extends chain detected: ${cycle} [_core-adr-policy-010.31-extends-no-cycle]`);
+      return;
+    }
+    if (visitedCycle.has(scope)) return;
+    visitedCycle.add(scope);
+    inStackCycle.add(scope);
+    stack.push(scope);
+    for (const target of (extendsRelationships.get(scope) || [])) {
+      detectExtendsCycles(target, stack);
+    }
+    stack.pop();
+    inStackCycle.delete(scope);
+  };
+  for (const scope of extendsRelationships.keys()) {
+    detectExtendsCycles(scope, []);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
   if (!existsFile(rootIndexPath)) {
     errors.push('Missing required root index: .xdrs/index.md [_core-adr-policy-001]');
   } else {
-    lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, effectiveExternalScopes);
+    lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warnings, effectiveExternalScopes, extendsRelationships);
   }
 
   return { xdrsRoot, errors, warnings, readOnlyScopes };
 }
 
-function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, externalScopes = new Set()) {
+function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, warnings = [], externalScopes = new Set(), extendsRelationships = new Map()) {
   const content = fs.readFileSync(rootIndexPath, 'utf8');
   const repoRoot = path.dirname(xdrsRoot);
 
@@ -263,6 +290,12 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, exter
     }
   }
 
+  // Build set of all scopes referenced via any extends: chain
+  const extendsReferencedScopes = new Set();
+  for (const entries of extendsRelationships.values()) {
+    for (const e of entries) extendsReferencedScopes.add(e);
+  }
+
   // Collect non-_local scopes that have type indexes and check their scope index is linked
   const scopesWithTypeIndexes = new Set();
   for (const indexPath of actualTypeIndexes) {
@@ -275,7 +308,16 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors, exter
   for (const scopeName of scopesWithTypeIndexes) {
     const scopeIndexPath = normalizePath(path.join(xdrsRoot, scopeName, 'index.md'));
     if (!linkedSet.has(scopeIndexPath)) {
+      // Exempt scopes that are only reachable via extends: chains
+      if (extendsReferencedScopes.has(scopeName)) {
+        // Scope is extends-only (not in root index) — exempt from mandatory link requirement
+        // No warning here: absence from root index is expected and valid for extends-only scopes
+        continue;
+      }
       errors.push(`Root index is missing scope index link: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))} [_core-adr-policy-001]`);
+    } else if (extendsReferencedScopes.has(scopeName)) {
+      // Scope is in BOTH root index and extends chain — ambiguous dual precedence
+      warnings.push(`Scope "${scopeName}" appears in both the root index and an extends: chain; precedence may be ambiguous for consumers that do not follow extends declarations: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))} [_core-adr-policy-010.35-extends-index]`);
     }
   }
 }
@@ -316,7 +358,7 @@ function extractParentScopeType(policyFilePath) {
   return bodyMatch ? bodyMatch[1] : null;
 }
 
-function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes = new Map(), readOnlyScopes = new Set()) {
+function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes = new Map(), readOnlyScopes = new Set(), extendsRelationships = new Map()) {
   const content = fs.readFileSync(scopeIndexPath, 'utf8');
   const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
   if (!fmMatch) {
@@ -528,24 +570,27 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
     }
   }
 
-  const relatedScopesLineMatch = block.match(/^related-scopes:[ \t]*(.*)/m);
-  if (relatedScopesLineMatch !== null) {
-    const relatedScopesValue = relatedScopesLineMatch[1].trim();
+  // Parse extends: field
+  let extendsEntries = [];
+  const extendsLineMatch = block.match(/^extends:[ \t]*(.*)/m);
+  if (extendsLineMatch !== null) {
+    const extendsValue = extendsLineMatch[1].trim();
     const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
-    if (relatedScopesValue) {
-      if (!scopeNamePattern.test(relatedScopesValue)) {
-        errors.push(`Scope index frontmatter related-scopes must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+    const commaSeparatedPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(?:\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
+    if (extendsValue) {
+      if (!scopeNamePattern.test(extendsValue) && !commaSeparatedPattern.test(extendsValue)) {
+        errors.push(`Scope index frontmatter extends must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
       }
     } else {
-      const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
+      const extendsStart = block.indexOf(extendsLineMatch[0]) + extendsLineMatch[0].length;
       const listItems = [];
       let hasInvalidEntry = false;
-      for (const line of block.slice(relatedScopesStart).split('\n')) {
+      for (const line of block.slice(extendsStart).split('\n')) {
         const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
         if (itemMatch) {
           const item = (itemMatch[1] || '').trim();
           if (!item || !scopeNamePattern.test(item)) {
-            errors.push(`Scope index frontmatter related-scopes entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+            errors.push(`Scope index frontmatter extends entries must be non-empty scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
             hasInvalidEntry = true;
             break;
           }
@@ -555,45 +600,63 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
         }
       }
       if (!hasInvalidEntry && listItems.length === 0) {
-        errors.push(`Scope index frontmatter related-scopes must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+        errors.push(`Scope index frontmatter extends must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
       }
     }
-    if (xdrsRoot) {
-      const entries = relatedScopesValue ? [relatedScopesValue] : (() => {
+    const rawEntries = extendsValue
+      ? (commaSeparatedPattern.test(extendsValue)
+          ? extendsValue.split(',').map((s) => s.trim())
+          : (scopeNamePattern.test(extendsValue) ? [extendsValue] : []))
+      : (() => {
         const items = [];
-        const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
-        for (const line of block.slice(relatedScopesStart).split('\n')) {
+        const extendsStart = block.indexOf(extendsLineMatch[0]) + extendsLineMatch[0].length;
+        for (const line of block.slice(extendsStart).split('\n')) {
           const itemMatch = line.match(/^\s+-\s*(\S.*)?$/);
           if (itemMatch && itemMatch[1]) items.push(itemMatch[1].trim());
           else if (line.trim() && !/^\s/.test(line)) break;
         }
         return items;
       })();
-      const seenRelated = new Set();
-      for (const entry of entries) {
-        if (seenRelated.has(entry)) {
-          errors.push(`Scope index frontmatter related-scopes has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
+    const seenExtends = new Set();
+    for (const entry of rawEntries) {
+      if (seenExtends.has(entry)) {
+        errors.push(`Scope index frontmatter extends has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.27-extends-declaration]`);
+        continue;
+      }
+      seenExtends.add(entry);
+      if (!scopeNamePattern.test(entry)) continue;
+      if (entry === scopeName) {
+        errors.push(`Scope index frontmatter extends must not reference the scope itself: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.30-extends-no-self]`);
+        continue;
+      }
+      if (entry === '_local' || entry === '_core') {
+        errors.push(`Scope index frontmatter extends must not reference reserved scope "${entry}": ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.29-extends-reserved-scopes]`);
+        continue;
+      }
+      extendsEntries.push(entry);
+    }
+    if (xdrsRoot) {
+      const seenValid = new Set();
+      for (const entry of extendsEntries) {
+        if (seenValid.has(entry)) continue;
+        seenValid.add(entry);
+        if (followsEntries.includes(entry)) {
+          errors.push(`Scope index frontmatter extends must not repeat scope "${entry}" already declared in follows: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.28-extends-disjoint]`);
+          continue;
         }
-        seenRelated.add(entry);
-        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
-          if (entry === scopeName) {
-            errors.push(`Scope index frontmatter related-scopes must not reference the scope itself: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-            continue;
-          }
-          if (followsEntries.includes(entry)) {
-            errors.push(`Scope index frontmatter related-scopes must not repeat scope "${entry}" already declared in follows: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-            continue;
-          }
-          if (!existsFile(path.join(xdrsRoot, entry, 'index.md'))) {
-            errors.push(`Scope index frontmatter related-scopes references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
-          }
+        if (!existsFile(path.join(xdrsRoot, entry, 'index.md'))) {
+          errors.push(`Scope index frontmatter extends references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-010.32-extends-mandatory-presence]`);
         }
       }
+      if (extendsEntries.length > 0) {
+        extendsRelationships.set(scopeName, extendsEntries.filter((e) => existsFile(path.join(xdrsRoot, e, 'index.md'))));
+      }
     }
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeIndexes, ignoreExternal, externalScopes, knownScopeTypes = new Map(), readOnlyScopes = new Set()) {
+
+function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeIndexes, ignoreExternal, externalScopes, knownScopeTypes = new Map(), readOnlyScopes = new Set(), extendsRelationships = new Map()) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
   if (ignoreExternal && externalScopes.has(scopeName)) {
@@ -607,6 +670,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
   // Determine if this scope is a core-type scope (but not _core which is exempt)
   // Used to enforce structured format on all policies in core-type scopes
   let isCoreTypeNonExempt = false;
+  let isCompiledScope = false;
   if (scopeName !== '_core') {
     const scopeIndexPath = path.join(scopePath, 'index.md');
     if (existsFile(scopeIndexPath)) {
@@ -615,10 +679,12 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
         const stMatch = idxContent.match(/^scope-type:\s*(.+)$/m);
         if (stMatch) {
           const stRaw = stMatch[1].trim();
+          // Handle both "[type1, type2]" YAML array format and "type1, type2" inline CSV format
           const stList = stRaw.startsWith('[') && stRaw.endsWith(']')
             ? stRaw.slice(1, -1).split(',').map((s) => s.trim())
-            : [stRaw];
+            : stRaw.split(',').map((s) => s.trim());
           isCoreTypeNonExempt = stList.includes('core');
+          isCompiledScope = stList.includes('compiled');
         }
       } catch { /* ignore read errors; will be caught later */ }
     }
@@ -633,7 +699,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
         errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)} [_core-adr-policy-001]`);
         continue;
       }
-      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, warnings, actualTypeIndexes, externalScopes, isCoreTypeNonExempt);
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, warnings, actualTypeIndexes, externalScopes, isCoreTypeNonExempt, isCompiledScope);
       const typeIndexPath = path.join(entryPath, 'index.md');
       if (existsFile(typeIndexPath)) {
         typeIndexesInScope.push(typeIndexPath);
@@ -653,12 +719,12 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, warnings, actualTypeInd
     errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)} [_core-adr-policy-001]`);
   } else {
     lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes);
-    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes, readOnlyScopes);
+    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes, readOnlyScopes, extendsRelationships);
   }
-  lintLocalMetaPolicies(xdrsRoot, scopeName, errors);
+  lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope);
 }
 
-function lintLocalMetaPolicies(xdrsRoot, scopeName, errors) {
+function lintLocalMetaPolicies(xdrsRoot, scopeName, errors, isCompiledScope = false) {
   const scopePath = path.join(xdrsRoot, scopeName);
   // Track qualifiers across all type folders: qualifier ('' for primary) -> filePath
   const seenQualifiers = new Map();
@@ -694,6 +760,21 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors) {
         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
+    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) {
+          errors.push(`Compiled scope meta-policy must include a "## Sources" section: ${toDisplayPath(primaryInFolder.filePath)} [_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]`);
+        }
+      }
+    }
     // Check qualifier uniqueness across all type folders
     const allInFolder = primaryInFolder ? [primaryInFolder, ...companionsInFolder] : companionsInFolder;
     for (const { filePath, qualifier } of allInFolder) {
@@ -710,7 +791,7 @@ function lintLocalMetaPolicies(xdrsRoot, scopeName, errors) {
   }
 }
 
-function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, warnings, actualTypeIndexes, externalScopes = new Set(), enforceStructured = false) {
+function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, warnings, actualTypeIndexes, externalScopes = new Set(), enforceStructured = false, isCompiledScope = false) {
   const typePath = path.join(xdrsRoot, scopeName, typeName);
   const indexPath = path.join(typePath, 'index.md');
   const xdrsNumbers = new Map();
@@ -741,7 +822,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, warnings, actu
       warnings.push(`Invalid subject folder for ${typeName}: ${toDisplayPath(entryPath)} [_core-adr-policy-001] [exempt: freeze-reference]`);
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrsNumbers, errors, warnings, externalScopes, enforceStructured));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrsNumbers, errors, warnings, externalScopes, enforceStructured, isCompiledScope));
   }
 
   if (existsFile(indexPath)) {
@@ -749,7 +830,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, warnings, actu
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNumbers, errors, warnings, externalScopes = new Set(), enforceStructured = false) {
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNumbers, errors, warnings, externalScopes = new Set(), enforceStructured = false, isCompiledScope = false) {
   const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
   const artifacts = [];
   const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
@@ -788,7 +869,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
     }
 
     artifacts.push(entryPath);
-    lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, entryPath, xdrsNumbers, errors, warnings, externalScopes, enforceStructured);
+    lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, entryPath, xdrsNumbers, errors, warnings, externalScopes, enforceStructured, isCompiledScope);
   }
 
   const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
@@ -798,7 +879,7 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrsNu
   return artifacts;
 }
 
-function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePath, xdrsNumbers, errors, warnings, externalScopes = new Set(), enforceStructured = false) {
+function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePath, xdrsNumbers, errors, warnings, externalScopes = new Set(), enforceStructured = false, isCompiledScope = false) {
   const baseName = path.basename(filePath);
   const match = baseName.match(NUMBERED_FILE_RE);
   if (!match) {
@@ -840,9 +921,15 @@ function lintXdrsElementFile(xdrsRoot, scopeName, typeName, subjectName, filePat
   lintXdrsElementFrontmatter(content, expectedName, filePath, errors, warnings, freezeReference);
   if (enforceStructured) {
     validateStructuredFormatContent(content, filePath, errors, '_core-adr-policy-010.08c-def-core-scope-policies-must-be-structured');
+  } else if (isCompiledScope) {
+    validateStructuredFormatContent(content, filePath, errors, '_core-adr-policy-019.04-structured-format-required');
   } else {
     lintStructuredRuleBlocks(content, filePath, errors);
   }
+  const isLocalMetaPolicy = subjectName === 'principles' && titleParts[0] === 'core';
+  if (isCompiledScope && !isLocalMetaPolicy) {
+    lintCompiledPolicySourceSection(content, filePath, errors);
+  }
   lintRequiredSections(content, filePath, XDRS_REQUIRED_SECTIONS, 'Policy', errors);
   lintNoEmojis(content, filePath, 'Policy', errors);
   lintWordCount(content, filePath, 'Policy', POLICY_MAX_WORDS, errors);
@@ -1645,6 +1732,32 @@ function validateStructuredFormatContent(content, filePath, errors, errorCode) {
   lintStructuredRuleBlocks(content, filePath, errors);
 }
 
+function lintCompiledPolicySourceSection(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const sourceStart = findHeadingLine(lines, ignoredLines, '## Source');
+  if (sourceStart === -1) {
+    errors.push(`Compiled policy must include a "## Source" section: ${toDisplayPath(filePath)} [_core-adr-policy-019.10-source-section]`);
+    return;
+  }
+  // Find end of ## Source section (next ## heading or EOF)
+  let sourceEnd = lines.length;
+  for (let i = sourceStart + 1; i < lines.length; i++) {
+    if (!ignoredLines[i] && /^## /.test(lines[i])) {
+      sourceEnd = i;
+      break;
+    }
+  }
+  // Paths in ## Source MUST NOT be written as markdown links
+  const MD_LINK_RE = /\[.+?\]\(.+?\)/;
+  for (let i = sourceStart + 1; i < sourceEnd; i++) {
+    if (!ignoredLines[i] && MD_LINK_RE.test(lines[i])) {
+      errors.push(`Compiled policy "## Source" section must not use markdown links (use plain text paths): ${toDisplayPath(filePath)}:${i + 1} [_core-adr-policy-019.10-source-section]`);
+      break;
+    }
+  }
+}
+
 function findIgnoredMarkdownLines(lines) {
   const ignored = [];
   let inCodeFence = false;