xdrs-core 0.16.0 → 0.17.1

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

@@ -13,6 +13,7 @@ Foundational standards, principles, and guidelines.
 - [_core-adr-005](principles/005-semantic-versioning-for-xdr-packages.md) - **Semantic versioning for XDR packages** — How to version XDR packages to communicate upgrade impact
 - [_core-adr-006](principles/006-research-standards.md) - **Research standards** — How to structure research documents backing XDR decisions
 - [_core-adr-007](principles/007-plan-standards.md) - **Plan standards** — How to structure ephemeral execution plans that implement decisions
+- [_core-adr-008](principles/008-xdr-standards-structured.md) - **XDR standards - structured** — How to expose individually referenceable numbered rules inside an XDR when external citation by identifier is required
 
 ## Skills
 

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

@@ -25,7 +25,7 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 |---|---|---|
 | `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. |
-| `applied-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. Examples: `Only frontend code`, `JavaScript projects`. |
+| `applied-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. |
@@ -60,6 +60,7 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 - Decisions MUST be concise and reference other XDRs to avoid duplication.
 - The `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use the frontmatter fields `applied-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.
@@ -107,6 +108,14 @@ Question: In the end, state explicitly the question that needs to be answered. E
 
 [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 there was more than one option to choose from]
+
+* (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
 
@@ -144,3 +153,4 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - [_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/008-xdr-standards-structured.md

@@ -0,0 +1,81 @@
+---
+name: _core-adr-008-xdr-standards-structured
+description: Extends xdr-standards with a numbered rule format for XDR documents that define strong policies or rules, or need individually referenceable items. Use when an XDR must expose explicit rule blocks that other documents or skills may cite by identifier.
+---
+
+# _core-adr-008: XDR standards - structured
+
+## Context and Problem Statement
+
+Some XDR documents define multiple strong policies or rules that must be stated explicitly so they can be applied consistently. In other cases, documents, skills, or agents need to refer to one specific rule without copying its content. Without a standard format, prose references like "see the third bullet in Implementation Details" are fragile and ambiguous.
+
+Question: How should an XDR document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
+
+## Decision Outcome
+
+**Numbered rule blocks inside Implementation Details with a canonical citation syntax**
+
+When an XDR document defines strong rules or policies that should be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule must be placed inside `### Implementation Details` as a numbered heading block. Referencing documents and skills must cite rules using the canonical dot-notation identifier.
+
+### Implementation Details
+
+Use this format when the decision defines strong rules or policies that must be stated explicitly as stable rule blocks, or when there is a clear need for external documents, skills, or agents to reference specific items inside an XDR without duplicating the full policy text. Standard XDRs that do not define strong rule sets and do not need item-level citation should follow `_core-adr-002-xdr-standards` without adding numbered rule headings.
+
+#### Rule block format
+
+Each numbered rule must be written as:
+
+```markdown
+#### [NN]-[short-descriptive-title-in-kebab-case]
+[Body using mandatory or advisory language as defined in _core-adr-001. State the requirement and the situations in which it must or should be followed. Under 500 words.]
+```
+
+Where `NN` is a two-digit zero-padded sequence number (e.g. `01`, `02`, `12`). Numbers must be unique within the document and must never be reused after a rule is removed.
+
+Rule bodies must use the mandatory or advisory language terms defined in `_core-adr-001`:
+
+- Mandatory: "must", "always", "never", "required", "mandatory"
+- Advisory: "should", "recommended", "advised", "preferably", "possibly", "optionally"
+
+#### Citation syntax
+
+When another document or skill cites a specific rule, it must use the following dot-notation:
+
+```
+[xdr-name].[NN-short-descriptive-title-in-kebab-case]
+```
+
+Examples:
+
+- `_core-adr-008-xdr-standards-structured.[01-use-numbered-rules-for-strong-or-referenceable-policies]`
+- `_local-bdr-003-data-retention-policy.[02-purge-schedule-for-pii]`
+
+The `xdr-name` must match the `name` field in the frontmatter of the source document exactly. The rule identifier after the dot must match the heading text exactly, including the two-digit prefix and kebab-case title.
+
+#### 01-use-numbered-rules-for-strong-or-referenceable-policies
+
+Numbered rule blocks must be added to an XDR when the decision defines strong rules or policies that must be stated explicitly as stable items, or when there is a clear need for other documents, skills, or agents to cite individual rules by identifier. Adding numbered rules only for cosmetic organization is not recommended. Standard XDR documents that do not define strong rule sets and are not expected to be cited at the rule level should follow `_core-adr-002-xdr-standards` without this structured format.
+
+#### 02-rule-numbering-must-be-stable
+
+Rule numbers must never be reused within the same document. When a rule is removed, its number becomes permanently retired for that document. Gaps in the sequence are expected and must not be filled by renumbering remaining rules, as existing citations depend on number stability.
+
+#### 03-rule-body-must-use-normative-language
+
+Every rule body must contain at least one mandatory or advisory language term as defined in `_core-adr-001`. Rule bodies without normative language must not be published, as they fail to communicate whether compliance is required or recommended.
+
+#### 04-citations-must-use-exact-identifiers
+
+Documents and skills that cite a rule must use the exact dot-notation form: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`. Prose paraphrases such as "see rule 3" or "the third rule in that XDR" must not be used as citations, because they are ambiguous and break when rules are reordered or reworded.
+
+## Considered Options
+
+* (REJECTED) **Free-form prose rules with section anchors** — Use markdown heading anchors as citation targets.
+  * Reason: Anchors are fragile across editors, rendering tools, and refactors. They do not enforce a stable numbering contract and break silently when headings are reworded.
+* (CHOSEN) **Numbered rule blocks inside Implementation Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
+  * Reason: Minimal addition to the existing XDR template, stable identifiers independent of heading text, and fully compatible with `_core-adr-002-xdr-standards`.
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md)
+- [_core-adr-002 - XDR standards](002-xdr-standards.md)

package/.xdrs/_core/adrs/principles/skills/001-lint/001-lint.test.int.report

@@ -18,6 +18,6 @@
       ".xdrs/_core/adrs/principles/skills/001-lint/SKILL.md",
       "AGENTS.md"
     ],
-    "contextHash": "dc167dc47aab0f4de26ddbcd4fa979b4"
+    "contextHash": "b64868b8dba3664c0a1b641f06ef718b"
   }
 }

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

@@ -3,12 +3,11 @@
     "result": "success",
     "contextFiles": [
       ".xdrs/_core/adrs/index.md",
-      ".xdrs/_core/adrs/principles/001-xdrs-core.md",
       ".xdrs/_core/adrs/principles/002-xdr-standards.md",
       ".xdrs/_core/adrs/principles/skills/002-write-xdr/SKILL.md",
       ".xdrs/index.md",
       "AGENTS.md"
     ],
-    "contextHash": "8d030307248237f1775ab38126d354db"
+    "contextHash": "808c78ca2f4aeb670c7503766a37dc1a"
   }
 }

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

@@ -76,6 +76,32 @@ Choose a title that clearly states the question this XDR answers, not the answer
 
 Use the mandatory template from `002-xdr-standards`:
 
+**Check if the decision requires a structured set of rules:**
+If the decision defines strong rules or policies that must be stated explicitly, or if other documents, skills, or agents have a clear need to reference individual rules, you MUST apply the structured rule format from `_core-adr-008-xdr-standards-structured`. This means:
+  - Place each rule as a numbered heading block inside `### Implementation Details`.
+  - Use the format:
+    #### [NN]-[short-descriptive-title-in-kebab-case]
+    [Rule body with mandatory/advisory language.]
+  - Ensure each rule is uniquely numbered (two digits, zero-padded) and never reuse numbers if a rule is removed.
+  - Other documents must cite rules using the canonical dot-notation: `[xdr-name].[NN-short-descriptive-title-in-kebab-case]`.
+
+**Example of a structured set of rules:**
+
+```markdown
+### Implementation Details
+
+#### 01-data-must-be-encrypted-at-rest
+All user data must be encrypted at rest using AES-256 or stronger algorithms.
+
+#### 02-access-logs-must-be-retained
+Access logs must be retained for at least 90 days and reviewed monthly for suspicious activity.
+
+#### 03-external-integrations-should-be-reviewed
+All external integrations should be reviewed annually for compliance with current security standards.
+```
+
+Refer to `_core-adr-008-xdr-standards-structured` for full requirements and citation syntax.
+
 ```
 ---
 name: [scope]-[type]-[number]-[short-title]

package/.xdrs/_core/adrs/principles/skills/003-write-skill/003-write-skill.test.int.report

@@ -2,12 +2,13 @@
   "Create a skill with instructions on how -a7079882": {
     "result": "success",
     "contextFiles": [
-      ".xdrs/_core/adrs/principles/001-xdrs-core.md",
+      ".xdrs/_core/adrs/index.md",
       ".xdrs/_core/adrs/principles/003-skill-standards.md",
       ".xdrs/_core/adrs/principles/skills/003-write-skill/SKILL.md",
+      ".xdrs/_core/bdrs/index.md",
       ".xdrs/index.md",
       "AGENTS.md"
     ],
-    "contextHash": "30c68e62fee8f74be079e7df7f6c10d1"
+    "contextHash": "a9dd40b6bf1d4913cca7638a5b34820c"
   }
 }

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

@@ -116,10 +116,10 @@ If any check fails, revise before continuing.
 ### Phase 6: Write Files
 
 1. Create the skill file at `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`.
-2. Create a hardlink at `.github/skills/[number]-[skill-name]/SKILL.md` so VS Code picks it up immediately:
+2. Create a symlink at `.github/skills/[number]-[skill-name]` so VS Code picks it up immediately:
    ```
    mkdir -p .github/skills/[number]-[skill-name]
-   ln .xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md .github/skills/[number]-[skill-name]/SKILL.md
+   ln -s ../../.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name] .github/skills/[number]-[skill-name]
    ```
 
 ### Constraints

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

@@ -5,12 +5,16 @@
       ".xdrs/_core/adrs/index.md",
       ".xdrs/_core/adrs/principles/001-xdrs-core.md",
       ".xdrs/_core/adrs/principles/002-xdr-standards.md",
+      ".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/008-xdr-standards-structured.md",
       ".xdrs/_core/adrs/principles/articles/001-xdrs-overview.md",
       ".xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md",
       ".xdrs/index.md",
       "AGENTS.md"
     ],
-    "contextHash": "21d52973f1313bfbbf238f69e080de81"
+    "contextHash": "3be2670eaae626887f9cd7ee8a8e5f6d"
   }
 }

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

@@ -0,0 +1,9 @@
+# _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

@@ -0,0 +1,52 @@
+---
+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.
+
+### Implementation Details
+
+- Before treating any XDR as a current requirement, evaluate applicability in order: `valid-from`, `applied-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)

package/.xdrs/index.md

@@ -10,6 +10,7 @@ XDRs in scopes listed last override the ones listed first
 
 Decisions about how XDRs work
 [View _core ADRs Index](_core/adrs/index.md)
+[View _core BDRs Index](_core/bdrs/index.md)
 
 ---
 

package/README.md

@@ -1,6 +1,6 @@
 # xdr-standards
 
-XDRs (eXtended Decision Records) is a standard for organizing Architectural (ADR), Business (BDR), and Engineering (EDR) decision records so that AI agents and humans can reliably find and follow them. Each XDR package bundles four document types: Decision Records (the source of truth), Research (exploratory backing), Skills (step-by-step procedural guides), and Articles (synthetic overviews).
+XDRs (eXtended Decision Records) is a standard for organizing Architectural (ADR), Business (BDR), and Engineering (EDR) decision records so that AI agents and humans can reliably find and follow them. Each XDR package bundles five document types: Decision Records (the source of truth), Research (exploratory backing), Skills (step-by-step procedural guides), Articles (synthetic overviews), and Plans (ephemeral execution guidance).
 
 > **Note:** This repository contains a minimum set of standards and very basic set of ADRs that describe the proposed decisions structure. It is intended to be used as a foundation that other projects can reference, extend, or install as a dependency in order to bootstrap and create their own XDRs.
 
@@ -66,7 +66,7 @@ The folder layout, file naming, and document format are designed so that AI agen
 - Each XDR is a small, focused Markdown file (target under 1300 words), covering one decision.
 - The canonical index per scope and type lists all XDRs 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.
-- XDR metadata gives agents a first-pass filter: check `Valid` for the convergence date, then check `Applied 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.
+- XDR metadata gives agents a first-pass filter: check `valid-from` for the convergence date, then check `applied-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 XDR ID rather than duplicating content, keeping individual files concise.
 - Subject folders reduce the search space when a query maps to a known domain.
 
@@ -166,7 +166,7 @@ The `lint` command reads `./.xdrs/**` from the given workspace path and checks c
 - plan `Expected end date:` field presence and ISO date format
 - canonical index presence and link consistency
 - root index coverage for all discovered canonical indexes
-- XDR metadata section placement and `Valid` / `Applied to` field format
+- XDR metadata section placement and `valid-from` / `applied-to` field format
 - local markdown links between XDR documents, skills, articles, researches, and plans (excluding fenced code blocks)
 - local image and `assets/` links resolving inside the sibling `assets/` folder for each document
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "A standard way to organize Decision Records (XDRs) across scopes, subjects, and teams so that AI agents can reliably query and follow them.",
   "repository": {
     "type": "git",
@@ -14,7 +14,6 @@
   ],
   "license": "MIT",
   "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },