xdrs-core 0.46.3 → 0.48.0

package/.xdrs/_core/adrs/index.md

@@ -12,7 +12,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-policy-004](principles/004-article-standards.md) - **Article standards** — How to write synthetic views combining Policies, research, and skills
 - [_core-adr-policy-005](principles/005-semantic-versioning-for-xdrs-packages.md) - **Semantic versioning for XDRS packages** — How to version XDRS packages to communicate upgrade impact
 - [_core-adr-policy-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing Policy decisions
-- [_core-adr-policy-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
+- [_core-adr-policy-007](principles/007-initiative-standards.md) - **Initiative standards** — How to structure ephemeral execution initiatives that implement decisions
 - [_core-adr-policy-008](principles/008-policy-structured-standards.md) - **Policy structured standards** — How to expose individually referenceable numbered rules inside a Policy when external citation by identifier is required
 - [_core-adr-policy-009](principles/009-presentation-standards.md) - **Presentation standards** — How to structure Marp slide presentations that support XDRS documents
 - [_core-adr-policy-010](principles/010-scope-governance.md) - **Scope governance** — How to define custom scope types, scope-local standards, and how all governance mechanisms apply with their precedence chain
@@ -36,7 +36,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [003-write-skill](principles/skills/003-write-skill/SKILL.md) - **Write Skill** — create a new skill package
 - [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
 - [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
-- [006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
+- [006-write-initiative](principles/skills/006-write-initiative/SKILL.md) - **Write Initiative** — create a new initiative document
 - [007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDRS documents
 - [008-write-xdrs-doc](principles/skills/008-write-xdrs-doc/SKILL.md) - **Write XDRS Doc** — router skill; infers document type and delegates to the appropriate authoring skill
 - [009-compile-scope](principles/skills/009-compile-scope/SKILL.md) - **Compile Scope** — compiles or updates a `compiled`-type scope from its configured external sources

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

@@ -21,7 +21,7 @@ Provides clear ownership by scope, predictable navigation, and reusable decision
 
 ### Details
 
-A standard Decision Record normally combines several concerns in the same document: a reason (why, options considered), a policy (rules, what is the decision), a plan (consequences, when it will be implemented), a how-to (step-by-step how-to procedure), and a view on a topic. The XDRS framework separates these concerns into different document types: Policies as the source of truth for the core of the decision, Research for reasoning and evidence, Plans for implementation approach, Skills for execution procedures, and Articles for topic overviews. Supporting artifacts MAY explain, justify, or operationalize the policy, but they do not replace it. 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.
+A standard Decision Record normally combines several concerns in the same document: a reason (why, options considered), a policy (rules, what is the decision), an initiative (consequences, when it will be implemented), a how-to (step-by-step how-to procedure), and a view on a topic. The XDRS framework separates these concerns into different document types: Policies as the source of truth for the core of the decision, Research for reasoning and evidence, Initiatives for implementation approach, Skills for execution procedures, and Articles for topic overviews. Supporting artifacts MAY explain, justify, or operationalize the policy, but they do not replace it. 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.
 
 Policies can be of different kinds, depending on the nature of the decision:
 - BDR (Business Decision Record): Captures business process, product features, procedures and strategic decisions. Examples: business rules, product policies, customer service, business workflow, control frameworks for regulators for finance, product procedures and manuals, KYC requirements, business requirements in general
@@ -55,18 +55,18 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - `[xdrs-root]/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`
   - `[xdrs-root]/[scope]/[type]/[subject]/articles/[number]-[short-title].md`
-  - `[xdrs-root]/[scope]/[type]/[subject]/plans/[number]-[short-title].md`
+  - `[xdrs-root]/[scope]/[type]/[subject]/initiatives/[number]-[short-title].md`
 - Research, skills, and articles are part of the framework, but each has its own concept-specific standards in dedicated Policies. This Policy defines the shared framework baseline; `_core-adr-policy-002` defines the Policy document writing standard.
   - `_core-adr-policy-002` defines Policy standards (document writing)
   - `_core-adr-policy-003` defines skill standards
   - `_core-adr-policy-004` defines article standards
   - `_core-adr-policy-006` defines research standards
-  - `_core-adr-policy-007` defines plan standards
+  - `_core-adr-policy-007` defines initiative standards
 - For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). **Per-document-type `.assets/` paths:**
   - Policies in the subject root use `[xdrs-root]/[scope]/[type]/[subject]/.assets/`
   - Articles use `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/`
   - Research uses `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/`
-  - Plans use `[xdrs-root]/[scope]/[type]/[subject]/plans/.assets/`
+  - Initiatives use `[xdrs-root]/[scope]/[type]/[subject]/initiatives/.assets/`
   - Skills use `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/`
 - **Scopes:** 
   - Short name that defines a group or a package of XDRS
@@ -91,7 +91,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
     - `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 plans) 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. Scopes referenced only via `extends:` chains (not entry scopes in the root index) are exempt from the root index link requirement. `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` (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. Scopes referenced only via `extends:` chains (not entry scopes in the root index) are exempt from the root index link requirement. `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.
     - `license` (optional): SPDX identifier for the scope's content license.
     - `metadata` (optional): Arbitrary key-value map for additional scope metadata.
 - **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.
@@ -99,8 +99,9 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
 - MUST NOT use emojis
 - **Links:** Use relative paths for all links; MUST NOT use absolute paths starting with `/`.
 - **Indexes**
-  - Every document in the collection (Policies, skills, articles, research, and plans) MUST be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and MUST be added to the index or removed.
-  - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index MUST link to every Policy, skill, article, research, and plan under that type+scope.
+  - Every document in the collection (Policies, skills, articles, research, and initiatives) MUST be reachable through the index chain: root index → scope index → type index → document. A document that exists on disk but is not linked from its canonical type index is considered an orphan and MUST be added to the index or removed.
+  - Index files MUST NOT contain policy rules or normative requirements. Those MUST be placed in dedicated Policy documents. Indexes are navigation artifacts only: links and short descriptions.
+  - Keep a canonical type index with all documents of a certain type+scope in `[xdrs-root]/[scope]/[type]/index.md`. The type index MUST link to every Policy, skill, article, research, and initiative under that type+scope.
   - Canonical index requirements:
     - Organize XDRS documents by subject for easier navigation
     - Add a short description of what this scope is about (responsibilities, general worries, teams involved, link to discussion process, etc)
@@ -114,7 +115,7 @@ ADR and EDR share the same six technical subject names (see [`_core-adr-policy-0
   - The audience for the scope index are engineers, architects, or business analysts who want to check if the scope's contents are useful before diving into specific documents. Write a guided summary that helps them decide whether to explore further.
   - Focus on the most relevant content of the scope: what decisions are covered, what problems they address, and how the scope relates to other scopes.
   - At the end of the scope index, MUST add links to the canonical type indexes (`adrs/index.md`, `bdrs/index.md`, `edrs/index.md`) that exist within the scope.
-  - Whenever the contents of a scope change (new Policies, skills, articles, research, or plans are added, updated, or removed), evaluate whether the scope index SHOULD be updated to reflect the newer contents.
+  - Whenever the contents of a scope change (new Policies, skills, articles, research, or initiatives are added, updated, or removed), evaluate whether the scope index SHOULD be updated to reflect the newer contents.
 
 **Folder structure examples** (using the default `.xdrs/` root):
 - `.xdrs/business-x/edrs/platform/003-required-development-workflow.md`
@@ -128,8 +129,8 @@ subject/
 |-- articles/
 |   |-- 001-article.md
 |   `-- .assets/
-|-- plans/
-|   |-- 001-plan.md
+|-- initiatives/
+|   |-- 001-initiative.md
 |   `-- .assets/
 |-- researches/
 |   |-- 001-study.md
@@ -151,5 +152,5 @@ subject/
 - [_core-adr-policy-003 - Skill standards](003-skill-standards.md)
 - [_core-adr-policy-004 - Article standards](004-article-standards.md)
 - [_core-adr-policy-006 - Research standards](006-research-standards.md)
-- [_core-adr-policy-007 - Plan standards](007-plan-standards.md)
+- [_core-adr-policy-007 - Initiative standards](007-initiative-standards.md)
 - [_core-adr-policy-020 - Media and asset standards](020-media-and-asset-standards.md) - Diagram format preferences and non-Markdown asset rules

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

@@ -81,7 +81,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - When research exists for a decision, the Policy SHOULD mention the related research documents after the `## Considered Options` list.
 - MUST NOT use emojis in contents.
 - File names MUST be lowercase.
-- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
+- For diagram and asset rules in Policy documents, see [`_core-adr-policy-020`](020-media-and-asset-standards.md). Rule `02-policy-diagram-restrictions` below summarises the overall stance; the detailed rules are in policy 020.
 - Avoid using lengthy instructions on the Policy. If there are long and detailed instructions related to the Policy, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the Policy itself.
 - Policies SHOULD be under 1300 words long as a rule of thumb.
   - This is important to make them focused on a clear decision
@@ -99,6 +99,10 @@ When a policy's frontmatter includes `freeze-reference: true`, the policy MUST N
 
 Content-level checks that do not affect the policy's reference (required sections, word count, emojis, broken outgoing links, structured rule block format, normative language) remain enforced. The `valid-from` date is not taken into consideration when evaluating whether `freeze-reference` applies.
 
+#### 02-policy-diagram-restrictions
+
+Images and diagrams in Policy documents are subject to strict restrictions: images MUST NOT be used; diagrams SHOULD be avoided and are only allowed in direct and punctual cases where directly connected to the decision. Diagram content has no normative force and must not be used for enforcement. For full rules see [`_core-adr-policy-020`](020-media-and-asset-standards.md) rules `10` through `14`.
+
 **Policy template**
 
 All Policies MUST follow this template

package/.xdrs/_core/adrs/principles/004-article-standards.md

@@ -26,7 +26,7 @@ Articles are Markdown documents placed inside a subject folder alongside policie
 - The primary objective of an article is to make information available and accessible to humans. Good copywriting style, storytelling, clear organization, and clustering of related information are essential. Avoid repetitive content; each sentence SHOULD add new value.
 - Articles SHOULD stay under 2000 words (approximately a 10-minute read) to maximize reader engagement. When planning an article, keep it as small as possible. Break large subjects into separate chapters, each in its own article, so readers can consume and understand sections independently.
 - When a topic is broken into multiple articles, organize them as a **series**: each article MUST declare its position at the very top (e.g., `_This is article 2/4 of the "Engineering Practices" series._`) and MUST link to the previous and next articles in the series so readers can navigate the sequence without returning to an index.
-- Articles MUST NOT exceed 8000 words (hard limit). Move or point to detailed contents referenced in Policy decisions, researches, plans, or skills.
+- Articles MUST NOT exceed 8000 words (hard limit). Move or point to detailed contents referenced in Policy decisions, researches, initiatives, or skills.
 
 **Content and structure**
 

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

@@ -0,0 +1,140 @@
+---
+name: _core-adr-policy-007-initiative-standards
+description: Defines initiative document standards for describing problems, solutions, and activities. Use when creating or reviewing initiatives.
+apply-to: All initiative documents
+valid-from: 2025-01-01
+---
+
+# _core-adr-policy-007: Initiative standards
+
+## Context and Problem Statement
+
+Teams need a structured way to describe a problem, propose a solution, and lay out the approach and activities needed to solve it. Without a standard format, initiative documents drift in structure and completeness, making it hard to assess scope, track progress, and verify that an initiative was fully implemented.
+
+How should initiatives be structured and organized so they provide clear guidance for execution while remaining connected to the decisions, research, and skills they relate to?
+
+## Decision Outcome
+
+**Subject-level ephemeral initiative documents co-located with Policies**
+
+Initiatives are Markdown documents placed inside a subject folder alongside policies. They describe a problem, a proposed solution, and the approach to solve it. Initiatives have a clear start and end and a well-defined scope.
+
+### Details
+
+- Initiatives describe a problem (why), what we will do to solve the problem, and the approach and activities needed to solve it (how).
+- Initiatives are NOT the source of truth. When an initiative and a Policy disagree, the Policy takes precedence.
+- Initiatives are ephemeral. They MUST be deleted after full implementation. The lasting outputs of an initiative are actual actions or Decisions, Skills, Articles, Research documents, and other artifacts that result from execution.
+- Initiatives MAY be used to implement a certain Decision. They MAY also use Research documents to help with the planning process. Articles MAY be written on top of an initiative to give more context and connect more details present in other decisions and research to people involved in the initiative.
+- During the implementation of an initiative, new Decisions, Articles, Skills, Research documents, and even other Initiatives MAY be created. All related elements MUST be linked to each other.
+- An initiative can be high level, describing only one milestone, or more complex, describing a WBS (work breakdown structure) along with owners, multiple milestones in a tactical sequence, and checklists to verify completeness. Actual tasks performed by actors SHOULD be tracked in specialized software such as GitHub or Azure DevOps.
+- The total time to deliver an initiative SHOULD NOT be more than 2 years. If more time is needed, create a new initiative later with what was learned.
+- Initiatives MUST live under `initiatives/` inside the relevant subject folder: `.xdrs/[scope]/[type]/[subject]/initiatives/[number]-[short-title].md`
+- The `[subject]` component MUST be one of the allowed subjects for the chosen type. The required list of allowed subjects per type is defined in `_core-adr-policy-001`.
+- Initiatives MUST include an `Expected end date:` field in ISO format (YYYY-MM-DD) inside the `## Proposed Solution` section.
+- File names MUST be lowercase.
+- MUST NOT use emojis in initiative content.
+- For diagram format preferences and non-Markdown asset rules, see [`_core-adr-policy-020`](020-media-and-asset-standards.md).
+
+**Folder layout**
+
+```
+.xdrs/
+  [scope]/
+    [type]/
+      [subject]/
+        initiatives/
+          [number]-[short-title].md
+          .assets/
+```
+
+Examples:
+- `.xdrs/_local/adrs/principles/initiatives/001-checkout-performance.md`
+- `.xdrs/business-x/bdrs/product/initiatives/002-onboarding-redesign.md`
+
+**Initiative numbering**
+
+- Each initiative has a number unique within its `scope/type/subject/initiatives/` namespace.
+- Determine the next number by checking the highest number already present in that namespace.
+- MUST NOT reuse numbers of deleted initiatives. Gaps in the sequence are expected and allowed.
+
+**Initiative template**
+
+All initiatives MUST follow this template:
+
+```markdown
+# [scope]-[type]-initiative-[number]: [Short Title]
+
+## Executive Summary
+
+[Required. A summary of all sections below using bullet points, focused on the most important items. Under 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.
+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.
+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.]
+
+## 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.]
+
+## 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.]
+
+## 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.]
+
+## 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.]
+
+### Milestone 1: [Title]
+Owner: [name or team]
+Due date: YYYY-MM-DD
+
+[Description of the milestone goal.]
+
+**Acceptance checklist:** [optional]
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+
+**Key tasks:**
+- [Task description]
+
+**Risks:** [optional]
+- [Risk description] — Mitigation: [strategy]
+
+## Risks Identified
+
+[Optional. List of risks along with a short description and mitigation strategy. Under 1000 words.]
+
+## References
+
+- [Related Policy or artifact](relative/path.md) - Brief description of relevance
+```
+
+## Considered Options
+
+* (REJECTED) **Inline planning in Policies** — Embed planning details inside policies.
+  * Reason: Initiatives are ephemeral execution documents while Policies are lasting decisions. Mixing them bloats Policies and creates confusion about what to delete after execution.
+* (CHOSEN) **Subject-level initiatives folder co-located with Policies** — Keeps initiatives alongside the decisions they implement, with clear lifecycle expectations.
+  * Reason: Consistent with how skills, articles, and research are organized. The explicit deletion requirement after implementation keeps the document base clean.
+
+## References
+
+- [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Framework elements: types, scopes, subjects, folder structure
+- [_core-adr-policy-004 - Article standards](004-article-standards.md) - Companion artifact type for synthetic views
+- [_core-adr-policy-006 - Research standards](006-research-standards.md) - Companion artifact type for exploratory evidence
+- [006-write-initiative skill](skills/006-write-initiative/SKILL.md) - Step-by-step instructions for creating a new initiative

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -9,7 +9,7 @@ valid-from: 2025-01-01
 
 ## Context and Problem Statement
 
-Teams often need slide presentations to communicate decisions, research findings, plans, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the policies they support.
+Teams often need slide presentations to communicate decisions, research findings, initiatives, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the policies they support.
 
 How should slide presentations be structured, placed, and maintained within the XDRS framework so they remain consistent, discoverable, and always traceable to the documents they support?
 
@@ -21,7 +21,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
 
 ### Details
 
-- Slides are supporting media for XDRS documents. They MUST NOT exist as standalone artifacts without a parent decision, research, article, or plan.
+- Slides are supporting media for XDRS documents. They MUST NOT exist as standalone artifacts without a parent decision, research, article, or initiative.
 - Slides MUST use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
   ```
   ---
@@ -35,7 +35,7 @@ Presentations are Markdown files in Marp format, stored in the `.assets/` folder
   - Example: parent `003-naming-conventions.md` produces `003-naming-conventions-slides.md` or `003-naming-conventions-slides-overview.md`.
 - Slide file names MUST NOT exceed 64 characters (including the `.md` extension).
 - Slide file names MUST be lowercase.
-- When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view MUST be written first. The slides then support that article, not the individual documents directly.
+- When slides refer to content from multiple decisions, initiatives, or research documents, an article explaining the combined view MUST be written first. The slides then support that article, not the individual documents directly.
 - Slides SHOULD contain minimal text. For diagrams, prefer ASCII art for very simple cases, Mermaid for flows and relationships, and draw.io when Mermaid is insufficient (see [`_core-adr-policy-020`](020-media-and-asset-standards.md)); for other slide content, prefer short bullet points, key short statements, and tables. Use longer text only when the exact wording MUST be evaluated by the audience (policies, texts under discussion, controls).
 - Slides SHOULD follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
 - Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.

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

@@ -118,7 +118,7 @@ Creating a local meta-policy is optional. It SHOULD be created when a scope has
 
 #### 18-local-content
 
-A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 04–05 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, plans, research).
+A local meta-policy SHOULD define the same kinds of instructions as a scope-type definition policy (rules 04–05 above): naming conventions for content in the scope, allowed content, forbidden content, and organisation rules. These instructions apply only to policy documents authored in this one scope; they do not govern non-policy artifacts (skills, articles, initiatives, research).
 
 #### 19-local-must-be-structured
 
@@ -192,7 +192,7 @@ A `## Conflicts` section MAY also document cross-scope-type incompatibilities fo
 
 #### 27-extends-declaration
 
-A scope MAY declare an `extends:` field in its `index.md` YAML frontmatter. The value MUST be a single scope name or a comma-separated list (YAML list format also valid). The field causes all **policy documents** (decision records only — skills, articles, research, and plans are NOT inherited) from the listed scopes to be treated as if authored in the extending scope. Valid for all scope types.
+A scope MAY declare an `extends:` field in its `index.md` YAML frontmatter. The value MUST be a single scope name or a comma-separated list (YAML list format also valid). The field causes all **policy documents** (decision records only — skills, articles, research, and initiatives are NOT inherited) from the listed scopes to be treated as if authored in the extending scope. Valid for all scope types.
 
 #### 28-extends-disjoint
 

package/.xdrs/_core/adrs/principles/020-media-and-asset-standards.md

@@ -1,6 +1,6 @@
 ---
 name: _core-adr-policy-020-media-and-asset-standards
-description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types. Use when choosing a diagram format or referencing any non-Markdown file in any XDRS document.
+description: Defines the preferred order for representing visual information and the rules for non-Markdown assets across all XDRS document types, including policy-document-specific restrictions on images and diagrams. Use when choosing a diagram format or referencing any non-Markdown file in any XDRS document.
 apply-to: All XDRS document types
 valid-from: 2026-08-06
 ---
@@ -34,10 +34,10 @@ Mermaid.js SHOULD be used for diagrams that require explicit visual representati
 draw.io SHOULD be used when Mermaid cannot adequately express the needed diagram — for example, custom visual layouts, freehand annotations, or combined view types that Mermaid does not support natively. draw.io SHOULD also be used when the diagram is expected to be edited directly by users in a graphical tool and its structure fits the draw.io editing model (e.g., boxes, connectors, swimlanes, layered layouts). draw.io diagrams MUST be saved as `.drawio` files in the sibling `.assets/` folder and referenced directly from the Markdown document.
 
 #### 05-svg-for-custom-vector
-Plain SVG MAY be used instead of draw.io when greater visual freedom is needed than draw.io provides, or when the diagram originates from tooling other than draw.io. SVG files MUST be stored in the sibling `.assets/` folder.
+Plain SVG MAY be used instead of draw.io when greater visual freedom is needed than draw.io provides, or when the diagram originates from tooling other than draw.io. SVG files MUST be stored in the sibling `.assets/` folder. SVG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 06-png-as-last-resort
-PNG (or other raster formats) MAY be used only when no vector or text-based format can adequately represent the content — for example, screenshots or photographs. PNG files MUST be stored in the sibling `.assets/` folder.
+PNG (or other raster formats) MAY be used only when no vector or text-based format can adequately represent the content — for example, screenshots or photographs. PNG files MUST be stored in the sibling `.assets/` folder. PNG MUST NOT be used in Policy documents (see rule `10-no-images-in-policies`).
 
 #### 07-assets-no-policy-content
 Asset files MUST NOT contain policy content. Diagrams and images do not carry mandatory or advisory language — they cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires. Assets MAY be used only to support the understanding of policy already stated in Markdown text; a visual that merely illustrates what the prose already says is acceptable, but any rule or constraint that exists only inside an asset file is invisible to policy and has no normative force. When in doubt, keep the content in Markdown.
@@ -48,7 +48,23 @@ Non-Markdown files (images, diagrams, schemas, JSON examples, binaries, or any o
 #### 09-assets-placement
 Non-Markdown files MUST live in the sibling `.assets/` folder next to the referencing document. The canonical per-document-type `.assets/` paths are defined in `_core-adr-policy-001`.
 
+#### 10-no-images-in-policies
+Images — including raster formats (PNG, JPEG, GIF, TIFF, and similar) and SVG files — MUST NOT be used in Policy documents. These formats cannot express MUST, SHOULD, or MAY obligations with the precision that prose requires, and their content cannot be systematically enforced during review.
+
+#### 11-diagrams-rare-in-policies
+Mermaid and draw.io diagrams SHOULD be avoided in Policy documents. They MAY be included only in direct and punctual cases where the diagram illustrates the core structural pattern or architecture that the policy decision itself mandates. A diagram that introduces context, detail, or explanation not already present in the policy prose MUST NOT be included.
+
+#### 12-diagrams-connected-to-decision
+Any diagram included in a Policy document MUST be directly connected to the policy decision described in that document. A diagram MAY include a simple illustrative example. Diagrams showing multiple usage examples, edge cases, or supplementary context MUST be placed in an article instead.
+
+#### 13-diagrams-not-normative-in-policies
+Content within diagrams in Policy documents — labels, annotations, and depicted relationships — MUST NOT be used for policy enforcement. Mandatory and advisory language within a diagram has no normative force. During authoring, diagram content MUST be checked for consistency with the policy prose; any inconsistency MUST be resolved before the policy is published.
+
+#### 14-articles-for-visual-explanation
+When additional visual explanation is needed for a Policy — such as multiple usage examples, context breakdowns, detailed walkthroughs, or educational material — an article MUST be written instead of adding more diagrams to the policy. Articles are the appropriate place for visual education about a policy; the policy itself MUST remain focused on the decision declaration.
+
 ## References
 
 - [_core-adr-policy-001 - XDRS standards](001-xdrs-standards.md) - Per-document-type `.assets/` canonical paths
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md) - Summary rule `02-policy-diagram-restrictions` that points to rules 10–14 here
 - [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Structured rule block format used in this policy

package/.xdrs/_core/adrs/principles/articles/.assets/001-xdrs-overview-slides.md

@@ -28,7 +28,7 @@ A standard Decision Record combines too many concerns in one file:
 |---------|-----|
 | Why we decided | Rationale / Research |
 | What we decided | Policy (the rule) |
-| How to implement it | Plan |
+| How to implement it | Initiative |
 | How to apply it daily | Skill |
 | Overview for readers | Article |
 
@@ -44,7 +44,7 @@ XDRS splits the concerns into focused, linkable documents:
 - **Research** — exploration, options, evidence
 - **Skill** — step-by-step execution procedure
 - **Article** — synthetic overview linking multiple artifacts
-- **Plan** — ephemeral execution plan, deleted after implementation
+- **Initiative** — ephemeral execution initiative, deleted after implementation
 
 ---
 
@@ -93,7 +93,7 @@ Synthetic views that **explain a topic** across multiple Policies, Research, and
 
 ---
 
-## Plans
+## Initiatives
 
 Describe a problem, proposed solution, and implementation approach.
 
@@ -111,7 +111,7 @@ Describe a problem, proposed solution, and implementation approach.
 | Research | What did we learn while evaluating options? |
 | Skill | How do we carry out work under this decision? |
 | Article | How do these artifacts fit together for a reader? |
-| Plan | What are we going to do, why, and how? |
+| Initiative | What are we going to do, why, and how? |
 
 ---
 
@@ -140,7 +140,7 @@ Articles appear when the **ecosystem around the decision** needs explanation.
         researches/
         skills/[N]-[name]/SKILL.md
         articles/
-        plans/
+        initiatives/
         .assets/              ← slides, diagrams
 ```
 
@@ -217,7 +217,7 @@ This creates `AGENTS.md` and `.xdrs/index.md` with the `_core` scope pre-loaded.
 
 # Summary
 
-- XDRS separates concerns: Policy, Research, Skill, Article, Plan
+- XDRS separates concerns: Policy, Research, Skill, Article, Initiative
 - Policies are the source of truth; all other artifacts support them
 - Scopes and indexes make decisions discoverable and overridable
 - AI agents consult XDRS before every request via `AGENTS.md`

package/.xdrs/_core/adrs/principles/articles/.assets/001-xdrs-overview.svg

@@ -88,9 +88,9 @@
   <text x="354" y="400" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Synthetic texts combining multiple policies and skills.</text>
   <text x="354" y="417" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Never replace policies as source of truth.</text>
 
-  <!-- Plans element -->
+  <!-- Initiatives element -->
   <rect x="334" y="437" width="412" height="64" rx="6" fill="#f8cecc" stroke="#b85450" stroke-width="1.5"/>
-  <text x="354" y="457" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Plans — When / How to roll out</text>
+  <text x="354" y="457" font-family="Arial,Helvetica,sans-serif" font-size="13" font-weight="bold" fill="#1a1a2e">Initiatives — When / How to roll out</text>
   <text x="354" y="474" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Ephemeral execution docs. Deleted after implementation.</text>
   <text x="354" y="491" font-family="Arial,Helvetica,sans-serif" font-size="11" fill="#444">Lasting outputs become Policies, Skills, or Articles.</text>
 
@@ -151,7 +151,7 @@
   <text x="38" y="722" font-family="Courier New,monospace" font-size="11" fill="#333">        researches/     ← Research docs</text>
   <text x="38" y="740" font-family="Courier New,monospace" font-size="11" fill="#333">        skills/         ← Skill packages</text>
   <text x="38" y="758" font-family="Courier New,monospace" font-size="11" fill="#333">        articles/       ← Article docs</text>
-  <text x="38" y="776" font-family="Courier New,monospace" font-size="11" fill="#333">        plans/          ← Plan docs</text>
+  <text x="38" y="776" font-family="Courier New,monospace" font-size="11" fill="#333">        initiatives/    ← Initiative docs</text>
   <text x="38" y="794" font-family="Courier New,monospace" font-size="11" fill="#333">        .assets/        ← Binary assets</text>
 
   <!-- ===== SECTION: GOVERNANCE MECHANISMS ===== -->

package/.xdrs/_core/adrs/principles/articles/001-xdrs-overview.md

@@ -16,10 +16,10 @@ The XDRS framework is built around a small set of artifact types that play diffe
 same decision system.
 
 A standard Decision Record normally combines several concerns in the same document: a reason
-(why, options considered), a policy (rules, core decision), a plan (consequences, implementation
+(why, options considered), a policy (rules, core decision), an initiative (consequences, implementation
 approach), a how-to (step-by-step procedure), and a view on a topic. The XDRS framework separates
 these concerns into different document types: Policies as the source of truth, Research for
-reasoning and evidence, Plans for implementation approach, Skills for execution procedures, and
+reasoning and evidence, Initiatives for implementation approach, Skills for execution procedures, and
 Articles for topic overviews. Supporting artifacts may explain, justify, or operationalize the
 policy, but they do not replace it. 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
@@ -43,10 +43,10 @@ without starting from a raw Decision Record.
 - **Articles** are synthetic views, like this one. They explain a topic across multiple Policies,
   Research documents, and Skills, helping readers understand the system without making new
   decisions. See [_core-adr-policy-004](../004-article-standards.md).
-- **Plans** describe a problem, a proposed solution, and the approach and activities needed to
-  solve it. They have a clear start and end and a well-defined scope. Plans are ephemeral: they
+- **Initiatives** describe a problem, a proposed solution, and the approach and activities needed to
+  solve it. They have a clear start and end and a well-defined scope. Initiatives are ephemeral: they
   must be deleted after full implementation, with lasting outputs captured as Policies, Skills,
-  Articles, or other artifacts. See [_core-adr-policy-007](../007-plan-standards.md).
+  Articles, or other artifacts. See [_core-adr-policy-007](../007-initiative-standards.md).
 - **Indexes and folder structure** are the discovery layer. They do not make decisions by
   themselves, but they determine how people and agents find the right artifacts, how scopes
   override one another, and how a large set of decisions remains navigable.
@@ -59,7 +59,7 @@ The easiest way to distinguish the central elements is by asking what job each o
 - **Research**: "What did we learn while evaluating options?"
 - **Skill**: "How do we carry out work under this decision?"
 - **Article**: "How do these artifacts fit together for a reader?"
-- **Plan**: "What are we going to do, why, and how?"
+- **Initiative**: "What are we going to do, why, and how?"
 - **Index/Scope structure**: "Where do I look, and which decision set takes precedence?"
 
 This separation matters because mixing these jobs into one file makes the system harder to search,
@@ -118,7 +118,7 @@ Every decision record and its supporting artifacts live at a fixed path:
             SKILL.md
         articles/
           [number]-[short-title].md
-        plans/
+        initiatives/
           [number]-[short-title].md
 ```
 
@@ -174,8 +174,8 @@ Follow [_core-adr-policy-001](../001-xdrs-standards.md) and [_core-adr-policy-00
   folder, following [_core-adr-policy-003](../003-skill-standards.md).
 - **New article** — add an `articles/[number]-[short-title].md` inside the relevant subject
   folder, following [_core-adr-policy-004](../004-article-standards.md).
-- **New plan** — add a `plans/[number]-[short-title].md` inside the relevant subject
-  folder, following [_core-adr-policy-007](../007-plan-standards.md).
+- **New initiative** — add an `initiatives/[number]-[short-title].md` inside the relevant subject
+  folder, following [_core-adr-policy-007](../007-initiative-standards.md).
 
 ### Using XDRS in your own project
 
@@ -199,7 +199,7 @@ Follow [_core-adr-policy-001](../001-xdrs-standards.md) and [_core-adr-policy-00
 - [_core-adr-policy-003](../003-skill-standards.md) - Skill standards and co-location rules
 - [_core-adr-policy-004](../004-article-standards.md) - Article standards
 - [_core-adr-policy-006](../006-research-standards.md) - Research standards
-- [_core-adr-policy-007](../007-plan-standards.md) - Plan standards
+- [_core-adr-policy-007](../007-initiative-standards.md) - Initiative standards
 - [001-review skill](../skills/001-review/SKILL.md) - Reviewing code against Policies
 - [002-write-policy skill](../skills/002-write-policy/SKILL.md) - Writing a new Policy
 - [003-write-skill skill](../skills/003-write-skill/SKILL.md) - Writing a new skill

package/.xdrs/_core/adrs/principles/skills/.assets/meta-policy-compliance.md

@@ -2,7 +2,7 @@
 
 This module is shared across XDRS writing skills. Read and execute every check during the final review of a document.
 
-Substitute `[DOCUMENT]` with the appropriate noun for the calling skill: `policy`, `skill`, `article`, `research`, or `plan`.
+Substitute `[DOCUMENT]` with the appropriate noun for the calling skill: `policy`, `skill`, `article`, `research`, or `initiative`.
 
 ---
 

package/.xdrs/_core/adrs/principles/skills/.assets/prerequisites-gate.md

@@ -2,7 +2,7 @@
 
 This module is shared across all XDRS writing skills. Read these instructions in full and execute every check before proceeding with any authoring task.
 
-Substitute `[DOCUMENT TYPE]` with the appropriate noun for the calling skill: `policy`, `skill`, `article`, `research`, `plan`, `presentation`, or `document`.
+Substitute `[DOCUMENT TYPE]` with the appropriate noun for the calling skill: `policy`, `skill`, `article`, `research`, `initiative`, `presentation`, or `document`.
 
 ---
 
@@ -16,4 +16,4 @@ Read the confirmed scope's `index.md` frontmatter and perform ALL of the followi
 
 Once all prerequisites pass, load ALL scope-type governance (see `_core-adr-policy-010` rule 22): for each declared type, resolve its full ancestor chain (primary, companions alphabetically, parent chain). Deduplicate keeping first occurrence. Then run conflict detection using the shared module at `.xdrs/_core/adrs/principles/skills/.assets/conflict-detection.md` across all loaded governance layers. Halt if undeclared structural conflicts are found (see `_core-adr-policy-010` rules 24 and 26).
 
-If the scope declares `extends:` entries (and the extends check above passed), load the inherited **policy documents** (decision records only — not skills, articles, research, or plans) from the full `extends:` chain using depth-first resolution (see `_core-adr-policy-010` rule 33): for each extends entry in declaration order, recursively resolve that scope's own `extends:` chain, then append the scope's own policies. Deduplicate keeping first occurrence. The extending scope's own policies always take precedence over all inherited ones. Apply the resolved policy set as additional context when authoring or reviewing [DOCUMENT TYPE] documents in this scope.
+If the scope declares `extends:` entries (and the extends check above passed), load the inherited **policy documents** (decision records only — not skills, articles, research, or initiatives) from the full `extends:` chain using depth-first resolution (see `_core-adr-policy-010` rule 33): for each extends entry in declaration order, recursively resolve that scope's own `extends:` chain, then append the scope's own policies. Deduplicate keeping first occurrence. The extending scope's own policies always take precedence over all inherited ones. Apply the resolved policy set as additional context when authoring or reviewing [DOCUMENT TYPE] documents in this scope.

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

@@ -42,7 +42,17 @@ Performs a structured review of code changes or files against the Policies in th
    - **Local meta-policies (policy documents only):** Apply all found local meta-policy files as mandatory conventions when reviewing policy documents in the scope. Local meta-policies take highest precedence in the chain. See `_core-adr-policy-010` rules 23, 24, and 26.
 3. Filter relevance based on file types, domains, and architectural patterns in scope.
 
-### Phase 3: Policy Review
+### Phase 3: Diagram Validation
+
+1. For every file in scope, scan for fenced ` ```mermaid ` code blocks.
+2. For each diagram found, extract the content to a temporary `.mmd` file and run:
+   ```bash
+   npx -y @mermaid-js/mermaid-cli -i <tempfile>.mmd --quiet 2>&1
+   ```
+3. For each diagram that fails validation, report as ERROR: include the file path, approximate location (heading or surrounding text), and the error message from `mmdc`.
+4. Delete all temporary files created in this step.
+
+### Phase 4: Policy Review
 
 1. Cross-reference each file in scope against active, applicable Policies.
    - **Drop any finding that cannot be traced to a specific rule in an Accepted Policy.** General good-practice observations, personal opinions, or inferred issues without an explicit Policy backing must not be reported.
@@ -60,14 +70,14 @@ Performs a structured review of code changes or files against the Policies in th
    - Consider context (existing style, legacy sections, etc.).
 3. For related Policies and files, lookup for the specific line number in both the Policy and the code that are related to the finding. This will be used in the reporting phase to provide precise references and actionable suggestions.
 
-### Phase 4: Judgment
+### Phase 5: Judgment
 1. Judgment criteria (all must be true to keep a finding):
    - Is the violation explicitly stated as a rule in an Accepted Policy using mandatory or advisory language? Templates, examples, and diagrams in Policies are illustrative only — they do not constitute rules. If the only evidence for the violation is an implicit pattern in a code sample or template, drop it.
    - Is there concrete evidence in the code or diff?
    - Is the finding actionable?
    - Would fixing it meaningfully improve compliance with the Policies?
 
-### Phase 5: Reporting
+### Phase 6: Reporting
 
 **Report template**
 ```text

package/.xdrs/_core/adrs/principles/skills/004-write-article/004-write-article.test.int.report

@@ -8,7 +8,7 @@
       ".xdrs/_core/adrs/principles/003-skill-standards.md",
       ".xdrs/_core/adrs/principles/004-article-standards.md",
       ".xdrs/_core/adrs/principles/006-research-standards.md",
-      ".xdrs/_core/adrs/principles/007-plan-standards.md",
+      ".xdrs/_core/adrs/principles/007-initiative-standards.md",
       ".xdrs/_core/adrs/principles/008-xdr-standards-structured.md",
       ".xdrs/_core/adrs/principles/articles/001-xdrs-overview.md",
       ".xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md",