xdrs-core 0.36.1 → 0.37.1

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

@@ -30,17 +30,25 @@ Policies can be of different kinds, depending on the nature of the decision:
 
 #### General framework standards
 
-- The main document type in the collection of XDRS is the Policy document, which contains the core of a decision, contraints, rules and what should be followed. Other documents are normally related to this policy and should never go against its contents.
-- All documents in the framework should be removed when they are no longer necessary. The latest version of the collection always represents the active set of documents. Historical versions are available via versioned packages or git history. There is no status field on documents; if a document is present, it is considered active and valid. This keeps the document base clean and avoids confusion about which documents are current. REJECT any indication in the Decisions that contradicts this rule to avoid confusion and complexity.
+- The main document type in the collection of XDRS is the Policy document, which contains the core of a decision, contraints, rules and what SHOULD be followed. Other documents are normally related to this policy and MUST NOT go against its contents.
+- All documents in the framework SHOULD be removed when they are no longer necessary. The latest version of the collection MUST represent the active set of documents. Historical versions are available via versioned packages or git history. There is no status field on documents; if a document is present, it is considered active and valid. This keeps the document base clean and avoids confusion about which documents are current. REJECT any indication in the Decisions that contradicts this rule to avoid confusion and complexity.
 - Make it clear if an instruction is mandatory or advisory.
-  - Mandatory language: "must", "always", "never", "required", "mandatory"
-  - Advisory language: "should", "recommended", "advised", "preferably", "possibly", "optionally"
-- The XDRS root folder is the folder that contains the root `index.md`. The default root folder name is `.xdrs/`. Any folder name is valid as long as it contains an `index.md`. When `.xdrs/` is used, tools and agents discover it automatically by looking for `.xdrs/index.md` relative to the workspace root. When a different folder name is used, it must be passed explicitly to tools (e.g., `xdrs-core lint my-decisions/`).
-- ALWAYS use the following folder structure for Policy documents:
+  - Policy documents MUST use BCP 14 (RFC 2119 / RFC 8174) keywords when expressing normative requirements
+    - Use **MUST** / **MUST NOT** for absolute requirements or prohibitions.
+    - Use **SHOULD** / **SHOULD NOT** for strong recommendations where valid exceptions exist but MUST be justified.
+    - Use **MAY** / **OPTIONAL** for truly optional choices.
+    - Avoid overusing normative keywords; reserve them for rules that genuinely require unambiguous compliance or optionality.
+    - Uppercase statements are ALWAYS enforced.
+    - When those words are in lowercase, they have the normal meanings in english, but are not necessarily enforced. Use only when not defining normative statements in a statement. e.g.: "This policy defines when you should use something"
+  - Expressions like "must", "always", "never", "required", "mandatory" SHOULD be written in the MUST/MUST NOT format
+  - Expressions like: "should", "recommended", "advised", "preferably" SHOULD be written in the SHOULD/SHOULD NOT format
+  - Expressions like: "possibly", "optionally" SHOULD be written in MAY/OPTIONAL format
+- The XDRS root folder is the folder that contains the root `index.md`. The default root folder name is `.xdrs/`. Any folder name is valid as long as it contains an `index.md`. When `.xdrs/` is used, tools and agents discover it automatically by looking for `.xdrs/index.md` relative to the workspace root. When a different folder name is used, it MUST be passed explicitly to tools (e.g., `xdrs-core lint my-decisions/`).
+- MUST use the following folder structure for Policy documents:
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
-- ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
-- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
+- MUST ignore symlinks paths. MUST NOT create or update documents inside symlinked folders.
+- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
@@ -71,12 +79,12 @@ Policies can be of different kinds, depending on the nature of the decision:
     - `platform` — see [`_core-adr-policy-013`](013-platform-scope-type.md)
     - `standard` — see [`_core-adr-policy-014`](014-standard-scope-type.md)
     - `_local` — see [`_core-adr-policy-015`](015-local-scope-type.md)
-  - Scope name suffixes are unlimited and may be used in any scope type.
+  - Scope name suffixes are unlimited and MAY be used in any scope type.
   - When writing or generating a new XDRS root `index.md`, use the following default ordering (scopes listed later override earlier ones): `core → reference → platform → standard → _local`. Custom-type scopes SHOULD be placed in the `standard` position.
   - **Scope index frontmatter fields:** Every scope's `index.md` MUST include the following YAML frontmatter. Fields match the Policy frontmatter standard (`_core-adr-policy-002`) in purpose, adjusted for scope-level semantics:
-    - `name` (required): The scope identifier, must exactly match the scope directory name (e.g., `myteam`, `cloud-platform-aws`). Used by tools to verify scope identity.
+    - `name` (required): The scope identifier, MUST exactly match the scope directory name (e.g., `myteam`, `cloud-platform-aws`). Used by tools to verify scope identity.
     - `description` (required): Short overview of what this scope covers and who the intended audience is. Used by AI agents for discovery and relevance matching. Max 40 words.
-    - `scope-type` (required): Scope classification type. Must match a `{scope-type}-scope-type` policy in any `core`-type scope's `principles/` directory. See `_core-adr-policy-010` for the full governance convention and `_core-adr-policy-011`, `012`–`015` for built-in type definitions.
+    - `scope-type` (required): Scope classification type. MUST match a `{scope-type}-scope-type` policy in any `core`-type scope's `principles/` directory. See `_core-adr-policy-010` for the full governance convention and `_core-adr-policy-011`, `012`–`015` for built-in type definitions.
     - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
     - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
@@ -129,24 +137,24 @@ Policies can be of different kinds, depending on the nature of the decision:
     - `governance`: Engineering governance, risk controls, and compliance mechanics.
       - Examples: dependency governance, approval policies, mandatory quality checks.
 - Never use emojis
-- **Links:** Use relative paths for all links; never use absolute paths starting with `/`.
+- **Links:** Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - **Indexes**
-  - Every document in the collection (Policies, skills, articles, research, and plans) must be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and must be added to the index or removed.
-  - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index must link to every Policy, skill, article, research, and plan under that type+scope.
+  - Every document in the collection (Policies, skills, articles, research, and plans) MUST be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and MUST be added to the index or removed.
+  - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index MUST link to every Policy, skill, article, research, and plan under that type+scope.
   - Canonical index requirements:
     - Organize XDRS documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRS in scopes listed last override XDRS in scopes listed first when addressing the same topic.
-    - Each XDRS element entry in the index MUST include a short description of its content, preferably with an imperative statement or the question it answers, when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
-  - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first". The root index must not link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
-  - Always verify if indexes are up to date after making changes
+    - Each XDRS element entry in the index MUST include a short description of its content. The description SHOULD use an imperative statement or the question it answers when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
+  - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first". The root index MUST NOT link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
+  - MUST verify if indexes are up to date after making changes
 - **Scope index**
-  - Each scope folder must maintain an `index.md` file at `[xdrs-root]/[scope]/index.md`.
+  - Each scope folder MUST maintain an `index.md` file at `[xdrs-root]/[scope]/index.md`.
   - The scope index is a short article (under 1000 words) that provides an overview of all XDRS contents within that scope. Follow article standards (`_core-adr-policy-004`) when writing this file.
-  - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful for them before diving into the specific documents. Write a guided summary that helps them decide whether to explore further.
+  - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful before diving into specific documents. Write a guided summary that helps them decide whether to explore further.
   - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
-  - At the end of the scope index, always add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
-  - Whenever the contents of a scope change (new Policies, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index should be updated to reflect the newer contents.
+  - At the end of the scope index, MUST add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
+  - Whenever the contents of a scope change (new Policies, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index SHOULD be updated to reflect the newer contents.
 
 **Folder structure examples** (using the default `.xdrs/` root):
 - `.xdrs/business-x/edrs/devops/003-required-development-workflow.md`

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

@@ -15,20 +15,20 @@ Policy framework elements (types, scopes, subjects, folder structure) are define
 
 **Structured policies with a mandatory template, applicability metadata, and clear conflict rules**
 
-Policy documents are the authoritative source of truth for their scope, type, and subject. They must be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
+Policy documents are the authoritative source of truth for their scope, type, and subject. They MUST be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
 
 ### Details
 
-- Policies MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Always cite sources.
+- Policies MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Sources MUST be cited.
 - Policies are the central artifact of the framework and the authoritative source of truth for their scope, type, and subject.
 - Policy documents MUST include a YAML frontmatter block at the very beginning of the file. The supported fields are:
 
 | Field | Required | Constraints |
 |---|---|---|
-| `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. |
+| `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` | 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. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—do not update it to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
+| `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. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—do not update it to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
 | `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. |
 
@@ -52,34 +52,35 @@ Policy documents are the authoritative source of truth for their scope, type, an
       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.
+- 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 a Policy as a current rule, humans and AI agents MUST decide whether the decision is applicable for the current case.
   - 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 Policies, but the Policy document remains the source of truth.
-- **Policy Id:** [scope]-[type]-policy-[number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
+- **Policy Id:** [scope]-[type]-policy-[number] (numbers are scoped per type+scope combination and MUST NOT be reused within that combination; MUST be lowercase)
   - Types in IDs: `adr-policy`, `bdr-policy`, `edr-policy`
-  - Define the next number of a Policy by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted Policies and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
+  - Define the next number of a Policy by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted Policies and we MUST NOT reuse numbers of different documents/decisions. Numbering gaps are expected.
 - Policies MUST be concise and reference other Policies 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 `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.
-- Policies MUST NOT include historical change notes or descriptions of what changed from a previous version. State only the current rule that must be followed. Historical context is available via git history or versioned packages.
+- Policies MUST NOT include historical change notes or descriptions of what changed from a previous version. State only the current rule that MUST be followed. Historical context is available via git history or versioned packages.
 - When a policy covers elements that could be confused with each other, include explicit disambiguation statements clarifying the distinction before stating the rules for each.
+- A "why" explanation for a policy rule MAY only be included if it is brief, non-obvious, relevant to the reader, and not longer than the rule itself.
 - Rules MUST focus on what is required or forbidden. Explanations of why a rule exists belong in a Research document, not in the Policy itself. Link to the relevant research when the rationale is important for adoption.
-- 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 Policy MUST follow the extension [_core-adr-policy-008 - Policy standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
+- 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 Policy MUST follow the extension [_core-adr-policy-008 - Policy standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
 - Conflict handling applies to Policy documents:
   - For cross-scope overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope.
-  - **Within-scope conflicts:** Policies within the same type+scope must not conflict. If two Policies appear to conflict, one should be updated, removed, or the conflict resolved through a new Policy.
+  - **Within-scope conflicts:** Policies within the same type+scope MUST NOT conflict. If two Policies appear to conflict, one SHOULD be updated, removed, or the conflict resolved through a new Policy.
 - When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
-- Never use emojis in contents.
-- Always use file names with lowercase.
+- MUST NOT use emojis in contents.
+- File names MUST be 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/`.
 - 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.
+- Policies SHOULD be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision
   - Exceptions can reach under 2600 words (templates, more elaborate decision implementations etc)
-- ALWAYS use `_local` scope if the user doesn't explicitly indicate a specific scope while creating a policy or skill.
+- MUST use `_local` scope if the user doesn't explicitly indicate a specific scope while creating a policy or skill.
 
 **Policy template**
 

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

@@ -21,12 +21,12 @@ How should skills be authored, structured, and organized within a project so tha
 
 Skills follow the [agentskills](https://agentskills.io/specification) open format and live inside the XDRS subject folder under a `skills/` sub-directory. Each skill occupies its own numbered package folder, mirroring the XDRS numbering convention.
 
-A skill may target a human operator, an AI agent, or both. Instructions must be written imperatively and at a level of detail that either a person or an agent can follow without additional context. This design allows a skill to start as a human-only procedure and evolve — incrementally — toward partial or full AI automation without restructuring the document.
+A skill MAY target a human operator, an AI agent, or both. Instructions MUST be written imperatively and at a level of detail that either a person or an agent can follow without additional context. This design allows a skill to start as a human-only procedure and evolve — incrementally — toward partial or full AI automation without restructuring the document.
 
 ### Details
 
 **Automation gradient**
-Skills exist on a spectrum from fully manual (human-only) to fully automated (agent-only). A skill should be written so it can be executed at any point on that spectrum:
+Skills exist on a spectrum from fully manual (human-only) to fully automated (agent-only). A skill SHOULD be written so it can be executed at any point on that spectrum:
 - Human reads and follows each step manually.
 - Human delegates some steps to an AI assistant.
 - An AI agent executes the skill autonomously.
@@ -35,11 +35,11 @@ Write instructions so that each step is unambiguous and self-contained. Avoid im
 
 **Relation with Policies, Research, and Articles**
 Skills are procedures, Policies are guardrails and decisions, Research documents capture the explored option space and findings behind a decision, and Articles are synthetic views that combine information from multiple artifacts.
-Always create links back and forth between skills <-> Policies 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 a Policy or another explicit policy that references the skill.
-- When a skill reads, operationalizes, or enforces Policies, it MUST evaluate the Policy 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 Policies as current requirements.
-- Skills and Policies have a many-to-many relationship: one skill may operationalize multiple Policies, and one Policy may be executed through multiple skills in different contexts.
+Skills MUST link back and forth to their related Policies 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 a Policy or another explicit policy that references the skill.
+- When a skill reads, operationalizes, or enforces Policies, it MUST evaluate the Policy 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 Policies as current requirements.
+- Skills and Policies have a many-to-many relationship: one skill MAY operationalize multiple Policies, and one Policy MAY be executed through multiple skills in different contexts.
 
 Place a skill under the XDRS type that matches the nature of the activity the skill performs:
 - **EDR skills** - engineering workflows, tool usage, coding procedures, implementation how-tos (e.g. how to design a webpage, how to run a CI pipeline, how to debug a service)
@@ -76,7 +76,7 @@ Examples:
 **Skill numbering**
 
 - Each skill has a number unique within its `scope/type/subject/skills/` namespace.
-- Determine the next number by checking the highest number already present in that namespace. Never reuse numbers of deleted skills.
+- Determine the next number by checking the highest number already present in that namespace. MUST NOT reuse numbers of deleted skills.
 - Gaps in the sequence are expected and allowed.
 
 **SKILL.md format** (agentskills spec)
@@ -119,9 +119,9 @@ Rules:
 - 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` SHOULD be used only when they are materially necessary and MUST live in `.assets/` inside the same skill package. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
 - 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.
-- Never use emojis in skill content.
+- Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
+- File names MUST be lowercase.
+- MUST NOT use emojis in skill content.
 
 **Validation**
 

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

@@ -23,25 +23,25 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 
 **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.
+- 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.
+- Articles MUST NOT exceed 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.
-- 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 `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 Policies as current rules for the discussed context.
-- Articles must remain consistent with the Policies, Research documents, and Skills they reference. When a referenced artifact changes, the article must be reviewed and updated.
+- 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. MUST NOT 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 `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 Policies as current rules for the discussed context.
+- Articles MUST remain consistent with the Policies, 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-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 SHOULD be used only when they are materially necessary and MUST live in `articles/.assets/` next to the article files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
-- Always use lowercase file names.
-- Never use emojis in article content.
+- File names MUST be lowercase.
+- MUST NOT use emojis in article content.
 
 **Folder layout**
 
@@ -64,7 +64,7 @@ Examples:
 
 - Each article has a number unique within its `scope/type/subject/articles/` namespace.
 - Determine the next number by checking the highest number already present in that namespace.
-- Never reuse numbers of deleted articles. Gaps in the sequence are expected and allowed.
+- MUST NOT reuse numbers of deleted articles. Gaps in the sequence are expected and allowed.
 
 **Article template**
 

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

@@ -17,7 +17,7 @@ Question: How should semantic versioning be used when publishing or versioning a
 
 **semantic versioning aligned with decision impact**
 
-XDRS packages must use semantic versioning so the package version communicates the expected upgrade impact on consuming teams and projects.
+XDRS packages MUST use semantic versioning so the package version communicates the expected upgrade impact on consuming teams and projects.
 
 ### Details
 
@@ -29,7 +29,7 @@ XDRS packages must use semantic versioning so the package version communicates t
 **MAJOR**
 - Use a major bump for breaking changes.
 - Use a major bump when an existing Policy changes meaning in a way that can require consuming teams to revisit architecture, governance, operations, or implementation decisions.
-- Use a major bump when impactful concepts are introduced or changed in a way that materially alters how the package should be adopted or interpreted.
+- Use a major bump when impactful concepts are introduced or changed in a way that materially alters how the package SHOULD be adopted or interpreted.
 - Typical cases: removed or renamed Policies that affect references, changed mandatory rules, changed conflict/override behavior, or changed guidance that invalidates previously compliant usage.
 
 **MINOR**

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

@@ -48,10 +48,10 @@ Research documents are Markdown files placed inside a subject folder alongside p
 - Be strict about the goal of each section. Avoid duplicating the same material across sections and prefer clarity over rhetorical flourishes.
 - Research documents SHOULD stay under 5000 words total. They MAY exceed that only when the `## Introduction` explicitly states that the study will be lengthy because a very detailed analysis is required.
 - Research documents SHOULD link in `## References` to the Policies, 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.
+- A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not mandatory.
 - 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 SHOULD be used only when they are materially necessary and MUST live in `researches/.assets/` next to the research files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
-- Research file names MUST be lowercase. Never use emojis.
+- Research file names MUST be lowercase. MUST NOT 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.
 
 **Folder layout**
@@ -75,7 +75,7 @@ Examples:
 
 - Each research document has a number unique within its `scope/type/subject/researches/` namespace.
 - Determine the next number by checking the highest number already present in that namespace.
-- Never reuse numbers of deleted research documents. Gaps are expected.
+- MUST NOT reuse numbers of deleted research documents. Gaps are expected.
 
 **Research template**
 

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

@@ -24,15 +24,15 @@ Plans are Markdown documents placed inside a subject folder alongside policies.
 - Plans describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
 - Plans are NOT the source of truth. When a plan and a Policy disagree, the Policy takes precedence.
 - Plans are ephemeral. They MUST be deleted after full implementation. The lasting outputs of a plan are actual actions or Decisions, Skills, Articles, Research documents, and other artifacts that result from execution.
-- Plans may be used to implement a certain Decision. They may also use Research documents to help with the planning process. Articles may be written on top of a plan to give more context and connect more details present in other decisions and research to people involved in the plan.
-- During the implementation of a plan, new Decisions, Articles, Skills, Research documents, and even other Plans may be created. Always link all related elements to each other.
-- A plan can be high level, describing only one milestone, or more complex, describing a WBS (work breakdown structure) along with owners, multiple milestones in a tactical sequence, and checklists to verify completeness. Actual tasks performed by actors should normally be tracked in specialized software such as GitHub or Azure DevOps.
-- The total time to deliver a plan should not be more than 2 years. If more time is needed, create a new plan later with what was learned.
+- Plans MAY be used to implement a certain Decision. They MAY also use Research documents to help with the planning process. Articles MAY be written on top of a plan to give more context and connect more details present in other decisions and research to people involved in the plan.
+- During the implementation of a plan, new Decisions, Articles, Skills, Research documents, and even other Plans MAY be created. All related elements MUST be linked to each other.
+- A plan can be high level, describing only one milestone, or more complex, describing a WBS (work breakdown structure) along with owners, multiple milestones in a tactical sequence, and checklists to verify completeness. Actual tasks performed by actors SHOULD be tracked in specialized software such as GitHub or Azure DevOps.
+- The total time to deliver a plan SHOULD NOT be more than 2 years. If more time is needed, create a new plan later with what was learned.
 - Plans MUST live under `plans/` inside the relevant subject folder: `.xdrs/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
 - The `[subject]` component MUST be one of the allowed subjects for the chosen type. The required list of allowed subjects per type is defined in `_core-adr-policy-001`.
 - 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.
+- File names MUST be lowercase.
+- MUST NOT use emojis in plan content.
 - Any non-Markdown files referenced by a plan SHOULD be used only when they are materially necessary and MUST live in `plans/.assets/` next to the plan files. See `_core-adr-policy-001` for the canonical `.assets/` path conventions.
 
 **Folder layout**
@@ -55,7 +55,7 @@ Examples:
 
 - Each plan has a number unique within its `scope/type/subject/plans/` namespace.
 - Determine the next number by checking the highest number already present in that namespace.
-- Never reuse numbers of deleted plans. Gaps in the sequence are expected and allowed.
+- MUST NOT reuse numbers of deleted plans. Gaps in the sequence are expected and allowed.
 
 **Plan template**
 

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

@@ -17,31 +17,31 @@ Question: How should a Policy document expose strong or individually referenceab
 
 **Numbered rule blocks inside Details with a canonical citation syntax**
 
-When a Policy document defines strong rules or policies that must be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
+When a Policy document defines strong rules or policies that MUST be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule MUST be placed inside `### Details` as a numbered heading block. Referencing documents and skills MUST cite rules using the canonical dot-notation identifier.
 
 ### 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 a Policy without duplicating the full policy text. Standard Policies that do not define strong rule sets and do not need item-level citation should follow `_core-adr-policy-002-policy-standards` without adding numbered rule headings.
+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 a Policy without duplicating the full policy text. Standard Policies that do not define strong rule sets and do not need item-level citation SHOULD follow `_core-adr-policy-002-policy-standards` without adding numbered rule headings.
 
 #### Rule block format
 
-Each numbered rule must be written as:
+Each numbered rule MUST be written as:
 
 ```markdown
 #### [NN]-[short-rule-title-in-mandatory-advisory-language-in-kebab-case-<12-words]
-[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.]
+[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.]
 ```
 
-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. The short descriptive title must be in kebab-case (lowercase words separated by hyphens, no spaces or uppercase letters) and express the rule summary contents (e.g.: "43-code-must-be-linted", "12-use-standard-file-structure", "02-log-all-errors-to-mlflow")
+Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers MUST be unique within the document and MUST NOT be reused after a rule is removed. The short descriptive title MUST be in kebab-case (lowercase words separated by hyphens, no spaces or uppercase letters) and express the rule summary contents (e.g.: "43-code-must-be-linted", "12-use-standard-file-structure", "02-log-all-errors-to-mlflow")
 
-Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-policy-001`:
+Rule bodies MUST use the mandatory or advisory language terms defined in `_core-adr-policy-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:
+When another document or skill cites a specific rule, it MUST use the following dot-notation:
 
 ```
 policy-name.NN-short-rule-title-in-kebab-case
@@ -52,23 +52,23 @@ Examples:
 - `_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.
+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.
 
 #### 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.
+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 SHOULD NOT be done. 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
 
-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.
+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-policy-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
+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
 
-Documents and skills that cite a rule must use the exact dot-notation form: `policy-name.NN-short-rule-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-short-rule-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.
 
 ## Considered Options
 

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

@@ -21,29 +21,29 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 
 ### Details
 
-- Slides are supporting media for XDRS documents. They must never exist as standalone artifacts without a parent decision, research, article, or plan.
-- Slides must use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
+- Slides are supporting media for XDRS documents. They MUST NOT exist as standalone artifacts without a parent decision, research, article, or plan.
+- Slides MUST use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
   ```
   ---
   marp: true
   ---
   ```
-  Additional Marp configuration keys (e.g. `theme`, `paginate`, `header`, `footer`) may be added when needed, but `marp: true` is always required as the first frontmatter key.
-- Slide files must be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-policy-001`.
-- The parent document must always contain a link to the slide file. The slide file must always contain a link back to the parent document at the end of the presentation. This bidirectional linking is mandatory.
-- Slide files must use the same base name as the parent file, suffixed with `-slides`. When multiple slide sets exist for the same parent, append a context indicator after `-slides` (e.g. `-slides-overview`, `-slides-executive`).
+  Additional Marp configuration keys (e.g. `theme`, `paginate`, `header`, `footer`) MAY be added when needed, but `marp: true` MUST be the first frontmatter key.
+- Slide files MUST be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-policy-001`.
+- The parent document MUST contain a link to the slide file. The slide file MUST contain a link back to the parent document at the end of the presentation.
+- Slide files MUST use the same base name as the parent file, suffixed with `-slides`. When multiple slide sets exist for the same parent, append a context indicator after `-slides` (e.g. `-slides-overview`, `-slides-executive`).
   - Example: parent `003-naming-conventions.md` produces `003-naming-conventions-slides.md` or `003-naming-conventions-slides-overview.md`.
-- Slide file names must not exceed 64 characters (including the `.md` extension).
-- Slide file names must be lowercase.
-- When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view must be written first. The slides then support that article, not the individual documents directly.
-- Slides should contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording must be evaluated by the audience (policies, texts under discussion, controls).
-- Slides should follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
+- Slide file names MUST NOT exceed 64 characters (including the `.md` extension).
+- Slide file names MUST be lowercase.
+- When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view MUST be written first. The slides then support that article, not the individual documents directly.
+- Slides SHOULD contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
+- Slides SHOULD follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
 - Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.
-- Always identify the target audience (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
+- The target audience MUST be identified (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
 - Keep presentations under 30 slides. Create separate slide sets for different views or audiences when needed.
-- Slides never replace policies or related document contents. When the underlying document changes, the associated slides must be reviewed and updated to stay consistent.
-- Never use emojis in slide content.
-- Always use lowercase file names.
+- Slides MUST NOT replace policies or related document contents. When the underlying document changes, the associated slides MUST be reviewed and updated to stay consistent.
+- MUST NOT use emojis in slide content.
+- File names MUST be lowercase.
 
 ## References
 

package/.xdrs/_core/adrs/principles/010-scope-governance.md

@@ -44,11 +44,11 @@ Note: this naming applies to the **policy name** only, not to any scope director
 A scope-type definition policy MUST define:
 
 - The scope type name (the value that instances declare in their `scope-type:` field).
-- When to use this scope type and what kinds of scopes should declare it.
+- When to use this scope type and what kinds of scopes SHOULD declare it.
 
 ##### 04-def-preferred-content
 
-A scope-type definition policy SHOULD preferably define:
+A scope-type definition policy SHOULD define:
 
 - Naming conventions for scope instances of this type.
 - What content SHOULD be placed in scopes of this type.
@@ -87,7 +87,7 @@ A scope-local standards policy MUST be placed in the `principles` subject of any
 
 ##### 11-local-optional
 
-Creating a scope-local standards policy is optional. It is recommended when a scope has specific structural, authoring, or content constraints that differ from `_core` defaults or the scope's declared scope-type standards.
+Creating a scope-local standards policy is optional. It SHOULD be created when a scope has specific structural, authoring, or content constraints that differ from `_core` defaults or the scope's declared scope-type standards.
 
 ##### 12-local-content
 

package/.xdrs/_core/adrs/principles/011-core-scope-type.md

@@ -36,7 +36,7 @@ Use `scope-type: core` when the scope's purpose is to hold meta governance conte
 
 #### 03-naming-convention
 
-A scope of type `core` MUST have "core" somewhere in its name (e.g., `_core`, `myarea-core`, `security-core`). The `-core` suffix is the recommended pattern. The built-in `_core` scope is the only exception to the suffix requirement.
+A scope of type `core` MUST have "core" somewhere in its name (e.g., `_core`, `myarea-core`, `security-core`). The `-core` suffix SHOULD be used as the naming pattern. The built-in `_core` scope is the only exception to the suffix requirement.
 
 #### 04-allowed-content
 
@@ -61,7 +61,7 @@ A scope that is governed by a `core` scope MUST declare this relationship explic
 
 #### 07-distribution
 
-A `core`-type scope MAY be distributed to consumers alongside the companion consumable scope, or kept internal to the team that maintains the domain. When distributed, consumers who extend or contribute to the domain scope locally MUST follow its standards. When not distributed, internal contributors must still comply.
+A `core`-type scope MAY be distributed to consumers alongside the companion consumable scope, or kept internal to the team that maintains the domain. When distributed, consumers who extend or contribute to the domain scope locally MUST follow its standards. When not distributed, internal contributors MUST still comply.
 
 ## References
 

package/.xdrs/_core/adrs/principles/012-reference-scope-type.md

@@ -32,7 +32,7 @@ Use `scope-type: reference` when the scope contains:
 - Industry standards or compliance frameworks to be adopted or mapped against (e.g., ISO 27001, SOC2, PCI-DSS, GDPR, financial regulations, accounting standards).
 - Vendor best-practice patterns or recommended architectures.
 - Reference architectures or canonical system blueprints meant to be instantiated or adapted locally.
-- Business area procedure standards: how sales processes should be conducted, how customer data must be handled, how marketing communications must comply with applicable regulations.
+- Business area procedure standards: how sales processes SHOULD be conducted, how customer data MUST be handled, how marketing communications MUST comply with applicable regulations.
 - Operational compliance guidelines: finance controls, accounting procedures, public communication standards, customer data management rules.
 
 Do not use `scope-type: reference` for scopes that represent a live service, an active team, or a production system. Use `scope-type: platform` for those.
@@ -43,7 +43,7 @@ A scope of type `reference` MUST follow the naming pattern `{domain}-ref-{name}`
 
 #### 04-content-guidance
 
-Content in a `reference`-type scope describes how something should or could be done — whether that is building a system, running a business process, or complying with a regulation. It should not describe what is currently deployed or actively managed.
+Content in a `reference`-type scope describes how something could be done — whether that is building a system, running a business process, or complying with a regulation. It SHOULD NOT describe what is currently deployed or actively managed.
 
 Policies, decisions, and standards here are to be read, adopted, adapted, or mapped — not consumed directly as live service or operational documentation. Examples include:
 

package/.xdrs/_core/adrs/principles/014-standard-scope-type.md

@@ -40,7 +40,7 @@ There is no naming requirement for `standard`-type scopes. Any valid scope name
 
 #### 04-ordering
 
-In the root `index.md`, `standard`-type scopes are placed after `platform` scopes and before `_local`. Custom scope types should also be placed in this position. Scopes listed later override scopes listed earlier on the same topic.
+In the root `index.md`, `standard`-type scopes are placed after `platform` scopes and before `_local`. Custom scope types SHOULD also be placed in this position. Scopes listed later override scopes listed earlier on the same topic.
 
 ## References
 

package/.xdrs/_core/adrs/principles/015-local-scope-type.md

@@ -1,6 +1,6 @@
 ---
 name: _core-adr-policy-015-local-scope-type
-description: Defines the `_local` scope type — reserved exclusively for the `_local` scope, which holds workspace-local decisions that must never be distributed or shared outside the current repository. Use when understanding what the `_local` scope type means.
+description: Defines the `_local` scope type — reserved exclusively for the `_local` scope, which holds workspace-local decisions that MUST NOT be distributed or shared outside the current repository. Use when understanding what the `_local` scope type means.
 apply-to: All XDRS workspace authors
 valid-from: 2026-07-01
 ---
@@ -13,7 +13,7 @@ Every XDRS workspace may need project-specific overrides or local decisions that
 
 ## Decision Outcome
 
-**Reserve `scope-type: _local` exclusively for the `_local` scope, which holds workspace-local decisions that must never leave the repository.**
+**Reserve `scope-type: _local` exclusively for the `_local` scope, which holds workspace-local decisions that MUST NEVER leave the repository.**
 
 ### Details
 
@@ -29,7 +29,7 @@ The `_local` scope holds project-specific decisions, local overrides, and worksp
 
 #### 03-exclusive-reservation
 
-The value `scope-type: _local` is reserved exclusively for the single scope named `_local`. No other scope may use this scope type.
+The value `scope-type: _local` is reserved exclusively for the single scope named `_local`. Other scopes MUST NOT use this scope type.
 
 #### 04-never-distributed
 

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

@@ -43,6 +43,7 @@ Performs a structured review of code changes or files against the Policies in th
    - **Drop any finding that cannot be traced to a specific rule in an Accepted Policy.** General good-practice observations, personal opinions, or inferred issues without an explicit Policy backing must not be reported.
    - Classify as ERROR (mandatory) or WARNING (advisory).
    - Include: location, description, Policy reference (file + line), suggestion.
+   - **Normative language check (Policy documents only):** For every Policy document in scope, verify that normative statements use uppercase BCP 14 keywords as required by `_core-adr-policy-001`. Flag as ERROR when a lowercase `must`, `must not`, `always`, or `never` is used in a normative requirement context (Details or Decision Outcome sections). Flag as WARNING when lowercase `should`, `should not`, `recommended`, `advised`, `may`, `possibly`, or `optionally` appear in a normative or permissive context where the uppercase form is expected. Context sections and question statements are exempt.
 2. Reduce false positives:
    - Evaluate ERROR findings for mandatory language in the Policy ("must", "always", "never", "required", "mandatory"). Drop or downgrade to WARNING if the language is advisory ("should", "recommended", "advised").
    - Remove findings unrelated to actual changes.

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

@@ -153,6 +153,7 @@ 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:` 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. **Normative language**: Does every normative requirement in the Details and Decision Outcome sections use uppercase BCP 14 keywords per `_core-adr-policy-001`? Replace any lowercase `must`/`should`/`may` that express requirements, prohibitions, or permissions with MUST/MUST NOT, SHOULD/SHOULD NOT, or MAY/OPTIONAL respectively. Lowercase forms are only acceptable in Context sections, question statements, or when used with their ordinary English meaning.
 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/package.json

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