xdrs-core 0.17.1 → 0.19.0

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

@@ -48,12 +48,12 @@ Collectively, these are referred to as XDRs.
   - `_core-adr-004` defines article standards
   - `_core-adr-006` defines research standards
   - `_core-adr-007` defines plan standards
-- For simple structure, flow, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
-- Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they SHOULD live in a sibling `assets/` folder next to the document.
-  - XDRs in the subject root use `.xdrs/[scope]/[type]/[subject]/assets/`
-  - 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/`
+- For simple structures, flows, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams) 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 MUST 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`
@@ -107,6 +107,7 @@ Collectively, these are referred to as XDRs.
     - `governance`: Engineering governance, risk controls, and compliance mechanics.
       - Examples: dependency governance, approval policies, mandatory quality checks.
 - Never use emojis
+- **Links:** Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`); they break when files are moved and are harder to read.
 - **Indexes**
   - Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
   - Canonical index requirements:
@@ -125,27 +126,27 @@ Collectively, these are referred to as XDRs.
 ```text
 subject/
 |-- 001-xdr.md
-|-- assets/
+|-- .assets/
 |-- articles/
 |   |-- 001-article.md
-|   `-- assets/
+|   `-- .assets/
 |-- plans/
 |   |-- 001-plan.md
-|   `-- assets/
+|   `-- .assets/
 |-- researches/
 |   |-- 001-study.md
-|   `-- assets/
+|   `-- .assets/
 `-- skills/
     `-- 001-task/
         |-- SKILL.md
-        `-- assets/
+        `-- .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
+- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](/.xdrs/_core/adrs/principles/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

@@ -109,7 +109,7 @@ Question: In the end, state explicitly the question that needs to be answered. E
 [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)]
 
 ## Considered Options 
-[this section is present ONLY if there was more than one option to choose from]
+[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision.]
 
 * (CHOSEN) **Option 2** - Brief description of option 2
   * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.
@@ -148,8 +148,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
 ## 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
+- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
+- [002-write-xdr skill](/.xdrs/_core/adrs/principles/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

@@ -63,7 +63,7 @@ Quick test:
             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
+            .assets/               # optional: images, templates, data files, and other local resources
 ```
 
 Examples:
@@ -114,9 +114,9 @@ Rules:
 - `## 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.
+- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package.
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
-- Reference other files with relative paths from the skill root.
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/`. Sibling files and child folder references SHOULD use relative paths (e.g., `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../other.md`).
 - Always use lowercase file names.
 - Never use emojis in skill content.
 

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

@@ -28,7 +28,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - 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 using the required list of subjects per type defined in `_core-adr-001`. 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.
+- Images and other local resource files referenced by an article SHOULD be used only when they are materially necessary and MUST 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 1950 words. Move detailed content to referenced XDRs or Skills.
@@ -42,7 +42,7 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
       [subject]/
         articles/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:
@@ -89,4 +89,4 @@ when referencing an information from those documents.]
 - [_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
+- [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article

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

@@ -48,7 +48,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
 - 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.
+- Images and other local resource files referenced by a research document SHOULD be used only when they are materially necessary and MUST 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.
 
@@ -61,7 +61,7 @@ Research documents are Markdown files placed inside a subject folder alongside d
       [subject]/
         researches/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:
@@ -133,4 +133,4 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 - [_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
+- [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Step-by-step instructions for creating a research document

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

@@ -31,7 +31,7 @@ Plans are Markdown documents placed inside a subject folder alongside decision r
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - Always use lowercase file names.
 - Never use emojis in plan content.
-- Images and other local resource files referenced by a plan SHOULD live in `plans/assets/` next to the plan files.
+- Images and other local resource files referenced by a plan MUST live in `plans/.assets/` next to the plan files.
 
 **Folder layout**
 
@@ -42,7 +42,7 @@ Plans are Markdown documents placed inside a subject folder alongside decision r
       [subject]/
         plans/
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Examples:
@@ -135,4 +135,4 @@ Due date: YYYY-MM-DD
 - [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
 - [_core-adr-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
 - [_core-adr-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
-- [006-write-plan skill](skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan
+- [006-write-plan skill](/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md) - Step-by-step instructions for creating a new plan

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

@@ -17,23 +17,23 @@ 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-xdrs-core.md).
+  implementation decisions. See [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md).
 - **Research** captures exploration before or around a decision: constraints, findings, options,
   pros, and cons. Research supports elaboration, discussion, and updates,
   but it is not the final rule. A single Research document may inform multiple downstream ADRs,
   BDRs, or EDRs. If Research and an XDR disagree, the XDR wins. See
-  [_core-adr-006](../006-research-standards.md).
+  [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
 - **Skills** describe how to execute work under the constraints of the decisions. They add the
   procedural detail that XDRs intentionally avoid. A Skill may be used by a human, an AI agent, or
   both. Skills are task-based, should end in a verifiable outcome, and are only mandatory when a
-  policy such as an XDR makes them mandatory. See [_core-adr-003](../003-skill-standards.md).
+  policy such as an XDR makes them mandatory. See [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
 - **Articles** are synthetic views, like this one. They explain a topic across multiple XDRs,
   Research documents, and Skills, helping readers understand the system without making new
-  decisions. See [_core-adr-004](../004-article-standards.md).
+  decisions. See [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
 - **Plans** describe a problem, a proposed solution, and the approach and activities needed to
   solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
   must be deleted after full implementation, with lasting outputs captured as Decisions, Skills,
-  Articles, or other artifacts. See [_core-adr-007](../007-plan-standards.md).
+  Articles, or other artifacts. See [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
 - **Indexes and folder structure** are the discovery layer. They do not make decisions by
   themselves, but they determine how people and agents find the right artifacts, how scopes
   override one another, and how a large set of decisions remains navigable.
@@ -139,7 +139,7 @@ guidance, and the explanatory overview close together without collapsing them in
 
 ### Guidelines
 
-Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-standards.md) strictly. Key rules:
+Follow [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) and [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md) strictly. Key rules:
 
 - Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
   **advisory language** (`should`, `recommended`) for guidance.
@@ -157,13 +157,13 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 - **New subject** — create the subject folder under the existing scope+type path. Add an
   allowed subject or use `principles` if none fits (propose a new subject via a `_core` ADR).
 - **New research** — add a `researches/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-006](../006-research-standards.md).
+  folder, following [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md).
 - **New skill** — add a `skills/[number]-[skill-name]/SKILL.md` inside the relevant subject
-  folder, following [_core-adr-003](../003-skill-standards.md).
+  folder, following [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-004](../004-article-standards.md).
+  folder, following [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md).
 - **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-007](../007-plan-standards.md).
+  folder, following [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md).
 
 ### Using XDRs in your own project
 
@@ -181,15 +181,15 @@ Follow [_core-adr-001](../001-xdrs-core.md) and [_core-adr-002](../002-xdr-stand
 
 ## References
 
-- [_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
-- [_core-adr-007](../007-plan-standards.md) - Plan standards
-- [001-lint skill](../skills/001-lint/SKILL.md) - Linting code against XDRs
-- [002-write-xdr skill](../skills/002-write-xdr/SKILL.md) - Writing a new XDR
-- [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill
-- [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
+- [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md) - XDR elements: types, scopes, subjects, folder structure
+- [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md) - XDR document standards and mandatory template
+- [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md) - Skill standards and co-location rules
+- [_core-adr-004](/.xdrs/_core/adrs/principles/004-article-standards.md) - Article standards
+- [_core-adr-006](/.xdrs/_core/adrs/principles/006-research-standards.md) - Research standards
+- [_core-adr-007](/.xdrs/_core/adrs/principles/007-plan-standards.md) - Plan standards
+- [001-lint skill](/.xdrs/_core/adrs/principles/skills/001-lint/SKILL.md) - Linting code against XDRs
+- [002-write-xdr skill](/.xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md) - Writing a new XDR
+- [003-write-skill skill](/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md) - Writing a new skill
+- [004-write-article skill](/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md) - Writing a new article
+- [005-write-research skill](/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md) - Writing a new research document
+- [_core-adr-005](/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md) - Semantic versioning rules for XDR packages

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

@@ -88,7 +88,7 @@ Scope: [scope identifier]
 
 ## References
 
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
+- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
 

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

@@ -123,7 +123,7 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ### Implementation Details
 [Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
 
-## Considered Options (if meaningful options exist)
+## Considered Options (only if the user explicitly indicated multiple options)
 
 ## Conflicts (mandatory if conflicts found in Phase 3)
 
@@ -140,8 +140,9 @@ Mandatory rules to apply while drafting:
 - 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.
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), 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 them using a same-folder relative path (e.g., `.assets/image.png`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - No emojis. Lowercase filenames.
 - Target under 1300 words total; under 2600 words for complex decisions.
 
@@ -187,6 +188,6 @@ If any check fails, revise and re-run this phase before proceeding.
 
 ## References
 
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
+- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
+- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)

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

@@ -97,8 +97,9 @@ Rules:
 - 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.
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), 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 them using a same-folder relative path (e.g., `.assets/image.png`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - No emojis. Lowercase filenames. Target under 6500 words.
 
 ### Phase 5: Review the Draft
@@ -154,6 +155,6 @@ If any check fails, revise before continuing.
 
 ## References
 
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [002-write-xdr skill](../002-write-xdr/SKILL.md)
+- [_core-adr-003 - Skill standards](/.xdrs/_core/adrs/principles/003-skill-standards.md)
+- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [002-write-xdr skill](/.github/skills/002-write-xdr/SKILL.md)

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

@@ -84,7 +84,7 @@ when referencing information from those documents. Keep under 1950 words total.]
 
 ## References
 
-- [XDR id or Skill name](relative/path/to/file.md) - Brief description of relevance
+- [XDR id or Skill name](/.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md) - Brief description of relevance
 ```
 
 Rules to apply while drafting:
@@ -93,8 +93,9 @@ Rules to apply while drafting:
 - 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.
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), 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 them using a same-folder relative path (e.g., `.assets/image.png`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - Keep the article under 1950 words; 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.
@@ -139,6 +140,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 - XDRs core](../../001-xdrs-core.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 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)

package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md

@@ -134,8 +134,9 @@ Rules:
 - 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.
+- Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), bullet points, 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 them using a same-folder relative path (e.g., `.assets/image.png`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - 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
@@ -266,9 +267,9 @@ If any check fails, revise before continuing.
 
 ## References
 
-- [_core-adr-006 - Research standards](../../006-research-standards.md)
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [002-write-xdr skill](../002-write-xdr/SKILL.md)
+- [_core-adr-006 - Research standards](/.xdrs/_core/adrs/principles/006-research-standards.md)
+- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [002-write-xdr skill](/.github/skills/002-write-xdr/SKILL.md)
 
 ## Constraints
 

package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md

@@ -114,7 +114,8 @@ Rules to apply while drafting:
 - If the plan scope is too large for 2 years, break it into multiple plans.
 - Remember that this plan must be deleted after full implementation. Write it with that ephemeral nature in mind.
 - Prefer plain Markdown, tables, or ASCII art for structure and flow.
-- If the plan genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/plans/assets/` and link with a relative path.
+- If the plan genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/plans/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
+- Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`).
 - Use lowercase file names. Never use emojis.
 
 ### Phase 6: Place and Register
@@ -152,6 +153,6 @@ Rules to apply while drafting:
 
 ## References
 
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [_core-adr-007 - Plan standards](../../007-plan-standards.md)
-- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
+- [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [_core-adr-007 - Plan standards](/.xdrs/_core/adrs/principles/007-plan-standards.md)
+- [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)

package/.xdrs/_core/bdrs/principles/001-xdr-decisions-and-skills-usage.md

@@ -47,6 +47,6 @@ Disallowed:
 
 ## References
 
-- [_core-adr-001](../../adrs/principles/001-xdrs-core.md)
-- [_core-adr-002](../../adrs/principles/002-xdr-standards.md)
-- [_core-adr-003](../../adrs/principles/003-skill-standards.md)
+- [_core-adr-001](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
+- [_core-adr-002](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
+- [_core-adr-003](/.xdrs/_core/adrs/principles/003-skill-standards.md)

package/README.md

@@ -86,20 +86,20 @@ 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
+        .assets/                     # optional local resources for subject-level XDR files
         researches/                 # optional decision-backing research documents
           [number]-[short-title].md
-          assets/
+          .assets/
         skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
-            assets/
+            .assets/
         articles/                   # optional synthetic views over XDRs, Research, and Skills
           [number]-[short-title].md
-          assets/
+          .assets/
         plans/                      # optional ephemeral execution plans
           [number]-[short-title].md
-          assets/
+          .assets/
 ```
 
 Document types:
@@ -129,7 +129,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, 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.
+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
 
@@ -168,7 +168,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - root index coverage for all discovered canonical indexes
 - XDR metadata section placement and `valid-from` / `applied-to` field format
 - local markdown links between XDR documents, skills, articles, researches, and plans (excluding fenced code blocks)
-- local image and `assets/` links resolving inside the sibling `assets/` folder for each document
+- local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document
 
 Examples:
 

package/lib/lint.js

@@ -22,7 +22,7 @@ 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', 'plans']);
-const RESOURCE_DIR_NAME = 'assets';
+const RESOURCE_DIR_NAME = '.assets';
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 
 function runLintCli(args) {
@@ -96,12 +96,13 @@ function lintWorkspace(targetPath, options = {}) {
 
 function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
   const content = fs.readFileSync(rootIndexPath, 'utf8');
+  const repoRoot = path.dirname(xdrsRoot);
 
   if (!content.includes(REQUIRED_ROOT_INDEX_TEXT)) {
     errors.push(`Root index is missing required override text: ${toDisplayPath(rootIndexPath)}`);
   }
 
-  const links = parseLocalLinks(content, path.dirname(rootIndexPath));
+  const links = parseLocalLinks(content, path.dirname(rootIndexPath), repoRoot);
   for (const linkPath of links) {
     if (!fs.existsSync(linkPath)) {
       errors.push(`Broken link in root index: ${displayPath(rootIndexPath, linkPath)}`);
@@ -572,7 +573,8 @@ function lintPlanExpectedEndDate(content, filePath, errors) {
 
 function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   const content = fs.readFileSync(indexPath, 'utf8');
-  const localLinks = parseLocalLinks(content, path.dirname(indexPath));
+  const repoRoot = path.dirname(xdrsRoot);
+  const localLinks = parseLocalLinks(content, path.dirname(indexPath), repoRoot);
   const linkedSet = new Set();
   const scopeName = path.relative(xdrsRoot, indexPath).split(path.sep)[0];
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
@@ -603,15 +605,24 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors) {
   const documentDir = path.dirname(documentPath);
   const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
+  const repoRoot = path.dirname(xdrsRoot);
 
   for (let index = 0; index < lines.length; index += 1) {
     if (ignoredLines[index]) {
       continue;
     }
 
-    for (const link of parseLocalLinkTargets(lines[index], documentDir)) {
+    for (const link of parseLocalLinkTargets(lines[index], documentDir, repoRoot)) {
       const isResourceLink = shouldValidateResourceLink(link.rawTarget);
 
+      if (!isResourceLink && !link.isAbsolutePath) {
+        const relativeToDoc = path.relative(documentDir, link.resolvedPath);
+        const goesUpToParent = relativeToDoc.startsWith('..');
+        if (goesUpToParent) {
+          errors.push(`Relative links to parent directories must use absolute paths starting with / in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget}`);
+        }
+      }
+
       if (!fs.existsSync(link.resolvedPath)) {
         if (isResourceLink) {
           errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
@@ -632,11 +643,11 @@ function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors) {
   }
 }
 
-function parseLocalLinks(markdown, baseDir) {
-  return parseLocalLinkTargets(markdown, baseDir).map((link) => link.resolvedPath);
+function parseLocalLinks(markdown, baseDir, repoRoot) {
+  return parseLocalLinkTargets(markdown, baseDir, repoRoot).map((link) => link.resolvedPath);
 }
 
-function parseLocalLinkTargets(markdown, baseDir) {
+function parseLocalLinkTargets(markdown, baseDir, repoRoot) {
   const links = [];
   const linkRe = /!?\[[^\]]+\]\(([^)]+)\)/g;
   let match = linkRe.exec(markdown);
@@ -644,9 +655,13 @@ function parseLocalLinkTargets(markdown, baseDir) {
     const rawTarget = match[1].trim();
     const normalizedTarget = normalizeLocalLinkTarget(rawTarget);
     if (normalizedTarget) {
+      const isAbsolutePath = normalizedTarget.startsWith('/');
       links.push({
         rawTarget,
-        resolvedPath: path.resolve(baseDir, normalizedTarget)
+        resolvedPath: isAbsolutePath && repoRoot
+          ? path.join(repoRoot, normalizedTarget)
+          : path.resolve(baseDir, normalizedTarget),
+        isAbsolutePath
       });
     }
     match = linkRe.exec(markdown);

package/lib/lint.test.js

@@ -145,7 +145,7 @@ test('allows _local XDR linking to another _local scope document', () => {
       '',
       '## Context and Problem Statement',
       '',
-      'See [second](002-second.md).',
+      'See [second](/.xdrs/_local/adrs/principles/002-second.md).',
       ''
     ].join('\n'),
     '.xdrs/_local/adrs/principles/002-second.md': [
@@ -187,6 +187,110 @@ test('reports non-_local canonical index linking to _local scope document', () =
   expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
 });
 
+test('reports relative non-asset links to parent directories in XDR documents', () => {
+  const workspaceRoot = createWorkspace('parent-dir-relative-link-in-xdr', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [other](../other.md).'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Relative links to parent directories must use absolute paths');
+  expect(result.errors.join('\n')).toContain('../other.md');
+});
+
+test('allows child directory relative non-asset links in XDR documents', () => {
+  const workspaceRoot = createWorkspace('child-dir-relative-link-in-xdr', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [skill](skills/001-lint/SKILL.md).'),
+  });
+  const skillDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/skills/001-lint');
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.writeFileSync(path.join(skillDir, 'SKILL.md'), '---\nname: 001-lint\ndescription: test skill\n---\n# Skill');
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Relative links to parent directories');
+  expect(result.errors.join('\n')).not.toContain('Broken local link');
+});
+
+test('allows same-directory relative non-asset links in XDR documents', () => {
+  const workspaceRoot = createWorkspace('same-dir-relative-link-in-xdr', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision',
+      '- [002-other](principles/002-other.md) - Other decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [other](002-other.md).'),
+    '.xdrs/_local/adrs/principles/002-other.md': xdrDocument('Other body.').replace('_local-adr-001-main', '_local-adr-002-other').replace('# _local-adr-001: Main decision', '# _local-adr-002: Other decision'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('absolute paths');
+  expect(result.errors.join('\n')).not.toContain('Broken local link');
+});
+
+test('allows relative asset links in XDR documents', () => {
+  const workspaceRoot = createWorkspace('relative-asset-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See ![diagram](.assets/diagram.png).'),
+  });
+  const assetsDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/.assets');
+  fs.mkdirSync(assetsDir, { recursive: true });
+  fs.writeFileSync(path.join(assetsDir, 'diagram.png'), Buffer.alloc(0));
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Non-asset links must use absolute paths');
+  expect(result.errors.join('\n')).not.toContain('Broken asset link');
+});
+
+test('reports absolute path link that is broken', () => {
+  const workspaceRoot = createWorkspace('broken-absolute-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See [missing](/.xdrs/_local/adrs/principles/999-nonexistent.md).'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Broken local link');
+  expect(result.errors.join('\n')).toContain('999-nonexistent.md');
+  expect(result.errors.join('\n')).not.toContain('Non-asset links must use absolute paths');
+});
+
+test('reports non-_local XDR linking to _local scope via absolute path', () => {
+  const workspaceRoot = createWorkspace('abs-non-local-links-to-local', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument(
+      'See [local doc](/.xdrs/_local/adrs/principles/001-main.md).'
+    ),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
+});
+
 function teamAdrIndex(entries) {
   return [
     '# myteam ADR Index',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.17.1",
+  "version": "0.19.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",