xdrs-core 0.38.1 → 0.38.3

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

@@ -13,7 +13,7 @@ Foundational standards, principles, and guidelines.
 - [_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-008](principles/008-xdr-standards-structured.md) - **Policy standards - structured** — How to expose individually referenceable numbered rules inside a Policy when external citation by identifier is required
+- [_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
 - [_core-adr-policy-011](principles/011-core-scope-type.md) - **core scope type** — Defines the `core` scope type: meta-governance scopes that hold writing standards, templates, and process guidance for a domain

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

@@ -69,7 +69,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 - When a policy covers elements that could be confused with each other, include explicit disambiguation statements clarifying the distinction before stating the rules for each.
 - A "why" explanation for a policy rule MAY only be included if it is brief, non-obvious, relevant to the reader, and not longer than the rule itself.
 - Rules MUST focus on what is required or forbidden. Explanations of why a rule exists belong in a Research document, not in the Policy itself. Link to the relevant research when the rationale is important for adoption.
-- 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 Policy MUST follow the extension [_core-adr-policy-008 - Policy standards - structured](008-xdr-standards-structured.md) instead of using plain bullet lists for those rules.
+- 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 Policy MUST follow the extension [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) instead of using plain bullet lists for those rules.
 - Conflict handling applies to Policy documents:
   - For cross-scope overrides, document the decision conflict in the Policy `## Conflicts` section of the Policy that overrides another scope.
   - **Within-scope conflicts:** Policies within the same type+scope MUST NOT conflict. If two Policies appear to conflict, one SHOULD be updated, removed, or the conflict resolved through a new Policy.
@@ -158,4 +158,4 @@ Question: In the end, state explicitly the question that needs to be answered. E
 - [_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-008 - Policy standards - structured](008-xdr-standards-structured.md) - Extension for Policies that expose individually referenceable rules
+- [_core-adr-policy-008 - Policy structured standards](008-policy-structured-standards.md) - Extension for Policies that expose individually referenceable rules

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

@@ -0,0 +1,74 @@
+---
+name: _core-adr-policy-008-policy-structured-standards
+description: Extends policy-standards with a numbered rule format for Policy documents that define strong policies or rules, or need individually referenceable items. Use when a Policy must expose explicit rule blocks that other documents or skills may cite by identifier.
+apply-to: Policy documents requiring structured rule blocks
+valid-from: 2025-01-01
+---
+
+# _core-adr-policy-008: Policy structured standards
+
+## Context and Problem Statement
+
+Some Policy documents define strong rules or constraints that must be individually referenceable by other documents, skills, or automated agents. The standard policy format from `_core-adr-policy-002` does not specify how such numbered rule blocks should be structured, titled, or cited. Without a consistent format, citations become ambiguous and tools cannot reliably locate referenced rules.
+
+## Decision Outcome
+
+**Numbered rule blocks with stable identifiers, normative language, and dot-notation citations**
+
+Policies that define strong or frequently-cited rules MUST use a numbered rule block format. Each rule receives a stable two-digit identifier, a lowercase kebab-case title, and a body with at least one normative keyword. Citations MUST use dot-notation referencing the exact rule identifier.
+
+### Details
+
+#### 01-always-use-numbered-rules-for-strong-or-referenceable-policies
+
+A Policy MUST use numbered rule blocks when it defines strong rules that must be stable and referenceable. Rules MUST NOT be added for cosmetic organization only. Policies without strong rule sets SHOULD follow `_core-adr-policy-002-policy-standards` instead.
+
+#### 02-rule-numbering-must-be-stable
+
+Rule numbers MUST NOT be reused within the same document. When a rule is removed, its number is permanently retired. Gaps MUST NOT be filled by renumbering remaining rules.
+
+#### 03-rule-body-must-use-normative-language
+
+Every rule body MUST contain at least one normative term (MUST, SHOULD, MAY, etc.) as defined in `_core-adr-policy-001`. Rule bodies without normative language MUST NOT be published.
+
+#### 04-citations-must-use-exact-identifiers
+
+Citations MUST use the exact dot-notation form: `policy-name.NN-short-rule-title-in-kebab-case`. Prose references such as "see rule 3" or "the third rule" MUST NOT be used.
+
+#### 05-rule-title-must-be-all-lowercase
+
+Rule titles MUST be all lowercase. Uppercase letters MUST NOT appear in rule titles, including normative keywords (e.g. `01-code-must-be-linted`, not `01-code-MUST-be-linted`).
+
+#### 06-normative-keywords-must-not-use-emphasis-marks
+
+Normative keywords in rule bodies MUST be written as plain text. Bold or italic markers around normative keywords MUST NOT be used.
+
+#### 07-rule-title-should-include-normative-keyword-in-simple-cases
+
+A rule title SHOULD include a normative keyword when the rule can be stated clearly in a short phrase. For complex rules, the title MAY omit normative language, provided the rule body contains it.
+
+#### 08-rule-block-must-use-standard-syntax
+
+Each rule MUST be written as a level-4 heading with a two-digit zero-padded sequence number followed by a kebab-case title, and a body paragraph:
+
+```markdown
+#### [NN]-[short-rule-title-in-kebab-case]
+[Rule body using normative language per _core-adr-policy-001. Under 500 words.]
+```
+
+#### 09-citations-must-use-dot-notation
+
+Citations MUST use dot-notation where `policy-name` matches the `name` frontmatter field and the rule identifier after the dot matches the heading text exactly:
+
+```
+policy-name.NN-short-rule-title-in-kebab-case
+```
+
+Examples:
+- `_core-adr-policy-008-policy-structured-standards.01-always-use-numbered-rules-for-strong-or-referenceable-policies`
+- `_local-bdr-policy-003-data-retention-policy.02-purge-schedule-for-pii`
+
+## References
+
+- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md)
+- [_core-adr-policy-002 - Policy standards](002-policy-standards.md)

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

@@ -78,7 +78,7 @@ Choose a title that clearly states the question this Policy answers, not the ans
 Use the mandatory template from `002-policy-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-policy-008-policy-standards-structured`. This means:
+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-policy-008-policy-structured-standards`. This means:
   - Place each rule as a numbered heading block inside `### Details`.
   - Use the format:
     #### [NN]-[short-descriptive-title-in-kebab-case]
@@ -101,7 +101,7 @@ Access logs must be retained for at least 90 days and reviewed monthly for suspi
 All external integrations should be reviewed annually for compliance with current security standards.
 ```
 
-Refer to `_core-adr-policy-008-policy-standards-structured` for full requirements and citation syntax.
+Refer to `_core-adr-policy-008-policy-structured-standards` for full requirements and citation syntax.
 
 ```
 ---

package/.xdrs/_core/index.md

@@ -29,7 +29,7 @@ The core architectural decision [_core-adr-policy-001](adrs/principles/001-xdrs-
 Each artifact type has its own writing standard:
 
 - **Policy documents** follow [_core-adr-policy-002](adrs/principles/002-policy-standards.md), which defines the mandatory template, frontmatter metadata, applicability rules, conflict handling, and word limits that keep decisions concise and authoritative.
-- **Structured Policies** with individually referenceable rules follow the extension [_core-adr-policy-008](adrs/principles/008-xdr-standards-structured.md), adding numbered rule blocks and a dot-notation citation syntax.
+- **Structured Policies** with individually referenceable rules follow the extension [_core-adr-policy-008](adrs/principles/008-policy-structured-standards.md), adding numbered rule blocks and a dot-notation citation syntax.
 - **Skills** follow [_core-adr-policy-003](adrs/principles/003-skill-standards.md), using the agentskills format so they work for both humans and AI agents on an automation gradient from fully manual to fully automated.
 - **Articles** follow [_core-adr-policy-004](adrs/principles/004-article-standards.md), providing synthetic views that combine and link multiple Policies, research, and skills without replacing them as the source of truth.
 - **Research** follows [_core-adr-policy-006](adrs/principles/006-research-standards.md), using an IMRAD-based structure for studies that back decisions with reproducible evidence.

package/lib/lint.js

@@ -38,6 +38,7 @@ const RESEARCH_MAX_WORDS = 5000;
 const SKILL_MAX_WORDS = 6500;
 
 const NORMATIVE_KEYWORDS_RE = /\bMUST NOT\b|\bMUST\b|\bSHOULD NOT\b|\bSHOULD\b|\bMAY\b|\bREQUIRED\b|\bOPTIONAL\b/;
+const NORMATIVE_EMPHASIS_RE = /(\*{1,2}|_{1,2})(MUST NOT|SHOULD NOT|MUST|SHOULD|MAY|REQUIRED|OPTIONAL|always|never|mandatory|recommended|advised|preferably|possibly|optionally)(\*{1,2}|_{1,2})/i;
 
 const RESEARCH_SECTION_LIMITS = {
   '## Abstract': 200,
@@ -1623,7 +1624,11 @@ function lintStructuredRuleBlocks(content, filePath, errors) {
     }
 
     if (title.length === 0 || !/^[a-z][a-z0-9-]*$/.test(title)) {
-      errors.push(`Policy structured rule title must be in kebab-case ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]`);
+      if (/[A-Z]/.test(title)) {
+        errors.push(`Policy structured rule title must be all lowercase ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.05-rule-title-must-be-all-lowercase]`);
+      } else {
+        errors.push(`Policy structured rule title must be in kebab-case ("${title}"): ${toDisplayPath(filePath)} [_core-adr-policy-008.01-always-use-numbered-rules-for-strong-or-referenceable-policies]`);
+      }
     }
 
     const wordCount = title.split('-').filter(Boolean).length;
@@ -1646,10 +1651,16 @@ function lintStructuredRuleBlocks(content, filePath, errors) {
       }
     }
     const ruleBodyText = lines.slice(bodyStart, bodyEnd).join('\n');
+    const ruleBodyNonCodeLines = lines.slice(bodyStart, bodyEnd).filter((_, idx) => !ignoredLines[bodyStart + idx]);
+    const ruleBodyTextForEmphasis = ruleBodyNonCodeLines.join('\n');
 
     if (!NORMATIVE_KEYWORDS_RE.test(ruleBodyText)) {
       errors.push(`Policy structured rule body must contain normative language (MUST/SHOULD/MAY) in "${number}-${title}": ${toDisplayPath(filePath)} [_core-adr-policy-008.03-rule-body-must-use-normative-language]`);
     }
+
+    if (NORMATIVE_EMPHASIS_RE.test(ruleBodyTextForEmphasis)) {
+      errors.push(`Policy structured rule body must not use bold or italic marks around normative keywords in "${number}-${title}": ${toDisplayPath(filePath)} [_core-adr-policy-008.06-normative-keywords-must-not-use-emphasis-marks]`);
+    }
   }
 }
 

package/lib/lint.test.js

@@ -2651,7 +2651,7 @@ test('reports structured rule block with non-kebab-case title', () => {
     '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
       '### Details',
       '',
-      '#### 01-My Rule Title',
+      '#### 01-my rule title',
       '',
       'This rule MUST be followed.',
     ].join('\n')),
@@ -2733,6 +2733,89 @@ test('accepts valid structured rule blocks', () => {
   expect(result.errors.join('\n')).not.toContain('structured rule');
 });
 
+test('reports structured rule block title with uppercase letters', () => {
+  const workspaceRoot = createWorkspace('structured-rule-uppercase-title', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '### Details',
+      '',
+      '#### 01-code-MUST-be-linted',
+      '',
+      'This rule MUST be followed.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule title must be all lowercase');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.05-rule-title-must-be-all-lowercase]');
+});
+
+test('reports structured rule body with bold marks around normative keyword', () => {
+  const workspaceRoot = createWorkspace('structured-rule-bold-normative', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '### Details',
+      '',
+      '#### 01-my-rule',
+      '',
+      'This rule **MUST** be followed.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must not use bold or italic marks around normative keywords');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.06-normative-keywords-must-not-use-emphasis-marks]');
+});
+
+test('reports structured rule body with italic marks around normative keyword', () => {
+  const workspaceRoot = createWorkspace('structured-rule-italic-normative', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '### Details',
+      '',
+      '#### 01-my-rule',
+      '',
+      'This rule _SHOULD_ be considered.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('must not use bold or italic marks around normative keywords');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.06-normative-keywords-must-not-use-emphasis-marks]');
+});
+
+test('accepts normative keywords in plain text in structured rule body', () => {
+  const workspaceRoot = createWorkspace('structured-rule-plain-normative', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-main](principles/001-main.md) - Main decision'
+    ]),
+    '.xdrs/_local/adrs/principles/001-main.md': xdrDocument([
+      '### Details',
+      '',
+      '#### 01-my-rule',
+      '',
+      'This rule MUST be followed and implementors SHOULD consider it carefully.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('bold or italic marks');
+});
+
 test('reports research section exceeding word limit', () => {
   const body500words = Array(500).fill('word').join(' ');
   const workspaceRoot = createWorkspace('research-section-over-limit', {

package/package.json

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

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

@@ -1,83 +0,0 @@
----
-name: _core-adr-policy-008-policy-standards-structured
-description: Extends policy-standards with a numbered rule format for Policy documents that define strong policies or rules, or need individually referenceable items. Use when a Policy must expose explicit rule blocks that other documents or skills may cite by identifier.
-apply-to: Policy documents requiring structured rule blocks
-valid-from: 2025-01-01
----
-
-# _core-adr-policy-008: Policy standards - structured
-
-## Context and Problem Statement
-
-Some Policy 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 Details" are fragile and ambiguous.
-
-Question: How should a Policy document expose strong or individually referenceable rules or policies so they stay explicit, stable, and easy to cite?
-
-## Decision Outcome
-
-**Numbered rule blocks inside Details with a canonical citation syntax**
-
-When a Policy document defines strong rules or policies that MUST be stated explicitly, or when documents and skills need to cite individual rules precisely, each rule MUST be placed inside `### Details` as a numbered heading block. Referencing documents and skills MUST cite rules using the canonical dot-notation identifier.
-
-### 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 a Policy without duplicating the full policy text. Standard Policies that do not define strong rule sets and do not need item-level citation SHOULD follow `_core-adr-policy-002-policy-standards` without adding numbered rule headings.
-
-#### Rule block format
-
-Each numbered rule MUST be written as:
-
-```markdown
-#### [NN]-[short-rule-title-in-mandatory-advisory-language-in-kebab-case-<12-words]
-[Body using mandatory or advisory language as defined in _core-adr-policy-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 NOT be reused after a rule is removed. The short descriptive title MUST be in kebab-case (lowercase words separated by hyphens, no spaces or uppercase letters) and express the rule summary contents (e.g.: "43-code-must-be-linted", "12-use-standard-file-structure", "02-log-all-errors-to-mlflow")
-
-Rule bodies MUST use the mandatory or advisory language terms defined in `_core-adr-policy-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:
-
-```
-policy-name.NN-short-rule-title-in-kebab-case
-```
-
-Examples:
-
-- `_core-adr-policy-008-policy-standards-structured.01-always-use-numbered-rules-for-strong-or-referenceable-policies`
-- `_local-bdr-policy-003-data-retention-policy.02-purge-schedule-for-pii`
-
-The `policy-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.
-
-#### 01-always-use-numbered-rules-for-strong-or-referenceable-policies
-
-Numbered rule blocks MUST be added to a Policy 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 SHOULD NOT be done. Standard Policy documents that do not define strong rule sets and are not expected to be cited at the rule level SHOULD follow `_core-adr-policy-002-policy-standards` without this structured format.
-
-#### 02-rule-numbering-must-be-stable
-
-Rule numbers MUST NOT 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-policy-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: `policy-name.NN-short-rule-title-in-kebab-case`. Prose paraphrases such as "see rule 3" or "the third rule in that Policy" 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 Details** — Prefix each rule heading with a two-digit sequence number and use dot-notation for citations.
-  * Reason: Minimal addition to the existing Policy template, stable identifiers independent of heading text, and fully compatible with `_core-adr-policy-002-policy-standards`.
-
-## References
-
-- [_core-adr-policy-001 - XDRS core](001-xdrs-core.md)
-- [_core-adr-policy-002 - Policy standards](002-policy-standards.md)