py-wlcli 0.8.0__py3-none-any.whl

wl_cli/commands/gate/gate_command.py

@@ -0,0 +1,862 @@
+"""``wl gate`` - the single canonical local quality gate.
+
+Before the chain starts, a step-0 preflight (see :mod:`.preflight`) checks that
+the subjects this chain is about to execute are actually available -- the
+executables PATH will resolve for it, and the plugins inside the interpreter its
+test step will use. If not, the gate fails fast with a named, actionable error
+and never enters the chain: its red can then only ever mean "your change is
+broken", never "this machine is missing packages".
+
+Two failure modes are kept apart (review N1). An *environment* gap -- a subject
+preflight cannot find, or an executable that will not start at all -- exits
+:data:`~.preflight.EXIT_ENV_MISSING` (78) and never produces a step line. A step
+that *ran and was then killed by a signal* is a signalled step, not an
+environment gap, and exits ``128 + signum`` instead: the step's own death can
+well be caused by the change under test (an oversized suite OOM-killing its
+runner), so it must not be read as "go fix the machine".
+
+The two are told apart by :attr:`SubprocessResult.launch_error`, never by the
+sign of the exit code: ``subprocess`` reports a signalled child as ``-signum``,
+so SIGHUP (``-1``) would otherwise be indistinguishable from the launch-failure
+sentinel and would be mislabelled as an environment gap (review F1).
+
+Runs the repo's full local quality chain sequentially, stopping at the first
+failure:
+
+1. ``ruff check`` (lint, excluding vendored assets)
+2. ``mypy`` over ``src/`` (the repo's own mypy contract and config)
+3. ``wl test -s --no-cache`` (the repo's pytest runner, which stops at the first
+   failure -- and never reuses a cached result: a cache hit did not exercise the
+   tree under test, so it is not a pass, #193). Its freshness verdict is read
+   from the run's structured evidence file (``--evidence-json``), never parsed
+   out of stdout (#212, ADR-0010)
+4. ``ruff format --check`` (format, excluding vendored assets)
+5. ``pre-commit run --all-files`` (the managed hook suite in
+   ``.wl/.pre-commit-config.yaml``, #193)
+
+The command is a thin orchestrator: it does not reimplement any check. The
+ruff/mypy command lines come from :class:`LintExecutor`, pytest is delegated to
+the existing ``wl test`` subcommand, the hook suite is judged through
+:class:`~wl_cli.utils.pre_commit.PreCommitRun`, and every step runs through the
+shared :class:`SubprocessExecutor`.
+
+Every leg runs in the deploy root, resolved **once** into a :class:`GateChain`
+(see :meth:`GateChain.resolve`); the judging preflight and each executing step
+then read that one value, so the two can never disagree about where the chain
+runs (issue #110). The mypy leg is the one exception: a monorepo whose deploy
+root has no ``src/`` would otherwise be red forever, so that leg alone moves to
+the project root, and only :meth:`GateChain.resolve` decides that -- the anchor
+is derived once, not re-derived per leg (see :func:`resolve_mypy_anchor`).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import click
+
+from ...utils.pre_commit import PreCommitRun
+from ...utils.root import Root, RootKind
+from ...utils.root_fallback import current_root
+from ...utils.run_evidence import TestRunEvidence
+from ...utils.subprocess_utils import SubprocessExecutor, SubprocessResult
+from ..lint.lint_executor import LintExecutor
+from ..lint.mypy_config import mypy_config_file
+from .preflight import (
+    EXIT_ENV_MISSING,
+    PreflightReport,
+    render_env_error,
+    render_launch_error,
+    render_signal_error,
+    run_preflight,
+    signal_exit_code,
+)
+
+
+@dataclass(frozen=True)
+class GateStep:
+    """One named check in the gate chain.
+
+    *cwd* is where this one step runs -- an explicit path for **every** step,
+    never a ``None`` "use the chain root" convention. The chain root is resolved
+    once into a :class:`GateChain` and written onto each step by
+    :meth:`GateCommand.build_steps`, so a step's own record says where it runs
+    and no later reader has to agree with a *separate* variable about what
+    ``None`` meant.
+    """
+
+    name: str
+    command: list[str]
+    cwd: Path
+    probe_interpreter: bool = False
+    """True on the one step whose interpreter the step-0 preflight must probe.
+
+    The interpreter the chain's test runner will use is decided by the directory
+    that runner is launched in, so preflight reads *this* step's ``cwd`` -- the
+    very field :meth:`GateCommand.execute` hands the executor. The judged root
+    and the executed root are therefore the same field, not two values kept in
+    step by hand (issue #110).
+    """
+
+    capture: bool = False
+    """Whether the executor must capture this step's output instead of streaming it.
+
+    The pre-commit leg's *stdout* carries its verdict -- the hook blocks that
+    :class:`~wl_cli.utils.pre_commit.PreCommitRun` judges -- so it is captured.
+    The test leg keeps capture as well, so a long run is replayed as one block
+    after the step instead of interleaving with the ``[i/n]`` progress lines;
+    its verdict, however, is no longer read from stdout: it comes from the
+    structured evidence file named by :attr:`evidence_path` (#212, ADR-0010).
+    Every other leg streams its output live.
+    """
+
+    reject_cached_results: bool = False
+    """True on the test leg: a successful run that still reused cached results is
+    not a pass.
+
+    ``--no-cache`` is what keeps the leg fresh; this flag is the *verdict* that
+    makes the guarantee executable rather than aspirational. It is judged from
+    the run's structured evidence (:attr:`evidence_path`): ``cache_hits > 0``
+    is red even when the step exited 0, because a cache hit tested an older
+    tree and "all checks passed" after one would be a false green (#193,
+    #212). The evidence's ``no_cache_requested`` fact only chooses the wording
+    -- the runner ignoring its flag vs. the gate failing to pass it.
+    """
+
+    evidence_path: Path | None = None
+    """Where the test leg writes its structured run evidence (#212, ADR-0010).
+
+    :meth:`GateCommand.execute` creates this temporary path and passes it to
+    :meth:`GateCommand.build_steps`, which hands it to ``wl test`` as
+    ``--evidence-json``. ``execute`` reads it for the verdict and removes it in
+    a ``finally`` -- so one run's evidence can never be read by the next. A
+    missing, corrupt or unknown-version file is red, named by path: there is
+    deliberately no stdout fallback. Building the steps alone creates no file
+    (review M1): the path is an *input* here, never a side effect.
+    """
+
+    managed_config: Path | None = None
+    """Set on the pre-commit step: the managed config the run is judged against.
+
+    The step is *skipped* (never failed) when this file is absent, so a checkout
+    that was never ``wl init``-ed does not get a phantom red; the skip is a
+    visible ``- skipped`` line, never silence. When it exists it is passed to
+    ``pre-commit`` as ``--config``, so the run judges exactly the hooks wl
+    deploys -- not whatever ``.pre-commit-config.yaml`` happens to sit in the
+    user's directory.
+    """
+
+    @property
+    def is_skipped(self) -> bool:
+        """True when this step declares a managed config that is not there.
+
+        The **one** answer to "will this step run?", read by both readers that
+        must agree: :meth:`GateCommand.execute` (which prints the skip and moves
+        on) and :func:`~wl_cli.commands.gate.preflight.requirements_for` (which
+        must not demand the executable of a step that will never be launched).
+        Before rv193 those were two separate judgements, so a repo with no
+        managed hooks still had ``pre-commit`` listed as a required subject and
+        the gate exited 78 over a leg it was going to skip.
+        """
+        return self.managed_config is not None and not _is_file(self.managed_config)
+
+
+#: How :class:`GateCommand` obtains its step-0 verdict. The default is the real
+#: probe; tests inject a stub so the orchestration can be exercised without
+#: reaching the machine (and without monkey-patching a module global).
+PreflightRunner = Callable[[Sequence[GateStep]], PreflightReport]
+
+
+@dataclass(frozen=True)
+class GateChain:
+    """The roots one ``wl gate`` run is anchored on -- resolved once.
+
+    ``root`` is the **chain root**: the deploy root every regular step runs in.
+    ``mypy_root`` is where the mypy leg alone runs -- equal to ``root`` in the
+    regular layout, the project root in the monorepo fallback -- and
+    ``mypy_notice`` is the one line explaining a fallback that happened. Both
+    roots are explicit :class:`Root` values, so there is no bare path for a
+    later reader to re-resolve and no ``None`` for it to interpret.
+
+    :meth:`resolve` is the **only** place a gate root is computed. The judging
+    preflight and every executing step then read this one value, so "which root
+    the chain uses" cannot drift between them -- the drift that once let
+    preflight judge one interpreter while ``wl test`` ran under another (#110),
+    and the reason the mypy anchor used to be derived twice.
+    """
+
+    root: Root
+    mypy_root: Root
+    mypy_notice: str | None = None
+
+    @classmethod
+    def resolve(cls) -> GateChain:
+        """Resolve the chain root and the mypy anchor for the invocation CWD.
+
+        The deploy root comes from the one fallback policy (#160): ``wl gate``
+        is a single-root consumer, so it never builds a ``RootContext``.
+        """
+        root = current_root(RootKind.DEPLOY)
+        mypy_root, notice = resolve_mypy_anchor(root)
+        return cls(root=root, mypy_root=mypy_root, mypy_notice=notice)
+
+
+def resolve_mypy_anchor(deploy_root: Root) -> tuple[Root, str | None]:
+    """The root the mypy leg anchors to, plus the notice if it is not *deploy_root*.
+
+    Every leg of the chain runs in the deploy root -- the git work-tree root,
+    where the repo's ``.wl`` (its ``mypy.ini`` baseline) and its ``src/``
+    contract live, and the directory CI runs the same commands from. The mypy
+    leg alone may move, and only when staying put would make the gate
+    permanently red for a reason the change cannot fix: a monorepo whose git
+    work-tree root is a bare container (no ``src/``, no ``.wl``) while each
+    package carries its own. ``mypy --config-file <vendored> src/`` there can
+    only ever report ``src: Cannot read file`` (exit 2) -- a red that never
+    clears, whatever the code, and one that says *less* than the pre-#95 signal
+    did (exit 1 pointing at a real type error inside the package).
+
+    So when the deploy root has no ``src/`` to check, the leg anchors at the
+    project root (``current_root(RootKind.PROJECT)``, the one fallback policy) --
+    the package the user is actually in -- and the returned notice says why and
+    where. The fallback
+    moves the root, never the contract: the scope stays ``src/`` and nothing
+    else, so it can never widen onto directories the change has nothing to do
+    with (review F0). When the project root *is* the deploy root (no ``src/``
+    anywhere) there is nothing to fall back to: the root is returned unchanged
+    and no notice is printed, so the leg keeps failing on its own terms exactly
+    as it did before this fallback existed.
+
+    This is the single derivation point for the anchor: :meth:`GateChain.resolve`
+    calls it once and both the mypy leg's command and the notices read the value
+    it stored, so the leg is never anchored at one root while it is *judged*
+    against another.
+
+    #193 adds the mirror-image case to the one above. When the deploy root *does*
+    carry ``src/`` but the invocation's project root is a **strict subdirectory**
+    of it that carries its own ``src/``, the deploy root's ``src/`` is the wrong
+    tree: in a monorepo whose git root has a (clean) ``src/`` and whose package
+    ``packages/pkgA`` has the type error, staying put judged ``mono2/src`` and
+    reported "all checks passed" over code the user never touched -- a false
+    green with no hint at all (issue #193, evidence 3). The leg therefore anchors
+    at that nested project root, and the notice says so and names both roots.
+
+    Only a *strict subdirectory* moves the anchor. A project root that is the
+    deploy root itself (the regular layout) or an **ancestor** of it (a workspace
+    ``.wl`` above a member repo) is not the package the user is in, and moving
+    there is exactly the #95/#96 regression these legs were fixed to stop.
+    """
+    project_root = current_root(RootKind.PROJECT)
+
+    if _has_src(deploy_root):
+        # Deploy root can honour the ``src/`` contract, so the only reason to
+        # move is a *nested* project that is a better anchor for this run.
+        if _is_strict_subdirectory(project_root.path, deploy_root.path) and _has_src(
+            project_root
+        ):
+            notice = (
+                f"wl gate: note: the project root {project_root.path} is a "
+                f"subdirectory of the gate root {deploy_root.path} and carries its "
+                f"own 'src/', so the mypy leg anchors there (its own .wl/mypy.ini "
+                f"and src/ apply); the other legs stay at {deploy_root.path}."
+            )
+            return project_root, notice
+        return deploy_root, None
+
+    if _same_path(project_root.path, deploy_root.path):
+        return deploy_root, None
+
+    notice = (
+        f"wl gate: note: the gate root {deploy_root.path} has no 'src/', so the "
+        f"mypy leg falls back to the project root {project_root.path} (its own "
+        f".wl/mypy.ini and src/ apply); the other legs stay at {deploy_root.path}."
+    )
+    return project_root, notice
+
+
+def mypy_scope_notice(chain: GateChain) -> str | None:
+    """The line to print when the mypy leg cannot see the package you ran from.
+
+    The leg checks ``<mypy_root>/src/`` and nothing else (a contract, never a
+    widened scope -- see :meth:`GateCommand.build_steps`). That is right when the
+    leg's root *is* the package the user is in, and it is wrong -- silently -- in
+    the other direction: a git root that carries ``src/`` while the user stands
+    in a nested package whose ``src/`` the leg does not check. The gate then
+    reports green over a tree that never contained the change under test.
+
+    So the notice is **unconditional**: it does not depend on a fallback having
+    happened, only on the scope genuinely not covering the invocation's project
+    root. It is ``None`` in every layout where the leg does cover it:
+
+    * the regular layout -- the project root *is* the deploy root;
+    * an ancestor project root (a workspace ``.wl`` above a member repo) -- the
+      user is in the member repo, which is the leg's root;
+    * a nested project root the leg anchored at (the #193 rule in
+      :func:`resolve_mypy_anchor`) -- the leg checks exactly that package.
+
+    Printed on stderr so the parseable ``[i/n]`` progress on stdout is untouched.
+    """
+    project_root = current_root(RootKind.PROJECT)
+    if not _is_strict_subdirectory(project_root.path, chain.root.path):
+        return None
+    if _same_path(project_root.path, chain.mypy_root.path):
+        return None
+    return (
+        f"wl gate: note: the mypy leg checks {chain.mypy_root.src_dir()} and that "
+        f"scope does not include the package you ran from ({project_root.path}), "
+        f"so type errors there are NOT reported by this gate."
+    )
+
+
+def _has_src(root: Root) -> bool:
+    """Whether *root* carries a ``src/`` directory, without letting I/O raise."""
+    try:
+        return root.src_dir().is_dir()
+    except OSError:
+        return False
+
+
+def _is_strict_subdirectory(child: Path, parent: Path) -> bool:
+    """True when *child* lies strictly below *parent* (same directory is not)."""
+    try:
+        relative = child.resolve().relative_to(parent.resolve())
+    except (OSError, ValueError):
+        return False
+    return bool(relative.parts)
+
+
+def _same_path(left: Path, right: Path) -> bool:
+    """Path equality that survives an unresolvable component."""
+    try:
+        return left.resolve() == right.resolve()
+    except OSError:
+        return left == right
+
+
+def vendored_baseline_notice(mypy_root: Root) -> str | None:
+    """The line to print when the mypy leg cannot use *mypy_root*'s baseline.
+
+    ``mypy_config_file`` falls back to the template shipped with ``wl`` when the
+    gate root has no ``.wl/mypy.ini``. Falling back is fine; doing it *silently*
+    is not: the user is then judged against a baseline they never chose, and a
+    ``.wl/mypy.ini`` living somewhere else (a nested project root, say) looks
+    like it applied when it did not (review F1). Returns ``None`` when the
+    root's own baseline is there, so the regular layout prints nothing.
+
+    Takes the mypy leg's :class:`Root` -- the value :class:`GateChain` already
+    resolved -- rather than a bare path, so no caller has to rebuild a ``Root``
+    from a path to ask where that leg's baseline is.
+    """
+    baseline = mypy_root.mypy_ini()
+    if baseline.is_file():
+        return None
+    return (
+        f"wl gate: note: {baseline} does not exist, so the "
+        f"mypy leg uses the vendored template shipped with wl "
+        f"({mypy_config_file(mypy_root.path)}) instead."
+        "\nwl gate: a .wl/mypy.ini outside the gate root -- for example at a "
+        "nested project root -- is not part of this gate's contract."
+    )
+
+
+class GateCommand:
+    """Run the local quality chain sequentially, stopping at first failure."""
+
+    def __init__(
+        self,
+        executor: SubprocessExecutor | None = None,
+        preflight: PreflightRunner | None = None,
+    ) -> None:
+        self.executor = executor if executor is not None else SubprocessExecutor()
+        # The step-0 probe is a collaborator, not a module global reached for
+        # mid-run: injecting it lets the orchestration below be tested without
+        # monkey-patching ``run_preflight``.
+        self.preflight: PreflightRunner = (
+            preflight if preflight is not None else run_preflight
+        )
+
+    def build_steps(
+        self,
+        chain: GateChain | None = None,
+        evidence_path: Path | None = None,
+    ) -> list[GateStep]:
+        """Build the ordered list of gate steps for *chain*.
+
+        Reuses the lint executor so the ruff and mypy command lines (including
+        the ``--config-file`` decision from ``mypy_config``) stay in one place.
+
+        *evidence_path* is the file the test leg's verdict will be read from
+        (#212). It is an **input**: this method is a pure description of the
+        chain -- tests, preflight and every "what would the gate run?" reader
+        call it -- so it must not create the file. Earlier it did, and every
+        build-only caller (one per test, 220 in a single suite) left an orphan
+        ``wl-gate-evidence-*.json`` in the system temp directory that only
+        ``execute``'s ``finally`` knew how to collect (review M1). Creation and
+        removal now both live in :meth:`execute`.
+
+        When *evidence_path* is ``None`` the returned test step carries no
+        evidence channel, which on purpose leaves it fail-closed at judging
+        time: :func:`_evidence_exit_code` refuses to vouch for a run whose
+        verdict it cannot read, rather than treating "no file" as a pass.
+
+        *chain* is the resolved root -- :meth:`GateChain.resolve` when omitted.
+        Every step is built against that one value, so each ``GateStep.cwd`` is
+        written out here and **no step carries a ``None``** for a later reader
+        to resolve against a second variable. The chain root (``chain.root``) is
+        where the repo's own ``.wl`` (including its ``mypy.ini`` baseline) is
+        deployed, where the repo's ``src/`` lives, and the directory CI runs the
+        same commands from. The project root is *not* interchangeable here -- in
+        the ``项目根 != 部署根`` layouts (#95 / #96) the two differ, and anchoring
+        at the project root silently ran the leg in the other tree: the baseline
+        was swapped for the vendored template and ``src/`` was either the wrong
+        package (a silent green over the wrong files) or absent, widening the
+        scope to the ``src/ tests/`` fallback (a red that says nothing about the
+        change under test -- exactly #98's complaint).
+
+        The mypy leg is the one exception, and only in the opposite direction:
+        when the deploy root has no ``src/`` to check, that leg anchors at
+        ``chain.mypy_root`` instead -- see :func:`resolve_mypy_anchor`, which
+        :meth:`GateChain.resolve` calls once and whose value is already on the
+        chain.
+        """
+        if chain is None:
+            chain = GateChain.resolve()
+        lint = LintExecutor()
+        return [
+            GateStep(
+                "ruff check",
+                lint.prepare_ruff_command(None, fix=False, quiet=False),
+                chain.root.path,
+            ),
+            # Scope is ``src/`` on purpose: it is the repo's own mypy contract
+            # (CI runs ``mypy --config-file .wl/mypy.ini src/`` with a baseline
+            # converged to 0 errors). LintExecutor's default is ``src/ tests/``,
+            # which reddens this leg on the repo's pre-existing ``tests/``
+            # typing debt -- a red that says nothing about the change under
+            # test, which is precisely what #98 is about.
+            GateStep(
+                "mypy",
+                # ``src/`` and nothing else. The gate must never fall back to
+                # LintExecutor's ``src/ tests/`` default: widening the scope
+                # would scan directories that have nothing to do with the
+                # change under test -- the false red review F0 is about. When
+                # the deploy root cannot satisfy ``src/`` the *root* moves (to
+                # the project root, per resolve_mypy_anchor) rather than the
+                # scope; the leg keeps checking ``src/`` and nothing else.
+                lint.prepare_mypy_command(
+                    ["src/"],
+                    quiet=False,
+                    project_root=chain.mypy_root.path,
+                    fallback_paths=("src/",),
+                ),
+                # The mypy leg's own root: equal to the chain root in the
+                # regular layout, the project root in the monorepo fallback.
+                chain.mypy_root.path,
+            ),
+            # The test leg's ``cwd`` is what decides which interpreter ``wl
+            # test`` resolves, so preflight probes the interpreter from this
+            # very field (``probe_interpreter``) rather than a root passed
+            # alongside the steps.
+            #
+            # ``--no-cache`` is not an optimisation knob here, it is what makes
+            # the leg a *test* of this tree (#193): with the default 24h result
+            # cache a broken ``conftest.py`` -- a file whose change re-runs
+            # nothing -- left ``wl gate`` green while the same tree failed
+            # ``pytest``. ``reject_cached_results`` is the verdict behind the
+            # flag: even if the flag is ever dropped, a run that reports cache
+            # hits cannot reach "all checks passed".
+            GateStep(
+                "pytest",
+                _pytest_command(evidence_path),
+                chain.root.path,
+                probe_interpreter=True,
+                capture=True,
+                reject_cached_results=True,
+                evidence_path=evidence_path,
+            ),
+            GateStep(
+                "ruff format --check",
+                ["ruff", "format", "--check", "."],
+                chain.root.path,
+            ),
+            # The managed hook suite (#193). Without it a green gate could be
+            # followed by a *rejected commit*: codespell, check-yaml, gitleaks
+            # and the lockfile check live only in the pre-commit config, so a
+            # green gate never meant "this commit is acceptable".
+            #
+            # The argv is the one ``run_pre_commit(files=None, config=<managed>,
+            # prefer_uv=False)`` builds -- ``pre-commit run --all-files --config
+            # <path>`` -- written out here so the step runs through the chain's
+            # one executor (and its output is judged by ``PreCommitRun`` below)
+            # rather than through a second, private subprocess wrapper. Bare
+            # ``pre-commit`` first matches ``wl lint``: the gate already runs
+            # inside the project environment and does not need uv to re-resolve
+            # it, and preflight resolves that same token from PATH.
+            #
+            # Read-only *verdict*: fixers (ruff-format, end-of-file-fixer,
+            # trailing-whitespace) rewrite files and exit non-zero, which a
+            # commit rejects too -- so a rewrite is reported as a step failure
+            # (``pre-commit rewrote files``), never as "all checks passed".
+            GateStep(
+                "pre-commit",
+                [
+                    "pre-commit",
+                    "run",
+                    "--all-files",
+                    "--config",
+                    str(chain.root.wl_dir() / ".pre-commit-config.yaml"),
+                ],
+                chain.root.path,
+                capture=True,
+                managed_config=chain.root.wl_dir() / ".pre-commit-config.yaml",
+            ),
+        ]
+
+    def execute(self) -> int:
+        """Run the step-0 preflight, then every step in order.
+
+        Returns:
+            0 when every step passes; :data:`EXIT_ENV_MISSING` when this machine
+            cannot run the chain at all (a required executable or plugin is
+            absent, or a step's executable cannot even be launched) -- in which
+            case no ``[i/n]`` step lines are produced; ``128 + signum`` when a
+            step ran and was then killed by a signal (reported as a signalled
+            step, never as an environment gap); 1 when the gate cannot create
+            its own evidence file (no verdict channel, so the chain is not
+            run); otherwise the failing step's own exit code.
+        """
+        # One resolution, read by every leg. ``build_steps`` writes it onto each
+        # step and preflight reads it back off the test step's own ``cwd``, so
+        # the judged root and the executed root are the same value by
+        # construction (issue #110).
+        chain = GateChain.resolve()
+        # The test leg's verdict channel (#212), owned by this call. Created
+        # here -- never in ``build_steps`` -- so a build-only caller leaves no
+        # orphan behind, and removed in the ``finally`` below whether the chain
+        # passed, failed early, or step-0 stopped it (review M1).
+        evidence_path = _create_evidence_file()
+        if evidence_path is None:
+            # No verdict channel means no verdict: refuse to run the chain
+            # rather than report "all checks passed" over a run nothing can
+            # vouch for. ``_create_evidence_file`` already said why on stderr.
+            return 1
+        steps = self.build_steps(chain, evidence_path)
+        try:
+            return self._execute_steps(steps, chain)
+        finally:
+            # Gate-owned scratch (#212): every evidence file goes, whether the
+            # chain passed, failed before the test leg ran, or step-0 preflight
+            # stopped it. A leftover would be read as a later run's verdict.
+            for step in steps:
+                _discard_evidence(step)
+
+    def _execute_steps(self, steps: list[GateStep], chain: GateChain) -> int:
+        """Judge *steps* over an already-resolved *chain*, in order."""
+        report = self.preflight(steps)
+        if not report.ok:
+            click.echo(render_env_error(report), err=True)
+            return EXIT_ENV_MISSING
+
+        # Say why the mypy leg left the gate root when it did (a monorepo whose
+        # git work-tree root has no ``src/``), and where it anchored instead.
+        # The notice was written by the single derivation on the chain.
+        if chain.mypy_notice is not None:
+            click.echo(chain.mypy_notice, err=True)
+
+        # Never swap the mypy baseline silently (review F1). Emitted on stderr
+        # so the parseable ``[i/n]`` progress on stdout is untouched. Judged
+        # against the mypy leg's own root -- the same value the leg runs in.
+        notice = vendored_baseline_notice(chain.mypy_root)
+        if notice is not None:
+            click.echo(notice, err=True)
+
+        # Unconditional (#193): say so whenever the mypy leg's scope cannot see
+        # the package this run was started from, whether or not a root moved.
+        scope_notice = mypy_scope_notice(chain)
+        if scope_notice is not None:
+            click.echo(scope_notice, err=True)
+
+        total = len(steps)
+        #: Steps that never ran, carried into the closing summary. A skip is not
+        #: a failure, but it is also not an unqualified pass (rv193/M1).
+        skipped: list[str] = []
+
+        for index, step in enumerate(steps, start=1):
+            click.echo(f"[{index}/{total}] {step.name} - running")
+            if step.is_skipped:
+                # Nothing to run: a checkout that was never ``wl init``-ed has no
+                # managed hooks. Skipped, never failed -- but said out loud, so
+                # the reader knows that part of the "canonical" gate was not
+                # applied here.
+                skipped.append(
+                    f"{step.name} (no managed config at {step.managed_config})"
+                )
+                click.echo(
+                    f"[{index}/{total}] {step.name} - skipped "
+                    f"(no managed config at {step.managed_config})"
+                )
+                continue
+            result = self.executor.run(step.command, cwd=step.cwd, quiet=step.capture)
+            if step.capture:
+                _echo_captured_output(result)
+            failure = _failure_exit_code(index, total, step, result)
+            if failure is None:
+                failure = _evidence_exit_code(index, total, step)
+            if failure is not None:
+                return failure
+            click.echo(f"[{index}/{total}] {step.name} - ok")
+
+        if skipped:
+            # No failures, but not "all checks passed" either: what did not run
+            # is named in the closing line, so a green gate can never be read as
+            # "every check this project has was applied" (rv193/M1).
+            click.echo(f"wl gate: no failures; skipped: {'; '.join(skipped)}")
+        else:
+            click.echo("wl gate: all checks passed")
+        return 0
+
+
+def _failure_exit_code(
+    index: int, total: int, step: GateStep, result: SubprocessResult
+) -> int | None:
+    """Report a failed step and return the code the gate must exit with.
+
+    ``None`` means the step passed. Every "which kind of red is this?" decision
+    lives here -- launch failure (an environment gap, never a step line),
+    signalled step (``128 + signum``), a pre-commit run whose only effect was
+    rewriting files, and the step's own exit code -- so :meth:`GateCommand.execute`
+    stays a plain loop over steps.
+    """
+    if result.success:
+        return None
+    if result.launch_error is not None:
+        # The executor's OSError path: the step's executable could not be
+        # started at all. That is an environment problem -- a FAILED line would
+        # be the phantom #98 exists to remove, and returning the raw sentinel
+        # would exit 255. Judged by the dedicated field, never by a bare ``-1``:
+        # a SIGHUP-killed child also reports ``-1`` (review F1).
+        click.echo(render_launch_error(step.name, step.command[0]), err=True)
+        return EXIT_ENV_MISSING
+    if result.returncode < 0:
+        # subprocess reports a child killed by signal N as -N. The step *ran*
+        # (PATH resolved it, it was launched) and was then signalled, so this is
+        # NOT the environment gap review N1 caught: it gets a signalled-step
+        # report and the shell's 128 + N code, never "PATH no longer resolves
+        # it" or "the chain was NOT run". SIGHUP (-1) reaches here too, because
+        # launch failure is now judged by ``launch_error``.
+        signum = -result.returncode
+        click.echo(
+            f"[{index}/{total}] {step.name} - FAILED (killed by signal {signum})"
+        )
+        click.echo(render_signal_error(step.name, step.command[0], signum), err=True)
+        return signal_exit_code(signum)
+    if step.managed_config is not None and _pre_commit_rewrote_files(
+        PreCommitRun(result)
+    ):
+        # Non-zero *only* because a hook rewrote files. A commit would reject
+        # that tree too, so this is a step failure -- and never a silent "all
+        # checks passed" over a tree the gate just modified.
+        click.echo(f"[{index}/{total}] {step.name} - FAILED (pre-commit rewrote files)")
+        click.echo(
+            "wl gate: the pre-commit step modified files (fixers such as "
+            "ruff-format / end-of-file-fixer / trailing-whitespace), so this tree "
+            "would be rejected by a commit; review and stage the rewrite or fix "
+            "the files yourself.",
+            err=True,
+        )
+        return 1
+    click.echo(f"[{index}/{total}] {step.name} - FAILED (exit {result.returncode})")
+    click.echo(f"wl gate: failed at step '{step.name}'")
+    return result.returncode
+
+
+def _evidence_exit_code(index: int, total: int, step: GateStep) -> int | None:
+    """Red when the test leg's structured evidence is unusable or reports hits.
+
+    ``None`` means the file is present, parseable, of a known schema version,
+    and says no result came from the cache. Everything else is red, and the
+    message names the path -- there is deliberately no stdout fallback, so a
+    run the gate cannot observe is never a pass (ADR-0010, #212).
+
+    ``no_cache_requested`` does not change the verdict (a cache hit is red
+    either way); it only chooses the *wording*, so the user can tell "the
+    runner ignored ``--no-cache``" from "the gate did not pass it".
+    """
+    if not step.reject_cached_results:
+        return None
+
+    path = step.evidence_path
+    if path is None:
+        # Fail-closed and *named* (review L3): a step that must prove a fresh
+        # run but carries no path is a wiring bug in the gate, not a verdict
+        # about the tree. Reading through anyway produced "could not read the
+        # test run's evidence at None", which reads as a missing file the user
+        # could recreate -- and points at nothing.
+        click.echo(f"[{index}/{total}] {step.name} - FAILED (no evidence path)")
+        click.echo(
+            "wl gate: the test leg must prove it ran against this tree, but it "
+            "carries no evidence path, so there is no file to read a verdict "
+            "from. This is a wiring bug in the gate rather than a result of "
+            "your change; re-run 'wl gate' and, if it persists, report it.",
+            err=True,
+        )
+        return 1
+
+    evidence = TestRunEvidence.read(path)
+    if evidence is None:
+        click.echo(f"[{index}/{total}] {step.name} - FAILED (no usable run evidence)")
+        click.echo(
+            f"wl gate: could not read the test run's evidence at {path} "
+            "(missing, corrupt, or an unknown schema version). The test leg's "
+            "verdict comes from that file, so the gate cannot vouch for this "
+            "run; re-run 'wl gate' and, if it persists, check that 'wl test' "
+            "supports --evidence-json.",
+            err=True,
+        )
+        return 1
+
+    if evidence.cache_hits <= 0:
+        return None
+
+    click.echo(
+        f"[{index}/{total}] {step.name} - FAILED "
+        f"(cache reused {evidence.cache_hits} result(s) of "
+        f"{evidence.cache_total} file(s))"
+    )
+    if evidence.no_cache_requested:
+        cause = (
+            "the runner was asked for '--no-cache' but its evidence says "
+            "no_cache_requested=true, so the flag was ignored"
+        )
+    else:
+        cause = (
+            "the runner's evidence says no_cache_requested=false, so the gate's "
+            "own '--no-cache' never reached it"
+        )
+    click.echo(
+        f"wl gate: the test leg reused cached results, so it did not exercise "
+        f"the current tree; a cache hit is not a pass ({cause}). "
+        f"Evidence: {path}",
+        err=True,
+    )
+    return 1
+
+
+def _pytest_command(evidence_path: Path | None) -> list[str]:
+    """The test leg's argv, carrying the evidence channel when there is one.
+
+    ``--evidence-json`` is appended only for a real path: naming ``None`` on a
+    command line would be a path the runner tries to write to, and the step's
+    verdict is read from ``GateStep.evidence_path`` anyway.
+    """
+    command = ["wl", "test", "-s", "--no-cache"]
+    if evidence_path is not None:
+        command += ["--evidence-json", str(evidence_path)]
+    return command
+
+
+def _create_evidence_file() -> Path | None:
+    """Create the gate-owned evidence file, or ``None`` when it cannot be made.
+
+    The file is created eagerly -- an empty file rather than only a name --
+    because a runner that never writes it then leaves something the reader
+    rejects as corrupt: red, not "no opinion" (ADR-0010).
+
+    An unwritable or full temp directory is an environment failure at the
+    moment the gate is asked to run, so it is reported as one: a named,
+    actionable message on stderr and a ``None`` verdict for the caller to turn
+    into a non-zero exit. It must never surface as a traceback out of
+    ``mkstemp`` -- the gate refuses to run without its verdict channel, and
+    that refusal has to be readable (review M1).
+    """
+    name: str | None = None
+    try:
+        descriptor, name = tempfile.mkstemp(prefix="wl-gate-evidence-", suffix=".json")
+        os.close(descriptor)
+    except OSError as error:
+        if name is not None:
+            try:
+                Path(name).unlink()
+            except OSError:
+                pass
+        click.echo(
+            "wl gate: could not create the test leg's evidence file in "
+            f"{tempfile.gettempdir()} ({error}). The test leg's verdict comes "
+            "from that file, so the gate refuses to run without it; check that "
+            "TMPDIR is writable and has free space.",
+            err=True,
+        )
+        return None
+    return Path(name)
+
+
+def _discard_evidence(step: GateStep) -> None:
+    """Remove the temporary evidence file this step owns, if it has one.
+
+    A file left behind would survive into a later run or a reused temp name and
+    be read as a fresh verdict, so the removal is unconditional and quiet -- a
+    ``FileNotFoundError`` here just means the runner never created it, which the
+    reader already treats as red.
+    """
+    if step.evidence_path is None:
+        return
+    try:
+        step.evidence_path.unlink()
+    except OSError:
+        pass
+
+
+def _echo_captured_output(result: SubprocessResult) -> None:
+    """Replay a captured step's output, so capturing loses no information.
+
+    Steps that carry their verdict in stdout are run with ``quiet=True`` (the
+    executor then captures instead of streaming). Everything they said is echoed
+    here as one block, with the trailing newline preserved only when the stream
+    already had one -- so a step's own formatting survives unchanged.
+    """
+    if result.stdout:
+        click.echo(result.stdout, nl=not result.stdout.endswith("\n"))
+    if result.stderr:
+        click.echo(result.stderr, nl=not result.stderr.endswith("\n"), err=True)
+
+
+def _pre_commit_rewrote_files(run: PreCommitRun) -> bool:
+    """True when a non-zero pre-commit run's only effect was rewriting files.
+
+    :attr:`PreCommitRun.hooks_failed` deliberately answers "a hook judged a
+    failure", and it excludes auto-fix blocks because formatting *expects* them.
+    A gate cannot: the tree it just rewrote is not the tree it was asked to
+    judge, and a commit would reject it. So the two are told apart here, using
+    the run's own blocks rather than re-parsing its exit code.
+    """
+    return bool(run.verdict_blocks) and not run.failed_blocks
+
+
+def _is_file(path: Path) -> bool:
+    """``is_file`` without letting an unreadable component raise."""
+    try:
+        return path.is_file()
+    except OSError:
+        return False
+
+
+@click.command()
+def gate_command() -> None:
+    """Run the full local quality gate (ruff, mypy, pytest, format, hooks).
+
+    A step-0 preflight first checks that the executables the chain will run
+    (ruff, mypy, wl, pre-commit) and the pytest plugins its test step needs are
+    available. If any is missing the gate exits 78 (environment error) and the
+    chain is not run.
+
+    Exit codes: 0 all clear; 78 the environment cannot run the chain; 128 + N a
+    step ran and was killed by signal N (e.g. 137 = SIGKILL); otherwise the
+    failing step's own code.
+    """
+    exit_code = GateCommand().execute()
+    if exit_code != 0:
+        sys.exit(exit_code)