Settle the Coverage Boundary and Scope D7.3 to Event Inputs

.github/workflows/validate-task.yml

@@ -1,7 +1,7 @@
 name: Validate task
 
 # The fleet validation gate, hosted here once and reached by every repo's test-pull-request stub and its own publish-release stub.
-# Three jobs: lint (the fleet doc-lint block plus language lint by tree detection, the prose gate, and the repo gate), unit-test (a generic dotnet test or uv run pytest, skipped where the caller has no test project), and validate (the validate hook, a repo's own domain checks such as an ESPHome compile, a Hugo build, a KiCad ERC, a codegen-drift check, or PowerShell tests).
+# Three jobs: lint (the fleet doc-lint block plus language lint by tree detection, the prose gate, and the repo gate), unit-test (a generic dotnet test or pytest, skipped where the caller has no test project), and validate (the validate hook, a repo's own domain checks such as an ESPHome compile, a Hugo build, a KiCad ERC, a codegen-drift check, or PowerShell tests).
 # No permissions beyond contents: read where a job needs one, since every job here only checks out and reads.
 # No required inputs, markdown-exclude-globs and repo-gate-exclude-globs are the two optional inputs, and CODECOV_TOKEN is the one optional secret, since coverage upload is best-effort.
 # Hub-owned gates and default hooks resolve through $/ at the reusable workflow's commit, so each implementation is reproducible against the caller's released pin without a second checkout.
@@ -257,8 +257,9 @@ jobs:
 
   # No job-level if: here, since GitHub Actions does not evaluate hashFiles in a job condition, only a step one.
   # Every step below carries its own tree-detection guard instead.
-  # A caller with neither a *Tests*.csproj nor a uv.lock-backed tests/ directory beside a pyproject.toml runs every step's guard false, and the job reports success having done nothing, which is the clean skip this job promises.
-  # The uv.lock guard excludes the lint-only Python profile (spec/project-types.json python profileNote), which is stdlib-only, uvx-run, and carries no lockfile to sync from.
+  # A caller with neither a *Tests*.csproj nor a tests/ directory beside a pyproject.toml and a dependency manifest runs every step's guard false, and the job reports success having done nothing, which is the clean skip this job promises.
+  # That manifest is a committed uv.lock or a root requirements*.txt, the two dependency mechanisms spec/project-types.json names, so a pip-based Python repo with tests is served here rather than skipped, per D1.6.
+  # What excludes the lint-only Python profile here is the root tests/ guard rather than the manifest one, that profile being tooling scripts embedded in a non-Python repo rather than a tested package at the root.
   unit-test:
     name: Unit test job
     runs-on: ubuntu-latest
@@ -299,32 +300,63 @@ jobs:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Setup uv step
-        if: hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != '' && hashFiles('uv.lock') != ''
+        if: >-
+          hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != ''
+          && (hashFiles('uv.lock') != '' || hashFiles('requirements*.txt') != '')
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.13"
 
+      # One resolve over the collected requirements files, since the glob sorts the base file last and a per-file install would let its pins downgrade what the test file just resolved.
+      # The editable install matches what uv sync gives the other branch, and its guard leaves a layout declaring no [project] alone.
       - name: Sync dependencies step
-        if: hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != '' && hashFiles('uv.lock') != ''
-        run: uv sync --all-groups --frozen
+        if: >-
+          hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != ''
+          && (hashFiles('uv.lock') != '' || hashFiles('requirements*.txt') != '')
+        run: |
+          set -Eeuo pipefail
+          if [ -f uv.lock ]; then
+            uv sync --all-groups --frozen
+          else
+            uv venv
+            requirement_args=()
+            for file in requirements*.txt; do
+              [ -e "$file" ] || continue
+              requirement_args+=(-r "$file")
+            done
+            if [ "${#requirement_args[@]}" -gt 0 ]; then
+              uv pip install "${requirement_args[@]}"
+            fi
+            if grep -Eq '^[[:space:]]*\[project\]' pyproject.toml; then
+              uv pip install -e .
+            fi
+          fi
 
       # --cov-report=xml names the report format and selects nothing to measure, so the repository's own pyproject.toml supplies the --cov selector, per D1.6.
       # The report is checked rather than assumed, because the best-effort upload below reads a missing file exactly as it reads a healthy run.
       # The pre-run delete makes that a check on what this run wrote, since a committed coverage.xml would otherwise satisfy it without any measurement.
       - name: Run pytest step
-        if: hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != '' && hashFiles('uv.lock') != ''
+        if: >-
+          hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != ''
+          && (hashFiles('uv.lock') != '' || hashFiles('requirements*.txt') != '')
         run: |
           set -Eeuo pipefail
           rm -f coverage.xml
-          uv run pytest --cov-report=xml
+          if [ -f uv.lock ]; then
+            uv run pytest --cov-report=xml
+          else
+            .venv/bin/python -m pytest --cov-report=xml
+          fi
           if [[ ! -s coverage.xml ]]; then
             echo "::error::This run wrote no coverage.xml at the repository root. Select a coverage source in this repository's pyproject.toml, an addopts entry of --cov=<package> in practice, since --cov-report=xml alone measures nothing, and leave the report at the root path the upload step below reads."
             exit 1
           fi
 
       # Best-effort: continue-on-error plus fail_ci_if_error false, so a missing token never reds the gate.
       - name: Upload coverage to Codecov step (Python)
-        if: hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != '' && hashFiles('uv.lock') != ''
+        if: >-
+          hashFiles('pyproject.toml') != '' && hashFiles('tests/**') != ''
+          && (hashFiles('uv.lock') != '' || hashFiles('requirements*.txt') != '')
         continue-on-error: true
         uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
         with:

docs/reusable-workflows.md

@@ -148,15 +148,15 @@ Adoptable since `2.0.338`. Each repo replaces the whole of its `.github/workflow
 
 ### Stage 2: The Gates
 
-Hub: `validate-task.yml` hosts a `lint` job (the fleet doc-lint block, language lint by tree detection, the prose gate, and the repo gate), a generic `unit-test` job (a `dotnet test` or a `uv run pytest`, skipped cleanly where the caller carries no test project), and a `validate` job resolving the `validate` hook for a repo's own domain checks, which decides #729 in the one place the `uvx` tools are pinned or floated. There is no `test-pull-request-task.yml`: the ruleset-bound aggregator stays in the caller stub by design, and a task wrapping one line that calls `validate-task.yml` hosts nothing generic, so the stub shapes live in [Adopting the Gates][adopting-the-gates] instead, with the trigger shape, operational or release, settling #585. This stage is where the hook fallback is first proven live: the hub carries its own `validate` hook (its registry and spec check, its script self-tests, its fleet-skills check, and its unclassified-character report), so a hub pull request exercises the override path, and a repo with no hook of its own exercises the default.
+Hub: `validate-task.yml` hosts a `lint` job (the fleet doc-lint block, language lint by tree detection, the prose gate, and the repo gate), a generic `unit-test` job (a `dotnet test` or a `pytest`, skipped cleanly where the caller carries no test project), and a `validate` job resolving the `validate` hook for a repo's own domain checks, which decides #729 in the one place the `uvx` tools are pinned or floated. There is no `test-pull-request-task.yml`: the ruleset-bound aggregator stays in the caller stub by design, and a task wrapping one line that calls `validate-task.yml` hosts nothing generic, so the stub shapes live in [Adopting the Gates][adopting-the-gates] instead, with the trigger shape, operational or release, settling #585. This stage is where the hook fallback is first proven live: the hub carries its own `validate` hook (its registry and spec check, its script self-tests, its fleet-skills check, and its unclassified-character report), so a hub pull request exercises the override path, and a repo with no hook of its own exercises the default.
 
 - [x] Hub pull request on `develop` with the task, the hub's own hook and default, the manifest contracts, and the catalog snippets left for the release that follows, [#760][pr-760].
 - [x] Promoted to `main` in #774 (`0b07a59d`) and released as `2.0.352`, the first tag carrying `validate-task.yml`.
 - [ ] Catalog snippets for both stub shapes in [Adopting the Gates][adopting-the-gates] pinned to that release. The no-build shape has one, `catalog/snippets/workflows/test-pull-request.yml`. The release-with-smoke shape still calls its own repo's `build-release-task.yml` by `./` path rather than the hub's, so it carries no catalog-ready pin yet, and this item stays open until it does.
 - [x] Hook override path observed on a hub pull request run, [proof run][override-path-run] (runs `./.github/actions/validate`, no hub checkout). Default path observed on PhotoCleaner's adoption pull request, [pilot smoke run][pilot-smoke-run], where the hub's `validate-default` ran because that repo carries no `validate` hook. The follow-up self-reference pilot also runs the bundled prose and repository gates through `$/.github/actions/` without checking out the hub.
 - [x] PhotoCleaner (pilot, release trigger shape with smoke, the same repo that piloted stage 1): ptr727/PhotoCleaner#55 on `develop` (`c80cb29`), promoted in ptr727/PhotoCleaner#56 (`fa91db0`), both on 2026-08-16. `test-pull-request.yml` calls the hub validate task and no repo hook was needed.
 - [ ] HomeAutomation-Config (second pilot, operational trigger shape)
-- [ ] The remaining repos, one checkbox each added when the pilots close, since the sweep list is every cataloged repo. A Python adopter owes one precondition before its bump: the `unit-test` job fails when the run wrote no root `coverage.xml`, and that job's Python leg runs where the repository root carries `pyproject.toml`, `tests/`, and `uv.lock`, so an adopter of that shape puts `pytest-cov` in a dev group and a `--cov=<package>` selector in its own `pyproject.toml` before it bumps, per D1.6, which binds that selector for every Python repo with tests, lint-only excepted. aiopurpleair and Financial-Modeling carry both, homeassistant-purpleair and PlexCleaner carry no `uv.lock` so the step never runs there, and ESPHome-Config's Python is lint-only. The hub cannot smoke-test this itself, having no `tests/` and no `uv.lock` of its own.
+- [ ] The remaining repos, one checkbox each added when the pilots close, since the sweep list is every cataloged repo. A Python adopter owes one precondition before its bump: the `unit-test` job fails when the run wrote no root `coverage.xml`, and that job's Python leg runs where the repository root carries `pyproject.toml`, `tests/`, and a dependency manifest it installs from, a committed `uv.lock` or a root `requirements*.txt`, so an adopter of that shape puts `pytest-cov` among its test dependencies and a `--cov=<package>` selector in its own `pyproject.toml` before it bumps, per D1.6, which binds that selector for every Python repo with tests, lint-only excepted. aiopurpleair and Financial-Modeling carry both. homeassistant-purpleair owes the same precondition, its `requirements*.txt` and `tests/` reaching the leg though it carries no `uv.lock`, and its adoption is a design question rather than a bump, its pytest run being a matrix over several Home Assistant versions on Python 3.14 where the hub leg pins 3.13 and expresses no matrix at all. PlexCleaner's Python is a stdlib-only tooling subtree with no tests, and ESPHome-Config's Python is lint-only. The hub cannot smoke-test this itself, having no `tests/` of its own.
 - [ ] `reports/workflow-reuse.md` regenerated with `validate-task.yml` at 0 copies (a hub-only file no repo carries) and `test-pull-request.yml` showing callers equal to copies.
 
 ### Stage 3: The Pure Functions

reports/canonical-review.json

@@ -459,19 +459,19 @@
     },
     {
       "unit": "WORKFLOW.md > 4. Behavioral Contract: Expected Outcomes",
-      "digest": "sha256:a4b85d3b43f98646b6cf1a7161acacc09f3e4b8f3c23c1197af69d13bba74d84",
+      "digest": "sha256:3616be733206b40f62b360374e08056785038ec7b528c7746ab0a5dfaffc34c3",
       "reviewer": "agent-skill",
-      "findings": 0,
-      "hubCommit": "4fdc718663d0149994e496e890c20c7a77f27c96",
-      "stamp": "2026-09-03T03:04:24Z"
+      "findings": 16,
+      "hubCommit": "28dafdf46ee35cc9901e845a317991d909a94fac",
+      "stamp": "2026-09-03T18:21:27Z"
     },
     {
       "unit": "WORKFLOW.md > 5. Test Methodology",
-      "digest": "sha256:18e41e5b607eb337226934496038656cdb047c0cfb99e6bce5c8f7832dfc74b4",
+      "digest": "sha256:e4c043871a8fe90f89741b36893a0a4b8cf8ddba18ca8259a4513a300931ed24",
       "reviewer": "agent-skill",
-      "findings": 38,
-      "hubCommit": "6525cb888406c7f6a1f43c5f9b21fb041200c601",
-      "stamp": "2026-09-03T17:41:49Z"
+      "findings": 12,
+      "hubCommit": "28dafdf46ee35cc9901e845a317991d909a94fac",
+      "stamp": "2026-09-03T18:21:33Z"
     },
     {
       "unit": "WORKFLOW.md > 6. Per-Project-Type Test Walkthroughs",

scripts/tests/test_release_guards.py

@@ -3,13 +3,71 @@
 
 from __future__ import annotations
 
+import re
 import unittest
 from pathlib import Path
 from subprocess import run
 
 REPO = Path(__file__).resolve().parents[2]
 
 
+def hash_files(pattern: str, present: set[str]) -> bool:
+    """Whether a workflow `hashFiles(<pattern>)` would match anything in `present`.
+
+    `**` spans directory separators and `*` does not, which is what separates a root-only
+    `requirements*.txt` from a recursive `tests/**`.
+    """
+    regex = re.escape(pattern).replace(r"\*\*", "@@").replace(r"\*", "[^/]*").replace("@@", ".*")
+    return any(re.fullmatch(regex, path) for path in present)
+
+
+def split_top_level(expression: str, operator: str) -> list[str]:
+    """Split on `operator` outside any parentheses."""
+    parts: list[str] = []
+    depth = 0
+    start = 0
+    index = 0
+    while index < len(expression):
+        character = expression[index]
+        if character == "(":
+            depth += 1
+        elif character == ")":
+            depth -= 1
+        elif depth == 0 and expression.startswith(operator, index):
+            parts.append(expression[start:index])
+            index += len(operator)
+            start = index
+            continue
+        index += 1
+    parts.append(expression[start:])
+    return [part.strip() for part in parts]
+
+
+def evaluate_guard(expression: str, present: set[str]) -> bool:
+    """Evaluate a workflow `if:` written only from `hashFiles(...)` emptiness tests, `&&`, `||`, `()`.
+
+    Deliberately narrow rather than a general expression engine: it is here to answer what the
+    validator's Python leg does for one file set, not to reimplement GitHub's evaluator.
+    """
+
+    def atom(text: str) -> bool:
+        match = re.fullmatch(r"hashFiles\('([^']*)'\)\s*(!=|==)\s*''", text.strip())
+        if not match:
+            raise ValueError(f"unsupported guard atom: {text!r}")
+        hit = hash_files(match.group(1), present)
+        return hit if match.group(2) == "!=" else not hit
+
+    result = True
+    for clause in split_top_level(expression, "&&"):
+        if clause.startswith("(") and clause.endswith(")"):
+            result = result and any(
+                atom(alternative) for alternative in split_top_level(clause[1:-1], "||")
+            )
+        else:
+            result = result and atom(clause)
+    return result
+
+
 class ReleaseGuardCase(unittest.TestCase):
     """Publishing and audit discovery require their prerequisite checks to succeed."""
 
@@ -158,6 +216,52 @@ def test_audit_probes_fail_before_local_path_checks(self) -> None:
             audit,
         )
 
+    def test_validator_python_leg_reaches_a_pip_dependency_repo(self) -> None:
+        """WORKFLOW.md D1.6 owes coverage to every Python repo with tests, uv-managed or not.
+
+        Gating the leg on `uv.lock` alone skipped a pip/requirements repo that has tests, so it
+        collected no coverage and never reached the missing-report failure either.
+        """
+        workflow = (REPO / ".github/workflows/validate-task.yml").read_text(encoding="utf-8")
+        job = workflow.split("\n  unit-test:\n", 1)[1].split("\n  validate:\n", 1)[0]
+        guards = [
+            " ".join(line.strip() for line in block.strip().splitlines())
+            for block in re.findall(r"(?m)^        if: >-\n((?:^ {10}.*\n)+)", job)
+        ]
+        python_guards = [guard for guard in guards if "tests/**" in guard]
+
+        # Setup, dependency install, pytest, and upload: one drifting guard reintroduces the skip.
+        self.assertEqual(4, len(python_guards))
+        self.assertEqual(1, len(set(python_guards)))
+
+        trees = {
+            "uv project with tests": ({"pyproject.toml", "uv.lock", "tests/test_a.py"}, True),
+            "pip project with tests": (
+                {"pyproject.toml", "requirements.txt", "requirements-test.txt", "tests/test_a.py"},
+                True,
+            ),
+            "tests but no dependency manifest": ({"pyproject.toml", "tests/test_a.py"}, False),
+            "lint-only scripts tree": ({"pyproject.toml", "scripts/tool.py"}, False),
+            "pip project with no tests": ({"pyproject.toml", "requirements.txt"}, False),
+        }
+        for label, (present, expected) in trees.items():
+            with self.subTest(tree=label):
+                self.assertEqual(expected, evaluate_guard(python_guards[0], present))
+
+        # The guard admitting a pip repo is only half of it: the steps must install and run without a lockfile.
+        self.assertIn('requirement_args+=(-r "$file")', job)
+        self.assertIn('uv pip install "${requirement_args[@]}"', job)
+        self.assertIn(".venv/bin/python -m pytest --cov-report=xml", job)
+
+        # One resolve over every requirements file, never one install per file.
+        # The glob sorts the base file last, so a per-file install lets its pins downgrade what the test-requirements file just resolved.
+        self.assertNotIn('uv pip install -r "$file"', job)
+
+        # The lockfile branch installs the project itself, so the pip branch owes the same.
+        # Without it a src-layout repo fails collection on its own package instead of running its tests.
+        self.assertIn("uv pip install -e .", job)
+        self.assertIn(r"grep -Eq '^[[:space:]]*\[project\]' pyproject.toml", job)
+
     def test_audit_bash_blocks_are_not_labeled_as_posix_shell(self) -> None:
         audit_lines = (REPO / "AUDIT.md").read_text(encoding="utf-8").splitlines()
         bash_only = ("<(", "<<<", "$'", "[[")