xdrs-core 0.24.1 → 0.26.0

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

@@ -1,158 +0,0 @@
----
-name: _core-adr-002-xdr-standards
-description: Defines how XDR decision documents should be written, including template, frontmatter, applicability fields, and conflict handling. Use when writing or reviewing any XDR document.
----
-
-# _core-adr-002: XDR standards
-
-## Context and Problem Statement
-
-XDR framework elements (types, scopes, subjects, folder structure) are defined in `_core-adr-001`. Once a decision record's structural placement is clear, how should the document itself be written to remain authoritative, concise, and consistently structured?
-
-## Decision Outcome
-
-**Structured decision records with a mandatory template, applicability metadata, and clear conflict rules**
-
-XDR documents are the authoritative policy for their scope, type, and subject. They must be concise, template-compliant, and clear about applicability so that humans and AI agents can reliably determine whether and how to apply any decision.
-
-### Details
-
-- XDRs MUST contain a clear decision about a certain problem or situation. Avoid being too verbose and focus on explaining clearly the context and the decision. Avoid adding contents that are not original. If you have other references that are important to understand the document, add links and references. Always cite sources.
-- XDRs are the central artifact of the framework and the authoritative policy for their scope, type, and subject. Supporting artifacts may explain, justify, or operationalize the decision (like articles, researches and skills), but they do not replace it.
-- XDR documents MUST include a YAML frontmatter block at the very beginning of the file. The supported fields are:
-
-| Field | Required | Constraints |
-|---|---|---|
-| `name` | Yes | 1-64 characters. Lowercase letters, numbers, hyphens, and leading underscores only. Must not end with a hyphen. Must not contain consecutive hyphens. Must match the document identifier from the heading: `[scope]-[type]-[number]-[short-title]`. |
-| `description` | Yes | 1-1024 characters. Describes what this decision is about and when to use it. Should include keywords that help agents identify when to apply it. |
-| `apply-to` | No | Short description of contexts this decision is applicable to. Keep it under 40 words. If omitted, the decision applies to all logically applicable elements. ONLY use this section if the usage is very specific to a specific case. Examples: `Only frontend code`, `JavaScript projects`. |
-| `valid-from` | No | ISO date (`YYYY-MM-DD`) indicating from when this decision must be enforced. Before this date it should be used everywhere possible, but compliance is not enforced during reviews until after this date. |
-| `license` | No | SPDX license expression (e.g. `MIT`, `Apache-2.0`, `CC-BY-4.0`). Indicates the license under which the document content is shared. If omitted, the license is governed by the repository or package defaults. |
-| `metadata` | No | Arbitrary key-value map for additional properties not defined by this spec. |
-
-  - Minimal example:
-    ```yaml
-    ---
-    name: _core-adr-002-xdr-standards
-    description: Defines how XDR documents should be written. Use when writing or reviewing any XDR.
-    ---
-    ```
-  - Example with optional fields:
-    ```yaml
-    ---
-    name: _core-adr-002-xdr-standards
-    description: Defines how XDR documents should be written. Use when writing or reviewing any XDR.
-    apply-to: All XDR scopes
-    valid-from: 2026-06-01
-    metadata:
-      author: example-org
-    ---
-    ```
-- All documents present in the collection are considered active. There is no status field. When a decision is no longer relevant, valid or active, it must be removed from the collection. Historical versions are available via versioned packages or git history.
-- Before using, enforcing, or citing an XDR as a current rule, humans and AI agents MUST decide whether the decision is applicable for the current case.
-  - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-  - Check `apply-to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
-  - Check the decision context and implementation details last to determine any additional boundaries, exceptions, or qualifiers that metadata alone cannot express.
-- Research documents MAY be added under the same subject to capture the exploration, findings, and proposals that backed a decision. Research is useful during elaboration, discussion, and updates of XDRs, but the XDR document remains the source of truth.
-- **XDR Id:** [scope]-[type]-[xdr number] (numbers are scoped per type+scope combination and must not be reused within that combination; always use lowercase)
-  - Types in IDs: `adr`, `bdr`, `edr`
-  - Define the next number of an XDR by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted XDRs and we should never reuse numbers of different documents/decisions. Numbering gaps are expected.
-- Decisions MUST be concise and reference other XDRs to avoid duplication.
-- The `### Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `apply-to` and `valid-from` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
-- Use concise rules, examples, `Allowed` / `Disallowed` lists or checklists with required items to help the reader apply the decision correctly. Keep them short and decision-specific.
-- When the decision defines strong policies or rules that should be stated explicitly as stable rule blocks, or when other documents, skills, or agents need to cite those rules individually by identifier, the XDR MUST follow the extension [_core-adr-008 - XDR standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
-- Conflict handling applies to XDR documents:
-  - For cross-scope overrides, document the decision conflict in the XDR `## Conflicts` section of the XDR that overrides another scope.
-  - **Within-scope conflicts:** XDRs within the same type+scope must not conflict. If two XDRs appear to conflict, one should be updated, removed, or the conflict resolved through a new XDR.
-- When research exists for a decision, the XDR SHOULD mention the related research documents after the `## Considered Options` list.
-- Never use emojis in contents.
-- Always use file names with lowercase.
-- Any non-Markdown files referenced by an XDR (schemas, JSON examples, images, diagrams, binaries, or any other data files) SHOULD be used only when they are materially necessary and MUST live in `[xdrs-root]/[scope]/[type]/[subject]/.assets/`.
-- Sub-directories inside this `.assets/` folder are allowed only when it already has more than 10 files. Otherwise, keep files flat.
-- Avoid using lengthy instructions on the XDR. If there are long and detailed instructions related to the XDR, or instructions that are outside the decision, create another file with a guide. If the guide is small, keep it in the XDR itself.
-- XDRs should be under 1300 words long as a rule of thumb.
-  - This is important to make them focused on a clear decision
-  - Exceptions can reach under 2600 words (templates, more elaborate decision implementations etc)
-- ALWAYS use `_local` scope if the user doesn't explicitly indicate a specific scope while creating an xdr or skill.
-
-**XDR template**
-
-All XDRs MUST follow this template
-
-```markdown
----
-name: [scope]-[type]-[number]-[short-title]
-description: [What this decision is about and when to use it]
-apply-to: [Optional. Contexts this decision applies to, under 40 words]
-valid-from: [Optional. ISO date YYYY-MM-DD from when enforcement begins]
-license: [Optional. SPDX license expression]
-metadata:
-  [optional-key]: [optional-value]
----
-
-# [scope]-[type]-[number]: [Short Title]
-
-## Context and Problem Statement
-
-[Describe the context, background, or need that led to this decision.
-What is the problem we are trying to solve? Who is being impacted? (<40 words)
-
-Question: In the end, state explicitly the question that needs to be answered. E.g: "Which platform should I use when implementing an AI agent?"]
-
-## Decision Outcome
-
-**[Chosen Option Title]**
-[Very short description of what is the decision, aligned with the titles on the Considered Options section]
-
-[Short description of implementation details for the chosen path]
-
-### Details
-
-[Optional section with implementation specifics, applicability boundaries, rules, concise examples, or do/don't guidance. This is the answer to the question in the "Context and Problem Statement". (<1300 words)]
-
-## Considered Options 
-[this section is present ONLY if the user explicitely indicated that there were multiple options to choose from while making this decision.]
-
-* (CHOSEN) **Option 2** - Brief description of option 2
-  * Reason: Brief description of why this option was accepted, containing the strengths, strategical motivations and it's differential over the other options.
-* (REJECTED) **Option 1** - Brief description of option 1
-  * Reason: Brief description why this was rejected with important aspects to be re-checked in the case we want to change this decision
-
-[Related research, if any]
-- [Research document title](researches/001-example.md) - Brief description of what it informed
-
-## Conflicts
-
-[If this XDR has conflicts with other scopes, this section is MANDATORY and needs to have an explanation why the conflict is accepted]
-
-* Conflict with [XDR id] (e.g.: adr-business-x-001)
-  * Summary: Brief description of the conflict
-  * Reason to accept: Brief description of why it was decided to accept this conflict, possibly overriding or diverging from the other decision/scopes
-
-## References
-
-[optional section]
-[useful links related to this implementation]
-[links to the discussion (PRs, meetings etc)]
-[links to related skills]
-```
-
-**Examples:**
-- Frontmatter examples:
-  - `valid-from: 2026-03-01`
-  - `apply-to: JavaScript projects`
-
-**XDR ID Examples:**
-- `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)
-- `business-x-edr-042` (not `EDR-BUSINESS-X-042`)
-- `business-x-bdr-007`
-
-## References
-
-- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework elements: types, scopes, subjects, folder structure
-- [001-lint skill](skills/001-lint/SKILL.md) - Skill for reviewing code changes against XDRs
-- [002-write-xdr skill](skills/002-write-xdr/SKILL.md) - Skill for creating a new XDR following this standard
-- [_core-adr-003 - Skill standards](003-skill-standards.md)
-- [_core-adr-004 - Article standards](004-article-standards.md)
-- [_core-adr-006 - Research standards](006-research-standards.md)
-- [_core-adr-008 - XDR standards - structured](008-xdr-standards-structured.md) - Extension for XDRs that expose individually referenceable rules

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

@@ -1,94 +0,0 @@
----
-name: 001-lint
-description: >
-  Reviews code changes or files against applicable XDRs (Decision Records) and reports violations as structured findings. 
-  Activate this skill when the user asks to review, lint, or audit code, or when you identify a need to check compliance with XDRs during implementation.
-metadata:
-  author: flaviostutz
-  version: "1.0"
----
-
-## Overview
-
-Performs a structured review of code changes or files against the XDRs in the repository, categorizing findings by severity and type, and reporting them without modifying any code.
-
-## Instructions
-
-### Phase 1: Code Gathering
-
-1. Identify changes based on requested scope:
-   - For diffs: run and parse `git diff refs/remotes/origin/HEAD`
-   - For files: analyze file contents directly
-
-### Phase 2: XDR Compilation
-
-1. Gather all Decision Records from the XDR root `index.md` (default: `.xdrs/index.md`) starting from the working directory.
-   - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
-   - Extract frontmatter first to decide whether each XDR should be used for the current review context.
-   - All documents present in the collection are considered active.
-   - Check `valid-from:` first. If a date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-   - Check `apply-to:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
-   - Check the decision text itself last for additional boundaries or exceptions that metadata does not encode.
-2. Filter relevance based on file types, domains, and architectural patterns in scope.
-
-### Phase 3: XDR Review
-
-1. Cross-reference each file in scope against active, applicable XDRs.
-   - **Drop any finding that cannot be traced to a specific rule in an Accepted XDR.** General good-practice observations, personal opinions, or inferred issues without an explicit XDR backing must not be reported.
-   - Classify as ERROR (mandatory) or WARNING (advisory).
-   - Include: location, description, XDR reference (file + line), suggestion.
-2. Reduce false positives:
-   - Evaluate ERROR findings for mandatory language in the XDR ("must", "always", "never", "required", "mandatory"). Drop or downgrade to WARNING if the language is advisory ("should", "recommended", "advised").
-   - Remove findings unrelated to actual changes.
-   - Consolidate duplicates.
-   - Consider context (existing style, legacy sections, etc.).
-3. For related XDRs and files, lookup for the specific line number in both the XDR 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
-1. Judgment criteria (all must be true to keep a finding):
-   - Is the violation explicitly stated as a rule in an Accepted XDR using mandatory or advisory language? Templates, examples, and diagrams in XDRs 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 XDR?
-
-### Phase 5: Reporting
-
-**Report template**
-```text
-### Code Review Against XDRs
-Scope: [scope identifier]
-
-## Findings
-### 1. [ERROR|WARNING] - [filename:line_number](filename:line_number)
-- Title of the finding (<=15 words)
-- XDR reference: [xdr-file:line_number](xdr-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
-
-### 2. [second finding etc]
-
-## Summary
-- Errors: [count]
-- Warnings: [count]
-- Outcome: [PASS|FAIL]
-```
-
-### Constraints
-- MUST NOT include any text or explanations outside the required output format.
-- MUST NOT edit code. Instruct the user on how to request code changes in suggestions.
-
-## Examples
-- An XDR mentions that "Every code MUST have a header comment with author name", if you find a codebase without the author name, report as ERROR.
-- An XDR mentions that "Functions SHOULD be no longer than 50 lines", if you find a function with 80 lines, report as WARNING.
-
-## Edge Cases
-- If no XDRs apply to the scope, output "No applicable XDRs found" and skip reporting.
-- If a potential violation is in pre-existing code outside the diff, report it as WARNING only.
-
-## References
-
-- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
-- [_core-adr-002 - XDR standards](../../002-xdr-standards.md)
-- [_core-adr-003 - Skill standards](../../003-skill-standards.md)
-

package/.xdrs/_core/adrs/principles/skills/002-write-xdr/002-write-xdr.test.int.js

@@ -1,24 +0,0 @@
-'use strict';
-
-const path = require('path');
-const { copilotCmd, testPrompt } = require('xdrs-core');
-
-const REPO_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..', '..');
-
-jest.setTimeout(300000);
-
-test('002-write-xdr creates a local EDR decision record', async () => {
-	const err = await testPrompt(
-		{
-			workspaceRoot: REPO_ROOT,
-			workspaceMode: 'copy',
-			...copilotCmd(REPO_ROOT),
-		},
-		'Create a very small XDR deciding to use pnpm for Node.js monorepos',
-		'Verify that an XDR markdown file was created under .xdrs/_local/edrs/devops/, that it contains "## Context and Problem Statement" and "## Decision Outcome", that it read file 002-write-xdr/SKILL.md and has the decision of using pnpm for Node.js monorepos.',
-		null,
-		true
-	);
-
-	expect(err).toBe('');
-});

package/.xdrs/_core/bdrs/index.md

@@ -1,9 +0,0 @@
-# _core BDRs Index
-
-Business and operational decisions about how the XDR framework operates, including policy and process rules for framework users. Owned by the platform team. Propose changes via pull request.
-
-## Principles
-
-Foundational business principles and policy decisions that guide all framework users.
-
-- [_core-bdr-001](principles/001-xdr-decisions-and-skills-usage.md) - **XDR decisions and skills usage** — How agents and humans must use XDR decisions and skills, separating policy authority from execution guidance

package/.xdrs/_core/bdrs/principles/001-xdr-decisions-and-skills-usage.md

@@ -1,52 +0,0 @@
----
-name: _core-bdr-001-xdr-decisions-and-skills-usage
-description: Defines how agents and humans must use XDR decisions and skills, separating policy authority from execution guidance across single-agent and multi-agent workflows.
----
-
-# _core-bdr-001: XDR decisions and skills usage
-
-## Context and Problem Statement
-
-Repositories using the XDR framework contain both decision records (BDRs, ADRs, EDRs) and skills. In multi-agent or multi-role workflows, each actor needs to know which artifact carries policy authority and which carries execution guidance.
-
-Question: How must agents and humans use XDR decisions and skills so policy, execution guidance, and role boundaries stay clear?
-
-## Decision Outcome
-
-**BDRs define compliance policy; skills operationalize it**
-
-XDR decisions are the authoritative source of mandatory policy. Skills are execution artifacts that operationalize those decisions and must never substitute them as policy authority.
-
-### Details
-
-- Before treating any XDR as a current requirement, evaluate applicability in order: `valid-from`, `apply-to`, then the decision text.
-- The set of policies that an agent or human must comply with for a given operational context must be declared in BDRs.
-- If a policy set becomes too large or too mixed in purpose to review clearly in one record, it must be split into multiple focused BDRs.
-- Specific work instructions that operationalize BDR policies must be structured as skills when the procedure is detailed enough to benefit from a dedicated operational document.
-- Every skill that operationalizes or verifies BDR policies must link to the BDRs it implements or checks.
-- If a skill conflicts with an applicable XDR, the XDR prevails. The human or agent must stop relying on the conflicting skill behavior and report the inconsistency.
-- If an applicable BDR exists but no supporting skill exists yet, the human or agent may proceed by following the BDR directly when the decision is actionable, and must report the missing skill as an operational gap.
-- In multi-agent graphs or staged workflows, every participating agent must remain bounded by the same applicable BDR policies even when agents have different local objectives, prompts, or skills.
-- Each agent or human role involved in a workflow must make explicit which applicable BDRs govern its work and which skills it is following.
-- Different documents may be consumed by different actors. For example: one agent uses skills for data acquisition, another for plan execution, and a reviewer reads BDRs directly to validate outcomes.
-
-Allowed:
-- using multiple skills to operationalize one BDR in different phases of a workflow;
-- using one skill to operationalize multiple related BDRs when the skill links them clearly;
-- having human-only, agent-only, or mixed human-agent execution for the same skill.
-
-Disallowed:
-- treating a skill as policy authority by itself;
-- inventing mandatory policy rules only inside prompts, plans, or skills;
-- allowing one agent in a workflow to bypass an applicable BDR because another agent checked a different subset of rules.
-
-## Considered Options
-
-- (REJECTED) **Keep policy and execution guidance mixed inside operational BDRs** — Makes decisions harder to reuse, review, and assign across humans and multiple agent roles.
-- (CHOSEN) **Separate mandatory policy in BDRs from executable guidance in skills** — Preserves a clear source of truth while allowing different humans and agents to execute specialized procedures.
-
-## References
-
-- [_core-adr-001](../../adrs/principles/001-xdrs-core.md)
-- [_core-adr-002](../../adrs/principles/002-xdr-standards.md)
-- [_core-adr-003](../../adrs/principles/003-skill-standards.md)