# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json

# SPEC TIER 3 (nested under business-flow)
# Story filename format: <actor>--<story-name>.md
# Example: sales-manager--create-sales-order.md
# Heading must match story name (after --): # Create Sales Order
# Defines WHAT users accomplish (the requirement)

structure:
  - heading:
      # Validates: slug of text after "--" matches heading
      # trimPrefix removes "actor--" prefix, leaving story name
      # e.g., "sales-manager--create-sales-order" -> "create-sales-order" -> matches "# Create Sales Order"
      expr: 'slug(trimPrefix(filename, "^[a-z-]+--")) == slug(heading)'
    description: |
      User story defining a specific requirement within a business flow.
      The name of the story should start with the actor followed by `--` and the story name.
    children:
      - heading: "## User Story"
        description: |
          Define the user story in the format:
          As a [role], I want [goal], so that [benefit].

      # Diagram representing this story - REQUIRED
      - heading: "## Story Diagram"
        description: |
          Mermaid flowchart showing user interactions with screens.
          Focus on actors, UI screens, and business outcomes.
          Avoid technical details (APIs, databases, endpoints).
        code_blocks:
          - min: 1
            lang: mermaid

      # Scenario Patterns, including edge cases - REQUIRED
      - heading: "## Scenario Patterns"
        lists:
          - min: 1
            type: unordered
            min_items: 1

      # Test cases must be covered - REQUIRED
      - heading: "## Test Cases"
        lists:
          - min: 0
            type: unordered
            min_items: 1

      # Screens that implement this story - REQUIRED
      # Enables M:N relationship between stories and screens
      - heading: "## Screens"
        description: |
          Link to screen docs that implement this story's UI.
        lists:
          - min: 1
            type: unordered
            min_items: 1

      # Resolvers that implement this story's backend operations - OPTIONAL
      # Enables M:N relationship between stories and resolvers
      # Stories that only read data (browse, view, list) may not need resolvers
      - heading: "## Resolvers"
        description: |
          Link to resolver docs that implement this story's backend operations.
          Write "None" if this story does not require any resolvers.
        lists:
          - min: 0
            type: unordered
            min_items: 1

# Link validation
links:
  validate_internal: true
  validate_files: true

# Heading rules
heading_rules:
  no_skip_levels: true
  unique: true
  max_depth: 3