Hold the README shape constant across repository visibility - #511
Merged
Conversation
spec/readme-structure.md stated no behavior for a private repo, so each one decided separately whether to write the GitHub-sourced shields that shields.io cannot read while private. PhotoCleaner carried Docker Hub shields only and planned to add the rest at the visibility flip. The maintainer's decision is that the structure does not vary. A private repo carries the same sections and the same shield set, written in full, and the broken badges are accepted until it goes public. The reason is that visibility is temporary by design. A repo is usually private precisely while it is being made presentable, which is exactly when its README is written, so keying the shape to visibility means writing the README twice and owing work at the flip. Carrying the full shape makes going public a visibility change and nothing else, and leaves the audit one shape to accept rather than two. Answers finding 3 of #509. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the README structure specification to explicitly define expected behavior for private repositories, ensuring repository visibility does not introduce a second, conditional README shape across the fleet.
Changes:
- Specifies that private repos must keep the same README sections and GitHub badge set as public repos.
- Documents that broken GitHub-sourced shields in private repos are an accepted temporary cost rather than something to work around.
The paragraph opened a sentence with "shields.io", which reads as a continuation and is the lowercase-opening problem the review flagged. The suggested fix was to write "Shields.io", which the repo's own rules forbid: CODESTYLE.md requires each tool's official casing in prose and says not to invent variants, and GOVERNANCE.md says to restructure so the sentence does not open on a lowercase tool name rather than capitalizing it against its official spelling. So the sentence now opens on the subject instead, which fixes the opening and keeps the tool's own casing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Answers the four remaining spec questions from #509, raised by the PhotoCleaner agent. Finding 3 landed separately in #511. Each was verified against the current tree before being changed. ## 1. `.github/copilot-instructions.md` described the pre-split `AGENTS.md` The carried `Reviewing Carried Fleet Content` section said most of `AGENTS.md` is fleet law and that two of its sections describe this repository's own directory tree and devcontainer. Verified wrong in **both** halves against `spec/files.json`: - `AGENTS.md` declares exactly two sections, both `verbatim`, and no repo-specific ones. - `GOVERNANCE.md` holds the sixteen rule sections **and** the two `intent` ones, `Devcontainer` and `Repository Layout`. It is carried at `intent`, so every repo inherits the stale description, and a reviewer following it looks for byte-locked rule text in the wrong file. Now names `GOVERNANCE.md` as the fleet-law file and describes `AGENTS.md` as the thin router carrying two byte-locked sections of its own. ## 2. `CODESTYLE.md` contradicted `.markdownlint-cli2.jsonc` on MD033 `CODESTYLE.md` said HTML elements are flagged. `.markdownlint-cli2.jsonc:10` sets `"MD033": { "allowed_elements": ["details", "summary"] }`, and the config's own comment documents the exception the prose denied: "The details and summary elements are allowed for GitHub collapsibles, which have no markdown equivalent." The prose now matches the config, naming the two allowed elements and why. ## 3. The `HISTORY.md` mirror rule had no carried home The rule lived only in `spec/readme-structure.md`, which is **hub-only** and appears in no `spec/files.json` entry, so no repo carries it. A repo could not read the rule it was being graded against, and PhotoCleaner wrote a local copy into its own `CODESTYLE.md` for want of a destination, which is the duplication the fleet normally avoids. The maintainer's call was to move it where it can be audited, so it becomes item 4 of `CODESTYLE.md` "Markdown and Spelling", which every repo carries whole. `spec/readme-structure.md` now states only **what the audit does** with the rule rather than restating it, so there is one authority and one pointer rather than two copies. ## 4. `WORKFLOW.md` D2.2 "skipped on smoke" was ambiguous D2.2 said the gate "is **skipped on smoke**", naming the *validation*. A Copilot review on PhotoCleaner#29 read it as the **job status** and proposed a job-level `if: !inputs.smoke`. That would have been a real regression rather than a style difference: `github-release` carries `validate-release` in its `needs`, and a skipped need skips the dependent, so the release job would have been coupled to smoke through a second path on top of the `if:` it already carries. The canonical was right and the wording invited the misreading. It now says the check exits early while the job still reports success, and states why the distinction matters. ## Verification ``` markdownlint-cli2 (docker, canonical, **/*.md) 42 files, 0 issues editorconfig-checker (docker, canonical) clean prose_lint (charset, dupword, spelling, charset-unknown) on all four files clean python3 spec/validate.py OK, 21 cataloged python3 spec/audit.py --selftest SELFTEST PASS ``` `spec/readme-structure.md` carried no links at all, so the new pointer to `CODESTYLE.md` is its first. It is written reference-style with a definition block at the bottom, per the rule that same file states, rather than inline. Three of the four are carried files (`.github/copilot-instructions.md`, `CODESTYLE.md`, `WORKFLOW.md`), so downstream repos pick these up on their next re-vendor. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
… the carried-file corrections to main (#517) Promotes twelve commits to `main`. Three of them change **carried** files, so downstream repos read the stale text until this lands, which is what makes the promotion the delivery step rather than bookkeeping. ## What this delivers to the fleet **Carried-file corrections**, picked up by every repo on its next re-vendor: | PR | File | Correction | | --- | --- | --- | | #514 | `.github/copilot-instructions.md` | Described the pre-split `AGENTS.md`, wrong in both halves. `GOVERNANCE.md` holds the rule sections and the two `intent` ones; `AGENTS.md` carries two verbatim sections and none repo-specific | | #514 | `CODESTYLE.md` | Said MD033 flags HTML elements while the config allows `details` and `summary`; also gains the `HISTORY.md` mirror rule, moved from a hub-only spec file so a repo can read the rule it is graded against | | #514 | `WORKFLOW.md` | D2.2 "skipped on smoke" read as the job rather than the validation, and a review acting on it proposed a change that would have coupled the release to smoke | | #503 | `.editorconfig`, `.gitattributes` | 36 comment findings in the files a new repo copies first | | #501 (earlier) | `repo-config/configure.sh` | Already on `main` | **Spec and requirement changes**: - **#507** makes `OPERATIONS.md` `appliesTo: "*"`, keyed to the need rather than to `workflowModel`. Measured: 3 of 21 repos carry it, so **17 will report a new `LETTER file:` finding**. Intended, and a headed stub satisfies it. - **#512** declares `.github/workflows/merge-bot-pull-request.yml` at `interface` fidelity, closing a graded contract (`WORKFLOW.md` D8.1) that no spec required. 15 of 21 already carry it, so this ratifies a de facto standard; the other **6 report a new `DRIFT`**, and those six have Dependabot pull requests piling up with nothing to merge them. - **#505** stops the audit flagging the hub against itself and drops a premise that was false since this repo went public. - **#511** fixes the README shape across repository visibility. - **#515** puts audit-report authorship with the hub and names the base branch, after a downstream conformance PR targeted `main` and I merged it without checking. - **#513** forward-ports that PR's content, restoring the forward-only invariant. **Backlog and reports**: #504, #506, #510, #516 record the README shape rework, the branch-bootstrap step, the declared-description design, and why the audit is on demand. ## Fleet consequence, stated before it lands Two owed follow-ups this promotion creates or carries: 1. **Re-vendor `repo-config/configure.sh`**, already owed from #501, since it is `verbatim` with `appliesTo: "*"` and every repo holding a copy is byte-mismatched. 2. **The next fleet audit reads noisier**, by 17 `OPERATIONS.md` letters and 6 merge-bot drifts. Both are new requirements rather than repo regressions. ## Verification Run on `develop` at `e4c76bc`: ``` python3 scripts/test_prose_lint.py 144 tests, OK python3 scripts/test_repo_gate.py 23 tests, OK python3 scripts/test_pr_review.py 27 tests, OK python3 spec/audit.py --selftest SELFTEST PASS python3 scripts/repo_gate.py eol 0, sha-pin 0 python3 spec/validate.py OK, 21 cataloged prose_lint --check charset --check dupword --check spelling clean editorconfig-checker (docker, canonical) clean ``` Every one of the twelve was merged green with a Copilot review covering its head SHA. 🤖 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 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.
Answers finding 3 of #509, raised by the PhotoCleaner agent.
The gap
spec/readme-structure.mdstated no behavior for a private repository. shields.io cannot read one, so every GitHub-sourced badge in Build Status and Releases renders broken, and section 2 reads as unconditional. With nothing declared, each repo decided separately: PhotoCleaner carries Docker Hub shields only and planned to add the GitHub ones at the visibility flip.The decision
The structure does not vary by visibility. A private repo carries the same sections and the same shield set as a public one, written in full, and the broken badges are accepted rather than worked around.
The reasoning is that visibility is temporary by design. A repo is usually private precisely while it is being made presentable, which is exactly when its README is written. Keying the shape to visibility therefore means writing the README twice and owing work at the flip, on the one axis guaranteed to change.
Holding it constant means:
What this means for PhotoCleaner
Its README should carry the GitHub build and release shields now rather than at the flip. They will render broken until it goes public, which is the accepted cost. No urgency, and nothing else about its README changes.
Verification
Prose only. No schema, audit, or workflow change, and no fleet impact beyond removing a decision each repo was making on its own.
🤖 Generated with Claude Code