xdrs-core 0.24.0 → 0.25.0

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

@@ -1,37 +1,37 @@
 ---
-name: _core-adr-006-research-standards
-description: Defines research document standards including IMRAD structure and traceability to XDRs. Use when creating or reviewing research documents.
+name: _core-adr-policy-006-research-standards
+description: Defines research document standards including IMRAD structure and traceability to Policies. Use when creating or reviewing research documents.
 ---
 
-# _core-adr-006: Research standards
+# _core-adr-policy-006: Research standards
 
 ## Context and Problem Statement
 
-Teams often need more space than an XDR allows to evaluate constraints, explore options, and record findings before or after a decision changes. When that material is scattered across PR comments, docs, and chat, the reasoning behind a decision becomes hard to recover or update.
+Teams often need more space than a Policy allows to evaluate constraints, explore options, and record findings before or after a decision changes. When that material is scattered across PR comments, docs, and chat, the reasoning behind a decision becomes hard to recover or update.
 
-Question: How should research documents be structured and organized so they communicate an investigated problem, evidence, and conclusions clearly, while remaining traceable from related XDRs?
+Question: How should research documents be structured and organized so they communicate an investigated problem, evidence, and conclusions clearly, while remaining traceable from related Policies?
 
 ## Decision Outcome
 
-**IMRAD-based subject-level research documents co-located with XDRs**
+**IMRAD-based subject-level research documents co-located with XDRS**
 
-Research documents are Markdown files placed inside a subject folder alongside decision records. They use an IMRAD-inspired paper structure adapted to company needs so teams can communicate investigated problems, methods, findings, and conclusions clearly, combine experienced professional judgment with good-enough evidence, preserve reproducibility where it matters, and revisit the work when technology, constraints, or facts change.
+Research documents are Markdown files placed inside a subject folder alongside policies. They use an IMRAD-inspired paper structure adapted to company needs so teams can communicate investigated problems, methods, findings, and conclusions clearly, combine experienced professional judgment with good-enough evidence, preserve reproducibility where it matters, and revisit the work when technology, constraints, or facts change.
 
 ### Details
 
-- Research is evidence and exploration, not the adopted decision. When a research document and an XDR disagree, the XDR takes precedence.
+- Research is evidence and exploration, not the adopted decision. When a research document and a Policy disagree, the Policy takes precedence.
 - `Research` is the artifact name. `researches/` is only the folder name used alongside `skills/` and `articles/`.
 - Research documents MUST live under `researches/` inside the relevant subject folder:
   `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
-- The `[subject]` component 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 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`.
 - Research documents SHOULD stay focused on one investigated problem, comparison, or hypothesis.
 - Research documents MUST state clearly what problem or question is being investigated, the relevant system or domain context, and why the subject matters in practice.
 - Research documents MUST follow this section order: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
 - Research uses a company-adapted IMRAD structure. It MAY include informed professional judgment and experience-based observations, but claims that affect the conclusion MUST have enough evidence to be teachable, reviewable, and useful to other colleagues.
 - Research does not require full academic statistical rigor. Use good-enough evidence that supports the conclusion without demanding exhaustive proof.
-- Research documents MUST read as standalone technical papers for readers who do not know the XDR process.
+- Research documents MUST read as standalone technical papers for readers who do not know the XDRS process.
 - Mentions of future ADRs, decision lifecycle, repository process, or artifact management SHOULD be avoided in the body unless they are materially necessary to understand the research question.
-- Traceability to related XDRs, skills, articles, discussions, and external sources SHOULD live primarily in `## References` and surrounding indexes rather than in the body narrative.
+- Traceability to related Policies, skills, articles, discussions, and external sources SHOULD live primarily in `## References` and surrounding indexes rather than in the body narrative.
 - 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.
@@ -45,13 +45,13 @@ Research documents are Markdown files placed inside a subject folder alongside d
 - In general, research SHOULD roughly follow the proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
 - Be strict about the goal of each section. Avoid duplicating the same material across sections and prefer clarity over rhetorical flourishes.
 - Research documents SHOULD stay under 5000 words total. They MAY exceed that only when the `## Introduction` explicitly states that the study will be lengthy because a very detailed analysis is required.
-- Research documents SHOULD link in `## References` to the XDRs, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
+- 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 XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
+- 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 (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files.
 - Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Research file names MUST be lowercase. Never use emojis.
-- A research document MAY exist before the related XDR is written, or remain after the XDR changes, as long as its status and references stay clear.
+- 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.
 
 **Folder layout**
 
@@ -116,22 +116,22 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 
 [A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
 
-- [Related XDR or artifact](relative/path.md) - Why it matters
-- [Another related XDR if this research informed multiple decisions](relative/path.md) - Why it matters
+- [Related Policy or artifact](relative/path.md) - Why it matters
+- [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters
 ```
 
 ## Considered Options
 
 - Related research: `001-research-and-decision-lifecycle` (workspace-local research)
 
-* (REJECTED) **Inline long-form analysis inside the XDR** - Put all research and decision text in one file.
-  * Reason: Makes XDRs too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.
-* (CHOSEN) **IMRAD-based subject-level research beside XDRs** - Keep exploratory material beside the decisions, skills, and articles it informs, using an IMRAD-inspired structure adapted to company work.
-  * Reason: Preserves lifecycle context, keeps the XDR concise, gives readers a predictable structure, and raises evidence quality without demanding full academic rigor.
+* (REJECTED) **Inline long-form analysis inside the Policy** - Put all research and decision text in one file.
+  * Reason: Makes Policies too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.
+* (CHOSEN) **IMRAD-based subject-level research beside XDRS** - Keep exploratory material beside the decisions, skills, and articles it informs, using an IMRAD-inspired structure adapted to company work.
+  * Reason: Preserves lifecycle context, keeps the Policy concise, gives readers a predictable structure, and raises evidence quality without demanding full academic rigor.
 
 ## References
 
-- [_core-adr-001 - XDRs core](001-xdrs-core.md)
-- [_core-adr-003 - Skill standards](003-skill-standards.md)
-- [_core-adr-004 - Article standards](004-article-standards.md)
+- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md)
+- [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
+- [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [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

@@ -1,9 +1,9 @@
 ---
-name: _core-adr-007-plan-standards
+name: _core-adr-policy-007-plan-standards
 description: Defines plan document standards for describing problems, solutions, and activities. Use when creating or reviewing plans.
 ---
 
-# _core-adr-007: Plan standards
+# _core-adr-policy-007: Plan standards
 
 ## Context and Problem Statement
 
@@ -13,21 +13,21 @@ How should plans be structured and organized so they provide clear guidance for
 
 ## Decision Outcome
 
-**Subject-level ephemeral plan documents co-located with XDRs**
+**Subject-level ephemeral plan documents co-located with Policies**
 
-Plans are Markdown documents placed inside a subject folder alongside decision records. They describe a problem, a proposed solution, and the approach to solve it. Plans have a clear start and end and a well-defined scope.
+Plans are Markdown documents placed inside a subject folder alongside policies. They describe a problem, a proposed solution, and the approach to solve it. Plans have a clear start and end and a well-defined scope.
 
 ### Details
 
 - Plans describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
-- Plans are NOT the source of truth. When a plan and an XDR disagree, the XDR takes precedence.
+- Plans are NOT the source of truth. When a plan and a Policy disagree, the Policy takes precedence.
 - Plans are ephemeral. They MUST be deleted after full implementation. The lasting outputs of a plan are actual actions or Decisions, Skills, Articles, Research documents, and other artifacts that result from execution.
 - Plans may be used to implement a certain Decision. They may also use Research documents to help with the planning process. Articles may be written on top of a plan to give more context and connect more details present in other decisions and research to people involved in the plan.
 - During the implementation of a plan, new Decisions, Articles, Skills, Research documents, and even other Plans may be created. Always link all related elements to each other.
 - A plan can be high level, describing only one milestone, or more complex, describing a WBS (work breakdown structure) along with owners, multiple milestones in a tactical sequence, and checklists to verify completeness. Actual tasks performed by actors should normally be tracked in specialized software such as GitHub or Azure DevOps.
 - The total time to deliver a plan should not be more than 2 years. If more time is needed, create a new plan later with what was learned.
 - Plans MUST live under `plans/` inside the relevant subject folder: `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
-- The `[subject]` component 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 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`.
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - Always use lowercase file names.
 - Never use emojis in plan content.
@@ -121,19 +121,19 @@ Due date: YYYY-MM-DD
 
 ## References
 
-- [Related XDR or artifact](relative/path.md) - Brief description of relevance
+- [Related Policy or artifact](relative/path.md) - Brief description of relevance
 ```
 
 ## Considered Options
 
-* (REJECTED) **Inline planning in XDRs** — Embed planning details inside decision records.
-  * Reason: Plans are ephemeral execution documents while XDRs are lasting decisions. Mixing them bloats XDRs and creates confusion about what to delete after execution.
-* (CHOSEN) **Subject-level plans folder co-located with XDRs** — Keeps plans alongside the decisions they implement, with clear lifecycle expectations.
+* (REJECTED) **Inline planning in Policies** — Embed planning details inside policies.
+  * Reason: Plans are ephemeral execution documents while Policies are lasting decisions. Mixing them bloats Policies and creates confusion about what to delete after execution.
+* (CHOSEN) **Subject-level plans folder co-located with Policies** — Keeps plans alongside the decisions they implement, with clear lifecycle expectations.
   * Reason: Consistent with how skills, articles, and research are organized. The explicit deletion requirement after implementation keeps the document base clean.
 
 ## References
 
-- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
-- [_core-adr-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
-- [_core-adr-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
+- [_core-adr-policy-001 - Policies core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
+- [_core-adr-policy-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
+- [_core-adr-policy-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
 - [006-write-plan skill](skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan

package/.xdrs/_core/adrs/principles/008-xdr-standards-structured.md

@@ -1,25 +1,25 @@
 ---
-name: _core-adr-008-xdr-standards-structured
-description: Extends xdr-standards with a numbered rule format for XDR documents that define strong policies or rules, or need individually referenceable items. Use when an XDR must expose explicit rule blocks that other documents or skills may cite by identifier.
+name: _core-adr-policy-008-policy-standards-structured
+description: Extends policy-standards with a numbered rule format for Policy documents that define strong policies or rules, or need individually referenceable items. Use when a Policy must expose explicit rule blocks that other documents or skills may cite by identifier.
 ---
 
-# _core-adr-008: XDR standards - structured
+# _core-adr-policy-008: Policy standards - structured
 
 ## Context and Problem Statement
 
-Some XDR documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Details" are fragile and ambiguous.
+Some Policy documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Details" are fragile and ambiguous.
 
-Question: How should an XDR document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
+Question: How should a Policy document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
 
 ## Decision Outcome
 
 **Numbered rule blocks inside Details with a canonical citation syntax**
 
-When an XDR document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
+When a Policy document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
 
 ### Details
 
-Use this format when the decision defines strong rules or policies that must be stated explicitly as stable rule blocks, or when there is a clear need for external documents, skills, or agents to reference specific items inside an XDR without duplicating the full policy text. Standard XDRs that do not define strong rule sets and do not need item-level citation should follow `_core-adr-002-xdr-standards` without adding numbered rule headings.
+Use this format when the decision defines strong rules or policies that must be stated explicitly as stable rule blocks, or when there is a clear need for external documents, skills, or agents to reference specific items inside a Policy without duplicating the full policy text. Standard Policies that do not define strong rule sets and do not need item-level citation should follow `_core-adr-policy-002-policy-standards` without adding numbered rule headings.
 
 #### Rule block format
 
@@ -27,12 +27,12 @@ Each numbered rule must be written as:
 
 ```markdown
 #### [NN]-[short-descriptive-title-in-kebab-case]
-[Body using mandatory or advisory language as defined in _core-adr-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
+[Body using mandatory or advisory language as defined in _core-adr-policy-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
 ```
 
 Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers must be unique within the document and must never be reused after a rule is removed.
 
-Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-001`:
+Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-policy-001`:
 
 - Mandatory: "must", "always", "never", "required", "mandatory"
 - Advisory: "should", "recommended", "advised", "preferably", "possibly", "optionally"
@@ -42,19 +42,19 @@ Rule bodies must use the mandatory or advisory language terms defined in `_core-
 When another document or skill cites a specific rule, it must use the following dot-notation:
 
 ```
-[xdr-name].[NN-short-descriptive-title-in-kebab-case]
+policy-name.NN-short-descriptive-title-in-kebab-case
 ```
 
 Examples:
 
-- `_core-adr-008-xdr-standards-structured.[01-use-numbered-rules-for-strong-or-referenceable-policies]`
-- `_local-bdr-003-data-retention-policy.[02-purge-schedule-for-pii]`
+- `_core-adr-policy-008-policy-standards-structured.[01-use-numbered-rules-for-strong-or-referenceable-policies]`
+- `_local-bdr-policy-003-data-retention-policy.[02-purge-schedule-for-pii]`
 
-The `xdr-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier after the dot must match the heading text exactly, including the two-digit prefix and kebab-case title.
+The `policy-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier after the dot must match the heading text exactly, including the two-digit prefix and kebab-case title.
 
 #### 01-use-numbered-rules-for-strong-or-referenceable-policies
 
-Numbered rule blocks must be added to an XDR when the decision defines strong rules or policies that must be stated explicitly as stable items, or when there is a clear need for other documents, skills, or agents to cite individual rules by identifier. Adding numbered rules only for cosmetic organization is not recommended. Standard XDR documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-002-xdr-standards` without this structured format.
+Numbered rule blocks must be added to a Policy when the decision defines strong rules or policies that must be stated explicitly as stable items, or when there is a clear need for other documents, skills, or agents to cite individual rules by identifier. Adding numbered rules only for cosmetic organization is not recommended. Standard Policy documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-policy-002-policy-standards` without this structured format.
 
 #### 02-rule-numbering-must-be-stable
 
@@ -62,20 +62,20 @@ Rule numbers must never be reused within the same document. When a rule is remov
 
 #### 03-rule-body-must-use-normative-language
 
-Every rule body must contain at least one mandatory or advisory language term as defined in `_core-adr-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
+Every rule body must contain at least one mandatory or advisory language term as defined in `_core-adr-policy-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
 
 #### 04-citations-must-use-exact-identifiers
 
-Documents and skills that cite a rule must use the exact dot-notation form: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`. Prose paraphrases such as "see rule 3" or "the third rule in that XDR" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
+Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.NN-short-descriptive-title-in-kebab-case`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
 
 ## Considered Options
 
 * (REJECTED) **Free-form prose rules with section anchors** — Use markdown heading anchors as citation targets.
   * Reason: Anchors are fragile across editors, rendering tools, and refactors. They do not enforce a stable numbering contract and break silently when headings are reworded.
 * (CHOSEN) **Numbered rule blocks inside Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
-  * Reason: Minimal addition to the existing XDR template, stable identifiers independent of heading text, and fully compatible with `_core-adr-002-xdr-standards`.
+  * Reason: Minimal addition to the existing Policy template, stable identifiers independent of heading text, and fully compatible with `_core-adr-policy-002-policy-standards`.
 
 ## References
 
-- [_core-adr-001 - XDRs core](001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](002-xdr-standards.md)
+- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md)
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md)

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

@@ -1,15 +1,15 @@
 ---
-name: _core-adr-009-presentation-standards
-description: Defines how Marp slide presentations are structured, named, placed, and linked within XDR projects. Use when creating, reviewing, or linting slide decks that support XDR documents.
+name: _core-adr-policy-009-presentation-standards
+description: Defines how Marp slide presentations are structured, named, placed, and linked within XDRS projects. Use when creating, reviewing, or linting slide decks that support XDRS documents.
 ---
 
-# _core-adr-009: Presentation standards
+# _core-adr-policy-009: Presentation standards
 
 ## Context and Problem Statement
 
-Teams often need slide presentations to communicate decisions, research findings, plans, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the decision records they support.
+Teams often need slide presentations to communicate decisions, research findings, plans, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the policies they support.
 
-How should slide presentations be structured, placed, and maintained within the XDR framework so they remain consistent, discoverable, and always traceable to the documents they support?
+How should slide presentations be structured, placed, and maintained within the XDRS framework so they remain consistent, discoverable, and always traceable to the documents they support?
 
 ## Decision Outcome
 
@@ -19,7 +19,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 
 ### Details
 
-- Slides are supporting media for XDR documents. They must never exist as standalone artifacts without a parent decision, research, article, or plan.
+- Slides are supporting media for XDRS documents. They must never exist as standalone artifacts without a parent decision, research, article, or plan.
 - Slides must use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
   ```
   ---
@@ -27,7 +27,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
   ---
   ```
   Additional Marp configuration keys (e.g. `theme`, `paginate`, `header`, `footer`) may be added when needed, but `marp: true` is always required as the first frontmatter key.
-- Slide files must be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-001`.
+- Slide files must be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-policy-001`.
 - The parent document must always contain a link to the slide file. The slide file must always contain a link back to the parent document at the end of the presentation. This bidirectional linking is mandatory.
 - Slide files must use the same base name as the parent file, suffixed with `-slides`. When multiple slide sets exist for the same parent, append a context indicator after `-slides` (e.g. `-slides-overview`, `-slides-executive`).
   - Example: parent `003-naming-conventions.md` produces `003-naming-conventions-slides.md` or `003-naming-conventions-slides-overview.md`.
@@ -39,14 +39,14 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 - 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.
 - Always identify the target audience (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`).
 - Keep presentations under 30 slides. Create separate slide sets for different views or audiences when needed.
-- Slides never replace decision records or related document contents. When the underlying document changes, the associated slides must be reviewed and updated to stay consistent.
+- Slides never replace policies or related document contents. When the underlying document changes, the associated slides must be reviewed and updated to stay consistent.
 - Never use emojis in slide content.
 - Always use lowercase file names.
 
 ## References
 
-- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework structure and `.assets/` placement rules
-- [_core-adr-002 - XDR standards](002-xdr-standards.md) - XDR document writing rules
-- [_core-adr-004 - Article standards](004-article-standards.md) - Article standards for multi-document views
+- [_core-adr-policy-001 - XDRs core](001-xdrs-core.md) - Framework structure and `.assets/` placement rules
+- [_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
 - [Marp](https://marp.app/) - Markdown Presentation Ecosystem

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -1,39 +1,50 @@
-# _core-article-001: XDRs Overview
+# _core-article-001: XDRS Overview
 
 ## Overview
 
-This article introduces XDRs (Decision Records), explains their purpose and design, and guides
+This article introduces XDRS, explains its purpose and design, and guides
 teams through adopting, extending, and distributing them. It is an entry point for anyone new to
-the framework and links out to the authoritative Decision Records for full details.
+the framework and links out to the authoritative Policy documents for full details.
 
 ## Content
 
 ### What the central elements are
 
-The XDR framework is built around a small set of artifact types that play different roles in the
+The XDRS framework is built around a small set of artifact types that play different roles in the
 same decision system.
 
-- **Decision Records (XDRs)** are the authoritative decisions. They answer a concrete question and
+A standard Decision Record normally combines several concerns in the same document: a reason
+(why, options considered), a policy (rules, core decision), a plan (consequences, implementation
+approach), a how-to (step-by-step procedure), and a view on a topic. The XDRS framework separates
+these concerns into different document types: Policies as the source of truth, 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
+without starting from a raw Decision Record.
+
+- **Policies** are the authoritative decisions. They answer a concrete question and
   record the adopted direction. They are the central policy artifact of the framework for the
-  scope and topic they cover. Three decision record types exist: **ADR** for architectural and
+  scope and topic they cover. Three policy types exist: **ADR** for architectural and
   technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
-  implementation decisions. See [_core-adr-001](../001-xdrs-core.md).
+  implementation decisions. See [_core-adr-policy-001](../001-xdrs-core.md).
 - **Research** captures exploration before or around a decision: constraints, findings, options,
   pros, and cons. Research supports elaboration, discussion, and updates,
   but it is not the final rule. A single Research document may inform multiple downstream ADRs,
-  BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
-  [_core-adr-006](../006-research-standards.md).
+  BDRs, or EDRs. If Research and a Policy disagree, the Policy wins. See
+  [_core-adr-policy-006](../006-research-standards.md).
 - **Skills** describe how to execute work under the constraints of the decisions. They add the
-  procedural detail that XDRs intentionally avoid. A Skill may be used by a human, an AI agent, or
+  procedural detail that Policies intentionally avoid. A Skill may be used by a human, an AI agent, or
   both. Skills are task-based, should end in a verifiable outcome, and are only mandatory when a
-  policy such as an XDR makes them mandatory. See [_core-adr-003](../003-skill-standards.md).
-- **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
+  policy such as a Policy document makes them mandatory. See [_core-adr-policy-003](../003-skill-standards.md).
+- **Articles** are synthetic views, like this one. They explain a topic across multiple Policies,
   Research documents, and Skills, helping readers understand the system without making new
-  decisions. See [_core-adr-004](../004-article-standards.md).
+  decisions. See [_core-adr-policy-004](../004-article-standards.md).
 - **Plans** describe a problem, a proposed solution, and the approach and activities needed to
   solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
-  must be deleted after full implementation, with lasting outputs captured as Decisions, Skills,
-  Articles, or other artifacts. See [_core-adr-007](../007-plan-standards.md).
+  must be deleted after full implementation, with lasting outputs captured as Policies, Skills,
+  Articles, or other artifacts. See [_core-adr-policy-007](../007-plan-standards.md).
 - **Indexes and folder structure** are the discovery layer. They do not make decisions by
   themselves, but they determine how people and agents find the right artifacts, how scopes
   override one another, and how a large set of decisions remains navigable.
@@ -42,7 +53,7 @@ same decision system.
 
 The easiest way to distinguish the central elements is by asking what job each one performs.
 
-- **XDR**: "What did we decide?"
+- **Policy**: "What did we decide?"
 - **Research**: "What did we learn while evaluating options?"
 - **Skill**: "How do we carry out work under this decision?"
 - **Article**: "How do these artifacts fit together for a reader?"
@@ -52,13 +63,13 @@ The easiest way to distinguish the central elements is by asking what job each o
 This separation matters because mixing these jobs into one file makes the system harder to search,
 harder to update, and harder for agents to apply correctly.
 
-### How to decide whether an XDR should be used
+### How to decide whether a Policy should be used
 
-Before treating an XDR as a rule for the current case, check its metadata first. All documents present in the collection are considered active — if a document exists, it is current.
+Before treating a Policy as a rule for the current case, check its metadata first. All documents present in the collection are considered active — if a document exists, it is current.
 
 - **Valid first**: if present, the convergence date indicates when full adoption is expected. New implementations SHOULD adopt the decision immediately; compliance is not enforced during reviews until the date.
 - **Applied to second**: if present, the current codebase, workflow, system, or audience must fit that scope.
-- **Decision text last**: the XDR's own context and implementation details still determine the final boundaries and exceptions.
+- **Decision text last**: the Policy's own context and implementation details still determine the final boundaries and exceptions.
 - **Then enforce**: only decisions that pass those checks should be used as active requirements. The rest may still be useful context.
 
 Documents that are no longer relevant should be removed from the collection. Historical versions are available via versioned packages or git history.
@@ -70,21 +81,21 @@ The framework is easiest to understand as a lifecycle rather than a static folde
 1. **Explore** — A team starts with a problem, constraints, and uncertainty. Research is the best
   place to compare options, record findings, and keep tradeoffs visible. That same research may
   later support more than one decision record.
-2. **Decide** — Once a direction is chosen, an XDR captures the final answer in concise,
-  authoritative form. The XDR should make clear when the decision applies, and may link back to
+2. **Decide** — Once a direction is chosen, a Policy captures the final answer in concise,
+  authoritative form. The Policy should make clear when the decision applies, and may link back to
   the Research that informed its considered options.
 3. **Execute** — If the decision affects daily work, a Skill explains how to apply it in practice.
-   The Skill operationalizes the decision without turning the XDR into a procedure manual.
-4. **Explain** — When the topic becomes broad or cross-cutting, an Article synthesizes the XDR,
+   The Skill operationalizes the decision without turning the Policy into a procedure manual.
+4. **Explain** — When the topic becomes broad or cross-cutting, an Article synthesizes the Policy,
    Research, and Skills into a navigable explanation for humans and agents.
 5. **Distribute and override** — Canonical indexes and scope ordering make the artifacts
    discoverable across teams. Broader scopes can be reused, and more specific scopes can extend or
    override them.
 
-This gives XDRs a timeline feel:
+This gives Policies a timeline feel:
 
 - Research usually appears before or around a decision.
-- The XDR marks the adopted outcome.
+- The Policy marks the adopted outcome.
 - Skills appear when the decision must be executed repeatedly.
 - Articles appear when the ecosystem around the decision needs explanation or onboarding support.
 
@@ -121,8 +132,8 @@ guidance, and the explanatory overview close together without collapsing them in
 ### Why this separation works
 
 - **Small focused files** keep decisions readable and agent-friendly.
-- **Research beside the XDR** preserves why options were accepted or rejected.
-- **Skills beside the XDR** reduce drift between decisions and execution.
+- **Research beside the Policy** preserves why options were accepted or rejected.
+- **Skills beside the Policy** reduce drift between decisions and execution.
 - **Articles above the artifacts** help readers understand the whole topic without replacing the
   source of truth.
 - **Indexes and scopes** let the framework scale across teams while preserving override behavior.
@@ -131,25 +142,25 @@ guidance, and the explanatory overview close together without collapsing them in
 
 1. Create or open a project workspace.
 2. Run `npx xdrs-core` in the workspace root. This installs:
-   - `AGENTS.md` — instructs AI agents to always consult XDRs.
+   - `AGENTS.md` — instructs AI agents to always consult XDRS.
    - `.xdrs/index.md` — root index (editable, `keepExisting` mode).
-   - `_core` XDRs, Research documents, and skills under `.xdrs/_core/`.
+   - `_core` Policies, Research documents, and skills under `.xdrs/_core/`.
 3. Start a conversation with your AI agent:
    > Create an ADR about our decision to use Python for AI projects.
 
 ### Guidelines
 
-Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-standards.md) strictly. Key rules:
+Follow [_core-adr-policy-001](../001-xdrs-core.md) and [_core-adr-policy-002](../002-policy-standards.md) strictly. Key rules:
 
 - Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
   **advisory language** (`should`, `recommended`) for guidance.
-- Before citing an XDR as a requirement, check `Valid` first, then `Applied to`, and finally the decision text to confirm the decision is in scope for the current case.
+- Before citing a Policy as a requirement, check `Valid` first, then `Applied to`, and finally the decision text to confirm the decision is in scope for the current case.
 - All documents present in the collection are considered active. Remove documents that are no longer relevant.
-- Keep XDRs under 1300 words as a rule of thumb (exceptions up to 2600 words for templates or more elaborate decisions). Move procedural detail to a co-located Skill.
-- Keep exploratory option analysis in a co-located Research document instead of bloating the XDR.
-- Always update the scope+type index and the root index after adding or changing an XDR.
+- Keep Policies under 1300 words as a rule of thumb (exceptions up to 2600 words for templates or more elaborate decisions). Move procedural detail to a co-located Skill.
+- Keep exploratory option analysis in a co-located Research document instead of bloating the Policy.
+- Always update the scope+type index and the root index after adding or changing a Policy.
 - Use `_local` scope when a decision is project-specific and must not be shared.
-- Never reuse a number once it has been assigned, even if the XDR is deleted.
+- Never reuse a number once it has been assigned, even if the Policy is deleted.
 
 ### How to extend
 
@@ -157,18 +168,18 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 - **New subject** — create the subject folder under the existing scope+type path. Add an
   allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
 - **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-006](../006-research-standards.md).
+  folder, following [_core-adr-policy-006](../006-research-standards.md).
 - **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
-  folder, following [_core-adr-003](../003-skill-standards.md).
+  folder, following [_core-adr-policy-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-004](../004-article-standards.md).
+  folder, following [_core-adr-policy-004](../004-article-standards.md).
 - **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-007](../007-plan-standards.md).
+  folder, following [_core-adr-policy-007](../007-plan-standards.md).
 
-### Using XDRs in your own project
+### Using XDRS in your own project
 
 1. **Install** — add the scope package as a dependency and run `npx xdrs-core extract` (or
-   `pnpm exec xdrs-core extract`) to unpack XDR files into `.xdrs/` in your workspace.
+   `pnpm exec xdrs-core extract`) to unpack XDRS files into `.xdrs/` in your workspace.
 2. **Pins and upgrades** — update the npm dependency version to pull in the latest decisions
    for a scope. The `filedist` mechanism tracks managed files in `.filedist` and keeps
   `.xdrs/index.md` in `keepExisting` mode so local edits are preserved.
@@ -181,15 +192,15 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 
 ## References
 
-- [_core-adr-001](../001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
-- [_core-adr-002](../002-xdr-standards.md) - XDR document standards and mandatory template
-- [_core-adr-003](../003-skill-standards.md) - Skill standards and co-location rules
-- [_core-adr-004](../004-article-standards.md) - Article standards
-- [_core-adr-006](../006-research-standards.md) - Research standards
-- [_core-adr-007](../007-plan-standards.md) - Plan standards
-- [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
-- [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
+- [_core-adr-policy-001](../001-xdrs-core.md) - XDRS elements: types, scopes, subjects, folder structure
+- [_core-adr-policy-002](../002-policy-standards.md) - Policy document standards and mandatory template
+- [_core-adr-policy-003](../003-skill-standards.md) - Skill standards and co-location rules
+- [_core-adr-policy-004](../004-article-standards.md) - Article standards
+- [_core-adr-policy-006](../006-research-standards.md) - Research standards
+- [_core-adr-policy-007](../007-plan-standards.md) - Plan standards
+- [001-review skill](../skills/001-review/SKILL.md) - Reviewing code against Policies
+- [002-write-policy skill](../skills/002-write-policy/SKILL.md) - Writing a new Policy
 - [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
 - [004-write-article skill](../skills/004-write-article/SKILL.md) - Writing a new article
 - [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document
-- [_core-adr-005](../005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages
+- [_core-adr-policy-005](../005-semantic-versioning-for-xdrs-packages.md) - Semantic versioning rules for XDRS packages

package/.xdrs/_core/adrs/principles/skills/{001-lint/001-lint.test.int.js → 001-review/001-review.test.int.js}

@@ -15,7 +15,7 @@ test('smoke test', async () => {
 			...copilotCmd(REPO_ROOT),
 		},
 		'Reply ONLY with "READY" after checking if SKILL 001 has any contents',
-		'Verify that the final output is ONLY "READY" and that it read file 001-lint/SKILL.md',
+		'Verify that the final output is ONLY "READY" and that it read file 001-review/SKILL.md',
 		null,
 		true
 	);
@@ -23,15 +23,15 @@ test('smoke test', async () => {
 	expect(err).toBe('');
 });
 
-test('001-lint outputs the required review template', async () => {
+test('001-review outputs the required review template', async () => {
 	const err = await testPrompt(
 		{
 			workspaceRoot: REPO_ROOT,
 			workspaceMode: 'copy',
 			...copilotCmd(REPO_ROOT),
 		},
-		'Review xdr 001-xdrs-core',
-		'Verify that the skill 001-lint was used, contains "## Findings", and "## Summary", includes an "Outcome: PASS", and that it read file 001-lint/SKILL.md and 001-xdrs-core.md.',
+		'Review XDRS Policy 001-xdrs-core',
+		'Verify that the skill 001-review was used, contains "## Findings", and "## Summary", includes an "Outcome: PASS", and that it read file 001-review/SKILL.md and 001-xdrs-core.md.',
 		null,
 		true
 	);

package/.xdrs/_core/adrs/principles/skills/{001-lint/001-lint.test.int.report → 001-review/001-review.test.int.report}

@@ -1,5 +1,5 @@
 {
-  "Review xdr 001-xdrs-core-ac1c8339": {
+  "Review XDRS Policy 001-xdrs-core-ac1c8339": {
     "result": "success",
     "contextFiles": [
       ".github/skills/001-lint/SKILL.md",