xdrs-core 0.43.1 → 0.45.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)) {
@@ -653,7 +716,7 @@ 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);
 }

package/lib/lint.test.js

@@ -1733,83 +1733,198 @@ test('reports scope index description exceeding 40 words', () => {
   expect(result.errors.join('\n')).toContain('Scope index frontmatter description must be 40 words or fewer');
 });
 
-test('accepts related-scopes as a list of scope names in scope index frontmatter', () => {
-  const workspaceRoot = createWorkspace('valid-scope-related-scopes-list', {
-    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[sibling-team](sibling-team/index.md)', '[parent-domain](parent-domain/index.md)']),
-    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes:\n  - sibling-team\n  - parent-domain\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+test('reports related-scopes as unknown frontmatter field in scope index (field removed)', () => {
+  const workspaceRoot = createWorkspace('scope-related-scopes-unknown-field', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: sibling-team\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
     '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
-    '.xdrs/sibling-team/index.md': '---\nscope-type: standard\nname: sibling-team\ndescription: Sibling team.\napply-to: Sibling team\nvalid-from: 2026-01-01\n---\n\n# sibling-team Scope Overview\n\n[ADRs](adrs/index.md)\n',
-    '.xdrs/sibling-team/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
-    '.xdrs/sibling-team/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
-    '.xdrs/parent-domain/index.md': '---\nscope-type: standard\nname: parent-domain\ndescription: Parent domain.\napply-to: Parent domain\nvalid-from: 2026-01-01\n---\n\n# parent-domain Scope Overview\n\n[ADRs](adrs/index.md)\n',
-    '.xdrs/parent-domain/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
-    '.xdrs/parent-domain/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
   });
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter related-scopes');
+  expect(result.errors.join('\n')).toContain('unknown field "related-scopes"');
 });
 
-test('accepts related-scopes as a single scope name string in scope index frontmatter', () => {
-  const workspaceRoot = createWorkspace('valid-scope-related-scopes-string', {
-    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[sibling-team](sibling-team/index.md)']),
-    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: sibling-team\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+test('accepts extends: single scope name in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('extends-single-scope', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[shared](shared/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: shared\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
     '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
-    '.xdrs/sibling-team/index.md': '---\nscope-type: standard\nname: sibling-team\ndescription: Sibling team.\napply-to: Sibling team\nvalid-from: 2026-01-01\n---\n\n# sibling-team Scope Overview\n\n[ADRs](adrs/index.md)\n',
-    '.xdrs/sibling-team/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
-    '.xdrs/sibling-team/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared/index.md': '---\nscope-type: standard\nname: shared\ndescription: Shared policies.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Shared decision']),
+    '.xdrs/shared/adrs/principles/001-team.md': teamXdrDocument('Shared decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.filter((e) => /\[_core-adr-policy-010\.\d+-extends-/.test(e)).join('\n')).toBe('');
+});
+
+test('accepts extends: multiple scopes comma-separated in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('extends-multiple-scopes', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[shared-a](shared-a/index.md)', '[shared-b](shared-b/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: shared-a, shared-b\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared-a/index.md': '---\nscope-type: standard\nname: shared-a\ndescription: Shared A.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-a Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-a/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Shared A decision']),
+    '.xdrs/shared-a/adrs/principles/001-team.md': teamXdrDocument('Shared A decision.'),
+    '.xdrs/shared-b/index.md': '---\nscope-type: standard\nname: shared-b\ndescription: Shared B.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-b Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-b/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Shared B decision']),
+    '.xdrs/shared-b/adrs/principles/001-team.md': teamXdrDocument('Shared B decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.filter((e) => /\[_core-adr-policy-010\.\d+-extends-/.test(e)).join('\n')).toBe('');
+});
+
+test('accepts extends: YAML list format in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('extends-yaml-list', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[shared-a](shared-a/index.md)', '[shared-b](shared-b/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends:\n  - shared-a\n  - shared-b\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared-a/index.md': '---\nscope-type: standard\nname: shared-a\ndescription: Shared A.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-a Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-a/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Shared A decision']),
+    '.xdrs/shared-a/adrs/principles/001-team.md': teamXdrDocument('Shared A decision.'),
+    '.xdrs/shared-b/index.md': '---\nscope-type: standard\nname: shared-b\ndescription: Shared B.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-b Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-b/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Shared B decision']),
+    '.xdrs/shared-b/adrs/principles/001-team.md': teamXdrDocument('Shared B decision.'),
   });
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter related-scopes');
+  expect(result.errors.filter((e) => /\[_core-adr-policy-010\.\d+-extends-/.test(e)).join('\n')).toBe('');
 });
 
-test('reports invalid related-scopes value in scope index frontmatter', () => {
-  const workspaceRoot = createWorkspace('invalid-scope-related-scopes', {
+test('reports extends: referencing a missing scope', () => {
+  const workspaceRoot = createWorkspace('extends-missing-scope', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
-    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: 123\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: nonexistent-scope\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
     '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
   });
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('Scope index frontmatter related-scopes must be a scope name or list of scope names');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.32-extends-mandatory-presence]');
+  expect(result.errors.join('\n')).toContain('nonexistent-scope');
 });
 
-test('reports related-scopes scope that does not exist in workspace', () => {
-  const workspaceRoot = createWorkspace('related-scopes-missing-scope', {
+test('reports extends: self-reference in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('extends-self-reference', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
-    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: nonexistent-scope\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: myteam\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
     '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
   });
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('related-scopes references scope "nonexistent-scope" which does not exist in the workspace');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.30-extends-no-self]');
 });
 
-test('accepts related-scopes scope that exists in workspace', () => {
-  const workspaceRoot = createWorkspace('related-scopes-existing-scope', {
-    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[sibling-team](sibling-team/index.md)']),
-    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: sibling-team\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+test('reports extends: referencing reserved scope _local', () => {
+  const workspaceRoot = createWorkspace('extends-reserved-local', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: _local\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
     '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
-    '.xdrs/sibling-team/index.md': '---\nscope-type: standard\nname: sibling-team\ndescription: Sibling team.\napply-to: Sibling team\nvalid-from: 2026-01-01\n---\n\n# sibling-team Scope Overview\n\n[ADRs](adrs/index.md)\n',
-    '.xdrs/sibling-team/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
-    '.xdrs/sibling-team/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
   });
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).not.toContain('related-scopes references scope "sibling-team"');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.29-extends-reserved-scopes]');
 });
 
+test('reports extends: referencing reserved scope _core', () => {
+  const workspaceRoot = createWorkspace('extends-reserved-core', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: _core\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.29-extends-reserved-scopes]');
+});
+
+test('reports extends: cycle between two scopes', () => {
+  const workspaceRoot = createWorkspace('extends-cycle', {
+    '.xdrs/index.md': rootIndex(['[scope-a](scope-a/index.md)', '[scope-b](scope-b/index.md)']),
+    '.xdrs/scope-a/index.md': '---\nscope-type: standard\nname: scope-a\ndescription: Scope A.\napply-to: Scope A\nvalid-from: 2026-01-01\nextends: scope-b\n---\n\n# scope-a Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/scope-a/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - A decision']),
+    '.xdrs/scope-a/adrs/principles/001-team.md': teamXdrDocument('A decision.'),
+    '.xdrs/scope-b/index.md': '---\nscope-type: standard\nname: scope-b\ndescription: Scope B.\napply-to: Scope B\nvalid-from: 2026-01-01\nextends: scope-a\n---\n\n# scope-b Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/scope-b/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - B decision']),
+    '.xdrs/scope-b/adrs/principles/001-team.md': teamXdrDocument('B decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.31-extends-no-cycle]');
+});
+
+test('reports extends: and follows: referencing same scope (disjoint violation)', () => {
+  const workspaceRoot = createWorkspace('extends-follows-overlap', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: myarea-core\nextends: myarea-core\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/myarea-core/index.md': '---\nscope-type: core\nname: myarea-core\ndescription: Meta-governance for myarea.\napply-to: All myarea scopes\nvalid-from: 2026-01-01\n---\n\n# myarea-core Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myarea-core/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Core decision']),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Core decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-010.28-extends-disjoint]');
+});
+
+test('extends-only scope not in root index is exempt from missing link error', () => {
+  const workspaceRoot = createWorkspace('extends-only-scope-not-in-index', {
+    // shared-policies is NOT linked in the root index — it is only referenced via extends:
+    '.xdrs/index.md': rootIndex(['[_core](_core/index.md)', '[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: shared-policies\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared-policies/index.md': '---\nscope-type: standard\nname: shared-policies\ndescription: Shared policies.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-policies Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-policies/adrs/index.md': teamAdrIndex(['- [001-shared](principles/001-shared.md) - Shared decision']),
+    '.xdrs/shared-policies/adrs/principles/001-shared.md': teamXdrDocument('Shared decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  // shared-policies should NOT trigger "missing root index link" since it is extends-only
+  expect(result.errors.filter((e) => e.includes('Root index is missing scope index link') && e.includes('shared-policies')).length).toBe(0);
+  // No extends: validation errors should fire for the extends: field
+  expect(result.errors.filter((e) => /\[_core-adr-policy-010\.\d+-extends-/.test(e)).join('\n')).toBe('');
+});
+
+test('warns when extends-referenced scope also appears in root index', () => {
+  const workspaceRoot = createWorkspace('extends-scope-in-root-index', {
+    '.xdrs/index.md': rootIndex(['[_core](_core/index.md)', '[myteam](myteam/index.md)', '[shared-policies](shared-policies/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nextends: shared-policies\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared-policies/index.md': '---\nscope-type: standard\nname: shared-policies\ndescription: Shared policies.\napply-to: All teams\nvalid-from: 2026-01-01\n---\n\n# shared-policies Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-policies/adrs/index.md': teamAdrIndex(['- [001-shared](principles/001-shared.md) - Shared decision']),
+    '.xdrs/shared-policies/adrs/principles/001-shared.md': teamXdrDocument('Shared decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('[_core-adr-policy-010.35-extends-index]');
+  expect(result.warnings.join('\n')).toContain('[_core-adr-policy-010.35-extends-index]');
+  expect(result.warnings.join('\n')).toContain('shared-policies');
+});
+
+
+
 test('reports duplicate entries in follows list', () => {
   const workspaceRoot = createWorkspace('follows-duplicate-entries', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
@@ -1842,7 +1957,7 @@ test('reports duplicate entries in follows comma-separated list', () => {
   expect(result.errors.join('\n')).toContain('follows has duplicate entry "myarea-core"');
 });
 
-test('reports related-scopes that references the scope itself', () => {
+test('reports related-scopes that references the scope itself (field now removed, reports unknown field)', () => {
   const workspaceRoot = createWorkspace('related-scopes-self-reference', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
     '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes: myteam\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
@@ -1852,10 +1967,10 @@ test('reports related-scopes that references the scope itself', () => {
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('related-scopes must not reference the scope itself');
+  expect(result.errors.join('\n')).toContain('unknown field "related-scopes"');
 });
 
-test('reports duplicate entries in related-scopes list', () => {
+test('reports duplicate entries in related-scopes list (field now removed, reports unknown field)', () => {
   const workspaceRoot = createWorkspace('related-scopes-duplicate-entries', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[sibling-team](sibling-team/index.md)']),
     '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nrelated-scopes:\n  - sibling-team\n  - sibling-team\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
@@ -1868,10 +1983,10 @@ test('reports duplicate entries in related-scopes list', () => {
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('related-scopes has duplicate entry "sibling-team"');
+  expect(result.errors.join('\n')).toContain('unknown field "related-scopes"');
 });
 
-test('reports related-scopes entry that is already declared in follows', () => {
+test('reports related-scopes entry already in follows (field now removed, reports unknown field)', () => {
   const workspaceRoot = createWorkspace('related-scopes-follows-overlap', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
     '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: myarea-core\nrelated-scopes: myarea-core\n---\n\n# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
@@ -1884,7 +1999,7 @@ test('reports related-scopes entry that is already declared in follows', () => {
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('related-scopes must not repeat scope "myarea-core" already declared in follows');
+  expect(result.errors.join('\n')).toContain('unknown field "related-scopes"');
 });
 
 test('reports orphan asset files not referenced by any document', () => {

package/package.json

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