xdrs-core 0.18.0 → 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,7 +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.
+- **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:
@@ -126,20 +126,20 @@ 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

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.

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/`.
-- 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`).
+- 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:

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:

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:

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,9 +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 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`).
+- 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.
 

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

@@ -97,9 +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 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`).
+- 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

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

@@ -93,9 +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 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`).
+- 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.

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

@@ -134,9 +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 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`).
+- 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

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

@@ -114,8 +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 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`).
+- 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

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) {

package/lib/lint.test.js

@@ -243,9 +243,9 @@ test('allows relative asset links in XDR documents', () => {
     '.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).'),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('See ![diagram](.assets/diagram.png).'),
   });
-  const assetsDir = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/assets');
+  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));
 

package/package.json

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