Skip to content

Sweep the semicolon prose class out of the carried docs - #478

Merged
ptr727 merged 1 commit into
developfrom
feature/semicolon-sweep-carried-docs
Jul 31, 2026
Merged

Sweep the semicolon prose class out of the carried docs#478
ptr727 merged 1 commit into
developfrom
feature/semicolon-sweep-carried-docs

Conversation

@ptr727

@ptr727 ptr727 commented Jul 31, 2026

Copy link
Copy Markdown
Owner

The semicolon sweep only ever cleared GOVERNANCE.md. The other six carried files still ran the class, and they vendor downstream on the same no-downstream-trigger argument the dash sweep (#476) ran on.

The exemption came first

Sweeping the corpus straight away would have restructured the lists the exemption exists to protect, the same trap LABEL_DASH caught in #476. The rule keeps "a semicolon separating items in a list that already contains commas", but the check read the comma positionally (',' in prose[:m.start()]), so an enumeration whose commas fall in a later item had its openers flagged and its tail exempted, splitting one series in two. Three corrections, each with a test:

  • The comma qualifies the list as a whole, not one separator's position.
  • A markdown table row is judged one cell at a time. A row is a record of fields, and a comma in one column cannot excuse a semicolon in another.
  • A bullet's **Label**: is dropped before the line is read, because it opens the bullet rather than announcing a list, the same construct the label dash is already exempted for.

Net on the carried corpus: 64 findings -> 60. Five lines went exempt (the D2/D4 guarantee lists and the S1 trace row, all genuine comma-carrying series), and two were newly caught.

The sweep

44 genuine clause joins recast as a comma or two sentences: CODESTYLE.md 24, .github/copilot-instructions.md 13, WORKFLOW.md 12, AUDIT.md 10, repo-config/README.md 1.

The 5A guarantees and the 5B trace table keep their semicolons, which is the standard series punctuation the rule already allows. Where a 5B cell carries no commas of its own (S2-S6, S10) it takes commas, so the table now punctuates each cell by what that cell contains.

Two splices that the relaxed exemption no longer flags (CODESTYLE.md "Spelling", WORKFLOW.md D4.1) are fixed by hand anyway, since I read them while sweeping.

Where this stops

All six files report zero, the bar GOVERNANCE.md already meets. The paren-internal asides they still carry ((default; strict baseline)-shaped) are the same construction GOVERNANCE.md kept through its own sweep, so holding the other files to a stricter bar than the rules file itself would be incoherent. The known limit is documented in scripts/README.md: a colon early in a long line still excuses a splice later on it.

Verification

prose_lint 130 cases and the full 180-case suite pass, repo_gate.py, spec/validate.py, spec/audit.py --selftest, the blocking prose run (charset, dupword, spelling) clean tree-wide, markdownlint 0 issues over 39 files, editorconfig-checker clean. cspell's gated scope (README + HISTORY) is clean, and the tree-wide 38-issue backlog is byte-identical to develop.

No downstream trigger, and this adds to the existing re-vendor debt rather than creating a new class of it.

🤖 Generated with Claude Code

The semicolon sweep only ever cleared GOVERNANCE.md. The other six carried
files still ran the class, and they vendor downstream on the same
no-trigger argument the dash sweep ran on.

Two parts, because sweeping the corpus first meant restructuring lists the
exemption exists to protect. The rule keeps a semicolon separating items in
a list that already carries commas, but the check read the comma
positionally, so an enumeration whose commas fall in a later item had its
openers flagged and its tail exempted, splitting one series in two. The
comma now qualifies the list as a whole. A table row is judged one cell at
a time, since a row is a record of fields and a comma in one column cannot
excuse a semicolon in another, and a bullet's `**Label**:` is dropped
before the line is read, because it opens the bullet rather than announcing
a list, the same construct the label dash is already exempted for.

That leaves 44 genuine clause joins, now recast as a comma or two
sentences: CODESTYLE.md 24, .github/copilot-instructions.md 13, AUDIT.md
10, WORKFLOW.md 12, repo-config/README.md 1. The 5A guarantees and the 5B
trace table keep their semicolons, which is the standard series
punctuation the rule already allows.

All six files now report zero, the bar GOVERNANCE.md already meets. The
paren-internal asides those files still carry are the same construction
GOVERNANCE.md kept through its own sweep, so they stay.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 31, 2026 18:03

Copilot AI 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 expands the “semicolon” prose sweep beyond GOVERNANCE.md by (1) updating the prose-lint rule’s exemption logic to match the documented intent more precisely (list-level comma detection, table-cell scoping, and bullet-label handling) and (2) applying the resulting sweep across the remaining carried documentation files so they reach zero findings consistently.

Changes:

  • Refines semicolon detection/exemptions in scripts/prose_lint.py (list-level comma qualification, per-table-cell evaluation, and stripping - **Label**: bullet openers before analysis).
  • Adds targeted regression tests covering the corrected semicolon exemption behaviors.
  • Rewrites remaining carried-doc semicolon splices into comma/two-sentence forms while preserving allowed list-series semicolons.

Reviewed changes

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

Show a summary per file
File Description
WORKFLOW.md Recasts semicolon splices while preserving the workflow model and guarantee text intent.
scripts/test_prose_lint.py Adds regression tests for list-level commas, per-table-cell checks, and bullet-label colon handling.
scripts/README.md Documents the refined semicolon-rule interpretation and its known heuristic limit.
scripts/prose_lint.py Implements span-based semicolon evaluation (table cells + label-colon stripping) and list-level comma exemption.
repo-config/README.md Removes semicolon splice from carried prose without changing described ruleset behavior.
CODESTYLE.md Sweeps semicolon splices throughout carried style guidance while keeping requirements intact.
AUDIT.md Removes semicolon splices in carried audit procedure prose without changing audit semantics.
.github/copilot-instructions.md Sweeps semicolon splices in carried Copilot/runbook instructions while preserving operational guidance.

@ptr727
ptr727 merged commit 8771e62 into develop Jul 31, 2026
7 checks passed
@ptr727
ptr727 deleted the feature/semicolon-sweep-carried-docs branch July 31, 2026 19:22
ptr727 added a commit that referenced this pull request Jul 31, 2026
…479)

Forward promotion of four commits. `main` carries no content beyond the
merge-base (`f7c77d8`, #473), so this is a clean forward merge with no
conflicts.

## What promotes

- **#475 - Gate US English spelling where cspell does not reach.** The
cspell gate reads README and HISTORY only, so a British spelling
anywhere else in the tree had nothing checking it. The `spelling` rule
generates its banned words from stems rather than listing them one by
one, since an inflected spelling is as wrong as its base and a
hand-listed family drifts.
- **#476 - Sweep the spaced-hyphen prose class out of the carried
docs.** All seven carried documents to zero: `GOVERNANCE.md` 219,
`CODESTYLE.md` 53, `WORKFLOW.md` 51, `.github/copilot-instructions.md`
40, `AUDIT.md` 29, `repo-config/README.md` 20, `AGENTS.md` 3. The
remaining ~538 are hub-only (`reports/`, `docs/`, `spec/*.md`,
`STANDUP.md`, `catalog/`), stay warn-only, and are corrected as each
file is next edited, which works because nothing vendors them.
- **#477 - Report the suppressed findings the thread poll cannot see.**
The merge gate counts a review body's collapsed low-confidence block as
an outstanding finding, but the digest read `reviewThreads` alone, where
that block never appears, so the one command written to answer "is this
PR clean" reported clean while findings stood.
- **#478 - Sweep the semicolon prose class out of the carried docs.**
The exemption is fixed first (list-wide comma, per-table-cell scoping,
bullet-label colon), then 44 genuine clause joins recast across five
files. All six remaining carried files reach zero, the bar
`GOVERNANCE.md` already met.

## Verification on the merged `develop`

Both prose classes report zero across all seven carried documents. The
full 180-case script suite, `scripts/repo_gate.py`, `spec/validate.py`,
and `spec/audit.py --selftest` pass. The blocking prose run (charset,
dupword, spelling) is clean tree-wide, markdownlint reports 0 issues
over 39 files, and editorconfig-checker is clean. cspell's gated scope
(README + HISTORY) is clean; the tree-wide backlog is unchanged.

## Release

A human merge never auto-publishes, so this fires no release, as
designed. The latest release stays `2.0.108`.

## Re-vendor debt

This promotion changes prose in all seven carried documents, so every
downstream repo goes further out of date against canonical. That debt is
pre-existing and still untracked - no issue covers it and filing one has
not been authorized. `spec/audit.py --branch <ref>` checks a repo's
convergence before it promotes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
ptr727 added a commit that referenced this pull request Aug 1, 2026
Forward promotion of five commits. `main` carries no content beyond the
merge-base (`8771e62`, #478), so this is a clean forward merge with no
conflicts.

**This one has a consumer waiting.** The Blog standup (#456) is
mid-correction and has been told to carry its instruction set from
`main`, because `main` is the audit ground truth. Every fix for the
failure it just hit is currently on `develop` only: `main`'s
`STANDUP.md` still begins at "1. Classify and Catalog", with no step 0
and no step 1A, and `main` does not yet require `OPERATIONS.md`. Until
this promotes, a repo following the corrected instructions re-runs the
uncorrected procedure.

## What promotes

- **#480 - Name where repo-specific content goes.** `STANDUP.md` step 2
named no destination for content that is not a carried file. The three
destinations existed only in `spec/section-model.md`, which nothing on
the scaffolding path pointed at.
- **#481 - Verify commit identity before the first commit, and require
`OPERATIONS.md`.** Step 0 verifies identity and signing before `git
init`, framed **verify, never set**, because the host carries the
identity globally and a repo-local override shadows it silently.
`OPERATIONS.md` becomes required for an `operational` repo,
presence-checked like `README.md`.
- **#482 - State what a host must provide.** The tooling contract,
naming no installer so it stays true on every platform, plus a route to
the write-safety kit which the host-setup document never referenced.
- **#484 - Prefix the PowerShell invocation, and name the interpreter
per platform.** Both corrections came from real Windows and WSL2 testing
in #483 and disproved something #482 asserted.
- **#485 - Require the instruction set before any authoring.** Step 1A,
the direct fix for the Blog failure.

## Verification on the merged `develop`

The full 180-case `scripts/` suite, `scripts/repo_gate.py`,
`spec/validate.py` and `spec/audit.py --selftest` all pass. The blocking
prose run (charset, dupword, spelling) is clean tree-wide, markdownlint
reports 0 issues over 39 files, and editorconfig-checker is clean.

## Release

A human merge never auto-publishes, so this fires no release, as
designed. The latest release stays `2.0.108`.

## Re-vendor debt

#481 changed `GOVERNANCE.md` "Git and Commit Rules", a `verbatim`
section, so this promotion re-vendors it across the fleet. That was
accepted deliberately when the change was made. The debt is pre-existing
and still untracked, and `spec/audit.py --branch <ref>` checks a repo's
convergence before it promotes.

## Known backlog, not in this promotion

The hub's own `.editorconfig`, `.gitattributes` and `.gitignore` carry
44 comment-shape findings, which downstream repos inherit by copying
them and reading them for house style. #485 works around it by telling
agents to trust the rule text over a carried file's formatting. Cleaning
those three files is owed and deliberately separate.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to 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