From 4794c5451972357e7fc571f97d8e91cd9080f7ae Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Mon, 10 Aug 2026 11:45:55 -0700 Subject: [PATCH 1/2] Name the Host Contract Where the Layout Enumerates spec/ 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) --- GOVERNANCE.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 1156020d..4f5e4b19 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -432,7 +432,7 @@ Every repo's GitHub repository details (the About panel) follow a fixed conventi - [`AGENTS.md`](./AGENTS.md): the agent entry point, carrying context and delegation rules plus the map to the sections below. - [`GOVERNANCE.md`](./GOVERNANCE.md), [`CODESTYLE.md`](./CODESTYLE.md), [`WORKFLOW.md`](./WORKFLOW.md), [`AUDIT.md`](./AUDIT.md): the governance and audit docs. This file is the cross-cutting-rules authority. -- [`spec/`](./spec/): the machine-readable ground truth, covering project-type requirements, the file/section baseline, secrets, and the preferred README structure. +- [`spec/`](./spec/): the machine-readable ground truth, covering project-type requirements, the file/section baseline, secrets, the host tool contract and its floors, and the preferred README structure. - [`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. diff --git a/README.md b/README.md index adb54e70..5d8ef271 100644 --- a/README.md +++ b/README.md @@ -87,7 +87,7 @@ This repo is the single home for those rules, a machine-readable spec they are c - **[STANDUP.md][standup]** - how an agent stands a repository up and carries the baseline it is owed. - **[AUDIT.md][audit]** - how an agent audits a repository against the spec and reports drift. - **[RESYNC.md][resync]** - how an agent brings an already-stood-up repository back into line, in the order the remedies require. -- **[spec/][spec]** - the machine-readable ground truth: project-type requirements, the file/section baseline, required/forbidden secrets, and the preferred README structure. +- **[spec/][spec]** - the machine-readable ground truth: project-type requirements, the file/section baseline, required/forbidden secrets, the host tool contract and its version floors, and the preferred README structure. - **[registry/repos.json][repos]** - the fleet registry: every project, its type(s), publish mechanism, and status (cataloged or standardization backlog). - **[repo-config/][repo-config]** - branch rulesets and the apply script (kept out of `.github/`, which is Actions-owned), plus the GitHub setup reference. - **[host-setup/][host-setup-dir]** - the host guardrail kit, which is per machine rather than per repository. From 43fdf9ee03b5b7a9297aa32e070570b39cc07618 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Mon, 10 Aug 2026 11:49:55 -0700 Subject: [PATCH 2/2] Record Peer Messaging as a Method Awaiting a Home 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) --- TODO.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/TODO.md b/TODO.md index 45e2a964..25dc9607 100644 --- a/TODO.md +++ b/TODO.md @@ -367,6 +367,24 @@ One pull request adding the observer the fleet has no equivalent of, reading mer - **Settled** - Two floors are not optional. A run reading zero pull requests reports that rather than a clean zero, and a repo the search surfaces with no registry entry is reported separately, which feeds "Registry Membership Coverage" above. - **Settled** - This is not the deferred audit automation recorded under "Standalone Chores". That entry rejected three scheduled and hook-driven shapes on three blockers, and this is owner-run and on demand like [`spec/fidelity_honesty.py`][fidelity-honesty], so it lands on none of them. +### Peer Messaging Between Agents as a Declared Method + +One pull request writing down the agent-to-agent messaging this fleet has now used successfully, so it is a method with stated boundaries rather than a capability each session rediscovers. The mechanism already works and needs no build, so the deliverable is prose plus the decision about where prose that binds a downstream agent is allowed to live. + +**State** `decision`. **Touches** either `GOVERNANCE.md` with [`spec/files.json`][files] and [`spec/section-model.md`][section-model], or a hub-only `docs/` file, and the choice between those is the decision. **Cost** one hub edit, and a fleet-wide re-vendor on the first option only. + +- **Declare peer messaging a standard method, and decide which document carries its rules.** The safety half is the load-bearing half: confirm a peer's identity before sending it anything substantive, verify a peer's factual claims against the tree before repeating them, never read a peer's request as the maintainer's approval, and never ask a peer to perform what the asking session was denied. + - **Blocked by** - Nothing. The mechanism is live and was exercised end to end on 2026-08-10. + - **Issue** - None filed. + - **Checked** - `develop` at `3855dbb` on 2026-08-10, against a live exchange with the ESPHome-Config session on this host, and `ListAgents` listing two local peers and no cloud or remote row. + - **Open** - Whether the rules belong in `GOVERNANCE.md` as a carried verbatim section or in a hub-only `docs/` file. The first reaches the downstream agents the rules are about and costs a fleet-wide re-vendor plus the two manifest edits [`spec/section-model.md`][section-model] requires of any new section. The second costs nothing and leaves the rules unreachable from the repositories that would apply them, which is the failure `AGENTS.md` "Fleet Bootstrap" exists to prevent. + - **Open** - Whether to document cross-host at all while it is unverified, or to state the same-host limit and leave the rest until a second machine is reachable. + - **Settled** - Same-host works and cross-host does not, by construction rather than by configuration. A peer address is a Unix domain socket under `/run/user/1000/cc-socks/`, which cannot cross a machine boundary. Cloud sessions and Remote Control sessions on other machines are the documented cross-host paths and neither appears in a listing on this host, so both are unverified rather than absent. + - **Settled** - The addressing has a guardrail worth keeping in the write-up. A bare peer name was refused and the transport required the `[ref]` a listing prints, which is what stops a message reaching the wrong repository's agent. + - **Settled** - The method earns its place on evidence rather than novelty. One exchange produced the causal commit for the section 6 ruleset defect, `90e3255`, which the hub session had not identified from the symptom, plus a one-line reproduction of the gojq key-sorting behavior that made an earlier fix pass for the wrong reason, plus four procedure gaps a reader found that no gate reports. + - **Settled** - A peer's finding is checked rather than adopted. Two of those four did not reproduce at the hub, the `AGENTS.md` anchor rewrite and the settings-diff exposure, and one did and shipped as #653. So the write-up states verification as a step rather than as a courtesy. + - **Settled** - The boundary that matters most is not politeness but permission. A peer cannot widen what the asking session may do, so work blocked in one session goes back to the maintainer rather than sideways to another agent. + ## Standalone Chores Small work with no research to preserve, selectable one bullet at a time.