xdrs-core 0.35.0 → 0.36.0

package/.xdrs/_core/adrs/principles/012-reference-scope-type.md

@@ -39,7 +39,7 @@ Do not use `scope-type: reference` for scopes that represent a live service, an
 
 #### 03-naming-convention
 
-A scope of type `reference` MUST have the word "reference" somewhere in its name. The position of the word is not enforced. Examples: `domain1-reference-mobile`, `security-reference-baseline`, `aws-reference-landing-zone`, `sales-reference-procedures`, `finance-reference-compliance`, `marketing-reference-standards`.
+A scope of type `reference` MUST follow the naming pattern `{domain}-ref-{name}`, where `{domain}` identifies the owning domain or team and `{name}` identifies the specific reference area. Examples: `domain1-ref-mobile`, `security-ref-baseline`, `aws-ref-landing-zone`, `sales-ref-procedures`, `finance-ref-compliance`, `marketing-ref-standards`.
 
 #### 04-content-guidance
 

package/.xdrs/_core/adrs/principles/013-platform-scope-type.md

@@ -35,7 +35,7 @@ Do not use `scope-type: platform` for blueprints or reference architectures. Use
 
 #### 03-naming-convention
 
-A scope of type `platform` MUST have the word "platform" somewhere in its name. The position of the word is not enforced. Examples: `domain2-platform-aws`, `domain2-platform-callcenter`, `cloud-platform`.
+A scope of type `platform` MUST follow the naming pattern `{domain}-plat-{name}`, where `{domain}` identifies the owning domain or team and `{name}` identifies the specific platform area. Examples: `domain2-plat-aws`, `domain2-plat-callcenter`, `cloud-plat-infra`.
 
 #### 04-content-guidance
 

package/AGENTS.md

@@ -25,10 +25,7 @@ This rule has NO exceptions. Simple questions ("which command?", "what pattern?"
    - Analyse your work against the Policies and ensure implementation decisions follow guidelines and patterns
    - Fix any issues
 
-4. **Document decisions as Policies when appropriate**
-   - Check if what is being performed shouldn't be documented as a Policy in _local scope (because the decision has potential to be reused in the future or the topic is complex and would benefit from a document for clarity). Create or update existing documents accordingly.
-
-5. **Do not perform git operations unless explicitelly asked**
+4. **Do not perform risky git operations unless explicitelly asked**
    - The developer should be in control of possible destructive operations on the workspace
 
 **This AGENTS.md file was created with xdrs-core and shouldn't be changed**

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; }
@@ -261,7 +250,7 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
     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
@@ -278,7 +267,7 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
         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);
@@ -297,11 +286,11 @@ function lintScopeIndexFrontmatter(scopeIndexPath, scopeName, errors, xdrsRoot,
   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 === 'reference' && !scopeName.includes('-ref-')) {
+    errors.push(`Scope with type "reference" must follow the naming pattern {domain}-ref-{name} (e.g. "security-ref-baseline"): ${toDisplayPath(scopeIndexPath)}`);
   }
-  if (scopeType === 'platform' && !scopeName.includes('platform')) {
-    errors.push(`Scope with type "platform" must have "platform" in its name: ${toDisplayPath(scopeIndexPath)}`);
+  if (scopeType === 'platform' && !scopeName.includes('-plat-')) {
+    errors.push(`Scope with type "platform" must follow the naming pattern {domain}-plat-{name} (e.g. "cloud-plat-aws"): ${toDisplayPath(scopeIndexPath)}`);
   }
 
   if (!fm.name) {

package/lib/lint.test.js

@@ -716,18 +716,18 @@ test('accepts all valid scope-type values', () => {
   expect(result.errors.join('\n')).not.toContain('Scope index must start with');
 });
 
-test('accepts scope-type reference when scope name contains reference', () => {
+test('accepts scope-type reference when scope name follows {domain}-ref-{name} pattern', () => {
   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', '',
+    '.xdrs/index.md': rootIndex(['[security-ref-baseline](security-ref-baseline/index.md)']),
+    '.xdrs/security-ref-baseline/index.md': '---\nscope-type: reference\nname: security-ref-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-ref-baseline Scope Overview\n\nSecurity reference.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/security-ref-baseline/adrs/index.md': [
+      '# security-ref-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',
+    '.xdrs/security-ref-baseline/adrs/principles/001-baseline.md': [
+      '---', 'name: security-ref-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', '',
+      '# security-ref-baseline-adr-policy-001: Security baseline', '',
       '## Context and Problem Statement', '', 'Baseline context.', '',
       '## Decision Outcome', '', 'Baseline outcome.', ''
     ].join('\n'),
@@ -758,21 +758,21 @@ test('reports scope-type reference when scope name does not contain reference',
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('Scope with type "reference" must have "reference" in its name');
+  expect(result.errors.join('\n')).toContain('Scope with type "reference" must follow the naming pattern {domain}-ref-{name}');
 });
 
-test('accepts scope-type platform when scope name contains platform', () => {
+test('accepts scope-type platform when scope name follows {domain}-plat-{name} pattern', () => {
   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', '',
+    '.xdrs/index.md': rootIndex(['[cloud-plat-infra](cloud-plat-infra/index.md)']),
+    '.xdrs/cloud-plat-infra/index.md': '---\nscope-type: platform\nname: cloud-plat-infra\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-plat-infra Scope Overview\n\nCloud platform.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/cloud-plat-infra/adrs/index.md': [
+      '# cloud-plat-infra 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',
+    '.xdrs/cloud-plat-infra/adrs/principles/001-baseline.md': [
+      '---', 'name: cloud-plat-infra-adr-policy-001-baseline',
       'description: Cloud platform baseline', 'apply-to: All scopes', 'valid-from: 2026-01-01', '---', '',
-      '# cloud-platform-adr-policy-001: Cloud baseline', '',
+      '# cloud-plat-infra-adr-policy-001: Cloud baseline', '',
       '## Context and Problem Statement', '', 'Platform context.', '',
       '## Decision Outcome', '', 'Platform outcome.', ''
     ].join('\n'),
@@ -804,7 +804,7 @@ test('reports scope-type platform when scope name does not contain platform', ()
 
   const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
-  expect(result.errors.join('\n')).toContain('Scope with type "platform" must have "platform" in its name');
+  expect(result.errors.join('\n')).toContain('Scope with type "platform" must follow the naming pattern {domain}-plat-{name}');
 });
 
 test('reports scope-type core when scope name does not contain core', () => {
@@ -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-plat-custom](my-plat-custom/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-plat-custom/index.md': '---\nscope-type: platform\nname: my-plat-custom\ndescription: Platform scope.\napply-to: All\nvalid-from: 2026-01-01\n---\n\n# my-plat-custom Scope Overview\n\nPlatform scope.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/my-plat-custom/adrs/index.md': [
+      '# my-plat-custom ADR Index', '', 'Platform ADRs.', '', '## principles', '',
+      '- [001-domain-scope-type](principles/001-domain-scope-type.md) - domain type', ''
+    ].join('\n'),
+    '.xdrs/my-plat-custom/adrs/principles/001-domain-scope-type.md': [
+      '---', 'name: my-plat-custom-adr-policy-001-domain-scope-type',
+      'description: Defines the domain scope type.', 'apply-to: All', 'valid-from: 2026-01-01', '---', '',
+      '# my-plat-custom-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)']),

package/package.json

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