xtask: reject implicit system python

docs/RESEARCH_LEDGER.md

@@ -2007,3 +2007,10 @@ RE-863 hook correction: pre-commit/pre-push now require a Nix-store `PYTHON`, pr
 RE-863 final review: targeted xtask dependency-registry test passes, including all five new source→Rust edges and shared transition composition. Both hooks pass shell syntax checks and reject missing PYTHON before invoking any interpreter.
 
 Batch RE-854–863 boundary: the single `cargo xtask test-full --since cedc6d02` run passed after commit ten through the flake shell and its declared Nix Python3.13.15: 1,688 Python tests, 157 Rust tests (assets 10, gameplay 119, xtask 28), 51 deterministic producers, storage policy, 425 documentation files and whitespace checks. No generated report drift; notes amended into task ten. Original assets unchanged. Remaining commit/push hooks use the explicit Nix-store interpreter.
+
+
+## 2026-10-27 — Block remaining implicit system-Python runner entry points
+
+Prompt investigation found the ordinary shell resolves python3 to /usr/bin/python3, while xtask still had a PATH fallback and two Rust integration tests invoked that name directly. The Git hooks were already guarded. The runner and real Python-using tests now require the explicit Nix-store interpreter, rejecting missing/system paths without launching them. Direct analysis-script shebangs still require the documented flake shell. No active Python/xcrun process was observed at inspection; that snapshot cannot attribute an already-dispatched installer prompt.
+
+Validation: all30 xtask tests and the focused storage group (21 Python tests) pass using the flake-declared Nix Python. A real runner invocation with PYTHON unset exits with nix-develop guidance before starting Python. Full suite was not repeated for this focused runner correction.

docs/TESTING.md

@@ -2,7 +2,7 @@
 
 ## Development toolchain
 
-Run analysis and validation inside `nix develop`. The pinned flake declares Python as a development dependency and sets `PYTHON` to its absolute Nix-store executable, which `cargo xtask` uses. Do not use Python from macOS Command Line Tools. For a one-shot run, use `nix develop --command cargo xtask test-group <name>`; the same environment supplies Python for direct analysis scripts and their subprocesses. The shell also supplies Rust, Cargo, Git and pkg-config on macOS and Linux.
+Run analysis and validation inside `nix develop`. The pinned flake declares Python as a development dependency and sets `PYTHON` to its absolute Nix-store executable, which `cargo xtask` and its Python-using Rust integration tests require. Without it, they stop before launching an interpreter; there is no PATH/system fallback. Do not use Python from macOS Command Line Tools. For a one-shot run, use `nix develop --command cargo xtask test-group <name>`; the same environment supplies Python for direct analysis scripts and their subprocesses. The shell also supplies Rust, Cargo, Git and pkg-config on macOS and Linux. Directly executing an analysis script outside this shell can still follow its `env python3` shebang, so run those scripts inside the flake too.
 
 The Rust `xtask` workspace package selects and runs the existing Python research tests and Rust crate tests. It has no third-party Rust dependencies. Python remains necessary for the existing analyzers/tests and a syntax-only AST reader; selection, Git inspection, scheduling, determinism checks and command execution live in Rust.
 

xtask/src/lib.rs

@@ -7,6 +7,52 @@ use std::process::Command;
 type Result<T> = std::result::Result<T, String>;
 type Set = BTreeSet<String>;
 
+fn python_program(value: Option<&str>) -> Result<String> {
+    let value = value.ok_or("PYTHON is unset; run this command inside nix develop")?;
+    let path = Path::new(value);
+    if !value.starts_with("/nix/store/")
+        || !value.ends_with("/bin/python3")
+        || path.components().any(|part| {
+            matches!(
+                part,
+                std::path::Component::ParentDir | std::path::Component::CurDir
+            )
+        })
+    {
+        return Err(
+            "PYTHON must be the flake's absolute Nix-store Python executable; run nix develop"
+                .into(),
+        );
+    }
+    Ok(value.into())
+}
+fn python_runtime() -> Result<String> {
+    python_program(std::env::var("PYTHON").ok().as_deref())
+}
+
+#[cfg(test)]
+mod python_tests {
+    use super::*;
+    #[test]
+    fn missing_system_and_relative_python_are_rejected_without_launching() {
+        assert!(python_program(None).unwrap_err().contains("nix develop"));
+        for value in [
+            "",
+            "python3",
+            "/usr/bin/python3",
+            "/Library/Developer/CommandLineTools/usr/bin/python3",
+            "/nix/store/../../usr/bin/python3",
+        ] {
+            assert!(python_program(Some(value)).is_err(), "{value}");
+        }
+    }
+    #[test]
+    fn explicit_nix_dependency_is_accepted() {
+        let value = "/nix/store/example-python3/bin/python3";
+        assert_eq!(python_program(Some(value)).unwrap(), value);
+    }
+}
+
 #[derive(Default, Debug)]
 pub struct Graph {
     nodes: Set,
@@ -505,7 +551,7 @@ fn execute(root: &Path, g: &Graph, p: &Plan, python: &str, runner: &mut impl Run
 pub fn run(args: Vec<String>) -> Result<()> {
     if args.is_empty() || args.iter().any(|a| matches!(a.as_str(), "--help" | "-h")) {
         println!(
-            "cargo xtask test-changed [--since REV] [--path PATH ...] [--dry-run]\ncargo xtask test-group NAME [--dry-run]\ncargo xtask test-full [--since REV] [--dry-run]\ncargo xtask list-groups\nPYTHON overrides python3. Run from anywhere inside the checkout. Reports regenerate twice before tests."
+            "cargo xtask test-changed [--since REV] [--path PATH ...] [--dry-run]\ncargo xtask test-group NAME [--dry-run]\ncargo xtask test-full [--since REV] [--dry-run]\ncargo xtask list-groups\nPYTHON must come from nix develop; no system-Python fallback. Run from anywhere inside the checkout. Reports regenerate twice before tests."
         );
         return Ok(());
     }
@@ -516,7 +562,7 @@ pub fn run(args: Vec<String>) -> Result<()> {
         )?
         .trim(),
     );
-    let python = std::env::var("PYTHON").unwrap_or_else(|_| "python3".into());
+    let python = python_runtime()?;
     let mode = &args[0];
     let mut index = 1;
     let mut group = None;
@@ -980,7 +1026,7 @@ mod tests {
         let out = capture(
             &t.0,
             &Cmd::new(
-                "python3",
+                &python_runtime().expect("run cargo test inside nix develop"),
                 ["-I".into(), scanner.to_string_lossy().into_owned()],
             ),
         )
@@ -999,7 +1045,14 @@ mod integration_tests {
         let root = Path::new(env!("CARGO_MANIFEST_DIR")).parent().unwrap();
         let mut g =
             Graph::registry(&fs::read_to_string(root.join("xtask/checks.tsv")).unwrap()).unwrap();
-        let output = capture(root, &Cmd::new("python3", ["-I", "xtask/python_graph.py"])).unwrap();
+        let output = capture(
+            root,
+            &Cmd::new(
+                &python_runtime().expect("run cargo test inside nix develop"),
+                ["-I", "xtask/python_graph.py"],
+            ),
+        )
+        .unwrap();
         g.scanner(&output).unwrap();
         assert!(g.warnings.is_empty(), "{:?}", g.warnings);
         let health = plan(