xdrs-core 0.50.0 → 0.52.0

package/.xdrs/_core/adrs/index.md

@@ -27,6 +27,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-019](principles/019-compiled-scope-type.md) - **compiled scope type** — Defines the `compiled` scope type: scopes whose policies are compiled from external authoritative sources with strict source traceability and no invented content
 - [_core-adr-policy-020](principles/020-media-and-asset-standards.md) - **Media and asset standards** — Canonical diagram format preference order and non-Markdown asset rules for all XDRS document types
 - [_core-adr-policy-021](principles/021-skill-bundling.md) - **Skill bundling** — Optional per-skill Makefile mechanism to stage a self-contained dist/ output for standalone distribution
+- [_core-adr-policy-022](principles/022-scope-activation.md) - **Scope activation** — How installed scopes are listed in the root index, activated, narrowed, or disabled, and when they become read-only
 
 ## Skills
 

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

@@ -75,25 +75,26 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - **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.
-  - **Scope types:** Every scope MUST declare its type via a `scope-type` field 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 MUST be valid independently. See `_core-adr-policy-010` rules 06 and 07 for the full multi-type grammar. Custom scope-type names MUST NOT start with `_`. The five built-in scope types and their definitions are:
+  - **Scope types:** Every scope MUST declare its type via a `scope-type` field 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 MUST be valid independently. See `_core-adr-policy-010` rules 06–08 for the full multi-type grammar and naming constraints. The six built-in scope types and their definitions are:
     - `core` — see [`_core-adr-policy-011`](011-core-scope-type.md)
     - `reference` — see [`_core-adr-policy-012`](012-reference-scope-type.md)
     - `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)
+    - `compiled` — see [`_core-adr-policy-019`](019-compiled-scope-type.md)
   - 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. This ordering is the **default fallback** for conflict resolution between scopes: `extends:` declarations (Section D of `_core-adr-policy-010`) take precedence over it for policy document inheritance, and `follows:` declarations govern authoring governance rules independently. See `_core-adr-policy-010.36-root-index-ordering-fallback` for the full normative definition.
   - **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.
     - `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. MAY be a comma-separated list of types (e.g., `scope-type: compiled, internal-docs`). Each element MUST match a `{scope-type}-scope-type` policy in any `core`-type scope's `principles/` directory. See `_core-adr-policy-010` rules 06 and 07 for the full multi-type grammar and `_core-adr-policy-011`, `012`–`015` for built-in type definitions.
+    - `scope-type` (required): Scope classification type. MAY be a comma-separated list of types (e.g., `scope-type: compiled, internal-docs`). Each element MUST match a `{scope-type}-scope-type` policy in any `core`-type scope's `principles/` directory. See `_core-adr-policy-010` rules 06 and 07 for the full multi-type grammar and `_core-adr-policy-011`, `012`–`015`, and `019` 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.
     - `follows` (optional): Core scope names whose Policies apply as mandatory governance conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`). All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail.
-    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or initiatives) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail. When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Scopes referenced only via `extends:` chains (not entry scopes in the root index) are exempt from the root index link requirement. `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
+    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or initiatives) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail. When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Extended scopes are still linked in the root index; tag them `extends-only` to apply them only via `extends:` (see `_core-adr-policy-022.01-root-index-completeness`). `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
+    - `extends-only` (optional): See `_core-adr-policy-022.07-extends-only-field`.
     - `license` (optional): SPDX identifier for the scope's content license.
-    - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
 - **Subjects:** The subject folder MUST be chosen per [`_core-adr-policy-016`](016-policy-subjects.md), which defines allowed subjects, full descriptions, examples, and disambiguation tiebreakers.
 - **Policy numbering:** Numbers MUST be assigned within the subject-based block ranges defined in [`_core-adr-policy-017`](017-policy-numbering-ranges.md). Use the lowest available number within the block for the chosen subject. See [`_core-adr-policy-002-policy-standards.01-freeze-reference-exemption`](002-policy-standards.md) for exemptions.
 - MUST NOT use emojis
@@ -107,7 +108,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
     - Add links to related scope indexes that this scope might override or be overridden by (scopes listed last override earlier ones on the same topic).
     - Each XDRS element entry MUST include a short description. SHOULD use an imperative statement or the question it answers (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?"
-  - 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" followed by a note that `extends:` and `follows:` declarations in individual scope indexes take precedence over this ordering for their respective resolution concerns (see `_core-adr-policy-010.36-root-index-ordering-fallback`). 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)`).
+  - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`) exactly once (see `_core-adr-policy-022`). Add the text "XDRS scopes listed last override the ones listed first" followed by a note that `extends:` and `follows:` declarations in individual scope indexes take precedence over this ordering for their respective resolution concerns (see `_core-adr-policy-010.36-root-index-ordering-fallback`). 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`.

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

@@ -9,19 +9,20 @@ valid-from: 2026-07-01
 
 ## Context and Problem Statement
 
-XDRS provides three mechanisms that govern what content belongs in a scope and how it should be structured:
+XDRS provides four mechanisms that govern what content belongs in a scope and how it should be structured:
 
 1. **Scope-type standards**: a policy in a `core`-type scope that defines the rules for all scopes of that type.
 2. **`follows:` declarations**: a scope explicitly declares that it follows the standards of a named `core`-type scope.
 3. **Scope-local standards**: a policy inside a scope that defines content rules specific to that one scope.
+4. **`extends:` declarations**: a scope inherits another named scope's policy documents (Section D).
 
 ## Decision Outcome
 
 **Define scope types as policies, local meta-policies as `core`-named policies in `principles/`, and a clear precedence chain for governance application.**
 
-All scope types — both the five built-in types and any custom types — are defined using the same convention: a `{scope-type}-scope-type` policy in a `core`-type scope. Scope-local standards (called _local meta-policies_) are optional policies whose filename title starts with `core` and which are placed in the `principles` subject of the scope. Multiple local meta-policy files are allowed, each distinguished by an optional qualifier. Tools and agents apply all applicable standards in a defined order.
+All scope types — both the six built-in types and any custom types — are defined using the same convention: a `{scope-type}-scope-type` policy in a `core`-type scope. Scope-local standards (called _local meta-policies_) are optional policies whose filename title starts with `core` and which are placed in the `principles` subject of the scope. Multiple local meta-policy files are allowed, each distinguished by an optional qualifier. Tools and agents apply all applicable standards in a defined order.
 
-> **Choosing between a local meta-policy and a `-core` sibling scope**: use a local meta-policy when the standards apply only to one scope. Use a `-core` sibling scope (see `_core-adr-policy-011`) when the governance needs to be shared or governs a family of scopes.
+> **Local meta-policy vs. `-core` sibling scope**: use a local meta-policy for single-scope standards; use a `-core` sibling scope (`_core-adr-policy-011`) when governance is shared across a family of scopes.
 
 ### Details
 
@@ -82,7 +83,7 @@ A scope-type definition policy MAY declare a parent scope type by including a ru
 
 A `scope-type` value in a scope `index.md` is valid if and only if a policy file whose name ends with `{scope-type}-scope-type` exists in the `principles` subject of any `core`-type scope in the workspace. Tools (such as `xdrs-core lint`) MUST enforce this for every element when `scope-type` is an array.
 
-When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace, the scope MUST be treated as READ-ONLY: content MUST NOT be added, changed, removed, or reviewed. Tools MUST surface the read-only status and MUST NOT apply changes until the scope-type governance is installed.
+When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace or defined only in a `disabled` scope, the scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). Missing types are a lint error for local scopes.
 
 #### 11-def-scope-type-must-be-structured
 
@@ -90,7 +91,7 @@ All `{scope-type}-scope-type.md` policies (primary and companion files) MUST fol
 
 #### 12-def-core-scope-policies-must-be-structured
 
-All policy files in a `core`-type scope (a scope whose `index.md` declares `scope-type: core`) MUST follow the structured format defined in `_core-adr-policy-008` (see rule 11). This requirement applies to ALL policies in the scope, not only scope-type definitions or local meta-policies. The `_core` scope itself is exempt from this requirement until its existing policies are migrated. Tools MUST enforce this for all non-exempt core-type scopes and report an error using code `_core-adr-policy-010-scope-governance.12-def-core-scope-policies-must-be-structured`.
+All policy files in a `core`-type scope (a scope whose resolved scope-type chain, including parent types per rule 09, contains `core`) MUST follow the structured format defined in `_core-adr-policy-008` (see rule 11). This requirement applies to ALL policies in the scope, not only scope-type definitions or local meta-policies. The `_core` scope itself is exempt from this requirement until its existing policies are migrated. Tools MUST enforce this for all non-exempt core-type scopes and report an error using code `_core-adr-policy-010-scope-governance.12-def-core-scope-policies-must-be-structured`.
 
 ---
 
@@ -145,7 +146,7 @@ When adding or reviewing content in a scope, tools and agents MUST:
    a. Search `[type]/principles/` directories of all `core`-type scopes for the `{scope-type}-scope-type.md` primary file.
    b. If found, load the primary and all companion files (`{scope-type}-scope-type-{qualifier}.md`) from the **same directory**, in alphabetical qualifier order.
    c. If the primary contains a rule titled `NN-parent-scope-type`, extract the parent type name and repeat steps a–c. Detect and stop on cycles.
-3. Concatenate all resolved ancestor chains in declaration order to form a flat list (e.g., `scope-type: [reference, platform]` where `reference → standard`, `platform → core`: `[standard, reference, core, platform]`).
+3. Concatenate all resolved ancestor chains in declaration order to form a flat list (e.g., `scope-type: [reference, internal-docs]` where `reference → standard`, `internal-docs → standard`: `[standard, reference, standard, internal-docs]`).
 4. Deduplicate keeping the **first occurrence** of each type.
 5. Apply all policies from the deduplicated list as mandatory conventions. Later entries override earlier entries on same rule number conflicts (see rule 26-conflict-declarations).
 
@@ -188,7 +189,7 @@ A `## Conflicts` section MAY also document cross-scope-type incompatibilities fo
 
 ---
 
-**Section D — Scope extends**
+**Section D — Scope extends** (content-inheritance precedence, distinct from Section C's rule-authoring precedence)
 
 #### 27-extends-declaration
 
@@ -234,7 +235,7 @@ An undeclared conflict MUST be surfaced during review (see `_core-adr-policy-010
 
 #### 35-extends-index
 
-Scopes referenced only via `extends:` chains and not linked in the root `index.md` are **exempt** from the "root index must link all scopes" requirement. If a scope is both referenced via `extends:` AND linked in the root index, tools SHOULD warn of ambiguous dual precedence using warning code `_core-adr-policy-010.35-extends-index`.
+Scopes referenced via `extends:` MUST still be linked in the root `index.md` (see `_core-adr-policy-022.01-root-index-completeness`). Consumers SHOULD tag them `extends-only` when they must apply only through `extends:` chains (see `_core-adr-policy-022.04-extends-only`).
 
 ---
 
@@ -242,6 +243,6 @@ Scopes referenced only via `extends:` chains and not linked in the root `index.m
 
 #### 36-root-index-ordering-fallback
 
-The root `index.md` ordering ("scopes listed last override the ones listed first") is the **default fallback** for policy document conflict resolution. `extends:` takes precedence: when a scope explicitly `extends:` another, the `extends:` chain (Section D, rule 33) governs; root index ordering MUST NOT be used to resolve conflicts between those scopes. For all other scope pairs, agents and tools MUST treat the later-listed scope in the root `index.md` as providing the overriding policy.
+The root `index.md` ordering ("scopes listed last override the ones listed first") is the **default fallback** for policy document conflict resolution. `extends:` takes precedence: when a scope explicitly `extends:` another, the `extends:` chain (Section D, rule 33) governs; root index ordering MUST NOT be used to resolve conflicts between those scopes. For all other pairs of active scopes (not tagged `disabled` or `extends-only`, see `_core-adr-policy-022`), agents and tools MUST treat the later-listed scope in the root `index.md` as providing the overriding policy.
 
-`follows:` is independent of policy document conflict resolution. It governs authoring governance rules only (Section C, rule 24). Agents reading a single scope's `index.md` MUST also read the root `index.md` to determine conflict resolution order absent an `extends:` relationship.
+`follows:` does not affect policy document conflict resolution. Agents reading a scope's `index.md` MUST also read the root `index.md` to determine conflict order absent an `extends:` relationship.

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

@@ -65,12 +65,16 @@ A `core`-type scope MAY be distributed to consumers alongside the companion cons
 
 #### 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: content in it MUST NOT 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.
+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 or tagged `disabled` in the root index, the companion scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`): content in it MUST NOT 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`).
 
+#### 10-no-type-combination
+
+A scope is core-type when its resolved scope-type chain, including parent types (see `_core-adr-policy-010.09-def-parent-scope-type`), contains `core`. A core-type scope MUST declare exactly one scope type; combining a core-type with any other type (e.g., `scope-type: core, standard`) is a lint error. Core-type scopes hold meta governance only, so mixing them with consumable types would blur rules 04 and 05.
+
 ## References
 
 - [_core-adr-policy-010 - Scope governance](010-scope-governance.md) — full scope governance model including when to prefer a local meta-policy (`NNN-core.md` in `principles/`) vs. this pattern

package/.xdrs/_core/adrs/principles/019-compiled-scope-type.md

@@ -23,7 +23,7 @@ How should a scope that exists solely as a compiled representation of external s
 
 #### 01-scope-type-name
 
-The scope type defined by this policy is `compiled`. A scope MUST declare it by setting `scope-type: compiled` in its `index.md` YAML frontmatter. The `compiled` type MAY be combined with one or more other scope types using a comma-separated list (e.g., `scope-type: compiled, reference`).
+The scope type defined by this policy is `compiled`. A scope MUST declare it by setting `scope-type: compiled` in its `index.md` YAML frontmatter. The `compiled` type MAY be combined with one or more other scope types except core-type ones (see `_core-adr-policy-011.10-no-type-combination`) using a comma-separated list (e.g., `scope-type: compiled, reference`).
 
 #### 02-when-to-use
 
@@ -62,12 +62,13 @@ When multiple source entries point to the same content (e.g., a web page and its
 
 #### 07-compilation-meta-policy
 
-Before any compilation begins, at least one local meta-policy file named `NNN-core.md` MUST exist in a `[type]/principles/` directory of the target scope (e.g., `adrs/principles/001-core.md`). Compilation tools and agents MUST scan all type folders (`adrs`, `bdrs`, `edrs`) for such meta-policy files; each meta-policy governs compilation for its own type folder.
+Before any compilation begins, at least one local meta-policy file named `NNN-core.md` MUST exist in a `[type]/principles/` directory of the target scope (e.g., `adrs/principles/001-core.md`). Compilation tools and agents MUST scan all type folders (`adrs`, `bdrs`, `edrs`) for such meta-policy files; each meta-policy governs compilation for its own type folder, including every subject compiled under it.
 
 The meta-policy MUST contain the following sections:
 
-- `## Sources` — one bullet per source using the format `- [web] https://...`, `- [git] git@...`, or `- [local] ./path`. Each source entry MAY include an inline description after the URL.
+- `## Sources` — one bullet per source using the format `- [web] name: https://...`, `- [git] name: git@...`, or `- [local] name: ./path`. `name` MUST be a lowercase kebab-case slug (`[a-z0-9-]+`) that meaningfully identifies the source's organisation, project, or content (e.g., `github-official-docs`, `spreadsheet-team-123`). It is used as the folder name under `.assets/sources/` (rule 12) and as the path prefix in `## Source` sections (rule 10). Multiple bullets MAY share the same `name` to list alternate access methods for the same logical source — the preference order in rule 06 picks which one is actually fetched. Each source entry MAY include an inline description after the URL.
 - `## Selectors` — describes which portions of the fetched source to include or exclude, expressed as document sections, filename patterns, topics, or other criteria.
+- `## Sync Settings` — governs re-synchronisation behaviour (rule 13). MUST contain a `Source re-sync period days: N` bullet, where `N` is a positive integer number of days. MAY contain a `Source storage: temporary` bullet; when absent, source storage defaults to persistent (rule 12).
 
 The meta-policy MAY also contain:
 
@@ -85,15 +86,15 @@ There is no fixed position for `compiled`-type scopes in the root `index.md`. Wh
 
 #### 10-source-section
 
-Every compiled policy MUST include a `## Source` section placed after the `## References` section (or after `## Decision Outcome` when no `## References` section is present). The section MUST list the relative file path(s) of the source document(s) used to produce the policy as plain text. Paths MUST NOT be written as markdown links, because the source files exist only inside a temporary local directory that is created during the compilation or review process.
+Every compiled policy MUST include a `## Source` section placed after the `## References` section (or after `## Decision Outcome` when no `## References` section is present). The section MUST list the relative file path(s) of the source document(s) used to produce the policy as plain text, relative to the scope's `.assets/sources/` directory. Paths MUST NOT be written as markdown links: when source storage is temporary, the paths only exist for the duration of the compilation or review process; when source storage is persistent, `.assets/sources/` is exempt from orphan-asset tracking and, per rule 14, MUST NOT be linked to directly — these paths identify compilation inputs, not navigable or citable XDRS resources.
 
 Example:
 
 ```
 ## Source
 
-- source-1/standards/owasp-top-10-2021/A01-broken-access-control.md
-- source-2/docs/security-controls.html
+- owasp-top10/standards/owasp-top-10-2021/A01-broken-access-control.md
+- security-controls-docs/docs/security-controls.html
 ```
 
 #### 11-compilation-notes
@@ -109,6 +110,37 @@ All access control implementations MUST enforce the principle of least privilege
 **compilation-note:** derived from OWASP A01:2021 "How to Prevent", bullet 3 — "Deny by default".
 ```
 
+#### 12-source-storage-and-tracking
+
+Unless a meta-policy declares `Source storage: temporary`, fetched and selected source content (rule 13) MUST be persisted under `[type]/principles/.assets/sources/[name]/`, sibling to the governing meta-policy, where `[name]` is the source's slug from its `## Sources` bullet. This location is shared across every subject compiled under that meta-policy's type folder; it is not duplicated per subject. Persisted source content MUST be committed to version control and MUST NOT be gitignored.
+
+When `Source storage: temporary` is declared, bulk fetched content MUST instead be written only to the ephemeral compilation working directory and removed at the end of the compilation run.
+
+Regardless of storage mode, a tracking file `.assets/sources/[name]/source.md` MUST always be created and kept up to date, with the following format:
+
+```
+# Source
+
+last-fetch-timestamp: YYYY-MM-DD HH:MM:SS
+last-compilation-timestamp: YYYY-MM-DD HH:MM:SS
+```
+
+`last-fetch-timestamp` MUST be updated whenever that source is freshly fetched. `last-compilation-timestamp` MUST be updated only after a compilation cycle consuming that source completes lint and review successfully. If a meta-policy's `Source storage` setting changes between compilation runs, the next compilation MUST reconcile storage accordingly: switching to `temporary` MUST remove any previously persisted bulk content under `.assets/sources/[name]/` while keeping `source.md`; switching away from `temporary` MUST resume persisting bulk content going forward.
+
+#### 13-selective-persistence-and-resync-optimization
+
+Only content matched by `## Selectors` and actually used by at least one compiled policy's `## Source` section MAY be written to `.assets/sources/[name]/`. Content excluded by selectors, or that becomes unused after a re-sync, MUST be removed from persisted storage — `.assets/sources/[name]/` MUST NOT accumulate content beyond what compiled policies currently depend on.
+
+Before fetching, compilation tools and agents MUST evaluate whether a re-sync is necessary: compare the elapsed days since `last-fetch-timestamp` against `Source re-sync period days`, and confirm `last-compilation-timestamp` is not older than `last-fetch-timestamp`. If every source governed by a meta-policy is within its re-sync period and already fully compiled, no fetch or recompilation is required unless explicitly requested. When a re-sync does proceed, newly fetched and selected content MUST be compared against the previous `.assets/sources/[name]/` snapshot (for example, by content hash) to scope which existing compiled policies need re-verification and which can be kept unchanged.
+
+#### 14-source-documents-not-authoritative
+
+By default, content persisted under `.assets/sources/` MUST NOT be treated as a source of truth, cited, or used directly to make architectural, business, or engineering decisions. Only compiled policies — the numbered Policy documents produced from this content — are authoritative for decision-making. Content under `.assets/sources/` exists to support synchronisation, diffing, and recompilation (rules 12 and 13); it is unstructured relative to compiled policies and MAY be misleading, inconsistent, or outdated.
+
+An exception MUST be documented in a dedicated `[type]/principles/NNN-direct-source-usage.md` policy, mirroring the dedicated-file convention of rule 08. That policy MUST explicitly state when and how direct use of source documents is permitted. Absent such a policy, direct use of source documents for decisions is forbidden.
+
+This rule governs reasoning and usage, not the document-link graph. Independently of this rule, and regardless of whether a `NNN-direct-source-usage.md` policy exists, no document MAY hyperlink directly into `.assets/sources/`; that restriction is enforced mechanically and addresses a separate, structural concern.
+
 ## References
 
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) — numbered rule format required for all policies in compiled scopes

package/.xdrs/_core/adrs/principles/022-scope-activation.md

@@ -0,0 +1,69 @@
+---
+name: _core-adr-policy-022-scope-activation
+description: Defines how installed scopes are listed in the root index, how consumers activate, narrow, or disable them with activation tags, and when a scope becomes read-only because a dependency is missing, disabled, or invalid.
+apply-to: All XDRS workspaces, scope authors, consumers, tools, and agents
+valid-from: 2026-07-20
+---
+
+# _core-adr-policy-022: Scope activation
+
+## Context and Problem Statement
+
+Packages install scope folders into a workspace, but nothing guaranteed that every installed scope was listed in the root `index.md`. Scopes that were meant to be reused only through `extends:` were hidden from the root index, so agents could not discover them, and consumers had no way to switch off a scope they installed but did not want to apply. When a scope depended on another scope that was absent, the result was either a hard lint error or silent misbehaviour.
+
+How does a consumer control which installed scopes apply globally, which apply only through `extends:`, and which are ignored, while keeping every scope discoverable?
+
+## Decision Outcome
+
+**Every installed scope is listed once in the root index; the consumer controls activation with an inline activation tag next to the scope link, and the scope author declares intent with an `extends-only` frontmatter field that lint checks for coherence.**
+
+Policies of listed scopes apply globally by default. An activation tag narrows a scope to `extends-only` or turns it off with `disabled`. Agents rely only on the tags. Scopes whose dependencies are missing, disabled, or invalid become read-only.
+
+### Details
+
+#### 01-root-index-completeness
+
+Every scope folder under the XDRS root that contains an `index.md`, including scopes installed from external packages, MUST be linked exactly once from the root `index.md`. The `_local` scope MUST NOT be linked (see `_core-adr-policy-001`). A scope folder with no link, or a scope linked more than once, is a lint error. Links that resolve to the same scope index (e.g. `./x/index.md` and `x/index.md`) count as the same link. Links inside fenced code blocks are ignored.
+
+#### 02-global-applicability
+
+Policies of a listed scope without an activation tag MUST be applied globally, narrowed by the scope `apply-to` and each policy `apply-to`. Meta-policies (local meta-policies, scope-type definition policies) and all content of core-type scopes are never applied globally; they govern authoring only (see `_core-adr-policy-010` Sections B and C). `_core` always applies globally.
+
+#### 03-activation-tag-syntax
+
+An activation tag is an inline code span placed immediately after a scope link on the same line, optionally separated by spaces or tabs, for example a link to `payments-ref/index.md` followed by `` `extends-only` ``. Allowed values are `extends-only` and `disabled`, lowercase only. A scope link line MUST NOT contain any other inline code: an unknown value, a second tag, or inline code placed elsewhere on the line is a lint error. A tag on the next line is not a tag. `_core` MUST NOT be tagged.
+
+#### 04-extends-only
+
+Policies of a scope tagged `extends-only` MUST be applied only through the `extends:` chain of an active scope (untagged, including read-only scopes, or `_local`). Reach is transitive: if A extends B and B extends C, both B and C apply to A. The root index position of a tagged scope never matters for conflict resolution; `extends:` precedence applies (see `_core-adr-policy-010.33-extends-content-precedence`). Skills, articles, research, and initiatives of the scope remain usable. Tools SHOULD warn when no active scope reaches an `extends-only` scope; reach only through a `disabled` scope does not count.
+
+#### 05-disabled
+
+All content of a scope tagged `disabled` MUST be ignored by agents: its policies, skills, articles, research, and initiatives are not applied, and nothing is inherited from it through `extends:` or `follows:`. The scope is still linted and MAY be edited. Skills of a disabled scope that are symlinked into `.agents/skills` (see `_core-adr-policy-018`) stay loaded by tools and MUST be removed by the consumer.
+
+#### 06-read-only-dependencies
+
+A scope MUST be treated as READ-ONLY when a scope it follows or extends, or the scope that defines one of its scope types (including parent types), is missing, disabled, or invalid, or when it is an external scope and its own `index.md` is invalid. Content in a READ-ONLY scope MUST NOT be added, changed, or removed. For local scopes, missing dependencies and invalid indexes remain lint errors (see `_core-adr-policy-010.32-extends-mandatory-presence`); a disabled dependency only makes the scope read-only. Tools MUST report each cause and how to fix it, citing this rule.
+
+#### 07-extends-only-field
+
+A scope author MAY declare `extends-only: true` or `extends-only: false` in the scope index frontmatter. Only unquoted lowercase `true` and `false` are valid. An invalid value is a lint error in a local scope; in an external scope it makes the scope read-only and the value is treated as absent. `extends-only` (field `true` or tag) on `_core`, `_local`, or a core-type scope is a lint error. Coherence: when the field is `true`, the root index link MUST carry the tag `extends-only` or `disabled`; when the field is `false` or absent, the consumer MAY add either tag (narrowing), and MUST NOT widen a scope beyond what the author declared. The field is a lint aid only.
+
+#### 08-agent-resolution
+
+Agents MUST decide activation only from the root index tags, never from the `extends-only` field:
+
+1. Skip scopes tagged `disabled`.
+2. Apply scopes tagged `extends-only` only through the `extends:` chain of an active scope.
+3. Apply all other listed scopes per rule 02.
+4. Never edit READ-ONLY scopes (rule 06).
+
+#### 09-root-index-ownership
+
+The root `index.md` is owned by the consumer. Packages that ship a root index SHOULD install it without overwriting an existing file, so activation tags survive reinstalls. When any activation tag is used, the root index MUST contain this exact legend line: "Scopes tagged `disabled` MUST be ignored; `extends-only` scopes apply only via extends (see _core-adr-policy-022)".
+
+## References
+
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) — root index and scope index frontmatter
+- [_core-adr-policy-010 - Scope governance](010-scope-governance.md) — `extends:` (Section D) and root index ordering (Section E)
+- [_core-adr-policy-011 - core scope type](011-core-scope-type.md) — core-type scopes and read-only companions

package/.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md

@@ -10,6 +10,7 @@ Read the confirmed scope's `index.md` frontmatter and perform ALL of the followi
 
 - **Follows scopes:** If the scope declares `follows:` entries (e.g., `follows: myarea-core, shared-standards`), verify that each listed scope directory exists in the workspace AND contains an accessible `index.md` (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing or unreadable, output: `FAIL — Cannot proceed: scope \`[scope-name]\` is listed in \`follows\` but its policies are not present in the workspace. Install it before authoring documents in this scope, as the governance constraints cannot be verified.`
 - **Extends scopes:** If the scope declares `extends:` entries, verify that each listed scope directory exists in the workspace AND contains an accessible `index.md`. If any listed scope is missing or unreadable, output: `FAIL — Cannot proceed: scope \`[scope-name]\` is listed in \`extends\` but its policies are not present in the workspace. Install it before authoring documents in this scope, as inherited policies cannot be verified.`
+- **Activation and read-only:** Read the root `index.md`. If a scope listed in `follows:` or `extends:`, or the scope defining one of its scope types, is tagged `disabled`, output: `FAIL — Cannot proceed: scope \`[scope-name]\` depends on disabled scope \`[dependency]\` and is READ-ONLY (see _core-adr-policy-022.06-read-only-dependencies). Enable it in the root index or remove the reference.`
 - **Local meta-policies:** Scan the target scope's `[type]/principles/` directories for all files whose filename title starts with `core` (i.e., `NNN-core.md` or `NNN-core-{qualifier}.md`), excluding scope-type definition files. If any are found but cannot be read, output: `FAIL — Cannot proceed: local meta-policy \`[filename]\` exists in scope \`[scope-name]\` but could not be read. Without it, the [DOCUMENT TYPE] cannot be authored in full compliance with the scope's governance.` Zero matches is valid.
 - **Scope-type:** Read the scope's `scope-type` from its `index.md`. Normalise the value to a list: split on commas and trim whitespace (`scope-type: typeA, typeB` becomes `[typeA, typeB]`). For **each** type in the list, search the `[type]/principles/` directories of all `core`-type scopes in the workspace for a file whose name ends with `{scope-type}-scope-type.md`. If the scope declares any `scope-type` elements but no matching file is found for ANY of them, output: `FAIL — Cannot proceed: scope \`[scope-name]\` declares \`scope-type: [scope-type]\` but no \`[scope-type]-scope-type.md\` policy exists in any \`core\`-type scope in the workspace. The scope is READ-ONLY; install the scope-type governance before authoring documents in this scope.`
 - **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer MUST be present before writing begins.

package/.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md

@@ -25,7 +25,7 @@ Determine the appropriate scope-type by matching the content being authored to o
 
 ## Step C — Enumerate and Rank Workspace Scopes
 
-1. Read `.xdrs/index.md` to list all declared scopes.
+1. Read `.xdrs/index.md` to list all declared scopes. Exclude scopes tagged `disabled` or `extends-only` (see `_core-adr-policy-022`) unless the user names them explicitly.
 2. For each scope whose `scope-type` matches the type identified in Step A or B (match if ANY of a scope's declared types fit), read its `index.md` and assess the following signals, in order of weight:
    - **Primary**: Does `apply-to` or `description` describe a domain that covers this content?
    - **Secondary**: Does the scope's `follows:` chain declare a governance relationship relevant to this content area?

package/.xdrs/_core/adrs/principles/skills/compile-scope/SKILL.md

@@ -10,7 +10,7 @@ metadata:
 
 ## Overview
 
-Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, fetches sources into a temporary directory, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). Requires `_core-adr-policy-019-compiled-scope-type` to be present in the workspace.
+Performs a full compilation cycle for any scope declaring `scope-type: compiled`: discovers compilation meta-policies across all type folders, checks whether each governed source is already in sync before doing any work, fetches due sources into a temporary staging directory, plans which policies to create, update, or remove, migrates them one at a time with full source traceability, runs lint and review, persists selected source content and updates sync tracking, and documents any inconsistencies found in the source. Works for both initial compilation and re-compilation (updates). By default, fetched source content used to compile policies is persisted under `.assets/sources/[name]/` in the scope (see `_core-adr-policy-019` rules 12–13); this content is never authoritative for decisions (rule 14). Requires `_core-adr-policy-019-compiled-scope-type` to be present in the workspace.
 
 ### Inputs
 
@@ -20,13 +20,13 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 
 #### Optional
 
-- None.
+- Force-refetch flag to bypass the re-sync short-circuit.
 
 ### Outputs
 
 #### Contents
 
-- Updated compiled scope, linted and reviewed.
+- Updated compiled scope, or a no-op already-in-sync report.
 
 #### Changes
 
@@ -56,39 +56,51 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 2. Scan ALL type folders (`adrs/`, `bdrs/`, `edrs/`) inside the target scope for local meta-policy files whose filename matches `NNN-core.md` in `[type]/principles/`. Collect every match.
 3. If no meta-policy is found in any type folder, output: `FAIL — Compilation cannot proceed: no local meta-policy NNN-core.md found in any [type]/principles/ folder of [scope-name]. Create it first with ## Sources and ## Selectors sections per _core-adr-policy-019 rule 07.`
 4. Read every found meta-policy fully. For each, extract:
-   - **Sources**: parse all `- [web] ...`, `- [git] ...`, `- [local] ...` bullet entries from the `## Sources` section.
-   - **Selectors**: read the `## Selectors` section content (used in Phase 2).
-   - **Fetch Procedures**: read the `## Fetch Procedures` section if present (used in Phase 1).
-   - **Compilation Notes**: read if present (used in Phase 2–3).
-   - **Review Notes**: read if present (used in Phase 6).
-
-### Phase 1: Fetch Sources
-
-1. Create a temporary directory `.tmp/compilation-[YYYYMMDDHHMMSS]/` in the workspace root.
-2. For each source discovered in Phase 0, fetch in the following preference order (first available wins; if all equivalent URLs are listed, try each in order):
-   - **Git URL** (`- [git] ...`): run `git clone --depth=1 [url] .tmp/compilation-[ts]/source-N/`. If `git` is not available or the clone fails, fall back to the next option.
-   - **Local folder** (`- [local] ...`): copy the folder contents to `.tmp/compilation-[ts]/source-N/`.
-   - **Web URL** (`- [web] ...`): before scraping, search the workspace for a skill specialized in fetching content from this URL or website domain (e.g., a skill whose description or name references the domain, the product, or the content type). Some websites require special handling — SSO, client certificates, shadow DOM, iframes, CAPTCHAs, or other quirks. If a specialized fetch skill is found, follow it to retrieve the content. If no specialized skill exists, fall back to `npx --package=@playwright/cli@latest playwright-cli`; run with `--help` to confirm available commands and save output as `.html` file(s) in `.tmp/compilation-[ts]/source-N/`.
+   - **Sources**: parse all `- [web] ...`, `- [git] ...`, `- [local] ...` bullet entries from the `## Sources` section, including each source's `name` slug (per `_core-adr-policy-019` rule 07).
+   - **Selectors**: read the `## Selectors` section content (used in Phase 3).
+   - **Sync Settings**: parse `Source re-sync period days` and, if present, `Source storage: temporary` from the `## Sync Settings` section (used in Phase 1 and Phase 9).
+   - **Fetch Procedures**: read the `## Fetch Procedures` section if present (used in Phase 2).
+   - **Compilation Notes**: read if present (used in Phase 3–4).
+   - **Review Notes**: read if present (used in Phase 7).
+
+### Phase 1: Check Sync Necessity
+
+1. For each source `name` extracted in Phase 0, look for `.assets/sources/[name]/source.md` in the governed type folder.
+2. If `source.md` does not exist for a source, that source has never been synced — it is due for Phase 2.
+3. If `source.md` exists, read its `last-fetch-timestamp` and `last-compilation-timestamp`. Compute the elapsed days since `last-fetch-timestamp`. That source is due for Phase 2 if either is true: the elapsed days exceed the meta-policy's `Source re-sync period days`, or `last-compilation-timestamp` is older than `last-fetch-timestamp` (a previous run fetched but never finished compiling).
+4. If the input includes an explicit force-refetch/recompile request (see Inputs > Optional), treat every source as due regardless of timestamps.
+5. If no source across any governed meta-policy is due, output: `OK — [scope-name] is already in sync. No action taken.` and halt — do not proceed to later phases.
+6. Otherwise, proceed to Phase 2, but scope fetching and compilation to only the meta-policies and sources that are due; meta-policies with no due sources MAY be skipped entirely.
+
+### Phase 2: Fetch Sources
+
+1. Create a temporary directory `.tmp/compilation-[YYYYMMDDHHMMSS]/staging/` in the workspace root.
+2. For each due source (from Phase 1), fetch in the following preference order (first available wins; if all equivalent URLs are listed, try each in order):
+   - **Git URL** (`- [git] ...`): run `git clone --depth=1 [url] .tmp/compilation-[ts]/staging/[name]/`. If `git` is not available or the clone fails, fall back to the next option.
+   - **Local folder** (`- [local] ...`): copy the folder contents to `.tmp/compilation-[ts]/staging/[name]/`.
+   - **Web URL** (`- [web] ...`): before scraping, search the workspace for a skill specialized in fetching content from this URL or website domain (e.g., a skill whose description or name references the domain, the product, or the content type). Some websites require special handling — SSO, client certificates, shadow DOM, iframes, CAPTCHAs, or other quirks. If a specialized fetch skill is found, follow it to retrieve the content. If no specialized skill exists, fall back to `npx --package=@playwright/cli@latest playwright-cli`; run with `--help` to confirm available commands and save output as `.html` file(s) in `.tmp/compilation-[ts]/staging/[name]/`.
 3. If any source cannot be fetched via any listed option, report the failure and continue with remaining sources. Do not abort the entire compilation for a single failed source.
-4. Convert non-markdown documents found in the fetched source directories. Use only the format converters actually needed:
+4. Immediately after a source is fetched successfully, create `.assets/sources/[name]/source.md` if absent and update its `last-fetch-timestamp` to the current time — this happens regardless of the `Source storage` setting, since the tracking file always persists per `_core-adr-policy-019` rule 12.
+5. Convert non-markdown documents found in the fetched source directories. Use only the format converters actually needed:
    - PDF files: `uvx markitdown[pdf] <file> -o <output>.md`
    - XLSX files: `uvx markitdown[xlsx] <file> -o <output>.md`
    - DOCX files: `uvx markitdown[docx] <file> -o <output>.md`
    - PPTX files: `uvx markitdown[pptx] <file> -o <output>.md`
    - HTML files saved from web scraping: `uvx markitdown <file.html> -o <output>.md`
 
-### Phase 2: Plan Policies
+### Phase 3: Plan Policies
 
-1. For each type folder governed by a meta-policy (from Phase 0), apply the `## Selectors` rules to the fetched content to determine which portions to include.
+1. For each type folder governed by a meta-policy (from Phase 0), apply the `## Selectors` rules to the fetched staging content to determine which portions to include.
 2. List all existing policies in the scope under each governed type folder.
-3. Analyse the selected content and produce a TODO list showing for each expected policy:
+3. If `.assets/sources/[name]/` already holds a previous persisted snapshot, diff the newly selected staging content against it (for example, by content hash per file) to pre-seed which policies are likely unaffected.
+4. Analyse the selected content and produce a TODO list showing for each expected policy:
    - **CREATE** — new policy to be compiled from source (does not yet exist in scope)
    - **UPDATE** — existing policy whose source content has changed
    - **REMOVE** — existing policy whose source content no longer exists or is excluded by selectors
-   - **KEEP** — existing policy that is up to date; no action needed
-4. Present the TODO list to the user and wait for confirmation before proceeding to Phase 3.
+   - **KEEP** — existing policy that is up to date; no action needed (default for policies whose source content is unchanged per the step 3 diff)
+5. Present the TODO list to the user and wait for confirmation before proceeding to Phase 4.
 
-### Phase 3: Migrate Policies (one at a time)
+### Phase 4: Migrate Policies (one at a time)
 
 For each TODO item marked CREATE or UPDATE, in sequence:
 
@@ -99,21 +111,21 @@ For each TODO item marked CREATE or UPDATE, in sequence:
 
 2. **Add a `**compilation-note:**` marker** inside a rule body only when the mapping from source to rule is not obvious — for example: indirect references, conclusions drawn by connecting multiple source sections, interpretations that required judgment, or cases where the same source passage could be read differently. Do NOT add a marker when the rule is a direct, literal transcription of a single source statement. Place the marker as a new sentence at the end of the rule body. Example:
    ```
-   All API keys MUST be rotated every 90 days. **compilation-note:** derived from [source-1/security/api-guidelines.md section 4.2] — "Keys should be invalidated and replaced quarterly"; frequency inferred as 90 days from the term "quarterly".
+   All API keys MUST be rotated every 90 days. **compilation-note:** derived from [api-guidelines/security/api-guidelines.md section 4.2] — "Keys should be invalidated and replaced quarterly"; frequency inferred as 90 days from the term "quarterly".
    ```
 
-3. **Add a `## Source` section** as the LAST section of the policy (after `## References` if present, otherwise after `## Decision Outcome`). List the relative file path(s) of the source document(s) as plain text — NOT as markdown links. Paths are relative to the temporary source directory (e.g., `source-1/docs/chapter-3.md`).
+3. **Add a `## Source` section** as the LAST section of the policy (after `## References` if present, otherwise after `## Decision Outcome`). List the relative file path(s) of the source document(s) as plain text — NOT as markdown links. Paths are relative to `.assets/sources/` and use the source's `name` slug as their first segment (e.g., `api-guidelines/standards/section-4/api-security.md`), regardless of whether storage is currently persistent or temporary.
    ```
    ## Source
 
-   - source-1/standards/section-4/api-security.md
+   - api-guidelines/standards/section-4/api-security.md
    ```
 
 4. For REMOVE items: delete the policy file and remove its entry from the type's `index.md`.
 
-5. Note any content in the source that is inconsistent, contradictory, or cannot be faithfully expressed as a valid XDRS policy. Record these for Phase 7.
+5. Note any content in the source that is inconsistent, contradictory, or cannot be faithfully expressed as a valid XDRS policy. Record these for Phase 8.
 
-### Phase 4: Verify Each Policy
+### Phase 5: Verify Each Policy
 
 After writing each policy:
 
@@ -121,25 +133,25 @@ After writing each policy:
 2. Confirm the policy uses structured numbered rule blocks (`_core-adr-policy-008`).
 3. Confirm `**compilation-note:**` markers are present for every rule whose mapping from source is non-obvious (indirect references, multi-source conclusions, interpretations requiring judgment). Direct literal transcriptions do not require a marker.
 4. Confirm no normative statements are present that cannot be traced to the listed source file.
-5. Add any new inconsistencies found to the list for Phase 7.
+5. Add any new inconsistencies found to the list for Phase 8.
 
-### Phase 5: Lint
+### Phase 6: Lint
 
 1. Run `npx xdrs-core lint` from the workspace root (or `make lint` if a `Makefile` is present with a `lint` target).
 2. Review all reported errors and warnings.
 3. Fix only mechanical and structural errors (missing required frontmatter fields, naming violations, index link mismatches). Do NOT invent content to satisfy content-level findings.
 4. Re-run lint after fixes until it passes or only unfixable findings remain.
 
-### Phase 6: Review
+### Phase 7: Review
 
 1. Read and follow `.xdrs/_core/adrs/principles/skills/review/SKILL.md` fully, scoped to the compiled scope.
 2. Apply any review notes from the meta-policy's `## Review Notes` section as additional mandatory conventions during this review.
 3. Fix only mechanical and structural findings from the review. Do NOT invent content to resolve content-level findings.
-4. Any review findings that require inventing or guessing content MUST be recorded as inconsistencies in Phase 7.
+4. Any review findings that require inventing or guessing content MUST be recorded as inconsistencies in Phase 8.
 
-### Phase 7: Document Inconsistencies
+### Phase 8: Document Inconsistencies
 
-1. Collect all inconsistencies noted during Phases 3, 4, and 6.
+1. Collect all inconsistencies noted during Phases 4, 5, and 7.
 2. If any inconsistencies exist:
    - Determine the next available policy number in the `001–100` principles block for the relevant type folder.
    - Create or update `[type]/principles/NNN-inconsistencies-from-source.md` in the scope.
@@ -148,25 +160,51 @@ After writing each policy:
    - Do NOT propose or include fixes.
 3. If no inconsistencies exist, report that the compilation is clean.
 
-### Phase 8: Cleanup
+### Phase 9: Persist Sources and Update Tracking
 
-1. Remove the temporary directory `.tmp/compilation-[ts]/` created in Phase 1.
+1. For each meta-policy and source processed in this run, check its `Source storage` setting.
+2. If storage is persistent (the default): replace the contents of `.assets/sources/[name]/` (excluding `source.md`) with the staged content actually selected and used in Phase 3–4 — remove any previously persisted file that is no longer selected or used, per `_core-adr-policy-019` rule 13.
+3. If storage is `temporary`: do not copy any bulk staged content into `.assets/sources/[name]/`; only `source.md` lives there.
+4. For every source processed in this run, update `.assets/sources/[name]/source.md`'s `last-compilation-timestamp` to the current time — this step only runs after Phase 6 (Lint) and Phase 7 (Review) both pass for the policies depending on that source.
+5. If a source's `Source storage` setting changed since its last run, reconcile per `_core-adr-policy-019` rule 12: switching to `temporary` removes previously persisted bulk content (keeping `source.md`); switching away from `temporary` begins persisting bulk content from this run onward.
+
+### Phase 10: Cleanup
+
+1. Remove the temporary staging directory `.tmp/compilation-[ts]/` created in Phase 2. Never remove or modify persisted content under `.assets/sources/` — that is governed solely by Phase 9.
 2. Report a compilation summary:
    - Policies created, updated, removed.
    - Inconsistencies documented (with file path).
    - Any sources that could not be fetched.
    - Lint and review pass/fail status.
+   - Sources persisted, kept temporary, or skipped as already in sync.
 
 ## Anti-Patterns
 
 - **Mistake:** Inventing content to fill gaps when source material is incomplete or ambiguous.
   **Why it happens:** The agent wants to produce a "complete" policy and fills gaps with plausible-sounding text.
-  **Instead:** Transcribe faithfully, preserve ambiguities as-is, and record inconsistencies in Phase 7 instead of guessing.
+  **Instead:** Transcribe faithfully, preserve ambiguities as-is, and record inconsistencies in Phase 8 instead of guessing.
 
-- **Mistake:** Skipping the Phase 2 confirmation and migrating policies before the user approves the CREATE/UPDATE/REMOVE plan.
+- **Mistake:** Skipping the Phase 3 confirmation and migrating policies before the user approves the CREATE/UPDATE/REMOVE plan.
   **Why it happens:** Momentum from prior compilations makes the plan feel obviously correct.
-  **Instead:** Always present the TODO list and wait for explicit confirmation before Phase 3.
+  **Instead:** Always present the TODO list and wait for explicit confirmation before Phase 4.
 
 - **Mistake:** Leaving the temporary `.tmp/compilation-[ts]/` directory behind after a run.
-  **Why it happens:** Phase 8 cleanup is easy to forget once the summary is reported.
-  **Instead:** Always remove the temporary directory as the first Phase 8 step, even on partial failures.
+  **Why it happens:** Phase 10 cleanup is easy to forget once the summary is reported.
+  **Instead:** Always remove the temporary directory as the first Phase 10 step, even on partial failures.
+
+- **Mistake:** Persisting every fetched file under `.assets/sources/[name]/`, including content excluded by selectors or no longer used by any compiled policy.
+  **Why it happens:** It feels safer to keep everything "just in case" rather than compute what is actually still used.
+  **Instead:** Persist only Selector-matched content actually referenced by a compiled policy's `## Source` section, per `_core-adr-policy-019` rule 13; remove the rest during Phase 9.
+
+- **Mistake:** Skipping Phase 1 and always re-fetching and recompiling, even when every source is well within its re-sync period.
+  **Why it happens:** Re-running the full cycle unconditionally feels more thorough or "safe".
+  **Instead:** Always check `.assets/sources/[name]/source.md` timestamps against `Source re-sync period days` first, and short-circuit with a no-op report when nothing is due.
+
+- **Mistake:** Reading or citing content under `.assets/sources/` as if it were an authoritative policy, or adding a markdown link to it from another document.
+  **Why it happens:** The raw source content is readily available and often more detailed than the compiled policy.
+  **Instead:** Treat only compiled policies as authoritative per `_core-adr-policy-019` rule 14; source content exists solely to support fetch/diff/recompilation, and linking to it is also forbidden mechanically by lint.
+
+## References
+
+- [_core-adr-policy-019 - Compiled scope type](../../019-compiled-scope-type.md)
+- [_core-adr-policy-008 - Policy structured standards](../../008-policy-structured-standards.md)

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

@@ -66,6 +66,7 @@ Performs a structured review of code changes or files against the Policies in th
 2. **Prerequisites gate — MUST complete before any review work:** For each scope containing files under review, read its `index.md` frontmatter and check for `follows` and `extends` fields. `_core` Policies always apply to all scopes. Perform ALL of the following checks before proceeding; if ANY check fails, output a FAIL result immediately and do not continue the review:
    - **Follows scopes:** If the scope declares `follows:` entries (e.g., `follows: myarea-core, shared-standards`), verify that each listed scope directory exists in the workspace AND contains an accessible `index.md` (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing or its index is unreadable, output: `FAIL — Review cannot proceed: scope \`[scope-name]\` is listed in \`follows\` but its policies are not present in the workspace. Install it before reviewing, as compliance with its governance cannot be verified.`
    - **Extends scopes:** If the scope declares `extends:` entries, verify that each listed scope directory exists in the workspace AND contains an accessible `index.md`. If any listed scope is missing or its index is unreadable, output: `FAIL — Review cannot proceed: scope \`[scope-name]\` is listed in \`extends\` but its policies are not present in the workspace. Install it before reviewing, as inherited policies cannot be verified.`
+   - **Activation tags:** Read the root `index.md`. Do not apply policies of scopes tagged `disabled`, and apply scopes tagged `extends-only` only through the `extends:` chain of the reviewed scope (see `_core-adr-policy-022.08-agent-resolution`). If a `follows:`/`extends:` dependency or a scope-type-defining scope is tagged `disabled`, the reviewed scope is READ-ONLY (`_core-adr-policy-022.06-read-only-dependencies`): report it and do not propose fixes inside it.
    - **Local meta-policies:** Scan the scope's `[type]/principles/` directories for all files whose filename title starts with `core` (i.e., `NNN-core.md` or `NNN-core-{qualifier}.md`), excluding scope-type definition files. If any are found but cannot be read, output: `FAIL — Review cannot proceed: local meta-policy \`[filename]\` exists in scope \`[scope-name]\` but could not be read. Without it, full compliance cannot be verified.` Zero matches is valid — absence of local meta-policies is not an error.
    - **Rationale:** A review that silently omits mandatory governance layers produces false PASS results. Every governance layer declared by the scope MUST be loaded and applied; if any layer is inaccessible, the review result is unreliable and MUST be rejected.
    - **Scope-type:** Read the scope's `scope-type` from its `index.md`. Normalise the value to a list: split on commas and trim whitespace (`scope-type: typeA, typeB` becomes `[typeA, typeB]`). For **each** type in the list, search the `[type]/principles/` directories of all `core`-type scopes in the workspace for a file whose name ends with `{scope-type}-scope-type.md`. If the scope declares any `scope-type` elements but no matching file is found for ANY of them, output: `FAIL — Review cannot proceed: scope \`[scope-name]\` declares \`scope-type: [scope-type]\` but no \`[scope-type]-scope-type.md\` policy exists in any \`core\`-type scope in the workspace. The scope is READ-ONLY; install the scope-type governance before reviewing.`