xdrs-core 0.41.1 → 0.42.0

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

@@ -23,6 +23,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-015](principles/015-local-scope-type.md) - **_local scope type** — Defines the `_local` scope type: reserved for workspace-local decisions that must never be distributed
 - [_core-adr-policy-016](principles/016-policy-subjects.md) - **Policy Subjects** — Allowed subjects per type (ADR/BDR/EDR), descriptions, examples, and disambiguation tiebreakers
 - [_core-adr-policy-017](principles/017-policy-numbering-ranges.md) - **Policy numbering ranges** — Subject-based 100-number block ranges for policy numbering and the freeze-reference exemption
+- [_core-adr-policy-018](principles/018-external-path-symlinks.md) - **External path symlinks** — How to make XDRS files accessible from paths outside the .xdrs/ root using symlinks
 
 ## Skills
 

package/.xdrs/_core/adrs/principles/018-external-path-symlinks.md

@@ -0,0 +1,49 @@
+---
+name: _core-adr-policy-018-external-path-symlinks
+description: Governs how XDRS files that need to be accessible from paths outside the .xdrs/ root must be exposed using symlinks. Use when placing skills, articles, or any XDRS content at non-standard external paths required by external tools or conventions.
+apply-to: All XDRS workspaces where files need to be accessible from paths outside the .xdrs/ root
+valid-from: 2026-07-10
+---
+
+# _core-adr-policy-018: External path symlinks
+
+## Context and Problem Statement
+
+Some external tools and runtime environments require files at specific paths outside the `.xdrs/` folder. Examples include AI agent runtimes that expect skills in `.agents/skills/`, documentation generators that read from `docs/`, or CI tooling that references scripts from a fixed project-root path. Without a rule, contributors may duplicate files, breaking the single-source-of-truth guarantee that the `.xdrs/` root provides.
+
+This policy extends [`_core-adr-policy-001`](001-xdrs-core.md), which already prohibits creating or modifying XDRS documents via symlinked paths.
+
+How should XDRS files be made accessible from paths outside the `.xdrs/` root without duplicating their content?
+
+## Decision Outcome
+
+**Symlinks from external paths to the canonical `.xdrs/` location**
+
+When a file or directory inside `.xdrs/` needs to be reachable from an external path, a symlink MUST be created at the external path pointing to the canonical `.xdrs/` location. The canonical file always lives inside `.xdrs/`. Copying is never acceptable.
+
+**Example:** `.agents/skills/001-review` (symlink) → `.xdrs/_core/adrs/principles/skills/001-review/`
+
+### Details
+
+#### 01-canonical-source-must-be-in-xdrs
+Every XDRS file or directory that needs to be accessible from an external path MUST reside inside the `.xdrs/` root. The external path MUST be a symlink only.
+
+#### 02-files-must-not-be-copied-outside-xdrs
+XDRS files MUST NOT be copied to any path outside `.xdrs/`. Creating a copy — even a temporary one — violates the single-source-of-truth guarantee. Only symlinks are acceptable for external access.
+
+#### 03-symlinks-must-point-from-external-to-xdrs
+Symlinks MUST point from the external path to the `.xdrs/` target. The reverse direction — a symlink inside `.xdrs/` pointing outward — MUST NOT be used.
+
+#### 04-symlinks-should-be-declared
+Symlinks SHOULD be declared in `.filedist-package.yml` under the `symlinks:` block so they are created and managed automatically. When a symlink is created manually rather than through automation, its source and target MUST be documented in a README or equivalent note co-located with the external path.
+
+#### 05-symlinks-may-target-a-directory-or-a-single-file
+A symlink MAY target a directory (for example, an entire skill package folder) or an individual file, depending on what the external tool requires.
+
+#### 06-parent-directory-must-exist-before-symlink-creation
+The parent directory of the external symlink path MUST exist before the symlink is created. Symlink creation MUST NOT implicitly create parent directories as a side effect.
+
+## References
+
+- [`_core-adr-policy-001`](001-xdrs-core.md) — XDRS core framework: folder structure and the rule prohibiting modifications via symlinked paths
+- [`_core-adr-policy-008`](008-policy-structured-standards.md) — Policy structured standards: numbered rule block format used in this document

package/.xdrs/_core/index.md

@@ -24,6 +24,8 @@ If you are evaluating whether to adopt XDRS, setting up a new XDRS project, or e
 
 The core architectural decision [_core-adr-policy-001](adrs/principles/001-xdrs-core.md) defines the fundamental building blocks: three decision types (ADR for architecture, BDR for business, EDR for engineering), scopes as grouping boundaries, subjects as topic categories within each type, and a folder layout that keeps everything discoverable. It also defines the index system (canonical type indexes, scope indexes, and the root index) that ties the collection together.
 
+When external tools or conventions require XDRS files to be accessible from paths outside the `.xdrs/` root (for example, AI agent runtimes that expect skills in `.agents/skills/`), [_core-adr-policy-018](adrs/principles/018-external-path-symlinks.md) governs how to do this safely using symlinks.
+
 ### Document writing standards
 
 Each artifact type has its own writing standard:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.41.1",
+  "version": "0.42.0",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",