diff --git a/.github/workflows/pr_build_test.yml b/.github/workflows/pr_build_test.yml
index f932049..13fdec3 100644
--- a/.github/workflows/pr_build_test.yml
+++ b/.github/workflows/pr_build_test.yml
@@ -10,7 +10,12 @@ on:
       - "BrewUITests/**"
       - "Brew.xcodeproj/**"
       - "Brew.entitlements"
+      - "Sources/**"
+      - "Tests/**"
+      - "Package.swift"
       - "Package.resolved"
+      - "Tools/BrewUILint/**"
+      - "scripts/test"
       - ".github/workflows/pr_build_test.yml"
   pull_request:
     types: [opened, reopened, synchronize]
@@ -20,7 +25,12 @@ on:
       - "BrewUITests/**"
       - "Brew.xcodeproj/**"
       - "Brew.entitlements"
+      - "Sources/**"
+      - "Tests/**"
+      - "Package.swift"
       - "Package.resolved"
+      - "Tools/BrewUILint/**"
+      - "scripts/test"
       - ".github/workflows/pr_build_test.yml"
 
 permissions:
@@ -42,7 +52,7 @@ jobs:
       - name: Resolve package dependencies
         run: xcodebuild -resolvePackageDependencies -project Brew.xcodeproj
 
-      - name: Build and test
+      - name: Build and test (Xcode app target)
         run: |
           set -o pipefail
           xcodebuild test \
@@ -57,10 +67,43 @@ jobs:
             CODE_SIGNING_ALLOWED=NO \
             | tee xcodebuild.log
 
+      - name: Capture Swift toolchain fingerprint
+        id: swift-toolchain
+        run: echo "fingerprint=$(swift --version | shasum -a 256 | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
+      - name: Cache BrewKit .build
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: .build
+          key: ${{ runner.os }}-brewkit-${{ steps.swift-toolchain.outputs.fingerprint }}-${{ hashFiles('Package.swift', 'Package.resolved') }}
+          restore-keys: |
+            ${{ runner.os }}-brewkit-${{ steps.swift-toolchain.outputs.fingerprint }}-
+
+      - name: Run BrewKit package tests
+        run: |
+          set -o pipefail
+          xcrun swift test --package-path . | tee swift-test-brewkit.log
+
+      - name: Cache BrewUILint .build
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: Tools/BrewUILint/.build
+          key: ${{ runner.os }}-brewuilint-${{ steps.swift-toolchain.outputs.fingerprint }}-${{ hashFiles('Tools/BrewUILint/Package.swift', 'Tools/BrewUILint/Package.resolved', 'Tools/BrewUILint/Sources/**', 'Tools/BrewUILint/Tests/**', 'Tools/BrewUILint/Plugins/**') }}
+          restore-keys: |
+            ${{ runner.os }}-brewuilint-${{ steps.swift-toolchain.outputs.fingerprint }}-
+
+      - name: Run BrewUILint package tests
+        run: |
+          set -o pipefail
+          xcrun swift test --package-path Tools/BrewUILint | tee swift-test-brewuilint.log
+
       - name: Upload logs on failure
         if: failure() || cancelled()
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: pr-build-test-logs
-          path: xcodebuild.log
+          path: |
+            xcodebuild.log
+            swift-test-brewkit.log
+            swift-test-brewuilint.log
           retention-days: 7
diff --git a/.github/workflows/swift_quality.yml b/.github/workflows/swift_quality.yml
index 2aec7e5..d524b69 100644
--- a/.github/workflows/swift_quality.yml
+++ b/.github/workflows/swift_quality.yml
@@ -64,13 +64,17 @@ jobs:
       - name: Run SwiftLint (strict)
         run: mint run swiftlint lint --strict
 
+      - name: Capture Swift toolchain fingerprint
+        id: swift-toolchain
+        run: echo "fingerprint=$(swift --version | shasum -a 256 | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
       - name: Cache BrewUILint build
         uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
         with:
           path: Tools/BrewUILint/.build
-          key: ${{ runner.os }}-brewuilint-${{ hashFiles('Tools/BrewUILint/Package.swift', 'Tools/BrewUILint/Package.resolved', 'Tools/BrewUILint/Sources/**', 'Tools/BrewUILint/Plugins/**') }}
+          key: ${{ runner.os }}-brewuilint-${{ steps.swift-toolchain.outputs.fingerprint }}-${{ hashFiles('Tools/BrewUILint/Package.swift', 'Tools/BrewUILint/Package.resolved', 'Tools/BrewUILint/Sources/**', 'Tools/BrewUILint/Plugins/**') }}
           restore-keys: |
-            ${{ runner.os }}-brewuilint-
+            ${{ runner.os }}-brewuilint-${{ steps.swift-toolchain.outputs.fingerprint }}-
 
       - name: Build BrewUILint
         run: swift build --package-path Tools/BrewUILint -c release --enable-experimental-prebuilts
diff --git a/AGENTS.md b/AGENTS.md
index c4b064e..d7f12e0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,6 +89,17 @@ When you change Swift sources or anything that affects Swift formatting or linti
 
 The pre-commit hook formats and lints **staged** Swift files (SwiftFormat/SwiftLint) and additionally runs **BrewUILint over the whole tree** on every commit; these manual commands validate the whole tree like CI and catch drift in unstaged paths.
 
+### Tests (local parity with CI)
+
+`scripts/test` runs `swift test` for both packages — `BrewKit` (root `Package.swift`) and `BrewUILint` (`Tools/BrewUILint/Package.swift`) — matching what `.github/workflows/pr_build_test.yml` runs in CI.
+
+**Agents must run `scripts/test` and confirm it exits 0 at both of these points:**
+
+1. **Before any `git commit` you make.** Tests are intentionally **not** enforced by the pre-commit git hook (too slow to run on every staged-file commit during interactive work), so the responsibility moves to the agent. If `scripts/test` fails, fix it before committing — do not commit with failures, and do not skip the run.
+2. **Before reporting a code-changing turn complete to the user,** when that turn modified Swift sources under `Sources/`, `Tests/`, `Brew/`, or `Tools/BrewUILint/`, *or* changed `Package.swift` / `Package.resolved` / `.github/workflows/pr_build_test.yml`. For turns that only touch docs, YAML unrelated to tests, or other non-Swift files, the run is optional.
+
+If a test failure surfaces a real regression that's out of scope for the current turn, surface it to the user rather than silently skipping it — never paper over a red test with `.disabled` or `--filter` exclusions without flagging.
+
 ---
 
 ## What Lives Where
diff --git a/scripts/test b/scripts/test
new file mode 100755
index 0000000..11bb2d4
--- /dev/null
+++ b/scripts/test
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# test — run all Swift Package tests (BrewKit + BrewUILint).
+#
+# Mirrors what CI runs in .github/workflows/pr_build_test.yml, so green
+# locally means green on CI.
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+echo "==> BrewKit package tests"
+xcrun swift test --package-path .
+
+echo "==> BrewUILint package tests"
+xcrun swift test --package-path Tools/BrewUILint
+
+echo "==> All package tests passed."