Correct the docs that stopped describing the repository - #12
Conversation
The hub's first audit of this repo (ProjectTemplate#547) found three prose violations and, reading the docs alongside it, three claims that were true when written and are not now. A doc that describes a past state is worse than an absent one, because a reader cannot tell which half still holds. ## Claims that outlived their state - `reports/Blog/audit.md` said the release path was untested because the publisher had never been dispatched. It was dispatched on 2026-08-01 and cut release `1.0.11`, so the path is proven rather than untested. - The same file said the registry entry stays `publish: []`. The hub now carries an entry declaring the GitHub release, which is the only channel that ships today. The VPS target is still deferred, and that half is unchanged. - `TODO.md` still listed dispatching the publisher as the next task. Removed, and the State table gains the release-pipeline row, so the fact that it is proven is recorded rather than merely no longer denied. ## The current-time rule `HISTORY.md` described the 1.0 content as "having previously lived inside a hosted blogging platform". Release notes are written in current time, describing what the thing is: a reader of 1.0 never saw the platform it came from, so the delta is noise that only makes sense to whoever did the work. ## Prose Two of the three findings are fixed: a comment opening on a lowercase identifier in the merge-bot workflow, and a semicolon in `OPERATIONS.md` prose. The third is the COPYRIGHT SIGN in `layouts/rss.xml`, left alone deliberately. The character-set tiers classify it nowhere, so the linter reports `charset-unknown` rather than pass or fail, and transliterating it in a machine-read feed to satisfy a rule that does not exist yet is the wrong way round. It is raised as an escalation in the hub's audit report and is the hub's call. ## Verification markdownlint, editorconfig-checker, and the JSON gates are clean, and `prose_lint.py` over the repo excluding the imported archive now reports only the escalated `charset-unknown`. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates repository documentation to accurately reflect the current, proven release state and to remove/replace statements that described an older past state. It also makes a small workflow comment wording tweak in the merge-bot workflow.
Changes:
- Update
TODO.mdandreports/Blog/audit.mdto record that the release pipeline has been proven (release1.0.11), and adjust the “publish surface deferred” description accordingly. - Rewrite the
HISTORY.md1.0 note to describe the release in current-time terms rather than historical migration context. - Minor prose cleanup in
OPERATIONS.mdand a comment wording change in.github/workflows/merge-bot-pull-request.yml.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| TODO.md | Records release pipeline as proven and removes the now-completed “dispatch once” next step. |
| reports/Blog/audit.md | Updates audit claims to match the now-proven dispatch-only release workflow and current publish-channel reality. |
| OPERATIONS.md | Prose punctuation cleanup (semicolon → sentence). |
| HISTORY.md | Rewords 1.0 release note to be current-state focused. |
| .github/workflows/merge-bot-pull-request.yml | Rephrases concurrency rationale comment (one wording issue noted). |
Uh oh!
There was an error while loading. Please reload this page.
The reworded comment opened "The false cancel-in-progress", which reads as an adjective modifying the key name rather than as the key's value. Naming the setting and its value says the same thing without the ambiguity, and it still opens on a capital, which is what the rewording was for. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
Suppressed comments (1)
reports/Blog/audit.md:111
- The section header still says “Publish and Release: Deferred”, but the updated paragraph below now states the release workflow is proven end-to-end (manual dispatch). This reads as internally contradictory for readers skimming headings; consider updating the header to reflect that publish is deferred while release is manual/proven.
`publish-release.yml` is dispatch-only and proven end to end: release `1.0.11` on 2026-08-01 carries the tag, the source archive, the README, and the LICENSE.
The section read "Publish and Release: Deferred" over a paragraph saying the release is proven end to end, which is a heading contradicting its own body. A reader skimming headings got the opposite of the finding. They are two surfaces and only one is outstanding. The release is dispatch-only and proven by release `1.0.11`, and the hub registry declares it as such. The deploy to the VPS is the deferred half, and it is deferred because the VPS does not exist rather than because anything failed. Fixing the heading exposed two more places stating the merged claim: the verdict paragraph and the dimension table, which carried one "Publish and release: Deferred" row where there are two answers. Both now say which surface they mean, and the stale "`publish` is empty and `releaseTrigger` is `none`" line goes with them, since the registry entry landing in ProjectTemplate#547 declares the GitHub release and `dispatch-only`. Found by a suppressed low-confidence Copilot finding on the previous push, which was correct. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
commented
Aug 3, 2026
The suppressed low-confidence finding on the last review was correct, so acting on it here. The section header said "Publish and Release: Deferred" over a paragraph saying the release is proven end to end. A reader skimming headings got the opposite of the finding. Fixed in 91a3c0b by splitting the two surfaces, since only one is outstanding. The release is dispatch-only and proven by release Fixing the heading exposed two more places carrying the same merged claim, which the finding did not name: the verdict paragraph and the dimension table, which had one "Publish and release: Deferred" row where there are two answers. Both now say which surface they mean. The stale |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
Suppressed comments (1)
reports/Blog/audit.md:126
- This line uses “publish surface” even though the surrounding updates split “Release” vs “Deploy to the VPS”. Using “publish” here reads like it includes the (now-proven) GitHub release and makes the residual delta ambiguous. Consider renaming it to “VPS deploy surface” (or similar) for consistency with the table and section headings.
- No deploy exists, so the publish surface stays deferred. The hub registry declares the GitHub release, which is the only channel that currently ships, and the VPS target is revisited when a deploy has actually run.
The residual-delta bullet still called it the publish surface, from before the section split release from deploy. That reading now includes the GitHub release, which ships and is proven, so the bullet said the proven half was deferred. Found by a suppressed low-confidence Copilot finding, the second in a row on this branch that was correct. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727
commented
Aug 3, 2026
The second suppressed finding was correct too, so fixed in c7f1155. The residual-delta bullet still said "publish surface", from before this branch split release from deploy. That reading now takes in the GitHub release, which ships and is proven, so the bullet was saying the proven half was deferred. It now names the VPS deploy surface, matching the section heading and the dimension table. Swept the file for the same leftover phrasing and there are no others. |
The hub's first audit of this repo (ProjectTemplate#547) found three prose violations, and reading the docs alongside it turned up three claims that were true when written and are not now. A doc describing a past state is worse than an absent one, because a reader cannot tell which half still holds.
This is the second of two convergence PRs. #11 carries the verbatim re-vendor; this one carries everything the audit found that is ours rather than the hub's.
Claims that outlived their state
reports/Blog/audit.md: the release path is untested, the publisher never dispatched1.0.11reports/Blog/audit.md: the registry entry stayspublish: []TODO.md: dispatching the publisher is the next taskThe current-time rule
HISTORY.mddescribed the 1.0 content as "having previously lived inside a hosted blogging platform". Release notes are written in current time, describing what the thing is. A reader of 1.0 never saw the platform it came from, so the delta is noise that only makes sense to whoever did the work.Prose
Two of the three findings are fixed: a comment opening on a lowercase identifier in the merge-bot workflow, and a semicolon in
OPERATIONS.mdprose.The third is deliberately not fixed.
layouts/rss.xmlemits the COPYRIGHT SIGN, and the character-set tiers classify it nowhere, soprose_lint.pyreportscharset-unknownrather than pass or fail. Transliterating it in a machine-read feed to satisfy a rule that does not exist yet is the wrong way round, so it is raised as an escalation in the hub's audit report and left for the hub to settle.Verification
markdownlint, editorconfig-checker, and the JSON gates are clean.
prose_lint.pyover the repo excluding the imported archive now reports only that one escalatedcharset-unknown, down from three findings.🤖 Generated with Claude Code