Name configure.sh as the Hub's in the Rules Every Repo Carries - #657
Merged
Conversation
Two verbatim GOVERNANCE.md sections cited repo-config/configure.sh as though the reader had it. Branching Model carried a repo-relative inline link to ./repo-config/configure.sh, and Repository Boundaries and Write Safety used the bare path as the worked example of when suppressing a write's stdout is legitimate. Both sections are byte-locked fleet-wide, so all 22 repositories carry those words, and the file was retired from the manifest in #644's ledger and is carried by none of them. A downstream repository cannot fix this. Editing a verbatim section is what the fidelity check exists to prevent, so the reference is the hub's to correct for the whole class at once, which is what this file's own Documentation Style Conventions rule requires of a finding against carried rule text. Hub-Hosted Tooling already states the correct form: a tool named in a carried rule is named as the hub's, because the alternative is a pointer to a path the reader does not have. Both now read that way, and the Branching Model mention says the script runs from a hub checkout against the repository named on its command line, which is the invocation a reader needs rather than a path they lack. Raised by the ESPHome-Config agent, which found it while sweeping eleven inbound references to configure.sh across five files and discovered that two sat inside carried sections its own preamble forbids it to edit. That makes the retirement depend on the instruction set being current first, for any repository whose carried rule text cites the file being retired. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates byte-locked governance prose to stop referring to a repo-local repo-config/configure.sh that downstream repositories do not carry, and instead consistently name the hub-owned script and how it is reached.
Changes:
- Adjusts the write-safety “stdout suppression” exception example to reference the hub’s
repo-config/configure.sh(reachable from the hub, not carried per-repo). - Replaces the
Branching Modelrepo-relativeconfigure.shinline link with hub-scoped wording describing the intended execution context.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Aug 10, 2026
One squash: [#657](#657) at [`7bc6978`](7bc6978). **Merge with a merge commit, never a squash, and never with `--delete-branch`** — this PR's head *is* `develop`. ## Why it wants promoting rather than waiting It corrects two `verbatim` `GOVERNANCE.md` sections that cite `repo-config/configure.sh` as a repo-local path. Those sections are byte-locked, so until this reaches `main`: - All 22 repositories carry rule text pointing at a file none of them has, including a dead relative inline link in `Branching Model`. - Any repository re-vendoring its instruction set copies the **wrong** text down and needs a second re-vendor afterwards. The second point is live rather than theoretical. A Blog resync is committed on an unpushed branch, holding for this: its 12 re-vendored sections include both of the ones this PR corrects, so promoting first means Blog re-vendors once instead of twice. ## Fleet consequence, stated plainly This makes every downstream copy of those two sections stale, which is the mechanism working rather than a regression. They were already stale in most repositories, and the ones that were current become one re-vendor behind. ## Verification Checked mechanically rather than by eye: zero repo-relative pointers to `configure.sh` remain in any `verbatim` section of `GOVERNANCE.md`, walking the fidelity declarations in `spec/files.json` rather than a hand list of names. `prose_lint`, `markdownlint-cli2`, `editorconfig-checker` clean. The review on [#657](#657) was bound to its head commit and described both edits accurately. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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.
A fleet-wide defect that no downstream repository can fix, so it is the hub's to sweep for the whole class at once.
Problem
Two
verbatimGOVERNANCE.mdsections citerepo-config/configure.shas though the reader had a copy:Branching Model[configure.sh](./repo-config/configure.sh)Repository Boundaries and Write SafetyBoth sections are byte-locked fleet-wide, so all 22 repositories carry those exact words. The file was retired from the manifest and carries a
retiredisposition inspec/divergences.json, so none of them carries it. The link resolves nowhere and the example cannot be opened.A downstream repository cannot correct this: editing a verbatim section is what the fidelity check exists to prevent. This file's own
Documentation Style Conventionsrule says so directly, that a review finding against carried rule text is fixed at the hub for the whole class and re-vendored.The correct form was already written down
Hub-Hosted Toolingstates it: "A tool named in a carried rule is therefore named as the hub's, since the alternative is a pointer to a path the reader does not have." Both mentions now follow that.Branching Modeladditionally says the script runs from a hub checkout against the repository named on its command line, which is the invocation a reader actually needs in place of a path they lack.Provenance, and the sequencing consequence
Raised by the ESPHome-Config agent over peer messaging. Sweeping the inbound references for its own
configure.shretirement, it found eleven hits across five files, and two of them sat inside carried sections its own preamble forbids it to edit:That is a real ordering constraint the hub had not stated: for any repository whose carried rule text cites the file being retired, the hub-only retirement depends on the instruction set being current first. This PR removes the constraint at its source rather than documenting it, since after this there is no carried section citing the path.
It also observed a fourth reference shape that #654 and #656 do not cover: a mention that is about the path rather than a use of it, such as incident history recording that a backtick-quoted
configure.shin a review reply once executed the script. "Remove the mention" is wrong for that shape, because the history stays true. Not addressed here, and worth its own decision.Verification
Checked mechanically rather than by eye: zero repo-relative pointers to
configure.shremain in anyverbatimsection ofGOVERNANCE.md, walking the fidelity declarations inspec/files.jsonrather than a hand list of section names.prose_lint --diff HEAD,markdownlint-cli2,editorconfig-checker: all clean.Note on ordering
This changes two verbatim sections, so it makes every downstream copy stale and belongs in the next promotion. A Blog resync is in progress on an unpushed branch and is held for it, so Blog re-vendors these two sections once from corrected text rather than twice.
🤖 Generated with Claude Code