xdrs-core 0.7.1 → 0.9.0

package/README.md

@@ -12,11 +12,14 @@ This project defines a standard for organizing XDRs that satisfies the following
 
 ## XDR elements
 
-Every XDR package contains three types of documents:
+Every XDR package contains four types of documents:
 
-- **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth.
-- **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
-- **Articles** — Synthetic explanatory texts that combine information from multiple XDRs and Skills around a specific topic or audience. They never replace XDRs as source of truth.
+- **Decision Records (XDRs)** — Architectural (ADR), Business (BDR), or Engineering (EDR) records that capture a single decision, its rationale, and the rules that follow from it. They are the source of truth. An XDR may optionally start with a `Metadata` section for short applicability and validity markers.
+- **Research** — Exploratory documents that capture the problem being investigated, constraints or requirements, findings, and option tradeoffs that back a decision during its lifecycle. One research document may inform multiple downstream decisions, but it is not a replacement for the Decision Record.
+- **Skills** — Step-by-step procedural guides that can be followed by humans, AI agents, or both. Skills are task-based artifacts with a concrete outcome and should include enough detail to verify the task was completed correctly. A skill may start as a fully manual procedure and evolve toward partial or full AI automation over time. Co-located with the XDRs they implement.
+- **Articles** — Synthetic explanatory texts that combine information from multiple XDRs, Research documents, and Skills around a specific topic or audience. They never replace XDRs as source of truth.
+
+For simple indications, prefer plain Markdown, tables, or ASCII art. Use local images and other supporting files only when they are materially necessary, and keep them in a sibling `assets/` folder next to the document file.
 
 ## Getting started
 
@@ -51,8 +54,11 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - XDR numbering uniqueness per `scope/type`
 - skill numbering uniqueness per `scope/type/subject/skills`
 - article numbering uniqueness per `scope/type/subject/articles`
+- research numbering uniqueness per `scope/type/subject/researches`
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
+- XDR metadata section placement and `Applied to` / `Validity` field format
+- local image and `assets/` links resolving inside the sibling `assets/` folder for each document
 
 Examples:
 
@@ -106,11 +112,17 @@ 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
+        researches/                 # optional decision-backing research documents
+          [number]-[short-title].md
+          assets/
         skills/                     # optional skill packages for humans and AI agents
           [number]-[skill-name]/
             SKILL.md
-        articles/                   # optional synthetic views over XDRs and Skills
+            assets/
+        articles/                   # optional synthetic views over XDRs, Research, and Skills
           [number]-[short-title].md
+          assets/
 ```
 
 Document types:
@@ -118,31 +130,32 @@ Document types:
 - **ADR** - Architectural Decision Record: architectural and technical decisions
 - **BDR** - Business Decision Record: business process and strategy decisions
 - **EDR** - Engineering Decision Record: engineering workflow and tooling decisions
-- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Decision Records, but add the execution detail they lack. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the XDRs they implement inside `skills/` sub-directories.
-- **Articles** - Synthetic views that explain concepts or combine information from multiple Decision Records and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Decision Records take precedence when there is a conflict. Useful as navigational indexes that link related DRs and Skills around a specific aspect.
+- **Research** - Exploratory support material used while evaluating or updating a decision. Research captures constraints, findings, options, and proposal tradeoffs, but it is not the source of truth.
+- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Decision Records, but add the execution detail they lack. Skills are not mandatory by themselves unless referenced by an XDR or another policy artifact. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the XDRs they implement inside `skills/` sub-directories.
+- **Articles** - Synthetic views that explain concepts or combine information from multiple Decision Records, Research documents, and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Decision Records take precedence when there is a conflict. Useful as navigational indexes that link related artifacts around a specific aspect.
 
 See [.xdrs/index.md](.xdrs/index.md) for the full list of active decision records.
 
 For a deeper overview of XDRs — objective, structure, guidelines, extension, and usage — see the [XDRs Overview article](.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md).
-For packaging guidance on publishing your own reusable scope with DRs, skills, and articles, see the [Create your own xdrs-core extension package article](docs/create-your-own-xdrs-extension-package.md), then compare [examples/basic-usage](examples/basic-usage) and [examples/mydevkit](examples/mydevkit).
+For packaging guidance on publishing your own reusable scope with DRs, Research documents, skills, and articles, see the [Create your own xdrs-core extension package article](docs/create-your-own-xdrs-extension-package.md), then compare [examples/basic-usage](examples/basic-usage) and [examples/mydevkit](examples/mydevkit).
 
 ## Flow: Decision -> Distribution -> Usage
 
-XDRs and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
+XDRs, Research documents, and skills follow a three-stage lifecycle that keeps decision-making decentralized while allowing controlled adoption across projects.
 
 ### Decision
 
-Each scope manages its own set of XDRs independently. Scope owners discuss and evolve decisions through whatever process fits their team, such as RFCs, pull requests, or architecture review boards. XDRs and skills are authored, reviewed, and merged within the scope's folder in the repository.
+Each scope manages its own set of XDR artifacts independently. Scope owners discuss and evolve decisions through whatever process fits their team, such as RFCs, pull requests, or architecture review boards. Research documents, XDRs, and skills are authored, reviewed, and merged within the scope's folder in the repository.
 
 ### Distribution
 
 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 skills: 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
 
-A project that wants to follow a scope's decisions adds the corresponding npm package as a regular dependency. Using a tool such as [filedist](https://github.com/flaviostutz/filedist), the package contents are unpacked into the project's `.xdrs/` folder at install or update time. Updating the dependency version pulls in the latest XDRs and skills for that scope, keeping the project aligned with the scope owners' current decisions.
+A project that wants to follow a scope's decisions adds the corresponding npm package as a regular dependency. Using a tool such as [filedist](https://github.com/flaviostutz/filedist), the package contents are unpacked into the project's `.xdrs/` folder at install or update time. Updating the dependency version pulls in the latest XDRs, Research documents, and skills for that scope, keeping the project aligned with the scope owners' current decisions.
 
 Multiple scope packages can be combined in the same workspace by listing them as separate dependencies. Scope precedence (defined in `.xdrs/index.md`) determines which decisions take effect when scopes overlap.
 
@@ -152,6 +165,7 @@ Multiple scope packages can be combined in the same workspace by listing them as
     adrs/ bdrs/ edrs/                                                adrs/ bdrs/ edrs/
     [subject]/                                                        [subject]/
       *.md                                                              *.md
+      researches/                                                       researches/
       skills/                                                           skills/
       articles/                                                         articles/
 ```

package/lib/lint.js

@@ -21,6 +21,9 @@ const RESERVED_SCOPES = new Set(['_core', '_local']);
 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']);
+const RESOURCE_DIR_NAME = 'assets';
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 
 function runLintCli(args) {
   if (args.includes('--help') || args.includes('-h')) {
@@ -190,6 +193,9 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
     const entryPath = path.join(subjectPath, entry.name);
 
     if (entry.isDirectory()) {
+      if (entry.name === RESOURCE_DIR_NAME) {
+        continue;
+      }
       if (entry.name === 'skills') {
         artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
@@ -198,6 +204,10 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
+      if (entry.name === 'researches') {
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        continue;
+      }
 
       errors.push(`Unexpected directory under ${scopeName}/${typeName}/${subjectName}: ${toDisplayPath(entryPath)}`);
       continue;
@@ -240,6 +250,120 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   if (!firstLine.startsWith(expectedHeader)) {
     errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
+
+  lintXdrMetadata(content, filePath, errors);
+  lintDocumentResourceLinks(filePath, errors);
+}
+
+function lintXdrMetadata(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const metadataLine = findHeadingLine(lines, ignoredLines, '## Metadata');
+  const contextLine = findHeadingLine(lines, ignoredLines, '## Context and Problem Statement');
+  const headingLines = findHeadingLines(lines, ignoredLines);
+
+  if (metadataLine !== -1) {
+    const nextHeadingLine = headingLines.find((lineIndex) => lineIndex > metadataLine);
+    if (nextHeadingLine !== contextLine) {
+      errors.push(`XDR metadata section must appear immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+    }
+  }
+
+  if (metadataLine !== -1 && contextLine !== -1 && metadataLine > contextLine) {
+    errors.push(`XDR metadata section must appear before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+  }
+
+  const metadataRange = metadataLine === -1
+    ? null
+    : {
+        start: metadataLine + 1,
+        end: (headingLines.find((lineIndex) => lineIndex > metadataLine) ?? lines.length) - 1
+      };
+  const appliedLineNumbers = findFieldLines(lines, ignoredLines, 'Applied to:');
+  const validityLineNumbers = findFieldLines(lines, ignoredLines, 'Validity:');
+
+  if (!metadataRange && (appliedLineNumbers.length > 0 || validityLineNumbers.length > 0)) {
+    errors.push(`XDR metadata fields require a ## Metadata section immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+    return;
+  }
+
+  if (!metadataRange) {
+    return;
+  }
+
+  const metadataApplied = appliedLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+  const metadataValidity = validityLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
+
+  if (metadataApplied.length === 0 && metadataValidity.length === 0) {
+    errors.push(`XDR metadata section must be omitted when no metadata fields are defined: ${toDisplayPath(filePath)}`);
+  }
+
+  if (metadataApplied.length > 1) {
+    errors.push(`XDR metadata must not repeat Applied to: ${toDisplayPath(filePath)}`);
+  }
+
+  if (metadataValidity.length > 1) {
+    errors.push(`XDR metadata must not repeat Validity: ${toDisplayPath(filePath)}`);
+  }
+
+  for (const lineIndex of [...appliedLineNumbers, ...validityLineNumbers]) {
+    if (!isLineInsideRange(lineIndex, metadataRange)) {
+      errors.push(`XDR metadata fields must be declared inside ## Metadata: ${toDisplayPath(filePath)}`);
+      break;
+    }
+  }
+
+  for (let lineIndex = metadataRange.start; lineIndex <= metadataRange.end; lineIndex += 1) {
+    if (ignoredLines[lineIndex]) {
+      continue;
+    }
+    const trimmed = lines[lineIndex].trim();
+    if (trimmed === '') {
+      continue;
+    }
+    if (!trimmed.startsWith('Applied to:') && !trimmed.startsWith('Validity:')) {
+      errors.push(`XDR metadata section only supports Applied to: and Validity: fields: ${toDisplayPath(filePath)}`);
+      break;
+    }
+  }
+
+  if (metadataApplied.length === 1) {
+    const value = lines[metadataApplied[0]].slice('Applied to:'.length).trim();
+    if (value === '') {
+      errors.push(`XDR Applied to: must not be empty: ${toDisplayPath(filePath)}`);
+    } else if (countWords(value) >= 40) {
+      errors.push(`XDR Applied to: must be under 40 words: ${toDisplayPath(filePath)}`);
+    }
+  }
+
+  if (metadataValidity.length === 1) {
+    lintValidityField(lines[metadataValidity[0]], filePath, errors);
+  }
+}
+
+function lintValidityField(line, filePath, errors) {
+  const value = line.slice('Validity:'.length).trim().replace(/\.$/, '');
+
+  if (value === 'Draft' || value === 'Retired') {
+    return;
+  }
+
+  const validityMatch = value.match(/^(?:from\s+(\d{4}-\d{2}-\d{2}))?(?:\s+until\s+(\d{4}-\d{2}-\d{2}))?$/);
+  if (!validityMatch || (!validityMatch[1] && !validityMatch[2])) {
+    errors.push(`XDR Validity: must be Draft, Retired, from YYYY-MM-DD, until YYYY-MM-DD, or from YYYY-MM-DD until YYYY-MM-DD: ${toDisplayPath(filePath)}`);
+    return;
+  }
+
+  const fromDate = validityMatch[1];
+  const untilDate = validityMatch[2];
+  if ((fromDate && !isIsoDate(fromDate)) || (untilDate && !isIsoDate(untilDate))) {
+    errors.push(`XDR Validity: must use ISO dates in YYYY-MM-DD format: ${toDisplayPath(filePath)}`);
+    return;
+  }
+
+  if (fromDate && untilDate && fromDate > untilDate) {
+    errors.push(`XDR Validity: from date must be on or before until date: ${toDisplayPath(filePath)}`);
+  }
 }
 
 function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
@@ -287,6 +411,8 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     } else if (frontmatterName !== entry.name) {
       errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
     }
+
+    lintDocumentResourceLinks(skillFilePath, errors);
   }
 
   return artifacts;
@@ -299,6 +425,10 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
 
   for (const entry of entries) {
     const entryPath = path.join(articlesPath, entry.name);
+    if (entry.isDirectory() && entry.name === RESOURCE_DIR_NAME) {
+      continue;
+    }
+
     if (!entry.isFile()) {
       errors.push(`Unexpected directory in articles folder: ${toDisplayPath(entryPath)}`);
       continue;
@@ -330,6 +460,57 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     if (!firstLine.startsWith(expectedHeader)) {
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
+
+    lintDocumentResourceLinks(entryPath, errors);
+  }
+
+  return artifacts;
+}
+
+function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors) {
+  const artifacts = [];
+  const researchNumbers = new Map();
+  const entries = safeReadDir(researchPath, errors, `read research directory ${scopeName}/${typeName}/${subjectName}/researches`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(researchPath, entry.name);
+    if (entry.isDirectory() && entry.name === RESOURCE_DIR_NAME) {
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      errors.push(`Unexpected directory in researches folder: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const match = entry.name.match(NUMBERED_FILE_RE);
+    if (!match) {
+      errors.push(`Invalid research file name: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    artifacts.push(entryPath);
+
+    const number = match[1];
+    const previous = researchNumbers.get(number);
+    if (previous) {
+      errors.push(`Duplicate research number ${number} in ${scopeName}/${typeName}/${subjectName}/researches: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)}`);
+    } else {
+      researchNumbers.set(number, entryPath);
+    }
+
+    if (entry.name !== entry.name.toLowerCase()) {
+      errors.push(`Research file name must be lowercase: ${toDisplayPath(entryPath)}`);
+    }
+
+    const content = fs.readFileSync(entryPath, 'utf8');
+    const expectedHeader = `# ${scopeName}-research-${number}:`;
+    const firstLine = firstNonEmptyLine(content);
+    if (!firstLine.startsWith(expectedHeader)) {
+      errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
+    }
+
+    lintDocumentResourceLinks(entryPath, errors);
   }
 
   return artifacts;
@@ -356,15 +537,43 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
+function lintDocumentResourceLinks(documentPath, errors) {
+  const content = fs.readFileSync(documentPath, 'utf8');
+  const documentDir = path.dirname(documentPath);
+  const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
+
+  for (const link of parseLocalLinkTargets(content, documentDir)) {
+    if (!shouldValidateResourceLink(link.rawTarget)) {
+      continue;
+    }
+
+    if (!fs.existsSync(link.resolvedPath)) {
+      errors.push(`Broken asset link in ${toDisplayPath(documentPath)}: ${link.rawTarget}`);
+      continue;
+    }
+
+    if (!isPathInside(resourceDir, link.resolvedPath)) {
+      errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
+    }
+  }
+}
+
 function parseLocalLinks(markdown, baseDir) {
+  return parseLocalLinkTargets(markdown, baseDir).map((link) => link.resolvedPath);
+}
+
+function parseLocalLinkTargets(markdown, baseDir) {
   const links = [];
-  const linkRe = /\[[^\]]+\]\(([^)]+)\)/g;
+  const linkRe = /!?\[[^\]]+\]\(([^)]+)\)/g;
   let match = linkRe.exec(markdown);
   while (match) {
     const rawTarget = match[1].trim();
     if (isLocalLink(rawTarget)) {
       const targetWithoutAnchor = rawTarget.split('#')[0];
-      links.push(path.resolve(baseDir, targetWithoutAnchor));
+      links.push({
+        rawTarget,
+        resolvedPath: path.resolve(baseDir, targetWithoutAnchor)
+      });
     }
     match = linkRe.exec(markdown);
   }
@@ -384,6 +593,17 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
   return relative.length === 3 && TYPE_NAMES.has(relative[1]) && relative[2] === 'index.md';
 }
 
+function shouldValidateResourceLink(rawTarget) {
+  const targetWithoutAnchor = rawTarget.split('#')[0];
+  const normalizedTarget = targetWithoutAnchor.replace(/\\/g, '/');
+  const extension = path.extname(targetWithoutAnchor).toLowerCase();
+
+  return normalizedTarget === RESOURCE_DIR_NAME
+    || normalizedTarget.startsWith(`${RESOURCE_DIR_NAME}/`)
+    || normalizedTarget.includes(`/${RESOURCE_DIR_NAME}/`)
+    || IMAGE_EXTENSIONS.has(extension);
+}
+
 function extractFrontmatterName(content) {
   const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
   if (!frontmatterMatch) {
@@ -394,6 +614,82 @@ function extractFrontmatterName(content) {
   return nameMatch ? nameMatch[1].trim() : null;
 }
 
+function findIgnoredMarkdownLines(lines) {
+  const ignored = [];
+  let inCodeFence = false;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (/^```/.test(trimmed)) {
+      ignored[index] = true;
+      inCodeFence = !inCodeFence;
+      continue;
+    }
+
+    ignored[index] = inCodeFence;
+  }
+
+  return ignored;
+}
+
+function findHeadingLine(lines, ignoredLines, headingText) {
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (lines[index].trim() === headingText) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function findHeadingLines(lines, ignoredLines) {
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (/^##\s+/.test(lines[index].trim())) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+function findFieldLines(lines, ignoredLines, prefix) {
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (ignoredLines[index]) {
+      continue;
+    }
+    if (lines[index].trim().startsWith(prefix)) {
+      result.push(index);
+    }
+  }
+  return result;
+}
+
+function isLineInsideRange(lineIndex, range) {
+  return lineIndex >= range.start && lineIndex <= range.end;
+}
+
+function countWords(value) {
+  return value.split(/\s+/).filter(Boolean).length;
+}
+
+function isIsoDate(value) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return false;
+  }
+
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day;
+}
+
 function firstNonEmptyLine(content) {
   const lines = content.split(/\r?\n/);
   for (const line of lines) {
@@ -452,6 +748,11 @@ function normalizePath(filePath) {
   return path.normalize(filePath);
 }
 
+function isPathInside(parentPath, childPath) {
+  const relative = path.relative(parentPath, childPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
 module.exports = {
   runLintCli,
   lintWorkspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.7.1",
+  "version": "0.9.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",
@@ -14,10 +14,10 @@
   ],
   "license": "MIT",
   "files": [
-    ".xdrs/**",
+    ".xdrs/_core/**",
+    ".xdrs/index.md",
     "package.json",
     "AGENTS.md",
-    "AGENTS.local.md",
     "bin/filedist.js",
     "lib/**/*.js"
   ],
@@ -47,8 +47,7 @@
       {
         "selector": {
           "files": [
-            ".xdrs/index.md",
-            "AGENTS.local.md"
+            ".xdrs/index.md"
           ]
         },
         "output": {

package/AGENTS.local.md

@@ -1,3 +0,0 @@
-# AGENTS.local.md
-
-No repository specific instructions available. Focus on XDRS instructions only.