xdrs-core 0.37.1 → 0.38.0

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

@@ -21,7 +21,7 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 
 ### Details
 
-A standard Decision Record normally combines several concerns in the same document: a reason (why, options considered), a policy (rules, what is the decision), a plan (consequences, when it will be implemented), a how-to (step-by-step how-to procedure), and a view on a topic. The XDRS framework separates these concerns into different document types: Policies as the source of truth for the core of the decision, Research for reasoning and evidence, Plans for implementation approach, Skills for execution procedures, and Articles for topic overviews. Supporting artifacts may explain, justify, or operationalize the policy, but they do not replace it. The compilation process of a raw Decision Record is to distribute it into those different documents and create links between them. You can also use the framework standalone, generating these elements individually directly during the writing process.
+A standard Decision Record normally combines several concerns in the same document: a reason (why, options considered), a policy (rules, what is the decision), a plan (consequences, when it will be implemented), a how-to (step-by-step how-to procedure), and a view on a topic. The XDRS framework separates these concerns into different document types: Policies as the source of truth for the core of the decision, Research for reasoning and evidence, Plans for implementation approach, Skills for execution procedures, and Articles for topic overviews. Supporting artifacts MAY explain, justify, or operationalize the policy, but they do not replace it. The compilation process of a raw Decision Record is to distribute it into those different documents and create links between them. You can also use the framework standalone, generating these elements individually directly during the writing process.
 
 Policies can be of different kinds, depending on the nature of the decision:
 - BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
@@ -48,7 +48,7 @@ Policies can be of different kinds, depending on the nature of the decision:
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
 - 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.
+- **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 NOT 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`
@@ -69,7 +69,7 @@ Policies can be of different kinds, depending on the nature of the decision:
 - **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 elements created locally to a specific project or repository. XDRS elements 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`.
+  - `_local` is a reserved scope for XDRS elements created locally to a specific project or repository. XDRS elements in `_local` MUST NOT be shared with or propagated to other contexts. This scope MUST 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 NOT 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`)
   - The `-core` suffix designates a scope as the meta governance layer for a domain. See `_core-adr-policy-011` for the `core` scope type definition.
@@ -136,7 +136,7 @@ Policies can be of different kinds, depending on the nature of the decision:
       - Examples: CI/CD stages, branch strategy, release promotion gates.
     - `governance`: Engineering governance, risk controls, and compliance mechanics.
       - Examples: dependency governance, approval policies, mandatory quality checks.
-- Never use emojis
+- MUST NOT use emojis
 - **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.

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

@@ -13,7 +13,7 @@ Policy framework elements (types, scopes, subjects, folder structure) are define
 
 ## Decision Outcome
 
-**Structured policies with a mandatory template, applicability metadata, and clear conflict rules**
+**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.
 
@@ -62,7 +62,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
   - 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 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.
+- 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.
 - 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.

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

@@ -37,7 +37,7 @@ Write instructions so that each step is unambiguous and self-contained. Avoid im
 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.
 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.
+- A skill is not policy by itself. If following a skill is REQUIRED, 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.
 

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

@@ -48,7 +48,7 @@ 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 mandatory.
+- A 1:1 relationship between one research document and one decision will likely be common in practice, but it is not REQUIRED.
 - One research document MAY also be referenced by multiple Policies, including a mix of ADRs, BDRs, and EDRs, when the same investigation remains relevant across several decisions.
 - Any non-Markdown files referenced by a research document 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. MUST NOT use emojis.

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

@@ -60,7 +60,7 @@ Numbered rule blocks MUST be added to a Policy when the decision defines strong
 
 #### 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 NOT 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
 

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

@@ -52,7 +52,7 @@ 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.
-- What content SHOULD NEVER be placed in scopes of this type.
+- What content SHOULD NOT be placed in scopes of this type.
 - Special instructions on how to organise or write content in scopes of this type.
 
 ##### 05-def-instance-declaration
@@ -130,7 +130,7 @@ When multiple standards address the same topic, the following precedence applies
 3. `follows:` scope standards (last-listed `follows:` scope wins among themselves)
 4. Scope-local `{scope-name}-core` policy standards
 
-All of the above are subordinate to `_core` structural rules, which cannot be overridden.
+All of the above are subordinate to `_core` structural rules, which MUST NOT be overridden.
 
 ##### 18-ordering-custom-types
 

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

@@ -28,11 +28,11 @@ A scope declared with `scope-type: core` is reserved for the meta organisation o
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `core`. A scope declares it by setting `scope-type: core` in its `index.md` YAML frontmatter.
+The scope type defined by this policy is `core`. A scope MUST declare it by setting `scope-type: core` in its `index.md` YAML frontmatter.
 
 #### 02-when-to-use
 
-Use `scope-type: core` when the scope's purpose is to hold meta governance content for a domain: writing standards, structural templates, process guidance for authoring or reviewing, skill files for domain-specific workflows, and ownership or contact information. Do not use it for scopes that contain actual rules or decisions intended for other teams to follow.
+`scope-type: core` MUST be used when the scope's purpose is to hold meta governance content for a domain: writing standards, structural templates, process guidance for authoring or reviewing, skill files for domain-specific workflows, and ownership or contact information. It MUST NOT be used for scopes that contain actual rules or decisions intended for other teams to follow.
 
 #### 03-naming-convention
 
@@ -40,7 +40,7 @@ A scope of type `core` MUST have "core" somewhere in its name (e.g., `_core`, `m
 
 #### 04-allowed-content
 
-Content that belongs in a `core`-type scope:
+A `core`-type scope SHOULD contain only the following types of content:
 
 - Writing standards and templates specific to the domain.
 - Structural conventions for that domain's policies.
@@ -63,6 +63,14 @@ A scope that is governed by a `core` scope MUST declare this relationship explic
 
 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.
 
+#### 08-unavailable-core-read-only
+
+A `-core` scope referenced via `follows:` in a companion scope's `index.md` may not be present in the workspace of a consumer of that companion scope. When the referenced `-core` scope is absent, the companion scope MUST be treated as READ-ONLY: no content in it MUST be added, changed, or removed. The scope lacks the meta governance that defines how its content must be authored, and modifications without those standards would produce non-compliant content. Tools and agents MUST NOT propose or apply changes to a READ-ONLY scope and MUST surface the read-only status to the user when the scope is accessed.
+
+#### 09-distribution-advisable
+
+Distributing `-core` scopes alongside their companion consumable scope to downstream consumers SHOULD be done when possible. Having the meta governance available locally allows tools, agents, and contributors to reason about authoring standards, validate content, and apply scope-local conventions correctly. Distribution is not mandatory; the companion scope remains valid and usable in READ-ONLY mode when the `-core` scope is absent (see `08-unavailable-core-read-only`).
+
 ## References
 
 - [_core-adr-policy-010 - Scope governance](010-scope-governance.md) — full scope governance model including when to prefer a `{scope-name}-core` policy (scope-local) vs. this pattern

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

@@ -23,7 +23,7 @@ How should a scope that exists as a reference model or standard be identified?
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `reference`. A scope declares it by setting `scope-type: reference` in its `index.md` YAML frontmatter.
+The scope type defined by this policy is `reference`. A scope MUST declare it by setting `scope-type: reference` in its `index.md` YAML frontmatter.
 
 #### 02-when-to-use
 

package/.xdrs/_core/adrs/principles/013-platform-scope-type.md

@@ -21,17 +21,17 @@ How should a scope that documents a live, consumable platform or service be iden
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `platform`. A scope declares it by setting `scope-type: platform` in its `index.md` YAML frontmatter.
+The scope type defined by this policy is `platform`. A scope MUST declare it by setting `scope-type: platform` in its `index.md` YAML frontmatter.
 
 #### 02-when-to-use
 
-Use `scope-type: platform` when the scope documents:
+`scope-type: platform` MUST be used when the scope documents:
 
 - An existing cloud or runtime environment that teams can deploy to directly.
 - A shared foundational service available for consumption (e.g., a payment platform, a data platform, a messaging service).
 - An operational area or live capability that can be used without local instantiation.
 
-Do not use `scope-type: platform` for blueprints or reference architectures. Use `scope-type: reference` for those. Do not use it for business domains, products, or teams — use `scope-type: standard` for those.
+`scope-type: platform` MUST NOT be used for blueprints or reference architectures — use `scope-type: reference` for those. It MUST NOT be used for business domains, products, or teams — use `scope-type: standard` for those.
 
 #### 03-naming-convention
 
@@ -39,7 +39,7 @@ A scope of type `platform` MUST follow the naming pattern `{domain}-plat-{name}`
 
 #### 04-content-guidance
 
-Content in a `platform`-type scope describes what is available, how to access it, what decisions govern its use, and what constraints or service levels apply. It documents a live service — not a blueprint to copy.
+Content in a `platform`-type scope SHOULD describe what is available, how to access it, what decisions govern its use, and what constraints or service levels apply. It MUST document a live service — not a blueprint to copy.
 
 ## References
 

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

@@ -21,22 +21,22 @@ Most XDRS scopes represent a business area, a product, a team, or a general grou
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `standard`. A scope declares it by setting `scope-type: standard` in its `index.md` YAML frontmatter.
+The scope type defined by this policy is `standard`. A scope MUST declare it by setting `scope-type: standard` in its `index.md` YAML frontmatter.
 
 #### 02-when-to-use
 
-Use `scope-type: standard` for:
+`scope-type: standard` SHOULD be used for:
 
 - Business areas, business units, or product lines.
 - Product or feature team scopes.
 - Cross-cutting engineering or architecture scopes that are not a platform or reference model.
 - Any scope that does not fit `core`, `reference`, `platform`, or `_local`.
 
-This is the default scope type. When uncertain, use `standard`.
+This is the default scope type. When uncertain, `standard` SHOULD be used.
 
 #### 03-naming-convention
 
-There is no naming requirement for `standard`-type scopes. Any valid scope name is acceptable (e.g., `business-x`, `team-43`, `mobile-app`, `checkout`).
+There is no naming requirement for `standard`-type scopes. Any valid scope name is acceptable (e.g., `business-x`, `team-43`, `mobile-app`, `checkout`). Scopes MUST follow the general scope naming rules defined in `_core-adr-policy-001`.
 
 #### 04-ordering
 

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

@@ -13,13 +13,13 @@ 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 NOT leave the repository.**
 
 ### Details
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `_local`. A scope declares it by setting `scope-type: _local` in its `index.md` YAML frontmatter.
+The scope type defined by this policy is `_local`. A scope MUST declare it by setting `scope-type: _local` in its `index.md` YAML frontmatter.
 
 #### 02-when-to-use
 
@@ -33,7 +33,7 @@ The value `scope-type: _local` is reserved exclusively for the single scope name
 
 #### 04-never-distributed
 
-Content in the `_local` scope MUST NOT be shared with or propagated to any other context. It is workspace-local only and is never packaged for distribution.
+Content in the `_local` scope MUST NOT be shared with or propagated to any other context. It is workspace-local only and MUST NOT be packaged for distribution.
 
 ## References
 

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -152,15 +152,14 @@ guidance, and the explanatory overview close together without collapsing them in
 
 Follow [_core-adr-policy-001](../001-xdrs-core.md) and [_core-adr-policy-002](../002-policy-standards.md) strictly. Key rules:
 
-- Use **mandatory language** (`must`, `never`, `required`) for non-negotiable rules and
-  **advisory language** (`should`, `recommended`) for guidance.
+- Use uppercase BCP 14 keywords: MUST/MUST NOT for non-negotiable rules, SHOULD/SHOULD NOT for strong recommendations, MAY/OPTIONAL for optional choices.
 - Before citing a Policy as a requirement, check `Valid` first, then `Applied to`, and finally the decision text to confirm the decision is in scope for the current case.
 - All documents present in the collection are considered active. Remove documents that are no longer relevant.
 - Keep Policies under 1300 words as a rule of thumb (exceptions up to 2600 words for templates or more elaborate decisions). Move procedural detail to a co-located Skill.
 - Keep exploratory option analysis in a co-located Research document instead of bloating the Policy.
-- Always update the scope+type index and the root index after adding or changing a Policy.
-- Use `_local` scope when a decision is project-specific and must not be shared.
-- Never reuse a number once it has been assigned, even if the Policy is deleted.
+- ALWAYS update the scope+type index and the root index after adding or changing a Policy.
+- Use `_local` scope when a decision is project-specific and MUST NOT be shared.
+- NEVER reuse a number once it has been assigned, even if the Policy is deleted.
 
 ### How to extend