xdrs-core 0.11.1 → 0.12.0

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

@@ -1,18 +1,17 @@
-# general ADRs Index
+# _core ADRs Index
 
-This index covers cross-business architectural and technical decisions that apply to all scopes. Owned by the platform team. Propose changes via pull request.
-
-This index lists all ADRs for the general scope, organized by subject.
+Decisions about how the XDR framework itself works: structure, standards, document types, versioning, and supporting artifacts. Owned by the platform team. Propose changes via pull request.
 
 ## Principles
 
 Foundational standards, principles, and guidelines.
 
-- [_core-adr-001](principles/001-xdr-standards.md) - **XDR standards** (includes XDR template)
-- [_core-adr-003](principles/003-skill-standards.md) - **Skill standards**
-- [_core-adr-004](principles/004-article-standards.md) - **Article standards**
-- [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages**
-- [_core-adr-006](principles/006-research-standards.md) - **Research standards**
+- [_core-adr-001](principles/001-xdrs-core.md) - **XDRs core** — Types, scopes, subjects, folder structure, and indexes for the XDR framework
+- [_core-adr-002](principles/002-xdr-standards.md) - **XDR standards** — How to write individual XDR decision documents: template, metadata, ID, lifecycle rules
+- [_core-adr-003](principles/003-skill-standards.md) - **Skill standards** — How to author and organize reusable skill packages within XDR projects
+- [_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
 

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

@@ -0,0 +1,138 @@
+# _core-adr-001: XDRs core
+
+## Context and Problem Statement
+
+We need a consistent way to capture decisions that scales across scopes and subjects, remains easy to navigate, and works well with AI agents.
+
+How should XDRs be structured and organized across types, teams, and scopes?
+
+## Decision Outcome
+
+**Scoped + typed + subject folders**
+
+Provides clear ownership by scope, predictable navigation, and reusable decisions that work well with AI agents by keeping files small and focused.
+
+### Implementation Details
+
+Decision Records can be of different kinds, depending on the nature of the decision:
+- BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
+- ADR (Architectural Decision Record): Wider architectural and technical decisions. Examples: how big topics relate to each other, system contexts, overview without realy deciding on details, integration patterns, overarching topics, corporate wide practices, corporate systems, external and internal partners etc
+- EDR (Engineering Decision Record): captures engineering details about how to implement things. Examples: specific tools and libraries selection, framework usage, best practices on coding, testing, quality, project structure, pipelines etc
+
+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.
+- Make it clear if an instruction is mandatory or advisory.
+  - Mandatory language: "must", "always", "never", "required", "mandatory"
+  - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
+- Always use the following folder structure for XDR documents:
+  `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
+- Optional supporting artifacts under the same subject:
+  - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
+  - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
+  - `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
+- Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated XDRs. This XDR defines the shared framework baseline; `_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
+- 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:** 
+  - Short name that defines a group or a package of xdrs
+  - examples: `business-x`, `business-y`, `team-43`, `_core`
+  - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared `.xdrs/index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them.
+  - **Types:** `adrs`, `bdrs`, `edrs`
+  - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
+- **Subjects:** MUST be one of the following depending on the type of the XDR. Use the subject to indicate the main concern of the decision.
+  - **ADR subjects**
+    - `principles`: Cross-cutting architecture and policy foundations.
+      - Examples: architecture style, interoperability rules, long-term technology direction.
+    - `application`: System and service design decisions at application level.
+      - Examples: modularization strategy, service decomposition, app-level security flows.
+    - `data`: Data architecture and information modeling choices.
+      - Examples: canonical schemas, data ownership boundaries, retention strategies.
+    - `integration`: Decisions about communication between internal/external systems.
+      - Examples: sync vs async patterns, contract strategy, partner integration approach.
+    - `platform`: Platform-level runtime and enabling capabilities.
+      - Examples: cloud/runtime baseline, foundational services, platform tenancy approach.
+    - `controls`: Architecture controls for risk, security, and compliance at a high level.
+      - Examples: encryption baseline, auditability requirements, policy enforcement points.
+    - `operations`: Operational architecture decisions.
+      - Examples: incident model, resilience objectives, operational ownership boundaries.
+  - **BDR subjects**
+    - `principles`: Business principles and decision criteria that guide all business areas.
+      - Examples: customer fairness rules, policy precedence, strategic guardrails.
+    - `marketing`: Go-to-market, communication, and campaign policy decisions.
+      - Examples: campaign approval rules, channel usage standards, positioning constraints.
+    - `product`: Product behavior, lifecycle, and offering decisions.
+      - Examples: feature rollout policy, packaging/tiers, product requirement governance.
+    - `controls`: Business control framework decisions.
+      - Examples: approval segregation, mandatory checks, exception handling policy.
+    - `operations`: Day-to-day business process and procedure decisions.
+      - Examples: support workflows, onboarding/offboarding procedures, SLA operations.
+    - `organization`: Structure, roles, and responsibility model decisions.
+      - Examples: decision rights, team topology, accountability boundaries.
+    - `finance`: Financial and cost-control business decisions.
+      - Examples: budgeting process, pricing governance, investment approval rules.
+    - `sustainability`: Environmental and social responsibility policy decisions.
+      - Examples: sustainability KPIs, reporting cadence, procurement sustainability criteria.
+  - **EDR subjects**
+    - `principles`: Engineering principles and non-functional quality defaults.
+      - Examples: coding standards baseline, testing philosophy, secure-by-default engineering rules.
+    - `application`: Code-level implementation patterns and application conventions.
+      - Examples: framework patterns, layer organization, API implementation conventions.
+    - `infra`: Infrastructure implementation and runtime operations details.
+      - Examples: IaC patterns, environment provisioning, network/runtime hardening details.
+    - `observability`: Telemetry, monitoring, alerting, and diagnostics implementation.
+      - Examples: log/metric/tracing standards, alert routing policy, SLO measurement approach.
+    - `devops`: Delivery pipeline, release automation, and developer workflow decisions.
+      - Examples: CI/CD stages, branch strategy, release promotion gates.
+    - `governance`: Engineering governance, risk controls, and compliance mechanics.
+      - Examples: dependency governance, approval policies, mandatory quality checks.
+- Never use emojis
+- **Indexes**
+  - Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
+  - Canonical index requirements:
+    - Organize XDR documents by subject for easier navigation
+    - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
+    - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRs in scopes listed last override XDRs in scopes listed first when addressing the same topic.
+    - Each XDR element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
+  - Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
+  - Always verify if indexes are up to date after making changes
+
+**Folder structure examples:**
+- `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`
+- `.xdrs/business-x/adrs/controls/010-security-and-secrets-management.md`
+- `.xdrs/_core/edrs/devops/001-multi-repo.md`
+
+```text
+subject/
+|-- 001-xdr.md
+|-- assets/
+|-- articles/
+|   |-- 001-article.md
+|   `-- assets/
+|-- researches/
+|   |-- 001-study.md
+|   `-- assets/
+`-- skills/
+    `-- 001-task/
+        |-- SKILL.md
+        `-- assets/
+```
+
+## References
+
+- [_core-adr-002 - XDR standards](002-xdr-standards.md) - Standards for writing individual XDR decision documents
+- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
+- [_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)

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

@@ -0,0 +1,117 @@
+# _core-adr-002: XDR standards
+
+## Context and Problem Statement
+
+XDR framework elements (types, scopes, subjects, folder structure) are defined in `_core-adr-001`. Once a decision record's structural placement is clear, how should the document itself be written to remain authoritative, concise, and consistently structured?
+
+## Decision Outcome
+
+**Structured decision records with a mandatory template, lifecycle 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.
+
+### Implementation Details
+
+- XDRs MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Always cite sources.
+- 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.
+  - `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 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 the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
+  - If any check fails, the XDR MAY still be read as background, history, or context, but it MUST NOT be treated as a current requirement for that case.
+- Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, approval, retirement, and updates of xdrs, but the XDR document remains the source of truth.
+- **XDR Id:** [scope]-[type]-[xdr number] (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.
+- 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.
+- 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.
+- Avoid using lengthy instructions on the XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
+- XDRs should be under 1300 words long as a rule of thumb.
+  - This is important to make them focused on a clear decision
+  - Exceptions can reach under 2600 words (templates, more elaborate decision implementations etc)
+- ALWAYS use `_local` scope if the user doesn't explicitly indicate a specific scope while creating an xdr or skill.
+
+**XDR template**
+
+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.
+What is the problem we are trying to solve? Who is being impacted? (<40 words)
+
+Question: In the end, state explicitly the question that needs to be answered. E.g: "Which platform should I use when implementing an AI agent?"]
+
+## Decision Outcome
+
+**[Chosen Option Title]**
+[Very short description of what is the decision, aligned with the titles on the Considered Options section]
+
+[Short description of implementation details for the chosen path]
+
+### Implementation Details
+
+[Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
+
+[Related research, if any]
+- [Research document title](researches/001-example.md) - Brief description of what it informed
+
+## Conflicts
+
+[If this XDR has conflicts with other scopes, this section is MANDATORY and needs to have an explanation why the conflict is accepted]
+
+* Conflict with [XDR id] (e.g.: adr-business-x-001)
+  * Summary: Brief description of the conflict
+  * Reason to accept: Brief description of why it was decided to accept this conflict, possibly overriding or diverging from the other decision/scopes
+
+## References
+
+[optional section]
+[useful links related to this implementation]
+[links to the discussion (PRs, meetings etc)]
+[links to related skills]
+```
+
+**Examples:**
+- Metadata examples:
+  - `Status: Draft`
+  - `Status: Active`
+  - `Valid: from 2026-03-01 until 2026-12-31`
+  - `Applied to: JavaScript projects`
+
+**XDR ID Examples:**
+- `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)
+- `business-x-edr-042` (not `EDR-BUSINESS-X-042`)
+- `business-x-bdr-007`
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
+- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
+- [_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)

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

@@ -47,11 +47,16 @@ Quick test:
 **Folder layout**
 
 ```
-.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/
-    SKILL.md              # required
-    scripts/              # optional: executable scripts the agent may run
-    references/           # optional: detailed reference material
-    assets/               # optional: images, templates, data files, and other local resources
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        skills/
+          [number]-[skill-name]/
+            SKILL.md              # required
+            scripts/              # optional: executable scripts the agent may run
+            references/           # optional: detailed reference material
+            assets/               # optional: images, templates, data files, and other local resources
 ```
 
 Examples:
@@ -103,7 +108,7 @@ Rules:
 - `## 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/`.
+- Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
 - Reference other files with relative paths from the skill root.
 - Always use lowercase file names.
 - Never use emojis in skill content.
@@ -128,6 +133,6 @@ skills-ref validate .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]
 - [agentskills specification](https://agentskills.io/specification)
 - [agentskills/agentskills repository](https://github.com/agentskills/agentskills)
 - [skills-ref validation library](https://github.com/agentskills/agentskills/tree/main/skills-ref)
-- [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-001 - XDRs core](001-xdrs-core.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)

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

@@ -15,8 +15,10 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 ### Implementation Details
 
 - 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 are not limited to synthesizing XDRs. They may also document application features, APIs, general project information, reference tables, diagrams, FAQs and other elements useful to their intended audience.
 - 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.
 - 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`.
@@ -24,15 +26,18 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - 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.
+- Articles should be kept under 1950 words. Move detailed content to referenced XDRs or Skills.
 
 **Folder layout**
 
 ```
-.xdrs/[scope]/[type]/[subject]/
-  articles/
-    [number]-[short-title].md
-    assets/
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        articles/
+          [number]-[short-title].md
+          assets/
 ```
 
 Examples:
@@ -55,7 +60,7 @@ All articles MUST follow this template:
 
 ## Overview
 
-[Brief description of what this article covers and its intended audience. (<3 lines)]
+[Brief description of what this article covers and its intended audience. (<40 words)]
 
 ## Content
 
@@ -69,8 +74,6 @@ when referencing an information from those documents.]
 
 ## Considered Options
 
-* (REJECTED) **Inline summaries inside XDR index files** - Keeps everything in one place but clutters the navigation indexes.
-  * Reason: Index files should remain lean navigation aids; mixing synthesis into them hurts readability and makes updates harder.
 * (REJECTED) **Separate documentation repository** - Removes drift risk but decouples docs from decisions.
   * Reason: Increases maintenance burden and makes it easy for articles to go stale relative to the XDRs they reference.
 * (CHOSEN) **Subject-level articles folder co-located with XDRs** - Keeps articles alongside the decision records and skills they reference, with `principles` as the fallback for cross-subject articles.
@@ -78,7 +81,7 @@ when referencing an information from those documents.]
 
 ## References
 
-- [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-001 - XDRs core](001-xdrs-core.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)
 - [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article

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

@@ -49,10 +49,13 @@ Research documents are Markdown files placed inside a subject folder alongside d
 **Folder layout**
 
 ```
-.xdrs/[scope]/[type]/[subject]/
-  researches/
-    [number]-[short-title].md
-    assets/
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        researches/
+          [number]-[short-title].md
+          assets/
 ```
 
 Examples:
@@ -121,7 +124,7 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 
 ## References
 
-- [_core-adr-001 - XDR standards](001-xdr-standards.md)
+- [_core-adr-001 - XDRs core](001-xdrs-core.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [005-write-research skill](skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document

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

@@ -17,7 +17,7 @@ same decision system.
   record the adopted direction. They are the central policy artifact of the framework for the
   scope and topic they cover. Three decision record types exist: **ADR** for architectural and
   technical decisions, **BDR** for business and operational decisions, and **EDR** for engineering
-  implementation decisions. See [_core-adr-001](../001-xdr-standards.md).
+  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,
   but it is not the final rule. A single Research document may inform multiple downstream ADRs,
@@ -51,7 +51,7 @@ harder to update, and harder for agents to apply correctly.
 
 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.
+- **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.
 - **Decision text last**: the XDR's own context and implementation details still determine the final boundaries and exceptions.
@@ -84,18 +84,21 @@ This gives XDRs a timeline feel:
 
 ### How the structure supports the model
 
-Every decision record lives at a fixed path:
+Every decision record and its supporting artifacts live at a fixed path:
 
 ```
-.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md
-```
-
-Supporting artifacts live beside it in the same subject:
-
-```
-researches/[number]-[short-title].md
-skills/[number]-[skill-name]/SKILL.md
-articles/[number]-[short-title].md
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        [number]-[short-title].md
+        researches/
+          [number]-[short-title].md
+        skills/
+          [number]-[skill-name]/
+            SKILL.md
+        articles/
+          [number]-[short-title].md
 ```
 
 - **Scopes** represent ownership domains such as `_core`, `business-x`, or `team-43`.
@@ -128,12 +131,12 @@ guidance, and the explanatory overview close together without collapsing them in
 
 ### Guidelines
 
-Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
+Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-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 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.
 - Use `_local` scope when a decision is project-specific and must not be shared.
@@ -167,11 +170,14 @@ Follow [_core-adr-001](../001-xdr-standards.md) strictly. Key rules:
 
 ## References
 
-- [_core-adr-001](../001-xdr-standards.md) - XDR standards and mandatory template
+- [_core-adr-001](../001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
+- [_core-adr-002](../002-xdr-standards.md) - XDR document standards and mandatory template
 - [_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
 - [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
+- [004-write-article skill](../skills/004-write-article/SKILL.md) - Writing a new article
 - [005-write-research skill](../skills/005-write-research/SKILL.md) - Writing a new research document
+- [_core-adr-005](../005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages

package/.xdrs/_core/adrs/principles/researches/001-research-and-decision-lifecycle.md

@@ -1,26 +1,47 @@
 # _core-research-001: Research and decision lifecycle
 
-## Overview
+## Abstract
 
-This research evaluates how Research should fit into the XDR model so maintainers can evolve it as a supporting artifact without weakening XDRs as the source of truth. It provides the context behind the decision captured in [_core-adr-006](../006-research-standards.md).
+This study evaluates where research material should be positioned in the XDR framework so teams can preserve decision traceability and option analysis without weakening XDRs as the authoritative source. Three placement strategies were assessed against the framework's discoverability and conciseness constraints. Subject-level co-location in a dedicated `researches/` folder alongside `skills/` and `articles/` was found to best preserve context, keep XDRs concise, and stay consistent with the existing folder conventions. The study recommends treating Research as a first-class optional supporting artifact at the subject level.
+
+## Introduction
+
+As the XDR framework grows, teams need space beyond a concise XDR to record the reasoned evaluation of options — constraints, findings, tradeoffs, and rejected paths — before or after a decision changes. Without a dedicated place for this material, long-form analysis migrates into pull request comments, shared documents, and chat threads, making it hard to discover and harder to review when facts or technology change.
+
+Three structural concerns drive this study:
+
+- XDRs must stay under roughly 1300 words so both humans and AI agents can parse them quickly.
+- Supporting analysis must be discoverable without knowing where to look outside the XDR folder tree.
+- The framework already has `skills/` and `articles/` co-located per subject; a research artifact needs to fit that model or justify a deviation.
+
+Known constraints from the XDR model:
+
+- XDRs are the authoritative source of truth; no other artifact may override them.
+- Subject-level folder structure is the canonical navigation layer.
+- The framework must remain simple enough to onboard with a short article.
 
 Question: How should a Research artifact fit into the XDR model so it supports the decision lifecycle without diluting the role of XDRs as the source of truth?
 
-## Constraints
+## Methods
 
-- XDRs must stay concise and decision-focused.
-- Supporting analysis must be easy to discover from the same subject folder.
-- The new artifact must help during elaboration, discussion, approval, retirement, and updates.
-- The structure must remain simple enough for humans and AI agents to navigate.
+This study used a structured option evaluation approach:
 
-## Findings
+1. Catalogued the current XDR folder model and subject-level artifacts (`skills/`, `articles/`) from `_core-adr-001`.
+2. Identified the key discoverability and maintenance constraints documented in `_core-adr-001`.
+3. Defined three candidate placement strategies for research material based on common documentation pattern variants.
+4. Assessed each option against four criteria: proximity to the relevant XDR, impact on XDR conciseness, discoverability for subjects with multiple related XDRs, and overall framework simplicity.
 
-- Long-form option analysis does not fit well inside XDRs because it mixes evidence gathering with the adopted decision.
-- Articles are useful for synthesis, but they are optimized for understanding and navigation rather than preserving the full option tradeoff study.
-- Skills are procedures, not evidence. They explain how to do something, not why an option was evaluated or rejected.
-- Subject-level co-location is the strongest predictor of discoverability in the current XDR model.
+No external benchmarks were used. Assessment is based on the existing XDR structural rules and professional judgment about folder-based discoverability in developer tooling ecosystems.
 
-## Proposals
+## Results
+
+Three placement strategies were evaluated:
+
+| Option | Placement | Proximity to XDR | XDR Conciseness | Simplicity |
+|--------|-----------|-----------------|-----------------|------------|
+| 1 | Inside the XDR file | High (same file) | Low (bloat risk) | High |
+| 2 | Global `researches/` tree | Low (detached from subjects) | High | Medium |
+| 3 | Subject-level `researches/` | High (same subject) | High | Medium |
 
 ### Option 1: Keep research inside XDRs
 
@@ -28,42 +49,51 @@ Use larger XDRs and keep all exploratory analysis in the same file as the final
 
 **Pros**
 - One file per decision thread.
-- No new folder type to teach.
+- No new folder type to learn or maintain.
 
 **Cons**
-- Bloats XDRs and makes the adopted rule set harder to scan.
-- Weakens the under-100-line guidance for decision records.
+- Makes XDRs too long and hard to scan.
+- Weakens the under-1300-word size constraint for decision records.
 
 ### Option 2: Create a top-level shared research area
 
 Store all research under a global `researches/` tree detached from subjects.
 
 **Pros**
-- Centralized catalog of studies.
-- Easy to browse all research at once.
+- Centralized catalog of studies; easy to browse all research at once.
 
 **Cons**
 - Loses proximity to the decisions it informed.
 - Makes subject-scoped discovery and maintenance harder.
+- Inconsistent with how `skills/` and `articles/` are organized.
 
 ### Option 3: Add `researches/` beside `skills/` and `articles/`
 
-Keep research documents under the same subject as the XDR they support.
+Keep research documents under the same subject folder as the XDR they support.
 
 **Pros**
-- Preserves context and keeps evidence close to the decision.
-- Lets XDRs stay concise while retaining detailed tradeoff history.
+- Preserves context: evidence lives beside the decision it informed.
+- Keeps XDRs concise while retaining detailed tradeoff history.
+- Consistent with the existing `skills/` and `articles/` co-location pattern.
 
 **Cons**
 - Adds one more artifact type to explain and maintain.
-- Requires linting and indexes to recognize another optional folder.
+- Requires canonical indexes to cover one additional optional folder.
+
+## Discussion
+
+Option 3 dominates the evaluation on the key criteria. Subject-level co-location is what makes `skills/` and `articles/` discoverable in practice; research benefits from the same property. A global research tree (Option 2) loses the proximity that makes it useful when revisiting a decision, and inline analysis (Option 1) conflicts directly with the under-1300-word XDR guideline.
+
+The main cost of Option 3 is framework complexity: teams must learn a new artifact type and canonical indexes must cover one more folder. This cost is real but modest. The XDR framework already has four artifact types (XDR, Skill, Article, Index); adding Research brings it to five, adding only one new section to the index template and one new optional folder per subject.
+
+A risk worth noting: teams may resist creating a separate research file for simple decisions. This is acceptable. Research documents are optional and are most valuable for decisions with non-trivial option tradeoffs, evolving constraints, or evidence worth preserving for future reviews. For simple decisions, brief inline rationale in the XDR itself remains appropriate as long as the total XDR length stays under 1300 words.
 
-## Recommendation
+## Conclusion
 
-Option 3 is the best fit because it preserves the existing navigation model while separating evidence gathering from the adopted decision text.
+Subject-level co-location in `researches/[number]-[short-title].md` alongside the XDR is the model that best preserves discoverability, keeps XDRs concise, and stays consistent with existing folder conventions. Option 1 (inline) conflicts with the XDR size constraint; Option 2 (global tree) breaks subject-level proximity. The framework overhead of an optional `researches/` folder is low relative to the lifecycle traceability it provides. Research is optional and most useful for non-trivial decisions; for simple decisions, inline rationale remains acceptable within the 1300-word XDR budget.
 
 ## References
 
 - [_core-adr-006](../006-research-standards.md) - Decision that adopts research as a first-class artifact
-- [_core-adr-001](../001-xdr-standards.md) - Base XDR structure and references
-- [_core-adr-004](../004-article-standards.md) - Distinction between research and synthesis
+- [_core-adr-001](../001-xdrs-core.md) - Base XDR structure and folder conventions
+- [_core-adr-004](../004-article-standards.md) - Distinction between research (evidence) and synthesis (articles)