kyle-sexton · Oct 22, 2026 · Oct 22, 2026
diff --git a/.changes/animation/test-declare-audit-gap-scopes-1a9585ae.md b/.changes/animation/test-declare-audit-gap-scopes-1a9585ae.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/biome-format/test-declare-audit-gap-scopes-3cd5e055.md b/.changes/biome-format/test-declare-audit-gap-scopes-3cd5e055.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/code-metrics/test-declare-audit-gap-scopes-5ac4878b.md b/.changes/code-metrics/test-declare-audit-gap-scopes-5ac4878b.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/guardrails/test-declare-audit-gap-scopes-336857b6.md b/.changes/guardrails/test-declare-audit-gap-scopes-336857b6.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/planning/test-declare-audit-gap-scopes-eb69d31e.md b/.changes/planning/test-declare-audit-gap-scopes-eb69d31e.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/review/test-declare-audit-gap-scopes-9259ff6a.md b/.changes/review/test-declare-audit-gap-scopes-9259ff6a.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/ruff-format/test-declare-audit-gap-scopes-3254dc66.md b/.changes/ruff-format/test-declare-audit-gap-scopes-3254dc66.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/session-flow/test-declare-audit-gap-scopes-d9062c45.md b/.changes/session-flow/test-declare-audit-gap-scopes-d9062c45.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/source-control/test-declare-audit-gap-scopes-16a4930e.md b/.changes/source-control/test-declare-audit-gap-scopes-16a4930e.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/user-interface/test-declare-audit-gap-scopes-b0777b24.md b/.changes/user-interface/test-declare-audit-gap-scopes-b0777b24.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.changes/work-items/test-declare-audit-gap-scopes-f86b7d14.md b/.changes/work-items/test-declare-audit-gap-scopes-f86b7d14.md
@@ -0,0 +1,5 @@
+---
+bump: none
+---
+
+Test-only: a suite's test-scope header now declares files it reads that the pull-request test selection could not see, so a change to one of them runs the suite; no shipped behavior changes.
diff --git a/.claude/hooks/check-affected-pre-push.test.sh b/.claude/hooks/check-affected-pre-push.test.sh
@@ -18,6 +18,7 @@
 # it ran and exits with $STUB_RC, so these cases test the hook, not the checks.
 # The cases hold shell source as literal data on purpose.
 # shellcheck disable=SC2016
+# test-scope: .claude/settings.json
 set -uo pipefail
 
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" || exit 2

diff --git a/plugins/animation/scripts/animation.test.sh b/plugins/animation/scripts/animation.test.sh
@@ -7,7 +7,7 @@
 # broken environment, not as passing coverage. test_render renders through node and playwright-core with
 # Chromium and skips without them, or fails under ANIMATION_REQUIRE_DEPS=1.
 # test-scope: plugins/animation/skills/*/SKILL.md plugins/animation/skills/*/scripts/* plugins/animation/hooks/*.sh plugins/animation/scripts/*
-# test-scope: plugins/animation/requirements.in plugins/animation/styles/*
+# test-scope: plugins/animation/requirements.in plugins/animation/styles/* plugins/animation/.claude-plugin/plugin.json
 set -uo pipefail
 
 cd "$(dirname "${BASH_SOURCE[0]}")" || exit 1

diff --git a/plugins/biome-format/hooks/biome-format.test.sh b/plugins/biome-format/hooks/biome-format.test.sh
@@ -20,7 +20,7 @@
 #
 # Requires a real Biome binary: $BIOME_TEST_BIN if set, else `biome` on PATH.
 # Without one the behavioral assertions cannot run, so the suite skips.
-# test-scope: plugins/biome-format/.claude-plugin/plugin.json plugins/biome-format/hooks/hooks.json plugins/biome-format/prerequisites.json
+# test-scope: plugins/biome-format/.claude-plugin/plugin.json plugins/biome-format/hooks/hooks.json plugins/biome-format/prerequisites.json plugins/biome-format/lib/git-hooks/install.mjs plugins/biome-format/lib/prerequisites.mjs
 
 set -uo pipefail
 

diff --git a/plugins/code-metrics/skills/audit-coverage/scripts/audit-coverage.test.sh b/plugins/code-metrics/skills/audit-coverage/scripts/audit-coverage.test.sh
@@ -16,7 +16,7 @@
 # only, which is what makes Bash CRAP not-applicable). Nothing executable is
 # committed (design T13). No test command is ever run: this skill reads
 # artifacts.
-# test-scope: plugins/code-metrics/scripts/collectors/*.py plugins/code-metrics/scripts/parsers/*.py plugins/code-metrics/scripts/fixtures/*
+# test-scope: plugins/code-metrics/scripts/collectors/*.py plugins/code-metrics/scripts/parsers/*.py plugins/code-metrics/scripts/fixtures/* plugins/code-metrics/scripts/yaml_subset.py
 set -uo pipefail
 unset GIT_DIR GIT_WORK_TREE GIT_CONFIG
 

diff --git a/plugins/code-metrics/skills/audit-type-debt/scripts/audit-type-debt.test.sh b/plugins/code-metrics/skills/audit-type-debt/scripts/audit-type-debt.test.sh
@@ -13,7 +13,7 @@
 # repository-relative path and passed relative, as the dispatcher passes a
 # scope in a real run, because the type-coverage capture names its file by
 # that relative path and a file row matches a scope file on the path.
-# test-scope: plugins/code-metrics/scripts/collectors/*.py plugins/code-metrics/scripts/fixtures/*
+# test-scope: plugins/code-metrics/scripts/collectors/*.py plugins/code-metrics/scripts/fixtures/* plugins/code-metrics/scripts/yaml_subset.py
 set -uo pipefail
 unset GIT_DIR GIT_WORK_TREE GIT_CONFIG
 

diff --git a/plugins/guardrails/git-hooks/reference-verify.test.sh b/plugins/guardrails/git-hooks/reference-verify.test.sh
@@ -8,7 +8,7 @@
 # the skip key covers only a missing jq); --worktree covers uncommitted files;
 # and the plugin's vendored installer wires the entry as a pre-push hook, so
 # `git commit` does not run it and `git push` does.
-# test-scope: plugins/guardrails/git-hooks/entries.json plugins/guardrails/hooks/run-guards.sh plugins/guardrails/hooks/cli-flag-verify.sh plugins/guardrails/hooks/stale-path-verify.sh plugins/guardrails/hooks/skill-reference-verify.sh plugins/guardrails/lib/git-hooks/install.mjs plugins/guardrails/lib/git-hooks/check-lib.sh
+# test-scope: plugins/guardrails/git-hooks/entries.json plugins/guardrails/hooks/run-guards.sh plugins/guardrails/hooks/cli-flag-verify.sh plugins/guardrails/hooks/stale-path-verify.sh plugins/guardrails/hooks/skill-reference-verify.sh plugins/guardrails/lib/git-hooks/install.mjs plugins/guardrails/lib/git-hooks/check-lib.sh plugins/guardrails/.claude-plugin/plugin.json plugins/guardrails/git-hooks/commit-msg-convention.sh plugins/guardrails/git-hooks/pre-commit-content.sh
 set -uo pipefail
 unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_CONFIG CLAUDECODE AI_AGENT CLAUDE_PLUGIN_ROOT CLAUDE_PLUGIN_DATA
 

diff --git a/plugins/guardrails/hooks/block-convention-violation.test.sh b/plugins/guardrails/hooks/block-convention-violation.test.sh
@@ -4,6 +4,7 @@
 # Black-box: invokes the hook as a subprocess, pipes PreToolUse JSON on stdin,
 # asserts on exit code (2 = blocked, 0 = allowed). Each case runs against an
 # isolated repo root whose team convention file this test controls.
+# test-scope: plugins/guardrails/hooks/*.test.sh plugins/guardrails/hooks/workflow-resilience-check.sh
 
 set -uo pipefail
 

diff --git a/plugins/guardrails/hooks/block-fix-request-post.test.sh b/plugins/guardrails/hooks/block-fix-request-post.test.sh
@@ -12,6 +12,7 @@
 # names the phrase, so a substring matcher would have blocked it.
 
 # shellcheck disable=SC2016  # command strings are literal test input, never expanded here
+# test-scope: plugins/guardrails/.claude-plugin/plugin.json
 set -uo pipefail
 
 HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

diff --git a/plugins/planning/shared/tests/align.test.sh b/plugins/planning/shared/tests/align.test.sh
@@ -4,6 +4,7 @@
 # PASS n / n with n above 0.
 #   bash plugins/planning/shared/tests/align.test.sh
 # Narrow a run with ALIGN_VIEWS (comma list of view names) and ALIGN_SIZES (comma list of WxH, e.g. 390x844).
+# test-scope: plugins/planning/.claude-plugin/plugin.json plugins/planning/shared/detached.py plugins/planning/shared/server.py plugins/planning/shared/session.py plugins/planning/shared/session_bridge.py plugins/planning/shared/share.py plugins/planning/shared/share.sh plugins/planning/shared/tunnel.py plugins/planning/shared/schema/*.schema.json plugins/planning/shared/tests/browser_harness.js plugins/planning/shared/tests/fixtures/fake-cloudflared.sh plugins/planning/shared/web/*.css plugins/planning/shared/web/*.js plugins/planning/shared/web/index.html plugins/planning/shared/web/proto.html plugins/planning/surface/schema.py plugins/planning/surface/schema/*.schema.json
 set -u
 here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 command -v node >/dev/null || {

diff --git a/plugins/planning/shared/tests/test_people_proposals.py b/plugins/planning/shared/tests/test_people_proposals.py
@@ -1,4 +1,4 @@
-# test-scope: plugins/planning/shared/session.py plugins/planning/shared/schema/ops.schema.json plugins/planning/shared/schema/state.schema.json plugins/planning/shared/schema/event.schema.json
+# test-scope: plugins/planning/shared/session.py plugins/planning/shared/schema/ops.schema.json plugins/planning/shared/schema/state.schema.json plugins/planning/shared/schema/event.schema.json plugins/planning/shared/schema/question-shape.schema.json plugins/planning/shared/schema/wire.schema.json plugins/planning/surface/schema/*.schema.json
 """Claude proposes a duplicate-person merge or a join admit; only the owner's tap carries it out.
 
 Expected values come from issue #8697 and the owner's decision on it (Claude proposes with its

diff --git a/plugins/planning/shared/tests/tracer.test.sh b/plugins/planning/shared/tests/tracer.test.sh
@@ -5,6 +5,7 @@
 # sends -> watch.sh prints round-sent -> apply ack-round plus the next open-round -> restart ->
 # the guest link, the people and the answers are intact -> stop leaves nothing running.
 # Credentials reach curl through header files (-H @file), never its command line.
+# test-scope: plugins/planning/.claude-plugin/plugin.json plugins/planning/shared/schema/event.schema.json plugins/planning/shared/schema/question-shape.schema.json plugins/planning/surface/schema/event.schema.json plugins/planning/surface/schema/ops.schema.json plugins/planning/surface/schema/responses.schema.json plugins/planning/surface/schema/visual.schema.json
 set -u
 here=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
 shared=$(cd "$here/.." && pwd)

@@ -3,6 +3,7 @@
 # Each case builds its own repository root in a temp directory; expected values
 # come from the schema's allowed values (true, false) and the script's stated
 # exit codes, not from the script's output.
+# test-scope: plugins/review/lib/parse-concern-value.sh plugins/review/lib/resolve-convention-home.sh
 set -uo pipefail
 
 unset GIT_DIR GIT_WORK_TREE GIT_CONFIG

diff --git a/plugins/ruff-format/hooks/ruff-format-end-of-turn.test.sh b/plugins/ruff-format/hooks/ruff-format-end-of-turn.test.sh
@@ -5,7 +5,7 @@
 # keeps it from blocking twice in one turn; the plugin kill switch wins. The
 # spawn budget case fences the cost every user pays per turn with the option
 # off: the node launcher only.
-# test-scope: plugins/ruff-format/hooks/hooks.json plugins/ruff-format/git-hooks/ruff-check.sh plugins/ruff-format/.claude-plugin/plugin.json
+# test-scope: plugins/ruff-format/hooks/hooks.json plugins/ruff-format/git-hooks/ruff-check.sh plugins/ruff-format/.claude-plugin/plugin.json plugins/ruff-format/hooks/exec-bash.mjs
 set -uo pipefail
 unset GIT_DIR GIT_WORK_TREE GIT_CONFIG GIT_INDEX_FILE CLAUDE_PLUGIN_OPTION_RUFF_FORMAT_END_OF_TURN CLAUDE_PLUGIN_OPTION_RUFF_FORMAT_ENABLED
 

diff --git a/plugins/session-flow/skills/running-retro/scripts/test_observer.py b/plugins/session-flow/skills/running-retro/scripts/test_observer.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+# test-scope: plugins/session-flow/.claude-plugin/plugin.json
 """Unit + integration tests for the detached observer (stdlib unittest, no deps).
 
 Mirrors retro's `test_parse_transcript.py` convention. Covers the pieces the

@@ -1,3 +1,4 @@
+# test-scope: plugins/source-control/skills/babysit-prs/scripts/tests/repo_config_fake.py
 """pr-merge's candidate prefilter: a held candidate never reaches the gate.
 
 A candidate whose listed labels or body carry a hold the gate refuses on is

diff --git a/plugins/user-interface/tests/detect.test.sh b/plugins/user-interface/tests/detect.test.sh
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Discovery wrapper: scripts/run-plugin-tests.sh finds plugins/**/*.test.sh, so
 # this hands off to the Node suite. SKIPs (exit 0) when Node is unavailable.
-# test-scope: plugins/user-interface/tests/fixtures/*/package.json plugins/user-interface/tests/fixtures/*/conventions/*.yaml
+# test-scope: plugins/user-interface/tests/fixtures/*/package.json plugins/user-interface/tests/fixtures/*/conventions/*.yaml plugins/user-interface/tests/fixtures/*/src/*.svelte plugins/user-interface/tests/fixtures/*/src/*.vue
 set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

diff --git a/plugins/work-items/tools/work-item-tracker/adapters/linear/list-items.test.sh b/plugins/work-items/tools/work-item-tracker/adapters/linear/list-items.test.sh
@@ -2,6 +2,7 @@
 # shellcheck disable=SC2154  # FAILED/CASE_NUM initialized by the sourced helper
 # list-items: offline contract tests. Pagination, state filtering, and the scope
 # boundary are driven through a mocked curl — no live Linear call.
+# test-scope: plugins/work-items/tools/work-item-tracker/adapters/linear/*.sh
 set -uo pipefail
 S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/list-items.sh"
 D="$(dirname "$S")"

diff --git a/scripts/selection-audit.sh b/scripts/selection-audit.sh
@@ -249,12 +249,13 @@ cmd_trace() {
   done <"$out/files"
   # gaps.tsv: suite, file, verdict, for every read the selector would not
   # take. An unmapped file is no gap for a suite the fallback runs, and a gap
-  # for one it does not; an unchecked file is counted apart.
+  # for one it does not; an unchecked file is counted apart; a file recorded in
+  # scripts/affected-tests-no-suite.txt is covered by a non-shell lane, so no gap.
   awk -F'\t' '
     FILENAME ~ /fallback$/ { fb[$0] = 1; next }
     FILENAME ~ /selected.tsv$/ { sel[$1 SUBSEP $2] = 1; next }
     FILENAME ~ /verdicts.tsv$/ { v[$1] = $2; next }
-    v[$2] ~ /^not checked/ || (($2 SUBSEP $1) in sel) { next }
+    v[$2] ~ /^(not checked|no-suite:)/ || (($2 SUBSEP $1) in sel) { next }
     v[$2] ~ /^unmapped/ { if ($1 in fb) next; print $1 "\t" $2 "\tunmapped: the fallback corpus does not run this suite"; next }
     { print $1 "\t" $2 "\t" v[$2] }
   ' "$out/fallback" "$out/selected.tsv" "$out/verdicts.tsv" "$out/edges.tsv" | sort >"$out/gaps.tsv"

diff --git a/scripts/selection-audit.test.sh b/scripts/selection-audit.test.sh
@@ -69,14 +69,15 @@ else
   git_repo "$t"
   mkdir -p "$t/suites" "$t/data"
   echo hidden >"$t/data/hidden.txt"
+  echo recorded >"$t/data/recorded.txt"
   echo named >"$t/data/named.txt"
   echo odd >"$t/data/unmapped.txt"
   echo broken >"$t/data/broken.txt"
   # The root toolchain files every suite reads are no gap.
   echo '{}' >"$t/package.json"
   echo 22 >"$t/.node-version"
   echo '*.log' >"$t/.gitignore"
-  printf '%s\n' '#!/usr/bin/env bash' 'cat data/hidden.txt data/named.txt data/unmapped.txt data/untracked.txt data/broken.txt' \
+  printf '%s\n' '#!/usr/bin/env bash' 'cat data/hidden.txt data/recorded.txt data/named.txt data/unmapped.txt data/untracked.txt data/broken.txt' \
     'cat package.json .node-version .gitignore' >"$t/suites/reader.test.sh"
   printf '%s\n' '#!/usr/bin/env bash' 'true' >"$t/suites/quiet.test.sh"
   # Reads the unmapped file too, but the fallback corpus does not run it.
@@ -97,21 +98,21 @@ case "$f" in
 data/named.txt) echo suites/reader.test.sh ;;
 data/unmapped.txt) echo "UNMAPPED: 1 changed file(s) map to no test suite:" >&2 ;;
 data/broken.txt) exit 3 ;;
-*) echo "no-suite: $f (recorded in the stub)" >&2 ;;
+data/recorded.txt) echo "no-suite: $f (recorded in the stub)" >&2 ;;
 esac
 EOF
   rc=0
   (cd "$t" && SELECTION_AUDIT_SELECTOR="$TMP_ROOT/stub-selector.sh" GITHUB_STEP_SUMMARY="$TMP_ROOT/summary.md" \
     bash "$AUDIT" trace --jobs 2 --out "$TMP_ROOT/out") >"$TMP_ROOT/trace.log" 2>&1 || rc=$?
   gaps="$(cat "$TMP_ROOT/out/gaps.tsv" 2>/dev/null)"
-  want=$'suites/reader.test.sh\tdata/hidden.txt\tno-suite: data/hidden.txt (recorded in the stub)\nsuites/zz-outside.test.sh\tdata/unmapped.txt\tunmapped: the fallback corpus does not run this suite'
+  want=$'suites/reader.test.sh\tdata/hidden.txt\tselects no suite\nsuites/zz-outside.test.sh\tdata/unmapped.txt\tunmapped: the fallback corpus does not run this suite'
   if [[ "$rc" -eq 1 ]]; then
     ok "trace: exits 1 on a gap"
   else
     fail "trace: exit $rc, want 1: $(cat "$TMP_ROOT/trace.log")"
   fi
   if [[ "$gaps" == "$want" ]]; then
-    ok "trace: gaps are the unmapped-to-suite read and the unmapped read of a suite the fallback does not run (mapped, fallback-run, unchecked, untracked, self and root toolchain files are not)"
+    ok "trace: gaps are the read that selects no suite, the unmapped-to-suite read and the unmapped read of a suite the fallback does not run (mapped, recorded no-suite, fallback-run, unchecked, untracked, self and root toolchain files are not)"
   else
     fail "trace: gaps.tsv [$gaps] want [$want]"
   fi