From 6e69d8957f69d169805f524ba45db14c27bf43ed Mon Sep 17 00:00:00 2001
From: Brett Heap <1513478+brettheap@users.noreply.github.com>
Date: Sun, 11 Oct 2026 21:39:06 +0000
Subject: [PATCH 1/3] shape-doctor.py: a validator row that ran the standard's
 TEMPLATE copy prints the `PYTHONPATH` it ran it under in its NEXT, in sh's or
 PowerShell's dialect, so pasting the `manifest`, `pins` or `family` row's
 NEXT prints the validator's own finding and exits with `detail.exit` instead
 of dying on `ModuleNotFoundError: No module named 'repo_shape'` with exit 1,
 a finding's code (#238)

A root with no `scripts/validate-<x>.py` of its own is checked by the
standard's template copy, and the row's NEXT named that template as a bare
command. The template imports `repo_shape` from beside itself, and
`repo_shape.py` is copied INTO a project out of the standard's `scripts/`, so
the doctor's own child ran it only because `run_validator` puts
`<standard>/scripts` on the child's `PYTHONPATH`. The printed line was a
different process from the one whose output the row quoted: pasted from any
directory with no `PYTHONPATH` in the environment it printed a traceback and
exited 1, which is also what a validator exits with for "findings", so
anything keyed on the exit code read a crash as the finding the row had
already reported. A reader whose shell exported a `PYTHONPATH` reaching the
standard never saw it.

The fix is in the one definition #205 split out, not in a row.
`validator_for` now also returns whether the validator is the root's own
copy, and a new `validator_command` spells the line from that, for the
reader's platform, the way `copy_command` and `scaffold_command` already do
(`platform` is passed on, `None` is the host):

  sh          PYTHONPATH=<standard>/scripts python3 <template> --root <root>
  PowerShell  $env:PYTHONPATH = '<standard>\scripts'; python <template> --root <root>

`validator_row` (the `manifest`, `pins` and `family` rows) and
`unloaded_manifest_row` both build their NEXT through it, so there is no
per-row patch. The root's own copy is unchanged byte for byte: it sits beside
its own `repo_shape.py`, and an environment in front of it would send a
project's pinned gate at the standard's `repo_shape.py` instead.

`validator_scripts` names the directory once, for `run_validator`'s `env` and
for the printed line, so the two cannot name different places.

Decisions the issue left open:
- The PowerShell value is quoted whether or not `quote_arg` would leave it
  bare. What follows `=` is a pipeline, so `$env:PYTHONPATH = C:\shape\scripts`
  would RUN the path as a command. `quote_arg` takes a keyword-only `always`
  for that position and nothing else changes, so the doubling of an
  apostrophe stays in the one function that knows it.
- ONE directory, assigned, not spliced: the doctor's child prepends to the
  reader's `PYTHONPATH`; a printed line cannot see it and sets only the path
  the import needs. `PYTHONIOENCODING` and `PYTHONDONTWRITEBYTECODE` are the
  doctor's own, for quoting prose and for writing nothing, and are not
  printed.
- PowerShell's `$env:` is the session's, so the assignment outlives the line.
  That is the dialect's property; undoing it would delete a `PYTHONPATH` the
  reader may have meant to keep.
- The row's reason is untouched: it already says "the standard's <template>".

Tests (tests/test_shape_doctor.py): for a root with no validator of its own
and a gate that fails on a file that still loads (a wrong `topic:`, a zeroed
pin digest, a `Bad Id` family id), the row's NEXT is pasted into `sh -c` from
the filesystem root with `PYTHONPATH` removed and must print the finding, exit
with `detail.exit` and show no traceback; the same line without its
environment is shown to die on the import, so the test can see the defect.
The same for `unloaded_manifest_row` over each manifest breakage and a
holder; from a standard checked out at a path with a space and an apostrophe;
`--json` and the text report carry one line; the root's own copy is asserted
byte for byte in both rows; and the Windows spelling is asserted as text
through the builder with `platform="nt"`, the doctor's own spelling of the
platform, including the apostrophe doubling and the always-quoted value.

Lane: openreposhape-4 (openRepoShape-4)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 shape-doctor.py            | 148 +++++++++++--
 tests/test_shape_doctor.py | 430 +++++++++++++++++++++++++++++++++++++
 2 files changed, 559 insertions(+), 19 deletions(-)

diff --git a/shape-doctor.py b/shape-doctor.py
index 71d07000..54f6e225 100755
--- a/shape-doctor.py
+++ b/shape-doctor.py
@@ -56,7 +56,11 @@
     manifest          the project's own `scripts/validate-manifest.py` when it
                       has one -- it is the pinned copy, and that is the point
                       -- else the standard's template copy, and the row says
-                      which ran
+                      which ran; the template's NEXT line carries the
+                      `PYTHONPATH` the doctor ran it under, because it
+                      imports `repo_shape` from the standard's `scripts/` and
+                      a bare path pasted anywhere else dies on that import
+                      (#238)
     pins              the project's own `scripts/validate-pins.py` likewise:
                       the lockstep invariant, and the shape-copy digests
     manifest kinds    every `kind:`-bearing manifest in the root, against
@@ -528,7 +532,8 @@ def ascii_text(text: str) -> str:
 UNQUOTED_NT = re.compile(r"^[A-Za-z0-9_./:%+=\\-]+$")
 
 
-def quote_arg(value, platform: str | None = None) -> str:
+def quote_arg(value, platform: str | None = None, *,
+              always: bool = False) -> str:
     # A RAW docstring, because the Windows examples below are Windows paths:
     # `C:\Users\...` is a `\U` escape to the interpreter, and a docstring that
     # had to spell a reader's path with doubled backslashes would be a
@@ -606,6 +611,17 @@ def quote_arg(value, platform: str | None = None) -> str:
     and false to the point of it (Copilot, PR #102). `.fullmatch` is what
     actually requires every character to be in the alphabet, not only the
     ones before wherever `$` was willing to stop.
+
+    `always` QUOTES A VALUE THE ALPHABET WOULD LEAVE BARE, and exists for the
+    one position where bare is not a value at all: the right-hand side of a
+    PowerShell assignment. `$env:PYTHONPATH = C:\shape\scripts` is not the
+    string `C:\shape\scripts`, it is an attempt to RUN it, because what
+    follows `=` is a pipeline and a bareword in one is a command name (#238).
+    Every other position this file interpolates into is an argument, where
+    bare is the value; so it is off unless a caller asks, and the quoting
+    itself is still this function's alone -- one place that knows the
+    apostrophe is doubled, rather than a second copy of the rule beside the
+    one that needs it.
     """
     # ASCII first, so the alphabet check and the quoting below it both see
     # what `Row.__init__` will (Copilot, PR #102); see the docstring above.
@@ -614,7 +630,8 @@ def quote_arg(value, platform: str | None = None) -> str:
     # `.fullmatch`, not `.match`: a pattern ending in `$` still matches just
     # before a trailing newline, so `.match` alone would call "Atlas\n" bare
     # (Copilot, PR #102).
-    if (UNQUOTED_NT if windows else UNQUOTED_POSIX).fullmatch(text):
+    if not always and (UNQUOTED_NT if windows else UNQUOTED_POSIX).fullmatch(
+            text):
         return text
     if windows:
         # PowerShell's verbatim string: nothing inside is expanded, and the
@@ -865,6 +882,17 @@ def adopt(self):
 # ---------------------------------------------------------------------------
 
 
+def validator_scripts(shape: Path) -> Path:
+    """Where a TEMPLATE validator finds `repo_shape`: the standard's own
+    `scripts/`, and nowhere beside the template.
+
+    One definition for the two places that have to agree about it:
+    `run_validator` puts it on the doctor's child's `PYTHONPATH`, and
+    `validator_command` puts it in the line a row prints (#238).
+    """
+    return shape / "scripts"
+
+
 def run_validator(ctx: Context, script: Path, args: list[str]) -> tuple:
     """`(exit code, first line worth quoting, whole output)`.
 
@@ -875,10 +903,17 @@ def run_validator(ctx: Context, script: Path, args: list[str]) -> tuple:
     template -- so when this command falls back to the template it must put
     `<shape>/scripts` on the path or the fallback dies on an ImportError that
     says nothing about the project being checked.
+
+    A PASTED COMMAND IS A SECOND PROCESS, AND THIS `env` IS NOT IN IT. What a
+    row prints as its NEXT is run later, by a person, in their own shell --
+    so the `PYTHONPATH` set here reaches the doctor's child and never the
+    reader's, and `validator_command` is what puts the same directory in the
+    printed line (#238). The directory is `validator_scripts`'s for both, so
+    the line and the run cannot name two different places.
     """
     env = dict(os.environ)
     existing = env.get("PYTHONPATH")
-    scripts = str(ctx.shape / "scripts")
+    scripts = str(validator_scripts(ctx.shape))
     env["PYTHONPATH"] = (f"{scripts}{os.pathsep}{existing}" if existing
                          else scripts)
     # UTF-8 whatever the console is: these validators print this repository's
@@ -911,18 +946,89 @@ def run_validator(ctx: Context, script: Path, args: list[str]) -> tuple:
 
 
 def validator_for(ctx: Context, own: str, template: str) -> tuple:
-    """`(the validator a row runs, how the row names it)`: the root's own
-    copy when it has one, else the standard's template copy.
+    """`(the validator a row runs, how the row names it, whether it is the
+    root's own copy)`: the root's own copy when it has one, else the
+    standard's template copy.
 
     One choice, made in one place, because two rows make it: `validator_row`
     runs what this picks, and `unloaded_manifest_row` names it as the next
     command (#205). A root told to run one copy by one row and another by the
     next would be told two different things about one gate.
+
+    THE THIRD VALUE IS WHAT `validator_command` NEEDS to spell the line, and
+    it is returned here, from the one place that made the choice, instead of
+    being re-derived from the path by a caller (#238). It is also the row's
+    `detail.own_copy`.
     """
     own_path = ctx.root / own
     if own_path.is_file():
-        return own_path, f"the project's own {own}"
-    return ctx.shape / template, f"the standard's {template}"
+        return own_path, f"the project's own {own}", True
+    return ctx.shape / template, f"the standard's {template}", False
+
+
+def validator_command(shape: Path, used: Path, own_copy: bool, args: list,
+                      platform: str | None = None) -> str:
+    r"""The line that runs `used` on `args`, spelled for the READER'S shell,
+    and carrying the environment the doctor ran it under (#238).
+
+    A NEXT IS A COMMAND, and a command pasted into the shell it was quoted
+    for, from any directory and with no `PYTHONPATH` in the environment, has
+    to do what its row says: print the validator's own output and exit with
+    the code the row records. The root's OWN copy does -- it sits beside its
+    own `repo_shape.py` and imports it from there -- so that line is the bare
+    interpreter, path and arguments it has always been, byte for byte.
+
+    THE STANDARD'S TEMPLATE COPY DOES NOT. It imports `repo_shape` from beside
+    itself, and `repo_shape.py` is copied INTO a project's `scripts/` out of
+    the standard's `scripts/`, never kept beside the template (`REPO_SHAPE`,
+    `scripts/shape_materialize.py`). The doctor's own child runs it with
+    `<shape>/scripts` on `PYTHONPATH` (`run_validator`); the line a row
+    printed carried only the path, so pasting it died on `ModuleNotFoundError:
+    No module named 'repo_shape'` with exit 1 -- the code a validator uses for
+    "findings", so anything keyed on the exit code read a crash as the finding
+    the row had already reported, and the one command the row hands over to
+    "read its output in full" printed a traceback that named nothing about the
+    project. A reader whose own shell already exported a `PYTHONPATH` that
+    reached the standard never saw it, which is how it went unfound.
+
+    SO THE TEMPLATE'S LINE SETS IT, in the reader's dialect, which is the
+    same two this file already speaks (`quote_arg`, `copy_command`,
+    `scaffold_command`): `PYTHONPATH=<shape>/scripts python3 <template> ...`
+    for `sh`, and `$env:PYTHONPATH = '<shape>\scripts'; python <template> ...`
+    for PowerShell. Both are ONE directory, so this is a plain assignment and
+    not a list: `os.pathsep` is the doctor's child's business, where it
+    PREPENDS to whatever the environment already holds, and a printed line
+    sets the one path it needs rather than splicing into a value it cannot
+    see.
+
+    ONLY `PYTHONPATH`, and not the rest of the child's environment.
+    `PYTHONIOENCODING` and `PYTHONDONTWRITEBYTECODE` exist so the DOCTOR can
+    quote a validator's prose and keep its own promise to write nothing; a
+    reader pasting a line is making their own run, and the import is the only
+    thing that run cannot do without.
+
+    THE POWERSHELL VALUE IS QUOTED WHETHER OR NOT IT NEEDS IT, which is
+    `quote_arg`'s `always`: what follows `=` is a pipeline, so a bare
+    `C:\shape\scripts` would be run as a command and not assigned as a
+    string. The assignment also outlives the line -- `$env:` is the session's
+    -- and that is a property of the dialect, not something this line can
+    undo without deleting a `PYTHONPATH` the reader may have meant to keep.
+
+    `platform` IS PASSED ON, as `copy_command` says at length: one resolved
+    `target` governs the dialect, the interpreter and every quoting, so a
+    Windows line built on a POSIX runner is a Windows line, and both are
+    asserted from either host. `platform=None` is the host, unchanged.
+    """
+    target = os.name if platform is None else platform
+    command = " ".join([python_command(platform), quote_arg(used, target),
+                        *(quote_arg(arg, target) for arg in args)])
+    if own_copy:
+        return command
+    scripts = validator_scripts(shape)
+    if target == "nt":
+        return (f"$env:PYTHONPATH = {quote_arg(scripts, target, always=True)}; "
+                f"{command}")
+    return f"PYTHONPATH={quote_arg(scripts, target)} {command}"
 
 
 def validator_row(ctx: Context, check_id: str, label: str, own: str,
@@ -936,8 +1042,7 @@ def validator_row(ctx: Context, check_id: str, label: str, own: str,
     have". The template copy is the fallback for a root that has lost or never
     had one, and the row names which of the two answered.
     """
-    own_path = ctx.root / own
-    used, which = validator_for(ctx, own, template)
+    used, which, own_copy = validator_for(ctx, own, template)
     if not used.is_file():
         return Row(check_id, label, FINDING,
                    f"neither {own} nor {template} is readable, so the "
@@ -948,7 +1053,7 @@ def validator_row(ctx: Context, check_id: str, label: str, own: str,
                    "the standard; this one is missing that file",
                    {"validator": None})
     code, quoted, _ = run_validator(ctx, used, args)
-    detail = {"validator": used.as_posix(), "own_copy": own_path.is_file(),
+    detail = {"validator": used.as_posix(), "own_copy": own_copy,
               "exit": code}
     if code == 0:
         return Row(check_id, label, OK, f"{which} passes", None, detail)
@@ -958,11 +1063,14 @@ def validator_row(ctx: Context, check_id: str, label: str, own: str,
     # `python3 validate-pins.py in <root>`, which is prose wearing a command's
     # clothes: `in` arrives as an argument and argparse refuses it. Every
     # validator here takes `--root`, so the runnable spelling is the absolute
-    # path and that flag, and it needs no `cd` (Copilot, PR #96).
-    spelled = " ".join(quote_arg(arg) for arg in args)
+    # path and that flag, and it needs no `cd` (Copilot, PR #96). AND IT NEEDS
+    # NO ENVIRONMENT FROM THE READER: where `used` is the standard's template
+    # copy the line carries the `PYTHONPATH` the doctor ran it under, or it
+    # dies on an import and exits with a finding's code (#238).
+    command = validator_command(ctx.shape, used, own_copy, args)
     return Row(check_id, label, FINDING, reason,
-               f"{PYTHON} {quote_arg(used)} {spelled}   # read its output in "
-               "full; it names what it refused", detail)
+               f"{command}   # read its output in full; it names what it "
+               "refused", detail)
 
 
 #: The row that OWNS each kind's manifest, by id: the one that quotes its
@@ -1015,10 +1123,10 @@ def unloaded_manifest_row(ctx: Context, check_id: str, label: str, own: str,
     """
     refusal = ctx.manifest_refusal
     name = ctx.manifest_path.name
-    used, _which = validator_for(ctx, own, template)
+    used, _which, own_copy = validator_for(ctx, own, template)
     reason = f"{name} does not load: {refusal_line(refusal)}"
-    detail = {"validator": used.as_posix(),
-              "own_copy": (ctx.root / own).is_file(), "manifest": name,
+    detail = {"validator": used.as_posix(), "own_copy": own_copy,
+              "manifest": name,
               "refusal": {"code": refusal.code, "detail": refusal.detail}}
     if not used.is_file():
         # Neither copy to name: `validator_row` already says so, for any
@@ -1027,8 +1135,10 @@ def unloaded_manifest_row(ctx: Context, check_id: str, label: str, own: str,
                                 ["--root", str(ctx.root)])
         return Row(check_id, label, FINDING, f"{reason}; {missing.reason}",
                    missing.next_command, {**missing.detail, **detail})
+    command = validator_command(ctx.shape, used, own_copy,
+                                ["--root", ctx.root])
     return Row(check_id, label, FINDING, reason,
-               f"{PYTHON} {quote_arg(used)} --root {quote_arg(ctx.root)}   "
+               f"{command}   "
                f"# the file to fix is {quote_arg(ctx.manifest_path)}, where "
                "the line above says; this refuses it the same way until it "
                "loads. What it should say there -- a merge conflict "
diff --git a/tests/test_shape_doctor.py b/tests/test_shape_doctor.py
index 80363556..8f27c432 100644
--- a/tests/test_shape_doctor.py
+++ b/tests/test_shape_doctor.py
@@ -5174,6 +5174,436 @@ def test_a_drifted_roots_next_command_runs_when_it_is_pasted(
         f"  {said[:400]}")
 
 
+# --- a validator the root does not carry: its NEXT brings the environment ---
+#
+# When a root has no `scripts/validate-<x>.py` of its own, the doctor runs the
+# standard's TEMPLATE copy and prints that file as the NEXT command. The
+# template imports `repo_shape` from beside itself, and `repo_shape.py` is
+# copied INTO a project out of the standard's `scripts/`, so the doctor's own
+# child works only because `run_validator` puts `<standard>/scripts` on its
+# `PYTHONPATH` -- and the line the row printed carried only the path. Pasted,
+# it died on `ModuleNotFoundError: No module named 'repo_shape'` with exit 1,
+# the code a validator uses for a finding (#238).
+#
+# Every other test of a validator's NEXT here runs a root that carries its OWN
+# copy, which sits beside its own `repo_shape.py` -- so none of them could
+# see it, and a `PYTHONPATH` exported by the person running the suite hides
+# it from the ones that paste.
+
+def _wrong_topic(body: bytes) -> bytes:
+    return re.sub(rb"(?m)^topic: .*$", b"topic: xf-project-wrong", body)
+
+
+def _zero_digest(body: bytes) -> bytes:
+    return re.sub(rb'(tree_sha256: ")[0-9a-f]{64}(")',
+                  rb"\g<1>" + b"0" * 64 + rb"\g<2>", body)
+
+
+def _bad_family_id(body: bytes) -> bytes:
+    return re.sub(rb"(?m)^id: .*$", b"id: Bad Id", body)
+
+
+#: The three rows that go through `validator_row`, each made red by one edit
+#: that LEAVES THE FILE LOADING (a manifest that does not load is another row,
+#: `unloaded_manifest_row`, tested below): the validator it runs, the standard's
+#: copy of it, the file the edit goes in, and the one finding that copy prints.
+TEMPLATE_FALLBACK = {
+    "manifest": {
+        "own": "scripts/validate-manifest.py",
+        "template": "templates/assembly-root/scripts/validate-manifest.py",
+        "file": "project.yaml", "edit": _wrong_topic,
+        "finding": "manifest-topic"},
+    "pins": {
+        "own": "scripts/validate-pins.py",
+        "template": "templates/assembly-root/scripts/validate-pins.py",
+        "file": "contracts/spec-pin.yaml", "edit": _zero_digest,
+        "finding": "pin-digest-mismatch"},
+    "family": {
+        "own": "scripts/validate-family.py",
+        "template": "templates/family-root/scripts/validate-family.py",
+        "file": "family.yaml", "edit": _bad_family_id,
+        "finding": "family-id"},
+}
+
+
+def red_root(case: str, project: Path, holder: dict, tmp_path: Path,
+             keep_own: bool = False) -> Path:
+    """A root whose `case` gate is red, with or without its own validator.
+
+    `keep_own=False` is the fixture the issue was filed against: the root's
+    copy of the validator is gone, so the row falls back to the standard's.
+    `keep_own=True` is the same red gate with the root's own copy in place,
+    which is the case that must not change. The holder is COPIED, as every
+    test here that edits one does, so the session's stays intact.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    if case == "family":
+        root = tmp_path / FAMILY_NAME
+        shutil.copytree(holder["root"], root, symlinks=True)
+    else:
+        root = project
+    root = root.resolve()
+    target = root / spec["file"]
+    body = target.read_bytes()
+    edited = spec["edit"](body)
+    assert edited != body, "the edit did not change the file"
+    target.write_bytes(edited)
+    if not keep_own:
+        (root / spec["own"]).unlink()
+    return root
+
+
+def pasted_from_elsewhere(command: str, tmp_path: Path):
+    """The row's NEXT into `sh -c`, exactly as printed, from the filesystem
+    root, with no `PYTHONPATH` in the environment.
+
+    The three things a reader's shell can have that the doctor's child did
+    not: a different working directory (the line names every path absolutely,
+    so it needs none), a different environment (this is the one under test),
+    and the whole line -- trailing `#` comment and all -- rather than an argv
+    the test split. `PYTHONDONTWRITEBYTECODE` is the one thing put back, so
+    that running the standard's validators from the session's `standard`
+    leaves no `__pycache__` in it, as every other paste here does.
+    """
+    env = {name: value for name, value in os.environ.items()
+           if name.upper() != "PYTHONPATH"}
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    return subprocess.run(["sh", "-c", command], cwd=str(Path(tmp_path.anchor)),
+                          capture_output=True, text=True, check=False,
+                          env=env)
+
+
+@WINDOWS_SKIP
+@pytest.mark.skipif(shutil.which("sh") is None, reason="needs sh")
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_a_template_validators_next_command_runs_when_it_is_pasted(
+        standard, project, holder, tmp_path, case):
+    """(a) and (b): the row's NEXT, pasted, is the finding the row reported.
+
+    ONE CLAIM, MADE OF THREE THINGS the doctor's own run already did: the
+    validator's own finding is printed, the exit is the row's `detail.exit`,
+    and there is no traceback. The bare-path spelling made all three false at
+    once -- `ModuleNotFoundError`, exit 1, which is also what a finding exits
+    with, so the exit code alone would have passed. That is why the finding
+    id is asserted in the output and the import error is asserted absent.
+
+    The root's own validator is GONE and the gate is red by a file that still
+    loads, so the row is the one `validator_row` builds for the fallback and
+    `shape-currency` separately calls the missing copy a drift.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = red_root(case, project, holder, tmp_path)
+    result = doctor(standard, root, "--json")
+    row = rows_of(result)[case]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is False, row
+    template = (standard / spec["template"]).resolve()
+    assert Path(row["detail"]["validator"]).resolve() == template, row
+    assert row["detail"]["exit"] == 1, row
+    assert spec["finding"] in row["reason"], row
+
+    pasted = pasted_from_elsewhere(row["next"], tmp_path)
+    whole = pasted.stdout + pasted.stderr
+    assert pasted.returncode == row["detail"]["exit"], whole
+    assert f"FINDING {spec['finding']}" in whole, whole
+    for crash in ("Traceback", "ModuleNotFoundError", "repo_shape"):
+        assert crash not in whole, (crash, whole)
+
+    # AND THE TEST CAN SEE THE DEFECT: the same line without its environment
+    # is the traceback, exit 1, and says nothing about the project.
+    scripts = doctor_module(standard).quote_arg(standard.resolve() / "scripts",
+                                                "posix")
+    assert row["next"].startswith(f"PYTHONPATH={scripts} python3 "), row["next"]
+    bare = pasted_from_elsewhere(
+        row["next"].removeprefix(f"PYTHONPATH={scripts} "), tmp_path)
+    assert bare.returncode == 1, bare.stdout + bare.stderr
+    assert "ModuleNotFoundError: No module named 'repo_shape'" in \
+        bare.stdout + bare.stderr, bare.stdout + bare.stderr
+    assert spec["finding"] not in bare.stdout + bare.stderr
+
+
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_a_template_validators_row_carries_the_same_next_in_text_and_json(
+        standard, project, holder, tmp_path, case):
+    """`--json` and the table print ONE line, and it is the builder's for
+    this host: the interpreter, the standard's template as a path, the
+    environment in the dialect of the platform running -- PowerShell's
+    assignment on Windows, `sh`'s prefix elsewhere.
+
+    NOT SKIPPED ON WINDOWS, unlike the paste above, so the Windows job holds
+    the row to its own dialect even though it cannot run the `sh` line.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = red_root(case, project, holder, tmp_path)
+    row = rows_of(doctor(standard, root, "--json"))[case]
+    module = doctor_module(standard)
+    shape = standard.resolve()
+    expected = module.validator_command(shape, shape / spec["template"],
+                                        False, ["--root", root])
+    assert expected.startswith("$env:PYTHONPATH = " if os.name == "nt"
+                               else "PYTHONPATH="), expected
+    assert row["next"].startswith(expected + "   # "), (expected, row["next"])
+    assert row["next"] in doctor(standard, root).stdout
+    assert row["next"].split("#", 1)[1].strip().startswith(
+        "read its output in full"), row["next"]
+
+
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_a_roots_own_validators_next_command_is_unchanged(
+        standard, project, holder, tmp_path, case):
+    """(3): the root's OWN copy, byte for byte as it has always been.
+
+    That copy sits beside its own `repo_shape.py`, so it needs no
+    environment, and a `PYTHONPATH` in front of it would send the reader's
+    run at the STANDARD's `repo_shape.py` instead -- the gate of a project
+    that holds its own pinned copy, answered by a different one. The whole
+    line is spelled here out of the pieces this file already trusts, rather
+    than read back from the code that builds it.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = red_root(case, project, holder, tmp_path, keep_own=True)
+    row = rows_of(doctor(standard, root, "--json"))[case]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is True, row
+    module = doctor_module(standard)
+    assert row["next"] == (
+        f"{module.PYTHON} {module.quote_arg(root / spec['own'])} --root "
+        f"{module.quote_arg(root)}   # read its output in full; it names "
+        "what it refused"), row["next"]
+    assert "PYTHONPATH" not in row["next"], row["next"]
+    assert_next_runs_the_roots_own(row, root, Path(spec["own"]).name)
+
+
+#: One breakage per kind of root, and the three an assembly root's `project.yaml`
+#: has, for `unloaded_manifest_row`: the manifest is THERE and does not load,
+#: so it is that row's NEXT, not `validator_row`'s, that names the gate.
+UNLOADED = [("project", case) for case in sorted(BREAKAGES)] + \
+    [("family", "tab-indent")]
+
+
+@WINDOWS_SKIP
+@pytest.mark.skipif(shutil.which("sh") is None, reason="needs sh")
+@pytest.mark.parametrize("kind,case", UNLOADED)
+def test_an_unloaded_manifests_template_next_command_runs_when_it_is_pasted(
+        standard, project, holder, tmp_path, kind, case):
+    """`unloaded_manifest_row` names the gate through the same definition.
+
+    A root with no `validate-manifest.py` of its own and a `project.yaml`
+    that does not parse is told to run the standard's copy -- and that line
+    was the bare template path too (#205 chose the file, #238 is what the
+    file needs to run). Pasted, it refuses the file with the validator's exit
+    2 and the loader's own words, the way the root's own copy does in
+    `test_the_manifest_rows_next_command_refuses_the_same_file_the_same_way`.
+    """
+    if kind == "family":
+        root = tmp_path / FAMILY_NAME
+        shutil.copytree(holder["root"], root, symlinks=True)
+        edit, code = FAMILY_BREAKAGES[case]
+        name, own, row_id, script = ("family.yaml", "scripts/validate-family.py",
+                                     "family", "validate-family.py")
+    else:
+        root = project
+        edit, code = BREAKAGES[case]
+        name, own, row_id, script = ("project.yaml",
+                                     "scripts/validate-manifest.py",
+                                     "manifest", "validate-manifest.py")
+    root = root.resolve()
+    (root / own).unlink()
+    path = root / name
+    refusal = break_manifest(path, edit, code)
+    row = rows_of(doctor(standard, root, "--json"))[row_id]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is False, row
+    assert Path(row["detail"]["validator"]).name == script, row
+    assert Path(row["detail"]["validator"]).resolve() != \
+        (root / own).resolve(), row
+    assert row["next"].startswith("PYTHONPATH="), row["next"]
+
+    pasted = pasted_from_elsewhere(row["next"], tmp_path)
+    whole = pasted.stdout + pasted.stderr
+    assert pasted.returncode == 2, whole
+    assert f"REFUSED {refusal.code}: " in whole, whole
+    assert refusal.detail[len(str(path)):] in whole, (refusal.detail, whole)
+    for crash in ("Traceback", "ModuleNotFoundError"):
+        assert crash not in whole, (crash, whole)
+
+
+@pytest.mark.parametrize("kind,case", UNLOADED)
+def test_an_unloaded_manifests_own_copy_next_command_is_unchanged(
+        standard, project, holder, tmp_path, kind, case):
+    """The same row, the root's own copy present: no environment, and the
+    line is what #205 printed -- the interpreter, the root's own validator
+    as a path, `--root` the root, and the comment that names the file to fix.
+    """
+    if kind == "family":
+        root = tmp_path / FAMILY_NAME
+        shutil.copytree(holder["root"], root, symlinks=True)
+        edit, code = FAMILY_BREAKAGES[case]
+        name, own, row_id = ("family.yaml", "scripts/validate-family.py",
+                             "family")
+    else:
+        root = project
+        edit, code = BREAKAGES[case]
+        name, own, row_id = ("project.yaml", "scripts/validate-manifest.py",
+                             "manifest")
+    root = root.resolve()
+    break_manifest(root / name, edit, code)
+    row = rows_of(doctor(standard, root, "--json"))[row_id]
+    assert row["detail"]["own_copy"] is True, row
+    module = doctor_module(standard)
+    assert row["next"].startswith(
+        f"{module.PYTHON} {module.quote_arg(root / own)} --root "
+        f"{module.quote_arg(root)}   # the file to fix is "
+        f"{module.quote_arg(root / name)}, where the line above says; "), \
+        row["next"]
+    assert "PYTHONPATH" not in row["next"], row["next"]
+
+
+#: THE LINE FOR EACH SHELL, whole, as `validator_command` is asked for it.
+#: `quote_arg` is asserted on its own above and `copy_command` and
+#: `scaffold_command` have their own rows; what is new here is the ENVIRONMENT
+#: in front of the interpreter -- an assignment prefix for `sh`, a statement
+#: before it for PowerShell -- and what each does to a path that needs quoting.
+VALIDATOR_TEMPLATE = "templates/assembly-root/scripts/validate-manifest.py"
+VALIDATOR_COMMAND = [
+    # `sh`: `NAME=value command ...`, and a root's own copy has none.
+    ("posix", PurePosixPath("/srv/openRepoShape"), False, PurePosixPath(
+        "/srv/work/Atlas"),
+     "PYTHONPATH=/srv/openRepoShape/scripts python3 "
+     "/srv/openRepoShape/templates/assembly-root/scripts/validate-manifest.py "
+     "--root /srv/work/Atlas"),
+    ("posix", PurePosixPath("/srv/openRepoShape"), True, PurePosixPath(
+        "/srv/work/Atlas"),
+     "python3 /srv/work/Atlas/scripts/validate-manifest.py "
+     "--root /srv/work/Atlas"),
+    # A standard checked out where a space is: both words are quoted whole,
+    # and the assignment's quote closes at the value's end.
+    ("posix", PurePosixPath("/srv/my shape"), False, PurePosixPath(
+        "/srv/work/Atlas"),
+     "PYTHONPATH='/srv/my shape/scripts' python3 "
+     "'/srv/my shape/templates/assembly-root/scripts/validate-manifest.py' "
+     "--root /srv/work/Atlas"),
+    # PowerShell: `$env:NAME = 'value'; command ...`, the value ALWAYS quoted.
+    # The first row is the one a bare `C:\srv\openRepoShape\scripts` would
+    # have got wrong: after `=` it is a command to run, not a string.
+    ("nt", PureWindowsPath(r"C:\srv\openRepoShape"), False, PureWindowsPath(
+        r"C:\work\Atlas"),
+     r"$env:PYTHONPATH = 'C:\srv\openRepoShape\scripts'; python "
+     r"C:\srv\openRepoShape\templates\assembly-root\scripts\validate-manifest.py "
+     r"--root C:\work\Atlas"),
+    ("nt", PureWindowsPath(r"C:\srv\openRepoShape"), True, PureWindowsPath(
+        r"C:\work\Atlas"),
+     r"python C:\work\Atlas\scripts\validate-manifest.py "
+     r"--root C:\work\Atlas"),
+    # An apostrophe is doubled, in the path and in the value.
+    ("nt", PureWindowsPath(r"C:\Users\Jane O'Neill\openRepoShape"), False,
+     PureWindowsPath(r"C:\work\Atlas"),
+     r"$env:PYTHONPATH = 'C:\Users\Jane O''Neill\openRepoShape\scripts'; "
+     r"python 'C:\Users\Jane O''Neill\openRepoShape\templates\assembly-root"
+     r"\scripts\validate-manifest.py' --root C:\work\Atlas"),
+    # And the quoting is the platform's asked for, not the host's: a Windows
+    # path on `sh` is quoted whole, every `\` a literal character.
+    ("posix", PureWindowsPath(r"C:\srv\openRepoShape"), False,
+     PureWindowsPath(r"C:\work\Atlas"),
+     r"PYTHONPATH='C:\srv\openRepoShape\scripts' python3 "
+     r"'C:\srv\openRepoShape\templates\assembly-root\scripts"
+     r"\validate-manifest.py' --root 'C:\work\Atlas'"),
+]
+
+
+@pytest.mark.parametrize("platform,shape,own_copy,root,expected",
+                         VALIDATOR_COMMAND)
+def test_the_validator_line_carries_its_environment_in_the_readers_dialect(
+        platform, shape, own_copy, root, expected):
+    """(c): the Windows spelling, asserted as text from any host.
+
+    No PowerShell runs here, as for the `Copy-Item` rows: the line is held
+    to the exact string a PowerShell reader is meant to paste, which is the
+    contract this file keeps for every dialect it prints.
+    """
+    module = doctor_module(REPO)
+    used = (root / "scripts" / "validate-manifest.py" if own_copy
+            else shape / VALIDATOR_TEMPLATE)
+    assert module.validator_command(shape, used, own_copy,
+                                    ["--root", root], platform) == expected
+
+
+def test_the_posix_validator_line_is_read_back_whole_by_sh_quoting():
+    """A standard at an awkward path arrives as one value, apostrophe and all.
+
+    `shlex.split` is the reader's own shell for the `sh` dialect, as it is
+    for every other line asserted that way here: the first word is the
+    assignment whole, the next the interpreter, the next the template.
+    """
+    module = doctor_module(REPO)
+    shape = PurePosixPath("/srv/Jane O'Neill/open Repo Shape")
+    line = module.validator_command(
+        shape, shape / VALIDATOR_TEMPLATE, False,
+        ["--root", PurePosixPath("/srv/work dir/Atlas")], "posix")
+    assert shlex.split(line) == [
+        "PYTHONPATH=/srv/Jane O'Neill/open Repo Shape/scripts", "python3",
+        f"/srv/Jane O'Neill/open Repo Shape/{VALIDATOR_TEMPLATE}", "--root",
+        "/srv/work dir/Atlas"], line
+
+
+def test_the_validator_line_asked_for_no_platform_is_this_hosts():
+    """`platform=None` is `os.name`, so the line every real run prints is the
+    one the rows above assert, byte for byte, on whichever host runs it."""
+    module = doctor_module(REPO)
+    shape = WINDOWS_SHAPE
+    host = "nt" if os.name == "nt" else "posix"
+    args = ["--root", PureWindowsPath(r"C:\work\Atlas")]
+    template = shape / VALIDATOR_TEMPLATE
+    assert module.validator_command(shape, template, False, args) == \
+        module.validator_command(shape, template, False, args, host)
+    assert module.validator_command(shape, template, True, args) == \
+        module.validator_command(shape, template, True, args, host)
+
+
+def test_the_quoter_can_be_made_to_quote_a_value_it_would_leave_bare():
+    """`always` exists for the right-hand side of a PowerShell assignment, and
+    changes nothing for any caller that does not pass it."""
+    module = doctor_module(REPO)
+    for platform in ("posix", "nt"):
+        assert module.quote_arg("scripts", platform) == "scripts"
+        assert module.quote_arg("scripts", platform, always=True) == \
+            "'scripts'"
+        assert module.quote_arg("it's", platform, always=True) == (
+            "'it''s'" if platform == "nt" else "'it'\\''s'")
+
+
+@WINDOWS_SKIP
+@pytest.mark.skipif(shutil.which("sh") is None, reason="needs sh")
+def test_a_template_validators_next_command_runs_from_an_awkward_standard(
+        standard, project, tmp_path):
+    """The assignment prefix, in front of a path `sh` has to be told about.
+
+    The whole standard is COPIED to a directory with a space and an
+    apostrophe in it and the doctor is run from there, so the line has the
+    awkward path twice: in `PYTHONPATH=...` and in the template's own. An
+    unquoted one is not a line `sh` will parse; a quoted interpreter and an
+    unquoted assignment would be the other half of the same fault.
+    """
+    here = tmp_path / AWKWARD / "openRepoShape"
+    here.parent.mkdir()
+    shutil.copytree(standard, here, symlinks=True)
+    spec = TEMPLATE_FALLBACK["manifest"]
+    root = red_root("manifest", project, {}, tmp_path)
+    row = rows_of(doctor(here, root, "--json"))["manifest"]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is False, row
+    assert Path(row["detail"]["validator"]).resolve() == \
+        (here / spec["template"]).resolve(), row
+    # The apostrophe is closed, escaped and reopened -- in BOTH paths.
+    assert row["next"].count("ct'\\''or") == 2, row["next"]
+    pasted = pasted_from_elsewhere(row["next"], tmp_path)
+    whole = pasted.stdout + pasted.stderr
+    assert pasted.returncode == 1, whole
+    assert f"FINDING {spec['finding']}" in whole, whole
+    for crash in ("Traceback", "ModuleNotFoundError", "unexpected EOF"):
+        assert crash not in whole, (crash, whole)
+
+
 @pytest.fixture
 def curly_project(scaffolded_here, tmp_path) -> Path:
     """The fixture project, at a path with a CURLY apostrophe in it.

From 7851c1f8109ee38f9c1640d425462ab459e1c505 Mon Sep 17 00:00:00 2001
From: Brett Heap <1513478+brettheap@users.noreply.github.com>
Date: Mon, 12 Oct 2026 00:02:05 +0000
Subject: [PATCH 2/3] shape-doctor.py runs a validator under the `PYTHONPATH`
 its NEXT line prints and under no other, so only the standard's TEMPLATE copy
 gets `<shape>/scripts`, and a root's OWN validator that cannot import
 `repo_shape` from beside itself is a FINDING quoting the validator's
 `ModuleNotFoundError` instead of a "passes" its own gate would never give
 (#238)

Review S1 (fix round 1). `run_validator` put `<shape>/scripts` on the
child's `PYTHONPATH` for EVERY validator run, while `validator_command`
printed it only for the standard's template copy. While a root keeps
`scripts/repo_shape.py` beside its own validator the difference is inert,
because the validator inserts its own directory first. A root that lost that
file got a row that quoted what the doctor's child saw -- a pass, or the
validator's own finding -- over a gate that dies on `ModuleNotFoundError`
when the project runs it, and a pasted line that did exactly that.

`validator_scripts(shape, own_copy)` is now the one place the CONDITION is
decided as well as the directory: it answers the standard's `scripts/` for
the template copy and None for the root's own. `validator_row` hands that to
`run_validator` (a new `pythonpath` argument, off unless a caller asks) and
`validator_command` prints from the same answer, each asked with the one
`own_copy` that `validator_for` returned, so there is no second test of it to
drift. The own-copy NEXT line stays byte-identical. The two docstring
sentences the review quotes ("the line and the run cannot name two different
places", "it sits beside its own `repo_shape.py`") are rewritten so each is
true.

Decision the brief left open: the other `run_validator` callers
(`check_naming`, `check_not_a_root_naming` and `check_machine`) now get no
`PYTHONPATH` either. `check_manifest` is not one of them: it goes through
`validator_row` and gets the decision above. The two naming callers run the
standard's own `validate-repository-naming.py`, which inserts its own
directory ahead of its `repo_shape` import. The machine preflight needs
nothing from `repo_shape` at all: `setup-project.py --preflight` returns
before the only `import repo_shape` (deferred) and its module imports are the
standard library's, so it never imports it. So it was inert for all three and
printed nowhere.

Review N1. The PowerShell spelling is kept. Its docstring now says what it
does: the `$env:PYTHONPATH` assignment lasts for the PowerShell session and
REPLACES any `PYTHONPATH` the reader had, which is accepted because the issue
and the plan named this spelling and the effect ends with the session. The
backwards reason ("would delete a `PYTHONPATH` the reader may have meant to
keep") is deleted.

Review N3. A Windows-only test runs each template NEXT line for real in a
fresh `powershell -NoProfile -NonInteractive -Command "<line>; exit
$LASTEXITCODE"` (cwd the filesystem root, `PYTHONPATH` removed, the row's
trailing `#` comment cut first so it cannot swallow the `exit`, output read
as bytes) and asserts the validator's finding and the row's `detail.exit`.
Skipped elsewhere with the reason beside it; it has not been run anywhere
until tests-windows runs it.

Tests: a root with its own validator and no `scripts/repo_shape.py`, for the
manifest, pins and family rows -- (a) with the file edited red, the row is a
FINDING quoting the `ModuleNotFoundError` and its own-copy NEXT pasted into
`sh -c` from `/` with no `PYTHONPATH` exits with `detail.exit`; (b) with a
valid file, the row no longer says the validator passes and agrees with the
project's own gate run directly. Mutation: `PYTHONPATH` put back on the
own-copy run only -- all 6 new tests fail (log mut2.log). The template-copy
tests are unchanged. Replayed onto main d94d155 (after #232 landed), the
targeted run (tests/test_shape_doctor.py, tests/test_shape_advisory.py,
tests/test_cli_reference.py) gives 295 passed, 3 skipped; the 3 are the
Windows-only PowerShell test. Not here: N2, O1-O4.

Lane: openreposhape-4 (openRepoShape-4)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 shape-doctor.py            | 119 +++++++++++++++++---------
 tests/test_shape_doctor.py | 170 +++++++++++++++++++++++++++++++++++++
 2 files changed, 248 insertions(+), 41 deletions(-)

diff --git a/shape-doctor.py b/shape-doctor.py
index 54f6e225..122227e4 100755
--- a/shape-doctor.py
+++ b/shape-doctor.py
@@ -59,8 +59,9 @@
                       which ran; the template's NEXT line carries the
                       `PYTHONPATH` the doctor ran it under, because it
                       imports `repo_shape` from the standard's `scripts/` and
-                      a bare path pasted anywhere else dies on that import
-                      (#238)
+                      a bare path pasted anywhere else dies on that import,
+                      and the project's own copy is run and printed with none,
+                      as its own gate runs it (#238)
     pins              the project's own `scripts/validate-pins.py` likewise:
                       the lockstep invariant, and the shape-copy digests
     manifest kinds    every `kind:`-bearing manifest in the root, against
@@ -882,40 +883,65 @@ def adopt(self):
 # ---------------------------------------------------------------------------
 
 
-def validator_scripts(shape: Path) -> Path:
-    """Where a TEMPLATE validator finds `repo_shape`: the standard's own
-    `scripts/`, and nowhere beside the template.
-
-    One definition for the two places that have to agree about it:
-    `run_validator` puts it on the doctor's child's `PYTHONPATH`, and
-    `validator_command` puts it in the line a row prints (#238).
+def validator_scripts(shape: Path, own_copy: bool) -> Path | None:
+    """The directory a validator run has on `PYTHONPATH`, or None for a run
+    that has none: the standard's own `scripts/` for the standard's TEMPLATE
+    copy, and nothing for the root's OWN copy (#238).
+
+    ONE DEFINITION OF THE DIRECTORY AND OF THE CONDITION, for the two places
+    that have to agree about both. `run_validator` sets what this returns on
+    the doctor's child and `validator_command` prints what it returns in the
+    line a row hands over, and each is asked with the one `own_copy` that
+    `validator_for` made -- so the run and the line apply `PYTHONPATH` under
+    the same condition, and there is no second test of `own_copy` to drift
+    from the first (review S1 on #238).
+
+    THE TEMPLATE'S IS THE STANDARD'S `scripts/`, because that is the only
+    place `repo_shape.py` is: the template has none beside it. THE ROOT'S OWN
+    COPY GETS NOTHING, because it is the project's own gate and the doctor's
+    job is to run it as the project runs it -- as a path, importing
+    `repo_shape` from beside itself. A root that has lost its own
+    `scripts/repo_shape.py` has a gate that cannot import it, and the row
+    must say what that gate says (`ModuleNotFoundError` as a finding), not a
+    "passes" the project's own gate would never give.
     """
-    return shape / "scripts"
+    return None if own_copy else shape / "scripts"
 
 
-def run_validator(ctx: Context, script: Path, args: list[str]) -> tuple:
+def run_validator(ctx: Context, script: Path, args: list[str],
+                  pythonpath: Path | None = None) -> tuple:
     """`(exit code, first line worth quoting, whole output)`.
 
-    THE PYTHONPATH IS THE POINT OF THE `env` BLOCK. A project's own
+    THE PYTHONPATH IS THE POINT OF THE `env` BLOCK, AND IT IS SET ONLY WHEN
+    A CALLER ASKS: `pythonpath` is the directory to put on it, and
+    `validator_row` passes `validator_scripts`'s answer. A project's own
     `scripts/validate-pins.py` sits beside its own copy of `repo_shape.py` and
-    imports it from there. The STANDARD's template copy has no `repo_shape.py`
-    beside it -- that file is copied out of the shape itself, not out of the
-    template -- so when this command falls back to the template it must put
-    `<shape>/scripts` on the path or the fallback dies on an ImportError that
-    says nothing about the project being checked.
+    imports it from there, so it is run with nothing added -- the way the
+    project's own gate runs it. The STANDARD's template copy has no
+    `repo_shape.py` beside it -- that file is copied out of the shape itself,
+    not out of the template -- so when a row falls back to the template it
+    must put `<shape>/scripts` on the path or the fallback dies on an
+    ImportError that says nothing about the project being checked. The
+    standard's own scripts (naming, the machine's preflight) find
+    `repo_shape` themselves and are not given one either.
 
     A PASTED COMMAND IS A SECOND PROCESS, AND THIS `env` IS NOT IN IT. What a
     row prints as its NEXT is run later, by a person, in their own shell --
     so the `PYTHONPATH` set here reaches the doctor's child and never the
     reader's, and `validator_command` is what puts the same directory in the
-    printed line (#238). The directory is `validator_scripts`'s for both, so
-    the line and the run cannot name two different places.
+    printed line (#238). Both are `validator_scripts`'s, asked with the same
+    `own_copy`, so the run and the line apply `PYTHONPATH` under one
+    condition: a template copy gets it in both and the root's own copy gets
+    it in neither. A root's own copy that cannot import `repo_shape` from
+    beside itself therefore fails here as it fails when pasted, and the row
+    reports that failure rather than a pass the pasted line would not give.
     """
     env = dict(os.environ)
-    existing = env.get("PYTHONPATH")
-    scripts = str(validator_scripts(ctx.shape))
-    env["PYTHONPATH"] = (f"{scripts}{os.pathsep}{existing}" if existing
-                         else scripts)
+    if pythonpath is not None:
+        existing = env.get("PYTHONPATH")
+        scripts = str(pythonpath)
+        env["PYTHONPATH"] = (f"{scripts}{os.pathsep}{existing}" if existing
+                             else scripts)
     # UTF-8 whatever the console is: these validators print this repository's
     # own prose, and `ascii_text` flattens it for the report afterwards.
     env["PYTHONIOENCODING"] = "utf-8"
@@ -974,22 +1000,28 @@ def validator_command(shape: Path, used: Path, own_copy: bool, args: list,
     A NEXT IS A COMMAND, and a command pasted into the shell it was quoted
     for, from any directory and with no `PYTHONPATH` in the environment, has
     to do what its row says: print the validator's own output and exit with
-    the code the row records. The root's OWN copy does -- it sits beside its
-    own `repo_shape.py` and imports it from there -- so that line is the bare
-    interpreter, path and arguments it has always been, byte for byte.
+    the code the row records. The root's OWN copy does, for as long as the
+    project keeps its own `repo_shape.py` beside it, as a project copied from
+    the shape does: it imports it from there, so that line is the bare
+    interpreter, path and arguments it has always been, byte for byte. It is
+    the project's own gate and is run, and printed, as the project runs it. A
+    root that has lost that file has a gate that dies on the import, pasted
+    or not, and the row says so as a finding, because the doctor ran it the
+    same way (`validator_scripts`).
 
     THE STANDARD'S TEMPLATE COPY DOES NOT. It imports `repo_shape` from beside
     itself, and `repo_shape.py` is copied INTO a project's `scripts/` out of
     the standard's `scripts/`, never kept beside the template (`REPO_SHAPE`,
     `scripts/shape_materialize.py`). The doctor's own child runs it with
-    `<shape>/scripts` on `PYTHONPATH` (`run_validator`); the line a row
-    printed carried only the path, so pasting it died on `ModuleNotFoundError:
-    No module named 'repo_shape'` with exit 1 -- the code a validator uses for
-    "findings", so anything keyed on the exit code read a crash as the finding
-    the row had already reported, and the one command the row hands over to
-    "read its output in full" printed a traceback that named nothing about the
-    project. A reader whose own shell already exported a `PYTHONPATH` that
-    reached the standard never saw it, which is how it went unfound.
+    `<shape>/scripts` on `PYTHONPATH` (`run_validator`, through
+    `validator_scripts`); the line a row printed carried only the path, so
+    pasting it died on `ModuleNotFoundError: No module named 'repo_shape'`
+    with exit 1 -- the code a validator uses for "findings", so anything keyed
+    on the exit code read a crash as the finding the row had already
+    reported, and the one command the row hands over to "read its output in
+    full" printed a traceback that named nothing about the project. A reader
+    whose own shell already exported a `PYTHONPATH` that reached the standard
+    never saw it, which is how it went unfound.
 
     SO THE TEMPLATE'S LINE SETS IT, in the reader's dialect, which is the
     same two this file already speaks (`quote_arg`, `copy_command`,
@@ -1010,9 +1042,12 @@ def validator_command(shape: Path, used: Path, own_copy: bool, args: list,
     THE POWERSHELL VALUE IS QUOTED WHETHER OR NOT IT NEEDS IT, which is
     `quote_arg`'s `always`: what follows `=` is a pipeline, so a bare
     `C:\shape\scripts` would be run as a command and not assigned as a
-    string. The assignment also outlives the line -- `$env:` is the session's
-    -- and that is a property of the dialect, not something this line can
-    undo without deleting a `PYTHONPATH` the reader may have meant to keep.
+    string. THE ASSIGNMENT LASTS FOR THE POWERSHELL SESSION, not for the one
+    command, and it REPLACES any `PYTHONPATH` the reader had: `sh`'s prefix
+    applies to one command and leaves the reader's environment alone, and
+    this does not. That is accepted: the issue and the plan for this change
+    named this spelling, `$env:` is PowerShell's idiom, and the effect ends
+    with the session (review N1 on #238).
 
     `platform` IS PASSED ON, as `copy_command` says at length: one resolved
     `target` governs the dialect, the interpreter and every quoting, so a
@@ -1022,9 +1057,9 @@ def validator_command(shape: Path, used: Path, own_copy: bool, args: list,
     target = os.name if platform is None else platform
     command = " ".join([python_command(platform), quote_arg(used, target),
                         *(quote_arg(arg, target) for arg in args)])
-    if own_copy:
+    scripts = validator_scripts(shape, own_copy)
+    if scripts is None:
         return command
-    scripts = validator_scripts(shape)
     if target == "nt":
         return (f"$env:PYTHONPATH = {quote_arg(scripts, target, always=True)}; "
                 f"{command}")
@@ -1052,7 +1087,8 @@ def validator_row(ctx: Context, check_id: str, label: str, own: str,
                    f"{quote_arg(ctx.root)}   # from a complete checkout of "
                    "the standard; this one is missing that file",
                    {"validator": None})
-    code, quoted, _ = run_validator(ctx, used, args)
+    code, quoted, _ = run_validator(ctx, used, args,
+                                    validator_scripts(ctx.shape, own_copy))
     detail = {"validator": used.as_posix(), "own_copy": own_copy,
               "exit": code}
     if code == 0:
@@ -1066,7 +1102,8 @@ def validator_row(ctx: Context, check_id: str, label: str, own: str,
     # path and that flag, and it needs no `cd` (Copilot, PR #96). AND IT NEEDS
     # NO ENVIRONMENT FROM THE READER: where `used` is the standard's template
     # copy the line carries the `PYTHONPATH` the doctor ran it under, or it
-    # dies on an import and exits with a finding's code (#238).
+    # dies on an import and exits with a finding's code (#238); the root's own
+    # copy was run under none, and its line carries none.
     command = validator_command(ctx.shape, used, own_copy, args)
     return Row(check_id, label, FINDING, reason,
                f"{command}   # read its output in full; it names what it "
diff --git a/tests/test_shape_doctor.py b/tests/test_shape_doctor.py
index 8f27c432..ed390940 100644
--- a/tests/test_shape_doctor.py
+++ b/tests/test_shape_doctor.py
@@ -5322,6 +5322,60 @@ def test_a_template_validators_next_command_runs_when_it_is_pasted(
     assert spec["finding"] not in bare.stdout + bare.stderr
 
 
+#: SKIPPED EVERYWHERE BUT WINDOWS, with the reason beside it: the `$env:` line
+#: is only the one the doctor PRINTS on a Windows host (`validator_command`
+#: asks `os.name`), and only a Windows runner carries `powershell.exe` to run
+#: it. The dialect is held as text from every host by
+#: `VALIDATOR_COMMAND` below; this is the one test that RUNS it (review N3).
+@pytest.mark.skipif(os.name != "nt",
+                    reason="the PowerShell line is printed, and powershell.exe "
+                           "exists, only on a Windows host")
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_a_template_validators_next_runs_when_pasted_into_powershell(
+        standard, project, holder, tmp_path, case):
+    """The `$env:` line, run for real in a FRESH `powershell`, is the finding.
+
+    The same three claims as the `sh` paste above: the validator's own
+    finding is printed, the exit is the row's `detail.exit`, and no
+    `ModuleNotFoundError` -- from the filesystem root and with no
+    `PYTHONPATH` in the environment, so the only `repo_shape` this run can
+    find is the one the line itself put on the path.
+
+    TWO THINGS ABOUT `-Command`. A native command's non-zero exit is
+    `$LASTEXITCODE`, and `-Command` ends the session with 1 whatever it was,
+    so `; exit $LASTEXITCODE` is appended -- to the COMMAND, with the row's
+    trailing `   # ...` comment cut off first, because PowerShell reads a
+    comment to the end of the line and would swallow the `exit` with it. And
+    the output is read as BYTES and decoded here as UTF-8 with replacement,
+    on purpose: the finding id this asserts is ASCII, and what the console's
+    code page does to anything else is not under test. Nothing is fed to
+    stdin (`subprocess.DEVNULL`), so there is no path to encode.
+
+    NOT RUN ON THE WRITER'S WORKSTATION, which has no PowerShell: the pull
+    request's `tests-windows` job is this test's first run.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = red_root(case, project, holder, tmp_path)
+    row = rows_of(doctor(standard, root, "--json"))[case]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is False, row
+    assert row["next"].startswith("$env:PYTHONPATH = '"), row["next"]
+    line = row["next"].split("   # ", 1)[0]
+    env = {name: value for name, value in os.environ.items()
+           if name.upper() != "PYTHONPATH"}
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    pasted = subprocess.run(
+        ["powershell", "-NoProfile", "-NonInteractive", "-Command",
+         f"{line}; exit $LASTEXITCODE"],
+        cwd=str(Path(tmp_path.anchor)), capture_output=True,
+        stdin=subprocess.DEVNULL, check=False, env=env)
+    whole = (pasted.stdout + pasted.stderr).decode("utf-8", errors="replace")
+    assert pasted.returncode == row["detail"]["exit"], whole
+    assert f"FINDING {spec['finding']}" in whole, whole
+    for crash in ("Traceback", "ModuleNotFoundError", "repo_shape"):
+        assert crash not in whole, (crash, whole)
+
+
 @pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
 def test_a_template_validators_row_carries_the_same_next_in_text_and_json(
         standard, project, holder, tmp_path, case):
@@ -5374,6 +5428,122 @@ def test_a_roots_own_validators_next_command_is_unchanged(
     assert_next_runs_the_roots_own(row, root, Path(spec["own"]).name)
 
 
+# --- a root's OWN validator is run, and printed, as its own gate runs it ----
+#
+# The template's `PYTHONPATH` is the doctor's to give, and only to the copy
+# that has no `repo_shape.py` beside it. A root that keeps its OWN validator
+# and has lost its own `scripts/repo_shape.py` has a gate that cannot import
+# it: the doctor must run that gate the way the project does, so the row says
+# what the gate says, and the line it prints says the same thing when pasted.
+# Run under the standard's `PYTHONPATH` instead, the row answered "passes" or
+# quoted the validator's own finding, and the pasted line died on
+# `ModuleNotFoundError` -- the #238 symptom, with `own_copy: true` (review S1).
+
+def root_without_its_repo_shape(case: str, project: Path, holder: dict,
+                                tmp_path: Path, red: bool) -> Path:
+    """A root with its OWN `case` validator and no `scripts/repo_shape.py`.
+
+    `red=True` is the gate made red by the file edit `TEMPLATE_FALLBACK` names
+    for the case, which still loads; `red=False` leaves the manifest valid, so
+    the only thing wrong with the root is the file it lost. The holder is
+    COPIED, as everywhere here, so the session's stays intact.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    if red:
+        root = red_root(case, project, holder, tmp_path, keep_own=True)
+    elif case == "family":
+        root = tmp_path / FAMILY_NAME
+        shutil.copytree(holder["root"], root, symlinks=True)
+        root = root.resolve()
+    else:
+        root = project.resolve()
+    assert (root / spec["own"]).is_file(), spec["own"]
+    gone = root / "scripts" / "repo_shape.py"
+    assert gone.is_file(), gone
+    gone.unlink()
+    return root
+
+
+def doctor_with_no_pythonpath(standard: Path, root: Path):
+    """`rows_of` this root, from a doctor whose environment has NO
+    `PYTHONPATH`: one the person running the suite exported would reach the
+    root's own validator through the child's inherited environment and hide
+    the very import this is asking about. An empty value is no entry to
+    Python, and `run_script` can set a variable but not remove one."""
+    return rows_of(run_script(standard / DOCTOR, "--root", str(root), "--json",
+                              env={"PYTHONPATH": ""}))
+
+
+@WINDOWS_SKIP
+@pytest.mark.skipif(shutil.which("sh") is None, reason="needs sh")
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_an_own_validator_without_repo_shape_is_a_finding_the_paste_agrees(
+        standard, project, holder, tmp_path, case):
+    """(a): the row quotes the ImportError, and the own-copy NEXT, pasted from
+    `/` with no `PYTHONPATH`, dies on that same import with the row's exit.
+
+    THE RUN AND THE LINE ARE ONE PROCESS FOR THIS COPY: neither has a
+    `PYTHONPATH` the root's own validator did not already have, so what the
+    row quoted is what the reader gets. The finding the wrong file would have
+    produced (`manifest-topic`, ...) is in NEITHER, because neither run got as
+    far as reading it -- which is what separates this from a validator that
+    ran and was red.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = root_without_its_repo_shape(case, project, holder, tmp_path,
+                                       red=True)
+    row = doctor_with_no_pythonpath(standard, root)[case]
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is True, row
+    assert row["detail"]["exit"] == 1, row
+    assert "ModuleNotFoundError: No module named 'repo_shape'" in \
+        row["reason"], row
+    assert spec["finding"] not in row["reason"], row
+    # The own copy's line is what it has always been: no environment.
+    assert "PYTHONPATH" not in row["next"], row["next"]
+    assert_next_runs_the_roots_own(row, root, Path(spec["own"]).name)
+
+    pasted = pasted_from_elsewhere(row["next"], tmp_path)
+    whole = pasted.stdout + pasted.stderr
+    assert pasted.returncode == row["detail"]["exit"], whole
+    assert "ModuleNotFoundError: No module named 'repo_shape'" in whole, whole
+    assert spec["finding"] not in whole, whole
+
+
+@pytest.mark.parametrize("case", sorted(TEMPLATE_FALLBACK))
+def test_an_own_validator_without_repo_shape_does_not_pass(
+        standard, project, holder, tmp_path, case):
+    """(b): a VALID manifest, the same lost file -- and no "passes".
+
+    The row used to say `the project's own scripts/validate-manifest.py
+    passes` over a gate that exits 1 on `ModuleNotFoundError` when the project
+    runs it. It is now the gate's own failure, and the gate is run here
+    directly to say so: the row and the project's own command agree on the
+    exit code and on the line, not only on the absence of a pass.
+    """
+    spec = TEMPLATE_FALLBACK[case]
+    root = root_without_its_repo_shape(case, project, holder, tmp_path,
+                                       red=False)
+    row = doctor_with_no_pythonpath(standard, root)[case]
+    assert row["status"] != "ok", row
+    assert "passes" not in row["reason"], row
+    assert row["status"] == "FINDING", row
+    assert row["detail"]["own_copy"] is True, row
+    assert "ModuleNotFoundError: No module named 'repo_shape'" in \
+        row["reason"], row
+
+    env = {name: value for name, value in os.environ.items()
+           if name.upper() != "PYTHONPATH"}
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    gate = subprocess.run(
+        [sys.executable, str(root / spec["own"]), "--root", str(root)],
+        cwd=str(root), capture_output=True, encoding="utf-8",
+        errors="replace", stdin=subprocess.DEVNULL, check=False, env=env)
+    assert gate.returncode == row["detail"]["exit"], gate.stdout + gate.stderr
+    assert "ModuleNotFoundError: No module named 'repo_shape'" in \
+        gate.stdout + gate.stderr
+
+
 #: One breakage per kind of root, and the three an assembly root's `project.yaml`
 #: has, for `unloaded_manifest_row`: the manifest is THERE and does not load,
 #: so it is that row's NEXT, not `validator_row`'s, that names the gate.

From 290a4c1799ebaf65138d6f8dd2d7a261e7ef5ca8 Mon Sep 17 00:00:00 2001
From: Brett Heap <1513478+brettheap@users.noreply.github.com>
Date: Sun, 11 Oct 2026 23:56:12 +0000
Subject: [PATCH 3/3] shape-doctor.py: `run_validator`'s docstring says the
 machine's preflight needs nothing from `repo_shape` and never imports it,
 instead of that it "finds `repo_shape` itself", so the note on which of the
 standard's own scripts get no `PYTHONPATH` is true of the preflight as well
 as of the naming script (#238)

Re-check N3 on the fix round. The sentence said "The standard's own scripts
(naming, the machine's preflight) find `repo_shape` themselves". That is
true of `validate-repository-naming.py`, which inserts its own directory
ahead of its `repo_shape` import. It is not true of `setup-project.py
--preflight`: that returns before the only `import repo_shape` (deferred) and
its module imports are the standard library's, so it finds nothing because
it looks for nothing. A reader taking the old wording would think the
preflight needed `repo_shape` on the path and would restore a `PYTHONPATH` it
has no use for.

Docstring only; no code, no test and no `--help` text changes.

Lane: openreposhape-4 (openRepoShape-4)
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 shape-doctor.py | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/shape-doctor.py b/shape-doctor.py
index 122227e4..a7648923 100755
--- a/shape-doctor.py
+++ b/shape-doctor.py
@@ -922,8 +922,10 @@ def run_validator(ctx: Context, script: Path, args: list[str],
     not out of the template -- so when a row falls back to the template it
     must put `<shape>/scripts` on the path or the fallback dies on an
     ImportError that says nothing about the project being checked. The
-    standard's own scripts (naming, the machine's preflight) find
-    `repo_shape` themselves and are not given one either.
+    standard's own scripts (naming, the machine's preflight) are not given
+    one either: the naming script inserts its own directory ahead of its
+    `repo_shape` import, and the machine's preflight needs nothing from
+    `repo_shape` at all and never imports it (#238).
 
     A PASTED COMMAND IS A SECOND PROCESS, AND THIS `env` IS NOT IN IT. What a
     row prints as its NEXT is run later, by a person, in their own shell --