@startuml cascading-rules
!theme plain
title Cascading Rules Configuration System

package "Repository Root" {
  file ".ai-rules.yml" as root_rules #LightBlue

  package "Docs/features/" {
    file ".ai-rules.yml" as features_rules #LightGreen

    package "FR_123/" {
      file ".ai-rules.yml" as feature_rules #LightYellow
      file "request.md" as request

      folder "discussions/" {
        file "feature.discussion.md" as discussion
      }
    }
  }
}

component "config.py" as config

request --> config: Process file
config --> feature_rules: 1. Load (nearest)
config --> features_rules: 2. Load (parent)
config --> root_rules: 3. Load (root)
config --> config: 4. Deep merge\n(nearest wins)

note right of config
  **Cascading Precedence:**
  1. Nearest directory rules
  2. Parent directory rules
  3. Root rules

  **Merge Strategy:**
  - Nested dictionaries are merged recursively
  - Arrays are replaced (not merged)
  - Nearest values win on conflicts
end note

note top of feature_rules
  **FR_123/.ai-rules.yml**

  rules:
    feature_request:
      outputs:
        feature_discussion:
          # Override specific output config
          instruction_append: |
            Additional context for FR_123
end note

note top of features_rules
  **Docs/features/.ai-rules.yml**

  file_associations:
    "request.md": "feature_request"
    "feature.discussion.md": "feature_discussion_update"

  rules:
    feature_request:
      outputs:
        feature_discussion:
          path: "Docs/features/{feature_id}/discussions/feature.discussion.md"
          output_type: "feature_discussion_writer"
end note

note top of root_rules
  **Root .ai-rules.yml**

  Global rules that apply
  to the entire repository
end note

@enduml