xdrs-core 0.40.0 → 0.41.0

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

@@ -30,9 +30,11 @@ 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. **Meta-policy scopes:** 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. If a scope declares `follows:` with additional core scope names (e.g., `follows: myarea-core, shared-standards`), 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 — do not proceed with the review — 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, load their 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:** Read the scope's `scope-type` from its `index.md`. 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 found, apply its rules as mandatory conventions. If the scope-type policy contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat for the parent; continue until no more parents are declared. Detect and stop on cycles. See `_core-adr-policy-010` rules 15 and 17 for the full application model.
-   - **Scope-local standards:** Search the scope's own `[type]/principles/` directories for a policy file whose name ends with `{scope-name}-core.md`. If found, apply its rules as mandatory conventions; scope-local standards take precedence over scope-type standards on any conflict. See `_core-adr-policy-010` rules 16 and 17.
+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:
+   - **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.`
+   - **Scope-local core policy:** Check whether a `-core` policy file exists for the scope being reviewed (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Review cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, full compliance cannot be verified.`
+   - **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.
+   - 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:** Read the scope's `scope-type` from its `index.md`. 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 found, apply its rules as mandatory conventions. If the scope-type policy contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat for the parent; continue until no more parents are declared. Detect and stop on cycles. See `_core-adr-policy-010` rules 15 and 17 for the full application model.
    - **Scope-local standards:** Search the scope's own `[type]/principles/` directories for a policy file whose name ends with `{scope-name}-core.md`. If found, apply its rules as mandatory conventions; scope-local standards take precedence over scope-type standards on any conflict. See `_core-adr-policy-010` rules 16 and 17.
 3. Filter relevance based on file types, domains, and architectural patterns in scope.

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

@@ -14,6 +14,14 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 ## Instructions
 
+### Phase 0: 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 1: Understand the Decision
 
 1. Read the XDRS root `index.md` (default: `.xdrs/index.md`) to discover all active scopes and their canonical indexes.

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

@@ -15,6 +15,14 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 ## Instructions
 
+### Phase 0: 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 1: Understand the Skill Goal
 
 1. Read `.xdrs/_core/adrs/principles/003-skill-standards.md` in full to internalize the SKILL.md format, folder layout, and numbering rules.

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

@@ -26,6 +26,12 @@ 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:
+
+- **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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audience**.
 
 ### Phase 1: Understand the Article Goal

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

@@ -17,6 +17,14 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 ## Instructions
 
+### Phase 0: 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 1: Understand the Research Goal
 
 1. Read `.xdrs/_core/adrs/principles/006-research-standards.md` in full to internalize the folder layout, numbering rules, and mandatory template.

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

@@ -15,6 +15,14 @@ Guides the creation of a well-structured plan document by following `_core-adr-p
 
 ## Instructions
 
+### Phase 0: 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 1: Understand the Plan Goal
 
 1. Read `.xdrs/_core/adrs/principles/007-plan-standards.md` in full to internalize the template, placement rules, numbering rules, and the constraint that plans are ephemeral and must be deleted after implementation.

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

@@ -14,6 +14,14 @@ Guides the creation of a Marp Markdown slide presentation that supports an exist
 
 ## Instructions
 
+### 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 1: Identify the Parent Document
 
 1. Read `.xdrs/_core/adrs/principles/009-presentation-standards.md` in full to internalize all presentation rules.

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

@@ -26,6 +26,14 @@ Routes the request to the appropriate XDRS authoring skill based on the type of
 
 2. If the type cannot be confidently inferred, ask the user one focused question: *"What type of XDRS document do you want to create — Policy, Skill, Research, Plan, Article, or Presentation?"* Wait for the answer before proceeding.
 
+### 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.`
+- **Scope-local core policy:** Check whether a `-core` policy file exists for the target scope (i.e., a file ending in `{scope-name}-core.md` inside the scope's `[type]/principles/` directory). If the scope's `index.md` references or implies a local core standard and that file is absent or unreadable, output: `FAIL — Cannot proceed: the local core policy \`{scope-name}-core.md\` is referenced for scope \`[scope-name]\` but could not be found. Without it, the document cannot be authored in full compliance with the scope's governance.`
+- **Rationale:** Authoring a document without all mandatory governance layers loaded risks producing content that silently violates scope policies. Every governance layer declared by the scope MUST be present before writing begins.
+
 ### Phase 2: Load and Follow Target Skill
 
 Read the full content of the skill file for the inferred type, then follow all its phases and instructions exactly as if that skill had been activated directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "A framework to structure, compile and distribute Architectural (ADR), Business (BDR), and Engineering (EDR) decision records contents so that AI agents and humans can reliably find and use them with hierarchical scopes and controlled rollout in the format of distributable versioned packages.",
   "repository": {
     "type": "git",