xdrs-core 0.24.1 → 0.26.0

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

@@ -1,35 +1,35 @@
 # _core ADRs Index
 
-Decisions about how the XDR framework itself works: structure, standards, document types, versioning, and supporting artifacts. Owned by the platform team. Propose changes via pull request.
+Decisions about how the XDRS framework itself works: structure, standards, document types, versioning, and supporting artifacts. Owned by the platform team. Propose changes via pull request.
 
 ## Principles
 
 Foundational standards, principles, and guidelines.
 
-- [_core-adr-001](principles/001-xdrs-core.md) - **XDRs core** — Types, scopes, subjects, folder structure, and indexes for the XDR framework
-- [_core-adr-002](principles/002-xdr-standards.md) - **XDR standards** — How to write individual XDR decision documents: template, metadata, ID, lifecycle rules
-- [_core-adr-003](principles/003-skill-standards.md) - **Skill standards** — How to author and organize reusable skill packages within XDR projects
-- [_core-adr-004](principles/004-article-standards.md) - **Article standards** — How to write synthetic views combining XDRs, research, and skills
-- [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages** — How to version XDR packages to communicate upgrade impact
-- [_core-adr-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing XDR decisions
-- [_core-adr-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
-- [_core-adr-008](principles/008-xdr-standards-structured.md) - **XDR standards - structured** — How to expose individually referenceable numbered rules inside an XDR when external citation by identifier is required
-- [_core-adr-009](principles/009-presentation-standards.md) - **Presentation standards** — How to structure Marp slide presentations that support XDR documents
+- [_core-adr-policy-001](principles/001-xdrs-core.md) - **XDRS core** — Types, scopes, subjects, folder structure, and indexes for the XDRS framework
+- [_core-adr-policy-002](principles/002-policy-standards.md) - **Policy standards** — How to write individual Policy documents: template, metadata, ID, lifecycle rules
+- [_core-adr-policy-003](principles/003-skill-standards.md) - **Skill standards** — How to author and organize reusable skill packages within XDRS projects
+- [_core-adr-policy-004](principles/004-article-standards.md) - **Article standards** — How to write synthetic views combining Policies, research, and skills
+- [_core-adr-policy-005](principles/005-semantic-versioning-for-xdrs-packages.md) - **Semantic versioning for XDRS packages** — How to version XDRS packages to communicate upgrade impact
+- [_core-adr-policy-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing Policy decisions
+- [_core-adr-policy-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
+- [_core-adr-policy-008](principles/008-xdr-standards-structured.md) - **Policy standards - structured** — How to expose individually referenceable numbered rules inside a Policy when external citation by identifier is required
+- [_core-adr-policy-009](principles/009-presentation-standards.md) - **Presentation standards** — How to structure Marp slide presentations that support XDRS documents
 
 ## Skills
 
 Step-by-step procedural guides for humans and AI agents.
 
-- [001-lint](principles/skills/001-lint/SKILL.md) - **Lint** — review code and files against XDRs
-- [002-write-xdr](principles/skills/002-write-xdr/SKILL.md) - **Write XDR** — create a new Decision Record
-- [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
-- [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
-- [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
-- [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 XDR documents
+- [_core-adr-skill-001-review](principles/skills/001-review/SKILL.md) - **Review** — review code and files against Policies
+- [_core-adr-skill-002-write-policy](principles/skills/002-write-policy/SKILL.md) - **Write Policy** — create a new Policy document
+- [_core-adr-skill-003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
+- [_core-adr-skill-004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
+- [_core-adr-skill-005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
+- [_core-adr-skill-006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
+- [_core-adr-skill-007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
 
 ## Articles
 
-Synthetic views combining XDRs, Research, and Skills around a specific topic.
+Synthetic views combining Policies, Research, and Skills around a specific topic.
 
-- [_core-article-001](principles/articles/001-xdrs-overview.md) - **XDRs Overview** (objective, structure, getting started, guidelines, extension, usage)
+- [_core-adr-article-001](principles/articles/001-xdrs-overview.md) - **XDRS Overview** (objective, structure, getting started, guidelines, extension, usage)

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

@@ -1,15 +1,15 @@
 ---
-name: _core-adr-001-xdrs-core
-description: Defines the core XDR framework including types (ADR, BDR, EDR), folder structure, scopes, subjects, and index requirements. Use when structuring or navigating decision records.
+name: _core-adr-policy-001-xdrs-core
+description: Defines the core XDRS framework including types (ADR, BDR, EDR), folder structure, scopes, subjects, and index requirements. Use when structuring or navigating policies.
 ---
 
-# _core-adr-001: XDRs core
+# _core-adr-policy-001: XDRs core
 
 ## Context and Problem Statement
 
 We need a consistent way to capture decisions that scales across scopes and subjects, remains easy to navigate, and works well with AI agents.
 
-How should XDRs be structured and organized across types, teams, and scopes?
+How should XDRS be structured and organized across types, teams, and scopes?
 
 ## Decision Outcome
 
@@ -19,24 +19,24 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 
 ### Details
 
-Decision Records can be of different kinds, depending on the nature of the decision:
+A standard Decision Record normally combines several concerns in the same document: a reason (why, options considered), a policy (rules, what is the decision), a plan (consequences, when it will be implemented), a how-to (step-by-step how-to procedure), and a view on a topic. The XDRS framework separates these concerns into different document types: Policies as the source of truth for the core of the decision, Research for reasoning and evidence, Plans for implementation approach, Skills for execution procedures, and Articles for topic overviews. Supporting artifacts may explain, justify, or operationalize the policy, but they do not replace it. The compilation process of a raw Decision Record is to distribute it into those different documents and create links between them. You can also use the framework standalone, generating these elements individually directly during the writing process.
+
+Policies can be of different kinds, depending on the nature of the decision:
 - BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
 - ADR (Architectural Decision Record): Wider architectural and technical decisions. Examples: how big topics relate to each other, system contexts, overview without realy deciding on details, integration patterns, overarching topics, corporate wide practices, corporate systems, external and internal partners etc
 - EDR (Engineering Decision Record): captures engineering details about how to implement things. Examples: specific tools and libraries selection, framework usage, best practices on coding, testing, quality, project structure, pipelines etc
 
-Collectively, these are referred to as XDRs.
-
 #### General framework standards
 
-- The main document type in the collection of XDRs is the XDR document, which contains a decision. Other documents are normally related to this decision and shouldn't go against its contents.
+- The main document type in the collection of XDRS is the Policy document, which contains the core of a decision, contraints, rules and what should be followed. Other documents are normally related to this policy and should never go against its contents.
 - All documents in the framework should be removed when they are no longer necessary. The latest version of the collection always represents the active set of documents. Historical versions are available via versioned packages or git history. There is no status field on documents; if a document is present, it is considered active and valid. This keeps the document base clean and avoids confusion about which documents are current. REJECT any indication in the Decisions that contradicts this rule to avoid confusion and complexity.
 - Make it clear if an instruction is mandatory or advisory.
   - Mandatory language: "must", "always", "never", "required", "mandatory"
   - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
-- The XDR root folder is the folder that contains the root `index.md`. The default root folder name is `.xdrs/`. Any folder name is valid as long as it contains an `index.md`. When `.xdrs/` is used, tools and agents discover it automatically by looking for `.xdrs/index.md` relative to the workspace root. When a different folder name is used, it must be passed explicitly to tools (e.g., `xdrs-core lint my-decisions/`).
-- ALWAYS use the following folder structure for XDR documents:
+- The XDRS root folder is the folder that contains the root `index.md`. The default root folder name is `.xdrs/`. Any folder name is valid as long as it contains an `index.md`. When `.xdrs/` is used, tools and agents discover it automatically by looking for `.xdrs/index.md` relative to the workspace root. When a different folder name is used, it must be passed explicitly to tools (e.g., `xdrs-core lint my-decisions/`).
+- ALWAYS use the following folder structure for Policy documents:
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
-  where `[xdrs-root]` is the XDR root folder (default: `.xdrs/`).
+  where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
 - **Files listed in `.filedist` are external XDRs.** A file whose path appears in the workspace root `.filedist` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
@@ -44,26 +44,26 @@ Collectively, these are referred to as XDRs.
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
   - `[xdrs-root]/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
-- Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated XDRs. This XDR defines the shared framework baseline; `_core-adr-002` defines the XDR document writing standard.
-  - `_core-adr-002` defines XDR standards (document writing)
-  - `_core-adr-003` defines skill standards
-  - `_core-adr-004` defines article standards
-  - `_core-adr-006` defines research standards
-  - `_core-adr-007` defines plan standards
+- Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated Policies. This Policy defines the shared framework baseline; `_core-adr-policy-002` defines the Policy document writing standard.
+  - `_core-adr-policy-002` defines Policy standards (document writing)
+  - `_core-adr-policy-003` defines skill standards
+  - `_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.
-  - XDRs in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
+  - 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/`
   - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - Sub-directories inside `.assets/` are allowed to keep related files organized only when that `.assets/` folder already has more than 10 files. Otherwise, keep files flat in `.assets/`.
 - **Scopes:** 
-  - Short name that defines a group or a package of xdrs
+  - Short name that defines a group or a package of XDRS
   - examples: `business-x`, `business-y`, `team-43`, `_core`
-  - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` MUST NOT be shared with or propagated to other contexts. This scope MUST always be placed in the lowest position in the root `index.md` so that its decisions override or extend any decisions from higher-positioned scopes. Shared root `index.md` files MUST NOT include an explicit link to `_local`, because `_local` remains workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try the default workspace-local path `_local/index.md` when it exists, even without a root-index link. Documents in non-`_local` scopes MUST NEVER link to any document inside `_local`; documents inside `_local` MAY link to other documents inside `_local`.
+  - `_local` is a reserved scope for XDRS elements created locally to a specific project or repository. XDRS elements in `_local` MUST NOT be shared with or propagated to other contexts. This scope MUST always be placed in the lowest position in the root `index.md` so that its decisions override or extend any decisions from higher-positioned scopes. Shared root `index.md` files MUST NOT include an explicit link to `_local`, because `_local` remains workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try the default workspace-local path `_local/index.md` when it exists, even without a root-index link. Documents in non-`_local` scopes MUST NEVER link to any document inside `_local`; documents inside `_local` MAY link to other documents inside `_local`.
   - **Types:** `adrs`, `bdrs`, `edrs`
   - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
-- **Subjects:** MUST be one of the following depending on the type of the XDR. Use the subject to indicate the main concern of the decision.
+- **Subjects:** MUST be one of the following depending on the type of the Policy. Use the subject to indicate the main concern of the decision.
   - **ADR subjects**
     - `principles`: Cross-cutting architecture and policy foundations.
       - Examples: architecture style, interoperability rules, long-term technology direction.
@@ -112,22 +112,22 @@ Collectively, these are referred to as XDRs.
 - Never use emojis
 - **Links:** Use relative paths for all links; never use absolute paths starting with `/`.
 - **Indexes**
-  - Every document in the collection (XDRs, 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.
-  - 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 XDR, skill, article, research, and plan under that type+scope.
+  - 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.
+  - 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 XDR documents by subject for easier navigation
+    - 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 a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRs in scopes listed last override XDRs in scopes listed first when addressing the same topic.
-    - Each XDR element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
-  - 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 in 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)`).
+    - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRS in scopes listed last override XDRS in scopes listed first when addressing the same topic.
+    - Each XDRS element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
+  - 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)`).
   - Always 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`.
-  - The scope index is a short article (under 1000 words) that provides an overview of all XDR contents within that scope. Follow article standards (`_core-adr-004`) when writing this file.
+  - The scope index is a short article (under 1000 words) that provides an overview of all XDRS contents within that scope. Follow article standards (`_core-adr-policy-004`) when writing this file.
   - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful for them before diving into the specific documents. Write a guided summary that helps them decide whether to explore further.
   - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
   - At the end of the scope index, always add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
-  - Whenever the contents of a scope change (new XDRs, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
+  - Whenever the contents of a scope change (new Policies, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
 
 **Folder structure examples** (using the default `.xdrs/` root):
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
@@ -136,7 +136,7 @@ Collectively, these are referred to as XDRs.
 
 ```text
 subject/
-|-- 001-xdr.md
+|-- 001-policy.md
 |-- .assets/
 |-- articles/
 |   |-- 001-article.md
@@ -155,10 +155,10 @@ subject/
 
 ## References
 
-- [_core-adr-002 - XDR standards](002-xdr-standards.md) - Standards for writing individual XDR decision documents
-- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
-- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
-- [_core-adr-003 - Skill standards](003-skill-standards.md)
-- [_core-adr-004 - Article standards](004-article-standards.md)
-- [_core-adr-006 - Research standards](006-research-standards.md)
-- [_core-adr-007 - Plan standards](007-plan-standards.md)
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Standards for writing individual Policy documents
+- [001-review skill](skills/001-review/SKILL.md) - Skill for reviewing code changes against Policies
+- [002-write-policy skill](skills/002-write-policy/SKILL.md) - Skill for creating a new Policy following this standard
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
+- [_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)

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

@@ -0,0 +1,153 @@
+---
+name: _core-adr-policy-002-policy-standards
+description: Defines how Policy documents (the core Policy document type) should be written, including template, frontmatter, applicability fields, and conflict handling. Use when writing or reviewing any Policy, rules, contraints or a specific decision document.
+---
+
+# _core-adr-policy-002: Policy standards
+
+## Context and Problem Statement
+
+Policy framework elements (types, scopes, subjects, folder structure) are defined in `_core-adr-policy-001`. Once a policy's structural placement is clear, how should the document itself be written to remain authoritative, concise, and consistently structured?
+
+## Decision Outcome
+
+**Structured policies with a mandatory template, applicability metadata, and clear conflict rules**
+
+Policy documents are the authoritative source of truth for their scope, type, and subject. They must be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
+
+### Details
+
+- Policies MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Always cite sources.
+- Policies are the central artifact of the framework and the authoritative source of truth for their scope, type, and subject.
+- Policy documents MUST include a YAML frontmatter block at the very beginning of the file. The supported fields are:
+
+| Field | Required | Constraints |
+|---|---|---|
+| `name` | Yes | 1-64 characters. Lowercase letters, numbers, hyphens, and leading underscores only. Must not end with a hyphen. Must not contain consecutive hyphens. Must match the document identifier from the heading: `[scope]-[type]-policy-[number]-[short-title]`. |
+| `description` | Yes | 1-1024 characters. Describes what this decision is about and when to use it. Should include keywords that help agents identify when to apply it. |
+| `apply-to` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. ONLY use this section if the usage is very specific to a specific case. Examples: `Only frontend code`, `JavaScript projects`. |
+| `valid-from` | No | ISO date (`YYYY-MM-DD`) indicating from when this decision must be enforced. Before this date it should be used everywhere possible, but compliance is not enforced during reviews until after this date. |
+| `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
+| `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
+
+  - Minimal example:
+    ```yaml
+    ---
+    name: _core-adr-policy-002-policy-standards
+    description: Defines how Policy documents should be written. Use when writing or reviewing any Policy.
+    ---
+    ```
+  - Example with optional fields:
+    ```yaml
+    ---
+    name: _core-adr-policy-002-policy-standards
+    description: Defines how Policy documents should be written. Use when writing or reviewing any Policy.
+    apply-to: All Policy scopes
+    valid-from: 2026-06-01
+    metadata:
+      author: example-org
+    ---
+    ```
+- All documents present in the collection are considered active. There is no status field. When a decision is no longer relevant, valid or active, it must be removed from the collection. Historical versions are available via versioned packages or git history.
+- Before using, enforcing, or citing a Policy as a current rule, humans and AI agents MUST decide whether the decision is applicable for the current case.
+  - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
+  - Check `apply-to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
+  - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
+- Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, and updates of Policies, but the Policy document remains the source of truth.
+- **Policy Id:** [scope]-[type]-policy-[number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
+  - Types in IDs: `adr-policy`, `bdr-policy`, `edr-policy`
+  - Define the next number of a Policy by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted Policies and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
+- 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.
+- 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.
+  - **Within-scope conflicts:** Policies within the same type+scope must not conflict. If two Policies appear to conflict, one should be updated, removed, or the conflict resolved through a new Policy.
+- When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
+- Never use emojis in contents.
+- Always use file names with 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/`.
+- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
+- 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
+  - Exceptions can reach under 2600 words (templates, more elaborate decision implementations etc)
+- ALWAYS use `_local` scope if the user doesn't explicitly indicate a specific scope while creating a policy or skill.
+
+**Policy template**
+
+All Policies MUST follow this template
+
+```markdown
+---
+name: [scope]-[type]-policy-[number]-[short-title]
+description: [What this decision is about and when to use it]
+apply-to: [Optional. Contexts this decision applies to, under 40 words]
+valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+license: [Optional. SPDX license expression]
+metadata:
+  [optional-key]: [optional-value]
+---
+
+# [scope]-[type]-policy-[number]: [Short Title]
+
+## Context and Problem Statement
+
+[Describe the context, background, or need that led to this decision.
+What is the problem we are trying to solve? Who is being impacted? (<40 words)
+
+Question: In the end, state explicitly the question that needs to be answered. E.g: "Which platform should I use when implementing an AI agent?"]
+
+## Decision Outcome
+
+**[Chosen Option Title]**
+[Very short description of what is the decision, aligned with the titles on the Considered Options section]
+
+[Short description of implementation details for the chosen path]
+
+### Details
+
+[Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
+
+## Considered Options 
+[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision and have a backing research document]
+
+[Related research, if any]
+- [Research document title](researches/001-example.md) - Brief description of what it informed
+
+## Conflicts
+
+[If this Policy has conflicts with other scopes, this section is MANDATORY and needs to have an explanation why the conflict is accepted]
+
+* Conflict with [Policy id] (e.g.: business-x-adr-policy-001)
+  * Summary: Brief description of the conflict
+  * Reason to accept: Brief description of why it was decided to accept this conflict, possibly overriding or diverging from the other decision/scopes
+
+## References
+
+[optional section]
+[useful links related to this implementation]
+[links to the discussion (PRs, meetings etc)]
+[links to related skills]
+```
+
+**Examples:**
+- Frontmatter examples:
+  - `valid-from: 2026-03-01`
+  - `apply-to: JavaScript projects`
+
+**Policy ID Examples:**
+- `business-x-adr-policy-001` (not `ADR-business-x-001` or `business-x-adr-1`)
+- `business-x-edr-policy-042` (not `EDR-BUSINESS-X-042`)
+- `business-x-bdr-policy-007`
+
+## References
+
+- [_core-adr-policy-001 - Policies core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
+- [001-review skill](skills/001-review/SKILL.md) - Skill for reviewing code changes against Policies
+- [002-write-policy skill](skills/002-write-policy/SKILL.md) - Skill for creating a new Policy following this standard
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-006 - Research standards](006-research-standards.md)
+- [_core-adr-policy-008 - Policy standards - structured](008-xdr-standards-structured.md) - Extension for Policies that expose individually referenceable rules

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

@@ -1,9 +1,9 @@
 ---
-name: _core-adr-003-skill-standards
-description: Defines skill package standards including structure, SKILL.md format, and co-location with XDRs. Use when creating or reviewing skills.
+name: _core-adr-policy-003-skill-standards
+description: Defines skill package standards including structure, SKILL.md format, and co-location with XDRS packages. Use when creating or reviewing skills.
 ---
 
-# _core-adr-003: Skill standards
+# _core-adr-policy-003: Skill standards
 
 ## Context and Problem Statement
 
@@ -15,9 +15,9 @@ How should skills be authored, structured, and organized within a project so tha
 
 ## Decision Outcome
 
-**agentskills-compatible skill packages, co-located with XDRs**
+**agentskills-compatible skill packages, co-located with XDRS**
 
-Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDR subject folder under a `skills/` sub-directory. Each skill occupies its own numbered package folder, mirroring the XDR numbering convention.
+Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDRS subject folder under a `skills/` sub-directory. Each skill occupies its own numbered package folder, mirroring the XDRS numbering convention.
 
 A skill may target a human operator, an AI agent, or both. Instructions must be written imperatively and at a level of detail that either a person or an agent can follow without additional context. This design allows a skill to start as a human-only procedure and evolve — incrementally — toward partial or full AI automation without restructuring the document.
 
@@ -31,20 +31,20 @@ Skills exist on a spectrum from fully manual (human-only) to fully automated (ag
 
 Write instructions so that each step is unambiguous and self-contained. Avoid implicit knowledge that only a human or only an AI would have.
 
-**Relation with XDRs, Research, and Articles**
-Skills are procedures, XDRs are guardrails and decisions, Research documents capture the explored option space and findings behind a decision, and Articles are synthetic views that combine information from multiple artifacts.
-Always create links back and forth between skills <-> XDRs when the relationship is direct, and link to related Research or Articles when they provide important context.
+**Relation with Policies, Research, and Articles**
+Skills are procedures, Policies are guardrails and decisions, Research documents capture the explored option space and findings behind a decision, and Articles are synthetic views that combine information from multiple artifacts.
+Always create links back and forth between skills <-> Policies when the relationship is direct, and link to related Research or Articles when they provide important context.
 - Skills are task-based artifacts. They should have a clear starting trigger, an expected end result, and enough detail for a human or agent to verify that the task finished correctly.
-- A skill is not policy by itself. If following a skill is mandatory, that obligation must come from an XDR or another explicit policy that references the skill.
-- When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope XDRs as current requirements.
-- Skills and XDRs have a many-to-many relationship: one skill may operationalize multiple XDRs, and one XDR may be executed through multiple skills in different contexts.
+- A skill is not policy by itself. If following a skill is mandatory, that obligation must come from a Policy or another explicit policy that references the skill.
+- When a skill reads, operationalizes, or enforces Policies, it MUST evaluate the Policy metadata first. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope Policies as current requirements.
+- Skills and Policies have a many-to-many relationship: one skill may operationalize multiple Policies, and one Policy may be executed through multiple skills in different contexts.
 
-Place a skill under the XDR type that matches the nature of the activity the skill performs:
+Place a skill under the XDRS type that matches the nature of the activity the skill performs:
 - **EDR skills** - engineering workflows, tool usage, coding procedures, implementation how-tos (e.g. how to design a webpage, how to run a CI pipeline, how to debug a service)
 - **ADR skills** - architectural evaluation, pattern compliance checks, technology selection guidance (e.g. how to review an architecture diagram, how to assess API design)
 - **BDR skills** - business process execution, market analysis, operations procedures, business rules
 
-The `[subject]` component in the folder path MUST be one of the allowed subjects for the chosen type. The required list of allowed subjects per type is defined in `_core-adr-001`.
+The `[subject]` component in the folder path MUST be one of the allowed subjects for the chosen type. The required list of allowed subjects per type is defined in `_core-adr-policy-001`.
 
 Quick test:
 - "Is the skill about *how to implement or operate* something?" → EDR.
@@ -81,7 +81,7 @@ Examples:
 
 ```
 ---
-name: 001-skill-name      # required: must match the parent directory name exactly; max 64 chars
+name: [scope]-[type]-skill-[number]-[skill-name]      # required: full identifier including scope and type; max 64 chars
 description: >            # required: what the skill does AND when to activate it; max 1024 chars
   Concise explanation of the skill and the situations in which an agent should load it.
 license: <license>        # optional
@@ -110,7 +110,8 @@ Known gotchas and how to handle them.
 ```
 
 Rules:
-- The `name` field must match the parent directory name exactly (e.g., directory `001-code-review` uses `name: 001-code-review`). This preserves agentskills spec compliance while encoding the ordering number.
+- The `name` field MUST use the format `[scope]-[type]-skill-[number]-[skill-name]` (e.g., `_core-adr-skill-001-code-review`). This aligns skill identifiers with the Policy document identifier format, making every XDRS element consistently identifiable by scope and type.
+- The directory name MUST follow the format `[number]-[skill-name]` (e.g., `001-code-review`), which keeps the filesystem hierarchy simple while the `name:` field carries the full identifier.
 - `## 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.
@@ -131,16 +132,16 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
 
 ## Considered Options
 
-* (REJECTED) **Top-level `skills/` directory separate from XDRs** - Decouples skills from the decisions that govern them.
-  * Reason: Breaks the natural association between a decision (XDR) and the skill that implements it; makes navigation harder.
-* (CHOSEN) **agentskills-compatible packages co-located with XDRs** - Standardized format with scoped discovery and clear ownership.
-  * Reason: Reuses proven agentskills tooling, aligns with the existing XDR scope/subject hierarchy, and keeps skills close to the decisions they implement.
+* (REJECTED) **Top-level `skills/` directory separate from XDRS** - Decouples skills from the decisions that govern them.
+  * Reason: Breaks the natural association between a decision (Policy) and the skill that implements it; makes navigation harder.
+* (CHOSEN) **agentskills-compatible packages co-located with XDRS** - Standardized format with scoped discovery and clear ownership.
+  * Reason: Reuses proven agentskills tooling, aligns with the existing XDRS scope/subject hierarchy, and keeps skills close to the decisions they implement.
 
 ## References
 
 - [agentskills specification](https://agentskills.io/specification)
 - [agentskills/agentskills repository](https://github.com/agentskills/agentskills)
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
-- [_core-adr-001 - XDRs core](001-xdrs-core.md)
-- [_core-adr-004 - Article standards](004-article-standards.md)
-- [_core-adr-006 - Research standards](006-research-standards.md)
+- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md)
+- [_core-adr-policy-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-006 - Research standards](006-research-standards.md)

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

@@ -1,38 +1,38 @@
 ---
-name: _core-adr-004-article-standards
-description: Defines article document standards for synthesizing and linking XDRs, research, and skills. Use when creating or reviewing articles.
+name: _core-adr-policy-004-article-standards
+description: Defines article document standards for synthesizing and linking Policies, research, and skills. Use when creating or reviewing articles.
 ---
 
-# _core-adr-004: Article standards
+# _core-adr-policy-004: Article standards
 
 ## Context and Problem Statement
 
-As the number of XDRs, Research documents, and Skills grows, navigating and understanding related decisions across subjects and types becomes difficult. Without a structured format for synthetic documentation, teams create ad-hoc documents that drift from the actual decisions and supporting evidence over time.
+As the number of Policies, Research documents, and Skills grows, navigating and understanding related decisions across subjects and types becomes difficult. Without a structured format for synthetic documentation, teams create ad-hoc documents that drift from the actual decisions and supporting evidence over time.
 
-How should articles be structured and organized to provide useful views over XDRs, Research, and Skills without replacing them as the source of truth?
+How should articles be structured and organized to provide useful views over Policies, Research, and Skills without replacing them as the source of truth?
 
 ## Decision Outcome
 
-**Subject-level synthetic documents co-located with XDRs**
+**Subject-level synthetic documents co-located with Policies**
 
-Articles are Markdown documents placed inside a subject folder alongside decision records. Placing articles within a subject keeps them close to the decisions, research, and skills they reference.
+Articles are Markdown documents placed inside a subject folder alongside policies. Placing articles within a subject keeps them close to the decisions, research, and skills they reference.
 
 ### Details
 
-- Articles are views, not decisions. They summarize and synthesize content from XDRs, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Decision Record, the Decision Record takes precedence.
-- Articles are not limited to synthesizing XDRs. They may also document application features, APIs, general project information, reference tables, diagrams, FAQs and other elements useful to their intended audience.
-- Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
+- Articles are views, not decisions. They summarize and synthesize content from Policies, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Policy, the Policy takes precedence.
+- Articles are not limited to synthesizing Policies. They may also document application features, APIs, general project information, reference tables, diagrams, FAQs and other elements useful to their intended audience.
+- Articles must reference the Policies, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
 - Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
 - In more complex cases, an article may be an index of links to other articles, grouping related documentation into a single entry point that guides readers across a set of related topics.
-- 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 XDRs as current rules for the discussed context.
-- Articles must remain consistent with the XDRs, 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-001`. If an article spans more than one subject, place it in `principles`.
+- 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 (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files.
 - Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Always use lowercase file names.
 - Never use emojis in article content.
-- Articles should be kept under 5000 words. Move or point to detailed contents referenced in XDRs decisions, researches, plans or skills.
+- Articles should be kept under 5000 words. Move or point to detailed contents referenced in Policy decisions, researches, plans or skills.
 
 **Folder layout**
 
@@ -62,7 +62,7 @@ Examples:
 All articles MUST follow this template:
 
 ```markdown
-# [scope]-article-[number]: [Short Title]
+# [scope]-[type]-article-[number]: [Short Title]
 
 ## Overview
 
@@ -70,24 +70,24 @@ All articles MUST follow this template:
 
 ## Content
 
-[Synthetic text combining and explaining the topic. Use links to Decision Records, Research, and Skills
+[Synthetic text combining and explaining the topic. Use links to Policies, Research, and Skills
 when referencing an information from those documents.]
 
 ## References
 
-- [XDR id or Skill name](relative/path/to/file.md) - Brief description of relevance
+- [Policy id or Skill name](relative/path/to/file.md) - Brief description of relevance
 ```
 
 ## Considered Options
 
 * (REJECTED) **Separate documentation repository** - Removes drift risk but decouples docs from decisions.
-  * Reason: Increases maintenance burden and makes it easy for articles to go stale relative to the XDRs they reference.
-* (CHOSEN) **Subject-level articles folder co-located with XDRs** - Keeps articles alongside the decision records and skills they reference, with `principles` as the fallback for cross-subject articles.
-  * Reason: Easy to discover, consistent with where skills are placed, and clearly distinct from the decision records themselves.
+  * Reason: Increases maintenance burden and makes it easy for articles to go stale relative to the Policies they reference.
+* (CHOSEN) **Subject-level articles folder co-located with Policies** - Keeps articles alongside the policies and skills they reference, with `principles` as the fallback for cross-subject articles.
+  * Reason: Easy to discover, consistent with where skills are placed, and clearly distinct from the policies themselves.
 
 ## References
 
-- [_core-adr-001 - XDRs core](001-xdrs-core.md)
-- [_core-adr-003 - Skill standards](003-skill-standards.md)
-- [_core-adr-006 - Research standards](006-research-standards.md)
+- [_core-adr-policy-001 - Policies core](001-xdrs-core.md)
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-policy-006 - Research standards](006-research-standards.md)
 - [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article