xdrs-core 0.52.2 → 0.53.0

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

@@ -50,7 +50,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md`
   where `[xdrs-root]` is the XDRS root folder (default: `.xdrs/`).
 - MUST ignore symlinks paths. MUST NOT create or update documents inside symlinked folders.
-- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NOT be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`, and tools (such as `xdrs-core lint`) will skip external scopes by default. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
+- **Files listed in `.filedist.lock` are external XDRs.** A file whose path appears in the workspace root `.filedist.lock` file was distributed from an external source repository. It MUST NOT be modified locally. To change it, submit the change to the source repository and re-extract the updated package. The `.filedist.lock` format is one entry per line: `<relative-path>|<package>|<version>`. A scope is considered external when any of its files appear in `.filedist.lock`. The `.filedist.lock` file can also be used to detect which files changed when bumping an external scope to a newer version: compare the version field in `.filedist.lock` entries before and after the upgrade and diff the affected paths to understand what decisions were added, updated, or removed.
 - Optional supporting artifacts under the same subject:
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[skill-name]/SKILL.md`
@@ -91,8 +91,8 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `apply-to` (required): Declares in which contexts — teams, systems, codebases, or environments — the decisions in this scope are relevant. Max 30 words.
     - `valid-from` (required): ISO date (YYYY-MM-DD) from which this scope became active.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
-    - `follows` (optional): Core scope names whose Policies apply as mandatory governance conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`). All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail.
-    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or initiatives) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. All referenced scopes MUST exist in the workspace; if any is absent, READ/WRITE/REVIEW operations MUST fail. When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Extended scopes are still linked in the root index; tag them `extends-only` to apply them only via `extends:` (see `_core-adr-policy-022.01-root-index-completeness`). `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
+    - `follows` (optional): Core scope names whose Policies apply as mandatory governance conventions to this scope, beyond `_core`. Last-listed takes precedence on conflicts (e.g., `follows: myarea-core, shared-standards`). A missing scope MUST be fixed in local scopes and makes external scopes READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`).
+    - `extends` (optional): Scope names whose **policy documents** (decision records only — not skills, articles, research, or initiatives) are inherited by this scope as if they were authored here. Any scope type except `_local` and `_core` may be referenced. Last-listed extended scope takes precedence on conflicts; the extending scope's own policies always take highest precedence. Depth-first transitive resolution applies: if A extends [B, C] and B extends [D], the effective precedence order is D < B < C < A. `extends:` and `follows:` MUST reference disjoint scope sets. A missing scope MUST be fixed in local scopes and makes external scopes READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). When an extending scope's policy overrides an inherited policy on the same topic, a `## Conflicts` section MUST document the override. Extended scopes are still linked in the root index; tag them `extends-only` to apply them only via `extends:` (see `_core-adr-policy-022.01-root-index-completeness`). `extends:` takes precedence over root index ordering for conflict resolution between the scopes involved; root index ordering is the fallback for all other scope pairs. See `_core-adr-policy-010` Section D (rules 27–35) and Section E (rule 36) for full normative rules.
     - `extends-only` (optional): See `_core-adr-policy-022.07-extends-only-field`.
     - `license` (optional): SPDX identifier for the scope's content license.
 - **Subjects:** The subject folder MUST be chosen per [`_core-adr-policy-016`](016-policy-subjects.md), which defines allowed subjects, full descriptions, examples, and disambiguation tiebreakers.

package/.xdrs/_core/adrs/principles/002-policy-standards.md

@@ -111,7 +111,7 @@ All Policies MUST follow this template
 ---
 name: [scope]-[type]-policy-[number]-[short-title]
 description: [What this decision is about and when to use it]
-apply-to: [Required. Contexts this decision applies to, under 40 words. Use "All scopes" when broadly applicable.]
+apply-to: [Required. Contexts this decision applies to, <40 words. Use "All scopes" when broadly applicable.]
 valid-from: [Required. ISO date YYYY-MM-DD from when enforcement begins. Defaults to creation date.]
 license: [Optional. SPDX license expression]
 metadata:

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -121,7 +121,7 @@ Brief description of the skill goal.
 ### Outputs
 
 #### Contents
-- Generated files or chat-delivered results, one bullet per item, or "None".
+- Generated files or chat-delivered results, one bullet per item, or "None" (e.g., `Release notes (<300 words)`).
 
 #### Changes
 - External system mutations that are part of the skill's main objective, one bullet per item, or "None".
@@ -202,6 +202,17 @@ Generative skills — those producing a deliverable document (Policy, Skill, Art
 
 Skills MUST halt on missing required input, dubious/ambiguous input, or insufficient agent confidence, unless the user explicitly instructs the agent to proceed anyway. This override applies generally; a skill's own `## Halt Conditions` list does not need to restate it.
 
+**Generated content caps**
+
+Every natural-language content a skill generates MUST declare a hard word cap written exactly as `<N words`, whether a human or an agent executes the skill. This covers files, templates, reports, intermediate chat messages, HITL questions, final summaries, and text posted to external systems (e.g., PR comments, commit messages).
+- Exempt, with no marker: code (including its comments), structured data (JSON, YAML, tracking files), verbatim copies, and frontmatter fields already limited in characters by a spec or Policy.
+- Caps MUST be in words; other limits MAY coexist but never replace them.
+- Declare each cap once: in the template placeholder (including templates in `references/` or `.assets/`), else in the Instructions step producing the content, else in its `#### Contents` bullet.
+- A blanket statement MAY cover a content class (e.g., all intermediate messages); a more specific cap overrides it.
+- Write the number inline; a Policy reference is optional.
+- Content whose size cannot be bounded MUST be marked `(uncapped: <reason>)`, the reason explaining why.
+- Caps are hard: condense, or split into another item only where the skill allows it; never split one logical item across messages. An explicit user request lifts the cap for that item only.
+
 **Validation**
 
 Use the [skills-ref](https://github.com/agentskills/agentskills/tree/main/skills-ref) CLI to validate before committing:

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -86,32 +86,32 @@ All research documents MUST follow this template:
 
 ## Abstract
 
-[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. Under 200 words.]
+[Single paragraph summarizing the goal, methods, results, and conclusion. Goal: let a quick technical reader understand the question, method, main result, and takeaway. <200 words.]
 
 ## Introduction
 
 [Describe the problem, context, constraints, known facts, experiences, gaps, assumptions, and objectives.
-Prefer markdown structures (bullets, tables, headings) first; for diagrams see _core-adr-policy-020. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
+Prefer markdown structures (bullets, tables, headings) first; for diagrams see _core-adr-policy-020. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. <700 words.]
 
 Question: [Central question of the research]?
 
 ## Methods
 
 [Explain how the study was conducted, including design, tools, data sources, and test conditions.
-Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. Under 1200 words.]
+Include enough detail for an experienced professional to reproduce the relevant parts. Goal: make the important parts of the study reproducible. <1200 words.]
 
 ## Results
 
 [Report findings, data, trends, quantitative results, code artifacts, and option comparisons.
-Prefer tables and bullet lists for simple comparisons; for diagrams see _core-adr-policy-020. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. Under 1800 words.]
+Prefer tables and bullet lists for simple comparisons; for diagrams see _core-adr-policy-020. If multiple options solve the same problem, add comparison tables and explicit pros and cons for each option. Focus on raw findings, not interpretation. Goal: present the raw findings with minimal interpretation. <1800 words.]
 
 ## Discussion
 
-[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged and under 1000 words.]
+[Interpret the results, explain significance, trade-offs, performance considerations, limitations, and implications. Goal: interpret the findings for technical readers. Keep this section technically engaged. <1000 words.]
 
 ## Conclusion
 
-[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. Under 400 words.]
+[Summarize the main findings, practical takeaway, applicability boundaries, and important open questions. Goal: summarize the main findings and what they mean in practice. <400 words.]
 
 ## References
 

package/.xdrs/_core/adrs/principles/007-initiative-standards.md

@@ -66,39 +66,39 @@ All initiatives MUST follow this template:
 
 ## Executive Summary
 
-[Required. A summary of all sections below using bullet points, focused on the most important items. Under 500 words.]
+[Required. A summary of all sections below using bullet points, focused on the most important items. <500 words.]
 
 ## Context and Problem Statement
 
-[Required. Describe clearly why we are executing this initiative. What is the impact? Who is impacted? Why is this important? Under 200 words.
+[Required. Describe clearly why we are executing this initiative. What is the impact? Who is impacted? Why is this important? <200 words.
 E.g.: Our checkout abandon rate is 50%, and it's increasing over time.]
 
 ## Proposed Solution
 
-[Required. What we expect to achieve to solve the problem described above. Under 200 words.
+[Required. What we expect to achieve to solve the problem described above. <200 words.
 E.g.: Reduce payment time in our App by 30% and fix the 3 most impactful bugs.]
 
 Expected end date: YYYY-MM-DD
 
 ## Acceptance Criteria
 
-[Optional. Used to make it clear what the expected result is and to create a way to verify when the goal is achieved. May include a short checklist. Under 100 words.]
+[Optional. Used to make it clear what the expected result is and to create a way to verify when the goal is achieved. May include a short checklist. <100 words.]
 
 ## Approach
 
-[Optional. High level description about how to achieve the result and the strategy used, including how to engage people, projects, organize the work, how to learn unknowns, deal with risks, and distribute workload. May include a WBS with the hierarchy of the work. Under 300 words.]
+[Optional. High level description about how to achieve the result and the strategy used, including how to engage people, projects, organize the work, how to learn unknowns, deal with risks, and distribute workload. May include a WBS with the hierarchy of the work. <300 words.]
 
 ## Key Deliverables
 
-[Optional. List of the main features, goods, artifacts, data, articles, skills, decisions, training, programs, events etc that will be important to achieve the expected result. Under 300 words.]
+[Optional. List of the main features, goods, artifacts, data, articles, skills, decisions, training, programs, events etc that will be important to achieve the expected result. <300 words.]
 
 ## Key Resources
 
-[Optional. List of equipment, people, other project results, budget, areas or dependencies that need to be engaged or allocated for this initiative to be implemented. Under 100 words.]
+[Optional. List of equipment, people, other project results, budget, areas or dependencies that need to be engaged or allocated for this initiative to be implemented. <100 words.]
 
 ## Milestones
 
-[Optional. List of goals to be followed along with an optional acceptance criteria, owner and due date. Each milestone may have a checklist used as acceptance criteria verification. Key tasks and risks can be listed as part of a milestone. Under 1000 words per milestone.]
+[Optional. List of goals to be followed along with an optional acceptance criteria, owner and due date. Each milestone may have a checklist used as acceptance criteria verification. Key tasks and risks can be listed as part of a milestone. <1000 words per milestone.]
 
 ### Milestone 1: [Title]
 Owner: [name or team]
@@ -118,7 +118,7 @@ Due date: YYYY-MM-DD
 
 ## Risks Identified
 
-[Optional. List of risks along with a short description and mitigation strategy. Under 1000 words.]
+[Optional. List of risks along with a short description and mitigation strategy. <1000 words.]
 
 ## References
 

package/.xdrs/_core/adrs/principles/008-policy-structured-standards.md

@@ -53,7 +53,7 @@ Each rule MUST be written as a level-4 heading with a two-digit zero-padded sequ
 
 ```markdown
 #### [NN]-[short-rule-title-in-kebab-case]
-[Rule body using normative language per _core-adr-policy-001. Under 500 words.]
+[Rule body using normative language per _core-adr-policy-001. <500 words.]
 ```
 
 #### 09-citations-must-use-dot-notation

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

@@ -81,9 +81,9 @@ A scope-type definition policy MAY declare a parent scope type by including a ru
 
 #### 10-def-valid-iff-policy-exists
 
-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.
+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. When `scope-type` is an array, this applies to every element.
 
-When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace or defined only in a `disabled` scope, the scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). Missing types are a lint error for local scopes.
+When a scope declares a `scope-type` but any corresponding `{scope-type}-scope-type.md` policy is absent from the workspace or defined only in a `disabled` scope, the scope MUST be treated as READ-ONLY (see `_core-adr-policy-022.06-read-only-dependencies`). Missing or disabled-only types MUST be fixed in local scopes.
 
 #### 11-def-scope-type-must-be-structured
 
@@ -103,7 +103,7 @@ The word `core` as a hyphen-delimited segment in a policy filename title is rese
 
 #### 14-local-placement
 
-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.
+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 invalid.
 
 #### 15-local-primary-required
 
@@ -180,7 +180,7 @@ When a policy (scope-type definition, local meta-policy, or companion) overrides
 - The policy file where the original rule is defined.
 - A short explanation of why the override is required for this scope or type.
 
-A `## Conflicts` section MAY also document cross-scope-type incompatibilities for informational purposes. Tools and agents MUST detect undeclared conflicts at review time and surface them as errors. Semantic conflict detection is the responsibility of the authoring agent, not the lint tool.
+A `## Conflicts` section MAY also document cross-scope-type incompatibilities for informational purposes. Tools and agents MUST detect undeclared conflicts at review time and surface them as errors. Semantic conflict detection is the responsibility of the authoring agent.
 
 ## References
 
@@ -213,7 +213,7 @@ A scope `extends:` declaration MUST NOT reference the declaring scope itself. To
 
 #### 32-extends-mandatory-presence
 
-Every scope listed in a scope's `extends:` field MUST exist in the workspace with an accessible `index.md`. If any referenced scope is absent or its `index.md` cannot be read, all READ, WRITE, and REVIEW operations on the extending scope MUST fail immediately. Tools MUST surface a clear message naming the missing scope and citing code `_core-adr-policy-010.32-extends-mandatory-presence`.
+Every scope listed in a scope's `extends:` field MUST exist in the workspace with an accessible `index.md`. If any referenced scope is absent or its `index.md` cannot be read, the extending scope MUST be fixed when local and is READ-ONLY when external (`_core-adr-policy-022.06-read-only-dependencies`).
 
 #### 33-extends-content-precedence
 

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

@@ -73,7 +73,7 @@ Distributing `-core` scopes alongside their companion consumable scope to downst
 
 #### 10-no-type-combination
 
-A scope is core-type when its resolved scope-type chain, including parent types (see `_core-adr-policy-010.09-def-parent-scope-type`), contains `core`. A core-type scope MUST declare exactly one scope type; combining a core-type with any other type (e.g., `scope-type: core, standard`) is a lint error. Core-type scopes hold meta governance only, so mixing them with consumable types would blur rules 04 and 05.
+A scope is core-type when its resolved scope-type chain, including parent types (see `_core-adr-policy-010.09-def-parent-scope-type`), contains `core`. A core-type scope MUST declare exactly one scope type; combining a core-type with any other type (e.g., `scope-type: core, standard`) is invalid. Core-type scopes hold meta governance only, so mixing them with consumable types would blur rules 04 and 05.
 
 ## References
 

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

@@ -9,21 +9,21 @@ valid-from: 2026-07-20
 
 ## Context and Problem Statement
 
-Packages install scope folders into a workspace, but nothing guaranteed that every installed scope was listed in the root `index.md`. Scopes that were meant to be reused only through `extends:` were hidden from the root index, so agents could not discover them, and consumers had no way to switch off a scope they installed but did not want to apply. When a scope depended on another scope that was absent, the result was either a hard lint error or silent misbehaviour.
+Packages install scope folders into a workspace, but nothing guaranteed that every installed scope was listed in the root `index.md`. Scopes that were meant to be reused only through `extends:` were hidden from the root index, so agents could not discover them, and consumers had no way to switch off a scope they installed but did not want to apply. When a scope depended on another scope that was absent, the result was either a hard failure or silent misbehaviour.
 
 How does a consumer control which installed scopes apply globally, which apply only through `extends:`, and which are ignored, while keeping every scope discoverable?
 
 ## Decision Outcome
 
-**Every installed scope is listed once in the root index; the consumer controls activation with an inline activation tag next to the scope link, and the scope author declares intent with an `extends-only` frontmatter field that lint checks for coherence.**
+**Every installed scope is listed once in the root index; the consumer controls activation with an inline activation tag next to the scope link, and the scope author declares intent with an `extends-only` frontmatter field that MUST be coherent with the tag.**
 
-Policies of listed scopes apply globally by default. An activation tag narrows a scope to `extends-only` or turns it off with `disabled`. Agents rely only on the tags. Scopes whose dependencies are missing, disabled, or invalid become read-only.
+Policies of listed scopes apply globally by default. An activation tag narrows a scope to `extends-only` or turns it off with `disabled`. Agents rely only on the tags. Scopes whose dependencies are missing, disabled, or invalid become read-only; local scopes MUST NOT stay in that state.
 
 ### Details
 
 #### 01-root-index-completeness
 
-Every scope folder under the XDRS root that contains an `index.md`, including scopes installed from external packages, MUST be linked exactly once from the root `index.md`. The `_local` scope MUST NOT be linked (see `_core-adr-policy-001`). A scope folder with no link, or a scope linked more than once, is a lint error. Links that resolve to the same scope index (e.g. `./x/index.md` and `x/index.md`) count as the same link. Links inside fenced code blocks are ignored.
+Every scope folder under the XDRS root that contains an `index.md`, including scopes installed from external packages, MUST be linked exactly once from the root `index.md`. The `_local` scope MUST NOT be linked (see `_core-adr-policy-001`). A scope folder with no link, or a scope linked more than once, is invalid. Links that resolve to the same scope index (e.g. `./x/index.md` and `x/index.md`) count as the same link. Links inside fenced code blocks are ignored.
 
 #### 02-global-applicability
 
@@ -31,23 +31,26 @@ Policies of a listed scope without an activation tag MUST be applied globally, n
 
 #### 03-activation-tag-syntax
 
-An activation tag is an inline code span placed immediately after a scope link on the same line, optionally separated by spaces or tabs, for example a link to `payments-ref/index.md` followed by `` `extends-only` ``. Allowed values are `extends-only` and `disabled`, lowercase only. A scope link line MUST NOT contain any other inline code: an unknown value, a second tag, or inline code placed elsewhere on the line is a lint error. A tag on the next line is not a tag. `_core` MUST NOT be tagged.
+An activation tag is an inline code span placed immediately after a scope link on the same line, optionally separated by spaces or tabs, for example a link to `payments-ref/index.md` followed by `` `extends-only` ``. Allowed values are `extends-only` and `disabled`, lowercase only. A scope link line MUST NOT contain any other inline code: an unknown value, a second tag, or inline code placed elsewhere on the line is invalid. A tag on the next line is not a tag. `_core` MUST NOT be tagged.
 
 #### 04-extends-only
 
-Policies of a scope tagged `extends-only` MUST be applied only through the `extends:` chain of an active scope (untagged, including read-only scopes, or `_local`). Reach is transitive: if A extends B and B extends C, both B and C apply to A. The root index position of a tagged scope never matters for conflict resolution; `extends:` precedence applies (see `_core-adr-policy-010.33-extends-content-precedence`). Skills, articles, research, and initiatives of the scope remain usable. Tools SHOULD warn when no active scope reaches an `extends-only` scope; reach only through a `disabled` scope does not count.
+Policies of a scope tagged `extends-only` MUST be applied only through the `extends:` chain of an active scope (untagged, including read-only scopes, or `_local`). Reach is transitive: if A extends B and B extends C, both B and C apply to A. The root index position of a tagged scope never matters for conflict resolution; `extends:` precedence applies (see `_core-adr-policy-010.33-extends-content-precedence`). Skills, articles, research, and initiatives of the scope remain usable. Every `extends-only` scope MUST be reached by at least one active scope; reach only through a `disabled` scope does not count. Fix it by adding the scope to the `extends:` of an active scope or by tagging it `disabled`.
 
 #### 05-disabled
 
-All content of a scope tagged `disabled` MUST be ignored by agents: its policies, skills, articles, research, and initiatives are not applied, and nothing is inherited from it through `extends:` or `follows:`. The scope is still linted and MAY be edited. Skills of a disabled scope that are symlinked into `.agents/skills` (see `_core-adr-policy-018`) stay loaded by tools and MUST be removed by the consumer.
+All content of a scope tagged `disabled` MUST be ignored by agents: its policies, skills, articles, research, and initiatives are not applied, and nothing is inherited from it through `extends:` or `follows:`. The scope is still validated and MAY be edited; a disabled local scope follows rule 06 like any other local scope. Skills of a disabled scope that are symlinked into `.agents/skills` (see `_core-adr-policy-018`) stay loaded by tools and MUST be removed by the consumer.
 
 #### 06-read-only-dependencies
 
-A scope MUST be treated as READ-ONLY when a scope it follows or extends, or the scope that defines one of its scope types (including parent types), is missing, disabled, or invalid, or when it is an external scope and its own `index.md` is invalid. Content in a READ-ONLY scope MUST NOT be added, changed, or removed. For local scopes, missing dependencies and invalid indexes remain lint errors (see `_core-adr-policy-010.32-extends-mandatory-presence`); a disabled dependency only makes the scope read-only. Tools MUST report each cause and how to fix it, citing this rule.
+A scope MUST be treated as READ-ONLY when a scope it follows or extends, or the scope that defines one of its scope types (including parent types), is missing, disabled, or invalid, or when it is an external scope and its own `index.md` is invalid. Content in a READ-ONLY scope MUST NOT be added, changed, or removed.
+
+- **Local scope** (not tracked in `.filedist.lock`, including `_local` and disabled scopes): a read-only local scope is frozen and cannot be maintained, so each cause is invalid and MUST be fixed.
+- **External scope** (tracked in `.filedist.lock`): the scope is READ-ONLY; agents MUST tell the user when they skip a change because of it, naming the cause and fix.
 
 #### 07-extends-only-field
 
-A scope author MAY declare `extends-only: true` or `extends-only: false` in the scope index frontmatter. Only unquoted lowercase `true` and `false` are valid. An invalid value is a lint error in a local scope; in an external scope it makes the scope read-only and the value is treated as absent. `extends-only` (field `true` or tag) on `_core`, `_local`, or a core-type scope is a lint error. Coherence: when the field is `true`, the root index link MUST carry the tag `extends-only` or `disabled`; when the field is `false` or absent, the consumer MAY add either tag (narrowing), and MUST NOT widen a scope beyond what the author declared. The field is a lint aid only.
+A scope author MAY declare `extends-only: true` or `extends-only: false` in the scope index frontmatter. Only unquoted lowercase `true` and `false` are valid. An invalid value in a local scope MUST be fixed; in an external scope it makes the scope READ-ONLY and the value is treated as absent. `extends-only` (field `true` or tag) MUST NOT be used on `_core`, `_local`, or a core-type scope. Coherence: when the field is `true`, the root index link MUST carry the tag `extends-only` or `disabled`; when the field is `false` or absent, the consumer MAY add either tag (narrowing), and MUST NOT widen a scope beyond what the author declared. Agents MUST NOT use the field for activation (rule 08).
 
 #### 08-agent-resolution
 

package/.xdrs/_core/adrs/principles/skills/.assets/lint-verification.md

@@ -9,4 +9,3 @@ This module is shared across all XDRS writing skills. Run these steps after all
    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.

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

@@ -4,8 +4,8 @@ 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.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -50,6 +50,8 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### 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.`
@@ -93,7 +95,7 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 1. For each type folder governed by a meta-policy (from Phase 0), apply the `## Selectors` rules to the fetched staging content to determine which portions to include.
 2. List all existing policies in the scope under each governed type folder.
 3. If `.assets/sources/[name]/` already holds a previous persisted snapshot, diff the newly selected staging content against it (for example, by content hash per file) to pre-seed which policies are likely unaffected.
-4. Analyse the selected content and produce a TODO list showing for each expected policy:
+4. Analyse the selected content and produce a TODO list (uncapped: one line per expected policy; each line <30 words) 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
@@ -104,12 +106,12 @@ Performs a full compilation cycle for any scope declaring `scope-type: compiled`
 
 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.
+1. **Write the policy file** (<2600 words, per `_core-adr-policy-002`) following `_core-adr-policy-019` and `_core-adr-policy-008`:
+   - Use standard policy frontmatter: `name`, `description`, `apply-to` (<40 words), `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:
+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 and keep it <60 words. Example:
    ```
    All API keys MUST be rotated every 90 days. **compilation-note:** derived from [api-guidelines/security/api-guidelines.md section 4.2] — "Keys should be invalidated and replaced quarterly"; frequency inferred as 90 days from the term "quarterly".
    ```
@@ -138,7 +140,7 @@ After writing each policy:
 ### Phase 6: Lint
 
 1. Run `npx xdrs-core lint` from the workspace root (or `make lint` if a `Makefile` is present with a `lint` target).
-2. Review all reported errors and warnings.
+2. Review all reported errors.
 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.
 
@@ -154,7 +156,7 @@ After writing each policy:
 1. Collect all inconsistencies noted during Phases 4, 5, and 7.
 2. If any inconsistencies exist:
    - Determine the next available policy number in the `001–100` principles block for the relevant type folder.
-   - Create or update `[type]/principles/NNN-inconsistencies-from-source.md` in the scope.
+   - Create or update `[type]/principles/NNN-inconsistencies-from-source.md` (<2600 words) 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.

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

@@ -6,8 +6,8 @@ description: >
    Also activate when you identify a need to check compliance with Policies during implementation.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -28,7 +28,7 @@ Performs a structured review of code changes or files against the Policies in th
 
 #### Contents
 
-- Structured ERROR/WARNING findings report in chat.
+- Findings report in chat (uncapped: one per finding).
 
 #### Changes
 
@@ -48,6 +48,8 @@ Performs a structured review of code changes or files against the Policies in th
 
 ## Instructions
 
+Keep every question and intermediate message <100 words.
+
 ### Phase 1: Code Gathering
 
 1. Identify changes based on requested scope:
@@ -113,18 +115,18 @@ Performs a structured review of code changes or files against the Policies in th
 
 ### Phase 6: Reporting
 
-**Report template**
+**Report template** (keep `## Summary` <50 words)
 ```text
 ### Code Review Against Policies
 Scope: [scope identifier]
 
 ## Findings
 ### 1. [ERROR|WARNING] - [filename:line_number](filename:line_number)
-- Title of the finding (<=15 words)
+- Title of the finding (<15 words)
 - Policy reference: [policy-file:line_number](policy-file:line_number)
-- Why: Brief description of the issue in 20 words
-- Fix: Specific action to fix this issue in 15 words
-- Relevance: Why this matters / What to watch for in 15 words
+- Why: Brief description of the issue (<20 words)
+- Fix: Specific action to fix this issue (<15 words)
+- Relevance: Why this matters / What to watch for (<15 words)
 
 ### 2. [second finding etc]
 

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

@@ -4,8 +4,8 @@ description: >
    Creates a new article document following XDRS article standards: selects scope, type, subject, and number; then writes a focused synthetic text that combines and links multiple Policies, Research documents, and Skills around a topic. Activate this skill when the user asks to create, add, or write a new article, guide, or overview document within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -42,6 +42,8 @@ Guides the creation of a well-structured article by following `_core-adr-policy-
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Clarify Intent
 
 Before reading any standards, ask the user clarifying questions to gather the information needed to proceed. Use the `vscode_askQuestions` tool with all questions in a single call.
@@ -108,16 +110,16 @@ Use the mandatory template from `004-article-standards`:
 
 ## Overview
 
-[Brief description of what this article covers and its intended audience. Under 40 words.]
+[Brief description of what this article covers and its intended audience. <40 words.]
 
 ## Content
 
 [Synthetic text combining and explaining the topic. Use links to Policies, Research documents, and Skills
-when referencing information from those documents. Keep under 1950 words total.]
+when referencing information from those documents. <1950 words total.]
 
 ## References
 
-- [Policy id or Skill name](relative/path/to/file.md) - Brief description of relevance
+- [Policy id or Skill name](relative/path/to/file.md) - Brief description of relevance (<15 words)
 ```
 
 Rules to apply while drafting:
@@ -130,15 +132,15 @@ Rules to apply while drafting:
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists first, then ASCII art for very simple cases, then Mermaid.js (sequence, state, activity, entity diagrams) for complex ones, then draw.io when Mermaid is insufficient — save as Editable Vector (File → Save As → Editable Vector) and store as `.svg` in the sibling `.assets/` folder.
 - If the article genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/articles/.assets/` and link them using a same-folder relative path (e.g., `.assets/image.png`).
 - Use relative paths for all links; never use absolute paths starting with `/`.
-- Target under 1950 words for best reader engagement (SHOULD). If content grows beyond that, break it into separate chapter articles rather than expanding a single file. The hard limit is 8000 words.
+- When content would exceed the Content cap, break it into separate chapter articles rather than expanding a single file.
 - Use lowercase file names. Never use emojis.
 - If a conflict exists between the article and a Policy, note it and defer to the Policy.
 
 ### Phase 6: Place and Register
 
 1. Save the file at `.xdrs/[scope]/[type]/[subject]/articles/[number]-[short-title].md`.
-2. Add a link to the article 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 article synthesizes, under their `## References`
+2. Add a link to the article in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`), with a description <15 words.
+3. Add back-references (<15 words each) 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**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `article`.
@@ -169,7 +171,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - **Cross-subject topic** — place the article in `principles`, not in any single subject folder.
 - **No existing articles folder** — create it; it is optional in the folder layout.
 - **Conflicting information found** — note the conflict in the article and always defer to the Policy.
-- **Article approaches 2000 words** — split the content into separate chapter articles (e.g., `001-topic-overview.md`, `002-topic-deep-dive.md`) so each can be read and understood independently. Move detailed content to a Research, Skill, or Policy and link back. The hard ceiling is 8000 words; never exceed it.
+- **Article would exceed the Content cap** — split the content into separate chapter articles (e.g., `001-topic-overview.md`, `002-topic-deep-dive.md`) so each can be read and understood independently. Move detailed content to a Research, Skill, or Policy and link back.
 - **Article is part of a series** — add the series position line immediately after the heading (e.g., `_This is article 2/4 of the "Engineering Practices" series. | Previous: ... | Next: ..._`) and link to the adjacent articles. When creating a new article that splits an existing one, update the neighbouring articles to reflect the new total and add or correct their navigation links.
 
 ## Constraints
@@ -188,7 +190,7 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 
 - **Mistake:** Writing an article that spans multiple unrelated subjects without splitting it into chapters.
   **Why it happens:** A broad topic feels easier to cover in one long document.
-  **Instead:** Once content approaches ~2000 words or covers distinct sub-topics, split into separate chapter articles per Phase 5/Edge Cases guidance.
+  **Instead:** Once content approaches the Content cap or covers distinct sub-topics, split into separate chapter articles per Phase 5/Edge Cases guidance.
 
 - **Mistake:** Skipping Phase 0 clarifying questions (topic/audience/scope) because the request seems clear.
   **Why it happens:** The request looks self-explanatory, so asking feels like unnecessary friction.

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

@@ -6,8 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write an initiative, plan, project plan, roadmap, or execution plan within an XDRS project.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -44,6 +44,8 @@ Guides the creation of a well-structured initiative document by following `_core
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Scope Placement and Prerequisites Gate — MUST complete before writing
 
 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.
@@ -98,45 +100,45 @@ Use the mandatory template from `007-initiative-standards`:
 
 ## Executive Summary
 
-[Required. Bullet points summarizing all sections below. Under 500 words.]
+[Required. Bullet points summarizing all sections below. <500 words.]
 
 ## Context and Problem Statement
 
-[Required. Why are we executing this initiative? What is the impact? Who is impacted? Under 200 words.]
+[Required. Why are we executing this initiative? What is the impact? Who is impacted? <200 words.]
 
 ## Proposed Solution
 
-[Required. What we expect to achieve. Under 200 words.]
+[Required. What we expect to achieve. <200 words.]
 
 Expected end date: YYYY-MM-DD
 
 ## Acceptance Criteria
 
-[Optional. Expected result and how to verify the goal is achieved. Under 100 words.]
+[Optional. Expected result and how to verify the goal is achieved. <100 words.]
 
 ## Approach
 
-[Optional. Strategy and high-level how. Under 300 words.]
+[Optional. Strategy and high-level how. <300 words.]
 
 ## Key Deliverables
 
-[Optional. Main outputs needed. Under 300 words.]
+[Optional. Main outputs needed. <300 words.]
 
 ## Key Resources
 
-[Optional. Equipment, people, budget, dependencies. Under 100 words.]
+[Optional. Equipment, people, budget, dependencies. <100 words.]
 
 ## Milestones
 
-[Optional. Goals with acceptance criteria, owners, and due dates. Under 1000 words per milestone.]
+[Optional. Goals with acceptance criteria, owners, and due dates. <1000 words per milestone.]
 
 ## Risks Identified
 
-[Optional. Risks with description and mitigation strategy. Under 1000 words.]
+[Optional. Risks with description and mitigation strategy. <1000 words.]
 
 ## References
 
-- [Related Policy or artifact](relative/path.md) - Brief description of relevance
+- [Related Policy or artifact](relative/path.md) - Brief description of relevance (<15 words)
 ```
 
 Rules to apply while drafting:
@@ -154,8 +156,8 @@ Rules to apply while drafting:
 ### Phase 6: Place and Register
 
 1. Save the file at `.xdrs/[scope]/[type]/[subject]/initiatives/[number]-[short-title].md`.
-2. Add a link to the initiative 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 initiative relates to, under their `## References` section.
+2. Add a link to the initiative in the canonical index for that scope+type (`.xdrs/[scope]/[type]/index.md`), with a description <15 words.
+3. Add back-references (<15 words each) in the Policies, Research documents, and Skills that the initiative relates to, under their `## References` section.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new initiative. 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**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `initiative`.