xdrs-core 0.52.3 → 0.53.0

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/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".
    ```
@@ -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`.
 

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

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a new Policy (ADR, BDR, or EDR).
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -27,7 +27,7 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 #### Contents
 
-- A new Policy file.
+- A new Policy file (<1300 words; complex <2600).
 
 #### Changes
 
@@ -43,6 +43,8 @@ Guides the creation of a well-structured Policy by following the standards in `_
 
 ## 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.
@@ -137,22 +139,22 @@ Refer to `_core-adr-policy-008-policy-structured-standards` for full requirement
 ---
 name: [scope]-[type]-[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. Defaults to today's date when not specified by the user.]
 ---
 
 # [scope]-[type]-[number]: [Short Title]
 
 ## Context and Problem Statement
-[background, who is impacted, and the explicit question being answered - under 40 words]
+[background, who is impacted, and the explicit question being answered - <40 words]
 
 ## Decision Outcome
 
 **[Chosen Option Title]**
-[One sentence: what is the decision - under 30 words]
+[One sentence: what is the decision - <30 words]
 
 ### Details
-[Rules, applicability boundaries, concise examples, and optional do/don't guidance — under 1300 words]
+[Rules, applicability boundaries, concise examples, and optional do/don't guidance — <1300 words]
 
 ## Considered Options (only if the user explicitly indicated multiple options)
 
@@ -164,7 +166,7 @@ valid-from: [Required. ISO date YYYY-MM-DD. Defaults to today's date when not sp
 Mandatory rules to apply while drafting:
 - Always include frontmatter `apply-to:`. Use `All scopes` when the decision applies broadly, or a more specific description when the decision is narrowly scoped.
 - Always include frontmatter `valid-from:`. Use today's date in `YYYY-MM-DD` format when the user does not specify a date.
-- Keep `apply-to:` under 40 words and use `valid-from:` only with `YYYY-MM-DD` ISO format.
+- Use `valid-from:` only with `YYYY-MM-DD` ISO format.
 - When frontmatter metadata is present, write it so a reader can decide whether the Policy should be used for the current case without guessing. `valid-from:` sets a convergence date for adoption, `apply-to:` narrows the contexts where the decision applies, and the decision text defines any remaining boundaries.
 - Use mandatory language ("must", "always", "never") only for hard requirements; use advisory language ("should", "recommended") for guidance.
 - Do not duplicate content already in referenced Policies — link instead.
@@ -175,13 +177,12 @@ Mandatory rules to apply while drafting:
 - If the Policy genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/.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 `/`.
 - No emojis. Lowercase filenames.
-- Target under 1300 words total; under 2600 words for complex decisions.
 
 ### Phase 7: Review the Draft
 
 Check every item before finalizing:
 
-1. **Length**: Is it under 1300 words? Trim verbose explanations. Move detailed skills to a separate file and link.
+1. **Length**: Is it within the Policy file cap and every template section cap? Trim verbose explanations. Move detailed skills to a separate file and link.
 2. **Frontmatter**: Are `apply-to:` and `valid-from:` both present? `apply-to:` must describe the applicable context (use `All scopes` when broadly applicable). `valid-from:` must be set (use today's date if the user did not specify one).
 3. **Normative language**: Does every normative requirement in the Details and Decision Outcome sections use uppercase BCP 14 keywords per `_core-adr-policy-001`? Replace any lowercase `must`/`should`/`may` that express requirements, prohibitions, or permissions with MUST/MUST NOT, SHOULD/SHOULD NOT, or MAY/OPTIONAL respectively. Lowercase forms are only acceptable in Context sections, question statements, or when used with their ordinary English meaning.
 4. **Originality**: Does every sentence add value that cannot be found in a generic web search? Remove obvious advice. Keep only the project-specific decision.
@@ -196,7 +197,7 @@ If any check fails, revise and re-run this phase before proceeding.
 ### Phase 8: Write Files
 
 1. Create the Policy file at `[xdrs-root]/[scope]/[type]/[subject]/[number]-[short-title].md` (default root: `.xdrs/`).
-2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist).
+2. Add an entry to `[xdrs-root]/[scope]/[type]/index.md` (create the file if it does not exist); keep its description <15 words.
 3. Add or verify the scope entry in the Policy root `index.md` (exactly one link per scope; when the scope index declares `extends-only: true`, append the tag `` `extends-only` `` right after the link and make sure the legend line is present, see `_core-adr-policy-022`).
 4. If significant research was produced or already exists, link it from the Policy `## Considered Options` section.
 5. If concise rules, examples, or do/don't bullets help readers apply the decision correctly, add them inside `### Details` without turning the Policy into a long procedure.

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

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDRS document.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -47,6 +47,8 @@ Guides the creation of a Marp Markdown slide presentation that supports an exist
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 0: Prerequisites Gate — MUST complete before writing
 
 Identify the target scope from the parent document's path or the user's request; use `_local` if none is specified. Then run the prerequisites gate from the shared module at `.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md`. Substitute `[DOCUMENT TYPE]` with `presentation`.
@@ -135,7 +137,7 @@ Rules:
 - The first line of YAML frontmatter must be `marp: true`. Additional Marp keys (`theme`, `paginate`, `header`, `footer`) may be added after.
 - Use `---` as the slide separator (standard Marp syntax).
 - The last slide must contain links back to the parent document and any other related documents.
-- Minimize text per slide. Prefer visual elements and short statements.
+- Minimize text per slide: each slide <80 words. Prefer visual elements and short statements.
 - Stress central questions, answers, doubts, decisions, and risks from the parent document.
 - No emojis.
 - Use relative paths for all links.

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

@@ -6,8 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a research document that backs a decision.
 metadata:
   author: flaviostutz
-  version: "1.4.0"
-  updated: 2026-09-19
+  version: "1.5.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -30,7 +30,7 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 #### Contents
 
-- A standalone IMRAD research document.
+- A standalone IMRAD research document (<5000 words).
 
 #### Changes
 
@@ -50,6 +50,8 @@ This skill is interactive by design. Ask clarifying questions to the user at eac
 
 ## 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.
@@ -129,39 +131,39 @@ Use the mandatory template from `006-research-standards`:
 
 ## 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.
-Use visuals, bullets, graphs, or diagrams when helpful. Goal: explain the investigated problem, operating context, constraints, and why the subject matters. Under 700 words.]
+Use visuals, bullets, graphs, or diagrams when helpful. 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.
-Use figures, tables, or bullets when useful. 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.]
+Use figures, tables, or bullets when useful. 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
 
 [A list of all cited literature, websites, tutorials, documentation, discussions, and related artifacts. Goal: make all cited sources and supporting artifacts traceable.]
 
-- [Related Policy or artifact](relative/path.md) - Why it matters
-- [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters
+- [Related Policy or artifact](relative/path.md) - Why it matters (<15 words)
+- [Another related Policy if this research informed multiple decisions](relative/path.md) - Why it matters (<15 words)
 ```
 
 Rules:
@@ -175,13 +177,13 @@ Rules:
 - For diagrams and non-Markdown assets, follow `_core-adr-policy-020`: prefer plain Markdown tables/lists and bullet points 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 research genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/researches/.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 `/`.
-- Keep section word limits within the standard and keep the document under 5000 words total unless the introduction explicitly states that a very detailed analysis is required.
+- Keep every section within its template cap; exceed the document cap only when the introduction explicitly states that a very detailed analysis is required.
 
 ### Phase 8: Check Section Goals
 
 Before the final review, verify each section against its specific goal:
 
-1. **Abstract goal**: Does it let a quick technical reader understand the question, method, main result, and takeaway, in one paragraph and under 200 words?
+1. **Abstract goal**: Does it let a quick technical reader understand the question, method, main result, and takeaway, in one paragraph and within its cap?
 2. **Introduction goal**: Does it explain the investigated problem and context, stay within scope, and end with `Question: ...?`?
 3. **Methods goal**: Could an experienced professional reproduce the important parts that materially affect the conclusion?
 4. **Results goal**: Are the findings concrete and minimally interpreted, with comparisons and pros/cons when multiple options exist?
@@ -279,8 +281,8 @@ If any check fails, revise before continuing.
 ### Phase 11: Write Files
 
 1. Create the research file at `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`.
-2. Add an entry to `.xdrs/[scope]/[type]/index.md`.
-3. Add back-references from the related Policy, article, or skill when the relationship is important for discovery.
+2. Add an entry to `.xdrs/[scope]/[type]/index.md`, with a description <15 words.
+3. Add back-references (<15 words each) from the related Policy, article, or skill when the relationship is important for discovery.
 4. Evaluate whether the scope index at `.xdrs/[scope]/index.md` should be updated to reflect the new research. If the scope index does not exist, create it following article standards and the scope index rules in `_core-adr-policy-001`.
 
 ### Phase 12: Verify with Lint

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

@@ -6,8 +6,8 @@ description: >
   Activate this skill when the user asks to create, add, or write a new skill, agent skill, or SKILL.md file.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -28,7 +28,7 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 #### Contents
 
-- A complete SKILL.md file
+- A complete SKILL.md file (<7000 words)
 
 #### Changes
 
@@ -48,6 +48,8 @@ Guides the creation of a well-structured skill package by following `_core-adr-p
 
 ## 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.
@@ -109,29 +111,29 @@ metadata:
 
 #### Required
 
-[Bare-minimum bullets needed to invoke the skill, or a single "None" bullet. Each under 10 words.]
+[Bare-minimum bullets needed to invoke the skill, or a single "None" bullet. Each <10 words.]
 
 #### Optional
 
-[Extra helpful-context bullets, or a single "None" bullet. Each under 10 words.]
+[Extra helpful-context bullets, or a single "None" bullet. Each <10 words.]
 
 ### Outputs
 
 #### Contents
 
-[End-objective files/chat text produced, or a single "None" bullet. Each under 10 words.]
+[End-objective files/chat text produced, or a single "None" bullet. Each <10 words. Append "(<N words)" or "(uncapped: <reason>)" to natural-language items not capped in a template or step, e.g. "Release notes (<300 words)". Code and structured data get no marker.]
 
 #### Changes
 
-[End-objective external system mutations, or a single "None" bullet. Each under 10 words.]
+[End-objective external system mutations, or a single "None" bullet. Each <10 words.]
 
 ### Halt Conditions
 
-[This skill's specific stop-before-completing triggers, or a single "None" bullet. Each under 10 words.]
+[This skill's specific stop-before-completing triggers, or a single "None" bullet. Each <10 words.]
 
 ### User Interaction
 
-[Optional. Human-in-the-loop exchanges during execution: clarifying questions or approval gates, or a single "None" bullet. Each under 10 words. Omit the whole section if none apply.]
+[Optional. Human-in-the-loop exchanges during execution: clarifying questions or approval gates, or a single "None" bullet. Each <10 words. Omit the whole section if none apply.]
 
 ### Runtime Requirements
 
@@ -139,8 +141,10 @@ metadata:
 
 ## Instructions
 
+[Blanket cap line, e.g. "Keep every question and intermediate message <100 words and the final summary <150 words."]
+
 ### Phase 1: …
-[Step-by-step agent instructions organized into named phases. Use imperative language and include verification or acceptance criteria at the end of the task or major phases.]
+[Step-by-step agent instructions organized into named phases. Use imperative language and include verification or acceptance criteria at the end of the task or major phases. State "<N words" in each step that produces natural-language content not covered by the blanket line or a template.]
 
 ## Examples
 
@@ -166,13 +170,14 @@ Rules:
 - The `description` field must state both *what* the skill does and *when* to activate it.
 - Keep the skill task-oriented. It should have a clear starting trigger and a concrete ending result.
 - Mention tools or prerequisites when they are required to complete the task reliably.
+- Declare a "<N words" cap, or "(uncapped: <reason>)", exactly once for every natural-language content the skill generates, per **Generated content caps** in `_core-adr-policy-003`.
 - Do not duplicate content from referenced Policies — link instead.
 - Do not present the skill itself as policy; mandatory behavior must come from referenced Policies or other policy artifacts.
 - When the skill depends on Policies, make the activation logic and instructions consistent with the Policy metadata so the skill does not operationalize inactive or out-of-scope decisions.
 - 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 `SKILL.md` genuinely needs local images or supporting files, store them in `.xdrs/[scope]/[type]/[subject]/skills/[skill-name]/.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 `/`.
-- No emojis. Lowercase filenames. Target under 7000 words.
+- No emojis. Lowercase filenames.
 
 ### Phase 5: Review the Draft
 
@@ -180,12 +185,13 @@ Before writing files, verify:
 
 1. **Activation criteria**: Is it unambiguous when this skill loads vs. when it should not?
 2. **Completeness**: Does every phase have actionable steps?
-3. **Length**: Under 7000 words? Trim verbose explanations.
+3. **Length**: Within the SKILL.md word cap? Trim verbose explanations.
 4. **Duplication**: Does this overlap an existing skill? If yes, revise.
 5. **References**: Are all related XDRs and skills linked, including the cases where the skill operationalizes multiple XDRs?
 6. **Anti-Patterns**: Does the skill include at least 3 genuine, domain-specific `## Anti-Patterns` entries (not generic filler)?
 7. **Required sections**: Does `## Overview` contain nested `### Inputs` (Required/Optional bullets), `### Outputs` (Contents/Changes bullets), and `### Halt Conditions` listing this skill's specific stop triggers — each bullet under 10 words or a single "None"?
 8. **Meta-policy compliance**: Run the shared module at `.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md`. Substitute `[DOCUMENT]` with `skill`.
+9. **Output caps**: Does every natural-language content the skill generates (files, messages, questions, summaries, external posts) have exactly one "<N words" cap or "(uncapped: <reason>)" marker, with code and structured data unmarked?
 
 If any check fails, revise before continuing.
 
@@ -213,6 +219,8 @@ Follow the lint verification steps in `.xdrs/_core/adrs/principles/skills/.asset
 - MUST include a References section linking to `003-skill-standards`.
 - MUST include nested `### Inputs`, `### Outputs`, and `### Halt Conditions` subsections inside `## Overview` with skill-specific content.
 
+## Examples
+
 **Input**: "Create a skill to help debug CI pipelines"
 - Type: EDR (engineering workflow)
 - Scope: `_local`

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

@@ -5,8 +5,8 @@ description: >
   Activate this skill when the user asks to create or write any XDRS element.
 metadata:
   author: flaviostutz
-  version: "1.0.0"
-  updated: 2026-09-19
+  version: "1.1.0"
+  updated: 2026-09-24
 ---
 
 ## Overview
@@ -47,6 +47,8 @@ Routes the request to the appropriate XDRS authoring skill based on the type of
 
 ## Instructions
 
+Keep every question and intermediate message <100 words and the final summary <150 words.
+
 ### Phase 1: Infer Document Type
 
 1. Infer the target document type from the user's request and context using the mapping below. Do not ask the user unless the type is genuinely ambiguous after reading the request.

package/README.md

@@ -12,7 +12,7 @@ After preparation those elements can be downloaded anywhere and used to compose
 
 Policies capture Architectural (ADR), Business (BDR), and Engineering (EDR) decisions. As organizations grow, hundreds of decisions accumulate across teams, levels, and domains. Without a consistent structure, AI agents cannot efficiently locate the right decisions for a given context, and humans cannot maintain or evolve them sustainably.
 
-This project defines a standard for organizing XDRS that satisfies the following requirements.
+This project defines a standard for organizing XDRS that addresses this problem (see [Features](#features)).
 
 ## Overview
 
@@ -35,6 +35,20 @@ The XDRS framework separates these concerns into different document types, each
 - **Articles** — Synthetic explanatory texts that combine information from multiple Policies, Research documents, and Skills around a specific topic or audience. They never replace Policies as source of truth.
 - **Initiatives** — Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Initiatives have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts.
 
+```mermaid
+flowchart LR
+    DR["Raw Decision Record<br/>ADR / BDR / EDR"]
+    DR -- why --> R[Research]
+    DR -- what --> P["Policy<br/>source of truth"]
+    DR -- how --> S[Skill]
+    DR -- when --> I["Initiative<br/>ephemeral"]
+    DR -- view --> A[Article]
+    R -. backs .-> P
+    S -. complies with .-> P
+    I -. implements .-> P
+    A -. explains .-> P
+```
+
 The compilation process of a raw Decision Record is to distribute it into those different documents and create links between them. You can also use the framework standalone, generating these elements individually directly during the writing process without starting from a raw Decision Record.
 
 ## Getting started
@@ -43,9 +57,11 @@ The compilation process of a raw Decision Record is to distribute it into those
 
 2. On the workspace root folder, run `npx xdrs-core`
 
-   The basic xdrs tooling should be installed in your workspace along with:
-     - AGENTS.md pointing to the Policies structure
-     - XDRS related skills and prompts for Copilot
+   This installs:
+     - `AGENTS.md` instructing agents to consult Policies before every request
+     - `.xdrs/_core/` with the framework Policies, skills and articles
+     - `.xdrs/index.md` root index, installed unmanaged so you own it and list your scopes there
+     - `.agents/skills/review` and `.agents/skills/write-xdrs-doc` symlinks so agents discover the main skills
 
 3. Run a prompt such as:
 
@@ -53,10 +69,28 @@ The compilation process of a raw Decision Record is to distribute it into those
 
    > Compile ADR 043-python-package-manager into the XDRS structure
 
+   > Review my changes against our Policies
+
+4. Validate the result with `npx xdrs-core lint .`
+
+### Bundled skills
+
+| Skill | Purpose |
+|---|---|
+| `write-xdrs-doc` | Router: infers the document type from your request and delegates to the right skill below |
+| `write-policy`, `write-skill`, `write-article`, `write-research`, `write-initiative` | Author each XDRS element type |
+| `write-presentation` | Create Marp slide decks backing XDRS documents |
+| `review` | Review code or documents against applicable Policies and report violations |
+| `compile-scope` | Fetch and compile a `compiled`-type scope from external sources |
+
+See [.xdrs/_core/adrs/index.md](.xdrs/_core/adrs/index.md) for the full list of `_core` Policies, skills and articles.
+
 ## Examples
 
 - [examples/basic-usage](examples/basic-usage) shows the minimal consumer flow for installing the packaged `xdrs-core` tarball, extracting files, checking drift, and linting the resulting tree.
 - [examples/mydevkit](examples/mydevkit) shows a reusable extension package that uses `.filedistrc` as its package config source, composes `xdrs-core`, and ships its own named scope.
+- [examples/typed-scope](examples/typed-scope) shows `core`, `reference`, `platform` and `_local` scopes, a custom `business-area` scope type, and `follows`.
+- [examples/load-test](examples/load-test) generates a large synthetic XDRS tree to exercise the linter at scale.
 - For a fuller real-world package built on the same distribution model, see [flaviostutz/agentme](https://github.com/flaviostutz/agentme).
 
 
@@ -66,7 +100,7 @@ The compilation process of a raw Decision Record is to distribute it into those
 
 Different teams at different organizational levels make decisions that apply to different audiences. XDRS are organized by scope (e.g. `_core`, `business-x`, `business-y-mobileapp`) so that each team owns its own decision space. Scopes can extend or override policies from broader scopes, with explicit precedence rules: scopes listed later in an index override those listed earlier.
 
-### Scope types and `follows`
+### Scope types
 
 Every scope declares a `scope-type` in its `index.md` frontmatter. The six built-in types are `core`, `reference`, `platform`, `compiled`, `standard`, and `_local`, each with different governance rules. Custom types (e.g. `business-area`) can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope.
 
@@ -79,11 +113,7 @@ Every scope declares a `scope-type` in its `index.md` frontmatter. The six built
 | `standard` | Business areas, products, teams, or any general-purpose scope. Default type when nothing else fits. | Any valid scope name (e.g. `checkout`, `mobile-app`) | 4th |
 | `_local` | Workspace-local overrides. Reserved exclusively for the `_local` scope. Never distributed. | `_local` (reserved) | last |
 
-**`core` scopes** carry meta-policies — authoring standards, scope-type definitions, and governance conventions. `_core` is the built-in foundation; teams add their own `core` scope (e.g. `myorg-core`) to extend it with organisation-level standards. A `core`-type scope MUST NOT contain consumable policies intended for other teams to follow.
-
-**`reference` scopes** hold read-only material to adopt or map against: industry frameworks, regulatory requirements, vendor best-practice patterns, business procedure standards. Content describes how something should be done — not what is currently running.
-
-**`platform` scopes** document what already exists and is ready to use. A scope is of type `platform` when its content describes a live operational capability — what is available, how to access it, and what constraints apply.
+`_core` is the built-in `core` scope; teams can add their own (e.g. `myorg-core`) with organisation-level authoring standards.
 
 **`compiled` scopes** hold policies compiled directly from external authoritative sources. All content must trace back to the source; no invented content is allowed. A `compiled` scope requires a local meta-policy with source URLs and compilation configuration, and uses the `compile-scope` skill to fetch, compile, and keep content up to date. The `compiled` type may be combined with another type (e.g. `scope-type: compiled, reference`) when the combined type's governance also applies.
 
@@ -102,9 +132,7 @@ Include A01–A10 risk entries only.
 
 By default, fetched and selected source content persists under `.assets/sources/[name]/` so later compilations can re-sync incrementally instead of always refetching; set `Source storage: temporary` in `## Sync Settings` to discard the bulk content after each run instead (only the per-source tracking file persists in that mode). Either way, `.assets/sources/` content is never authoritative on its own — only the compiled policies are.
 
-**`standard` scopes** are the default. Use them for team, product, or business-area scopes that do not fit the other types.
-
-**`_local` scopes** hold workspace-specific content such as local tooling decisions, transition overrides, or temporary decisions. This content is never packaged or distributed.
+### Scope relationships: `follows` and `extends`
 
 The `follows` field in a scope's `index.md` links it to one or more `core` scopes whose standards it must respect (beyond `_core`). This models organisational hierarchies: a team scope can follow a business-area `core` scope, which in turn follows `_core`.
 
@@ -118,11 +146,37 @@ description: Checkout team decisions
 ---
 ```
 
-The recommended ordering in `.xdrs/index.md` is: `core → reference → platform → compiled/standard → _local`. Scopes listed later override earlier ones on the same topic.
+The `extends` field makes a scope inherit all **policy documents** (not skills, articles, research or initiatives) of other scopes, as if authored locally. Use it to adopt a `reference` scope and override only what differs. When scopes are related by `extends`, the chain decides conflicts instead of root index ordering. A scope cannot list the same scope in both `follows` and `extends`, cannot extend `_core`/`_local` or itself, and cannot form cycles.
+
+```yaml
+# .xdrs/payments/index.md
+---
+scope-type: standard
+name: payments
+extends: ecomm-ref-payments   # inherit its policies, override locally when needed
+---
+```
+
+A scope can also hold its own authoring rules in a local meta-policy (`[type]/principles/NNN-core.md`) without creating a separate `-core` scope. See [_core-adr-policy-010](.xdrs/_core/adrs/principles/010-scope-governance.md) for the full precedence chain.
+
+```mermaid
+flowchart LR
+    ecore["ecomm-core<br/>core"]
+    ref["ecomm-ref-payments<br/>reference, extends-only"]
+    checkout["checkout<br/>standard"]
+    payments["payments<br/>standard"]
+    local["_local<br/>workspace only"]
+
+    checkout -- "follows: respects authoring rules" --> ecore
+    payments -- follows --> ecore
+    payments -- "extends: inherits policies" --> ref
+    local -- overrides --> checkout
+    local -- overrides --> payments
+```
 
-Custom scope types can be introduced by adding a `{type}-scope-type` policy to any `core`-type scope. The `checkout` scope in [examples/typed-scope](examples/typed-scope) uses a custom `business-area` type defined in `ecomm-core`.
+`_core` applies implicitly to every scope, so it is never listed in `follows` or `extends`.
 
-See [examples/typed-scope](examples/typed-scope) for a full working example covering all five scope types and a custom `business-area` type.
+The `checkout` scope in [examples/typed-scope](examples/typed-scope) uses a custom `business-area` type defined in `ecomm-core` and declares `follows: ecomm-core`.
 
 ### Scope activation
 
@@ -158,13 +212,27 @@ XDRS packages are versioned and distributed via the npm registry. This allows te
 
 The folder layout, file naming, and document format are designed so that AI agents can efficiently work with hundreds of decisions:
 
-- Each Policy is a small, focused Markdown file (target under 1300 words), covering a set of rules or statements.
+- Each Policy is a small, focused Markdown file (target under 1300 words, hard limit 2600), covering a set of rules or statements.
+- Policies that need external citation can expose individually numbered rules (e.g. `_core-adr-policy-010.28-extends-disjoint`), see [_core-adr-policy-008](.xdrs/_core/adrs/principles/008-policy-structured-standards.md).
 - The canonical index per scope and type lists all XDRS elements with short descriptions, enabling agents to identify relevant records without reading every file.
 - The root index at `.xdrs/index.md` provides a single entry point for discovery.
 - Policy metadata gives agents a first-pass filter: check `valid-from` for the convergence date, then check `apply-to`, and finally the decision text itself to confirm the decision should be used in the current context. All documents present in the collection are considered active.
 - Decisions cross-reference each other by Policy ID rather than duplicating content, keeping individual files concise.
 - Subject folders reduce the search space when a query maps to a known domain.
 
+How an agent finds the Policies that apply to a request:
+
+```mermaid
+flowchart LR
+    Q([Request]) --> AG[AGENTS.md]
+    AG --> RI[".xdrs/index.md<br/>scope order and activation"]
+    RI --> TI["scope type indexes<br/>one line per document"]
+    TI --> F{"apply-to and<br/>valid-from match?"}
+    F -- yes --> P["Read Policy<br/>and linked Skills"]
+    F -- no --> X[Skip]
+    P --> W([Act and verify])
+```
+
 ### Multi-agent framework support
 
 Policies and skills must be usable by any type of AI agent, not only coding agents (e.g. GitHub Copilot, Cursor, Cline). General-purpose agent frameworks such as LangGraph, CrewAI, AutoGen, and similar orchestration runtimes must be able to consume Policies without relying on IDE-specific tooling or conventions.
@@ -197,15 +265,13 @@ This is especially important for BDRs: because business rules govern decisions t
           .assets/
 ```
 
-Document types:
+Types:
 
 - **ADR** - Architectural Decision Record: architectural and technical decisions
 - **BDR** - Business Decision Record: business process and strategy decisions
 - **EDR** - Engineering Decision Record: engineering workflow and tooling decisions
-- **Research** - Exploratory support material used while evaluating or updating a decision. Research captures constraints, findings, options, and proposal tradeoffs, but it is not the source of truth.
-- **Skills** - Step-by-step procedural guides that can be followed by humans, AI agents, or both. Must comply with Policies, but add the execution detail they lack. Skills are not mandatory by themselves unless referenced by a Policy or another policy artifact. A skill may start as a fully manual human procedure and evolve incrementally toward partial or full AI automation without being restructured. Co-located with the Policies they implement inside `skills/` sub-directories.
-- **Articles** - Synthetic views that explain concepts or combine information from multiple Policies, Research documents, and Skills into a coherent text for a specific topic or audience. Articles are not the source of truth; Policies take precedence when there is a conflict. Useful as navigational indexes that link related artifacts around a specific aspect.
-- **Initiatives** - Ephemeral execution documents that describe a problem, proposed solution, and the approach and activities needed to solve it. Initiatives have a clear start and end and must be deleted after full implementation. Lasting outputs are captured as Policies, Skills, Articles, or other artifacts. Co-located with Policies inside `initiatives/` sub-directories.
+
+Each type has a fixed set of allowed subjects (e.g. `principles`, `application`, `data` for ADRs), see [_core-adr-policy-016](.xdrs/_core/adrs/principles/016-policy-subjects.md). Element types are described in [XDRS elements](#xdrs-elements).
 
 See [.xdrs/index.md](.xdrs/index.md) for the full list of active policies.
 
@@ -232,38 +298,37 @@ A project that wants to follow a scope's decisions adds the corresponding npm pa
 
 Multiple scope packages can be combined in the same workspace by listing them as separate dependencies. Scope precedence (defined in `.xdrs/index.md`) determines which decisions take effect when scopes overlap.
 
-```
-[Scope repo] --> npm publish --> [npm registry] --> npm install --> [Project workspace]
-  .xdrs/[scope]/                  versioned pkg                    .xdrs/[scope]/
-    adrs/ bdrs/ edrs/                                                adrs/ bdrs/ edrs/
-    [subject]/                                                        [subject]/
-      *.md                                                              *.md
-      researches/                                                       researches/
-      skills/                                                           skills/
-      articles/                                                         articles/
+```mermaid
+flowchart LR
+    subgraph owners[Scope owner repositories]
+        A[".xdrs/ecomm-core/"]
+        B[".xdrs/checkout/"]
+    end
+    A -- pack and publish --> NPM[("npm registry<br/>versioned packages")]
+    B -- pack and publish --> NPM
+    NPM -- "install (filedist)" --> WS
+    subgraph WS[Project workspace]
+        M[".xdrs/_core, ecomm-core, checkout<br/>managed, pinned in .filedist.lock"]
+        X[".xdrs/index.md<br/>owned by the project"]
+        L[".xdrs/_local<br/>never published"]
+    end
+    WS -- "xdrs-core lint / check" --> CI([CI])
 ```
 
 ## CLI
 
 The published package exposes the `xdrs-core` CLI.
 
-- Bootstrap or extract managed XDRS files with the existing `filedist`-backed commands such as `npx -y xdrs-core extract` and `npx -y xdrs-core check`.
-- Lint a Policy tree with `npx -y xdrs-core lint .`. By default, scopes whose files are listed in the workspace root `.filedist.lock` file are treated as external and skipped; use `--all` to include them.
+- `npx -y xdrs-core` (or `install`) installs or updates the managed XDRS files; `npx -y xdrs-core check` fails if managed files drifted from the package. Both are delegated to [filedist](https://github.com/flaviostutz/filedist) (run `--help` for all options).
+- `npx -y xdrs-core lint [path]` validates the XDRS tree. Scopes listed in the workspace `.filedist.lock` are treated as external and skipped; use `--all` to include them.
 
-The `lint` command reads `./.xdrs/**` from the given workspace path and checks common consistency rules, including:
+The `lint` command reads `.xdrs/**` (or `[path]` directly when it contains an `index.md`) and reports errors citing the violated Policy rule. It checks:
 
-- allowed scope, type, and subject folder structure
-- Policy numbering uniqueness per `scope/type`
-- article numbering uniqueness per `scope/type/subject/articles`
-- research numbering uniqueness per `scope/type/subject/researches`
-- initiative numbering uniqueness per `scope/type/subject/initiatives`
-- initiative `Expected end date:` field presence and ISO date format
-- canonical index presence and link consistency
-- root index coverage for all discovered canonical indexes
-- root index completeness: every scope folder linked exactly once, activation tags (`extends-only`, `disabled`) valid, coherent with the scope's `extends-only` field, and explained by the legend line when used
-- Policy metadata section placement and `valid-from` / `apply-to` field format
-- local markdown links between Policy documents, skills, articles, researches, and initiatives (excluding fenced code blocks)
-- local image and `.assets/` links resolving inside the sibling `.assets/` folder for each document
+- **Structure**: allowed scope, type and subject folders; canonical indexes present and linking every document; root index linking every scope exactly once with valid activation tags
+- **Numbering**: unique numbers per element type, subject-based numbering ranges ([_core-adr-policy-017](.xdrs/_core/adrs/principles/017-policy-numbering-ranges.md))
+- **Document format**: Policy metadata (`valid-from`, `apply-to`), structured rule syntax, initiative `Expected end date`, skill `README.md`, word limits per element type
+- **Scope governance**: scope-type definitions and naming conventions, `follows`/`extends` targets, cycles and conflicts, local meta-policies, `compiled` scope meta-policy
+- **Links**: local markdown links and `.assets/` references resolve (fenced code blocks are ignored)
 
 Examples:
 
@@ -279,30 +344,61 @@ The package also exposes a reusable behavior-test library for Jest or any other
 
 Main exports:
 
-- `testPrompt(config, inputPrompt, judgePrompt)` runs the task prompt, evaluates the result in a fresh judge session, and returns an empty string on success or a markdown bullet list on failure.
-- `runPromptTest(config, inputPrompt, judgePrompt)` returns the structured result object when you need access to captured output and the agent-reported changed file list.
-- `copilotCmd(workspaceRoot)` returns a ready-to-use `promptCmd` template for the Copilot CLI in headless mode (`--autopilot`, full tool/url permissions, and `--no-ask-user`). The library uses that same command template for both the task and judge phases. If `workspaceRoot` is omitted it defaults to the current git repository root.
-- `config.workspaceRoot`, when set, is the authoritative workspace under test. If omitted, the library uses the current git repository root.
+- `async testPrompt(config, inputPrompt, judgePrompt, id?, verbose?)` runs the task prompt, evaluates the result with a judge prompt, and resolves to an empty string on success or a markdown bullet list of findings on failure. Passing results are cached (see below).
+- `async runPromptTest(config, inputPrompt, judgePrompt, verbose?)` resolves to the structured result (`passed`, `findings`, `taskOutput`, `agentReportedChanges`, `contextFiles`, `workspace`), without caching.
+- `copilotCmd(workspaceRoot?)` returns a partial config for the Copilot CLI in headless mode (`promptCmd`, `promptCmdContinueFlag`, `workspaceFilter`, `workspaceExclude`). Spread it into your config. `workspaceRoot` defaults to the current git repository root.
+
+Main `config` fields:
+
+| Field | Description |
+|---|---|
+| `promptCmd` | Command as string array or JSON array string; must include a `{PROMPT}` placeholder |
+| `promptCmdContinueFlag` | Flag inserted before the prompt to continue the previous session (e.g. `--continue`) |
+| `workspaceRoot` | Workspace under test (default: current git repository root) |
+| `workspaceMode` | `copy` (default, runs in a temp copy honoring `.gitignore`, without git metadata) or `in-place` |
+| `workspaceFilter` / `workspaceExclude` | Globs selecting which files are copied |
+| `taskTimeoutMs` / `judgeTimeoutMs` | Timeouts per phase |
+| `env` | Extra environment variables for the command |
+| `reportFile` | Cache file of passing tests (default: `<test-file>.report` next to the calling test); `null` disables caching |
+| `checkOnly` | Do not run prompts; fail unless a matching passing entry exists in `reportFile` (useful in CI) |
+| `model` | Model name, included in the cache hash |
 
 Execution model:
 
-- phase 1 runs the task prompt and captures final output text plus the files the agent says it changed
-- phase 2 runs an independent judge prompt in a fresh invocation of `promptCmd` against the original task prompt, task output, the agent-reported changed file list, and the current workspace state
-- the judge trusts that reported file list as the authoritative change report and reads file contents from the workspace directly when needed
-- when `workspaceMode: 'copy'` is used, the temporary workspace honors nested `.gitignore` rules and skips git metadata files during the copy
-
-`promptCmd` accepts either a string array or a JSON array string and must include a `{PROMPT}` placeholder.
+1. **Task**: runs the task prompt and captures the final output
+2. **Files**: continues the same session to collect the files the agent read and changed
+3. **Judge**: continues the same session and evaluates the task output, changed files and workspace state against the judge prompt
+
+A passing result is stored in `reportFile` with a hash of the model, prompts and the files the agent read. Later runs are skipped while that hash is unchanged, so tests re-run only when relevant context changes.
+
+```mermaid
+sequenceDiagram
+    participant T as Test
+    participant L as testPrompt
+    participant A as Agent CLI
+    T->>L: testPrompt(config, task, judge)
+    alt hash matches reportFile entry
+        L-->>T: empty string (cached pass)
+    else run
+        L->>A: 1. task prompt (temp workspace copy)
+        L->>A: 2. continue: list files read and changed
+        L->>A: 3. continue: judge prompt
+        A-->>L: pass and findings
+        L->>L: store hash when passed
+        L-->>T: empty string or findings markdown
+    end
+```
 
 Example with Jest:
 
 ```js
 const { copilotCmd, testPrompt } = require('xdrs-core');
 
-test('creates hello.md', () => {
-  const err = testPrompt(
+test('creates hello.md', async () => {
+  const err = await testPrompt(
     {
+      ...copilotCmd(process.cwd()),
       workspaceRoot: process.cwd(),
-      promptCmd: copilotCmd(process.cwd()),
       workspaceMode: 'copy'
     },
     "Create a nice markdown file at hello.md saying 'hello!'",

package/package.json

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