xdrs-core 0.24.1 → 0.26.0

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

@@ -1,39 +1,50 @@
-# _core-article-001: XDRs Overview
+# _core-adr-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",

package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: _core-adr-skill-001-review
+description: >
+  Reviews code changes or files against applicable Policies and reports violations as structured findings. 
+  Activate this skill when the user asks to review, lint, or audit code or Policies, or when you identify a need to check compliance with Policies during implementation.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Performs a structured review of code changes or files against the Policies in the repository, categorizing findings by severity and type, and reporting them without modifying any code.
+
+## Instructions
+
+### Phase 1: Code Gathering
+
+1. Identify changes based on requested scope:
+   - For diffs: run and parse `git diff refs/remotes/origin/HEAD`
+   - For files: analyze file contents directly
+
+### Phase 2: Policy Compilation
+
+1. Gather all Policies from the Policy root `index.md` (default: `.policies/index.md`) starting from the working directory.
+   - Policy scopes are controlled by nested folders; some are broad, others domain-specific.
+   - Extract frontmatter first to decide whether each Policy should be used for the current review context.
+   - All documents present in the collection are considered active.
+   - 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:` second. Keep only Policies whose stated scope fits the files, systems, or workflows under review.
+   - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
+2. Filter relevance based on file types, domains, and architectural patterns in scope.
+
+### Phase 3: Policy Review
+
+1. Cross-reference each file in scope against active, applicable Policies.
+   - **Drop any finding that cannot be traced to a specific rule in an Accepted Policy.** General good-practice observations, personal opinions, or inferred issues without an explicit Policy backing must not be reported.
+   - Classify as ERROR (mandatory) or WARNING (advisory).
+   - Include: location, description, Policy reference (file + line), suggestion.
+2. Reduce false positives:
+   - Evaluate ERROR findings for mandatory language in the Policy ("must", "always", "never", "required", "mandatory"). Drop or downgrade to WARNING if the language is advisory ("should", "recommended", "advised").
+   - Remove findings unrelated to actual changes.
+   - Consolidate duplicates.
+   - Consider context (existing style, legacy sections, etc.).
+3. For related Policies and files, lookup for the specific line number in both the Policy and the code that are related to the finding. This will be used in the reporting phase to provide precise references and actionable suggestions.
+
+### Phase 4: Judgment
+1. Judgment criteria (all must be true to keep a finding):
+   - Is the violation explicitly stated as a rule in an Accepted Policy using mandatory or advisory language? Templates, examples, and diagrams in Policies are illustrative only — they do not constitute rules. If the only evidence for the violation is an implicit pattern in a code sample or template, drop it.
+   - Is there concrete evidence in the code or diff?
+   - Is the finding actionable?
+   - Would fixing it meaningfully improve compliance with the Policies?
+
+### Phase 5: Reporting
+
+**Report template**
+```text
+### Code Review Against Policies
+Scope: [scope identifier]
+
+## Findings
+### 1. [ERROR|WARNING] - [filename:line_number](filename:line_number)
+- Title of the finding (<=15 words)
+- Policy reference: [policy-file:line_number](policy-file:line_number)
+- Why: Brief description of the issue in 20 words
+- Fix: Specific action to fix this issue in 15 words
+- Relevance: Why this matters / What to watch for in 15 words
+
+### 2. [second finding etc]
+
+## Summary
+- Errors: [count]
+- Warnings: [count]
+- Outcome: [PASS|FAIL]
+```
+
+### Constraints
+- MUST NOT include any text or explanations outside the required output format.
+- MUST NOT edit code. Instruct the user on how to request code changes in suggestions.
+
+## Examples
+- A Policy mentions that "Every code MUST have a header comment with author name", if you find a codebase without the author name, report as ERROR.
+- A Policy mentions that "Functions SHOULD be no longer than 50 lines", if you find a function with 80 lines, report as WARNING.
+
+## Edge Cases
+- If no Policies apply to the scope, output "No applicable Policies found" and skip reporting.
+- If a potential violation is in pre-existing code outside the diff, report it as WARNING only.
+
+## References
+
+- [_core-adr-policy-001 - Policies core](../../001-xdrs-core.md)
+- [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
+- [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)
+

package/.xdrs/_core/adrs/principles/skills/002-write-policy/002-write-policy.test.int.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const path = require('path');
+const { copilotCmd, testPrompt } = require('xdrs-core');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
+
+jest.setTimeout(300000);
+
+test('002-write-policy creates a local EDR policy', async () => {
+	const err = await testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'copy',
+			...copilotCmd(REPO_ROOT),
+		},
+		'Create a very small XDRS Policy deciding to use pnpm for Node.js monorepos',
+		'Verify that an XDRS Policy markdown file was created under .xdrs/_local/edrs/devops/, that it contains "## Context and Problem Statement" and "## Decision Outcome", that it read file 002-write-policy/SKILL.md and has the decision of using pnpm for Node.js monorepos.',
+		null,
+		true
+	);
+
+	expect(err).toBe('');
+});

package/.xdrs/_core/adrs/principles/skills/{002-write-xdr/002-write-xdr.test.int.report → 002-write-policy/002-write-policy.test.int.report}

@@ -1,10 +1,10 @@
 {
-  "Create a very small XDR deciding to use -8b1a2ddd": {
+  "Create a very small XDRS Policy deciding to -8b1a2ddd": {
     "result": "success",
     "contextFiles": [
       ".xdrs/_core/adrs/index.md",
       ".xdrs/_core/adrs/principles/002-xdr-standards.md",
-      ".xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md",
+      ".xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md",
       ".xdrs/index.md",
       "AGENTS.md"
     ],

package/.xdrs/_core/adrs/principles/skills/{002-write-xdr → 002-write-policy}/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: 002-write-xdr
+name: _core-adr-skill-002-write-policy
 description: >
-  Creates a new XDR (Decision Record) interactively: selects type, scope, subject, and writes a focused, conflict-checked decision document.
-  Activate this skill when the user asks to create, add, or write a new XDR, ADR, BDR, or EDR.
+  Creates a new Policy interactively: selects type, scope, subject, and writes a focused, conflict-checked policy document.
+  Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -10,16 +10,16 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured XDR by following the standards in `_core-adr-001`, consulting `xdr-standards` for every core element definition, researching existing records for conflicts, checking redundancy across related artifacts, and iterating until the document is concise, decision-focused, and clear about when the decision should be used.
+Guides the creation of a well-structured Policy by following the standards in `_core-adr-policy-001`, consulting `policy-standards` for every core element definition, researching existing policies for conflicts, checking redundancy across related artifacts, and iterating until the document is concise, decision-focused, and clear about when the decision should be used.
 
 ## Instructions
 
 ### Phase 1: Understand the Decision
 
-1. Read the XDR root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.
-2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full to internalize structure rules, mandatory language, and the XDR framework elements.
-3. Read `.xdrs/_core/adrs/principles/002-xdr-standards.md` in full to internalize the XDR template and document writing rules.
-4. Treat `001-xdrs-core` as the canonical source for all core XDR element definitions (type, scope, subject, numbering, placement). Treat `002-xdr-standards` as the canonical source for how to write and structure the document itself.
+1. Read the XDRS root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.
+2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` in full to internalize structure rules, mandatory language, and the XDRS framework elements.
+3. Read `.xdrs/_core/adrs/principles/002-policy-standards.md` in full to internalize the Policy template and document writing rules.
+4. Treat `001-xdrs-core` as the canonical source for all core XDRS element definitions (type, scope, subject, numbering, placement). Treat `002-policy-standards` as the canonical source for how to write and structure the document itself.
 5. Ask the user (or infer from context) the topic of the decision. Do NOT proceed to Phase 2 without a clear topic.
    - Ask one focused clarifying question at a time. Wait for the answer before asking the next question.
    - Each answer may reveal new ambiguities; ask follow-up questions as needed until the topic, intent, and scope are unambiguous.
@@ -44,47 +44,47 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 
 When type, scope, or subject cannot be confidently inferred, ask the user a clarifying question before proceeding. Ask one question at a time and wait for the answer; follow up if the response introduces new ambiguity.
 
-**XDR ID** — format: `[scope]-[type]-[next available number]`
+**Policy ID** — format: `[scope]-[type]-[next available number]`
 - Scan `.xdrs/[scope]/[type]/` for the highest existing number in that scope+type and increment by 1.
-- Never reuse numbers from deleted XDRs.
+- Never reuse numbers from deleted Policies.
 
 ### Phase 3: Choose the Title
 
-Choose a title that clearly states the question this XDR answers, not the answer itself. The title should let a reader know at a glance what decision scope this record covers.
+Choose a title that clearly states the question this Policy answers, not the answer itself. The title should let a reader know at a glance what decision scope this record covers.
 
 - Good: "Package manager for Node.js projects", "Phone marketing procedures", "Integration patterns for systems connectivity"
 - Avoid: "Use pnpm", "We chose pnpm", or overly vague titles like "Tooling decisions"
 
-### Phase 4: Research Related XDRs
+### Phase 4: Research Related Policies
 
-1. Read all existing XDRs relevant to the topic across all scopes listed in the XDR root `index.md`.
-2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
+1. Read all existing Policies relevant to the topic across all scopes listed in the Policy root `index.md`.
+2. Evaluate Policy metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope Policies as background only when assessing overlaps and conflicts.
 3. Identify decisions that already address the topic (full or partial overlap).
 4. Note decisions that might conflict with the intended outcome.
 5. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
-6. Collect XDR IDs and file paths for cross-references.
+6. Collect Policy IDs and file paths for cross-references.
 
 ### Phase 5: Check Redundancy Across Related Artifacts
 
-1. Review the related XDRs, research documents, skills, articles, and guides connected to the same decision thread.
+1. Review the related Policies, research documents, skills, articles, and guides connected to the same decision thread.
 2. Identify content that is repeated across those files, especially decision statements, applicability boundaries, mandatory rules, and rationale.
-3. Prioritize the final decision, core boundaries, and short key instructions in the XDR itself.
+3. Prioritize the final decision, core boundaries, and short key instructions in the Policy itself.
 4. When another document already explains details well, link to it instead of re-explaining the same content in full.
-5. Copy only short instructions or key excerpts when they materially help a reader apply the decision without leaving the XDR.
+5. Copy only short instructions or key excerpts when they materially help a reader apply the decision without leaving the Policy.
 6. Avoid repeating the same decision text across multiple related documents whenever a link or short reference is enough.
 
 ### Phase 6: Write the First Draft
 
-Use the mandatory template from `002-xdr-standards`:
+Use the mandatory template from `002-policy-standards`:
 
 **Check if the decision requires a structured set of rules:**
-If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-008-xdr-standards-structured`. This means:
+If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-policy-008-policy-standards-structured`. This means:
   - Place each rule as a numbered heading block inside `### Details`.
   - Use the format:
     #### [NN]-[short-descriptive-title-in-kebab-case]
     [Rule body with mandatory/advisory language.]
   - Ensure each rule is uniquely numbered (two digits, zero-padded) and never reuse numbers if a rule is removed.
-  - Other documents must cite rules using the canonical dot-notation: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`.
+  - Other documents must cite rules using the canonical dot-notation: `[policy-name].[NN-short-descriptive-title-in-kebab-case]`.
 
 **Example of a structured set of rules:**
 
@@ -101,7 +101,7 @@ Access logs must be retained for at least 90 days and reviewed monthly for suspi
 All external integrations should be reviewed annually for compliance with current security standards.
 ```
 
-Refer to `_core-adr-008-xdr-standards-structured` for full requirements and citation syntax.
+Refer to `_core-adr-policy-008-policy-standards-structured` for full requirements and citation syntax.
 
 ```
 ---
@@ -135,14 +135,14 @@ Mandatory rules to apply while drafting:
 - Include frontmatter `apply-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
 - Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
 - Keep `apply-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
-- When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `apply-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
+- When frontmatter metadata is present, write it so a reader can decide whether the Policy should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `apply-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
-- Do not duplicate content already in referenced XDRs — link instead.
-- Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
+- Do not duplicate content already in referenced Policies — link instead.
+- Keep the decision itself authoritative in the Policy. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
 - Make clear when the decision applies and any important exception boundaries.
 - Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
 - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
-- If the XDR genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
+- If the Policy genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - No emojis. Lowercase filenames.
 - Target under 1300 words total; under 2600 words for complex decisions.
@@ -152,23 +152,23 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Frontmatter**: Are `apply-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
+2. **Frontmatter**: Are `apply-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the Policy is currently valid and applicable?
 3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
-5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
+5. **Redundancy**: Is the Policy the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
 6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
-7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and the XDR root `index.md`?
+7. **Index entries**: Will the new Policy be added to `[scope]/[type]/index.md` and the Policy root `index.md`?
 
 If any check fails, revise and re-run this phase before proceeding.
 
 ### Phase 8: Write Files
 
-1. Create the XDR file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
+1. Create the Policy file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
 2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
-3. Add or verify the scope entry in the XDR root `index.md`.
-4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
-5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the XDR into a long procedure.
-6. Evaluate whether the scope index at `[xdrs-root]/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
+3. Add or verify the scope entry in the Policy root `index.md`.
+4. If significant research was produced or already exists, link it from the Policy `## Considered Options` section.
+5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the Policy into a long procedure.
+6. Evaluate whether the scope index at `[xdrs-root]/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
 
 ### Phase 9: Verify Package structure with Lint
 
@@ -181,16 +181,16 @@ If any check fails, revise and re-run this phase before proceeding.
 
 ### Constraints
 
-- MUST follow the XDR template from `002-xdr-standards` exactly.
-- MUST consult `001-xdrs-core` as the canonical source for element definitions (type, scope, subject, ID, numbering, naming, placement) and `002-xdr-standards` for document writing rules and template.
+- MUST follow the Policy template from `002-policy-standards` exactly.
+- MUST consult `001-xdrs-core` as the canonical source for element definitions (type, scope, subject, ID, numbering, naming, placement) and `002-policy-standards` for document writing rules and template.
 - MUST NOT add personal opinions or general best-practice content not tied to a decision.
-- MUST NOT create an XDR that duplicates a decision already captured in another XDR — extend or reference instead.
+- MUST NOT create a Policy that duplicates a decision already captured in another Policy — extend or reference instead.
 - MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 
 ## References
 
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-policy-001 - XDRS core](../../001-xdrs-core.md)
+- [_core-adr-policy-002 - Policy standards](../../002-policy-standards.md)
+- [_core-adr-policy-003 - Skill standards](../../003-skill-standards.md)