xdrs-core 0.15.3 → 0.16.0

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

@@ -57,7 +57,7 @@ Collectively, these are referred to as XDRs.
 - **Scopes:** 
   - Short name that defines a group or a package of xdrs
   - examples: `business-x`, `business-y`, `team-43`, `_core`
-  - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared `.xdrs/index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them.
+  - `_local` is a reserved scope for XDRs created locally to a specific project or repository. XDRs in `_local` must not be shared with or propagated to other contexts. This scope must always be placed in the lowest position in `.xdrs/index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared `.xdrs/index.md` files MUST NOT link `_local` canonical type indexes because `_local` stays workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try to discover existing workspace-local `_local` canonical indexes by default, even when the shared root index does not link them. Documents in non-`_local` scopes MUST NEVER link to any document inside the `_local` scope, because `_local` is workspace-only and such links would break in any consumer workspace. Documents inside `_local` MAY link to other documents inside `_local`.
   - **Types:** `adrs`, `bdrs`, `edrs`
   - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
 - **Subjects:** MUST be one of the following depending on the type of the XDR. Use the subject to indicate the main concern of the decision.

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

@@ -121,7 +121,7 @@ Prefer tables, bullets, or ASCII art for simple comparisons. Use external figure
 
 ## Considered Options
 
-- Related research: [001-research-and-decision-lifecycle](../../../_local/adrs/principles/researches/001-research-and-decision-lifecycle.md)
+- Related research: `001-research-and-decision-lifecycle` (workspace-local research)
 
 * (REJECTED) **Inline long-form analysis inside the XDR** - Put all research and decision text in one file.
   * Reason: Makes XDRs too long, mixes evidence with the adopted rule set, and hurts fast retrieval by humans and AI agents.

package/.xdrs/index.md

@@ -19,4 +19,4 @@ Decisions about how XDRs work
 
 ### _local (reserved)
 
-Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Keep `_local` canonical indexes in the workspace tree only; do not link them from this shared index. Readers and tools should still try to discover existing `_local` indexes in the current workspace by default.
+Project-local XDRs that must not be shared with other contexts. Always keep this scope last so its decisions override or extend all scopes listed above. Keep `_local` canonical indexes in the workspace tree only; do not link them from this shared index. Readers and tools should still try to discover existing `_local` indexes in the current workspace by default. Documents in non-`_local` scopes must never link into `_local`; only `_local` documents may link to other `_local` documents.

package/lib/lint.js

@@ -248,7 +248,6 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   }
 
   const number = match[1];
-  const shortTitle = match[2];
   const previous = xdrNumbers.get(number);
   if (previous) {
     errors.push(`Duplicate XDR number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
@@ -267,9 +266,35 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
     errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
 
-  const expectedName = `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${shortTitle}`;
+  const expectedName = extractExpectedXdrNameFromHeading(firstLine)
+    || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
   lintXdrFrontmatter(content, expectedName, filePath, errors);
-  lintDocumentLinks(filePath, errors);
+  lintDocumentLinks(filePath, xdrsRoot, scopeName, errors);
+}
+
+function extractExpectedXdrNameFromHeading(headingLine) {
+  const match = headingLine.match(/^#\s+([a-z0-9_]+-(?:adr|bdr|edr)-\d{3,}):\s+(.+?)\s*$/);
+  if (!match) {
+    return null;
+  }
+
+  const identifier = match[1];
+  const titleSlug = slugifyTitle(match[2]);
+  if (!titleSlug) {
+    return null;
+  }
+
+  return `${identifier}-${titleSlug}`;
+}
+
+function slugifyTitle(title) {
+  return title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .replace(/--+/g, '-');
 }
 
 function lintXdrFrontmatter(content, expectedName, filePath, errors) {
@@ -359,7 +384,7 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       }
     }
 
-    lintDocumentLinks(skillFilePath, errors);
+    lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -412,7 +437,7 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -465,7 +490,7 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -519,7 +544,7 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     lintPlanExpectedEndDate(content, entryPath, errors);
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -549,6 +574,8 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   const content = fs.readFileSync(indexPath, 'utf8');
   const localLinks = parseLocalLinks(content, path.dirname(indexPath));
   const linkedSet = new Set();
+  const scopeName = path.relative(xdrsRoot, indexPath).split(path.sep)[0];
+  const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (const linkPath of localLinks) {
     if (!fs.existsSync(linkPath)) {
@@ -556,6 +583,10 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
       continue;
     }
 
+    if (scopeName !== '_local' && (isPathInside(localScopePath, linkPath) || normalizePath(linkPath) === localScopePath)) {
+      errors.push(`Non-_local document must not link into _local scope: ${displayPath(indexPath, linkPath)}`);
+    }
+
     linkedSet.add(normalizePath(linkPath));
   }
 
@@ -566,11 +597,12 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
-function lintDocumentLinks(documentPath, errors) {
+function lintDocumentLinks(documentPath, xdrsRoot, scopeName, 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);
+  const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (let index = 0; index < lines.length; index += 1) {
     if (ignoredLines[index]) {
@@ -589,6 +621,10 @@ function lintDocumentLinks(documentPath, errors) {
         continue;
       }
 
+      if (scopeName !== '_local' && (isPathInside(localScopePath, link.resolvedPath) || normalizePath(link.resolvedPath) === localScopePath)) {
+        errors.push(`Non-_local document must not link into _local scope in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget}`);
+      }
+
       if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
         errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
       }

package/lib/lint.test.js

@@ -82,6 +82,140 @@ test('skips read-only files by default and checks them when ignoreReadOnly is fa
   expect(allResult.errors.join('\n')).toContain('Broken local link in');
 });
 
+test('derives expected frontmatter name from the markdown heading title', () => {
+  const workspaceRoot = createWorkspace('heading-name-match', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [002-scope-guidelines](principles/002-xdr-scope-guidelines.md) - Scope guidelines'
+    ]),
+    '.xdrs/_local/adrs/principles/002-xdr-scope-guidelines.md': [
+      '---',
+      'name: _local-adr-002-xdr-scope-guidelines-for-agentme',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-002: XDR scope guidelines for agentme',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).not.toContain('XDR frontmatter name must be');
+});
+
+test('reports non-_local XDR linking to _local scope document', () => {
+  const workspaceRoot = createWorkspace('non-local-links-to-local-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('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](../../../_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');
+});
+
+test('allows _local XDR linking to another _local scope document', () => {
+  const workspaceRoot = createWorkspace('local-links-to-local', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision',
+      '- [002-second](principles/002-second.md) - Second decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': [
+      '---',
+      'name: _local-adr-001-main',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See [second](002-second.md).',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/002-second.md': [
+      '---',
+      'name: _local-adr-002-second',
+      'description: Second test XDR document',
+      '---',
+      '',
+      '# _local-adr-002: Second decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Second body.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).not.toContain('Non-_local document must not link into _local scope');
+  expect(result.errors.join('\n')).not.toContain('Broken local link');
+});
+
+test('reports non-_local canonical index linking to _local scope document', () => {
+  const workspaceRoot = createWorkspace('non-local-type-index-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([
+      '- [_local 001](../../_local/adrs/principles/001-main.md) - Cross-scope link'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  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',
+    '',
+    'Team ADRs for tests.',
+    '',
+    '## principles',
+    '',
+    ...entries,
+    ''
+  ].join('\n');
+}
+
+function teamXdrDocument(body) {
+  return [
+    '---',
+    'name: myteam-adr-001-team',
+    'description: Team test XDR document',
+    '---',
+    '',
+    '# myteam-adr-001: Team decision',
+    '',
+    '## Context and Problem Statement',
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
 function createWorkspace(name, files) {
   const workspaceRoot = path.join(tmpRoot, name);
   fs.mkdirSync(workspaceRoot, { recursive: true });

package/package.json

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