xdrs-core 0.17.1 → 0.18.0

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

@@ -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:
@@ -144,8 +145,8 @@ subject/
 ## 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

@@ -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

@@ -116,7 +116,7 @@ Rules:
 - 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 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

@@ -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

@@ -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

@@ -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

@@ -141,7 +141,8 @@ Mandatory rules to apply while drafting:
 - 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.
+- 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

@@ -98,7 +98,8 @@ Rules:
 - 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.
+- 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:
@@ -94,7 +94,8 @@ Rules to apply while drafting:
 - 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.
+- 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

@@ -135,7 +135,8 @@ Rules:
 - 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.
+- 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/lib/lint.js

@@ -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.18.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",