Settle Markdown capitalization and fix two TODO prose defects - #566
Merged
Conversation
Answers the live half of #565, the six suppressed Copilot findings the digest defect in #562 hid, which reached no thread and so were never answered anywhere. ## The two prose defects Both are in `TODO.md` and were raised on #546 round 4. The downstream-surface entry joined two independent clauses with a comma, now two sentences. The reading-a-local-clone entry read "answers instead what that clone last saw", missing its connector, now "answers a different question, which is what that clone last saw". ## The capitalization convention The reviewer asked for the proper noun on one bullet of #561. That bullet is now internally consistent, so the live question was the file-wide mix rather than the line: `GOVERNANCE.md` alone carried 17 lowercase against 7 capitalized, and the same mix is vendored fleet-wide, so settling it per file settles it nowhere. `CODESTYLE.md` "Markdown and Spelling" gains item 5. Prose capitalizes the format's name; lowercase is for the strings a machine reads, meaning a tool or package name, a settings key, a heading anchor, an identifier, and a file extension. It lands in that file because every repo carries it, so the convention arrives with the file rather than being re-decided per repo. The sweep then corrected 40 prose occurrences across 18 files, in documents, code comments, docstrings, and two audit output strings. No identifier changed, and the tree now carries one spelling of the format's name. ## For the reviewer The sweep touched four `verbatim` regions, so every downstream repo is byte-mismatched until re-vendored: three `GOVERNANCE.md` sections by one word each, plus two comment lines in `.markdownlint-cli2.jsonc`, which is verbatim and whole. `CODESTYLE.md` is `intent`, so its new item reaches the fleet as a rule to adopt. `TODO.md`'s re-vendor entry records all of it and now names five files rather than three. The three findings #565 lists as already resolved were re-verified against the tree and need no change here. ## Verification prose_lint's gating rules (charset, dupword, spelling) clean tree-wide; the 157 prose_lint tests, test_repo_gate, test_pr_review, and `audit.py --selftest` all pass; repo_gate clean on eol and sha-pin; `spec/validate.py` clean; markdownlint-cli2 0 issues in 44 files; cspell clean; editorconfig-checker clean. Every changed file kept its own line endings. The `--diff` run reports five warn-only findings (four comment-wrap, one dash) on the three lines this diff touched in `spec/audit.py`, `spec/validate.py`, and `spec/fidelity-model.md`. All predate this change and belong to the #519 backlog: those files carry 101 and 8 respectively, and correcting one line of each would leave the file no more conformant while burying a one-word sweep. Related: #565 Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR standardizes prose casing of the word "Markdown" across the repository and fixes two prose defects in TODO.md, aligning documentation, comments, and user-facing strings with a single convention captured in CODESTYLE.md.
Changes:
- Fix two prose defects in
TODO.md(comma splice; missing connector) and update an entry describing re-vendor scope. - Add a
CODESTYLE.mdrule establishing"Markdown"as the proper-noun casing in prose, then apply a sweep across docs/comments/strings. - Update several spec/docs/test strings to match the new casing and keep audit/selftest outputs consistent.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| TODO.md | Fixes two prose defects and updates the carried-content sweep entry to reflect the broader re-vendor scope. |
| STANDUP.md | Updates prose casing to match the new "Markdown" convention. |
| spec/validate.py | Updates validation error text/comment casing for consistency. |
| spec/section-model.md | Updates prose casing to match the new "Markdown" convention. |
| spec/readme-structure.md | Updates prose casing in the README spec model to "Markdown". |
| spec/fidelity-model.md | Updates prose casing in the fidelity model to "Markdown". |
| spec/audit.py | Updates docstrings, comments, and output strings to "Markdown" casing. |
| scripts/test_prose_lint.py | Updates test docstrings/comments to match the "Markdown" convention. |
| scripts/test_pr_review.py | Updates test docstrings/comments to match the "Markdown" convention. |
| scripts/README.md | Updates prose casing in docs describing prose_lint, with one remaining mixed-case instance noted. |
| scripts/prose_lint.py | Updates comments to "Markdown" casing. |
| scripts/pr_review.py | Updates comments/docstrings to "Markdown" casing. |
| OPERATIONS.md | Updates prose casing in tooling docs to "Markdown". |
| GOVERNANCE.md | Updates policy text casing to "Markdown" for consistency. |
| CODESTYLE.md | Adds the new "Markdown" proper-noun rule and applies casing updates within the section. |
| AUDIT.md | Updates audit procedure prose casing to "Markdown". |
| .markdownlint-cli2.jsonc | Updates explanatory comments to "Markdown" casing. |
| .github/copilot-instructions.md | Updates prose casing to "Markdown" to match the new convention. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Both findings from the first review round are the same defect in the sweep rather than two: its pattern treated a following `-` or `.` as the mark of an identifier, so a hyphenated prose compound and a sentence-final use were read as code and left lowercase. `markdown-only` in `scripts/README.md` and `scripts/prose_lint.py`, and "uses the markdown." in `CODESTYLE.md` item 1, are the two the reviewer named. Re-scanning the tree for the same shape found three more the reviewer did not reach: `spec/audit.py`, `spec/fidelity_honesty.py`, and one assert string in `spec/project-types.json`. Item 5 now states the boundary, that a hyphenated compound in prose capitalizes, and says why, since the hyphen is exactly what a mechanical sweep misreads. Gates re-run clean: prose_lint gating rules, the script self-tests, `audit.py --selftest`, `repo_gate.py`, `spec/validate.py`, and markdownlint-cli2. Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
This was referenced Aug 5, 2026
Closed
ptr727 added a commit
that referenced
this pull request
Aug 6, 2026
…574) Promotes the nine commits `develop` has carried since the previous promotion (#555) to `main`. Merge commit only, no squash, and `develop` is not deleted. ## What lands - **#560** Standardize the static-site-deploy repo type and its destination, including the deploy-verification guarantee and a retention rule that records which side owns the prune. - **#561** Ask for a blocked decision instead of reporting it, and scope the clickable-link rule to a surface that renders markdown. - **#564** Read a suppressed section nested inside the review-details wrapper, so `scripts/pr_review.py` stops reporting a clean round over findings that reach no thread. - **#566** Settle Markdown capitalization in `CODESTYLE.md`, and fix the two `TODO.md` prose defects the digest defect had hidden. - **#568** Check a `driftNote` on every run rather than only on an otherwise clean audit, and state what the audit does not evaluate. - **#569** Name who trips the production ref gate, and state that a harness refusal is a different thing from the maintainer's permission and is not lifted by it. - **#571** Re-audit `ptr727/Blog` against the hugo type and bump the conformance matrix. - **#573** Scope the semicolon exemption to the sentence its list lives in, with the 44 newly reported occurrences recorded on #519 rather than swept here. - **#572** Exempt a verbatim section from the coordination-reference scan. ## Issues closed Fixes#562. Closes#565. The closing keywords sit on this promotion rather than on the feature pull requests, because GitHub fires them only on a merge into the default branch. #456, #558, #563, #567, and #570 are already closed against their merged fixes. ## Verification `git merge-tree` reports no conflict between `origin/main` and `origin/develop`, so this promotion needs no throwaway resolution branch. Every constituent pull request merged green with its review loop closed.
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.
Answers the live half of #565, the six suppressed Copilot findings the digest defect fixed in #562 hid. A suppressed finding reaches no thread, so the digest was the only place it could have surfaced, and it reported
suppressed=0for five rounds across two pull requests.The two prose defects
Both are in
TODO.md, both raised on #546 round 4, both still present ondevelop.does not fail loudly, it quietly audits itselfanswers instead what that clone last sawanswers a different question, which is what that clone last sawThe capitalization convention
The reviewer asked for the proper noun on one bullet of #561, and that bullet is now internally consistent in lowercase. So the live question is not the line but the file-wide mix:
GOVERNANCE.mdalone carried 17 lowercase against 7 capitalized, and the same mix is vendored fleet-wide, which is why settling it per file settles it nowhere.CODESTYLE.md"Markdown and Spelling" gains item 5. Prose capitalizes the format's name. Lowercase is for the strings a machine reads and nothing else: a tool or package name (markdownlint,yzhang.markdown-all-in-one), a settings key (markdown.extension.toc.levels), a heading anchor (#markdown-and-spelling), an identifier in code, and a file extension. What it settles is the mix rather than either spelling, since a file carrying both gives the next author no default and a reviewer a finding to raise on whichever one it wrote last. It lands inCODESTYLE.mdbecause every repo carries that file, so the convention arrives with it rather than being re-decided per repo.The sweep corrected 40 occurrences across 18 files in documents, code comments, docstrings, and two
spec/audit.pyoutput strings. No identifier changed: the pattern skips a word adjacent to.,-,_,[,#, or a paren, soheading_texts(markdown)andmarkdown.splitlines()were left alone, and the result was read line by line before applying.For the reviewer
Four
verbatimregions changed, so every downstream repo is byte-mismatched until re-vendored:GOVERNANCE.mdsections by one word each, "Documentation Style Conventions", "Communicating with the User", and "Repository Details"..markdownlint-cli2.jsonc, which isverbatimandwhole, so a config nothing else changed about now reports as drifted.CODESTYLE.mdisintent, so its new item reaches the fleet as a rule each repo adopts in its own copy rather than as bytes to match.TODO.md's re-vendor entry records all of this and now names five files rather than three, so the next sweep does not have to rediscover it from a diff that reads cosmetic.The three findings #565 records as already resolved were re-verified against the tree and need no change here.
Verification
prose_lint.pygating rules (charset, dupword, spelling)test_prose_lint.py,test_repo_gate.py,test_pr_review.pyspec/audit.py --selftestscripts/repo_gate.pyspec/validate.pyEvery changed file kept its own line endings, which was checked after a first attempt flattened CRLF to LF and was reverted before anything was committed.
prose_lint.py --diffreports five warn-only findings (fourcomment-wrap, onedash) on the three lines this diff touched inspec/audit.py,spec/validate.py, andspec/fidelity-model.md. All five predate this change and belong to the #519 backlog, where those files carry 101 and 8 violations respectively. Correcting the one line of each that this diff touches would leave the file no more conformant while burying a one-word sweep in rewrapped comments.Not in this PR
prose_lintrule for the convention. The legitimate lowercase uses are the whole difficulty, so a checker is a design question rather than a follow-through, and stating the rule is what Answer the six suppressed findings the digest never surfaced #565 asked for.TODO.md's entry and needs the maintainer to name the repos.Related: #565