openspecui 0.0.0

package/references/openspec/src/core/update.ts

@@ -0,0 +1,129 @@
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { OPENSPEC_DIR_NAME } from './config.js';
+import { ToolRegistry } from './configurators/registry.js';
+import { SlashCommandRegistry } from './configurators/slash/registry.js';
+import { agentsTemplate } from './templates/agents-template.js';
+
+export class UpdateCommand {
+  async execute(projectPath: string): Promise<void> {
+    const resolvedProjectPath = path.resolve(projectPath);
+    const openspecDirName = OPENSPEC_DIR_NAME;
+    const openspecPath = path.join(resolvedProjectPath, openspecDirName);
+
+    // 1. Check openspec directory exists
+    if (!await FileSystemUtils.directoryExists(openspecPath)) {
+      throw new Error(`No OpenSpec directory found. Run 'openspec init' first.`);
+    }
+
+    // 2. Update AGENTS.md (full replacement)
+    const agentsPath = path.join(openspecPath, 'AGENTS.md');
+
+    await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
+
+    // 3. Update existing AI tool configuration files only
+    const configurators = ToolRegistry.getAll();
+    const slashConfigurators = SlashCommandRegistry.getAll();
+    const updatedFiles: string[] = [];
+    const createdFiles: string[] = [];
+    const failedFiles: string[] = [];
+    const updatedSlashFiles: string[] = [];
+    const failedSlashTools: string[] = [];
+
+    for (const configurator of configurators) {
+      const configFilePath = path.join(
+        resolvedProjectPath,
+        configurator.configFileName
+      );
+      const fileExists = await FileSystemUtils.fileExists(configFilePath);
+      const shouldConfigure =
+        fileExists || configurator.configFileName === 'AGENTS.md';
+
+      if (!shouldConfigure) {
+        continue;
+      }
+
+      try {
+        if (fileExists && !await FileSystemUtils.canWriteFile(configFilePath)) {
+          throw new Error(
+            `Insufficient permissions to modify ${configurator.configFileName}`
+          );
+        }
+
+        await configurator.configure(resolvedProjectPath, openspecPath);
+        updatedFiles.push(configurator.configFileName);
+
+        if (!fileExists) {
+          createdFiles.push(configurator.configFileName);
+        }
+      } catch (error) {
+        failedFiles.push(configurator.configFileName);
+        console.error(
+          `Failed to update ${configurator.configFileName}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+    }
+
+    for (const slashConfigurator of slashConfigurators) {
+      if (!slashConfigurator.isAvailable) {
+        continue;
+      }
+
+      try {
+        const updated = await slashConfigurator.updateExisting(
+          resolvedProjectPath,
+          openspecPath
+        );
+        updatedSlashFiles.push(...updated);
+      } catch (error) {
+        failedSlashTools.push(slashConfigurator.toolId);
+        console.error(
+          `Failed to update slash commands for ${slashConfigurator.toolId}: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+      }
+    }
+
+    const summaryParts: string[] = [];
+    const instructionFiles: string[] = ['openspec/AGENTS.md'];
+
+    if (updatedFiles.includes('AGENTS.md')) {
+      instructionFiles.push(
+        createdFiles.includes('AGENTS.md') ? 'AGENTS.md (created)' : 'AGENTS.md'
+      );
+    }
+
+    summaryParts.push(
+      `Updated OpenSpec instructions (${instructionFiles.join(', ')})`
+    );
+
+    const aiToolFiles = updatedFiles.filter((file) => file !== 'AGENTS.md');
+    if (aiToolFiles.length > 0) {
+      summaryParts.push(`Updated AI tool files: ${aiToolFiles.join(', ')}`);
+    }
+
+    if (updatedSlashFiles.length > 0) {
+      // Normalize to forward slashes for cross-platform log consistency
+      const normalized = updatedSlashFiles.map((p) => p.replace(/\\/g, '/'));
+      summaryParts.push(`Updated slash commands: ${normalized.join(', ')}`);
+    }
+
+    const failedItems = [
+      ...failedFiles,
+      ...failedSlashTools.map(
+        (toolId) => `slash command refresh (${toolId})`
+      ),
+    ];
+
+    if (failedItems.length > 0) {
+      summaryParts.push(`Failed to update: ${failedItems.join(', ')}`);
+    }
+
+    console.log(summaryParts.join(' | '));
+
+    // No additional notes
+  }
+}

package/references/openspec/src/core/validation/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Validation threshold constants
+ */
+
+// Minimum character lengths
+export const MIN_WHY_SECTION_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
+
+// Maximum character/item limits
+export const MAX_WHY_SECTION_LENGTH = 1000;
+export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export const MAX_DELTAS_PER_CHANGE = 10;
+
+// Validation messages
+export const VALIDATION_MESSAGES = {
+  // Required content
+  SCENARIO_EMPTY: 'Scenario text cannot be empty',
+  REQUIREMENT_EMPTY: 'Requirement text cannot be empty',
+  REQUIREMENT_NO_SHALL: 'Requirement must contain SHALL or MUST keyword',
+  REQUIREMENT_NO_SCENARIOS: 'Requirement must have at least one scenario',
+  SPEC_NAME_EMPTY: 'Spec name cannot be empty',
+  SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
+  SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
+  CHANGE_NAME_EMPTY: 'Change name cannot be empty',
+  CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
+  CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
+  CHANGE_NO_DELTAS: 'Change must have at least one delta',
+  CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
+  DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
+  DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
+  
+  // Warnings
+  PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+  REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
+  DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
+  DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
+  
+  // Guidance snippets (appended to primary messages for remediation)
+  GUIDE_NO_DELTAS:
+    'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "openspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+  GUIDE_MISSING_SPEC_SECTIONS:
+    'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
+  GUIDE_MISSING_CHANGE_SECTIONS:
+    'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
+  GUIDE_SCENARIO_FORMAT:
+    'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',
+} as const;

package/references/openspec/src/core/validation/types.ts

@@ -0,0 +1,19 @@
+export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
+
+export interface ValidationIssue {
+  level: ValidationLevel;
+  path: string;
+  message: string;
+  line?: number;
+  column?: number;
+}
+
+export interface ValidationReport {
+  valid: boolean;
+  issues: ValidationIssue[];
+  summary: {
+    errors: number;
+    warnings: number;
+    info: number;
+  };
+}

package/references/openspec/src/core/validation/validator.ts

@@ -0,0 +1,448 @@
+import { z, ZodError } from 'zod';
+import { readFileSync, promises as fs } from 'fs';
+import path from 'path';
+import { SpecSchema, ChangeSchema, Spec, Change } from '../schemas/index.js';
+import { MarkdownParser } from '../parsers/markdown-parser.js';
+import { ChangeParser } from '../parsers/change-parser.js';
+import { ValidationReport, ValidationIssue, ValidationLevel } from './types.js';
+import { 
+  MIN_PURPOSE_LENGTH,
+  MAX_REQUIREMENT_TEXT_LENGTH,
+  VALIDATION_MESSAGES 
+} from './constants.js';
+import { parseDeltaSpec, normalizeRequirementName } from '../parsers/requirement-blocks.js';
+
+export class Validator {
+  private strictMode: boolean;
+
+  constructor(strictMode: boolean = false) {
+    this.strictMode = strictMode;
+  }
+
+  async validateSpec(filePath: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    const specName = this.extractNameFromPath(filePath);
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const parser = new MarkdownParser(content);
+      
+      const spec = parser.parseSpec(specName);
+      
+      const result = SpecSchema.safeParse(spec);
+      
+      if (!result.success) {
+        issues.push(...this.convertZodErrors(result.error));
+      }
+      
+      issues.push(...this.applySpecRules(spec, content));
+      
+    } catch (error) {
+      const baseMessage = error instanceof Error ? error.message : 'Unknown error';
+      const enriched = this.enrichTopLevelError(specName, baseMessage);
+      issues.push({
+        level: 'ERROR',
+        path: 'file',
+        message: enriched,
+      });
+    }
+    
+    return this.createReport(issues);
+  }
+
+  /**
+   * Validate spec content from a string (used for pre-write validation of rebuilt specs)
+   */
+  async validateSpecContent(specName: string, content: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    try {
+      const parser = new MarkdownParser(content);
+      const spec = parser.parseSpec(specName);
+      const result = SpecSchema.safeParse(spec);
+      if (!result.success) {
+        issues.push(...this.convertZodErrors(result.error));
+      }
+      issues.push(...this.applySpecRules(spec, content));
+    } catch (error) {
+      const baseMessage = error instanceof Error ? error.message : 'Unknown error';
+      const enriched = this.enrichTopLevelError(specName, baseMessage);
+      issues.push({ level: 'ERROR', path: 'file', message: enriched });
+    }
+    return this.createReport(issues);
+  }
+
+  async validateChange(filePath: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    const changeName = this.extractNameFromPath(filePath);
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const changeDir = path.dirname(filePath);
+      const parser = new ChangeParser(content, changeDir);
+      
+      const change = await parser.parseChangeWithDeltas(changeName);
+      
+      const result = ChangeSchema.safeParse(change);
+      
+      if (!result.success) {
+        issues.push(...this.convertZodErrors(result.error));
+      }
+      
+      issues.push(...this.applyChangeRules(change, content));
+      
+    } catch (error) {
+      const baseMessage = error instanceof Error ? error.message : 'Unknown error';
+      const enriched = this.enrichTopLevelError(changeName, baseMessage);
+      issues.push({
+        level: 'ERROR',
+        path: 'file',
+        message: enriched,
+      });
+    }
+    
+    return this.createReport(issues);
+  }
+
+  /**
+   * Validate delta-formatted spec files under a change directory.
+   * Enforces:
+   * - At least one delta across all files
+   * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
+   * - REMOVED: names only; no scenario/description required
+   * - RENAMED: pairs well-formed
+   * - No duplicates within sections; no cross-section conflicts per spec
+   */
+  async validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport> {
+    const issues: ValidationIssue[] = [];
+    const specsDir = path.join(changeDir, 'specs');
+    let totalDeltas = 0;
+    const missingHeaderSpecs: string[] = [];
+    const emptySectionSpecs: Array<{ path: string; sections: string[] }> = [];
+
+    try {
+      const entries = await fs.readdir(specsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const specName = entry.name;
+        const specFile = path.join(specsDir, specName, 'spec.md');
+        let content: string | undefined;
+        try {
+          content = await fs.readFile(specFile, 'utf-8');
+        } catch {
+          continue;
+        }
+
+        const plan = parseDeltaSpec(content);
+        const entryPath = `${specName}/spec.md`;
+        const sectionNames: string[] = [];
+        if (plan.sectionPresence.added) sectionNames.push('## ADDED Requirements');
+        if (plan.sectionPresence.modified) sectionNames.push('## MODIFIED Requirements');
+        if (plan.sectionPresence.removed) sectionNames.push('## REMOVED Requirements');
+        if (plan.sectionPresence.renamed) sectionNames.push('## RENAMED Requirements');
+        const hasSections = sectionNames.length > 0;
+        const hasEntries = plan.added.length + plan.modified.length + plan.removed.length + plan.renamed.length > 0;
+        if (!hasEntries) {
+          if (hasSections) emptySectionSpecs.push({ path: entryPath, sections: sectionNames });
+          else missingHeaderSpecs.push(entryPath);
+        }
+
+        const addedNames = new Set<string>();
+        const modifiedNames = new Set<string>();
+        const removedNames = new Set<string>();
+        const renamedFrom = new Set<string>();
+        const renamedTo = new Set<string>();
+
+        // Validate ADDED
+        for (const block of plan.added) {
+          const key = normalizeRequirementName(block.name);
+          totalDeltas++;
+          if (addedNames.has(key)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate requirement in ADDED: "${block.name}"` });
+          } else {
+            addedNames.add(key);
+          }
+          const requirementText = this.extractRequirementText(block.raw);
+          if (!requirementText) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" is missing requirement text` });
+          } else if (!this.containsShallOrMust(requirementText)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must contain SHALL or MUST` });
+          }
+          const scenarioCount = this.countScenarios(block.raw);
+          if (scenarioCount < 1) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `ADDED "${block.name}" must include at least one scenario` });
+          }
+        }
+
+        // Validate MODIFIED
+        for (const block of plan.modified) {
+          const key = normalizeRequirementName(block.name);
+          totalDeltas++;
+          if (modifiedNames.has(key)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate requirement in MODIFIED: "${block.name}"` });
+          } else {
+            modifiedNames.add(key);
+          }
+          const requirementText = this.extractRequirementText(block.raw);
+          if (!requirementText) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" is missing requirement text` });
+          } else if (!this.containsShallOrMust(requirementText)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must contain SHALL or MUST` });
+          }
+          const scenarioCount = this.countScenarios(block.raw);
+          if (scenarioCount < 1) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED "${block.name}" must include at least one scenario` });
+          }
+        }
+
+        // Validate REMOVED (names only)
+        for (const name of plan.removed) {
+          const key = normalizeRequirementName(name);
+          totalDeltas++;
+          if (removedNames.has(key)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate requirement in REMOVED: "${name}"` });
+          } else {
+            removedNames.add(key);
+          }
+        }
+
+        // Validate RENAMED pairs
+        for (const { from, to } of plan.renamed) {
+          const fromKey = normalizeRequirementName(from);
+          const toKey = normalizeRequirementName(to);
+          totalDeltas++;
+          if (renamedFrom.has(fromKey)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate FROM in RENAMED: "${from}"` });
+          } else {
+            renamedFrom.add(fromKey);
+          }
+          if (renamedTo.has(toKey)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Duplicate TO in RENAMED: "${to}"` });
+          } else {
+            renamedTo.add(toKey);
+          }
+        }
+
+        // Cross-section conflicts (within the same spec file)
+        for (const n of modifiedNames) {
+          if (removedNames.has(n)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Requirement present in both MODIFIED and REMOVED: "${n}"` });
+          }
+          if (addedNames.has(n)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Requirement present in both MODIFIED and ADDED: "${n}"` });
+          }
+        }
+        for (const n of addedNames) {
+          if (removedNames.has(n)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `Requirement present in both ADDED and REMOVED: "${n}"` });
+          }
+        }
+        for (const { from, to } of plan.renamed) {
+          const fromKey = normalizeRequirementName(from);
+          const toKey = normalizeRequirementName(to);
+          if (modifiedNames.has(fromKey)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `MODIFIED references old name from RENAMED. Use new header for "${to}"` });
+          }
+          if (addedNames.has(toKey)) {
+            issues.push({ level: 'ERROR', path: entryPath, message: `RENAMED TO collides with ADDED for "${to}"` });
+          }
+        }
+      }
+    } catch {
+      // If no specs dir, treat as no deltas
+    }
+
+    for (const { path: specPath, sections } of emptySectionSpecs) {
+      issues.push({
+        level: 'ERROR',
+        path: specPath,
+        message: `Delta sections ${this.formatSectionList(sections)} were found, but no requirement entries parsed. Ensure each section includes at least one "### Requirement:" block (REMOVED may use bullet list syntax).`,
+      });
+    }
+    for (const path of missingHeaderSpecs) {
+      issues.push({
+        level: 'ERROR',
+        path,
+        message: 'No delta sections found. Add headers such as "## ADDED Requirements" or move non-delta notes outside specs/.',
+      });
+    }
+
+    if (totalDeltas === 0) {
+      issues.push({ level: 'ERROR', path: 'file', message: this.enrichTopLevelError('change', VALIDATION_MESSAGES.CHANGE_NO_DELTAS) });
+    }
+
+    return this.createReport(issues);
+  }
+
+  private convertZodErrors(error: ZodError): ValidationIssue[] {
+    return error.issues.map(err => {
+      let message = err.message;
+      if (message === VALIDATION_MESSAGES.CHANGE_NO_DELTAS) {
+        message = `${message}. ${VALIDATION_MESSAGES.GUIDE_NO_DELTAS}`;
+      }
+      return {
+        level: 'ERROR' as ValidationLevel,
+        path: err.path.join('.'),
+        message,
+      };
+    });
+  }
+
+  private applySpecRules(spec: Spec, content: string): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    
+    if (spec.overview.length < MIN_PURPOSE_LENGTH) {
+      issues.push({
+        level: 'WARNING',
+        path: 'overview',
+        message: VALIDATION_MESSAGES.PURPOSE_TOO_BRIEF,
+      });
+    }
+    
+    spec.requirements.forEach((req, index) => {
+      if (req.text.length > MAX_REQUIREMENT_TEXT_LENGTH) {
+        issues.push({
+          level: 'INFO',
+          path: `requirements[${index}]`,
+          message: VALIDATION_MESSAGES.REQUIREMENT_TOO_LONG,
+        });
+      }
+      
+      if (req.scenarios.length === 0) {
+        issues.push({
+          level: 'WARNING',
+          path: `requirements[${index}].scenarios`,
+          message: `${VALIDATION_MESSAGES.REQUIREMENT_NO_SCENARIOS}. ${VALIDATION_MESSAGES.GUIDE_SCENARIO_FORMAT}`,
+        });
+      }
+    });
+    
+    return issues;
+  }
+
+  private applyChangeRules(change: Change, content: string): ValidationIssue[] {
+    const issues: ValidationIssue[] = [];
+    
+    const MIN_DELTA_DESCRIPTION_LENGTH = 10;
+    
+    change.deltas.forEach((delta, index) => {
+      if (!delta.description || delta.description.length < MIN_DELTA_DESCRIPTION_LENGTH) {
+        issues.push({
+          level: 'WARNING',
+          path: `deltas[${index}].description`,
+          message: VALIDATION_MESSAGES.DELTA_DESCRIPTION_TOO_BRIEF,
+        });
+      }
+      
+      if ((delta.operation === 'ADDED' || delta.operation === 'MODIFIED') && 
+          (!delta.requirements || delta.requirements.length === 0)) {
+        issues.push({
+          level: 'WARNING',
+          path: `deltas[${index}].requirements`,
+          message: `${delta.operation} ${VALIDATION_MESSAGES.DELTA_MISSING_REQUIREMENTS}`,
+        });
+      }
+    });
+    
+    return issues;
+  }
+
+  private enrichTopLevelError(itemId: string, baseMessage: string): string {
+    const msg = baseMessage.trim();
+    if (msg === VALIDATION_MESSAGES.CHANGE_NO_DELTAS) {
+      return `${msg}. ${VALIDATION_MESSAGES.GUIDE_NO_DELTAS}`;
+    }
+    if (msg.includes('Spec must have a Purpose section') || msg.includes('Spec must have a Requirements section')) {
+      return `${msg}. ${VALIDATION_MESSAGES.GUIDE_MISSING_SPEC_SECTIONS}`;
+    }
+    if (msg.includes('Change must have a Why section') || msg.includes('Change must have a What Changes section')) {
+      return `${msg}. ${VALIDATION_MESSAGES.GUIDE_MISSING_CHANGE_SECTIONS}`;
+    }
+    return msg;
+  }
+
+  private extractNameFromPath(filePath: string): string {
+    const normalizedPath = filePath.replaceAll('\\', '/');
+    const parts = normalizedPath.split('/');
+    
+    // Look for the directory name after 'specs' or 'changes'
+    for (let i = parts.length - 1; i >= 0; i--) {
+      if (parts[i] === 'specs' || parts[i] === 'changes') {
+        if (i < parts.length - 1) {
+          return parts[i + 1];
+        }
+      }
+    }
+    
+    // Fallback to filename without extension if not in expected structure
+    const fileName = parts[parts.length - 1] ?? '';
+    const dotIndex = fileName.lastIndexOf('.');
+    return dotIndex > 0 ? fileName.slice(0, dotIndex) : fileName;
+  }
+
+  private createReport(issues: ValidationIssue[]): ValidationReport {
+    const errors = issues.filter(i => i.level === 'ERROR').length;
+    const warnings = issues.filter(i => i.level === 'WARNING').length;
+    const info = issues.filter(i => i.level === 'INFO').length;
+    
+    const valid = this.strictMode 
+      ? errors === 0 && warnings === 0
+      : errors === 0;
+    
+    return {
+      valid,
+      issues,
+      summary: {
+        errors,
+        warnings,
+        info,
+      },
+    };
+  }
+
+  isValid(report: ValidationReport): boolean {
+    return report.valid;
+  }
+
+  private extractRequirementText(blockRaw: string): string | undefined {
+    const lines = blockRaw.split('\n');
+    // Skip header line (index 0)
+    let i = 1;
+
+    // Find the first substantial text line, skipping metadata and blank lines
+    for (; i < lines.length; i++) {
+      const line = lines[i];
+
+      // Stop at scenario headers
+      if (/^####\s+/.test(line)) break;
+
+      const trimmed = line.trim();
+
+      // Skip blank lines
+      if (trimmed.length === 0) continue;
+
+      // Skip metadata lines (lines starting with ** like **ID**, **Priority**, etc.)
+      if (/^\*\*[^*]+\*\*:/.test(trimmed)) continue;
+
+      // Found first non-metadata, non-blank line - this is the requirement text
+      return trimmed;
+    }
+
+    // No requirement text found
+    return undefined;
+  }
+
+  private containsShallOrMust(text: string): boolean {
+    return /\b(SHALL|MUST)\b/.test(text);
+  }
+
+  private countScenarios(blockRaw: string): number {
+    const matches = blockRaw.match(/^####\s+/gm);
+    return matches ? matches.length : 0;
+  }
+
+  private formatSectionList(sections: string[]): string {
+    if (sections.length === 0) return '';
+    if (sections.length === 1) return sections[0];
+    const head = sections.slice(0, -1);
+    const last = sections[sections.length - 1];
+    return `${head.join(', ')} and ${last}`;
+  }
+}