Fix the comment shape in the files every new repo copies first - #503
Merged
Conversation
`.editorconfig` and `.gitattributes` are the first files an onboarding repo carries, so until their comments follow the rules a new repo learns the shape the rules forbid. Both are `intent` fidelity, so a downstream copy is adapted rather than byte-matched and no re-vendor follows. 36 findings are gone, 22 in `.editorconfig` and 14 in `.gitattributes`. `.gitignore` was already clean, so the 44 counted in `TODO.md` was stale. Wrapped prose became one sentence per line. Two bare commands in `.gitattributes` gained a label (`Inspect with: git ls-files --eol`) rather than an exemption, since relabeling a command reads better where relabeling a URI would corrupt it. Comments opening on `git` or `uv` were restructured, not capitalized, per the tooling-casing rule. A mid-sentence semicolon and several spaced hyphens went with them, both banned in agent-authored prose and invisible here because those two rules are markdown-only. No setting or pattern changed: every non-comment line in both files is byte-identical, and `repo_gate`'s eol check still cross-validates them. `TODO.md` drops the two swept entries and records the fleet re-vendor that the `configure.sh` sweep in #501 now obliges. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR cleans up comment prose/shape in the “first-copied” repo bootstrap files so new repos don’t inherit comment-wrap / comment-case lint findings, and updates the repo TODO list to reflect completed work and the follow-up re-vendor obligation.
Changes:
- Rewrite
.editorconfigand.gitattributescomments to a one-sentence-per-line shape and restructure comments that previously started with bare tool invocations. - Label previously bare command comments (e.g.,
git config ...) so they read as prose without violating tooling-casing guidance. - Update
TODO.mdto drop the completed sweep items and add a fleet re-vendor task for the verbatimrepo-config/configure.shchange from #501.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
.editorconfig | Comment-shape and wording cleanup to eliminate prose-lint findings without changing settings. |
.gitattributes | Comment-shape and wording cleanup for EOL pin rationale without changing patterns. |
TODO.md | Removes completed sweep entries and records the configure.sh fleet re-vendor follow-up. |
Suppressed comments (2)
.editorconfig:67
- The phrase "..., being the PreToolUse hook and its installer" is ungrammatical; "namely" (or similar) reads more clearly.
# The agent-safety kit's Python is shebang-executable tooling run by path, being the PreToolUse hook and its installer.
.editorconfig:78
- "reds on every" is slang and may be unclear to readers; consider using a more explicit verb like "fails".
# Without the pin an EOL check (editorconfig-checker or CI) reds on every `uv lock` or `uv sync` until the file is manually reconverted.
Uh oh!
There was an error while loading. Please reload this page.
Copilot found three comments where the rewrite satisfied the linter at the cost of reading well, which is the failure a sweep is supposed to avoid. A fourth had the same fault and was found by re-reading the rest. - "keep it LF and a copied snippet runs, where a CRLF shebang breaks" splits into two sentences. - "being the PreToolUse hook and its installer" becomes "namely". - "reds on every `uv lock`" becomes "fails". That word was inherited rather than introduced, and rewriting the line was the moment to drop it. - "There git stays passive" becomes "For those, git stays passive". The awkward fronting existed only to dodge a lowercase opening. Also gates the class this work belongs to. GOVERNANCE puts verbatim content on the hub, because a downstream copy is byte-matched and cannot be corrected locally. Nothing enforced that, so the sweep could silently regress. `TestCarriedContent` reads the `verbatim` entries live from spec/files.json and asserts every one is comment-clean, with two guards so it cannot pass vacuously: the manifest must still declare verbatim content, and every declared file must exist. Confirmed to fail by reintroducing a wrapped comment in configure.sh. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Uh oh!
There was an error while loading. Please reload this page.
ptr727 added a commit
that referenced
this pull request
Aug 1, 2026
The `README.md` entry from `TODO.md`. It was deferred rather than dropped because two edits to that file were in flight, and both have since landed, so it is now free to take. > **Stacked on #503**, which also edits the `TODO.md` entry this PR removes. Merge #503 first and GitHub retargets this to `develop` automatically. Branching from `develop` instead would have conflicted on that line for no gain. ## Result **12 findings gone**: 6 `dash` and 6 `semicolon`, both constructions GOVERNANCE bans in agent-authored prose. ``` before: dash 6, semicolon 6 (12) after: 0 ``` Each was recast the way the rule prescribes: a spaced hyphen becomes a comma, a preposition, or a subordinate clause, and a prose semicolon becomes a comma or two sentences. **No content changed, only its construction.** ## Two worth naming **The Source Code and Versioned Releases bullets** read `- **Label**: [link] - explanation`. That is *not* the `- **Label** - explanation` separator the dash rule exempts, because the label already ends in a colon, so the dash was a genuine clause break rather than structural punctuation. Both now read `[link] for explanation`. **The Python bullet** carried both faults in a single line: ``` - Configure ruff and a type checker in `pyproject.toml` - pyright strict, or mypy in CI with pyright editor-only; whichever runs in CI is the gate. ``` It splits into two sentences, which resolves the dash and the semicolon together. ## Verification ``` prose_lint README.md (dash, semicolon, charset, charset-unknown, dupword, spelling, sentence-split) clean prose_lint TODO.md (same set) clean prose_lint . --diff HEAD clean, all default rules markdownlint-cli2 (docker, README + TODO) 0 issues cspell (docker, README + TODO) 0 issues python3 scripts/test_prose_lint.py 144 tests, OK python3 spec/validate.py OK, 21 cataloged ``` markdownlint and cspell were run because CI gates `README.md` with both, and this PR rewrites sentences rather than only comments. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 1, 2026
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 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.
The
.editorconfig/.gitattributes/.gitignoreentry fromTODO.md, taken now becauseBlogis carrying the baseline this week and these are the first files it copies.TODO.mdstates the reason itself: until they are fixed, a new repo learns the shape the rules forbid.Result
36 findings gone.
.gitignorewas already clean, so the 44 thatTODO.mdclaimed was stale, most likely because #500 removed several.editorconfigfindings on the way past..editorconfigintent.gitattributesintent.gitignoreBoth swept files are
intentfidelity, so a downstream copy is adapted rather than byte-matched. Unlike #501 this obliges no re-vendor.A recommendation I am reversing
In #501 I said a command-synopsis exemption in
prose_lint.pywas probably the better long-term answer than labeling each block. Having done this sweep, I no longer think so, and this PR labels instead.Two bare commands appear here:
The difference from the bare-URI case in #500 is that relabeling a command is easy and improves it, where relabeling a URI is impossible without corrupting the address:
The URI needed an exemption because there was no legal fix. A command has one, and it reads better. On top of that, "a comment body that is a command invocation" has no crisp form the way
^scheme://...$does, and a fuzzy exemption inside a gate silently swallows real prose. So the rule stays as it is.What was corrected, by shape
gitoruvrestructured rather than capitalized, per GOVERNANCE's tooling-casing rule. For example# uv regenerates uv.lock ...became# The uv tool regenerates uv.lock ....Fixed in passing, since these files were open
A mid-sentence semicolon in
.gitattributesand several spaced hyphens in both files. GOVERNANCE bans both in agent-authored prose, and neither was reported here because thesemicolonanddashrules are still markdown-only. Leaving them would have carried the banned construction into every repo copying these files.No setting or pattern changed
The whole point is that this is comment-only, so it is evidenced rather than asserted:
repo_gate'seolcheck still passes. That check cross-validates the two files against each other, asserting every path pinned LF in.gitattributeshas the matching.editorconfigoverride, so it would catch a mangled pattern or section header.Verification
Tree-wide warn-only backlog moves 1152 -> 1116.
TODO.md
Drops the two swept entries, and adds the fleet re-vendor of
configure.shthat #501 obliges, which was previously recorded only in the PR body. TheREADME.mdentry is reworded: it was deferred because two edits to that file were in flight, and both have since landed, so it is now free to take.🤖 Generated with Claude Code