⚙️ Run only impacted Playwright tests in PR checks

.agents/skills/address-pr-review-comments/SKILL.md

@@ -25,7 +25,7 @@ description: Inspect, triage, implement, test, and reply to unresolved BrainRot
 ## Verify and respond
 
 1. Batch compatible fixes, then review the consolidated diff once. Run `npm run update-metadata` after game-file changes and check its output against the implementation.
-2. Run one applicable change-scoped path from `verify-changes` after the fixes are complete. Reuse passing evidence while the relevant inputs remain unchanged; the updated pull request reruns the complete lint, build, and Playwright gate in CI.
+2. Run one applicable change-scoped path from `verify-changes` after the fixes are complete. Reuse passing evidence while the relevant inputs remain unchanged; the updated pull request reruns complete quality checks and impact-selected Playwright coverage in CI.
 3. Commit fixes with a Gitmoji subject and the repository's required co-author trailer, then push normally.
 4. Reply to each valid thread with the implementing model, concise fix summary, and commit identifier.
 5. Reply to skipped comments with the triage rationale. Resolve a thread only after its fix or rationale is published.

.agents/skills/verify-changes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify-changes
-description: Validate BrainRot repository changes with process-safe, change-scoped local checks while leaving the complete lint, build, and Playwright gate to required pull request CI. Use after implementation, before committing or opening a PR, or when diagnosing test and build failures.
+description: Validate BrainRot repository changes with process-safe, change-scoped local checks while leaving complete quality checks and impact-selected Playwright coverage to required pull request CI. Use after implementation, before committing or opening a PR, or when diagnosing test and build failures.
 ---
 
 # Verify Changes
@@ -35,6 +35,6 @@ Verification-only commands may run without creating a branch. Before applying an
 
 ## Rely on the pull request gate
 
-1. GitHub Actions runs lint, the production build, and the complete Playwright suite for every pull request.
-2. Agents may publish a PR after the selected local path passes. Do not add a second verifier pass or duplicate the full CI gate locally unless one of the exceptions above applies.
+1. GitHub Actions runs complete lint, production build, asset, and selector checks plus impact-selected Playwright tests for every pull request. CI/test infrastructure and unclassified executable changes fall back to the full browser suite.
+2. Agents may publish a PR after the selected local path passes. Do not add a second verifier pass or duplicate the CI-selected browser coverage locally unless one of the exceptions above applies.
 3. The required aggregate CI check is authoritative before merge. Use its merged HTML report and retained traces when diagnosing failures.

.github/workflows/pr-checks.yml

@@ -16,6 +16,58 @@ env:
   NODE_VERSION: "22"
 
 jobs:
+  scope:
+    name: Select Playwright tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      mode: ${{ steps.pull_request.outputs.mode || steps.merge_group.outputs.mode || steps.manual.outputs.mode }}
+      grep: ${{ steps.pull_request.outputs.grep || steps.merge_group.outputs.grep || steps.manual.outputs.grep }}
+      summary: ${{ steps.pull_request.outputs.summary || steps.merge_group.outputs.summary || steps.manual.outputs.summary }}
+    steps:
+      - name: Check out repository history
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Select pull request tests
+        if: ${{ github.event_name == 'pull_request' }}
+        id: pull_request
+        run: >-
+          node scripts/select-playwright-tests.js
+          --base "${{ github.event.pull_request.base.sha }}"
+          --head "${{ github.event.pull_request.head.sha }}"
+          --github-output "$GITHUB_OUTPUT"
+
+      - name: Select merge group tests
+        if: ${{ github.event_name == 'merge_group' }}
+        id: merge_group
+        run: >-
+          node scripts/select-playwright-tests.js
+          --base "${{ github.event.merge_group.base_sha }}"
+          --head "${{ github.event.merge_group.head_sha }}"
+          --github-output "$GITHUB_OUTPUT"
+
+      - name: Select the full manual suite
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        id: manual
+        run: >-
+          node scripts/select-playwright-tests.js
+          --force-full
+          --github-output "$GITHUB_OUTPUT"
+
+      - name: Publish selection summary
+        env:
+          SUMMARY: ${{ steps.pull_request.outputs.summary || steps.merge_group.outputs.summary || steps.manual.outputs.summary }}
+        run: |
+          echo "### Playwright selection" >> "$GITHUB_STEP_SUMMARY"
+          echo "$SUMMARY" >> "$GITHUB_STEP_SUMMARY"
+
   quality:
     name: Quality
     runs-on: ubuntu-latest
@@ -42,6 +94,9 @@ jobs:
       - name: Test game asset tooling
         run: npm run test:game-assets
 
+      - name: Test CI selection
+        run: npm run test:ci-selection
+
       - name: Lint
         run: npm run lint
 
@@ -50,6 +105,8 @@ jobs:
 
   playwright:
     name: Playwright ${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+    needs: scope
+    if: ${{ needs.scope.outputs.mode != 'none' }}
     runs-on: ubuntu-latest
     timeout-minutes: 15
     strategy:
@@ -73,8 +130,15 @@ jobs:
       - name: Install Chromium
         run: npx playwright install --with-deps chromium
 
-      - name: Run Playwright shard
-        run: npm test -- --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+      - name: Run full Playwright shard
+        if: ${{ needs.scope.outputs.mode == 'full' }}
+        run: npm test -- --pass-with-no-tests --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+
+      - name: Run scoped Playwright shard
+        if: ${{ needs.scope.outputs.mode == 'scoped' }}
+        env:
+          PLAYWRIGHT_GREP: ${{ needs.scope.outputs.grep }}
+        run: npm test -- --grep "$PLAYWRIGHT_GREP" --pass-with-no-tests --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
 
       - name: Upload shard report
         if: ${{ !cancelled() }}
@@ -87,8 +151,8 @@ jobs:
 
   merge-reports:
     name: Playwright report
-    if: ${{ !cancelled() }}
-    needs: playwright
+    if: ${{ !cancelled() && needs.scope.outputs.mode != 'none' }}
+    needs: [scope, playwright]
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
@@ -125,17 +189,33 @@ jobs:
   required:
     name: Required PR checks
     if: ${{ always() }}
-    needs: [quality, playwright, merge-reports]
+    needs: [scope, quality, playwright, merge-reports]
     runs-on: ubuntu-latest
     timeout-minutes: 2
     steps:
       - name: Confirm required jobs passed
         env:
+          SCOPE_RESULT: ${{ needs.scope.result }}
+          PLAYWRIGHT_MODE: ${{ needs.scope.outputs.mode }}
           QUALITY_RESULT: ${{ needs.quality.result }}
           PLAYWRIGHT_RESULT: ${{ needs.playwright.result }}
           REPORT_RESULT: ${{ needs.merge-reports.result }}
         run: |
-          if [ "$QUALITY_RESULT" != "success" ] || [ "$PLAYWRIGHT_RESULT" != "success" ] || [ "$REPORT_RESULT" != "success" ]; then
-            echo "Required jobs did not all pass: quality=$QUALITY_RESULT playwright=$PLAYWRIGHT_RESULT report=$REPORT_RESULT"
+          if [ "$SCOPE_RESULT" != "success" ] || [ "$QUALITY_RESULT" != "success" ]; then
+            echo "Required setup failed: scope=$SCOPE_RESULT quality=$QUALITY_RESULT"
+            exit 1
+          fi
+          if [ "$PLAYWRIGHT_MODE" = "none" ]; then
+            if [ "$PLAYWRIGHT_RESULT" != "skipped" ] || [ "$REPORT_RESULT" != "skipped" ]; then
+              echo "Expected skipped browser jobs: playwright=$PLAYWRIGHT_RESULT report=$REPORT_RESULT"
+              exit 1
+            fi
+          elif [ "$PLAYWRIGHT_MODE" = "scoped" ] || [ "$PLAYWRIGHT_MODE" = "full" ]; then
+            if [ "$PLAYWRIGHT_RESULT" != "success" ] || [ "$REPORT_RESULT" != "success" ]; then
+              echo "Required browser jobs failed: mode=$PLAYWRIGHT_MODE playwright=$PLAYWRIGHT_RESULT report=$REPORT_RESULT"
+              exit 1
+            fi
+          else
+            echo "Invalid Playwright selection mode: $PLAYWRIGHT_MODE"
             exit 1
           fi

AGENTS.md

@@ -48,5 +48,5 @@ BrainRot instructions should give capable models the outcome, repository constra
 - This file applies repository-wide. Explicit user instructions take precedence; a more deeply nested `AGENTS.md` takes precedence for its subtree.
 - `games-metadata.json` is the source of truth for games, versions, model ownership, reviews, and detected features.
 - A game file may only be created or changed by the exact AI model that owns that version. Resolve ownership from `games-metadata.json`; if the exact model is unavailable, stop instead of substituting another model.
-- Keep local verification scoped to the change and avoid rerunning unchanged evidence. GitHub Actions runs the complete lint, build, and Playwright gate for every pull request, and its required aggregate check is authoritative before merge.
+- Keep local verification scoped to the change and avoid rerunning unchanged evidence. GitHub Actions runs complete lint, build, and asset checks plus impact-selected Playwright coverage for every pull request; CI/test infrastructure and unclassified executable changes fall back to the full browser suite. The required aggregate check is authoritative before merge.
 - Follow `GAME_DEVELOPMENT_GUIDE.md` for game work. Keep detailed workflows in the skills above, not in this file.

README.md

@@ -74,13 +74,16 @@ npm test
 
 # Run one affected spec while developing
 npm test -- tests/smoke.spec.ts
+
+# Validate the CI impact selector and Playwright tags
+npm run test:ci-selection
 ```
 
 ## ✅ Pull Request Checks
 
-Every pull request runs the complete validation gate in GitHub Actions: lint, the production build, and every Playwright test. The browser suite is split across two Chromium shards, then combined into one HTML report that is retained with the workflow run for 14 days.
+Every pull request runs the complete lint, production build, and asset-tooling gate in GitHub Actions. Playwright is change-scoped: game files select that exact game/model's load and regression coverage, shared application files select the site and ratings suites, and Three.js runtime files select their actual consumers. The selected browser tests remain split across two Chromium shards and are combined into one HTML report retained with the workflow run for 14 days. Documentation-only changes skip the browser jobs.
 
-Local development should stay focused. Run the smallest Playwright spec or filtered load probe that covers the change, run lint for JavaScript, TypeScript, test, or configuration changes, and run the production build for application, routing, dependency, Next.js, or shared-runtime changes. The full `npm test` suite is reserved for test or CI infrastructure changes, changes whose impact cannot be bounded, and explicit requests; otherwise the required `Required PR checks` status is the authoritative full gate before merge.
+Local development should stay focused. Run the smallest Playwright spec or filtered load probe that covers the change, run lint for JavaScript, TypeScript, test, or configuration changes, and run the production build for application, routing, dependency, Next.js, or shared-runtime changes. CI and test-infrastructure changes, unclassified executable paths, and manual `workflow_dispatch` runs use the complete Playwright suite as a fail-safe. The required `Required PR checks` status remains authoritative before merge.
 
 ## ⭐ Ratings Setup
 
@@ -107,7 +110,7 @@ If you only provide `KV_REST_API_READ_ONLY_TOKEN`, the site can show rating summ
 
 ```
 .github/
-└── workflows/pr-checks.yml      # Required lint, build, and sharded Playwright PR gate
+└── workflows/pr-checks.yml      # Required quality and change-scoped Playwright PR gate
 .agents/
 └── skills/                     # Portable workflows for all agent harnesses
 AGENTS.md                       # Cross-harness instructions and skill catalog

package.json

@@ -8,6 +8,7 @@
     "start": "next start",
     "lint": "eslint",
     "test": "playwright test",
+    "test:ci-selection": "node --test tests-node/select-playwright-tests.test.js",
     "update-metadata": "node scripts/update-metadata.js",
     "sync:three-runtime": "node scripts/sync-three-runtime.js",
     "validate:game-assets": "node scripts/validate-game-assets.js",