xdrs-core 0.31.2 → 0.32.0

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

@@ -65,6 +65,22 @@ Policies can be of different kinds, depending on the nature of the decision:
   - **Types:** `adrs`, `bdrs`, `edrs`
   - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
   - The `-core` suffix is a reserved special suffix (e.g., `security-core`, `platform-core`) that designates a scope as the meta governance layer for all scopes sharing the same prefix. See `_core-adr-policy-010` for the full convention.
+  - **Scope types:** Every scope MUST declare its type via a `scope-type` field in its `index.md` YAML frontmatter. Allowed values:
+    - `core`: A meta-policy scope defining governance conventions for a group of scopes. It may set mandatory conventions (naming rules, subject taxonomy, scope ordering) enforced on related scopes. The built-in `_core` is the framework-level instance that applies globally; area-specific `core` scopes (e.g., `myarea-core`) layer governance on top. A scope with this type MUST have `core` in its name (e.g., `_core`, `myarea-core`, `security-core`). Area `core` scopes MUST NOT contradict `_core` structural rules; they may only extend them.
+    - `reference`: A blueprint, standard, or reference architecture meant to be copied or adapted — not a live service. Examples of what belongs here: industry standards (ISO, SOC2, PCI-DSS), vendor best-practice patterns, reference architectures. A scope with this type MUST have the word `reference` somewhere in its name (e.g., `domain1-reference-mobile`, `security-reference-baseline`, `aws-reference-landing-zone`).
+    - `platform`: An existing implementation, live service, or operational area that can be consumed directly without local instantiation. Defines something that exists and can be used, not merely a blueprint. A scope with this type MUST have the word `platform` somewhere in its name (e.g., `domain2-platform-aws`, `domain2-platform-callcenter`, `cloud-platform`).
+    - `domain`: The default type. Any business area, product domain, team, or general-purpose scope that does not fit one of the specific types above. No naming requirement.
+    - `_local`: Workspace-local decisions only. Never shared or distributed outside the local workspace. Reserved exclusively for the `_local` scope.
+  - Scope name suffixes are unlimited and may be used in any scope type. For `reference` and `platform` types only the presence of the keyword in the name is enforced, not its position (e.g., `domain2-reference-people-framework` and `domain2-platform-callcenter` are both valid).
+  - When writing or generating a new XDRS root `index.md`, use the following default ordering (scopes listed later override earlier ones): `core → reference → platform → domain → _local`.
+  - **Scope index frontmatter fields:** Every scope's `index.md` MUST include the following YAML frontmatter. Fields match the Policy frontmatter standard (`_core-adr-policy-002`) in purpose, adjusted for scope-level semantics:
+    - `name` (required): The scope identifier, must exactly match the scope directory name (e.g., `myteam`, `cloud-platform-aws`). Used by tools to verify scope identity.
+    - `description` (required): Short overview of what this scope covers and who the intended audience is. Used by AI agents for discovery and relevance matching. Max 40 words.
+    - `scope-type` (required): Scope classification type, see scope types above.
+    - `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]`).
 - **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/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md

@@ -30,7 +30,8 @@ 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. Filter relevance based on file types, domains, and architectural patterns in scope.
+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.
+3. Filter relevance based on file types, domains, and architectural patterns in scope.
 
 ### Phase 3: Policy Review
 

package/.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md

@@ -158,6 +158,7 @@ Check every item before finalizing:
 5. **Redundancy**: Is the Policy the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
 6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
 7. **Index entries**: Will the new Policy be added to `[scope]/[type]/index.md` and the Policy root `index.md`?
+8. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names (e.g., `follows: [myarea-core]`), 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 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, verify the document satisfies all requirements from those Policies. Scopes are applied in order; last-listed scope in `follows` takes precedence when the same topic is covered by multiple scopes.
 
 If any check fails, revise and re-run this phase before proceeding.
 

package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md

@@ -112,6 +112,7 @@ Before writing files, verify:
 3. **Length**: Under 6500 words? Trim verbose explanations.
 4. **Duplication**: Does this overlap an existing skill? If yes, revise.
 5. **References**: Are all related XDRs and skills linked, including the cases where the skill operationalizes multiple XDRs?
+6. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, 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 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, verify the skill's activation criteria, phase structure, and content satisfy any requirements from those Policies. Last-listed scope in `follows` takes precedence.
 
 If any check fails, revise before continuing.
 

package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md

@@ -109,6 +109,7 @@ Rules to apply while drafting:
 3. Add back-references in the Policies, Research documents, and Skills that the article synthesizes, under their `## References`
    section.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new article. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
+5. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, 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 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, verify the article satisfies any content or structural requirements from those Policies. Last-listed scope in `follows` takes precedence.
 
 ### Phase 7: Verify with Lint
 

package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md

@@ -237,6 +237,7 @@ Before writing files, verify:
 5. **Standalone focus**: Does the text read as a technical paper rather than commentary about future ADRs, repository process, or artifact management?
 6. **Ratio fit**: Does the document stay within section word limits and pass the Python ratio check, or does the introduction explicitly justify the deviation?
 7. **References**: Are all related Policies, research docs, skills, articles, and external sources linked when relevant?
+8. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, 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 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, verify the research satisfies any structural or content requirements from those Policies. Last-listed scope in `follows` takes precedence.
 
 If any check fails, revise before continuing.
 

package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md

@@ -125,6 +125,7 @@ Rules to apply while drafting:
 2. Add a link to the plan in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
 3. Add back-references in the Policies, Research documents, and Skills that the plan relates to, under their `## References` section.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new plan. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
+5. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, 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 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, verify the plan satisfies any structural or content requirements from those Policies. Last-listed scope in `follows` takes precedence.
 
 ### Phase 7: Verify with Lint
 

package/.xdrs/_core/index.md

@@ -1,3 +1,11 @@
+---
+scope-type: core
+name: _core
+description: Defines the XDRS framework structure, types, document standards, and conventions. Use when working with any XDRS scope or building AI-agent-compatible documentation.
+apply-to: All XDRS scopes and document types
+valid-from: 2025-01-01
+---
+
 # _core Scope Overview
 
 ## Overview
@@ -39,6 +47,10 @@ Slide presentations that support XDRS documents follow [_core-adr-policy-009](ad
 
 [_core-adr-policy-010](adrs/principles/010-core-scope-naming.md) defines the `-core` suffix naming convention for XDRS scopes. A scope named `[domain]-core` (e.g., `security-core`) holds meta governance content — writing standards, templates, ownership, and process guidance — for all scopes sharing the same prefix. It must not contain consumable policies, and all contributors to same-prefix scopes must follow its standards.
 
+### Scope types
+
+Every XDRS scope declares a `scope-type` in its `index.md` YAML frontmatter. [_core-adr-policy-001](adrs/principles/001-xdrs-core.md) defines five allowed types: `core` (reserved for this scope), `reference` (blueprints and standards to be copied or adapted), `platform` (live services or areas usable directly), `domain` (the default for business areas, products, or teams), and `_local` (reserved for workspace-local decisions). The recommended root index ordering is `core → reference → platform → domain → _local`.
+
 ### Available skills
 
 The `_core` scope ships with seven skills that automate the most common framework operations:

package/.xdrs/index.md

@@ -6,6 +6,8 @@ This index points to all type- and scope-specific XDRS indexes. It covers Archit
 
 XDRS scopes listed last override the ones listed first
 
+Default ordering by scope type: `core → reference → platform → domain → _local`
+
 ### _core
 
 Defines how XDRS framework work

package/lib/lint.js

@@ -18,6 +18,7 @@ const ALLOWED_SUBJECTS = {
 
 const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
 const RESERVED_SCOPES = new Set(['_core', '_local']);
+const SCOPE_TYPE_NAMES = new Set(['core', 'reference', 'platform', 'domain', '_local']);
 const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRS scopes listed last override the ones listed first';
@@ -27,6 +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 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;
@@ -181,6 +183,130 @@ function lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope,
   }
 }
 
+function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot) {
+  const content = fs.readFileSync(scopeIndexPath, 'utf8');
+  const fmMatch = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!fmMatch) {
+    errors.push(`Scope index must start with a YAML frontmatter block: ${toDisplayPath(scopeIndexPath)}`);
+    return;
+  }
+  const block = fmMatch[1];
+  const fm = extractFrontmatter(content);
+
+  for (const key of fm.topLevelKeys) {
+    if (!SCOPE_INDEX_ALLOWED_FRONTMATTER_KEYS.has(key)) {
+      errors.push(`Scope index frontmatter has unknown field "${key}": ${toDisplayPath(scopeIndexPath)}`);
+    }
+  }
+
+  const scopeTypeMatch = block.match(/^scope-type:\s*(.+)$/m);
+  const scopeType = scopeTypeMatch ? scopeTypeMatch[1].trim() : null;
+  if (!scopeType) {
+    errors.push(`Scope index frontmatter must include a scope-type field: ${toDisplayPath(scopeIndexPath)}`);
+    return;
+  }
+  if (!SCOPE_TYPE_NAMES.has(scopeType)) {
+    errors.push(`Scope index scope-type must be one of [${[...SCOPE_TYPE_NAMES].join(', ')}]: ${toDisplayPath(scopeIndexPath)}`);
+    return;
+  }
+  if (scopeName === '_core' && scopeType !== 'core') {
+    errors.push(`Scope "_core" must have scope-type "core": ${toDisplayPath(scopeIndexPath)}`);
+  }
+  if (scopeName === '_local' && scopeType !== '_local') {
+    errors.push(`Scope "_local" must have scope-type "_local": ${toDisplayPath(scopeIndexPath)}`);
+  }
+  if (scopeType === 'core' && !scopeName.includes('core')) {
+    errors.push(`Scope with type "core" must have "core" in its name: ${toDisplayPath(scopeIndexPath)}`);
+  }
+  if (scopeType === '_local' && scopeName !== '_local') {
+    errors.push(`Scope type "_local" is reserved for the "_local" scope: ${toDisplayPath(scopeIndexPath)}`);
+  }
+  if (scopeType === 'reference' && !scopeName.includes('reference')) {
+    errors.push(`Scope with type "reference" must have "reference" in its name: ${toDisplayPath(scopeIndexPath)}`);
+  }
+  if (scopeType === 'platform' && !scopeName.includes('platform')) {
+    errors.push(`Scope with type "platform" must have "platform" in its name: ${toDisplayPath(scopeIndexPath)}`);
+  }
+
+  if (!fm.name) {
+    errors.push(`Scope index frontmatter must include a non-empty name field: ${toDisplayPath(scopeIndexPath)}`);
+  } else if (fm.name !== scopeName) {
+    errors.push(`Scope index frontmatter name must match scope directory name "${scopeName}": ${toDisplayPath(scopeIndexPath)}`);
+  }
+
+  if (!fm.description) {
+    errors.push(`Scope index frontmatter must include a non-empty description field: ${toDisplayPath(scopeIndexPath)}`);
+  } else if (fm.descriptionText && fm.descriptionText.length > 1024) {
+    errors.push(`Scope index frontmatter description must be 1024 characters or fewer: ${toDisplayPath(scopeIndexPath)}`);
+  }
+
+  if (!fm.appliedTo) {
+    errors.push(`Scope index frontmatter must include an apply-to field: ${toDisplayPath(scopeIndexPath)}`);
+  } else {
+    const words = countWords(fm.appliedTo);
+    if (words === 0) {
+      errors.push(`Scope index frontmatter apply-to must not be empty: ${toDisplayPath(scopeIndexPath)}`);
+    } else if (words >= 40) {
+      errors.push(`Scope index frontmatter apply-to must be under 40 words: ${toDisplayPath(scopeIndexPath)}`);
+    }
+  }
+
+  if (!fm.validFrom) {
+    errors.push(`Scope index frontmatter must include a valid-from field: ${toDisplayPath(scopeIndexPath)}`);
+  } else if (!isIsoDate(fm.validFrom)) {
+    errors.push(`Scope index frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(scopeIndexPath)}`);
+  }
+
+  const followsLineMatch = block.match(/^follows:[ \t]*(.*)/m);
+  if (followsLineMatch !== null) {
+    const followsValue = followsLineMatch[1].trim();
+    const scopeNamePattern = /^[a-zA-Z_][a-zA-Z0-9_-]*$/;
+    if (followsValue) {
+      if (!scopeNamePattern.test(followsValue)) {
+        errors.push(`Scope index frontmatter follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)}`);
+      }
+    } else {
+      const followsStart = block.indexOf(followsLineMatch[0]) + followsLineMatch[0].length;
+      const listItems = [];
+      let hasInvalidEntry = false;
+      for (const line of block.slice(followsStart).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 follows 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 follows must be a core scope name or list of core scope names: ${toDisplayPath(scopeIndexPath)}`);
+      }
+    }
+    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;
+      })();
+      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 follows references scope "${entry}" which does not exist in the workspace: ${toDisplayPath(scopeIndexPath)}`);
+        }
+      }
+    }
+  }
+}
+
 function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
@@ -221,6 +347,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
     errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)}`);
   } else {
     lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors, externalScopes);
+    lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot);
   }
 }
 

package/lib/lint.test.js

@@ -391,7 +391,7 @@ test('reports non-_local XDRS element linking to _local scope document', () => {
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
     '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': teamScopeIndex(),
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -453,7 +453,7 @@ test('reports non-_local canonical index linking to _local scope document', () =
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
     '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': teamScopeIndex(),
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [_local 001](../../_local/adrs/principles/001-main.md) - Cross-scope link'
     ]),
@@ -556,7 +556,7 @@ test('reports non-_local XDRS element linking to _local scope via absolute path'
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
     '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': teamScopeIndex(),
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -573,7 +573,7 @@ test('reports non-_local XDRS element linking to _local scope via absolute path'
 test('allows index.md at scope level', () => {
   const workspaceRoot = createWorkspace('scope-index-allowed', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview of local scope.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
@@ -588,7 +588,7 @@ test('allows index.md at scope level', () => {
 test('reports scope index missing link to type index', () => {
   const workspaceRoot = createWorkspace('scope-index-missing-type-link', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\nNo type links here.\n',
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team scope for tests.\napply-to: Test team only\nvalid-from: 2026-01-01\n---\n\n# myteam Scope Overview\n\nNo type links here.\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -605,7 +605,7 @@ test('reports scope index missing link to type index', () => {
 test('passes when scope index links to all type indexes', () => {
   const workspaceRoot = createWorkspace('scope-index-links-all-types', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/index.md': teamScopeIndex(),
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -620,7 +620,7 @@ test('passes when scope index links to all type indexes', () => {
 test('reports broken link in scope index', () => {
   const workspaceRoot = createWorkspace('scope-index-broken-link', {
     '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
-    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n[Missing](missing/index.md)\n',
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\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[Missing](missing/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -648,6 +648,405 @@ test('reports missing scope index', () => {
   expect(result.errors.join('\n')).toContain('_local/index.md');
 });
 
+// ─── Scope type checks ────────────────────────────────────────────────────────
+
+test('reports missing scope-type frontmatter in scope index', () => {
+  const workspaceRoot = createWorkspace('scope-type-missing-frontmatter', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\nNo frontmatter here.\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 must start with a YAML frontmatter block');
+  expect(result.errors.join('\n')).toContain('myteam/index.md');
+});
+
+test('reports missing scope-type field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-type-missing-field', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nsome-field: value\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 must include a scope-type field');
+});
+
+test('reports invalid scope-type value in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-type-invalid-value', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: invalid-type\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-type must be one of');
+  expect(result.errors.join('\n')).toContain('myteam/index.md');
+});
+
+test('accepts all valid scope-type values', () => {
+  const workspaceRoot = createWorkspace('valid-domain-type-check', {
+    '.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'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('Scope index scope-type must be one of');
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter must include');
+  expect(result.errors.join('\n')).not.toContain('Scope index must start with');
+});
+
+test('accepts scope-type reference when scope name contains reference', () => {
+  const workspaceRoot = createWorkspace('valid-reference-type', {
+    '.xdrs/index.md': rootIndex(['[security-reference-baseline](security-reference-baseline/index.md)']),
+    '.xdrs/security-reference-baseline/index.md': '---\nscope-type: reference\nname: security-reference-baseline\ndescription: Security reference architecture baseline for all teams.\napply-to: All teams following security reference patterns\nvalid-from: 2026-01-01\n---\n\n# security-reference-baseline Scope Overview\n\nSecurity reference.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/security-reference-baseline/adrs/index.md': [
+      '# security-reference-baseline ADR Index', '', 'Security reference ADRs.', '', '## principles', '',
+      '- [001-baseline](principles/001-baseline.md) - Security baseline', ''
+    ].join('\n'),
+    '.xdrs/security-reference-baseline/adrs/principles/001-baseline.md': [
+      '---', 'name: security-reference-baseline-adr-policy-001-baseline',
+      'description: Security baseline policy', 'apply-to: All scopes', 'valid-from: 2026-01-01', '---', '',
+      '# security-reference-baseline-adr-policy-001: Security baseline', '',
+      '## Context and Problem Statement', '', 'Baseline context.', '',
+      '## Decision Outcome', '', 'Baseline outcome.', ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('Scope index scope-type must be one of');
+  expect(result.errors.join('\n')).not.toContain('Scope with type "reference"');
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter must include');
+});
+
+test('reports scope-type reference when scope name does not contain reference', () => {
+  const workspaceRoot = createWorkspace('scope-type-reference-invalid-name', {
+    '.xdrs/index.md': rootIndex(['[security-baseline](security-baseline/index.md)']),
+    '.xdrs/security-baseline/index.md': '---\nscope-type: reference\nname: security-baseline\ndescription: Security baseline policy decisions.\napply-to: All teams following security patterns\nvalid-from: 2026-01-01\n---\n\n# security-baseline Scope Overview\n\nSecurity baseline.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/security-baseline/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/security-baseline/adrs/principles/001-team.md': [
+      '---', 'name: security-baseline-adr-policy-001-team',
+      'description: Security baseline policy', 'apply-to: All scopes', 'valid-from: 2026-01-01', '---', '',
+      '# security-baseline-adr-policy-001: Team decision', '',
+      '## Context and Problem Statement', '', 'Body.', '',
+      '## Decision Outcome', '', 'Outcome.', ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope with type "reference" must have "reference" in its name');
+});
+
+test('accepts scope-type platform when scope name contains platform', () => {
+  const workspaceRoot = createWorkspace('valid-platform-type', {
+    '.xdrs/index.md': rootIndex(['[cloud-platform](cloud-platform/index.md)']),
+    '.xdrs/cloud-platform/index.md': '---\nscope-type: platform\nname: cloud-platform\ndescription: Cloud platform infrastructure decisions for all teams.\napply-to: All teams using the cloud platform\nvalid-from: 2026-01-01\n---\n\n# cloud-platform Scope Overview\n\nCloud platform.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/cloud-platform/adrs/index.md': [
+      '# cloud-platform ADR Index', '', 'Cloud platform ADRs.', '', '## principles', '',
+      '- [001-baseline](principles/001-baseline.md) - Cloud baseline', ''
+    ].join('\n'),
+    '.xdrs/cloud-platform/adrs/principles/001-baseline.md': [
+      '---', 'name: cloud-platform-adr-policy-001-baseline',
+      'description: Cloud platform baseline', 'apply-to: All scopes', 'valid-from: 2026-01-01', '---', '',
+      '# cloud-platform-adr-policy-001: Cloud baseline', '',
+      '## Context and Problem Statement', '', 'Platform context.', '',
+      '## Decision Outcome', '', 'Platform outcome.', ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('Scope index scope-type must be one of');
+  expect(result.errors.join('\n')).not.toContain('Scope with type "platform"');
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter must include');
+});
+
+test('reports scope-type platform when scope name does not contain platform', () => {
+  const workspaceRoot = createWorkspace('scope-type-platform-invalid-name', {
+    '.xdrs/index.md': rootIndex(['[cloud-infra](cloud-infra/index.md)']),
+    '.xdrs/cloud-infra/index.md': '---\nscope-type: platform\nname: cloud-infra\ndescription: Cloud infrastructure decisions.\napply-to: All teams using cloud infrastructure\nvalid-from: 2026-01-01\n---\n\n# cloud-infra Scope Overview\n\nCloud infrastructure.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/cloud-infra/adrs/index.md': [
+      '# cloud-infra ADR Index', '', 'Cloud infra ADRs.', '', '## principles', '',
+      '- [001-infra](principles/001-infra.md) - Infra', ''
+    ].join('\n'),
+    '.xdrs/cloud-infra/adrs/principles/001-infra.md': [
+      '---', 'name: cloud-infra-adr-policy-001-infra',
+      'description: Cloud infra policy', 'apply-to: All scopes', 'valid-from: 2026-01-01', '---', '',
+      '# cloud-infra-adr-policy-001: Infra', '',
+      '## Context and Problem Statement', '', 'Body.', '',
+      '## Decision Outcome', '', 'Outcome.', ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope with type "platform" must have "platform" in its name');
+});
+
+test('reports scope-type core when scope name does not contain core', () => {
+  const workspaceRoot = createWorkspace('scope-type-core-invalid-name', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: core\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.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope with type "core" must have "core" in its name');
+});
+
+test('accepts scope-type core when scope name contains core', () => {
+  const workspaceRoot = createWorkspace('valid-core-type', {
+    '.xdrs/index.md': rootIndex(['[myarea-core](myarea-core/index.md)']),
+    '.xdrs/myarea-core/index.md': '---\nscope-type: core\nname: myarea-core\ndescription: Meta-governance scope for the myarea group of scopes.\napply-to: All scopes in the myarea group\nvalid-from: 2026-01-01\n---\n\n# myarea-core Scope Overview\n\nMeta-governance.\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')).not.toContain('Scope with type "core"');
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter');
+});
+
+test('reports scope-type _local used on non-_local scope', () => {
+  const workspaceRoot = createWorkspace('scope-type-local-reserved', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: _local\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.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope type "_local" is reserved for the "_local" scope');
+});
+
+test('reports _local scope with wrong scope-type', () => {
+  const workspaceRoot = createWorkspace('scope-type-local-wrong-type', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '---\nscope-type: domain\nname: _local\ndescription: Local scope for tests.\napply-to: Test workspace only\nvalid-from: 2026-01-01\n---\n\n# _local Scope Overview\n\nLocal scope for tests.\n\n[ADRs](adrs/index.md)\n',
+    '.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')).toContain('Scope "_local" must have scope-type "_local"');
+});
+
+test('reports missing name field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-missing-name', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\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 must include a non-empty name field');
+});
+
+test('reports name mismatch in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-name-mismatch', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: wrong-name\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\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 name must match scope directory name "myteam"');
+});
+
+test('reports missing description field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-missing-description', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\napply-to: Test team\nvalid-from: 2026-01-01\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 must include a non-empty description field');
+});
+
+test('reports missing apply-to field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-missing-apply-to', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team.\nvalid-from: 2026-01-01\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 must include an apply-to field');
+});
+
+test('reports missing valid-from field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-missing-valid-from', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team.\napply-to: Test 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.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope index frontmatter must include a valid-from field');
+});
+
+test('reports invalid valid-from date in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-invalid-valid-from', {
+    '.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: not-a-date\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 valid-from must be a valid ISO date YYYY-MM-DD');
+});
+
+test('reports unknown field in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('scope-index-unknown-field', {
+    '.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\nunknown-field: value\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 has unknown field "unknown-field"');
+});
+
+test('accepts all valid scope index frontmatter fields', () => {
+  const workspaceRoot = createWorkspace('valid-all-scope-fields', {
+    '.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\nlicense: MIT\nmetadata:\n  owner: 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.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('Scope index frontmatter');
+});
+
+test('accepts follows as a list of core scope names in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('valid-scope-follows-list', {
+    '.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: domain\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows:\n  - myarea-core\n  - 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('accepts follows as a single core scope name string in scope index frontmatter', () => {
+  const workspaceRoot = createWorkspace('valid-scope-follows-string', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: 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')).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)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: 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 follows must be a core scope name or list of core scope names');
+});
+
+test('reports follows scope that does not exist in workspace', () => {
+  const workspaceRoot = createWorkspace('follows-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\nfollows: nonexistent-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 references scope "nonexistent-core" which does not exist in the workspace');
+});
+
+test('accepts follows scope that exists in workspace', () => {
+  const workspaceRoot = createWorkspace('follows-existing-scope', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)', '[myarea-core](myarea-core/index.md)']),
+    '.xdrs/myteam/index.md': '---\nscope-type: domain\nname: myteam\ndescription: Team.\napply-to: Test team\nvalid-from: 2026-01-01\nfollows: 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')).not.toContain('follows references scope');
+});
+
 test('reports orphan asset files not referenced by any document', () => {
   const workspaceRoot = createWorkspace('orphan-asset', {
     '.xdrs/index.md': rootIndex(),
@@ -707,7 +1106,7 @@ test('reports orphan asset in articles .assets directory', () => {
 test('reports unexpected directories inside a skill package', () => {
   const workspaceRoot = createWorkspace('unexpected-skill-package-directory', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
     ]),
@@ -724,7 +1123,7 @@ test('reports unexpected directories inside a skill package', () => {
 test('allows nested directories in .assets', () => {
   const workspaceRoot = createWorkspace('asset-subdir-allowed', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
@@ -753,6 +1152,44 @@ test('allows nested directories in .assets', () => {
   expect(result.errors.join('\n')).not.toContain('.assets directory must be flat');
 });
 
+function localScopeIndex() {
+  return [
+    '---',
+    'scope-type: _local',
+    'name: _local',
+    'description: Local scope for tests.',
+    'apply-to: Test workspace only',
+    'valid-from: 2026-01-01',
+    '---',
+    '',
+    '# _local Scope Overview',
+    '',
+    'Local scope for tests.',
+    '',
+    '[ADRs](adrs/index.md)',
+    ''
+  ].join('\n');
+}
+
+function teamScopeIndex() {
+  return [
+    '---',
+    'scope-type: domain',
+    'name: myteam',
+    'description: Team scope for tests.',
+    'apply-to: Test team only',
+    'valid-from: 2026-01-01',
+    '---',
+    '',
+    '# myteam Scope Overview',
+    '',
+    'Team scope for tests.',
+    '',
+    '[ADRs](adrs/index.md)',
+    ''
+  ].join('\n');
+}
+
 function teamAdrIndex(entries) {
   return [
     '# myteam ADR Index',
@@ -896,7 +1333,7 @@ test('accepts a custom root folder name as the XDRS root when it contains index.
   ].join('\n');
   const workspaceRoot = createWorkspace('custom-root-folder', {
     'my-decisions/index.md': rootIndex(),
-    'my-decisions/_local/index.md': '# _local Scope Overview\n\nOverview.\n\n[ADRs](adrs/index.md)\n',
+    'my-decisions/_local/index.md': localScopeIndex(),
     'my-decisions/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
@@ -931,7 +1368,7 @@ test('falls back to .xdrs subdirectory when given path has no index.md', () => {
   ].join('\n');
   const workspaceRoot = createWorkspace('fallback-to-xdrs', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
@@ -1266,7 +1703,7 @@ test('passes when research ## Introduction contains Question: line', () => {
 test('passes for valid slide file in .assets with marp frontmatter and backlink', () => {
   const workspaceRoot = createWorkspace('marp-valid', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\n## Content\n\nLocal scope.\n\n- [ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-main](principles/001-main.md) - Main decision'
     ]),
@@ -1409,7 +1846,7 @@ test('does not lint non-slide files in .assets as slides', () => {
 test('passes for slide file in article .assets with backlink', () => {
   const workspaceRoot = createWorkspace('marp-article-valid', {
     '.xdrs/index.md': rootIndex(),
-    '.xdrs/_local/index.md': '# _local Scope Overview\n\n## Content\n\nLocal scope.\n\n- [ADRs](adrs/index.md)\n',
+    '.xdrs/_local/index.md': localScopeIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
       '- [001-guide](principles/articles/001-guide.md) - Guide'
     ]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.31.2",
+  "version": "0.32.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",
@@ -30,7 +30,7 @@
     "jest": "^29.7.0"
   },
   "dependencies": {
-    "filedist": "^0.37.0",
+    "filedist": "^0.39.0",
     "ignore": "^7.0.5",
     "minimatch": "^10.2.5"
   },