ci: automated Claude PR review + human merge gate

.github/workflows/claude-mention.yml

@@ -0,0 +1,52 @@
+name: Claude Mention
+
+# @claude-triggered review. Runs in the trusted base-repo context (so the token is
+# available) — which is why it is gated to trusted commenters. Handles fork PRs
+# WITHOUT executing their code: no npm scripts are granted here, so Claude reviews
+# statically and cites the existing `validate-and-test` CI check (which already ran
+# on the fork PR without secrets) as the source of truth for pass/fail.
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  mention:
+    # Fire only when: the comment is on a PR, mentions @claude, and the commenter is
+    # a trusted actor (prevents anonymous users burning subscription quota).
+    if: >-
+      (
+        (github.event_name == 'issue_comment' && github.event.issue.pull_request != null) ||
+        github.event_name == 'pull_request_review_comment'
+      ) &&
+      contains(github.event.comment.body, '@claude') &&
+      (
+        github.event.comment.author_association == 'OWNER' ||
+        github.event.comment.author_association == 'MEMBER' ||
+        github.event.comment.author_association == 'COLLABORATOR'
+      )
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Built-in Actions token for GitHub API; skips the OIDC exchange so no
+          # `id-token: write` and no Claude GitHub App install are required.
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          # No `prompt`: the @claude comment body is the instruction, so a maintainer
+          # can ask for a full review or a targeted question.
+          # Fork-safe tool set: read-only git + read utils for static inspection, and
+          # `gh pr comment` to post the reply. Deliberately NO `npm`/build execution —
+          # this path may target a fork, so it never runs the PR's code; it reviews
+          # statically and cites the existing `validate-and-test` CI check for pass/fail.
+          claude_args: |
+            --max-turns 30
+            --allowedTools "Bash(git diff:*),Bash(git log:*),Bash(git show:*),Bash(git ls-tree:*),Bash(git cat-file:*),Bash(git rev-parse:*),Bash(git status:*),Bash(cat:*),Bash(ls:*),Bash(head:*),Bash(tail:*),Bash(grep:*),Bash(wc:*),Bash(find:*),Bash(jq:*),Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh pr checks:*),Bash(gh pr comment:*)"

.github/workflows/claude-review.yml

@@ -0,0 +1,87 @@
+name: Claude PR Review
+
+# Auto-review for pull requests opened from a branch inside THIS repo
+# (maintainer/collaborators — trusted). Fork PRs fall through to a no-op via the
+# job `if` guard and are instead handled by claude-mention.yml on an @claude
+# comment. Uses the plain `pull_request` event (never pull_request_target).
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  review:
+    # Only run for non-draft PRs whose head branch lives in this repo (not a fork).
+    if: >-
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history so the reviewer can `git diff` against the base
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Use the built-in Actions token for GitHub API (post comments / read PR).
+          # Providing github_token makes the action SKIP the OIDC exchange, so no
+          # `id-token: write` permission and no Claude GitHub App install are needed.
+          # Trade-off: review comments post as github-actions[bot], not claude[bot].
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            You are reviewing a pull request against the Droidnet Command Library —
+            a schema-driven engine + composer that builds serial commands for
+            Astromech droid boards. Most PRs edit a JSON board file under
+            libraries/boards/. Read CLAUDE.md and CONTRIBUTING.md for the full rules
+            before reviewing.
+
+            Do all of the following, then post your review as exactly ONE PR
+            comment using: gh pr comment <PR_NUMBER> --repo <OWNER/REPO> --body "…".
+            Reference specific file:line locations inline in the summary text (you
+            do not have a GitHub inline-comment tool here). You are advisory only:
+            do NOT modify code, approve, or merge.
+
+            1. Verify the checks. Run:
+                 npm ci
+                 npm run validate
+                 npm test
+               Report pass/fail with the actual output. If validate or a test fails,
+               point at the offending file and line and explain the fix.
+
+            2. Enforce the board-contribution rules (see CONTRIBUTING.md "What the
+               validator enforces"):
+               - Every command has at least one `examples` string.
+               - Every {placeholder} in a template has a matching param, and every
+                 param maps to a placeholder (both directions).
+               - Every param.enum resolves to a defined enum.
+               - Command ids are unique across ALL board files.
+               - If any board changed, libraries/manifest.json `libraryVersion` is
+                 bumped per semver (patch=fix, minor=add, major=rename/remove), and
+                 releases.json is in sync if the released version changed.
+               - `confidence` is set honestly — unverified contributions use
+                 `community`, not `high`.
+
+            3. HIGH SEVERITY — flag any safety-class mislabeling. A command that moves
+               the droid or affects power must NOT be marked safety:"cosmetic". Per
+               the project's Code of Conduct, mislabeling can cause real hardware to
+               move unexpectedly. Call this out prominently.
+
+            4. For changes to src/*.js: check correctness, keep the engine DOM-free
+               and the UI going through buildWCBValue/parseWCBValue, and preserve the
+               round-trip invariant buildWCBValue(parseWCBValue(v)) === v.
+
+            Keep the summary concise and actionable. Reference specific file:line
+            locations for any line-specific issues.
+          claude_args: |
+            --max-turns 40
+            --allowedTools "Bash(npm ci),Bash(npm run validate),Bash(npm test),Bash(npm run lint),Bash(git diff:*),Bash(git log:*),Bash(git show:*),Bash(git ls-tree:*),Bash(git cat-file:*),Bash(git rev-parse:*),Bash(git status:*),Bash(cat:*),Bash(ls:*),Bash(head:*),Bash(tail:*),Bash(grep:*),Bash(wc:*),Bash(find:*),Bash(jq:*),Bash(gh pr comment:*)"