xdrs-core 0.43.1 → 0.45.0

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

@@ -30,14 +30,16 @@ Performs a structured review of code changes or files against the Policies in th
    - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
    - Check `apply-to:` second. Keep only Policies whose stated scope fits the files, systems, or workflows under review.
    - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
-2. **Prerequisites gate — MUST complete before any review work:** For each scope containing files under review, read its `index.md` frontmatter and check for a `follows` field. `_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:
+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.`
    - **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.`
    - Once all prerequisites pass, load the `follows` scopes' Policies and apply them as mandatory governance. Last-listed scope in `follows` takes precedence when the same topic is addressed by multiple scopes.
-   - **Scope-type standards (application):** For each declared scope-type (single or comma-separated list), resolve its full ancestor chain (see `_core-adr-policy-010` rule 15): load the primary `{scope-type}-scope-type.md`, load all companion files (`{scope-type}-scope-type-{qualifier}.md`) alphabetically, then follow `NN-parent-scope-type` rules transitively until no more parents are declared. Stop on cycles. Concatenate all resolved chains in declaration order and deduplicate keeping first occurrence. Apply all policies from the deduplicated list as mandatory conventions. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. See `_core-adr-policy-010` rules 15, 17, and 19 for the full application model.
-   - **Local meta-policies (policy documents only):** Apply all found local meta-policy files as mandatory conventions when reviewing policy documents in the scope. Local meta-policies take highest precedence in the chain. See `_core-adr-policy-010` rules 16, 17, and 19.
+   - **Scope-type standards (application):** For each declared scope-type (single or comma-separated list), resolve its full ancestor chain (see `_core-adr-policy-010` rule 22): load the primary `{scope-type}-scope-type.md`, load all companion files (`{scope-type}-scope-type-{qualifier}.md`) alphabetically, then follow `NN-parent-scope-type` rules transitively until no more parents are declared. Stop on cycles. Concatenate all resolved chains in declaration order and deduplicate keeping first occurrence. Apply all policies from the deduplicated list as mandatory conventions. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. See `_core-adr-policy-010` rules 22, 24, and 26 for the full application model.
+   - **Extends chain loading (policy documents only):** If the scope declares `extends:` entries (and the extends check above passed), load the inherited policy documents depth-first (see `_core-adr-policy-010` rule 33). For each extends entry in declaration order, recursively resolve that scope's own `extends:` chain, then append its policies. Deduplicate keeping first occurrence. The reviewing scope's own policies take precedence over all inherited policies. Apply the resolved extended policy set as additional context during the review — inherited policies MUST be evaluated for compliance just as if they were authored in this scope.
+   - **Local meta-policies (policy documents only):** Apply all found local meta-policy files as mandatory conventions when reviewing policy documents in the scope. Local meta-policies take highest precedence in the chain. See `_core-adr-policy-010` rules 23, 24, and 26.
 3. Filter relevance based on file types, domains, and architectural patterns in scope.
 
 ### Phase 3: Policy Review
@@ -47,6 +49,10 @@ Performs a structured review of code changes or files against the Policies in th
    - Classify as ERROR (mandatory) or WARNING (advisory).
    - Include: location, description, Policy reference (file + line), suggestion.
    - **Normative language check (Policy documents only):** For every Policy document in scope, verify that normative statements use uppercase BCP 14 keywords as required by `_core-adr-policy-001`. Flag as ERROR when a lowercase `must`, `must not`, `always`, or `never` is used in a normative requirement context (Details or Decision Outcome sections). Flag as WARNING when lowercase `should`, `should not`, `recommended`, `advised`, `may`, `possibly`, or `optionally` appear in a normative or permissive context where the uppercase form is expected. Context sections and question statements are exempt.
+   - **Extends chain conflict check:** If the reviewed scope has an `extends:` field, check for undeclared semantic conflicts in the following combinations (use AI judgment; report as ERROR citing `[_core-adr-policy-010.34-extends-conflict-declaration]` for each undeclared conflict found):
+     - Between the reviewing scope's own policies and policies from any extended scope (where the same topic is addressed differently and no `## Conflicts` section declares the override).
+     - Between two or more extended scopes that address the same topic differently without documented resolution.
+     - Between extended scopes' policies and the policies of **all scopes that appear after the reviewed scope in the root index** (those scopes have higher root-index precedence and silently override the inherited policy set for non-extends consumers; if no `## Conflicts` section exists in the later-listed scope's policy to acknowledge the inherited policy it overrides, flag as ERROR).
 2. Reduce false positives:
    - Evaluate ERROR findings for mandatory language in the Policy ("must", "always", "never", "required", "mandatory"). Drop or downgrade to WARNING if the language is advisory ("should", "recommended", "advised").
    - Remove findings unrelated to actual changes.

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

@@ -14,16 +14,10 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 ## Instructions
 
-### Phase 0: Prerequisites Gate — MUST complete before writing
+### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
-Identify the target scope from the user's request; use `_local` if none is specified. Read the scope's `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 policy 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
+2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `policy`.
 
 ### Phase 1: Understand the Decision
 
@@ -45,10 +39,7 @@ Consult `001-xdrs-standards` while making each choice in this phase. The summari
 - **ADR**: system context, integration pattern, overarching architectural choice
 - **EDR**: specific tool/library, coding practice, testing strategy, project structure
 
-**Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
-
-**Subject** — MUST read `_core-adr-policy-016` ([016-policy-subjects.md](../../016-policy-subjects.md)) in full before choosing. That document defines all allowed subjects per type with full descriptions, examples, and disambiguation tiebreakers. Do not rely on summaries or prior knowledge of the subject list — always read the policy and select the subject that best matches the decision topic according to its definitions.
+**Scope** — confirmed in Phase 0. Follow the external-scope validation and subject selection guidance in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 When type, scope, or subject cannot be confidently inferred, ask the user a clarifying question before proceeding. Ask one question at a time and wait for the answer; follow up if the response introduces new ambiguity.
 
@@ -67,7 +58,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`.
+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.
 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.
@@ -169,9 +160,7 @@ Check every item before finalizing:
 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**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names (e.g., `follows: [myarea-core]`), verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, verify the document satisfies all requirements from those Policies. Scopes are applied in order; last-listed scope in `follows` takes precedence when the same topic is covered by multiple scopes.
-   - **Scope-type standards:** Read the target scope's `scope-type`. 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 for a file ending in `{scope-type}-scope-type.md`. If found, also load all companion files (`{scope-type}-scope-type-{qualifier}.md`) from the **same directory** and apply their rules as additional requirements. Resolve any `NN-parent-scope-type` rule transitively from the primary file. See `_core-adr-policy-010` rules 15 and 17.
-   - **Scope-local standards:** Scan the target scope's own `[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 (whose title ends with `-scope-type`). If any are found, apply ALL of them as mandatory requirements; they override scope-type standards on conflict. See `_core-adr-policy-010` rules 16 and 17.
+8. **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.
 
@@ -186,12 +175,7 @@ If any check fails, revise and re-run this phase before proceeding.
 
 ### Phase 9: Verify Package structure with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
-3. Review warnings; fix straightforward ones and note intentional deviations explicitly.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ### Constraints
 

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

@@ -15,16 +15,10 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 ## Instructions
 
-### Phase 0: Prerequisites Gate — MUST complete before writing
+### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
-Identify the target scope from the user's request; use `_local` if none is specified. Read the scope's `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
+2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `skill`.
 
 ### Phase 1: Understand the Skill Goal
 
@@ -46,10 +40,9 @@ Quick test:
 - "How to evaluate or decide on architecture?" → ADR
 - "How to execute a business process or policy?" → BDR
 
-**Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+**Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
-**Subject** — MUST read `_core-adr-policy-016` ([016-policy-subjects.md](../../016-policy-subjects.md)) in full before choosing. That document defines all allowed subjects per type with full descriptions, examples, and disambiguation tiebreakers. Do not rely on summaries or prior knowledge of the subject list — always read the policy and select the most specific subject that matches the skill's activity domain.
+**Subject** — follow the subject selection guidance in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 **Skill number** — scan `.xdrs/[scope]/[type]/[subject]/skills/` for the highest existing number and increment by 1. Never reuse numbers from deleted skills.
 
@@ -120,7 +113,7 @@ Before writing files, verify:
 3. **Length**: Under 6500 words? Trim verbose explanations.
 4. **Duplication**: Does this overlap an existing skill? If yes, revise.
 5. **References**: Are all related XDRs and skills linked, including the cases where the skill operationalizes multiple XDRs?
-6. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, verify the skill's activation criteria, phase structure, and content satisfy any requirements from those Policies. Last-listed scope in `follows` takes precedence.
+6. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `skill`.
 
 If any check fails, revise before continuing.
 
@@ -136,11 +129,7 @@ If any check fails, revise before continuing.
 
 ### Phase 7: Verify with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ### Constraints
 

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

@@ -26,14 +26,9 @@ Optional questions (ask only when genuinely unclear):
 - **Type**: Should the article primarily synthesize ADRs, BDRs, or EDRs? Ask only when the topic spans multiple types.
 - **Existing XDRS elements**: Are there specific Policies or Skills you want the article to reference or synthesize?
 
-**Prerequisites gate** — once the scope is confirmed from the answers above, perform ALL of the following checks before proceeding. If ANY check fails, output a FAIL result immediately and do not continue:
+**Scope placement** — once the scope is known from the answers above, run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to confirm it is the right placement for this content.
 
-- **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.`
-- **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 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+**Prerequisites gate** — once scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `article`.
 
 Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audience**.
 
@@ -49,8 +44,7 @@ Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audi
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
-**Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+**Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 **Type** — match the type of the XDRS elements the article primarily synthesizes (`adrs`, `bdrs`, or `edrs`).
 If the topic spans multiple types, use `adrs`. Use the same rules as `002-write-policy` Phase 2:
@@ -118,15 +112,11 @@ Rules to apply while drafting:
 3. Add back-references in the Policies, Research documents, and Skills that the article synthesizes, under their `## References`
    section.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new article. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
-5. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, verify the article satisfies any content or structural requirements from those Policies. Last-listed scope in `follows` takes precedence.
+5. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `article`.
 
 ### Phase 7: Verify with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ## Examples
 

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

@@ -17,16 +17,10 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 ## Instructions
 
-### Phase 0: Prerequisites Gate — MUST complete before writing
+### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
-Identify the target scope from the user's request; use `_local` if none is specified. Read the scope's `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
+2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `research`.
 
 ### Phase 1: Understand the Research Goal
 
@@ -46,8 +40,7 @@ If the answers from Phase 1 leave scope, type, or subject ambiguous, use `vscode
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when any detail matters, the standard decides.
 
-**Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+**Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 **Type** — match the type of decision this research supports (`adrs`, `bdrs`, or `edrs`). Use the same rules as `002-write-policy` Phase 2:
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -248,7 +241,7 @@ Before writing files, verify:
 5. **Standalone focus**: Does the text read as a technical paper rather than commentary about future ADRs, repository process, or artifact management?
 6. **Ratio fit**: Does the document stay within section word limits and pass the Python ratio check, or does the introduction explicitly justify the deviation?
 7. **References**: Are all related Policies, research docs, skills, articles, and external sources linked when relevant?
-8. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, verify the research satisfies any structural or content requirements from those Policies. Last-listed scope in `follows` takes precedence.
+8. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `research`.
 
 If any check fails, revise before continuing.
 
@@ -261,11 +254,7 @@ If any check fails, revise before continuing.
 
 ### Phase 12: Verify with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ## Examples
 

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

@@ -15,16 +15,10 @@ Guides the creation of a well-structured plan document by following `_core-adr-p
 
 ## Instructions
 
-### Phase 0: Prerequisites Gate — MUST complete before writing
+### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
-Identify the target scope from the user's request; use `_local` if none is specified. Read the scope's `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+1. Run the scope placement analysis from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/scope-placement.md` to determine and confirm the target scope.
+2. Once the scope is confirmed, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `plan`.
 
 ### Phase 1: Understand the Plan Goal
 
@@ -43,8 +37,7 @@ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-poli
 
 Consult `001-xdrs-standards` while making each choice in this phase. The summaries below are orientation only; when any detail is unclear, the standard decides.
 
-**Scope** — use `_local` unless the user explicitly names another scope.
-- If the user names a scope other than `_local`, check the workspace root `.filedist.lock` file. If any file under `.xdrs/[scope]/` appears in `.filedist.lock`, the scope is external and new documents MUST NOT be created there. Inform the user and ask them to choose a non-external scope.
+**Scope** — confirmed in Phase 0. Follow the external-scope validation in `.xdrs/_core/adrs/principles/skills/.assets/scope-selection.md`.
 
 **Type** — match the type of the Policies the plan primarily implements or relates to (`adrs`, `bdrs`, or `edrs`).
 - **BDR**: business process, product policy, strategic rule, operational procedure
@@ -136,15 +129,11 @@ Rules to apply while drafting:
 2. Add a link to the plan in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`).
 3. Add back-references in the Policies, Research documents, and Skills that the plan relates to, under their `## References` section.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new plan. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
-5. **Meta-policy compliance**: Check the target scope's `index.md` for a `follows` frontmatter field. `_core` Policies always apply to all scopes. If `follows` lists additional core scope names, verify that each listed scope directory exists in the workspace (e.g., `.xdrs/[scope-name]/index.md`). If any listed scope is missing, STOP immediately and tell the user: "Scope `[scope-name]` is listed in `follows` but not found in the workspace. Install it before proceeding." Once all `follows` scopes are confirmed present, verify the plan satisfies any structural or content requirements from those Policies. Last-listed scope in `follows` takes precedence.
+5. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `plan`.
 
 ### Phase 7: Verify with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ## Examples
 

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

@@ -16,14 +16,7 @@ Guides the creation of a Marp Markdown slide presentation that supports an exist
 
 ### Phase 0: Prerequisites Gate — MUST complete before writing
 
-Identify the target scope from the parent document's path or the user's request; use `_local` if none is specified. Read the scope's `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+Identify the target scope from the parent document's path or the user's request; use `_local` if none is specified. Then run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `presentation`.
 
 ### Phase 1: Identify the Parent Document
 
@@ -135,11 +128,7 @@ Rules:
 
 ### Phase 8: Verify with Lint
 
-1. Run the CLI lint utility from the repository root:
-   ```
-   npx -y xdrs-core@latest lint
-   ```
-2. Fix all reported errors before considering the task complete.
+Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md`.
 
 ### Constraints
 

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

@@ -28,14 +28,7 @@ Routes the request to the appropriate XDRS authoring skill based on the type of
 
 ### Phase 1.5: Prerequisites Gate — MUST complete before writing
 
-For the target scope where the document will be created, read its `index.md` frontmatter and perform ALL of the following checks. If ANY check fails, output a FAIL result immediately and do not proceed:
-
-- **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.`
-- **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 cannot be authored in full compliance with the scope's governance.` Zero matches is valid. When routing to the policy skill, apply all found local meta-policies as mandatory conventions.
-- **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.
-
-Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 15): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 17 and 19).
+For the target scope where the document will be created, run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `document`. When routing to the policy skill, apply all local meta-policies found during the gate as mandatory conventions.
 
 ### Phase 2: Load and Follow Target Skill
 

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

@@ -0,0 +1,121 @@
+---
+name: 009-compile-scope
+description: >
+  Compiles or updates any scope declaring `scope-type: compiled` from its configured external sources. Reads compilation meta-policies to discover sources, fetches content (git clone, local copy, or web scrape), plans policy changes, migrates policies one at a time with structured format, `## Source` sections, and `**compilation-note:**` markers, then runs lint and review. Documents source inconsistencies without inventing fixes. Activate when the user asks to compile, update, sync, refresh, or recompile a compiled scope.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## 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.
+
+## Instructions
+
+### Phase 0: Prerequisites Gate
+
+1. Identify the target scope. Verify its `index.md` declares `scope-type: compiled` (alone or combined with other types). If not, output: `FAIL — [scope-name] does not declare scope-type: compiled. This skill only applies to compiled scopes.`
+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/`.
+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:
+   - 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
+
+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.
+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:
+   - **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.
+
+### Phase 3: Migrate Policies (one at a time)
+
+For each TODO item marked CREATE or UPDATE, in sequence:
+
+1. **Write the policy file** following `_core-adr-policy-019` and `_core-adr-policy-008`:
+   - Use standard policy frontmatter: `name`, `description`, `apply-to`, `valid-from`. Generate these from the source text; they are exempt from the no-invented-content rule per policy-019 rule 05.
+   - Use structured numbered rule blocks for all claims (per `_core-adr-policy-008`).
+   - Transcribe source content faithfully. Do NOT invent, infer beyond what the source states, or fill gaps. Preserve ambiguities as-is.
+
+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".
+   ```
+
+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`).
+   ```
+   ## Source
+
+   - source-1/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.
+
+### Phase 4: Verify Each Policy
+
+After writing each policy:
+
+1. Confirm the `## Source` section is present with at least one path entry.
+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.
+
+### Phase 5: 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
+
+1. Read and follow `.xdrs/_core/adrs/principles/skills/001-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.
+
+### Phase 7: Document Inconsistencies
+
+1. Collect all inconsistencies noted during Phases 3, 4, and 6.
+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.
+   - The policy `name` field MUST be `[scope]-[type]-policy-NNN-inconsistencies-from-source`.
+   - List each inconsistency with: source file path, affected compiled policy, and a description of the inconsistency.
+   - Do NOT propose or include fixes.
+3. If no inconsistencies exist, report that the compilation is clean.
+
+### Phase 8: Cleanup
+
+1. Remove the temporary directory `.tmp/compilation-[ts]/` created in Phase 1.
+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.

package/.xdrs/_core/index.md

@@ -53,7 +53,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 05 and 05b. 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 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`.
 
 ### Available skills
 

package/README.md

@@ -62,13 +62,14 @@ Different teams at different organizational levels make decisions that apply to
 
 ### Scope types and `follows`
 
-Every scope declares a `scope-type` in its `index.md` frontmatter. The five built-in types are `core`, `reference`, `platform`, `standard`, and `_local`, each with different governance rules. Custom types (e.g. `business-area`) can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope.
+Every scope declares a `scope-type` in its `index.md` frontmatter. The six built-in types are `core`, `reference`, `platform`, `compiled`, `standard`, and `_local`, each with different governance rules. Custom types (e.g. `business-area`) can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope.
 
 | Type | Purpose | Naming pattern | Root index order |
 |---|---|---|---|
 | `core` | Meta-governance: authoring standards, scope-type definitions, process guidance. No consumable policies. | `{name}-core` (e.g. `myorg-core`) | 1st |
 | `reference` | Standards, regulations, or reference models to be adopted or adapted (e.g. PCI-DSS, ISO 27001, reference architectures). Not a live service. | `{domain}-ref-{name}` (e.g. `security-ref-baseline`) | 2nd |
 | `platform` | Existing live services or infrastructure teams can consume directly (e.g. cloud platform, shared data service). | `{domain}-plat-{name}` (e.g. `cloud-plat-infra`) | 3rd |
+| `compiled` | Policies compiled directly from external sources (web pages, git repos, local folders). All content must trace to source; no invented content. Combinable with other types. | Free-form (no naming requirement) | any, before `_local` |
 | `standard` | Business areas, products, teams, or any general-purpose scope. Default type when nothing else fits. | Any valid scope name (e.g. `checkout`, `mobile-app`) | 4th |
 | `_local` | Workspace-local overrides. Reserved exclusively for the `_local` scope. Never distributed. | `_local` (reserved) | last |
 
@@ -78,6 +79,18 @@ Every scope declares a `scope-type` in its `index.md` frontmatter. The five buil
 
 **`platform` scopes** document what already exists and is ready to use. A scope is of type `platform` when its content describes a live operational capability — what is available, how to access it, and what constraints apply.
 
+**`compiled` scopes** hold policies compiled directly from external authoritative sources. All content must trace back to the source; no invented content is allowed. A `compiled` scope requires a local meta-policy with source URLs and compilation configuration, and uses the `009-compile-scope` skill to fetch, compile, and keep content up to date. The `compiled` type may be combined with another type (e.g. `scope-type: compiled, reference`) when the combined type's governance also applies.
+
+```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
+
+## Selectors
+Include A01–A10 risk entries only.
+```
+
 **`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.
@@ -94,7 +107,7 @@ description: Checkout team decisions
 ---
 ```
 
-The recommended ordering in `.xdrs/index.md` is: `core → reference → platform → standard → _local`. Scopes listed later override earlier ones on the same topic.
+The recommended ordering in `.xdrs/index.md` is: `core → reference → platform → compiled/standard → _local`. Scopes listed later override earlier ones on the same topic.
 
 Custom scope types can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope. The `checkout` scope in [examples/typed-scope](examples/typed-scope) uses a custom `business-area` type defined in `ecomm-core`.