name: Claude review controls comment

# Posts (and keeps in sync) a sticky "Claude review controls" comment on
# every PR. The comment lists the slash-commands reviewers can copy-paste into
# a reply to (re-)trigger a review. The comment is upserted by heading
# match so it never duplicates.
#
# This is the discoverability layer for the four review workflows:
# claude-review-help tells reviewers HOW to trigger them; the workflows
# themselves react to /review (all four) or /review <kind>.
#
# Re-runs whenever a PR is opened or transitions from draft to ready,
# AND whenever someone comments /review-help so the controls can be
# re-posted if they got buried in a long PR conversation.

on:
  pull_request:
    types: [opened, ready_for_review]
  issue_comment:
    types: [created]

permissions:
  contents: read
  pull-requests: write
  issues: write

concurrency:
  group: claude-review-help-${{ github.event.pull_request.number || github.event.issue.number }}
  cancel-in-progress: true

jobs:
  upsert-help-comment:
    if: |
      (github.event_name == 'pull_request' && github.event.pull_request.draft == false) ||
      (github.event_name == 'issue_comment' && github.event.issue.pull_request != null &&
       startsWith(github.event.comment.body, '/review-help'))
    runs-on: ubuntu-latest
    timeout-minutes: 2
    steps:
      - name: Resolve PR number
        id: ctx
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            PR=${{ github.event.pull_request.number }}
          else
            PR=${{ github.event.issue.number }}
          fi
          echo "pr_number=$PR" >> "$GITHUB_OUTPUT"

      - name: Upsert sticky controls comment
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          REPO: ${{ github.repository }}
          PR: ${{ steps.ctx.outputs.pr_number }}
        run: |
          BODY=$(cat <<'EOF'
          ## 🤖 Claude review controls

          This PR has Claude-powered reviews wired in. Comment one of these to (re-)trigger a review:

          | Command | Runs |
          | --- | --- |
          | `/review` | All four reviews (security · coverage · breaking · quality) |
          | `/review security` | Security only |
          | `/review coverage` | Test coverage only |
          | `/review breaking` | Breaking changes only |
          | `/review quality` | Code quality only |
          | `/review-help` | Re-post this controls comment (if it scrolled out of view) |

          Each review runs automatically when the PR opens or transitions from draft → ready. After pushing fixes, comment `/review` to refresh the verdicts.

          Verdicts post as separate sticky comments (one per review) and update in-place on re-run. 🟢 green / 🟡 yellow (advisory) / 🔴 red (blocks merge if the workflow's status check is required on the branch).

          <sub>Powered by Claude Max (subscription, not pay-per-token). Same system as root-platform; setup + override flow in root-platform’s `docs/runbooks/branch-protection-required-checks.md`.</sub>

          <!-- sticky:claude-review-controls -->
          EOF
          )

          # Sticky upsert: find an existing controls comment by heading match,
          # PATCH it if present, POST a new one if not. Heading is unique
          # across the four verdict stickies so there's no collision.
          EXISTING=$(gh api "repos/$REPO/issues/$PR/comments" --paginate \
            --jq '[.[] | select(.body | startswith("## 🤖 Claude review controls"))][0].id // empty')

          if [ -n "$EXISTING" ]; then
            gh api -X PATCH "repos/$REPO/issues/comments/$EXISTING" -f body="$BODY" >/dev/null
            echo "Updated existing controls comment $EXISTING"
          else
            gh api "repos/$REPO/issues/$PR/comments" -f body="$BODY" >/dev/null
            echo "Posted new controls comment on PR #$PR"
          fi