xdrs-core 0.21.0 → 0.21.2

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

@@ -51,15 +51,16 @@ Collectively, these are referred to as XDRs.
   - `_core-adr-006` defines research standards
   - `_core-adr-007` defines plan standards
 - For simple structures, flows, layout, or relationship indications, documents SHOULD prefer plain Markdown, tables, Mermaid.js (sequence, state, activity, entity diagrams) or ASCII art instead of external assets.
-- Images and other supporting files SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they MUST live in a sibling `.assets/` folder next to the document.
+- Any non-Markdown supporting files referenced by a document (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary to preserve clarity, fidelity, or evidence. When used, they MUST live in a sibling `.assets/` folder next to the document.
   - XDRs in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
   - 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`
-  - `_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 the root `index.md` so that its decisions override or extend any decisions from all higher-positioned scopes. Shared root `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`.
+  - `_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 the root `index.md` so that its decisions override or extend any decisions from higher-positioned scopes. Shared root `index.md` files MUST NOT include an explicit link to `_local`, because `_local` remains workspace-local and is not distributed with shared packages. Readers, tools, and agents SHOULD still try the default workspace-local path `_local/index.md` when it exists, even without a root-index link. Documents in non-`_local` scopes MUST NEVER link to any document inside `_local`; 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,8 +25,8 @@ 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. |
-| `applyTo` | 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`. |
-| `validFrom` | 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` | 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. |
 
@@ -42,23 +42,23 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
     ---
     name: _core-adr-002-xdr-standards
     description: Defines how XDR documents should be written. Use when writing or reviewing any XDR.
-    applyTo: All XDR scopes
-    validFrom: 2026-06-01
+    apply-to: All XDR scopes
+    valid-from: 2026-06-01
     metadata:
       author: example-org
     ---
     ```
 - All documents present in the collection are considered active. There is no status field. When a decision is no longer relevant, valid or active, it must be removed from the collection. Historical versions are available via versioned packages or git history.
 - Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is applicable for the current case.
-  - Check `validFrom:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-  - Check `applyTo:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
+  - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
+  - Check `apply-to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
   - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
 - Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, and updates of XDRs, but the XDR document remains the source of truth.
 - **XDR Id:** [scope]-[type]-[xdr number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
   - Types in IDs: `adr`, `bdr`, `edr`
   - Define the next number of an XDR by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted XDRs and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
 - Decisions MUST be concise and reference other XDRs to avoid duplication.
-- The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `applyTo` and `validFrom` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
+- The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `apply-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:
@@ -67,6 +67,8 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 - When research exists for a decision, the XDR SHOULD mention the related research documents after the `## Considered Options` list.
 - Never use emojis in contents.
 - Always use file names with lowercase.
+- Any non-Markdown files referenced by an XDR (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 XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
 - XDRs should be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision
@@ -81,8 +83,8 @@ All XDRs MUST follow this template
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-applyTo: [Optional. Contexts this decision applies to, under 40 words]
-validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+apply-to: [Optional. Contexts this decision applies to, under 40 words]
+valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 license: [Optional. SPDX license expression]
 metadata:
   [optional-key]: [optional-value]
@@ -137,8 +139,8 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 **Examples:**
 - Frontmatter examples:
-  - `validFrom: 2026-03-01`
-  - `applyTo: JavaScript projects`
+  - `valid-from: 2026-03-01`
+  - `apply-to: JavaScript projects`
 
 **XDR ID Examples:**
 - `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)

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

@@ -36,7 +36,7 @@ Skills are procedures, XDRs are guardrails and decisions, Research documents cap
 Always create links back and forth between skills <-> XDRs when the relationship is direct, and link to related Research or Articles when they provide important context.
 - Skills are task-based artifacts. They should have a clear starting trigger, an expected end result, and enough detail for a human or agent to verify that the task finished correctly.
 - A skill is not policy by itself. If following a skill is mandatory, that obligation must come from an XDR or another explicit policy that references the skill.
-- When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope XDRs as current requirements.
+- When a skill reads, operationalizes, or enforces XDRs, it MUST evaluate the XDR metadata first. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the current task context, and the decision text itself determines any remaining boundaries. All documents present in the collection are considered active. Skills must not treat out-of-window or out-of-scope XDRs as current requirements.
 - Skills and XDRs have a many-to-many relationship: one skill may operationalize multiple XDRs, and one XDR may be executed through multiple skills in different contexts.
 
 Place a skill under the XDR type that matches the nature of the activity the skill performs:
@@ -114,7 +114,8 @@ Rules:
 - `## Overview` SHOULD state the task objective, expected outcome, and relevant prerequisites or tools when they matter.
 - `## 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.
-- Images and other local resource files referenced from `SKILL.md` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package.
+- 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

@@ -24,11 +24,12 @@ Articles are Markdown documents placed inside a subject folder alongside decisio
 - Articles must reference the XDRs, Research documents, and Skills they synthesize. Never duplicate decision content; link back to the authoritative sources.
 - Articles may serve as indexes, combining related artifacts on a specific topic into a single navigable document.
 - In more complex cases, an article may be an index of links to other articles, grouping related documentation into a single entry point that guides readers across a set of related topics.
-- When an article tells readers which decisions to follow, it SHOULD check `validFrom:` first to determine the convergence date, `applyTo:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles must not present out-of-window or out-of-scope XDRs as current rules for the discussed context.
+- When an article tells readers which decisions to follow, it SHOULD check `valid-from:` first to determine the convergence date, `apply-to:` second to determine context fit, and the decision text itself last. All documents present in the collection are considered active; articles must not present out-of-window or out-of-scope XDRs as current rules for the discussed context.
 - Articles must remain consistent with the XDRs, Research documents, and Skills they reference. When a referenced artifact changes, the article must be reviewed and updated.
 - Place an article in the subject folder that best matches its topic using the required list of subjects per type defined in `_core-adr-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.
-- Images and other local resource files referenced by an article SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files.
+- 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 1950 words. Move detailed content to referenced XDRs or Skills.

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

@@ -48,7 +48,8 @@ Research documents are Markdown files placed inside a subject folder alongside d
 - Research documents SHOULD link in `## References` to the XDRs, skills, articles, discussions, and external references relevant to the subject or that later cite the work.
 - 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 XDRs, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
-- Images and other local resource files referenced by a research document SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files.
+- 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 XDR is written, or remain after the XDR changes, as long as its status and references stay clear.
 

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

@@ -31,7 +31,8 @@ Plans are Markdown documents placed inside a subject folder alongside decision r
 - Plans MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
 - Always use lowercase file names.
 - Never use emojis in plan content.
-- Images and other local resource files referenced by a plan MUST live in `plans/.assets/` next to the plan files.
+- 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/skills/001-lint/SKILL.md

@@ -26,8 +26,8 @@ Performs a structured review of code changes or files against the XDRs in the re
    - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
    - Extract frontmatter first to decide whether each XDR should be used for the current review context.
    - All documents present in the collection are considered active.
-   - Check `validFrom:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-   - Check `applyTo:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
+   - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
+   - Check `apply-to:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
    - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
 2. Filter relevance based on file types, domains, and architectural patterns in scope.
 

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

@@ -58,7 +58,7 @@ Choose a title that clearly states the question this XDR answers, not the answer
 ### Phase 4: Research Related XDRs
 
 1. Read all existing XDRs relevant to the topic across all scopes listed in the XDR root `index.md`.
-2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
+2. Evaluate XDR metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope XDRs as background only when assessing overlaps and conflicts.
 3. Identify decisions that already address the topic (full or partial overlap).
 4. Note decisions that might conflict with the intended outcome.
 5. Read related `researches/` documents when they exist, especially if they contain constraints, findings, or option tradeoffs that should influence the decision.
@@ -107,8 +107,8 @@ Refer to `_core-adr-008-xdr-standards-structured` for full requirements and cita
 ---
 name: [scope]-[type]-[number]-[short-title]
 description: [What this decision is about and when to use it]
-applyTo: [Optional. Contexts this decision applies to, under 40 words]
-validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
+apply-to: [Optional. Contexts this decision applies to, under 40 words]
+valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ---
 
 # [scope]-[type]-[number]: [Short Title]
@@ -132,10 +132,10 @@ validFrom: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
 ```
 
 Mandatory rules to apply while drafting:
-- Include frontmatter `applyTo:` only when it adds value by narrowing the decision scope; omit it when the decision applies broadly.
-- Include frontmatter `validFrom:` only when there is a specific future enforcement date; omit it when the decision is immediately effective.
-- Keep `applyTo:` under 40 words and use `validFrom:` only with `YYYY-MM-DD` ISO format.
-- When frontmatter metadata is present, write it so a reader can decide whether the XDR should be used for the current case without guessing. `validFrom:` sets a convergence date for adoption, `applyTo:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
+- 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.
+- 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 XDR 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.
 - Do not duplicate content already in referenced XDRs — link instead.
 - Keep the decision itself authoritative in the XDR. Supporting artifacts may elaborate, but they should not restate the full decision when a short reference is enough.
@@ -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 `applyTo:` and `validFrom:` present only when they add value, omitted entirely when not needed, and specific enough for a reader to decide whether the XDR is currently valid and applicable?
+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 XDR is currently valid and applicable?
 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 XDR 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

@@ -51,7 +51,7 @@ Quick test:
 
 1. List `.xdrs/[scope]/[type]/[subject]/skills/` for existing skills. If one already covers the goal, extend or reference it instead of creating a duplicate.
 2. Read all XDRs relevant to the skill's domain to collect rules and cross-references.
-3. Evaluate XDR metadata before operationalizing those rules. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
+3. Evaluate XDR metadata before operationalizing those rules. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
 4. Decide whether the skill is merely guidance or is being referenced by an XDR as a mandatory procedure. Do not encode policy in the skill unless it comes from a referenced XDR.
 
 ### Phase 4: Write the SKILL.md

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

@@ -63,7 +63,7 @@ If the article spans more than one subject, place it in `principles`.
 ### Phase 4: Research XDRs and Skills to Synthesize
 
 1. Read all XDRs, Research documents, and Skills relevant to the article topic across all scopes listed in the XDR root `index.md`.
-2. Evaluate XDR metadata before synthesizing guidance. All documents present in the collection are considered active. Use `validFrom:` to determine the convergence date for adoption, `applyTo:` to determine whether the decision fits the audience or context being discussed, and the decision text itself for any remaining applicability boundaries.
+2. Evaluate XDR metadata before synthesizing guidance. All documents present in the collection are considered active. Use `valid-from:` to determine the convergence date for adoption, `apply-to:` to determine whether the decision fits the audience or context being discussed, and the decision text itself for any remaining applicability boundaries.
 3. Identify the key points a reader needs to understand the topic end-to-end.
 4. Collect XDR IDs and file paths for cross-references. Never copy decision text verbatim; link to it.
 

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

@@ -50,7 +50,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 ### Phase 3: Research Existing Artifacts
 
 1. Read relevant XDRs across all scopes listed in the XDR root `index.md`.
-2. Evaluate XDR metadata before treating any decision as current context. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
+2. Evaluate XDR metadata before treating any decision as current context. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope XDRs as background only.
 3. Read existing research documents in the same or overlapping subjects to avoid duplicating the same study.
 4. Read related skills or articles if they contain context, implementation limits, or terminology that must be reflected.
 5. Collect links that should appear in the final `## References` section.

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

@@ -53,7 +53,7 @@ Consult `001-xdrs-core` while making each choice in this phase. The summaries be
 ### Phase 4: Research Related Artifacts
 
 1. Read all XDRs, Research documents, Skills, and existing Plans relevant to the plan topic across all scopes listed in the XDR root `index.md`.
-2. Evaluate XDR metadata before treating any decision as current context. All documents present in the collection are considered active. `validFrom:` determines the convergence date for adoption, `applyTo:` determines whether the decision fits the intended context, and the decision text defines any remaining boundaries.
+2. Evaluate XDR metadata before treating any decision as current context. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended context, and the decision text defines any remaining boundaries.
 3. Identify Decisions that this plan implements, Research that informs the planning, and any existing Plans that overlap.
 4. Collect artifact IDs and file paths for cross-references.
 

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

@@ -19,7 +19,7 @@ XDR decisions are the authoritative source of mandatory policy. Skills are execu
 
 ### Details
 
-- Before treating any XDR as a current requirement, evaluate applicability in order: `validFrom`, `applyTo`, then the decision text.
+- Before treating any XDR as a current requirement, evaluate applicability in order: `valid-from`, `apply-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.

package/.xdrs/index.md

@@ -19,4 +19,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. Documents in non-`_local` scopes must never link into `_local`; only `_local` documents may link to other `_local` documents.
+Read _local scope index at `_local/index.md` when it exists.

package/README.md

@@ -66,7 +66,7 @@ The folder layout, file naming, and document format are designed so that AI agen
 - Each XDR is a small, focused Markdown file (target under 1300 words), covering one decision.
 - The canonical index per scope and type lists all XDRs with short descriptions, enabling agents to identify relevant records without reading every file.
 - The root index at `.xdrs/index.md` provides a single entry point for discovery.
-- XDR metadata gives agents a first-pass filter: check `validFrom` for the convergence date, then check `applyTo`, and finally the decision text itself to confirm the decision should be used in the current context. All documents present in the collection are considered active.
+- XDR metadata gives agents a first-pass filter: check `valid-from` for the convergence date, then check `apply-to`, and finally the decision text itself to confirm the decision should be used in the current context. All documents present in the collection are considered active.
 - Decisions cross-reference each other by XDR ID rather than duplicating content, keeping individual files concise.
 - Subject folders reduce the search space when a query maps to a known domain.
 
@@ -166,7 +166,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - plan `Expected end date:` field presence and ISO date format
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
-- XDR metadata section placement and `validFrom` / `applyTo` field format
+- XDR metadata section placement and `valid-from` / `apply-to` field format
 - local markdown links between XDR documents, skills, articles, researches, and plans (excluding fenced code blocks)
 - local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document
 

package/lib/lint.js

@@ -23,6 +23,10 @@ const NUMBERED_DIR_RE = /^(\d{3,})-([a-z0-9-]+)$/;
 const REQUIRED_ROOT_INDEX_TEXT = 'XDRs in scopes listed last override the ones listed first';
 const SUBJECT_ARTIFACT_DIRS = new Set(['skills', 'articles', 'researches', 'plans']);
 const RESOURCE_DIR_NAME = '.assets';
+const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_DIR_NAME]);
+
+const XDR_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata']);
+const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata', 'compatibility', 'allowed-tools']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
 
 function runLintCli(args) {
@@ -371,15 +375,20 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
   if (fm.validFrom !== undefined) {
     if (!isIsoDate(fm.validFrom)) {
-      errors.push(`XDR frontmatter validFrom must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
+      errors.push(`XDR frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
     }
   }
   if (fm.appliedTo !== undefined) {
     const words = countWords(fm.appliedTo);
     if (words === 0) {
-      errors.push(`XDR frontmatter applyTo must not be empty: ${toDisplayPath(filePath)}`);
+      errors.push(`XDR frontmatter apply-to must not be empty: ${toDisplayPath(filePath)}`);
     } else if (words >= 40) {
-      errors.push(`XDR frontmatter applyTo must be under 40 words: ${toDisplayPath(filePath)}`);
+      errors.push(`XDR frontmatter apply-to must be under 40 words: ${toDisplayPath(filePath)}`);
+    }
+  }
+  for (const key of fm.topLevelKeys) {
+    if (!XDR_ALLOWED_FRONTMATTER_KEYS.has(key)) {
+      errors.push(`XDR frontmatter has unknown field "${key}": ${toDisplayPath(filePath)}`);
     }
   }
 }
@@ -415,6 +424,21 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     const skillFilePath = path.join(entryPath, 'SKILL.md');
+    const packageEntries = safeReadDir(entryPath, errors, `read skill package ${toDisplayPath(entryPath)}`);
+
+    for (const packageEntry of packageEntries) {
+      const packageEntryPath = path.join(entryPath, packageEntry.name);
+
+      if (!packageEntry.isDirectory()) {
+        continue;
+      }
+
+      if (SKILL_PACKAGE_OPTIONAL_DIRS.has(packageEntry.name)) {
+        continue;
+      }
+
+      errors.push(`Unexpected directory in skill package: ${toDisplayPath(packageEntryPath)}`);
+    }
 
     if (!existsFile(skillFilePath)) {
       errors.push(`Missing SKILL.md in skill package: ${toDisplayPath(entryPath)}`);
@@ -437,6 +461,11 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       if (!skillFm.description) {
         errors.push(`SKILL.md frontmatter must include a non-empty description field: ${toDisplayPath(skillFilePath)}`);
       }
+      for (const key of skillFm.topLevelKeys) {
+        if (!SKILL_ALLOWED_FRONTMATTER_KEYS.has(key)) {
+          errors.push(`SKILL.md frontmatter has unknown field "${key}": ${toDisplayPath(skillFilePath)}`);
+        }
+      }
     }
 
     lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors, externalScopes);
@@ -673,17 +702,15 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
     return;
   }
 
-  const entries = safeReadDir(assetsDir, errors, `read assets directory ${toDisplayPath(assetsDir)}`);
-  if (entries.length === 0) {
+  const assetTree = collectAssetTree(assetsDir, errors);
+  if (assetTree.files.length === 0 && assetTree.directories.length === 0) {
     return;
   }
 
-  const assetFiles = entries
-    .filter((entry) => entry.isFile())
-    .map((entry) => normalizePath(path.join(assetsDir, entry.name)));
-
-  if (assetFiles.length === 0) {
-    return;
+  if (assetTree.directories.length > 0 && assetTree.files.length <= 10) {
+    for (const directoryPath of assetTree.directories) {
+      errors.push(`.assets directory must be flat unless it already contains more than 10 files: ${toDisplayPath(directoryPath)}`);
+    }
   }
 
   const repoRoot = path.dirname(xdrsRoot);
@@ -701,13 +728,37 @@ function lintOrphanAssets(assetsDir, documentPaths, xdrsRoot, errors) {
     }
   }
 
-  for (const assetPath of assetFiles) {
+  for (const assetPath of assetTree.files) {
     if (!referencedAssets.has(assetPath)) {
       errors.push(`Orphan asset file not referenced by any document: ${toDisplayPath(assetPath)}`);
     }
   }
 }
 
+function collectAssetTree(dirPath, errors) {
+  const files = [];
+  const directories = [];
+  const entries = safeReadDir(dirPath, errors, `read assets directory ${toDisplayPath(dirPath)}`);
+
+  for (const entry of entries) {
+    const entryPath = path.join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      directories.push(normalizePath(entryPath));
+      const nestedTree = collectAssetTree(entryPath, errors);
+      directories.push(...nestedTree.directories);
+      files.push(...nestedTree.files);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(normalizePath(entryPath));
+    }
+  }
+
+  return { files, directories };
+}
+
 function lintDocumentLinks(documentPath, xdrsRoot, scopeName, errors, externalScopes = new Set()) {
   const lines = fs.readFileSync(documentPath, 'utf8').split(/\r?\n/);
   const ignoredLines = findIgnoredMarkdownLines(lines);
@@ -834,18 +885,24 @@ function shouldValidateResourceLink(rawTarget) {
 function extractFrontmatter(content) {
   const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
   if (!match) {
-    return { present: false, name: null, description: false, validFrom: undefined, appliedTo: undefined };
+    return { present: false, name: null, description: false, validFrom: undefined, appliedTo: undefined, topLevelKeys: [] };
   }
   const block = match[1];
   const nameMatch = block.match(/^name:\s*(.+)$/m);
-  const validFromMatch = block.match(/^validFrom:\s*(.+)$/m);
-  const appliedToMatch = block.match(/^applyTo:\s*(.+)$/m);
+  const validFromMatch = block.match(/^valid-from:\s*(.+)$/m);
+  const appliedToMatch = block.match(/^apply-to:\s*(.+)$/m);
+  const topLevelKeys = [];
+  for (const line of block.split('\n')) {
+    const keyMatch = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*/);
+    if (keyMatch) topLevelKeys.push(keyMatch[1]);
+  }
   return {
     present: true,
     name: nameMatch ? nameMatch[1].trim() || null : null,
     description: /^description:\s*\S/m.test(block),
     validFrom: validFromMatch ? validFromMatch[1].trim() : undefined,
     appliedTo: appliedToMatch ? appliedToMatch[1].trim() : undefined,
+    topLevelKeys,
   };
 }
 

package/lib/lint.test.js

@@ -168,6 +168,134 @@ test('skips entire external scope when only some of its files are in filedist',
   expect(result.errors.join('\n')).not.toContain('Broken local link in');
 });
 
+test('reports unknown frontmatter fields in XDR documents', () => {
+  const workspaceRoot = createWorkspace('xdr-unknown-frontmatter', {
+    '.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-001-main',
+      'description: Test XDR document',
+      'unknown-field: some value',
+      '---',
+      '',
+      '# _local-adr-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('XDR frontmatter has unknown field "unknown-field"');
+});
+
+test('accepts all known frontmatter fields in XDR documents', () => {
+  const workspaceRoot = createWorkspace('xdr-known-frontmatter', {
+    '.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-001-main',
+      'description: Test XDR document',
+      'apply-to: All projects',
+      'valid-from: 2026-01-01',
+      'license: MIT',
+      'metadata:',
+      '  author: test',
+      '---',
+      '',
+      '# _local-adr-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')).not.toContain('unknown field');
+});
+
+test('reports unknown frontmatter fields in SKILL.md files', () => {
+  const workspaceRoot = createWorkspace('skill-unknown-frontmatter', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+      '---',
+      'name: 001-check-links',
+      'description: Test skill document',
+      'unknown-field: some value',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('SKILL.md frontmatter has unknown field "unknown-field"');
+});
+
+test('accepts all known frontmatter fields in SKILL.md files', () => {
+  const workspaceRoot = createWorkspace('skill-known-frontmatter', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+      '---',
+      'name: 001-check-links',
+      'description: Test skill document',
+      'license: MIT',
+      'metadata:',
+      '  version: "1.0"',
+      'compatibility: node >= 18',
+      'allowed-tools: read_file grep_search',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Test skill overview.',
+      '',
+      '## Instructions',
+      '',
+      'Test instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('unknown field');
+});
+
 test('derives expected frontmatter name from the markdown heading title', () => {
   const workspaceRoot = createWorkspace('heading-name-match', {
     '.xdrs/index.md': rootIndex(),
@@ -514,6 +642,100 @@ test('reports orphan asset in articles .assets directory', () => {
   expect(result.errors.join('\n')).not.toContain('used.png');
 });
 
+test('reports unexpected directories inside a skill package', () => {
+  const workspaceRoot = createWorkspace('unexpected-skill-package-directory', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\n\n[ADRs](adrs/index.md)\n',
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check local links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Skill body.'),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/extras/note.txt': 'unexpected',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Unexpected directory in skill package');
+  expect(result.errors.join('\n')).toContain('extras');
+});
+
+test('reports nested directories in .assets when it has 10 files or fewer', () => {
+  const workspaceRoot = createWorkspace('asset-subdir-too-small', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\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': [
+      '---',
+      'name: _local-adr-001-main-decision',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See ![img](.assets/used.png).',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/.assets/used.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/grouped/extra.png': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('.assets directory must be flat unless it already contains more than 10 files');
+  expect(result.errors.join('\n')).toContain('.assets/grouped');
+});
+
+test('allows nested directories in .assets when it has more than 10 files', () => {
+  const workspaceRoot = createWorkspace('asset-subdir-large-enough', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/index.md': '# _local Scope Overview\n\nOverview.\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': [
+      '---',
+      'name: _local-adr-001-main-decision',
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'See ![img](.assets/used.png).',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+    '.xdrs/_local/adrs/principles/.assets/used.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/01.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/02.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/03.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/04.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/05.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/06.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/07.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/08.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/09.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/10.png': Buffer.alloc(0),
+    '.xdrs/_local/adrs/principles/.assets/grouped/11.png': Buffer.alloc(0),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('.assets directory must be flat unless it already contains more than 10 files');
+});
+
 function teamAdrIndex(entries) {
   return [
     '# myteam ADR Index',
@@ -575,7 +797,7 @@ function rootIndex(extraScopeLinks) {
   lines.push(
     '### _local (reserved)',
     '',
-    'Project-local XDRs stay in the workspace tree only.',
+    'Read _local scope index at `_local/index.md` when it exists.',
   );
   return lines.join('\n');
 }

package/package.json

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