Record the README shape rework against the PlexCleaner template - #510
Merged
Conversation
The maintainer wants the hand-crafted PlexCleaner README as the canonical shape, and wants the result auditable rather than advisory. Four divergences measured against PlexCleaner README.md, this repo's README.md, and spec/readme-structure.md. The distribution bullet is labeled by deliverable, so PlexCleaner ships executables and says Binary Releases where the spec fixes Versioned Releases for everything, which makes the label a per-channel table rather than one string. The license shield sits in the top Build Status block here and at the very bottom of PlexCleaner, inside a closing License section immediately before the link definitions. The Release Notes closing sentence differs, and PlexCleaner's is the wanted one, though it writes that link inline where the reference-style rule forbids it, so the wording is adopted and the form is not. And the channel bullets and shields vary per deliverable across GitHub binaries, Docker Hub, NuGet and PyPI, which is what the readme-structure dimension needs encoded to check a repo against its own declared types. The section order is recorded as a separate open question, because it affects every repo and the audit rather than only this repo's file. PlexCleaner places Questions or Issues right after the Table of Contents where the spec orders it ninth, and it carries sections the spec names nowhere. Under the recurrence rule those unnamed ones are correctly repo-specific and stay undeclared, so only the position of the already-named sections is open. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Ready to approve
The change is limited to backlog documentation with consistent reference-style links and no detected correctness or policy issues.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Pull request overview
Updates the repository backlog to record a measured “README shape rework” comparison against the PlexCleaner template, capturing specific divergences and an open question about canonical section ordering.
Changes:
- Adds two new TODO backlog items documenting four concrete README-structure divergences vs PlexCleaner and the need for per-deliverable channel labeling/shields.
- Records an explicit open question on whether canonical README section order should follow PlexCleaner’s placement of “Questions or Issues”.
- Adds new reference-style link definitions for the newly referenced spec documents.
File summaries
| File | Description |
|---|---|
| TODO.md | Records the README-shape rework findings and related follow-up decisions as actionable backlog items, with supporting reference links. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
README.md opened the block as `**Version: 2.0**:`, with the colon both inside the bold and after it, so it renders as a double colon. Its own sibling line `**Summary**:` puts the colon outside. Found by Copilot on ptr727/Blog#3, the first pull request of the first repo to copy the shape, and reported by the Blog agent on #456. The Release Notes block is one a new repo copies by shape, so every adopter inherited a finding on its first review. Same reasoning as the dotfile comment sweep: the files a new repo copies first teach it the shape, so a defect there propagates by construction. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟡 Not ready to approve
The PR description says the change is “Backlog only,” but the PR also includes a README modification that should be reflected in scope/description (or split out).
Once you've addressed the issues Copilot identified, you can request another Copilot review.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
Suppressed comments (1)
README.md:23
- PR description says this change is "Backlog only", but this PR also modifies README release-notes formatting. Either update the PR description to mention the README adjustment, or move this README tweak into a separate PR so the stated scope matches the actual changes.
**Version**: 2.0
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
spec/audit.py extracts the intro line after the README H1 and compares the GitHub About panel and the Docker Hub short description against it, so the canonical value lives inside prose and anything that wants it has to parse markdown. PhotoCleaner#32 measured that cost. A publish-time step reading the intro needs nine guards, against headings, block quotes, four list markers, ordered lists, HTML, tables, code, links and the length cap, and each one exits non-zero inside the release job, so a restructured README fails the release over a tagline. Declaring the value makes the README intro a third mirror rather than the source. The audit then compares all three against one declared string, the Docker workflow pushes a literal with no parser, and configure.sh can set the GitHub About panel from the same field it already uses for every other setting. Recorded rather than built: the field is mechanical, but populating it needs a per-repo decision wherever the current intro exceeds the 100-character cap. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🟢 Ready to approve
The changes are limited to documentation/backlog content and a small README formatting tweak, with no behavioral or spec changes introduced.
This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 0 new
- Review effort level: Lite
We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.
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.
Records the README shape rework Pieter asked for, measured rather than described. Backlog only, no spec change here.
What was compared
ptr727/PlexCleanerREADME.md(hand-crafted, the wanted shape), this repo'sREADME.md, andspec/readme-structure.md.Four concrete divergences
**Binary Releases**, pre-compiled executables**Versioned Releases**, fixed for every repo## Licensesection right before the link definitions### Build Statusblock1 and 4 are the same underlying point. The label depends on what ships. PlexCleaner ships executables so the channel is Binary Releases, while this repo ships source archives so Versioned Releases is right here. That makes the label a per-channel table rather than one canonical string, which is also what the
readme-structureaudit dimension needs in order to check a repo against its own declared types (GitHub binaries, Docker Hub, NuGet, PyPI each with a distinct bullet label and shield set).3 carries a caveat. PlexCleaner writes it as an inline link:
The reference-style rule in
GOVERNANCE.mdforbids inline targets outside the four agent-instruction files. So the entry says to adopt the wording and keep the reference form, rather than copying the line whole.The section order is recorded as a separate question
Deliberately not folded into the item above, because it affects every repo and the audit rather than one file's contents.
PlexCleaner places
## Questions or Issuesimmediately after the Table of Contents, where the spec orders it ninth. It also carries sections the spec names nowhere: Performance Considerations, Runtime Metrics, Custom Plugins, Testing, Development Tooling, Feature Ideas, Sample Media Files.Under the recurrence rule landed in #507, those unnamed sections are correctly repo-specific and stay undeclared, so they are not evidence that the spec's list is short. The open question is only the position of the sections the spec already names, and that is Pieter's call rather than something to infer from one repo.
Verification
The spelling gate caught
labelledin the first draft of this entry and it was corrected tolabeled. Worth noting because it is the gate doing its job on the same commit that documents gates.🤖 Generated with Claude Code