Skip to content

Fix the comment shape in the files every new repo copies first - #503

Merged
ptr727 merged 2 commits into
developfrom
feature/dotfile-comment-shape
Aug 1, 2026
Merged

Fix the comment shape in the files every new repo copies first#503
ptr727 merged 2 commits into
developfrom
feature/dotfile-comment-shape

Conversation

@ptr727

Copy link
Copy Markdown
Owner

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.

FileBeforeAfterFidelity
.editorconfig220intent
.gitattributes140intent
.gitignore00repo-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

`.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>
CopilotAI review requested due to automatic review settings August 1, 2026 14:14

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 .editorconfig and .gitattributes comments 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.md to drop the completed sweep items and add a fleet re-vendor task for the verbatim repo-config/configure.sh change from #501.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

FileDescription
.editorconfigComment-shape and wording cleanup to eliminate prose-lint findings without changing settings.
.gitattributesComment-shape and wording cleanup for EOL pin rationale without changing patterns.
TODO.mdRemoves 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.

Comment thread.editorconfig Outdated
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>
CopilotAI review requested due to automatic review settings August 1, 2026 14:17

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

@ptr727
ptr727 merged commit 3fe605d into developAug 1, 2026
7 checks passed
@ptr727
ptr727 deleted the feature/dotfile-comment-shape branch August 1, 2026 14:50
@ptr727
ptr727 restored the feature/dotfile-comment-shape branch August 1, 2026 14:52
@ptr727
ptr727 deleted the feature/dotfile-comment-shape branch August 1, 2026 14:52
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>
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)
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

@ptr727