[fix] use /review-docs to trigger new ai review (#3578)

Author: morningman

.github/workflows/docs-ai-review-comment.yml

@@ -3,62 +3,43 @@ name: Docs AI Review
 on:
   issue_comment:
     types: [created]
-  pull_request:
-    types: [labeled, synchronize, reopened]
   workflow_dispatch:
     inputs:
       pr_number:
-        description: Pull request number to prepare a docs AI review packet for
+        description: Pull request number to run docs AI review for
         required: true
         type: string
 
 permissions:
   contents: read
+  issues: write
+  pull-requests: read
 
 jobs:
-  prepare-docs-ai-review:
+  docs-ai-review:
     runs-on: ubuntu-latest
     timeout-minutes: 20
-    permissions:
-      contents: read
-      pull-requests: read
-    outputs:
-      pr_number: ${{ steps.pr.outputs.number }}
-      head_sha: ${{ steps.pr.outputs.head_sha }}
-      base_sha: ${{ steps.pr.outputs.base_sha }}
     if: >-
       github.event_name == 'workflow_dispatch' ||
       (
-        github.event_name == 'issue_comment' &&
         github.event.issue.pull_request &&
         contains(github.event.comment.body, '/review-docs') &&
         (
           github.event.comment.author_association == 'MEMBER' ||
           github.event.comment.author_association == 'OWNER' ||
           github.event.comment.author_association == 'COLLABORATOR'
         )
-      ) ||
-      (
-        github.event_name == 'pull_request' &&
-        github.event.action == 'labeled' &&
-        github.event.label.name == 'ai-review-docs'
-      ) ||
-      (
-        github.event_name == 'pull_request' &&
-        (github.event.action == 'synchronize' || github.event.action == 'reopened') &&
-        contains(github.event.pull_request.labels.*.name, 'ai-review-docs')
       )
+
     steps:
       - name: Get PR info
         id: pr
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ github.token }}
           EVENT_NAME: ${{ github.event_name }}
           DISPATCH_PR_NUMBER: ${{ inputs.pr_number }}
         run: |
-          if [ "$EVENT_NAME" = "pull_request" ]; then
-            PR_NUMBER=$(jq -r '.pull_request.number' "$GITHUB_EVENT_PATH")
-          elif [ "$EVENT_NAME" = "workflow_dispatch" ]; then
+          if [ "$EVENT_NAME" = "workflow_dispatch" ]; then
             PR_NUMBER="$DISPATCH_PR_NUMBER"
           else
             PR_NUMBER=$(jq -r '.issue.number' "$GITHUB_EVENT_PATH")
@@ -91,30 +72,61 @@ jobs:
         env:
           BASE_SHA: ${{ steps.pr.outputs.base_sha }}
           HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
-          PR_NUMBER: ${{ steps.pr.outputs.number }}
-          TRIGGER_NAME: ${{ github.event_name }}
         run: |
           mkdir -p website-quality-governance/generated
-          changed_files=$(git diff --name-only "$BASE_SHA" HEAD | paste -sd, -)
+          changed_files=$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" | paste -sd, -)
+
           yarn docs:ai-review:prepare \
             --files "$changed_files" \
             --base "$BASE_SHA" \
             --output website-quality-governance/generated/ai-review-packet.json
+
           jq '{schema_version, changed_files, high_risk, review_agents: [.review_agents[].id], sync_groups: [.sync_groups[].sync_group_id]}' \
             website-quality-governance/generated/ai-review-packet.json
-          jq -n \
-            --arg pr_number "$PR_NUMBER" \
-            --arg head_sha "$HEAD_SHA" \
-            --arg base_sha "$BASE_SHA" \
-            --arg trigger "$TRIGGER_NAME" \
-            '{pr_number: $pr_number, head_sha: $head_sha, base_sha: $base_sha, trigger: $trigger}' \
-            > website-quality-governance/generated/pr-metadata.json
-
-      - name: Upload review packet artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: docs-ai-review-packet-${{ steps.pr.outputs.number }}
-          path: |
-            website-quality-governance/generated/ai-review-packet.json
-            website-quality-governance/generated/pr-metadata.json
-          if-no-files-found: error
+
+      - name: Upsert advisory PR comment
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+          HEAD_SHA: ${{ steps.pr.outputs.head_sha }}
+          BASE_SHA: ${{ steps.pr.outputs.base_sha }}
+        run: |
+          packet=website-quality-governance/generated/ai-review-packet.json
+
+          marker='<!-- docs-ai-review:packet -->'
+          changed_count=$(jq '.changed_files | length' "$packet")
+          high_risk=$(jq -r '.high_risk.required' "$packet")
+          agent_count=$(jq '.review_agents | length' "$packet")
+
+          cat > /tmp/docs-ai-review-comment.md <<EOF
+          $marker
+          Docs AI review packet prepared for this PR.
+
+          - Trigger: \`/review-docs\`
+          - Changed files in packet: \`$changed_count\`
+          - High-risk docs path matched: \`$high_risk\`
+          - Review agents included: \`$agent_count\`
+          - Base SHA: \`$BASE_SHA\`
+          - Head SHA: \`$HEAD_SHA\`
+
+          This MVP prepares the packet for advisory AI review. AI findings, when produced, are suggestions only; deterministic governance CI remains the blocking signal.
+          EOF
+
+          existing_comment_id=$(
+            gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+              --paginate \
+              --jq ".[] | select(.user.type == \"Bot\" and (.body | contains(\"$marker\"))) | .id" \
+              | tail -n 1
+          )
+
+          if [ -n "$existing_comment_id" ]; then
+            gh api \
+              --method PATCH \
+              "repos/${{ github.repository }}/issues/comments/${existing_comment_id}" \
+              -f body="$(cat /tmp/docs-ai-review-comment.md)"
+          else
+            gh api \
+              --method POST \
+              "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+              -f body="$(cat /tmp/docs-ai-review-comment.md)"
+          fi