xdrs-core 0.34.2 → 0.35.1

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

@@ -80,7 +80,7 @@ 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): 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]`).
+    - `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**

package/.xdrs/_core/adrs/principles/011-core-scope-type.md

@@ -57,7 +57,7 @@ Content that MUST NOT be placed in a `core`-type scope:
 
 #### 06-follows-required
 
-A scope that is governed by a `core` scope MUST declare this relationship explicitly using `follows: [{core-scope-name}]` in its `index.md` frontmatter.
+A scope that is governed by a `core` scope MUST declare this relationship explicitly using `follows: {core-scope-name}` in its `index.md` frontmatter.
 
 #### 07-distribution
 

package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md

@@ -30,7 +30,7 @@ Performs a structured review of code changes or files against the Policies in th
    - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
    - Check `apply-to:` second. Keep only Policies whose stated scope fits the files, systems, or workflows under review.
    - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
-2. **Meta-policy scopes:** For each scope containing files under review, read its `index.md` frontmatter and check for a `follows` field. `_core` Policies always apply to all scopes. If a scope declares `follows:` with additional core scope names (e.g., `follows: [myarea-core, shared-standards]`), verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately — do not proceed with the review — and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, load their Policies and apply them as mandatory governance. Last-listed scope in `follows` takes precedence when the same topic is addressed by multiple scopes.
+2. **Meta-policy scopes:** For each scope containing files under review, read its `index.md` frontmatter and check for a `follows` field. `_core` Policies always apply to all scopes. If a scope declares `follows:` with additional core scope names (e.g., `follows: myarea-core, shared-standards`), verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately — do not proceed with the review — and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, load their Policies and apply them as mandatory governance. Last-listed scope in `follows` takes precedence when the same topic is addressed by multiple scopes.
    - **Scope-type standards:** Read the scope's `scope-type` from its `index.md`. Search the `[type]/principles/` directories of all `core`-type scopes in the workspace for a file whose name ends with `{scope-type}-scope-type.md`. If found, apply its rules as mandatory conventions. If the scope-type policy contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat for the parent; continue until no more parents are declared. Detect and stop on cycles. See `_core-adr-policy-010` rules 15 and 17 for the full application model.
    - **Scope-local standards:** Search the scope's own `[type]/principles/` directories for a policy file whose name ends with `{scope-name}-core.md`. If found, apply its rules as mandatory conventions; scope-local standards take precedence over scope-type standards on any conflict. See `_core-adr-policy-010` rules 16 and 17.
    - **Scope-type standards:** Read the scope's `scope-type` from its `index.md`. Search the `[type]/principles/` directories of all `core`-type scopes in the workspace for a file whose name ends with `{scope-type}-scope-type.md`. If found, apply its rules as mandatory conventions. If the scope-type policy contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat for the parent; continue until no more parents are declared. Detect and stop on cycles. See `_core-adr-policy-010` rules 15 and 17 for the full application model.

package/lib/lint.js

@@ -99,23 +99,12 @@ function lintWorkspace(targetPath, options = {}) {
   const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDRS root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
 
-  // Pass 1: collect all core-type scopes by reading index.md directly (bypasses external-skip)
-  const coreScopes = [];
-  for (const scopeEntry of scopeEntries) {
-    const scopeIndexPath = path.join(xdrsRoot, scopeEntry.name, 'index.md');
-    if (!existsFile(scopeIndexPath)) continue;
-    const content = fs.readFileSync(scopeIndexPath, 'utf8');
-    const scopeTypeMatch = content.match(/^scope-type:\s*(.+)$/m);
-    if (scopeTypeMatch && scopeTypeMatch[1].trim() === 'core') {
-      coreScopes.push(path.join(xdrsRoot, scopeEntry.name));
-    }
-  }
-
-  // Pass 2: collect known scope-type names from NNN-{scope-type}-scope-type.md files in core scopes
+  // Pass 1: collect known scope-type names from NNN-{scope-type}-scope-type.md files in any scope
   const knownScopeTypes = new Map(); // scopeTypeName -> filePath
-  for (const coreScopePath of coreScopes) {
+  for (const scopeEntry of scopeEntries) {
+    const scopePath = path.join(xdrsRoot, scopeEntry.name);
     for (const typeName of Object.keys(TYPE_TO_ID)) {
-      const principlesDir = path.join(coreScopePath, typeName, 'principles');
+      const principlesDir = path.join(scopePath, typeName, 'principles');
       if (!existsDirectory(principlesDir)) continue;
       let principlesEntries;
       try { principlesEntries = fs.readdirSync(principlesDir, { withFileTypes: true }); } catch { continue; }
@@ -256,8 +245,12 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
     errors.push(`Scope index frontmatter must include a scope-type field: ${toDisplayPath(scopeIndexPath)}`);
     return;
   }
+  if (scopeType.startsWith('_') && scopeType !== '_local') {
+    errors.push(`Scope type "${scopeType}" uses a reserved "_" prefix; only "_local" is a valid underscore-prefixed scope type: ${toDisplayPath(scopeIndexPath)}`);
+    return;
+  }
   if (!knownScopeTypes.has(scopeType) && scopeType !== '_local') {
-    errors.push(`Scope index scope-type "${scopeType}" has no corresponding ${scopeType}-scope-type policy in the principles subject of any core-type scope: ${toDisplayPath(scopeIndexPath)}`);
+    errors.push(`Scope index scope-type "${scopeType}" has no corresponding ${scopeType}-scope-type policy in the principles of any scope: ${toDisplayPath(scopeIndexPath)}`);
     return;
   }
   // Validate inheritance chain: ensure all ancestors exist in knownScopeTypes
@@ -269,9 +262,12 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
       if (!policyPath) break;
       const parentType = extractParentScopeType(policyPath);
       if (!parentType) break;
-      if (visited.has(parentType)) break; // cycle detected
+      if (visited.has(parentType)) {
+        errors.push(`Scope type "${currentType}" declares parent "${parentType}" which creates a cycle in the scope-type inheritance chain: ${toDisplayPath(scopeIndexPath)}`);
+        break;
+      }
       if (!knownScopeTypes.has(parentType)) {
-        errors.push(`Scope type "${currentType}" declares parent "${parentType}" but no ${parentType}-scope-type policy exists in any core-type scope: ${toDisplayPath(scopeIndexPath)}`);
+        errors.push(`Scope type "${currentType}" declares parent "${parentType}" but no ${parentType}-scope-type policy exists in any scope: ${toDisplayPath(scopeIndexPath)}`);
         break;
       }
       visited.add(parentType);
@@ -326,12 +322,14 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
     errors.push(`Scope index frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(scopeIndexPath)}`);
   }
 
+  let followsEntries = [];
   const followsLineMatch = block.match(/^follows:[ \t]*(.*)/m);
   if (followsLineMatch !== null) {
     const followsValue = followsLineMatch[1].trim();
     const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+    const commaSeparatedPattern = /^[a-zA-Z_][a-zA-Z0-9_-]*(\s*,\s*[a-zA-Z_][a-zA-Z0-9_-]*)+$/;
     if (followsValue) {
-      if (!scopeNamePattern.test(followsValue)) {
+      if (!scopeNamePattern.test(followsValue) && !commaSeparatedPattern.test(followsValue)) {
         errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)}`);
       }
     } else {
@@ -357,18 +355,36 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
       }
     }
     if (xdrsRoot) {
-      const entries = followsValue ? [followsValue] : (() => {
-        const items = [];
-        const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
-        for (const line of block.slice(followsStart).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 entries = followsValue
+        ? (commaSeparatedPattern.test(followsValue)
+            ? followsValue.split(',').map((s) => s.trim())
+            : [followsValue])
+        : (() => {
+          const items = [];
+          const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
+          for (const line of block.slice(followsStart).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;
+        })();
+      followsEntries = entries;
+      const seenFollows = new Set();
       for (const entry of entries) {
+        if (seenFollows.has(entry)) {
+          errors.push(`Scope index frontmatter follows has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)}`);
+        }
+        seenFollows.add(entry);
         if (/^[a-zA-Z_][a-zA-Z0-9_-]*$/.test(entry)) {
+          if (entry === scopeName) {
+            errors.push(`Scope index frontmatter follows must not reference the scope itself: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
+          if (entry === '_core') {
+            errors.push(`Scope index frontmatter follows must not reference "_core" as it is always applied implicitly: ${toDisplayPath(scopeIndexPath)}`);
+            continue;
+          }
           const followedIndexPath = path.join(xdrsRoot, entry, 'index.md');
           if (!existsFile(followedIndexPath)) {
             errors.push(`Scope index frontmatter follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
@@ -425,9 +441,24 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
         }
         return items;
       })();
+      const seenRelated = new Set();
       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)}`);
+        if (seenRelated.has(entry)) {
+          errors.push(`Scope index frontmatter related-scopes has duplicate entry "${entry}": ${toDisplayPath(scopeIndexPath)}`);
+        }
+        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)}`);
+            continue;
+          }
+          if (followsEntries.includes(entry)) {
+            errors.push(`Scope index frontmatter related-scopes must not repeat scope "${entry}" already declared in follows: ${toDisplayPath(scopeIndexPath)}`);
+            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)}`);
+          }
         }
       }
     }
@@ -476,6 +507,34 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
     lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes);
     lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot, knownScopeTypes);
   }
+  lintScopeLocalStandards(xdrsRoot, scopeName, errors);
+}
+
+function lintScopeLocalStandards(xdrsRoot, scopeName, errors) {
+  const scopePath = path.join(xdrsRoot, scopeName);
+  const corePolicySuffix = `${scopeName}-core`;
+  const foundPolicies = [];
+  for (const typeName of Object.keys(TYPE_TO_ID)) {
+    const principlesDir = path.join(scopePath, typeName, 'principles');
+    if (!existsDirectory(principlesDir)) continue;
+    let principlesEntries;
+    try { principlesEntries = fs.readdirSync(principlesDir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of principlesEntries) {
+      if (!entry.isFile()) continue;
+      if (!NUMBERED_FILE_RE.test(entry.name)) continue;
+      const filePath = path.join(principlesDir, entry.name);
+      let content;
+      try { content = fs.readFileSync(filePath, 'utf8'); } catch { continue; }
+      const fm = extractFrontmatter(content);
+      if (fm.name && (fm.name === corePolicySuffix || fm.name.endsWith(`-${corePolicySuffix}`))) {
+        foundPolicies.push(filePath);
+      }
+    }
+  }
+  if (foundPolicies.length > 1) {
+    const paths = foundPolicies.map((p) => toDisplayPath(p)).join(', ');
+    errors.push(`Scope "${scopeName}" has more than one scope-local standards policy (name ending with "${corePolicySuffix}"): ${paths}`);
+  }
 }
 
 function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, externalScopes = new Set()) {

package/lib/lint.test.js

@@ -885,6 +885,34 @@ test('accepts custom scope-type when policy exists in core-type scope', () => {
   expect(result.errors.join('\n')).not.toContain('Scope index frontmatter');
 });
 
+test('accepts custom scope-type when policy exists in a non-core scope', () => {
+  // domain-scope-type.md is in a platform-type scope (not a core scope), but lint should still find it
+  const workspaceRoot = createWorkspace('custom-scope-type-in-non-core-scope', {
+    '.xdrs/index.md': rootIndex(['[nnb-mt-domain](nnb-mt-domain/index.md)', '[my-platform](my-platform/index.md)']),
+    '.xdrs/nnb-mt-domain/index.md': '---\nscope-type: domain\nname: nnb-mt-domain\ndescription: Domain scope.\napply-to: All\nvalid-from: 2026-01-01\n---\n\n# nnb-mt-domain Scope Overview\n\nDomain scope.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/nnb-mt-domain/adrs/index.md': teamAdrIndex([]),
+    // scope-type 'domain' defined in a non-core platform scope (not _core)
+    '.xdrs/my-platform/index.md': '---\nscope-type: platform\nname: my-platform\ndescription: Platform scope.\napply-to: All\nvalid-from: 2026-01-01\n---\n\n# my-platform Scope Overview\n\nPlatform scope.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/my-platform/adrs/index.md': [
+      '# my-platform ADR Index', '', 'Platform ADRs.', '', '## principles', '',
+      '- [001-domain-scope-type](principles/001-domain-scope-type.md) - domain type', ''
+    ].join('\n'),
+    '.xdrs/my-platform/adrs/principles/001-domain-scope-type.md': [
+      '---', 'name: my-platform-adr-policy-001-domain-scope-type',
+      'description: Defines the domain scope type.', 'apply-to: All', 'valid-from: 2026-01-01', '---', '',
+      '# my-platform-adr-policy-001: domain scope type', '', '## Context and Problem Statement', '',
+      'Defines the domain scope type.', '', '## Decision Outcome', '', 'Use scope-type: domain.', ''
+    ].join('\n'),
+    // _core only defines 'core' and 'platform' — no 'domain' here
+    ...coreWithScopeTypes(['platform']),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('has no corresponding');
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter');
+});
+
 test('reports custom scope-type when no policy exists', () => {
   const workspaceRoot = createWorkspace('custom-scope-type-missing-policy', {
     '.xdrs/index.md': rootIndex(['[my-scope](my-scope/index.md)']),
@@ -943,6 +971,205 @@ test('reports error when parent scope-type in chain does not exist', () => {
   expect(result.errors.join('\n')).toContain('declares parent "nonexistent-parent" but no nonexistent-parent-scope-type policy exists');
 });
 
+test('reports cycle in scope-type inheritance chain', () => {
+  const workspaceRoot = createWorkspace('scope-type-inheritance-cycle', {
+    '.xdrs/index.md': rootIndex(['[my-custom](my-custom/index.md)', '[_core](_core/index.md)']),
+    '.xdrs/my-custom/index.md': '---\nscope-type: child\nname: my-custom\ndescription: Custom scope.\napply-to: All\nvalid-from: 2026-01-01\n---\n\n# my-custom Scope Overview\n\nCustom.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/my-custom/adrs/index.md': teamAdrIndex([]),
+    '.xdrs/_core/index.md': '---\nscope-type: core\nname: _core\ndescription: Core scope.\napply-to: All\nvalid-from: 2026-01-01\n---\n\n# _core\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_core/adrs/index.md': [
+      '# _core ADR Index', '', 'Core ADRs.', '', '## principles', '',
+      '- [001-core-scope-type](principles/001-core-scope-type.md) - core type',
+      '- [002-parent-scope-type](principles/002-parent-scope-type.md) - parent type',
+      '- [003-child-scope-type](principles/003-child-scope-type.md) - child type',
+      ''
+    ].join('\n'),
+    '.xdrs/_core/adrs/principles/001-core-scope-type.md': '---\nname: _core-adr-policy-001-core-scope-type\ndescription: core stub\napply-to: All\nvalid-from: 2026-01-01\n---\n\n## Context and Problem Statement\n\nStub.\n\n## Decision Outcome\n\nStub.\n',
+    '.xdrs/_core/adrs/principles/002-parent-scope-type.md': '---\nname: _core-adr-policy-002-parent-scope-type\ndescription: parent type that cycles back to child\napply-to: All\nvalid-from: 2026-01-01\n---\n\n## Context and Problem Statement\n\nParent.\n\n## Decision Outcome\n\nParent.\n\n#### 01-parent-scope-type\n\nInstances inherit from the `child` scope type.\n',
+    '.xdrs/_core/adrs/principles/003-child-scope-type.md': '---\nname: _core-adr-policy-003-child-scope-type\ndescription: child type that points to parent\napply-to: All\nvalid-from: 2026-01-01\n---\n\n## Context and Problem Statement\n\nChild.\n\n## Decision Outcome\n\nChild.\n\n#### 01-parent-scope-type\n\nInstances inherit from the `parent` scope type.\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('creates a cycle in the scope-type inheritance chain');
+  expect(result.errors.join('\n')).toContain('my-custom/index.md');
+});
+
+test('reports scope-type with reserved underscore prefix', () => {
+  const workspaceRoot = createWorkspace('scope-type-underscore-prefix', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: _custom\nname: myteam\ndescription: Team scope for tests.\napply-to: Test team only\nvalid-from: 2026-01-01\n---\n\n# myteam Scope Overview\n\nTeam scope for tests.\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.'),
+    ...coreWithScopeTypes([]),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('uses a reserved "_" prefix');
+  expect(result.errors.join('\n')).toContain('myteam/index.md');
+});
+
+test('does not report underscore prefix error for valid _local scope type', () => {
+  const workspaceRoot = createWorkspace('scope-type-local-no-prefix-error', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': localScopeIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Test body.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('uses a reserved "_" prefix');
+});
+
+test('reports follows that references the scope itself', () => {
+  const workspaceRoot = createWorkspace('follows-self-reference', {
+    '.xdrs/index.md': rootIndex(['[myarea-core](myarea-core/index.md)']),
+    '.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\nfollows: myarea-core\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) - Team decision'
+    ]),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('follows must not reference the scope itself');
+  expect(result.errors.join('\n')).toContain('myarea-core/index.md');
+});
+
+test('reports follows that references _core', () => {
+  const workspaceRoot = createWorkspace('follows-core-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\nfollows: _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('follows must not reference "_core" as it is always applied implicitly');
+  expect(result.errors.join('\n')).toContain('myteam/index.md');
+});
+
+test('reports follows list that includes _core', () => {
+  const workspaceRoot = createWorkspace('follows-list-includes-core', {
+    '.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:\n  - myarea-core\n  - _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) - Team decision'
+    ]),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('follows must not reference "_core" as it is always applied implicitly');
+});
+
+test('reports duplicate scope-local standards policies in same scope', () => {
+  const workspaceRoot = createWorkspace('duplicate-scope-local-standards', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': teamScopeIndex(),
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision',
+      '- [002-myteam-core](principles/002-myteam-core.md) - Local standards',
+      '- [003-myteam-core-dup](principles/003-myteam-core-dup.md) - Duplicate local standards',
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/myteam/adrs/principles/002-myteam-core.md': [
+      '---',
+      'name: myteam-adr-policy-002-myteam-core',
+      'description: Local standards for myteam.',
+      'apply-to: myteam scope',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# myteam-adr-policy-002: myteam local standards',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines local authoring standards.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Standard outcome.',
+      ''
+    ].join('\n'),
+    '.xdrs/myteam/adrs/principles/003-myteam-core-dup.md': [
+      '---',
+      'name: myteam-adr-policy-003-myteam-core',
+      'description: Duplicate local standards for myteam.',
+      'apply-to: myteam scope',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# myteam-adr-policy-003: myteam local standards duplicate',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Duplicate defines local authoring standards.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Duplicate outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('has more than one scope-local standards policy');
+  expect(result.errors.join('\n')).toContain('myteam-core');
+});
+
+test('accepts single scope-local standards policy in a scope', () => {
+  const workspaceRoot = createWorkspace('single-scope-local-standards', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': teamScopeIndex(),
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision',
+      '- [002-myteam-core](principles/002-myteam-core.md) - Local standards',
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/myteam/adrs/principles/002-myteam-core.md': [
+      '---',
+      'name: myteam-adr-policy-002-myteam-core',
+      'description: Local standards for myteam.',
+      'apply-to: myteam scope',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# myteam-adr-policy-002: myteam local standards',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Defines local authoring standards.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Standard outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('has more than one scope-local standards policy');
+});
+
 test('reports missing name field in scope index frontmatter', () => {
   const workspaceRoot = createWorkspace('scope-index-missing-name', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
@@ -1082,6 +1309,25 @@ test('accepts follows as a single core scope name string in scope index frontmat
   expect(result.errors.join('\n')).not.toContain('Scope index frontmatter follows');
 });
 
+test('accepts follows as a comma-separated list of core scope names in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('valid-scope-follows-comma', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)', '[shared-standards-core](shared-standards-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, shared-standards-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) - Team decision']),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+    '.xdrs/shared-standards-core/index.md': '---\nscope-type: core\nname: shared-standards-core\ndescription: Shared standards for all areas.\napply-to: All scopes\nvalid-from: 2026-01-01\n---\n\n# shared-standards-core Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/shared-standards-core/adrs/index.md': teamAdrIndex(['- [001-team](principles/001-team.md) - Team decision']),
+    '.xdrs/shared-standards-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter follows');
+});
+
 test('reports invalid follows value in scope index frontmatter', () => {
   const workspaceRoot = createWorkspace('invalid-scope-follows', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
@@ -1243,6 +1489,83 @@ test('accepts related-scopes scope that exists in workspace', () => {
   expect(result.errors.join('\n')).not.toContain('related-scopes references scope "sibling-team"');
 });
 
+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)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: standard\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows:\n  - myarea-core\n  - 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) - Team decision']),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('follows has duplicate entry "myarea-core"');
+});
+
+test('reports duplicate entries in follows comma-separated list', () => {
+  const workspaceRoot = createWorkspace('follows-comma-duplicate-entries', {
+    '.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, 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) - Team decision']),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('follows has duplicate entry "myarea-core"');
+});
+
+test('reports related-scopes that references the scope itself', () => {
+  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',
+    '.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 must not reference the scope itself');
+});
+
+test('reports duplicate entries in related-scopes list', () => {
+  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',
+    '.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')).toContain('related-scopes has duplicate entry "sibling-team"');
+});
+
+test('reports related-scopes entry that is already declared in follows', () => {
+  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',
+    '.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) - Team decision']),
+    '.xdrs/myarea-core/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('related-scopes must not repeat scope "myarea-core" already declared in follows');
+});
+
 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.34.2",
+  "version": "0.35.1",
   "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",