Adopt the two prose/comment style rules (#357 item 2) - #361
Merged
Conversation
Both proposals from a downstream agent, adopted where the owner placed them. Comments gains: no class-, type-, or file-header summary comment blocks. A summary restates the declaration below it and goes stale as the file grows, which is the file-scope form of the design narrative and verbosity creep the section already bans. A licence or provenance header a tool or policy requires is not a summary and is unaffected. Character Set gains: no semicolon joining two independent clauses in agent-authored prose, recast as a comma or two sentences. Written to the proposal's actual scope - "as sentence separators" - so a semicolon separating items in a list that already contains commas keeps its standard use, and a code statement terminator is untouched. On existing prose: the hub carries 248 doc lines with prose semicolons, so a sweep would be a sprawling rewrite of dense governance text with real risk of changing meaning. The rule says existing prose is corrected as each file is next edited rather than swept, matching how the fleet already handles propagation debt. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repo’s governance guidance in AGENTS.md to adopt item 2 from #357 (two prose/comment house-style rules) in the selected sections.
Changes:
- Add an explicit prohibition on class/type/file header “summary comment blocks”, with a carve-out for required license/provenance headers.
- Add a prose-style rule banning semicolons used to join independent clauses in agent-authored prose (while preserving legitimate uses).
The repo mandates US English (cspell language en-US); the carve-out I added used the British spelling. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Adopts item 2 of #357, in the sections the owner chose. Item 1 is #360.
Comments: no header summary blocks
Placed in
AGENTS.md"Comments", which already bans design narrative, rule citations, and verbosity creep - a header summary is the same failure at file scope: it restates the declaration below it and goes stale as the file grows.One carve-out added: a licence or provenance header that a tool or policy requires is not a summary, so it is unaffected. That was the only real objection to a blanket ban.
Character Set: no clause-joining semicolons
Placed beside the ASCII/em-dash rules, as the same class of house-style constraint on agent prose habits.
Written to the proposal's actual scope. It says "as sentence separators", which is narrower than all semicolons, so the rule bans the clause-joining use and explicitly preserves two legitimate ones: a semicolon separating items in a list that already contains commas, and a statement terminator in code.
On sweeping existing prose
I measured before writing the rule, because a rule the hub immediately violates is the trap this repo hit with
set -Eeuo(#338/#350):Not all are clause-joining - many are list separators the rule preserves - but a full sweep would still be a sprawling rewrite of dense governance prose with real risk of changing meaning in text that is load-bearing.
So the rule states that existing prose is corrected as each file is next edited, not swept. That matches how the fleet already handles propagation debt, and it is honest about the hub's current state rather than pretending compliance.
Flagging plainly: this changes my own output style going forward, and the 248 lines are a known, deliberate residue rather than an oversight.
spec/validate.py, markdownlint, editorconfig-checker: clean. CRLF preserved.🤖 Generated with Claude Code