fix(pr-status): make --watch usable on a draft PR

[CybotTM]

Closes #228.

The issue's proposed fix was not enough, so this goes one step further. Adding ready to the --ignore-action allowlist (the issue's ask) would have made the flag accepted but the watch still useless: draft sat near the top of the NEXT ladder, so on a parked PR every poll answered ready and a red check, an open thread, or a conflict could never surface — with or without the flag. The ladder placement is the actual defect.

Change. draft now ranks below the real-work branches (conflicts, stale base, red checks, open threads) and above the review/merge advice, mirroring the queue-entry placement and its rationale. Checks actually running report wait — the watch holds and returns on the first real event. Everything else answers ready, now in ACTIONABLE: the watch returns handing over gh pr ready, and --ignore-action ready takes the name (on a settled draft that return is labelled SETTLED per the #165 semantics). This makes the back-to-draft-on-resume convention (#227) and --watch compatible; the reference now says so.

Review round caught a regression in the first cut, verified by the reviewer with a stubbed probe: gating ready on checks_settled left it unreachable for a draft with zero registered check contexts or a never-dispatched required context (workflows that skip drafts or trigger on ready_for_review, fork runs awaiting approval) — an endless wait of the very shape this PR removes. ready is now gated only on nothing actually running, and the why names undispatched required contexts when present.

investigate joins ACTIONABLE too — same family: it is the terminal check-branch-protection-manually verdict on settled checks, so a watch heartbeating on it idles into the timeout on a state that waiting cannot change. Observed on #226, where classic-protection CodeQL contexts kept mergeState=BLOCKED through an hour of waiting: lines. rules-unavailable stays a heartbeat on purpose: an API blip can heal on the next poll, and --max-wait bounds the true-failure case. Known trade-off (reviewer-flagged, accepted): right after the last check greens, one poll can catch mergeStateStatus still at BLOCKED and return investigate where the next poll would say merge — a cheap exit-and-re-arm, preferred over the unbounded heartbeat.

Tests. tests/test_pr_status_draft_watch.sh (stubbed gh, no network) pins the ladder — hold on running checks; return on a thread, a red check, on ready; ready reachable with zero registered checks and with a ghost required context; plain status names a red check instead of ready — and pins the action vocabulary: every action:"…" literal must be ACTIONABLE or a declared waiting heartbeat, and every ACTIONABLE entry must actually be emitted. Watched failing against the respective pre-fix states: 9 assertions red on the original script, 5 more on the version before the checks_settled correction. Full tests/*.sh suite green, shellcheck clean.

Assisted by claude-code:claude-fable-5 — Session

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[sonarqubecloud]

Quality Gate passed

Issues
20 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[CybotTM]

Self-review: 3320d13

The review this pull request demands is unsatisfiable (Copilot quota wall or repeated bot failures on this head). Per the documented fallback, the diff on this head was reviewed by the PR author; this comment is the on-the-record attestation the merge gate reads back. It stops matching on the next push.