xdrs-core 0.14.5 → 0.15.1

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

@@ -1,3 +1,8 @@
+---
+name: _core-adr-001-xdrs-core
+description: Defines the core XDR framework including types (ADR, BDR, EDR), folder structure, scopes, subjects, and index requirements. Use when structuring or navigating decision records.
+---
+
 # _core-adr-001: XDRs core
 
 ## Context and Problem Statement
@@ -31,6 +36,7 @@ Collectively, these are referred to as XDRs.
 - ALWAYS use the following folder structure for XDR documents:
   `.xdrs/[scope]/[type]/[subject]/[number]-[short-title].md`
 - ALWAYS ignore symlinks paths. NEVER create or update documents inside symlinked folders.
+- **Readonly files are external XDRs.** A file with read-only permissions (e.g., `444` set by a distribution tool such as filedist) was distributed from an external source repository. It must NEVER be modified locally. To change it, submit the change to the source repository and re-extract the updated package.
 - Optional supporting artifacts under the same subject:
   - `.xdrs/[scope]/[type]/[subject]/researches/[number]-[short-title].md`
   - `.xdrs/[scope]/[type]/[subject]/skills/[number]-[skill-name]/SKILL.md`

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

@@ -1,3 +1,8 @@
+---
+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
@@ -14,21 +19,46 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 
 - 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.
-- XDRs MAY include a `## Metadata` section, but only when at least one supported metadata field is present. When used, `## Metadata` MUST appear immediately before `## Context and Problem Statement`.
-- Supported XDR metadata fields are:
-  - `Valid:` Optional. Defines a convergence date after which the decision is expected to be fully adopted. Use ISO date format: `from YYYY-MM-DD`. New implementations SHOULD adopt the decision immediately, but compliance is not enforced during reviews until the convergence date.
-  - `Applied to:` Optional. A short description of the contexts in which the decision is applicable. Keep it under 40 words. If omitted, the decision should be interpreted as applying to all logically applicable elements according to the decision text itself. Examples: `Only frontend code`, `JavaScript projects`, `Performance-sensitive codebases`
+- 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. |
+| `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`. |
+| `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.
+    applied-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:` first. If a convergence date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-  - Check `Applied to:` next to determine whether the decision fits the current codebase, system, workflow, or audience.
+  - 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 `applied-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 `### Implementation Details` section SHOULD state relevant boundaries or exceptions and what a reader should do or avoid in common cases. Use `## Metadata` as the first-pass filter for applicability, then keep nuanced boundaries in the decision text.
+- 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.
 - 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.
@@ -47,13 +77,17 @@ XDR documents are the authoritative policy for their scope, type, and subject. T
 All XDRs MUST follow this template
 
 ```markdown
-# [scope]-[type]-[number]: [Short Title]
+---
+name: [scope]-[type]-[number]-[short-title]
+description: [What this decision is about and when to use it]
+applied-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]
+---
 
-## Metadata
-
-[Optional section. Omit the entire section when none of `Valid:` or `Applied to:` is defined. Readers decide whether to use the XDR by checking `Valid:` first, then `Applied to:`, and finally the decision text itself.]
-Valid: [Optional. Use `from YYYY-MM-DD` to set a convergence date for adoption]
-Applied to: [Optional short applicability scope, under 40 words]
+# [scope]-[type]-[number]: [Short Title]
 
 ## Context and Problem Statement
 
@@ -93,9 +127,9 @@ Question: In the end, state explicitly the question that needs to be answered. E
 ```
 
 **Examples:**
-- Metadata examples:
-  - `Valid: from 2026-03-01`
-  - `Applied to: JavaScript projects`
+- Frontmatter examples:
+  - `valid-from: 2026-03-01`
+  - `applied-to: JavaScript projects`
 
 **XDR ID Examples:**
 - `business-x-adr-001` (not `ADR-business-x-001` or `business-x-adr-1`)

package/.xdrs/_core/adrs/principles/003-skill-standards.md

@@ -1,3 +1,8 @@
+---
+name: _core-adr-003-skill-standards
+description: Defines skill package standards including structure, SKILL.md format, and co-location with XDRs. Use when creating or reviewing skills.
+---
+
 # _core-adr-003: Skill standards
 
 ## Context and Problem Statement

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

@@ -1,3 +1,8 @@
+---
+name: _core-adr-004-article-standards
+description: Defines article document standards for synthesizing and linking XDRs, research, and skills. Use when creating or reviewing articles.
+---
+
 # _core-adr-004: Article standards
 
 ## Context and Problem Statement

package/.xdrs/_core/adrs/principles/005-semantic-versioning-for-xdr-packages.md

@@ -1,3 +1,8 @@
+---
+name: _core-adr-005-semantic-versioning-for-xdr-packages
+description: Defines how semantic versioning applies to XDR packages. Use when publishing or versioning a package containing XDRs, research, skills, or articles.
+---
+
 # _core-adr-005: Semantic versioning for XDR packages
 
 ## Context and Problem Statement

package/.xdrs/_core/adrs/principles/006-research-standards.md

@@ -1,3 +1,8 @@
+---
+name: _core-adr-006-research-standards
+description: Defines research document standards including IMRAD structure and traceability to XDRs. Use when creating or reviewing research documents.
+---
+
 # _core-adr-006: Research standards
 
 ## Context and Problem Statement

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

@@ -1,3 +1,8 @@
+---
+name: _core-adr-007-plan-standards
+description: Defines plan document standards for describing problems, solutions, and activities. Use when creating or reviewing plans.
+---
+
 # _core-adr-007: Plan standards
 
 ## Context and Problem Statement

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

@@ -24,10 +24,10 @@ Performs a structured review of code changes or files against the XDRs in the re
 
 1. Gather all Decision Records from `.xdrs/index.md` starting from the working directory.
    - XDR scopes are controlled by nested folders; some are broad, others domain-specific.
-   - Extract metadata first to decide whether each XDR should be used for the current review context.
+   - 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:` first. If a convergence date is present and has not yet been reached, the decision SHOULD be adopted for new implementations but is not enforced during reviews.
-   - Check `Applied to:` second. Keep only XDRs whose stated scope fits the files, systems, or workflows under review.
+   - 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 `applied-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.
 

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

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

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

@@ -5,16 +5,12 @@
       ".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/articles/001-xdrs-overview.md",
-      ".xdrs/_local/adrs/index.md",
-      ".xdrs/_local/adrs/principles/researches/001-research-and-decision-lifecycle.md",
+      ".xdrs/_core/adrs/principles/skills/004-write-article/SKILL.md",
       ".xdrs/index.md",
       "AGENTS.md"
     ],
-    "contextHash": "4935b72a3613a4fad7cc72e477afed7a"
+    "contextHash": "21d52973f1313bfbbf238f69e080de81"
   }
 }

package/.xdrs/_core/adrs/principles/skills/005-write-research/005-write-research.test.int.js

@@ -14,7 +14,7 @@ test('005-write-research creates an IMRAD research document in copy mode', async
 			workspaceMode: 'copy',
 			...copilotCmd(REPO_ROOT),
 		},
-		'Create a very small research document with the following data: Java vs Python for datascience projects. Java has much less libraries and community momentum than Python. Java is faster, but in general our DS applications doesn\'t require high performance. Is some cases we could use Spark for data and very specific ETL and transformations, but in general Python should be the norm for Data Science projects, especially in the early phases.',
+		'Create a very small research document in principles subject with the following data: Java vs Python for datascience projects. Java has much less libraries and community momentum than Python. Java is faster, but in general our DS applications doesn\'t require high performance. Is some cases we could use Spark for data and very specific ETL and transformations, but in general Python should be the norm for Data Science projects, especially in the early phases.',
 		'Verify that a research file was created under .xdrs/_local/edrs/application/researches/, that it contains the sections Abstract, Introduction, Methods, Results, Discussion, Conclusion, and References, have the right ratio of words on the sections (not worse than 50% in deviation) and that the content contains all the provided data in input prompt, and doesn\'t contain more than 20% of additional information outside the central topic. Check also if there is at least one comparison table between the options, ',
 		null,
 		true

package/lib/lint.js

@@ -105,11 +105,11 @@ function lintRootIndex(rootIndexPath, xdrsRoot, actualTypeIndexes, errors) {
 
   const linkedTypeIndexes = links.filter((linkPath) => isCanonicalTypeIndex(linkPath, xdrsRoot));
   const linkedSet = new Set(linkedTypeIndexes.map(normalizePath));
+  const localScopePath = normalizePath(path.join(xdrsRoot, '_local'));
 
-  for (const indexPath of linkedTypeIndexes) {
-    const scopeName = path.basename(path.dirname(path.dirname(indexPath)));
-    if (scopeName === '_local') {
-      errors.push(`Root index must not link _local canonical index: ${displayPath(rootIndexPath, indexPath)}`);
+  for (const linkPath of links) {
+    if (isPathInside(localScopePath, linkPath) || normalizePath(linkPath) === localScopePath) {
+      errors.push(`Root index must not link into _local scope: ${displayPath(rootIndexPath, linkPath)}`);
     }
   }
 
@@ -235,6 +235,7 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
   }
 
   const number = match[1];
+  const shortTitle = match[2];
   const previous = xdrNumbers.get(number);
   if (previous) {
     errors.push(`Duplicate XDR number ${number} in ${scopeName}/${typeName}: ${toDisplayPath(previous)} and ${toDisplayPath(filePath)}`);
@@ -248,124 +249,42 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
 
   const content = fs.readFileSync(filePath, 'utf8');
   const expectedHeader = `# ${scopeName}-${TYPE_TO_ID[typeName]}-${number}:`;
-  const firstLine = firstNonEmptyLine(content);
+  const firstLine = firstNonEmptyLine(stripFrontmatter(content));
   if (!firstLine.startsWith(expectedHeader)) {
     errors.push(`XDR title must start with "${expectedHeader}": ${toDisplayPath(filePath)}`);
   }
 
-  lintXdrMetadata(content, filePath, errors);
+  const expectedName = `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${shortTitle}`;
+  lintXdrFrontmatter(content, expectedName, filePath, errors);
   lintDocumentResourceLinks(filePath, errors);
 }
 
-function lintXdrMetadata(content, filePath, errors) {
-  const lines = content.split(/\r?\n/);
-  const ignoredLines = findIgnoredMarkdownLines(lines);
-  const metadataLine = findHeadingLine(lines, ignoredLines, '## Metadata');
-  const contextLine = findHeadingLine(lines, ignoredLines, '## Context and Problem Statement');
-  const headingLines = findHeadingLines(lines, ignoredLines);
-
-  if (metadataLine !== -1) {
-    const nextHeadingLine = headingLines.find((lineIndex) => lineIndex > metadataLine);
-    if (nextHeadingLine !== contextLine) {
-      errors.push(`XDR metadata section must appear immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
-    }
-  }
-
-  if (metadataLine !== -1 && contextLine !== -1 && metadataLine > contextLine) {
-    errors.push(`XDR metadata section must appear before Context and Problem Statement: ${toDisplayPath(filePath)}`);
-  }
-
-  const metadataRange = metadataLine === -1
-    ? null
-    : {
-        start: metadataLine + 1,
-        end: (headingLines.find((lineIndex) => lineIndex > metadataLine) ?? lines.length) - 1
-      };
-  const appliedLineNumbers = findFieldLines(lines, ignoredLines, 'Applied to:');
-  const validLineNumbers = findFieldLines(lines, ignoredLines, 'Valid:');
-
-  if (!metadataRange && (appliedLineNumbers.length > 0 || validLineNumbers.length > 0)) {
-    errors.push(`XDR metadata fields require a ## Metadata section immediately before Context and Problem Statement: ${toDisplayPath(filePath)}`);
+function lintXdrFrontmatter(content, expectedName, filePath, errors) {
+  const fm = extractFrontmatter(content);
+  if (!fm.present) {
+    errors.push(`XDR must start with a YAML frontmatter block: ${toDisplayPath(filePath)}`);
     return;
   }
-
-  if (!metadataRange) {
-    return;
-  }
-
-  const metadataApplied = appliedLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
-  const metadataValid = validLineNumbers.filter((lineIndex) => isLineInsideRange(lineIndex, metadataRange));
-
-  if (metadataApplied.length === 0 && metadataValid.length === 0) {
-    errors.push(`XDR metadata section must be omitted when no metadata fields are defined: ${toDisplayPath(filePath)}`);
+  if (!fm.name) {
+    errors.push(`XDR frontmatter must include a non-empty name field: ${toDisplayPath(filePath)}`);
+  } else if (fm.name !== expectedName) {
+    errors.push(`XDR frontmatter name must be "${expectedName}": ${toDisplayPath(filePath)}`);
   }
-
-  if (metadataApplied.length > 1) {
-    errors.push(`XDR metadata must not repeat Applied to: ${toDisplayPath(filePath)}`);
+  if (!fm.description) {
+    errors.push(`XDR frontmatter must include a non-empty description field: ${toDisplayPath(filePath)}`);
   }
-
-  if (metadataValid.length > 1) {
-    errors.push(`XDR metadata must not repeat Valid: ${toDisplayPath(filePath)}`);
-  }
-
-  for (const lineIndex of [...appliedLineNumbers, ...validLineNumbers]) {
-    if (!isLineInsideRange(lineIndex, metadataRange)) {
-      errors.push(`XDR metadata fields must be declared inside ## Metadata: ${toDisplayPath(filePath)}`);
-      break;
+  if (fm.validFrom !== undefined) {
+    if (!isIsoDate(fm.validFrom)) {
+      errors.push(`XDR frontmatter valid-from must be a valid ISO date YYYY-MM-DD: ${toDisplayPath(filePath)}`);
     }
   }
-
-  let previousFieldOrder = -1;
-  for (let lineIndex = metadataRange.start; lineIndex <= metadataRange.end; lineIndex += 1) {
-    if (ignoredLines[lineIndex]) {
-      continue;
+  if (fm.appliedTo !== undefined) {
+    const words = countWords(fm.appliedTo);
+    if (words === 0) {
+      errors.push(`XDR frontmatter applied-to must not be empty: ${toDisplayPath(filePath)}`);
+    } else if (words >= 40) {
+      errors.push(`XDR frontmatter applied-to must be under 40 words: ${toDisplayPath(filePath)}`);
     }
-    const trimmed = lines[lineIndex].trim();
-    if (trimmed === '') {
-      continue;
-    }
-    const currentFieldOrder = trimmed.startsWith('Valid:')
-      ? 0
-      : trimmed.startsWith('Applied to:')
-        ? 1
-        : -1;
-    if (currentFieldOrder === -1) {
-      errors.push(`XDR metadata section only supports Valid: and Applied to: fields: ${toDisplayPath(filePath)}`);
-      break;
-    }
-    if (currentFieldOrder < previousFieldOrder) {
-      errors.push(`XDR metadata fields must be ordered as Valid:, Applied to: ${toDisplayPath(filePath)}`);
-      break;
-    }
-    previousFieldOrder = currentFieldOrder;
-  }
-
-  if (metadataApplied.length === 1) {
-    const value = lines[metadataApplied[0]].slice('Applied to:'.length).trim();
-    if (value === '') {
-      errors.push(`XDR Applied to: must not be empty: ${toDisplayPath(filePath)}`);
-    } else if (countWords(value) >= 40) {
-      errors.push(`XDR Applied to: must be under 40 words: ${toDisplayPath(filePath)}`);
-    }
-  }
-
-  if (metadataValid.length === 1) {
-    lintValidField(lines[metadataValid[0]], filePath, errors);
-  }
-}
-
-function lintValidField(line, filePath, errors) {
-  const value = line.slice('Valid:'.length).trim().replace(/\.$/, '');
-
-  const validMatch = value.match(/^from\s+(\d{4}-\d{2}-\d{2})$/);
-  if (!validMatch) {
-    errors.push(`XDR Valid: must be from YYYY-MM-DD: ${toDisplayPath(filePath)}`);
-    return;
-  }
-
-  const fromDate = validMatch[1];
-  if (!isIsoDate(fromDate)) {
-    errors.push(`XDR Valid: must use ISO dates in YYYY-MM-DD format: ${toDisplayPath(filePath)}`);
   }
 }
 
@@ -408,11 +327,18 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     }
 
     const skillContent = fs.readFileSync(skillFilePath, 'utf8');
-    const frontmatterName = extractFrontmatterName(skillContent);
-    if (!frontmatterName) {
-      errors.push(`SKILL.md is missing a frontmatter name field: ${toDisplayPath(skillFilePath)}`);
-    } else if (frontmatterName !== entry.name) {
-      errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+    const skillFm = extractFrontmatter(skillContent);
+    if (!skillFm.present) {
+      errors.push(`SKILL.md must start with a YAML frontmatter block: ${toDisplayPath(skillFilePath)}`);
+    } else {
+      if (!skillFm.name) {
+        errors.push(`SKILL.md frontmatter must include a non-empty name field: ${toDisplayPath(skillFilePath)}`);
+      } else if (skillFm.name !== entry.name) {
+        errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+      }
+      if (!skillFm.description) {
+        errors.push(`SKILL.md frontmatter must include a non-empty description field: ${toDisplayPath(skillFilePath)}`);
+      }
     }
 
     lintDocumentResourceLinks(skillFilePath, errors);
@@ -677,14 +603,27 @@ function shouldValidateResourceLink(rawTarget) {
     || IMAGE_EXTENSIONS.has(extension);
 }
 
-function extractFrontmatterName(content) {
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-  if (!frontmatterMatch) {
-    return null;
-  }
-
-  const nameMatch = frontmatterMatch[1].match(/^name:\s*(.+)$/m);
-  return nameMatch ? nameMatch[1].trim() : null;
+function extractFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
+  if (!match) {
+    return { present: false, name: null, description: false, validFrom: undefined, appliedTo: undefined };
+  }
+  const block = match[1];
+  const nameMatch = block.match(/^name:\s*(.+)$/m);
+  const validFromMatch = block.match(/^valid-from:\s*(.+)$/m);
+  const appliedToMatch = block.match(/^applied-to:\s*(.+)$/m);
+  return {
+    present: true,
+    name: nameMatch ? nameMatch[1].trim() || null : null,
+    description: /^description:\s*\S/m.test(block),
+    validFrom: validFromMatch ? validFromMatch[1].trim() : undefined,
+    appliedTo: appliedToMatch ? appliedToMatch[1].trim() : undefined,
+  };
+}
+
+function stripFrontmatter(content) {
+  const match = content.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  return match ? content.slice(match[0].length) : content;
 }
 
 function findIgnoredMarkdownLines(lines) {

package/lib/testPrompt.js

@@ -242,6 +242,7 @@ async function runJudgePhase({ judgePrompt, commandTemplate, continueFlag, works
 		'Use target="output" when the issue is in the final task output and target="workspace" when it is not tied to a specific file.',
 		'Include 1-based line numbers when you cite a file or the output text. Include the exact judge-prompt phrase that triggered each finding in assertionRef.',
 		'NEVER change any file during judge evaluation. If you identify an issue that would require a file change to fix, report it as a finding instead.',
+		'</INSTRUCTIONS>',
 		'',
 		judgePrompt,
 	].join('\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xdrs-core",
-  "version": "0.14.5",
+  "version": "0.15.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",