xdrs-core 0.9.0 → 0.10.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"
@@ -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`, 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
 
@@ -71,8 +71,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 +94,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 +113,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?

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

@@ -47,7 +47,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 +93,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.

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

@@ -43,8 +43,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 +72,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.
@@ -111,6 +113,6 @@ Rules to apply while drafting:
 
 ## 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/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:
@@ -93,6 +93,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/lint.js

@@ -279,10 +279,11 @@ function lintXdrMetadata(content, filePath, errors) {
         start: metadataLine + 1,
         end: (headingLines.find((lineIndex) => lineIndex > metadataLine) ?? lines.length) - 1
       };
+  const statusLineNumbers = findFieldLines(lines, ignoredLines, 'Status:');
   const appliedLineNumbers = findFieldLines(lines, ignoredLines, 'Applied to:');
-  const validityLineNumbers = findFieldLines(lines, ignoredLines, 'Validity:');
+  const validLineNumbers = findFieldLines(lines, ignoredLines, 'Valid:');
 
-  if (!metadataRange && (appliedLineNumbers.length > 0 || validityLineNumbers.length > 0)) {
+  if (!metadataRange && (statusLineNumbers.length > 0 || appliedLineNumbers.length > 0 || validLineNumbers.length > 0)) {
     errors.push(`XDR metadata fields require a ## Metadata section immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
     return;
   }
@@ -291,28 +292,34 @@ function lintXdrMetadata(content, filePath, errors) {
     return;
   }
 
+  const metadataStatus = statusLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
   const metadataApplied = appliedLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
-  const metadataValidity = validityLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+  const metadataValid = validLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
 
-  if (metadataApplied.length === 0 && metadataValidity.length === 0) {
+  if (metadataStatus.length === 0 && metadataApplied.length === 0 && metadataValid.length === 0) {
     errors.push(`XDR metadata section must be omitted when no metadata fields are defined: ${toDisplayPath(filePath)}`);
   }
 
+  if (metadataStatus.length > 1) {
+    errors.push(`XDR metadata must not repeat Status: ${toDisplayPath(filePath)}`);
+  }
+
   if (metadataApplied.length > 1) {
     errors.push(`XDR metadata must not repeat Applied to: ${toDisplayPath(filePath)}`);
   }
 
-  if (metadataValidity.length > 1) {
-    errors.push(`XDR metadata must not repeat Validity: ${toDisplayPath(filePath)}`);
+  if (metadataValid.length > 1) {
+    errors.push(`XDR metadata must not repeat Valid: ${toDisplayPath(filePath)}`);
   }
 
-  for (const lineIndex of [...appliedLineNumbers, ...validityLineNumbers]) {
+  for (const lineIndex of [...statusLineNumbers, ...appliedLineNumbers, ...validLineNumbers]) {
     if (!isLineInsideRange(lineIndex, metadataRange)) {
       errors.push(`XDR metadata fields must be declared inside ## Metadata: ${toDisplayPath(filePath)}`);
       break;
     }
   }
 
+  let previousFieldOrder = -1;
   for (let lineIndex = metadataRange.start; lineIndex <= metadataRange.end; lineIndex += 1) {
     if (ignoredLines[lineIndex]) {
       continue;
@@ -321,10 +328,26 @@ function lintXdrMetadata(content, filePath, errors) {
     if (trimmed === '') {
       continue;
     }
-    if (!trimmed.startsWith('Applied to:') && !trimmed.startsWith('Validity:')) {
-      errors.push(`XDR metadata section only supports Applied to: and Validity: fields: ${toDisplayPath(filePath)}`);
+    const currentFieldOrder = trimmed.startsWith('Status:')
+      ? 0
+      : trimmed.startsWith('Valid:')
+        ? 1
+        : trimmed.startsWith('Applied to:')
+          ? 2
+          : -1;
+    if (currentFieldOrder === -1) {
+      errors.push(`XDR metadata section only supports Status:, Valid:, and Applied to: fields: ${toDisplayPath(filePath)}`);
       break;
     }
+    if (currentFieldOrder < previousFieldOrder) {
+      errors.push(`XDR metadata fields must be ordered as Status:, Valid:, Applied to: ${toDisplayPath(filePath)}`);
+      break;
+    }
+    previousFieldOrder = currentFieldOrder;
+  }
+
+  if (metadataStatus.length === 1) {
+    lintStatusField(lines[metadataStatus[0]], filePath, errors);
   }
 
   if (metadataApplied.length === 1) {
@@ -336,33 +359,37 @@ function lintXdrMetadata(content, filePath, errors) {
     }
   }
 
-  if (metadataValidity.length === 1) {
-    lintValidityField(lines[metadataValidity[0]], filePath, errors);
+  if (metadataValid.length === 1) {
+    lintValidField(lines[metadataValid[0]], filePath, errors);
   }
 }
 
-function lintValidityField(line, filePath, errors) {
-  const value = line.slice('Validity:'.length).trim().replace(/\.$/, '');
+function lintStatusField(line, filePath, errors) {
+  const value = line.slice('Status:'.length).trim().replace(/\.$/, '');
 
-  if (value === 'Draft' || value === 'Retired') {
-    return;
+  if (value !== 'Draft' && value !== 'Active' && value !== 'Deprecated') {
+    errors.push(`XDR Status: must be Draft, Active, or Deprecated: ${toDisplayPath(filePath)}`);
   }
+}
+
+function lintValidField(line, filePath, errors) {
+  const value = line.slice('Valid:'.length).trim().replace(/\.$/, '');
 
-  const validityMatch = value.match(/^(?:from\s+(\d{4}-\d{2}-\d{2}))?(?:\s+until\s+(\d{4}-\d{2}-\d{2}))?$/);
-  if (!validityMatch || (!validityMatch[1] && !validityMatch[2])) {
-    errors.push(`XDR Validity: must be Draft, Retired, from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD: ${toDisplayPath(filePath)}`);
+  const validMatch = value.match(/^(?:from\s+(\d{4}-\d{2}-\d{2})(?:\s+until\s+(\d{4}-\d{2}-\d{2}))?|until\s+(\d{4}-\d{2}-\d{2}))$/);
+  if (!validMatch) {
+    errors.push(`XDR Valid: must be from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD: ${toDisplayPath(filePath)}`);
     return;
   }
 
-  const fromDate = validityMatch[1];
-  const untilDate = validityMatch[2];
+  const fromDate = validMatch[1];
+  const untilDate = validMatch[2] ?? validMatch[3];
   if ((fromDate && !isIsoDate(fromDate)) || (untilDate && !isIsoDate(untilDate))) {
-    errors.push(`XDR Validity: must use ISO dates in YYYY-MM-DD format: ${toDisplayPath(filePath)}`);
+    errors.push(`XDR Valid: must use ISO dates in YYYY-MM-DD format: ${toDisplayPath(filePath)}`);
     return;
   }
 
   if (fromDate && untilDate && fromDate > untilDate) {
-    errors.push(`XDR Validity: from date must be on or before until date: ${toDisplayPath(filePath)}`);
+    errors.push(`XDR Valid: from date must be on or before until date: ${toDisplayPath(filePath)}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",