docs: refine recommended paths defaults (composer.json, drop tests filter)

.github/workflows/php-composer-script.yml

@@ -34,17 +34,21 @@
 #         name: Run PHPStan
 #         run: composer phpstan
 #
-# Recommended path filters by script (in addition to the workflow file
-# and composer.json/composer.lock for anything that runs `composer install`):
+# Recommended path filters by script. Always include composer.json (and
+# composer.lock for anything that runs `composer install`) since each job
+# is invoked through a composer script that's defined there:
 #
 #   composer-validate          composer.json
 #   composer-normalize         composer.json
 #   composer-require-checker   composer.json, composer.lock, '**.php',
 #                              .composer-require-checker.json
-#   php-syntax-check           '**.php'
-#   phpcs                      '**.php', .phpcs.xml*, phpcs.xml*
-#   phpstan                    '**.php', phpstan.neon*, phpstan-baseline.neon
-#   rector                     '**.php', rector.php
+#   php-syntax-check           '**.php', composer.json
+#   phpcs                      '**.php', .phpcs.xml*, phpcs.xml*,
+#                              composer.json, composer.lock
+#   phpstan                    '**.php', phpstan.neon*, phpstan-baseline.neon,
+#                              composer.json, composer.lock
+#   rector                     '**.php', rector.php,
+#                              composer.json, composer.lock
 name: PHP Composer Script (reusable)
 
 on:

.github/workflows/php-tests.yml

@@ -1,27 +1,18 @@
 # PHPUnit reusable workflow with PHP-version matrix and optional coverage.
 #
+# Tests depend on too many runtime assets (templates, SQL, config, fixtures)
+# to safely enumerate via a paths filter. Don't add one — let tests run on
+# every change. The runner cost is much smaller than the cost of skipping
+# tests when an asset that affects them changed.
+#
 # Recommended caller stanza:
 #
 #   name: Tests
 #   on:
 #     push:
 #       branches: [main]
-#       paths:
-#         - '**.php'
-#         - composer.json
-#         - composer.lock
-#         - phpunit.xml
-#         - phpunit.xml.dist
-#         - .github/workflows/tests.yml
 #     pull_request:
 #       branches: [main]
-#       paths:
-#         - '**.php'
-#         - composer.json
-#         - composer.lock
-#         - phpunit.xml
-#         - phpunit.xml.dist
-#         - .github/workflows/tests.yml
 #   jobs:
 #     test:
 #       uses: openCoreEMR/github-workflows-public/.github/workflows/php-tests.yml@<tag>

README.md

@@ -18,7 +18,14 @@ Pin to a specific version tag (e.g. `@1.0.0`). Pinning to `@main` works but may
 
 GitHub evaluates `on: push.paths` and `on: pull_request.paths` *before* the reusable is invoked, so the reusable only sees `workflow_call` and cannot influence whether the workflow runs at all. Always declare an appropriately scoped `paths:` filter in the caller — running every PHP linter on every CSS-only PR wastes both runner minutes and reviewer attention.
 
-Each reusable workflow file has a header comment with the recommended caller stanza (including paths). Copy from there. As a rule of thumb, include the caller's own workflow file in the paths so the job re-runs whenever the caller changes.
+Each reusable workflow file has a header comment with the recommended caller stanza (including paths). Copy from there.
+
+Two rules of thumb:
+
+1. **Include `composer.json` in every PHP linter caller.** The linters are invoked through composer scripts (`composer phpstan`, `composer phpcs`, etc.), so a change to `composer.json` can change what runs. For anything that runs `composer install`, also include `composer.lock`.
+2. **Don't put a `paths` filter on `tests.yml`.** Tests depend on too many runtime assets (templates, SQL, config, fixtures) to safely enumerate, and missing a real test failure costs more than running tests on a docs-only PR.
+
+And as a general rule, include the caller's own workflow file in the paths so the job re-runs whenever the caller changes.
 
 ## Workflows