clud-bug 0.6.34 → 0.7.0-rc.11

package/src/core/version.ts

@@ -0,0 +1,3 @@
+// Generated by scripts/gen-version.mjs at build time. Do not edit.
+// Regenerated automatically on every `npm run build` via "prebuild" hook.
+export const PKG_VERSION = '0.7.0-rc.11';

package/templates/clud-bug-review.md.tmpl

@@ -0,0 +1,115 @@
+---
+description: Review the current branch's open PR locally, in this Claude Code session
+argument-hint: "[pr-number]"
+---
+
+<!-- clud-bug-local-version: v1 -->
+
+You are running **clud-bug** as a local code review — inside this Claude Code
+session, using this session's own model tokens (Max or API, whatever you have).
+No hosted App, no extra auth: you already have `gh`, `git`, and file access.
+
+## 1. Find the PR
+
+PR number: `$ARGUMENTS`
+
+If `$ARGUMENTS` is empty, detect the current branch's open PR:
+
+```bash
+gh pr list --head "$(git branch --show-current)" --state open --json number --jq '.[0].number'
+```
+
+If there is no open PR, stop and tell the user to open one (or pass a PR number).
+
+## 2. Load the review skills
+
+Read the manifest and every referenced skill body from the checkout:
+
+- `.claude/skills/.clud-bug.json` — which skills are installed, plus `strictMode`.
+- For each installed skill, `.claude/skills/<name>/SKILL.md` — the discipline to apply.
+
+Load skills **before** the diff. At minimum the baseline set applies:
+**critical-issues-only** (flag only correctness / security / performance — skip
+nits), **evidence-based-review** (quote the exact line you criticize — no
+hand-waving), **respect-existing-conventions** (don't fight the codebase's
+established patterns).
+
+## 3. Fetch the diff
+
+```bash
+gh pr diff <PR_NUMBER>
+```
+
+## 4. Review
+
+Review the diff against every loaded skill. For each finding record: `file`,
+`line`, `severity` (`critical` | `minor` | `preexisting`), the `skill` that
+motivated it, and a one-line `summary`. Apply the skills strictly — especially
+critical-issues-only (no nits) and evidence-based-review (quote the code).
+
+## 5. Render the review comment
+
+Build the body in clud-bug's standard shape (omit any empty findings section):
+
+```
+## 🐛 Clud Bug review — <clean | critical findings>
+
+**This round:** N critical · N minor · N resolved from prior · N still open
+
+Found: N 🔴 / N 🟡 / N 🟣
+
+### Per-skill scan
+- [<skill>]: <one line on what it scanned + found>
+
+### Critical findings
+🔴 [<skill>]: <summary> (<file>:<line>).
+
+### Minor findings
+🟡 [<skill>]: <summary> (<file>:<line>).
+
+### Pre-existing findings
+🟣 [<skill>]: <summary> (<file>:<line>).
+
+Skills referenced: [<skill>, <skill>]
+
+<!-- written-by: @<your-gh-login> (clud-bug local-mode) -->
+<!-- review-sha: <HEAD_SHA> -->
+```
+
+Get your gh login with `gh api user --jq .login` and the head sha with
+`git rev-parse HEAD`. The `written-by` marker **MUST** end with
+`(clud-bug local-mode)` so the bot's auto-resolve never mistakes this for a
+`clud-bug[bot]` comment.
+
+## 6. Post (or update) the comment
+
+Look for an existing local-mode comment and edit it in place (one rolling review
+comment), otherwise post a fresh one. Use the **REST** issues-comments endpoint
+for the lookup — its `.id` is the **integer** comment id the PATCH endpoint needs.
+(Do NOT use `gh pr view --json comments`; that returns GraphQL node IDs, which
+404 on the REST PATCH and cause duplicate comments.) `gh` fills `{owner}/{repo}`.
+
+```bash
+# existing local-mode comment id (integer), if any:
+EXISTING_ID=$(gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments" \
+  --jq '[.[] | select(.body | test("written-by: @.* \\(clud-bug local-mode\\)"))] | first | .id // empty')
+```
+
+- `$EXISTING_ID` empty → `gh pr comment <PR_NUMBER> --body-file <body.md>`
+- `$EXISTING_ID` set → `gh api "repos/{owner}/{repo}/issues/comments/$EXISTING_ID" -X PATCH -F body=@<body.md>`
+
+## 7. Summarize
+
+Print one line:
+`clud-bug local-review: N critical · N minor · N preexisting — <PASS | FAIL (strictMode) | advisory>`
+
+If `.clud-bug.json` has `strictMode: true` and there are critical findings, say
+**FAIL** and tell the user to fix them before merging.
+
+---
+
+_Optional: if the `clud-bug-mcp` MCP server is connected, you may use its
+structured tools (`load_skills_from_pr_base`, `fetch_pr_diff`,
+`partition_findings_by_severity`, `emit_review_comment`) in place of the raw
+`gh`/`git` calls above — same flow, with the base-ref skill read and the exact
+review rendering done for you._

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:
@@ -222,7 +222,7 @@ jobs:
           # HEAD_SHA (v0.6.10+) — see workflow.yml.tmpl for design notes.
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           # Per-section byte budgets — see workflow.yml.tmpl for design notes.
-          MAX_DIFF_BYTES: '80000'
+          MAX_DIFF_BYTES: '5000000'
           MAX_COMMENT_BYTES: '20000'
           MAX_SKILL_BYTES: '4000'
           # Thinking-budget cap (v0.6.8) — see workflow.yml.tmpl for design notes.
@@ -283,6 +283,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 +400,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.6.34
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.11
         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:
@@ -222,7 +222,7 @@ jobs:
           # HEAD_SHA (v0.6.10+) — see workflow.yml.tmpl for design notes.
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
           # Per-section byte budgets — see workflow.yml.tmpl for design notes.
-          MAX_DIFF_BYTES: '80000'
+          MAX_DIFF_BYTES: '5000000'
           MAX_COMMENT_BYTES: '20000'
           MAX_SKILL_BYTES: '4000'
           # Thinking-budget cap (v0.6.8) — see workflow.yml.tmpl for design notes.
@@ -283,6 +283,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 +400,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.6.34
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.11
         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: v12
+# clud-bug-template-version: v14
 name: Clud Bug 🐛 Crawls Your Code
 
 on:
@@ -396,12 +396,21 @@ jobs:
           # <prior_sha>..HEAD` (delta) when the SHA is still in HEAD's
           # ancestry. Fix-push reviews ingest only the new bytes.
           HEAD_SHA: ${{ github.event.pull_request.head.sha }}
-          # Per-section byte budgets (v0.6.4). The system-prompt instructs
-          # Claude to cap each per-PR input fetch with `head -c`. Caching
-          # covers the stable system prefix; capping covers the variable
-          # suffix (diff, comments, skills). Override per-repo by setting
-          # these env vars in the consuming workflow if defaults don't fit.
-          MAX_DIFF_BYTES: '80000'
+          # Per-section byte budgets (v0.6.4, MAX_DIFF_BYTES bumped 2026-06-08).
+          # The system-prompt instructs Claude to cap each per-PR input fetch
+          # with `head -c`. Caching covers the stable system prefix; capping
+          # covers the variable suffix (diff, comments, skills). Override
+          # per-repo by setting these env vars in the consuming workflow if
+          # defaults don't fit.
+          #
+          # 2026-06-08 CEO directive (v0.6.35): MAX_DIFF_BYTES bumped from
+          # 80000 (80KB) → 5000000 (5MB). The old default silently truncated
+          # any PR diff > 80KB, leading to half-reviews on real-world PRs.
+          # CEO: "a large diff should NEVER be a blocker or guard." 5MB is
+          # far above realistic single-PR diff sizes but bounded enough that
+          # the runner doesn't OOM. Repos that want stricter discipline can
+          # still set lower values per-repo.
+          MAX_DIFF_BYTES: '5000000'
           MAX_COMMENT_BYTES: '20000'
           MAX_SKILL_BYTES: '4000'
           # MAX_THINKING_TOKENS caps Claude Code's extended-thinking budget per
@@ -494,6 +503,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
@@ -632,7 +704,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.6.34
+        uses: thrillmade/clud-bug/.github/actions/strict-mode-gate@v0.7.0-rc.11
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           # v0.6.22 / 0.0.O: the summary is now posted by the workflow
@@ -642,3 +714,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."