xdrs-core 0.50.0 → 0.52.0

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

@@ -94,7 +94,7 @@ If the article spans more than one subject, place it in `principles`.
 
 ### Phase 4: Research Policies and Skills to Synthesize
 
-1. Read all Policies, Research documents, and Skills relevant to the article topic across all scopes listed in the Policy root `index.md`.
+1. Read all Policies, Research documents, and Skills relevant to the article topic across all scopes listed in the Policy root `index.md`, honouring activation tags (skip `disabled` scopes; use `extends-only` scope policies only through an extending scope, see `_core-adr-policy-022.08-agent-resolution`).
 2. Evaluate Policy metadata before synthesizing guidance. All documents present in the collection are considered active. Use `valid-from:` to determine the convergence date for adoption, `apply-to:` to determine whether the decision fits the audience or context being discussed, and the decision text itself for any remaining applicability boundaries.
 3. Identify the key points a reader needs to understand the topic end-to-end.
 4. Collect Policy IDs and file paths for cross-references. Never copy decision text verbatim; link to it.

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

@@ -84,7 +84,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 
 ### Phase 4: Research Related Artifacts
 
-1. Read all Policies, Research documents, Skills, and existing Initiatives relevant to the initiative topic across all scopes listed in the Policy root `index.md`.
+1. Read all Policies, Research documents, Skills, and existing Initiatives relevant to the initiative topic across all scopes listed in the Policy root `index.md`, honouring activation tags (skip `disabled` scopes; use `extends-only` scope policies only through an extending scope, see `_core-adr-policy-022.08-agent-resolution`).
 2. Evaluate Policy metadata before treating any decision as current context. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended context, and the decision text defines any remaining boundaries.
 3. Identify Decisions that this initiative implements, Research that informs the planning, and any existing Initiatives that overlap.
 4. Collect artifact IDs and file paths for cross-references.

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

@@ -50,7 +50,7 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 ### Phase 1: Understand the Decision
 
-1. Read the XDRS root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.
+1. Read the XDRS root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes. Skip scopes tagged `disabled`; scopes tagged `extends-only` apply only through an extending scope (see `_core-adr-policy-022.08-agent-resolution`).
 2. Read `.xdrs/_core/adrs/principles/001-xdrs-standards.md` in full to internalize structure rules, mandatory language, and the XDRS framework elements.
 3. Read `.xdrs/_core/adrs/principles/002-policy-standards.md` in full to internalize the Policy template and document writing rules.
 4. Treat `001-xdrs-standards` as the canonical source for all core XDRS element definitions (type, scope, subject, numbering, placement). Treat `002-policy-standards` as the canonical source for how to write and structure the document itself.
@@ -87,7 +87,7 @@ Choose a title that clearly states the question this Policy answers, not the ans
 
 ### Phase 4: Research Related Policies
 
-1. Read all existing Policies relevant to the topic across all scopes listed in the Policy root `index.md`. **Additionally**, if the target scope declares an `extends:` field in its `index.md`, resolve its full `extends:` chain depth-first (see `_core-adr-policy-010` rule 33) and treat all policy documents from those extended scopes as if they were authored in the target scope — they MUST be included in the research and conflict check just like policies written directly in the scope.
+1. Read all existing Policies relevant to the topic across all active scopes listed in the Policy root `index.md` (not tagged `disabled` or `extends-only`). **Additionally**, if the target scope declares an `extends:` field in its `index.md`, resolve its full `extends:` chain depth-first (see `_core-adr-policy-010` rule 33) and treat all policy documents from those extended scopes as if they were authored in the target scope — they MUST be included in the research and conflict check just like policies written directly in the scope.
 2. Evaluate Policy metadata before treating any decision as a current constraint. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether it fits the current topic, and the decision text defines any remaining boundaries. Treat out-of-window or out-of-scope Policies as background only when assessing overlaps and conflicts.
 3. Identify decisions that already address the topic (full or partial overlap).
 4. Note decisions that might conflict with the intended outcome.
@@ -184,12 +184,12 @@ 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?
-6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
-7. **Index entries**: Will the new Policy be added to `[scope]/[type]/index.md` and the Policy root `index.md`?
-8. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `policy`.
+4. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
+5. **Clarity**: Is the chosen option unambiguous? Is the "why" clear in one reading?
+6. **Redundancy**: Is the Policy the primary source for the decision itself, with related documents linked instead of duplicated wherever possible?
+7. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
+8. **Index entries**: Will the new Policy be added to `[scope]/[type]/index.md` and the Policy root `index.md`?
+9. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `policy`.
 
 If any check fails, revise and re-run this phase before proceeding.
 
@@ -197,7 +197,7 @@ If any check fails, revise and re-run this phase before proceeding.
 
 1. Create the Policy file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
 2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
-3. Add or verify the scope entry in the Policy root `index.md`.
+3. Add or verify the scope entry in the Policy root `index.md` (exactly one link per scope; when the scope index declares `extends-only: true`, append the tag `` `extends-only` `` right after the link and make sure the legend line is present, see `_core-adr-policy-022`).
 4. If significant research was produced or already exists, link it from the Policy `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the Policy into a long procedure.
 6. Evaluate whether the scope index at `[xdrs-root]/[scope]/index.md` should be updated to reflect the new content. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.

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

@@ -86,7 +86,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 
 ### Phase 3: Research Existing Artifacts
 
-1. Read relevant Policies across all scopes listed in the Policy root `index.md`.
+1. Read relevant Policies across all scopes listed in the Policy root `index.md`, honouring activation tags (skip `disabled` scopes; use `extends-only` scope policies only through an extending scope, see `_core-adr-policy-022.08-agent-resolution`).
 2. Evaluate Policy metadata before treating any decision as current context. All documents present in the collection are considered active. `valid-from:` determines the convergence date for adoption, `apply-to:` determines whether the decision fits the intended task context, and the decision text defines any remaining boundaries. Keep out-of-window or out-of-scope Policies as background only.
 3. Read existing research documents in the same or overlapping subjects to avoid duplicating the same study.
 4. Read related skills or articles if they contain context, implementation limits, or terminology that must be reflected.

package/.xdrs/_core/index.md

@@ -57,7 +57,7 @@ Slide presentations that support XDRS documents follow [_core-adr-policy-009](ad
 
 ### Scope types
 
-Every XDRS scope declares a `scope-type` in its `index.md` YAML frontmatter. A `scope-type` value is valid when a `{scope-type}-scope-type` policy exists in the `principles` subject of any `core`-type scope in the workspace. Multiple types MAY be declared using a comma-separated list (e.g., `scope-type: compiled, internal-docs`); each element is validated independently — see [_core-adr-policy-010](adrs/principles/010-scope-governance.md) rules 06 and 07. The five built-in scope types are defined by [_core-adr-policy-011](adrs/principles/011-core-scope-type.md) (`core`), [_core-adr-policy-012](adrs/principles/012-reference-scope-type.md) (`reference`), [_core-adr-policy-013](adrs/principles/013-platform-scope-type.md) (`platform`), [_core-adr-policy-014](adrs/principles/014-standard-scope-type.md) (`standard`), and [_core-adr-policy-015](adrs/principles/015-local-scope-type.md) (`_local`). Custom scope types can be defined following [_core-adr-policy-010](adrs/principles/010-scope-governance.md). The recommended root index ordering is `core → reference → platform → standard → _local`.
+Every XDRS scope declares a `scope-type` in its `index.md` YAML frontmatter. A `scope-type` value is valid when a `{scope-type}-scope-type` policy exists in the `principles` subject of any `core`-type scope in the workspace. Multiple types MAY be declared using a comma-separated list (e.g., `scope-type: compiled, internal-docs`); each element is validated independently — see [_core-adr-policy-010](adrs/principles/010-scope-governance.md) rules 06 and 07. The six built-in scope types are defined by [_core-adr-policy-011](adrs/principles/011-core-scope-type.md) (`core`), [_core-adr-policy-012](adrs/principles/012-reference-scope-type.md) (`reference`), [_core-adr-policy-013](adrs/principles/013-platform-scope-type.md) (`platform`), [_core-adr-policy-014](adrs/principles/014-standard-scope-type.md) (`standard`), [_core-adr-policy-015](adrs/principles/015-local-scope-type.md) (`_local`), and [_core-adr-policy-019](adrs/principles/019-compiled-scope-type.md) (`compiled`). Custom scope types can be defined following [_core-adr-policy-010](adrs/principles/010-scope-governance.md). The recommended root index ordering is `core → reference → platform → standard → _local`.
 
 ### Available skills
 

package/.xdrs/index.md

@@ -8,6 +8,8 @@ XDRS scopes listed last override the ones listed first
 
 Default ordering by scope type: `core → reference → platform → standard → _local`
 
+Scopes tagged `disabled` MUST be ignored; `extends-only` scopes apply only via extends (see _core-adr-policy-022)
+
 ### _core
 
 Defines how XDRS framework work

package/AGENTS.md

@@ -18,7 +18,7 @@ This rule has NO exceptions. Simple questions ("which command?", "what pattern?"
    - You MUST search and follow Policies for architecture, engineering and business in the Policy root index (default: [.xdrs/index.md](.xdrs/index.md)) during Informational, Q&A questions, design, plan, implementation, test and review steps etc. This is the source of truth for this agent.
 
 2. **Verify all work with build, tests and linting before completion**
-   - Always run build, lint-fix and test at the end of the implementation when changing code
+   - Always run build, lint and test at the end of the implementation when changing code
    - Fix any issues
 
 3. **Verify if implementation complies with Policies from XDRS**

package/README.md

@@ -90,13 +90,18 @@ Every scope declares a `scope-type` in its `index.md` frontmatter. The six built
 ```yaml
 # .xdrs/owasp-top10/adrs/principles/001-core.md  (compilation meta-policy)
 ## Sources
-- [web] https://owasp.org/Top10/
-- [git] https://github.com/OWASP/Top10.git
+- [web] owasp-top10-web: https://owasp.org/Top10/
+- [git] owasp-top10-git: https://github.com/OWASP/Top10.git
 
 ## Selectors
 Include A01–A10 risk entries only.
+
+## Sync Settings
+- Source re-sync period days: 30
 ```
 
+By default, fetched and selected source content persists under `.assets/sources/[name]/` so later compilations can re-sync incrementally instead of always refetching; set `Source storage: temporary` in `## Sync Settings` to discard the bulk content after each run instead (only the per-source tracking file persists in that mode). Either way, `.assets/sources/` content is never authoritative on its own — only the compiled policies are.
+
 **`standard` scopes** are the default. Use them for team, product, or business-area scopes that do not fit the other types.
 
 **`_local` scopes** hold workspace-specific content such as local tooling decisions, transition overrides, or temporary decisions. This content is never packaged or distributed.
@@ -119,6 +124,24 @@ Custom scope types can be introduced by adding a `{type}-scope-type` policy to a
 
 See [examples/typed-scope](examples/typed-scope) for a full working example covering all five scope types and a custom `business-area` type.
 
+### Scope activation
+
+Every installed scope MUST be linked exactly once in `.xdrs/index.md`, and its non-meta policies apply globally by default. Consumers narrow that with an activation tag placed right after the link:
+
+```markdown
+Scopes tagged `disabled` MUST be ignored; `extends-only` scopes apply only via extends (see _core-adr-policy-022)
+
+[View scope ecomm-ref-payments](ecomm-ref-payments/index.md) `extends-only`
+[View scope legacy-standards](legacy-standards/index.md) `disabled`
+```
+
+- `extends-only`: the scope's policies apply only through scopes that list it in `extends:`.
+- `disabled`: the scope is ignored; scopes that follow, extend or take their type from it become READ-ONLY.
+- Scope authors declare `extends-only: true` in the scope `index.md` frontmatter when the scope is meant only to be extended; lint requires the root index tag to match.
+- The root index belongs to the consumer: packages ship it unmanaged so tags survive reinstalls.
+
+See [_core-adr-policy-022](.xdrs/_core/adrs/principles/022-scope-activation.md), [_core-adr-policy-010](.xdrs/_core/adrs/principles/010-scope-governance.md) and [_core-adr-policy-011](.xdrs/_core/adrs/principles/011-core-scope-type.md).
+
 ### Subject grouping
 
 Within each scope and type, decisions are grouped by subject (e.g. `application`, `data`, `platform` for ADRs; `product`, `finance` for BDRs). This keeps related decisions together, improves human navigation, and allows AI agents to narrow their search to the relevant subject folder before reading individual records.
@@ -237,6 +260,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - initiative `Expected end date:` field presence and ISO date format
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
+- root index completeness: every scope folder linked exactly once, activation tags (`extends-only`, `disabled`) valid, coherent with the scope's `extends-only` field, and explained by the legend line when used
 - Policy metadata section placement and `valid-from` / `apply-to` field format
 - local markdown links between Policy documents, skills, articles, researches, and initiatives (excluding fenced code blocks)
 - local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document