Name the Host Contract in the Layout, and Record Peer Messaging - #653
Merged
Conversation
Two enumerations of spec/ list its contents and stop before the host tool contract, which landed there in #652 along with a stub at the repository root. Both were accurate when written and are now short by the part a reader looking for the tool floors would search for. Raised by the ESPHome-Config agent, which hit the same class in its own Repository Layout section while planning its AGENTS.md split, and named it as the trap the Documentation Style Conventions maintenance rule exists for: prose elsewhere that no gate can see going stale under a change it never mentioned. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates repository documentation to explicitly include the host tool contract within the spec/ directory descriptions, keeping the high-level layout summaries accurate after the host contract addition.
Changes:
- Extend
README.md’sspec/bullet to mention the host tool contract and version floors. - Extend
GOVERNANCE.md“Repository Layout”spec/entry to mention the host tool contract and floors.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Updates the spec/ summary bullet to include the host tool contract and version floors. |
| GOVERNANCE.md | Updates the “Repository Layout” spec/ entry to include the host tool contract and floors. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Agent-to-agent messaging was exercised end to end today and produced findings no gate reports, so it is worth declaring rather than rediscovering. The entry is a decision cluster because the mechanism needs no build and the only open question is which document may carry rules that bind a downstream agent: GOVERNANCE.md reaches them and costs a fleet-wide re-vendor, a hub-only doc costs nothing and leaves them unreachable from the repositories they govern. Cross-host is recorded as settled and negative. A peer address is a Unix domain socket, which cannot leave the machine, and the two documented cross-host paths appear in no listing here, so they are unverified rather than absent. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Aug 10, 2026
Promotion of six squashes. **Merge with a merge commit, never a squash, and never with `--delete-branch`** — this PR's head *is* `develop`. | PR | What it fixed | |---|---| | [#649](#649) | `AUDIT.md` section 6's ruleset diff projected `bypass_actors`, which no payload declares, so jq exited 5 and **every ruleset on every repo reported DRIFT**. Two further surfaces carried the same dead policy. | | [#650](#650) | The deletion detector: hub git-tracked paths minus the `spec/files.json` baseline, so a retired file is derived rather than remembered. Corrected `configure.sh` from 6 carriers to **15**. | | [#651](#651) | `RESYNC.md`, the third entry point, routed from the byte-locked `AGENTS.md` "Fleet Bootstrap". | | [#652](#652) | A `jq` 1.7 target floor, `host-tools.json` as a carried baseline file, and `scripts/host_gate.py` wired into all three procedures for the first time. | | [#653](#653) | Two `spec/` enumerations that went stale when the host contract landed there. | | [#654](#654) | The inbound-reference sweep counts as part of a deletion, including the runnable-command and orphaned-definition shapes. | ## Why this promotion matters more than most Downstream repos read hub `main` as ground truth. While `main` sits at [`0a86bca`](0a86bca): - Every repo that runs the `AUDIT.md` section 6 snippet gets **false ruleset drift on both branches**. The ESPHome-Config agent reproduced this live and is holding its own fix stashed rather than diverging from the hub. - A repo resyncing now re-vendors to `main`'s revision and then again after promotion. Verified against Blog, whose carried `AGENTS.md` "Fleet Bootstrap" differs from both refs, so it is two re-vendors instead of one. - `RESYNC.md` does not exist on `main`, so a downstream agent asking "how do I sync" still routes to `AUDIT.md`, which measures and deliberately states no order. ## Fleet cost this carries, measured and accepted `host-tools.json` becomes a carried baseline file, so it is one `LETTER` on **22 of 22** cataloged repos, the hub included. That was measured before landing and accepted by the maintainer. `RESYNC.md` section 0 was amended so a letter wave of this shape reads as a file to carry inside a resync rather than as evidence a repo was never stood up. ## Verification on the merged head `spec/validate.py` OK, `spec/audit.py --selftest` PASS, 557 script tests OK, `scripts/host_gate.py` clean over 7 declared tools, `repo_gate.py --check eol` clean, `editorconfig-checker` clean, working tree clean. Post-merge fleet audit: 22 repos, **zero errors**. Two hub-side artifacts clear on this merge, both promotion-pending rather than defects: the hub's own `AGENTS.md` "Fleet Bootstrap" reads as stale against its `develop` canonical, and the hub reports its own `host-tools.json` absent because the file exists on `develop` only. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
ptr727 added a commit
that referenced
this pull request
Aug 11, 2026
A pre-release check that found something, rather than a change anyone asked for. ## Problem `HISTORY.md`'s Version 2.0 entry enumerates what this repository became: *"the shared fleet rules, a machine-readable `spec/`, the fleet `registry/`, per-repo audit `reports/`, branch rulesets, and the `AUDIT.md` convergence procedure."* Three things shipped since are **peers of the items in that list** and appear nowhere in it: - **`RESYNC.md`**, now the third procedure an agent routes between, not a detail of the second - **The host tool contract** and its version floors, `spec/host-tools.json` plus a carried `host-tools.json` per repository - **The derived detector** for files the hub hosts rather than carries, so a retired file is found rather than remembered ## Why it was worth catching first A patch release cut against this entry would have published a changelog whose summary omits the session's main deliverable. A reader asking how a repository resyncs would find an enumeration naming only the procedure that *measures*. `HISTORY.md` is per minor version rather than per patch, so nothing is owed for a routine `2.0.x`. What is owed is that the 2.0 summary stay true about what 2.0 contains, and it had stopped being true. ## The pattern, third time today This is the same shape as the `spec/` enumerations corrected in [#653](#653) and the `Repository Layout` bullet corrected downstream in Blog: **a list that was accurate when written, going stale under a change that never mentioned it, with no gate that reads it.** The recurrence is worth noting on its own. Three instances in one session suggests enumerations are a standing hazard rather than three accidents, and the deletion sweep's new "read the files whose job is to say what the repo holds" ([#660](#660)) covers deletions only. Additions have no equivalent instruction. Not fixing that here. ## Verification The `README.md` and `HISTORY.md` openings must mirror per `spec/readme-structure.md`, so that was checked rather than assumed: titles match, taglines match, using the audit's own extraction. `cspell` on both gated files clean, `prose_lint --diff HEAD` clean, `markdownlint-cli2` clean, `editorconfig-checker` clean, CRLF preserved byte-wise. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Two changes from one source: a stale enumeration a peer agent found, and a backlog entry for the method that found it. TODO disposition: New entry, per
TODO.mdrule 8.1. The stale enumeration
Two enumerations of
spec/list its contents and stop before the host tool contract, which landed there in #652 along with a stub at the repository root:GOVERNANCE.md"Repository Layout"README.md'sspec/bulletBoth were accurate when written. Neither is now, and a reader looking for where the tool floors live would search both and find nothing.
Provenance, and two claims that did not reproduce
Raised by the ESPHome-Config agent over peer messaging, not by a gate. It hit the same class in its own
Repository Layoutwhile planning itsAGENTS.md->AGENTS.md+GOVERNANCE.mdsplit, and named it as the trap theDocumentation Style Conventionsmaintenance rule exists for: prose no linter can see, going stale under a change that never mentioned it.I checked the hub for the same shape and for two adjacent claims from the same report. Recorded because a future reader will wonder:
AGENTS.md#<section>for sections that moved toGOVERNANCE.mdAGENTS.md#anchors tree-wide, so the hub's anchors were rewritten with the split. Downstream-only, for repos still carrying pre-split docs.gh api ... --jq '{...}'projections feeding a diff share the gojq key-sorting exposure fixed in #649jq -S .over a flat boolean object, so key order cannot reach the comparison. Verified by running it both ways,gh api --jqand rawgh apipiped to realjq: byte-identical.repo-config/keeps its "apply script" wording, still true of the hub, which hosts the script it no longer carries downstream.2. The backlog entry
A
decisioncluster, because the mechanism needs no build and the only open question is which document may carry rules that bind a downstream agent.GOVERNANCE.mdreaches those agents and costs a fleet-wide re-vendor plus the two manifest editsspec/section-model.mdrequires of any new section. A hub-onlydocs/file costs nothing and leaves the rules unreachable from the repositories that would apply them, which is the failureAGENTS.md"Fleet Bootstrap" exists to prevent.Settled and recorded so it is not re-derived:
/run/user/1000/cc-socks/, which cannot cross a machine boundary. Cloud sessions and Remote Control sessions are the documented cross-host paths and neither appears in a listing on this host, so both are unverified rather than absent.[ref]a listing prints, which is what stops a message reaching the wrong repository's agent.90e3255), which this session had not identified from the symptom; a one-line reproduction of the gojq behavior that made an earlier fix pass for the wrong reason; and four procedure gaps no gate reports.Verification
prose_lint --diff HEAD,repo_gate --check eol,editorconfig-checker,markdownlint-cli2onTODO.md, andcspellon the gated files: all clean. Both[files]and[section-model]reference names already resolve inTODO.md.GOVERNANCE.md"Repository Layout" isintentfidelity perspec/section-model.md, so part 1 forces no fleet-wide re-vendor.🤖 Generated with Claude Code