xdrs-core 0.26.0 → 0.27.1

package/.filedist-package.yml

@@ -0,0 +1,23 @@
+sets:
+  - selector:
+      files:
+        - AGENTS.md
+        - .xdrs/_core/**
+      exclude:
+        - "**/*.test.js"
+        - "**/*.test.int.js"
+        - "**/*.test.int.report"
+    output:
+      path: .
+      symlinks:
+        - source: .xdrs/**/skills/*
+          target: .github/skills
+      gitignore: false
+
+  - selector:
+      files:
+        - .xdrs/index.md
+    output:
+      path: .
+      gitignore: false
+      managed: false

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-001-xdrs-core
 description: Defines the core XDRS framework including types (ADR, BDR, EDR), folder structure, scopes, subjects, and index requirements. Use when structuring or navigating policies.
+apply-to: All XDRS scopes and document types
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-001: XDRs core
@@ -56,7 +58,6 @@ Policies can be of different kinds, depending on the nature of the decision:
   - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
   - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
   - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
-- Sub-directories inside `.assets/` are allowed to keep related files organized only when that `.assets/` folder already has more than 10 files. Otherwise, keep files flat in `.assets/`.
 - **Scopes:** 
   - Short name that defines a group or a package of XDRS
   - examples: `business-x`, `business-y`, `team-43`, `_core`

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-002-policy-standards
 description: Defines how Policy documents (the core Policy document type) should be written, including template, frontmatter, applicability fields, and conflict handling. Use when writing or reviewing any Policy, rules, contraints or a specific decision document.
+apply-to: All Policy documents
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-002: Policy standards
@@ -25,8 +27,8 @@ Policy documents are the authoritative source of truth for their scope, type, an
 |---|---|---|
 | `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]-policy-[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. |
-| `apply-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. |
+| `apply-to` | Yes | Short description of contexts this decision is applicable to. Keep it under 40 words. Use `All scopes` when the decision applies broadly. Examples: `Only frontend code`, `JavaScript projects`, `All scopes`. |
+| `valid-from` | Yes | 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. Defaults to the date the Policy was created. |
 | `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. |
 
@@ -35,6 +37,8 @@ Policy documents are the authoritative source of truth for their scope, type, an
     ---
     name: _core-adr-policy-002-policy-standards
     description: Defines how Policy documents should be written. Use when writing or reviewing any Policy.
+    apply-to: All scopes
+    valid-from: 2026-05-21
     ---
     ```
   - Example with optional fields:
@@ -68,7 +72,6 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - Never use emojis in contents.
 - Always use file names with lowercase.
 - Any non-Markdown files referenced by a Policy (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `[xdrs-root]/[scope]/[type]/[subject]/.assets/`.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Avoid using lengthy instructions on the Policy. If there are long and detailed instructions related to the Policy, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the Policy itself.
 - Policies should be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision
@@ -83,8 +86,8 @@ All Policies MUST follow this template
 ---
 name: [scope]-[type]-policy-[number]-[short-title]
 description: [What this decision is about and when to use it]
-apply-to: [Optional. Contexts this decision applies to, under 40 words]
-valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+apply-to: [Required. Contexts this decision applies to, under 40 words. Use "All scopes" when broadly applicable.]
+valid-from: [Required. ISO date YYYY-MM-DD from when enforcement begins. Defaults to creation date.]
 license: [Optional. SPDX license expression]
 metadata:
   [optional-key]: [optional-value]
@@ -111,7 +114,7 @@ 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 the user explicitely indicated that there were multiple options to choose from while making this decision and have a backing research document]
+[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision or have a backing research document]
 
 [Related research, if any]
 - [Research document title](researches/001-example.md) - Brief description of what it informed

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-003-skill-standards
 description: Defines skill package standards including structure, SKILL.md format, and co-location with XDRS packages. Use when creating or reviewing skills.
+apply-to: All skill packages
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-003: Skill standards
@@ -116,7 +118,6 @@ Rules:
 - `## Instructions` SHOULD include verification steps or acceptance criteria at the end of the task, or at the end of major phases when partial validation matters.
 - For simple structure, flow, layout, or relationship indications, `SKILL.md` SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
 - Any non-Markdown files referenced from `SKILL.md` (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Keep `SKILL.md` under 6500 words. Move lengthy reference material to `references/`.
 - Use relative paths for all links; never use absolute paths starting with `/`.
 - Always use lowercase file names.

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-004-article-standards
 description: Defines article document standards for synthesizing and linking Policies, research, and skills. Use when creating or reviewing articles.
+apply-to: All article documents
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-004: Article standards
@@ -19,6 +21,15 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 
 ### Details
 
+**Human-first writing**
+
+- The primary objective of an article is to make information available and accessible to humans. Good copywriting style, storytelling, clear organization, and clustering of related information are essential. Avoid repetitive content; each sentence should add new value.
+- Articles SHOULD stay under 2000 words (approximately a 10-minute read) to maximize reader engagement. When planning an article, keep it as small as possible. Break large subjects into separate chapters, each in its own article, so readers can consume and understand sections independently.
+- When a topic is broken into multiple articles, organize them as a **series**: each article MUST declare its position at the very top (e.g., `_This is article 2/4 of the "Engineering Practices" series._`) and MUST link to the previous and next articles in the series so readers can navigate the sequence without returning to an index.
+- Articles should be kept under 8000 words (hard limit). Move or point to detailed contents referenced in Policy decisions, researches, plans, or skills.
+
+**Content and structure**
+
 - Articles are views, not decisions. They summarize and synthesize content from Policies, Research, and Skills but are NOT the source of truth. When there is a conflict between an article and a Policy, the Policy takes precedence.
 - Articles are not limited to synthesizing Policies. They may also document application features, APIs, general project information, reference tables, diagrams, FAQs and other elements useful to their intended audience.
 - Articles must reference the Policies, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
@@ -29,10 +40,8 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 - Place an article in the subject folder that best matches its topic using the required list of subjects per type defined in `_core-adr-policy-001`. If an article spans more than one subject, place it in `principles`.
 - For simple structure, flow, layout, or relationship indications, articles SHOULD prefer plain Markdown, tables, or ASCII art instead of external assets.
 - Any non-Markdown files referenced by an article (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Always use lowercase file names.
 - Never use emojis in article content.
-- Articles should be kept under 5000 words. Move or point to detailed contents referenced in Policy decisions, researches, plans or skills.
 
 **Folder layout**
 
@@ -64,6 +73,9 @@ All articles MUST follow this template:
 ```markdown
 # [scope]-[type]-article-[number]: [Short Title]
 
+<!-- If this article is part of a series, add the line below (omit otherwise): -->
+_This is article [N]/[Total] of the "[Series Name]" series. | Previous: [title](./[prev-file].md) | Next: [title](./[next-file].md)_
+
 ## Overview
 
 [Brief description of what this article covers and its intended audience. (<40 words)]

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-005-semantic-versioning-for-xdrs-packages
 description: Defines how semantic versioning applies to XDRS packages. Use when publishing or versioning a package containing Policies, research, skills, or articles.
+apply-to: XDRS packages using semantic versioning
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-005: Semantic versioning for XDRS packages

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-006-research-standards
 description: Defines research document standards including IMRAD structure and traceability to Policies. Use when creating or reviewing research documents.
+apply-to: All research documents
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-006: Research standards
@@ -49,7 +51,6 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not required.
 - One research document MAY also be referenced by multiple Policies, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
 - Any non-Markdown files referenced by a research document (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 - Research file names MUST be lowercase. Never use emojis.
 - A research document MAY exist before the related Policy is written, or remain after the Policy changes, as long as its status and references stay clear.
 

package/.xdrs/_core/adrs/principles/007-plan-standards.md

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-007-plan-standards
 description: Defines plan document standards for describing problems, solutions, and activities. Use when creating or reviewing plans.
+apply-to: All plan documents
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-007: Plan standards
@@ -32,7 +34,6 @@ Plans are Markdown documents placed inside a subject folder alongside policies.
 - Always use lowercase file names.
 - Never use emojis in plan content.
 - Any non-Markdown files referenced by a plan (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `plans/.assets/` next to the plan files.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
 
 **Folder layout**
 

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

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-008-policy-standards-structured
 description: Extends policy-standards with a numbered rule format for Policy documents that define strong policies or rules, or need individually referenceable items. Use when a Policy must expose explicit rule blocks that other documents or skills may cite by identifier.
+apply-to: Policy documents requiring structured rule blocks
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-008: Policy standards - structured
@@ -26,7 +28,7 @@ Use this format when the decision defines strong rules or policies that must be
 Each numbered rule must be written as:
 
 ```markdown
-#### [NN]-[short-descriptive-title-in-kebab-case]
+#### [NN]-[short descriptive title with mandatory or advisory language about the enforced policy item]
 [Body using mandatory or advisory language as defined in _core-adr-policy-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
 ```
 
@@ -42,31 +44,31 @@ Rule bodies must use the mandatory or advisory language terms defined in `_core-
 When another document or skill cites a specific rule, it must use the following dot-notation:
 
 ```
-policy-name.NN-short-descriptive-title-in-kebab-case
+policy-name.[NN-Short descriptive title as written in the heading]
 ```
 
 Examples:
 
-- `_core-adr-policy-008-policy-standards-structured.[01-use-numbered-rules-for-strong-or-referenceable-policies]`
-- `_local-bdr-policy-003-data-retention-policy.[02-purge-schedule-for-pii]`
+- `_core-adr-policy-008-policy-standards-structured.[01-Always use numbered rules for strong or referenceable policies]`
+- `_local-bdr-policy-003-data-retention-policy.[02-Purge schedule for PII]`
 
-The `policy-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.
+The `policy-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier inside the brackets must match the heading text exactly, including the two-digit prefix.
 
-#### 01-use-numbered-rules-for-strong-or-referenceable-policies
+#### 01-Always use numbered rules for strong or referenceable policies
 
 Numbered rule blocks must be added to a Policy 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 Policy documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-policy-002-policy-standards` without this structured format.
 
-#### 02-rule-numbering-must-be-stable
+#### 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
+#### 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-policy-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
+#### 04-Citations must use exact identifiers
 
-Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.NN-short-descriptive-title-in-kebab-case`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
+Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.[NN-Heading text as written]`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
 
 ## Considered Options
 

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -1,6 +1,8 @@
 ---
 name: _core-adr-policy-009-presentation-standards
 description: Defines how Marp slide presentations are structured, named, placed, and linked within XDRS projects. Use when creating, reviewing, or linting slide decks that support XDRS documents.
+apply-to: Marp slide presentations in XDRS projects
+valid-from: 2025-01-01
 ---
 
 # _core-adr-policy-009: Presentation standards

package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md

@@ -22,7 +22,7 @@ Performs a structured review of code changes or files against the Policies in th
 
 ### Phase 2: Policy Compilation
 
-1. Gather all Policies from the Policy root `index.md` (default: `.policies/index.md`) starting from the working directory.
+1. Gather all Policies from the Policy root `index.md` (default: `.xdrs/index.md`) starting from the working directory.
    - Policy scopes are controlled by nested folders; some are broad, others domain-specific.
    - Extract frontmatter first to decide whether each Policy should be used for the current review context.
    - All documents present in the collection are considered active.

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

@@ -107,8 +107,8 @@ Refer to `_core-adr-policy-008-policy-standards-structured` for full requirement
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-apply-to: [Optional. Contexts this decision applies to, under 40 words]
-valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+apply-to: [Required. Contexts this decision applies to, under 40 words. Use "All scopes" when broadly applicable.]
+valid-from: [Required. ISO date YYYY-MM-DD. Defaults to today's date when not specified by the user.]
 ---
 
 # [scope]-[type]-[number]: [Short Title]
@@ -132,8 +132,8 @@ valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ```
 
 Mandatory rules to apply while drafting:
-- Include frontmatter `apply-to:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
-- Include frontmatter `valid-from:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
+- Always include frontmatter `apply-to:`. Use `All scopes` when the decision applies broadly, or a more specific description when the decision is narrowly scoped.
+- Always include frontmatter `valid-from:`. Use today's date in `YYYY-MM-DD` format when the user does not specify a date.
 - Keep `apply-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
 - When frontmatter metadata is present, write it so a reader can decide whether the Policy should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `apply-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
@@ -152,7 +152,7 @@ Mandatory rules to apply while drafting:
 Check every item before finalizing:
 
 1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
-2. **Frontmatter**: Are `apply-to:` and `valid-from:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the Policy is currently valid and applicable?
+2. **Frontmatter**: Are `apply-to:` and `valid-from:` both present? `apply-to:` must describe the applicable context (use `All scopes` when broadly applicable). `valid-from:` must be set (use today's date if the user did not specify one).
 3. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
 4. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
 5. **Redundancy**: Is the Policy the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?

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

@@ -120,7 +120,7 @@ If any check fails, revise before continuing.
 1. Create the skill file at `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`.
 2. Create a symlink at `.github/skills/[number]-[skill-name]` so VS Code picks it up immediately:
    ```
-   mkdir -p .github/skills/[number]-[skill-name]
+   mkdir -p .github/skills
    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-policy-001`.

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

@@ -90,6 +90,7 @@ when referencing information from those documents. Keep under 1950 words total.]
 
 Rules to apply while drafting:
 
+- **Write for humans first.** Use clear copywriting style, natural storytelling flow, and logical clustering of related information. Each paragraph should guide the reader forward — avoid repeating information already stated.
 - Write for the stated audience; avoid jargon unexplained elsewhere.
 - Every factual claim must link back to the authoritative Policy or Skill.
 - If the article advises readers what to do, clearly separate active/applicable Policies from background, historical, or out-of-scope ones.
@@ -97,7 +98,7 @@ Rules to apply while drafting:
 - Prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams), or ASCII art for simple structure, flow, layout, or relationship indications.
 - If the article genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/articles/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
-- Keep the article under 1950 words; move detailed content to Policies or Skills.
+- Target under 1950 words for best reader engagement (SHOULD). If content grows beyond that, break it into separate chapter articles rather than expanding a single file. The hard limit is 8000 words.
 - Use lowercase file names. Never use emojis.
 - If a conflict exists between the article and a Policy, note it and defer to the Policy.
 
@@ -131,7 +132,8 @@ Rules to apply while drafting:
 - **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 Policy.
-- **Article would exceed 1950 words** — move detailed content to a new Research, Skill, or Policy and link back.
+- **Article approaches 2000 words** — split the content into separate chapter articles (e.g., `001-topic-overview.md`, `002-topic-deep-dive.md`) so each can be read and understood independently. Move detailed content to a Research, Skill, or Policy and link back. The hard ceiling is 8000 words; never exceed it.
+- **Article is part of a series** — add the series position line immediately after the heading (e.g., `_This is article 2/4 of the "Engineering Practices" series. | Previous: ... | Next: ..._`) and link to the adjacent articles. When creating a new article that splits an existing one, update the neighbouring articles to reflect the new total and add or correct their navigation links.
 
 ## Constraints
 

package/lib/lint.js

@@ -32,7 +32,7 @@ const SLIDE_FILE_RE = /^.+-slides(?:-[a-z0-9-]+)?\.md$/;
 const SLIDE_MAX_NAME_LENGTH = 64;
 const EMOJI_RE = /\p{Extended_Pictographic}/u;
 const POLICY_MAX_WORDS = 2600;
-const ARTICLE_MAX_WORDS = 5000;
+const ARTICLE_MAX_WORDS = 8000;
 const RESEARCH_MAX_WORDS = 5000;
 const SKILL_MAX_WORDS = 6500;
 
@@ -389,12 +389,14 @@ function lintXdrsElementFrontmatter(content, expectedName, filePath, errors) {
   } else if (fm.descriptionText && fm.descriptionText.length > 1024) {
     errors.push(`Policy frontmatter description must be 1024 characters or fewer: ${toDisplayPath(filePath)}`);
   }
-  if (fm.validFrom !== undefined) {
-    if (!isIsoDate(fm.validFrom)) {
-      errors.push(`Policy frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
-    }
+  if (!fm.validFrom) {
+    errors.push(`Policy frontmatter must include a valid-from field: ${toDisplayPath(filePath)}`);
+  } else if (!isIsoDate(fm.validFrom)) {
+    errors.push(`Policy frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
   }
-  if (fm.appliedTo !== undefined) {
+  if (!fm.appliedTo) {
+    errors.push(`Policy frontmatter must include an apply-to field: ${toDisplayPath(filePath)}`);
+  } else {
     const words = countWords(fm.appliedTo);
     if (words === 0) {
       errors.push(`Policy frontmatter apply-to must not be empty: ${toDisplayPath(filePath)}`);

package/lib/lint.test.js

@@ -234,6 +234,68 @@ test('accepts all known frontmatter fields in XDRS element documents', () => {
   expect(result.errors.join('\n')).not.toContain('unknown field');
 });
 
+test('reports missing apply-to field in Policy frontmatter', () => {
+  const workspaceRoot = createWorkspace('xdrs-element-missing-apply-to', {
+    '.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': [
+      '---',
+      'name: _local-adr-policy-001-main',
+      'description: Test XDRS element',
+      'valid-from: 2026-01-01',
+      '---',
+      '',
+      '# _local-adr-policy-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Policy frontmatter must include an apply-to field');
+});
+
+test('reports missing valid-from field in Policy frontmatter', () => {
+  const workspaceRoot = createWorkspace('xdrs-element-missing-valid-from', {
+    '.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': [
+      '---',
+      'name: _local-adr-policy-001-main',
+      'description: Test XDRS element',
+      'apply-to: All scopes',
+      '---',
+      '',
+      '# _local-adr-policy-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Policy frontmatter must include a valid-from field');
+});
+
 test('reports unknown frontmatter fields in SKILL.md files', () => {
   const workspaceRoot = createWorkspace('skill-unknown-frontmatter', {
     '.xdrs/index.md': rootIndex(),
@@ -820,6 +882,8 @@ function xdrDocument(body) {
     '---',
     'name: _local-adr-policy-001-main',
     'description: Test XDRS element',
+    'apply-to: All scopes',
+    'valid-from: 2026-01-01',
     '---',
     '',
     '# _local-adr-policy-001: Main decision',
@@ -860,6 +924,8 @@ test('accepts a custom root folder name as the XDRS root when it contains index.
     '---',
     'name: _local-adr-policy-001-main-decision',
     'description: Test XDRS element',
+    'apply-to: All scopes',
+    'valid-from: 2026-01-01',
     '---',
     '',
     '# _local-adr-policy-001: Main decision',
@@ -893,6 +959,8 @@ test('falls back to .xdrs subdirectory when given path has no index.md', () => {
     '---',
     'name: _local-adr-policy-001-main-decision',
     'description: Test XDRS element',
+    'apply-to: All scopes',
+    'valid-from: 2026-01-01',
     '---',
     '',
     '# _local-adr-policy-001: Main decision',
@@ -1144,8 +1212,8 @@ test('reports XDRS element document exceeding 2600 word limit', () => {
   expect(result.errors.join('\n')).toContain('Policy exceeds maximum word count of 2600');
 });
 
-test('reports article exceeding 5000 word limit', () => {
-  const longBody = ('word '.repeat(5001)).trimEnd();
+test('reports article exceeding 8000 word limit', () => {
+  const longBody = ('word '.repeat(8001)).trimEnd();
   const workspaceRoot = createWorkspace('article-too-many-words', {
     '.xdrs/index.md': rootIndex(),
     '.xdrs/_local/adrs/index.md': localAdrIndex([
@@ -1156,7 +1224,7 @@ test('reports article exceeding 5000 word limit', () => {
 
   const result = lintWorkspace(workspaceRoot);
 
-  expect(result.errors.join('\n')).toContain('Article exceeds maximum word count of 5000');
+  expect(result.errors.join('\n')).toContain('Article exceeds maximum word count of 8000');
 });
 
 test('reports research exceeding 5000 word limit', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",
@@ -20,58 +20,19 @@
   "files": [
     ".xdrs/_core/**",
     ".xdrs/index.md",
+    ".filedist-package.yml",
     "package.json",
     "AGENTS.md",
     "bin/core.js",
-	  "lib/**/*.js"
+    "lib/**/*.js"
   ],
   "devDependencies": {
     "jest": "^29.7.0"
   },
   "dependencies": {
-    "filedist": "^0.26.0",
+    "filedist": "^0.34.1",
     "ignore": "^7.0.5",
     "minimatch": "^10.2.5"
   },
-  "filedist": {
-    "sets": [
-      {
-        "selector": {
-          "files": [
-            "AGENTS.md",
-            ".xdrs/_core/**"
-          ],
-          "exclude": [
-            "**/*.test.js",
-            "**/*.test.int.js",
-            "**/*.test.int.report"
-          ]
-        },
-        "output": {
-          "path": ".",
-          "symlinks": [
-            {
-              "source": ".xdrs/**/skills/*",
-              "target": ".github/skills"
-            }
-          ],
-          "gitignore": false
-        }
-      },
-      {
-        "selector": {
-          "files": [
-            ".xdrs/index.md"
-          ]
-        },
-        "output": {
-          "path": ".",
-          "gitignore": false,
-          "managed": false,
-          "keepExisting": true
-        }
-      }
-    ]
-  },
   "bin": "bin/core.js"
 }