xdrs-core 0.46.2 → 0.47.0

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

@@ -82,7 +82,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `standard` — see [`_core-adr-policy-014`](014-standard-scope-type.md)
     - `_local` — see [`_core-adr-policy-015`](015-local-scope-type.md)
   - Scope name suffixes are unlimited and MAY be used in any scope type.
-  - When writing or generating a new XDRS root `index.md`, use the following default ordering (scopes listed later override earlier ones): `core → reference → platform → standard → _local`. Custom-type scopes SHOULD be placed in the `standard` position.
+  - When writing or generating a new XDRS root `index.md`, use the following default ordering (scopes listed later override earlier ones): `core → reference → platform → standard → _local`. Custom-type scopes SHOULD be placed in the `standard` position. This ordering is the **default fallback** for conflict resolution between scopes: `extends:` declarations (Section D of `_core-adr-policy-010`) take precedence over it for policy document inheritance, and `follows:` declarations govern authoring governance rules independently. See `_core-adr-policy-010.36-root-index-ordering-fallback` for the full normative definition.
   - **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.
@@ -91,7 +91,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `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 governance conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`). All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail.
-    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or plans) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail. When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Scopes referenced only via `extends:` chains (not entry scopes in the root index) are exempt from the root index link requirement. See `_core-adr-policy-010` Section D (rules 27–35) for full normative rules.
+    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or plans) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail. When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Scopes referenced only via `extends:` chains (not entry scopes in the root index) are exempt from the root index link requirement. `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
     - `license` (optional): SPDX identifier for the scope's content license.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
 - **Subjects:** The subject folder MUST be chosen per [`_core-adr-policy-016`](016-policy-subjects.md), which defines allowed subjects, full descriptions, examples, and disambiguation tiebreakers.
@@ -100,13 +100,14 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
 - **Links:** Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - **Indexes**
   - Every document in the collection (Policies, skills, articles, research, and plans) MUST be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and MUST be added to the index or removed.
+  - Index files MUST NOT contain policy rules or normative requirements. Those MUST be placed in dedicated Policy documents. Indexes are navigation artifacts only: links and short descriptions.
   - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index MUST link to every Policy, skill, article, research, and plan under that type+scope.
   - Canonical index requirements:
     - Organize XDRS documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - Add links to related scope indexes that this scope might override or be overridden by (scopes listed last override earlier ones on the same topic).
     - Each XDRS element entry MUST include a short description. SHOULD use an imperative statement or the question it answers (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?"
-  - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first". The root index MUST NOT link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
+  - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first" followed by a note that `extends:` and `follows:` declarations in individual scope indexes take precedence over this ordering for their respective resolution concerns (see `_core-adr-policy-010.36-root-index-ordering-fallback`). The root index MUST NOT link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
   - MUST verify if indexes are up to date after making changes
 - **Scope index**
   - Each scope folder MUST maintain an `index.md` file at `[xdrs-root]/[scope]/index.md`.

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

@@ -81,7 +81,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
 - MUST NOT use emojis in contents.
 - File names MUST be lowercase.
-- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
+- For diagram and asset rules in Policy documents, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Rule `02-policy-diagram-restrictions` below summarises the overall stance; the detailed rules are in policy 020.
 - Avoid using lengthy instructions on the Policy. If there are long and detailed instructions related to the Policy, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the Policy itself.
 - Policies SHOULD be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision
@@ -99,6 +99,10 @@ When a policy's frontmatter includes `freeze-reference: true`, the policy MUST N
 
 Content-level checks that do not affect the policy's reference (required sections, word count, emojis, broken outgoing links, structured rule block format, normative language) remain enforced. The `valid-from` date is not taken into consideration when evaluating whether `freeze-reference` applies.
 
+#### 02-policy-diagram-restrictions
+
+Images and diagrams in Policy documents are subject to strict restrictions: images MUST NOT be used; diagrams SHOULD be avoided and are only allowed in direct and punctual cases where directly connected to the decision. Diagram content has no normative force and must not be used for enforcement. For full rules see [`_core-adr-policy-020`](020-media-and-asset-standards.md) rules `10` through `14`.
+
 **Policy template**
 
 All Policies MUST follow this template

package/.xdrs/_core/adrs/principles/010-scope-governance.md

@@ -223,17 +223,25 @@ When loading the effective policy set for a scope, tools and agents MUST resolve
 
 Deduplication: if the same scope name appears more than once in the depth-first traversal, keep only the first occurrence. When a scope's policy overrides an inherited policy on the same topic, the overriding policy MUST include a `## Conflicts` section (see rule 34).
 
-Note: the `extends:` content-precedence chain is independent of Section C rule 24. `extends:` determines which policy documents are in scope; rule 24 determines which authoring rules apply.
-
 #### 34-extends-conflict-declaration
 
-When an extending scope's own policy addresses the same topic as a policy in an extended scope, or when two extended scopes address the same topic differently, the higher-precedence policy MUST include a `## Conflicts` section that:
+When an extending scope's policy overrides an inherited policy, or when extended scopes address the same topic differently, the higher-precedence policy MUST include a `## Conflicts` section that:
 
 - Names the conflicting policy (scope and policy ID) being overridden or superseded.
-- Explains why the override or difference exists.
+- Explains why the override exists.
 
-An undeclared semantic conflict between policies from the `extends:` chain MUST be surfaced as an error during review (see `_core-adr-policy-010.34-extends-conflict-declaration`).
+An undeclared conflict MUST be surfaced during review (see `_core-adr-policy-010.34-extends-conflict-declaration`).
 
 #### 35-extends-index
 
-Scopes referenced only via `extends:` chains and not linked in the root `index.md` are **exempt** from the "root index must link all scopes" requirement. These scopes form the building-block layer; the root index lists only entry scopes. If a scope is both referenced via `extends:` AND linked in the root index, tools SHOULD warn of ambiguous dual precedence (the root index ordering governs for consumers that do not interpret `extends:` declarations), using warning code `_core-adr-policy-010.35-extends-index`.
+Scopes referenced only via `extends:` chains and not linked in the root `index.md` are **exempt** from the "root index must link all scopes" requirement. If a scope is both referenced via `extends:` AND linked in the root index, tools SHOULD warn of ambiguous dual precedence using warning code `_core-adr-policy-010.35-extends-index`.
+
+---
+
+**Section E — Root index ordering and global conflict resolution**
+
+#### 36-root-index-ordering-fallback
+
+The root `index.md` ordering ("scopes listed last override the ones listed first") is the **default fallback** for policy document conflict resolution. `extends:` takes precedence: when a scope explicitly `extends:` another, the `extends:` chain (Section D, rule 33) governs; root index ordering MUST NOT be used to resolve conflicts between those scopes. For all other scope pairs, agents and tools MUST treat the later-listed scope in the root `index.md` as providing the overriding policy.
+
+`follows:` is independent of policy document conflict resolution. It governs authoring governance rules only (Section C, rule 24). Agents reading a single scope's `index.md` MUST also read the root `index.md` to determine conflict resolution order absent an `extends:` relationship.

package/.xdrs/_core/adrs/principles/020-media-and-asset-standards.md

@@ -1,6 +1,6 @@
 ---
 name: _core-adr-policy-020-media-and-asset-standards
-description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types. Use when choosing a diagram format or referencing any non-Markdown file in any XDRS document.
+description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types, including policy-document-specific restrictions on images and diagrams. Use when choosing a diagram format or referencing any non-Markdown file in any XDRS document.
 apply-to: All XDRS document types
 valid-from: 2026-08-06
 ---
@@ -34,10 +34,10 @@ Mermaid.js SHOULD be used for diagrams that require explicit visual representati
 draw.io SHOULD be used when Mermaid cannot adequately express the needed diagram — for example, custom visual layouts, freehand annotations, or combined view types that Mermaid does not support natively. draw.io SHOULD also be used when the diagram is expected to be edited directly by users in a graphical tool and its structure fits the draw.io editing model (e.g., boxes, connectors, swimlanes, layered layouts). draw.io diagrams MUST be saved as `.drawio` files in the sibling `.assets/` folder and referenced directly from the Markdown document.
 
 #### 05-svg-for-custom-vector
-Plain SVG MAY be used instead of draw.io when greater visual freedom is needed than draw.io provides, or when the diagram originates from tooling other than draw.io. SVG files MUST be stored in the sibling `.assets/` folder.
+Plain SVG MAY be used instead of draw.io when greater visual freedom is needed than draw.io provides, or when the diagram originates from tooling other than draw.io. SVG files MUST be stored in the sibling `.assets/` folder. SVG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 06-png-as-last-resort
-PNG (or other raster formats) MAY be used only when no vector or text-based format can adequately represent the content — for example, screenshots or photographs. PNG files MUST be stored in the sibling `.assets/` folder.
+PNG (or other raster formats) MAY be used only when no vector or text-based format can adequately represent the content — for example, screenshots or photographs. PNG files MUST be stored in the sibling `.assets/` folder. PNG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 07-assets-no-policy-content
 Asset files MUST NOT contain policy content. Diagrams and images do not carry mandatory or advisory language — they cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires. Assets MAY be used only to support the understanding of policy already stated in Markdown text; a visual that merely illustrates what the prose already says is acceptable, but any rule or constraint that exists only inside an asset file is invisible to policy and has no normative force. When in doubt, keep the content in Markdown.
@@ -48,7 +48,23 @@ Non-Markdown files (images, diagrams, schemas, JSON examples, binaries, or any o
 #### 09-assets-placement
 Non-Markdown files MUST live in the sibling `.assets/` folder next to the referencing document. The canonical per-document-type `.assets/` paths are defined in `_core-adr-policy-001`.
 
+#### 10-no-images-in-policies
+Images — including raster formats (PNG, JPEG, GIF, TIFF, and similar) and SVG files — MUST NOT be used in Policy documents. These formats cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires, and their content cannot be systematically enforced during review.
+
+#### 11-diagrams-rare-in-policies
+Mermaid and draw.io diagrams SHOULD be avoided in Policy documents. They MAY be included only in direct and punctual cases where the diagram illustrates the core structural pattern or architecture that the policy decision itself mandates. A diagram that introduces context, detail, or explanation not already present in the policy prose MUST NOT be included.
+
+#### 12-diagrams-connected-to-decision
+Any diagram included in a Policy document MUST be directly connected to the policy decision described in that document. A diagram MAY include a simple illustrative example. Diagrams showing multiple usage examples, edge cases, or supplementary context MUST be placed in an article instead.
+
+#### 13-diagrams-not-normative-in-policies
+Content within diagrams in Policy documents — labels, annotations, and depicted relationships — MUST NOT be used for policy enforcement. Mandatory and advisory language within a diagram has no normative force. During authoring, diagram content MUST be checked for consistency with the policy prose; any inconsistency MUST be resolved before the policy is published.
+
+#### 14-articles-for-visual-explanation
+When additional visual explanation is needed for a Policy — such as multiple usage examples, context breakdowns, detailed walkthroughs, or educational material — an article MUST be written instead of adding more diagrams to the policy. Articles are the appropriate place for visual education about a policy; the policy itself MUST remain focused on the decision declaration.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Per-document-type `.assets/` canonical paths
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Summary rule `02-policy-diagram-restrictions` that points to rules 10–14 here
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Structured rule block format used in this policy

package/package.json

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