From ca54a959406452bcec8ca42784bf3f0a737ec1a9 Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Fri, 14 Aug 2026 11:49:00 -0700
Subject: [PATCH 1/3] Add Python Tooling to CI and Move the Script Tests to
 scripts/tests

CI carried no ruff, mypy, or coverage step, so the hub failed the
zero-warnings bar it asks downstream Python for: 88 ruff findings and
5 mypy errors at the configured contract. This fixes every finding,
adds the Python gates to validate-task.yml, moves the unit tests to
scripts/tests/, documents the gate-versus-utility naming split, and
amends the lint-only profile law to carry Python tooling in CI,
coverage included.

Closes #700
---
 .agents/skills/python-codestyle/SKILL.md      | 17 ++--
 .agents/skills/shell-codestyle/SKILL.md       |  2 +-
 .agents/skills/skill-lifecycle/SKILL.md       |  2 +-
 .claude-plugin/fleet-skills/.source-digest    |  2 +-
 .../skills/python-codestyle/SKILL.md          | 17 ++--
 .../skills/shell-codestyle/SKILL.md           |  2 +-
 .../skills/skill-lifecycle/SKILL.md           |  2 +-
 .editorconfig                                 |  5 +-
 .gitattributes                                | 14 +--
 .github/workflows/validate-task.yml           | 29 +++---
 CODESTYLE.md                                  |  2 +-
 GOVERNANCE.md                                 |  2 +-
 OPERATIONS.md                                 | 15 ++-
 TODO.md                                       |  2 +-
 docs/fleet-map.md                             |  8 +-
 host-setup/README.md                          |  4 +-
 host-setup/agent-safety/gh-write-guard.py     | 23 +++--
 host-setup/agent-safety/install.py            |  9 +-
 host-setup/agent-safety/test_install.py       |  6 +-
 host-setup/windows/README.md                  |  4 +-
 scripts/README.md                             | 17 ++--
 scripts/host_gate.py                          | 10 +-
 scripts/pr_review.py                          | 24 ++---
 scripts/prose_lint.py                         | 22 ++---
 scripts/repo_gate.py                          |  6 +-
 scripts/skills_install.py                     |  6 +-
 scripts/{ => tests}/test_bootstrap.py         |  6 +-
 scripts/{ => tests}/test_build_dist.py        |  4 +-
 scripts/{ => tests}/test_host_gate.py         |  2 +-
 scripts/{ => tests}/test_pr_review.py         | 74 +++++++-------
 scripts/{ => tests}/test_prose_lint.py        | 13 +--
 scripts/{ => tests}/test_repo_gate.py         |  5 +-
 scripts/{ => tests}/test_skills_install.py    | 38 ++++----
 spec/audit.py                                 | 97 ++++++++++---------
 spec/fidelity_honesty.py                      |  0
 spec/host-tools.json                          |  4 +-
 spec/project-types.json                       |  2 +-
 spec/validate.py                              | 12 +--
 38 files changed, 272 insertions(+), 237 deletions(-)
 mode change 100644 => 100755 host-setup/agent-safety/gh-write-guard.py
 mode change 100644 => 100755 host-setup/agent-safety/install.py
 mode change 100644 => 100755 host-setup/agent-safety/test_install.py
 mode change 100644 => 100755 scripts/pr_review.py
 mode change 100644 => 100755 scripts/prose_lint.py
 mode change 100644 => 100755 scripts/repo_gate.py
 rename scripts/{ => tests}/test_bootstrap.py (99%)
 rename scripts/{ => tests}/test_build_dist.py (98%)
 rename scripts/{ => tests}/test_host_gate.py (99%)
 rename scripts/{ => tests}/test_pr_review.py (98%)
 mode change 100644 => 100755
 rename scripts/{ => tests}/test_prose_lint.py (99%)
 mode change 100644 => 100755
 rename scripts/{ => tests}/test_repo_gate.py (99%)
 mode change 100644 => 100755
 rename scripts/{ => tests}/test_skills_install.py (92%)
 mode change 100644 => 100755 spec/audit.py
 mode change 100644 => 100755 spec/fidelity_honesty.py
 mode change 100644 => 100755 spec/validate.py

diff --git a/.agents/skills/python-codestyle/SKILL.md b/.agents/skills/python-codestyle/SKILL.md
index 34662c92..68aeaed9 100644
--- a/.agents/skills/python-codestyle/SKILL.md
+++ b/.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
 
diff --git a/.agents/skills/shell-codestyle/SKILL.md b/.agents/skills/shell-codestyle/SKILL.md
index 91f40af5..5064582d 100644
--- a/.agents/skills/shell-codestyle/SKILL.md
+++ b/.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
 
diff --git a/.agents/skills/skill-lifecycle/SKILL.md b/.agents/skills/skill-lifecycle/SKILL.md
index bce071d4..92972b0f 100644
--- a/.agents/skills/skill-lifecycle/SKILL.md
+++ b/.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.
 
diff --git a/.claude-plugin/fleet-skills/.source-digest b/.claude-plugin/fleet-skills/.source-digest
index d14fbfc1..2a30d312 100644
--- a/.claude-plugin/fleet-skills/.source-digest
+++ b/.claude-plugin/fleet-skills/.source-digest
@@ -1 +1 @@
-f1e6675e6e015c18
+676ab1e915338dd7
diff --git a/.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md b/.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md
index 34662c92..68aeaed9 100644
--- a/.claude-plugin/fleet-skills/skills/python-codestyle/SKILL.md
+++ b/.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
 
diff --git a/.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md b/.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md
index 91f40af5..5064582d 100644
--- a/.claude-plugin/fleet-skills/skills/shell-codestyle/SKILL.md
+++ b/.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
 
diff --git a/.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md b/.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md
index bce071d4..92972b0f 100644
--- a/.claude-plugin/fleet-skills/skills/skill-lifecycle/SKILL.md
+++ b/.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.
 
diff --git a/.editorconfig b/.editorconfig
index 2ef0c084..b4571269 100644
--- a/.editorconfig
+++ b/.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.
diff --git a/.gitattributes b/.gitattributes
index e4eb1500..3ccb1caf 100644
--- a/.gitattributes
+++ b/.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`.
diff --git a/.github/workflows/validate-task.yml b/.github/workflows/validate-task.yml
index ed9ac5c0..d3c2adb0 100644
--- a/.github/workflows/validate-task.yml
+++ b/.github/workflows/validate-task.yml
@@ -80,6 +80,17 @@ 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
+
+      - 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 +100,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.
+      # 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.
       # Standard library only, so no install step and no dependency to pin.
       # 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
diff --git a/CODESTYLE.md b/CODESTYLE.md
index 4e85088d..b8c3d004 100644
--- a/CODESTYLE.md
+++ b/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 -->
 
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
index b2acb8e2..be38ed0d 100644
--- a/GOVERNANCE.md
+++ b/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.
diff --git a/OPERATIONS.md b/OPERATIONS.md
index ffb62f89..59bd1472 100644
--- a/OPERATIONS.md
+++ b/OPERATIONS.md
@@ -11,11 +11,14 @@ What verifying a change here requires, including the part CI cannot perform. The
 CI passes explicit `--check` lists, and a bare `python3 scripts/prose_lint.py [file]` runs `DEFAULT_RULES`, which is those two lists together. What differs is the exit code rather than the coverage. CI gates on nine of the ten and reports `charset-unknown` warn-only, where a bare run exits non-zero on any of the ten. `sentence-split` and `sentence-length` are in neither, so nothing below runs them and a local run reaches them only by naming them. Run the CI invocations:
 
 ```sh
-python3 scripts/test_prose_lint.py
-python3 scripts/test_repo_gate.py
-python3 scripts/test_pr_review.py
-python3 spec/audit.py --selftest
-python3 host-setup/agent-safety/gh-write-guard.py --selftest
+uvx ruff@latest check .
+uvx mypy@latest
+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
+python3 scripts/build_dist.py --check
 python3 scripts/repo_gate.py
 python3 scripts/prose_lint.py . --check charset --check semicolon --check dash --check dupword --check spelling --check comment-wrap --check comment-case --check home-path --check dead-path
 python3 scripts/prose_lint.py . --check charset-unknown --summary
@@ -26,6 +29,8 @@ scripts=(); while IFS= read -r f; do scripts+=("$f"); done < <(git ls-files '*.s
 docker run --rm --pull=always -e PS_SCRIPTS="$(git ls-files '*.ps1')" -v "$PWD":/mnt --workdir /mnt mcr.microsoft.com/powershell:latest pwsh -NoProfile -Command 'Set-PSRepository PSGallery -InstallationPolicy Trusted; Install-Module PSScriptAnalyzer -RequiredVersion 1.23.0 -Force -Scope AllUsers; Import-Module PSScriptAnalyzer; $files = $env:PS_SCRIPTS -split "\s+" | Where-Object { $_ }; if (-not $files) { Write-Host "no PowerShell scripts are tracked"; exit 0 }; $found = @(); foreach ($f in $files) { $found += Invoke-ScriptAnalyzer -Path $f -Settings ./PSScriptAnalyzerSettings.psd1 }; Write-Host "Checked $($files.Count) file(s)"; if ($found) { $found | Format-Table RuleName,Severity,ScriptName,Line,Message -AutoSize | Out-String -Width 200 | Write-Host; exit 1 }; Write-Host "no findings"'
 ```
 
+The `test_install.py` line behaves differently here than in CI, stated so its failure reads as the verdict it is. Its report cases install from this checkout and assert the machine then reads as current. An install from a checkout carrying uncommitted changes records a dirty stamp that reads as stale. So on a working tree mid-change those cases fail by design where CI's clean checkout passes. The remedy is to run them again once the change is committed, not to read the failure as a regression.
+
 The two container lines that take a file list differ from the workflow in **form** and not in what they check, and both differences exist because this runbook runs on a developer's machine where the workflow runs on `ubuntu-latest`. The shell list is collected with a `while read` loop rather than the workflow's `mapfile`, since `mapfile` arrives in bash 4 and macOS ships 3.2, and it stays an array so a path carrying whitespace is still passed as one argument. The PowerShell list splits on whitespace rather than on a newline, since a shell joins `git ls-files` output with newlines and PowerShell joins it with spaces, and splitting on the newline alone hands the analyzer one argument holding every path, which it reports as one file it cannot find and a clean run over nothing.
 
 Two gaps in that list are CI's rather than this runbook's, reproduced here so a local run matches CI rather than quietly exceeding it. The `jq` glob covers `repo-config/*.json` and does not reach `repo-config/operational/develop.json`, so a malformed operational payload passes. The second is that `sentence-split` and `sentence-length` are implemented and tested but named by no invocation, so nothing runs them.
diff --git a/TODO.md b/TODO.md
index a30a8903..c838bd41 100644
--- a/TODO.md
+++ b/TODO.md
@@ -468,7 +468,7 @@ Small work with no research to preserve, selectable one bullet at a time.
 
 - **Answer the symmetric reading of [`.editorconfig`][editorconfig], a path-specific section naming files that do not exist**, which is the half of [#633][issue-633] the `eol-coverage` check deliberately left open. The dead-pin reading it does ship is the `.gitattributes` side, and the same question on the other document is not the same shape: this repo's `[.github/workflows/*]` and `[catalog/snippets/workflows/*]` sections are legitimately broad, and the issue's own first attempt at it produced false positives because the matcher did not expand brace syntax, which [`scripts/repo_gate.py`][repo-gate] already implements. Measure the exemption against the live corpus before building the gate rather than after, since a stale exemption hands out a work list that damages correct documents, and decide whether `forward-declared` carries across or whether an editorconfig section needs its own marker.
 - **Reconsider whether the pre-commit hook runs the doc gates now that they are diff-scoped.** [`scripts/README.md`][scripts] records the current decision and its reason, that doc linters stay out of the hook so it stays fast, which was sound when the only mode was a whole-tree sweep, and a diff-scoped run finishes in about a second. The failure it would prevent is the most repeated one on record, comment sentences wrapped across lines caught after the commit rather than before it. Weigh it against the standing preference for a fast hook. The other objection, a hook running the gate from the wrong directory and reporting its own false clean, no longer applies: the rule set, the file set, the diff, and the keys joining them are all read from the repository being scanned rather than from wherever the process stands.
-- **Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is cheaper.** The evidence is the review record rather than a language preference, since a non-trivial shell script earns findings round after round while every gate under [`scripts/`][scripts] carries a test file beside it and converges in one or two. The measure is lines, branch count, and the review rounds each has cost. `repo-config/configure.sh` and the agent-safety installer are the two worth measuring, and a bootstrap script that needs the Python it exists to install is not a rewrite worth having, which protects the installer more than the config script.
+- **Audit the fleet's shell surface by size and branching, and decide per script whether Python with unit tests is cheaper.** The evidence is the review record rather than a language preference, since a non-trivial shell script earns findings round after round while every gate under [`scripts/`][scripts] carries a test file under `scripts/tests/` and converges in one or two. The measure is lines, branch count, and the review rounds each has cost. `repo-config/configure.sh` and the agent-safety installer are the two worth measuring, and a bootstrap script that needs the Python it exists to install is not a rewrite worth having, which protects the installer more than the config script.
 - **Make a table of contents standard for a long document rather than for the README alone.** [`spec/readme-structure.md`][readme-structure] fixes one at README position 4 and no other hub file carries one, which leaves the three longest documents without it, `CODESTYLE.md` at 516 lines, `GOVERNANCE.md` at 436 and `WORKFLOW.md` at 301, measured on `develop` at `3d1a0b1` on 2026-08-06. Settle the threshold in headings or lines so the audit can check it, and settle how it sits with the reference-link exception, since the four agent-instruction files keep inline links exactly because they are read one section at a time, which is the property that makes a contents list worth having in them. The mechanical constraint is that the list is filled by the Markdown All in One extension on save, so a file nobody opens in the editor grows a stale list, which is worse than absent because it is read as current.
 - **Converge this repo's Python on the ruff configuration it already declares, then add the formatting half to the pre-commit hook.** `pyproject.toml` carries `[tool.ruff]` and [`spec/project-types.json`][project-types] declares `python.ruff.config`, yet no workflow runs ruff and the tree does not pass it, measured on `develop` at `6d020b1` on 2026-08-09 with ruff 0.16.2: `ruff format --check` reports 13 of 57 files would be reformatted, and `ruff check` reports 106 errors, of which 39 are auto-fixable. The largest groups are 24 `PLW1510` (a `subprocess.run` with no `check`), 17 `FURB167` (`re.M` for `re.MULTILINE`), 11 `EXE001` (a shebang on a non-executable file, which wants reading against the `eol-coverage` shebang set rather than fixed blindly), 9 `BLE001` and 9 `SIM117`. The hook deliberately ships without the ruff step for this reason, since a gate failing on the corpus it guards blocks every commit from the moment it lands, which is the measure-the-corpus-first rule applied to a gate rather than to an exemption. Decide whether CI gains a ruff job in the same pass, since a formatter enforced only by a hook is enforced only on the machines that enabled it.
 - **Adopt the OCI annotation keys for Docker image metadata across the Docker repos**, replacing the ad-hoc and label-schema keys, per [#363][issue-363].
diff --git a/docs/fleet-map.md b/docs/fleet-map.md
index e82755c3..dc86b6a1 100644
--- a/docs/fleet-map.md
+++ b/docs/fleet-map.md
@@ -174,7 +174,7 @@ Each gap's handoff below states who detects it, what closes it, and the test tha
 ### G2: Host-Tools Repo Overlay Is Silently Skippable (Closed)
 
 - **Gap** - [`scripts/host_gate.py`][host-gate] run without `--repo` read only the declaration at its own working directory, so a run started in a subdirectory of a repo carrying a `host-tools.json` overlay skipped that overlay without a word.
-- **Resolution** - A bare run whose working directory sits inside such a repo prints a warning naming the overlay's directory and the `--repo` re-run that counts it, asserted by the `TestBareRunOverlayWarning` cases in `scripts/test_host_gate.py`. An explicit `--repo` and `--no-local` each stay silent, since both are a choice the caller made. [`STANDUP.md`][standup] section 0 states the residual case the warning cannot cover, a target repo that does not exist yet, instead of the workaround sentence.
+- **Resolution** - A bare run whose working directory sits inside such a repo prints a warning naming the overlay's directory and the `--repo` re-run that counts it, asserted by the `TestBareRunOverlayWarning` cases in `scripts/tests/test_host_gate.py`. An explicit `--repo` and `--no-local` each stay silent, since both are a choice the caller made. [`STANDUP.md`][standup] section 0 states the residual case the warning cannot cover, a target repo that does not exist yet, instead of the workaround sentence.
 
 ### G3: A Failed Tool Floor Names No Install Remedy (Closed)
 
@@ -189,13 +189,13 @@ flowchart LR
   run --> recheck["re-run host_gate"] --> ok["proceed"]
 ```
 
-- **Closing test** - [`scripts/test_bootstrap.py`][test-bootstrap] asserts the mapping stays total per platform, with the one recorded not-applicable exception, and that a remedy handing back into an installer names a tool that installer manages. [`spec/validate.py`][validate] and the schema require a remedy on every hub floor. A repository overlay may still add a floor without one, in which case the failure degrades to the `INSTALL FROM:` source line.
+- **Closing test** - [`scripts/tests/test_bootstrap.py`][test-bootstrap] asserts the mapping stays total per platform, with the one recorded not-applicable exception, and that a remedy handing back into an installer names a tool that installer manages. [`spec/validate.py`][validate] and the schema require a remedy on every hub floor. A repository overlay may still add a floor without one, in which case the failure degrades to the `INSTALL FROM:` source line.
 
 ### G4: Deletion Sweeps Miss Prose (Closed)
 
 - **Gap** - A resync that deletes a carried file greps for the path and finds code uses, not prose describing the file without naming its path. A measured incident left a layout section describing a deleted script.
 - **Resolution** - Split by what a pattern can reach. The named-path half is mechanized: the `dead-path` rule in [`scripts/prose_lint.py`][prose-lint] reports a Markdown mention (a backtick span, an inline link target, or a reference definition) of a path git once tracked and the tree no longer holds. Keying on deletion history is what scopes it: a proposed file a backlog names, another repository's layout, and a ref like `origin/develop` each have no history here and stay silent, and a manifest-declared carried path is exempt since the hub's own instance retires to a catalog snippet while docs keep naming the carried file. The rule runs in the default set and in CI, where the checkout fetches full history because the rule stands down loudly in a shallow clone rather than pass blind. The name-shaped half, the description that names no path, is `accepted` as manual: no pattern reaches it, the same judgment the home-path rule records, so the [`RESYNC.md`][resync] section 4 read of the layout and operations sections stands and now names the lint beside it.
-- **Closing test** - `TestDeadPath` in `scripts/test_prose_lint.py`, including the shallow stand-down and the tree-clean assertion. The rule's first tree-wide run caught a real instance, [`docs/host-setup.md`][host-setup-doc] describing bind-mounts in the deleted `.devcontainer/` definitions, fixed by re-pointing at the catalog snippets.
+- **Closing test** - `TestDeadPath` in `scripts/tests/test_prose_lint.py`, including the shallow stand-down and the tree-clean assertion. The rule's first tree-wide run caught a real instance, [`docs/host-setup.md`][host-setup-doc] describing bind-mounts in the deleted `.devcontainer/` definitions, fixed by re-pointing at the catalog snippets.
 
 ### G5: Intent-Fidelity Drift Is Invisible (Closed)
 
@@ -369,7 +369,7 @@ Design-doc first: this doc merges, then each unchecked item becomes an issue lin
 [skills-install]: ../scripts/skills_install.py
 [skills-readme]: ../.agents/skills/README.md
 [standup]: ../STANDUP.md
-[test-bootstrap]: ../scripts/test_bootstrap.py
+[test-bootstrap]: ../scripts/tests/test_bootstrap.py
 [todo]: ../TODO.md
 [validate]: ../spec/validate.py
 [validate-task]: ../.github/workflows/validate-task.yml
diff --git a/host-setup/README.md b/host-setup/README.md
index a6337505..6b5e8a46 100644
--- a/host-setup/README.md
+++ b/host-setup/README.md
@@ -77,7 +77,7 @@ host-setup\windows\setup-wsl.ps1 -Status
 
 **Group by whichever axis has one member.** `agent-safety/` is one concern across three platforms, so it is a concern directory holding `install.sh`, `install.ps1` and `install.py`. `linux/` is three concerns on one platform, so it is a platform directory. Windows host tooling therefore sits at `windows/` rather than beside the Linux scripts, because the `winget` equivalent of `install-tools.sh` is a different program rather than a translation of one. It carries one registry record per tool where the Linux script carries four functions, since every Windows source is `winget` and the per-tool variation those functions exist for does not arise. `windows/` also carries a fourth script with no Linux peer, because WSL is a Windows-side concern. The loader is the same shape as `agent-safety/`, not as `linux/`/`windows/`: one concern, two platforms, so `bootstrap.ps1` sits beside `bootstrap.sh` at the top level rather than inside `windows/`.
 
-**Nothing here needs Python to stand a host up, and neither loader needs an interpreter to fetch what it drives.** [`docs/host-setup.md`][host-setup] carries that as part of the contract, with the reasoning. `bootstrap.sh` needs only `curl` and `tar`. `bootstrap.ps1` needs only `tar.exe`, which has shipped with Windows since 1803, and installs its one further dependency, `pwsh`, itself through `winget`. The one exception is the `install-skills` pair, which drives the Python installer at `scripts/skills_install.py` and runs last in a stand-up for exactly that reason: `install-tools` has provided the interpreter by then, and run alone on a host without one it stops and names the tools step as its prerequisite. Neither loader runs a gate as a closing step: [`scripts/host_gate.py`][host-gate] measures a host against the floors and is not called from here, and nothing here is called from it. A host set up by hand years ago is an ordinary host, so the gate reports what it is missing and running this tooling is a remedy a person chooses. The two are joined at code time instead, by [`scripts/test_bootstrap.py`][test-bootstrap] asserting that every tool the spec requires is one this tooling can provide.
+**Nothing here needs Python to stand a host up, and neither loader needs an interpreter to fetch what it drives.** [`docs/host-setup.md`][host-setup] carries that as part of the contract, with the reasoning. `bootstrap.sh` needs only `curl` and `tar`. `bootstrap.ps1` needs only `tar.exe`, which has shipped with Windows since 1803, and installs its one further dependency, `pwsh`, itself through `winget`. The one exception is the `install-skills` pair, which drives the Python installer at `scripts/skills_install.py` and runs last in a stand-up for exactly that reason: `install-tools` has provided the interpreter by then, and run alone on a host without one it stops and names the tools step as its prerequisite. Neither loader runs a gate as a closing step: [`scripts/host_gate.py`][host-gate] measures a host against the floors and is not called from here, and nothing here is called from it. A host set up by hand years ago is an ordinary host, so the gate reports what it is missing and running this tooling is a remedy a person chooses. The two are joined at code time instead, by [`scripts/tests/test_bootstrap.py`][test-bootstrap] asserting that every tool the spec requires is one this tooling can provide.
 
 **The scripts under `linux/` and `windows/` share no file, and the duplication is deliberate.** Each is independently fetchable and runnable on its own, which is the property that lets a host with no checkout use one without the others. A shared helper file would take that away: the moment one script sources a sibling, fetching it alone yields a script that dies on a missing file. What is duplicated is about thirty lines each of logging, the dry-run wrapper, the confirmation prompt, and a temporary directory, and those copies are identical rather than merely similar. Do not factor them out. `bootstrap.ps1` now exercises the same fetchability argument `bootstrap.sh` always has, rather than merely being written to allow for it. The `install-skills` pair is the one recorded exception to independent fetchability: it drives `scripts/skills_install.py` at the tree root, because the skills content lives in the tree, so a copy fetched alone has nothing to install and the property cannot apply to it.
 
@@ -90,5 +90,5 @@ host-setup\windows\setup-wsl.ps1 -Status
 [host-gate]: ../scripts/host_gate.py
 [host-setup]: ../docs/host-setup.md
 [linux]: ./linux/
-[test-bootstrap]: ../scripts/test_bootstrap.py
+[test-bootstrap]: ../scripts/tests/test_bootstrap.py
 [windows]: ./windows/
diff --git a/host-setup/agent-safety/gh-write-guard.py b/host-setup/agent-safety/gh-write-guard.py
old mode 100644
new mode 100755
index 351265eb..a2d518d4
--- a/host-setup/agent-safety/gh-write-guard.py
+++ b/host-setup/agent-safety/gh-write-guard.py
@@ -113,9 +113,10 @@ def _origin_owner_repo(cwd):
     try:
         url = subprocess.run(
             ["git", "-C", cwd or ".", "remote", "get-url", "origin"],
-            capture_output=True, text=True, timeout=5,
+            capture_output=True, text=True, timeout=5, check=False,
         ).stdout.strip()
-    except Exception:
+    # A checkout with no usable origin is answered as unknown rather than crashing the hook.
+    except Exception:  # noqa: BLE001
         return None
     m = re.search(r"[:/]([A-Za-z0-9_.\-]+)/([A-Za-z0-9_.\-]+?)(?:\.git)?/?$", url)
     return (m.group(1).lower(), m.group(2).lower()) if m else None
@@ -163,15 +164,17 @@ def _live_branch_rules(owner, repo, branch):
         r = subprocess.run(
             # Quote the branch, since a name carrying `/`, such as feature/x, would otherwise split the API path.
             ["gh", "api", f"repos/{owner}/{repo}/rules/branches/{quote(branch, safe='')}", "--jq", "[.[].type]"],
-            capture_output=True, text=True, timeout=10,
+            capture_output=True, text=True, timeout=10, check=False,
         )
-    except Exception:
+    # Any failure to query means unknown, so the caller can fail closed instead of the hook crashing.
+    except Exception:  # noqa: BLE001
         return None
     if r.returncode != 0:
         return None
     try:
         return set(json.loads(r.stdout or "[]"))
-    except Exception:
+    # Unparseable output also means unknown rather than a crash.
+    except Exception:  # noqa: BLE001
         return None
 
 
@@ -182,8 +185,9 @@ def _current_push_branch(cwd):
         ["rev-parse", "--abbrev-ref", "HEAD"],
     ):
         try:
-            r = subprocess.run(["git", "-C", cwd or ".", *args], capture_output=True, text=True, timeout=5)
-        except Exception:
+            r = subprocess.run(["git", "-C", cwd or ".", *args], capture_output=True, text=True, timeout=5, check=False)
+        # The hook must answer on any failure rather than crash.
+        except Exception:  # noqa: BLE001
             return None
         ref = r.stdout.strip()
         if r.returncode == 0 and ref and ref != "HEAD":
@@ -479,7 +483,7 @@ def classify(cmd, cwd=None, origin=None, current_branch=None, rules_lookup=None,
     if _GRAPHQL.search(cmd) and _MUTATION.search(cmd):
         for m in _FIELD_ASSIGN.finditer(cmd):
             val = m.group("v").strip("'\"")
-            if val.startswith("$") or val.startswith("${"):
+            if val.startswith(("$", "${")):
                 continue
             if _NODE_ID_LITERAL.match(val):
                 return "deny", (
@@ -680,7 +684,8 @@ def _selftest():
 def _main():
     try:
         data = json.load(sys.stdin)
-    except Exception:
+    # The hook must never crash on input it does not recognize.
+    except Exception:  # noqa: BLE001
         sys.exit(0)  # not our event shape - do not interfere
     if data.get("tool_name") != "Bash":
         sys.exit(0)
diff --git a/host-setup/agent-safety/install.py b/host-setup/agent-safety/install.py
old mode 100644
new mode 100755
index 5156c773..19197fec
--- a/host-setup/agent-safety/install.py
+++ b/host-setup/agent-safety/install.py
@@ -130,7 +130,7 @@ def git(*args):
         # A host with no git is the normal case for a tarball install, and it is not an error here.
         # Letting FileNotFoundError escape would crash both the install and the read-only report.
         try:
-            r = subprocess.run(["git", "-C", str(HERE), *args], capture_output=True, text=True)
+            r = subprocess.run(["git", "-C", str(HERE), *args], capture_output=True, text=True, check=False)
         except OSError:
             return None
         return r.stdout.strip() if r.returncode == 0 else None
@@ -417,9 +417,6 @@ def main():
                         help="read-only: compare this machine's stamp against this checkout and exit")
     args = parser.parse_args()
 
-    if sys.version_info < (3, 7):
-        sys.stderr.write("This installer and the hook require Python 3.7+. Run it with python3.\n")
-        return 1
     # Expanduser resolves a CLAUDE_HOME set in `~/...` form to the home dir rather than a literal `~` dir.
     claude_home_env = os.environ.get("CLAUDE_HOME")
     claude_home = pathlib.Path(claude_home_env).expanduser() if claude_home_env else pathlib.Path.home() / ".claude"
@@ -442,7 +439,7 @@ def main():
     except OSError:
         pass
     print(f"  hook -> {hook_dst}")
-    r = subprocess.run([sys.executable, str(hook_dst), "--selftest"], capture_output=True, text=True)
+    r = subprocess.run([sys.executable, str(hook_dst), "--selftest"], capture_output=True, text=True, check=False)
     if r.returncode != 0:
         sys.stderr.write("Hook self-test FAILED; aborting before registration.\n" + r.stdout + r.stderr)
         return 1
@@ -590,7 +587,7 @@ def once(_match, _snippet=snippet, _written=written):
     # 5. Stamp the machine, written last so it records a completed install rather than an attempted one.
     # The blocks are read back off disk here, so the stamp reports what CLAUDE.md holds rather than what was intended.
     stamp_path = claude_home / "agent-safety-stamp.json"
-    stamp = build_stamp(claude_home, datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"))
+    stamp = build_stamp(claude_home, datetime.datetime.now(datetime.UTC).strftime("%Y-%m-%dT%H:%M:%SZ"))
     stamp_path.write_text(json.dumps(stamp, indent=2) + "\n", encoding="utf-8")
     print(f"  stamp -> {stamp_path}")
 
diff --git a/host-setup/agent-safety/test_install.py b/host-setup/agent-safety/test_install.py
old mode 100644
new mode 100755
index 550faaaf..b8f3f402
--- a/host-setup/agent-safety/test_install.py
+++ b/host-setup/agent-safety/test_install.py
@@ -20,14 +20,14 @@
 INSTALL = HERE / "install.py"
 
 sys.path.insert(0, str(HERE))
-import install  # noqa: E402
+import install
 
 
 def run(home, *args):
     """Invoke the installer as a subprocess, the way a host actually runs it."""
     env = dict(os.environ, CLAUDE_HOME=str(home))
     return subprocess.run([sys.executable, str(INSTALL), *args],
-                          capture_output=True, text=True, env=env)
+                          capture_output=True, text=True, env=env, check=False)
 
 
 class StampCase(unittest.TestCase):
@@ -198,7 +198,7 @@ class TestDegradedEnvironments(StampCase):
     def test_a_host_without_git_stamps_rather_than_crashing(self):
         """A tarball install on a minimal host has no git, which is normal rather than an error."""
         env = dict(os.environ, CLAUDE_HOME=str(self.home), PATH="")
-        r = subprocess.run([sys.executable, str(INSTALL)], capture_output=True, text=True, env=env)
+        r = subprocess.run([sys.executable, str(INSTALL)], capture_output=True, text=True, env=env, check=False)
         self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
         stamp = json.loads(self.stamp.read_text(encoding="utf-8"))
         self.assertEqual(stamp["source"]["vcs"], "none")
diff --git a/host-setup/windows/README.md b/host-setup/windows/README.md
index 9a561dea..86f5aba2 100644
--- a/host-setup/windows/README.md
+++ b/host-setup/windows/README.md
@@ -124,7 +124,7 @@ host-setup\windows\setup-wsl.ps1 -Install Debian -DryRun
 
 Two of those are guards rather than previews, and each prints a refusal rather than a command: `upgrade-host.ps1 -Wsl -DryRun` on a host running Docker Desktop, and an `-Upgrade` whose `-Scope` disagrees with the installed copy. A `[dry run]` line from either means the guard sits in the wrong place.
 
-The scripts are checked by `PSScriptAnalyzer`, which runs in CI as the peer of the `shellcheck` step and locally through the invocation in [`GOVERNANCE.md`][governance]. [`scripts/test_bootstrap.py`][test-bootstrap] asserts that every tool the spec requires is one this registry carries, and that no script here opens with a shebang.
+The scripts are checked by `PSScriptAnalyzer`, which runs in CI as the peer of the `shellcheck` step and locally through the invocation in [`GOVERNANCE.md`][governance]. [`scripts/tests/test_bootstrap.py`][test-bootstrap] asserts that every tool the spec requires is one this registry carries, and that no script here opens with a shebang.
 
 <!-- Repo -->
 
@@ -137,5 +137,5 @@ The scripts are checked by `PSScriptAnalyzer`, which runs in CI as the peer of t
 [install-tools]: ./install-tools.ps1
 [setup-github]: ./setup-github.ps1
 [setup-wsl]: ./setup-wsl.ps1
-[test-bootstrap]: ../../scripts/test_bootstrap.py
+[test-bootstrap]: ../../scripts/tests/test_bootstrap.py
 [upgrade-host]: ./upgrade-host.ps1
diff --git a/scripts/README.md b/scripts/README.md
index 7803d410..4f136161 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -6,16 +6,16 @@ The fleet's checks and review tooling, run by hand, with the deterministic ones
 
 Python only, standard library only, no third-party packages. Every check script is read-only and exits non-zero on a finding. `build_dist.py` and `skills_install.py` below are the two exceptions, since a generator and an installer both exist to write, and each still offers a read-only mode (`--check`, `--report`) for CI and for asking without changing anything.
 
-Each script has a `test_<script>.py` beside it, driving its gates against input they must reject, because a gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
+The directory separates its kinds by name and by tree. A gate checks and exits non-zero on a finding, and its name carries a `_lint` or `_gate` suffix saying what it gates. `prose_lint.py` and `repo_gate.py` gate this tree in CI, and `host_gate.py` gates the machine it runs on. A utility does work rather than gating and carries no suffix: `build_dist.py`, `pr_review.py`, `skills_install.py`. The unit tests live apart under [`scripts/tests/`][tests], one `test_<script>.py` per script, driving its gates against input they must reject. A gate nobody has watched fail is a gate nobody knows works. Where a case covers a table it reads the live table rather than restating it, and each one asserts a floor on what a healthy run reaches, since a check whose scan matches nothing reports zero findings and reads exactly like a pass.
 
 ```sh
-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 -m unittest discover -s scripts          # all of them, and exits 5 if the suite vanishes
-uvx coverage@latest run --source=. -m unittest discover -s scripts && uvx coverage@latest report
+python3 scripts/tests/test_prose_lint.py
+python3 scripts/tests/test_repo_gate.py
+python3 scripts/tests/test_pr_review.py
+python3 scripts/tests/test_build_dist.py
+python3 scripts/tests/test_skills_install.py
+python3 -m unittest discover -s scripts/tests    # all of them, and exits 5 if the suite vanishes
+uvx coverage@latest run --source=scripts,spec,host-setup -m unittest discover -s scripts/tests && uvx coverage@latest report
 ```
 
 ## `prose_lint.py`
@@ -225,3 +225,4 @@ Installs the fleet's Skills for the current machine, cross-platform and idempote
 [prose-gate-action]: ../.github/actions/prose-gate/action.yml
 [repos]: ../registry/repos.json
 [section-model]: ../spec/section-model.md
+[tests]: ./tests/
diff --git a/scripts/host_gate.py b/scripts/host_gate.py
index 64b4756e..e15a1e4c 100755
--- a/scripts/host_gate.py
+++ b/scripts/host_gate.py
@@ -68,7 +68,7 @@ def probe(argv: list[str]) -> str | None:
     the exit code decides and a failing probe falls through to the next one.
     """
     try:
-        p = subprocess.run(argv, capture_output=True, text=True, timeout=20)
+        p = subprocess.run(argv, capture_output=True, text=True, timeout=20, check=False)
     except (OSError, subprocess.SubprocessError):
         return None
     if p.returncode != 0:
@@ -128,9 +128,9 @@ def field_problems(entry: dict) -> list[str]:
         problems.append('why must be a non-empty string')
     if 'required' in entry and not isinstance(entry['required'], bool):
         problems.append(f'required must be true or false, not {entry["required"]!r}')
-    if 'minimum' in entry and entry['minimum'] is not None:
-        if not isinstance(entry['minimum'], str) or parse_version(entry['minimum']) is None:
-            problems.append(f'minimum must be dot-separated integers or null, not {entry["minimum"]!r}')
+    if ('minimum' in entry and entry['minimum'] is not None
+            and (not isinstance(entry['minimum'], str) or parse_version(entry['minimum']) is None)):
+        problems.append(f'minimum must be dot-separated integers or null, not {entry["minimum"]!r}')
     if 'source' in entry and not isinstance(entry['source'], dict):
         problems.append('source must be an object')
     if 'remedy' in entry and not isinstance(entry['remedy'], dict):
@@ -201,7 +201,7 @@ def contract_problems(tools: list[dict]) -> list[str]:
             if not isinstance(src[plat], str) or not src[plat]:
                 problems.append(f'{name} source.{plat} is empty, so a host on that platform is told to upgrade and not where from')
         # The remedy is shape-checked and not required, so a repository floor without one degrades to the source line rather than failing the merge.
-        # Requiring it fleet-wide is the hub declaration's contract, held by spec/validate.py and scripts/test_bootstrap.py rather than here.
+        # Requiring it fleet-wide is the hub declaration's contract, held by spec/validate.py and scripts/tests/test_bootstrap.py rather than here.
         rem = t.get('remedy')
         if rem is not None and not isinstance(rem, dict):
             problems.append(f'{name} remedy must be an object keyed by platform, so its command was not read')
diff --git a/scripts/pr_review.py b/scripts/pr_review.py
old mode 100644
new mode 100755
index 9ad74dce..f631faf8
--- a/scripts/pr_review.py
+++ b/scripts/pr_review.py
@@ -379,7 +379,7 @@ def gh_graphql(query: str, **variables) -> dict:
     argv = ['gh', 'api', 'graphql', '-f', f'query={query}']
     for name, value in variables.items():
         argv += ['-F' if isinstance(value, int) else '-f', f'{name}={value}']
-    r = subprocess.run(argv, capture_output=True, text=True, encoding='utf-8')
+    r = subprocess.run(argv, capture_output=True, text=True, encoding='utf-8', check=False)
     if r.returncode != 0:
         sys.stderr.write(r.stderr[:800])
         raise SystemExit(f'gh graphql failed rc={r.returncode}')
@@ -406,7 +406,7 @@ def timeline(owner: str, repo: str, num: int) -> list[tuple[str, str]]:
     r = subprocess.run(
         ['gh', 'api', '--paginate', f'repos/{owner}/{repo}/issues/{num}/timeline?per_page=100',
          '--jq', TIMELINE_JQ],
-        capture_output=True, text=True, encoding='utf-8')
+        capture_output=True, text=True, encoding='utf-8', check=False)
     if r.returncode != 0:
         sys.stderr.write(r.stderr[:800])
         raise SystemExit(f'gh timeline failed rc={r.returncode}')
@@ -684,10 +684,10 @@ def file_table(body: str) -> list[str]:
     for line in FENCE.sub('', body or '').splitlines():
         if TABLE_HEADER.match(line):
             reading = True
-        elif not TABLE_ROW.match(line):
+        elif (row := TABLE_ROW.match(line)) is None:
             reading = False
         elif reading and not TABLE_RULE.match(line):
-            cell = TABLE_ROW.match(line).group(1)
+            cell = row.group(1)
             paths.append(cell.strip().strip('`').strip())
     return [p for p in paths if p]
 
@@ -891,8 +891,7 @@ def age(stamp: str, now: datetime) -> float | None:
     if not stamp:
         return None
     try:
-        # `fromisoformat` reads the trailing Z only from 3.11, and a fleet machine may carry less.
-        return (now - datetime.fromisoformat(stamp.replace('Z', '+00:00'))).total_seconds()
+        return (now - datetime.fromisoformat(stamp)).total_seconds()
     # ValueError is the unparseable stamp, and TypeError is the parseable one carrying no zone.
     # A stamp with no offset parses to a naive datetime, which will not subtract from an aware now.
     # Catching only the first lets that raise out of a reporting call and take the digest with it.
@@ -1333,8 +1332,10 @@ def origin_owner() -> str | None:
     try:
         url = subprocess.run(['git', '-C', str(Path(__file__).resolve().parent),
                               'remote', 'get-url', 'origin'],
-                             capture_output=True, text=True, encoding='utf-8', timeout=5).stdout.strip()
-    except Exception:
+                             capture_output=True, text=True, encoding='utf-8', timeout=5,
+                             check=False).stdout.strip()
+    # A missing git, a timeout, or any other failure all mean the owner cannot be read.
+    except Exception:  # noqa: BLE001
         return None
     m = re.search(r'[:/]([A-Za-z0-9_.\-]+)/([A-Za-z0-9_.\-]+?)(?:\.git)?/?$', url)
     return m.group(1).lower() if m else None
@@ -1480,7 +1481,8 @@ def gh_rest(path: str, jq: str | None = None) -> subprocess.CompletedProcess:
     """
     argv = ['gh', 'api', path] + (['--jq', jq] if jq else [])
     try:
-        return subprocess.run(argv, capture_output=True, text=True, encoding='utf-8', timeout=30)
+        return subprocess.run(argv, capture_output=True, text=True, encoding='utf-8', timeout=30,
+                              check=False)
     except (OSError, subprocess.SubprocessError):
         return subprocess.CompletedProcess(argv, 1, '', 'gh could not be run')
 
@@ -1488,7 +1490,7 @@ def gh_rest(path: str, jq: str | None = None) -> subprocess.CompletedProcess:
 def answered_absent(proc: subprocess.CompletedProcess) -> bool:
     """Whether GitHub said the object is not there, as opposed to nothing having been read."""
     m = HTTP_STATUS.search(proc.stderr)
-    return bool(m) and m.group(1) in ABSENT
+    return m is not None and m.group(1) in ABSENT
 
 
 def body_references(body: str) -> tuple[list[str], list[str]]:
@@ -1546,7 +1548,7 @@ def head_carries(owner: str, repo: str, head: str, refs: list[str]) -> set[str]
     # Raising instead would abort a run the caller is in the middle of.
     try:
         proc = subprocess.run(['gh', 'api', f'repos/{owner}/{repo}/tarball/{head}'],
-                              capture_output=True, timeout=TARBALL_TIMEOUT)
+                              capture_output=True, timeout=TARBALL_TIMEOUT, check=False)
     except (OSError, subprocess.SubprocessError):
         return None
     if proc.returncode != 0:
diff --git a/scripts/prose_lint.py b/scripts/prose_lint.py
old mode 100644
new mode 100755
index df6053f9..effb9018
--- a/scripts/prose_lint.py
+++ b/scripts/prose_lint.py
@@ -137,7 +137,7 @@ def untracked_paths(root: Path) -> list[str]:
     """
     try:
         r = subprocess.run(['git', '-C', str(root), 'ls-files', '-z', '--others',
-                            '--exclude-standard'], capture_output=True, text=True)
+                            '--exclude-standard'], capture_output=True, text=True, check=False)
     except (OSError, ValueError):
         return []
     if r.returncode != 0:
@@ -251,8 +251,8 @@ def home_path_findings(lineno: int, line: str) -> list[tuple[int, str, str]]:
         if m.group('user').lower() in SERVICE_ACCOUNTS:
             continue
         out.append((lineno, 'home-path',
-                    f'absolute home path {m.group(0)!r} -> use a constructed path, not an '
-                    'observed one'))
+                    (f'absolute home path {m.group(0)!r} -> use a constructed path, not an '
+                    'observed one')))
     return out
 
 
@@ -312,7 +312,7 @@ def once_tracked(root: str, rel_path: str) -> bool:
     """Whether git at `root` ever recorded `rel_path`, the deletion signature this rule keys on."""
     try:
         r = subprocess.run(['git', '-C', root, 'log', '-1', '--format=%H', '--', rel_path],
-                           capture_output=True, text=True)
+                           capture_output=True, text=True, check=False)
     except (OSError, ValueError):
         return False
     return r.returncode == 0 and bool(r.stdout.strip())
@@ -350,8 +350,8 @@ def dead_path_findings(root: Path, base: Path, lineno: int,
                 continue
             if once_tracked(str(root), str(tracked_rel)):
                 out.append((lineno, 'dead-path',
-                            f'path {token!r} is deleted from this tree -> re-point, rewrite, '
-                            'or remove the stale mention'))
+                            (f'path {token!r} is deleted from this tree -> re-point, rewrite, '
+                            'or remove the stale mention')))
                 break
     return out
 
@@ -360,7 +360,7 @@ def shallow_checkout(root: Path) -> bool:
     """Whether the checkout at `root` is shallow, which holds no deletion history to key on."""
     try:
         r = subprocess.run(['git', '-C', str(root), 'rev-parse', '--is-shallow-repository'],
-                           capture_output=True, text=True)
+                           capture_output=True, text=True, check=False)
     except (OSError, ValueError):
         return False
     return r.returncode == 0 and r.stdout.strip() == 'true'
@@ -392,7 +392,7 @@ def repo_root(path: Path) -> str:
     start = path if path.is_dir() else path.parent
     try:
         r = subprocess.run(['git', '-C', str(start), 'rev-parse', '--show-toplevel'],
-                           capture_output=True, text=True)
+                           capture_output=True, text=True, check=False)
     except (OSError, ValueError):
         return ''
     return r.stdout.strip() if r.returncode == 0 else ''
@@ -406,7 +406,7 @@ def tracked_paths(root: Path) -> list[Path] | None:
     """
     try:
         r = subprocess.run(['git', '-C', str(root), 'ls-files', '-z'],
-                           capture_output=True, text=True)
+                           capture_output=True, text=True, check=False)
     except (OSError, ValueError):
         return None
     if r.returncode != 0 or not r.stdout.strip('\0'):
@@ -1196,8 +1196,8 @@ def comment_wrap_findings(path: Path, raw: str, lines: list[str]) -> list[tuple[
         # A label opening a definition is exempt, since the lowercase word is the name being defined.
         elif leading and body[:1].islower() and not COMMENT_LABEL.match(body):
             out.append((n, 'comment-case',
-                        'comment sentence opens in lowercase -> capitalize, or restructure so it '
-                        'does not open on a lowercase name'))
+                        ('comment sentence opens in lowercase -> capitalize, or restructure so it '
+                        'does not open on a lowercase name')))
         # A trailing comment can start a sentence the next full-line comment continues.
         # The continuation has to be a full-line comment, since a trailing one annotates its own.
         prev_body = body
diff --git a/scripts/repo_gate.py b/scripts/repo_gate.py
old mode 100644
new mode 100755
index 84bca21f..3bf2ea94
--- a/scripts/repo_gate.py
+++ b/scripts/repo_gate.py
@@ -72,7 +72,7 @@
 
 
 def sh(*args: str) -> str:
-    return subprocess.run(args, capture_output=True, text=True).stdout
+    return subprocess.run(args, capture_output=True, text=True, check=False).stdout
 
 
 def origin_owner(root: Path) -> str | None:
@@ -95,7 +95,7 @@ def gh_exists(path: str) -> bool | None:
     """
     try:
         r = subprocess.run(['gh', 'api', path, '--jq', '.sha'],
-                           capture_output=True, text=True, timeout=GH_TIMEOUT)
+                           capture_output=True, text=True, timeout=GH_TIMEOUT, check=False)
     except (OSError, subprocess.SubprocessError):
         return None
     if r.returncode == 0:
@@ -235,7 +235,7 @@ def resolved_eol(root: Path, paths: list[str]) -> dict[str, str] | None:
         return {}
     try:
         r = subprocess.run(['git', '-C', str(root), 'check-attr', '-z', '--stdin', 'eol'],
-                           input='\0'.join(paths) + '\0', capture_output=True, text=True)
+                           input='\0'.join(paths) + '\0', capture_output=True, text=True, check=False)
     except (OSError, subprocess.SubprocessError):
         return None
     if r.returncode != 0:
diff --git a/scripts/skills_install.py b/scripts/skills_install.py
index 6528e0ca..266f7a97 100755
--- a/scripts/skills_install.py
+++ b/scripts/skills_install.py
@@ -57,7 +57,7 @@ def source_ref():
     """The hub commit this installer is running from, and whether the tree is dirty."""
     def git(*args):
         try:
-            r = subprocess.run(["git", "-C", str(ROOT), *args], capture_output=True, text=True)
+            r = subprocess.run(["git", "-C", str(ROOT), *args], capture_output=True, text=True, check=False)
         except OSError:
             return None
         return r.stdout.strip() if r.returncode == 0 else None
@@ -159,7 +159,7 @@ def register_claude_marketplace():
     """
     marketplace_add = subprocess.run(
         ["claude", "plugin", "marketplace", "add", str(ROOT)],
-        capture_output=True, text=True,
+        capture_output=True, text=True, check=False,
     )
     # Re-adding an already-registered marketplace is expected on a re-run.
     # Only a genuine failure (not "already exists") is fatal, since idempotence is the point.
@@ -171,7 +171,7 @@ def register_claude_marketplace():
 
     install = subprocess.run(
         ["claude", "plugin", "install", f"{PLUGIN_NAME}@{MARKETPLACE_NAME}", "--scope", "user"],
-        capture_output=True, text=True,
+        capture_output=True, text=True, check=False,
     )
     if (install.returncode != 0
             and "already" not in install.stdout.lower()
diff --git a/scripts/test_bootstrap.py b/scripts/tests/test_bootstrap.py
similarity index 99%
rename from scripts/test_bootstrap.py
rename to scripts/tests/test_bootstrap.py
index 1dcc56d6..08b4abf2 100644
--- a/scripts/test_bootstrap.py
+++ b/scripts/tests/test_bootstrap.py
@@ -18,7 +18,7 @@
 difference is a decision rather than an accident. `git-restore-mtime` serves a Linux deploy path and
 the spec declares it not applicable on Windows.
 
-Run: python3 scripts/test_bootstrap.py
+Run: python3 scripts/tests/test_bootstrap.py
 """
 from __future__ import annotations
 
@@ -27,7 +27,7 @@
 import subprocess
 from pathlib import Path
 
-ROOT = Path(__file__).resolve().parent.parent
+ROOT = Path(__file__).resolve().parent.parent.parent
 BOOTSTRAP = ROOT / 'host-setup' / 'bootstrap.sh'
 BOOTSTRAP_PS = ROOT / 'host-setup' / 'bootstrap.ps1'
 LINUX = ROOT / 'host-setup' / 'linux'
@@ -60,7 +60,7 @@
 
 # A spec tool an installer deliberately does not manage, and the reason, recorded so an omission is a decision somebody made rather than one nobody noticed.
 # Both sets are empty, which is itself the assertion: docker installs the same way on a hypervisor and a workstation on both platforms now, and the one case that differs, a WSL distribution, is handled inside install-tools.sh itself (it skips the native install and points at Docker Desktop's own WSL integration) rather than by leaving docker unmanaged on Linux entirely.
-NOT_MANAGED = {
+NOT_MANAGED: dict[str, dict[str, str]] = {
     'linux': {},
     'windows': {},
 }
diff --git a/scripts/test_build_dist.py b/scripts/tests/test_build_dist.py
similarity index 98%
rename from scripts/test_build_dist.py
rename to scripts/tests/test_build_dist.py
index c26cce49..120de8c2 100755
--- a/scripts/test_build_dist.py
+++ b/scripts/tests/test_build_dist.py
@@ -1,14 +1,16 @@
 #!/usr/bin/env python3
 """Exercise build_dist.py's regeneration and staleness detection against a crafted skills tree.
 
-Run as `python3 scripts/test_build_dist.py`, or under `python3 -m unittest discover -s scripts`.
+Run as `python3 scripts/tests/test_build_dist.py`, or under `python3 -m unittest discover -s scripts/tests`.
 """
 from __future__ import annotations
 
 import json
+import sys
 import unittest
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import build_dist
 
 
diff --git a/scripts/test_host_gate.py b/scripts/tests/test_host_gate.py
similarity index 99%
rename from scripts/test_host_gate.py
rename to scripts/tests/test_host_gate.py
index 767cb2f7..c9eafdb1 100755
--- a/scripts/test_host_gate.py
+++ b/scripts/tests/test_host_gate.py
@@ -14,7 +14,7 @@
 import unittest
 from pathlib import Path
 
-sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import host_gate
 
 
diff --git a/scripts/test_pr_review.py b/scripts/tests/test_pr_review.py
old mode 100644
new mode 100755
similarity index 98%
rename from scripts/test_pr_review.py
rename to scripts/tests/test_pr_review.py
index 48e55cf6..250bbf7e
--- a/scripts/test_pr_review.py
+++ b/scripts/tests/test_pr_review.py
@@ -6,7 +6,7 @@
 stale head, or a wait that returns success while nothing landed. Each case below feeds a crafted
 GraphQL payload and asserts the reading, with `gql` replaced so no case reaches the network.
 
-Run as `python3 scripts/test_pr_review.py`, or under `python3 -m unittest discover -s scripts`.
+Run as `python3 scripts/tests/test_pr_review.py`, or under `python3 -m unittest discover -s scripts/tests`.
 """
 from __future__ import annotations
 
@@ -22,9 +22,10 @@
 from pathlib import Path
 from unittest import mock
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import pr_review
 
-REPO = Path(__file__).resolve().parent.parent
+REPO = Path(__file__).resolve().parent.parent.parent
 RUNBOOK = REPO / '.github' / 'copilot-instructions.md'
 
 HEAD = 'a' * 40
@@ -653,14 +654,14 @@ def digest_for(self, *reviews: dict) -> str:
     def test_each_vetted_spelling_of_a_full_round_reads_as_full(self) -> None:
         """The census: four tails on the first spelling, and the `Review details` bullet."""
         for covers in (
-            'Copilot reviewed 7 out of 7 changed files in this pull request and generated '
-            'no new comments.',
-            'Copilot reviewed 7 out of 7 changed files in this pull request and generated '
-            'no comments.',
-            'Copilot reviewed 7 out of 7 changed files in this pull request and generated '
-            '1 comment.',
-            'Copilot reviewed 7 out of 7 changed files in this pull request and generated '
-            '4 comments.',
+            ('Copilot reviewed 7 out of 7 changed files in this pull request and generated '
+            'no new comments.'),
+            ('Copilot reviewed 7 out of 7 changed files in this pull request and generated '
+            'no comments.'),
+            ('Copilot reviewed 7 out of 7 changed files in this pull request and generated '
+            '1 comment.'),
+            ('Copilot reviewed 7 out of 7 changed files in this pull request and generated '
+            '4 comments.'),
             '- **Files reviewed:** 7/7 changed files',
         ):
             with self.subTest(covers=covers[:44]):
@@ -1364,9 +1365,8 @@ def test_a_stamp_ahead_of_the_clock_renders_zero_rather_than_a_negative_age(self
         self.assertIn('queued 0m', out)
         self.assertNotIn('-2m', out)
         # The CLI cannot reach it, since the parser refuses the threshold that would.
-        with contextlib.redirect_stderr(io.StringIO()):
-            with self.assertRaises(SystemExit):
-                pr_review.main(['status', '7', '--repo', 'o/r', '--check-grace', '-200'])
+        with contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit):
+            pr_review.main(['status', '7', '--repo', 'o/r', '--check-grace', '-200'])
 
     def test_a_caller_handing_the_digest_an_odd_node_costs_a_field_not_the_digest(self) -> None:
         """The rendering path reads with `.get` for the reason `age` catches two exceptions.
@@ -1584,9 +1584,8 @@ def test_a_failed_call_raises_rather_than_returning_an_empty_reading(self) -> No
         """Returning nothing on failure would read as a PR with no reviews and no threads."""
         failed = subprocess.CompletedProcess(args=[], returncode=1, stdout='', stderr='boom')
         with mock.patch.object(pr_review.subprocess, 'run', return_value=failed), \
-                contextlib.redirect_stderr(io.StringIO()) as err:
-            with self.assertRaises(SystemExit):
-                pr_review.gql('query', 'o', 'r', 1)
+                contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit):
+            pr_review.gql('query', 'o', 'r', 1)
         self.assertIn('boom', err.getvalue())
 
     def test_a_successful_call_unwraps_to_the_pull_request(self) -> None:
@@ -1855,18 +1854,17 @@ def test_a_run_naming_no_repo_is_rejected_rather_than_sent_somewhere(self) -> No
         the run was reading a pull request in a repository nobody had named.
         """
         self.answer(payload([review()]))
-        with contextlib.redirect_stderr(io.StringIO()) as err:
-            with self.assertRaises(SystemExit):
-                pr_review.main(['status', '7'])
+        with contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit):
+            pr_review.main(['status', '7'])
         self.assertIn('--repo', err.getvalue())
 
     def test_a_repo_that_is_not_owner_slash_name_is_rejected_by_name(self) -> None:
         """The near-miss a required argument still admits, and unpacking it is a bare traceback."""
         for bad in ('ProjectTemplate', 'ptr727/', '/ProjectTemplate', 'a/b/c', ''):
             with self.subTest(repo=bad):
-                with contextlib.redirect_stderr(io.StringIO()) as err:
-                    with self.assertRaises(SystemExit):
-                        pr_review.main(['status', '7', '--repo', bad])
+                with (contextlib.redirect_stderr(io.StringIO()) as err,
+                      self.assertRaises(SystemExit)):
+                    pr_review.main(['status', '7', '--repo', bad])
                 self.assertIn('OWNER/NAME', err.getvalue())
 
     def test_the_digest_names_the_repository_it_read(self) -> None:
@@ -2103,9 +2101,8 @@ def test_a_sibling_repository_under_the_same_owner_is_in_scope(self) -> None:
 
 class TestReplyArguments(unittest.TestCase):
     def err(self, argv: list[str]) -> str:
-        with contextlib.redirect_stderr(io.StringIO()) as err:
-            with self.assertRaises(SystemExit):
-                pr_review.main(argv)
+        with contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit):
+            pr_review.main(argv)
         return err.getvalue()
 
     def test_an_empty_body_is_rejected_rather_than_posted(self) -> None:
@@ -2503,7 +2500,8 @@ def test_the_timeline_filter_takes_the_reviewer_s_own_requests_only(self) -> Non
             {'event': 'commented', 'created_at': '05'},
         ]
         run = subprocess.run(['jq', '-r', pr_review.TIMELINE_JQ],
-                             input=json.dumps(events), capture_output=True, text=True)
+                             input=json.dumps(events), capture_output=True, text=True,
+                             check=False)
         self.assertEqual(0, run.returncode, run.stderr)
         self.assertEqual(['review_requested 01', 'copilot_work_started 02'],
                          run.stdout.split('\n')[:-1])
@@ -2513,9 +2511,8 @@ def test_the_timeline_filter_takes_the_reviewer_s_own_requests_only(self) -> Non
 
     def test_a_negative_pickup_grace_is_rejected_rather_than_read_as_every_poll(self) -> None:
         """It leaves the next reading behind the clock, which is the per-poll pattern returning."""
-        with contextlib.redirect_stderr(io.StringIO()) as err:
-            with self.assertRaises(SystemExit):
-                pr_review.main(['wait', '7', '--repo', 'o/r', '--pickup-grace', '-1'])
+        with contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit):
+            pr_review.main(['wait', '7', '--repo', 'o/r', '--pickup-grace', '-1'])
         # The repository is named, or this exits on the missing argument and proves nothing.
         self.assertIn('pickup-grace', err.getvalue())
 
@@ -2527,9 +2524,9 @@ def test_a_negative_check_threshold_is_rejected_rather_than_firing_on_every_chec
         """
         for flag in ('--check-grace', '--check-stall'):
             with self.subTest(flag=flag):
-                with contextlib.redirect_stderr(io.StringIO()) as err:
-                    with self.assertRaises(SystemExit):
-                        pr_review.main(['wait', '7', '--repo', 'o/r', flag, '-1'])
+                with (contextlib.redirect_stderr(io.StringIO()) as err,
+                      self.assertRaises(SystemExit)):
+                    pr_review.main(['wait', '7', '--repo', 'o/r', flag, '-1'])
                 self.assertIn(flag.lstrip('-'), err.getvalue())
 
     def test_the_documented_exit_codes_are_the_ones_the_code_returns(self) -> None:
@@ -2563,19 +2560,18 @@ def test_an_inverted_pair_of_check_thresholds_is_rejected_at_the_flags_too(self)
         """
         for grace, stall in (('1800', '300'), ('600', '600')):
             with self.subTest(grace=grace, stall=stall):
-                with contextlib.redirect_stderr(io.StringIO()) as err:
-                    with self.assertRaises(SystemExit):
-                        pr_review.main(['wait', '7', '--repo', 'o/r',
-                                        '--check-grace', grace, '--check-stall', stall])
+                with (contextlib.redirect_stderr(io.StringIO()) as err,
+                      self.assertRaises(SystemExit)):
+                    pr_review.main(['wait', '7', '--repo', 'o/r',
+                                    '--check-grace', grace, '--check-stall', stall])
                 self.assertIn('check-grace', err.getvalue())
 
     def test_a_failed_timeline_read_raises_rather_than_reading_as_no_events(self) -> None:
         """An empty list reads as no request pending, which is the false clean one level up."""
         failed = subprocess.CompletedProcess(args=[], returncode=1, stdout='', stderr='boom')
         with mock.patch.object(pr_review.subprocess, 'run', return_value=failed), \
-                contextlib.redirect_stderr(io.StringIO()) as err:
-            with self.assertRaises(SystemExit):
-                pr_review.timeline('o', 'r', 7)
+                contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit):
+            pr_review.timeline('o', 'r', 7)
         self.assertIn('boom', err.getvalue())
 
     def test_the_backoff_is_bounded_and_non_decreasing(self) -> None:
diff --git a/scripts/test_prose_lint.py b/scripts/tests/test_prose_lint.py
old mode 100644
new mode 100755
similarity index 99%
rename from scripts/test_prose_lint.py
rename to scripts/tests/test_prose_lint.py
index 74b4734b..5de34781
--- a/scripts/test_prose_lint.py
+++ b/scripts/tests/test_prose_lint.py
@@ -5,7 +5,7 @@
 watched fail is a gate nobody knows works. Where a case covers a table, it reads the live table
 rather than restating it: a proof that restates the gated data proves only that the function runs.
 
-Run as `python3 scripts/test_prose_lint.py`, or under `python3 -m unittest discover -s scripts`.
+Run as `python3 scripts/tests/test_prose_lint.py`, or under `python3 -m unittest discover -s scripts/tests`.
 """
 from __future__ import annotations
 
@@ -21,9 +21,10 @@
 from pathlib import Path
 from unittest import mock
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import prose_lint
 
-REPO = Path(__file__).resolve().parent.parent
+REPO = Path(__file__).resolve().parent.parent.parent
 COMMENT_AND_DOC_STYLE_SKILL = REPO / '.agents' / 'skills' / 'comment-and-doc-style' / 'SKILL.md'
 
 # Bait assembled from two literals, so this module never holds the pattern it feeds the gate.
@@ -1117,7 +1118,7 @@ def test_no_discovered_path_is_git_ignored(self) -> None:
         found = prose_lint.discover([str(REPO)])
         r = subprocess.run(['git', '-C', str(REPO), 'check-ignore', '--stdin'],
                            input='\n'.join(str(p) for p in found),
-                           capture_output=True, text=True)
+                           capture_output=True, text=True, check=False)
         self.assertEqual('', r.stdout.strip())
 
     def test_the_fallback_skips_generated_roots(self) -> None:
@@ -1780,9 +1781,9 @@ def test_neither_source_file_carries_a_literal_home_path(self) -> None:
         its own cases, and the only repair would be an exemption naming these files, which is the
         stale-exemption shape that hands out a work list damaging correct documents.
         """
-        for name in ('prose_lint.py', 'test_prose_lint.py'):
-            with self.subTest(source=name):
-                found = prose_lint.check_file(Path(__file__).with_name(name), {'home-path'})
+        for path in (REPO / 'scripts' / 'prose_lint.py', Path(__file__)):
+            with self.subTest(source=path.name):
+                found = prose_lint.check_file(path, {'home-path'})
                 self.assertEqual([], found)
 
 
diff --git a/scripts/test_repo_gate.py b/scripts/tests/test_repo_gate.py
old mode 100644
new mode 100755
similarity index 99%
rename from scripts/test_repo_gate.py
rename to scripts/tests/test_repo_gate.py
index e82cb96a..e566a570
--- a/scripts/test_repo_gate.py
+++ b/scripts/tests/test_repo_gate.py
@@ -5,7 +5,7 @@
 objects to the fault instead of proving the repo is currently clean. The coverage floors are the
 other half: a check whose scan matches nothing reports zero issues and reads exactly like a pass.
 
-Run as `python3 scripts/test_repo_gate.py`, or under `python3 -m unittest discover -s scripts`.
+Run as `python3 scripts/tests/test_repo_gate.py`, or under `python3 -m unittest discover -s scripts/tests`.
 """
 from __future__ import annotations
 
@@ -20,9 +20,10 @@
 from pathlib import Path
 from unittest import mock
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import repo_gate
 
-REPO = Path(__file__).resolve().parent.parent
+REPO = Path(__file__).resolve().parent.parent.parent
 GOVERNANCE = REPO / 'GOVERNANCE.md'
 GITATTRIBUTES = REPO / '.gitattributes'
 
diff --git a/scripts/test_skills_install.py b/scripts/tests/test_skills_install.py
similarity index 92%
rename from scripts/test_skills_install.py
rename to scripts/tests/test_skills_install.py
index 0247c86a..2d34856c 100755
--- a/scripts/test_skills_install.py
+++ b/scripts/tests/test_skills_install.py
@@ -2,17 +2,19 @@
 """Exercise skills_install.py's materialization and staleness reporting, without touching the
 real `claude` CLI state or the real ~/.agents directory.
 
-Run as `python3 scripts/test_skills_install.py`, or under `python3 -m unittest discover -s scripts`.
+Run as `python3 scripts/tests/test_skills_install.py`, or under `python3 -m unittest discover -s scripts/tests`.
 """
 from __future__ import annotations
 
 import json
 import shutil
+import sys
 import tempfile
 import unittest
 from pathlib import Path
 from unittest import mock
 
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import skills_install
 
 
@@ -74,9 +76,9 @@ def fake_run(args, **kwargs):
             result.stdout = "deadbeef\n" if "rev-parse" in args else ""
             return result
 
-        with mock.patch("subprocess.run", side_effect=fake_run):
-            with mock.patch.dict("os.environ", {"SKILLS_SOURCE_COMMIT": "cafe1234"}):
-                self.assertEqual(skills_install.source_ref()["commit"], "deadbeef")
+        with (mock.patch("subprocess.run", side_effect=fake_run),
+              mock.patch.dict("os.environ", {"SKILLS_SOURCE_COMMIT": "cafe1234"})):
+            self.assertEqual(skills_install.source_ref()["commit"], "deadbeef")
 
 
 class MaterializeCase(unittest.TestCase):
@@ -264,10 +266,10 @@ def test_installed_from_dirty_but_now_clean_at_the_same_commit_still_reports_sta
                         "source": {"commit": "abc", "dirty": True}}),
             encoding="utf-8",
         )
-        with mock.patch("skills_install.source_ref",
-                         return_value={"vcs": "git", "commit": "abc", "dirty": False}):
-            with mock.patch("builtins.print"):
-                exit_code = skills_install.report(stamp)
+        with (mock.patch("skills_install.source_ref",
+                         return_value={"vcs": "git", "commit": "abc", "dirty": False}),
+              mock.patch("builtins.print")):
+            exit_code = skills_install.report(stamp)
         self.assertEqual(exit_code, 1)
 
     def test_a_valid_json_non_dict_stamp_reports_stale_instead_of_crashing(self) -> None:
@@ -283,9 +285,10 @@ def test_a_dict_stamp_with_a_non_dict_source_reports_stale_instead_of_crashing(s
             json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": "oops"}),
             encoding="utf-8",
         )
-        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "abc", "dirty": False}):
-            with mock.patch("builtins.print"):
-                exit_code = skills_install.report(stamp)
+        with (mock.patch("skills_install.source_ref",
+                         return_value={"vcs": "git", "commit": "abc", "dirty": False}),
+              mock.patch("builtins.print")):
+            exit_code = skills_install.report(stamp)
         self.assertEqual(exit_code, 1)
 
     def test_an_unrecognized_stamp_version_reports_stale(self) -> None:
@@ -295,9 +298,10 @@ def test_an_unrecognized_stamp_version_reports_stale(self) -> None:
             json.dumps({"stampVersion": skills_install.STAMP_VERSION + 1, "source": {"commit": "abc"}}),
             encoding="utf-8",
         )
-        with mock.patch("skills_install.source_ref", return_value={"vcs": "git", "commit": "abc", "dirty": False}):
-            with mock.patch("builtins.print"):
-                exit_code = skills_install.report(stamp)
+        with (mock.patch("skills_install.source_ref",
+                         return_value={"vcs": "git", "commit": "abc", "dirty": False}),
+              mock.patch("builtins.print")):
+            exit_code = skills_install.report(stamp)
         self.assertEqual(exit_code, 1)
 
     def test_a_non_git_checkout_reports_stale_rather_than_current(self) -> None:
@@ -309,9 +313,9 @@ def test_a_non_git_checkout_reports_stale_rather_than_current(self) -> None:
             json.dumps({"stampVersion": skills_install.STAMP_VERSION, "source": {"commit": None}}),
             encoding="utf-8",
         )
-        with mock.patch("skills_install.source_ref", return_value={"vcs": "none"}):
-            with mock.patch("builtins.print"):
-                exit_code = skills_install.report(stamp)
+        with (mock.patch("skills_install.source_ref", return_value={"vcs": "none"}),
+              mock.patch("builtins.print")):
+            exit_code = skills_install.report(stamp)
         self.assertEqual(exit_code, 1)
 
 
diff --git a/spec/audit.py b/spec/audit.py
old mode 100644
new mode 100755
index 2dca9ed6..ccffe17d
--- a/spec/audit.py
+++ b/spec/audit.py
@@ -26,6 +26,7 @@
 import base64
 import functools
 import hashlib
+import itertools
 import json
 import pathlib
 import re
@@ -74,7 +75,7 @@ def hub_tracked():
     A non-zero exit raises rather than returning an empty set, which would read as "the hub tracks nothing"
     and silently clear every hub-only finding.
     """
-    r = subprocess.run(["git", "ls-files"], cwd=ROOT, capture_output=True, text=True)
+    r = subprocess.run(["git", "ls-files"], cwd=ROOT, capture_output=True, text=True, check=False)
     if r.returncode != 0:
         raise RuntimeError(f"git ls-files failed in {ROOT}: {r.stderr.strip() or 'non-zero exit'}")
     return frozenset(r.stdout.splitlines())
@@ -135,7 +136,7 @@ def hub_name():
     worktree without an origin would silently break. The caller announces the directory-name fallback:
     a silently degraded match is the fail-open case this check exists to prevent.
     """
-    r = subprocess.run(["git", "config", "--get", "remote.origin.url"], capture_output=True, text=True, cwd=ROOT)
+    r = subprocess.run(["git", "config", "--get", "remote.origin.url"], capture_output=True, text=True, cwd=ROOT, check=False)
     if r.returncode == 0 and r.stdout.strip():
         return r.stdout.strip().rstrip("/").removesuffix(".git").split("/")[-1], True
     return ROOT.name, False
@@ -150,7 +151,7 @@ def gh(path, ok404=False) -> Any:
     No --paginate: on object endpoints it concatenates page documents into unparseable JSON. Every
     list read here fits one page; callers pass per_page=100 where a default page could truncate.
     """
-    r = subprocess.run(["gh", "api", path], capture_output=True, text=True)
+    r = subprocess.run(["gh", "api", path], capture_output=True, text=True, check=False)
     if r.returncode != 0:
         if ok404 and ("HTTP 404" in r.stderr or "Not Found" in r.stderr):
             return None
@@ -317,7 +318,7 @@ def extract_section(text, heading):
     out, capturing, fenced = [], False, False
     for ln in normalize(text).split("\n"):
         stripped = ln.strip()
-        if stripped.startswith("```") or stripped.startswith("~~~"):
+        if stripped.startswith(("```", "~~~")):
             fenced = not fenced
         elif not fenced and stripped.startswith("## "):
             if capturing:
@@ -348,7 +349,7 @@ def strip_sections(text, names):
     out, dropping, fenced = [], False, False
     for ln in normalize(text).split("\n"):
         stripped = ln.strip()
-        if stripped.startswith("```") or stripped.startswith("~~~"):
+        if stripped.startswith(("```", "~~~")):
             fenced = not fenced
         elif not fenced and stripped.startswith("## "):
             dropping = stripped[2:].strip().lower() in want  # a sibling H2 always ends the previous region
@@ -446,7 +447,7 @@ def unfenced_text(text):
     out, fenced = [], False
     for ln in normalize(text).split("\n"):
         s = ln.strip()
-        if s.startswith("```") or s.startswith("~~~"):
+        if s.startswith(("```", "~~~")):
             fenced = not fenced
             continue
         if not fenced:
@@ -563,7 +564,7 @@ def readme_section_findings(text, model, sel, public):
         findings.append(("LETTER", f"readme: no `## {s['name']}` section{why} - it is a required section (spec/readme-structure.md)"))
 
     seq = [(by_name.get(hl) or retired.get(hl), h) for h, hl in zip(heads, lower) if hl in by_name or hl in retired]
-    for (prev, prev_h), (cur, cur_h) in zip(seq, seq[1:]):
+    for (prev, prev_h), (cur, cur_h) in itertools.pairwise(seq):
         if cur["ordinal"] < prev["ordinal"]:
             findings.append(("LETTER", f"readme: section '{cur_h}' follows '{prev_h}' but is ordered before it - the declared sections keep their relative order (spec/readme-structure.md)"))
 
@@ -831,7 +832,7 @@ def third_party_tool_findings(text, catalog):
             findings.append(("LETTER", f"readme: 3rd Party Tools describes {name} as {shown} where the fleet describes it as '{want['description']}' - a shared tool carries one description (spec/third-party-tools.json)"))
     # Ordering covers every tool listed, not only the cataloged ones, since a reader scans the whole list.
     if listed != sorted(listed, key=str.lower):
-        first = next(f"{a} before {b}" for a, b in zip(listed, listed[1:]) if a.lower() > b.lower())
+        first = next(f"{a} before {b}" for a, b in itertools.pairwise(listed) if a.lower() > b.lower())
         findings.append(("LETTER", f"readme: 3rd Party Tools is not alphabetized ({first}) - the list is scanned rather than read (spec/readme-structure.md)"))
     return findings
 
@@ -1082,11 +1083,11 @@ def git_file_history(rel_path):
     # Decode as UTF-8 with replacement to match the downstream and canonical reads.
     # A divergent decode would fabricate a mismatch.
     r = subprocess.run(["git", "log", "--format=%H", "--", rel_path], cwd=ROOT, capture_output=True,
-                       encoding="utf-8", errors="replace")
+                       encoding="utf-8", errors="replace", check=False)
     if r.returncode == 0:
         for sha in r.stdout.split():
             s = subprocess.run(["git", "show", f"{sha}:{rel_path}"], cwd=ROOT, capture_output=True,
-                               encoding="utf-8", errors="replace")
+                               encoding="utf-8", errors="replace", check=False)
             if s.returncode == 0:
                 out.append(s.stdout)
     _HISTORY_CACHE[rel_path] = out
@@ -1100,7 +1101,7 @@ def hub_last_change(rel_path):
     Cached because one canonical's date is compared against every audited repo's copy.
     """
     r = subprocess.run(["git", "log", "-1", "--format=%cI %h", "--", rel_path], cwd=ROOT,
-                       capture_output=True, text=True)
+                       capture_output=True, text=True, check=False)
     if r.returncode != 0 or not r.stdout.strip():
         return None
     date, sha = r.stdout.strip().split(" ", 1)
@@ -1138,9 +1139,9 @@ def check_intent_staleness(slug, ground, path, canonical_rel, down_text):
     hub_date, hub_sha = hub_change
     if datetime.fromisoformat(hub_date) <= datetime.fromisoformat(repo_date):
         return []
-    return [("DRIFT", f"intent: {path} last changed {repo_date} on {ground}, and the hub canonical "
+    return [("DRIFT", (f"intent: {path} last changed {repo_date} on {ground}, and the hub canonical "
              f"changed later at {hub_date} ({hub_sha}) - the copy possibly trails the hub, "
-             f"verify intent per AUDIT.md section 7")]
+             f"verify intent per AUDIT.md section 7"))]
 
 
 def check_verbatim(label, down_text, canonical_rel, extract=None):
@@ -1216,36 +1217,36 @@ def audit_repo(entry, spec, branch=None):
         ground_head = gh(f"repos/{slug}/branches/{ground}", ok404=True)
     if ground_head is None:
         return findings + [("ERROR", f"branch: ground-truth branch {ground} does not exist, so nothing could be read")], ""
-    if main_exists and dev_exists:
-        # Commit counts mislead here, since merge-commit promotions leave main permanently ahead while the head trees are identical, so tree equality is the no-drift fast path.
-        # Where the head trees differ, an empty compare files[] means develop is merely ahead, carrying no main-side changes since the merge-base, which is normal and yields no finding and no further API calls.
-        if branch_main["commit"]["commit"]["tree"]["sha"] != branch_dev["commit"]["commit"]["tree"]["sha"]:
-            cmp = gh(f"repos/{slug}/compare/develop...main", ok404=True)
-            if cmp and cmp.get("files"):
-                # A non-empty files[] signals main-side changes but is not usable directly.
-                # It is blind to cherry-picked promotions, where develop may already hold identical content under different commit SHAs such as a promote branch, and it is capped at 300 entries, per #336.
-                # Derive the main-side change set from the merge-base tree instead, taking paths whose object SHA, a blob or a submodule pointer, differs from base to main, additions and deletions included and with no cap.
-                # Then drop paths whose objects already match at develop, since content develop already has is not content develop lacks.
-                # That is three recursive tree calls, so where any tree is truncated, or unexpectedly not a dict, the filter is skipped and the compare's unfiltered count is kept, which is conservative and marked.
-                trees = {
-                    "base": gh(f"repos/{slug}/git/trees/{cmp['merge_base_commit']['commit']['tree']['sha']}?recursive=1"),
-                    "develop": gh(f"repos/{slug}/git/trees/{branch_dev['commit']['commit']['tree']['sha']}?recursive=1"),
-                    "main": gh(f"repos/{slug}/git/trees/{branch_main['commit']['commit']['tree']['sha']}?recursive=1"),
-                }
-                if not all(isinstance(t, dict) for t in trees.values()) or any(t.get("truncated") for t in trees.values()):
-                    findings.append(("DRIFT", f"branch: {len(cmp['files'])}+ path(s) differ between main and develop (forward-sync or reconciliation may be needed; tree unavailable or too large to classify direction)"))
-                else:
-                    objs = {name: {e["path"]: e["sha"] for e in t["tree"] if e["type"] in ("blob", "commit")} for name, t in trees.items()}
-                    # Split main-side drift by direction, never flagging every difference as a develop deficit.
-                    # A path develop still holds at the merge-base is a genuine forward-sync gap.
-                    # A path both branches moved is diverged, and develop may already supersede main.
-                    behind, diverged = classify_branch_drift(objs["base"], objs["main"], objs["develop"])
-                    if behind:
-                        shown = ", ".join(behind[:8]) + (" ..." if len(behind) > 8 else "")
-                        findings.append(("DRIFT", f"branch: {len(behind)} main-side path change(s) develop is behind on (forward-sync needed): {shown}"))
-                    if diverged:
-                        shown = ", ".join(diverged[:8]) + (" ..." if len(diverged) > 8 else "")
-                        findings.append(("DRIFT", f"branch: {len(diverged)} path(s) changed on both main and develop since the merge-base - reconcile before promoting (develop may already supersede main): {shown}"))
+    # Commit counts mislead here, since merge-commit promotions leave main permanently ahead while the head trees are identical, so tree equality is the no-drift fast path.
+    # Where the head trees differ, an empty compare files[] means develop is merely ahead, carrying no main-side changes since the merge-base, which is normal and yields no finding and no further API calls.
+    if (main_exists and dev_exists
+            and branch_main["commit"]["commit"]["tree"]["sha"] != branch_dev["commit"]["commit"]["tree"]["sha"]):
+        cmp = gh(f"repos/{slug}/compare/develop...main", ok404=True)
+        if cmp and cmp.get("files"):
+            # A non-empty files[] signals main-side changes but is not usable directly.
+            # It is blind to cherry-picked promotions, where develop may already hold identical content under different commit SHAs such as a promote branch, and it is capped at 300 entries, per #336.
+            # Derive the main-side change set from the merge-base tree instead, taking paths whose object SHA, a blob or a submodule pointer, differs from base to main, additions and deletions included and with no cap.
+            # Then drop paths whose objects already match at develop, since content develop already has is not content develop lacks.
+            # That is three recursive tree calls, so where any tree is truncated, or unexpectedly not a dict, the filter is skipped and the compare's unfiltered count is kept, which is conservative and marked.
+            trees = {
+                "base": gh(f"repos/{slug}/git/trees/{cmp['merge_base_commit']['commit']['tree']['sha']}?recursive=1"),
+                "develop": gh(f"repos/{slug}/git/trees/{branch_dev['commit']['commit']['tree']['sha']}?recursive=1"),
+                "main": gh(f"repos/{slug}/git/trees/{branch_main['commit']['commit']['tree']['sha']}?recursive=1"),
+            }
+            if not all(isinstance(t, dict) for t in trees.values()) or any(t.get("truncated") for t in trees.values()):
+                findings.append(("DRIFT", f"branch: {len(cmp['files'])}+ path(s) differ between main and develop (forward-sync or reconciliation may be needed; tree unavailable or too large to classify direction)"))
+            else:
+                objs = {name: {e["path"]: e["sha"] for e in t["tree"] if e["type"] in ("blob", "commit")} for name, t in trees.items()}
+                # Split main-side drift by direction, never flagging every difference as a develop deficit.
+                # A path develop still holds at the merge-base is a genuine forward-sync gap.
+                # A path both branches moved is diverged, and develop may already supersede main.
+                behind, diverged = classify_branch_drift(objs["base"], objs["main"], objs["develop"])
+                if behind:
+                    shown = ", ".join(behind[:8]) + (" ..." if len(behind) > 8 else "")
+                    findings.append(("DRIFT", f"branch: {len(behind)} main-side path change(s) develop is behind on (forward-sync needed): {shown}"))
+                if diverged:
+                    shown = ", ".join(diverged[:8]) + (" ..." if len(diverged) > 8 else "")
+                    findings.append(("DRIFT", f"branch: {len(diverged)} path(s) changed on both main and develop since the merge-base - reconcile before promoting (develop may already supersede main): {shown}"))
 
     # --- General settings ---
     expected = dict(spec["settings"])
@@ -1508,7 +1509,7 @@ def audit_repo(entry, spec, branch=None):
             if any((pt.get("target") if isinstance(pt, dict) else pt) == "docker" for pt in entry.get("publish", [])):
                 try:
                     dh = docker_hub_description(slug)
-                except Exception as e:
+                except Exception as e:  # noqa: BLE001
                     dh = None
                     findings.append(("DRIFT", f"description: could not read the Docker Hub short description to verify it mirrors the README ({e}) - verify by hand"))
                 if dh is not None and dh.strip() != want:
@@ -2231,7 +2232,7 @@ def main(argv=None):
     # Findings are a point-in-time snapshot.
     # Stamp the run so anything derived from it, an onboarding issue or a report, carries its own freshness signal and a reader can tell whether it still applies.
     run_utc = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-    hub = subprocess.run(["git", "rev-parse", "--short", "HEAD"], capture_output=True, text=True, cwd=ROOT)
+    hub = subprocess.run(["git", "rev-parse", "--short", "HEAD"], capture_output=True, text=True, cwd=ROOT, check=False)
     hub_sha = hub.stdout.strip() if hub.returncode == 0 else "unknown"
 
     # --issue <repo>: emit only the convergence issue on stdout (title first line, then body) so it captures cleanly.
@@ -2242,7 +2243,8 @@ def main(argv=None):
         entry = repos[0]
         try:
             findings, audited_sha = audit_repo(entry, spec, a.branch)
-        except Exception as e:  # an unverifiable audit still produces an honest issue
+        # An unverifiable audit still produces an honest issue.
+        except Exception as e:  # noqa: BLE001
             findings, audited_sha = [("ERROR", str(e))], ""
         title, body = render_issue(entry, findings, ground_branch_of(entry, a.branch),
                                    audited_sha, run_utc, hub_sha)
@@ -2262,7 +2264,8 @@ def main(argv=None):
         ground = ground_branch_of(entry, a.branch)
         try:
             findings, audited_sha = audit_repo(entry, spec, a.branch)
-        except Exception as e:  # a gh/JSON failure mid-audit must not abort the sweep
+        # A gh/JSON failure mid-audit must not abort the sweep.
+        except Exception as e:  # noqa: BLE001
             findings, audited_sha = [("ERROR", str(e))], ""
         stamp = f" @ {ground}@{audited_sha[:7]}" if audited_sha else ""
         print(f"== {entry['name']} ({', '.join(entry.get('types', []))}; {model}){stamp} ==")
diff --git a/spec/fidelity_honesty.py b/spec/fidelity_honesty.py
old mode 100644
new mode 100755
diff --git a/spec/host-tools.json b/spec/host-tools.json
index d8f12f6b..5b985054 100644
--- a/spec/host-tools.json
+++ b/spec/host-tools.json
@@ -1,6 +1,6 @@
 {
     "$schema": "./host-tools.schema.json",
-    "note": "The host contract in docs/host-setup.md, as data a gate can read. docs/host-setup.md states which tools a host needs and which repo procedure stops working without each one; this file adds the version floors, and each floor records the defect it encodes rather than a preference. A floor is one of two kinds and says which in its own why. A measured floor sits immediately above a version known to break a documented procedure, and is the kind most floors here are. A target floor declares the version the repo's own toolchain is configured for, where a lower interpreter is unverified rather than known broken, and it is honest about that rather than implying a defect nobody found. Everything else is presence-only, which is deliberate: a floor nobody can justify becomes a host failure nobody can act on. An entry is required unless it declares otherwise, and an optional tool that is absent is skipped rather than failed, since it is needed by one repository rather than by the fleet. Probes are tried in order and the first that runs is the answer, which is how a host whose interpreter is not called python3 still reports a version. The pattern is matched against the probe's combined output and its first capture group is the version, read as dot-separated integers, so a two-part YYYY.MM version compares correctly against a three-part semantic one. A floor also carries a remedy beside its source: the source says where the tool must come from and why, and the remedy is the one command that installs or upgrades it on each platform, printed under a below-floor failure so the finding carries its own fix. A remedy is written for the below-floor state, which is why the host-setup installers run in their upgrade mode there. A macOS remedy runs brew install rather than brew upgrade where the entry's source is the platform rather than Homebrew: brew install upgrades a formula that is installed but outdated, per the Homebrew manpage's install entry, and brew upgrade refuses a tool Homebrew never installed, so install is the one form that fixes both below-floor states. A remedy path under host-setup/ is repo-relative and the gate resolves it against the checkout it runs from, so the printed command is runnable as printed. A platform where the tool does not apply carries no remedy key, and scripts/test_bootstrap.py is what keeps this mapping total and pointing at tools the installers actually manage.",
+    "note": "The host contract in docs/host-setup.md, as data a gate can read. docs/host-setup.md states which tools a host needs and which repo procedure stops working without each one; this file adds the version floors, and each floor records the defect it encodes rather than a preference. A floor is one of two kinds and says which in its own why. A measured floor sits immediately above a version known to break a documented procedure, and is the kind most floors here are. A target floor declares the version the repo's own toolchain is configured for, where a lower interpreter is unverified rather than known broken, and it is honest about that rather than implying a defect nobody found. Everything else is presence-only, which is deliberate: a floor nobody can justify becomes a host failure nobody can act on. An entry is required unless it declares otherwise, and an optional tool that is absent is skipped rather than failed, since it is needed by one repository rather than by the fleet. Probes are tried in order and the first that runs is the answer, which is how a host whose interpreter is not called python3 still reports a version. The pattern is matched against the probe's combined output and its first capture group is the version, read as dot-separated integers, so a two-part YYYY.MM version compares correctly against a three-part semantic one. A floor also carries a remedy beside its source: the source says where the tool must come from and why, and the remedy is the one command that installs or upgrades it on each platform, printed under a below-floor failure so the finding carries its own fix. A remedy is written for the below-floor state, which is why the host-setup installers run in their upgrade mode there. A macOS remedy runs brew install rather than brew upgrade where the entry's source is the platform rather than Homebrew: brew install upgrades a formula that is installed but outdated, per the Homebrew manpage's install entry, and brew upgrade refuses a tool Homebrew never installed, so install is the one form that fixes both below-floor states. A remedy path under host-setup/ is repo-relative and the gate resolves it against the checkout it runs from, so the printed command is runnable as printed. A platform where the tool does not apply carries no remedy key, and scripts/tests/test_bootstrap.py is what keeps this mapping total and pointing at tools the installers actually manage.",
     "tools": [
         {
             "name": "docker",
@@ -87,7 +87,7 @@
             "probes": [["python3", "--version"], ["py", "-3", "--version"]],
             "pattern": "Python (\\d+(?:\\.\\d+)*)",
             "minimum": "3.13",
-            "why": "Every script here is standard library only, so a bare interpreter is enough and no package floor exists. The floor is the toolchain target rather than a measured breakage one version below it, which is the one entry here that reads that way and says so rather than implying a defect nobody found. pyproject.toml sets ruff target-version to py313 and mypy python_version to 3.13, so what those tools report describes 3.13 and describes no other interpreter, and a run below the floor is unverified rather than known broken. Neither tool runs in CI. What CI does run is markdownlint, cspell, actionlint and editorconfig-checker, the registry and spec validation, the script self-tests, and the repo and prose gates, and no Python linter or type checker among them. So this floor is a configuration choice rather than an enforced result, and a host failing it has no CI failure to point at. Two hard requirements are measured, both sit lower, and they fail differently. str.removeprefix and str.removesuffix need 3.9, and each is called where the tree actually calls it: removeprefix in scripts/prose_lint.py and spec/audit.py, removesuffix in spec/audit.py alone. An older interpreter starts, runs, and raises AttributeError when it reaches one. datetime.UTC needs 3.11 and arrives through a module-level from datetime import UTC in spec/audit.py, scripts/pr_review.py and its tests, so an older interpreter raises ImportError before any of those modules run at all. Which mode a host sees is decided by the script it runs rather than by the interpreter alone: spec/audit.py carries both and fails at import, scripts/pr_review.py carries only the import and fails the same way, and scripts/prose_lint.py carries only the call and therefore starts, runs, and fails partway through. The name rather than the version is what differs per platform, which the second probe covers.",
+            "why": "Every script here is standard library only, so a bare interpreter is enough and no package floor exists. The floor is the toolchain target rather than a measured breakage one version below it, which is the one entry here that reads that way and says so rather than implying a defect nobody found. pyproject.toml sets ruff target-version to py313 and mypy python_version to 3.13, so what those tools report describes 3.13 and describes no other interpreter, and a run below the floor is unverified rather than known broken. Both tools run in CI through uvx at their latest releases, beside the doc linters, the registry and spec validation, the script self-tests under coverage, and the repo and prose gates. That run judges the code rather than any host, so this floor is still a configuration choice rather than an enforced result, and a host failing it has no CI failure to point at. Two hard requirements are measured, both sit lower, and they fail differently. str.removeprefix and str.removesuffix need 3.9, and each is called where the tree actually calls it: removeprefix in scripts/prose_lint.py and spec/audit.py, removesuffix in spec/audit.py alone. An older interpreter starts, runs, and raises AttributeError when it reaches one. datetime.UTC needs 3.11 and arrives through a module-level from datetime import UTC in spec/audit.py, scripts/pr_review.py and its tests, so an older interpreter raises ImportError before any of those modules run at all. Which mode a host sees is decided by the script it runs rather than by the interpreter alone: spec/audit.py carries both and fails at import, scripts/pr_review.py carries only the import and fails the same way, and scripts/prose_lint.py carries only the call and therefore starts, runs, and fails partway through. The name rather than the version is what differs per platform, which the second probe covers.",
             "source": {
                 "linux": "Whatever the platform provides at or above the floor, since the scripts need an interpreter and no packages, so no distribution or build is pinned here.",
                 "macos": "Whatever the platform provides at or above the floor, on the same reasoning as Linux.",
diff --git a/spec/project-types.json b/spec/project-types.json
index 8d741a73..5d07fb65 100644
--- a/spec/project-types.json
+++ b/spec/project-types.json
@@ -41,7 +41,7 @@
                 { "id": "python.pyright.config", "verdict": "intent", "assert": "Build profile: pyright is configured and runs strict on first-party code (src or the integration package) - the strong typing baseline. Third-party strictness is relaxed only where a dependency has no usable types. N/A for the lint-only profile, whose type checker is mypy over stdlib-only code (python.mypy.allowed).", "intentRef": "CODESTYLE.md", "minProfile": "build" },
                 { "id": "python.config.placement", "verdict": "letter", "assert": "ruff and the type-checker config live in pyproject.toml (canonical); standalone .ruff.toml / pyrightconfig.json is a drift finding. A Home Assistant integration is the exception - it follows home-assistant/core standalone-config conventions and is scored by ha.python.conventions instead.", "intentRef": "CODESTYLE.md" },
                 { "id": "python.mypy.allowed", "verdict": "intent", "assert": "mypy is permitted as an additional type checker, not banned. It is required for a Home Assistant integration (platinum strict-typing) and is the lint-only profile's type checker. When used it runs in CI and the editor.", "intentRef": "CODESTYLE.md" },
-                { "id": "python.coverage.codecov", "verdict": "letter", "assert": "The test job collects coverage (pytest --cov-report=xml) and uploads it to Codecov via codecov/codecov-action, best-effort (continue-on-error and fail_ci_if_error: false). CODECOV_TOKEN is stored in the repo actions secrets. Required for every Python repo with tests. N/A for the lint-only profile (lint/type-checked only, no pytest). In a mixed repo the codecov.yml file-presence is still required by any co-present type that has tests, e.g. csharp.", "intentRef": "WORKFLOW.md", "minProfile": "build" },
+                { "id": "python.coverage.codecov", "verdict": "letter", "assert": "The test job collects coverage (pytest --cov-report=xml) and uploads it to Codecov via codecov/codecov-action, best-effort (continue-on-error and fail_ci_if_error: false). CODECOV_TOKEN is stored in the repo actions secrets. Required for every Python repo with tests. N/A for the lint-only profile (its unittest suite runs under coverage in CI, reported without a threshold and never uploaded to Codecov). In a mixed repo the codecov.yml file-presence is still required by any co-present type that has tests, e.g. csharp.", "intentRef": "WORKFLOW.md", "minProfile": "build" },
                 { "id": "python.uvlock.pinned", "verdict": "letter", "assert": "Build profile: the committed uv.lock is pinned to LF in both .editorconfig ([uv.lock]) and .gitattributes (uv.lock text eol=lf). uv regenerates it LF on every platform, so a CRLF-default repo otherwise reds editorconfig-checker on every uv lock/sync. N/A for a non-uv Python repo (a Home Assistant integration on pip/requirements) and for the lint-only profile (no uv.lock by definition).", "intentRef": "GOVERNANCE.md#line-endings", "minProfile": "build" },
                 { "id": "python.scripts.uvx", "verdict": "letter", "assert": "Lint-only profile only: the tools run via uvx (no project install, no lockfile). A uvx <tool>@<ver> pin in a run: step is not Dependabot-trackable, so CI runs uvx ruff@latest / uvx mypy@latest - the fleet rule pins only what Dependabot auto-updates and otherwise runs latest, never a manual pin that goes stale. VS Code tasks, README, and CI all run the unpinned latest. N/A for the build profile (which pins tool versions via uv.lock + uv sync --frozen instead).", "intentRef": "CODESTYLE.md" }
             ]
diff --git a/spec/validate.py b/spec/validate.py
old mode 100644
new mode 100755
index ea5ddf8e..7c038660
--- a/spec/validate.py
+++ b/spec/validate.py
@@ -49,8 +49,8 @@ def main():
             errors.append(f"{fname}: missing required key '{key}'")
     if errors:
         print("Spec validation FAILED:")
-        for e in errors:
-            print(f"  - {e}")
+        for err in errors:
+            print(f"  - {err}")
         return 1
 
     known_types = set(types["types"])
@@ -231,8 +231,8 @@ def check_secret_set(label, entry, need_kind):
                 errors.append(f"secrets.json: typeMechanisms['{t}'] must be a mechanism name or null")
     if errors:
         print("Spec validation FAILED:")
-        for e in errors:
-            print(f"  - {e}")
+        for err in errors:
+            print(f"  - {err}")
         return 1
 
     # The defaults for workflowModel and releaseTrigger feed configure.sh's fallback and selector resolution.
@@ -513,8 +513,8 @@ def check_selector(where, applies_to):
 
     if errors:
         print("Spec validation FAILED:")
-        for e in errors:
-            print(f"  - {e}")
+        for err in errors:
+            print(f"  - {err}")
         return 1
     cataloged = sum(1 for r in repos["repos"] if isinstance(r, dict) and r.get("status") == "cataloged")
     backlog = sum(1 for r in repos["repos"] if isinstance(r, dict) and r.get("status") == "backlog")

From 57d09dcd4ee502e2788b1340e58ab3abd694ec39 Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Fri, 14 Aug 2026 11:59:35 -0700
Subject: [PATCH 2/3] Pin the CI Interpreter and Restore the Installer's
 Version Guard

Review round 1: the uv-run CI steps now pin python 3.13 to match the
pyproject target, and the agent-safety installer refuses a pre-3.11
interpreter by capability probe, since the datetime.UTC cleanup raised
its runtime floor and the removed version-tuple guard was the friendly
error.
---
 .github/workflows/validate-task.yml | 3 +++
 host-setup/agent-safety/install.py  | 6 ++++++
 2 files changed, 9 insertions(+)

diff --git a/.github/workflows/validate-task.yml b/.github/workflows/validate-task.yml
index d3c2adb0..396b26e5 100644
--- a/.github/workflows/validate-task.yml
+++ b/.github/workflows/validate-task.yml
@@ -84,6 +84,9 @@ jobs:
       # @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 .
diff --git a/host-setup/agent-safety/install.py b/host-setup/agent-safety/install.py
index 19197fec..8789a93e 100755
--- a/host-setup/agent-safety/install.py
+++ b/host-setup/agent-safety/install.py
@@ -417,6 +417,12 @@ def main():
                         help="read-only: compare this machine's stamp against this checkout and exit")
     args = parser.parse_args()
 
+    # The stamp step calls datetime.UTC, a 3.11 API, so an older interpreter is refused up front rather than crashing mid-install.
+    # A capability probe rather than a version tuple, which the linter reads as dead code under the py313 target.
+    if not hasattr(datetime, "UTC"):
+        sys.stderr.write("This installer and the hook require Python 3.11+. Run it with a newer python3.\n")
+        return 1
+
     # Expanduser resolves a CLAUDE_HOME set in `~/...` form to the home dir rather than a literal `~` dir.
     claude_home_env = os.environ.get("CLAUDE_HOME")
     claude_home = pathlib.Path(claude_home_env).expanduser() if claude_home_env else pathlib.Path.home() / ".claude"

From b5f1e2b1388f7b739414ace0250e0e79e60c42ea Mon Sep 17 00:00:00 2001
From: Pieter Viljoen <ptr727@users.noreply.github.com>
Date: Fri, 14 Aug 2026 12:06:11 -0700
Subject: [PATCH 3/3] Correct the Self-Test Step Comment About Dependencies

Review round 2: the step runs uvx coverage now, so the standard-library
claim narrows to the tests and names the one tool the step fetches.
---
 .github/workflows/validate-task.yml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.github/workflows/validate-task.yml b/.github/workflows/validate-task.yml
index 396b26e5..50eeec5e 100644
--- a/.github/workflows/validate-task.yml
+++ b/.github/workflows/validate-task.yml
@@ -104,7 +104,7 @@ jobs:
 
       # 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 lives in scripts/tests/ 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.
+      # 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.