xdrs-core 0.22.1 → 0.24.0

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

@@ -14,6 +14,7 @@ Foundational standards, principles, and guidelines.
 - [_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
+- [_core-adr-009](principles/009-presentation-standards.md) - **Presentation standards** — How to structure Marp slide presentations that support XDR documents
 
 ## Skills
 
@@ -25,6 +26,7 @@ Step-by-step procedural guides for humans and AI agents.
 - [004-write-article](principles/skills/004-write-article/SKILL.md) - **Write Article** — create a new article document
 - [005-write-research](principles/skills/005-write-research/SKILL.md) - **Write Research** — create a new research document
 - [006-write-plan](principles/skills/006-write-plan/SKILL.md) - **Write Plan** — create a new plan document
+- [007-write-presentation](principles/skills/007-write-presentation/SKILL.md) - **Write Presentation** — create Marp slide presentations for XDR documents
 
 ## Articles
 

package/.xdrs/_core/adrs/principles/009-presentation-standards.md

@@ -0,0 +1,52 @@
+---
+name: _core-adr-009-presentation-standards
+description: Defines how Marp slide presentations are structured, named, placed, and linked within XDR projects. Use when creating, reviewing, or linting slide decks that support XDR documents.
+---
+
+# _core-adr-009: Presentation standards
+
+## Context and Problem Statement
+
+Teams often need slide presentations to communicate decisions, research findings, plans, or article content to different audiences. Without a standard, slides drift from the authoritative documents, use inconsistent formats, and become disconnected from the decision records they support.
+
+How should slide presentations be structured, placed, and maintained within the XDR framework so they remain consistent, discoverable, and always traceable to the documents they support?
+
+## Decision Outcome
+
+**Marp Markdown slides co-located in `.assets/` next to the parent document**
+
+Presentations are Markdown files in Marp format, stored in the `.assets/` folder of the document they support, with bidirectional links and strict naming conventions.
+
+### Details
+
+- Slides are supporting media for XDR documents. They must never exist as standalone artifacts without a parent decision, research, article, or plan.
+- Slides must use the [Marp](https://marp.app/) Markdown format with a minimal YAML frontmatter block at the beginning of the file:
+  ```
+  ---
+  marp: true
+  ---
+  ```
+  Additional Marp configuration keys (e.g. `theme`, `paginate`, `header`, `footer`) may be added when needed, but `marp: true` is always required as the first frontmatter key.
+- Slide files must be placed in the `.assets/` folder next to the element they relate to, following the `.assets/` placement rules defined in `_core-adr-001`.
+- The parent document must always contain a link to the slide file. The slide file must always contain a link back to the parent document at the end of the presentation. This bidirectional linking is mandatory.
+- Slide files must use the same base name as the parent file, suffixed with `-slides`. When multiple slide sets exist for the same parent, append a context indicator after `-slides` (e.g. `-slides-overview`, `-slides-executive`).
+  - Example: parent `003-naming-conventions.md` produces `003-naming-conventions-slides.md` or `003-naming-conventions-slides-overview.md`.
+- Slide file names must not exceed 64 characters (including the `.md` extension).
+- Slide file names must be lowercase.
+- When slides refer to content from multiple decisions, plans, or research documents, an article explaining the combined view must be written first. The slides then support that article, not the individual documents directly.
+- Slides should contain minimal text. Prefer Mermaid diagrams, short bullet points, ASCII art, key short statements, and tables. Use longer text only when the exact wording must be evaluated by the audience (policies, texts under discussion, controls).
+- Slides should follow a clean, linear storytelling structure (context, problem, solution, actions). Follow the structure of the underlying document, extracting the most important points and stressing central questions, answers, doubts, decisions, and risks.
+- Define the central message or objective of the presentation before creating the slides. If the objective is unclear or there are multiple possible paths, ask the user before proceeding.
+- Always identify the target audience (executives, engineers, specialists, control). If the audience is not clear from the underlying document, ask before creating the slides. Include audience info in the file name when multiple audiences exist (e.g. `005-rail-standards-slides-executive.md`).
+- Keep presentations under 30 slides. Create separate slide sets for different views or audiences when needed.
+- Slides never replace decision records or related document contents. When the underlying document changes, the associated slides must be reviewed and updated to stay consistent.
+- Never use emojis in slide content.
+- Always use lowercase file names.
+
+## References
+
+- [_core-adr-001 - XDRs core](001-xdrs-core.md) - Framework structure and `.assets/` placement rules
+- [_core-adr-002 - XDR standards](002-xdr-standards.md) - XDR document writing rules
+- [_core-adr-004 - Article standards](004-article-standards.md) - Article standards for multi-document views
+- [007-write-presentation skill](skills/007-write-presentation/SKILL.md) - Skill for creating slide presentations
+- [Marp](https://marp.app/) - Markdown Presentation Ecosystem

package/.xdrs/_core/adrs/principles/skills/007-write-presentation/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: 007-write-presentation
+description: >
+  Creates a Marp slide presentation for an existing XDR document (decision, research, article, or plan).
+  Activate this skill when the user asks to create slides, a presentation, or a slide deck for an XDR document.
+metadata:
+  author: flaviostutz
+  version: "1.0"
+---
+
+## Overview
+
+Guides the creation of a Marp Markdown slide presentation that supports an existing XDR document. The skill ensures the slides follow presentation standards (`_core-adr-009`), are correctly placed in the `.assets/` folder, and maintain bidirectional links with the parent document.
+
+## Instructions
+
+### Phase 1: Identify the Parent Document
+
+1. Read `.xdrs/_core/adrs/principles/009-presentation-standards.md` in full to internalize all presentation rules.
+2. Read `.xdrs/_core/adrs/principles/001-xdrs-core.md` for `.assets/` placement rules and general framework structure.
+3. Identify the parent document (decision, research, article, or plan) that the slides will support. The parent document must already exist. If no parent document exists, inform the user that slides cannot be standalone and suggest creating the parent document first.
+4. If the user wants slides covering content from multiple documents, check whether an article already exists that synthesizes those documents. If not, suggest creating an article first (using the 004-write-article skill) and then creating slides for that article.
+
+### Phase 2: Define the Presentation Scope
+
+1. Read the parent document in full.
+2. Define the central message or objective of the presentation. If the objective is ambiguous or there are multiple possible paths, ask the user before proceeding. Ask one question at a time.
+3. Identify the target audience. Check the parent document for audience indicators. If unclear, ask the user. Common audiences:
+   - **Executives**: high-level, strategic, outcome-focused
+   - **Engineers**: technical depth, implementation details, trade-offs
+   - **Specialists**: domain-specific depth, compliance, controls
+   - **Control**: risk, compliance, audit, governance focus
+4. Determine if multiple slide sets are needed for different audiences. If so, create separate files for each.
+
+### Phase 3: Plan the Slide Structure
+
+1. Extract the most important points from the parent document.
+2. Organize slides following a linear storytelling structure:
+   - **Context**: what is the situation, background, who is impacted
+   - **Problem**: what needs to be decided, addressed, or understood
+   - **Solution/Decision**: what was decided and why
+   - **Actions/Next Steps**: what happens now, who is responsible
+3. For each slide, identify the best format:
+   - Mermaid diagrams for flows, relationships, architecture
+   - Short bullet points for key decisions and trade-offs
+   - Tables for comparisons, options, criteria
+   - ASCII art for simple layouts or structures
+   - Key short statements for emphasis
+   - Longer text only when exact wording must be evaluated (policies, controls)
+4. Keep the total under 30 slides. If more content is needed, plan separate slide sets.
+
+### Phase 4: Determine the File Name
+
+1. Take the parent document file name (without `.md` extension).
+2. Append `-slides` for the primary set.
+3. If multiple sets exist, append a context indicator: `-slides-overview`, `-slides-executive`, `-slides-technical`, etc.
+4. Verify the final file name (including `.md`) is 64 characters or fewer. If it exceeds 64 characters, shorten the base name while keeping it recognizable.
+5. Ensure the file name is entirely lowercase.
+
+Examples:
+- Parent: `003-naming-conventions.md` -> `003-naming-conventions-slides.md`
+- Parent: `005-rail-standards.md` (executive audience) -> `005-rail-standards-slides-executive.md`
+- Parent: `001-xdrs-overview.md` (article) -> `001-xdrs-overview-slides.md`
+
+### Phase 5: Write the Slides
+
+Create the Marp Markdown file with this structure:
+
+```markdown
+---
+marp: true
+---
+
+# [Presentation Title]
+
+[Subtitle or context line]
+[Audience and date if relevant]
+
+---
+
+[Slide 2: Context/Background]
+
+---
+
+[Slide 3: Problem Statement]
+
+---
+
+[... additional slides ...]
+
+---
+
+# References
+
+- [Parent document title](relative/path/to/parent.md)
+- [Other related documents if applicable]
+```
+
+Rules:
+- The first line of YAML frontmatter must be `marp: true`. Additional Marp keys (`theme`, `paginate`, `header`, `footer`) may be added after.
+- Use `---` as the slide separator (standard Marp syntax).
+- The last slide must contain links back to the parent document and any other related documents.
+- Minimize text per slide. Prefer visual elements and short statements.
+- Stress central questions, answers, doubts, decisions, and risks from the parent document.
+- No emojis.
+- Use relative paths for all links.
+- Follow the audience-appropriate level of detail.
+
+### Phase 6: Update the Parent Document
+
+1. Add a link to the slide file in the parent document. Place it in the `## References` section or, for XDRs, in the most appropriate section.
+2. Use a descriptive link text such as "Presentation slides" pointing to the slide file in `.assets/`.
+
+### Phase 7: Write Files
+
+1. Create the slide file at the correct `.assets/` location:
+   - XDRs: `[xdrs-root]/[scope]/[type]/[subject]/.assets/[slide-file].md`
+   - Articles: `[xdrs-root]/[scope]/[type]/[subject]/articles/.assets/[slide-file].md`
+   - Research: `[xdrs-root]/[scope]/[type]/[subject]/researches/.assets/[slide-file].md`
+   - Skills: `[xdrs-root]/[scope]/[type]/[subject]/skills/[number]-[skill-name]/.assets/[slide-file].md`
+   - Plans: `[xdrs-root]/[scope]/[type]/[subject]/plans/.assets/[slide-file].md`
+2. Update the parent document with the link to the slide file.
+3. Verify that the slide file name is <= 64 characters and lowercase.
+
+### Phase 8: Verify with Lint
+
+1. Run the CLI lint utility from the repository root:
+   ```
+   npx -y xdrs-core lint .
+   ```
+2. Fix all reported errors before considering the task complete.
+
+### Constraints
+
+- MUST follow presentation standards from `_core-adr-009` exactly.
+- MUST NOT create slides without an existing parent document.
+- MUST NOT create standalone slides that reference multiple documents without an article as the parent.
+- MUST maintain bidirectional links between slides and parent document.
+- MUST keep slide file names under 64 characters.
+- MUST include `marp: true` in the slide frontmatter.
+- MUST keep presentations under 30 slides.
+- MUST ask the user about audience and objective when not clear from context.
+
+## Examples
+
+**Input**: "Create slides for our naming conventions decision"
+- Locate the parent XDR (e.g. `003-naming-conventions.md`)
+- Ask: "Who is the target audience for these slides?"
+- Create: `.assets/003-naming-conventions-slides.md`
+- Update: Add link in `003-naming-conventions.md`
+
+**Input**: "Create an executive presentation covering our security and data decisions"
+- Check if an article synthesizing security + data decisions exists
+- If not, suggest creating the article first
+- Create slides for the article, not the individual XDRs
+
+## Edge Cases
+
+- If the parent document does not exist, do not create slides. Inform the user and suggest creating the parent first.
+- If the slide file name would exceed 64 characters, shorten the base name while keeping it recognizable.
+- If the content requires more than 30 slides, split into multiple slide sets with distinct audience or topic focus.
+- If the parent document changes after slides are created, the slides must be reviewed and updated.
+
+## References
+
+- [_core-adr-009 - Presentation standards](../../009-presentation-standards.md)
+- [_core-adr-001 - XDRs core](../../001-xdrs-core.md)
+- [_core-adr-004 - Article standards](../../004-article-standards.md)
+- [_core-adr-003 - Skill standards](../../003-skill-standards.md)

package/.xdrs/_core/index.md

@@ -35,9 +35,13 @@ Each artifact type has its own writing standard:
 
 The business decision [_core-bdr-001](bdrs/principles/001-xdr-decisions-and-skills-usage.md) establishes how agents and humans must use XDR decisions and skills, separating policy authority (which lives in XDRs) from execution guidance (which lives in skills).
 
+### Presentation standards
+
+Slide presentations that support XDR documents follow [_core-adr-009](adrs/principles/009-presentation-standards.md). Slides use the Marp Markdown format, live in `.assets/` next to the document they support, and must maintain bidirectional links with the parent document.
+
 ### Available skills
 
-The `_core` scope ships with six skills that automate the most common framework operations:
+The `_core` scope ships with seven skills that automate the most common framework operations:
 
 - **001-lint** reviews code and files against applicable XDRs
 - **002-write-xdr** guides creation of a new decision record
@@ -45,6 +49,7 @@ The `_core` scope ships with six skills that automate the most common framework
 - **004-write-article** guides creation of a new article
 - **005-write-research** guides creation of a new research document
 - **006-write-plan** guides creation of a new execution plan
+- **007-write-presentation** guides creation of Marp slide presentations
 
 ### Getting started
 

package/lib/lint.js

@@ -28,6 +28,11 @@ const SKILL_PACKAGE_OPTIONAL_DIRS = new Set(['scripts', 'references', RESOURCE_D
 const XDR_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'apply-to', 'valid-from', 'license', 'metadata']);
 const SKILL_ALLOWED_FRONTMATTER_KEYS = new Set(['name', 'description', 'license', 'metadata', 'compatibility', 'allowed-tools']);
 const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.bmp']);
+const EMOJI_RE = /\p{Extended_Pictographic}/u;
+const XDR_MAX_WORDS = 2600;
+const ARTICLE_MAX_WORDS = 5000;
+const RESEARCH_MAX_WORDS = 5000;
+const SKILL_MAX_WORDS = 6500;
 
 function runLintCli(args) {
   if (args.includes('--help') || args.includes('-h')) {
@@ -331,6 +336,8 @@ function lintXdrFile(xdrsRoot, scopeName, typeName, filePath, xdrNumbers, errors
     || `${scopeName}-${TYPE_TO_ID[typeName]}-${number}-${match[2]}`;
   lintXdrFrontmatter(content, expectedName, filePath, errors);
   lintRequiredSections(content, filePath, XDR_REQUIRED_SECTIONS, 'XDR', errors);
+  lintNoEmojis(content, filePath, 'XDR', errors);
+  lintWordCount(content, filePath, 'XDR', XDR_MAX_WORDS, errors);
   lintDocumentLinks(filePath, xdrsRoot, scopeName, errors, externalScopes);
 }
 
@@ -367,11 +374,18 @@ function lintXdrFrontmatter(content, expectedName, filePath, errors) {
   }
   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)}`);
+  } else {
+    if (fm.name !== expectedName) {
+      errors.push(`XDR frontmatter name must be "${expectedName}": ${toDisplayPath(filePath)}`);
+    }
+    if (fm.name.length > 64) {
+      errors.push(`XDR frontmatter name must be 64 characters or fewer: ${toDisplayPath(filePath)}`);
+    }
   }
   if (!fm.description) {
     errors.push(`XDR frontmatter must include a non-empty description field: ${toDisplayPath(filePath)}`);
+  } else if (fm.descriptionText && fm.descriptionText.length > 1024) {
+    errors.push(`XDR frontmatter description must be 1024 characters or fewer: ${toDisplayPath(filePath)}`);
   }
   if (fm.validFrom !== undefined) {
     if (!isIsoDate(fm.validFrom)) {
@@ -455,11 +469,18 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
     } 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)}`);
+      } else {
+        if (skillFm.name !== entry.name) {
+          errors.push(`Skill frontmatter name must match package directory "${entry.name}": ${toDisplayPath(skillFilePath)}`);
+        }
+        if (skillFm.name.length > 64) {
+          errors.push(`SKILL.md frontmatter name must be 64 characters or fewer: ${toDisplayPath(skillFilePath)}`);
+        }
       }
       if (!skillFm.description) {
         errors.push(`SKILL.md frontmatter must include a non-empty description field: ${toDisplayPath(skillFilePath)}`);
+      } else if (skillFm.descriptionText && skillFm.descriptionText.length > 1024) {
+        errors.push(`SKILL.md frontmatter description must be 1024 characters or fewer: ${toDisplayPath(skillFilePath)}`);
       }
       for (const key of skillFm.topLevelKeys) {
         if (!SKILL_ALLOWED_FRONTMATTER_KEYS.has(key)) {
@@ -468,6 +489,8 @@ function lintSkillsDirectory(xdrsRoot, scopeName, typeName, subjectName, skillsP
       }
     }
 
+    lintNoEmojis(skillContent, skillFilePath, 'Skill', errors);
+    lintWordCount(skillContent, skillFilePath, 'Skill', SKILL_MAX_WORDS, errors);
     lintDocumentLinks(skillFilePath, xdrsRoot, scopeName, errors, externalScopes);
     lintOrphanAssets(path.join(entryPath, RESOURCE_DIR_NAME), [skillFilePath], xdrsRoot, errors);
   }
@@ -519,6 +542,8 @@ function lintArticlesDirectory(xdrsRoot, scopeName, typeName, subjectName, artic
     }
 
     lintRequiredSections(content, entryPath, ARTICLE_REQUIRED_SECTIONS, 'Article', errors);
+    lintNoEmojis(content, entryPath, 'Article', errors);
+    lintWordCount(content, entryPath, 'Article', ARTICLE_MAX_WORDS, errors);
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors, externalScopes);
   }
 
@@ -571,6 +596,9 @@ function lintResearchDirectory(xdrsRoot, scopeName, typeName, subjectName, resea
     }
 
     lintRequiredSections(content, entryPath, RESEARCH_REQUIRED_SECTIONS, 'Research', errors);
+    lintResearchIntroductionQuestion(content, entryPath, errors);
+    lintNoEmojis(content, entryPath, 'Research', errors);
+    lintWordCount(content, entryPath, 'Research', RESEARCH_MAX_WORDS, errors);
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors, externalScopes);
   }
 
@@ -624,6 +652,7 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
 
     lintRequiredSections(content, entryPath, PLAN_REQUIRED_SECTIONS, 'Plan', errors);
     lintPlanExpectedEndDate(content, entryPath, errors);
+    lintNoEmojis(content, entryPath, 'Plan', errors);
     lintDocumentLinks(entryPath, xdrsRoot, scopeName, errors, externalScopes);
   }
 
@@ -632,6 +661,52 @@ function lintPlansDirectory(xdrsRoot, scopeName, typeName, subjectName, plansPat
   return artifacts;
 }
 
+function lintNoEmojis(content, filePath, docType, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  for (let i = 0; i < lines.length; i++) {
+    if (ignoredLines[i]) continue;
+    if (EMOJI_RE.test(lines[i])) {
+      errors.push(`${docType} must not contain emojis: ${toDisplayPath(filePath)}:${i + 1}`);
+    }
+  }
+}
+
+function lintWordCount(content, filePath, docType, maxWords, errors) {
+  const body = stripFrontmatter(content);
+  const wordCount = countWords(body);
+  if (wordCount > maxWords) {
+    errors.push(`${docType} exceeds maximum word count of ${maxWords} (${wordCount} words): ${toDisplayPath(filePath)}`);
+  }
+}
+
+function lintResearchIntroductionQuestion(content, filePath, errors) {
+  const lines = content.split(/\r?\n/);
+  const ignoredLines = findIgnoredMarkdownLines(lines);
+  const introStart = findHeadingLine(lines, ignoredLines, '## Introduction');
+  if (introStart === -1) return; // Already caught by lintRequiredSections
+
+  let introEnd = lines.length;
+  for (let i = introStart + 1; i < lines.length; i++) {
+    if (!ignoredLines[i] && /^## /.test(lines[i].trim())) {
+      introEnd = i;
+      break;
+    }
+  }
+
+  let hasQuestion = false;
+  for (let i = introStart + 1; i < introEnd; i++) {
+    if (!ignoredLines[i] && lines[i].trim().startsWith('Question:')) {
+      hasQuestion = true;
+      break;
+    }
+  }
+
+  if (!hasQuestion) {
+    errors.push(`Research ## Introduction must contain a "Question:" line: ${toDisplayPath(filePath)}`);
+  }
+}
+
 const XDR_REQUIRED_SECTIONS = ['## Context and Problem Statement', '## Decision Outcome'];
 const ARTICLE_REQUIRED_SECTIONS = ['## Overview', '## Content', '## References'];
 const RESEARCH_REQUIRED_SECTIONS = ['## Abstract', '## Introduction', '## Methods', '## Results', '## Discussion', '## Conclusion', '## References'];
@@ -882,10 +957,33 @@ function shouldValidateResourceLink(rawTarget) {
     || IMAGE_EXTENSIONS.has(extension);
 }
 
+function extractDescriptionText(block) {
+  const lines = block.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^description:\s*(.*)$/);
+    if (!m) continue;
+    const inlineValue = m[1].trim();
+    if (inlineValue && inlineValue !== '>' && inlineValue !== '|') {
+      return inlineValue;
+    }
+    // Block scalar: collect following indented lines
+    const bodyLines = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (lines[j] === '' || /^\s+/.test(lines[j])) {
+        bodyLines.push(lines[j].trim());
+      } else {
+        break;
+      }
+    }
+    return bodyLines.join(' ').trim() || null;
+  }
+  return 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, topLevelKeys: [] };
+    return { present: false, name: null, description: false, descriptionText: null, validFrom: undefined, appliedTo: undefined, topLevelKeys: [] };
   }
   const block = match[1];
   const nameMatch = block.match(/^name:\s*(.+)$/m);
@@ -896,10 +994,12 @@ function extractFrontmatter(content) {
     const keyMatch = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*/);
     if (keyMatch) topLevelKeys.push(keyMatch[1]);
   }
+  const descriptionText = extractDescriptionText(block);
   return {
     present: true,
     name: nameMatch ? nameMatch[1].trim() || null : null,
     description: /^description:\s*\S/m.test(block),
+    descriptionText,
     validFrom: validFromMatch ? validFromMatch[1].trim() : undefined,
     appliedTo: appliedToMatch ? appliedToMatch[1].trim() : undefined,
     topLevelKeys,

package/lib/lint.test.js

@@ -919,4 +919,401 @@ test('falls back to .xdrs subdirectory when given path has no index.md', () => {
 
   expect(result.errors).toHaveLength(0);
   expect(result.xdrsRoot).toBe(path.join(workspaceRoot, '.xdrs'));
-});
+});
+
+// ─── Emoji checks ─────────────────────────────────────────────────────────────
+
+test('reports emoji in XDR document body', () => {
+  const workspaceRoot = createWorkspace('xdr-emoji-body', {
+    '.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('This is great \uD83C\uDF89'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('XDR must not contain emojis');
+});
+
+test('does not report emoji inside a code block in XDR documents', () => {
+  const workspaceRoot = createWorkspace('xdr-emoji-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('```\necho "hello \uD83C\uDF89"\n```'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('must not contain emojis');
+});
+
+test('reports emoji in SKILL.md', () => {
+  const workspaceRoot = createWorkspace('skill-emoji', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Step 1: do something \u2705'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill must not contain emojis');
+});
+
+test('reports emoji in article document', () => {
+  const workspaceRoot = createWorkspace('article-emoji', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': articleDocument('Nice overview \uD83D\uDE80'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Article must not contain emojis');
+});
+
+test('reports emoji in research document', () => {
+  const workspaceRoot = createWorkspace('research-emoji', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument('Some finding \uD83D\uDD2C', 'Question: Is this right?'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Research must not contain emojis');
+});
+
+test('reports emoji in plan document', () => {
+  const workspaceRoot = createWorkspace('plan-emoji', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-myplan](principles/plans/001-myplan.md) - My plan'
+    ]),
+    '.xdrs/_local/adrs/principles/plans/001-myplan.md': planDocument('Great plan \uD83C\uDFAF'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Plan must not contain emojis');
+});
+
+// ─── Name / description length ────────────────────────────────────────────────
+
+test('reports XDR frontmatter name exceeding 64 characters', () => {
+  const longName = '_local-adr-001-' + 'a'.repeat(50);
+  const workspaceRoot = createWorkspace('xdr-name-too-long', {
+    '.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': [
+      '---',
+      `name: ${longName}`,
+      'description: Test XDR document',
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('XDR frontmatter name must be 64 characters or fewer');
+});
+
+test('reports XDR frontmatter description exceeding 1024 characters', () => {
+  const workspaceRoot = createWorkspace('xdr-description-too-long', {
+    '.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': [
+      '---',
+      'name: _local-adr-001-main',
+      `description: ${'x'.repeat(1025)}`,
+      '---',
+      '',
+      '# _local-adr-001: Main decision',
+      '',
+      '## Context and Problem Statement',
+      '',
+      'Test body.',
+      '',
+      '## Decision Outcome',
+      '',
+      'Test decision outcome.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('XDR frontmatter description must be 1024 characters or fewer');
+});
+
+test('reports SKILL.md frontmatter name exceeding 64 characters', () => {
+  const longName = '001-check-links-' + 'a'.repeat(50);
+  const workspaceRoot = createWorkspace('skill-name-too-long', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+      '---',
+      `name: ${longName}`,
+      'description: Test skill document',
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Overview.',
+      '',
+      '## Instructions',
+      '',
+      'Instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('SKILL.md frontmatter name must be 64 characters or fewer');
+});
+
+test('reports SKILL.md frontmatter description exceeding 1024 characters', () => {
+  const workspaceRoot = createWorkspace('skill-description-too-long', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': [
+      '---',
+      'name: 001-check-links',
+      `description: ${'x'.repeat(1025)}`,
+      '---',
+      '',
+      '## Overview',
+      '',
+      'Overview.',
+      '',
+      '## Instructions',
+      '',
+      'Instructions.',
+      ''
+    ].join('\n'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('SKILL.md frontmatter description must be 1024 characters or fewer');
+});
+
+// ─── Word count ───────────────────────────────────────────────────────────────
+
+test('reports XDR document exceeding 2600 word limit', () => {
+  const longBody = ('word '.repeat(2601)).trimEnd();
+  const workspaceRoot = createWorkspace('xdr-too-many-words', {
+    '.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(longBody),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('XDR exceeds maximum word count of 2600');
+});
+
+test('reports article exceeding 5000 word limit', () => {
+  const longBody = ('word '.repeat(5001)).trimEnd();
+  const workspaceRoot = createWorkspace('article-too-many-words', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-guide](principles/articles/001-guide.md) - Guide'
+    ]),
+    '.xdrs/_local/adrs/principles/articles/001-guide.md': articleDocument(longBody),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Article exceeds maximum word count of 5000');
+});
+
+test('reports research exceeding 5000 word limit', () => {
+  const longBody = ('word '.repeat(5001)).trimEnd();
+  const workspaceRoot = createWorkspace('research-too-many-words', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument(longBody, 'Question: What is the answer?'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Research exceeds maximum word count of 5000');
+});
+
+test('reports SKILL.md exceeding 6500 word limit', () => {
+  const longBody = ('word '.repeat(6501)).trimEnd();
+  const workspaceRoot = createWorkspace('skill-too-many-words', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument(longBody),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Skill exceeds maximum word count of 6500');
+});
+
+// ─── Files outside .assets in skill package root ────────────────────────────
+
+test('passes when extra files exist at skill package root', () => {
+  const workspaceRoot = createWorkspace('extra-skill-file', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-check-links](principles/skills/001-check-links/SKILL.md) - Check links'
+    ]),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/SKILL.md': skillDocument('Body.'),
+    '.xdrs/_local/adrs/principles/skills/001-check-links/extra.md': 'Allowed extra file',
+    '.xdrs/_local/adrs/principles/skills/001-check-links/schema.json': '{"type":"object"}',
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('extra.md');
+  expect(result.errors.join('\n')).not.toContain('schema.json');
+});
+
+// ─── Research Question: in Introduction ──────────────────────────────────────
+
+test('reports research ## Introduction missing Question: line', () => {
+  const workspaceRoot = createWorkspace('research-no-question', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument('No question here.', null),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).toContain('Research ## Introduction must contain a "Question:" line');
+});
+
+test('passes when research ## Introduction contains Question: line', () => {
+  const workspaceRoot = createWorkspace('research-with-question', {
+    '.xdrs/index.md': rootIndex(),
+    '.xdrs/_local/adrs/index.md': localAdrIndex([
+      '- [001-study](principles/researches/001-study.md) - Study'
+    ]),
+    '.xdrs/_local/adrs/principles/researches/001-study.md': researchDocument('Some context.', 'Question: Is this the right approach?'),
+  });
+
+  const result = lintWorkspace(workspaceRoot);
+
+  expect(result.errors.join('\n')).not.toContain('Research ## Introduction must contain');
+});
+
+// ─── New helpers ──────────────────────────────────────────────────────────────
+
+function articleDocument(body) {
+  return [
+    '# _local-article-001: Guide',
+    '',
+    '## Overview',
+    '',
+    'Overview text.',
+    '',
+    '## Content',
+    '',
+    body,
+    '',
+    '## References',
+    '',
+    '- No references.',
+    ''
+  ].join('\n');
+}
+
+function researchDocument(introBody, questionLine) {
+  const introSection = questionLine
+    ? `${introBody}\n\n${questionLine}`
+    : introBody;
+  return [
+    '# _local-research-001: Study',
+    '',
+    '## Abstract',
+    '',
+    'Single paragraph abstract.',
+    '',
+    '## Introduction',
+    '',
+    introSection,
+    '',
+    '## Methods',
+    '',
+    'Study methods.',
+    '',
+    '## Results',
+    '',
+    'Study results.',
+    '',
+    '## Discussion',
+    '',
+    'Discussion.',
+    '',
+    '## Conclusion',
+    '',
+    'Conclusion.',
+    '',
+    '## References',
+    '',
+    '- No references.',
+    ''
+  ].join('\n');
+}
+
+function planDocument(body) {
+  return [
+    '# _local-plan-001: My plan',
+    '',
+    '## Executive Summary',
+    '',
+    'Summary.',
+    '',
+    '## Context and Problem Statement',
+    '',
+    body,
+    '',
+    '## Proposed Solution',
+    '',
+    'We will fix it.',
+    '',
+    'Expected end date: 2026-12-31',
+    ''
+  ].join('\n');
+}

package/package.json

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