xdrs-core 0.35.1 → 0.36.1

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -64,6 +64,9 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - Policies MUST be concise and reference other Policies to avoid duplication.
 - The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `apply-to` and `valid-from` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
 - Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the reader apply the decision correctly. Keep them short and decision-specific.
+- Policies MUST NOT include historical change notes or descriptions of what changed from a previous version. State only the current rule that must be followed. Historical context is available via git history or versioned packages.
+- When a policy covers elements that could be confused with each other, include explicit disambiguation statements clarifying the distinction before stating the rules for each.
+- Rules MUST focus on what is required or forbidden. Explanations of why a rule exists belong in a Research document, not in the Policy itself. Link to the relevant research when the rationale is important for adoption.
 - When the decision defines strong policies or rules that should be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the Policy MUST follow the extension [_core-adr-policy-008 - Policy standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
 - Conflict handling applies to Policy documents:
   - For cross-scope overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope.

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

@@ -286,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', () => {
@@ -888,19 +888,19 @@ test('accepts custom scope-type when policy exists in core-type scope', () => {
 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/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-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', '',
+    '.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-platform/adrs/principles/001-domain-scope-type.md': [
-      '---', 'name: my-platform-adr-policy-001-domain-scope-type',
+    '.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-platform-adr-policy-001: domain scope type', '', '## Context and Problem Statement', '',
+      '# 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

package/package.json

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