xdrs-core 0.32.0 → 0.33.0

package/.xdrs/_core/adrs/principles/001-xdrs-core.md

@@ -80,7 +80,8 @@ Policies can be of different kinds, depending on the nature of the decision:
     - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
     - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
-    - `follows` (optional): List of core scope names whose Policies apply as mandatory conventions to all documents in this scope, in addition to `_core` which always applies. Last-listed scope takes precedence when the same topic is covered by multiple scopes (e.g., `follows: [myarea-core, shared-standards]`).
+    - `follows` (optional): Core scope names whose Policies apply as mandatory conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: [myarea-core, shared-standards]`).
+    - `related-scopes` (optional): Scope names of parent, sibling, or child scopes. Use when structural links help verify policy correctness across related scopes.
 - **Subjects:** MUST be one of the following depending on the type of the Policy. Use the subject to indicate the main concern of the decision.
   - **ADR subjects**
     - `principles`: Cross-cutting architecture and policy foundations.

package/lib/lint.js

@@ -28,7 +28,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']);
 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']);
+const SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS = new Set(['scope-type', 'name', 'description', 'apply-to', 'valid-from', 'license', 'metadata', 'follows', 'related-scopes']);
 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;
@@ -305,6 +305,55 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot)
       }
     }
   }
+
+  const relatedScopesLineMatch = block.match(/^related-scopes:[ \t]*(.*)/m);
+  if (relatedScopesLineMatch !== null) {
+    const relatedScopesValue = relatedScopesLineMatch[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)}`);
+      }
+    } else {
+      const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
+      const listItems = [];
+      let hasInvalidEntry = false;
+      for (const line of block.slice(relatedScopesStart).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)}`);
+            hasInvalidEntry = true;
+            break;
+          }
+          listItems.push(item);
+        } else if (line.trim() && !/^\s/.test(line)) {
+          break;
+        }
+      }
+      if (!hasInvalidEntry && listItems.length === 0) {
+        errors.push(`Scope index frontmatter related-scopes must be a scope name or list of scope names: ${toDisplayPath(scopeIndexPath)}`);
+      }
+    }
+    if (xdrsRoot) {
+      const entries = relatedScopesValue ? [relatedScopesValue] : (() => {
+        const items = [];
+        const relatedScopesStart = block.indexOf(relatedScopesLineMatch[0]) + relatedScopesLineMatch[0].length;
+        for (const line of block.slice(relatedScopesStart).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;
+      })();
+      for (const entry of entries) {
+        if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry) && !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)}`);
+        }
+      }
+    }
+  }
 }
 
 function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes) {

package/lib/lint.test.js

@@ -1047,6 +1047,83 @@ test('accepts follows scope that exists in workspace', () => {
   expect(result.errors.join('\n')).not.toContain('follows references scope');
 });
 
+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: domain\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',
+    '.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: domain\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: domain\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');
+});
+
+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: domain\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: domain\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('Scope index frontmatter related-scopes');
+});
+
+test('reports invalid related-scopes value in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('invalid-scope-related-scopes', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\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/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');
+});
+
+test('reports related-scopes scope that does not exist in workspace', () => {
+  const workspaceRoot = createWorkspace('related-scopes-missing-scope', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\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/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');
+});
+
+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: domain\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: domain\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"');
+});
+
 test('reports orphan asset files not referenced by any document', () => {
   const workspaceRoot = createWorkspace('orphan-asset', {
     '.xdrs/index.md': rootIndex(),

package/package.json

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