Say what the developer carve-out exempts, and what it does not - #463
Merged
Conversation
Two adjacent bullets disagreed on the emoji case. One said developer-typed Unicode stays regardless of tier and is never stripped, the next said an unrecognized non-ASCII character is reported rather than allowed. A reader could not tell which governed an un-tiered emoji, and the gate reports it as `charset-unknown` while the first bullet reads as an exemption from being reported at all. The carve-out is about what an agent may rewrite, not about what the gate reports. Saying so leaves both bullets true: the character stays, and it is still surfaced until someone classifies it. The tool README restated the same claim, so it takes the same clause. The spaced hyphen in the edited bullet is recast, under the standing rule that existing prose is corrected as each file is next edited. Reported by Copilot in the low-confidence block of its review of #460. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Clarifies the “developer-typed Unicode” carve-out in the Documentation Style Conventions so it’s explicit that the carve-out limits what agents may rewrite, while the charset gate still reports un-tiered characters as charset-unknown until they’re classified. This aligns the prose with the existing charset-unknown behavior and removes the apparent contradiction between adjacent bullets.
Changes:
- Updates
GOVERNANCE.mdto explicitly distinguish rewrite permissions from what the gate reports, and to state that un-tiered developer-typed Unicode still producescharset-unknownfindings until classified. - Updates
scripts/README.mdto include the same clarification for the prose lint documentation.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
GOVERNANCE.md |
Clarifies the developer-typed Unicode carve-out scope (rewrite vs reporting) to eliminate ambiguity in “Documentation Style Conventions.” |
scripts/README.md |
Mirrors the clarification so the prose-lint documentation matches the intended/implemented charset-unknown reporting behavior. |
ptr727
added a commit
that referenced
this pull request
Jul 31, 2026
Promotes `d4c4085` (#459), `adaa068` (#461), `e52c68a` (#463), `7bf8a12` (#464), `269629a` (#465), and `036e468` (#467). Conflict-free, six commits ahead. ## What lands The charset rule gets three tiers instead of a flat non-ASCII ban, which could not express context - an audit report classified U+2264 and U+2265 as the scientific carve-out while the rule named both must-replace. Tier 1 never survives ASCII, tier 2 is an operator kept beside a number and replaced between words, tier 3 is a unit symbol whose ASCII form would be a lie. A character in no tier is reported rather than passed, and the rule is clean tree-wide, so it gates. Two prose rules invert from detecting a subset to banning the construction. The pronoun-keyed splice pattern found 170 of 493 and missed every imperative one; the em-dash rule now says restructure the sentence, and the spaced hyphen is banned in its own right. Comments get a gate covering every syntax the fleet types carry - `//`, `/* */`, `<!-- -->`, `<# #>`, `;`, `#` - with JSON read as JSONC because that is what ships. That recovered four files the old discovery never saw, including the VS Code task and devcontainer snippets downstream repos copy; their 37 malformed comments are fixed here. The Verification Discipline mechanisms land too: a gate has to be watched failing, and a check is scoped by what the project declares rather than by the file that prompted it. ## The comment-extractor fix (#461) Copilot's review of this promotion found a defect in the extractor #459 adds, so it was fixed at the source and this PR now carries it. Block openers were searched before line markers against a ceiling of the whole line, so a `/*` inside a `//` comment opened a real block: the line's own comment was truncated at the opener, the closer carried into the lines below, and the code there was handed to the comment rules as prose. PowerShell failed identically with `<#` inside a `#` comment. Those are the two fleet syntaxes carrying both marker kinds. Tree-wide counts are unchanged - dash 963, comment-wrap 454, semicolon 388, comment-case 56 - because nothing in this repository nests the markers that way. The exposure is downstream, in the C# and PowerShell repositories the extractor is aimed at, and it would surface the moment the comment rules gate rather than warn. That is the argument for fixing before promotion rather than after. ## The carve-out contradiction (#463) Copilot's second round found the same review's own subject matter contradicting itself. Two adjacent bullets disagreed on whether a developer-typed but un-tiered character is exempt from the gate or reported by it. The implementation already reported it as `charset-unknown` while the doc read as an exemption. The carve-out now states that it governs what an agent may rewrite rather than what the gate reports, which leaves both bullets true and changes neither rule. Worth blocking a promotion for, because `main` is what the audit reads as ground truth, and this contradiction had already produced a real misreading - the audit report that classified U+2264 and U+2265 as the scientific carve-out, which is what motivated tiering the rule in #459 to begin with. ## The scanner rewrite (#464) The third round found a fourth defect in the same function, so the structure went rather than the instance. The extractor searched each marker kind from column 0 against a ceiling, and a ceiling can only describe the first comment on a line. That one shape produced every extractor defect in this promotion: a marker quoted inside the first comment read as real, a doc marker excluded from the ceiling unbounded it, and anything after the first comment was unreachable. A single left-to-right pass replaces it. Several blocks on one line, a comment trailing the line where a block closes, and a multi-line documentation block that no longer leaks its prose into the scan all come with it. #462 is fixed there too rather than deferred, since a defect left in the promoted diff keeps being found and the loop cannot reach a clean round while it stands. C# verbatim strings read correctly in both directions and in all three spellings, and C# took its own syntax entry so the rest of the C-like family does not inherit a form it lacks. ## Multi-line strings (#465) The fourth round found that masking runs per line while a C# verbatim string spans them, so a marker on any later line of one was reported as a comment. A false positive, and the direction that is worse than a miss, since it asks a reader to edit text that is data. Reviewing that fix found two more in the same area: a quote in comment text opened a phantom string that blanked the markers after it, within a line and then across lines, and a line-skip meant as an optimization dropped a string that closed and reopened around real code. Masking now runs from the scan position and only code advances the string state. #466 records what is still not carried. C# is the only syntax whose strings are tracked across lines, and the README says so rather than leaving a reader to find out. ## The continuation asterisk (#467) The fifth round found the extractor damaging the prose it then judged. A leading `*` was taken off every block comment body, which is the `/* */` convention for continuing a line and ordinary text everywhere else, so `<!-- *emphasis* leads here -->` became `emphasis* leads here` and `comment-case` reported the lowercase opening it had just created. Worse than a plain false positive, since the prose reported is not what the file holds. Stripping is now one `*` against whitespace, on a line continuing a `/* */` block. This defect dates to `d4c4085` rather than to any fix made during this review, so the promotion is where it would first reach `main`. ## Why promote now The snippets fixed here are the ones a new or realigning repo copies, and the reviewer-facing rules - the merge gate and the runbook now require investigating the low-confidence block - only bind downstream once `main` carries them. That requirement earned itself twice more on #461. Round one's single inline comment read as a wording nit and was a live defect; round two had no inline comments at all and both findings sat in the suppressed block, one of them the reopened bug. A loop polling `reviewThreads` would have reported a clean pass on both rounds. ## Fidelity note `GOVERNANCE.md` and `.github/copilot-instructions.md` sections declared verbatim changed, so downstream copies are **stale** until re-vendored. `spec/fidelity_honesty.py` separates stale from modified by hash, so the audit reports it correctly. Warn-only backlog, reported but not gating: dash 963, comment-wrap 454, semicolon 388, comment-case 56. 🤖 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.
Copilot's finding on promotion PR #460, fixed at the source. That PR's head is
develop, so it picks this up when this squashes in.The contradiction
Two adjacent bullets in "Documentation Style Conventions" disagreed on the emoji case:
An emoji is both developer-typed and un-tiered, so the two bullets pointed opposite ways. The implementation already had a coherent answer:
It is preserved in place and never rewritten, and it is still reported until classified. The doc simply never said the second half, so the first bullet read as an exemption from the gate rather than from rewriting.
The fix
The carve-out is about what an agent may rewrite, not about what the gate reports. Saying that leaves both bullets true and needs no change to either rule.
scripts/README.mdrestated the same claim in one sentence, so it takes the same clause.The spaced hyphen in the edited bullet is recast at the same time, under the rule three bullets below it that existing prose is corrected as each file is next edited rather than swept.
Why it blocks a promotion
This is fleet law on its way to
main, andmainis what the audit reads as ground truth. Shipping a self-contradicting rule is what leaves downstream repositories arguing the point, and the contradiction already produced one real misreading: the audit report that classified U+2264 and U+2265 as the scientific carve-out, which is what motivated tiering the rule in #459 to begin with.No behavior change, so no test accompanies it. 62 self-tests and 19 repo_gate tests pass,
repo_gateis clean, andcharsetplusdupwordexit 0.🤖 Generated with Claude Code