docs(core): the exemptions have ONE home, so the two gates cannot drift on WHICH modes are exempt

AGENTS.md

@@ -159,9 +159,11 @@ prose only.
   path's content is read from disk, so the working tree decides WHAT they say. The
   index modes that are exempt from it live in ONE committed file,
   `scripts/tracked-files.txt`, which BOTH this control and the retired-knob surface
-  control (`charly/retired_build_selector_test.go`) read — so the two gates cannot
-  drift, and two copies of one rule are two rules (R2). Edit that file, never a
-  reader's copy.
+  control (`charly/retired_build_selector_test.go`) read — so the exemptions have ONE
+  home and the two gates cannot drift on WHICH modes are exempt. Each reader parses
+  that file in its own language, so a copy of the LIST in a reader would be a second
+  list, and two lists drift (R2). That file's own header specifies its grammar; read
+  it there, never copy it here. Edit that file, never a reader's copy.
 - **The control proves it can fail.** `python3 -I scripts/check-pin-verb-scope.py
   --self-test` turns each of the arms RED on its own mutation — a surface that drops
   the scope, a surface whose line is gone, a file that calls the advance a

charly/retired_build_selector_test.go

@@ -22,8 +22,11 @@ package main
 // The sweep reads the repo's TRACKED files, and it derives that set from the INDEX —
 // the same rule `scripts/check-pin-verb-scope.py` applies. The modes that are EXEMPT
 // from that set live in ONE committed file — `scripts/tracked-files.txt` — which BOTH
-// controls read, so the two gates cannot drift (R2): two copies of one rule are two
-// rules. The sweep reads each tracked path's CONTENT from disk, so a change that is
+// controls read, so the exemptions have ONE home and the two gates cannot drift on
+// WHICH modes are exempt (R2). Each reader parses that file in its own language, so a
+// copy of the LIST in a reader would be a second list, and two lists drift. The rule
+// file's own header specifies its grammar; read it there, never copy it here. The
+// sweep reads each tracked path's CONTENT from disk, so a change that is
 // not staged yet is still judged; the index decides WHICH files are in scope, and the
 // working tree decides WHAT they say.
 
@@ -61,7 +64,9 @@ func repoRootFromModule(t *testing.T) string {
 // trackedFilesRule returns the index modes that are EXEMPT from this repository's
 // tracked-file set. They come from ONE committed file — `scripts/tracked-files.txt` —
 // which the pin-advance claim control (`scripts/check-pin-verb-scope.py`) reads too,
-// so the two gates cannot drift (R2): two copies of one rule are two rules.
+// so the exemptions have ONE home and the two gates cannot drift on WHICH modes are
+// exempt (R2). Each reader parses the file in its own language; the rule file's own
+// header specifies its grammar.
 func trackedFilesRule(t *testing.T, root string) map[string]bool {
 	t.Helper()
 	path := filepath.Join(root, "scripts", "tracked-files.txt")
@@ -113,7 +118,8 @@ func requireRepoCheckout(t *testing.T, root string) {
 // trackedRegularFiles returns the repository's tracked REGULAR files, as paths relative
 // to the repo root — derived from the INDEX, never hand-kept. The modes that are exempt
 // from it are the ONE committed rule (`scripts/tracked-files.txt`), shared with the
-// pin-advance claim control, so the two gates cannot drift (R2).
+// pin-advance claim control, so the exemptions have ONE home and the two gates cannot
+// drift on WHICH modes are exempt (R2).
 //
 // Deriving the set from the index also means the sweep's scope is the COMMITTED
 // surface: an untracked scratch file in a developer's working tree is not this repo's

scripts/check-pin-verb-scope.py

@@ -50,8 +50,11 @@
 
 # The ONE rule for what this repository's tracked tree contains: the index modes
 # that are EXEMPT from it. It is a committed FILE, and BOTH readers of the tracked
-# tree read it — this gate and charly/retired_build_selector_test.go — so the two
-# cannot drift (R2): two copies of one rule are two rules.
+# tree read it — this gate and charly/retired_build_selector_test.go — so the
+# exemptions have ONE home and the two gates cannot drift on WHICH modes are exempt
+# (R2). Each reader parses that file in its own language, so a copy of the LIST in
+# a reader would be a second list, and two lists drift. The file's own header
+# specifies the grammar; read it there, never copy it here.
 TRACKED_FILES_RULE = "tracked-files.txt"
 
 # The SCOPE claim: the verb advances EVERY pin this repo declares.
@@ -257,7 +260,8 @@ def extract(lines, idx, kind):
 def tracked_files_rule():
     """The index modes that are EXEMPT from this repository's tracked tree — the
     ONE rule, read from the committed `scripts/tracked-files.txt` that the
-    retired-knob surface control reads too, so the two gates cannot drift (R2)."""
+    retired-knob surface control reads too, so the exemptions have ONE home and the
+    two gates cannot drift on WHICH modes are exempt (R2)."""
     path = os.path.join(os.path.dirname(os.path.abspath(__file__)), TRACKED_FILES_RULE)
     try:
         with open(path, "r", encoding="utf-8") as fh:
@@ -285,7 +289,8 @@ def tracked_files(root):
     """The tracked REGULAR files of a tree — derived from the INDEX, never
     hand-kept. The modes that are exempt from it come from the ONE committed
     rule (`scripts/tracked-files.txt`), which the retired-knob surface control
-    reads too, so the two gates cannot drift (R2)."""
+    reads too, so the exemptions have ONE home and the two gates cannot drift on
+    WHICH modes are exempt (R2)."""
     try:
         raw = subprocess.run(
             ["git", "ls-files", "-s", "-z"],

scripts/tracked-files.txt

@@ -11,8 +11,11 @@
 #
 # THE READERS. `scripts/check-pin-verb-scope.py` (the pin-advance claim control)
 # and `charly/retired_build_selector_test.go` (the retired-knob surface control)
-# BOTH read this file, so the two gates cannot drift. Edit THIS file, never a
-# reader's copy: two copies of one rule are two rules, and they drift.
+# BOTH read this file, so the exemptions have ONE home and the two gates cannot
+# drift on WHICH modes are exempt. Each reader parses this file in its own
+# language, so a copy of the LIST in a reader would be a second list, and two
+# lists drift (R2). The GRAMMAR is specified ONCE, in the WHAT IS EXEMPT header
+# above - never restated in a reader. Edit THIS file, never a reader's copy.
 #
 # The mode numbers are git's own (`git ls-files --stage`): 100644 and 100755 are
 # regular files, 120000 is a symlink, 160000 is a gitlink.