xdrs-core 0.13.0 → 0.14.2

package/.xdrs/_core/adrs/index.md

@@ -12,12 +12,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-004](principles/004-article-standards.md) - **Article standards** — How to write synthetic views combining XDRs, research, and skills
 - [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages** — How to version XDR packages to communicate upgrade impact
 - [_core-adr-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing XDR decisions
-
-## Research
-
-Exploratory documents that back decisions during their lifecycle.
-
-- [_core-research-001](principles/researches/001-research-and-decision-lifecycle.md) - **Research and decision lifecycle** (how research supports XDRs, skills, and articles)
+- [_core-adr-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
 
 ## Skills
 
@@ -28,6 +23,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
 - [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
 - [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
+- [006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
 
 ## Articles
 

package/.xdrs/_core/adrs/principles/001-xdrs-core.md

@@ -24,20 +24,24 @@ Collectively, these are referred to as XDRs.
 #### General framework standards
 
 - The main document type in the collection of XDRs is the XDR document, which contains a decision. Other documents are normally related to this decision and shouldn't go against its contents.
+- All documents in the framework should be removed when they are no longer necessary. The latest version of the collection always represents the active set of documents. Historical versions are available via versioned packages or git history. There is no status field on documents; if a document is present, it is considered active and valid. This keeps the document base clean and avoids confusion about which documents are current. REJECT any indication in the Decisions that contradicts this rule to avoid confusion and complexity.
 - 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:
+- ALWAYS use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
+- ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
 - 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`
+  - `.xdrs/[scope]/[type]/[subject]/plans/[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; `_core-adr-002` defines the XDR document writing standard.
   - `_core-adr-002` defines XDR standards (document writing)
   - `_core-adr-003` defines skill standards
   - `_core-adr-004` defines article standards
   - `_core-adr-006` defines research standards
+  - `_core-adr-007` defines plan 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/`
@@ -119,6 +123,9 @@ subject/
 |-- articles/
 |   |-- 001-article.md
 |   `-- assets/
+|-- plans/
+|   |-- 001-plan.md
+|   `-- assets/
 |-- researches/
 |   |-- 001-study.md
 |   `-- assets/
@@ -136,3 +143,4 @@ subject/
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)
+- [_core-adr-007 - Plan standards](007-plan-standards.md)

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

@@ -6,9 +6,9 @@ XDR framework elements (types, scopes, subjects, folder structure) are defined i
 
 ## Decision Outcome
 
-**Structured decision records with a mandatory template, lifecycle metadata, and clear conflict rules**
+**Structured decision records with a mandatory template, applicability metadata, and clear conflict rules**
 
-XDR documents are the authoritative policy for their scope, type, and subject. They must be concise, template-compliant, and lifecycle-aware so that humans and AI agents can reliably determine whether and how to apply any decision.
+XDR documents are the authoritative policy for their scope, type, and subject. They must be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
 
 ### Implementation Details
 
@@ -16,25 +16,23 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 - 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 (like articles, researches and skills), 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.
+  - `Valid:` Optional. Defines a convergence date after which the decision is expected to be fully adopted. Use ISO date format: `from YYYY-MM-DD`. New implementations SHOULD adopt the decision immediately, but compliance is not enforced during reviews until the convergence date.
   - `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`
+- All documents present in the collection are considered active. There is no status field. When a decision is no longer relevant, valid or active, it must be removed from the collection. Historical versions are available via versioned packages or git history.
 - Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is applicable 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 `Valid:` first. If a convergence date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
+  - Check `Applied to:` next to determine whether the 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.
+- 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, and updates of XDRs, but the XDR document remains the source of truth.
 - **XDR Id:** [scope]-[type]-[xdr number] (numbers are scoped per type+scope combination and must not be reused within that combination; 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.
-- 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.
+- 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 applicability, then keep nuanced boundaries in the decision text.
 - Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the 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.
+  - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, removed, 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.
@@ -53,9 +51,8 @@ All XDRs MUST follow this template
 
 ## Metadata
 
-[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`]
+[Optional section. Omit the entire section when none of `Valid:` or `Applied to:` is defined. Readers decide whether to use the XDR by checking `Valid:` first, then `Applied to:`, and finally the decision text itself.]
+Valid: [Optional. Use `from YYYY-MM-DD` to set a convergence date for adoption]
 Applied to: [Optional short applicability scope, under 40 words]
 
 ## Context and Problem Statement
@@ -97,9 +94,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 **Examples:**
 - Metadata examples:
-  - `Status: Draft`
-  - `Status: Active`
-  - `Valid: from 2026-03-01 until 2026-12-31`
+  - `Valid: from 2026-03-01`
   - `Applied to: JavaScript projects`
 
 **XDR ID Examples:**

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

@@ -31,7 +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.
+- When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `Valid:` determines the convergence date for adoption, `Applied to:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat 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

@@ -19,7 +19,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - 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.
 - In more complex cases, an article may be an index of links to other articles, grouping related documentation into a single entry point that guides readers across a set of related topics.
-- 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.
+- When an article tells readers which decisions to follow, it SHOULD check `Valid:` first to determine the convergence date, `Applied to:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles must not present 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/006-research-standards.md

@@ -59,7 +59,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/_local/adrs/principles/researches/001-research-and-decision-lifecycle.md`
 - `.xdrs/business-x/adrs/platform/researches/003-api-gateway-options.md`
 - `.xdrs/_local/edrs/application/researches/002-model-serving-constraints.md`
 
@@ -115,7 +115,7 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 
 ## Considered Options
 
-- Related research: [001-research-and-decision-lifecycle](researches/001-research-and-decision-lifecycle.md)
+- Related research: [001-research-and-decision-lifecycle](../../../_local/adrs/principles/researches/001-research-and-decision-lifecycle.md)
 
 * (REJECTED) **Inline long-form analysis inside the XDR** - Put all research and decision text in one file.
   * Reason: Makes XDRs too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.

package/.xdrs/_core/adrs/principles/007-plan-standards.md

@@ -0,0 +1,132 @@
+# _core-adr-007: Plan standards
+
+## Context and Problem Statement
+
+Teams need a structured way to describe a problem, propose a solution, and lay out the approach and activities needed to solve it. Without a standard format, planning documents drift in structure and completeness, making it hard to assess scope, track progress, and verify that a plan was fully implemented.
+
+How should plans be structured and organized so they provide clear guidance for execution while remaining connected to the decisions, research, and skills they relate to?
+
+## Decision Outcome
+
+**Subject-level ephemeral plan documents co-located with XDRs**
+
+Plans are Markdown documents placed inside a subject folder alongside decision records. They describe a problem, a proposed solution, and the approach to solve it. Plans have a clear start and end and a well-defined scope.
+
+### Implementation Details
+
+- Plans describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
+- Plans are NOT the source of truth. When a plan and an XDR disagree, the XDR takes precedence.
+- Plans are ephemeral. They MUST be deleted after full implementation. The lasting outputs of a plan are actual actions or Decisions, Skills, Articles, Research documents, and other artifacts that result from execution.
+- Plans may be used to implement a certain Decision. They may also use Research documents to help with the planning process. Articles may be written on top of a plan to give more context and connect more details present in other decisions and research to people involved in the plan.
+- During the implementation of a plan, new Decisions, Articles, Skills, Research documents, and even other Plans may be created. Always link all related elements to each other.
+- A plan can be high level, describing only one milestone, or more complex, describing a WBS (work breakdown structure) along with owners, multiple milestones in a tactical sequence, and checklists to verify completeness. Actual tasks performed by actors should normally be tracked in specialized software such as GitHub or Azure DevOps.
+- The total time to deliver a plan should not be more than 2 years. If more time is needed, create a new plan later with what was learned.
+- Plans MUST live under `plans/` inside the relevant subject folder: `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
+- Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD).
+- Always use lowercase file names.
+- Never use emojis in plan content.
+- Images and other local resource files referenced by a plan SHOULD live in `plans/assets/` next to the plan files.
+
+**Folder layout**
+
+```
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        plans/
+          [number]-[short-title].md
+          assets/
+```
+
+Examples:
+- `.xdrs/_local/adrs/principles/plans/001-checkout-performance.md`
+- `.xdrs/business-x/bdrs/product/plans/002-onboarding-redesign.md`
+
+**Plan numbering**
+
+- Each plan has a number unique within its `scope/type/subject/plans/` namespace.
+- Determine the next number by checking the highest number already present in that namespace.
+- Never reuse numbers of deleted plans. Gaps in the sequence are expected and allowed.
+
+**Plan template**
+
+All plans MUST follow this template:
+
+```markdown
+# [scope]-plan-[number]: [Short Title]
+
+## Executive Summary
+
+[Required. A summary of all sections below using bullet points, focused on the most important items. Under 500 words.]
+
+## Context and Problem Statement
+
+[Required. Describe clearly why we are executing this plan. What is the impact? Who is impacted? Why is this important? Under 200 words.
+E.g.: Our checkout abandon rate is 50%, and it's increasing over time.]
+
+## Proposed Solution
+
+[Required. What we expect to achieve to solve the problem described above. Under 200 words.
+E.g.: Reduce payment time in our App by 30% and fix the 3 most impactful bugs.]
+
+## Acceptance Criteria
+
+[Optional. Used to make it clear what the expected result is and to create a way to verify when the goal is achieved. May include a short checklist. Under 100 words.]
+
+Expected end date: YYYY-MM-DD
+
+## Approach
+
+[Optional. High level description about how to achieve the result and the strategy used, including how to engage people, projects, organize the work, how to learn unknowns, deal with risks, and distribute workload. May include a WBS with the hierarchy of the work. Under 300 words.]
+
+## Key Deliverables
+
+[Optional. List of the main features, goods, artifacts, data, articles, skills, decisions, training, programs, events etc that will be important to achieve the expected result. Under 300 words.]
+
+## Key Resources
+
+[Optional. List of equipment, people, other project results, budget, areas or dependencies that need to be engaged or allocated for this plan to be implemented. Under 100 words.]
+
+## Milestones
+
+[Optional. List of goals to be followed along with an optional acceptance criteria, owner and due date. Each milestone may have a checklist used as acceptance criteria verification. Key tasks and risks can be listed as part of a milestone. Under 1000 words per milestone.]
+
+### Milestone 1: [Title]
+Owner: [name or team]
+Due date: YYYY-MM-DD
+
+[Description of the milestone goal.]
+
+**Acceptance checklist:** [optional]
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+**Key tasks:**
+- [Task description]
+
+**Risks:** [optional]
+- [Risk description] — Mitigation: [strategy]
+
+## Risks Identified
+
+[Optional. List of risks along with a short description and mitigation strategy. Under 1000 words.]
+
+## References
+
+- [Related XDR or artifact](relative/path.md) - Brief description of relevance
+```
+
+## Considered Options
+
+* (REJECTED) **Inline planning in XDRs** — Embed planning details inside decision records.
+  * Reason: Plans are ephemeral execution documents while XDRs are lasting decisions. Mixing them bloats XDRs and creates confusion about what to delete after execution.
+* (CHOSEN) **Subject-level plans folder co-located with XDRs** — Keeps plans alongside the decisions they implement, with clear lifecycle expectations.
+  * Reason: Consistent with how skills, articles, and research are organized. The explicit deletion requirement after implementation keeps the document base clean.
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
+- [_core-adr-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
+- [_core-adr-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
+- [006-write-plan skill](skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan

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

@@ -19,7 +19,7 @@ same decision system.
   technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
   implementation decisions. See [_core-adr-001](../001-xdrs-core.md).
 - **Research** captures exploration before or around a decision: constraints, findings, options,
-  pros, and cons. Research supports elaboration, discussion, approval, retirement, and updates,
+  pros, and cons. Research supports elaboration, discussion, and updates,
   but it is not the final rule. A single Research document may inform multiple downstream ADRs,
   BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
   [_core-adr-006](../006-research-standards.md).
@@ -30,6 +30,10 @@ same decision system.
 - **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
   Research documents, and Skills, helping readers understand the system without making new
   decisions. See [_core-adr-004](../004-article-standards.md).
+- **Plans** describe a problem, a proposed solution, and the approach and activities needed to
+  solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
+  must be deleted after full implementation, with lasting outputs captured as Decisions, Skills,
+  Articles, or other artifacts. See [_core-adr-007](../007-plan-standards.md).
 - **Indexes and folder structure** are the discovery layer. They do not make decisions by
   themselves, but they determine how people and agents find the right artifacts, how scopes
   override one another, and how a large set of decisions remains navigable.
@@ -42,6 +46,7 @@ The easiest way to distinguish the central elements is by asking what job each o
 - **Research**: "What did we learn while evaluating options?"
 - **Skill**: "How do we carry out work under this decision?"
 - **Article**: "How do these artifacts fit together for a reader?"
+- **Plan**: "What are we going to do, why, and how?"
 - **Index/Scope structure**: "Where do I look, and which decision set takes precedence?"
 
 This separation matters because mixing these jobs into one file makes the system harder to search,
@@ -49,13 +54,14 @@ 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.
+Before treating an XDR as a rule for the current case, check its metadata first. All documents present in the collection are considered active — if a document exists, it is current.
 
-- **Status first**: only `Active` decisions can be current policy, and omitted `Status` is 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.
+- **Valid first**: if present, the convergence date indicates when full adoption is expected. New implementations SHOULD adopt the decision immediately; compliance is not enforced during reviews until the date.
+- **Applied to second**: if present, the current codebase, workflow, system, or audience must fit that scope.
 - **Decision text last**: the XDR's own context and implementation details still determine the final boundaries and exceptions.
-- **Then enforce**: only decisions that pass those checks should be used as active requirements. The rest may still be useful background or historical context.
+- **Then enforce**: only decisions that pass those checks should be used as active requirements. The rest may still be useful context.
+
+Documents that are no longer relevant should be removed from the collection. Historical versions are available via versioned packages or git history.
 
 ### How they relate over time
 
@@ -99,6 +105,8 @@ Every decision record and its supporting artifacts live at a fixed path:
             SKILL.md
         articles/
           [number]-[short-title].md
+        plans/
+          [number]-[short-title].md
 ```
 
 - **Scopes** represent ownership domains such as `_core`, `business-x`, or `team-43`.
@@ -135,7 +143,8 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 
 - 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.
+- Before citing an XDR as a requirement, check `Valid` first, then `Applied to`, and finally the decision text to confirm the decision is in scope for the current case.
+- All documents present in the collection are considered active. Remove documents that are no longer relevant.
 - Keep XDRs under 1300 words as a rule of thumb (exceptions up to 2600 words for templates or more elaborate decisions). Move procedural detail to a co-located Skill.
 - Keep exploratory option analysis in a co-located Research document instead of bloating the XDR.
 - Always update the scope+type index and the root index after adding or changing an XDR.
@@ -153,6 +162,8 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
   folder, following [_core-adr-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
   folder, following [_core-adr-004](../004-article-standards.md).
+- **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
+  folder, following [_core-adr-007](../007-plan-standards.md).
 
 ### Using XDRs in your own project
 
@@ -175,6 +186,7 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 - [_core-adr-003](../003-skill-standards.md) - Skill standards and co-location rules
 - [_core-adr-004](../004-article-standards.md) - Article standards
 - [_core-adr-006](../006-research-standards.md) - Research standards
+- [_core-adr-007](../007-plan-standards.md) - Plan standards
 - [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
 - [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
 - [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill

package/.xdrs/_core/adrs/principles/skills/001-lint/001-lint.test.int.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const path = require('path');
+const { copilotCmd, testPrompt } = require('xdrs-core');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
+
+jest.setTimeout(300000);
+
+test('smoke test', async () => {
+	const err = await testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'in-place',
+			...copilotCmd(REPO_ROOT),
+		},
+		'Reply ONLY with "READY" after checking if SKILL 001 has any contents',
+		'Verify that the final output is ONLY "READY" and that it read file 001-lint/SKILL.md',
+		null,
+		true
+	);
+
+	expect(err).toBe('');
+});
+
+test('001-lint outputs the required review template', async () => {
+	const err = await testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'copy',
+			...copilotCmd(REPO_ROOT),
+		},
+		'Review xdr 001-xdrs-core',
+		'Verify that the skill 001-lint was used, contains "## Findings", and "## Summary", includes an "Outcome: PASS", and that it read file 001-lint/SKILL.md and 001-xdrs-core.md.',
+		null,
+		true
+	);
+
+	expect(err).toBe('');
+});

package/.xdrs/_core/adrs/principles/skills/001-lint/001-lint.test.int.report

@@ -0,0 +1,23 @@
+{
+  "Review xdr 001-xdrs-core-ac1c8339": {
+    "result": "success",
+    "contextFiles": [
+      ".xdrs/_core/adrs/index.md",
+      ".xdrs/_core/adrs/principles/001-xdrs-core.md",
+      ".xdrs/_core/adrs/principles/002-xdr-standards.md",
+      ".xdrs/_core/adrs/principles/skills/001-lint/SKILL.md",
+      ".xdrs/_local/bdrs/index.md",
+      ".xdrs/index.md",
+      "AGENTS.md"
+    ],
+    "contextHash": "98562e9ef1410e8976d719391a098ab3"
+  },
+  "Reply ONLY with \"READY\" after checking i-a61b0904": {
+    "result": "success",
+    "contextFiles": [
+      ".xdrs/_core/adrs/principles/skills/001-lint/SKILL.md",
+      "AGENTS.md"
+    ],
+    "contextHash": "dc167dc47aab0f4de26ddbcd4fa979b4"
+  }
+}

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

@@ -25,9 +25,9 @@ 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 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.
+   - All documents present in the collection are considered active.
+   - Check `Valid:` first. If a convergence date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
+   - Check `Applied to:` second. Keep only 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.
 

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

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

package/.xdrs/_core/adrs/principles/skills/002-write-xdr/002-write-xdr.test.int.report

@@ -0,0 +1,14 @@
+{
+  "Create a very small XDR deciding to use -8b1a2ddd": {
+    "result": "success",
+    "contextFiles": [
+      ".xdrs/_core/adrs/principles/001-xdrs-core.md",
+      ".xdrs/_core/adrs/principles/002-xdr-standards.md",
+      ".xdrs/_local/bdrs/index.md",
+      ".xdrs/_local/bdrs/operations/001-agent-behavior-validation-procedure.md",
+      ".xdrs/index.md",
+      "AGENTS.md"
+    ],
+    "contextHash": "5ceaa69409aa5eff1728d3a4212865a0"
+  }
+}

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

@@ -52,7 +52,7 @@ Choose a title that clearly states the question this XDR answers, not the answer
 ### Phase 4: Research Related XDRs
 
 1. Read all existing XDRs relevant to the topic across all scopes listed in `.xdrs/index.md`.
-2. Evaluate XDR metadata before treating any decision as a current constraint. `Status:` decides whether a decision is eligible to be used, and omitted `Status:` means `Active`; `Valid:` decides whether that active decision is currently in force, `Applied to:` decides whether it fits the current topic, and the decision text defines any remaining boundaries. Treat inactive, out-of-window, or out-of-scope XDRs as background only when assessing overlaps and conflicts.
+2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `Valid:` determines the convergence date for adoption, `Applied to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
 3. Identify decisions that already address the topic (full or partial overlap).
 4. Note decisions that might conflict with the intended outcome.
 5. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
@@ -76,8 +76,7 @@ Use the mandatory template from `002-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]
+Valid: [Optional. Use from YYYY-MM-DD to set a convergence date for adoption]
 Applied to: [Optional short applicability scope, under 40 words]
 
 ## Context and Problem Statement
@@ -99,10 +98,10 @@ Applied to: [Optional short applicability scope, under 40 words]
 ```
 
 Mandatory rules to apply while drafting:
-- Include `## Metadata` only when `Status:`, `Valid:`, and/or `Applied to:` adds value; omit the whole section when none of those fields is defined.
+- Include `## Metadata` only when `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, 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.
+- Keep `Applied to:` under 40 words and use `Valid:` only with `from YYYY-MM-DD` format.
+- When metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `Valid:` sets a convergence date for adoption, `Applied to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced XDRs — link instead.
 - Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
@@ -118,7 +117,7 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **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?
+2. **Metadata**: If metadata exists, is it directly before Context, limited to `Valid:` / `Applied to:`, omitted entirely when both are absent, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
 3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
 5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
@@ -135,6 +134,15 @@ If any check fails, revise and re-run this phase before proceeding.
 4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Implementation Details` without turning the XDR into a long procedure.
 
+### Phase 9: Verify Package structure with Lint
+
+1. Run the CLI lint utility from the repository root:
+   ```
+   npx -y xdrs-core lint .
+   ```
+2. Fix all reported errors before considering the task complete.
+3. Review warnings; fix straightforward ones and note intentional deviations explicitly.
+
 ### Constraints
 
 - MUST follow the XDR template from `002-xdr-standards` exactly.

package/.xdrs/_core/adrs/principles/skills/003-write-skill/003-write-skill.test.int.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const path = require('path');
+const { copilotCmd, testPrompt } = require('xdrs-core');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
+
+jest.setTimeout(300000);
+
+test('003-write-skill creates a devops skill package', async () => {
+	const err = await testPrompt(
+		{
+			workspaceRoot: REPO_ROOT,
+			workspaceMode: 'copy',
+			...copilotCmd(REPO_ROOT),
+		},
+		'Create a skill with instructions on how to do a call to a customer during a marketing campaign: - look for the phone number in the CRM opportunity, - read the proposal to be offered, - make the call, - maintain a friendly and professional tone, - report the outcome on CRM, - say "Thank you for your time".',
+		'Verify that SKILL.md was created under .xdrs/_local/bdrs/marketing/skills and has instructions about calling a customer, especifically about the tone of voice',
+		null,
+		true
+	);
+
+	expect(err).toBe('');
+});

package/.xdrs/_core/adrs/principles/skills/003-write-skill/003-write-skill.test.int.report

@@ -0,0 +1,14 @@
+{
+  "Create a skill with instructions on how -a7079882": {
+    "result": "success",
+    "contextFiles": [
+      ".xdrs/_core/adrs/principles/001-xdrs-core.md",
+      ".xdrs/_core/adrs/principles/003-skill-standards.md",
+      ".xdrs/_local/bdrs/index.md",
+      ".xdrs/_local/bdrs/operations/001-agent-behavior-validation-procedure.md",
+      ".xdrs/index.md",
+      "AGENTS.md"
+    ],
+    "contextHash": "738b99bad5adfe36fa14191c6c31ddab"
+  }
+}