Sweep the carried configure.sh comments to one sentence per line - #501
Merged
Conversation
`repo-config/configure.sh` is carried `verbatim` with `appliesTo: "*"`, so every repo copies it byte-matched and cannot correct it locally. GOVERNANCE assigns that class to the hub, swept whole rather than waiting for a next edit downstream can never make. It carried 54 comment-wrap and comment-case findings. All 54 are gone. Three shapes were corrected. Wrapped prose became one sentence per line. A comment opening on a lowercase API or JSON key was restructured rather than capitalized, per the tooling-casing rule. The usage synopsis gained an Apply/Check label so it no longer reads as a lowercase sentence. The `ruleset_id` header moved above the function, since a trailing comment carrying two sentences cannot be split in place. No executable code changed: every non-comment line is byte-identical except that one moved header, all three `shellcheck disable=SC2016` directives still sit directly above their targets, shellcheck passes, and the file parses. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR performs a comments-only prose-lint sweep of repo-config/configure.sh, restructuring comment blocks to consistently use one sentence per line (and avoiding lowercase-leading “sentences” that trigger comment-case) while preserving script behavior.
Changes:
- Reformats the header synopsis into labeled
Apply:/Check:lines to avoid lowercase-leading comment findings. - Rewrites wrapped comment prose into one-sentence-per-line form throughout the script.
- Moves the
ruleset_idtrailing comment above the function and removes the inline trailing fragment (ruleset_id() { # ...→ruleset_id() {), without changing logic.
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
Promotes the three prose-gate fixes to `main`, so a repo carrying the baseline from `main` gets the corrected gates and the corrected `configure.sh` rather than the versions that reject correct work. This is the unblocking step for the `Blog` onboarding in #456: `Blog` carries from `main`, and today's `main` hands it two false-positive gates and 54 unfixable findings. | PR | Squash | What | | --- | --- | --- | | #499 | `d68b2ca` | `dupword` reads the comments outside markdown, not the raw source line (#489 finding 3) | | #500 | `c3ad6db` | A URI-only comment is a reference, not a sentence (#489 finding 4) | | #501 | `67aaa6c` | The `verbatim`-carried `repo-config/configure.sh` swept to one sentence per line (#489 finding 6) | ## What this changes for a repo carrying from `main` - `class="gallery gallery-cols-1"` and any other repeated token outside a comment stops being a **blocking** CI failure. That was the reported case with no legal fix in the HTML. - A comment whose whole body is a URI stops producing a `comment-case` finding no edit can answer. Every config file opening with a reference block inherited one. - `repo-config/configure.sh` arrives clean. It is `verbatim` with `appliesTo: "*"`, so a downstream copy is byte-matched and could never have been fixed locally. ## Consequence, stated plainly `configure.sh` is `verbatim`, so **every repo already carrying it now differs from `main` until re-vendored**. A fleet re-vendor pass is owed after this merges. A repo onboarding after this point carries the corrected file from the start. ## Verification Run on `develop` at `67aaa6c`, which is what this promotes: ``` python3 scripts/test_prose_lint.py 141 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 prose_lint --check charset --check dupword --check spelling clean ``` Warn-only backlog moved 526 -> 516 on the comment rules from #500, and `configure.sh` went 54 -> 0 from #501. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
ptr727
added a commit
that referenced
this pull request
Aug 1, 2026
The `.editorconfig` / `.gitattributes` / `.gitignore` entry from `TODO.md`, taken now because `Blog` is carrying the baseline this week and these are the first files it copies. `TODO.md` states the reason itself: until they are fixed, a new repo learns the shape the rules forbid. ## Result **36 findings gone.** `.gitignore` was already clean, so the 44 that `TODO.md` claimed was stale, most likely because #500 removed several `.editorconfig` findings on the way past. | File | Before | After | Fidelity | | --- | --- | --- | --- | | `.editorconfig` | 22 | 0 | `intent` | | `.gitattributes` | 14 | 0 | `intent` | | `.gitignore` | 0 | 0 | repo-owned | Both swept files are `intent` fidelity, 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.py` was 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: ``` # git config --global core.autocrlf false # git ls-files --eol ``` 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: ``` # Configure with: git config --global core.autocrlf false # Inspect with: git ls-files --eol ``` 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 - **Wrapped prose** rewritten one sentence per line, which is the bulk of the 36. - **Comments opening on `git` or `uv`** restructured rather than capitalized, per GOVERNANCE's tooling-casing rule. For example `# uv regenerates uv.lock ...` became `# The uv tool regenerates uv.lock ...`. - **Bare commands** labeled, as above. ## Fixed in passing, since these files were open A mid-sentence semicolon in `.gitattributes` and several spaced hyphens in both files. GOVERNANCE bans both in agent-authored prose, and neither was reported here because the `semicolon` and `dash` rules 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: - **Every non-comment line in both files is byte-identical**, checked by diffing the files with comment lines stripped. - **`repo_gate`'s `eol` check still passes.** That check cross-validates the two files against each other, asserting every path pinned LF in `.gitattributes` has the matching `.editorconfig` override, so it would catch a mangled pattern or section header. ## Verification ``` prose_lint .editorconfig .gitattributes --check comment-wrap --check comment-case clean prose_lint . --check charset --check dupword --check spelling clean prose_lint . --diff HEAD clean, all default rules python3 scripts/repo_gate.py eol 0, sha-pin 0 python3 scripts/test_prose_lint.py 141 tests, OK python3 spec/validate.py OK, 21 cataloged ``` Tree-wide warn-only backlog moves **1152 -> 1116**. ## TODO.md Drops the two swept entries, and adds the **fleet re-vendor of `configure.sh`** that #501 obliges, which was previously recorded only in the PR body. The `README.md` entry 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](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 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.
The
repo-config/configure.shsweep listed inTODO.md, and finding 6 of #489.Why the hub sweeps this one
configure.shisverbatimfidelity withappliesTo: "*", so every repo in the fleet carries it byte-matched and cannot correct it locally. GOVERNANCE already names this case:Blog is onboarding now, so fixing it here means Blog carries the corrected file from the start rather than inheriting 54 findings it has no way to answer.
Result
54 findings, all gone. Verified under
develop's current rule, not a modified one.What was actually wrong, by shape
I classified the 54 before touching anything, because a sweep driven by a bad work list damages a correct document:
apply:,check:,has_discussions:,per_page=100,pull_request:,required_status_checks:,vulnerability-alerts:, plus theassert/jq_has/gh_okhelper docs)repo-config/configure.sh apply ...)Apply:/Check:label so the line no longer reads as a lowercase sentenceThe
ruleset_iddoc comment moved from a trailing position to above the function, because a trailing comment carrying two sentences cannot be split where it sits.No behavior change
This is a comments-only change to an operational script that writes GitHub rulesets, so that claim is evidenced rather than asserted:
ruleset_id() { # ...becomingruleset_id() {.shellcheck disable=SC2016directives survive and still sit directly above the lines they suppress (93, 199, 223). A directive that drifted off its target would silently stop suppressing.koalaman/shellcheck:latest, exit 0).bash -nparses.[*.sh]requires.One thing worth a follow-up
The two synopsis findings were fixable here with a label, but the underlying shape is general: a comment whose body is a command invocation is not prose, the same way a bare URI is not (#500). Every repo that documents a script's usage in a comment block will hit this. A synopsis exemption in
prose_lint.pyis probably the better long-term answer than labeling each block, and I did not add one here because #500 is already changing that file.Downstream consequence, stated plainly
configure.shis verbatim, so every repo carrying it now differs from the hub until re-vendored. That is the documented cost of a verbatim sweep, not a surprise, but it does mean a fleet re-vendor pass is owed after this merges.🤖 Generated with Claude Code