Record what the ggshield config does and does not reach

.gitguardian.yaml

@@ -5,13 +5,17 @@
 # not credentials: the redaction tests prove the value never reaches the audit log
 # or a listing, which requires a distinctive value to search for.
 #
-# Two mechanisms keep the scanner quiet, and they cover different things:
+# Three mechanisms keep the scanner quiet, and they cover different things:
 #
 #   1. `envkit_canary()` in tests/Pest.php, so no line reads
 #      `SOMETHING_PASSWORD=<literal>` -- the shape the detector matches. That is
-#      the better fix, and it handles new commits at source.
+#      the better fix, it handles new commits at source, and it is the only one of
+#      the three that works everywhere.
 #   2. The entries below, for what a rename cannot reach: the literals already in
-#      history, and the three that remain on assignment lines today.
+#      history, and the three that remain on assignment lines today. These apply
+#      only where `ggshield` runs -- see the scope note below.
+#   3. Resolution in the GitGuardian dashboard, which is what silences the
+#      `GitGuardian Security Checks` run on a pull request.
 #
 # WHY MATCHES AND NOT PATHS
 #
@@ -40,6 +44,22 @@
 # warning, because an unknown key is not an error. This file carried
 # `ignored-matches` and `show-secrets` from 2026-09-17 until 2026-11-07, so all
 # six exemptions below were inert for that whole period.
+#
+# WHAT THIS FILE DOES AND DOES NOT REACH
+#
+# It is read by the `ggshield` CLI, so it governs a local or manual
+# `ggshield secret scan` and nothing else. It does not configure the GitGuardian
+# GitHub App: the `GitGuardian Security Checks` run on a pull request is scanned
+# server-side, and its exemptions live in the dashboard. That is why the
+# 2026-11-07 finding had to be resolved there while this file already existed in
+# the repository.
+#
+# Measured 2026-11-07: no workflow runs `ggshield` -- 429 workflow files across
+# laranail/packages and simtabi/packages, plus the 8 reusable workflows in
+# laranail/.github, none of them referencing it. So the entries below currently
+# have no consumer in CI. Fixing the key spelling was still right -- a wrong key
+# is wrong whenever something does read it -- but do not read a green
+# GitGuardian check as evidence that an entry here worked.
 
 version: 2
 
@@ -50,28 +70,36 @@ secret:
     # --- Still on `KEY=value` lines in the current tree, so these are the
     # --- entries actually doing work.
 
-    # `SECRET=plaintext` / `API_TOKEN=plaintext-secret`: the encryption tests
-    # assert the raw value is ABSENT from the file on disk afterwards, which
-    # needs the pre-encryption value to be a known literal.
+    # `SECRET=plaintext` at tests/Feature/EncryptCliTest.php:11. The encryption
+    # test asserts the raw value is ABSENT from the file on disk afterwards,
+    # which needs the pre-encryption value to be a known literal.
     - name: "test fixture: pre-encryption plaintext"
       match: plaintext
-    - name: "test fixture: pre-encryption plaintext (API_TOKEN)"
-      match: plaintext-secret
 
-    # `DB_PASSWORD=oldsecret` in the audit test: the before-value has to be
-    # distinctive to prove it is redacted in the JSON-lines record.
+    # `DB_PASSWORD=oldsecret` at tests/Feature/AuditTest.php:128: the
+    # before-value has to be distinctive to prove it is redacted in the
+    # JSON-lines record.
     - name: "test fixture: audit record old value"
       match: oldsecret
 
-    # --- No longer on assignment lines after the envkit_canary() change, but
-    # --- kept because they remain in the commits already pushed.
+    # --- Not on an assignment line any more, kept because they remain in
+    # --- commits already pushed and a history scan still reaches them.
+    # --- Re-measured 2026-11-07; each line states where the value is now.
 
+    # 3 tracked files, none an assignment line.
     - name: "test fixture: encryption round-trip input"
       match: hunter2
+    # tests/Feature/AuditTest.php, not an assignment line.
     - name: "test fixture: audit record new value"
       match: newsecret
+    # tests/Pest.php -- the envkit_canary() value itself.
     - name: "test fixture: redaction canary"
       match: redaction-canary-not-a-secret
+    # Gone from the tree entirely (removed in #23); survives in 3 commits of
+    # history only. It was grouped above as live until 2026-11-07, which was
+    # wrong -- `API_TOKEN=plaintext-secret` has not existed since #23.
+    - name: "test fixture: pre-encryption plaintext (API_TOKEN), history only"
+      match: plaintext-secret
 
   # A fixture that is genuinely a placeholder should be readable as one. If a
   # finding here is ever anything other than that, fix the code -- do not extend