xdrs-core 0.19.0 → 0.20.0

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

@@ -36,7 +36,7 @@ Collectively, these are referred to as XDRs.
 - ALWAYS use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
-- **Readonly files are external XDRs.** A file with read-only permissions (e.g., `444` set by a distribution tool such as filedist) was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package.
+- **Files listed in `.filedist` are external XDRs.** A file whose path appears in the workspace root `.filedist` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist`, and tools (such as `xdrs-core lint`) will skip external scopes by default.
 - Optional supporting artifacts under the same subject:
   - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
@@ -109,14 +109,22 @@ Collectively, these are referred to as XDRs.
 - Never use emojis
 - **Links:** Links that reference a parent folder MUST use absolute paths from the repository root with a leading `/` (e.g., `/.xdrs/_core/adrs/principles/001-xdrs-core.md`). Sibling files and child folder references SHOULD use relative paths (e.g., `002-other-doc.md`, `.assets/image.png`, `subdir/file.md`). Never use relative paths that traverse up the directory tree (e.g., `../../.assets/test.png`, `../other.md`); they break when files are moved and are harder to read.
 - **Indexes**
-  - Keep a canonical index with all XDRs of a certain type+scope in `.xdrs/[scope]/[type]/index.md`
+  - Every document in the collection (XDRs, skills, articles, research, and plans) must be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and must be added to the index or removed.
+  - Keep a canonical type index with all documents of a certain type+scope in `.xdrs/[scope]/[type]/index.md`. The type index must link to every XDR, skill, article, research, and plan under that type+scope.
   - Canonical index requirements:
     - Organize XDR documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRs in scopes listed last override XDRs in scopes listed first when addressing the same topic.
     - Each XDR element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
-  - Outside the scopes, keep an index pointing to all canonical indexes in `.xdrs/index.md`. Add the text "XDRs in scopes listed last override the ones listed first"
+  - Outside the scopes, keep a root index in `.xdrs/index.md` that links to each scope index (`.xdrs/[scope]/index.md`). Add the text "XDRs in scopes listed last override the ones listed first". The root index must not link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
   - Always verify if indexes are up to date after making changes
+- **Scope index**
+  - Each scope folder must maintain an `index.md` file at `.xdrs/[scope]/index.md`.
+  - The scope index is a short article (under 1000 words) that provides an overview of all XDR contents within that scope. Follow article standards (`_core-adr-004`) when writing this file.
+  - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful for them before diving into the specific documents. Write a guided summary that helps them decide whether to explore further.
+  - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
+  - At the end of the scope index, always add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
+  - Whenever the contents of a scope change (new XDRs, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
 
 **Folder structure examples:**
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`

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

@@ -35,6 +35,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick one from the allowed list for the chosen type (from `001-xdrs-core`):
 - ADR: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -167,6 +168,7 @@ If any check fails, revise and re-run this phase before proceeding.
 3. Add or verify the scope entry in `.xdrs/index.md`.
 4. If significant research was produced or already exists, link it from the XDR `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Implementation Details` without turning the XDR into a long procedure.
+6. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Phase 9: Verify Package structure with Lint
 
@@ -185,6 +187,7 @@ If any check fails, revise and re-run this phase before proceeding.
 - MUST NOT create an XDR that duplicates a decision already captured in another XDR — extend or reference instead.
 - MUST prefer links and short references over repeating the same decision content across related documents.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 
 ## References
 

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

@@ -36,6 +36,7 @@ Quick test:
 - "How to execute a business process or policy?" → BDR
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Subject** — pick the most specific match for the chosen type (required list per type is in `_core-adr-001`):
 - ADR subjects: `principles`, `application`, `data`, `integration`, `platform`, `controls`, `operations`
@@ -122,6 +123,7 @@ If any check fails, revise before continuing.
    mkdir -p .github/skills/[number]-[skill-name]
    ln -s ../../.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name] .github/skills/[number]-[skill-name]
    ```
+3. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new skill. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Constraints
 
@@ -129,6 +131,7 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST NOT create a skill that duplicates an existing one — extend or reference it instead.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST include a References section linking to `003-skill-standards`.
 
 ## Examples

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

@@ -41,6 +41,7 @@ Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audi
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRs the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
 If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-xdr` Phase 2:
@@ -106,6 +107,7 @@ Rules to apply while drafting:
 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, Research documents, and Skills that the article synthesizes, under their `## References`
    section.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new article. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ## Examples
 
@@ -136,6 +138,7 @@ Rules to apply while drafting:
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the article template and placement rules from `004-article-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST defer to active and applicable XDRs when article synthesis conflicts with them.
 
 ## References

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

@@ -36,6 +36,7 @@ If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-xdr` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -244,6 +245,7 @@ If any check fails, revise before continuing.
 1. Create the research file at `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`.
 2. Add an entry to `.xdrs/[scope]/[type]/index.md`.
 3. Add back-references from the related XDR, article, or skill when the relationship is important for discovery.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new research. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ## Examples
 
@@ -276,4 +278,5 @@ If any check fails, revise before continuing.
 - MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
 - MUST follow the research template and section-goal rules from `006-research-standards`.
 - MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).
 - MUST keep the document as research rather than turning it into a final decision.

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

@@ -33,6 +33,7 @@ Guides the creation of a well-structured plan document by following `_core-adr-0
 Consult `001-xdrs-core` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
 **Scope** — use `_local` unless the user explicitly names another scope.
+- If the user names a scope other than `_local`, check the workspace root `.filedist` file. If any file under `.xdrs/[scope]/` appears in `.filedist`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
 
 **Type** — match the type of the XDRs the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -123,6 +124,7 @@ Rules to apply while drafting:
 1. Save the file at `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`.
 2. Add a link to the plan in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
 3. Add back-references in the XDRs, Research documents, and Skills that the plan relates to, under their `## References` section.
+4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new plan. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-001`.
 
 ### Phase 7: Verify with Lint
 
@@ -156,3 +158,10 @@ Rules to apply while drafting:
 - [_core-adr-001 - XDRs core](/.xdrs/_core/adrs/principles/001-xdrs-core.md)
 - [_core-adr-007 - Plan standards](/.xdrs/_core/adrs/principles/007-plan-standards.md)
 - [_core-adr-002 - XDR standards](/.xdrs/_core/adrs/principles/002-xdr-standards.md)
+
+## Constraints
+
+- MUST follow the plan template and section-goal rules from `007-plan-standards`.
+- MUST consult `001-xdrs-core` as the canonical source for every core element definition, especially type, scope, subject, numbering, naming, and placement.
+- MUST keep scope `_local` unless the user explicitly states otherwise.
+- MUST NOT create documents in external scopes (scopes whose files appear in the workspace root `.filedist`).

package/.xdrs/_core/index.md

@@ -0,0 +1,56 @@
+# _core Scope Overview
+
+## Overview
+
+The `_core` scope defines the XDR framework itself: how decision records, skills, research, articles, and plans are structured, written, versioned, and discovered. This scope is aimed at engineers, architects, and business analysts who build or consume XDR-based documentation.
+
+## Content
+
+### What this scope covers
+
+The `_core` scope is the foundation that all other scopes inherit from. It establishes the rules and conventions that every XDR document, skill, article, research, and plan must follow regardless of which team, product, or domain produces them.
+
+If you are evaluating whether to adopt XDRs, setting up a new XDR project, or extending the framework with your own scopes, start here.
+
+### Framework structure and organization
+
+The core architectural decision [_core-adr-001](adrs/principles/001-xdrs-core.md) defines the fundamental building blocks: three decision types (ADR for architecture, BDR for business, EDR for engineering), scopes as grouping boundaries, subjects as topic categories within each type, and a folder layout that keeps everything discoverable. It also defines the index system (canonical type indexes, scope indexes, and the root index) that ties the collection together.
+
+### Document writing standards
+
+Each artifact type has its own writing standard:
+
+- **XDR documents** follow [_core-adr-002](adrs/principles/002-xdr-standards.md), which defines the mandatory template, frontmatter metadata, applicability rules, conflict handling, and word limits that keep decisions concise and authoritative.
+- **Structured XDRs** with individually referenceable rules follow the extension [_core-adr-008](adrs/principles/008-xdr-standards-structured.md), adding numbered rule blocks and a dot-notation citation syntax.
+- **Skills** follow [_core-adr-003](adrs/principles/003-skill-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
+- **Articles** follow [_core-adr-004](adrs/principles/004-article-standards.md), providing synthetic views that combine and link multiple XDRs, research, and skills without replacing them as the source of truth.
+- **Research** follows [_core-adr-006](adrs/principles/006-research-standards.md), using an IMRAD-based structure for studies that back decisions with reproducible evidence.
+- **Plans** follow [_core-adr-007](adrs/principles/007-plan-standards.md), capturing ephemeral execution plans with problem context, proposed solutions, milestones, and deliverables that are deleted after implementation.
+
+### Versioning and distribution
+
+[_core-adr-005](adrs/principles/005-semantic-versioning-for-xdr-packages.md) defines how XDR packages use semantic versioning to communicate upgrade impact when decisions are shared across repositories or teams.
+
+### Usage policy
+
+The business decision [_core-bdr-001](bdrs/principles/001-xdr-decisions-and-skills-usage.md) establishes how agents and humans must use XDR decisions and skills, separating policy authority (which lives in XDRs) from execution guidance (which lives in skills).
+
+### Available skills
+
+The `_core` scope ships with six skills that automate the most common framework operations:
+
+- **001-lint** reviews code and files against applicable XDRs
+- **002-write-xdr** guides creation of a new decision record
+- **003-write-skill** guides creation of a new skill package
+- **004-write-article** guides creation of a new article
+- **005-write-research** guides creation of a new research document
+- **006-write-plan** guides creation of a new execution plan
+
+### Getting started
+
+For a narrative introduction to the framework, including how elements differ, how to decide whether an XDR applies, and how to extend the framework with your own scopes, see the overview article [_core-article-001](adrs/principles/articles/001-xdrs-overview.md).
+
+## Type Indexes
+
+- [ADRs Index](adrs/index.md) - Architectural decisions about the XDR framework structure and standards
+- [BDRs Index](bdrs/index.md) - Business and operational decisions about framework usage policy

package/.xdrs/index.md

@@ -9,8 +9,7 @@ XDRs in scopes listed last override the ones listed first
 ### _core
 
 Decisions about how XDRs work
-[View _core ADRs Index](_core/adrs/index.md)
-[View _core BDRs Index](_core/bdrs/index.md)
+[View scope _core](_core/index.md)
 
 ---
 

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 .`. By default, read-only files distributed from external scopes are skipped; use `--all` to include them.
+- Lint an XDR tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist` file are treated as external and skipped; use `--all` to include them.
 
 The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
 

package/lib/lint.js

@@ -34,7 +34,7 @@ function runLintCli(args) {
   const all = args.includes('--all');
   const pathArgs = args.filter((a) => !a.startsWith('--'));
   const targetPath = pathArgs[0] || '.';
-  const result = lintWorkspace(targetPath, { ignoreReadOnly: !all });
+  const result = lintWorkspace(targetPath, { ignoreExternal: !all });
 
   if (result.errors.length === 0) {
     console.log(`Lint passed for ${toDisplayPath(result.xdrsRoot)}`);
@@ -53,12 +53,12 @@ function printHelp() {
   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('\nOptions:');
-  console.log('  --all    Check all files, including read-only files from other scopes (default: skip read-only files)');
+  console.log('  --all    Check all files, including files from external scopes distributed via .filedist (default: skip external scopes)');
   console.log('\nAll other commands continue to be delegated to the bundled filedist CLI.');
 }
 
 function lintWorkspace(targetPath, options = {}) {
-  const { ignoreReadOnly = true } = options;
+  const { ignoreExternal = true } = options;
   const resolvedTarget = path.resolve(targetPath);
   const xdrsRoot = path.basename(resolvedTarget) === '.xdrs'
     ? resolvedTarget
@@ -70,6 +70,10 @@ function lintWorkspace(targetPath, options = {}) {
     return { xdrsRoot, errors };
   }
 
+  const repoRoot = path.dirname(xdrsRoot);
+  const filedistPaths = loadFiledist(repoRoot);
+  const externalScopes = getExternalScopes(filedistPaths, xdrsRoot);
+
   const actualTypeIndexes = [];
   const rootEntries = safeReadDir(xdrsRoot, errors, 'read XDR root directory');
   const scopeEntries = rootEntries.filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'));
@@ -81,7 +85,7 @@ function lintWorkspace(targetPath, options = {}) {
   }
 
   for (const scopeEntry of scopeEntries) {
-    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreReadOnly);
+    lintScopeDirectory(xdrsRoot, scopeEntry.name, errors, actualTypeIndexes, ignoreExternal, externalScopes);
   }
 
   const rootIndexPath = path.join(xdrsRoot, 'index.md');
@@ -109,8 +113,8 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
     }
   }
 
-  const linkedTypeIndexes = links.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
-  const linkedSet = new Set(linkedTypeIndexes.map(normalizePath));
+  const linkedScopeIndexes = links.filter((linkPath) => isScopeIndex(linkPath, xdrsRoot));
+  const linkedSet = new Set(linkedScopeIndexes.map(normalizePath));
   const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (const linkPath of links) {
@@ -119,21 +123,46 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
     }
   }
 
+  // Collect non-_local scopes that have type indexes and check their scope index is linked
+  const scopesWithTypeIndexes = new Set();
   for (const indexPath of actualTypeIndexes) {
     const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
-    if (scopeName === '_local') {
-      continue;
+    if (scopeName !== '_local') {
+      scopesWithTypeIndexes.add(scopeName);
+    }
+  }
+
+  for (const scopeName of scopesWithTypeIndexes) {
+    const scopeIndexPath = normalizePath(path.join(xdrsRoot, scopeName, 'index.md'));
+    if (!linkedSet.has(scopeIndexPath)) {
+      errors.push(`Root index is missing scope index link: ${toDisplayPath(path.join(xdrsRoot, scopeName, 'index.md'))}`);
+    }
+  }
+}
+
+function lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors) {
+  const content = fs.readFileSync(scopeIndexPath, 'utf8');
+  const repoRoot = path.dirname(xdrsRoot);
+  const links = parseLocalLinks(content, path.dirname(scopeIndexPath), repoRoot);
+  const linkedSet = new Set(links.map(normalizePath));
+
+  for (const linkPath of links) {
+    if (!fs.existsSync(linkPath)) {
+      errors.push(`Broken link in scope index: ${displayPath(scopeIndexPath, linkPath)}`);
     }
-    if (!linkedSet.has(normalizePath(indexPath))) {
-      errors.push(`Root index is missing canonical index link: ${toDisplayPath(indexPath)}`);
+  }
+
+  for (const typeIndexPath of typeIndexesInScope) {
+    if (!linkedSet.has(normalizePath(typeIndexPath))) {
+      errors.push(`Scope index ${toDisplayPath(scopeIndexPath)} is missing link to type index: ${toDisplayPath(typeIndexPath)}`);
     }
   }
 }
 
-function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreReadOnly) {
+function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, ignoreExternal, externalScopes) {
   const scopePath = path.join(xdrsRoot, scopeName);
 
-  if (ignoreReadOnly && isReadOnly(scopePath)) {
+  if (ignoreExternal && externalScopes.has(scopeName)) {
     return;
   }
 
@@ -141,6 +170,7 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
     errors.push(`Invalid scope name: ${toDisplayPath(scopePath)}`);
   }
 
+  const typeIndexesInScope = [];
   const entries = safeReadDir(scopePath, errors, `read scope directory ${scopeName}`);
   for (const entry of entries) {
     const entryPath = path.join(scopePath, entry.name);
@@ -149,15 +179,30 @@ function lintScopeDirectory(xdrsRoot, scopeName, errors, actualTypeIndexes, igno
         errors.push(`Unexpected directory under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
         continue;
       }
-      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes, ignoreReadOnly);
+      lintTypeDirectory(xdrsRoot, scopeName, entry.name, errors, actualTypeIndexes);
+      const typeIndexPath = path.join(entryPath, 'index.md');
+      if (existsFile(typeIndexPath)) {
+        typeIndexesInScope.push(typeIndexPath);
+      }
+      continue;
+    }
+
+    if (entry.name === 'index.md') {
       continue;
     }
 
     errors.push(`Unexpected file under scope ${scopeName}: ${toDisplayPath(entryPath)}`);
   }
+
+  const scopeIndexPath = path.join(scopePath, 'index.md');
+  if (!existsFile(scopeIndexPath)) {
+    errors.push(`Missing required scope index: ${toDisplayPath(scopeIndexPath)}`);
+  } else {
+    lintScopeIndex(scopeIndexPath, xdrsRoot, scopeName, typeIndexesInScope, errors);
+  }
 }
 
-function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeIndexes, ignoreReadOnly) {
+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();
@@ -165,7 +210,7 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
 
   if (!existsFile(indexPath)) {
     errors.push(`Missing canonical index: ${toDisplayPath(indexPath)}`);
-  } else if (!shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
+  } else {
     actualTypeIndexes.push(indexPath);
   }
 
@@ -184,15 +229,15 @@ function lintTypeDirectory(xdrsRoot, scopeName, typeName, errors, actualTypeInde
       continue;
     }
 
-    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors, ignoreReadOnly));
+    artifacts.push(...lintSubjectDirectory(xdrsRoot, scopeName, typeName, entry.name, xdrNumbers, errors));
   }
 
-  if (existsFile(indexPath) && !shouldSkipReadOnlyPath(indexPath, ignoreReadOnly)) {
+  if (existsFile(indexPath)) {
     lintTypeIndex(indexPath, xdrsRoot, artifacts, errors);
   }
 }
 
-function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNumbers, errors, ignoreReadOnly) {
+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}`);
@@ -205,19 +250,19 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
         continue;
       }
       if (entry.name === 'skills') {
-        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'articles') {
-        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'researches') {
-        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
       if (entry.name === 'plans') {
-        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors, ignoreReadOnly));
+        artifacts.push(...lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, entryPath, errors));
         continue;
       }
 
@@ -230,14 +275,14 @@ function lintSubjectDirectory(xdrsRoot, scopeName, typeName, subjectName, xdrNum
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
     lintXdrFile(xdrsRoot, scopeName, typeName, entryPath, xdrNumbers, errors);
   }
 
+  const subjectAssetsDir = path.join(subjectPath, RESOURCE_DIR_NAME);
+  const xdrDocsInSubject = artifacts.filter((p) => path.dirname(p) === subjectPath);
+  lintOrphanAssets(subjectAssetsDir, xdrDocsInSubject, xdrsRoot, errors);
+
   return artifacts;
 }
 
@@ -327,7 +372,7 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
 }
 
-function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsPath, errors, ignoreReadOnly) {
+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`);
@@ -364,10 +409,6 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(skillFilePath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(skillFilePath);
 
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
@@ -386,12 +427,13 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors);
+    lintOrphanAssets(path.join(entryPath, RESOURCE_DIR_NAME), [skillFilePath], xdrsRoot, errors);
   }
 
   return artifacts;
 }
 
-function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, articlesPath, errors, ignoreReadOnly) {
+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`);
@@ -413,10 +455,6 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -441,10 +479,12 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(articlesPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
-function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, researchPath, errors, ignoreReadOnly) {
+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`);
@@ -466,10 +506,6 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -494,10 +530,12 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(researchPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
-function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors, ignoreReadOnly) {
+function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPath, errors) {
   const artifacts = [];
   const planNumbers = new Map();
   const entries = safeReadDir(plansPath, errors, `read plans directory ${scopeName}/${typeName}/${subjectName}/plans`);
@@ -519,10 +557,6 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
       continue;
     }
 
-    if (shouldSkipReadOnlyPath(entryPath, ignoreReadOnly)) {
-      continue;
-    }
-
     artifacts.push(entryPath);
 
     const number = match[1];
@@ -548,6 +582,8 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
+  lintOrphanAssets(path.join(plansPath, RESOURCE_DIR_NAME), artifacts, xdrsRoot, errors);
+
   return artifacts;
 }
 
@@ -599,6 +635,46 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
+function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
+  if (!existsDirectory(assetsDir)) {
+    return;
+  }
+
+  const entries = safeReadDir(assetsDir, errors, `read assets directory ${toDisplayPath(assetsDir)}`);
+  if (entries.length === 0) {
+    return;
+  }
+
+  const assetFiles = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => normalizePath(path.join(assetsDir, entry.name)));
+
+  if (assetFiles.length === 0) {
+    return;
+  }
+
+  const repoRoot = path.dirname(xdrsRoot);
+  const referencedAssets = new Set();
+
+  for (const docPath of documentPaths) {
+    if (!existsFile(docPath)) {
+      continue;
+    }
+    const content = fs.readFileSync(docPath, 'utf8');
+    const docDir = path.dirname(docPath);
+    const links = parseLocalLinks(content, docDir, repoRoot);
+    for (const linkPath of links) {
+      referencedAssets.add(normalizePath(linkPath));
+    }
+  }
+
+  for (const assetPath of assetFiles) {
+    if (!referencedAssets.has(assetPath)) {
+      errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)}`);
+    }
+  }
+}
+
 function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors) {
   const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
   const ignoredLines = findIgnoredMarkdownLines(lines);
@@ -693,6 +769,11 @@ function isCanonicalTypeIndex(filePath, xdrsRoot) {
   return relative.length === 3 && TYPE_NAMES.has(relative[1]) && relative[2] === 'index.md';
 }
 
+function isScopeIndex(filePath, xdrsRoot) {
+  const relative = relativeFrom(xdrsRoot, filePath).split(path.sep);
+  return relative.length === 2 && relative[1] === 'index.md';
+}
+
 function shouldValidateResourceLink(rawTarget) {
   const normalizedTargetPath = normalizeLocalLinkTarget(rawTarget);
   if (!normalizedTargetPath) {
@@ -857,17 +938,38 @@ function existsFile(filePath) {
   }
 }
 
-function isReadOnly(filePath) {
-  try {
-    fs.accessSync(filePath, fs.constants.W_OK);
-    return false;
-  } catch {
-    return true;
+function loadFiledist(repoRoot) {
+  const filedistPath = path.join(repoRoot, '.filedist');
+  if (!existsFile(filedistPath)) {
+    return new Set();
   }
+  const content = fs.readFileSync(filedistPath, 'utf8');
+  const paths = new Set();
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      continue;
+    }
+    const parts = trimmed.split('|');
+    if (parts.length >= 2) {
+      paths.add(normalizePath(path.join(repoRoot, parts[0])));
+    }
+  }
+  return paths;
 }
 
-function shouldSkipReadOnlyPath(filePath, ignoreReadOnly) {
-  return ignoreReadOnly && isReadOnly(filePath);
+function getExternalScopes(filedistPaths, xdrsRoot) {
+  const externalScopes = new Set();
+  for (const filePath of filedistPaths) {
+    const relative = path.relative(xdrsRoot, filePath);
+    if (!relative.startsWith('..') && !path.isAbsolute(relative)) {
+      const parts = relative.split(path.sep);
+      if (parts.length >= 1 && parts[0]) {
+        externalScopes.add(parts[0]);
+      }
+    }
+  }
+  return externalScopes;
 }
 
 function displayPath(indexPath, targetPath) {

package/lib/lint.test.js

@@ -64,24 +64,92 @@ test('reports broken local document links in skill files', () => {
   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).'),
+test('skips external scopes by default and checks them when ignoreExternal is false', () => {
+  const workspaceRoot = createWorkspace('external-default-skip', {
+    '.xdrs/index.md': rootIndex(['[extscope](extscope/index.md)']),
+    '.xdrs/extscope/index.md': '# extscope Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/extscope/adrs/index.md': [
+      '# extscope ADR Index',
+      '',
+      'Test.',
+      '',
+      '## principles',
+      '',
+      '- [001-ext](principles/001-ext.md) - Ext decision',
+      ''
+    ].join('\n'),
+    '.xdrs/extscope/adrs/principles/001-ext.md': [
+      '---',
+      'name: extscope-adr-001-ext',
+      'description: External test XDR document',
+      '---',
+      '',
+      '# extscope-adr-001: Ext decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See [Missing](002-missing.md).',
+      ''
+    ].join('\n'),
+    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
   });
-  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 });
+  const allResult = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
   expect(defaultResult.errors.join('\n')).not.toContain('Broken local link in');
   expect(allResult.errors.join('\n')).toContain('Broken local link in');
 });
 
+test('skips entire external scope when only some of its files are in filedist', () => {
+  const workspaceRoot = createWorkspace('external-scope-partial-filedist', {
+    '.xdrs/index.md': rootIndex(['[extscope](extscope/index.md)']),
+    '.xdrs/extscope/index.md': '# extscope Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/extscope/adrs/index.md': [
+      '# extscope ADR Index',
+      '',
+      'Test.',
+      '',
+      '## principles',
+      '',
+      '- [001-ext](principles/001-ext.md) - Ext decision',
+      '- [002-local](principles/002-local.md) - Local decision',
+      ''
+    ].join('\n'),
+    '.xdrs/extscope/adrs/principles/001-ext.md': [
+      '---',
+      'name: extscope-adr-001-ext',
+      'description: External test XDR document',
+      '---',
+      '',
+      '# extscope-adr-001: Ext decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'External body.',
+      ''
+    ].join('\n'),
+    '.xdrs/extscope/adrs/principles/002-local.md': [
+      '---',
+      'name: extscope-adr-002-local',
+      'description: Second XDR in external scope',
+      '---',
+      '',
+      '# extscope-adr-002: Local decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See [Missing](003-missing.md).',
+      ''
+    ].join('\n'),
+    '.filedist': '.xdrs/extscope/adrs/principles/001-ext.md|some-package|1.0.0\n',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.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(),
@@ -103,18 +171,19 @@ test('derives expected frontmatter name from the markdown heading title', () =>
     ].join('\n'),
   });
 
-  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: 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/index.md': rootIndex(['[myteam](myteam/index.md)']),
     '.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/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -123,7 +192,7 @@ test('reports non-_local XDR linking to _local scope document', () => {
     ),
   });
 
-  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
   expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
 });
@@ -163,7 +232,7 @@ test('allows _local XDR linking to another _local scope document', () => {
     ].join('\n'),
   });
 
-  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: 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');
@@ -171,18 +240,19 @@ test('allows _local XDR linking to another _local scope document', () => {
 
 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/index.md': rootIndex(['[myteam](myteam/index.md)']),
     '.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/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.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 });
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
   expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
 });
@@ -273,11 +343,12 @@ test('reports absolute path link that is broken', () => {
 
 test('reports non-_local XDR linking to _local scope via absolute path', () => {
   const workspaceRoot = createWorkspace('abs-non-local-links-to-local', {
-    '.xdrs/index.md': rootIndex(),
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
     '.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/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
     '.xdrs/myteam/adrs/index.md': teamAdrIndex([
       '- [001-team](principles/001-team.md) - Team decision'
     ]),
@@ -286,11 +357,145 @@ test('reports non-_local XDR linking to _local scope via absolute path', () => {
     ),
   });
 
-  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
 
   expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
 });
 
+test('allows index.md at scope level', () => {
+  const workspaceRoot = createWorkspace('scope-index-allowed', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview of local scope.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Test body.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Unexpected file under scope');
+});
+
+test('reports scope index missing link to type index', () => {
+  const workspaceRoot = createWorkspace('scope-index-missing-type-link', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\nNo type links here.\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Scope index');
+  expect(result.errors.join('\n')).toContain('is missing link to type index');
+  expect(result.errors.join('\n')).toContain('adrs/index.md');
+});
+
+test('passes when scope index links to all type indexes', () => {
+  const workspaceRoot = createWorkspace('scope-index-links-all-types', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).not.toContain('is missing link to type index');
+});
+
+test('reports broken link in scope index', () => {
+  const workspaceRoot = createWorkspace('scope-index-broken-link', {
+    '.xdrs/index.md': rootIndex(['[myteam](myteam/index.md)']),
+    '.xdrs/myteam/index.md': '# myteam Scope Overview\n\n[ADRs](adrs/index.md)\n[Missing](missing/index.md)\n',
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreExternal: false });
+
+  expect(result.errors.join('\n')).toContain('Broken link in scope index');
+  expect(result.errors.join('\n')).toContain('missing/index.md');
+});
+
+test('reports missing scope index', () => {
+  const workspaceRoot = createWorkspace('missing-scope-index', {
+    '.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('Test body.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Missing required scope index');
+  expect(result.errors.join('\n')).toContain('_local/index.md');
+});
+
+test('reports orphan asset files not referenced by any document', () => {
+  const workspaceRoot = createWorkspace('orphan-asset', {
+    '.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 ![used](.assets/used.png).'),
+    '.xdrs/_local/adrs/principles/.assets/used.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/orphan.png': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Orphan asset file');
+  expect(result.errors.join('\n')).toContain('orphan.png');
+  expect(result.errors.join('\n')).not.toContain('used.png');
+});
+
+test('does not report asset files that are referenced', () => {
+  const workspaceRoot = createWorkspace('no-orphan-asset', {
+    '.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 ![img](.assets/diagram.png).'),
+    '.xdrs/_local/adrs/principles/.assets/diagram.png': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Orphan asset file');
+});
+
+test('reports orphan asset in articles .assets directory', () => {
+  const workspaceRoot = createWorkspace('orphan-article-asset', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide article'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': [
+      '# _local-article-001: Guide',
+      '',
+      'See ![used](.assets/used.png).',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/articles/.assets/used.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/articles/.assets/unused.jpg': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Orphan asset file');
+  expect(result.errors.join('\n')).toContain('unused.jpg');
+  expect(result.errors.join('\n')).not.toContain('used.png');
+});
+
 function teamAdrIndex(entries) {
   return [
     '# myteam ADR Index',
@@ -333,18 +538,24 @@ function createWorkspace(name, files) {
   return workspaceRoot;
 }
 
-function rootIndex() {
-  return [
+function rootIndex(extraScopeLinks) {
+  const lines = [
     '# XDR Standards Index',
     '',
     '## Scope Indexes',
     '',
     'XDRs in scopes listed last override the ones listed first',
     '',
+  ];
+  if (extraScopeLinks) {
+    lines.push(...extraScopeLinks, '');
+  }
+  lines.push(
     '### _local (reserved)',
     '',
     'Project-local XDRs stay in the workspace tree only.',
-  ].join('\n');
+  );
+  return lines.join('\n');
 }
 
 function localAdrIndex(entries) {

package/package.json

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