xdrs-core 0.9.0 → 0.11.0

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

@@ -25,8 +25,15 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 - 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`
-  - `Validity:` Optional. Defines when the decision is active. 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. `Draft` or `Retired` mean the XDR should be ignored as an active rule or policy.
+- 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"
@@ -45,7 +52,7 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
   - Skills use `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/`
 - **Scopes:** 
   - 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:
@@ -56,7 +63,7 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
   - 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
-- The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use `## Metadata` for short applicability or lifecycle markers and keep nuanced boundaries in the decision text.
+- 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.
 - When research exists for a decision, the XDR SHOULD mention the related research documents after the `## Considered Options` list.
 - Never use emojis in contents
@@ -85,9 +92,10 @@ All XDRs MUST follow this template
 
 ## Metadata
 
-[Optional section. Omit the entire section when neither `Applied to:` nor `Validity:` is defined.]
+[Optional section. Omit the entire section when none of `Status:`, `Valid:`, or `Applied to:` is defined. Readers decide whether to use the XDR by checking `Status:` first, treating omission as `Active`, then `Valid:`, then `Applied to:`, and finally the decision text itself.]
+Status: [Optional. Use `Draft`, `Active`, or `Deprecated`. Defaults to `Active` when omitted]
+Valid: [Optional. Use `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`]
 Applied to: [Optional short applicability scope, under 40 words]
-Validity: [Optional. Use `Draft`, `Retired`, `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`]
 
 ## Context and Problem Statement
 
@@ -141,9 +149,10 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - `.xdrs/business-x/adrs/governance/010-security-and-secrets-management.md`
 - `.xdrs/_core/adrs/devops/001-multi-repo.md`
 - Metadata examples:
+  - `Status: Draft`
+  - `Status: Active`
+  - `Valid: from 2026-03-01 until 2026-12-31`
   - `Applied to: JavaScript projects`
-  - `Validity: Draft`
-  - `Validity: from 2026-03-01 until 2026-12-31`
 
 ```text
 subject/

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

@@ -31,6 +31,7 @@ Skills are procedures, XDRs are guardrails and decisions, Research documents cap
 Always create links back and forth between skills <-> XDRs when the relationship is direct, and link to related Research or Articles when they provide important context.
 - Skills are task-based artifacts. They should have a clear starting trigger, an expected end result, and enough detail for a human or agent to verify that the task finished correctly.
 - A skill is not policy by itself. If following a skill is mandatory, that obligation must come from an XDR or another explicit policy that references the skill.
+- When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `Status:` determines whether the decision is eligible to be used, and an omitted `Status:` must be treated as `Active`. `Valid:` determines whether that active decision is currently in force by date, `Applied to:` determines whether it fits the current task context, and the decision text itself determines any remaining boundaries. Skills must not treat inactive, out-of-window, or out-of-scope XDRs as current requirements.
 - Skills and XDRs have a many-to-many relationship: one skill may operationalize multiple XDRs, and one XDR may be executed through multiple skills in different contexts.
 
 Place a skill under the XDR type that matches the nature of the activity the skill performs:

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

@@ -17,6 +17,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - Articles are views, not decisions. They summarize and synthesize content from XDRs, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Decision Record, the Decision Record takes precedence.
 - Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
 - Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
+- When an article tells readers which decisions to follow, it SHOULD distinguish currently usable XDRs from background-only ones by checking `Status:` first, treating omission as `Active`, `Valid:` second, `Applied to:` third, and the decision text itself last. Articles must not present Draft, Deprecated, inactive-date, out-of-window, or out-of-scope XDRs as current rules for the discussed context.
 - Articles must remain consistent with the XDRs, Research documents, and Skills they reference. When a referenced artifact changes, the article must be reviewed and updated.
 - Place an article in the subject folder that best matches its topic. If an article spans more than one subject, place it in `principles`.
 - For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.

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

@@ -47,6 +47,16 @@ 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
+
+Before treating an XDR as a rule for the current case, check its metadata first.
+
+- **Status first**: only `Active` decisions can be current policy, and omitted `Status` should be treated as `Active`. `Draft` and `Deprecated` are background or historical context.
+- **Valid second**: if present, the current moment must fall inside the decision's date window.
+- **Applied to third**: 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.
+- **Then enforce**: only decisions that pass those checks should be used as active requirements. The rest may still be useful background or historical context.
+
 ### How they relate over time
 
 The framework is easiest to understand as a lifecycle rather than a static folder tree.
@@ -122,6 +132,7 @@ Follow [_core-adr-001](../001-xdr-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 `Status` first, treating omission as `Active`, then `Valid`, then `Applied to`, and finally the decision text to confirm the decision is active and in scope for the current case.
 - Keep XDRs under 100 lines. 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.

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

@@ -24,12 +24,16 @@ Performs a structured review of code changes or files against the XDRs in the re
 
 1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
    - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
-   - Extract metadata first (validity status and applicability) to filter relevant XDRs before deep analysis. Treat `Validity: Draft` and `Validity: Retired` as inactive policy.
+   - Extract metadata first to decide whether each XDR should be used for the current review context.
+   - Check `Status:` first. Treat an omitted `Status:` as `Active`, and treat `Draft` and `Deprecated` XDRs as background only, not active policy.
+   - Check `Valid:` second. Keep only `Active` XDRs whose date window covers the current review moment.
+   - Check `Applied to:` third. Keep only active, in-window XDRs 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: XDR Review
 
-1. Cross-reference each file in scope against applicable XDRs.
+1. Cross-reference each file in scope against active, applicable XDRs.
    - **Drop any finding that cannot be traced to a specific rule in an Accepted XDR.** General good-practice observations, personal opinions, or inferred issues without an explicit XDR backing must not be reported.
    - Classify as ERROR (mandatory) or WARNING (advisory).
    - Include: location, description, XDR reference (file + line), suggestion.
@@ -50,7 +54,7 @@ Performs a structured review of code changes or files against the XDRs in the re
 ### Phase 5: Reporting
 
 **Report template**
---------
+```text
 ### Code Review Against XDRs
 Scope: [scope identifier]
 
@@ -68,7 +72,7 @@ Scope: [scope identifier]
 - Errors: [count]
 - Warnings: [count]
 - Outcome: [PASS|FAIL]
---------
+```
 
 ### Constraints
 - MUST NOT include any text or explanations outside the required output format.
@@ -84,6 +88,6 @@ Scope: [scope identifier]
 
 ## References
 
-- [_core-adr-001 - XDR standards](../../../.xdrs/_core/adrs/principles/001-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../../.xdrs/_core/adrs/principles/003-skill-standards.md)
+- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
 

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 and decision-focused.
+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
@@ -71,8 +74,9 @@ Use the mandatory template from `001-xdr-standards`:
 
 ## Metadata
 [Optional. Include only when at least one metadata field is present]
+Status: [Optional. Use Draft, Active, or Deprecated. Defaults to Active when omitted]
+Valid: [Optional. Use from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD]
 Applied to: [Optional short applicability scope, under 40 words]
-Validity: [Optional. Use Draft, Retired, from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD]
 
 ## Context and Problem Statement
 [4 lines max: background, who is impacted, and the explicit question being answered]
@@ -93,9 +97,10 @@ Validity: [Optional. Use Draft, Retired, from YYYY-MM-DD, until YYYY-MM-DD, or f
 ```
 
 Mandatory rules to apply while drafting:
-- Include `## Metadata` only when `Applied to:` and/or `Validity:` adds value; omit the whole section when neither field is defined.
+- Include `## Metadata` only when `Status:`, `Valid:`, and/or `Applied to:` adds value; omit the whole section when none of those fields is defined.
 - When present, place `## Metadata` immediately before `## Context and Problem Statement`.
-- Keep `Applied to:` under 40 words and use `Validity:` only with ISO dates or the special values `Draft` / `Retired`.
+- Keep `Applied to:` under 40 words, use `Status:` only with `Draft`, `Active`, or `Deprecated`, remember that omitted `Status:` means `Active`, and use `Valid:` only with ISO date ranges.
+- When metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `Status:` controls lifecycle state, omitted `Status:` means `Active`, `Valid:` controls the active time window, `Applied to:` narrows the contexts where that active 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.
@@ -111,7 +116,7 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 100 lines? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Metadata**: If metadata exists, is it directly before Context, limited to `Applied to:` / `Validity:`, and omitted entirely when both are absent?
+2. **Metadata**: If metadata exists, is it directly before Context, limited to `Status:` / `Valid:` / `Applied to:`, omitted entirely when all three are absent, and specific enough for a reader to decide whether the XDR is active, 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?
@@ -131,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
@@ -47,7 +50,8 @@ Quick test:
 
 1. List `.xdrs/[scope]/[type]/[subject]/skills/` for existing skills. If one already covers the goal, extend or reference it instead of creating a duplicate.
 2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
-3. Decide whether the skill is merely guidance or is being referenced by an XDR as a mandatory procedure. Do not encode policy in the skill unless it comes from a referenced XDR.
+3. Evaluate XDR metadata before operationalizing those rules. `Status:` decides whether a decision is eligible to be used, and omitted `Status:` means `Active`; `Valid:` decides whether that active decision is in force at the current moment, `Applied to:` decides whether it fits the intended task context, and the decision text defines any remaining boundaries. Keep inactive, out-of-window, or out-of-scope XDRs as background only.
+4. Decide whether the skill is merely guidance or is being referenced by an XDR as a mandatory procedure. Do not encode policy in the skill unless it comes from a referenced XDR.
 
 ### Phase 4: Write the SKILL.md
 
@@ -92,6 +96,7 @@ Rules:
 - Mention tools or prerequisites when they are required to complete the task reliably.
 - Do not duplicate content from referenced XDRs — link instead.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced XDRs or other policy artifacts.
+- When the skill depends on XDRs, make the activation logic and instructions consistent with the XDR metadata so the skill does not operationalize inactive or out-of-scope decisions.
 - Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
 - If `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/assets/` and link with a relative path.
 - No emojis. Lowercase filenames. Target under 500 lines.
@@ -120,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`.
@@ -43,8 +47,9 @@ If the article spans more than one subject, place it in `principles`.
 ### Phase 4: Research XDRs and Skills to Synthesize
 
 1. Read all XDRs, Research documents, and Skills relevant to the article topic across all scopes listed in `.xdrs/index.md`.
-2. Identify the key points a reader needs to understand the topic end-to-end.
-3. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
+2. Evaluate XDR metadata before synthesizing guidance. Use `Status:` to determine whether a decision is eligible to be current guidance, treating omitted `Status:` as `Active`; use `Valid:` to determine whether that active decision is in force for the article's time horizon, `Applied to:` to determine whether it fits the audience or context being discussed, and the decision text itself for any remaining applicability boundaries.
+3. Identify the key points a reader needs to understand the topic end-to-end.
+4. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
 
 ### Phase 5: Write the Article
 
@@ -71,6 +76,7 @@ Rules to apply while drafting:
 
 - Write for the stated audience; avoid jargon unexplained elsewhere.
 - Every factual claim must link back to the authoritative XDR or Skill.
+- If the article advises readers what to do, clearly separate active/applicable XDRs from background, historical, or out-of-scope ones.
 - Never reproduce decision text verbatim; summarize and link.
 - Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
 - If the article genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/articles/assets/` and link with a relative path.
@@ -109,8 +115,15 @@ 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](../../004-article-standards.md)
-- [_core-adr-006 - Research standards](../../006-research-standards.md)
-- [_core-adr-001 - XDR standards](../../001-xdr-standards.md)
+- [_core-adr-004 - Article standards](../../../.xdrs/_core/adrs/principles/004-article-standards.md)
+- [_core-adr-006 - Research standards](../../../.xdrs/_core/adrs/principles/006-research-standards.md)
+- [_core-adr-001 - XDR standards](../../../.xdrs/_core/adrs/principles/001-xdr-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

@@ -14,7 +14,7 @@ This project defines a standard for organizing XDRs that satisfies the following
 
 Every XDR package contains four types of documents:
 
-- **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth. An XDR may optionally start with a `Metadata` section for short applicability and validity markers.
+- **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth. An XDR may optionally start with a `Metadata` section for short status, validity-window, and applicability markers, and readers should use that metadata to decide whether the decision is currently in force for their case. If `Status:` is omitted, treat the decision as `Active` by default.
 - **Research** — Exploratory documents that capture the problem being investigated, constraints or requirements, findings, and option tradeoffs that back a decision during its lifecycle. One research document may inform multiple downstream decisions, but it is not a replacement for the Decision Record.
 - **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. Skills are task-based artifacts with a concrete outcome and should include enough detail to verify the task was completed correctly. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
 - **Articles** — Synthetic explanatory texts that combine information from multiple XDRs, Research documents, and Skills around a specific topic or audience. They never replace XDRs as source of truth.
@@ -57,7 +57,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - research numbering uniqueness per `scope/type/subject/researches`
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
-- XDR metadata section placement and `Applied to` / `Validity` field format
+- XDR metadata section placement and `Status` / `Valid` / `Applied to` field format
 - local image and `assets/` links resolving inside the sibling `assets/` folder for each document
 
 Examples:
@@ -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. 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
@@ -93,6 +133,7 @@ The folder layout, file naming, and document format are designed so that AI agen
 - Each XDR is a small, focused Markdown file (target under 100 lines), covering one decision.
 - The canonical index per scope and type lists all XDRs with short descriptions, enabling agents to identify relevant records without reading every file.
 - The root index at `.xdrs/index.md` provides a single entry point for discovery.
+- XDR metadata gives agents a first-pass filter: check `Status` first, treating an omitted `Status` as `Active`; then check `Valid`, then `Applied to`, and finally the decision text itself to confirm the decision should be used in the current context.
 - Decisions cross-reference each other by XDR ID rather than duplicating content, keeping individual files concise.
 - Subject folders reduce the search space when a query maps to a known domain.
 

package/lib/index.js

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