Add a ci-status skill that reports a PR's real CI state

[Babissimo]

ClickUp: 2.1 Add a ci-status command that reports a PR's real CI state

Summary

gh pr checks and gh run watch have each reported green for a PR that was untested, conflicting, failed or unreviewed. On retina-server that happened in at least eight distinct ways, each kept as a separate memory note that worktree sessions never load. This adds a ci-status skill to core whose script reads the PR's runs directly and exits non-zero unless every gate passed:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/ci-status/scripts/ci_status.py" <pr> -R <owner>/<repo> [--watch]

Exit status: 0 green, 1 failed or will not run until someone acts, 2 the question was wrong, 3 not settled yet, 4 GitHub could not be read.

What it handles

• Runs for the PR's recorded head only, checked against its branch on GitHub and the local branch. While the head lags its branch nothing about the old head is judged. Unpushed local commits fail the reading.
• A conflicting PR, which gets no merge ref and so no CI, is reported as never going to run.
• Runs whose jobs all skipped (the run a title or body edit fires) are set aside. A newer run supersedes an older one job by job, so an edit's run cannot hide tests that failed, or that a timeout cut short, before it.
• Cancelled duplicates from a stack push are set aside, and lend no job that never queued. The latest attempt decides, and failed earlier attempts are still listed, because a rerun overwrites the run's conclusion.
• Job conclusions decide, not the run's, since a run can read completed while its jobs are still going.
• Other apps' checks and commit statuses count as gates.
• The Claude review counts only when a bot comment from the latest attempt of this head's review run links back to it and carries a fully ticked checklist. It reports when the PR edits the review workflow, or when the head carries an older copy of it than the default branch; either way the action skips itself without a word.
• --watch polls until the answer settles. It rides out outages, and after a few minutes it calls a wait that has not cleared final: no runs, no review run, or a head that has not moved.

The script's docstring records what it cannot see.

Testing

• 126 unit tests against a fake GitHub (tests/ci-status/), a few of them against real git for the local-branch comparison, run by a new ci-status tests workflow with SHA-pinned actions and a read-only token.
• Every branch was checked by deliberately breaking it: 85 such changes, and each one turns at least one test red.
• Run against live PRs:
  • retina-server #570, #573, #574, #577, #578, #579, #585 and #600, including a partial review, a rerun review, a PR that edits the review workflow and a conflicting PR.
  • claude-shared Python apps lock their dependencies with uv: ADR and setup-repo python-app stack #28 and Pin an app's CI to the uv its image builds with #29.
  • --commit on retina-server main commits, including one whose first attempt failed.
  • retina-server #613, #620 and #622 after the last fix. #622 has a cancelled duplicate beside its surviving run.

Not done

The last three review passes each found one misreport, all now fixed:

1. A test run cancelled by a timeout, followed by a body edit, read green.
2. The fix for that let a stack push's cancelled duplicate lend jobs that never queued, which turned a green PR red (retina-server #622).
3. The first fix for #622 also withheld tests that had queued, so a run cancelled by hand before its tests started, followed by a body edit, read green.

These points from the passes are left as they are:

• --commit on a main merge whose deploy job was cancelled in a burst, and so superseded by the next merge's run, reads failed. It judges the commit's runs, not whether the change shipped.
• Under --watch, a continue-on-error job that fails while its run is still going ends the watch with exit 1, even if the run then succeeds. The docstring says so.
• After GitHub's "Update branch" rebases the PR, a local copy of the branch from before it reads as diverged, and fails the reading, where main changed lines beside the PR's.
• A run's own allowed failure still gates while a job lent by an older, still-running run is unfinished. It needs two overlapping runs for one head plus continue-on-error.
• A job waiting on an environment approval reads as not settled (exit 3), not as needing action. No PR workflow in the org uses environments.
• A job list kept once its run reads completed is not read again should the same attempt later read in progress. The verdict still follows the run's own status.

Review notes

• The core plugin goes from 0.6.0 to 0.7.0 so installs pick the skill up.
• This repo's own review workflow does not set track_progress, so its runs post nothing to link. ci-status says so rather than calling such a PR reviewed.

🤖 Generated with Claude Code