clud-bug 0.7.0-rc.2 → 0.7.0-rc.21

package/templates/workflow-py.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v12
+# clud-bug-template-version: v14
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -213,6 +213,19 @@ jobs:
           echo "::error::Set it: Settings → Secrets and variables → Actions → New repository secret."
           exit 1
 
+      # ── Design-critic (optional, opt-in) ─────────────────────────────────
+      # clud-bug can also review the *rendered* UI of your PR's preview deploy.
+      # The hosted clud-bug[bot] does this for you on Team installs (Browserless).
+      # To run it here on the Action reviewer instead — Claude drives a real
+      # browser on this runner, no paid render service — enable it in 3 steps:
+      #   1. clud-bug init --with-design   (installs the design kit + flips the
+      #      `design` block in .claude/skills/.clud-bug.json to enabled: true)
+      #   2. add a browser MCP to claude_args below, e.g.:
+      #        --mcp-config '{"mcpServers":{"playwright":{"command":"npx","args":["-y","@playwright/mcp@latest"]}}}'
+      #   3. append the browser tools to --allowedTools, e.g.:
+      #        ,mcp__playwright__browser_navigate,mcp__playwright__browser_take_screenshot
+      # Off by default. See the §3b design step in `clud-bug review-prompt`.
+      # ──────────────────────────────────────────────────────────────────────
       - uses: anthropics/claude-code-action@{{CCA_VERSION}}
         if: steps.guard.outputs.skip != 'true'
         env:
@@ -283,6 +296,40 @@ jobs:
 
           $CALIBRATION"
 
+      # Wave 5a (D.2.X) — see workflow.yml.tmpl for design notes.
+      - name: Post inline review threads
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          RESULT=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} post-inline-threads --stdin)
+          echo "::notice title=inline-threads::$RESULT"
+
+      # Wave 5b (D.2.6) — see workflow.yml.tmpl for design notes.
+      - name: Auto-resolve fixed threads
+        if: success() && github.event.action == 'synchronize'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # Optional fine-grained PAT (Pull requests: write). Present → the
+          # workflow resolves fixed threads like the hosted App. Absent (the
+          # default; an unset secret renders empty) → graceful "verified fixed"
+          # reply only, since the Actions GITHUB_TOKEN can't resolve threads.
+          CLUD_BUG_RESOLVE_PAT: ${{ secrets.CLUD_BUG_RESOLVE_PAT }}
+        run: |
+          set -euo pipefail
+          RESULT=$(npx --yes clud-bug@{{CLUD_BUG_VERSION}} resolve-threads)
+          echo "::notice title=auto-resolve::$RESULT"
+
       # v0.6.29 / Component 4 — see workflow.yml.tmpl for design notes.
       - name: Update skill-usage tracking
         if: success() && steps.clud-bug-review.outputs.structured_output != ''
@@ -366,9 +413,52 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.2
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.21
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].
           # See workflow.yml.tmpl for design notes.
           bot-login: 'github-actions[bot]'
+
+      # v0.7.0-rc.3 — SPEC §7.2.1 formal-review event poster.
+      # See workflow.yml.tmpl for full design rationale; this step
+      # bridges the canonical-ruleset `required_approving_review_count: 1`
+      # floor on the npm workflow path. Best-effort: never fails the
+      # workflow (continue-on-error). Drive-by exploit guard: external
+      # contributors NEVER get APPROVE.
+      - name: Formal review — APPROVE / REQUEST_CHANGES / COMMENT
+        if: always() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+          PR_AUTHOR_LOGIN: ${{ github.event.pull_request.user.login }}
+          PR_AUTHOR_ASSOCIATION: ${{ github.event.pull_request.author_association }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          set -uo pipefail
+          STRICT_MODE=false
+          if git show "origin/${BASE_REF}:.claude/skills/.clud-bug.json" > /tmp/base-manifest.json 2>/dev/null; then
+            if jq -e '.strictMode == true' /tmp/base-manifest.json > /dev/null 2>&1; then
+              STRICT_MODE=true
+            fi
+          fi
+          export STRICT_MODE
+          VERDICT=$(printf '%s\n' "$STRUCTURED" \
+            | npx --yes clud-bug@{{CLUD_BUG_VERSION}} select-review-event --stdin \
+            | tail -n1)
+          VERDICT="${VERDICT:-skip}"
+          echo "::notice title=Clud Bug 🐛::Formal review verdict: $VERDICT (strictMode=$STRICT_MODE, author_assoc=$PR_AUTHOR_ASSOCIATION)"
+          if [ "$VERDICT" = "skip" ]; then
+            exit 0
+          fi
+          BODY=$(printf 'Automated formal review by clud-bug — see the summary comment for the substantive findings.\n\nVerdict: **%s**\n\n<!-- clud-bug-formal-review: workflow-path v0.7.0-rc.3 -->' "$VERDICT")
+          gh api -X POST "/repos/$REPO/pulls/$PR_NUMBER/reviews" \
+            -f event="$VERDICT" \
+            -f commit_id="$HEAD_SHA" \
+            -f body="$BODY" \
+            > /dev/null \
+            || echo "::warning title=Clud Bug 🐛::Formal review POST failed (likely 422 self-PR or missing perms); degrading to comment-only."

package/templates/workflow-ts.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v12
+# clud-bug-template-version: v14
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -213,6 +213,19 @@ jobs:
           echo "::error::Set it: Settings → Secrets and variables → Actions → New repository secret."
           exit 1
 
+      # ── Design-critic (optional, opt-in) ─────────────────────────────────
+      # clud-bug can also review the *rendered* UI of your PR's preview deploy.
+      # The hosted clud-bug[bot] does this for you on Team installs (Browserless).
+      # To run it here on the Action reviewer instead — Claude drives a real
+      # browser on this runner, no paid render service — enable it in 3 steps:
+      #   1. clud-bug init --with-design   (installs the design kit + flips the
+      #      `design` block in .claude/skills/.clud-bug.json to enabled: true)
+      #   2. add a browser MCP to claude_args below, e.g.:
+      #        --mcp-config '{"mcpServers":{"playwright":{"command":"npx","args":["-y","@playwright/mcp@latest"]}}}'
+      #   3. append the browser tools to --allowedTools, e.g.:
+      #        ,mcp__playwright__browser_navigate,mcp__playwright__browser_take_screenshot
+      # Off by default. See the §3b design step in `clud-bug review-prompt`.
+      # ──────────────────────────────────────────────────────────────────────
       - uses: anthropics/claude-code-action@{{CCA_VERSION}}
         if: steps.guard.outputs.skip != 'true'
         env:
@@ -283,6 +296,40 @@ jobs:
 
           $CALIBRATION"
 
+      # Wave 5a (D.2.X) — see workflow.yml.tmpl for design notes.
+      - name: Post inline review threads
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          RESULT=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} post-inline-threads --stdin)
+          echo "::notice title=inline-threads::$RESULT"
+
+      # Wave 5b (D.2.6) — see workflow.yml.tmpl for design notes.
+      - name: Auto-resolve fixed threads
+        if: success() && github.event.action == 'synchronize'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # Optional fine-grained PAT (Pull requests: write). Present → the
+          # workflow resolves fixed threads like the hosted App. Absent (the
+          # default; an unset secret renders empty) → graceful "verified fixed"
+          # reply only, since the Actions GITHUB_TOKEN can't resolve threads.
+          CLUD_BUG_RESOLVE_PAT: ${{ secrets.CLUD_BUG_RESOLVE_PAT }}
+        run: |
+          set -euo pipefail
+          RESULT=$(npx --yes clud-bug@{{CLUD_BUG_VERSION}} resolve-threads)
+          echo "::notice title=auto-resolve::$RESULT"
+
       # v0.6.29 / Component 4 — see workflow.yml.tmpl for design notes.
       - name: Update skill-usage tracking
         if: success() && steps.clud-bug-review.outputs.structured_output != ''
@@ -366,9 +413,52 @@ jobs:
       # Strict-mode gate — composite action; see workflow.yml.tmpl for design notes.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.2
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.21
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: summary now posted by github-actions[bot].
           # See workflow.yml.tmpl for design notes.
           bot-login: 'github-actions[bot]'
+
+      # v0.7.0-rc.3 — SPEC §7.2.1 formal-review event poster.
+      # See workflow.yml.tmpl for full design rationale; this step
+      # bridges the canonical-ruleset `required_approving_review_count: 1`
+      # floor on the npm workflow path. Best-effort: never fails the
+      # workflow (continue-on-error). Drive-by exploit guard: external
+      # contributors NEVER get APPROVE.
+      - name: Formal review — APPROVE / REQUEST_CHANGES / COMMENT
+        if: always() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+          PR_AUTHOR_LOGIN: ${{ github.event.pull_request.user.login }}
+          PR_AUTHOR_ASSOCIATION: ${{ github.event.pull_request.author_association }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          set -uo pipefail
+          STRICT_MODE=false
+          if git show "origin/${BASE_REF}:.claude/skills/.clud-bug.json" > /tmp/base-manifest.json 2>/dev/null; then
+            if jq -e '.strictMode == true' /tmp/base-manifest.json > /dev/null 2>&1; then
+              STRICT_MODE=true
+            fi
+          fi
+          export STRICT_MODE
+          VERDICT=$(printf '%s\n' "$STRUCTURED" \
+            | npx --yes clud-bug@{{CLUD_BUG_VERSION}} select-review-event --stdin \
+            | tail -n1)
+          VERDICT="${VERDICT:-skip}"
+          echo "::notice title=Clud Bug 🐛::Formal review verdict: $VERDICT (strictMode=$STRICT_MODE, author_assoc=$PR_AUTHOR_ASSOCIATION)"
+          if [ "$VERDICT" = "skip" ]; then
+            exit 0
+          fi
+          BODY=$(printf 'Automated formal review by clud-bug — see the summary comment for the substantive findings.\n\nVerdict: **%s**\n\n<!-- clud-bug-formal-review: workflow-path v0.7.0-rc.3 -->' "$VERDICT")
+          gh api -X POST "/repos/$REPO/pulls/$PR_NUMBER/reviews" \
+            -f event="$VERDICT" \
+            -f commit_id="$HEAD_SHA" \
+            -f body="$BODY" \
+            > /dev/null \
+            || echo "::warning title=Clud Bug 🐛::Formal review POST failed (likely 422 self-PR or missing perms); degrading to comment-only."

package/templates/workflow.yml.tmpl

@@ -1,4 +1,4 @@
-# clud-bug-template-version: v13
+# clud-bug-template-version: v14
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -383,6 +383,19 @@ jobs:
           echo "::error::Without it, Clud Bug review is a silent no-op."
           exit 1
 
+      # ── Design-critic (optional, opt-in) ─────────────────────────────────
+      # clud-bug can also review the *rendered* UI of your PR's preview deploy.
+      # The hosted clud-bug[bot] does this for you on Team installs (Browserless).
+      # To run it here on the Action reviewer instead — Claude drives a real
+      # browser on this runner, no paid render service — enable it in 3 steps:
+      #   1. clud-bug init --with-design   (installs the design kit + flips the
+      #      `design` block in .claude/skills/.clud-bug.json to enabled: true)
+      #   2. add a browser MCP to claude_args below, e.g.:
+      #        --mcp-config '{"mcpServers":{"playwright":{"command":"npx","args":["-y","@playwright/mcp@latest"]}}}'
+      #   3. append the browser tools to --allowedTools, e.g.:
+      #        ,mcp__playwright__browser_navigate,mcp__playwright__browser_take_screenshot
+      # Off by default. See the §3b design step in `clud-bug review-prompt`.
+      # ──────────────────────────────────────────────────────────────────────
       - uses: anthropics/claude-code-action@{{CCA_VERSION}}
         # Skip the action when guard already posted the bot/fork advisory.
         if: steps.guard.outputs.skip != 'true'
@@ -503,6 +516,69 @@ jobs:
 
           $CALIBRATION"
 
+      # v0.7.0-rc.7 / Wave 5a (D.2.X): post per-finding inline review
+      # threads alongside the summary comment. Each thread is anchored
+      # to a file + line in the diff and is a first-class GitHub review
+      # thread users can reply to. Each thread body carries a hidden
+      # `<!-- finding-id: <hash> -->` marker so Wave 5b (rc.8) auto-
+      # resolve can re-match findings on subsequent fix-pushes without
+      # any persistent state.
+      #
+      # Posted IN ADDITION TO the summary comment above — they serve
+      # different UX needs: the summary is the at-a-glance digest; the
+      # inline threads are where conversation + resolution happens.
+      #
+      # `continue-on-error` so a partial GraphQL/REST failure doesn't
+      # fail the whole review; the verb itself swallows errors into its
+      # stdout JSON and exits 0.
+      - name: Post inline review threads
+        if: success() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+        run: |
+          set -euo pipefail
+          RESULT=$(printf '%s\n' "$STRUCTURED" | npx --yes clud-bug@{{CLUD_BUG_VERSION}} post-inline-threads --stdin)
+          echo "::notice title=inline-threads::$RESULT"
+
+      # v0.7.0-rc.8 / Wave 5b (D.2.6): on fix-push events
+      # (pull_request.synchronize), ask the Anthropic Messages API per
+      # bot-authored unresolved inline thread whether the new commit
+      # addressed the original finding. ADDRESSED → resolve the thread
+      # + post a marker reply; UNCERTAIN / NOT_ADDRESSED → leave open.
+      # Fail-closed: verifier errors route to UNCERTAIN (never silently
+      # dismiss).
+      #
+      # Gated on `synchronize` because:
+      # - `opened` events have no prior threads to resolve.
+      # - Re-running on every event would waste verifier $ on unchanged
+      #   state.
+      #
+      # The verb re-derives prior-finding context from the
+      # `<!-- finding-id: ... -->` markers Wave 5a embeds in each
+      # comment body, so no persistent state is needed across pushes.
+      - name: Auto-resolve fixed threads
+        if: success() && github.event.action == 'synchronize'
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          # Optional fine-grained PAT (Pull requests: write). Present → the
+          # workflow resolves fixed threads like the hosted App. Absent (the
+          # default; an unset secret renders empty) → graceful "verified fixed"
+          # reply only, since the Actions GITHUB_TOKEN can't resolve threads.
+          CLUD_BUG_RESOLVE_PAT: ${{ secrets.CLUD_BUG_RESOLVE_PAT }}
+        run: |
+          set -euo pipefail
+          RESULT=$(npx --yes clud-bug@{{CLUD_BUG_VERSION}} resolve-threads)
+          echo "::notice title=auto-resolve::$RESULT"
+
       # v0.6.29 / Component 4: pipe structured_output through
       # `clud-bug update-skill-usage` to compute the per-skill loads +
       # citations delta from this one review. Writes to the ephemeral
@@ -641,7 +717,7 @@ jobs:
       # Letting the action's own failure fail the check is louder and right.
       - name: Strict mode — fail check on critical findings
         if: success()
-        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.2
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.21
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: the summary is now posted by the workflow
@@ -651,3 +727,98 @@ jobs:
           # never matches the new summary author → strict mode falls
           # open advisory for every install that opted in.
           bot-login: 'github-actions[bot]'
+
+      # v0.7.0-rc.3 — SPEC §7.2.1 formal-review event poster.
+      #
+      # Why this step exists: the canonical ruleset (SPEC §7.2) pins
+      # `required_approving_review_count: 1`. Before this step, the
+      # workflow path posted only a summary issue comment + a
+      # `clud-bug-review` check-run — neither of which counts as an
+      # approving review. So every PR on the workflow path required a
+      # human to click Approve, even when the bot's verdict was clean.
+      #
+      # This step bridges that gap: it pipes the same structured_output
+      # the render step consumed through `clud-bug select-review-event`
+      # (SPEC §7.2.1 rule table) and, on org-trusted authors, posts a
+      # formal `pulls.createReview` with `event=APPROVE` so the
+      # `required_approving_review_count: 1` floor flips automatically.
+      #
+      # Drive-by exploit guard: external contributors NEVER get APPROVE.
+      # The select-review-event verdict for any author in
+      # {NONE, FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, MANNEQUIN} is forced
+      # to COMMENT — a human reviewer must explicitly Approve. See
+      # SPEC §7.2.1 precondition #3.
+      #
+      # Best-effort contract: this step MUST NEVER fail the workflow.
+      # `continue-on-error: true` ensures a malformed payload, network
+      # blip, or rate-limit on the formal-review API can't undo the
+      # already-posted summary comment. Worst case: no formal review is
+      # posted, falling back to today's comment-only behavior (= the
+      # pre-rc.3 status quo).
+      #
+      # Self-PR guard: when the PR author is `clud-bug[bot]` (D.7
+      # migration fan-out path that clud-bug-app authors), the verdict
+      # is "skip" — GitHub returns 422 on self-review, so we short-
+      # circuit before the network call.
+      - name: Formal review — APPROVE / REQUEST_CHANGES / COMMENT
+        if: always() && steps.clud-bug-review.outputs.structured_output != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          STRUCTURED: ${{ steps.clud-bug-review.outputs.structured_output }}
+          # SPEC §7.2.1 fields. The select-review-event command reads
+          # these from env (NOT stdin) so the workflow doesn't have to
+          # construct a nested JSON shape.
+          PR_AUTHOR_LOGIN: ${{ github.event.pull_request.user.login }}
+          PR_AUTHOR_ASSOCIATION: ${{ github.event.pull_request.author_association }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          set -uo pipefail
+
+          # Resolve strictMode from the BASE ref's manifest — same
+          # discipline as strict-mode-gate (a PR can't opt itself out
+          # of strict mode by editing its own .clud-bug.json). Best-
+          # effort: any error here falls through to STRICT_MODE=false.
+          STRICT_MODE=false
+          if git show "origin/${BASE_REF}:.claude/skills/.clud-bug.json" > /tmp/base-manifest.json 2>/dev/null; then
+            if jq -e '.strictMode == true' /tmp/base-manifest.json > /dev/null 2>&1; then
+              STRICT_MODE=true
+            fi
+          fi
+          export STRICT_MODE
+
+          # Compute the verdict (one of: APPROVE / REQUEST_CHANGES /
+          # COMMENT / skip). The command degrades to "skip" on any
+          # caller-side error (malformed JSON, missing env), so we never
+          # need a fallback in shell.
+          VERDICT=$(printf '%s\n' "$STRUCTURED" \
+            | npx --yes clud-bug@{{CLUD_BUG_VERSION}} select-review-event --stdin \
+            | tail -n1)
+          VERDICT="${VERDICT:-skip}"
+
+          echo "::notice title=Clud Bug 🐛::Formal review verdict: $VERDICT (strictMode=$STRICT_MODE, author_assoc=$PR_AUTHOR_ASSOCIATION)"
+
+          if [ "$VERDICT" = "skip" ]; then
+            # Self-PR or caller-error case. No formal review posted;
+            # the summary comment + check-run remain the visible review
+            # surface. This is the pre-rc.3 status quo.
+            exit 0
+          fi
+
+          # Body is short + machine-pingable: human reviewers see the
+          # summary issue comment for the substantive review surface;
+          # the formal-review body is a cross-link.
+          BODY=$(printf 'Automated formal review by clud-bug — see the summary comment for the substantive findings.\n\nVerdict: **%s**\n\n<!-- clud-bug-formal-review: workflow-path v0.7.0-rc.3 -->' "$VERDICT")
+
+          # gh api fires `pulls.createReview` with the verdict event.
+          # commit_id pins the review to the exact SHA we reviewed so a
+          # later push doesn't auto-extend the approval scope.
+          gh api -X POST "/repos/$REPO/pulls/$PR_NUMBER/reviews" \
+            -f event="$VERDICT" \
+            -f commit_id="$HEAD_SHA" \
+            -f body="$BODY" \
+            > /dev/null \
+            || echo "::warning title=Clud Bug 🐛::Formal review POST failed (likely 422 self-PR or missing perms); degrading to comment-only."