xdrs-core 0.38.1 → 0.38.4

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/001-xdrs-core.md

@@ -144,8 +144,8 @@ Policies can be of different kinds, depending on the nature of the decision:
   - 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)
-    - Add a list of other scope indexes that this scope might be related to (only add scopes that might be overridden). E.g: "business-x-mobileapp" scope could refer to "business-x" and "sensitive-data" scopes in its index list. XDRS in scopes listed last override XDRS in scopes listed first when addressing the same topic.
-    - Each XDRS element entry in the index MUST include a short description of its content. The description SHOULD use an imperative statement or the question it answers when possible (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?", "PNPM vs Yarn comparison study"
+    - Add links to related scope indexes that this scope might override or be overridden by (scopes listed last override earlier ones on the same topic).
+    - Each XDRS element entry MUST include a short description. SHOULD use an imperative statement or the question it answers (<15 words). Example: "Use this while planning a new feature", "What communication tone we use with our customers?"
   - Outside the scopes, keep a root index in `[xdrs-root]/index.md` that links to each scope index (`[xdrs-root]/[scope]/index.md`). Add the text "XDRS scopes listed last override the ones listed first". The root index MUST NOT link directly to type indexes; readers navigate from the scope index to the type indexes. Use the link text pattern `View scope [scope_name]` for each scope link (e.g. `[View scope myteam] linking to (myteam/index.md)`).
   - MUST verify if indexes are up to date after making changes
 - **Scope index**

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

@@ -28,7 +28,7 @@ Policy documents are the authoritative source of truth for their scope, type, an
 | `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]-policy-[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` | Yes | Short description of contexts this decision is applicable to. Keep it under 40 words. Use `All scopes` when the decision applies broadly. Examples: `Only frontend code`, `JavaScript projects`, `All scopes`. |
-| `valid-from` | Yes | 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. Defaults to the date the Policy was created. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—do not update it to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
+| `valid-from` | Yes | 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. Defaults to the date the Policy was created. When updating an existing Policy whose `valid-from` date has already passed, preserve the original date—it MUST NOT be updated to the current date. The historical date shows when the policy was originally enabled and is important for understanding policy evolution. |
 | `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. |
 
@@ -62,6 +62,8 @@ Policy documents are the authoritative source of truth for their scope, type, an
   - Types in IDs: `adr-policy`, `bdr-policy`, `edr-policy`
   - Define the next number of a Policy by checking what is the highest number present in the type+scope. Don't fill numbering gaps, as they might be old deleted Policies and we MUST NOT reuse numbers of different documents/decisions. Numbering gaps are expected.
 - Policies MUST be concise and reference other Policies to avoid duplication.
+- Policies MUST NOT contain duplicated content: the same rule or information MUST NOT appear more than once in the document, whether stated identically or rephrased. Consolidate into a single authoritative statement and reference it where needed.
+- Policies MUST NOT contain conflicting content: all rules and statements within the same document MUST be consistent with each other.
 - 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.
 - Policies MUST NOT include historical change notes or descriptions of what changed from a previous version. State only the current rule that MUST be followed. Historical context is available via git history or versioned packages.
@@ -69,7 +71,8 @@ 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.
+- Each policy rule and rule block MUST be unambiguous: it MUST be possible to clearly follow, check, and discuss it without requiring additional interpretation.
+- 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 +161,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/012-reference-scope-type.md

@@ -35,7 +35,7 @@ Use `scope-type: reference` when the scope contains:
 - Business area procedure standards: how sales processes SHOULD be conducted, how customer data MUST be handled, how marketing communications MUST comply with applicable regulations.
 - Operational compliance guidelines: finance controls, accounting procedures, public communication standards, customer data management rules.
 
-Do not use `scope-type: reference` for scopes that represent a live service, an active team, or a production system. Use `scope-type: platform` for those.
+`scope-type: reference` MUST NOT be used for scopes that represent a live service, an active team, or a production system. Use `scope-type: platform` for those.
 
 #### 03-naming-convention
 

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)) {
+    if (!NORMATIVE_KEYWORDS_RE.test(ruleBodyTextForEmphasis)) {
       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')),
@@ -2709,6 +2709,33 @@ test('reports structured rule block body missing normative language', () => {
   expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.03-rule-body-must-use-normative-language]');
 });
 
+test('reports structured rule block body with normative language only inside a code block', () => {
+  const workspaceRoot = createWorkspace('structured-rule-normative-in-code-block', {
+    '.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',
+      '',
+      'Here is an example:',
+      '',
+      '```',
+      'You MUST do this.',
+      '```',
+      '',
+      'No normative language in prose.',
+    ].join('\n')),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('structured rule body must contain normative language');
+  expect(result.errors.join('\n')).toContain('[_core-adr-policy-008.03-rule-body-must-use-normative-language]');
+});
+
 test('accepts valid structured rule blocks', () => {
   const workspaceRoot = createWorkspace('structured-rule-valid', {
     '.xdrs/index.md': rootIndex(),
@@ -2733,6 +2760,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.4",
   "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)