xdrs-core 0.5.0 → 0.7.0

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

@@ -11,6 +11,16 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-001](principles/001-xdr-standards.md) - **XDR standards** (includes XDR template)
 - [_core-adr-003](principles/003-skill-standards.md) - **Skill standards**
 - [_core-adr-004](principles/004-article-standards.md) - **Article standards**
+- [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages**
+
+## Skills
+
+Step-by-step procedural guides for humans and AI agents.
+
+- [001-lint](principles/skills/001-lint/SKILL.md) - **Lint** — review code and files against XDRs
+- [002-write-xdr](principles/skills/002-write-xdr/SKILL.md) - **Write XDR** — create a new Decision Record
+- [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
+- [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
 
 ## Articles
 

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -76,3 +76,4 @@ when referencing an information from those documents.]
 
 - [_core-adr-001 - XDR standards](001-xdr-standards.md)
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
+- [004-write-article skill](skills/004-write-article/SKILL.md) - Step-by-step instructions for creating a new article

package/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md

@@ -0,0 +1,45 @@
+# _core-adr-005: Semantic versioning for XDR packages
+
+## Context and Problem Statement
+
+Teams consume XDR packages as reusable guidance, constraints, skills, and articles. If package versions do not reflect the real impact of a release, upgrades become risky and teams lose trust in reuse.
+
+Question: How should semantic versioning be used when publishing or versioning a package containing XDRs, skills, and articles?
+
+## Decision Outcome
+
+**semantic versioning aligned with decision impact**
+
+XDR packages must use semantic versioning so the package version communicates the expected upgrade impact on consuming teams and projects.
+
+### Implementation Details
+
+- Package versions MUST follow `MAJOR.MINOR.PATCH`.
+- The published package version MUST represent the impact of the package as a whole, not only of a single changed file.
+- If a release contains changes of different severities, the highest-impact change MUST define the version bump.
+- When uncertainty exists between two levels, the safer and more explicit version bump SHOULD be chosen.
+
+**MAJOR**
+- Use a major bump for breaking changes.
+- Use a major bump when an existing XDR changes meaning in a way that can require consuming teams to revisit architecture, governance, operations, or implementation decisions.
+- Use a major bump when impactful concepts are introduced or changed in a way that materially alters how the package should be adopted or interpreted.
+- Typical cases: removed or renamed XDRs that affect references, changed mandatory rules, changed conflict/override behavior, or changed guidance that invalidates previously compliant usage.
+
+**MINOR**
+- Use a minor bump for backward-compatible additions and new capabilities.
+- Use a minor bump for new XDRs that do not break existing guidance.
+- Use a minor bump for new or updated articles and skill changes that extend the package without requiring consumers to undo previous adoption work.
+- Typical cases: new features, new optional guidance, new articles, expanded skills, or additive non-breaking decision coverage.
+
+**PATCH**
+- Use a patch bump for low-risk fixes and simple improvements.
+- Use a patch bump for corrections that preserve the existing meaning and upgrade expectations of the package.
+- Typical cases: typo fixes, broken links, wording clarifications, examples, simple additions, formatting fixes, and small consistency improvements.
+
+- Teams publishing XDR packages SHOULD treat the version number as an upgrade contract.
+- Consumers SHOULD be able to assume that patch upgrades are low risk, minor upgrades are additive, and major upgrades may require review or migration work.
+- Release notes SHOULD explain the reason for the chosen bump, especially for major releases.
+
+## References
+
+- https://semver.org/

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

@@ -0,0 +1,111 @@
+---
+name: 004-write-article
+description: >
+  Creates a new article document following XDR article standards: selects scope, type, subject, and number;
+  then writes a focused synthetic text that combines and links multiple XDRs and Skills around a topic.
+  Activate this skill when the user asks to create, add, or write a new article, guide, or overview document
+  within an XDR project.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Guides the creation of a well-structured article by following `_core-adr-004`, researching the XDRs and
+Skills to synthesize, and producing a concise document that serves as a navigable view without duplicating
+decision content.
+
+## Instructions
+
+### Phase 1: Understand the Article Goal
+
+1. Read `.xdrs/_core/adrs/principles/004-article-standards.md` in full to internalize the template,
+   placement rules, numbering rules, and the constraint that articles are views, not decisions.
+2. Identify the topic and intended audience from user input or context. Do NOT proceed without a clear
+   topic.
+
+### Phase 2: Select Scope, Type, and Subject
+
+**Scope** — use `_local` unless the user explicitly names another scope.
+
+**Type** — match the type of the XDRs the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
+If the topic spans multiple types, use `adrs`.
+
+**Subject** — pick the subject that best matches the article's topic (see `004-article-standards`).
+If the article spans more than one subject, place it in `principles`.
+
+### Phase 3: Assign a Number and Name
+
+1. List `.xdrs/[scope]/[type]/[subject]/articles/` (create the folder if it does not exist).
+2. Find the highest existing article number in that namespace and increment by 1. Never reuse numbers.
+3. Choose a short lowercase kebab-case title that describes the topic clearly.
+   - Good: `onboarding-guide`, `checkout-flow-overview`, `api-design-principles`
+   - Avoid: `summary`, `notes`, `misc`
+
+### Phase 4: Research XDRs and Skills to Synthesize
+
+1. Read all XDRs and Skills relevant to the article topic across all scopes listed in `.xdrs/index.md`.
+2. Identify the key points a reader needs to understand the topic end-to-end.
+3. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
+
+### Phase 5: Write the Article
+
+Use the mandatory template from `004-article-standards`:
+
+```
+# [scope]-article-[number]: [Short Title]
+
+## Overview
+
+[Brief description of what this article covers and its intended audience. Under 3 lines.]
+
+## Content
+
+[Synthetic text combining and explaining the topic. Use links to Decision Records and Skills
+when referencing information from those documents. Keep under 150 lines total.]
+
+## References
+
+- [XDR id or Skill name](relative/path/to/file.md) - Brief description of relevance
+```
+
+Rules to apply while drafting:
+
+- Write for the stated audience; avoid jargon unexplained elsewhere.
+- Every factual claim must link back to the authoritative XDR or Skill.
+- Never reproduce decision text verbatim; summarize and link.
+- Keep the article under 150 lines; 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.
+
+### Phase 6: Place and Register
+
+1. Save the file at `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`.
+2. Add a link to the article in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
+3. Add back-references in the XDRs and Skills that the article synthesizes, under their `## References`
+   section.
+
+## Examples
+
+**Input:** "Write an article about how skills work in this project."
+
+**Expected actions:**
+1. Read `004-article-standards.md`.
+2. Topic: how skills work. Audience: developers new to the project.
+3. Scope: `_local`, type: `adrs`, subject: `principles`.
+4. Scan `.xdrs/_local/adrs/principles/articles/` — no articles exist → number is `001`.
+5. Research `_core-adr-003` and all existing skill SKILL.md files.
+6. Write `.xdrs/_local/adrs/principles/articles/001-skills-overview.md` following the template, linking
+   to `_core-adr-003` and the individual skill files.
+7. Update `.xdrs/_local/adrs/index.md` with a link to the new article.
+8. Add a reference to the article in `_core-adr-003` under `## References`.
+
+## Edge Cases
+
+- **Article vs. XDR confusion** — if the user asks for a document that makes a decision, write an XDR
+  (use the `002-write-xdr` skill), not an article.
+- **Cross-subject topic** — place the article in `principles`, not in any single subject folder.
+- **No existing articles folder** — create it; it is optional in the folder layout.
+- **Conflicting information found** — note the conflict in the article and always defer to the XDR.
+- **Article would exceed 150 lines** — move detailed content to a new Skills or XDR and link back.

package/.xdrs/_local/adrs/index.md

@@ -0,0 +1,11 @@
+# local ADRs Index
+
+This index covers project-local architectural documentation for this repository. These documents
+are not meant to be distributed as reusable scope packages unless they are promoted into a named
+shared scope.
+
+## Articles
+
+Synthetic views combining XDRs, repository examples, and packaging guidance.
+
+- [_local-article-001](principles/articles/001-create-your-own-xdrs-extension-package.md) - **Create your own xdrs-core extension package** (package layout, filedist sets, publishing, versioning, and consumer overrides)

package/.xdrs/_local/adrs/principles/articles/001-create-your-own-xdrs-extension-package.md

@@ -0,0 +1,123 @@
+# _local-article-001: Create your own xdrs-core extension package
+
+## Overview
+
+This article explains how to turn your own XDR scope into a distributable npm package. It is for
+teams that want to publish their own DRs, skills, and articles while staying compatible with the
+xdrs-core structure and extraction flow.
+
+## Content
+
+### Start with a real shared scope, not `_local`
+
+Use `_local` only for project-only records that must stay inside one repository. Shared packages
+should publish a named scope such as `acme-platform` or `team-ml`, because scopes are the unit of
+ownership, distribution, and override ordering in XDRs. The root structure and precedence rules are
+defined in [_core-adr-001](../../../../_core/adrs/principles/001-xdr-standards.md).
+
+### Package the whole scope as a normal npm package
+
+The package shape used by this repository is the simplest reference implementation: the published
+artifact is a regular npm package with a `files` whitelist, a thin CLI entrypoint, and `filedist`
+configuration embedded in [package.json](../../../../../package.json). The important parts are:
+
+- include the shipped XDR tree, agent instruction files, and CLI files in `files`
+- expose `bin/filedist.js` as the package `bin` so consumers run the package through the same
+  `extract` and `check` interface
+- define one `filedist.sets` entry for managed files and another for editable local overrides
+
+For a minimal consumer flow, see [example/package.json](../../../../../example/package.json) and
+[example/Makefile](../../../../../example/Makefile).
+
+### Separate managed files from local overrides
+
+This repository's `filedist` config in [package.json](../../../../../package.json) shows the key
+pattern:
+
+- managed set: ships `AGENTS.md` and `.xdrs/**`, while excluding `.xdrs/index.md`
+- keep-existing set: ships `.xdrs/index.md` and `AGENTS.local.md` with `managed=false` and
+  `keepExisting=true`
+
+That split matters because consumers need some files to stay under package control and others to
+remain editable in their own repository. The current example verifies exactly that behavior by
+re-extracting into [example/output](../../../../../example/output) and asserting that local edits to
+`.xdrs/index.md` survive `extract --keep-existing` while managed files are still checked for drift in
+[example/Makefile](../../../../../example/Makefile).
+
+### Keep DRs, skills, and articles together
+
+Your reusable package should place DRs, skills, and articles under the same scope folder so they
+ship together:
+
+```text
+.xdrs/
+  my-scope/
+    adrs/
+      index.md
+      principles/
+        001-my-decision.md
+        skills/
+          001-my-skill/SKILL.md
+        articles/
+          001-my-overview.md
+```
+
+The co-location rule for skills comes from [_core-adr-003](../../../../_core/adrs/principles/003-skill-standards.md),
+and article placement rules come from [_core-adr-004](../../../../_core/adrs/principles/004-article-standards.md).
+When you publish the scope folder, those documents travel together and stay version-aligned.
+
+### Expose skills to Copilot-compatible tooling
+
+This repository's managed `filedist` set creates symlinks from `.xdrs/**/skills/*` into
+`.github/skills`, configured in [package.json](../../../../../package.json). That means your skills
+remain authored next to the XDRs they implement, but consumers also get the discovery path expected
+by GitHub Copilot and similar tooling.
+
+If your package targets non-Copilot agents too, keep the source of truth in `.xdrs/[scope]/.../skills/`
+and treat `.github/skills` as an exposure mechanism rather than the canonical location.
+
+### Verify with a consumer example before publishing
+
+The [example](../../../../../example) folder is the best reference in this repository for the
+consumer side of the workflow:
+
+1. depend on the locally packed tarball from `dist/`
+2. run `pnpm exec xdrs-core extract --output ./output`
+3. verify the expected files exist
+4. re-run extraction to confirm keep-existing behavior
+5. run `check` and `lint` against the extracted tree
+
+That same pattern should exist in your extension package repository. A runnable example catches bad
+selectors, missing files, broken indexes, and skill exposure problems before you publish.
+
+### Publish and version the package as an upgrade contract
+
+The release flow in [Makefile](../../../../../Makefile) packs the project and publishes it with npm,
+including prerelease tag handling. Your extension package can follow the same shape: `pnpm pack` for
+local verification, then `npm publish` to your public or internal registry.
+
+Version the package with semantic versioning according to the impact on consumers, not only on the
+changed file. [_core-adr-005](../../../../_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md)
+defines the practical rule: breaking guidance or changed mandatory behavior is `MAJOR`, additive
+guidance such as new DRs, skills, or articles is usually `MINOR`, and low-risk corrections are
+`PATCH`.
+
+### Use agentme as the fuller packaged example
+
+This repository shows the baseline xdrs-core packaging model. For a fuller distribution package that
+combines reusable XDR scopes with additional agent workflow files and presets, use
+[flaviostutz/agentme](https://github.com/flaviostutz/agentme) as the reference. Its README shows the
+same extraction model applied to a richer package: install the dependency, run `extract`, review the
+generated output, and re-run `check` when upgrading.
+
+## References
+
+- [_core-adr-001](../../../../_core/adrs/principles/001-xdr-standards.md) - Scope structure, precedence, and distribution model
+- [_core-adr-003](../../../../_core/adrs/principles/003-skill-standards.md) - Skill co-location and discovery rules
+- [_core-adr-004](../../../../_core/adrs/principles/004-article-standards.md) - Article placement and template rules
+- [_core-adr-005](../../../../_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md) - Versioning policy for published XDR packages
+- [package.json](../../../../../package.json) - Reference `files`, `bin`, symlink, and `filedist` set layout
+- [Makefile](../../../../../Makefile) - Reference pack and publish flow
+- [example/package.json](../../../../../example/package.json) - Minimal consumer dependency setup
+- [example/Makefile](../../../../../example/Makefile) - Extraction, keep-existing, check, and lint verification flow
+- [agentme](https://github.com/flaviostutz/agentme) - Full distribution package example built on top of xdrs-core

package/.xdrs/index.md

@@ -21,8 +21,4 @@ Decisions about how XDRs work
 
 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. Add specific `_local` ADR/BDR/EDR index links here when present.
 
-[View _local BDRs Index](_local/bdrs/index.md)
-
-[View _local ADRs Index](_local/adrs/index.md)
-
-[View _local EDRs Index](_local/edrs/index.md)
+[View local ADRs Index](_local/adrs/index.md)

package/README.md

@@ -32,6 +32,36 @@ Every XDR package contains three types of documents:
 
    > Create an ADR about our decision on using Python for AI related projects. For high volume projects (expected >1000 t/s), an exception can be made on using Golang.
 
+## Examples
+
+- [examples/basic-usage](examples/basic-usage) shows the minimal consumer flow for installing the packaged `xdrs-core` tarball, extracting files, checking drift, and linting the resulting tree.
+- [examples/mydevkit](examples/mydevkit) shows a reusable extension package that uses `.filedistrc` as its package config source, composes `xdrs-core`, and ships its own named scope.
+- For a fuller real-world package built on the same distribution model, see [flaviostutz/agentme](https://github.com/flaviostutz/agentme).
+
+## CLI
+
+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 .`.
+
+The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
+
+- allowed scope, type, and subject folder structure
+- XDR numbering uniqueness per `scope/type`
+- skill numbering uniqueness per `scope/type/subject/skills`
+- article numbering uniqueness per `scope/type/subject/articles`
+- canonical index presence and link consistency
+- root index coverage for all discovered canonical indexes
+
+Examples:
+
+```bash
+npx -y xdrs-core lint .
+npx -y xdrs-core lint ./some-project
+pnpm exec xdrs-core lint .
+```
+
 ## Requirements
 
 ### Multi-scope support
@@ -94,6 +124,7 @@ Document types:
 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](.xdrs/_local/adrs/principles/articles/001-create-your-own-xdrs-extension-package.md), then compare [examples/basic-usage](examples/basic-usage) and [examples/mydevkit](examples/mydevkit).
 
 ## Flow: Decision -> Distribution -> Usage
 

package/bin/filedist.js

@@ -1,3 +1,12 @@
 #!/usr/bin/env node
 'use strict';
-require('filedist').binpkg(__dirname, process.argv.slice(2));
+
+const { runLintCli } = require('../lib/lint');
+
+const args = process.argv.slice(2);
+
+if (args[0] === 'lint') {
+	process.exitCode = runLintCli(args.slice(1));
+} else {
+	require('filedist').binpkg(__dirname, args);
+}

package/lib/lint.js

@@ -0,0 +1,462 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const TYPE_TO_ID = {
+  adrs: 'adr',
+  bdrs: 'bdr',
+  edrs: 'edr'
+};
+
+const ALLOWED_SUBJECTS = {
+  adrs: new Set(['principles', 'application', 'data', 'integration', 'platform', 'controls', 'operations']),
+  bdrs: new Set(['principles', 'marketing', 'product', 'controls', 'operations', 'organization', 'finance', 'sustainability']),
+  edrs: new Set(['principles', 'application', 'infra', 'ai', 'observability', 'devops', 'governance'])
+};
+
+const TYPE_NAMES = new Set(Object.keys(TYPE_TO_ID));
+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';
+
+function runLintCli(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return 0;
+  }
+
+  const targetPath = args[0] || '.';
+  const result = lintWorkspace(targetPath);
+
+  if (result.errors.length === 0) {
+    console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
+    return 0;
+  }
+
+  console.error(`Lint failed for ${toDisplayPath(result.xdrsRoot)}`);
+  for (const error of result.errors) {
+    console.error(`- ${error}`);
+  }
+
+  return 1;
+}
+
+function printHelp() {
+  console.log('Usage: xdrs-core lint [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.');
+}
+
+function lintWorkspace(targetPath) {
+  const resolvedTarget = path.resolve(targetPath);
+  const xdrsRoot = path.basename(resolvedTarget) === '.xdrs'
+    ? resolvedTarget
+    : path.join(resolvedTarget, '.xdrs');
+  const errors = [];
+
+  if (!existsDirectory(xdrsRoot)) {
+    errors.push(`Missing XDR root directory: ${toDisplayPath(xdrsRoot)}`);
+    return { xdrsRoot, errors };
+  }
+
+  const actualTypeIndexes = [];
+  const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDR root directory');
+  const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
+
+  for (const entry of rootEntries) {
+    if (entry.isFile() && entry.name !== 'index.md') {
+      errors.push(`Unexpected file at .xdrs root: ${entry.name}`);
+    }
+  }
+
+  for (const scopeEntry of scopeEntries) {
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes);
+  }
+
+  const rootIndexPath = path.join(xdrsRoot, 'index.md');
+  if (!existsFile(rootIndexPath)) {
+    errors.push('Missing required root index: .xdrs/index.md');
+  } else {
+    lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors);
+  }
+
+  return { xdrsRoot, errors };
+}
+
+function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
+  const content = fs.readFileSync(rootIndexPath, 'utf8');
+
+  if (!content.includes(REQUIRED_ROOT_INDEX_TEXT)) {
+    errors.push(`Root index is missing required override text: ${toDisplayPath(rootIndexPath)}`);
+  }
+
+  const localLinks = parseLocalLinks(content, path.dirname(rootIndexPath));
+  for (const linkPath of localLinks) {
+    if (!fs.existsSync(linkPath)) {
+      errors.push(`Broken link in root index: ${displayPath(rootIndexPath, linkPath)}`);
+    }
+  }
+
+  const linkedTypeIndexes = localLinks.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
+  const linkedSet = new Set(linkedTypeIndexes.map(normalizePath));
+
+  for (const indexPath of actualTypeIndexes) {
+    if (!linkedSet.has(normalizePath(indexPath))) {
+      errors.push(`Root index is missing canonical index link: ${toDisplayPath(indexPath)}`);
+    }
+  }
+
+  let seenLocal = false;
+  for (const indexPath of linkedTypeIndexes) {
+    const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
+    if (scopeName === '_local') {
+      seenLocal = true;
+      continue;
+    }
+    if (seenLocal) {
+      errors.push('Root index must keep all _local scope links after every non-_local scope link');
+      break;
+    }
+  }
+}
+
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes) {
+  const scopePath = path.join(xdrsRoot, scopeName);
+
+  if (!isValidScopeName(scopeName)) {
+    errors.push(`Invalid scope name: ${toDisplayPath(scopePath)}`);
+  }
+
+  const entries = safeReadDir(scopePath, errors, `read scope directory ${scopeName}`);
+  for (const entry of entries) {
+    const entryPath = path.join(scopePath, entry.name);
+    if (entry.isDirectory()) {
+      if (!TYPE_NAMES.has(entry.name)) {
+        errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
+        continue;
+      }
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes);
+      continue;
+    }
+
+    errors.push(`Unexpected file under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
+  }
+}
+
+function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes) {
+  const typePath = path.join(xdrsRoot, scopeName, typeName);
+  const indexPath = path.join(typePath, 'index.md');
+  const xdrNumbers = new Map();
+  const artifacts = [];
+
+  if (!existsFile(indexPath)) {
+    errors.push(`Missing canonical index: ${toDisplayPath(indexPath)}`);
+  } else {
+    actualTypeIndexes.push(indexPath);
+  }
+
+  const entries = safeReadDir(typePath, errors, `read type directory ${scopeName}/${typeName}`);
+  for (const entry of entries) {
+    const entryPath = path.join(typePath, entry.name);
+    if (entry.isFile()) {
+      if (entry.name !== 'index.md') {
+        errors.push(`Unexpected file under ${scopeName}/${typeName}: ${toDisplayPath(entryPath)}`);
+      }
+      continue;
+    }
+
+    if (!ALLOWED_SUBJECTS[typeName].has(entry.name)) {
+      errors.push(`Invalid subject folder for ${typeName}: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors));
+  }
+
+  if (existsFile(indexPath)) {
+    lintTypeIndex(indexPath, xdrsRoot, artifacts, errors);
+  }
+}
+
+function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors) {
+  const subjectPath = path.join(xdrsRoot, scopeName, typeName, subjectName);
+  const artifacts = [];
+  const entries = safeReadDir(subjectPath, errors, `read subject directory ${scopeName}/${typeName}/${subjectName}`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(subjectPath, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'skills') {
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        continue;
+      }
+      if (entry.name === 'articles') {
+        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
+        continue;
+      }
+
+      errors.push(`Unexpected directory under ${scopeName}/${typeName}/${subjectName}: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    if (!NUMBERED_FILE_RE.test(entry.name)) {
+      errors.push(`Invalid XDR file name: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    artifacts.push(entryPath);
+    lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors);
+  }
+
+  return artifacts;
+}
+
+function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors) {
+  const baseName = path.basename(filePath);
+  const match = baseName.match(NUMBERED_FILE_RE);
+  if (!match) {
+    return;
+  }
+
+  const number = match[1];
+  const previous = xdrNumbers.get(number);
+  if (previous) {
+    errors.push(`Duplicate XDR number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
+  } else {
+    xdrNumbers.set(number, filePath);
+  }
+
+  if (baseName !== baseName.toLowerCase()) {
+    errors.push(`XDR file name must be lowercase: ${toDisplayPath(filePath)}`);
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const expectedHeader = `# ${scopeName}-${TYPE_TO_ID[typeName]}-${number}:`;
+  const firstLine = firstNonEmptyLine(content);
+  if (!firstLine.startsWith(expectedHeader)) {
+    errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
+  }
+}
+
+function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors) {
+  const artifacts = [];
+  const skillNumbers = new Map();
+  const entries = safeReadDir(skillsPath, errors, `read skills directory ${scopeName}/${typeName}/${subjectName}/skills`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(skillsPath, entry.name);
+    if (!entry.isDirectory()) {
+      errors.push(`Unexpected file in skills directory: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const match = entry.name.match(NUMBERED_DIR_RE);
+    if (!match) {
+      errors.push(`Invalid skill package name: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const number = match[1];
+    const previous = skillNumbers.get(number);
+    if (previous) {
+      errors.push(`Duplicate skill number ${number} in ${scopeName}/${typeName}/${subjectName}/skills: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)}`);
+    } else {
+      skillNumbers.set(number, entryPath);
+    }
+
+    if (entry.name !== entry.name.toLowerCase()) {
+      errors.push(`Skill package name must be lowercase: ${toDisplayPath(entryPath)}`);
+    }
+
+    const skillFilePath = path.join(entryPath, 'SKILL.md');
+    artifacts.push(skillFilePath);
+
+    if (!existsFile(skillFilePath)) {
+      errors.push(`Missing SKILL.md in skill package: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const skillContent = fs.readFileSync(skillFilePath, 'utf8');
+    const frontmatterName = extractFrontmatterName(skillContent);
+    if (!frontmatterName) {
+      errors.push(`SKILL.md is missing a frontmatter name field: ${toDisplayPath(skillFilePath)}`);
+    } else if (frontmatterName !== entry.name) {
+      errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+    }
+  }
+
+  return artifacts;
+}
+
+function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors) {
+  const artifacts = [];
+  const articleNumbers = new Map();
+  const entries = safeReadDir(articlesPath, errors, `read articles directory ${scopeName}/${typeName}/${subjectName}/articles`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(articlesPath, entry.name);
+    if (!entry.isFile()) {
+      errors.push(`Unexpected directory in articles folder: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    const match = entry.name.match(NUMBERED_FILE_RE);
+    if (!match) {
+      errors.push(`Invalid article file name: ${toDisplayPath(entryPath)}`);
+      continue;
+    }
+
+    artifacts.push(entryPath);
+
+    const number = match[1];
+    const previous = articleNumbers.get(number);
+    if (previous) {
+      errors.push(`Duplicate article number ${number} in ${scopeName}/${typeName}/${subjectName}/articles: ${toDisplayPath(previous)} and ${toDisplayPath(entryPath)}`);
+    } else {
+      articleNumbers.set(number, entryPath);
+    }
+
+    if (entry.name !== entry.name.toLowerCase()) {
+      errors.push(`Article file name must be lowercase: ${toDisplayPath(entryPath)}`);
+    }
+
+    const content = fs.readFileSync(entryPath, 'utf8');
+    const expectedHeader = `# ${scopeName}-article-${number}:`;
+    const firstLine = firstNonEmptyLine(content);
+    if (!firstLine.startsWith(expectedHeader)) {
+      errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
+    }
+  }
+
+  return artifacts;
+}
+
+function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
+  const content = fs.readFileSync(indexPath, 'utf8');
+  const localLinks = parseLocalLinks(content, path.dirname(indexPath));
+  const linkedSet = new Set();
+
+  for (const linkPath of localLinks) {
+    if (!fs.existsSync(linkPath)) {
+      errors.push(`Broken link in canonical index ${toDisplayPath(indexPath)}: ${displayPath(indexPath, linkPath)}`);
+      continue;
+    }
+
+    linkedSet.add(normalizePath(linkPath));
+  }
+
+  for (const artifactPath of artifacts) {
+    if (!linkedSet.has(normalizePath(artifactPath))) {
+      errors.push(`Canonical index ${toDisplayPath(indexPath)} is missing an entry for ${toDisplayPath(artifactPath)}`);
+    }
+  }
+}
+
+function parseLocalLinks(markdown, baseDir) {
+  const links = [];
+  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));
+    }
+    match = linkRe.exec(markdown);
+  }
+  return links;
+}
+
+function isLocalLink(target) {
+  return target !== ''
+    && !target.startsWith('#')
+    && !target.startsWith('http://')
+    && !target.startsWith('https://')
+    && !target.startsWith('mailto:');
+}
+
+function isCanonicalTypeIndex(filePath, xdrsRoot) {
+  const relative = relativeFrom(xdrsRoot, filePath).split(path.sep);
+  return relative.length === 3 && TYPE_NAMES.has(relative[1]) && relative[2] === 'index.md';
+}
+
+function extractFrontmatterName(content) {
+  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!frontmatterMatch) {
+    return null;
+  }
+
+  const nameMatch = frontmatterMatch[1].match(/^name:\s*(.+)$/m);
+  return nameMatch ? nameMatch[1].trim() : null;
+}
+
+function firstNonEmptyLine(content) {
+  const lines = content.split(/\r?\n/);
+  for (const line of lines) {
+    if (line.trim() !== '') {
+      return line.trim();
+    }
+  }
+  return '';
+}
+
+function safeReadDir(dirPath, errors, operation) {
+  try {
+    return fs.readdirSync(dirPath, { withFileTypes: true });
+  } catch (error) {
+    errors.push(`Failed to ${operation}: ${toDisplayPath(dirPath)} (${error.message})`);
+    return [];
+  }
+}
+
+function isValidScopeName(scopeName) {
+  if (RESERVED_SCOPES.has(scopeName)) {
+    return true;
+  }
+  return /^[a-z0-9][a-z0-9-]*$/.test(scopeName);
+}
+
+function existsDirectory(dirPath) {
+  try {
+    return fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function existsFile(filePath) {
+  try {
+    return fs.statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function displayPath(indexPath, targetPath) {
+  return `${toDisplayPath(indexPath)} -> ${toDisplayPath(targetPath)}`;
+}
+
+function toDisplayPath(targetPath) {
+  return relativeFrom(process.cwd(), targetPath);
+}
+
+function relativeFrom(basePath, targetPath) {
+  return path.relative(basePath, targetPath) || '.';
+}
+
+function normalizePath(filePath) {
+  return path.normalize(filePath);
+}
+
+module.exports = {
+  runLintCli,
+  lintWorkspace
+};
+
+if (require.main === module) {
+  process.exitCode = runLintCli(process.argv.slice(2));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.5.0",
+  "version": "0.7.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",
@@ -18,10 +18,11 @@
     "package.json",
     "AGENTS.md",
     "AGENTS.local.md",
-    "bin/filedist.js"
+    "bin/filedist.js",
+    "lib/**/*.js"
   ],
   "dependencies": {
-    "filedist": "^0.24.0"
+    "filedist": "^0.26.0"
   },
   "filedist": {
     "sets": [