Promote the README Rework, the Tool-Row Repair, and the Line-Ending Gate

[ptr727]

Closes#633.

Promotion of develop at 2082547, six squashes since the last one. Merge commit only, no squash and no rebase, and no --delete-branch, since this pull request's head is develop itself.

What is being promoted

Squash	Change
9b73d1a (#631)	Routes the README by reader, adding a Getting Started table above the Table of Contents and three sections the file lacked, and documents the GH_WRITE_GUARD_ALLOW grant in docs/host-setup.md where a denied cross-owner write puts the reader.
c2ce145 (#632)	Moves readme.sections from intent to letter and adds four checks beside it, backed by the new spec/readme-sections.json and spec/third-party-tools.json. Settles the tagline rule, which is #577's first half, and closes the License section over the file.
0bb43c5 (#634)	Adds repo_gate.py --check eol-coverage, reading the line-ending pins against the tree rather than only against .editorconfig, in the two directions #633 measured: a shebang file git does not resolve to eol=lf, and a pin matching no tracked file.
1e2a4ba (#636)	Repairs the tool-row reader Copilot found on this pull request: both outer table pipes are optional, as GitHub's Markdown makes them, and the header is read for the License column that spec/project-types.json already asserted at verdict letter without anything reading it.
042c853 (#637)	Repairs the second reader Copilot found here: a retired badge written as an inline image was invisible to the deprecatedShields scan, which read reference definitions alone, and the finding's own wording then mis-attributed a render to an unused reference.
2082547 (#638)	Adds scripts/host_gate.py and spec/host-tools.json, turning the host contract's presence check into a version gate. Retires two gh workarounds that were artifacts of a stale distribution package, re-tested on an upgraded host rather than inferred.

27 files at 2906 insertions against 101 deletions, of which spec/ and scripts/ are 2597, so the prose half of the diff is small.

The closing keyword

Closes #633 is on this pull request rather than on #634, because GitHub fires a closing keyword only when it merges into the default branch, and #634 merged into develop. Merging this closes that issue. The work itself landed in 0bb43c5.

Issue #577 stays open deliberately. Its tagline half shipped in c2ce145, and TODO.md now reuses the issue for what remains, the README-to-About-panel hop that nothing writes.

The two findings this pull request produced

Both are defects in develop, not in the promotion, and both were fixed on develop rather than here, since this pull request's head isdevelop. They share one shape, which is the reason to state them together: a claim wider than the code behind it, where the comment, the finding text and the selftest name all agreed with each other and none agreed with the behavior.

• Read a Tool Row Without a Trailing Pipe, and Report the License Column #636, the tool-row reader.third_party_tool_findings required a trailing pipe on every row, so a valid Markdown row without one was skipped and its link, description and ordering all went unread. A table written that way reported zero findings, which scores as clean rather than as unread. Round 2 found the symmetric case on the leading pipe. Also makes honest an assert spec/project-types.json already carried at verdict letter, that the section carries no License column, which nothing read.
• Report a Retired Badge Written Inline, Not Only One Defined #637, the retired-badge scan.readme_shield_findings read reference definitions alone while its comment said the badge is caught "wherever it sits" and its selftest case carried that name while testing one form. An inline badge rendered and reported nothing. Three further rounds corrected the finding's own wording, moved attribution from the URL to the reference name, and settled the four shapes a retired badge can take.

Measured across all 22 cataloged READMEs at every round, in both directions: tool findings go 56 to 57, the addition being Blog's License column; shield findings stay at 7 with no verdict and no wording moving. No fleet README carries either blind spot today, so both fixes close a silent gap rather than correct a live report. Stating that plainly is the point: the 17 repos still owing a 3rd Party Tools section have not written their tables yet.

What this owes downstream

Three carried files changed, and each reaches the fleet differently:

• GOVERNANCE.md"Repository Details" is verbatim, so every downstream copy is byte-mismatched and the audit reports it as stale. It propagates a rule rather than refreshing a hash: the About description is the tagline alone rather than the paragraph it opens, and Docker Hub receives it from the About panel rather than from the README, so a panel left diverged is carried onward instead of corrected at publish time.

• CODESTYLE.mditem 4 is intent and whole, so no audit reports it. A repo on the old copy has HISTORY.md mirror the whole intro paragraph, which is wrong for any README that takes the room the tagline rule opens.

• .gitattributes is intent and whole, and this one couples to the new gate. eol-coverage exempts a pin block marked forward-declared, and a repo holding the pre-0bb43c5 copy carries no such mark, so its uv.lock, Dockerfile and *.Dockerfile pins read as dead the first time the check runs there against a tree with no lockfile and no Dockerfile.

• .github/copilot-instructions.md is intent, so nothing reports it, and it propagates a correction rather than a refresh. Its gh pr edit entry called the command broken outright; it now names the 2.45.x / 2.46.x range and says to check gh --version first. A repo left on the old copy has its agents routing around a command that works, which is the inverse of the usual staleness: the old text is not merely out of date, it is now wrong.

AUDIT.md is intent and takes one dimension description; cspell.json takes one word; OPERATIONS.md and docs/host-setup.md are this repo's own; spec/ and scripts/ are hub-hosted tooling and carry nothing.

None of these four are recorded in the TODO.md re-vendor entry yet, which still lists the batch ending at #629. That entry needs the three above added before the sweep runs, and saying so here rather than editing TODO.md on this pull request keeps the promotion a merge of what develop already holds.

The conformance backlog this opens

The readme-structure checks were run against all 22 cataloged repos before shipping, and TODO.md records what they report: 73 section and shield findings, 57 third-party-tool findings across four repos, 55 link-naming findings with 27 more on grouping, and the retired byob.yarr.is badge on three repos. No repo is edited by the hub, and each lands on its own next visit. This repo reports zero across all four checks.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Promotes the develop changeset that reworks the README (including tagline/mirror semantics and audited README structure) and adds a new repository gate for line-ending coverage, then carries the corresponding spec/tooling updates into main.

Changes:

• Updates the README spec and audit tooling to treat the first post-H1 line as the canonical tagline, and adds auditable README structure/link/shield/tool-catalog rules.
• Introduces a new repo_gate.py --check eol-coverage that validates .gitattributes EOL pins against the tracked tree (shebang LF enforcement + dead-pin detection with forward-declared exemptions).
• Updates documentation and governance text to align with the new README/tagline and EOL-coverage behaviors.

Reviewed changes

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

Show a summary per file

File	Description
TODO.md	Updates backlog entries to reflect the shipped tagline work and the new downstream-observer idea, plus link ref maintenance.
spec/validate.py	Adds shape checks for spec/readme-sections.json and spec/third-party-tools.json to avoid audit crashes and silent passes.
spec/third-party-tools.schema.json	Adds JSON schema for the shared 3rd party tool catalog.
spec/third-party-tools.json	Introduces the shared 3rd party tool catalog (standardized links/descriptions).
spec/readme-structure.md	Updates README prose spec (tagline semantics, required sections, link groups, shields, tools catalog rules).
spec/readme-sections.schema.json	Adds JSON schema for the declared README section/link/shield model.
spec/readme-sections.json	Adds the declared README model consumed by the audit (sections, link groups/naming, shield classes, canonical links).
spec/project-types.json	Promotes README checks from intent to letter and adds new README-related checks (sections/shields/links/tools/tagline).
spec/audit.py	Implements README structure/shield/link/tool checks and tagline-based mirroring behavior.
scripts/test_repo_gate.py	Expands tests to cover eol-coverage, forward-declared pins, and gitattributes-matching correctness.
scripts/repo_gate.py	Adds eol-coverage gate (tree-facing EOL pin validation) and supporting helpers.
scripts/README.md	Documents the new eol-coverage check and its rationale/constraints.
README.md	Reworks the README structure (Getting Started routing, new sections, canonical link groups, license shield placement).
host-setup/agent-safety/README.md	Documents cross-owner write grants (GH_WRITE_GUARD_ALLOW) and removes Proxmox mentions.
host-setup/agent-safety/install.sh	Updates platform comment (removes Proxmox mention).
GOVERNANCE.md	Updates “Repository Details” to define description/tagline semantics and Docker Hub propagation path.
docs/host-setup.md	Adds a detailed “Granting a Write the Guard Denies” section and removes Proxmox mention.
cspell.json	Adds “untriaged” to the dictionary.
CODESTYLE.md	Updates HISTORY.md mirroring rule to mirror the tagline (not the full intro paragraph).
AUDIT.md	Updates readme-structure dimension description to reflect the declared model + new checks.
.gitattributes	Marks uv.lock/Dockerfile pins as forward-declared to support the new dead-pin coverage check.

---

💡 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 21 out of 21 changed files in this pull request and generated no new comments.

Suppressed comments (1)

spec/audit.py:796

• readme_shield_findings claims retired badge services are reported “wherever it sits”, but the implementation only scans reference definitions (defs.items()). If a repo uses the retired badge as an inline image (![...](https://...)), it won’t appear in defs and will be missed even though the URL is rendered in the README.

 findings = []
defs = {m.group(1): m.group(2) for m in _LINK_DEF.finditer(unfenced_text(text))}
# A retired badge service is scanned across the whole document rather than per section, since a dead badge is wrong wherever it sits.
# It renders broken rather than absent, which a visitor reads as a failing build rather than as a stale badge.
for dep in model.get("deprecatedShields", []):
for ref, url in sorted(defs.items()):
if dep["match"] in url:
findings.append(("LETTER", f"readme: `[{ref}]` renders {dep['label']}, which is retired - {dep['reason']} (spec/readme-structure.md)"))

[Copilot]

Pull request overview

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

[ptr727]

Closing the record on the suppressed finding raised here on 1e2a4ba, whose fix landed on a separate pull request:

readme_shield_findings claims retired badge services are reported "wherever it sits", but the implementation only scans reference definitions (defs.items()). If a repo uses the retired badge as an inline image (![...](https://...)), it won't appear in defs and will be missed even though the URL is rendered in the README.

Accepted and fixed on develop in #637, now 042c853, which this pull request's head carries. It took four rounds, because the first fix was correct and its reporting was not:

1. Both image forms are read, via shield_endpoints, which already resolved them for every other shield and whose docstring records this exact lesson. This was the one site that had not taken it.
2. The finding text claimed every matching definition "renders" the badge, contradicting the comment directly above it. The wording now follows which of four shapes applies.
3. Attribution moved from the URL to the reference name. The same endpoint rendered inline leaves a definition unused, so reading the URL credited that render to a reference nothing uses, and deleting the named reference would have left the badge on the page.
4. The endpoint set is held as a set, named by namespace, since this block reasons about reference names and URLs a line apart and step 3 was exactly that confusion.

Measured against all 22 cataloged READMEs at every round: shield findings stay at 7 and no verdict and no wording moves, because all three repos carrying the badge write it as a rendered reference definition. Every new selftest case was A/B tested against the pre-fix function rather than reasoned about.

Both findings this pull request produced share one shape, which is why the description now states them together: a claim wider than the code behind it, where a comment, a finding message and a selftest name all agreed with each other and none agreed with the behavior. Neither was introduced by this promotion; both were in develop and are now fixed in it.

[Copilot]

Pull request overview

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