xdrs-core 0.43.0 → 0.44.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/.xdrs/_core/adrs/principles/001-xdrs-standards.md +2 -2
  2. package/.xdrs/_core/adrs/principles/002-policy-standards.md +1 -1
  3. package/.xdrs/_core/adrs/principles/010-scope-governance.md +41 -41
  4. package/.xdrs/_core/adrs/principles/018-external-path-symlinks.md +1 -1
  5. package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md +2 -2
  6. package/.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md +3 -3
  7. package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md +1 -1
  8. package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md +1 -1
  9. package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md +1 -1
  10. package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md +1 -1
  11. package/.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md +1 -1
  12. package/.xdrs/_core/adrs/principles/skills/008-write-xdrs-doc/SKILL.md +1 -1
  13. package/.xdrs/_core/index.md +1 -1
  14. package/package.json +1 -1
package/.xdrs/_core/adrs/principles/001-xdrs-standards.md CHANGED
@@ -75,7 +75,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
75
75
  - **Types:** `adrs`, `bdrs`, `edrs`
76
76
  - there can exist sufixes to the standard scope names (e.g: `business-x-mobileapp`, `business-y-servicedesk`)
77
77
  - 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.
78
- - **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 05 and 05b for the full multi-type grammar. Custom scope-type names MUST NOT start with `_`. The five built-in scope types and their definitions are:
78
+ - **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:
79
79
  - `core` — see [`_core-adr-policy-011`](011-core-scope-type.md)
80
80
  - `reference` — see [`_core-adr-policy-012`](012-reference-scope-type.md)
81
81
  - `platform` — see [`_core-adr-policy-013`](013-platform-scope-type.md)
@@ -86,7 +86,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
86
86
  - **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:
87
87
  - `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.
88
88
  - `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.
89
- - `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 05 and 05b for the full multi-type grammar and `_core-adr-policy-011`, `012`–`015` for built-in type definitions.
89
+ - `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.
90
90
  - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
91
91
  - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
92
92
  - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
package/.xdrs/_core/adrs/principles/002-policy-standards.md CHANGED
@@ -76,7 +76,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
76
76
  - Each policy rule and rule block MUST be unambiguous: it MUST be possible to clearly follow, check, and discuss it without requiring additional interpretation.
77
77
  - When the decision defines strong policies or rules that SHOULD be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the Policy MUST follow the extension [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) instead of using plain bullet lists for those rules.
78
78
  - Conflict handling applies to Policy documents:
79
- - For cross-scope and cross-scope-type overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope or scope-type policy. Local meta-policies (`NNN-core.md` and companion files) and scope-type definition policies MAY include a `## Conflicts` section for this purpose. See `_core-adr-policy-010` rule 19-conflict-declarations for the required structure.
79
+ - For cross-scope and cross-scope-type overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope or scope-type policy. Local meta-policies (`NNN-core.md` and companion files) and scope-type definition policies MAY include a `## Conflicts` section for this purpose. See `_core-adr-policy-010` rule 26-conflict-declarations for the required structure.
80
80
  - **Within-scope conflicts:** Policies within the same type+scope MUST NOT conflict. If two Policies appear to conflict, one SHOULD be updated, removed, or the conflict resolved through a new Policy.
81
81
  - When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
82
82
  - MUST NOT use emojis in contents.
package/.xdrs/_core/adrs/principles/010-scope-governance.md CHANGED
@@ -27,30 +27,30 @@ All scope types — both the five built-in types and any custom types — are de
27
27
 
28
28
  ### Details
29
29
 
30
- #### Section A — Scope-type definition standards
30
+ **Section A — Scope-type definition standards**
31
31
 
32
- ##### 01-def-must-live-in-core-scope
32
+ #### 01-def-must-live-in-core-scope
33
33
 
34
34
  A scope-type definition policy MUST be placed in a `core`-type scope (i.e., a scope whose `index.md` declares `scope-type: core`).
35
35
 
36
- ##### 02-def-naming
36
+ #### 02-def-naming
37
37
 
38
38
  The policy `name` field MUST end with `{scope-type}-scope-type` (e.g., `security-scope-type`, `business-area-scope-type`). The policy file MUST follow the standard numbered filename convention `NNN-{scope-type}-scope-type.md` and MUST be placed in the `principles` subject of any decision type folder within the `core`-type scope (e.g., `_core/adrs/principles/011-core-scope-type.md`).
39
39
 
40
40
  Note: this naming applies to the **policy name** only, not to any scope directory name. It is distinct from the `-core` scope-name suffix convention defined in `_core-adr-policy-011`.
41
41
 
42
- ##### 02b-def-companion-files
42
+ #### 03-def-companion-files
43
43
 
44
44
  A scope-type definition MAY be split across multiple policy files. The primary file MUST follow rule 02 above. Each additional companion file MUST be named `NNN-{scope-type}-scope-type-{qualifier}.md` (e.g., `012-business-area-scope-type-writing-style.md`), where `{qualifier}` is a short lowercase kebab-case descriptor. All companion files MUST be placed in the **same** `[type]/principles/` directory as the primary file within the same scope. A companion file MUST NOT exist without a corresponding primary file in the same scope and type folder. Tools and agents MUST apply all companion files for a scope-type as additional mandatory conventions alongside the primary.
45
45
 
46
- ##### 03-def-required-content
46
+ #### 04-def-required-content
47
47
 
48
48
  A scope-type definition policy MUST define:
49
49
 
50
50
  - The scope type name (the value that instances declare in their `scope-type:` field).
51
51
  - When to use this scope type and what kinds of scopes SHOULD declare it.
52
52
 
53
- ##### 04-def-preferred-content
53
+ #### 05-def-preferred-content
54
54
 
55
55
  A scope-type definition policy SHOULD define:
56
56
 
@@ -59,86 +59,86 @@ A scope-type definition policy SHOULD define:
59
59
  - What content SHOULD NOT be placed in scopes of this type.
60
60
  - Special instructions on how to organise or write content in scopes of this type.
61
61
 
62
- ##### 05-def-instance-declaration
62
+ #### 06-def-instance-declaration
63
63
 
64
64
  A scope that is an instance of one or more scope types MUST declare `scope-type` in its `index.md` frontmatter. Two formats are valid:
65
65
 
66
66
  - **Single type**: `scope-type: business-area`
67
67
  - **Multiple types** (comma-separated): `scope-type: compiled, internal-docs, auditable`
68
68
 
69
- When multiple scope types are declared, all rules from all declared types (and their parent chains) apply simultaneously to documents in the scope. A document MUST satisfy the requirements of every applicable type. When two types define a rule with the same rule number but different content, the conflict MUST be declared in a `## Conflicts` section of the overriding scope-type policy (see Section C rule 19-conflict-declarations). An undeclared conflict makes a document impossible to satisfy and MUST be resolved before authoring begins.
69
+ When multiple scope types are declared, all rules from all declared types (and their parent chains) apply simultaneously to documents in the scope. A document MUST satisfy the requirements of every applicable type. When two types define a rule with the same rule number but different content, the conflict MUST be declared in a `## Conflicts` section of the overriding scope-type policy (see Section C rule 26-conflict-declarations). An undeclared conflict makes a document impossible to satisfy and MUST be resolved before authoring begins.
70
70
 
71
- ##### 05b-def-multi-type-validation
71
+ #### 07-def-multi-type-validation
72
72
 
73
- A comma-separated `scope-type` list MUST NOT have empty elements. Each element MUST satisfy the same constraints as a single `scope-type` value (rules 06 and 08). Duplicate values within the same list are NOT allowed.
73
+ A comma-separated `scope-type` list MUST NOT have empty elements. Each element MUST satisfy the same constraints as a single `scope-type` value (rules 08 and 10). Duplicate values within the same list are NOT allowed.
74
74
 
75
- ##### 06-def-no-underscore-prefix
75
+ #### 08-def-no-underscore-prefix
76
76
 
77
77
  Custom scope-type names MUST NOT start with `_`. The `_` prefix is reserved for built-in scope types defined in `_core` (currently only `_local`).
78
78
 
79
- ##### 07-def-parent-scope-type
79
+ #### 09-def-parent-scope-type
80
80
 
81
- A scope-type definition policy MAY declare a parent scope type by including a rule titled `NN-parent-scope-type` in its `### Details` section. The body of that rule MUST reference the parent scope-type name in backticks (e.g., "Instances of this scope type inherit all rules from the `standard` scope type."). This rule MUST appear only in the **primary** file (rule 02), not in a companion file (rule 02b). Tools and agents MUST resolve the full parent chain transitively. Child scope-type standards override parent standards on any conflict.
81
+ A scope-type definition policy MAY declare a parent scope type by including a rule titled `NN-parent-scope-type` in its `### Details` section. The body of that rule MUST reference the parent scope-type name in backticks (e.g., "Instances of this scope type inherit all rules from the `standard` scope type."). This rule MUST appear only in the **primary** file (rule 02), not in a companion file (rule 03). Tools and agents MUST resolve the full parent chain transitively. Child scope-type standards override parent standards on any conflict.
82
82
 
83
- ##### 08-def-valid-iff-policy-exists
83
+ #### 10-def-valid-iff-policy-exists
84
84
 
85
85
  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.
86
86
 
87
87
  When a scope declares a `scope-type` (single or array) but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace, the scope MUST be treated as READ-ONLY by all tools and agents: content in it MUST NOT be added, changed, or removed, and its content MUST NOT be reviewed. Tools and agents MUST surface the read-only status to the user and MUST NOT propose or apply any changes until the scope-type governance is installed.
88
88
 
89
- ##### 08b-def-scope-type-must-be-structured
89
+ #### 11-def-scope-type-must-be-structured
90
90
 
91
- All `{scope-type}-scope-type.md` policies (primary and companion files) MUST follow the structured format defined in `_core-adr-policy-008`: the policy MUST contain a `### Details` section and at least one `#### NN-rulename` rule block within it. This makes individual scope-type rules machine-readable, individually citable, and detectable for conflict analysis. Tools MUST enforce this and report an error using code `_core-adr-policy-010.08b-def-scope-type-must-be-structured`.
91
+ All `{scope-type}-scope-type.md` policies (primary and companion files) MUST follow the structured format defined in `_core-adr-policy-008`: the policy MUST contain a `### Details` section and at least one `#### NN-rulename` rule block within it. This makes individual scope-type rules machine-readable, individually citable, and detectable for conflict analysis. Tools MUST enforce this and report an error using code `_core-adr-policy-010-scope-governance.11-def-scope-type-must-be-structured`.
92
92
 
93
- ##### 08c-def-core-scope-policies-must-be-structured
93
+ #### 12-def-core-scope-policies-must-be-structured
94
94
 
95
- 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 08b). 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.08c-def-core-scope-policies-must-be-structured`.
95
+ 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`.
96
96
 
97
97
  ---
98
98
 
99
- #### Section B — Local meta-policies
99
+ **Section B — Local meta-policies**
100
100
 
101
- ##### 09-local-naming
101
+ #### 13-local-naming
102
102
 
103
- The word `core` as a hyphen-delimited segment in a policy filename title is reserved for local meta-policies. A local meta-policy is identified by its filename title starting with `core`: either `NNN-core.md` (primary, no qualifier) or `NNN-core-{qualifier}.md` (companion, where `{qualifier}` is a short lowercase kebab-case descriptor). A policy filename title MUST NOT use `core` as a word segment unless it is a valid local meta-policy (see rule 10). Scope-type definition files (`NNN-{scope-type}-scope-type.md`) are exempt from this restriction even when their title begins with `core`.
103
+ The word `core` as a hyphen-delimited segment in a policy filename title is reserved for local meta-policies. A local meta-policy is identified by its filename title starting with `core`: either `NNN-core.md` (primary, no qualifier) or `NNN-core-{qualifier}.md` (companion, where `{qualifier}` is a short lowercase kebab-case descriptor). A policy filename title MUST NOT use `core` as a word segment unless it is a valid local meta-policy (see rule 14). Scope-type definition files (`NNN-{scope-type}-scope-type.md`) are exempt from this restriction even when their title begins with `core`.
104
104
 
105
- ##### 10-local-placement
105
+ #### 14-local-placement
106
106
 
107
107
  Local meta-policy files MUST be placed in the `principles` subject of any type folder within the scope they govern (e.g., `my-team/adrs/principles/001-core.md`). They apply implicitly to that scope — no declaration in `index.md` is required. Local meta-policies MUST NOT be placed in any other subject folder; a file whose title starts with `core` in a non-`principles` subject is a lint error.
108
108
 
109
- ##### 10b-local-primary-required
109
+ #### 15-local-primary-required
110
110
 
111
111
  A companion local meta-policy (`NNN-core-{qualifier}.md`) MUST NOT exist in a type folder unless a primary local meta-policy (`NNN-core.md`) also exists in the **same** type folder. Tools MUST enforce this constraint.
112
112
 
113
- ##### 10c-local-unique-qualifier
113
+ #### 16-local-unique-qualifier
114
114
 
115
115
  Each qualifier (including the blank qualifier of the primary) MUST be unique across all type folders within the same scope. For example, a scope MUST NOT have both `adrs/principles/001-core.md` and `bdrs/principles/001-core.md` — the blank qualifier would appear twice.
116
116
 
117
- ##### 11-local-optional
117
+ #### 17-local-optional
118
118
 
119
119
  Creating a local meta-policy is optional. It SHOULD be created when a scope has specific structural, authoring, or content constraints that differ from `_core` defaults or the scope's declared scope-type standards.
120
120
 
121
- ##### 12-local-content
121
+ #### 18-local-content
122
122
 
123
- A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 03–04 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, plans, research). Local meta-policies and their companion files MAY include a `## Conflicts` section to declare that one of their rules overrides a conflicting rule from a scope-type policy or `follows:` scope policy (see Section C rule 19-conflict-declarations).
123
+ A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 04–05 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, plans, research). Local meta-policies and their companion files MAY include a `## Conflicts` section to declare that one of their rules overrides a conflicting rule from a scope-type policy or `follows:` scope policy (see Section C rule 26-conflict-declarations).
124
124
 
125
- ##### 12b-local-must-be-structured
125
+ #### 19-local-must-be-structured
126
126
 
127
- All local meta-policy files (`NNN-core.md` and `NNN-core-{qualifier}.md`) MUST follow the structured format defined in `_core-adr-policy-008` (see rule 08b). Tools MUST enforce this and report an error using code `_core-adr-policy-010.12b-local-must-be-structured`.
127
+ All local meta-policy files (`NNN-core.md` and `NNN-core-{qualifier}.md`) MUST follow the structured format defined in `_core-adr-policy-008` (see rule 11). Tools MUST enforce this and report an error using code `_core-adr-policy-010-scope-governance.19-local-must-be-structured`.
128
128
 
129
- ##### 13-local-mandatory-when-present
129
+ #### 20-local-mandatory-when-present
130
130
 
131
131
  When one or more local meta-policies exist in a scope, tools and agents MUST load and apply ALL of them as mandatory conventions when authoring or reviewing **policy documents** in that scope. If any found local meta-policy file is unreadable, tools MUST halt and report an error before proceeding.
132
132
 
133
133
  ---
134
134
 
135
- #### Section C — Governance application and precedence
135
+ **Section C — Governance application and precedence**
136
136
 
137
- ##### 14-application-follows
137
+ #### 21-application-follows
138
138
 
139
- A scope's `follows:` frontmatter field lists `core`-type scope names whose policies apply as mandatory conventions to this scope, in addition to `_core`. The last-listed scope takes precedence on conflicts when the same topic is addressed by multiple `follows:` scopes.
139
+ Tools and agents MUST apply the policies of all scopes listed in a scope's `follows:` frontmatter as mandatory conventions, in addition to `_core`. When the same topic is addressed by multiple `follows:` scopes, the last-listed scope MUST take precedence on conflicts.
140
140
 
141
- ##### 15-application-scope-type
141
+ #### 22-application-scope-type
142
142
 
143
143
  When adding or reviewing content in a scope, tools and agents MUST:
144
144
 
@@ -149,9 +149,9 @@ When adding or reviewing content in a scope, tools and agents MUST:
149
149
  c. If the primary contains a rule titled `NN-parent-scope-type`, extract the parent type name (backtick-quoted identifier in the rule body) and repeat steps a–c for the parent. Continue until no more parents are declared. Detect and stop on cycles.
150
150
  3. Concatenate all resolved ancestor chains in declaration order to form a single flat list (e.g., for `scope-type: [reference, platform]` where `reference → standard` and `platform → core`: `[standard, reference, core, platform]`).
151
151
  4. Deduplicate the flat list keeping the **first occurrence** of each type (preserves the ancestor semantics of whichever type introduced the parent earliest).
152
- 5. Apply all policies from the deduplicated list as mandatory conventions. Later entries in the list override earlier entries when the same rule number appears with different content, provided the override is declared (see rule 19-conflict-declarations).
152
+ 5. Apply all policies from the deduplicated list as mandatory conventions. Later entries in the list override earlier entries when the same rule number appears with different content, provided the override is declared (see rule 26-conflict-declarations).
153
153
 
154
- ##### 16-application-local
154
+ #### 23-application-local
155
155
 
156
156
  When adding or reviewing **policy documents** in a scope, tools and agents MUST:
157
157
 
@@ -159,23 +159,23 @@ When adding or reviewing **policy documents** in a scope, tools and agents MUST:
159
159
  2. If any are found, read and apply ALL of them as mandatory conventions. If a found file is unreadable, halt with an error before proceeding.
160
160
  3. If none are found, continue without error — absence of local meta-policies is valid.
161
161
 
162
- ##### 17-precedence
162
+ #### 24-precedence
163
163
 
164
164
  When multiple governance layers define a rule with the same rule number, the later entry in the following ordered chain takes precedence (lowest to highest):
165
165
 
166
- 1. All scope-types in the deduplicated ancestor chain (rule 15), in chain order — earlier entries are overridden by later entries.
166
+ 1. All scope-types in the deduplicated ancestor chain (rule 22), in chain order — earlier entries are overridden by later entries.
167
167
  2. `follows:` scope policies (applied in `follows:` list order; last-listed scope wins among themselves).
168
168
  3. Local meta-policies (`NNN-core.md` and companions in alphabetical qualifier order).
169
169
 
170
- In all cases, an override is valid only if the overriding policy contains a `## Conflicts` section that explicitly declares the conflict with the overridden rule (see rule 19-conflict-declarations). A conflict that is not declared MUST be surfaced as an error by tools and agents; the content cannot be validated until the conflict is resolved.
170
+ In all cases, an override is valid only if the overriding policy contains a `## Conflicts` section that explicitly declares the conflict with the overridden rule (see rule 26-conflict-declarations). A conflict that is not declared MUST be surfaced as an error by tools and agents; the content cannot be validated until the conflict is resolved.
171
171
 
172
172
  All of the above are subordinate to `_core` structural rules, which MUST NOT be overridden.
173
173
 
174
- ##### 18-ordering-custom-types
174
+ #### 25-ordering-custom-types
175
175
 
176
176
  Custom-type scopes SHOULD be placed in the `standard` position in the root `index.md` ordering (i.e., after `platform` scopes and before `_local`).
177
177
 
178
- ##### 19-conflict-declarations
178
+ #### 26-conflict-declarations
179
179
 
180
180
  When a policy (scope-type definition, local meta-policy, or companion) overrides a rule defined by a lower-precedence policy in the governance chain, the overriding policy MUST include a `## Conflicts` section that declares:
181
181
 
package/.xdrs/_core/adrs/principles/018-external-path-symlinks.md CHANGED
@@ -19,7 +19,7 @@ How should XDRS files be made accessible from paths outside the `.xdrs/` root wi
19
19
 
20
20
  **Symlinks from external paths to the canonical `.xdrs/` location**
21
21
 
22
- When a file or directory inside `.xdrs/` needs to be reachable from an external path, a symlink MUST be created at the external path pointing to the canonical `.xdrs/` location. The canonical file always lives inside `.xdrs/`. Copying is never acceptable.
22
+ When a file or directory inside `.xdrs/` needs to be reachable from an external path, a symlink MUST be created at the external path pointing to the canonical `.xdrs/` location. The canonical file MUST remain inside `.xdrs/`. Files MUST NOT be copied to external paths.
23
23
 
24
24
  **Example:** `.agents/skills/001-review` (symlink) → `.xdrs/_core/adrs/principles/skills/001-review/`
25
25
 
package/.xdrs/_core/adrs/principles/skills/001-review/SKILL.md CHANGED
@@ -36,8 +36,8 @@ Performs a structured review of code changes or files against the Policies in th
36
36
  - **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.
37
37
  - **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.`
38
38
  - 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.
39
- - **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.
40
- - **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.
39
+ - **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.
40
+ - **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.
41
41
  3. Filter relevance based on file types, domains, and architectural patterns in scope.
42
42
 
43
43
  ### Phase 3: Policy Review
package/.xdrs/_core/adrs/principles/skills/002-write-policy/SKILL.md CHANGED
@@ -23,7 +23,7 @@ Identify the target scope from the user's request; use `_local` if none is speci
23
23
  - **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.`
24
24
  - **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.
25
25
 
26
- 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).
26
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
27
27
 
28
28
  ### Phase 1: Understand the Decision
29
29
 
@@ -170,8 +170,8 @@ Check every item before finalizing:
170
170
  6. **Conflicts section**: Is it present and filled if Phase 3 found any conflicts?
171
171
  7. **Index entries**: Will the new Policy be added to `[scope]/[type]/index.md` and the Policy root `index.md`?
172
172
  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.
173
- - **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.
174
- - **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.
173
+ - **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 22 and 24.
174
+ - **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 23 and 24.
175
175
 
176
176
  If any check fails, revise and re-run this phase before proceeding.
177
177
 
package/.xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md CHANGED
@@ -24,7 +24,7 @@ Identify the target scope from the user's request; use `_local` if none is speci
24
24
  - **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.`
25
25
  - **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.
26
26
 
27
- 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).
27
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
28
28
 
29
29
  ### Phase 1: Understand the Skill Goal
30
30
 
package/.xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md CHANGED
@@ -33,7 +33,7 @@ Optional questions (ask only when genuinely unclear):
33
33
  - **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.`
34
34
  - **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.
35
35
 
36
- 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).
36
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
37
37
 
38
38
  Do NOT proceed to Phase 1 until you have at minimum a clear **topic** and **audience**.
39
39
 
package/.xdrs/_core/adrs/principles/skills/005-write-research/SKILL.md CHANGED
@@ -26,7 +26,7 @@ Identify the target scope from the user's request; use `_local` if none is speci
26
26
  - **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.`
27
27
  - **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.
28
28
 
29
- 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).
29
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
30
30
 
31
31
  ### Phase 1: Understand the Research Goal
32
32
 
package/.xdrs/_core/adrs/principles/skills/006-write-plan/SKILL.md CHANGED
@@ -24,7 +24,7 @@ Identify the target scope from the user's request; use `_local` if none is speci
24
24
  - **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.`
25
25
  - **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.
26
26
 
27
- 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).
27
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
28
28
 
29
29
  ### Phase 1: Understand the Plan Goal
30
30
 
package/.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md CHANGED
@@ -23,7 +23,7 @@ Identify the target scope from the parent document's path or the user's request;
23
23
  - **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.`
24
24
  - **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.
25
25
 
26
- 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).
26
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
27
27
 
28
28
  ### Phase 1: Identify the Parent Document
29
29
 
package/.xdrs/_core/adrs/principles/skills/008-write-xdrs-doc/SKILL.md CHANGED
@@ -35,7 +35,7 @@ For the target scope where the document will be created, read its `index.md` fro
35
35
  - **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.`
36
36
  - **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.
37
37
 
38
- 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).
38
+ Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): 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 24 and 26).
39
39
 
40
40
  ### Phase 2: Load and Follow Target Skill
41
41
 
package/.xdrs/_core/index.md CHANGED
@@ -53,7 +53,7 @@ Slide presentations that support XDRS documents follow [_core-adr-policy-009](ad
53
53
 
54
54
  ### Scope types
55
55
 
56
- 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`.
56
+ 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`.
57
57
 
58
58
  ### Available skills
59
59
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "xdrs-core",
3
- "version": "0.43.0",
3
+ "version": "0.44.0",
4
4
  "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.",
5
5
  "repository": {
6
6
  "type": "git",