Split carry-process out of the carried repo-config README into a hub-only doc (#345) - #349
Merged
Conversation
…only doc (#345) Finding 1: repo-config/README.md is carried verbatim by every fleet repo, but it shipped carry-*process* narration - the Downstream Carry rules, the ruleset import/regen procedure, and the maintainer brownfield migration - which is meta-guidance for whoever performs the carry, not a current fact about the repo the file lands in. (This is also how the private-repo link reached public carriers; #344 removed the link, this removes the narration that hosted it.) - New hub-only docs/repo-config-carry.md holds the carry/apply/regen process: Downstream Carry, Applying the Config, Regenerating the Payloads, Brownfield Migration. Not in spec/files.json baseline, so never carried downstream; being hub-only it may name repos and link the hub freely. - repo-config/README.md trims to current facts about a repo's own config: the file descriptions, what the rulesets enforce, the secrets each mechanism needs, the general settings. - Cross-refs fixed: AGENTS.md (carried) plain-text-mentions the hub doc for the full procedure/brownfield instead of linking it, and drops two stale anchors ("Rules / Rulesets", "Template - GitHub Setup"); STANDUP.md and spec/files.json (both hub-only) point at the new doc. Finding 2: the adapted spec/secrets.json shape rule now lives in the hub doc - a source-only repo whose targets all map to null carries just baseline (no lone targetMechanisms map, which read as a schema bug that tripped Copilot 3x); a repo with a real mechanism carries mechanisms + its targetMechanisms routing. spec/validate.py passes; markdownlint, editorconfig-checker, and the CI-scoped cspell all clean; no dangling references. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Moves fleet carry/apply/regen guidance out of the carried repo-config/README.md into a hub-only document, so downstream repos only receive repo-scoped, “current facts” documentation while the hub retains the full operational procedure.
Changes:
- Add hub-only
docs/repo-config-carry.mdand update hub-only references to point to it. - Trim
repo-config/README.mdto remove downstream-carry and brownfield-migration process narration. - Update intent references and spelling allowlist to match the new doc split.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| STANDUP.md | Updates the setup procedure link target to the new hub-only carry doc. |
| spec/files.json | Retargets AUDIT.md / spec/secrets.json intent refs to the hub-only carry doc. |
| repo-config/README.md | Removes carry-process and brownfield-migration sections so the carried README stays repo-scoped. |
| docs/repo-config-carry.md | Introduces the hub-only carry/apply/regen/brownfield procedure document. |
| cspell.json | Adds “regen” to the word allowlist. |
| AGENTS.md | Updates references to point at the new hub-only doc and adjusts anchors to the trimmed README. |
docs/repo-config-carry.md now uses reference-style links with the definitions grouped at the bottom, per the AGENTS.md Markdown rule (inline links are reserved for AGENTS.md and copilot-instructions.md). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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 free
to 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.
Fixes #345 (both findings). Surfaced when ESPHome-Config became the first public repo to carry
repo-config/README.md.Finding 1: carry-process narration shipped downstream
repo-config/README.mdis carried verbatim by every fleet repo, but it shipped carry-process guidance -## Downstream Carry, the ruleset import/regen procedure, and the maintainer## Brownfield Migration. That is meta-guidance for whoever performs the carry, not a current fact about the repo the file lands in (it's also what hosted the private-repo link #344 removed).Split (the settled approach):
docs/repo-config-carry.mdholds the process: Downstream Carry, Applying the Config, Regenerating the Payloads, Brownfield Migration. It's not inspec/files.jsonbaseline, so it's never carried; being hub-only it may name repos and link the hub freely.repo-config/README.mdtrims to current facts about a repo's own config: file descriptions, what the rulesets enforce, the secrets each mechanism needs, the general settings.AGENTS.mdplain-text-mentions the hub doc for the full procedure/brownfield and drops two stale anchors (Rules / Rulesets,Template - GitHub Setup);STANDUP.mdandspec/files.json(both hub-only) link the new doc directly.Finding 2: repo-scoped secrets schema clarity
The rule for the adapted
spec/secrets.jsonnow lives in the hub doc: a source-only repo whose publish targets all map to a null mechanism carries justbaseline(+note) - it omitstargetMechanisms, since a lone routing map with nomechanismsreads as "the audit ignores the mechanism list" (Copilot tripped on it 3x across the standup PRs). A repo with a real mechanism carriesmechanismsand itstargetMechanismsrouting, which the audit picks up.Rollout
Hub only. Downstream repos' carried
repo-config/README.md(and any source-onlyspec/secrets.jsonstill carrying an all-nulltargetMechanisms) correct on each repo's next conformance touch - consistent with the prior sweeps. ESPHome-Config already stripped both in its standup.Validation
spec/validate.pyOK; markdownlint + editorconfig-checker clean on all changed files; CI-scoped cspell (README+HISTORY) clean; grep confirms no dangling references to the moved sections.🤖 Generated with Claude Code