xdrs-core 0.15.1 → 0.15.3

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

@@ -77,12 +77,14 @@ Choose a title that clearly states the question this XDR answers, not the answer
 Use the mandatory template from `002-xdr-standards`:
 
 ```
-# [scope]-[type]-[number]: [Short Title]
+---
+name: [scope]-[type]-[number]-[short-title]
+description: [What this decision is about and when to use it]
+applied-to: [Optional. Contexts this decision applies to, under 40 words]
+valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+---
 
-## Metadata
-[Optional. Include only when at least one metadata field is present]
-Valid: [Optional. Use from YYYY-MM-DD to set a convergence date for adoption]
-Applied to: [Optional short applicability scope, under 40 words]
+# [scope]-[type]-[number]: [Short Title]
 
 ## Context and Problem Statement
 [background, who is impacted, and the explicit question being answered - under 40 words]
@@ -103,10 +105,10 @@ Applied to: [Optional short applicability scope, under 40 words]
 ```
 
 Mandatory rules to apply while drafting:
-- Include `## Metadata` only when `Valid:` and/or `Applied to:` adds value; omit the whole section when none of those fields is defined.
-- When present, place `## Metadata` immediately before `## Context and Problem Statement`.
-- Keep `Applied to:` under 40 words and use `Valid:` only with `from YYYY-MM-DD` format.
-- When metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `Valid:` sets a convergence date for adoption, `Applied to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
+- Include frontmatter `applied-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
+- Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
+- Keep `applied-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
+- When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `applied-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced XDRs — link instead.
 - 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.
@@ -122,7 +124,7 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Metadata**: If metadata exists, is it directly before Context, limited to `Valid:` / `Applied to:`, omitted entirely when both are absent, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
+2. **Frontmatter**: Are `applied-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
 3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
 5. **Redundancy**: Is the XDR the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?

package/README.md

@@ -153,7 +153,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
 The published package exposes the `xdrs-core` CLI.
 
 - Bootstrap or extract managed XDR files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint an XDR tree with `npx -y xdrs-core lint .`.
+- Lint an XDR tree with `npx -y xdrs-core lint .`. By default, read-only files distributed from external scopes are skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 
@@ -167,6 +167,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
 - XDR metadata section placement and `Valid` / `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
 
 Examples:

package/lib/lint.js

@@ -31,8 +31,10 @@ function runLintCli(args) {
     return 0;
   }
 
-  const targetPath = args[0] || '.';
-  const result = lintWorkspace(targetPath);
+  const all = args.includes('--all');
+  const pathArgs = args.filter((a) => !a.startsWith('--'));
+  const targetPath = pathArgs[0] || '.';
+  const result = lintWorkspace(targetPath, { ignoreReadOnly: !all });
 
   if (result.errors.length === 0) {
     console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
@@ -48,12 +50,15 @@ function runLintCli(args) {
 }
 
 function printHelp() {
-  console.log('Usage: xdrs-core lint [path]\n');
+  console.log('Usage: xdrs-core lint [options] [path]\n');
   console.log('Lint the XDR tree rooted at [path]/.xdrs or at [path] when [path] already points to .xdrs.');
-  console.log('All other commands continue to be delegated to the bundled filedist CLI.');
+  console.log('\nOptions:');
+  console.log('  --all    Check all files, including read-only files from other scopes (default: skip read-only files)');
+  console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
-function lintWorkspace(targetPath) {
+function lintWorkspace(targetPath, options = {}) {
+  const { ignoreReadOnly = true } = options;
   const resolvedTarget = path.resolve(targetPath);
   const xdrsRoot = path.basename(resolvedTarget) === '.xdrs'
     ? resolvedTarget
@@ -76,7 +81,7 @@ function lintWorkspace(targetPath) {
   }
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreReadOnly);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
@@ -124,9 +129,13 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreReadOnly) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
+  if (ignoreReadOnly && isReadOnly(scopePath)) {
+    return;
+  }
+
   if (!isValidScopeName(scopeName)) {
     errors.push(`Invalid scope name: ${toDisplayPath(scopePath)}`);
   }
@@ -139,7 +148,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes) {
         errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
         continue;
       }
-      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes);
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes, ignoreReadOnly);
       continue;
     }
 
@@ -147,7 +156,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes) {
   }
 }
 
-function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes) {
+function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, ignoreReadOnly) {
   const typePath = path.join(xdrsRoot, scopeName, typeName);
   const indexPath = path.join(typePath, 'index.md');
   const xdrNumbers = new Map();
@@ -155,7 +164,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
 
   if (!existsFile(indexPath)) {
     errors.push(`Missing canonical index: ${toDisplayPath(indexPath)}`);
-  } else {
+  } else if (!shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
     actualTypeIndexes.push(indexPath);
   }
 
@@ -174,15 +183,15 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
       continue;
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors, ignoreReadOnly));
   }
 
-  if (existsFile(indexPath)) {
+  if (existsFile(indexPath) && !shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
     lintTypeIndex(indexPath, xdrsRoot, artifacts, errors);
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors) {
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors, ignoreReadOnly) {
   const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
   const artifacts = [];
   const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
@@ -195,19 +204,19 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         continue;
       }
       if (entry.name === 'skills') {
-        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'articles') {
-        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'researches') {
-        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
       if (entry.name === 'plans') {
-        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
         continue;
       }
 
@@ -220,6 +229,10 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
     lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors);
   }
@@ -256,7 +269,7 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
 
   const expectedName = `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${shortTitle}`;
   lintXdrFrontmatter(content, expectedName, filePath, errors);
-  lintDocumentResourceLinks(filePath, errors);
+  lintDocumentLinks(filePath, errors);
 }
 
 function lintXdrFrontmatter(content, expectedName, filePath, errors) {
@@ -288,7 +301,7 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
 }
 
-function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
+function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const skillNumbers = new Map();
   const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
@@ -319,13 +332,18 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     const skillFilePath = path.join(entryPath, 'SKILL.md');
-    artifacts.push(skillFilePath);
 
     if (!existsFile(skillFilePath)) {
       errors.push(`Missing SKILL.md in skill package: ${toDisplayPath(entryPath)}`);
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(skillFilePath, ignoreReadOnly)) {
+      continue;
+    }
+
+    artifacts.push(skillFilePath);
+
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
     const skillFm = extractFrontmatter(skillContent);
     if (!skillFm.present) {
@@ -341,13 +359,13 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       }
     }
 
-    lintDocumentResourceLinks(skillFilePath, errors);
+    lintDocumentLinks(skillFilePath, errors);
   }
 
   return artifacts;
 }
 
-function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors) {
+function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const articleNumbers = new Map();
   const entries = safeReadDir(articlesPath, errors, `read articles directory ${scopeName}/${typeName}/${subjectName}/articles`);
@@ -369,6 +387,10 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -390,13 +412,13 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
 }
 
-function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors) {
+function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const researchNumbers = new Map();
   const entries = safeReadDir(researchPath, errors, `read research directory ${scopeName}/${typeName}/${subjectName}/researches`);
@@ -418,6 +440,10 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -439,13 +465,13 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
 }
 
-function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors) {
+function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors, ignoreReadOnly) {
   const artifacts = [];
   const planNumbers = new Map();
   const entries = safeReadDir(plansPath, errors, `read plans directory ${scopeName}/${typeName}/${subjectName}/plans`);
@@ -467,6 +493,10 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
       continue;
     }
 
+    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
+      continue;
+    }
+
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -489,7 +519,7 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     lintPlanExpectedEndDate(content, entryPath, errors);
-    lintDocumentResourceLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, errors);
   }
 
   return artifacts;
@@ -536,23 +566,32 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
-function lintDocumentResourceLinks(documentPath, errors) {
-  const content = fs.readFileSync(documentPath, 'utf8');
+function lintDocumentLinks(documentPath, errors) {
+  const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
   const documentDir = path.dirname(documentPath);
   const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
 
-  for (const link of parseLocalLinkTargets(content, documentDir)) {
-    if (!shouldValidateResourceLink(link.rawTarget)) {
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
       continue;
     }
 
-    if (!fs.existsSync(link.resolvedPath)) {
-      errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
-      continue;
-    }
+    for (const link of parseLocalLinkTargets(lines[index], documentDir)) {
+      const isResourceLink = shouldValidateResourceLink(link.rawTarget);
+
+      if (!fs.existsSync(link.resolvedPath)) {
+        if (isResourceLink) {
+          errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
+        } else {
+          errors.push(`Broken local link in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget}`);
+        }
+        continue;
+      }
 
-    if (!isPathInside(resourceDir, link.resolvedPath)) {
-      errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+      if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
+        errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+      }
     }
   }
 }
@@ -567,11 +606,11 @@ function parseLocalLinkTargets(markdown, baseDir) {
   let match = linkRe.exec(markdown);
   while (match) {
     const rawTarget = match[1].trim();
-    if (isLocalLink(rawTarget)) {
-      const targetWithoutAnchor = rawTarget.split('#')[0];
+    const normalizedTarget = normalizeLocalLinkTarget(rawTarget);
+    if (normalizedTarget) {
       links.push({
         rawTarget,
-        resolvedPath: path.resolve(baseDir, targetWithoutAnchor)
+        resolvedPath: path.resolve(baseDir, normalizedTarget)
       });
     }
     match = linkRe.exec(markdown);
@@ -579,6 +618,17 @@ function parseLocalLinkTargets(markdown, baseDir) {
   return links;
 }
 
+function normalizeLocalLinkTarget(target) {
+  if (!isLocalLink(target)) {
+    return null;
+  }
+
+  const bracketWrappedTarget = target.match(/^<(.+)>$/);
+  const cleanedTarget = bracketWrappedTarget ? bracketWrappedTarget[1] : target;
+
+  return cleanedTarget.split('#')[0].split('?')[0] || null;
+}
+
 function isLocalLink(target) {
   return target !== ''
     && !target.startsWith('#')
@@ -593,9 +643,13 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
 }
 
 function shouldValidateResourceLink(rawTarget) {
-  const targetWithoutAnchor = rawTarget.split('#')[0];
-  const normalizedTarget = targetWithoutAnchor.replace(/\\/g, '/');
-  const extension = path.extname(targetWithoutAnchor).toLowerCase();
+  const normalizedTargetPath = normalizeLocalLinkTarget(rawTarget);
+  if (!normalizedTargetPath) {
+    return false;
+  }
+
+  const normalizedTarget = normalizedTargetPath.replace(/\\/g, '/');
+  const extension = path.extname(normalizedTargetPath).toLowerCase();
 
   return normalizedTarget === RESOURCE_DIR_NAME
     || normalizedTarget.startsWith(`${RESOURCE_DIR_NAME}/`)
@@ -629,12 +683,20 @@ function stripFrontmatter(content) {
 function findIgnoredMarkdownLines(lines) {
   const ignored = [];
   let inCodeFence = false;
+  let activeFence = null;
 
   for (let index = 0; index < lines.length; index += 1) {
     const trimmed = lines[index].trim();
-    if (/^```/.test(trimmed)) {
+    const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+    if (fenceMatch) {
       ignored[index] = true;
-      inCodeFence = !inCodeFence;
+      if (activeFence === fenceMatch[1][0]) {
+        activeFence = null;
+        inCodeFence = false;
+      } else if (activeFence === null) {
+        activeFence = fenceMatch[1][0];
+        inCodeFence = true;
+      }
       continue;
     }
 
@@ -744,6 +806,19 @@ function existsFile(filePath) {
   }
 }
 
+function isReadOnly(filePath) {
+  try {
+    fs.accessSync(filePath, fs.constants.W_OK);
+    return false;
+  } catch {
+    return true;
+  }
+}
+
+function shouldSkipReadOnlyPath(filePath, ignoreReadOnly) {
+  return ignoreReadOnly && isReadOnly(filePath);
+}
+
 function displayPath(indexPath, targetPath) {
   return `${toDisplayPath(indexPath)} -> ${toDisplayPath(targetPath)}`;
 }

package/lib/lint.test.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { lintWorkspace } = require('./lint');
+
+let tmpRoot;
+
+beforeAll(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'xdrs-core-lint-'));
+});
+
+afterAll(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+test('reports broken local document links in XDR files', () => {
+  const workspaceRoot = createWorkspace('broken-xdr-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](002-missing.md).`),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Broken local link in');
+  expect(result.errors.join('\n')).toContain('002-missing.md');
+});
+
+test('ignores local links inside fenced code blocks', () => {
+  const workspaceRoot = createWorkspace('ignore-code-fence', {
+    '.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([
+      '```markdown',
+      '[Missing](002-missing.md)',
+      '```'
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Broken local link in');
+});
+
+test('reports broken local document links in skill files', () => {
+  const workspaceRoot = createWorkspace('broken-skill-link', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('See [Missing](missing.md).'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Broken local link in');
+  expect(result.errors.join('\n')).toContain('missing.md');
+});
+
+test('skips read-only files by default and checks them when ignoreReadOnly is false', () => {
+  const workspaceRoot = createWorkspace('readonly-default-skip', {
+    '.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](002-missing.md).'),
+  });
+  const filePath = path.join(workspaceRoot, '.xdrs/_local/adrs/principles/001-main.md');
+  fs.chmodSync(filePath, 0o444);
+
+  const defaultResult = lintWorkspace(workspaceRoot);
+  const allResult = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(defaultResult.errors.join('\n')).not.toContain('Broken local link in');
+  expect(allResult.errors.join('\n')).toContain('Broken local link in');
+});
+
+function createWorkspace(name, files) {
+  const workspaceRoot = path.join(tmpRoot, name);
+  fs.mkdirSync(workspaceRoot, { recursive: true });
+
+  for (const [relativePath, content] of Object.entries(files)) {
+    const filePath = path.join(workspaceRoot, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+  }
+
+  return workspaceRoot;
+}
+
+function rootIndex() {
+  return [
+    '# XDR Standards Index',
+    '',
+    '## Scope Indexes',
+    '',
+    'XDRs in scopes listed last override the ones listed first',
+    '',
+    '### _local (reserved)',
+    '',
+    'Project-local XDRs stay in the workspace tree only.',
+  ].join('\n');
+}
+
+function localAdrIndex(entries) {
+  return [
+    '# _local ADR Index',
+    '',
+    'Local ADRs for tests.',
+    '',
+    '## principles',
+    '',
+    ...entries,
+    ''
+  ].join('\n');
+}
+
+function xdrDocument(body) {
+  return [
+    '---',
+    'name: _local-adr-001-main',
+    'description: Test XDR document',
+    '---',
+    '',
+    '# _local-adr-001: Main decision',
+    '',
+    '## Context and Problem Statement',
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
+function skillDocument(body) {
+  return [
+    '---',
+    'name: 001-check-links',
+    'description: Test skill document',
+    '---',
+    '',
+    '# Test skill',
+    '',
+    body,
+    ''
+  ].join('\n');
+}

package/package.json

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