xdrs-core 0.44.0 → 0.46.0

package/.xdrs/_core/adrs/index.md

@@ -24,6 +24,8 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-016](principles/016-policy-subjects.md) - **Policy Subjects** — Allowed subjects per type (ADR/BDR/EDR), descriptions, examples, and disambiguation tiebreakers
 - [_core-adr-policy-017](principles/017-policy-numbering-ranges.md) - **Policy numbering ranges** — Subject-based 100-number block ranges for policy numbering and the freeze-reference exemption
 - [_core-adr-policy-018](principles/018-external-path-symlinks.md) - **External path symlinks** — How to make XDRS files accessible from paths outside the .xdrs/ root using symlinks
+- [_core-adr-policy-019](principles/019-compiled-scope-type.md) - **compiled scope type** — Defines the `compiled` scope type: scopes whose policies are compiled from external authoritative sources with strict source traceability and no invented content
+- [_core-adr-policy-020](principles/020-media-and-asset-standards.md) - **Media and asset standards** — Canonical diagram format preference order and non-Markdown asset rules for all XDRS document types
 
 ## Skills
 
@@ -37,6 +39,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
 - [007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
 - [008-write-xdrs-doc](principles/skills/008-write-xdrs-doc/SKILL.md) - **Write XDRS Doc** — router skill; infers document type and delegates to the appropriate authoring skill
+- [009-compile-scope](principles/skills/009-compile-scope/SKILL.md) - **Compile Scope** — compiles or updates a `compiled`-type scope from its configured external sources
 
 ## Articles
 

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

@@ -62,11 +62,11 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - `_core-adr-policy-004` defines article standards
   - `_core-adr-policy-006` defines research standards
   - `_core-adr-policy-007` defines plan standards
-- For simple structures, flows, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams) or ASCII art instead of external assets.
-- Any non-Markdown supporting files referenced by a document (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they MUST live in a sibling `.assets/` folder next to the document.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). **Per-document-type `.assets/` paths:**
   - Policies in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
   - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
   - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
+  - Plans use `[xdrs-root]/[scope]/[type]/[subject]/plans/.assets/`
   - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of XDRS
@@ -90,8 +90,10 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
     - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
-    - `follows` (optional): Core scope names whose Policies apply as mandatory conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`).
-    - `related-scopes` (optional): Scope names of parent, sibling, or child scopes. Use when structural links help verify policy correctness across related scopes.
+    - `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.
+    - `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.
 - **Policy numbering:** Numbers MUST be assigned within the subject-based block ranges defined in [`_core-adr-policy-017`](017-policy-numbering-ranges.md). Use the lowest available number within the block for the chosen subject. See [`_core-adr-policy-002-policy-standards.01-freeze-reference-exemption`](002-policy-standards.md) for exemptions.
 - MUST NOT use emojis
@@ -150,3 +152,4 @@ subject/
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
 - [_core-adr-policy-007 - Plan standards](007-plan-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules

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.
-- Any non-Markdown files referenced by a Policy (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `[xdrs-root]/[scope]/[type]/[subject]/.assets/`.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 - 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

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -116,8 +116,7 @@ Rules:
 - The directory name MUST follow the format `[number]-[skill-name]` (e.g., `001-code-review`), matching the `name:` field.
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
 - `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
-- For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Any non-Markdown files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
 - Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - File names MUST be lowercase.

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -38,8 +38,7 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 - When an article tells readers which decisions to follow, it SHOULD check `valid-from:` first to determine the convergence date, `apply-to:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles MUST NOT present out-of-window or out-of-scope Policies as current rules for the discussed context.
 - Articles MUST remain consistent with the Policies, Research documents, and Skills they reference. When a referenced artifact changes, the article MUST be reviewed and updated.
 - Place an article in the subject folder that best matches its topic using the required list of subjects per type defined in `_core-adr-policy-001`. If an article spans more than one subject, place it in `principles`.
-- For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Any non-Markdown files referenced by an article SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Articles SHOULD use diagrams to illustrate concepts, overviews, and relationships; draw.io SHOULD be used for conceptual and relationship diagrams (e.g., component maps, context views, architecture overviews) when Mermaid cannot adequately express them.
 - File names MUST be lowercase.
 - MUST NOT use emojis in article content.
 

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -37,9 +37,9 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - Research documents MUST describe the methods, tools, sources, and conditions with enough detail that an experienced professional could at least minimally reproduce the important parts of the study, especially the aspects that materially affected the conclusion.
 - The short title portion after the research id MUST stay under 20 words.
 - `## Abstract` MUST be a single paragraph under 200 words summarizing the goal, methods, results, and conclusion. It SHOULD let a quick technical reader understand the question, method, main result, and takeaway.
-- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations, and SHOULD use external visuals only when they are materially necessary to improve understanding. It MUST stay under 700 words and MUST end with `Question: [central question]?`.
+- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, and tables for simple explanations, and SHOULD use diagrams to illustrate concepts and relationships when they improve clarity over plain text (see [`_core-adr-policy-020`](020-media-and-asset-standards.md) for format preference; draw.io SHOULD be used for conceptual and relationship diagrams such as context maps, component relationships, and architecture overviews). It MUST stay under 700 words and MUST end with `Question: [central question]?`.
 - `## Methods` MUST explain how the study was conducted, including design, tools, data sources, and test conditions, with a reproducibility goal. It MUST stay under 1200 words.
-- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables, bullet lists, or ASCII art for simple comparisons, and SHOULD use external figures only when they are materially necessary. Keep interpretation to a minimum. It MUST stay under 1800 words.
+- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables and bullet lists for simple comparisons, and SHOULD use diagrams to illustrate concepts and relationships when they improve clarity over plain text (see [`_core-adr-policy-020`](020-media-and-asset-standards.md) for format preference; draw.io SHOULD be used for conceptual and relationship diagrams). Keep interpretation to a minimum. It MUST stay under 1800 words.
 - When different options for the same problem are being analyzed, `## Results` SHOULD include comparison tables and explicit pros and cons for each option so the trade-offs are directly inspectable.
 - `## Discussion` MUST interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications for technical readers. It MUST stay under 1000 words.
 - `## Conclusion` MUST summarize the main findings, practical takeaway, applicability boundaries, and important open questions. It MUST stay under 400 words.
@@ -50,7 +50,7 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - Research documents SHOULD link in `## References` to the Policies, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
 - A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not REQUIRED.
 - One research document MAY also be referenced by multiple Policies, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
-- Any non-Markdown files referenced by a research document SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Research documents SHOULD use diagrams to illustrate concepts and relationships; draw.io SHOULD be used for conceptual and relationship diagrams (e.g., context maps, component relationships, architecture overviews) when Mermaid cannot adequately express them.
 - Research file names MUST be lowercase. MUST NOT use emojis.
 - A research document MAY exist before the related Policy is written, or remain after the Policy changes, as long as its status and references stay clear.
 
@@ -91,7 +91,7 @@ All research documents MUST follow this template:
 ## Introduction
 
 [Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
-Prefer bullets, tables, or ASCII art for simple explanations. Use external visuals only when they are materially necessary. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
+Prefer markdown structures (bullets, tables, headings) first; for diagrams see _core-adr-policy-020. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
 
 Question: [Central question of the research]?
 
@@ -103,7 +103,7 @@ Include enough detail for an experienced professional to reproduce the relevant
 ## Results
 
 [Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
-Prefer tables, bullets, or ASCII art for simple comparisons. Use external figures only when they are materially necessary. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
+Prefer tables and bullet lists for simple comparisons; for diagrams see _core-adr-policy-020. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
 
 ## Discussion
 
@@ -135,4 +135,5 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md)
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
 - [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document

package/.xdrs/_core/adrs/principles/007-plan-standards.md

@@ -33,7 +33,7 @@ Plans are Markdown documents placed inside a subject folder alongside policies.
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - File names MUST be lowercase.
 - MUST NOT use emojis in plan content.
-- Any non-Markdown files referenced by a plan SHOULD be used only when they are materially necessary and MUST live in `plans/.assets/` next to the plan files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
 
 **Folder layout**
 

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -36,7 +36,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - Slide file names MUST NOT exceed 64 characters (including the `.md` extension).
 - Slide file names MUST be lowercase.
 - When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view MUST be written first. The slides then support that article, not the individual documents directly.
-- Slides SHOULD contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
+- Slides SHOULD contain minimal text. For diagrams, prefer ASCII art for very simple cases, Mermaid for flows and relationships, and draw.io when Mermaid is insufficient (see [`_core-adr-policy-020`](020-media-and-asset-standards.md)); for other slide content, prefer short bullet points, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
 - Slides SHOULD follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
 - Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.
 - The target audience MUST be identified (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
@@ -51,4 +51,5 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Policy document writing rules
 - [_core-adr-policy-004 - Article standards](004-article-standards.md) - Article standards for multi-document views
 - [007-write-presentation skill](skills/007-write-presentation/SKILL.md) - Skill for creating slide presentations
+- [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules
 - [Marp](https://marp.app/) - Markdown Presentation Ecosystem

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

@@ -15,15 +15,13 @@ XDRS provides three mechanisms that govern what content belongs in a scope and h
 2. **`follows:` declarations**: a scope explicitly declares that it follows the standards of a named `core`-type scope.
 3. **Scope-local standards**: a policy inside a scope that defines content rules specific to that one scope.
 
-Without a clear definition of how these mechanisms are authored and how they interact, tools, agents, and authors cannot reliably determine which standards apply when adding or reviewing content in a scope.
-
 ## Decision Outcome
 
 **Define scope types as policies, local meta-policies as `core`-named policies in `principles/`, and a clear precedence chain for governance application.**
 
 All scope types — both the five built-in types and any custom types — are defined using the same convention: a `{scope-type}-scope-type` policy in a `core`-type scope. Scope-local standards (called _local meta-policies_) are optional policies whose filename title starts with `core` and which are placed in the `principles` subject of the scope. Multiple local meta-policy files are allowed, each distinguished by an optional qualifier. Tools and agents apply all applicable standards in a defined order.
 
-> **Choosing between a local meta-policy and a `-core` sibling scope**: use a local meta-policy (Section B) when the standards apply only to one scope and do not need to be shared. Use a separate `-core` sibling scope (see `_core-adr-policy-011`) when the meta governance needs to be shared with or distributed to other teams, or when it governs a family of scopes sharing the same prefix.
+> **Choosing between a local meta-policy and a `-core` sibling scope**: use a local meta-policy when the standards apply only to one scope. Use a `-core` sibling scope (see `_core-adr-policy-011`) when the governance needs to be shared or governs a family of scopes.
 
 ### Details
 
@@ -84,7 +82,7 @@ A scope-type definition policy MAY declare a parent scope type by including a ru
 
 A `scope-type` value in a scope `index.md` is valid if and only if a policy file whose name ends with `{scope-type}-scope-type` exists in the `principles` subject of any `core`-type scope in the workspace. Tools (such as `xdrs-core lint`) MUST enforce this for every element when `scope-type` is an array.
 
-When a scope declares a `scope-type` (single or array) but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace, the scope MUST be treated as READ-ONLY by all tools and agents: content in it MUST NOT be added, changed, or removed, and its content MUST NOT be reviewed. Tools and agents MUST surface the read-only status to the user and MUST NOT propose or apply any changes until the scope-type governance is installed.
+When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace, the scope MUST be treated as READ-ONLY: content MUST NOT be added, changed, removed, or reviewed. Tools MUST surface the read-only status and MUST NOT apply changes until the scope-type governance is installed.
 
 #### 11-def-scope-type-must-be-structured
 
@@ -120,7 +118,7 @@ Creating a local meta-policy is optional. It SHOULD be created when a scope has
 
 #### 18-local-content
 
-A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 04–05 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, plans, research). Local meta-policies and their companion files MAY include a `## Conflicts` section to declare that one of their rules overrides a conflicting rule from a scope-type policy or `follows:` scope policy (see Section C rule 26-conflict-declarations).
+A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 04–05 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, plans, research).
 
 #### 19-local-must-be-structured
 
@@ -142,14 +140,14 @@ Tools and agents MUST apply the policies of all scopes listed in a scope's `foll
 
 When adding or reviewing content in a scope, tools and agents MUST:
 
-1. Read the scope's `scope-type` from its `index.md`. Normalise the value to a list: split on commas and trim whitespace; a single value with no comma becomes a one-element list.
+1. Read the scope's `scope-type` from its `index.md`. Normalise to a list: split on commas and trim whitespace.
 2. For each declared type in list order, resolve its full ancestor chain:
-   a. Search the `[type]/principles/` directories of all `core`-type scopes in the workspace for the `{scope-type}-scope-type.md` primary file.
-   b. If found, load the primary and all companion files (`{scope-type}-scope-type-{qualifier}.md`) from the **same directory**. Companions are loaded in alphabetical order by qualifier.
-   c. If the primary contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat steps a–c for the parent. Continue until no more parents are declared. Detect and stop on cycles.
-3. Concatenate all resolved ancestor chains in declaration order to form a single flat list (e.g., for `scope-type: [reference, platform]` where `reference → standard` and `platform → core`: `[standard, reference, core, platform]`).
-4. Deduplicate the flat list keeping the **first occurrence** of each type (preserves the ancestor semantics of whichever type introduced the parent earliest).
-5. Apply all policies from the deduplicated list as mandatory conventions. Later entries in the list override earlier entries when the same rule number appears with different content, provided the override is declared (see rule 26-conflict-declarations).
+   a. Search `[type]/principles/` directories of all `core`-type scopes for the `{scope-type}-scope-type.md` primary file.
+   b. If found, load the primary and all companion files (`{scope-type}-scope-type-{qualifier}.md`) from the **same directory**, in alphabetical qualifier order.
+   c. If the primary contains a rule titled `NN-parent-scope-type`, extract the parent type name and repeat steps a–c. Detect and stop on cycles.
+3. Concatenate all resolved ancestor chains in declaration order to form a flat list (e.g., `scope-type: [reference, platform]` where `reference → standard`, `platform → core`: `[standard, reference, core, platform]`).
+4. Deduplicate keeping the **first occurrence** of each type.
+5. Apply all policies from the deduplicated list as mandatory conventions. Later entries override earlier entries on same rule number conflicts (see rule 26-conflict-declarations).
 
 #### 23-application-local
 
@@ -167,8 +165,6 @@ When multiple governance layers define a rule with the same rule number, the lat
 2. `follows:` scope policies (applied in `follows:` list order; last-listed scope wins among themselves).
 3. Local meta-policies (`NNN-core.md` and companions in alphabetical qualifier order).
 
-In all cases, an override is valid only if the overriding policy contains a `## Conflicts` section that explicitly declares the conflict with the overridden rule (see rule 26-conflict-declarations). A conflict that is not declared MUST be surfaced as an error by tools and agents; the content cannot be validated until the conflict is resolved.
-
 All of the above are subordinate to `_core` structural rules, which MUST NOT be overridden.
 
 #### 25-ordering-custom-types
@@ -183,9 +179,61 @@ When a policy (scope-type definition, local meta-policy, or companion) overrides
 - The policy file where the original rule is defined.
 - A short explanation of why the override is required for this scope or type.
 
-A `## Conflicts` section MAY also document cross-scope-type incompatibilities for informational purposes — cases where two declared scope types define the same rule number differently and the content author needs to know which definition wins. Tools and agents MUST detect undeclared conflicts at review time (rules with the same number defined differently in the loaded chain) and surface them as errors. Semantic conflict detection (two rules with different numbers that are logically incompatible) is the responsibility of the authoring agent, not the lint tool.
+A `## Conflicts` section MAY also document cross-scope-type incompatibilities for informational purposes. Tools and agents MUST detect undeclared conflicts at review time and surface them as errors. Semantic conflict detection is the responsibility of the authoring agent, not the lint tool.
 
 ## References
 
 - [_core-adr-policy-011 - core scope type](011-core-scope-type.md) — defines the `core` scope type and when to use a `-core` sibling scope vs. a scope-local policy
-- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) — scope structure, `follows:` field definition, scope index frontmatter fields
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) — scope structure, `follows:` and `extends:` field definitions, scope index frontmatter fields
+
+---
+
+**Section D — Scope extends**
+
+#### 27-extends-declaration
+
+A scope MAY declare an `extends:` field in its `index.md` YAML frontmatter. The value MUST be a single scope name or a comma-separated list (YAML list format also valid). The field causes all **policy documents** (decision records only — skills, articles, research, and plans are NOT inherited) from the listed scopes to be treated as if authored in the extending scope. Valid for all scope types.
+
+#### 28-extends-disjoint
+
+The `extends:` field and the `follows:` field MUST reference disjoint sets of scope names. The same scope MUST NOT appear in both fields. Tools MUST enforce this and report an error using code `_core-adr-policy-010.28-extends-disjoint`.
+
+#### 29-extends-reserved-scopes
+
+A scope `extends:` declaration MUST NOT reference the reserved scope names `_local` or `_core` by name. `_local` is workspace-only and non-distributable; `_core` policies are always applied implicitly to every scope and extending them would be redundant. Tools MUST enforce this and report an error using code `_core-adr-policy-010.29-extends-reserved-scopes`.
+
+#### 30-extends-no-self
+
+A scope `extends:` declaration MUST NOT reference the declaring scope itself. Tools MUST enforce this and report an error using code `_core-adr-policy-010.30-extends-no-self`.
+
+#### 31-extends-no-cycle
+
+`extends:` declarations MUST NOT form circular chains (e.g., scope A extends B, B extends A). Tools MUST detect such cycles across the full workspace and report an error using code `_core-adr-policy-010.31-extends-no-cycle`, identifying the cycle.
+
+#### 32-extends-mandatory-presence
+
+Every scope listed in a scope's `extends:` field MUST exist in the workspace with an accessible `index.md`. If any referenced scope is absent or its `index.md` cannot be read, all READ, WRITE, and REVIEW operations on the extending scope MUST fail immediately. Tools MUST surface a clear message naming the missing scope and citing code `_core-adr-policy-010.32-extends-mandatory-presence`.
+
+#### 33-extends-content-precedence
+
+When loading the effective policy set for a scope, tools and agents MUST resolve the full `extends:` chain depth-first and apply the following content precedence (lowest to highest):
+
+1. Transitively extended scopes, in depth-first order, deduplicated keeping first occurrence. For A extends [B, C] where B itself extends [D]: resolved order is D < B < C.
+2. The extending scope's own policy documents (always take highest precedence and override all inherited policies).
+
+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:
+
+- Names the conflicting policy (scope and policy ID) being overridden or superseded.
+- Explains why the override or difference 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`).
+
+#### 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`.

package/.xdrs/_core/adrs/principles/019-compiled-scope-type.md

@@ -0,0 +1,117 @@
+---
+name: _core-adr-policy-019-compiled-scope-type
+description: Defines the `compiled` scope type — scopes whose policies are compiled strictly from external authoritative sources (web pages, git repositories, or local folders). All content must trace back to source; no invented content is permitted. The type may be combined with other scope types. Use when declaring a compiled-type scope, authoring content in a compiled scope, or configuring the compilation process.
+apply-to: All XDRS scope authors declaring compiled-type scopes; tools or agents compiling or reviewing compiled scopes
+valid-from: 2026-08-03
+---
+
+# _core-adr-policy-019: compiled scope type
+
+## Context and Problem Statement
+
+Some XDRS scopes exist to provide structured policy representations of external authoritative sources — industry standards, regulatory frameworks, vendor documentation, or reference materials published on the web, in git repositories, or in local folders. The content of these scopes must remain strictly faithful to the source: editorial additions, invented rules, and inferences beyond what the source states are not permitted.
+
+These scopes differ structurally from `reference`, `platform`, and `standard` scopes: they are defined by a systematic compilation process, require source traceability in every policy, and must document any inconsistencies found in the source rather than silently correcting them.
+
+How should a scope that exists solely as a compiled representation of external sources be identified and governed?
+
+## Decision Outcome
+
+**Declare `scope-type: compiled` for any scope whose policies are compiled directly from one or more external sources, where all content must trace back to the source and no invention is permitted.**
+
+### Details
+
+#### 01-scope-type-name
+
+The scope type defined by this policy is `compiled`. A scope MUST declare it by setting `scope-type: compiled` in its `index.md` YAML frontmatter. The `compiled` type MAY be combined with one or more other scope types using a comma-separated list (e.g., `scope-type: compiled, reference`).
+
+#### 02-when-to-use
+
+Use `scope-type: compiled` when the scope holds policies that are directly compiled from external authoritative sources and where the primary governance constraint is source fidelity, not editorial judgment. Examples include:
+
+- Policies compiled from industry standards (e.g., OWASP Top 10, NIST guidelines, ISO 27001 controls).
+- Policies compiled from vendor documentation, product specifications, or API contracts.
+- Policies compiled from regulatory texts, compliance frameworks, or legal documents.
+- Policies compiled from internal reference documents published in another repository or folder.
+
+`scope-type: compiled` MUST NOT be used for scopes that contain policies authored from scratch, derived from general knowledge, or editorially synthesised without a direct external source.
+
+#### 03-naming-convention
+
+`compiled`-type scopes have no required naming pattern. Any valid scope name MAY be used. When `compiled` is combined with another type (e.g., `scope-type: compiled, reference`), the naming convention of the non-`compiled` type MUST apply.
+
+#### 04-structured-format-required
+
+All policies in a `compiled` scope MUST use the structured policy format defined in `_core-adr-policy-008`. Every claim or rule originating from the source MUST be expressed as an individually referenceable numbered rule block.
+
+#### 05-source-traceability
+
+Every policy claim, rule body, and normative statement in a `compiled` scope MUST be traceable to at least one external source. Content MUST NOT be invented, inferred beyond what the source states, or filled in to cover gaps. Where the source is ambiguous or contradictory, the ambiguity or contradiction MUST be transcribed faithfully and documented as an inconsistency per rule 08.
+
+XDRS structural frontmatter fields (`name`, `description`, `apply-to`, `valid-from`) are explicitly exempt from this rule. These fields are generated from source text by the compilation process and are not considered invented content.
+
+#### 06-source-types
+
+Sources for a compiled scope MAY be specified as:
+
+- A web URL pointing to a publicly accessible page or document.
+- A git repository URL (e.g., `git@github.com:org/repo.git` or `https://github.com/org/repo.git`) pointing to a repository containing the source content.
+- A local folder path relative to the workspace root.
+
+When multiple source entries point to the same content (e.g., a web page and its git mirror), all MAY be listed so that the compilation process can use whichever source is accessible. The preference order for fetching is: git URL first, then local folder, then web URL.
+
+#### 07-compilation-meta-policy
+
+Before any compilation begins, at least one local meta-policy file named `NNN-core.md` MUST exist in a `[type]/principles/` directory of the target scope (e.g., `adrs/principles/001-core.md`). Compilation tools and agents MUST scan all type folders (`adrs`, `bdrs`, `edrs`) for such meta-policy files; each meta-policy governs compilation for its own type folder.
+
+The meta-policy MUST contain the following sections:
+
+- `## Sources` — one bullet per source using the format `- [web] https://...`, `- [git] git@...`, or `- [local] ./path`. Each source entry MAY include an inline description after the URL.
+- `## Selectors` — describes which portions of the fetched source to include or exclude, expressed as document sections, filename patterns, topics, or other criteria.
+
+The meta-policy MAY also contain:
+
+- `## Fetch Procedures` — special instructions for fetching the source (authentication, crawl depth, pagination, format conversion, etc.).
+- `## Compilation Notes` — guidance on how to structure or categorise the compiled content.
+- `## Review Notes` — guidance for reviewers verifying compiled content against the source.
+
+#### 08-inconsistencies-policy
+
+If the source contains inconsistencies, contradictions, errors, or gaps that cannot be faithfully transcribed as a valid policy, the compiled scope MUST document them in a dedicated policy file at `[type]/principles/NNN-inconsistencies-from-source.md`. Each inconsistency MUST reference the source file path and the affected compiled policy. Inconsistencies MUST NOT be silently corrected, omitted, or worked around.
+
+#### 09-ordering
+
+There is no fixed position for `compiled`-type scopes in the root `index.md`. When `compiled` is combined with another type, the ordering convention of the non-`compiled` type governs placement. When declared standalone, a `compiled` scope MAY appear at any position before `_local`.
+
+#### 10-source-section
+
+Every compiled policy MUST include a `## Source` section placed after the `## References` section (or after `## Decision Outcome` when no `## References` section is present). The section MUST list the relative file path(s) of the source document(s) used to produce the policy as plain text. Paths MUST NOT be written as markdown links, because the source files exist only inside a temporary local directory that is created during the compilation or review process.
+
+Example:
+
+```
+## Source
+
+- source-1/standards/owasp-top-10-2021/A01-broken-access-control.md
+- source-2/docs/security-controls.html
+```
+
+#### 11-compilation-notes
+
+Rule bodies in compiled policies SHOULD include `**compilation-note:**` inline markers when the mapping from source to rule is not obvious — for example: indirect references, conclusions drawn from multiple source sections, or interpretations that required judgment. Direct literal transcriptions of a single source statement do not require a marker. Review and update processes MUST consult these notes and re-fetch the source before making changes to compiled rules.
+
+Example:
+
+```
+#### 03-access-control-must-enforce-least-privilege
+
+All access control implementations MUST enforce the principle of least privilege.
+**compilation-note:** derived from OWASP A01:2021 "How to Prevent", bullet 3 — "Deny by default".
+```
+
+## References
+
+- [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) — numbered rule format required for all policies in compiled scopes
+- [_core-adr-policy-010 - Scope governance](010-scope-governance.md) — scope-type definition convention and local meta-policy mechanism
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) — policy document format and frontmatter requirements
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) — scope structure and `scope-type` field definition

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

@@ -0,0 +1,48 @@
+---
+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.
+apply-to: All XDRS document types
+valid-from: 2026-08-06
+---
+
+# _core-adr-policy-020: Media and asset standards
+
+## Context and Problem Statement
+
+Rules for diagram format preference and non-Markdown asset handling are scattered across multiple policies (001, 002, 003, 004, 006, 007) and all write-\* skills. The same asset placement and diagram preference rules appear independently in each document-type policy, creating duplication that `_core-adr-policy-002` itself prohibits, and inconsistency when the rules diverge.
+
+Question: What is the canonical preference order for representing visual information in XDRS documents, and where must non-Markdown files be stored?
+
+## Decision Outcome
+
+**Markdown-first preference order, with centralized asset placement rules**
+
+All diagram format preferences and non-Markdown asset rules are defined here as individually citable rule blocks. Individual document-type policies and skills reference this policy instead of repeating these rules.
+
+### Details
+
+#### 01-prefer-markdown
+Markdown structures MUST be the first choice for any layout, tabular data, list, heading hierarchy, or simple relationship that can be expressed adequately as plain text. Plain Markdown tables, bullet lists, headings, and code blocks MUST be used before reaching for any external visual format.
+
+#### 02-ascii-for-simple
+ASCII art MAY be used for very simple spatial layouts or shapes where plain Markdown structures cannot adequately convey the diagram. ASCII art SHOULD be limited to cases that are trivial to write and maintain as plain text; anything requiring visual complexity SHOULD use Mermaid instead.
+
+#### 03-mermaid-for-complex
+Mermaid.js SHOULD be used for diagrams that require explicit visual representation: flows, sequences, state machines, entity relationships, class diagrams, and activity diagrams. Mermaid is preferred over draw.io when it can adequately express the needed diagram.
+
+#### 04-drawio-when-mermaid-insufficient
+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.
+
+#### 05-drawio-storage
+draw.io diagrams MUST be saved as editable vector: File → Save As → Editable Vector. The resulting `.svg` file MUST be stored in the sibling `.assets/` folder. This embeds the draw.io source in the SVG so the diagram remains editable without a separate `.drawio` file.
+
+#### 06-assets-materially-necessary
+Non-Markdown files (images, diagrams, schemas, JSON examples, binaries, or any other data files) SHOULD be referenced only when they are materially necessary to preserve clarity, fidelity, or evidence. Assets that duplicate information already expressible in Markdown SHOULD NOT be added.
+
+#### 07-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`.
+
+## References
+
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Per-document-type `.assets/` canonical paths
+- [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Structured rule block format used in this policy