xdrs-core 0.10.0 → 0.11.1

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

@@ -21,29 +21,23 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 
 ### Implementation Details
 
-- XDRs 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.
-- XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision, but they do not replace it.
-- XDRs MAY include a `## Metadata` section, but only when at least one supported metadata field is present. When used, `## Metadata` MUST appear immediately before `## Context and Problem Statement`.
-- Supported XDR metadata fields are:
-  - `Status:` Optional. Defines the lifecycle state of the decision. Allowed values are `Draft`, `Active`, and `Deprecated`. If omitted, the decision is treated as `Active`. Only `Active` decisions may be treated as current policy.
-  - `Valid:` Optional. Defines the time window in which an active decision may be treated as current. Use ISO dates only: `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`. If `from` is omitted, the decision takes effect immediately. If `until` is omitted, the decision remains valid indefinitely.
-  - `Applied to:` Optional. A short description of the contexts in which the decision is applicable. Keep it under 40 words. If omitted, the decision should be interpreted as applying to all logically applicable elements according to the decision text itself. Examples: `Only frontend code`, `JavaScript projects`, `Performance-sensitive codebases`
-- Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is in force for the current case.
-  - Check `Status:` first to determine whether the XDR is eligible to be used now. If `Status:` is omitted, treat it as `Active`. `Draft` and `Deprecated` decisions are background or history, not current policy.
-  - Check `Valid:` next to determine whether the current moment falls inside the decision's active date window. Not-yet-active and expired windows are not current policy.
-  - Check `Applied to:` next to determine whether the active, currently valid 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.
-  - If any check fails, the XDR MAY still be read as background, history, or context, but it MUST NOT be treated as a current requirement for that case.
-- 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, approval, retirement, and updates, but the XDR remains the source of truth.
-- 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"
-- Always the following folder structure:
+The standards below are split into framework-wide standards and XDR document standards.
+
+#### General framework standards
+
+- 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"
+- Always use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
 - Optional supporting artifacts under the same subject:
   - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
   - `.xdrs/[scope]/[type]/[subject]/articles/[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 and the decision-record standard.
+  - `_core-adr-003` defines skill standards
+  - `_core-adr-004` defines article standards
+  - `_core-adr-006` defines research standards
 - For simple structure, flow, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
 - Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they SHOULD live in a sibling `assets/` folder next to the document.
   - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/assets/`
@@ -51,34 +45,98 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
   - Research uses `.xdrs/[scope]/[type]/[subject]/researches/assets/`
   - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/`
 - **Scopes:** 
+  - 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 `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes.
+  - `_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 `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared `.xdrs/index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them.
   - **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:
-  - **ADR:** `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
-  - **BDR:** `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
-  - **EDR:** `principles`, `application`, `infra`, `ai`, `observability`, `devops`, `governance`
+- **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.
+  - **ADR subjects**
+    - `principles`: Cross-cutting architecture and policy foundations.
+      - Examples: architecture style, interoperability rules, long-term technology direction.
+    - `application`: System and service design decisions at application level.
+      - Examples: modularization strategy, service decomposition, app-level security flows.
+    - `data`: Data architecture and information modeling choices.
+      - Examples: canonical schemas, data ownership boundaries, retention strategies.
+    - `integration`: Decisions about communication between internal/external systems.
+      - Examples: sync vs async patterns, contract strategy, partner integration approach.
+    - `platform`: Platform-level runtime and enabling capabilities.
+      - Examples: cloud/runtime baseline, foundational services, platform tenancy approach.
+    - `controls`: Architecture controls for risk, security, and compliance at a high level.
+      - Examples: encryption baseline, auditability requirements, policy enforcement points.
+    - `operations`: Operational architecture decisions.
+      - Examples: incident model, resilience objectives, operational ownership boundaries.
+  - **BDR subjects**
+    - `principles`: Business principles and decision criteria that guide all business areas.
+      - Examples: customer fairness rules, policy precedence, strategic guardrails.
+    - `marketing`: Go-to-market, communication, and campaign policy decisions.
+      - Examples: campaign approval rules, channel usage standards, positioning constraints.
+    - `product`: Product behavior, lifecycle, and offering decisions.
+      - Examples: feature rollout policy, packaging/tiers, product requirement governance.
+    - `controls`: Business control framework decisions.
+      - Examples: approval segregation, mandatory checks, exception handling policy.
+    - `operations`: Day-to-day business process and procedure decisions.
+      - Examples: support workflows, onboarding/offboarding procedures, SLA operations.
+    - `organization`: Structure, roles, and responsibility model decisions.
+      - Examples: decision rights, team topology, accountability boundaries.
+    - `finance`: Financial and cost-control business decisions.
+      - Examples: budgeting process, pricing governance, investment approval rules.
+    - `sustainability`: Environmental and social responsibility policy decisions.
+      - Examples: sustainability KPIs, reporting cadence, procurement sustainability criteria.
+  - **EDR subjects**
+    - `principles`: Engineering principles and non-functional quality defaults.
+      - Examples: coding standards baseline, testing philosophy, secure-by-default engineering rules.
+    - `application`: Code-level implementation patterns and application conventions.
+      - Examples: framework patterns, layer organization, API implementation conventions.
+    - `infra`: Infrastructure implementation and runtime operations details.
+      - Examples: IaC patterns, environment provisioning, network/runtime hardening details.
+    - `observability`: Telemetry, monitoring, alerting, and diagnostics implementation.
+      - Examples: log/metric/tracing standards, alert routing policy, SLO measurement approach.
+    - `devops`: Delivery pipeline, release automation, and developer workflow decisions.
+      - Examples: CI/CD stages, branch strategy, release promotion gates.
+    - `governance`: Engineering governance, risk controls, and compliance mechanics.
+      - Examples: dependency governance, approval policies, mandatory quality checks.
+- If there is a README.md file in the root of the xdrs folder, always keep it up to date. Never use emojis.
+- **Indexes**
+  - Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
+  - Canonical index requirements:
+    - Organize XDRs 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 in imperative format and with fewer than 10 words. Example: "understand customer communication tone"
+  - Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
+  - Always verify if indexes are up to date after making changes
+
+#### XDR document standards (decision record source of truth)
+
+- XDRs 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.
+- XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision, but they do not replace it.
+- XDRs MAY include a `## Metadata` section, but only when at least one supported metadata field is present. When used, `## Metadata` MUST appear immediately before `## Context and Problem Statement`.
+- Supported XDR metadata fields are:
+  - `Status:` Optional. Defines the lifecycle state of the decision. Allowed values are `Draft`, `Active`, and `Deprecated`. If omitted, the decision is treated as `Active`. Only `Active` decisions may be treated as current policy.
+  - `Valid:` Optional. Defines the time window in which an active decision may be treated as current. Use ISO dates only: `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`. If `from` is omitted, the decision takes effect immediately. If `until` is omitted, the decision remains valid indefinitely.
+  - `Applied to:` Optional. A short description of the contexts in which the decision is applicable. Keep it under 40 words. If omitted, the decision should be interpreted as applying to all logically applicable elements according to the decision text itself. Examples: `Only frontend code`, `JavaScript projects`, `Performance-sensitive codebases`
+- Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is appliable for the current case.
+  - Check `Status:` first to determine whether the XDR is eligible to be used now. If `Status:` is omitted, treat it as `Active`. `Draft` and `Deprecated` decisions are background or history, not current policy.
+  - Check `Valid:` next to determine whether the current moment falls inside the decision's active date window. Not-yet-active and expired windows are not current policy.
+  - Check `Applied to:` next to determine whether the active, currently valid 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.
+  - If any check fails, the XDR MAY still be read as background, history, or context, but it MUST NOT be treated as a current requirement for that case.
+- 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, approval, retirement, and updates of xdrs, but the XDR document remains the source of truth.
 - **XDR Id:** [scope]-[type]-[xdr number unique in scope] (the xdr id must be unique among all XDRs of the same type in the different scopes and always use lowercase)
   - Types in IDs: `adr`, `bdr`, `edr`
   - Define the next number of an XDR by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted XDRs and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
-- Decisions MUST be concise and reference other XDRs to avoid duplication
+- Decisions MUST be concise and reference other XDRs to avoid duplication.
 - The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use `## Metadata` as the first-pass filter for whether the decision should be used at all, then keep nuanced boundaries in the decision text.
 - Use concise rules, examples, or `Do` / `Don't` lists only when they help a reader apply the decision correctly. Keep them short and decision-specific.
+- Conflict handling applies to XDR documents:
+  - For cross-scope overrides, document the decision conflict in the XDR `## Conflicts` section of the XDR that overrides another scope.
+  - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, deprecated, or the conflict resolved through a new XDR.
 - When research exists for a decision, the XDR SHOULD mention the related research documents after the `## Considered Options` list.
-- Never use emojis in contents
-- Always use file names with lowercase
+- Never use emojis in contents.
+- Always use file names with lowercase.
 - Avoid using lengthy instructions on the XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
-- If there is a README.md file in the root of the xdrs folder, always keep it up to date. Never use emojis
-- Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
-  - Organize XDRs by subject for easier navigation
-  - 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.
-  - Document decision conflicts in "Conflicts" section for the XDR that is overriding another XDR in other scopes
-  - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, deprecated, or the conflict resolved through a new XDR.
-  - In the index add a short description of what is this scope about (responsibilities, general worries, teams involved, link to discussion process etc)
-- Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
-- Always verify if the index is up to date after making changes
-- XDRs should be less than 100 lines long as a rule of thumb
+- XDRs should be less than 100 lines long as a rule of thumb.
   - This is important to make them focused on a clear decision
   - Exceptions can reach 200 lines (templates, more elaborate decision implementations etc)
 - ALWAYS use `_local` scope if the user doesn't explicitelly indicate a specific scope while creating an xdr or skill.

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

@@ -58,7 +58,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
 Examples:
 - `.xdrs/_core/adrs/principles/researches/001-research-and-decision-lifecycle.md`
 - `.xdrs/business-x/adrs/platform/researches/003-api-gateway-options.md`
-- `.xdrs/_local/edrs/ai/researches/002-model-serving-constraints.md`
+- `.xdrs/_local/edrs/application/researches/002-model-serving-constraints.md`
 
 **Research numbering**
 

package/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured XDR by following the standards in `_core-adr-001`, 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 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.
 
 ## Instructions
 
@@ -18,10 +18,13 @@ Guides the creation of a well-structured XDR by following the standards in `_cor
 
 1. Read `.xdrs/index.md` to discover all active scopes and their canonical indexes.
 2. Read `.xdrs/_core/adrs/principles/001-xdr-standards.md` in full to internalize structure rules, mandatory language, and the XDR template.
-3. Ask the user (or infer from context) the topic of the decision. Do NOT proceed to Phase 2 without a clear topic.
+3. Treat `.xdrs/_core/adrs/principles/001-xdr-standards.md` as the canonical source for all core XDR element definitions. Before choosing or writing any core element, consult it for the exact rules for type, scope, subject, ID, numbering, title, placement, and applicable folder structure instead of relying on memory or local convention.
+4. Ask the user (or infer from context) the topic of the decision. Do NOT proceed to Phase 2 without a clear topic.
 
 ### Phase 2: Select Type, Scope, and Subject
 
+Consult `001-xdr-standards` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
+
 **Type** — choose exactly one based on the nature of the decision:
 - **BDR**: business process, product policy, strategic rule, operational procedure
 - **ADR**: system context, integration pattern, overarching architectural choice
@@ -32,7 +35,7 @@ Guides the creation of a well-structured XDR by following the standards in `_cor
 **Subject** — pick one from the allowed list for the chosen type (from `001-xdr-standards`):
 - ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
 - BDR: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
-- EDR: `principles`, `application`, `infra`, `ai`, `observability`, `devops`, `governance`
+- EDR: `principles`, `application`, `infra`, `observability`, `devops`, `governance`
 
 **XDR ID** — format: `[scope]-[type]-[next available number]`
 - Scan `.xdrs/[scope]/[type]/` for the highest existing number in that scope+type and increment by 1.
@@ -133,6 +136,7 @@ If any check fails, revise and re-run this phase before proceeding.
 ### Constraints
 
 - MUST follow the XDR template from `001-xdr-standards` exactly.
+- MUST consult `001-xdr-standards` as the canonical source for every core element definition, especially type, scope, subject, ID, numbering, naming, and placement.
 - 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 prefer links and short references over repeating the same decision content across related documents.

package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md

@@ -11,17 +11,20 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured skill package by following `_core-adr-003` skill standards, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
+Guides the creation of a well-structured skill package by following `_core-adr-003` skill standards, consulting `xdr-standards` for every core element definition, checking existing skills to avoid duplication, and producing a complete SKILL.md ready to activate in VS Code.
 
 ## Instructions
 
 ### Phase 1: Understand the Skill Goal
 
 1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format, folder layout, and numbering rules.
-2. Identify what the skill must do, the concrete outcome it should produce, and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal, outcome, and activation trigger.
+2. Read `.xdrs/_core/adrs/principles/001-xdr-standards.md` in full before defining any core element for the skill package. Treat it as the canonical source for type, scope, subject, numbering expectations, naming constraints, and folder placement rules.
+3. Identify what the skill must do, the concrete outcome it should produce, and the exact conditions under which an agent should activate it. Do NOT proceed without a clear goal, outcome, and activation trigger.
 
 ### Phase 2: Select Type, Scope, Subject, and Number
 
+Consult `001-xdr-standards` while making each choice in this phase. The summaries below are orientation only; when there is any ambiguity or edge case, the standard decides.
+
 **Type** — choose one based on the skill's activity:
 - **EDR skill**: engineering workflows, tool usage, coding procedures, implementation how-tos
 - **ADR skill**: architectural evaluation, pattern compliance, technology selection guidance
@@ -37,7 +40,7 @@ Quick test:
 **Subject** — pick the most specific match for the chosen type (see `003-skill-standards`):
 - ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
 - BDR subjects: `principles`, `marketing`, `product`, `controls`, `operations`, `organization`, `finance`, `sustainability`
-- EDR subjects: `principles`, `application`, `infra`, `ai`, `observability`, `devops`, `governance`
+- EDR subjects: `principles`, `application`, `infra`, `observability`, `devops`, `governance`
 
 **Skill number** — scan `.xdrs/[scope]/[type]/[subject]/skills/` for the highest existing number and increment by 1. Never reuse numbers from deleted skills.
 
@@ -122,6 +125,7 @@ If any check fails, revise before continuing.
 ### Constraints
 
 - MUST follow the agentskills SKILL.md format from `003-skill-standards` exactly.
+- MUST consult `001-xdr-standards` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
 - MUST include a References section linking to `003-skill-standards`.

package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md

@@ -9,9 +9,7 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured article by following `_core-adr-004`, researching the XDRs,
-Research documents, and Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating
-decision content.
+Guides the creation of a well-structured article by following `_core-adr-004`, consulting `xdr-standards` for every core element definition, researching the XDRs, Research documents, and Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating decision content.
 
 ## Instructions
 
@@ -19,15 +17,21 @@ decision content.
 
 1. Read `.xdrs/_core/adrs/principles/004-article-standards.md` in full to internalize the template,
    placement rules, numbering rules, and the constraint that articles are views, not decisions.
-2. Identify the topic and intended audience from user input or context. Do NOT proceed without a clear
+2. Read `.xdrs/_core/adrs/principles/001-xdr-standards.md` in full before defining the article's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering, naming, and folder placement.
+3. Identify the topic and intended audience from user input or context. Do NOT proceed without a clear
    topic.
 
 ### Phase 2: Select Scope, Type, and Subject
 
+Consult `001-xdr-standards` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
+
 **Scope** — use `_local` unless the user explicitly names another scope.
 
 **Type** — match the type of the XDRs the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
-If the topic spans multiple types, use `adrs`.
+If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-xdr` Phase 2:
+- **BDR**: business process, product policy, strategic rule, operational procedure
+- **ADR**: system context, integration pattern, overarching architectural choice
+- **EDR**: specific tool/library, coding practice, testing strategy, project structure, pipelines
 
 **Subject** — pick the subject that best matches the article's topic (see `004-article-standards`).
 If the article spans more than one subject, place it in `principles`.
@@ -111,6 +115,13 @@ Rules to apply while drafting:
 - **Conflicting information found** — note the conflict in the article and always defer to the XDR.
 - **Article would exceed 150 lines** — move detailed content to a new Research, Skill, or XDR and link back.
 
+## Constraints
+
+- MUST consult `001-xdr-standards` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
+- MUST follow the article template and placement rules from `004-article-standards`.
+- MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST defer to active and applicable XDRs when article synthesis conflicts with them.
+
 ## References
 
 - [_core-adr-004 - Article standards](../../../.xdrs/_core/adrs/principles/004-article-standards.md)

package/.xdrs/_core/adrs/principles/skills/005-write-research/005-write-research.test.int.js

@@ -0,0 +1,37 @@
+'use strict';
+
+const path = require('path');
+const { copilotCmd, testPrompt } = require('xdrs-core');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
+
+jest.setTimeout(60000);
+
+test.skip('check', () => {
+	const err = testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'in-place',
+			promptCmd: copilotCmd(REPO_ROOT)
+		},
+		'Reply with READY and nothing else.',
+		'Verify that the final output is READY and nothing else.',
+		true
+	);
+
+	expect(err).toBe('');
+});
+
+test('005-write-research creates an IMRAD research document in copy mode', () => {
+	const err = testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'copy',
+			promptCmd: copilotCmd(REPO_ROOT)
+		},
+		'Create a very small research document with the following data: We measured the installation time in our monorepo and pnpm is 3.5x faster than Yarn when installing dependencies. We recommend using PNPM in our monorepo to speed up our productivity as it seems very easy to use and have a better internal hoisting mechanism.',
+		'Verify that a research file was created under .xdrs/_local/edrs/devops/researches/, that it contains the sections Abstract, Introduction, Methods, Results, Discussion, Conclusion, and References, and that the content contains all the provided data in input prompt, and doesn\'t contain more than 20% of additional information.'
+	);
+
+	expect(err).toBe('');
+});

package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md

@@ -11,26 +11,32 @@ metadata:
 
 ## Overview
 
-Guides the creation of a well-structured research document by following `_core-adr-006`, checking related XDRs and existing research to avoid duplication, and producing an IMRAD-based study that reads as a standalone technical paper. Treat each section goal in the research template as an acceptance criterion, not as optional wording. Do not assume missing direction, evidence, or intended follow-up; ask the user explicitly before proceeding when those points are not already concrete.
+Guides the creation of a well-structured research document by following `_core-adr-006`, consulting `xdr-standards` for every core element definition, checking related XDRs and existing research to avoid duplication, and producing an IMRAD-based study that reads as a standalone technical paper. Treat each section goal in the research template as an acceptance criterion, not as optional wording. Do not assume missing direction, evidence, or intended follow-up; ask the user explicitly before proceeding when those points are not already concrete.
 
 ## Instructions
 
 ### Phase 1: Understand the Research Goal
 
 1. Read `.xdrs/_core/adrs/principles/006-research-standards.md` in full to internalize the folder layout, numbering rules, and mandatory template.
-2. Ask the user to confirm the intended direction of the research before planning the document: what decision, question, or option space the study should support, what boundaries or exclusions apply, and what kind of outcome they expect.
-3. Ask the user what evidence already exists and what evidence-gathering methods are acceptable if the current evidence is incomplete. Do not invent facts, sources, or confidence that the user did not provide.
-4. Ask the user what the proposed next step is after the research, such as writing a new XDR, updating an existing XDR, informing a discussion, or documenting trade-offs for later. Use that answer to shape the framing without turning the research into the final decision.
-5. Identify the problem or question being explored, the relevant system or domain context, the likely technical audience, and why the subject matters in practice.
-6. Internalize the goal of each required section before drafting: `Abstract` gives a quick technical reader the question, method, main result, and takeaway, `Introduction` frames the investigated problem and context, `Methods` makes the important parts reproducible, `Results` records raw findings with minimal interpretation, `Discussion` interprets the findings, `Conclusion` summarizes the practical takeaway and boundaries, and `References` makes sources traceable.
-7. Collect the main constraints, known facts, important experiences, gaps, and assumptions that belong in the introduction.
-8. Do NOT proceed without a clear problem statement, a central question, explicit user direction, an understood next step, and at least one credible source of evidence or a method for generating it. If any of these are ambiguous, stop and ask instead of assuming.
+2. Read `.xdrs/_core/adrs/principles/001-xdr-standards.md` in full before defining the research document's core elements. Treat it as the canonical source for how to choose and write type, scope, subject, numbering expectations, naming constraints, and folder placement.
+3. Ask the user to confirm the intended direction of the research before planning the document: what decision, question, or option space the study should support, what boundaries or exclusions apply, and what kind of outcome they expect.
+4. Ask the user what evidence already exists and what evidence-gathering methods are acceptable if the current evidence is incomplete. Do not invent facts, sources, or confidence that the user did not provide.
+5. Ask the user what the proposed next step is after the research, such as writing a new XDR, updating an existing XDR, informing a discussion, or documenting trade-offs for later. Use that answer to shape the framing without turning the research into the final decision.
+6. Identify the problem or question being explored, the relevant system or domain context, the likely technical audience, and why the subject matters in practice.
+7. Internalize the goal of each required section before drafting: `Abstract` gives a quick technical reader the question, method, main result, and takeaway, `Introduction` frames the investigated problem and context, `Methods` makes the important parts reproducible, `Results` records raw findings with minimal interpretation, `Discussion` interprets the findings, `Conclusion` summarizes the practical takeaway and boundaries, and `References` makes sources traceable.
+8. Collect the main constraints, known facts, important experiences, gaps, and assumptions that belong in the introduction.
+9. Do NOT proceed without a clear problem statement, a central question, explicit user direction, an understood next step, and at least one credible source of evidence or a method for generating it. If any of these are ambiguous, stop and ask instead of assuming.
 
 ### Phase 2: Select Scope, Type, Subject, and Number
 
+Consult `001-xdr-standards` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
+
 **Scope** — use `_local` unless the user explicitly names another scope.
 
-**Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`).
+**Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-xdr` Phase 2:
+- **BDR**: business process, product policy, strategic rule, operational procedure
+- **ADR**: system context, integration pattern, overarching architectural choice
+- **EDR**: specific tool/library, coding practice, testing strategy, project structure, pipelines
 
 **Subject** — pick the most specific subject that matches the problem domain.
 
@@ -253,4 +259,11 @@ If any check fails, revise before continuing.
 
 - [_core-adr-006 - Research standards](../../006-research-standards.md)
 - [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
-- [002-write-xdr skill](../002-write-xdr/SKILL.md)
+- [002-write-xdr skill](../002-write-xdr/SKILL.md)
+
+## Constraints
+
+- MUST consult `001-xdr-standards` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
+- MUST follow the research template and section-goal rules from `006-research-standards`.
+- MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST keep the document as research rather than turning it into a final decision.

package/.xdrs/index.md

@@ -19,6 +19,4 @@ Decisions about how XDRs work
 
 ### _local (reserved)
 
-Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Add specific `_local` ADR/BDR/EDR index links here when present.
-
-
+Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Keep `_local` canonical indexes in the workspace tree only; do not link them from this shared index. Readers and tools should still try to discover existing `_local` indexes in the current workspace by default.

package/README.md

@@ -68,6 +68,46 @@ npx -y xdrs-core lint ./some-project
 pnpm exec xdrs-core lint .
 ```
 
+## Library Testing
+
+The package also exposes a reusable behavior-test library for Jest or any other JavaScript test runner.
+
+Main exports:
+
+- `testPrompt(config, inputPrompt, judgePrompt)` runs the task prompt, evaluates the result in a fresh judge session, and returns an empty string on success or a markdown bullet list on failure.
+- `runPromptTest(config, inputPrompt, judgePrompt)` returns the structured result object when you need access to captured output and the agent-reported changed file list.
+- `copilotCmd(workspaceRoot)` returns a ready-to-use `promptCmd` template for the Copilot CLI in headless mode (`--autopilot`, full tool/url permissions, and `--no-ask-user`). The library uses that same command template for both the task and judge phases. If `workspaceRoot` is omitted it defaults to the current git repository root.
+- `config.workspaceRoot`, when set, is the authoritative workspace under test. If omitted, the library uses the current git repository root.
+
+Execution model:
+
+- phase 1 runs the task prompt and captures final output text plus the files the agent says it changed
+- phase 2 runs an independent judge prompt in a fresh invocation of `promptCmd` against the original task prompt, task output, the agent-reported changed file list, and the current workspace state
+- the judge trusts that reported file list as the authoritative change report and reads file contents from the workspace directly when needed
+- when `workspaceMode: 'copy'` is used, the temporary workspace honors nested `.gitignore` rules and skips git metadata files during the copy
+
+`promptCmd` accepts either a string array or a JSON array string and must include a `{PROMPT}` placeholder.
+
+Example with Jest:
+
+```js
+const { copilotCmd, testPrompt } = require('xdrs-core');
+
+test('creates hello.md', () => {
+  const err = testPrompt(
+    {
+      workspaceRoot: process.cwd(),
+      promptCmd: copilotCmd(process.cwd()),
+      workspaceMode: 'copy'
+    },
+    "Create a nice markdown file at hello.md saying 'hello!'",
+    'The resulting file should be created at hello.md and have hello as part of its contents, without too much extra info (should be <100 chars)'
+  );
+
+  expect(err).toBe('');
+});
+```
+
 ## Requirements
 
 ### Multi-scope support

package/lib/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./testPrompt');

package/lib/lint.js

@@ -13,7 +13,7 @@ const TYPE_TO_ID = {
 const ALLOWED_SUBJECTS = {
   adrs: new Set(['principles', 'application', 'data', 'integration', 'platform', 'controls', 'operations']),
   bdrs: new Set(['principles', 'marketing', 'product', 'controls', 'operations', 'organization', 'finance', 'sustainability']),
-  edrs: new Set(['principles', 'application', 'infra', 'ai', 'observability', 'devops', 'governance'])
+  edrs: new Set(['principles', 'application', 'infra', 'observability', 'devops', 'governance'])
 };
 
 const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
@@ -96,32 +96,30 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
     errors.push(`Root index is missing required override text: ${toDisplayPath(rootIndexPath)}`);
   }
 
-  const localLinks = parseLocalLinks(content, path.dirname(rootIndexPath));
-  for (const linkPath of localLinks) {
+  const links = parseLocalLinks(content, path.dirname(rootIndexPath));
+  for (const linkPath of links) {
     if (!fs.existsSync(linkPath)) {
       errors.push(`Broken link in root index: ${displayPath(rootIndexPath, linkPath)}`);
     }
   }
 
-  const linkedTypeIndexes = localLinks.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
+  const linkedTypeIndexes = links.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
   const linkedSet = new Set(linkedTypeIndexes.map(normalizePath));
 
-  for (const indexPath of actualTypeIndexes) {
-    if (!linkedSet.has(normalizePath(indexPath))) {
-      errors.push(`Root index is missing canonical index link: ${toDisplayPath(indexPath)}`);
+  for (const indexPath of linkedTypeIndexes) {
+    const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
+    if (scopeName === '_local') {
+      errors.push(`Root index must not link _local canonical index: ${displayPath(rootIndexPath, indexPath)}`);
     }
   }
 
-  let seenLocal = false;
-  for (const indexPath of linkedTypeIndexes) {
+  for (const indexPath of actualTypeIndexes) {
     const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
     if (scopeName === '_local') {
-      seenLocal = true;
       continue;
     }
-    if (seenLocal) {
-      errors.push('Root index must keep all _local scope links after every non-_local scope link');
-      break;
+    if (!linkedSet.has(normalizePath(indexPath))) {
+      errors.push(`Root index is missing canonical index link: ${toDisplayPath(indexPath)}`);
     }
   }
 }