xdrs-core 0.8.0 → 0.10.0

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

@@ -23,6 +23,17 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 
 - XDRs MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references.
 - XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision, but they do not replace it.
+- XDRs MAY include a `## Metadata` section, but only when at least one supported metadata field is present. When used, `## Metadata` MUST appear immediately before `## Context and Problem Statement`.
+- Supported XDR metadata fields are:
+  - `Status:` Optional. Defines the lifecycle state of the decision. Allowed values are `Draft`, `Active`, and `Deprecated`. If omitted, the decision is treated as `Active`. Only `Active` decisions may be treated as current policy.
+  - `Valid:` Optional. Defines the time window in which an active decision may be treated as current. Use ISO dates only: `from YYYY-MM-DD`, `until YYYY-MM-DD`, or `from YYYY-MM-DD until YYYY-MM-DD`. If `from` is omitted, the decision takes effect immediately. If `until` is omitted, the decision remains valid indefinitely.
+  - `Applied to:` Optional. A short description of the contexts in which the decision is applicable. Keep it under 40 words. If omitted, the decision should be interpreted as applying to all logically applicable elements according to the decision text itself. Examples: `Only frontend code`, `JavaScript projects`, `Performance-sensitive codebases`
+- Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is in force for the current case.
+  - Check `Status:` first to determine whether the XDR is eligible to be used now. If `Status:` is omitted, treat it as `Active`. `Draft` and `Deprecated` decisions are background or history, not current policy.
+  - Check `Valid:` next to determine whether the current moment falls inside the decision's active date window. Not-yet-active and expired windows are not current policy.
+  - Check `Applied to:` next to determine whether the active, currently valid decision fits the current codebase, system, workflow, or audience.
+  - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
+  - If any check fails, the XDR MAY still be read as background, history, or context, but it MUST NOT be treated as a current requirement for that case.
 - Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, approval, retirement, and updates, but the XDR remains the source of truth.
 - Make it clear if an instruction is mandatory or advisory
     - Mandatory language: "must", "always", "never", "required", "mandatory"
@@ -33,6 +44,12 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
   - `.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`
+- 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/`
+  - Articles use `.xdrs/[scope]/[type]/[subject]/articles/assets/`
+  - Research uses `.xdrs/[scope]/[type]/[subject]/researches/assets/`
+  - 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.
@@ -46,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 when the decision applies, relevant boundaries or exceptions, and what a reader should do or avoid in common cases.
+- 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
@@ -73,6 +90,13 @@ All XDRs MUST follow this template
 ```markdown
 # [scope]-[type]-[number]: [Short Title]
 
+## 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`]
+Applied to: [Optional short applicability scope, under 40 words]
+
 ## Context and Problem Statement
 
 [Describe the context, background, or need that led to this decision.
@@ -124,6 +148,27 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
 - `.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`
+
+```text
+subject/
+|-- 001-xdr.md
+|-- assets/
+|-- articles/
+|   |-- 001-article.md
+|   `-- assets/
+|-- researches/
+|   |-- 001-study.md
+|   `-- assets/
+`-- skills/
+    `-- 001-task/
+        |-- SKILL.md
+        `-- assets/
+```
 
 **XDR ID Examples:**
 - `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)

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:
@@ -50,7 +51,7 @@ Quick test:
     SKILL.md              # required
     scripts/              # optional: executable scripts the agent may run
     references/           # optional: detailed reference material
-    assets/               # optional: templates, images, data files
+    assets/               # optional: images, templates, data files, and other local resources
 ```
 
 Examples:
@@ -100,6 +101,8 @@ Rules:
 - The `name` field must match the parent directory name exactly (e.g., directory `001-code-review` uses `name: 001-code-review`). This preserves agentskills spec compliance while encoding the ordering number.
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
 - `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
+- For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
+- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and SHOULD live in `assets/` inside the same skill package.
 - Keep `SKILL.md` under 500 lines. Move lengthy reference material to `references/`.
 - Reference other files with relative paths from the skill root.
 - Always use lowercase file names.

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

@@ -17,8 +17,11 @@ 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.
+- Images and other local resource files referenced by an article SHOULD be used only when they are materially necessary and SHOULD live in `articles/assets/` next to the article files.
 - Always use lowercase file names.
 - Never use emojis in article content.
 - Articles should be kept under 150 lines. Move detailed content to referenced XDRs or Skills.
@@ -29,6 +32,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 .xdrs/[scope]/[type]/[subject]/
   articles/
     [number]-[short-title].md
+    assets/
 ```
 
 Examples:

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

@@ -4,13 +4,13 @@
 
 Teams often need more space than an XDR allows to evaluate constraints, explore options, and record findings before or after a decision changes. When that material is scattered across PR comments, docs, and chat, the reasoning behind a decision becomes hard to recover or update.
 
-Question: How should research documents be structured and organized so they support the decision lifecycle without replacing XDRs as the source of truth?
+Question: How should research documents be structured and organized so they communicate an investigated problem, evidence, and conclusions clearly, while remaining traceable from related XDRs?
 
 ## Decision Outcome
 
-**subject-level research documents co-located with XDRs**
+**IMRAD-based subject-level research documents co-located with XDRs**
 
-Research documents are Markdown files placed inside a subject folder alongside decision records. They capture the explored option space, relevant constraints, findings, and proposal tradeoffs that back a decision during elaboration, discussion, approval, retirement, and updates.
+Research documents are Markdown files placed inside a subject folder alongside decision records. They use an IMRAD-inspired paper structure adapted to company needs so teams can communicate investigated problems, methods, findings, and conclusions clearly, combine experienced professional judgment with good-enough evidence, preserve reproducibility where it matters, and revisit the work when technology, constraints, or facts change.
 
 ### Implementation Details
 
@@ -18,15 +18,31 @@ Research documents are Markdown files placed inside a subject folder alongside d
 - `Research` is the artifact name. `researches/` is only the folder name used alongside `skills/` and `articles/`.
 - Research documents MUST live under `researches/` inside the relevant subject folder:
   `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
-- Research documents SHOULD stay focused on one problem statement or decision thread.
-- Research documents MUST state clearly what problem or question is being investigated and who needs the result.
-- The `## Overview` section MUST end with a line in the form `Question: [central question]?` that states the central question the research answers.
-- Research constraints MAY include hard requirements, stack limitations, regulatory limits, or other conditions that narrow the option space.
-- Research documents MUST summarize the problem constraints, important findings, and a small set of proposals with pros and cons for each option.
-- Research proposals are the considered options for the decision thread. They are not the final policy.
-- Research documents SHOULD link to the XDRs, skills, articles, discussions, and external references they informed.
-- One research document MAY inform multiple XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation produced several downstream decisions.
-- Research documents SHOULD remain concise enough to read end-to-end. Target under 500 lines; hard limit 2000 lines.
+- Research documents SHOULD stay focused on one investigated problem, comparison, or hypothesis.
+- Research documents MUST state clearly what problem or question is being investigated, the relevant system or domain context, and why the subject matters in practice.
+- Research documents MUST follow this section order: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
+- Research uses a company-adapted IMRAD structure. It MAY include informed professional judgment and experience-based observations, but claims that affect the conclusion MUST have enough evidence to be teachable, reviewable, and useful to other colleagues.
+- Research does not require full academic statistical rigor. Use good-enough evidence that supports the conclusion without demanding exhaustive proof.
+- Research documents MUST read as standalone technical papers for readers who do not know the XDR process.
+- Mentions of future ADRs, decision lifecycle, repository process, or artifact management SHOULD be avoided in the body unless they are materially necessary to understand the research question.
+- Traceability to related XDRs, skills, articles, discussions, and external sources SHOULD live primarily in `## References` and surrounding indexes rather than in the body narrative.
+- Research documents MUST describe the methods, tools, sources, and conditions with enough detail that an experienced professional could at least minimally reproduce the important parts of the study, especially the aspects that materially affected the conclusion.
+- The short title portion after the research id MUST stay under 20 words.
+- `## Abstract` MUST be a single paragraph under 200 words summarizing the goal, methods, results, and conclusion. It SHOULD let a quick technical reader understand the question, method, main result, and takeaway.
+- `## Introduction` MUST define the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives. It SHOULD prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations, and SHOULD use external visuals only when they are materially necessary to improve understanding. It MUST stay under 700 words and MUST end with `Question: [central question]?`.
+- `## Methods` MUST explain how the study was conducted, including design, tools, data sources, and test conditions, with a reproducibility goal. It MUST stay under 1200 words.
+- `## Results` MUST present findings, data, trends, quantitative results, produced code, and option comparisons when relevant. It SHOULD prefer tables, bullet lists, or ASCII art for simple comparisons, and SHOULD use external figures only when they are materially necessary. Keep interpretation to a minimum. It MUST stay under 1800 words.
+- When different options for the same problem are being analyzed, `## Results` SHOULD include comparison tables and explicit pros and cons for each option so the trade-offs are directly inspectable.
+- `## Discussion` MUST interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications for technical readers. It MUST stay under 1000 words.
+- `## Conclusion` MUST summarize the main findings, practical takeaway, applicability boundaries, and important open questions. It MUST stay under 400 words.
+- `## References` MUST list all cited literature, websites, tutorials, documentation, discussions, or related artifacts.
+- In general, research SHOULD roughly follow the proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
+- Be strict about the goal of each section. Avoid duplicating the same material across sections and prefer clarity over rhetorical flourishes.
+- Research documents SHOULD stay under 5000 words total. They MAY exceed that only when the `## Introduction` explicitly states that the study will be lengthy because a very detailed analysis is required.
+- Research documents SHOULD link in `## References` to the XDRs, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
+- A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not required.
+- One research document MAY also be referenced by multiple XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
+- Images and other local resource files referenced by a research document SHOULD be used only when they are materially necessary and SHOULD live in `researches/assets/` next to the research files.
 - Research file names MUST be lowercase. Never use emojis.
 - A research document MAY exist before the related XDR is written, or remain after the XDR changes, as long as its status and references stay clear.
 
@@ -36,6 +52,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
 .xdrs/[scope]/[type]/[subject]/
   researches/
     [number]-[short-title].md
+    assets/
 ```
 
 Examples:
@@ -56,46 +73,39 @@ All research documents MUST follow this template:
 ```markdown
 # [scope]-research-[number]: [Short Title]
 
-## Overview
+## Abstract
 
-[Brief description of the problem or question being explored, who needs the result, and the decision thread(s) it supports. Under 5 lines.]
+[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. Under 200 words.]
 
-Question: [Central question of the research]?
-
-## Constraints
-
-- [Constraint or requirement 1]
-- [Constraint or requirement 2]
+## Introduction
 
-## Findings
+[Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
+Prefer bullets, tables, or ASCII art for simple explanations. Use external visuals only when they are materially necessary. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
 
-- [Important finding 1]
-- [Important finding 2]
-
-## Proposals
+Question: [Central question of the research]?
 
-### Option 1: [Name]
+## Methods
 
-[Short description of the option.]
+[Explain how the study was conducted, including design, tools, data sources, and test conditions.
+Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. Under 1200 words.]
 
-**Pros**
-- [Benefit 1]
-- [Benefit 2]
+## Results
 
-**Cons**
-- [Drawback 1]
-- [Drawback 2]
+[Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
+Prefer tables, bullets, or ASCII art for simple comparisons. Use external figures only when they are materially necessary. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
 
-### Option 2: [Name]
+## Discussion
 
-[Same structure as above for each meaningful option.]
+[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged and under 1000 words.]
 
-## Recommendation
+## Conclusion
 
-[Optional summary of the currently preferred direction, if any.]
+[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. Under 400 words.]
 
 ## References
 
+[A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
+
 - [Related XDR or artifact](relative/path.md) - Why it matters
 - [Another related XDR if this research informed multiple decisions](relative/path.md) - Why it matters
 ```
@@ -106,10 +116,8 @@ Question: [Central question of the research]?
 
 * (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.
-* (REJECTED) **Separate top-level research area outside the subject tree** - Centralize all research in one independent folder.
-  * Reason: Breaks proximity with the decisions it supports and makes subject-scoped discovery weaker.
-* (CHOSEN) **Subject-level research folder co-located with XDRs** - Keep exploratory material beside the decisions, skills, and articles it informs.
-  * Reason: Preserves lifecycle context, keeps the XDR concise, and makes the research easy to discover when revisiting or updating a decision.
+* (CHOSEN) **IMRAD-based subject-level research beside XDRs** - Keep exploratory material beside the decisions, skills, and articles it informs, using an IMRAD-inspired structure adapted to company work.
+  * Reason: Preserves lifecycle context, keeps the XDR concise, gives readers a predictable structure, and raises evidence quality without demanding full academic rigor.
 
 ## References
 

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 (status, impact, scope, applicability) to filter relevant XDRs before deep analysis.
+   - 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.

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, 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
 
@@ -53,13 +53,28 @@ Choose a title that clearly states the question this XDR answers, not the answer
 4. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
 5. Collect XDR IDs and file paths for cross-references.
 
-### Phase 5: Write the First Draft
+### Phase 5: Check Redundancy Across Related Artifacts
+
+1. Review the related XDRs, research documents, skills, articles, and guides connected to the same decision thread.
+2. Identify content that is repeated across those files, especially decision statements, applicability boundaries, mandatory rules, and rationale.
+3. Prioritize the final decision, core boundaries, and short key instructions in the XDR itself.
+4. When another document already explains details well, link to it instead of re-explaining the same content in full.
+5. Copy only short instructions or key excerpts when they materially help a reader apply the decision without leaving the XDR.
+6. Avoid repeating the same decision text across multiple related documents whenever a link or short reference is enough.
+
+### Phase 6: Write the First Draft
 
 Use the mandatory template from `001-xdr-standards`:
 
 ```
 # [scope]-[type]-[number]: [Short Title]
 
+## 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]
+
 ## Context and Problem Statement
 [4 lines max: background, who is impacted, and the explicit question being answered]
 
@@ -79,26 +94,35 @@ Use the mandatory template from `001-xdr-standards`:
 ```
 
 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.
+- 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.
 - 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.
 - Make clear when the decision applies and any important exception boundaries.
 - Keep exploratory option analysis in a related Research document when it would distract from the final decision text.
+- Prefer plain Markdown, tables, or ASCII art for simple structure, flow, layout, or relationship indications.
+- If the XDR genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/assets/` and link with a relative path.
 - No emojis. Lowercase filenames.
 - Target under 100 lines total; 200 lines max for complex decisions.
 
-### Phase 6: Review the Draft
+### Phase 7: Review the Draft
 
 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. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
-3. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
-4. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
-5. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
+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?
+6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
+7. **Index entries**: Will the new XDR be added to `[scope]/[type]/index.md` and `.xdrs/index.md`?
 
 If any check fails, revise and re-run this phase before proceeding.
 
-### Phase 7: Write Files
+### Phase 8: Write Files
 
 1. Create the XDR file at `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`.
 2. Add an entry to `.xdrs/[scope]/[type]/index.md` (create the file if it does not exist).
@@ -111,4 +135,5 @@ If any check fails, revise and re-run this phase before proceeding.
 - MUST follow the XDR template from `001-xdr-standards` exactly.
 - 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.
 - MUST keep scope `_local` unless the user explicitly states otherwise.

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,9 @@ 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.
 
 ### Phase 5: Review the Draft

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

@@ -1,11 +1,7 @@
 ---
 name: 004-write-article
 description: >
-   Creates a new article document following XDR article standards: selects scope, type, subject, and number;
-   then writes a focused synthetic text that combines and links multiple XDRs, Research documents,
-   and Skills around a topic.
-  Activate this skill when the user asks to create, add, or write a new article, guide, or overview document
-  within an XDR project.
+   Creates a new article document following XDR article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple XDRs, Research documents, and Skills around a topic. Activate this skill when the user asks to create, add, or write a new article, guide, or overview document within an XDR project.
 metadata:
   author: flaviostutz
   version: "1.0"
@@ -47,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
 
@@ -75,7 +72,10 @@ 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.
 - Keep the article under 150 lines; move detailed content to XDRs or Skills.
 - Use lowercase file names. Never use emojis.
 - If a conflict exists between the article and a Decision Record, note it and defer to the XDR.
@@ -113,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/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md

@@ -2,24 +2,29 @@
 name: 005-write-research
 description: >
   Creates a new research document following XDR research standards: selects scope, type, subject, and number;
-  then writes a focused study of constraints, findings, and option proposals with pros and cons.
+  then writes an IMRAD-based study with enough evidence and method detail to stand on its own as a technical paper.
   Activate this skill when the user asks to create, add, or write a research document that backs a decision.
 metadata:
   author: flaviostutz
-  version: "1.0"
+  version: "1.3"
 ---
 
 ## 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 a concise study that supports a decision lifecycle without replacing the XDR.
+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.
 
 ## 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. Identify the problem or question being explored, the main constraints or requirements, and which decision or decision threads this research supports.
-3. Do NOT proceed without a clear problem statement and at least one concrete constraint or requirement.
+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.
 
 ### Phase 2: Select Scope, Type, Subject, and Number
 
@@ -38,69 +43,187 @@ Guides the creation of a well-structured research document by following `_core-a
 3. Read related skills or articles if they contain context, implementation limits, or terminology that must be reflected.
 4. Collect links that should appear in the final `## References` section.
 
-### Phase 4: Write the Research Document
+### Phase 4: Create the Skeleton and Frame the Study
+
+1. Create the final section skeleton in the research file before running the study: `Abstract`, `Introduction`, `Methods`, `Results`, `Discussion`, `Conclusion`, `References`.
+2. Write a one-line note under each section heading capturing that section's goal before filling in the content so the draft stays disciplined.
+3. Draft `## Introduction` early so the problem, scope, constraints, assumptions, and central question are fixed before evidence collection expands.
+4. Draft `## Methods` before or while executing the study so tools, data sources, and conditions are captured while they are still precise.
+5. Treat `## Abstract` as a late-stage summary. Do not try to finalize it yet.
+6. Keep process framing out of the body. If related ADRs or repository context matter, push that traceability to `## References` unless it is essential to the technical question itself.
+
+### Phase 5: Capture Evidence as the Study Runs
+
+1. As experiments, comparisons, code spikes, interviews, benchmarks, or document reviews happen, append the concrete findings to `## Results` continuously.
+2. Prefer capturing tables, bullet points, numbers, code outputs, and option comparisons while the evidence is fresh.
+3. If multiple options solve the same problem, add a comparison table and explicit pros and cons for each option in `## Results` so the trade-offs are directly inspectable.
+4. Update `## Methods` whenever the actual study design changes so the final document remains reproducible.
+5. Keep interpretation out of `## Results`; record observations first and save meaning-making for `## Discussion`.
+
+### Phase 6: Synthesize After Results Stabilize
+
+1. Write `## Discussion` only after the important findings are visible in `## Results`.
+2. Use `## Discussion` to interpret significance, trade-offs, limitations, implications, and performance considerations for technical readers.
+3. Write `## Conclusion` after the discussion so it reflects the actual findings, practical takeaway, applicability boundaries, and open questions.
+4. Write `## Abstract` last so it accurately summarizes the final goal, methods, results, and conclusion for quick technical readers.
+
+### Phase 7: Write the Research Document
 
 Use the mandatory template from `006-research-standards`:
 
 ```markdown
 # [scope]-research-[number]: [Short Title]
 
-## Overview
+## Abstract
 
-[Brief description of the problem or question, audience, and decision thread(s) it supports.]
+[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. Under 200 words.]
 
-Question: [Central question of the research]?
-
-## Constraints
+## Introduction
 
-- [Constraint 1]
+[Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
+Use visuals, bullets, graphs, or diagrams when helpful. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
 
-## Findings
+Question: [Central question of the research]?
 
-- [Finding 1]
+## Methods
 
-## Proposals
+[Explain how the study was conducted, including design, tools, data sources, and test conditions.
+Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. Under 1200 words.]
 
-### Option 1: [Name]
+## Results
 
-[Short description]
+[Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
+Use figures, tables, or bullets when useful. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
 
-**Pros**
-- [Benefit]
+## Discussion
 
-**Cons**
-- [Drawback]
+[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged and under 1000 words.]
 
-## Recommendation
+## Conclusion
 
-[Optional preferred direction]
+[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. Under 400 words.]
 
 ## References
+
+[A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
+
+- [Related XDR or artifact](relative/path.md) - Why it matters
+- [Another related XDR if this research informed multiple decisions](relative/path.md) - Why it matters
 ```
 
 Rules:
-- Focus on exploring options under stated constraints; do not turn the document into the final decision.
-- End the `## Overview` section with `Question: [central question]?` so the main research question is explicit.
-- Make it explicit when the same research may feed multiple downstream XDRs.
-- Include a few meaningful proposals and summarize pros and cons for each.
-- Keep findings concrete and useful for later discussion or revision.
-- Keep the document under 2000 lines. Prefer much shorter when possible.
-- Treat `Research` as the artifact name; `researches/` is only the folder name.
-- Use lowercase file names. Never use emojis.
+- Treat the goal sentence of each section as a hard check on what belongs in that section.
+- Focus on exploring and evidencing the problem space; do not turn the document into the final decision.
+- Write as a standalone technical paper for readers who do not know the XDR process.
+- Keep mentions of future ADRs, decision lifecycle, repository process, or artifact management out of the body unless they are materially necessary to understand the research question.
+- Keep traceability to related XDRs, skills, articles, discussions, and external sources primarily in `## References`.
+- Use good-enough evidence. Experienced professional judgment is allowed, but the conclusions still need support that other colleagues can inspect and learn from.
+- Ensure the methods and test conditions are reproducible enough for an experienced professional to rerun or evolve the critical parts later.
+- Prefer plain Markdown, bullet points, tables, or ASCII art for simple explanations and comparisons, especially in the introduction and results.
+- If the research genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/researches/assets/` and link with a relative path.
+- Keep section word limits within the standard and keep the document under 5000 words total unless the introduction explicitly states that a very detailed analysis is required.
+
+### Phase 8: Check Section Goals
+
+Before the final review, verify each section against its specific goal:
+
+1. **Abstract goal**: Does it let a quick technical reader understand the question, method, main result, and takeaway, in one paragraph and under 200 words?
+2. **Introduction goal**: Does it explain the investigated problem and context, stay within scope, and end with `Question: ...?`?
+3. **Methods goal**: Could an experienced professional reproduce the important parts that materially affect the conclusion?
+4. **Results goal**: Are the findings concrete and minimally interpreted, with comparisons and pros/cons when multiple options exist?
+5. **Discussion goal**: Does it interpret the findings rather than repeat the results?
+6. **Conclusion goal**: Does it summarize the main findings, practical takeaway, applicability boundaries, and open questions without introducing new evidence?
+7. **References goal**: Are cited sources and related artifacts traceable, including related XDRs, skills, articles, and research where relevant?
+
+If any section fails its goal, revise that section before continuing.
+
+### Phase 9: Check Word Counts and Ratios
+
+Before the final review, run a word-count pass over the draft and verify that the main body roughly follows the standard proportion `Introduction : Methods : Results : Discussion ≈ 3 : 5 : 6 : 4`.
+
+1. Count words by top-level `##` section after stripping Markdown syntax so lists, tables, and links count as prose rather than punctuation.
+2. Compare only `Introduction`, `Methods`, `Results`, and `Discussion` for the ratio check.
+3. Use these target shares of the main body: `Introduction = 16.7%`, `Methods = 27.8%`, `Results = 33.3%`, `Discussion = 22.2%`.
+4. Treat any section as out of ratio when its share differs by more than 25% from its target share, unless the `## Introduction` explicitly justifies a very detailed or intentionally unbalanced analysis.
+5. If the ratio check fails, rebalance the draft before final review instead of accepting the imbalance silently.
+6. Use this Python script when you need a fast deterministic check:
+
+```python
+from pathlib import Path
+import re
+
+path = Path(".xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md")
+text = path.read_text(encoding="utf-8")
+
+sections = {}
+current = None
+for line in text.splitlines():
+  if line.startswith("## "):
+    current = line[3:].strip()
+    sections[current] = []
+    continue
+  if line.startswith("# "):
+    continue
+  if current is not None:
+    sections[current].append(line)
+
+
+def count_words(markdown: str) -> int:
+  cleaned = markdown
+  cleaned = re.sub(r"^\|(?:\s*[-:]+\s*\|)+\s*$", " ", cleaned, flags=re.M)
+  cleaned = re.sub(r"```[\s\S]*?```", " ", cleaned)
+  cleaned = re.sub(r"`([^`]*)`", r"\1", cleaned)
+  cleaned = re.sub(r"!\[([^\]]*)\]\([^)]*\)", r"\1", cleaned)
+  cleaned = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", cleaned)
+  cleaned = re.sub(r"^#+\s+", "", cleaned, flags=re.M)
+  cleaned = re.sub(r"[|*_>#-]", " ", cleaned)
+  cleaned = re.sub(r"[^\w'’]+", " ", cleaned, flags=re.UNICODE)
+  words = cleaned.strip().split()
+  return len(words)
+
+
+targets = {
+  "Introduction": 3,
+  "Methods": 5,
+  "Results": 6,
+  "Discussion": 4,
+}
+
+counts = {name: count_words("\n".join(lines)) for name, lines in sections.items()}
+total_words = sum(counts.values())
+body_total = sum(counts.get(name, 0) for name in targets)
+target_weight_total = sum(targets.values())
+
+print(f"TOTAL\t{total_words}")
+for name, count in counts.items():
+  print(f"{name}\t{count}")
+
+print("\nRATIO CHECK")
+for name, weight in targets.items():
+  actual_share = counts.get(name, 0) / body_total if body_total else 0
+  target_share = weight / target_weight_total
+  delta = ((actual_share - target_share) / target_share) if target_share else 0
+  status = "OK" if abs(delta) <= 0.25 else "REVISE"
+  print(
+    f"{name}: actual={actual_share:.1%} target={target_share:.1%} delta={delta:+.1%} {status}"
+  )
+```
 
-### Phase 5: Review the Draft
+### Phase 10: Review the Draft
 
 Before writing files, verify:
 
 1. **Problem clarity**: Is the research question explicit?
-2. **Constraints**: Are the most important constraints stated clearly?
-3. **Option quality**: Do the proposals represent real alternatives with non-trivial pros and cons?
-4. **Decision boundary**: Does the text support a decision without pretending to be the XDR itself?
-5. **References**: Are all related XDRs, research docs, skills, or articles linked, including multiple decisions when applicable?
+2. **Section discipline**: Does each section contain the right kind of content with minimal duplication?
+3. **Method quality**: Could an experienced professional reproduce or extend the important parts of the study from the methods section?
+4. **Evidence quality**: Are the results concrete enough to support the discussion and conclusion?
+5. **Standalone focus**: Does the text read as a technical paper rather than commentary about future ADRs, repository process, or artifact management?
+6. **Ratio fit**: Does the document stay within section word limits and pass the Python ratio check, or does the introduction explicitly justify the deviation?
+7. **References**: Are all related XDRs, research docs, skills, articles, and external sources linked when relevant?
 
 If any check fails, revise before continuing.
 
-### Phase 6: Write Files
+### Phase 11: Write Files
 
 1. Create the research file at `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`.
 2. Add an entry to `.xdrs/[scope]/[type]/index.md`.
@@ -115,15 +238,16 @@ If any check fails, revise before continuing.
 2. Choose type `adrs` and subject `principles`.
 3. Scan `.xdrs/_local/adrs/principles/researches/` for the next number.
 4. Read related XDRs about packaging and versioning.
-5. Write a research document with constraints, findings, and options such as npm package, git submodule, and copy-paste distribution.
+5. Write an IMRAD-based research document comparing options such as npm package, git submodule, and copy-paste distribution, with the comparison grounded in methods and results.
 6. Add references to the resulting XDR if a decision is later created.
 
 ## Edge Cases
 
 - If the user is really asking for a final decision, write an XDR instead of research.
-- If only one viable option exists, still record why alternatives were excluded or unavailable.
-- If the document grows too large, split independent problem threads into separate research files.
-- If the supported decision does not exist yet, reference the decision topic or planned XDR title in the overview.
+- If only one viable option exists, still explain what was evaluated, what was ruled out, or what constraints removed the alternatives.
+- If the document grows too large, split independent problem threads into separate research files unless the introduction explicitly justifies a longer study.
+- If the supported decision does not exist yet, reference the decision topic or planned XDR title in the introduction and conclusion.
+- If the user's direction, evidence base, or intended next step is vague, ask follow-up questions and wait for clarification instead of choosing a path yourself.
 
 ## References
 

package/README.md

@@ -14,11 +14,13 @@ 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.
+- **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.
 
+For simple indications, prefer plain Markdown, tables, or ASCII art. Use local images and other supporting files only when they are materially necessary, and keep them in a sibling `assets/` folder next to the document file.
+
 ## Getting started
 
 1. Create a new project workspace
@@ -55,6 +57,8 @@ 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 `Status` / `Valid` / `Applied to` field format
+- local image and `assets/` links resolving inside the sibling `assets/` folder for each document
 
 Examples:
 
@@ -89,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.
 
@@ -108,13 +113,17 @@ This is especially important for BDRs: because business rules govern decisions t
       index.md                      # canonical index for this scope+type
       [subject]/
         [number]-[short-title].md   # individual decision record
+        assets/                     # optional local resources for subject-level XDR files
         researches/                 # optional decision-backing research documents
           [number]-[short-title].md
+          assets/
         skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
+            assets/
         articles/                   # optional synthetic views over XDRs, Research, and Skills
           [number]-[short-title].md
+          assets/
 ```
 
 Document types:
@@ -143,7 +152,7 @@ Each scope manages its own set of XDR artifacts independently. Scope owners disc
 
 Once a set of decisions is ready to share, scope owners pack the relevant `.xdrs/[scope]/` folder into a versioned npm package using a tool such as [filedist](https://github.com/flaviostutz/filedist) and publish it to an npm registry, either public or a company-internal one. Versioning gives consumers explicit control over which revision of a scope's decisions they adopt, avoiding situations where a single breaking policy change is forced on all consumers at once.
 
-The same applies to Research documents and skills: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
+The same applies to Research documents, skills, articles, and any sibling `assets/` folders: because they live alongside XDRs inside the scope folder, they are included in the same package and published together.
 
 ### Usage
 

package/lib/lint.js

@@ -22,6 +22,8 @@ const NUMBERED_FILE_RE = /^(\d{3,})-([a-z0-9-]+)\.md$/;
 const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRs in scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches']);
+const RESOURCE_DIR_NAME = 'assets';
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 
 function runLintCli(args) {
   if (args.includes('--help') || args.includes('-h')) {
@@ -191,6 +193,9 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
     const entryPath = path.join(subjectPath, entry.name);
 
     if (entry.isDirectory()) {
+      if (entry.name === RESOURCE_DIR_NAME) {
+        continue;
+      }
       if (entry.name === 'skills') {
         artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
@@ -245,6 +250,147 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   if (!firstLine.startsWith(expectedHeader)) {
     errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
+
+  lintXdrMetadata(content, filePath, errors);
+  lintDocumentResourceLinks(filePath, errors);
+}
+
+function lintXdrMetadata(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const metadataLine = findHeadingLine(lines, ignoredLines, '## Metadata');
+  const contextLine = findHeadingLine(lines, ignoredLines, '## Context and Problem Statement');
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  if (metadataLine !== -1) {
+    const nextHeadingLine = headingLines.find((lineIndex) => lineIndex > metadataLine);
+    if (nextHeadingLine !== contextLine) {
+      errors.push(`XDR metadata section must appear immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+    }
+  }
+
+  if (metadataLine !== -1 && contextLine !== -1 && metadataLine > contextLine) {
+    errors.push(`XDR metadata section must appear before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+  }
+
+  const metadataRange = metadataLine === -1
+    ? null
+    : {
+        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 validLineNumbers = findFieldLines(lines, ignoredLines, 'Valid:');
+
+  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;
+  }
+
+  if (!metadataRange) {
+    return;
+  }
+
+  const metadataStatus = statusLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+  const metadataApplied = appliedLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+  const metadataValid = validLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+
+  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 (metadataValid.length > 1) {
+    errors.push(`XDR metadata must not repeat Valid: ${toDisplayPath(filePath)}`);
+  }
+
+  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;
+    }
+    const trimmed = lines[lineIndex].trim();
+    if (trimmed === '') {
+      continue;
+    }
+    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) {
+    const value = lines[metadataApplied[0]].slice('Applied to:'.length).trim();
+    if (value === '') {
+      errors.push(`XDR Applied to: must not be empty: ${toDisplayPath(filePath)}`);
+    } else if (countWords(value) >= 40) {
+      errors.push(`XDR Applied to: must be under 40 words: ${toDisplayPath(filePath)}`);
+    }
+  }
+
+  if (metadataValid.length === 1) {
+    lintValidField(lines[metadataValid[0]], filePath, errors);
+  }
+}
+
+function lintStatusField(line, filePath, errors) {
+  const value = line.slice('Status:'.length).trim().replace(/\.$/, '');
+
+  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 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 = validMatch[1];
+  const untilDate = validMatch[2] ?? validMatch[3];
+  if ((fromDate && !isIsoDate(fromDate)) || (untilDate && !isIsoDate(untilDate))) {
+    errors.push(`XDR Valid: must use ISO dates in YYYY-MM-DD format: ${toDisplayPath(filePath)}`);
+    return;
+  }
+
+  if (fromDate && untilDate && fromDate > untilDate) {
+    errors.push(`XDR Valid: from date must be on or before until date: ${toDisplayPath(filePath)}`);
+  }
 }
 
 function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
@@ -292,6 +438,8 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     } else if (frontmatterName !== entry.name) {
       errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
     }
+
+    lintDocumentResourceLinks(skillFilePath, errors);
   }
 
   return artifacts;
@@ -304,6 +452,10 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
 
   for (const entry of entries) {
     const entryPath = path.join(articlesPath, entry.name);
+    if (entry.isDirectory() && entry.name === RESOURCE_DIR_NAME) {
+      continue;
+    }
+
     if (!entry.isFile()) {
       errors.push(`Unexpected directory in articles folder: ${toDisplayPath(entryPath)}`);
       continue;
@@ -335,6 +487,8 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
+
+    lintDocumentResourceLinks(entryPath, errors);
   }
 
   return artifacts;
@@ -347,6 +501,10 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
 
   for (const entry of entries) {
     const entryPath = path.join(researchPath, entry.name);
+    if (entry.isDirectory() && entry.name === RESOURCE_DIR_NAME) {
+      continue;
+    }
+
     if (!entry.isFile()) {
       errors.push(`Unexpected directory in researches folder: ${toDisplayPath(entryPath)}`);
       continue;
@@ -378,6 +536,8 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
+
+    lintDocumentResourceLinks(entryPath, errors);
   }
 
   return artifacts;
@@ -404,15 +564,43 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
+function lintDocumentResourceLinks(documentPath, errors) {
+  const content = fs.readFileSync(documentPath, 'utf8');
+  const documentDir = path.dirname(documentPath);
+  const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
+
+  for (const link of parseLocalLinkTargets(content, documentDir)) {
+    if (!shouldValidateResourceLink(link.rawTarget)) {
+      continue;
+    }
+
+    if (!fs.existsSync(link.resolvedPath)) {
+      errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
+      continue;
+    }
+
+    if (!isPathInside(resourceDir, link.resolvedPath)) {
+      errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+    }
+  }
+}
+
 function parseLocalLinks(markdown, baseDir) {
+  return parseLocalLinkTargets(markdown, baseDir).map((link) => link.resolvedPath);
+}
+
+function parseLocalLinkTargets(markdown, baseDir) {
   const links = [];
-  const linkRe = /\[[^\]]+\]\(([^)]+)\)/g;
+  const linkRe = /!?\[[^\]]+\]\(([^)]+)\)/g;
   let match = linkRe.exec(markdown);
   while (match) {
     const rawTarget = match[1].trim();
     if (isLocalLink(rawTarget)) {
       const targetWithoutAnchor = rawTarget.split('#')[0];
-      links.push(path.resolve(baseDir, targetWithoutAnchor));
+      links.push({
+        rawTarget,
+        resolvedPath: path.resolve(baseDir, targetWithoutAnchor)
+      });
     }
     match = linkRe.exec(markdown);
   }
@@ -432,6 +620,17 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
   return relative.length === 3 && TYPE_NAMES.has(relative[1]) && relative[2] === 'index.md';
 }
 
+function shouldValidateResourceLink(rawTarget) {
+  const targetWithoutAnchor = rawTarget.split('#')[0];
+  const normalizedTarget = targetWithoutAnchor.replace(/\\/g, '/');
+  const extension = path.extname(targetWithoutAnchor).toLowerCase();
+
+  return normalizedTarget === RESOURCE_DIR_NAME
+    || normalizedTarget.startsWith(`${RESOURCE_DIR_NAME}/`)
+    || normalizedTarget.includes(`/${RESOURCE_DIR_NAME}/`)
+    || IMAGE_EXTENSIONS.has(extension);
+}
+
 function extractFrontmatterName(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (!frontmatterMatch) {
@@ -442,6 +641,82 @@ function extractFrontmatterName(content) {
   return nameMatch ? nameMatch[1].trim() : null;
 }
 
+function findIgnoredMarkdownLines(lines) {
+  const ignored = [];
+  let inCodeFence = false;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (/^```/.test(trimmed)) {
+      ignored[index] = true;
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+
+    ignored[index] = inCodeFence;
+  }
+
+  return ignored;
+}
+
+function findHeadingLine(lines, ignoredLines, headingText) {
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (lines[index].trim() === headingText) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function findHeadingLines(lines, ignoredLines) {
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (/^##\s+/.test(lines[index].trim())) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+function findFieldLines(lines, ignoredLines, prefix) {
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (lines[index].trim().startsWith(prefix)) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+function isLineInsideRange(lineIndex, range) {
+  return lineIndex >= range.start && lineIndex <= range.end;
+}
+
+function countWords(value) {
+  return value.split(/\s+/).filter(Boolean).length;
+}
+
+function isIsoDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return false;
+  }
+
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
 function firstNonEmptyLine(content) {
   const lines = content.split(/\r?\n/);
   for (const line of lines) {
@@ -500,6 +775,11 @@ function normalizePath(filePath) {
   return path.normalize(filePath);
 }
 
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
 module.exports = {
   runLintCli,
   lintWorkspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.8.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",
@@ -14,7 +14,8 @@
   ],
   "license": "MIT",
   "files": [
-    ".xdrs/**",
+    ".xdrs/_core/**",
+    ".xdrs/index.md",
     "package.json",
     "AGENTS.md",
     "bin/filedist.js",