Add Python Tooling to CI and Move the Script Tests to scripts/tests

.agents/skills/python-codestyle/SKILL.md

@@ -73,12 +73,17 @@ whether the Python has third-party runtime dependencies, which shows up structur
   auto-updates (SHA-pinned actions, package deps) and otherwise run latest, so the VS Code tasks,
   README, and CI all run the unpinned latest here. `.py` files follow the repo's line-ending
   default (CRLF in a CRLF-default repo, and a shebang-executed script is LF-pinned by path, per
-  GOVERNANCE.md's "Line Endings" section). There is no pytest suite and no coverage gate. A script
-  that carries a gate still earns tests, written with the standard library's `unittest` so they
-  run under bare `python3` with nothing installed, as `test_<script>.py` beside the script it
-  exercises. Measure them with `uvx coverage@latest run -m unittest discover -s <dir>` when a
-  number is wanted, without adopting a threshold. A co-present `csharp` type still carries
-  `codecov.yml` for its own tests.
+  GOVERNANCE.md's "Line Endings" section). There is no pytest suite, and `unittest` is the runner
+  instead. A script that carries a gate still earns tests, written with the standard library's
+  `unittest` so they run under bare `python3` with nothing installed, as `test_<script>.py` under
+  a `tests/` directory beside the scripts it exercises (`<scripts-dir>/tests/`), kept apart so a
+  test never reads as a tool. Within the scripts directory the name carries the kind: a gate that
+  checks and exits non-zero on a finding takes a `_lint` or `_gate` suffix, and a utility that
+  does work takes none. Any repo carrying Python carries the Python tooling in CI, coverage
+  included, this profile too: `uvx ruff@latest check`, `uvx mypy@latest`, and the unittest suite
+  under `uvx coverage@latest run -m unittest discover -s <scripts-dir>/tests` with
+  `coverage report`, informational with no threshold adopted. A co-present `csharp` type still
+  carries `codecov.yml` for its own tests.
 
 ## Toolchain
 

.agents/skills/shell-codestyle/SKILL.md

@@ -27,7 +27,7 @@ cover general scripting style.
 
 Bash, and only where a program cannot be Python: a bootstrap that installs the interpreter cannot
 be written in it, and a host tool that must run before a development toolchain exists cannot
-depend on one. Everything else is Python, with a test beside it.
+depend on one. Everything else is Python, with a test under the scripts tree's `tests/` directory.
 
 ## Rules
 

.agents/skills/skill-lifecycle/SKILL.md

@@ -28,7 +28,7 @@ A skill surfaces at a trigger moment. A rule that binds every action all the tim
 3. **Author the body per the `comment-and-doc-style` skill**: CRLF (the repo default), present tense, ASCII tiers, no semicolon in prose. Name hub paths as plain code spans rather than repo-relative links, because an installed copy resolves no repo path, and say "from a hub checkout" for anything the reader must run.
 4. **Split bulk into `references/`** when the source doc is large: the SKILL.md carries the summary and the binding rules, and each `references/*.md` carries one topic read on demand, the shape `comment-and-doc-style` uses.
 5. **Apply the doc-packaging pattern below in the same change** when the skill packages a law doc or one of its sections.
-6. **Regenerate and commit both trees together**: `python3 scripts/build_dist.py`, then commit the source and the regenerated `.claude-plugin/` in one commit. CI runs `--check` on every pull request and fails a desynced pair. `python3 scripts/test_build_dist.py` covers the generator itself.
+6. **Regenerate and commit both trees together**: `python3 scripts/build_dist.py`, then commit the source and the regenerated `.claude-plugin/` in one commit. CI runs `--check` on every pull request and fails a desynced pair. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
 7. **Record the surfacing**: annotate the `AGENTS.md` "Where the Rules Live" row when the skill packages a GOVERNANCE section, or its closing paragraph when the skill is new content, so the map stays the one place coverage is read from.
 8. **Refresh the machines after merge**: re-run `python3 scripts/skills_install.py` per machine, the cadence `docs/host-setup.md` "Fleet Skills Install" states. Until then every machine serves the previous skill set, which `--report` says.
 

.claude-plugin/fleet-skills/.source-digest

@@ -1 +1 @@
-f1e6675e6e015c18
+676ab1e915338dd7

.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md

@@ -73,12 +73,17 @@ whether the Python has third-party runtime dependencies, which shows up structur
   auto-updates (SHA-pinned actions, package deps) and otherwise run latest, so the VS Code tasks,
   README, and CI all run the unpinned latest here. `.py` files follow the repo's line-ending
   default (CRLF in a CRLF-default repo, and a shebang-executed script is LF-pinned by path, per
-  GOVERNANCE.md's "Line Endings" section). There is no pytest suite and no coverage gate. A script
-  that carries a gate still earns tests, written with the standard library's `unittest` so they
-  run under bare `python3` with nothing installed, as `test_<script>.py` beside the script it
-  exercises. Measure them with `uvx coverage@latest run -m unittest discover -s <dir>` when a
-  number is wanted, without adopting a threshold. A co-present `csharp` type still carries
-  `codecov.yml` for its own tests.
+  GOVERNANCE.md's "Line Endings" section). There is no pytest suite, and `unittest` is the runner
+  instead. A script that carries a gate still earns tests, written with the standard library's
+  `unittest` so they run under bare `python3` with nothing installed, as `test_<script>.py` under
+  a `tests/` directory beside the scripts it exercises (`<scripts-dir>/tests/`), kept apart so a
+  test never reads as a tool. Within the scripts directory the name carries the kind: a gate that
+  checks and exits non-zero on a finding takes a `_lint` or `_gate` suffix, and a utility that
+  does work takes none. Any repo carrying Python carries the Python tooling in CI, coverage
+  included, this profile too: `uvx ruff@latest check`, `uvx mypy@latest`, and the unittest suite
+  under `uvx coverage@latest run -m unittest discover -s <scripts-dir>/tests` with
+  `coverage report`, informational with no threshold adopted. A co-present `csharp` type still
+  carries `codecov.yml` for its own tests.
 
 ## Toolchain
 

.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md

@@ -27,7 +27,7 @@ cover general scripting style.
 
 Bash, and only where a program cannot be Python: a bootstrap that installs the interpreter cannot
 be written in it, and a host tool that must run before a development toolchain exists cannot
-depend on one. Everything else is Python, with a test beside it.
+depend on one. Everything else is Python, with a test under the scripts tree's `tests/` directory.
 
 ## Rules
 

.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md

@@ -28,7 +28,7 @@ A skill surfaces at a trigger moment. A rule that binds every action all the tim
 3. **Author the body per the `comment-and-doc-style` skill**: CRLF (the repo default), present tense, ASCII tiers, no semicolon in prose. Name hub paths as plain code spans rather than repo-relative links, because an installed copy resolves no repo path, and say "from a hub checkout" for anything the reader must run.
 4. **Split bulk into `references/`** when the source doc is large: the SKILL.md carries the summary and the binding rules, and each `references/*.md` carries one topic read on demand, the shape `comment-and-doc-style` uses.
 5. **Apply the doc-packaging pattern below in the same change** when the skill packages a law doc or one of its sections.
-6. **Regenerate and commit both trees together**: `python3 scripts/build_dist.py`, then commit the source and the regenerated `.claude-plugin/` in one commit. CI runs `--check` on every pull request and fails a desynced pair. `python3 scripts/test_build_dist.py` covers the generator itself.
+6. **Regenerate and commit both trees together**: `python3 scripts/build_dist.py`, then commit the source and the regenerated `.claude-plugin/` in one commit. CI runs `--check` on every pull request and fails a desynced pair. `python3 scripts/tests/test_build_dist.py` covers the generator itself.
 7. **Record the surfacing**: annotate the `AGENTS.md` "Where the Rules Live" row when the skill packages a GOVERNANCE section, or its closing paragraph when the skill is new content, so the map stays the one place coverage is read from.
 8. **Refresh the machines after merge**: re-run `python3 scripts/skills_install.py` per machine, the cadence `docs/host-setup.md` "Fleet Skills Install" states. Until then every machine serves the previous skill set, which `--report` says.
 

.editorconfig

@@ -80,9 +80,10 @@ end_of_line = lf
 [host-setup/agent-safety/*.py]
 end_of_line = lf
 
-# The repo lint and review scripts are shebang-executable tooling run by path, so a CRLF shebang would break direct execution on a Unix host.
+# The repo lint and review scripts, and their tests under scripts/tests/, are shebang-executable tooling run by path, so a CRLF shebang would break direct execution on a Unix host.
 # They are pinned in .gitattributes to match.
-[scripts/*.py]
+# `**` rather than `*`, because an EditorConfig `*` stops at a path separator and would leave scripts/tests/ on the CRLF default.
+[scripts/**.py]
 end_of_line = lf
 
 # The uv tool regenerates uv.lock with LF on every platform, so pin it here.

.gitattributes

@@ -29,16 +29,16 @@ host-setup/agent-safety/test_install.py text eol=lf
 scripts/prose_lint.py text eol=lf
 scripts/repo_gate.py text eol=lf
 scripts/pr_review.py text eol=lf
-scripts/test_prose_lint.py text eol=lf
-scripts/test_repo_gate.py text eol=lf
-scripts/test_pr_review.py text eol=lf
+scripts/tests/test_prose_lint.py text eol=lf
+scripts/tests/test_repo_gate.py text eol=lf
+scripts/tests/test_pr_review.py text eol=lf
 scripts/host_gate.py text eol=lf
-scripts/test_host_gate.py text eol=lf
-scripts/test_bootstrap.py text eol=lf
+scripts/tests/test_host_gate.py text eol=lf
+scripts/tests/test_bootstrap.py text eol=lf
 scripts/build_dist.py text eol=lf
-scripts/test_build_dist.py text eol=lf
+scripts/tests/test_build_dist.py text eol=lf
 scripts/skills_install.py text eol=lf
-scripts/test_skills_install.py text eol=lf
+scripts/tests/test_skills_install.py text eol=lf
 
 # The uv tool regenerates uv.lock with LF on every platform, so pin it here.
 # That makes git enforce LF on checkout and renormalize, so a CRLF-default repo does not fight the tool on every `uv lock` or `uv sync`.

.github/workflows/validate-task.yml

@@ -80,6 +80,20 @@ jobs:
               Write-Host "no findings"
             '
 
+      # The Python lint and type gates for the Scripts profile, CODESTYLE.md "Python".
+      # @latest rather than a version pin, since a `uvx <tool>@<ver>` pin is nothing Dependabot tracks and would silently go stale, where the action SHA below is tracked.
+      - name: Setup uv step
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          # The interpreter for the uv-run steps matches the pyproject py313 target, bumped in lockstep with it.
+          python-version: "3.13"
+
+      - name: Lint Python step
+        run: uvx ruff@latest check .
+
+      - name: Type check Python step
+        run: uvx mypy@latest
+
       - name: Validate registry and spec step
         run: |
           set -Eeuo pipefail
@@ -89,23 +103,19 @@ jobs:
           python3 spec/validate.py
 
       # Each gate here is proven by a case that reintroduces the fault it catches, wherever it lives.
-      # A test sits with the layer that owns it rather than beside the file it names, so a read-only gate over the spec and the host tooling is scripts/ even where its subject is shell, and the agent-safety kit carries its own because it ships as a unit.
-      # Standard library only, so no install step and no dependency to pin.
+      # A test sits with the layer that owns it rather than beside the file it names, so a read-only gate over the spec and the host tooling lives in scripts/tests/ even where its subject is shell, and the agent-safety kit carries its own because it ships as a unit.
+      # The tests are standard library only, so uvx coverage at its unpinned latest is the one tool the step fetches.
       # The audit engine self-test is offline, so it runs here rather than only on an owner sweep.
       # The write-guard self-test is offline too, and it otherwise runs only when a host installs the hook, which is where a regression in it would surface as a broken machine.
+      # Every run goes through coverage with --append, so one report covers the whole self-test surface, informational with no threshold adopted.
       - name: Run script self-tests step
         run: |
           set -Eeuo pipefail
-          python3 scripts/test_bootstrap.py
-          python3 scripts/test_host_gate.py
-          python3 scripts/test_prose_lint.py
-          python3 scripts/test_repo_gate.py
-          python3 scripts/test_pr_review.py
-          python3 scripts/test_build_dist.py
-          python3 scripts/test_skills_install.py
-          python3 spec/audit.py --selftest
-          python3 host-setup/agent-safety/gh-write-guard.py --selftest
-          python3 host-setup/agent-safety/test_install.py
+          uvx coverage@latest run --source=scripts,spec,host-setup -m unittest discover -s scripts/tests
+          uvx coverage@latest run --source=scripts,spec,host-setup --append spec/audit.py --selftest
+          uvx coverage@latest run --source=scripts,spec,host-setup --append host-setup/agent-safety/gh-write-guard.py --selftest
+          uvx coverage@latest run --source=scripts,spec,host-setup --append host-setup/agent-safety/test_install.py
+          uvx coverage@latest report
 
       - name: Check repo gates step
         run: python3 scripts/repo_gate.py

CODESTYLE.md

@@ -51,7 +51,7 @@ This is packaged as the `python-codestyle` Skill at `.agents/skills/python-codes
 
 ## Shell
 
-Bash, and only where a program cannot be Python: a bootstrap that installs the interpreter cannot be written in it, and a host tool that must run before a development toolchain exists cannot depend on one. Everything else is Python, with a test beside it. The mandatory `set -Eeuo pipefail` header, the pipefail-versus-early-reader pitfall, self-locating scripts, `shellcheck` cleanliness, and the why-not-what comment rule are packaged as the `shell-codestyle` Skill at `.agents/skills/shell-codestyle/SKILL.md` in the hub, not a repo-relative link since that path is hub-local and not carried into every fleet repo. Read the skill for the full rules.
+Bash, and only where a program cannot be Python: a bootstrap that installs the interpreter cannot be written in it, and a host tool that must run before a development toolchain exists cannot depend on one. Everything else is Python, with a test under the scripts tree's `tests/` directory. The mandatory `set -Eeuo pipefail` header, the pipefail-versus-early-reader pitfall, self-locating scripts, `shellcheck` cleanliness, and the why-not-what comment rule are packaged as the `shell-codestyle` Skill at `.agents/skills/shell-codestyle/SKILL.md` in the hub, not a repo-relative link since that path is hub-local and not carried into every fleet repo. Read the skill for the full rules.
 
 <!-- Repo -->
 

GOVERNANCE.md

@@ -306,7 +306,7 @@ Every repo's GitHub repository details (the About panel) follow a fixed conventi
 - [`registry/repos.json`](./registry/repos.json): the fleet registry, holding every project, its type(s), and its status.
 - [`repo-config/`](./repo-config/): branch rulesets, the fleet settings, and the apply script every repo is configured by, kept out of `.github/` (which is Actions-owned). The payloads carry to the fleet and the script is reached here.
 - [`catalog/`](./catalog/): reusable reference snippets (workflows, configs, devcontainers) the audit compares implementations against.
-- [`scripts/`](./scripts/): the fleet's lint and review tooling, with the deterministic checks also gating CI, for the documented rules no CI linter checks. Hosted here and reached rather than carried, per "Hub-Hosted Tooling".
+- [`scripts/`](./scripts/): the fleet's lint and review tooling, with the deterministic checks also gating CI, for the documented rules no CI linter checks. Its unit tests sit apart under [`scripts/tests/`](./scripts/tests/). Hosted here and reached rather than carried, per "Hub-Hosted Tooling".
 - [`docs/`](./docs/): hub-only procedure and measurement docs (host setup, config carry, signing, agent token cost), none of them carried downstream.
 - [`reports/`](./reports/): per-repo audit output.
 - [`.github/workflows/`](./.github/workflows/): this repo's own lint-only CI and source-only release, the workflow contract it dogfoods.