Document pull_request state transitions in schema

[Copilot]

The converted_to_draft and ready_for_review pull request event types represent state transitions, not states. Users may inadvertently listen for both without understanding their opposite nature.

Changes

• Enhanced pull_request.types description to clarify these are state transitions rather than states
• Added $comment documenting the logical conflict between the two event types
• No validation behavior changes—both events remain valid to use together

"types": {
  "type": "array",
  "description": "Pull request event types to trigger on. Note: 'converted_to_draft' and 'ready_for_review' represent state transitions (events) rather than states. While technically valid to listen for both, consider if you need to handle both transitions or just one.",
  "$comment": "converted_to_draft and ready_for_review are logically opposite state transitions. Using both may indicate unclear intent."
}

This follows existing schema patterns for documenting mutually exclusive options (see branches/branches-ignore).

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/user
  • Triggering command: /usr/bin/gh gh api user --jq .login eutil.test GO111MODULE ortcfg.link GOINSECURE GOMOD GOMODCACHE 8_NJKpgYiLwRNKaQea/mARpsQ65GVtlHgf8IblM/b0xRmyctrefs/tags/v0.20.10 env it/ref/tags/v5 GO111MODULE g_.a GOINSECURE GOMOD GOMODCACHE ache/go/1.25.0/x64/pkg/tool/linu--prefix=/net/ipv6/conf/veth981939b (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login (http block)
  • Triggering command: /usr/bin/gh gh api user --jq .login est" GO111MODULE 504e4a92b5432bc3a4dacce25ca693d828b/log.json GOINSECURE GOMOD GOMODCACHE go env oad-artifact.git GO111MODULE 0439227/b361/vet.cfg GOINSECURE GOMOD GOMODCACHE go (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add documentation for draft/ready_for_review state conflict</issue_title>
<issue_description>## Objective

Document the logical conflict between converted_to_draft and ready_for_review pull request event types to help users understand state transitions vs states.

Context

Pull request events include both converted_to_draft and ready_for_review event types. While technically valid to listen for both (they represent state transitions), it may indicate unclear user intent since a PR cannot be both draft and ready simultaneously.

Approach

Add a $comment and enhance the description in the schema to clarify that these are state transitions, not states.

Files to Modify

• Update: pkg/parser/schemas/main_workflow_schema.json (pull_request.types section)

Implementation

Enhance the types description to include guidance about state transitions:

"types": {
  "type": "array",
  "description": "Pull request event types to trigger on. Note: 'converted_to_draft' and 'ready_for_review' represent state transitions (events) rather than states. While technically valid to listen for both, consider if you need to handle both transitions or just one.",
  "$comment": "converted_to_draft and ready_for_review are logically opposite state transitions. Using both may indicate unclear intent.",
  "items": {
    "type": "string",
    "enum": [
      "assigned",
      "auto_merge_disabled",
      "auto_merge_enabled",
      "closed",
      "converted_to_draft",
      "demilestoned",
      "dequeued",
      "edited",
      "enqueued",
      "labeled",
      "locked",
      "milestoned",
      "opened",
      "ready_for_review",
      "reopened",
      "review_request_removed",
      "review_requested",
      "synchronize",
      "unassigned",
      "unlabeled",
      "unlocked"
    ]
  }
}

Acceptance Criteria

• Enhanced description added to pull_request.types field
• $comment added explaining the logical conflict
• Schema is valid JSON (run make build to verify)
• Documentation is clear and helpful for users
• No change to validation behavior (this is documentation only)

Testing

# Rebuild binary with updated schema
make build

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

# Existing behavior unchanged
echo '---
on:
  pull_request:
    types: [converted_to_draft, ready_for_review]
---
Test' > /tmp/test-draft-ready.md

./gh-aw compile /tmp/test-draft-ready.md  # Should succeed (no validation added)

Notes

This is a documentation-only change to help users understand the semantics. No runtime validation is added. Users may legitimately want to trigger on both state transitions (e.g., to track all PR status changes).
Related to #5804

AI generated by Plan Command for discussion #5799

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add documentation for draft/ready_for_review state conflict #5808

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.