Promote the Tagline Close, the Ledger Refresh, and the Pre-Commit Doc Gates

[ptr727]

Three commits, all backlog bookkeeping and local tooling. No rule changes meaning, and nothing here alters what CI gates.

#640, the tagline question. #577 asked that the tagline be a distinct thing from the intro so a README may carry a second paragraph without the cap or the mirrors reaching it. That shipped in c2ce145 (#632), so the issue is closed against it. Grepping the number before closing found TODO.md had also given #577 to a different entry, the README-to-About hop, which the issue's body never covers. That hop now carries #639 of its own.

#641, the divergence ledger. reports/divergences.md is a live pass over each repo's ground-truth branch, so a committed copy is only as current as its last run. Regenerating moved three rows: AGENTS.md "Fleet Bootstrap" is now divergent at Blog and HomeAutomation-Config, and GOVERNANCE.md "Verification Discipline" and "Workflow YAML Conventions" widened from one repo to four. The reason TODO.md gave for regenerating did not survive the run and is corrected. Two spent backlog claims went with it.

#642, the pre-commit hook. The chore was to reconsider whether the hook should run the doc gates now that they are diff-scoped. Measuring first found this repository had no hook at all, while GOVERNANCE.md and scripts/README.md both described what one runs. There is now a committed .husky/pre-commit running the prose gate diff-scoped and the line-ending check repo-wide, with the .gitattributes and .editorconfig pins that GOVERNANCE.md "Line Endings" makes mandatory for an extensionless hook.

The formatting half the fleet convention names is deliberately absent, and that is the finding worth carrying: this repository declares [tool.ruff] in pyproject.toml and spec/project-types.json declares python.ruff.config, yet no workflow runs ruff and the tree does not pass it, at 13 of 57 files unformatted and 106 lint errors. A ruff step would have blocked every commit from the moment it landed. The GOVERNANCE.md bullet now states the condition rather than a tool list, that a repo adds each half once its tree passes that half, and the measurement is recorded as a TODO.md chore.

Carried content in this promotion

GOVERNANCE.md "Running the Linters Locally" changed, and that section is carried verbatim, so every downstream copy is byte-mismatched until the next fleet visit. It rides the re-vendor entry already tracked under TODO.md "Fleet Sweeps" rather than owing a sweep of its own.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Updates local tooling and bookkeeping to reflect recent decisions: closes/renumbers backlog references, refreshes the generated divergence ledger, and adds a repo-local pre-commit hook that runs the diff-scoped prose gate plus the repo-wide EOL consistency check (with corresponding documentation and line-ending pins).

Changes:

• Refresh backlog bookkeeping in TODO.md, including moving the About-hop entry to #639 and recording the ruff-convergence prerequisite before adding a ruff hook gate.
• Regenerate reports/divergences.md to reflect current verbatim drift counts across the fleet.
• Add .husky/pre-commit and update GOVERNANCE.md + scripts/README.md to describe the new hook behavior; pin the extensionless hook to LF in .gitattributes and .editorconfig.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
TODO.md	Backlog bookkeeping updates: renumbering/closure notes and adding a ruff-convergence chore before enabling ruff in hooks.
scripts/README.md	Updates script documentation to reflect that the pre-commit hook now runs two doc gates (diff-scoped prose gate + repo-wide EOL check).
reports/divergences.md	Regenerated divergence ledger reflecting updated drift counts/rows.
GOVERNANCE.md	Updates local-lint guidance to describe the hook running formatting + diff-scoped doc gates (and what remains CI-only).
.husky/pre-commit	Adds a repo-local pre-commit hook running prose_lint.py --diff HEAD and repo_gate.py --check eol.
.gitattributes	Pins .husky/pre-commit to LF to prevent CRLF shebang breakage.
.editorconfig	Pins .husky/pre-commit to LF at the editor layer to match .gitattributes enforcement.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (2)

scripts/test_host_gate.py:17

• scripts/test_host_gate.py manipulates sys.path before importing host_gate, so ruff's default E402 (import not at top of file) will flag this once ruff is enforced. Since pyproject.toml already configures ruff, keep the existing pattern but add an explicit suppression so this file doesn't add new debt during ruff convergence.

sys.path.insert(0, str(Path(__file__).resolve().parent))
import host_gate

docs/host-setup.md:33

• This section says python3 carries a 3.13 target floor and scripts/host_gate.py will enforce it as a hard minimum. The contract table above still says "Python 3", which can mislead a host on 3.12 into thinking it meets the requirement until the gate fails. Update the table row to reflect the enforced floor (3.13+).

Presence is the weaker half of this contract. Both host defects this fleet has actually hit are **version** facts on a tool that is installed, answers `--version`, and looks healthy, so the table above cannot see either one. [`spec/host-tools.json`][host-tools] carries the floors as data and records the defect each one encodes, and [`scripts/host_gate.py`][host-gate] reads it. A floor is one of two kinds and names its own kind in the `why` it carries. A **measured** floor sits above a version known to break a documented procedure, which is what both `gh` and `git-restore-mtime` carry. A **target** floor names the version the repo's own toolchain is configured for, which is what `python3` carries at 3.13, where `pyproject.toml` sets ruff and mypy to that version, so a lower interpreter is unverified rather than known broken and the entry says exactly that. Everything else carries none, deliberately: a floor nobody can justify becomes a host failure nobody can act on.

[ptr727]

Answering both suppressed findings from the round on 9eb2510e, which carry no thread to resolve.

The contract table, accepted and widened

The contract table above still says "Python 3", which can mislead a host on 3.12 into thinking it meets the requirement until the gate fails.

Correct, and it is not confined to the row it names. The table answers presence, and a tool below its floor answers --version exactly like one above it, so a host on gh 2.46 reads that row and reaches the same wrong conclusion, and has been able to since the gh floor was declared. Fixing only the Python row would have left the identical trap one row up.

docs/host-setup.md now carries a Floor column across the whole table, naming the kind beside the number, since a measured floor gives a failing host a defect to point at and a target floor does not. Restating a number in prose is how a document drifts from the data it describes, so a test reads the shipped file and asserts every required tool's declared floor appears in a table row. Written first against the old table to confirm it fails, its first failure was a real finding, git-restore-mtime declares a floor and has no row, which is what scoped it to required tools.

That is in #646, since a promotion pull request's head is the branch being promoted and cannot carry a fix of its own.

The E402 suppression, declined again on the same evidence

scripts/test_host_gate.py manipulates sys.path before importing host_gate, so ruff's default E402 will flag this once ruff is enforced.

This is the same claim raised and answered on #644, whose change is one of the commits this promotion carries. Ruff's E402 deliberately exempts an import that follows sys.path manipulation, which is why RUF100 reported the suppression as unused rather than as load-bearing. Two constructed files isolate the exemption:

$ cat e402a.py
import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).resolve().parent))
import json
$ uvx ruff check --isolated --select E402 e402a.py
All checks passed!

$ cat e402b.py
import sys

x = 1
import json
$ uvx ruff check --isolated --select E402 e402b.py
e402b.py:4:1: E402 Module level import not at top of file
Found 1 error.

Only the preceding statement differs. Adding the suppression back would put a noqa in the tree for a finding that does not occur, which RUF100 would then report, which is the loop the original removal ended.

Where the concern would be real is a pycodestyle-family linter, which has no such exemption. This repository runs none, and this promotion does not add one.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (1)

.husky/pre-commit:37

• The hook invokes python3 directly, but docs/host-setup.md notes that on native Windows the python.org install registers py (and python) but not python3, so this hook will fail for Windows contributors running Git hooks via Git Bash. Consider falling back to py -3 when python3 is not on PATH so the hook matches the documented host contract probes.

python3 scripts/prose_lint.py . --diff HEAD

# The eol check is repo-wide rather than diff-scoped, and it is here because it is already fast.
# It reads `.gitattributes` against `.editorconfig` for the whole repository and takes no file list.
# At about 0.04 seconds there is nothing to scope, so scoping it would only make it wrong.

[ptr727]

Answering the suppressed finding from the round on 1286e800, which carries no thread to resolve.

The hook invokes python3 directly, but docs/host-setup.md notes that on native Windows the python.org install registers py (and python) but not python3, so this hook will fail for Windows contributors running Git hooks via Git Bash.

Accepted, and fixed before this promotion rather than after it, in #647 against develop.

This is the repository contradicting itself rather than an oversight about an untested platform. docs/host-setup.md devotes a paragraph to exactly this hazard, and spec/host-tools.json already encodes the answer as its probe order, [["python3", "--version"], ["py", "-3", "--version"]]. The hook restated a name its own contract documents as wrong on a supported platform, and I wrote it having read that paragraph earlier in this session.

Reproduced the shape rather than reasoning about Windows from Linux, on a PATH carrying a stand-in launcher and no python3:

$ PATH="$D" sh .husky/pre-commit        # fixed hook
[ok  ] eol          0 issue(s)
exit=0

$ PATH="$D" sh "$D/old-pre-commit"      # the hook as this promotion carries it
old-pre-commit: 32: python3: not found
exit=127

Being precise about the failure, since it changes how urgent this is: exit 127 is non-zero, so the current hook blocks the commit rather than passing it falsely. It is unusable on such a host rather than silently wrong, which is the better of the two failures and still not one to promote.

It is fixed on develop first because this pull request's head is develop and cannot carry a commit of its own. This promotion will pick it up on its next head.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (1)

spec/host-tools.json:53

• The python3 tool's why text says older interpreters fail with an AttributeError "at the call rather than at startup", but spec/audit.py and scripts/pr_review.py now import UTC from datetime, which raises ImportError at import time on Python < 3.11. Updating this wording will keep the host contract accurate about the actual failure mode.

            "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, which gates the standard-library script tests and the prose and repo gates and nothing else, 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 and both sit lower: str.removeprefix and str.removesuffix need 3.9 and are called in spec/audit.py and scripts/prose_lint.py, and datetime.UTC needs 3.11 and is used in spec/audit.py, scripts/pr_review.py and their tests. Those are what an older interpreter actually fails on, as an AttributeError at the call rather than at startup. The name rather than the version is what differs per platform, which the second probe covers.",

[ptr727]

Answering the suppressed finding from the round on bfef86a7, which carries no thread to resolve. Fixed on develop in #648.

The python3 tool's why text says older interpreters fail with an AttributeError "at the call rather than at startup", but spec/audit.py and scripts/pr_review.py now import UTC from datetime, which raises ImportError at import time on Python < 3.11.

Accepted. The sentence collapsed two requirements into one failure mode and was wrong for one of them. str.removeprefix is a method call and fails as described. datetime.UTC arrives through a module-level import in all three files, so an older interpreter raises before any of the module runs.

Both failures were constructed rather than described, since naming the symptom is the sentence's whole job:

import-time  : ImportError -> cannot import name '...' from 'datetime'
call-time    : AttributeError -> 'str' object has no attribute 'removeprefix'

This matters more than a wording nit because of where the text is read. why is what scripts/host_gate.py prints to a host that has just failed the floor. Telling that reader to expect an AttributeError partway through a run, when what they will see is an ImportError before anything starts, sends them looking for a different problem.

It also has a common cause with the finding two rounds ago about "the lint and type results this repo gates on". Both are the same entry claiming more than was checked, in the one field whose stated purpose is to keep a floor from becoming folklore. The entry is now three corrections deep, and each correction came from reading it against the tree rather than from re-reading the sentence.

The fix is on develop because this pull request's head is develop and cannot carry a commit of its own. This promotion will pick it up on its next head.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 22 out of 22 changed files in this pull request and generated no new comments.

Suppressed comments (1)

GOVERNANCE.md:371

• The opening sentence says the .husky/pre-commit hook runs language formatting, but this repo's committed hook currently runs only doc gates (it explicitly documents the formatting half as absent). Consider rewording so the hook's behavior is described accurately even for repos mid-convergence (doc gates always; formatting once the tree passes/enables it).

- **The `.husky/pre-commit` hook** runs **language formatting** and the **diff-scoped doc gates**, never Docker and never a network call, so it stays fast. The formatting half is whatever the repo's own language needs, CSharpier and `dotnet format` for .NET or ruff for Python, via native tooling. A repo adds each half once its tree passes that half, since a gate that fails on the corpus it guards blocks every commit from the moment it lands, so a hook running one half is a repo mid-convergence rather than a repo out of conformance. The doc half runs each gate at the scope that fits it. The prose gate is scoped to what the commit changes rather than swept over the tree, which is the difference between about 2.2 seconds and about 0.13 and is what makes it affordable in a hook at all. A whole-repo check belongs there too when it is already fast and takes no file list, which the line-ending consistency check is, so scope is a property of the gate rather than a rule the hook applies to all of them. `repo_gate.py --check sha-pin` stays out, since it resolves a same-owner pin against the GitHub API and a hook that needs a network fails offline. A repo enables the hook per clone with `git config core.hooksPath .husky`, and CI remains the authoritative run either way.