volt: Q139 -- the TOOLS.md drift guard is a fast leg, not a sweep-only cell

tools/selftest_baseline.tsv

@@ -30,5 +30,5 @@ reply_check.py	49	cells
 selftest_sweep.py	49	cells
 served_drift_check.py	25	cells
 tool_map.py	23	cells
-verify.py	59	cells
+verify.py	61	cells
 write_probe.py	15	cells

tools/tool_map.py

@@ -7,7 +7,8 @@ WHY THIS EXISTS
   queue block, in a reply -- and nothing states the whole set: which tool grades
   what, which flags each one actually accepts, which of them the two probe axes
   cover, and which leg of the operator's gate a failure shows up in. The closest
-  thing is `verify.py`'s `LEGS` table, which names ten of them.
+  thing is `verify.py`'s `LEGS` table, which names some of them and never all;
+  a leg count written here would be one more number to drift.
 
   A hand-written map would be a fourth notation of the defect this suite keeps
   grading: prose about the tree, one step from the thing it describes, with no

tools/verify.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""verify.py -- the HOME the index gate did not have: one command, eleven legs,
+"""verify.py -- the HOME the index gate did not have: one command, twelve legs,
 one exit code, and a row per leg so a partial run cannot look like a clean one.
 
 WHY THIS EXISTS
@@ -73,6 +73,16 @@ WHAT IT RUNS -- one row per leg, cheapest first, never in parallel
                   document being written is the document graded; this leg did
                   not exist before 2026-10-22, and every docstring command in
                   the archive was prose until it did
+  tools-map       tools/tool_map.py --repo . --rev WORKTREE --check docs/TOOLS.md
+                  `docs/TOOLS.md` re-derived from this tree and byte-compared:
+                  every cell of the map (a tool's first docstring line, its
+                  `--help` flags, its probe rows, its gate leg) against the
+                  document on disk. The drift cell already lived in
+                  `tool_map.py`'s own selftest, but the only leg that runs a
+                  selftest is `selftest-sweep`, and `--fast` skips it -- so a
+                  docstring edited in a `--fast` tick landed with a stale map
+                  and a green gate (Q138's own residual). This leg is the same
+                  guard at ~6 s, on every run including `--fast`.
   selftest-sweep  tools/selftest_sweep.py
                   every tool's --selftest plus its two read-refusal axes
                   (skip with --fast; the row is still printed and counted)
@@ -178,7 +188,7 @@ TOOLS ARE RESOLVED FROM --repo, NOT FROM THIS FILE'S DIRECTORY
   The path must still be the ROOT: a subdirectory is rc 2 naming the root,
   because widening `--repo` silently would grade a tree nobody named.
 
-`--selftest`          fixture corpus, 59 cells
+`--selftest`          fixture corpus, 61 cells
 """
 
 import argparse
@@ -215,6 +225,10 @@ LEGS = (
     {"key": "doc-commands", "tool": "doc_command_check.py", "slow": False,
      "what": "every command a tool's docstring tells a reader to run: its "
              "flags must be options that tool's --help accepts"},
+    {"key": "tools-map", "tool": "tool_map.py", "slow": False,
+     "what": "re-derive docs/TOOLS.md from this tree and byte-compare it with "
+             "the document on disk -- the same drift guard the sweep runs, at "
+             "~6 s, on every run including --fast (Q138's residual)"},
     {"key": "selftest-sweep", "tool": "selftest_sweep.py", "slow": True,
      "what": "every tool's --selftest and both read-refusal axes"},
     {"key": "write-axis", "tool": "write_probe.py", "slow": False,
@@ -426,6 +440,15 @@ def leg_argv(key, repo, queue, index, checkin_day=None):
         return [sys.executable, os.path.join(repo, "tools",
                                              "doc_command_check.py"),
                 "--repo", repo, "--rev", "WORKTREE", "--fail"]
+    if key == "tools-map":
+        # --repo and the document path both come from the tree being graded;
+        # WORKTREE, not HEAD, for the reason doc-commands gives: the drift this
+        # leg exists to catch is written in the tick that edits a docstring, and
+        # a leg reading HEAD would grade the last commit while that edit sat
+        # unrendered -- the exact blind spot Q138 hit.
+        return [sys.executable, os.path.join(repo, "tools", "tool_map.py"),
+                "--repo", repo, "--rev", "WORKTREE",
+                "--check", os.path.join(repo, "docs", "TOOLS.md")]
     if key == "selftest-sweep":
         return [sys.executable, os.path.join(repo, "tools", "selftest_sweep.py"),
                 "--repo", repo, "--quiet"]
@@ -715,6 +738,7 @@ def _verify(*argv):
 GREEN_ALL = {"checkin_check.py": 0, "path_claim_check.py": 0,
              "reply_check.py": 0, "queue_index.py": 0,
              "queue_append_audit.py": 0, "doc_command_check.py": 0,
+             "tool_map.py": 0,
              "selftest_sweep.py": 0, "write_probe.py": 0,
              "import_resolve_check.py": 0,
              os.path.join("wizard-work", "spark",
@@ -737,12 +761,23 @@ def selftest():
             failures.append("%s\n    got:  %r\n    want: %r" % (label, got, want))
 
     with tempfile.TemporaryDirectory(prefix="verify-selftest-") as td:
-        # 1. ten green stubs -> rc 0
+        # 1. twelve green stubs -> rc 0
         repo = _fixture(os.path.join(td, "c1"), GREEN_ALL)
         rc, out = _verify("--repo", repo)
-        check("1 all eleven legs green -> rc 0", rc, 0)
-        check("1b summary counts the eleven legs", "verify: 11 legs, 11 pass, 0 fault, "
+        check("1 all twelve legs green -> rc 0", rc, 0)
+        check("1b summary counts the twelve legs", "verify: 12 legs, 12 pass, 0 fault, "
               "0 ungradable, 0 skipped" in out, True)
+        # 1c. the drift leg is graded on the same terms as any other: a map that
+        # does not reproduce is a FAULT, and its DRIFT line reaches the row.
+        repo = _fixture(os.path.join(td, "c1c"),
+                        dict(GREEN_ALL, **{"tool_map.py": 1}),
+                        outs={"tool_map.py":
+                              "DRIFT at line 35: document: ten legs\n"})
+        rc, out = _verify("--repo", repo, "--fast")
+        check("1c a stale map under --fast -> rc 1", rc, 1)
+        check("1d the DRIFT line is carried into the row",
+              "tools-map" in out and "DRIFT at line 35" in out
+              and "fault:      tools-map" in out, True)
 
         # 2. a stale index is a FAULT, and its own line reaches the row
         repo = _fixture(os.path.join(td, "c2"),
@@ -797,7 +832,8 @@ def selftest():
         obj = json.load(open(jpath)) if os.path.exists(jpath) else {}
         check("7 --json writes the rows", [r["key"] for r in obj.get("rows", [])],
               ["checkin", "path-claims", "reply-headings", "index-current",
-               "append-audit", "doc-commands", "selftest-sweep", "write-axis",
+               "append-audit", "doc-commands", "tools-map", "selftest-sweep",
+               "write-axis",
                "import-resolve", "closed-artifacts", "open-set"])
         check("7b --json carries the same rc the process returned",
               obj.get("rc"), rc)
@@ -842,7 +878,7 @@ def selftest():
         check("12 skipped leg is its own count in --json",
               obj.get("counts", {}).get("SKIP"), 1)
         check("12b and the skipped leg is not counted as a pass",
-              obj.get("counts", {}).get(PASS), 10)
+              obj.get("counts", {}).get(PASS), 11)
 
         # 13. the detail line must not contradict the verdict: a row graded
         # FAULT beside "0 fatal" is the SILENT failure this gate exists to catch.