xdrs-core 0.15.4 → 0.17.0

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

@@ -13,6 +13,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages** — How to version XDR packages to communicate upgrade impact
 - [_core-adr-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing XDR decisions
 - [_core-adr-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
+- [_core-adr-008](principles/008-xdr-standards-structured.md) - **XDR standards - structured** — How to expose individually referenceable numbered rules inside an XDR when external citation by identifier is required
 
 ## Skills
 

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

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

package/.xdrs/_core/adrs/principles/002-xdr-standards.md

@@ -25,7 +25,7 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 |---|---|---|
 | `name` | Yes | 1-64 characters. Lowercase letters, numbers, hyphens, and leading underscores only. Must not end with a hyphen. Must not contain consecutive hyphens. Must match the document identifier from the heading: `[scope]-[type]-[number]-[short-title]`. |
 | `description` | Yes | 1-1024 characters. Describes what this decision is about and when to use it. Should include keywords that help agents identify when to apply it. |
-| `applied-to` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. Examples: `Only frontend code`, `JavaScript projects`. |
+| `applied-to` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. ONLY use this section if the usage is very specific to a specific case. Examples: `Only frontend code`, `JavaScript projects`. |
 | `valid-from` | No | ISO date (`YYYY-MM-DD`) indicating from when this decision must be enforced. Before this date it should be used everywhere possible, but compliance is not enforced during reviews until after this date. |
 | `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
 | `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
@@ -60,6 +60,7 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 - Decisions MUST be concise and reference other XDRs to avoid duplication.
 - The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `applied-to` and `valid-from` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
 - Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the reader apply the decision correctly. Keep them short and decision-specific.
+- When the decision defines strong policies or rules that should be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the XDR MUST follow the extension [_core-adr-008 - XDR standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
 - Conflict handling applies to XDR documents:
   - For cross-scope overrides, document the decision conflict in the XDR `## Conflicts` section of the XDR that overrides another scope.
   - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, removed, or the conflict resolved through a new XDR.
@@ -107,6 +108,14 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 [Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
 
+## Considered Options 
+[this section is present ONLY if there was more than one option to choose from]
+
+* (CHOSEN) **Option 2** - Brief description of option 2
+  * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.
+* (REJECTED) **Option 1** - Brief description of option 1
+  * Reason: Brief description why this was rejected with important aspects to be re-checked in the case we want to change this decision
+
 [Related research, if any]
 - [Research document title](researches/001-example.md) - Brief description of what it informed
 
@@ -144,3 +153,4 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - [_core-adr-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-004 - Article standards](004-article-standards.md)
 - [_core-adr-006 - Research standards](006-research-standards.md)
+- [_core-adr-008 - XDR standards - structured](008-xdr-standards-structured.md) - Extension for XDRs that expose individually referenceable rules

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

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

package/.xdrs/_core/adrs/principles/008-xdr-standards-structured.md

@@ -0,0 +1,81 @@
+---
+name: _core-adr-008-xdr-standards-structured
+description: Extends xdr-standards with a numbered rule format for XDR documents that define strong policies or rules, or need individually referenceable items. Use when an XDR must expose explicit rule blocks that other documents or skills may cite by identifier.
+---
+
+# _core-adr-008: XDR standards - structured
+
+## Context and Problem Statement
+
+Some XDR documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Implementation Details" are fragile and ambiguous.
+
+Question: How should an XDR document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
+
+## Decision Outcome
+
+**Numbered rule blocks inside Implementation Details with a canonical citation syntax**
+
+When an XDR document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Implementation Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
+
+### Implementation Details
+
+Use this format when the decision defines strong rules or policies that must be stated explicitly as stable rule blocks, or when there is a clear need for external documents, skills, or agents to reference specific items inside an XDR without duplicating the full policy text. Standard XDRs that do not define strong rule sets and do not need item-level citation should follow `_core-adr-002-xdr-standards` without adding numbered rule headings.
+
+#### Rule block format
+
+Each numbered rule must be written as:
+
+```markdown
+#### [NN]-[short-descriptive-title-in-kebab-case]
+[Body using mandatory or advisory language as defined in _core-adr-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
+```
+
+Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers must be unique within the document and must never be reused after a rule is removed.
+
+Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-001`:
+
+- Mandatory: "must", "always", "never", "required", "mandatory"
+- Advisory: "should", "recommended", "advised", "preferably", "possibly", "optionally"
+
+#### Citation syntax
+
+When another document or skill cites a specific rule, it must use the following dot-notation:
+
+```
+[xdr-name].[NN-short-descriptive-title-in-kebab-case]
+```
+
+Examples:
+
+- `_core-adr-008-xdr-standards-structured.[01-use-numbered-rules-for-strong-or-referenceable-policies]`
+- `_local-bdr-003-data-retention-policy.[02-purge-schedule-for-pii]`
+
+The `xdr-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier after the dot must match the heading text exactly, including the two-digit prefix and kebab-case title.
+
+#### 01-use-numbered-rules-for-strong-or-referenceable-policies
+
+Numbered rule blocks must be added to an XDR when the decision defines strong rules or policies that must be stated explicitly as stable items, or when there is a clear need for other documents, skills, or agents to cite individual rules by identifier. Adding numbered rules only for cosmetic organization is not recommended. Standard XDR documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-002-xdr-standards` without this structured format.
+
+#### 02-rule-numbering-must-be-stable
+
+Rule numbers must never be reused within the same document. When a rule is removed, its number becomes permanently retired for that document. Gaps in the sequence are expected and must not be filled by renumbering remaining rules, as existing citations depend on number stability.
+
+#### 03-rule-body-must-use-normative-language
+
+Every rule body must contain at least one mandatory or advisory language term as defined in `_core-adr-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
+
+#### 04-citations-must-use-exact-identifiers
+
+Documents and skills that cite a rule must use the exact dot-notation form: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`. Prose paraphrases such as "see rule 3" or "the third rule in that XDR" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
+
+## Considered Options
+
+* (REJECTED) **Free-form prose rules with section anchors** — Use markdown heading anchors as citation targets.
+  * Reason: Anchors are fragile across editors, rendering tools, and refactors. They do not enforce a stable numbering contract and break silently when headings are reworded.
+* (CHOSEN) **Numbered rule blocks inside Implementation Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
+  * Reason: Minimal addition to the existing XDR template, stable identifiers independent of heading text, and fully compatible with `_core-adr-002-xdr-standards`.
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](002-xdr-standards.md)

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

@@ -76,6 +76,32 @@ Choose a title that clearly states the question this XDR answers, not the answer
 
 Use the mandatory template from `002-xdr-standards`:
 
+**Check if the decision requires a structured set of rules:**
+If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-008-xdr-standards-structured`. This means:
+  - Place each rule as a numbered heading block inside `### Implementation Details`.
+  - Use the format:
+    #### [NN]-[short-descriptive-title-in-kebab-case]
+    [Rule body with mandatory/advisory language.]
+  - Ensure each rule is uniquely numbered (two digits, zero-padded) and never reuse numbers if a rule is removed.
+  - Other documents must cite rules using the canonical dot-notation: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`.
+
+**Example of a structured set of rules:**
+
+```markdown
+### Implementation Details
+
+#### 01-data-must-be-encrypted-at-rest
+All user data must be encrypted at rest using AES-256 or stronger algorithms.
+
+#### 02-access-logs-must-be-retained
+Access logs must be retained for at least 90 days and reviewed monthly for suspicious activity.
+
+#### 03-external-integrations-should-be-reviewed
+All external integrations should be reviewed annually for compliance with current security standards.
+```
+
+Refer to `_core-adr-008-xdr-standards-structured` for full requirements and citation syntax.
+
 ```
 ---
 name: [scope]-[type]-[number]-[short-title]

package/.xdrs/_core/bdrs/index.md

@@ -0,0 +1,9 @@
+# _core BDRs Index
+
+Business and operational decisions about how the XDR framework operates, including policy and process rules for framework users. Owned by the platform team. Propose changes via pull request.
+
+## Principles
+
+Foundational business principles and policy decisions that guide all framework users.
+
+- [_core-bdr-001](principles/001-xdr-decisions-and-skills-usage.md) - **XDR decisions and skills usage** — How agents and humans must use XDR decisions and skills, separating policy authority from execution guidance

package/.xdrs/_core/bdrs/principles/001-xdr-decisions-and-skills-usage.md

@@ -0,0 +1,52 @@
+---
+name: _core-bdr-001-xdr-decisions-and-skills-usage
+description: Defines how agents and humans must use XDR decisions and skills, separating policy authority from execution guidance across single-agent and multi-agent workflows.
+---
+
+# _core-bdr-001: XDR decisions and skills usage
+
+## Context and Problem Statement
+
+Repositories using the XDR framework contain both decision records (BDRs, ADRs, EDRs) and skills. In multi-agent or multi-role workflows, each actor needs to know which artifact carries policy authority and which carries execution guidance.
+
+Question: How must agents and humans use XDR decisions and skills so policy, execution guidance, and role boundaries stay clear?
+
+## Decision Outcome
+
+**BDRs define compliance policy; skills operationalize it**
+
+XDR decisions are the authoritative source of mandatory policy. Skills are execution artifacts that operationalize those decisions and must never substitute them as policy authority.
+
+### Implementation Details
+
+- Before treating any XDR as a current requirement, evaluate applicability in order: `valid-from`, `applied-to`, then the decision text.
+- The set of policies that an agent or human must comply with for a given operational context must be declared in BDRs.
+- If a policy set becomes too large or too mixed in purpose to review clearly in one record, it must be split into multiple focused BDRs.
+- Specific work instructions that operationalize BDR policies must be structured as skills when the procedure is detailed enough to benefit from a dedicated operational document.
+- Every skill that operationalizes or verifies BDR policies must link to the BDRs it implements or checks.
+- If a skill conflicts with an applicable XDR, the XDR prevails. The human or agent must stop relying on the conflicting skill behavior and report the inconsistency.
+- If an applicable BDR exists but no supporting skill exists yet, the human or agent may proceed by following the BDR directly when the decision is actionable, and must report the missing skill as an operational gap.
+- In multi-agent graphs or staged workflows, every participating agent must remain bounded by the same applicable BDR policies even when agents have different local objectives, prompts, or skills.
+- Each agent or human role involved in a workflow must make explicit which applicable BDRs govern its work and which skills it is following.
+- Different documents may be consumed by different actors. For example: one agent uses skills for data acquisition, another for plan execution, and a reviewer reads BDRs directly to validate outcomes.
+
+Allowed:
+- using multiple skills to operationalize one BDR in different phases of a workflow;
+- using one skill to operationalize multiple related BDRs when the skill links them clearly;
+- having human-only, agent-only, or mixed human-agent execution for the same skill.
+
+Disallowed:
+- treating a skill as policy authority by itself;
+- inventing mandatory policy rules only inside prompts, plans, or skills;
+- allowing one agent in a workflow to bypass an applicable BDR because another agent checked a different subset of rules.
+
+## Considered Options
+
+- (REJECTED) **Keep policy and execution guidance mixed inside operational BDRs** — Makes decisions harder to reuse, review, and assign across humans and multiple agent roles.
+- (CHOSEN) **Separate mandatory policy in BDRs from executable guidance in skills** — Preserves a clear source of truth while allowing different humans and agents to execute specialized procedures.
+
+## References
+
+- [_core-adr-001](../../adrs/principles/001-xdrs-core.md)
+- [_core-adr-002](../../adrs/principles/002-xdr-standards.md)
+- [_core-adr-003](../../adrs/principles/003-skill-standards.md)

package/.xdrs/index.md

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

package/lib/lint.js

@@ -269,7 +269,7 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   const expectedName = extractExpectedXdrNameFromHeading(firstLine)
     || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
   lintXdrFrontmatter(content, expectedName, filePath, errors);
-  lintDocumentLinks(filePath, errors);
+  lintDocumentLinks(filePath, xdrsRoot, scopeName, errors);
 }
 
 function extractExpectedXdrNameFromHeading(headingLine) {
@@ -384,7 +384,7 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       }
     }
 
-    lintDocumentLinks(skillFilePath, errors);
+    lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -437,7 +437,7 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
       errors.push(`Article title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -490,7 +490,7 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
       errors.push(`Research title must start with "${expectedHeader}": ${toDisplayPath(entryPath)}`);
     }
 
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -544,7 +544,7 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
     }
 
     lintPlanExpectedEndDate(content, entryPath, errors);
-    lintDocumentLinks(entryPath, errors);
+    lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors);
   }
 
   return artifacts;
@@ -574,6 +574,8 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   const content = fs.readFileSync(indexPath, 'utf8');
   const localLinks = parseLocalLinks(content, path.dirname(indexPath));
   const linkedSet = new Set();
+  const scopeName = path.relative(xdrsRoot, indexPath).split(path.sep)[0];
+  const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (const linkPath of localLinks) {
     if (!fs.existsSync(linkPath)) {
@@ -581,6 +583,10 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
       continue;
     }
 
+    if (scopeName !== '_local' && (isPathInside(localScopePath, linkPath) || normalizePath(linkPath) === localScopePath)) {
+      errors.push(`Non-_local document must not link into _local scope: ${displayPath(indexPath, linkPath)}`);
+    }
+
     linkedSet.add(normalizePath(linkPath));
   }
 
@@ -591,11 +597,12 @@ function lintTypeIndex(indexPath, xdrsRoot, artifacts, errors) {
   }
 }
 
-function lintDocumentLinks(documentPath, errors) {
+function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors) {
   const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
   const ignoredLines = findIgnoredMarkdownLines(lines);
   const documentDir = path.dirname(documentPath);
   const resourceDir = path.join(documentDir, RESOURCE_DIR_NAME);
+  const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
   for (let index = 0; index < lines.length; index += 1) {
     if (ignoredLines[index]) {
@@ -614,6 +621,10 @@ function lintDocumentLinks(documentPath, errors) {
         continue;
       }
 
+      if (scopeName !== '_local' && (isPathInside(localScopePath, link.resolvedPath) || normalizePath(link.resolvedPath) === localScopePath)) {
+        errors.push(`Non-_local document must not link into _local scope in ${toDisplayPath(documentPath)}:${index + 1}: ${link.rawTarget}`);
+      }
+
       if (isResourceLink && !isPathInside(resourceDir, link.resolvedPath)) {
         errors.push(`Asset links in ${toDisplayPath(documentPath)} must point to ${toDisplayPath(resourceDir)}: ${link.rawTarget}`);
       }

package/lib/lint.test.js

@@ -108,6 +108,114 @@ test('derives expected frontmatter name from the markdown heading title', () =>
   expect(result.errors.join('\n')).not.toContain('XDR frontmatter name must be');
 });
 
+test('reports non-_local XDR linking to _local scope document', () => {
+  const workspaceRoot = createWorkspace('non-local-links-to-local-xdr', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [001-team](principles/001-team.md) - Team decision'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument(
+      'See [local doc](../../../_local/adrs/principles/001-main.md).'
+    ),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
+});
+
+test('allows _local XDR linking to another _local scope document', () => {
+  const workspaceRoot = createWorkspace('local-links-to-local', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision',
+      '- [002-second](principles/002-second.md) - Second decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': [
+      '---',
+      'name: _local-adr-001-main',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See [second](002-second.md).',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/002-second.md': [
+      '---',
+      'name: _local-adr-002-second',
+      'description: Second test XDR document',
+      '---',
+      '',
+      '# _local-adr-002: Second decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Second body.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).not.toContain('Non-_local document must not link into _local scope');
+  expect(result.errors.join('\n')).not.toContain('Broken local link');
+});
+
+test('reports non-_local canonical index linking to _local scope document', () => {
+  const workspaceRoot = createWorkspace('non-local-type-index-links-to-local', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument('Local decision.'),
+    '.xdrs/myteam/adrs/index.md': teamAdrIndex([
+      '- [_local 001](../../_local/adrs/principles/001-main.md) - Cross-scope link'
+    ]),
+    '.xdrs/myteam/adrs/principles/001-team.md': teamXdrDocument('Team decision.'),
+  });
+
+  const result = lintWorkspace(workspaceRoot, { ignoreReadOnly: false });
+
+  expect(result.errors.join('\n')).toContain('Non-_local document must not link into _local scope');
+});
+
+function teamAdrIndex(entries) {
+  return [
+    '# myteam ADR Index',
+    '',
+    'Team ADRs for tests.',
+    '',
+    '## principles',
+    '',
+    ...entries,
+    ''
+  ].join('\n');
+}
+
+function teamXdrDocument(body) {
+  return [
+    '---',
+    'name: myteam-adr-001-team',
+    'description: Team test XDR document',
+    '---',
+    '',
+    '# myteam-adr-001: Team decision',
+    '',
+    '## Context and Problem Statement',
+    '',
+    body,
+    ''
+  ].join('\n');
+}
+
 function createWorkspace(name, files) {
   const workspaceRoot = path.join(tmpRoot, name);
   fs.mkdirSync(workspaceRoot, { recursive: true });

package/package.json

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