[plan] Document branches/paths mutual exclusivity in schema

[github-actions]

Objective

Add $comment documentation to schema for GitHub Actions mutual exclusivity rules: branches/branches-ignore and paths/paths-ignore cannot be used together.

Context

GitHub Actions requires that branches and branches-ignore (and similarly paths and paths-ignore) be mutually exclusive. The schema doesn't validate this constraint because JSON Schema lacks native mutual exclusivity support. Adding documentation via $comment helps developers and future maintainers understand the constraint.

Approach

Add $comment fields to the schema for both push and pull_request event filters to document the mutual exclusivity requirement.

Files to Modify

• Update: pkg/parser/schemas/main_workflow_schema.json
  • push event filters (branches, branches-ignore, paths, paths-ignore)
  • pull_request event filters (branches, branches-ignore, paths, paths-ignore)

Implementation

Add $comment to each filter field:

"branches": {
  "type": "array",
  "$comment": "Mutually exclusive with branches-ignore. GitHub Actions requires only one to be specified.",
  "description": "Branches to filter on",
  "items": { "type": "string" }
},
"branches-ignore": {
  "type": "array",
  "$comment": "Mutually exclusive with branches. GitHub Actions requires only one to be specified.",
  "description": "Branches to ignore",
  "items": { "type": "string" }
},
"paths": {
  "type": "array",
  "$comment": "Mutually exclusive with paths-ignore. GitHub Actions requires only one to be specified.",
  "description": "Paths to filter on",
  "items": { "type": "string" }
},
"paths-ignore": {
  "type": "array",
  "$comment": "Mutually exclusive with paths. GitHub Actions requires only one to be specified.",
  "description": "Paths to ignore",
  "items": { "type": "string" }
}

Locations to Update

1. push.branches / push.branches-ignore
2. push.paths / push.paths-ignore
3. pull_request.branches / pull_request.branches-ignore
4. pull_request.paths / pull_request.paths-ignore

Acceptance Criteria

• $comment added to all 8 filter fields (4 pairs × 2 events)
• Comments accurately describe the mutual exclusivity constraint
• Schema is valid JSON (run make build to verify)
• No change to existing validation behavior (this is documentation only)

Testing

# Rebuild binary with updated schema
make build

# Verify schema is still valid and embeds correctly
./gh-aw --version

# Existing behavior should be unchanged (invalid configs still compile)
echo '---
on:
  push:
    branches: [main]
    branches-ignore: [dev]
---
Test' > /tmp/test-both.md

./gh-aw compile /tmp/test-both.md  # Should still succeed (no runtime validation yet)

Notes

This is a documentation-only change. Runtime validation will be added in a separate issue (#5804 tracks the parent). The $comment field is part of JSON Schema spec and is ignored by validators but visible to developers reading the schema.
Related to #5804

AI generated by Plan Command for discussion #5799